PHP マニュアル

2024-08-17
PHP マニュアル翻訳プロジェクト
© 1997-2024 the PHP Documentation Group
  • 著作権
  • 序文
  • はじめに
    • 入門
    • 簡易チュートリアル
  • インストールと設定
    • インストールにあたっての一般的な注意事項
    • Unix システムへのインストール
    • macOS へのインストール
    • Windows システムへのインストール
    • クラウドコンピューティングプラットフォームへのインストール
    • FastCGI Process Manager (FPM)
    • PECL 拡張モジュールのインストール
    • 問題が起きた場合
    • 実行時設定
  • 言語リファレンス
    • 基本的な構文
    • 型
    • 変数
    • 定数
    • 式
    • 演算子
    • 制御構造
    • 関数
    • クラスとオブジェクト
    • 名前空間
    • 列挙型(Enum)
    • エラー
    • 例外(exceptions)
    • ファイバー
    • ジェネレータ
    • アトリビュート
    • リファレンスの説明
    • 定義済みの変数
    • 定義済みの例外
    • 定義済みのインターフェイスとクラス
    • 定義済みのアトリビュート
    • コンテキストオプションとパラメータ
    • サポートするプロトコル/ラッパー
  • セキュリティ
    • はじめに
    • 一般的な考慮事項
    • CGI バイナリとしてインストール
    • Apache モジュールとしてインストール
    • セッションのセキュリティ
    • ファイルシステムのセキュリティ
    • データベースのセキュリティ
    • エラーのレポート
    • ユーザーが投稿したデータ
    • PHPの隠蔽
    • 最新版を維持する
  • 機能
    • PHP による HTTP 認証
    • クッキー(Cookies)
    • セッション
    • ファイルアップロードの処理
    • リモートファイルの使用
    • 接続処理
    • 持続的データベース接続
    • コマンドラインの使用法 — PHP をコマンドラインから使用する
    • ガベージコレクション
    • DTrace 動的トレーシング
  • 関数リファレンス
    • PHP の振る舞いの変更
    • 音声フォーマットの操作
    • 認証サービス
    • コマンドライン関連
    • 圧縮およびアーカイブ
    • 暗号
    • データベース関連
    • 日付および時刻関連
    • ファイルシステム
    • 自然言語および文字エンコーディング
    • 画像処理および作成
    • メール関連
    • 数学
    • テキスト以外の MIME 型
    • プロセス制御
    • その他の基本モジュール
    • その他のサービス
    • 検索エンジン用の拡張モジュール
    • サーバー固有のモジュール
    • セッション関連
    • テキスト処理
    • 変数・データ型関連
    • ウェブサービス
    • Windows 用のモジュール
    • XML 操作
    • GUI用の拡張モジュール
  • FAQ — FAQ: よくある質問
    • 一般的な情報
    • メーリングリスト
    • PHP を手に入れるには
    • データベースに関する問題
    • インストール
    • 構築時の問題
    • PHP の使いかた
    • パスワードのハッシュ — 安全なパスワードハッシュ
    • PHP と HTML
    • PHP と COM
    • その他の質問
  • 付録
    • PHP の歴史と関連するプロジェクト
    • PHP 8.2.x から PHP 8.3.x への移行
    • PHP 8.1.x から PHP 8.2.x への移行
    • PHP 8.0.x から PHP 8.1.x への移行
    • PHP 7.4.x から PHP 8.0.x への移行
    • PHP 7.3.x から PHP 7.4.x への移行
    • PHP 7.2.x から PHP 7.3.x への移行
    • PHP 7.1.x から PHP 7.2.x への移行
    • PHP 7.0.x から PHP 7.1.x への移行
    • PHP 5.6.x から PHP 7.0.x への移行
    • PHP 5.5.x から PHP 5.6.x への移行
    • PHP のデバッグ
    • Configure オプション
    • php.ini ディレクティブ
    • 拡張モジュールの一覧/分類
    • 関数エイリアスのリスト
    • 予約語の一覧
    • リソース型の一覧
    • 利用できるフィルタのリスト
    • サポートされるソケットトランスポートのリスト
    • PHP 型の比較表
    • パーサトークンの一覧
    • ユーザーレベルでの命名の手引き
    • マニュアルについて
    • Creative Commons Attribution 3.0
    • 索引
    • 変更履歴
  • HTML ヘルプ版
    • このヘルプについて
    • CHM版 の PHPマニュアル を使う
    • 全文検索
    • Integrating the PHP Manual


著作権

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

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

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

著者と貢献者

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

著者と編集者

以下の方々は本マニュアルに ついてコンテンツを提供したことで大きな貢献をしています。 Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Nilgun Belma Buguner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Antony Dovgal, 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 Junior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Georg Richter, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar そして Andrei Zmievski.

以下の方々は本マニュアルについて多くの編集作業を行ったことで大きな貢献を しています。 Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson そして 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, Takashi Iwamoto, Yasuo Ohgaki, Yoshinari Takaoka, Yu Watanabe, Yuji Uchiyama, Yusuke Hata.


はじめに

  • 入門
    • PHP とはなんでしょう?
    • PHPにできることは?
  • 簡易チュートリアル
    • 必要なものは?
    • PHP を使用する初めてのページ
    • 実用的な例
    • フォームの処理
    • 次にするべきことは?


  • ≪ はじめに
  • PHP とはなんでしょう? ≫
  • PHP Manual
  • はじめに
  • 入門

入門

目次

  • PHP とはなんでしょう?
  • PHPにできることは?


PHP とはなんでしょう?

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

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

例1 初歩的な例

<!DOCTYPE html>
<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スクリプトが使用される場所は主に2つあります。

  • サーバーサイドでのスクリプティング。これは最も古くからあり PHPの中心となる分野です。ここでPHPを動作させるには 3つのものが必要です。PHPパーサ(CGIもしくはサーバーモジュール)、 ウェブサーバー、そしてブラウザです。ウェブサーバーは インストールされたPHPと連結して起動されなければなりません。 ブラウザでウェブサーバーにアクセスし、PHPページを閲覧することで PHPプログラムの出力を得ることが出来ます。インストール手順の章に詳しい 情報があります。
  • コマンドラインでのスクリプティング。PHPスクリプトは サーバーもブラウザも無しで動作させるようにすることも出来ます。 この場合、PHPパーサだけが必要となります。このタイプは cron(Windowsではタスクスケジューラ)を使用して一定間隔で スクリプトを実行したい場合や、ちょっとした文書処理を 行うのに最適な方法です。 コマンドラインでPHPを使うの章に詳しい情報があります。

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

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

PHP は HTML を出力するだけではありません。PHP はリッチなファイルタイプ、 たとえば 画像やPDFファイルを出力する機能を備えていますし、 データを暗号化したり、メールを送信することもできます。 また、JSON や 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 の基礎の基礎について簡単なチュートリアルで説明したいと思います。 PHP は Web ページを作成する機能だけを有しているわけではありませんが、 ここでは PHP で動的な Web ページを作成することのみを扱います。詳細は、 PHP でできること と題するセクションを参照ください。

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


必要なものは?

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

ここでは、貴重なネットワーク帯域を節約するために、 ローカルに開発を行うことにしましょう。この場合、 » 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

<!DOCTYPE html>
<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 によりパースされ、以下の出力がブラウザに送信されます。

<!DOCTYPE html>
<html>
    <head>
        <title>PHP Test</title>
    </head>
    <body>
        <p>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 はスクリプトを読み込んで実行できません。

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

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

<?php phpinfo(); ?>


実用的な例

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

注意:

$_SERVER は、 Web サーバー関連情報を全て保持する PHP の特別な予約変数です。詳細は、 スーパーグローバル を参照ください。

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

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

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

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

Mozilla/5.0 (Linux) Firefox/112.0

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

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

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

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

<?php
if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
echo 'あなたはFirefoxを使用しています';
}
?>

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

あなたはFirefoxを使用しています

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

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

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

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

<?php
if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
?>
<h3>str_contains() がtrueを返しました</h3>
<center>あなたはFirefoxを使用しています</center>
<?php
} else {
?>
<h3>str_contains()がfalseを返しました</h3>
<center>あなたはFirefoxを使用していません</center>
<?php
}
?>

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

<h3>str_contains() がtrueを返しました</h3>
<center>あなたはFirefoxを使用しています</center>

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


フォームの処理

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

例1 簡単な HTML フォーム

<form action="action.php" method="post">
    <label for="name">名前:</label>
    <input name="name" id="name" type="text">

    <label for="age">年齢:</label>
    <input name="age" id="age" type="number">

    <button type="submit">Submit</button>
</form>

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

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

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

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

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

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


次にするべきことは?

ここで得た知識により、マニュアルのほとんどの部分、 そしてサンプルのアーカイブにある多くのスクリプトの例を理解できるようになったはずです。

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


インストールと設定

  • インストールにあたっての一般的な注意事項
  • Unix システムへのインストール
    • Apache 2.x (Unixシステム用)
    • Nginx 1.4.x (Unix システム用)
    • Lighttpd 1.4 (Unix システム用)
    • LiteSpeed/OpenLiteSpeed Webサーバー(Unixシステム用)
    • CGI およびコマンドライン
    • OpenBSD へのインストール
    • Solaris へのインストール
    • Debian GNU/Linux へのインストール
  • macOS へのインストール
    • パッケージの使用
    • macOS Monterey より前のバージョンにバンドルされている、PHP の使用法
    • macOS 上での PHP のコンパイル
  • Windows システムへのインストール
    • インストール要件
    • PECL
    • Windows 上での PHP インストーラ
    • Windows でのおすすめの構成
    • Windows 上での PHP の手動インストール
    • ソースからのビルド
    • Microsoft Windows のコマンドラインでの PHP
    • Apache 2.x （Microsoft Windows 用）
    • Windows 上での PHP のトラブルシューティング
  • クラウドコンピューティングプラットフォームへのインストール
    • Azure App Services
    • Amazon EC2
    • DigitalOcean
  • FastCGI Process Manager (FPM)
    • インストール
    • 設定
  • PECL 拡張モジュールのインストール
    • PECL インストール入門
    • PECL 拡張モジュールをダウンロードする
    • PHP 拡張モジュールの Windows へのインストール
    • 共有 PECL 拡張モジュールを、pecl コマンドを用いてコンパイルする
    • phpize で共有 PECL 拡張モジュールをコンパイルする方法
    • php-config
    • PECL 拡張モジュールを PHP に静的に組み込む
  • 問題が起きた場合
    • FAQ を読む
    • FAQ に無い問題
    • バグ報告
  • 実行時設定
    • 設定ファイル
    • .user.ini ファイル
    • どこで設定を行うのか
    • 設定を変更するには


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

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

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

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

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

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

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

PHP のソースコードと Windows 用のバイナリアーカイブは、 » https://www.php.net/ にあります。


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

目次

  • Apache 2.x (Unixシステム用)
  • Nginx 1.4.x (Unix システム用)
  • Lighttpd 1.4 (Unix システム用)
  • LiteSpeed/OpenLiteSpeed Webサーバー(Unixシステム用)
  • CGI およびコマンドライン
  • OpenBSD へのインストール
  • Solaris へのインストール
  • Debian GNU/Linux へのインストール

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

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

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

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

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

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

  • autoconf:
    • PHP 7.3 以降: 2.68+
    • PHP 7.2: 2.64+
    • PHP 7.1 以前: 2.59+
  • automake: 1.4+
  • libtool: 1.4.x+ (ただし 1.4.2 は除く)
  • re2c:
    • PHP 8.3 以降: 1.0.3+
    • PHP 8.2 以前: 0.13.4+
  • bison:
    • PHP 7.4 以降: 3.0.0+
    • PHP 7.3 以前: 2.4+ (Bison 3.x を含む)

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

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

注意:

Unixシステム (OpenBSD や SELinux のような) によっては、 セキュリティ上の理由で、 メモリ上のページに書き込み可能属性と実行可能属性の両方を付与することを 許可しないかもしれません。 これは PaX MPROTECT とか W^X (Write XOR Execute) 防御と呼ばれています。 しかしながら、この手のメモリマッピングは PCRE の JIT サポートに必要なので、 PHP を PCRE の JIT サポート抜きでビルドする か、 何とかしてシステムが提供するホワイトリストに PHP のバイナリを入れなければならないでしょう。

注意: Android ツール群を使った ARM 向けのクロスコンパイルには、今のところ対応していません。


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.4 と 2.2 の二種類があります。 どちらを選ぶにしてもそれなりの理由があるでしょうが、 2.4 が現在の最新版です。もし選択の余地があるのなら 2.4 を使うことを推奨します。しかし、この例では 2.4 と 2.2 のどちらでも使えるようにしています。 Apache httpd 2.2 は正式には廃止予定で、新しい開発やパッチが 発行されないことに注意してください。

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

    tar -xzf httpd-2.x.NN.tar.gz

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

    tar -xzf php-NN.tar.gz

  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-pdo-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 により既にこの設定は 追加されている場合もありますが、確認が必要です。

    PHP 8:

    LoadModule php_module modules/libphp.so

    PHP 7:

    LoadModule php7_module modules/libphp7.so

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

    <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 モジュールでビルドすることです。


Nginx 1.4.x (Unix システム用)

このドキュメントは、Nginx 1.4.x HTTPサーバー 向けに PHP を PHP-FPM とともにインストールし、設定する方法を示します。

このガイドは、あなたが Nginx をソースコードからビルドしたことを想定しています。 よって、すべてのバイナリと設定は /usr/local/nginx にあると想定しています。 仮にこれに当てはまらず、Nginx を他の手段で取得した場合は、 » Nginx Wiki を参照し、 このマニュアルをあなたのセットアップに読み替えてください。

このガイドは、Nginx サーバーが PHP アプリケーションを実行できるように設定し、 それを port 80 で公開するための基本的な設定を示します。 あなたのセットアップを最適化したい場合、Nginx と PHP-FPM のドキュメント を調べることを推奨します。セットアップの最適化は、このガイドの範囲外です。

このドキュメント全体を通して、バージョン番号は ドキュメント全体が将来でも正しく保たれるようにするため、 'x' で置き換えられている点に注意してください。 'x' については、必要に応じて対応するバージョン番号に置き換えるようにしてください。

  1. あなたのシステム向けに Nginx を取得し、インストールするために、 Nginx Wiki の » install を参照することを推奨します。

  2. PHP のソースコードを取得し、展開します。

    tar zxf php-x.x.x

  3. PHP を configure し、ビルドします。 ここで PHP を様々なオプションを使ってカスタマイズできます。 たとえば、どの拡張モジュールを有効にするか、のようなものです。 利用できるオプションの一覧については、 ./configure --help を 参照ください。 私達の例では、PHP-FPM を MySQLi のサポートを有効にして シンプルに configure することにします。

    cd ../php-x.x.x
./configure --enable-fpm --with-mysqli
make
sudo make install

  4. 設定ファイルを取得し、正しい場所に移動します。

    cp php.ini-development /usr/local/php/php.ini
cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf
cp sapi/fpm/php-fpm /usr/local/bin

  5. ファイルが存在しなかったときは、Nginx が PHP-FPM バックエンドに、 リクエストを渡さないようにし、任意のスクリプトの挿入を防げるようにすることが重要です。

    php.ini ファイルで、 cgi.fix_pathinfo ディレクティブを 0 に設定することで、 この設定を行うことができます。

    php.ini をエディタで読み込みます:

    vim /usr/local/php/php.ini

    cgi.fix_pathinfo= の行を探し、以下のように修正します:

    cgi.fix_pathinfo=0

  6. サービスを開始する前に、php-fpm が www-data ユーザーと www-data グループで 必ず実行されるように、php-fpm.conf も修正しなければいけません:

    vim /usr/local/etc/php-fpm.d/www.conf

    以下の部分を探し、修正します:

    ; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = www-data
group = www-data

    ここまで来れば、php-fpm サービスを開始できます:

    /usr/local/bin/php-fpm

    このガイドでは php-fpm をこれ以上設定しませんが、 php-fpm のさらなる設定に興味がある場合、ドキュメントを参照ください。

  7. Nginx が PHP アプリケーションの実行をサポートするように設定しなければなりません。

    vim /usr/local/nginx/conf/nginx.conf

    Nginx が、.php ファイルをサービスすることを認識させるため、 デフォルトの location ブロックを修正します:

    location / {
    root   html;
    index  index.php index.html index.htm;
}

    次のステップは、 .php ファイルへのリクエストが PHP-FPM バックエンドに渡されるようにすることです。 コメントアウトされているデフォルトの PHP location ブロックを 以下のように修正します:

    location ~* \.php$ {
    fastcgi_index   index.php;
    fastcgi_pass    127.0.0.1:9000;
    include         fastcgi_params;
    fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
    fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
}

    Nginx を再起動します。

    sudo /usr/local/nginx/sbin/nginx -s stop
sudo /usr/local/nginx/sbin/nginx

  8. テスト用のファイルを作成します。

    rm /usr/local/nginx/html/index.html
echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php

    http://localhost にアクセスすれば、 phpinfo() が表示されるはずです。

上のステップに従うことで、 FPM SAPI モジュールとして PHP をサポートした Nginx Web サーバーを実行できるでしょう。 もちろん、さらに沢山の設定オプションが Nginx と PHP では利用可能です。 さらに多くの情報を得るには、対応するソースツリーで、 ./configure --help とタイプしてみてください。


Lighttpd 1.4 (Unix システム用)

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

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

PHP と Lighttpd を組み合わせる際におすすめの SAPI は FastCGI です。 FastCGI は、php-cgi では自動的に有効になります。

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 ))
)


LiteSpeed/OpenLiteSpeed Webサーバー(Unixシステム用)

LiteSpeed PHP は、LiteSpeed SAPI を通じて LiteSpeed プロダクトと動作させるための 最適化された PHP ビルドです。 LSPHP は、自分自身がプロセスとして動き、スタンドアロンなバイナリを持ちます。 よって、PHP スクリプトをコマンドラインから実行するための シンプルなコマンドラインバイナリとして使うことができます。

LSAPI は LiteSpeed と サードパーティーの Webエンジンの間で通信できる 高度に最適化された API です。 そのプロトコルは FCGI に似ていますが、それよりもっと効率的です。

このドキュメントは、 LiteSpeed/OpenLiteSpeed Webサーバーのために、PHP を LSAPI とともに インストールし、設定する方法を示します。

このガイドは、LSWS または OLS が それぞれのデフォルトの path とフラグを使ってインストールされていると想定しています。 それぞれの Webサーバーのデフォルトのインストールディレクトリは /usr/local/lsws であり、 bin サブディレクトリから実行できます。

このドキュメント全体を通して、バージョン番号は ドキュメント全体が将来でも正しく保たれるようにするため、 'x' で置き換えられている点に注意してください。 'x' については、必要に応じて対応するバージョン番号に置き換えるようにしてください。

  1. LiteSpeed/OpenLiteSpeed Web サーバーを取得し、インストールするには、 LiteSpeed Web サーバーの ドキュメント » install page または OpenLiteSpeed のドキュメント » install page. を参照ください。

  2. PHP のソースコードを取得し、展開します:

    mkdir /home/php
cd /home/php
wget http://us1.php.net/get/php-x.x.x.tar.gz/from/this/mirror
tar -zxvf php-x.x.x.tar.gz
cd php-x.x.x

  3. PHP を configure し、ビルドします。 ここで PHP を様々なオプションを使ってカスタマイズできます。 たとえば、どの拡張モジュールを有効にするか、のようなものです。 利用できるオプションの一覧については、 ./configure --help を 参照ください。 私達の例では、LiteSpeed Webサーバーで推奨されているデフォルトの設定オプションを使うことにします:

    ./configure ... '--with-litespeed'
make
sudo make install

  4. LSPHP のインストールをチェックします。

    PHP のインストールが成功したかをチェックする一番簡単な方法は、次のコードを実行することです:

    cd /usr/local/lsws/fcgi-bin/
./lsphp5 -v

    このコードは、新しい PHP ビルドについての情報を返すはずです:

    PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
Copyright (c) 1997-2014 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

    litespeed が括弧で囲まれていることに注意してください。これは、PHP が LSAPI サポートを有効にしてビルドされていることを意味しています。

上のステップに従えば、 LiteSpeed / OpenLiteSpeed Webサーバーが SAPI 拡張としての PHP サポートを有効にした状態で実行できるようになっているはずです。 LSWS / OLS と PHP で利用可能な設定オプションはもっとたくさんあります。 さらに詳しい情報は、 LiteSpeed ドキュメント の » PHP のページを参照ください。

LSPHP をコマンドラインから使う:

LSPHP(LSAPI + PHP) コマンドラインモードは、 必ずしも Web サーバーが実行されていないリモートサーバー上で PHPスクリプトを実行するために使います。 (別にある)ローカルの Webサーバーのそばで、 PHPスクリプトを実行するために使われます。 PHP の実行がリモートサーバーにオフロードされるので、 このセットアップはサービスのスケールさせる目的にも合っています。

リモートサーバー上でのコマンドラインから lsphp を起動します: LSPHP は実行可能であり、-b socket_address オプションを使えば、 IPv4/IPv6/Unixドメインソケットアドレスに bindした状態で手動で起動できます。

例:

LSPHP を 全 IPv4, IPv6 アドレスのポート3000にbindさせる:

/path/to/lsphp -b [::]:3000

LSPHP を 全 IPv4 アドレスのポート3000にbindさせる:

/path/to/lsphp -b *:3000

LSPHP を 192.168.0.2:3000 にbindさせる:

/path/to/lsphp -b 192.168.0.2:3000

LSPHP に、Unixドメインソケット /tmp/lsphp_manual.sock でリクエストを受けさせる:

/path/to/lsphp -b /tmp/lsphp_manual.sock

LSPHP を実行する前に、環境変数を追加できます:

PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

LiteSpeed PHP は、 LiteSpeed/OpenLiteSpeed Web サーバー、 および Apache の mod_lsapi とともに使えます。 サーバーサイドの設定のさらなるステップについては、 ドキュメントの » LiteSpeed Web Server および » OpenLiteSpeed を参照ください。

LSPHP は、複数の他の方法でもインストールできます

CentOS: CentOS では、LSPHP は LiteSpeed リポジトリ または Remi リポジトリ から、 » RPM を使ってインストールできます。

Debian: Debian では、LSPHP は LiteSpeed リポジトを経由で、 » apt を使ってインストールできます。

cPanel: CPanel と EashApache 4 を使って、LSWS/OLS と CPanel とともに LSPHP をインストールする方法については、 それぞれの » documentation page を参照ください。

Plesk: Plesk は、CentOS, CloudLinux, Debian, および Ubuntu 上の LSPHP ともに利用できます。 これに関するさらなる情報は、 それぞれの » documentation page を参照ください。


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 。 その他の環境変数は、「ベンダー拡張」として取り扱うべきです。


OpenBSD へのインストール

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

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

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

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

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

# pkg_add php
# pkg_add php-apache
# pkg_add php-mysqli
  (install the PEAR libraries)
# pkg_add pear

Follow the instructions shown with each package!

  (to remove packages)
# pkg_delete php
# pkg_delete php-apache
# pkg_delete php-mysqli
# pkg_delete pear

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

Ports の使用

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

一般的な問題点

  • Apache や Nginx は OpenBSD のデフォルトサーバーではなくなりましたが、ports や packages で簡単に導入できます。新しいデフォルトサーバーの名前は 'httpd' です。
  • httpd は、デフォルトインストールでは、 » 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 の» gd 拡張モジュールのパッケージは Xorg のインストールが必要です。ベースインストール時に xbase.tgz を追加していない場合、 post-installation (» OpenBSD FAQ#4 を参照ください) で追加できます。


Solaris へのインストール

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

必要なソフトウエア

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

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

  • tar
  • gzip あるいは
  • bzip2

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

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

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

  • 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 や aptitude といったコマンドの使い方です。 このマニュアルページでの説明は、これらふたつのコマンドのどちらを使っても実行できます。

APT の使用

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

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

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

# apt install php-common libapache2-mod-php php-cli

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

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

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

よりよい設定の管理

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

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

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

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

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

# apt install php-mysql php-curl

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

よく起きる問題

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


macOS へのインストール

目次

  • パッケージの使用
  • macOS Monterey より前のバージョンにバンドルされている、PHP の使用法
  • macOS 上での PHP のコンパイル

本章では、PHP を macOS にインストールする際の注意事項とコツを説明します。 PHP は Mac OS X バージョン 10.0.0 以降、 macOS Monterey (12.0.0) より前の MacOS に標準添付されています。 また、コンパイルの手順は Unix へのインストールガイド と同じです。


パッケージの使用

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

macOS で一番手っ取り早いインストール方法は、 以下のようにして、homebrew を使うやり方です。

  1. » brew.sh にある手順に従って、homebrew をインストールします。

  2. brew install php

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

  • MacPorts: » http://www.macports.org/
  • Liip: » http://php-osx.liip.ch/ (PHP 5.3 - PHP 7.3; 現在は推奨されていません)
  • Fink: » http://www.finkproject.org/


macOS Monterey より前のバージョンにバンドルされている、PHP の使用法

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

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

標準的なインストール方法は mod_php を使用するものです。macOS 上の 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>

    注意:

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

  4. DirectoryIndex でデフォルトインデックスファイルが読み込まれるようにします。 これも httpd.conf で設定します。典型的なパターンは index.php および index.html でしょう。デフォルトでは index.php が有効になります。上で見たような設定がすでにあるからです。 これを適切に調整しましょう。
  5. php.ini の場所を設定するか、デフォルトを使用します。 macOS におけるデフォルトの場所は /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 を実行するか、あるいは macOS 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() をコールしても、この情報を取得できます。


  • ≪ macOS Monterey より前のバージョンにバンドルされている、PHP の使用法
  • Windows システムへのインストール ≫
  • PHP Manual
  • macOS へのインストール
  • macOS 上での PHP のコンパイル

macOS 上での PHP のコンパイル

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


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

目次

  • インストール要件
  • PECL
  • Windows 上での PHP インストーラ
  • Windows でのおすすめの構成
  • Windows 上での PHP の手動インストール
  • ソースからのビルド
  • Microsoft Windows のコマンドラインでの PHP
  • Apache 2.x （Microsoft Windows 用）
  • Windows 上での PHP のトラブルシューティング

最近の Microsoft Windows システムへのインストール方法と、一般的なウェブサーバー用の推奨構成を説明します。

Windows 版の PHP の公式リリースは、実運用環境でも使えるものです。しかし、PHP をソースからビルドすることもできます。 そのためには Visual Studio の環境が必要です。詳細は » Step Build Instructions を参照ください。

  • Windows コマンドラインでの PHP の使用法

  • Azure App Services (aka Microsoft Azure, Windows Azure, (Windows) Azure Web Apps) 上での PHP のインストール


インストール要件

PHP を動かすには、少なくとも Windows 2008/Vista が必要です。 32ビットまたは64ビット(別名 X86 または X64。PHP は、Windows RT/WOA/ARM では動作しません) の環境が必要です。 PHP 7.2.0 以降では、 Windows 2008/Vista での動作はサポートしていません。 PHP 8.3.0 以降では、Windows 2008 R2 と Windows 7 での動作はサポートされていません。

PHP には、Visual C ランタイム (CRT) が必要です。これを必要とするアプリケーションは多いので、おそらく既にインストールされているでしょう。

Microsoft Visual C++ 再配布可能パッケージ for Visual Studio 2022 が、これらの PHP バージョンと適合します。 » https://visualstudio.microsoft.com/downloads/ を参照ください。

x86 版のビルドには x86 版の CRT を、そして x64 版のビルドには x64 版の CRT が必要です。

CRT が既にインストール済みである場合はインストーラがそれを検出して通知してくれます。この場合、インストーラは何も手を加えません。

CRT のインストーラはコマンドラインオプション /quiet および /norestart に対応しているので、スクリプトで自動実行させることもできます。


PECL

PECL 拡張モジュールは、 Windows 用にビルド済みのものがこちらからダウンロードできます。 » http://windows.php.net/downloads/pecl/releases/

Unix システム固有の機能を使っている拡張モジュールは Windows 版が存在しませんが、 それ以外についてはすべて Windows 版が用意されています。


Windows 上での PHP インストーラ

PHP インストールツール

» XAMPP や、 WampServer や BitNami などを使えば、 Windows 上で Apache を使う場合の PHP アプリケーションをセットアップできます。

Nginx を Windows でセットアップする場合は、 少し多くの設定が必要です。 セットアップに関して追加のヘルプが必要な場合は、 » Nginx のドキュメント を参照ください。


Windows でのおすすめの構成

OpCache

OpCache を有効にすることを強く推奨します。この拡張モジュールは Windows 版の PHP に含まれています。 これは PHP スクリプトをコンパイルして最適化したうえで、メモリにキャッシュします。 そのため、ページを読み込むたびにコンパイルされることがなくなります。

php.ini では、次のように設定します:

例1 OpCache の推奨構成

opcache.enable=On
opcache.enable_cli=On
そしてウェブサーバーを再起動します。 詳細な情報は OpCache の実行時設定 を参照ください。

WinCache

IIS を使うなら、 WinCache を有効にすることを推奨します。 特に、共有ウェブホスティング環境やネットワークファイルストレージ (NAS) での利用の際におすすめです。 但し、PHP 8.0.0 以降では WinCache はサポートされていないことに注意して下さい。 すべての PHP アプリケーションが、 WinCache のファイルキャッシュ機能の恩恵を受けられます。 ファイルシステム上での操作が、メモリにキャッシュされるのです。 WinCache は、メモリ内のユーザーオブジェクトをキャッシュして、 php.exe や php-cgi.exe のプロセス間で共有することもできます (複数リクエストでのオブジェクトの共有)。 主要なウェブアプリケーションの多くは、 プラグインや拡張モジュールあるいは設定オプションで WinCache のユーザーオブジェクトキャッシュを使えるようになっています。 ハイパフォーマンスを求めるなら、 アプリケーション内でオブジェクトキャッシュを利用すべきです。 » http://pecl.php.net/package/WinCache から WinCache DLL (あるいは tgz) をダウンロードして、 PHP の拡張モジュール用ディレクトリ (php.ini の extensions_dir) に配置しましょう。 php.ini では、次のように設定します:

例2 WinCache の推奨構成

extension=php_wincache.dll
wincache.fcenabled=1
wincache.ocenabled=1 ; removed as of wincache 2.0.0.0
詳細な情報は » http://php.net/manual/ja/wincache.configuration.php を参照ください。

IIS の構成

IIS マネージャーで FastCGI モジュールをインストールして、`.php` へのハンドラマッピングを追加します。ここでは、PHP-CGI.exe へのパスを指定します (PHP.exe ではありません)。

コマンドラインツール APPCMD を使えば、IIS の構成をスクリプト化できます。

データベース

おそらく、データベースサーバーも必要となることでしょう。 主要なデータベースは PHP 用の拡張モジュールを提供しています。 もしウェブサイトへのアクセスがそれほど多くないのなら、 ウェブサーバーと同じマシンでデータベースを動かすこともできます。 主要なデータベースの多くは Windows 上でも動作します。

PHP には mysqli 拡張モジュールと pdo_mysql 拡張モジュールが含まれています。

» https://dev.mysql.com/downloads/windows/ を参照ください。


Windows 上での PHP の手動インストール

ウェブサーバーの選択

IIS

IIS は Windows に標準で組み込まれています。 Windows サーバーの場合は、サーバーマネージャーを使って IIS ロールを追加します。CGI ロールを含める必要があります。 Windows デスクトップの場合は、コントロールパネルの「プログラムの追加と削除」を使って IIS を追加します。 Microsoft のドキュメントに » 詳細な手順があります。 デスクトップウェブアプリケーションやウェブ開発の場合は、IIS/Express や PHP Desktop も使えます。

例1 IIS と PHP の設定をするためのコマンドライン

@echo off

REM download .ZIP file of PHP build from http://windows.php.net/downloads/

REM path to directory you decompressed PHP .ZIP file into (no trailing \)
set phppath=c:\php

REM Clear current PHP handlers
%windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
REM The following command will generate an error message if PHP is not installed. This can be ignored.
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

REM Set up the PHP handler
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

REM Configure FastCGI Variables
%windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

Apache

Windows 用の Apache2 のビルドには、いくつかの種類があります。 ApacheLounge がおすすめですが、それ以外にも XAMPP や WampServer や BitNami といったものがあり、これらはインストーラがついています。 Apache で PHP を使うには、mod_php あるいは mod_fastcgi を用います。 mod_php を使う場合は、スレッドセーフ版の Apache を使う必要があります。また、同じバージョンの Visual C、同じ CPU (x86 あるいは x64) のビルドでなければいけません。

ビルド方法の選択

Windows 向けのビルドは » http://windows.php.net/download/ からダウンロードできます。 全てのビルドは最適化(PGO) されており、 QA や GA リリースで数多くのテストがなされています。

PHP には四種類のビルドがあります。

  • Thread-Safe(TS) - Apache と mod_php のような、シングルプロセスのウェブサービス用

  • Non-Thread-Safe(NTS) - IIS やその他の FastCGI ウェブサーバー (Apache と mod_fastcgi など) 用。また、コマンドラインのスクリプト用にもおすすめ。

  • x86 - 32ビット版向け

  • x64 - 64ビット版向け


ソースからのビルド

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

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


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

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

注意:

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

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

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

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

    注意:

    PATH と PATHEXT は Windows で重要な働きをするシステム変数です。 既存の変数の値を上書きしないように注意しましょう。 あくまでも追記するだけにします。

  • 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:\php\php.exe" -f "%1" -- %~2

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

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

例1 Registry changes

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:\\php\\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:\\php\\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 を参照ください。 Windows 10 ではこの設定が変更されたようです。Windows 10 をインストールしたデフォルトの状態で、 コンソールのハンドルが自動的に引き継がれるようになります。この件に関しては、 » Microsoft のフォーラムへの投稿 に説明があります。


Apache 2.x （Microsoft Windows 用）

このセクションでは、Microsoft Windows 上の Apache 2.x で PHP をインストールする場合の説明とヒントを記しています。

注意:

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

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

最新の » 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 2.x 用の PHP モジュールを読み込むには、 以下の行を Apache 設定ファイル httpd.conf に追加しなければいけません:

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

# PHP 8.0.0 より前のバージョンでは、モジュール名は php7_module でした。
LoadModule php_module "c:/php/php8apache2_4.dll"
<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>
# configure the path to php.ini
PHPIniDir "C:/php"

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

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 を » https://www.apachelounge.com から取得します。Win32 用のバイナリがこのサイトからダウンロードできます。 そして、説明に従ってモジュールをインストールしましょう。

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

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

LoadModule fcgid_module modules/mod_fcgid.so
# Where is your php.ini file?
FcgidInitialEnv PHPRC        "c:/php"
<FilesMatch \.php$>
    SetHandler fcgid-script
</FilesMatch>
FcgidWrapper "c:/php/php-cgi.exe" .php
これで、拡張子 .php のファイルは PHP FastCGI ラッパーが処理するようになります。


Windows 上での PHP のトラブルシューティング

テンポラリディレクトリのパーミッションのチェック

  1. エクスプローラでテンポラリディレクトリを右クリックして、パーミッションを調べます。

  2. IIS の場合は、 IIS_User ユーザーがこのディレクトリへの書き込み権限を持っている必要があります。 テンポラリディレクトリの場所は、php の設定や phpinfo で取得できます。


  • ≪ Windows 上での PHP のトラブルシューティング
  • Azure App Services ≫
  • PHP Manual
  • インストールと設定
  • クラウドコンピューティングプラットフォームへのインストール

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

目次

  • Azure App Services
  • Amazon EC2
  • DigitalOcean

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


Azure App Services

PHP は、Azure App Services (aka Microsoft Azure, Windows Azure, Azure Web Apps) 上でもよく使われています。

Azure App Services は、ウェブアプリケーションをホストする Windows Web Servers のプールを管理します。自前の Azure Compute VM などで自前のウェブサーバーを管理する方法の代替となるものです。

Azure App Services のウェブサイトでは、PHP がはじめから有効になっています。Azure Portal でウェブサイトを選択すると、どのバージョンの PHP を使うかを選ぶことができます。デフォルトよりも新しいバージョンを使うこともできます。

つまり Azure App Services 上では、その他の Windows サーバー上と同様に PHP や拡張モジュールが動くということです。 Windows 上での知識の多くがそのまま使えるので、Windows のトラブルシューティングページ も参照ください。 しかし、Azure App Services の管理インターフェイスは、Windows サーバーとは少し異なります。

  • Azure portal: ウェブサイトの作成や設定変更、削除を行います。» Azure Portal

  • Kudu Dashboard: [your web site name].azurewebsites.net の Kudu dashboard は » https://[your web site name].scm.azurewebsites.net/ です。このダッシュボードには、デバッグやファイル管理そしてサイト拡張といった機能があります。サイト拡張とは、PHP のプレビュー版などの追加プログラムをウェブサイトに追加するための Azure の機構のことです。

  • IIS Manager や Server Manager や RDP は使えません。

PHP SDK も用意されていて、自分の PHP コードからさまざまな Azure Service を使うことができます。» Azure SDK for PHP を参照ください。

詳細な情報は » Azure PHP Developer Center を参照ください。

WinCache

WinCache は Azure App Services でデフォルトで有効になっています。そのままにしておくことを推奨します。 もし PHP を自分でビルドするなら、WinCache も有効にしておくべきです。

カスタム PHP ビルド

自分でビルドした PHP を D:\Home にアップロードします (C:\ への書き込み権限はありません)。そして、Azure Portal で、.php の SCRIPT_PROCESSOR に php-cgi.exe への絶対パスを設定します。


  • ≪ Azure App Services
  • DigitalOcean ≫
  • PHP Manual
  • クラウドコンピューティングプラットフォームへのインストール
  • Amazon EC2

Amazon EC2

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

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


DigitalOcean

DigitalOcean は、PHP をインストールし、クラウドをホスティングするインフラ上でWebアプリケーションを動作させるために、以下のプラットフォームを提供しています。

  • » Cloudways: 以下のような、主要なPHPアプリケーションをワンクリックでデプロイできます: WordPress, Magento, Drupal, Laravel など

  • » Droplet: 仮想マシンのボックスで、 » Lamp スタックをLinuxサーバ上にインストールできます 。

  • » App Platform: アプリを素早くビルド、デプロイし、スケールさせるための マネージドなインフラストラクチャです。 » how to run PHP application on the App Platform を参照ください。

  • » Functions: 開発者がサーバのプロビジョニングや管理を行うことなく、コードを実行できるサーバレスプラットフォームです。 PHP をネイティブでサポートしています。 » how to create serverless functions in PHP を参照ください。


FastCGI Process Manager (FPM)

目次

  • インストール
  • 設定

FPM (FastCGI Process Manager) は、PHP における FastCGI 実装です。(主に)高負荷のサイトで有用な機能が含まれています。

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

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

  • 異なる uid/gid/chroot/environment でワーカーが開始でき、 異なるポートで Listen でき、異なる php.ini が適用できる (safe_mode の代替) プールのサポート。

  • 設定が変更可能な、 標準出力および標準エラー出力へのログ出力

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

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

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

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

  • 動的/オンデマンド/静的 な子プロセスの起動

  • 基本的な SAPI の動作状況 (Apache の mod_status と同等) を、 json, xml, openmetrics のようなフォーマットで提供

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


インストール

ソースからのコンパイル

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

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

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

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

  • --with-fpm-systemd - systemd 統合をアクティブにします (デフォルトは no)。

  • --with-fpm-acl - POSIX アクセス制御リストを使用します (デフォルトは no)。

  • --with-fpm-apparmor - AppArmor との統合を有効にします (デフォルトは no)。

  • --with-fpm-selinux - SELinux との統合を有効にします (デフォルトは no)。

変更履歴

バージョン | 説明
8.2.0 | --with-fpm-selinux が追加されました。
8.0.0 | --with-fpm-apparmor が追加されました。


設定

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

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

pid string

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

error_log string

エラーログファイルへのパス。デフォルト値: #INSTALL_PREFIX#/log/php-fpm.log "syslog" と設定すると、ログをローカルファイルに書き出すのではなく、syslogd に送信します。

log_level string

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

log_limit int

1024文字以上のログメッセージを、 改行せずにロギングできる文字数の上限。 デフォルト値: 1024 PHP 7.3.0 以降で利用可能

log_buffering bool

追加のバッファリングを行わずに実験的なロギングを行う デフォルト値: yes PHP 7.3.0 以降で利用可能

syslog.facility string

メッセージを記録するプログラムの種別。 デフォルト値: daemon

syslog.ident string

すべてのメッセージの先頭に付加する内容。 複数の FPM インスタンスを同一サーバー上で実行する場合には、 デフォルト値を変更すれば区別できるようになります。 デフォルト値: php-fpm

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

process.max int

FPM がフォークするプロセスの最大数。 多数のプール内で動的な PM を使う場合に、全体のプロセス数を制御するために用意されたものです。 気をつけて使うようにしましょう。 デフォルト値: 0

process.priority int

マスタープロセスに適用する nice(2) 値。 -19 (優先度最高) から 20 (優先度最低) までの値を指定します。 デフォルト値: 未設定

daemonize bool

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

rlimit_files int

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

rlimit_core int

マスタープロセス用の、最大コアサイズの rlimit。 デフォルト値: 0

events.mechanism string

FPM が利用するイベントメカニズム。 select、pool、epoll、kqueue (*BSD)、port (Solaris) が利用可能。 デフォルト値: 未設定 (自動検出)

systemd_interval int

FPM を systemd 統合込みでビルドした場合に、 ヘルスチェックのレポートを systemd に送る間隔 (秒単位)。 0 にすると、無効化されます。 デフォルト値: 10

プール一覧の項目

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

listen string

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

listen.backlog int

listen(2) のバックログを設定します。 -1 はBSD 系のシステムでは最大値を意味します。 デフォルト値: -1 (FreeBSD や OpenBSD) または 511 (Linux やその他のプラットフォーム)

listen.allowed_clients string

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

listen.owner string

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

listen.group string

listen.owner を参照ください。

listen.mode string

listen.owner を参照ください。

listen.acl_users string

POSIX の Access Control List をサポートしている場合は、このオプションでそれを指定できます。 これを設定した場合は、listen.owner および listen.group は無視されます。 値には、ユーザー名をカンマ区切りのリスト形式で指定します。

listen.acl_groups string

listen.acl_users を参照。 グループ名を、カンマ区切りのリスト形式で指定します。

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 int

起動時に作成される子プロセスの数。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_spawn_rate int

一度に子プロセスを生成する数。 pm の値が dynamic である場合にのみ使えます。 デフォルト値: 32

pm.process_idle_timeout mixed

アイドルなプロセスがkillされた後の秒数。 pm の値が 使用可能な単位: s(秒)(デフォルト)、m(分)、h(時間)、または d(日)。 デフォルト値: 10 秒

pm.max_requests int

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

pm.status_listen string

FastCGI の statusリクエスト を受け付けるアドレス。 これを設定すると、独自にリクエストを処理する新しい、 外からは見えないプールが作られます。 これは、長時間実行されるリクエストによって メインプールがビジーである場合に役立ちます。 なぜなら、そうした処理に長時間かかるリクエストが終わる前であっても、 FPM の情報ページ を見ることが出来るからです。 listen ディレクティブと設定できる内容は同じです。 デフォルト値: 未設定。

pm.status_path string

FPM の情報ページ を見るための URI。この値は、スラッシュ (/) で始めなければいけません。 この値を省略した場合は、どの URI も情報ページとは見なされません。 デフォルト値: なし

ping.path string

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

ping.response string

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

process.priority int

ワーカープロセスに適用される、 nice(2) の値の優先度を指定します。 (指定された場合のみ有効) この値は、-19(優先度最高) から、20(優先度最低) まで変わります。 デフォルト値: 未設定

process.dumpable bool

プロセスのユーザーやグループが、 masterプロセスのユーザーと異なっていた場合でも、 プロセスのダンプ可能フラグ(PR_SET_DUMPABLE prctl)を設定します。 これにより、プロセスのコアダンプを生成できるようになり、 pool のユーザーがプロセスを ptrace 出来るようになります。 デフォルト値: no PHP 7.0.29, 7.1.17 および 7.2.5 から利用可能

prefix string

path を評価する際に、 path の前につける prefix を指定します。

request_terminate_timeout mixed

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

request_terminate_timeout_track_finished bool

fastcgi_finish_request がコールされた後や、 アプリケーションが終了し、 内部的なシャットダウン関数がコールされているときには適用されない request_terminate_timeout を有効にするかどうか。 このディレクティブを有効にすると、 そのような適用されないケースでもタイムアウトを無条件に有効にします。 デフォルト値: no。PHP 7.3.0 以降で利用可能。

request_slowlog_timeout mixed

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

request_slowlog_trace_depth int

slowlog に吐き出されるログのスタックトレースの深さ。 デフォルト値: 20。PHP 7.2.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 bool

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

decorate_workers_output bool

catch_workers_output が有効になった場合に、 ワーカーの出力のデコレートを有効にします。 デフォルト値: yes PHP 7.3.0 以降で利用可能。

clear_env bool

FPM ワーカー内の環境をクリアする。 任意の環境変数が FPM ワーカープロセスに到達してしまうことを防ぐために、 ワーカー内の環境をいったんクリアしてから、このプールの設定で指定された環境変数を追加します。 デフォルト値: Yes

security.limit_extensions string

FPM がパース可能なメインスクリプトを拡張子で制限する。 サーバー側の設定ミスによる被害を抑えることができます。 FPM には拡張子 .php だけをパースさせるようにしておけば、 悪意のあるユーザーがその他の拡張子で php のコードを実行させようとする試みを防ぐことができます。 デフォルト値: .php .phar

apparmor_hat string

AppArmor が有効になっている場合に、 ハット変更を許可します。 デフォルト値: 未設定。

access.log string

アクセス・ログ・ファイル。 デフォルト値: 未設定

access.format string

アクセス・ログ形式。 デフォルト値: "%R - %u %t \"%m %r\" %s":

有効なオプション
プレースホルダ | 説明
%C | %CPU
%d | duration μs
%e | fastcgi env
%f | script
%l | content length
%m | method
%M | memory
%n | pool name
%o | header output
%p | PID
%q | query string
%Q | the glue between %q and %r
%r | request URI
%R | remote IP address
%s | status
%T | time
%t | time
%u | remote user

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

例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() で上書きすることはできません。

PHP の設定は、ウェブサーバーでも設定できます。

例2 PHP の設定を nginx.conf で行う例

set $php_value "pcre.backtrack_limit=424242";
set $php_value "$php_value \n pcre.recursion_limit=99999";
fastcgi_param  PHP_VALUE $php_value;

fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";
警告

これらの設定は fastcgi ヘッダーとして php-fpm に渡されるので、 一般公開されているアドレスに php-fpm をバインドしてはいけません。 そんなことをすると、誰でもそのサーバーの PHP の設定を変更できることになります。 listen.allowed_clients も参照ください。

注意: プールはセキュリティを考慮した仕組みではありません。 なぜなら、完全な分離を提供しないからです。 たとえば、FPM のプールは、単一の OPcache のインスタンスを使います。


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

目次

  • PECL インストール入門
  • PECL 拡張モジュールをダウンロードする
  • PHP 拡張モジュールの Windows へのインストール
  • 共有 PECL 拡張モジュールを、pecl コマンドを用いてコンパイルする
  • phpize で共有 PECL 拡張モジュールをコンパイルする方法
  • php-config
  • PECL 拡張モジュールを PHP に静的に組み込む


PECL インストール入門

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

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

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

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


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

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

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

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

  • Windows ダウンロード PHP プロジェクトでは、大半の PECL 拡張モジュールの Windows 用コンパイル済み DLL を提供しています。各パッケージのページをごらんください。


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

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

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

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

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

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

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

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

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

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

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

各 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 上に存在し、 あとはセミコロンを取り除くだけで有効にできるようになっています。

PHP 7.2.0 以降では、拡張モジュールの名前が、拡張モジュールのファイル名の代わりに使えるようになりました。 これは OS に依存せず、特に初心者に簡単な仕組みです。 これは、読み込む拡張モジュールを指定する推奨できるやり方になっています。 それより前のバージョンとの互換性を確保するため、ファイル名の指定もまだサポートされています。

;extension=php_extname.dll

extension=php_extname.dll

; PHP バージョン 7.2 以降では、下記が良いでしょう。
extension=extname
zend_extension=another_extension

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

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

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

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

問題の解決

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

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

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

DLL そのものや、それが依存している 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 インストーラを使用するという選択肢が使えない場合もあります。 たとえばファイアウォールの内部で作業をしている場合がそうですし、 まだリリースされていない git 版のように 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 に静的に組み込みたいと思うこともあるでしょう。 そのためには、拡張モジュールのソースを /path/to/php/src/dir/ext/ ディレクトリに置き、PHP にその設定スクリプトを生成させる必要があります。

$ cd /path/to/php/src/dir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname

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

/path/to/php/src/dir/ext/extname

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

$ cd /path/to/php/src/dir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install

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

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

$ ./configure --help | grep extname


  • ≪ PECL 拡張モジュールを PHP に静的に組み込む
  • FAQ を読む ≫
  • PHP Manual
  • インストールと設定
  • 問題が起きた場合

問題が起きた場合

目次

  • FAQ を読む
  • FAQ に無い問題
  • バグ報告


FAQ を読む

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


FAQ に無い問題

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

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


バグ報告

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

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


実行時設定

目次

  • 設定ファイル
  • .user.ini ファイル
  • どこで設定を行うのか
  • 設定を変更するには


設定ファイル

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

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

  • SAPI モジュール特有の場所 (Apache 2 における PHPIniDir ディレクティブ、 CGI/CLI 版における -c コマンドラインオプション)
  • PHPRC 環境変数。
  • PHP のバージョンごとに別の場所の php.ini を使用することができます。レジストリキーの root は、 インストールされたOS や PHP が 32bit や 64bit どちらのビルドかによって変わります。 32bit OS 上の 32bit ビルドの PHP、 もしくは 64bit OS 上の 64bit ビルドの PHP は [(HKEY_LOCAL_MACHINE\SOFTWARE\PHP] を使いますが、 64bit OS 上での 32bit ビルドのPHPは、 [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]] を代わりに使います。 ビルドのbit数がOSと同じPHPのインストールの場合、 以下のレジストリキーを順に調べて使用します。 [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 のメジャーバージョン、マイナーバージョン、 リリース番号を表します。 64bit OS の 32bitビルドの PHP では、 以下のレジストリキーを順に調べて使用します。 [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z], [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y] および [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x] x、y および z はそれぞれ PHP のメジャーバージョン、マイナーバージョン、 リリース番号を表します。 これらのキーに IniFilePath の値が設定されていれば、最初に見つかった場所の php.ini を使用します (Windows のみ)。
  • [HKEY_LOCAL_MACHINE\SOFTWARE\PHP] または [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\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 の中で環境変数を使うには、次のようにします。

例1 php.ini での環境変数

; 環境変数 PHP_MEMORY_LIMIT を利用します
memory_limit = ${PHP_MEMORY_LIMIT}

拡張モジュールに対する php.ini ディレクティブは、 各拡張モジュールのドキュメントで解説されています。 コア ディレクティブ （PHP 本体に対するディレクティブ）のリストは付録にまとめられています。 ただし、（更新の都合上）すべての PHP ディレクティブが 本マニュアル中で解説されている訳ではありません。 使っているバージョンの PHP で指定可能なすべてのディレクティブについては、 php.ini ファイル内に詳細なコメントが記されていますので、参照ください。 もしくは、Git から入手可能な » 最新の php.ini も有用でしょう。

例2 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"

ini ファイル内で既存の ini 変数を参照することが可能です。 例: open_basedir = ${open_basedir} ":/new/dir"

スキャンディレクトリ

PHP の設定で、php.ini を読んだ後に .ini ファイルを探すディレクトリを指定できます。 これは、コンパイル時のオプション --with-config-file-scan-dir で設定します。 このスキャンディレクトリは実行時に上書きできます。 環境変数 PHP_INI_SCAN_DIR で指定します。

複数のディレクトリを指定するには、各プラットフォームのパス区切り文字 (Window や NetWare そして RISC OS の場合は ;、 その他のプラットフォームの場合は :。PHP が用いる値は定数 PATH_SEPARATOR で取得できます) を用います。PHP_INI_SCAN_DIR に空文字列が指定された場合は、 PHP のコンパイル時に --with-config-file-scan-dir で指定されたディレクトリもスキャンします。

指定されたディレクトリの中にあるファイルの中で、ファイル名が .ini で終わるすべてのファイルを、アルファベット順にスキャンします。 読み込まれたファイルの一覧とその順序を調べるには、 php_ini_scanned_files() を呼ぶか、あるいは --ini オプションつきで PHP を実行します。

PHP のコンパイル時に --with-config-file-scan-dir=/etc/php.d
を指定しており、パス区切り文字が : であるものとします

$ php
  PHP は /etc/php.d/*.ini を設定ファイルとして読み込みます。

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP は /usr/local/etc/php.d/*.ini を設定ファイルとして読み込みます。

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP はまず /etc/php.d/*.ini を設定ファイルとして読み込み、
  続いて /usr/local/etc/php.d/*.ini も設定ファイルとして読み込みます。

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP はまず /usr/local/etc/php.d/*.ini を設定ファイルとして読み込み、
  続いて /etc/php.d/*.ini を設定ファイルとして読み込みます。


.user.ini ファイル

PHP はディレクトリ単位での INI ファイルをサポートしています。 このファイルは、CGI/FastCGI SAPI の場合にのみ処理されます。 この機能は、PECL htscanner 拡張モジュールを置き換えるものです。 Apache モジュールとして PHP を実行している場合は .htaccess ファイルを使えば同じ機能を実現できます。

メイン php.ini ファイルに加えて、PHP が各ディレクトリの INI ファイルをスキャンします。 リクエストされた PHP ファイルがあるディレクトリから始まり、 現在のドキュメントルート ($_SERVER['DOCUMENT_ROOT']) まで順にたどっていきます。PHP ファイルがドキュメントルート配下以外の場所にある場合は、 PHP ファイルがあるディレクトリだけをスキャンします。

.user.ini 形式の INI ファイルがサポートするのは、 モードが INI_PERDIR および 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 は INI_PERDIR なので、 ini_set() で設定することはできません。 一方 display_errors は INI_ALL なのでどこででも設定でき、当然 ini_set() ででも設定できます。

INI モードの定数
INI_USER (int)
エントリはユーザーのスクリプトで (ini_set() のようなものを使って) 設定できます。 また、Windows registry でも設定できます。 .user.ini でも設定できます。
INI_PERDIR (int)
エントリは php.ini, .htaccess, httpd.conf, .user.ini で設定できます。
INI_SYSTEM (int)
エントリは php.ini または httpd.conf で設定できます。
INI_ALL (int)
エントリはどこでも設定できます


設定を変更するには

Apache モジュールとして PHP を実行している場合

PHP を Apache モジュールとして使用している場合、Apache 設定ファイル (例、httpd.conf) もしくは .htaccess ファイルにディレクティブを記述することで、PHP の設定の変更を行うことが 可能です。このようにして設定変更を行うには、"AllowOverride Options" もしくは "AllowOverride All" 権限が必要です。

Apache 設定ファイルから PHP の設定を変更するには、 以下に示す Apache ディレクティブを使用します。 各設定オプションの変更の可否 (INI_ALL, INI_PERDIR, または INI_SYSTEM) については、付録 php.ini ディレクティブのリスト を参照ください。

php_value name value

指定した設定オプションに値を設定します。変更の可否が、 INI_ALL もしくは INI_PERDIR である設定オプションに対し利用できます。 セット済みの値をクリアしたい場合は、none を 値として使用してください。

注意: 論理値を設定する場合には php_value を使用しないでください。代わりに、php_flag （下記参照）を使用する必要があります。

php_flag name on|off

設定オプションに論理値を設定するために使用します。変更の可否が、 INI_ALL もしくは 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 定数を記述しても解釈されませんので、注意してください。 しかし、INI_USER で変更可能な設定値はこの方法で設定することが可能ですが、 INI_PERDIR である設定値は設定できません。 なぜなら、これらの設定値はリクエストがあるたびに読み直されるからです。

他の方法

どのように PHP を実行しているかに係わらず、ini_set() 関数を 用いて、スクリプトの実行時に一部のオプションの設定値を変更することができます。詳細は、 ini_set() 関数のリファレンスを参照ください。

使用しているシステムにおける現在のオプション設定値の完全なリストを得たい場合は、 phpinfo() 関数を実行し、出力された結果を参照ください。 また、ini_get() 関数または get_cfg_var() 関数を用いて、個々のオプションの設定値にアクセスすることも可能です。


言語リファレンス

  • 基本的な構文
    • PHP タグ
    • HTML からの脱出
    • 命令の分離
    • コメント
  • 型
    • はじめに
    • 型システム
    • NULL
    • 論理型 (boolean)
    • 整数
    • 浮動小数点数
    • 文字列
    • 数値形式の文字列
    • 配列
    • オブジェクト
    • 列挙型 / Enum
    • リソース
    • コールバック / Callable
    • Mixed
    • Void
    • Never
    • クラス内での関係を示す相対型
    • Value型
    • Iterable
    • 型宣言
    • 型の相互変換
  • 変数
    • 基本的な事
    • 定義済みの変数
    • 変数のスコープ
    • 可変変数
    • 外部から来る変数
  • 定数
    • 構文
    • 自動的に定義される定数
    • マジック定数
  • 式
  • 演算子
    • 演算子の優先順位
    • 算術演算子
    • 加算子/減算子
    • 代入演算子
    • ビット演算子
    • 比較演算子
    • エラー制御演算子
    • 実行演算子
    • 論理演算子
    • 文字列演算子
    • 配列演算子
    • 型演算子
  • 制御構造
    • はじめに
    • if
    • else
    • elseif/else if
    • 制御構造に関する別の構文
    • while
    • do-while
    • for
    • foreach
    • break
    • continue
    • switch
    • match
    • declare
    • return
    • require
    • include
    • require_once
    • include_once
    • goto
  • 関数
    • ユーザー定義関数
    • 関数の引数
    • 戻り値
    • 可変関数
    • 内部（ビルトイン）関数
    • 無名関数
    • アロー関数
    • 第一級callableを生成する記法
  • クラスとオブジェクト
    • はじめに
    • クラスの基礎
    • プロパティ
    • クラス定数
    • クラスのオートローディング
    • コンストラクタとデストラクタ
    • アクセス権
    • オブジェクトの継承
    • スコープ定義演算子 (::)
    • static キーワード
    • クラスの抽象化
    • オブジェクト インターフェイス
    • トレイト
    • 無名クラス
    • オーバーロード
    • オブジェクトの反復処理
    • マジックメソッド
    • finalキーワード
    • オブジェクトのクローン作成
    • オブジェクトの比較
    • 遅延静的束縛 (Late Static Bindings)
    • オブジェクトと参照
    • オブジェクトのシリアライズ — オブジェクトのシリアライズ - セッション内でのオブジェクト
    • 共変性と反変性
    • 変更履歴
  • 名前空間
    • 概要 — 名前空間の概要
    • 名前空間 — 名前空間の定義
    • サブ名前空間 — サブ名前空間の宣言
    • 同一ファイル内での複数の名前空間の定義
    • 基本編 — 名前空間の使用法: 基本編
    • 名前空間と動的言語機能
    • namespace キーワードおよび __NAMESPACE__ — namespace キーワードおよび __NAMESPACE__ 定数
    • エイリアス/インポート — 名前空間の使用法: エイリアス/インポート
    • グローバル空間
    • グローバル関数/定数への移行 — 名前空間の使用法: グローバル関数/定数への移行
    • 名前解決のルール
    • FAQ — FAQ: 名前空間について知っておくべきこと
  • 列挙型(Enum)
    • 列挙型の概要
    • 列挙型の基礎
    • 値に依存した列挙型(Backed Enum)
    • 列挙型とメソッド
    • 列挙型と static メソッド
    • 列挙型と定数
    • トレイト
    • 定数式における列挙型の値
    • オブジェクトとの違い
    • 値のリスト
    • 列挙型をシリアライズする
    • 列挙型が継承できない理由
    • 例
  • エラー
    • 基本
    • PHP 7 でのエラー
  • 例外(exceptions)
    • 例外を拡張する
  • ファイバー
  • ジェネレータ
    • ジェネレータとは
    • ジェネレータの構文
    • ジェネレータと Iterator オブジェクトとの比較
  • アトリビュート
    • アトリビュートの概要
    • アトリビュートの文法
    • リフレクションAPI を使ってアトリビュートを読み取る
    • アトリビュートクラスを宣言する
  • リファレンスの説明
    • リファレンスとは?
    • リファレンスが行うことは何ですか?
    • リファレンスが行わないこと
    • リファレンス渡し
    • リファレンスを返す
    • リファレンスの解除
    • リファレンスの適用範囲
  • 定義済みの変数
    • スーパーグローバル — すべてのスコープで使用できる組み込みの変数
    • $GLOBALS — グローバルスコープで使用可能なすべての変数への参照
    • $_SERVER — サーバー情報および実行時の環境情報
    • $_GET — HTTP GET 変数
    • $_POST — HTTP POST 変数
    • $_FILES — HTTP ファイルアップロード変数
    • $_REQUEST — HTTP リクエスト変数
    • $_SESSION — セッション変数
    • $_ENV — 環境変数
    • $_COOKIE — HTTP クッキー
    • $php_errormsg — 直近のエラーメッセージ
    • $http_response_header — HTTP レスポンスヘッダ
    • $argc — スクリプトに渡された引数の数
    • $argv — スクリプトに渡された引数の配列
  • 定義済みの例外
    • Exception
    • ErrorException
    • ClosedGeneratorException — ClosedGeneratorException クラス
    • Error
    • ArgumentCountError
    • ArithmeticError
    • AssertionError
    • DivisionByZeroError
    • CompileError
    • ParseError
    • TypeError
    • ValueError
    • UnhandledMatchError
    • FiberError
  • 定義済みのインターフェイスとクラス
    • Traversable — Traversable インターフェイス
    • Iterator — Iterator インターフェイス
    • IteratorAggregate — IteratorAggregate インターフェイス
    • InternalIterator — InternalIterator クラス
    • Throwable
    • ArrayAccess — ArrayAccess インターフェイス
    • Serializable — Serializable インターフェイス
    • Closure — Closure クラス
    • stdClass — stdClass クラス
    • Generator — Generator クラス
    • Fiber — Fiber クラス
    • WeakReference — WeakReference クラス
    • WeakMap — WeakMap クラス
    • Stringable — Stringable インターフェイス
    • UnitEnum — UnitEnum インターフェイス
    • BackedEnum — BackedEnum インターフェイス
    • SensitiveParameterValue — SensitiveParameterValue クラス
    • __PHP_Incomplete_Class — __PHP_Incomplete_Class クラス
  • 定義済みのアトリビュート
    • Attribute — Attribute クラス
    • AllowDynamicProperties — AllowDynamicProperties クラス
    • Override — Override クラス
    • ReturnTypeWillChange — ReturnTypeWillChange クラス
    • SensitiveParameter — SensitiveParameter クラス
  • コンテキストオプションとパラメータ
    • ソケットコンテキストオプション — ソケットコンテキストオプション一覧
    • HTTP コンテキストオプション — HTTP コンテキストオプションの一覧
    • FTP コンテキストオプション — FTP コンテキストオプションの一覧
    • SSL コンテキストオプション — SSL コンテキストオプションの一覧
    • Phar コンテキストオプション — Phar コンテキストオプション一覧
    • コンテキストパラメータ — コンテキストパラメータの一覧
    • Zip コンテキストオプション — Zip コンテキストオプション一覧
    • Zlib コンテキストオプション — Zlib コンテキストオプション一覧
  • サポートするプロトコル/ラッパー
    • 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 タグ ≫
  • PHP Manual
  • 言語リファレンス
  • 基本的な構文

基本的な構文

目次

  • PHP タグ
  • HTML からの脱出
  • 命令の分離
  • コメント


PHP タグ

PHP はファイルを解析して開始タグと終了タグ (<?php と ?>) を探します。 タグが見つかると、PHP はコードの実行を開始したり終了したりします。 このような仕組みにより、PHP を他のあらゆる形式のドキュメント中に 埋め込むことができるのです。つまり、開始タグと終了タグで囲まれている 箇所以外のすべての部分は、PHP パーサに無視されます。

PHP では、短い形式のechoタグ <?= も使えます。 これは、より冗長な <?php echo を短くしたものです。

例1 PHP の開始タグと終了タグ

1. <?php echo 'XHTMLまたはXMLドキュメントの中でPHPコードを扱いたい場合は、このタグを使いましょう'; ?>

2. 短い形式の echo タグを使って <?= 'この文字列を表示' ?> とすることもできます。
これは <?php echo 'この文字列を表示' ?> と同じ意味になります。

3. <? echo 'このコードは短縮型のタグに囲まれていますが、'.
'short_open_tag が有効な場合にしか動作しません'; ?>

短縮型のタグ（例 3.）はデフォルトで有効ですが、 php.ini 設定ファイルのディレクティブ short_open_tag で無効にすることもできますし、 --disable-short-tags オプション付きで configure した場合は、 デフォルトで無効にすることも出来ます。

注意:

短縮形のタグは無効にすることができるので、 互換性を最大限保つために、通常のタグ (<?php ?> and <?= ?>) を使うことを推奨します。

ファイルが 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 コードを XML や XHTML に 埋め込む場合には、標準規格に従うために <?php ?> タグを使用する 必要があるでしょう。


命令の分離

C や Perl と同様に、PHP でもステートメントを区切るにはセミコロンが必要と なります。PHP コードブロックの終了タグには自動的にセミコロンが含まれていると 認識されます。 従って PHP コードの最終行にはセミコロンを記述する必要はありません。 ブロックの終了タグは、直後に改行がある場合、それを含んだものになります。

例1 改行を囲んだ終了タグを表示させる例

<?php echo "Some text"; ?>
No newline
<?= "But newline now" ?>

上の例の出力は以下となります。

Some textNo newline
But newline now

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 モードに戻ると、そこでは // あるいは # は何の影響も 及ぼしません。

<h1>これは <?php # echo 'シンプルな';?> 例です。</h1>
<p>上の見出しは 'これは 例です。' となります。

'C' 型のコメントは、最初に */ が現れた時点で終了します。 'C' 型のコメントがネストしないように注意する必要があります。 大きなブロックをコメントアウトしようとする際に、この間違いを犯しがちです。

<?php
/*
echo 'テストです'; /* このコメントが問題を生じます */
*/
?>


型

目次

  • はじめに
  • 型システム
  • NULL
  • 論理型 (boolean)
  • 整数
  • 浮動小数点数
  • 文字列
  • 数値形式の文字列
  • 配列
  • オブジェクト
  • 列挙型 / Enum
  • リソース
  • コールバック / Callable
  • Mixed
  • Void
  • Never
  • クラス内での関係を示す相対型
  • Value型
  • Iterable
  • 型宣言
  • 型の相互変換


はじめに

PHP における単一の式はそれぞれ、 その値に応じて、以下の組み込み型のうちのひとつを持ちます:

  • null
  • bool
  • int
  • float (浮動小数点数)
  • string
  • array
  • object
  • callable
  • resource

PHP は、動的に型付けを行う言語です。 これは、PHP が実行時に型を決定するため、 デフォルトでは変数の型を指定する必要がないということです。 しかし、 型宣言 を使うことで、 その一部に静的に型を指定することができます。

型は、それに対して行える操作を制限します。 しかし、式や変数に対して、型がサポートしていない操作を行うと、 PHP はその操作をサポートする 型に変換 しようとします。 この処理は、値が使われる文脈によって異なります。 詳細は 型の相互変換 のページを参照ください。

ヒント

型の比較表 も役に立つかもしれません。 さまざまな型の値の比較に関する例があります。

注意: ある式を強制的に他の型として評価させたい場合、 型キャスト を使います。 settype() 関数を変数に対して使うと、 変数の型をその場で変換できます。

式の型と値を知りたい場合は、 var_dump() 関数を使用してください。 式 の型を知りたい場合は、 get_debug_type() を使用してください。 式がある型であるかどうかをチェックするには is_type 関数を代わりに使用してください。

<?php
$a_bool = true; // bool
$a_str = "foo"; // string
$a_str2 = 'foo'; // string
$an_int = 12; // int

echo get_debug_type($a_bool), "\n";
echo get_debug_type($a_str), "\n";

// 数値であれば、4を足す
if (is_int($an_int)) {
$an_int += 4;
}
var_dump($an_int);

// $a_bool が文字列であれば, それをprintする
if (is_string($a_bool)) {
echo "String: $a_bool";
}
?>

上の例の PHP 8 での出力は、このようになります。:

bool
string
int(16)

注意: PHP 8.0.0 より前のバージョンでは、 get_debug_type() が使えません。 代わりに gettype() が使えますが、 この関数は正規化された型の名前を使いません。


型システム

PHP は部分型の関係を満たしつつ(behavioral subtyping)、 名前ベースで一致を調べる型システム(nominal type system) を採用しています。 部分型の関係はコンパイル時にチェックされますが、 型の検証は実行時に動的に行われます。

PHP の型システムは、様々な基本型(atomic type)をサポートしており、 それらを組み合わせてより複雑な型を作ることができます。 そうした複雑な型の一部については、 型宣言 時に記述できます。

基本型

基本型の一部は言語に強く統合されている組み込み型であり、 ユーザー定義の型として再現できません。

基本型の一覧は以下になります:

  • 組み込みの型
    • ヌル(null)
    • スカラー型:
      • 論理値(bool)
      • 整数(int)
      • 浮動小数点数(float)
      • 文字列(string)
    • 配列(array)
    • オブジェクト(object)
    • リソース(resource)
    • never
    • void
    • クラス内での関係を示す相対型: self, parent, static
  • Value型
    • false
    • true
  • ユーザー定義型 (一般的に、クラス型とも呼びます)
    • インターフェイス
    • クラス
    • 列挙型(Enum)
  • callable

複合型

複数の基本型を組み合わせて、複合型を作ることができます。 PHP では、次のやり方で型を組み合わせることができます:

  • (インターフェイスやクラスの)交差型
  • union 型

交差型

交差型 は、宣言した複数のクラス型を(単一ではなく) すべて満たす値を受け入れることができます。 交差型を構成する個別の型は、& 記号で結合します。 よって、型 T, U, V の交差型は T&U&V と書きます。

union 型

union 型は、ひとつではなく、 複数の異なる型を値として受け入れることができます。 union 型を構成する個別の型は、| 記号で結合します。 よって、型 T, U, V の union 型は T|U|V と書きます。 型のひとつが交差型の場合、DNF で記すために 括弧で囲む必要があります。 つまり、T|(X&Y) と書く必要があります。

型のエイリアス

PHP は型のエイリアスをふたつサポートしています。 mixed と iterable です。 それぞれ、 union 型 object|resource|array|string|float|int|bool|null と、Traversable|array に対応します。

注意: PHP は、ユーザー定義の型のエイリアスはサポートしていません。


NULL

null 型は、PHP の unit 型 (意味のある情報を持たないことを示す型) です。 つまり、単一の値 null しか持ちません。

未定義、そして unset() された値は、値 null に解決されます。

文法

null 型の値は一つだけで、 大文字小文字を区別しない定数 null です。

<?php
$var = NULL;
?>

null へのキャスト

警告

この機能は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この機能に頼らないことを強く推奨します。

(unset) $var を使って変数を null にキャストすると、その変数を削除したり値の設定を解除したりは しません。単に null 値を返すだけです。

参考

  • is_null()
  • unset()


論理型 (boolean)

bool 型は、ふたつの値だけを持ち、真偽の値を表します。 この値は、true または false のどちらかになります。

構文

bool リテラルを指定するには、定数 true または false を指定してください。 両方とも大文字小文字を区別しません。

<?php
$foo = True; // 値TRUEを$fooに代入する
?>

通常、bool 型の値を返す演算子を使用してから、 制御構造にその結果を渡します。

<?php
// == は、boolean型を返す演算子
if ($action == "show_version") {
echo "バージョンは1.23です。";
}

// これは冗長
if ($show_separators == TRUE) {
echo "<hr>\n";
}

// 上の例は次のように簡単に書くことができます。
if ($show_separators) {
echo "<hr>\n";
}
?>

boolean への変換

bool に明示的に変換を行うには、キャスト (bool) を使用します。 を使用します。論理型が必要な場合には、値は自動的に bool 型に変換されるので、一般的にはキャストは不要です。 詳細な情報は 型の相互変換 のページを参照ください。

bool に変換する場合、次の値は false とみなされます。

  • boolean の false
  • integer の 0 (ゼロ)
  • float の 0.0 および -0.0 (ゼロ)
  • 空の文字列 ""、 および文字列の "0"
  • 要素の数がゼロである 配列
  • unit 型 NULL (値がセットされていない変数を含む)
  • bool 型へキャストするように動作がオーバーロードされた内部オブジェクト。 例: 属性がない空要素から作成された SimpleXML オブジェクト。

その他の値は全て true とみなされます。 (resource および NAN を含みます)

警告

-1 は、他のゼロでない数と同様に (正負によらず) true とみなされます。

<?php
var_dump((bool) ""); // bool(false)
var_dump((bool) "0"); // 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)
?>


整数

int は、? = {..., -2, -1, 0, 1, 2, ...} という集合です。

参考

  • 浮動小数点数
  • 任意精度整数 / BCMath
  • 任意精度整数 / GMP

構文

整数 (integer) は、10 進数(基数 10)、16 進数 (基数 16)、8 進数 (基数 8) あるいは 2 進数 (基数 2) 表記で指定可能です。オプションで、符号(-または+)を前に付けることが可能です。

8 進数表記を使用する場合、数の前に 0 (ゼロ) を付ける必要があります。 PHP 8.1.0 以降では、数の前に 0o や 0O を付けても 8進数を表記できます。 また、16 進数表記を使用するには、数の前に 0x を付ける必要があります。 2 進数表記を使用する場合、数の前に 0b を付ける必要があります。

PHP 7.4.0 以降では、可読性を向上させるために整数リテラルの桁の間にアンダースコア (_) を含めることができるようになりました。 アンダースコアは PHP の scanner が除去します。

例1 整数リテラル

<?php
$a = 1234; // 10進整数
$a = 0123; // 8進数 (10進数の83と等価)
$a = 0o123; // 8進数 (PHP 8.1.0 以降)
$a = 0x1A; // 16進数 (10進数の26と等価)
$a = 0b11111111; // 2進数 (10進数の255と等価)
$a = 1_234_567; // 10進数 (PHP 7.4.0 以降)
?>

PHP 8.1.0 以降で使用可能な整数リテラルの形式は以下のように定義されています。 (これより前のバージョンでは、8進数のプレフィックス 0o や 0O が許されませんでした。さらに、PHP 7.4.0 より前のバージョンでは、アンダースコアも許されませんでした)

decimal     : [1-9][0-9]*(_[0-9]+)*
            | 0

hexadecimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*

octal       : 0[oO]?[0-7]+(_[0-7]+)*

binary      : 0[bB][01]+(_[01]+)*

integer     : decimal
            | hexadecimal
            | octal
            | binary

整数のサイズはプラットフォームに依存しますが、 約 20 億 (32 ビット符号付) が一般的な値です。 64 ビットプラットフォームでの通常の最大値は、およそ 9*10^18 (900京) になります。 PHP は符号無し整数をサポートしていません。 整数のサイズは定数 PHP_INT_SIZE で、 整数の最大値は定数 PHP_INT_MAX で、 整数の最小値は定数 PHP_INT_MIN で決まります。

整数のオーバーフロー

int型の範囲外の数を指定した場合、かわりに floatとして解釈されます。また、結果が int型の範囲外の数となるような計算を行うと floatが代わりに返されます。

例2 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)
?>

例3 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 には整数の割り算を行う演算子はありません。 整数の割り算を行うには、intdiv() 関数を使って下さい。 1/2 は float 型の 0.5 になります。 0 に近い方向の整数値に値を丸めるためにキャストを使用することができ、 また、round() 関数を使用することもできます。

<?php
var_dump(25/7); // float(3.5714285714286)
var_dump((int) (25/7)); // int(3)
var_dump(round(25/7)); // float(4)
?>

整数への変換

int に値を明示的に変換するには、キャスト (int) または (integer) のどちらかを使用してください。しかし、多くの場合、演算子、関数、制御構造が int 引数を必要とする場合、値は自動的に変換されるため、 キャストを使用する必要はありません。 関数 intval() を用いて値を整数に変換することも可能です。

resource を int に変換すると、その結果は一意なリソース番号となります。 これは、その resource に対して PHP が実行時に割り当てた番号です。

型の相互変換 を参照ください。

booleans から

false は、0 (ゼロ) となり、 true は、1 となります。

浮動小数点数から

float から整数に変換する場合、その数はゼロのほうに丸められます。 PHP 8.1.0 以降では、精度を損なうことになる float から int への暗黙の変換は推奨されなくなり、警告が発生します。

<?php
function foo($value): int {
return $value;
}
var_dump(foo(8.1)); // PHP 8.1.0 以降では "Deprecated: Implicit conversion from float 8.1 to int loses precision"
var_dump(foo(8.1)); // PHP 8.1.0 より前のバージョンでは 8
var_dump(foo(8.0)); // PHP 8.1.0 より前でもあとでも、8
var_dump((int)8.1); // PHP 8.1.0 より前でもあとでも、8
var_dump(intval(8.1)); // PHP 8.1.0 より前でもあとでも、8
?>

float が整数の範囲 (通常は、32 ビットプラットフォームでは +/- 2.15e+9 = 2^31、64 ビットプラットフォームでは +/- 9.22e+18 = 2^63 ) を越える場合、結果は undefined となります。これは、 その float が正しい整数の結果を得るために十分な精度を得られなかったからです。 この場合、警告も通知も発生しません!

注意:

NaN や無限大を int にキャストした結果は、常にゼロとなります。

警告

未知の端数を int にキャストしないでください。 この場合、予期しない結果となることがあります。

<?php
echo (int) ( (0.1+0.7) * 10 ); // 7が出力されます!
?>

より詳細な情報については、 float の精度に関する注意を参照ください。

文字列から

文字列が 数値形式の文字列 の場合は、対応する整数値に解決されます。 そうでない場合は、ゼロ (0) に変換されます。

NULL から

null は、常に0に変換されます。

他の型から

警告

整数への変換の動作は、他の型については定義されません。 現在の動作は、その値がまず 論理値に変換された 場合と同じです。しかし、この動作は予告なく変更されることがありえるので、 これを前提にしてはいけません。


浮動小数点数

浮動小数点数 (あるいは "float", "double", "実数") は、次の構文により指定できます。

<?php
$a = 1.234;
$b = 1.2e3;
$c = 7E-10;
$d = 1_234.567; // PHP 7.4.0 以降
?>

PHP 7.4.0 以降の規約(これより前のバージョンでは、アンダースコアは許されませんでした):

LNUM          [0-9]+(_[0-9]+)*
DNUM          ({LNUM}?"."{LNUM}) | ({LNUM}"."{LNUM}?)
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 関数を代わりに使用してください。

もっと「シンプルな」説明が欲しければ、» floating point guide を見るといいでしょう。"Why don't my numbers add up? (なんで数字が足されないの?)" というタイトルが付いています。

float への変換

文字列から float への変換

文字列が 数値形式の文字列 の場合、対応する float の値に解決されます。 そうでない場合、ゼロ(0)に変換されます。

他の型から float への変換

文字列以外の値については、 まず最初に int に変換された後、 float に変換されます。 詳細は 整数への変換 を参照ください。

注意:

型によっては、int に変換したときの動作が未定義のものがあります。 この場合、float に変換する場合の動作も未定義です。

float の比較

先ほど警告したように、浮動小数点数値が等しいかどうかを比較するのには問題があります。 これは、浮動小数点数値の内部表現形式に起因するものです。 しかし、この制限を回避して浮動小数点数値の値を比較する方法もあります。

浮動小数点数値が等しいかどうかを調べるには、比較時の丸め誤差の上界を用います。 この値は計算機イプシロンあるいは丸め単位と呼ばれ、 計算時に扱える最小の差分を表します。

$a と $b は、精度 5 桁では等しくなります。

<?php
$a = 1.23456789;
$b = 1.23456780;
$epsilon = 0.00001;

if(abs($a-$b) < $epsilon) {
echo "true";
}
?>

NaN

数値演算の結果が、定数 NAN で表される値になることがあります。 この定数は、浮動小数点演算における未定義の値あるいは表現不能な値を表します。 この値を他の値と比較すると、緩やかな比較および厳密な比較のいずれでも結果は false になります。 自分自身と比較した場合も含みますが、true と比較した場合は除きます。

NAN はさまざまな値の数を表すものなので、 NAN を他の値と比較してはいけません。たとえ自分自身とであってもです。 チェックをする場合には、かわりに is_nan() を使います。


文字列

string は、文字が連結されたものです。PHP では、 文字は 1 バイトと同じです。つまり、256 個の異なる文字を使用可能です。 これは、PHP が Unicode をネイティブにサポートしていないことも意味します。 文字列型の詳細を参照ください。

注意: 32bit ビルドでは、 文字列の最大長は 2GB (2147483647 バイト) です。

構文

文字列リテラルは、4 つの異なる方法で指定することが可能です。

  • 引用符
  • 二重引用符
  • ヒアドキュメント構文
  • Nowdoc 構文

引用符

文字列を指定する最も簡単な方法は、引用符 (文字 ') で括ることです。

引用符をリテラルとして指定するには、バックスラッシュ (\) でエスケープする必要があります。 バックスラッシュをリテラルとして指定するには、二重 (\\) にします。 それ以外の場面で登場するバックスラッシュは、すべてバックスラッシュそのものとして扱われます。 つまり、\r や \n といったおなじみのエスケープシーケンスを書いても特別な効果は得られず、 書いたままの形式で出力されます。

注意: ダブルクォート 構文や ヒアドキュメント構文 とは異なり、 変数と特殊文字のエスケープシーケンスは、 引用符 (シングルクオート) で括られた文字列にある場合には展開されません。

<?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))
\e | エスケープ (ESC あるいはアスキーの 0x1B (27))
\f | フォームフィード (FF またはアスキーの 0x0C (12))
\\ | バックスラッシュ
\$ | ドル記号
\" | 二重引用符
\[0-7]{1,3} | 8進数: 正規表現 [0-7]{1,3} にマッチする文字シーケンスは、8 進数表記の 1 文字 (例:. "\101" === "A") です。 正規表現にマッチする文字シーケンスは、8 進数表記の 1 文字です。 1 バイトに収まらない部分は、何もメッセージを出さずにオーバーフローします (例: "\400" === "\000") 。
\x[0-9A-Fa-f]{1,2} | 16進数: 正規表現 [0-9A-Fa-f]{1,2} にマッチする文字シーケンスは、16 進数表記の 1 文字(例: "\x41" === "A")です。
\u{[0-9A-Fa-f]+} | Unicode: 正規表現 [0-9A-Fa-f]+ にマッチする文字シーケンスは、Unicode のコードポイントです。 そのコードポイントの UTF-8 表現を文字列として出力します。 シーケンスを波括弧で囲む必要があります。例 "\u{41}" === "A"

繰り返しますが、この他の文字をエスケープしようとした場合には、 バックスラッシュも出力されます!

しかし、二重引用符で括られた文字列で最も重要なのは、 変数名が展開されるところです。詳細は、文字列のパースを参照ください。

ヒアドキュメント

文字列を区切る別の方法としてヒアドキュメント構文 ("<<<") があります。この場合、ある ID (と、それに続けて改行文字) を <<< の後に指定し、文字列を置いた後で、 同じ ID (終端ID) を括りを閉じるために置きます。

終端ID は、スペースまたはタブでインデントできます。 その場合、インデントされた部分は文字列の全ての行から取り除かれます。 PHP 7.3.0 より前のバージョンでは、 終端ID はその行の最初のカラムから始めなければ いけませんでした。

また、終端ID は、PHP の他のラベルと同様の命名規則に従う必要があります。 つまり、英数字およびアンダースコアのみを含み、 数字でない文字またはアンダースコアで始まる必要があります。

例1 PHP 7.3.0 以降での、基本的なヒアドキュメントの使い方

<?php
// 終端IDをインデントしない場合
echo <<<END
 a
b
c
\n
END;
// 終端IDを4つのスペースでインデントする場合
echo <<<END
 a
b
c
 END;

上の例の PHP 7.3 での出力は、このようになります。

      a
     b
    c
  a
 b
c

終端ID が、文字列のいずれかの行より奥にインデントされている場合、 ParseError がスローされます。

例2 終端ID は 文字列本体よりも奥にインデントしてはいけない

<?php
echo <<<END
 a
b
c
 END;

上の例の PHP 7.3 での出力は、このようになります。

PHP Parse error:  Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4

終端ID をインデントする場合、 インデントに使う文字として、タブまたはスペースが使えます。 しかし、終端ID、および (終端ID までの)文字列の本体どちらであっても、 インデントする際にタブとスペースを混ぜては いけません。 混ぜた場合、 ParseError がスローされます。 インデントに使う文字に制限があるのは、 タブとスペースを混ぜてしまうと可読性が損なわれるためです。

例3 文字列本体 や 終端ID のインデントに違う文字を使う

<?php
// 以下のコードはいずれも動作しません。
// 文字列本体(スペース) と 終端ID(タブ) とで、異なる文字でインデントする
{
echo <<<END
 a
 END;
}
// 文字列本体に、タブとスペースを混ぜてインデントする
{
echo <<<END
 a
 END;
}
// 終端IDのインデントに、スペースとタブを混ぜる
{
echo <<<END
 a
 END;
}

上の例の PHP 7.3 での出力は、このようになります。

PHP Parse error:  Invalid indentation - tabs and spaces cannot be mixed in example.php line 8

文字列本体の後に置かれる 終端ID の後に、 セミコロンや改行を続ける必要はありません。 たとえば、次のようなコードが PHP 7.3.0 以降で動作します:

例4 終端ID の後に式を継続する

<?php
$values = [<<<END
a
b
c
END, 'd e f'];
var_dump($values);

上の例の PHP 7.3 での出力は、このようになります。

array(2) {
  [0] =>
  string(11) "a
  b
    c"
  [1] =>
  string(5) "d e f"
}
警告

終端ID が行のはじめに見つかった場合、 それが別の単語の一部かどうかにかかわらず、 それが終端IDと見なされ、 ParseError が起きる可能性があります。

例5 文字列本体に 終端ID が含まれると、ParseError が起きがち

<?php
$values = [<<<END
a
b
END ING
END, 'd e f'];

上の例の PHP 7.3 での出力は、このようになります。

PHP Parse error:  syntax error, unexpected identifier "ING", expecting "]" in example.php on line 6

この問題を避けるために、 次のようなシンプルなルールに従っておくと安全です: 文字列本体に出現するテキストを、終端ID として採用しない

警告

PHP 7.3.0 より前のバージョンで注意すべき非常に重要な点は、 終端ID がある行には、セミコロン (;) 以外の他の文字が含まれていてはいけなかったことです。 これは、特に ID はインデントしてはならないということ、 セミコロンの前に空白やタブを付けてはいけないことを意味していました。 終端ID の前の最初の文字は、使用するオペレーティングシステムで定義された 改行である必要があることにも注意を要します。 これは、UNIX システムでは macOS を含め \n となります。 最後の区切り文字の後にもまた、改行を入れる必要があります。

この規則が破られて 終端ID が "clean" でない場合、 終端ID と認識されず、PHP はさらに終端 ID を探し続けます。 適当な 終端ID がみつからない場合、 スクリプトの最終行でパースエラーが発生します。

例6 PHP 7.3.0 より前のバージョンでの間違った例

<?php
class foo {
public $bar = <<<EOT
bar
 EOT;
}
// 識別子はインデントしてはいけません
?>

例7 PHP 7.3.0 より前のバージョンでも有効な例

<?php
class foo {
public $bar = <<<EOT
bar
EOT;
}
?>

変数を含んでいるヒアドキュメントは、クラスのプロパティの初期化に用いることはできません。

ヒアドキュメントは二重引用符を使用しませんが、 二重引用符で括られた文字列と全く同様に動作します。 しかし、この場合でも上記のリストでエスケープされたコードを使用することも可能です。 変数は展開されますが、文字列の場合と同様に ヒアドキュメントの内部で複雑な変数を表わす場合には注意が必要です。

例8 ヒアドキュメントで文字列を括る例

<?php
$str = <<<EOD
Example of string
spanning multiple lines
using heredoc syntax.
EOD;

/* 変数を使用するより複雑な例 */
class foo
{
var $foo;
var $bar;

function __construct()
{
$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

ヒアドキュメント構文を用いて、 関数の引数にデータを渡すこともできます。

例9 ヒアドキュメントを引数に使用する例

<?php
var_dump(array(<<<EOD
foobar!
EOD
));
?>

static変数やクラスのプロパティ/定数は、 ヒアドキュメント構文で初期化することができます。

例10 ヒアドキュメントを用いた静的な値の初期化

<?php
// static 変数
function foo()
{
static $bar = <<<LABEL
Nothing in here...
LABEL;
}

// クラスのプロパティ/定数
class foo
{
const BAR = <<<FOOBAR
Constant example
FOOBAR;

public $baz = <<<FOOBAR
Property example
FOOBAR;
}
?>

ヒアドキュメントの宣言をダブルクォートで囲むこともできます。

例11 ヒアドキュメントでのダブルクォート

<?php
echo <<<"FOOBAR"
Hello World!
FOOBAR;
?>

Nowdoc

Nowdoc はヒアドキュメントと似ていますが、 ヒアドキュメントがダブルクォートで囲んだ文字列として扱われるのに対して、 Nowdoc はシングルクォートで囲んだ文字列として扱われます。 Nowdoc の使用方法はヒアドキュメントとほぼ同じですが、 その中身について パース処理を行いません。 PHP のコードや大量のテキストを埋め込む際に、 エスケープが不要になるので便利です。この機能は、SGML の <![CDATA[ ]]> (ブロック内のテキストをパースしないことを宣言する) と同じようなものです。

Nowdoc の書き方は、ヒアドキュメントと同じように <<< を使用します。 しかし、その後に続く識別子をシングルクォートで囲んで <<<'EOT' のようにします。 ヒアドキュメントの識別子に関する決まりがすべて Nowdoc の識別子にも当てはまります。特に 終端ID の書き方に関する決まりに注意しましょう。

例12 Nowdoc による文字列のクォートの例

<?php
echo <<<'EOD'
Example of string spanning multiple lines
using nowdoc syntax. Backslashes are always treated literally,
e.g. \\ and \'.
EOD;

上の例の出力は以下となります。

Example of string spanning multiple lines
using nowdoc syntax. Backslashes are always treated literally,
e.g. \\ and \'.

例13 変数がある場合の、Nowdoc による文字列のクォートの例

<?php
/* 変数を使った、より複雑な例 */
class foo
{
public $foo;
public $bar;

function __construct()
{
$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

例14 静的なデータの例

<?php
class foo {
public $bar = <<<'EOT'
bar
EOT;
}
?>

変数のパース

文字列が二重引用符で括られるかヒアドキュメントで指定された場合、 その中の変数はパースされます。

構文の型には、単純な構文と 複雑な 構文の 2 種類があります。簡単な構文は、最も一般的で便利です。 この構文では、変数や配列の値、オブジェクトのプロパティを、 簡単に文字列に埋め込むことができます。

複雑な構文は、式を波括弧で括ることにより認識されます。

簡単な構文

ドル記号 ($) を見付けると、 パーサは、有効な変数名を形成することが可能な最長のトークンを取得します。 変数名の終りを明示的に指定したい場合は、変数名を波括弧で括ってください。

<?php
$juice = "apple";

echo "He drank some $juice juice." . PHP_EOL;

// 意図しない動作をします。"s" は、変数名として有効な文字です。よって、変数は $juices を参照しています。$juice ではありません。
echo "He drank some juice made of $juices." . PHP_EOL;

// 参照する変数名を波括弧で囲むことで、変数名の終端を明示的に指定しています。
echo "He drank some juice made of {$juice}s.";

?>

上の例の出力は以下となります。

He drank some apple juice.
He drank some juice made of .
He drank some juice made of apples.

同様に、配列添字とオブジェクトのプロパティをパースすることも可能です。 配列添字の場合、閉じ角括弧 (]) は添字の終りを意味します。 シンプルな変数の場合と同じ規則が、オブジェクトのプロパティに対しても適用されます。

例15 簡単な構文の例

<?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 $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 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 .

PHP 7.1.0 以降では、 負の 数値インデックスもサポートされました。

例16 負の数値インデックス

<?php
$string = 'string';
echo "The character at index -2 is $string[-2].", PHP_EOL;
$string[-3] = 'o';
echo "Changing the character at index -3 to o gives $string.", PHP_EOL;
?>

上の例の出力は以下となります。

The character at index -2 is n.
Changing the character at index -3 to o gives strong.

より複雑な場合は、複雑な構文を使用する必要があります。

複雑な (波括弧) 構文

この構文が「複雑(complex)な構文」と呼ばれているのは、 構文が複雑であるからではなく、 この方法では複雑な式を含めることができるからです。

どんなスカラー変数、配列の要素あるいはオブジェクトのプロパティの文字列表現であっても この構文で含めることができます。 文字列の外側に置く場合と同様に式を書き、これを { と } の間に含めてください。'{' はエスケープすることができないため、 この構文は $ が { のすぐ後に続く場合にのみ認識されます (リテラル "{$" を指定するには、"{\$" を使用してください)。 以下のいくつかの例を見ると理解しやすくなるでしょう。

<?php
// すべてのエラーを表示します
error_reporting(E_ALL);

$great = 'fantastic';

// うまく動作しません。出力: This is { fantastic}
echo "This is { $great}";

// うまく動作します。出力: This is fantastic
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 という名前の定数を探し、
// 見つからない場合はエラーをスローします。
// 定数が見つかった場合は、その値('foo' そのものではない)
// を配列のインデックスとして使います。
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()}";

// 動作しません。出力: C:\folder\{fantastic}.txt
echo "C:\folder\{$great}.txt"
// 動作します。出力: C:\folder\fantastic.txt
echo "C:\\folder\\{$great}.txt"
?>

文字列内で、変数を使ってクラスのプロパティにアクセスすることもできます。 このような構文を使います。

<?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.

注意:

{$} の内部における 関数やメソッドのコール、static なクラス変数、クラス定数からアクセスする値は、 文字列が定義されたスコープにおける変数名として解釈します。 ひとつの波括弧 ({}) では、 関数やメソッドの戻り値、クラス定数やstaticなクラス変数の値にはアクセスできません。

<?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() が使えます。

注意: PHP 7.1.0 以降では、負の文字列オフセットにも対応するようになりました。 これは、文字列の末尾からのオフセットを表します。 以前のバージョンでは、負のオフセットで読み込もうとすると E_NOTICE が発生し (空文字列を返します)、負のオフセットで書き込もうとすると E_WARNING が発生していました (文字列には何も手が加えられません)。

注意: PHP 8.0.0 より前のバージョンでは、 $str{42} のように波括弧を使用してアクセスすることもできました。 この文法は PHP 7.4.0 以降は非推奨になり、 PHP 8.0.0 以降はサポートされなくなっています。

警告

範囲外のオフセットに書き込んだ場合は、空いた部分に空白文字が埋められます。 整数型以外の型は整数型に変換されます。 無効なオフセット形式を指定した場合は E_WARNING を発行します。 文字列を代入した場合は最初の文字だけを使用します。 PHP 7.1.0 以降では、空の文字列を代入すると fatal エラーが発生するようになりました。 これまでのバージョンでは、NULL バイトが代入されていました。

警告

内部的には、PHP の文字列はバイト配列です。 そのため、角括弧を使った配列形式での文字列へのアクセスは、 マルチバイト対応ではありません。この方法は、 ISO-8859-1 のようなシングルバイトエンコーディングの文字列に対してだけしか使えません。

注意: PHP 7.1.0 以降では、空の文字列に空のインデックス演算子を適用すると fatal エラーが発生するようになりました。 これまでのバージョンではエラーにならず、空の文字列が配列に変換されていました。

例17 文字列の例

<?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';

?>

文字列のオフセットは整数あるいは整数と見なせる文字列に限られます。 それ以外の場合は警告が発生します。

例18 不正な文字列のオフセットの例

<?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']));
?>

上の例の出力は以下となります。

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)

注意:

その他の型の変数 (配列や、適切なインターフェイスを実装したオブジェクトを除く) に対して [] や {} でアクセスすると、何もメッセージを出さずに単に null を返します。

注意:

文字列リテラル内の文字に対して [] や {} でアクセスすることができます。

注意:

文字列リテラル内の文字に対して、 {} を使ってアクセスする機能は、 PHP 7.4 で非推奨になり、PHP 8.0 で削除されました。

便利な関数および演算子

文字列は、'.' (ドット) 結合演算子で結合することが可能です。'+' (加算) 演算子はこの例では出てこないことに注意してください。詳細については 文字列演算子 を参照ください。

文字列の修正を行う場合には、便利な関数がたくさん用意されています。

一般的な関数については、文字列関数の節 を参照ください。高度な検索/置換を行う関数については Perl 互換の正規表現関数 を参照ください。

URL 文字列用関数や文字列の暗号化/ 復号用の関数 (Sodium および Hash) もあります。

最後に、探しているものがまだ見付からない場合には、 文字型の関数も参照ください。

文字列への変換

(string) キャストや strval() 関数を使って変数を文字列へ変換することができます。 文字列型を必要とする式のスコープにおいて、文字列への変換は自動的に行われます。 echo や print 関数を使うとき、 あるいは可変変数を文字列を比較するときにこの自動変換が行われます。 マニュアルの型 と 型の相互変換 の項を読むとわかりやすいでしょう。 settype()も参照ください。

bool の true は文字列の "1" に、 false は "" (空文字列) に変換されます。 これにより boolean と文字列の値を相互に変換することができます。

int (整数) や浮動小数点数 (float) は その数値の数字として文字列に変換されます (指数の表記や浮動小数点数を含めて)。 浮動小数点数は、指数表記 (4.1E+6) を使用して変換されます。

注意:

PHP 8.0.0 以降では、小数点を表す文字は常にピリオド (".") です。 それより前のバージョンでは、 スクリプトのロケール (LC_NUMERIC カテゴリ) によって決まります。 setlocale() を参照ください。

配列は常に "Array" という文字列に変換されるので、 array の中を見るために echo や print を使ってダンプさせることはできません。 一つの要素を見るためには、echo $arr['foo'] のようにしてください。内容の全てをダンプ/見るためには以降の TIP をご覧ください。

object を string へ変換するには、 マジック・メソッド __toString を使用してください。

リソースは常に "Resource id #1" という文字列に変換されます。1 は実行中の PHP によって割り当てられる resource の番号です。 この文字列の構造に依存したコードを書いてはいけません (この構造は変わる可能性があります) が、スクリプトの実行中 (ウェブのリクエストや CLI プロセスの処理中) は、指定したリソースに対してこの文字列が一意に割り当てられることが保証されます。 他のリソースで同じ文字列が再利用されることはありません。 リソースの型を知るためには get_resource_type() を使用してください。

null は常に空文字列に変換されます。

以上に述べたように、配列、オブジェクト、リソースをプリントアウトしても その値に関する有益な情報を得られるわけではありません。 デバッグのために値を出力するのによりよい方法が知りたければ、 print_r() や var_dump() を参照ください。

PHP 変数を恒久的に保存するための文字列に変換することもできます。 この方法はシリアライゼーションと呼ばれ、 serialize() 関数によって実現できます。

文字列型の詳細

PHP における文字列型は、バイトの配列と整数値 (バッファ長) で実装されています。 バイト列を文字列に変換する方法については何の情報も持っておらず、完全にプログラマ任せとなっています。 文字列を構成する値には何の制限もありません。特に気をつけるべきなのは、 値 0 のバイト (いわゆる "NUL バイト") を文字列内のどの部分にでも使えるという点です (しかし、このマニュアル上で「バイナリセーフではない」とされている一部の関数では、 受け取った文字列をライブラリに渡すときに NUL バイト以降を無視することがあります)。

PHP の文字列型の正体を知ってしまえば、なぜ PHP には「バイト型」が存在しないのかもわかります。 つまり、文字列型がその役割を受け持っているのです。テキスト以外のデータ、 たとえばネットワークソケットから読み込んだ任意のデータを返す関数も、 文字列で値を返します。

PHP が文字列に対して特定のエンコーディングを強制しないのなら、 いったいどのようにして文字列リテラルをエンコードしているのでしょう? たとえば、文字列 "a" と同等なのは "\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() を参照ください) を使うけれども、 処理はバイト単位で行う関数もあります。
  • 最後に、文字列が特定のエンコーディング (たいていは UTF-8) であることを前提としている関数があります。 intl の関数や PCRE の関数 (u 修飾子を使う場合のみ) の多くがこのタイプになります。

結局、Unicode を使うプログラムをきちんと書くには、 うまく動かない関数を使わないよう注意するしかないということです。 特にデータを破壊してしまう可能性のある関数の使用は避け、 きちんと動作する関数を使うようにしましょう。 intl や mbstring の関数を選択するとよいでしょう。 しかし、Unicode をまともに扱える関数を使うというのは単なる始まりに過ぎません。 たとえ関数側で Unicode を扱う機能があったとしても、 Unicode の仕様に関する知識は不可欠です。 たとえば、世の中には大文字と小文字しか存在しないという思い込みで作ったプログラムは、 うまく動かない可能性があります。


数値形式の文字列

PHP の 文字列 は、 int や float と解釈できる場合は 数値と見なされます。

PHP 8.0.0 以降の正式な仕様は下記の通りです:

WHITESPACES      \s*
LNUM             [0-9]+
DNUM             ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

PHP は 先頭から始まる 数値形式の文字列という概念も持っています。 これは、数値形式の文字列から始まり、その後に任意の文字が続く文字列です。

注意:

文字 E (大文字小文字を区別しません) が含まれる文字列のうち、 その文字で数値を区切っている場合、科学的記法で記された数値とみなされます。 この場合、予期しない結果が発生するかもしれません。

<?php
var_dump("0D1" == "000"); // false, "0D1" は科学的記法ではありません
var_dump("0E1" == "000"); // true, "0E1" は 0 * (10 ^ 1), または 0
var_dump("2E1" == "020"); // true, "2E1" は 2 * (10 ^ 1), または 20
?>

数値の文脈で使われる文字列

文字列が数値として評価される必要がある場合 (例: 算術演算や、int 型の宣言がある場合など) は、次のステップを踏むことで結果が決まります:

  1. 文字列が数値の場合、かつそれが int 型の範囲 (PHP_INT_MAX で定義されています) に含まれる場合、int に解決されます。 そうでない場合、float に解決されます。
  2. 文脈が 先頭から始まる数値形式の文字列を許す場合、 かつ値が文字列の場合は、次のように解決されます: 文字列の先頭部分が数値形式の文字列、かつそれが int 型の範囲 (PHP_INT_MAX で定義されています) に含まれる場合、int に解決されます。 そうでない場合、float に解決されます。 それに加えて、エラーレベル E_WARNING が発生します。
  3. 文字列が数値でない場合、 TypeError がスローされます。

PHP 8.0.0 より前の振る舞い

PHP 8.0.0 より前のバージョンでは、 先頭に ホワイトスペースがある場合にだけ、 文字列は数値と見なされていました。 数値の後に ホワイトスペースがある場合は、 その文字列は 先頭から始まる 数値形式の文字列とみなされていました。

PHP 8.0.0 より前のバージョンでは、 文字列が数値の文脈で使われる場合、既に述べたステップと同じ処理を行いますが、 以下の違いがあります:

  • 先頭から始まる数値形式の文字列の場合、 E_WARNING ではなく、 E_NOTICE が発生していました。
  • 文字列が数値でない場合、 E_WARNING が発生し、 0 が返されていました。
PHP 7.1.0 より前のバージョンでは、 E_NOTICE も E_WARNING も発生していませんでした。

<?php
$foo = 1 + "10.5"; // $foo は float (11.5)
$foo = 1 + "-1.3e3"; // $foo は float (-1299)
$foo = 1 + "bob-1.3e3"; // PHP 8.0.0 以降は TypeError。それより前は、$foo は integer (1)
$foo = 1 + "bob3"; // PHP 8.0.0 以降は TypeError。それより前は、$foo は integer (1)
$foo = 1 + "10 Small Pigs"; // PHP 8.0.0 では $foo は integer (11) で、かつ E_WARNING。それより前は E_NOTICE
$foo = 4 + "10.2 Little Piggies"; // PHP 8.0.0 では $foo は float (14.2) で、かつ E_WARNING。それより前は E_NOTICE
$foo = "10.0 pigs " + 1; // PHP 8.0.0 では $foo は float (11) で、かつ E_WARNING。それより前は E_NOTICE
$foo = "10.0 pigs " + 1.0; // PHP 8.0.0 では $foo は float (11) で、かつ E_WARNING。それより前は E_NOTICE
?>


配列

PHP の配列は、実際には順番付けられたマップです。マップは型の一種で、 値をキーに関連付けます。 この型は、さまざまな使い道にあわせて最適化されます。 配列としてだけでなく、リスト (ベクター)、 ハッシュテーブル (マップの実装の一つ)、辞書、コレクション、スタック、 キュー等として使用することが可能です。 PHP の配列には他の PHP 配列を値として保持することができるため、 非常に簡単にツリー構造を表現することが可能です。

これらのデータ構造に関する説明は本マニュアルの範囲を超えるので省略しますが、 各々について、少なくとも一つは例を示します。 この分野は広範囲にまたがり、さまざまな文献が存在します。 より詳細な情報については、それらの文献を参照ください。

構文

array() で指定

配列 は、言語に組み込まれた array() で作成することが可能です。この構造は、 特定の数のカンマで区切られた キー => 値 の組を引数とします。

array(
    key  => value,
    key2 => value2,
    key3 => value3,
    ...
)

最後の要素のあとのカンマは、書いても書かなくてもかまいません。 配列を一行で定義する場合は、ふつうは最後のカンマを省略します。つまり、 array(1, 2) のほうが array(1, 2, ) よりおすすめだということです。 しかし複数行で定義する場合は、最後のカンマをつけることが一般的です。 そうしておけば、配列の最後に要素を追加するのが容易になるからです。

注意:

array() を [] で置き換えることが出来る、配列の短縮構文も使えます。

例1 シンプルな配列定義

<?php
$array = array(
"foo" => "bar",
"bar" => "foo",
);

// 配列の短縮構文
$array = [
"foo" => "bar",
"bar" => "foo",
];
?>

key は、整数 または 文字列です。 value には任意の型を指定できます。

さらに、次のような key のキャストが発生します。

  • 10 進数の int として妥当な形式の String は、 数値の前に + 記号がついていない限り、 int 型にキャストされます。 つまり、キーに "8" を指定すると、実際には 8 として格納されるということです。一方 "08" はキャストされません。これは十進数として妥当な形式ではないからです。
  • floats もまた int にキャストされます。つまり、 小数部分は切り捨てられるということです。たとえばキーに 8.7 を指定すると、実際には 8 として格納されます。
  • bool も int にキャストされます。つまり、 キーに true を指定すると実際には 1 に格納され、 同様にキーを false とすると実際には 0 となります。
  • Null は空文字列にキャストされます。つまり、キーに null を指定すると、実際には "" として格納されます。
  • array や object は、キーとして使えません。 キーとして使おうとすると Illegal offset type という警告が発生します。

配列の宣言時に同じキーで複数の要素を指定すると、 最後に指定したものがそれまでの値を上書きします。

例2 型のキャストと値の上書きの例

<?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 つだけで、 同じ配列で整数のインデックスと文字列のインデックスを同時に使えます。

例3 整数と文字列のキーの混在例

<?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 を加えた値を使います。

例4 数値添字配列でキーを省略する例

<?php
$array = array("foo", "bar", "hello", "world");
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(5) "hello"
  [3]=>
  string(5) "world"
}

一部の要素にだけキーを指定することもできます。

例5 一部の要素にだけキーを指定する例

<?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 だからです。

例6 複雑な型のキャストと上書きの例

以下の例は、型のキャストされた時と、要素が上書きされる時の全ての場合を示しています。

<?php
$array = array(
1 => 'a',
'1' => 'b', // 値 "a" は "b" で上書きされます。
1.5 => 'c', // 値 "b" は "c" で上書きされます。
-1 => 'd',
'01' => 'e', // この値は数値文字列ではないので、キー1を上書きしません
'1.5' => 'f', // この値は数値文字列ではないので、キー1を上書きしません
true => 'g', // 値 "c" は "g" で上書きされます。
false => 'h',
'' => 'i',
null => 'j', // 値 "i" は "j" で上書きされます。
'k', // 値 "k" にはキー2が割り当てられます。なぜなら、これより前のキーの最大値は1だからです。
2 => 'l', // 値 "k" は "l" で上書きされます。
);

var_dump($array);
?>

上の例の出力は以下となります。

array(7) {
  [1]=>
  string(1) "g"
  [-1]=>
  string(1) "d"
  ["01"]=>
  string(1) "e"
  ["1.5"]=>
  string(1) "f"
  [0]=>
  string(1) "h"
  [""]=>
  string(1) "j"
  [2]=>
  string(1) "l"
}

角括弧構文による配列要素へのアクセス

配列の要素へのアクセスには 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 8.0.0 より前のバージョンでは、 配列の要素にアクセスするときに、 角括弧と波括弧がどちらも同じ意味で使えていました。 (つまり、この例で $array[42] と $array{42} は同じものを表しているということです)。 波括弧で配列にアクセスする文法は、 PHP 7.4.0 以降は非推奨になり、 PHP 8.0.0 以降はサポートされなくなっています。

例8 配列のデリファレンス

<?php
function getArray() {
return array(1, 2, 3);
}

$secondElement = getArray()[1];
?>

注意:

配列に定義されていないキーへアクセスしたときの挙動は、 未定義の変数にアクセスしたときと同じです。 つまり、E_WARNING レベルの警告 (PHP 8.0.0 より前のバージョンでは E_NOTICE) が発生し、結果が null になります。

注意:

配列で文字列以外のスカラー値をデリファレンスした場合は、 返される結果は null となります。 PHP 7.4.0 より前のバージョンでは、何もエラーは発生しませんでした。 PHP 7.4.0 以降では、E_NOTICE が発生します。 PHP 8.0.0 以降では、E_WARNING が発生します。

角括弧構文で作成/修正

明示的に値を設定することにより、既存の配列を修正することも可能です。

これは、角括弧の中にキーを指定し、配列に値を代入することにより行います。 キーを省略することも可能です。この場合、空の角括弧 ("[]") の変数名として追加してください。

$arr[キー] = 値;
$arr[] = 値;
// キー は 文字列 または
// 整数のどちらかです。
// 値 の型は、何でもかまいません。

$arr がまだ存在しない場合、 あるいは null や false に設定されている場合は、 新しく配列を作成します。 つまり、これは配列を作成する方法のひとつでもあります。 とはいえ、この方法を使うことはおすすめしません。なぜなら、既に $arr に何らかの値 (リクエスト変数からの文字列など) が入っている場合にはその値がそのまま残り、 [] が実際には 文字列アクセス演算子 を表してしまうからです。 変数を初期化するときには、直接代入するほうがよいでしょう。

注意: PHP 7.1.0 以降では、文字列に空のインデックス演算子を適用すると fatal エラーが発生するようになりました。 これまでのバージョンではエラーにならず、文字列が配列に変換されていました。

注意: PHP 8.1.0 以降では、 false に設定している値から新しく配列を作成することは推奨されません。 null や未定義の値から配列を新しく作成することはまだ許可されています。

ある値を変更するには、 新しい値に値を代入します。特定のキー/値の組を削除したい場合には、 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
)

配列の分解

配列は、言語構造 [] (PHP 7.1.0 以降) または、list() を使って分解することができます。 これらの言語構造は、 配列を個別の値に分解する用途に使えます。

<?php
$source_array = ['foo', 'bar', 'baz'];

[$foo, $bar, $baz] = $source_array;

echo $foo; // "foo" を出力します。
echo $bar; // "bar" を出力します。
echo $baz; // "baz" を出力します。
?>

これは、多次元配列を foreach で反復処理しながら分解する用途に使えます。

<?php
$source_array = [
[1, 'John'],
[2, 'Jane'],
];

foreach ($source_array as [$id, $name]) {
// $id と $name を使うロジックをここに書きます
}
?>

変数が与えられない配列の要素は無視されます。 配列の分解は、常にインデックス 0 から始まります。

<?php
$source_array = ['foo', 'bar', 'baz'];

// インデックス2の要素を、変数 $baz に代入します
[, , $baz] = $source_array;

echo $baz; // "baz" を出力します。
?>

PHP 7.1.0 以降では、 連想配列も分解できるようになりました。 数値をキーとした配列の右側の要素を、 インデックスを明示的に指定することで簡単に選択できるようになっています。

<?php
$source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];

// インデックス 'baz' の要素を、変数 $three に代入します。
['baz' => $three] = $source_array;

echo $three; // 3 を出力します。

$source_array = ['foo', 'bar', 'baz'];

// インデックス 2 の要素を、変数 $baz に代入します。
[2 => $baz] = $source_array;

echo $baz; // "baz" を出力します。
?>

配列の分解を使うと、2つの変数を簡単に入れ替えることができます。

<?php
$a = 1;
$b = 2;

[$b, $a] = [$a, $b];

echo $a; // 2 を出力します。
echo $b; // 1 を出力します。
?>

注意:

分解時に値を代入する際には、... 演算子はサポートされていません。

注意:

定義されていない配列のキーにアクセスしようとすると、 未定義の変数にアクセスする場合と同じ扱いになります。 つまり、E_WARNING レベルの警告 (PHP 8.0.0 より前のバージョンでは E_NOTICE) が発生し、結果が null になります。

有用な関数

配列で使用する便利な関数がたくさんあります。 配列関数 の節を参照ください。

注意:

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) が使用されているためです。 下位互換性の維持のため、未定義の定数は同じ名前の文字列に自動的に変換されます。 そのため、このコードは動作します。 例えば、bar という名前の定義されていない定数があるとすると、 PHP は 'bar' という文字列でそれを置換して使用します。

警告

生の文字列を未定義の定数として扱う振る舞いは、 E_NOTICE レベルの警告が発生します。 この振る舞いは PHP 7.2.0 以降は推奨されなくなり、 E_WARNING レベルの警告が発生します。 PHP 8.0.0 以降は、この振る舞いは削除され、 Error 例外がスローされるようになっています。

注意: これは、添字を常にクォートするという意味ではありません。 定数や 変数 を添字として使う際には、クォートしてしまうと 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 occurred";
$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 occurred";
$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]" は有効です。 この理由の詳細については、上記の例や 文字列中での変数のパースを参照ください。

配列への変換

int, float, string, bool, resourceのいずれの型においても、 array に変換する場合、 最初のスカラー値が割り当てられている一つの要素 (添字は 0) を持つ配列を得ることになります。

objectを配列にする場合には、配列の要素として オブジェクトの属性 (メンバ変数) を持つ配列を得ることになります。 添字はメンバ変数名となりますが、いくつか注意すべき例外があります。 整数のプロパティはアクセス不能になります。 private 変数の場合、変数名の頭にクラス名がつきます。また、 protected 変数の場合は、変数名の頭に '*' がつきます。 このとき、頭に追加される値の前後に NUL バイトがついてきます。 未初期化の 型付きプロパティ は黙って捨てられます。

<?php
class A {
private $B;
protected $C;
public $D;
function __construct()
{
$this->{1} = null;
}
}
var_export((array) new A());
?>

上の例の出力は以下となります。

array (
  '' . "\0" . 'A' . "\0" . 'B' => NULL,
  '' . "\0" . '*' . "\0" . 'C' => NULL,
  'D' => NULL,
  1 => NULL,
)

これらの NUL バイトは、以下のような予期せぬ振る舞いをすることがあります:

<?php

class A {
private $A; // これは '\0A\0A' となります
}

class B extends A {
private $A; // これは '\0B\0A' となります
public $AA; // これは 'AA' となります
}

var_dump((array) new B());
?>

上の例の出力は以下となります。

array(3) {
  ["BA"]=>
  NULL
  ["AA"]=>
  NULL
  ["AA"]=>
  NULL
}

上の例では 'AA' というキーがふたつあるように見えますが、 そのうちひとつは、実際は '\0A\0A' ということになります。

null を配列に変換すると、空の配列を得ます。

比較

array_diff() と 配列演算子 を用いると、配列を比較することができます。

配列のアンパック

配列の前に ... を付けると、 配列を定義する際に、その配列の値を展開(アンパック)させることができます。 配列と、Traversable を実装したオブジェクトを展開させることができます。 ... を使った配列のアンパックは、 PHP 7.4.0 以降で利用可能です。

配列のアンパックは、配列中で何度でも行うことができます。 ... の前後に通常の要素を置くこともできます:

例9 簡単な配列のアンパック

<?php
// 配列の短縮構文を使っています。
// array() 記法も使えます。
$arr1 = [1, 2, 3];
$arr2 = [...$arr1]; //[1, 2, 3]
$arr3 = [0, ...$arr1]; //[0, 1, 2, 3]
$arr4 = [...$arr1, ...$arr2, 111]; //[1, 2, 3, 1, 2, 3, 111]
$arr5 = [...$arr1, ...$arr1]; //[1, 2, 3, 1, 2, 3]

function getArr() {
return ['a', 'b'];
}
$arr6 = [...getArr(), 'c' => 'd']; //['a', 'b', 'c' => 'd']
?>

... を使ったアンパックの動作は、 array_merge() 関数の仕様に従います。 つまり、キーが文字列の場合は後に指定された値が前の値を上書きしますし、 キーが整数の場合は、ゼロから値が振り直されます:

例10 キーが重複した場合の配列のアンパック

<?php
// キーが文字列の場合
$arr1 = ["a" => 1];
$arr2 = ["a" => 2];
$arr3 = ["a" => 0, ...$arr1, ...$arr2];
var_dump($arr3); // ["a" => 2]

// キーが整数の場合
$arr4 = [1, 2, 3];
$arr5 = [4, 5, 6];
$arr6 = [...$arr4, ...$arr5];
var_dump($arr6); // [1, 2, 3, 4, 5, 6]
// $arr6 は、 [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6] と同義です。
// ここでは、キーの値は保存されません。
?>

注意:

キーが整数でも文字列でもない場合は、 TypeError がスローされます。 そのようなキーを持つ値は、 Traversable オブジェクト経由でしか生成できません。

注意:

PHP 8.1 より前のバージョンでは、 キーが文字列の場合に、アンパックをサポートしていませんでした:

<?php

$arr1 = [1, 2, 3];
$arr2 = ['a' => 4];
$arr3 = [...$arr1, ...$arr2];
// Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5

$arr4 = [1, 2, 3];
$arr5 = [4, 5];
$arr6 = [...$arr4, ...$arr5]; // 動作します。 [1, 2, 3, 4, 5]
?>

例

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') となります
?>

例11 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();
?>

例12 コレクション

<?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?

配列を参照渡しすることでその値を直接変更できます。

例13 ループ内での要素の変更

<?php
foreach ($colors as &$color) {
$color = mb_strtoupper($color);
}
unset($color); /* これ以降の $color への書き込みが
配列の要素を書き換えてしまわないことを保証する */

print_r($colors);
?>

上の例の出力は以下となります。

Array
(
    [0] => RED
    [1] => BLUE
    [2] => GREEN
    [3] => YELLOW
)

この例は、1 から始まる配列を作成します。

例14 1 から始まる添字

<?php
$firstquarter = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>

上の例の出力は以下となります。

Array
(
    [1] => 'January'
    [2] => 'February'
    [3] => 'March'
)

例15 配列に代入する

<?php
// ディレクトリから全てのアイテムを配列に代入する
$handle = opendir('.');
while (false !== ($file = readdir($handle))) {
$files[] = $file;
}
closedir($handle);
?>

配列には順番が付けられます。異なったソート関数を用いて順番を変更することも可能です。 より詳細な情報については、配列関数 を参照ください。 count() 関数を使用することで、 配列の要素数を数えることが可能です。

例16 配列のソート

<?php
sort($files);
print_r($files);
?>

配列の値は何でも良いため、その値を他の配列とすることも可能です。 これにより、再帰的な配列や多次元の配列を作成することが可能です。

例17 再帰および多次元配列

<?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 というビルトインクラス（予めPHPの内部で定義されているクラス）のインスタンスが新しく生成されます。 その際、値が null の場合は新しいインスタンスは空となります。 また、配列がオブジェクトに変換される場合、配列のキーと値がそれぞれオブジェクトのプロパティ名とその値となります。 PHP 7.2.0 より前のバージョンでは、数値のキーの場合プロパティ名によるアクセスはできなかった点に注意して下さい。

<?php
$obj = (object) array('1' => 'foo');
var_dump(isset($obj->{'1'})); // PHP 7.2.0 以降は 'bool(true)' それより前は 'bool(false)'
var_dump(key($obj)); // PHP 7.2.0 以降は 'string(1) "1"' それより前は 'int(1)'
?>

上記以外の値の場合には、scalar という名前のメンバ変数が値を格納します。

<?php
$obj = (object) 'ciao';
echo $obj->scalar; // 'ciao' を出力します
?>


列挙型 / Enum

(PHP 8 >= 8.1.0)

列挙型の基礎

列挙型は、クラスやクラス定数に対して、さらに制限を加えたものです。 ある型に対して、取り得る値の限られた集合を定義する方法を提供します。

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

function do_stuff(Suit $s)
{
// ...
}

do_stuff(Suit::Spades);
?>

完全な説明は、 列挙型(Enum) を参照ください。

キャスト

列挙型を object にキャストしても、値は変更されません。 列挙型を array にキャストすると、 name というキーだけ(Pure Enum の場合) をもつ配列か、 name と value というキー(Backed Enum の場合) を持つ配列が生成されます。 それ以外のキャストを行っても、エラーが発生します。


リソース

リソース は特別な変数であり、外部リソースへのリファレンスを保持しています。 リソースは、特別な関数により作成され、使用されます。 これらの関数および対応する全ての リソース 型の一覧については、 付録 を参照ください。

get_resource_type() も参照ください。

リソースへの変換

リソース 型は、オープンされたファイル、データベース接続、 イメージキャンバスエリアのような特殊なハンドルを保持するため、 他の値を リソース に変換することはできません。

リソースの開放

Zend エンジンの一部であるリファレンスカウンティングシステムのおかげで、 ある リソース がもう参照されなくなった場合に (Java と全く同様に)、 そのリソースは自動的に削除されます。この場合、このリソースが作成した 全てのリソースは、ガベージコレクタにより開放されます。 このため、free_result 関数を用いて手動でメモリを開放する必要が生じるのはまれです。

注意: 持続的データベース接続は特別で、ガベージコレクタにより破棄されません。 持続的接続 も参照ください。


コールバック / Callable

コールバックは、callable 型で表されます。

call_user_func() や usort() 等の関数は、ユーザーが定義するコールバック関数を引数として受け入れます。 コールバック関数は、単純な関数だけでなく、オブジェクトのメソッド あるいはクラスのstaticメソッドであってもかまいません。

受け渡し

PHP 関数はその名前を単に文字列として渡します。 どのようなビルトインまたはユーザー定義の関数も渡すことができます。 ただし、 array(), echo, empty(), eval(), exit(), isset(), list(), print あるいは unset() といった言語構造はコールバックとしては使えないことに注意しましょう。

オブジェクトのインスタンスを渡すには配列を使います。 配列の 0 番目の要素にオブジェクトを、 そして 1 番目の要素にメソッド名を指定します。 protected メソッドや private メソッドは、クラスの内部からはアクセスできます。

static メソッドの場合、オブジェクトのインスタンスは不要です。 0 番目の要素として、オブジェクトのかわりにクラス名を指定します。 'ClassName::methodName' 形式で指定することもできます。

一般的なユーザー定義関数とは異なり、 無名関数 と アロー関数 もパラメータとして渡せます。

注意:

PHP 8.1.0 以降では、 無名関数を作るための記法として、第一級callableを生成する記法 も使えます。

一般的には、 __invoke() を実装した任意のオブジェクトもパラメータとして渡せます。

例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: staticメソッドのコール
call_user_func(array('MyClass', 'myCallbackMethod'));

// タイプ 3: オブジェクトメソッドのコール
$obj = new MyClass();
call_user_func(array($obj, 'myCallbackMethod'));

// タイプ 4: staticメソッドのコール
call_user_func('MyClass::myCallbackMethod');

// タイプ 5: 相対指定によるstaticメソッドのコール
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, 但し PHP 8.2.0 以降は非推奨

// タイプ 6: __invoke を実装したオブジェクトを callable として用いる
class C {
public function __invoke($name) {
echo 'Hello ', $name, "\n";
}
}

$c = new C();
call_user_func($c, 'PHP!');
?>

例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

注意:

call_user_func() や call_user_func_array() で登録されたコールバックは、 前のコールバックからスローされた例外がキャッチされていない場合はコールされません。


Mixed

mixed は、あらゆる値を受け入れる型です。 これは、以下の union 型 と同等です。 object|resource|array|string|float|int|bool|null. この型は、PHP 8.0.0 以降で利用可能です。

mixed 型は、型理論の用語で言うと、トップ型にあたります。 つまり、他の全ての型は、この型の部分型になります


Void

void は、関数が値を返さないことを示す、 戻り値のみで指定できる型ですが、関数を終了させても構いません。 よって、この型は union 型 の一部として指定することが出来ません。 PHP 7.1.0 以降で利用できます。

注意: 戻り値の型が void である関数であっても、 値を返すことはできます。その場合には、戻り値は常に null になります。


Never

never は、 関数が戻ってこないことを示す戻り値の型です。 これは、関数の中で exit() がコールされるか、 例外がスローされるか、 無限ループに入るかのいずれかであることを意味します。 よって、この型は union 型 の一部として指定することが出来ません。 PHP 8.1.0 以降で利用できます。

never は、 型理論の用語で言うと、ボトム型にあたります。 つまり、全ての他の型の部分型であり、 継承する際に他の戻り値の型を置き換えることができます。


クラス内での関係を示す相対型

以下の型宣言は、クラスの内部でのみ使えます。

self

値が、型宣言が行われているクラスと同じクラスのインスタンスでなければいけません。

parent

値が、型宣言が行われたクラスの、親クラスのインスタンスでなければいけません。

static

値が、メソッドが呼び出されているクラスと同じインスタンスでなければならないことを示す、戻り値でのみ指定できる型です。PHP 8.0.0 以降で利用できます。


Value型

Value(値)型は、値の型だけでなく、値そのものもチェックされる型です。 PHP はふたつのValue型をサポートしています。 PHP 8.0.0 以降でサポートされた false 型と、 PHP 8.2.0 以降でサポートされた true 型です。

警告

PHP 8.2.0 より前のバージョンでは、 false 型は union 型 の一部としてのみ使える型でした。

注意: カスタムのValue型を定義することはできません。 そうしたい場合、列挙型(Enum) を使うことを検討してください。


Iterable

Iterable は組み込みの、コンパイル時に変換される array|Traversable 型のエイリアスです。 この型は PHP 7.1.0 で導入されました。 PHP 8.2.0 より前のバージョンでは、 この型は上で述べた型のエイリアスとして振る舞う組み込みの疑似型でした。 この型は、型宣言でも使うことができます。 iterable 型は、foreach で繰り返し可能であり、 ジェネレータ 内で yield from できます。

注意:

戻り値の型として iterable を宣言する関数は、 ジェネレータ にもなります。

例1 iterable を戻り値の型として使った、ジェネレータの例

<?php

function gen(): iterable {
yield 1;
yield 2;
yield 3;
}

?>


型宣言

関数のパラメータや戻り値、 クラスのプロパティ (PHP 7.4.0 以降) に対して型を宣言することができます。 これによって、その値が特定の型であることを保証できます。 その型でない場合は、TypeError がスローされます。

PHP がサポートしている単一の型それぞれを、 ユーザーが行う型宣言の中で使うことができます。 但し、resource 型を除きます。 このページでは、それぞれの型がいつ利用可能になったかの変更履歴や、 型宣言におけるそれらの使い方について記しています。

注意:

クラスがインターフェイスのメソッドを実装したり、 親クラスで既に定義されているメソッドを再実装する場合、 そのメソッドは、既に存在するメソッドと互換性がなければなりません。 共変性と反変性 のルールに従っている場合、メソッドには互換性があります。

変更履歴

バージョン | 説明
8.3.0 | クラス、インターフェイス、トレイト、そして列挙型の定数は、新たに型宣言をサポートするようになりました。
8.2.0 | DNF 型のサポートが追加されました。
8.2.0 | リテラル型 true のサポートが追加されました。
8.2.0 | null と false 型が、独立した型として使えるようになりました。
8.1.0 | 交差型のサポートが追加されました。
8.1.0 | 戻り値を void とした関数からリファレンスを返すことは、 推奨されなくなりました。
8.1.0 | 戻り値にのみ指定できる型として、 never 型のサポートが追加されました。
8.0.0 | mixed 型のサポートが追加されました。
8.0.0 | 戻り値にのみ指定できる型として、 static 型のサポートが追加されました。
8.0.0 | union 型のサポートが追加されました。
7.4.0 | クラスのプロパティに、型宣言のサポートが追加されました。
7.2.0 | object 型のサポートが追加されました。
7.1.0 | iterable 型のサポートが追加されました。
7.1.0 | void 型のサポートが追加されました。
7.1.0 | nullable な型のサポートが追加されました。

基本型を使うときの注意

基本型は、ここで説明する小さな注意事項はいくつかあるものの、 わかりやすい振る舞いをします。

スカラー型

警告

スカラー型(bool, int, float, string) のエイリアスはサポートされていません。 つまり、これらはクラスやインターフェイスの名前として扱われているということです。 たとえば、型の宣言に boolean を使った場合、 値が boolean クラスまたはインターフェイスのインスタンスであることが要求されます。 bool 型ではありません。

<?php
function test(boolean $param) {}
test(true);
?>

上の例の PHP 8 での出力は、このようになります。:

Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
Stack trace:
#0 -(3): test(true)
#1 {main}
  thrown in - on line 2

void

注意:

void を返す関数からリファレンスを返すことは、PHP 8.1.0 以降は推奨されなくなりました。 なぜなら、関数の定義そのものが矛盾しているからです。 PHP 8.1.0 より前のバージョンでは、 関数をコールした際に次のような E_NOTICE が発生していました: Only variable references should be returned by reference

<?php
function &test(): void {}
?>

Callable

この型は、クラスのプロパティの型宣言では使うことができません。

注意: 関数のシグネチャに指定することもできません。

リファレンス渡しのパラメータに対する型宣言

リファレンス渡しのパラメータに対して宣言される型は、 関数の入り口で だけ チェックされます。 しかし、関数から返される時はチェックされません。 これは、変数のリファレンスについては、関数が型を変更できるということです。

例1 リファレンス渡しのパラメータに対する型宣言

<?php
function array_baz(array &$param)
{
$param = 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
Stack trace:
#0 -(9): array_baz(1)
#1 {main}
  thrown in - on line 2

複合型を使うときの注意

複合型を宣言する場合、制限がいくつか存在します。 また、簡単なバグを防ぐために、型の冗長チェックがコンパイル時に行われます。

警告

PHP 8.2.0 より前のバージョン、 つまり DNF 型がサポートされる前は、 交差型とunion型を組み合わせることはできませんでした。

union 型

警告

union 型の中で、Value型 true と false を同時に組み合わせて使うことはできません。 bool 型を使ってください。

警告

PHP 8.2.0 より前のバージョンでは、 false と null 型は 独立した型として使えず、 union 型でそれらだけを指定することも許されませんでした。 つまり、false, false|null, ?false のような型はいずれも許されませんでした。

nullable な型とシンタックスシュガー

単一の基本型を宣言した場合、 型の名前の前にクエスチョンマーク (?) を付けることで、nullable であるという印を付けることができます。 よって、?T と T|null は同じ意味です。

注意: この文法は、PHP 7.1.0 以降でサポートされており、 一般化された union 型がサポートされる前から存在します。

注意:

デフォルト値に null を指定することで、 null を許容するパラメータを指定することができます。 これは、子クラスでデフォルト値が変更された場合にクラスの互換性が壊れ、 型宣言で null 型を追加しなければならなくなるため、おすすめできません。

例2 引数にnullを許容する古いやり方

<?php
class C {}

function f(C $c = null) {
var_dump($c);
}

f(new C);
f(null);
?>

上の例の出力は以下となります。

object(C)#1 (0) {
}
NULL

重複した冗長な型

複合型の宣言に関する単純なバグを見つけるため、 クラスの読み込みを行わずに検出できる冗長な型はコンパイル時にエラーになります。 たとえば、以下のような場合です:

  • 名前が解決された型は、一度しか現れることができません。 int|string|INT や Countable&Traversable&COUNTABLE のような型はエラーになります。
  • mixed 型を複合型で使うとエラーになります。
  • union 型に適用される制限:
    • bool 型が使われている場合、false や true 型は追加で使えません。
    • object 型が使われている場合、クラス型は追加で使えません。
    • iterable 型が使われている場合、 array と Traversable は追加で使えません。
  • 交差型に適用される制限:
    • クラス型でない型を、交差型で使うとエラーになります。
    • self, parent, static のいずれかを、交差型で使うとエラーになります。
  • DNF 型に適用される制限:
    • より広い型をひとつ使った場合、 それより狭い型は冗長とみなされます。
    • ふたつの等しい交差型を使った場合、冗長とみなされます。

注意: これによって、型が "最低限" であることは保証しません。 なぜなら、最低限であることを保証するためには、 使われている全てのクラスの型を読み込まなければならないからです。

たとえば、A と B がクラスのエイリアスだったとします。 この場合、A|B は A または B のみに縮めることができますが、 正しい union 型です。 同様に、B extends A {} というクラスがあった場合、 A|B は A のみに縮めることができますが、 正しい union 型です。

<?php
function foo(): int|INT {} // 許されません
function foo(): bool|false {} // 許されません
function foo(): int&Traversable {} // 許されません
function foo(): self&Traversable {} // 許されません

use A as B;
function foo(): A|B {} // 許されません ("use" は名前解決の一部です)
function foo(): A&B {} // 許されません ("use" は名前解決の一部です)

class_alias('X', 'Y');
function foo(): X|Y {} // 問題ありません (冗長かどうかは、実行時にだけわかります)
function foo(): X&Y {} // 問題ありません (冗長かどうかは、実行時にだけわかります)
?>

例

例3 クラスによる型宣言の基本

<?php
class C {}
class D extends C {}

// このクラスは、C を継承していません
class E {}

function f(C $c) {
echo get_class($c)."\n";
}

f(new C);
f(new D);
f(new E);
?>

上の例の PHP 8 での出力は、このようになります。:

C
D

Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8

例4 インターフェイスによる型宣言の基本

<?php
interface I { public function f(); }
class C implements I { public function f() {} }

// このクラスは、インターフェイス I を実装していません
class E {}

function f(I $i) {
echo get_class($i)."\n";
}

f(new C);
f(new E);
?>

上の例の PHP 8 での出力は、このようになります。:

C

Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
  thrown in - on line 8

例5 基本的な戻り値の型宣言

<?php
function sum($a, $b): float {
return $a + $b;
}

// float が返される点に注意
var_dump(sum(1, 2));
?>

上の例の出力は以下となります。

float(3)

例6 オブジェクトを返す

<?php
class C {}

function getC(): C {
return new C;
}

var_dump(getC());
?>

上の例の出力は以下となります。

object(C)#1 (0) {
}

例7 Null を許容する型宣言

<?php
class C {}

function f(?C $c) {
var_dump($c);
}

f(new C);
f(null);
?>

上の例の出力は以下となります。

object(C)#1 (0) {
}
NULL

例8 Null を許容する戻り値の型宣言

<?php
function get_item(): ?string {
if (isset($_GET['item'])) {
return $_GET['item'];
} else {
return null;
}
}
?>

例9 クラスのプロパティで型宣言

<?php
class User {
public static string $foo = 'foo';

public int $id;
public string $username;

public function __construct(int $id, string $username) {
$this->id = $id;
$this->username = $username;
}
}
?>

厳密な型付け

デフォルトでは、PHP は誤った型の値を 可能であれば期待されたスカラー型の宣言に従うよう自動的に変換します(coercive モード)。 たとえば、関数に int が与えられたが、 パラメータで文字列が期待されていた場合、文字列型の値を取得します。

ファイルごとに strict モードを有効にすることができます。 strict モードでは、型宣言に正確に対応する値のみを受け入れ、 それ以外の値の場合、TypeError がスローされます。 このルールに関する唯一の例外は、int の値が float 型の宣言に渡せることだけです。

警告

内部関数の中からの関数呼び出しは、 strict_types 宣言の影響を受けません。

strict モードを有効にするには、declare 文を strict_types 宣言と一緒に使います。

注意:

厳密な型付けは、strict モードが有効になったファイルの 内部 から行われる関数呼び出しに適用されます。 そのファイルで宣言された関数への呼び出しに対して適用されるわけではありません。 厳密な型付けが有効になっていないファイルから、 厳密な型付けが有効になっているファイルで定義された関数を呼び出した場合は、 呼び出し側の好み(型の自動変換)が尊重され、値は型変換されます。

注意:

厳密な型付けは、スカラー型の宣言に対してのみ定義されます。

例10 引数の値に対する厳密な型付け

<?php
declare(strict_types=1);

function sum(int $a, int $b) {
return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
?>

上の例の PHP 8 での出力は、このようになります。:

int(3)

Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
  thrown in - on line 4

例11 引数の値に対する型の自動変換

<?php
function sum(int $a, int $b) {
return $a + $b;
}

var_dump(sum(1, 2));

// これらは、整数型に変換されます: 以下の出力を参照!
var_dump(sum(1.5, 2.5));
?>

上の例の出力は以下となります。

int(3)
int(3)

例12 戻り値に対する厳密な型付け

<?php
declare(strict_types=1);

function sum($a, $b): int {
return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1, 2.5));
?>

上の例の出力は以下となります。

int(3)

Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
  thrown in - on line 5


型の相互変換

PHP は変数宣言時に明示的な型定義を必要としません。 型を定義しない場合、変数の型は保存する値によって決まります。 これは、変数 $var に文字列を代入した場合、 $var の型は文字列 (string) になることを意味しています。 その後、整数値を $var に代入すると、 その変数の型は整数 (int) になります。

コンテクスト(文脈)によっては、 PHP が値を別の型に自動変換しようとすることがあります。 自動変換が行われる異なるコンテクストが存在するのは、以下のとおりです:

  • 数値のコンテクスト
  • 文字列のコンテクスト
  • 論理コンテクスト
  • 整数と文字列のコンテクスト
  • 比較のコンテクスト
  • 関数のコンテクスト

注意: 値を別の型として解釈する必要がある場合でも、 値そのものの型は 変わりません。

変数を強制的にある特定の型として評価させたい場合は、 型キャスト のセクションを参照ください。 ある変数の型を変更したい場合は、settype() を参照ください。

数値のコンテクスト

これは、 算術演算子 を使った場合です。

このコンテクストでは、 オペランドのどちらかが float (または整数と解釈できない場合) の場合か、 両方のオペランドが float の場合、 結果の型は float になります。 そうでない場合、オペランドは整数として解釈され、 結果の型も整数になります。 PHP 8.0.0 以降では、いずれかのオペランドが解釈できない場合、 TypeError がスローされます。

文字列のコンテクスト

これは、 echo, print や 文字列中の変数のパース、または 文字列演算子 を使った場合です。

値は文字列として解釈されます。 文字列として解釈できない場合、 TypeError がスローされます。 PHP 7.4.0 より前のバージョンでは、 E_RECOVERABLE_ERROR が発生していました。

論理コンテクスト

これは、 制御構文や 三項演算子, 論理演算子 を使った場合です。

値は論理値 (bool) として解釈されます。

整数と文字列のコンテクスト

これは、 ビット演算子 を使った場合です。

全てのオペランドが文字列の場合、 結果の型も文字列になります。 そうでない場合、 オペランドは整数として解釈され、 結果の型も整数になります。 PHP 8.0.0 以降では、いずれかのオペランドが解釈できない場合、 TypeError がスローされます。

比較のコンテクスト

これは、 比較演算子 を使った場合です。

このコンテクストで発生する型変換については、 さまざまな型の比較表 に説明があります。

関数のコンテクスト

これは、値が型付きの引数、型付きプロパティに渡された場合や、 戻り値の型を宣言している関数から値が返される場合です。

このコンテクストでは、値はその型の値でなければなりません。 これにはふたつ例外があります。 ひとつめは値の型が int で、 宣言されている型が float の場合、 整数が浮動小数点に変換されることです。 ふたつめは型が スカラー型、 または値がスカラー型に変換可能な場合で、 かつ型の自動変換モードが有効な場合(デフォルト)、 スカラー型の値だけが別の変換可能なスカラー型に変換される可能性があることです。 この振る舞いに関する詳細は、以下を参照ください:

警告

内部関数 は、null を自動的にスカラー型に変換します。 この振る舞いは PHP 8.1.0 以降は 推奨されなくなっています。

単一の型宣言における、型の自動変換

  • 論理型(bool) が宣言されている場合: 値は bool として解釈されます。
  • 整数型 (int) が宣言されてい場合: int への変換が定義されている場合は、int として解釈されます。たとえば、文字列が 数値形式 である場合です。
  • float が宣言されている場合: float への変換が定義されている場合は、float として解釈されます。たとえば、文字列が 数値形式 である場合です。
  • 文字列 (string) 型として宣言されている場合: 値は文字列として解釈されます。

union 型と型の自動変換

strict_types が有効になっていない場合、 スカラー型の宣言は、限られた暗黙の型変換が行われます。 値の正確な型が union の一部に指定されていない場合、 次の順に対象となる型が選択されます:

  1. int
  2. float
  3. string
  4. bool
正確な型が union の中に存在し、 かつ値が PHP の既存の型チェックのセマンティクスによって型変換できる場合、 その型が選択されます。 そうでない場合、次の型を試そうとします。

警告

例外として、値が文字列で、int と float が union に含まれていた場合、 型は既存の 数値形式の文字列 を解釈するセマンティクスによって決まります。 たとえば、"42" の場合、 int が選ばれますし、 "42.0" の場合、float が選ばれます。

注意:

上のリストに入っていない型については、 暗黙の型変換が行われる対象ではありません。 特に、暗黙のうちに null, false, true に変換されることはありません。

例1 union の型のひとつに変換される例

<?php
// int|string
42 --> 42 // 正確に型が一致
"42" --> "42" // 正確に型が一致
new ObjectWithToString --> "Result of __toString()"
// オブジェクトは int と互換性がないので、文字列にフォールバック
42.0 --> 42 // float は int と互換性がある
42.1 --> 42 // float は int と互換性がある
1e100 --> "1.0E+100" // int には大きすぎる float なので、文字列にフォールバック
INF --> "INF" // int には大きすぎる float なので、文字列にフォールバック
true --> 1 // bool は int と互換性がある
[] --> TypeError // 配列はint, string と互換性はない。
// int|float|bool
"45" --> 45 // int の数値形式の文字列
"45.0" --> 45.0 // float の数値形式の文字列
"45X" --> true // 数値形式の文字列ではない。boolにフォールバック
"" --> false // 数値形式の文字列ではない。boolにフォールバック
"X" --> true // 数値形式の文字列ではない。boolにフォールバック
[] --> TypeError // 配列はint, float, bool と互換性はない。
?>

型キャスト

型キャストは、変換しようとする型の名前を括弧で括り、 キャストする変数の前に置くことで、値を別の型に変換するものです。

<?php
$foo = 10; // $foo は整数です
$bar = (bool) $foo; // $bar は boolean です
?>

使用可能なキャストを以下に示します:

  • (int) - 整数(int) へのキャスト
  • (bool) - 論理値(bool) へのキャスト
  • (float) - float へのキャスト
  • (string) - 文字列(string) へのキャスト
  • (array) - 配列(array) へのキャスト
  • (object) - オブジェクト(object) へのキャスト
  • (unset) - NULL へのキャスト

注意:

(integer) は、(int) のエイリアスです。 (boolean) は、(bool) のエイリアスです。 (binary) は、(string) のエイリアスです。 (double) と (real) は、(float) のエイリアスです。 これらのキャストは、正規化された型の名前を使っていません。そのため使うこと自体がおすすめできません。

警告

キャストのエイリアス (real) を使うことは、PHP 8.0.0 以降は推奨されなくなっています。

警告

(unset) によるキャストは、 PHP 7.2.0 以降推奨されなくなりました。 (unset) によるキャストは、 値に NULL 値を代入することと同じです。 (unset) によるキャストは、PHP 8.0.0 で削除されました。

警告

将来サポートされることを見越して、(binary) によるキャストと b プレフィックスが存在しています。 (binary) と (string) は現状は等価ですが、将来変更される可能性があります。そのため、現状等価であることに依存すべきではありません。

注意:

キャストの括弧内のホワイトスペースは無視されます。 よって、以下のふたつのキャストは等価です:

<?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";
}
?>

型の間でキャストを行う際の動作は、必ずしも明確ではありません。 詳細については、以下の節を参照ください:

  • 論理値への変換
  • 整数への変換
  • 浮動小数点数への変換
  • 文字列への変換
  • 配列への変換
  • オブジェクトへの変換
  • リソース型への変換
  • NULL への変換
  • 型の比較表

注意: PHP では配列の添字と同じ構文を使用した文字列へのアクセスをサポートしているので、次の例はあらゆるバージョンの PHP で成立します:

<?php
$a = 'car'; // $a は文字列です
$a[0] = 'b'; // $a はここでも文字列です
echo $a; // bar
?>
詳細は、 文字列への文字単位のアクセス を参照ください。


  • ≪ 型の相互変換
  • 基本的な事 ≫
  • PHP Manual
  • 言語リファレンス
  • 変数

変数

目次

  • 基本的な事
  • 定義済みの変数
  • 変数のスコープ
  • 可変変数
  • 外部から来る変数


基本的な事

PHP の変数はドル記号の後に変数名が続く形式で表されます。 変数名は大文字小文字を区別します。

変数名は、PHPの他のラベルと同じルールに従います。 有効な変数名は文字またはアンダースコアから始まり、任意の数の文字、 数字、アンダースコアが続きます。正規表現によれば、これは次の ように表現することができます。 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$

注意: ここで言うところの文字とはa-z、A-Z、128から255まで (0x80-0xff)のバイトを意味します。

注意: $this は特別な変数であり、ここに代入することはできません。 PHP 7.1.0 より前のバージョンでは、 (可変変数 を使った) 間接的な代入 が可能でした。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

変数関連の関数に関する情報については、 変数関数リファレンス を参照ください。

<?php
$var = 'Bob';
$Var = 'Joe';
echo "$var, $Var"; // "Bob, Joe"を出力します。

$4site = 'not yet'; // 無効：数字で始まっている。
$_4site = 'not yet'; // 有効：アンダースコアで始まっている。
$tayte = 'mansikka'; // 有効：'a' はアスキーコード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 として使用すると、出力は '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 している別のファイルで同名の変数が使用されていた場合などに問題を起こします。 初期化されていない変数を使用すると、 E_WARNING (PHP 8.0.0 より前のバージョンでは E_NOTICE) レベルのエラーが発生します。 しかし、初期化されていない配列に要素を追加する場合はエラーにはなりません。 変数が初期化されているかどうかの判断には、isset() を使用します。


定義済みの変数

PHPは、実行する全てのスクリプトに定義済みの多くの変数を 提供します。しかし、これらの変数の多くは、 実行するサーバーの種類、サーバーのバージョンおよび設定、 その他の要素に依存しており、完全に記述することはできません。 これらの変数のいくつかは、PHPを コマンドライン で実行した場合には利用できません。 これらの変数の一覧については、 定義済の変数 のセクションを参照ください。

PHP には、(使用する場合)Webサーバー、環境変数、 ユーザー入力からの変数を値とする定義済みの配列が追加されています。 これらの配列は、自動グローバル、すなわち、自動的に全ての スコープで利用可能であるという点でかなり特別です。このため、これらは "スーパーグローバル" といわれることもあります。 (PHPには、ユーザー定義のスーパーグローバルという機構はありません。) スーパーグローバルの一覧 も参照ください。

注意: 可変変数

可変変数として スーパーグローバルを使うことはできません。

variables_orderに ある変数が設定されていない場合、これらに対応するPHPの定義済み 変数も空のままとなります。


変数のスコープ

変数のスコープは、その変数が定義されたコンテキストです。ほとんどの PHP 変数は、スコープを1つだけ有しています。このスコープの範囲は、 include や require により読みこまれたファイルも含みます。例えば、

<?php
$a = 1;
include 'b.inc';
?>

この例で、変数$aはインクルードされた b.inc スクリプトの中でも利用可能です。しかし、 ユーザー定義の関数の中では変数の有効範囲はローカル関数の中となりま す。関数の中で使用された変数はデフォルトで有効範囲が関数内部に制限 されます。例えば、

<?php
$a = 1; /* グローバルスコープ */

function test()
{
echo $a; /* ローカルスコープ変数の参照 */
}

test();
?>

このスクリプトは、未定義の変数があるという E_WARNING (PHP 8.0.0 より前のバージョンでは E_NOTICE) を生成します。 しかし、display_errors INI 設定がこの警告を隠すよう設定されている場合、出力を全く行いません。 これは、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_superglobal()
{
echo $_POST['name'];
}
?>

注意:

global キーワードを関数の外部で使ってもエラーにはなりません。 そのファイルが関数の内部からインクルードされたときに使うことができます。

static 変数の使用

変数のスコープに関する別の重要な機能は、static (静的) 変数です。static 変数はローカル関数スコープのみに 存在しますが、プログラム実行がこのスコープの外で行われるようになっ てもその値を失いません。次の例を見てください。

例4 static 変数が必要な場面の例

<?php
function test()
{
$a = 0;
echo $a;
$a++;
}
?>

この関数は、コールされる度に$aを 0にセットし、0 を出力するのでほとん ど役にたちません。変数を1増やす $a++ は、関数から外に出ると変数 $aが消えてしまうために目的を達成しません。現在 のカウントの追跡ができるようにカウント関数を使用できるようにするた めには、変数$aを static として宣言します。

例5 static 変数の使用例

<?php
function test()
{
static $a = 0;
echo $a;
$a++;
}
?>

こうすると、$a は関数が最初にコールされたときにのみ初期化され、 test() 関数がコールされるたびに $a の値を出力してその値を増加させます。

static 変数は、再帰関数を実現する1つの手段としても使用されます。再帰 関数は、自分自身をコールする関数です。再帰関数を書くときには、無限 に再帰を行う可能性があるため、注意する必要があります。適当な方法に より再帰を確実に終了させる必要があります。次の簡単な関数は、中止す るタイミングを知るためにstatic変数$countを用いて、 10 回まで再帰を行います。

例6 再帰関数でのstatic変数の使用

<?php
function test()
{
static $count = 0;

$count++;
echo $count;
if ($count < 10) {
test();
}
$count--;
}
?>

static 変数には、定数式の結果としての値を代入できますが、 関数呼び出しのような動的な式の結果を代入すると、パースエラーになります。

例7 static 変数の宣言

<?php
function foo(){
static $int = 0; // 正しい
static $int = 1+2; // 正しい
static $int = sqrt(121); // 間違い（関数を使っています）

$int++;
echo $int;
}
?>

(オーバーライドされていない場合) 内部でstatic 変数を使ったメソッドも継承されます。 PHP 8.1.0 以降は、継承されたメソッドは、 親クラスのメソッドとstatic 変数を共有するようになりました。 つまり、メソッド内でのstatic 変数も、 static プロパティと同じ振る舞いになったということです。

例8 継承されたメソッドのstatic 変数を使う

<?php
class Foo {
public static function counter() {
static $counter = 0;
$counter++;
return $counter;
}
}
class Bar extends Foo {}
var_dump(Foo::counter()); // int(1)
var_dump(Foo::counter()); // int(2)
var_dump(Bar::counter()); // int(3), PHP 8.1.0 より前のバージョンでは int(1)
var_dump(Bar::counter()); // int(4), PHP 8.1.0 より前のバージョンでは int(2)
?>

注意:

static 変数の宣言は、コンパイル時に解決されます。

グローバル変数とstatic 変数のリファレンス

PHP は、 リファレンス 変数の修正子として static および global を実装しています。 例えば、関数スコープ内にglobal 命令により実際にインポートされた真のグローバル変数は、 実際にグローバル変数へのリファレンスを作成します。 これにより、以下の例が示すように予測できない動作を引き起こす可能性 があります。

<?php
function test_global_ref() {
global $obj;
$new = new stdClass;
$obj = &$new;
}

function test_global_noref() {
global $obj;
$new = new stdClass;
$obj = $new;
}

test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>

上の例の出力は以下となります。

NULL
object(stdClass)#1 (0) {
}

類似の動作がstatic命令にも適用されます。 リファレンスはstaitc 変数に保存することができません。

<?php
function &get_instance_ref() {
static $obj;

echo 'Static object: ';
var_dump($obj);
if (!isset($obj)) {
$new = new stdClass;
// Assign a reference to the static variable
$obj = &$new;
}
if (!isset($obj->property)) {
$obj->property = 1;
} else {
$obj->property++;
}
return $obj;
}

function &get_instance_noref() {
static $obj;

echo 'Static object: ';
var_dump($obj);
if (!isset($obj)) {
$new = new stdClass;
// Assign the object to the static variable
$obj = $new;
}
if (!isset($obj->property)) {
$obj->property = 1;
} else {
$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)#3 (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 が配列へのアクセスであっても同じです。

波括弧を使って、プロパティ名の区切りを明確にすることもできます。 これが特に有用なのは、配列が格納されているプロパティにアクセスするときや プロパティ名が複数のパーツからなる場合、 あるいはプロパティ名として無効な文字を含む場合 (たとえば json_decode() や SimpleXML に由来するプロパティ) などです。

例1 可変プロパティの例

<?php
class foo {
var $bar = 'I am bar.';
var $arr = array('I am A.', 'I am B.', 'I am C.');
var $r = 'I am r.';
}

$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo $foo->$bar . "\n";
echo $foo->{$baz[1]} . "\n";

$start = 'b';
$end = 'ar';
echo $foo->{$start . $end} . "\n";

$arr = 'arr';
echo $foo->{$arr[1]} . "\n";

?>

上の例の出力は以下となります。

I am bar.
I am bar.
I am bar.
I am r.

警告

関数やクラスメソッドの内部で、可変変数と 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
echo $_POST['username'];
echo $_REQUEST['username'];
?>

GETフォームを使用した場合も同じですが、かわりに適当な定義済みの GET変数を使用するところが異なります。 GETは、QUERY_STRING (URLの'?'の後の情報)にも代入されます。 例えば、 http://www.example.com/test.php?id=3には、 $_GET['id']によりアクセス可能なGETデータ が含まれます。 $_REQUEST も参照ください。

注意:

変数名のドットやスペースはアンダースコアに変換されます。 たとえば <input name="a.b" /> は $_REQUEST["a_b"] となります。

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 Schwabenbrau</option>
</select><br />
<input type="submit" value="submit me!" />
</form>

注意: 外部の変数の名前が、正しい配列の文法で始まっていた場合、 後に続く文字は黙って無視されます。 たとえば、<input name="foo[bar]baz"> は $_REQUEST['foo']['bar'] になります。

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 のような適当なCookieデータ 配列で参照可能です。また、 $_REQUESTでも 参照可能です。詳細および例については、 setcookie()のマニュアルページを参照ください。

注意: セキュリティ上の理由により、 PHP 7.2.34, 7.3.23, 7.4.11 以降では、外部から入力される Cookie の 名前 はurlデコードされなくなりました。

単一の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() です。 型の章も参照ください。

HTTP はテキストプロトコルなので、 $_POST および $_GET のような スーパーグローバル配列 に入ってくる内容は、全てとは言えないまでも、ほとんどは文字列のままです。 PHP は決して値を特定の型に変換したりはしません。 以下の例では、$_GET["var1"] は "null" という文字列を含みますし、 $_GET["var2"] は、文字列 "123" を含みます。

/index.php?var1=null&var2=123

変更履歴

バージョン | 説明
7.2.34, 7.3.23, 7.4.11 | セキュリティ上の理由により、外部から入力される Cookie の 名前 はurlデコードされなくなりました。


定数

目次

  • 構文
  • 自動的に定義される定数
  • マジック定数

定数は、値のためのID(名前)です。この名前が示すように、定数の値は スクリプト実行中に変更できません (マジック定数 は例外です。これは実際は定数ではありません)。 定数は大文字小文字を区別します。慣習的に、 定数は常に大文字で表記されます。

注意:

PHP 8.0.0 より前のバージョンでは、 define() 関数を使って定義された定数は、 大文字小文字を区別しない場合がありました。

定数の名前は、PHP のラベルと同じ規則に従います。有効な定数の名前は、 文字またはアンダースコアで始まり、任意の数の文字、数字、 アンダースコアが後に続きます。正規表現で示すと次のようになります。 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$

define() 関数を使うと、 予約語や有効でない名前の定数を定義することが可能です。 この場合の定数の値は constant() 関数によってのみ取得できますが、 このような使い方は推奨できません。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

例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, および128から255まで (0x80-0xff)のASCII文字を指します。

スーパーグローバルと同様に定数のスコープはグローバルです。 つまり、スコープによらずスクリプトの中ではどこでも定数に アクセスできます。スコープの詳細についてはマニュアルの 変数のスコープ をご覧ください。

注意: PHP 7.1.0 以降では、クラス定数は protected または private として宣言でき、 それが定義されたクラス階層のスコープでのみ利用可能にすることができます。


構文

const キーワードか、 define() 関数を使うことで、定数を宣言することが出来ます。 define() を使えば任意の式を使って定数を定義できますが、 const キーワードを使う場合には、 次の段落で説明する制約があります。 定数が一度定義されると、 変更または未定義とすることはできません。

const キーワードで定数に指定できるのは、スカラー式 (bool, int, float, string) と、 スカラー式だけを含んだ array の定数です。 resource の定数を指定することもできますが、 予期せぬ結果を引き起こすことがあるので避けるべきです。

単に定数の名前を指定することにより、その値を得ることが可能です。 変数とは異なり、その前に $ は不要です。 定数の名前を動的に得る必要がある場合、定数の値を読むために関数 constant() を使用することも可能です。 定義済の定数の一覧を得るには、 get_defined_constants() を使用してください。

注意: 定数と(グローバル)変数は、異なる名前空間にあります。 例えば、true と $TRUE は違うものを意味します。

未定義の定数を使用した場合、Error がスローされます。 PHP 8.0.0 より前のバージョンでは、 未定義の定数は、ちょうどstringとして コールしたかのように(CONSTANT vs "CONSTANT")、 PHPはその定数自体の名前を使用したと解釈していました。 このような振る舞いは、PHP 7.2.0 以降では非推奨となり、E_WARNING が発生するようになりました。 (それより前のバージョンでは、 E_NOTICE が発生していました) （barが定数でなければ) なぜ $foo[bar]が間違っている のかというマニュアルもご覧ください。 これは 完全修飾形式の定数 には適用されず、この場合は未定義なら Error が発生します。

注意: 定数が設定されているかを確認するには、defined() 関数を使って下さい。

変数との違いは次のようになります。

  • 定数は、前にドル記号($)を要しません。
  • 定数は、定義することができ、変数のスコープ規則に関係なく、あら ゆる場所からアクセス可能です。
  • 定数は一度設定されると再定義または未定義とすることはできません。
  • 定数は、スカラー値と配列としてのみ評価可能です。

例1 定数の定義

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // "Hello world."を出力
echo Constant; // エラーが発生: Undefined constant "Constant"
// PHP 8.0.0 より前のバージョンでは、"Constant" を出力し、警告が発生
?>

例2 const キーワードによる定数の定義

<?php
// 単純なスカラー値
const CONSTANT = 'Hello World';

echo CONSTANT;

// スカラー式
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // 出力は "cat"

// 配列の定数
define('ANIMALS', array(
'dog',
'cat',
'bird'
));
echo ANIMALS[1]; // 出力は "cat"
?>

注意:

define() による定数の定義とは反対に、 const キーワードで定義した定数はトップレベルのスコープで宣言しなければなりません。 これはコンパイル時に定義されるからです。 つまり、関数、ループ、if 文、または try/catch ブロックの内部では宣言できないということです。

注意:

PHP 8.0.0 より前のバージョンでは、define() 関数を使って定義された定数は、 大文字小文字を区別しません。

参考

  • クラス定数


自動的に定義される定数

PHPには実行されるスクリプトで使用可能な多くの 定義済みの定数があります。 しかし、これらの定数の多くは、種々の拡張モジュールにより作成され、 動的なロードやコンパイル時の組込みにより、これらの拡張モジュールが 使用可能である場合にのみ定義されます。


マジック定数

使われる場所によって値が変化する定数（マジック定数）が 9 つあります。 例えば、__LINE__はスクリプト上において 使われる行によって値が変化します。 これらの "マジック"定数は、実行時に解決される通常の定数とは異なり、コンパイル時に解決されます。 これらの特別な定数は大文字小文字を区別しません。 内容は以下のとおりです:

PHP の "マジック" 定数
名前 | 説明
__LINE__ | ファイル上の現在の行番号。
__FILE__ | ファイルのフルパスとファイル名 (シンボリックリンクを解決した後のもの)。 インクルードされるファイルの中で使用された場合、インクルードされるファイルの名前が返されます。
__DIR__ | そのファイルの存在するディレクトリ。include の中で使用すると、 インクルードされるファイルの存在するディレクトリを返します。 つまり、これは dirname(__FILE__) と同じ意味です。 ルートディレクトリである場合を除き、ディレクトリ名の末尾にスラッシュはつきません。
__FUNCTION__ | 関数名。無名関数の場合は、{closure}
__CLASS__ | クラス名。 クラス名には、そのクラスが宣言されている名前空間も含みます (例 Foo\Bar)。 トレイトのメソッド内で __CLASS__ を使うと、 そのトレイトを use しているクラスの名前を返します。
__TRAIT__ | トレイト名。 トレイト名には、宣言された名前空間も含みます (例 Foo\Bar)。
__METHOD__ | クラスのメソッド名。
__NAMESPACE__ | 現在の名前空間の名前。
ClassName::class | 完全に修飾されたクラス名。

参考

  • ::class
  • 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 種類のスカラー型: 整数(int)、 浮動小数点数(float)、文字列(string)、 真偽値(bool) をサポートします。 (スカラーとは、配列とかと異なり、より小さな部分に'分割する'ことができない値のことです。) 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 項演算子は、この演算子+代入式のモードで使用することができます。

もう一種類、三項演算子(ternary operator)を用いた式がありますが、 他の言語で見たことがない場合には理解できないかもしれません。

<?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 とします。

演算子の優先順位が等しい場合は、その結合性によって評価順 (右から評価するのか、あるいは左から評価するのか) が決まります。 たとえば "-" は左結合なので、 1 - 2 - 3 は (1 - 2) - 3 とグループ分けされて、 評価結果は -4 になります。 一方、"=" は右結合です。つまり $a = $b = $c のグループ分けは $a = ($b = $c) となります。

優先順位が同じで結合しない演算子を並べることはできません。つまり、たとえば 1 < 2 > 1 は PHP では無効になります。 一方 1 <= 1 == 1 は問題ありません。 == 演算子の優先順位が <= 演算子より低いからです。

演算子の結合は、 二項演算子(および三項演算子) の場合にだけ意味があります。 単項演算子は、前置または後置しかないため、 演算子の結合の考え方は適用できません。 たとえば、 !!$a は、 !(!$a) という形でのみグループ化できます。

厳密には不要な場所であっても、括弧をつけておけばコードの可読性があがります。 明示的にグループ分けをしておくことで、演算子の優先順位や結合性による暗黙のグループ分けに頼らずに済むからです。

次の表では、優先順位が高い順に演算子を挙げています。 同じ行にある演算子は優先順位が等しくなります。そのような場合は、 結合時の評価にしたがってグループ分けが決まります。

演算子の優先順位
結合時の評価 | 演算子 | 追加情報
(n/a) | clone new | clone および new
right | ** | 算術演算子
(n/a) | + - ++ -- ~ (int) (float) (string) (array) (object) (bool) @ | 算術演算子 (単項演算の + と -), 加算子/減算子, ビット演算子, 型の相互変換 そして エラー制御演算子
left | instanceof | 型演算子
(n/a) | ! | 論理演算子
left | * / % | 算術演算子
left | + - . | 算術演算子 (二項演算の + と -), 配列演算子 そして 文字列演算子 (PHP 8.0.0 より前のバージョンの.)
left | << >> | ビット演算子
left | . | 文字列演算子 (PHP 8.0.0 以降)
結合しない | < <= > >= | 比較演算子
結合しない | == != === !== <> <=> | 比較演算子
left | & | ビット演算子 そして リファレンス
left | ^ | ビット演算子
left | | | ビット演算子
left | && | 論理演算子
left | || | 論理演算子
right | ?? | NULL合体演算子
結合しない | ? : | 三項演算子 (PHP 8.0.0 より前のバージョンでは、左結合でした)
right | = += -= *= **= /= .= %= &= |= ^= <<= >>= ??= | 代入演算子
(n/a) | yield from | yield from
(n/a) | yield | yield
(n/a) | print | print
left | and | 論理演算子
left | xor | 論理演算子
left | or | 論理演算子

例1 結合時の評価

<?php
$a = 3 * 3 % 5; // (3 * 3) % 5 = 4
// PHP の三項演算子の結合法則は、C/C++のそれとは異なります
$a = true ? 0 : true ? 1 : 2; // PHP 8.0.0 より前のバージョンでは、(true ? 0 : true) ? 1 : 2 = 2

$a = 1;
$b = 2;
$a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
?>

演算子の優先順位や結合性は、あくまでも式のグループ分けだけを決めるものであり、評価順を決めるものではありません。 PHP では一般に、式をどの順番で評価するかは決めていません。 そのため、特定の順序で式が評価されることを前提としたコードを書いてはいけません。 PHP のバージョンが変わったり前後のコードが変わったりしたときに、評価順が変わる可能性があるからです。

例2 評価順序は未定義

<?php
$a = 1;
echo $a + $a++; // 2 になるかもしれないし、3 になるかもしれません

$i = 1;
$array[$i] = $i++; // インデックス 1 をセットするかもしれないし、インデックス 2 をセットするかもしれません
?>

例3 +、-、. の優先順位は同じ(PHP 8.0.0 より前のバージョン)

<?php
$x = 4;
// 次の行は、予期せぬ結果になることでしょう
echo "x minus one equals " . $x-1 . ", or so I hope\n";
// なぜなら、これは次のように評価されるからです(PHP 8.0.0より前のバージョン)
echo (("x minus one equals " . $x) - 1) . ", or so I hope\n";
// 期待どおりの結果を得るには、括弧を使って優先順位を指定します
echo "x minus one equals " . ($x-1) . ", or so I hope\n";
?>

上の例の出力は以下となります。

-1, or so I hope
-1, or so I hope
x minus one equals 3, or so I hope

注意:

= は他のほとんどの演算子よりも優先順位が低いはずなのにもかかわらず、 PHP は依然として if (!$a = foo()) のような式も許します。この場合は foo() の戻り値が $a に代入されます。

変更履歴

バージョン | 説明
8.0.0 | 文字列の連結 (.) の優先順位は、 算術演算子の加算/減算 (+ および -) と ビットシフト演算子 (<< および >>); よりも低くなりました。 これより前のバージョンでは、文字列の連結は + と - と同じ優先順位を持ち、 << と >> よりは高い優先順位を持っていました。
8.0.0 | 三項演算子 (? :) は、 どの演算とも結合しなくなりました。 これより前のバージョンでは、左結合でした。
7.4.0 | 三項演算子(? :) が左結合であることに依存すること、 つまり、括弧で囲わずに三項演算子をネストすることは推奨されなくなりました。
7.4.0 | 文字列の連結 (.) 演算と、 算術演算子の加算/減算 (+ および -) と ビットシフト演算子 (<< および >>); の優先順位に依存するコードは、推奨されなくなりました。 つまり、これらを括弧を使わずに一緒に使うことは推奨されなくなりました。


算術演算子

学校で習った初等算術を憶えていますか? この演算子はそれらと同様に動作します。

算術演算子
例 | 名前 | 結果
+$a | 同一 | $a を、必要に応じて int あるいは float に変換する
-$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 の $b 乗。

除算演算子 ("/") の返す値は浮動小数点数となります。 ただし、ふたつのオペランドがともに整数 (あるいは整数に変換できる文字列) であり、かつ結果が割り切れる場合には整数値を返します。 整数の除算については intdiv() を参照ください。

剰余演算子は、まず両方のオペランドを整数に直してから処理を行います。 浮動小数点の剰余については fmod() を参照ください。

剰余演算子 % の結果の符号は、被除数の符号と同じになります。 つまり、$a % $b の結果の符号は $a と同じになるということです。

<?php

echo (5 % 3)."\n"; // 2
echo (5 % -3)."\n"; // 2
echo (-5 % 3)."\n"; // -2
echo (-5 % -3)."\n"; // -2

?>

参考

  • 数学関数


加算子/減算子

PHP は 加算子/減算子（前置・後置ともに）をサポートします。 これらの単項演算子は、値をインクリメント(ひとつ増や)したり、デクリメント(ひとつ減ら)したりできます。

加算子/減算子
例 | 名前 | 効果
++$a | 前置加算子 | $a をインクリメントし、$a を返します。
$a++ | 後置加算子 | $a を返し、$a をインクリメントします。
--$a | 前置減算子 | $a をデクリメントし、$a を返します。
$a-- | 後置減算子 | $a を返し、$a をデクリメントします。

以下に簡単なスクリプトの例を示します:

<?php
echo '後置加算:', PHP_EOL;
$a = 5;
var_dump($a++);
var_dump($a);

echo '前置加算:', PHP_EOL;
$a = 5;
var_dump(++$a);
var_dump($a);

echo '後置減算:', PHP_EOL;
$a = 5;
var_dump($a--);
var_dump($a);

echo '前置減算:', PHP_EOL;
$a = 5;
var_dump(--$a);
var_dump($a);
?>

上の例の出力は以下となります。

後置加算:
int(5)
int(6)
前置加算:
int(6)
int(6)
後置減算:
int(5)
int(4)
前置減算:
int(4)
int(4)
警告

bool 型の値に、加算子や減算子を適用しても何も起こりません。 PHP 8.3.0 以降では、この操作に対して E_WARNING が発生するようになりました。なぜなら、bool 型の値を暗黙のうちに数値型にキャストするように将来変更されるからです。

null 型の値に、減算子を適用しても何も起こりません。 PHP 8.3.0 以降では、この操作に対して E_WARNING が発生するようになりました。なぜなら、null 型の値を暗黙のうちに数値型にキャストするように将来変更されるからです。

数値形式の文字列 でない文字列に対して、減算子を適用しても何も起こりません。 PHP 8.3.0 以降では、この操作に対して E_WARNING が発生するようになりました。なぜなら、こうした操作は TypeError がスローされるように将来変更されるからです。

注意:

加算や減算の振る舞いをオーバーロードする機能をサポートしている内部オブジェクトも、インクリメントしたり、デクリメントしたりできます。このような内部オブジェクトの例としては、GMP が挙げられます。

Perl 風の、文字列をインクリメントする機能

警告

この機能は、PHP 8.3.0 以降は soft-deprecated 扱い (E_DEPRECATED は発生しないものの、新しいコードではこの機能を使うべきではない) になっています。 str_increment() を代わりに使いましょう。

PHP では、数値形式の文字列 でない文字列をインクリメントすることも可能です。この場合、文字列は英数字からなる、ASCII 文字列である必要があり、文字を次の文字に変更します。文字が Z に達すると、左の文字がひとつ繰り上がります。たとえば、$a = 'Z'; $a++; というコードは、$a を 'AA' に変更します。

例1 Perl 風に、文字列をインクリメントする例

<?php
echo '== アルファベットからなる文字列 ==' . PHP_EOL;
$s = 'W';
for ($n=0; $n<6; $n++) {
echo ++$s . PHP_EOL;
}
// 英数字からなる文字列は、異なる振る舞いをします
echo '== 英数字からなる文字列 ==' . PHP_EOL;
$d = 'A8';
for ($n=0; $n<6; $n++) {
echo ++$d . PHP_EOL;
}
$d = 'A08';
for ($n=0; $n<6; $n++) {
echo ++$d . PHP_EOL;
}
?>

上の例の出力は以下となります。

== アルファベットからなる文字列 ==
X
Y
Z
AA
AB
AC
== 英数字からなる文字列 ==
A9
B0
B1
B2
B3
B4
A09
A10
A11
A12
A13
A14
警告

英数字からなる文字列が、数値形式の文字列 として解釈できる場合、その値は int または float にキャストされます。この挙動は、文字列が科学的記法で書かれた浮動小数点数の場合に特に問題になります。str_increment() を使えば、こうした暗黙の型変換の影響を受けません。

例2 英数字が浮動小数点数にキャストされる挙動

<?php
$s = "5d9";
var_dump(++$s);
var_dump(++$s);
?>

上の例の出力は以下となります。

string(3) "5e0"
float(6)

上記の出力になる理由は、"5e0" という値が float として解釈され、インクリメントされる前に 5.0 にキャストされるためです。


代入演算子

代入演算子の基本となるものは "=" です。この演算子に関して最初に 思い付く意味は"等しい"であるかもしれません。しかし、そうではありません。 本当は、左オペランドに右オペランドの式の値を設定する("得て代入する") ことを意味します。

代入式の値は、代入される値です。つまり、"$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 では通常は値による代入になりますが、 オブジェクトは参照で代入されます。 オブジェクトを明示的にコピーするには 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 であり、その値が変わったからです
?>

new 演算子は自動的に参照を返します。そのため、 new の結果を参照で代入するとエラーが発生します。

<?php
class C {}

$o = &new C;
?>

上の例の出力は以下となります。

Parse error: syntax error, unexpected 'new' (T_NEW) in ...

参照に関する詳細な情報やその使い方については、このマニュアルの リファレンスに関する説明 をご覧ください。

算術代入演算子

例 | 同一の結果になる操作 | 演算
$a += $b | $a = $a + $b | 加算
$a -= $b | $a = $a - $b | 減算
$a *= $b | $a = $a * $b | 乗算
$a /= $b | $a = $a / $b | 除算
$a %= $b | $a = $a % $b | 剰余
$a **= $b | $a = $a ** $b | べき乗

ビット代入演算子

例 | 同一の結果になる操作 | 演算
$a &= $b | $a = $a & $b | ビット積
$a |= $b | $a = $a | $b | ビット和
$a ^= $b | $a = $a ^ $b | 排他的論理和
$a <<= $b | $a = $a << $b | 左シフト
$a >>= $b | $a = $a >> $b | 右シフト

その他の代入演算子

例 | 同一の結果になる操作 | 演算
$a .= $b | $a = $a . $b | 文字列の結合
$a ??= $b | $a = $a ?? $b | Null合体

参考

  • 算術演算子
  • ビット演算子
  • Null 合体演算子


ビット演算子

ビット演算子は、整数値の特定のビットの評価や操作を行います。

ビット演算子
例 | 名前 | 結果
$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 値を使って行います。その結果は文字列になります。 それ以外の場合は、左右のオペランドを integer に変換 し、結果も integer になります。

~ 演算子のオペランドが文字列の場合、その演算は、 文字列を構成する文字の ASCII 値を使って行います。その結果は文字列になります。 それ以外の場合は、オペランドや演算結果を integer として扱います。

<< および >> 演算子のオペランドとその結果は、常に integer として扱います。

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

警告

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。
$a <=> $b | 宇宙船演算子 | $a が $b より小さい場合は、0より小さい整数。 $a が $b と等しい場合は、0。 $a が $b より大きい場合は、0より大きい整数。

オペランドが両方 数値形式の文字列 の場合、 もしくは一方が数値で、もう一方が 数値形式の文字列 の場合、 比較は数値として行われます。 これらのルールは switch 文にも適用されます。 型の変換は 演算子が === や !== の場合は行われません。 なぜなら、これらの演算子は、値と型を両方比較するものだからです。

警告

PHP 8.0.0 より前のバージョンでは、 文字列が数値または数値形式の文字列の場合、文字列は比較する前に数値に変換されていました。 これによって、以下の例で見られるような驚きの結果が生じる場合があります:

<?php
var_dump(0 == "a");
var_dump("1" == "01");
var_dump("10" == "1e1");
var_dump(100 == "1e2");

switch ("a") {
case 0:
echo "0";
break;
case "a":
echo "a";
break;
}
?>

上の例の PHP 7 での出力は、このようになります。

bool(true)
bool(true)
bool(true)
bool(true)
0

上の例の PHP 8 での出力は、このようになります。:

bool(false)
bool(true)
bool(true)
bool(true)
a

<?php
// Integer
echo 1 <=> 1; // 0
echo 1 <=> 2; // -1
echo 2 <=> 1; // 1

// Float
echo 1.5 <=> 1.5; // 0
echo 1.5 <=> 2.5; // -1
echo 2.5 <=> 1.5; // 1

// 文字列
echo "a" <=> "a"; // 0
echo "a" <=> "b"; // -1
echo "b" <=> "a"; // 1

echo "a" <=> "aa"; // -1
echo "zz" <=> "aa"; // 1

// 配列
echo [] <=> []; // 0
echo [1, 2, 3] <=> [1, 2, 3]; // 0
echo [1, 2, 3] <=> []; // 1
echo [1, 2, 3] <=> [1, 2, 1]; // 1
echo [1, 2, 3] <=> [1, 2, 4]; // -1

// オブジェクト
$a = (object) ["a" => "b"];
$b = (object) ["a" => "b"];
echo $a <=> $b; // 0

$a = (object) ["a" => "b"];
$b = (object) ["a" => "c"];
echo $a <=> $b; // -1

$a = (object) ["a" => "c"];
$b = (object) ["a" => "b"];
echo $a <=> $b; // 1

// 比較するのは値だけではない; キーも一致しなければならない
$a = (object) ["a" => "b"];
$b = (object) ["b" => "b"];
echo $a <=> $b; // 1

?>

多くの型では、以下の表にしたがって（上から順に）比較が行われます。

さまざまな型の比較
第 1 オペランドの型 | 第 2 オペランドの型 | 結果
null または string | string | null を "" に変換し、数値または文字として比較します
bool または null | あらゆる型 | 両辺を bool に変換し、false < true と判断します
object | object | 組み込みクラスには独自の比較基準が定義されています。 異なるクラスは比較できません。同じクラスであるかどうかは ここで説明されています。
string, resource, int または float | string, resource, int または float | 文字列やリソースを数値に変換し、算術演算を行います
array | array | 要素数の少ない配列のほうが小さくなります。オペランド 1 のキーが オペランド 2 に存在しない場合、配列は比較できません。そうでない場合は 個々の要素の値を比較します（以下の例を参照ください）
object | あらゆる型 | object のほうが常に大きくなります
array | あらゆる型 | array のほうが常に大きくなります

例1 Boolean/null の比較

<?php
// Bool and null are compared as bool always
var_dump(1 == TRUE); // TRUE - same as (bool)1 == TRUE
var_dump(0 == FALSE); // TRUE - same as (bool)0 == FALSE
var_dump(100 < TRUE); // FALSE - same as (bool)100 < TRUE
var_dump(-10 < FALSE);// FALSE - same as (bool)-10 < FALSE
var_dump(min(-100, -10, NULL, 10, 100)); // NULL - (bool)NULL < (bool)-100 is FALSE < TRUE
?>

例2 一般的な配列の比較

<?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 1;
} elseif ($val < $op2[$key]) {
return -1;
} elseif ($val > $op2[$key]) {
return 1;
}
}
return 0; // $op1 == $op2
}
?>

警告

浮動小数点数値の比較

ふたつの float 値が等しいかどうかを調べてはいけません。 float の内部的な表現方法がその理由です。

詳細な情報は float のドキュメントを参照ください。

注意: PHP における型の相互変換の動作は、 異なる型同士を比較する時には必ずしも自明でないことに注意して下さい。 整数型 と boolean を比較したり、 整数型 を 文字列 と比較する場合は特にそうです。 よって一般的には、 == や != ではなく === と !== を使う方がほとんどの場合は好ましいです。

比較できない値

(=== や !== を使った) 同一性の比較は、あらゆる値に適用できますが、 それ以外の演算子は、比較できる値同士の場合にのみ適用可能です。 比較できない値同士を比較した場合の結果は未定義であり、 その結果に依存すべきではありません。

参考

  • strcasecmp()
  • strcmp()
  • Array operators
  • Types

三項演算子

もうひとつの条件演算子として "?:"（あるいは三項）演算子があります。

例3 デフォルト値を設定する

<?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 を値とします。

三項演算子のまんなかの部分をなくすこともできます。 式 expr1 ?: expr3 の結果は、expr1 が true と同等の場合は expr1、 それ以外の場合は expr3 となります。 この場合、expr1 は一度だけ評価されます。

注意: 三項演算子は式であり、値としては評価されずに式の結果として評価される ことに注意してください。演算結果をリファレンスとして返したい場合に、 これを知っておくことが大切です。結果をリファレンスとして返す関数で return $var == 42 ? $a : $b; とすることはできず、 警告が発生します。

注意:

三項演算子を "積み重ねて" 使用することは避けましょう。 ひとつの文の中で括弧で囲わずに複数の三項演算子を使用した際の PHP の振る舞いは、 他のプログラミング言語のそれと比べて、少々わかりにくいものです。 PHP 8.0.0 より前のバージョンでは、三項演算子は左から右に評価されていました。 他の殆どのプログラミング言語では、右から左に評価されます。 左から右に評価される振る舞いに依存することは、PHP 7.4.0 以降は推奨されません。 PHP 8.0.0 以降は、三項演算子はどの演算とも結合しなくなっています。

例4 三項演算子のわかりにくい挙動

<?php
// ぱっと見た感じでは、これは 'true' と表示されると思うでしょう。
echo (true ? 'true' : false ? 't' : 'f');

// しかし、PHP 8.0.0 より前のバージョンでは、実際には上の出力結果は 't' です。
// なぜなら、三項演算子は左結合だったからです。

// 上のコードをもう少しわかりやすく書くと、このようになります。
echo ((true ? 'true' : false) ? 't' : 'f');

// まず、最初の式が 'true' と評価されます。この 'true' は
// (bool)true と評価されるので、それをもとに二番目の三項
// 演算子が評価されます。
?>

注意:

一方で、三項演算子の短縮形の挙動は安定しており、 理にかなった動作をします。 これは、false と評価されない最初の引数を評価します。 但し、未定義の値については未だ警告が出るので注意して下さい。

例5 三項演算子の短縮形

<?php
echo 0 ?: 1 ?: 2 ?: 3, PHP_EOL; //1
echo 0 ?: 0 ?: 2 ?: 3, PHP_EOL; //2
echo 0 ?: 0 ?: 0 ?: 3, PHP_EOL; //3
?>

Null 合体演算子

別の便利な短縮形式の演算子として、 "??" 演算子 (Null 合体演算子) を使うことが出来ます。

例6 デフォルト値の代入

<?php
// Null 合体演算子の使用例
$action = $_POST['action'] ?? 'default';

// 上の文は、この if/else 文と同じ意味です
if (isset($_POST['action'])) {
$action = $_POST['action'];
} else {
$action = 'default';
}
?>
式 (expr1) ?? (expr2) は、 expr1 が null である場合は expr2 と評価され、それ以外の場合は expr1 と評価されます。

この演算子は、左側の値が存在しない場合でも notice や warning が発生しません。 isset() と同じ挙動です。 これは、配列のキーを扱う場合に便利です。

注意: Null 合体演算子は式であることに注意しましょう。変数として評価されるのではなく、式の結果として評価されます。 変数を参照で返そうとするときには、これを意識しておくことが重要です。 参照返しの関数で return $foo ?? $bar; のように書いてもうまく動かずに、 警告が発生します。

注意:

Null 合体演算子の優先順位は低いです。 (文字列結合や、算術演算子のような) 他の演算子と組み合わせる場合には、おそらくカッコが必要になるでしょう。

<?php
// $name が未定義の場合、警告が発生します。
print 'Mr. ' . $name ?? 'Anonymous';
// "Mr. Anonymous" と出力
print 'Mr. ' . ($name ?? 'Anonymous');
?>

注意:

Null 合体演算子はネストさせることもできます。

例7 Null 合体演算子のネスト

<?php

$foo = null;
$bar = null;
$baz = 1;
$qux = 2;

echo $foo ?? $bar ?? $baz ?? $qux; // 出力は 1 です

?>


エラー制御演算子

PHP はエラー制御演算子(@)をサポートしています。 PHP の式の前に付けた場合、 その式により生成されたエラーメッセージは無視されます。

set_error_handler() で自作のエラーハンドラを設定した場合は エラー制御演算子があってもそのエラーハンドラがコールされます。

警告

PHP 8.0.0 より前のバージョンでは、 エラー制御演算子(@)でエラーが無視されている場合、 カスタムのエラーハンドラでコールされた error_reporting() が常に 0 を返していました。 PHP 8.0.0 以降では、以下の (ビット和の) 値を返すようになっています: E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE

式によって生成されたあらゆるエラーメッセージは error_get_last() 関数が返す配列要素 "message" から取得できます。 この関数の結果はエラーごとに変わります。よって速やかに確認する必要があります。

<?php
/* 意図的なエラー */
$my_file = @file ('non_existent_file') or
die ("Failed opening file: error was '" . error_get_last()['message'] . "'");

// この演算子は関数だけでなく、全ての式で動作します。
$value = @$cache[$key];
// インデックス $key が存在しない場合でも、警告を発生しません。

?>

注意: @ 演算子は、 式 に対してのみ動作します。基本的なルールは次のようになります。 値を得ることができるものの場合、 @ 演算子を前に付けることが可能です。 例えば、変数、関数、いくつかの言語構造(例: include) のコールなどの前に、この演算子をつけることが可能です。 関数またはクラスの定義、 if や foreach 等のような 条件構造の前には、この演算子を付けることはできません。

警告

PHP 8.0.0 より前のバージョンでは、 スクリプトの実行を停止させるような致命的な場合であっても @ 演算子でエラーメッセージを抑止することが可能でした。 たとえば、存在しなかったり、ミスタイプされていたり、 利用できない関数コールの前に @ 演算子を付けると、 原因を示すことなく、その場所でスクリプトは終了してしまっていました。

参考

  • error_reporting()
  • エラーハンドリングとロギング関数


実行演算子

PHP は 1 種類の実行演算子、バッククォート (``) をサポートします。 シングルクォートではないことに注意してください! PHP は、バッククォートの 中身をシェルコマンドとして実行しようとします。出力が返されます (すなわち、出力を単にダンプするのではなく、変数に代入することが できます) 。 バッククォート演算子の使用は shell_exec() と等価です。

<?php
$output = `ls -al`;
echo "<pre>$output</pre>";
?>

注意:

バッククォート演算子は、 shell_exec() が無効な場合は無効となります。

注意:

他の言語とは異なり、 ダブルクォートで囲まれた文字列の中でのバッククォート演算子には何の効力もありません。

参考

  • システムプログラムの実行
  • popen()
  • proc_open()
  • PHPをコマンドラインから使用する


論理演算子

論理演算子
例 | 名前 | 結果
$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 を代入してから "or" 演算子を評価します
// これは、次の式と同様です: (($f = false) or true)
$f = false or true;

var_dump($e, $f);

// --------------------
// "&&" の優先順位は "and" より高くなります

// $g に代入されるのは、(true && false) の評価結果です
// これは、次の式と同様です: ($g = (true && false))
$g = true && false;

// $h に true を代入してから "and" 演算子を評価します
// これは、次の式と同様です: (($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);

$a += $b; // Union of $a += $b is $a and $b
echo "Union of \$a += \$b: \n";
var_dump($a);
?>
このスクリプトを実行すると、以下のように出力されます。
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"
}
Union of $a += $b:
array(3) {
["a"]=>
string(5) "apple"
["b"]=>
string(6) "banana"
["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)

instanceof は、もし確かめる変数がオブジェクトでなくてもエラーになりません。単に false を返すだけです。ただし、PHP 7.3.0 以前では、定数を調べることはできませんでした。

例6 instanceof での他の変数の調べかた

<?php
$a = 1;
$b = NULL;
$c = imagecreate(5, 5);
var_dump($a instanceof stdClass); // $a は配列です
var_dump($b instanceof stdClass); // $b は NULL です
var_dump($c instanceof stdClass); // $c はリソースです
var_dump(FALSE instanceof stdClass);
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(false)
PHP Fatal error:  instanceof expects an object instance, constant given

PHP 7.3.0 以降では、 instanceof の左辺値に定数を指定できるようになりました。

例7 instanceof を使って定数を確認する

<?php
var_dump(FALSE instanceof stdClass);
?>

上の例の PHP 7.3 での出力は、このようになります。

bool(false)

PHP 8.0.0 以降では、 instanceof は任意の式と一緒に使えるようになりました。 式は文字列を生成するもので、かつ括弧で囲む必要があります。

例8 instanceof を任意の式と一緒に使う

<?php

class ClassA extends \stdClass {}
class ClassB extends \stdClass {}
class ClassC extends ClassB {}
class ClassD extends ClassA {}

function getSomeClass(): string
{
return ClassA::class;
}

var_dump(new ClassA instanceof ('std' . 'Class'));
var_dump(new ClassB instanceof ('Class' . 'B'));
var_dump(new ClassC instanceof ('Class' . 'A'));
var_dump(new ClassD instanceof (getSomeClass()));
?>

上の例の PHP 8 での出力は、このようになります。:

bool(true)
bool(true)
bool(false)
bool(true)

instanceof 演算子は、is_a() 関数とは機能的に異なる部分があります。

参考

  • get_class()
  • is_a()


制御構造

目次

  • はじめに
  • if
  • else
  • elseif/else if
  • 制御構造に関する別の構文
  • while
  • do-while
  • for
  • foreach
  • break
  • continue
  • switch
  • match
  • declare
  • return
  • require
  • include
  • require_once
  • include_once
  • goto


はじめに

すべての PHP スクリプトは、一連の文からなります。 文としては、代入、関数コール、ループ、条件文、そして何もしない文(空の文) さえ使用することができます。 文は、通常セミコロンで終了します。加えて、文は、中括弧によるグループ文で カプセル化することによりグループ化することが可能です。 グループ文は、同時に文にもなります。 本章では、様々な文の型について説明します。

参考

以下は、このマニュアルで関数として参照されていますが、言語構造の一部とも見なされています。

  • list()
  • array()
  • echo
  • eval()
  • print


if

(PHP 4, PHP 5, PHP 7, PHP 8)

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, PHP 7, PHP 8)

ある条件が満たされている場合にある文を実行し、 その条件が満たされていない場合に別の文を実行したいと考えた ことが度々あるかと思います。 このために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参照)

注意: else がぶら下がる場合

if-else 文がネストした場合、 else は常に、もっとも近い if 文に関連付けられます。

<?php
$a = false;
$b = true;
if ($a)
if ($b)
echo "b";
else
echo "c";
?>
どうインデントされているかに関わらず (PHP では、インデントは結果に影響しません)、 else は if ($b) に関連付けられます。 よって、この例は何も出力しません。 この振る舞いが正しいことに依存している場合、 曖昧さを解決するために波括弧を使うことを推奨します。


elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

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 7, PHP 8)

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;
?>

注意:

同じブロック内で別の構文を混ぜて使うことはできません。

警告

switch 文と最初の case の間で何か (空白文字も含む) を出力すると、構文エラーになります。 たとえば、以下のコードは無効です。

<?php switch ($foo): ?>
 <?php case 1: ?>
 ...
<?php endswitch; ?>

一方、以下のコードは有効です。というのも、 switch 文の行末の改行文字は終了タグ ?> の一部と見なされるため、 switch と case の間では何も出力されないからです。

<?php switch ($foo): ?>
<?php case 1: ?>
 ...
<?php endswitch; ?>

while、 for、および if に、より多くの例があります。


while

(PHP 4, PHP 5, PHP 7, PHP 8)

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, PHP 7, PHP 8)

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);
?>

この技のかわりに goto 演算子を使うこともできます。


for

(PHP 4, PHP 5, PHP 7, PHP 8)

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 < count($people); ++$i) {
$people[$i]['salt'] = mt_rand(000000, 999999);
}
?>

このコードは実行速度が遅くなることでしょう。 というのも、配列のサイズを毎回取得しているからです。 サイズが変わることはありえないのだから、これは簡単に最適化することができます。 配列のサイズを変数に格納して使うようにすれば、 何度も count() を呼ばずに済むのです。

<?php
$people = array(
array('name' => 'Kalle', 'salt' => 856412),
array('name' => 'Pierre', 'salt' => 215863)
);

for($i = 0, $size = count($people); $i < $size; ++$i) {
$people[$i]['salt'] = mt_rand(000000, 999999);
}
?>


foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

foreach は、配列を反復処理するための便利な方法です。 foreach が使えるのは配列とオブジェクトだけであり、 別のデータ型や初期化前の変数に対して使うとエラーになります。 この構造には二種類の構文があります。

foreach (iterable_expression as $value)
    文
foreach (iterable_expression as $key => $value)
    文

最初の形式は、iterable_expression で指定した反復可能な値に 関してループ処理を行います。各反復において現在の要素の値が $valueに代入されます。

2番目の形式は、さらに各反復で現在の要素のキーを変数 $keyに代入します。

foreach は、 current() や key() のような関数で使われる、内部的な配列のポインタを変更しない点に注意して下さい。

オブジェクトの反復処理をカスタマイズ することもできます。

ループの中で配列の要素を直接変更したい場合は、 $value の前に & をつけます。こうすると、変数には リファレンス が代入されることになります。

<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
$value = $value * 2;
}
// $arr は array(2, 4, 6, 8) となります
unset($value); // 最後の要素への参照を解除します
?>

警告

foreach ループを終えた後でも、 $value は配列の最後の要素を参照したままとなります。 unset() でその参照を解除しておくようにしましょう。 さもないと、次のような目に遭うことになるでしょう。

<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
$value = $value * 2;
}
// この時点で、$arr は array(2, 4, 6, 8) となります

// unset($value) しなければ、$value は今でも最後の要素 ($arr[3]) を指したままです

foreach ($arr as $key => $value) {
// $arr[3] が、$arr の各要素で上書きされて...
echo "{$key} => {$value} ";
print_r($arr);
}
// ...つまり、二番目から最後までの値が最後の値にコピーされていきます

// 出力
// 0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
// 1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
// 2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
// 3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
?>

配列定数の値を、参照によって反復処理させることもできます。

<?php
foreach (array(1, 2, 3, 4) as &$value) {
$value = $value * 2;
}
?>

注意:

foreach は、@ によりエラーメッセージ出力を抑制する機能をサポートしていません。

使用法を示すためにその他の例を示します。

<?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";
}
?>

ネストした配列の list() による展開

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

配列の配列の反復処理を行うこともできます。 値として list() を渡すと、 ネストした配列をループ変数に展開できます。

例を示します。

<?php
$array = [
[1, 2],
[3, 4],
];

foreach ($array as list($a, $b)) {
// $a にはネストした配列の最初の要素が含まれ、
// $b には二番目の要素が含まれます。
echo "A: $a; B: $b\n";
}
?>

上の例の出力は以下となります。

A: 1; B: 2
A: 3; B: 4

list() で指定する要素数を、ネストした配列の要素数より少なくしてもかまいません。 その場合は、配列の残りの要素は無視されます。

<?php
$array = [
[1, 2],
[3, 4],
];

foreach ($array as list($a)) {
// $b を指定していないことに注目。
echo "$a\n";
}
?>

上の例の出力は以下となります。

1
3

list() で指定した変数を埋めるだけの要素が足りないときには、notice が発生します。

<?php
$array = [
[1, 2],
[3, 4],
];

foreach ($array as list($a, $b, $c)) {
echo "A: $a; B: $b; C: $c\n";
}
?>

上の例の出力は以下となります。

Notice: Undefined offset: 2 in example.php on line 7
A: 1; B: 2; C:

Notice: Undefined offset: 2 in example.php on line 7
A: 3; B: 4; C:


break

(PHP 4, PHP 5, PHP 7, PHP 8)

breakは、現在実行中の for, foreach, while, do-while, switch 構造の実行を終了します。

break では、オプションの引数で ネストしたループ構造を抜ける数を指定することができます。 この引数のデフォルトは 1 で、直近のループ構造からだけ抜けます。

<?php
$arr = array('one', 'two', 'three', 'four', 'stop', 'five');
foreach ($arr as $val) {
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;
}
}
?>


continue

(PHP 4, PHP 5, PHP 7, PHP 8)

continue は、ループ構造において現在の繰り返しループ の残りの処理をスキップし、条件式を評価した後に 次の繰り返しの最初から実行を続けるために使用されます、

注意: PHP では、continue の動作に関しては switch 文がループ構造とみなされます。 continue に引数を渡さなかった場合の動きは break と同じですが、間違いの元なので警告が生成されます。 switch がループ内にある場合、 continue 2 とすると、外側のループの次回の処理から続行します。

continueでは、オプションの引数で 処理をスキップするループ構造のレベルの数を指定できます。 デフォルト値は 1 で、 これは現在のループの終了地点までスキップします。

<?php
$arr = ['zero', 'one', 'two', 'three', 'four', 'five', 'six'];
foreach ($arr as $key => $value) {
if (0 === ($key % 2)) { // キーが偶数の組をスキップします
continue;
}
echo $value . "\n";
}
?>

上の例の出力は以下となります。

one
three
five
<?php
$i = 0;
while ($i++ < 5) {
echo "Outer\n";
while (1) {
echo "Middle\n";
while (1) {
echo "Inner\n";
continue 3;
}
echo "This never gets output.\n";
}
echo "Neither does this.\n";
}
?>

上の例の出力は以下となります。

Outer
Middle
Inner
Outer
Middle
Inner
Outer
Middle
Inner
Outer
Middle
Inner
Outer
Middle
Inner

continue の後のセミコロンを省略すると混乱を生じることがあります。 以下の例のようなことをしてはいけません。

<?php
for ($i = 0; $i < 5; ++$i) {
if ($i == 2)
continue
print "$i\n";
}
?>

これは、以下のような結果になることを期待していたのでしょう。

0
1
3
4

continue の変更履歴
バージョン | 説明
7.3.0 | switch 内部で break 文のように振る舞おうとする continue については、E_WARNING が発生するようになりました。


switch

(PHP 4, PHP 5, PHP 7, PHP 8)

switch文は、同じ式を用いてIF文を並べたのに似ています。 同じ変数を異なる値と比較し、値に応じて異なったコードを実行したいと 思うことがしばしばあるかと思います。 switch文は、まさにこのためにあるのです。

注意: 他の言語とは違って、 continue命令は switch にも適用され、breakと同じ動作をします。 ループの内部で switch を使用しており、 外側のループの処理を続行させたい場合には、continue 2 を使用してください。

注意:

switch/case が行うのは、 緩やかな比較 であることに注意しましょう。

次の二つの例は、同じことを二つの異なった方法で書いたものです。 一つは、if と elseif文を、 もう一つはswitch文を使っています。 どちらも、出力は同じです。

例1 switch 文の構造

<?php
// これが switch 文です:

switch ($i) {
case 0:
echo "iは0に等しい";
break;
case 1:
echo "iは1に等しい";
break;
case 2:
echo "iは2に等しい";
break;
}

// 上記は、下記と同じです:
if ($i == 0) {
echo "iは0に等しい";
} elseif ($i == 1) {
echo "iは1に等しい";
} elseif ($i == 2) {
echo "iは2に等しい";
}

?>

失敗を避けるためにswitch文がどのように実行されるのかを 理解することが重要です。 switch文は、行毎に実行されます。 (実際には、文毎に実行されます。)初めは、何も実行しません。 switch式の値と同じ値として評価される式を有する case文が見つけられたときに初めてPHPにより 命令の実行が行われます。 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に等しくない";
}
?>

注意: 複数の default を置くと、 E_COMPILE_ERROR エラーが発生します。

注意: 技術的には、 default は switch 文の中のどの位置でも置くことができます。 default は他の case にマッチしなかった場合に使われるものです。 しかし、規約上は最後に置くのが一番です。

どの case にもマッチせず、 default も存在しない場合、 どのコードも実行されません。これは、 どの if 文も true でなかった場合と同じです。

case に与える値は、式であっても構いません。 しかし、式はそれ自体が実行され、 その結果が switch に与えた値と緩やかに比較されます。 これは、switch に与える値の複雑な評価には使えないということです。 たとえば、以下の例を見てみましょう:

<?php
$target = 1;
$start = 3;
switch ($target) {
case $start - 1:
print "A";
break;
case $start - 2:
print "B";
break;
case $start - 3:
print "C";
break;
case $start - 4:
print "D";
break;
}
// "B" を出力します。
?>

もっと複雑な比較を行うには、 true をswitch文の値として指定するやり方が使えます。 もしくは、switch文ではなく、 if-elseブロックが使えます。

<?php
$offset = 1;
$start = 3;
switch (true) {
case $start - $offset === 1:
print "A";
break;
case $start - $offset === 2:
print "B";
break;
case $start - $offset === 3:
print "C";
break;
case $start - $offset === 4:
print "D";
break;
}
// "B" を出力します。
?>

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 'ステラ';
case 'ハイネケン';
echo 'いいっすねぇ';
break;
default;
echo 'ほかのを選んでみませんか?';
break;
}
?>

参考

  • match


match

(PHP 8)

match 式は、値の一致をチェックした結果に基づいて評価結果を分岐します。 switch 文と似ていますが、 match 式は複数の候補と比較される制約式を持ちます。 switch 文とは異なり、 三項演算子のように値を評価します。 switch 文とは異なり、 弱い比較(==)ではなく、 型と値の一致チェック(===) に基づいて行われます。 match 式は PHP 8.0.0 以降で利用可能です。

例1 match 式の構造

<?php
$return_value = match (制約式) {
単一の条件式 => 返却式,
条件式1, 条件式2 => 返却式,
};
?>

例2 基本式な match 式の使い方

<?php
$food = 'cake';

$return_value = match ($food) {
'apple' => 'This food is an apple',
'bar' => 'This food is a bar',
'cake' => 'This food is a cake',
};

var_dump($return_value);
?>

上の例の出力は以下となります。

string(19) "This food is a cake"

例3 比較演算子と match 式を一緒に使う例

<?php
$age = 18;

$output = match (true) {
$age < 2 => "Baby",
$age < 13 => "Child",
$age <= 19 => "Teenager",
$age > 19 => "Young adult",
$age >= 40 => "Old adult"
};

var_dump($output);
?>

上の例の出力は以下となります。

string(8) "Teenager"

注意: match 式の結果は、必ずしも使う必要はありません。

注意: match 式は、必ずセミコロン ; で終わらなければなりません。

match 式は、 switch 文と似ていますが、いくつかの違いがあります:

  • match 式の比較は、 switch 文が行う弱い比較ではなく、 厳密に値を比較(===) します。
  • match 式は値を返します。
  • match 式の分岐は、 switch 文のように後の分岐に抜けたりはしません。
  • match 式は、全ての場合を網羅していなければいけません。

switch 文のように、 match 式はマッチさせる分岐をひとつひとつ実行します。 はじめは、コードは何も実行されません。 以前のすべての条件式が、制約式とマッチしなかった場合に条件式が実行されます。 条件式に一致する式が評価された場合に、返却式が評価されます。 たとえば、以下のようになります:

<?php
$result = match ($x) {
foo() => ...,
$this->bar() => ..., // foo() === $x であれば $this->bar() は呼び出されません。
$this->baz => beep(), // $x === $this->baz でなければ beep() は呼び出されません。
// などなど
};
?>

match 式の分岐は、複数の式をカンマ区切りで含めても構いません。 これは論理ORであり、複数の分岐の右辺を同じにする場合の短縮記法です。

<?php
$result = match ($x) {
// この分岐は:
$a, $b, $c => 5,
// 以下の3つの分岐と等しい:
$a => 5,
$b => 5,
$c => 5,
};
?>

default パターンという特別な場合があります。 このパターンは前の分岐にマッチしなかったあらゆる場合にマッチします。 たとえば、以下のようになります:

<?php
$expressionResult = match ($condition) {
1, 2 => foo(),
3, 4 => bar(),
default => baz(),
};
?>

注意: 複数の default パターンがあった場合、 E_FATAL_ERROR が発生します。

match 式は、全ての場合を網羅していなければいけません。 制約式がどの分岐でも処理できなかった場合、 UnhandledMatchError がスローされます。

例4 処理されない match 式の例

<?php
$condition = 5;

try {
match ($condition) {
1, 2 => foo(),
3, 4 => bar(),
};
} catch (\UnhandledMatchError $e) {
var_dump($e);
}
?>

上の例の出力は以下となります。

object(UnhandledMatchError)#1 (7) {
  ["message":protected]=>
  string(33) "Unhandled match value of type int"
  ["string":"Error":private]=>
  string(0) ""
  ["code":protected]=>
  int(0)
  ["file":protected]=>
  string(9) "/in/ICgGK"
  ["line":protected]=>
  int(6)
  ["trace":"Error":private]=>
  array(0) {
  }
  ["previous":"Error":private]=>
  NULL
}

厳密な一致チェックを行わずに match 式を使う

制約式に true を指定することで、 厳密な一致チェックを行わずに match 式を使うことができます。

例5 整数の範囲に応じてmatch式を分岐させる一般的な使い方

<?php

$age = 23;

$result = match (true) {
$age >= 65 => 'senior',
$age >= 25 => 'adult',
$age >= 18 => 'young adult',
default => 'kid',
};

var_dump($result);
?>

上の例の出力は以下となります。

string(11) "young adult"

例6 文字列の内容に応じてmatch式を分岐させる一般的な使い方

<?php

$text = 'Bienvenue chez nous';

$result = match (true) {
str_contains($text, 'Welcome') || str_contains($text, 'Hello') => 'en',
str_contains($text, 'Bienvenue') || str_contains($text, 'Bonjour') => 'fr',
// ...
};

var_dump($result);
?>

上の例の出力は以下となります。

string(2) "fr"


declare

(PHP 4, PHP 5, PHP 7, PHP 8)

declare 文は、あるコードブロックの中に 実行ディレクティブをセットするために使用します。declare の文法は他の制御構造と似ています。

declare (ディレクティブ)
    文

ディレクティブ の箇所で、セットされた declareブロックの挙動を指定することが出来ます。 現在のところ、使用できるディレクティブは ticks ( ticksに関しては以下を参照ください)、 encoding (encoding に関しては以下を参照ください)、 strict_types (型宣言のページの 厳密な型付け も参照ください) です。

ディレクティブの処理は、ファイルをコンパイルする際に行われるので、 ディレクティブの値として渡せるのは、リテラルだけとなります。 変数や定数は、使えません。以下に例を示します。

<?php
// これは有効です
declare(ticks=1);

// これは無効です
const TICK_VALUE = 1;
declare(ticks=TICK_VALUE);
?>

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'); // tick イベント発生

$a = 1; // tick イベント発生

if ($a > 0) {
$a += 2; // tick イベント発生
print $a; // tick イベント発生
}

?>

register_tick_function() および unregister_tick_function() も参照ください。

Encoding

スクリプトのエンコーディングをスクリプトごとに指定するには encoding ディレクティブを使用します。

例2 スクリプトのエンコーディングの宣言

<?php
declare(encoding='ISO-8859-1');
// ここにコードを書きます
?>

警告

名前空間と組み合わせて使用する場合、使用できる形式は declare(encoding='...'); のみです。... にエンコーディングを指定します。declare(encoding='...') {} は、名前空間と組み合わせるとパースエラーとなります。

zend.script_encoding も参照ください。


return

(PHP 4, PHP 5, PHP 7, PHP 8)

return は、プログラムの制御を呼び出し元に戻します。 呼び出し側のモジュールでは、呼び出しの次の式から続行します。

関数内で呼び出されると、return文は即座に その関数の実行を停止し、引数を関数の値として返します。 returnはまた、eval()文や スクリプト自体の実行を終了させることが出来ます。

グローバルスコープで呼び出されると、現在実行中のスクリプトが終了 します。もしそのスクリプトが include もしくは require されたものである場合、制御は呼び出し元 のファイルに戻ります。また、そのスクリプトが include されたものである場合は、returnに与えられた引数 の値は include の戻り値となります。 returnがメインスクリプトで呼び出された場合は スクリプトが終了します。また、 設定ファイルの auto_prepend_file 又は auto_append_fileオプションで指定されたスクリプトの場合も 同様にそのスクリプトが終了します。

さらに詳しい情報に関しては 戻り値を参照ください。

注意: return は関数ではなく言語構造であるため、 引数を括弧で囲う必要はなく、括弧の使用は推奨されないことに注意しましょう。

注意: パラメータを省略した場合は括弧も省略する必要があります。この場合の戻り値は null です。 return に括弧をつけてコールしながら何も引数を指定しないと、 パースエラーとなります。

PHP 7.1.0 以降では、戻り値の型を宣言している関数で、 かつ戻り値の型が void でない場合、 引数がない return 文を使うと E_COMPILE_ERROR が発生するようになりました。 戻り値の型が void の場合、 return 文に引数があると、同様のエラーが発生します。


require

(PHP 4, PHP 5, PHP 7, PHP 8)

require は include とほぼ同じですが、失敗した場合に E_COMPILE_ERROR レベルの致命的なエラーも発生するという点が異なります。 つまり、スクリプトの処理がそこで止まってしまうということです。一方 include の場合は、警告 (E_WARNING) を発するもののスクリプトの処理は続行します。

どのように動作するかについては include のドキュメントを参照ください。


include

(PHP 4, PHP 5, PHP 7, PHP 8)

include 式は指定されたファイルを読み込み、評価します。

以下の記述内容は require にも当てはまります。

ファイルのインクルードは、指定されたパスから行います。パスを指定しない場合は、 include_path の設定を利用します。 ファイルが include_path に見つからないときは、include は呼び出し元スクリプトのディレクトリと現在の作業ディレクトリも探します。 include は、ファイルを見つけられない場合に E_WARNING を発行します。一方 require の場合は、同じ場合に E_ERROR を発行する点が異なります。

include と require は、 ファイルがアクセスできない場合、 最終的に E_WARNING や E_ERROR を発生させる前に、 追加の E_WARNING を発生させることに注意して下さい。

パスを指定した場合 — 絶対パス (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 include ラッパー"が 有効になっている場合、ローカルなパス名 の代わりにURL(HTTP経由)を用いて読み込むファイルを指定することが可能です。 URLで指定されたサーバーがファイルをPHPコードとして解釈することが 出来る場合には、HTTP GETを使用してURLリクエストに引数を指定することが 出来ます。これはファイルの読み込み云々やスコープの継承とは関係なく、 ただ単純にスクリプトがリモートのサーバーで実行されて結果がローカルの スクリプトに読み込まれる、というだけのことです。

例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';
?>

警告

セキュリティの警告

リモートファイルはリモートサーバー上で実行されます（ファイルの拡張子や リモートサーバーが PHP の実行を許可しているかどうかに依存します）が、 有効な PHP スクリプトである必要があります。なぜならそれはローカル サーバー上で処理されるからです。もしリモートサーバー上で処理された結果が ほしいだけならば、readfile() を使用するほうがよい でしょう。そうでなければ、リモートスクリプトが有効な期待通りのコードを 生成していることを確認するため、注意を払うことが必要になります。

リモートファイル, fopen(), file()も参照ください。

値の返し方: include に失敗したときには FALSE を返し、警告を発生させます。 成功した場合の戻り値は、インクルードしたファイル側で変更していない限りは 1 です。 インクルードしたファイルの中で return を実行すれば、 そのファイルの処理をそこで止めて呼び出し元に処理を戻せます。 読み込まれたファイルから値を返すことも可能です。 通常の関数で行うのと同様にincludeコールの値を取得することができます。 しかし、読み込まれたリモートファイル(ローカルファイルの場合も同様)の出力が、 有効なPHPの開始／ 終了タグを有していない限り、リモートファイルを読み込む際に値を 取得することはできません。 必要な変数をこれらのタグの中で宣言することができ、これらの変数は ファイルが読み込まれた位置で使用可能となります。

include は特別な言語構造であるため、 引数の前後に括弧は不要です。 戻り値を比較する際には注意してください。

例4 インクルードの戻り値を比較する

<?php
// 動作しません。include(('vars.php') == TRUE) つまり、include('1') と評価されます
if (include('vars.php') == TRUE) {
echo 'OK';
}

// 動作します。
if ((include 'vars.php') == TRUE) {
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 の前後によらず メインファイルで使用できます。 このファイルが二度読み込まれた場合、関数が定義済みであるため 致命的なエラーが発生します。 ファイルが読み込み済みであるかどうかを調べ、 読み込まれるファイルの内容を条件分岐で返すかわりに 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, PHP 7, PHP 8)

require_once 式は require とほぼ同じ意味ですが、 ファイルがすでに読み込まれているかどうかを PHP がチェックするという点が異なります。 すでに読み込まれている場合はそのファイルを読み込みません。

_once の振る舞い、およびそれが _once なし版とどのように異なるのかについての情報は、 include_once のドキュメントを参照ください。


include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

include_once 命令は、スクリプトの実行時に指定 したファイルを読み込み評価します。この動作は、 include 命令と似ていますが、ファイルからのコー ドが既に読み込まれている場合は、再度読み込まれないという重要な違い があります。また、include_once は true を返します。その名が示す通り、ファイルは一度しか読み込まれません。

include_once は、スクリプトの実行時に同じファイ ルが複数回読み込まれ、評価される可能性がある場合に、関数の再定義や 変数値の再代入といった問題を回避するために一回だけ読み込ませるため に使用します。

この関数の動作についての情報は include のドキュメントを参照ください。


goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

What's the worse thing that could happen if you use goto?

この画像は » xkcd から提供いただいたものです。

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


関数

目次

  • ユーザー定義関数
  • 関数の引数
  • 戻り値
  • 可変関数
  • 内部（ビルトイン）関数
  • 無名関数
  • アロー関数
  • 第一級callableを生成する記法


ユーザー定義関数

関数は次のような構文で定義されます。

例1 関数の使用法を説明するための擬似コード

<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
echo "関数の例\n";
return $retval;
}
?>

関数の中では、他の関数や クラス 定義を含む PHP のあらゆる有効なコードを使用することができます。

関数名は、PHP の他のラベルと同じ規則に従います。関数名として有効な 形式は、まず文字かアンダースコアで始まり、その後に任意の数の文字・ 数字・あるいはアンダースコアが続くものです。正規表現で表すと、 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\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 は関数のオーバーロードをサポートしていません。 また、宣言された関数の定義を取り消したり再定義することも できません。

注意: 関数名は ASCII 文字 A から Z で構成されている場合、 大文字小文字を区別しませんが、 通常は関数宣言時と同じ名前で関数をコールする方が好ましいです。

可変引数 および デフォルト引数 の機能をサポートしています。 func_num_args(), func_get_arg(), func_get_args() に関する関数リファレンスを 参照ください。

PHP では、関数を再帰的にコールすることが可能です。

例4 再帰的な関数

<?php
function recursion($a)
{
if ($a < 20) {
echo "$a\n";
recursion($a + 1);
}
}
?>

注意: 100 から 200 を超えるようなレベルの再帰呼び出しは避けてください。そんなことをすると、 スタックが破壊され、スクリプトが異常終了してしまいます。 無限に続くような再帰処理は、プログラミングの間違いでしょう。


関数の引数

引数のリストにより関数へ情報を渡すことができます。 このリストは、カンマで区切られた式のリストです。 引数の評価は、関数が実際にコールされる前に、 左から右の順番で行われます(先行評価)。

PHP は、値渡し(デフォルト)、 リファレンス渡し、 デフォルト引数値 をサポートしています。また、 可変長引数リスト や、 名前付き引数 もサポートしています。

例1 関数に配列を渡す

<?php
function takes_array($input)
{
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>

PHP 8.0.0 以降では、引数リストの最後にカンマを付けることができます。 このカンマは無視されます。 これは、引数リストや変数名が長かったりした場合に、 引数を縦に並べるのに便利です。

例2 関数の引数リストの最後にカンマを付ける

<?php
function takes_many_args(
$first_arg,
$second_arg,
$a_very_long_argument_name,
$arg_with_default = 5,
$again = 'a default string', // この最後のカンマは、8.0.0 より前では許されません。
)
{
// ...
}
?>

引数のリファレンス渡し

デフォルトで、関数の引数は値で渡されます。(このため、関数の内部で 引数の値を変更しても関数の外側では値は変化しません。)関数がその引 数を修正できるようにするには、その引数をリファレンス渡しとする必要があり ます。

関数の引数を常にリファレンス渡しとしたい場合には、関数定義において アンパサンド(&) を引数名の前に付加することができます。

例3 関数のパラメータのリファレンス渡し

<?php
function add_some_extra(&$string)
{
$string .= 'and something extra.';
}
$str = 'This is a string, ';
add_some_extra($str);
echo $str; // 出力は 'This is a string, and something extra.' となります
?>

リファレンス渡しが想定されているところに、値渡しを行うとエラーになります。

デフォルト引数値

関数は、変数に代入する記法に似たやり方で、 デフォルト値を引数に定義することができます。 デフォルト値は引数が指定されなかった場合に使われますが、 null を渡した場合はデフォルト値を代入 しない ことに特に注意して下さい。

例4 関数におけるデフォルト引数の使用法

<?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.

デフォルト引数の値には、スカラー値、 配列、および特殊な型 null を指定できます。 PHP 8.1.0 以降では、 new ClassName() 記法を使ってオブジェクトも指定できます。

例5 スカラー型以外をデフォルト値として使用する

<?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");?>

例6 オブジェクトをデフォルト値として使用する(PHP 8.1.0 以降)

<?php
class DefaultCoffeeMaker {
public function brew() {
return 'Making coffee.';
}
}
class FancyCoffeeMaker {
public function brew() {
return 'Crafting a beautiful coffee just for you.';
}
}
function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
{
return $coffeeMaker->brew();
}
echo makecoffee();
echo makecoffee(new FancyCoffeeMaker);
?>

デフォルト値は、定数式である必要があり、 (例えば) 変数やクラスのメンバーであってはなりません。

デフォルト値を有する引数は、 デフォルト値がない引数の右側に全てある必要があることに注意して下さい。 そうでない場合、デフォルト値を指定していても、 呼び出し時に省略できません。 次の簡単なコードを見てみましょう。

例7 関数の引数のデフォルト値の 間違った使用法

<?php
function makeyogurt($container = "bowl", $flavour)
{
return "Making a $container of $flavour yogurt.\n";
}

echo makeyogurt("raspberry"); // $container に "raspberry" を指定します。$flavour ではありません。
?>

上の例の出力は以下となります。

Fatal error: Uncaught ArgumentCountError: Too few arguments
 to function makeyogurt(), 1 passed in example.php on line 42

ここで、上の例を次のコードと比べてみましょう。

例8 関数の引数のデフォルト値の 正しい使用法

<?php
function makeyogurt($flavour, $container = "bowl")
{
return "Making a $container of $flavour yogurt.\n";
}

echo makeyogurt("raspberry"); // $flavour に "raspberry" を指定します。
?>

上の例の出力は以下となります。

Making a bowl of raspberry yogurt.

PHP 8.0.0 以降では、 デフォルト値を指定した引数を複数スキップするために、 名前付き引数 が使えます。

例9 関数の引数のデフォルト値の 正しい使用法

<?php
function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")
{
return "Making a $container of $flavour $style yogurt.\n";
}

echo makeyogurt(style: "natural");
?>

上の例の出力は以下となります。

Making a bowl of raspberry natural yogurt.

PHP 8.0.0 以降では、 デフォルト値を指定した引数の後に、 必須の引数を宣言することは 推奨されません。 なぜなら、そのデフォルト値は絶対に使われないからです。 これは、デフォルト値を削除することで解決できます。 このルールの唯一の例外は、 Type $param = null と書かれた引数です。 null をデフォルトにすることは、 型が暗黙のうちに nullable であることを示しています。 この書き方はまだ許可されていますが、 以下のようにして 明示的に nullable 型 を使うことを推奨します:

例10 デフォルト値を指定した引数は、必須の引数の後に宣言する

<?php
function foo($a = [], $b) {} // デフォルト値が使われないため、PHP 8.0.0 以降は推奨されません
function foo($a, $b) {} // 上のコードと機能的には同じですが、推奨されない警告は発生しません。

function bar(A $a = null, $b) {} // まだ許可されています。$a は必須ですが、nullable です。
function bar(?A $a, $b) {} // 推奨される書き方です。
?>

注意: PHP 7.1.0 以降では、 デフォルト値を指定しないで引数を省略すると、 ArgumentCountError がスローされるようになりました。 これより前のバージョンでは、警告が発生していました。

注意: リファレンス渡しの引数にもデフォルト値を指定できます。

可変長引数リスト

PHP は ... を使った可変長引数をユーザー定義関数でサポートしています。

引数リストに ... トークンを含めることで、 その関数が可変長の引数を受け取ることを示せます。 引数は、指定した変数に配列として渡されます:

例11 ... を使った、可変長引数へのアクセス

<?php
function sum(...$numbers) {
$acc = 0;
foreach ($numbers as $n) {
$acc += $n;
}
return $acc;
}

echo sum(1, 2, 3, 4);
?>

上の例の出力は以下となります。

10

関数を呼び出すときに ... を使うと、 配列や Traversable を実装した変数やリテラルを引数リストに展開することができます。

例12 引数での ... の使用例

<?php
function add($a, $b) {
return $a + $b;
}

echo add(...[1, 2])."\n";

$a = [1, 2];
echo add(...$a);
?>

上の例の出力は以下となります。

3
3

通常の引数を、... の前に指定することもできます。 この場合は、通常の引数リストにマッチしなかったのこりの引数が ... による配列に追加されます。

... トークンの前に、 型宣言 を付加することもできます。 型宣言がある場合、... が取り込むすべての引数はその型に一致していなければいけません。

例13 型宣言つきの可変長引数

<?php
function total_intervals($unit, DateInterval ...$intervals) {
$time = 0;
foreach ($intervals as $interval) {
$time += $interval->$unit;
}
return $time;
}

$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo total_intervals('d', $a, $b).' days';

// これは失敗します。null は DateInterval オブジェクトではないからです。
echo total_intervals('d', null);
?>

上の例の出力は以下となります。

3 days
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2

可変長引数の リファレンス渡し もできます。その場合は、... の前にアンパサンド (&) を付加します。

名前付き引数

既にある、位置を指定した引数を拡張する形で、PHP 8.0.0 から名前付き引数が導入されました。 名前付き引数は、位置ではなく、名前ベースで引数を渡すことを可能にします。 これによって、引数の意味が自己文書化(self-documenting)され、 引数を任意の順番で渡せるようになり、任意のデフォルト値を持つ引数をスキップできるようになります。

名前付き引数は、引数の名前の後にコロンを付けたものを、値の前に付けることで指定します。 引数の名前に予約語を使うことも許されています。 引数の名前は識別子でなければならず、動的に指定することは出来ません。

例14 名前付き引数の文法

<?php
myFunction(paramName: $value);
array_foobar(array: $value);

// 以下の書き方はサポートされていません
function_name($variableStoringParamName: $value);
?>

例15 位置を指定した引数と、名前付き引数

<?php
// 位置を指定した引数の場合:
array_fill(0, 100, 50);

// 名前付き引数の場合:
array_fill(start_index: 0, count: 100, value: 50);
?>

名前付き引数は、渡す順番は関係ありません。

例16 上と同じ例を、引数の順番を変えて渡す

<?php
array_fill(value: 50, count: 100, start_index: 0);
?>

名前付き引数は、位置を指定した引数と組み合わせることが出来ます。 そうした場合、名前付き引数は、位置を指定した引数の後に置かなければいけません。 オプションの引数だけをいくつか、指定することもできます。 その場合も、名前付き引数の順番は関係ありません。

例17 位置を指定した引数と、名前付き引数を組み合わせる

<?php
htmlspecialchars($string, double_encode: false);
// 上記は、以下と同等です。
htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
?>

同じ引数を複数回渡すと、Error 例外が発生します。

例18 同じ引数を複数回渡すと、Error がスローされる

<?php
function foo($param) { ... }

foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument
foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument
?>

PHP 8.1.0 以降では、 引数を ... で展開した後に 名前付き引数を指定することができます。 名前付き引数は、展開済みの引数を上書きしては いけません。

例19 引数を展開した後に、名前付き引数を使う

<?php
function foo($a, $b, $c = 3, $d = 4) {
return $a + $b + $c + $d;
}

var_dump(foo(...[1, 2], d: 40)); // 46
var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites previous argument
?>


戻り値

オプションの return 文により値を返すことができます。 配列やオブジェクトを含むあらゆる型を返すことができます。 これにより、関数の実行を任意の箇所で終了し、その関数を呼び出した 箇所に制御を戻すことが出来ます。詳細に関しては return を参照ください。

注意:

return を省略した場合は null を返します。

return の使いかた

例1 return の使用法

<?php
function square($num)
{
return $num * $num;
}
echo square(4); // '16'を出力
?>

関数は複数の値を返すことは出来ませんが、 配列を返すことで似たような結果を得ることができます。

例2 複数の値を得るために配列を返す例

<?php
function small_numbers()
{
return [0, 1, 2];
}
// 配列を展開させると、配列のそれぞれのメンバが個別に得られます。
[$zero, $one, $two] = small_numbers();

// PHP 7.1.0 より前のバージョンで上と同じことをするには、
// 言語構造 list を使うしかありません。
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() をコールする

?>

staticメソッドをコールするときには、関数呼び出しのほうがstaticプロパティ演算子よりも優先されます。

例3 staticプロパティを含む可変メソッドの例

<?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 の内容を読むからです。

?>

例4 複雑な callable

<?php
class Foo
{
static function bar()
{
echo "bar\n";
}
function baz()
{
echo "baz\n";
}
}

$func = array("Foo", "bar");
$func(); // "bar" を表示します
$func = array(new Foo, "baz");
$func(); // "baz" を表示します
$func = "Foo::bar";
$func(); // "bar" を表示します。
?>

参考

  • is_callable()
  • call_user_func()
  • function_exists()
  • 可変変数


内部（ビルトイン）関数

PHPは標準で多くの関数と言語構造を持っています。また他にも コンパイル済みの特定のPHP拡張モジュールを必要とする関数があります。 それらはもしコンパイルされていなければ"undefined function（未定義の関数）" として致命的エラーを発するでしょう。例えば、 imagecreatetruecolor()のような 画像関数を使用するには、 GDサポートを有効にしてPHPをコンパイルしておく必要があります。 また、mysqli_connect()を使う場合もやはり MySQLサポートを有効にしてPHPが コンパイルされている必要があります。 stringや variable関数のように どのバージョンのPHPでも含まれているコアの関数もたくさんあります。 phpinfo()やget_loaded_extensions()を コールすることで使用しているPHPにロードされている拡張モジュールを 見ることができます。また、多くの拡張モジュールはデフォルトで有効に なっており、PHPのマニュアルは拡張モジュール毎に分けられていることにも 注意してください。PHPのセットアップについては 設定, インストール,そして個々の拡張モジュール の項をご覧ください。

関数のプロトタイプに関する解説はマニュアルの 関数の定義を読むにはを 参照ください。関数の戻り値や引数が直接与えられた場合に どのように動くかを認識することは重要です。 例えば、str_replace()は変更された文字列を 返すのに対し、usort()は与えられた引数そのものを 変更します。マニュアルの各項にはそれぞれの関数に関する情報があります。 関数の引数、振る舞いの変更、成功した場合失敗した場合の それぞれの戻り値、可用性に関する情報などです。 これらの重要な（時には微妙な）違いを知ることは、 正しいPHPコードを書くうえで極めて重要なことです。

注意: 関数へのパラメータとして関数が想定しているのとは異なるものを渡した場合、 例えば文字列を想定しているところに配列を渡した場合などの場合は 関数の戻り値は未定義となります。たいていの場合は null を返すでしょう。しかしこれはあくまでも規約にすぎず、 これに依存することはできません。 PHP 8.0.0 以降では、このような場合には TypeError をスローすることになっています。

注意:

ビルトイン関数のスカラー型の引数には、 デフォルトの自動変換(coercive)モードの場合、 null を渡すことが出来ます。 PHP 8.1.0 以降では、 nullable として宣言されていない内部関数の引数に null を渡すことは推奨されなくなり、 自動変換モードでは警告が発生するようになっています。 ユーザ定義の関数においては、スカラー型の引数は nullable と明示的にマークする必要があり、その振る舞いと合わせるためです。

たとえば、strlen() 関数は引数 $string に null でない文字列を渡すことを期待しています。 歴史的な理由により、 PHP は自動変換モードの場合に、 この引数に null を渡すことを許可してきました。 結果として、引数に null を渡すと暗黙のうちに文字列にキャストされ、 結果は空文字列 "" になっていました。 これに対し、strict モードの場合は TypeError がスローされます。

<?php
var_dump(strlen(null));
// "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
// int(0)

var_dump(str_contains("foobar", null));
// "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
// bool(true)
?>

参考

  • function_exists()
  • 関数リファレンス
  • get_extension_funcs()
  • dl()


無名関数

無名関数はクロージャとも呼ばれ、 関数名を指定せずに関数を作成できるようにするものです。 callable パラメータとして使う際に便利ですが、用途はそれにとどまりません。

無名関数の実装には Closure クラスを使っています。

例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');
?>

クロージャは、変数を親のスコープから引き継ぐことができます。 引き継ぐ変数は、use で渡さなければなりません。 PHP 7.1 以降は、引き継ぐ値に スーパーグローバル や $this、 およびパラメータと同じ名前の変数を含めてはいけません。 戻り値の型は、 use の 後 に置かなければいけません。

例3 親のスコープからの変数の引き継ぎ

<?php
$message = 'hello';

// "use" がない場合
$example = function () {
var_dump($message);
};
$example();

// $message を引き継ぎます
$example = function () use ($message) {
var_dump($message);
};
$example();

// 引き継がれた変数の値は、関数が定義された時点のものであり、
// 関数が呼ばれた時点のものではありません
$message = 'world';
$example();

// $message をリセットします
$message = 'hello';

// リファレンス渡しで引き継ぎます
$example = function () use (&$message) {
var_dump($message);
};
$example();

// 親のスコープで変更された値が、
// 関数呼び出しの内部にも反映されます
$message = 'world';
$example();

// クロージャは、通常の引数も受け付けます
$example = function ($arg) use ($message) {
var_dump($arg . ' ' . $message);
};
$example("hello");

// 戻り値の型は、use の後に置きます
$example = function () use ($message): string {
return "hello $message";
};
var_dump($example());
?>

上の例の出力は、 たとえば以下のようになります。

Notice: Undefined variable: message in /example.php on line 6
NULL
string(5) "hello"
string(5) "hello"
string(5) "hello"
string(5) "world"
string(11) "hello world"
string(11) "hello world"

PHP 8.0.0 以降では、親のスコープを継承した変数の一覧の最後にカンマを付けられるようになりました。 このカンマは無視されます。

親のスコープからの変数の引き継ぎは、グローバル変数を使うのとは 異なります。グローバル変数は、 関数が実行されるかどうかにかかわらずグローバルスコープに存在します。 クロージャの親スコープは、クロージャが宣言されている関数です (関数の呼び出し元のスコープである必要はありません)。 次の例を参照ください。

例4 クロージャのスコープ

<?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 です
?>

例5 $this の自動バインド

<?php

class Test
{
public function testing()
{
return function() {
var_dump($this);
};
}
}

$object = new Test;
$function = $object->testing();
$function();

?>

上の例の出力は以下となります。

object(Test)#1 (0) {
}

クラスのコンテキストで宣言した場合は、現在のクラスが自動的にバインドされて、 関数のスコープで $this が使えるようになります。 現在のクラスへの自動バインドを望まない場合は、 static な無名関数 を使いましょう。

static な無名関数

static を付けて無名関数を宣言することができます。 こうすることで、現在のクラスが無名関数を自動的にバインドすることがなくなります。 オブジェクトも、実行時にはバインドされなくなります。

例6 static な無名関数内での $this の使用例

<?php

class Foo
{
function __construct()
{
$func = static function() {
var_dump($this);
};
$func();
}
};
new Foo();

?>

上の例の出力は以下となります。

Notice: Undefined variable: this in %s on line %d
NULL

例7 static な無名関数へのオブジェクトのバインド

<?php

$func = static function() {
// 関数の本体
};
$func = $func->bindTo(new stdClass);
$func();

?>

上の例の出力は以下となります。

Warning: Cannot bind an instance to a static closure in %s on line %d

変更履歴

バージョン | 説明
7.1.0 | 無名関数は、スーパーグローバル や、 $this, もしくは 引数と同じ名前の変数を use で引き継げなくなりました。

注意

注意: クロージャ内から func_num_args()、 func_get_arg() および func_get_args() を使用することができます。


アロー関数

アロー関数は 無名関数 を簡潔に書ける文法として PHP 7.4 で追加されました。

無名関数とアロー関数は共に Closure クラスを使って実装されています。

アロー関数は fn (argument_list) => expr という形で記述します。

アロー関数は 無名関数 と同じ機能をサポートしていますが、 親のスコープで使える変数が常に自動で使える点だけが異なります。

式の中で使える変数が親のスコープで定義されている場合、 暗黙のうちに参照ではなく値がキャプチャされます。 次の例では、$fn1 と $fn2 は同じ振る舞いをします。

例1 アロー関数は参照ではなく値を自動でキャプチャする

<?php

$y = 1;

$fn1 = fn($x) => $x + $y;
// $y を値渡しするのと同じ
$fn2 = function ($x) use ($y) {
return $x + $y;
};

var_export($fn1(3));
?>

上の例の出力は以下となります。

4

この仕組みは、アロー関数をネストした場合でも同じ動きをします:

例2 アロー関数は、ネストされた場合でも変数を値でキャプチャする

<?php

$z = 1;
$fn = fn($x) => fn($y) => $x * $y + $z;
// 51 を出力
var_export($fn(5)(10));
?>

無名関数と同じように、 アロー関数の文法は、引数や戻り値、デフォルト値、可変長引数、 リファレンス渡しやリファレンス返しを含む、任意の関数シグネチャを扱えます。 次に示す例は、全て正しいアロー関数の例です:

例3 アロー関数の例

<?php

fn(array $x) => $x;
static fn(): int => $x;
fn($x = 42) => $x;
fn(&$x) => $x;
fn&($x) => $x;
fn($x, ...$rest) => $rest;

?>

アロー関数は変数を値でバインドします。 これは変数 $x をアロー関数の内部で使うたびに use($x) を実行することと大体同じです。 値でバインドするということは、アロー関数の外のスコープの値を変更することが不可能だということです。 参照でバインドしたい場合は、無名関数 が使えます。

例4 外部のスコープの値はアロー関数では変更できない

<?php

$x = 1;
$fn = fn() => $x++; // 意味がない
$fn();
var_export($x); // 1 を出力

?>

変更履歴

バージョン | 説明
7.4.0 | アロー関数が利用可能になりました。

注意

注意: アロー関数の内部から func_num_args()、 func_get_arg() および func_get_args() を使用することができます。


第一級callableを生成する記法

第一級callableを生成する記法 (First class callable syntax) とは、PHP 8.1.0 で追加された、 callable から 無名関数 を生成する記法です。 この記法は、 文字列や配列を使って callable を生成するやり方を置き換えるものです。 この記法の利点は、callable の静的解析を行いやすくなることに加え、 そのスコープが、callable を生成した時点のスコープになることです。

CallableExpr(...) という記法で、 callable から Closure を生成します。 CallableExpr には、 PHP の文法上直接コールできるあらゆる式が使えます:

例1 簡単な例

<?php

class Foo {
public function method() {}
public static function staticmethod() {}
public function __invoke() {}
}

$obj = new Foo();
$classStr = 'Foo';
$methodStr = 'method';
$staticmethodStr = 'staticmethod';

$f1 = strlen(...);
$f2 = $obj(...); // 呼び出し可能オブジェクト
$f3 = $obj->method(...);
$f4 = $obj->$methodStr(...);
$f5 = Foo::staticmethod(...);
$f6 = $classStr::$staticmethodStr(...);

// 文字列や配列を使った、古い記法
$f7 = 'strlen'(...);
$f8 = [$obj, 'method'](...);
$f9 = [Foo::class, 'staticmethod'](...);
?>

注意:

... は文法の一部であり、省略形ではありません。

この記法の動作は、 Closure::fromCallable() の仕様に従います。 つまり、文字列や配列から callable を作るやり方とは異なり、 CallableExpr(...) のスコープは、 それを生成した時点でのスコープになります:

例2 古い callable の生成方法と、CallableExpr(...) の比較

<?php

class Foo {
public function getPrivateMethod() {
return [$this, 'privateMethod'];
}

private function privateMethod() {
echo __METHOD__, "\n";
}
}

$foo = new Foo;
$privateMethod = $foo->getPrivateMethod();
$privateMethod();
// Fatal error: Call to private method Foo::privateMethod() from global scope
// 上記がエラーになるのは、呼び出しが Foo の外部から行われ、
// アクセス権のチェックもこの時点から行われるためです。

class Foo1 {
public function getPrivateMethod() {
// 下記は、callable を生成した時点のスコープになります。
return $this->privateMethod(...); // Closure::fromCallable([$this, 'privateMethod']); と同等です。
}

private function privateMethod() {
echo __METHOD__, "\n";
}
}

$foo1 = new Foo1;
$privateMethod = $foo1->getPrivateMethod();
$privateMethod(); // Foo1::privateMethod
?>

注意:

この記法を使ってオブジェクトを生成する操作 (例: new Foo(...)) はサポートされていません。 なぜなら、new Foo() は、呼び出しとは見なされないからです。

注意:

この記法は、nullsafe 演算子 と組み合わせて使うことはできません。 以下のコードは、いずれもコンパイルエラーになります:

<?php
$obj?->method(...);
$obj?->prop->method(...);
?>


クラスとオブジェクト

目次

  • はじめに
  • クラスの基礎
  • プロパティ
  • クラス定数
  • クラスのオートローディング
  • コンストラクタとデストラクタ
  • アクセス権
  • オブジェクトの継承
  • スコープ定義演算子 (::)
  • static キーワード
  • クラスの抽象化
  • オブジェクト インターフェイス
  • トレイト
  • 無名クラス
  • オーバーロード
  • オブジェクトの反復処理
  • マジックメソッド
  • finalキーワード
  • オブジェクトのクローン作成
  • オブジェクトの比較
  • 遅延静的束縛 (Late Static Bindings)
  • オブジェクトと参照
  • オブジェクトのシリアライズ
  • 共変性と反変性
  • 変更履歴


はじめに

PHP には完全なオブジェクトモデルが搭載されています。 搭載されている機能には アクセス権、 abstract クラスやメソッド、 final クラスやメソッド、 新たな マジックメソッド、 インターフェイス、 オブジェクトのクローン作成 などがあります。

PHP では、オブジェクトを参照やハンドルと同様に扱います。つまり、 オブジェクトそのものではなくオブジェクトへの参照を変数に格納するようになります。 オブジェクトおよびリファレンス を参照ください。

ヒント

ユーザーレベルでの命名の手引き も参照ください。


クラスの基礎

class

各クラスの定義は、classキーワードで始まり、クラス名が続きます。 そしてその後に波括弧のペアが続き、 その中にはクラスのプロパティとメソッドの定義を記述します。

クラス名には、PHP の予約語 以外でラベルとして有効なあらゆる名前を使用することができます。 有効なクラス名は、先頭が文字あるいはアンダースコアで始まり、 その後に任意の数の文字/数字/アンダースコアが続くものです。 正規表現で表すと、 ^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$ のようになります。

クラスの中には、 定数 や 変数 ("プロパティ" といいます) そして関数 ("メソッド" といいます) を含めることができます。

例1 簡単なクラス定義

<?php
class SimpleClass
{
// プロパティの宣言
public $var = 'a default value';

// メソッドの宣言
public function displayVar() {
echo $this->var;
}
}
?>

メソッドがオブジェクトのコンテキストからコールされる場合は、 疑似変数 $this が利用可能です。 $this は、呼び出し元オブジェクトの値です。

警告

static でないメソッドを static メソッドとしてコールすると、 Error がスローされます。 PHP 8.0.0 より前のバージョンでは、推奨されない警告が発生し、 $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()
{
A::foo();
}
}

$a = new A();
$a->foo();

A::foo();

$b = new B();
$b->bar();

B::bar();
?>

上の例の PHP 7 での出力は、このようになります。

$this is defined (A)

Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
$this is not defined.

Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
$this is not defined.

Deprecated: Non-static method B::bar() should not be called statically in %s  on line 32

Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
$this is not defined.

上の例の PHP 8 での出力は、このようになります。:

$this is defined (A)

Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
Stack trace:
#0 {main}
  thrown in %s  on line 27

読み取り専用クラス

PHP 8.2.0 以降では、 クラスに対して readonly を指定することができます。 クラスに対して readonly を指定すると、 宣言されている全ての プロパティに対して readonly を指定した ことになり、 かつ 動的なプロパティ の作成を禁止したことになります。 さらに、AllowDynamicProperties アトリビュートを指定しても動的なプロパティを作成できなくなります。 動的なプロパティを作成しようとすると、コンパイル時にエラーが発生します。

<?php
#[\AllowDynamicProperties]
readonly class Foo {
}

// Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
?>

型を指定していないプロパティや、 static プロパティ に対しては readonly を指定できません。 readonly クラスには、それらをいずれも指定できません:

<?php
readonly class Foo
{
public $bar;
}

// Fatal error: Readonly property Foo::$bar must have type
?>
<?php
readonly class Foo
{
public static int $bar;
}

// Fatal error: Readonly class Foo cannot declare static properties
?>

readonly を指定したクラスは、 子クラスでも readonly を指定した場合にのみ 継承 できます。

new

あるクラスのインスタンスを生成するには、new キーワードを使わなければなりません。エラー時に 例外をスローするような コンストラクタを定義していない限り、 オブジェクトが常に生成されます。 クラスは、そのインスタンスを作成する前に定義すべきです (これが必須となる場合もあります)。

クラス名を含む文字列を new で指定すると、 そのクラスのインスタンスを作成します。クラスが名前空間に属している場合は、 完全修飾名を指定しなければなりません。

注意:

クラスのコンストラクタに引数を渡さなかった場合、 クラス名の後の括弧は省略しても構いません。

例3 インスタンスを作成する

<?php
$instance = new SimpleClass();

// 変数を使うこともできます
$className = 'SimpleClass';
$instance = new $className(); // new SimpleClass()
?>

クラスのコンテキストにおいては、 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 8.0.0 以降では、 new を任意の式と一緒に使う機能がサポートされました。 これによって、式が文字列を生成する場合に、 より複雑なインスタンス化を行えるようになります。 式は括弧で囲まなければいけません。

例5 任意の式を使ってインスタンスを生成する

以下の例では、 クラス名を生成する有効な任意の式を複数示します。 関数呼び出し、文字列連結、そして ::class 定数です。

<?php

class ClassA extends \stdClass {}
class ClassB extends \stdClass {}
class ClassC extends ClassB {}
class ClassD extends ClassA {}

function getSomeClass(): string
{
return 'ClassA';
}

var_dump(new (getSomeClass()));
var_dump(new ('Class' . 'B'));
var_dump(new ('Class' . 'C'));
var_dump(new (ClassD::class));
?>

上の例の PHP 8 での出力は、このようになります。:

object(ClassA)#1 (0) {
}
object(ClassB)#1 (0) {
}
object(ClassC)#1 (0) {
}
object(ClassD)#1 (0) {
}

複数のやり方で、オブジェクトのインスタンスを作ることが出来ます:

例6 新しいオブジェクトの作成

<?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)

新しく作成したオブジェクトのメンバーに、作成したその式の中でもアクセスすることができます。

例7 新しく作成したオブジェクトのメンバーへのアクセス

<?php
echo (new DateTime())->format('Y');
?>

上の例の出力は、 たとえば以下のようになります。

2016

注意: PHP 7.1 より前のバージョンでは、コンストラクタが定義されない場合、それへの引数が評価されていませんでした。

プロパティとメソッド

クラスのプロパティとメソッドは、それぞれ別の "名前空間" に存在するので、 同じ名前のプロパティとメソッドを共存させることもできます。 プロパティを参照する場合もメソッドを参照する場合も書きかたは同じです。 それがプロパティへのアクセスなのかメソッドの呼び出しなのかは、そのコンテキストによって決まります。 つまり、変数にアクセスしようとしているのか関数を呼び出そうとしているのかの違いです。

例8 プロパティへのアクセスとメソッドの呼び出し

<?php
class Foo
{
public $bar = 'property';

public function bar() {
return 'method';
}
}

$obj = new Foo();
echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

上の例の出力は以下となります。

property
method

これはつまり、プロパティに 無名関数 を代入した場合に、その関数は直接呼び出せないということです。 その場合は、たとえば事前にプロパティを変数に代入しておく必要があります。 括弧で囲むと、プロパティを直接呼び出すこともできます。

例9 プロパティに格納した無名関数の呼び出し

<?php
class Foo
{
public $bar;

public function __construct() {
$this->bar = function() {
return 42;
};
}
}

$obj = new Foo();

echo ($obj->bar)(), PHP_EOL;

上の例の出力は以下となります。

42

extends

クラスは、宣言部に extends キーワードを含めることで、 他のクラスの定数や、メソッド、 およびプロパティを継承することができます。多重継承を行うことはできず、クラスが継承できるベース クラスは一つだけです。

継承された定数やメソッド、プロパティをオーバーライド(上書き)するには、 親クラスで定義されているのと同じ名前でそれを再宣言します。 しかし、親クラスでそのメソッドや定数が final として定義されている場合はオーバーライドできません。 オーバーライドされた元のメソッドやstaticプロパティにアクセスするには、 parent:: で参照します。

注意: PHP 8.1.0 以降では、定数も final として宣言できます。

例10 簡単なクラスの継承

<?php
class ExtendClass extends SimpleClass
{
// 親クラスのメソッドを再定義
function displayVar()
{
echo "Extending class\n";
parent::displayVar();
}
}

$extended = new ExtendClass();
$extended->displayVar();
?>

上の例の出力は以下となります。

Extending class
a default value

シグネチャの互換性に関するルール

メソッドをオーバーライドするときは、 子クラスのシグネチャが親クラスのそれと互換性がなければいけません。 互換性が壊れた場合、致命的なエラーが発生します。 PHP 8.0.0 より前のバージョンでは、 互換性が壊れた場合に、E_WARNING レベルの警告が発生していました。 共変性と反変性 の規則を守っている場合は、シグネチャに互換性があります。 必須の引数をオプションにした場合も、互換性があります。 新しいオプションの引数を追加しただけで、アクセス権を厳しくせず、 緩めただけの場合も互換性があります。 これは、リスコフの置換原則(Liskov Substitution Principle)、 略して LSP として知られています。 但し、コンストラクタ と private メソッドについては、 この規則の例外で、 オーバライドしたシグネチャにミスマッチがあっても致命的なエラーにはなりません。

例11 互換性がある子クラスのメソッド

<?php
class Base
{
public function foo(int $a) {
echo "Valid\n";
}
}
class Extend1 extends Base
{
function foo(int $a = 5)
{
parent::foo($a);
}
}
class Extend2 extends Base
{
function foo(int $a, $b = 5)
{
parent::foo($a);
}
}
$extended1 = new Extend1();
$extended1->foo();
$extended2 = new Extend2();
$extended2->foo(1);

上の例の出力は以下となります。

Valid
Valid

次の例は、引数を削除した子クラスのメソッドや、 オプションの引数を必須にしたりすることが、親クラスのメソッドと互換性がなくなることを示しています。

例12 子クラスのメソッドで引数を削除すると致命的なエラーになる

<?php
class Base
{
public function foo(int $a = 5) {
echo "Valid\n";
}
}
class Extend extends Base
{
function foo()
{
parent::foo(1);
}
}

上の例の PHP 8 での出力は、たとえば以下のようになります。:

Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

例13 子クラスのメソッドで、オプションの引数を必須にすると致命的なエラーになる

<?php
class Base
{
public function foo(int $a = 5) {
echo "Valid\n";
}
}
class Extend extends Base
{
function foo(int $a)
{
parent::foo($a);
}
}

上の例の PHP 8 での出力は、たとえば以下のようになります。:

Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13
警告

メソッドの引数の名前を子クラスで変更しても、 シグネチャ上は非互換になりません。 しかし、こうしてしまうと 名前付き引数 を使った時に実行時エラーになるので、おすすめできません。

例14 子クラスで引数の名前を変更し、かつ名前付き引数を使うとエラーになる

<?php
class A {
public function test($foo, $bar) {}
}
class B extends A {
public function test($a, $b) {}
}
$obj = new B;
// A::test() の規約に従って引数を渡す
$obj->test(foo: "foo", bar: "bar"); // エラー発生!

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
Stack trace:
#0 {main}
  thrown in /in/XaaeN on line 14

::class

class キーワードでもクラス名の解決を行うことが出来ます。 クラスの名前が ClassName になっているクラスの完全修飾名を取得するには、 ClassName::class を使います。 これは、名前空間付きのクラスに使うと特に便利です。

例15 クラス名の解決

<?php
namespace NS {
class ClassName {
}

echo ClassName::class;
}
?>

上の例の出力は以下となります。

NS\ClassName

注意:

::class によるクラス名の解決は、コンパイル時の変換です。 つまり、クラス名を作るタイミングでは、まだオートロードが行われていないということです。 結果的に、クラスがまだ存在しない時点でクラス名が展開されることになります。 この場合にはエラーは発生しません。

例16 クラス名が存在しない場合の名前解決

<?php
print Does\Not\Exist::class;
?>

上の例の出力は以下となります。

Does\Not\Exist

PHP 8.0.0 以降では、 ::class はオブジェクトに対しても使えるようになりました。 この名前解決はコンパイル時ではなく、実行時に行われます。 この場合、get_class() をオブジェクトに対して使った時と同じ動きをします。

例17 オブジェクトの名前解決

<?php
namespace NS {
class ClassName {
}
}
$c = new ClassName();
print $c::class;
?>

上の例の出力は以下となります。

NS\ClassName

nullsafe メソッドとプロパティ

PHP 8.0.0 以降では、プロパティやメソッドは "nullsafe" 演算子 ?-> を使ってアクセスすることもできます。 nullsafe 演算子は既に述べたメソッドやプロパティと同じように振る舞いますが、 オブジェクトが null と評価された場合に、例外はスローされず、 null が返される点だけが異なります。 オブジェクトの評価がチェインの一部だった場合は、 残りのチェインはスキップされます。

この演算子の働きは、 オブジェクトにアクセスするたびに is_null() でラップするコードに似ています。 しかし、よりコンパクトです。

例18 nullsafe 演算子

<?php

// PHP 8.0.0 以降は、このように書けます:
$result = $repository?->getUser(5)?->name;

// これは、以下のコードチェックと同等です:
if (is_null($repository)) {
$result = null;
} else {
$user = $repository->getUser(5);
if (is_null($user)) {
$result = null;
} else {
$result = $user->name;
}
}
?>

注意:

nullsafe 演算子は、プロパティやメソッドが値を返す際、 null が正しく、期待されうる値とみなせる場合に一番よく使います。 エラーを示すためなら、例外をスローするほうが好ましいです。


プロパティ

クラスのメンバ変数のことを プロパティ といいます。 それ以外に フィールド などという呼びかたを見たことがあるかもしれません。 しかし、このマニュアルでは プロパティ と呼ぶことにします。 プロパティは、少なくともひとつのキーワード (たとえば アクセス権 のキーワード、 static キーワード、 PHP 8.1.0 以降のみ readonly) のあとに、 オプションの型宣言 (PHP 7.4 以降、但し readonly を除く) を続け、 その後に通常の変数の宣言を続けます。 宣言時に初期値を設定することもできますが、 初期値は 定数 値でなければなりません。

注意:

クラスのプロパティを宣言する代替の方法として、 var キーワードを使う方法があります。

注意: アクセス権 を宣言しない場合、プロパティを public として宣言したとみなされます。

クラスのメソッドからstatic でないプロパティにアクセスするには -> (オブジェクト演算子) を使って $this->property のようにします (property のところにプロパティ名を指定します)。 staticプロパティへのアクセスには :: (ダブルコロン) を使って self::$property のようにします。 staticプロパティとそうでないプロパティの違いについては、 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 = [true, false];

public $var8 = <<<'EOD'
hello world
EOD;
// アクセス権を付けない場合
static $var9;
readonly int $var10;
}
?>

注意:

クラスやオブジェクトを操作するための便利な関数が用意されています。 クラス/オブジェクト関数 を参照ください。

型宣言

PHP 7.4.0 以降は、プロパティの定義に 型宣言 を含めることができます。 但し、callable 型を除きます。

例2 型付きプロパティの例

<?php

class User
{
public int $id;
public ?string $name;

public function __construct(int $id, ?string $name)
{
$this->id = $id;
$this->name = $name;
}
}

$user = new User(1234, null);

var_dump($user->id);
var_dump($user->name);

?>

上の例の出力は以下となります。

int(1234)
NULL

型付きプロパティは、アクセスする前に初期化しなければいけません。 初期化しないと、Error がスローされます。

例3 プロパティにアクセスする

<?php

class Shape
{
public int $numberOfSides;
public string $name;

public function setNumberOfSides(int $numberOfSides): void
{
$this->numberOfSides = $numberOfSides;
}

public function setName(string $name): void
{
$this->name = $name;
}

public function getNumberOfSides(): int
{
return $this->numberOfSides;
}

public function getName(): string
{
return $this->name;
}
}

$triangle = new Shape();
$triangle->setName("triangle");
$triangle->setNumberofSides(3);
var_dump($triangle->getName());
var_dump($triangle->getNumberOfSides());

$circle = new Shape();
$circle->setName("circle");
var_dump($circle->getName());
var_dump($circle->getNumberOfSides());
?>

上の例の出力は以下となります。

string(8) "triangle"
int(3)
string(6) "circle"

Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

読み取り専用プロパティ

PHP 8.1.0 以降では、readonly を付けてプロパティを宣言できます。 これによって、プロパティを初期化した後に値が変更されることを防止できます。

例4 読み取り専用プロパティの例

<?php

class Test {
public readonly string $prop;

public function __construct(string $prop) {
// 正しい初期化
$this->prop = $prop;
}
}

$test = new Test("foobar");
// 正しいプロパティの読み取り
var_dump($test->prop); // string(6) "foobar"

// 不正な再代入です。同じ値を代入することは問題ありません。
$test->prop = "foobar";
// Error: Cannot modify readonly property Test::$prop
?>

注意:

readonly は、 型付きプロパティ に対してのみ指定できます。 型の制約がないプロパティを読み取り専用にしたい場合、 Mixed が使えます。

注意:

読み取り専用の static プロパティはサポートされていません。

読み取り専用プロパティは、一度しか初期化できません。 初期化できるのは、 そのプロパティが宣言された場所と同じスコープに限られます。 これらのルールから外れたプロパティへの代入や変更を行った場合、 Error 例外が発生します。

例5 読み取り専用プロパティの不正な初期化

<?php
class Test1 {
public readonly string $prop;
}

$test1 = new Test1;
// スコープ外からの不正な初期化
$test1->prop = "foobar";
// Error: Cannot initialize readonly property Test1::$prop from global scope
?>

注意:

読み取り専用プロパティに対して、 明示的にデフォルト値を設定することはできません。 なぜなら、読み取り専用プロパティにデフォルト値を設定することは、 本質的に定数と同じであり、あまり役に立たないからです。

<?php

class Test {
// Fatal error: Readonly property Test::$prop cannot have default value
public readonly int $prop = 42;
}
?>

注意:

読み取り専用プロパティは、 一度初期化されると unset() できません。 しかし、初期化する前であれば プロパティを宣言した同一のスコープから unset することはできます。

プロパティの変更は、単純な代入にとどまりません。 次に示すプロパティへの変更例は、 すべて Error 例外が発生します:

<?php

class Test {
public function __construct(
public readonly int $i = 0,
public readonly array $ary = [],
) {}
}

$test = new Test;
$test->i += 1;
$test->i++;
++$test->i;
$test->ary[] = 1;
$test->ary[0][] = 1;
$ref =& $test->i;
$test->i =& $ref;
byRef($test->i);
foreach ($test as &$prop);
?>

但し、プロパティが読み取り専用であっても、 そのプロパティの内部まで変更できなくなるわけではありません。 読み取り専用プロパティ内部のオブジェクト(またはリソース) は、 内部的に変更しても構いません:

<?php

class Test {
public function __construct(public readonly object $obj) {}
}

$test = new Test(new stdClass);
// 有効なオブジェクト内部の変更
$test->obj->foo = 1;
// 不正な再代入
$test->obj = new stdClass;
?>

動的なプロパティ

オブジェクトに対して、存在しないプロパティを代入しようとした場合、 PHP は自動的に対応するプロパティを作成します。 こうして作成された動的なプロパティは、 そのインスタンスで のみ 使えます。

警告

動的なプロパティは、PHP 8.2.0 以降は推奨されなくなりました。 代わりに、プロパティを宣言することを推奨します。 任意のプロパティの名前を扱うには、 クラスがマジックメソッド __get() と __set() を実装すべきです。 動的なプロパティを使うための最終手段として、 アトリビュート #[\AllowDynamicProperties] でクラスをマークすることができます。


クラス定数

値が変更できない 定数 をクラス内に定義することができます。 クラス定数のデフォルトのアクセス範囲は public です。

注意:

クラス定数は、子クラスで再定義することもできます。 PHP 8.1.0 以降では、final として定義されたクラス定数は、子クラスで再定義できません。

インターフェイスに定数を持たせることもできます。 インターフェイスについてのドキュメント で例を御覧ください。

変数を用いてクラスを参照することも可能です。 変数の値に (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";

$class = new MyClass();
$class->showConstant();

echo $class::CONSTANT."\n";
?>

特別な ::class 定数を使うと、 コンパイル時の完全修飾クラス名が解決できます。 これは名前空間クラスに役立ちます。

例2 名前空間の ::class の例

<?php
namespace foo {
class bar {
}

echo bar::class; // foo\bar
}
?>

例3 クラス内での定数式の例

<?php
const ONE = 1;

class foo {
const TWO = ONE * 2;
const THREE = ONE + self::TWO;
const SENTENCE = 'The value of THREE is '.self::THREE;
}
?>

例4 PHP 7.1.0 以降の、クラス定数のアクセス範囲

<?php
class Foo {
public const BAR = 'bar';
private const BAZ = 'baz';
}
echo Foo::BAR, PHP_EOL;
echo Foo::BAZ, PHP_EOL;
?>

上の例の PHP 7.1 での出力は、このようになります。

bar

Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in ...

注意:

PHP 7.1.0 以降は、クラス定数のアクセス範囲を指定できるようになりました。


クラスのオートローディング

オブジェクト指向アプリケーションを作成する開発者の多くは、 クラス定義毎に一つのPHPソースファイルを作成します。 最大の問題は、各スクリプトの先頭に、必要な読み込みを行う長いリストを 記述する必要があることです(各クラスについて一つ)。

spl_autoload_register() 関数を使うと、 任意の数のオートローダーを登録でき、 クラスやインターフェイスが定義されていなくても自動的に読み込めるようになります。 オートローダーを登録すれば、PHPがエラーで止まる前にクラスをロードする最後の チャンスが与えられます。

クラスに類似した言語構造は、同じやり方でオートロードできます。 これには、クラス、インターフェイス、トレイト、列挙型が含まれます。

警告

PHP 8.0.0 より前のバージョンでは、 __autoload() 関数でもクラスやインターフェイスのオートロードが可能でした。 しかし、この関数は spl_autoload_register() 関数に比べると柔軟性という点で劣っています。 そのため、__autoload() 関数は PHP 7.2.0 で推奨されなくなり、 PHP 8.0.0 で削除されました。

注意:

複数のオートローダーを複数回登録するために、 spl_autoload_register() を複数回コールしても構いません。 但し、オートロードを行う関数から例外がスローされると、 オートロードのプロセスが中断され、 後続のオートロード関数の実行ができなくなります。 よって、オートロード関数から例外をスローすることは、 全くお勧めできません。

例1 オートロードの例

この例は、 クラス MyClass1 および MyClass2 をそれぞれ MyClass1.php および MyClass2.php からロードします。

<?php
spl_autoload_register(function ($class_name) {
include $class_name . '.php';
});

$obj = new MyClass1();
$obj2 = new MyClass2();
?>

例2 オートロードの別の例

この例は、インターフェイス ITest をロードしようとします。

<?php

spl_autoload_register(function ($name) {
var_dump($name);
});

class Foo implements ITest {
}

/*
string(5) "ITest"

Fatal error: Interface 'ITest' not found in ...
*/
?>

参考

  • unserialize()
  • unserialize_callback_func
  • unserialize_max_depth
  • spl_autoload_register()
  • spl_autoload()
  • __autoload()


コンストラクタとデストラクタ

コンストラクタ

__construct(mixed ...$values = ""): void

PHP では、開発者がクラスのコンストラクタメソッドを宣言することが できます。コンストラクタメソッドを有するクラスは、新たにオブジェクトが 生成される度にこのメソッドをコールします。これにより、 そのオブジェクトを使用する前に必要な初期化を行うことができます。

注意: 子クラスがコンストラクタを有している場合、親クラスのコンストラクタが 暗黙の内にコールされることはありません。 親クラスのコンストラクタを実行するには、子クラスのコンストラクタの 中で parent::__construct() をコールすることが 必要です。 子クラスでコンストラクタを定義していない場合は、親クラスのコンストラクタを継承します (ただし、private 宣言されている場合は除く)。 これは、通常のクラスメソッドと同様です。

例1 継承とコンストラクタ

<?php
class BaseClass {
function __construct() {
print "In BaseClass constructor\n";
}
}

class SubClass extends BaseClass {
function __construct() {
parent::__construct();
print "In SubClass constructor\n";
}
}

class OtherSubClass extends BaseClass {
// BaseClass のコンストラクタを継承します
}

// In BaseClass constructor
$obj = new BaseClass();

// In BaseClass constructor
// In SubClass constructor
$obj = new SubClass();

// In BaseClass constructor
$obj = new OtherSubClass();
?>

他のメソッドと異なり、__construct() を子クラスでオーバライドしても、 シグネチャの互換性に関するルール は適用されません。

コンストラクタは、対応するオブジェクトを初期化する間に呼び出されるメソッドです。 よって、任意の数の引数を取ることが出来ます。 この引数は必須にすることもできますし、型宣言もできますし、デフォルト値を取ったりすることもできます。 コンストラクタの引数は、クラス名の後の括弧に、引数を置くことで指定することが出来ます。

例2 コンストラクタを引数と一緒に使う

<?php
class Point {
protected int $x;
protected int $y;

public function __construct(int $x, int $y = 0) {
$this->x = $x;
$this->y = $y;
}
}

// 引数を両方渡す
$p1 = new Point(4, 5);
// 必須の引数のみを渡す。$y はデフォルト値0になります。
$p2 = new Point(4);
// 名前付き引数(PHP 8.0 以降):
$p3 = new Point(y: 5, x: 4);
?>

クラスにコンストラクタが存在しない場合、あるいは、コンストラクタに必須の引数がない場合、 括弧は省略できます。

古いスタイルのコンストラクタ

PHP 8.0.0 より前のバージョンでは、グローバル名前空間にあるクラスは、 クラス名と同じ名前のメソッドが古いスタイルのコンストラクタとして解釈されます。 この文法は推奨されておらず、E_DEPRECATED が発生するものの、 まだこの関数をコンストラクタとして呼び出すことが出来ます。 __construct() とクラス名と同じ名前のメソッドが両方定義されていた場合は、 __construct() がコンストラクタとして呼び出されます。

名前空間の中に存在するクラスについては、 PHP 8.0.0 以降では、 クラス名と同じ名前のメソッドはなんの意味も持ちません。

新しいコードでは、常に __construct() を使うようにしましょう。

コンストラクタのプロモーション

PHP 8.0.0 以降では、コンストラクタの引数を 対応するオブジェクトのプロパティに昇格させることができます。 コンストラクタの引数をプロパティに代入し、それ以外の操作を行わないことはよくあることです。 コンストラクタのプロモーションは、こういった場合の短縮記法を提供します。 「コンストラクタを引数と一緒に使う」の例は、次のように書き直すことが出来ます。

例3 コンストラクタのプロモーションを使う

<?php
class Point {
public function __construct(protected int $x, protected int $y = 0) {
}
}

コンストラクタの引数に修飾子が含まれている場合、 PHP はそれをオブジェクトのプロパティ、かつコンストラクタの引数であると解釈します。 そして、その引数の値をプロパティに代入します。 コンストラクタの本体は空にすることもできますし、 他の文を含めることも出来ます。 引数の値が対応するプロパティに代入された後、 追加の文が実行されます。

全ての引数をプロパティに昇格させる必要はありません。 昇格させる引数と、させない引数を混ぜることもできます。 プロパティに昇格した引数は、コンストラクタの呼び出しコードになんの影響も与えません。

注意:

アクセス権 の修飾子 (public, protected, private) を使うことが、プロパティの昇格を行わせるもっとも適したやり方ですが、 他にも (readonly のような) 単一の修飾子を使っても、 同じ昇格の効果が得られます。

注意:

PHP のエンジンが曖昧になってしまうため、 オブジェクトのプロパティは、callable 型にすることは出来ません。 そのため、昇格させる引数も callable 型にはできません。 しかし、それ以外の 型宣言 は許されています。

注意:

コンストラクタで昇格したプロパティはプロパティと関数のパラメータ両方に戻されるので、プロパティとパラメータの両方に対するあらゆる命名規則が適用されます。

注意:

昇格したコンストラクタの引数に指定された アトリビュート は、 プロパティと引数の両方にコピーされます。 昇格したコンストラクタの引数に指定されたデフォルト値は、 引数にだけコピーされます。プロパティにはコピーされません。

初期化時の new キーワード

PHP 8.1.0 以降では、 引数のデフォルト値の初期化時、 static 変数の初期化時、 グローバルな定数の初期化時に、 new を指定したオブジェクトが使えます。 同じものを、アトリビュートの引数や define() に渡せるようにもなっています。

注意:

この文脈で、動的なクラス名、文字列でないクラス名、 無名クラスを指定することはできません。 また、配列で引数を展開させることはできません。 未サポートの式を引数に指定することもできません。

例4 初期化時に new キーワードを使う

<?php

// 以下は全て許可されます
static $x = new Foo;

const C = new Foo;

function test($param = new Foo) {}

#[AnAttribute(new Foo)]
class Test {
public function __construct(
public $prop = new Foo,
) {}
}

// 以下はいずれも許されません(コンパイルエラーになります)
function test(
$a = new (CLASS_NAME_CONSTANT)(), // 動的なクラス名
$b = new class {}, // 無名クラス
$c = new A(...[]), // 引数の展開
$d = new B($abc), // 定数式の展開はサポートされていません
) {}
?>

static な生成メソッド

PHP は、クラスひとつにつき、コンストラクタをひとつだけサポートしています。 しかし、場合によっては異なる入力を使い、 異なるやり方でオブジェクトを生成させるのが望ましい場合もあります。 その場合におすすめなのが、staticメソッドをコンストラクタのラッパーとして使うことです。

例5 static な生成メソッドを使う

<?php
class Product {

private ?int $id;
private ?string $name;

private function __construct(?int $id = null, ?string $name = null) {
$this->id = $id;
$this->name = $name;
}

public static function fromBasicData(int $id, string $name): static {
$new = new static($id, $name);
return $new;
}

public static function fromJson(string $json): static {
$data = json_decode($json, true);
return new static($data['id'], $data['name']);
}

public static function fromXml(string $xml): static {
// Custom logic here.
$data = convert_xml_to_array($xml);
$new = new static();
$new->id = $data['id'];
$new->name = $data['name'];
return $new;
}
}

$p1 = Product::fromBasicData(5, 'Widget');
$p2 = Product::fromJson($some_json_string);
$p3 = Product::fromXml($some_xml_string);

コンストラクタは外部から呼ばれることを防ぐため、private または protected にしておきます。 この場合、staticメソッドだけがクラスをインスタンス化するのに使えます。 なぜなら、staticメソッドは、同じオブジェクトのインスタンスでなくとも、 private なメソッドにアクセスできる同じクラスのメソッド定義として存在するからです。 コンストラクタを private にすることはオプションです。使い方によっては意味がないかもしれません...

上の public なstaticメソッドは、オブジェクトをインスタンス化する3つの異なるやり方を示しています。

  • fromBasicData() は、必要となる必須の引数を取り、 コンストラクタを呼ぶことでオブジェクトを生成し、その結果を返します。
  • fromJson() は、JSON文字列を受け取り、 コンストラクタで必要なフォーマットに変換するための前処理を行います。 その上で、新しいオブジェクトを返します。
  • fromXml() は、XML文字列を受け取り、前処理をします。 そして生のオブジェクトを生成します。コンストラクタは呼び出されていますが、 全ての引数はオプションなので、その実行はスキップされます。 結果を返す前に、オブジェクトのプロパティに直接値を代入しています。

上の3つの場合全てで、static キーワードはコードが存在するクラスの名前として解釈されます。 この場合は Product です。

デストラクタ

__destruct(): void

PHP には、C++ のような他のオブジェクト指向言語に似たデストラクタの概念があります。 デストラクタメソッドは、 特定のオブジェクトを参照するリファレンスがひとつもなくなったときにコールされます。 あるいは、スクリプトの終了時にも順不同でコールされます。

例6 デストラクタの例

<?php

class MyDestructableClass
{
function __construct() {
print "In constructor\n";
}

function __destruct() {
print "Destroying " . __CLASS__ . "\n";
}
}

$obj = new MyDestructableClass();

コンストラクタと同様、親クラスのデストラクタがエンジンにより暗黙のうちに コールされるということはありません。親クラスのデストラクタを実行するには、 デストラクタの中で明示的に parent::__destruct() をコールする必要があります。 また、コンストラクタと同様、子クラスでデストラクタを定義していない場合は 親クラスのデストラクタを継承します。

exit() でスクリプトの実行を止めた場合にもデストラクタはコールされます。 デストラクタの内部で exit() をコールすると、 それ以降のシャットダウンルーチンを実行しません。

注意:

スクリプトのシャットダウン時にデストラクタがコールされた場合は、 HTTP ヘッダはすでに送信されています。スクリプトのシャットダウン時の作業ディレクトリは、 SAPI によっては (たとえば Apache など) 異なります。

注意:

デストラクタの中から (スクリプトの終了処理時に) 例外をスローしようとすると、致命的なエラーを引き起こします。


アクセス権

プロパティ、メソッドまたは (PHP 7.1.0 以降) 定数のアクセス権 (visibility) は、 キーワード: public, protected または private を指定することにより定義できます。 public 宣言されたクラスのメンバーには、どこからでもアクセス可能です。 protected 宣言されたメンバーには、 そのクラス自身、そのクラスを継承したクラス、および親クラスからのみアクセスできます。 private 宣言されたメンバーには、そのメンバーを定義したクラスからのみアクセスできます。

プロパティのアクセス権

クラスのプロパティは、public, private, または protected として定義することができます。 アクセス権を明示的に指定しない場合、 そのプロパティは 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 はできません。
public $public = 'Public2';
protected $protected = 'Protected2';

function printHello()
{
echo $this->public;
echo $this->protected;
echo $this->private;
}
}

$obj2 = new MyClass2();
echo $obj2->public; // 動作します
echo $obj2->protected; // Fatal エラー
echo $obj2->private; // 未定義です
$obj2->printHello(); // Public2, Protected2, Undefined を表示します

?>

メソッドのアクセス権

クラスメソッドは、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
?>

定数のアクセス権

PHP 7.1.0 以降では、クラスの定数は public, private, protected として定義できるようになりました。 明示的に公開範囲のキーワードを明示的に宣言しない定数は、public として定義されます。

例3 PHP 7.1.0 以降での定数の宣言

<?php
/**
* MyClass を定義する
*/
class MyClass
{
// public な定数を宣言する
public const MY_PUBLIC = 'public';

// protected な定数を宣言する
protected const MY_PROTECTED = 'protected';

// private な定数を宣言する
private const MY_PRIVATE = 'private';

public function foo()
{
echo self::MY_PUBLIC;
echo self::MY_PROTECTED;
echo self::MY_PRIVATE;
}
}

$myclass = new MyClass();
MyClass::MY_PUBLIC; // 動作します
MyClass::MY_PROTECTED; // Fatal エラー
MyClass::MY_PRIVATE; // Fatal エラー
$myclass->foo(); // Public, Protected, Private のいずれでも動作します

/**
* MyClass2 を定義する
*/
class MyClass2 extends MyClass
{
// これは public
function foo2()
{
echo self::MY_PUBLIC;
echo self::MY_PROTECTED;
echo self::MY_PRIVATE; // Fatal エラー
}
}

$myclass2 = new MyClass2;
echo MyClass2::MY_PUBLIC; // 動作します
$myclass2->foo2(); // Public, Protected では動作しますが、Private では動作しません
?>

他のオブジェクトからのアクセス権

同じ型のオブジェクト間では、たとえ同一のインスタンスでなくても お互いの private メンバーや protected メンバーにアクセスすることができます。 これは、そのオブジェクトの内部ではオブジェクトの実装の詳細が既知であるからです。

例4 同じ型のオブジェクトの 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 のメソッドや、プロパティや定数をすべて引き継ぎます。 (子の)クラスが親のメソッドを上書きしない限り、 親のメソッドの機能が保持されます。

これは、機能を定義して抽象化するのに便利です。 また、同じようなオブジェクトに機能を追加する際に、 共通機能を再実装する必要がなくなります。

親クラスの private メソッドは、子クラスからアクセスすることができません。 その結果として、子クラスは通常の継承のルールを無視して private メソッドそのものを再実装することができてしまいます。 しかし、PHP 8.0.0 より前のバージョンでは、 final と static に関連する制限が private メソッドに適用されていました。 PHP 8.0.0 以降では、private メソッドの規則が強制されるのは private final として宣言されたコンストラクタのみになりました。 なぜなら、static として宣言されたファクトリメソッドを使う場合に、 コンストラクタを無効にする方法として private final が用いられるからです。

メソッドやプロパティ、そして定数の アクセス権 に関するルールは、子クラスで緩めることが可能です。 たとえば、 親クラスで protected なメソッドは 子クラスで public としてマークできます。 しかし、厳しくすることはできません。 つまり、親クラスで public なプロパティを 子クラスで private にすることはできません。 これの例外はコンストラクタです。 コンストラクタのアクセス権は厳しくすることができます。 たとえば、親クラスの public なコンストラクタは、 子クラスで private としてマークできます。

注意:

オートローディングが有効になっていない限り、 クラスの定義は実際に使うより前になければなりません。 別のクラスを継承したクラスの場合は、 そのクラスより前に親クラスが宣言されていなければなりません。 この規則が適用されるのは、別のクラスやインターフェイスを継承したクラスです。

注意:

読み取りと書き込みが両方可能なプロパティを、 readonly として上書きしてはいけません。逆も同じです。

<?php

class A {
public int $prop;
}
class B extends A {
// 正しくありません: read-write -> readonly
public readonly int $prop;
}
?>

例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'

?>

内部クラスと戻り値の型の互換性

PHP 8.1 より前のバージョンでは、 ほとんどの内部クラスやメソッドは戻り値の型を宣言していませんでしたし、 それらを継承する際にもあらゆる戻り値の型を指定することができていました。

PHP 8.1.0 以降では、 ほとんどの内部メソッドが、戻り値の型を "とりあえず" 宣言するようになりました。 この場合、それらを継承したメソッドの戻り値の型は、 親と互換性があるものにすべきです。 そうしない場合、推奨されない警告が発生します。 注意すべきなのは、明示的に戻り値の型を宣言していない場合でも、 シグネチャが一致していないとみなされ、 推奨されない警告が発生することです。

PHP のバージョン間の互換性を保ちたいがために、 戻り値の型を宣言できない場合、 アトリビュート ReturnTypeWillChange を追加することで警告を抑止できます。

例2 戻り値の型を宣言せずにメソッドをオーバーライドする場合

<?php
class MyDateTime extends DateTime
{
public function modify(string $modifier) { return false; }
}

// PHP 8.1.0 以降では、"Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice"
?>

例3 間違った型を宣言してメソッドをオーバーライドする場合

<?php
class MyDateTime extends DateTime
{
public function modify(string $modifier): ?DateTime { return null; }
}

// PHP 8.1.0 以降では、"Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice"
?>

例4 間違った型を宣言してメソッドをオーバーライドする場合でも、警告を抑制する

<?php
class MyDateTime extends DateTime
{
/**
* @return DateTime|false
*/
#[\ReturnTypeWillChange]
public function modify(string $modifier) { return false; }
}

// 警告は発生しません。
?>


スコープ定義演算子 (::)

スコープ定義演算子 (またの名を Paamayim Nekudotayim)、 平たく言うと「ダブルコロン」は、トークンのひとつです。 定数 static プロパティ、 クラスの static メソッド、 や親クラスのそれにアクセスできます。 さらに、static メソッドやプロパティは 遅延静的束縛 (Late Static Bindings) 経由でオーバーライドできます。

これらの要素をクラス定義の外から参照する際には、 クラスの名前を使用してください。

変数を用いてクラスを参照することも可能です。 変数の値に (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;

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';
$classname::doubleColon();

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 メソッド や static プロパティを定義する方法を説明します。 static は、 static 変数 や static な無名関数、そして 遅延静的束縛 にも使えます。これらの場合の static の使い方は、 それぞれのページを参照ください。

クラスプロパティもしくはメソッドを static として宣言することで、 クラスのインスタンス化の必要なしにアクセスすることができます。 static として宣言されたプロパティやメソッドは、 インスタンス化されたオブジェクトの内部からも :: (スコープ定義演算子) を使ってコールできます。

static メソッド

static メソッドはオブジェクトのインスタンスを生成せずに コールすることができるので、疑似変数 $this は、 static として宣言されたメソッドの内部から利用することはできません。

警告

static でないメソッドをstaticメソッドとしてコールすると、 Error がスローされます。

PHP 8.0.0 より前のバージョンでは、 static でないメソッドをstaticメソッドとしてコールすることが非推奨になっており、 E_DEPRECATED レベルの警告が発生していました。

例1 static メソッドの例

<?php
class Foo {
public static function aStaticMethod() {
// ...
}
}

Foo::aStaticMethod();
$classname = 'Foo';
$classname::aStaticMethod();
?>

static プロパティ

static プロパティは、 スコープ定義演算子 を使ってアクセスできますが、 オブジェクト演算子 (->) を使ってアクセスすることはできません。

変数を用いてクラスを参照することも可能です。 変数の値に (self や parent、 static といった) キーワードを指定することはできません。

例2 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";

print Bar::$my_static . "\n";
$bar = new Bar();
print $bar->fooStatic() . "\n";
?>

上の例の PHP 8 での出力は、たとえば以下のようになります。:

foo
foo

Notice: Accessing static property Foo::$my_static as non static in /in/V0Rvv on line 23

Warning: Undefined property: Foo::$my_static in /in/V0Rvv on line 23

foo
foo
foo
foo


クラスの抽象化

PHP には、抽象クラスと抽象メソッドの機能があります。 abstract として定義されたクラスのインスタンスを生成することはできません。 1つ以上の抽象メソッドを含む全てのクラスもまた抽象クラスとなります。 abstract として定義されたメソッドは、そのメソッドのシグネチャを宣言するのみで、 実装を定義することはできません。

抽象クラスから継承する際、親クラスの宣言で abstract としてマークされた 全てのメソッドは、子クラスで定義されなければなりません。加えて、 オブジェクトの継承 と シグネチャの互換性に関するルール に従わなければいけません。

例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

例2 抽象クラスの例

<?php
abstract class AbstractClass
{
// 抽象メソッドでは、必須の引数だけを定義しています
abstract protected function prefixName($name);

}

class ConcreteClass extends AbstractClass
{

// 子クラスでは、親のシグネチャにないオプション引数を定義することもあるでしょう
public function prefixName($name, $separator = ".") {
if ($name == "Pacman") {
$prefix = "Mr";
} elseif ($name == "Pacwoman") {
$prefix = "Mrs";
} else {
$prefix = "";
}
return "{$prefix}{$separator} {$name}";
}
}

$class = new ConcreteClass;
echo $class->prefixName("Pacman"), "\n";
echo $class->prefixName("Pacwoman"), "\n";
?>

上の例の出力は以下となります。

Mr. Pacman
Mrs. Pacwoman


オブジェクト インターフェイス

オブジェクト インターフェイスを使うと、 メソッドの実装を定義せずに、 クラスが実装する必要があるメソッドを指定するコードを作成できます。 インターフェイス は クラス や トレイト と名前空間を共有するので、 それらと同じ名前を使ってはいけません。

インターフェイスは通常のクラスと同様に定義することができますが、 キーワード class のかわりに interface を用います。またメソッドの実装は全く定義しません。

インターフェイス内で宣言される全てのメソッドは public である必要があります。 これは、インターフェイスの特性によります。

インターフェイスには、ふたつの互いを補完する役割があります。

  • 同じインターフェイスを実装していることで、 開発者が交換可能な異なるクラスを作成できるようにします。 同じインターフェイスを持つクラスによくある例として、 複数のデータベースにアクセスするサービスや 決済のゲートウェイ、 異なるキャッシュ戦略が挙げられます。 実装が異なっていても、 それを使うコードに変更を加えることなく、それらを交換することができます。
  • メソッドや関数が、インターフェイスを満たす引数を受け付け、 操作できるようにします。 オブジェクトが何をするのかや、 どう実装されているのかを気にする必要はありません。 振る舞いの重要性を説明するために、 Iterable や Cacheable、 Renderable のような名前が付けられることがよくあります。

インターフェイスは、 マジックメソッド を宣言しても問題ありません。

注意:

コンストラクタ をインターフェイスで宣言できますが、全くおすすめできません。 そうしてしまうと、 インターフェイスを実装するクラスの柔軟性が大きく損なわれる上、 コンストラクタには継承ルールが適用されないため、 一貫しない、予期せぬ結果を生む可能性があるからです。

implements

インターフェイスを実装するには、implements 演算子を使用し、 このインターフェイスに含まれる全てのメソッドを実装する必要があります。 実装されていない場合、致命的エラーとなります。 各インターフェイスをカンマで区切って指定することで、 クラスは複数のインターフェイスを実装することができます。

警告

インターフェイスを実装するクラスでは、 インターフェイス内の名前とは異なる名前を メソッドの引数に使うことができます。 しかし、PHP 8.0 以降では 名前付き引数 がサポートされています。 これは、メソッドをコールする側がインターフェイス内の名前に依存する可能性があるということです。 そうした理由から、開発者は実装されるインターフェイスと同じ引数名を使うことを強く推奨します。

注意:

クラスと同様、インターフェイスも extends 演算子で継承することができます。

注意:

インターフェイスを実装したクラスでは、 シグネチャの互換性に関するルール を守った形で、インターフェイス内の全てのメソッドを宣言しなければいけません。 クラスは、同じ名前のメソッドを定義した複数のインターフェイスを実装することが出来ます。 この場合、実装されるメソッドは全て、 シグネチャの互換性に関するルール に従わなければいけません。 そうすることで、共変性と反変性 のルールも適用できます。

定数

インターフェイスに定数を持たせることもできます。 インターフェイス定数は クラス定数 とまったく同じように動作します。 PHP 8.1.0 より前のバージョンでは、 そのインターフェイスを継承したクラスやインターフェイスから定数をオーバーライドすることができませんでした。

例

例1 Interface の例

<?php

// インターフェイス 'Template' を宣言する
interface Template
{
public function setVariable($name, $var);
public function getHtml($template);
}

// インターフェイスを実装する。
// これは動作します。
class WorkingTemplate implements Template
{
private $vars = [];

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 (Template::getHtml)
class BadTemplate implements Template
{
private $vars = [];

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
class Foo {}
class Bar extends Foo {}

interface A {
public function myfunc(Foo $arg): Foo;
}

interface B {
public function myfunc(Bar $arg): Bar;
}

class MyClass implements A, B
{
public function myfunc(Foo $arg): Bar
{
return new Bar();
}
}
?>

例4 複数のインターフェイスの継承

<?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()
{
}
}
?>

例5 インターフェイスでの定数

<?php
interface A
{
const B = 'Interface constant';
}

// Interface constant と表示します。
echo A::B;

class B implements A
{
const B = 'Class constant';
}

// Class constant と表示します。
// PHP 8.1.0 より前のバージョンでは、定数をオーバライドできなかったため、これは動作しませんでした。
echo B::B;
?>

例6 抽象クラスとインターフェイス

<?php
interface A
{
public function foo(string $s): string;

public function bar(int $i): int;
}

// 抽象クラスは、インターフェイスの一部のみを実装しても構いません。
// 抽象クラスを継承したクラスは、未実装の残りのメソッドを実装しなければなりません。
abstract class B implements A
{
public function foo(string $s): string
{
return $s . PHP_EOL;
}
}

class C extends B
{
public function bar(int $i): int
{
return $i * 2;
}
}
?>

例7 継承と実装を同時に行う

<?php

class One
{
/* ... */
}

interface Usable
{
/* ... */
}

interface Updatable
{
/* ... */
}

// ここでは、キーワードの順番が重要です。
// 'extends' を始めに置かなければいけません。
class Two extends One implements Usable, Updatable
{
/* ... */
}
?>

インターフェイスと型宣言を組み合わせると、 特定のオブジェクトに特定のメソッドをうまく持たせることができます。 instanceof 演算子および 型宣言 を参照ください。


トレイト

PHP は、コードを再利用するための「トレイト」という仕組みを実装しています。

トレイトは、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 演算子を使うと、 メソッドのいずれかにエイリアスを追加できます。 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!

トレイトのメンバーの抽象化

トレイトでは、抽象メソッドを使ってクラスの要件を指定できます。 アクセス権は public, protected, private をサポートしています。 PHP 8.0.0 より前のバージョンでは、 public と protected な抽象メソッドだけがサポートされていました。

警告

PHP 8.0.0 以降では、具象メソッドは シグネチャの互換性に関するルール を満たさなければなりません。 これより前のバージョンでは、シグネチャは異なっていても構いませんでした。

例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;
}
}
?>

トレイトの static メンバー

トレイトでは、static 変数、static メソッド、static プロパティを定義できます。

注意:

PHP 8.1.0 以降では、トレイトにある static メソッドや、 static プロパティに直接アクセスすることは、 推奨されなくなりました。 これらは、トレイトを使っているクラスからのみアクセスすべきものです。

例9 static変数

<?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 staticメソッド

<?php
trait StaticExample {
public static function doSomething() {
return 'Doing something';
}
}

class Example {
use StaticExample;
}

Example::doSomething();
?>

例11 staticプロパティ

<?php
trait StaticExample {
public static $static = 'foo';
}
class Example {
use StaticExample;
}
echo Example::$static;
?>

プロパティ

トレイトにはプロパティも定義できます。

例12 プロパティの定義

<?php
trait PropertiesTrait {
public $x = 1;
}

class PropertiesExample {
use PropertiesTrait;
}

$example = new PropertiesExample;
$example->x;
?>

トレイトでプロパティを定義したときは、 クラスではそれと互換性 (公開範囲と型とreadonlyの有無、そして初期値が同じ) がない同じ名前のプロパティを定義できません。 互換性がない名前を定義すると、致命的なエラーが発生します。

例13 衝突の解決

<?php
trait PropertiesTrait {
public $same = true;
public $different1 = false;
public bool $different2;
public bool $different3;
}

class PropertiesExample {
use PropertiesTrait;
public $same = true;
public $different1 = true; // Fatal error
public string $different2; // Fatal error
readonly protected bool $different3; // Fatal error
}
?>

定数

PHP 8.2.0 以降では、トレイトでも定数を定義できます。

例14 定数を定義する

<?php
trait ConstantsTrait {
public const FLAG_MUTABLE = 1;
final public const FLAG_IMMUTABLE = 5;
}

class ConstantsExample {
use ConstantsTrait;
}

$example = new ConstantsExample;
echo $example::FLAG_MUTABLE; // 1
?>

トレイトで定数を定義したときは、 クラスではそれと互換性 (公開範囲と初期値、そして final の有無が同じ) がない同じ名前の定数を定義できません。 互換性がない名前を定義すると、致命的なエラーが発生します。

例15 衝突の解決

<?php
trait ConstantsTrait {
public const FLAG_MUTABLE = 1;
final public const FLAG_IMMUTABLE = 5;
}

class ConstantsExample {
use ConstantsTrait;
public const FLAG_IMMUTABLE = 5; // Fatal error
}
?>


無名クラス

無名クラスは、その場限りの使い捨てのオブジェクトが必要になった場合に便利です。

<?php

// 明示的にクラスを宣言して使う
class Logger
{
public function log($msg)
{
echo $msg;
}
}

$util->setLogger(new Logger());

// 無名クラスを使う
$util->setLogger(new class {
public function log($msg)
{
echo $msg;
}
});

コンストラクタを使って引数を渡したり、他のクラスを継承したり、 インターフェイスを実装したり、トレイトを使ったりといった、 普通のクラスと同じようなことが可能です。

<?php

class SomeClass {}
interface SomeInterface {}
trait SomeTrait {}

var_dump(new class(10) extends SomeClass implements SomeInterface {
private $num;

public function __construct($num)
{
$this->num = $num;
}

use SomeTrait;
});

上の例の出力は以下となります。

object(class@anonymous)#1 (1) {
  ["Command line code0x104c5b612":"class@anonymous":private]=>
  int(10)
}

無名クラスを別のクラス内で作っても、外側のクラスの private や protected なメソッド、 およびプロパティにはアクセスできません。 外側のクラスの protected プロパティやメソッドにアクセスするには、 無名クラスに外側のクラスを継承させます。 外側のクラスの private プロパティを無名クラスで使うには、 コンストラクタでそれを渡す必要があります。

<?php

class Outer
{
private $prop = 1;
protected $prop2 = 2;

protected function func1()
{
return 3;
}

public function func2()
{
return new class($this->prop) extends Outer {
private $prop3;

public function __construct($prop)
{
$this->prop3 = $prop;
}

public function func3()
{
return $this->prop2 + $this->prop3 + $this->func1();
}
};
}
}

echo (new Outer)->func2()->func3();

上の例の出力は以下となります。

6

同じ無名クラス宣言から作ったすべてのオブジェクトは、その同じクラスのインスタンスとなります。

<?php
function anonymous_class()
{
return new class {};
}

if (get_class(anonymous_class()) === get_class(anonymous_class())) {
echo '同じクラス';
} else {
echo '違うクラス';
}

上の例の出力は以下となります。

同じクラス

注意:

無名クラスには内部的な名前が付けられていることに注意しましょう。これは次の例で確認できます。 ただこれは細部の実装上の話なので、この名前に依存するコードを書いてはいけません。

<?php
echo get_class(new class {});

上の例の出力は、 たとえば以下のようになります。

class@anonymous/in/oNi1A0x7f8636ad2021


オーバーロード

PHP におけるオーバーロード機能は、 プロパティやメソッドを動的に 作成する ための手法です。 これらの動的エンティティは、マジックメソッドを用いて処理されます。 マジックメソッドは、クラス内でさまざまなアクションに対して用意することができます。

オーバーロードメソッドが起動するのは、 宣言されていないプロパティやメソッドを操作しようとしたときです。 また、現在のスコープからは アクセス不能な プロパティやメソッドを操作しようとしたときにも起動します。 このセクションでは、これらの (宣言されていない、 あるいは現在のスコープからはアクセス不能な) プロパティやメソッドのことを アクセス不能プロパティ および アクセス不能メソッド と表記することにします。

オーバーロードメソッドは、すべて public で定義しなければなりません。

注意:

これらのマジックメソッドの引数は、 リファレンス渡し とすることはできません。

注意:

PHP における オーバーロード の解釈は、他の多くのオブジェクト指向言語とは異なります。 一般的に「オーバーロード」とは、 「名前は同じだけれども引数の数や型が異なるメソッドを複数用意できる」 という機能のことを指します。

プロパティのオーバーロード

public __set(string $name, mixed $value): void
public __get(string $name): mixed
public __isset(string $name): bool
public __unset(string $name): void

__set() は、 アクセス不能(protected または private)または存在しないプロパティへデータを書き込む際に実行されます。

__get() は、 アクセス不能(protected または private)または存在しないプロパティからデータを読み込む際に使用します。

__isset() は、 isset() あるいは empty() をアクセス不能(protected または private)または存在しないプロパティに対して実行したときに起動します。

__unset() は、 unset() をアクセス不能(protected または private)または存在しないプロパティに対して実行したときに起動します。

引数 $name は、 操作しようとしたプロパティの名前です。 __set() メソッドの引数 $value は、 $name に設定しようとした値となります。

プロパティのオーバーロードはオブジェクトのコンテキストでのみ動作します。 これらのマジックメソッドは、static メソッドとしては呼び出されません。 したがって、これらのメソッドを static メソッドとして宣言してはいけません。 マジックメソッドを static メソッドとして宣言すると警告が発生します。

注意:

__set() の戻り値は無視されます。 これは、PHP が代入演算子を処理する方法によるものです。 同様に __get() は、

 $a = $obj->b = 8;
のように代入と連結した場合には決してコールされません。

注意:

PHP は、オーバーロードメソッドを、 同じオーバーロードメソッドから決してコールしません。 これはたとえば、__get() の内部に return $this->foo というコードを書いたとしても、 foo というプロパティが定義されていなければ E_WARNING が発生し、null を返すということです。 2回目の __get() のコールを行ったりはしません。 しかし、オーバーロードメソッドが、他のオーバーロードメソッドを暗黙のうちに呼び出す可能性はあります(たとえば、 __set() が __get() を呼び出す場合)。

例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;
}

public function __isset($name)
{
echo "Is '$name' set?\n";
return isset($this->data[$name]);
}

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 __call(string $name, array $arguments): mixed
public static __callStatic(string $name, array $arguments): mixed

__call() は、 アクセス不能メソッドをオブジェクトのコンテキストで実行したときに起動します。

__callStatic() は、 アクセス不能メソッドをstatic メソッドとして呼び出した場合に起動します。

引数 $name は、 コールしようとしたメソッドの名前です。 引数 $arguments は配列で、メソッド $name に渡そうとしたパラメータが格納されます。

例2 __call() および __callStatic() メソッドによる、メソッドのオーバーロードの例

<?php
class MethodTest
{
public function __call($name, $arguments)
{
// 注意: $name は大文字小文字を区別します
echo "Calling object method '$name' "
. implode(', ', $arguments). "\n";
}

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');
?>

上の例の出力は以下となります。

Calling object method 'runTest' in object context
Calling static method 'runTest' in static context


オブジェクトの反復処理

PHP は、たとえば foreach 命令などによる反復処理を可能とするように、 オブジェクトを定義する手段を提供します。 デフォルトで、 全ての アクセス権限がある プロパティは、反復処理に使用することができます。

例1 単純なオブジェクトの反復の例

<?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 による反復処理がすべての アクセス権がある プロパティについて行われています。

参考

  • Generators
  • Iterator
  • IteratorAggregate
  • SPL Iterators


マジックメソッド

マジックメソッドは、 ある動作がオブジェクトに対して行われた場合に、 PHP のデフォルトの動作を上書きする特別なメソッドです。

警告

__ で始まる全てのメソッドは、 PHP によって予約されています。 よって、PHP の動作を上書きするのでなければ、 このようなメソッド名を使うことは推奨されません。

以下の関数名は、マジックメソッドと見なされます:

__construct(),
__destruct(),
__call(),
__callStatic(),
__get(),
__set(),
__isset(),
__unset(),
__sleep(),
__wakeup(),
__serialize(),
__unserialize(),
__toString(),
__invoke(),
__set_state(),
__clone(),
__debugInfo()

警告

__construct(),
__destruct(),
__clone() を除く全てのマジックメソッドは、
public として宣言しなければいけません。
そうしないと、
E_WARNING レベルの警告が発生します。
PHP 8.0.0 より前のバージョンでは、
__sleep(),
__wakeup(),
__serialize(),
__unserialize(),
__set_state() については、エラーは発生していませんでした。

警告

マジックメソッドの定義で型宣言が使われている場合、 それらは、このマニュアルで説明しているシグネチャと同じでなければいけません。 そうでない場合、致命的なエラーが発生します。 PHP 8.0.0 より前のバージョンでは、 エラーは全く発生していませんでした。 但し、__construct() と __destruct() については、戻り値の型を宣言してはいけません。 宣言してしまうと、致命的なエラーが発生します。

__sleep() と __wakeup()

public __sleep(): array
public __wakeup(): void

serialize() は、クラスに特殊な名前 __sleep() の関数があるかどうかを調べます。 もしあれば、シリアル化の前にその関数を実行します。 この関数で、オブジェクトをクリアすることができます。 またこの関数は、シリアル化するオブジェクトについて、 すべての変数の名前を配列で返すことが前提となっています。 このメソッドが何も返さなかった場合は、null がシリアル化され、E_NOTICE が発生します。

注意:

__sleep() で、親クラスの private プロパティの名前を返すことはできません。 そうしようとすると E_NOTICE レベルのエラーとなります。 この場合は、__serialize() を代わりに使って下さい。

注意:

PHP 8.0.0 以降では、 __sleep() から配列でない値を返すと、 E_WARNING が発生するようになりました。これより前のバージョンでは、 E_NOTICE が発生していました。

典型的な __sleep() の使用法は、 途中のデータをコミットしたり、 似たようなタスクのクリアを行うといったものです。 また、オブジェクトが非常に大きく、かつ、完全に保存する必要がない場合、 この関数が有用です。

逆に、unserialize() は、 特殊な名前 __wakeup() を有する 関数の存在を調べます。 もし存在する場合、この関数は、オブジェクトが有する可能性が あるあらゆるリソースを再構築することができます。

__wakeup() の使用目的は、 シリアル化の際に失われたデータベース接続を再度確立したり、 その他の再初期化を行うことです。

例1 sleep と wakeup

<?php
class Connection
{
protected $link;
private $dsn, $username, $password;

public function __construct($dsn, $username, $password)
{
$this->dsn = $dsn;
$this->username = $username;
$this->password = $password;
$this->connect();
}

private function connect()
{
$this->link = new PDO($this->dsn, $this->username, $this->password);
}

public function __sleep()
{
return array('dsn', 'username', 'password');
}

public function __wakeup()
{
$this->connect();
}
}?>

__serialize() と __unserialize()

public __serialize(): array
public __unserialize(array $data): void

serialize() は、クラスが 特殊な名前 __serialize() を持つかを調べます。 もしあれば、シリアル化の前にその関数を実行します。 この関数は、オブジェクトをシリアル化した状態を示すキー/値のペアを連想配列にして返さなければなりません。 配列を返さなかった場合、TypeError がスローされます。

注意:

__serialize() と __sleep() が両方同じオブジェクトに定義されていた場合、 __serialize() だけが呼び出されます。 __sleep() は無視されます。 オブジェクトが Serializable インターフェイスを実装していた場合、 インターフェイスの serialize() メソッドは無視され、 __serialize() が代わりに使われます。

__serialize() の目的は、 任意のオブジェクトの表現をシリアライズしやすいように定義することです。 配列の要素はオブジェクトのプロパティに対応していても構いませんが、必須ではありません。

逆に、unserialize() は
特殊な名前 __unserialize() を持つかを調べます。
もしあれば、__serialize() が返した配列を復元し、この関数に渡します。
この関数では、その配列から必要に応じてオブジェクトのプロパティを復元して構いません。

注意:

__unserialize() と __wakeup() が両方同じオブジェクトに定義されていた場合、 __unserialize() だけが呼び出されます。 __wakeup() は無視されます。

注意:

この機能は PHP 7.4.0 以降で利用できます。

例2 Serialize と unserialize

<?php
class Connection
{
protected $link;
private $dsn, $username, $password;

public function __construct($dsn, $username, $password)
{
$this->dsn = $dsn;
$this->username = $username;
$this->password = $password;
$this->connect();
}

private function connect()
{
$this->link = new PDO($this->dsn, $this->username, $this->password);
}

public function __serialize(): array
{
return [
'dsn' => $this->dsn,
'user' => $this->username,
'pass' => $this->password,
];
}

public function __unserialize(array $data): void
{
$this->dsn = $data['dsn'];
$this->username = $data['user'];
$this->password = $data['pass'];

$this->connect();
}
}?>

__toString()

public __toString(): string

__toString() メソッドにより、 クラスが文字列に変換される際の動作を決めることができます。たとえば echo $obj; としたときに何を表示させるかといったことです。

警告

PHP 8.0.0 以降では、戻り値は PHP で標準的な型のセマンティクスに従います。 つまり、厳密な型付け が無効になっている場合、可能であれば文字列型に強制されます。

厳密な型付け が有効になっている場合、string 型を宣言していても Stringable は受け入れられ ません。 受け入れさせたい場合、Stringable と string を union 型を使って型宣言しなければいけません。

PHP 8.0.0 以降では、 __toString() メソッドを含む全てのクラスは、 暗黙のうちに Stringable インターフェイスも実装するようになりました。 よって、このインターフェイスの型チェックは通過することになります。 いずれにせよ、明示的にこのインターフェイスを実装することを推奨します。

PHP 7.4 では、戻り値は文字列でなければいけません。 そうでない場合、Error がスローされます。

PHP 7.4.0 より前のバージョンでは、 戻り値は文字列でなければいけません。 そうでない場合、E_RECOVERABLE_ERROR が発生します。

警告

PHP 7.4.0 より前のバージョンでは、__toString() メソッド内から例外をスローすることはできません。そうした場合、致命的なエラーが発生します。

例3 簡単な例

<?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

__invoke()

__invoke( ...$values): mixed

__invoke() メソッドは、 スクリプトがオブジェクトを関数としてコールしようとした際にコールされます。

例4 __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)

例5 __invoke() の使用

<?php
class Sort
{
private $key;

public function __construct(string $key)
{
$this->key = $key;
}

public function __invoke(array $a, array $b): int
{
return $a[$this->key] <=> $b[$this->key];
}
}

$customers = [
['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
];

// $customers を 'first_name' でソートします
usort($customers, new Sort('first_name'));
print_r($customers);

// $customers を 'last_name' でソートします
usort($customers, new Sort('last_name'));
print_r($customers);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [id] => 3
            [first_name] => Alice
            [last_name] => Gustav
        )

    [1] => Array
        (
            [id] => 2
            [first_name] => Bob
            [last_name] => Filipe
        )

    [2] => Array
        (
            [id] => 1
            [first_name] => John
            [last_name] => Do
        )

)
Array
(
    [0] => Array
        (
            [id] => 1
            [first_name] => John
            [last_name] => Do
        )

    [1] => Array
        (
            [id] => 2
            [first_name] => Bob
            [last_name] => Filipe
        )

    [2] => Array
        (
            [id] => 3
            [first_name] => Alice
            [last_name] => Gustav
        )

)

__set_state()

static __set_state(array $properties): object

この static メソッドは、 var_export() によって エクスポートされたクラスのためにコールされます。

このメソッドの唯一のパラメータは、エクスポートされたプロパティを ['property' => value, ...] の形式で保持する配列です。

例6 __set_state() の使用法

<?php

class A
{
public $var1;
public $var2;

public static function __set_state($an_array)
{
$obj = new A;
$obj->var1 = $an_array['var1'];
$obj->var2 = $an_array['var2'];
return $obj;
}
}

$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';

$b = var_export($a, true);
var_dump($b);
eval('$c = ' . $b . ';');
var_dump($c);
?>

上の例の出力は以下となります。

string(60) "A::__set_state(array(
   'var1' => 5,
   'var2' => 'foo',
))"
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

注意: var_export() でオブジェクトをエクスポートする際に、 そのオブジェクトのクラスが __set_state() を実装しているかどうかはチェックされません。 よって、__set_state() が実装されていない場合、 エクスポートしたオブジェクトを再度インポートしようとすると、 Error 例外が発生します。 この振る舞いは、特に一部の内部クラスを扱う際に影響が出てきます。 エクスポートしたオブジェクトをインポートする際に、 __set_state() を実装するクラスのものだけをインポートさせるようにするのは、プログラマーの責務となります。

__debugInfo()

__debugInfo(): array

このメソッドは、var_dump() がオブジェクトをダンプするときに、 プロパティの情報を取得するために呼ばれます。 もしオブジェクトにこのメソッドが定義されていなければ、 すべての public, protected, private プロパティを表示します。

例7 __debugInfo() の使用法

<?php
class C {
private $prop;

public function __construct($val) {
$this->prop = $val;
}

public function __debugInfo() {
return [
'propSquared' => $this->prop ** 2,
];
}
}

var_dump(new C(42));
?>

上の例の出力は以下となります。

object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}


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";
}

// As the class is already final, the final keyword is redundant
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)
?>

例3 final定数の例(PHP 8.1.0 以降)

<?php
class Foo
{
final public const X = "foo";
}
class Bar extends Foo
{
public const X = "bar";
}
// Fatal error: Bar::X cannot override final constant Foo::X
?>

注意: プロパティを final として宣言することはできません。 final として宣言できるのはクラスとメソッド、 および定数(PHP 8.1.0以降)だけです。 PHP 8.0.0 以降は、private メソッドを final として宣言できるのはコンストラクタだけになりました。


オブジェクトのクローン作成

オブジェクトのコピーを作成する際、そのプロパティも全て二重化することが、 常に望ましい動作であるわけではありません。 コピーコンストラクタが必要となる例として、 GTKウインドウを表すオブジェクトを有しており、 そのオブジェクトがGTKウインドウのリソースを保持している際、 コピーを作成する時に、同じプロパティを有するウインドウを作成し、 その新しいオブジェクトがその新しいウインドウのリソースを保持する ようにしたい場合が考えられます。 他の例としては、 オブジェクトがそのオブジェクトが使用する他のオブジェクトへのリファレンスを 保持しており、親オブジェクトをコピーする際に、そのコピーが独立したオブジェクトの コピーを有するように、そのオブジェクトのインスタンスを新たに作成したい場合が 考えられます。

オブジェクトのコピーは、clone キーワード (これは、そのオブジェクトの __clone() メソッドがある場合にこれをコールします)により作成されます。

$copy_of_object = clone $object;

オブジェクトのクローンが作成される際、PHP は、そのオブジェクトのプロパティを 全てシャローコピーします。他の変数へのリファレンスを保持する全てのプロパティは、 リファレンスのままとなります。

__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
        )

)

新しくクローンしたオブジェクトのメンバーに、作成したその式の中でもアクセスできます:

例2 クローンしたオブジェクトのメンバーへのアクセス

<?php
$dateTime = new DateTime();
echo (clone $dateTime)->format('Y');
?>

上の例の出力は、 たとえば以下のようになります。

2016


オブジェクトの比較

比較演算子(==)を使用する際、 オブジェクト変数は、単純に比較されます。つまり、 二つのオブジェクトのインスタンスは、 同じ属性と値 (値の比較は == によるもの) を有し、同じクラスのインスタンスである場合に、 等しいとされます。

一致演算子(===)を使用する場合、 オブジェクト変数は、同じクラスの同じインスタンスを参照する場合のみ、 等しいとされます。

これらのルールを明確に示す例を以下に示します。

例1 オブジェクト比較の例

<?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 __construct($flag = true) {
$this->flag = $flag;
}
}

class OtherFlag
{
public $flag;

function __construct($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

注意:

拡張モジュール内では、自前で作成したオブジェクトの (== による) 比較方法を独自に定義することができます。


遅延静的束縛 (Late Static Bindings)

PHP には、遅延静的束縛と呼ばれる機能が搭載されています。 これを使用すると、静的継承のコンテキストで呼び出し元のクラスを参照できるようになります。

より正確に言うと、遅延静的束縛は直近の "非転送コール" のクラス名を保存します。
staticメソッドの場合、これは明示的に指定されたクラス (通常は
::
演算子の左側に書かれたもの) となります。staticメソッド以外の場合は、そのオブジェクトのクラスとなります。
"転送コール" とは、self:: や
parent::、static:: による :: 演算子を使ったコール。
あるいはクラス階層の中での forward_static_call() によるコールのことです。

get_called_class() 関数を使うとコール元のクラス名を文字列で取得できます。
static:: はこのクラスのスコープとなります。

この "遅延静的束縛" という機能名は、内部動作を考慮してつけられたものです。 "遅延束縛 (Late binding)" の由来は、メソッドを定義しているクラス名を使用しても static:: の解決ができないことによります。 その代わりに、実行時情報をもとに解決するようになります。 "静的束縛 (static binding)" の由来は、 staticメソッドのコールに使用できることによります (ただし、staticメソッド以外でも使用可能です)。

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:: は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 でのオブジェクト指向プログラミングのポイントとしてよく言われるのは 「オブジェクトはデフォルトでは参照渡しとなります」ということです。 しかし、正確には少し異なります。 この節では、いくつかの例を用いてその誤解をといていきます。

PHP の参照は一種のエイリアスで、ふたつの異なる変数に同じ値を書き込めるものです。 PHP では、オブジェクト変数の値にオブジェクト自身は含まれません。 含まれるのはオブジェクトの 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
// A.php:

class A {
public $one = 1;

public function show_one() {
echo $this->one;
}
}

// page1.php:

include "A.php";

$a = new A;
$s = serialize($a);
// $s を、page2.php からみつけられるどこかに書き出します
file_put_contents('store', $s);

// page2.php:

// シリアライズした文字列を復元するには、これが必要です
include "A.php";

$s = file_get_contents('store');
$a = unserialize($s);

// これで、$a オブジェクトの show_one() が使えるようになりました
$a->show_one();
?>

アプリケーション内でオブジェクトをシリアライズして再利用する場合のお勧めは、 そのクラスの定義をアプリケーション全体で include することです。 クラスの定義が存在しなければオブジェクトの復元に失敗してしまいます。 その場合、PHP は __PHP_Incomplete_Class_Name クラスのオブジェクトを返します。このオブジェクトにはメソッドは一切なく、 使い道がなくなってしまいます。

つまり、もし上の例の $a を スーパーグローバル $_SESSION に新しいキーを追加してセッションに格納するなら、 page1.php と page2.php だけではなく すべてのページで A.php を include しなければなりません。

ここまでで説明した以外の方法として、オブジェクトのシリアライズや復元のイベントを
__sleep() メソッドと
__wakeup() メソッドでフックすることができます。
__sleep() を使うと、
オブジェクトの一部のプロパティだけをシリアライズすることもできます。


共変性と反変性

PHP 7.2.0 で、子クラスのメソッドの引数の型の制限を除く形で、反変性が一部サポートされました。 PHP 7.4.0 以降で、共変性と反変性が完全にサポートされるようになりました。

共変性とは、子クラスのメソッドが、親クラスの戻り値よりも、より特定の、狭い型を返すことを許すことです。 一方で、反変性とは、親クラスのものよりも、より抽象的な、広い型を引数に指定することを許すものです。

型宣言は以下の場合に、より特定の、狭い型であると見なされます:

  • union 型 から、特定の型が削除されている場合
  • 特定の型が 交差型 に追加されている場合
  • クラスの型が、子クラスの型に変更されている場合
  • iterable が 配列 または Traversable に変更されている場合
上記と反対のことが当てはまる場合は、より抽象的な、広い型であると見なされます。

共変性

共変性がどのように動作するかを示すために、 単純な抽象クラスの親であるAnimal を作ることにします。 このクラスは子クラス Cat と Dog に継承されています。

<?php

abstract class Animal
{
protected string $name;

public function __construct(string $name)
{
$this->name = $name;
}

abstract public function speak();
}

class Dog extends Animal
{
public function speak()
{
echo $this->name . " barks";
}
}

class Cat extends Animal
{
public function speak()
{
echo $this->name . " meows";
}
}

この例では、どのメソッドも値を返さないことに注意して下さい。 以下ではこれらのクラスを使い、 Animal, Cat または Dog クラスの新しいオブジェクトを返すファクトリをいくつか作ってみることにします。

<?php

interface AnimalShelter
{
public function adopt(string $name): Animal;
}

class CatShelter implements AnimalShelter
{
public function adopt(string $name): Cat // Animal 型を返す代わりに、Cat型を返すことができる
{
return new Cat($name);
}
}

class DogShelter implements AnimalShelter
{
public function adopt(string $name): Dog // Animal 型を返す代わりに、Dog型を返すことができる
{
return new Dog($name);
}
}

$kitty = (new CatShelter)->adopt("Ricky");
$kitty->speak();
echo "\n";

$doggy = (new DogShelter)->adopt("Mavrick");
$doggy->speak();

上の例の出力は以下となります。

Ricky meows
Mavrick barks

反変性

既に示した Animal, Cat および Dog クラスの例を引き続き使い、 Food と AnimalFood クラスを追加し、 Animal 抽象クラスに eat(AnimalFood $food) メソッドを追加してみましょう。

<?php

class Food {}

class AnimalFood extends Food {}

abstract class Animal
{
protected string $name;

public function __construct(string $name)
{
$this->name = $name;
}

public function eat(AnimalFood $food)
{
echo $this->name . " eats " . get_class($food);
}
}

反変性 の振る舞いを見るため、Dog クラスの eat メソッドをオーバーライドし、あらゆる Food 型のオブジェクトを受け入れることにします。 Cat クラスは変更していません。

<?php

class Dog extends Animal
{
public function eat(Food $food) {
echo $this->name . " eats " . get_class($food);
}
}

さて、反変性がどのように動くかが以下でわかるでしょう。

<?php

$kitty = (new CatShelter)->adopt("Ricky");
$catFood = new AnimalFood();
$kitty->eat($catFood);
echo "\n";

$doggy = (new DogShelter)->adopt("Mavrick");
$banana = new Food();
$doggy->eat($banana);

上の例の出力は以下となります。

Ricky eats AnimalFood
Mavrick eats Food

しかし、$kitty の eat() メソッドに $banana を渡すとどうなるでしょう？

$kitty->eat($banana);

上の例の出力は以下となります。

Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given


変更履歴

PHP の OOP モデルの変更履歴をここに記録します。 個々の機能の説明や注意点については、クラスとオブジェクトに関するドキュメントを参照ください。

バージョン | 説明
8.1.0 | 追加: クラスの定数に対して、final が指定できるようになりました。インターフェイスの定数も、デフォルトでオーバーライドできるようになりました。
8.0.0 | 追加: null になる可能性があるオブジェクトのメソッドやプロパティにアクセスする手段として、nullsafe 演算子 ?-> をサポートしました。
7.4.0 | 変更: __toString() から、例外をスローすることができるようになりました。
7.4.0 | 追加: 戻り値の型を制限する 共変性 と、引数の型の 反変性 がサポートされました。 完全な型の変位指定は、オートローディングが使われている場合のみ有効です。 単一ファイル内では、型の参照が循環参照していない場合のみ可能です。
7.4.0 | 追加: クラスのプロパティは、型を宣言できるようになりました。
7.3.0 | 互換性のない変更: Traversable への引数のアンパックを int でないキーで行うことはサポートされなくなりました。 このような動作は意図されていなかったので、削除されました。
7.3.0 | 互換性のない変更: 7.3.0 より前のバージョンでは、参照を代入することによって、 static なプロパティが異なる値になる可能性がありました。 この振る舞いは削除されました。
7.3.0 | 変更: instanceof 演算子が、 最初のオペランドにリテラルを受け入れるようになりました。 この場合、結果は常に FALSE を返します。
7.2.0 | 推奨されない変更: __autoload() メソッドは非推奨になりました。 spl_autoload_register() を使うのが望ましいためです。
7.2.0 | 変更: 次の名前は、クラスや trait、 インターフェイスの名前として使うことが禁止されます: object
7.2.0 | 変更: 名前空間のグループ指定における最後のカンマが許可されるようになりました。
7.2.0 | 変更: パラメータの型の拡大変換が可能になりました。 オーバーライドされたメソッドや、インターフェイスの実装の 引数の型を省略できるようになりました。
7.2.0 | 変更: ある抽象クラスが別の抽象クラスを継承しているときに、 継承元クラスの抽象メソッドをオーバーライドできるようになりました。
7.1.0 | 変更: 以下のキーワードが、 クラスやインターフェイスやトレイトの名前として使えなくなりました: void と iterable
7.1.0 | 追加: クラス定数のアクセス範囲 を指定できるようになりました。
7.0.0 | 推奨されない変更: static 宣言されていないメソッドに対する static 呼び出しが非推奨となりました。
7.0.0 | 推奨されない変更: PHP 4 形式の コンストラクタ は非推奨になりました。 つまり、クラスと同じ名前のメソッドがクラスに定義されていた場合です。
7.0.0 | 追加: use 宣言のグループ化: 複数のクラスや関数そして定数を同じ namespace からインポートする際に、 単一の use 文にまとめられるようになりました。
7.0.0 | 追加: new class 経由での 無名クラス のサポートが追加されました。
7.0.0 | 互換性のない変更: Traversable ではない object の反復処理の挙動が、 array を参照渡しで反復処理したときと同じようになりました。
7.0.0 | 変更: (互換性のある) プロパティを2つの traits で使っても エラーにならなくなりました。
5.6.0 | 追加: __debugInfo() メソッド。
5.5.0 | 追加: ::class マジック定数。
5.5.0 | 追加: 例外処理に finally。
5.4.0 | 追加: トレイト が追加されました。
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 と直接組み合わせて使った場合のみでした。このバージョンからは、任意の string コンテキスト (printf() で %s 修飾子を使った場合など) でコールされるようになりました。ただし、他の型のコンテキスト (%d 修飾子を使った場合など) は除きます。 PHP 5.2.0 以降は、__toString メソッドを持たない object を string に変換しようとすると E_RECOVERABLE_ERROR レベルのエラーが発生します。
5.1.3 | 変更: PHP 5 の初期のバージョンでは var を使うことが非推奨とされており、E_STRICT レベルのエラーが発生していました。 このバージョンからは非推奨ではなくなり、エラーが発生しなくなりました。
5.1.0 | 変更: __set_state() メソッドが、 var_export() でエクスポートしたクラスに対してもコールされるようになりました。
5.1.0 | 追加: __isset() メソッドおよび __unset() メソッド。


名前空間

目次

  • 概要
  • 名前空間
  • サブ名前空間
  • 同一ファイル内での複数の名前空間の定義
  • 基本編
  • 名前空間と動的言語機能
  • namespace キーワードおよび __NAMESPACE__
  • エイリアス/インポート
  • グローバル空間
  • グローバル関数/定数への移行
  • 名前解決のルール
  • FAQ


名前空間の概要

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

名前空間とは何でしょう? 広義の「名前空間」とは、項目をカプセル化するもののことです。 これは多くの場面で見られる抽象概念です。 たとえば、たいていの 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\Classes など) は 言語の内部で使うために予約されており、ユーザーのコードで使うべきではありません。


名前空間の定義

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP のコードならなんでも名前空間に含めることができますが、 実際に名前空間の影響を受けるのはクラス (抽象クラスやトレイトを含む) とインターフェイス、関数、そして定数だけです。

名前空間を宣言するには、キーワード 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 7, PHP 8)

ディレクトリやファイルと同様、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, PHP 7, PHP 8)

複数の名前空間を同一ファイル内で宣言することもあります。 この場合の構文は次の 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 7, PHP 8)

名前空間の使い方についてあれこれ言う前に、まずは 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 7, PHP 8)

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";

/* ダブルクォートを使う場合は "\\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 7, PHP 8)

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 クラスのstaticメソッド "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 クラスのstaticメソッド "method" をコールします
$a = new namespace\sub\cname(); // sub\cname クラスのオブジェクトのインスタンスを作成します
$b = namespace\CONSTANT; // 定数 CONSTANT の値を $b に代入します
?>


名前空間の使用法: エイリアス/インポート

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

外部の完全修飾名をエイリアスで参照したりインポートしたりする機能は、 名前空間において非常に重要なものです。 これは、Unix 系のファイルシステムでファイルやディレクトリへのシンボリックリンクを作成することに似ています。

PHP は定数、関数、クラス、インターフェイス、トレイト、列挙型(Enum)、名前空間のエイリアスやインポートをサポートしています。

エイリアス作成には use 演算子を使用します。 ここに、5 種類すべてのインポート方法の例を示します。

例1 use 演算子によるインポート/エイリアス

<?php
namespace foo;
use My\Full\Classname as Another;

// これは use My\Full\NSname as NSname と同じです
use My\Full\NSname;

// グローバルクラスをインポートします
use ArrayObject;

// 関数をインポートします
use function My\Full\functionName;

// 関数のエイリアスを定義します
use function My\Full\functionName as func;

// 定数をインポートします
use const My\Full\CONSTANT;

$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 クラスのオブジェクトのインスタンスを作成することになります
func(); // 関数 My\Full\functionName を呼びます
echo CONSTANT; // 定数 My\Full\CONSTANT の値を表示します
?>
名前空間つきの名前 (完全修飾形式の名前空間は区切り文字を含んだ 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;

function toGreenlandic()
{
use Languages\Danish;

// ...
}
?>

注意:

インポート規則はファイル単位のものです。つまり、インクルードされたファイルは インクロード元の親ファイルのインポート規則を 引き継ぎません。

use 宣言のグループ化

同じ namespace から複数のクラスや関数そして定数をインポートする際には、 それらをひとつの use にまとめることができます。

<?php

use some\namespace\ClassA;
use some\namespace\ClassB;
use some\namespace\ClassC as C;

use function some\namespace\fn_a;
use function some\namespace\fn_b;
use function some\namespace\fn_c;

use const some\namespace\ConstA;
use const some\namespace\ConstB;
use const some\namespace\ConstC;

// 上記のコードは、グループ化されたuse宣言と同等です。
use some\namespace\{ClassA, ClassB, ClassC as C};
use function some\namespace\{fn_a, fn_b, fn_c};
use const some\namespace\{ConstA, ConstB, ConstC};


グローバル空間

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

名前空間の定義がない場合、すべてのクラスや関数の定義はグローバル空間に配置されます。 これは、名前空間に対応する前の PHP がサポートしていた空間です。 名前の先頭に \ をつけると、 名前空間の内部からであってもグローバル空間の名前を指定することができます。

例1 グローバル空間を指定する方法

<?php
namespace A\B\C;

/* この関数は A\B\C\fopen です */
function fopen() {
/* ... */
$f = \fopen(...); // グローバルな fopen をコールします
return $f;
}
?>


名前空間の使用法: グローバル関数/定数への移行

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

名前空間内で、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, PHP 7, PHP 8)

名前解決のルールを説明するにあたって、いくつかの重要な定義を示しておきます。

名前空間名の定義
非修飾名

これは名前空間区切り文字を含まない識別子で、Foo のようなものです。

修飾名

これは名前空間区切り文字を含む識別子で、Foo\Bar のようなものです。

完全修飾名

これは名前空間区切り文字を含む識別子のうち先頭が名前空間区切り文字で始まるもので、 \Foo\Bar のようなものです。名前空間 \Foo も完全修飾名です。

相対名

namespace\Foo\Bar のように、 namespace で始まる識別子です。

名前解決は、これらの解決ルールによって行われます。

  1. 完全修飾名は、先頭の名前空間区切り文字を除いた名前に常に解決されます。 たとえば、\A\B は A\B と解釈されます。
  2. 相対名は、namespace という名前を、 現在の名前空間に置き換えたものに常に解決されます。 現在の名前空間がグローバル名前空間だった場合、 namespace\ 名前空間は取り除かれます。 たとえば、名前空間 X\Y の中にある namespace\A は、 X\Y\A に解決されます。 グローバル名前空間の中にある同じ名前は、 A に解決されます。
  3. 修飾名の場合は、名前の最初の識別子を、 現在のクラス/名前空間のインポートテーブルに従って翻訳します。 たとえば、名前空間 A\B\C が C としてインポートされた場合、 C\D\E という名前は、 A\B\C\D\E と翻訳されます。
  4. 修飾名の場合で、適用すべきインポートルールがない場合、 現在の名前空間が名前の先頭に付加されます。 たとえば、名前空間 A\B の中にある C\D\E という名前は A\B\C\D\E に解決されます。
  5. 非修飾名の場合、名前はそれぞれのシンボルタイプの 現在のインポートテーブルに従って翻訳されます。 これは、クラスのような名前は、クラス/名前空間のインポートテーブルに従って 翻訳されるし、関数名は、関数のインポートテーブルに従うし、 定数は定数のインポートテーブルに従うということになります。 たとえば、use A\B\C; の後に、 new C() のようなことをすると、 C は A\B\C() に解決されます。 同じように、use function A\B\foo; の後に foo() のようなことをすると、 A\B\foo という名前に解決されます。
  6. 非修飾名について、適用すべきインポートルールが存在せず、 名前がクラスのようなシンボルを参照している場合、 現在の名前空間が先頭に付加されます。 たとえば、名前空間 A\B の内部にある new C() は、 A\B\C という名前に解決されます。
  7. 非修飾名について、適用すべきインポートルールが存在せず、 名前が関数や定数を参照しており、 コードがグローバル名前空間の外に存在する場合は 名前は実行時に解決されます。 コードが名前空間 A\B の中にあると仮定すると、 関数 foo() のコールは、次のように解決されます。
    1. まず現在の名前空間から関数 A\B\foo() を探します。
    2. 次に グローバル 関数 foo() を探します。

例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 を試みます

// 別の名前空間から使用するstaticメソッド/関数

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 を試みます

// 現在の名前空間から使用するstaticメソッド/関数

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, PHP 7, PHP 8)

この FAQ は 2 つに別れています。一般的な質問と、 深く理解するために有用な実装に関する質問です。

まずは一般的な質問。

  1. 名前空間を使わない場合、 何か注意すべきことはありますか?
  2. 名前空間内での内部クラスあるいはグローバルクラスの使用法は?
  3. 同じ名前空間にあるクラス、関数あるいは定数を使用する方法は?
  4. \my\name や \name のような名前はどのように解決される?
  5. my\name のような名前はどのように解決される?
  6. 修飾されていない name のようなクラス名はどのように解決される?
  7. 修飾されていない name のような関数名/定数名はどのように解決される?

また、名前空間の実装を理解するために有用な実装の詳細は次のとおりです。

  1. インポートした名前が同一ファイルで定義されているクラスと衝突してはいけない
  2. 名前空間のネストはできない
  3. 動的な名前空間名 (クォートした名前) ではバックスラッシュのエスケープが必要
  4. バックスラッシュを含む未定義な定数を参照すると、致命的なエラーが発生する
  5. 特別な定数 null, true, false は上書きできない

名前空間を使わない場合、何か注意すべきことはありますか?

いいえ。これまで書いてきたコード、今後書く名前空間を含まないコードのいずれについても、 名前空間が何らかの影響を及ぼすことはありません。 お望みなら名前空間を使わないコードを書くこともできます。

例1 名前空間の外部にあるグローバルクラスへのアクセス

<?php
$a = new \stdClass;
?>

これは、機能的に次と同等です。

例2 名前空間の外部にあるグローバルクラスへのアクセス

<?php
$a = new stdClass;
?>

名前空間内での内部クラスあるいはグローバルクラスの使用法は?

例3 名前空間内からの内部クラスへのアクセス

<?php
namespace foo;
$a = new \stdClass;

function test(\ArrayObject $parameter_type_example = null) {}

$a = \DirectoryIterator::CURRENT_AS_FILEINFO;

// 内部クラス/グローバルクラスの継承
class MyException extends \Exception {}
?>

同じ名前空間にあるクラス、関数あるいは定数を使用する方法は?

例4 名前空間内のクラス、関数あるいは定数へのアクセス

<?php
namespace foo;

class MyClass {}

// 現在の名前空間のクラスを引数の型として使う
function test(MyClass $parameter_type_example = null) {}
// 現在の名前空間のクラスを引数の型として使うもうひとつの方法
function test(\foo\MyClass $parameter_type_example = 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" のstaticメソッド "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" クラスのstaticメソッド "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); // グローバル関数 "sort" をコールします
$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 {}
}
?>

動的な名前空間名 (クォートした名前) ではバックスラッシュのエスケープが必要

バックスラッシュは文字列のエスケープ文字として使われることに注意しましょう。 文字列の中で使う際にはバックスラッシュを二重に書く必要があります。 そうしないと、予期せぬ結果を引き起こしてしまいます。

例9 ダブルクォートで囲んだ文字列内で名前空間名を扱う際の危険

<?php
$a = "dangerous\name"; // ダブルクォートの中では \n が改行文字になってしまいます!
$obj = new $a;

$a = '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 は上書きできない

名前空間内で特別な組み込み定数を定義しようとすると、致命的なエラーが発生します。

例11 未定義の定数

<?php
namespace bar;
const NULL = 0; // 致命的なエラー
const true = 'stupid'; // これも、致命的なエラー
// etc.
?>


列挙型(Enum)

目次

  • 列挙型の概要
  • 列挙型の基礎
  • 値に依存した列挙型(Backed Enum)
  • 列挙型とメソッド
  • 列挙型と static メソッド
  • 列挙型と定数
  • トレイト
  • 定数式における列挙型の値
  • オブジェクトとの違い
  • 値のリスト
  • 列挙型をシリアライズする
  • 列挙型が継承できない理由
  • 例


列挙型の概要

(PHP 8 >= 8.1.0)

列挙型(Enumerations) または Enum を使うと、 開発者は取りうる値を限定した独自の型を定義できます。 これによって、"不正な状態を表現できなくなる" ので、 ドメインモデルを定義する時に特に役立ちます。

列挙型は、多くのプログラミング言語に備わっており、 様々な異なる機能があります。 PHP では、列挙型は特別な種類のオブジェクトです。 列挙型そのものはクラスですし、そこで定義される case は全て、 そのクラスのインスタンスです。 これは、列挙型で定義される case は有効なオブジェクトであり、 型チェックを含む、オブジェクトが使えるあらゆる場所で使えるということです。

列挙型のもっとも有名な例は、組み込みの論理型(boolean) です。 これは、有効な値 true と false を持つ列挙型です。 列挙型によって、開発者は任意の値の一覧を、 安定した形で定義できるようになります。


列挙型の基礎

列挙型はクラスに似ていますし、 クラスやインターフェイス、トレイトと名前空間を共有します。 列挙型はオートローディングも可能です。 列挙型は新しい型を定義しますが、 固定の、限られた数の有効な値を持ちます。

<?php

enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}
?>

上記の宣言によって、新しい列挙型 Suit が作られますが、 これが持つ有効な値は4つだけです。 Suit::Hearts、Suit::Diamonds、Suit::Clubs、そして Suit::Spades です。 これらの有効な値のうち、ひとつだけを変数に代入できます。 関数は列挙型に対する型チェックを行えますし、 その場合は列挙型の値だけが渡せます。

<?php

function pick_a_card(Suit $suit)
{
/* ... */
}

$val = Suit::Diamonds;

// OK
pick_a_card($val);

// OK
pick_a_card(Suit::Clubs);

// TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
pick_a_card('Spades');
?>

列挙型は、0個以上の case を定義できます。 case を定義する数に上限はありません。 case が0個の列挙型も文法的には有効ですが、役に立ちません。

列挙型の case は、PHP のラベルと同じ規則に従います。 定数 のページを参照ください。

デフォルトでは、case は本質的にスカラーの値に依存していません。 つまり、Suit::Hearts は "0" に等しくないということです。 むしろ、それぞれの case はその名前が付いたシングルトンオブジェクトです。 以下のコードがそれを示しています:

<?php

$a = Suit::Spades;
$b = Suit::Spades;

$a === $b; // true

$a instanceof Suit; // true
?>

このことは、列挙型の値は決して < や > で比較できないことも意味しています。 なぜなら、それらの比較をオブジェクトで行っても無意味だからです。 列挙型の値を使ってこれらの比較を行っても、常に false を返します。

関連するデータのない、こうしたタイプの case を、 "Pure Case" と呼びます。 Pure Case のみを含む列挙型を、"Pure Enum" と呼びます。

全ての Pure Case は、その列挙型のインスタンスとして実装されています。 列挙型は内部的にクラスとして表現されます。

全ての case は読み取り専用のプロパティ name を持ちます。 これは大文字小文字が区別される、case そのものの名前です。

<?php

print Suit::Spades->name;
// "Spades" と表示
?>

列挙型の名前を動的に取得している場合、 case の存在を確認したり、読み取る用途として defined() や constant() 関数が使えます。 しかしながら、これらの関数の利用はおすすめできません。 なぜなら、 Backed Enum で大半の用途を満たせるはずだからです。


値に依存した列挙型(Backed Enum)

デフォルトでは、列挙型はスカラー値の情報を持っていません。 単なるシングルトンオブジェクトです。 しかし、列挙型の case をデータベースや、 類似のデータストアで読み書きする必要があるケースが多くあります。 よって、ビルトインの (シリアライズ可能であることが自明な) スカラー値を持つ case があると、本質的に役に立ちます。

列挙型にスカラー値を定義するには、以下のようにします:

<?php

enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}
?>

スカラー値を持つ case を、"Backed Case" と呼びます。 なぜなら、オブジェクトよりもシンプルな値に依存して(Backed)いるからです。 全ての case が Backed Case である列挙型を "Backed Enum" と呼びます。 Backed Enum には Backed Case のみを含めることができます。 Pure Enum には Pure Case だけを含めることができます。

Backed Enum は、整数、または文字列の値を持つことができます。 そして、単一の列挙型が一度に持つことの出来る型はひとつだけです (つまり、int|string のような union 型はサポートしていないということです)。 列挙型がスカラー情報を持つとマークすると、 全ての case はユニークなスカラーの値を明示的に定義しなければいけません。 自動生成されるスカラー値 (例: 整数の連番) は存在しません。 Backed Enum の case の値は、全てユニークでなければいけません。 つまり、ふたつの Backed Enum の case は、 同じスカラー値を持ってはいけないということです。 しかし、定数は case を参照していても構わないので、 別名を作成することはできます。 列挙型と定数 も参照ください。

スカラー値は、リテラルか、リテラルを表す式でなければいけません。 定数や定数式はサポートしていません。 つまり、1 + 1 は許されますが、 1 + SOME_CONST は許されません。

Backed Enum の case は、追加の読み取り専用のプロパティ value を持っています。 これは、Backed Enum の定義で指定された値です。

<?php

print Suit::Clubs->value;
// "C" と表示
?>

value プロパティを強制的に読み取り専用にするため、 そのリファレンスを変数には代入できません。 つまり、以下のようなコードはエラーになります:

<?php

$suit = Suit::Clubs;
$ref = &$suit->value;
// Error: Cannot acquire reference to property Suit::$value
?>

Backed Enum は内部的に BackedEnum インターフェイスを実装しています。 このメソッドは、以下の2つのメソッドを公開しています:

  • from(int|string): self スカラー値を受け取り、対応する Enum の case を返します。 対応する case がない場合は、 ValueError がスローされます。 このメソッドは、入力のスカラー値が信頼でき、 存在しない enum の値はアプリケーションを停止すべきエラーとみなせる場合に役立ちます。
  • tryFrom(int|string): ?self スカラー値を受け取り、対応する Enum の case を返します。 対応する case がない場合は、null を返します。 このメソッドは、入力のスカラー値が信頼できない場合で、 呼び出し側が独自のエラーハンドリングや、 デフォルト値のロジックを実装したい場合に役立ちます。

from() と tryFrom() メソッドは、標準の 弱い/強い 型付けのルールに従います。 弱い型付けのルールでは、整数または文字列を受け入れ、 システムは値をそれに従って自動変換します。 厳密な型付けモードの場合、文字列型の Backed Enum に整数値を渡す (またはその逆をする) と、TypeError が発生します。 float についても、全ての場合に同じ型付けのルールに従います。 それ以外の型については、どちらのモードでも TypeError が発生します。

<?php

$record = get_stuff_from_database($id);
print $record['suit'];

$suit = Suit::from($record['suit']);
// 不正なデータを渡すと、次のようなエラーが発生 -> ValueError: "X" is not a valid scalar value for enum "Suit"
print $suit->value;

$suit = Suit::tryFrom('A') ?? Suit::Spades;
// 不正なデータに対しては null を返すので、Suit::Spades が代わりに使われます。
print $suit->value;
?>

Backed Enum において、手動で from() や tryFrom() メソッドを定義すると、 致命的なエラーが発生します。


列挙型とメソッド

列挙型では、(Pure Enum と Backed Enum ともに) メソッドを含めることもできますし、 インターフェイスを実装することもできます。 列挙型がインターフェイスを実装する場合、 そのインターフェイスでの型チェックは、 実装した列挙型の全ての case で有効です。

<?php

interface Colorful
{
public function color(): string;
}

enum Suit implements Colorful
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;

// インターフェイスの規約を満たすための実装
public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}

// インターフェイスの一部ではないが、正しいコード
public function shape(): string
{
return "Rectangle";
}
}

function paint(Colorful $c)
{
/* ... */
}

paint(Suit::Clubs); // 動作します

print Suit::Diamonds->shape(); // "Rectangle" と表示
?>

上記の例の Suit の4つのインスタンスは、 全てふたつのメソッド color() と shape() を持ちます。 コードの呼び出しと型チェックに限れば、 これらのメソッドは他のオブジェクトのインスタンスと全く同じ振る舞いをします。

Backed Enum の場合、 インターフェイスの宣言は依存する型の宣言の直後に置きます。

<?php

interface Colorful
{
public function color(): string;
}

enum Suit: string implements Colorful
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';

// インターフェイスの規約を満たすための実装
public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}
}
?>

メソッドの内部では、 変数 $this が定義され、 case のインスタンスを参照します。

メソッドには任意の複雑な処理を記述できますが、 実際、通常は静的な値を返したり、 case 毎に異なる結果を提供するために match を $this と共に使う処理を行います。

この場合は、Red と Black の値を持ち、 それらを返す SuitColor という列挙型を定義する方が、 より良いデータモデリングのプラクティスであることにも注意して下さい。 しかし、そうすると上の例が複雑になるでしょう。

上で示した階層は、論理的には次のようなクラス階層に似ています (しかし、以下のコードは実際には動作しません):

<?php

interface Colorful
{
public function color(): string;
}

final class Suit implements UnitEnum, Colorful
{
public const Hearts = new self('Hearts');
public const Diamonds = new self('Diamonds');
public const Clubs = new self('Clubs');
public const Spades = new self('Spades');

private function __construct(public readonly string $name) {}

public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}

public function shape(): string
{
return "Rectangle";
}

public static function cases(): array
{
// 不正なメソッド。列挙型では、手動で cases() メソッドを定義できないからです。
// "値のリスト" のページも参照ください。
}
}
?>

メソッドには public, private, protected が指定できますが、 列挙型では実際 private と protected は同じものです。 なぜなら、継承が許されていないからです。


列挙型と static メソッド

列挙型は、static メソッドを持つこともできます。 列挙型で static メソッドを使う主な理由は、 コンストラクタの代わりをさせるためです。たとえば、以下のようなものです:

<?php

enum Size
{
case Small;
case Medium;
case Large;

public static function fromLength(int $cm): static
{
return match(true) {
$cm < 50 => static::Small,
$cm < 100 => static::Medium,
default => static::Large,
};
}
}
?>

static メソッドには public, private, protected が指定できますが、 列挙型では実際 private と protected は同じものです。 なぜなら、継承が許されていないからです。


列挙型と定数

列挙型には定数も含めることができます。 定数には public, private, protected が指定できますが、 列挙型では実際 private と protected は同じものです。 なぜなら、継承が許されていないからです。

列挙型の定数は、以下のように case を参照していても構いません:

<?php

enum Size
{
case Small;
case Medium;
case Large;

public const Huge = self::Large;
}
?>


トレイト

列挙型ではトレイトを使えます。 列挙型におけるトレイトは、クラスにおけるそれと同じ振る舞いをします。 注意すべきことは、列挙型で use されるトレイトには、プロパティが含まれていてはいけないという点です。 use されるトレイトには、 メソッドと static メソッドだけを含めることができます。 プロパティを持つトレイトの場合、致命的なエラーが発生します。

<?php

interface Colorful
{
public function color(): string;
}

trait Rectangle
{
public function shape(): string {
return "Rectangle";
}
}

enum Suit implements Colorful
{
use Rectangle;

case Hearts;
case Diamonds;
case Clubs;
case Spades;

public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}
}
?>


定数式における列挙型の値

列挙型の case は、定数として表現されているので、 ほとんどの定数式の中で静的な値として使えます。 つまり、プロパティのデフォルト値や、 static 変数のデフォルト値、引数のデフォルト値、 グローバル定数やクラス定数の値として使えます。 列挙型の case 以外の値は使えませんが、 通常の定数は、列挙型の case を参照できます。

しかしながら、列挙型の中で ArrayAccess のような暗黙のマジックメソッドの呼び出しを行うことは、 定数や static な定義では許されません。 なぜなら、結果の値が保証できなくなりますし、 副作用がまったくないことも保証できないからです。 関数コールやメソッドコール、そしてプロパティへのアクセスは、 引き続き定数式では不正な操作として扱われます。

<?php

// これは、完全に正しい列挙型の定義です
enum Direction implements ArrayAccess
{
case Up;
case Down;

public function offsetExists($offset): bool
{
return false;
}

public function offsetGet($offset): mixed
{
return null;
}

public function offsetSet($offset, $value): void
{
throw new Exception();
}

public function offsetUnset($offset): void
{
throw new Exception();
}
}

class Foo
{
// これは、許されています。
const DOWN = Direction::Down;

// これは、許可されません。結果の値が保証できない可能性があります。
const UP = Direction::Up['short'];
// Fatal error: Cannot use [] on enums in constant expression
}

// これは、完全に正しいコードです。定数式ではないからです。
var_dump("\$x is " . var_export($x, true));

$foo = new Foo();
?>


オブジェクトとの違い

列挙型はクラスやオブジェクトの上に構築されていますが、 オブジェクトに関連する機能を全てサポートしているわけではありません。 特に、列挙型では状態を持つことが禁止されています。

  • コンストラクタやデストラクタは禁止されています。
  • 継承はサポートされていません。列挙型は継承できませんし、何かを継承されることもありません。
  • staticまたはオブジェクトのプロパティは許可されていません。
  • 列挙型の case を clone することはサポートされていません。なぜなら、case はシングルトンインスタンスでなければならないからです。
  • 以下に示すもの以外の マジックメソッド は許可されていません。
  • 列挙型は、常に使う前に宣言しておかなければなりません。

以下のオブジェクトの機能は利用可能ですし、 他のオブジェクトと同じ振る舞いをします:

  • public, private, protected メソッド
  • public, private, protected な static メソッド
  • public, private, protected な定数
  • 列挙型は、任意の数のインターフェイスを実装できます。
  • 列挙型と case には、 アトリビュート を付加することができます。 TARGET_CLASS ターゲットフィルタには、 列挙型そのものも含まれます。 TARGET_CLASS_CONST ターゲットフィルタには、 列挙型の case も含まれます。
  • マジックメソッド __call, __callStatic, __invoke
  • マジック定数 __CLASS__ と __FUNCTION__ は、通常通り動作します。

マジック定数 ::class を列挙型で使うと、 任意の名前空間を含んだ型の名前として評価されます。 これはオブジェクトと全く同じです。 case インスタンスにおける ::class も、 列挙型として評価されます。これは、その型のインスタンスの場合と同じです。

さらに、列挙型の case は new を使って直接インスタンス化できませんし、 ReflectionClass::newInstanceWithoutConstructor() を使っても同様です。 これらは両方、エラーになります。

<?php

$clovers = new Suit();
// Error: Cannot instantiate enum Suit

$horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
// Error: Cannot instantiate enum Suit
?>


値のリスト

Pure Enum と Backed Enum は、 共に内部インターフェイス UnitEnum を実装しています。 UnitEnum には static メソッド cases() が含まれています。 cases() は、 定義されている全ての case を宣言された順に含めた配列を返します。

<?php

Suit::cases();
// [Suit::Hearts, Suit::Diamonds, Suit::Clubs, Suit::Spades] を生成
?>

列挙型において、手動で cases() メソッドを定義すると、致命的なエラーが発生します。


列挙型をシリアライズする

列挙型は、オブジェクトとは違う形でシリアライズされます。 特別に、列挙型には case 名を指定する新しいシリアライズコード "E" が付与されています。 アンシリアライズのルーチンはそれを使って、 既存のシングルトンの値を変数に設定できます。 これにより、以下のようなコードが動作することが保証されます:

<?php

Suit::Hearts === unserialize(serialize(Suit::Hearts));

print serialize(Suit::Hearts);
// E:11:"Suit:Hearts";
?>

アンシリアライズする際に、 マッチする列挙型と case がシリアライズした値に見つからなかった場合は、 警告が発生し、false が返されます。

Pure Enum を JSON にシリアライズしようとすると、 Error がスローされます。 Backed Enum を JSON にシリアライズしようとすると、 適切な型の、スカラーの値だけが表現されます。 これらの振る舞いは、 JsonSerializable をオーバーライドすることで上書きできます。

print_r() 向けに、 列挙型の case の出力はオブジェクトと少し違う形式になっています。 これは、混乱を最小限に抑えるためです。

<?php

enum Foo {
case Bar;
}

enum Baz: int {
case Beep = 5;
}

print_r(Foo::Bar);
print_r(Baz::Beep);

/* 上記は、以下を出力

Foo Enum (
[name] => Bar
)
Baz Enum:int {
[name] => Beep
[value] => 5
}
*/
?>


列挙型が継承できない理由

クラスは、メソッドの使い方を約束(契約)するものです:

<?php

class A {}
class B extends A {}

function foo(A $a) {}

function bar(B $b) {
foo($b);
}
?>

上のコードは型安全といえます。なぜなら、 B は A との契約を守っており、かつ共変性/反変性のマジックによって、 メソッドへのあらゆる期待が満たされるからです。例外は別です。

一方で、列挙型は case について契約するものです。メソッドではありません:

<?php

enum ErrorCode {
case SOMETHING_BROKE;
}

function quux(ErrorCode $errorCode)
{
// 以下のようなコードを書くと、全ての case をカバーします
match ($errorCode) {
ErrorCode::SOMETHING_BROKE => true,
}
}

?>

quux 関数内の match 式は、 ErrorCode の全ての case をカバーしているかを静的に解析できます。

ここで以下のように、列挙型が継承可能だとしましょう:

<?php

// 列挙型が final でなかったと仮定した、思考実験のコード
// このコードは実際には動作しないので注意
enum MoreErrorCode extends ErrorCode {
case PEBKAC;
}

function fot(MoreErrorCode $errorCode) {
quux($errorCode);
}

fot(MoreErrorCode::PEBKAC);

?>

通常の継承のルールでは、あるクラスの子クラスは親クラスの型チェックを通過します。

上のコードの問題点は、 quux() 関数の match 式が全ての case をカバーしてはいないということです。 なぜなら、MoreErrorCode::PEBKAC がカバーされていないので、match 式が例外をスローするからです。

こうした理由から、列挙型は final 扱いであり、継承できなくなっています。


例

例1 基本的な、値を限定する例

<?php

enum SortOrder
{
case Asc;
case Desc;
}

function query($fields, $filter, SortOrder $order = SortOrder::Asc)
{
/* ... */
}
?>

query() 関数は、 $order が SortOrder::Asc または SortOrder::Desc であることが保証されることを知っているので、安全に処理できます。 それら以外の値を渡しても、 TypeError になるので、それ以上のチェックやテストは不要です。

例2 唯一の値を指定する、高度な例

<?php

enum UserStatus: string
{
case Pending = 'P';
case Active = 'A';
case Suspended = 'S';
case CanceledByUser = 'C';

public function label(): string
{
return match($this) {
static::Pending => 'Pending',
static::Active => 'Active',
static::Suspended => 'Suspended',
static::CanceledByUser => 'Canceled by user',
};
}
}
?>

この例では、ユーザーのステータスは UserStatus::Pending、 UserStatus::Active、 UserStatus::Suspended または UserStatus::CanceledByUser のうちのひとつに限られています。 関数は引数の型を UserStatus に指定できますし、これら4つの値だけを受け入れます。

これら4つの値は、それぞれ label() メソッドを持ちます。 これは、人間が読みやすい文字列を返します。 この文字列は、"マシン上の" スカラー値とは別のものです。 このスカラー値は、データベースのフィールドや、 HTML の select ボックスで使うことができます。

<?php

foreach (UserStatus::cases() as $case) {
printf('<option value="%s">%s</option>\n', $case->value, $case->label());
}
?>


エラー

目次

  • 基本
  • PHP 7 でのエラー

はじめに

残念ながら、どんなに気をつけてコードを書いたところで、 エラーをなくすことはできません。 PHP は、コーディングや実行時に発生する問題を、 エラー (error) や警告 (warning) そして注意 (notice) などの形式で報告します。 これらの報告を検出して処理する方法を知っておけば、 デバッグがずっと楽になることでしょう。


基本

PHP は、各種のエラー条件に対応したさまざまなエラーを報告します。 これらを使えばさまざまな状況を伝えられるでしょうし、 必要に応じて画面に表示したりログに記録したりすることもできます。

PHP が発するあらゆるエラーには、型情報が含まれます。 エラーに関する定数の一覧 を参照ください。 それぞれについての簡単な説明と、どのような原因で発生するのかについても説明があります。

PHP におけるエラー処理

何もエラーハンドラを設定しなければ、PHP は、 発生したあらゆるエラーを設定にあわせて処理します。 どのエラーを報告してどのエラーを無視するのかを決めるのが、php.ini の error_reporting です。あるいは、実行時に error_reporting() を呼んで設定することもできます。 しかし、できるだけ php.ini で設定しておくことをお勧めします。 というのも、スクリプトの実行が始まるまえにエラーが発生することもありえるからです。

開発中は常に、 error_reporting を E_ALL にしておくべきです。 PHP が発する報告をすべて確認して対応する必要があるからです。 実際の運用に入ったら、もう少しレベルを下げて E_ALL & ~E_NOTICE & ~E_DEPRECATED などのようにすることもあるでしょう。しかし、できれば運用中も E_ALL にしておきたいものです。 そうすれば、何かの問題が発生しそうなときに早い段階で気づけるからです。

エラーが発生したときの PHP の挙動を決める php.ini 設定項目が、あと二つあります。 ひとつは display_errors で、これは、エラーの内容をスクリプトの出力に含めるかどうかを設定します。 この項目は、運用時には常に無効にしておくべきです。 エラーメッセージの中には、データベースのパスワードなどの機密情報が含まれることもありえるからです。 しかし、開発中は有効にしておくほうが便利です。 どこに問題があるのかに、すぐに気づけるからです。

もうひとつの項目が log_errors で、これを有効にしておくと、PHP はエラーをログに記録します。 発生したすべてのエラーが、 error_log で定義した場所 (ファイルや syslog など) に書き出されます。 これは、運用環境で特に役立ちます。 発生したエラーを記録しておけば、後でそれを使ってレポートを生成できるからです。

ユーザー定義のエラーハンドラ

PHP のデフォルトのエラー処理では不十分な場合は、 自作のエラーハンドラを用意して、それを set_error_handler() で設定することもできます。 中にはこの方式では処理できない型のエラーもありますが、 処理できる型のエラーについてはこの方法が便利です。 たとえば、ユーザー向けにはカスタムエラーページを表示して、 内部的にはログに書き出すかわりにメールを送るなどとすることもできます。


PHP 7 でのエラー

PHP 7 は大半のエラーがどのようにPHPから報告されるかを変更しています。 PHP 5 で使われていたこれまでのエラー報告メカニズムを使うかわりに、 大半のエラーを Error 例外としてスローするようになったのです。

通常の例外と同様、Error 例外も、 最初にマッチした catch ブロックで現れます。 マッチするブロックがなければ、set_exception_handler() で設定したデフォルトの例外ハンドラが呼ばれます。 デフォルトの例外ハンドラもない場合は、例外が fatal error に変換されて、 これまでのバージョンのエラーと同じように扱われます。

Error クラスは Exception を継承していないので、 キャッチし損ねた例外を catch (Exception $e) { ... } ブロックで受け止めているような PHP 5 のコードでは、 Error をキャッチできません。 catch (Error $e) { ... } ブロックを用意するか、あるいは set_exception_handler() でハンドラを設定する必要があります。

Error の階層

  • Throwable
    • Error
      • ArithmeticError
        • DivisionByZeroError
      • AssertionError
      • CompileError
        • ParseError
      • TypeError
        • ArgumentCountError
      • ValueError
      • UnhandledMatchError
      • FiberError
    • Exception
      • ...


例外(exceptions)

目次

  • 例外を拡張する

PHP は、他のプログラミング言語に似た例外モデルを持っています。 PHP 内で例外がスローされ (throw され)、それが 捕捉され (catch され) ます。発生した例外を 捕捉するには、コードを try ブロックで囲みます。 各 try ブロックには、対応する catch ブロックあるいは finally ブロックが存在する必要があります。

例外がスローされ、現在の関数スコープに catch ブロックがなかった場合、 その例外は、マッチする catch ブロックが見つかるまで関数のコールスタックを "遡って" いきます。 その途中で見つかった全ての finally ブロックが実行されます。 グローバルスコープに遡るまで全てのコールスタックを探しても、 マッチする catch ブロックが見つからない場合は、 グローバルな例外ハンドラが設定されていない限り fatal error となり、 プログラムが終了します。

スローされるオブジェクトは、 Throwable のインスタンスでなければなりません。 それ以外のオブジェクトをスローしようとすると PHP の fatal error が発生します。

PHP 8.0.0 以降では、throw キーワードは式として扱えるようになり、 様々なコンテクストで使えるようになりました。 これより前のバージョンでは、throw は文であり、 それが現れる行でだけでしか使えませんでした。

catch

catch ブロックは、スローされた例外にどのように反応するかを定義します。 catch ブロックは、扱えるひとつ以上の例外またはエラー型を定義します。 そして、オプションで例外を代入できる変数も定義できます。 (PHP 8.0.0 より前のバージョンでは、この変数定義は必須でした) スローされた例外またはエラーにマッチする最初の catch ブロックが、そのオブジェクトを処理します。

さまざまな型の例外を捕捉するために 複数の catch ブロックを使用することができます。 通常の実行時 (try ブロック内で例外がスローされなかった 場合) は、catch ブロック内は処理されず、それ以降から処理が続けられます。 catch ブロックの中から例外を throw する (あるいは throw しなおす) こともできます。 throw し直さない場合、その catch ブロックの後から処理が続けられます。

例外がスローされた場合、その命令に続くコードは実行されず、 PHP は最初にマッチする catch ブロックを探します。 例外が捕捉されない場合、PHP は "Uncaught Exception ..." というメッセージとともに 致命的なエラー(fatal error)を発生させます。 ただし、set_exception_handler() でハンドラが 定義されている場合を除きます。

PHP 7.1.0 以降では、catch ブロック で 複数の例外を パイプ文字 (|) を使って指定できるようになりました。 これは、異なるクラス階層からの例外を同時に扱う必要がある場合に有用です。

PHP 8.0.0 以降では、キャッチされた例外に対応する変数はオプションになりました。 指定されない場合、catch ブロックは実行されるものの、 スローされたオブジェクトへアクセスすることは出来ません。

finally

catch ブロックの後、または catch ブロックの代わりに、 finally ブロックも指定できます。 finally ブロックの中に書いたコードは、 try および catch ブロックの後で、 かつ通常のコードの実行が再開される前に常に実行されます。 例外がスローされたかどうかは関係ありません。

finally ブロックと return 文の間には注意すべき相互作用があります。 return 文が try や catch ブロックの内部に存在した場合でも、 finally ブロックは実行されます。 さらに、return 文は出現した時に評価されますが、 結果は finally ブロックが実行された後に返されます。 さらに、finally ブロックにも return 文が存在した場合は、 finally ブロックから値が返されます。

グローバルな例外ハンドラ

例外がグローバルスコープにまで遡った場合、 設定されていれば、グローバルな例外ハンドラがそれをキャッチすることができます。 他の catch ブロックが呼び出されなかった場合に、 catch の代わりに呼び出される関数を set_exception_handler() 関数で設定できます。 その効果は、プログラム全体を try-catch ブロックで囲むことと同じです。

注意

注意:

PHP の内部関数の多くは エラー報告(error_reporting) を使っており、例外を使っているのは新しい オブジェクト指向 の拡張モジュールのみです。 しかし、ErrorException を使えば簡単にエラーを例外に変換することができます。 この変換テクニックが使えるのは、致命的でないエラーに限ります。

例1 エラーを例外に変換する

<?php
function exceptions_error_handler($severity, $message, $filename, $lineno) {
throw new ErrorException($message, 0, $severity, $filename, $lineno);
}

set_error_handler('exceptions_error_handler');
?>

ヒント

Standard PHP Library (SPL) には 組み込みの例外 が数多く用意されています。

例

例2 例外をスローする

<?php
function inverse($x) {
if (!$x) {
throw new Exception('ゼロによる除算。');
}
return 1/$x;
}

try {
echo inverse(5) . "\n";
echo inverse(0) . "\n";
} catch (Exception $e) {
echo '捕捉した例外: ', $e->getMessage(), "\n";
}

// 実行は継続される
echo "Hello World\n";
?>

上の例の出力は以下となります。

0.2
捕捉した例外: ゼロによる除算。
Hello World

例3 例外処理での finally ブロック

<?php
function inverse($x) {
if (!$x) {
throw new Exception('ゼロによる除算。');
}
return 1/$x;
}

try {
echo inverse(5) . "\n";
} catch (Exception $e) {
echo '捕捉した例外: ', $e->getMessage(), "\n";
} finally {
echo "First finally.\n";
}

try {
echo inverse(0) . "\n";
} catch (Exception $e) {
echo '捕捉した例外: ', $e->getMessage(), "\n";
} finally {
echo "Second finally.\n";
}

// 実行は継続される
echo "Hello World\n";
?>

上の例の出力は以下となります。

0.2
First finally.
捕捉した例外: ゼロによる除算。
Second finally.
Hello World

例4 finally ブロックと return の相互作用

<?php

function test() {
try {
throw new Exception('foo');
} catch (Exception $e) {
return 'catch';
} finally {
return 'finally';
}
}

echo test();
?>

上の例の出力は以下となります。

finally

例5 ネストした例外

<?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!"

例6 複数の例外ハンドリングをひとつの catch で行う

<?php

class MyException extends Exception { }

class MyOtherException extends Exception { }

class Test {
public function testing() {
try {
throw new MyException();
} catch (MyException | MyOtherException $e) {
var_dump(get_class($e));
}
}
}

$foo = new Test;
$foo->testing();

?>

上の例の出力は以下となります。

string(11) "MyException"

例7 キャッチする時に変数を省略する

PHP 8.0.0 以降でのみ許されます

<?php

function test() {
throw new SpecificException('Oopsie');
}

try {
test();
} catch (SpecificException) {
print "A SpecificException was thrown, but we don't care about the details.";
}
?>

例8 throw を 式として扱う

PHP 8.0.0 以降でのみ許されます

<?php

class SpecificException extends Exception {}

function test() {
do_something_risky() or throw new Exception('It did not work');
}

try {
test();
} catch (Exception $e) {
print $e->getMessage();
}
?>


例外を拡張する

組み込みの Exception クラスを拡張することで、例外クラスをユーザーが 定義することが可能です。以下のメンバーおよびプロパティは、 組み込みの Exception クラスから派生した子クラスの中でアクセス可能です。

例1 組み込みの例外クラス

<?php
class Exception implements Throwable
{
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 = '', $code = 0, Throwable $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
/**
* カスタム例外クラスを定義する
*/
class MyException extends Exception
{
// 例外を再定義し、メッセージをオプションではなくする
public function __construct($message, $code = 0, Throwable $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) { // ここでキャッチされる
echo "Caught my exception\n", $e;
$e->customFunction();
} catch (Exception $e) { // ここはスキップされる
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 8 >= 8.1.0)

ファイバー(Fibers) は、完全なスタックを持つ、停止可能な関数です。 ファイバー はコールスタック中のどこからでも停止することができますし、 後に再開されるまで実行を停止したままにできます。

ファイバーは実行スタック全体を停止するので、 関数を直接呼び出している側は、関数の呼び出し方を変更する必要はありません。

実行スタック中のどこからでも、 Fiber::suspend() を使って実行を停止できます。 (つまり、Fiber::suspend() の呼び出しは、 深くネストされた関数のコールスタックの中から行っても構いませんし、 呼び出しが全く存在しなくても構いません)

スタックを持たない Generator と異なり、 個々の Fiber は自分のコールスタックを持ちます。 これによって、深くネストされた関数のコールスタックの中からでも 関数を停止できます。 停止ポイントを宣言した (つまり、Fiber::suspend() を呼び出した) 関数は、 yield を使った、Generator のインスタンスを返さなければならない関数と異なり、 戻り値の型を宣言する必要はありません。

ファイバーは任意の関数をコールしている間に停止できます。 これには、PHP VM の中からコールされた関数も含みます。 たとえば、array_map() に渡した関数や、 foreach によってコールされる、Iterator オブジェクトのメソッドなどです。

いったんファイバーが停止されると、 ファイバーの実行は Fiber::resume() に任意の値を渡すか、 Fiber::throw() を使ってファイバーに例外をスローさせることで再開できます。 再開される時は、Fiber::suspend() から値が返されます(または、例外がスローされます)。

注意: 現状の制限により、 ファイバーをオブジェクトのデストラクタ中で切り替えることはできません。

例1 ファイバーの基本的な使い方

<?php
$fiber = new Fiber(function (): void {
$value = Fiber::suspend('fiber');
echo "Value used to resume fiber: ", $value, PHP_EOL;
});

$value = $fiber->start();

echo "Value from fiber suspending: ", $value, PHP_EOL;

$fiber->resume('test');
?>

上の例の出力は以下となります。

Value from fiber suspending: fiber
Value used to resume fiber: test


ジェネレータ

目次

  • ジェネレータとは
  • ジェネレータの構文
  • ジェネレータと Iterator オブジェクトとの比較

参考

  • オブジェクトの反復処理


ジェネレータとは

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

ジェネレータを使えば、シンプルな イテレータを簡単に実装できます。 Iterator インターフェイスを実装したクラスを用意する オーバーヘッドや複雑さを心配する必要はありません。

ジェネレータを使うと、foreach でデータ群を順に処理するコードを書くときに メモリ内で配列を組み立てなくても済むようになります。 メモリ内で配列を組み立てると memory_limit を越えてしまうかもしれないし、 無視できないほどの時間がかかってしまうかもしれません。 配列を作る代わりに、ジェネレータ関数を書くことになります。これは通常の 関数と同じものですが、 ジェネレータ関数は一度だけ return するのではなく、必要に応じて何度でも yield することができます。 つまり、値を繰り返し返せるということです。

シンプルな例として、range() 関数をジェネレータで実装しなおしてみましょう。 標準の range() 関数は、すべての値を含む配列を作ってそれを返します。 結果的に、かなり大きな配列になる可能性があります。たとえば range(0, 1000000) を実行すると、 100 MB を超えるメモリを使うことになります。

その代替として、ジェネレータ xrange() を実装します。 必要なメモリは、Iterator オブジェクトを作ってジェネレータの内部の状態を記録しておくのに必要なものだけになります。 1 KB 未満で収まるでしょう。

例1 ジェネレータを使った range() の実装

<?php
function xrange($start, $limit, $step = 1) {
if ($start <= $limit) {
if ($step <= 0) {
throw new LogicException('Step must be positive');
}

for ($i = $start; $i <= $limit; $i += $step) {
yield $i;
}
} else {
if ($step >= 0) {
throw new LogicException('Step must be negative');
}

for ($i = $start; $i >= $limit; $i += $step) {
yield $i;
}
}
}

/*
* 次の例で、range() と xrange() が同じ結果を返すことに注目しましょう
*/

echo 'Single digit odd numbers from range(): ';
foreach (range(1, 9, 2) as $number) {
echo "$number ";
}
echo "\n";

echo 'Single digit odd numbers from xrange(): ';
foreach (xrange(1, 9, 2) as $number) {
echo "$number ";
}
?>

上の例の出力は以下となります。

Single digit odd numbers from range():  1 3 5 7 9
Single digit odd numbers from xrange(): 1 3 5 7 9

Generator オブジェクト

ジェネレータ関数を呼んだときには、内部クラス Generator の新しいオブジェクトを返します。 このオブジェクトは Iterator インターフェイスを実装しており、 前進しかできないイテレータオブジェクトと同じように振る舞います。 そして、このオブジェクトが提供するメソッドを使えば、 値を送ったり戻したりなどしてジェネレータの状態を操作できます。


ジェネレータの構文

ジェネレータ関数の見た目はふつうの関数とほぼ同じです。違うのは、値を返すのではなく、 必要なだけ値を yield することです。 yield が含まれていれば、どんな関数でもジェネレータ関数です。

ジェネレータ関数が呼ばれると、反復処理が可能なオブジェクトを返します。 このオブジェクトを (foreach ループなどで) 反復させると、 値が必要になるたびに PHP がオブジェクトの反復メソッドを呼びます。 そして、ジェネレータが値を yield した時点の状態を保存しておき、 次に値が必要になったときにはそこから再開できるようにします。

yield できる値がなくなると、ジェネレータは単純に呼び出し元に制御を戻します。 呼び出し元のコードでは、配列の要素をすべて処理し終えた後のように、そのまま処理が続きます。

注意:

ジェネレータは値を返すことができます。返した値は Generator::getReturn() で取得することが出来ます。

yield キーワード

ジェネレータ関数の肝となるのが yield キーワードです。 最もシンプルな書きかたをすると、yield 文の見た目は return 文とほぼ同じになります。 ただ、return の場合はそこで関数の実行を終了して値を返すのに対して、 yield の場合はジェネレータを呼び出しているループに値を戻して ジェネレータ関数の実行を一時停止します。

例1 値を yield する単純な例

<?php
function gen_one_to_three() {
for ($i = 1; $i <= 3; $i++) {
// yield を繰り返す間、$i の値が維持されることに注目しましょう
yield $i;
}
}

$generator = gen_one_to_three();
foreach ($generator as $value) {
echo "$value\n";
}
?>

上の例の出力は以下となります。

1
2
3

注意:

内部的には整数の連番のキーが yield する値とペアになり、 配列と同じようになります。

値とキーの yield

PHP は、数値添字の配列だけでなく連想配列にも対応しています。ジェネレータも例外ではありません。 先ほどの例のように単なる値を yield するだけでなく、 値と同時にキーも yield することができます。

キーと値のペアを yield する構文は連想配列の定義とよく似ており、次のようになります。

例2 キー/値 のペアの yield

<?php
/*
* 入力は各フィールドをセミコロンで区切ったものです
* 最初のフィールドが ID となり、これをキーとして使います
*/

$input = <<<'EOF'
1;PHP;$が大好き
2;Python;インデントが大好き
3;Ruby;ブロックが大好き
EOF;

function input_parser($input) {
foreach (explode("\n", $input) as $line) {
$fields = explode(';', $line);
$id = array_shift($fields);

yield $id => $fields;
}
}

foreach (input_parser($input) as $id => $fields) {
echo "$id:\n";
echo " $fields[0]\n";
echo " $fields[1]\n";
}
?>

上の例の出力は以下となります。

1:
    PHP
    $が大好き
2:
    Python
    インデントが大好き
3:
    Ruby
    ブロックが大好き

null 値の yield

何も引数を渡さずに yield を呼ぶと、null 値を yield します。キーは自動的に割り振られます。

例3 null の yield

<?php
function gen_three_nulls() {
foreach (range(1, 3) as $i) {
yield;
}
}

var_dump(iterator_to_array(gen_three_nulls()));
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  NULL
  [1]=>
  NULL
  [2]=>
  NULL
}

参照による yield

ジェネレータ関数は、値を参照として yield することもできます。 関数の結果を参照で返す ときと同じように、関数名の前にアンパサンドを付けます。

例4 参照による値の yield

<?php
function &gen_reference() {
$value = 3;

while ($value > 0) {
yield $value;
}
}

/*
* $number をループ内で変更していることに注目しましょう。
* このジェネレータは参照を yield するので、
* gen_reference() 内の $value が変わります。
*/
foreach (gen_reference() as &$number) {
echo (--$number).'... ';
}
?>

上の例の出力は以下となります。

2... 1... 0...

yield from によるジェネレータの委譲

ジェネレーターを委譲することで、 別のジェネレータや Traversable オブジェクトあるいは配列から、 yield from キーワードを使って値を yield できます。 外側のジェネレータは、内側のジェネレータ (あるいはオブジェクトや配列) から受け取れるすべての値を yield し、 何も取得できなくなったら外側のジェネレータの処理を続行します。

ジェネレータに対して yield from を使った場合は、 yield from 式は内側のジェネレータが返す任意の値を返します。

警告

iterator_to_array() を用いた、配列への格納

yield from は配列のキーをリセットしません。 Traversable オブジェクトや array が返すキーを、そのまま利用します。つまり、別々の yield や yield from から取得した異なる値のキーが、重複することもありえます。 これを配列に格納すると、後からきた値がそれまでの値を上書きします。

iterator_to_array() を使う場合に問題になることがよくあります。 この関数はデフォルトで数値添字配列を返すので、予期せぬ結果を引き起こす可能性があります。 iterator_to_array() には二番目のパラメータ preserve_keys があり、これを false にすれば、Generator が返すキーを無視してすべての値を取得できます。

例5 yield from と iterator_to_array()

<?php
function inner() {
yield 1; // キー 0
yield 2; // キー 1
yield 3; // キー 2
}
function gen() {
yield 0; // キー 0
yield from inner(); // キー 0?2
yield 4; // キー 1
}
// 二番目のパラメータに false を指定すると、結果は array [0, 1, 2, 3, 4] となります
var_dump(iterator_to_array(gen()));
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(4)
  [2]=>
  int(3)
}

例6 yield from の基本的な使いかた

<?php
function count_to_ten() {
yield 1;
yield 2;
yield from [3, 4];
yield from new ArrayIterator([5, 6]);
yield from seven_eight();
yield 9;
yield 10;
}

function seven_eight() {
yield 7;
yield from eight();
}

function eight() {
yield 8;
}

foreach (count_to_ten() as $num) {
echo "$num ";
}
?>

上の例の出力は以下となります。

1 2 3 4 5 6 7 8 9 10

例7 yield from の返す値

<?php
function count_to_ten() {
yield 1;
yield 2;
yield from [3, 4];
yield from new ArrayIterator([5, 6]);
yield from seven_eight();
return yield from nine_ten();
}

function seven_eight() {
yield 7;
yield from eight();
}

function eight() {
yield 8;
}

function nine_ten() {
yield 9;
return 10;
}

$gen = count_to_ten();
foreach ($gen as $num) {
echo "$num ";
}
echo $gen->getReturn();
?>

上の例の出力は以下となります。

1 2 3 4 5 6 7 8 9 10


ジェネレータと Iterator オブジェクトとの比較

ジェネレータの最大のメリットは、シンプルに書けることです。 Iterator を実装するのに比べて、必要な決まり文句の数がかなり少なくなります。 また、ジェネレータを使ったコードのほうが、一般的に読みやすくなります。 たとえば、次の関数とクラスを比べてみましょう。これらはどちらも同じ働きをするものです。

<?php
function getLinesFromFile($fileName) {
if (!$fileHandle = fopen($fileName, 'r')) {
return;
}

while (false !== $line = fgets($fileHandle)) {
yield $line;
}

fclose($fileHandle);
}

// これを、下のクラスと比べてみると......

class LineIterator implements Iterator {
protected $fileHandle;

protected $line;
protected $i;

public function __construct($fileName) {
if (!$this->fileHandle = fopen($fileName, 'r')) {
throw new RuntimeException('Couldn\'t open file "' . $fileName . '"');
}
}

public function rewind() {
fseek($this->fileHandle, 0);
$this->line = fgets($this->fileHandle);
$this->i = 0;
}

public function valid() {
return false !== $this->line;
}

public function current() {
return $this->line;
}

public function key() {
return $this->i;
}

public function next() {
if (false !== $this->line) {
$this->line = fgets($this->fileHandle);
$this->i++;
}
}

public function __destruct() {
fclose($this->fileHandle);
}
}
?>

しかし、柔軟性を実現するために犠牲にしていることもあります。 ジェネレータは前方にしか進めないイテレータなので、いったん反復処理が始まれば巻き戻すことができません。 これはつまり、同じジェネレータを何度も使い回せないということです。 ジェネレータ関数を呼んでもう一度作り直す必要があります。


アトリビュート

目次

  • アトリビュートの概要
  • アトリビュートの文法
  • リフレクションAPI を使ってアトリビュートを読み取る
  • アトリビュートクラスを宣言する


アトリビュートの概要

(PHP 8)

アトリビュートを使うと、 コンピューターが解析できる構造化されたメタデータの情報を、 コードの宣言時に埋め込むことができます。 つまり、クラス、メソッド、関数、パラメータ、プロパティ、クラス定数にアトリビュートを指定することができます。 アトリビュートで定義されたメタデータは、 実行時に リフレクションAPI を使って調べることが出来ます。 よって、アトリビュートは、 コードに直接埋め込むことが出来る、 設定のための言語とみなすことができます。

アトリビュートを使うと、機能の抽象的な実装と、アプリケーションでの具体的な利用を分離できます。 この点でアトリビュートは、インターフェイスとその実装と比較できます。 インターフェイスとその実装はコードに関する情報ですが、 アトリビュートはコードの追加情報と設定に注釈を付けるものです。 インターフェイスはクラスによって実装できますが、 アトリビュートはメソッドや関数、パラメータ、プロパティ、クラス定数で宣言できます。 よって、アトリビュートはインターフェイスより柔軟です。

アトリビュートの使い方の簡単な例として、 必須でないメソッドを持つインターフェイスを、 アトリビュートを使うように変換するコードを示します。 アプリケーションの操作を表現する ActionHandler があるとします。 この ActionHandler の実装は、セットアップが必須なものもありますが、 そうでないものもあります。 ActionHandler を実装する全てのクラスで setUp() メソッドを必須とする代わりに、 アトリビュートを使うようにしてみましょう。 このアプローチの利点のひとつは、 アトリビュートを複数回使えることです。

例1 アトリビュートを使い、インターフェイスのオプションのメソッドを実装する

<?php
interface ActionHandler
{
public function execute();
}

#[Attribute]
class SetUp {}

class CopyFile implements ActionHandler
{
public string $fileName;
public string $targetDirectory;

#[SetUp]
public function fileExists()
{
if (!file_exists($this->fileName)) {
throw new RuntimeException("File does not exist");
}
}

#[SetUp]
public function targetDirectoryExists()
{
if (!file_exists($this->targetDirectory)) {
mkdir($this->targetDirectory);
} elseif (!is_dir($this->targetDirectory)) {
throw new RuntimeException("Target directory $this->targetDirectory is not a directory");
}
}

public function execute()
{
copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
}
}

function executeAction(ActionHandler $actionHandler)
{
$reflection = new ReflectionObject($actionHandler);

foreach ($reflection->getMethods() as $method) {
$attributes = $method->getAttributes(SetUp::class);

if (count($attributes) > 0) {
$methodName = $method->getName();

$actionHandler->$methodName();
}
}

$actionHandler->execute();
}

$copyAction = new CopyFile();
$copyAction->fileName = "/tmp/foo.jpg";
$copyAction->targetDirectory = "/home/user";

executeAction($copyAction);


アトリビュートの文法

アトリビュートの文法は、複数の部分からなります。 まず最初に、アトリビュートの宣言は常に #[ で始まり、 それに対応する ] で囲みます。 その内部では、ひとつ以上のアトリビュートが並び、それぞれをカンマで区切ります。 アトリビュートの名前は、 名前空間の基礎 で説明している 非修飾名、修飾名、完全修飾名が指定できます。 アトリビュートの引数はオプションですが、 括弧 () で囲みます。 アトリビュートの引数はリテラル値か、定数式のみが指定できます。 位置を指定した引数と、名前付き引数の両方が使えます。

アトリビュートの名前と引数は、 アトリビュートのインスタンスがリフレクションAPIから要求された際、 クラスとそのコンストラクタに渡す引数として解決されます。 よって、それぞれのアトリビュート毎にクラスが存在するはずです。

例1 アトリビュートの文法

<?php
// a.php
namespace MyExample;

use Attribute;

#[Attribute]
class MyAttribute
{
const VALUE = 'value';

private $value;

public function __construct($value = null)
{
$this->value = $value;
}
}

// b.php

namespace Another;

use MyExample\MyAttribute;

#[MyAttribute]
#[\MyExample\MyAttribute]
#[MyAttribute(1234)]
#[MyAttribute(value: 1234)]
#[MyAttribute(MyAttribute::VALUE)]
#[MyAttribute(array("key" => "value"))]
#[MyAttribute(100 + 200)]
class Thing
{
}

#[MyAttribute(1234), MyAttribute(5678)]
class AnotherThing
{
}


リフレクションAPI を使ってアトリビュートを読み取る

クラス、メソッド、関数、パラメータ、プロパティ、クラス定数からアトリビュートにアクセスするために、 リフレクションAPI は対応するリフレクションオブジェクトに getAttributes() メソッドを提供しています。 このメソッドを使うと、 アトリビュートの名前や引数で問い合わせを行うことができ、 アトリビュートを表現するクラスをインスタンス化させることができます。 このメソッドは、ReflectionAttribute のインスタンスの配列を返します。

リフレクションされたアトリビュートの表現と、 実際のインスタンスを分離することで、 アトリビュートのクラスが存在しなかったり、 タイピングミスや引数の不足に関するエラーをプログラマが制御しやすくなります。 ReflectionAttribute::newInstance() を呼び出した後のみ、 アトリビュートクラスのオブジェクトはインスタンス化でき、 引数が合っているかを検証できます。これ以前のタイミングでは出来ません。

例1 リフレクションAPIを使い、アトリビュートを読み取る

<?php

#[Attribute]
class MyAttribute
{
public $value;

public function __construct($value)
{
$this->value = $value;
}
}

#[MyAttribute(value: 1234)]
class Thing
{
}

function dumpAttributeData($reflection) {
$attributes = $reflection->getAttributes();

foreach ($attributes as $attribute) {
var_dump($attribute->getName());
var_dump($attribute->getArguments());
var_dump($attribute->newInstance());
}
}

dumpAttributeData(new ReflectionClass(Thing::class));
/*
string(11) "MyAttribute"
array(1) {
["value"]=>
int(1234)
}
object(MyAttribute)#3 (1) {
["value"]=>
int(1234)
}
*/

アトリビュートクラスの名前を渡すことで、 リフレクションインスタンスの全てのアトリビュートをループさせる代わりに、 特定のアトリビュートのクラスだけを取得することができます。

例2 リフレクションAPIを使い、特定のアトリビュートを読み取る

<?php

function dumpMyAttributeData($reflection) {
$attributes = $reflection->getAttributes(MyAttribute::class);

foreach ($attributes as $attribute) {
var_dump($attribute->getName());
var_dump($attribute->getArguments());
var_dump($attribute->newInstance());
}
}

dumpMyAttributeData(new ReflectionClass(Thing::class));


アトリビュートクラスを宣言する

厳密に必須ではありませんが、 アトリビュート毎にクラスを作成することを推奨します。 もっとも簡単な場合、 グローバル名前空間からuse文でインポートできる アトリビュート #[Attribute] を宣言した空のクラスだけが必要です。

例1 単純なアトリビュートクラスの例

<?php

namespace Example;

use Attribute;

#[Attribute]
class MyAttribute
{
}

アトリビュートを割り当てられる場所を制限するために、 #[Attribute] 宣言の第一引数にビットマスクを渡すことができます。

例2 アトリビュートを使える場所を限定するために、ターゲットとなるクラスを作る

<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class MyAttribute
{
}

MyAttribute を別の型で宣言すると、 ReflectionAttribute::newInstance() の呼び出し時に例外がスローされます。

ビットマスクには、以下が指定できます:

  • Attribute::TARGET_CLASS
  • Attribute::TARGET_FUNCTION
  • Attribute::TARGET_METHOD
  • Attribute::TARGET_PROPERTY
  • Attribute::TARGET_CLASS_CONSTANT
  • Attribute::TARGET_PARAMETER
  • Attribute::TARGET_ALL

デフォルトでは、アトリビュートは一度宣言したら一度だけ使うことが出来ます。 アトリビュートを宣言時に繰り返し使えるようにする場合、 #[Attribute] の宣言時に、ビットマスクで指定しなければいけません。

例3 宣言時にアトリビュートを複数回使えるように、IS_REPEATABLE を使う

<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class MyAttribute
{
}


リファレンスの説明

目次

  • リファレンスとは?
  • リファレンスが行うことは何ですか?
  • リファレンスが行わないこと
  • リファレンス渡し
  • リファレンスを返す
  • リファレンスの解除
  • リファレンスの適用範囲


リファレンスとは?

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)
?>

リファレンスを返す関数でも 同じ構文が使用可能です

<?php
$foo =& find_var($bar);
?>

リファレンスを返さない関数で、同じ構文を使うとエラーになります。 new 演算子の結果に対して同じ構文を使った場合もエラーになります。 オブジェクトはポインタで渡されますが、 これはリファレンスとは異なります。 詳細な情報は オブジェクトと参照 にあります。

警告

関数の内部で 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 を、 リファレンスを使って関数内の何かに結合することはできません。 なぜなら、$bar は関数 foo からは利用できないからです （この変数は $var として表されていますが、 $var はその変数の内容のみを有しており、 コール側のシンボルテーブルで名前と変数を結合したものではありません）。 関数内で指定した変数を参照するには、リファレンス返し が使用可能です。


リファレンス渡し

リファレンスにより関数に変数を渡すことが可能です。この場合、関数内で その引数を修正可能になります。構文は次のようになります。

<?php
function foo(&$var)
{
$var++;
}

$a=5;
foo($a);
// $a はここでは 6 です
?>

注意: 関数コールの際には、リファレンス記号がないことに注意してください。 関数定義にのみリファレンス記号があります。リファレンスで正しく引数を 渡すには、関数定義のみで十分です。

次のものはリファレンスで渡すことが可能です。

  • 変数、すなわち、foo($a)

  • 関数から返されるリファレンスは、次のようになります。

    <?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()); // notice が発生

foo($a = 5); // 式、変数ではない
foo(5); // 致命的なエラーが発生する

class Foobar
{
}

foo(new Foobar()) // PHP 7.0.7 以降は E_NOTICE が発生
// Notice: Only variables should be passed by reference
?>


リファレンスを返す

リファレンスを返すことは、結合する変数を見付けるために関数を使用し たい場合に便利です。パフォーマンスを向上させるためだけの目的で この機能を用いることはやめてください。 そのようなことをしなくても、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
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 を削除してもグローバル変数は 削除されないことを意味します。


定義済みの変数

PHP には定義済みの定数が多く用意されており、すべてのスクリプトで使用することができます。 外部から来る変数 や組み込みの環境変数、直近のエラーメッセージや最後に取得したヘッダなどのあらゆる内容が取得できます。

目次

  • スーパーグローバル — すべてのスコープで使用できる組み込みの変数
  • $GLOBALS — グローバルスコープで使用可能なすべての変数への参照
  • $_SERVER — サーバー情報および実行時の環境情報
  • $_GET — HTTP GET 変数
  • $_POST — HTTP POST 変数
  • $_FILES — HTTP ファイルアップロード変数
  • $_REQUEST — HTTP リクエスト変数
  • $_SESSION — セッション変数
  • $_ENV — 環境変数
  • $_COOKIE — HTTP クッキー
  • $php_errormsg — 直近のエラーメッセージ
  • $http_response_header — HTTP レスポンスヘッダ
  • $argc — スクリプトに渡された引数の数
  • $argv — スクリプトに渡された引数の配列


すべてのスコープで使用できる組み込みの変数

  • ≪ 定義済みの変数
  • $GLOBALS ≫
  • PHP Manual
  • 定義済みの変数
  • すべてのスコープで使用できる組み込みの変数

スーパーグローバル

スーパーグローバル — すべてのスコープで使用できる組み込みの変数

説明

PHP の定義済み変数の中には "スーパーグローバル" というものがあります。 これは、スクリプト全体を通してすべてのスコープで使用可能な変数のことです。 関数やメソッドの内部からアクセスする際にも global $variable; などとする必要はありません。

スーパーグローバルには次のようなものがあります。

  • $GLOBALS
  • $_SERVER
  • $_GET
  • $_POST
  • $_FILES
  • $_COOKIE
  • $_SESSION
  • $_REQUEST
  • $_ENV

注意

注意: 使用できる変数

デフォルトでは、すべてのスーパーグローバルが使用可能です。 ただし、それに影響を与える設定項目もあります。詳細は variables_order のドキュメントを参照ください。

注意: 可変変数

スーパーグローバルは、関数やクラスメソッドの中の 可変変数 として使用することはできません。

参考

  • 変数のスコープ
  • variables_order ディレクティブ
  • filter 拡張モジュール


グローバルスコープで使用可能なすべての変数への参照

  • ≪ スーパーグローバル
  • $_SERVER ≫
  • PHP Manual
  • 定義済みの変数
  • グローバルスコープで使用可能なすべての変数への参照

$GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$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

警告

PHP 8.1.0 以降、$GLOBALS 配列全体を書き換える操作はサポートされなくなりました:

例2 $GLOBALS 配列全体を書き換える操作はエラーになる

<?php
// 以下は、コンパイル時にエラーが発生します:
$GLOBALS = [];
$GLOBALS += [];
$GLOBALS =& $x;
$x =& $GLOBALS;
unset($GLOBALS);
array_pop($GLOBALS);
// ...上記以外の、$GLOBALS 全体に対するあらゆる書き込み/読み書き操作も同様です
?>

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意: 変数の可用性

他のスーパーグローバル とは異なり、$GLOBALS は PHP で常に使用可能です。

注意:

PHP 8.1.0 以降、$GLOBALS はグローバルなシンボルテーブルの、読み取り専用のコピーになりました。つまり、グローバル変数は $GLOBALS のコピーを通じて書き換えられなくなったということです。 それより前のバージョンでは、 $GLOBALS 配列は値渡しの振る舞いの例外とされ、そのコピーを通じてグローバル変数の書き換えができていました。

<?php
// PHP 8.1.0 より前の振る舞い
$a = 1;
$globals = $GLOBALS; // 建前上は値渡しのコピー
$globals['a'] = 2;
var_dump($a); // int(2)

// PHP 8.1.0 以降の振る舞い
// 以下のようにしても、$a の値は変更されません。以前の振る舞いは、値渡しのセマンティクスに違反していました。
$globals = $GLOBALS;
$globals['a'] = 1;

// 以前の振る舞いを復元するには、$GLOBALS 配列のコピーを走査し、個別のキーと値を $GLOBALS 配列に書き戻すようにして下さい。
foreach ($globals as $key => $value) {
$GLOBALS[$key] = $value;
}
?>


サーバー情報および実行時の環境情報

  • ≪ $GLOBALS
  • $_GET ≫
  • PHP Manual
  • 定義済みの変数
  • サーバー情報および実行時の環境情報

$_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — サーバー情報および実行時の環境情報

説明

$_SERVER は、ヘッダ、パス、スクリプトの位置のような 情報を有する配列です。この配列のエントリは、Web サーバーにより 生成されます。全ての Web サーバーがこれら全てを提供する保証はありません。 サーバーは、これらのいくつかを省略したり、この一覧にない他のものを 定義する可能性があります。しかし、これらの変数のほとんどは、 » CGI/1.1 specification で定義されています。したがって、これらのほとんどは定義されていることを 期待することができます。

注意: PHP を コマンドライン から実行している場合、 これらの変数のほとんどは利用できないか、 なんの意味も持ちません。

以下に示された要素に加え、 PHP はリクエストヘッダから追加の要素を生成します。 それらの要素は HTTP_ で始まり、 その後にヘッダの名前が続き、 かつ大文字に変換され、ハイフンがアンダースコアになります。 たとえば、 Accept-Language ヘッダは $_SERVER['HTTP_ACCEPT_LANGUAGE'] として利用可能です。

インデックス

'PHP_SELF'
現在実行しているスクリプトのファイル名です。 ドキュメントルートから取得されます。 例えば、http://example.com/foo/bar.php というアドレス上にあるスクリプトでは $_SERVER['PHP_SELF'] は /foo/bar.php となります。 __FILE__ 定数 には、カレント(すなわち読み込まれた)ファイルのパスとファイル名が含まれます。 PHP がコマンドラインから実行される場合、 この変数にはスクリプト名が含まれます。
'argv'
スクリプトに渡された引数の配列です。スクリプトがコマンドラインから 実行された場合、C 言語スタイルでコマンドライン引数に アクセスすることができます。GET メソッドを通してコールされた場合には 検索引数が格納されます。
'argc'
スクリプトに渡されたコマンドライン引数の数 (コマンドラインから実行した場合) です。
'GATEWAY_INTERFACE'
サーバーが使用している CGI のバージョンです。 例 'CGI/1.1'
'SERVER_ADDR'
現在のスクリプトが実行されているサーバーの IP アドレスです。
'SERVER_NAME'
現在のスクリプトが実行されているサーバーのホスト名です。 スクリプトがバーチャルホスト上で実行されている場合は そのバーチャルホスト名となります。

注意: Apache 2 では、UseCanonicalName = On と ServerName を設定する必要があります。 そうしなければ、この値はクライアントが提供するホスト名を指すようになってしまい、無意味です。 また、セキュリティ的な意味合いでこの値に頼ってはいけません。

'SERVER_SOFTWARE'
レスポンスヘッダ上に書かれている、 サーバーの認識文字列です。
'SERVER_PROTOCOL'
ページがリクエストされた際のプロトコル名とバージョンです。 例. 'HTTP/1.0'
'REQUEST_METHOD'
ページにアクセスする際に使用されたリクエストのメソッド名です。 'GET', 'HEAD', 'POST', 'PUT' など。

注意:

リクエストのメソッドが HEAD だった場合、 PHP スクリプトはヘッダを送信した後（言い換えれば、 出力バッファリングを行わずに全出力を処理した後）に終了します。

'REQUEST_TIME'
リクエストの開始時のタイムスタンプ。
'REQUEST_TIME_FLOAT'
リクエストの開始時のタイムスタンプ (マイクロ秒までの精度)。
'QUERY_STRING'
ページがアクセスされた際にもし検索引数があればそれが格納されます。
'DOCUMENT_ROOT'
現在実行されているスクリプトが存在するドキュメントルート ディレクトリです。サーバーのコンフィグレーションファイルで 定義されています。
'HTTPS'
スクリプトが HTTPS プロトコルを通じて実行されている場合に 空でない値が設定されます。
'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 ポートとして設定されている値に変わります。

注意: Apache 2 では、UseCanonicalName = On だけでなく UseCanonicalPhysicalPort = On も設定しないと物理ポート (実際のポート) を取得できません。設定しなければ、 この値は詐称できる状態になり、 物理ポートを返さなくなるかもしれません。 セキュリティに依存するコンテキストで、この値に頼るのは安全ではありません。

'SERVER_SIGNATURE'
サーバー上で生成されたページに追加される、 サーバーのバージョン名とバーチャルホスト名の文字列。 Web サーバーの設定で有効になっていることが必要です。
'PATH_TRANSLATED'
バーチャルからリアルへのマッピングがなされた後の、 現在のスクリプトのファイルシステム上（ドキュメントルートではなく） でのパス。

注意: 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 という URI でアクセスしていた場合の $_SERVER['PATH_INFO'] は /some/stuff となります。
'ORIG_PATH_INFO'
PHP で処理される前の 'PATH_INFO' の原本。

例

例1 $_SERVER の例

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

上の例の出力は、 たとえば以下のようになります。

www.example.com

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • filter 拡張モジュール


HTTP GET 変数

  • ≪ $_SERVER
  • $_POST ≫
  • PHP Manual
  • 定義済みの変数
  • HTTP GET 変数

$_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — HTTP GET 変数

説明

URL パラメータ (a.k.a クエリストリング) で現在のスクリプトに渡された変数の連想配列です。 この配列の値は、GETリクエストだけでなく、クエリストリングが含まれた全てのリクエストで収集されることに注意して下さい。

例

例1 $_GET の例

<?php
echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
?>

ユーザーが http://example.com/?name=Hannes と入力したとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意:

GET 変数は urldecode() 関数を介して渡されます。

参考

  • 外部からくる変数の処理
  • filter 拡張モジュール


HTTP POST 変数

  • ≪ $_GET
  • $_FILES ≫
  • PHP Manual
  • 定義済みの変数
  • HTTP POST 変数

$_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — HTTP POST 変数

説明

Content-Type に application/x-www-form-urlencoded あるいは multipart/form-data を用いた HTTP リクエストで、 HTTP POST メソッドから現在のスクリプトに渡された変数の連想配列です。

例

例1 $_POST の例

<?php
echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
?>

ユーザーが name=Hannes と POST したとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • 外部からくる変数の処理
  • filter 拡張モジュール


HTTP ファイルアップロード変数

  • ≪ $_POST
  • $_REQUEST ≫
  • PHP Manual
  • 定義済みの変数
  • HTTP ファイルアップロード変数

$_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — HTTP ファイルアップロード変数

説明

HTTP POST メソッドで現在のスクリプトにアップロードされた項目の連想配列です。 この配列の構造については POST メソッドによるアップロード を参照ください。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する
  • ファイルアップロードの処理


HTTP リクエスト変数

  • ≪ $_FILES
  • $_SESSION ≫
  • PHP Manual
  • 定義済みの変数
  • HTTP リクエスト変数

$_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — HTTP リクエスト変数

説明

$_GET、 $_POST そして $_COOKIE の内容をまとめた連想配列です。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意:

コマンドライン で実行する場合、ここには argv や argc の内容は含まれません。これらの内容は $_SERVER 配列に格納されます。

注意:

$_REQUEST 内の変数の内容は、 GET や POST そして COOKIE といった仕組みでスクリプトに渡されます。 これらはリモートユーザーが変更可能なので、信頼できるとは限りません。 この配列内に含まれる変数の値や順序は、 PHP の設定ディレクティブ request_order や variables_order によって決まります。

参考

  • 外部からくる変数の処理
  • filter 拡張モジュール


セッション変数

  • ≪ $_REQUEST
  • $_ENV ≫
  • PHP Manual
  • 定義済みの変数
  • セッション変数

$_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — セッション変数

説明

現在のスクリプトで使用できるセッション変数を含む連想配列です。 セッション変数の使用法についての詳細は、 セッション関数 のドキュメントを参照ください。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する


環境変数

  • ≪ $_SESSION
  • $_COOKIE ≫
  • PHP Manual
  • 定義済みの変数
  • 環境変数

$_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — 環境変数

説明

環境変数として現在のスクリプトに渡された変数の連想配列です。

これらの変数は PHP パーサが実行されている環境から PHP のグローバル名前空間に取り込まれます。 その多くは、PHP が実行されているシェルに由来するものであり、 システムが違えばシェルも違ってくるため、確定的なリストを 得ることは不可能です。定義されている環境変数のリストについては 使用しているシェルのドキュメントをご覧ください。

CGI 変数を含むその他の環境変数も、 PHP がサーバーモジュールとして実行されているか CGI プロセッサとして 実行されているかに関わらずここに含まれます。

例

例1 $_ENV の例

<?php
echo 'My username is ' .$_ENV["USER"] . '!';
?>

"bjori" がこのスクリプトを実行したとします。

上の例の出力は、 たとえば以下のようになります。

My username is bjori!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • getenv() - 環境変数の値をひとつ、または全て取得する
  • filter 拡張モジュール


HTTP クッキー

  • ≪ $_ENV
  • $php_errormsg ≫
  • PHP Manual
  • 定義済みの変数
  • HTTP クッキー

$_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — HTTP クッキー

説明

現在のスクリプトに HTTP クッキーから渡された変数の連想配列です。

例

例1 $_COOKIE の例

<?php
echo 'Hello ' . htmlspecialchars($_COOKIE["name"]) . '!';
?>

"name" というクッキーが事前に設定されているものとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • setcookie() - クッキーを送信する
  • 外部からくる変数の処理
  • filter 拡張モジュール


直近のエラーメッセージ

  • ≪ $_COOKIE
  • $http_response_header ≫
  • PHP Manual
  • 定義済みの変数
  • 直近のエラーメッセージ

$php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — 直近のエラーメッセージ

警告

この機能は PHP 7.2.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

代わりに error_get_last() を使用してください。

説明

$php_errormsg は、PHP によって発せられた 最後のエラーメッセージのテキストを格納する変数です。 エラーが発生したスコープ内、かつ track_errors 設定オプションが オン (デフォルトはオフ) にセットされている場合にのみ有効です。

警告

ユーザー定義のエラーハンドラ (set_error_handler()) が設定されている場合は、$php_errormsg はエラーハンドラが false を返した場合にのみ設定されます。

変更履歴

バージョン | 説明
8.0.0 | $php_errormsg を利用できるようにしていた track_errors ディレクティブ が削除されました。
7.2.0 | $php_errormsg を利用できるようにしていた track_errors ディレクティブ は非推奨になりました。

例

例1 $php_errormsg の例

<?php
@strpos();
echo $php_errormsg;
?>

上の例の出力は、 たとえば以下のようになります。

Wrong parameter count for strpos()

参考

  • error_get_last() - 最後に発生したエラーを取得する


HTTP レスポンスヘッダ

  • ≪ $php_errormsg
  • $argc ≫
  • PHP Manual
  • 定義済みの変数
  • HTTP レスポンスヘッダ

$http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$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); // get_contents() をコールしても、関数スコープの外側では変数の値を取得しません。
?>

上の例の出力は、 たとえば以下のようになります。

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=shift-jis"
}

Warning: Undefined variable $http_response_header
NULL


スクリプトに渡された引数の数

  • ≪ $http_response_header
  • $argv ≫
  • PHP Manual
  • 定義済みの変数
  • スクリプトに渡された引数の数

$argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argc — スクリプトに渡された引数の数

説明

コマンドラインから実行したときに、 現在のスクリプトに渡された引数の数が含まれます。

注意: スクリプトのファイル名は、常にスクリプトへの引数として渡されます。 したがって、$argc の最小値は 1 です。

注意: この変数は、register_argc_argv が無効になっている場合には使えません。

例

例1 $argc の例

<?php
var_dump($argc);
?>

このサンプルを php script.php arg1 arg2 arg3 と実行します。

上の例の出力は、 たとえば以下のようになります。

int(4)

注意

注意:

これは、$_SERVER['argc'] としても使用可能です。

参考

  • getopt() - コマンドライン引数のリストからオプションを取得する


スクリプトに渡された引数の配列

  • ≪ $argc
  • 定義済みの例外 ≫
  • PHP Manual
  • 定義済みの変数
  • スクリプトに渡された引数の配列

$argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$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"
}

注意

注意:

これは、$_SERVER['argv'] としても使用可能です。

参考

  • getopt() - コマンドライン引数のリストからオプションを取得する


定義済みの例外

目次

  • Exception
  • ErrorException
  • ClosedGeneratorException
  • Error
  • ArgumentCountError
  • ArithmeticError
  • AssertionError
  • DivisionByZeroError
  • CompileError
  • ParseError
  • TypeError
  • ValueError
  • UnhandledMatchError
  • FiberError

SPL の例外 も参照ください。


Exception

(PHP 5, PHP 7, PHP 8)

はじめに

Exception は、 すべてのユーザー例外の基底クラスです。

クラス概要

class Exception implements Throwable {
/* プロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public getMessage(): string
final public getPrevious(): ?Throwable
final public getCode(): int
final public getFile(): string
final public getLine(): int
final public getTrace(): array
final public getTraceAsString(): string
public __toString(): string
private __clone(): void
}

プロパティ

message

例外メッセージ

code

例外コード

file

例外が作られたファイル名

line

例外が作られた行

previous

直前にスローされた例外

string

スタックトレースを示す文字列

trace

スタックトレースを示す配列

目次

  • Exception::__construct — 例外を作成する
  • Exception::getMessage — 例外メッセージを取得する
  • Exception::getPrevious — 前の例外(Throwable)を返す
  • Exception::getCode — 例外コードを取得する
  • Exception::getFile — 例外が作られたファイルを取得する
  • Exception::getLine — 例外が作られた行を取得する
  • Exception::getTrace — スタックトレースを取得する
  • Exception::getTraceAsString — スタックトレースを文字列で取得する
  • Exception::__toString — 例外の文字列表現
  • Exception::__clone — 例外をコピーする


例外を作成する

  • ≪ Exception
  • Exception::getMessage ≫
  • PHP Manual
  • Exception
  • 例外を作成する

Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — 例外を作成する

説明

public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)

例外を作成します。

パラメータ

message

スローする例外メッセージ。

code

例外コード。

previous

以前に使われた例外。例外の連結に使用します。

注意: Exception クラスのコンストラクタをサブクラス側から呼ぶと、 $code と $message が設定済みの場合はデフォルトの引数を無視します。

注意

注意:

message は、バイナリセーフ ではありません。


例外メッセージを取得する

  • ≪ Exception::__construct
  • Exception::getPrevious ≫
  • PHP Manual
  • Exception
  • 例外メッセージを取得する

Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — 例外メッセージを取得する

説明

final public Exception::getMessage(): string

例外メッセージを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外メッセージ文字列を返します。

例

例1 Exception::getMessage() の例

<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Some error message

参考

  • Throwable::getMessage() - メッセージを取得する


前の例外(Throwable)を返す

  • ≪ Exception::getMessage
  • Exception::getCode ≫
  • PHP Manual
  • Exception
  • 前の例外(Throwable)を返す

Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — 前の例外(Throwable)を返す

説明

final public Exception::getPrevious(): ?Throwable

前に発生した Throwable (Exception::__construct() に渡された 3 番目の引数) を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

前に発生した Throwable、あるいはそれが存在しない場合は 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 happened", 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 happened (911) [MyCustomException]
/home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentException]

参考

  • Throwable::getPrevious() - ひとつ前の Throwable を返す


例外コードを取得する

  • ≪ Exception::getPrevious
  • Exception::getFile ≫
  • PHP Manual
  • Exception
  • 例外コードを取得する

Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — 例外コードを取得する

説明

final public Exception::getCode(): int

例外コードを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外コードを整数値で返します。しかし、 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

参考

  • Throwable::getCode() - 例外コードを取得する


例外が作られたファイルを取得する

  • ≪ Exception::getCode
  • Exception::getLine ≫
  • PHP Manual
  • Exception
  • 例外が作られたファイルを取得する

Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — 例外が作られたファイルを取得する

説明

final public Exception::getFile(): string

例外が作られたファイルの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外が作られたファイルの名前を返します。

例

例1 Exception::getFile() の例

<?php
try {
throw new Exception;
} catch(Exception $e) {
echo $e->getFile();
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/tmp/ex.php

参考

  • Throwable::getFile() - オブジェクトが作られたファイル名を取得する


例外が作られた行を取得する

  • ≪ Exception::getFile
  • Exception::getTrace ≫
  • PHP Manual
  • Exception
  • 例外が作られた行を取得する

Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — 例外が作られた行を取得する

説明

final public Exception::getLine(): int

例外が作られた行番号を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外が作られた行番号を返します。

例

例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

参考

  • Throwable::getLine() - オブジェクトのインスタンスが作られた行番号を取得する


スタックトレースを取得する

  • ≪ Exception::getLine
  • Exception::getTraceAsString ≫
  • PHP Manual
  • Exception
  • スタックトレースを取得する

Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — スタックトレースを取得する

説明

final public Exception::getTrace(): array

例外のスタックトレースを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外のスタックトレースを配列で返します。

例

例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) {
    }
  }
}

参考

  • Throwable::getTrace() - スタックトレースを取得する


スタックトレースを文字列で取得する

  • ≪ Exception::getTrace
  • Exception::__toString ≫
  • PHP Manual
  • Exception
  • スタックトレースを文字列で取得する

Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — スタックトレースを文字列で取得する

説明

final public Exception::getTraceAsString(): string

例外のスタックトレースを文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外のスタックトレースを文字列で返します。

例

例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}

参考

  • Throwable::getTraceAsString() - スタックトレースを文字列として取得する


例外の文字列表現

  • ≪ Exception::getTraceAsString
  • Exception::__clone ≫
  • PHP Manual
  • Exception
  • 例外の文字列表現

Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — 例外の文字列表現

説明

public Exception::__toString(): string

例外を文字列で表現したものを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外を文字列で表現したものを返します。

例

例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}

参考

  • Throwable::__toString() - スローされたオブジェクトの文字列表現を取得する


例外をコピーする

  • ≪ Exception::__toString
  • ErrorException ≫
  • PHP Manual
  • Exception
  • 例外をコピーする

Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — 例外をコピーする

説明

private Exception::__clone(): void

Exception のコピーは作成できません。 作成しようとすると、Error がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

例外はクローン不可能です。

変更履歴

バージョン | 説明
8.1.0 | Exception::__clone() は、、 final ではなくなりました。


ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

エラー例外です。

クラス概要

class ErrorException extends Exception {
/* プロパティ */
protected int $severity = E_ERROR;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public __construct(
string $message = "",
int $code = 0,
int $severity = E_ERROR,
?string $filename = null,
?int $line = null,
?Throwable $previous = null
)
final public getSeverity(): int
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

severity

例外の深刻度

例

例1 set_error_handler() を使用した、エラーメッセージから ErrorException への変換

<?php
set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
if (!(error_reporting() & $errno)) {
// このエラーコードが error_reporting に含まれていない場合
return;
}
if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
// 推奨されない警告の場合は、例外をスローしません。
// 新規または想定外の渓谷がアプリケーションを壊すからです。
return;
}
throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
});

// 壊れたデータをアンシリアライズすると、エラーハンドラによって
// 警告は ErrorException に変換されます。
unserialize('broken data');
?>

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught ErrorException: unserialize(): Error at offset 0 of 11 bytes in test.php:16
Stack trace:
#0 [internal function]: {closure}(2, 'unserialize(): ...', 'test.php', 16)
#1 test.php(16): unserialize('broken data')
#2 {main}
  thrown in test.php on line 16

目次

  • ErrorException::__construct — 例外を作成する
  • ErrorException::getSeverity — 例外の深刻度を取得する


例外を作成する

  • ≪ ErrorException
  • ErrorException::getSeverity ≫
  • PHP Manual
  • ErrorException
  • 例外を作成する

ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — 例外を作成する

説明

public ErrorException::__construct(
string $message = "",
int $code = 0,
int $severity = E_ERROR,
?string $filename = null,
?int $line = null,
?Throwable $previous = null
)

例外を作成します。

パラメータ

message

スローする例外メッセージ。

code

例外コード。

severity

例外の深刻度。

注意:

任意の int を設定できますが、ここでは エラー定数 を用いることを想定しています。

filename

例外がスローされたファイル名。

line

例外がスローされた行番号。

previous

ひとつ前の例外。例外の連結に使います。

変更履歴

バージョン | 説明
8.0.0 | filename と line は、 nullable になりました。 これより前のバージョンでは、 それらのデフォルト値はそれぞれ __FILE__ と __LINE__ でした。


例外の深刻度を取得する

  • ≪ ErrorException::__construct
  • ClosedGeneratorException ≫
  • PHP Manual
  • ErrorException
  • 例外の深刻度を取得する

ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — 例外の深刻度を取得する

説明

final public ErrorException::getSeverity(): int

例外の深刻度を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外の深刻度レベルを返します。

例

例1 ErrorException::getSeverity() の例

<?php
try {
throw new ErrorException("Exception message", 0, E_USER_ERROR);
} catch(ErrorException $e) {
echo "This exception severity is: " . $e->getSeverity();
var_dump($e->getSeverity() === E_USER_ERROR);
}
?>

上の例の出力は、 たとえば以下のようになります。

This exception severity is: 256
bool(true)


ClosedGeneratorException クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

ClosedGeneratorException は 閉じられた Generator から値を取得しようとした場合にスローされます。

クラス概要

class ClosedGeneratorException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


Error

(PHP 7, PHP 8)

はじめに

Error は、PHP のすべての内部エラーの基底クラスです。

クラス概要

class Error implements Throwable {
/* プロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public getMessage(): string
final public getPrevious(): ?Throwable
final public getCode(): int
final public getFile(): string
final public getLine(): int
final public getTrace(): array
final public getTraceAsString(): string
public __toString(): string
private __clone(): void
}

プロパティ

message

エラーメッセージ

code

エラーコード

file

エラーが発生したファイル名

line

エラーが発生した行番号

previous

直前にスローされた例外

string

スタックトレースを示す文字列

trace

スタックトレースを示す配列

目次

  • Error::__construct — エラーオブジェクトを生成する
  • Error::getMessage — エラーメッセージを取得する
  • Error::getPrevious — 直前の Throwable を返す
  • Error::getCode — エラーコードを取得する
  • Error::getFile — エラーが起きたファイルを取得する
  • Error::getLine — エラーが起きた行番号を取得する
  • Error::getTrace — スタックトレースを取得する
  • Error::getTraceAsString — スタックトレースを文字列として取得する
  • Error::__toString — エラーの文字列表現
  • Error::__clone — エラーをクローンする


エラーオブジェクトを生成する

  • ≪ Error
  • Error::getMessage ≫
  • PHP Manual
  • Error
  • エラーオブジェクトを生成する

Error::__construct

(PHP 7, PHP 8)

Error::__construct — エラーオブジェクトを生成する

説明

public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)

エラーを生成する。

パラメータ

message

エラーメッセージ。

code

エラーコード。

previous

例外チェーンに使われる、直前のスロー可能オブジェクト。

注意

注意:

message はバイナリセーフでは ありません。


エラーメッセージを取得する

  • ≪ Error::__construct
  • Error::getPrevious ≫
  • PHP Manual
  • Error
  • エラーメッセージを取得する

Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — エラーメッセージを取得する

説明

final public Error::getMessage(): string

エラーメッセージを返す。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーメッセージを文字列で返す。

例

例1 Error::getMessage() の例

<?php
try {
throw new Error("Some error message");
} catch(Error $e) {
echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Some error message

参考

  • Throwable::getMessage() - メッセージを取得する


直前の Throwable を返す

  • ≪ Error::getMessage
  • Error::getCode ≫
  • PHP Manual
  • Error
  • 直前の Throwable を返す

Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — 直前の Throwable を返す

説明

final public Error::getPrevious(): ?Throwable

直前の Throwable（Error::__construct() の3番目の引数）を返す。

パラメータ

この関数にはパラメータはありません。

戻り値

直前の Throwable が利用可能であればそれを返し、 そうでなければ null を返す。

例

例1 Error::getPrevious() の例

エラートレースをループし、出力する。

<?php
class MyCustomError extends Error {}

function doStuff() {
try {
throw new InvalidArgumentError("You are doing it wrong!", 112);
} catch(Error $e) {
throw new MyCustomError("Something happened", 911, $e);
}
}

try {
doStuff();
} catch(Error $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 happened (911) [MyCustomError]
/home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentError]

参考

  • Throwable::getPrevious() - ひとつ前の Throwable を返す


エラーコードを取得する

  • ≪ Error::getPrevious
  • Error::getFile ≫
  • PHP Manual
  • Error
  • エラーコードを取得する

Error::getCode

(PHP 7, PHP 8)

Error::getCode — エラーコードを取得する

説明

final public Error::getCode(): int

エラーコードを返します

パラメータ

この関数にはパラメータはありません。

戻り値

エラーコードを int 型として返します

例

例1 Error::getCode() の例

<?php
try {
throw new Error("Some error message", 30);
} catch(Error $e) {
echo "The Error code is: " . $e->getCode();
}
?>

上の例の出力は、 たとえば以下のようになります。

The Error code is: 30

参考

  • Throwable::getCode() - 例外コードを取得する


エラーが起きたファイルを取得する

  • ≪ Error::getCode
  • Error::getLine ≫
  • PHP Manual
  • Error
  • エラーが起きたファイルを取得する

Error::getFile

(PHP 7, PHP 8)

Error::getFile — エラーが起きたファイルを取得する

説明

final public Error::getFile(): string

エラーが起きたファイル名を取得します

パラメータ

この関数にはパラメータはありません。

戻り値

エラーが起きたファイル名を返します

例

例1 Error::getFile() の例

<?php
try {
throw new Error;
} catch(Error $e) {
echo $e->getFile();
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/tmp/ex.php

参考

  • Throwable::getFile() - オブジェクトが作られたファイル名を取得する


エラーが起きた行番号を取得する

  • ≪ Error::getFile
  • Error::getTrace ≫
  • PHP Manual
  • Error
  • エラーが起きた行番号を取得する

Error::getLine

(PHP 7, PHP 8)

Error::getLine — エラーが起きた行番号を取得する

説明

final public Error::getLine(): int

エラーが起きた行番号を取得します

パラメータ

この関数にはパラメータはありません。

戻り値

エラーが起きた行番号を返します

例

例1 Error::getLine() の例

<?php
try {
throw new Error("Some error message");
} catch(Error $e) {
echo "The error was created on line: " . $e->getLine();
}
?>

上の例の出力は、 たとえば以下のようになります。

The error was created on line: 3

参考

  • Throwable::getLine() - オブジェクトのインスタンスが作られた行番号を取得する


スタックトレースを取得する

  • ≪ Error::getLine
  • Error::getTraceAsString ≫
  • PHP Manual
  • Error
  • スタックトレースを取得する

Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — スタックトレースを取得する

説明

final public Error::getTrace(): array

スタックトレースを返します

パラメータ

この関数にはパラメータはありません。

戻り値

スタックトレースを array として返します

例

例1 Error::getTrace() の例

<?php
function test() {
throw new Error;
}

try {
test();
} catch(Error $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) {
    }
  }
}

参考

  • Throwable::getTrace() - スタックトレースを取得する


スタックトレースを文字列として取得する

  • ≪ Error::getTrace
  • Error::__toString ≫
  • PHP Manual
  • Error
  • スタックトレースを文字列として取得する

Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — スタックトレースを文字列として取得する

説明

final public Error::getTraceAsString(): string

スタックトレースを文字列として返します

パラメータ

この関数にはパラメータはありません。

戻り値

スタックトレースを文字列として返します

例

例1 Error::getTraceAsString() の例

<?php
function test() {
throw new Error;
}

try {
test();
} catch(Error $e) {
echo $e->getTraceAsString();
}
?>

上の例の出力は、 たとえば以下のようになります。

#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}

参考

  • Throwable::getTraceAsString() - スタックトレースを文字列として取得する


エラーの文字列表現

  • ≪ Error::getTraceAsString
  • Error::__clone ≫
  • PHP Manual
  • Error
  • エラーの文字列表現

Error::__toString

(PHP 7, PHP 8)

Error::__toString — エラーの文字列表現

説明

public Error::__toString(): string

エラーの string 型の表現を返します

パラメータ

この関数にはパラメータはありません。

戻り値

エラーの string 型の表現を返します

例

例1 Error::__toString() の例

<?php
try {
throw new Error("Some error message");
} catch(Error $e) {
echo $e;
}
?>

上の例の出力は、 たとえば以下のようになります。

Error: Some error message in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}

参考

  • Throwable::__toString() - スローされたオブジェクトの文字列表現を取得する


エラーをクローンする

  • ≪ Error::__toString
  • ArgumentCountError ≫
  • PHP Manual
  • Error
  • エラーをクローンする

Error::__clone

(PHP 7, PHP 8)

Error::__clone — エラーをクローンする

説明

private Error::__clone(): void

エラーはクローンできないので、このメソッドは fatal エラーとなります。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

エラーはクローン可能ではありません。

変更履歴

バージョン | 説明
8.1.0 | Error::__clone() は、 final ではなくなりました。


ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

はじめに

ArgumentCountError は、 ユーザー定義の関数あるいはメソッドに渡された引数が少なすぎる場合にスローされます。

可変長引数でない組み込み関数に、多過ぎる引数を渡した場合にもスローされます。

クラス概要

class ArgumentCountError extends TypeError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


ArithmeticError

(PHP 7, PHP 8)

はじめに

ArithmeticError は、数学的な操作でエラーが発生した場合にスローされます。 たとえばマイナスのビットシフトを行おうとした場合などに発生します。 また、結果が int の範囲をこえてしまうような intdiv() の呼び出しの際にも発生します。

クラス概要

class ArithmeticError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


AssertionError

(PHP 7, PHP 8)

はじめに

AssertionError は、assert() によるアサーションが失敗したときにスローされます。

クラス概要

class AssertionError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


DivisionByZeroError

(PHP 7, PHP 8)

はじめに

DivisionByZeroError は、数値をゼロで割ろうとした場合にスローされます。

クラス概要

class DivisionByZeroError extends ArithmeticError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


CompileError

(PHP 7 > 7.3.0, PHP 8)

はじめに

CompileError は コンパイルエラーが起きた時にスローされます。 以前は fatal error が発生していました。

クラス概要

class CompileError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


ParseError

(PHP 7, PHP 8)

はじめに

ParseError は、eval() を呼んだときなどの PHP コードのパースに失敗した場合にスローされます。

注意: PHP 7.3.0 以降は、ParseError クラスは CompileError クラスを継承するようになりました。 以前のバージョンでは、Error を継承していました。

クラス概要

class ParseError extends CompileError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


TypeError

(PHP 7, PHP 8)

はじめに

TypeError がスローされるのは、以下の場合です:

  • クラスのプロパティに設定されている値が、プロパティで宣言されている型と一致しない場合。
  • 関数に渡された引数の型が、関数の宣言時に指定された型と一致しない場合。
  • 関数の戻り値の型が、関数の宣言時に指定された型と一致しない場合。

クラス概要

class TypeError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}

変更履歴

バージョン | 説明
7.1.0 | strict モードの場合に、 PHP の組み込みの関数に渡す引数の数を間違えた場合でも、 TypeError はスローされなくなりました。 代わりに、 ArgumentCountError がスローされるようになっています。


ValueError

(PHP 8)

はじめに

ValueError は、 引数の型は正しいものの、値が正しくない場合にスローされます。 たとえば、関数は正の整数を期待しているのに負の値を渡したり、 空でない文字列/配列を期待しているのに空の値を渡したりした場合です。

クラス概要

class ValueError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


UnhandledMatchError

(PHP 8)

はじめに

UnhandledMatchError は、 match 式がどの分岐でも処理できなかったことを検知した場合にスローされます。

クラス概要

class UnhandledMatchError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


FiberError

(PHP 8 >= 8.1.0)

はじめに

FiberError は、 Fiber に対して不正な操作が行われた場合にスローされます。

クラス概要

final class FiberError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public __construct()
/* 継承したメソッド */
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}

目次

  • FiberError::__construct — インスタンス化を禁止するためのコンストラクタ


インスタンス化を禁止するためのコンストラクタ

  • ≪ FiberError
  • 定義済みのインターフェイスとクラス ≫
  • PHP Manual
  • FiberError
  • インスタンス化を禁止するためのコンストラクタ

FiberError::__construct

(PHP 8 >= 8.1.0)

FiberError::__construct — インスタンス化を禁止するためのコンストラクタ

説明

public FiberError::__construct()

パラメータ

この関数にはパラメータはありません。

エラー / 例外

このメソッドがコールされると、 Error 例外がスローされます。


定義済みのインターフェイスとクラス

目次

  • Traversable
  • Iterator
  • IteratorAggregate
  • InternalIterator
  • Throwable
  • ArrayAccess
  • Serializable
  • Closure
  • stdClass
  • Generator
  • Fiber
  • WeakReference
  • WeakMap
  • Stringable
  • UnitEnum
  • BackedEnum
  • SensitiveParameterValue
  • __PHP_Incomplete_Class

SPL インターフェイス および 定義済のクラス も参照ください。


Traversable インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

そのクラスの中身が foreach を使用してたどれるかどうかを検出するインターフェイスです。

これは抽象インターフェイスであり、単体で実装することはできません。 IteratorAggregate あるいは Iterator を実装しなければなりません。

インターフェイス概要

interface Traversable {
}

このインターフェイスにはメソッドがありません。 traverse 可能なすべてのクラス用の基底インターフェイスとしてのみ存在しています。

変更履歴

バージョン | 説明
7.4.0 | Traversable インターフェイスは、抽象クラスによって実装できるようになりました。 これを拡張するには、 Iterator あるいは IteratorAggregate を実装しなければなりません。

注意

注意:

このインターフェイスを実装した内部（組み込み）クラスは、 foreach の中で使うことができます。 IteratorAggregate や Iterator を実装する必要はありません。

注意:

PHP 7.4.0 より前のバージョンでは、 この内部的なエンジンのインターフェイスは PHP スクリプトが実装できませんでした。 代わりに、 IteratorAggregate か Iterator を使わなければなりませんでした。


Iterator インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

外部のイテレータあるいはオブジェクト自身から反復処理を行うためのインターフェイスです。

インターフェイス概要

interface Iterator extends Traversable {
/* メソッド */
public current(): mixed
public key(): mixed
public next(): void
public rewind(): void
public valid(): bool
}

定義済みのイテレータ

PHP には多くのイテレータがあらかじめ用意されており、日々の作業に使えます。その一覧は SPL イテレータ を参照ください。

例

例1 基本的な使用法

この例は、イテレータで foreach を使ったときに、どんな順番でメソッドが呼ばれるかを示すものです。

<?php
class myIterator implements Iterator {
private $position = 0;
private $array = array(
"firstelement",
"secondelement",
"lastelement",
);

public function __construct() {
$this->position = 0;
}

public function rewind(): void {
var_dump(__METHOD__);
$this->position = 0;
}

#[\ReturnTypeWillChange]
public function current() {
var_dump(__METHOD__);
return $this->array[$this->position];
}

#[\ReturnTypeWillChange]
public function key() {
var_dump(__METHOD__);
return $this->position;
}

public function next(): void {
var_dump(__METHOD__);
++$this->position;
}

public function valid(): bool {
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 — 現在の要素を返す
  • Iterator::key — 現在の要素のキーを返す
  • Iterator::next — 次の要素に進む
  • Iterator::rewind — イテレータの最初の要素に巻き戻す
  • Iterator::valid — 現在位置が有効かどうかを調べる


現在の要素を返す

  • ≪ Iterator
  • Iterator::key ≫
  • PHP Manual
  • Iterator
  • 現在の要素を返す

Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — 現在の要素を返す

説明

public Iterator::current(): mixed

現在の要素を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

あらゆる型を返すことが可能です。


現在の要素のキーを返す

  • ≪ Iterator::current
  • Iterator::next ≫
  • PHP Manual
  • Iterator
  • 現在の要素のキーを返す

Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — 現在の要素のキーを返す

説明

public Iterator::key(): mixed

現在の要素のキーを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にスカラー型、失敗した場合に null を返します。

エラー / 例外

失敗した場合に E_NOTICE を発行します。


次の要素に進む

  • ≪ Iterator::key
  • Iterator::rewind ≫
  • PHP Manual
  • Iterator
  • 次の要素に進む

Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — 次の要素に進む

説明

public Iterator::next(): void

現在位置を次の要素に移動します。

注意:

このメソッドは、各 foreach ループの 後 にコールされます。

パラメータ

この関数にはパラメータはありません。

戻り値

戻り値は無視されます。


イテレータの最初の要素に巻き戻す

  • ≪ Iterator::next
  • Iterator::valid ≫
  • PHP Manual
  • Iterator
  • イテレータの最初の要素に巻き戻す

Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — イテレータの最初の要素に巻き戻す

説明

public Iterator::rewind(): void

イテレータの最初の要素に巻き戻します。

注意:

これは、foreach ループの開始時に 最初 にコールされるメソッドです。 foreach ループの 後 には実行 されません。

パラメータ

この関数にはパラメータはありません。

戻り値

戻り値は無視されます。


現在位置が有効かどうかを調べる

  • ≪ Iterator::rewind
  • IteratorAggregate ≫
  • PHP Manual
  • Iterator
  • 現在位置が有効かどうかを調べる

Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — 現在位置が有効かどうかを調べる

説明

public Iterator::valid(): bool

このメソッドは Iterator::rewind() および Iterator::next() の後にコールされ、 現在の位置が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

戻り値は bool にキャストして評価されます。 成功した場合に true を、失敗した場合に false を返します。


IteratorAggregate インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

外部イテレータを作成するためのインターフェイスです。

インターフェイス概要

interface IteratorAggregate extends Traversable {
/* メソッド */
public getIterator(): Traversable
}

例

例1 基本的な例

<?php

class myData implements IteratorAggregate
{
public $property1 = "Public property one";
public $property2 = "Public property two";
public $property3 = "Public property three";
public $property4 = "";

public function __construct()
{
$this->property4 = "last property";
}

public function getIterator(): Traversable
{
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 — 外部イテレータを取得する


外部イテレータを取得する

  • ≪ IteratorAggregate
  • InternalIterator ≫
  • PHP Manual
  • IteratorAggregate
  • 外部イテレータを取得する

IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — 外部イテレータを取得する

説明

public IteratorAggregate::getIterator(): Traversable

外部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Iterator あるいは Traversable を実装したオブジェクトのインスタンスを返します。

エラー / 例外

失敗した場合は Exception をスローします。


InternalIterator クラス

(PHP 8)

はじめに

内部クラス が、 IteratorAggregate を実装しやすくするためのクラスです。

クラス概要

final class InternalIterator implements Iterator {
/* メソッド */
private __construct()
public current(): mixed
public key(): mixed
public next(): void
public rewind(): void
public valid(): bool
}

目次

  • InternalIterator::__construct — private なコンストラクタのため、直接インスタンス化できません
  • InternalIterator::current — 現在の要素を返す
  • InternalIterator::key — 現在の要素のキーを返す
  • InternalIterator::next — 次の要素に進む
  • InternalIterator::rewind — イテレータの最初の要素に巻き戻す
  • InternalIterator::valid — 現在位置が有効かどうかを調べる


private なコンストラクタのため、直接インスタンス化できません

  • ≪ InternalIterator
  • InternalIterator::current ≫
  • PHP Manual
  • InternalIterator
  • private なコンストラクタのため、直接インスタンス化できません

InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — private なコンストラクタのため、直接インスタンス化できません

説明

private InternalIterator::__construct()

パラメータ

この関数にはパラメータはありません。


現在の要素を返す

  • ≪ InternalIterator::__construct
  • InternalIterator::key ≫
  • PHP Manual
  • InternalIterator
  • 現在の要素を返す

InternalIterator::current

(PHP 8)

InternalIterator::current — 現在の要素を返す

説明

public InternalIterator::current(): mixed

現在の要素を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素を返します。


現在の要素のキーを返す

  • ≪ InternalIterator::current
  • InternalIterator::next ≫
  • PHP Manual
  • InternalIterator
  • 現在の要素のキーを返す

InternalIterator::key

(PHP 8)

InternalIterator::key — 現在の要素のキーを返す

説明

public InternalIterator::key(): mixed

現在の要素のキーを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素のキーを返します。


次の要素に進む

  • ≪ InternalIterator::key
  • InternalIterator::rewind ≫
  • PHP Manual
  • InternalIterator
  • 次の要素に進む

InternalIterator::next

(PHP 8)

InternalIterator::next — 次の要素に進む

説明

public InternalIterator::next(): void

現在位置を次の要素に移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


イテレータの最初の要素に巻き戻す

  • ≪ InternalIterator::next
  • InternalIterator::valid ≫
  • PHP Manual
  • InternalIterator
  • イテレータの最初の要素に巻き戻す

InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — イテレータの最初の要素に巻き戻す

説明

public InternalIterator::rewind(): void

イテレータの最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


現在位置が有効かどうかを調べる

  • ≪ InternalIterator::rewind
  • Throwable ≫
  • PHP Manual
  • InternalIterator
  • 現在位置が有効かどうかを調べる

InternalIterator::valid

(PHP 8)

InternalIterator::valid — 現在位置が有効かどうかを調べる

説明

public InternalIterator::valid(): bool

現在位置が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在位置が有効かどうかを返します。


Throwable

(PHP 7, PHP 8)

はじめに

Throwable は、throw 文でスロー可能なあらゆるオブジェクトが実装する基底インターフェイスです。 Error や Exception も、これを実装しています。

注意:

PHP のクラスが Throwable インターフェイスを直接実装することはできません。 そのかわりに、Exception を継承する必要があります。

インターフェイス概要

interface Throwable extends Stringable {
/* メソッド */
public getMessage(): string
public getCode(): int
public getFile(): string
public getLine(): int
public getTrace(): array
public getTraceAsString(): string
public getPrevious(): ?Throwable
public __toString(): string
/* 継承したメソッド */
public Stringable::__toString(): string
}

変更履歴

バージョン | 説明
8.0.0 | Throwable は、 Stringable を新たに実装しました。

目次

  • Throwable::getMessage — メッセージを取得する
  • Throwable::getCode — 例外コードを取得する
  • Throwable::getFile — オブジェクトが作られたファイル名を取得する
  • Throwable::getLine — オブジェクトのインスタンスが作られた行番号を取得する
  • Throwable::getTrace — スタックトレースを取得する
  • Throwable::getTraceAsString — スタックトレースを文字列として取得する
  • Throwable::getPrevious — ひとつ前の Throwable を返す
  • Throwable::__toString — スローされたオブジェクトの文字列表現を取得する


メッセージを取得する

  • ≪ Throwable
  • Throwable::getCode ≫
  • PHP Manual
  • Throwable
  • メッセージを取得する

Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — メッセージを取得する

説明

public Throwable::getMessage(): string

スローされたオブジェクトに関連づけられたメッセージを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

スローされたオブジェクトに関連づけられたメッセージを返します。

参考

  • Exception::getMessage() - 例外メッセージを取得する


例外コードを取得する

  • ≪ Throwable::getMessage
  • Throwable::getFile ≫
  • PHP Manual
  • Throwable
  • 例外コードを取得する

Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — 例外コードを取得する

説明

public Throwable::getCode(): int

スローされたオブジェクトのエラーコードを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

例外コードを返します。 Exception の場合は int ですが、 その派生クラスでは別の型かもしれません (たとえば PDOException の場合は string です)。

参考

  • Exception::getCode() - 例外コードを取得する


オブジェクトが作られたファイル名を取得する

  • ≪ Throwable::getCode
  • Throwable::getLine ≫
  • PHP Manual
  • Throwable
  • オブジェクトが作られたファイル名を取得する

Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — オブジェクトが作られたファイル名を取得する

説明

public Throwable::getFile(): string

スローされたオブジェクトが作られたファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

スローされたオブジェクトが作られたファイル名を返します。

参考

  • Exception::getFile() - 例外が作られたファイルを取得する


オブジェクトのインスタンスが作られた行番号を取得する

  • ≪ Throwable::getFile
  • Throwable::getTrace ≫
  • PHP Manual
  • Throwable
  • オブジェクトのインスタンスが作られた行番号を取得する

Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — オブジェクトのインスタンスが作られた行番号を取得する

説明

public Throwable::getLine(): int

スローされたオブジェクトのインスタンスが作られた行番号を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

スローされたオブジェクトのインスタンスが作られた行番号を返します。

参考

  • Exception::getLine() - 例外が作られた行を取得する


スタックトレースを取得する

  • ≪ Throwable::getLine
  • Throwable::getTraceAsString ≫
  • PHP Manual
  • Throwable
  • スタックトレースを取得する

Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — スタックトレースを取得する

説明

public Throwable::getTrace(): array

スタックトレースの配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

スタックトレースの配列を返します。その書式は debug_backtrace() と同じです。

参考

  • Exception::getTrace() - スタックトレースを取得する


スタックトレースを文字列として取得する

  • ≪ Throwable::getTrace
  • Throwable::getPrevious ≫
  • PHP Manual
  • Throwable
  • スタックトレースを文字列として取得する

Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — スタックトレースを文字列として取得する

説明

public Throwable::getTraceAsString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

スタックトレースを文字列として返します。

参考

  • Exception::getTraceAsString() - スタックトレースを文字列で取得する


ひとつ前の Throwable を返す

  • ≪ Throwable::getTraceAsString
  • Throwable::__toString ≫
  • PHP Manual
  • Throwable
  • ひとつ前の Throwable を返す

Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — ひとつ前の Throwable を返す

説明

public Throwable::getPrevious(): ?Throwable

ひとつ前の Throwable (たとえば Exception::__construct() の第三パラメータで指定したもの) を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ひとつ前の Throwable が存在すればそれを返します。 存在しない場合は null を返します。

参考

  • Exception::getPrevious() - 前の例外(Throwable)を返す


スローされたオブジェクトの文字列表現を取得する

  • ≪ Throwable::getPrevious
  • ArrayAccess ≫
  • PHP Manual
  • Throwable
  • スローされたオブジェクトの文字列表現を取得する

Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — スローされたオブジェクトの文字列表現を取得する

説明

public Throwable::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

スローされたオブジェクトの文字列表現を返します。

参考

  • Exception::__toString() - 例外の文字列表現


ArrayAccess インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

配列としてオブジェクトにアクセスするための機能のインターフェイスです。

インターフェイス概要

interface ArrayAccess {
/* メソッド */
public offsetExists(mixed $offset): bool
public offsetGet(mixed $offset): mixed
public offsetSet(mixed $offset, mixed $value): void
public offsetUnset(mixed $offset): void
}

例

例1 基本的な使用法

<?php
class Obj implements ArrayAccess {
public $container = [
"one" => 1,
"two" => 2,
"three" => 3,
];

public function offsetSet($offset, $value): void {
if (is_null($offset)) {
$this->container[] = $value;
} else {
$this->container[$offset] = $value;
}
}

public function offsetExists($offset): bool {
return isset($this->container[$offset]);
}

public function offsetUnset($offset): void {
unset($this->container[$offset]);
}

public function offsetGet($offset): mixed {
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 — オフセットが存在するかどうか
  • ArrayAccess::offsetGet — オフセットを取得する
  • ArrayAccess::offsetSet — 指定したオフセットに値を設定する
  • ArrayAccess::offsetUnset — オフセットの設定を解除する


オフセットが存在するかどうか

  • ≪ ArrayAccess
  • ArrayAccess::offsetGet ≫
  • PHP Manual
  • ArrayAccess
  • オフセットが存在するかどうか

ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — オフセットが存在するかどうか

説明

public ArrayAccess::offsetExists(mixed $offset): bool

オフセットが存在するかどうかを返します。

このメソッドが実行されるのは、ArrayAccess を実装したオブジェクト上で isset() あるいは empty() を使用した場合です。

注意:

empty() を使用すると ArrayAccess::offsetGet() がコールされ、ArrayAccess::offsetExists() が true を返すかどうかで空かどうかを判断します。

パラメータ

offset

調べたいオフセット。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意:

非 boolean 値が返された場合は bool にキャストして返します。

例

例1 ArrayAccess::offsetExists() の例

<?php
class obj implements ArrayAccess {
public function offsetSet($offset, $value): void {
var_dump(__METHOD__);
}
public function offsetExists($var): bool {
var_dump(__METHOD__);
if ($var == "foobar") {
return true;
}
return false;
}
public function offsetUnset($var): void {
var_dump(__METHOD__);
}
#[\ReturnTypeWillChange]
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::offsetExists
  • ArrayAccess::offsetSet ≫
  • PHP Manual
  • ArrayAccess
  • オフセットを取得する

ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — オフセットを取得する

説明

public ArrayAccess::offsetGet(mixed $offset): mixed

指定したオフセットの値を返します。

このメソッドは、オフセットが empty() かどうかを調べる際に実行されます。

パラメータ

offset

取得したいオフセット。

戻り値

すべての型の値を返すことができます。

注意

注意:

このメソッドの実装で参照を返すことができます。 これにより、ArrayAccess オブジェクトのオーバーロードされた配列に対する間接的な変更ができます。

直接的な変更とは、$obj[6] = 7 のように配列のその次元の値を完全に置き換える変更のことです。 一方、間接的な変更とは、$obj[6][7] = 7 のようにその次元の一部分のみを変更したり $var =& $obj[6] のように他の変数に参照を代入したりする変更のことです。 ++ によるインクリメントや -- によるデクリメントもまた、ある意味では間接的な変更を要するものです。

直接的な変更の際には ArrayAccess::offsetSet() がコールされますが、間接的な変更の際には ArrayAccess::offsetGet() がコールされます。この場合は ArrayAccess::offsetGet() の実装が参照を返せるようにしておく必要があります。 そうしなければ E_NOTICE メッセージが発生します。

参考

  • ArrayAccess::offsetExists() - オフセットが存在するかどうか


指定したオフセットに値を設定する

  • ≪ ArrayAccess::offsetGet
  • ArrayAccess::offsetUnset ≫
  • PHP Manual
  • ArrayAccess
  • 指定したオフセットに値を設定する

ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — 指定したオフセットに値を設定する

説明

public ArrayAccess::offsetSet(mixed $offset, mixed $value): void

指定したオフセットに値を代入します。

パラメータ

offset

値を代入したいオフセット。

value

設定したい値。

戻り値

値を返しません。

注意

注意:

下記の例のように、もし他の値が利用できなければ、 offset パラメータは null に設定されます。

<?php
$arrayaccess[] = "first value";
$arrayaccess[] = "second value";
print_r($arrayaccess);
?>

上の例の出力は以下となります。

Array
(
    [0] => first value
    [1] => second value
)

注意:

この関数は、参照による代入の場合にはコールされません。また、 ArrayAccess でオーバーロードした配列の次元への間接的な変更 (間接的な変更とは、その次元を直接変更するのではなく 下位の次元やプロパティを変更したり、配列の次元を別の変数に参照で代入したりすることです) の場合にもコールされません。これらの場合は、かわりに ArrayAccess::offsetGet() がコールされます。 この操作が成功するのはメソッドが参照を返せるようになっているときだけです。


オフセットの設定を解除する

  • ≪ ArrayAccess::offsetSet
  • Serializable ≫
  • PHP Manual
  • ArrayAccess
  • オフセットの設定を解除する

ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — オフセットの設定を解除する

説明

public ArrayAccess::offsetUnset(mixed $offset): void

オフセットの設定を解除します。

注意:

このメソッドは、 (unset) による型キャストの際にはコール されません。

パラメータ

offset

設定解除したいオフセット。

戻り値

値を返しません。


Serializable インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

独自のシリアライズ用のインターフェイスです。

このインターフェイスを実装したクラスは
__sleep() や
__wakeup() をサポートしなくなります。
シリアライズが必要な場合には、自動的に serialize メソッドがコールされます。
このメソッドは __destruct() を実行しません。また、
メソッド内で明示的に書かない限りは一切の副作用を及ぼしません。
アンシリアライズされるときにはそのクラスが自動的に検知し、__construct()
メソッドのかわりに適切な unserialize() メソッドがコールされます。
標準のコンストラクタを実行させたい場合は、unserialize() メソッドの中でそれをコールします。

警告

PHP 8.1.0 以降は、 __serialize() と __unserialize() がない状態で Serializable を実装したクラスに対しては、推奨されない警告が発生します。

インターフェイス概要

interface Serializable {
/* メソッド */
public serialize(): ?string
public unserialize(string $data): void
}

例

例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 — オブジェクトの文字列表現
  • Serializable::unserialize — オブジェクトを作成する


オブジェクトの文字列表現

  • ≪ Serializable
  • Serializable::unserialize ≫
  • PHP Manual
  • Serializable
  • オブジェクトの文字列表現

Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — オブジェクトの文字列表現

説明

public Serializable::serialize(): ?string

オブジェクトを文字列であらわしたものを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトの文字列表現、あるいは null を返します。

エラー / 例外

文字列や null 以外の型を返すときに Exception をスローします。

参考

  • __sleep()
  • __serialize()


オブジェクトを作成する

  • ≪ Serializable::serialize
  • Closure ≫
  • PHP Manual
  • Serializable
  • オブジェクトを作成する

Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — オブジェクトを作成する

説明

public Serializable::unserialize(string $data): void

オブジェクトのアンシリアライズ時にコールされます。

注意:

このメソッドは、オブジェクトの コンストラクタ として働きます。 このメソッドの後に __construct() メソッドがコールされることは ありません。

パラメータ

data

オブジェクトの文字列表現。

戻り値

このメソッドの戻り値は無視されます。

参考

  • __wakeup()
  • __unserialize()


Closure クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

無名関数 を表すために使うクラスです。

無名関数は、Closure 型のオブジェクトを生成します。 このクラスにはメソッドが用意され、 生成した無名関数をさらにコントロールできるようになっています。

ここであげたメソッド以外にも、このクラスには __invoke メソッドが存在します。 これは、マジックメソッド __invoke() を実装した他のクラスとの一貫性を保つためのものであり、 関数をコールするときにこのメソッドは使われません。

クラス概要

final class Closure {
/* メソッド */
private __construct()
public static bind(Closure $closure, ?object $newThis, object|string|null $newScope = "static"): ?Closure
public bindTo(?object $newThis, object|string|null $newScope = "static"): ?Closure
public call(object $newThis, mixed ...$args): mixed
public static fromCallable(callable $callback): Closure
}

目次

  • Closure::__construct — インスタンス作成を無効化したコンストラクタ
  • Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する
  • Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する
  • Closure::call — クロージャを束縛して呼び出す
  • Closure::fromCallable — callable をクロージャに変換する


インスタンス作成を無効化したコンストラクタ

  • ≪ Closure
  • Closure::bind ≫
  • PHP Manual
  • Closure
  • インスタンス作成を無効化したコンストラクタ

Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — インスタンス作成を無効化したコンストラクタ

説明

private Closure::__construct()

このメソッドは、 Closure クラスのインスタンスを作れないようにするために存在します。 このクラスのオブジェクトを作るには、 無名関数 のページに書かれている手順を使います。

パラメータ

この関数にはパラメータはありません。

参考

  • 無名関数


バインドされたオブジェクトとクラスのスコープでクロージャを複製する

  • ≪ Closure::__construct
  • Closure::bindTo ≫
  • PHP Manual
  • Closure
  • バインドされたオブジェクトとクラスのスコープでクロージャを複製する

Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する

説明

public static Closure::bind(Closure $closure, ?object $newThis, object|string|null $newScope = "static"): ?Closure

このメソッドは、staticメソッド版の Closure::bindTo() です。 詳細な説明は Closure::bindTo() のドキュメントを参照ください。

パラメータ

closure

バインドする無名関数。

newThis

指定した無名関数をバインドするオブジェクト。クロージャのバインドを解除するには null を指定します。

newScope

クロージャを関連づけるクラススコープ、あるいは 'static' で現在のスコープを維持します。 オブジェクトを渡した場合は、そのオブジェクトの型をその代わりに使います。 これは、バインドしたオブジェクトの protected メソッドや private メソッドのアクセス権を決めます。 このパラメータに、内部クラスのオブジェクトを渡すことはできません。

戻り値

新しい Closure オブジェクトを返します。 失敗した場合は null を返します。

例

例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() - 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する


新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

  • ≪ Closure::bind
  • Closure::call ≫
  • PHP Manual
  • Closure
  • 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

説明

public Closure::bindTo(?object $newThis, object|string|null $newScope = "static"): ?Closure

自身と同じ本体とバインド変数を持つ新しい 無名関数 を作って返します。しかし、バインドするオブジェクトは変わって新しいクラスのスコープとなります。

"バインドするオブジェクト" によって、$this が関数本体で持つ値が決まり、"クラスのスコープ" は、無名関数からどのクラスの private メンバーや protected メンバーにアクセスできるのかが決まります。 すなわち、無名関数から見えるメンバーは、 その無名関数が newScope クラスのメソッドであった場合と同じものになります。

static なクロージャは何もオブジェクトをバインドできません (newThis の値は null でなければなりません) が、 それでもこの関数を使ってクラスのスコープを変えることができます。

この関数が static でないクロージャに関して保証するのは、 バインドされたインスタンスを持っていればスコープ内にあるということです。 また、その逆も成り立ちます。そのため、static でないクロージャにスコープとして null インスタンスを渡すとそれはstaticとなり、staticでなくスコープにもないクロージャに null でないインスタンスを渡すと、特定されていない何らかのクラスのスコープに入ります。

注意:

単に無名関数を複製したいだけの場合は、 cloning を使うこともできます。

パラメータ

newThis

指定した無名関数をバインドするオブジェクト。クロージャのバインドを解除するには null を指定します。

newScope

クロージャを関連づけるクラススコープ、あるいは 'static' で現在のスコープを維持します。 オブジェクトを渡した場合は、そのオブジェクトの型をその代わりに使います。 これは、バインドしたオブジェクトの protected メソッドや private メソッドのアクセス権を決めます。 内部クラス (のオブジェクト) を をパラメータとして渡すことはできません。

戻り値

新しい Closure オブジェクトを返します。 失敗した場合に null を返します。

例

例1 Closure::bindTo() の例

<?php

class A
{
private $val;

public function __construct($val)
{
$this->val = $val;
}

public 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::bind() - バインドされたオブジェクトとクラスのスコープでクロージャを複製する


クロージャを束縛して呼び出す

  • ≪ Closure::bindTo
  • Closure::fromCallable ≫
  • PHP Manual
  • Closure
  • クロージャを束縛して呼び出す

Closure::call

(PHP 7, PHP 8)

Closure::call — クロージャを束縛して呼び出す

説明

public Closure::call(object $newThis, mixed ...$args): mixed

クロージャを一時的に newThis に束縛し、 指定したパラメータでそれを呼び出します。

パラメータ

newThis

この呼び出しの間だけクロージャを束縛するオブジェクト。

args

クロージャに渡すパラメータがある場合は、ここで指定します。

戻り値

クロージャの戻り値を返します。

例

例1 Closure::call() の例

<?php
class Value {
protected $value;

public function __construct($value) {
$this->value = $value;
}

public function getValue() {
return $this->value;
}
}

$three = new Value(3);
$four = new Value(4);

$closure = function ($delta) { var_dump($this->getValue() + $delta); };
$closure->call($three, 4);
$closure->call($four, 4);
?>

上の例の出力は以下となります。

int(7)
int(8)


callable をクロージャに変換する

  • ≪ Closure::call
  • stdClass ≫
  • PHP Manual
  • Closure
  • callable をクロージャに変換する

Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — callable をクロージャに変換する

説明

public static Closure::fromCallable(callable $callback): Closure

現在のスコープを用いて、指定された callback から新しい 無名関数 を作って返します。 このメソッドは、現在のスコープで callback が呼び出し可能かどうかをチェックし、可能でなければ TypeError をスローします。

注意:

PHP 8.1.0 以降では、このメソッドと同等の機能を実現するやり方として、第一級callableを生成する記法 があります。

パラメータ

callback

変換する callable。

戻り値

新しく作られた Closure を返します。 callback が現在のスコープで呼び出し可能でなければ、 TypeError をスローします。

参考

  • 無名関数
  • 第一級callableを生成する記法


stdClass クラス

(PHP 4, PHP 5, PHP 7, PHP 8)

はじめに

動的なプロパティが使える、汎用的な空のクラスです。

このクラスのインスタンスは、 new 演算子や、 オブジェクトへの型変換 によって作成できます。 PHP の関数によっては、このクラスのインスタンスを返すものがあります。 たとえば json_decode(), mysqli_fetch_object(), PDOStatement::fetchObject() が挙げられます。

マジックメソッド __get()/__set() を実装しているかどうかに関わらず、 このクラスでは動的なプロパティが許可されています。 よって、#[\AllowDynamicProperties] アトリビュートは必要ありません。

PHP には全てのクラスの親となる基底クラスの概念がないため、 このクラスは基底クラスではありません。 ただ、stdClass を継承させることで、 動的なプロパティの機能を持ったカスタムクラスを結果的に作ることはできます。

クラス概要

class stdClass {
}

このクラスは、メソッドやデフォルトのプロパティを持っていません。

例

例1 オブジェクトへの型変換を使い、stdClass を作る

<?php
$obj = (object) array('foo' => 'bar');
var_dump($obj);

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["foo"]=>
  string(3) "bar"
}

例2 json_decode() によって、stdClass を作る

<?php
$json = '{"foo":"bar"}';
var_dump(json_decode($json));

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["foo"]=>
  string(3) "bar"
}

例3 動的にプロパティを宣言する

<?php
$obj = new stdClass();
$obj->foo = 42;
$obj->{1} = 42;
var_dump($obj);

上の例の出力は以下となります。

object(stdClass)#1 (2) {
  ["foo"]=>
  int(42)
  ["1"]=>
  int(42)
}


Generator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

Generator は ジェネレータ が返すオブジェクトです。

警告

Generator オブジェクトのインスタンスは new では作れません。

クラス概要

final class Generator implements Iterator {
/* メソッド */
public current(): mixed
public getReturn(): mixed
public key(): mixed
public next(): void
public rewind(): void
public send(mixed $value): mixed
public throw(Throwable $exception): mixed
public valid(): bool
public __wakeup(): void
}

参考

オブジェクトの反復処理 も参照ください。

目次

  • Generator::current — yield した値を取得する
  • Generator::getReturn — ジェネレータの戻り値を取得する
  • Generator::key — yield したキーを取得する
  • Generator::next — ジェネレータを続行する
  • Generator::rewind — イテレータを巻き戻す
  • Generator::send — 値をジェネレータに送る
  • Generator::throw — 例外をジェネレータにスローする
  • Generator::valid — イテレータが終了したかどうかを調べる
  • Generator::__wakeup — シリアライズのコールバック


yield した値を取得する

  • ≪ Generator
  • Generator::getReturn ≫
  • PHP Manual
  • Generator
  • yield した値を取得する

Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — yield した値を取得する

説明

public Generator::current(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

yield した値を返します。


ジェネレータの戻り値を取得する

  • ≪ Generator::current
  • Generator::key ≫
  • PHP Manual
  • Generator
  • ジェネレータの戻り値を取得する

Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — ジェネレータの戻り値を取得する

説明

public Generator::getReturn(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

ジェネレータの実行が終了すると、その戻り値を返します。

例

例1 Generator::getReturn() の例

<?php

$gen = (function() {
yield 1;
yield 2;

return 3;
})();

foreach ($gen as $val) {
echo $val, PHP_EOL;
}

echo $gen->getReturn(), PHP_EOL;

上の例の出力は以下となります。

1
2
3


yield したキーを取得する

  • ≪ Generator::getReturn
  • Generator::next ≫
  • PHP Manual
  • Generator
  • yield したキーを取得する

Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — yield したキーを取得する

説明

public Generator::key(): mixed

yield した値のキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

yield したキーを返します。

例

例1 Generator::key() の例

<?php

function Gen()
{
yield 'key' => 'value';
}

$gen = Gen();

echo "{$gen->key()} => {$gen->current()}";

上の例の出力は以下となります。

key => value


ジェネレータを続行する

  • ≪ Generator::key
  • Generator::rewind ≫
  • PHP Manual
  • Generator
  • ジェネレータを続行する

Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — ジェネレータを続行する

説明

public Generator::next(): void

Generator::next() のコールは、 null を引数として Generator::send() をコールすることと同じ効果があります。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


イテレータを巻き戻す

  • ≪ Generator::next
  • Generator::send ≫
  • PHP Manual
  • Generator
  • イテレータを巻き戻す

Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — イテレータを巻き戻す

説明

public Generator::rewind(): void

既に処理が始まっている場合は、例外をスローします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


値をジェネレータに送る

  • ≪ Generator::rewind
  • Generator::throw ≫
  • PHP Manual
  • Generator
  • 値をジェネレータに送る

Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — 値をジェネレータに送る

説明

public Generator::send(mixed $value): mixed

指定した値を yield の結果としてジェネレータに送り、ジェネレータを続行します。

ジェネレータが yield 式を指していないときにこのメソッドが呼ばれると、 まずは最初の yield 式まで進めてから値を送信します。そのため、 最初のジェネレータを指すためにわざわざ Generator::next() を呼ぶ必要はありません (Python と同じです)。

パラメータ

value

ジェネレータに送り込む値。この値が、ジェネレータが現在指している yield 式の戻り値になります。

戻り値

yield した値を返します。

例

例1 Generator::send() による値の注入

<?php
function printer() {
echo "I'm printer!".PHP_EOL;
while (true) {
$string = yield;
echo $string.PHP_EOL;
}
}

$printer = printer();
$printer->send('Hello world!');
$printer->send('Bye world!');
?>

上の例の出力は以下となります。

I'm printer!
Hello world!
Bye world!


例外をジェネレータにスローする

  • ≪ Generator::send
  • Generator::valid ≫
  • PHP Manual
  • Generator
  • 例外をジェネレータにスローする

Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — 例外をジェネレータにスローする

説明

public Generator::throw(Throwable $exception): mixed

例外をジェネレータにスローして、ジェネレータを続行します。 この振る舞いは、現在の yield 式の部分を throw $exception 文に置き換えたのと同じになります。

このメソッドの起動時に既にジェネレータが閉じられている場合は、呼び出し側のコンテキストに例外がスローされます。

パラメータ

exception

ジェネレータにスローする例外。

戻り値

yield した値を返します。

例

例1 ジェネレータへの例外のスロー

<?php
function gen() {
echo "Foo\n";
try {
yield;
} catch (Exception $e) {
echo "Exception: {$e->getMessage()}\n";
}
echo "Bar\n";
}

$gen = gen();
$gen->rewind();
$gen->throw(new Exception('Test'));
?>

上の例の出力は以下となります。

Foo
Exception: Test
Bar


イテレータが終了したかどうかを調べる

  • ≪ Generator::throw
  • Generator::__wakeup ≫
  • PHP Manual
  • Generator
  • イテレータが終了したかどうかを調べる

Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — イテレータが終了したかどうかを調べる

説明

public Generator::valid(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータが終了した場合に false を返します。まだ終了していない場合は true を返します。


シリアライズのコールバック

  • ≪ Generator::valid
  • Fiber ≫
  • PHP Manual
  • Generator
  • シリアライズのコールバック

Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — シリアライズのコールバック

説明

public Generator::__wakeup(): void

ジェネレータはシリアライズできないので、例外をスローします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Fiber クラス

(PHP 8 >= 8.1.0)

はじめに

ファイバー(Fiber) は 完全なスタックを持つ、停止可能な関数です。 ファイバー はコールスタック中のどこからでも停止することができますし、 後に再開されるまで実行を停止したままにできます。

クラス概要

final class Fiber {
/* メソッド */
public __construct(callable $callback)
public start(mixed ...$args): mixed
public resume(mixed $value = null): mixed
public throw(Throwable $exception): mixed
public getReturn(): mixed
public isStarted(): bool
public isSuspended(): bool
public isRunning(): bool
public isTerminated(): bool
public static suspend(mixed $value = null): mixed
public static getCurrent(): ?Fiber
}

参考

ファイバーの概要

目次

  • Fiber::__construct — 新しいファイバーのインスタンスを構築する
  • Fiber::start — ファイバーの実行を開始する
  • Fiber::resume — 値を渡して、ファイバーの実行を再開させる
  • Fiber::throw — ファイバーの実行を、例外をスローすることで再開する
  • Fiber::getReturn — ファイバーが返した値を取得する
  • Fiber::isStarted — ファイバーが開始したかどうかを調べる
  • Fiber::isSuspended — ファイバーが停止中かどうかを調べる
  • Fiber::isRunning — ファイバーが実行中かどうかを調べる
  • Fiber::isTerminated — ファイバーが終了しているかを調べる
  • Fiber::suspend — 現在実行中のファイバーを停止する
  • Fiber::getCurrent — 現在実行中のファイバーのインスタンスを取得する


新しいファイバーのインスタンスを構築する

  • ≪ Fiber
  • Fiber::start ≫
  • PHP Manual
  • Fiber
  • 新しいファイバーのインスタンスを構築する

Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — 新しいファイバーのインスタンスを構築する

説明

public Fiber::__construct(callable $callback)

パラメータ

callback

ファイバーを開始する時の callable を指定します。 Fiber::start() に引数を指定することで、 ここで指定する callable に引数を与えます。


ファイバーの実行を開始する

  • ≪ Fiber::__construct
  • Fiber::resume ≫
  • PHP Manual
  • Fiber
  • ファイバーの実行を開始する

Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — ファイバーの実行を開始する

説明

public Fiber::start(mixed ...$args): mixed

ファイバーを構築する際に使われる callable に対して、可変長引数を指定します。

このメソッドをコールした時点で ファイバーが既に開始されている場合、 FiberError がスローされます。

パラメータ

args

ファイバーのコンストラクタに指定する callable を呼び出す際に、 使用する引数。

戻り値

Fiber::suspend() が最初にコールされた際に指定した値を返します。 ファイバーから制御が戻った場合は null を返します。 停止する前に ファイバーが例外をスローする場合、 このメソッドの呼び出しからスローされます。


値を渡して、ファイバーの実行を再開させる

  • ≪ Fiber::start
  • Fiber::throw ≫
  • PHP Manual
  • Fiber
  • 値を渡して、ファイバーの実行を再開させる

Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — 値を渡して、ファイバーの実行を再開させる

説明

public Fiber::resume(mixed $value = null): mixed

現在の Fiber::suspend() の呼び出し結果として、指定した値を渡すことでファイバーを再開します。

このメソッドがコールされた時点で ファイバーが停止していない場合、 FiberError がスローされます。

パラメータ

value

ファイバーの実行を再開するための値。 この値は、 現在の Fiber::suspend() からの戻り値となります。

戻り値

Fiber::suspend() が次回コールされた際に指定した値を返します。 ファイバーから制御が戻った場合は null を返します。 停止する前に ファイバーが例外をスローする場合、 このメソッドの呼び出しからスローされます。


ファイバーの実行を、例外をスローすることで再開する

  • ≪ Fiber::resume
  • Fiber::getReturn ≫
  • PHP Manual
  • Fiber
  • ファイバーの実行を、例外をスローすることで再開する

Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — ファイバーの実行を、例外をスローすることで再開する

説明

public Fiber::throw(Throwable $exception): mixed

現在の Fiber::suspend() への呼び出しから、 指定した例外をスローさせることでファイバーを再開させます。

このメソッドがコールされた時点でファイバーが停止していない場合、 FiberError がスローされます。

パラメータ

exception

現在の Fiber::suspend() への呼び出しから、 ファイバーにスローする例外を指定します。

戻り値

Fiber::suspend() が次回コールされた際に指定した値を返します。 ファイバーから制御が戻った場合は null を返します。 停止する前にファイバーが例外をスローする場合、 このメソッドの呼び出しからスローされます。


ファイバーが返した値を取得する

  • ≪ Fiber::throw
  • Fiber::isStarted ≫
  • PHP Manual
  • Fiber
  • ファイバーが返した値を取得する

Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — ファイバーが返した値を取得する

説明

public Fiber::getReturn(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Fiber::__construct() に指定した callable が返した値を返します。 ファイバーが値を返さなかった場合、 ファイバーそのものが開始されていないか、 終了していないか、例外をスローしている場合で、 それらの場合は FiberError がスローされます。


ファイバーが開始したかどうかを調べる

  • ≪ Fiber::getReturn
  • Fiber::isSuspended ≫
  • PHP Manual
  • Fiber
  • ファイバーが開始したかどうかを調べる

Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — ファイバーが開始したかどうかを調べる

説明

public Fiber::isStarted(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

ファイバーが既に開始した後にのみ、 true を返します。 そうでない場合、false を返します。


ファイバーが停止中かどうかを調べる

  • ≪ Fiber::isStarted
  • Fiber::isRunning ≫
  • PHP Manual
  • Fiber
  • ファイバーが停止中かどうかを調べる

Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — ファイバーが停止中かどうかを調べる

説明

public Fiber::isSuspended(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

ファイバーが現在停止中の場合に true を返します。 そうでない場合、false を返します。


ファイバーが実行中かどうかを調べる

  • ≪ Fiber::isSuspended
  • Fiber::isTerminated ≫
  • PHP Manual
  • Fiber
  • ファイバーが実行中かどうかを調べる

Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — ファイバーが実行中かどうかを調べる

説明

public Fiber::isRunning(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

ファイバーが実行中の場合にのみ true を返します。 Fiber::start(), Fiber::resume(), Fiber::throw() のいずれかがコールされた (但し、Fiber::throw の場合は、まだ制御が戻っていない場合に限る) 後、 ファイバーは実行中と見なされます。 ファイバーが実行中でない場合、false を返します。


ファイバーが終了しているかを調べる

  • ≪ Fiber::isRunning
  • Fiber::suspend ≫
  • PHP Manual
  • Fiber
  • ファイバーが終了しているかを調べる

Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — ファイバーが終了しているかを調べる

説明

public Fiber::isTerminated(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

ファイバーが終了した後にのみ、true を返します。 値を返したか、例外をスローした場合のいずれかに限ります。 そうでない場合、false を返します。


現在実行中のファイバーを停止する

  • ≪ Fiber::isTerminated
  • Fiber::getCurrent ≫
  • PHP Manual
  • Fiber
  • 現在実行中のファイバーを停止する

Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — 現在実行中のファイバーを停止する

説明

public static Fiber::suspend(mixed $value = null): mixed

現在実行中のファイバーを停止します。 このメソッドに渡した値が、 Fiber::start(), Fiber::resume(), Fiber::throw() から返されます。 但し、Fiber::throw() は 実行の制御が現在のファイバーに移った場合に限ります。

ファイバーの実行が再開されると、 このメソッドは Fiber::resume() に渡された値を返します。 ファイバーの実行が Fiber::throw() を使って再開された場合、 そのメソッドに渡された例外が、 このメソッドの呼び出しからスローされます。

このメソッドがファイバーの外部からコールされた場合、 FiberError がスローされます。

パラメータ

value

Fiber::start(),
Fiber::resume(),
Fiber::throw() を呼び出した際に返される値。
 但し、Fiber::throw()
 は 実行の制御が現在のファイバーに移った場合に限ります。

戻り値

Fiber::resume() に渡された値を返します。


現在実行中のファイバーのインスタンスを取得する

  • ≪ Fiber::suspend
  • WeakReference ≫
  • PHP Manual
  • Fiber
  • 現在実行中のファイバーのインスタンスを取得する

Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — 現在実行中のファイバーのインスタンスを取得する

説明

public static Fiber::getCurrent(): ?Fiber

パラメータ

この関数にはパラメータはありません。

戻り値

現在実行中の Fiber のインスタンスを返します。 このメソッドがファイバーの外から実行された場合は null を返します。


WeakReference クラス

(PHP 7 >= 7.4.0, PHP 8)

はじめに

弱い参照により、オブジェクトが破棄されるのを妨げないオブジェクトへの参照を保持することが可能です。 この機能は、キャッシュのようなデータ構造を実装するのに役立ちます。

WeakReference クラスはシリアライズできません。

クラス概要

final class WeakReference {
/* メソッド */
public __construct()
public static create(object $object): WeakReference
public get(): ?object
}

WeakReference の例

例1 基本的な WeakReference クラスの使い方

<?php
$obj = new stdClass;
$weakref = WeakReference::create($obj);
var_dump($weakref->get());
unset($obj);
var_dump($weakref->get());
?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#1 (0) {
}
NULL

目次

  • WeakReference::__construct — コンストラクタを使ってインスタンス化はできません
  • WeakReference::create — 弱い参照を生成する
  • WeakReference::get — 弱く参照されたオブジェクトを取得する


コンストラクタを使ってインスタンス化はできません

  • ≪ WeakReference
  • WeakReference::create ≫
  • PHP Manual
  • WeakReference
  • コンストラクタを使ってインスタンス化はできません

WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — コンストラクタを使ってインスタンス化はできません

説明

public WeakReference::__construct()

このメソッドは、WeakReference クラスの インスタンス化を禁止するためだけに存在しています。 WeakReference は、 ファクトリメソッド WeakReference::create() を使ってインスタンス化されることになっています。

パラメータ

この関数にはパラメータはありません。

参考

  • WeakReference::create() - 弱い参照を生成する


弱い参照を生成する

  • ≪ WeakReference::__construct
  • WeakReference::get ≫
  • PHP Manual
  • WeakReference
  • 弱い参照を生成する

WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — 弱い参照を生成する

説明

public static WeakReference::create(object $object): WeakReference

新しい WeakReference を生成します

パラメータ

object

このオブジェクトは、弱く参照されます。

戻り値

新しい WeakReference を返します。 既に同じオブジェクトに対する WeakReference のインスタンスが存在する場合は、それを返します。


弱く参照されたオブジェクトを取得する

  • ≪ WeakReference::create
  • WeakMap ≫
  • PHP Manual
  • WeakReference
  • 弱く参照されたオブジェクトを取得する

WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — 弱く参照されたオブジェクトを取得する

説明

public WeakReference::get(): ?object

弱く参照されたオブジェクトを取得します。 既にオブジェクトが破棄されていた場合、null が返されます。

パラメータ

この関数にはパラメータはありません。

戻り値

参照されている object を返します。 オブジェクトが破棄されている場合は、null を返します。


WeakMap クラス

(PHP 8)

はじめに

WeakMap は、 オブジェクトをキーとして受け入れるマップ(辞書)です。 SplObjectStorage と似ていますが、 WeakMap のキーとなるオブジェクトは、 オブジェクトのリファレンスカウントが更新されません。 つまり、WeakMap のキーとなっているオブジェクトだけが唯一の残された参照だった場合、 オブジェクトはガベージコレクションの対象となり WeakMap から削除されます。 WeakMap の用途は、 長く生き残る必要がないオブジェクトから派生した、 データのキャッシュを作ることです。

WeakMap は ArrayAccess, Traversable (IteratorAggregate 経由), Countable を実装しています。 よって、ほとんどのケースで、 連想配列と同じやり方で操作できます。

クラス概要

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* メソッド */
public count(): int
public getIterator(): Iterator
public offsetExists(object $object): bool
public offsetGet(object $object): mixed
public offsetSet(object $object, mixed $value): void
public offsetUnset(object $object): void
}

例

例1 Weakmap の使い方の例

<?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::count — マップ内に存在する有効なエントリの数を数える
  • WeakMap::getIterator — イテレータを取得する
  • WeakMap::offsetExists — あるオブジェクトがマップ内に存在するかを調べる
  • WeakMap::offsetGet — オブジェクトが指す値を返す
  • WeakMap::offsetSet — 新しいキーと値でマップを更新する
  • WeakMap::offsetUnset — マップからエントリを削除する


マップ内に存在する有効なエントリの数を数える

  • ≪ WeakMap
  • WeakMap::getIterator ≫
  • PHP Manual
  • WeakMap
  • マップ内に存在する有効なエントリの数を数える

WeakMap::count

(PHP 8)

WeakMap::count — マップ内に存在する有効なエントリの数を数える

説明

public WeakMap::count(): int

マップ内の有効なエントリの数を数えます。

パラメータ

この関数にはパラメータはありません。

戻り値

マップ内の有効なエントリの数を返します。


イテレータを取得する

  • ≪ WeakMap::count
  • WeakMap::offsetExists ≫
  • PHP Manual
  • WeakMap
  • イテレータを取得する

WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — イテレータを取得する

説明

public WeakMap::getIterator(): Iterator

イテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Iterator または Traversable を実装したオブジェクトのインスタンスを返します。

エラー / 例外

失敗した場合は Exception をスローします。


あるオブジェクトがマップ内に存在するかを調べる

  • ≪ WeakMap::getIterator
  • WeakMap::offsetGet ≫
  • PHP Manual
  • WeakMap
  • あるオブジェクトがマップ内に存在するかを調べる

WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — あるオブジェクトがマップ内に存在するかを調べる

説明

public WeakMap::offsetExists(object $object): bool

指定されたオブジェクトが、マップ内で参照されているかを調べます。

パラメータ

object

チェックするオブジェクト

戻り値

オブジェクトがマップ内に含まれている場合、true を返します。 そうでない場合、false を返します。


オブジェクトが指す値を返す

  • ≪ WeakMap::offsetExists
  • WeakMap::offsetSet ≫
  • PHP Manual
  • WeakMap
  • オブジェクトが指す値を返す

WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — オブジェクトが指す値を返す

説明

public WeakMap::offsetGet(object $object): mixed

指定されたオブジェクトが指す値を返します。

パラメータ

object

マップにキーとして含まれるオブジェクト

戻り値

引数で渡されたオブジェクトに関連付けられた値を返します。

エラー / 例外

失敗した場合、Error をスローします。


新しいキーと値でマップを更新する

  • ≪ WeakMap::offsetGet
  • WeakMap::offsetUnset ≫
  • PHP Manual
  • WeakMap
  • 新しいキーと値でマップを更新する

WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — 新しいキーと値でマップを更新する

説明

public WeakMap::offsetSet(object $object, mixed $value): void

新しいキーと値でマップを更新します。 既にキーがマップに存在した場合、古い値は新しい値で置き換えられます。

パラメータ

object

キーと値のペアを構成する、キーとなるオブジェクト

value

キーと値のペアのうち、値となる任意のデータ

戻り値

値を返しません。


マップからエントリを削除する

  • ≪ WeakMap::offsetSet
  • Stringable ≫
  • PHP Manual
  • WeakMap
  • マップからエントリを削除する

WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — マップからエントリを削除する

説明

public WeakMap::offsetUnset(object $object): void

マップからエントリを削除します。

パラメータ

object

マップから削除するオブジェクト

戻り値

値を返しません。


Stringable インターフェイス

(PHP 8)

はじめに

Stringable インターフェイスは、 特定のクラスが __toString() メソッドを実装していることを示します。 ほとんどのインターフェイスと異なり、 Stringable は、マジックメソッド __toString() が定義されているあらゆるクラスで 暗黙のうちに存在すると見なされますが、 明示的に宣言することもできますし、宣言すべきです。

このインターフェイスの一番の存在意義は、 文字列プリミティブや、 文字列にキャストできるオブジェクトを受け入れる union型 string|Stringable に対する型チェックを、関数ができるようにすることです。

インターフェイス概要

interface Stringable {
/* メソッド */
public __toString(): string
}

Stringable インターフェイスの例

例1 基本的な Stringable インターフェイスの使い方

<?php
class IPv4Address implements Stringable {
public function __construct(
private string $oct1,
private string $oct2,
private string $oct3,
private string $oct4,
) {}

public function __toString(): string {
return "$this->oct1.$this->oct2.$this->oct3.$this->oct4";
}
}

function showStuff(string|Stringable $value) {
// Stringable を渡した場合、以下は暗黙のうちに __toString() をコールします。
print $value;
}

$ip = new IPv4Address('123', '234', '42', '9');

showStuff($ip);
?>

上の例の出力は、 たとえば以下のようになります。

123.234.42.9

目次

  • Stringable::__toString — オブジェクトの文字列表現を取得する


オブジェクトの文字列表現を取得する

  • ≪ Stringable
  • UnitEnum ≫
  • PHP Manual
  • Stringable
  • オブジェクトの文字列表現を取得する

Stringable::__toString

(PHP 8)

Stringable::__toString — オブジェクトの文字列表現を取得する

説明

public Stringable::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトの文字列表現を返します。

参考

  • __toString()


UnitEnum インターフェイス

(PHP 8 >= 8.1.0)

はじめに

UnitEnum インターフェイスは、 全ての列挙型に対して、PHP のエンジンが自動的に適用するものです。 ユーザー定義のクラスとして実装してはいけません。 列挙型はメソッドのオーバーライドを禁止しています。 デフォルトの実装は PHP のエンジンから提供されるからです。 このインターフェイスは、型チェックのためだけに存在しています。

インターフェイス概要

interface UnitEnum {
/* メソッド */
public static cases(): array
}

目次

  • UnitEnum::cases — 列挙型の case 一覧を生成する


列挙型の case 一覧を生成する

  • ≪ UnitEnum
  • BackedEnum ≫
  • PHP Manual
  • UnitEnum
  • 列挙型の case 一覧を生成する

UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — 列挙型の case 一覧を生成する

説明

public static UnitEnum::cases(): array

このメソッドは列挙型の全ての case を含む配列を返します。 要素は宣言された順に並びます。

パラメータ

この関数にはパラメータはありません。

戻り値

列挙型で定義されている全ての case を含む配列を返します。 要素は宣言された順に並びます。

例

例1 基本的な使用法

以下の例は、列挙型の case がどのように返されるかを示しています。

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

var_dump(Suit::cases());
?>

上の例の出力は以下となります。

array(4) {
    [0]=>
    enum(Suit::Hearts)
    [1]=>
    enum(Suit::Diamonds)
    [2]=>
    enum(Suit::Clubs)
    [3]=>
    enum(Suit::Spades)
}


BackedEnum インターフェイス

(PHP 8 >= 8.1.0)

はじめに

BackedEnum インターフェイスは、 Backed Enum を定義すると、PHP のエンジンが自動的に適用します。 ユーザー定義のクラスとして実装してはいけません。 列挙型はメソッドのオーバーライドを禁止しています。 デフォルトの実装は PHP のエンジンから提供されるからです。 このインターフェイスは、型チェックのためだけに存在しています。

インターフェイス概要

interface BackedEnum extends UnitEnum {
/* メソッド */
public static from(int|string $value): static
public static tryFrom(int|string $value): ?static
/* 継承したメソッド */
public static UnitEnum::cases(): array
}

目次

  • BackedEnum::from — スカラー型の値を列挙型にマップする
  • BackedEnum::tryFrom — スカラー型の値を列挙型にマップするか、null を返す


スカラー型の値を列挙型にマップする

  • ≪ BackedEnum
  • BackedEnum::tryFrom ≫
  • PHP Manual
  • BackedEnum
  • スカラー型の値を列挙型にマップする

BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — スカラー型の値を列挙型にマップする

説明

public static BackedEnum::from(int|string $value): static

from() メソッドは 文字列型や整数型の値を、存在する場合に 列挙型の case に変換します。 マッチする case が定義されていない場合は、 ValueError がスローされます。

パラメータ

value

列挙型の case にマップするスカラー値。

戻り値

この列挙型の case のインスタンスを返します。

例

例1 基本的な使用法

以下の例は、列挙型の case がどのように返されるかを示しています。

<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}

$h = Suit::from('H');

var_dump($h);

$b = Suit::from('B');
?>

上の例の出力は以下となります。

enum(Suit::Hearts)

Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

参考

  • UnitEnum::cases() - 列挙型の case 一覧を生成する
  • BackedEnum::tryFrom() - スカラー型の値を列挙型にマップするか、null を返す


スカラー型の値を列挙型にマップするか、null を返す

  • ≪ BackedEnum::from
  • SensitiveParameterValue ≫
  • PHP Manual
  • BackedEnum
  • スカラー型の値を列挙型にマップするか、null を返す

BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — スカラー型の値を列挙型にマップするか、null を返す

説明

public static BackedEnum::tryFrom(int|string $value): ?static

tryfrom() メソッドは 文字列型や整数型の値を、存在する場合に 列挙型の case に変換します。 マッチする case が定義されていない場合は、null を返します。

パラメータ

value

列挙型の case にマップするスカラー値。

戻り値

この列挙型の case のインスタンスを返します。 対応する case が見つからない場合は、null を返します。

例

例1 基本的な使用法

以下の例は、列挙型の case がどのように返されるかを示しています。

<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}

$h = Suit::tryFrom('H');

var_dump($h);

$b = Suit::tryFrom('B') ?? Suit::Spades;

var_dump($b);
?>

上の例の出力は以下となります。

enum(Suit::Hearts)
enum(Suit::Spades)

参考

  • UnitEnum::cases() - 列挙型の case 一覧を生成する
  • BackedEnum::from() - スカラー型の値を列挙型にマップする


SensitiveParameterValue クラス

(PHP 8 >= 8.2.0)

はじめに

SensitiveParameterValue クラスを使うと、 秘密の値をうっかり公開してしまうことを防ぐために値をラップすることができます。

SensitiveParameter アトリビュートを持つパラメータに渡される値は、 スタックトレース中では SensitiveParameterValue オブジェクトで自動的にラップされます。

クラス概要

final class SensitiveParameterValue {
/* プロパティ */
private readonly mixed $value;
/* メソッド */
public __construct(mixed $value)
public __debugInfo(): array
public getValue(): mixed
}

プロパティ

value

うっかり公開してしまうことを防ぎたい、秘密の値

目次

  • SensitiveParameterValue::__construct — 新しい SensitiveParameterValue オブジェクトを作成する
  • SensitiveParameterValue::__debugInfo — 秘密の値をうっかり公開することを防止する
  • SensitiveParameterValue::getValue — 秘密の値を返す


新しい SensitiveParameterValue オブジェクトを作成する

  • ≪ SensitiveParameterValue
  • SensitiveParameterValue::__debugInfo ≫
  • PHP Manual
  • SensitiveParameterValue
  • 新しい SensitiveParameterValue オブジェクトを作成する

SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — 新しい SensitiveParameterValue オブジェクトを作成する

説明

public SensitiveParameterValue::__construct(mixed $value)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

value

SensitiveParameterValue オブジェクトの内部に保存すべき、任意の値


秘密の値をうっかり公開することを防止する

  • ≪ SensitiveParameterValue::__construct
  • SensitiveParameterValue::getValue ≫
  • PHP Manual
  • SensitiveParameterValue
  • 秘密の値をうっかり公開することを防止する

SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — 秘密の値をうっかり公開することを防止する

説明

public SensitiveParameterValue::__debugInfo(): array

var_dump() を使った時にうっかり秘密の値を公開しないように、 空の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

空の配列を返します

例

例1 SensitiveParameterValue オブジェクトを var_dump() に渡す

<?php
$s = new \SensitiveParameterValue('secret');

var_dump($s);
?>

上の例の出力は以下となります。

object(SensitiveParameterValue)#1 (0) {
}


秘密の値を返す

  • ≪ SensitiveParameterValue::__debugInfo
  • __PHP_Incomplete_Class ≫
  • PHP Manual
  • SensitiveParameterValue
  • 秘密の値を返す

SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — 秘密の値を返す

説明

public SensitiveParameterValue::getValue(): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

秘密の値を返します。

例

例1 SensitiveParameterValue::getValue() の例

<?php
$s = new \SensitiveParameterValue('secret');

echo "The protected value is: ", $s->getValue(), "\n";
?>

上の例の出力は以下となります。

The protected value is: secret


__PHP_Incomplete_Class クラス

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

未定義のクラスや、 unserialize() の options 配列の allowed_classes のリストに入っていなかったクラスを アンシリアライズしようとした場合に、 unserialize() が生成します。

PHP 7.2.0 より前のバージョンでは、 __PHP_Incomplete_Class に対して is_object() を呼び出すと false を返していました。 PHP 7.2.0 以降では true を返します。

クラス概要

class __PHP_Incomplete_Class {
}

このクラスはデフォルトのプロパティやメソッドを持っていません。 unserialize() がこのクラスを生成した場合、 アンシリアライズされたプロパティやオブジェクトの値について、 アンシリアライズされたクラス名を含む __PHP_Incomplete_Class_Name プロパティを持ちます。

例

例1 unserialize() によって生成されるクラス

<?php

class MyClass
{
public string $property = "myValue";
}

$myObject = new MyClass;

$foo = serialize($myObject);

// unserializes all objects into __PHP_Incomplete_Class objects
$disallowed = unserialize($foo, ["allowed_classes" => false]);

var_dump($disallowed);

// unserializes all objects into __PHP_Incomplete_Class objects except those of MyClass2 and MyClass3
$disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

var_dump($disallowed2);

// unserializes undefined class into __PHP_Incomplete_Class object
$undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

var_dump($undefinedClass);

上の例の出力は以下となります。

object(__PHP_Incomplete_Class)#2 (2) {
  ["__PHP_Incomplete_Class_Name"]=>
  string(7) "MyClass"
  ["property"]=>
  string(7) "myValue"
}
object(__PHP_Incomplete_Class)#3 (2) {
  ["__PHP_Incomplete_Class_Name"]=>
  string(7) "MyClass"
  ["property"]=>
  string(7) "myValue"
}
object(__PHP_Incomplete_Class)#4 (1) {
  ["__PHP_Incomplete_Class_Name"]=>
  string(16) "MyUndefinedClass"
}


定義済みのアトリビュート

目次

  • Attribute
  • AllowDynamicProperties
  • Override
  • ReturnTypeWillChange
  • SensitiveParameter

PHP には、定義済みのアトリビュートがいくつか用意されています。


Attribute クラス

(PHP 8)

はじめに

アトリビュートを使うと、 コンピューターが解析できる構造化されたメタデータの情報を、 コードの宣言時に埋め込むことができます。 つまり、クラス、メソッド、関数、パラメータ、プロパティ、クラス定数にアトリビュートを指定することができます。 アトリビュートで定義されたメタデータは、 実行時に リフレクションAPI を使って調べることが出来ます。 よって、アトリビュートは、 コードに直接埋め込むことが出来る、 設定のための言語とみなすことができます。

クラス概要

final class Attribute {
/* 定数 */
const int TARGET_CLASS;
const int TARGET_FUNCTION;
const int TARGET_METHOD;
const int TARGET_PROPERTY;
const int TARGET_CLASS_CONSTANT;
const int TARGET_PARAMETER;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* プロパティ */
public int $flags;
/* メソッド */
public __construct(int $flags = Attribute::TARGET_ALL)
}

定義済み定数

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

プロパティ

flags

参考

アトリビュートの概要

目次

  • Attribute::__construct — 新しい Attribute のインスタンスを作成する


新しい Attribute のインスタンスを作成する

  • ≪ Attribute
  • AllowDynamicProperties ≫
  • PHP Manual
  • Attribute
  • 新しい Attribute のインスタンスを作成する

Attribute::__construct

(PHP 8)

Attribute::__construct — 新しい Attribute のインスタンスを作成する

説明

public Attribute::__construct(int $flags = Attribute::TARGET_ALL)

新しい Attribute のインスタンスを作成します。

パラメータ

flags


AllowDynamicProperties クラス

(PHP 8 >= 8.2.0)

はじめに

このアトリビュートを使うと、 クラスに 動的なプロパティ を許可することをマークできます。

クラス概要

final class AllowDynamicProperties {
/* メソッド */
public __construct()
}

例

動的なプロパティは、PHP 8.2.0 以降は推奨されなくなりました。 よって、このアトリビュートでクラスをマークせずに、 動的なプロパティを使うと、 推奨されない警告が発生します。

<?php
class DefaultBehaviour { }

#[\AllowDynamicProperties]
class ClassAllowsDynamicProperties { }

$o1 = new DefaultBehaviour();
$o2 = new ClassAllowsDynamicProperties();

$o1->nonExistingProp = true;
$o2->nonExistingProp = true;
?>

上の例の PHP 8.2 での出力は、このようになります。:

Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

参考

アトリビュートの概要

目次

  • AllowDynamicProperties::__construct — 新しい AllowDynamicProperties のインスタンスを作成する


新しい AllowDynamicProperties のインスタンスを作成する

  • ≪ AllowDynamicProperties
  • Override ≫
  • PHP Manual
  • AllowDynamicProperties
  • 新しい AllowDynamicProperties のインスタンスを作成する

AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — 新しい AllowDynamicProperties のインスタンスを作成する

説明

public AllowDynamicProperties::__construct()

新しい AllowDynamicProperties のインスタンスを作成します。

パラメータ

この関数にはパラメータはありません。


Override クラス

(PHP 8 >= 8.3.0)

はじめに

クラス概要

final class Override {
/* メソッド */
public __construct()
}

例

<?php

class Base {
protected function foo(): void {}
}

final class Extended extends Base {
#[\Override]
protected function boo(): void {}
}

?>

上の例の PHP 8.3 での出力は、たとえば以下のようになります。:

Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

参考

  • アトリビュート

目次

  • Override::__construct — 新しいOverrideアトリビュートのインスタンスを作成する


新しいOverrideアトリビュートのインスタンスを作成する

  • ≪ Override
  • ReturnTypeWillChange ≫
  • PHP Manual
  • Override
  • 新しいOverrideアトリビュートのインスタンスを作成する

Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — 新しいOverrideアトリビュートのインスタンスを作成する

説明

public Override::__construct()

新しい Override のインスタンスを構築します。

パラメータ

この関数にはパラメータはありません。


ReturnTypeWillChange クラス

(PHP 8 >= 8.1.0)

はじめに

ほとんどの final でない内部メソッドは、 それをオーバライドする際、 互換性がある戻り値の型を宣言することが必須になっています。 そうしない場合、継承が有効かを検証する際に、 推奨されない警告が発生します。 PHP のバージョン間の互換性を保ちたいがために、 戻り値の型を宣言できない場合、 アトリビュート #[\ReturnTypeWillChange] を追加することで警告を抑止できます。

クラス概要

final class ReturnTypeWillChange {
/* メソッド */
public __construct()
}

参考

アトリビュートの概要

目次

  • ReturnTypeWillChange::__construct — 新しい ReturnTypeWillChange のインスタンスを作成する


新しい ReturnTypeWillChange のインスタンスを作成する

  • ≪ ReturnTypeWillChange
  • SensitiveParameter ≫
  • PHP Manual
  • ReturnTypeWillChange
  • 新しい ReturnTypeWillChange のインスタンスを作成する

ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — 新しい ReturnTypeWillChange のインスタンスを作成する

説明

public ReturnTypeWillChange::__construct()

新しい ReturnTypeWillChange のインスタンスを作成します。

パラメータ

この関数にはパラメータはありません。


SensitiveParameter クラス

(PHP 8 >= 8.2.0)

はじめに

このアトリビュートを使うと、スタックトレース中に現れた場合に、 値を削除すべき秘密の値としてパラメータをマークできます。

クラス概要

final class SensitiveParameter {
/* メソッド */
public __construct()
}

例

<?php

function defaultBehavior(
string $secret,
string $normal
) {
throw new Exception('Error!');
}

function sensitiveParametersWithAttribute(
#[\SensitiveParameter]
string $secret,
string $normal
) {
throw new Exception('Error!');
}

try {
defaultBehavior('password', 'normal');
} catch (Exception $e) {
echo $e, PHP_EOL, PHP_EOL;
}

try {
sensitiveParametersWithAttribute('password', 'normal');
} catch (Exception $e) {
echo $e, PHP_EOL, PHP_EOL;
}

?>

上の例の PHP 8.2 での出力は、たとえば以下のようになります。:

Exception: Error! in example.php:7
Stack trace:
#0 example.php(19): defaultBehavior('password', 'normal')
#1 {main}

Exception: Error! in example.php:15
Stack trace:
#0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
#1 {main}

参考

  • アトリビュートの概要
  • SensitiveParameterValue

目次

  • SensitiveParameter::__construct — 新しい SensitiveParameter のインスタンスを作成する


新しい SensitiveParameter のインスタンスを作成する

  • ≪ SensitiveParameter
  • コンテキストオプションとパラメータ ≫
  • PHP Manual
  • SensitiveParameter
  • 新しい SensitiveParameter のインスタンスを作成する

SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — 新しい SensitiveParameter のインスタンスを作成する

説明

public SensitiveParameter::__construct()

新しい SensitiveParameter のインスタンスを作成します。

パラメータ

この関数にはパラメータはありません。


コンテキストオプションとパラメータ

PHP にはさまざまなコンテキストオプションやパラメータがあり、 すべてのファイルシステムラッパーおよびストリームラッパーで使用することができます。 コンテキストの作成は stream_context_create() で行います。オプションの設定は stream_context_set_option() で、そしてパラメータの設定は stream_context_set_params() で行います。

目次

  • ソケットコンテキストオプション — ソケットコンテキストオプション一覧
  • HTTP コンテキストオプション — HTTP コンテキストオプションの一覧
  • FTP コンテキストオプション — FTP コンテキストオプションの一覧
  • SSL コンテキストオプション — SSL コンテキストオプションの一覧
  • Phar コンテキストオプション — Phar コンテキストオプション一覧
  • コンテキストパラメータ — コンテキストパラメータの一覧
  • Zip コンテキストオプション — Zip コンテキストオプション一覧
  • Zlib コンテキストオプション — Zlib コンテキストオプション一覧


ソケットコンテキストオプション一覧

  • ≪ コンテキストオプションとパラメータ
  • HTTP コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • ソケットコンテキストオプション一覧

ソケットコンテキストオプション

ソケットコンテキストオプション — ソケットコンテキストオプション一覧

説明

ここでは、ソケット越しに動作するラッパー すなわち tcp、http あるいは ftp でサポートされるオプションを扱います。

オプション

bindto

PHP がネットワークにアクセスする際の IP アドレス (IPv4 あるいは IPv6 のどちらか）やポート番号を指定する際に使用されます。 書式は、IPv4 アドレスの場合は ip:port、 IPv6 アドレスの場合は [ip]:port です。 IP やポート番号に 0 を指定すると、それをシステムに自動的に設定させる ことができます。

注意:

FTP の通常の操作では 2 つのソケット接続を使用するので、 このオプションでポート番号を指定することができません。

backlog

ソケットのリスンキューから出て行く接続の数を制限します。

注意:

stream_socket_server() でのみ有効です。

ipv6_v6only

IPv4射影アドレスに関する OS のデフォルトを上書きする

注意:

これは、[::] に バインドされたアドレスが存在するときに、 IPv4 アドレス で listen しようとする場合に特に重要です。 上で、

stream_socket_server() でのみ有効です。

so_reuseport

異なるプロセスからであっても、同じ IPアドレス:ポート のペアに 複数 bind することを許可します。

注意:

stream_socket_server() でのみ有効です。

so_broadcast

ブロードキャストアドレスへのデータの送信や、 ブロードキャストアドレスからのデータの受信を有効にします。

注意:

stream_socket_server() でのみ有効です。

tcp_nodelay

このオプションを true にすると、 SOL_TCP,NO_DELAY=1 をそれぞれ設定します。 これによって、TCP の Nagle アルゴリズムを無効にします。

変更履歴

バージョン | 説明
7.1.0 | tcp_nodelay が追加されました。
7.0.1 | ipv6_v6only が追加されました。

例

例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',
),
);

// IPv6 アドレス '2001:db8::1' とポート番号 '7000' でインターネットに接続する
$opts = array(
'socket' => array(
'bindto' => '[2001:db8::1]: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 コンテキストオプションの一覧

  • ≪ ソケットコンテキストオプション
  • FTP コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • HTTP コンテキストオプションの一覧

HTTP コンテキストオプション

HTTP コンテキストオプション — HTTP コンテキストオプションの一覧

説明

http:// および https:// トランスポート用のコンテキストオプションです。

オプション

method string

リモートサーバーでサポートされる GET、 POST あるいはその他の HTTP メソッド。

デフォルトは GET です。

header array あるいは string

リクエストに付加されるヘッダ。ここで指定した値が (User-agent:、Host:、 および Authentication: などの) 他の値を上書きすることもあります。 これは、後にLocation: によってリダイレクトが行われる場合でも同様です。 よって、follow_location が有効になっている場合、 Host: ヘッダを設定することはお勧めしません。

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 bool

true を指定すると、リクエストを生成する際に完全な URI (例: GET http://www.example.com/path/to/file.html HTTP/1.0) が用いられます。これは標準のリクエストフォーマットではありませんが、 このようなフォーマットを要求するプロキシサーバーも存在します。

デフォルトは false です。

follow_location int

Location のリダイレクトをたどります。 0 で無効にできます。

デフォルトは 1 です。

max_redirects int

リダイレクトをたどる最大数。値が 1 以下の場合は リダイレクトをたどらないことを意味します。

デフォルトは 20 です。

protocol_version float

HTTP プロトコルのバージョン。

PHP 8.0.0 以降では、デフォルトは 1.1 です。 それより前のバージョンでは、デフォルトは 1.0 でした。

timeout float

読み込みタイムアウト秒数を float (例 10.5) で指定します。

デフォルトでは php.ini 設定 default_socket_timeout の値を使用します。

ignore_errors bool

ステータスコードが失敗を意味する場合でもコンテンツを取得します。

デフォルトは false です。

例

例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 Permanently',
    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) を取得しました。

参考

  • http://
  • ソケットコンテキストオプション
  • SSL コンテキストオプション


FTP コンテキストオプションの一覧

  • ≪ HTTP コンテキストオプション
  • SSL コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • FTP コンテキストオプションの一覧

FTP コンテキストオプション

FTP コンテキストオプション — FTP コンテキストオプションの一覧

説明

ftp:// および ftps:// トランスポート用のコンテキストオプションです。

オプション

overwrite bool

リモートサーバー上の既存のファイルに対する上書きを許可する。 書き込みモード（アップロード）時のみ有効。

デフォルトは false です。

resume_pos int

転送を開始するファイル内の位置。 読み込みモード（ダウンロード）時のみ有効。

デフォルトは 0 (ファイルの先頭) です。

proxy string

FTP リクエストを、http プロキシサーバー経由で行う。 ファイルの読み込み操作にのみ適用される。 例: tcp://squid.example.com:8000

注意

注意: 基盤となるソケットストリームのコンテキストオプション
これ以外のコンテキストオプションが 基盤となるトランスポート でサポートされています。 ftp:// ストリームの場合は、tcp:// のコンテキストオプションを参照ください。 ftps:// ストリームの場合は、ssl:// のコンテキストオプションを参照ください。

参考

  • ftp://
  • ソケットコンテキストオプション
  • SSL コンテキストオプション


SSL コンテキストオプションの一覧

  • ≪ FTP コンテキストオプション
  • Phar コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • SSL コンテキストオプションの一覧

SSL コンテキストオプション

SSL コンテキストオプション — SSL コンテキストオプションの一覧

説明

ssl:// および tls:// トランスポート用のコンテキストオプションです。

オプション

peer_name string

使用するピア名。省略した場合は、ストリームをオープンしたときに使ったホスト名をもとに、名前を推測します。

verify_peer bool

SSL サーバー証明書の検証を要求するかどうか。

デフォルトは true です。

verify_peer_name bool

ピア名の検証を要求するかどうか。

デフォルトは true です。

allow_self_signed bool

自己証明の証明書を許可するかどうか。 verify_peer が必要です。

デフォルトは false です。

cafile string

ローカルファイルシステム上の証明書ファイルの場所。 verify_peer オプションでリモートサーバーとの 認証の際に使用する。

capath string

cafile が指定されていなかったりその場所にファイルが 見つからなかったりした場合、capath が指す ディレクトリを検索して認証ファイルを探します。capath は認証ファイルのディレクトリを正確に指している必要があります。

local_cert string

ファイルシステム上のローカル証明書ファイルのパス。 あなたの証明書とプライベートキーを含み、PEM エンコードされた ファイルである必要があります。オプションで、発行者の 認証チェーンを含めることも可能です。 プライベートキーは、 local_pk で指定した別のファイルに含めることも可能です。

local_pk string

ローカルファイルシステム上のプライベートキーファイルの場所。 証明書 (local_cert) とプライベートキーを別のファイルに分けたい場合に用います。

passphrase string

local_cert ファイルをエンコードした際の パスフレーズ。

verify_depth int

証明書のチェインが深すぎる場合に終了するかどうか。

デフォルトでは検証を行いません。

ciphers string

使用可能な暗号化方式の一覧を設定します。設定できるフォーマットは » ciphers(1) の説明を参照ください。

デフォルトは DEFAULT です。

capture_peer_cert bool

true に設定すると、peer_certificate コンテキストオプションがピア証明書を含んで作成されます。

capture_peer_cert_chain bool

true に設定すると、peer_certificate_chain コンテキストオプションが証明書チェインを含んで作成されます。

SNI_enabled bool

true に設定すると、サーバー名の表示 (SNI) が有効になります。 これを有効にすると、同じ IP アドレスで複数の証明書を使えるようになります。

disable_compression bool

設定すると、TLS 圧縮を無効にします。これは、CRIME アタックベクターを軽減するのに役立ちます。

peer_fingerprint string | array

リモート証明書のダイジェストが指定したハッシュに一致しない場合に、異常終了させます。

string を指定する場合は、その長さでハッシュアルゴリズムを判断します。 "md5" (32) あるいは "sha1" (40) のいずれかです。

array を指定する場合は、キーがハッシュアルゴリズムで、 それに対応する値がダイジェストとなります。

security_level int

セキュリティレベルを設定します。 指定されない場合、ライブラリのデフォルトのセキュリティレベルが使われます。 セキュリティレベルについては、 » SSL_CTX_get_security_level(3) に説明があります。

PHP 7.2.0 および OpenSSL 1.1.0 以降が必要です。

変更履歴

バージョン | 説明
7.2.0 | security_level が追加されました。 OpenSSL >= 1.1.0 が必要です。

注意

注意: ssl:// は https:// および ftps:// のラッパーの 基盤となるものなので、ssl:// に適用可能なオプションは https:// および ftps:// にも 適用可能です。

注意: SNI (Server Name Indication) を使うには、PHP のコンパイル時に OpenSSL 0.9.8j 以降を使わなければなりません。SNI をサポートしているかどうかは OPENSSL_TLSEXT_SERVER_NAME で判定します。

参考

  • ソケットコンテキストオプション


Phar コンテキストオプション一覧

  • ≪ SSL コンテキストオプション
  • コンテキストパラメータ ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • Phar コンテキストオプション一覧

Phar コンテキストオプション

Phar コンテキストオプション — Phar コンテキストオプション一覧

説明

phar:// ラッパーのコンテキストオプションです。

オプション

compress int

Phar 圧縮定数 のいずれか。

metadata mixed

Phar メタデータ。Phar::setMetadata() を参照ください。

参考

  • phar://
  • Phar ストリームラッパー


コンテキストパラメータの一覧

  • ≪ Phar コンテキストオプション
  • Zip コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • コンテキストパラメータの一覧

コンテキストパラメータ

コンテキストパラメータ — コンテキストパラメータの一覧

説明

これらの パラメータ を コンテキスト に設定するには stream_context_set_params() 関数を使用します。

パラメータ

notification callable

イベントがストリーム上で発生したときにコールされる callable。

詳細は stream_notification_callback を参照ください。


Zip コンテキストオプション一覧

  • ≪ コンテキストパラメータ
  • Zlib コンテキストオプション ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • Zip コンテキストオプション一覧

Zip コンテキストオプション

Zip コンテキストオプション — Zip コンテキストオプション一覧

説明

Zip コンテキストオプションは zip ラッパーで使用可能です。

オプション

password

アーカイブの暗号化に使われたパスワードを指定します。

変更履歴

バージョン | 説明
PHP 7.2.0, PECL zip 1.14.0 | password が追加されました。

例

例1 password の基本的な使用例

<?php
// 暗号化されたアーカイブを参照する
$opts = array(
'zip' => array(
'password' => 'secret',
),
);
// コンテキストを作成して
$context = stream_context_create($opts);

// データを取得する
echo file_get_contents('zip://test.zip#test.txt', false, $context);

?>


Zlib コンテキストオプション一覧

  • ≪ Zip コンテキストオプション
  • サポートするプロトコル/ラッパー ≫
  • PHP Manual
  • コンテキストオプションとパラメータ
  • Zlib コンテキストオプション一覧

Zlib コンテキストオプション

Zlib コンテキストオプション — Zlib コンテキストオプション一覧

説明

Zlib コンテキストオプションは zlib ラッパーで使用可能です。

オプション

level

圧縮レベル (0 - 9) を指定します。

変更履歴

バージョン | 説明
7.3.0 | level が追加されました。


サポートするプロトコル/ラッパー

PHP には多くの組み込みラッパーが用意されています。さまざまな URL 風のプロトコルによって、 fopen() や copy()、 file_exists() そして filesize() といったファイルシステム関数で使用することができます。 これらのラッパーだけでなく、 stream_wrapper_register() 関数でラッパーを自作することもできます。

注意: ラッパーを指定する際の URL 構文としてサポートしているのは scheme://... 形式のみです。 scheme:/ や scheme: といった形式には対応していません。

目次

  • 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:// — 対話的プロセスストリーム


ローカルファイルシステムへのアクセス

  • ≪ サポートするプロトコル/ラッパー
  • http:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • ローカルファイルシステムへのアクセス

file://

file:// — ローカルファイルシステムへのアクセス

説明

file:// is the default wrapper used with PHP and represents the local filesystem. When a relative path is specified (a path which does not begin with /, \, \\, or a Windows drive letter) the path provided will be applied against the current working directory. In many cases this is the directory in which the script resides unless it has been changed. Using the CLI SAPI, this defaults to the directory from which the script was called. PHP で使用されるデフォルトのラッパーは file:// で、 これはローカルファイルシステムを表します。 相対パス(/, \, \\, または 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


HTTP(s) URL へのアクセス

  • ≪ file://
  • ftp:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • HTTP(s) URL へのアクセス

http://

https://

http:// -- https:// — HTTP(s) URL へのアクセス

説明

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

例

例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);
}

}

?>

注意

注意: HTTPS がサポートされるのは、openssl 拡張モジュールが有効な場合のみです。

HTTP 接続は読み込みのみ可で、HTTP リソースにデータを書き込んだり ファイルをコピーしたりすることはできません。

たとえば POST および PUT リクエストを送信することも、 HTTP コンテキスト を使えば可能です。

参考

  • HTTP コンテキストオプション
  • $http_response_header
  • stream_get_meta_data() - ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する


FTP(s) URL へのアクセス

  • ≪ http://
  • php:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • FTP(s) URL へのアクセス

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

オプション

ラッパーの概要
属性 | サポート対象か
allow_url_fopen で制約される | Yes
読み込み許可 | Yes
書き込み許可 | Yes（新規ファイル あるいは 既存のファイルで overwrite を指定）
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | filesize()、filemtime()、 filetype()、file_exists()、 is_file()、is_dir() のみ。
unlink() のサポート | Yes
rename() のサポート | Yes
mkdir() のサポート | Yes
rmdir() のサポート | Yes

注意

注意:

FTPS がサポートされるのは、openssl 拡張モジュールが有効な場合のみです。

もしサーバーが SSL をサポートして いなければ、通常の（暗号化されない）FTP を使用します。

注意: 追記
ftp:// URL ラッパー経由での ファイルの追記が可能です。

参考

  • FTP コンテキストオプション


さまざまな入出力ストリームへのアクセス

  • ≪ ftp://
  • zlib:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • さまざまな入出力ストリームへのアクセス

php://

php:// — さまざまな入出力ストリームへのアクセス

説明

PHP ではさまざまな入出力ストリームを提供しています。 これらを使うと、PHP 自身の入出力ストリームへのアクセスや 標準入出力と標準エラー出力のファイル記述子へのアクセス、 メモリやディスクを使ったテンポラリファイルストリームへのアクセスができ、 フィルタを使って他のファイルリソースの読み書きに手を加えることもできます。

php://stdin, php://stdout および php://stderr

php://stdin、php://stdout および php://stderr は、PHP プロセスの 対応する入出力ストリームへの直接アクセスを許可します。 これらのストリームは複製されたファイル記述子を参照します。そのため、 php://stdin をオープンしたあとでそれを閉じたとしても、 識別子のコピーが閉じられるだけです。STDIN で参照される実際のストリームは何も影響を受けません。 これらのラッパーを使うのではなく、定数 STDIN, STDOUT および STDERR を使用することを推奨します。

php://stdin は読み込み専用で、 php://stdout および php://stderr は書き込み専用です。

php://input

php://input は読み込み専用のストリームで、 リクエストの body 部から生のデータを読み込むことができます。 enable_post_data_reading オプションが有効になっている場合、 かつ enctype="multipart/form-data" を指定した POST リクエストでは、php://input は使用できません。

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 の拡張モジュールによっては、 標準入出力が必須なものがあるかもしれません。 その場合、指定されたストリームを標準入出力のストリームにキャストしようとするかもしれませんが、メモリに格納するストリームの場合、このキャストは失敗する可能性があります。なぜなら、C言語の fopencookie() 関数が使える必要があるからです。この関数は、Windows では 利用できません。

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() のサポート | No. 但し、php://memory および php://temp は、fstat() をサポートしています。
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No
stream_select() のサポート | php://stdin、 php://stdout、 php://stderr、 php://fd、および php://temp のみ。

例

例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");
?>

例5 php://memory と php://temp は再利用できない

php://memory と php://temp の再利用はできません。つまり、いったんストリームを閉じてしまったら、もうそれを参照できないということです。

<?php
file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // 何も表示されません


圧縮ストリーム

  • ≪ php://
  • data:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • 圧縮ストリーム

zlib://

bzip2://

zip://

zlib:// -- bzip2:// -- zip:// — 圧縮ストリーム

説明

compress.zlib:// および compress.bzip2://

zlib: は gzopen() と同様に 動作しますが、このストリームは fread() および 他のファイルシステム関数と組み合わせて使用することができるところが 異なります。この機能ではファイル名に ':' 文字が含まれる曖昧さが あるため、推奨されません。代わりに compress.zlib:// を使用してください。

compress.zlib:// および compress.bzip2:// は、それぞれ gzopen() および bzopen() と等価で、 fopencookie をサポートしないシステムの上でも動作します。

ZIP 拡張モジュール は、zip: ラッパーを登録します。 PHP 7.2.0 以降、かつ libzip 1.2.0+ では、 暗号化されたアーカイブに対するパスワードのサポートが追加され、 ストリームのコンテキストでパスワードを与えることが出来るようになりました。 パスワードは、'password' コンテキストオプションで設定できます。

利用法

  • compress.zlib://file.gz
  • compress.bzip2://file.bz2
  • zip://archive.zip#dir/file.txt

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes (zip:// を除く)
追加許可 | Yes (zip:// を除く)
同時読み書き許可 | No
stat() のサポート | No, 圧縮されたファイルの状態を知るには、通常の file:// ラッパーを使用します。
unlink() のサポート | No, 圧縮されたファイルを unlink するには、通常の file:// ラッパーを使用します。
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

参考

  • Zlib コンテキストオプション


データ (RFC 2397)

  • ≪ zlib://
  • glob:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • データ (RFC 2397)

data://

data:// — データ (RFC 2397)

説明

data: (» RFC 2397) ストリームラッパーです。

利用法

  • data://text/plain;base64,

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | Yes
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'];
?>


パターンにマッチするパス名の検索

  • ≪ data://
  • phar:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • パターンにマッチするパス名の検索

glob://

glob:// — パターンにマッチするパス名の検索

説明

glob: ストリームラッパーは、パターンにマッチするパス名の探索が行なえます。

利用法

  • 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


PHP アーカイブ

  • ≪ glob://
  • ssh2:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • PHP アーカイブ

phar://

phar:// — PHP アーカイブ

説明

phar:// ストリームラッパーに関する詳細は Phar ストリームラッパー を参照ください。

利用法

  • phar://

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
allow_url_include で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | No
同時読み書き許可 | Yes
stat() のサポート | Yes
unlink() のサポート | Yes
rename() のサポート | Yes
mkdir() のサポート | Yes
rmdir() のサポート | Yes

参考

  • Phar コンテキストオプション


Secure Shell 2

  • ≪ phar://
  • rar:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • Secure Shell 2

ssh2://

ssh2:// — Secure Shell 2

説明

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// （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');
?>

例2 $session を有効にしておかないといけない!

ssh2.*://$session ラッパーを使うには、 リソース変数 $session をキープしておかないといけません。 次のコードは、期待通りには動きません。

<?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');
$connection_string = "ssh2.sftp://$session/";
unset($session);
$stream = fopen($connection_string . "path/to/file", 'r');
?>

この例では、unset() のところでセッションを閉じてしまいます。 なぜなら、$connection_string が持つのが $session への参照ではなく、単にそれを文字列にキャストしたものだからです。 これは、unset() が暗黙のうちに呼ばれた場合にも起こりえます (関数などの) スコープを抜けるときに発生する可能性があります。


RAR

  • ≪ ssh2://
  • ogg:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • RAR

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
)


オーディオストリーム

  • ≪ rar://
  • expect:// ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • オーディオストリーム

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:// (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


対話的プロセスストリーム

  • ≪ ogg://
  • セキュリティ ≫
  • PHP Manual
  • サポートするプロトコル/ラッパー
  • 対話的プロセスストリーム

expect://

expect:// — 対話的プロセスストリーム

説明

expect:// ラッパーでオープンしたストリームを使用すると、 プロセスの標準入力・標準出力・標準エラー出力への PTY 経由でのアクセスが 可能となります。

注意: このラッパーはデフォルトでは有効となっていません。
expect:// ラッパーを使用するには、 » PECL にある » Expect 拡張モジュールを インストールする必要があります。

expect:// (PECL)

利用法

  • expect://command

オプション

ラッパーの概要
属性 | サポートの有無
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No


セキュリティ

  • はじめに
  • 一般的な考慮事項
  • CGI バイナリとしてインストール
    • 受ける可能性がある攻撃
    • ケース 1: 配布制限がないファイルのみを配布
    • ケース 2: cgi.force_redirect を使用
    • ケース 3: doc_root または user_dir を設定
    • ケース 4: Webツリーの外にPHPパーサを置く
  • Apache モジュールとしてインストール
  • セッションのセキュリティ
  • ファイルシステムのセキュリティ
    • Null バイト関連の問題
  • データベースのセキュリティ
    • データベースのデザイン
    • データベースへの接続
    • ストレージの暗号化
    • SQLインジェクション
  • エラーのレポート
  • ユーザーが投稿したデータ
  • PHPの隠蔽
  • 最新版を維持する


はじめに

PHP は強力な言語そしてインタプリタであり、モジュールとして Web サー バーに組み込んだ場合でも、独立した CGI バイナリ として実行される場合でも、ファイルをアクセスしたり、コマンドを実行 したり、サーバーへのネットワーク接続を開くことができます。デフォル トでは、これらの機能を実行した場合、Webサーバー上でセキュリティ上の 問題を生じる可能性があります。PHP は、特に CGI プログラムを書く場合、 Perl や C より安全な言語となるように設計されています。コンパイル時 または実行時の設定オプションを正しく選び、適切なコードを書くことに より、必要な自由度とセキュリティの組み合わせを確実に提供することが できます。

PHP の使用法に多くの異なった手段があるように、PHP の動作を制御する 多くの設定オプションがあります。オプションの選択肢が広いため、PHP を様々な用途に使用することができます。しかし、このことは、これらの オプションとサーバー設定の組み合わせによっては、安全でない設定とな ることを意味します。

PHPの設定の自由度はそのコードの柔軟さにほぼ匹敵します。PHPは、シェ ルユーザーコマンドを全て実行可能な完全なサーバーアプリケーションや 厳しく制御された環境で低リスクの簡単なサーバーサイドインクルードを 使用できるようなアプリケーションを構築する場合に使用することが可能 です。そうした環境の構築方法、セキュリティのレベルはPHPの開発者に大 きく依存しています。

本章は、安全に使用可能な異なった設定と条件の組み合わせについての説 明から始めます。続いて、複数のセキュリティレベルのコーディングにお ける複数の考慮事項について説明し、最後にいくつかの一般的なセキュリ ティ上のアドバイスを行います。


一般的な考慮事項

完全に安全なシステムは理想の産物でしかないため、セキュリティ業界で しばしば使用される手法は、リスクと利便性のバランスのとれた手法です。 変数がユーザーから投稿される度に(網膜スキャンと指紋のような)2種類の 生体認証が必要だとしたら、極端に高いレベルの説明義務を生じます。ま た、かなり複雑なフォームを埋めるために30分もかかるとすれば、ユーザー がセキュリティをバイパスする手段を探す気分にさせる傾向があります。

最善のセキュリティは、通常、ユーザーによる業務の達成を防たげずに要求 を十分に達成できる程度にさしでがましくないものです。むしろ、いくつ かのセキュリティ攻撃は、単純にこの種の多げさに構築され、時間を浪費 しがちなセキュリティ機構を狙うものです。

記憶するに値する言葉として次のようなものがあります。「システムは鎖 の最も弱い輪と同程度に優れている」全てのトランザクションが時間、場 所、トランザクションの型等に基づき大量に記録されているが、ユーザーは 一つのクッキーのみにより認証されている場合、ユーザーとそのトランザク ションログの結び付きの確実性はかなり弱くなります。

テストの際に、最も簡単なページに関してでさえ、全ての可能性をテスト することは不可能であるということを頭に入れておいてください。期待する 入力は、不機嫌な社員、経験のあるクラッカー、キーボードの上を歩く家 の猫による入力とは全く無関係でしょう。これが、想定外のデータが入力 される可能性がある場所を見分けるために論理的な視点からコードを見て、 その後、修正、減少、または詳細に調べるというのが、最善であるという 理由です。

インターネットにはあなたのコードを壊したり、システムを破壊したり、 不適切な内容を投稿したり、その他あなたの一日を不快にするようなこと により自分の名を馳せたいと思う人がたくさんいます。サイトの規模の大 小によらず、単にオンラインであり、接続できるサーバーを有しているだけ で攻撃目標となりえます。多くのクラック用プログラムはサイトの大きさ を考慮せず、犠牲者を探しつつ大きなIPブロックで網を張っています。 その犠牲者の一人にならないようにしてください。


CGI バイナリとしてインストール

目次

  • 受ける可能性がある攻撃
  • ケース 1: 配布制限がないファイルのみを配布
  • ケース 2: cgi.force_redirect を使用
  • ケース 3: doc_root または user_dir を設定
  • ケース 4: Webツリーの外にPHPパーサを置く


受ける可能性がある攻撃

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 バイナリ と通信できる手段を有していない場合、ini ディレクティブ cgi.force_redirect を有効にできます。 この場合でも、直接 的な方法 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 はこのモードでのみ処理を行います。

通常、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 情報を正しく処理するためには、 ini ディレクティブ cgi.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専用エリアを設定する ことも可能です。


セッションのセキュリティ

HTTPセッション管理を安全にし続けることは重要です。 セッション関連のセキュリティについては セッションのセキュリティ セクション （セッションモジュール リファレンス内） で説明しています。


ファイルシステムのセキュリティ

目次

  • Null バイト関連の問題

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';
}
?>


データベースのセキュリティ

目次

  • データベースのデザイン
  • データベースへの接続
  • ストレージの暗号化
  • SQLインジェクション

今日、ダイナミックなコンテンツを提供するウェブアプリケーションにおいてはデータベースは欠く事のできないコンポーネントとなっています。 そういったデータベースには重要な、そして秘密にすべき情報が格納されることになるので、それらをいかにして保護するかについて十分に考慮する必要があります。

情報を取り出したり格納するためにはデータベースに接続する必要があります。 そして適切なクエリを送信し、結果を受け取り、切断します。クエリに使用される言語は Structured Query Language (SQL) が一般的です。アタッカーがどのようにSQLに 干渉するかについて参照ください。

皆さんがお気づきの様に、PHPそれ自体は貴方のデータベースを保護することは ありません。以下のセクションはPHPスクリプトからどのようにデータベースに アクセスし操作すればいいのか、ということに関する非常に基本的な導入です。

このシンプルなルールを覚えて置いてください：それは「多重防衛」です。 より多くの箇所で、より多くの保護を行うことにより、アタッカーが攻撃に 成功して機密情報が漏洩する可能性は減っていきます。データベースと アプリケーションを正しくデザインすることで貴方の心配を取り除くことが できます。


データベースのデザイン

他人が用意した既存のものを使用するのでない限り、最初に行うのはデータベースの作成です。 データベースが作成されると、そのデータベースのオーナーは作成コマンドを 実行したユーザーになります。通常、オーナー(とスーパーユーザー)のみが そのデータベースに対して操作を行うことが出来ます。他のユーザーがデータベースを 使用するには適切な権利が与えられている必要があります。

アプリケーションはデータベースにオーナー、もしくはスーパーユーザーとして接続することは絶対にしてはなりません。 なぜならこれらのユーザーは 例えばスキーマの変更(テーブルの削除等)や全コンテンツの削除、といったあらゆるクエリーを実行することが出来るからです。

貴方が作成するアプリケーションがデータベースに対して行う操作の各方面ごとに、 操作対象となるオブジェクトに対して、出来る限り少ない権限を持った複数の ユーザーを作成した方が良いでしょう。ユーザーに対しては、最低限必要な権限のみを 与え、関係の無いデータへのアクセスを許可しないようにします。これは、 万が一侵入者がそのユーザーの権限を以ってデータベースにアクセスした際に、 アプリケーションと関係の無いデータにまでアクセスされることを防ぐためです。


データベースへの接続

更なるセキュリティのために、クライアント/サーバー間の通信においてSSLを用いた 暗号化を行った方が良いでしょう。もしくはsshを使用することも出来ます。 どちらかの手段を講じた後、トラフィックをモニタリングしてみれば ここから何らかの情報を得ることが困難だという事が分かると思います。


ストレージの暗号化

SSL/SSHによってクライアント/サーバー間で通信されるデータは保護されますが、 データベースに保存されたデータは保護されません。SSLはあくまで通信上の プロトコルなのです。

一旦アタッカーがデータベースへ(ウェブサーバーを通さずに)アクセスできてしまうと、 そこに格納されているデータ自体が暗号化されていない限り、自由に閲覧され、 使用されてしまいます。データを暗号化することによって、この脅威を減らすことが できますが、この機能をサポートしているデータベースは僅かです。

この問題への最も簡単な対応策は、まず自分専用の暗号化パッケージを作成し、 それをあなたのPHPスクリプトから使用することです。PHPのOpenSSL, Sodium といった幾つかの拡張モジュールは、様々な暗号化アルゴリズムをサポート しているので役に立つでしょう。データ格納時に暗号化を行い、取得時に 復号化します。この方法についてはリファレンスを参照ください。

ハッシュ

もし完全にデータを隠したい場合や、元のデータ自体は必要ない場合(つまり 表示されない場合)は、ハッシュも考慮に入れたほうが良いでしょう。 ハッシュの良く知られた使用方法は、パスワードをそのまま格納せずに、 その暗号学的ハッシュ値を格納する方法です。

PHP は password 関数を提供しており、 機密データをハッシュしたりそのハッシュを扱ったりする便利な仕組みが用意されています。

password_hash() は、その時点で最も強力なアルゴリズムを使って、 与えられた文字列をハッシュします。また password_verify() は、与えられたパスワードのハッシュがデータベース内のハッシュと一致するかどうかを調べます。

例1 ハッシュされたパスワードフィールド

<?php

// ハッシュされたパスワードを格納する
$query = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($username),
password_hash($password, PASSWORD_DEFAULT));
$result = pg_query($connection, $query);

// パスワードが正しいかどうか問い合わせる
$query = sprintf("SELECT pwd FROM users WHERE name='%s';",
pg_escape_string($username));
$row = pg_fetch_assoc(pg_query($connection, $query));

if ($row && password_verify($password, $row['pwd'])) {
echo 'Welcome, ' . htmlspecialchars($username) . '!';
} else {
echo 'Authentication failed for ' . htmlspecialchars($username) . '.';
}
?>


SQLインジェクション

SQLインジェクションは、 攻撃者が動的なSQLクエリを組み立てる責任があるアプリケーションコードの欠陥を突く手法です。 攻撃者は、アプリケーションの権限が必要な部分にアクセスでき、 データベースからすべての情報を引き出し、既存のデータを改ざんしたり、 危険なシステムレベルのコマンドをデータベースのホスト上で実行できてしまいます。 こうした脆弱性は、開発者が任意の入力をSQL文に結合したり、挿入したりすることで発生します。

例1 表示するデータを分割し ... そしてスーパーユーザーを作成します。(PostgreSQLの例)

以下の例では、ユーザーからの入力が直接SQLクエリに挿入されているため、 攻撃者がデータベースの superuser アカウントを取得できてしまいます。

$offset = $_GET['offset']; // 入力チェックが行われていません！
$query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
$result = pg_query($conn, $query);
通常のユーザーは、$offset が URL に埋め込まれている '次へ'または'前へ'リンクをクリックします。スクリプトは、受け取った $offset が数字であることを期待します。しかしながら、 以下のような値を 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'";
$result = odbc_exec($conn, $query);
クエリの静的な部分は、以下のように全てのパスワードを外部にもらす別の SELECT文と組み合わせることができます。
'
union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
--

UPDATE や INSERT 文も、 データベースを攻撃するために使用されます。

例3 パスワードのリセットから ... (全てのデータベースサーバーで)より多 くの権限を得るまで

$query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
もし悪意のあるユーザーが管理者のパスワードを変更するために 値 ' or uid like'%admin% を $uid に代入するか、または、より多くの権限を得 るために、単純に$pwd に hehehe', trusted=100, admin='yesと設定すると、 このクエリは以下のように改謬されてしまいます。
<?php

// $uid: ' or uid like '%admin%
$query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

// $pwd: hehehe', trusted=100, admin='yes
$query = "UPDATE usertable SET pwd='hehehe', trusted=100, admin='yes' WHERE
...;";

?>

攻撃者がデータベースの構造に関して最低限の知識を持っていないと攻撃は成功しないのが明らかです。 しかし、その手の情報はたいてい、とても簡単に入手できます。 たとえば、コードの一部がオープンソースソフトウェアの一部のため、 公開されている可能性があります。 こうした情報は、クローズドソースの場合でも漏洩する可能性があります - エンコードされたり、難読化されたり、コンパイルされていてもです。 - さらに、自作のコードであっても、エラーメッセージを表示することで漏れてしまう可能性があるのです。 他の方法としては、ありがちなテーブルやカラムの名前を使うことが挙げられます。 たとえば、'id', 'username', 'password' カラムを持つ 'users' テーブルを使うログインフォームが挙げられます。

例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サービスが充分な権限で実行されていた場合、攻撃者は このマシンにアクセスする権限を有することになります。

注意:

上記の例は、データベースサーバーの種類に依存しています。 しかし、他の製品に対して同様な攻撃ができないことを意味するもので はありません。使用しているデータベースが他の手段で攻撃できる可能性もあります。

この画像は » xkcd から提供いただいたものです。

回避策

SQLインジェクションを回避するおすすめの方法は、 すべてのデータをプリペアドステートメント経由でバインドすることです。 パラメータ化されたクエリは、 SQLインジェクションをすべて防ぐのに十分ではありませんが、 SQL文への入力を与える一番簡単かつ安全な方法です。 WHERE, SET, VALUES 句に与えるすべての動的なデータリテラルは、 すべてプレースホルダーで置き換えなければいけません。 すべての実データは実行中にバインドされ、SQLコマンドとは別に送信されます。

パラメータのバインドは、データに対してのみ使えます。 SQLクエリの他の動的な部分については、 許される値の既知の値でフィルタしなければいけません。

例5 PDO のプリペアドステートメントを使い、SQLインジェクションを回避する

<?php
// SQL の動的な部分は、期待する値になるように検証されています
$sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
$productId = $_GET['productId'];
// SQL はプレースホルダを使って準備します。
$stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");
// 値は LIKE ワイルドカードを使って与えられます
$stmt->execute(["%{$productId}%"]);
?>

プリペアドステートメントは PDO や MySQLi、 そして他のデータベースライブラリでも使えます。

SQLインジェクションによる攻撃は、 セキュリティを考慮して書かれていないコードを攻撃する方法です。 特にクライアント側から入力されるあらゆる種類の入力を決して信用しないでください。これは、select ボックス や hidden input フィールド、Cookie の場合も同様です。最初に示した例は、簡単なクエリが破滅をもたらしうることを示しています。

攻撃を防ぐ戦略として、以下に示すいくつかのコーディングプラクティスに従うことが挙げられます:

  • データベースにスーパーユーザーまたはデータベースの所有者として接続しないでください。 非常に制限された権限を有するカスタマイズされたユーザーを常に使用してください。
  • 指定された入力が期待するデータ型であることを確認してください。 PHPは、 多くの種類の入力検証用関数を有しており、 変数関連の関数 や 文字型関数 にある簡単な関数 (例: それぞれ、is_numeric(), ctype_digit()) や、Perl互換の正規表現のサポートまであります。
  • アプリケーションが数値入力を期待している場合、
ctype_digit() を使ってデータを検証するか、
settype() で暗黙の型変換を行うか、
sprintf() で数値表現を使用することを検討してみてください。
  • データベースがバインド変数をサポートしていない場合は、 データベースに渡される数値以外のユーザー入力を データベース固有の文字列エスケープ関数 (e.g. mysql_real_escape_string(), sqlite_escape_string() など) を使ってクォートしてください。 addslashes() のような汎用関数が使える場面は、 とても限定された環境に限られます。 (MySQL をシングルバイト文字セットで使っていて、かつ NO_BACKSLASH_ESCAPES を無効にしている場合など) よって、この関数は使わないほうが良いです。
  • 正しい手段でも、そうでなくても、データベース固有の情報、特にスキーマに関する情報は出力してはいけません。 エラー出力 および エラー処理およびログ関数 も参照ください。

これらのケースにおいて、スクリプトまたはサポートされている場合はデータベース自体でクエリのログをとることが有益です。 明らかにログは破壊的な行為を防止することはできませんが、 攻撃されたアプリケーションを追跡する際には有効です。ログ自体は有益ではありませんが、含まれている情報は有益です。通常、より詳細なログをとる方が良いでしょう。


エラーのレポート

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 のプログラムで最も脆弱な部分は、言語自体に起因するものではなく、 単にセキュリティを考慮して書かれていないコードの問題です。そのため、 指定したコードの部分の意味を常に時間をかけて吟味し、 予想外の変数が投稿された場合に有り得る損害を確かめる必要があります。

例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の隠蔽

一般に隠蔽という手段はセキュリティとしては弱いものだと言われています。 しかしこうした手法が望ましい場合もあります。

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 認証
  • クッキー(Cookies)
  • セッション
  • ファイルアップロードの処理
    • POST メソッドによるアップロード
    • エラーメッセージの説明
    • 陥りやすい落とし穴
    • 複数ファイルのアップロード
    • PUT メソッドのサポート
    • 参考
  • リモートファイルの使用
  • 接続処理
  • 持続的データベース接続
  • コマンドラインの使用法 — PHP をコマンドラインから使用する
    • 他の SAPI との違い
    • オプション — コマンドラインオプション
    • PHP ファイルの実行
    • I/O ストリーム — 入出力ストリーム
    • 対話シェル
    • ビルトインウェブサーバー
    • INI 設定
  • ガベージコレクション
    • リファレンスカウントの原理
    • 循環の収集
    • パフォーマンスの考慮点
  • DTrace 動的トレーシング
    • PHP および DTrace への入門
    • PHP および DTrace の使用
    • PHP DTrace 静的プローブとともに SystemTap を使用


PHP による HTTP 認証

header() 関数を使うと、 "Authentication Required" メッセージをクライアントブラウザに送ることができます。 これにより、クライアントブラウザではユーザー名とパスワードの入力要求 ウインドウがポップアップ表示されます。一度、ユーザーがユーザー名と パスワードを入力すると、PHP スクリプトを含むその URL は、次回以降、 定義済みの変数 PHP_AUTH_USER と、 PHP_AUTH_PW と、 PHP_AUTH_TYPE にそれぞれユーザー名、 パスワード、認証型が代入された状態で呼ばれます。 定義済みの変数は、配列 $_SERVER でアクセス可能です。 "Basic" 認証 のみ がサポートされています。詳細は、 header()を参照ください。

ページ上でクライアント認証を強制するスクリプトの例を以下に示します。

例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>";
}
?>

注意: 互換性に関する注意

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 は、外部認証が動作しているかどうかの判定を AuthType ディレクティブの有無で行います。

しかし、上記の機能も、認証を要求されないURLを管理する人が同じサーバー にある認証を要するURLからパスワードを盗むことを防ぐわけではありませ ん。

サーバーからレスポンスコード 401 を受けた際に、Netscape Navigatorおよび Internet Explorer は共にローカルブラウザのウインドウ上の認証キャッシュを 消去します。この機能により、簡単にユーザーを"ログアウト"させ、強制的に ユーザー名とパスワードを再入力させることができます。この機能は、 "タイムアウト" 付きのログインや、"ログアウト" ボタンに適用されています。

例2 新規に名前 / パスワードを入力させる 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 を再度押すことにより 証明書の要件が変更されない限りリソースをオープンすることができます。 しかし、ユーザーは '_' キーを押すことにより認証情報をクリアすることが可能です。

IIS サーバーと CGI 版の PHP の組み合わせで HTTP 認証を使うには、 IIS の設定の "ディレクトリセキュリティ" の "編集" ボタンを押して "匿名アクセス" のみをオンにしてください。 その他のフィールドはオフのままにしてください。

注意: IIS に関する注意:
IIS上 で HTTP 認証を使用する場合、PHP の cgi.rfc2616_headers ディレクティブは0 (デフォルト値) にセットされて いなければなりません。


クッキー(Cookies)

PHP は、HTTP クッキー(Cookie)を完全にサポートします。 クッキーは、リモートブラウザに文字列データを保存したり、 再訪するユーザーを特定したりする機構です。 setcookie() か setrawcookie() を使用してクッキーをセットすることができます。 クッキーは HTTP ヘッダの一部なので、 setcookie() はブラウザに何らかの出力を行う前にコールする必要があります。 この制約は、header() に課されているものと同じです。 また、 出力バッファ関数を使用して、 設定するクッキーや送信するヘッダの内容が決まるまで スクリプトからの出力を遅らせることが出来ます。

もし variables_order が "C" を含んでいる場合、クライアントからサーバーへ送られた全てのクッキーは 自動的に $_COOKIE という（常にグローバルな）配列に格納されます。 多数の値を一つのクッキーに割り付けたい場合は、[] をクッキー名に加えてください。

ちょっとした注意やブラウザのバグといった詳細に関しては、 setcookie() と setrawcookie() を参照ください。


セッション

PHPのセッションサポートは、連続するアクセスを通じて特定のデータを保持する 手段を構成します。この機能により、よりカスタマイズされたアプリケーション の構築が可能となり、Webサイトをより魅力的なものにすることができます。 詳細な情報は、 セッションに関するリファレンス のセクションにあります。


ファイルアップロードの処理

目次

  • POST メソッドによるアップロード
  • エラーメッセージの説明
  • 陥りやすい落とし穴
  • 複数ファイルのアップロード
  • PUT メソッドのサポート
  • 参考


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 要素の name 属性の値が、$_FILES 配列のキーになります -->
    このファイルをアップロード: <input name="userfile" type="file" />
    <input type="submit" value="ファイルを送信" />
</form>

上の例の __URL__ は、PHP ファイルを指すよう置換される 必要があります。

"MAX_FILE_SIZE" hidden フィールドは、 "file" input フィールドの前に置く必要があります。 この値は、PHP で取得可能なファイルの最大サイズを規定します。この値はバイト数で指定します。 MAX_FILE_SIZE は常に指定しておくべきです。 巨大なファイルを転送しようとして長時間待ち続け、 結局ファイルが大きすぎて転送できなかったなどといった羽目に陥るのを防げるからです。 注意: ブラウザ側でこの最大値を出し抜くのは簡単なことなので、この機能を信頼して、 これより大きなサイズのファイルがブロックされることを前提にしてはいけません。 しかし、PHP 側の最大サイズの設定を欺くことはできません。

注意:

アップロード用のフォームが enctype="multipart/form-data" 属性を有しているかを 確認してください。さもないと、ファイルのアップロードは動作しません。

グローバルの $_FILES には、アップロードされたファイルの情報が含まれます。 サンプルのフォームからの内容は次のようになります。ここでは、上の例のスクリプトで使われたように、 アップロードファイルの名前として userfile を 使用することを仮定していることに注意してください。 実際にはどんな名前にすることもできます。

$_FILES['userfile']['name']

クライアントマシンの元のファイル名。

$_FILES['userfile']['type']

ファイルの MIME 型。ただし、ブラウザがこの情報を提供する場合。 例えば、"image/gif" のようになります。 この MIME 型は PHP 側ではチェックされません。そのため、 この値は信用できません。

$_FILES['userfile']['size']

アップロードされたファイルのバイト単位のサイズ。

$_FILES['userfile']['tmp_name']

アップロードされたファイルがサーバー上で保存されているテンポラ リファイルの名前。

$_FILES['userfile']['error']

このファイルアップロードに関する エラーコード

$_FILES['userfile']['full_path']

ブラウザからアップロードされたファイルのフルパス。 この値は実際のディレクトリ構造を反映しているとは必ずしも言えないため、 信用できません。 PHP 8.1.0 以降で利用可能です。

php.ini の upload_tmp_dir ディレクティブで 他の場所を指定しない限り、ファイルはサーバーにおけるデフォルトの テンポラリディレクトリに保存されます。サーバーのデフォルトディレクトリは、 PHP を実行する環境において環境変数 TMPDIR を設定する ことにより変更することができます。しかし、PHP スクリプトの内部から putenv() 関数により設定しても上手くいきません。 この環境変数は、アップロードされたファイルに他の処理を行う際にも 同様に使用することが可能です。

例2 ファイルのアップロードを検証する

詳細については、is_uploaded_file() および move_uploaded_file() の関数のエントリも 参照ください。以下はフォームからファイルをアップロードするプロセスの例です。

<?php
$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 側では何もチェックしていないからです。 また、 $_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];
// basename() で、ひとまずファイルシステムトラバーサル攻撃は防げるでしょう。
// ファイル名についてのその他のバリデーションも、適切に行いましょう。
$name = basename($_FILES["pictures"]["name"][$key]);
move_uploaded_file($tmp_name, "data/$name");
}
}
?>

ファイルアップロードのプログレスバーは、セッションのアップロードの進捗 で実装することができます。


エラーメッセージの説明

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; テンポラリフォルダがありません。

UPLOAD_ERR_CANT_WRITE

値: 7; ディスクへの書き込みに失敗しました。

UPLOAD_ERR_EXTENSION

値: 8; PHP の拡張モジュールがファイルのアップロードを中止しました。 どの拡張モジュールがファイルアップロードを中止させたのかを突き止めることはできません。 読み込まれている拡張モジュールの一覧を phpinfo() で取得すれば参考になるでしょう。


陥りやすい落とし穴

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 秒を増やしましょう。

post_max_size の設定値が 小さすぎた場合、大きなファイルをアップロードすることができなくなります。 post_max_size に充分大きな値を設定するように してください。

max_file_uploads は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。 この制限を超える数のファイルをアップロードしようとすると、制限に達した時点で $_FILES は処理を停止します。たとえば max_file_uploads が 10 の場合には、$_FILES には 10 件までの要素しか入らないということです。

処理するファイルを検証しない場合、ユーザーが他のディレクトリにある 非公開情報にアクセスできる可能性を生じます。

大量のディレクトリ一覧のスタイルのせいで、 風変わりな名前（空白を含んでいるとか）のファイルを適切に扱えることは 保証できません。

通常の 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'] が設定されます。

例えば、ファイル名が /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] も設定されます。

警告

max_file_uploads は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。 フォームからの一回のリクエストで、 これを超える数のファイルをアップロードしてしまわないようにしましょう。

例2 ディレクトリ全体をアップロードする

HTML のファイルアップロードフィールド中に、 webkitdirectory 属性を指定することで ディレクトリ全体をアップロードすることができます。 この機能はほとんどのモダンなブラウザでサポートされています。

full_path の情報を使うと、 相対パスを保存することもできますし、 サーバー上で同じディレクトリを再構築することもできます。

<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send this directory:<br />
  <input name="userfile[]" type="file" webkitdirectory multiple />
  <input type="submit" value="Send files" />
</form>
警告

webkitdirectory 属性は標準ではありませんし、 標準化の過程にも入っていません。 この属性を Web 上の本番環境で使わないで下さい: なぜなら、この属性を全ユーザーが使えるとは限らないからです。 また、この属性はクライアントの実装に非互換がある可能性もありますし、 振る舞いが将来変更される可能性もあります。

PHP は ブラウザ/ユーザーエージェントから送られてきた相対パスの情報をパースし、 その情報を $_FILES 配列に渡すことだけを行います。 full_path 配列中の値が、 実際のディレクトリ構造を含んでいるという保証はありません。 よって、PHP アプリケーションはこの情報を信用してはいけません。


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);
?>


  • ≪ PUT メソッドのサポート
  • リモートファイルの使用 ≫
  • PHP Manual
  • ファイルアップロードの処理
  • 参考

参考

  • ファイルシステムのセキュリティ


リモートファイルの使用

php.iniでallow_url_fopenを有効にした場合、 ファイル名をパラメータとする関数の多くで HTTP および FTP のURL を使用することができます。加えて、 include、 include_once、 require および require_once 命令でURLを使用することができます (これらで使用するためには allow_url_include を有効にする必要があります)。 PHPがサポートしているプロトコルに関する詳細は サポートするプロトコル/ラッパーを参照ください。

例えば、リモート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 内部で、接続ステータスが保持されます。 これは、次の 4 つの状態をとりえます。

  • 0 - NORMAL
  • 1 - ABORTED
  • 2 - TIMEOUT
  • 3 - ABORTED および 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 は、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の割りつけ を行うように設計されています。このことは、常に 持続的接続を非持続的接続で置きかえ、かつ動作を変更しないということ ができることを意味します。持続的接続は、スクリプトの効率を変える かもしれません(おそらく変えます)が、動作は変更しません!

ibase_pconnect(), ociplogon(),
odbc_pconnect(), oci_pconnect(),
pfsockopen(), pg_pconnect()
も参照ください。


PHP をコマンドラインから使用する

目次

  • 他の SAPI との違い
  • オプション
  • PHP ファイルの実行
  • I/O ストリーム
  • 対話シェル
  • ビルトインウェブサーバー
  • INI 設定

はじめに

CLI 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 になるとは限りません。

Windows 版の CLI はメインフォルダ内で php.exe という名前で配布されます。CGI バージョンは、php-cgi.exe として配布されます。さらに 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 INI 設定に -d を使って値を設定する例

# 値の部分を省略すると、設定ディレクティブに"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 オプションに指定したファイル名をパースし、 実行します。このスイッチはオプションで省略することもできます。 実行するスクリプトを指定するだけで充分です。

-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

例2 PHP に組み込まれた (そしてロードされた) Zend モジュールの表示

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-r --run

このオプションにより、コマンドラインのみで PHP の実行ができるようになります。 PHP の開始および終了タグ (<?php および ?>) は不要で、これらを付けると パーサエラーとなります。

注意:

このように PHP を実行する際に、コマンドラインの 変数がシェルにより行なわれる置換と干渉しないように注意してください。

例3 ダブルクォートの使用時に構文エラーが出る例

$ 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 により展開されません。

例4 シングルクォートを使い、シェルの変数置換を防ぐ例

$ 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 以外のシェルを使用している場合には、別の問題を経験したことが あるかもしれません。バグを » https://github.com/php/php-src/issues に報告してください。 シェル変数をコードに取得しようとしたり、エスケープを行なうために バックスラッシュを使用したりした場合にも、容易に問題を発生する 可能性があります。注意が必要です。

注意:

-r は CLI SAPI で有効で、 CGI SAPI では使用できません。

注意:

このオプションはあくまで基本的な機能を提供するものです。そのため、 いくつかの設定ディレクティブ（例: auto_prepend_file および auto_append_file）は このモードでは無視されます。

-B --process-begin

標準入力を処理する前に実行する PHP コードを指定します。

-R --process-code

それぞれの入力行に対して実行する PHP コードを指定します。

このモードには 2 つの特別な変数 $argn と $argi が用意されています。 $argn は PHP がその瞬間に処理している行を含み、 $argi はその行番号を含んでいます。

-F --process-file

全ての入力行に対して実行する PHP ファイルを指定します。

-E --process-end

入力を処理した後に実行する PHP コードを指定します。

例5 とあるプロジェクトの行数をカウントするための -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

ビルトインウェブサーバー を開始させます。

-t | --docroot | ビルトインウェブサーバー のドキュメントルートを指定します。
-s --syntax-highlight と --syntax-highlighting

カラー構文ハイライト表示されたソースを表示します。

このオプションは、ファイルをパースし、HTML ハイライト表示版のファイルを生成し、標準出力に書き出す内部機 構を使用します。行うのは <code> [...] </code> のブロックを 生成することだけで、HTML ヘッダは 出力されないことに注意してください。

注意:

このオプションは、-r オプションと同時に 使用することはできません。

-v --version

例6 -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

設定ファイルの名前、設定ファイルを検索するディレクトリを表示します。

例7 --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 が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例8 基本的な --rf の使用法

$ php --rf var_dump
Function [ <internal> public function var_dump ] {

  - Parameters [2] {
    Parameter #0 [ <required> $var ]
    Parameter #1 [ <optional> $... ]
  }
}
--rc --rclass

指定したクラスについての情報 (定数、プロパティおよびメソッドの一覧) を表示します。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例9 --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 が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例10 --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() が返す情報と同じもの) を表示します。

--ri --rextinfo

指定した拡張モジュールについての設定情報 (phpinfo() が返す情報と同じもの) を表示します。 コア機能に関する設定情報は、 "main" というモジュール名で取得できます。

例11 --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 で終わる必要がなく、任意の名前や拡張子を 使用することができます。

  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] の値は "Standard input code" となることに注意しましょう。 PHP 7.2.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 を参照ください。

注意:

Windows では、実際に存在するユーザーアカウントの権限で PHP を実行することを推奨します。 "アカウント名とセキュリティID の間のマッピングは実行されませんでした。" というエラーのため、 ネットワークサービス経由で実行する特定の操作は失敗する場合があります


入出力ストリーム

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 から読み込んだ場合は使用できません。


対話シェル

--with-readline オプションつきで PHP をコンパイルした場合に CLI SAPI で対話シェルが使えるようになりました。 対話シェルは、-a オプションで使うことができます。 PHP 7.1.0 以降では、readline 拡張モジュール が有効であれば 対話シェルは Windows 上でも使用可能です。

対話シェルを使うと、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 >

対話シェル上では、タブ補完機能を使って 関数や定数、クラス名、変数名、static メソッドの呼び出し、 そしてクラス定数を補完することができます。

例2 タブ補完

補完候補が複数あるときにタブキーを二度押すと、 補完候補の一覧が表示されます。

php > strp[TAB][TAB]
strpbrk   strpos    strptime
php > strp

候補がひとつしかないときは、タブキーを一度押せば残りを補完してくれます。

php > strpt[TAB]ime(

対話シェルのセッション上で定義したものについても補完することができます。

php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName

対話シェル上では操作履歴が保存され、上矢印キーと下矢印キーで履歴にアクセスすることができます。 履歴の保存先は ~/.php_history ファイルです。

CLI SAPI では、二つの php.ini 設定が使えます。cli.pager と cli.prompt です。cli.pager は、外部のプログラム (less など) を出力のページャとして指定することができます。 出力が画面に直接送られるかわりに、このページャに送られるようになります。 cli.prompt を指定すると、 php > プロンプトを変更することができます。

また、対話シェルの中では、 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 8.1.0 より前のバージョンでは、readline 拡張モジュールが利用できない場合に、 CLI SAPI を -a オプション付きで呼び出すとインタラクティブモードになっていました。 このモードでは、 完全な PHP スクリプトを標準入力(STDIN)から与えなければいけません。 スクリプトを入力後、CRTL+d (POSIXの場合) や CTRL+z の後に ENTER (Windows) を続けると、その PHP スクリプトが評価されていました。 CLI SAPI を -a なしで呼び出しても基本的に同じ動きをします。

PHP 8.1.0 以降では、 readline 拡張モジュールが利用できない場合、 CLI SAPI に -a オプションを付けた呼び出しは失敗します。


ビルトインウェブサーバー

警告

このウェブサーバーは、アプリケーション開発の支援用として設計されたものです。 テスト用に使ったり、制約のある環境でアプリケーションをデモするために使ったりすることもできるでしょう。 あらゆる機能を兼ね備えたウェブサーバーを目指したものではないので、 公開ネットワーク上で使ってはいけません。

CLI SAPI にはウェブサーバーの機能が組み込まれています。

このウェブサーバーは単一のシングルスレッドプロセスしか実行しないので、 リクエストがブロックされると、PHP アプリケーションはストールします。

URI リクエストの処理は、PHP を開始した時点の作業ディレクトリから行われます。 -t オプションを使えば、ドキュメントルートを明示的に指定することができます。 URI リクエストにファイルが含まれない場合は、指定したディレクトリにある index.php あるいは index.html を返します。どちらも存在しない場合は、 親ディレクトリにさかのぼって index.php と index.html を探します。 どちらか一方が見つかるか、あるいはドキュメントルートに達するまでこれが続きます。 index.php あるいは index.html が見つかるとそれを返し、 $_SERVER['PATH_INFO'] が URI の末尾にセットされます。 見つからなかった場合はレスポンスコード 404 を返します。

ウェブサーバーの開始時にコマンドラインで PHP ファイルを指定すると、 そのファイルをウェブサーバーの "ルーター" スクリプトとして使います。 このスクリプトは、各 HTTP リクエストの開始時に動きます。このスクリプトが false を返すと、リクエストされたリソースをそのままの形式で返します。 それ以外の場合はスクリプトの出力をブラウザに返します。

以下にあげる拡張子のファイルについては、標準の MIME タイプを返します: .3gp, .apk, .avi, .bmp, .css, .csv, .doc, .docx, .flac, .gif, .gz, .gzip, .htm, .html, .ics, .jpe, .jpeg, .jpg, .js, .kml, .kmz, .m4a, .mov, .mp3, .mp4, .mpeg, .mpg, .odp, .ods, .odt, .oga, .ogg, .ogv, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text, .tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, .zip

PHP 7.4.0 以降では、ビルトインウェブサーバーに対して複数のリクエストを並列で投げる必要があるテストコードのために、 複数のワーカーをフォークさせるよう設定できるようになりました。 サーバーを起動する前に欲しいワーカーの数を PHP_CLI_SERVER_WORKERS 環境変数に設定してください。

注意: この機能は Windows ではサポートされていません。

警告

この機能は 実験的なもの であり、 本番環境で使うことを意図した機能では ありません。 ビルトインウェブサーバーは本番環境で使うものではありません。

例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

Windows 環境、かつ PHP 7.4.0 より前のバージョンでは、 ルーティングを行うスクリプトがシンボリックリンク先の静的なリソースを処理しない限り、 それらのリソースにアクセスできませんでした。

例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; // リクエストされたリソースをそのままの形式で扱います。
} else {
echo "<p>Welcome to PHP</p>";
}
?>
$ php -S localhost:8000 router.php

例4 CLI ウェブサーバーを使っているかどうかのチェック

フレームワークのルータースクリプトを、開発中は CLI ウェブサーバーで使って その後は本番環境のウェブサーバーでも使うという例です。

<?php
// router.php
if (php_sapi_name() == 'cli-server') {
/* 静的コンテンツのルーティングをして false を返します */
}
/* 通常の index.php の処理を続きます */
?>
$ php -S localhost:8000 router.php

例5 未サポートのファイル形式の処理

CLI ウェブサーバーで対応していない MIME タイプの静的リソースを扱うには、このようにします。

<?php
// router.php
$path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
if ($path["extension"] == "el") {
header("Content-Type: text/x-script.elisp");
readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
return FALSE;
}
?>
$ php -S localhost:8000 router.php

例6 CLI ウェブサーバーへのリモートマシンからのアクセス

ウェブサーバーを、任意のインターフェイスからポート 8000 でアクセスできるようにするには、このようにします。

$ php -S 0.0.0.0:8000
警告

ビルトインウェブサーバーは、公開ネットワークで使うべきではありません。


INI 設定

CLI SAPI の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
cli_server.color | "0" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

cli_server.color bool

組み込みの開発用ウェブサーバーで、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」を持つ参照 ("is_ref" ビットが true の場合) が 1 の場合、 参照されていないかのように (つまり、is_ref が常に false であったかのように) 扱われる点に注意してください。 もし » Xdebug をインストール済みなら、 xdebug_debug_zval()を呼ぶと、この情報を表示できます。

例2 zval 情報を表示

<?php
$a = "new string";
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' );
$b = 42;
xdebug_debug_zval( 'a' );
unset( $c );
xdebug_debug_zval( 'a' );
?>

上の例の出力は以下となります。

a: (refcount=3, is_ref=0)='new string'
a: (refcount=2, 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
)

つまり、図で示すと

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'
)

つまり、図で示すと

上記の 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)=...
)

つまり、図で示すと

配列変数 (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)=...
)

つまり、図で示すと

片づけの問題

この構造体を指すシンボルがいかなるスコープにももはや存在しないにもかかわらず、 配列要素「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 です。

ガベージコレクタがオンの場合、 ルート・バッファが満杯になるといつでも、先に述べたように循環検出法が実行されます。 ルート・バッファでは、可能性があるルートのサイズが10000件に固定されています。 （PHP のソースコードの Zend/zend_gc.c で GC_THRESHOLD_DEFAULT 定数を変更して、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.14159265359';
public $self;
}

$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.14159265359';
public $self;
}

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 アプリケーションについては、 時がたつにつれて忍び込むメモリリークに関して、新しい機構によるかなりの差が生じなければなりません。


DTrace 動的トレーシング

目次

  • PHP および DTrace への入門
  • PHP および DTrace の使用
  • PHP DTrace 静的プローブとともに SystemTap を使用


PHP および DTrace への入門

DTrace は、常に使用可能で、オーバーヘッドが少なく、 Solaris、macOS、Oracle Linux および BSD を含む 多数のプラットフォーム上で使用可能なトレーシング・フレームワークです。 DTrace は、OS の挙動およびユーザー・プログラムの実行を追跡できます。 それは、引数の値を表示したり、パフォーマンス統計を推定することに使用できます。 プローブは、DTrace D スクリプト言語で書かれた ユーザー作成のスクリプトによりモニターされます。 これにより、データ・ポイントの効率的な分析が可能になります。

ユーザーの DTrace D スクリプトによりアクティブにモニターされていない PHP プローブには計装化コードを含みません。 それは、通常のアプリケーション実行中は、パフォーマンス低下がないからです。 モニターされているプローブのオーバーヘッド負荷は、 一般的に作業中の本番システム上で DTrace をモニターしてもよいほど十分な低さです。

PHP は、ランタイムで駆動された "User-level Statically Defined Tracing (USDT。ユーザーレベルの静的に定義されたトレーシング)" プローブを組み入れます。 例えば、D スクリプトが PHP の function-entry プローブをモニター中の場合、 PHP スクリプトの関数が呼ばれるたびにこのプローブは発射され、 関連付けられた D スクリプトの実行コードが実行されます。 この実行コードは、例えば PHP 関数のソースファイルの場所のような、 プローブの引数を印刷したり、 各関数が呼ばれる回数のようなデータを集計できるでしょう。

PHP USDT プローブの記述はここだけです。 任意の関数をトレースするために DTrace を使用する方法、 および OS の挙動をトレースするための使用方法については、 外部の一般および OS 固有の DTrace の文献を参照ください。 すべての DTrace の機能がすべての DTrace 実装で使用可能とは 限らないことに注意してください。

PHP での静的な DTrace プローブは、 一部の Linux ディストリビューションの SystemTap 機能に対して 代わりに使用できます。


PHP および DTrace の使用

DTrace 動的トレーシングをサポートするプラットフォームでは、 DTrace 静的プローブ付きで PHP を構成できます。

DTrace 静的プローブのために PHP を構成

OS の DTrace サポートを有効にするには、 プラットフォーム固有の外部のドキュメントを参照ください。 例えば、Oracle Linux では UEK3 を起動して下記を行います。

# modprobe fasttrap
# chmod 666 /dev/dtrace/helper

chmod を使用する代わりに、 デバイスのアクセスを特定のユーザーに制限するために ACL パッケージ・ルールを使用できるでしょう。

--enable-dtrace 構成パラメータとともに PHP をビルドします。

# ./configure --enable-dtrace ...
# make
# make install

これは、 コア PHP で静的プローブを有効にします。 それら自身のプローブを提供するどの PHP 拡張モジュールも、 共用拡張モジュールとして別々にビルドするべきです。

コア PHP の DTrace 静的プローブ

PHP では、以下の静的プローブが使用できます
プローブ名 | プローブの説明 | プローブの引数
request-startup | リクエスト開始時に発射されます。 | char *file, char *request_uri, char *request_method
request-shutdown | リクエスト・シャットダウン時に発射されます。 | char *file, char *request_uri, char *request_method
compile-file-entry | スクリプトのコンパイル開始時に発射されます。 | char *compile_file, char *compile_file_translated
compile-file-return | スクリプトのコンパイル終了時に発射されます。 | char *compile_file, char *compile_file_translated
execute-entry | op コードの配列が実行される際に発射されます。 例えば、関数の呼び出し、インクルードおよびジェネレータ続行時に発射されます。 | char *request_file, int lineno
execute-return | op コードの配列の実行後に発射されます。 | char *request_file, int lineno
function-entry | PHP エンジンが、PHP の関数またはメソッドの呼び出しに入り込む際に発射されます。 | char *function_name, char *request_file, int lineno, char *classname, char *scope
function-return | PHP エンジンが、PHP の関数またはメソッドの呼び出しから戻る際に発射されます。 | char *function_name, char *request_file, int lineno, char *classname, char *scope
exception-thrown | 例外がスローされる際に発射されます。 | char *classname
exception-caught | 例外が捕捉される際に発射されます。 | char *classname
error | error_reporting レベルにかかわらず、 エラー発生時に発射されます。 | char *errormsg, char *request_file, int lineno

PHP 拡張モジュールには、追加の静的プローブもあるかもしれません。

PHP の DTrace 静的プローブ一覧

使用できるプローブを一覧表示するには、 PHP プロセスを開始して以下のように実行します。

# dtrace -l

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

   ID   PROVIDER            MODULE                          FUNCTION NAME
   [ . . . ]
    4   php15271               php               dtrace_compile_file compile-file-entry
    5   php15271               php               dtrace_compile_file compile-file-return
    6   php15271               php                        zend_error error
    7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
    8   php15271               php     zend_throw_exception_internal exception-thrown
    9   php15271               php                 dtrace_execute_ex execute-entry
   10   php15271               php           dtrace_execute_internal execute-entry
   11   php15271               php                 dtrace_execute_ex execute-return
   12   php15271               php           dtrace_execute_internal execute-return
   13   php15271               php                 dtrace_execute_ex function-entry
   14   php15271               php                 dtrace_execute_ex function-return
   15   php15271               php              php_request_shutdown request-shutdown
   16   php15271               php               php_request_startup request-startup

PROVIDER 列の値は、php および 現在実行中の PHP プロセスのプロセス ID から構成されます。

Apache Web サーバーが実行中の場合、モジュール名は、例えば libphp5.so かもしれません。 そして、実行中の Apache プロセスごとに 1 つ、 一覧表の複数のブロックが存在するかもしれません。

FUNCTION 列は、各プロバイダが配置された PHP 内部の C 実装関数名を参照します。

PHP プロセスが実行されていない場合、PHP プローブは表示されません。

PHP についての DTrace の例

この例では、DTrace の D スクリプト言語の基本を示します。

例1 DTrace を使用してすべての PHP 静的プローブをトレースするためのall_probes.d

#!/usr/sbin/dtrace -Zs

#pragma D option quiet

php*:::compile-file-entry
{
    printf("PHP compile-file-entry\n");
    printf("  compile_file              %s\n", copyinstr(arg0));
    printf("  compile_file_translated   %s\n", copyinstr(arg1));
}

php*:::compile-file-return
{
    printf("PHP compile-file-return\n");
    printf("  compile_file              %s\n", copyinstr(arg0));
    printf("  compile_file_translated   %s\n", copyinstr(arg1));
}

php*:::error
{
    printf("PHP error\n");
    printf("  errormsg                  %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
}

php*:::exception-caught
{
    printf("PHP exception-caught\n");
    printf("  classname                 %s\n", copyinstr(arg0));
}

php*:::exception-thrown
{
    printf("PHP exception-thrown\n");
    printf("  classname                 %s\n", copyinstr(arg0));
}

php*:::execute-entry
{
    printf("PHP execute-entry\n");
    printf("  request_file              %s\n", copyinstr(arg0));
    printf("  lineno                    %d\n", (int)arg1);
}

php*:::execute-return
{
    printf("PHP execute-return\n");
    printf("  request_file              %s\n", copyinstr(arg0));
    printf("  lineno                    %d\n", (int)arg1);
}

php*:::function-entry
{
    printf("PHP function-entry\n");
    printf("  function_name             %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
    printf("  classname                 %s\n", copyinstr(arg3));
    printf("  scope                     %s\n", copyinstr(arg4));
}

php*:::function-return
{
    printf("PHP function-return\n");
    printf("  function_name             %s\n", copyinstr(arg0));
    printf("  request_file              %s\n", copyinstr(arg1));
    printf("  lineno                    %d\n", (int)arg2);
    printf("  classname                 %s\n", copyinstr(arg3));
    printf("  scope                     %s\n", copyinstr(arg4));
}

php*:::request-shutdown
{
    printf("PHP request-shutdown\n");
    printf("  file                      %s\n", copyinstr(arg0));
    printf("  request_uri               %s\n", copyinstr(arg1));
    printf("  request_method            %s\n", copyinstr(arg2));
}

php*:::request-startup
{
    printf("PHP request-startup\n");
    printf("  file                      %s\n", copyinstr(arg0));
    printf("  request_uri               %s\n", copyinstr(arg1));
    printf("  request_method            %s\n", copyinstr(arg2));
}

このスクリプトは、dtrace に対して -Z オプションを使用します。 それにより、実行中の PHP プロセスがない場合に実行できるようになります。 もしこのオプションが書き落とされた場合、 モニターされているプローブがどれも存在しないことがわかっているので、 スクリプトは即座に終了します。

スクリプトは、PHP スクリプト実行中の期間全体にわたって、 すべてのコア PHP 静的プローブ・ポイントをトレースします。 D スクリプトを実行します。

# ./all_probes.d

PHP スクリプトまたはアプリケーションを実行します。 モニタリングの D スクリプトは、各プローブが発射されるたびに その引数を出力します。

モニタリングが完了した際には、CTRL+C を使用して D スクリプトを終わらせることができます。

マルチ CPU マシンでは、プローブの順序は規則的に連続して表示されないことがあります。 これは、どの CPU がプローブを処理し、 CPU の間をスレッドがどのように移動したかに依存します。 プローブのタイムスタンプを表示すると、 混乱を減らすことができます。 その例です。

php*:::function-entry
{
      printf("%lld: PHP function-entry ", walltimestamp);
      [ . . .]
}

参考

  • OCI8 および DTrace 動的トレーシング


PHP DTrace 静的プローブとともに SystemTap を使用

一部の Linux ディストリビューションでは、 PHP の静的な DTrace プローブをトレースするために SystemTap トレーシング・ユーティリティを使用できます。 これは、PHP 5.4.20 および PHP 5.5 で使用できます。

SystemTap とともに PHP をインストール

SystemTap SDT 開発パッケージをインストールします。

# yum install systemtap-sdt-devel

DTrace プローブが有効化された状態で PHP をインストールします。

# ./configure --enable-dtrace ...
# make

SystemTap による静的プローブ一覧

stap を使用して PHP の静的プローブを一覧表示できます。

# stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

この出力です。

process("sapi/cli/php").provider("php").mark("compile__file__entry")
process("sapi/cli/php").provider("php").mark("compile__file__return")
process("sapi/cli/php").provider("php").mark("error")
process("sapi/cli/php").provider("php").mark("exception__caught")
process("sapi/cli/php").provider("php").mark("exception__thrown")
process("sapi/cli/php").provider("php").mark("execute__entry")
process("sapi/cli/php").provider("php").mark("execute__return")
process("sapi/cli/php").provider("php").mark("function__entry")
process("sapi/cli/php").provider("php").mark("function__return")
process("sapi/cli/php").provider("php").mark("request__shutdown")
process("sapi/cli/php").provider("php").mark("request__startup")

PHP についての SystemTap の例

例1 SystemTap を使用してすべての PHP 静的プローブをトレースするためのall_probes.stp

probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
    printf("Probe compile__file__entry\n");
    printf("  compile_file %s\n", user_string($arg1));
    printf("  compile_file_translated %s\n", user_string($arg2));
}
probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
    printf("Probe compile__file__return\n");
    printf("  compile_file %s\n", user_string($arg1));
    printf("  compile_file_translated %s\n", user_string($arg2));
}
probe process("sapi/cli/php").provider("php").mark("error") {
    printf("Probe error\n");
    printf("  errormsg %s\n", user_string($arg1));
    printf("  request_file %s\n", user_string($arg2));
    printf("  lineno %d\n", $arg3);
}
probe process("sapi/cli/php").provider("php").mark("exception__caught") {
    printf("Probe exception__caught\n");
    printf("  classname %s\n", user_string($arg1));
}
probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
    printf("Probe exception__thrown\n");
    printf("  classname %s\n", user_string($arg1));
}
probe process("sapi/cli/php").provider("php").mark("execute__entry") {
    printf("Probe execute__entry\n");
    printf("  request_file %s\n", user_string($arg1));
    printf("  lineno %d\n", $arg2);
}
probe process("sapi/cli/php").provider("php").mark("execute__return") {
    printf("Probe execute__return\n");
    printf("  request_file %s\n", user_string($arg1));
    printf("  lineno %d\n", $arg2);
}
probe process("sapi/cli/php").provider("php").mark("function__entry") {
    printf("Probe function__entry\n");
    printf("  function_name %s\n", user_string($arg1));
    printf("  request_file %s\n", user_string($arg2));
    printf("  lineno %d\n", $arg3);
    printf("  classname %s\n", user_string($arg4));
    printf("  scope %s\n", user_string($arg5));
}
probe process("sapi/cli/php").provider("php").mark("function__return") {
    printf("Probe function__return: %s\n", user_string($arg1));
    printf(" function_name %s\n", user_string($arg1));
    printf("  request_file %s\n", user_string($arg2));
    printf("  lineno %d\n", $arg3);
    printf("  classname %s\n", user_string($arg4));
    printf("  scope %s\n", user_string($arg5));
}
probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
    printf("Probe request__shutdown\n");
    printf("  file %s\n", user_string($arg1));
    printf("  request_uri %s\n", user_string($arg2));
    printf("  request_method %s\n", user_string($arg3));
}
probe process("sapi/cli/php").provider("php").mark("request__startup") {
    printf("Probe request__startup\n");
    printf("  file %s\n", user_string($arg1));
    printf("  request_uri %s\n", user_string($arg2));
    printf("  request_method %s\n", user_string($arg3));
}

上記のスクリプトは、PHP スクリプト実行中の期間全体にわたって、 すべてのコア PHP 静的プローブ・ポイントをトレースします。

# stap -c 'sapi/cli/php test.php' all_probes.stp


関数リファレンス

ヒント

参考 拡張モジュールの一覧/分類.

  • PHP の振る舞いの変更
    • APCu — APC User Cache
    • Componere
    • エラー処理 — エラー処理およびログ記録
    • FFI — Foreign Function Interface
    • OPcache
    • 出力制御 — 出力バッファリング制御
    • PHP Options/Info — PHP オプションと情報
    • phpdbg — 対話的な PHP デバッガ
    • runkit7
    • uopz — Zend に対するユーザー操作
    • WinCache — PHP 用の Windows キャッシュ
    • Xhprof — 階層型プロファイラ
    • Yac
  • 音声フォーマットの操作
    • OpenAL — OpenAL 音声バインディング
  • 認証サービス
    • Radius
  • コマンドライン関連
    • Readline — GNU Readline
  • 圧縮およびアーカイブ
    • Bzip2
    • LZF
    • Phar
    • Rar — Rar アーカイブ
    • Zip
    • Zlib — Zlib 圧縮
  • 暗号
    • Hash — HASH メッセージダイジェストフレームワーク
    • Mcrypt
    • Mhash
    • OpenSSL
    • パスワードのハッシュ
    • Rnp
    • Sodium
  • データベース関連
    • 抽象化レイヤー
    • ベンダー固有のモジュール
  • 日付および時刻関連
    • カレンダー
    • Date/Time — 日付・時刻
    • HRTime — High resolution timing
  • ファイルシステム
    • ダイレクト IO
    • ディレクトリ
    • Fileinfo — ファイル情報
    • ファイルシステム
    • Inotify
    • xattr
    • xdiff
  • 自然言語および文字エンコーディング
    • Enchant — Enchant スペリングライブラリ
    • Gender — 名前の性別の判別
    • Gettext
    • iconv
    • intl — 国際化関数
    • マルチバイト文字列
    • Pspell
    • Recode — GNU Recode
  • 画像処理および作成
    • Exif — Exchangeable image information
    • GD — 画像処理 (GD)
    • Gmagick
    • ImageMagick — 画像処理 (ImageMagick)
  • メール関連
    • IMAP — IMAP、POP3 および NNTP
    • メール
    • Mailparse
  • 数学
    • BC Math — BCMath 任意精度数学関数
    • GMP — GNU Multiple Precision
    • Math — 数学関数
    • Statistics
    • Trader — Technical Analysis for Traders
  • テキスト以外の MIME 型
    • FDF — Forms Data Format
    • GnuPG — GNU Privacy Guard
    • wkhtmltox
    • PS — PostScript ドキュメントの作成
    • RpmInfo
    • XLSWriter
  • プロセス制御
    • Eio
    • Ev
    • Expect
    • PCNTL — プロセス制御
    • POSIX
    • プログラムの実行 — システムプログラムの実行
    • parallel
    • pthreads
    • セマフォ — セマフォ、共有メモリおよび IPC
    • 共有メモリ
    • Sync
  • その他の基本モジュール
    • GeoIP — Geo IP ロケーション
    • FANN — FANN (Fast Artificial Neural Network)
    • Igbinary
    • JSON — JavaScript Object Notation
    • Simdjson
    • Lua
    • LuaSandbox
    • その他 — その他の関数
    • Random — 乱数生成器および、乱数関連の関数
    • Seaslog
    • SPL — Standard PHP Library (SPL)
    • ストリーム
    • Swoole
    • Tidy
    • Tokenizer
    • URLs
    • V8js — V8 JavaScript Engine 統合
    • Yaml — YAML によるデータのシリアライズ
    • Yaf — Yet Another Framework (Yaf)
    • Yaconf
    • Taint
    • Data Structures
    • var_representation
  • その他のサービス
    • cURL — Client URL Library
    • Event
    • FTP
    • Gearman
    • LDAP — Lightweight Directory Access Protocol
    • Memcache
    • Memcached
    • mqseries
    • ネットワーク
    • RRD — RRDtool
    • ScoutAPM
    • SNMP
    • ソケット
    • SSH2 — Secure Shell2
    • Stomp — Stomp Client
    • SVM — サポートベクターマシン
    • SVN — Subversion
    • TCP — TCP ラッパー
    • Varnish
    • YAZ
    • 0MQ messaging — ZMQ
    • ZooKeeper
  • 検索エンジン用の拡張モジュール
    • Solr — Apache Solr
  • サーバー固有のモジュール
    • Apache
    • FastCGI Process Manager(FPM)
  • セッション関連
    • Sessions — セッション処理
  • テキスト処理
    • CommonMark
    • Parle — Parsing and lexing
    • PCRE — 正規表現 (Perl 互換)
    • ssdeep — ssdeep Fuzzy Hashing
    • 文字列
  • 変数・データ型関連
    • 配列
    • クラス/オブジェクト — クラス/オブジェクトの情報
    • Ctype — 文字タイプチェック
    • Filter — データのフィルタリング
    • 関数処理
    • Quickhash
    • リフレクション
    • 変数操作
  • ウェブサービス
    • OAuth
    • SOAP
    • Yar — Yet Another RPC Framework
    • XML-RPC
  • Windows 用のモジュール
    • COM — COM および .Net (Windows)
    • win32service
  • XML 操作
    • DOM — Document Object Model
    • libxml
    • SimpleXML
    • WDDX
    • XMLDiff — XML diff and merge
    • XML パーサ
    • XMLReader
    • XMLWriter
    • XSL
  • GUI用の拡張モジュール
    • UI


PHP の振る舞いの変更

  • APCu — APC User Cache
    • はじめに
    • インストール/設定
    • 定義済み定数
    • APCu 関数
    • APCUIterator — APCUIterator クラス
  • Componere
    • はじめに
    • インストール/設定
    • Componere\Abstract\Definition — The Componere\Abstract\Definition class
    • Componere\Definition — The Componere\Definition class
    • Componere\Patch — The Componere\Patch class
    • Componere\Method — The Componere\Method class
    • Componere\Value — The Componere\Value class
    • Componere 関数
  • エラー処理 — エラー処理およびログ記録
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • エラー処理関数
  • FFI — Foreign Function Interface
    • はじめに
    • インストール/設定
    • 例
    • FFI — Main interface to C code and data
    • FFI\CData — C Data Handles
    • FFI\CType — C Type Handles
    • FFI\Exception — FFI Exceptions
    • FFI\ParserException — FFI Parser Exceptions
  • OPcache
    • はじめに
    • インストール/設定
    • コードの事前ロード
    • OPcache 関数
  • 出力制御 — 出力バッファリング制御
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 出力バッファリング
    • システムバッファのフラッシュ
    • ユーザーレベルの出力バッファ
    • 例
    • 出力制御 関数
  • PHP Options/Info — PHP オプションと情報
    • はじめに
    • インストール/設定
    • 定義済み定数
    • PHP オプション/情報 関数
  • phpdbg — 対話的な PHP デバッガ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • phpdbg 関数
  • runkit7
    • はじめに
    • インストール/設定
    • 定義済み定数
    • runkit7 関数
  • uopz — Zend に対するユーザー操作
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Uopz 関数
  • WinCache — PHP 用の Windows キャッシュ
    • はじめに
    • インストール/設定
    • WinCache 関数
    • Windows でのビルド
  • Xhprof — 階層型プロファイラ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Xhprof 関数
  • Yac
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Yac — The Yac class


APC User Cache

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • APCu 関数
    • apcu_add — 新規の変数をデータ領域にキャッシュする
    • apcu_cache_info — APCu のデータから、キャッシュされた情報を取得する
    • apcu_cas — 古い値を新しい値に更新する
    • apcu_clear_cache — APCu キャッシュをクリアする
    • apcu_dec — 保存した数値を減らす
    • apcu_delete — 格納されている変数をキャッシュから取り除く
    • apcu_enabled — 現在の環境で apcu が使えるかを確認する
    • apcu_entry — アトミックに値を取得するか、キャッシュエントリを生成する
    • apcu_exists — エントリが存在するかどうかを調べる
    • apcu_fetch — 格納されている変数をキャッシュから取得する
    • apcu_inc — 保存した数値を増やす
    • apcu_key_info — キャッシュのキーに関する詳細な情報を取得する
    • apcu_sma_info — APCu の共有メモリ割り当てに関する情報を取得する
    • apcu_store — 変数をデータ領域にキャッシュする
  • APCUIterator — APCUIterator クラス
    • APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する
    • APCUIterator::current — 現在の項目を取得する
    • APCUIterator::getTotalCount — 総数を取得する
    • APCUIterator::getTotalHits — キャッシュヒットの総数を取得する
    • APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する
    • APCUIterator::key — イテレータのキーを取得する
    • APCUIterator::next — ポインタを次の項目に移動させる
    • APCUIterator::rewind — イテレータを巻き戻す
    • APCUIterator::valid — 現在位置が有効かどうかを調べる


はじめに

APCu は、PHP で動くインメモリの key-value ストアです。 キーは文字列型で、値は任意のPHPの変数を保存できます。 APCu はユーザーランドの変数のキャッシュのみをサポートしています。

APCu のキャッシュは、Windows ではプロセス単位で機能します。 そのため、(スレッドベースではない) プロセスベースの SAPI を使う場合、 異なるプロセスをまたがってキャッシュは共有されません。

APCu は APC から opcode のキャッシュ機能を除いたものです。

一番はじめの APCu のコードベースには 4.0.0 というバージョンが付けられました。 これは当時の APC の master ブランチの最新版からフォークした時点のものです。

APCu 5.0.0 以降で PHP 7 がサポートされています。 PHP 8 は APCu 5.1.19 以降でサポートされています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • APCu
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/apcu.

ヒント

PHP 7 では、APC との後方互換性を保った別モジュール (» apcu-bc) を提供しています。

後方互換モードの場合、APCu は適切な APC 関数を 後方互換を保ったプロトタイプと一緒に登録します。

APC 関数が cache_type を受け入れる場合、 後方互換モードが有効なバージョンではそれを単に無視します。 そして、APCu 版のプロトタイプからは省略されます。

警告

PHP 8 では、apcu-bc はもはやサポートされていません。

注意: Windows では、既に存在しており、 かつ Webサーバーから書き込み可能な temp path が必要です。 APCu は TMP, TEMP, USERPROFILE 環境変数をこの順でチェックし、 これらに値がセットされていない場合は WINDOWS ディレクトリを最後に調べます。

注意: さらに細かい、技術的に高度な実装の詳細については、 » 開発者が提供している TECHNOTES ファイル を参照ください。

APCu のソースコードは、» ここ で見ることが出来ます。


実行時設定

php.ini の設定により動作が変化します。

大半のインストール環境では、APCu はデフォルトの設定で問題ありません。 しかし、本格的なユーザーは以下のパラメータのチューニングを考慮すべきです。

APCuを設定するには、ひとつ決断が必要です。 どれくらいのメモリをAPCuに割り当てるのかということです。 この値を制御するのは apc.shm_size です。 以下のこれに関するセクションを注意深く読んで下さい。

サーバーがいったん起動したら、 拡張モジュールにバンドルされている apc.php スクリプトをドキュメントルートのどこかにコピーし、ブラウザから見てみましょう。 apcu の内部動作を詳細に分析した情報が見られるからです。 gd が有効になっている場合、面白いグラフも見られるでしょう。

apcu が動作している場合、(左側の) Cache full count の数が、キャッシュの容量が一杯になり、 メモリを開放するためにエントリを強制的に掃除しなければならなかった回数を示しています。 強制的に掃除している間、apc.ttl が指定されている場合、 APCu はまず期限切れのエントリを削除しようとします。 つまり、TTL が期限切れになったか、 TTL が設定されずに apc.ttl 秒間アクセスがないエントリです。 apc.ttl が指定されていないか、 期限切れのエントリを削除しても十分な容量を確保できない場合、 APCu はキャッシュ全体を削除してしまいます。

強制的に掃除しなければならなかった回数は、 上手に設定されているキャッシュであれば最小にすべきです。 キャッシュが頻繁に一杯になり、強制的に開放される場合、 スクリプトのパフォーマンスに悪影響が出てしまいます。 この数値を最小にする一番簡単な方法は、APCu により多くのメモリを割り当てることです。

APCu が mmap (メモリマッピング) のサポートを有効にしてコンパイルされている場合、 APCu はメモリセグメントをひとつしか使いません。 一方で、SHM (SysV共有メモリ) を有効にしてビルドした場合は、複数のメモリセグメントを使います。 SHM は /proc/sys/kernel/shmmax で最大値を持っていますが、MMAP にはそれがありません。 一般的には、MMAP のサポートを有効にすることをおすすめします。 なぜなら、MMAPはWebサーバーが再起動したときのメモリの再要求の速度が速く、 全体として起動時のメモリ割り当ての負荷が減るからです。

APCu の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
apc.enabled | 1 | INI_SYSTEM |
apc.shm_segments | 1 | INI_SYSTEM |
apc.shm_size | "32M" | INI_SYSTEM |
apc.entries_hint | 4096 | INI_SYSTEM |
apc.ttl | 0 | INI_SYSTEM |
apc.gc_ttl | 3600 | INI_SYSTEM |
apc.mmap_file_mask | NULL | INI_SYSTEM |
apc.slam_defense | 0 | INI_SYSTEM |
apc.enable_cli | 0 | INI_SYSTEM |
apc.use_request_time | 0 | INI_ALL | APCu 5.1.19 より前のバージョンでは、デフォルト値は 1 でした。
apc.serializer | "php" | INI_SYSTEM | APCu 5.1.15 より前のバージョンでは、デフォルト値は "default" でした。
apc.coredump_unmap | 0 | INI_SYSTEM |
apc.preload_path | NULL | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

apc.enabled bool

APC を無効にする場合、apc.enabled を0に設定できます。 これはAPCがPHPに静的にコンパイルされている場合に役に立ちます。 なぜなら、これ以外にAPCを無効にする方法がないからです。 (DSO としてコンパイルされている場合、 php.ini の extension の行をコメントアウトすれば済みます)

apc.shm_segments int

コンパイラキャッシュに割り当てる共有メモリセグメントの数。 APC の共有メモリが不足したが、apc.shm_size にシステムが許可できるできるだけ高い値を設定している場合、 この値を増やすことでAPCがメモリ不足になることを避けられるかもしれません。

apc.shm_size string

個別の共有メモリセグメントのサイズ。 このFAQ で説明している短縮記法を使います。 デフォルトでは、システムによって(ほとんどのBSD系)は、 共有メモリセグメントのサイズの限界値がとても小さい場合があります。

apc.entries_hint int

異なる値を保存する数のおおよその"ヒント"。 わからない場合はゼロを設定して下さい。

apc.ttl int

ここで指定された秒数アクセスされていない場合、 TTL を明示的に指定しないキャッシュエントリが期限切れとみなされます。 こうすることで、キャッシュを挿入している間や、すべてのキャッシュを削除する前に、 そうした期限切れのエントリを都合よく削除できます。 こうした削除は場当たり的に行われるため、 apc.ttl 秒より古いデータであっても まだ読み取れてしまうことがあり得るので注意してください。 この設定は、TTLが明示的に指定されたキャッシュエントリに対しては意味がありません。

apc.gc_ttl int

キャッシュエントリがガベージコレクションのリストに残っても良い秒数。 この値はキャッシュされたソースファイルを実行中にWebサーバーが死んだ場合のフェイルセーフを提供します。 つまり、このソースファイルが変更された場合、 古いバージョンに割り当てられたメモリはTTLに達するまで絶対に要求されないからです。 この機能を無効にするにはゼロを設定して下さい。

apc.mmap_file_mask string

--enable-mmap を使ってPHPをコンパイルした場合に、 mmapされたメモリ領域をファイルベースか共有メモリベースにするかを決めるために、 mmapモジュールに渡すmktempスタイルのファイルマスク。 ファイルベースのmmapの場合、 /tmp/apc.XXXXXX のように設定します (X はちょうど6つにして下さい)。 POSIXスタイルの shm_open/mmap を使う場合、 .shm をマスクのどこかに含めて下さい。 e.g. /apc.shm.XXXXXX。 匿名のmmapされたメモリを使うために kernel の /dev/zero インターフェイスを使う場合、 この値に /dev/zero も設定できます。

apc.slam_defense bool

とても負荷が高いサーバーでは、いつサーバーを起動したり、 変更したりしても、同じファイルを同時にキャッシュしようとする 多くのプロセスの競合が発生します。 apc.slam_defense の値を 1 に設定すると、確率的な仕組みを使うことで、 複数のプロセスが同時に同じファイルをキャッシュするのを防ぐのを助けます。 同じキーが短期間に異なるプロセスからキャッシュされようとすると、 現在のプロセスがキャッシュをスラム化させるのを防ぐため、 キャッシュをスキップします。

apc.enable_cli int

この設定はほとんどの場合、テストかデバッグに使います。 これを設定すると、CLI版PHPでAPCが有効になります。 通常の状態では、CLI リクエストのたびにAPCキャッシュを生成し、 収集し、破棄するのは望ましくありません。しかし、テストシナリオによっては、 CLI版のPHPでAPCを簡単に有効に出来た方が便利な場合があります。

apc.serializer string

APCにサードパーティーのシリアライザを使わせる場合に使います。

apc.coredump_unmap bool

SIGSEGV のようなシグナルのシグナルハンドラをAPCで有効にします。 ハンドラでは、シグナルを受け取ったときにコアファイルに書き込みます。 これらのシグナルを受け取った場合、 APC はコアファイルから除外するために共有メモリセグメントをアンマップしようとします。 この設定は致命的なシグナルを受け取ったり、 APCの共有メモリセグメントの数を大きく設定している場合に、 システムの安定性を向上させる可能性があります。

警告

この機能は潜在的に危険です。 致命的なシグナルハンドラで共有メモリセグメントをアンマップすると、 致命的なエラーが発生したときの動作が未定義になる可能性があるからです。

注意:

kernel によっては、コアダンプファイルを生成するときに 様々なタイプの共有メモリを無視する機能を提供するものがあります。 こうしたkernelの実装は、 Apache scoreboard のような重要な共有メモリセグメントも無視するかもしれません。

apc.preload_path string

オプション。キャッシュデータを起動時に読み込むディレクトリのパスを設定します。

apc.use_request_time bool

TTL に SAPI リクエストの開始時刻を使います。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

APC_ITER_ALL (int)
APC_ITER_ATIME (int)
APC_ITER_CTIME (int)
APC_ITER_DEVICE (int)
APC_ITER_DTIME (int)
APC_ITER_FILENAME (int)
APC_ITER_INODE (int)
APC_ITER_KEY (int)
APC_ITER_MD5 (int)
APC_ITER_MEM_SIZE (int)
APC_ITER_MTIME (int)
APC_ITER_NONE (int)
APC_ITER_NUM_HITS (int)
APC_ITER_REFCOUNT (int)
APC_ITER_TTL (int)
APC_ITER_TYPE (int)
APC_ITER_VALUE (int)
APC_LIST_ACTIVE (int)
APC_LIST_DELETED (int)


APCu 関数

目次

  • apcu_add — 新規の変数をデータ領域にキャッシュする
  • apcu_cache_info — APCu のデータから、キャッシュされた情報を取得する
  • apcu_cas — 古い値を新しい値に更新する
  • apcu_clear_cache — APCu キャッシュをクリアする
  • apcu_dec — 保存した数値を減らす
  • apcu_delete — 格納されている変数をキャッシュから取り除く
  • apcu_enabled — 現在の環境で apcu が使えるかを確認する
  • apcu_entry — アトミックに値を取得するか、キャッシュエントリを生成する
  • apcu_exists — エントリが存在するかどうかを調べる
  • apcu_fetch — 格納されている変数をキャッシュから取得する
  • apcu_inc — 保存した数値を増やす
  • apcu_key_info — キャッシュのキーに関する詳細な情報を取得する
  • apcu_sma_info — APCu の共有メモリ割り当てに関する情報を取得する
  • apcu_store — 変数をデータ領域にキャッシュする


新規の変数をデータ領域にキャッシュする

  • ≪ APCu 関数
  • apcu_cache_info ≫
  • PHP Manual
  • APCu 関数
  • 新規の変数をデータ領域にキャッシュする

apcu_add

(PECL apcu >= 4.0.0)

apcu_add — 新規の変数をデータ領域にキャッシュする

説明

apcu_add(string $key, mixed $var, int $ttl = 0): bool
apcu_add(array $values, mixed $unused = NULL, int $ttl = 0): array

まだ保存されていない場合にのみ、変数をデータ領域にキャッシュします。

注意: PHP の他の多くの仕組みと異なり、apcu_add() を用いて格納された変数はリクエストを超えて （その値がキャッシュから取り除かれるまで）持続します。

パラメータ

key

この名前を用いて変数を格納します。key は キャッシュ内で一意です。そのため、apcu_add() を使用して同一の key で新しい値を格納しようとしても、それは保存されません。 かわりに false が返されます (これが、apcu_add() と apcu_store() の唯一の相違点です)。

var

格納する変数。

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

values

名前をキー、変数を値に指定します。

戻り値

何かがキャッシュに正しく追加されたときに TRUE、それ以外の場合に FALSE を返します。 二番目の構文は、エラーになったキーを含む配列を返します。

例

例1 apcu_add() の例

<?php
$bar = 'BAR';
apcu_add('foo', $bar);
var_dump(apcu_fetch('foo'));
echo "\n";
$bar = 'NEVER GETS SET';
apcu_add('foo', $bar);
var_dump(apcu_fetch('foo'));
echo "\n";
?>

上の例の出力は以下となります。

string(3) "BAR"
string(3) "BAR"

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く


APCu のデータから、キャッシュされた情報を取得する

  • ≪ apcu_add
  • apcu_cas ≫
  • PHP Manual
  • APCu 関数
  • APCu のデータから、キャッシュされた情報を取得する

apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — APCu のデータから、キャッシュされた情報を取得する

説明

apcu_cache_info(bool $limited = false): array|false

APC のデータから、キャッシュされた情報およびメタデータを取得します。

パラメータ

limited

limited が true の場合は、 戻り値にキャッシュエントリの個々の一覧が含まれません。 これは、統計情報の収集時に呼び出しを最適化したい場合などに有用です。

戻り値

キャッシュされたデータ（およびメタデータ）の配列を返します。 失敗した場合に false を返します

注意: もし APC キャッシュのデータを取得できなかった場合、 apcu_cache_info() は警告を発生します。これが起こるのは、 一般的には APC が有効になっていない場合などです。

変更履歴

バージョン | 説明
PECL apcu 3.0.11 | limited パラメータが追加されました。
PECL apcu 3.0.16 | "filehits" オプションが cache_type パラメータに追加されました。

例

例1 apcu_cache_info() の例

<?php
print_r(apcu_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/apcu_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)
)

参考

  • APCu 設定ディレクティブ
  • APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
  • APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
  • APCUIterator::getTotalCount() - 総数を取得する


古い値を新しい値に更新する

  • ≪ apcu_cache_info
  • apcu_clear_cache ≫
  • PHP Manual
  • APCu 関数
  • 古い値を新しい値に更新する

apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — 古い値を新しい値に更新する

説明

apcu_cas(string $key, int $old, int $new): bool

apcu_cas() は、既に保存されている整数値が old パラメータにマッチする値のときに、それを new パラメータの値に更新します。

パラメータ

key

更新する値のキー。

old

古い値 (現在保存されている値)。

new

新しく更新したい値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 apcu_cas() の例

<?php
apcu_store('foobar', 2);
echo '$foobar = 2', PHP_EOL;
echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

apcu_store('perfection', 'xyz');
echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

echo '$foobar = ', apcu_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

参考

  • apcu_dec() - 保存した数値を減らす
  • apcu_store() - 変数をデータ領域にキャッシュする


APCu キャッシュをクリアする

  • ≪ apcu_cas
  • apcu_dec ≫
  • PHP Manual
  • APCu 関数
  • APCu キャッシュをクリアする

apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — APCu キャッシュをクリアする

説明

apcu_clear_cache(): bool

キャッシュをクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。

参考

  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する


保存した数値を減らす

  • ≪ apcu_clear_cache
  • apcu_delete ≫
  • PHP Manual
  • APCu 関数
  • 保存した数値を減らす

apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — 保存した数値を減らす

説明

apcu_dec(
string $key,
int $step = 1,
bool &$success = ?,
int $ttl = 0
): int|false

保存した整数値を減らします。

パラメータ

key

減らしたい値のキー。

step

減らしたい数。

success

この参照渡しの変数に、成功したか失敗したかの結果が格納されます。

ttl

(既存の値を減らすのではなく) 新しい値を挿入する操作に使うTTL

戻り値

成功した場合に key の現在値を返します。 失敗した場合に false を返します

例

例1 apcu_dec() の例

<?php
echo "Let's do something with success", PHP_EOL;

apcu_store('anumber', 42);

echo apcu_fetch('anumber'), PHP_EOL;

echo apcu_dec('anumber'), PHP_EOL;
echo apcu_dec('anumber', 10), PHP_EOL;
echo apcu_dec('anumber', 10, $success), PHP_EOL;

var_dump($success);

echo "Now, let's fail", PHP_EOL, PHP_EOL;

apcu_store('astring', 'foo');

$ret = apcu_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)

参考

  • apcu_inc() - 保存した数値を増やす


格納されている変数をキャッシュから取り除く

  • ≪ apcu_dec
  • apcu_enabled ≫
  • PHP Manual
  • APCu 関数
  • 格納されている変数をキャッシュから取り除く

apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — 格納されている変数をキャッシュから取り除く

説明

apcu_delete(mixed $key): mixed

格納されている変数をキャッシュから取り除きます。

パラメータ

key

単一のキーの文字列、複数のキーの文字列の配列、 または APCUIterator オブジェクトとして 値を格納するために使用されるキー。

戻り値

key が array の場合、 インデックスが振られた array のキーが返されます。 そうでない場合、成功したら true 失敗したら false が返されます。

例

例1 apcu_delete() の例

<?php
$bar = 'BAR';
apcu_store('foo', $bar);
apcu_delete('foo');
// もちろん、このような使い方は無意味

// 複数のキーを削除することもできます。
apcu_delete(['foo', 'bar', 'baz']);

// または、正規表現とともに Iterator を使用します。
apcu_delete(new APCUIterator('#^myprefix_#'));
?>

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_clear_cache() - APCu キャッシュをクリアする
  • APCUIterator


現在の環境で apcu が使えるかを確認する

  • ≪ apcu_delete
  • apcu_entry ≫
  • PHP Manual
  • APCu 関数
  • 現在の環境で apcu が使えるかを確認する

apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — 現在の環境で apcu が使えるかを確認する

説明

apcu_enabled(): bool

現在の環境で apcu が使えるかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の環境で apcu が使えるなら true を、そうでなければ false を返します。


アトミックに値を取得するか、キャッシュエントリを生成する

  • ≪ apcu_enabled
  • apcu_exists ≫
  • PHP Manual
  • APCu 関数
  • アトミックに値を取得するか、キャッシュエントリを生成する

apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — アトミックに値を取得するか、キャッシュエントリを生成する

説明

apcu_entry(string $key, callable $generator, int $ttl = 0): mixed

キャッシュに key が存在するかをアトミックに検索します。 存在しなければ generator が呼び出され、 key が唯一の引数として渡されます。 generator ではオプションで指定する ttl の間だけ値をキャッシュし、 キャッシュした値が返されます。

注意: apcu_entry() 関数に制御が移ると、 キャッシュのロックを排他的に取得します。 このロックは apcu_entry() の実行が終わったときに開放されます: この結果、generator はクリティカルセクションに入るため、 ふたつのプロセスが同時に同じコードパスを実行することができなくなります。 さらに、他のAPCuのあらゆる関数も同時に並列に実行できなくなります。 なぜなら、同じロックを共有しているからです。

警告

generator から安全に呼び出せるAPCuの関数は apcu_entry() だけです。

パラメータ

key

キャッシュエントリのキー。

generator

key を唯一の引数として取り、 キャッシュする値を返す関数

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

戻り値

キャッシュされた値を返します。

例

例1 apcu_entry() の例

<?php
$config = apcu_entry("config", function($key) {
return [
"fruit" => apcu_entry("config.fruit", function($key){
return [
"apples",
"pears"
];
}),
"people" => apcu_entry("config.people", function($key){
return [
"bob",
"joe",
"niki"
];
})
];
});

var_dump($config);
?>

上の例の出力は以下となります。

array(2) {
  ["fruit"]=>
  array(2) {
    [0]=>
    string(6) "apples"
    [1]=>
    string(5) "pears"
  }
  ["people"]=>
  array(3) {
    [0]=>
    string(3) "bob"
    [1]=>
    string(3) "joe"
    [2]=>
    string(4) "niki"
  }
}

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く


エントリが存在するかどうかを調べる

  • ≪ apcu_entry
  • apcu_fetch ≫
  • PHP Manual
  • APCu 関数
  • エントリが存在するかどうかを調べる

apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — エントリが存在するかどうかを調べる

説明

apcu_exists(string|array $keys): bool|array

指定した APCu エントリが存在するかどうかを調べます。

パラメータ

keys

キーを含む文字列、あるいは文字列の配列。

戻り値

キーが存在する場合に true、それ以外の場合に false を返します。 keys に配列を渡したときは、 存在するキーをすべて含む配列を返します。 どれも存在しない場合は空の配列を返します。

例

例1 apcu_exists() の例

<?php
$fruit = 'apple';
$veggie = 'carrot';

apcu_store('foo', $fruit);
apcu_store('bar', $veggie);

if (apcu_exists('foo')) {
echo "Foo exists: ";
echo apcu_fetch('foo');
} else {
echo "Foo does not exist";
}

echo PHP_EOL;
if (apcu_exists('baz')) {
echo "Baz exists.";
} else {
echo "Baz does not exist";
}

echo PHP_EOL;

$ret = apcu_exists(array('foo', 'donotexist', 'bar'));
var_dump($ret);

?>

上の例の出力は、 たとえば以下のようになります。

Foo exists: apple
Baz does not exist
array(2) {
  ["foo"]=>
  bool(true)
  ["bar"]=>
  bool(true)
}

参考

  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する
  • apcu_fetch() - 格納されている変数をキャッシュから取得する


格納されている変数をキャッシュから取得する

  • ≪ apcu_exists
  • apcu_inc ≫
  • PHP Manual
  • APCu 関数
  • 格納されている変数をキャッシュから取得する

apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — 格納されている変数をキャッシュから取得する

説明

apcu_fetch(mixed $key, bool &$success = ?): mixed

エントリをキャッシュから取得します。

パラメータ

key

(apcu_store() を用いて) 値を格納する際に使用された key。 配列を渡した場合は、各要素について取得した値を返します。

success

成功した場合に true、失敗した際に false が設定されます。

戻り値

成功した場合に格納されていた変数 (あるいは配列)、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL apcu 3.0.17 | success パラメータが追加されました。

例

例1 apcu_fetch() の例

<?php
$bar = 'BAR';
apcu_store('foo', $bar);
var_dump(apcu_fetch('foo'));
?>

上の例の出力は以下となります。

string(3) "BAR"

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_delete() - 格納されている変数をキャッシュから取り除く
  • APCUIterator


保存した数値を増やす

  • ≪ apcu_fetch
  • apcu_key_info ≫
  • PHP Manual
  • APCu 関数
  • 保存した数値を増やす

apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — 保存した数値を増やす

説明

apcu_inc(
string $key,
int $step = 1,
bool &$success = ?,
int $ttl = 0
): int|false

保存した整数値を増やします。

パラメータ

key

増やしたい値のキー。

step

増やしたい数。

success

この参照渡しの変数に、成功したか失敗したかの結果が格納されます。

ttl

(既存の値を増やすのではなく) 新しい値を挿入する操作に使うTTL

戻り値

成功した場合に key の現在値を返します。 失敗した場合に false を返します

例

例1 apcu_inc() の例

<?php
echo "Let's do something with success", PHP_EOL;

apcu_store('anumber', 42);

echo apcu_fetch('anumber'), PHP_EOL;

echo apcu_inc('anumber'), PHP_EOL;
echo apcu_inc('anumber', 10), PHP_EOL;
echo apcu_inc('anumber', 10, $success), PHP_EOL;

var_dump($success);

echo "Now, let's fail", PHP_EOL, PHP_EOL;

apcu_store('astring', 'foo');

$ret = apcu_inc('astring', 1, $fail);

var_dump($ret);
var_dump($fail);
?>

上の例の出力は、 たとえば以下のようになります。

Let's do something with success
42
43
53
63
bool(true)
Now, let's fail

bool(false)
bool(false)

参考

  • apcu_dec() - 保存した数値を減らす


キャッシュのキーに関する詳細な情報を取得する

  • ≪ apcu_inc
  • apcu_sma_info ≫
  • PHP Manual
  • APCu 関数
  • キャッシュのキーに関する詳細な情報を取得する

apcu_key_info

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

apcu_key_info — キャッシュのキーに関する詳細な情報を取得する

説明

apcu_key_info(string $key): ?array

キャッシュのキーに関する詳細な情報を取得します。

パラメータ

key

キャッシュのキー

戻り値

キャッシュのキーに関する、詳細な情報を含む配列を返します。 キーが存在しない場合、null を返します。

例

例1 A apcu_key_info() の例

<?php
apcu_add('a','b');
var_dump(apcu_key_info('a'));
?>

上の例の出力は以下となります。

array(7) {
  ["hits"]=>
  int(0)
  ["access_time"]=>
  int(1606701783)
  ["mtime"]=>
  int(1606701783)
  ["creation_time"]=>
  int(1606701783)
  ["deletion_time"]=>
  int(0)
  ["ttl"]=>
  int(0)
  ["refs"]=>
  int(0)
}

参考

  • apcu_store() - 変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く


APCu の共有メモリ割り当てに関する情報を取得する

  • ≪ apcu_key_info
  • apcu_store ≫
  • PHP Manual
  • APCu 関数
  • APCu の共有メモリ割り当てに関する情報を取得する

apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — APCu の共有メモリ割り当てに関する情報を取得する

説明

apcu_sma_info(bool $limited = false): array|false

APCu の共有メモリ割り当てに関する情報を取得します。

パラメータ

limited

false (デフォルト) を設定すると、apcu_sma_info() は各セグメントの詳細な情報を返します。

戻り値

共有メモリ割り当てデータの配列を返します。失敗した場合は false を返します。

例

例1 apcu_sma_info() の例

<?php
print_r(apcu_sma_info());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [num_seg] => 1
    [seg_size] => 31457280
    [avail_mem] => 31448408
    [block_lists] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [size] => 31448408
                            [offset] => 8864
                        )

                )

        )

)

参考

  • APCu 設定ディレクティブ


変数をデータ領域にキャッシュする

  • ≪ apcu_sma_info
  • APCUIterator ≫
  • PHP Manual
  • APCu 関数
  • 変数をデータ領域にキャッシュする

apcu_store

(PECL apcu >= 4.0.0)

apcu_store — 変数をデータ領域にキャッシュする

説明

apcu_store(string $key, mixed $var, int $ttl = 0): bool
apcu_store(array $values, mixed $unused = NULL, int $ttl = 0): array

変数をデータ領域にキャッシュします。

注意: PHP の他の多くの仕組みと異なり、apcu_store() を用いて格納された変数はリクエストを超えて （その値がキャッシュから取り除かれるまで）持続します。

パラメータ

key

この名前を用いて変数を格納します。key は キャッシュ内で一意です。そのため、同一の key で新しい値を格納すると、元の値は上書きされます。

var

格納する変数。

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

values

名前をキー、変数を値に指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 二番目の構文は、エラーになったキーを含む配列を返します。

例

例1 apcu_store() の例

<?php
$bar = 'BAR';
apcu_store('foo', $bar);
var_dump(apcu_fetch('foo'));
?>

上の例の出力は以下となります。

string(3) "BAR"

参考

  • apcu_add() - 新規の変数をデータ領域にキャッシュする
  • apcu_fetch() - 格納されている変数をキャッシュから取得する
  • apcu_delete() - 格納されている変数をキャッシュから取り除く


APCUIterator クラス

(PECL apcu >= 5.0.0)

はじめに

APCUIterator クラスを使うと、巨大な APCu キャッシュの反復処理を容易に行えます。 巨大なキャッシュを順を追って処理し、 ロックインスタンス単位で決まった数のエントリを取得することができます。 そのため、キャッシュ全体を抱え込んで 100 件 (デフォルト) のエントリを取り込むのではなく、 キャッシュのロックを解放して他の操作ができる状態にすることが可能です。 また、正規表現によるマッチングは C 言語レベルで行われるのでより効率的です。

クラス概要

class APCUIterator implements Iterator {
/* メソッド */
public __construct(
array|string|null $search = null,
int $format = APC_ITER_ALL,
int $chunk_size = 100,
int $list = APC_LIST_ACTIVE
)
public current(): mixed
public getTotalCount(): int
public getTotalHits(): int
public getTotalSize(): int
public key(): string
public next(): bool
public rewind(): void
public valid(): bool
}

目次

  • APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する
  • APCUIterator::current — 現在の項目を取得する
  • APCUIterator::getTotalCount — 総数を取得する
  • APCUIterator::getTotalHits — キャッシュヒットの総数を取得する
  • APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する
  • APCUIterator::key — イテレータのキーを取得する
  • APCUIterator::next — ポインタを次の項目に移動させる
  • APCUIterator::rewind — イテレータを巻き戻す
  • APCUIterator::valid — 現在位置が有効かどうかを調べる


APCUIterator イテレータオブジェクトを作成する

  • ≪ APCUIterator
  • APCUIterator::current ≫
  • PHP Manual
  • APCUIterator
  • APCUIterator イテレータオブジェクトを作成する

APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する

説明

public APCUIterator::__construct(
array|string|null $search = null,
int $format = APC_ITER_ALL,
int $chunk_size = 100,
int $list = APC_LIST_ACTIVE
)

APCUIterator オブジェクトを作成します。

パラメータ

search

単一の文字列を指定する場合、APCu のキーの名前にマッチする PCRE 正規表現を指定します。 配列を指定した場合は、APCu のキーの名前を指定します。 null を渡すと、検索をスキップします。

format

希望する書式。 APC_ITER_* 定数の組み合わせで指定します。

chunk_size

チャンクサイズ。0 より大きい値でなければなりません。 デフォルト値は 100 です。

list

一覧にする形式。APC_LIST_ACTIVE あるいは APC_LIST_DELETED を渡します。

例

例1 APCUIterator::__construct() の例

<?php
foreach (new APCUIterator('/^counter\./') as $counter) {
echo "$counter[key]: $counter[value]\n";
apc_dec($counter['key'], $counter['value']);
}
?>

参考

  • apcu_exists() - エントリが存在するかどうかを調べる
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する


現在の項目を取得する

  • ≪ APCUIterator::__construct
  • APCUIterator::getTotalCount ≫
  • PHP Manual
  • APCUIterator
  • 現在の項目を取得する

APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — 現在の項目を取得する

説明

public APCUIterator::current(): mixed

APCUIterator から現在の項目を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に現在の項目を返します。 もう項目が存在しない場合や取得に失敗した場合は false を返します。

参考

  • APCUIterator::next() - ポインタを次の項目に移動させる
  • Iterator::current() - 現在の要素を返す


総数を取得する

  • ≪ APCUIterator::current
  • APCUIterator::getTotalHits ≫
  • PHP Manual
  • APCUIterator
  • 総数を取得する

APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — 総数を取得する

説明

public APCUIterator::getTotalCount(): int

総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

総数を返します。

参考

  • APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
  • APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する


キャッシュヒットの総数を取得する

  • ≪ APCUIterator::getTotalCount
  • APCUIterator::getTotalSize ≫
  • PHP Manual
  • APCUIterator
  • キャッシュヒットの総数を取得する

APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — キャッシュヒットの総数を取得する

説明

public APCUIterator::getTotalHits(): int

キャッシュヒットの総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にヒット数、失敗した場合に false を返します。

参考

  • APCUIterator::getTotalCount() - 総数を取得する
  • APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する


キャッシュのサイズの合計を取得する

  • ≪ APCUIterator::getTotalHits
  • APCUIterator::key ≫
  • PHP Manual
  • APCUIterator
  • キャッシュのサイズの合計を取得する

APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する

説明

public APCUIterator::getTotalSize(): int

キャッシュのサイズの合計を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

キャッシュのサイズの合計を返します。

参考

  • APCUIterator::getTotalCount() - 総数を取得する
  • APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
  • apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する


イテレータのキーを取得する

  • ≪ APCUIterator::getTotalSize
  • APCUIterator::next ≫
  • PHP Manual
  • APCUIterator
  • イテレータのキーを取得する

APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — イテレータのキーを取得する

説明

public APCUIterator::key(): string

現在のイテレータのキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にキー、失敗した場合に false を返します。

参考

  • APCUIterator::current() - 現在の項目を取得する
  • Iterator::key() - 現在の要素のキーを返す


ポインタを次の項目に移動させる

  • ≪ APCUIterator::key
  • APCUIterator::rewind ≫
  • PHP Manual
  • APCUIterator
  • ポインタを次の項目に移動させる

APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — ポインタを次の項目に移動させる

説明

public APCUIterator::next(): bool

イテレータのポインタを次の要素に移動させます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • APCUIterator::current() - 現在の項目を取得する
  • APCUIterator::rewind() - イテレータを巻き戻す
  • Iterator::next() - 次の要素に進む


イテレータを巻き戻す

  • ≪ APCUIterator::next
  • APCUIterator::valid ≫
  • PHP Manual
  • APCUIterator
  • イテレータを巻き戻す

APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — イテレータを巻き戻す

説明

public APCUIterator::rewind(): void

イテレータを最初の要素に巻き戻します

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • APCUIterator::next() - ポインタを次の項目に移動させる
  • Iterator::next() - 次の要素に進む


現在位置が有効かどうかを調べる

  • ≪ APCUIterator::rewind
  • Componere ≫
  • PHP Manual
  • APCUIterator
  • 現在位置が有効かどうかを調べる

APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — 現在位置が有効かどうかを調べる

説明

public APCUIterator::valid(): bool

イテレータの現在位置が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータの現在位置が有効な場合に true、それ以外の場合に false を返します。

参考

  • APCUIterator::current() - 現在の項目を取得する
  • Iterator::valid() - 現在位置が有効かどうかを調べる


Componere

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Componere\Abstract\Definition — The Componere\Abstract\Definition class
    • Componere\Abstract\Definition::addInterface — Add Interface
    • Componere\Abstract\Definition::addMethod — Add Method
    • Componere\Abstract\Definition::addTrait — Add Trait
    • Componere\Abstract\Definition::getReflector — Reflection
  • Componere\Definition — The Componere\Definition class
    • Componere\Definition::__construct — Definition Construction
    • Componere\Definition::addConstant — Add Constant
    • Componere\Definition::addProperty — Add Property
    • Componere\Definition::register — Registration
    • Componere\Definition::isRegistered — State Detection
    • Componere\Definition::getClosure — Get Closure
    • Componere\Definition::getClosures — Get Closures
  • Componere\Patch — The Componere\Patch class
    • Componere\Patch::__construct — Patch Construction
    • Componere\Patch::apply — Application
    • Componere\Patch::revert — Reversal
    • Componere\Patch::isApplied — State Detection
    • Componere\Patch::derive — Patch Derivation
    • Componere\Patch::getClosure — Get Closure
    • Componere\Patch::getClosures — Get Closures
  • Componere\Method — The Componere\Method class
    • Componere\Method::__construct — Method Construction
    • Componere\Method::setPrivate — Accessibility Modification
    • Componere\Method::setProtected — Accessibility Modification
    • Componere\Method::setStatic — Accessibility Modification
    • Componere\Method::getReflector — Reflection
  • Componere\Value — The Componere\Value class
    • Componere\Value::__construct — Value Construction
    • Componere\Value::setPrivate — Accessibility Modification
    • Componere\Value::setProtected — Accessibility Modification
    • Componere\Value::setStatic — Accessibility Modification
    • Componere\Value::isPrivate — Accessibility Detection
    • Componere\Value::isProtected — Accessibility Detection
    • Componere\Value::isStatic — Accessibility Detection
    • Componere\Value::hasDefault — Value Interaction
  • Componere 関数
    • Componere\cast — Casting
    • Componere\cast_by_ref — Casting


はじめに

Componere (latin, English: compose) targets production environments and provides an API for composition of classes, monkey patching, and casting.

Composition:

Componere\Definition is used to define (or redefine) a class at runtime; The class can then be registered, and in the case of redefinition it replaces the original class for as long as the Componere\Definition exists.

public Componere\Definition::__construct(string $name)
public Componere\Definition::__construct(string $name, string $parent)
public Componere\Definition::__construct(string $name, array $interfaces)
public Componere\Definition::__construct(string $name, string $parent, array $interfaces)

Patching:

Componere\Patch is used to change the class of a specific instance of an object at runtime; Upon application the patch will remain applied for as long as the Componere\Patch exists, and can be reverted explicitly.

public Componere\Patch::__construct(object $instance)
public Componere\Patch::__construct(object $instance, array $interfaces)

Casting:

Componere\ casting functions can cast among user defined compatible types; Where compatible means Type is sub or super to the type of object.

Componere\cast(Type $type, $object): Type
Componere\cast_by_ref(Type $type, $object): Type


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Componere
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

Reflection is required


  • ≪ 要件
  • Componere\Abstract\Definition ≫
  • PHP Manual
  • インストール/設定
  • インストール手順

インストール手順

Componere source and releases are available on » github


The Componere\Abstract\Definition class

(Componere 2 >= 2.1.0)

はじめに

This final abstract represents a class entry, and should not be used by the programmer.

クラス概要

final abstract class Componere\Abstract\Definition {
/* メソッド */
public addInterface(string $interface): Definition
public addMethod(string $name, Componere\Method $method): Definition
public addTrait(string $trait): Definition
public getReflector(): ReflectionClass
}

目次

  • Componere\Abstract\Definition::addInterface — Add Interface
  • Componere\Abstract\Definition::addMethod — Add Method
  • Componere\Abstract\Definition::addTrait — Add Trait
  • Componere\Abstract\Definition::getReflector — Reflection


Add Interface

  • ≪ Componere\Abstract\Definition
  • Componere\Abstract\Definition::addMethod ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Add Interface

Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Add Interface

説明

public Componere\Abstract\Definition::addInterface(string $interface): Definition

Shall implement the given interface on the current definition

パラメータ

interface

The case insensitive name of an interface

戻り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered


Add Method

  • ≪ Componere\Abstract\Definition::addInterface
  • Componere\Abstract\Definition::addTrait ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Add Method

Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Add Method

説明

public Componere\Abstract\Definition::addMethod(string $name, Componere\Method $method): Definition

Shall create or override a method on the current definition.

パラメータ

name

The case insensitive name for method

method

Componere\Method not previously added to another Definition

戻り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if Method was added to another Definition


Add Trait

  • ≪ Componere\Abstract\Definition::addMethod
  • Componere\Abstract\Definition::getReflector ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Add Trait

Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Add Trait

説明

public Componere\Abstract\Definition::addTrait(string $trait): Definition

Shall use the given trait for the current definition

パラメータ

trait

The case insensitive name of a trait

戻り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered


Reflection

  • ≪ Componere\Abstract\Definition::addTrait
  • Componere\Definition ≫
  • PHP Manual
  • Componere\Abstract\Definition
  • Reflection

Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

説明

public Componere\Abstract\Definition::getReflector(): ReflectionClass

Shall create or return a ReflectionClass

戻り値

A ReflectionClass for the current definition (cached)


The Componere\Definition class

(Componere 2 >= 2.1.0)

はじめに

The Definition class allows the programmer to build and register a type at runtime.

Should a Definition replace an existing class, the existing class will be restored when the Definition is destroyed.

クラス概要

final class Componere\Definition extends Componere\Abstract\Definition {
/* Constructors */
public __construct(string $name)
public __construct(string $name, string $parent)
public __construct(string $name, array $interfaces)
public __construct(string $name, string $parent, array $interfaces)
/* メソッド */
public addConstant(string $name, Componere\Value $value): Definition
public addProperty(string $name, Componere\Value $value): Definition
public register(): void
public isRegistered(): bool
public getClosure(string $name): Closure
public getClosures(): array
/* 継承したメソッド */
public Componere\Abstract\Definition::addInterface(string $interface): Definition
public Componere\Abstract\Definition::addMethod(string $name, Componere\Method $method): Definition
public Componere\Abstract\Definition::addTrait(string $trait): Definition
public Componere\Abstract\Definition::getReflector(): ReflectionClass
}

目次

  • Componere\Definition::__construct — Definition Construction
  • Componere\Definition::addConstant — Add Constant
  • Componere\Definition::addProperty — Add Property
  • Componere\Definition::register — Registration
  • Componere\Definition::isRegistered — State Detection
  • Componere\Definition::getClosure — Get Closure
  • Componere\Definition::getClosures — Get Closures


Definition Construction

  • ≪ Componere\Definition
  • Componere\Definition::addConstant ≫
  • PHP Manual
  • Componere\Definition
  • Definition Construction

Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Definition Construction

説明

public Componere\Definition::__construct(string $name)
public Componere\Definition::__construct(string $name, string $parent)
public Componere\Definition::__construct(string $name, array $interfaces)
public Componere\Definition::__construct(string $name, string $parent, array $interfaces)

パラメータ

name

A case insensitive class name

parent

A case insensitive class name

interfaces

An array of case insensitive class names

Exceptions

警告

Shall throw InvalidArgumentException if an attempt is made to replace an internal class

警告

Shall throw InvalidArgumentException if an attempt is made to replace an interface

警告

Shall throw InvalidArgumentException if an attempt is made to replace a trait

警告

Shall throw RuntimeException if a class in interfaces cannot be found

警告

Shall throw RuntimeException if an class in interfaces is not an interface


Add Constant

  • ≪ Componere\Definition::__construct
  • Componere\Definition::addProperty ≫
  • PHP Manual
  • Componere\Definition
  • Add Constant

Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Add Constant

説明

public Componere\Definition::addConstant(string $name, Componere\Value $value): Definition

Shall declare a class constant on the current Definition

パラメータ

name

The case sensitive name for the constant

value

The Value for the constant, must not be undefined or static

戻り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if name is already declared as a constant

警告

Shall throw RuntimeException if value is static

警告

Shall throw RuntimeException if value is undefined


Add Property

  • ≪ Componere\Definition::addConstant
  • Componere\Definition::register ≫
  • PHP Manual
  • Componere\Definition
  • Add Property

Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Add Property

説明

public Componere\Definition::addProperty(string $name, Componere\Value $value): Definition

Shall declare a class property on the current Definition

パラメータ

name

The case sensitive name for the property

value

The default Value for the property

戻り値

The current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if name is already declared as a property


Registration

  • ≪ Componere\Definition::addProperty
  • Componere\Definition::isRegistered ≫
  • PHP Manual
  • Componere\Definition
  • Registration

Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registration

説明

public Componere\Definition::register(): void

Shall register the current Definition

Exceptions

警告

Shall throw RuntimeException if Definition was registered


State Detection

  • ≪ Componere\Definition::register
  • Componere\Definition::getClosure ≫
  • PHP Manual
  • Componere\Definition
  • State Detection

Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — State Detection

説明

public Componere\Definition::isRegistered(): bool

Shall detect the registration state of this Definition

戻り値

Shall return true if this Definition is registered


Get Closure

  • ≪ Componere\Definition::isRegistered
  • Componere\Definition::getClosures ≫
  • PHP Manual
  • Componere\Definition
  • Get Closure

Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Get Closure

説明

public Componere\Definition::getClosure(string $name): Closure

Shall return a Closure for the method specified by name

パラメータ

name

The case insensitive name of the method

戻り値

A Closure bound to the correct scope

Exceptions

警告

Shall throw RuntimeException if Definition was registered

警告

Shall throw RuntimeException if name could not be found


Get Closures

  • ≪ Componere\Definition::getClosure
  • Componere\Patch ≫
  • PHP Manual
  • Componere\Definition
  • Get Closures

Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Get Closures

説明

public Componere\Definition::getClosures(): array

Shall return an array of Closures

戻り値

Shall return all methods as an array of Closure objects bound to the correct scope

Exceptions

警告

Shall throw RuntimeException if Definition was registered


The Componere\Patch class

(Componere 2 >= 2.1.0)

はじめに

The Patch class allows the programmer to change the type of an instance at runtime without registering a new Definition

When a Patch is destroyed it is reverted, so that instances that were patched during the lifetime of the Patch are restored to their formal type.

クラス概要

final class Componere\Patch extends Componere\Abstract\Definition {
/* Constructors */
public __construct(object $instance)
public __construct(object $instance, array $interfaces)
/* メソッド */
public apply(): void
public revert(): void
public isApplied(): bool
public derive(object $instance): Patch
public getClosure(string $name): Closure
public getClosures(): array
/* 継承したメソッド */
public Componere\Abstract\Definition::addInterface(string $interface): Definition
public Componere\Abstract\Definition::addMethod(string $name, Componere\Method $method): Definition
public Componere\Abstract\Definition::addTrait(string $trait): Definition
public Componere\Abstract\Definition::getReflector(): ReflectionClass
}

目次

  • Componere\Patch::__construct — Patch Construction
  • Componere\Patch::apply — Application
  • Componere\Patch::revert — Reversal
  • Componere\Patch::isApplied — State Detection
  • Componere\Patch::derive — Patch Derivation
  • Componere\Patch::getClosure — Get Closure
  • Componere\Patch::getClosures — Get Closures


Patch Construction

  • ≪ Componere\Patch
  • Componere\Patch::apply ≫
  • PHP Manual
  • Componere\Patch
  • Patch Construction

Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Patch Construction

説明

public Componere\Patch::__construct(object $instance)
public Componere\Patch::__construct(object $instance, array $interfaces)

パラメータ

instance

The target for this Patch

interfaces

A case insensitive array of class names

Exceptions

警告

Shall throw RuntimeException if a class in interfaces cannot be found

警告

Shall throw RuntimeException if an class in interfaces is not an interface


Application

  • ≪ Componere\Patch::__construct
  • Componere\Patch::revert ≫
  • PHP Manual
  • Componere\Patch
  • Application

Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Application

説明

public Componere\Patch::apply(): void

Shall apply the current patch


Reversal

  • ≪ Componere\Patch::apply
  • Componere\Patch::isApplied ≫
  • PHP Manual
  • Componere\Patch
  • Reversal

Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversal

説明

public Componere\Patch::revert(): void

Shall revert the current patch


State Detection

  • ≪ Componere\Patch::revert
  • Componere\Patch::derive ≫
  • PHP Manual
  • Componere\Patch
  • State Detection

Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — State Detection

説明

public Componere\Patch::isApplied(): bool


Patch Derivation

  • ≪ Componere\Patch::isApplied
  • Componere\Patch::getClosure ≫
  • PHP Manual
  • Componere\Patch
  • Patch Derivation

Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Patch Derivation

説明

public Componere\Patch::derive(object $instance): Patch

Shall derive a Patch for the given instance

パラメータ

instance

The target for the derived Patch

戻り値

Patch for instance derived from the current Patch

Exceptions

警告

Shall throw InvalidArgumentException if instance is not compatible


Get Closure

  • ≪ Componere\Patch::derive
  • Componere\Patch::getClosures ≫
  • PHP Manual
  • Componere\Patch
  • Get Closure

Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Get Closure

説明

public Componere\Patch::getClosure(string $name): Closure

Shall return a Closure for the method specified by name

パラメータ

name

The case insensitive name of the method

戻り値

A Closure bound to the correct scope and object

Exceptions

警告

Shall throw RuntimeException if name could not be found


Get Closures

  • ≪ Componere\Patch::getClosure
  • Componere\Method ≫
  • PHP Manual
  • Componere\Patch
  • Get Closures

Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Get Closures

説明

public Componere\Patch::getClosures(): array

Shall return an array of Closures

戻り値

Shall return all methods as an array of Closure objects bound to the correct scope and object


The Componere\Method class

(Componere 2 >= 2.1.0)

はじめに

A Method represents a function with modifiable accessibility flags

クラス概要

final class Componere\Method {
/* Constructor */
public __construct(Closure $closure)
/* メソッド */
public setPrivate(): Method
public setProtected(): Method
public setStatic(): Method
public getReflector(): ReflectionMethod
}

目次

  • Componere\Method::__construct — Method Construction
  • Componere\Method::setPrivate — Accessibility Modification
  • Componere\Method::setProtected — Accessibility Modification
  • Componere\Method::setStatic — Accessibility Modification
  • Componere\Method::getReflector — Reflection


Method Construction

  • ≪ Componere\Method
  • Componere\Method::setPrivate ≫
  • PHP Manual
  • Componere\Method
  • Method Construction

Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Method Construction

説明

public Componere\Method::__construct(Closure $closure)

パラメータ

closure


Accessibility Modification

  • ≪ Componere\Method::__construct
  • Componere\Method::setProtected ≫
  • PHP Manual
  • Componere\Method
  • Accessibility Modification

Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Accessibility Modification

説明

public Componere\Method::setPrivate(): Method

戻り値

The current Method

Exceptions

警告

Shall throw RuntimeException if access level was previously set


Accessibility Modification

  • ≪ Componere\Method::setPrivate
  • Componere\Method::setStatic ≫
  • PHP Manual
  • Componere\Method
  • Accessibility Modification

Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Accessibility Modification

説明

public Componere\Method::setProtected(): Method

戻り値

The current Method

Exceptions

警告

Shall throw RuntimeException if access level was previously set


Accessibility Modification

  • ≪ Componere\Method::setProtected
  • Componere\Method::getReflector ≫
  • PHP Manual
  • Componere\Method
  • Accessibility Modification

Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Accessibility Modification

説明

public Componere\Method::setStatic(): Method

戻り値

The current Method


Reflection

  • ≪ Componere\Method::setStatic
  • Componere\Value ≫
  • PHP Manual
  • Componere\Method
  • Reflection

Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

説明

public Componere\Method::getReflector(): ReflectionMethod

Shall create or return a ReflectionMethod

戻り値

A ReflectionMethod for the current method (cached)


The Componere\Value class

(Componere 2 >= 2.1.0)

はじめに

A Value represents a PHP variable of all types, including undefined

クラス概要

final class Componere\Value {
/* Constructor */
public __construct( $default = ?)
/* メソッド */
public setPrivate(): Value
public setProtected(): Value
public setStatic(): Value
public isPrivate(): bool
public isProtected(): bool
public isStatic(): bool
public hasDefault(): bool
}

目次

  • Componere\Value::__construct — Value Construction
  • Componere\Value::setPrivate — Accessibility Modification
  • Componere\Value::setProtected — Accessibility Modification
  • Componere\Value::setStatic — Accessibility Modification
  • Componere\Value::isPrivate — Accessibility Detection
  • Componere\Value::isProtected — Accessibility Detection
  • Componere\Value::isStatic — Accessibility Detection
  • Componere\Value::hasDefault — Value Interaction


Value Construction

  • ≪ Componere\Value
  • Componere\Value::setPrivate ≫
  • PHP Manual
  • Componere\Value
  • Value Construction

Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Value Construction

説明

public Componere\Value::__construct( $default = ?)

パラメータ

default

Exceptions

警告

Shall throw InvalidArgumentException if default does not have a suitable value


Accessibility Modification

  • ≪ Componere\Value::__construct
  • Componere\Value::setProtected ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Modification

Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Accessibility Modification

説明

public Componere\Value::setPrivate(): Value

戻り値

The current Value

Exceptions

警告

Shall throw RuntimeException if access level was previously set


Accessibility Modification

  • ≪ Componere\Value::setPrivate
  • Componere\Value::setStatic ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Modification

Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Accessibility Modification

説明

public Componere\Value::setProtected(): Value

戻り値

The current Value

Exceptions

警告

Shall throw RuntimeException if access level was previously set


Accessibility Modification

  • ≪ Componere\Value::setProtected
  • Componere\Value::isPrivate ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Modification

Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Accessibility Modification

説明

public Componere\Value::setStatic(): Value

戻り値

The current Value


Accessibility Detection

  • ≪ Componere\Value::setStatic
  • Componere\Value::isProtected ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Detection

Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Accessibility Detection

説明

public Componere\Value::isPrivate(): bool


Accessibility Detection

  • ≪ Componere\Value::isPrivate
  • Componere\Value::isStatic ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Detection

Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Accessibility Detection

説明

public Componere\Value::isProtected(): bool


Accessibility Detection

  • ≪ Componere\Value::isProtected
  • Componere\Value::hasDefault ≫
  • PHP Manual
  • Componere\Value
  • Accessibility Detection

Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Accessibility Detection

説明

public Componere\Value::isStatic(): bool


Value Interaction

  • ≪ Componere\Value::isStatic
  • Componere 関数 ≫
  • PHP Manual
  • Componere\Value
  • Value Interaction

Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Value Interaction

説明

public Componere\Value::hasDefault(): bool


  • ≪ Componere\Value::hasDefault
  • Componere\cast ≫
  • PHP Manual
  • Componere
  • Componere 関数

Componere 関数

目次

  • Componere\cast — Casting
  • Componere\cast_by_ref — Casting


Casting

  • ≪ Componere 関数
  • Componere\cast_by_ref ≫
  • PHP Manual
  • Componere 関数
  • Casting

Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Casting

説明

Componere\cast(Type $type, $object): Type

パラメータ

type

A user defined type

object

An object with a user defined type compatible with Type

戻り値

An object of type Type, cast from object

エラー / 例外

警告

Shall throw InvalidArgumentException if the type of object is or is derived from an internal class

警告

Shall throw InvalidArgumentException if Type is an interface

警告

Shall throw InvalidArgumentException if Type is a trait

警告

Shall throw InvalidArgumentException if Type is an abstract

警告

Shall throw InvalidArgumentException if Type is not compatible with the type of object

参考

  • Componere\cast_by_ref


Casting

  • ≪ Componere\cast
  • エラー処理 ≫
  • PHP Manual
  • Componere 関数
  • Casting

Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Casting

説明

Componere\cast_by_ref(Type $type, $object): Type

パラメータ

type

A user defined type

object

An object with a user defined type compatible with Type

戻り値

An object of type Type, cast from object, where members are references to object members

エラー / 例外

警告

Shall throw InvalidArgumentException if the type of object is or is derived from an internal class

警告

Shall throw InvalidArgumentException if Type is an interface

警告

Shall throw InvalidArgumentException if Type is a trait

警告

Shall throw InvalidArgumentException if Type is an abstract

警告

Shall throw InvalidArgumentException if Type is not compatible with the type of object

参考

  • Componere\cast


エラー処理およびログ記録

  • はじめに
  • インストール/設定
    • 実行時設定
  • 定義済み定数
  • 例
  • エラー処理関数
    • debug_backtrace — バックトレースを生成する
    • debug_print_backtrace — バックトレースを表示する
    • error_clear_last — 最も最近のエラーをクリア
    • error_get_last — 最後に発生したエラーを取得する
    • error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する
    • error_reporting — 出力する PHP エラーの種類を設定する
    • restore_error_handler — 以前のエラーハンドラ関数を回復する
    • restore_exception_handler — 以前の例外ハンドラ関数を回復する
    • set_error_handler — ユーザー定義のエラーハンドラ関数を設定する
    • set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する
    • trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する
    • user_error — trigger_error のエイリアス


はじめに

以下の関数は、エラー処理およびログ記録を行います。これらの関数によ り、独自のエラー処理規則を定義することが可能になり、同時にエラーの ログを記録する方法を修正することが可能になります。これにより、ニーズに 即したエラー出力の変更と拡張が可能になります。

ログ記録関数により他のマシンやemail(またはポケベルのゲートウエイ に!)、システムログ等に直接メッセージを送信することが可能になります。 これにより、ログを行うものを選択したり、アプリケーションやWebサイ トに最も重要な部分をモニタすることが可能になります。

エラー出力関数により、エラーのフィードバックのレベルと種類、 簡単な通知からカスタマイズされた関数までエラーの際に返すもの をカスタマイズすることが可能になります。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • エラー処理
  • インストール/設定

インストール/設定

目次

  • 実行時設定


実行時設定

php.ini の設定により動作が変化します。

エラーおよびロギング設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
error_reporting | NULL | INI_ALL |
display_errors | "1" | INI_ALL |
display_startup_errors | "1" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "0" でした。
log_errors | "0" | INI_ALL |
log_errors_max_len | "1024" | INI_ALL | PHP 8.0.0 以降は意味をなさなくなり、PHP 8.1.0 で削除されました。
ignore_repeated_errors | "0" | INI_ALL |
ignore_repeated_source | "0" | INI_ALL |
report_memleaks | "1" | INI_ALL |
track_errors | "0" | INI_ALL | PHP 7.2.0 以降で非推奨になり、PHP 8.0.0 で削除されました。
html_errors | "1" | INI_ALL |
xmlrpc_errors | "0" | INI_SYSTEM |
xmlrpc_error_number | "0" | INI_ALL |
docref_root | "" | INI_ALL |
docref_ext | "" | INI_ALL |
error_prepend_string | NULL | INI_ALL |
error_append_string | NULL | INI_ALL |
error_log | NULL | INI_ALL |
error_log_mode | 0o644 | INI_ALL | PHP 8.2.0 以降で有効です。
syslog.facility | "LOG_USER" | INI_SYSTEM | PHP 7.3.0 以降で有効です。
syslog.filter | "no-ctrl" | INI_ALL | PHP 7.3.0 以降で有効です。
syslog.ident | "php" | INI_SYSTEM | PHP 7.3.0 以降で有効です。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブの簡単な説明を示します。

error_reporting int

エラー出力レベルを設定します。パラメータは、あるビットフィールドを表 す整数か定数名で指定します。このerror_reportingのレベルと定数は、 定義済の定数および php.iniに記述されています。 実行時に設定するには、 error_reporting() 関数を指定してください。 display_errors ディレクティブも参照ください。

デフォルト値は E_ALL です。

PHP 8.0.0 より前のバージョンでは、 E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED でした。 これは、E_NOTICE、 E_STRICT、 そして E_DEPRECATED レベルのエラーが出力されないということです。

注意: PHP 定数の、PHP 以外での使用

PHP の定数を、httpd.conf など PHP の外部で使用しても何の意味もありません。外部で使用する場合には、 int 型の値を指定しなければなりません。 また、エラーレベルはこれからも追加されることがあるので、 最大値 (E_ALL に対応する値) は変わる可能性があります。そこで、E_ALL を指定する場面では 2147483647 (E_ALL だけではなくすべてのエラーを含める) のような数を指定するようにしましょう。 これは現状の全ビットに対応した上で、かつ値が将来追加された場合にも対応できます。

display_errors string

エラーをHTML出力の一部として画面に出力するかどうかを定義します。

"stderr" を指定すると、エラーの内容を stdout (標準出力) ではなく stderr (標準エラー出力) に送ります。

注意:

開発をサポートする仕組みであり、本番のシステムでは 使用すべきではありません (例えばインターネットに接続されたシステムなど)。

注意:

display_errors は実行時にも設定可能（ini_set() 関数を用いて）ですが、スクリプトが致命的（fatal）なエラーを発生した場合は その設定は反映されません。なぜなら、要求されたアクションは 実行されなかったからです。

display_startup_errors bool

display_errorsをonにした場合でも、PHPの起動シーケンスにおいて発 生したエラーは表示されません。デバッグ時を除き、 display_startup_errorsをoffにしておくことが強く推奨されます。

log_errors bool

エラーメッセージを、サーバーのエラーログまたはerror_logに記録するかどうかを指定 します。このオプションはサーバーに依存します。

注意:

実用Webサイトではエラー表示を行う代わりにエラーを記録することを 強く推奨します。

log_errors_max_len int

log_errorsの最大長をバイト単位で設定します。 error_log には、 この設定で情報が追加されます。デフォルトは 1024 で、0 を指定すると 最大長の制限は全く適用されなくなります。 この長さはエラーログへの記録や エラーの表示、そして $php_errormsg に適用されます。 しかし、明示的に呼び出される error_log() のような関数には適用されません。

intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。
ignore_repeated_errors bool

繰り返されるメッセージを記録しません。エラーの繰り返しは、 ignore_repeated_sourceが trueに設定されるまで同じファイルの同じ行で発生します。

ignore_repeated_source bool

メッセージの繰り返しを無視する場合にメッセージのソースを無視しま す。この設定をOnにすると、異なるファイルまたはソース行からの同じ エラーメッセージの繰り返しを記録しなくなります。

report_memleaks bool

このパラメータを On (デフォルト) にすると、Zend メモリマネージャーが検出した メモリリークの報告を表示します。この報告は、Posix プラットフォームでは標準エラー出力に送られます。 Windows では、デバッガに OutputDebugString() を使って送られ、 » DbgView のようなツールで見ることができます。 このパラメータが使えるのはデバッグビルドだけであり、かつ error_reporting で E_WARNING を有効にしている場合のみです。

track_errors bool

有効にした場合、直近のエラーメッセージが、 $php_errormsg 変数に常に代入されます。

html_errors bool

有効にすると、エラーメッセージにHTMLタグが含まれるようになります。 HTML形式のエラーメッセージでは、ユーザーがエラーまたはエラーを発生した関数を説明するページ に導くようクリック可能なメッセージを出力します。これらのリファレ ンスは、docref_root およ び docref_extの設定に依存 します。

無効にすると、エラーメッセージは単なるプレーンテキストになります。

xmlrpc_errors bool

有効にすると、通常のエラー報告を無効にして XML-RPC 形式のエラーメッセージとします。

xmlrpc_error_number int

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

エラーメッセージの前に出力する文字列。 エラーメッセージを画面に表示する時にだけ使います。 主な目的は、 エラーメッセージの先頭に追加のHTMLマークアップを付加できるようにすることです。

error_append_string string

エラーメッセージの後に出力する文字列。 エラーメッセージを画面に表示する時にだけ使います。 主な目的は、 エラーメッセージに追加のHTMLマークアップを付加できるようにすることです。

error_log string

スクリプトエラーが記録されるファイル名です。 ファイルはウェブサーバーユーザーで書き込めなければなりません。 syslog が指定されると、エラーはファイルではなく システムロガーに送られます。これは Unix では syslog(3) であり Windows ではイベントログのことです。 syslog() も参照ください。 このディレクティブが設定されていない場合、エラーは SAPI エラーロガーに送信されます。これは、例えば Apache のエラーログ、 あるいは CLI なら stderr になります。 error_log() も参照ください。

error_log_mode int

error_log で設定されたファイルのモード(パーミッション)。

syslog.facility string

どの種類のプログラムがメッセージを記録するのかを指定します。 error_log が "syslog" の場合にだけ有効です。

syslog.filter string

記録されたメッセージをフィルタリングするフィルターの種類を指定します。 フィルターで許可された文字はそのまま記録されますが、許可されていない文字は \x で始まる十六進表記に変換して記録されます。

  • all - ロギングされる文字列は改行文字で分割され、すべての文字は変更せずに渡されます。
  • ascii - ロギングされる文字列は改行文字で分割され、 印刷可能な 7bit ASCII 文字以外の文字は全てエスケープされます。
  • no-ctrl - ロギングされる文字列は改行文字で分割され、 印刷可能な文字以外は全てエスケープされます。
  • raw - 全ての文字はシステムロガーに変更せずに渡されます。 改行文字で分割されることもありません(PHP 7.3 より前の振る舞いと同等です)
この設定は、error_log を "syslog" に設定し、 syslog() をコールした場合にのみ影響します。

注意:

raw フィルタタイプは、PHP 7.3.8 および PHP 7.4.0 以降で使えます。

このディレクティブは、Windows ではサポートされていません。
syslog.ident string

すべての文字列の先頭に追加する識別用文字列を指定します。 error_log が "syslog" の場合にだけ有効です。


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

注意: 以下の定数をphp.iniで使用することができますが、 httpd.confのようなPHPの外部では、 代わりにビットマスク値を使用する必要があります。

エラーとロギング
値 | 定数 | 説明 | 注記
1 | E_ERROR (int) | 重大な実行時エラー。これは、メモリ確保に関する問題のように復帰で きないエラーを示します。スクリプトの実行は中断されます。 |
2 | E_WARNING (int) | 実行時の警告 (致命的なエラーではない)。スクリプトの実行は中断さ れません。 |
4 | E_PARSE (int) | コンパイル時のパースエラー。パースエラーはパーサでのみ生成されま す。 |
8 | E_NOTICE (int) | 実行時の警告。エラーを発しうる状況に遭遇したことを示す。 ただし通常のスクリプト実行の場合にもこの警告を発することがありうる。 |
16 | E_CORE_ERROR (int) | PHPの初期始動時点での致命的なエラー。E_ERRORに 似ているがPHPのコアによって発行される点が違う。 |
32 | E_CORE_WARNING (int) | （致命的ではない）警告。PHPの初期始動時に発生する。 E_WARNINGに似ているがPHPのコアによって発行される 点が違う。 |
64 | E_COMPILE_ERROR (int) | コンパイル時の致命的なエラー。E_ERRORに 似ているがZendスクリプティングエンジンによって発行される点が違う。 |
128 | E_COMPILE_WARNING (int) | コンパイル時の警告（致命的ではない）。E_WARNINGに 似ているがZendスクリプティングエンジンによって発行される点が違う。 |
256 | E_USER_ERROR (int) | ユーザーによって発行されるエラーメッセージ。E_ERROR に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。 |
512 | E_USER_WARNING (int) | ユーザーによって発行される警告メッセージ。E_WARNING に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。 |
1024 | E_USER_NOTICE (int) | ユーザーによって発行される注意メッセージ。E_NOTICEに に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。 |
2048 | E_STRICT (int) | コードの相互運用性や互換性を維持するために PHP がコードの変更を提案する。 |
4096 | E_RECOVERABLE_ERROR (int) | キャッチできる致命的なエラー。危険なエラーが発生したが、 エンジンが不安定な状態になるほどではないことを表す。 ユーザー定義のハンドラでエラーがキャッチされなかった場合 (set_error_handler() も参照ください) は、 E_ERROR として異常終了する。 |
8192 | E_DEPRECATED (int) | 実行時の注意。これを有効にすると、 将来のバージョンで動作しなくなるコードについての警告を受け取ることができる。 |
16384 | E_USER_DEPRECATED (int) | ユーザー定義の警告メッセージ。これは E_DEPRECATED と同等だが、 PHP のコード上で関数 trigger_error() によって作成されるという点が異なる。 |
32767 | E_ALL (int) | 全てのエラーと警告。 |

上記の値（数値も論理値も）はどのエラーをレポートするかを指定する ビットマスクを組み立てる。ビット演算子 を使用して値を組み合わせたり特定のエラータイプをマスクすることができる。 php.ini では'|', '~', '!', '^' および '&'のみが解釈されることに 注意すべきである。


例

エラー処理機能を 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 — バックトレースを生成する
  • debug_print_backtrace — バックトレースを表示する
  • error_clear_last — 最も最近のエラーをクリア
  • error_get_last — 最後に発生したエラーを取得する
  • error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する
  • error_reporting — 出力する PHP エラーの種類を設定する
  • restore_error_handler — 以前のエラーハンドラ関数を回復する
  • restore_exception_handler — 以前の例外ハンドラ関数を回復する
  • set_error_handler — ユーザー定義のエラーハンドラ関数を設定する
  • set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する
  • trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する
  • user_error — trigger_error のエイリアス


バックトレースを生成する

  • ≪ エラー処理関数
  • debug_print_backtrace ≫
  • PHP Manual
  • エラー処理関数
  • バックトレースを生成する

debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — バックトレースを生成する

説明

debug_backtrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array

debug_backtrace() は PHP バックトレースを生成します。

パラメータ

options

このパラメータは次のオプションのビットマスクとなります。

debug_backtrace() のオプション
DEBUG_BACKTRACE_PROVIDE_OBJECT | "object" インデックスを埋めるかどうか。
DEBUG_BACKTRACE_IGNORE_ARGS | "args" インデックス、 すなわちすべての関数/メソッドの引数を省略してメモリを節約するかどうか。

注意:

可能な組み合わせは以下の4つです:

debug_backtrace() のオプション
debug_backtrace() | インデックスを両方収集します。
debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)
debug_backtrace(1)
debug_backtrace(0) | インデックス "object" を省略し、"args" を収集します。
debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS) | インデックス "object" と "args" を 両方省略します。
debug_backtrace(2)
debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS) | インデックス "object" を収集し、"args" を省略します。
debug_backtrace(3)

limit

このパラメータを使ってスタックフレームの数を制限できます。 デフォルト (limit=0) は、すべてのスタックフレームを返します。

戻り値

連想配列の配列を返します。連想配列の要素として返される可能性があるものは以下のとおりです。

debug_backtrace() から返される可能性がある要素
名前 | 型 | 説明
function | string | カレントの関数名。 __FUNCTION__ も参照ください。
line | int | カレントの行番号。 __LINE__ も参照ください。
file | string | カレントのファイル名。 __FILE__ も参照ください。
class | string | カレントのクラス名。 __CLASS__ も参照ください。
object | object | カレントのオブジェクト。
type | string | カレントのコール方式。メソッドを呼び出している場合は "->"、 staticメソッドを呼び出している場合は "::" が返されます。 関数呼び出しの場合は何も返されません。
args | array | 関数の内部の場合、関数の引数のリストとなります。 インクルードされたファイル内では、 読み込まれたファイルの名前となります。

例

例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"
  }
}

参考

  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
  • debug_print_backtrace() - バックトレースを表示する


バックトレースを表示する

  • ≪ debug_backtrace
  • error_clear_last ≫
  • PHP Manual
  • エラー処理関数
  • バックトレースを表示する

debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — バックトレースを表示する

説明

debug_print_backtrace(int $options = 0, int $limit = 0): void

debug_print_backtrace() は PHP バックトレースを 表示します。関数のコール、include/require されているファイル、 そして eval() された内容などが表示されます。

パラメータ

options

このパラメータは次のオプションのビットマスクとなります。

debug_print_backtrace() のオプション
DEBUG_BACKTRACE_IGNORE_ARGS "args" インデックスを無視してすべての関数/メソッドの引数をメモリに格納するかどうか。

limit

このパラメータを使ってスタックフレームの数を制限できます。 デフォルト (limit=0) は、すべてのスタックフレームを表示します。

戻り値

値を返しません。

例

例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]

参考

  • debug_backtrace() - バックトレースを生成する


最も最近のエラーをクリア

  • ≪ debug_print_backtrace
  • error_get_last ≫
  • PHP Manual
  • エラー処理関数
  • 最も最近のエラーをクリア

error_clear_last

(PHP 7, PHP 8)

error_clear_last — 最も最近のエラーをクリア

説明

error_clear_last(): void

パラメータ

この関数にはパラメータはありません。

戻り値

最も最近のエラーをクリアーし、 error_get_last() で取得できないようにします。

例

例1 error_clear_last() の例

<?php
var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());

@$a = $b;

var_dump(error_get_last());
error_clear_last();
var_dump(error_get_last());
?>

上の例の出力は、 たとえば以下のようになります。

NULL
NULL
array(4) {
  ["type"]=>
  int(8)
  ["message"]=>
  string(21) "Undefined variable: b"
  ["file"]=>
  string(9) "%s"
  ["line"]=>
  int(6)
}
NULL

参考

  • エラー定数


最後に発生したエラーを取得する

  • ≪ error_clear_last
  • error_log ≫
  • PHP Manual
  • エラー処理関数
  • 最後に発生したエラーを取得する

error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — 最後に発生したエラーを取得する

説明

error_get_last(): ?array

最後に発生したエラーについての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

最後に発生したエラーについての情報を連想配列で返します。連想配列のキーは "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
)

参考

  • エラー定数
  • 変数 $php_errormsg
  • error_clear_last() - 最も最近のエラーをクリア
  • ディレクティブ display_errors
  • ディレクティブ html_errors
  • ディレクティブ xmlrpc_errors


定義されたエラー処理ルーチンにエラーメッセージを送信する

  • ≪ error_get_last
  • error_reporting ≫
  • PHP Manual
  • エラー処理関数
  • 定義されたエラー処理ルーチンにエラーメッセージを送信する

error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する

説明

error_log(
string $message,
int $message_type = 0,
?string $destination = null,
?string $additional_headers = null
): bool

エラーメッセージを Web サーバーのエラーログあるいはファイルに送ります。

パラメータ

message

ログに記録されるエラーメッセージ。

message_type

メッセージをどこに送るのかを指定します。以下の中から指定できます。

error_log() ログタイプ
0 | message は PHP のシステムロガーに送られ、 設定ディレクティブ error_log の値に応じて、 オペレーティングシステムのシステムログ機構を使って保存されるか、 ファイルに保存されるかが決まります。 これがデフォルトのオプションです。
1 | message は、destination パラメータで指定されたアドレスに、電子メール により送られます。このメッセージタイプの場合にのみ、 4 番目のパラメータである additional_headers が使われます。
2 | このオプションは存在しません。
3 | message は destination で指定されたファイルに追加されます。 明示的に指定しない限り、message の 最後には改行文字は追加されません。
4 | message は、直接 SAPI のログ出力ハンドラに送信されます。

destination

メッセージの送信先。その設定は、上で説明している message_type パラメータの値によります。

additional_headers

追加のヘッダ。message_type パラメータが 1 に設定される場合に利用されます。 このメッセージタイプは、mail() と同様に 内部関数を利用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 message_type が0の場合、 エラーがロギング出来たかそうでないかに関わらず、この関数は常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | destination と additional_headers は、nullable になりました。

例

例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_log() はバイナリセーフではありません。 message に null 文字があれば、そこで切り詰められます。

ヒント

message に null 文字を含めてはいけません。 message の送り先はファイルやメール、そして syslog などになることもあります。 base64_encode() や rawurlencode()、addslashes() などの関数で適切に変換してから error_log() に渡す必要があります。


出力する PHP エラーの種類を設定する

  • ≪ error_log
  • restore_error_handler ≫
  • PHP Manual
  • エラー処理関数
  • 出力する PHP エラーの種類を設定する

error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — 出力する PHP エラーの種類を設定する

説明

error_reporting(?int $error_level = null): int

error_reporting() 関数は、 error_reporting ディレクティブを 実行時に設定します。PHP には多くのエラーレベルがあり、 この関数によりスクリプトの持続時間(実行時間)のレベルが設定されます。 オプションの error_level を指定しなかった場合は、 error_reporting() は単に現在のエラーレベルを返します。

パラメータ

error_level

新しい error_reporting レベル。ビットマスクまたは名前つき定数のどちらかです。将来の バージョンとの互換性を保証するために、名前つき定数の使用が 強く推奨されています。エラーレベルが追加されると、整数の幅は増加します。 そのため、以前の整数を使用するエラーレベルは常に期待通りに動作するとは 限りません。

利用可能なエラーレベル定数とその実際の意味は、 定義済みの定数に 記述されています。

戻り値

error_level に変更される 前 の、 error_reporting レベルを返します。

注意: エラー制御演算子 @ は、エラーハンドリングの間に error_level を変更します。

変更履歴

バージョン | 説明
8.0.0 | error_level は、nullable になりました。

例

例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 以外の全てのエラーを表示する
error_reporting(E_ALL & ~E_NOTICE);

// 全ての PHP エラーを表示する
error_reporting(E_ALL);

// 全ての PHP エラーを表示する
error_reporting(-1);

// error_reporting(E_ALL); と同じ
ini_set('error_reporting', E_ALL);

?>

注意

ヒント

値に -1 を指定すると、仮に将来のバージョンの PHP で新しいレベルと定数が追加されたとしてもすべてのエラーを表示するようになります。 E_ALL 定数も、これと同じ挙動になります。

参考

  • display_errors ディレクティブ
  • html_errors ディレクティブ
  • xmlrpc_errors ディレクティブ
  • エラー制御演算子
  • ini_set() - 設定オプションの値を設定する


以前のエラーハンドラ関数を回復する

  • ≪ error_reporting
  • restore_exception_handler ≫
  • PHP Manual
  • エラー処理関数
  • 以前のエラーハンドラ関数を回復する

restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — 以前のエラーハンドラ関数を回復する

説明

restore_error_handler(): true

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_reporting() - 出力する PHP エラーの種類を設定する
  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • restore_exception_handler() - 以前の例外ハンドラ関数を回復する
  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する


以前の例外ハンドラ関数を回復する

  • ≪ restore_error_handler
  • set_error_handler ≫
  • PHP Manual
  • エラー処理関数
  • 以前の例外ハンドラ関数を回復する

restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — 以前の例外ハンドラ関数を回復する

説明

restore_exception_handler(): true

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_exception_handler() - ユーザー定義の例外ハンドラ関数を設定する
  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • error_reporting() - 出力する PHP エラーの種類を設定する


ユーザー定義のエラーハンドラ関数を設定する

  • ≪ restore_exception_handler
  • set_exception_handler ≫
  • PHP Manual
  • エラー処理関数
  • ユーザー定義のエラーハンドラ関数を設定する

set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — ユーザー定義のエラーハンドラ関数を設定する

説明

set_error_handler(?callable $callback, int $error_levels = E_ALL): ?callable

スクリプトのエラー処理を行うユーザー関数 (callback)を設定します。

この関数は、実行時にカスタムのエラーハンドラを定義するために使います。 例えば、致命的なエラーの際にデータやファイルを消去する必要があるような アプリケーションや、ある条件のもとに (trigger_error()を使用して)エラーを発生する必要がある アプリケーションがこの場合にあたります。

コールバック関数が false を返さない限り、error_levels で指定した型のエラーでは PHP 標準のエラーハンドラが完全にバイパスされることに注意してください。 error_reporting() の設定にかかわらず、どのような場合でも ユーザーが設定したエラーハンドラがコールされます。ただし、この場合でも ハンドラで error_reporting() の現在の値を読み込み、 それにあわせて適切に動作させることは可能です。

ユーザーハンドラ関数は、必要に応じて exit() を コールすることで、スクリプトを停止させる責任があることにも注意しましょう。 エラーハンドラ関数がリターンした場合、エラーが発生した次の行から実行が継続されます。

以下のエラータイプは、ユーザー定義の関数では扱えません。 E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING。これらは発生した場所に関係なく使えません。 また、set_error_handler() がコールされたファイルで発生した 大半の E_STRICT も、ユーザー定義の関数では扱えません。

(ファイルアップロードのように)スクリプトが実行される前にエラーが 発生した場合、カスタムエラーハンドラはコールされません。 これは、その時点では登録されていないためです。

パラメータ

callback

null を渡すと、ハンドラをデフォルトの状態に戻せます。 それ以外の場合、次のシグネチャに従うコールバックを渡します:

handler(
int $errno,
string $errstr,
string $errfile = ?,
int $errline = ?,
array $errcontext = ?
): bool
errno
最初のパラメータ errno は、発生させる エラーのレベルが整数で渡されます。
errstr
2 番目のパラメータ errstr は、 エラーメッセージが文字列で渡されます。
errfile
コールバックが第3引数 errfile を受け入れる場合、 エラーが発生したファイルの名前が文字列で渡されます。
errline
コールバックが第4引数 errline を受け入れる場合、 エラーが発生した行番号が整数で渡されます。
errcontext
コールバックが第5引数 errcontext を受け入れる場合、 エラーが発生した場所のアクティブシンボルテーブルが配列で渡されます。 つまり、エラーが発生したスコープ内でのすべての変数の内容を格納した 配列が errcontext だということです。 ユーザーエラーハンドラは、決してエラーコンテキストを書き換えては いけません。
警告

このパラメータは PHP 7.2.0 以降では 推奨されなくなり、 PHP 8.0.0 で 削除されました。 この引数をデフォルト値以外に設定すると、 ハンドラが呼び出された時に "too few arguments" エラーが発生します。

この関数が false を返した場合は、通常のエラーハンドラが処理を引き継ぎます。

error_levels

設定パラメータ error_reporting で表示するエラーを制御するのと全く同様に、 callback の起動を制御する際に 使用可能です。 このマスクを指定しない場合、 callback は error_reporting の設定によらず 全てのエラーに関してコールされます。

戻り値

前に定義されたエラーハンドラ(ある場合)を返します。 組み込みのエラーハンドラを使用している場合は null を返します。 前に定義されたハンドラがクラスメソッドの場合、この関数は、 クラスとメソッド名からなる添字配列を返します。

変更履歴

バージョン | 説明
8.0.0 | errcontext 引数は削除されました。 よって、ユーザー定義のコールバックに渡されることはありません。
7.2.0 | errcontext が非推奨になりました。 このパラメーターを使うと、 E_DEPRECATED レベルの警告が発生するようになりました。

例

例1 set_error_handler() および trigger_error() によるエラー処理

以下の例では、エラーを発生させることによる内部例外の処理や それらをユーザー定義関数で処理する方法を説明します。

<?php
// エラーハンドラ関数
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
if (!(error_reporting() & $errno)) {
// error_reporting 設定に含まれていないエラーコードのため、
// 標準の PHP エラーハンドラに渡されます。
return;
}

// $errstr はエスケープする必要があるかもしれません。
$errstr = htmlspecialchars($errstr);

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);

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 />

参考

  • ErrorException
  • error_reporting() - 出力する PHP エラーの種類を設定する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
  • エラーレベル定数


ユーザー定義の例外ハンドラ関数を設定する

  • ≪ set_error_handler
  • trigger_error ≫
  • PHP Manual
  • エラー処理関数
  • ユーザー定義の例外ハンドラ関数を設定する

set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する

説明

set_exception_handler(?callable $callback): ?callable

例外が try/catch ブロックの中でキャッチされなかった場合の デフォルトの例外ハンドラを設定します。 実行は、callback がコールされた後に 停止します。

パラメータ

callback

キャッチされない例外が発生した際にコールされる関数。 このハンドラ関数は、スローされる Throwable オブジェクトを引数にとります。 Error と Exception は、 どちらも Throwable インターフェイスを実装しています。 ハンドラのシグネチャは、次のようになります。

handler(Throwable $ex): void

null を渡すと、このハンドラをデフォルトの状態に戻せます。

戻り値

前に定義された例外ハンドラを返します。 エラー発生時に null を返します。 前にハンドラが定義されていない場合にも null が返されます。

例

例1 set_exception_handler() の例

<?php
function exception_handler(Throwable $exception) {
echo "Uncaught exception: " , $exception->getMessage(), "\n";
}

set_exception_handler('exception_handler');

throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>

参考

  • restore_exception_handler() - 以前の例外ハンドラ関数を回復する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • error_reporting() - 出力する PHP エラーの種類を設定する
  • 例外(exceptions)


ユーザーレベルのエラー/警告/通知メッセージを生成する

  • ≪ set_exception_handler
  • user_error ≫
  • PHP Manual
  • エラー処理関数
  • ユーザーレベルのエラー/警告/通知メッセージを生成する

trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する

説明

trigger_error(string $message, int $error_level = E_USER_NOTICE): true

ユーザーエラーを発生させるために使います。組み込みのエラーハンドラまたは新しいエラーハンドラ (set_error_handler()) として設定済みのユーザー定義関数と組み合わせて使うこともできます。

この関数は、実行時の例外に特定の応答を生成する必要がある場合に便利です。

パラメータ

message

このエラーに割り当てられたメッセージ。長さは最大 1024 バイトまでです。1024 バイトを超える部分は切り捨てられます。

error_level

このエラーに割り当てられたエラー型です。E_USER_* の定数のみが指定可能で、デフォルトは E_USER_NOTICE です。

戻り値

常に true を返します。

エラー / 例外

error_level が E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE, E_USER_DEPRECATED のいずれかでない場合、この関数は ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | 不正な error_level を指定すると、ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。

例

例1 trigger_error() の例

より拡張した例については set_error_handler() を参照ください。

<?php
if ($divisor == 0) {
trigger_error("ゼロで割ることはできません", E_USER_ERROR);
}
?>

注意

警告

message の HTML エンティティはエスケープされません。エラーをブラウザに表示するのであれば、メッセージに htmlentities() を使います。

参考

  • error_reporting() - 出力する PHP エラーの種類を設定する
  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • restore_error_handler() - 以前のエラーハンドラ関数を回復する
  • エラーレベル定数


trigger_error のエイリアス

  • ≪ trigger_error
  • FFI ≫
  • PHP Manual
  • エラー処理関数
  • trigger_error のエイリアス

user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — trigger_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 trigger_error().


Foreign Function Interface

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 例
    • Basic FFI usage
    • PHP Callbacks
    • A Complete PHP/FFI/preloading Example
  • FFI — Main interface to C code and data
    • FFI::addr — Creates an unmanaged pointer to C data
    • FFI::alignof — Gets the alignment
    • FFI::arrayType — Dynamically constructs a new C array type
    • FFI::cast — Performs a C type cast
    • FFI::cdef — Creates a new FFI object
    • FFI::free — Releases an unmanaged data structure
    • FFI::isNull — Checks whether a FFI\CData is a null pointer
    • FFI::load — Loads C declarations from a C header file
    • FFI::memcmp — Compares memory areas
    • FFI::memcpy — Copies one memory area to another
    • FFI::memset — Fills a memory area
    • FFI::new — Creates a C data structure
    • FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
    • FFI::sizeof — Gets the size of C data or types
    • FFI::string — Creates a PHP string from a memory area
    • FFI::type — Creates an FFI\CType object from a C declaration
    • FFI::typeof — Gets the FFI\CType of FFI\CData
  • FFI\CData — C Data Handles
  • FFI\CType — C Type Handles
    • FFI\CType::getAlignment — Description
    • FFI\CType::getArrayElementType — Description
    • FFI\CType::getArrayLength — Description
    • FFI\CType::getAttributes — Description
    • FFI\CType::getEnumKind — Description
    • FFI\CType::getFuncABI — Description
    • FFI\CType::getFuncParameterCount — Description
    • FFI\CType::getFuncParameterType — Description
    • FFI\CType::getFuncReturnType — Description
    • FFI\CType::getKind — Description
    • FFI\CType::getName — Description
    • FFI\CType::getPointerType — Description
    • FFI\CType::getSize — Description
    • FFI\CType::getStructFieldNames — Description
    • FFI\CType::getStructFieldOffset — Description
    • FFI\CType::getStructFieldType — Description
  • FFI\Exception — FFI Exceptions
  • FFI\ParserException — FFI Parser Exceptions


はじめに

This extension allows the loading of shared libraries (.DLL or .so), calling of C functions and accessing of C data structures in pure PHP, without having to have deep knowledge of the Zend extension API, and without having to learn a third "intermediate" language. The public API is implemented as a single class FFI with several static methods (some of them may be called dynamically), and overloaded object methods, which perform the actual interaction with C data.

警告

FFI is dangerous, since it allows to interface with the system on a very low level. The FFI extension should only be used by developers having a working knowledge of C and the used C APIs. To minimize the risk, the FFI API usage may be restricted with the ffi.enable php.ini directive.

注意:

The FFI extension does not render the classic PHP extension API obsolete; it is merely provided for ad-hoc interfacing with C functions and data structures.

ヒント

Currently, accessing FFI data structures is significantly (about 2 times) slower than accessing native PHP arrays and objects. Therefore, it makes no sense to use the FFI extension for speed; however, it may make sense to use it to reduce memory consumption.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • FFI
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

This extension requires the » libffi library to be installed.


インストール手順

To enable the FFI extension, PHP has to be configured with --with-ffi.

Windows users have to include php_ffi.dll into php.ini to enable the FFI extension.


実行時設定

php.ini の設定により動作が変化します。

FFI 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ffi.enable | "preload" | INI_SYSTEM |
ffi.preload | "" | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ffi.enable string

Allows enabling ("true") or disabling ("false") FFI API usage, or restricting it only to the CLI SAPI and preloaded files ("preload").

The FFI API restrictions only affect the FFI class, but not overloaded functions of FFI\CData objects. This means that it is possible to create some FFI\CData objects in preloaded files, and then to use these directly in PHP scripts.

ffi.preload string

Allows preloading of FFI bindings during startup, which is not possible with FFI::load() if opcache.preload_user is set. This directive accepts a DIRECTORY_SEPARATOR delimited list of filenames. The preloaded bindings can be accessed by calling FFI::scope().


例

目次

  • Basic FFI usage
  • PHP Callbacks
  • A Complete PHP/FFI/preloading Example


Basic FFI usage

Before diving into the details of the FFI API, lets take a look at a few examples demonstrating the simplicity of the FFI API usage for regular tasks.

注意:

Some of these examples require libc.so.6 and as such will not work on systems where it is not available.

例1 Calling a function from shared library

<?php
// create FFI object, loading libc and exporting function printf()
$ffi = FFI::cdef(
"int printf(const char *format, ...);", // this is a regular C declaration
"libc.so.6");
// call C's printf()
$ffi->printf("Hello %s!\n", "world");
?>

上の例の出力は以下となります。

Hello world!

注意:

Note that some C functions need specific calling conventions, e.g. __fastcall, __stdcall or ,__vectorcall.

例2 Calling a function, returning a structure through an argument

<?php
// create gettimeofday() binding
$ffi = FFI::cdef("
typedef unsigned int time_t;
typedef unsigned int suseconds_t;

struct timeval {
time_t tv_sec;
suseconds_t tv_usec;
};

struct timezone {
int tz_minuteswest;
int tz_dsttime;
};

int gettimeofday(struct timeval *tv, struct timezone *tz);
", "libc.so.6");
// create C data structures
$tv = $ffi->new("struct timeval");
$tz = $ffi->new("struct timezone");
// call C's gettimeofday()
var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
// access field of C data structure
var_dump($tv->tv_sec);
// print the whole C data structure
var_dump($tz);
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
int(1555946835)
object(FFI\CData:struct timezone)#3 (2) {
  ["tz_minuteswest"]=>
  int(0)
  ["tz_dsttime"]=>
  int(0)
}

例3 Accessing existing C variables

<?php
// create FFI object, loading libc and exporting errno variable
$ffi = FFI::cdef(
"int errno;", // this is a regular C declaration
"libc.so.6");
// print C's errno
var_dump($ffi->errno);
?>

上の例の出力は以下となります。

int(0)

例4 Creating and Modifying C variables

<?php
// create a new C int variable
$x = FFI::new("int");
var_dump($x->cdata);

// simple assignment
$x->cdata = 5;
var_dump($x->cdata);

// compound assignment
$x->cdata += 2;
var_dump($x->cdata);
?>

上の例の出力は以下となります。

int(0)
int(5)
int(7)

例5 Working with C arrays

<?php
// create C data structure
$a = FFI::new("long[1024]");
// work with it like with a regular PHP array
for ($i = 0; $i < count($a); $i++) {
$a[$i] = $i;
}
var_dump($a[25]);
$sum = 0;
foreach ($a as $n) {
$sum += $n;
}
var_dump($sum);
var_dump(count($a));
var_dump(FFI::sizeof($a));
?>

上の例の出力は以下となります。

int(25)
int(523776)
int(1024)
int(8192)

例6 Working with C enums

<?php
$a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
ZEND_FFI_SYM_TYPE,
ZEND_FFI_SYM_CONST = 2,
ZEND_FFI_SYM_VAR,
ZEND_FFI_SYM_FUNC
} zend_ffi_symbol_kind;
');
var_dump($a->ZEND_FFI_SYM_TYPE);
var_dump($a->ZEND_FFI_SYM_CONST);
var_dump($a->ZEND_FFI_SYM_VAR);
?>

上の例の出力は以下となります。

int(0)
int(2)
int(3)


PHP Callbacks

It is possible to assign a PHP closure to a native variable of function pointer type or to pass it as a function argument:

例1 Assigning a PHP Closure to a C function pointer

<?php
$zend = FFI::cdef("
typedef int (*zend_write_func_t)(const char *str, size_t str_length);
extern zend_write_func_t zend_write;
");

echo "Hello World 1!\n";

$orig_zend_write = clone $zend->zend_write;
$zend->zend_write = function($str, $len) {
global $orig_zend_write;
$orig_zend_write("{\n\t", 3);
$ret = $orig_zend_write($str, $len);
$orig_zend_write("}\n", 2);
return $ret;
};
echo "Hello World 2!\n";
$zend->zend_write = $orig_zend_write;
echo "Hello World 3!\n";
?>

上の例の出力は以下となります。

Hello World 1!
{
        Hello World 2!
}
Hello World 3!
Although this works, this functionality is not supported on all libffi platforms, is not efficient and leaks resources by the end of request.
ヒント

It is therefore recommended to minimize the usage of PHP callbacks.


A Complete PHP/FFI/preloading Example

php.ini

ffi.enable=preload
opcache.preload=preload.php

preload.php

<?php
FFI::load(__DIR__ . "/dummy.h");
opcache_compile_file(__DIR__ . "/dummy.php");
?>

dummy.h

#define FFI_SCOPE "DUMMY"
#define FFI_LIB "libc.so.6"

int printf(const char *format, ...);

dummy.php

<?php
final class Dummy {
private static $ffi = null;
function __construct() {
if (is_null(self::$ffi)) {
self::$ffi = FFI::scope("DUMMY");
}
}
function printf($format, ...$args) {
return (int)self::$ffi->printf($format, ...$args);
}
}
?>

test.php

<?php
$d = new Dummy();
$d->printf("Hello %s!\n", "world");
?>


Main interface to C code and data

(PHP 7 >= 7.4.0, PHP 8)

はじめに

Objects of this class are created by the factory methods FFI::cdef(), FFI::load() or FFI::scope(). Defined C variables are made available as properties of the FFI instance, and defined C functions are made available as methods of the FFI instance. Declared C types can be used to create new C data structures using FFI::new() and FFI::type().

FFI definition parsing and shared library loading may take significant time. It is not useful to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files may be extended with special FFI_SCOPE defines (e.g. #define FFI_SCOPE "foo"; the default scope is "C") and then loaded by FFI::load() during preloading. This leads to the creation of a persistent binding, that will be available to all the following requests through FFI::scope(). Refer to the complete PHP/FFI/preloading example for details.

It is possible to preload more than one C header file into the same scope.

クラス概要

final class FFI {
/* 定数 */
public const int __BIGGEST_ALIGNMENT__;
/* メソッド */
public static addr(FFI\CData &$ptr): FFI\CData
public static alignof(FFI\CData|FFI\CType &$ptr): int
public static arrayType(FFI\CType $type, array $dimensions): FFI\CType
public cast(FFI\CType|string $type, FFI\CData|int|float|bool|null &$ptr): ?FFI\CData
public static cdef(string $code = "", ?string $lib = null): FFI
public static free(FFI\CData &$ptr): void
public static isNull(FFI\CData &$ptr): bool
public static load(string $filename): ?FFI
public static memcmp(string|FFI\CData &$ptr1, string|FFI\CData &$ptr2, int $size): int
public static memcpy(FFI\CData &$to, FFI\CData|string &$from, int $size): void
public static memset(FFI\CData &$ptr, int $value, int $size): void
public new(FFI\CType|string $type, bool $owned = true, bool $persistent = false): ?FFI\CData
public static scope(string $name): FFI
public static sizeof(FFI\CData|FFI\CType &$ptr): int
public static string(FFI\CData &$ptr, ?int $size = null): string
public type(string $type): ?FFI\CType
public static typeof(FFI\CData &$ptr): FFI\CType
}

定義済み定数

FFI::__BIGGEST_ALIGNMENT__

目次

  • FFI::addr — Creates an unmanaged pointer to C data
  • FFI::alignof — Gets the alignment
  • FFI::arrayType — Dynamically constructs a new C array type
  • FFI::cast — Performs a C type cast
  • FFI::cdef — Creates a new FFI object
  • FFI::free — Releases an unmanaged data structure
  • FFI::isNull — Checks whether a FFI\CData is a null pointer
  • FFI::load — Loads C declarations from a C header file
  • FFI::memcmp — Compares memory areas
  • FFI::memcpy — Copies one memory area to another
  • FFI::memset — Fills a memory area
  • FFI::new — Creates a C data structure
  • FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
  • FFI::sizeof — Gets the size of C data or types
  • FFI::string — Creates a PHP string from a memory area
  • FFI::type — Creates an FFI\CType object from a C declaration
  • FFI::typeof — Gets the FFI\CType of FFI\CData


Creates an unmanaged pointer to C data

  • ≪ FFI
  • FFI::alignof ≫
  • PHP Manual
  • FFI
  • Creates an unmanaged pointer to C data

FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Creates an unmanaged pointer to C data

説明

public static FFI::addr(FFI\CData &$ptr): FFI\CData

Creates an unmanaged pointer to the C data represented by the given FFI\CData. The source ptr must survive the resulting pointer. This function is mainly useful to pass arguments to C functions by pointer.

パラメータ

ptr

The handle of the pointer to a C data structure.

戻り値

Returns the freshly created FFI\CData object.


Gets the alignment

  • ≪ FFI::addr
  • FFI::arrayType ≫
  • PHP Manual
  • FFI
  • Gets the alignment

FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Gets the alignment

説明

public static FFI::alignof(FFI\CData|FFI\CType &$ptr): int

Gets the alignment of the given FFI\CData or FFI\CType object.

パラメータ

ptr

The handle of the C data or type.

戻り値

Returns the alignment of the given FFI\CData or FFI\CType object.


Dynamically constructs a new C array type

  • ≪ FFI::alignof
  • FFI::cast ≫
  • PHP Manual
  • FFI
  • Dynamically constructs a new C array type

FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — Dynamically constructs a new C array type

説明

public static FFI::arrayType(FFI\CType $type, array $dimensions): FFI\CType

Dynamically constructs a new C array type with elements of type defined by type, and dimensions specified by dimensions. In the following example $t1 and $t2 are equivalent array types:

<?php
$t1 = FFI::type("int[2][3]");
$t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
?>

パラメータ

type

A valid C declaration as string, or an instance of FFI\CType which has already been created.

dimensions

The dimensions of the type as array.

戻り値

Returns the freshly created FFI\CType object.


Performs a C type cast

  • ≪ FFI::arrayType
  • FFI::cdef ≫
  • PHP Manual
  • FFI
  • Performs a C type cast

FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Performs a C type cast

説明

public FFI::cast(FFI\CType|string $type, FFI\CData|int|float|bool|null &$ptr): ?FFI\CData

FFI::cast() creates a new FFI\CData object, that references the same C data structure, but is associated with a different type. The resulting object does not own the C data, and the source ptr must survive the result. The C type may be specified as a string with any valid C type declaration or as FFI\CType object, created before. Any type declared for the instance is allowed.

パラメータ

type

A valid C declaration as string, or an instance of FFI\CType which has already been created.

ptr

The handle of the pointer to a C data structure.

戻り値

Returns the freshly created FFI\CData object.

変更履歴

バージョン | 説明
8.3.0 | Calling FFI::cast() statically is now deprecated.


Creates a new FFI object

  • ≪ FFI::cast
  • FFI::free ≫
  • PHP Manual
  • FFI
  • Creates a new FFI object

FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — Creates a new FFI object

説明

public static FFI::cdef(string $code = "", ?string $lib = null): FFI

Creates a new FFI object.

パラメータ

code

A string containing a sequence of declarations in regular C language (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files.

注意:

C preprocessor directives are not supported, i.e. #include, #define and CPP macros do not work.

lib

The name of a shared library file, to be loaded and linked with the definitions.

注意:

If lib is omitted or null, platforms supporting RTLD_DEFAULT attempt to lookup symbols declared in code in the normal global scope. Other systems will fail to resolve these symbols.

戻り値

Returns the freshly created FFI object.

変更履歴

バージョン | 説明
8.0.0 | lib is nullable now.


Releases an unmanaged data structure

  • ≪ FFI::cdef
  • FFI::isNull ≫
  • PHP Manual
  • FFI
  • Releases an unmanaged data structure

FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — Releases an unmanaged data structure

説明

public static FFI::free(FFI\CData &$ptr): void

Manually releases a previously created unmanaged data structure.

パラメータ

ptr

The handle of the unmanaged pointer to a C data structure.

戻り値

値を返しません。


Checks whether a FFI\CData is a null pointer

  • ≪ FFI::free
  • FFI::load ≫
  • PHP Manual
  • FFI
  • Checks whether a FFI\CData is a null pointer

FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Checks whether a FFI\CData is a null pointer

説明

public static FFI::isNull(FFI\CData &$ptr): bool

Checks whether a FFI\CData is a null pointer.

パラメータ

ptr

The handle of the pointer to a C data structure.

戻り値

Returns whether a FFI\CData is a null pointer.


Loads C declarations from a C header file

  • ≪ FFI::isNull
  • FFI::memcmp ≫
  • PHP Manual
  • FFI
  • Loads C declarations from a C header file

FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — Loads C declarations from a C header file

説明

public static FFI::load(string $filename): ?FFI

Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, using special FFI_LIB defines in the loaded C header file.

パラメータ

filename

The name of a C header file.

C preprocessor directives are not supported, i.e. #include, #define and CPP macros do not work, except for special cases listed below.

The header file should contain a #define statement for the FFI_SCOPE variable, e.g.: #define FFI_SCOPE "MYLIB". Refer to the class introduction for details.

The header file may contain a #define statement for the FFI_LIB variable to specify the library it exposes. If it is a system library only the file name is required, e.g.: #define FFI_LIB "libc.so.6". If it is a custom library, a relative path is required, e.g.: #define FFI_LIB "./mylib.so".

戻り値

Returns the freshly created FFI object, or null on failure.

参考

  • FFI::scope() - Instantiates an FFI object with C declarations parsed during preloading


Compares memory areas

  • ≪ FFI::load
  • FFI::memcpy ≫
  • PHP Manual
  • FFI
  • Compares memory areas

FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — Compares memory areas

説明

public static FFI::memcmp(string|FFI\CData &$ptr1, string|FFI\CData &$ptr2, int $size): int

Compares size bytes from the memory areas ptr1 and ptr2. Both ptr1 and ptr2 can be any native data structures (FFI\CData) or PHP strings.

パラメータ

ptr1

The start of one memory area.

ptr2

The start of another memory area.

size

The number of bytes to compare.

戻り値

Returns a value less than 0 if the contents of the memory area starting at ptr1 are considered less than the contents of the memory area starting at ptr2, a value greater than 0 if the contents of the first memory area are considered greater than the second, and 0 if they are equal.


Copies one memory area to another

  • ≪ FFI::memcmp
  • FFI::memset ≫
  • PHP Manual
  • FFI
  • Copies one memory area to another

FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — Copies one memory area to another

説明

public static FFI::memcpy(FFI\CData &$to, FFI\CData|string &$from, int $size): void

Copies size bytes from the memory area from to the memory area to.

パラメータ

to

The start of the memory area to copy to.

from

The start of the memory area to copy from.

size

The number of bytes to copy.

戻り値

値を返しません。


Fills a memory area

  • ≪ FFI::memcpy
  • FFI::new ≫
  • PHP Manual
  • FFI
  • Fills a memory area

FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Fills a memory area

説明

public static FFI::memset(FFI\CData &$ptr, int $value, int $size): void

Fills size bytes of the memory area pointed to by ptr with the given byte value.

パラメータ

ptr

The start of the memory area to fill.

value

The byte to fill with.

size

The number of bytes to fill.

戻り値

値を返しません。


Creates a C data structure

  • ≪ FFI::memset
  • FFI::scope ≫
  • PHP Manual
  • FFI
  • Creates a C data structure

FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Creates a C data structure

説明

public FFI::new(FFI\CType|string $type, bool $owned = true, bool $persistent = false): ?FFI\CData

Creates a native data structure of the given C type. Any type declared for the instance is allowed.

パラメータ

type

type is a valid C declaration as string, or an instance of FFI\CType which has already been created.

owned

Whether to create owned (i.e. managed) or unmanaged data. Managed data lives together with the returned FFI\CData object, and is released when the last reference to that object is released by regular PHP reference counting or GC. Unmanaged data should be released by calling FFI::free(), when no longer needed.

persistent

Whether to allocate the C data structure permanently on the system heap (using malloc()), or on the PHP request heap (using emalloc()).

戻り値

Returns the freshly created FFI\CData object, or null on failure.

変更履歴

バージョン | 説明
8.3.0 | Calling FFI::new() statically is now deprecated.


Instantiates an FFI object with C declarations parsed during preloading

  • ≪ FFI::new
  • FFI::sizeof ≫
  • PHP Manual
  • FFI
  • Instantiates an FFI object with C declarations parsed during preloading

FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — Instantiates an FFI object with C declarations parsed during preloading

説明

public static FFI::scope(string $name): FFI

Instantiates an FFI object with C declarations parsed during preloading.

The FFI::scope() method is safe to call multiple times for the same scope. Multiple references to the same scope may be loaded at the same time.

パラメータ

name

The scope name defined by a special FFI_SCOPE define.

戻り値

Returns the freshly created FFI object.

参考

  • FFI::load() - Loads C declarations from a C header file


Gets the size of C data or types

  • ≪ FFI::scope
  • FFI::string ≫
  • PHP Manual
  • FFI
  • Gets the size of C data or types

FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — Gets the size of C data or types

説明

public static FFI::sizeof(FFI\CData|FFI\CType &$ptr): int

Returns the size of the given FFI\CData or FFI\CType object.

パラメータ

ptr

The handle of the C data or type.

戻り値

The size of the memory area pointed at by ptr.


Creates a PHP string from a memory area

  • ≪ FFI::sizeof
  • FFI::type ≫
  • PHP Manual
  • FFI
  • Creates a PHP string from a memory area

FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — Creates a PHP string from a memory area

説明

public static FFI::string(FFI\CData &$ptr, ?int $size = null): string

Creates a PHP string from size bytes of the memory area pointed to by ptr.

パラメータ

ptr

The start of the memory area from which to create a string.

size

The number of bytes to copy to the string. If size is omitted or null, ptr must be a zero terminated array of C char.

戻り値

The freshly created PHP string.

変更履歴

バージョン | 説明
8.0.0 | size is nullable now; previously, its default was 0.


Creates an FFI\CType object from a C declaration

  • ≪ FFI::string
  • FFI::typeof ≫
  • PHP Manual
  • FFI
  • Creates an FFI\CType object from a C declaration

FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — Creates an FFI\CType object from a C declaration

説明

public FFI::type(string $type): ?FFI\CType

This function creates and returns a FFI\CType object for the given string containing a C type declaration. Any type declared for the instance is allowed.

パラメータ

type

A valid C declaration as string.

戻り値

Returns the freshly created FFI\CType object, or null on failure.

変更履歴

バージョン | 説明
8.3.0 | Calling FFI::type() statically is now deprecated.


Gets the FFI\CType of FFI\CData

  • ≪ FFI::type
  • FFI\CData ≫
  • PHP Manual
  • FFI
  • Gets the FFI\CType of FFI\CData

FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — Gets the FFI\CType of FFI\CData

説明

public static FFI::typeof(FFI\CData &$ptr): FFI\CType

Gets the FFI\CType object representing the type of the given FFI\CData object.

パラメータ

ptr

The handle of the pointer to a C data structure.

戻り値

Returns the FFI\CType object representing the type of the given FFI\CData object.


C Data Handles

(PHP 7 >= 7.4.0, PHP 8)

はじめに

FFI\CData objects can be used in a number of ways as a regular PHP data:

  • C data of scalar types can be read and assigned via the $cdata property, e.g. $x = FFI::new('int'); $x->cdata = 42;
  • C struct and union fields can be accessed as regular PHP object property, e.g. $cdata->field
  • C array elements can be accessed as regular PHP array elements, e.g. $cdata[$offset]
  • C arrays can be iterated using foreach statements.
  • C arrays can be used as arguments of count().
  • C pointers can be dereferenced as arrays, e.g. $cdata[0]
  • C pointers can be compared using regular comparison operators (<, <=, ==, !=, >=, >).
  • C pointers can be incremented and decremented using regular +/-/ ++/-- operations, e.g. $cdata += 5
  • C pointers can be subtracted from another using regular - operations.
  • C pointers to functions can be called as a regular PHP closure, e.g. $cdata()
  • Any C data can be duplicated using the clone operator, e.g. $cdata2 = clone $cdata;
  • Any C data can be visualized using var_dump(), print_r(), etc.
  • FFI\CData can now be assigned to structs and fields as of PHP 8.3.0.

注意: Notable limitations are that FFI\CData instances do not support isset(), empty() and unset(), and that wrapped C structs and unions do not implement Traversable.

クラス概要

final class FFI\CData {
}

変更履歴

バージョン | 説明
8.3.0 | FFI\CData can now be assigned to structs and fields.


C Type Handles

(PHP 7 >= 7.4.0, PHP 8)

はじめに

クラス概要

final class FFI\CType {
/* 定数 */
public const int TYPE_VOID;
public const int TYPE_FLOAT;
public const int TYPE_DOUBLE;
public const int TYPE_LONGDOUBLE;
public const int TYPE_UINT8;
public const int TYPE_SINT8;
public const int TYPE_UINT16;
public const int TYPE_SINT16;
public const int TYPE_UINT32;
public const int TYPE_SINT32;
public const int TYPE_UINT64;
public const int TYPE_SINT64;
public const int TYPE_ENUM;
public const int TYPE_BOOL;
public const int TYPE_CHAR;
public const int TYPE_POINTER;
public const int TYPE_FUNC;
public const int TYPE_ARRAY;
public const int TYPE_STRUCT;
public const int ATTR_CONST;
public const int ATTR_INCOMPLETE_TAG;
public const int ATTR_VARIADIC;
public const int ATTR_INCOMPLETE_ARRAY;
public const int ATTR_VLA;
public const int ATTR_UNION;
public const int ATTR_PACKED;
public const int ATTR_MS_STRUCT;
public const int ATTR_GCC_STRUCT;
public const int ABI_DEFAULT;
public const int ABI_CDECL;
public const int ABI_FASTCALL;
public const int ABI_THISCALL;
public const int ABI_STDCALL;
public const int ABI_PASCAL;
public const int ABI_REGISTER;
public const int ABI_MS;
public const int ABI_SYSV;
public const int ABI_VECTORCALL;
/* メソッド */
public getAlignment(): int
public getArrayElementType(): FFI\CType
public getArrayLength(): int
public getAttributes(): int
public getEnumKind(): int
public getFuncABI(): int
public getFuncParameterCount(): int
public getFuncParameterType(int $index): FFI\CType
public getFuncReturnType(): FFI\CType
public getKind(): int
public getName(): string
public getPointerType(): FFI\CType
public getSize(): int
public getStructFieldNames(): array
public getStructFieldOffset(string $name): int
public getStructFieldType(string $name): FFI\CType
}

定義済み定数

FFI\CType::TYPE_VOID

FFI\CType::TYPE_FLOAT

FFI\CType::TYPE_DOUBLE

FFI\CType::TYPE_LONGDOUBLE

FFI\CType::TYPE_UINT8

FFI\CType::TYPE_SINT8

FFI\CType::TYPE_UINT16

FFI\CType::TYPE_SINT16

FFI\CType::TYPE_UINT32

FFI\CType::TYPE_SINT32

FFI\CType::TYPE_UINT64

FFI\CType::TYPE_SINT64

FFI\CType::TYPE_ENUM

FFI\CType::TYPE_BOOL

FFI\CType::TYPE_CHAR

FFI\CType::TYPE_POINTER

FFI\CType::TYPE_FUNC

FFI\CType::TYPE_ARRAY

FFI\CType::TYPE_STRUCT

FFI\CType::ATTR_CONST

FFI\CType::ATTR_INCOMPLETE_TAG

FFI\CType::ATTR_VARIADIC

FFI\CType::ATTR_INCOMPLETE_ARRAY

FFI\CType::ATTR_VLA

FFI\CType::ATTR_UNION

FFI\CType::ATTR_PACKED

FFI\CType::ATTR_MS_STRUCT

FFI\CType::ATTR_GCC_STRUCT

FFI\CType::ABI_DEFAULT

FFI\CType::ABI_CDECL

FFI\CType::ABI_FASTCALL

FFI\CType::ABI_THISCALL

FFI\CType::ABI_STDCALL

FFI\CType::ABI_PASCAL

FFI\CType::ABI_REGISTER

FFI\CType::ABI_MS

FFI\CType::ABI_SYSV

FFI\CType::ABI_VECTORCALL

目次

  • FFI\CType::getAlignment — Description
  • FFI\CType::getArrayElementType — Description
  • FFI\CType::getArrayLength — Description
  • FFI\CType::getAttributes — Description
  • FFI\CType::getEnumKind — Description
  • FFI\CType::getFuncABI — Description
  • FFI\CType::getFuncParameterCount — Description
  • FFI\CType::getFuncParameterType — Description
  • FFI\CType::getFuncReturnType — Description
  • FFI\CType::getKind — Description
  • FFI\CType::getName — Description
  • FFI\CType::getPointerType — Description
  • FFI\CType::getSize — Description
  • FFI\CType::getStructFieldNames — Description
  • FFI\CType::getStructFieldOffset — Description
  • FFI\CType::getStructFieldType — Description


Description

  • ≪ FFI\CType
  • FFI\CType::getArrayElementType ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — Description

説明

public FFI\CType::getAlignment(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getAlignment
  • FFI\CType::getArrayLength ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Description

説明

public FFI\CType::getArrayElementType(): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getArrayElementType
  • FFI\CType::getAttributes ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Description

説明

public FFI\CType::getArrayLength(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getArrayLength
  • FFI\CType::getEnumKind ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Description

説明

public FFI\CType::getAttributes(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getAttributes
  • FFI\CType::getFuncABI ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Description

説明

public FFI\CType::getEnumKind(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getEnumKind
  • FFI\CType::getFuncParameterCount ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Description

説明

public FFI\CType::getFuncABI(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getFuncABI
  • FFI\CType::getFuncParameterType ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Description

説明

public FFI\CType::getFuncParameterCount(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getFuncParameterCount
  • FFI\CType::getFuncReturnType ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — Description

説明

public FFI\CType::getFuncParameterType(int $index): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

戻り値


Description

  • ≪ FFI\CType::getFuncParameterType
  • FFI\CType::getKind ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — Description

説明

public FFI\CType::getFuncReturnType(): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getFuncReturnType
  • FFI\CType::getName ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Description

説明

public FFI\CType::getKind(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getKind
  • FFI\CType::getPointerType ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Description

説明

public FFI\CType::getName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getName
  • FFI\CType::getSize ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Description

説明

public FFI\CType::getPointerType(): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getPointerType
  • FFI\CType::getStructFieldNames ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Description

説明

public FFI\CType::getSize(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getSize
  • FFI\CType::getStructFieldOffset ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Description

説明

public FFI\CType::getStructFieldNames(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ FFI\CType::getStructFieldNames
  • FFI\CType::getStructFieldType ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Description

説明

public FFI\CType::getStructFieldOffset(string $name): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


Description

  • ≪ FFI\CType::getStructFieldOffset
  • FFI\Exception ≫
  • PHP Manual
  • FFI\CType
  • Description

FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Description

説明

public FFI\CType::getStructFieldType(string $name): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


FFI Exceptions

(PHP 7 >= 7.4.0, PHP 8)

はじめに

クラス概要

class FFI\Exception extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


FFI Parser Exceptions

(PHP 7 >= 7.4.0, PHP 8)

はじめに

クラス概要

final class FFI\ParserException extends FFI\Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


OPcache

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • コードの事前ロード
  • OPcache 関数
    • opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする
    • opcache_get_configuration — キャッシュについての構成情報を取得
    • opcache_get_status — キャッシュについてのステータス情報を取得
    • opcache_invalidate — キャッシュされたスクリプトを無効にする
    • opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。
    • opcache_reset — opcode のキャッシュ内容をリセットする


はじめに

OPcache はコンパイル済みのバイトコードを共有メモリに保存し、PHP がリクエストのたびにスクリプトを読み込み、パースする手間を省くことでパフォーマンスを向上させます。

このPHP拡張モジュールは PHP 5.5.0 以降のバージョンにバンドルされています。 PHP 5.2, 5.3, 5.4 では » PECL で利用可能です。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • OPcache
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

OPcache は共有ライブラリ形式の拡張モジュールとしてしかコンパイルできません。 --disable-all を指定してデフォルトでコンパイルされる拡張モジュールを無効にしている場合は、OPcache が利用可能になるように --enable-opcache オプションを使って PHP をコンパイルしなければいけません。

いったんコンパイルすると、zend_extension 設定ディレクティブを使って OPcache を PHP にロードできます。これは zend_extension=/full/path/to/opcache.so という設定で行えます。Windows の場合は zend_extension=C:\path\to\php_opcache.dll を使います。

注意:

OPcache を » Xdebug と一緒に使う場合は、OPcache を Xdebug より前にロードさせなければいけません。

推奨される php.ini の設定

良好なパフォーマンスを得るために、一般的に推奨される設定は次の通りです。

opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.revalidate_freq=60
opcache.fast_shutdown=1 ; PHP 7.2.0 より前のバージョンで有効
opcache.enable_cli=1

opcache.save_comments を無効にし、 opcache.enable_file_override を有効にしたいと思うかもしれませんが、この設定を行う前に実運用環境であなたのコードを必ずテストするようにしてください。なぜなら、この設定は特にドキュメント向けのコメントやアノテーションを使っている場合に、既存のフレームワークやアプリケーションが壊れることが既知の現象としてあるからです。

Windows では、 opcache.file_cache_fallback を有効にすべきです。 かつ、既に存在し、書き込み可能なディレクトリを opcache.file_cache に設定すべきです。

OPcache がサポートしている設定ディレクティブの完全なリストは 実行時設定 のページにあります。


実行時設定

php.ini の設定により動作が変化します。

OPcache 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
opcache.enable | 1 | INI_ALL |
opcache.enable_cli | 0 | INI_SYSTEM | PHP 7.1.2 と 7.1.6 の間では、デフォルトは 1 でした
opcache.memory_consumption | 128 | INI_SYSTEM |
opcache.interned_strings_buffer | 8 | INI_SYSTEM |
opcache.max_accelerated_files | 10000 | INI_SYSTEM |
opcache.max_wasted_percentage | 5 | INI_SYSTEM |
opcache.use_cwd | 1 | INI_SYSTEM |
opcache.validate_timestamps | 1 | INI_ALL |
opcache.revalidate_freq | 2 | INI_ALL |
opcache.revalidate_path | 0 | INI_ALL |
opcache.save_comments | 1 | INI_SYSTEM |
opcache.fast_shutdown | 0 | INI_SYSTEM | PHP 7.2.0 で削除されました
opcache.enable_file_override | 0 | INI_SYSTEM |
opcache.optimization_level | 0x7FFEBFFF | INI_SYSTEM | PHP 7.3.0 で 0x7FFFBFFF から変更されました。
opcache.inherited_hack | 1 | INI_SYSTEM | PHP 7.3.0 で削除されました
opcache.dups_fix | 0 | INI_ALL |
opcache.blacklist_filename | "" | INI_SYSTEM |
opcache.max_file_size | 0 | INI_SYSTEM |
opcache.consistency_checks | 0 | INI_ALL | PHP 8.1.18 と PHP 8.2.5 で無効。PHP 8.3.0 で削除。
opcache.force_restart_timeout | 180 | INI_SYSTEM |
opcache.error_log | "" | INI_SYSTEM |
opcache.log_verbosity_level | 1 | INI_SYSTEM |
opcache.record_warnings | 0 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.preferred_memory_model | "" | INI_SYSTEM |
opcache.protect_memory | 0 | INI_SYSTEM |
opcache.mmap_base | null | INI_SYSTEM | Windows のみ
opcache.restrict_api | "" | INI_SYSTEM |
opcache.file_update_protection | 2 | INI_ALL |
opcache.huge_code_pages | 0 | INI_SYSTEM |
opcache.lockfile_path | "/tmp" | INI_SYSTEM |
opcache.opt_debug_level | 0 | INI_SYSTEM | PHP 7.1.0 以降で利用可能
opcache.file_cache | null | INI_SYSTEM |
opcache.file_cache_only | 0 | INI_SYSTEM |
opcache.file_cache_consistency_checks | 1 | INI_SYSTEM |
opcache.file_cache_fallback | 1 | INI_SYSTEM | Windows のみ
opcache.validate_permission | 0 | INI_SYSTEM | PHP 7.0.14 以降で利用可能
opcache.validate_root | 0 | INI_SYSTEM | PHP 7.0.14 以降で利用可能
opcache.preload | "" | INI_SYSTEM | PHP 7.4.0 以降で利用可能
opcache.preload_user | "" | INI_SYSTEM | PHP 7.4.0 以降で利用可能
opcache.cache_id | "" | INI_SYSTEM | Windows のみ。PHP 7.4.0 以降で利用可能
opcache.jit | "tracing" | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_buffer_size | 0 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_debug | 0 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_bisect_limit | 0 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_prof_threshold | 0.005 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_root_traces | 1024 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_max_side_traces | 128 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_max_exit_counters | 8192 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_loop | 64 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_func | 127 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_return | 8 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_side_exit | 8 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_blacklist_root_trace | 16 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_blacklist_side_trace | 8 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_loop_unrolls | 8 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_recursive_calls | 2 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_recursive_returns | 2 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_polymorphic_calls | 2 | INI_ALL | PHP 8.0.0 以降で利用可能
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

opcache.enable bool

オペコード・キャッシュを有効にします。 無効にした場合、コードは最適化もキャッシュもされません。 opcache.enable の設定を、実行時に ini_set() で有効化することはできません。 実行時にできるのは、無効化だけです。スクリプト内で有効化しようとすると、警告が発生します。

opcache.enable_cli bool

PHP の CLI 版に対してオペコード・キャッシュを有効にします。

opcache.memory_consumption int

OPcache によって使用される共有メモリ・ストレージのサイズ。（ MB 単位） 設定できる最小値は "8" です。これより小さい値を設定しても、最小値が強制されます。

opcache.interned_strings_buffer int

インターン化 (intern) された文字列を格納するために使用されるメモリ量。（ MB 単位）

opcache.max_accelerated_files int

OPcache ハッシュテーブルのキー（すなわちスクリプト）の最大数。 使用される現時点の値は、 素数の集合 { 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 } のうち、 設定値以上の最初の数値です。 最小値は 200 です。最大値は 1000000 です。 これらの範囲外の値が設定されても、範囲内の値に設定し直されます。

opcache.max_wasted_percentage int

メモリが不十分な場合に、再起動がスケジュールされるまでに許される、無駄なメモリの最大の割合。 最大値は "50" です。これ以上の値が設定されても、最大値が強制されます。

opcache.use_cwd bool

有効にすると、OPcache は現行の作業ディレクトリをスクリプト・キーに追加します。 その方法によって、同じ基底名を持つファイル同士で起こりうる衝突を回避します。 このディレクティブを無効にするとパフォーマンスが向上しますが、既存のアプリケーションを破壊するかもしれません。

opcache.validate_timestamps bool

有効にすると、OPcache は、スクリプトが更新されたかを opcache.revalidate_freq 秒ごとにチェックします。 このディレクティブが無効な場合、ファイルシステムへの変更を反映するには、 opcache_reset() または opcache_invalidate() 関数を介して、 または Web サーバーを再起動して手動で OPcache をリセットしなければいけません。

注意: opcache.file_update_protection や opcache.max_file_size の値に0でない値が設定されている場合、OPcache はファイルのタイムスタンプをまだコンパイル時にチェックする可能性があります。

opcache.revalidate_freq int

更新のためにスクリプトのタイムスタンプをチェックする頻度。（秒単位） 0 にすると、OPcache は、リクエストごとに更新をチェックします。

この設定ディレクティブは、 opcache.validate_timestamps が無効の場合、 無視されます。

opcache.revalidate_path bool

無効にすると、 同一の include_path を使用する、 キャッシュされた既存のファイルが再利用されます。 したがって、同じ名前を持つファイルが include_path の他の部分にあると、それは見つかりません。

opcache.save_comments bool

無効にすると、最適化したコードのサイズを減らすために OPcode キャッシュからすべてのドキュメンテーション・コメントが廃棄されます。 この設定ディレクティブを無効にすると、注釈のためにコメント・パースに依存するアプリケーションおよびフレームワークを破壊するかもしれません。 それには、Doctrine、Zend Framework 2 および PHPUnit が含まれます。

opcache.fast_shutdown bool

有効にすると、それぞれに割り当てられたブロックを解放しない、高速シャットダウン・シーケンスが使用されます。 しかし、リクエスト変数のすべてのセットをひとまとめに割当てを解除することは、Zend Engine のメモリ・マネージャに依存します。

このディレクティブは、PHP 7.2.0 で削除されました。 高速なシャットダウンシーケンスの類の設定は、PHP本体に統合され、可能であれば自動的に使用されます。

opcache.enable_file_override bool

有効にすると、file_exists()、 is_file() および is_readable() が呼ばれた際に、 ファイルが既にキャッシュ済みかどうかをオペコード・キャッシュからチェックします。 これは、PHP スクリプトの存在および読み込み可能かをチェックするアプリケーションのパフォーマンスを改善させるかもしれません。 しかし、opcache.validate_timestamps が無効な場合に、 陳腐化した結果を返す危険があります。

opcache.optimization_level int

どの最適化パスが実行されるかコントロールするビットマスク。 デフォルトでは、すべての安全な最適化を適用します。 デフォルト値の変更が役に立つのは、 大半が最適化エンジンをデバッグ/開発する時です(opcache.opt_debug_level も参照ください)。

opcache.inherited_hack bool

この設定ディレクティブの値は無視されます。

opcache.dups_fix bool

"Cannot redeclare class" （クラスを再宣言できません）というエラーを回避する目的でのみ、このハックを有効にするべきです。

opcache.blacklist_filename string

OPcache ブラックリスト・ファイルの場所。 ブラックリスト・ファイルは、高速化すべきではないファイルの名前を 1 行につき 1 つ含むテキストファイルです。 ワイルドカードが許されます。そして、プレフィックスも提示できます。 セミコロンで始まる行は、コメントとして無視されます。

簡単なブラックリスト・ファイルは、以下の通りかもしれません。

; 特定のファイルに一致します。
/var/www/broken.php
; x で始まるすべてのファイルに一致するプレフィックス
/var/www/x
; ワイルドカード一致です。
/var/www/*-broken.php
opcache.max_file_size int

キャッシュできるファイル・サイズの最大。（バイト単位） これが 0 の場合、すべてのファイルがキャッシュされます。

opcache.consistency_checks int

ゼロ以外の場合、OPcache は、リクエスト Ｎ 回毎にキャッシュのチェックサムを検証します。 N は、この設定ディレクティブの値です。 パフォーマンスを損なうので、これはデバッグ時のみ有効にすべきです。

注意:

PHP 8.1.18 と 8.2.5 で無効になり、PHP 8.3.0 で削除されました。

opcache.force_restart_timeout int

キャッシュがアクティブではない場合に、スケジュールされた再起動が始まるのを待つ時間の長さ。（秒単位） タイムアウトに達すると、OPcache は何か具合が悪いとみなして、リスタートできるようにするためにキャッシュのロックを所持する処理を殺します。

opcache.log_verbosity_level が 2 以上の場合、警告発生時にエラーログに記録されます。

このディレクティブは、Windows ではサポートされていません。

opcache.error_log string

エラーに対するエラーログ。 空の文字列は、stderr と同様に扱われ、 結果として標準エラー（ほとんどの場合、Web サーバーのエラーログです）に送られるログになります。

opcache.log_verbosity_level int

ログ冗長レベルです。 デフォルトでは、致命的エラー（レベル 0 ）およびエラー（レベル 1 ）だけが記録されます。 利用できる他のレベルは、警告（レベル 2 ）、情報メッセージ（レベル 3 ）およびデバッグ・メッセージ（レベル 4 ）です。

opcache.record_warnings bool

有効にすると、OPcache はコンパイル時の警告を記録し、 次回の include 時にもその警告を再度発生させます。 これは、コードがキャッシュされていたとしても同じです。

opcache.preferred_memory_model string

OPcache が使用する優先のメモリ・モデル。 空のままにすると、OPcache は最も適切なモデルを選びます。 それは実質的にすべての場合に正しい振る舞いです。

可能な値には、mmap、shm、 posix および win32 があります。

opcache.protect_memory bool

スクリプト実行中に予期しない書込みから共有メモリを保護する。 これは、内部のデバッギングだけに役立ちます。

opcache.mmap_base string

Windows 上で共有メモリ・セグメントに使用される基底。 すべての PHP 処理は、共有メモリを同じアドレス空間にマップしなければいけません。 このディレクティブを使用すると、"Unable to reattach to base address" （基底アドレスに再アタッチできません） というエラーを修復できます。

opcache.restrict_api string

OPcache API 関数の呼び出しを、指定した文字列から始まるパス上の PHP スクリプトからだけに制限します。 デフォルトは "" で、これは、何も制限しないことを意味します。

opcache.file_update_protection string

ここで指定された秒数の間は、キャッシュすることを防ぎます。 これにより、不完全に更新されたファイルがキャッシュされることを防止します。 全てのファイルの更新がアトミックに行われる場合、 この設定を "0" に設定することで、パフォーマンスを向上させられる可能性があります。なぜなら、こうすることでファイルがすぐにキャッシュされるからです。

opcache.huge_code_pages bool

PHPコード(textセグメント)を HUGE PAGE にコピーする機能を有効にしたり、無効にしたりできます。 これにより、パフォーマンスは向上するはずですが、適切なOSの設定が必要です。 Linux では PHP 7.0.0 以降、FreeBSD では PHP 7.4.0 以降が必要です。

opcache.lockfile_path string

共用ロックファイルを格納する絶対パス (*nix のみ)

opcache.opt_debug_level string

異なった段階の最適化をデバッグするために、オペコードのダンプを生成します。 0x10000 を指定すると、あらゆる最適化の前にコンパイラが提供するオペコードを出力します。 0x20000 を指定すると、最適化されたコードを出力します。

opcache.file_cache string

ファイルベースのセカンドレベル opcode キャッシュを有効にし、そのディレクトリを設定します。 これは共有メモリ上の opcode キャッシュがいっぱいの時やサーバー再起動時、 もしくは共有メモリ上の opcode キャッシュをリセットした場合のパフォーマンスを向上させます。 デフォルトは "" で、これはファイルベースのキャッシュを無効にします。

opcache.file_cache_only bool

共有メモリ内でのオペコード・キャッシュを有効あるいは無効にします。

注意:

PHP 8.1.0 より前のバージョンでは、 既に収集されているファイルキャッシュに対してこのディレクティブを無効にするには、 手動でファイルキャッシュをクリアする必要があります。

opcache.file_cache_consistency_checks bool

ファイルキャッシュから読み込んだスクリプトのチェックサムの検証を有効あるいは無効にします。

opcache.file_cache_fallback bool

共有メモリへの再アタッチに失敗するプロセスについて、 opcache.file_cache_only=1 であるものとみなします (Windows のみ)。 ファイルキャッシュを明示的に有効にする必要があります。

警告

この構成オプションを無効にすると、プロセスの開始が妨げられる可能性があります。 そのため推奨しません。

opcache.validate_permission bool

キャッシュされたファイルのアクセス権限を現在のユーザーに対して検証します。

opcache.validate_root bool

chroot された環境での名前の衝突を防止します。 これは、chroot 以外でのファイルへのアクセスを防止するために、 chroot されたすべての環境で有効にする必要があります。

opcache.preload string

サーバーが起動した際にコンパイルされ、実行されるPHPスクリプトを指定します。 ここで指定したファイルは include されたり、opcache_compile_file() 関数で指定されることで他のファイルも事前ロードするかもしれません。 それらのファイルに指定された全てのエンティティ(e.g 関数やクラス) は、サーバーがシャットダウンされるまで、外部からのリクエストに対して利用できるようになります。

注意:

コードの事前ロードは、Windows ではサポートされていません。

opcache.preload_user string

指定されたシステムユーザでコードを事前ロードするようにします。 これは、特権がないシステムユーザに切り替える前に、 root で起動するサーバーの場合に役立ちます。 root ユーザでコードを事前ロードすることは、 セキュリティ上の理由からデフォルトでは禁止されています。 但し、このディレクティブに明示的に root を指定した場合は許可されます。

opcache.cache_id string

Windows では、同じユーザーアカウントで同じ PHP SAPI を実行し、 かつ同じ cache ID を持つ全てのプロセスが同一の OPcache インスタンスを共有します。 cache ID の値は自由に選べます。

ヒント

IIS の場合、異なるアプリケーションプールは 環境変数 APP_POOL_ID を opcache.cache_id の値として使うことで、 それぞれが異なる OPcache インスタンスを持つことが出来ます。

opcache.jit string|int

典型的な使い方として、このオプションには以下の4通りの文字列を指定できます。

  • disable: 完全に無効にする。実行時にも有効にできません。
  • off: 無効にしますが、実行時に有効にできます。
  • tracing/on: トレーシングJIT を使う。 デフォルトはこの値です。ほとんどのユーザに推奨される値です。
  • function: 関数単位でJITを使う。

高度な使い方として、このオプションには4桁の整数値 CRTO を指定できます。 それぞれの桁の意味は下記のとおりです。

C (特定のCPU向けの最適化フラグ)
  • 0: 特定のCPU向けの最適化を無効にする
  • 1: CPU がサポートしている場合に、AVX の使用を有効にする。
R (レジスタの割り付け)
  • 0: レジスタ割り付けを行わない
  • 1: ブロックについて、ローカルレジスタ割り付けを行う
  • 2: グローバルレジスタ割り付けを行う
T (JITを行うトリガ)
  • 0: スクリプトの読み込み時に全ての関数をコンパイルする
  • 1: 最初の実行時に関数をコンパイルする
  • 2: 最初のリクエスト時に関数の実行をプロファイリングし、 ホットな関数を後でコンパイルします。
  • 3: その場でプロファイリングを行い、ホットな関数をコンパイルします
  • 4: 現在は使われていません。
  • 5: トレーシングJITを使う。 その場でプロファイリングを行い、ホットコードの断片のトレースをコンパイルします。
O (最適化レベル)
  • 0: JIT を使わない
  • 1: 最小限しかJITを使わない (通常のVMハンドラを呼び出す)
  • 2: VMハンドラをインライン化する
  • 3: 型推論を使う
  • 4: コールグラフを使う
  • 5: スクリプト全体を最適化する
"tracing" モードは、CRTO = 1254 に対応しています。 "function" モードは、CRTO = 1205 に対応しています。

opcache.jit_buffer_size int

コンパイル済みのJITコードを保存する共有メモリの合計サイズ。 0 を指定すると、JIT が無効になります。

intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。
opcache.jit_debug int

どの JIT のデバッグ出力を有効にするかを指定するビットマスク。 指定可能な値については、zend_jit.h を参照ください (ZEND_JIT_DEBUG から始まるマクロ定義を検索してください)。

opcache.jit_bisect_limit int

一定の数の関数をコンパイル後、JIT コンパイルを無効にするデバッグオプション。 このオプションは、JITコンパイルが失敗している原因を二分探索するのに役立ちます。 注意: このオプションは、「JITを行うトリガ」が 0 (スクリプトの読み込み時に全ての関数をコンパイル) または 1 (最初の実行時に関数をコンパイルする) の場合に機能します。たとえば opcache.jit=1215 の場合です。opcache.jit も参照ください。

opcache.jit_prof_threshold float

JITを行うトリガに "最初のリクエスト時にプロファイリングを行う" モードが指定されている場合、 どの関数がホットであるかはこのしきい値によって決まります。 特定の関数の呼び出し回数を、全関数の呼び出し回数で割った数は、この値以上でなければなりません。 たとえば、0.005 という値を指定すると、 全ての呼び出しの 0.5% 以上を占める関数が JITコンパイルされるという意味になります。

opcache.jit_max_root_traces int

ルートトレースの数の最大値を指定します。 ルートトレースとは、最初に実行されるコードの実行フローのことで、 これが JIT のコンパイル単位になります。 この最大値に達すると、JIT は新しくコードをコンパイルしません。

opcache.jit_max_side_traces int

ルートトレースが、サイドトレースを最大いくつ持つことができるかを指定します。 サイドトレースとは、コンパイル済みのルートトレースのパスとは別の実行フローのことです。 同じルートトレースに属するサイドトレースは、 この最大値に達するとコンパイルされません。

opcache.jit_max_exit_counters int

サイドトレースの出口のカウンタを最大いくつ持つかを指定します。 この数によって、全ルートトレースが持つサイドトレースの数の合計値を制御できます。

opcache.jit_hot_loop int

何回イテレーションが行われたら、そのループをホットと判断するかを指定します。 有効な値の範囲は [0,255] です。 範囲外の値 (例: -1 や 256) を設定すると、 デフォルトの値が使われます。特に 0 を設定すると、 JIT はどのイテレーションにおいてもコンパイルとトレースをしなくなります。

opcache.jit_hot_func int

何回関数呼び出しが行われたら、関数をホットと判断するかを指定します。 有効な値の範囲は [0,255] です。 範囲外の値 (例: -1 や 256) を設定すると、 デフォルトの値が使われます。特に 0 を設定すると、 JIT はどの関数呼び出しにおいてもコンパイルとトレースをしなくなります。

opcache.jit_hot_return int

何回リターンした場合に、そのリターンをホットと判断するかを指定します。 有効な値の範囲は [0,255] です。 範囲外の値 (例: -1 や 256) を設定すると、 デフォルトの値が使われます。特に 0 を設定すると、 JIT はどのリターンにおいてもコンパイルとトレースをしなくなります。

opcache.jit_hot_side_exit int

サイドトレースから何回抜けたら、ホットと判断するかを指定します。 有効な値の範囲は [0,255] です。 範囲外の値 -1 や 256) を設定すると、 デフォルトの値が使われます。特に 0 を設定すると、 JIT はどのサイドトレースから抜けてもコンパイルとトレースをしなくなります。

opcache.jit_blacklist_root_trace int

ブラックリストに入れるまでに、ルートトレースのコンパイルを最大何回試みるかを指定します。

opcache.jit_blacklist_side_trace int

ブラックリストに入れるまでに、サイドトレースのコンパイルを最大何回試みるかを指定します。

opcache.jit_max_loop_unrolls int

ルートトレースに達して外側のループが閉じられるまでに、 サイドトレース内で行えるループ展開の回数の最大値を指定します。

opcache.jit_max_recursive_calls int

再帰的な呼び出しループを展開する最大の回数を指定します。

opcache.jit_max_recursive_returns int

再帰的に行われるリターンを展開する最大回数を指定します。

opcache.jit_max_polymorphic_calls int

(動的な、もしくはメソッドの)ポリモーフィックな呼び出しのインライン化を試みる回数の最大値を指定します。 この呼び出し回数を超えると、メガモーフィックと見なされ、インライン化されません。


コードの事前ロード

PHP 7.4.0 以降では、エンジンの起動時に opcache に事前ロードするスクリプトを指定できるようになりました。 指定されたファイルに存在するあらゆる 関数、クラス、 インターフェイス や トレイト (定数は除く) は、 明示的にインクルードすることなく全てのリクエストからグローバルに利用できるようになります。 これにより(コードが常に利用できるようになるため)、メモリ使用量と、 パフォーマンスおよび便利さのトレードオフが発生します。 事前ロードされたスクリプトをクリアするには PHP プロセスの再起動が必要です。 つまり、この機能は本番環境でのみ役に立ちます。開発環境では役に立ちません。

パフォーマンスとメモリ使用量の最適なトレードオフは、アプリケーションによって異なることに注意して下さい。 "全てをあらかじめ読み込む" ことはもっとも簡単な戦略かもしれませんが、 必ずしも最適とは限りません。 さらに、コードの事前ロードは、リクエストが終了しても継続して生き残るプロセスの場合にだけ役に立ちます。 つまり、opcache が有効になった CLI スクリプトは動作はしますが、 一般的にコードの事前ロードは役に立ちません。 但し、FFI 経由でコードの事前ロードを使う場合は例外です。

注意:

コードの事前ロードは、Windows ではサポートされていません。

コードの事前ロードを設定するには、2つのステップが必要です。 まず、opcache を有効にしなければなりません。 その上で、opcache.preload の値を php.ini に設定します。

opcache.preload=preload.php

preload.php は、サーバーの起動時(PHP-FPM, mod_php, など) に一度だけ実行され、リクエストを越えて生き残るメモリ領域に読み込まれる任意のファイルです。 特権のないシステムユーザに切り替える前に root で起動するサーバーの場合や、 PHP が root 権限で実行(推奨されません)される場合のために、 opcache.preload_user を使って事前ロードを実行するためのシステムユーザーを指定することが出来ます。 デフォルトでは、事前ロードを root で行うことは禁止されていますが、 明示的に opcache.preload_user=root と指定した場合は許可されます。

preload.php スクリプトでは、 include, include_once, require, require_once, opcache_compile_file() で参照されるあらゆるファイルが評価され、 リクエストを越えて生き残るメモリ領域に読み込まれます。 次の例では、src ディレクトリにある全ての .php ファイルが事前ロードされます。 但し、Test ファイルの場合を除きます。

<?php
$directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
$fullTree = new RecursiveIteratorIterator($directory);
$phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);

foreach ($phpFiles as $key => $file) {
require_once $file[0];
}
?>

include と opcache_compile_file() 両方が動作しますが、コードをどう扱うかが異なります。

  • include は、ファイル内でコードを実行しますが、 opcache_compile_file() は実行しません。 これは、前者のみが条件付きの宣言 (if ブロック内の関数宣言)をサポートしているということです。
  • include はコードを実行するので、 ネストして include されたファイルも評価され、 それに含まれる宣言も事前ロードされます。
  • opcache_compile_file() は任意の順番でファイルを読み込むことが出来ます。 つまり、a.php が クラス A を定義しており、 b.php が A を継承したクラス B を定義している場合、 opcache_compile_file() はそれらふたつのファイルを任意の順番で読み込めます。 しかし、include を使う場合、 a.php は 必ず 最初にインクルードしなければなりません。
  • どちらの場合も、後に読み込まれるスクリプトが、 既に事前ロードされているファイルをインクルードしていれば、 スクリプトの内容は実行されます。しかし、そこで定義されているシンボルは再定義されません。 include_once を使っても、 ファイルが二度インクルードされることを妨げません。 ファイルで定義されたグローバルな定数をインクルードするために、 ファイルを再読み込みする必要があるかもしれません。 なぜなら、定数は事前ロードでは処理されないからです。
どちらのアプローチが優れているかは、あなたがどのような挙動を望むか次第です。 オートローディング と一緒に使うことで、 opcache_compile_file() は大きな柔軟性を得られます。 一方で、手動でコードをロードする場合、 include を使うほうが堅牢になるでしょう。


OPcache 関数

目次

  • opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする
  • opcache_get_configuration — キャッシュについての構成情報を取得
  • opcache_get_status — キャッシュについてのステータス情報を取得
  • opcache_invalidate — キャッシュされたスクリプトを無効にする
  • opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。
  • opcache_reset — opcode のキャッシュ内容をリセットする


PHP スクリプトを、実行せずにコンパイルしてキャッシュする

  • ≪ OPcache 関数
  • opcache_get_configuration ≫
  • PHP Manual
  • OPcache 関数
  • PHP スクリプトを、実行せずにコンパイルしてキャッシュする

opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする

説明

opcache_compile_file(string $filename): bool

この関数は、PHP スクリプトをコンパイルして opcode キャッシュに追加しますが、スクリプトは実行しません。 これを使うと、ウェブサーバーの再起動後にファイルをキャッシュしておき、 後でリクエストがあったときにそのキャッシュを使えるようになります。

パラメータ

filename

コンパイルしたい PHP スクリプトへのパス。

戻り値

filename を正常にコンパイルしたときに true を返します。 失敗した場合に false を返します。

エラー / 例外

filename を読み込めなかったりコンパイルできなかったりした場合は E_WARNING レベルのエラーが発生します。 @ を使えば、この警告を抑制できます。

参考

  • opcache_invalidate() - キャッシュされたスクリプトを無効にする


キャッシュについての構成情報を取得

  • ≪ opcache_compile_file
  • opcache_get_status ≫
  • PHP Manual
  • OPcache 関数
  • キャッシュについての構成情報を取得

opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — キャッシュについての構成情報を取得

説明

opcache_get_configuration(): array|false

この関数は、キャッシュ・インスタンスについての構成情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

情報の配列を返します。その配列は ini 、ブラックリストおよびバージョンを含みます。

エラー / 例外

opcache.restrict_api を使用中で、 かつ現在のパスがルール違反の場合、 E_WARNING が発生します。 ステータス情報は返されません。

参考

  • opcache_get_status() - キャッシュについてのステータス情報を取得


キャッシュについてのステータス情報を取得

  • ≪ opcache_get_configuration
  • opcache_invalidate ≫
  • PHP Manual
  • OPcache 関数
  • キャッシュについてのステータス情報を取得

opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — キャッシュについてのステータス情報を取得

説明

opcache_get_status(bool $include_scripts = true): array|false

この関数は、インメモリ の キャッシュ・インスタンス についてのステータス情報を返します。 ファイルキャッシュに関する情報は一切返しません。

パラメータ

include_scripts

スクリプト固有の状態の情報を含む。

戻り値

情報の配列を返します。スクリプト固有の状態の情報をオプションで含みます、 失敗した場合に false を返します。

エラー / 例外

opcache.restrict_api を使用中で、 かつ現在のパスがルール違反の場合、 E_WARNING が発生します。 ステータス情報は返されません。

参考

  • opcache_get_configuration() - キャッシュについての構成情報を取得


キャッシュされたスクリプトを無効にする

  • ≪ opcache_get_status
  • opcache_is_script_cached ≫
  • PHP Manual
  • OPcache 関数
  • キャッシュされたスクリプトを無効にする

opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — キャッシュされたスクリプトを無効にする

説明

opcache_invalidate(string $filename, bool $force = false): bool

この関数は opcode キャッシュのうち、特定のスクリプトを無効にします。 force パラメータが指定されていないか、 false の場合は、スクリプトの更新時刻が opcode キャッシュ時の更新時刻より新しい場合にだけ無効にします。 この関数は、インメモリキャッシュ の情報だけを無効にします。 ファイルキャッシュ の情報は無効にしません。

パラメータ

filename

無効にしたいスクリプトのパス

force

true にすると、無効にする必要があるかどうかに関わらずスクリプトは無効にされます。

戻り値

filename の opcode キャッシュが無効にされたか、無効にする対象が存在しない場合は true を返します。 opcode キャッシュ機能そのものが無効にされている場合は false を返します。

参考

  • opcache_compile_file() - PHP スクリプトを、実行せずにコンパイルしてキャッシュする
  • opcache_reset() - opcode のキャッシュ内容をリセットする


スクリプトが OPCache にキャッシュされているかどうかを伝えます。

  • ≪ opcache_invalidate
  • opcache_reset ≫
  • PHP Manual
  • OPcache 関数
  • スクリプトが OPCache にキャッシュされているかどうかを伝えます。

opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。

説明

opcache_is_script_cached(string $filename): bool

この関数は、PHP スクリプトが OPCache にキャッシュされているかチェックします。 これは、特定のスクリプトに対するキャッシュの "ウォーミング" をより簡単に検出するために使用できます。 この関数は、インメモリキャッシュ の情報だけをチェックします。 ファイルキャッシュ の情報はチェックしません。

パラメータ

filename

チェックされる PHP スクリプトへのパスです。

戻り値

filename が OPCache にキャッシュされている場合、true を、 そうでなければ false を返します。

参考

  • opcache_compile_file() - PHP スクリプトを、実行せずにコンパイルしてキャッシュする


opcode のキャッシュ内容をリセットする

  • ≪ opcache_is_script_cached
  • 出力制御 ≫
  • PHP Manual
  • OPcache 関数
  • opcode のキャッシュ内容をリセットする

opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — opcode のキャッシュ内容をリセットする

説明

opcache_reset(): bool

この関数は、キャッシュされた opcode 全てをリセットします。opcache_reset() 関数が呼び出されると、次回ヒットする全てのスクリプトが再び読み込まれ、パースされます。 この関数は、インメモリキャッシュ だけをリセットします。 ファイルキャッシュ はリセットしません。

パラメータ

この関数にはパラメータはありません。

戻り値

opcode のキャッシュがリセットさせた場合は true を返します。 opcode キャッシュが無効にされている場合は false を返します。 "restart_pending" や "restart_in_progress" の値が true の場合も false を返します (opcache_get_status() も参照ください)。

参考

  • opcache_invalidate() - キャッシュされたスクリプトを無効にする
  • opcache_get_status() - キャッシュについてのステータス情報を取得


出力バッファリング制御

  • はじめに
  • インストール/設定
    • 実行時設定
  • 定義済み定数
  • 出力バッファリング
  • システムバッファのフラッシュ
  • ユーザーレベルの出力バッファ
    • どの出力をバッファするのか？
    • 出力バッファをネストさせる
    • バッファサイズ
    • バッファに対して可能な操作
    • 出力ハンドラ
    • 出力ハンドラを扱う
    • 出力ハンドラに渡されるフラグ
    • 出力ハンドラの戻り値
  • 例
    • 基本的な使用法
    • 出力リライトの使用法
  • 出力制御 関数
    • 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_implicit_flush — 自動フラッシュをオンまたはオフにする
    • ob_list_handlers — 使用中の出力ハンドラの一覧を取得する
    • ob_start — 出力のバッファリングを有効にする
    • output_add_rewrite_var — URL リライタの値を追加する
    • output_reset_rewrite_vars — URL リライタの値をリセットする


はじめに

出力制御関数により、スクリプトから送信される出力を制御することが可 能になります。この機能は、複数の異なった場面、特にスクリプトがデー タ出力を開始した後にヘッダをブラウザに送信する必要がある場合に有用 です。出力制御関数は、header() または setcookie()を使用して送信されたヘッダには作用せ ず、echo のような関数とPHPコードのブロック間 のデータにのみ作用します。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • 出力制御
  • インストール/設定

インストール/設定

目次

  • 実行時設定


実行時設定

php.ini の設定により動作が変化します。

出力制御設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
output_buffering | "0" | INI_PERDIR |
output_handler | null | INI_PERDIR |
implicit_flush | "0" | INI_ALL |
url_rewriter.tags | "form=" | INI_ALL | PHP 7.1.0 以降では、このINI設定は output_add_rewrite_var() でのみ影響します。 PHP 7.1.0 より前のバージョンでは、このINI設定は 透過的セッションIDのサポートを有効にしていました。 (session.trans_sid_tags も参照ください)
url_rewriter.hosts | $_SERVER['HTTP_HOST'] | INI_ALL | PHP 7.1.0 以降で使用可能です。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

output_buffering bool/int

このディレクティブを "On" と設定することにより、 全てのファイルに関して出力バッファリングを有効にすることができます。 バッファの大きさを制限したい場合、 このディレクティブに "On" を設定する代わりに、許可される最大値をバイト数単位で設定できます。 たとえば output_buffering=4096 のように設定できます。 PHP-CLI ではこのディレクティブが常に Off となります。

output_handler string

スクリプトの出力を、関数にリダイレクトできます。 たとえば output_handler に mb_output_handler() を指定した場合、 文字エンコーディングは透過的に指定したエンコーディングに 変換されます。出力ハンドラを指定することにより自動的に出力 バッファリングが on になります。

注意:

mb_output_handler() と ob_iconv_handler() は一緒に使えません。 また、ob_gzhandler() と zlib.output_compression は、以下の値のいずれかと一緒に使えません: mb_output_handler(), ob_gzhandler(), zlib.output_compression, 'URL-Rewriter' ハンドラ (session.use_trans_sid と output_add_rewrite_var() も参照ください)

注意:

このディレクティブには、ビルトイン関数のみが使用可能です。ユーザー定義の 関数については、ob_start() を使用してください。

implicit_flush bool

デフォルトは false です。これを true に変更すると、PHP が 各出力ブロックの後で自動的に出力レイヤをフラッシュするよう 指定します。これは、 (print や echo のような) 出力を生成するあらゆる関数をコールするたびに/コールし、 HTML ブロックの後で flush() 関数をコールすることと等価です。

Web 環境の中で PHP を使用している時に このオプションを on に変更すると、著しい性能低下が生じるため、 通常はデバッグ目的のみにすることが推奨されます。CLI SAPI のもとで実行される時、この値はデフォルトで true になっています。

ob_implicit_flush() も参照ください。

url_rewriter.tags string
url_rewriter.tags は、 output_add_rewrite_var() の値でどのURLのHTMLタグや属性を書き換えるかを指定します。 デフォルトは "form=" です。 "form=" や form の任意の属性を追加すると、 input 要素の hidden 要素が output_add_rewrite_var() に渡された name/value のペアごとに form要素に追加されます。
警告

url_rewriter.tags に一度以上同じタグを追加すると、 URL書き換えプロセスの間に最初に出てきたものだけが使われます。

注意: PHP 7.1.0 より前のバージョンでは、url_rewriter.tags は session.trans_sid_tags のを指定するために使われていました。 PHP 7.1.0 以降は、fieldset は特別なタグとはみなされなくなります。

url_rewriter.hosts string
url_rewriter.hosts は、 output_add_rewrite_var() に含めるリライト対象のホストを指定します。 デフォルトは $_SERVER['HTTP_HOST'] です。 複数のホストを指定する場合は、コンマ区切りのリストとして指定します。 但し、スペースを入れてはいけません。 たとえば、"php.net,wiki.php.net,bugs.php.net" のように指定します。


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

出力ハンドラに渡されるステータスフラグ

以下のフラグは、ob_start() によってセットされる出力ハンドラの2番目の引数(phase) に、ビットマスクの一部として渡されます。

PHP_OUTPUT_HANDLER_START (int)

出力バッファリングが始まったことを表します。

PHP_OUTPUT_HANDLER_WRITE (int)

出力バッファがフラッシュされ、データが出力されたことを表します。

PHP_OUTPUT_HANDLER_FLUSH (int)

バッファがフラッシュされたことを表します。

PHP_OUTPUT_HANDLER_CLEAN (int)

出力バッファが消去されたことを表します。

PHP_OUTPUT_HANDLER_FINAL (int)

出力バッファリングの最終操作であることを表します。

PHP_OUTPUT_HANDLER_CONT (int)

バッファはフラッシュされたけれども、出力バッファリングはまだ続くことを表します。

これは PHP_OUTPUT_HANDLER_WRITE のエイリアスです。

PHP_OUTPUT_HANDLER_END (int)

出力バッファリングが終わったことを表します。

これは PHP_OUTPUT_HANDLER_FINAL のエイリアスです。

出力バッファの制御フラグ

以下のフラグは、ob_start() によってセットされる出力ハンドラの3番目の引数(flags) に、ビットマスクの一部として渡されます。

PHP_OUTPUT_HANDLER_CLEANABLE (int)

ob_start() が作る出力バッファを、
ob_clean() がクリーンできるかどうかを設定します。
このフラグは、ob_end_clean() や
ob_get_clean() の振る舞いは制御しません。

PHP_OUTPUT_HANDLER_FLUSHABLE (int)

ob_start() が作る出力バッファを、
ob_flush() がフラッシュできるかどうかを設定します。
このフラグは、ob_end_flush() や
ob_get_flush() の振る舞いは制御しません。

PHP_OUTPUT_HANDLER_REMOVABLE (int)

ob_start() が作る出力バッファを、 スクリプトの終了前や ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() をコールしたときに削除できるかを設定します。

PHP_OUTPUT_HANDLER_STDFLAGS (int)

出力バッファのフラグのデフォルト設定。 PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_REMOVABLE と同等です。

出力ハンドラのステータスフラグ

以下のフラグは、 ob_get_status() が返す ビットマスク flags の一部です:

PHP_OUTPUT_HANDLER_STARTED (int)

出力ハンドラがコールされたことを示します。

PHP_OUTPUT_HANDLER_DISABLED (int)

出力ハンドラが無効になっていることを示します。 このフラグは、出力ハンドラが false を返したときや バッファの処理が失敗したとき、 または出力ハンドラをコールする前に設定されたときに設定されます。

PHP_OUTPUT_HANDLER_PROCESSED (int)

出力ハンドラがバッファの処理に成功したことを示します。 PHP 8.4.0 以降で利用可能です。


出力バッファリング

出力バッファリングとは、ブラウザ(Web の場合) や シェル(コマンドラインの場合) に出力をフラッシュ(送信して破棄)する前に、 バッファリング(一時的に保存) することです。 出力バッファリングが有効な間は、スクリプトから出力は送信されず、 代わりに内部バッファに保存されます。

PHPに影響するバッファリング

PHP は、出力をフラッシュする際に、 基礎となる ソフトウェア/ハードウェア のインフラストラクチャに依存します。 コマンドライン上のコンソールで実装されているバッファリング (例: 行バッファリング(訳注: 改行されるごとにフラッシュされる)) や Web のコンテキストにおける ウェブサーバー やブラウザが実装するバッファリング (例: フルバッファリング(訳注:バッファが一杯になったらフラッシュされる)) は、 エンドユーザーに出力を表示するタイミングに影響を与えます。 サーバの設定を微調整したり、 さまざまなレイヤーのバッファサイズを揃えたりすることで、これらの影響のいくつかを取り除くことができます。

PHPにおける出力バッファリングの制御

PHP は、ユーザレベルの出力バッファを提供しており、 バッファリングを開始したり、管理したり、無効にしたりする関数を提供しています。 (これらの関数のほとんどは、ob_* 関数にあります) そして、既存のシステムバッファをフラッシュするための関数をふたつ (flush()と ob_implicit_flush()) 提供しています。 これらの機能の中には、php.ini を適切に設定することで、 設定や構成できるものがあります。

バッファリングの用途

出力バッファリングは一般的に、 バッファリングされた出力を修正したり、検査したり、 リクエストの中で出力を複数回使う場合に有用です。 あるいは、出力をフラッシュするタイミングを制御したい場合にも有用です。 具体的な使用例として、以下が挙げられます:

  • 計算/時間のかかるスクリプトの実行結果をキャッシュする場合。 たとえば、静的なHTMLページを生成する場合などです。
  • 生成された出力を表示したり、ファイルに保存したり、 電子メールで送るなどの用途に再利用することができます。
  • HTMLページの head を body とは別にフラッシュすることで、 ブラウザは時間のかかる可能性のある処理 (例: データベース/ファイルへのアクセス、外部ネットワーク接続) をスクリプトが実行している間に、外部リソースを読み込むことができます。 これは、HTTP ステータスコード がヘッダ送信後に変更できない場合にのみ有効です。
  • 出力を生成する関数(例: phpinfo())から情報を抽出する場合。
  • 出力を部分的に修正したり、一部を採用したり (例えば、データの抽出、単語/フレーズの置換、 足りないHTMLタグの追加)、 特定の条件下(例えばエラー)では完全に破棄することで、 サードパーティのコードの出力を制御します。
  • 特定のウェブサーバーでは利用できない機能をサポートする場合。 (出力の圧縮やエンコードなど)


システムバッファのフラッシュ

PHP は、システムバッファをフラッシュ(内容を送信して破棄) する方法をふたつ提供します: flush() と、 ob_implicit_flush() や php.ini 設定 implicit_flush 経由で暗黙のフラッシュを有効にする方法です。

出力をフラッシュする動作

暗黙のフラッシュを無効にすると、 PHP は flush() をコールしたときか、 スクリプトが終了したときにだけ出力をフラッシュします。

暗黙のフラッシュを有効にすると、 PHP は出力を生成するコードブロックが終了するたびに、 フラッシュを実行しようとします。 このコンテクストにおける出力は、以下に示す長さが 0 より大きなデータです:

  • <?php ?> タグの外側
  • ユーザが提供した変数や文字列を出力することを明確な目的とした言語構造や関数による出力。 これにあてはまる言語構造や関数は、 echo, print, printf(), var_dump(), var_export(), vprintf() です。
  • 実行中のスクリプトや PHP に関するデータ/情報を収集し、 出力することを目的とした関数による出力。 これにあてはまる関数は、 debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info() です。
  • 捕捉されなかった例外や、処理されなかったエラーが発生したときに PHP が行う出力。 (出力されるかどうかは、 display_errors と error_reporting の設定次第です)
  • php://output に書き込まれたあらゆるデータ

注意: 空文字列やヘッダの送信は、出力とはみなされないので、 フラッシュは発生しません。

警告

暗黙のフラッシュが有効な場合、制御文字 (例: "\n", "\r", "\0") もフラッシュを発生させます。

制限事項

この機能は、ユーザレベルの出力バッファをフラッシュできません。 ユーザレベルの出力バッファを一緒にフラッシュするには、 PHP が何らかの出力を生成するためにシステムバッファをフラッシュする前に、 ユーザレベルの出力バッファをフラッシュしなければなりません。

警告

flush() をコールしたり、 暗黙のフラッシュを有効にすると、 Web のコンテキスト中でヘッダを設定して送信するユーザレベルの出力バッファのハンドラ(例: ob_gzhandler()) を邪魔する可能性があります。 これは、これらのハンドラがヘッダを送信する前に、フラッシュの動作がヘッダを送信することが原因です。

基礎となる ソフトウェア/ハードウェアによって実装されたバッファリングは PHP によって上書きできません。 よって、PHP のバッファ制御関数を使う際にはこの点を考慮する必要があります。 ウェブサーバー/ブラウザ/コンソールのバッファリング設定をチェックして使うことで、 起こりうる問題を軽減することができます。 Web のコンテキストで作業する場合、ウェブサーバーのバッファリング設定や スクリプトのバッファリングを一緒に調整することができます。 PHP スクリプトのバッファリングを調整することで、 さまざまなブラウザのバッファリング戦略を回避できます。 行バッファリングを実装しているコンソールでは、 改行文字を適切な場所に挿入してから出力をフラッシュします。

SAPI ごとのフラッシュの動作の違い

フラッシュの機能は、SAPI ごとに少し違ったやり方で実装されていますが、 以下の2つのカテゴリに分類できます:

  • Web のコンテキストで使われる SAPI は、 ヘッダをまずフラッシュし、その後に出力を続けます。 Apache2Handler, CGI, FastCGI, FPM がこうした SAPI に該当します。
  • 出力をフラッシュするだけのその他の SAPI。 たとえば CLI と embed が該当します。


ユーザーレベルの出力バッファ

目次

  • どの出力をバッファするのか？
  • 出力バッファをネストさせる
  • バッファサイズ
  • バッファに対して可能な操作
  • 出力ハンドラ
  • 出力ハンドラを扱う
  • 出力ハンドラに渡されるフラグ
  • 出力ハンドラの戻り値

ユーザレベルの出力バッファは、 PHP コードから開始、操作、終了することができます。 バッファは、出力バッファと関連する出力ハンドラ関数を含みます。

出力バッファをオンにする

出力バッファリングは、php.ini 設定 output_buffering と output_handler を設定するか、ob_start() 関数を使うことでオンにできます。 これらは両方、出力バッファを生成できますが、 ob_start() の方がより柔軟です。 なぜなら、出力ハンドラをユーザー定義関数として受け入れますし、 (フラッシュ、クリーン、削除 のような) バッファに対する操作もできるからです。 ob_start() で開始したバッファは、 それをコールした行からアクティブになりますが、 output_buffering を使って開始したバッファは、スクリプトの最初の行から、出力をバッファします。

PHP は組み込みの "URL-Rewriter" 出力ハンドラをバンドルしています。 このハンドラは、自分の出力バッファを開始します。 同時に実行できるのはふたつです(1つはユーザレベルのURL書き換えと、 透過的なセッションIDサポートのためのもの) 。 これらのバッファは、output_add_rewrite_var() 関数をコールするか、php.ini 設定 session.use_trans_sid を有効にすることで開始できます。

バンドルされている zlib 拡張モジュールは、 独自の出力バッファを持っています。 この出力バッファは、php.ini 設定 zlib.output_compression を使うことで有効にできます。

注意: 一度に二つまでしか実行できないという意味で、 "URL-Rewriter" は特別です。 しかし、すべてのユーザレベルの出力バッファは、 カスタムの出力ハンドラ関数を指定して ob_start() をコールすることで開始した既存のバッファと同じものを使います。 そのため、すべての機能はユーザランドのコードでエミュレートすることができます。

バッファの内容をフラッシュ/アクセス/削除する

フラッシュは、アクティブなバッファの内容を送信し、破棄します。 出力バッファは、出力のサイズがバッファのサイズを超えたときか、 スクリプトが終了するか、 ob_flush(), ob_end_flush(), ob_get_flush() のいずれかがコールされたときにフラッシュされます。

警告

ob_end_flush() や ob_get_flush() をコールすると、アクティブなバッファがオフになります。

警告

バッファをフラッシュすると、 出力バッファの戻り値がフラッシュされますが、 この値はバッファの内容と異なる場合があります。 例えば、ob_gzhandler() を使うと、出力が圧縮され、圧縮された出力がフラッシュされます。

アクティブなバッファの内容は ob_get_contents(), ob_get_clean(), ob_get_flush() をコールすると取得できます。

バッファの中身の長さだけが必要な場合、 ob_get_length() や ob_get_status() を使えばバッファの中身の長さをバイト単位で取得できます。

警告

ob_get_clean() や ob_get_flush() をコールすると、アクティブなバッファの中身を返した後、 そのバッファをオフにします。

アクティブなバッファの中身は、 ob_clean(), ob_end_clean(), ob_get_clean() を使って削除できます。

警告

ob_end_clean() や ob_get_clean() を使うと、アクティブなバッファがオフになります。

出力バッファをオフにする

ob_end_clean(), ob_end_flush(), ob_get_flush(), ob_get_clean() をコールすると、出力バッファをオフにできます。

警告

PHP_OUTPUT_HANDLER_REMOVABLE を指定せずに起動した出力バッファはオフにできず、 E_NOTICE が発生します。

スクリプトの終了時、または exit() がコールされるまでに閉じられていないすべての出力バッファは、 PHP のシャットダウン処理によってフラッシュされ、オフになります。 バッファは、起動した順序と逆の順序でフラッシュされ、オフになります。 最後にバッファリングが開始されたものが最初になり、 最初にバッファリングが開始されたものが最後にフラッシュされ、オフになります。

警告

バッファの内容をフラッシュしたくない場合は、 カスタムの出力ハンドラを使い、シャットダウン中のフラッシュを防ぐべきです。

出力ハンドラでスローされる例外

捕捉されない例外が出力ハンドラでスローされた場合、 プログラムは終了し、"Uncaught Exception" エラーメッセージがフラッシュされた後に、 シャットダウン処理によってハンドラが呼び出されます。

ob_flush(), ob_end_flush(), ob_get_flush() が呼び出したハンドラが、捕捉されない例外をスローした場合、 エラーメッセージがフラッシュされる前にバッファの内容がフラッシュされます。

シャットダウン処理中に出力ハンドラが捕捉されない例外をスローした場合、 ハンドラは終了し、バッファの内容もエラーメッセージもフラッシュされません。

注意: ハンドラが例外をスローした場合、 PHP_OUTPUT_HANDLER_DISABLED フラグが設定されます。

出力ハンドラで発生したエラー

出力ハンドラで致命的でないエラーが発生した場合、 プログラムの実行は継続されます。

ob_flush(), ob_end_flush(), ob_get_flush() が呼び出したハンドラで致命的でないエラーが発生した場合、 ハンドラの戻り値に応じて、バッファは一定のデータをフラッシュします。 ハンドラが false を返す場合、 バッファの中身とエラーメッセージがフラッシュされます。 それ以外の値をハンドラが返す場合、 ハンドラの戻り値はフラッシュされますが、エラーメッセージはフラッシュされません。

注意: ハンドラが false を返す場合、 PHP_OUTPUT_HANDLER_DISABLED フラグが設定されます。

出力ハンドラ中で致命的なエラーが発生した場合、 プログラムは終了し、 エラーメッセージがフラッシュされた後に、 シャットダウン処理によってハンドラが呼び出されます。

ob_flush(), ob_end_flush(), ob_get_flush() が呼び出したハンドラで、致命的なエラーが発生した場合、 エラーメッセージがフラッシュされる前にバッファの内容がフラッシュされます。

シャットダウン処理中に出力ハンドラで致命的なエラーが発生した場合、 プログラムは終了し、バッファの内容もエラーメッセージもフラッシュされません。

出力ハンドラで行われた出力

特定の状況下では、 ハンドラ内で生成された出力はバッファの内容と共にフラッシュされます。 この出力はバッファに追加されず、 ob_get_flush() が返す文字列の一部にもなりません。

フラッシュの操作中 (ob_flush(), ob_end_flush(), ob_get_flush() のコール中、またはシャットダウン処理中)に、 ハンドラが false を返した場合、 バッファの内容がフラッシュされ、その後に出力が行われます。 シャットダウン処理中にハンドラが呼び出されなかった場合、 ハンドラが例外をスローするか、exit() が呼び出されると、 同じ動作になります。

注意: ハンドラが false を返した場合、 PHP_OUTPUT_HANDLER_DISABLED が設定されます。

出力ハンドラのステータスフラグ

バッファが持つ flags ビットマスクの 出力ハンドラのステータスフラグ は、 出力ハンドラが起動されるたびに設定され、 ob_get_status() が返す flags の一部になります。 ハンドラが正常に実行され、false を返さなかった場合、 PHP_OUTPUT_HANDLER_STARTED と PHP_OUTPUT_HANDLER_PROCESSED が設定されます。 ハンドラが false を返すか、実行中に例外がスローされた場合は、 PHP_OUTPUT_HANDLER_STARTED と PHP_OUTPUT_HANDLER_DISABLED が設定されます。

注意: ハンドラの PHP_OUTPUT_HANDLER_DISABLED が設定されている場合、 ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() 経由でハンドラは呼び出されません。 PHP のシャットダウン処理中でも同様です。 ob_clean() や ob_flush() をコールする際には、このフラグはなんの意味もありません。


どの出力をバッファするのか？

PHP のユーザレベル出力バッファは、 起動した後から、バッファリングをオフにするか、 スクリプトが終わるまでのすべての出力をバッファリングします。 PHP のユーザーレベル出力バッファにおける出力とは、 PHP が表示したりブラウザに送り返したりするすべてのものを指します。 実用的な用語で説明すると、出力とは以下に示す、 長さがゼロでないデータのことです:

  • <?php ?> タグの外側
  • ユーザが提供した変数や文字列を出力することを明確な目的とした言語構造や関数による出力。 これにあてはまる言語構造や関数は、 echo, print, printf(), var_dump(), var_export(), vprintf() です。
  • 実行中のスクリプトや PHP に関するデータ/情報を収集し、 出力することを目的とした関数による出力。 これにあてはまる関数は、 debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info() です。
  • 捕捉されなかった例外や、処理されなかったエラーが発生したときに PHP が行う出力。 (出力されるかどうかは、 display_errors と error_reporting の設定次第です)
  • php://output に書き込まれたあらゆるデータ

注意: stdout に直接書き込まれたり、 同様の機能を持つ SAPI 関数に渡されたデータは、 ユーザレベルの出力バッファには取り込まれません。 これに該当するのは、 fwrite() を使って stdout にデータを書き込む場合や、header() や setcookie() を使ってヘッダを送信する場合です。


出力バッファをネストさせる

新しいバッファが開始されたときに、既にアクティブな出力バッファがある場合、 新しいバッファは、以前にアクティブだったバッファの内部にネストされます。 ネストされたバッファは、ネストされているかどうかに関係なく同じ動作をしますが、 ネストされたバッファによってバッファリングされた出力は、 以前にアクティブだった外側のバッファにはバッファリングされません。 ネストされたバッファからフラッシュされた出力のみが、 外側のバッファによってバッファリングされます。

ほとんどの ob_* 関数は、アクティブな出力バッファ（最後に開始されたもの）に対してのみ動作するため、 アクティブなバッファのみをフラッシュ、クリーン、オフにすることができます。 それ以外のバッファに対して動作する関数は、 使用中のすべての出力ハンドラのリストを返す ob_list_handlers() や、 アクティブなバッファや使用中のすべてのバッファに関する情報を返すことができる ob_get_status() があります。

ob_get_level() や ob_get_status() をコールすると、アクティブな出力バッファのネストレベルを返します。

警告

ob_get_level() と ob_get_status() が指す、同じレベルの値は1つずれています。 ob_get_level() では最初のレベルは 1 であるのに対し、 ob_get_status() の最初のレベルは 0 になります。


バッファサイズ

バッファサイズは整数で表され、 バッファがフラッシュせずに格納できるバイト数を表します。 バッファ内の出力サイズがバッファサイズを超えると、 バッファの内容が出力ハンドラに送られ、 その戻り値がフラッシュされ、バッファがクリアされます。

"URL-Rewriter" を除いて、 出力バッファのサイズはバッファの開始時に設定することができます。 0 に設定すると、 出力バッファのサイズは PHP が使用可能なメモリの量に制限されます。 1 に設定すると、 0 より大きい長さの出力を生成するコードブロックの後にバッファがフラッシュされます。

出力バッファのサイズは、 ob_get_status() をコールすることで取得できます。

ob_start() で開始された出力バッファのバッファサイズは、 2番目のパラメータ chunk_size に渡された整数値に設定されます。省略された場合、 0 が設定されます。

ini 設定 output_buffering が "On" に設定されている場合、 開始された出力バッファのバッファサイズは 0 に設定されます。 バッファサイズより大きな整数を設定した場合、バッファサイズはその値になります。

"URL-Rewriter" のバッファサイズは 0 に設定されているため、 PHP が使用可能なメモリの量に制限されます。

zlib の出力バッファのサイズは、 php.ini の zlib.output_compression で設定します。 "On" に設定すると、バッファサイズは "16K"/16384 になります。 バッファサイズより大きな整数を設定した場合、 バッファサイズはそのバイト数になります。


バッファに対して可能な操作

バッファに対して可能な操作は、 出力バッファの制御フラグ のいずれかを ob_start() の3番めの flags パラメータに渡すことで制御できます。 省略した場合、すべての操作がデフォルトで許可されます。 0 を指定すると、 バッファのフラッシュ、クリーン、削除はできませんが、 その内容を取得することはできます。

PHP_OUTPUT_HANDLER_CLEANABLE を指定すると、 ob_clean() によってバッファの内容を削除できるようになります。

警告

PHP_OUTPUT_HANDLER_CLEANABLE フラグ を指定していなくても、 ob_end_clean() や ob_get_clean() がバッファの内容を削除できなくなるわけではありません。

PHP_OUTPUT_HANDLER_FLUSHABLE を指定すると、 ob_flush() を使ってバッファの内容をフラッシュできるようになります。

警告

PHP_OUTPUT_HANDLER_FLUSHABLE フラグ を指定していなくても、 ob_end_flush() や ob_get_flush() がバッファの内容をフラッシュできなくなるわけではありません。

PHP_OUTPUT_HANDLER_REMOVABLE を指定すると、 ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() を使ってバッファをオフにすることができるようになります。

PHP_OUTPUT_HANDLER_STDFLAGS は、既に述べた3つのフラグの組み合わせで、 指定するとバッファに対する3つの操作を実行できます。


出力ハンドラ

出力ハンドラは、出力バッファに関連付けられた callable です。
ob_clean(),
ob_flush(), ob_end_flush(),
ob_get_flush(), ob_end_clean(),
ob_get_clean() をコールすると呼び出されます。
また、PHP のシャットダウン処理中にも呼び出されます。

注意: シャットダウン処理は、ハンドラの戻り値をフラッシュします。

出力バッファを開始するときに、ハンドラを省略したり null を指定した場合、 内部的な "default output handler" が使われます。このハンドラは、呼び出された際にバッファの内容を変更せずに返します。 出力ハンドラは、バッファの内容を変更 かつ/または 副作用(例:ヘッダの送信) をもたせるために使うことができます。

PHP には、内部的な出力ハンドラをふたつ持っています: "default output handler" と "URL-Rewriter" (これは独自の出力バッファに統合されており、2つまでしか起動できません) がそうです。

PHP 本体にバンドルされている拡張モジュールには、 追加の出力ハンドラが4つあります: mb_output_handler(), ob_gzhandler(), ob_iconv_handler(), ob_tidyhandler() です。


出力ハンドラを扱う

出力ハンドラが呼び出されると、 バッファの内容と、出力バッファリングの状態を示すビットマスクが渡されます。

handler ( string $buffer , int $phase = ?): string
buffer
出力バッファの内容
phase
PHP_OUTPUT_HANDLER_* 定数 のビットマスク

警告

出力ハンドラの内部で以下の関数をコールすると、致命的なエラーが発生します:
ob_clean(), ob_end_clean(),
ob_end_flush(), ob_flush(),
ob_get_clean(), ob_get_flush(),
ob_start()

注意: ハンドラの PHP_OUTPUT_HANDLER_DISABLED が設定されている場合、 ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() をコールしてもハンドラは呼び出されません。 PHP のシャットダウン処理中でも同様です。 ob_clean() や ob_flush() をコールしてもこのフラグは何の効果もありません。

注意: 一部のウェブサーバー、例えば Apache やビルトイン・ウェブサーバーでは、 作業ディレクトリがシャットダウン中に変更される場合があります。


出力ハンドラに渡されるフラグ

出力ハンドラの2つめの phase パラメータに渡されるビットマスクは、 ハンドラの起動に関する情報を提供します。

注意: ビットマスクは複数のフラグを含むことができるので、 フラグがセットされているかどうかをチェックするには、 ビット演算子 & を使う必要があります。

警告

PHP_OUTPUT_HANDLER_WRITE と、そのエイリアス PHP_OUTPUT_HANDLER_CONT の値は 0 です。 よって、これらの値が設定されているかを調べられるのは 比較演算子 (== or ===) だけです。

ハンドラのライフサイクルの特定のフェーズで、以下のフラグが設定されます: PHP_OUTPUT_HANDLER_START は、ハンドラが初めて起動されたときに設定されます。 PHP_OUTPUT_HANDLER_FINAL やそのエイリアス PHP_OUTPUT_HANDLER_END はハンドラが最後に起動されるとき、 つまりハンドラがオフになるときに設定されます。 PHP のシャットダウン処理によってバッファがオフにする際にも設定されます。

ハンドラの特定の呼び出しに応じて、以下のフラグが設定されます: PHP_OUTPUT_HANDLER_FLUSH は、 ob_flush() をコールしてハンドラが呼び出された際に設定されます。 PHP_OUTPUT_HANDLER_WRITE やそのエイリアス PHP_OUTPUT_HANDLER_CONT は、バッファの内容の長さがバッファのサイズ以上かつ、 バッファが自動的にフラッシュされている間にハンドラを起動したときに設定されます。 PHP_OUTPUT_HANDLER_FLUSH は、 ob_clean(), ob_end_clean() や ob_get_clean() をコールしてハンドラが呼び出された場合に設定されます。 ob_end_clean() や ob_get_clean() がコールされた場合は、PHP_OUTPUT_HANDLER_FINAL も同時に設定されます。

注意: ob_end_flush() や ob_get_flush() がコールされると、PHP_OUTPUT_HANDLER_FINAL が設定されますが、PHP_OUTPUT_HANDLER_FLUSH は設定されません。


出力ハンドラの戻り値

出力ハンドラの戻り値は、 以下に示す PHP の標準的な型のセマンティクスに従って文字列に自動変換されますが、 ふたつだけ例外があります: array と bool です。

配列は文字列 "Array" に変換されますが、警告 Array to string conversion は発生しません。

ハンドラが false を返した場合、 バッファの内容が返されます。 ハンドラが true を返した場合、 空文字列が返されます。

注意: ハンドラが false を返したり、ハンドラで例外が発生した場合、 　PHP_OUTPUT_HANDLER_DISABLED フラグが設定されます。


  • ≪ 出力ハンドラの戻り値
  • 基本的な使用法 ≫
  • PHP Manual
  • 出力制御
  • 例

例

目次

  • 基本的な使用法
  • 出力リライトの使用法


基本的な使用法

例1 出力制御の例

<?php

ob_start();
echo "Hello\n";

setcookie("cookiename", "cookiedata");

ob_end_flush();

?>

上記の例では、echo からの出力は、 ob_end_flush() がコールされるまで出力バッファに 保存されます。この際、 setcookie()をコールするとエラーを発生することな くクッキーが保存されます (通常、データの送信後はブラウザにヘッダ を送信することはできません)。


出力リライトの使用法

PHP 7.1.0 以降は、output_add_rewrite_var() と output_reset_rewrite_vars() は専用の出力バッファを用いるようになります。透過的セッションID の出力バッファは用いません。

例1 出力リライトの例

<?php
// このコードは PHP 7.1.0, 7.0.10, 5.6.25 以降で動作します

// HTTP_HOST はデフォルトのターゲットホストです。適切に書き換えてください
$_SERVER['HTTP_HOST'] = 'php.net';

// 出力リライトはフォームだけを書き換えます。a=href を追加します。
// タグは tag_name=url_attr 形式で指定します。たとえば img=src,iframe=src のようになります。
// 各設定の間にスペースを含めることはできません。
// form タグは特別なタグで、hidden を追加します。
ini_set('url_rewriter.tags','a=href,form=');
var_dump(ini_get('url_rewriter.tags'));

// これが URL と form に追加されます
output_add_rewrite_var('test', 'value');
?>
<a href="//php.net/index.php?bug=1234">bug1234</a>
<form action="https://php.net/?bug=1234&edit=1" method="post">
<input type="text" name="title" />
</form>

上の例の出力は以下となります。

<a href="//php.net/?bug=1234&test=value">bug1234</a>
<form action="https://php.net/?bug=1234&edit=1" method="post"><input type="hidden" name="test" value="value" />
 <input type="text" name="title" />
</form>

PHP 7.1.0 以降、出力リライトにはそれ専用の INI 項目が用意されるようになりました。 url_rewriter.tags と url_rewriter.hosts です。


出力制御 関数

参考

header()およびsetcookie() も参照ください。

目次

  • 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_implicit_flush — 自動フラッシュをオンまたはオフにする
  • ob_list_handlers — 使用中の出力ハンドラの一覧を取得する
  • ob_start — 出力のバッファリングを有効にする
  • output_add_rewrite_var — URL リライタの値を追加する
  • output_reset_rewrite_vars — URL リライタの値をリセットする


システム出力バッファをフラッシュする

  • ≪ 出力制御 関数
  • ob_clean ≫
  • PHP Manual
  • 出力制御 関数
  • システム出力バッファをフラッシュする

flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — システム出力バッファをフラッシュする

説明

flush(): void

PHP および PHP が使っている (CGI, Web サーバーなどの) バックエンドのシステム書き込みバッファをフラッシュします。 コマンドライン環境では、flush() はバッファの中身だけをフラッシュしようとします。 一方で web のコンテキストではヘッダとバッファの内容をフラッシュします。

注意: flush() はウェブサーバーのバッファリング手法を上書きすることはできません。 また、クライアント側のブラウザでのバッファリングにはなんの影響も及ぼしません。

注意: この関数は、 ob_start() や output_add_rewrite_var() によって開始されたユーザーレベルの出力ハンドラには、何ら影響しません。

警告

flush() は、 ハンドラがヘッダを送信する前にヘッダを送信することで、 web のコンテキストでヘッダを設定したり送信したりするハンドラ (例:ob_gzhandler()) を中断させることができます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する
  • ob_clean() - アクティブな出力バッファの内容をクリア(消去)する
  • ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする
  • ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする


アクティブな出力バッファの内容をクリア(消去)する

  • ≪ flush
  • ob_end_clean ≫
  • PHP Manual
  • 出力制御 関数
  • アクティブな出力バッファの内容をクリア(消去)する

ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — アクティブな出力バッファの内容をクリア(消去)する

説明

ob_clean(): bool

この関数は、 (PHP_OUTPUT_HANDLER_CLEAN フラグを指定して) 出力ハンドラをコールし、その戻り値を破棄するとともに、 アクティブな出力バッファの内容をクリア(消去)します。

この関数は、ob_end_clean() や ob_get_clean() のようにアクティブな出力バッファを無効にするわけではありません。

PHP_OUTPUT_HANDLER_CLEANABLE を指定して アクティブな出力バッファを開始しないと、 ob_clean() は失敗します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

この関数が失敗すると、 E_NOTICE が発生します。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_get_clean() - アクティブな出力バッファの内容を取得し、そのバッファをオフにする
  • ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する


アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

  • ≪ ob_clean
  • ob_end_flush ≫
  • PHP Manual
  • 出力制御 関数
  • アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

説明

ob_end_clean(): bool

この関数は、 (PHP_OUTPUT_HANDLER_CLEAN と PHP_OUTPUT_HANDLER_FINAL フラグを指定して) 出力ハンドラをコールし、その戻り値を破棄するとともに、 アクティブな出力バッファの内容をクリア(消去)し、 かつそれをオフにします。

PHP_OUTPUT_HANDLER_REMOVABLE を指定して アクティブな出力バッファを開始しないと、 ob_clean() は失敗します。

ob_end_clean() は、PHP_OUTPUT_HANDLER_CLEANABLE を指定せずにアクティブな出力バッファを開始したとしても、 そのバッファの内容をクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

この関数は失敗すると E_NOTICE レベルのエラーを発行します。

例

以下は、アクティブな全ての出力バッファの内容を消去する簡単な方法の例です。

例1 ob_end_clean() の例

<?php
ob_start();
echo 'Text that won\'t get displayed.';
ob_end_clean();
?>

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_clean() - アクティブな出力バッファの内容をクリア(消去)する
  • ob_get_clean() - アクティブな出力バッファの内容を取得し、そのバッファをオフにする
  • ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする


アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする

  • ≪ ob_end_clean
  • ob_flush ≫
  • PHP Manual
  • 出力制御 関数
  • アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする

ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする

説明

ob_end_flush(): bool

この関数は、 (PHP_OUTPUT_HANDLER_FINAL フラグを指定して) 出力ハンドラをコールし、その戻り値をフラッシュ(送信)するとともに、 アクティブな出力バッファの内容をクリアし、 かつそれをオフにします。

PHP_OUTPUT_HANDLER_REMOVABLE を指定して アクティブな出力バッファを開始しないと、 ob_end_flush() は失敗します。

ob_end_flush() は、PHP_OUTPUT_HANDLER_FLUSHABLE を指定せずにアクティブな出力バッファを開始したとしても、 その出力ハンドラの戻り値をフラッシュ(送信)します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

この関数は失敗すると E_NOTICE が発生します。

例

例1 ob_end_flush() の例

以下は全ての出力バッファをフラッシュする簡単な方法の例です。

<?php
while (@ob_end_flush());
?>

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する
  • ob_get_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする
  • ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする


アクティブな出力ハンドラの戻り値をフラッシュ(送信)する

  • ≪ ob_end_flush
  • ob_get_clean ≫
  • PHP Manual
  • 出力制御 関数
  • アクティブな出力ハンドラの戻り値をフラッシュ(送信)する

ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — アクティブな出力ハンドラの戻り値をフラッシュ(送信)する

説明

ob_flush(): bool

この関数は、 (PHP_OUTPUT_HANDLER_FLUSH フラグを指定して) 出力ハンドラをコールし、その戻り値をフラッシュ(送信)するとともに、 アクティブな出力バッファの内容をクリアします。

この関数は、 ob_end_flush() や ob_get_flush() のように、アクティブな出力バッファをオフにしません。

PHP_OUTPUT_HANDLER_FLUSHABLE を指定して アクティブな出力バッファを開始しないと、 ob_flush() は失敗します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

この関数が失敗すると、 E_NOTICE が発生します。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする
  • ob_get_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする
  • ob_clean() - アクティブな出力バッファの内容をクリア(消去)する


アクティブな出力バッファの内容を取得し、そのバッファをオフにする

  • ≪ ob_flush
  • ob_get_contents ≫
  • PHP Manual
  • 出力制御 関数
  • アクティブな出力バッファの内容を取得し、そのバッファをオフにする

ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — アクティブな出力バッファの内容を取得し、そのバッファをオフにする

説明

ob_get_clean(): string|false

この関数は、 (PHP_OUTPUT_HANDLER_CLEAN と PHP_OUTPUT_HANDLER_FINAL フラグを指定して) 出力ハンドラをコールし、その戻り値を破棄するとともに、 アクティブな出力バッファの内容を返しつつ、 かつそれをオフにします。

PHP_OUTPUT_HANDLER_REMOVABLE を指定して アクティブな出力バッファを開始しないと、 ob_get_clean() は失敗します。

ob_get_clean() は、PHP_OUTPUT_HANDLER_CLEANABLE を指定せずにアクティブな出力バッファを開始したとしても、 そのバッファの内容をクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合、アクティブな出力バッファの内容を返します。 失敗した場合は、false を返します。

警告

アクティブな出力バッファがない場合、 　ob_get_clean() は false を返しますが E_NOTICE は発生しません。

エラー / 例外

この関数が失敗すると、 E_NOTICE が発生します。

例

例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_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_clean() - アクティブな出力バッファの内容をクリア(消去)する
  • ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_get_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする


出力用バッファの内容を返す

  • ≪ ob_get_clean
  • ob_get_flush ≫
  • PHP Manual
  • 出力制御 関数
  • 出力用バッファの内容を返す

ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — 出力用バッファの内容を返す

説明

ob_get_contents(): string|false

出力用バッファの内容を取得します。バッファの内容はクリアしません。

パラメータ

この関数にはパラメータはありません。

戻り値

出力用バッファの内容を返します。 出力のバッファリングがアクティブでない場合には 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_start() - 出力のバッファリングを有効にする
  • ob_get_length() - 出力バッファの長さを返す


アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする

  • ≪ ob_get_contents
  • ob_get_length ≫
  • PHP Manual
  • 出力制御 関数
  • アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする

ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする

説明

ob_get_flush(): string|false

この関数は、 (PHP_OUTPUT_HANDLER_FINAL フラグを指定して) 出力ハンドラをコールし、その戻り値をフラッシュ(送信)するとともに、 アクティブな出力バッファの内容を返しつつ、 それをオフにします。

PHP_OUTPUT_HANDLER_REMOVABLE を指定して アクティブな出力バッファを開始しないと、 ob_get_flush() は失敗します。

ob_get_flush() は、PHP_OUTPUT_HANDLER_FLUSHABLE を指定せずにアクティブな出力バッファを開始したとしても、 出力ハンドラの戻り値をフラッシュ(送信) します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合、アクティブな出力バッファの内容を返します。 失敗した場合、false を返します。

エラー / 例外

この関数が失敗すると、 E_NOTICE が発生します。

例

例1 ob_get_flush() の例

<?php
//output_buffering=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_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する
  • ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする
  • ob_get_clean() - アクティブな出力バッファの内容を取得し、そのバッファをオフにする


出力バッファの長さを返す

  • ≪ ob_get_flush
  • ob_get_level ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファの長さを返す

ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — 出力バッファの長さを返す

説明

ob_get_length(): int|false

この関数は、出力バッファの内容の長さをバイト単位で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

出力バッファの内容の長さをバイト単位で返します。 出力のバッファリングがアクティブでない場合には、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_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す


出力バッファリング機構のネストレベルを返す

  • ≪ ob_get_length
  • ob_get_status ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファリング機構のネストレベルを返す

ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — 出力バッファリング機構のネストレベルを返す

説明

ob_get_level(): int

出力バッファリングハンドラのネストレベルを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

出力バッファリングハンドラのネストレベルを返します。 バッファリングがアクティブでない場合はゼロを返します。

警告

ob_get_level() と ob_get_status() が返す同じレベルの値は、1だけ差があります。 ob_get_level() では最初のレベルは 1 ですが、ob_get_status() の最初のレベルは 0 です。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_status() - 出力バッファのステータスを取得する
  • ob_get_contents() - 出力用バッファの内容を返す


出力バッファのステータスを取得する

  • ≪ ob_get_level
  • ob_implicit_flush ≫
  • PHP Manual
  • 出力制御 関数
  • 出力バッファのステータスを取得する

ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — 出力バッファのステータスを取得する

説明

ob_get_status(bool $full_status = false): array

ob_get_status() は、トップレベルの出力バッファの ステータス情報を返します。full_status が true に設定されている場合は、すべてのアクティブな出力バッファの ステータス情報を返します。

パラメータ

full_status

true を指定すると、すべてのアクティブな出力バッファを返します。 false を指定した場合、あるいは省略した場合は、 トップレベルの出力バッファのみを返します。

戻り値

full_status が省略されるか、false の場合、 出力レベルがアクティブなステータス情報を持つ配列を返します。

full_status が true の場合、 アクティブな出力バッファの階層をひとつの要素とする配列を返します。 出力レベルは配列のトップレベルのキーとして使われ、 それぞれの配列の要素自体は、 単一のアクティブな出力レベルのステータス情報を持つ配列になります。

出力バッファが有効になっていない場合は、 空の配列が返されます。

ob_get_status() が返す配列の要素
Key | Value
name | アクティブな出力ハンドラの名前 (詳細は ob_list_handlers() の戻り値を参照下さい)
type | 0 (内部ハンドラ) あるいは 1 (ユーザー指定のハンドラ)
flags | ob_start() が設定したフラグのビットマスク。 出力ハンドラのタイプ(上記を参照) と、 バッファリング中のプロセス ( PHP_OUTPUT_HANDLER_* 定数)。 ハンドラのバッファの処理が成功し、false を返さなかった場合、 PHP_OUTPUT_HANDLER_STARTED と PHP_OUTPUT_HANDLER_PROCESSED が設定されます。 ハンドラのバッファの処理が失敗するか、false を返した場合、 PHP_OUTPUT_HANDLER_STARTED と PHP_OUTPUT_HANDLER_DISABLED が設定されます。
level | 出力階層レベル(ゼロから始まります)。 ob_get_level() が返す階層の値とは、 ひとつずれることに注意して下さい。 ob_get_status() が返す最初のレベルは 0 ですが、ob_get_level() は 1 になります。
chunk_size | ob_start() で設定したチャンクの大きさ。 output_buffering が有効で、整数の値が設定されている場合はその値
buffer_size | 出力バッファのサイズ(バイト単位)
buffer_used | 出力バッファ中のデータサイズ(バイト単位) (ob_get_length() が返す整数値と同じです)

例

例1 full_status が false の場合に返される配列

Array
(
    [name] => URL-Rewriter
    [type] => 0
    [flags] => 112
    [level] => 2
    [chunk_size] => 0
    [buffer_size] => 16384
    [buffer_used] => 1024
)

例2 full_status が true の場合に返される配列

Array
(
    [0] => Array
        (
            [name] => default output handler
            [type] => 0
            [flags] => 112
            [level] => 1
            [chunk_size] => 0
            [buffer_size] => 16384
            [buffer_used] => 2048
        )

    [1] => Array
        (
            [name] => URL-Rewriter
            [type] => 0
            [flags] => 112
            [level] => 2
            [chunk_size] => 0
            [buffer_size] => 16384
            [buffer_used] => 1024
        )

)

参考

  • ob_get_level() - 出力バッファリング機構のネストレベルを返す
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する
  • ob_get_length() - 出力バッファの長さを返す
  • ob_start() - 出力のバッファリングを有効にする


自動フラッシュをオンまたはオフにする

  • ≪ ob_get_status
  • ob_list_handlers ≫
  • PHP Manual
  • 出力制御 関数
  • 自動フラッシュをオンまたはオフにする

ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — 自動フラッシュをオンまたはオフにする

説明

ob_implicit_flush(bool $enable = true): void

ob_implicit_flush() は、 自動フラッシュをオンまたはオフに切替えます。 自動フラッシュにより、出力が行われるコードブロックが実行されるたびに フラッシュ操作が行われるようになります。このため、flush() を明示的にコールする必要はなくなります。

注意: 空文字列を出力したり、ヘッダを送信することは出力とはみなされないため、 フラッシュ操作は行われません。

注意: この関数は、 ob_start() や output_add_rewrite_var() によって開始されたユーザーレベルの出力ハンドラには、何ら影響しません。

パラメータ

enable

true で自動フラッシュをオンに、false でオフにします。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | enable は、bool 型の値を期待するようになりました。 これより前のバージョンでは、数値型が期待されていました。

参考

  • flush() - システム出力バッファをフラッシュする
  • ob_start() - 出力のバッファリングを有効にする
  • ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする


使用中の出力ハンドラの一覧を取得する

  • ≪ ob_implicit_flush
  • ob_start ≫
  • PHP Manual
  • 出力制御 関数
  • 使用中の出力ハンドラの一覧を取得する

ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — 使用中の出力ハンドラの一覧を取得する

説明

ob_list_handlers(): array

使用中の出力ハンドラの一覧を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

これは、使用中の出力ハンドラを（もし存在すれば）配列で返します。

もし output_buffering が 有効になっており、output_handler が未設定の場合や、コールバックが設定されていない場合、 あるいは ob_start() に null を渡した場合は、 "default output handler" を返します。 output_buffering を有効にし、output_handler を設定することは、 内部(組み込み)関数 を ob_start() に渡すことと同じです。

ob_start() に callable を渡した場合、callable の 完全修飾名 を返します。callable が __invoke() を実装したオブジェクトの場合、 オブジェクトの __invoke() メソッドの 完全修飾名 を返します。 callable が Closure の場合、 "Closure::__invoke" を返します。

例

例1 ob_list_handlers() の例

<?php
// using output_buffering=On, no output_handler set
var_dump(ob_list_handlers());
ob_end_flush();

// no callback or null
ob_start();
var_dump(ob_list_handlers());
ob_end_flush();

// anonymous function
ob_start(function($string) { return $string; });
var_dump(ob_list_handlers());
ob_end_flush();

// arrow function
ob_start(fn($string) => $string);
var_dump(ob_list_handlers());
ob_end_flush();

// first class callable
$firstClassCallable = userDefinedFunction(...);

ob_start([$firstClassCallable, '__invoke']);
var_dump(ob_list_handlers());
ob_end_flush();

// internal (built-in) function
ob_start('print_r');
var_dump(ob_list_handlers());
ob_end_flush();

// user-defined function
function userDefinedFunction($string, $flags) { return $string; };

ob_start('userDefinedFunction');
var_dump(ob_list_handlers());
ob_end_flush();

class MyClass {
public static function staticHandle($string) {
return $string;
}

public static function handle($string) {
return $string;
}

public function __invoke($string) {
return $string;
}
}

// class and static method
ob_start(['MyClass','staticHandle']);
var_dump(ob_list_handlers());
ob_end_flush();

// object and non-static method
ob_start([new MyClass,'handle']);
var_dump(ob_list_handlers());
ob_end_flush();

// invokable object
ob_start(new MyClass);
var_dump(ob_list_handlers());
ob_end_flush();
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(22) "default output handler"
}
array(1) {
  [0]=>
  string(22) "default output handler"
}
array(1) {
  [0]=>
  string(7) "print_r"
}
array(1) {
  [0]=>
  string(19) "userDefinedFunction"
}
array(1) {
  [0]=>
  string(17) "Closure::__invoke"
}
array(1) {
  [0]=>
  string(17) "Closure::__invoke"
}
array(1) {
  [0]=>
  string(17) "Closure::__invoke"
}
array(1) {
  [0]=>
  string(21) "MyClass::staticHandle"
}
array(1) {
  [0]=>
  string(15) "MyClass::handle"
}
array(1) {
  [0]=>
  string(17) "MyClass::__invoke"
}

参考

  • ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする
  • ob_get_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする
  • ob_start() - 出力のバッファリングを有効にする


出力のバッファリングを有効にする

  • ≪ ob_list_handlers
  • output_add_rewrite_var ≫
  • PHP Manual
  • 出力制御 関数
  • 出力のバッファリングを有効にする

ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — 出力のバッファリングを有効にする

説明

ob_start(?callable $callback = null, int $chunk_size = 0, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS): bool

この関数は出力のバッファリングをオンにします。 出力のバッファリングを有効にすると、 (ヘッダ以外の) スクリプトからの出力は実際には行われず、 代わりに内部バッファに保存されます。

この内部バッファの内容は、ob_get_contents() を用いて文字列変数にコピーされます。 内部バッファの内容を出力するには ob_end_flush() を使用します。 ob_end_clean() は、バッファの内容を出力せずに消去します。

警告

web サーバーによっては (例: Apache)、コールバック関数からコールされた際に、 スクリプトの実行ディレクトリを変更するものがあります。 コールバック関数の内部で chdir(dirname($_SERVER['SCRIPT_FILENAME'])) などと指定することで、これをもとに戻すことが可能です。

出力バッファはスタッカブルであり、このため、他の ob_start() がアクティブの間に ob_start() をコールすることが可能です。この場合、 ob_end_flush() を適切な回数コールするようにしてください。 複数の出力コールバック関数がアクティブの場合、 ネストした順番で逐次連続的に出力がフィルタ処理されます。

スクリプトが終了した際に、 出力バッファリングがまだアクティブな場合、 PHP はバッファリングされた内容を自動的に出力します。

パラメータ

callback

オプションの引数 callback 関数を指定することが可能です。この関数は、パラメータとして文字列をとり、 文字列を返します。このコールバック関数は、 出力バッファがフラッシュ (送信) あるいは消去 (ob_flush(), ob_clean() あるいは同等の関数で) された場合、 またはリクエストの最後にブラウザに出力をフラッシュする際にコールされます。 callback がコールされた際に、 この関数は出力バッファの内容をパラメータとして受け取ります。このコールバック関数は、 新規の出力バッファを実際に出力される結果として返す必要があり、 この結果はブラウザに送信されます。 callback がコール可能な関数ではない場合は false を返します。 コールバックのシグネチャは、次のとおりです。

handler(string $buffer, int $phase = ?): string
buffer
出力バッファの内容。
phase
PHP_OUTPUT_HANDLER_* 定数 のビットマスク

callback が false を返すと、元の入力がそのままブラウザに送信されます。

callback パラメータに null 値を渡すと、 これをバイパスすることができます。

ob_end_clean()、 ob_end_flush()、ob_clean()、 ob_flush() および ob_start() をコールバック関数の内部からコールすることはできません。 実際にコールした際の挙動は未定義です。バッファの内容を消去したい際には、 コールバック関数から "" (空文字列) を返してください。 同じく、print_r($expression, true) や highlight_file($filename, true) のような 出力バッファリング関数も、 コールバック関数の内部からコールすることはできません。

注意:

Web ページの圧縮をサポートする圧縮 gz エンコード されたデータの Web ブラウザへの送信を容易にするために ob_gzhandler() が存在します。 ob_gzhandler() は、ブラウザが受け入れる content encoding の型を調べ、それに基づいて出力を返します。

chunk_size

オプションのパラメータ chunk_size が渡された場合、 バッファの長さが chunk_size バイトを超えるたびに、 出力の後でバッファがフラッシュされます。 デフォルト値は 0 で、これは出力関数がコールされるのが 出力バッファが閉じたときだけであることを意味します。

flags

flags はビットマスクで、出力バッファ上でどんな操作ができるのかを制御します。 デフォルトでは、出力バッファのクリーン、フラッシュ、削除がすべてできるようになっています。 これは、 出力バッファの制御フラグ を経由して明示的に設定できます。 詳細は バッファに対して可能な操作 を参照ください。

各フラグが、次の表のように関数へのアクセスを制御します。

定数 関数
PHP_OUTPUT_HANDLER_CLEANABLE ob_clean()
PHP_OUTPUT_HANDLER_FLUSHABLE ob_end_flush() ob_flush()
PHP_OUTPUT_HANDLER_REMOVABLE ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush()

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例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>

例2 削除不可能な出力バッファを作る例

<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>

参考

  • 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 コールバック関数


URL リライタの値を追加する

  • ≪ ob_start
  • output_reset_rewrite_vars ≫
  • PHP Manual
  • 出力制御 関数
  • URL リライタの値を追加する

output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — URL リライタの値を追加する

説明

output_add_rewrite_var(string $name, string $value): bool

この関数は、'URL-Rewriter' 出力バッファハンドラをアクティブでない場合に開始します。 その上で、name と value パラメータを保存し、バッファがフラッシュされた際には URL とフォームをini設定に基づいて書き換えます。 後にこの関数をコールした場合は、ハンドラがオフになるまで name/value のペアをすべて保存します。

(ob_flush(), ob_end_flush(), ob_get_flush() がコールされたり、 スクリプトが終了する際) 出力バッファがフラッシュされると、 'URL-Rewriter' ハンドラが name/value のペアを HTML タグの属性にある URL のクエリパラメータに追加します。 そして url_rewriter.tags と url_rewriter.hosts 設定ディレクティブの値に基づいて hidden フィールドをの値をフォームに追加します。

'URL-Rewriter' のハンドラに追加された name/value ペアは、たとえ URL のクエリパラメータが重複したり、 同じ名前の属性をもつ要素が発生したとしても、 それぞれが URL やフォームに追加されます。

注意: 'URL-Rewriter' ハンドラがオフにされると、 再び値を保存することはできません。

パラメータ

name

変数名。

value

変数の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | PHP 7.1.0 以降では、専用の出力バッファを用いるようになりました。 url_rewriter.tags はただ関数の出力にだけ使われるようになり、 url_rewriter.hosts が追加されました。 PHP 7.1.0 より前のバージョンでは、 output_add_rewrite_var() で設定したリライト変数は、 透過的セッションID出力バッファと同じ出力バッファを共有していました。 (session.trans_sid_tags を参照ください)

例

例1 output_add_rewrite_var() の例

<?php
ini_set('url_rewriter.tags', 'a=href,form=');

output_add_rewrite_var('var', 'value');

// リンク
echo '<a href="file.php">link</a>
<a href="http://example.com">link2</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">link</a>
<a href="http://example.com">link2</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() - URL リライタの値をリセットする
  • ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する
  • url_rewriter.tags
  • url_rewriter.hosts


URL リライタの値をリセットする

  • ≪ output_add_rewrite_var
  • PHP Options/Info ≫
  • PHP Manual
  • 出力制御 関数
  • URL リライタの値をリセットする

output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — URL リライタの値をリセットする

説明

output_reset_rewrite_vars(): bool

この関数は、output_add_rewrite_var() 関数によって事前に設定されたリライト変数をすべて削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | PHP 7.1.0 より前のバージョンでは、output_add_rewrite_var() で設定したリライト変数は、透過的セッションID出力バッファと同じセッションモジュールを使っていました。 PHP 7.1.0 以降では、専用の出力バッファを用いるようになり、 output_reset_rewrite_vars() は output_add_rewrite_var(). で定義したリライト変数だけを削除するようになります。

例

例1 output_reset_rewrite_vars() の例

<?php
ini_set('url_rewriter.tags', 'a=href');

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?var=value">link</a>
<a href="file.php">link</a>

参考

  • output_add_rewrite_var() - URL リライタの値を追加する
  • ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する
  • url_rewriter.tags
  • url_rewriter.hosts
  • session.trans_sid_tags
  • session.trans_sid_hosts


PHP オプションと情報

  • はじめに
  • インストール/設定
    • 実行時設定
  • 定義済み定数
  • PHP オプション/情報 関数
    • assert — アサーションの値を調べる
    • assert_options — 様々な assert フラグを設定/取得する
    • cli_get_process_title — 現在のプロセスのタイトルを返す
    • cli_set_process_title — プロセスのタイトルを設定する
    • dl — 実行時に PHP 拡張モジュールをロードする
    • extension_loaded — ある拡張モジュールがロードされているかどうかを調べる
    • gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する
    • gc_disable — 循環参照コレクタを無効にする
    • gc_enable — 循環参照コレクタを有効にする
    • gc_enabled — 循環参照コレクタの状態を返す
    • gc_mem_caches — Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する
    • gc_status — ガベージコレクタに関する情報を取得する
    • 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 のエイリアス
    • get_resources — アクティブなリソースを返す
    • getenv — 環境変数の値をひとつ、または全て取得する
    • getlastmod — 最終更新時刻を取得する
    • getmygid — PHP スクリプトの所有者の GID を得る
    • getmyinode — 現在のスクリプトの inode を取得する
    • getmypid — PHP のプロセス ID を取得する
    • getmyuid — PHP スクリプト所有者のユーザー ID を取得する
    • getopt — コマンドライン引数のリストからオプションを取得する
    • getrusage — 現在のリソース使用状況を取得する
    • ini_alter — ini_set のエイリアス
    • ini_get — 設定オプションの値を得る
    • ini_get_all — すべての設定オプションを得る
    • ini_parse_quantity — ini ディレクティブの省略形を解釈し、サイズを取得する
    • ini_restore — 設定オプションの値を元に戻す
    • ini_set — 設定オプションの値を設定する
    • memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す
    • memory_get_usage — PHP に割り当てられたメモリの量を返す
    • memory_reset_peak_usage — メモリの最大値をリセットする
    • php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する
    • php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する
    • 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_time_limit — 実行時間の最大値を制限する
    • sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す
    • version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する
    • zend_thread_id — 現在のスレッドの一意な ID を返す
    • zend_version — 現在の Zend Engine のバージョンを取得する


はじめに

以下の関数によりPHP自体に関する多くの情報(例えば、実行時の設定、 ロードされている拡張モジュール、バージョン等)を 得ることができます。実行しているPHPのオプションを設定する関数もあ ります。おそらく最も有名な関数であるphpinfo() もここにあります。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • PHP Options/Info
  • インストール/設定

インストール/設定

目次

  • 実行時設定


実行時設定

php.ini の設定により動作が変化します。

PHP オプション/情報設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
assert.active | "1" | INI_ALL | PHP 8.3.0 以降は非推奨
assert.bail | "0" | INI_ALL | PHP 8.3.0 以降は非推奨
assert.warning | "1" | INI_ALL | PHP 8.3.0 以降は非推奨
assert.callback | NULL | INI_ALL | PHP 8.3.0 以降は非推奨
assert.quiet_eval | "0" | INI_ALL | PHP 8.0.0 で削除
assert.exception | "1" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "0" でした。 PHP 8.3.0 以降は非推奨
enable_dl | "1" | INI_SYSTEM | この非推奨の機能は、きっと 将来 削除 されるでしょう。
max_execution_time | "30" | INI_ALL |
max_input_time | "-1" | INI_PERDIR |
max_input_nesting_level | "64" | INI_PERDIR |
max_input_vars | 1000 | INI_PERDIR |
zend.enable_gc | "1" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

assert.active bool

assert() の評価を有効にします。 assert() の振る舞いを制御するには、 zend.assertions を代わりに使うべきです。

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

assert.bail bool

assertion が失敗した時にスクリプトの実行を終了します。

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

assert.warning bool

assertion が失敗する度に PHP 警告を発行します。

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

assert.callback string

assertion が失敗した時にコールされるユーザー関数

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

assert.quiet_eval bool
警告

この機能は、PHP 8.0.0 で 削除されました。

assertion 式の評価時に error_reporting() の現在の 設定を使用します。有効な場合、評価時にエラーは表示されません。 (暗黙のうちに error_reporting(0) とします) 無効な場合、エラーは、error_reporting() の設定に 基づき設定されます。

assert.exception bool

アサーションに失敗した場合に AssertionError 例外を発行します。

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

enable_dl bool

このディレクティブを使うと、 PHP の拡張モジュールを dl() で動的にロードする機能を、オンまたはオフに変更することができます。

動的ロード機能をオフにするのは主としてセキュリティ上の理由によります。 動的ロード機能により、 open_basedir の拘束を全て 無視することが可能になります。 デフォルトでは、動的ロードが可能です。

max_execution_time int

スクリプトがパーサにより強制終了されるまでに許容される最大の 時間を秒単位で指定します。この命令は、いい加減に書かれた スクリプトがサーバーの負荷を上げることを防止するのに役立ちます。 デフォルトでは、30 に設定されています。 PHP を コマンドライン から実行する場合のデフォルト設定は 0 です。

Windows 以外のシステムでは、 最大実行時間は、システムコール、ストリーム操作等の 影響を受けません。より詳細な情報については、 set_time_limit() 関数の説明を参照ください。

Web サーバー側でもタイムアウトの設定項目を持ち、 その設定で PHP の実行が中断されることもあります。 Apache には Timeout ディレクティブ、IIS には CGI タイムアウト関数があり、どちらもデフォルトで 300 秒に設定されています。 これらの意味については、Web サーバーのドキュメントを参照ください。

max_input_time int

スクリプトが POST、GET などの入力を パースする最大の時間を、秒単位で指定します。 これは、サーバー側で PHP が起動してからスクリプトの実行を開始するまでの時間です。 デフォルトの設定は -1 です。 これは max_execution_time が代わりに使われることを意味しています。 無制限にするには、0 を設定してください。

max_input_nesting_level int

外部からの入力変数 ($_GET や $_POST など) のネストの深さの最大値を設定します。

max_input_vars int

入力変数 を最大で何個まで受け付けるかを指定します (この制限は、スーパーグローバル $_GET、$_POST そして $_COOKIE にそれぞれ個別に適用されます)。 このディレクティブを使うと、ハッシュの衝突を悪用したサービス不能攻撃を受ける可能性を軽減できます。 このディレクティブで設定した数を超える入力変数があった場合は E_WARNING が発生し、 それ以降の入力変数はリクエストから削除されます。

zend.enable_gc bool

循環参照コレクタを有効あるいは無効にします。


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

定義済の phpcredits() 定数
定数 | 説明
CREDITS_GROUP (int) | コア開発者のリスト
CREDITS_GENERAL (int) | 一般的なクレジット: 言語設計とコンセプト、PHP と PHP SAPIモジュールの作者。
CREDITS_SAPI (int) | PHPのサーバーAPIモジュールとその作者の一覧。
CREDITS_MODULES (int) | PHPの拡張モジュールとその作者の一覧。
CREDITS_DOCS (int) | ドキュメント作成チームのクレジット
CREDITS_FULLPAGE (int) | 通常、他のフラグと組み合わせて使用されます。 他のフラグで示される情報を含む完全に独立したHTMLページを出力する ことを指定します。
CREDITS_QA (int) | 品質管理チームのクレジット
CREDITS_ALL (int) | 全てのクレジット、CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE を指定した場合と同じ。 この定数は、適当なタグを有する完全にスタンドアローンのHTMLページ を生成します。
phpinfo() の定数
定数 | 説明
INFO_GENERAL (int) | configureオプション、php.ini の場所、構築日、Webサーバー、システム等。
INFO_CREDITS (int) | PHP クレジット。phpcredits()も参照ください。
INFO_CONFIGURATION (int) | PHPディレクティブの現在のローカルおよびマスター値。 ini_get()も参照ください。
INFO_MODULES (int) | ロードされているモジュールとそれぞれの設定。
INFO_ENVIRONMENT (int) | 環境変数に関する情報で、$_ENVでも入手可能です。
INFO_VARIABLES (int) | EGPCS (Environment, GET, POST, Cookie, Server)から定義済の変数を表示します。
INFO_LICENSE (int) | PHPライセンス情報。» license faqも参照ください。
INFO_ALL (int) | 上記を全て表示します。これがデフォルト値です。
INI モードの定数
定数 | 説明
INI_USER (int) | エントリはユーザーのスクリプトで (ini_set() のようなものを使って) 設定できます。 また、Windows registry でも設定できます。 .user.ini でも設定できます。
INI_PERDIR (int) | エントリは php.ini, .htaccess, httpd.conf, .user.ini で設定できます。
INI_SYSTEM (int) | エントリは php.ini または httpd.conf で設定できます。
INI_ALL (int) | エントリはどこでも設定できます

Assert 定数。これらの値を使用して、 assert_options() のオプションを設定します。

assert() 定数
定数 | 説明
ASSERT_ACTIVE (int) | assert() の評価を有効にします。 警告 この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。
ASSERT_CALLBACK (int) | アサーションに失敗した場合に実行するコールバック。 警告 この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。
ASSERT_BAIL (int) | アサーションに失敗した時点に実行を中断します。 警告 この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。
ASSERT_EXCEPTION (int) | アサーションに失敗するたびに PHP の警告を発行します。 警告 この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。
ASSERT_WARNING (int) | アサーションに失敗するたびに PHP の警告を発行します。 警告 この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。
ASSERT_QUIET_EVAL (int) | アサーション式の評価中は error_reporting を無効にします。 警告 この機能は、PHP 8.0.0 で 削除されました。

次の定数は、ホスト OS が Windows の場合にのみ使用可能なものです。 バージョン情報を知ることができるので、さまざまな機能を使う際に役立ちます。

Windows 固有の定数
定数 | 説明
PHP_WINDOWS_VERSION_MAJOR (int) | Windows のメジャーバージョン。4 (NT4/Me/98/95)、 5 (XP/2003 R2/2003/2000) あるいは 6 (Vista/2008/7/8/8.1) となります。
PHP_WINDOWS_VERSION_MINOR (int) | Windows のマイナーバージョン。0 (Vista/2008/2000/NT4/95)、 1 (XP)、2 (2003 R2/2003/XP x64)、10 (98) あるいは 90 (ME) となります。
PHP_WINDOWS_VERSION_BUILD (int) | Windows のビルド番号 (たとえば Windows Vista SP1 はビルド 6001 となります)。
PHP_WINDOWS_VERSION_PLATFORM (int) | PHP が現在動作しているプラットフォーム。この値は Windows Vista/XP/2000/NT4, Server 2008/2003 では 2、 Windows ME/98/95 では 1 となります。
PHP_WINDOWS_VERSION_SP_MAJOR (int) | インストールされているサービスパックのメジャーバージョン。サービスパックがインストールされていない場合は 0 となります。たとえば Windows XP にサービスパック 3 をインストールした場合、この値は 3 となります。
PHP_WINDOWS_VERSION_SP_MINOR (int) | インストールされているサービスパックのマイナーバージョン。サービスパックがインストールされていない場合は 0 となります。
PHP_WINDOWS_VERSION_SUITEMASK (int) | Windows のさまざまな機能がインストールされているかどうかを示すビットマスク。 各フィールドの意味については以下の表を参照ください。
PHP_WINDOWS_VERSION_PRODUCTTYPE (int) | PHP_WINDOWS_NT_* 定数を決定するために使用する値を含みます。 この値は PHP_WINDOWS_NT_* 定数のいずれかとなり、 プラットフォームの形式を示します。
PHP_WINDOWS_NT_DOMAIN_CONTROLLER (int) | これはドメインコントローラです。
PHP_WINDOWS_NT_SERVER (int) | これはサーバーシステム (Server 2008/2003/2000 など) です。もしドメインコントローラである場合は PHP_WINDOWS_NT_DOMAIN_CONTROLLER と報告されることに注意しましょう。
PHP_WINDOWS_NT_WORKSTATION (int) | これはワークステーションシステム (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 — アサーションの値を調べる
  • assert_options — 様々な assert フラグを設定/取得する
  • cli_get_process_title — 現在のプロセスのタイトルを返す
  • cli_set_process_title — プロセスのタイトルを設定する
  • dl — 実行時に PHP 拡張モジュールをロードする
  • extension_loaded — ある拡張モジュールがロードされているかどうかを調べる
  • gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する
  • gc_disable — 循環参照コレクタを無効にする
  • gc_enable — 循環参照コレクタを有効にする
  • gc_enabled — 循環参照コレクタの状態を返す
  • gc_mem_caches — Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する
  • gc_status — ガベージコレクタに関する情報を取得する
  • 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 のエイリアス
  • get_resources — アクティブなリソースを返す
  • getenv — 環境変数の値をひとつ、または全て取得する
  • getlastmod — 最終更新時刻を取得する
  • getmygid — PHP スクリプトの所有者の GID を得る
  • getmyinode — 現在のスクリプトの inode を取得する
  • getmypid — PHP のプロセス ID を取得する
  • getmyuid — PHP スクリプト所有者のユーザー ID を取得する
  • getopt — コマンドライン引数のリストからオプションを取得する
  • getrusage — 現在のリソース使用状況を取得する
  • ini_alter — ini_set のエイリアス
  • ini_get — 設定オプションの値を得る
  • ini_get_all — すべての設定オプションを得る
  • ini_parse_quantity — ini ディレクティブの省略形を解釈し、サイズを取得する
  • ini_restore — 設定オプションの値を元に戻す
  • ini_set — 設定オプションの値を設定する
  • memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す
  • memory_get_usage — PHP に割り当てられたメモリの量を返す
  • memory_reset_peak_usage — メモリの最大値をリセットする
  • php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する
  • php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する
  • 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_time_limit — 実行時間の最大値を制限する
  • sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す
  • version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する
  • zend_thread_id — 現在のスレッドの一意な ID を返す
  • zend_version — 現在の Zend Engine のバージョンを取得する


アサーションの値を調べる

  • ≪ PHP オプション/情報 関数
  • assert_options ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • アサーションの値を調べる

assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — アサーションの値を調べる

説明

assert(mixed $assertion, Throwable|string|null $description = null): bool

assert() は expectation の定義を満たします。すなわち、 開発環境やテスト環境では有効であるが、 運用環境では除去されて、まったくコストのかからないアサーションということです。

アサーションは、デバッグ目的にのみ使用するべきです。 アサーションを常に true となる条件を調べる不具合診断に使用し、 true でない場合に何らかのプログラミングエラーを示したり、 extension 関数または特定のシステム制限や機能といった、 特定の機能の存在をチェックするために使用することが可能です。

アサーションは削除するように設定できるため、 入力パラメータのチェックのような通常の実行動作に使用するべきでは ありません。 一般的には、アサーションのチェックを無効にしてもそのコードが正常に動作しなければなりません。

assert() は assertion で指定された expectation をチェックします。 それを満たさない場合、この関数の結果は false になり、 assert() の設定に応じて適切な動作をします。

assert() の振る舞いは、以下のINI設定によって制御できます:

Assert 設定オプション
名前 | デフォルト | 説明 | 変更履歴
zend.assertions 1
  • 1: コードを生成して実行する (開発モード)
  • 0: コードを生成するが、実行時には読み飛ばす
  • -1: コードを生成しない (運用モード)
assert.active | true | false を指定すると、 assert() は expectation をチェックせず、 無条件に true を返します。 | PHP 8.3.0 以降は非推奨
assert.callback null

アサーションが失敗した時にコールされるユーザー定義の関数。 シグネチャは以下の形であるべきです:

assert_callback(
string $file,
int $line,
null $assertion,
string $description = ?
): void

PHP 8.0.0 より前のバージョンでは、 コールバックのシグネチャは以下の形であるべきでした:

assert_callback(
string $file,
int $line,
string $assertion,
string $description = ?
): void

PHP 8.3.0 以降は非推奨
assert.exception | true | true を指定すると、expectation を満たさない場合に AssertionError がスローされます。 | PHP 8.3.0 以降は非推奨
assert.bail | false | true を指定すると、expectation を満たさない場合に PHP スクリプトの実行を停止します。 | PHP 8.3.0 以降は非推奨
assert.warning | true | true を指定すると、expectation を満たさない場合に E_WARNING が発生します。 このINI設定は assert.exception が有効な場合は意味がありません。 | PHP 8.3.0 以降は非推奨

パラメータ

assertion

値を返すあらゆる式を指定できます。 この式を実行した結果を用いて、アサーションに成功したか否かを判断します。

警告

PHP 8.0.0 より前のバージョンでは、 assertion に文字列を指定すると、 PHP コードとして解釈され、 eval() 経由で実行されていました。 この文字列はコールバックの3番目の引数として渡されていました。 この振る舞いは PHP 7.2.0 以降では 非推奨 になり、 PHP 8.0.0 で 削除されました。

description

description が Throwable のインスタンスの場合、 assertion が実行され、 かつ失敗した場合にスローされます。

注意:

PHP 8.0.0 以降では、 定義済みのアサーションのコールバックがコールされる 前 に上の処理は行われます。

注意:

PHP 8.0.0 以降では、 assert.exception の設定に関わらず、object がスローされます。

注意:

例外がスローされる場合、 PHP 8.0.0 以降では、 assert.bail は意味がありません。

description が文字列の場合、 例外や警告が発生した場合にここで指定したメッセージを使います。 assertion が失敗したときのオプションのメッセージを指定します。

description は省略できます。 デフォルトの値は、assert() を呼び出したソースコードと同じです。この値はコンパイル時に生成されます。

戻り値

assert() は、以下のうちのひとつが当てはまる場合、常に true を返します:

  • zend.assertions=0
  • zend.assertions=-1
  • assert.exception=1
  • assert.bail=1
  • カスタムの例外オブジェクトが description に渡された場合

上記の条件がすべて当てはまらない場合でも、 assertion が真と評価できる値であれば true を返します。 そうでない場合、false を返します。

変更履歴

バージョン | 説明
8.3.0 | すべての assert. INI 設定は、推奨されなくなりました。
8.0.0 | assert() は、文字列の引数を評価しなくなりました。 代わりに、他の引数と同じ扱いをされるようになっています。 assert('$a == $b') ではなく、assert($a == $b) を使うべきです。 php.ini ディレクティブ assert.quiet_eval と定数 ASSERT_QUIET_EVAL も削除されており、 それらを使っても何も起きなくなっています。
8.0.0 | description が Throwable のインスタンスの場合、 assertion が失敗した場合、 assert.exception の値に関わらず、object がスローされるようになりました。
8.0.0 | descriptionが Throwable のインスタンスの場合、 たとえ設定されていてもコールバックは呼び出されません。
8.0.0 | 名前空間の内部で、assert() という名前の関数を宣言することはできなくなりました。 宣言した場合、E_COMPILE_ERROR が発生します。
7.3.0 | 名前空間の内部で、assert() という名前の関数を宣言することは推奨されなくなりました。 宣言した場合、 E_DEPRECATED が発生するようになっています。
7.2.0 | assertion に string を使うことは推奨されなくなりました。 assert.active と zend.assertions が両方 1 に設定されると E_DEPRECATED レベルの警告が発生するようになりました。

例

例1 assert() の例

<?php
assert(1 > 2);
echo 'Hi!';

アサーションが有効になっている (zend.assertions=1) 場合は、上の例の結果は次のようになります:

Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'assert(1 > 2)')
#1 {main}
  thrown in example.php on line 2

アサーションが無効になっている (zend.assertions=0 または zend.assertions=-1) 場合は、上の例の結果は次のようになります:

Hi!

例2 カスタムのメッセージを使う

<?php
assert(1 > 2, "Expected one to be greater than two");
echo 'Hi!';

アサーションが有効になっている場合は、上の例の結果は次のようになります:

Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'Expected one to...')
#1 {main}
  thrown in example.php on line 2

アサーションが無効になっている場合は、上の例の結果は次のようになります:

Hi!

例3 カスタムの例外クラスを使う

<?php
class ArithmeticAssertionError extends AssertionError {}

assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
echo 'Hi!';

アサーションが有効になっている場合は、上の例の結果は次のようになります:

Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
Stack trace:
#0 {main}
  thrown in example.php on line 4

アサーションが無効になっている場合は、上の例の結果は次のようになります:

Hi!

参考

  • assert_options() - 様々な assert フラグを設定/取得する


様々な assert フラグを設定/取得する

  • ≪ assert
  • cli_get_process_title ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 様々な assert フラグを設定/取得する

assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — 様々な assert フラグを設定/取得する

警告

この関数は PHP 8.3.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

assert_options(int $option, mixed $value = ?): mixed

種々の assert() 制御オプションを設定したり、 単に現在の設定を調べたりします。

注意: assert_options() を使うことはお勧めできません。 php.ini のディレクティブ zend.assertions と assert.exception を ini_set() や ini_get() で取得したり設定したりする方が望ましいです。

パラメータ

option

assert オプション
オプション | INI 設定 | デフォルト値 | 説明
ASSERT_ACTIVE | assert.active | 1 | assert() による評価を有効にする
ASSERT_EXCEPTION | assert.exception | 1 | assertion に失敗するたびに AssertionErrorをスローする
ASSERT_WARNING | assert.warning | 1 | assertion に失敗するたびに PHP の警告を発生させる
ASSERT_BAIL | assert.bail | 0 | assersion に失敗した場合に実行を終了する
ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | assersion 式については error_reporting を無効にする。 PHP 8.0.0 以降では削除されています。
ASSERT_CALLBACK | assert.callback | (null) | assertion に失敗した場合にコールされるコールバック

value

オプションに指定する新しい値。

ASSERT_CALLBACK 定数または assert.callback に設定するコールバック関数は、次のようなシグネチャを持つべきです:

assert_callback(
string $file,
int $line,
?string $assertion,
string $description = ?
): void
file
assert() 関数がコールされたファイル名
line
assert() 関数がコールされた行番号
assertion
PHP 8.0.0 より前のバージョンでは、 この値は assert() に渡された assertion でした。 但し、これは assertion が文字列として渡された場合に限られていました。 (assertion が 論理型の条件だった場合は、このパラメータは空文字列でした)。 PHP 8.0.0 以降では、このパラメータは常に null になります。
description
assert() 関数に渡された説明

value に空文字列を渡すと、assertコールバックはリセットされます。

戻り値

そのオプションの元の値を返します。

エラー / 例外

option が無効なオプションの場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | assert_option() は、推奨されなくなりました。
8.0.0 | option が無効なオプションの場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、false を返していました。

例

例1 assert_options() の例

<?php
// これは、assert に失敗した際の
// 処理を行う関数です
function assert_failure($file, $line, $assertion, $message)
{
echo "The assertion $assertion in $file on line $line has failed: $message";
}

// これがテスト関数です
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() - アサーションの値を調べる


現在のプロセスのタイトルを返す

  • ≪ assert_options
  • cli_set_process_title ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のプロセスのタイトルを返す

cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — 現在のプロセスのタイトルを返す

説明

cli_get_process_title(): ?string

現在のプロセスのタイトルを返します。これは cli_set_process_title() で設定したものです。 これは、ps や top で表示されるタイトルと必ずしも一致するとは限りません。OS に依存します。

この関数は、 CLI モードでしか使えません。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のプロセスのタイトルを文字列で返します。エラー時には null を返します。

エラー / 例外

OS がこの機能に対応していない場合に E_WARNING が発生します。

例

例1 cli_get_process_title() の例

<?php
echo "Process title: " . cli_get_process_title() . "\n";
?>

参考

  • cli_set_process_title() - プロセスのタイトルを設定する


プロセスのタイトルを設定する

  • ≪ cli_get_process_title
  • dl ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • プロセスのタイトルを設定する

cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — プロセスのタイトルを設定する

説明

cli_set_process_title(string $title): bool

プロセスのタイトルを設定します。これは top や ps といったツールで表示されます。 この関数は、 CLI モードでしか使えません。

パラメータ

title

新しいタイトル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

OS がこの機能に対応していない場合に E_WARNING が発生します。

例

例1 cli_set_process_title() の例

<?php
$title = "My Amazing PHP Script";
$pid = getmypid(); // これを使えば、プロセスのタイトルを ps で確認できます

if (!cli_set_process_title($title)) {
echo "Unable to set process title for PID $pid...\n";
exit(1);
} else {
echo "The process title '$title' for PID $pid has been set for your process!\n";
sleep(5);
}
?>

参考

  • cli_get_process_title() - 現在のプロセスのタイトルを返す


実行時に PHP 拡張モジュールをロードする

  • ≪ cli_set_process_title
  • extension_loaded ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 実行時に PHP 拡張モジュールをロードする

dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — 実行時に PHP 拡張モジュールをロードする

説明

dl(string $extension_filename): bool

extension_filename で指定された PHP 拡張モジュールを読み込みます。

その拡張モジュールが既に使用可能かどうかを調べるには、 extension_loaded() を使用します。 これは、組み込みのモジュールと (php.ini か、あるいは dl() を使用して) 動的に読み込むモジュールの両方に対応しています。

警告

この関数は、CLI と、組み込済みの SAPI に対してのみ使えます。 また、コマンドラインから実行している場合にのみ CGI SAPI に対しても使えます。

パラメータ

extension_filename

このパラメータに指定できるのは拡張モジュールの ファイル名だけであり、それはプラットフォームに依存します。 例えば、Unix プラットフォームでは sockets 拡張モジュール (共有モジュールとしてコンパイルされていれば。デフォルトでは有りません!) は sockets.so と呼ばれていますし、一方 Windows プラットフォームでは php_sockets.dll と呼ばれます。

拡張モジュールを読み込むディレクトリは、プラットフォームによって異なります。

Windows - php.ini に明記されていない場合、デフォルトでは 拡張モジュールは、C:\php5\ からロードされます。

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 でオフにされている)場合は、 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_SHLIB_SUFFIX 定数を使用
if (!extension_loaded('sqlite')) {
$prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
}
?>

注意

注意:

dl() は Unix プラットフォーム上では 大文字小文字を区別します。

参考

  • 拡張モジュール読み込み用のディレクティブ
  • extension_loaded() - ある拡張モジュールがロードされているかどうかを調べる


ある拡張モジュールがロードされているかどうかを調べる

  • ≪ dl
  • gc_collect_cycles ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ある拡張モジュールがロードされているかどうかを調べる

extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — ある拡張モジュールがロードされているかどうかを調べる

説明

extension_loaded(string $extension): bool

拡張モジュールがロードされているかどうかを調べます。

パラメータ

extension

拡張モジュールの名前。大文字小文字を区別します。

phpinfo()を使って種々の拡張モジュールの 名前を見ることができます。PHP の CGIまたはCLIバージョン を使っている場合には -m スイッチで、 使用できる全ての拡張モジュールのリストを得ることができます:

$ php -m
[PHP Modules]
xml
tokenizer
standard
sockets
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

戻り値

extension で指定する拡張モジュールがロードされている場合に true を返します。さもなければ false を返します。

例

例1 extension_loaded() の例

<?php
if (!extension_loaded('gd')) {
if (!dl('gd.so')) {
exit;
}
}
?>

参考

  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_extension_funcs() - あるモジュールの関数名を配列として返す
  • phpinfo() - PHP の設定情報を出力する
  • dl() - 実行時に PHP 拡張モジュールをロードする
  • function_exists() - 指定した関数が定義されている場合に true を返す


すべての既存ガベージサイクルを強制的に収集する

  • ≪ extension_loaded
  • gc_disable ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • すべての既存ガベージサイクルを強制的に収集する

gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する

説明

gc_collect_cycles(): int

すべての既存ガベージサイクルを強制的に収集します。

パラメータ

この関数にはパラメータはありません。

戻り値

収集したサイクルの数を返します。

参考

  • ガベージコレクション


循環参照コレクタを無効にする

  • ≪ gc_collect_cycles
  • gc_enable ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 循環参照コレクタを無効にする

gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — 循環参照コレクタを無効にする

説明

gc_disable(): void

zend.enable_gc を 0 に設定して、循環参照コレクタを無効にします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • ガベージコレクション


循環参照コレクタを有効にする

  • ≪ gc_disable
  • gc_enabled ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 循環参照コレクタを有効にする

gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — 循環参照コレクタを有効にする

説明

gc_enable(): void

zend.enable_gc を 1 に設定して、循環参照コレクタを有効にします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • ガベージコレクション


循環参照コレクタの状態を返す

  • ≪ gc_enable
  • gc_mem_caches ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 循環参照コレクタの状態を返す

gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — 循環参照コレクタの状態を返す

説明

gc_enabled(): bool

循環参照コレクタの状態を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ガベージコレクタが有効な場合に true、そうでない場合に false を返します。

例

例1 gc_enabled() の例

<?php
if(gc_enabled()) gc_collect_cycles();
?>

参考

  • ガベージコレクション


Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

  • ≪ gc_enabled
  • gc_status ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

説明

gc_mem_caches(): int

Zend Engine のメモリーマネージャによって使用されたメモリーを再利用します。

パラメータ

この関数にはパラメータはありません。

戻り値

解放されたバイト数を返します。

参考

  • ガベージコレクション


ガベージコレクタに関する情報を取得する

  • ≪ gc_mem_caches
  • get_cfg_var ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ガベージコレクタに関する情報を取得する

gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — ガベージコレクタに関する情報を取得する

説明

gc_status(): array

ガベージコレクタの現在の状態に関する情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

次の要素を持つ連想配列を返します:

  • "runs"
  • "collected"
  • "threshold"
  • "roots"
  • "running"
  • "protected"
  • "full"
  • "buffer_size"
  • "application_time"
  • "collector_time"
  • "destructor_time"
  • "free_time"

変更履歴

バージョン | 説明
8.3.0 | gc_status() は、 以下の追加のフィールドを返すようになりました: "running", "protected", "full", "buffer_size", "application_time", "collector_time", "destructor_time", and "free_time".

例

例1 gc_status() の使い方

<?php

// create object tree that needs gc collection
$a = new stdClass();
$a->b = [];
for ($i = 0; $i < 100000; $i++) {
$b = new stdClass();
$b->a = $a;
$a->b[] = $b;
}
unset($a);
unset($b);
gc_collect_cycles();

var_dump(gc_status());

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["runs"]=>
  int(5)
  ["collected"]=>
  int(100002)
  ["threshold"]=>
  int(50001)
  ["roots"]=>
  int(0)
}

上の例の PHP 8.3 での出力は、たとえば以下のようになります。:

array(12) {
  ["running"]=>
  bool(false)
  ["protected"]=>
  bool(false)
  ["full"]=>
  bool(false)
  ["runs"]=>
  int(5)
  ["collected"]=>
  int(100002)
  ["threshold"]=>
  int(50001)
  ["buffer_size"]=>
  int(131072)
  ["roots"]=>
  int(0)
  ["application_time"]=>
  float(0.031182458)
  ["collector_time"]=>
  float(0.020106291)
  ["destructor_time"]=>
  float(0)
  ["free_time"]=>
  float(0.003707167)
}

参考

  • ガベージコレクション


PHP 設定オプションの値を取得する

  • ≪ gc_status
  • get_current_user ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP 設定オプションの値を取得する

get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — PHP 設定オプションの値を取得する

説明

get_cfg_var(string $option): string|array|false

PHP の設定オプション option の値を取得します。

この関数は、 PHP がコンパイルされた際にセットされた設定情報や Apache の設定ファイルから読んだ設定情報は返しません。

システムが 設定ファイル を使用しているかどうかを確認するには、cfg_file_path の設定値を取得してみてください。 この値が利用可能なら、設定ファイルが使用されています。

パラメータ

option

設定オプションの名前。

戻り値

option で指定された PHP 設定オプションの現在の値を返し、 エラーの場合は false を返します。

参考

  • ini_get() - 設定オプションの値を得る
  • ini_get_all() - すべての設定オプションを得る


現在の PHP スクリプトの所有者の名前を取得する

  • ≪ get_cfg_var
  • get_defined_constants ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の PHP スクリプトの所有者の名前を取得する

get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — 現在の PHP スクリプトの所有者の名前を取得する

説明

get_current_user(): string

現在の 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_current_user
  • get_extension_funcs ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • すべての定数の名前とその値を連想配列として返す

get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — すべての定数の名前とその値を連想配列として返す

説明

get_defined_constants(bool $categorize = false): array

現在定義されている全ての定数の名前と値を返します。返される値には、 拡張モジュールにより作成された定数や 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
        )

)

戻り値

定数名 => 定数値 の配列の配列を返します。 オプションで、その定数を定義している拡張モジュール名ごとにグループ化することもできます。

例

例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
)

参考

  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • constant() - 定数の値を返す
  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_defined_functions() - 定義済みの全ての関数を配列で返す
  • get_defined_vars() - 全ての定義済の変数を配列で返す


あるモジュールの関数名を配列として返す

  • ≪ get_defined_constants
  • get_include_path ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • あるモジュールの関数名を配列として返す

get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — あるモジュールの関数名を配列として返す

説明

get_extension_funcs(string $extension): array|false

この関数は、extension で示したモジュールで定義された全ての関数の名前を返します。

パラメータ

extension

モジュール名。

注意:

このパラメータは 小文字 でなければなりません。

戻り値

すべての関数を含む配列を返します。 extension が拡張モジュールでない場合は 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
)

参考

  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • ReflectionExtension::getFunctions() - 拡張モジュールの関数を取得する


現在の include_path 設定オプションを取得する

  • ≪ get_extension_funcs
  • get_included_files ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の include_path 設定オプションを取得する

get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — 現在の include_path 設定オプションを取得する

説明

get_include_path(): string|false

現在の include_path 設定オプションを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

パスを表す文字列を返します。 失敗した場合に false を返します

例

例1 get_include_path() の例

<?php
echo get_include_path();

// または ini_get を使用します
echo ini_get('include_path');
?>

参考

  • ini_get() - 設定オプションの値を得る
  • restore_include_path() - include_path 設定オプションの値を元に戻す
  • set_include_path() - include_path 設定オプションをセットする
  • include - include


include または require で読み込まれたファイルの名前を配列として返す

  • ≪ get_include_path
  • get_loaded_extensions ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • include または require で読み込まれたファイルの名前を配列として返す

get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — include または require で読み込まれたファイルの名前を配列として返す

説明

get_included_files(): array

この関数は、 include、include_once、 require あるいは require_once によりスクリプトにロードされたすべてのファイルの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

すべてのファイル名を含む配列を返します。

最初にコールされたスクリプトは "include されたファイル" という扱いに なります。そのため、 include やその仲間たちにより 読み込まれたファイルの一覧に含めて表示されます。

複数回読み込まれているファイルも、 返される配列には一度しかあらわれません。

例

例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";
}

?>

上の例の出力は以下となります。

/path/to/abc.php
/path/to/test1.php
/path/to/test2.php
/path/to/test3.php
/path/to/test4.php

参考

  • include - include
  • include_once - include_once
  • require - require
  • require_once - require_once
  • get_required_files() - get_included_files のエイリアス


コンパイル/ロードされている全てのモジュールの名前を配列として返す

  • ≪ get_included_files
  • get_magic_quotes_gpc ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • コンパイル/ロードされている全てのモジュールの名前を配列として返す

get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — コンパイル/ロードされている全てのモジュールの名前を配列として返す

説明

get_loaded_extensions(bool $zend_extensions = false): array

この関数は、PHPインタプリタにコンパイル、 ロードされている全てのモジュールの名前を返します。

パラメータ

zend_extensions

Zend 拡張モジュールのみを返します。指定しない場合は、 mysqli のような通常の拡張モジュールを返します。デフォルトは false (通常の拡張モジュールを返す) です。

戻り値

モジュール名の配列を返します。

例

例1 get_loaded_extensions() の例

<?php
print_r(get_loaded_extensions());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Core
    [1] => date
    [2] => libxml
    [3] => pcre
    [4] => sqlite3
    [5] => zlib
    [6] => ctype
    [7] => dom
    [8] => fileinfo
    [9] => filter
    [10] => hash
    [11] => json
    [12] => mbstring
    [13] => SPL
    [14] => PDO
    [15] => session
    [16] => posix
    [17] => Reflection
    [18] => standard
    [19] => SimpleXML
    [20] => pdo_sqlite
    [21] => Phar
    [22] => tokenizer
    [23] => xml
    [24] => xmlreader
    [25] => xmlwriter
    [26] => gmp
    [27] => iconv
    [28] => intl
    [29] => bcmath
    [30] => sodium
    [31] => Zend OPcache
)

参考

  • get_extension_funcs() - あるモジュールの関数名を配列として返す
  • extension_loaded() - ある拡張モジュールがロードされているかどうかを調べる
  • dl() - 実行時に PHP 拡張モジュールをロードする
  • phpinfo() - PHP の設定情報を出力する


magic_quotes_gpc の現在の設定を得る

  • ≪ get_loaded_extensions
  • get_magic_quotes_runtime ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • magic_quotes_gpc の現在の設定を得る

get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — magic_quotes_gpc の現在の設定を得る

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

get_magic_quotes_gpc(): false

常に false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

常に false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は推奨されなくなりました。

参考

  • addslashes() - 文字列をスラッシュでクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • get_magic_quotes_runtime() - magic_quotes_runtime の現在アクティブな設定値を取得する
  • ini_get() - 設定オプションの値を得る


magic_quotes_runtime の現在アクティブな設定値を取得する

  • ≪ get_magic_quotes_gpc
  • get_required_files ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • magic_quotes_runtime の現在アクティブな設定値を取得する

get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — magic_quotes_runtime の現在アクティブな設定値を取得する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

get_magic_quotes_runtime(): false

常に false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

常に false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は推奨されなくなりました。

参考

  • get_magic_quotes_gpc() - magic_quotes_gpc の現在の設定を得る


get_included_files のエイリアス

  • ≪ get_magic_quotes_runtime
  • get_resources ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • get_included_files のエイリアス

get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — get_included_files() のエイリアス

説明

この関数は次の関数のエイリアスです。 get_included_files().


アクティブなリソースを返す

  • ≪ get_required_files
  • getenv ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • アクティブなリソースを返す

get_resources

(PHP 7, PHP 8)

get_resources — アクティブなリソースを返す

説明

get_resources(?string $type = null): array

現在アクティブなすべてのリソースの配列を返します。 オプションでリソース型によってフィルタリングされます。

注意: この関数は、デバッグやテストの用途に使うものです。 本番環境で使う用途を想定していません。 特に、通常のやり方ではアクセスできないリソース (例: SplFileObject インスタンスのストリームリソース) にアクセスしたり、管理する用途に使ってはいけません。

パラメータ

type

定義された場合、get_resources() は、指定された型のリソースのみを返すようになります。 リソース型の一覧が使用できます。

string Unknown が型として指定された場合、 不明な型のリソースのみが返されます。

省略した場合、すべてのリソースが返されます。

戻り値

現在アクティブなリソースの array を返します。 リソース番号でインデックス付けされます。

変更履歴

バージョン | 説明
8.0.0 | type は、nullable になりました。

例

例1 フィルタリングされていない get_resources()

<?php
$fp = tmpfile();
var_dump(get_resources());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [1]=>
  resource(1) of type (stream)
}

例2 フィルタリングされた get_resources()

<?php
$fp = tmpfile();
var_dump(get_resources('stream'));
var_dump(get_resources('curl'));
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [1]=>
  resource(1) of type (stream)
}
array(0) {
}

参考

  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_defined_constants() - すべての定数の名前とその値を連想配列として返す
  • get_defined_functions() - 定義済みの全ての関数を配列で返す
  • get_defined_vars() - 全ての定義済の変数を配列で返す


環境変数の値をひとつ、または全て取得する

  • ≪ get_resources
  • getlastmod ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 環境変数の値をひとつ、または全て取得する

getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — 環境変数の値をひとつ、または全て取得する

説明

getenv(?string $name = null, bool $local_only = false): string|array|false

環境変数の値をひとつ、または全て取得します。

phpinfo() を使えば、すべての環境変数の一覧を見ることができます。 これらの変数の多くは、 » RFC 3875 の section 4.1, "Request Meta-Variables" に挙げられているものです。

パラメータ

name

変数の名前を文字列で指定します。null も指定できます。

local_only

true に設定すると、(OS または putenv により設定された) ローカルの環境変数のみを返します。 これは、name に文字列を指定した場合にのみ有効です。

戻り値

name に対応する環境変数の値を返します。 環境変数 name が存在しない場合は false を返します。 name が null の場合、 すべての環境変数を連想配列で返します。

変更履歴

バージョン | 説明
8.0.0 | name は、nullable になりました。
7.1.0 | name は、すべての環境変数の連想配列を取得するために 省略することができるようになりました。
7.0.9 | local_only パラメーターが追加されました。

例

例1 getenv() の例

<?php
// getenv() の使用例
$ip = getenv('REMOTE_ADDR');

// または単純にスーパーグローバル（$_SERVER または $_ENV）を使用します
$ip = $_SERVER['REMOTE_ADDR'];

// SAPI により設定されたか、または putenv により変更されたかどうかを無視して
// 環境変数の値を安全に取得します。
$ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
?>

注意

警告

PHP が Fast CGI のような SAPI で実行中の場合、 同じ名前のローカル環境変数を設定するために putenv() が使用されても、 この関数は SAPI により設定された環境変数の値を常に返します。 ローカル設定された環境変数の値を返すには、 local_only パラメーターを使用してください。

参考

  • putenv() - 環境変数の値を設定する
  • apache_getenv() - Apache の subprocess_env 変数を取得する
  • スーパーグローバル


最終更新時刻を取得する

  • ≪ getenv
  • getmygid ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 最終更新時刻を取得する

getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — 最終更新時刻を取得する

説明

getlastmod(): int|false

実行中のスクリプト本体の最終更新時刻を取得します。

別のファイルの最終更新時刻が知りたい場合は、 filemtime() を使用してください。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のページの最終更新時刻を返します。 この値は Unix のタイムスタンプで、そのまま date() に渡す事ができます。エラーの場合は false を返します。

例

例1 getlastmod() の例

<?php
// たとえば、'最終更新時刻：March 04 1998 20:43:59.' を出力します
echo "最終更新時刻: " . date ("F d Y H:i:s.", getlastmod());
?>

参考

  • date() - Unixタイムスタンプを書式化する
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmygid() - PHP スクリプトの所有者の GID を得る
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • filemtime() - ファイルの更新時刻を取得する


PHP スクリプトの所有者の GID を得る

  • ≪ getlastmod
  • getmyinode ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP スクリプトの所有者の GID を得る

getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — PHP スクリプトの所有者の GID を得る

説明

getmygid(): int|false

現在のスクリプトのグループ ID を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のスクリプトのグループ ID を返します。またはエラー時に false を返します。

参考

  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する


現在のスクリプトの inode を取得する

  • ≪ getmygid
  • getmypid ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のスクリプトの inode を取得する

getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — 現在のスクリプトの inode を取得する

説明

getmyinode(): int|false

現在のスクリプトの inode を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のスクリプトの inode を表す整数値、あるいはエラーの場合は false を返します。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getlastmod() - 最終更新時刻を取得する


PHP のプロセス ID を取得する

  • ≪ getmyinode
  • getmyuid ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP のプロセス ID を取得する

getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — PHP のプロセス ID を取得する

説明

getmypid(): int|false

現在の PHP プロセスの ID を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の PHP のプロセス ID を返し、エラーの場合は false を返します。

注意

警告

プロセス ID は一意ではなく、エントロピ源として優れたものではありません。 セキュリティが問題となる状況では、PID に頼らないようにしましょう。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する


PHP スクリプト所有者のユーザー ID を取得する

  • ≪ getmypid
  • getopt ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP スクリプト所有者のユーザー ID を取得する

getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — PHP スクリプト所有者のユーザー ID を取得する

説明

getmyuid(): int|false

現在のスクリプトのユーザー ID を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のスクリプトのユーザー ID を返し、エラーの場合は false を返します。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する


コマンドライン引数のリストからオプションを取得する

  • ≪ getmyuid
  • getrusage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • コマンドライン引数のリストからオプションを取得する

getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — コマンドライン引数のリストからオプションを取得する

説明

getopt(string $short_options, array $long_options = [], int &$rest_index = null): array|false

スクリプトに渡されたオプションをパースします。

パラメータ

short_options
この文字列の各文字をオプション文字として使用し、 スクリプトにハイフンひとつ (-) で始まるオプションとして渡された内容とマッチさせます。 たとえば、オプション文字列 "x" は -x というオプションを認識します。 a-z、A-Z および 0-9 のみを認識します。
long_options
オプションの配列。 この配列の各要素をオプション文字列として使用し、 スクリプトにハイフンふたつ (--) で始まるオプションとして渡された内容とマッチさせます。 たとえば、longopts の要素 "opt" は --opt というオプションを認識します。
rest_index
rest_index パラメータが与えられると、 引数のパースを止めた時点のインデックスがこの変数に書き込まれます。

short_options パラメータに含まれる要素には次のようなものがあります。

  • 単一の文字 (値を受け付けない)
  • 文字の後にコロンをひとつ続けたもの (値が必須であるパラメータ)
  • 文字の後にコロンをふたつ続けたもの (値がオプションであるパラメータ)
オプションの値は、文字列の後の最初の引数となります。 値が必須の場合、その前に空白があるかどうかは関係ありません。

注意: オプションの値で、" " (空白) を区切り文字として使用することはできません。

long_options パラメータに含まれる要素には次のようなものがあります。

  • 文字列 (値を受け付けない)
  • 文字列の後にコロンをひとつ続けたもの (値が必須であるパラメータ)
  • 文字列の後にコロンをふたつ続けたもの (値がオプションであるパラメータ)

注意:

short_options と long_options の書式はほぼ同じです。唯一の違いは、 long_options はオプションの配列 (その各要素がオプションとなる) を受け取るけれども short_options は文字列 (その各文字がオプションとなる) を受け取るということです。

戻り値

この関数はオプション/引数のペアを連想配列で返します。 失敗した場合に false を返します。

注意:

オプション以外のものが見つかった時点でオプションのパースは終了し、 それ以降の内容は破棄されます。

変更履歴

バージョン | 説明
7.1.0 | rest_index パラメータが追加されました。

例

例1 getopt() の例：基本編

<?php
// スクリプト example.php
$options = getopt("f:hp:");
var_dump($options);
?>
shell> php example.php -fvalue -h

上の例の出力は以下となります。

array(2) {
  ["f"]=>
  string(5) "value"
  ["h"]=>
  bool(false)
}

例2 getopt() の例：長いオプション

<?php
// スクリプト example.php
$shortopts = "";
$shortopts .= "f:"; // 値が必須
$shortopts .= "v::"; // 値がオプション
$shortopts .= "abc"; // これらのオプションは値を受け取りません

$longopts = array(
"required:", // 値が必須
"optional::", // 値がオプション
"option", // 値なし
"opt", // 値なし
);
$options = getopt($shortopts, $longopts);
var_dump($options);
?>
shell> php example.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() の例：複数のオプションを一度に渡す

<?php
// スクリプト example.php
$options = getopt("abc");
var_dump($options);
?>
shell> php example.php -aaac

上の例の出力は以下となります。

array(2) {
  ["a"]=>
  array(3) {
    [0]=>
    bool(false)
    [1]=>
    bool(false)
    [2]=>
    bool(false)
  }
  ["c"]=>
  bool(false)
}

例4 getopt() の例: rest_index を使う

<?php
// Script example.php
$rest_index = null;
$opts = getopt('a:b:', [], $rest_index);
$pos_args = array_slice($argv, $rest_index);
var_dump($pos_args);
shell> php example.php -a 1 -b 2 -- test

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(4) "test"
}

参考

  • $argv


現在のリソース使用状況を取得する

  • ≪ getopt
  • ini_alter ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のリソース使用状況を取得する

getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — 現在のリソース使用状況を取得する

説明

getrusage(int $mode = 0): array|false

この関数は、getrusage(2) へのインターフェイスです。 システムコールから返されたデータを含む連想配列を返します。

パラメータ

mode

mode が 1 の場合、getrusage は RUSAGE_CHILDREN を付けてコールされます。

戻り値

システムコールから返されたデータを含む連想配列を返します。 すべてのエントリは、記述されたフィールド名を用いてアクセス可能です。 失敗時に false を返します。

変更履歴

バージョン | 説明
7.0.0 | この関数は、Windows でサポートされるようになりました。

例

例1 getrusage() の例

<?php
$dat = getrusage();
echo $dat["ru_oublock"]; // ブロック出力操作の回数
echo $dat["ru_inblock"]; // ブロック入力操作の回数
echo $dat["ru_msgsnd"]; // IPC メッセージの送信数
echo $dat["ru_msgrcv"]; // IPC メッセージの受信数
echo $dat["ru_maxrss"]; // RAM 上に存在する仮想ページのサイズ(resident set size) の最大値
echo $dat["ru_ixrss"]; // 共有メモリサイズの合計値
echo $dat["ru_idrss"]; // 非共有データの合計サイズ
echo $dat["ru_minflt"]; // ページの再利用 (ソフトページフォルト)
echo $dat["ru_majflt"]; // ページフォルトの数 (hard page faults)
echo $dat["ru_nsignals"]; // 受信したシグナル
echo $dat["ru_nvcsw"]; // 意図したコンテキストスイッチ
echo $dat["ru_nivcsw"]; // 意図しないコンテキストスイッチ
echo $dat["ru_nswap"]; // スワップの数
echo $dat["ru_utime.tv_usec"]; // 使用するユーザー時間 (マイクロ秒)
echo $dat["ru_utime.tv_sec"]; // 使用するユーザー時間 (秒)
echo $dat["ru_stime.tv_usec"]; // 使用するシステム時間 (マイクロ秒)
echo $dat["ru_stime.tv_sec"]; // 使用するシステム時間 (秒)
?>

注意

注意:

Windows では、getrusage() は以下のメンバーしか帰しません。

  • "ru_stime.tv_sec"
  • "ru_stime.tv_usec"
  • "ru_utime.tv_sec"
  • "ru_utime.tv_usec"
  • "ru_majflt" (mode が RUSAGE_SELF である場合のみ)
  • "ru_maxrss" (mode が RUSAGE_SELF である場合のみ)

getrusage() を呼び出す際に mode に 1 (RUSAGE_CHILDREN) を指定すると、 各スレッドのリソース使用状況を収集します (つまり、内部的には RUSAGE_THREAD を指定してこの関数が呼ばれるということです)。

注意:

BeOS 2000 では、以下のメンバーしか返しません。

  • "ru_stime.tv_sec"
  • "ru_stime.tv_usec"
  • "ru_utime.tv_sec"
  • "ru_utime.tv_usec"

参考

  • getrusage(2) についてのシステムの man ページ


ini_set のエイリアス

  • ≪ getrusage
  • ini_get ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ini_set のエイリアス

ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — ini_set() のエイリアス

説明

この関数は次の関数のエイリアスです。 ini_set().


設定オプションの値を得る

  • ≪ ini_alter
  • ini_get_all ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 設定オプションの値を得る

ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — 設定オプションの値を得る

説明

ini_get(string $option): string|false

成功時に、設定オプションの値を返します。

パラメータ

option

設定オプションの名前。

戻り値

成功した場合に設定オプションの値、 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 = ' . (int) ini_get('register_globals') . "\n";
echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
echo 'post_max_size + 1 = ' . (rtrim(ini_get('post_max_size'), 'KMG') + 1) . "\n";
echo 'post_max_size in bytes = ' . return_bytes(ini_get('post_max_size'));

function return_bytes($val)
{
$val = trim($val);
$num = (int) rtrim($val, 'KMG');
$last = strtolower($val[strlen($val) - 1]);

switch ($last) {
// 'G' も使えます
case 'g':
$num = $num * 1024 * 1024 * 1024;
break;
case 'm':
$num = $num * 1024 * 1024;
break;
case 'k':
$num *= 1024;
break;
}

return $num;
}

?>

上の例の出力は、 たとえば以下のようになります。

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_get() は、"配列" 形式の ini オプション (pdo.dsn.* など) を読むことができません。この場合は false を返します。

参考

  • get_cfg_var() - PHP 設定オプションの値を取得する
  • ini_get_all() - すべての設定オプションを得る
  • ini_restore() - 設定オプションの値を元に戻す
  • ini_set() - 設定オプションの値を設定する


すべての設定オプションを得る

  • ≪ ini_get
  • ini_parse_quantity ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • すべての設定オプションを得る

ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — すべての設定オプションを得る

説明

ini_get_all(?string $extension = null, bool $details = true): array|false

すべての登録済み設定オプションを返します。

パラメータ

extension

オプションで指定する拡張モジュール名。 この値が null でない場合、 または 文字列 core を指定した場合、 その拡張モジュールに関するオプションのみを返します。

details

詳細な設定を取得するか、あるいは各設定の現在の値のみを取得するか。 デフォルトは true (詳細情報を取得する) です。

戻り値

ディレクティブ名をキーとする連想配列を返します。 extension が存在しない場合は、 false を返し、E_WARNING レベルの警告を発生させます。

details が true (デフォルト) の場合、 配列の値は、 global_value (php.iniで設定されている)、 local_value (おそらくini_set()または .htaccessでセットされている)、access (アクセスレベル) を含む配列となります。

details が false の場合、 配列の値はそのオプションの現在の値となります。

アクセスレベルの意味についてはマニュアルを参照ください。

注意:

ひとつのディレクティブに複数のアクセスレベルを設定することができます。 access がビットマスク値となっているのはそのためです。

例

例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_all() は、"配列" 形式の ini オプション (pdo.dsn.* など) を無視します。

参考

  • 設定を変更するには
  • ini_get() - 設定オプションの値を得る
  • ini_restore() - 設定オプションの値を元に戻す
  • ini_set() - 設定オプションの値を設定する
  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • phpinfo() - PHP の設定情報を出力する
  • ReflectionExtension::getINIEntries() - 拡張モジュールの ini エントリを取得する


ini ディレクティブの省略形を解釈し、サイズを取得する

  • ≪ ini_get_all
  • ini_restore ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ini ディレクティブの省略形を解釈し、サイズを取得する

ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — ini ディレクティブの省略形を解釈し、サイズを取得する

説明

ini_parse_quantity(string $shorthand): int

成功した場合に、 ini ディレクティブの省略形 を解釈したサイズをバイト単位で返します。

パラメータ

shorthand

パースする ini ディレクティブの省略形。 数値を指定しなければなりません。そのあとに、オプションの倍率を続けます。 サポートされている倍率は以下のとおりです: k/K (1024), m/M (1048576), g/G (1073741824)。 数値は10進数、16進数(数値の前に 0x,0X を付けた場合)、 8進数(数値の前に 0o, 0O, 0 を付けた場合)、 2進数(数値の前に 0b, 0B を付けた場合) を指定できます。

戻り値

解釈済みのサイズをバイト単位で、整数として返します。

エラー / 例外

値をパースできなかった場合や、 不正な倍率を使った場合には、E_WARNING が発生します。

例

例1 ini_parse_quantity() の例

<?php

var_dump(ini_parse_quantity('1024'));
var_dump(ini_parse_quantity('1024M'));
var_dump(ini_parse_quantity('512K'));
var_dump(ini_parse_quantity('0xFFk'));
var_dump(ini_parse_quantity('0b1010k'));
var_dump(ini_parse_quantity('0o1024'));
var_dump(ini_parse_quantity('01024'));
var_dump(ini_parse_quantity('Foobar'));
var_dump(ini_parse_quantity('10F'));

?>

上の例の出力は、 たとえば以下のようになります。

int(1024)
int(1073741824)
int(524288)
int(261120)
int(10240)
int(532)
int(532)

Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
int(0)

Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
int(10)

参考

  • ini_get() - 設定オプションの値を得る


設定オプションの値を元に戻す

  • ≪ ini_parse_quantity
  • ini_set ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 設定オプションの値を元に戻す

ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — 設定オプションの値を元に戻す

説明

ini_restore(string $option): void

指定した設定オプションを元の値に戻します。

パラメータ

option

設定オプションの名前。

戻り値

値を返しません。

例

例1 ini_restore() の例

<?php
$setting = 'html_errors';

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 'html_errors': 1
New value for 'html_errors': 0
Original value for 'html_errors': 1

参考

  • ini_get() - 設定オプションの値を得る
  • ini_get_all() - すべての設定オプションを得る
  • ini_set() - 設定オプションの値を設定する


設定オプションの値を設定する

  • ≪ ini_restore
  • memory_get_peak_usage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 設定オプションの値を設定する

ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — 設定オプションの値を設定する

説明

ini_set(string $option, string|int|float|bool|null $value): string|false

指定した設定オプションの値を設定します。 設定オプションは、スクリプトの実行中は新しい値を保持し、 スクリプト終了時に元の値へ戻されます。

パラメータ

option

全てのオプションが ini_set() を使用して変更することが 可能なわけではありません。有効なオプションの完全な一覧は 付録 を参照ください。

value

オプションの新しい値。

戻り値

成功した場合に元の値、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | value は、 任意のスカラー型を受け入れるようになりました (null を含みます)。 これより前のバージョンでは、文字列のみを受け入れていました。

例

例1 ini オプションの設定

<?php
echo ini_get('display_errors');

if (!ini_get('display_errors')) {
ini_set('display_errors', '1');
}

echo ini_get('display_errors');
?>

参考

  • get_cfg_var() - PHP 設定オプションの値を取得する
  • ini_get() - 設定オプションの値を得る
  • ini_get_all() - すべての設定オプションを得る
  • ini_restore() - 設定オプションの値を元に戻す
  • 設定を変更するには


PHP によって割り当てられたメモリの最大値を返す

  • ≪ ini_set
  • memory_get_usage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP によって割り当てられたメモリの最大値を返す

memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す

説明

memory_get_peak_usage(bool $real_usage = false): int

PHP スクリプトに割り当てられたメモリの最大値を、バイト単位で返します。

パラメータ

real_usage

これを true に設定すると、システムが割り当てた実際のメモリの大きさを取得します。 省略したり false を設定したりすると、 emalloc() が使用するメモリのみを報告します。

戻り値

メモリの最大値をバイト数で返します。

参考

  • memory_get_usage() - PHP に割り当てられたメモリの量を返す
  • memory_reset_peak_usage() - メモリの最大値をリセットする
  • memory_limit


PHP に割り当てられたメモリの量を返す

  • ≪ memory_get_peak_usage
  • memory_reset_peak_usage ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP に割り当てられたメモリの量を返す

memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — PHP に割り当てられたメモリの量を返す

説明

memory_get_usage(bool $real_usage = false): int

現在の PHP スクリプトに割り当てられたメモリの量をバイト単位で返します。

パラメータ

real_usage

これを true に設定すると、システムが割り当てた実際のメモリの大きさ (未使用のページも含むもの) を取得します。 省略したり false を設定したりすると、使用したメモリのみを報告します。

注意:

PHP は、emalloc() が割り当てたメモリ以外のメモリは追跡しません。

戻り値

メモリの量をバイト単位で返します。

例

例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

?>

参考

  • memory_get_peak_usage() - PHP によって割り当てられたメモリの最大値を返す
  • memory_limit


メモリの最大値をリセットする

  • ≪ memory_get_usage
  • php_ini_loaded_file ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • メモリの最大値をリセットする

memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — メモリの最大値をリセットする

説明

memory_reset_peak_usage(): void

memory_get_peak_usage() が返したメモリの最大値をリセットします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 memory_reset_peak_usage() の例

<?php

var_dump(memory_get_peak_usage());

$a = str_repeat("Hello", 424242);
var_dump(memory_get_peak_usage());

unset($a);
memory_reset_peak_usage();

$a = str_repeat("Hello", 2424);
var_dump(memory_get_peak_usage());

?>

上の例の出力は、 たとえば以下のようになります。

int(422440)
int(2508672)
int(399208)

参考

  • memory_get_peak_usage() - PHP によって割り当てられたメモリの最大値を返す


読み込まれた php.ini ファイルのパスを取得する

  • ≪ memory_reset_peak_usage
  • php_ini_scanned_files ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 読み込まれた php.ini ファイルのパスを取得する

php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する

説明

php_ini_loaded_file(): string|false

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() - 追加の ini ディレクトリにある .ini ファイルのリストを取得する
  • phpinfo() - PHP の設定情報を出力する
  • 設定ファイル


追加の ini ディレクトリにある .ini ファイルのリストを取得する

  • ≪ php_ini_loaded_file
  • php_sapi_name ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 追加の ini ディレクトリにある .ini ファイルのリストを取得する

php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する

説明

php_ini_scanned_files(): string|false

php_ini_scanned_files()は、php.iniをパースした 後で、設定ファイルのリストをカンマ区切りで返します。 ファイルを探すディレクトリは、コンパイル時のオプションで指定します。 また、実行時に環境変数で指定することもできます。詳細は インストールガイド を参照ください。

戻り値のファイル名は、フルパス形式となります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功すると、.iniファイルをカンマ区切りにした文字列が返されます。 --with-config-file-scan-dir がセットされておらず、かつ環境変数 PHP_INI_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";
}
}
}
?>

参考

  • ini_set() - 設定オプションの値を設定する
  • phpinfo() - PHP の設定情報を出力する
  • php_ini_loaded_file() - 読み込まれた php.ini ファイルのパスを取得する


ウェブサーバーと PHP の間のインターフェイスの型を返す

  • ≪ php_ini_scanned_files
  • php_uname ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ウェブサーバーと PHP の間のインターフェイスの型を返す

php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — ウェブサーバーと PHP の間のインターフェイスの型を返す

説明

php_sapi_name(): string|false

PHP が使用しているインターフェイス (サーバー API、SAPI) の型を小文字の文字列で返します。たとえば、CLI 版の PHP ではこの文字列は "cli" となります。Apache と組み合わせて使用している場合は、 実際に使用している SAPI によってさまざまな結果となります。 返されうる値の一覧を以下にあげます。

パラメータ

この関数にはパラメータはありません。

戻り値

インターフェイスの型を小文字の文字列で返します。 失敗した場合に false を返します

これがすべてではありませんが、以下のような値が返されます。 apache, apache2handler, cgi (PHP 5.3 まで), cgi-fcgi, cli, cli-server, embed, fpm-fcgi, litespeed, phpdbg

例

例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 と定義されることもあります。

参考

  • PHP_SAPI


PHP が稼動しているオペレーティングシステムに関する情報を返す

  • ≪ php_sapi_name
  • phpcredits ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP が稼動しているオペレーティングシステムに関する情報を返す

php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — PHP が稼動しているオペレーティングシステムに関する情報を返す

説明

php_uname(string $mode = "a"): string

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 の設定情報を出力する


PHP に関するクレジットを出力する

  • ≪ php_uname
  • phpinfo ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP に関するクレジットを出力する

phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — PHP に関するクレジットを出力する

説明

phpcredits(int $flags = CREDITS_ALL): true

この関数は、PHP 開発者、モジュール等のリストを有するクレジットを出力します。 ページに情報を挿入するために、適切な HTML コードが生成されます。

パラメータ

flags

独自のクレジットページを出力したい場合に flags を利用するとよいでしょう。

定義済みの 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 を返します。

例

例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>

注意

注意:

phpcredits() を CLI モードで使うと、 HTML ではなくプレーンテキスト形式で出力します。

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • phpinfo() - PHP の設定情報を出力する


PHP の設定情報を出力する

  • ≪ phpcredits
  • phpversion ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • PHP の設定情報を出力する

phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — PHP の設定情報を出力する

説明

phpinfo(int $flags = INFO_ALL): true

現在の PHP の状態に関する、多くの情報を出力します。出力される情報には、 PHP コンパイルオプションと拡張モジュール、PHP のバージョン、 サーバー情報と環境（モジュールとしてコンパイルされた場合）、 PHP の環境、OS バージョン情報、パス、構成オプションのマスター およびローカルの値、HTTP ヘッダ、PHP License などがあります。

システムの設定はそれぞれ違うため、実行時設定 や 利用できる 定義済みの変数 を調べるために phpinfo() がよく使われます。

また、phpinfo() には EGPCS (Environment, GET, POST, Cookie, Server) の情報が含まれているため、デバッグツールとしても便利です。

パラメータ

flags

以下にあるconstantsビット値をひとつまたは 複数個を加算して、オプションのflags引数に 渡すことによって出力をカスタマイズできます。 それぞれの定数やビット値を ビット和演算子 で結んで渡すこともできます。

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 を返します。

例

例1 phpinfo() の例

<?php

// すべての情報を表示します。デフォルトは INFO_ALL です。
phpinfo();

// モジュール情報だけを表示します。
// phpinfo(8) としても同じです。
phpinfo(INFO_MODULES);

?>

注意

注意:

PHP 5.5 より前のバージョンでは、 expose_php が off の場合、一部の情報は表示されません。 これにはPHPとZendのロゴ、そしてクレジットが含まれます。

注意:

CLI モードを利用している場合、phpinfo() は HTML ではなくプレーンテキストで結果を出力します。

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • phpcredits() - PHP に関するクレジットを出力する
  • ini_get() - 設定オプションの値を得る
  • ini_set() - 設定オプションの値を設定する
  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • 定義済みの変数


現在の PHP バージョンを取得する

  • ≪ phpinfo
  • putenv ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の PHP バージョンを取得する

phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — 現在の PHP バージョンを取得する

説明

phpversion(?string $extension = null): string|false

現在動作中の PHP パーサあるいは拡張モジュールのバージョンを表す文字列を返します。

パラメータ

extension

オプションで指定する拡張モジュール名。

戻り値

現在の PHP のバージョンを文字列で返します。 オプションの extension パラメータが文字列で指定されている場合、phpversion() はその拡張モジュールのバージョンを返します。 関連するバージョン情報が存在しない場合、 あるいは拡張モジュールが有効でない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | extension は、nullable になりました。

例

例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_* で取得可能です。

注意:

拡張モジュールによっては、独自のバージョン番号を定義しているものがありますが、 PHP にバンドルされているほとんどの拡張モジュールは、PHP のバージョンをそれらのバージョン番号として使っています。

参考

  • PHP_VERSION 定数
  • version_compare() - ふたつの "PHP 標準" バージョン番号文字列を比較する
  • phpinfo() - PHP の設定情報を出力する
  • phpcredits() - PHP に関するクレジットを出力する
  • zend_version() - 現在の Zend Engine のバージョンを取得する


環境変数の値を設定する

  • ≪ phpversion
  • restore_include_path ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 環境変数の値を設定する

putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — 環境変数の値を設定する

説明

putenv(string $assignment): bool

サーバーの環境変数に assignment を追加します。 この環境変数は、カレントのリクエストを実行している間のみ存在します。 リクエスト終了時、環境変数は元の状態に戻されます。

パラメータ

assignment

"FOO=BAR" 形式の設定。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 環境変数の設定

<?php
putenv("UNIQID=$uniqid");
?>

参考

  • getenv() - 環境変数の値をひとつ、または全て取得する
  • apache_setenv() - Apacheサブプロセスの環境変数を設定する


include_path 設定オプションの値を元に戻す

  • ≪ putenv
  • set_include_path ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • include_path 設定オプションの値を元に戻す

restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — include_path 設定オプションの値を元に戻す

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

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

restore_include_path();

// または ini_restore を使用します
ini_restore('include_path');

echo get_include_path(); // .:/usr/local/lib/php

?>

参考

  • ini_restore() - 設定オプションの値を元に戻す
  • get_include_path() - 現在の include_path 設定オプションを取得する
  • set_include_path() - include_path 設定オプションをセットする
  • include - include


include_path 設定オプションをセットする

  • ≪ restore_include_path
  • set_time_limit ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • include_path 設定オプションをセットする

set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — include_path 設定オプションをセットする

説明

set_include_path(string $include_path): string|false

include_path 設定オプションの値を、このスクリプト内でだけ変更します。

パラメータ

include_path

include_path の新しい値。

戻り値

成功した場合に元の include_path の値、失敗した場合に false を返します。

例

例1 set_include_path() の例

<?php
set_include_path('/usr/lib/pear');

// または ini_set を使用します
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);
?>

参考

  • ini_set() - 設定オプションの値を設定する
  • get_include_path() - 現在の include_path 設定オプションを取得する
  • restore_include_path() - include_path 設定オプションの値を元に戻す
  • include - include


実行時間の最大値を制限する

  • ≪ set_include_path
  • sys_get_temp_dir ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 実行時間の最大値を制限する

set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — 実行時間の最大値を制限する

説明

set_time_limit(int $seconds): bool

スクリプトが実行可能な秒数を設定します。 この制限にかかるとスクリプトは致命的エラーを返します。 デフォルトの制限値は 30 秒です。 なお、php.iniでmax_execution_timeの 値が定義されている場合にはそれを用います。

この関数がコールされた場合、 タイムアウトカウンタをゼロから再スタートします。 言いかえると、タイムアウトがデフォルトの 30 秒で スクリプト実行までに 25 秒かかる場合に、 set_time_limit(20) を実行すると、スクリプトは、 タイムアウトまでに全体で 45秒 の間実行されます。

パラメータ

seconds

最大実行時間を表す秒数。ゼロを設定すると、時間制限を行いません。

戻り値

成功した場合に true、失敗した場合に false を返します。

注意

注意:

関数 set_time_limit() と設定ディレクティブ max_execution_time は、 このスクリプト自体の実行時間にのみ影響を与えます。 system() を用いたシステムコール、ストリーム操作、 データベースクエリ等のスクリプト実行以外で発生する処理にかかった時間は スクリプトが実行される最大時間を定義する際には含まれません。 ただし、Windows ではこれは当てはまりません。 計測された時間は実際の時間と等しくなります。

参考

  • max_execution_time
  • max_input_time


一時ファイル用に使用されるディレクトリのパスを返す

  • ≪ set_time_limit
  • version_compare ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 一時ファイル用に使用されるディレクトリのパスを返す

sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す

説明

sys_get_temp_dir(): string

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() - 一意なファイル名を生成する


ふたつの "PHP 標準" バージョン番号文字列を比較する

  • ≪ sys_get_temp_dir
  • zend_thread_id ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • ふたつの "PHP 標準" バージョン番号文字列を比較する

version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する

説明

version_compare(string $version1, string $version2, ?string $operator = null): int|bool

version_compare()は、ふたつの "PHP 標準" バージョン 番号文字列を比較します。

この関数はまず、バージョン文字列の _, -, + をドット . で置き換えます。 さらに、数値でない部分の前後にドット . を追加します。 例えば '4.3.2RC1' は '4.3.2.RC.1' となります。 次に、左から右へ 各部分を比較していきます。特殊な文字列が含まれている場合は以下の順で 並べ替えます: ここにないすべての文字列 < dev < alpha = a < beta = b < RC = rc < # < pl = p この方法により、'4.1' と '4.1.2' のようなバージョンの違いだけではなく PHP 固有の開発ステータスの違いも判断することが可能となります。

パラメータ

version1

最初のバージョン番号。

version2

ふたつめのバージョン番号。

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, '7.0.0') >= 0) {
echo '7.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 '5.0.0 より新しいバージョンの PHP を使っています。バージョンは ' . 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) より小さいとみなされます。

注意:

alpha や beta のようなバージョン文字列は、大文字小文字を区別します。 したがって、どこかから取得したバージョン文字列を PHP の標準に従わせるなら、 まず strtolower() で小文字化してから version_compare() を呼ぶ必要があります。

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • php_uname() - PHP が稼動しているオペレーティングシステムに関する情報を返す
  • function_exists() - 指定した関数が定義されている場合に true を返す


現在のスレッドの一意な ID を返す

  • ≪ version_compare
  • zend_version ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在のスレッドの一意な ID を返す

zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — 現在のスレッドの一意な ID を返す

説明

zend_thread_id(): int

この関数は、現在のスレッドの一意な 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 Engine のバージョンを取得する

  • ≪ zend_thread_id
  • phpdbg ≫
  • PHP Manual
  • PHP オプション/情報 関数
  • 現在の Zend Engine のバージョンを取得する

zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — 現在の Zend Engine のバージョンを取得する

説明

zend_version(): string

現在実行中の Zend Engine のバージョンを含む文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Zend Engine のバージョン番号を文字列で返します。

例

例1 zend_version() の例

<?php
echo "Zend engine version: " . zend_version();
?>

上の例の出力は、 たとえば以下のようになります。

Zend engine version: 2.2.0

参考

  • phpinfo() - PHP の設定情報を出力する
  • phpcredits() - PHP に関するクレジットを出力する
  • phpversion() - 現在の PHP バージョンを取得する


対話的な PHP デバッガ

  • はじめに
  • インストール/設定
    • 実行時設定
  • 定義済み定数
  • phpdbg 関数
    • phpdbg_break_file — ファイルの行にブレークポイントを挿入する
    • phpdbg_break_function — 関数のエントリにブレークポイントを挿入する
    • phpdbg_break_method — メソッドのエントリにブレークポイントを挿入する
    • phpdbg_break_next — 次のオペコードにブレークポイントを挿入します
    • phpdbg_clear — 全てのブレークポイントをクリアする
    • phpdbg_color — 特定の要素に色を設定する
    • phpdbg_end_oplog — 説明
    • phpdbg_exec — 実行コンテクストの設定を試みる
    • phpdbg_get_executable — 説明
    • phpdbg_prompt — コマンドのプロンプトを設定する
    • phpdbg_start_oplog — 説明


はじめに

phpdbg は SAPIモジュール として実装されており、 コードのパフォーマンスや機能に影響を与えずに実行環境を完全に制御できます。

phpdbg は、軽量、強力かつ、使いやすい PHP のデバッガ環境になることを目標としています。 提供する機能は次の通りです:

  • ステップスルーデバッグが可能
  • 柔軟なブレークポイント設定が可能 (クラスのメソッド、関数、ファイルの行単位、アドレス、Opcode単位)
  • ビルトインの eval() を使って PHP に簡単にアクセスできます
  • ユーザーランドで使える API
  • SAPI に関係なく、簡単に統合できます
  • PHP の設定ファイルをサポート
  • スーパーグローバルを実行時に設定 - 自分の値が設定できます !!
  • オプションの readline サポート - ターミナルを気持ちよく操作できます
  • 使いやすい操作 - Help を参照してね :)

コマンドラインオプション
オプション | 引数の例 | 説明
-c | -c/my/php.ini | 読み込む php.ini ファイルを指定します。
-d | -dmemory_limit=4G | php.ini ディレクティブを指定します。
-n |  | デフォルトの php.ini を無効にします。
-q |  | welcome バナーを非表示にします。
-v |  | oplog 出力を有効にします。
-b |  | 色付きの出力を無効にします。
-i | -imy.init | .phpdbginit ファイルを設定します。
-I |  | デフォルトの .phpdbginit ファイルを無視します。
-O | -Omy.oplog | oplog の出力先ファイルを設定します。
-r |  | 実行コンテキストを実行します。
-rr |  | 実行コンテキストを実行し、 実行後は (ブレークポイントを考慮せず) 終了します。
-e |  | デバッガ/プロファイラのための拡張情報を生成します。
-E |  | eval されたコードのステップスルー実行を有効にします。使用する時は注意！
-s | -s=, -s=foo | オプションのデリミタを使って、 標準入力から入力されたコードを読み取り、実行します。
-S | -Scli | SAPI 名を上書きします。使用する時は注意！
-l | -l4000 | リモートのコンソールのポートを設定します。
-a | -a192.168.0.3 | リモートのコンソールにバインドするアドレスを設定します。
-x |  | (通常のテキストではなく) xml 出力を有効にします。
-p | -p, -p=func, -p* | opcode を出力して終了します。
-h |  | ヘルプの概要を出力します。
-V |  | バージョン番号を出力します。
-- | -- arg1 arg2 | phpdbg への引数と php への $argv を区切るために使います。 -- の後に、任意の $argv を追加できます。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • phpdbg
  • インストール/設定

インストール/設定

目次

  • 実行時設定


実行時設定

php.ini の設定により動作が変化します。

phpdbg 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
phpdbg.eol | 2 | INI_ALL | PHP 8.1.0 で削除されました。
phpdbg.path |  | 6 | PHP 8.1.0 で削除されました。

以下に設定ディレクティブに関する 簡単な説明を示します。

phpdbg.eol mixed

出力に用いる、行末文字の種類。 この値を設定するには、以下に示す文字列のエイリアスを使う必要があります。

数値型の値 | 文字列エイリアス
0 | CRLF, crlf, DOS, dos
1 | LF, lf, UNIX, unix
2 | CR, cr, MAC, mac

phpdbg.path string


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PHPDBG_VERSION (string)
PHPDBG_FILE (int)
PHP 7.3.0 で削除されました。
PHPDBG_METHOD (int)
PHP 7.3.0 で削除されました。
PHPDBG_LINENO (int)
PHP 7.3.0 で削除されました。
PHPDBG_FUNC (int)
PHP 7.3.0 で削除されました。


phpdbg 関数

目次

  • phpdbg_break_file — ファイルの行にブレークポイントを挿入する
  • phpdbg_break_function — 関数のエントリにブレークポイントを挿入する
  • phpdbg_break_method — メソッドのエントリにブレークポイントを挿入する
  • phpdbg_break_next — 次のオペコードにブレークポイントを挿入します
  • phpdbg_clear — 全てのブレークポイントをクリアする
  • phpdbg_color — 特定の要素に色を設定する
  • phpdbg_end_oplog — 説明
  • phpdbg_exec — 実行コンテクストの設定を試みる
  • phpdbg_get_executable — 説明
  • phpdbg_prompt — コマンドのプロンプトを設定する
  • phpdbg_start_oplog — 説明


ファイルの行にブレークポイントを挿入する

  • ≪ phpdbg 関数
  • phpdbg_break_function ≫
  • PHP Manual
  • phpdbg 関数
  • ファイルの行にブレークポイントを挿入する

phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — ファイルの行にブレークポイントを挿入する

説明

phpdbg_break_file(string $file, int $line): void

指定された file の 指定された line にブレークポイントを挿入します。

パラメータ

file

ファイル名

line

行番号

戻り値

値を返しません。

参考

  • phpdbg_break_function() - 関数のエントリにブレークポイントを挿入する
  • phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
  • phpdbg_break_next() - 次のオペコードにブレークポイントを挿入します
  • phpdbg_clear() - 全てのブレークポイントをクリアする


関数のエントリにブレークポイントを挿入する

  • ≪ phpdbg_break_file
  • phpdbg_break_method ≫
  • PHP Manual
  • phpdbg 関数
  • 関数のエントリにブレークポイントを挿入する

phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — 関数のエントリにブレークポイントを挿入する

説明

phpdbg_break_function(string $function): void

指定された function のエントリにブレークポイントを挿入します。

パラメータ

function

関数の名前

戻り値

値を返しません。

参考

  • phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
  • phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
  • phpdbg_break_next() - 次のオペコードにブレークポイントを挿入します
  • phpdbg_clear() - 全てのブレークポイントをクリアする


メソッドのエントリにブレークポイントを挿入する

  • ≪ phpdbg_break_function
  • phpdbg_break_next ≫
  • PHP Manual
  • phpdbg 関数
  • メソッドのエントリにブレークポイントを挿入する

phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — メソッドのエントリにブレークポイントを挿入する

説明

phpdbg_break_method(string $class, string $method): void

指定された class の 指定された method にブレークポイントを挿入します。

パラメータ

class

クラスの名前

method

メソッドの名前

戻り値

値を返しません。

参考

  • phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
  • phpdbg_break_function() - 関数のエントリにブレークポイントを挿入する
  • phpdbg_break_next() - 次のオペコードにブレークポイントを挿入します
  • phpdbg_clear() - 全てのブレークポイントをクリアする


次のオペコードにブレークポイントを挿入します

  • ≪ phpdbg_break_method
  • phpdbg_clear ≫
  • PHP Manual
  • phpdbg 関数
  • 次のオペコードにブレークポイントを挿入します

phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — 次のオペコードにブレークポイントを挿入します

説明

phpdbg_break_next(): void

次のオペコードにブレークポイントを挿入します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
  • phpdbg_break_function() - 関数のエントリにブレークポイントを挿入する
  • phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
  • phpdbg_clear() - 全てのブレークポイントをクリアする


全てのブレークポイントをクリアする

  • ≪ phpdbg_break_next
  • phpdbg_color ≫
  • PHP Manual
  • phpdbg 関数
  • 全てのブレークポイントをクリアする

phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — 全てのブレークポイントをクリアする

説明

phpdbg_clear(): void

これまでに設定されたブレークポイントをすべてクリアします。 phpdbg_break_*() 関数や、 コンソールで対話的に設定したブレークポイントが全て含まれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
  • phpdbg_break_function() - 関数のエントリにブレークポイントを挿入する
  • phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
  • phpdbg_break_next() - 次のオペコードにブレークポイントを挿入します


特定の要素に色を設定する

  • ≪ phpdbg_clear
  • phpdbg_end_oplog ≫
  • PHP Manual
  • phpdbg 関数
  • 特定の要素に色を設定する

phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — 特定の要素に色を設定する

説明

phpdbg_color(int $element, string $color): void

指定された element に color を設定します。

パラメータ

element

定数 PHPDBG_COLOR_* のうちのひとつを指定します。

color

色の名前。 white, red, green, yellow, blue, purple, cyan, black のうちのいずれかを指定します。 オプションで、これらの色の後に -bold や -underline を付加できます。 たとえば、 white-bold とか green-underline のようなものです。

戻り値

値を返しません。

参考

  • phpdbg_prompt() - コマンドのプロンプトを設定する


説明

  • ≪ phpdbg_color
  • phpdbg_exec ≫
  • PHP Manual
  • phpdbg 関数
  • 説明

phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog —

説明

phpdbg_end_oplog(array $options = []): ?array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

options

戻り値


実行コンテクストの設定を試みる

  • ≪ phpdbg_end_oplog
  • phpdbg_get_executable ≫
  • PHP Manual
  • phpdbg 関数
  • 実行コンテクストの設定を試みる

phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — 実行コンテクストの設定を試みる

説明

phpdbg_exec(string $context): string|bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

context

戻り値

実行コンテクストが既に設定されていた場合、それを返します。 実行コンテクストが以前設定されたことがない場合、true を返します。 実行コンテクストを設定出来なかった場合、false を返し、 E_WARNING が発生します。


説明

  • ≪ phpdbg_exec
  • phpdbg_prompt ≫
  • PHP Manual
  • phpdbg 関数
  • 説明

phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable —

説明

phpdbg_get_executable(array $options = []): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

options

戻り値


コマンドのプロンプトを設定する

  • ≪ phpdbg_get_executable
  • phpdbg_start_oplog ≫
  • PHP Manual
  • phpdbg 関数
  • コマンドのプロンプトを設定する

phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — コマンドのプロンプトを設定する

説明

phpdbg_prompt(string $string): void

コマンドのプロンプトを、指定された string に設定します。

パラメータ

string

コマンドのプロンプトとして使う文字列。

戻り値

値を返しません。

参考

  • phpdbg_color() - 特定の要素に色を設定する


説明

  • ≪ phpdbg_prompt
  • runkit7 ≫
  • PHP Manual
  • phpdbg 関数
  • 説明

phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog —

説明

phpdbg_start_oplog(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


runkit7

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • runkit7 関数
    • runkit7_constant_add — Similar to define(), but allows defining in class definitions as well
    • runkit7_constant_redefine — Redefine an already defined constant
    • runkit7_constant_remove — Remove/Delete an already defined constant
    • runkit7_function_add — Add a new function, similar to create_function
    • runkit7_function_copy — Copy a function to a new function name
    • runkit7_function_redefine — Replace a function definition with a new implementation
    • runkit7_function_remove — Remove a function definition
    • runkit7_function_rename — Change a function's name
    • runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate
    • runkit7_method_add — Dynamically adds a new method to a given class
    • runkit7_method_copy — Copies a method from class to another
    • runkit7_method_redefine — Dynamically changes the code of the given method
    • runkit7_method_remove — Dynamically removes the given method
    • runkit7_method_rename — Dynamically changes the name of the given method
    • runkit7_object_id — Return the integer object handle for given object
    • runkit7_superglobals — Return numerically indexed array of registered superglobals
    • runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc


はじめに

The runkit7 extension provides means to modify constants, user-defined functions, and user-defined classes. It also provides for custom superglobal variables.

This package is a fork of the » runkit package providing PHP 7 support.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • runkit7
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

Modifying Constants, Functions, Classes, and Methods as well as Custom Superglobals works with all releases of PHP 7. No special requirements are necessary.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/runkit7.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


実行時設定

php.ini の設定により動作が変化します。

Runkit Configuration Options
名前 | デフォルト | 変更可能 | 変更履歴
runkit.superglobal | "" | INI_PERDIR |
runkit.internal_override | "0" | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

runkit.superglobal string
Comma-separated list of variable names to be treated as superglobals. This value should be set in the systemwide php.ini file, but may work in perdir configuration contexts depending on your SAPI.

例1 Custom Superglobals with runkit.superglobal=_FOO,_BAR in php.ini

<?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';

/* Displays foo and bar, but not baz */
show_values();
?>
runkit.internal_override bool
Enables ability to modify/rename/remove internal functions.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RUNKIT7_IMPORT_FUNCTIONS (int)
runkit7_import() flag indicating that normal functions should be imported from the specified file.
RUNKIT7_IMPORT_CLASS_METHODS (int)
runkit7_import() flag indicating that class methods should be imported from the specified file.
RUNKIT7_IMPORT_CLASS_CONSTS (int)
runkit7_import() flag indicating that class constants should be imported from the specified file.
RUNKIT7_IMPORT_CLASS_PROPS (int)
runkit7_import() flag indicating that class standard properties should be imported from the specified file.
RUNKIT7_IMPORT_CLASS_STATIC_PROPS (int)
runkit7_import() flag indicating that class static properties should be imported from the specified file. Available since Runkit 1.0.1.
RUNKIT7_IMPORT_CLASSES (int)
runkit7_import() flag representing a bitwise OR of the RUNKIT7_IMPORT_CLASS_* constants.
RUNKIT7_IMPORT_OVERRIDE (int)
runkit7_import() flag indicating that if any of the imported functions, methods, constants, or properties already exist, they should be replaced with the new definitions. If this flag is not set, then any imported definitions which already exist will be discarded.
RUNKIT7_ACC_RETURN_REFERENCE (int)
Include this flag to make the function or method being created or redeclared return a reference.
RUNKIT7_ACC_PUBLIC (int)
Flag for runkit7_method_add() and runkit7_method_redefine() to make the method public.
RUNKIT7_ACC_PROTECTED (int)
Flag for runkit7_method_add() and runkit7_method_redefine() to make the method protected.
RUNKIT7_ACC_PRIVATE (int)
Flag for runkit7_method_add() and runkit7_method_redefine() to make the method private.
RUNKIT7_ACC_STATIC (int)
Flag for runkit7_method_add() and runkit7_method_redefine() to make the method static.
RUNKIT7_FEATURE_MANIPULATION (int)
Equal to 1 if runtime manipulation is enabled, and 0 otherwise.
RUNKIT7_FEATURE_SUPERGLOBALS (int)
Equal to 1 if custom superglobals are enabled, and 0 otherwise.
RUNKIT7_FEATURE_SANDBOX (int)
Always 0, it's impractical to implement the sandbox feature in php 7.


runkit7 関数

目次

  • runkit7_constant_add — Similar to define(), but allows defining in class definitions as well
  • runkit7_constant_redefine — Redefine an already defined constant
  • runkit7_constant_remove — Remove/Delete an already defined constant
  • runkit7_function_add — Add a new function, similar to create_function
  • runkit7_function_copy — Copy a function to a new function name
  • runkit7_function_redefine — Replace a function definition with a new implementation
  • runkit7_function_remove — Remove a function definition
  • runkit7_function_rename — Change a function's name
  • runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate
  • runkit7_method_add — Dynamically adds a new method to a given class
  • runkit7_method_copy — Copies a method from class to another
  • runkit7_method_redefine — Dynamically changes the code of the given method
  • runkit7_method_remove — Dynamically removes the given method
  • runkit7_method_rename — Dynamically changes the name of the given method
  • runkit7_object_id — Return the integer object handle for given object
  • runkit7_superglobals — Return numerically indexed array of registered superglobals
  • runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc


Similar to define(), but allows defining in class definitions as well

  • ≪ runkit7 関数
  • runkit7_constant_redefine ≫
  • PHP Manual
  • runkit7 関数
  • Similar to define(), but allows defining in class definitions as well

runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similar to define(), but allows defining in class definitions as well

説明

runkit7_constant_add(string $constant_name, mixed $value, int $newVisibility = ?): bool

パラメータ

constant_name

Name of constant to declare. Either a string to indicate a global constant, or classname::constname to indicate a class constant.

value

NULL, Bool, Long, Double, String, Array, or Resource value to store in the new constant.

newVisibility

Visibility of the constant, for class constants. Public by default. One of the RUNKIT7_ACC_* constants.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • define() - 名前を指定して定数を定義する
  • runkit7_constant_redefine() - Redefine an already defined constant
  • runkit7_constant_remove() - Remove/Delete an already defined constant


Redefine an already defined constant

  • ≪ runkit7_constant_add
  • runkit7_constant_remove ≫
  • PHP Manual
  • runkit7 関数
  • Redefine an already defined constant

runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redefine an already defined constant

説明

runkit7_constant_redefine(string $constant_name, mixed $value, int $new_visibility = ?): bool

パラメータ

constant_name

Constant to redefine. Either the name of a global constant, or classname::constname indicating class constant.

value

Value to assign to the constant.

new_visibility

The new visibility of the constant, for class constants. Unchanged by default. One of the RUNKIT7_ACC_* constants.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • runkit7_constant_add() - Similar to define(), but allows defining in class definitions as well
  • runkit7_constant_remove() - Remove/Delete an already defined constant


Remove/Delete an already defined constant

  • ≪ runkit7_constant_redefine
  • runkit7_function_add ≫
  • PHP Manual
  • runkit7 関数
  • Remove/Delete an already defined constant

runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Remove/Delete an already defined constant

説明

runkit7_constant_remove(string $constant_name): bool

パラメータ

constant_name

Name of the constant to remove. Either the name of a global constant, or classname::constname indicating a class constant.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • define() - 名前を指定して定数を定義する
  • runkit7_constant_add() - Similar to define(), but allows defining in class definitions as well
  • runkit7_constant_redefine() - Redefine an already defined constant


Add a new function, similar to create_function

  • ≪ runkit7_constant_remove
  • runkit7_function_copy ≫
  • PHP Manual
  • runkit7 関数
  • Add a new function, similar to create_function

runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Add a new function, similar to create_function()

説明

runkit7_function_add(
string $function_name,
string $argument_list,
string $code,
bool $return_by_reference = null,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool
runkit7_function_add(
string $function_name,
Closure $closure,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool

パラメータ

function_name

Name of the function to be created

argument_list

Comma separated argument list

code

Code making up the function

closure

A closure that defines the function.

return_by_reference

Whether the function should return by reference.

doc_comment

The doc comment of the function.

return_type

The return type of the function.

is_strict

Whether the function should behave as if it were declared in a file with strict_types=1

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 A runkit7_function_add() example

<?php
runkit7_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

参考

  • create_function() - 文字列のコードを評価し、動的に関数を作成する
  • runkit7_function_redefine() - Replace a function definition with a new implementation
  • runkit7_function_copy() - Copy a function to a new function name
  • runkit7_function_rename() - Change a function's name
  • runkit7_function_remove() - Remove a function definition
  • runkit7_method_add() - Dynamically adds a new method to a given class


Copy a function to a new function name

  • ≪ runkit7_function_add
  • runkit7_function_redefine ≫
  • PHP Manual
  • runkit7 関数
  • Copy a function to a new function name

runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copy a function to a new function name

説明

runkit7_function_copy(string $source_name, string $target_name): bool

パラメータ

source_name

Name of the existing function

target_name

Name of the new function to copy the definition to

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 A runkit7_function_copy() example

<?php
function original() {
echo "In a function\n";
}
runkit7_function_copy('original','duplicate');
original();
duplicate();
?>

上の例の出力は以下となります。

In a function
In a function

参考

  • runkit7_function_add() - Add a new function, similar to create_function
  • runkit7_function_redefine() - Replace a function definition with a new implementation
  • runkit7_function_rename() - Change a function's name
  • runkit7_function_remove() - Remove a function definition


Replace a function definition with a new implementation

  • ≪ runkit7_function_copy
  • runkit7_function_remove ≫
  • PHP Manual
  • runkit7 関数
  • Replace a function definition with a new implementation

runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Replace a function definition with a new implementation

説明

runkit7_function_redefine(
string $function_name,
string $argument_list,
string $code,
bool $return_by_reference = null,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool
runkit7_function_redefine(
string $function_name,
Closure $closure,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

function_name

Name of function to redefine

argument_list

New list of arguments to be accepted by function

code

New code implementation

closure

A closure that defines the function.

return_by_reference

Whether the function should return by reference.

doc_comment

The doc comment of the function.

return_type

The return type of the function.

is_strict

Whether the function behaves as if it was declared in a file with strict_types=1

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 A runkit7_function_redefine() example

<?php
function testme() {
echo "Original Testme Implementation\n";
}
testme();
runkit7_function_redefine('testme','','echo "New Testme Implementation\n";');
testme();
?>

上の例の出力は以下となります。

Original Testme Implementation
New Testme Implementation

参考

  • runkit7_function_add() - Add a new function, similar to create_function
  • runkit7_function_copy() - Copy a function to a new function name
  • runkit7_function_rename() - Change a function's name
  • runkit7_function_remove() - Remove a function definition
  • runkit7_method_redefine() - Dynamically changes the code of the given method


Remove a function definition

  • ≪ runkit7_function_redefine
  • runkit7_function_rename ≫
  • PHP Manual
  • runkit7 関数
  • Remove a function definition

runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Remove a function definition

説明

runkit7_function_remove(string $function_name): bool

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

function_name

Name of the function to be deleted

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • runkit7_function_add() - Add a new function, similar to create_function
  • runkit7_function_copy() - Copy a function to a new function name
  • runkit7_function_redefine() - Replace a function definition with a new implementation
  • runkit7_function_rename() - Change a function's name


Change a function's name

  • ≪ runkit7_function_remove
  • runkit7_import ≫
  • PHP Manual
  • runkit7 関数
  • Change a function's name

runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Change a function's name

説明

runkit7_function_rename(string $source_name, string $target_name): bool

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

source_name

Current function name

target_name

New function name

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • runkit7_function_add() - Add a new function, similar to create_function
  • runkit7_function_copy() - Copy a function to a new function name
  • runkit7_function_redefine() - Replace a function definition with a new implementation
  • runkit7_function_remove() - Remove a function definition


Process a PHP file importing function and class definitions, overwriting where appropriate

  • ≪ runkit7_function_rename
  • runkit7_method_add ≫
  • PHP Manual
  • runkit7 関数
  • Process a PHP file importing function and class definitions, overwriting where appropriate

runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate

警告

This feature has been removed in PECL runkit7 4.0.0.

説明

runkit7_import(string $filename, int $flags = ?): bool

Similar to include. However, any code residing outside of a function or class is simply ignored. Additionally, depending on the value of flags, any functions or classes which already exist in the currently running environment may be automatically overwritten by their new definitions.

パラメータ

filename

Filename to import function and class definitions from

flags

Bitwise OR of the RUNKIT7_IMPORT_* family of constants.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Dynamically adds a new method to a given class

  • ≪ runkit7_import
  • runkit7_method_copy ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically adds a new method to a given class

runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Dynamically adds a new method to a given class

説明

runkit7_method_add(
string $class_name,
string $method_name,
string $argument_list,
string $code,
int $flags = RUNKIT7_ACC_PUBLIC,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool
runkit7_method_add(
string $class_name,
string $method_name,
Closure $closure,
int $flags = RUNKIT7_ACC_PUBLIC,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool

パラメータ

class_name

The class to which this method will be added

method_name

The name of the method to add

argument_list

Comma-delimited list of arguments for the newly-created method

code

The code to be evaluated when method_name is called

closure

A closure that defines the method.

flags

The type of method to create, can be RUNKIT7_ACC_PUBLIC, RUNKIT7_ACC_PROTECTED or RUNKIT7_ACC_PRIVATE optionally combined via bitwise OR with RUNKIT7_ACC_STATIC

doc_comment

The doc comment of the method.

return_type

The return type of the method.

is_strict

Whether the method behaves as if it were declared in a file with strict_types=1

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 runkit7_method_add() example

<?php
class Example {
function foo() {
echo "foo!\n";
}
}

// create an Example object
$e = new Example();

// Add a new public method
runkit7_method_add(
'Example',
'add',
'$num1, $num2',
'return $num1 + $num2;',
RUNKIT7_ACC_PUBLIC
);

// add 12 + 4
echo $e->add(12, 4);
?>

上の例の出力は以下となります。

16

参考

  • runkit7_method_copy() - Copies a method from class to another
  • runkit7_method_redefine() - Dynamically changes the code of the given method
  • runkit7_method_remove() - Dynamically removes the given method
  • runkit7_method_rename() - Dynamically changes the name of the given method
  • runkit7_function_add() - Add a new function, similar to create_function


Copies a method from class to another

  • ≪ runkit7_method_add
  • runkit7_method_redefine ≫
  • PHP Manual
  • runkit7 関数
  • Copies a method from class to another

runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copies a method from class to another

説明

runkit7_method_copy(
string $destination_class,
string $destination_method_name,
string $source_class,
string $source_method_name = ?
): bool

パラメータ

destination_class

Destination class for copied method

destination_method_name

Destination method name

source_class

Source class of the method to copy

source_method_name

Name of the method to copy from the source class. If this parameter is omitted, the value of destination_method_name is assumed.

戻り値

例

例1 runkit7_method_copy() example

<?php
class Foo {
function example() {
return "foo!\n";
}
}

class Bar {
// initially, no methods
}

// copy the example() method from the Foo class to the Bar class, as baz()
runkit7_method_copy('Bar', 'baz', 'Foo', 'example');

// output copied function
echo Bar::baz();
?>

上の例の出力は以下となります。

foo!

参考

  • runkit7_method_add() - Dynamically adds a new method to a given class
  • runkit7_method_redefine() - Dynamically changes the code of the given method
  • runkit7_method_remove() - Dynamically removes the given method
  • runkit7_method_rename() - Dynamically changes the name of the given method
  • runkit7_function_copy() - Copy a function to a new function name


Dynamically changes the code of the given method

  • ≪ runkit7_method_copy
  • runkit7_method_remove ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically changes the code of the given method

runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Dynamically changes the code of the given method

説明

runkit7_method_redefine(
string $class_name,
string $method_name,
string $argument_list,
string $code,
int $flags = RUNKIT7_ACC_PUBLIC,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool
runkit7_method_redefine(
string $class_name,
string $method_name,
Closure $closure,
int $flags = RUNKIT7_ACC_PUBLIC,
string $doc_comment = null,
string $return_type = ?,
bool $is_strict = ?
): bool

パラメータ

class_name

The class in which to redefine the method

method_name

The name of the method to redefine

argument_list

Comma-delimited list of arguments for the redefined method

code

The new code to be evaluated when method_name is called

closure

A closure that defines the method.

flags

The redefined method can be RUNKIT7_ACC_PUBLIC, RUNKIT7_ACC_PROTECTED or RUNKIT7_ACC_PRIVATE optionally combined via bitwise OR with RUNKIT7_ACC_STATIC

doc_comment

The doc comment of the method.

return_type

The return type of the method.

is_strict

Whether the method behaves as if it was declared in a file with strict_types=1.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 runkit7_method_redefine() example

<?php
class Example {
function foo() {
return "foo!\n";
}
}

// create an Example object
$e = new Example();

// output Example::foo() (before redefine)
echo "Before: " . $e->foo();

// Redefine the 'foo' method
runkit7_method_redefine(
'Example',
'foo',
'',
'return "bar!\n";',
RUNKIT7_ACC_PUBLIC
);

// output Example::foo() (after redefine)
echo "After: " . $e->foo();
?>

上の例の出力は以下となります。

Before: foo!
After: bar!

参考

  • runkit7_method_add() - Dynamically adds a new method to a given class
  • runkit7_method_copy() - Copies a method from class to another
  • runkit7_method_remove() - Dynamically removes the given method
  • runkit7_method_rename() - Dynamically changes the name of the given method
  • runkit7_function_redefine() - Replace a function definition with a new implementation


Dynamically removes the given method

  • ≪ runkit7_method_redefine
  • runkit7_method_rename ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically removes the given method

runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Dynamically removes the given method

説明

runkit7_method_remove(string $class_name, string $method_name): bool

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

パラメータ

class_name

The class in which to remove the method

method_name

The name of the method to remove

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 runkit7_method_remove() example

<?php
class Example {
function foo() {
return "foo!\n";
}

function bar() {
return "bar!\n";
}
}

// Remove the 'foo' method
runkit7_method_remove(
'Example',
'foo'
);

echo implode(' ', get_class_methods('Example'));

?>

上の例の出力は以下となります。

bar

参考

  • runkit7_method_add() - Dynamically adds a new method to a given class
  • runkit7_method_copy() - Copies a method from class to another
  • runkit7_method_redefine() - Dynamically changes the code of the given method
  • runkit7_method_rename() - Dynamically changes the name of the given method
  • runkit7_function_remove() - Remove a function definition


Dynamically changes the name of the given method

  • ≪ runkit7_method_remove
  • runkit7_object_id ≫
  • PHP Manual
  • runkit7 関数
  • Dynamically changes the name of the given method

runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Dynamically changes the name of the given method

説明

runkit7_method_rename(string $class_name, string $source_method_name, string $target_method_name): bool

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

パラメータ

class_name

The class in which to rename the method

source_method_name

The name of the method to rename

target_method_name

The new name to give to the renamed method

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 runkit7_method_rename() example

<?php
class Example {
function foo() {
return "foo!\n";
}
}

// Rename the 'foo' method to 'bar'
runkit7_method_rename(
'Example',
'foo',
'bar'
);

// output renamed function
echo (new Example)->bar();
?>

上の例の出力は以下となります。

foo!

参考

  • runkit7_method_add() - Dynamically adds a new method to a given class
  • runkit7_method_copy() - Copies a method from class to another
  • runkit7_method_redefine() - Dynamically changes the code of the given method
  • runkit7_method_remove() - Dynamically removes the given method
  • runkit7_function_rename() - Change a function's name


Return the integer object handle for given object

  • ≪ runkit7_method_rename
  • runkit7_superglobals ≫
  • PHP Manual
  • runkit7 関数
  • Return the integer object handle for given object

runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Return the integer object handle for given object

説明

runkit7_object_id(object $obj): int

This function is equivalent to spl_object_id().

This function returns a unique identifier for the object. The object id is unique for the lifetime of the object. Once the object is destroyed, its id may be reused for other objects. This behavior is similar to spl_object_hash().

パラメータ

obj

Any object.

戻り値

An integer identifier that is unique for each currently existing object and is always the same for each object.

注意

注意:

When an object is destroyed, its id may be reused for other objects.

参考

  • spl_object_id() - 与えられたオブジェクトを扱う数値オブジェクトを返す


Return numerically indexed array of registered superglobals

  • ≪ runkit7_object_id
  • runkit7_zval_inspect ≫
  • PHP Manual
  • runkit7 関数
  • Return numerically indexed array of registered superglobals

runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Return numerically indexed array of registered superglobals

説明

runkit7_superglobals(): array

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

参考

  • Variable Scope


Returns information about the passed in value with data types, reference counts, etc

  • ≪ runkit7_superglobals
  • uopz ≫
  • PHP Manual
  • runkit7 関数
  • Returns information about the passed in value with data types, reference counts, etc

runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

説明

runkit7_zval_inspect(string $value): array

パラメータ

value

The value to return the representation of

戻り値

The array returned by this function contains the following elements:

  • address
  • refcount (optional)
  • is_ref (optional)
  • type

例

例1 runkit7_zval_inspect() example

<?php

$var = new DateTime();
var_dump(runkit7_zval_inspect($var));

$var = 1;
var_dump(runkit7_zval_inspect($var));
?>

上の例の出力は以下となります。

array(4) {
  ["address"]=>
  string(14) "0x7f45ab21b1e0"
  ["refcount"]=>
  int(2)
  ["is_ref"]=>
  bool(false)
  ["type"]=>
  int(8)
}

array(2) {
  ["address"]=>
  string(14) "0x7f45ab21b1e0"
  ["type"]=>
  int(4)
}

参考

  • References Explained
  • » References Explained (by Derick Rethans)


Zend に対するユーザー操作

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Uopz 関数
    • uopz_add_function — Adds non-existent function or method
    • uopz_allow_exit — Allows control over disabled exit opcode
    • uopz_backup — Backup a function
    • uopz_compose — Compose a class
    • uopz_copy — Copy a function
    • uopz_del_function — Deletes previously added function or method
    • uopz_delete — Delete a function
    • uopz_extend — 実行時にクラスを継承させる
    • uopz_flags — 関数またはクラスのフラグを 取得/設定 する
    • uopz_function — Creates a function at runtime
    • uopz_get_exit_status — Retrieve the last set exit status
    • uopz_get_hook — Gets previously set hook on function or method
    • uopz_get_mock — Get the current mock for a class
    • uopz_get_property — Gets value of class or instance property
    • uopz_get_return — Gets a previous set return value for a function
    • uopz_get_static — 関数またはメソッドスコープから、static変数を取得する
    • uopz_implement — 実行時にインターフェイスを実装させる
    • uopz_overload — Overload a VM opcode
    • uopz_redefine — 定数を再定義
    • uopz_rename — Rename a function at runtime
    • uopz_restore — Restore a previously backed up function
    • uopz_set_hook — Sets hook to execute when entering a function or method
    • uopz_set_mock — 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う
    • uopz_set_property — Sets value of existing class or instance property
    • uopz_set_return — Provide a return value for an existing function
    • uopz_set_static — Sets the static variables in function or method scope
    • uopz_undefine — 定数を未定義化
    • uopz_unset_hook — Removes previously set hook on function or method
    • uopz_unset_mock — 以前に設定したモックを削除する
    • uopz_unset_return — Unsets a previously set return value for a function


はじめに

uopz (User Operations for Zend) 拡張モジュールは、 コンパイル時および実行時に通常使用される Zend Engine の機能を公開します。 その目的は、PHP コードを表す内部構造の変更を可能にすること、 およびユーザーのコードが VM と対話できるようにすることです。

uopz は、以下のアクティビティをサポートします。

  • ZEND_EXIT および ZEND_NEW を含む一部のオペコードをオーバーロード
  • 関数およびメソッドをバックアップおよびリストア
  • 関数およびメソッドの名前を変更
  • 関数およびメソッドのコピー
  • 関数およびメソッドの削除
  • グローバル定数およびクラス定数の再定義
  • グローバル定数およびクラス定数の削除
  • クラスのランタイム構成および変更

注意:

すべてのサポートされるアクティビティは、opcache と互換性があります。

警告

PECL uopz 6.1.1 は、Xdebug >= 2.9.4 と互換性がありません。 これ以後のバージョンの uopz は、Xdebug < 2.9.4 と互換性がありません。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • uopz
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

uopz 5.0 以降は PHP 7 が必要です。 uopz 5.1 以降は PHP 7.1 以降が必要です。


インストール手順

uopz のリリースは PECL でホストされています。 ソースコードは » github でホストされています。 インストールする最も簡単な方法は、いつもの PECL から行うことです。 » https://pecl.php.net/package/uopz

Windows ユーザーは、» PECL Web サイトからビルド済みのリリースバイナリーをダウンロードすることができます。

uopz 5.0.0 以降、この拡張は extension としてロードされる必要があります。 このバージョンより前は、zend_extension としてロードされる必要があります。


実行時設定

php.ini の設定により動作が変化します。

uopz 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
uopz.disable | "0" | INI_SYSTEM | uopz 5.0.2 以降で利用可能
uopz.exit | "0" | INI_SYSTEM | uopz 6.0.1 以降で利用可能
uopz.overloads | "1" | INI_SYSTEM | uopz 2.0.2 以降で利用可能。uopz 5.0.0 以降は削除されています
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

uopz.disable bool

true にすると、uopz はエンジンに影響を及ぼさなくなります。

uopz.exit bool

exit オペコードの実行を許可するかどうかを指定します。 この設定は uopz_allow_exit() を呼ぶことで 実行時に上書きすることができます。

uopz.overloads bool

uopz_overload() 関数を使えるようにします。

注意: OPcache が有効になっている場合、 OPcache の最適化レベル を無効にする必要があるかもしれません。 (opcache.optimization_level=0)


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

The following opcodes are defined as constants by uopz before 5.0.0:

ZEND_EXIT (int)
Invoked by exit() and die(), receives no arguments. Return boolean true to exit, false to continue
ZEND_NEW (int)
Invoked by object construction, receives the class of object being created as the only argument
ZEND_THROW (int)
Invoked by the throw construct, receives the class of exception being thrown as the only argument
ZEND_FETCH_CLASS (int)
Invoked upon composure, receives the class the name of the class being fetched as the only argument
ZEND_ADD_TRAIT (int)
Invoked upon composure, receives the class the trait is being added to as the first argument, and the name of the trait as the second argument
ZEND_ADD_INTERFACE (int)
Invoked upon composure, receives the class the interface is being added to as the first argument, and the name of the interface as the second argument
ZEND_INSTANCEOF (int)
Invoked by instanceof operator, receives the object being verified as the first argument, and the name of the class which that object should be as the second argument

The following constants control the VM's behaviour after a user handler is invoked, be extremely careful! These constants are removed as of uopz 5.0.0.

ZEND_USER_OPCODE_CONTINUE (int)
Advance 1 opcode and continuue
ZEND_USER_OPCODE_ENTER (int)
Enter into new op_array without recursion
ZEND_USER_OPCODE_LEAVE (int)
Return to calling op_array within the same executor
ZEND_USER_OPCODE_DISPATCH (int)
Dispatch to original opcode handler
ZEND_USER_OPCODE_DISPATCH_TO (int)
Dispatch to a specific handler (OR'd with ZEND opcode constant)
ZEND_USER_OPCODE_RETURN (int)
Exit from executor (return from function)

The following modifiers are registered as constants by uopz

ZEND_ACC_PUBLIC (int)
Mark function as public, the default
ZEND_ACC_PROTECTED (int)
Mark function as protected
ZEND_ACC_PRIVATE (int)
Mark function as private
ZEND_ACC_STATIC (int)
Mark function as static
ZEND_ACC_FINAL (int)
Mark function as final
ZEND_ACC_ABSTRACT (int)
Mark function as abstract
ZEND_ACC_CLASS (int)
Dummy registered for consistency, the default kind of class entry. Removed as of uopz 5.0.0.
ZEND_ACC_INTERFACE (int)
Mark class as interface. Removed as of uopz 5.0.0.
ZEND_ACC_TRAIT (int)
Mark class as trait. Removed as of uopz 5.0.0.
ZEND_ACC_FETCH (int)
Used for getting flags only. Removed as of uopz 5.0.0.


Uopz 関数

目次

  • uopz_add_function — Adds non-existent function or method
  • uopz_allow_exit — Allows control over disabled exit opcode
  • uopz_backup — Backup a function
  • uopz_compose — Compose a class
  • uopz_copy — Copy a function
  • uopz_del_function — Deletes previously added function or method
  • uopz_delete — Delete a function
  • uopz_extend — 実行時にクラスを継承させる
  • uopz_flags — 関数またはクラスのフラグを 取得/設定 する
  • uopz_function — Creates a function at runtime
  • uopz_get_exit_status — Retrieve the last set exit status
  • uopz_get_hook — Gets previously set hook on function or method
  • uopz_get_mock — Get the current mock for a class
  • uopz_get_property — Gets value of class or instance property
  • uopz_get_return — Gets a previous set return value for a function
  • uopz_get_static — 関数またはメソッドスコープから、static変数を取得する
  • uopz_implement — 実行時にインターフェイスを実装させる
  • uopz_overload — Overload a VM opcode
  • uopz_redefine — 定数を再定義
  • uopz_rename — Rename a function at runtime
  • uopz_restore — Restore a previously backed up function
  • uopz_set_hook — Sets hook to execute when entering a function or method
  • uopz_set_mock — 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う
  • uopz_set_property — Sets value of existing class or instance property
  • uopz_set_return — Provide a return value for an existing function
  • uopz_set_static — Sets the static variables in function or method scope
  • uopz_undefine — 定数を未定義化
  • uopz_unset_hook — Removes previously set hook on function or method
  • uopz_unset_mock — 以前に設定したモックを削除する
  • uopz_unset_return — Unsets a previously set return value for a function


Adds non-existent function or method

  • ≪ Uopz 関数
  • uopz_allow_exit ≫
  • PHP Manual
  • Uopz 関数
  • Adds non-existent function or method

uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Adds non-existent function or method

説明

uopz_add_function(string $function, Closure $handler, int &$flags = ZEND_ACC_PUBLIC): bool
uopz_add_function(
string $class,
string $function,
Closure $handler,
int &$flags = ZEND_ACC_PUBLIC,
int &$all = true
): bool

Adds a non-existent function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

handler

The Closure that defines the new function or method.

flags

Flags to set for the new function or method.

all

Whether all classes that descend from class will also be affected.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

uopz_add_function() throws a RuntimeException if the function or method to add already exists.

例

例1 Basic uopz_add_function() Usage

<?php
uopz_add_function('foo', function () {echo 'bar';});
foo();
?>

上の例の出力は以下となります。

bar

参考

  • uopz_del_function() - Deletes previously added function or method
  • uopz_set_return() - Provide a return value for an existing function


Allows control over disabled exit opcode

  • ≪ uopz_add_function
  • uopz_backup ≫
  • PHP Manual
  • Uopz 関数
  • Allows control over disabled exit opcode

uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Allows control over disabled exit opcode

説明

uopz_allow_exit(bool $allow): void

By default uopz disables the exit opcode, so exit() calls are practically ignored. uopz_allow_exit() allows to control this behavior.

パラメータ

allow

Whether to allow the execution of exit opcodes or not.

戻り値

値を返しません。

例

例1 uopz_allow_exit() example

<?php
exit(1);
echo 1;
uopz_allow_exit(true);
exit(2);
echo 2;
?>

上の例の出力は以下となります。

1

注意

警告

OPcache optimizes away dead code after unconditional exit.

参考

  • uopz_get_exit_status() - Retrieve the last set exit status


Backup a function

  • ≪ uopz_allow_exit
  • uopz_compose ≫
  • PHP Manual
  • Uopz 関数
  • Backup a function

uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Backup a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_backup(string $function): void
uopz_backup(string $class, string $function): void

Backup a function at runtime, to be restored on shutdown

パラメータ

class

The name of the class containing the function to backup

function

The name of the function

戻り値

例

例1 uopz_backup() example

<?php
uopz_backup("fgets");
uopz_function("fgets", function(){
return true;
});
var_dump(fgets());
?>

上の例の出力は以下となります。

bool(true)


Compose a class

  • ≪ uopz_backup
  • uopz_copy ≫
  • PHP Manual
  • Uopz 関数
  • Compose a class

uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compose a class

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_compose(
string $name,
array $classes,
array $methods = ?,
array $properties = ?,
int $flags = ?
): void

Creates a new class of the given name that implements, extends, or uses all of the provided classes

パラメータ

name

A legal class name

classes

An array of class, interface and trait names

methods

An associative array of methods, values are either closures or [modifiers => closure]

properties

An associative array of properties, keys are names, values are modifiers

flags

Entry type, by default ZEND_ACC_CLASS

戻り値

例

例1 uopz_compose() example

<?php
class myClass {}
trait myTrait {}
interface myInterface {}

uopz_compose(
Composed::class, [
myClass::class,
myTrait::class,
myInterface::class
], [
"__construct" => function() {
/* ... */
}
]);

var_dump(
class_uses(Composed::class),
class_parents(Composed::class),
class_implements(Composed::class));
?>

上の例の出力は以下となります。

array(1) {
  ["myTrait"]=>
  string(7) "myTrait"
}
array(1) {
  ["myClass"]=>
  string(7) "myClass"
}
array(1) {
  ["myInterface"]=>
  string(11) "myInterface"
}


Copy a function

  • ≪ uopz_compose
  • uopz_del_function ≫
  • PHP Manual
  • Uopz 関数
  • Copy a function

uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copy a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_copy(string $function): Closure
uopz_copy(string $class, string $function): Closure

Copy a function by name

パラメータ

class

The name of the class containing the function to copy

function

The name of the function

戻り値

A Closure for the specified function

例

例1 uopz_copy() example

<?php
$strtotime = uopz_copy('strtotime');

uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
/* can call original strtotime from here */
var_dump($arg1);
});

var_dump(strtotime('dummy'));
?>

上の例の出力は以下となります。

string(5) "dummy"


Deletes previously added function or method

  • ≪ uopz_copy
  • uopz_delete ≫
  • PHP Manual
  • Uopz 関数
  • Deletes previously added function or method

uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Deletes previously added function or method

説明

uopz_del_function(string $function): bool
uopz_del_function(string $class, string $function, int &$all = true): bool

Deletes a previously added function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

all

Whether all classes that descend from class will also be affected.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

uopz_del_function() throws a RuntimeException if the function or method to delete has not been added by uopz_add_function().

例

例1 Basic uopz_del_function() Usage

<?php
uopz_add_function('foo', function () {echo 'bar';});
var_dump(function_exists('foo'));
uopz_del_function('foo');
var_dump(function_exists('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • uopz_add_function() - Adds non-existent function or method
  • uopz_unset_return() - Unsets a previously set return value for a function


Delete a function

  • ≪ uopz_del_function
  • uopz_extend ≫
  • PHP Manual
  • Uopz 関数
  • Delete a function

uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Delete a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_delete(string $function): void
uopz_delete(string $class, string $function): void

Deletes a function or method

パラメータ

class

function

戻り値

例

例1 uopz_delete() example

<?php
uopz_delete("strlen");

echo strlen("Hello World");
?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

例2 uopz_delete() class example

<?php
class My {
public static function strlen($arg) {
return strlen($arg);
}
}

uopz_delete(My::class, "strlen");

echo My::strlen("Hello World");
?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10


実行時にクラスを継承させる

  • ≪ uopz_delete
  • uopz_flags ≫
  • PHP Manual
  • Uopz 関数
  • 実行時にクラスを継承させる

uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — 実行時にクラスを継承させる

説明

uopz_extend(string $class, string $parent): bool

class に parent を継承させます。

パラメータ

class

拡張するクラスの名前

parent

継承するクラスの名前

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PHP 7.4.0 以降では、 OPcache が有効になっており、 かつ class または parent が変更不能な場合(トレイトの場合も)、 uopz_extends() 関数は RuntimeException をスローするようになりました。

例

例1 uopz_extend() の例

<?php
class A {}
class B {}

uopz_extend(A::class, B::class);

var_dump(class_parents(A::class));
?>

上の例の出力は以下となります。

array(1) {
  ["B"]=>
  string(1) "B"
}


関数またはクラスのフラグを 取得/設定 する

  • ≪ uopz_extend
  • uopz_function ≫
  • PHP Manual
  • Uopz 関数
  • 関数またはクラスのフラグを 取得/設定 する

uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — 関数またはクラスのフラグを 取得/設定 する

説明

uopz_flags(string $function, int $flags = PHP_INT_MAX): int
uopz_flags(string $class, string $function, int $flags = PHP_INT_MAX): int

実行時にクラスまたは関数エントリのフラグを 取得/設定 します。

パラメータ

class

クラス名を指定します。

function

関数名を指定します。 class が指定され、 かつ function の値にから文字列が指定されると、 uopz_flags() はクラスエントリのフラグを取得または設定します。

flags

ZEND_ACC_ フラグの有効なセット。 省略された場合、uopz_flags() 関数が getter として振る舞います。

戻り値

フラグを設定する場合、古いフラグを返します。それ以外の場合、現在のフラグを返します。

エラー / 例外

PHP 7.4.0 以降で flags が渡された場合は、 OPcache が有効になっており、 かつ class や function のエントリが変更不能な場合、 RuntimeException をスローするようになりました。

変更履歴

バージョン | 説明
PECL uopz 5.0.0 | flags はオプションになりました。 このバージョンより前は、 uopz_flags() を getter として使うために ZEND_ACC_FETCH を渡さなければなりませんでした。

例

例1 uopz_flags() の例

<?php
class Test {
public function method() {
return __CLASS__;
}
}

$flags = uopz_flags("Test", "method");

var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(false)
int(1234567890)
bool(true)
bool(true)

例2 クラスの final 宣言を外す

<?php
final class MyClass
{
}

$flags = uopz_flags(MyClass::class, '');
uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
var_dump((new ReflectionClass(MyClass::class))->isFinal());
?>

上の例の出力は以下となります。

bool(false)


Creates a function at runtime

  • ≪ uopz_flags
  • uopz_get_exit_status ≫
  • PHP Manual
  • Uopz 関数
  • Creates a function at runtime

uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Creates a function at runtime

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_function(string $function, Closure $handler, int $modifiers = ?): void
uopz_function(
string $class,
string $function,
Closure $handler,
int $modifiers = ?
): void

Creates a function at runtime

パラメータ

class

The name of the class to receive the new function

function

The name of the function

handler

The Closure for the function

modifiers

The modifiers for the function, by default copied or ZEND_ACC_PUBLIC

戻り値

例

例1 uopz_function() example

<?php
uopz_function("my_strlen", function($arg) {
return strlen($arg);
});
echo my_strlen("Hello World");
?>

上の例の出力は以下となります。

11

例2 uopz_function() class example

<?php
class My {}

uopz_function(My::class, "strlen", function($arg) {
return strlen($arg);
}, ZEND_ACC_STATIC);

echo My::strlen("Hello World");
?>

上の例の出力は以下となります。

11


Retrieve the last set exit status

  • ≪ uopz_function
  • uopz_get_hook ≫
  • PHP Manual
  • Uopz 関数
  • Retrieve the last set exit status

uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Retrieve the last set exit status

説明

uopz_get_exit_status(): mixed

Retrieves the last set exit status, i.e. the value passed to exit().

パラメータ

この関数にはパラメータはありません。

戻り値

This function returns the last exit status, or null if exit() has not been called.

例

例1 uopz_get_exit_status() example

<?php
exit(123);
echo uopz_get_exit_status();?>

上の例の出力は以下となります。

123

注意

警告

OPcache optimizes away dead code after unconditional exit.

参考

  • uopz_allow_exit() - Allows control over disabled exit opcode


Gets previously set hook on function or method

  • ≪ uopz_get_exit_status
  • uopz_get_mock ≫
  • PHP Manual
  • Uopz 関数
  • Gets previously set hook on function or method

uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Gets previously set hook on function or method

説明

uopz_get_hook(string $function): Closure
uopz_get_hook(string $class, string $function): Closure

Gets the previously set hook on a function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

戻り値

Returns the previously set hook on a function or method, or null if no hook has been set.

例

例1 Basic uopz_get_hook() Usage

<?php
function foo() {
echo 'foo';
}
uopz_set_hook('foo', function () {echo 'bar';});
var_dump(uopz_get_hook('foo'));
?>

上の例の出力は、 たとえば以下のようになります。

object(Closure)#2 (0) {
}

参考

  • uopz_set_hook() - Sets hook to execute when entering a function or method
  • uopz_unset_hook() - Removes previously set hook on function or method


Get the current mock for a class

  • ≪ uopz_get_hook
  • uopz_get_property ≫
  • PHP Manual
  • Uopz 関数
  • Get the current mock for a class

uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Get the current mock for a class

説明

uopz_get_mock(string $class): mixed

Returns the current mock for class.

パラメータ

class

The name of the mocked class.

戻り値

Either a string containing the name of the mock, or an object, or null if no mock has been set.

例

例1 uopz_get_mock() example

<?php
class A {
public static function who() {
echo "A";
}
}

class mockA {
public static function who() {
echo "mockA";
}
}

uopz_set_mock(A::class, mockA::class);
echo uopz_get_mock(A::class);
?>

上の例の出力は以下となります。

mockA

参考

  • uopz_set_mock() - 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う
  • uopz_unset_mock() - 以前に設定したモックを削除する


Gets value of class or instance property

  • ≪ uopz_get_mock
  • uopz_get_return ≫
  • PHP Manual
  • Uopz 関数
  • Gets value of class or instance property

uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Gets value of class or instance property

説明

uopz_get_property(string $class, string $property): mixed
uopz_get_property(object $instance, string $property): mixed

Gets the value of a static class property, if class is given, or the value of an instance property, if instance is given.

パラメータ

class

The name of the class.

instance

The object instance.

property

The name of the property.

戻り値

Returns the value of the class or instance property, or null if the property is not defined.

例

例1 Basic uopz_get_property() Usage

<?php
class Foo {
private static $staticBar = 10;
private $bar = 100;
}
$foo = new Foo;
var_dump(uopz_get_property('Foo', 'staticBar'));
var_dump(uopz_get_property($foo, 'bar'));
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(100)

参考

  • uopz_set_property() - Sets value of existing class or instance property


Gets a previous set return value for a function

  • ≪ uopz_get_property
  • uopz_get_static ≫
  • PHP Manual
  • Uopz 関数
  • Gets a previous set return value for a function

uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Gets a previous set return value for a function

説明

uopz_get_return(string $function): mixed
uopz_get_return(string $class, string $function): mixed

Gets the return value of the function previously set by uopz_set_return().

パラメータ

class

The name of the class containing the function

function

The name of the function

戻り値

The return value or Closure previously set.

例

例1 uopz_get_return() example

<?php
uopz_set_return("strlen", 42);
echo uopz_get_return("strlen");
?>

上の例の出力は以下となります。

42


関数またはメソッドスコープから、static変数を取得する

  • ≪ uopz_get_return
  • uopz_implement ≫
  • PHP Manual
  • Uopz 関数
  • 関数またはメソッドスコープから、static変数を取得する

uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — 関数またはメソッドスコープから、static変数を取得する

説明

uopz_get_static(string $class, string $function): array
uopz_get_static(string $function): array

関数またはメソッドスコープから、static変数を取得します。

パラメータ

class

クラスの名前

function

関数またはメソッドの名前

戻り値

成功した場合、現在の値にマップされた変数名の連想配列を返します。 関数やメソッド名が存在しない場合は null を返します。

PHP 8.3.0 以降では、static 変数の初期化子はコンパイル時に計算されますが、 それが不可能な場合、つまり関数やメソッドが初回実行される場合のみ、 初回実行前の static変数の値は null として報告されます。

例

例1 uopz_get_static() の基本的な使い方

<?php
function foo() {
static $bar = 'baz';
}
var_dump(uopz_get_static('foo'));
?>

上の例の出力は以下となります。

array(1) {
  ["bar"]=>
  string(3) "baz"
}

参考

  • ReflectionFunctionAbstract::getStaticVariables() - static変数を取得する
  • uopz_set_static() - Sets the static variables in function or method scope


実行時にインターフェイスを実装させる

  • ≪ uopz_get_static
  • uopz_overload ≫
  • PHP Manual
  • Uopz 関数
  • 実行時にインターフェイスを実装させる

uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — 実行時にインターフェイスを実装させる

説明

uopz_implement(string $class, string $interface): bool

class にinterface を実装させます。

パラメータ

class

interface

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PHP 7.4.0 以降では、 OPcache が有効になっており、 かつ class のエントリが変更不能な場合、 uopz_implements() 関数は RuntimeException をスローするようになりました。

例

例1 uopz_implement() の例

<?php
interface myInterface {}

class myClass {}

uopz_implement(myClass::class, myInterface::class);

var_dump(class_implements(myClass::class));
?>

上の例の出力は以下となります。

array(1) {
  ["myInterface"]=>
  string(11) "myInterface"
}


Overload a VM opcode

  • ≪ uopz_implement
  • uopz_redefine ≫
  • PHP Manual
  • Uopz 関数
  • Overload a VM opcode

uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Overload a VM opcode

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_overload(int $opcode, Callable $callable): void

Overloads the specified opcode with the user defined function

パラメータ

opcode

A valid opcode, see constants for details of supported codes

callable

戻り値

例

例1 uopz_overload() example

<?php
uopz_overload(ZEND_EXIT, function(){});

exit();
echo "Hello World";
?>

上の例の出力は以下となります。

Hello World


定数を再定義

  • ≪ uopz_overload
  • uopz_rename ≫
  • PHP Manual
  • Uopz 関数
  • 定数を再定義

uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — 定数を再定義

説明

uopz_redefine(string $constant, mixed $value): bool
uopz_redefine(string $class, string $constant, mixed $value): bool

指定された constant を value として再定義します。

パラメータ

class

定数を含むクラスの名前

constant

定数名

value

定数の新しい値。定数のバリアブルに対して有効な型にする必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 uopz_redefine() の例

<?php
define("MY", 100);

uopz_redefine("MY", 1000);

echo MY;
?>

上の例の出力は以下となります。

1000


Rename a function at runtime

  • ≪ uopz_redefine
  • uopz_restore ≫
  • PHP Manual
  • Uopz 関数
  • Rename a function at runtime

uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Rename a function at runtime

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_rename(string $function, string $rename): void
uopz_rename(string $class, string $function, string $rename): void

Renames function to rename

注意:

If both functions exist, this effectively swaps their names

パラメータ

class

The name of the class containing the function

function

The name of an existing function

rename

The new name for the function

戻り値

例

例1 uopz_rename() example

<?php
uopz_rename("strlen", "original_strlen");

echo original_strlen("Hello World");
?>

上の例の出力は以下となります。

11

例2 uopz_rename() class example

<?php
class My {
public function strlen($arg) {
return strlen($arg);
}
}

uopz_rename(My::class, "strlen", "original_strlen");

echo My::original_strlen("Hello World");
?>

上の例の出力は以下となります。

11


Restore a previously backed up function

  • ≪ uopz_rename
  • uopz_set_hook ≫
  • PHP Manual
  • Uopz 関数
  • Restore a previously backed up function

uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restore a previously backed up function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

説明

uopz_restore(string $function): void
uopz_restore(string $class, string $function): void

Restore a previously backed up function

パラメータ

class

The name of the class containing the function to restore

function

The name of the function

戻り値

例

例1 uopz_restore() example

<?php
uopz_backup("fgets");
uopz_function("fgets", function(){
return true;
});
var_dump(fgets());
uopz_restore('fgets');
fgets();
?>

上の例の出力は、 たとえば以下のようになります。

Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8


Sets hook to execute when entering a function or method

  • ≪ uopz_restore
  • uopz_set_mock ≫
  • PHP Manual
  • Uopz 関数
  • Sets hook to execute when entering a function or method

uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hook — Sets hook to execute when entering a function or method

説明

uopz_set_hook(string $function, Closure $hook): bool
uopz_set_hook(string $class, string $function, Closure $hook): bool

Sets a hook to execute when entering a function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

hook

A closure to execute when entering the function or method.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Basic uopz_set_hook() Usage

<?php
function foo() {
echo 'foo';
}
uopz_set_hook('foo', function () {echo 'bar';});
foo();
?>

上の例の出力は以下となります。

barfoo

参考

  • uopz_get_hook() - Gets previously set hook on function or method
  • uopz_unset_hook() - Removes previously set hook on function or method


新しいオブジェクトを生成する際に、クラスの代わりにモックを使う

  • ≪ uopz_set_hook
  • uopz_set_property ≫
  • PHP Manual
  • Uopz 関数
  • 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う

uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う

説明

uopz_set_mock(string $class, mixed $mock): void

mock がクラス名を含んだ文字列だった場合、 class の代わりにそれがインスタンス化されます。 mock はオブジェクトであっても構いません。

注意:

プロパティやメソッドに動的にアクセスした場合にだけ、 mock オブジェクトを使います。 静的にアクセスした場合には、オリジナルの class を使います。 後に示す 例 を参照ください。

パラメータ

class

モックで代替するクラスの名前

mock

モックとして使うクラス名を含む文字列。またはオブジェクト。 文字列を渡す場合、完全修飾されたクラス名でなければいけません。 この場合、マジック定数 ::class を使うことを推奨します。

戻り値

値を返しません。

変更履歴

バージョン | 説明
uopz 6.0.0 | static なメンバは、この関数でサポートされなくなりました。 uopz_redefine() や uopz_set_return() を使うか、Componere が代わりに使えます。

例

例1 uopz_set_mock() の例

<?php
class A {
public function who() {
echo "A";
}
}

class mockA {
public function who() {
echo "mockA";
}
}

uopz_set_mock(A::class, mockA::class);
(new A)->who();
?>

上の例の出力は以下となります。

mockA

例2 uopz_set_mock() の例

<?php
class A {
public function who() {
echo "A";
}
}

uopz_set_mock(A::class, new class {
public function who() {
echo "mockA";
}
});
(new A)->who();
?>

上の例の出力は以下となります。

mockA

例3 uopz_set_mock() と static メンバ

uopz 6.0.0 以降、static なメンバはサポートされなくなりました。

<?php
class A {
const CON = 'A';
public static function who() {
echo "A";
}
}

uopz_set_mock(A::class, new class {
const CON = 'mockA';
public static function who() {
echo "mockA";
}
});
echo A::CON, PHP_EOL;
A::who();
?>

上の例の出力は以下となります。

A
A

Output of the above example in uopz 5:

mockA
mockA

参考

  • uopz_get_mock() - Get the current mock for a class
  • uopz_unset_mock() - 以前に設定したモックを削除する


Sets value of existing class or instance property

  • ≪ uopz_set_mock
  • uopz_set_return ≫
  • PHP Manual
  • Uopz 関数
  • Sets value of existing class or instance property

uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Sets value of existing class or instance property

説明

uopz_set_property(string $class, string $property, mixed $value): void
uopz_set_property(object $instance, string $property, mixed $value): void

Sets the value of an existing static class property, if class is given, or the value of an instance property (regardless whether the instance property already exists), if instance is given.

パラメータ

class

The name of the class.

instance

The object instance.

property

The name of the property.

value

The value to assign to the property.

戻り値

値を返しません。

例

例1 Basic uopz_set_property() Usage

<?php
class Foo {
private static $staticBar;
private $bar;
public static function testStaticBar() {
return self::$staticBar;
}
public function testBar() {
return $this->bar;
}
}
$foo = new Foo;
uopz_set_property('Foo', 'staticBar', 10);
uopz_set_property($foo, 'bar', 100);
var_dump(Foo::testStaticBar());
var_dump($foo->testBar());
?>

上の例の出力は以下となります。

int(10)

参考

  • uopz_get_property() - Gets value of class or instance property


Provide a return value for an existing function

  • ≪ uopz_set_property
  • uopz_set_static ≫
  • PHP Manual
  • Uopz 関数
  • Provide a return value for an existing function

uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Provide a return value for an existing function

説明

uopz_set_return(string $function, mixed $value, bool $execute = false): bool
uopz_set_return(
string $class,
string $function,
mixed $value,
bool $execute = false
): bool

Sets the return value of the function to value. If value is a Closure and execute is set, the Closure will be executed in place of the original function. It is possible to call the original function from the Closure.

注意:

This function replaces uopz_rename().

パラメータ

class

The name of the class containing the function

function

The name of an existing function

value

The value the function should return. If a Closure is provided and the execute flag is set, the Closure will be executed in place of the original function.

execute

If true, and a Closure was provided as the value, the Closure will be executed in place of the original function.

戻り値

True if succeeded, false otherwise.

例

例1 uopz_set_return() example

<?php
uopz_set_return("strlen", 42);
echo strlen("Banana");
?>

上の例の出力は以下となります。

42

例2 uopz_set_return() example

<?php
uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
echo strlen("Banana");
?>

上の例の出力は以下となります。

12

例3 uopz_set_return() class example

<?php
class My {
public static function strlen($arg) {
return strlen($arg);
}
}
uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
echo My::strlen("Banana");
?>

上の例の出力は以下となります。

12


Sets the static variables in function or method scope

  • ≪ uopz_set_return
  • uopz_undefine ≫
  • PHP Manual
  • Uopz 関数
  • Sets the static variables in function or method scope

uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Sets the static variables in function or method scope

説明

uopz_set_static(string $function, array $static): void
uopz_set_static(string $class, string $function, array $static): void

Sets the static variables in function or method scope.

パラメータ

class

The name of the class.

function

The name of the function or method.

static

The associative array of variable names mapped to their values.

戻り値

値を返しません。

例

例1 Basic uopz_set_static() Usage

<?php
function foo() {
static $bar = 'baz';
var_dump($bar);
}
uopz_set_static('foo', ['bar' => 'qux']);
foo();
?>

上の例の出力は以下となります。

string(3) "qux"

参考

  • uopz_get_static() - 関数またはメソッドスコープから、static変数を取得する


定数を未定義化

  • ≪ uopz_set_static
  • uopz_unset_hook ≫
  • PHP Manual
  • Uopz 関数
  • 定数を未定義化

uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — 定数を未定義化

説明

uopz_undefine(string $constant): bool
uopz_undefine(string $class, string $constant): bool

実行時に定数を除去します。

パラメータ

class

constant を含むクラスの名前

constant

既存の定数名

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 uopz_undefine() の例

<?php
define("MY", true);

uopz_undefine("MY");

var_dump(defined("MY"));
?>

上の例の出力は以下となります。

bool(false)


Removes previously set hook on function or method

  • ≪ uopz_undefine
  • uopz_unset_mock ≫
  • PHP Manual
  • Uopz 関数
  • Removes previously set hook on function or method

uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Removes previously set hook on function or method

説明

uopz_unset_hook(string $function): bool
uopz_unset_hook(string $class, string $function): bool

Removes the previously set hook on a function or method.

パラメータ

class

The name of the class.

function

The name of the function or method.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Basic uopz_unset_hook() Usage

<?php
function foo() {
echo 'foo';
}
uopz_set_hook('foo', function () {echo 'bar';});
foo();
echo PHP_EOL;
uopz_unset_hook('foo');
foo();
?>

上の例の出力は以下となります。

barfoo
foo

参考

  • uopz_set_hook() - Sets hook to execute when entering a function or method
  • uopz_get_hook() - Gets previously set hook on function or method


以前に設定したモックを削除する

  • ≪ uopz_unset_hook
  • uopz_unset_return ≫
  • PHP Manual
  • Uopz 関数
  • 以前に設定したモックを削除する

uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — 以前に設定したモックを削除する

説明

uopz_unset_mock(string $class): void

以前に class で設定したモックを削除します。

パラメータ

class

モックで代替されているクラス。

戻り値

値を返しません。

エラー / 例外

class で指定されたモックが見つからない場合、 RuntimeException がスローされます。

例

例1 uopz_unset_mock() の例

<?php
class A {
public static function who() {
echo "A";
}
}

class mockA {
public static function who() {
echo "mockA";
}
}

uopz_set_mock(A::class, mockA::class);
uopz_unset_mock(A::class);
A::who();
?>

上の例の出力は以下となります。

A

参考

  • uopz_set_mock() - 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う
  • uopz_get_mock() - Get the current mock for a class


Unsets a previously set return value for a function

  • ≪ uopz_unset_mock
  • WinCache ≫
  • PHP Manual
  • Uopz 関数
  • Unsets a previously set return value for a function

uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Unsets a previously set return value for a function

説明

uopz_unset_return(string $function): bool
uopz_unset_return(string $class, string $function): bool

Unsets the return value of the function previously set by uopz_set_return().

パラメータ

class

The name of the class containing the function

function

The name of the function

戻り値

True on success

例

例1 uopz_unset_return() example

<?php
uopz_set_return("strlen", 42);
$len = strlen("Banana");
uopz_unset_return("strlen");
echo $len + strlen("Banana");
?>

上の例の出力は以下となります。

48


PHP 用の Windows キャッシュ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • WinCache 統計スクリプト
    • WinCache セッションハンドラ
    • WinCache 関数への切り替え
  • WinCache 関数
    • 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 でのビルド
    • 要件
    • コンパイルおよびビルド
    • ビルドの検証


はじめに

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 エンジンはこのバイトコードを再利用します。

    opcode キャッシングのサポートは、Wincache 2.0.0 で削除されました。 opcache を所有したいすべてのユーザーは、PHP に含まれる OPcache 拡張を使用すべきです。

  • ファイルキャッシュ - 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 セッションに格納するときのパフォーマンスが向上します。


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • WinCache 統計スクリプト
  • WinCache セッションハンドラ
  • WinCache 関数への切り替え


要件

この拡張モジュールは、現在は次の構成のみをサポートしています。

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 といった関連する情報については、次の場所にあります。 » https://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" | INI_ALL | WinCache 1.0.0 以降で使用可能
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.fcachesize | "24" | "5" | "255" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.fcndetect | "1" | "0" | "1" | INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.maxfilesize | "256" | "10" | "2048" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ocenabled | "1" | "0" | "1" | INI_ALL | WinCache 1.0.0 以降で使用可能、2.0.0.0 で削除
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能、2.0.0.0 で削除
wincache.ocachesize | "96" | "15" | "255" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能、2.0.0.0 で削除
wincache.filecount | "4096" | "1024" | "16384" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.chkinterval | "30" | "0" | "300" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ttlmax | "1200" | "0" | "7200" | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.enablecli | 0 | 0 | 1 | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ignorelist | NULL | NULL | NULL | INI_ALL | WinCache 1.0.0 以降で使用可能
wincache.namesalt | NULL | NULL | NULL | INI_SYSTEM | WinCache 1.0.0 以降で使用可能
wincache.ucenabled | 1 | 0 | 1 | INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.ucachesize | 8 | 5 | 85 | INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.scachesize | 8 | 5 | 85 | INI_SYSTEM | WinCache 1.1.0 以降で使用可能
wincache.rerouteini | NULL | NULL | NULL | INI_SYSTEM | WinCache 1.2.0 以降で使用可能。1.3.7 で削除。
wincache.reroute_enabled | 1 | 0 | 1 | INI_SYSTEM|INI_PERDIR | WinCache 1.3.7 以降で使用可能
wincache.srwlocks | 1 | 0 | 1 | INI_SYSTEM | WinCache 1.3.6.3 以降で使用可能、2.0.0.0 で削除
wincache.filemapdir | NULL | NULL | NULL | INI_SYSTEM | WinCache 1.3.7.4 以降で使用可能
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

wincache.fcenabled bool
ファイルキャッシュ機能を有効あるいは無効にします。
wincache.fcenabledfilter string
ファイルキャッシュ有効あるいは無効にする IIS ウェブサイト識別子の一覧を、 カンマ区切りで指定します。この設定は wincache.fcenabled との組み合わせで機能します。 wincache.fcenabled が 1 の場合は、 wincache.fcenabledfilter のファイルキャッシュが無効になります。 wincache.fcenabled が 0 の場合は wincache.fcenabledfilter のファイルキャッシュが有効になります。
wincache.fcachesize int
ファイルキャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 キャッシュされたファイルの総容量がこの設定値を超えると、 いちばん古いファイルから順にファイルキャッシュから取り除かれます。
wincache.fcndetect bool
ファイルの変更通知検出機能を有効あるいは無効にします。 ファイル変更通知がサポートされているときは、対応するファイルがファイスシステム上で変更されるとすぐに opcode キャッシュおよびファイルキャッシュも更新します。 ファイル変更通知をサポートしていないとき (ネットワークファイル共有を使っている場合など) は、 wincache.chkinterval で指定した間隔ごとに wincache がファイル更新を確認します。
wincache.maxfilesize int
キャッシュする個々のファイルの最大サイズ (キロバイト単位) を指定します。 この大きさを超えるサイズのファイルはキャッシュされません。 この設定は、ファイルにのみ適用されます。
wincache.ocenabled bool
警告

このオプションは 2.0.0.0 で削除されました。

opcode キャッシュ機能を有効あるいは無効にします。
wincache.ocenabledfilter string
opcode キャッシュ有効あるいは無効にする IIS ウェブサイト識別子の一覧を、 カンマ区切りで指定します。この設定は wincache.ocenabled との組み合わせで機能します。 wincache.ocenabled が 1 の場合は、 wincache.ocenabledfilter に指定したサイトの opcode キャッシュを無効にします。 wincache.ocenabled が 0 の場合は、 wincache.ocenabledfilter に指定したサイトの opcode キャッシュを有効にします。 このオプションは 2.0.0.0 で削除されました。
wincache.ocachesize int
警告

このオプションは 2.0.0.0 で削除されました。

opcode キャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 キャッシュされた opcode の総容量がこの設定値を超えると、 いちばん古い opcode から順に opcode キャッシュから取り除かれます。 opcode キャッシュのサイズは、少なくともファイルキャッシュの三倍以上でなければならないことに注意しましょう。 そうなっていなければ、opcode キャッシュのサイズが自動的に拡張されます。
wincache.filecount int
この拡張モジュールがどれくらいの数のファイルをキャッシュすることを想定しているのかを指定し、 起動時に適切なサイズのメモリを確保できるようにします。ファイルの数がこの設定値を超えると、 WinCache は必要に応じてさらにメモリを確保します。
wincache.chkinterval int
ファイルの変更チェックとそれに伴うキャッシュの更新を何秒間隔で行うかを指定します。 0 にすると、キャッシュの更新機能が無効になります。 その場合は、キャッシュエントリが scavenger で削除されたり IIS アプリケーションプールがリサイクルされたり wincache_refresh_if_changed 関数がコールされたりしない限り ファイルの変更がキャッシュに反映されなくなります。
wincache.ttlmax int
未使用状態のキャッシュエントリの最大生存期間 (秒単位) を定義します。 これを 0 にすると、キャッシュの scavenger を無効にします。 そのため、IIS ワーカープロセスが生き続ける限りキャッシュエントリは削除されなくなります。
wincache.enablecli bool
PHP がコマンドライン (CLI) モードで動いているときのキャッシュを有効にするかどうかを設定します。
wincache.ignorelist string

この拡張モジュールでキャッシュをしないファイルの一覧を定義します。 ファイルリストにはファイル名のみを指定し、パイプ記号 "|" で区切ります。

例1 wincache.ignorelist の例

wincache.ignorelist = "index.php|misc.php|admin.php"

wincache.namesalt string
この拡張モジュールが使うオブジェクトを共有メモリに格納する際に、 そのオブジェクトの名前に使う文字列を定義します。 IIS ワーカープロセス内の別のアプリケーションとの間で名前の衝突を起こさないようにするために、 これを使います。namesalt 文字列の長さは最大 8 文字までです。
wincache.ucenabled bool
ユーザーキャッシュ機能を有効あるいは無効にします。
wincache.ucachesize int
ユーザーキャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 ユーザーキャッシュに格納された変数のサイズがこの設定値を超えると、 いちばん古い変数から順にキャッシュから取り除かれます。
wincache.scachesize int
セッションキャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 セッションキャッシュに格納されたデータのサイズがこの設定値を超えると、 いちばん古いデータから順にキャッシュから取り除かれます。
wincache.rerouteini string
警告

このオプションは 1.3.7 で削除されました。1.3.7 以降で同様の機能を使うには、wincache.reroute_enabled を参照ください。

reroute.ini ファイルへの絶対パスあるいは相対パスを指定します。 このファイルには、同等の WinCache 関数で実装を置き換える PHP 関数の一覧を記述します。 相対パスで指定した場合は、php-cgi.exe の場所を基準としたパスとみなします。
wincache.reroute_enabled bool
ファイルキャッシュを用いたファイル入出力関数群のリルートを有効あるいは無効にします。
wincache.srwlocks bool
警告

このオプションは 2.0.0.0 で削除されました。

共有のリーダーロック／ライターロックを有効あるいは無効にします。WinCache におけるデッドロックのトラブルシューティングの際には、無効にしておくと便利です。
wincache.filemapdir string
WinCache が共有メモリセグメント用の一時ファイルを格納するために使うディレクトリへの絶対パスを指定します。 このディレクトリはローカルマシン上のものでなければいけません。ネットワークファイルシステム上のディレクトリは使えません。 ディレクトリを指定しなかった場合は、WinCache は Windows System Page File をすべての共有メモリセグメント用に使います。


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.rerouteini は WinCache 1.3.7.0 で削除されました。かわりに、自動的な関数置き換え機能を利用します。 wincache.reroute_enabled を参照ください。

WinCache の関数切り替え機能 (WinCache 1.2.0 以降で使用可能で、WinCache 1.3.7.0 で削除されました) を使うと、 その用途向けに最適化した同等の関数で組み込みの PHP 関数を置き換えることができます。 WinCache 拡張モジュールには、PHP のファイル操作関数を Windows 向けに最適化した実装が含まれています。PHP でネットワーク共有上のファイルにアクセスする必要がある場合などに、 これを使うとアプリケーションのパフォーマンスを向上させることができるでしょう。 最適化した実装が用意されている関数は、次のとおりです。

  • file_exists
  • file_get_contents
  • readfile
  • is_readable
  • is_writable
  • is_dir
  • realpath
  • filesize

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 — ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • 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 — 指定したキーの排他ロックを解放する


ファイルキャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ WinCache 関数
  • wincache_fcache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • ファイルキャッシュにキャッシュされたファイルについての情報を取得する

wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_fcache_fileinfo(bool $summaryonly = false): array|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() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


ファイルキャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_fcache_fileinfo
  • wincache_lock ≫
  • PHP Manual
  • WinCache 関数
  • ファイルキャッシュのメモリ使用状況についての情報を取得する

wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する

説明

wincache_fcache_meminfo(): array|false

ファイルキャッシュによるメモリ使用状況についての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に 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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


指定したキーで排他ロックを確保する

  • ≪ wincache_fcache_meminfo
  • wincache_ocache_fileinfo ≫
  • PHP Manual
  • WinCache 関数
  • 指定したキーで排他ロックを確保する

wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — 指定したキーで排他ロックを確保する

説明

wincache_lock(string $key, bool $isglobal = false): bool

指定したキーについての排他ロックを確保します。 ロックを確保するまでは、現在のスクリプトの実行はブロックされます。 ロックを確保できたら、その後は他のスクリプトから同じキーのロックを要求があってもそれをブロックします。 現在のスクリプトが 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_unlock() - 指定したキーの排他ロックを解放する
  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する


opcode キャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ wincache_lock
  • wincache_ocache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • opcode キャッシュにキャッシュされたファイルについての情報を取得する

wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_ocache_fileinfo(bool $summaryonly = false): array|false

opcode キャッシュの中身とその利用状況についての情報を取得します。

警告

この機能は PHP 7.0.0 で 削除 されました。

パラメータ

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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


opcode キャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_ocache_fileinfo
  • wincache_refresh_if_changed ≫
  • PHP Manual
  • WinCache 関数
  • opcode キャッシュのメモリ使用状況についての情報を取得する

wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する

説明

wincache_ocache_meminfo(): array|false

opcode キャッシュによるメモリ使用状況についての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

opcode キャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に false を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - opcode キャッシュ用に確保されたメモリのバイト数。
  • memory_free - opcode キャッシュで使える空きメモリのバイト数。
  • num_used_blks - opcode キャッシュが使っているメモリブロック数。
  • num_free_blks - opcode キャッシュで使える空きメモリブロック数。
  • memory_overhead - opcode キャッシュが内部的に使っているメモリのバイト数。

警告

この機能は PHP 7.0.0 で 削除 されました。

例

例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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


キャッシュされたファイルのキャッシュエントリをリフレッシュする

  • ≪ wincache_ocache_meminfo
  • wincache_rplist_fileinfo ≫
  • PHP Manual
  • WinCache 関数
  • キャッシュされたファイルのキャッシュエントリをリフレッシュする

wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする

説明

wincache_refresh_if_changed(array $files = NULL): bool

ファイルのキャッシュエントリをリフレッシュします。ファイル名は引数で渡します。 引数を指定しなかった場合は、キャッシュ内のすべてのエントリをリフレッシュします。

パラメータ

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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する


ファイルパス解決キャッシュについての情報を取得する

  • ≪ wincache_refresh_if_changed
  • wincache_rplist_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • ファイルパス解決キャッシュについての情報を取得する

wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する

説明

wincache_rplist_fileinfo(bool $summaryonly = false): array|false

相対ファイルパスとそれに対応する絶対ファイルパスとの対応を記録したキャッシュについての情報を取得します。

パラメータ

summaryonly

戻り値

ファイルパス解決キャッシュについてのメタデータの配列を返します。失敗した場合に 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_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_rplist_fileinfo
  • wincache_scache_info ≫
  • PHP Manual
  • WinCache 関数
  • ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

説明

wincache_rplist_meminfo(): array|false

ファイルパス解決キャッシュによるメモリ使用状況についての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルパス解決キャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に 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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


セッションキャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ wincache_rplist_meminfo
  • wincache_scache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • セッションキャッシュにキャッシュされたファイルについての情報を取得する

wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_scache_info(bool $summaryonly = false): array|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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


セッションキャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_scache_info
  • wincache_ucache_add ≫
  • PHP Manual
  • WinCache 関数
  • セッションキャッシュのメモリ使用状況についての情報を取得する

wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する

説明

wincache_scache_meminfo(): array|false

セッションキャッシュによるメモリ使用状況についての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

セッションキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に 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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する


変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

  • ≪ wincache_scache_meminfo
  • wincache_ucache_cas ≫
  • PHP Manual
  • WinCache 関数
  • 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

説明

wincache_ucache_add(string $key, mixed $value, int $ttl = 0): bool
wincache_ucache_add(array $values, mixed $unused = NULL, int $ttl = 0): bool

変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加します。 追加された変数は、有効期限に達するか、 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_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • __sleep()


変数を古い値と比較して新しい値を代入する

  • ≪ wincache_ucache_add
  • wincache_ucache_clear ≫
  • PHP Manual
  • WinCache 関数
  • 変数を古い値と比較して新しい値を代入する

wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する

説明

wincache_ucache_cas(string $key, int $old_value, int $new_value): bool

指定したキーの変数を 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_inc() - キーに関連づけられた値を増加させる
  • wincache_ucache_dec() - キーに関連づけられた値を減少させる


ユーザーキャッシュの中身全体を削除する

  • ≪ wincache_ucache_cas
  • wincache_ucache_dec ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュの中身全体を削除する

wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する

説明

wincache_ucache_clear(): bool

ユーザーキャッシュに格納されているすべての値を消去/削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に 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_clear
  • wincache_ucache_delete ≫
  • PHP Manual
  • WinCache 関数
  • キーに関連づけられた値を減少させる

wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — キーに関連づけられた値を減少させる

説明

wincache_ucache_dec(string $key, int $dec_by = 1, bool &$success = ?): mixed

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_inc() - キーに関連づけられた値を増加させる
  • wincache_ucache_cas() - 変数を古い値と比較して新しい値を代入する


変数をユーザーキャッシュから削除する

  • ≪ wincache_ucache_dec
  • wincache_ucache_exists ≫
  • PHP Manual
  • WinCache 関数
  • 変数をユーザーキャッシュから削除する

wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — 変数をユーザーキャッシュから削除する

説明

wincache_ucache_delete(mixed $key): bool

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_delete
  • wincache_ucache_get ≫
  • PHP Manual
  • WinCache 関数
  • 変数がユーザーキャッシュに存在するかどうかを調べる

wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる

説明

wincache_ucache_exists(string $key): bool

指定したキーの変数がユーザーキャッシュに存在するかどうかを調べます。

パラメータ

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_exists
  • wincache_ucache_inc ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュに格納された変数を取得する

wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する

説明

wincache_ucache_get(mixed $key, bool &$success = ?): mixed

ユーザーキャッシュに格納された変数を取得します。

パラメータ

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_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • __wakeup()


キーに関連づけられた値を増加させる

  • ≪ wincache_ucache_get
  • wincache_ucache_info ≫
  • PHP Manual
  • WinCache 関数
  • キーに関連づけられた値を増加させる

wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — キーに関連づけられた値を増加させる

説明

wincache_ucache_inc(string $key, int $inc_by = 1, bool &$success = ?): mixed

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_dec() - キーに関連づけられた値を減少させる
  • wincache_ucache_cas() - 変数を古い値と比較して新しい値を代入する


ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

  • ≪ wincache_ucache_inc
  • wincache_ucache_meminfo ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

説明

wincache_ucache_info(bool $summaryonly = false, string $key = NULL): array|false

ユーザーキャッシュに格納されたデータについての情報を取得します。

パラメータ

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 - データがセッション変数であることを示します。
    • 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_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo() - opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


ユーザーキャッシュのメモリ使用状況についての情報を取得する

  • ≪ wincache_ucache_info
  • wincache_ucache_set ≫
  • PHP Manual
  • WinCache 関数
  • ユーザーキャッシュのメモリ使用状況についての情報を取得する

wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する

説明

wincache_ucache_meminfo(): array|false

ユーザーキャッシュによるメモリ使用状況についての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ユーザーキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に 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_fcache_fileinfo() - ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo() - ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ocache_fileinfo() - opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_rplist_fileinfo() - ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo() - ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed() - キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo() - セッションキャッシュのメモリ使用状況についての情報を取得する


変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

  • ≪ wincache_ucache_meminfo
  • wincache_unlock ≫
  • PHP Manual
  • WinCache 関数
  • 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

説明

wincache_ucache_set(mixed $key, mixed $value, int $ttl = 0): bool
wincache_ucache_set(array $values, mixed $unused = NULL, int $ttl = 0): bool

変数をユーザーキャッシュに追加します。変数が既にキャッシュに存在する場合はそれを上書きします。 追加あるいは更新された変数は、有効期限に達するか、 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_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • __sleep()


指定したキーの排他ロックを解放する

  • ≪ wincache_ucache_set
  • Windows でのビルド ≫
  • PHP Manual
  • WinCache 関数
  • 指定したキーの排他ロックを解放する

wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — 指定したキーの排他ロックを解放する

説明

wincache_unlock(string $key): bool

指定したキーに対して、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_lock() - 指定したキーで排他ロックを確保する
  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_info() - セッションキャッシュにキャッシュされたファイルについての情報を取得する


  • ≪ wincache_unlock
  • 要件 ≫
  • PHP Manual
  • WinCache
  • Windows でのビルド

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 ディレクティブと関数の一覧を出力します。


階層型プロファイラ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
  • Xhprof 関数
    • xhprof_disable — xhprof プロファイラを終了する
    • xhprof_enable — xhprof プロファイラを開始する
    • xhprof_sample_disable — xhprof サンプルプロファイラを終了する
    • xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する


はじめに

XHProf は、軽量で階層型な命令ベースのプロファイラです。 データ収集フェーズでは、呼び出し回数や プログラムの動的コールグラフ内の弧の包括的メトリクスを追跡します。 排他的メトリクス (実行時間や CPU 時間、メモリ使用量など) の計算は、レポーティングや後処理のフェーズで行います。 関数のプロファイルは、呼び出す側と呼び出される側に分けることができます。 XHProf が再帰関数を扱うときには、コールグラフ内での循環をデータ収集時に検出し、 循環を回避するために、再帰の実行のたびにその深さも含めた一意な名前をつけます。

XHProf には、シンプルな HTML ベースのユーザーインターフェイス (PHP で書かれたもの) が含まれています。 ブラウザ上でプロファイル結果を見られるので、結果を見たり他人と共有したりが簡単にできるようになります。 コールグラフの画像表示にも対応しています。

XHProf のレポートは、実行されたコードの構造を把握するのにも便利です。 レポートは階層構造になっているので、これを利用して、 たとえば特定の関数が呼ばれるに至るまでの関数呼び出しの流れをたどることもできます。

XHProf には、二回の実行結果を比較 ("diff" レポート) したり、複数回実行した結果を集約したりする機能もあります。 差分のレポートや集約レポートに関しても、単一の実行レポートと同様に 「フラット」な表示と「階層型」の表示でプロファイルを確認できます。

詳細な情報は » xhprof の facebook ページ を参照ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Xhprof
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

必須ではありませんが、xhprof には PHP で書かれたインターフェイスが含まれています。 これを使うと、プロファイル結果のデータを保存したり表示したり便利に使えます。 閲覧にはウェブブラウザーを使います。なので、PHP が使えるウェブサーバーを用意しておけば xhprof をより便利に使えるでしょう。

また、GUI インターフェイスのフォークが » http://github.com/preinheimer/xhprof にあります。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xhprof


実行時設定

php.ini の設定により動作が変化します。

Xhprof 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
xhprof.output_dir | "" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

xhprof.output_dir string

iXHProfRuns インターフェイスのデフォルト実装 (つまり XHProfRuns_Default クラス) が、 XHProf の実行結果の保存に使うディレクトリ。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XHPROF_FLAGS_NO_BUILTINS (int)
すべてのビルトイン関数 (内部関数) をスキップします。
XHPROF_FLAGS_CPU (int)
CPU のプロファイル情報を出力に含めます。
XHPROF_FLAGS_MEMORY (int)
メモリのプロファイル情報を出力に含めます。


例

例1 オプションの GUI を使った Xhprof の例

この例では、プロファイラを開始して終了させた後に、 組み込みの GUI を使って結果を保存してパースします。 つまり、拡張モジュール自身のコードは、 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 — xhprof プロファイラを終了する
  • xhprof_enable — xhprof プロファイラを開始する
  • xhprof_sample_disable — xhprof サンプルプロファイラを終了する
  • xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する


xhprof プロファイラを終了する

  • ≪ Xhprof 関数
  • xhprof_enable ≫
  • PHP Manual
  • Xhprof 関数
  • xhprof プロファイラを終了する

xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — xhprof プロファイラを終了する

説明

xhprof_disable(): array

プロファイラを終了して、xhprof の実行結果データを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

実行結果の xhprof データを配列で返します。

例

例1 xhprof_disable() の例

<?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 プロファイラを開始する

  • ≪ xhprof_disable
  • xhprof_sample_disable ≫
  • PHP Manual
  • Xhprof 関数
  • xhprof プロファイラを開始する

xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — xhprof プロファイラを開始する

説明

xhprof_enable(int $flags = 0, array $options = ?): void

xhprof のプロファイリングを開始します。

パラメータ

flags

オプションのフラグで、プロファイル用の追加情報を指定します。フラグの詳細な情報は XHprof 定数 を参照ください。たとえば XHPROF_FLAGS_MEMORY はメモリのプロファイリングを有効にします。

options

オプション項目の配列。つまり、 'ignored_functions' オプションで関数を渡すと、 その関数のプロファイリングを無視したりできます。

戻り値

null

変更履歴

バージョン | 説明
PECL xhprof 0.9.2 | オプションのパラメータ options が追加されました。

例

例1 xhprof_enable() の例

<?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_disable() - xhprof プロファイラを終了する
  • xhprof_sample_enable() - サンプリングモードでの XHProf プロファイリングを開始する
  • memory_get_usage() - PHP に割り当てられたメモリの量を返す
  • getrusage() - 現在のリソース使用状況を取得する


xhprof サンプルプロファイラを終了する

  • ≪ xhprof_enable
  • xhprof_sample_enable ≫
  • PHP Manual
  • Xhprof 関数
  • xhprof サンプルプロファイラを終了する

xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — xhprof サンプルプロファイラを終了する

説明

xhprof_sample_disable(): array

サンプルモードの xhprof プロファイラを終了します。

パラメータ

この関数にはパラメータはありません。

戻り値

xhprof のサンプルデータの配列を返します。

例

例1 xhprof_sample_disable() の例

<?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 プロファイリングを開始する

  • ≪ xhprof_sample_disable
  • Yac ≫
  • PHP Manual
  • Xhprof 関数
  • サンプリングモードでの XHProf プロファイリングを開始する

xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

説明

xhprof_sample_enable(): void

サンプルモードでのプロファイルを開始します。これは xhprof_enable() の軽量版です。 サンプリング間隔は 0.1 秒で、完全な関数のコールスタックを記録します。 主な使い道は、パフォーマンス監視や調査などでオーバーヘッドを極力抑えたい場合です。

パラメータ

この関数にはパラメータはありません。

戻り値

null

参考

  • xhprof_sample_disable() - xhprof サンプルプロファイラを終了する
  • xhprof_enable() - xhprof プロファイラを開始する
  • memory_get_usage() - PHP に割り当てられたメモリの量を返す
  • getrusage() - 現在のリソース使用状況を取得する


Yac

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Yac — The Yac class
    • Yac::add — Store into cache
    • Yac::__construct — Constructor
    • Yac::delete — Remove items from cache
    • Yac::dump — Dump cache
    • Yac::flush — Flush the cache
    • Yac::get — Retrieve values from cache
    • Yac::__get — Getter
    • Yac::info — Status of cache
    • Yac::set — Store into cache
    • Yac::__set — Setter


はじめに

Yac (Yet Another cache), is a lock-free, shared memory user data cache, could be used to replace APC, local memcache.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Yac
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yac.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


実行時設定

php.ini の設定により動作が変化します。

Yac 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yac.compress_threshold | -1 | INI_SYSTEM |
yac.debug | 0 | INI_ALL |
yac.enable | 1 | INI_SYSTEM |
yac.enable_cli | 0 | INI_SYSTEM |
yac.keys_memory_size | 4M | INI_SYSTEM |
yac.serializer | php | INI_SYSTEM |
yac.values_memory_size | 64M | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

yac.compress_threshold int

yac.debug int

yac.enable int

yac.enable_cli int

yac.keys_memory_size string

yac.serializer string

yac.values_memory_size string


  • ≪ 実行時設定
  • 定義済み定数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

YAC_VERSION (string)
YAC_MAX_KEY_LEN (int)
Max length of a key could be, it is 48 bytes.
YAC_MAX_VALUE_RAW_LEN (int)
YAC_MAX_RAW_COMPRESSED_LEN (int)
YAC_SERIALIZER_PHP (int)
Use php serialize as serializer
YAC_SERIALIZER_JSON (int)
Use json as serializer(requrie --enable-json)
YAC_SERIALIZER_IGBINARY (int)
Use igbinary as serializer(require --enable-igbinary)
YAC_SERIALIZER_MSGPACK (int)
Use msgpack as serializer(require --enable-msgpack)
YAC_SERIALIZER (string)
Which serialzier is yac used


The Yac class

(PECL yac >= 1.0.0)

はじめに

クラス概要

class Yac {
/* プロパティ */
protected $_prefix;
/* メソッド */
public __construct(string $prefix = "")
public add(string $keys, mixed $value, int $ttl = 0): bool
public add(array $key_vals): bool
public delete(string|array $keys, int $ttl = ?): bool
public dump(int $$num): mixed
public flush(): bool
public get(string|array $key, int &$cas = null): mixed
public __get(string $key): mixed
public info(): array
public set(string $keys, mixed $value, int $ttl = 0): bool
public add(array $key_vals): bool
public __set(string $keys, mixed $value): mixed
}

プロパティ

_prefix

目次

  • Yac::add — Store into cache
  • Yac::__construct — Constructor
  • Yac::delete — Remove items from cache
  • Yac::dump — Dump cache
  • Yac::flush — Flush the cache
  • Yac::get — Retrieve values from cache
  • Yac::__get — Getter
  • Yac::info — Status of cache
  • Yac::set — Store into cache
  • Yac::__set — Setter


Store into cache

  • ≪ Yac
  • Yac::__construct ≫
  • PHP Manual
  • Yac
  • Store into cache

Yac::add

(PECL yac >= 1.0.0)

Yac::add — Store into cache

説明

public Yac::add(string $keys, mixed $value, int $ttl = 0): bool
public Yac::add(array $key_vals): bool

Added a item into cache.

パラメータ

keys

string key

value

mixed value, All php value type could be stored except リソース

ttl

expire time

戻り値

bool, true on success, false on failure

注意:

Yac::add() may fail if cas lock could not obtain, so, if you need the value to be stored properly, you may write codes like:

例1 Make sure the item is stored

while(!$yac->set("key", "vale));


Constructor

  • ≪ Yac::add
  • Yac::delete ≫
  • PHP Manual
  • Yac
  • Constructor

Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructor

説明

public Yac::__construct(string $prefix = "")

prefix is used to prepended to keys, this could be used to avoiding conflicts between apps.

パラメータ

prefix

string prefix

エラー / 例外

Throws an Exception if Yac is not enabled. Throws Exception if prefix exceeds max key length of 48 (YAC_MAX_KEY_LEN) bytes.


Remove items from cache

  • ≪ Yac::__construct
  • Yac::dump ≫
  • PHP Manual
  • Yac
  • Remove items from cache

Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Remove items from cache

説明

public Yac::delete(string|array $keys, int $ttl = ?): bool

remove items from cache

パラメータ

keys

string key, or array of multiple keys to be removed

ttl

if delay is set, delete will mark the items to be invalid in ttl second.

戻り値


Dump cache

  • ≪ Yac::delete
  • Yac::flush ≫
  • PHP Manual
  • Yac
  • Dump cache

Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Dump cache

説明

public Yac::dump(int $$num): mixed

Dump values stored in cache

パラメータ

num

Maximum number of items should be returned

戻り値

mixed


Flush the cache

  • ≪ Yac::dump
  • Yac::get ≫
  • PHP Manual
  • Yac
  • Flush the cache

Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Flush the cache

説明

public Yac::flush(): bool

Remove all cached values

パラメータ

この関数にはパラメータはありません。

戻り値

bool, always true


Retrieve values from cache

  • ≪ Yac::flush
  • Yac::__get ≫
  • PHP Manual
  • Yac
  • Retrieve values from cache

Yac::get

(PECL yac >= 1.0.0)

Yac::get — Retrieve values from cache

説明

public Yac::get(string|array $key, int &$cas = null): mixed

Retrieve values from cache

パラメータ

key

string keys, or array of multiple keys.

cas

if not null, it will be set to the retrieved item's cas.

戻り値

mixed on success, false on failure


Getter

  • ≪ Yac::get
  • Yac::info ≫
  • PHP Manual
  • Yac
  • Getter

Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Getter

説明

public Yac::__get(string $key): mixed

Retrieve values from cache

パラメータ

key

string key

戻り値

mixed on success, null on failure


Status of cache

  • ≪ Yac::__get
  • Yac::set ≫
  • PHP Manual
  • Yac
  • Status of cache

Yac::info

(PECL yac >= 1.0.0)

Yac::info — Status of cache

説明

public Yac::info(): array

Get status of cache system

パラメータ

この関数にはパラメータはありません。

戻り値

Return an array, consistent with: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"


Store into cache

  • ≪ Yac::info
  • Yac::__set ≫
  • PHP Manual
  • Yac
  • Store into cache

Yac::set

(PECL yac >= 1.0.0)

Yac::set — Store into cache

説明

public Yac::set(string $keys, mixed $value, int $ttl = 0): bool
public Yac::add(array $key_vals): bool

Add a item into cache, it the key is already exists, override it.

パラメータ

keys

string key

value

mixed value, All php value type could be stored except リソース

ttl

expire time

戻り値

the value self


Setter

  • ≪ Yac::set
  • 音声フォーマットの操作 ≫
  • PHP Manual
  • Yac
  • Setter

Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Setter

説明

public Yac::__set(string $keys, mixed $value): mixed

store a item into cache

パラメータ

keys

string key

value

mixed value, All php value type could be stored except リソース

戻り値

Always return the value self


音声フォーマットの操作

  • OpenAL — OpenAL 音声バインディング
    • はじめに
    • インストール/設定
    • 定義済み定数
    • OpenAL 関数


OpenAL 音声バインディング

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • OpenAL 関数
    • openal_buffer_create — OpenAL バッファを生成する
    • openal_buffer_data — バッファのデータを読み込む
    • openal_buffer_destroy — OpenAL バッファを削除する
    • openal_buffer_get — OpenAL バッファのプロパティを取得する
    • openal_buffer_loadwav — .wav ファイルをバッファに読み込む
    • openal_context_create — 音声処理コンテキストを作成する
    • openal_context_current — 指定したコンテキストを現在のコンテキストにする
    • openal_context_destroy — コンテキストを削除する
    • openal_context_process — 指定したコンテキストを処理する
    • openal_context_suspend — 指定したコンテキストをサスペンドする
    • openal_device_close — OpenAL デバイスを閉じる
    • openal_device_open — OpenAL 音声レイヤを初期化する
    • openal_listener_get — リスナーのプロパティを取得する
    • openal_listener_set — リスナーのプロパティを設定する
    • openal_source_create — ソースリソースを生成する
    • openal_source_destroy — ソースリソースを削除する
    • openal_source_get — OpenAL ソースのプロパティを取得する
    • openal_source_pause — ソースを一時停止する
    • openal_source_play — ソースの再生を開始する
    • openal_source_rewind — ソースを巻き戻す
    • openal_source_set — ソースのプロパティを設定する
    • openal_source_stop — ソースの再生を停止する
    • openal_stream — ソースのストリーム再生を開始する


  • ≪ OpenAL
  • インストール/設定 ≫
  • PHP Manual
  • OpenAL
  • はじめに

はじめに

プラットフォームに依存しない音声バインディングです。 » OpenAL ライブラリ が必要です。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • OpenAL
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://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 (int)
コンテキスト属性
ALC_REFRESH (int)
コンテキスト属性
ALC_SYNC (int)
コンテキスト属性
AL_FREQUENCY (int)
バッファ設定
AL_BITS (int)
バッファ設定
AL_CHANNELS (int)
バッファ設定
AL_SIZE (int)
バッファ設定
AL_BUFFER (int)
ソース/リスナー 設定 (Integer)
AL_SOURCE_RELATIVE (int)
ソース/リスナー 設定 (Integer)
AL_SOURCE_STATE (int)
ソース/リスナー 設定 (Integer)
AL_PITCH (int)
ソース/リスナー 設定 (Float)
AL_GAIN (int)
ソース/リスナー 設定 (Float)
AL_MIN_GAIN (int)
ソース/リスナー 設定 (Float)
AL_MAX_GAIN (int)
ソース/リスナー 設定 (Float)
AL_MAX_DISTANCE (int)
ソース/リスナー 設定 (Float)
AL_ROLLOFF_FACTOR (int)
ソース/リスナー 設定 (Float)
AL_CONE_OUTER_GAIN (int)
ソース/リスナー 設定 (Float)
AL_CONE_INNER_ANGLE (int)
ソース/リスナー 設定 (Float)
AL_CONE_OUTER_ANGLE (int)
ソース/リスナー 設定 (Float)
AL_REFERENCE_DISTANCE (int)
ソース/リスナー 設定 (Float)
AL_POSITION (int)
ソース/リスナー 設定 (Float Vector)
AL_VELOCITY (int)
ソース/リスナー 設定 (Float Vector)
AL_DIRECTION (int)
ソース/リスナー 設定 (Float Vector)
AL_ORIENTATION (int)
ソース/リスナー 設定 (Float Vector)
AL_FORMAT_MONO8 (int)
PCM フォーマット
AL_FORMAT_MONO16 (int)
PCM フォーマット
AL_FORMAT_STEREO8 (int)
PCM フォーマット
AL_FORMAT_STEREO16 (int)
PCM フォーマット
AL_INITIAL (int)
ソースの状態
AL_PLAYING (int)
ソースの状態
AL_PAUSED (int)
ソースの状態
AL_STOPPED (int)
ソースの状態
AL_LOOPING (int)
ソースの状態
AL_TRUE (int)
OpenAL が理解する boolean 値
AL_FALSE (int)
OpenAL が理解する boolean 値


OpenAL 関数

目次

  • openal_buffer_create — OpenAL バッファを生成する
  • openal_buffer_data — バッファのデータを読み込む
  • openal_buffer_destroy — OpenAL バッファを削除する
  • openal_buffer_get — OpenAL バッファのプロパティを取得する
  • openal_buffer_loadwav — .wav ファイルをバッファに読み込む
  • openal_context_create — 音声処理コンテキストを作成する
  • openal_context_current — 指定したコンテキストを現在のコンテキストにする
  • openal_context_destroy — コンテキストを削除する
  • openal_context_process — 指定したコンテキストを処理する
  • openal_context_suspend — 指定したコンテキストをサスペンドする
  • openal_device_close — OpenAL デバイスを閉じる
  • openal_device_open — OpenAL 音声レイヤを初期化する
  • openal_listener_get — リスナーのプロパティを取得する
  • openal_listener_set — リスナーのプロパティを設定する
  • openal_source_create — ソースリソースを生成する
  • openal_source_destroy — ソースリソースを削除する
  • openal_source_get — OpenAL ソースのプロパティを取得する
  • openal_source_pause — ソースを一時停止する
  • openal_source_play — ソースの再生を開始する
  • openal_source_rewind — ソースを巻き戻す
  • openal_source_set — ソースのプロパティを設定する
  • openal_source_stop — ソースの再生を停止する
  • openal_stream — ソースのストリーム再生を開始する


OpenAL バッファを生成する

  • ≪ OpenAL 関数
  • openal_buffer_data ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL バッファを生成する

openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — OpenAL バッファを生成する

説明

openal_buffer_create(): resource

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に Open AL (バッファ) リソース、失敗した場合に false を返します。

参考

  • openal_buffer_loadwav() - .wav ファイルをバッファに読み込む
  • openal_buffer_data() - バッファのデータを読み込む


バッファのデータを読み込む

  • ≪ openal_buffer_create
  • openal_buffer_destroy ≫
  • PHP Manual
  • OpenAL 関数
  • バッファのデータを読み込む

openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — バッファのデータを読み込む

説明

openal_buffer_data(
resource $buffer,
int $format,
string $data,
int $freq
): bool

パラメータ

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_loadwav() - .wav ファイルをバッファに読み込む
  • openal_stream() - ソースのストリーム再生を開始する


OpenAL バッファを削除する

  • ≪ openal_buffer_data
  • openal_buffer_get ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL バッファを削除する

openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — OpenAL バッファを削除する

説明

openal_buffer_destroy(resource $buffer): bool

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_buffer_create() - OpenAL バッファを生成する


OpenAL バッファのプロパティを取得する

  • ≪ openal_buffer_destroy
  • openal_buffer_loadwav ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL バッファのプロパティを取得する

openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — OpenAL バッファのプロパティを取得する

説明

openal_buffer_get(resource $buffer, int $property): int|false

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

property

特定のプロパティ。 AL_FREQUENCY、 AL_BITS、 AL_CHANNELS そして AL_SIZE のいずれか。

戻り値

要求された property の値を整数で返します。 失敗した場合に false を返します。

参考

  • openal_buffer_create() - OpenAL バッファを生成する


.wav ファイルをバッファに読み込む

  • ≪ openal_buffer_get
  • openal_context_create ≫
  • PHP Manual
  • OpenAL 関数
  • .wav ファイルをバッファに読み込む

openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — .wav ファイルをバッファに読み込む

説明

openal_buffer_loadwav(resource $buffer, string $wavfile): bool

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

wavfile

ローカルファイルシステム上の .wav ファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_buffer_data() - バッファのデータを読み込む
  • openal_stream() - ソースのストリーム再生を開始する


音声処理コンテキストを作成する

  • ≪ openal_buffer_loadwav
  • openal_context_current ≫
  • PHP Manual
  • OpenAL 関数
  • 音声処理コンテキストを作成する

openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — 音声処理コンテキストを作成する

説明

openal_context_create(resource $device): resource

パラメータ

device

Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

戻り値

成功した場合に Open AL (コンテキスト) リソース、 失敗した場合に false を返します。

参考

  • openal_device_open() - OpenAL 音声レイヤを初期化する
  • openal_context_destroy() - コンテキストを削除する


指定したコンテキストを現在のコンテキストにする

  • ≪ openal_context_create
  • openal_context_destroy ≫
  • PHP Manual
  • OpenAL 関数
  • 指定したコンテキストを現在のコンテキストにする

openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — 指定したコンテキストを現在のコンテキストにする

説明

openal_context_current(resource $context): bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する


コンテキストを削除する

  • ≪ openal_context_current
  • openal_context_process ≫
  • PHP Manual
  • OpenAL 関数
  • コンテキストを削除する

openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — コンテキストを削除する

説明

openal_context_destroy(resource $context): bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する


指定したコンテキストを処理する

  • ≪ openal_context_destroy
  • openal_context_suspend ≫
  • PHP Manual
  • OpenAL 関数
  • 指定したコンテキストを処理する

openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — 指定したコンテキストを処理する

説明

openal_context_process(resource $context): bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する
  • openal_context_current() - 指定したコンテキストを現在のコンテキストにする
  • openal_context_suspend() - 指定したコンテキストをサスペンドする


指定したコンテキストをサスペンドする

  • ≪ openal_context_process
  • openal_device_close ≫
  • PHP Manual
  • OpenAL 関数
  • 指定したコンテキストをサスペンドする

openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — 指定したコンテキストをサスペンドする

説明

openal_context_suspend(resource $context): bool

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_context_create() - 音声処理コンテキストを作成する
  • openal_context_current() - 指定したコンテキストを現在のコンテキストにする
  • openal_context_process() - 指定したコンテキストを処理する


OpenAL デバイスを閉じる

  • ≪ openal_context_suspend
  • openal_device_open ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL デバイスを閉じる

openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — OpenAL デバイスを閉じる

説明

openal_device_close(resource $device): bool

パラメータ

device

閉じようとしている Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_device_open() - OpenAL 音声レイヤを初期化する


OpenAL 音声レイヤを初期化する

  • ≪ openal_device_close
  • openal_listener_get ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL 音声レイヤを初期化する

openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — OpenAL 音声レイヤを初期化する

説明

openal_device_open(string $device_desc = ?): resource

パラメータ

device_desc

device_desc で指定した音声デバイスをオープンします。 device_desc が指定されなかった場合は、 最初に見つかった音声デバイスが使用されます。

戻り値

成功した場合に Open AL (デバイス) リソース、 失敗した場合に false を返します。

参考

  • openal_device_close() - OpenAL デバイスを閉じる
  • openal_context_create() - 音声処理コンテキストを作成する


リスナーのプロパティを取得する

  • ≪ openal_device_open
  • openal_listener_set ≫
  • PHP Manual
  • OpenAL 関数
  • リスナーのプロパティを取得する

openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — リスナーのプロパティを取得する

説明

openal_listener_get(int $property): mixed

パラメータ

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() - リスナーのプロパティを設定する


リスナーのプロパティを設定する

  • ≪ openal_listener_get
  • openal_source_create ≫
  • PHP Manual
  • OpenAL 関数
  • リスナーのプロパティを設定する

openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — リスナーのプロパティを設定する

説明

openal_listener_set(int $property, mixed $setting): bool

パラメータ

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_listener_get() - リスナーのプロパティを取得する


ソースリソースを生成する

  • ≪ openal_listener_set
  • openal_source_destroy ≫
  • PHP Manual
  • OpenAL 関数
  • ソースリソースを生成する

openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — ソースリソースを生成する

説明

openal_source_create(): resource

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に Open AL (ソース) リソース、 失敗した場合に false を返します。

参考

  • openal_source_set() - ソースのプロパティを設定する
  • openal_source_play() - ソースの再生を開始する
  • openal_source_destroy() - ソースリソースを削除する


ソースリソースを削除する

  • ≪ openal_source_create
  • openal_source_get ≫
  • PHP Manual
  • OpenAL 関数
  • ソースリソースを削除する

openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — ソースリソースを削除する

説明

openal_source_destroy(resource $source): bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_create() - ソースリソースを生成する


OpenAL ソースのプロパティを取得する

  • ≪ openal_source_destroy
  • openal_source_pause ≫
  • PHP Manual
  • OpenAL 関数
  • OpenAL ソースのプロパティを取得する

openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — OpenAL ソースのプロパティを取得する

説明

openal_source_get(resource $source, int $property): mixed

パラメータ

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_create() - ソースリソースを生成する
  • openal_source_set() - ソースのプロパティを設定する
  • openal_source_play() - ソースの再生を開始する


ソースを一時停止する

  • ≪ openal_source_get
  • openal_source_play ≫
  • PHP Manual
  • OpenAL 関数
  • ソースを一時停止する

openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — ソースを一時停止する

説明

openal_source_pause(resource $source): bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_stop() - ソースの再生を停止する
  • openal_source_play() - ソースの再生を開始する
  • openal_source_rewind() - ソースを巻き戻す


ソースの再生を開始する

  • ≪ openal_source_pause
  • openal_source_rewind ≫
  • PHP Manual
  • OpenAL 関数
  • ソースの再生を開始する

openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — ソースの再生を開始する

説明

openal_source_play(resource $source): bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_stop() - ソースの再生を停止する
  • openal_source_pause() - ソースを一時停止する
  • openal_source_rewind() - ソースを巻き戻す


ソースを巻き戻す

  • ≪ openal_source_play
  • openal_source_set ≫
  • PHP Manual
  • OpenAL 関数
  • ソースを巻き戻す

openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — ソースを巻き戻す

説明

openal_source_rewind(resource $source): bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_stop() - ソースの再生を停止する
  • openal_source_pause() - ソースを一時停止する
  • openal_source_play() - ソースの再生を開始する


ソースのプロパティを設定する

  • ≪ openal_source_rewind
  • openal_source_stop ≫
  • PHP Manual
  • OpenAL 関数
  • ソースのプロパティを設定する

openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — ソースのプロパティを設定する

説明

openal_source_set(resource $source, int $property, mixed $setting): bool

パラメータ

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_create() - ソースリソースを生成する
  • openal_source_get() - OpenAL ソースのプロパティを取得する
  • openal_source_play() - ソースの再生を開始する


ソースの再生を停止する

  • ≪ openal_source_set
  • openal_stream ≫
  • PHP Manual
  • OpenAL 関数
  • ソースの再生を停止する

openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — ソースの再生を停止する

説明

openal_source_stop(resource $source): bool

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • openal_source_play() - ソースの再生を開始する
  • openal_source_pause() - ソースを一時停止する
  • openal_source_rewind() - ソースを巻き戻す


ソースのストリーム再生を開始する

  • ≪ openal_source_stop
  • 認証サービス ≫
  • PHP Manual
  • OpenAL 関数
  • ソースのストリーム再生を開始する

openal_stream

(PECL openal >= 0.1.0)

openal_stream — ソースのストリーム再生を開始する

説明

openal_stream(resource $source, int $format, int $rate): resource|false

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

format

data のフォーマット。 AL_FORMAT_MONO8、 AL_FORMAT_MONO16、 AL_FORMAT_STEREO8 そして AL_FORMAT_STEREO16 のいずれか。

rate

データをストリームに流す際の周波数を Hz 単位で指定します。

戻り値

成功した場合にストリームリソースを返します。失敗した場合に false を返します。

参考

  • openal_source_create() - ソースリソースを生成する
  • fwrite() - バイナリセーフなファイル書き込み処理


認証サービス

  • Radius
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Radius 関数


Radius

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
    • RADIUS Options
    • RADIUS Packet Types
    • RADIUS Attribute Types
    • RADIUS Vendor Specific Attribute Types
  • 例
  • Radius 関数
    • radius_acct_open — 課金用の Radius ハンドルを作成する
    • radius_add_server — サーバーを追加する
    • radius_auth_open — 認証用の Radius ハンドルを作成する
    • radius_close — すべてのリソースを開放する
    • radius_config — 指定した設定ファイルをライブラリに読み込ませる
    • radius_create_request — 課金あるいは認証のリクエストを作成する
    • radius_cvt_addr — 生データを IP アドレスに変換する
    • radius_cvt_int — 生データを整数に変換する
    • radius_cvt_string — 生データを文字列に変換する
    • radius_demangle — データを復元する
    • radius_demangle_mppe_key — 変形されたデータから mppe キーを得る
    • radius_get_attr — 属性を取得する
    • radius_get_tagged_attr_data — Extracts the data from a tagged attribute
    • radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute
    • radius_get_vendor_attr — ベンダ固有の属性を取得する
    • radius_put_addr — IP アドレス属性を設定する
    • radius_put_attr — バイナリ属性を設定する
    • radius_put_int — 整数属性を設定する
    • radius_put_string — 文字列属性を設定する
    • radius_put_vendor_addr — ベンダー固有の IP アドレス属性を設定する
    • radius_put_vendor_attr — ベンダー固有のバイナリ属性を設定する
    • radius_put_vendor_int — ベンダー固有の整数属性を設定する
    • radius_put_vendor_string — ベンダー固有の文字列属性を設定する
    • radius_request_authenticator — リクエスト認証子を返す
    • radius_salt_encrypt_attr — Salt-encrypts a value
    • radius_send_request — リクエストを送信し、応答を待つ
    • radius_server_secret — 共有秘密鍵を返す
    • radius_strerror — エラーメッセージを返す


はじめに

このパッケージは、FreeBSD の libradius (Remote Authentication Dial In User Service) をもとにしたものです。 クライアントからの認証や課金を、ネットワーク越しのリモートサーバーに行うことができます。

この PECL モジュールは、Radius 認証 (» RFC 2865) および Radius 課金 (» RFC 2866) を完全にサポートします。 このパッケージは、Unix (FreeBSD および Linux でテストしました) および Windows で使用可能です。

注意:

libradius に関する正確な説明は» ここ にあります。設定ファイルについての詳細な説明は » ここです。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Radius
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/radius.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


定義済み定数

目次

  • RADIUS Options
  • RADIUS Packet Types
  • RADIUS Attribute Types
  • RADIUS Vendor Specific Attribute Types

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RADIUS_MPPE_KEY_LEN (int)
The maximum length of MPPE keys.


RADIUS Options

Several RADIUS functions accept option flags as bitmasks. The constants representing those flags are listed below.

RADIUS_OPTION_SALT (int)

When set, this option will result in the attribute value being salt-encrypted.

RADIUS_OPTION_TAGGED (int)

When set, this option will result in the attribute value being tagged with the value of the tag parameter.


RADIUS Packet Types

RADIUS packets, whether requests or responses, always include a type. These constants are provided to make it easier to specify types when using radius_create_request() and when comparing the result of radius_send_request().

RADIUS_ACCESS_REQUEST (int)

An Access-Request, used to authenticate a user against a RADIUS server. Access request packets must include a RADIUS_NAS_IP_ADDRESS or a RADIUS_NAS_IDENTIFIER attribute, must also include a RADIUS_USER_PASSWORD, RADIUS_CHAP_PASSWORD or a RADIUS_STATE attribute, and should include a RADIUS_USER_NAME attribute.

RADIUS_ACCESS_ACCEPT (int)

An Access-Accept response to an Access-Request indicating that the RADIUS server authenticated the user successfully.

RADIUS_ACCESS_REJECT (int)

An Access-Reject response to an Access-Request indicating that the RADIUS server could not authenticate the user.

RADIUS_ACCESS_CHALLENGE (int)

An Access-Challenge response to an Access-Request indicating that the RADIUS server requires further information in another Access-Request before authenticating the user.

RADIUS_ACCOUNTING_REQUEST (int)

An Accounting-Request, used to convey accounting information for a service to the RADIUS server.

RADIUS_ACCOUNTING_RESPONSE (int)

An Accounting-Response response to an Accounting-Request.

RADIUS_COA_REQUEST (int)

A CoA-Request, sent from the RADIUS server to indicate that the authorisations within the user session have changed. A response must be sent in the form of a CoA-ACK or a CoA-NAK.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_COA_ACK (int)

A CoA-ACK, sent to the RADIUS server to indicate that the user authorisations have been updated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_COA_NAK (int)

A CoA-NAK, sent to the RADIUS server to indicate that the user authorisations could not be updated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_DISCONNECT_REQUEST (int)

A Disconnect-Request, sent from the RADIUS server to indicate that the user session must be terminated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_DISCONNECT_ACK (int)

A Disconnect-ACK, sent to the RADIUS server to indicate that the user session has been terminated.

This constant is available in PECL radius 1.3.0 and later.

RADIUS_DISCONNECT_NAK (int)

A Disconnect-NAK, sent to the RADIUS server to indicate that the user session could not be terminated.

This constant is available in PECL radius 1.3.0 and later.


RADIUS Attribute Types

These constants define RADIUS attribute types that can be used with
radius_put_addr(), radius_put_attr(),
radius_put_int() and
radius_put_string().

RADIUS_USER_NAME (int)

The User-Name attribute. The attribute value is expected to be a string containing the name of the user being authenticated, and can be set using radius_put_attr().

RADIUS_USER_PASSWORD (int)

The User-Password attribute. The attribute value is expected to be a string containing the user's password, and can be set using radius_put_attr(). This value will be obfuscated on transmission as described in » section 5.2 of RFC 2865.

RADIUS_CHAP_PASSWORD (int)

The Chap-Password attribute. The attribute value is expected to be a string with the first byte containing the CHAP identifier, and the subsequent 16 bytes containing the MD5 hash of the CHAP identifier, the plaintext password and the CHAP challenge value concatenated together. Note that the CHAP challenge value should also be sent separately in a RADIUS_CHAP_CHALLENGE attribute.

例1 Using CHAP passwords

<?php
// Firstly, we'll create an authentication handle and request.
$radh = radius_auth_open();
radius_add_server($radh, $server, $port, $secret, 3, 3);
radius_create_request($radh, RADIUS_ACCESS_REQUEST);

// Assuming $password contains the plaintext password, we now:

// Generate a challenge.
$challenge = mt_rand();

// Specify a CHAP identifier.
$ident = 1;

// Add the Chap-Password attribute.
$cp = hash('md5', pack('Ca*', $ident, $password.$challenge), true);
radius_put_attr($radh, RADIUS_CHAP_PASSWORD, pack('C', $ident).$cp);

// Add the Chap-Challenge attribute.
radius_put_attr($radh, RADIUS_CHAP_CHALLENGE, $challenge);

/* From here, you would add the remaining attributes and
* call radius_send_request(). */
?>

RADIUS_NAS_IP_ADDRESS (int)

The NAS-IP-Address attribute. The attribute value is expected to the IP address of the RADIUS client encoded as an int, which can be set using radius_put_addr().

RADIUS_NAS_PORT (int)

The NAS-Port attribute. The attribute value is expected to be the physical port of the user on the RADIUS client encoded as an int, which can be set using radius_put_int().

RADIUS_SERVICE_TYPE (int)

The Service-Type attribute. The attribute value indicates the service type the user is requesting, and is expected to be an int, which can be set using radius_put_int().

A number of constants are provided to represent the possible values of this attribute. They include:

  • 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)

The Framed-Protocol attribute. The attribute value is expected to be an int indicating the framing to be used for framed access, and can be set using radius_put_int(). The possible attribute values include these constants:

  • RADIUS_PPP
  • RADIUS_SLIP
  • RADIUS_ARAP
  • RADIUS_GANDALF
  • RADIUS_XYLOGICS

RADIUS_FRAMED_IP_ADDRESS (int)

The Framed-IP-Address attribute. The attribute value is expected to be the address of the user's network encoded as an int, which can be set using radius_put_addr() and retrieved using radius_cvt_addr().

RADIUS_FRAMED_IP_NETMASK (int)

The Framed-IP-Netmask attribute. The attribute value is expected to be the netmask of the user's network encoded as an int, which can be set using radius_put_addr() and retrieved using radius_cvt_addr().

RADIUS_FRAMED_ROUTING (int)

The Framed-Routing attribute. The attribute value is expected to be an int indicating the routing method for the user, which can be set using radius_put_int().

Possible values include:

  • 0: No routing
  • 1: Send routing packets
  • 2: Listen for routing packets
  • 3: Send and listen

RADIUS_FILTER_ID (int)

The Filter-ID attribute. The attribute value is expected to be an implementation-specific, human-readable string of filters, which can be set using radius_put_attr().

RADIUS_FRAMED_MTU (int)

The Framed-MTU attribute. The attribute value is expected to be an int indicating the MTU to be configured for the user, and can be set using radius_put_int().

RADIUS_FRAMED_COMPRESSION (int)

The Framed-Compression attribute. The attribute value is expected to be an int indicating the compression protocol to be used, and can be set using radius_put_int(). Possible values include these constants:

  • RADIUS_COMP_NONE: No compression
  • RADIUS_COMP_VJ: VJ TCP/IP header compression
  • RADIUS_COMP_IPXHDR: IPX header compression
  • RADIUS_COMP_STAC_LZS: Stac-LZS compression (added in PECL radius 1.3.0b2)

RADIUS_LOGIN_IP_HOST (int)

The Login-IP-Host attribute. The attribute value is expected to the IP address to connect the user to, encoded as an int, which can be set using radius_put_addr().

RADIUS_LOGIN_SERVICE (int)

The Login-Service attribute. The attribute value is an int indicating the service to connect the user to on the login host. The value can be converted to a PHP integer via radius_cvt_int().

RADIUS_LOGIN_TCP_PORT (int)

The Login-TCP-Port attribute. The attribute value is an int indicating the port to connect the user to on the login host. The value can be converted to a PHP integer via radius_cvt_int().

RADIUS_REPLY_MESSAGE (int)

The Reply-Message attribute. The attribute value is a string containing text that may be displayed to the user in response to an access request.

RADIUS_CALLBACK_NUMBER (int)

The Callback-Number attribute. The attribute value is a string containing the dialing string to use for callback.

RADIUS_CALLBACK_ID (int)

The Callback-Id attribute. The attribute value is a string containing an implementation-specific name of the place to be called.

RADIUS_FRAMED_ROUTE (int)

The Framed-Route attribute. The attribute value is a string containing an implementation-specific set of routes to be configured for the user.

RADIUS_FRAMED_IPX_NETWORK (int)

The Framed-IPX-Network attribute. The attribute value is an int containing the IPX network to be configured for the user, or 0xFFFFFFFE to indicate that the RADIUS client should select the network, and can be accessed via radius_cvt_int().

RADIUS_STATE (int)

The State attribute. The attribute value is an implementation-defined string included in an Access-Challenge from a server that must be included in the subsequent Access-Request, and can be set using radius_put_attr().

RADIUS_CLASS (int)

The Class attribute. The attribute value is an arbitrary string included in an Access-Accept message that should then be sent to the accounting server in Accounting-Request messages, and can be set using radius_put_attr().

RADIUS_VENDOR_SPECIFIC (int)

The Vendor-Specific attribute. In general, vendor attribute values
should be set using radius_put_vendor_addr(),
radius_put_vendor_attr(),
radius_put_vendor_int() and
radius_put_vendor_string(), rather than directly.

This constant is mostly useful when interpreting vendor specific attributes in responses from a RADIUS server; when a vendor specific attribute is received, the radius_get_vendor_attr() function should be used to access the vendor ID, attribute type and attribute value.

RADIUS_SESSION_TIMEOUT (int)

Session timeout

RADIUS_IDLE_TIMEOUT (int)

Idle timeout

RADIUS_TERMINATION_ACTION (int)

Termination action

RADIUS_CALLED_STATION_ID (int)

Called Station Id

RADIUS_CALLING_STATION_ID (int)

Calling Station Id

RADIUS_NAS_IDENTIFIER (int)

NAS ID

RADIUS_PROXY_STATE (int)

Proxy State

RADIUS_LOGIN_LAT_SERVICE (int)

Login LAT Service

RADIUS_LOGIN_LAT_NODE (int)

Login LAT Node

RADIUS_LOGIN_LAT_GROUP (int)

Login LAT Group

RADIUS_FRAMED_APPLETALK_LINK (int)

Framed Appletalk Link

RADIUS_FRAMED_APPLETALK_NETWORK (int)

Framed Appletalk Network

RADIUS_FRAMED_APPLETALK_ZONE (int)

Framed Appletalk Zone

RADIUS_CHAP_CHALLENGE (int)

Challenge

RADIUS_NAS_PORT_TYPE (int)

NAS port type, one of:

  • 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)

Port Limit

RADIUS_LOGIN_LAT_PORT (int)

Login LAT Port

RADIUS_CONNECT_INFO (int)

Connect info

RADIUS_ACCT_STATUS_TYPE (int)

Accounting status type, one of:

  • RADIUS_START
  • RADIUS_STOP
  • RADIUS_ACCOUNTING_ON
  • RADIUS_ACCOUNTING_OFF

RADIUS_ACCT_DELAY_TIME (int)

Accounting delay time

RADIUS_ACCT_INPUT_OCTETS (int)

Accounting input bytes

RADIUS_ACCT_OUTPUT_OCTETS (int)

Accounting output bytes

RADIUS_ACCT_SESSION_ID (int)

Accounting session ID

RADIUS_ACCT_AUTHENTIC (int)

Accounting authentic, one of:

  • RADIUS_AUTH_RADIUS
  • RADIUS_AUTH_LOCAL
  • RADIUS_AUTH_REMOTE

RADIUS_ACCT_SESSION_TIME (int)

Accounting session time

RADIUS_ACCT_INPUT_PACKETS (int)

Accounting input packets

RADIUS_ACCT_OUTPUT_PACKETS (int)

Accounting output packets

RADIUS_ACCT_TERMINATE_CAUSE (int)

Accounting terminate cause, one of:

  • 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 (int)

Accounting multi session ID

RADIUS_ACCT_LINK_COUNT (int)

Accounting link count

Service-Type Constants
RADIUS_LOGIN
RADIUS_FRAMED
RADIUS_CALLBACK_LOGIN
RADIUS_CALLBACK_FRAMED
RADIUS_OUTBOUND
RADIUS_ADMINISTRATIVE
RADIUS_NAS_PROMPT
RADIUS_AUTHENTICATE_ONLY
RADIUS_CALLBACK_NAS_PROMPT
Framed-Protocol Constants
RADIUS_PPP
RADIUS_SLIP
RADIUS_ARAP
RADIUS_GANDALF
RADIUS_XYLOGICS
Framed-Compression Constants
RADIUS_COMP_NONE
RADIUS_COMP_VJ
RADIUS_COMP_IPXHDR
RADIUS_COMP_STAC_LZS
NAS Port Type Constants
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
Accounting Status Type Constants
RADIUS_START
RADIUS_STOP
RADIUS_ACCOUNTING_ON
RADIUS_ACCOUNTING_OFF
Accounting Authentic Constants
RADIUS_AUTH_RADIUS
RADIUS_AUTH_LOCAL
RADIUS_AUTH_REMOTE
Accounting Terminate Cause Constants
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 Vendor Specific Attribute Types

RADIUS_VENDOR_MICROSOFT (int)

Microsoft specific vendor attributes (» RFC 2548), one of:

  • 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_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 関数

目次

  • radius_acct_open — 課金用の Radius ハンドルを作成する
  • radius_add_server — サーバーを追加する
  • radius_auth_open — 認証用の Radius ハンドルを作成する
  • radius_close — すべてのリソースを開放する
  • radius_config — 指定した設定ファイルをライブラリに読み込ませる
  • radius_create_request — 課金あるいは認証のリクエストを作成する
  • radius_cvt_addr — 生データを IP アドレスに変換する
  • radius_cvt_int — 生データを整数に変換する
  • radius_cvt_string — 生データを文字列に変換する
  • radius_demangle — データを復元する
  • radius_demangle_mppe_key — 変形されたデータから mppe キーを得る
  • radius_get_attr — 属性を取得する
  • radius_get_tagged_attr_data — Extracts the data from a tagged attribute
  • radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute
  • radius_get_vendor_attr — ベンダ固有の属性を取得する
  • radius_put_addr — IP アドレス属性を設定する
  • radius_put_attr — バイナリ属性を設定する
  • radius_put_int — 整数属性を設定する
  • radius_put_string — 文字列属性を設定する
  • radius_put_vendor_addr — ベンダー固有の IP アドレス属性を設定する
  • radius_put_vendor_attr — ベンダー固有のバイナリ属性を設定する
  • radius_put_vendor_int — ベンダー固有の整数属性を設定する
  • radius_put_vendor_string — ベンダー固有の文字列属性を設定する
  • radius_request_authenticator — リクエスト認証子を返す
  • radius_salt_encrypt_attr — Salt-encrypts a value
  • radius_send_request — リクエストを送信し、応答を待つ
  • radius_server_secret — 共有秘密鍵を返す
  • radius_strerror — エラーメッセージを返す


課金用の Radius ハンドルを作成する

  • ≪ Radius 関数
  • radius_add_server ≫
  • PHP Manual
  • Radius 関数
  • 課金用の Radius ハンドルを作成する

radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — 課金用の Radius ハンドルを作成する

説明

radius_acct_open(): resource

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にハンドル、エラー時に false を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

例

例1 radius_acct_open() の例

<?php
$res = radius_acct_open ()
or die ("ハンドルを作成できませんでした");
print "ハンドルの作成に成功しました";
?>


サーバーを追加する

  • ≪ radius_acct_open
  • radius_auth_open ≫
  • PHP Manual
  • Radius 関数
  • サーバーを追加する

radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — サーバーを追加する

説明

radius_add_server(
resource $radius_handle,
string $hostname,
int $port,
string $secret,
int $timeout,
int $max_tries
): bool

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 ハンドルを作成する

  • ≪ radius_add_server
  • radius_close ≫
  • PHP Manual
  • Radius 関数
  • 認証用の Radius ハンドルを作成する

radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — 認証用の Radius ハンドルを作成する

説明

radius_auth_open(): resource

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にハンドル、エラー時に false を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

例

例1 radius_auth_open() の例

<?php
$radh = radius_auth_open()
or die ("ハンドルを作成できませんでした");
echo "ハンドルの作成に成功しました";
?>


すべてのリソースを開放する

  • ≪ radius_auth_open
  • radius_config ≫
  • PHP Manual
  • Radius 関数
  • すべてのリソースを開放する

radius_close

(PECL radius >= 1.1.0)

radius_close — すべてのリソースを開放する

説明

radius_close(resource $radius_handle): bool

各リクエストの終了時に PHP がすべてのリソースを開放するので、 この関数をコールする必要はありません。

パラメータ

radius_handle

The RADIUS resource.

戻り値

成功した場合に true を、失敗した場合に false を返します。


指定した設定ファイルをライブラリに読み込ませる

  • ≪ radius_close
  • radius_create_request ≫
  • PHP Manual
  • Radius 関数
  • 指定した設定ファイルをライブラリに読み込ませる

radius_config

(PECL radius >= 1.1.0)

radius_config — 指定した設定ファイルをライブラリに読み込ませる

説明

radius_config(resource $radius_handle, string $file): bool

Radius リクエストを発行する前には、ライブラリが接続可能なサーバーを 知っている必要があります。ライブラリを設定するいちばん簡単な方法は radius_config() をコールすることです。 radius_config() は、ライブラリに » radius.conf 形式のファイルを読み込ませます。

パラメータ

radius_handle

file

設定ファイルへのパスを、引数として radius_config() に渡します。 radius_add_server() をコールすることで、 プログラム上でライブラリの設定をすることも可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • radius_add_server() - サーバーを追加する


課金あるいは認証のリクエストを作成する

  • ≪ radius_config
  • radius_cvt_addr ≫
  • PHP Manual
  • Radius 関数
  • 課金あるいは認証のリクエストを作成する

radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — 課金あるいは認証のリクエストを作成する

説明

radius_create_request(resource $radius_handle, int $type): bool

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_send_request() - リクエストを送信し、応答を待つ


生データを IP アドレスに変換する

  • ≪ radius_create_request
  • radius_cvt_int ≫
  • PHP Manual
  • Radius 関数
  • 生データを IP アドレスに変換する

radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — 生データを IP アドレスに変換する

説明

radius_cvt_addr(string $data): string

生データをIPアドレスに変換します。

パラメータ

data

入力値

戻り値

IPアドレスを返します。

例

例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() - 生データを整数に変換する
  • radius_cvt_string() - 生データを文字列に変換する


生データを整数に変換する

  • ≪ radius_cvt_addr
  • radius_cvt_string ≫
  • PHP Manual
  • Radius 関数
  • 生データを整数に変換する

radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — 生データを整数に変換する

説明

radius_cvt_int(string $data): int

生データを整数に変換します。

パラメータ

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_addr() - 生データを IP アドレスに変換する
  • radius_cvt_string() - 生データを文字列に変換する


生データを文字列に変換する

  • ≪ radius_cvt_int
  • radius_demangle ≫
  • PHP Manual
  • Radius 関数
  • 生データを文字列に変換する

radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — 生データを文字列に変換する

説明

radius_cvt_string(string $data): 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_cvt_addr() - 生データを IP アドレスに変換する
  • radius_cvt_int() - 生データを整数に変換する


データを復元する

  • ≪ radius_cvt_string
  • radius_demangle_mppe_key ≫
  • PHP Manual
  • Radius 関数
  • データを復元する

radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — データを復元する

説明

radius_demangle(resource $radius_handle, string $mangled): string

セキュリティ上の理由により、(パスワード、MS-CHAPv1 MPPE キーなど) いくつかのデータは変形されます。それを使用する際には事前に復元する 必要があります。

パラメータ

radius_handle

The RADIUS resource.

mangled

復元対象のデータ

戻り値

復元した文字列、あるいはエラー時には false を返します。


変形されたデータから mppe キーを得る

  • ≪ radius_demangle
  • radius_get_attr ≫
  • PHP Manual
  • Radius 関数
  • 変形されたデータから mppe キーを得る

radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — 変形されたデータから mppe キーを得る

説明

radius_demangle_mppe_key(resource $radius_handle, string $mangled): string

MS-CHAPv2 で MPPE を使用している場合には、送信キーおよび受信キーが 変形されます (» RFC 2548 を参照ください)。しかしこの関数は無意味です。なぜなら PHP では PPTP-MPPE は実装されていないし、今後も実装されるとは思えないからです。

パラメータ

radius_handle

The RADIUS resource.

mangled

復元対象のデータ

戻り値

復元したデータ、あるいはエラー時には false を返します。


属性を取得する

  • ≪ radius_demangle_mppe_key
  • radius_get_tagged_attr_data ≫
  • PHP Manual
  • Radius 関数
  • 属性を取得する

radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — 属性を取得する

説明

radius_get_attr(resource $radius_handle): mixed

Radius リクエストと同様、各レスポンスもゼロ個以上の属性を含んでいます。
radius_send_request() でレスポンスを受け取ったら、
radius_get_attr() を使用して各属性を抽出することが
できます。radius_get_attr() がコールされるたびに、
現在のレスポンスから次の属性を取得します。

パラメータ

radius_handle

The RADIUS resource.

戻り値

属性の型とデータを含む連想配列、あるいは 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_put_attr() - バイナリ属性を設定する
  • radius_get_vendor_attr() - ベンダ固有の属性を取得する
  • radius_put_vendor_attr() - ベンダー固有のバイナリ属性を設定する
  • radius_send_request() - リクエストを送信し、応答を待つ


Extracts the data from a tagged attribute

  • ≪ radius_get_attr
  • radius_get_tagged_attr_tag ≫
  • PHP Manual
  • Radius 関数
  • Extracts the data from a tagged attribute

radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extracts the data from a tagged attribute

説明

radius_get_tagged_attr_data(string $data): string|false

If a tagged attribute has been returned from radius_get_attr(), radius_get_tagged_attr_data() will return the data from the attribute.

パラメータ

data

The tagged attribute to be decoded.

戻り値

Returns the data from the tagged attribute 失敗した場合に false を返します.

例

例1 radius_get_tagged_attr_data() example

<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}

$attr = $resa['attr'];
$data = $resa['data'];

$tag = radius_get_tagged_attr_tag($data);
$value = radius_get_tagged_attr_data($data);

printf("Got tagged attribute with tag %d and value %s\n", $tag, $value);
}
?>

参考

  • radius_get_attr() - 属性を取得する
  • radius_get_tagged_attr_tag() - Extracts the tag from a tagged attribute


Extracts the tag from a tagged attribute

  • ≪ radius_get_tagged_attr_data
  • radius_get_vendor_attr ≫
  • PHP Manual
  • Radius 関数
  • Extracts the tag from a tagged attribute

radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute

説明

radius_get_tagged_attr_tag(string $data): int|false

If a tagged attribute has been returned from radius_get_attr(), radius_get_tagged_attr_data() will return the tag from the attribute.

パラメータ

data

The tagged attribute to be decoded.

戻り値

Returns the tag from the tagged attribute 失敗した場合に false を返します.

例

例1 radius_get_tagged_attr_tag() example

<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}

$attr = $resa['attr'];
$data = $resa['data'];

$tag = radius_get_tagged_attr_tag($data);
$value = radius_get_tagged_attr_data($data);

printf("Got tagged attribute with tag %d and value %s\n", $tag, $value);
}
?>

参考

  • radius_get_attr() - 属性を取得する
  • radius_get_tagged_attr_data() - Extracts the data from a tagged attribute


ベンダ固有の属性を取得する

  • ≪ radius_get_tagged_attr_tag
  • radius_put_addr ≫
  • PHP Manual
  • Radius 関数
  • ベンダ固有の属性を取得する

radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — ベンダ固有の属性を取得する

説明

radius_get_vendor_attr(string $data): array

radius_get_attr() が RADIUS_VENDOR_SPECIFIC を返す場合に、 ベンダを特定するために radius_get_vendor_attr() をコールします。

パラメータ

data

入力値

戻り値

属性の型、ベンダおよびデータを含む連想配列か、エラー時には 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_get_attr() - 属性を取得する
  • radius_put_vendor_attr() - ベンダー固有のバイナリ属性を設定する


IP アドレス属性を設定する

  • ≪ radius_get_vendor_attr
  • radius_put_attr ≫
  • PHP Manual
  • Radius 関数
  • IP アドレス属性を設定する

radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — IP アドレス属性を設定する

説明

radius_put_addr(
resource $radius_handle,
int $type,
string $addr,
int $options = 0,
int $tag = ?
): bool

IP アドレス属性を、現在の RADIUS リクエストにアタッチします。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

type

The attribute type.

addr

IPv4 アドレスを表す文字列。 10.0.0.1 など。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。


バイナリ属性を設定する

  • ≪ radius_put_addr
  • radius_put_int ≫
  • PHP Manual
  • Radius 関数
  • バイナリ属性を設定する

radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — バイナリ属性を設定する

説明

radius_put_attr(
resource $radius_handle,
int $type,
string $value,
int $options = 0,
int $tag = ?
): bool

バイナリ属性を、現在の RADIUS リクエストにアタッチします。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

type

The attribute type.

value

属性の値。バイナリ文字列として扱われます。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

例

例1 radius_put_attr() の例

<?php
mt_srand(time());
$chall = mt_rand();
$chapval = hash('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_get_attr() - 属性を取得する
  • radius_get_vendor_attr() - ベンダ固有の属性を取得する
  • radius_put_vendor_attr() - ベンダー固有のバイナリ属性を設定する


整数属性を設定する

  • ≪ radius_put_attr
  • radius_put_string ≫
  • PHP Manual
  • Radius 関数
  • 整数属性を設定する

radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — 整数属性を設定する

説明

radius_put_int(
resource $radius_handle,
int $type,
int $value,
int $options = 0,
int $tag = ?
): bool

整数属性を、現在の RADIUS リクエストにアタッチします。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

type

The attribute type.

value

属性の値。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に 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;
}
?>

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

参考

  • radius_put_string() - 文字列属性を設定する
  • radius_put_vendor_int() - ベンダー固有の整数属性を設定する
  • radius_put_vendor_string() - ベンダー固有の文字列属性を設定する


文字列属性を設定する

  • ≪ radius_put_int
  • radius_put_vendor_addr ≫
  • PHP Manual
  • Radius 関数
  • 文字列属性を設定する

radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — 文字列属性を設定する

説明

radius_put_string(
resource $radius_handle,
int $type,
string $value,
int $options = 0,
int $tag = ?
): bool

文字列属性を、現在の RADIUS リクエストにアタッチします。 一般に、文字列属性をアタッチするには radius_put_attr() のほうがより便利です。 というのも、こちらのほうはバイナリセーフだからです。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

type

The attribute type.

value

属性の値。 これはヌル終端であることが期待されています。つまり、このパラメータはバイナリセーフではないということです。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

例

例1 radius_put_string() の例

<?php
if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>

参考

  • radius_put_int() - 整数属性を設定する
  • radius_put_vendor_int() - ベンダー固有の整数属性を設定する
  • radius_put_vendor_string() - ベンダー固有の文字列属性を設定する


ベンダー固有の IP アドレス属性を設定する

  • ≪ radius_put_string
  • radius_put_vendor_attr ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有の IP アドレス属性を設定する

radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — ベンダー固有の IP アドレス属性を設定する

説明

radius_put_vendor_addr(
resource $radius_handle,
int $vendor,
int $type,
string $addr
): bool

ベンダー固有の IP アドレス属性を、現在の RADIUS リクエストにアタッチします。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

vendor

The vendor ID.

type

The attribute type.

addr

文字列形式の IPv4 アドレス。 10.0.0.1 など。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。


ベンダー固有のバイナリ属性を設定する

  • ≪ radius_put_vendor_addr
  • radius_put_vendor_int ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有のバイナリ属性を設定する

radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — ベンダー固有のバイナリ属性を設定する

説明

radius_put_vendor_attr(
resource $radius_handle,
int $vendor,
int $type,
string $value,
int $options = 0,
int $tag = ?
): bool

ベンダー固有のバイナリ属性を、現在の RADIUS リクエストにアタッチします。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

vendor

The vendor ID.

type

The attribute type.

value

属性の値。バイナリ文字列として扱われます。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

例

例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_get_vendor_attr() - ベンダ固有の属性を取得する


ベンダー固有の整数属性を設定する

  • ≪ radius_put_vendor_attr
  • radius_put_vendor_string ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有の整数属性を設定する

radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — ベンダー固有の整数属性を設定する

説明

radius_put_vendor_int(
resource $radius_handle,
int $vendor,
int $type,
int $value,
int $options = 0,
int $tag = ?
): bool

ベンダー固有の整数属性を、現在の RADIUS リクエストにアタッチします。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

vendor

The vendor ID.

type

The attribute type.

value

属性の値。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

参考

  • radius_put_vendor_string() - ベンダー固有の文字列属性を設定する


ベンダー固有の文字列属性を設定する

  • ≪ radius_put_vendor_int
  • radius_request_authenticator ≫
  • PHP Manual
  • Radius 関数
  • ベンダー固有の文字列属性を設定する

radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — ベンダー固有の文字列属性を設定する

説明

radius_put_vendor_string(
resource $radius_handle,
int $vendor,
int $type,
string $value,
int $options = 0,
int $tag = ?
): bool

ベンダー固有の文字列属性を、現在の RADIUS リクエストにアタッチします。 一般に、文字列属性をアタッチするには radius_put_vendor_attr() のほうがより便利です。 というのも、こちらのほうはバイナリセーフだからです。

注意:

A request must be created via radius_create_request() before this function can be called.

パラメータ

radius_handle

The RADIUS resource.

vendor

The vendor ID.

type

The attribute type.

value

属性の値。 これはヌル終端であることが期待されています。つまり、このパラメータはバイナリセーフではないということです。

options

A bitmask of the attribute options. The available options include RADIUS_OPTION_TAGGED and RADIUS_OPTION_SALT.

tag

The attribute tag. This parameter is ignored unless the RADIUS_OPTION_TAGGED option is set.

変更履歴

バージョン | 説明
PECL radius 1.3.0 | options および tag が追加されました。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • radius_put_vendor_int() - ベンダー固有の整数属性を設定する


リクエスト認証子を返す

  • ≪ radius_put_vendor_string
  • radius_salt_encrypt_attr ≫
  • PHP Manual
  • Radius 関数
  • リクエスト認証子を返す

radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — リクエスト認証子を返す

説明

radius_request_authenticator(resource $radius_handle): string

パスワードや暗号化キーのような加工されたデータを復元する際には リクエスト認証子が必要となります。

パラメータ

radius_handle

The RADIUS resource.

戻り値

リクエスト認証子を文字列で返します。エラー時には false を返します。

参考

  • radius_demangle() - データを復元する


Salt-encrypts a value

  • ≪ radius_request_authenticator
  • radius_send_request ≫
  • PHP Manual
  • Radius 関数
  • Salt-encrypts a value

radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Salt-encrypts a value

説明

radius_salt_encrypt_attr(resource $radius_handle, string $data): string|false

Applies the RADIUS salt-encryption algorithm to the given value.

In general, this is achieved automatically by providing the RADIUS_OPTION_SALT option to an attribute setter function, but this function can be used if low-level request construction is required.

パラメータ

data

The data to be salt-encrypted.

戻り値

Returns the salt-encrypted data 失敗した場合に false を返します.

参考

  • radius_put_addr() - IP アドレス属性を設定する
  • radius_put_attr() - バイナリ属性を設定する
  • radius_put_int() - 整数属性を設定する
  • radius_put_string() - 文字列属性を設定する


リクエストを送信し、応答を待つ

  • ≪ radius_salt_encrypt_attr
  • radius_server_secret ≫
  • PHP Manual
  • Radius 関数
  • リクエストを送信し、応答を待つ

radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — リクエストを送信し、応答を待つ

説明

radius_send_request(resource $radius_handle): int

Radius リクエストを作成した後は、 radius_send_request() でそれを送信します。

radius_send_request() 関数は、リクエストを送信して 応答を待ちます。定義されているサーバー間で、必要に応じてラウンドロビン 形式で再試行します。

パラメータ

radius_handle

The RADIUS resource.

戻り値

有効な応答を受信したら、radius_send_request() は応答の型を示す Radius コードを返します。一般的なコードは RADIUS_ACCESS_ACCEPT、 RADIUS_ACCESS_REJECT あるいは RADIUS_ACCESS_CHALLENGE です。 有効な応答を受信できなかった場合は、 radius_send_request() は false を返します。

参考

  • radius_create_request() - 課金あるいは認証のリクエストを作成する


共有秘密鍵を返す

  • ≪ radius_send_request
  • radius_strerror ≫
  • PHP Manual
  • Radius 関数
  • 共有秘密鍵を返す

radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — 共有秘密鍵を返す

説明

radius_server_secret(resource $radius_handle): string

パスワードや暗号化キーのような加工されたデータを復元する際の SALT として、共有秘密鍵が必要となります。

パラメータ

radius_handle

The RADIUS resource.

戻り値

サーバーの共有秘密鍵を文字列で返します。エラー時には false を返します。


エラーメッセージを返す

  • ≪ radius_server_secret
  • コマンドライン関連 ≫
  • PHP Manual
  • Radius 関数
  • エラーメッセージを返す

radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — エラーメッセージを返す

説明

radius_strerror(resource $radius_handle): string

Radius 関数が失敗した場合にはエラーメッセージが記録されます。 この関数により、エラーメッセージを取得することが可能となります。

パラメータ

radius_handle

The RADIUS resource.

戻り値

失敗した radius 関数からのエラーメッセージを文字列で返します。


コマンドライン関連

  • Readline — GNU Readline
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Readline 関数


GNU Readline

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Readline 関数
    • readline — 一行読み込む
    • readline_add_history — ヒストリに 1 行追加する
    • readline_callback_handler_install — readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
    • readline_callback_handler_remove — インストールされたハンドラを削除し、端末の設定をもとに戻す
    • readline_callback_read_char — 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する
    • readline_clear_history — ヒストリをクリアする
    • readline_completion_function — 補完関数を登録する
    • readline_info — 種々の readline の内部変数を取得/設定する
    • readline_list_history — ヒストリを一覧表示する
    • readline_on_new_line — カーソルが新しい行に移動したことを readline に通知する
    • readline_read_history — ヒストリを読み込む
    • readline_redisplay — 画面を再描画する
    • readline_write_history — ヒストリを書きこむ


はじめに

readline 関数群は、GNU Readline ライブラリへの インターフェイスを実装したものです。これらの関数は、コマンドラインの 編集機能を提供します。一例をあげると、Bash において文字を挿入したり コマンド履歴を走査したりする際に、矢印キーを使用することを 可能にしているものです。 このライブラリは対話的なものであるため、Web アプリケーションで 使用されることはほとんどないでしょう。しかし、 コマンドライン から PHP を使用するスクリプトを書く際には有用です。

PHP 7.1.0 以降、この拡張モジュールは Windows でサポートされます。

警告

readline 拡張モジュールはスレッドセーフではありません！ (Apache の mod_winnt のような) 本物のスレッドセーフな SAPI と使わないことを強くお勧めします。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Readline
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

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] を指定してください。

Windowsでは、この拡張モジュールは PHP 7.1.0からデフォルトで利用可能です。


実行時設定

php.ini の設定により動作が変化します。

Readline 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
cli.pager | "" | INI_ALL |
cli.prompt | "\\b \\> " | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

cli.pager string

コマンドライン の出力を表示する外部ツール。

cli.prompt string

コマンドラインのプロンプト。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

READLINE_LIB (string)
readline サポートに使われるライブラリ。 現状は、readline または libedit が指定できます。


Readline 関数

目次

  • readline — 一行読み込む
  • readline_add_history — ヒストリに 1 行追加する
  • readline_callback_handler_install — readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
  • readline_callback_handler_remove — インストールされたハンドラを削除し、端末の設定をもとに戻す
  • readline_callback_read_char — 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する
  • readline_clear_history — ヒストリをクリアする
  • readline_completion_function — 補完関数を登録する
  • readline_info — 種々の readline の内部変数を取得/設定する
  • readline_list_history — ヒストリを一覧表示する
  • readline_on_new_line — カーソルが新しい行に移動したことを readline に通知する
  • readline_read_history — ヒストリを読み込む
  • readline_redisplay — 画面を再描画する
  • readline_write_history — ヒストリを書きこむ


一行読み込む

  • ≪ Readline 関数
  • readline_add_history ≫
  • PHP Manual
  • Readline 関数
  • 一行読み込む

readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — 一行読み込む

説明

readline(?string $prompt = null): string|false

ユーザーからの入力を一行読み込みます。 この行を readline_add_history() を用いてヒストリに追加する必要があります。

パラメータ

prompt

ユーザーに示す確認文字列を指定します。

戻り値

ユーザーから取得した文字列を一つだけ返します。 戻り値の最後の改行は取り除かれます。 読み取るデータが残っていない場合、false を返します。

例

例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());
?>


ヒストリに 1 行追加する

  • ≪ readline
  • readline_callback_handler_install ≫
  • PHP Manual
  • Readline 関数
  • ヒストリに 1 行追加する

readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — ヒストリに 1 行追加する

説明

readline_add_history(string $prompt): bool

この関数は、コマンドラインヒストリに 1 行追加します。

パラメータ

prompt

ヒストリに追加する行。

戻り値

成功した場合に true を、失敗した場合に false を返します。


readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

  • ≪ readline_add_history
  • readline_callback_handler_remove ≫
  • PHP Manual
  • Readline 関数
  • readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

説明

readline_callback_handler_install(string $prompt, callable $callback): bool

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() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う


インストールされたハンドラを削除し、端末の設定をもとに戻す

  • ≪ readline_callback_handler_install
  • readline_callback_read_char ≫
  • PHP Manual
  • Readline 関数
  • インストールされたハンドラを削除し、端末の設定をもとに戻す

readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — インストールされたハンドラを削除し、端末の設定をもとに戻す

説明

readline_callback_handler_remove(): bool

インストールされたハンドラを削除し、端末の設定をもとに戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

インストールされたコールバックが削除できた場合に true、 削除するハンドラが見つからなかった場合に false を返します。

例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

参考

  • readline_callback_handler_install() - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
  • readline_callback_read_char() - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する


文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

  • ≪ readline_callback_handler_remove
  • readline_clear_history ≫
  • PHP Manual
  • Readline 関数
  • 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

説明

readline_callback_read_char(): void

ユーザーが入力した文字を読み込みます。改行を受け取ると、この関数は readline_callback_handler_install() で インストールされた readline コールバックインターフェイスに対して 入力待ちを通知します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

参考

  • readline_callback_handler_install() - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
  • readline_callback_handler_remove() - インストールされたハンドラを削除し、端末の設定をもとに戻す


ヒストリをクリアする

  • ≪ readline_callback_read_char
  • readline_completion_function ≫
  • PHP Manual
  • Readline 関数
  • ヒストリをクリアする

readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — ヒストリをクリアする

説明

readline_clear_history(): bool

この関数はコマンドラインヒストリ全体をクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


補完関数を登録する

  • ≪ readline_clear_history
  • readline_info ≫
  • PHP Manual
  • Readline 関数
  • 補完関数を登録する

readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — 補完関数を登録する

説明

readline_completion_function(callable $callback): bool

この関数は補完用の関数を登録します。 これは、Bash を使用している際に、タブキーを 押して得られるのと同様の機能です。

パラメータ

callback

コマンドラインの一部を入力とし、 マッチする可能性がある文字列の配列を返す 既存の関数の名前を指定する必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。


種々の readline の内部変数を取得/設定する

  • ≪ readline_completion_function
  • readline_list_history ≫
  • PHP Manual
  • Readline 関数
  • 種々の readline の内部変数を取得/設定する

readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — 種々の readline の内部変数を取得/設定する

説明

readline_info(?string $var_name = null, int|string|bool|null $value = null): mixed

さまざまな readline の内部変数の取得あるいは設定を行います。

パラメータ

var_name

変数の名前。

value

指定した場合は、これがその設定の新しい値となります。

戻り値

パラメータを指定しないでコールした場合、この関数は readline が使用する すべての設定の値を配列で返します。要素の添字は次のようになります。 done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point, prompt, readline_name, terminal_name。 返される配列は、readline 拡張モジュールをビルドするのに使われるライブラリがサポートする要素だけを含みます。

ひとつあるいはふたつのパラメータを指定してコールした場合は、 元の値が返されます。

変更履歴

バージョン | 説明
8.0.0 | var_name と value は、 nullable になりました。


ヒストリを一覧表示する

  • ≪ readline_info
  • readline_on_new_line ≫
  • PHP Manual
  • Readline 関数
  • ヒストリを一覧表示する

readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — ヒストリを一覧表示する

説明

readline_list_history(): array

コマンドラインヒストリ全体を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

コマンドラインヒストリ全体の配列を返します。 各要素にはゼロから始まる整数の添字が付加されています。


カーソルが新しい行に移動したことを readline に通知する

  • ≪ readline_list_history
  • readline_read_history ≫
  • PHP Manual
  • Readline 関数
  • カーソルが新しい行に移動したことを readline に通知する

readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — カーソルが新しい行に移動したことを readline に通知する

説明

readline_on_new_line(): void

readline に、カーソルが新しい行に移動したことを通知します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

注意

注意:

この関数は、依存する readline ライブラリがサポートしている場合にのみ利用できます。 この関数は、Windows ではサポートされていません。


ヒストリを読み込む

  • ≪ readline_on_new_line
  • readline_redisplay ≫
  • PHP Manual
  • Readline 関数
  • ヒストリを読み込む

readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — ヒストリを読み込む

説明

readline_read_history(?string $filename = null): bool

この関数は、コマンドヒストリをファイルから読み込みます。

パラメータ

filename

コマンドヒストリを含むファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | filename は、nullable になりました。


画面を再描画する

  • ≪ readline_read_history
  • readline_write_history ≫
  • PHP Manual
  • Readline 関数
  • 画面を再描画する

readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — 画面を再描画する

説明

readline_redisplay(): void

画面の再描画を readline に依頼します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


ヒストリを書きこむ

  • ≪ readline_redisplay
  • 圧縮およびアーカイブ ≫
  • PHP Manual
  • Readline 関数
  • ヒストリを書きこむ

readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — ヒストリを書きこむ

説明

readline_write_history(?string $filename = null): bool

この関数はコマンドヒストリをファイルに書き込みます。

パラメータ

filename

保存するファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | filename は、nullable になりました。


圧縮およびアーカイブ

  • Bzip2
    • はじめに
    • インストール/設定
    • 例
    • Bzip2 関数
  • LZF
    • はじめに
    • インストール/設定
    • LZF 関数
  • Phar
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Phar アーカイブの使用法
    • Phar アーカイブの作成
    • phar って、tar や zip とは何が違うの?
    • Phar — Phar クラス
    • PharData — PharData クラス
    • PharFileInfo — PharFileInfo クラス
    • PharException — PharException クラス
  • Rar — Rar アーカイブ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Rar 関数
    • RarArchive — RarArchive クラス
    • RarEntry — The RarEntry class
    • RarException — RarException クラス
  • Zip
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • ZipArchive — ZipArchive クラス
    • Zip 関数
  • Zlib — Zlib 圧縮
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Zlib 関数
    • DeflateContext — DeflateContext クラス
    • InflateContext — InflateContext クラス


Bzip2

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 例
  • Bzip2 関数
    • bzclose — bzip2 ファイルを閉じる
    • bzcompress — 文字列をbzip2形式のデータに圧縮する
    • bzdecompress — bzip2 形式のデータを解凍する
    • bzerrno — bzip2 エラー番号を返す
    • bzerror — bzip2 エラー番号とエラー文字列を配列で返す
    • bzerrstr — bzip2 エラー文字列を返す
    • bzflush — 何もしない
    • bzopen — bzip2 圧縮されたファイルをオープンする
    • bzread — バイナリ対応の bzip2 ファイル読み込み
    • bzwrite — バイナリ対応の bzip2 ファイルへの書き込み


  • ≪ Bzip2
  • インストール/設定 ≫
  • PHP Manual
  • Bzip2
  • はじめに

はじめに

bzip2関数は、bzip2 (.bz2) 圧縮されたファイルを透過的に読み書きするために使用します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Bzip2
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

このモジュールは、Julian Seward により作成された » bzip2ライブラリの関数を使用しています。 このモジュールには、bzip2/libbzip2 のバージョン >= 1.0.x が必要です。


インストール手順

PHP の bzip2 サポートはデフォルトでは有効となっていません。 bzip2 サポートを有効とするには、PHP をコンパイルする際に設定オプション --with-bz2[=DIR] を使用する必要があります。


  • ≪ インストール手順
  • 例 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型

この拡張モジュールは、リソース型として処理を行う 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 — bzip2 ファイルを閉じる
  • bzcompress — 文字列をbzip2形式のデータに圧縮する
  • bzdecompress — bzip2 形式のデータを解凍する
  • bzerrno — bzip2 エラー番号を返す
  • bzerror — bzip2 エラー番号とエラー文字列を配列で返す
  • bzerrstr — bzip2 エラー文字列を返す
  • bzflush — 何もしない
  • bzopen — bzip2 圧縮されたファイルをオープンする
  • bzread — バイナリ対応の bzip2 ファイル読み込み
  • bzwrite — バイナリ対応の bzip2 ファイルへの書き込み


bzip2 ファイルを閉じる

  • ≪ Bzip2 関数
  • bzcompress ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 ファイルを閉じる

bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — bzip2 ファイルを閉じる

説明

bzclose(resource $bz): bool

与えられた bzip2 ファイルポインタを閉じます。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • bzopen() - bzip2 圧縮されたファイルをオープンする


文字列をbzip2形式のデータに圧縮する

  • ≪ bzclose
  • bzdecompress ≫
  • PHP Manual
  • Bzip2 関数
  • 文字列をbzip2形式のデータに圧縮する

bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — 文字列をbzip2形式のデータに圧縮する

説明

bzcompress(string $data, int $block_size = 4, int $work_factor = 0): string|int

bzcompress() は、与えられた文字列を圧縮し、 bzip2 形式のデータとして返します。

パラメータ

data

圧縮する文字列

block_size

圧縮時のブロック長を指定します。 1 から 9 の数とする必要があります。この場合、9 の圧縮度が最大ですが、リソースの消費量も最大となります。

work_factor

繰り返しが多い、最悪の入力データの場合の圧縮処理の動作を制御します。 この値は、0 から 250 までとなり、0 は特別な場合です。

work_factor によらず、 生成される出力は同じになります。

戻り値

圧縮された文字列、もしくはエラー時はエラー数

例

例1 データの圧縮

<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
echo $bzstr;
?>

参考

  • bzdecompress() - bzip2 形式のデータを解凍する


bzip2 形式のデータを解凍する

  • ≪ bzcompress
  • bzerrno ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 形式のデータを解凍する

bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — bzip2 形式のデータを解凍する

説明

bzdecompress(string $data, bool $use_less_memory = false): string|int|false

bzdecompress() は、bzip2 形式のデータを含む文字列を解凍します。

パラメータ

data

解凍する文字列

use_less_memory

true の場合、よりメモリの消 費量が少ない (所要メモリは最大2300K程度まで少なくなります) 別の圧縮アルゴリズムが使用されますが、速度は約半分になってしまいます。

この機能に関する詳細については、» bzip2 ドキュメント を参照ください。

戻り値

解凍された文字列、もしくは or false。 エラー時はエラー数を返します。

変更履歴

バージョン | 説明
8.0.0 | use_less_memory の型は int から bool に変更されました。 これより前のバージョンでは、 デフォルト値は 0 でした。

例

例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形式のデータに圧縮する


bzip2 エラー番号を返す

  • ≪ bzdecompress
  • bzerror ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 エラー番号を返す

bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — bzip2 エラー番号を返す

説明

bzerrno(resource $bz): int

与えられたファイルポインタから返された bzip2 エラーのエラー番号を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

戻り値

整数としてのエラー番号を返します。

参考

  • bzerror() - bzip2 エラー番号とエラー文字列を配列で返す
  • bzerrstr() - bzip2 エラー文字列を返す


bzip2 エラー番号とエラー文字列を配列で返す

  • ≪ bzerrno
  • bzerrstr ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 エラー番号とエラー文字列を配列で返す

bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — bzip2 エラー番号とエラー文字列を配列で返す

説明

bzerror(resource $bz): array

与えられたファイルポインタから返された bzip2 エラーのエラー番号とエラー文字列を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

戻り値

errno エントリにエラーコード、errstr エントリにエラーメッセージを持つ連想配列を返します。

例

例1 bzerror() の例

<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>

参考

  • bzerrno() - bzip2 エラー番号を返す
  • bzerrstr() - bzip2 エラー文字列を返す


bzip2 エラー文字列を返す

  • ≪ bzerror
  • bzflush ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 エラー文字列を返す

bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — bzip2 エラー文字列を返す

説明

bzerrstr(resource $bz): string

与えられたファイルポインタから返された bzip2 エラーのエラーの文字列を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

戻り値

エラーメッセージを含む文字列を返します。

参考

  • bzerrno() - bzip2 エラー番号を返す
  • bzerror() - bzip2 エラー番号とエラー文字列を配列で返す


何もしない

  • ≪ bzerrstr
  • bzopen ≫
  • PHP Manual
  • Bzip2 関数
  • 何もしない

bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — 何もしない

説明

bzflush(resource $bz): bool

バッファリングされた全ての bzip2 データをファイルポインタ bz に書き込むことが想定された関数です。 しかし、libbz2 では null な関数として実装されており、何もしません。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • bzread() - バイナリ対応の bzip2 ファイル読み込み
  • bzwrite() - バイナリ対応の bzip2 ファイルへの書き込み


bzip2 圧縮されたファイルをオープンする

  • ≪ bzflush
  • bzread ≫
  • PHP Manual
  • Bzip2 関数
  • bzip2 圧縮されたファイルをオープンする

bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — bzip2 圧縮されたファイルをオープンする

説明

bzopen(string|resource $file, string $mode): resource|false

bzopen() は、 bzip2 (.bz2) ファイルを読み書き用にオープンします。

パラメータ

file

オープンするファイル名、あるいは既存のストリームリソース

mode

'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);

?>

参考

  • bzclose() - bzip2 ファイルを閉じる


バイナリ対応の bzip2 ファイル読み込み

  • ≪ bzopen
  • bzwrite ≫
  • PHP Manual
  • Bzip2 関数
  • バイナリ対応の bzip2 ファイル読み込み

bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — バイナリ対応の bzip2 ファイル読み込み

説明

bzread(resource $bz, int $length = 1024): string|false

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 圧縮されたファイルをオープンする


バイナリ対応の bzip2 ファイルへの書き込み

  • ≪ bzread
  • LZF ≫
  • PHP Manual
  • Bzip2 関数
  • バイナリ対応の bzip2 ファイルへの書き込み

bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

説明

bzwrite(resource $bz, string $data, ?int $length = null): int|false

bzwrite() は、文字列を与えられた bzip2 ファイルストリームに書き込みます。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

data

書き込むデータ

length

指定した場合、 (圧縮前の) length バイト分の書き込みが終ったか、 data の終端に達したかで書き込みは終了します。

戻り値

書き込んだバイト数、もしくはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 bzwrite() の例

<?php
$str = "uncompressed data";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>

参考

  • bzread() - バイナリ対応の bzip2 ファイル読み込み
  • bzopen() - bzip2 圧縮されたファイルをオープンする


LZF

  • はじめに
  • インストール/設定
    • インストール手順
  • LZF 関数
    • lzf_compress — LZF 圧縮を行う
    • lzf_decompress — LZF 圧縮を伸長する
    • lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する


はじめに

LZF は非常に高速な圧縮アルゴリズムで、わずかな速度の低下と引き換えに スペースを節約したい場合に適しています。 コンパイル時に速度もしくはスペースのどちらを優先して最適化を行うかを 選択することができます。この拡張モジュールは、Marc Lehmann による » liblzf ライブラリを用いて操作を行います。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • LZF
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://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 — LZF 圧縮を行う
  • lzf_decompress — LZF 圧縮を伸長する
  • lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する


LZF 圧縮を行う

  • ≪ LZF 関数
  • lzf_decompress ≫
  • PHP Manual
  • LZF 関数
  • LZF 圧縮を行う

lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — LZF 圧縮を行う

説明

lzf_compress(string $data): string

lzf_compress() は、指定された arg を LZF 符号化方式で圧縮します。

パラメータ

data

圧縮するデータ。

戻り値

圧縮されたデータを返します。エラー時には false を返します。

参考

  • lzf_decompress() - LZF 圧縮を伸長する


LZF 圧縮を伸長する

  • ≪ lzf_compress
  • lzf_optimized_for ≫
  • PHP Manual
  • LZF 関数
  • LZF 圧縮を伸長する

lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — LZF 圧縮を伸長する

説明

lzf_decompress(string $data): string

lzf_decompress() は、lzf で符号化された文字列を含む data を伸長します。

パラメータ

data

圧縮されたデータ。

戻り値

伸長したデータを返します。エラー時には false を返します。

参考

  • lzf_compress() - LZF 圧縮を行う


LZF 拡張モジュールの最適化指定を取得する

  • ≪ lzf_decompress
  • Phar ≫
  • PHP Manual
  • LZF 関数
  • LZF 拡張モジュールの最適化指定を取得する

lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

説明

lzf_optimized_for(): int

LZF 拡張モジュールが圧縮時に使用した最適化指定を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

LZF が速度に最適化されている場合に 1、圧縮率に最適化されている場合に 0 を返します。


Phar

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Phar アーカイブの使用法
    • Phar アーカイブの使用法: 導入
    • Phar アーカイブの使用法: phar ストリームラッパー
    • Phar アーカイブの使用法: Phar クラスおよび PharData クラス
  • Phar アーカイブの作成
    • Phar アーカイブの作成: 導入
  • phar って、tar や zip とは何が違うの?
    • Phar アーカイブの原料のうち、ファイル形式に依存しないもの
    • Phar ファイルのスタブ
    • Phar 形式と Tar 形式、Zip 形式の徹底比較
    • Tar 形式の phar アーカイブ
    • Zip 形式の phar アーカイブ
    • Phar ファイルフォーマット
    • グローバルな Phar ビットマップフラグ
    • Phar マニフェストのファイルエントリの定義
    • Phar のシグネチャの書式
  • Phar — 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::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::__destruct — アクティブな Phar オブジェクトを破棄する
    • Phar::extractTo — phar アーカイブの内容をディレクトリに展開する
    • Phar::getAlias — Phar のエイリアスを取得する
    • Phar::getMetadata — phar アーカイブのメタデータを返す
    • Phar::getModified — phar が変更されているかどうかを返す
    • Phar::getPath — 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::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する
    • Phar::webPhar — ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する
  • PharData — PharData クラス
    • PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する
    • PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する
    • PharData::addFromString — 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する
    • PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する
    • PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する
    • PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
    • PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
    • PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する
    • PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
    • PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
    • PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
    • PharData::decompress — Phar アーカイブ全体の圧縮を解除する
    • PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
    • PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する
    • PharData::delete — tar/zip アーカイブ内のファイルを削除する
    • PharData::__destruct — 実行不能な tar や zip アーカイブオブジェクトを破棄する
    • PharData::extractTo — tar/zip アーカイブの内容をディレクトリに展開する
    • PharData::isWritable — tar/zip アーカイブが変更可能な場合に true を返す
    • PharData::offsetSet — tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
    • PharData::offsetUnset — ファイルを tar/zip アーカイブから削除する
    • PharData::setAlias — ダミー関数 (Phar::setAlias は PharData では使用不能)
    • PharData::setDefaultStub — ダミー関数 (Phar::setDefaultStub は PharData では無効)
    • PharData::setMetadata — phar アーカイブのメタデータを設定する
    • PharData::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定する
    • PharData::setStub — ダミー関数 (Phar::setStub は PharData では使用不能)
  • PharFileInfo — PharFileInfo クラス
    • PharFileInfo::chmod — ファイル固有のパーミッションビットを設定する
    • PharFileInfo::compress — 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
    • PharFileInfo::__construct — Phar エントリオブジェクトを作成する
    • PharFileInfo::decompress — phar 内の現在の Phar エントリの圧縮を解除する
    • PharFileInfo::delMetadata — エントリのメタデータを削除する
    • PharFileInfo::__destruct — Phar エントリオブジェクトを破棄する
    • PharFileInfo::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする
    • PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
    • PharFileInfo::getContent — エントリの完全なファイルの内容を取得する
    • PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す
    • PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す
    • PharFileInfo::hasMetadata — エントリのメタデータを返す
    • PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる
    • PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる
    • PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharException — PharException クラス


はじめに

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、SHA-1、SHA-256 あるいは SHA-512 シグネチャで自動的に検証します。

最後に、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 アーカイブは、 動かす前に多少手を入れなければならないことがよくあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Phar
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

オプションとして、zlib 拡張モジュールおよび bzip2 拡張モジュールを有効にしておくと、 圧縮された phar をサポートすることができます。 さらに、OpenSSL の署名を使用するには、OpenSSL 拡張モジュールを有効にする必要があります。

zend.multibyte が有効になっている場合、 zend.detect_unicode も有効になっている必要があります。


インストール手順

Phar 拡張モジュールは PHP にバンドルされており、 デフォルトで有効になっています。 Phar のサポートを無効にするには、 --disable-phar を使ってください。

それより前のバージョンの PHP では PECL 拡張モジュールとしてインストールできます。 » PECL の Phar のページ には詳しい情報や過去の歴史があります。


実行時設定

php.ini の設定により動作が変化します。

ファイルシステムおよびストリームの設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
phar.readonly | "1" | INI_ALL |
phar.require_hash | "1" | INI_ALL |
phar.cache_list | "" | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

phar.readonly bool

このオプションを使用すると、phar ストリームや Phar オブジェクトによる Phar アーカイブの作成や変更ができなくなります。 この設定は、実運用環境では常に有効にしておくべきです。 phar 拡張モジュールのこの機能は、 サーバー上に他のセキュリティ上の脆弱性があった場合に php ベースのウィルスを直接作成されてしまうことにつながります。

注意:

この設定は、php.ini でしか解除できません。 phar.readonly を php.ini で無効にした場合は、 ユーザーがスクリプト内で phar.readonly の有効/無効を切りかえることができます。 phar.readonly を php.ini で有効にした場合は、 スクリプト内でこれを "再度有効にする" ことはできますが、無効にすることはできません。

phar.require_hash bool

このオプションを使用すると、署名つき (現在サポートしているのは MD5、SHA1、SHA256、SHA512、および OpenSSL) の Phar アーカイブのみをオープンするようになります。 署名を含まない Phar アーカイブの処理はできません。

注意:

この設定は、セキュリティ上の理由により php.ini でしか解除できません。 phar.require_hash を php.ini で無効にした場合は、 ユーザーがスクリプト内で phar.require_hash の有効/無効を切りかえることができます。 phar.require_hash を php.ini で有効にした場合は、 スクリプト内でこれを "再度有効にする" ことはできますが、無効にすることはできません。

この設定は、 PharData クラスで通常の tar ファイルを読み込む際には影響を及ぼしません。

警告

phar.require_hash は、それ自体はセキュリティ上の機能を提供しません。 壊れた Pharアーカイブを誤って実行することへの備えでしかありません。 Phar を改ざんできる人は、シグネチャを後で簡単に修正できてしまうからです。

phar.cache_list string

phar アーカイブをウェブサーバーの起動時に事前にパースさせるようにします。 これによりパフォーマンスが向上し、 ディスク上に配置した伝統的なファイルに近い速度で実行することができます。

例1 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 (int) | 0x00000000 | 圧縮しない
Phar::COMPRESSED (int) | 0x0000F000 | そのファイルが既に何らかの形式で圧縮されているかどうかを表すフラグとして用いるビットマスク
Phar::GZ (int) | 0x00001000 | zlib (gzip) 圧縮
Phar::BZ2 (int) | 0x00002000 | bzip2 圧縮
Phar ファイル形式定数
定数 | 値 | 説明
Phar::PHAR (int) | 1 | phar ファイル形式
Phar::TAR (int) | 2 | tar ファイル形式
Phar::ZIP (int) | 3 | zip ファイル形式
Phar 署名定数
定数 | 値 | 説明
Phar::MD5 (int) | 0x0001 | md5 ハッシュアルゴリズムでの署名
Phar::SHA1 (int) | 0x0002 | sha1 ハッシュアルゴリズムでの署名
Phar::SHA256 (int) | 0x0003 | sha256 ハッシュアルゴリズムでの署名 (hash 拡張モジュールが必要)
Phar::SHA512 (int) | 0x0004 | sha512 ハッシュアルゴリズムでの署名 (hash 拡張モジュールが必要)
Phar::OPENSSL (int) | 0x0010 | OpenSSL 公開鍵/秘密鍵 ペアでの署名。真の意味での非対称鍵による署名。
Phar::OPENSSL_SHA256 (int) |  |
Phar::OPENSSL_SHA512 (int) |  |
Phar webPhar mime オーバーライド定数
定数 | 値 | 説明
Phar::PHP (int) | 0 | Phar::webPhar() の mimeoverrides パラメータに対して、その拡張子を PHP ファイルとしてパースするよう指示する
Phar::PHPS (int) | 1 | Phar::webPhar() の mimeoverrides パラメータに対して、その拡張子を PHP ファイルとしてパースして highlight_file() を通すよう指示する


Phar アーカイブの使用法

目次

  • Phar アーカイブの使用法: 導入
  • Phar アーカイブの使用法: phar ストリームラッパー
  • Phar アーカイブの使用法: Phar クラスおよび PharData クラス


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 RecursiveDirectoryIterator('/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 を使用した非対称公開鍵/秘密鍵ペアによる署名のいずれかを使用します。 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 署名の検証ができなくなります。

Phar には 3 つのstaticメソッド 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()、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 クラスおよび PharData クラス
  • Phar アーカイブの作成: 導入 ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの作成

Phar アーカイブの作成

目次

  • Phar アーカイブの作成: 導入


Phar アーカイブの作成: 導入

そのうちにきちんと書きます。今のところは、とりあえず Phar アーカイブの使用法 を読んでおいてください。

まず最初のとっかかりとしては Phar::buildFromIterator() を読むといいでしょう。そして、アーカイブで使用できる ファイル形式 の詳細を確認します。 phar アーカイブを作成するには、スタブについてきちんと理解しておくことが大切です。 そのためには Phar::setStub() と Phar::createDefaultStub() を調べるといいでしょう。 ウェブアプリケーションを配布しようと考えているのなら、 Phar::webPhar() と Phar::mungServer() について調べてみましょう。 アーカイブ内のファイルにアクセスするアプリケーションを作成する場合は Phar::interceptFileFuncs() の使用を検討しましょう。


phar って、tar や zip とは何が違うの?

目次

  • Phar アーカイブの原料のうち、ファイル形式に依存しないもの
  • Phar ファイルのスタブ
  • Phar 形式と Tar 形式、Zip 形式の徹底比較
  • Tar 形式の phar アーカイブ
  • Zip 形式の phar アーカイブ
  • Phar ファイルフォーマット
  • グローバルな Phar ビットマップフラグ
  • Phar マニフェストのファイルエントリの定義
  • Phar のシグネチャの書式


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
ウェブアプリケーションへの対応 | 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 拡張モジュールで実行できます。

pax 中間フォーマット経由で、tarボールを読み込む機能も限定的ながらサポートされていますが、 全ての認識される pax ヘッダ (今のところ、型フラグ x と g) は静かに無視されます。 GNU tar アーカイブも限定的ながらサポートされていますが、 今のところ、././@LongLink を解決するのみにとどまっています。

アーカイブ全体を圧縮するには Phar::compress() を使用します。 アーカイブ全体の圧縮を解くには Phar::decompress() を使用します。


Zip 形式の phar アーカイブ

zip 形式のアーカイブは、zip ファイル形式に組み込まれているいくつかの機能に対応しています。 ファイルごとのメタデータやアーカイブ全体のメタデータを、 文字列にシリアル化して zip ファイルのコメントや zip アーカイブのコメントとして格納することができます。 また、既存の zip コメントも文字列として読み込むことができます。 zlib 圧縮ではファイル単位の DEFLATE 圧縮の読み書き、 そして 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 DEFLATE 圧縮されたファイルが少なくともひとつ含まれます。
0x00002000 | 設定されている場合、この Phar には bzip2 圧縮されたファイルが少なくともひとつ含まれます。


Phar マニフェストのファイルエントリの定義

マニフェスト内の各ファイルについて、次のような情報が含まれます。

Phar マニフェストのファイルエントリ
バイト数 | 説明
4 バイト | ファイル名の長さを表すバイト数。
?? | ファイル名 (先ほど指定した長さになります)。
4 バイト | 圧縮前のファイルサイズを表すバイト数。
4 バイト | ファイルの Unix タイムスタンプ。
4 バイト | 圧縮後のファイルサイズを表すバイト数。
4 バイト | 圧縮前のファイルの CRC32 チェックサム。
4 バイト | ファイル固有のビットマップフラグ。
4 バイト | シリアライズされたファイルのメタデータの長さ (存在しない場合は 0)。
?? | シリアライズされたファイルのメタデータ。serialize() の形式で格納される。

API バージョン 1.1.1 では、空のディレクトリの最後にスラッシュをつけて my/directory/ のような形式で保存されることに注意しましょう。

ファイル固有のビットマップ値として認識される値は次のとおりです。

認識されるビットマップ値
値 | 説明
0x000001FF | これらのビットは、ファイルの特定のパーミッションを定義するために予約されています。 このパーミッションは fstat() で用いられ、 ファイルを展開する際に特定のパーミッションを指定することができます。
0x00001000 | 設定されている場合、このファイルは zlib DEFLATE 圧縮されています。
0x00002000 | 設定されている場合、このファイルは bzip2 圧縮されています。


Phar のシグネチャの書式

シグネチャを含む Phar は、常にシグネチャを保持しています。 シグネチャの場所は、 ローダ、マニフェスト、実際のファイルの内容に続く Phar アーカイブの最後の部分です。 現在サポートしているシグネチャのフォーマットは MD5, SHA1, SHA256, SHA512, OPENSSL です。

シグネチャのフォーマット
バイト長 | 説明
可変長 | 実際のシグネチャ。SHA1 の場合は 20 バイト、 MD5 の場合は 16 バイト、 SHA256 の場合は 32 バイト、 そして SHA512 の場合は 64 バイトとなります。 OPENSSL の場合は、秘密鍵の長さに応じて変化します。
4 バイト | シグネチャのフラグ。0x0001 は MD5 シグネチャ、そして 0x0002 は SHA1 シグネチャ、 0x0003 は SHA256 シグネチャ、 0x0004 は SHA512 シグネチャを表します。 SHA256 および SHA512 は、API バージョン 1.1.0 以降で利用可能です。 0x0010 は OPENSSL シグネチャを表します。 これは API バージョン 1.1.1 以降、 かつ OpenSSL と共にビルドされている場合にのみ利用可能です。
4 バイト | GBMB という固定値で、 シグネチャが存在することを表します。


Phar クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

はじめに

Phar クラスは、phar アーカイブへのアクセスや作成のための高レベルインターフェイスを提供します。

クラス概要

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* 継承した定数 */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* 定数 */
const int BZ2;
const int GZ;
const int NONE;
const int PHAR;
const int TAR;
const int ZIP;
const int COMPRESSED;
const int PHP;
const int PHPS;
const int MD5;
const int OPENSSL;
const int OPENSSL_SHA256;
const int OPENSSL_SHA512;
const int SHA1;
const int SHA256;
const int SHA512;
/* メソッド */
public __construct(string $filename, int $flags = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string $alias = null)
public addEmptyDir(string $directory): void
public addFile(string $filename, ?string $localName = null): void
public addFromString(string $localName, string $contents): void
final public static apiVersion(): string
public buildFromDirectory(string $directory, string $pattern = ""): array
public buildFromIterator(Traversable $iterator, ?string $baseDirectory = null): array
final public static canCompress(int $compression = 0): bool
final public static canWrite(): bool
public compress(int $compression, ?string $extension = null): ?Phar
public compressFiles(int $compression): void
public convertToData(?int $format = null, ?int $compression = null, ?string $extension = null): ?PharData
public convertToExecutable(?int $format = null, ?int $compression = null, ?string $extension = null): ?Phar
public copy(string $from, string $to): bool
public count(int $mode = COUNT_NORMAL): int
final public static createDefaultStub(?string $index = null, ?string $webIndex = null): string
public decompress(?string $extension = null): ?Phar
public decompressFiles(): bool
public delMetadata(): bool
public delete(string $localName): bool
public extractTo(string $directory, array|string|null $files = null, bool $overwrite = false): bool
public getAlias(): ?string
public getMetadata(array $unserializeOptions = []): mixed
public getModified(): bool
public getPath(): string
public getSignature(): array|false
public getStub(): string
final public static getSupportedCompression(): array
final public static getSupportedSignatures(): array
public getVersion(): string
public hasMetadata(): bool
final public static interceptFileFuncs(): void
public isBuffering(): bool
public isCompressed(): int|false
public isFileFormat(int $format): bool
final public static isValidPharFilename(string $filename, bool $executable = true): bool
public isWritable(): bool
final public static loadPhar(string $filename, ?string $alias = null): bool
final public static mapPhar(?string $alias = null, int $offset = 0): bool
final public static mount(string $pharPath, string $externalPath): void
final public static mungServer(array $variables): void
public offsetExists(string $localName): bool
public offsetGet(string $localName): SplFileInfo
public offsetSet(string $localName, resource|string $value): void
public offsetUnset(string $localName): void
final public static running(bool $returnPhar = true): string
public setAlias(string $alias): bool
public setDefaultStub(?string $index = null, ?string $webIndex = null): bool
public setMetadata(mixed $metadata): void
public setSignatureAlgorithm(int $algo, ?string $privateKey = null): void
public setStub(resource|string $stub, int $length = -1): bool
public startBuffering(): void
public stopBuffering(): void
final public static unlinkArchive(string $filename): bool
final public static webPhar(
?string $alias = null,
?string $index = null,
?string $fileNotFoundScript = null,
array $mimeTypes = [],
?callable $rewrite = null
): void
public __destruct()
/* 継承したメソッド */
public RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public RecursiveDirectoryIterator::getSubPath(): string
public RecursiveDirectoryIterator::getSubPathname(): string
public RecursiveDirectoryIterator::hasChildren(bool $allowLinks = false): bool
public RecursiveDirectoryIterator::key(): string
public RecursiveDirectoryIterator::next(): void
public RecursiveDirectoryIterator::rewind(): void
public FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public FilesystemIterator::getFlags(): int
public FilesystemIterator::key(): string
public FilesystemIterator::next(): void
public FilesystemIterator::rewind(): void
public FilesystemIterator::setFlags(int $flags): void
public DirectoryIterator::current(): mixed
public DirectoryIterator::getBasename(string $suffix = ""): string
public DirectoryIterator::getExtension(): string
public DirectoryIterator::getFilename(): string
public DirectoryIterator::isDot(): bool
public DirectoryIterator::key(): mixed
public DirectoryIterator::next(): void
public DirectoryIterator::rewind(): void
public DirectoryIterator::seek(int $offset): void
public DirectoryIterator::__toString(): string
public DirectoryIterator::valid(): bool
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • 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::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::__destruct — アクティブな Phar オブジェクトを破棄する
  • Phar::extractTo — phar アーカイブの内容をディレクトリに展開する
  • Phar::getAlias — Phar のエイリアスを取得する
  • Phar::getMetadata — phar アーカイブのメタデータを返す
  • Phar::getModified — phar が変更されているかどうかを返す
  • Phar::getPath — 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::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する
  • Phar::webPhar — ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する


空のディレクトリを phar アーカイブに追加する

  • ≪ Phar
  • Phar::addFile ≫
  • PHP Manual
  • Phar
  • 空のディレクトリを phar アーカイブに追加する

Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — 空のディレクトリを phar アーカイブに追加する

説明

public Phar::addEmptyDir(string $directory): void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、空のディレクトリが dirname に作成されます。このメソッドは ZipArchive::addEmptyDir() と同じようなものです。

パラメータ

directory

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 アーカイブに追加する

  • ≪ Phar::addEmptyDir
  • Phar::addFromString ≫
  • PHP Manual
  • Phar
  • ファイルシステム上のファイルを phar アーカイブに追加する

Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — ファイルシステム上のファイルを phar アーカイブに追加する

説明

public Phar::addFile(string $filename, ?string $localName = null): void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、任意のファイルあるいは URL を phar アーカイブに追加することができます。 オプションの 2 番目のパラメータ localName が文字列の場合、 ファイルはその名前でアーカイブ内に格納されます。指定しなかった場合は、 file パラメータをアーカイブ内のパスとして使用します。 URL を使用する場合は、localname を指定しないと例外がスローされます。 このメソッドは ZipArchive::addFile() と同じようなものです。

パラメータ

filename

phar アーカイブに追加したいディスク上のファイルへのフルパスあるいは相対パス。

localName

ファイルをアーカイブ内に格納するときのパス。

戻り値

戻り値はありません。失敗時には例外をスローします。

変更履歴

バージョン | 説明
8.0.0 | localName は、nullable になりました。

例

例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::addFile(), Phar::addFromString(), Phar::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに Phar::buildFromDirectory() や Phar::buildFromIterator() を使うべきです。

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • Phar::addFromString() - 文字列から、ファイルを phar アーカイブに追加する
  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する


文字列から、ファイルを phar アーカイブに追加する

  • ≪ Phar::addFile
  • Phar::apiVersion ≫
  • PHP Manual
  • Phar
  • 文字列から、ファイルを phar アーカイブに追加する

Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — 文字列から、ファイルを phar アーカイブに追加する

説明

public Phar::addFromString(string $localName, string $contents): void

注意:

このメソッドは、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::addFile(), Phar::addFromString(), Phar::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに Phar::buildFromDirectory() や Phar::buildFromIterator() を使うべきです。

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • PharData::addFromString() - 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する


API のバージョンを返す

  • ≪ Phar::addFromString
  • Phar::buildFromDirectory ≫
  • PHP Manual
  • Phar
  • API のバージョンを返す

Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — API のバージョンを返す

説明

final public static Phar::apiVersion(): string

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 を作成する

  • ≪ Phar::apiVersion
  • Phar::buildFromIterator ≫
  • PHP Manual
  • Phar
  • ディレクトリ内のファイルから phar を作成する

Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — ディレクトリ内のファイルから phar を作成する

説明

public Phar::buildFromDirectory(string $directory, string $pattern = ""): array

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

ディレクトリの中身をもとに phar アーカイブを作成します。 オプションの 2 番目のパラメータで正規表現 (pcre) を指定すると、特定のファイルを除外することができます。 正規表現にマッチするすべてのファイルがアーカイブに含められ、 それ以外のファイルは除外されます。より詳細に制御するには Phar::buildFromIterator() を使用します。

パラメータ

directory

アーカイブに追加するすべてのファイルを含むディレクトリへの フルパスあるいは相対パス。

pattern

オプションで指定する pcre 正規表現。 これを使用してファイル一覧をフィルタリングします。 正規表現にマッチするファイルパスのみがアーカイブに追加されます。

戻り値

Phar::buildFromDirectory() は、連想配列を返します。これは、 ファイルの内部パスをファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、内部ディレクトリイテレータのインスタンスの作成に失敗したときに BadMethodCallException をスローします。 また、phar アーカイブの保存時にエラーが発生した場合は PharException をスローします。

変更履歴

バージョン | 説明
8.1.0 | Phar::buildFromDirectory() は、 false を返さなくなりました。

例

例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() - イテレータから phar アーカイブを作成する


イテレータから phar アーカイブを作成する

  • ≪ Phar::buildFromDirectory
  • Phar::canCompress ≫
  • PHP Manual
  • Phar
  • イテレータから phar アーカイブを作成する

Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — イテレータから phar アーカイブを作成する

説明

public Phar::buildFromIterator(Traversable $iterator, ?string $baseDirectory = null): array

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブをイテレータから作成します。 サポートするイテレータは二種類で、 phar 内のファイル名とディスク上の実際のファイル名を対応させたものか、あるいは DirectoryIterator のように SplFileInfo オブジェクトを返すものです。 SplFileInfo オブジェクトを返すイテレータの場合は、2 番目のパラメータが必要となります。

パラメータ

iterator

phar ファイルと実際の場所の関連を返すイテレータ、 あるいは SplFileInfo オブジェクトを返すイテレータ。

baseDirectory

SplFileInfo オブジェクトを返すイテレータを指定した際、 phar アーカイブへの追加時にフルパスから取り除く部分。

戻り値

Phar::buildFromIterator() は連想配列を返します。 これは、ファイルの内部パスとファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、イテレータが間違った値 (たとえば文字列キーではなく整数キーなど) を返した場合に UnexpectedValueException を返します。また、SplFileInfo 型のイテレータを渡したときに baseDirectory を指定しなかった場合は BadMethodCallException を、 phar アーカイブの保存時にエラーが発生した場合は PharException を返します。

変更履歴

バージョン | 説明
8.1.0 | Phar::buildFromIterator() は、 false を返さなくなりました。
8.0.0 | baseDirectory は、nullable になりました。

例

例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'));
?>

参考

  • Phar::buildFromDirectory() - ディレクトリ内のファイルから phar を作成する


phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

  • ≪ Phar::buildFromIterator
  • Phar::canWrite ≫
  • PHP Manual
  • Phar
  • phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

説明

final public static Phar::canCompress(int $compression = 0): bool

これは、圧縮されたファイルを含む phar を読み込む前に、 圧縮が可能かどうかを調べるために使用します。

パラメータ

compression

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 '圧縮はできません';
}
?>

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する


phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

  • ≪ Phar::canCompress
  • Phar::compress ≫
  • PHP Manual
  • Phar
  • phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

説明

final public static Phar::canWrite(): bool

このstaticメソッドは、書き込みアクセスが php.ini の phar.readonly で無効にされているかどうかを調べます。

パラメータ

戻り値

書き込みが可能な場合に true、そうでない場合に false を返します。

例

例1 Phar::canWrite() の例

<?php
if (Phar::canWrite()) {
file_put_contents('phar://myphar.phar/file.txt', 'hi there');
}
?>

参考

  • phar.readonly
  • Phar::isWritable() - phar アーカイブが変更可能な場合に true を返す


Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

  • ≪ Phar::canWrite
  • Phar::compressFiles ≫
  • PHP Manual
  • Phar
  • Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

説明

public Phar::compress(int $compression, ?string $extension = null): ?Phar

注意:

このメソッドは、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 オブジェクトを返します。 失敗した場合は null を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

変更履歴

バージョン | 説明
8.0.0 | extension は、nullable になりました。

例

例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 は既に存在します
?>

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する


現在の Phar アーカイブ内のすべてのファイルを圧縮する

  • ≪ Phar::compress
  • Phar::__construct ≫
  • PHP Manual
  • Phar
  • 現在の Phar アーカイブ内のすべてのファイルを圧縮する

Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — 現在の Phar アーカイブ内のすべてのファイルを圧縮する

説明

public Phar::compressFiles(int $compression): void

注意:

このメソッドは、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)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する


Phar アーカイブオブジェクトを作成する

  • ≪ Phar::compressFiles
  • Phar::convertToData ≫
  • PHP Manual
  • Phar
  • Phar アーカイブオブジェクトを作成する

Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Phar アーカイブオブジェクトを作成する

説明

public Phar::__construct(string $filename, int $flags = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string $alias = null)

パラメータ

filename

既存の Phar アーカイブ、あるいは作成したいアーカイブへのパス。 ファイル名の拡張子は .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 アーカイブを実行可能でない tar あるいは zip ファイルに変換する

  • ≪ Phar::__construct
  • Phar::convertToExecutable ≫
  • PHP Manual
  • Phar
  • phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

説明

public Phar::convertToData(?int $format = null, ?int $compression = null, ?string $extension = null): ?PharData

このメソッドは、実行可能な 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 オブジェクトを返します。失敗した場合は null を返します。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、phar 作成中に何らかの問題が発生した場合に PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | format、 compression、 extension は、nullable になりました。

例

例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() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • PharData::convertToExecutable() - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
  • PharData::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する


phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

  • ≪ Phar::convertToData
  • Phar::copy ≫
  • PHP Manual
  • Phar
  • phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

説明

public Phar::convertToExecutable(?int $format = null, ?int $compression = null, ?string $extension = null): ?Phar

注意:

このメソッドは、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 オブジェクトを返します。失敗した場合は null を返します。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、書き込みサポートが無効な場合に UnexpectedValueException、 phar 作成中に何らかの問題が発生した場合に PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | format、 compression、 extension は、nullable になりました。

例

例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::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToExecutable() - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
  • PharData::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する


phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

  • ≪ Phar::convertToExecutable
  • Phar::count ≫
  • PHP Manual
  • Phar
  • phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

説明

public Phar::copy(string $from, string $to): bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

パラメータ

from

to

戻り値

成功した場合に 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 アーカイブ内のエントリ (ファイル) の数を返す

  • ≪ Phar::copy
  • Phar::createDefaultStub ≫
  • PHP Manual
  • Phar
  • Phar アーカイブ内のエントリ (ファイル) の数を返す

Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Phar アーカイブ内のエントリ (ファイル) の数を返す

説明

public Phar::count(int $mode = COUNT_NORMAL): int

パラメータ

mode

mode は、数え上げるモードを指定する整数です。 デフォルトは、COUNT_NORMAL です。 これは、削除されたり、隠されたりしていない、アーカイブ内のアイテムの数を数えます。 COUNT_RECURSIVE に設定すると、 削除されたり、既に隠されたものを含む、アーカイブ内のすべてのアイテムの数を数えます。

戻り値

この 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 ファイルフォーマット用のスタブを作成する

  • ≪ Phar::count
  • Phar::decompress ≫
  • PHP Manual
  • Phar
  • phar ファイルフォーマット用のスタブを作成する

Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — phar ファイルフォーマット用のスタブを作成する

説明

final public static Phar::createDefaultStub(?string $index = null, ?string $webIndex = null): string

このメソッドは、phar ファイル形式のスタブを作成するためのもので、 tar 形式や zip 形式の phar アーカイブでは使用しません。

PHP でかかれた起動ローダー (スタブ) を含む Phar アーカイブを PHP から実行するには、次のようにそれをインクルードするか、

<?php
include 'myphar.phar';
?>
あるいは単に実行します。
php myphar.phar

このメソッドは、phar アーカイブの起動時に実行するスタブ用のメソッドを作成します。 さらに、phar アーカイブをコマンドラインやウェブサーバーから実行する際には別のファイルを指定することもできます。 ローダースタブは Phar::interceptFileFuncs() もコールでき、PHP のアプリケーションからファイルシステムを簡単に扱えるようになります。 phar 拡張モジュールが存在しない場合は、 ローダースタブが phar アーカイブの内容を一時ディレクトリに展開し、 そのファイルを操作します。 シャットダウン関数が、この一時ファイル群を削除します。

パラメータ

index

コマンドラインからアクセスする場合に、 実行する phar アーカイブ内の相対パス。

webIndex

Webブラウザからアクセスする場合に、 実行する phar アーカイブ内の相対パス。

戻り値

独自の起動ローダー (スタブ) を文字列で返します。 これを用いて作成した Phar アーカイブは、 Phar 拡張モジュールが有効になっていない環境でも実行することができます。

エラー / 例外

パラメータの長さが 400 バイトをこえる場合に UnexpectedValueException をスローします。

変更履歴

バージョン | 説明
8.0.0 | index と webIndex は、nullable になりました。

例

例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 アーカイブ全体の圧縮を解除する

  • ≪ Phar::createDefaultStub
  • Phar::decompressFiles ≫
  • PHP Manual
  • Phar
  • Phar アーカイブ全体の圧縮を解除する

Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Phar アーカイブ全体の圧縮を解除する

説明

public Phar::decompress(?string $extension = null): ?Phar

注意:

このメソッドは、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 オブジェクトを返します。 失敗した場合は null を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

変更履歴

バージョン | 説明
8.0.0 | extension は、nullable になりました。

例

例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 を作成します
?>

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する


現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

  • ≪ Phar::decompress
  • Phar::delMetadata ≫
  • PHP Manual
  • Phar
  • 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

説明

public Phar::decompressFiles(): bool

注意:

このメソッドは、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)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する


phar のグローバルメタデータを削除する

  • ≪ Phar::decompressFiles
  • Phar::delete ≫
  • PHP Manual
  • Phar
  • phar のグローバルメタデータを削除する

Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — phar のグローバルメタデータを削除する

説明

public Phar::delMetadata(): bool

注意:

このメソッドは、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::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す


phar アーカイブ内のファイルを削除する

  • ≪ Phar::delMetadata
  • Phar::__destruct ≫
  • PHP Manual
  • Phar
  • phar アーカイブ内のファイルを削除する

Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — phar アーカイブ内のファイルを削除する

説明

public Phar::delete(string $localName): bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で unlink() をコールするのと同じ意味です。以下に例を示します。

パラメータ

localName

削除したいファイルの、アーカイブ内でのパス。

戻り値

成功した場合に 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) {
// エラー処理
}
?>

参考

  • PharData::delete() - tar/zip アーカイブ内のファイルを削除する
  • Phar::unlinkArchive() - phar アーカイブをディスクとメモリから完全に削除する


アクティブな Phar オブジェクトを破棄する

  • ≪ Phar::delete
  • Phar::extractTo ≫
  • PHP Manual
  • Phar
  • アクティブな Phar オブジェクトを破棄する

Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — アクティブな Phar オブジェクトを破棄する

説明

public Phar::__destruct()

パラメータ

この関数にはパラメータはありません。


phar アーカイブの内容をディレクトリに展開する

  • ≪ Phar::__destruct
  • Phar::getAlias ≫
  • PHP Manual
  • Phar
  • phar アーカイブの内容をディレクトリに展開する

Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — phar アーカイブの内容をディレクトリに展開する

説明

public Phar::extractTo(string $directory, array|string|null $files = null, bool $overwrite = false): bool

phar アーカイブ内のすべてのファイルをディスクに展開します。 展開されたファイルやディレクトリは、アーカイブに保存されたときのパーミッションを維持しています。 オプションのパラメータを使用すると、どのファイルを展開するかを制御したり 既存のファイルを上書きするかどうかを指定したりすることができます。 2 番目のパラメータ files には、 展開したいファイルやディレクトリの名前、あるいはその配列を指定します。 デフォルトでは、このメソッドは既存のファイルを上書きしません。 3 番目のパラメータを true にすると既存のファイルを上書きさせることができます。 このメソッドは ZipArchive::extractTo() と同じようなものです。

パラメータ

directory

指定した files の展開先のパス。

files

展開したいファイル名/ディレクトリ名、あるいはその配列。 この引数をスキップするには null を指定します。

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) {
// エラー処理
}
?>

注意

注意:

Windows の NTFS ファイルシステムには、ファイル名で使う場合にサポートしていない文字があります。具体的には、<|>*?": です。末尾にドットがあるファイル名もサポートしていません。いくつかの展開ツールと異なり、このメソッドはこれらの文字をアンダースコアで置き換えませんし、そのようなファイルを展開すると失敗します。

参考

  • PharData::extractTo() - tar/zip アーカイブの内容をディレクトリに展開する


Phar のエイリアスを取得する

  • ≪ Phar::extractTo
  • Phar::getMetadata ≫
  • PHP Manual
  • Phar
  • Phar のエイリアスを取得する

Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Phar のエイリアスを取得する

説明

public Phar::getAlias(): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

エイリアスを返します。エイリアスがない場合は null を返します。


phar アーカイブのメタデータを返す

  • ≪ Phar::getAlias
  • Phar::getModified ≫
  • PHP Manual
  • Phar
  • phar アーカイブのメタデータを返す

Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — phar アーカイブのメタデータを返す

説明

public Phar::getMetadata(array $unserializeOptions = []): mixed

アーカイブのメタデータを取得します。メタデータは、PHP の任意の変数をシリアライズしたものです。

パラメータ

パラメータはありません。

戻り値

Phar アーカイブのメタデータとして保存されている、シリアライズ可能な任意の PHP の値を返します。 メタデータが保存されていない場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 unserializeOptions が追加されました。

例

例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::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::delMetadata() - phar のグローバルメタデータを削除する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す


phar が変更されているかどうかを返す

  • ≪ Phar::getMetadata
  • Phar::getPath ≫
  • PHP Manual
  • Phar
  • phar が変更されているかどうかを返す

Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — phar が変更されているかどうかを返す

説明

public Phar::getModified(): bool

このメソッドを使用すると、phar 内のファイルが 削除されたり変更されたりしているかどうかを判断できます。

パラメータ

パラメータはありません。

戻り値

オープンした後でファイルが変更されている場合に true、 そうでない場合に false を返します。


Pharアーカイブのディスク上の実際のパスを取得する

  • ≪ Phar::getModified
  • Phar::getSignature ≫
  • PHP Manual
  • Phar
  • Pharアーカイブのディスク上の実際のパスを取得する

Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Pharアーカイブのディスク上の実際のパスを取得する

説明

public Phar::getPath(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

  • ≪ Phar::getPath
  • Phar::getStub ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignature — Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

説明

public Phar::getSignature(): array|false

phar アーカイブの検証用シグネチャを、 十六進文字列で返します。

パラメータ

戻り値

開いているアーカイブのシグネチャを配列で返します。 キー hash にはシグネチャ自体を、そしてキー hash_type には MD5、SHA-1、 SHA-256、SHA-512 あるいは OpenSSL を格納します。 このシグネチャは phar の中身全体から計算したハッシュで、 アーカイブの整合性を検証する際に使用します。 INI 設定 phar.require_hash が true の場合は、すべての実行可能な phar が有効なシグネチャを持っている必要があります。 シグネチャが存在しない場合、この関数は false を返します。


Phar アーカイブの PHP ローダーあるいは起動スタブを返す

  • ≪ Phar::getSignature
  • Phar::getSupportedCompression ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの PHP ローダーあるいは起動スタブを返す

Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Phar アーカイブの PHP ローダーあるいは起動スタブを返す

説明

public Phar::getStub(): string

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::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する


サポートする圧縮アルゴリズムの配列を返す

  • ≪ Phar::getStub
  • Phar::getSupportedSignatures ≫
  • PHP Manual
  • Phar
  • サポートする圧縮アルゴリズムの配列を返す

Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — サポートする圧縮アルゴリズムの配列を返す

説明

final public static Phar::getSupportedCompression(): array

パラメータ

パラメータはありません。

戻り値

Phar::GZ あるいは Phar::BZ2 を含む配列を返します。 これは、zlib 拡張モジュールと bz2 拡張モジュールが使用可能かどうかによって決まります。

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する


サポートするシグネチャ型の配列を返す

  • ≪ Phar::getSupportedCompression
  • Phar::getVersion ≫
  • PHP Manual
  • Phar
  • サポートするシグネチャ型の配列を返す

Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — サポートするシグネチャ型の配列を返す

説明

final public static Phar::getSupportedSignatures(): array

サポートするシグネチャ型の配列を返します。

パラメータ

パラメータはありません。

戻り値

MD5、SHA-1、 SHA-256、SHA-512 あるいは OpenSSL を含む配列を返します。

参考

  • Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す
  • Phar::setSignatureAlgorithm() - phar のシグネチャのアルゴリズムを設定して適用する


Phar アーカイブのバージョン情報を返す

  • ≪ Phar::getSupportedSignatures
  • Phar::hasMetadata ≫
  • PHP Manual
  • Phar
  • Phar アーカイブのバージョン情報を返す

Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Phar アーカイブのバージョン情報を返す

説明

public Phar::getVersion(): string

オープンした Phar アーカイブの API バージョンを返します。

パラメータ

戻り値

オープンしたアーカイブの API バージョンを返します。 これは、読み込んだ phar 拡張モジュールが新しい phar を作成する際に使用する API バージョンとは異なります。各 Phar アーカイブは、 マニフェスト内に API バージョンをハードコードして保持しています。 詳細は Phar ファイルフォーマット のドキュメントを参照ください。

参考

  • Phar::apiVersion() - API のバージョンを返す


ファイルがグローバルなメタデータを持つかどうかを返す

  • ≪ Phar::getVersion
  • Phar::interceptFileFuncs ≫
  • PHP Manual
  • Phar
  • ファイルがグローバルなメタデータを持つかどうかを返す

Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — ファイルがグローバルなメタデータを持つかどうかを返す

説明

public Phar::hasMetadata(): bool

ファイルがグローバルなメタデータを持っているかどうかを返します。

パラメータ

パラメータはありません。

戻り値

メタデータが設定されている場合に 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::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::delMetadata() - phar のグローバルメタデータを削除する


fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

  • ≪ Phar::hasMetadata
  • Phar::isBuffering ≫
  • PHP Manual
  • Phar
  • fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

説明

final public static 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 の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

  • ≪ Phar::interceptFileFuncs
  • Phar::isCompressed ≫
  • PHP Manual
  • Phar
  • Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

説明

public Phar::isBuffering(): bool

このメソッドを使用すると、その 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 アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

  • ≪ Phar::isBuffering
  • Phar::isFileFormat ≫
  • PHP Manual
  • Phar
  • phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressed — phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

説明

public Phar::isCompressed(): int|false

注意:

このメソッドは、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->compress(Phar::GZ);
var_dump($phar2->isCompressed() == Phar::GZ);
} catch (Exception $e) {
}
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(true)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す


phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

  • ≪ Phar::isCompressed
  • Phar::isValidPharFilename ≫
  • PHP Manual
  • Phar
  • phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

説明

public Phar::isFileFormat(int $format): bool

パラメータ

format

Phar::PHAR、Phar::TAR あるいは Phar::ZIP で、アーカイブの形式を指定します。

戻り値

phar アーカイブのファイル形式がパラメータで指定したものと一致する場合に true を返します。

エラー / 例外

パラメータで指定した内容が既知の形式でない場合に PharException をスローします。

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する


指定したファイル名が正しい形式の phar ファイルかどうかを返す

  • ≪ Phar::isFileFormat
  • Phar::isWritable ≫
  • PHP Manual
  • Phar
  • 指定したファイル名が正しい形式の phar ファイルかどうかを返す

Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — 指定したファイル名が正しい形式の phar ファイルかどうかを返す

説明

final public static Phar::isValidPharFilename(string $filename, bool $executable = true): bool

指定したファイル名のファイルが、phar 拡張モジュールで利用できる 正しい形式の phar ファイルであるかどうかを返します。 これは、phar アーカイブを実際に開く前にそのファイルを確認する際に使用します。 これで、 無効なファイルを指定したときに当然発生するであろう例外の処理を省略することができます。

パラメータ

filename

まだ作成されていない phar アーカイブの名前あるいはフルパス。

executable

このパラメータは、指定した名前のファイルを phar の実行可能アーカイブとして扱うかデータのみの非実行可能アーカイブとして扱うかを指定します。

戻り値

正しい形式のファイルである場合に true、そうでない場合に false を返します。


phar アーカイブが変更可能な場合に true を返す

  • ≪ Phar::isValidPharFilename
  • Phar::loadPhar ≫
  • PHP Manual
  • Phar
  • phar アーカイブが変更可能な場合に true を返す

Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — phar アーカイブが変更可能な場合に true を返す

説明

public Phar::isWritable(): bool

このメソッドは、phar.readonly が 0 かつディスク上の実際の phar アーカイブが読み取り専用でない場合に true を返します。

パラメータ

パラメータはありません。

戻り値

phar アーカイブが変更可能な場合に true を返します。

参考

  • Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
  • PharData::isWritable() - tar/zip アーカイブが変更可能な場合に true を返す


任意の phar アーカイブを、エイリアスを指定して読み込む

  • ≪ Phar::isWritable
  • Phar::mapPhar ≫
  • PHP Manual
  • Phar
  • 任意の phar アーカイブを、エイリアスを指定して読み込む

Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — 任意の phar アーカイブを、エイリアスを指定して読み込む

説明

final public static Phar::loadPhar(string $filename, ?string $alias = null): bool

これを使用して、外部の 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 形式の) ファイルを読み込み、その内容を登録する

  • ≪ Phar::loadPhar
  • Phar::mount ≫
  • PHP Manual
  • Phar
  • 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

説明

final public static Phar::mapPhar(?string $alias = null, int $offset = 0): bool

このstaticメソッドは、直接実行されたときや 他のスクリプトからインクルードされたときに Phar アーカイブのローダスタブ内で使用され、 phar を初期化します。

パラメータ

alias

このアーカイブを参照する際にフルパスのかわりに使用する、 phar:// 形式の URL。

offset

未使用。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 アーカイブ内に仮想的にマウントする

  • ≪ Phar::mapPhar
  • Phar::mungServer ≫
  • PHP Manual
  • Phar
  • 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

説明

final public static Phar::mount(string $pharPath, string $externalPath): void

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';
?>


最大 4 つまでの $_SERVER 変数を実行時に変更させる

  • ≪ Phar::mount
  • Phar::offsetExists ≫
  • PHP Manual
  • Phar
  • 最大 4 つまでの $_SERVER 変数を実行時に変更させる

Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — 最大 4 つまでの $_SERVER 変数を実行時に変更させる

説明

final public static Phar::mungServer(array $variables): void

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 となります。

パラメータ

variables

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 内に存在するかどうかを調べる

  • ≪ Phar::mungServer
  • Phar::offsetGet ≫
  • PHP Manual
  • Phar
  • ファイルが phar 内に存在するかどうかを調べる

Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — ファイルが phar 内に存在するかどうかを調べる

説明

public Phar::offsetExists(string $localName): bool

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。

offsetExists() は、isset() がコールされる際にはいつもコールされます。

パラメータ

localName

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() - 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • Phar::offsetUnset() - ファイルを phar から削除する


指定したファイルの PharFileInfo オブジェクトを取得する

  • ≪ Phar::offsetExists
  • Phar::offsetSet ≫
  • PHP Manual
  • Phar
  • 指定したファイルの PharFileInfo オブジェクトを取得する

Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — 指定したファイルの PharFileInfo オブジェクトを取得する

説明

public Phar::offsetGet(string $localName): SplFileInfo

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 Phar::offsetGet() を使用して、Phar アーカイブからファイルを取得します。

パラメータ

localName

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::offsetExists() - ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • Phar::offsetUnset() - ファイルを phar から削除する


内部ファイルに、外部ファイルの内容を設定する

  • ≪ Phar::offsetGet
  • Phar::offsetUnset ≫
  • PHP Manual
  • Phar
  • 内部ファイルに、外部ファイルの内容を設定する

Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — 内部ファイルに、外部ファイルの内容を設定する

説明

public Phar::offsetSet(string $localName, resource|string $value): void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetSet を使用して、Phar アーカイブの既存ファイルの変更や 新しいファイルの追加を行います。

パラメータ

localName

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::addFile(), Phar::addFromString(), Phar::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに Phar::buildFromDirectory() や Phar::buildFromIterator() を使うべきです。

参考

  • Phar::offsetExists() - ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetGet() - 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetUnset() - ファイルを phar から削除する


ファイルを phar から削除する

  • ≪ Phar::offsetSet
  • Phar::running ≫
  • PHP Manual
  • Phar
  • ファイルを phar から削除する

Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — ファイルを phar から削除する

説明

public Phar::offsetUnset(string $localName): void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetUnset を使用して、既存のファイルを削除します。また unset() が使用された場合にもコールされます。

パラメータ

localName

Phar 内で変更するファイル名 (相対パス)。

戻り値

値を返しません。

エラー / 例外

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::offsetExists() - ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetGet() - 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • Phar::unlinkArchive() - phar アーカイブをディスクとメモリから完全に削除する
  • Phar::delete() - phar アーカイブ内のファイルを削除する


現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

  • ≪ Phar::offsetUnset
  • Phar::setAlias ≫
  • PHP Manual
  • Phar
  • 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

説明

final public static Phar::running(bool $returnPhar = true): string

実行中の phar アーカイブのフルパスを返します。これはマジック定数 __FILE__ のような使い方を想定したもので、 実行中の phar アーカイブの内部でのみ有効です。

アーカイブ内のスタブでは、Phar::running() は "" を返します。現在実行中の phar にスタブ内からアクセスするには、 単純に __FILE__ を使用します。

パラメータ

returnPhar

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 アーカイブのエイリアスを設定する

  • ≪ Phar::running
  • Phar::setDefaultStub ≫
  • PHP Manual
  • Phar
  • Phar アーカイブのエイリアスを設定する

Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Phar アーカイブのエイリアスを設定する

説明

public Phar::setAlias(string $alias): bool

注意:

このメソッドは、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::__construct() - Phar アーカイブオブジェクトを作成する
  • Phar::interceptFileFuncs() - fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる


Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

  • ≪ Phar::setAlias
  • Phar::setMetadata ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

説明

public Phar::setDefaultStub(?string $index = null, ?string $webIndex = null): bool

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、 Phar::createDefaultStub() と Phar::setStub() の両方の機能を組み合わせた便利なメソッドです。

パラメータ

index

コマンドラインからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

webIndex

ウェブブラウザからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

phar.readonly が php.ini で有効になっている場合に UnexpectedValueException をスローします。 変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | webIndex は、nullable になりました。

例

例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::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する


phar アーカイブのメタデータを設定する

  • ≪ Phar::setDefaultStub
  • Phar::setSignatureAlgorithm ≫
  • PHP Manual
  • Phar
  • phar アーカイブのメタデータを設定する

Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — phar アーカイブのメタデータを設定する

説明

public Phar::setMetadata(mixed $metadata): void

注意:

このメソッドは、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::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::delMetadata() - phar のグローバルメタデータを削除する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す


phar のシグネチャのアルゴリズムを設定して適用する

  • ≪ Phar::setMetadata
  • Phar::setStub ≫
  • PHP Manual
  • Phar
  • phar のシグネチャのアルゴリズムを設定して適用する

Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定して適用する

説明

public Phar::setSignatureAlgorithm(int $algo, ?string $privateKey = null): void

注意:

このメソッドは、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() で明示的にシグネチャを作成して設定する必要があります。

パラメータ

algo

    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 をスローします。

変更履歴

バージョン | 説明
8.0.0 | privateKey は、nullable になりました。

参考

  • Phar::getSupportedSignatures() - サポートするシグネチャ型の配列を返す
  • Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す


Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

  • ≪ Phar::setSignatureAlgorithm
  • Phar::startBuffering ≫
  • PHP Manual
  • Phar
  • Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

説明

public Phar::setStub(resource|string $stub, int $length = -1): bool

注意:

このメソッドは、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 アーカイブの実行スタブとして使用します。

length

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

php.ini で phar.readonly が有効になっている場合に UnexpectedValueException がスローされます。 変更をディスクに書き込む際に何らかの問題が発生した場合は PharException がスローされます。

変更履歴

バージョン | 説明
8.3.0 | resource と length を渡して Phar::setStub() をコールすることは、 推奨されなくなりました。 $phar->setStub(stream_get_contents($resource)); に置き換えるべきです。

例

例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(); ?>"

変更履歴

バージョン | 説明
5.4.0 | len パラメータが追加されました。

参考

  • Phar::getStub() - Phar アーカイブの PHP ローダーあるいは起動スタブを返す
  • Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する


Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

  • ≪ Phar::setStub
  • Phar::stopBuffering ≫
  • PHP Manual
  • Phar
  • Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

説明

public 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 アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

  • ≪ Phar::startBuffering
  • Phar::unlinkArchive ≫
  • PHP Manual
  • Phar
  • Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

説明

public 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 アーカイブをディスクとメモリから完全に削除する

  • ≪ Phar::stopBuffering
  • Phar::webPhar ≫
  • PHP Manual
  • Phar
  • phar アーカイブをディスクとメモリから完全に削除する

Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する

説明

final public static Phar::unlinkArchive(string $filename): bool

phar アーカイブをディスクとメモリから削除します。

パラメータ

filename

ディスク上の 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::delete() - phar アーカイブ内のファイルを削除する
  • Phar::offsetUnset() - ファイルを phar から削除する


ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する

  • ≪ Phar::unlinkArchive
  • PharData ≫
  • PHP Manual
  • Phar
  • ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する

Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する

説明

final public static Phar::webPhar(
?string $alias = null,
?string $index = null,
?string $fileNotFoundScript = null,
array $mimeTypes = [],
?callable $rewrite = null
): void

Phar::webPhar() は、Phar::mapPhar() を、 ウェブベースの phar で使うものです。 このメソッドは、 $_SERVER['REQUEST_URI'] をパースして ウェブブラウザからのリクエストを phar アーカイブ内のファイルに転送します。 このメソッド自体がウェブサーバーをシミュレートします。 正しいファイルにリクエストを転送し、正しいヘッダを出力し、 必要に応じて PHP ファイルをパースします。 Phar::mungServer() や Phar::interceptFileFuncs() と組み合わせて使用すると、任意のウェブアプリケーションをそのまま phar アーカイブ化することができます。

Phar::webPhar() をコールするのは、 phar アーカイブのスタブ内からのみとしましょう (スタブって何? という方は ここ をごらんください)。

パラメータ

alias

phar:// URL でこのアーカイブを指す際に、 フルパスの代わりに使用するエイリアス。

index

phar の中でディレクトリインデックスとなるファイルの場所。

fileNotFoundScript

ファイルが見つからないときに実行するスクリプトの場所。 このスクリプトは 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',
);
?>

rewrite

書き換え関数は、唯一のパラメータとして文字列を受け取り、string あるいは false を返さないといけません。

fast-cgi あるいは cgi を使っている場合、この関数に渡されるパラメータは $_SERVER['PATH_INFO'] の値になります。 それ以外の場合、この関数に渡されるパラメータは $_SERVER['REQUEST_URI'] の値になります。

文字列を返した場合は、内部的なファイルパスとして扱います。false を返した場合は、 webPhar() が HTTP 403 を送信します。

戻り値

値を返しません。

エラー / 例外

出力したい内部ファイルのオープンに失敗した場合、 あるいはスタブ以外からコールした場合には PharException をスローします。 無効な配列を mimeTypes に渡したり、 無効なコールバックを rewrite に渡したりした場合は UnexpectedValueException をスローします。

変更履歴

バージョン | 説明
8.0.0 | fileNotFoundScript、 rewrite は、nullable になりました。

例

例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 に横取りさせる


PharData クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

はじめに

PharData クラスは、実行可能形式でない tar アーカイブや zip アーカイブへのアクセスや作成のための高レベルインターフェイスを提供します。 これらのアーカイブにはスタブが含まれておらず、 phar 拡張モジュールから実行することはできません。 そのため、PharData クラスによる通常の zip および tar ファイルの作成や 操作は php.ini の phar.readonly が 1 であっても可能です。

クラス概要

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* 継承した定数 */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* メソッド */
public __construct(
string $filename,
int $flags = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string $alias = null,
int $format = 0
)
public addEmptyDir(string $directory): void
public addFile(string $filename, ?string $localName = null): void
public addFromString(string $localName, string $contents): void
public buildFromDirectory(string $directory, string $pattern = ""): array
public buildFromIterator(Traversable $iterator, ?string $baseDirectory = null): array
public compress(int $compression, ?string $extension = null): ?PharData
public compressFiles(int $compression): void
public convertToData(?int $format = null, ?int $compression = null, ?string $extension = null): ?PharData
public convertToExecutable(?int $format = null, ?int $compression = null, ?string $extension = null): ?Phar
public copy(string $from, string $to): bool
public decompress(?string $extension = null): ?PharData
public decompressFiles(): bool
public delMetadata(): bool
public delete(string $localName): bool
public extractTo(string $directory, array|string|null $files = null, bool $overwrite = false): bool
public isWritable(): bool
public offsetSet(string $localName, resource|string $value): void
public offsetUnset(string $localName): void
public setAlias(string $alias): bool
public setDefaultStub(?string $index = null, ?string $webIndex = null): bool
public setMetadata(mixed $metadata): void
public setSignatureAlgorithm(int $algo, ?string $privateKey = null): void
public setStub(string $stub, int $len = -1): bool
public __destruct()
/* 継承したメソッド */
public RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public RecursiveDirectoryIterator::getSubPath(): string
public RecursiveDirectoryIterator::getSubPathname(): string
public RecursiveDirectoryIterator::hasChildren(bool $allowLinks = false): bool
public RecursiveDirectoryIterator::key(): string
public RecursiveDirectoryIterator::next(): void
public RecursiveDirectoryIterator::rewind(): void
public FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public FilesystemIterator::getFlags(): int
public FilesystemIterator::key(): string
public FilesystemIterator::next(): void
public FilesystemIterator::rewind(): void
public FilesystemIterator::setFlags(int $flags): void
public DirectoryIterator::current(): mixed
public DirectoryIterator::getBasename(string $suffix = ""): string
public DirectoryIterator::getExtension(): string
public DirectoryIterator::getFilename(): string
public DirectoryIterator::isDot(): bool
public DirectoryIterator::key(): mixed
public DirectoryIterator::next(): void
public DirectoryIterator::rewind(): void
public DirectoryIterator::seek(int $offset): void
public DirectoryIterator::__toString(): string
public DirectoryIterator::valid(): bool
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する
  • PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addFromString — 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する
  • PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する
  • PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する
  • PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
  • PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する
  • PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
  • PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
  • PharData::decompress — Phar アーカイブ全体の圧縮を解除する
  • PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
  • PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する
  • PharData::delete — tar/zip アーカイブ内のファイルを削除する
  • PharData::__destruct — 実行不能な tar や zip アーカイブオブジェクトを破棄する
  • PharData::extractTo — tar/zip アーカイブの内容をディレクトリに展開する
  • PharData::isWritable — tar/zip アーカイブが変更可能な場合に true を返す
  • PharData::offsetSet — tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
  • PharData::offsetUnset — ファイルを tar/zip アーカイブから削除する
  • PharData::setAlias — ダミー関数 (Phar::setAlias は PharData では使用不能)
  • PharData::setDefaultStub — ダミー関数 (Phar::setDefaultStub は PharData では無効)
  • PharData::setMetadata — phar アーカイブのメタデータを設定する
  • PharData::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定する
  • PharData::setStub — ダミー関数 (Phar::setStub は PharData では使用不能)


空のディレクトリを tar/zip アーカイブに追加する

  • ≪ PharData
  • PharData::addFile ≫
  • PHP Manual
  • PharData
  • 空のディレクトリを tar/zip アーカイブに追加する

PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する

説明

public PharData::addEmptyDir(string $directory): void

このメソッドを使用すると、空のディレクトリが dirname に作成されます。このメソッドは ZipArchive::addEmptyDir() と同じようなものです。

パラメータ

directory

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) {
// ここでエラー処理をします
}
?>

参考

  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addFromString() - 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する


ファイルシステム上のファイルを tar/zip アーカイブに追加する

  • ≪ PharData::addEmptyDir
  • PharData::addFromString ≫
  • PHP Manual
  • PharData
  • ファイルシステム上のファイルを tar/zip アーカイブに追加する

PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する

説明

public PharData::addFile(string $filename, ?string $localName = null): void

このメソッドを使用すると、任意のファイルあるいは URL を tar/zip アーカイブに追加することができます。 オプションの 2 番目のパラメータ localname を指定すると、 ファイルはその名前でアーカイブ内に格納されます。指定しなかった場合は、 file パラメータをアーカイブ内のパスとして使用します。 URL を使用する場合は、localname を指定しないと例外がスローされます。 このメソッドは ZipArchive::addFile() と同じようなものです。

パラメータ

filename

phar アーカイブに追加したいディスク上のファイルへのフルパスあるいは相対パス。

localName

ファイルをアーカイブ内に格納するときのパス。

戻り値

戻り値はありません。失敗時には例外をスローします。

変更履歴

バージョン | 説明
8.0.0 | localName は、nullable になりました。

例

例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::addFile(), PharData::addFromString(), PharData::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに PharData::buildFromDirectory() や PharData::buildFromIterator() を使うべきです。

参考

  • PharData::offsetSet() - tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • PharData::addFromString() - 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する
  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する


内容を文字列で指定したファイルを、tar/zip アーカイブに追加する

  • ≪ PharData::addFile
  • PharData::buildFromDirectory ≫
  • PHP Manual
  • PharData
  • 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する

PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する

説明

public PharData::addFromString(string $localName, string $contents): void

このメソッドを使用すると、任意の文字列を 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::addFile(), PharData::addFromString(), PharData::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに PharData::buildFromDirectory() や PharData::buildFromIterator() を使うべきです。

参考

  • PharData::offsetSet() - tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
  • Phar::addFromString() - 文字列から、ファイルを phar アーカイブに追加する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する


ディレクトリ内のファイルから tar/zip アーカイブを作成する

  • ≪ PharData::addFromString
  • PharData::buildFromIterator ≫
  • PHP Manual
  • PharData
  • ディレクトリ内のファイルから tar/zip アーカイブを作成する

PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する

説明

public PharData::buildFromDirectory(string $directory, string $pattern = ""): array

ディレクトリの中身をもとに tar/zip アーカイブを作成します。 オプションの 2 番目のパラメータで正規表現 (pcre) を指定すると、特定のファイルを除外することができます。 正規表現にマッチするすべてのファイルがアーカイブに含められ、 それ以外のファイルは除外されます。より詳細に制御するには PharData::buildFromIterator() を使用します。

パラメータ

directory

アーカイブに追加するすべてのファイルを含むディレクトリへの フルパスあるいは相対パス。

pattern

オプションで指定する pcre 正規表現。 これを使用してファイル一覧をフィルタリングします。 正規表現にマッチするファイルパスのみがアーカイブに追加されます。

戻り値

Phar::buildFromDirectory() は、連想配列を返します。これは、 ファイルの内部パスをファイルシステム上のフルパスを対応させたものです。 失敗した場合に false を返します

エラー / 例外

このメソッドは、内部ディレクトリイテレータのインスタンスの作成に失敗したときに BadMethodCallException をスローします。 また、phar アーカイブの保存時にエラーが発生した場合は PharException をスローします。

変更履歴

バージョン | 説明
8.1.0 | PharData::buildFromDirectory() は、 false を返さなくなりました。

例

例1 PharData::buildFromDirectory() の例

<?php
$phar = new PharData('project.tar');
// project 内のすべてのファイルを追加します
$phar->buildFromDirectory(dirname(__FILE__) . '/project');

$phar2 = new PharData('project2.zip');
// project 内のファイルのうち、php ファイルだけを追加します
$phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
?>

参考

  • Phar::buildFromDirectory() - ディレクトリ内のファイルから phar を作成する
  • PharData::buildFromIterator() - イテレータから tar あるいは zip アーカイブを作成する


イテレータから tar あるいは zip アーカイブを作成する

  • ≪ PharData::buildFromDirectory
  • PharData::compress ≫
  • PHP Manual
  • PharData
  • イテレータから tar あるいは zip アーカイブを作成する

PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する

説明

public PharData::buildFromIterator(Traversable $iterator, ?string $baseDirectory = null): array

tar あるいは zip アーカイブをイテレータから作成します。 サポートするイテレータは二種類で、 tar/zip 内のファイル名とディスク上の実際のファイル名を対応させたものか、あるいは DirectoryIterator のように SplFileInfo オブジェクトを返すものです。 SplFileInfo オブジェクトを返すイテレータの場合は、2 番目のパラメータが必要となります。

パラメータ

iterator

phar ファイルと実際の場所の関連を返すイテレータ、 あるいは SplFileInfo オブジェクトを返すイテレータ。

baseDirectory

SplFileInfo オブジェクトを返すイテレータを指定した際、 tar/zip アーカイブへの追加時にフルパスから取り除く部分。

戻り値

PharData::buildFromIterator() は連想配列を返します。 これは、ファイルの内部パスとファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、イテレータが間違った値 (たとえば文字列キーではなく整数キーなど) を返した場合に UnexpectedValueException を返します。また、SplFileInfo 型のイテレータを渡したときに baseDirectory を指定しなかった場合は BadMethodCallException を、 phar アーカイブの保存時にエラーが発生した場合は PharException を返します。

変更履歴

バージョン | 説明
8.1.0 | PharData::buildFromIterator() は、 false を返さなくなりました。
8.0.0 | baseDirectory は、nullable になりました。

例

例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'),
)));
?>

参考

  • Phar::buildFromIterator() - イテレータから phar アーカイブを作成する


tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

  • ≪ PharData::buildFromIterator
  • PharData::compressFiles ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

説明

public PharData::compress(int $compression, ?string $extension = null): ?PharData

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 オブジェクトを返します。 失敗した場合は null を返します。

エラー / 例外

zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

変更履歴

バージョン | 説明
8.0.0 | extension は、nullable になりました。

例

例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.tar.gz にコピーします
$p2 = $p->compress(Phar::BZ2); // /path/to/my.tar.bz2 にコピーします
$p3 = $p2->compress(Phar::NONE); // 例外: /path/to/my.tar が既に存在します
?>

参考

  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する


現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

  • ≪ PharData::compress
  • PharData::__construct ≫
  • PHP Manual
  • PharData
  • 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

説明

public PharData::compressFiles(int $compression): void

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 PharData::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式のアーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルを指定した方式で圧縮します。 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。さらに、 もし既に bzip2/zlib で圧縮されているファイルがある場合は、 いったんその圧縮を解除するために対応する拡張モジュールが必要となります。

パラメータ

compression

圧縮を行う場合は Phar::GZ あるいは Phar::BZ2、圧縮を解除するためには Phar::NONE のいずれかを指定しなければなりません。

戻り値

値を返しません。

エラー / 例外

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)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • PharData::decompressFiles() - 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • PharData::decompress() - Phar アーカイブ全体の圧縮を解除する


実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

  • ≪ PharData::compressFiles
  • PharData::convertToData ≫
  • PHP Manual
  • PharData
  • 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

説明

public PharData::__construct(
string $filename,
int $flags = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string $alias = null,
int $format = 0
)

パラメータ

filename

既存の 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', Phar::CURRENT_AS_FILEINFO | Phar::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');
?>


phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

  • ≪ PharData::__construct
  • PharData::convertToExecutable ≫
  • PHP Manual
  • PharData
  • phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

説明

public PharData::convertToData(?int $format = null, ?int $compression = null, ?string $extension = null): ?PharData

このメソッドは、実行可能でない 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 オブジェクトを返します。失敗した場合は null を返します。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、phar 作成中に何らかの問題が発生した場合に PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | format、 compression、 extension は、nullable になりました。

例

例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) {
// ここでエラー処理をします
}
?>

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToExecutable() - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する


実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

  • ≪ PharData::convertToData
  • PharData::copy ≫
  • PHP Manual
  • PharData
  • 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

説明

public PharData::convertToExecutable(?int $format = null, ?int $compression = null, ?string $extension = null): ?Phar

注意:

このメソッドは、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 オブジェクトを返します。失敗した場合は null を返します。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、書き込みサポートが無効な場合に UnexpectedValueException、 phar 作成中に何らかの問題が発生した場合に PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | format、 compression、 localName は、nullable になりました。

例

例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) {
// ここでエラー処理をします
}
?>

参考

  • Phar::convertToExecutable() - phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • PharData::convertToData() - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する


phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

  • ≪ PharData::convertToExecutable
  • PharData::decompress ≫
  • PHP Manual
  • PharData
  • phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

説明

public PharData::copy(string $from, string $to): bool

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

パラメータ

from

to

戻り値

成功した場合に 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"
?>


Phar アーカイブ全体の圧縮を解除する

  • ≪ PharData::copy
  • PharData::decompressFiles ≫
  • PHP Manual
  • PharData
  • Phar アーカイブ全体の圧縮を解除する

PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Phar アーカイブ全体の圧縮を解除する

説明

public PharData::decompress(?string $extension = null): ?PharData

tar 形式のアーカイブの場合は、 このメソッドはアーカイブ全体の圧縮を解除します。

zip 形式のアーカイブの場合は、このメソッドは失敗して例外が発生します。 gzip で圧縮されたファイルの圧縮を解除するためには zlib 拡張モジュールが、そして bzip2 で圧縮されたファイルの圧縮を解除するためには bzip2 拡張モジュールが有効になっていなければなりません。

さらに、このメソッドは自動的にアーカイブの拡張子を変更し、 .tar をデフォルトで追加します。 もうひとつの方法として、ファイルの拡張子を extension パラメータで指定することもできます。

パラメータ

extension

圧縮を解除する場合、デフォルトのファイル拡張子は .tar です。 このパラメータを使用すると、別の拡張子を指定することができます。 実行可能なアーカイブのみが、ファイル名に .phar を含むことができることに注意しましょう。

戻り値

成功した場合に PharData オブジェクトを返します。 失敗した場合は null を返します。

エラー / 例外

zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

変更履歴

バージョン | 説明
8.0.0 | extension は、nullable になりました。

例

例1 PharData::decompress() の例

<?php
$p = new PharData('/path/to/my.tar.gz');
$p->decompress(); // これは、/path/to/my.tar を作成します
?>

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • PharData::compressFiles() - 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
  • PharData::decompressFiles() - 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する


現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

  • ≪ PharData::decompress
  • PharData::delMetadata ≫
  • PHP Manual
  • PharData
  • 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

説明

public PharData::decompressFiles(): bool

注意:

このメソッドは、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)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • PharData::compressFiles() - 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • PharData::compress() - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • PharData::decompress() - Phar アーカイブ全体の圧縮を解除する


zip アーカイブのグローバルメタデータを削除する

  • ≪ PharData::decompressFiles
  • PharData::delete ≫
  • PHP Manual
  • PharData
  • zip アーカイブのグローバルメタデータを削除する

PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する

説明

public PharData::delMetadata(): bool

注意:

このメソッドは、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

参考

  • Phar::delMetadata() - phar のグローバルメタデータを削除する


tar/zip アーカイブ内のファイルを削除する

  • ≪ PharData::delMetadata
  • PharData::__destruct ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブ内のファイルを削除する

PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — tar/zip アーカイブ内のファイルを削除する

説明

public PharData::delete(string $localName): bool

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で unlink() をコールするのと同じ意味です。以下に例を示します。

パラメータ

localName

削除したいファイルの、アーカイブ内でのパス。

戻り値

成功した場合に 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 アーカイブ内のファイルを削除する


実行不能な tar や zip アーカイブオブジェクトを破棄する

  • ≪ PharData::delete
  • PharData::extractTo ≫
  • PHP Manual
  • PharData
  • 実行不能な tar や zip アーカイブオブジェクトを破棄する

PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — 実行不能な tar や zip アーカイブオブジェクトを破棄する

説明

public PharData::__destruct()

パラメータ

この関数にはパラメータはありません。


tar/zip アーカイブの内容をディレクトリに展開する

  • ≪ PharData::__destruct
  • PharData::isWritable ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブの内容をディレクトリに展開する

PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — tar/zip アーカイブの内容をディレクトリに展開する

説明

public PharData::extractTo(string $directory, array|string|null $files = null, bool $overwrite = false): bool

tar/zip アーカイブ内のすべてのファイルをディスクに展開します。 展開されたファイルやディレクトリは、アーカイブに保存されたときのパーミッションを維持しています。 オプションのパラメータを使用すると、どのファイルを展開するかを制御したり 既存のファイルを上書きするかどうかを指定したりすることができます。 2 番目のパラメータ files には、 展開したいファイルやディレクトリの名前、あるいはその配列を指定します。 デフォルトでは、このメソッドは既存のファイルを上書きしません。 3 番目のパラメータを true にすると既存のファイルを上書きさせることができます。 このメソッドは ZipArchive::extractTo() と同じようなものです。

パラメータ

directory

指定した files の展開先のパス。

files

展開したいファイル名/ディレクトリ名、あるいはその配列。

overwrite

true にすると既存のファイルを上書きします。

戻り値

成功した場合に true を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 PharData::extractTo() の例

<?php
try {
$phar = new PharData('myphar.tar');
$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) {
// エラー処理
}
?>

注意

注意:

Windows の NTFS ファイルシステムには、ファイル名で使う場合にサポートしていない文字があります。具体的には、<|>*?": です。末尾にドットがあるファイル名もサポートしていません。いくつかの展開ツールと異なり、このメソッドはこれらの文字をアンダースコアで置き換えませんし、そのようなファイルを展開すると失敗します。

参考

  • Phar::extractTo() - phar アーカイブの内容をディレクトリに展開する


tar/zip アーカイブが変更可能な場合に true を返す

  • ≪ PharData::extractTo
  • PharData::offsetSet ≫
  • PHP Manual
  • PharData
  • tar/zip アーカイブが変更可能な場合に true を返す

PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — tar/zip アーカイブが変更可能な場合に true を返す

説明

public PharData::isWritable(): bool

このメソッドは、ディスク上の tar/zip アーカイブが読み込み専用でない場合に true を返します。Phar::isWritable() とは異なり、 データのみの tar/zip アーカイブは phar.readonly が 1 であっても変更可能です。

パラメータ

パラメータはありません。

戻り値

tar/zip アーカイブが変更可能な場合に true を返します。

参考

  • Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
  • Phar::isWritable() - phar アーカイブが変更可能な場合に true を返す


tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

  • ≪ PharData::isWritable
  • PharData::offsetUnset ≫
  • PHP Manual
  • PharData
  • tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

説明

public PharData::offsetSet(string $localName, resource|string $value): void

これは ArrayAccess インターフェイスを実装したものです。 これにより、tar/zip アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetSet を使用して、tar/zip アーカイブの既存ファイルの変更や 新しいファイルの追加を行います。

パラメータ

localName

tar あるいは zip アーカイブ内で変更するファイル名 (相対パス)。

value

ファイルの内容。

戻り値

値を返しません。

エラー / 例外

Phar アーカイブへの変更をディスクに書き込む際に何らかのエラーが発生すると PharException がスローされます。

例

例1 PharData::offsetSet() の例

offsetSet は直接使用してはいけません。 配列に [] 演算子でアクセスする際に使用されます。

<?php
$p = new PharData('/path/to/my.tar');
try {
// offsetSet がコールされます
$p['file.txt'] = 'Hi there';
} catch (Exception $e) {
echo 'file.txt を変更できません: ', $e;
}
?>

注意

注意: PharData::addFile(), PharData::addFromString(), PharData::offsetSet() は、呼び出されるたびに新しいPharアーカイブを生成します。パフォーマンスを気にするなら、代わりに PharData::buildFromDirectory() や PharData::buildFromIterator() を使うべきです。

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する


ファイルを tar/zip アーカイブから削除する

  • ≪ PharData::offsetSet
  • PharData::setAlias ≫
  • PHP Manual
  • PharData
  • ファイルを tar/zip アーカイブから削除する

PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — ファイルを tar/zip アーカイブから削除する

説明

public PharData::offsetUnset(string $localName): void

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetUnset を使用して、既存のファイルを削除します。また unset() が使用された場合にもコールされます。

パラメータ

localName

tar/zip アーカイブ内で変更するファイル名 (相対パス)。

戻り値

値を返しません。

エラー / 例外

tar/zip アーカイブへの変更をディスクに書き込む際に何らかのエラーが発生すると PharException をスローします。

例

例1 PharData::offsetUnset() の例

<?php
$p = new PharData('/path/to/my.zip');
try {
// offsetUnset がコールされ、file.txt が my.zip から削除されます
unset($p['file.txt']);
} catch (Exception $e) {
echo 'file.txt を削除できません: ', $e;
}
?>

参考

  • Phar::offsetUnset() - ファイルを phar から削除する


ダミー関数 (Phar::setAlias は PharData では使用不能)

  • ≪ PharData::offsetUnset
  • PharData::setDefaultStub ≫
  • PHP Manual
  • PharData
  • ダミー関数 (Phar::setAlias は PharData では使用不能)

PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — ダミー関数 (Phar::setAlias は PharData では使用不能)

説明

public PharData::setAlias(string $alias): bool

実行可能でない tar/zip アーカイブはエイリアスを持つことができないので、 このメソッドは単に例外をスローします。

パラメータ

alias

このアーカイブを指すときに使用する短い文字列。 phar ストリームラッパーがアクセスする際にこれを使用します。 このパラメータは無視されます。

戻り値

エラー / 例外

このメソッドがコールされると必ず PharException をスローします。

参考

  • Phar::setAlias() - Phar アーカイブのエイリアスを設定する


ダミー関数 (Phar::setDefaultStub は PharData では無効)

  • ≪ PharData::setAlias
  • PharData::setMetadata ≫
  • PHP Manual
  • PharData
  • ダミー関数 (Phar::setDefaultStub は PharData では無効)

PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — ダミー関数 (Phar::setDefaultStub は PharData では無効)

説明

public PharData::setDefaultStub(?string $index = null, ?string $webIndex = null): bool

実行可能でない tar/zip アーカイブはスタブを持つことができません。 そのため、このメソッドは単に例外をスローするだけです。

パラメータ

index

コマンドラインからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

webIndex

ウェブブラウザからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

常に PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | webIndex は、nullable になりました。

参考

  • Phar::setDefaultStub() - Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する


phar アーカイブのメタデータを設定する

  • ≪ PharData::setDefaultStub
  • PharData::setSignatureAlgorithm ≫
  • PHP Manual
  • PharData
  • phar アーカイブのメタデータを設定する

PharData::setMetadata

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

PharData::setMetadata — phar アーカイブのメタデータを設定する

説明

public PharData::setMetadata(mixed $metadata): void

注意:

このメソッドは、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::getMetadata() - phar アーカイブのメタデータを返す
  • Phar::delMetadata() - phar のグローバルメタデータを削除する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す


phar のシグネチャのアルゴリズムを設定する

  • ≪ PharData::setMetadata
  • PharData::setStub ≫
  • PHP Manual
  • PharData
  • phar のシグネチャのアルゴリズムを設定する

PharData::setSignatureAlgorithm

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

PharData::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定する

説明

public PharData::setSignatureAlgorithm(int $algo, ?string $privateKey = null): void

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar のシグネチャのアルゴリズムを設定します。
シグネチャのアルゴリズムは Phar::MD5、
Phar::SHA1、Phar::SHA256、
Phar::SHA512 あるいは Phar::OPENSSL
のいずれかでなければなりません

パラメータ

algo

    Phar::MD5、
Phar::SHA1、Phar::SHA256、
Phar::SHA512 あるいは Phar::OPENSSL
    のいずれか。

戻り値

値を返しません。

エラー / 例外

さまざまなエラーが発生した場合に UnexpectedValueException をスローします。 zip 形式や tar 形式の phar アーカイブに対してコールした場合は BadMethodCallException をスローします。 変更内容をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

変更履歴

バージョン | 説明
8.0.0 | privateKey は、nullable になりました。

参考

  • Phar::getSupportedSignatures() - サポートするシグネチャ型の配列を返す
  • Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す


ダミー関数 (Phar::setStub は PharData では使用不能)

  • ≪ PharData::setSignatureAlgorithm
  • PharFileInfo ≫
  • PHP Manual
  • PharData
  • ダミー関数 (Phar::setStub は PharData では使用不能)

PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — ダミー関数 (Phar::setStub は PharData では使用不能)

説明

public PharData::setStub(string $stub, int $len = -1): bool

実行可能でない tar/zip アーカイブはスタブを持つことができないので、 このメソッドは単に例外をスローします。

パラメータ

stub

文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。 このパラメータは無視されます。

len

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドがコールされると必ず PharException をスローします。

参考

  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する


PharFileInfo クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

はじめに

PharFileInfo クラスは、 phar アーカイブ内の個々のファイルのコンテンツや属性への 高レベルインターフェイスを提供します。

クラス概要

class PharFileInfo extends SplFileInfo {
/* メソッド */
public __construct(string $filename)
public chmod(int $perms): void
public compress(int $compression): bool
public decompress(): bool
public delMetadata(): bool
public getCRC32(): int
public getCompressedSize(): int
public getContent(): string
public getMetadata(array $unserializeOptions = []): mixed
public getPharFlags(): int
public hasMetadata(): bool
public isCRCChecked(): bool
public isCompressed(?int $compression = null): bool
public setMetadata(mixed $metadata): void
public __destruct()
/* 継承したメソッド */
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • PharFileInfo::chmod — ファイル固有のパーミッションビットを設定する
  • PharFileInfo::compress — 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • PharFileInfo::__construct — Phar エントリオブジェクトを作成する
  • PharFileInfo::decompress — phar 内の現在の Phar エントリの圧縮を解除する
  • PharFileInfo::delMetadata — エントリのメタデータを削除する
  • PharFileInfo::__destruct — Phar エントリオブジェクトを破棄する
  • PharFileInfo::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする
  • PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::getContent — エントリの完全なファイルの内容を取得する
  • PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す
  • PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す
  • PharFileInfo::hasMetadata — エントリのメタデータを返す
  • PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる
  • PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる
  • PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する


ファイル固有のパーミッションビットを設定する

  • ≪ PharFileInfo
  • PharFileInfo::compress ≫
  • PHP Manual
  • PharFileInfo
  • ファイル固有のパーミッションビットを設定する

PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — ファイル固有のパーミッションビットを設定する

説明

public PharFileInfo::chmod(int $perms): void

PharFileInfo::chmod() は、ファイルパーミッションのうち実行ビットと読み込みビットを設定します。 書き込みビットについては無視されます。書き込みビットは、実行時に INI 設定 phar.readonly に基づいて自動的に設定されます。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを操作するには INI 設定 phar.readonly がオフでなければなりません。 PharData アーカイブ内のファイルについては、この制約はありません。

パラメータ

perms

パーミッション (chmod() を参照ください)。

戻り値

値を返しません。

例

例1 PharFileInfo::chmod() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
$p = new Phar('brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.sh'] = '#!/usr/local/lib/php
<?php echo "hi"; ?>';
// 実行ビットを設定します
$p['file.sh']->chmod(0555);
var_dump($p['file.sh']->isExecutable());
} catch (Exception $e) {
echo 'phar の作成/変更に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

bool(true)


現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

  • ≪ PharFileInfo::chmod
  • PharFileInfo::__construct ≫
  • PHP Manual
  • PharFileInfo
  • 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

説明

public PharFileInfo::compress(int $compression): bool

このメソッドは、Phar アーカイブ内のファイルを bzip あるいは zlib で圧縮します。 この機能を使用するには bzip2 拡張モジュールあるいは zlib 拡張モジュールが有効になっていなければなりません。 さらに、ファイルがすでに圧縮されている場合には、 その圧縮をいったん解除するために対応する拡張モジュールが必要となります。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを扱うには INI 設定 phar.readonly が off になっていなければなりません。 PharData アーカイブ内のファイルについてはこの制約はありません。

パラメータ

compression

Phar::GZ または Phar::BZ2 を指定しなければいけません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、あるいは zlib/zlib 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharFileInfo::compress() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressed(Phar::BZ2));
$p['myfile.txt']->compress(Phar::BZ2);
var_dump($file->isCompressed(Phar::BZ2));
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す


Phar エントリオブジェクトを作成する

  • ≪ PharFileInfo::compress
  • PharFileInfo::decompress ≫
  • PHP Manual
  • PharFileInfo
  • Phar エントリオブジェクトを作成する

PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Phar エントリオブジェクトを作成する

説明

public PharFileInfo::__construct(string $filename)

これは直接コールしてはいけません。PharFileInfo オブジェクトを作成するには、 配列へのアクセスを通じて Phar::offsetGet() をコールします。

パラメータ

filename

ファイルを取得するための完全な url。 ファイル my/file.php の情報を phar boo.phar から取得したい場合は、 このエントリは phar://boo.phar/my/file.php となります。

エラー / 例外

__construct() が二度コールされた場合に BadMethodCallException、 phar の URL がおかしかったり phar がオープンできなかったり、 あるいはファイルが phar 内で見つからなかった場合に UnexpectedValueException がスローされます。

例

例1 PharFileInfo::__construct() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['testfile.txt'] = "hi\nthere\ndude";
$file = $p['testfile.txt'];
foreach ($file as $line => $text) {
echo "行番号 $line: $text";
}
// これも動作します
$file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt');
foreach ($file as $line => $text) {
echo "行番号 $line: $text";
}
} catch (Exception $e) {
echo 'Phar 操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

行番号 1: hi
行番号 2: there
行番号 3: dude
行番号 1: hi
行番号 2: there
行番号 3: dude


phar 内の現在の Phar エントリの圧縮を解除する

  • ≪ PharFileInfo::__construct
  • PharFileInfo::delMetadata ≫
  • PHP Manual
  • PharFileInfo
  • phar 内の現在の Phar エントリの圧縮を解除する

PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — phar 内の現在の Phar エントリの圧縮を解除する

説明

public PharFileInfo::decompress(): bool

このメソッドは、Phar アーカイブ内のファイルの圧縮を解除します。 ファイルの圧縮形式に応じて、この機能を使用するには bzip2 拡張モジュールあるいは zlib 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを扱うには INI 設定 phar.readonly が off になっていなければなりません。 PharData アーカイブ内のファイルについてはこの制約はありません。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、あるいは zlib/zlib 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharFileInfo::decompress() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
$file->compress(Phar::GZ);
var_dump($file->isCompressed());
$p['myfile.txt']->decompress();
var_dump($file->isCompressed());
} catch (Exception $e) {
echo 'Create/modify failed for my.phar: ', $e;
}
?>

上の例の出力は以下となります。

int(4096)
bool(false)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す


エントリのメタデータを削除する

  • ≪ PharFileInfo::decompress
  • PharFileInfo::__destruct ≫
  • PHP Manual
  • PharFileInfo
  • エントリのメタデータを削除する

PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — エントリのメタデータを削除する

説明

public PharFileInfo::delMetadata(): bool

エントリのメタデータが存在する場合にそれを削除します。

パラメータ

パラメータはありません。

戻り値

成功した場合に true を返します。 エントリがメタデータを持っていない場合に false を返します。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを操作するには INI 設定 phar.readonly がオフでなければなりません。 PharData アーカイブ内のファイルについては、この制約はありません。

エラー / 例外

変更のディスクへの書き込み時にエラーが発生した場合は PharException、 書き込みアクセスが無効となっている場合は BadMethodCallException をスローします。

例

例1 PharFileInfo::delMetaData() の例

<?php
try {
$a = new Phar('myphar.phar');
$a['hi'] = 'hi';
var_dump($a['hi']->delMetadata());
$a['hi']->setMetadata('there');
var_dump($a['hi']->delMetadata());
var_dump($a['hi']->delMetadata());
} catch (Exception $e) {
// エラー処理
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

  • PharFileInfo::setMetadata() - ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharFileInfo::hasMetadata() - エントリのメタデータを返す
  • PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す


Phar エントリオブジェクトを破棄する

  • ≪ PharFileInfo::delMetadata
  • PharFileInfo::getCRC32 ≫
  • PHP Manual
  • PharFileInfo
  • Phar エントリオブジェクトを破棄する

PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Phar エントリオブジェクトを破棄する

説明

public PharFileInfo::__destruct()

パラメータ

この関数にはパラメータはありません。


CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

  • ≪ PharFileInfo::__destruct
  • PharFileInfo::getCompressedSize ≫
  • PHP Manual
  • PharFileInfo
  • CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

説明

public PharFileInfo::getCRC32(): int

Phar アーカイブ内のファイルの crc32() チェックサムを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Phar アーカイブ内のファイルの crc32() チェックサムを返します。

エラー / 例外

ファイルがまだ CRC32 で検証されていない場合に BadMethodCallException をスローします。 通常、これはありえません。CRC の検証は、 読み込みモードあるいは書き込みモードでファイルをオープンする際に行われるからです。

例

例1 PharFileInfo::getCRC32() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
echo $file->getCRC32();
} catch (Exception $e) {
echo 'my.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

3633523372


Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

  • ≪ PharFileInfo::getCRC32
  • PharFileInfo::getContent ≫
  • PHP Manual
  • PharFileInfo
  • Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

説明

public PharFileInfo::getCompressedSize(): int

この関数は、Phar アーカイブ内でのファイルの大きさを返します。 圧縮されていないファイルの場合は、getCompressedSize は filesize() と同じ値を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ディスク上の Phar アーカイブ内のファイルのバイト数を返します。

例

例1 PharFileInfo::getCompressedSize() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
echo $file->getCompressedSize();
} catch (Exception $e) {
echo 'my.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

2

参考

  • PharFileInfo::isCompressed() - エントリが圧縮されているかどうかを調べる
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する


エントリの完全なファイルの内容を取得する

  • ≪ PharFileInfo::getCompressedSize
  • PharFileInfo::getMetadata ≫
  • PHP Manual
  • PharFileInfo
  • エントリの完全なファイルの内容を取得する

PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — エントリの完全なファイルの内容を取得する

説明

public PharFileInfo::getContent(): string

この関数は file_get_contents() のように振る舞いますが、 Phar 専用です。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルの内容を返します。


ファイルとともに保存されている、ファイル固有のメタデータを返す

  • ≪ PharFileInfo::getContent
  • PharFileInfo::getPharFlags ≫
  • PHP Manual
  • PharFileInfo
  • ファイルとともに保存されている、ファイル固有のメタデータを返す

PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す

説明

public PharFileInfo::getMetadata(array $unserializeOptions = []): mixed

Phar アーカイブ内で、このファイル用のマニフェストに保存されたメタデータを返します。

パラメータ

戻り値

ファイルのメタデータとして保存されている、シリアライズ可能な任意の PHP 変数を返します。 メタデータが保存されていない場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 unserializeOptions が追加されました。

例

例1 PharFileInfo::getMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.txt'] = 'hello';
$p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
var_dump($p['file.txt']->getMetadata());
} catch (Exception $e) {
echo 'brandnewphar.phar を作成/変更できません: ', $e;
}
?>

上の例の出力は以下となります。

array(2) {
  ["user"]=>
  string(4) "bill"
  ["mime-type"]=>
  string(10) "text/plain"
}

参考

  • PharFileInfo::setMetadata() - ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharFileInfo::hasMetadata() - エントリのメタデータを返す
  • PharFileInfo::delMetadata() - エントリのメタデータを削除する
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す


Phar ファイルエントリのフラグを返す

  • ≪ PharFileInfo::getMetadata
  • PharFileInfo::hasMetadata ≫
  • PHP Manual
  • PharFileInfo
  • Phar ファイルエントリのフラグを返す

PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す

説明

public PharFileInfo::getPharFlags(): int

この関数は、Phar のマニフェスト内のフラグセットを返します。 現在の実装では、これは常に 0 を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Phar フラグを返します (現在の実装では、常に 0 となります)。

例

例1 PharFileInfo::getPharFlags() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->getPharFlags());
} catch (Exception $e) {
echo 'my.phar を作成/変更できません: ', $e;
}
?>

上の例の出力は以下となります。

int(0)


エントリのメタデータを返す

  • ≪ PharFileInfo::getPharFlags
  • PharFileInfo::isCRCChecked ≫
  • PHP Manual
  • PharFileInfo
  • エントリのメタデータを返す

PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — エントリのメタデータを返す

説明

public PharFileInfo::hasMetadata(): bool

phar アーカイブ内のファイルのメタデータを返します。

パラメータ

パラメータはありません。

戻り値

メタデータが設定されていないかあるいは null が設定されている場合に false、 null 以外のメタデータが設定されている場合に true を返します。

参考

  • PharFileInfo::setMetadata() - ファイルとともに保存する、ファイル固有のメタデータを設定する
  • PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
  • PharFileInfo::delMetadata() - エントリのメタデータを削除する
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す


ファイルエントリの CRC が検証されているかどうかを調べる

  • ≪ PharFileInfo::hasMetadata
  • PharFileInfo::isCompressed ≫
  • PHP Manual
  • PharFileInfo
  • ファイルエントリの CRC が検証されているかどうかを調べる

PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる

説明

public PharFileInfo::isCRCChecked(): bool

これは、Phar アーカイブ内のファイルが CRC 検証されているかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

そのファイルの CRC が検証されている場合に true、 そうでない場合に false を返します。

例

例1 PharFileInfo::isCRCChecked() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCRCChecked());
} catch (Exception $e) {
echo 'my.phar の作成/変更に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

bool(true)


エントリが圧縮されているかどうかを調べる

  • ≪ PharFileInfo::isCRCChecked
  • PharFileInfo::setMetadata ≫
  • PHP Manual
  • PharFileInfo
  • エントリが圧縮されているかどうかを調べる

PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる

説明

public PharFileInfo::isCompressed(?int $compression = null): bool

これは、Phar アーカイブ内のファイルが Gzip あるいは Bzip2 で圧縮されているかどうかを返します。

パラメータ

compression

Phar::GZ あるいは Phar::BZ2 のいずれか。デフォルトは任意の圧縮形式となります。

戻り値

Phar アーカイブ内のファイルが圧縮されている場合に true、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | compression は、nullable になりました。

例

例1 PharFileInfo::isCompressed() の例

<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
var_dump($file->isCompressed());
var_dump($file2->isCompressed());
} catch (Exception $e) {
echo 'my.phar の作成/変更に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • PharFileInfo::getCompressedSize() - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
  • PharFileInfo::decompress() - phar 内の現在の Phar エントリの圧縮を解除する
  • PharFileInfo::compress() - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
  • Phar::decompress() - Phar アーカイブ全体の圧縮を解除する
  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::canCompress() - phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::isCompressed() - phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::getSupportedCompression() - サポートする圧縮アルゴリズムの配列を返す
  • Phar::decompressFiles() - 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::compressFiles() - 現在の Phar アーカイブ内のすべてのファイルを圧縮する


ファイルとともに保存する、ファイル固有のメタデータを設定する

  • ≪ PharFileInfo::isCompressed
  • PharException ≫
  • PHP Manual
  • PharFileInfo
  • ファイルとともに保存する、ファイル固有のメタデータを設定する

PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する

説明

public PharFileInfo::setMetadata(mixed $metadata): void

PharFileInfo::setMetadata() を使用するのは、 既存のファイル情報としては表せない独自の情報を保存する場合のみに限るべきです。 メタデータを使用すると、phar アーカイブの読み込み時のパフォーマンスが劇的に低下します。これは、 メタデータのサイズが大きい場合やメタデータを含むファイルが大量にある場合に顕著になります。 ファイルのパーミッションについては phar 自体でネイティブにサポートしており、 PharFileInfo->chmod() で設定できることを覚えておきましょう。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを操作するには INI 設定 phar.readonly がオフでなければなりません。 PharData アーカイブ内のファイルについては、この制約はありません。

メタデータの使用例として考えられるのは、ユーザー/グループ を指定し、phar からディスクに展開する際にそれを設定することなどです。 ほかには、MIME 型として返す値を明示的に指定することなどがあります。 その他、ファイルについて説明するデータであるが ファイル自体に含むべきでないものを保存したりします。

パラメータ

metadata

ファイルとともに保存する情報を含む、PHP の変数。

戻り値

値を返しません。

例

例1 PharFileInfo::setMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.txt'] = 'hello';
$p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
var_dump($p['file.txt']->getMetaData());
} catch (Exception $e) {
echo 'phar を作成/変更できません:', $e;
}
?>

上の例の出力は以下となります。

array(2) {
  ["user"]=>
  string(4) "bill"
  ["mime-type"]=>
  string(10) "text/plain"
}

参考

  • PharFileInfo::hasMetadata() - エントリのメタデータを返す
  • PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
  • PharFileInfo::delMetadata() - エントリのメタデータを削除する
  • Phar::setMetadata() - phar アーカイブのメタデータを設定する
  • Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::getMetadata() - phar アーカイブのメタデータを返す


PharException クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

はじめに

PharException クラスは、try/catch ブロックで使用するための phar 固有の例外クラスです。

クラス概要

class PharException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


Rar アーカイブ

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
  • Rar 関数
    • rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数
  • RarArchive — RarArchive クラス
    • RarArchive::close — Rar アーカイブをクローズし、全リソースを開放する
    • RarArchive::getComment — RAR アーカイブのコメントテキストを取得する
    • RarArchive::getEntries — RAR アーカイブからエントリの全一覧を取得する
    • RarArchive::getEntry — Rar アーカイブからエントリオブジェクトを取得する
    • RarArchive::isBroken — アーカイブが壊れている (未完成である) かどうかを調べる
    • RarArchive::isSolid — RAR アーカイブがソリッドであるかどうかを調べる
    • RarArchive::open — Rar アーカイブをオープンする
    • RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する
    • RarArchive::__toString — テキスト形式で取得する
  • RarEntry — The RarEntry class
    • RarEntry::extract — アーカイブのエントリを展開する
    • RarEntry::getAttr — エントリの属性を取得する
    • RarEntry::getCrc — エントリの CRC を取得する
    • RarEntry::getFileTime — エントリの最終更新時刻を取得する
    • RarEntry::getHostOs — エントリのホスト OS を取得する
    • RarEntry::getMethod — エントリの圧縮方法を取得する
    • RarEntry::getName — エントリの名前を取得する
    • RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する
    • RarEntry::getStream — このエントリのファイルハンドラを取得する
    • RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する
    • RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する
    • RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる
    • RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる
    • RarEntry::__toString — エントリのテキスト表現を取得する
  • RarException — RarException クラス
    • RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる
    • RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う


はじめに

RAR は、Eugene Roshal が作成した強力で効率的なアーカイバです。 この拡張モジュールは unRAR ライブラリを使用していますが、 このライブラリは Rar アーカイブの読み込みしかサポートしていません。 unRAR のソースを使用して RAR/WinRAR アーカイバを作成することは、 unRAR のライセンス上で禁じられています。

RAR および unRAR についてのより詳細な情報は » http://www.rarlabs.com/ で見つけられます。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Rar
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

Rar 拡張モジュールは、現在 PECL » https://pecl.php.net/package/rar で取得可能です。

また、以下のコマンドを使用して PECL インストーラで Rar 拡張モジュールを インストールすることができます。pecl -v install rar

tar.gz パッケージをダウンロードし、Rar を手動でインストールすることも可能です。

例1 Rar のインストール

gunzip rar-xxx.tgz
tar -xvf rar-xxx.tar
cd rar-xxx
phpize
./configure && make && make install

Windows ユーザーがこれらの関数を使用するには、php_rar.dll を php.ini で有効にします。 この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


リソース型

この拡張モジュールは三つの内部クラスを使います。 rar_open() が返すアーカイブをあらわすクラス RarArchive、 rar_list() や rar_entry_get() が返すエントリをあらわすクラス RarEntry、そして例外をあらわす RarException です。

この拡張モジュールは、ストリームリソース "rar" も登録します。 また、URL ラッパー "rar ラッパー" も登録し、プレフィックス "rar" で使うことができます。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RAR_HOST_MSDOS (int)
かわりに RarEntry::HOST_MSDOS を使います。
RAR_HOST_OS2 (int)
かわりに RarEntry::HOST_OS2 を使います。
RAR_HOST_WIN32 (int)
かわりに RarEntry::HOST_WIN32 を使います。
RAR_HOST_UNIX (int)
かわりに RarEntry::HOST_UNIX を使います。
RAR_HOST_BEOS (int)
かわりに RarEntry::HOST_BEOS を使います。


例

rar:// ラッパー の例も参照ください。

例1 オンザフライでの復元

<?php

if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
die("Index unspecified or non-numeric");
$index = (int) $_GET["i"];

$arch = RarArchive::open("example.rar");
if ($arch === FALSE)
die("Cannot open example.rar");

$entries = $arch->getEntries();
if ($entries === FALSE)
die("Cannot retrieve entries");

if (!array_key_exists($index, $entries))
die("No such index: $index");

$orfilename = $entries[$index]->getName(); //UTF-8 encoded

$filesize = $entries[$index]->getUnpackedSize();

/* you could check HTTP_IF_MODIFIED_SINCE here and compare with
* $entries[$index]->getFileTime(). You could also send a
* "Last modified" header */

$fp = $entries[$index]->getStream();
if ($fp === FALSE)
die("Cannot open file with index $index insided the archive.");

$arch->close(); //no longer needed; stream is independent

function detectUserAgent() {
if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
return "Other";

$uas = $_SERVER['HTTP_USER_AGENT'];
if (preg_match("@Opera/@", $uas))
return "Opera";
if (preg_match("@Firefox/@", $uas))
return "Firefox";
if (preg_match("@Chrome/@", $uas))
return "Chrome";
if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
if (((float)$matches[1]) >= 7.0)
return "IE";
}

return "Other";
}

/*
* We have 3 options:
* - For FF and Opera, which support RFC 2231, use that format.
* - For IE and Chrome, use attwithfnrawpctenclong
* (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
* - For the others, convert to ISO-8859-1, if possible
*/
$formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
$formatDef = 'Content-Disposition: attachment; filename="%s"';

switch (detectUserAgent()) {
case "Opera":
case "Firefox":
$orfilename = rawurlencode($orfilename);
$format = $formatRFC2231;
break;

case "IE":
case "Chrome":
$orfilename = rawurlencode($orfilename);
$format = $formatDef;
break;
default:
if (function_exists('iconv'))
$orfilename =
@iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
$format = $formatDef;
}

header(sprintf($format, $orfilename));
//cannot send error messages from now on (headers already sent)

//replace by real content type, perhaps infering from the file extension
$contentType = "application/octet-stream";
header("Content-Type: $contentType");

header("Content-Transfer-Encoding: binary");

header("Content-Length: $filesize");

if ($_SERVER['REQUEST_METHOD'] == "HEAD")
die();

while (!feof($fp)) {
$s = @fread($fp, 8192);
if ($s === false)
break; //useless to send error messages

echo $s;
}
?>

この例は、RAR ファイルを開いて指定したファイルを RAR アーカイブ内から取り出し、 クライアントにダウンロードさせます。

例2 RAR 拡張モジュールでの展開の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブをオープンできません。");

$entries = rar_list($rar_file);

foreach ($entries as $entry) {
echo 'ファイル名: ' . $entry->getName() . "\n";
echo '圧縮時のファイルサイズ: ' . $entry->getPackedSize() . "\n";
echo '展開後のファイルサイズ: ' . $entry->getUnpackedSize() . "\n";

$entry->extract('/dir/extract/to/');
}

rar_close($rar_file);

?>

この例は Rar アーカイブファイルをオープンし、 指定したディレクトリに個々のファイルを展開します。


  • ≪ 例
  • rar_wrapper_cache_stats ≫
  • PHP Manual
  • Rar
  • Rar 関数

Rar 関数

目次

  • rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数


URL ラッパーのキャッシュのヒット数

  • ≪ Rar 関数
  • RarArchive ≫
  • PHP Manual
  • Rar 関数
  • URL ラッパーのキャッシュのヒット数

rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数

説明

rar_wrapper_cache_stats(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


RarArchive クラス

(PECL rar >= 2.0.0)

はじめに

このクラスは RAR アーカイブをあらわします。これは複数のパーツで構成されることもあり、 中に RAR エントリ (ファイルやディレクトリ、そしてシンボリックリンクなどの特殊なオブジェクト) を含みます。

このクラスのオブジェクトの中身を走査したり、RAR アーカイブに格納されているエントリを取り出したりすることができます。 このエントリは、RarArchive::getEntry() や RarArchive::getEntries() を使って取得することもできます。

クラス概要

final class RarArchive implements Traversable {
/* メソッド */
public close(): bool
public getComment(): string
public getEntries(): array|false
public getEntry(string $entryname): RarEntry|false
public isBroken(): bool
public isSolid(): bool
public static open(string $filename, string $password = NULL, callable $volume_callback = NULL): RarArchive|false
public setAllowBroken(bool $allow_broken): bool
public __toString(): string
}

目次

  • RarArchive::close — Rar アーカイブをクローズし、全リソースを開放する
  • RarArchive::getComment — RAR アーカイブのコメントテキストを取得する
  • RarArchive::getEntries — RAR アーカイブからエントリの全一覧を取得する
  • RarArchive::getEntry — Rar アーカイブからエントリオブジェクトを取得する
  • RarArchive::isBroken — アーカイブが壊れている (未完成である) かどうかを調べる
  • RarArchive::isSolid — RAR アーカイブがソリッドであるかどうかを調べる
  • RarArchive::open — Rar アーカイブをオープンする
  • RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する
  • RarArchive::__toString — テキスト形式で取得する


Rar アーカイブをクローズし、全リソースを開放する

  • ≪ RarArchive
  • RarArchive::getComment ≫
  • PHP Manual
  • RarArchive
  • Rar アーカイブをクローズし、全リソースを開放する

RarArchive::close

rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Rar アーカイブをクローズし、全リソースを開放する

説明

オブジェクト指向型 (メソッド)

public RarArchive::close(): bool

手続き型:

rar_close(RarArchive $rarfile): bool

Rar アーカイブをクローズし、割り当てられた全リソースを開放します。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | RarArchive::getEntry() や RarArchive::getEntries() が返した RAR エントリは、 このメソッドをコールした時点で無効になります。 これらのエントリのインスタンスメソッドをコールしても、成功は保証できないということです。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>

上の例の出力は、 たとえば以下のようになります。

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

例2 手続き型

<?php
$rar_arch = rar_open('latest_winrar.rar');
echo $rar_arch."\n";
rar_close($rar_arch);
echo $rar_arch."\n";
?>


RAR アーカイブのコメントテキストを取得する

  • ≪ RarArchive::close
  • RarArchive::getEntries ≫
  • PHP Manual
  • RarArchive
  • RAR アーカイブのコメントテキストを取得する

RarArchive::getComment

rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — RAR アーカイブのコメントテキストを取得する

説明

オブジェクト指向型 (メソッド)

public RarArchive::getComment(): string

手続き型:

rar_comment_get(RarArchive $rarfile): string

RAR アーカイブに格納された (グローバル) コメントを取得します。長さは最大 64 KiB までです。

注意:

この拡張モジュールは、エントリごとのコメントをサポートしていません。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

戻り値

コメントを返します。コメントがない場合は null を返します。

注意:

RAR は現在 unicode のコメントに対応していません。この関数の結果のエンコーディングは指定されていませんが、 おそらく Windows-1252 となるでしょう。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('commented.rar');
echo $rar_arch->getComment();
?>

上の例の出力は、 たとえば以下のようになります。

This is the comment of the file commented.rar.

例2 手続き型

<?php
$rar_arch = rar_open('commented.rar');
echo rar_comment_get($rar_arch);
?>


RAR アーカイブからエントリの全一覧を取得する

  • ≪ RarArchive::getComment
  • RarArchive::getEntry ≫
  • PHP Manual
  • RarArchive
  • RAR アーカイブからエントリの全一覧を取得する

RarArchive::getEntries

rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — RAR アーカイブからエントリの全一覧を取得する

説明

オブジェクト指向型 (メソッド)

public RarArchive::getEntries(): array|false

手続き型:

rar_list(RarArchive $rarfile): array|false

エントリ (ファイルおよびディレクトリ) の一覧を RAR アーカイブから取得します。

注意:

アーカイブの中に同じ名前のエントリが存在する場合は、このメソッドを RarArchive の foreach と組み合わせて 数値添字の配列形式で処理するのが唯一のアクセス方法となります (つまり、 RarArchive::getEntry() と rar:// ラッパー は使えないということです)。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

戻り値

rar_list() は RarEntry オブジェクトの配列を返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | エントリ名が繰り返される RAR アーカイブも対応するようになりました。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");

$rar_entries = $rar_arch->getEntries();
if ($rar_entries === FALSE)
die("Could not retrieve entries.");

echo "Found " . count($rar_entries) . " entries.\n";

foreach ($rar_entries as $e) {
echo $e;
echo "\n";
}
$rar_arch->close();
?>

上の例の出力は、 たとえば以下のようになります。

Found 2 entries.
RarEntry for file "tese.txt" (23b93a7a)
RarEntry for file "unrardll.txt" (2ed64b6e)

例2 手続き型

<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");

$rar_entries = rar_list($rar_arch);
if ($rar_entries === FALSE)
die("Could retrieve entries.");

echo "Found " . count($rar_entries) . " entries.\n";

foreach ($rar_entries as $e) {
echo $e;
echo "\n";
}
rar_close($rar_arch);
?>

参考

  • RarArchive::getEntry() - Rar アーカイブからエントリオブジェクトを取得する
  • rar:// ラッパー


Rar アーカイブからエントリオブジェクトを取得する

  • ≪ RarArchive::getEntries
  • RarArchive::isBroken ≫
  • PHP Manual
  • RarArchive
  • Rar アーカイブからエントリオブジェクトを取得する

RarArchive::getEntry

rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Rar アーカイブからエントリオブジェクトを取得する

説明

オブジェクト指向型 (メソッド)

public RarArchive::getEntry(string $entryname): RarEntry|false

手続き型:

rar_entry_get(RarArchive $rarfile, string $entryname): RarEntry|false

Rar アーカイブから、エントリオブジェクト (ファイルあるいはディレクトリ) を取得します。

注意:

RarArchive::getEntries() を使ってエントリオブジェクトを取得することもできます。

RAR アーカイブには、同じ名前のエントリを複数格納することができます。 このメソッドでは、その中の最初のものしか取得できません。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

entryname

Rar アーカイブ内のエントリへのパス。

注意:

このパスは、 RarEntry::getName() が返すものと同じでなければなりません。

戻り値

マッチした RarEntry オブジェクトを返します。失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entry = $rar_arch->getEntry('tese.txt');
if ($rar_entry === FALSE)
die("Could not get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
$rar_arch->close();
?>

上の例の出力は、 たとえば以下のようになります。

RarEntry
RarEntry for file "tese.txt" (23b93a7a)

例2 手続き型

<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entry = rar_entry_get($rar_arch, 'tese.txt');
if ($rar_entry === FALSE)
die("Could not get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
rar_close($rar_arch);
?>

参考

  • RarArchive::getEntries() - RAR アーカイブからエントリの全一覧を取得する
  • rar:// ラッパー


アーカイブが壊れている (未完成である) かどうかを調べる

  • ≪ RarArchive::getEntry
  • RarArchive::isSolid ≫
  • PHP Manual
  • RarArchive
  • アーカイブが壊れている (未完成である) かどうかを調べる

RarArchive::isBroken

rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — アーカイブが壊れている (未完成である) かどうかを調べる

説明

オブジェクト指向型 (メソッド)

public RarArchive::isBroken(): bool

手続き型:

rar_broken_is(RarArchive $rarfile): bool

この関数は、アーカイブが不完全である (ボリュームがなかったり、ボリュームが途中で終わっていたりする) かどうかを調べます。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

戻り値

アーカイブが壊れている場合に true、壊れていない場合に false を返します。 この関数は、渡されたファイルがすでに閉じている場合にも false を返します。どちらの原因かを特定するには exceptions with RarException::setUsingExceptions() で例外を有効にするしかありませんが、普通は閉じたファイルを操作することはないので これは不要なはずです。

例

例1 オブジェクト指向型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = RarArchive::open($file, null, 'retnull');
var_dump($arch->isBroken());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

例2 手続き型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = rar_open($file, null, 'retnull');
var_dump(rar_broken_is($arch));
?>

参考

  • RarArchive::setAllowBroken() - 壊れたアーカイブのオープンを許可するかどうかを設定する


RAR アーカイブがソリッドであるかどうかを調べる

  • ≪ RarArchive::isBroken
  • RarArchive::open ≫
  • PHP Manual
  • RarArchive
  • RAR アーカイブがソリッドであるかどうかを調べる

RarArchive::isSolid

rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — RAR アーカイブがソリッドであるかどうかを調べる

説明

オブジェクト指向型 (メソッド)

public RarArchive::isSolid(): bool

手続き型:

rar_solid_is(RarArchive $rarfile): bool

RAR アーカイブがソリッドであるかどうかを調べます。ソリッドなアーカイブでは、 個々のファイルの抽出速度が遅くなります。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

戻り値

アーカイブがソリッドである場合に true、それ以外の場合に false を返します。

例

例1 オブジェクト指向型

<?php
$arch1 = RarArchive::open("store_method.rar");
$arch2 = RarArchive::open("solid.rar");
echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

例2 手続き型

<?php
$arch1 = rar_open("store_method.rar");
$arch2 = rar_open("solid.rar");
echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
?>


Rar アーカイブをオープンする

  • ≪ RarArchive::isSolid
  • RarArchive::setAllowBroken ≫
  • PHP Manual
  • RarArchive
  • Rar アーカイブをオープンする

RarArchive::open

rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Rar アーカイブをオープンする

説明

オブジェクト指向型 (メソッド)

public static RarArchive::open(string $filename, string $password = NULL, callable $volume_callback = NULL): RarArchive|false

手続き型:

rar_open(string $filename, string $password = NULL, callable $volume_callback = NULL): RarArchive|false

指定した RAR アーカイブをオープンし、RarArchive インスタンスを返します。

注意:

マルチボリュームのアーカイブをオープンするときには、 最初のボリュームのパスをパラメータに指定します。 そうしないとすべてのファイルを表示することはできません。これは仕様です。

パラメータ

filename

Rar アーカイブへのパス。

password

ヘッダの復号に必要な場合、プレーンテキストのパスワード。 暗号化されたファイルが見つかったときにも、これがデフォルトのパスワードとして使われます。 ヘッダのパスワードとファイルのパスワードは異なる場合があることに注意しましょう。

volume_callback

ひとつのパラメータ (見つからなかったボリュームのパス) を受け取ってそのボリュームの正しいパスを返す関数。 この関数は、ボリュームが存在しなかったり未知であったりする場合は null を返さなければなりません。 この関数はループを引き起こさないようにしなければなりません。 前のコールで返されたパスがそのボリュームに対応しない場合に 関数が繰り返しコールされることがあるからです。 このパラメータを指定すると、ボリュームが見つからなかったときの notice は一切無視するようになります。したがって、 単に null を返すだけの実装を渡しておけば、 notice を無視させるためだけに使うこともできます。

警告

バージョン 2.0.0 より前では、この関数は相対パスを正しく処理できません。 回避策として realpath() を使いましょう。

戻り値

RarArchive インスタンスを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | volume_callback が追加されました。

例

例1 オブジェクト指向型

<?php
$rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
die("Failed opening file");

$entries = $rar_arch->getEntries();
if ($entries === FALSE)
die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
die("No valid entries found.");

$stream = reset($entries)->getStream();
if ($stream === FALSE)
die("Failed opening first file");

$rar_arch->close();

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>

上の例の出力は、 たとえば以下のようになります。

Found 2 files.
Content of first one follows:
Encrypted file 1 contents.

例2 手続き型

<?php
$rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
die("Failed opening file");

$entries = rar_list($rar_arch);
if ($entries === FALSE)
die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
die("No valid entries found.");

$stream = reset($entries)->getStream();
if ($stream === FALSE)
die("Failed opening first file");

rar_close($rar_arch);

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>

例3 ボリュームコールバック

<?php
/* この例では multi_broken.part1.rar というボリュームがあり、
* 次のボリュームが multi.part2.rar であるものとします */
function resolve($vol) {
if (preg_match('/_broken/', $vol))
return str_replace('_broken', '', $vol);
else
return null;
}
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>

参考

  • rar:// wrapper


壊れたアーカイブのオープンを許可するかどうかを設定する

  • ≪ RarArchive::open
  • RarArchive::__toString ≫
  • PHP Manual
  • RarArchive
  • 壊れたアーカイブのオープンを許可するかどうかを設定する

RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する

説明

オブジェクト指向型 (メソッド)

public RarArchive::setAllowBroken(bool $allow_broken): bool

手続き型:

rar_allow_broken_set(RarArchive $rarfile, bool $allow_broken): bool

このメソッドは、壊れたアーカイブの読み込みを許可するか、 あるいはアーカイブからエントリを抽出する操作をすべて失敗させるかを設定します。 壊れたアーカイブとは、ファイルのオープン時には何もエラーが検出されないのに エントリを読み込むときにエラーが発生するようなアーカイブのことです。

パラメータ

rarfile

rar_open() でオープンした RarArchive オブジェクト。

allow_broken

壊れたファイルの読み込みを許可する (true) か許可しない (false) か。

戻り値

true を返します。失敗した場合に false を返します。 失敗するのは、既にファイルが閉じられているときだけです。

例

例1 オブジェクト指向型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = RarArchive::open($file, null, 'retnull');
$a->setAllowBroken(true);
foreach ($a->getEntries() as $e) {
echo "$e\n";
}
var_dump(count($a));
?>

上の例の出力は、 たとえば以下のようになります。

RarEntry for file "file1.txt" (52b28202)
int(1)

例2 手続き型

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = rar_open($file, null, 'retnull');
rar_allow_broken_set($a, true);
foreach (rar_list($a) as $e) {
echo "$e\n";
}
var_dump(count($a));
?>

参考

  • RarArchive::isBroken() - アーカイブが壊れている (未完成である) かどうかを調べる


テキスト形式で取得する

  • ≪ RarArchive::setAllowBroken
  • RarEntry ≫
  • PHP Manual
  • RarArchive
  • テキスト形式で取得する

RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — テキスト形式で取得する

説明

public RarArchive::__toString(): string

この RarArchive オブジェクトの文字列表現を取得します。 現在表示されるのは、オープンしているアーカイブボリュームのフルパスと、 そのリソースが有効なのか RarArchive::close() で閉じられた後なのかということです。

このメソッドはデバッグ用にだけ使うものです。 結果にどのような情報が含まれるか、そしてどういった書式になるかなどは保証されていません。

パラメータ

この関数にはパラメータはありません。

戻り値

この RarArchive オブジェクトのテキスト表現を返します。 テキストの中身については未定義です。

例

例1 RarArchive::__toString() の例

<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>

上の例の出力は、 たとえば以下のようになります。

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)


The RarEntry class

(PECL rar >= 0.1)

はじめに

A RAR entry, representing a directory or a compressed file inside a RAR archive.

クラス概要

final class RarEntry {
/* 定数 */
const int HOST_MSDOS = 0;
const int HOST_OS2 = 1;
const int HOST_WIN32 = 2;
const int HOST_UNIX = 3;
const int HOST_MACOS = 4;
const int HOST_BEOS = 5;
const int ATTRIBUTE_WIN_READONLY = 1;
const int ATTRIBUTE_WIN_HIDDEN = 2;
const int ATTRIBUTE_WIN_SYSTEM = 4;
const int ATTRIBUTE_WIN_DIRECTORY = 16;
const int ATTRIBUTE_WIN_ARCHIVE = 32;
const int ATTRIBUTE_WIN_DEVICE = 64;
const int ATTRIBUTE_WIN_NORMAL = 128;
const int ATTRIBUTE_WIN_TEMPORARY = 256;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024;
const int ATTRIBUTE_WIN_COMPRESSED = 2048;
const int ATTRIBUTE_WIN_OFFLINE = 4096;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384;
const int ATTRIBUTE_WIN_VIRTUAL = 65536;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2;
const int ATTRIBUTE_UNIX_WORLD_READ = 4;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16;
const int ATTRIBUTE_UNIX_GROUP_READ = 32;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128;
const int ATTRIBUTE_UNIX_OWNER_READ = 256;
const int ATTRIBUTE_UNIX_STICKY = 512;
const int ATTRIBUTE_UNIX_SETGID = 1024;
const int ATTRIBUTE_UNIX_SETUID = 2048;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440;
const int ATTRIBUTE_UNIX_FIFO = 4096;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960;
const int ATTRIBUTE_UNIX_SOCKET = 49152;
/* メソッド */
public extract(
string $dir,
string $filepath = "",
string $password = NULL,
bool $extended_data = false
): bool
public getAttr(): int
public getCrc(): string
public getFileTime(): string
public getHostOs(): int
public getMethod(): int
public getName(): string
public getPackedSize(): int
public getStream(string $password = ?): resource|false
public getUnpackedSize(): int
public getVersion(): int
public isDirectory(): bool
public isEncrypted(): bool
public __toString(): string
}

定義済み定数

RarEntry::HOST_MSDOS

If the return value of RarEntry::getHostOs() equals this constant, MS-DOS was used to add this entry. Use instead of RAR_HOST_MSDOS.

RarEntry::HOST_OS2

If the return value of RarEntry::getHostOs() equals this constant, OS/2 was used to add this entry. Intended to replace RAR_HOST_OS2.

RarEntry::HOST_WIN32

If the return value of RarEntry::getHostOs() equals this constant, Microsoft Windows was used to add this entry. Intended to replace RAR_HOST_WIN32.

RarEntry::HOST_UNIX

If the return value of RarEntry::getHostOs() equals this constant, an unspecified UNIX OS was used to add this entry. Intended to replace RAR_HOST_UNIX.

RarEntry::HOST_MACOS

If the return value of RarEntry::getHostOs() equals this constant, Mac OS was used to add this entry.

RarEntry::HOST_BEOS

If the return value of RarEntry::getHostOs() equals this constant, BeOS was used to add this entry. Intended to replace RAR_HOST_BEOS.

RarEntry::ATTRIBUTE_WIN_READONLY

Bit that represents a Windows entry with a read-only attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_HIDDEN

Bit that represents a Windows entry with a hidden attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SYSTEM

Bit that represents a Windows entry with a system attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DIRECTORY

Bit that represents a Windows entry with a directory attribute (entry is a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.

RarEntry::ATTRIBUTE_WIN_ARCHIVE

Bit that represents a Windows entry with an archive attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DEVICE

Bit that represents a Windows entry with a device attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NORMAL

Bit that represents a Windows entry with a normal file attribute (entry is NOT a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.

RarEntry::ATTRIBUTE_WIN_TEMPORARY

Bit that represents a Windows entry with a temporary attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SPARSE_FILE

Bit that represents a Windows entry with a sparse file attribute (file is an NTFS sparse file). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_REPARSE_POINT

Bit that represents a Windows entry with a reparse point attribute (entry is an NTFS reparse point, e.g. a directory junction or a mount file system). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_COMPRESSED

Bit that represents a Windows entry with a compressed attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_OFFLINE

Bit that represents a Windows entry with an offline attribute (entry is offline and not accessible). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED

Bit that represents a Windows entry with a not content indexed attribute (entry is to be indexed). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_ENCRYPTED

Bit that represents a Windows entry with an encrypted attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_VIRTUAL

Bit that represents a Windows entry with a virtual attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE

Bit that represents a UNIX entry that is world executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE

Bit that represents a UNIX entry that is world writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_READ

Bit that represents a UNIX entry that is world readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE

Bit that represents a UNIX entry that is group executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE

Bit that represents a UNIX entry that is group writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_READ

Bit that represents a UNIX entry that is group readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE

Bit that represents a UNIX entry that is owner executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE

Bit that represents a UNIX entry that is owner writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_READ

Bit that represents a UNIX entry that is owner readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_STICKY

Bit that represents the UNIX sticky bit. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_SETGID

Bit that represents the UNIX setgid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_SETUID

Bit that represents the UNIX setuid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET

Mask to isolate the last four bits (nibble) of UNIX attributes
      (_S_IFMT, the type of file mask). To be used with
      RarEntry::getAttr() on entries whose host OS is UNIX and with the
      constants  RarEntry::ATTRIBUTE_UNIX_FIFO,
       RarEntry::ATTRIBUTE_UNIX_CHAR_DEV,
       RarEntry::ATTRIBUTE_UNIX_DIRECTORY,
       RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV,
       RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE,
       RarEntry::ATTRIBUTE_UNIX_SYM_LINK and
       RarEntry::ATTRIBUTE_UNIX_SOCKET.

RarEntry::ATTRIBUTE_UNIX_FIFO

Unix FIFOs will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_CHAR_DEV

Unix character devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_DIRECTORY

Unix directories will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.

RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV

Unix block devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE

Unix regular files (not directories) will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.

RarEntry::ATTRIBUTE_UNIX_SYM_LINK

Unix symbolic links will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_SOCKET

Unix sockets will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

目次

  • RarEntry::extract — アーカイブのエントリを展開する
  • RarEntry::getAttr — エントリの属性を取得する
  • RarEntry::getCrc — エントリの CRC を取得する
  • RarEntry::getFileTime — エントリの最終更新時刻を取得する
  • RarEntry::getHostOs — エントリのホスト OS を取得する
  • RarEntry::getMethod — エントリの圧縮方法を取得する
  • RarEntry::getName — エントリの名前を取得する
  • RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する
  • RarEntry::getStream — このエントリのファイルハンドラを取得する
  • RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する
  • RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する
  • RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる
  • RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる
  • RarEntry::__toString — エントリのテキスト表現を取得する


アーカイブのエントリを展開する

  • ≪ RarEntry
  • RarEntry::getAttr ≫
  • PHP Manual
  • RarEntry
  • アーカイブのエントリを展開する

RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — アーカイブのエントリを展開する

説明

public RarEntry::extract(
string $dir,
string $filepath = "",
string $password = NULL,
bool $extended_data = false
): bool

RarEntry::extract() は、エントリのデータを展開します。 二番目の引数が指定されていなければ、 指定した dir にエントリの名前と同名の新しいファイルを作成します。 詳細は以下を参照ください。

パラメータ

dir

ファイルを展開するディレクトリへのパス。 このパラメータが考慮されるのは filepath が指定されていないときだけです。両方のパラメータが空の場合は、 カレントディレクトリへの展開を試みます。

filepath

取り出すファイルのディレクトリとファイル名を含むパス (相対パスあるいは絶対パス)。 このパラメータは、dir の内容と元のファイル名を両方とも上書きします。

password

このエントリの暗号化に使うパスワード。 エントリが暗号化されていない場合は、この値は使われずに無視されます。 このパラメータが省略されていてエントリが暗号化されていた場合は、もし rar_open() でパスワードを指定していればそれを使います。 このパラメータや rar_open() で指定したパスワードが間違っていたときは、 CRC チェックが失敗してこのメソッドが失敗し、false を返します。 パスワードが要求されているときにパスワードを指定していなければ、 このメソッドは失敗して false を返します。 エントリが暗号化されているかどうかを知るには RarEntry::isEncrypted() を使います。

extended_data

true にすると、NTFS の ACL や Unix のオーナー情報といった拡張情報が アーカイブに設定されていれば、取り出したファイルにもそれを設定します。

警告

バージョン 2.0.0 より前は、この関数では相対パスを正しく扱えません。 回避策として realpath() を使いましょう。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | extended_data が追加されました。
PECL rar 3.0.0 | エントリ名が繰り返される RAR アーカイブも対応するようになりました。

例

例1 RarEntry::extract() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

$entry->extract('/dir/to'); // /dir/to/Dir/file.txt を作成します
$entry->extract(false, '/dir/to/new_name.txt'); // /dir/to/new_name.txt を作成します

?>

例2 アーカイブ内のすべてのファイルを展開する方法

<?php

/* erix こと Erik Jenssen によるサンプルです */

$filename = "foobar.rar";
$filepath = "/home/foo/bar/";

$rar_file = rar_open($filepath.$filename);
$list = rar_list($rar_file);
foreach($list as $file) {
$entry = rar_entry_get($rar_file, $file);
$entry->extract("."); // カレントディレクトリに展開します
}
rar_close($rar_file);

?>

参考

  • RarEntry::getStream() - このエントリのファイルハンドラを取得する
  • rar:// wrapper


エントリの属性を取得する

  • ≪ RarEntry::extract
  • RarEntry::getCrc ≫
  • PHP Manual
  • RarEntry
  • エントリの属性を取得する

RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — エントリの属性を取得する

説明

public RarEntry::getAttr(): int

アーカイブエントリの、OS に依存する属性を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

属性、あるいはエラー時に false を返します。

例

例1 RarEntry::getAttr() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("そのようなエントリは見つかりません");

$host_os = $entry->getHostOs();
$attr = $entry->getAttr();

switch($host_os) {
case RAR_HOST_MSDOS:
case RAR_HOST_OS2:
case RAR_HOST_WIN32:
case RAR_HOST_MACOS:
printf("%c%c%c%c%c%c\n",
($attr & 0x08) ? 'V' : '.',
($attr & 0x10) ? 'D' : '.',
($attr & 0x01) ? 'R' : '.',
($attr & 0x02) ? 'H' : '.',
($attr & 0x04) ? 'S' : '.',
($attr & 0x20) ? 'A' : '.');
break;
case RAR_HOST_UNIX:
case RAR_HOST_BEOS:
switch ($attr & 0xF000)
{
case 0x4000:
printf("d");
break;
case 0xA000:
printf("l");
break;
default:
printf("-");
break;
}
printf("%c%c%c%c%c%c%c%c%c\n",
($attr & 0x0100) ? 'r' : '-',
($attr & 0x0080) ? 'w' : '-',
($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
($attr & 0x0020) ? 'r' : '-',
($attr & 0x0010) ? 'w' : '-',
($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
($attr & 0x0004) ? 'r' : '-',
($attr & 0x0002) ? 'w' : '-',
($attr & 0x0001) ? 'x' : '-');
break;
}

rar_close($rar_file);

?>

参考

  • RarEntry::getHostOs() - エントリのホスト OS を取得する
  • The constants in RarEntry


エントリの CRC を取得する

  • ≪ RarEntry::getAttr
  • RarEntry::getFileTime ≫
  • PHP Manual
  • RarEntry
  • エントリの CRC を取得する

RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — エントリの CRC を取得する

説明

public RarEntry::getCrc(): string

アーカイブエントリの CRC を、十六進文字列表現で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

アーカイブエントリの CRC、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | 複数ボリュームのアーカイブでも正しい値を返すようになりました。


エントリの最終更新時刻を取得する

  • ≪ RarEntry::getCrc
  • RarEntry::getHostOs ≫
  • PHP Manual
  • RarEntry
  • エントリの最終更新時刻を取得する

RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — エントリの最終更新時刻を取得する

説明

public RarEntry::getFileTime(): string

エントリの最終更新時刻を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

エントリの最終更新時刻を YYYY-MM-DD HH:II:SS 形式で表した文字列、あるいはエラー時に false を返します。


エントリのホスト OS を取得する

  • ≪ RarEntry::getFileTime
  • RarEntry::getMethod ≫
  • PHP Manual
  • RarEntry
  • エントリのホスト OS を取得する

RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — エントリのホスト OS を取得する

説明

public RarEntry::getHostOs(): int

アーカイブエントリのホスト OS のコードを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ホスト OS のコード、あるいはエラー時に false を返します。

例

例1 RarEntry::getHostOs() の例 (バージョン >= 2.0.0)

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

switch ($entry->getHostOs()) {
case RarEntry::HOST_MSDOS:
echo "MS-DOS\n";
break;
case RarEntry::HOST_OS2:
echo "OS2\n";
break;
case RarEntry::HOST_WIN32:
echo "Win32\n";
break;
case RarEntry::HOST_MACOS:
echo "MacOS\n";
break;
case RarEntry::HOST_UNIX:
echo "Unix/Linux\n";
break;
case RarEntry::HOST_BEOS:
echo "BeOS\n";
break;
}

?>

例2 RarEntry::getHostOs() の例 (バージョン <= 1.0.0)

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

switch ($entry->getHostOs()) {
case RAR_HOST_MSDOS:
echo "MS-DOS\n";
break;
case RAR_HOST_OS2:
echo "OS2\n";
break;
case RAR_HOST_WIN32:
echo "Win32\n";
break;
case RAR_HOST_MACOS:
echo "MacOS\n";
break;
case RAR_HOST_UNIX:
echo "Unix/Linux\n";
break;
case RAR_HOST_BEOS:
echo "BeOS\n";
break;
}

?>

参考

  • RarEntry::extract() - アーカイブのエントリを展開する


エントリの圧縮方法を取得する

  • ≪ RarEntry::getHostOs
  • RarEntry::getName ≫
  • PHP Manual
  • RarEntry
  • エントリの圧縮方法を取得する

RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — エントリの圧縮方法を取得する

説明

public RarEntry::getMethod(): int

RarEntry::getMethod() は、現在のアーカイブエントリを 追加する際に使用したメソッドの番号を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

メソッド番号、あるいはエラー時に false を返します。

例

例1 RarEntry::getMethod() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "メソッド番号: " . $entry->getMethod();

?>


エントリの名前を取得する

  • ≪ RarEntry::getMethod
  • RarEntry::getPackedSize ≫
  • PHP Manual
  • RarEntry
  • エントリの名前を取得する

RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — エントリの名前を取得する

説明

public RarEntry::getName(): string

アーカイブエントリの名前 (パスつき) を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エントリ名を表す文字列、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | バージョン 2.0.0 以降、返される文字列のエンコードは Unicode/UTF-8 となりました。

例

例1 RarEntry::getName() の例

<?php

// このサンプルは、ページが UTF-8 でエンコードされていなくても安全です。
// UTF-8 でエンコードされているページの場合は mb_convert_encoding は不要です。

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "Entry name: " . mb_convert_encoding(
htmlentities(
$entry->getName(),
ENT_COMPAT,
"UTF-8"
),
"HTML-ENTITIES",
"UTF-8"
);

?>


圧縮後のエントリのサイズを取得する

  • ≪ RarEntry::getName
  • RarEntry::getStream ≫
  • PHP Manual
  • RarEntry
  • 圧縮後のエントリのサイズを取得する

RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する

説明

public RarEntry::getPackedSize(): int

圧縮後のアーカイブエントリのサイズを取得します。

注意:

調整数型が 32 ビットであるプラットフォーム (Windows x64 など) では、返されるサイズの上限は 2 GiB となります。定数 PHP_INT_MAX をチェックしましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

圧縮後のサイズ、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | このメソッドは、64 ビット整数型のプラットフォームで 2 GiB を超えるサイズを正しく返せるようになりました。 また、それ以外のプラットフォームでも負の値を返すことがなくなりました。

例

例1 RarEntry::getPackedSize() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "圧縮後の " . $entry->getName() . " のサイズ = " . $entry->getPackedSize() . " バイト";

?>


このエントリのファイルハンドラを取得する

  • ≪ RarEntry::getPackedSize
  • RarEntry::getUnpackedSize ≫
  • PHP Manual
  • RarEntry
  • このエントリのファイルハンドラを取得する

RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — このエントリのファイルハンドラを取得する

説明

public RarEntry::getStream(string $password = ?): resource|false

読み込み操作をサポートするファイルハンドラを返します。 このハンドラを使って、このエントリをその場で展開します。

このハンドラは、rar_close() をコールしても無効にはなりません。

警告

返されるストリームでは、整合性の検証を行いません。 特に、ファイルの破損や間違ったキーによる復号は検出できません。 もし整合性を検証したいのなら、エントリの CRC を確認するのはプログラマ側の役割となります。

パラメータ

password

このエントリの暗号化に使うパスワード。 エントリが暗号化されていない場合は、この値は使われずに無視されます。 このパラメータが省略されていてエントリが暗号化されていた場合は、もし rar_open() でパスワードを指定していればそれを使います。 このパラメータや rar_open() で指定したパスワードが間違っていたときは、 このメソッドの結果のストリームは間違った結果を出力します。 パスワードが要求されているときにパスワードを指定していなければ、 このメソッドは失敗して false を返します。 エントリが暗号化されているかどうかを知るには RarEntry::isEncrypted() を使います。

戻り値

ファイルハンドラを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL rar 3.0.0 | エントリ名が繰り返される RAR アーカイブも対応するようになりました。

例

例1 RarEntry::getStream() の例

<?php

$rar_file = rar_open('example.rar');
if ($rar_file === false)
die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt');
if ($entry === false)
die("そのようなエントリは見つかりません");

$stream = $entry->getStream();
if ($stream === false)
die("ストリームの取得に失敗しました");

rar_close($rar_file); // ストリームはファイルとは独立しています

while (!feof($stream)) {
$buff = fread($stream, 8192);
if ($buff !== false)
echo $buff;
else
break; // fread のエラー
}

fclose($stream);

?>

参考

  • RarEntry::extract() - アーカイブのエントリを展開する
  • rar:// ラッパー


展開後のエントリのサイズを取得する

  • ≪ RarEntry::getStream
  • RarEntry::getVersion ≫
  • PHP Manual
  • RarEntry
  • 展開後のエントリのサイズを取得する

RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する

説明

public RarEntry::getUnpackedSize(): int

展開後のアーカイブエントリのサイズを取得します。

注意:

調整数型が 32 ビットであるプラットフォーム (Windows x64 など) では、返されるサイズの上限は 2 GiB となります。定数 PHP_INT_MAX をチェックしましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

展開後のサイズ、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
PECL rar 2.0.0 | このメソッドは、64 ビット整数型のプラットフォームで 2 GiB を超えるサイズを正しく返せるようになりました。 また、それ以外のプラットフォームでも負の値を返すことがなくなりました。

戻り値

例1 RarEntry::getUnpackedSize() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりません");

echo "展開後の " . $entry->getName() . " のサイズ = " . $entry->getUnpackedSize() . " バイト";

?>


このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

  • ≪ RarEntry::getUnpackedSize
  • RarEntry::isDirectory ≫
  • PHP Manual
  • RarEntry
  • このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

説明

public RarEntry::getVersion(): int

このエントリを展開するのに必要な RAR プログラム (WinRAR など) の最低バージョンを取得します。 10 * メジャーバージョン + マイナーバージョン 形式になります。

パラメータ

この関数にはパラメータはありません。

戻り値

バージョン、あるいはエラー時に false を返します。

例

例1 RarEntry::getVersion() の例

<?php

$rar_file = rar_open('example.rar') or die("Rar アーカイブのオープンに失敗しました");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("そのようなエントリは見つかりませんでした");

echo "展開に必要な Rar のバージョン: " . $entry->getVersion();

?>


このエントリがディレクトリであるかどうかを調べる

  • ≪ RarEntry::getVersion
  • RarEntry::isEncrypted ≫
  • PHP Manual
  • RarEntry
  • このエントリがディレクトリであるかどうかを調べる

RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる

説明

public RarEntry::isDirectory(): bool

現在のエントリがディレクトリであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

エントリがディレクトリである場合に true、それ以外の場合に false を返します。

注意

この関数はバージョン 2.0.0 以降でしか使えませんが、 エントリの属性をチェックすればディレクトリであるかどうかを調べることができます (RAR for Windows あるいは Unix で圧縮したファイルでしか使えません)。

<?php
//...
//Open file, get entry and store in variable $e...
//...

$isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
(($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
?>


このエントリが暗号化されているかどうかを調べる

  • ≪ RarEntry::isDirectory
  • RarEntry::__toString ≫
  • PHP Manual
  • RarEntry
  • このエントリが暗号化されているかどうかを調べる

RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる

説明

public RarEntry::isEncrypted(): bool

現在のディレクトリが暗号化されているかどうかを調べます。

注意:

同じ RAR アーカイブ内でも、ファイルによってパスワードが異なることがあります。

パラメータ

この関数にはパラメータはありません。

戻り値

エントリが暗号化されている場合に true、それ以外の場合に false を返します。


エントリのテキスト表現を取得する

  • ≪ RarEntry::isEncrypted
  • RarException ≫
  • PHP Manual
  • RarEntry
  • エントリのテキスト表現を取得する

RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — エントリのテキスト表現を取得する

説明

public RarEntry::__toString(): string

RarEntry::__toString() は、このエントリのテキスト表現を返します。 その内容は、まずエントリがファイルであるかディレクトリであるか (シンボリックリンクやその他の特殊オブジェクトはファイルとみなされます)、 そしてエントリ名を UTF-8 であらわしたものと CRC となります。 この形式と内容は将来変更される可能性があるので、これに依存してはいけません。

パラメータ

この関数にはパラメータはありません。

戻り値

エントリのテキスト表現を返します。


RarException クラス

(PECL rar >= 2.0.0)

はじめに

このクラスの役割は、RAR 拡張モジュールの関数やメソッドからスローされた例外を表す型となることと staticメソッドを使ってエラーの詳細 (例外がスローされたのか、 それとも警告が発生しただけなのかなど) を得ることのふたつです。

次のエラーコードを使います。

  • -1 - UnRAR ライブラリ以外のエラー
  • 11 - メモリの不足
  • 12 - データ不良
  • 13 - アーカイブ不良
  • 14 - 未知のフォーマット
  • 15 - ファイルオープンエラー
  • 16 - ファイル作成エラー
  • 17 - ファイルクローズエラー
  • 18 - 読み込みエラー
  • 19 - 書き込みエラー
  • 20 - バッファ不足
  • 21 - 未知の RAR エラー
  • 22 - パスワードが要求されているのに指定しなかった

クラス概要

final class RarException extends Exception {
/* メソッド */
public static isUsingExceptions(): bool
public static setUsingExceptions(bool $using_exceptions): void
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

目次

  • RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる
  • RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う


例外によるエラー処理を使っているかどうかを調べる

  • ≪ RarException
  • RarException::setUsingExceptions ≫
  • PHP Manual
  • RarException
  • 例外によるエラー処理を使っているかどうかを調べる

RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる

説明

public static RarException::isUsingExceptions(): bool

RAR 関数が警告を発してエラー値を返すようになっているか、 あるいは例外をスローするようになっているかを調べます (引数の型を間違えるなどのプログラム上のエラーは含めません)。

パラメータ

この関数にはパラメータはありません。

戻り値

例外を使っている場合に true、それ以外の場合に false を返します。

例

例1 RarException::isUsingExceptions() の例

<?php
// デフォルトでは例外を使いません
var_dump(RarException::isUsingExceptions());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)

参考

  • RarException::setUsingExceptions() - 例外によるエラー処理の有効化および無効化を行う


例外によるエラー処理の有効化および無効化を行う

  • ≪ RarException::isUsingExceptions
  • Zip ≫
  • PHP Manual
  • RarException
  • 例外によるエラー処理の有効化および無効化を行う

RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う

説明

public static RarException::setUsingExceptions(bool $using_exceptions): void

引数に true を指定すると、UnRAR ライブラリがエラーに遭遇したときの挙動を変更し、 警告を発してエラーを示す値を返すのではなく RarException 型の例外をスローするようにします。

例外は次のエラーのときにもスローされます。これらはライブラリの外部で発生します (エラーコードは -1 です)。

  • 既に閉じた RarArchive オブジェクトやそれに関する RarEntry オブジェクトへのアクセスを試みたとき。
  • 存在しないエントリを RarArchive::getEntry() で取得しようと試みたとき。

パラメータ

using_exceptions

例外をスローさせるときは true、例外をスローさせないときは false (デフォルト)。

戻り値

値を返しません。

例

例1 RarException::setUsingExceptions() の例

<?php
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch);

RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch); //not reached
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)

Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)

Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
  thrown in C:\php_rar\trunk\tests\test.php on line 8

参考

  • RarException::isUsingExceptions() - 例外によるエラー処理を使っているかどうかを調べる


Zip

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
  • ZipArchive — ZipArchive クラス
    • ZipArchive::addEmptyDir — 新しいディレクトリを追加する
    • ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する
    • ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する
    • ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する
    • ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する
    • ZipArchive::clearError — ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする
    • ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる
    • ZipArchive::count — アーカイブにあるファイルの数を数える
    • ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する
    • ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する
    • ZipArchive::extractTo — アーカイブの内容を展開する
    • ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す
    • ZipArchive::getArchiveFlag — Zip アーカイブのグローバルフラグの値を返す
    • ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す
    • ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す
    • ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する
    • ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する
    • ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す
    • ZipArchive::getFromName — 名前を使用して、エントリの内容を返す
    • ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す
    • ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す
    • ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する
    • ZipArchive::getStreamIndex — インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
    • ZipArchive::getStreamName — 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
    • ZipArchive::isCompressionMethodSupported — 圧縮方式を libzip がサポートしているかをチェックする
    • ZipArchive::isEncryptionMethodSupported — 暗号化方式を libzip がサポートしているかどうかをチェックする
    • ZipArchive::locateName — アーカイブ内のエントリのインデックスを返す
    • ZipArchive::open — ZIP ファイルアーカイブをオープンする
    • ZipArchive::registerCancelCallback — アーカイブを閉じている間にキャンセルできるようにコールバックを登録する
    • ZipArchive::registerProgressCallback — アーカイブを閉じている間に更新できるようにコールバックを登録する
    • ZipArchive::renameIndex — インデックスを使用してエントリ名を変更する
    • ZipArchive::renameName — 名前を使用してエントリ名を変更する
    • ZipArchive::replaceFile — 指定されたパスのファイルにアーカイブの一部を置き換える
    • ZipArchive::setArchiveComment — ZIP アーカイブのコメントを設定する
    • ZipArchive::setArchiveFlag — Zip アーカイブのグローバルフラグを設定する
    • ZipArchive::setCommentIndex — インデックスを使用してエントリのコメントを設定する
    • ZipArchive::setCommentName — 名前を使用してエントリのコメントを設定する
    • ZipArchive::setCompressionIndex — インデックスで定義されたエントリの圧縮方法を設定する
    • ZipArchive::setCompressionName — 名前で定義されたエントリの圧縮メソッドを設定する
    • ZipArchive::setEncryptionIndex — index で定義されたエントリの暗号化方法を指定する
    • ZipArchive::setEncryptionName — 名前で定義されたエントリの暗号化方式を設定する
    • ZipArchive::setExternalAttributesIndex — インデックスで定義されたエントリの外部属性を設定する
    • ZipArchive::setExternalAttributesName — 名前で定義されたエントリの外部属性を設定する
    • ZipArchive::setMtimeIndex — インデックスを使用してエントリの変更時間を設定する
    • ZipArchive::setMtimeName — 名前を使ってエントリの変更時間を設定する
    • ZipArchive::setPassword — アクティブなアーカイブにパスワードを設定する
    • ZipArchive::statIndex — インデックスを使用してエントリの詳細を取得する
    • ZipArchive::statName — 名前を使用してエントリの詳細を取得する
    • ZipArchive::unchangeAll — アーカイブに対するすべての変更を取り消す
    • ZipArchive::unchangeArchive — アーカイブ全体に対して行われたすべての変更を取り消す
    • ZipArchive::unchangeIndex — 指定したインデックスのエントリに対するすべての変更を取り消す
    • ZipArchive::unchangeName — 指定した名前のエントリに対するすべての変更を取り消す
  • Zip 関数
    • zip_close — ZIP ファイルアーカイブを閉じる
    • zip_entry_close — ディレクトリエントリを閉じる
    • zip_entry_compressedsize — ディレクトリエントリの圧縮時のサイズを取得する
    • zip_entry_compressionmethod — ディレクトリエントリの圧縮方法を取得する
    • zip_entry_filesize — ディレクトリエントリの実際のファイルサイズを取得する
    • zip_entry_name — ディレクトリエントリの名前を取得する
    • zip_entry_open — 読込み用にディレクトリエントリをオープンする
    • zip_entry_read — オープンされたディレクトリエントリから読み込む
    • zip_open — Zip ファイルアーカイブをオープンする
    • zip_read — Zip ファイルアーカイブの中の次のエントリを読み込む


はじめに

この拡張モジュールにより、ZIP 圧縮されたアーカイブとその内部のファイルに対する透過的な読み書きが可能となります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Zip
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

この拡張モジュールには、» libzip が必要です。PHP 7.3 までは、libzip 1.1.2 がバンドルされていました。

サポートされている最も古いバージョンは 0.11 ですが、 それより新しいバージョンを使うことを強く推奨します。

  • 暗号化をサポートするにはバージョン 1.2 が必要です。ZipArchive::setEncryptionIndex() を参照ください。
  • 処理の進行に応じたコールバックをサポートするには、バージョン 1.3 が必要です。ZipArchive::registerProgressCallback() を参照ください。
  • 処理のキャンセルをサポートするには、バージョン 1.6 が必要です。ZipArchive::registerCancelCallback() を参照ください。


インストール手順

Linux システム

これらの関数を利用するには、設定オプション --with-zip を使用して ZIP サポートを有効にして PHP をコンパイルしなければなりません。

PHP 7.4.0 より前のバージョンでは、libzip は PHP にバンドルされていました。 拡張モジュールをコンパイルするには、--enable-zip オプションを使う必要がありました。 PHP 7.3.0 以降では、バンドルされている libzip を使って PHP をビルドすることは推奨されなくなりました。 しかし、--without-libzip オプションを configure オプションに追加することで バンドルされている libzip を使えていました。

--with-libzip=DIR オプションが追加されています。 これを指定すると、システムにインストールされた libzip を利用します。 これには、libzip 0.11 以降が必要です。0.11.2 以降を推奨します。

Windows

PHP 8.2.0 以降では、 php_zip.dll を php.ini で有効にする必要があります。 それより前のバージョンでは、この拡張モジュールは標準で PHP に組み込まれていました。

PECL 経由でのインストール

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/zip.


リソース型

Zip モジュールでは二種類のリソース型が使用されます。 まず最初が Zip アーカイブを表す Zip directory で、 もうひとつはアーカイブのエントリを表す Zip Entry です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

ZipArchive はクラス定数を使用します。 定数には様々なタイプがありますが、主なものは以下です: フラグ (接頭辞 FL_)、 グローバルフラグ(接頭辞 AFL_)、 エラー (接頭辞 ER_)、 モード (接頭辞なし)。

アーカイブのオープンモード
ZipArchive::CREATE (int)
アーカイブが存在しない場合に、作成します。
ZipArchive::OVERWRITE (int)
常に新しいアーカイブを開始します。このモードは、 ファイルが既に存在する場合にはそれを上書きします。
ZipArchive::EXCL (int)
アーカイブが既に存在する場合はエラーとします。
ZipArchive::RDONLY (int)
アーカイブを読み取り専用で開きます。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.17.1 以降で利用可能です。
ZipArchive::CHECKCONS (int)
アーカイブの一貫性チェックを別途行い、 失敗した場合はエラーとします。
アーカイブのグローバルフラグ
ZipArchive::AFL_RDONLY (int)
アーカイブが読み取り専用であることを示します。 クリアできません。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。 それぞれ、libzip ? 1.10.0 以降でビルドした場合に利用できます。
ZipArchive::AFL_IS_TORRENTZIP (int)
アーカイブが torrentzip フォーマットであることを示します。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。 それぞれ、libzip ? 1.10.0 以降でビルドした場合に利用できます。
ZipArchive::AFL_WANT_TORRENTZIP (int)
書き込みアーカイブが torrentzip フォーマットであることを示します。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。 それぞれ、libzip ? 1.10.0 以降でビルドした場合に利用できます。
ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE (int)
アーカイブが空の場合に、ファイルを削除しません。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。 それぞれ、libzip ? 1.10.0 以降でビルドした場合に利用できます。
アーカイブのフラグ
ZipArchive::FL_NOCASE (int)
名前で検索する際に大文字小文字を区別しません。
ZipArchive::FL_NODIR (int)
ディレクトリ要素を無視します。
ZipArchive::FL_COMPRESSED (int)
圧縮されたデータを読み込みます。
ZipArchive::FL_UNCHANGED (int)
元のデータを使用し、変更内容を無視します。
ZipArchive::FL_RECOMPRESS (int)
データを強制的に再び圧縮します。 PHP 8.0.0 以降、PECL zip 1.18.0 以降で利用可能です。 PHP 8.3.0 以降、PECL zip 1.22.1 以降では推奨されなくなりました。 libzip の将来のバージョンで削除予定です。
ZipArchive::FL_ENCRYPTED (int)
暗号化されたデータを読み込みます(FL_COMPRESSED が有効な場合)。 PHP 8.0.0 以降、PECL zip 1.18.0 以降で利用可能です。
ZipArchive::FL_OVERWRITE (int)
ファイル名が存在する場合、上書き(置き換え)します。 PHP 8.0.0 以降、PECL zip 1.18.0 以降で利用可能です。
ZipArchive::FL_LOCAL (int)
ローカルファイルヘッダ。 PHP 8.0.0 以降、PECL zip 1.18.0 以降で利用可能です。
ZipArchive::FL_CENTRAL (int)
セントラルディレクトリ。 PHP 8.0.0 以降、PECL zip 1.18.0 以降で利用可能です。
ZipArchive::FL_ENC_GUESS (int)
文字エンコーディングを推測します (デフォルト)。PHP 7.0.8 以降で利用可能です。
ZipArchive::FL_ENC_RAW (int)
何も手を加えない文字列を取得します。PHP 7.0.8 以降で利用可能です。
ZipArchive::FL_ENC_STRICT (int)
指示に厳格に従います。PHP 7.0.8 以降で利用可能です。
ZipArchive::FL_ENC_UTF_8 (int)
文字列のエンコーディングは UTF-8 です。PHP 7.0.8 以降で利用可能です。
ZipArchive::FL_ENC_CP437 (int)
文字列のエンコーディングは CP437 です。PHP 7.0.8 以降で利用可能です。
ZipArchive::FL_OPEN_FILE_NOW (int)
ファイルが追加された際に、アーカイブがクローズされるのを待つ代わりに、 ファイルをオープンします。 ファイルディスクリプタが消費されることに注意してください。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。
圧縮モード
ZipArchive::CM_DEFAULT (int)
圧縮あるいは保存のどちらか有効なほうを実行します。
ZipArchive::CM_STORE (int)
保存します (圧縮しません)。
ZipArchive::CM_SHRINK (int)
圧縮します。
ZipArchive::CM_REDUCE_1 (int)
Reduced 方式(compression factor 1)
ZipArchive::CM_REDUCE_2 (int)
Reduced 方式(compression factor 2)
ZipArchive::CM_REDUCE_3 (int)
Reduced 方式(compression factor 3)
ZipArchive::CM_REDUCE_4 (int)
Reduced 方式(compression factor 4)
ZipArchive::CM_IMPLODE (int)
Imploded 方式
ZipArchive::CM_DEFLATE (int)
Deflated 方式
ZipArchive::CM_DEFLATE64 (int)
Deflate64 方式
ZipArchive::CM_PKWARE_IMPLODE (int)
PKWARE 方式。
ZipArchive::CM_BZIP2 (int)
BZIP2 アルゴリズム。
ZipArchive::CM_LZMA (int)
LZMA アルゴリズム
ZipArchive::CM_LZMA2 (int)
LZMA2 アルゴリズム。 libzip ? 1.6.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.0 以降で利用可能です。
ZipArchive::CM_ZSTD (int)
Zstandard アルゴリズム。 libzip ? 1.8.0 でビルドした場合、 PHP 8.0.0 以降、PECL zip 1.19.0 以降で利用可能です。
ZipArchive::CM_XZ (int)
XZ アルゴリズム。 libzip ? 1.6.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::CM_TERSE (int)
ZipArchive::CM_LZ77 (int)
ZipArchive::CM_WAVPACK (int)
ZipArchive::CM_PPMD (int)
エラー
ZipArchive::ER_OK (int)
エラーはありません。
ZipArchive::ER_MULTIDISK (int)
複数ディスクの zip アーカイブはサポートされません。
ZipArchive::ER_RENAME (int)
一時ファイルの名前変更に失敗しました。
ZipArchive::ER_CLOSE (int)
zip アーカイブのクローズに失敗しました。
ZipArchive::ER_SEEK (int)
シークエラー。
ZipArchive::ER_READ (int)
読み込みエラー。
ZipArchive::ER_WRITE (int)
書き込みエラー。
ZipArchive::ER_CRC (int)
CRC エラー。
ZipArchive::ER_ZIPCLOSED (int)
zip アーカイブはクローズされました。
ZipArchive::ER_NOENT (int)
そのファイルはありません。
ZipArchive::ER_EXISTS (int)
ファイルが既に存在します。
ZipArchive::ER_OPEN (int)
ファイルをオープンできません。
ZipArchive::ER_TMPOPEN (int)
一時ファイルの作成に失敗しました。
ZipArchive::ER_ZLIB (int)
Zlib エラー。
ZipArchive::ER_MEMORY (int)
メモリの確保に失敗しました。
ZipArchive::ER_CHANGED (int)
エントリが変更されました。
ZipArchive::ER_COMPNOTSUPP (int)
圧縮方式がサポートされていません。
ZipArchive::ER_EOF (int)
予期せぬ EOF です。
ZipArchive::ER_INVAL (int)
無効な引数です。
ZipArchive::ER_NOZIP (int)
zip アーカイブではありません。
ZipArchive::ER_INTERNAL (int)
内部エラー。
ZipArchive::ER_INCONS (int)
矛盾した Zip アーカイブです。
ZipArchive::ER_REMOVE (int)
ファイルを削除できません。
ZipArchive::ER_DELETED (int)
エントリが削除されました。
ZipArchive::ER_ENCRNOTSUPP (int)
暗号化メソッドはサポートされていません。 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_RDONLY (int)
読み取り専用のアーカイブです。 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_NOPASSWD (int)
パスワードが指定されていません。 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_WRONGPASSWD (int)
間違ったパスワードが指定されました。 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_OPNOTSUPP (int)
操作はサポートされていません。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_INUSE (int)
リソースがまだ使用中です。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_TELL (int)
ストリームの位置変更エラー。 libzip ? 1.0.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_COMPRESSED_DATA (int)
圧縮データが不正です。 libzip ? 1.6.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_CANCELLED (int)
操作がキャンセルされました。 libzip ? 1.6.0 でビルドした場合、 PHP 7.4.3 以降、PECL zip 1.16.1 以降で利用可能です。
ZipArchive::ER_DATA_LENGTH (int)
データの長さが想定外です。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。 それぞれ、libzip ? 1.10.0 以降でビルドした場合に利用できます。
ZipArchive::ER_NOT_ALLOWED (int)
torrentzip では許可されません。 PHP 8.3.0 以降、PECL zip 1.22.0 以降で利用可能です。 それぞれ、libzip ? 1.10.0 以降でビルドした場合に利用できます。
暗号化モード
ZipArchive::EM_NONE (int)
暗号化しません。libzip ? 1.2.0 でビルドした場合、 PHP 7.2.0 以降、PECL zip 1.14.0 以降で利用可能です。
ZipArchive::EM_TRAD_PKWARE (int)
伝統的な PKWARE 仕様の暗号化を行います。 PHP 8.0.0 以降、PECL zip 1.19.0 以降で利用可能です。
ZipArchive::EM_AES_128 (int)
AES 128 ビットで暗号化します。 libzip ? 1.2.0 でビルドした場合、 PHP 7.2.0 以降、PECL zip 1.14.0 以降で利用可能です。
ZipArchive::EM_AES_192 (int)
AES 192 ビットで暗号化します。 libzip ? 1.2.0 でビルドした場合、 PHP 7.2.0 以降、PECL zip 1.14.0 以降で利用可能です。
ZipArchive::EM_AES_256 (int)
AES 256 ビットで暗号化します。 libzip ? 1.2.0 でビルドした場合、 PHP 7.2.0 以降、PECL zip 1.14.0 以降で利用可能です。
ZipArchive::EM_UNKNOWN (int)
不明な暗号化アルゴリズムです。 PHP 8.0.0 以降、PECL zip 1.19.0 以降で利用可能です。
Length parameter constants
ZipArchive::LENGTH_TO_END (int)
ファイルサイズを使います。 ファイルサイズが増えた場合、追加のデータは無視されます。 ファイルサイズが小さくなった場合、エラー (ZipArchive::ER_DATA_LENGTH) が発生します。 PHP 8.3.0 以降、PECL zip 1.22.2 以降で利用可能です。
ZipArchive::LENGTH_UNCHECKED (int)
利用可能なデータを全て使います。 libzip ? 1.10.1 でビルドした場合、 PHP 8.3.0 以降、PECL zip 1.22.2 以降で利用可能です。
その他の定数
ZipArchive::LIBZIP_VERSION (string)
Zip ライブラリのバージョン。 PHP 7.4.3 以降、PECL zip 1.16.0 以降で利用可能です。
外部属性用の、オペレーティングシステム定数
ZipArchive::OPSYS_DOS (int)
ZipArchive::OPSYS_AMIGA (int)
ZipArchive::OPSYS_OPENVMS (int)
ZipArchive::OPSYS_UNIX (int)
ZipArchive::OPSYS_VM_CMS (int)
ZipArchive::OPSYS_ATARI_ST (int)
ZipArchive::OPSYS_OS_2 (int)
ZipArchive::OPSYS_MACINTOSH (int)
ZipArchive::OPSYS_Z_SYSTEM (int)
ZipArchive::OPSYS_CPM (int)
ZipArchive::OPSYS_WINDOWS_NTFS (int)
ZipArchive::OPSYS_MVS (int)
ZipArchive::OPSYS_VSE (int)
ZipArchive::OPSYS_ACORN_RISC (int)
ZipArchive::OPSYS_VFAT (int)
ZipArchive::OPSYS_ALTERNATE_MVS (int)
ZipArchive::OPSYS_BEOS (int)
ZipArchive::OPSYS_TANDEM (int)
ZipArchive::OPSYS_OS_400 (int)
ZipArchive::OPSYS_OS_X (int)
ZipArchive::OPSYS_DEFAULT (int)
PECL zip 1.12.4 以降で使用可能です。


例

例1 Zip アーカイブの作成

<?php

$zip = new ZipArchive();
$filename = "./test112.zip";

if ($zip->open($filename, ZipArchive::CREATE)!==TRUE) {
exit("cannot open <$filename>\n");
}

$zip->addFromString("testfilephp.txt" . time(), "#1 This is a test string added as testfilephp.txt.\n");
$zip->addFromString("testfilephp2.txt" . time(), "#2 This is a test string added as testfilephp2.txt.\n");
$zip->addFile($thisdir . "/too.php","/testfromfile.php");
echo "numfiles: " . $zip->numFiles . "\n";
echo "status:" . $zip->status . "\n";
$zip->close();
?>

例2 アーカイブの詳細の出力および一覧表示

<?php
$za = new ZipArchive();

$za->open('test_with_comment.zip');
print_r($za);
var_dump($za);
echo "numFiles: " . $za->numFiles . "\n";
echo "status: " . $za->status . "\n";
echo "statusSys: " . $za->statusSys . "\n";
echo "filename: " . $za->filename . "\n";
echo "comment: " . $za->comment . "\n";

for ($i=0; $i<$za->numFiles;$i++) {
echo "index: $i\n";
print_r($za->statIndex($i));
}
echo "numFile:" . $za->numFiles . "\n";
?>

例3 Zip ストリームラッパーによる OpenOffice メタ情報の読み込み

<?php
$reader = new XMLReader();

$reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
$odt_meta = array();
while ($reader->read()) {
if ($reader->nodeType == XMLREADER::ELEMENT) {
$elm = $reader->name;
} else {
if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
break;
}
if (!trim($reader->value)) {
continue;
}
$odt_meta[$elm] = $reader->value;
}
}
print_r($odt_meta);
?>

この例は旧 API (PHP 4 用) を使用します。まず ZIP ファイルアーカイブをオープンし、アーカイブ内の各ファイルを読み込み、 その内容を出力します。この例で使用するアーカイブ test2.zip は、ZZIPlib のソース配布物に含まれているテスト用アーカイブのひとつです。

例4 Zip の使用例

<?php

$zip = zip_open("/tmp/test2.zip");

if ($zip) {
while ($zip_entry = zip_read($zip)) {
echo "Name: " . zip_entry_name($zip_entry) . "\n";
echo "Actual Filesize: " . zip_entry_filesize($zip_entry) . "\n";
echo "Compressed Size: " . zip_entry_compressedsize($zip_entry) . "\n";
echo "Compression Method: " . zip_entry_compressionmethod($zip_entry) . "\n";

if (zip_entry_open($zip, $zip_entry, "r")) {
echo "File Contents:\n";
$buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
echo "$buf\n";

zip_entry_close($zip_entry);
}
echo "\n";

}

zip_close($zip);

}
?>


ZipArchive クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

はじめに

Zip で圧縮されたファイルアーカイブです。

クラス概要

class ZipArchive implements Countable {
/* 定数 */
public const int CREATE;
public const int EXCL;
public const int CHECKCONS;
public const int OVERWRITE;
public const int RDONLY;
public const int FL_NOCASE;
public const int FL_NODIR;
public const int FL_COMPRESSED;
public const int FL_UNCHANGED;
public const int FL_RECOMPRESS;
public const int FL_ENCRYPTED;
public const int FL_OVERWRITE;
public const int FL_LOCAL;
public const int FL_CENTRAL;
public const int FL_ENC_GUESS;
public const int FL_ENC_RAW;
public const int FL_ENC_STRICT;
public const int FL_ENC_UTF_8;
public const int FL_ENC_CP437;
public const int FL_OPEN_FILE_NOW;
public const int CM_DEFAULT;
public const int CM_STORE;
public const int CM_SHRINK;
public const int CM_REDUCE_1;
public const int CM_REDUCE_2;
public const int CM_REDUCE_3;
public const int CM_REDUCE_4;
public const int CM_IMPLODE;
public const int CM_DEFLATE;
public const int CM_DEFLATE64;
public const int CM_PKWARE_IMPLODE;
public const int CM_BZIP2;
public const int CM_LZMA;
public const int CM_LZMA2;
public const int CM_ZSTD;
public const int CM_XZ;
public const int CM_TERSE;
public const int CM_LZ77;
public const int CM_WAVPACK;
public const int CM_PPMD;
public const int ER_OK;
public const int ER_MULTIDISK;
public const int ER_RENAME;
public const int ER_CLOSE;
public const int ER_SEEK;
public const int ER_READ;
public const int ER_WRITE;
public const int ER_CRC;
public const int ER_ZIPCLOSED;
public const int ER_NOENT;
public const int ER_EXISTS;
public const int ER_OPEN;
public const int ER_TMPOPEN;
public const int ER_ZLIB;
public const int ER_MEMORY;
public const int ER_CHANGED;
public const int ER_COMPNOTSUPP;
public const int ER_EOF;
public const int ER_INVAL;
public const int ER_NOZIP;
public const int ER_INTERNAL;
public const int ER_INCONS;
public const int ER_REMOVE;
public const int ER_DELETED;
public const int ER_ENCRNOTSUPP;
public const int ER_RDONLY;
public const int ER_NOPASSWD;
public const int ER_WRONGPASSWD;
public const int ER_OPNOTSUPP;
public const int ER_INUSE;
public const int ER_TELL;
public const int ER_COMPRESSED_DATA;
public const int ER_CANCELLED;
public const int ER_DATA_LENGTH;
public const int ER_NOT_ALLOWED;
public const int AFL_RDONLY;
public const int AFL_IS_TORRENTZIP;
public const int AFL_WANT_TORRENTZIP;
public const int AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE;
public const int OPSYS_DOS;
public const int OPSYS_AMIGA;
public const int OPSYS_OPENVMS;
public const int OPSYS_UNIX;
public const int OPSYS_VM_CMS;
public const int OPSYS_ATARI_ST;
public const int OPSYS_OS_2;
public const int OPSYS_MACINTOSH;
public const int OPSYS_Z_SYSTEM;
public const int OPSYS_CPM;
public const int OPSYS_WINDOWS_NTFS;
public const int OPSYS_MVS;
public const int OPSYS_VSE;
public const int OPSYS_ACORN_RISC;
public const int OPSYS_VFAT;
public const int OPSYS_ALTERNATE_MVS;
public const int OPSYS_BEOS;
public const int OPSYS_TANDEM;
public const int OPSYS_OS_400;
public const int OPSYS_OS_X;
public const int OPSYS_DEFAULT;
public const int EM_NONE;
public const int EM_TRAD_PKWARE;
public const int EM_AES_128;
public const int EM_AES_192;
public const int EM_AES_256;
public const int EM_UNKNOWN;
public const string LIBZIP_VERSION;
public const int LENGTH_TO_END;
public const int LENGTH_UNCHECKED;
/* プロパティ */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* メソッド */
public addEmptyDir(string $dirname, int $flags = 0): bool
public addFile(
string $filepath,
string $entryname = "",
int $start = 0,
int $length = ZipArchive::LENGTH_TO_END,
int $flags = ZipArchive::FL_OVERWRITE
): bool
public addFromString(string $name, string $content, int $flags = ZipArchive::FL_OVERWRITE): bool
public addGlob(string $pattern, int $flags = 0, array $options = []): array|false
public addPattern(string $pattern, string $path = ".", array $options = []): array|false
public clearError(): void
public close(): bool
public count(): int
public deleteIndex(int $index): bool
public deleteName(string $name): bool
public extractTo(string $pathto, array|string|null $files = null): bool
public getArchiveComment(int $flags = 0): string|false
public getArchiveFlag(int $flag, int $flags = 0): int
public getCommentIndex(int $index, int $flags = 0): string|false
public getCommentName(string $name, int $flags = 0): string|false
public getExternalAttributesIndex(
int $index,
int &$opsys,
int &$attr,
int $flags = 0
): bool
public getExternalAttributesName(
string $name,
int &$opsys,
int &$attr,
int $flags = 0
): bool
public getFromIndex(int $index, int $len = 0, int $flags = 0): string|false
public getFromName(string $name, int $len = 0, int $flags = 0): string|false
public getNameIndex(int $index, int $flags = 0): string|false
public getStatusString(): string
public getStream(string $name): resource|false
public getStreamIndex(int $index, int $flags = 0): resource|false
public getStreamName(string $name, int $flags = 0): resource|false
public static isCompressionMethodSupported(int $method, bool $enc = true): bool
public static isEncryptionMethodSupported(int $method, bool $enc = true): bool
public locateName(string $name, int $flags = 0): int|false
public open(string $filename, int $flags = 0): bool|int
public registerCancelCallback(callable $callback): bool
public registerProgressCallback(float $rate, callable $callback): bool
public renameIndex(int $index, string $new_name): bool
public renameName(string $name, string $new_name): bool
public replaceFile(
string $filepath,
int $index,
int $start = 0,
int $length = ZipArchive::LENGTH_TO_END,
int $flags = 0
): bool
public setArchiveComment(string $comment): bool
public setArchiveFlag(int $flag, int $value): bool
public setCommentIndex(int $index, string $comment): bool
public setCommentName(string $name, string $comment): bool
public setCompressionIndex(int $index, int $method, int $compflags = 0): bool
public setCompressionName(string $name, int $method, int $compflags = 0): bool
public setEncryptionIndex(int $index, int $method, #[\SensitiveParameter] ?string $password = null): bool
public setEncryptionName(string $name, int $method, #[\SensitiveParameter] ?string $password = null): bool
public setExternalAttributesIndex(
int $index,
int $opsys,
int $attr,
int $flags = 0
): bool
public setExternalAttributesName(
string $name,
int $opsys,
int $attr,
int $flags = 0
): bool
public setMtimeIndex(int $index, int $timestamp, int $flags = 0): bool
public setMtimeName(string $name, int $timestamp, int $flags = 0): bool
public setPassword(#[\SensitiveParameter] string $password): bool
public statIndex(int $index, int $flags = 0): array|false
public statName(string $name, int $flags = 0): array|false
public unchangeAll(): bool
public unchangeArchive(): bool
public unchangeIndex(int $index): bool
public unchangeName(string $name): bool
}

プロパティ

lastId

最後に追加されたエントリのインデックス(ファイルまたはディレクトリ)。 PHP 8.0.0 以降および PECL 1.18.0 以降で利用可能です。

status

Zip アーカイブの状態。 PHP 8.0.0 以降および PECL 1.18.0 以降では、閉じられたアーカイブでも利用可能です。

statusSys

Zip アーカイブのシステム状態。 PHP 8.0.0 以降および PECL 1.18.0 以降では、閉じられたアーカイブでも利用可能です。

numFiles

アーカイブ内のファイル数

filename

ファイルシステム上のファイル名

comment

アーカイブのコメント

目次

  • ZipArchive::addEmptyDir — 新しいディレクトリを追加する
  • ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する
  • ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する
  • ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する
  • ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する
  • ZipArchive::clearError — ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする
  • ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる
  • ZipArchive::count — アーカイブにあるファイルの数を数える
  • ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する
  • ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する
  • ZipArchive::extractTo — アーカイブの内容を展開する
  • ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す
  • ZipArchive::getArchiveFlag — Zip アーカイブのグローバルフラグの値を返す
  • ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す
  • ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す
  • ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する
  • ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する
  • ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す
  • ZipArchive::getFromName — 名前を使用して、エントリの内容を返す
  • ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す
  • ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す
  • ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する
  • ZipArchive::getStreamIndex — インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
  • ZipArchive::getStreamName — 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
  • ZipArchive::isCompressionMethodSupported — 圧縮方式を libzip がサポートしているかをチェックする
  • ZipArchive::isEncryptionMethodSupported — 暗号化方式を libzip がサポートしているかどうかをチェックする
  • ZipArchive::locateName — アーカイブ内のエントリのインデックスを返す
  • ZipArchive::open — ZIP ファイルアーカイブをオープンする
  • ZipArchive::registerCancelCallback — アーカイブを閉じている間にキャンセルできるようにコールバックを登録する
  • ZipArchive::registerProgressCallback — アーカイブを閉じている間に更新できるようにコールバックを登録する
  • ZipArchive::renameIndex — インデックスを使用してエントリ名を変更する
  • ZipArchive::renameName — 名前を使用してエントリ名を変更する
  • ZipArchive::replaceFile — 指定されたパスのファイルにアーカイブの一部を置き換える
  • ZipArchive::setArchiveComment — ZIP アーカイブのコメントを設定する
  • ZipArchive::setArchiveFlag — Zip アーカイブのグローバルフラグを設定する
  • ZipArchive::setCommentIndex — インデックスを使用してエントリのコメントを設定する
  • ZipArchive::setCommentName — 名前を使用してエントリのコメントを設定する
  • ZipArchive::setCompressionIndex — インデックスで定義されたエントリの圧縮方法を設定する
  • ZipArchive::setCompressionName — 名前で定義されたエントリの圧縮メソッドを設定する
  • ZipArchive::setEncryptionIndex — index で定義されたエントリの暗号化方法を指定する
  • ZipArchive::setEncryptionName — 名前で定義されたエントリの暗号化方式を設定する
  • ZipArchive::setExternalAttributesIndex — インデックスで定義されたエントリの外部属性を設定する
  • ZipArchive::setExternalAttributesName — 名前で定義されたエントリの外部属性を設定する
  • ZipArchive::setMtimeIndex — インデックスを使用してエントリの変更時間を設定する
  • ZipArchive::setMtimeName — 名前を使ってエントリの変更時間を設定する
  • ZipArchive::setPassword — アクティブなアーカイブにパスワードを設定する
  • ZipArchive::statIndex — インデックスを使用してエントリの詳細を取得する
  • ZipArchive::statName — 名前を使用してエントリの詳細を取得する
  • ZipArchive::unchangeAll — アーカイブに対するすべての変更を取り消す
  • ZipArchive::unchangeArchive — アーカイブ全体に対して行われたすべての変更を取り消す
  • ZipArchive::unchangeIndex — 指定したインデックスのエントリに対するすべての変更を取り消す
  • ZipArchive::unchangeName — 指定した名前のエントリに対するすべての変更を取り消す


新しいディレクトリを追加する

  • ≪ ZipArchive
  • ZipArchive::addFile ≫
  • PHP Manual
  • ZipArchive
  • 新しいディレクトリを追加する

ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — 新しいディレクトリを追加する

説明

public ZipArchive::addEmptyDir(string $dirname, int $flags = 0): bool

空のディレクトリをアーカイブに追加します。

パラメータ

dirname

追加するディレクトリ。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | flags が追加されました。

例

例1 アーカイブ内での新規ディレクトリの作成

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
if($zip->addEmptyDir('newDirectory')) {
echo '新しいディレクトリを作成しました';
} else {
echo 'ディレクトリが作成できませんでした';
}
$zip->close();
} else {
echo '失敗しました';
}
?>


指定したパスからファイルを ZIP アーカイブに追加する

  • ≪ ZipArchive::addEmptyDir
  • ZipArchive::addFromString ≫
  • PHP Manual
  • ZipArchive
  • 指定したパスからファイルを ZIP アーカイブに追加する

ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する

説明

public ZipArchive::addFile(
string $filepath,
string $entryname = "",
int $start = 0,
int $length = ZipArchive::LENGTH_TO_END,
int $flags = ZipArchive::FL_OVERWRITE
): bool

指定したパスから、ファイルを ZIP アーカイブに追加します。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

filepath

追加するファイルへのパス。

entryname

空でない値を指定した場合は ZIP アーカイブ内部での名前となり、filepath を上書きします。

start

ファイルを一部コピーする場合の開始位置。

length

ファイルを一部コピーする場合の、コピーする長さ。 ZipArchive::LENGTH_TO_END (0) を指定すると、 ファイルサイズのぶんだけコピーします。 ZipArchive::LENGTH_UNCHECKED を指定すると、 start の位置から)ファイル全体をコピーします。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_OVERWRITE,
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437,
ZipArchive::FL_OPEN_FILE_NOW。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | flags が追加されました。
8.3.0 / 1.22.1 | ZipArchive::FL_OPEN_FILE_NOW が追加されました。
8.3.0 / 1.22.2 | ZipArchive::LENGTH_TO_END と ZipArchive::LENGTH_UNCHECKED が追加されました。

例

この例は、ZIP ファイルアーカイブ test.zip をオープンし、ファイル /path/to/index.txt を newname.txt という名前で追加します。

例1 オープンおよび追加

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->addFile('/path/to/index.txt', 'newname.txt');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>

注意

注意:

アーカイブにファイルを追加するよう設定すると、PHP はそのファイルをロックします。 ロックが解除されるのは、ZipArchive::close() を呼ぶなり ZipArchive オブジェクトを破棄するなりして ZipArchive オブジェクトが閉じられたときだけです。 そのため、追加しようとしているファイルがロックが解除される前に削除されるようなことは起こりません。

参考

  • ZipArchive::replaceFile() - 指定されたパスのファイルにアーカイブの一部を置き換える


内容を指定して、ファイルを ZIP アーカイブに追加する

  • ≪ ZipArchive::addFile
  • ZipArchive::addGlob ≫
  • PHP Manual
  • ZipArchive
  • 内容を指定して、ファイルを ZIP アーカイブに追加する

ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する

説明

public ZipArchive::addFromString(string $name, string $content, int $flags = ZipArchive::FL_OVERWRITE): bool

内容を指定して、ファイルを ZIP アーカイブに追加します。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

name

作成するエントリの名前。

content

エントリを作成するために使用するデータの内容。 バイナリセーフな形式で使用します。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_OVERWRITE,
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | flags が追加されました。

例

例1 新しいアーカイブへのエントリの追加

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('test.txt', 'ここにファイルの内容を書きます');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>

例2 アーカイブ内のディレクトリへのファイルの追加

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->addFromString('dir/test.txt', 'ここにファイルの内容を書きます');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>


ディレクトリから、glob パターンを使ってファイルを追加する

  • ≪ ZipArchive::addFromString
  • ZipArchive::addPattern ≫
  • PHP Manual
  • ZipArchive
  • ディレクトリから、glob パターンを使ってファイルを追加する

ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する

説明

public ZipArchive::addGlob(string $pattern, int $flags = 0, array $options = []): array|false

ディレクトリから、glob pattern にマッチするファイルを追加します。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

pattern

glob() パターン。どのファイルを対象にするのかを指定します。

flags

glob() のフラグのビットマスク。

options

オプションの連想配列。次のオプションが使えます。

  • "add_path"

    アーカイブ内のファイルのローカルパスに変換するときにつけるプレフィックス。 これが適用されるのは、 "remove_path" や "remove_all_path" で定義された削除処理がすべて終わった後です。

  • "remove_path"

    マッチしたファイルをアーカイブに追加する前に削除するプレフィックス。

  • "remove_all_path"

    true にすると、ファイル名だけを使ってアーカイブのルートに追加します。

  • "flags"

    以下のビットマスクの組み合わせ:
ZipArchive::FL_OVERWRITE,
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437,
ZipArchive::FL_OPEN_FILE_NOW。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

  • "comp_method"

    圧縮メソッド。 ZipArchive::CM_* のうちのいずれかです。 定義済みの定数 も参照ください。

  • "comp_flags"

    圧縮レベル

  • "enc_method"

    暗号化メソッド。 ZipArchive::EM_* のうちのいずれかです。 定義済みの定数 も参照ください。

  • "enc_password"

    暗号化に使うパスワード

戻り値

成功した場合、追加されたファイルの array を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | options に "flags" が追加されました。
8.0.0 / 1.18.1 | options に "comp_method", "comp_flags", "enc_method", "enc_password" が追加されました。
8.3.0 / 1.22.1 | ZipArchive::FL_OPEN_FILE_NOW が追加されました。

例

例1 ZipArchive::addGlob() の例

現在の作業ディレクトリにある、すべての PHP スクリプトとテキストファイルを追加します。

<?php
$zip = new ZipArchive();
$ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($ret !== TRUE) {
printf('Failed with code %d', $ret);
} else {
$options = array('add_path' => 'sources/', 'remove_all_path' => TRUE);
$zip->addGlob('*.{php,txt}', GLOB_BRACE, $options);
$zip->close();
}
?>

参考

  • ZipArchive::addFile() - 指定したパスからファイルを ZIP アーカイブに追加する
  • ZipArchive::addPattern() - ディレクトリから、PCRE パターンを使ってファイルを追加する


ディレクトリから、PCRE パターンを使ってファイルを追加する

  • ≪ ZipArchive::addGlob
  • ZipArchive::clearError ≫
  • PHP Manual
  • ZipArchive
  • ディレクトリから、PCRE パターンを使ってファイルを追加する

ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する

説明

public ZipArchive::addPattern(string $pattern, string $path = ".", array $options = []): array|false

ディレクトリから、正規表現の pattern にマッチするファイルを追加します。 この操作は再帰処理ではありません。パターンマッチは、ファイル名に対してだけ行います。

パラメータ

pattern

PCRE のパターン。どのファイルを対象にするのかを指定します。

path

スキャンするディレクトリ。デフォルトは、現在の作業ディレクトリです。

options

オプションの連想配列。ZipArchive::addGlob() と同じオプションが使えます。

戻り値

成功した場合、追加されたファイルの array を返します。 失敗した場合に false を返します

例

例1 ZipArchive::addPattern() の例

現在の作業ディレクトリにある、すべての PHP スクリプトとテキストファイルを追加します。

<?php
$zip = new ZipArchive();
$ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($ret !== TRUE) {
printf('Failed with code %d', $ret);
} else {
$directory = realpath('.');
$options = array('add_path' => 'sources/', 'remove_path' => $directory);
$zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
$zip->close();
}
?>

参考

  • ZipArchive::addFile() - 指定したパスからファイルを ZIP アーカイブに追加する
  • ZipArchive::addGlob() - ディレクトリから、glob パターンを使ってファイルを追加する


ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする

  • ≪ ZipArchive::addPattern
  • ZipArchive::close ≫
  • PHP Manual
  • ZipArchive
  • ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする

ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする

説明

public ZipArchive::clearError(): void

アーカイブのステータスエラーメッセージか、 システムエラー かつ/または zip メッセージをクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • ZipArchive::getStatusString() - システムエラー、または ZIP メッセージに関するエラー情報を返す


アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

  • ≪ ZipArchive::clearError
  • ZipArchive::count ≫
  • PHP Manual
  • ZipArchive
  • アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

説明

public ZipArchive::close(): bool

オープンされた、あるいは作成されたアーカイブを閉じ、 変更内容を保存します。このメソッドは、 スクリプトの最後で自動的にコールされます。

アーカイブにファイルが含まれていない場合、 グローバルフラグ ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE に従って、 デフォルトではファイルは完全に削除されます。 (空のアーカイブが作られることはありません)

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ZipArchive::setArchiveFlag() - Zip アーカイブのグローバルフラグを設定する


アーカイブにあるファイルの数を数える

  • ≪ ZipArchive::close
  • ZipArchive::deleteIndex ≫
  • PHP Manual
  • ZipArchive
  • アーカイブにあるファイルの数を数える

ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — アーカイブにあるファイルの数を数える

説明

public ZipArchive::count(): int

パラメータ

この関数にはパラメータはありません。

戻り値

アーカイブにあるファイルの数を返します。


インデックスを使用して、アーカイブ内のエントリを削除する

  • ≪ ZipArchive::count
  • ZipArchive::deleteName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用して、アーカイブ内のエントリを削除する

ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する

説明

public ZipArchive::deleteIndex(int $index): bool

インデックスをもとにして、アーカイブ内のエントリを削除します。

パラメータ

index

削除するエントリのインデックス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 インデックスを使用した、アーカイブからのファイルの削除

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->deleteIndex(2);
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>


名前を使用して、アーカイブからエントリを削除する

  • ≪ ZipArchive::deleteIndex
  • ZipArchive::extractTo ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用して、アーカイブからエントリを削除する

ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する

説明

public ZipArchive::deleteName(string $name): bool

名前をもとにして、アーカイブ内のエントリを削除します。

パラメータ

name

削除するエントリの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 名前を使用した、アーカイブからのファイルやディレクトリの削除

<?php
$zip = new ZipArchive;
if ($zip->open('test1.zip') === TRUE) {
$zip->deleteName('testfromfile.php');
$zip->deleteName('testDir/');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>


アーカイブの内容を展開する

  • ≪ ZipArchive::deleteName
  • ZipArchive::getArchiveComment ≫
  • PHP Manual
  • ZipArchive
  • アーカイブの内容を展開する

ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — アーカイブの内容を展開する

説明

public ZipArchive::extractTo(string $pathto, array|string|null $files = null): bool

アーカイブの全体あるいは指定したファイルを、 指定した場所に展開します。

警告

展開されたファイルとディレクトリのデフォルトのパーミッションは、 可能な限りもっとも広いアクセス権限になります。 これは umask() 関数で変更できる umask で制限できます。

セキュリティ上の理由で、パーミッションは復元されません。 パーミッションを復元するコードのサンプルは、 ZipArchive::getExternalAttributesIndex() の コードサンプル を参照ください。

パラメータ

pathto

ファイルを展開する場所。

files

展開するエントリ。単一のエントリ名、 あるいはエントリ名の配列を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 全エントリの展開

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->extractTo('/my/destination/dir/');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>

例2 二つのエントリの展開

<?php
$zip = new ZipArchive;
$res = $zip->open('test_im.zip');
if ($res === TRUE) {
$zip->extractTo('/my/destination/dir/', array('pear_item.gif', 'testfromfile.php'));
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>

注意

注意:

Windows の NTFS ファイルシステムには、ファイル名で使う場合にサポートしていない文字があります。具体的には、<|>*?": です。末尾にドットがあるファイル名もサポートしていません。いくつかの展開ツールと異なり、このメソッドはこれらの文字をアンダースコアで置き換えませんし、そのようなファイルを展開すると失敗します。


ZIP アーカイブのコメントを返す

  • ≪ ZipArchive::extractTo
  • ZipArchive::getArchiveFlag ≫
  • PHP Manual
  • ZipArchive
  • ZIP アーカイブのコメントを返す

ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す

説明

public ZipArchive::getArchiveComment(int $flags = 0): string|false

Zip アーカイブのコメントを返します。

パラメータ

flags

ZipArchive::FL_UNCHANGED を設定すると、 元の変更されていないコメントを返します。

戻り値

Zip アーカイブのコメントを返します。失敗した場合に false を返します。

例

例1 アーカイブのコメントの出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test_with_comment.zip');
if ($res === TRUE) {
var_dump($zip->getArchiveComment());
/* あるいはアーカイブのプロパティを使用します */
var_dump($zip->comment);
} else {
echo '失敗、コード:' . $res;
}
?>


Zip アーカイブのグローバルフラグの値を返す

  • ≪ ZipArchive::getArchiveComment
  • ZipArchive::getCommentIndex ≫
  • PHP Manual
  • ZipArchive
  • Zip アーカイブのグローバルフラグの値を返す

ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Zip アーカイブのグローバルフラグの値を返す

説明

public ZipArchive::getArchiveFlag(int $flag, int $flags = 0): int

Zip アーカイブのグローバルフラグの値を返します。

パラメータ

flag

取得するグローバルフラグ。 以下の定数 AFL_* から選びます:

  • ZipArchive::AFL_RDONLY

  • ZipArchive::AFL_IS_TORRENTZIP

  • ZipArchive::AFL_WANT_TORRENTZIP

  • ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE

flags

ZipArchive::FL_UNCHANGED が設定された場合、 もともと設定されていた値が返されます。

戻り値

アーカイブにフラグが設定されている場合は、1 を返します。 設定されていない場合は 0 を返します。 エラーが発生した場合は -1 を返します。

例

例1 アーカイブが torrentzip フォーマットかを調べる

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
var_dump($zip->getArchiveFlag(ZipArchive::AFL_IS_TORRENTZIP));
} else {
echo 'failed, code:' . $res;
}
?>

参考

  • ZipArchive::setArchiveFlag() - Zip アーカイブのグローバルフラグを設定する


エントリのインデックスを使用して、エントリのコメントを返す

  • ≪ ZipArchive::getArchiveFlag
  • ZipArchive::getCommentName ≫
  • PHP Manual
  • ZipArchive
  • エントリのインデックスを使用して、エントリのコメントを返す

ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す

説明

public ZipArchive::getCommentIndex(int $index, int $flags = 0): string|false

エントリのインデックスを使用して、エントリのコメントを返します。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED を指定すると、 元の変化していないコメントを返します。

戻り値

成功した場合にコメント、失敗した場合に false を返します。

例

例1 エントリのコメントの出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test1.zip');
if ($res === TRUE) {
var_dump($zip->getCommentIndex(1));
} else {
echo '失敗、コード:' . $res;
}
?>


エントリ名を使用して、エントリのコメントを返す

  • ≪ ZipArchive::getCommentIndex
  • ZipArchive::getExternalAttributesIndex ≫
  • PHP Manual
  • ZipArchive
  • エントリ名を使用して、エントリのコメントを返す

ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す

説明

public ZipArchive::getCommentName(string $name, int $flags = 0): string|false

エントリ名を使用して、エントリのコメントを返します。

パラメータ

name

エントリの名前。

flags

ZipArchive::FL_UNCHANGED を指定すると、 元の変化していないコメントが返されます。

戻り値

成功した場合にコメント、失敗した場合に false を返します。

例

例1 エントリのコメントの出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test1.zip');
if ($res === TRUE) {
var_dump($zip->getCommentName('test/entry1.txt'));
} else {
echo '失敗、コード:' . $res;
}
?>


インデックスで定義されたエントリの外部属性を取得する

  • ≪ ZipArchive::getCommentName
  • ZipArchive::getExternalAttributesName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで定義されたエントリの外部属性を取得する

ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する

説明

public ZipArchive::getExternalAttributesIndex(
int $index,
int &$opsys,
int &$attr,
int $flags = 0
): bool

インデックスで定義されたエントリの外部属性を取得します。

パラメータ

index

エントリのインデックス

opsys

成功した場合に、 ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコードを取得します。

attr

成功した場合に、外部属性を取得します。 値はオペレーティングシステム依存です。

flags

ZipArchive::FL_UNCHANGED に設定された場合、 オリジナルの変更されなかった属性が返されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、ZIP アーカイブ test.zip の 全エントリを展開し、外部属性から Unixの権限を設定しています。

例1 全てのエントリをUnixの権限付きで展開する

<?php
$zip = new ZipArchive();
if ($zip->open('test.zip') === TRUE) {
for ($idx=0 ; $s = $zip->statIndex($idx) ; $idx++) {
if ($zip->extractTo('.', $s['name'])) {
if ($zip->getExternalAttributesIndex($idx, $opsys, $attr)
&& $opsys==ZipArchive::OPSYS_UNIX) {
chmod($s['name'], ($attr >> 16) & 0777);
}
}
}
$zip->close();
echo "Ok\n";
} else {
echo "KO\n";
}
?>


名前で定義されたエントリの外部属性を取得する

  • ≪ ZipArchive::getExternalAttributesIndex
  • ZipArchive::getFromIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの外部属性を取得する

ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する

説明

public ZipArchive::getExternalAttributesName(
string $name,
int &$opsys,
int &$attr,
int $flags = 0
): bool

名前で定義されたエントリの外部属性を取得します。

パラメータ

name

エントリの名前

opsys

成功した場合に、 ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコードを取得します。

attr

成功した場合に、外部属性を取得します。 値はオペレーティングシステム依存です。

flags

ZipArchive::FL_UNCHANGED に設定された場合、 オリジナルの変更されなかった属性が返されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。


インデックスを使用して、エントリの内容を返す

  • ≪ ZipArchive::getExternalAttributesName
  • ZipArchive::getFromName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用して、エントリの内容を返す

ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す

説明

public ZipArchive::getFromIndex(int $index, int $len = 0, int $flags = 0): string|false

インデックスを使用して、エントリの内容を返します。

パラメータ

index

エントリのインデックス。

len

エントリから読み込む長さ。0 の場合はエントリ全体を読み込みます。

flags

アーカイブのオープン時に使用するフラグ。以下の値を OR で連結して使用します。

  • ZipArchive::FL_UNCHANGED

  • ZipArchive::FL_COMPRESSED

戻り値

成功した場合にエントリの内容、失敗した場合に false を返します。

例

例1 ファイルの内容の取得

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
echo $zip->getFromIndex(2);
$zip->close();
} else {
echo '失敗';
}
?>

参考

  • ZipArchive::getFromName() - 名前を使用して、エントリの内容を返す


名前を使用して、エントリの内容を返す

  • ≪ ZipArchive::getFromIndex
  • ZipArchive::getNameIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用して、エントリの内容を返す

ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — 名前を使用して、エントリの内容を返す

説明

public ZipArchive::getFromName(string $name, int $len = 0, int $flags = 0): string|false

名前を使用して、エントリの内容を返します。

パラメータ

name

エントリの名前。

len

エントリから読み込む長さ。0 の場合はエントリ全体を読み込みます。

flags

エントリを探す際に使用するフラグ。以下の値を OR で連結して使用します。

  • ZipArchive::FL_UNCHANGED

  • ZipArchive::FL_COMPRESSED

  • ZipArchive::FL_NOCASE

戻り値

成功した場合にエントリの内容、失敗した場合に false を返します。

例

例1 ファイルの内容の取得

<?php
$zip = new ZipArchive;
if ($zip->open('test1.zip') === TRUE) {
echo $zip->getFromName('testfromfile.php');
$zip->close();
} else {
echo '失敗';
}
?>

例2 zip エントリの画像への変換

<?php
$z = new ZipArchive();
if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
$im_string = $z->getFromName("pear_item.gif");
$im = imagecreatefromstring($im_string);
imagepng($im, 'b.png');
}
?>

参考

  • ZipArchive::getFromIndex() - インデックスを使用して、エントリの内容を返す


インデックスを使用して、エントリの名前を返す

  • ≪ ZipArchive::getFromName
  • ZipArchive::getStatusString ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用して、エントリの名前を返す

ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す

説明

public ZipArchive::getNameIndex(int $index, int $flags = 0): string|false

インデックスを使用して、エントリの名前を返します。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED を指定すると、 元の変化していないコメントを返します。

戻り値

成功した場合に名前、失敗した場合に false を返します。

例

例1 ZipArchive::getNameIndex() の例

<?php
if ($zip->open('test.zip') == TRUE) {
for ($i = 0; $i < $zip->numFiles; $i++) {
$filename = $zip->getNameIndex($i);
// ...
}
}
?>


システムエラー、または ZIP メッセージに関するエラー情報を返す

  • ≪ ZipArchive::getNameIndex
  • ZipArchive::getStream ≫
  • PHP Manual
  • ZipArchive
  • システムエラー、または ZIP メッセージに関するエラー情報を返す

ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す

説明

public ZipArchive::getStatusString(): string

システムエラー、または ZIP メッセージに関するエラー情報を返す

パラメータ

この関数にはパラメータはありません。

戻り値

成功時にはステータスメッセージを文字列で返します。

変更履歴

バージョン | 説明
8.0.0 / 1.18.0 | このメソッドは、閉じられたアーカイブに対しても呼び出せるようになりました。
8.0.0 / 1.18.0 | このメソッドは、失敗時に false を返さなくなりました。


名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

  • ≪ ZipArchive::getStatusString
  • ZipArchive::getStreamIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

説明

public ZipArchive::getStream(string $name): resource|false

名前を使用して、エントリのファイルハンドラを取得します。 現時点では読み込み操作のみに対応しています。

パラメータ

name

使用するエントリの名前。

戻り値

成功した場合にファイルポインタ (リソース)、 失敗した場合に false を返します。

例

例1 エントリの内容を fread() で取得し、それを保存する

<?php
$contents = '';
$z = new ZipArchive();
if ($z->open('test.zip')) {
$fp = $z->getStream('test');
if(!$fp) exit("失敗\n");

while (!feof($fp)) {
$contents .= fread($fp, 2);
}

fclose($fp);
file_put_contents('t',$contents);
echo "終了\n";
}
?>

例2 先ほどの例と同じことを、fopen() および zip ストリームラッパーで行う

<?php
$contents = '';
$fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
if (!$fp) {
exit("オープンできません\n");
}
while (!feof($fp)) {
$contents .= fread($fp, 2);
}
echo "$contents\n";
fclose($fp);
echo "done.\n";
?>

例3 ストリームラッパーと画像の組み合わせ。xml 関数とでも使用可能

<?php
$im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
imagepng($im, 'a.png');
?>

参考

  • ZipArchive::getStreamIndex() - インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
  • ZipArchive::getStreamName() - 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
  • 圧縮ストリーム


インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

  • ≪ ZipArchive::getStream
  • ZipArchive::getStreamName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

説明

public ZipArchive::getStreamIndex(int $index, int $flags = 0): resource|false

インデックスで指定されたエントリへの、 ファイルハンドラを取得します。 現状では、読み取りのみをサポートしています。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED に設定すると、オリジナルの未変更のストリームを返します。

戻り値

成功時に、ファイルポインタ(リソース) を返します。 失敗した場合に false を返します.

例

例1 fread() でエントリの内容を取得し、保存する

<?php
$contents = '';
$z = new ZipArchive();
if ($z->open('test.zip')) {
$fp = $z->getStreamIndex(1, ZipArchive::FL_UNCHANGED);
if(!$fp) die($z->getStatusString());

echo stream_get_contents($fp);

fclose($fp);
}
?>

参考

  • ZipArchive::getStreamName() - 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)


名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

  • ≪ ZipArchive::getStreamIndex
  • ZipArchive::isCompressionMethodSupported ≫
  • PHP Manual
  • ZipArchive
  • 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

説明

public ZipArchive::getStreamName(string $name, int $flags = 0): resource|false

インデックスで指定されたエントリへの、 ファイルハンドラを取得します。 現状では、読み取り操作のみをサポートしています。

パラメータ

name

エントリの名前。

flags

ZipArchive::FL_UNCHANGED に設定すると、オリジナルの未変更のストリームを返します。

戻り値

成功時に、ファイルポインタ(リソース) を返します。 失敗した場合に false を返します.

例

例1 fread() でエントリの内容を取得し、保存する

<?php
$contents = '';
$z = new ZipArchive();
if ($z->open('test.zip')) {
$fp = $z->getStreamName('test', ZipArchive::FL_UNCHANGED);
if(!$fp) die($z->getStatusString());

echo stream_get_contents($fp);

fclose($fp);
}
?>

参考

  • ZipArchive::getStreamIndex() - インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)


圧縮方式を libzip がサポートしているかをチェックする

  • ≪ ZipArchive::getStreamName
  • ZipArchive::isEncryptionMethodSupported ≫
  • PHP Manual
  • ZipArchive
  • 圧縮方式を libzip がサポートしているかをチェックする

ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — 圧縮方式を libzip がサポートしているかをチェックする

説明

public static ZipArchive::isCompressionMethodSupported(int $method, bool $enc = true): bool

圧縮方式を libzip がサポートしているかをチェックします。

パラメータ

method

圧縮方式。 定数 ZipArchive::CM_* のうちのいずれかです。

enc

true を設定すると圧縮方式をチェックします。 false を設定すると伸長方式をチェックします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.7.0 を使ってPHPをビルドした場合にのみ利用可能です。

参考

  • ZipArchive::setCompressionIndex() - インデックスで定義されたエントリの圧縮方法を設定する
  • ZipArchive::setCompressionName() - 名前で定義されたエントリの圧縮メソッドを設定する


暗号化方式を libzip がサポートしているかどうかをチェックする

  • ≪ ZipArchive::isCompressionMethodSupported
  • ZipArchive::locateName ≫
  • PHP Manual
  • ZipArchive
  • 暗号化方式を libzip がサポートしているかどうかをチェックする

ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — 暗号化方式を libzip がサポートしているかどうかをチェックする

説明

public static ZipArchive::isEncryptionMethodSupported(int $method, bool $enc = true): bool

暗号化方式を libzip がサポートしているかどうかをチェックします

パラメータ

method

暗号化方式。 定数 ZipArchive::EM_* のうちのいずれかです。

enc

true を設定すると、暗号化方式をチェックし、 false を設定すると、復号化方式をチェックします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、libzip ? 1.7.0 を使ってPHPをビルドした場合にのみ利用可能です。

参考

  • ZipArchive::setEncryptionIndex() - index で定義されたエントリの暗号化方法を指定する
  • ZipArchive::setEncryptionName() - 名前で定義されたエントリの暗号化方式を設定する


アーカイブ内のエントリのインデックスを返す

  • ≪ ZipArchive::isEncryptionMethodSupported
  • ZipArchive::open ≫
  • PHP Manual
  • ZipArchive
  • アーカイブ内のエントリのインデックスを返す

ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — アーカイブ内のエントリのインデックスを返す

説明

public ZipArchive::locateName(string $name, int $flags = 0): int|false

名前を使用して、エントリの場所を取得します。

パラメータ

name

探したいエントリの名前。

flags

この関数は、アーカイブ内の指定した名前のファイルのインデックスを返します。 フラグには、次の値を OR で連結して指定します。 あるいは何もしていしない場合は 0 とします。

  • ZipArchive::FL_NOCASE

  • ZipArchive::FL_NODIR

戻り値

成功した場合にエントリのインデックス、失敗した場合に false を返します。

例

例1 アーカイブを作成し、ZipArchive::locateName() を使用する

<?php
$file = 'testlocate.zip';

$zip = new ZipArchive;
if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
exit('失敗');
}

$zip->addFromString('entry1.txt', 'entry #1');
$zip->addFromString('entry2.txt', 'entry #2');
$zip->addFromString('dir/entry2d.txt', 'entry #2');

if ($zip->status !== ZipArchive::ER_OK) {
echo "zip の書き込みに失敗\n";
}
$zip->close();

if ($zip->open($file) !== TRUE) {
exit('失敗');
}

echo $zip->locateName('entry1.txt') . "\n";
echo $zip->locateName('eNtry2.txt') . "\n";
echo $zip->locateName('eNtry2.txt', ZipArchive::FL_NOCASE) . "\n";
echo $zip->locateName('enTRy2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
$zip->close();

?>

上の例の出力は以下となります。

0

1
2


ZIP ファイルアーカイブをオープンする

  • ≪ ZipArchive::locateName
  • ZipArchive::registerCancelCallback ≫
  • PHP Manual
  • ZipArchive
  • ZIP ファイルアーカイブをオープンする

ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — ZIP ファイルアーカイブをオープンする

説明

public ZipArchive::open(string $filename, int $flags = 0): bool|int

新しい、または既に存在する zip アーカイブを 読み込み/書き込み/変更用にオープンします。

libzip 1.6.0 以降では、空のファイルは有効なアーカイブではなくなりました。

パラメータ

filename

オープンする ZIP アーカイブのファイル名。

flags

アーカイブのオープンに使用するモード。

  • ZipArchive::OVERWRITE

  • ZipArchive::CREATE

  • ZipArchive::RDONLY

  • ZipArchive::EXCL

  • ZipArchive::CHECKCONS

戻り値

成功した場合に true、失敗した場合は false を返し、 エラー時には以下のエラーコードを返します。

ZipArchive::ER_EXISTS
ファイルが既に存在します。
ZipArchive::ER_INCONS
Zipアーカイブに不整合があります。
ZipArchive::ER_INVAL
不正な引数です。
ZipArchive::ER_MEMORY
メモリ確保に失敗しました。
ZipArchive::ER_NOENT
ファイルが存在しません。
ZipArchive::ER_NOZIP
zip アーカイブではありません。
ZipArchive::ER_OPEN
ファイルを開けません。
ZipArchive::ER_READ
読み取りエラーです。
ZipArchive::ER_SEEK
シークエラーです。

例

例1 オープンおよび展開

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
echo '成功';
$zip->extractTo('test');
$zip->close();
} else {
echo '失敗、コード:' . $res;
}
?>

例2 アーカイブの作成

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('test.txt', 'ここにファイルの内容を書きます');
$zip->addFile('data.txt', 'entryname.txt');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>

例3 一時的なアーカイブの作成

<?php
$name = tempnam(sys_get_temp_dir(), "FOO");
$zip = new ZipArchive;
$res = $zip->open($name, ZipArchive::OVERWRITE); /* 空のファイルに切り詰めても無効です */
if ($res === TRUE) {
$zip->addFile('data.txt', 'entryname.txt');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>


アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

  • ≪ ZipArchive::open
  • ZipArchive::registerProgressCallback ≫
  • PHP Manual
  • ZipArchive
  • アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

説明

public ZipArchive::registerCancelCallback(callable $callback): bool

アーカイブを閉じている間にキャンセルできるように callback 関数を登録します。

パラメータ

callback

この関数が0を返すと、操作は続行されます。 それ以外の値を返すと、操作はキャンセルされます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、php.zip というZIPファイルを生成し、 ある実行時の条件に応じて操作をキャンセルします。

例1 ファイルをアーカイブする

<?php
$zip = new ZipArchive();
if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
$zip->addFile(PHP_BINARY, 'php');
$zip->registerCancelCallback(function () {
return ($someruncondition ? -1 : 0);
});
$zip->close();
}

注意

注意:

この関数は、libzip ? 1.6.0 と PHP をビルドした場合のみ利用できます。

参考

  • ZipArchive::registerProgressCallback() - アーカイブを閉じている間に更新できるようにコールバックを登録する


アーカイブを閉じている間に更新できるようにコールバックを登録する

  • ≪ ZipArchive::registerCancelCallback
  • ZipArchive::renameIndex ≫
  • PHP Manual
  • ZipArchive
  • アーカイブを閉じている間に更新できるようにコールバックを登録する

ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — アーカイブを閉じている間に更新できるようにコールバックを登録する

説明

public ZipArchive::registerProgressCallback(float $rate, callable $callback): bool

アーカイブを閉じている間に更新できるように callback 関数を登録します。

パラメータ

rate

コールバックを呼び出す間の変更の割合(0.0 から 1.0 の間の値を設定します)

callback

この関数は現在の state (状態) を (0.0 から 1.0 の間の) float で受け取ります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、php.zip というZIPファイルを生成し、 進捗状況を表示します。

例1 ファイルをアーカイブする

$zip = new ZipArchive();
if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
$zip->addFile(PHP_BINARY, 'php');
$zip->registerProgressCallback(0.05, function ($r) {
printf("%d%%\n", $r * 100);
});
$zip->close();
}

注意

注意:

この関数は、libzip ? 1.3.0 と PHP をビルドした場合のみ利用できます。

参考

  • ZipArchive::registerCancelCallback() - アーカイブを閉じている間にキャンセルできるようにコールバックを登録する


インデックスを使用してエントリ名を変更する

  • ≪ ZipArchive::registerProgressCallback
  • ZipArchive::renameName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリ名を変更する

ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — インデックスを使用してエントリ名を変更する

説明

public ZipArchive::renameIndex(int $index, string $new_name): bool

インデックスを使用して、エントリ名を変更します。

パラメータ

index

名前を変更するエントリのインデックス。

new_name

新しい名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 エントリ名の変更

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->renameIndex(2,'newname.txt');
$zip->close();
} else {
echo '失敗、コード:' . $res;
}
?>


名前を使用してエントリ名を変更する

  • ≪ ZipArchive::renameIndex
  • ZipArchive::replaceFile ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用してエントリ名を変更する

ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — 名前を使用してエントリ名を変更する

説明

public ZipArchive::renameName(string $name, string $new_name): bool

名前を使用して、エントリ名を変更します。

パラメータ

name

名前を変更するエントリの名前。

new_name

新しい名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 エントリ名の変更

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->renameName('currentname.txt','newname.txt');
$zip->close();
} else {
echo '失敗、コード:' . $res;
}
?>


指定されたパスのファイルにアーカイブの一部を置き換える

  • ≪ ZipArchive::renameName
  • ZipArchive::setArchiveComment ≫
  • PHP Manual
  • ZipArchive
  • 指定されたパスのファイルにアーカイブの一部を置き換える

ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — 指定されたパスのファイルにアーカイブの一部を置き換える

説明

public ZipArchive::replaceFile(
string $filepath,
int $index,
int $start = 0,
int $length = ZipArchive::LENGTH_TO_END,
int $flags = 0
): bool

指定されたパスのファイルにアーカイブの一部を置き換えます。

注意: ポータビリティを考慮して、ZIP ファイル名のディレクトリ区切り文字には常にスラッシュ (/) を使うことを推奨します。

パラメータ

filepath

追加するファイルのパス。

index

置き換えるファイルのインデックス。名前は変更されません。

start

ファイルを一部コピーする場合の開始位置。

length

ファイルを一部コピーする場合の、コピーする長さ。 ZipArchive::LENGTH_TO_END (0) を指定すると、 ファイルサイズのぶんだけコピーします。 ZipArchive::LENGTH_UNCHECKED を指定すると、 start の位置から)ファイル全体をコピーします。

flags

以下のビットマスクの組み合わせ:
ZipArchive::FL_ENC_GUESS,
ZipArchive::FL_ENC_UTF_8,
ZipArchive::FL_ENC_CP437,
ZipArchive::FL_OPEN_FILE_NOW。
これらの定数の振る舞いは、定義済みの定数 で説明しています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 / 1.22.1 | ZipArchive::FL_OPEN_FILE_NOW が追加されました。
8.3.0 / 1.22.2 | ZipArchive::LENGTH_TO_END と ZipArchive::LENGTH_UNCHECKED が追加されました。

例

この例は、ZIP ファイルアーカイブ test.zip をオープンし、インデックス1 のエントリを /path/to/index.txt に置き換えます。

例1 オープンおよび追加

<?php
$zip = new ZipArchive;
if ($zip->open('test.zip') === TRUE) {
$zip->replaceFile('/path/to/index.txt', 1);
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>

参考

  • ZipArchive::addFile() - 指定したパスからファイルを ZIP アーカイブに追加する


ZIP アーカイブのコメントを設定する

  • ≪ ZipArchive::replaceFile
  • ZipArchive::setArchiveFlag ≫
  • PHP Manual
  • ZipArchive
  • ZIP アーカイブのコメントを設定する

ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — ZIP アーカイブのコメントを設定する

説明

public ZipArchive::setArchiveComment(string $comment): bool

ZIP アーカイブのコメントを設定します。

パラメータ

comment

コメントの内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブの作成およびコメントの設定

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('test.txt', 'ここにファイルの内容を書きます');
$zip->setArchiveComment('新しいアーカイブのコメント');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>


Zip アーカイブのグローバルフラグを設定する

  • ≪ ZipArchive::setArchiveComment
  • ZipArchive::setCommentIndex ≫
  • PHP Manual
  • ZipArchive
  • Zip アーカイブのグローバルフラグを設定する

ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Zip アーカイブのグローバルフラグを設定する

説明

public ZipArchive::setArchiveFlag(int $flag, int $value): bool

ZIP アーカイブのグローバルフラグを設定します。

パラメータ

flag

変更するグローバルフラグ。 定数 AFL_* から選びます。

  • ZipArchive::AFL_WANT_TORRENTZIP

  • ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE

value

フラグの新しい値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 torrentzip アーカイブを作成する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->setArchiveFlag(ZipArchive::AFL_WANT_TORRENTZIP, 1);
$zip->addFromString('test.txt', 'file content goes here');
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>

参考

  • ZipArchive::getArchiveFlag() - Zip アーカイブのグローバルフラグの値を返す


インデックスを使用してエントリのコメントを設定する

  • ≪ ZipArchive::setArchiveFlag
  • ZipArchive::setCommentName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリのコメントを設定する

ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — インデックスを使用してエントリのコメントを設定する

説明

public ZipArchive::setCommentIndex(int $index, string $comment): bool

インデックスを使用して、エントリのコメントを設定します。

パラメータ

index

エントリのインデックス。

comment

コメントの内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブをオープンし、エントリのコメントを設定する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->setCommentIndex(2, '新しいエントリのコメント');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>


名前を使用してエントリのコメントを設定する

  • ≪ ZipArchive::setCommentIndex
  • ZipArchive::setCompressionIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用してエントリのコメントを設定する

ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — 名前を使用してエントリのコメントを設定する

説明

public ZipArchive::setCommentName(string $name, string $comment): bool

名前を使用して、エントリのコメントを設定します。

パラメータ

name

エントリの名前。

comment

コメントの内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブをオープンし、エントリのコメントを設定する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
$zip->setCommentName('entry1.txt', '新しいエントリのコメント');
$zip->close();
echo '成功';
} else {
echo '失敗';
}
?>


インデックスで定義されたエントリの圧縮方法を設定する

  • ≪ ZipArchive::setCommentName
  • ZipArchive::setCompressionName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで定義されたエントリの圧縮方法を設定する

ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — インデックスで定義されたエントリの圧縮方法を設定する

説明

public ZipArchive::setCompressionIndex(int $index, int $method, int $compflags = 0): bool

インデックスで定義されたエントリの圧縮方法を設定します。

パラメータ

index

エントリのインデックス

method

圧縮メソッド。 ZipArchive::CM_* のいずれかです。

compflags

圧縮レベル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブに異なる圧縮メソッドでファイルを追加する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('foo', 'Some text');
$zip->addFromString('bar', 'Some other text');
$zip->setCompressionIndex(0, ZipArchive::CM_STORE);
$zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>


名前で定義されたエントリの圧縮メソッドを設定する

  • ≪ ZipArchive::setCompressionIndex
  • ZipArchive::setEncryptionIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの圧縮メソッドを設定する

ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — 名前で定義されたエントリの圧縮メソッドを設定する

説明

public ZipArchive::setCompressionName(string $name, int $method, int $compflags = 0): bool

名前で定義されたエントリの圧縮メソッドを設定します。

パラメータ

name

エントリの名前

method

圧縮メソッド。 ZipArchive::CM_* のいずれかです。

compflags

圧縮レベル

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アーカイブに異なる圧縮メソッドでファイルを追加する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFromString('foo', 'Some text');
$zip->addFromString('bar', 'Some other text');
$zip->setCompressionName('foo', ZipArchive::CM_STORE);
$zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>

例2 ファイルを追加し、圧縮メソッドを設定する

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip', ZipArchive::CREATE);
if ($res === TRUE) {
$zip->addFile('foo.jpg', 'bar.jpg');
$zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
$zip->close();
echo 'ok';
} else {
echo 'failed';
}
?>


index で定義されたエントリの暗号化方法を指定する

  • ≪ ZipArchive::setCompressionName
  • ZipArchive::setEncryptionName ≫
  • PHP Manual
  • ZipArchive
  • index で定義されたエントリの暗号化方法を指定する

ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — index で定義されたエントリの暗号化方法を指定する

説明

public ZipArchive::setEncryptionIndex(int $index, int $method, #[\SensitiveParameter] ?string $password = null): bool

index で定義されたエントリの暗号化方法を設定します。

パラメータ

index

エントリのインデックスです

method

ZipArchive::EM_ 定数のうちのひとつによって定義された暗号化方式

password

オプションで指定するパスワード。 指定されない場合はデフォルトの値が使われます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | password は、nullable になりました。

注意

注意:

この関数は、libzip ? 1.2.0 でビルドされた場合にのみ利用可能です。

参考

  • ZipArchive::setPassword() - アクティブなアーカイブにパスワードを設定する
  • ZipArchive::setEncryptionName() - 名前で定義されたエントリの暗号化方式を設定する


名前で定義されたエントリの暗号化方式を設定する

  • ≪ ZipArchive::setEncryptionIndex
  • ZipArchive::setExternalAttributesIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの暗号化方式を設定する

ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — 名前で定義されたエントリの暗号化方式を設定する

説明

public ZipArchive::setEncryptionName(string $name, int $method, #[\SensitiveParameter] ?string $password = null): bool

名前で定義されたエントリの暗号化方式を設定する

パラメータ

name

エントリの名前です

method

ZipArchive::EM_ 定数のうちのひとつによって定義された暗号化方式

password

オプションで指定するパスワード。 指定されない場合はデフォルトの値が使われます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | password は、nullable になりました。

例

この例は、ZIP ファイルアーカイブ test.zip を作成し、 AES 256ビット で暗号化した test.txt を追加します。

例1 アーカイブを作成し、ファイルを暗号化する

<?php
$zip = new ZipArchive();
if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
$zip->setPassword('secret');
$zip->addFile('text.txt');
$zip->setEncryptionName('text.txt', ZipArchive::EM_AES_256);
$zip->close();
echo "Ok\n";
} else {
echo "KO\n";
}
?>

注意

注意:

この関数は、libzip ? 1.2.0 でビルドされた場合にのみ利用可能です。

参考

  • ZipArchive::setPassword() - アクティブなアーカイブにパスワードを設定する
  • ZipArchive::setEncryptionIndex() - index で定義されたエントリの暗号化方法を指定する


インデックスで定義されたエントリの外部属性を設定する

  • ≪ ZipArchive::setEncryptionName
  • ZipArchive::setExternalAttributesName ≫
  • PHP Manual
  • ZipArchive
  • インデックスで定義されたエントリの外部属性を設定する

ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — インデックスで定義されたエントリの外部属性を設定する

説明

public ZipArchive::setExternalAttributesIndex(
int $index,
int $opsys,
int $attr,
int $flags = 0
): bool

インデックスで定義されたエントリの外部属性を設定します。

パラメータ

index

エントリのインデックス

opsys

ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコード

attr

外部属性。 値はオペレーティングシステム依存です。

flags

オプションのフラグ。現在は使われていません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


名前で定義されたエントリの外部属性を設定する

  • ≪ ZipArchive::setExternalAttributesIndex
  • ZipArchive::setMtimeIndex ≫
  • PHP Manual
  • ZipArchive
  • 名前で定義されたエントリの外部属性を設定する

ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — 名前で定義されたエントリの外部属性を設定する

説明

public ZipArchive::setExternalAttributesName(
string $name,
int $opsys,
int $attr,
int $flags = 0
): bool

名前で定義されたエントリの外部属性を設定します。

パラメータ

name

エントリの名前

opsys

ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコード

attr

外部属性。 値はオペレーティングシステム依存です。

flags

オプションのフラグ。現在は使われていません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、ZIPファイルアーカイブ test.zip を開き、 ファイル test.txt を 外部属性として Unix権限を付けて追加しています。

例1 Unix権限付きでファイルをアーカイブする

<?php
$zip = new ZipArchive();
$stat = stat($filename='test.txt');
if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
$zip->addFile($filename);
$zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
$zip->close();
echo "Ok\n";
} else {
echo "KO\n";
}
?>


インデックスを使用してエントリの変更時間を設定する

  • ≪ ZipArchive::setExternalAttributesName
  • ZipArchive::setMtimeName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリの変更時間を設定する

ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — インデックスを使用してエントリの変更時間を設定する

説明

public ZipArchive::setMtimeIndex(int $index, int $timestamp, int $flags = 0): bool

インデックスを使用してエントリの変更時間を設定します。

パラメータ

index

エントリのインデックス

timestamp

ファイルの変更時間(Unixタイムスタンプ)

flags

オプションで指定するフラグ。現在未使用です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、php.zip というZIPファイルを生成し、 test.txt というファイルを変更日時と一緒に追加しています。

例1 ファイルをアーカイブする

<?php
$zip = new ZipArchive();
if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
$zip->addFile('text.txt');
$zip->setMtimeIndex(0, mktime(0,0,0,12,25,2019));
$zip->close();
echo "Ok\n";
} else {
echo "KO\n";
}
?>

注意

注意:

この関数は libzip ? 1.0.0 を使って PHP をビルドしたときのみ利用可能です。

参考

  • ZipArchive::setMtimeName() - 名前を使ってエントリの変更時間を設定する


名前を使ってエントリの変更時間を設定する

  • ≪ ZipArchive::setMtimeIndex
  • ZipArchive::setPassword ≫
  • PHP Manual
  • ZipArchive
  • 名前を使ってエントリの変更時間を設定する

ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — 名前を使ってエントリの変更時間を設定する

説明

public ZipArchive::setMtimeName(string $name, int $timestamp, int $flags = 0): bool

名前を使ってエントリの変更時間を設定します。

パラメータ

name

エントリの名前

timestamp

ファイルの変更時間(Unixタイムスタンプ)

flags

オプションで指定するフラグ。現在未使用です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

この例は、test.zip というファイル名の zipファイルを作成し、 test.txt というファイルを変更日時と一緒に追加しています。

例1 ファイルをアーカイブする

<?php
$zip = new ZipArchive();
if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
$zip->addFile('text.txt');
$zip->setMtimeName('text.txt', mktime(0,0,0,12,25,2019));
$zip->close();
echo "Ok\n";
} else {
echo "KO\n";
}
?>

注意

注意:

この関数は libzip ? 1.0.0 を使って PHP をビルドしたときのみ利用可能です。

参考

  • ZipArchive::setMtimeIndex() - インデックスを使用してエントリの変更時間を設定する


アクティブなアーカイブにパスワードを設定する

  • ≪ ZipArchive::setMtimeName
  • ZipArchive::statIndex ≫
  • PHP Manual
  • ZipArchive
  • アクティブなアーカイブにパスワードを設定する

ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — アクティブなアーカイブにパスワードを設定する

説明

public ZipArchive::setPassword(#[\SensitiveParameter] string $password): bool

アクティブなアーカイブにパスワードを設定します。

パラメータ

password

アーカイブに使用されるパスワード。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

PHP 7.2.0 と libzip 1.2.0 以降では、パスワードはアーカイブを解凍するのに使われます。 そして、ZipArchive::setEncryptionName() と ZipArchive::setEncryptionIndex() のデフォルトのパスワードとしても使われます。 これより前のバージョンでは、この関数はアーカイブの解凍のみに使うパスワードを設定していました。 つまり、パスワードで保護されていない ZipArchive をパスワードで保護された ZipArchive に変換していませんでした。

参考

  • ZipArchive::setEncryptionIndex() - index で定義されたエントリの暗号化方法を指定する
  • ZipArchive::setEncryptionName() - 名前で定義されたエントリの暗号化方式を設定する


インデックスを使用してエントリの詳細を取得する

  • ≪ ZipArchive::setPassword
  • ZipArchive::statName ≫
  • PHP Manual
  • ZipArchive
  • インデックスを使用してエントリの詳細を取得する

ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — インデックスを使用してエントリの詳細を取得する

説明

public ZipArchive::statIndex(int $index, int $flags = 0): array|false

この関数は、インデックスを使用してエントリの詳細情報を取得します。

パラメータ

index

エントリのインデックス。

flags

ZipArchive::FL_UNCHANGED を OR で連結すると、 アーカイブ内に最初に記録された際の情報を取得します。 変更内容は無視されます。

戻り値

エントリの詳細を含む配列を返します。失敗した場合に false を返します。

例

例1 エントリの情報の出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
print_r($zip->statIndex(3));
$zip->close();
} else {
echo '失敗、コード:' . $res;
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => foobar/baz
    [index] => 3
    [crc] => 499465816
    [size] => 27
    [mtime] => 1123164748
    [comp_size] => 24
    [comp_method] => 8
)


名前を使用してエントリの詳細を取得する

  • ≪ ZipArchive::statIndex
  • ZipArchive::unchangeAll ≫
  • PHP Manual
  • ZipArchive
  • 名前を使用してエントリの詳細を取得する

ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — 名前を使用してエントリの詳細を取得する

説明

public ZipArchive::statName(string $name, int $flags = 0): array|false

この関数は、名前を使用してエントリの詳細情報を取得します。

パラメータ

name

エントリの名前。

flags

名前をどのように探すのかを設定します。 また ZipArchive::FL_UNCHANGED を OR で連結すると、 アーカイブ内に最初に記録された際の情報を取得します。 変更内容は無視されます。

  • ZipArchive::FL_NOCASE

  • ZipArchive::FL_NODIR

  • ZipArchive::FL_UNCHANGED

戻り値

エントリの詳細を含む配列を返します。失敗した場合に false を返します。

例

例1 エントリの情報の出力

<?php
$zip = new ZipArchive;
$res = $zip->open('test.zip');
if ($res === TRUE) {
print_r($zip->statName('foobar/baz'));
$zip->close();
} else {
echo '失敗、コード:' . $res;
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => foobar/baz
    [index] => 3
    [crc] => 499465816
    [size] => 27
    [mtime] => 1123164748
    [comp_size] => 24
    [comp_method] => 8
)


アーカイブに対するすべての変更を取り消す

  • ≪ ZipArchive::statName
  • ZipArchive::unchangeArchive ≫
  • PHP Manual
  • ZipArchive
  • アーカイブに対するすべての変更を取り消す

ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — アーカイブに対するすべての変更を取り消す

説明

public ZipArchive::unchangeAll(): bool

アーカイブに対するすべての変更を取り消します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


アーカイブ全体に対して行われたすべての変更を取り消す

  • ≪ ZipArchive::unchangeAll
  • ZipArchive::unchangeIndex ≫
  • PHP Manual
  • ZipArchive
  • アーカイブ全体に対して行われたすべての変更を取り消す

ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — アーカイブ全体に対して行われたすべての変更を取り消す

説明

public ZipArchive::unchangeArchive(): bool

アーカイブ全体に対して行われたすべての変更を取り消します。 現在は、これはアーカイブのコメントに対する変更のみを取り消します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


指定したインデックスのエントリに対するすべての変更を取り消す

  • ≪ ZipArchive::unchangeArchive
  • ZipArchive::unchangeName ≫
  • PHP Manual
  • ZipArchive
  • 指定したインデックスのエントリに対するすべての変更を取り消す

ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — 指定したインデックスのエントリに対するすべての変更を取り消す

説明

public ZipArchive::unchangeIndex(int $index): bool

指定したインデックスのエントリに対するすべての変更を取り消します。

パラメータ

index

エントリのインデックス。

戻り値

成功した場合に true を、失敗した場合に false を返します。


指定した名前のエントリに対するすべての変更を取り消す

  • ≪ ZipArchive::unchangeIndex
  • Zip 関数 ≫
  • PHP Manual
  • ZipArchive
  • 指定した名前のエントリに対するすべての変更を取り消す

ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — 指定した名前のエントリに対するすべての変更を取り消す

説明

public ZipArchive::unchangeName(string $name): bool

エントリに対するすべての変更を取り消します。

パラメータ

name

エントリの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。


Zip 関数

警告

手続き型のAPI は PHP 8.0.0 以降、推奨されなくなりました。 代わりに ZipArchive クラスを使うべきです。

目次

  • zip_close — ZIP ファイルアーカイブを閉じる
  • zip_entry_close — ディレクトリエントリを閉じる
  • zip_entry_compressedsize — ディレクトリエントリの圧縮時のサイズを取得する
  • zip_entry_compressionmethod — ディレクトリエントリの圧縮方法を取得する
  • zip_entry_filesize — ディレクトリエントリの実際のファイルサイズを取得する
  • zip_entry_name — ディレクトリエントリの名前を取得する
  • zip_entry_open — 読込み用にディレクトリエントリをオープンする
  • zip_entry_read — オープンされたディレクトリエントリから読み込む
  • zip_open — Zip ファイルアーカイブをオープンする
  • zip_read — Zip ファイルアーカイブの中の次のエントリを読み込む


ZIP ファイルアーカイブを閉じる

  • ≪ Zip 関数
  • zip_entry_close ≫
  • PHP Manual
  • Zip 関数
  • ZIP ファイルアーカイブを閉じる

zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — ZIP ファイルアーカイブを閉じる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_close(resource $zip): void

ZIP ファイルアーカイブを閉じます。

パラメータ

zip

事前に zip_open() でオープンされた ZIP ファイル。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::close() を参照ください。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む


ディレクトリエントリを閉じる

  • ≪ zip_close
  • zip_entry_compressedsize ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリを閉じる

zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — ディレクトリエントリを閉じる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_close(resource $zip_entry): bool

指定されたディレクトリエントリを閉じます。

パラメータ

zip_entry

zip_entry_open()によりオープンされたディレクトリの エントリ

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。

参考

  • zip_entry_open() - 読込み用にディレクトリエントリをオープンする
  • zip_entry_read() - オープンされたディレクトリエントリから読み込む


ディレクトリエントリの圧縮時のサイズを取得する

  • ≪ zip_entry_close
  • zip_entry_compressionmethod ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの圧縮時のサイズを取得する

zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — ディレクトリエントリの圧縮時のサイズを取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_compressedsize(resource $zip_entry): int|false

ディレクトリエントリの圧縮時のサイズを取得します。

パラメータ

zip_entry

zip_read()により返されたディレクトリのエントリ

戻り値

圧縮後のサイズを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照ください。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む


ディレクトリエントリの圧縮方法を取得する

  • ≪ zip_entry_compressedsize
  • zip_entry_filesize ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの圧縮方法を取得する

zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — ディレクトリエントリの圧縮方法を取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_compressionmethod(resource $zip_entry): string|false

zip_entryにより指定されたディレクトリエントリの 圧縮方法を返します。

パラメータ

zip_entry

zip_read()により返されたディレクトリのエントリ

戻り値

圧縮方法を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照ください。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む


ディレクトリエントリの実際のファイルサイズを取得する

  • ≪ zip_entry_compressionmethod
  • zip_entry_name ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの実際のファイルサイズを取得する

zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — ディレクトリエントリの実際のファイルサイズを取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_filesize(resource $zip_entry): int|false

ディレクトリエントリの実際のファイルサイズを返します。

パラメータ

zip_entry

zip_read()により返されたディレクトリのエントリ

戻り値

ディレクトリエントリのサイズを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照ください。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む


ディレクトリエントリの名前を取得する

  • ≪ zip_entry_filesize
  • zip_entry_open ≫
  • PHP Manual
  • Zip 関数
  • ディレクトリエントリの名前を取得する

zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — ディレクトリエントリの名前を取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_name(resource $zip_entry): string|false

指定したディレクトリエントリの名前を返します。

パラメータ

zip_entry

zip_read()により返されたディレクトリエントリ

戻り値

ディレクトリエントリの名前を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照ください。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む


読込み用にディレクトリエントリをオープンする

  • ≪ zip_entry_name
  • zip_entry_read ≫
  • PHP Manual
  • Zip 関数
  • 読込み用にディレクトリエントリをオープンする

zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — 読込み用にディレクトリエントリをオープンする

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_open(resource $zip_dp, resource $zip_entry, string $mode = "rb"): bool

読込み用にzipファイルの中にディレクトリエントリをオープンします。

パラメータ

zip_dp

zip_open()により返された有効なリソースハンドル

zip_entry

zip_read()により返されたディレクトリエントリ

mode

fopen()のマニュアルで指定されたモードのどれか

注意:

現在、modeは無視され、 常に"rb"となります。 これは、PHPのzipサポートが読み込みのみのアクセスであるためです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意:

fopen()や他の同種の関数と異なり、 zip_entry_open()の戻り値は、 処理の結果のみを示し、ディレクトリエントリの読み込みやクローズの際には 必要とされません。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。

参考

  • zip_entry_close() - ディレクトリエントリを閉じる
  • zip_entry_read() - オープンされたディレクトリエントリから読み込む


オープンされたディレクトリエントリから読み込む

  • ≪ zip_entry_open
  • zip_open ≫
  • PHP Manual
  • Zip 関数
  • オープンされたディレクトリエントリから読み込む

zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — オープンされたディレクトリエントリから読み込む

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_entry_read(resource $zip_entry, int $len = 1024): string|false

オープンされたディレクトリエントリから読み込みます。

パラメータ

zip_entry

zip_read()により返されたディレクトリエントリ

len

返すバイト数。

注意:

これは、読み込むデータの非圧縮時の長さとなります。

戻り値

読み込んだデータを返します。ファイルの終端に達した場合は空文字列、エラー時には false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::getFromIndex() を参照ください。

参考

  • zip_entry_open() - 読込み用にディレクトリエントリをオープンする
  • zip_entry_close() - ディレクトリエントリを閉じる
  • zip_entry_filesize() - ディレクトリエントリの実際のファイルサイズを取得する


Zip ファイルアーカイブをオープンする

  • ≪ zip_entry_read
  • zip_read ≫
  • PHP Manual
  • Zip 関数
  • Zip ファイルアーカイブをオープンする

zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Zip ファイルアーカイブをオープンする

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_open(string $filename): resource|int|false

読み込み用に新規に Zip アーカイブをオープンします。

パラメータ

filename

オープンする ZIP アーカイブのファイル名。

戻り値

後で zip_read() および zip_close() で使用されるリソースハンドル、または、 filename が存在しない場合やその他のエラーが発生した場合は false か エラーの番号を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::open() を参照ください。

参考

  • zip_read() - Zip ファイルアーカイブの中の次のエントリを読み込む
  • zip_close() - ZIP ファイルアーカイブを閉じる


Zip ファイルアーカイブの中の次のエントリを読み込む

  • ≪ zip_open
  • Zlib ≫
  • PHP Manual
  • Zip 関数
  • Zip ファイルアーカイブの中の次のエントリを読み込む

zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Zip ファイルアーカイブの中の次のエントリを読み込む

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

zip_read(resource $zip): resource|false

Zip ファイルアーカイブの中の次のエントリを読み込みます。

パラメータ

zip

zip_open() でオープン済みの ZIP ファイル。

戻り値

後で zip_entry_... 関数で使用されるディレクトリエントリリソース、または、 読み込むエントリがもうない場合に false、 その他のエラーが発生した場合はエラー番号を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::statIndex() を参照ください。

参考

  • zip_open() - Zip ファイルアーカイブをオープンする
  • zip_close() - ZIP ファイルアーカイブを閉じる
  • zip_entry_open() - 読込み用にディレクトリエントリをオープンする
  • zip_entry_read() - オープンされたディレクトリエントリから読み込む


Zlib 圧縮

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Zlib 関数
    • deflate_add — インクリメンタルにデータを圧縮する
    • deflate_init — インクリメンタルな圧縮コンテキストを初期化する
    • gzclose — 開かれたgzファイルへのポインタを閉じる
    • gzcompress — 文字列を圧縮する
    • gzdecode — gzip 圧縮された文字列をデコードする
    • gzdeflate — 文字列を deflate 圧縮する
    • gzencode — gzip 圧縮された文字列を作成する
    • gzeof — gz ファイルポインタが EOF かどうか調べる
    • gzfile — gzファイル全体を配列に読み込む
    • gzgetc — gz ファイルへのポインタから文字を得る
    • gzgets — ファイルポインタから 1 行を得る
    • gzgetss — gzファイルへのポインタから1行を得て、HTMLタグを取り除く
    • gzinflate — deflate圧縮された文字列を解凍する
    • gzopen — gz ファイルを開く
    • gzpassthru — gzファイルへのポインタから残りのデータ全部を出力する
    • gzputs — gzwrite のエイリアス
    • gzread — バイナリ対応のgzファイル読み込み
    • gzrewind — gz ファイルポインタの示す位置を元に戻す
    • gzseek — gz ファイルポインタの位置を移動する
    • gztell — gz ファイルポインタの読み込み/書き込み位置を返します
    • gzuncompress — 圧縮された文字列を解凍する
    • gzwrite — バイナリセーフな gz ファイル書き込み
    • inflate_add — インクリメンタルにエンコードされたデータを解凍する
    • inflate_get_read_len — これまでに読み取ったバイト数を得る
    • inflate_get_status — 解凍の状態を取得する
    • inflate_init — インクリメンタルな解凍コンテキストを初期化する
    • ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数
    • readgzfile — gz ファイルを出力する
    • zlib_decode — raw/gzip/zlib で符号化されたデータを復元する
    • zlib_encode — 指定した符号化方式でデータを圧縮する
    • zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す
  • DeflateContext — DeflateContext クラス
  • InflateContext — InflateContext クラス


はじめに

このモジュールにより gzip (.gz) で圧縮されたファイルを読み書きすることが可能となります。 この際、ファイルシステム 関数の gzip 圧縮対応版 (非圧縮ファイルも扱えますが、 ソケットは扱えません)を使用します。

注意:

PHP には、.gz ファイルに対応した fopen のラッパーが搭載されています。 詳細な情報は、 zlib:// にあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Zlib
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

このモジュールは、Jean-loup Gailly および Mark Adler による » zlib の関数を使用します。 このモジュールを使用するには、 zlib >= 1.2.0.4 を使用する必要があります。


インストール手順

PHPにおけるZlibサポートは、デフォルトでは利用できません。 Zlibサポートを有効にするには、PHPのコンパイル時にconfigureの オプションに--with-zlib[=DIR]を 指定してコンパイルする必要があります。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


実行時設定

php.ini の設定により動作が変化します。

zlib 拡張モジュールは、 ブラウザがサポートする場合にページを透過的に圧縮するオプションを提供します。 ここで、 設定ファイル php.ini のオプションには、以下の 3 種類があります。

Zlib設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
zlib.output_compression | "0" | INI_ALL |
zlib.output_compression_level | "-1" | INI_ALL |
zlib.output_handler | "" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

zlib.output_compression bool/int

透過的なページ圧縮を行うかどうか。php.ini または Apache の設定でこのオプションが、"On" に設定された場合、 ブラウザが "Accept-Encoding: gzip" または "deflate" ヘッダを送信する場合に、ページは圧縮されます。 "Content-Encoding: gzip" (および "deflate") と "Vary: Accept-Encoding" ヘッダが出力に追加されます。 実行時、何らかのデータを送出する前にのみ設定することが可能です。

このオプションも論理値 "On"/"Off" のかわりに整数値をとることができ、 これを用いて出力のバッファサイズ (デフォルトは 4KB) を設定することができます。

注意:

このオプションに 'On' を設定した場合、 output_handler を空にする必要があります! かわりに zlib.output_handler を使用する必要があります。

zlib.output_compression_level int

透過的出力圧縮で使用される圧縮レベル。0 (圧縮しない) から 9 (最高レベルの圧縮をする) までの値を指定します。デフォルト値の -1 は、どのレベルを使用するかをサーバーで決定させます。

zlib.output_handler string

zlib.output_compression が有効な場合、 他の出力ハンドラを指定することはできません。 この設定は、output_handler と同じですが、順番が異なります。


リソース型

この拡張モジュールでは、ファイルポインタリソースを定義しています。これは gzopen() が返すものです。 PHP 8.0.0 より前のバージョンでは、 zlib.deflate と zlib.inflate リソースも定義されていました。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FORCE_GZIP (int)
FORCE_DEFLATE (int)
ZLIB_ENCODING_RAW (int)
RFC 1951 の DEFLATE アルゴリズム。
ZLIB_ENCODING_DEFLATE (int)
RFC 1950 の ZLIB 圧縮アルゴリズム。
ZLIB_ENCODING_GZIP (int)
RFC 1952 の GZIP アルゴリズム。
ZLIB_FILTERED (int)
ZLIB_HUFFMAN_ONLY (int)
ZLIB_FIXED (int)
ZLIB_RLE (int)
ZLIB_DEFAULT_STRATEGY (int)
ZLIB_BLOCK (int)
ZLIB_NO_FLUSH (int)
ZLIB_PARTIAL_FLUSH (int)
ZLIB_SYNC_FLUSH (int)
ZLIB_FULL_FLUSH (int)
ZLIB_FINISH (int)
ZLIB_VERSION (string)
zlib のバージョンナンバーの文字列
ZLIB_VERNUM (int)
zlib のバージョンナンバーの数値
ZLIB_OK (int)
エラーや追加のステータス情報がないことを示します
ZLIB_STREAM_END (int)
ストリームが無事終了したことを示します
ZLIB_NEED_DICT (int)
あらかじめ辞書を設定しておくことが必要です Preset dictionary is needed.
ZLIB_ERRNO (int)
ファイル操作時のエラー
ZLIB_STREAM_ERROR (int)
ストリームのステートが一貫していないか、 パラメータが不正です
ZLIB_DATA_ERROR (int)
入力データが壊れています
ZLIB_MEM_ERROR (int)
メモリが足りません
ZLIB_BUF_ERROR (int)
バッファスペースが足りないか、 入力ストリームの終端が壊れているために処理を続行できません。
ZLIB_VERSION_ERROR (int)
zlib のライブラリバージョンが、 呼び出し側が想定しているバージョンと互換性がありません


例

テンポラリファイルをオープンし、テスト用文字列を書きこみ、 続いて、このファイルの内容を 2 回出力します。

例1 簡単な Zlib の例

<?php

$filename = tempnam('/tmp', 'zlibtest') . '.gz';
echo "<html>\n<head></head>\n<body>\n<pre>\n";
$s = "Only a test, test, test, test, test, test, test, test!\n";

// 最大限の圧縮を指定して書きこみ用にファイルをオープン
$zp = gzopen($filename, "w9");

// 文字列をファイルに書きこむ
gzwrite($zp, $s);

// ファイルを閉じる
gzclose($zp);

// 読みこみ用にファイルをオープン
$zp = gzopen($filename, "r");

// 3 文字読みこむ
echo gzread($zp, 3);

// ファイルの終端まで出力して閉じる
gzpassthru($zp);
gzclose($zp);

echo "\n";

// ファイルをオープンし、内容を出力する (2回目)
if (readgzfile($filename) != strlen($s)) {
echo "Error with zlib functions!";
}
unlink($filename);
echo "</pre>\n</body>\n</html>\n";

?>

例2 インクリメンタルな圧縮および伸長の API

<?php
// GZIP 圧縮
$deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
$compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);

// GZIP 伸長
$inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
$uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
$uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
echo $uncompressed;
?>

上の例の出力は以下となります。

Data to compress, more data, and even more data!


Zlib 関数

目次

  • deflate_add — インクリメンタルにデータを圧縮する
  • deflate_init — インクリメンタルな圧縮コンテキストを初期化する
  • gzclose — 開かれたgzファイルへのポインタを閉じる
  • gzcompress — 文字列を圧縮する
  • gzdecode — gzip 圧縮された文字列をデコードする
  • gzdeflate — 文字列を deflate 圧縮する
  • gzencode — gzip 圧縮された文字列を作成する
  • gzeof — gz ファイルポインタが EOF かどうか調べる
  • gzfile — gzファイル全体を配列に読み込む
  • gzgetc — gz ファイルへのポインタから文字を得る
  • gzgets — ファイルポインタから 1 行を得る
  • gzgetss — gzファイルへのポインタから1行を得て、HTMLタグを取り除く
  • gzinflate — deflate圧縮された文字列を解凍する
  • gzopen — gz ファイルを開く
  • gzpassthru — gzファイルへのポインタから残りのデータ全部を出力する
  • gzputs — gzwrite のエイリアス
  • gzread — バイナリ対応のgzファイル読み込み
  • gzrewind — gz ファイルポインタの示す位置を元に戻す
  • gzseek — gz ファイルポインタの位置を移動する
  • gztell — gz ファイルポインタの読み込み/書き込み位置を返します
  • gzuncompress — 圧縮された文字列を解凍する
  • gzwrite — バイナリセーフな gz ファイル書き込み
  • inflate_add — インクリメンタルにエンコードされたデータを解凍する
  • inflate_get_read_len — これまでに読み取ったバイト数を得る
  • inflate_get_status — 解凍の状態を取得する
  • inflate_init — インクリメンタルな解凍コンテキストを初期化する
  • ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数
  • readgzfile — gz ファイルを出力する
  • zlib_decode — raw/gzip/zlib で符号化されたデータを復元する
  • zlib_encode — 指定した符号化方式でデータを圧縮する
  • zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す


インクリメンタルにデータを圧縮する

  • ≪ Zlib 関数
  • deflate_init ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルにデータを圧縮する

deflate_add

(PHP 7, PHP 8)

deflate_add — インクリメンタルにデータを圧縮する

説明

deflate_add(DeflateContext $context, string $data, int $flush_mode = ZLIB_SYNC_FLUSH): string|false

指定されたコンテクストで、インクリメンタルにデータを圧縮します。

パラメータ

context

deflate_init() で生成したコンテクスト

data

圧縮するデータ

flush_mode

ZLIB_BLOCK, ZLIB_NO_FLUSH, ZLIB_PARTIAL_FLUSH, ZLIB_SYNC_FLUSH (デフォルト), ZLIB_FULL_FLUSH, ZLIB_FINISH のいずれかです。 通常は、圧縮率を最大にするために、 ZLIB_NO_FLUSH を指定するでしょうし、 データの最後のチャンクで終了させるために ZLIB_FINISH を指定するでしょう。 これらの定数の詳細な説明は » zlib manual を参照ください。

戻り値

圧縮されたデータのチャンクを返します。 失敗した場合に false を返します

エラー / 例外

不正な引数が与えられた場合、 エラーレベル E_WARNING が生成されます。

変更履歴

バージョン | 説明
8.0.0 | context は、 DeflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • deflate_init() - インクリメンタルな圧縮コンテキストを初期化する


インクリメンタルな圧縮コンテキストを初期化する

  • ≪ deflate_add
  • gzclose ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルな圧縮コンテキストを初期化する

deflate_init

(PHP 7, PHP 8)

deflate_init — インクリメンタルな圧縮コンテキストを初期化する

説明

deflate_init(int $encoding, array $options = []): DeflateContext|false

指定された encoding を使って インクリメンタルな圧縮コンテキストを初期化します。

window オプションは、 アルゴリズムのウィンドウサイズだけを設定することに注意してください。 これは、同じパラメータが利用するエンコーディングも設定する zlib filter と異なります。 この関数では、エンコーディングは encoding で指定しなければなりません。

制限: GZIP 圧縮されたストリームにヘッダ情報を設定する方法が現状は存在しません。 これは、次のようにして設定されます: GZIP シグネチャ (\x1f\x8B); 圧縮メソッド (\x08 == DEFLATE); 6 個のゼロバイト; 現在のオペレーティングシステム (\x00 = Windows, \x03 = Unix, など)

パラメータ

encoding

定数 ZLIB_ENCODING_* のうちのひとつ

options

以下の要素を含む連想配列:

level

-1 .. 9 までの圧縮レベル。デフォルトは -1 です。

memory

1 .. 9 までの圧縮メモリレベル。デフォルトは8です。

window

8 .. 15 までの zlib の window サイズ(対数)。 デフォルトは 15 です。 zlib 1.2.8 以降では、 window サイズ 8 が ZLIB_ENCODING_RAW や ZLIB_ENCODING_GZIP と一緒に指定された場合、この関数は失敗し、警告が発生します。 同時に、zlib は window サイズを 8 から 9 に変更します。

strategy

ZLIB_FILTERED, ZLIB_HUFFMAN_ONLY, ZLIB_RLE, ZLIB_FIXED, ZLIB_DEFAULT_STRATEGY (デフォルト) のうちのいずれか。

dictionary

あらかじめ設定されたディクショナリの string または strings の array。 (デフォルト: 辞書なし)

戻り値

成功した場合、圧縮コンテキストリソース(zlib.deflate) を返します。 失敗した場合に false を返します

エラー / 例外

不正なオプションが options に渡されたり、 コンテキストが作れなかった場合には、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は DeflateContext クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

参考

  • deflate_add() - インクリメンタルにデータを圧縮する
  • inflate_init() - インクリメンタルな解凍コンテキストを初期化する


開かれたgzファイルへのポインタを閉じる

  • ≪ deflate_init
  • gzcompress ≫
  • PHP Manual
  • Zlib 関数
  • 開かれたgzファイルへのポインタを閉じる

gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — 開かれたgzファイルへのポインタを閉じる

説明

gzclose(resource $stream): bool

与えられた gz ファイルへのポインタを閉じます。

パラメータ

stream

gzファイルポインタ。有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 gzclose() の例

<?php
$gz = gzopen('somefile.gz','w9');
gzputs ($gz, 'I was added to somefile.gz');
gzclose($gz);
?>

参考

  • gzopen() - gz ファイルを開く


文字列を圧縮する

  • ≪ gzclose
  • gzdecode ≫
  • PHP Manual
  • Zlib 関数
  • 文字列を圧縮する

gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — 文字列を圧縮する

説明

gzcompress(string $data, int $level = -1, int $encoding = ZLIB_ENCODING_DEFLATE): string|false

この関数は、ZLIB データフォーマットを用いて 与えられた文字列を圧縮します。

ZLIB 圧縮アルゴリズムについての詳細は、 "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950) を参照ください。

注意:

これは、いくつかのヘッダデータを有する gzip 圧縮と同じでは ありません。 gzip圧縮については、gzencode()を参照ください。

パラメータ

data

圧縮するデータ

level

圧縮レベル。0 で圧縮無し、9 で最大限の圧縮を指定できます。

-1 を指定すると、zlib ライブラリのデフォルトを使います。デフォルトは 6 です。

encoding

定数 ZLIB_ENCODING_* のいずれか。

戻り値

圧縮された文字列、もしくはエラーの場合 false 。

例

例1 gzcompress() の例

<?php
$compressed = gzcompress('Compress me', 9);
echo $compressed;
?>

参考

  • gzdeflate() - 文字列を deflate 圧縮する
  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzencode() - gzip 圧縮された文字列を作成する


gzip 圧縮された文字列をデコードする

  • ≪ gzcompress
  • gzdeflate ≫
  • PHP Manual
  • Zlib 関数
  • gzip 圧縮された文字列をデコードする

gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — gzip 圧縮された文字列をデコードする

説明

gzdecode(string $data, int $max_length = 0): string|false

この関数は、入力された data をデコードしたものを返します。

パラメータ

data

デコードするデータ。これは gzencode() でエンコードされたものです。

max_length

デコードするデータの最大長。

戻り値

デコードされた文字列を返します。 失敗した場合に false を返します

エラー / 例外

失敗した場合、 E_WARNING レベルの警告が発生します。

参考

  • gzencode() - gzip 圧縮された文字列を作成する


文字列を deflate 圧縮する

  • ≪ gzdecode
  • gzencode ≫
  • PHP Manual
  • Zlib 関数
  • 文字列を deflate 圧縮する

gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — 文字列を deflate 圧縮する

説明

gzdeflate(string $data, int $level = -1, int $encoding = ZLIB_ENCODING_RAW): string|false

この関数は、DEFLATE データフォーマットを用いて 与えられた文字列を圧縮します。

DEFLATE 圧縮アルゴリズムについての詳細は、 "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951) を参照ください。

パラメータ

data

収縮させるデータ

level

圧縮レベル。圧縮しない場合に0、最大限の圧縮をする場合に9を指定可能です。 指定しない場合、デフォルトの圧縮レベルは zlib ライブラリのデフォルト圧縮レベルになります。

encoding

定数 ZLIB_ENCODING_* のいずれか。

戻り値

収縮された文字列、もしくはエラーの場合 false 。

例

例1 gzdeflate() の例

<?php
$compressed = gzdeflate('Compress me', 9);
echo $compressed;
?>

参考

  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzcompress() - 文字列を圧縮する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzencode() - gzip 圧縮された文字列を作成する


gzip 圧縮された文字列を作成する

  • ≪ gzdeflate
  • gzeof ≫
  • PHP Manual
  • Zlib 関数
  • gzip 圧縮された文字列を作成する

gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — gzip 圧縮された文字列を作成する

説明

gzencode(string $data, int $level = -1, int $encoding = ZLIB_ENCODING_GZIP): string|false

この関数は、入力 dataを gzip プログラムの出力と互換性のある形式で圧縮 して返します。

GZIPファイルフォーマットに関する詳細な情報については、次のドキュ メントを参照ください。 » GZIP file format specification version 4.3 (RFC 1952)

パラメータ

data

エンコードするデータを指定します

level

圧縮レベルを指定します。 圧縮をしない場合に 0、最大限の圧縮を行う場合に9を指定可能です。 指定されない場合のデフォルト圧縮レベルは、 zlib ライブラリのデフォルト圧縮レベルになります。

encoding

エンコーディングモードを指定します。 FORCE_GZIP (デフォルト) もしくは FORCE_DEFLATE を指定可能です。

FORCE_DEFLATE は RFC 1950 準拠の出力を生成します。 これは、zlib ヘッダ、圧縮したデータ、 そして Adler チェックサムで構成されます。

戻り値

エンコードされた文字列、もしくはエラー発生時に false

例

結果データは標準的な .gz ファイルを構成するための適当なヘッダとデータ構造を含みます。

例1 gzip ファイルの生成

<?php
$data = file_get_contents("bigfile.txt");
$gzdata = gzencode($data, 9);
file_put_contents("bigfile.txt.gz", $gzdata);
?>

参考

  • gzdecode() - gzip 圧縮された文字列をデコードする
  • gzdeflate() - 文字列を deflate 圧縮する
  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzcompress() - 文字列を圧縮する
  • » ZLIB Compressed Data Format Specification (RFC 1950)


gz ファイルポインタが EOF かどうか調べる

  • ≪ gzencode
  • gzfile ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタが EOF かどうか調べる

gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — gz ファイルポインタが EOF かどうか調べる

説明

gzeof(resource $stream): bool

与えられた GZ ファイルポインタが EOF (ファイル終端) を指すかどうかを調べます。

パラメータ

stream

gzファイルポインタは、有効なファイルポインタであり、かつ、 gzopen()によりオープンできたファイルを指している 必要があります。

戻り値

gz ファイルポインタが EOF を指す、もしくはエラーが発生した場合 true、 そうでなければ false を返します。

例

例1 gzeof() の例

<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
echo gzgetc($gz);
}
gzclose($gz);
?>


gzファイル全体を配列に読み込む

  • ≪ gzeof
  • gzgetc ≫
  • PHP Manual
  • Zlib 関数
  • gzファイル全体を配列に読み込む

gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — gzファイル全体を配列に読み込む

説明

gzfile(string $filename, int $use_include_path = 0): array|false

ファイルを配列にして返すこと以外は readgzfile() と同じです。

パラメータ

filename

ファイル名を指定します。

use_include_path

もし include_path にあるファイルも検索したい場合、 このオプションパラメータに 1 を設定することができます。

戻り値

ファイルを含む配列で、要素毎に 1 行ずつ含んでいます。空行も含み、改行もついた状態です。 失敗した場合に false を返します

例

例1 gzfile() の例

<?php
$lines = gzfile('somefile.gz');
foreach ($lines as $line) {
echo $line;
}
?>

参考

  • readgzfile() - gz ファイルを出力する
  • gzopen() - gz ファイルを開く


gz ファイルへのポインタから文字を得る

  • ≪ gzfile
  • gzgets ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルへのポインタから文字を得る

gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — gz ファイルへのポインタから文字を得る

説明

gzgetc(resource $stream): string|false

与えられた gz ファイルポインタから (非圧縮の) 1 文字を読み込み、これを含む 文字列を返します。

パラメータ

stream

gz ファイルポインタを指定します。 これは有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

戻り値

非圧縮の文字列、もしくは EOF (gzeof() とは異なる) の場合に false を返します。

例

例1 gzgetc() の例

<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
echo gzgetc($gz);
}
gzclose($gz);
?>

参考

  • gzopen() - gz ファイルを開く
  • gzgets() - ファイルポインタから 1 行を得る


ファイルポインタから 1 行を得る

  • ≪ gzgetc
  • gzgetss ≫
  • PHP Manual
  • Zlib 関数
  • ファイルポインタから 1 行を得る

gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — ファイルポインタから 1 行を得る

説明

gzgets(resource $stream, ?int $length = null): string|false

与えられたファイルポインタから最大 length - 1 バイトの文字を読み込み、 これを含む (非圧縮の) 文字列を返します。 length - 1 バイトを読み込むか、改行または EOF になった場合、 (どれかが最初にきた時点で) 読み込みを終了します。

パラメータ

stream

gz ファイルポインタを指定します。 これは有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

length

取得するデータ長を指定します。

戻り値

非圧縮の文字列、もしくはエラー時に false

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。 これより前のバージョンでは、 デフォルトは 1024 でした。

例

例1 gzgets() の例

<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
$buffer = gzgets($handle, 4096);
echo $buffer;
}
gzclose($handle);
?>

参考

  • gzopen() - gz ファイルを開く
  • gzgetc() - gz ファイルへのポインタから文字を得る
  • gzwrite() - バイナリセーフな gz ファイル書き込み


gzファイルへのポインタから1行を得て、HTMLタグを取り除く

  • ≪ gzgets
  • gzinflate ≫
  • PHP Manual
  • Zlib 関数
  • gzファイルへのポインタから1行を得て、HTMLタグを取り除く

gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — gzファイルへのポインタから1行を得て、HTMLタグを取り除く

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

gzgetss(resource $zp, int $length, string $allowable_tags = ?): string

gzgetss()は読み込んだテキストから HTML および PHP タグを全て取り除こうとすることを除いて、 gzgets()と同じです。

パラメータ

zp

gz ファイルポインタを指定します。 これは有効なファイルポインタであり、かつ、 gzopen() によりオープンできたファイルを指している必要があります。

length

取得するデータ長を指定します。

allowable_tags

このオプションパラメータにより、 取り除かないタグを指定することができます。

戻り値

非圧縮かつタグが取り除かれた文字列、もしくはエラー時に false

例

例1 gzgetss() の例

<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
$buffer = gzgetss($handle, 4096);
echo $buffer;
}
gzclose($handle);
?>

参考

  • gzopen() - gz ファイルを開く
  • gzgets() - ファイルポインタから 1 行を得る
  • strip_tags() - 文字列から HTML および PHP タグを取り除く


deflate圧縮された文字列を解凍する

  • ≪ gzgetss
  • gzopen ≫
  • PHP Manual
  • Zlib 関数
  • deflate圧縮された文字列を解凍する

gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — deflate圧縮された文字列を解凍する

説明

gzinflate(string $data, int $max_length = 0): string|false

この関数は圧縮された文字列を解凍(伸長)します。

パラメータ

data

gzdeflate() により圧縮されたデータを指定します

max_length

解凍されたデータの最大長を指定します

戻り値

オリジナルの無圧縮なデータ、もしくはエラー時に false

この関数は、もし無圧縮なデータが圧縮された入力 data の 32768 倍以上の場合、エラーを返します。 また、オプションのパラメータ max_length に 0 以外が指定された場合、 無圧縮なデータが max_length 以上の場合、エラーを返します。

例

例1 gzinflate() の例

<?php
$compressed = gzdeflate('Compress me', 9);
$uncompressed = gzinflate($compressed);
echo $uncompressed;
?>

参考

  • gzdeflate() - 文字列を deflate 圧縮する
  • gzcompress() - 文字列を圧縮する
  • gzuncompress() - 圧縮された文字列を解凍する
  • gzencode() - gzip 圧縮された文字列を作成する


gz ファイルを開く

  • ≪ gzinflate
  • gzpassthru ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルを開く

gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — gz ファイルを開く

説明

gzopen(string $filename, string $mode, int $use_include_path = 0): resource|false

読み込みもしくは書き込みのために gzip (.gz) ファイルをオープンします。

gzopen() は、gzip フォーマットでないファイルの読み込みについても使用することができます。 この場合、gzread()は、ファイルを解凍せずに直接読み 込まれます。

パラメータ

filename

ファイル名を指定します

mode

fopen() と同じ (rb または wb) ですが、 圧縮レベル (wb9) または圧縮の方策、 つまり、wb6f のようにフィルターを通したデータを f で指定したり、h でハフマン圧縮のみを行うことを指定したりすることができます (方策に関するパラメータの詳細については、zlib.h の中の deflateInit2 の説明を参照ください)。

use_include_path

このオプションパラメータを 1 にすることにより、 include_pathにあるファイルも 検索することができます。

戻り値

オープンしたファイルへのファイルポインタを返します。その後、 このファイルディスクプリタから読み込んだ全ては透過的に解凍され、 書き込んだものは圧縮されます。

オープンに失敗した場合、この関数は false を返します。

例

例1 gzopen() の例

<?php
$fp = gzopen("/tmp/file.gz", "r");
?>

参考

  • gzclose() - 開かれたgzファイルへのポインタを閉じる


gzファイルへのポインタから残りのデータ全部を出力する

  • ≪ gzopen
  • gzputs ≫
  • PHP Manual
  • Zlib 関数
  • gzファイルへのポインタから残りのデータ全部を出力する

gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — gzファイルへのポインタから残りのデータ全部を出力する

説明

gzpassthru(resource $stream): int

gz ファイルポインタについて現在位置から EOF までデータを読み込み、 標準出力に (伸長された) 結果を書き込みます。

注意:

すでにデータをファイルに書き込んでいる場合、 ファイルポインタをファイルの先頭にセットするために gzrewind() をコールする必要があるかも知れません。

ヒント

修正や特定のオフセットへの移動なしに ファイルの内容を出力バッファにダンプしたいだけの場合、 readgzfile() 関数を使用することもできます。 これにより、gzopen() をコールする手間を省くことができます。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

戻り値

gz から読み込んで解凍され、入力に渡された文字数。

例

例1 gzpassthru() の例

<?php
$fp = gzopen('file.gz', 'r');
gzpassthru($fp);
gzclose($fp);
?>


gzwrite のエイリアス

  • ≪ gzpassthru
  • gzread ≫
  • PHP Manual
  • Zlib 関数
  • gzwrite のエイリアス

gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — gzwrite() のエイリアス

説明

この関数は次の関数のエイリアスです。 gzwrite().


バイナリ対応のgzファイル読み込み

  • ≪ gzputs
  • gzrewind ≫
  • PHP Manual
  • Zlib 関数
  • バイナリ対応のgzファイル読み込み

gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — バイナリ対応のgzファイル読み込み

説明

gzread(resource $stream, int $length): string|false

gzread() は、最大 length バイトのデータを zp が指す gz ファイルポインタ から読み込みます。(伸長された) length バイトのデータが読み込まれたか、 EOF に達したとき、読み込みは終了します。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

length

読み込むバイト数を指定します。

戻り値

読み込まれたデータ。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | この関数は、失敗時に false を返すようになりました。 これより前のバージョンでは、0 を返していました。

例

例1 gzread() の例

<?php
// gz ファイルの内容を文字列に読み込む
$filename = "/usr/local/something.txt.gz";
$zd = gzopen($filename, "r");
$contents = gzread($zd, 10000);
gzclose($zd);
?>

参考

  • gzwrite() - バイナリセーフな gz ファイル書き込み
  • gzopen() - gz ファイルを開く
  • gzgets() - ファイルポインタから 1 行を得る
  • gzgetss() - gzファイルへのポインタから1行を得て、HTMLタグを取り除く
  • gzfile() - gzファイル全体を配列に読み込む
  • gzpassthru() - gzファイルへのポインタから残りのデータ全部を出力する


gz ファイルポインタの示す位置を元に戻す

  • ≪ gzread
  • gzseek ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタの示す位置を元に戻す

gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — gz ファイルポインタの示す位置を元に戻す

説明

gzrewind(resource $stream): bool

与えられた gz ファイルポインタが指すファイルのファイル位置記述子を、 ファイルストリームの先頭にセットします。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • gzseek() - gz ファイルポインタの位置を移動する
  • gztell() - gz ファイルポインタの読み込み/書き込み位置を返します


gz ファイルポインタの位置を移動する

  • ≪ gzrewind
  • gztell ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタの位置を移動する

gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — gz ファイルポインタの位置を移動する

説明

gzseek(resource $stream, int $offset, int $whence = SEEK_SET): int

与えられたファイルポインタが指すファイルのファイル位置記述子を、 ファイルストリーム上の与えられた offset バイトにセットします。 gzseek(zp, offset, SEEK_SET) を (C 言語において) コールするのと同じです。

ファイルが読み込み用にオープンされた場合、この関数は、 エミュレーションされますが、極端に遅くなる可能性があります。 ファイルを書き込み用にオープンした場合、 前方への移動のみがサポートされます。この場合、gzseek() は、新しい開始位置までゼロの並びのデータを圧縮します。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

offset

移動するオフセットを指定します。

whence

whence の値は次のいずれかです。

  • SEEK_SET - offset バイト目に設定します。
  • SEEK_CUR - 現在位置から offset ぶん進んだ位置に設定します。

whence を省略した場合は SEEK_SET とみなします。

戻り値

成功した場合、0を返します。それ以外の場合は、-1を返します。 移動がEOFを超える場合にもエラーは発生しないことに注意してください。

例

例1 gzseek() の例

<?php
$gz = gzopen('somefile.gz', 'r');
gzseek($gz,2);
echo gzgetc($gz);
gzclose($gz);
?>

参考

  • gztell() - gz ファイルポインタの読み込み/書き込み位置を返します
  • gzrewind() - gz ファイルポインタの示す位置を元に戻す


gz ファイルポインタの読み込み/書き込み位置を返します

  • ≪ gzseek
  • gzuncompress ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルポインタの読み込み/書き込み位置を返します

gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — gz ファイルポインタの読み込み/書き込み位置を返します

説明

gztell(resource $stream): int|false

与えられたファイルポインタが指す位置、つまり、 圧縮されていないファイルストリームにおけるオフセット値を返します。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

戻り値

ファイルポインタの位置、もしくはエラーが発生した場合 false

参考

  • gzopen() - gz ファイルを開く
  • gzseek() - gz ファイルポインタの位置を移動する
  • gzrewind() - gz ファイルポインタの示す位置を元に戻す


圧縮された文字列を解凍する

  • ≪ gztell
  • gzwrite ≫
  • PHP Manual
  • Zlib 関数
  • 圧縮された文字列を解凍する

gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — 圧縮された文字列を解凍する

説明

gzuncompress(string $data, int $max_length = 0): string|false

この関数は圧縮された文字列を解凍します。

パラメータ

data

gzcompress() によって圧縮されたデータを指定します。

max_length

デコードするデータの最大長を指定します。

戻り値

オリジナルの無圧縮なデータ、もしくはエラー時に false

この関数は、もし無圧縮なデータが圧縮された入力 data の 32768 倍、もしくはオプションのパラメータ max_length 以上の場合、エラーを返します。

例

例1 gzuncompress() の例

<?php
$compressed = gzcompress('Compress me', 9);
$uncompressed = gzuncompress($compressed);
echo $uncompressed;
?>

参考

  • gzcompress() - 文字列を圧縮する
  • gzinflate() - deflate圧縮された文字列を解凍する
  • gzdeflate() - 文字列を deflate 圧縮する
  • gzencode() - gzip 圧縮された文字列を作成する


バイナリセーフな gz ファイル書き込み

  • ≪ gzuncompress
  • inflate_add ≫
  • PHP Manual
  • Zlib 関数
  • バイナリセーフな gz ファイル書き込み

gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — バイナリセーフな gz ファイル書き込み

説明

gzwrite(resource $stream, string $data, ?int $length = null): int|false

gzwrite() は data の内容を与えられた gz ファイルに書き込みます。

パラメータ

stream

gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

data

書き込む文字列を指定します。

length

書き込む解凍されたバイト数を指定します。 もし指定された場合、 length バイトのデータが書き込まれたか、 data の終わりに達した時に 書き込みは終了します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。 これより前のバージョンでは、デフォルト値は 0 でした。
7.4.0 | この関数は、失敗時に false を返すようになりました。 これより前のバージョンでは、0 を返していました。

戻り値

与えられた gz ファイルストリームに書き込まれた (解凍された) バイト数を返します。失敗した場合に false を返します

例

例1 gzwrite() の例

<?php
$string = 'Some information to compress';
$gz = gzopen('somefile.gz','w9');
gzwrite($gz, $string);
gzclose($gz);
?>

参考

  • gzread() - バイナリ対応のgzファイル読み込み
  • gzopen() - gz ファイルを開く


インクリメンタルにエンコードされたデータを解凍する

  • ≪ gzwrite
  • inflate_get_read_len ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルにエンコードされたデータを解凍する

inflate_add

(PHP 7, PHP 8)

inflate_add — インクリメンタルにエンコードされたデータを解凍する

説明

inflate_add(InflateContext $context, string $data, int $flush_mode = ZLIB_SYNC_FLUSH): string|false

指定された context でエンコードされたデータをインクリメンタルに解凍します。

制限: GZIP 圧縮されたデータからは、ヘッダ情報は利用できません。

パラメータ

context

inflate_init() で作られたコンテクスト

data

圧縮されたデータのチャンク

flush_mode

ZLIB_BLOCK, ZLIB_NO_FLUSH, ZLIB_PARTIAL_FLUSH, ZLIB_SYNC_FLUSH (デフォルト), ZLIB_FULL_FLUSH, ZLIB_FINISH のいずれか。 通常は、圧縮率を最大にするために、 ZLIB_NO_FLUSH を指定するでしょうし、 データの最後のチャンクで終了させるために ZLIB_FINISH を指定するでしょう。 これらの定数の詳細な説明は » zlib manual を参照ください。

戻り値

解凍されたデータのチャンクを返します。 失敗した場合に false を返します

エラー / 例外

不正な引数が与えられた場合、データの解凍にはあらかじめ設定された辞書が必要なのに 何も指定されなかった場合、圧縮データが壊れていたり、不正なチェックサムだった場合、 エラーレベル E_WARNING が生成されます。

変更履歴

バージョン | 説明
8.0.0 | context は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • inflate_init() - インクリメンタルな解凍コンテキストを初期化する


これまでに読み取ったバイト数を得る

  • ≪ inflate_add
  • inflate_get_status ≫
  • PHP Manual
  • Zlib 関数
  • これまでに読み取ったバイト数を得る

inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — これまでに読み取ったバイト数を得る

説明

inflate_get_read_len(InflateContext $context): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

context

戻り値

これまでに読み取ったバイト数を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | context は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。


解凍の状態を取得する

  • ≪ inflate_get_read_len
  • inflate_init ≫
  • PHP Manual
  • Zlib 関数
  • 解凍の状態を取得する

inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — 解凍の状態を取得する

説明

inflate_get_status(InflateContext $context): int

通常 ZLIB_OK か ZLIB_STREAM_END を返します。

パラメータ

context

戻り値

解凍の状態を返します。

変更履歴

バージョン | 説明
8.0.0 | context は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。


インクリメンタルな解凍コンテキストを初期化する

  • ≪ inflate_get_status
  • ob_gzhandler ≫
  • PHP Manual
  • Zlib 関数
  • インクリメンタルな解凍コンテキストを初期化する

inflate_init

(PHP 7, PHP 8)

inflate_init — インクリメンタルな解凍コンテキストを初期化する

説明

inflate_init(int $encoding, array $options = []): InflateContext|false

指定された encoding でインクリメンタルな解凍コンテキストを初期化します

パラメータ

encoding

定数 ZLIB_ENCODING_* のうちのひとつ

options

次の要素を含む連想配列:

level

-1 .. 9 までの圧縮レベル。デフォルトは -1 です。

memory

1 .. 9 までの圧縮メモリレベル。デフォルトは8です。

window

8 .. 15 までの zlib の window サイズ(対数)。 デフォルトは 15 です。

strategy

ZLIB_FILTERED, ZLIB_HUFFMAN_ONLY, ZLIB_RLE, ZLIB_FIXED, ZLIB_DEFAULT_STRATEGY (デフォルト) のうちのひとつです。

dictionary

あらかじめ設定されたディクショナリの string または strings の array。 (デフォルト: 辞書なし)

戻り値

成功した場合、解凍コンテキストリソース(zlib.inflate) を返します。 失敗した場合に false を返します

エラー / 例外

不正なオプションが options に渡されたり、 コンテキストが作れなかった場合には、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は InflateContext クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

注意

警告

gzinflate() と異なり、 インクリメンタルな解凍コンテキストは、 解凍済みデータの大きさを強制しません。 よって、Zip爆弾を自動的に防御できません。

参考

  • inflate_add() - インクリメンタルにエンコードされたデータを解凍する
  • deflate_init() - インクリメンタルな圧縮コンテキストを初期化する


出力バッファを gzip 圧縮するための ob_start コールバック関数

  • ≪ inflate_init
  • readgzfile ≫
  • PHP Manual
  • Zlib 関数
  • 出力バッファを gzip 圧縮するための ob_start コールバック関数

ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数

説明

ob_gzhandler(string $data, int $flags): string|false

ob_gzhandler() は ob_start() 用のコールバック関数として使用されることを意図したもので、 圧縮されたページをサポートしている web ブラウザに対して gz エンコードされたデータを送信することを容易にします。 ob_gzhandler() は 実際に圧縮されたデータを送信する前にブラウザがサポートする content encoding の種類("gzip"、"deflate" またはなし)を調べ、それに基づいて 出力を返します。すべてのブラウザがサポートされています。 というのも、ブラウザは、 自分が圧縮されたページをサポートするかどうかを表す 適切なヘッダを送信することになっているからです。 圧縮されたページをブラウザがサポートしていない場合、 この関数は false を返します。

パラメータ

data

flags

戻り値

例

例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() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする


gz ファイルを出力する

  • ≪ ob_gzhandler
  • zlib_decode ≫
  • PHP Manual
  • Zlib 関数
  • gz ファイルを出力する

readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — gz ファイルを出力する

説明

readgzfile(string $filename, int $use_include_path = 0): int|false

ファイルを読み込み、解凍し、標準出力に書き込みます。

readgzfile()は、gzip フォーマットでないファイルの読込にも使用可能です。この場合、 readgzfile() はファイルを解凍せずに直接読込みます。

パラメータ

filename

ファイル名を指定します。このファイルはファイルシステムからオープンされ、 内容は標準出力に書き込まれます。

use_include_path

include_path にあるファイルも検索したい場合、このオプションパラメータを 1 に設定してください。

戻り値

成功時は、ファイルから読み込んだ (解凍された) データのバイト数を返します。 失敗した場合に false を返します

エラー / 例外

失敗したときは E_WARNING が発生します。

参考

  • gzpassthru() - gzファイルへのポインタから残りのデータ全部を出力する
  • gzfile() - gzファイル全体を配列に読み込む
  • gzopen() - gz ファイルを開く


raw/gzip/zlib で符号化されたデータを復元する

  • ≪ readgzfile
  • zlib_encode ≫
  • PHP Manual
  • Zlib 関数
  • raw/gzip/zlib で符号化されたデータを復元する

zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — raw/gzip/zlib で符号化されたデータを復元する

説明

zlib_decode(string $data, int $max_length = 0): string|false

raw/gzip/zlib で符号化されたデータを復元します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

max_length

戻り値

圧縮されていないデータを返します。失敗した場合に false を返します。

参考

  • zlib_encode() - 指定した符号化方式でデータを圧縮する


指定した符号化方式でデータを圧縮する

  • ≪ zlib_decode
  • zlib_get_coding_type ≫
  • PHP Manual
  • Zlib 関数
  • 指定した符号化方式でデータを圧縮する

zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — 指定した符号化方式でデータを圧縮する

説明

zlib_encode(string $data, int $encoding, int $level = -1): string|false

指定した符号化方式でデータを圧縮します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

圧縮するデータ。

encoding

圧縮アルゴリズム。 ZLIB_ENCODING_RAW、 ZLIB_ENCODING_DEFLATE または ZLIB_ENCODING_GZIP 。

level

戻り値

例

例1 zlib_encode() の例

<?php
$str = 'hello world';
$enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
echo bin2hex($enc);
?>

上の例の出力は以下となります。

789ccb48cdc9c95728cf2fca4901001a0b045d

参考

  • zlib_decode() - raw/gzip/zlib で符号化されたデータを復元する


出力圧縮に使用されたコーディングの種類を返す

  • ≪ zlib_encode
  • DeflateContext ≫
  • PHP Manual
  • Zlib 関数
  • 出力圧縮に使用されたコーディングの種類を返す

zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す

説明

zlib_get_coding_type(): string|false

出力圧縮に使用されたコーディングの種類を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

返される値は gzip, deflate, もしくは false です。

参考

  • zlib.output_compression ディレクティブ


DeflateContext クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 zlib.deflate リソースを置き換える完全不透明クラスです。

クラス概要

final class DeflateContext {
}


InflateContext クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 zlib.inflate リソースを置き換える完全不透明クラスです。

クラス概要

final class InflateContext {
}


暗号

  • Hash — HASH メッセージダイジェストフレームワーク
    • はじめに
    • インストール/設定
    • 定義済み定数
    • HashContext — HashContext クラス
    • Hash 関数
  • Mcrypt
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Mcrypt 暗号
    • Mcrypt 関数
  • Mhash
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Mhash 関数
  • OpenSSL
    • はじめに
    • インストール/設定
    • 定義済み定数
    • キー/証明書パラメータ
    • 証明書の認証
    • OpenSSL 関数
    • OpenSSLCertificate — OpenSSLCertificate クラス
    • OpenSSLCertificateSigningRequest — OpenSSLCertificateSigningRequest クラス
    • OpenSSLAsymmetricKey — OpenSSLAsymmetricKey クラス
  • パスワードのハッシュ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Password Hashing 関数
  • Rnp
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Rnp 関数
    • RnpFFI — The RnpFFI class
  • Sodium
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Sodium 関数
    • SodiumException — SodiumException クラス


HASH メッセージダイジェストフレームワーク

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • HashContext — HashContext クラス
    • HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません
    • HashContext::__serialize — HashContext オブジェクトをシリアライズする
    • HashContext::__unserialize — data を HashContext オブジェクト に復元する
  • Hash 関数
    • hash — ハッシュ値 (メッセージダイジェスト) を生成する
    • hash_algos — 登録されているハッシュアルゴリズムの一覧を返す
    • hash_copy — ハッシュコンテキストをコピーする
    • hash_equals — タイミング攻撃に対しても安全な文字列比較
    • hash_file — ファイルの内容から、ハッシュ値を生成する
    • hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
    • hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する
    • hash_hmac — HMAC 方式を使用してハッシュ値を生成する
    • hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す
    • hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
    • hash_init — 段階的なハッシュコンテキストを初期化する
    • hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する
    • hash_update — アクティブなハッシュコンテキストにデータを投入する
    • hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する
    • hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する


はじめに

この拡張モジュールは、様々なハッシュアルゴリズムを使って任意の長さのメッセージを直接、または徐々に処理する関数を提供します。可能な処理には、たとえば HMAC 値の生成や、HKDF や PBKDF2 を含む、鍵の導出処理があります。

ハッシュアルゴリズムには、大きく分けて3つのカテゴリがあります。完全な一覧は hash_algos() を参照ください。

  • チェックサムアルゴリズム(例: "crc32b", "adler32"): 通信エラーを検出するときなどに役立つチェックサムを計算するのに使えます。これらは大抵、とても高速です。また、衝突したり、容易に"推測可能な" 値を生成できたりするので、暗号には完全に不向きです。
  • 非暗号化アルゴリズム(例:xxHash ファミリ): ハッシュテーブルで使うハッシュ値を計算するのに用いられます。よって、任意の文字列の入力に対して、うまく分散したハッシュ値を生成するように設計されています。これらも一般的に高速ですが、暗号化の処理には向いていません。
  • 暗号化アルゴリズム(例:SHA-2 ファミリ): 入力そのものを表現するものの、それが推測できず、かつ衝突もしにくいハッシュ値を生成するように設計されています。パフォーマンスは二の次とされていますが、モダンなハードウェアはこれらのアルゴリズムの処理を特別に支援するものがあり、PHP も利用可能なときはそれらを使おうとします。 NIST の Computer Security Resource Center には、 » アメリカの連邦通信処理規格(FIPS) が現在認定しているアルゴリズムの説明 があります。
    警告

    "md4" "md5", "sha1" のような 初期の暗号化アルゴリズムの中には、既に衝突しやすいことが証明されているものがあります。こうしたアルゴリズムを使うことは、暗号を用いるアプリケーションでは既に推奨されません。

パスワードを処理する際にハッシュ関数を使うためのベストプラクティスに関する情報は、パスワードのハッシュに関するFAQ も参照ください。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Hash
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

PHP 5.1.2 以降、ハッシュ拡張モジュールは本体にバンドルされ、デフォルトでコンパイルされるようになります。

configure 時に --disable-hash を指定することで明示的に無効にすることも可能です。それ以前の バージョンの PHP にハッシュ拡張モジュールを組み込むには、 » PECL モジュール

PHP 7.4.0 以降、ハッシュ拡張モジュールはコア PHP 拡張モジュールとなり、常に有効になります。


リソース型

この拡張モジュールでは、ハッシュコンテキストリソースを定義しています。これは hash_init() が返すものです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

HASH_HMAC (int)
hash_init() のオプションのフラグです。 現在のハッシュコンテキストに対して HMAC digest-keying アルゴリズムが適用されることを示します。


HashContext クラス

(PHP 7 >= 7.2.0, PHP 8)

はじめに

クラス概要

final class HashContext {
/* メソッド */
private __construct()
public __serialize(): array
public __unserialize(array $data): void
}

目次

  • HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません
  • HashContext::__serialize — HashContext オブジェクトをシリアライズする
  • HashContext::__unserialize — data を HashContext オブジェクト に復元する


private なコンストラクタのため、直接インスタンス化できません

  • ≪ HashContext
  • HashContext::__serialize ≫
  • PHP Manual
  • HashContext
  • private なコンストラクタのため、直接インスタンス化できません

HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません

説明

private HashContext::__construct()

パラメータ

この関数にはパラメータはありません。


HashContext オブジェクトをシリアライズする

  • ≪ HashContext::__construct
  • HashContext::__unserialize ≫
  • PHP Manual
  • HashContext
  • HashContext オブジェクトをシリアライズする

HashContext::__serialize

(PHP 8)

HashContext::__serialize — HashContext オブジェクトをシリアライズする

説明

public HashContext::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


data を HashContext オブジェクト に復元する

  • ≪ HashContext::__serialize
  • Hash 関数 ≫
  • PHP Manual
  • HashContext
  • data を HashContext オブジェクト に復元する

HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — data を HashContext オブジェクト に復元する

説明

public HashContext::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

アンシリアライズする値。

戻り値

値を返しません。


Hash 関数

目次

  • hash — ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_algos — 登録されているハッシュアルゴリズムの一覧を返す
  • hash_copy — ハッシュコンテキストをコピーする
  • hash_equals — タイミング攻撃に対しても安全な文字列比較
  • hash_file — ファイルの内容から、ハッシュ値を生成する
  • hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
  • hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する
  • hash_hmac — HMAC 方式を使用してハッシュ値を生成する
  • hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す
  • hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
  • hash_init — 段階的なハッシュコンテキストを初期化する
  • hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する
  • hash_update — アクティブなハッシュコンテキストにデータを投入する
  • hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する
  • hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する


ハッシュ値 (メッセージダイジェスト) を生成する

  • ≪ Hash 関数
  • hash_algos ≫
  • PHP Manual
  • Hash 関数
  • ハッシュ値 (メッセージダイジェスト) を生成する

hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — ハッシュ値 (メッセージダイジェスト) を生成する

説明

hash(
string $algo,
string $data,
bool $binary = false,
array $options = []
): string

パラメータ

algo

選択したアルゴリズムの名前 (例: "sha256")。 サポートされているアルゴリズムの一覧は hash_algos() を参照ください。

data

ハッシュするメッセージ。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

options

様々なハッシュアルゴリズム向けの、オプションの配列。 現状は、MurmurHash バリアントが "seed" だけをサポートしています。

戻り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

変更履歴

バージョン | 説明
8.1.0 | options パラメータが追加されました。
8.0.0 | hash() は、 algo が未知の場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。

例

例1 hash() の例

<?php
echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');
?>

上の例の出力は以下となります。

68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_file() - ファイルの内容から、ハッシュ値を生成する
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する


登録されているハッシュアルゴリズムの一覧を返す

  • ≪ hash
  • hash_copy ≫
  • PHP Manual
  • Hash 関数
  • 登録されているハッシュアルゴリズムの一覧を返す

hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — 登録されているハッシュアルゴリズムの一覧を返す

説明

hash_algos(): array

パラメータ

この関数にはパラメータはありません。

戻り値

サポートされているハッシュアルゴリズムの一覧を、数値添字の 配列として返します。

変更履歴

バージョン | 説明
8.1.0 | MurmurHash3 と xxHash のサポートを追加しました。
7.4.0 | crc32c のサポートを追加しました。
7.1.0 | sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 および sha3-512 のサポートを追加しました。

例

例1 hash_algos() の例

PHP 8.1.0 では、hash_algos() は 以下のようなアルゴリズム名の一覧を返します。

<?php
print_r(hash_algos());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512/224
    [8] => sha512/256
    [9] => sha512
    [10] => sha3-224
    [11] => sha3-256
    [12] => sha3-384
    [13] => sha3-512
    [14] => ripemd128
    [15] => ripemd160
    [16] => ripemd256
    [17] => ripemd320
    [18] => whirlpool
    [19] => tiger128,3
    [20] => tiger160,3
    [21] => tiger192,3
    [22] => tiger128,4
    [23] => tiger160,4
    [24] => tiger192,4
    [25] => snefru
    [26] => snefru256
    [27] => gost
    [28] => gost-crypto
    [29] => adler32
    [30] => crc32
    [31] => crc32b
    [32] => crc32c
    [33] => fnv132
    [34] => fnv1a32
    [35] => fnv164
    [36] => fnv1a64
    [37] => joaat
    [38] => murmur3a
    [39] => murmur3c
    [40] => murmur3f
    [41] => xxh32
    [42] => xxh64
    [43] => xxh3
    [44] => xxh128
    [45] => haval128,3
    [46] => haval160,3
    [47] => haval192,3
    [48] => haval224,3
    [49] => haval256,3
    [50] => haval128,4
    [51] => haval160,4
    [52] => haval192,4
    [53] => haval224,4
    [54] => haval256,4
    [55] => haval128,5
    [56] => haval160,5
    [57] => haval192,5
    [58] => haval224,5
    [59] => haval256,5
)

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • hash_hmac_algos() - hash_hmac に合うハッシュアルゴリズムの一覧を返す


ハッシュコンテキストをコピーする

  • ≪ hash_algos
  • hash_equals ≫
  • PHP Manual
  • Hash 関数
  • ハッシュコンテキストをコピーする

hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — ハッシュコンテキストをコピーする

説明

hash_copy(HashContext $context): HashContext

パラメータ

context

hash_init() が返すハッシュコンテキスト。

戻り値

ハッシュコンテキストのコピーを返します。

変更履歴

バージョン | 説明
7.2.0 | リソースのかわりに、HashContext を受け入れ、返すようになりました。

例

例1 hash_copy() の例

<?php
$context = hash_init("sha256");
hash_update($context, "The quick brown fox ");

/* コンテキストをコピーし、それを使えるようにします */
$copy_context = hash_copy($context);

echo hash_final($context), "\n";

hash_update($copy_context, "jumped over the lazy dog.");
echo hash_final($copy_context), "\n";
?>

上の例の出力は以下となります。

b29d66e56ed90cce9b0165c43fedec612b60a071974d8be4513e18580d55b5bd
68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483


タイミング攻撃に対しても安全な文字列比較

  • ≪ hash_copy
  • hash_file ≫
  • PHP Manual
  • Hash 関数
  • タイミング攻撃に対しても安全な文字列比較

hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — タイミング攻撃に対しても安全な文字列比較

説明

hash_equals(#[\SensitiveParameter] string $known_string, #[\SensitiveParameter] string $user_string): bool

実行している間に known_string の内容を漏らすことなく、 ふたつの文字列が等しいかどうかを調べます。

この関数は、タイミング攻撃を緩和する目的で使えます。 === を用いた通常の比較は、値が異なるかどうかや、 値が最初に異なる位置に応じて、比較に多少時間がかかります。 よって、その間に秘密の known_string の内容が漏洩してしまいます。

警告

最初のパラメータよりはむしろ、 2つ目の文字列をユーザーが指定することが重要です。

パラメータ

known_string

秘密にしておく必要がある、既知の文字列

user_string

ユーザーが指定する、比較対象の文字列

戻り値

ふたつの文字列が等しい場合に true を返します。 そうでない場合に、false を返します。

例

例1 hash_equals() の例

<?php
$secretKey = '8uRhAeH89naXfFXKGOEj';

// $value と $signature の値はユーザが提供します。
// 例: URL内の値と、$_GET から取得した値です
$value = 'username=rasmuslerdorf';
$signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
echo "The value is correctly signed.", PHP_EOL;
} else {
echo "The value was tampered with.", PHP_EOL;
}
?>

上の例の出力は以下となります。

The value is correctly signed.

注意

注意:

指定するパラメータは両方、長さが等しくなければいけません。 違う長さの文字列が指定されると、この関数はすぐに false を返すので、 タイミング攻撃が行われた場合に既知の文字列の長さが漏洩するかもしれません。

参考

  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する


ファイルの内容から、ハッシュ値を生成する

  • ≪ hash_equals
  • hash_final ≫
  • PHP Manual
  • Hash 関数
  • ファイルの内容から、ハッシュ値を生成する

hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — ファイルの内容から、ハッシュ値を生成する

説明

hash_file(
string $algo,
string $filename,
bool $binary = false,
array $options = []
): string|false

パラメータ

algo

選択したアルゴリズムの名前 (例: "sha256")。 サポートされているアルゴリズムの一覧は hash_algos() を参照ください。

filename

ハッシュ対象となるファイルの位置を示す URL。 fopen() ラッパーをサポートしています。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

options

様々なハッシュアルゴリズム向けの、オプションの配列。 現状は、MurmurHash バリアントが "seed" だけをサポートしています。

戻り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

変更履歴

バージョン | 説明
8.1.0 | options パラメータが追加されました。

例

例1 hash_file() の使用例

<?php
/* ハッシュ値を計算するファイルを作成します */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

echo hash_file('sha256', 'example.txt');
?>

上の例の出力は以下となります。

68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_hmac_file() - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する


段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

  • ≪ hash_file
  • hash_hkdf ≫
  • PHP Manual
  • Hash 関数
  • 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

説明

hash_final(HashContext $context, bool $binary = false): string

パラメータ

context

hash_init() が返すハッシュコンテキスト。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

戻り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

変更履歴

バージョン | 説明
7.2.0 | リソースの代わりに、HashContext を受け入れるようになりました。

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update() - アクティブなハッシュコンテキストにデータを投入する
  • hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する


与えられたキーから導出されるHKDFキーを生成する

  • ≪ hash_final
  • hash_hmac ≫
  • PHP Manual
  • Hash 関数
  • 与えられたキーから導出されるHKDFキーを生成する

hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する

説明

hash_hkdf(
string $algo,
#[\SensitiveParameter] string $key,
int $length = 0,
string $info = "",
string $salt = ""
): string

パラメータ

algo

選択したハッシュアルゴリズムの名前 (例: "sha256")。 サポートされているアルゴリズムの一覧は hash_hmac_algos() を参照ください。

注意:

暗号に適さないハッシュ関数は許可されません。

key

入力キー (生のバイナリ)。 空ではいけません。

length

出力の長さをバイト単位で指定します。 選んだハッシュ関数のサイズの255倍以下でなければなりません。

length が 0 の場合、 出力の長さはハッシュ関数が選んだデフォルトのサイズになります。

info

アプリケーション/コンテキスト依存の情報を示す文字列

salt

導出の間に使うソルト

この値はオプションですが、 ランダムなソルトを追加するとHKDFの強度が飛躍的に向上します。

戻り値

導出されたキーの生バイナリ表現の文字列を返します(この値は、 出力キーマテリアル(OKM) としても知られています)。 失敗時には false を返します。

エラー / 例外

key が空の場合だったり、 algo が未知だったり/暗号に適さなかったり、 length が0より小さいか大きすぎる (ハッシュ関数のサイズの255倍より大きい)場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | エラーが発生した場合に ValueError をスローするようになりました。 これより前のバージョンでは、 false を返し、かつ E_WARNING が発生していました。

例

例1 hash_hkdf() の例

<?php
// ランダムなキーと、導出するキーを強力にするためのソルトを生成します。
$inputKey = random_bytes(32);
$salt = random_bytes(16);

// 上で生成した同じ入力を使い、異なるキーのペアを導出します。
$encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
$authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

var_dump($encryptionKey !== $authenticationKey); // bool(true)
?>

上の例は、AES-256 encryption と SHA-256 authentication をそれぞれ使い、 encrypt-then-HMAC を生成する用途に合った、 異なるキーペアを生成します。

参考

  • hash_pbkdf2() - PBKDF2 を使ってパスワードからキーを生成する
  • » RFC 5869
  • » userland implementation


HMAC 方式を使用してハッシュ値を生成する

  • ≪ hash_hkdf
  • hash_hmac_algos ≫
  • PHP Manual
  • Hash 関数
  • HMAC 方式を使用してハッシュ値を生成する

hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — HMAC 方式を使用してハッシュ値を生成する

説明

hash_hmac(
string $algo,
string $data,
#[\SensitiveParameter] string $key,
bool $binary = false
): string

パラメータ

algo

選択したアルゴリズムの名前 (例: "sha256")。 サポートするアルゴリズムの一覧は hash_hmac_algos() を参照ください。

注意:

暗号に適さないハッシュ関数は許可されません。

data

ハッシュするメッセージ。

key

HMAC 方式でのメッセージダイジェストを生成するために使用する 共有の秘密鍵。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

戻り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

エラー / 例外

algo が不明な場合や、 暗号に適さないハッシュ関数の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | algo が不明な場合や、 暗号に適さないハッシュ関数の場合に ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
7.2.0 | 暗号に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_hmac() の例

<?php
echo hash_hmac('sha256', 'The quick brown fox jumped over the lazy dog.', 'secret');
?>

上の例の出力は以下となります。

9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

参考

  • hash_hmac_algos() - hash_hmac に合うハッシュアルゴリズムの一覧を返す
  • hash_hmac_file() - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
  • hash_equals() - タイミング攻撃に対しても安全な文字列比較


hash_hmac に合うハッシュアルゴリズムの一覧を返す

  • ≪ hash_hmac
  • hash_hmac_file ≫
  • PHP Manual
  • Hash 関数
  • hash_hmac に合うハッシュアルゴリズムの一覧を返す

hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す

説明

hash_hmac_algos(): array

パラメータ

この関数にはパラメータはありません。

戻り値

数値インデックスをキーとし、 hash_hmac() に合う、 サポートされたハッシュアルゴリズムの一覧を値とした配列を返します。

例

例1 hash_hmac_algos() の例

<?php
print_r(hash_hmac_algos());

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => md2
    [1] => md4
    [2] => md5
    [3] => sha1
    [4] => sha224
    [5] => sha256
    [6] => sha384
    [7] => sha512/224
    [8] => sha512/256
    [9] => sha512
    [10] => sha3-224
    [11] => sha3-256
    [12] => sha3-384
    [13] => sha3-512
    [14] => ripemd128
    [15] => ripemd160
    [16] => ripemd256
    [17] => ripemd320
    [18] => whirlpool
    [19] => tiger128,3
    [20] => tiger160,3
    [21] => tiger192,3
    [22] => tiger128,4
    [23] => tiger160,4
    [24] => tiger192,4
    [25] => snefru
    [26] => snefru256
    [27] => gost
    [28] => gost-crypto
    [29] => haval128,3
    [30] => haval160,3
    [31] => haval192,3
    [32] => haval224,3
    [33] => haval256,3
    [34] => haval128,4
    [35] => haval160,4
    [36] => haval192,4
    [37] => haval224,4
    [38] => haval256,4
    [39] => haval128,5
    [40] => haval160,5
    [41] => haval192,5
    [42] => haval224,5
    [43] => haval256,5
)

注意

注意:

PHP 7.2.0 より前のバージョンでは、 サポートされたハッシュアルゴリズムの一覧を取得する唯一の手段は、 hash_hmac() に合わないアルゴリズムも返してしまう hash_algos() を呼び出すことでした。

参考

  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_algos() - 登録されているハッシュアルゴリズムの一覧を返す


HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

  • ≪ hash_hmac_algos
  • hash_init ≫
  • PHP Manual
  • Hash 関数
  • HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

説明

hash_hmac_file(
string $algo,
string $filename,
#[\SensitiveParameter] string $key,
bool $binary = false
): string|false

パラメータ

algo

選択したアルゴリズムの名前 (例: "sha256")。 サポートするアルゴリズムの一覧は hash_hmac_algos() を参照ください。

注意:

暗号に適さないハッシュ関数は許可されません。

filename

ハッシュ対象となるファイルの位置を示す URL。 fopen ラッパーをサポートしています。

key

HMAC 方式でのメッセージダイジェストを生成するために使用する 共有の秘密鍵。

binary

true を設定すると、生のバイナリデータを出力します。 false の場合は小文字の 16 進数値となります。

戻り値

binary が true に設定されていない場合は、 メッセージダイジェストの計算結果を小文字の 16 進数値形式の文字列で 返します。もし true に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。 filename が読めない場合は、false が返されます。

エラー / 例外

algo が不明な場合や、 暗号に適さないハッシュ関数の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | algo が不明な場合や、 暗号に適さないハッシュ関数の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、false を返していました。
7.2.0 | 暗号に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_hmac_file() の例

<?php
/* ハッシュ値を計算するファイルを作成します */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');

echo hash_hmac_file('sha256', 'example.txt', 'secret');
?>

上の例の出力は以下となります。

9c5c42422b03f0ee32949920649445e417b2c634050833c5165704b825c2a53b

参考

  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • hash_hmac_algos() - hash_hmac に合うハッシュアルゴリズムの一覧を返す
  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_equals() - タイミング攻撃に対しても安全な文字列比較


段階的なハッシュコンテキストを初期化する

  • ≪ hash_hmac_file
  • hash_pbkdf2 ≫
  • PHP Manual
  • Hash 関数
  • 段階的なハッシュコンテキストを初期化する

hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — 段階的なハッシュコンテキストを初期化する

説明

hash_init(
string $algo,
int $flags = 0,
#[\SensitiveParameter] string $key = "",
array $options = []
): HashContext

パラメータ

algo

選択したアルゴリズムの名前 (例: "sha256")。 サポートされているアルゴリズムの一覧については、hash_algos() を参照ください。

注意:

HASH_HMAC フラグが指定されている場合、 暗号に適さないハッシュ関数は許可されません。

flags

ハッシュ生成の際に使用するオプションで、現在は、ただひとつ HASH_HMAC のみをサポートしています。これが 指定された場合、key を 必ず指定しなければなりません。

key

flags に HASH_HMAC が指定された場合に、HMAC 形式のハッシュで使用される共有の秘密鍵を 設定する必要があります。

options

様々なハッシュアルゴリズム向けの、オプションの配列。 現状は、MurmurHash バリアントが "seed" だけをサポートしています。

戻り値

hash_update()、
hash_update_stream()、hash_update_file()
および hash_final() で使用するハッシュコンテキストを
返します。

エラー / 例外

algo が不明な場合や、 暗号に適さないハッシュ関数の場合、 または key が空の場合に ValueError がスローされます。

変更履歴

バージョン | 説明
8.1.0 | options パラメータが追加されました。
8.0.0 | algo が不明な場合や、 暗号に適さないハッシュ関数の場合、 または key が空の場合に ValueError がスローされるようになりました。 これより前のバージョンでは、false を返し、 E_WARNING が発生していました。
7.2.0 | 暗号に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。
7.2.0 | リソースの代わりに HashContext を返すようになりました。

例

例1 段階的なハッシュの例

<?php
$hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

$ctx = hash_init('sha256');
hash_update($ctx, 'The quick brown fox ');
hash_update($ctx, 'jumped over the lazy dog.');
$incremental_hash = hash_final($ctx);

echo $incremental_hash, PHP_EOL;
var_dump($hash === $incremental_hash);
?>

上の例の出力は以下となります。

68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
bool(true)

参考

  • hash_algos() - 登録されているハッシュアルゴリズムの一覧を返す
  • hash_update() - アクティブなハッシュコンテキストにデータを投入する
  • hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する
  • hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す


PBKDF2 を使ってパスワードからキーを生成する

  • ≪ hash_init
  • hash_update ≫
  • PHP Manual
  • Hash 関数
  • PBKDF2 を使ってパスワードからキーを生成する

hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する

説明

hash_pbkdf2(
string $algo,
#[\SensitiveParameter] string $password,
string $salt,
int $iterations,
int $length = 0,
bool $binary = false,
array $options = []
): string

パラメータ

algo

ハッシュアルゴリズムの名前 (例: "sha256")。 サポートされるアルゴリズムの一覧は hash_hmac_algos() をご参照ください。

注意:

暗号に適さないハッシュ関数は許可されません。

password

派生に使うパスワード

salt

派生に使うソルト。ランダムに生成した値でなければいけません。

iterations

派生の実行の際の内部の反復回数

length

出力する文字列の長さ。binary が true の場合、これは派生キーのバイト長になります。 binary が false の場合、 これは派生キーのバイト長の二倍になります (キーの全バイトが十六進二桁で返されるからです)。

binary

true にセットされている場合、名前のバイナリデータが出力されます。false の場合、小文字の16進数が出力されます。

options

様々なハッシュアルゴリズム向けの、オプションの配列。 現状は、MurmurHash バリアントが "seed" だけをサポートしています。

戻り値

小文字の16進数を含む文字列が返されます。binary が true の場合、派生キーの生のバイナリ表現が返されます。

エラー / 例外

アルゴリズムが未知である場合、 iterations パラメータが 0 以下である場合、 length が 0 以下である場合、 salt が長すぎる場合 (INT_MAX - 4 よりも大きい) に、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | エラーが発生した場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、 false を返し、 E_WARNING が発生していました。
7.2.0 | 暗号の使用に適さないハッシュ関数 (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) は使えなくなりました。

例

例1 hash_pbkdf2() の基本的な使い方の例

<?php
$password = "password";
$iterations = 600000;

// Generate a cryptographically secure random salt using random_bytes()
$salt = random_bytes(16);

$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
var_dump($hash);

// for raw binary, the $length needs to be halved for equivalent results
$hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
var_dump(bin2hex($hash));?>

上の例の出力は、 たとえば以下のようになります。

string(20) "120fb6cffcf8b32c43e7"
string(20) "120fb6cffcf8b32c43e7"

注意

警告

PBKDF2 による方法はパスワードのハッシュを保存するために使うことができます。 しかし、password_hash() や crypt() で CRYPT_BLOWFISH を使うのほうが、パスワードの保存に適しています。

参考

  • password_hash() - パスワードハッシュを作る
  • hash_hkdf() - 与えられたキーから導出されるHKDFキーを生成する
  • sodium_crypto_pwhash() - Argon2 アルゴリズムを使い、パスワードからキーを導出する


アクティブなハッシュコンテキストにデータを投入する

  • ≪ hash_pbkdf2
  • hash_update_file ≫
  • PHP Manual
  • Hash 関数
  • アクティブなハッシュコンテキストにデータを投入する

hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — アクティブなハッシュコンテキストにデータを投入する

説明

hash_update(HashContext $context, string $data): true

パラメータ

context

hash_init() が返すハッシュコンテキスト。

data

ハッシュダイジェストに含めるメッセージ。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
7.2.0 | リソースの代わりに HashContext を受け入れるようになりました。

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する
  • hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す


アクティブなハッシュコンテキストに、ファイルからデータを投入する

  • ≪ hash_update
  • hash_update_stream ≫
  • PHP Manual
  • Hash 関数
  • アクティブなハッシュコンテキストに、ファイルからデータを投入する

hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する

説明

hash_update_file(HashContext $context, string $filename, ?resource $stream_context = null): bool

パラメータ

context

hash_init() が返すハッシュコンテキスト。

filename

ハッシュ対象となるファイルの位置を示す URL。 fopen() ラッパーをサポートしています。

stream_context

stream_context_create() が返す ストリームコンテキスト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | stream_context は、nullable になりました。
7.2.0 | リソースの代わりに HashContext を受け入れるようになりました。

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update() - アクティブなハッシュコンテキストにデータを投入する
  • hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
  • hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
  • hash_file() - ファイルの内容から、ハッシュ値を生成する


アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

  • ≪ hash_update_file
  • Mcrypt ≫
  • PHP Manual
  • Hash 関数
  • アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

説明

hash_update_stream(HashContext $context, resource $stream, int $length = -1): int

パラメータ

context

hash_init() が返すハッシュコンテキスト。

stream

ストリーム作成用の関数が返す、オープンしているファイルハンドル。

length

stream からハッシュコンテキストにコピーする 最大文字数。

戻り値

stream からハッシュコンテキストに追加された 実際のバイト数を返します。

変更履歴

バージョン | 説明
7.2.0 | リソースの代わりに HashContext を受け入れるようになりました。

例

例1 hash_update_stream() の例

<?php
$fp = tmpfile();
fwrite($fp, 'jumped over the lazy dog.');
rewind($fp);

$ctx = hash_init('sha256');
hash_update($ctx, 'The quick brown fox ');
hash_update_stream($ctx, $fp);
echo hash_final($ctx);
?>

上の例の出力は以下となります。

68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

参考

  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • hash_update() - アクティブなハッシュコンテキストにデータを投入する
  • hash_update_stream()
  • hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す


Mcrypt

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Mcrypt 暗号
  • Mcrypt 関数
    • mcrypt_create_iv — Creates an initialization vector (IV) from a random source
    • mcrypt_decrypt — Decrypts crypttext with given parameters
    • mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
    • mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
    • mcrypt_enc_get_iv_size — オープンされたアルゴリズムの IV の大きさを返す
    • mcrypt_enc_get_key_size — オープンされたモードでサポートされる最大キー長を返す
    • mcrypt_enc_get_modes_name — オープンされたモードの名前を返す
    • mcrypt_enc_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキー長を配列にして返す
    • mcrypt_enc_is_block_algorithm — オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる
    • mcrypt_enc_is_block_algorithm_mode — オープンされたモードの暗号がブロックモードで動作するかどうかを調べる
    • mcrypt_enc_is_block_mode — オープンされたモードがブロック出力を行うかどうかを調べる
    • mcrypt_enc_self_test — オープンしたモジュールのセルフテストを実行する
    • mcrypt_encrypt — 指定したパラメータでプレーンテキストを暗号化する
    • mcrypt_generic — データを暗号化する
    • mcrypt_generic_deinit — 暗号化モジュールを終了する
    • mcrypt_generic_init — 暗号化に必要な全てのバッファを初期化する
    • mcrypt_get_block_size — 指定した暗号のブロックサイズを得る
    • mcrypt_get_cipher_name — 指定した暗号の名前を得る
    • mcrypt_get_iv_size — 指定した暗号/モードの組み合わせに属する IV の大きさを返す
    • mcrypt_get_key_size — 指定した暗号のキーの長さを得る
    • mcrypt_list_algorithms — サポートされる全ての暗号を配列として取得する
    • mcrypt_list_modes — サポートされる全てのモードの配列を取得する
    • mcrypt_module_close — mcrypt モジュールを閉じる
    • mcrypt_module_get_algo_block_size — 指定したアルゴリズムのブロック長を返す
    • mcrypt_module_get_algo_key_size — オープンされたモードでサポートされる最大キー長を返す
    • mcrypt_module_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す
    • mcrypt_module_is_block_algorithm — 指定したアルゴリズムがブロックアルゴリズムであるかを調べる
    • mcrypt_module_is_block_algorithm_mode — 指定したモジュールがブロックアルゴリズムであるかどうかを返す
    • mcrypt_module_is_block_mode — 指定したモードがブロック出力を行うかどうかを返す
    • mcrypt_module_open — 使用するアルゴリズムおよびモードのモジュールをオープンする
    • mcrypt_module_self_test — 指定したモジュールのセルフテストを実行する
    • mdecrypt_generic — データを復号する


はじめに

警告

この機能は PHP 7.1.0 で 非推奨 となり、 PHP 7.2.0 で削除 されました。

この機能の代替として、これらが使えます。

  • Sodium (PHP 7.2.0から利用可能)
  • OpenSSL

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.2.0.

この関数は、CBC, OFB, CFB, ECB 暗号モードの DES, TripleDES, Blowfish (デフォルト), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 , GOST のような広範なブロックアルゴリズムをサポートする mcrypt ライブラリへのインターフェイスです。加えて、"フリーではない" とされている RC6 および IDEA もサポートします。 CFB 及び OFB は既定では 8bit です。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Mcrypt
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

ここで示す関数は、» mcrypt を 使用して動作します。この拡張モジュールを使用するには、» http://mcrypt.sourceforge.net/ から libmcrypt-x.x.tar.gz をダウンロードし、含まれているインストール用の指示に従ってください。

libmcrypt のバージョン 2.5.6 以降が必要です。

Windows ユーザーは、PHP 5.2 Windows 版バイナリに含まれているライブラリを使います。 PHP 5.3 の Windows 版バイナリには MCrypt ライブラリがスタティックに組み込まれているので、 DLL は不要です。

libmcrypt 2.4.x とリンクした場合、加えてブロックアルゴリズム: CAST, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT および次のストリーム暗号: ENIGMA (crypt), PANAMA, RC4, WAKE がサポートされます。 libmcrypt 2.4.x を使用した場合、暗号モード nOFB もサポートされます。


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.2.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mcrypt.


実行時設定

php.ini の設定により動作が変化します。

Mcrypt 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mcrypt.algorithms_dir | null | INI_ALL |
mcrypt.modes_dir | null | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mcrypt.algorithms_dir string

アルゴリズムが格納されているディレクトリ。 デフォルトは libmcrypt をコンパイルするときに指定した場所で、通常は /usr/local/lib/libmcrypt です。 詳細は mcrypt_list_algorithms() を参照ください。

mcrypt.modes_dir string

モードが格納されているディレクトリ。 デフォルトは libmcrypt をコンパイルするときに指定した場所で、通常は /usr/local/lib/libmcrypt です。 詳細は mcrypt_list_modes() を参照ください。


  • ≪ 実行時設定
  • 定義済み定数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型

mcrypt_module_open() は暗号記述子を返します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

mcryptは 4 つのブロック暗号モード(CBC, OFB, CFB, ECB)で実行可能です。 libmcrypt-2.4.x 以降にリンクした場合、ブロック暗号モード nOFG と STREAM モードでも実行可能です。MCRYPT_MODE_mode 形式を関数で使用する 際には、いくつかの制約があります。ここで、これらの各モードの通常の 使用法の概要を示します。詳細なリファレンスおよび議論に関しては、 Applied Cryptography by Schneier (ISBN 0-471-11709-9) を参照ください。

  • MCRYPT_MODE_ECB (electronic codebook) は、 一般的にはほとんどの用途に合わないブロック暗号モードです。 このモードを使うことは推奨しません。
  • MCRYPT_MODE_CBC (cipher block chaining)は、ECB よりも著しく セキュアなブロック暗号モードです。
  • MCRYPT_MODE_CFB (cipher feedback、8 ビット形式) は、 ストリーム暗号モードです。 CFB ではなく、NCFB の使用を推奨します。
  • MCRYPT_MODE_OFB (output feedback、8 ビット形式) は CFBと互換性が あるストリーム暗号モードですが、エラーの伝播が許容されないアプリケーションに使用する ことが可能です。 OFB ではなく、 NOFB の使用を推奨します。
  • MCRYPT_MODE_NOFB (output feedback, nビット形式) は OFB と互換性がありますが、 アルゴリズムのブロックサイズを変更可能です。
  • MCRYPT_MODE_STREAM は、 "WAKE" や "RC4" のようないくつかのストリーム アルゴリズムを読み込む追加のモードです。

Mcrypt は、あらかじめ定義された定数が存在しない他の操作モードもサポートしています。 これらは不明な定数の代わりに、文字列を渡すことで利用できます。

  • "ctr" (counter mode) はストリーム暗号モードです。
  • "ncfb" (cipher feedback, n-bit 形式) は CFB と互換性がありますが、 アルゴリズムのブロックサイズを変更可能です。

他のモードおよびランダムデバイス定数:

MCRYPT_ENCRYPT (int)
MCRYPT_DECRYPT (int)
MCRYPT_DEV_RANDOM (int)
MCRYPT_DEV_URANDOM (int)
MCRYPT_RAND (int)


Mcrypt 暗号

以下に、mcrypt 拡張モジュールにより現在サポートされている暗号のリストを 示します。サポートされる暗号の完全なリストについては、 mcrypt.h の最後にある define を参照ください。 mcrypt-2.2.x API に関する一般的な規則は、 MCRYPT_暗号名で PHP から暗号をアクセス可能であるということです。 mcrypt-2.4.x および mcrypt-2.5.x の API についてもこれらの定数は 使用できますが、mcrypt_module_open() を コールする際に文字列で暗号名を指定することも可能です。

  • MCRYPT_3DES
  • MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x のみ)
  • MCRYPT_ARCFOUR (libmcrypt > 2.4.x のみ)
  • MCRYPT_BLOWFISH
  • MCRYPT_CAST_128
  • MCRYPT_CAST_256
  • MCRYPT_CRYPT
  • MCRYPT_DES
  • MCRYPT_DES_COMPAT (libmcrypt 2.2.x のみ)
  • MCRYPT_ENIGMA (libmcrypt > 2.4.x のみ、MCRYPT_CRYPT へのエイリアス)
  • MCRYPT_GOST
  • MCRYPT_IDEA (非フリー)
  • MCRYPT_LOKI97 (libmcrypt > 2.4.x のみ)
  • MCRYPT_MARS (libmcrypt > 2.4.x のみ、非フリー)
  • MCRYPT_PANAMA (libmcrypt > 2.4.x のみ)
  • MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x のみ)
  • MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x のみ)
  • MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x のみ)
  • MCRYPT_RC2
  • MCRYPT_RC4 (libmcrypt 2.2.x のみ)
  • MCRYPT_RC6 (libmcrypt > 2.4.x のみ)
  • MCRYPT_RC6_128 (libmcrypt 2.2.x のみ)
  • MCRYPT_RC6_192 (libmcrypt 2.2.x のみ)
  • MCRYPT_RC6_256 (libmcrypt 2.2.x のみ)
  • MCRYPT_SAFER64
  • MCRYPT_SAFER128
  • MCRYPT_SAFERPLUS (libmcrypt > 2.4.x のみ)
  • MCRYPT_SERPENT(libmcrypt > 2.4.x のみ)
  • MCRYPT_SERPENT_128 (libmcrypt 2.2.x のみ)
  • MCRYPT_SERPENT_192 (libmcrypt 2.2.x のみ)
  • MCRYPT_SERPENT_256 (libmcrypt 2.2.x のみ)
  • MCRYPT_SKIPJACK (libmcrypt > 2.4.x のみ)
  • MCRYPT_TEAN (libmcrypt 2.2.x のみ)
  • MCRYPT_THREEWAY
  • MCRYPT_TRIPLEDES (libmcrypt > 2.4.x のみ)
  • MCRYPT_TWOFISH (古い mcrypt 2.x 系か、あるいは mcrypt > 2.4.x )
  • MCRYPT_TWOFISH128 (TWOFISHxxx は 2.x の新しいバージョンで使用可能ですが、2.4.x では使用できません)
  • MCRYPT_TWOFISH192
  • MCRYPT_TWOFISH256
  • MCRYPT_WAKE (libmcrypt > 2.4.x のみ)
  • MCRYPT_XTEA (libmcrypt > 2.4.x のみ)

(CFB および OFB モードでは)それぞれの暗号関数に初期化ベクトル(IV) を指定する必要があり、(CBC モードでは)IV を指定することが可能です。 IV はユニークである必要があり、暗号化/復号化の際に同じである 必要があります。暗号化されて保存されたデータの場合、関数の出力を (ファイル名の MD5 キーのように) 保存されたデータの位置を表す インデックスとして使用することができます。もしくは、暗号化された データと共に IV を渡すことができます(このトピックに関する議論については、 Applied Cryptography by Schneier (ISBN 0-471-11709-9) の 9.3 章を参照ください)。


Mcrypt 関数

目次

  • mcrypt_create_iv — Creates an initialization vector (IV) from a random source
  • mcrypt_decrypt — Decrypts crypttext with given parameters
  • mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
  • mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
  • mcrypt_enc_get_iv_size — オープンされたアルゴリズムの IV の大きさを返す
  • mcrypt_enc_get_key_size — オープンされたモードでサポートされる最大キー長を返す
  • mcrypt_enc_get_modes_name — オープンされたモードの名前を返す
  • mcrypt_enc_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキー長を配列にして返す
  • mcrypt_enc_is_block_algorithm — オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる
  • mcrypt_enc_is_block_algorithm_mode — オープンされたモードの暗号がブロックモードで動作するかどうかを調べる
  • mcrypt_enc_is_block_mode — オープンされたモードがブロック出力を行うかどうかを調べる
  • mcrypt_enc_self_test — オープンしたモジュールのセルフテストを実行する
  • mcrypt_encrypt — 指定したパラメータでプレーンテキストを暗号化する
  • mcrypt_generic — データを暗号化する
  • mcrypt_generic_deinit — 暗号化モジュールを終了する
  • mcrypt_generic_init — 暗号化に必要な全てのバッファを初期化する
  • mcrypt_get_block_size — 指定した暗号のブロックサイズを得る
  • mcrypt_get_cipher_name — 指定した暗号の名前を得る
  • mcrypt_get_iv_size — 指定した暗号/モードの組み合わせに属する IV の大きさを返す
  • mcrypt_get_key_size — 指定した暗号のキーの長さを得る
  • mcrypt_list_algorithms — サポートされる全ての暗号を配列として取得する
  • mcrypt_list_modes — サポートされる全てのモードの配列を取得する
  • mcrypt_module_close — mcrypt モジュールを閉じる
  • mcrypt_module_get_algo_block_size — 指定したアルゴリズムのブロック長を返す
  • mcrypt_module_get_algo_key_size — オープンされたモードでサポートされる最大キー長を返す
  • mcrypt_module_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す
  • mcrypt_module_is_block_algorithm — 指定したアルゴリズムがブロックアルゴリズムであるかを調べる
  • mcrypt_module_is_block_algorithm_mode — 指定したモジュールがブロックアルゴリズムであるかどうかを返す
  • mcrypt_module_is_block_mode — 指定したモードがブロック出力を行うかどうかを返す
  • mcrypt_module_open — 使用するアルゴリズムおよびモードのモジュールをオープンする
  • mcrypt_module_self_test — 指定したモジュールのセルフテストを実行する
  • mdecrypt_generic — データを復号する


Creates an initialization vector (IV) from a random source

  • ≪ Mcrypt 関数
  • mcrypt_decrypt ≫
  • PHP Manual
  • Mcrypt 関数
  • Creates an initialization vector (IV) from a random source

mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Creates an initialization vector (IV) from a random source

警告

この関数は PHP 7.1.0 で 非推奨 となり、 PHP 7.2.0 で削除 されました。

この関数の代替として、これらが使えます。

  • random_bytes()

説明

mcrypt_create_iv(int $size, int $source = MCRYPT_DEV_URANDOM): string

Creates an initialization vector (IV) from a random source.

The IV is only meant to give an alternative seed to the encryption routines. This IV does not need to be secret at all, though it can be desirable. You even can send it along with your ciphertext without losing security.

パラメータ

size

The size of the IV.

source

The source of the IV. The source can be MCRYPT_RAND (system random number generator), MCRYPT_DEV_RANDOM (read data from /dev/random) and MCRYPT_DEV_URANDOM (read data from /dev/urandom). Prior to 5.3.0, MCRYPT_RAND was the only one supported on Windows.

Note that the default value of this parameter was MCRYPT_DEV_RANDOM prior to PHP 5.6.0.

注意: Note that MCRYPT_DEV_RANDOM may block until more entropy is available.

戻り値

Returns the initialization vector, or false on error.

例

例1 mcrypt_create_iv() Example

<?php
$size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
$iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
?>

参考

  • » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
  • » http://www.quadibloc.com/crypto/co0409.htm
  • Chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9)
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


Decrypts crypttext with given parameters

  • ≪ mcrypt_create_iv
  • mcrypt_enc_get_algorithms_name ≫
  • PHP Manual
  • Mcrypt 関数
  • Decrypts crypttext with given parameters

mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Decrypts crypttext with given parameters

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_decrypt(
string $cipher,
string $key,
string $data,
string $mode,
string $iv = ?
): string|false

Decrypts the data and returns the unencrypted data.

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

key

The key with which the data was encrypted. If the provided key size is not supported by the cipher, the function will emit a warning and return false

data

The data that will be decrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'.

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

iv

CBC, CFB, OFB モードおよび STREAM モードのいくつかのアルゴリズムの初期化の際に使用されます。 指定した IV のサイズがそのモードでサポートされていない場合、 あるいは IV を必要とするモードで IV が指定されなかった場合は、 この関数は警告を発して false を返します。

戻り値

Returns the decrypted data as a string 失敗した場合に false を返します.

参考

  • mcrypt_encrypt() - 指定したパラメータでプレーンテキストを暗号化する


Returns the name of the opened algorithm

  • ≪ mcrypt_decrypt
  • mcrypt_enc_get_block_size ≫
  • PHP Manual
  • Mcrypt 関数
  • Returns the name of the opened algorithm

mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_algorithms_name(resource $td): string

This function returns the name of the algorithm.

パラメータ

td

The encryption descriptor.

戻り値

Returns the name of the opened algorithm as a string.

例

例1 mcrypt_enc_get_algorithms_name() example

<?php
$td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";

$td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";
?>

上の例の出力は以下となります。

CAST-256
CAST-256


Returns the blocksize of the opened algorithm

  • ≪ mcrypt_enc_get_algorithms_name
  • mcrypt_enc_get_iv_size ≫
  • PHP Manual
  • Mcrypt 関数
  • Returns the blocksize of the opened algorithm

mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_block_size(resource $td): int

Gets the blocksize of the opened algorithm.

パラメータ

td

The encryption descriptor.

戻り値

Returns the block size of the specified algorithm in bytes.


オープンされたアルゴリズムの IV の大きさを返す

  • ≪ mcrypt_enc_get_block_size
  • mcrypt_enc_get_key_size ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたアルゴリズムの IV の大きさを返す

mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — オープンされたアルゴリズムの IV の大きさを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_iv_size(resource $td): int

この関数は、暗号化記述子で指定したアルゴリズムの iv の大きさを バイト単位で返します。IV は、cbc、cfb、ofbモード およびストリームモードのいくつかのアルゴリズムで使用されます。

パラメータ

td

暗号化記述子。

戻り値

この関数は、暗号化記述子で指定したアルゴリズムの iv の大きさを バイト単位で返します。 この関数が '0' を返す場合、IV は そのアルゴリズムでは無視されます。


オープンされたモードでサポートされる最大キー長を返す

  • ≪ mcrypt_enc_get_iv_size
  • mcrypt_enc_get_modes_name ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードでサポートされる最大キー長を返す

mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — オープンされたモードでサポートされる最大キー長を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_key_size(resource $td): int

そのアルゴリズムでサポートされる最大キー長をバイト単位で返します。

パラメータ

td

暗号化記述子。

戻り値

そのアルゴリズムでサポートされる最大キー長をバイト単位で返します。


オープンされたモードの名前を返す

  • ≪ mcrypt_enc_get_key_size
  • mcrypt_enc_get_supported_key_sizes ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードの名前を返す

mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — オープンされたモードの名前を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_modes_name(resource $td): string

この関数はモード名を返します。

パラメータ

td

暗号化記述子。

戻り値

名前を表す文字列を返します。

例

例1 mcrypt_enc_get_modes_name() の例

<?php
$td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_modes_name($td). "\n";

$td = mcrypt_module_open ('cast-256', '', 'ecb', '');
echo mcrypt_enc_get_modes_name($td). "\n";
?>

上の例の出力は以下となります。

CFB
ECB


オープンされたアルゴリズムでサポートされるキー長を配列にして返す

  • ≪ mcrypt_enc_get_modes_name
  • mcrypt_enc_is_block_algorithm ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたアルゴリズムでサポートされるキー長を配列にして返す

mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキー長を配列にして返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_get_supported_key_sizes(resource $td): array

オープンしたアルゴリズムでサポートするキーの長さを取得します。

パラメータ

td

暗号化記述子。

戻り値

暗号化記述子で指定したアルゴリズムでサポートされるキー長を配列と して返します。返された配列が空の場合、1 と mcrypt_enc_get_key_size() の値の間のすべての キー長がアルゴリズムでサポートされます。

例

例1 mcrypt_enc_get_supported_key_sizes() の例

<?php
$td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
var_dump(mcrypt_enc_get_supported_key_sizes($td));
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(16)
  [1]=>
  int(24)
  [2]=>
  int(32)
}


オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる

  • ≪ mcrypt_enc_get_supported_key_sizes
  • mcrypt_enc_is_block_algorithm_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる

mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_is_block_algorithm(resource $td): bool

オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べます。

パラメータ

td

暗号化記述子。

戻り値

アルゴリズムがブロックアルゴリズムである場合に true、 ストリームアルゴリズムである場合に false を返します。


オープンされたモードの暗号がブロックモードで動作するかどうかを調べる

  • ≪ mcrypt_enc_is_block_algorithm
  • mcrypt_enc_is_block_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードの暗号がブロックモードで動作するかどうかを調べる

mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — オープンされたモードの暗号がブロックモードで動作するかどうかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_is_block_algorithm_mode(resource $td): bool

オープンされているモードがブロックモードで動作するかどうかを調べます (たとえばストリームでは false、cbc や cfb、ofb では true)。

パラメータ

td

暗号化記述子。

戻り値

モードがブロックアルゴリズムを使用している場合に true、 その他の場合に false を返します。


オープンされたモードがブロック出力を行うかどうかを調べる

  • ≪ mcrypt_enc_is_block_algorithm_mode
  • mcrypt_enc_self_test ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードがブロック出力を行うかどうかを調べる

mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — オープンされたモードがブロック出力を行うかどうかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_is_block_mode(resource $td): bool

オープンされたモードがブロック出力を行うかどうかを調べます (例: cbc と ecb の場合に true、cfb と stream の場合に false)。

パラメータ

td

暗号化記述子。

戻り値

バイトブロックを出力するモードの場合に true、 バイト出力を行うモードの場合に false を返します。


オープンしたモジュールのセルフテストを実行する

  • ≪ mcrypt_enc_is_block_mode
  • mcrypt_encrypt ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンしたモジュールのセルフテストを実行する

mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — オープンしたモジュールのセルフテストを実行する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_enc_self_test(resource $td): int

この関数は、記述子 td で指定したアルゴリズムの セルフテストを実行します。

パラメータ

td

暗号化記述子。

戻り値

成功したときは 0 を返し、 失敗したときは負の int を返します。


指定したパラメータでプレーンテキストを暗号化する

  • ≪ mcrypt_enc_self_test
  • mcrypt_generic ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したパラメータでプレーンテキストを暗号化する

mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — 指定したパラメータでプレーンテキストを暗号化する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_encrypt(
string $cipher,
string $key,
string $data,
string $mode,
string $iv = ?
): string|false

データを暗号化して、それを返します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

key

データを暗号化する際のキー。 指定した暗号化方式に対応していないサイズのキーを渡された場合は、 警告を発して false を返します。

data

指定した cipher および mode で暗号化するデータ。 データの大きさが n * blocksize でない場合、データは、 '\0'で埋められます。

返される暗号化されたテキストは、data で指定したデータの大きさよりも大きくなる可能性があります。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

iv

CBC, CFB, OFB モードおよび STREAM モードのいくつかのアルゴリズムの初期化の際に使用されます。 指定した IV のサイズがそのモードでサポートされていない場合、 あるいは IV を必要とするモードで IV が指定されなかった場合は、 この関数は警告を発して false を返します。

戻り値

暗号化されたデータを文字列で返します。失敗した場合に false を返します。

例

例1 mcrypt_encrypt() の例

<?php
# --- ENCRYPTION ---

# the key should be random binary, use scrypt, bcrypt or PBKDF2 to
# convert a string into a key
# key is specified using hexadecimal
$key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

# show key size use either 16, 24 or 32 byte keys for AES-128, 192
# and 256 respectively
$key_size = strlen($key);
echo "Key size: " . $key_size . "\n";

$plaintext = "This string was AES-256 / CBC / ZeroBytePadding encrypted.";

# create a random IV to use with CBC encoding
$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

# creates a cipher text compatible with AES (Rijndael block size = 128)
# to keep the text confidential
# only suitable for encoded input that never ends with value 00h
# (because of default zero padding)
$ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
$plaintext, MCRYPT_MODE_CBC, $iv);

# prepend the IV for it to be available for decryption
$ciphertext = $iv . $ciphertext;

# encode the resulting cipher text so it can be represented by a string
$ciphertext_base64 = base64_encode($ciphertext);

echo $ciphertext_base64 . "\n";

# === WARNING ===

# Resulting cipher text has no integrity or authenticity added
# and is not protected against padding oracle attacks.

# --- DECRYPTION ---

$ciphertext_dec = base64_decode($ciphertext_base64);

# retrieves the IV, iv_size should be created using mcrypt_get_iv_size()
$iv_dec = substr($ciphertext_dec, 0, $iv_size);

# retrieves the cipher text (everything except the $iv_size in the front)
$ciphertext_dec = substr($ciphertext_dec, $iv_size);

# may remove 00h valued characters from end of plain text
$plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
$ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

echo $plaintext_dec . "\n";
?>

上の例の出力は以下となります。

Key size: 32
ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
This string was AES-256 / CBC / ZeroBytePadding encrypted.

参考

  • mcrypt_decrypt() - Decrypts crypttext with given parameters
  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする


データを暗号化する

  • ≪ mcrypt_encrypt
  • mcrypt_generic_deinit ≫
  • PHP Manual
  • Mcrypt 関数
  • データを暗号化する

mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — データを暗号化する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_generic(resource $td, string $data): string

この関数は、データを暗号化します。データ長を n * blocksize とする ために、データは "\0" で埋められます。 この関数は、暗号化されたデータを返します。 データのパディングが行われるため、返される文字列の長さは 入力よりも長いことがあることに注意してください。

暗号化したデータをデータベースに格納する場合は、mcrypt_generic が返す文字列全てを格納することを忘れないでください。さもないと、 文字列を適切に復号できなくなります。もとの文字列が 10 文字で ブロックサイズが 8 (ブロックサイズを調べるには mcrypt_enc_get_block_size() を使用します) だった場合、データベースのフィールドには少なくとも 16 文字が 必要です。mdecrypt_generic() が返す文字列も 16 文字となることに注意しましょう。埋められた文字を取り除くには... rtrim($str, "\0") を使用します。

もし MySQL データベースにデータを格納する場合は、 varchar フィールドに値を挿入する際に末尾のスペースが取り除かれることを 覚えておきましょう。暗号化されたデータの最後にスペース(ASCII 32)が 含まれていた場合、この処理によってデータが破壊されてしまいます。 かわりに tinyblob/tinytext (あるいはより大きな) フィールドを 使用してください。

パラメータ

td

暗号化記述子。

この関数をコールする前には、常にキーと IV を用いて mcrypt_generic_init() で暗号化ハンドルを 初期化しておくべきです。暗号化が終了したら、 mcrypt_generic_deinit() をコールして 暗号化バッファを開放すべきです。使用例は mcrypt_module_open() を参照ください。

data

暗号化するデータ。

戻り値

暗号化したデータを返します。

参考

  • mdecrypt_generic() - データを復号する
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する
  • mcrypt_generic_deinit() - 暗号化モジュールを終了する


暗号化モジュールを終了する

  • ≪ mcrypt_generic
  • mcrypt_generic_init ≫
  • PHP Manual
  • Mcrypt 関数
  • 暗号化モジュールを終了する

mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — 暗号化モジュールを終了する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_generic_deinit(resource $td): bool

この関数は、暗号化記述子(td)で指定した 暗号化を終了します。すべてのバッファを消去しますが、モジュールは 閉じません。mcrypt_module_close() をコールする 必要があります(しかし、スクリプトの終了時に PHP が自動でこれを 行います)。

パラメータ

td

暗号化記述子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する


暗号化に必要な全てのバッファを初期化する

  • ≪ mcrypt_generic_deinit
  • mcrypt_get_block_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 暗号化に必要な全てのバッファを初期化する

mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — 暗号化に必要な全てのバッファを初期化する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_generic_init(resource $td, string $key, string $iv): int

mcrypt_generic() または mdecrypt_generic() をコールする前に、 常にこの関数をコールする必要があります。

パラメータ

td

暗号化記述子。

key

キーの最大長は、mcrypt_enc_get_key_size() を コールした際に得られるキー長であり、この値より小さな値は全て有効です。

iv

IV は通常そのアルゴリズムのブロック長と同じ大きさですが、 mcrypt_enc_get_iv_size() をコールする ことにより、その大きさを得る必要があります。IV は ECB では 無視されます。IV は CFB、CBC、STREAM、nOFB では必須です。 IV はランダムで一意である必要があります(しかし、秘密ではある必要は ありません)。暗号化と復号で同じ IV を使用する必要があります。 IV を使用したくない場合にはゼロに設定しますが、これは推奨されません。

戻り値

この関数は、エラー時に負の値を返します。キー長が不正な場合に -3、メモリの確保に問題があった場合に -4、そしてそれ以外の戻り値は その他のエラーとなります。エラーが警告を発生させた場合、それが 表示されます。間違ったパラメータが渡された場合には false が返されます。

参考

  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする


指定した暗号のブロックサイズを得る

  • ≪ mcrypt_generic_init
  • mcrypt_get_cipher_name ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号のブロックサイズを得る

mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — 指定した暗号のブロックサイズを得る

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_block_size(int $cipher): int|false
mcrypt_get_block_size(string $cipher, string $mode): int|false

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合であり、2 番目 のものは libmcrypt 2.4.x あるいは 2.5.x とリンクした場合です。

mcrypt_get_block_size()は、指定した cipher のブロック長を返します (暗号化モードと組み合わせます)。

mcrypt_enc_get_block_size() 関数のほうがより有用です。というのもこちらの関数は mcrypt_module_open() が返すリソースを使用するからです。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

戻り値

アルゴリズムのブロックサイズをバイト数で返します。失敗した場合に false を返します.

例

例1 mcrypt_get_block_size() の例

この例は、libmcrypt 2.4.x および 2.5.x を対象にリンクした際の使用法を示すものです。

<?php

echo mcrypt_get_block_size('tripledes', 'ecb'); // 8

?>

参考

  • mcrypt_get_key_size() - 指定した暗号のキーの長さを得る
  • mcrypt_enc_get_block_size() - Returns the blocksize of the opened algorithm
  • mcrypt_encrypt() - 指定したパラメータでプレーンテキストを暗号化する


指定した暗号の名前を得る

  • ≪ mcrypt_get_block_size
  • mcrypt_get_iv_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号の名前を得る

mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — 指定した暗号の名前を得る

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_cipher_name(int $cipher): string
mcrypt_get_cipher_name(string $cipher): string

mcrypt_get_cipher_name() は、指定した暗号(cipher) の名前を得るために使用されます。

mcrypt_get_cipher_name() は、暗号の番号 (libmcrypt 2.2.x)または暗号名(libmcrypt 2.4.x 以降)を引数とし、 暗号名を返します。指定した暗号が存在しない場合は false を返します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

戻り値

暗号の名前、あるいは暗号が存在しない場合に false を返します。

例

例1 mcrypt_get_cipher_name() の例

<?php
$cipher = MCRYPT_TripleDES;

echo mcrypt_get_cipher_name($cipher);
?>

上の例の出力は以下となります。

3DES


指定した暗号/モードの組み合わせに属する IV の大きさを返す

  • ≪ mcrypt_get_cipher_name
  • mcrypt_get_key_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号/モードの組み合わせに属する IV の大きさを返す

mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — 指定した暗号/モードの組み合わせに属する IV の大きさを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_iv_size(string $cipher, string $mode): int

指定した cipher/mode の組み合わせにおける IV の大きさを取得します。

mcrypt_enc_get_iv_size() 関数を使用するほうが より有用です。これは mcrypt_module_open() が返すリソースを使用します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

ECB モードでは IV は要求されないため、IV は無視されます。 暗号化と復号の際には、同じ IV(開始位置)が必要です。さもないと 暗号化処理は失敗します。

戻り値

初期化ベクトル(IV)の大きさをバイト数で返します。 エラーの際には false を返します。IV が指定した暗号/モードで無視される場合には、ゼロを返します。

例

例1 mcrypt_get_iv_size() の例

<?php
echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

echo mcrypt_get_iv_size('des', 'ecb') . "\n";
?>

参考

  • mcrypt_get_block_size() - 指定した暗号のブロックサイズを得る
  • mcrypt_enc_get_iv_size() - オープンされたアルゴリズムの IV の大きさを返す
  • mcrypt_create_iv() - Creates an initialization vector (IV) from a random source


指定した暗号のキーの長さを得る

  • ≪ mcrypt_get_iv_size
  • mcrypt_list_algorithms ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定した暗号のキーの長さを得る

mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — 指定した暗号のキーの長さを得る

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_get_key_size(int $cipher): int|false
mcrypt_get_key_size(string $cipher, string $mode): int|false

最初のプロトタイプは libmcrypt 2.2.x とリンクした場合であり、2 番目の ものは libmcrypt 2.4.x あるいは 2.5.x とリンクした場合です。

mcrypt_get_key_size() は、 cipher で(暗号化モードとあわせて)指定した キーの長さを得るために使用されます。

mcrypt_enc_get_key_size() 関数を使用するほうが より有用です。これは mcrypt_module_open() が返すリソースを使用します。

パラメータ

cipher

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

戻り値

そのアルゴリズムでサポートする最長のキーサイズをバイト数で返します。 失敗した場合に false を返します.

例

例1 mcrypt_get_key_size() の例

<?php
echo mcrypt_get_key_size('tripledes', 'ecb');
?>

この例では、libmcrypt 2.4.x および 2.5.x とリンクした場合の この関数の使用法を示します。

上の例の出力は以下となります。

24

参考

  • mcrypt_get_block_size() - 指定した暗号のブロックサイズを得る
  • mcrypt_enc_get_key_size() - オープンされたモードでサポートされる最大キー長を返す
  • mcrypt_encrypt() - 指定したパラメータでプレーンテキストを暗号化する


サポートされる全ての暗号を配列として取得する

  • ≪ mcrypt_get_key_size
  • mcrypt_list_modes ≫
  • PHP Manual
  • Mcrypt 関数
  • サポートされる全ての暗号を配列として取得する

mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — サポートされる全ての暗号を配列として取得する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_list_algorithms(string $lib_dir = ini_get("mcrypt.algorithms_dir")): array

lib_dir パラメータにあるサポートするすべてのアルゴリズムの一覧を取得します。

パラメータ

lib_dir

すべてのアルゴリズムが存在するディレクトリを指定します。 指定しない場合は、php.ini の mcrypt.algorithms_dir ディレクティブを使用します。

戻り値

サポートするすべてのアルゴリズムを配列で返します。

例

例1 mcrypt_list_algorithms() の例

<?php
$algorithms = mcrypt_list_algorithms();
print_r($algorithms);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => cast-128
    [1] => gost
    [2] => rijndael-128
    [3] => twofish
    [4] => arcfour
    [5] => cast-256
    [6] => loki97
    [7] => rijndael-192
    [8] => saferplus
    [9] => wake
    [10] => blowfish-compat
    [11] => des
    [12] => rijndael-256
    [13] => serpent
    [14] => xtea
    [15] => blowfish
    [16] => enigma
    [17] => rc2
    [18] => tripledes
)


サポートされる全てのモードの配列を取得する

  • ≪ mcrypt_list_algorithms
  • mcrypt_module_close ≫
  • PHP Manual
  • Mcrypt 関数
  • サポートされる全てのモードの配列を取得する

mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — サポートされる全てのモードの配列を取得する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_list_modes(string $lib_dir = ini_get("mcrypt.modes_dir")): array

lib_dir にあるすべてのサポートするモードの一覧を取得します。

パラメータ

lib_dir

すべてのモードが存在するディレクトリを指定します。 指定しない場合は、 php.ini ディレクティブ mcrypt.modes_dir を使用します。

戻り値

サポートするすべてのモードを配列で返します。

例

例1 mcrypt_list_modes() の例

<?php
$modes = mcrypt_list_modes();

foreach ($modes as $mode) {
echo "$mode <br />\n";
}
?>

上の例は、デフォルトのモードディレクトリにあるサポートされる 全てのアルゴリズムの一覧を出力します。php.ini ディレクティブの mcrypt.modes_dir でこれが設定されていない場合、mcrypt の デフォルトディレクトリ(/usr/local/lib/libmcrypt)が使用されます。


mcrypt モジュールを閉じる

  • ≪ mcrypt_list_modes
  • mcrypt_module_get_algo_block_size ≫
  • PHP Manual
  • Mcrypt 関数
  • mcrypt モジュールを閉じる

mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — mcrypt モジュールを閉じる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_close(resource $td): bool

指定した暗号化ハンドルを閉じます。

パラメータ

td

暗号化記述子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする


指定したアルゴリズムのブロック長を返す

  • ≪ mcrypt_module_close
  • mcrypt_module_get_algo_key_size ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したアルゴリズムのブロック長を返す

mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — 指定したアルゴリズムのブロック長を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_get_algo_block_size(string $algorithm, string $lib_dir = ?): int

指定したアルゴリズムのブロック長を取得します。

パラメータ

algorithm

アルゴリズム名。

lib_dir

オプションのパラメータで、 システム上でのモードモジュールの位置を指定することが可能です。

戻り値

指定したアルゴリズムでサポートされるブロック長をバイト単位で返します。


オープンされたモードでサポートされる最大キー長を返す

  • ≪ mcrypt_module_get_algo_block_size
  • mcrypt_module_get_supported_key_sizes ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたモードでサポートされる最大キー長を返す

mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — オープンされたモードでサポートされる最大キー長を返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_get_algo_key_size(string $algorithm, string $lib_dir = ?): int

オープンされたモードでサポートされる最大キー長を取得します。

パラメータ

algorithm

アルゴリズム名。

lib_dir

オプションのパラメータで、 システム上でのモードモジュールの位置を指定することが可能です。

戻り値

この関数は、指定したアルゴリズムでサポートされる最大キー長をバイト単位で返します。


オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す

  • ≪ mcrypt_module_get_algo_key_size
  • mcrypt_module_is_block_algorithm ≫
  • PHP Manual
  • Mcrypt 関数
  • オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す

mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_get_supported_key_sizes(string $algorithm, string $lib_dir = ?): array

指定したアルゴリズムでサポートされるキーのサイズを配列で返します。 この関数が空の配列を返した場合、1 から mcrypt_module_get_algo_key_size() の戻り値の間のすべてのサイズのキーがアルゴリズムでサポートされます。

パラメータ

algorithm

使用するアルゴリズム。

lib_dir

オプションのパラメータ lib_dir により、 システムでアルゴリズムモジュールがある場所を指定することが可能です。

戻り値

指定したアルゴリズムでサポートするキーサイズの配列を返します。 空の配列を返した場合は、そのアルゴリズムでは 1 から mcrypt_module_get_algo_key_size() までのすべてのキーサイズをサポートすることになります。

参考

  • mcrypt_enc_get_supported_key_sizes() - オープンされたアルゴリズムでサポートされるキー長を配列にして返す


指定したアルゴリズムがブロックアルゴリズムであるかを調べる

  • ≪ mcrypt_module_get_supported_key_sizes
  • mcrypt_module_is_block_algorithm_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したアルゴリズムがブロックアルゴリズムであるかを調べる

mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — 指定したアルゴリズムがブロックアルゴリズムであるかを調べる

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_is_block_algorithm(string $algorithm, string $lib_dir = ?): bool

この関数は、指定したアルゴリズムがブロックアルゴリズムの場合に true、ストリームアルゴリズムの場合に false を返します。

パラメータ

algorithm

調べたいアルゴリズム。

lib_dir

オプションのパラメータ lib_dir により、 システム上での algorithm モジュールの位置を指定することが可能です。

戻り値

この関数は、指定したアルゴリズムがブロックアルゴリズムの場合に true、ストリームアルゴリズムの場合に false を返します。


指定したモジュールがブロックアルゴリズムであるかどうかを返す

  • ≪ mcrypt_module_is_block_algorithm
  • mcrypt_module_is_block_mode ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したモジュールがブロックアルゴリズムであるかどうかを返す

mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm_mode — 指定したモジュールがブロックアルゴリズムであるかどうかを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_is_block_algorithm_mode(string $mode, string $lib_dir = ?): bool

この関数は、mode がブロックアルゴリズムを使用する場合に true、 その他の場合に false を返します。(例: stream の場合に false、 cbc、cfb、ofb の場合に true)

パラメータ

mode

調べたいモード。

lib_dir

オプションのパラメータ lib_dir により、 システム上での mode モジュールの位置を指定することが可能です。

戻り値

この関数は、mode がブロックアルゴリズムを使用する場合に true、 その他の場合に false を返します。(例: stream の場合に false、 cbc、cfb、ofb の場合に true)


指定したモードがブロック出力を行うかどうかを返す

  • ≪ mcrypt_module_is_block_algorithm_mode
  • mcrypt_module_open ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したモードがブロック出力を行うかどうかを返す

mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — 指定したモードがブロック出力を行うかどうかを返す

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_is_block_mode(string $mode, string $lib_dir = ?): bool

この関数は、ブロック出力を行うモードの場合に true、バイトのみを 出力する場合に false を返します(例: cbc と ecb の場合に true、 cfb と streamの場合に false)。

パラメータ

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

lib_dir

オプションのパラメータ lib_dir により、システム上での mode モジュールの 位置を指定することが可能です。

戻り値

この関数は、ブロック出力を行うモードの場合に true、バイトのみを 出力する場合に false を返します(例: cbc と ecb の場合に true、 cfb と streamの場合に false)。


使用するアルゴリズムおよびモードのモジュールをオープンする

  • ≪ mcrypt_module_is_block_mode
  • mcrypt_module_self_test ≫
  • PHP Manual
  • Mcrypt 関数
  • 使用するアルゴリズムおよびモードのモジュールをオープンする

mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — 使用するアルゴリズムおよびモードのモジュールをオープンする

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_open(
string $algorithm,
string $algorithm_directory,
string $mode,
string $mode_directory
): resource

この関数は、使用するアルゴリズムおよびモードのモジュールをオープン します。アルゴリズム名は、たとえば "twofish" のように名前で指定するか定数 MCRYPT_暗号名 のいずれかを使用して指定します。 ライブラリは mcrypt_module_close() をコールする ことによりクローズされます。

パラメータ

algorithm

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

algorithm_directory

暗号化モジュールの位置を指定する際には algorithm_directory を使います。 ディレクトリ名を指定した場合には、これが使用されます。 これらの一つに空の文字列("")を指定した場合、php.ini ディレクティブ mcrypt.algorithms_dir に設定された値を使います。 これらが設定されていない場合、libmcrypt をコンパイルした際の デフォルトのディレクトリ (通常は/usr/local/lib/libmcrypt) を使います。

mode

定数 MCRYPT_MODE_モード名、あるいは文字列 "ecb", "cbc", "cfb", "ofb", "nofb" ,"stream" のいずれか。

mode_directory

暗号化モジュールの位置を指定する際には mode_directory を使います。 ディレクトリ名を指定した場合には、これが使用されます。 これらの一つに空の文字列("")を指定した場合、php.ini ディレクティブ mcrypt.modes_dir に設定された値を使います。 これらが設定されていない場合、libmcrypt をコンパイルした際の デフォルトのディレクトリ (通常は/usr/local/lib/libmcrypt) を使います。

戻り値

通常は暗号化記述子を返します。エラー時は false を返します。

例

例1 mcrypt_module_open() の例

<?php
$td = mcrypt_module_open(MCRYPT_DES, '',
MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

$td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
?>

上の例の最初の行では、デフォルトのディレクトリから DES 暗号化を、 そして /usr/lib/mcrypt-modes から ECB モードの オープンを試みます。2 行目の例では暗号化形式とモードを文字列で 指定しています。これは、libmcrypt 2.4.x あるいは 2.5.x に対して 拡張モジュールがリンクされている場合にのみ使用可能です。

例2 mcrypt_module_open() を暗号化で使用する

<?php
/* 暗号モジュールをオープンします */
$td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

/* IV を作成し、キー長を定義します。Windows では、かわりに
* MCRYPT_RAND を使用します */
$iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
$ks = mcrypt_enc_get_key_size($td);

/* キーを作成します (例示のみ: MD5 は、この用途には不向きなハッシュアルゴリズムです) */
$key = substr(hash('md5', 'very secret key'), 0, $ks);

/* 暗号化処理を初期化します */
mcrypt_generic_init($td, $key, $iv);

/* データを暗号化します */
$encrypted = mcrypt_generic($td, 'This is very important data');

/* 暗号化ハンドラを終了します */
mcrypt_generic_deinit($td);

/* 復号用の暗号モジュールを初期化します */
mcrypt_generic_init($td, $key, $iv);

/* 暗号化された文字列を復号します */
$decrypted = mdecrypt_generic($td, $encrypted);

/* 復号ハンドルを終了し、モジュールを閉じます */
mcrypt_generic_deinit($td);
mcrypt_module_close($td);

/* 文字列を表示します */
echo trim($decrypted) . "\n";
?>

参考

  • mcrypt_module_close() - mcrypt モジュールを閉じる
  • mcrypt_generic() - データを暗号化する
  • mdecrypt_generic() - データを復号する
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する
  • mcrypt_generic_deinit() - 暗号化モジュールを終了する


指定したモジュールのセルフテストを実行する

  • ≪ mcrypt_module_open
  • mdecrypt_generic ≫
  • PHP Manual
  • Mcrypt 関数
  • 指定したモジュールのセルフテストを実行する

mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — 指定したモジュールのセルフテストを実行する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mcrypt_module_self_test(string $algorithm, string $lib_dir = ?): bool

この関数は、指定したアルゴリズムのセルフテストを実行します。

パラメータ

algorithm

MCRYPT_暗号名 定数のいずれか、 あるいはアルゴリズム名をあらわす文字列。

lib_dir

オプションのパラメータ lib_dir により、 システム上での algorithm モジュールの位置を指定することが可能です。

戻り値

成功した場合 0、失敗した場合に負の int を返します。

例

例1 mcrypt_module_self_test() の例

<?php
var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
?>

上の例の出力は以下となります。

bool(true)
bool(false)


データを復号する

  • ≪ mcrypt_module_self_test
  • Mhash ≫
  • PHP Manual
  • Mcrypt 関数
  • データを復号する

mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — データを復号する

警告

この関数は PHP 7.1.0 で 非推奨となり、PHP 7.2.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

mdecrypt_generic(resource $td, string $data): string

この関数は、データを復号します。データのパディングが行われるため、 返される文字列の長さは暗号化前の文字列よりも長くなる可能性があることに 注意してください。

パラメータ

td

mcrypt_module_open() が返す暗号化記述子。

data

暗号化されたデータ。

戻り値

復号した文字列を返します。

例

例1 mdecrypt_generic() の例

<?php
/* データ */
$key = 'this is a very long key, even too long for the cipher';
$plain_text = 'very important data';

/* モジュールをオープンし、IV を作成します */
$td = mcrypt_module_open('des', '', 'ecb', '');
$key = substr($key, 0, mcrypt_enc_get_key_size($td));
$iv_size = mcrypt_enc_get_iv_size($td);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

/* 暗号化ハンドルを初期化します */
if (mcrypt_generic_init($td, $key, $iv) != -1) {

/* データを暗号化します */
$c_t = mcrypt_generic($td, $plain_text);
mcrypt_generic_deinit($td);

/* 復号のため、バッファを再度初期化します */
mcrypt_generic_init($td, $key, $iv);
$p_t = mdecrypt_generic($td, $c_t);

/* 後始末をします */
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
}

if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
echo "ok\n";
} else {
echo "error\n";
}
?>

上記の例は、暗号化前のデータと復号したデータと同じであるかどうかを 調べる方法を示すものです。データを復号する前に mcrypt_generic_init() で暗号化バッファを再度 初期化しておくことが重要です。

この関数をコールする前に、常に mcrypt_generic_init() でキーと IV を使用して 復号ハンドルを初期化しておくべきです。暗号化が終了した際には mcrypt_generic_deinit() をコールして暗号化 バッファを開放すべきです。 mcrypt_module_open() の例を参照ください。

参考

  • mcrypt_generic() - データを暗号化する
  • mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する
  • mcrypt_generic_deinit() - 暗号化モジュールを終了する


Mhash

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
  • Mhash 関数
    • mhash — ハッシュ値を計算する
    • mhash_count — 利用可能なハッシュ ID の最大値を得る
    • mhash_get_block_size — 指定したハッシュのブロックサイズを得る
    • mhash_get_hash_name — 指定したハッシュの名前を得る
    • mhash_keygen_s2k — キーを生成する


はじめに

以下の関数は、» mhash と組み合わせて 動作することを前提としています。mhashは、チェックサム、メッセージ ダイジェスト、メッセージ認証コード等を作成するために使用することが できます。

この関数は、mhash ライブラリへのインターフェイスです。 mhash は、MD5, SHAl, GOST や他の多くの方法といった広範なハッシュ アルゴリズムをサポートします。サポートされるハッシュの全一覧に ついては、定数のページを参照ください。一般的な規則として、 特定のハッシュアルゴリズムは、PHP から定数「MHASH_ハッシュ名」で アクセス可能です。例えば、TIGER の場合、PHP 定数 MHASH_TIGER を 使用します。

注意:

この拡張モジュールの後継版は Hash です。

注意:

PHP 7.0.0 以降は、Mhash 拡張モジュールは Hash 拡張モジュールに完全に統合されました。 よって、extension_loaded() を使って Mhash がサポートされているかを検知することはできません。 代わりに function_exists() を使ってください。 さらに、Mhash は get_loaded_extensions() や関連する機能でも報告されません。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Mhash
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

mhash を使用するには、mhash の配布ファイルを » mhash の Web サイト から ダウンロードし、その中のインストール用の指示に従ってください。


インストール手順

この拡張モジュールを使用するには、PHP に --with-mhash[=DIR] パラメータを付けて コンパイルする必要があります。DIR は mhash インストールディレクトリです。

PHP 5.3.0 以降では、 Hash 拡張モジュールが mhash 拡張モジュールの動作をエミュレートするようになりました。 そのため、mhash インストールディレクトリの指定は無意味となりました。 また、hash 拡張モジュールで mhash サポートを有効にしておく必要があります。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下に現在 mhash によりサポートされているハッシュの一覧を示します。 このリストにないけれでも mhash のドキュメントでは「サポートされている」というハッシュがある場合は このドキュメントが古いと考えてください。

  • MHASH_ADLER32
  • MHASH_CRC32
  • MHASH_CRC32B
  • MHASH_GOST
  • MHASH_HAVAL128
  • MHASH_HAVAL160
  • MHASH_HAVAL192
  • MHASH_HAVAL224
  • MHASH_HAVAL256
  • MHASH_MD2
  • MHASH_MD4
  • MHASH_MD5
  • MHASH_RIPEMD128
  • MHASH_RIPEMD256
  • MHASH_RIPEMD320
  • MHASH_SHA1
  • MHASH_SHA192
  • MHASH_SHA224
  • MHASH_SHA256
  • MHASH_SHA384
  • MHASH_SHA512
  • MHASH_SNEFRU128
  • MHASH_SNEFRU256
  • MHASH_TIGER
  • MHASH_TIGER128
  • MHASH_TIGER160
  • MHASH_WHIRLPOOL


例

例1 MD5 ダイジェストと hmac を計算し、16 進数で出力する

<?php
$input = "what do ya want for nothing?";
$hash = mhash(MHASH_MD5, $input);
echo "The hash is " . bin2hex($hash) . "<br />\n";
$hash = mhash(MHASH_MD5, $input, "Jefe");
echo "The hmac is " . bin2hex($hash) . "<br />\n";
?>

上の例の出力は以下となります。

The hash is d03cb659cbf9192dcd066272249f8412
The hmac is 750c783e6ab0b503eaa86e310a5db738


Mhash 関数

目次

  • mhash — ハッシュ値を計算する
  • mhash_count — 利用可能なハッシュ ID の最大値を得る
  • mhash_get_block_size — 指定したハッシュのブロックサイズを得る
  • mhash_get_hash_name — 指定したハッシュの名前を得る
  • mhash_keygen_s2k — キーを生成する


ハッシュ値を計算する

  • ≪ Mhash 関数
  • mhash_count ≫
  • PHP Manual
  • Mhash 関数
  • ハッシュ値を計算する

mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — ハッシュ値を計算する

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

mhash(int $hash, string $data, string $key = ?): string

mhash() は、 hash で指定したハッシュ関数を data に適用します。

パラメータ

algo

ハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

data

ユーザーが入力した文字列。

key

指定した場合は、この関数は結果の HMAC を返します。 HMAC は、メッセージ認証時のキーに基づくハッシュ、 あるいは指定したキーに基づく単なるメッセージダイジェストです。 mhash でサポートしている全てのアルゴリズムが HMAC モードで使用できるわけではありません。

戻り値

結果のハッシュ (あるいはダイジェストとも言います) あるいは HMAC を表す文字列を返します。 エラー時は false を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 hash_*() 関数 を代わりに使って下さい。
8.0.0 | key は、nullable になりました。


利用可能なハッシュ ID の最大値を得る

  • ≪ mhash
  • mhash_get_block_size ≫
  • PHP Manual
  • Mhash 関数
  • 利用可能なハッシュ ID の最大値を得る

mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — 利用可能なハッシュ ID の最大値を得る

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

mhash_count(): int

利用可能なハッシュ ID の最大値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

利用可能なハッシュ ID の最大値を返します。 ハッシュは、0 からこのハッシュ ID までの数字となります。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 hash_*() 関数 を代わりに使って下さい。

例

例1 全ハッシュをループする

<?php

$nr = mhash_count();

for ($i = 0; $i <= $nr; $i++) {
echo sprintf("The blocksize of %s is %d\n",
mhash_get_hash_name($i),
mhash_get_block_size($i));
}
?>


指定したハッシュのブロックサイズを得る

  • ≪ mhash_count
  • mhash_get_hash_name ≫
  • PHP Manual
  • Mhash 関数
  • 指定したハッシュのブロックサイズを得る

mhash_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — 指定したハッシュのブロックサイズを得る

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

mhash_get_block_size(int $algo): int|false

指定した algo のブロックサイズを取得します。

パラメータ

algo

ハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

戻り値

サイズをバイト数で返します。algo が存在しない場合は false を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 hash_*() 関数 を代わりに使って下さい。

例

例1 mhash_get_block_size() の例

<?php

echo mhash_get_block_size(MHASH_MD5); // 16

?>


指定したハッシュの名前を得る

  • ≪ mhash_get_block_size
  • mhash_keygen_s2k ≫
  • PHP Manual
  • Mhash 関数
  • 指定したハッシュの名前を得る

mhash_get_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — 指定したハッシュの名前を得る

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

mhash_get_hash_name(int $algo): string|false

指定した algo の名前を取得します。

パラメータ

algo

ハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

戻り値

ハッシュの名前を返します。そのハッシュが存在しない場合は、false を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 hash_*() 関数 を代わりに使って下さい。

例

例1 mhash_get_hash_name() の例

<?php

echo mhash_get_hash_name(MHASH_MD5); // MD5

?>


キーを生成する

  • ≪ mhash_get_hash_name
  • OpenSSL ≫
  • PHP Manual
  • Mhash 関数
  • キーを生成する

mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — キーを生成する

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

mhash_keygen_s2k(
int $algo,
string $password,
string $salt,
int $length
): string|false

algo にユーザーが指定した password を用いてキーを生成します。

OpenPGP のドキュメント (» RFC 2440) で規定されている、Salted S2k アルゴリズムを使用します。

ユーザーが指定したパスワードは、暗号化アルゴリズムのキーとしては 適切ではないということを覚えておきましょう。ユーザーが選択するのは、 通常はキーボードから入力可能なキーだからです。 これらのパスワードは、文字当たり 6 から 7 ビットのみ(もしくはそれ以下) しか使用していません。ユーザーの指定したキーに対して、 (この関数のような) ある種の変換を行うことを強く推奨します。

パラメータ

algo

キーの作成に使用するハッシュ ID。MHASH_ハッシュ名 定数のいずれかを指定します。

password

ユーザーが指定したパスワード。

salt

異なったキーを生成するため、キーを生成するたびに、 十分にランダムな異なる値となる必要があります。キーを調べる際に salt を知っている必要があるため、キーを salt に付加するというのは 良い発想です。salt は 8 バイト固定長で、これより少ない場合はゼロで 埋められます。

length

キーの長さをバイト数で指定します。

戻り値

生成されたキーを表す文字列、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 hash_*() 関数 を代わりに使って下さい。


OpenSSL

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
    • 目的を調べるフラグ
    • 非対称暗号化のパディングフラグ
    • キーの型
    • PKCS7 フラグ/定数
    • CMS (暗号メッセージシンタックス) 関連のフラグ/定数
    • 署名アルゴリズム
    • 暗号化方式
    • バージョン定数
    • Server Name Indication 定数
    • その他の定数
  • キー/証明書パラメータ
  • 証明書の認証
  • OpenSSL 関数
    • openssl_cipher_iv_length — 初期化ベクトル iv の長さを取得する
    • openssl_cipher_key_length — 暗号鍵の長さを取得する
    • openssl_cms_decrypt — CMS メッセージを復号化する
    • openssl_cms_encrypt — CMS メッセージを暗号化する
    • openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする
    • openssl_cms_sign — ファイルに署名する
    • openssl_cms_verify — CMS の署名を検証する
    • openssl_csr_export — CSR を文字列としてエクスポートする
    • openssl_csr_export_to_file — CSR をファイルにエクスポートする
    • openssl_csr_get_public_key — CSR の公開鍵を返す
    • openssl_csr_get_subject — CSR の subject を返す
    • openssl_csr_new — CSR を作成する
    • openssl_csr_sign — CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する
    • openssl_decrypt — データを復号する
    • openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する
    • openssl_digest — ダイジェストを計算する
    • openssl_encrypt — データを暗号化する
    • openssl_error_string — OpenSSL エラーメッセージを返す
    • openssl_free_key — キーリソースを開放する
    • openssl_get_cert_locations — 有効な証明書の格納場所を検索する
    • openssl_get_cipher_methods — 利用可能な暗号メソッドを取得
    • openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する
    • openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得
    • openssl_get_privatekey — openssl_pkey_get_private のエイリアス
    • openssl_get_publickey — openssl_pkey_get_public のエイリアス
    • openssl_open — シール(暗号化)されたデータをオープン(復号)する
    • openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する
    • openssl_pkcs12_export — PKCS#12 互換の証明書保存ファイルを変数にエクスポートする
    • openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする
    • openssl_pkcs12_read — PKCS#12 認証ストアをパースして配列形式にする
    • openssl_pkcs7_decrypt — S/MIME 暗号化されたメッセージを復号する
    • openssl_pkcs7_encrypt — S/MIME メッセージを暗号化する
    • openssl_pkcs7_read — PKCS7 ファイルを PEM証明書 の配列にエクスポートする
    • openssl_pkcs7_sign — S/MIME メッセージに署名する
    • openssl_pkcs7_verify — S/MIME で署名されたメッセージの署名を検証する
    • openssl_pkey_derive — リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する
    • openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する
    • openssl_pkey_export_to_file — エクスポート可能な形式で、キーをファイルに取得する
    • openssl_pkey_free — 秘密鍵を開放する
    • openssl_pkey_get_details — キーの詳細の配列を返す
    • openssl_pkey_get_private — 秘密鍵を取得する
    • openssl_pkey_get_public — 証明書から公開鍵を抽出し、使用できるようにする
    • openssl_pkey_new — 新規に秘密鍵を生成する
    • openssl_private_decrypt — 秘密鍵でデータを復号する
    • openssl_private_encrypt — 秘密鍵でデータを暗号化する
    • openssl_public_decrypt — 公開鍵でデータを復号する
    • openssl_public_encrypt — 公開鍵でデータを暗号化する
    • openssl_random_pseudo_bytes — 疑似ランダムなバイト文字列を生成する
    • openssl_seal — データをシール(暗号化)する
    • openssl_sign — 署名を生成する
    • openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
    • openssl_spki_export_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
    • openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する
    • openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する
    • openssl_verify — 署名を検証する
    • openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する
    • openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する
    • openssl_x509_export — 証明書を文字列としてエクスポートする
    • openssl_x509_export_to_file — 証明書をファイルにエクスポートする
    • openssl_x509_fingerprint — 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する
    • openssl_x509_free — 証明書リソースを開放する
    • openssl_x509_parse — X509 証明書をパースし、配列として情報を返す
    • openssl_x509_read — X.509 証明書をパースし、オブジェクトを返す
    • openssl_x509_verify — x509証明書のデジタル署名を公開鍵で検証する
  • OpenSSLCertificate — OpenSSLCertificate クラス
  • OpenSSLCertificateSigningRequest — OpenSSLCertificateSigningRequest クラス
  • OpenSSLAsymmetricKey — OpenSSLAsymmetricKey クラス


はじめに

この拡張モジュールは、対称鍵による暗号化、非対称鍵による暗号化や、 PBKDF2, PKCS7, PKCS12, X509 その他の暗号の操作を行う » OpenSSL ライブラリの機能をバインドしています。 それに加えて、TLS ストリームの実装も提供しています。

この拡張モジュールではまだサポートされていない機能が OpenSSL には多くあります。 それらのいくつかは将来的に追加される可能性があります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • OpenSSL
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

OpenSSL 関数を使用するためには、» OpenSSL ライブラリをインストールする必要があります。 PHP 7.0 の場合、OpenSSL >= 0.9.8 かつ < 1.2 が必要です。 PHP 7.1-8.0 の場合、OpenSSL >= 1.0.1 かつ < 3.0 が必要です。 PHP >= 8.1 の場合、OpenSSL >= 1.0.2 かつ < 4.0 が必要です。

警告

メンテナンスされている OpenSSL のバージョンを使用することを強く推奨します。 さもないと、Web サーバーへの攻撃に対しての脆弱性をかかえてしまいます。


インストール手順

PHP の OpenSSL サポートを使用するには、--with-openssl を指定して PHP を コンパイルする必要があります。

OpenSSL ライブラリを動作させるためには、実行時にさらに必要なものがあります。 特に、OpenSSL から乱数 (あるいは疑似乱数) 生成器にアクセスできなければなりません。 たいていの Unix および Unix 系のプラットフォーム (Linux など) の場合、 /dev/urandom あるいは /dev/random デバイスがこれにあたります。

configure オプション --with-system-ciphers が利用できます。 これにより、PHP がハードコードされたデフォルトではなく、システムが持つ暗号リストを使うようになります。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libeay32.dll, または、OpenSSL 1.1 以降では libcrypto-*.dll

加えてキー生成およびサイン認証関数を使用する計画がある場合、 システムに 有効な openssl.cnf をインストールする 必要があります。 Win32 バイナリ配布版にサンプル設定ファイルを同梱することにしました。 extras/ssl ディレクトリにあります。

PHP は、 以下のロジックにより openssl.cnf を探します。

  • 環境変数 OPENSSL_CONF が設定された場合、 設定ファイルの（ファイル名を含む）パスとして使用されます。
  • 環境変数 SSLEAY_CONF が設定された場合、 設定ファイルの（ファイル名を含む）パスとして使用されます。
  • ファイル openssl.cnf はデフォルトの認証エリアに あることが仮定され、openssl DLL がコンパイルされた時間で設定されます。 これは通常、デフォルトのファイル名が c:\usr\local\ssl\openssl.cnf (x64の場合), または C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86の場合), PHP 7.4.0 より前のバージョンでは C:\usr\local\ssl\openssl.cnf であることを意味します。

インストール時に、設定ファイルを デフォルトのパス または 他の場所にインストールし、(例えば仮想ホスト毎に)環境変数に設定ファ イルの場所を指定するかを選ぶ必要があります。 設定ファイルを必要とする関数の options に より、デフォルトのパスを上書きすることが可能であることに注意してください。
警告

権限がないユーザーに openssl.cnf を変更させないようにしてください。

変更履歴

バージョン | 説明
7.4.0 | --with-openssl[=DIR] は、ディレクトリ名を引数として受け入れなくなりました。 代わりに、pkg-config の変数 PKG_CONFIG_PATH を OpenSSL のインストールパスに設定するか、 環境変数 OPENSSL_LIBS と OPENSSL_CFLAGS を設定するようにしてください。
7.4.0 | OpenSSL のデフォルトの設定ファイルのパスが C:\usr\local\ssl から C:\Program Files\Common Files\SSL と C:\Program Files (x86)\Common Files\SSL にそれぞれ変更されました。


実行時設定

php.ini の設定により動作が変化します。

openssl 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
openssl.cafile | "" | INI_PERDIR |
openssl.capath | "" | INI_PERDIR |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

openssl.cafile string

ローカルファイルシステム上の証明書ファイルの場所。 verify_peer コンテキストオプションで リモートサーバーとの認証の際に使用します。

openssl.capath string

cafile が指定されていなかったりその場所にファイルが 見つからなかったりした場合、capath が指す ディレクトリを検索して認証ファイルを探します。capath は認証ファイルのディレクトリを正確に指している必要があります。

SSL コンテキスト オプションも参照ください。


リソース型

PHP 8.0.0 より前のバージョンでは、 OpenSSL モジュールで3つのリソースタイプが定義されていました:

  • OpenSSL key
  • OpenSSL X.509
  • OpenSSL X.509 CSR


定義済み定数

目次

  • 目的を調べるフラグ
  • 非対称暗号化のパディングフラグ
  • キーの型
  • PKCS7 フラグ/定数
  • CMS (暗号メッセージシンタックス) 関連のフラグ/定数
  • 署名アルゴリズム
  • 暗号化方式
  • バージョン定数
  • Server Name Indication 定数
  • その他の定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。


目的を調べるフラグ

X509_PURPOSE_SSL_CLIENT (int)
X509_PURPOSE_SSL_SERVER (int)
X509_PURPOSE_NS_SSL_SERVER (int)
X509_PURPOSE_SMIME_SIGN (int)
X509_PURPOSE_SMIME_ENCRYPT (int)
X509_PURPOSE_CRL_SIGN (int)
X509_PURPOSE_ANY (int)


非対称暗号化のパディングフラグ

OPENSSL_PKCS1_PADDING (int)
OPENSSL_SSLV23_PADDING (int)
OPENSSL_NO_PADDING (int)
OPENSSL_PKCS1_OAEP_PADDING (int)


キーの型

OPENSSL_KEYTYPE_RSA (int)
OPENSSL_KEYTYPE_DSA (int)
OPENSSL_KEYTYPE_DH (int)
OPENSSL_KEYTYPE_EC (int)
この定数が使えるのは、PHP をコンパイルする際に OpenSSL 0.9.8 以降を使ったときだけです。


PKCS7 フラグ/定数

S/MIME 関数はビットフィールドを使用して指定したフラグを使用します。 このビットフィールドには、以下の値を一つ以上含むことが可能です。

PKCS7 定数
定数 | 説明
PKCS7_TEXT (int) | text/plain content type ヘッダを暗号化/署名されたメッセージに 追加します。復号化または認証を行う際には、このヘッダは出力から 取り除かれます。復号化または認証されたメッセージが MIME 型 text/plain でない場合、エラーとなります。
PKCS7_BINARY (int) | 通常は、入力されたメッセージは CR および LF を行端として使用した 「正規化」された形式に変換されます。こらは、S/MIME の規格に 基づくものです。このオプションが指定された場合、変換は行われません。 この機能は、MIME 形式でないバイナリデータを処理する際に 便利です。
PKCS7_NOINTERN (int) | メッセージを認証する際に、通常、メッセージに含まれる証明書が 証明書にサインする際に検索されます。 このオプションでは、 openssl_pkcs7_verify() の untrusted_certificates_filename パラメータで指定した証明書 のみが使用されます。しかし、指定された証明書を信頼されていな い CA として使用することも可能です。
PKCS7_NOVERIFY (int) | サインつきメッセージをサインした証明書の署名について 検証しません。
PKCS7_NOCHAIN (int) | サインを行った側の証明書の認証の連鎖を行いません。 この場合、サイン付きのメッセージにある証明書を未認証の CA として使用しません。
PKCS7_NOCERTS (int) | メッセージにサインする際、通常はサインをする人の証明書が挿入 されますが、このオプションを指定した場合はそうなりません。これに よりサイン付きのメッセージのサイズは小さくなりますが、認証 側が（例えば、openssl_pkcs7_verify() の untrusted_certificates_filename を用いて渡すことにより） サインをした人の証明書のコピーをローカルに用意する必要があります。
PKCS7_NOATTR (int) | 通常、メッセージがサインされる時、サインした時間やサポートされる 対象アルゴリズムを含む一連の属性が付加されます。このオプションを 指定した場合、それらの属性は付加されません。
PKCS7_DETACHED (int) | メッセージにサインをする際、MIME型 "multipart/signed" を指定してクリアテキストでサインを行います。これは、 openssl_pkcs7_sign() において フラグを指定しなかった場合の flags パラメータのデフォルトです。このオプションをオフにした場合、 メッセージは不透明なサインによりサインされます。これは、 メールリレイによる変換に対してより耐性がありますが、S/MIME を サポートしないメールエージェントでは読むことはできません。
PKCS7_NOSIGS (int) | メッセージにサインや認証を試みません。
PKCS7_NOOLDMIMETYPE (int) | PHP 8.3.0 以降で利用可能です。 メッセージを暗号化する場合に、content-type の値として application/x-pkcs7-mime ではなく application/pkcs7-mime を設定します。


CMS (暗号メッセージシンタックス) 関連のフラグ/定数

CMS 関連の関数は、以下のうちひとつ以上の値をビットフィールドを使って指定することで、フラグを利用します。

CMS 関連の定数
定数 | 説明
OPENSSL_CMS_TEXT (int) | 暗号化済み/署名済み のメッセージに対して text/plain のヘッダを追加します。 復号化 または 検証する際に、これらのヘッダは出力から削除されます - もし 複号化済み/検証済み メッセージの MIMEタイプ が text/plain でない場合、エラーが発生します。
OPENSSL_CMS_BINARY (int) | 通常、入力されるメッセージは 行末を CR と LF として用いる "canonical" フォーマットに変換されます: これは、CMS の仕様です。 このオプションが指定されると、変換は行われません。 これは、 CMS フォーマットではない可能性があるバイナリデータを扱うのに便利です。
OPENSSL_CMS_NOINTERN (int) | メッセージを検証する際、 通常は(もしあれば)メッセージに含まれる証明書を 署名に用いた証明書として探します。 このオプションを使うと、 openssl_cms_verify() 関数の untrusted_certificates_filename 引数で指定した証明書だけを検証に使うようになります。 ここで証明書を指定しても、 それは信頼されない証明書のまま引き続き使われます。
OPENSSL_CMS_NOVERIFY (int) | 署名されたメッセージの、署名者の証明書を検証しません。
OPENSSL_CMS_NOCERTS (int) | メッセージに署名する場合、 通常は署名者の証明書がメッセージに付加されます - このオプションを使うと、その証明書を除去できます。 証明書を除去すると、署名済みのメッセージのサイズが減りますが、 (たとえば、openssl_cms_verify() 関数に untrusted_certificates_filename を使って渡すなどして) 検証する側が署名者の証明書をローカルに持っておく必要があります。
OPENSSL_CMS_NOATTR (int) | 通常、メッセージが署名済みの場合、 署名した時刻やサポートされている共通鍵アルゴリズムの情報が含まれる、 一連の属性情報が付加されます。 このオプションを使うと、その属性を含めないようにすることができます。
OPENSSL_CMS_DETACHED (int) | メッセージに署名する際、 MIMEタイプ "multipart/signed" を使って、 平文で署名します。 これは、openssl_cms_sign() で何も flags を指定しなかったときのデフォルトの動作です。 このオプションを無効にした場合、メッセージは opaque 署名を使って署名されます。 これは、メールがリレーされる際の変換を防ぐ一方で、 S/MIME をサポートしていないエージェントでは読めなくなります。
OPENSSL_CMS_NOSIGS (int) | メッセージの署名を検証しません。
OPENSSL_CMS_OLDMIMETYPE (int) | PHP 8.3.0 以降で利用可能です。 メッセージを暗号化する場合に、content-type の値として application/pkcs7-mime ではなく application/x-pkcs7-mime を設定します。


署名アルゴリズム

OPENSSL_ALGO_DSS1 (int)
OPENSSL_ALGO_SHA1 (int)
openssl_sign() および openssl_verify() のデフォルトアルゴリズムとして用いられます。
OPENSSL_ALGO_SHA224 (int)
OPENSSL_ALGO_SHA256 (int)
OPENSSL_ALGO_SHA384 (int)
OPENSSL_ALGO_SHA512 (int)
OPENSSL_ALGO_RMD160 (int)
OPENSSL_ALGO_MD5 (int)
OPENSSL_ALGO_MD4 (int)
OPENSSL_ALGO_MD2 (int)
この定数が使えるのは PHP のコンパイル時に MD2 サポートを有効にした場合だけになりました。 MD2 サポートを有効にするには、PHP のコンパイル時に -DHAVE_OPENSSL_MD2_H CFLAG を渡し、かつ OpenSSL 1.0.0 以降のコンパイル時に enable-md2 を指定する必要があります。


暗号化方式

OPENSSL_DEFAULT_STREAM_CIPHERS (string)
デフォルトの暗号リスト
OPENSSL_CIPHER_RC2_40 (int)
OPENSSL_CIPHER_RC2_128 (int)
OPENSSL_CIPHER_RC2_64 (int)
OPENSSL_CIPHER_DES (int)
OPENSSL_CIPHER_3DES (int)
OPENSSL_CIPHER_AES_128_CBC (int)
OPENSSL_CIPHER_AES_192_CBC (int)
OPENSSL_CIPHER_AES_256_CBC (int)


  • ≪ 暗号化方式
  • Server Name Indication 定数 ≫
  • PHP Manual
  • 定義済み定数
  • バージョン定数

バージョン定数

OPENSSL_VERSION_TEXT (string)
OPENSSL_VERSION_NUMBER (int)


Server Name Indication 定数

OPENSSL_TLSEXT_SERVER_NAME (int)
SNI サポートが有効か否か。

注意:

この定数を使うには、 OpenSSL 0.9.8j 以降を使って PHP をビルドしている必要があります。


その他の定数

OPENSSL_RAW_DATA (int)
openssl_encrypt() や openssl_decrypt() 関数で この値が設定されると、生のデータがそのまま返されます。 設定されない場合、Base64 エンコードされたデータが呼び出し側に返されます。
OPENSSL_DONT_ZERO_PAD_KEY (int)
デフォルトのキーの長さより短いキーについて openssl_encrypt() がパディングを行わないようにします。
OPENSSL_ZERO_PADDING (int)
デフォルトでは、暗号化の操作は標準的なブロックパディングを使ってパディングされ、 追加されたパディングは、復号化される際にチェックされ、除去されます。 openssl_encrypt() や openssl_decrypt() の options に OPENSSL_ZERO_PADDING が指定された場合、パディングは行われないので、 暗号化または復号化されるデータの総量はブロックサイズの倍数でなければなりません。 そうでない場合、エラーが発生します。
OPENSSL_ENCODING_SMIME (int)
エンコーディングが S/MIME 形式であることを示します。
OPENSSL_ENCODING_DER (int)
エンコーディングが DER 形式であることを示します。
OPENSSL_ENCODING_PEM (int)
エンコーディングが PEM 形式であることを示します。


キー/証明書パラメータ

OpenSSL 関数のうち、キーまたは証明書パラメータを必要とするものはごく一部です。 以下の方法を使用してそれらを取得できます。

  • 証明書

    1. openssl_x509_read() から返された OpenSSLCertificate クラスのインスタンス。 (PHP 8.0.0 より前のバージョンでは、OpenSSL X.509 型のリソース)
    2. file://path/to/cert.pem 形式の文字列。 このファイルは、PEM エンコードされた証明書である必要があります。
    3. PEM エンコードされた証明書の内容を含む文字列。 -----BEGIN CERTIFICATE----- から始まります。

  • 証明書の署名リクエスト (Certificate Signing Requests (CSRs))

    1. openssl_csr_new() 関数が返した OpenSSLCertificateSigningRequest クラスのインスタンス。 (PHP 8.0.0 より前のバージョンでは、 OpenSSL X.509 CSR 型のリソース)
    2. file://path/to/csr.pem 形式の文字列。 このファイルは、PEM エンコードされた証明書 (CSR) である必要があります。
    3. CSR, PEM エンコードされた証明書の内容を含む文字列。 -----BEGIN CERTIFICATE REQUEST----- から始まります。

  • 公開鍵/秘密鍵

    1. openssl_get_publickey() あるいは openssl_get_privatekey() から返された OpenSSLAsymmetricKey クラスのインスタンス。 (PHP 8.0.0 より前のバージョンでは、 OpenSSL key 型のリソース)
    2. 公開鍵のみ: OpenSSLCertificate クラスのインスタンス。 (PHP 8.0.0 より前のバージョンでは、 OpenSSL X.509 型のリソース)
    3. file://path/to/file.pem 形式の文字列。- このファイルは、PEM エンコードされた証明書/秘密鍵である 必要があります（両方を含むことも可能です）。
    4. PEM エンコードされた証明書/キーの内容を含む文字列。 -----BEGIN PUBLIC KEY----- から始まります。
    5. 秘密鍵については array($key, $passphrase) という構文を使用することも可能です。 ただし、$key は file:// または上記のテキスト表現形式を使用して指定したキー、 $passphrase はその秘密鍵に関するパスワードを有する文字列を表します。


証明書の認証

サイン/証明書を認証する関数をコールする際、 ca_info パラメータは、ファイルと認証済みの CA ファイルの場所を指定するファイルディレクトリ名を含む配列です。 ディレクトリが指定された場合、openssl コマンドが 使用できるような正しい形式にハッシュされたディレクトリである必要が あります。


OpenSSL 関数

目次

  • openssl_cipher_iv_length — 初期化ベクトル iv の長さを取得する
  • openssl_cipher_key_length — 暗号鍵の長さを取得する
  • openssl_cms_decrypt — CMS メッセージを復号化する
  • openssl_cms_encrypt — CMS メッセージを暗号化する
  • openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする
  • openssl_cms_sign — ファイルに署名する
  • openssl_cms_verify — CMS の署名を検証する
  • openssl_csr_export — CSR を文字列としてエクスポートする
  • openssl_csr_export_to_file — CSR をファイルにエクスポートする
  • openssl_csr_get_public_key — CSR の公開鍵を返す
  • openssl_csr_get_subject — CSR の subject を返す
  • openssl_csr_new — CSR を作成する
  • openssl_csr_sign — CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する
  • openssl_decrypt — データを復号する
  • openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する
  • openssl_digest — ダイジェストを計算する
  • openssl_encrypt — データを暗号化する
  • openssl_error_string — OpenSSL エラーメッセージを返す
  • openssl_free_key — キーリソースを開放する
  • openssl_get_cert_locations — 有効な証明書の格納場所を検索する
  • openssl_get_cipher_methods — 利用可能な暗号メソッドを取得
  • openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する
  • openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得
  • openssl_get_privatekey — openssl_pkey_get_private のエイリアス
  • openssl_get_publickey — openssl_pkey_get_public のエイリアス
  • openssl_open — シール(暗号化)されたデータをオープン(復号)する
  • openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する
  • openssl_pkcs12_export — PKCS#12 互換の証明書保存ファイルを変数にエクスポートする
  • openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする
  • openssl_pkcs12_read — PKCS#12 認証ストアをパースして配列形式にする
  • openssl_pkcs7_decrypt — S/MIME 暗号化されたメッセージを復号する
  • openssl_pkcs7_encrypt — S/MIME メッセージを暗号化する
  • openssl_pkcs7_read — PKCS7 ファイルを PEM証明書 の配列にエクスポートする
  • openssl_pkcs7_sign — S/MIME メッセージに署名する
  • openssl_pkcs7_verify — S/MIME で署名されたメッセージの署名を検証する
  • openssl_pkey_derive — リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する
  • openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する
  • openssl_pkey_export_to_file — エクスポート可能な形式で、キーをファイルに取得する
  • openssl_pkey_free — 秘密鍵を開放する
  • openssl_pkey_get_details — キーの詳細の配列を返す
  • openssl_pkey_get_private — 秘密鍵を取得する
  • openssl_pkey_get_public — 証明書から公開鍵を抽出し、使用できるようにする
  • openssl_pkey_new — 新規に秘密鍵を生成する
  • openssl_private_decrypt — 秘密鍵でデータを復号する
  • openssl_private_encrypt — 秘密鍵でデータを暗号化する
  • openssl_public_decrypt — 公開鍵でデータを復号する
  • openssl_public_encrypt — 公開鍵でデータを暗号化する
  • openssl_random_pseudo_bytes — 疑似ランダムなバイト文字列を生成する
  • openssl_seal — データをシール(暗号化)する
  • openssl_sign — 署名を生成する
  • openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_spki_export_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する
  • openssl_verify — 署名を検証する
  • openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する
  • openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する
  • openssl_x509_export — 証明書を文字列としてエクスポートする
  • openssl_x509_export_to_file — 証明書をファイルにエクスポートする
  • openssl_x509_fingerprint — 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する
  • openssl_x509_free — 証明書リソースを開放する
  • openssl_x509_parse — X509 証明書をパースし、配列として情報を返す
  • openssl_x509_read — X.509 証明書をパースし、オブジェクトを返す
  • openssl_x509_verify — x509証明書のデジタル署名を公開鍵で検証する


初期化ベクトル iv の長さを取得する

  • ≪ OpenSSL 関数
  • openssl_cipher_key_length ≫
  • PHP Manual
  • OpenSSL 関数
  • 初期化ベクトル iv の長さを取得する

openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — 初期化ベクトル iv の長さを取得する

説明

openssl_cipher_iv_length(string $cipher_algo): int|false

暗号初期化ベクトル (iv) の長さを取得します。

パラメータ

cipher_algo

暗号化方式。指定できる値は openssl_get_cipher_methods() を参照ください。

戻り値

成功した場合は暗号の長さ、失敗した場合には false を返します。

エラー / 例外

暗号アルゴリズムが未知の場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_cipher_iv_length() の例

<?php
$method = 'AES-128-CBC';
$ivlen = openssl_cipher_iv_length($method);

echo $ivlen;
?>

上の例の出力は、 たとえば以下のようになります。

16


暗号鍵の長さを取得する

  • ≪ openssl_cipher_iv_length
  • openssl_cms_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 暗号鍵の長さを取得する

openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — 暗号鍵の長さを取得する

説明

openssl_cipher_key_length(string $cipher_algo): int|false

暗号鍵の長さを取得します。

パラメータ

cipher_algo

暗号化方式。指定できる値は openssl_get_cipher_methods() を参照ください。

戻り値

成功した場合は暗号の長さを返します。 失敗した場合に false を返します.

エラー / 例外

暗号アルゴリズムが未知の場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_cipher_key_length() の例

<?php
$method = 'AES-128-CBC';

var_dump(openssl_cipher_key_length($method));
?>

上の例の出力は、 たとえば以下のようになります。

int(16)


CMS メッセージを復号化する

  • ≪ openssl_cipher_key_length
  • openssl_cms_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS メッセージを復号化する

openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — CMS メッセージを復号化する

説明

openssl_cms_decrypt(
string $input_filename,
string $output_filename,
#[\SensitiveParameter] OpenSSLCertificate|string $certificate,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null $private_key = null,
int $encoding = OPENSSL_ENCODING_SMIME
): bool

CMS メッセージを復号化します。

パラメータ

input_filename

暗号化された内容を含むファイル名。

output_filename

復号化した内容を書き込むファイル名。

certificate

メッセージの受け手の証明書のファイル名。

private_key

PKCS#8 形式の鍵を含むファイル名。

encoding

入力ファイルのエンコーディング。 OPENSSL_ENCODING_SMIME, OPENSSL_ENCODING_DER, OPENSSL_ENCODING_PEM のいずれかです。

戻り値

成功した場合に true を、失敗した場合に false を返します。


CMS メッセージを暗号化する

  • ≪ openssl_cms_decrypt
  • openssl_cms_read ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS メッセージを暗号化する

openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — CMS メッセージを暗号化する

説明

openssl_cms_encrypt(
string $input_filename,
string $output_filename,
OpenSSLCertificate|array|string $certificate,
?array $headers,
int $flags = 0,
int $encoding = OPENSSL_ENCODING_SMIME,
int $cipher_algo = OPENSSL_CIPHER_AES_128_CBC
): bool

この関数は、一人以上のメッセージの受け手に向けて、 それぞれの受け手の証明書を使ってメッセージを暗号化します。

パラメータ

input_filename

暗号化するファイル。

output_filename

ファイルの出力先。

certificate

暗号化されたメッセージの受け手の証明書。

headers

S/MIME を使う時に含めるヘッダ。

flags

CMS_sign に渡すフラグ。

encoding

出力のエンコーディング。 OPENSSL_ENCODING_SMIME, OPENSSL_ENCODING_DER, OPENSSL_ENCODING_PEM のいずれかです。

cipher_algo

使用する暗号化アルゴリズム。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | デフォルトの暗号化アルゴリズム (cipher_algo) が、 AES-128-CBC (OPENSSL_CIPHER_AES_128_CBC) になりました。 これより前のバージョンでは、 PKCS7/CMS (OPENSSL_CIPHER_RC2_40) が使われていました。


CMS ファイルを、PEM証明書の配列にエクスポートする

  • ≪ openssl_cms_encrypt
  • openssl_cms_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS ファイルを、PEM証明書の配列にエクスポートする

openssl_cms_read

(PHP 8)

openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする

説明

openssl_cms_read(string $input_filename, array &$certificates): bool

openssl_pkcs7_read() と似た処理を行います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

input_filename

certificates

戻り値

成功した場合に true を、失敗した場合に false を返します。


ファイルに署名する

  • ≪ openssl_cms_read
  • openssl_cms_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • ファイルに署名する

openssl_cms_sign

(PHP 8)

openssl_cms_sign — ファイルに署名する

説明

openssl_cms_sign(
string $input_filename,
string $output_filename,
OpenSSLCertificate|string $certificate,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
?array $headers,
int $flags = 0,
int $encoding = OPENSSL_ENCODING_SMIME,
?string $untrusted_certificates_filename = null
): bool

この関数は、X.509 証明書 と秘密鍵を使ってファイルに署名します。

パラメータ

input_filename

署名するファイル名。

output_filename

処理結果を出力するファイル名。

certificate

署名に使う証明書。 有効な値の一覧については、 キー/証明書パラメータ を参照ください。

private_key

certificate に関連付けられた秘密鍵。 有効な値の一覧については、 キー/証明書パラメータ を参照ください。

headers

S/MIME 形式の出力に含められるヘッダの配列。

flags

cms_sign() に渡すフラグ。

encoding

出力ファイルのエンコーディング。 OPENSSL_ENCODING_SMIME, OPENSSL_ENCODING_DER, OPENSSL_ENCODING_PEM のいずれかです。

untrusted_certificates_filename

署名に含まれる中間証明書。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 openssl_cms_sign() の例

<?php

openssl_cms_sign('input.txt', 'output.txt', 'file://cert.pem', 'file://privkey.pem', null, OPENSSL_CMS_BINARY, OPENSSL_ENCODING_DER, 'chain.pem');
?>


CMS の署名を検証する

  • ≪ openssl_cms_sign
  • openssl_csr_export ≫
  • PHP Manual
  • OpenSSL 関数
  • CMS の署名を検証する

openssl_cms_verify

(PHP 8)

openssl_cms_verify — CMS の署名を検証する

説明

openssl_cms_verify(
string $input_filename,
int $flags = 0,
?string $certificates = null,
array $ca_info = [],
?string $untrusted_certificates_filename = null,
?string $content = null,
?string $pk7 = null,
?string $sigfile = null,
int $encoding = OPENSSL_ENCODING_SMIME
): bool

この関数は、指定されたエンコーディングで CMS の署名を検証します。 署名には、Detached (外包)署名または Attached(内包)署名 のふたつがあります。

パラメータ

input_filename

入力ファイル。

flags

cms_verify() に渡すフラグ。

certificates

署名者の証明書のファイル。 オプションで、中間証明書も含めることができます。

ca_info

自己署名の認証局の証明書を含む配列。

untrusted_certificates_filename

追加の中間証明書を含むファイル名。

content

署名が外包である場合に、その内容を含むファイル。

pk7

sigfile

署名を保存するファイル名。

encoding

入力ファイルのエンコーディング。 OPENSSL_ENCODING_SMIME, OPENSSL_ENCODING_DER, OPENSSL_ENCODING_PEM のいずれかです。

戻り値

成功した場合に true を、失敗した場合に false を返します。


CSR を文字列としてエクスポートする

  • ≪ openssl_cms_verify
  • openssl_csr_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR を文字列としてエクスポートする

openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — CSR を文字列としてエクスポートする

説明

openssl_csr_export(OpenSSLCertificateSigningRequest|string $csr, string &$output, bool $no_text = true): bool

openssl_csr_export() は、Certificate Signing Request csr を受け取り、 それを output に PEMフォーマット として保存します。 このパラメータは参照で渡されます。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

output

成功した場合、この文字列には PEMエンコードされた CSR が入っています。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_export() の例

<?php
$subject = array(
"commonName" => "example.com",
);
$private_key = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$configargs = array(
'digest_alg' => 'sha256WithRSAEncryption'
);
$csr = openssl_csr_new($subject, $private_key, $configargs);
openssl_csr_export($csr, $csr_string);
echo $csr_string;
?>

参考

  • openssl_csr_export_to_file() - CSR をファイルにエクスポートする
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


CSR をファイルにエクスポートする

  • ≪ openssl_csr_export
  • openssl_csr_get_public_key ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR をファイルにエクスポートする

openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — CSR をファイルにエクスポートする

説明

openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string $csr, string $output_filename, bool $no_text = true): bool

openssl_csr_export_to_file() は、Certificate Signing Request csr を受け取り、 それを output_filename という名前のファイルに PEM フォーマットとして保存します。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

output_filename

出力ファイルへのパス。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_export_to_file() の例

<?php
$subject = array(
"commonName" => "example.com",
);
$private_key = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
openssl_pkey_export_to_file($private_key, 'example-priv.key');
// Along with the subject, the CSR contains the public key corresponding to the private key
openssl_csr_export_to_file($csr, 'example-csr.pem');
?>

参考

  • openssl_csr_export() - CSR を文字列としてエクスポートする
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


CSR の公開鍵を返す

  • ≪ openssl_csr_export_to_file
  • openssl_csr_get_subject ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR の公開鍵を返す

openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — CSR の公開鍵を返す

説明

openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string $csr, bool $short_names = true): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() 関数は、 csr から公開鍵を展開し、他の関数で利用できるよう準備します。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

short_names
警告

このパラメータは無視されます。

戻り値

成功した場合、OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースが返されていました。
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_get_public_key() の例

<?php
$subject = array(
"commonName" => "example.com",
);
$private_key = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
$public_key = openssl_csr_get_public_key($csr);
$info = openssl_pkey_get_details($public_key);
echo $info['key'];
?>

参考

  • openssl_csr_get_subject() - CSR の subject を返す
  • openssl_csr_new() - CSR を作成する
  • openssl_pkey_get_details() - キーの詳細の配列を返す
  • openssl_pkey_export_to_file() - エクスポート可能な形式で、キーをファイルに取得する
  • openssl_pkey_export() - エクスポート可能な形式で、キーを文字列に取得する


CSR の subject を返す

  • ≪ openssl_csr_get_public_key
  • openssl_csr_new ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR の subject を返す

openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — CSR の subject を返す

説明

openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string $csr, bool $short_names = true): array|false

openssl_csr_get_subject() 関数は、 csr にエンコードされた subject の識別名の情報を返します。 commonName (CN), organizationName (O), countryName (C) などが含まれます。

パラメータ

csr

使用できる値の一覧は CSR パラメータ を参照ください。

short_names

shortnames は、配列でデータがどのように インデックスされるかを制御します - shortnames が true の場合(デフォルト)、フィールドは短縮名を使ってインデックスされます。 false の場合、長い名前を使ってインデックされます - たとえば、 CN は commonName の短縮名です。

戻り値

subject の説明を記した連想配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | csr は、 OpenSSLCertificateSigningRequest クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_csr_get_subject() の例

<?php
$subject = array(
"countryName" => "CA",
"stateOrProvinceName" => "Alberta",
"localityName" => "Calgary",
"organizationName" => "XYZ Widgets Inc",
"organizationalUnitName" => "PHP Documentation Team",
"commonName" => "Wez Furlong",
"emailAddress" => "wez@example.com",
);
$private_key = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$configargs = array(
'digest_alg' => 'sha512WithRSAEncryption'
);
$csr = openssl_csr_new($subject, $privkey, $configargs);
print_r(openssl_csr_get_subject($csr));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [C] => CA
    [ST] => Alberta
    [L] => Calgary
    [O] => XYZ Widgets Inc
    [OU] => PHP Documentation Team
    [CN] => Wez Furlong
    [emailAddress] => wez@example.com
)

参考

  • openssl_csr_new() - CSR を作成する
  • openssl_csr_get_public_key() - CSR の公開鍵を返す
  • openssl_x509_parse() - X509 証明書をパースし、配列として情報を返す


CSR を作成する

  • ≪ openssl_csr_get_subject
  • openssl_csr_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR を作成する

openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — CSR を作成する

説明

openssl_csr_new(
array $distinguished_names,
#[\SensitiveParameter] OpenSSLAsymmetricKey &$private_key,
?array $options = null,
?array $extra_attributes = null
): OpenSSLCertificateSigningRequest|false

openssl_csr_new() は、新しい CSR を distinguished_names の情報に基づいて作成します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

distinguished_names

証明書で使用される識別名、またはsubjectフィールド。

private_key

private_key には、事前に openssl_pkey_new() （あるいはその他の openssl_pkey 系の関数）で作成した秘密鍵を設定します。 これに対応する公開鍵が、CSR への署名に使用されます。

options

デフォルトでは、システムの openssl.conf の設定に したがってリクエストが初期化されます。options のキー config_section_section を設定することで、この デフォルト項目を変更することが可能です。また、キー config に別の openssl 設定ファイルを指定することで別の設定を使用することも可能です。 もし options に以下の表のキーが存在すれば、それらは openssl.conf の対応する項目と同じ働きをします。

設定の上書き
options のキー | 型 | openssl.conf で同等の意味を持つ項目 | 説明
digest_alg | string | default_md | ダイジェストメソッド、または署名のハッシュ。 通常は openssl_get_md_methods() 関数のリストのうちのひとつです。
x509_extensions | string | x509_extensions | x509 証明書を作成する際に使用する拡張モジュールを選択します
req_extensions | string | req_extensions | CSR を作成する際に使用する拡張モジュールを選択します
private_key_bits | int | default_bits | 秘密鍵を作成する際に使用するビット数を指定します
private_key_type | int | none | 作成する秘密鍵の型を指定します。以下の定数 OPENSSL_KEYTYPE_DSA, OPENSSL_KEYTYPE_DH OPENSSL_KEYTYPE_RSA あるいは OPENSSL_KEYTYPE_EC からひとつ選択します。 デフォルト値は OPENSSL_KEYTYPE_RSA です。
encrypt_key | bool | encrypt_key | （パスフレーズとともに）エクスポートされるキーを暗号化するか?
encrypt_key_cipher | int | none | 暗号定数のうちの一つ。
curve_name | string | none | openssl_get_curve_names() のうちの一つ。
config | string | N/A | 代替の openssl.conf ファイルのパス

extra_attributes

extra_attributes は、CSR に関する追加の設定情報を 設定するために使用します。distinguished_names および extra_attributes はどちらも連想配列で、それらの キーが OID に変換されたうえでリクエストの関連する部分に適用されます。

戻り値

CSR を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLCertificateSigningRequest クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースが返されていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。
7.1.0 | options が、新たに curve_name をサポートしました。

例

例1 自己署名証明書の作成

<?php
// SSLサーバー証明書では、commonName はセキュアにするドメインです。
// S/MIME 電子メール証明書では、 commonName は電子メールアドレスのオーナーです。
// location と identification フィールドは、セキュアにするドメイン
// または電子メールのオーナーを参照します。
$dn = array(
"countryName" => "GB",
"stateOrProvinceName" => "Somerset",
"localityName" => "Glastonbury",
"organizationName" => "The Brain Room Limited",
"organizationalUnitName" => "PHP Documentation Team",
"commonName" => "Wez Furlong",
"emailAddress" => "wez@example.com"
);

// 新しい 秘密鍵(と公開鍵の) キーペアを生成します
$privkey = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));

// CSR を生成します
$csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

// 自己署名の証明書を生成します。365日有効です
$x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

// 秘密鍵、CSR と自己署名証明書をあとで使うために保存します。
openssl_csr_export($csr, $csrout) and var_dump($csrout);
openssl_x509_export($x509, $certout) and var_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

// 起きたエラーを表示します。
while (($e = openssl_error_string()) !== false) {
echo $e . "\n";
}
?>

例2 自己署名の ECC 証明書を作成する (PHP 7.1.0 以降)

<?php
$subject = array(
"commonName" => "docs.php.net",
);

// 新しい 秘密鍵(と公開鍵の) キーペアを生成します
$private_key = openssl_pkey_new(array(
"private_key_type" => OPENSSL_KEYTYPE_EC,
"curve_name" => 'prime256v1',
));

// CSR を生成します
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

// 自己署名のEC証明書を生成します。
$x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
openssl_x509_export_to_file($x509, 'ecc-cert.pem');
openssl_pkey_export_to_file($private_key, 'ecc-private.key');
?>

参考

  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する

  • ≪ openssl_csr_new
  • openssl_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する

openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する

説明

openssl_csr_sign(
OpenSSLCertificateSigningRequest|string $csr,
OpenSSLCertificate|string|null $ca_certificate,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
int $days,
?array $options = null,
int $serial = 0,
?string $serial_hex = null
): OpenSSLCertificate|false

openssl_csr_sign() は、 指定した CSR を用いて x509 証明書を作成します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

csr

事前に openssl_csr_new() で作成した CSR。 file://path/to/csr のように指定された PEM エンコードされた CSR へのパス、 あるいは openssl_csr_export() で生成した文字列も使用可能です。

ca_certificate

作成された証明書は ca_certificate で署名されます。 ca_certificate が null の場合は、自己署名の証明書となります。

private_key

private_key は ca_certificate に対応する秘密鍵です。

days

days は、作成された証明書の有効期限を日数で指定します。

options

options で CSR の詳細設定が可能です。 options についての詳細な情報は openssl_csr_new() を参照ください。

serial

発行される証明書のシリアル番号を、オプションで指定します。 省略した場合のデフォルトは 0 です。

戻り値

成功した場合に OpenSSLCertificate オブジェクト。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLCertificate クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを返していました。
8.0.0 | csr は、 OpenSSLCertificateSigningRequest のインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | ca_certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_csr_sign() の例 - CSR に署名する（あなた自身の CA を作成する）

<?php
// このスクリプトでは、前のページのテキストエリアから受け取った
// CSR を利用すると仮定します。
$csrdata = $_POST["CSR"];

// ここでは自己認証局の証明書を用いて署名要求に署名します。
// どんな証明書でも署名は可能ですが、署名に用いる証明書が
// 新たに署名される証明書を取り扱うであろうソフトウェアや
// ユーザーらに信頼されていない限り、その手続きは無意味です。

// 自己認証局証明書とその秘密鍵が必要です。
$cacert = "file://path/to/ca.crt";
$privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");

$usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

// ユーザーがローカル設定（SSL サーバー用の証明書
// ファイルなど）にコピー＆ペーストできるように
// 作成された証明書をそのまま表示します。
openssl_x509_export($usercert, $certout);
echo $certout;

// 発生したエラーをすべて表示します。
while (($e = openssl_error_string()) !== false) {
echo $e . "\n";
}
?>


データを復号する

  • ≪ openssl_csr_sign
  • openssl_dh_compute_key ≫
  • PHP Manual
  • OpenSSL 関数
  • データを復号する

openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — データを復号する

説明

openssl_decrypt(
string $data,
string $cipher_algo,
#[\SensitiveParameter] string $passphrase,
int $options = 0,
string $iv = "",
?string $tag = null,
string $aad = ""
): string|false

未加工の、または base64 エンコードされた文字列を受け取り、 与えられた暗号化方式とキーを使って文字列を復号します。

パラメータ

data

復号化する、暗号化されたメッセージ。

cipher_algo

暗号化方式。利用可能な暗号化方式のリストについては、 openssl_get_cipher_methods() を使用してください。

passphrase

キー

options

OPENSSL_RAW_DATA, OPENSSL_ZERO_PADDING, OPENSSL_DONT_ZERO_PAD_KEY のいずれか。

iv

NULL ではない初期化ベクトル

tag

AEAD 暗号モードの認証タグ。 正しくない場合、認証は失敗し、関数は false を返します。

警告

tag の長さをこの関数はチェックしません。 この値の長さは openssl_encrypt() を呼び出した時に取得できるものと一致させなければならず、それは呼び出し側の責任です。 一致しない場合でも、与えられた値が適切な tag の先頭部分と一致した場合に復号が成功するかもしれません。

aad

追加の認証済みデータ。

戻り値

成功した場合復号化された文字列、失敗した場合に false を返します。

エラー / 例外

cipher_algo パラメータに未知の暗号アルゴリズムが渡された場合、 E_WARNING レベルのエラーが発生します。

iv パラメータに空の値が渡された場合、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.1.0 | tag は、nullable になりました。
7.1.0 | tag および aad パラメータが追加されました。

参考

  • openssl_encrypt() - データを暗号化する


ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

  • ≪ openssl_decrypt
  • openssl_digest ≫
  • PHP Manual
  • OpenSSL 関数
  • ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

説明

openssl_dh_compute_key(string $public_key, #[\SensitiveParameter] OpenSSLAsymmetricKey $private_key): string|false

openssl_dh_compute_key() 関数が返す共有シークレットは、 リモート側と秘密の通信をするための暗号鍵としてよく使われます。 これはディフィー・ヘルマン鍵共有として知られています。

注意: ECDH は、PHP 8.1.0 以降、かつ OpenSSL 3.0.0 以降でのみサポートされています。

パラメータ

public_key

リモート側の DH 公開鍵

private_key

ローカル側の DH 秘密鍵。 これは、リモート側と共有している公開鍵に対応します。

戻り値

成功した場合、共有シークレットを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。

例

例1 共有シークレットを計算する

まず DH 公開鍵/秘密鍵 キーペア をローカルで生成します。 そしてリモート側でも同じことをします。 openssl コマンドラインユーティリティを使う必要があります。

# generate private/public key keypair
openssl dhparam -out dhparam.pem 2048
openssl genpkey -paramfile dhparam.pem -out privatekey.pem

# extract public key only
openssl pkey -in privatekey.pem -pubout -out publickey.pem

次に、あなたの公開鍵をリモート側に送ります。 あなたが送る公開鍵をリモート側で調べるために、 openssl pkey コマンドを使ってください。

openssl pkey -pubin -in remotepublickey.pem -text -noout

上の例の出力は、 たとえば以下のようになります。

PKCS#3 DH Public-Key: (2048 bit)
    public-key:
        67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
        9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
        42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
        88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
        77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
        98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
        79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
        d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
        f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
        0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
        4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
        37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
        94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
        aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
        74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
        87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
        a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
        36
 [...abbreviated...]

この公開鍵を openssl_dh_compute_key() のパラメーターとして渡し、 共有シークレットを計算します

<?php
$remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';

$local_priv_key = openssl_pkey_get_private('file://privatekey.pem');

$shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
echo bin2hex($shared_secret)."\n";
?>

例2 DH public/private キーペアをPHPで生成する

まず、DH prime を生成します。

openssl dhparam -out dhparam.pem 2048
openssl dh -in dhparam.pem -noout  -text

上の例の出力は、 たとえば以下のようになります。

PKCS#3 DH Parameters: (2048 bit)
        prime:
            00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
            4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
            d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
            e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
            12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
            78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
            55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
            34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
            f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
            4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
            7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
            fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
            a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
            9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
            40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
            cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
            22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
            62:6b
        generator: 2 (0x2)

prime と generator の値を 'p' と 'g' として openssl_pkey_new() 関数に渡します。

<?php
$configargs = array();
$configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
$configargs['g'] = hex2bin('02');
$private_key = openssl_pkey_new(array('dh' => $configargs));
openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');

$details = openssl_pkey_get_details($private_key);
$local_pub_key = $details['dh']['pub_key'];
echo bin2hex($local_pub_key)."\n";//you can send your public key to the remote party

$details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
$remote_public_key = $details['dh']['pub_key'];
$shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
echo bin2hex($shared_secret)."\n";
?>

参考

  • openssl_pkey_new() - 新規に秘密鍵を生成する
  • openssl_pkey_get_details() - キーの詳細の配列を返す
  • openssl_pkey_get_private() - 秘密鍵を取得する
  • openssl_pkey_get_public() - 証明書から公開鍵を抽出し、使用できるようにする


ダイジェストを計算する

  • ≪ openssl_dh_compute_key
  • openssl_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • ダイジェストを計算する

openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — ダイジェストを計算する

説明

openssl_digest(string $data, string $digest_algo, bool $binary = false): string|false

与えられたメソッドを使って、与えられたデータに対するダイジェスト・ハッシュ値を計算し、 未加工の、または binhex エンコードされた文字列を返します。

パラメータ

data

データ

digest_algo

ダイジェスト・メソッド。例: "sha256"。 利用可能なダイジェストメソットの一覧は、 openssl_get_md_methods() を参照ください。

binary

true に設定すると未加工の出力データとして返します。 そうでなければ binhex エンコードされた値を返します。

戻り値

成功した場合ダイジェスト・ハッシュ値、失敗した場合に false を返します。

エラー / 例外

digest_algo パラメータを通じて未知の署名アルゴリズムが渡された場合、 E_WARNING レベルのエラーを発生します。

参考

  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得


データを暗号化する

  • ≪ openssl_digest
  • openssl_error_string ≫
  • PHP Manual
  • OpenSSL 関数
  • データを暗号化する

openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — データを暗号化する

説明

openssl_encrypt(
#[\SensitiveParameter] string $data,
string $cipher_algo,
#[\SensitiveParameter] string $passphrase,
int $options = 0,
string $iv = "",
string &$tag = null,
string $aad = "",
int $tag_length = 16
): string|false

与えられた文字列を与えられたメソッドとキーで暗号化して、 未加工の、または base64 エンコードされた文字列を返します。

パラメータ

data

暗号化するプレーンテキストメッセージ

cipher_algo

暗号メソッド。 使用可能なメソッドの一覧を取得するには、openssl_get_cipher_methods() を用います。

passphrase

パスフレーズ。 期待された長さより短かった場合は、 黙ってNUL 文字で埋められます。 期待された長さより長かった場合は、 黙って切り詰められます。

options

OPENSSL_RAW_DATA, OPENSSL_ZERO_PADDING, OPENSSL_DONT_ZERO_PAD_KEY とのビット OR。

iv

NULL ではない初期化ベクトル。

tag

AEAD 暗号モード (GCM または CCM) を使う場合の 認証タグをリファレンスで渡します。

aad

追加の認証済みデータ

tag_length

認証 tag の長さ。 GCMモードでは、この値は 4 から 16 の間です。

戻り値

成功した場合暗号化された文字列、失敗した場合に false を返します。

エラー / 例外

cipher_algo パラメータを通じて未知の暗号アルゴリズムが渡された場合、 E_WARNING レベルのエラーを発生します。

iv パラメータを通じて空値が渡された場合、 E_WARNING レベルのエラーを発生します。

変更履歴

バージョン | 説明
7.1.0 | tag、aad および tag_length パラメータが追加されました。

例

例1 PHP 7.1以降で、AES を GCMモードで使う例

<?php
//$key should have been previously generated in a cryptographically safe way, like openssl_random_pseudo_bytes
$plaintext = "message to be encrypted";
$cipher = "aes-128-gcm";
if (in_array($cipher, openssl_get_cipher_methods()))
{
$ivlen = openssl_cipher_iv_length($cipher);
$iv = openssl_random_pseudo_bytes($ivlen);
$ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
//store $cipher, $iv, and $tag for decryption later
$original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
echo $original_plaintext."\n";
}
?>

例2 PHP 7.1 より前のバージョンで、AES を使う例

<?php
//$key previously generated safely, ie: openssl_random_pseudo_bytes
$plaintext = "message to be encrypted";
$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
$iv = openssl_random_pseudo_bytes($ivlen);
$ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
$hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
$ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

//decrypt later....
$c = base64_decode($ciphertext);
$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
$iv = substr($c, 0, $ivlen);
$hmac = substr($c, $ivlen, $sha2len=32);
$ciphertext_raw = substr($c, $ivlen+$sha2len);
$original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
$calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
if (hash_equals($hmac, $calcmac))// timing attack safe comparison
{
echo $original_plaintext."\n";
}
?>

参考

  • openssl_decrypt() - データを復号する


OpenSSL エラーメッセージを返す

  • ≪ openssl_encrypt
  • openssl_free_key ≫
  • PHP Manual
  • OpenSSL 関数
  • OpenSSL エラーメッセージを返す

openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — OpenSSL エラーメッセージを返す

説明

openssl_error_string(): string|false

openssl_error_string() は、 OpenSSL ライブラリから直近のエラーを返します。 エラーメッセージはキューに格納されるので、 すべての情報を集めるにはこの関数を複数回コールする必要があります。 最後のエラーが、いちばん最近に発生したエラーとなります。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーメッセージ文字列を返します。 エラーメッセージがもうない場合は、false を返します。

例

例1 openssl_error_string() の例

<?php
// ここで、処理に失敗する OpenSSL 関数をコールしたと仮定します
while ($msg = openssl_error_string())
echo $msg . "<br />\n";
?>


キーリソースを開放する

  • ≪ openssl_error_string
  • openssl_get_cert_locations ≫
  • PHP Manual
  • OpenSSL 関数
  • キーリソースを開放する

openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — キーリソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

openssl_free_key(OpenSSLAsymmetricKey $key): void

openssl_free_key() は、指定した key が指すキーをメモリから開放します。

パラメータ

key

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行してもなんの効果もないからです。
8.0.0 | key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。


有効な証明書の格納場所を検索する

  • ≪ openssl_free_key
  • openssl_get_cipher_methods ≫
  • PHP Manual
  • OpenSSL 関数
  • 有効な証明書の格納場所を検索する

openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — 有効な証明書の格納場所を検索する

説明

openssl_get_cert_locations(): array

openssl_get_cert_locations() は SSL 証明書の検出された有効な証明書の格納場所についての 情報の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

有効な証明書の格納場所の配列を返します。

例

例1 openssl_get_cert_locations() の例

<?php
var_dump(openssl_get_cert_locations());
?>

上の例の出力は以下となります。

array(8) {
  ["default_cert_file"]=>
  string(21) "/usr/lib/ssl/cert.pem"
  ["default_cert_file_env"]=>
  string(13) "SSL_CERT_FILE"
  ["default_cert_dir"]=>
  string(18) "/usr/lib/ssl/certs"
  ["default_cert_dir_env"]=>
  string(12) "SSL_CERT_DIR"
  ["default_private_dir"]=>
  string(20) "/usr/lib/ssl/private"
  ["default_default_cert_area"]=>
  string(12) "/usr/lib/ssl"
  ["ini_cafile"]=>
  string(0) ""
  ["ini_capath"]=>
  string(0) ""
}


利用可能な暗号メソッドを取得

  • ≪ openssl_get_cert_locations
  • openssl_get_curve_names ≫
  • PHP Manual
  • OpenSSL 関数
  • 利用可能な暗号メソッドを取得

openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — 利用可能な暗号メソッドを取得

説明

openssl_get_cipher_methods(bool $aliases = false): array

利用可能な暗号メソッドの一覧を取得します。

パラメータ

aliases

返される array に暗号のエイリアスを含めるべき場合、 true に設定します

戻り値

利用可能な暗号メソッドの array OpenSSL 1.1.1 より前のバージョンでは、 暗号メソッドは大文字、小文字両方で記されたものを返していました。 OpenSSL 1.1.1 以降では、小文字のみで記されたものが返されることに注意して下さい。

例

例1 openssl_get_cipher_methods() の例

どのように利用可能な暗号が見るか、およびどのエイリアスが利用可能か示します。

<?php
$ciphers = openssl_get_cipher_methods();
$ciphers_and_aliases = openssl_get_cipher_methods(true);
$cipher_aliases = array_diff($ciphers_and_aliases, $ciphers);

//ECB mode should be avoided
$ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

//At least as early as Aug 2016, Openssl declared the following weak: RC2, RC4, DES, 3DES, MD5 based
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
$ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
$cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
$cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

print_r($ciphers);
print_r($cipher_aliases);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => aes-128-cbc
    [1] => aes-128-cbc-hmac-sha1
    [2] => aes-128-cbc-hmac-sha256
    [3] => aes-128-ccm
    [4] => aes-128-cfb
    [5] => aes-128-cfb1
    [6] => aes-128-cfb8
    [7] => aes-128-ctr
    [9] => aes-128-gcm
    [10] => aes-128-ocb
    [11] => aes-128-ofb
    [12] => aes-128-xts
    [13] => aes-192-cbc
    [14] => aes-192-ccm
    [15] => aes-192-cfb
    [16] => aes-192-cfb1
    [17] => aes-192-cfb8
    [18] => aes-192-ctr
    [20] => aes-192-gcm
    [21] => aes-192-ocb
    [22] => aes-192-ofb
    [23] => aes-256-cbc
    [24] => aes-256-cbc-hmac-sha1
    [25] => aes-256-cbc-hmac-sha256
    [26] => aes-256-ccm
    [27] => aes-256-cfb
    [28] => aes-256-cfb1
    [29] => aes-256-cfb8
    [30] => aes-256-ctr
    [32] => aes-256-gcm
    [33] => aes-256-ocb
    [34] => aes-256-ofb
    [35] => aes-256-xts
    [36] => aria-128-cbc
    [37] => aria-128-ccm
    [38] => aria-128-cfb
    [39] => aria-128-cfb1
    [40] => aria-128-cfb8
    [41] => aria-128-ctr
    [43] => aria-128-gcm
    [44] => aria-128-ofb
    [45] => aria-192-cbc
    [46] => aria-192-ccm
    [47] => aria-192-cfb
    [48] => aria-192-cfb1
    [49] => aria-192-cfb8
    [50] => aria-192-ctr
    [52] => aria-192-gcm
    [53] => aria-192-ofb
    [54] => aria-256-cbc
    [55] => aria-256-ccm
    [56] => aria-256-cfb
    [57] => aria-256-cfb1
    [58] => aria-256-cfb8
    [59] => aria-256-ctr
    [61] => aria-256-gcm
    [62] => aria-256-ofb
    [63] => bf-cbc
    [64] => bf-cfb
    [66] => bf-ofb
    [67] => camellia-128-cbc
    [68] => camellia-128-cfb
    [69] => camellia-128-cfb1
    [70] => camellia-128-cfb8
    [71] => camellia-128-ctr
    [73] => camellia-128-ofb
    [74] => camellia-192-cbc
    [75] => camellia-192-cfb
    [76] => camellia-192-cfb1
    [77] => camellia-192-cfb8
    [78] => camellia-192-ctr
    [80] => camellia-192-ofb
    [81] => camellia-256-cbc
    [82] => camellia-256-cfb
    [83] => camellia-256-cfb1
    [84] => camellia-256-cfb8
    [85] => camellia-256-ctr
    [87] => camellia-256-ofb
    [88] => cast5-cbc
    [89] => cast5-cfb
    [91] => cast5-ofb
    [92] => chacha20
    [93] => chacha20-poly1305
    [111] => id-aes128-CCM
    [112] => id-aes128-GCM
    [113] => id-aes128-wrap
    [114] => id-aes128-wrap-pad
    [115] => id-aes192-CCM
    [116] => id-aes192-GCM
    [117] => id-aes192-wrap
    [118] => id-aes192-wrap-pad
    [119] => id-aes256-CCM
    [120] => id-aes256-GCM
    [121] => id-aes256-wrap
    [122] => id-aes256-wrap-pad
    [124] => idea-cbc
    [125] => idea-cfb
    [127] => idea-ofb
    [137] => seed-cbc
    [138] => seed-cfb
    [140] => seed-ofb
    [141] => sm4-cbc
    [142] => sm4-cfb
    [143] => sm4-ctr
    [145] => sm4-ofb
)
Array
(
    [36] => aes128
    [37] => aes128-wrap
    [38] => aes192
    [39] => aes192-wrap
    [40] => aes256
    [41] => aes256-wrap
    [69] => aria128
    [70] => aria192
    [71] => aria256
    [72] => bf
    [77] => blowfish
    [99] => camellia128
    [100] => camellia192
    [101] => camellia256
    [102] => cast
    [103] => cast-cbc
    [146] => idea
    [164] => seed
    [169] => sm4
)

参考

  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得


ECC で利用可能な楕円曲線の名前を取得する

  • ≪ openssl_get_cipher_methods
  • openssl_get_md_methods ≫
  • PHP Manual
  • OpenSSL 関数
  • ECC で利用可能な楕円曲線の名前を取得する

openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する

説明

openssl_get_curve_names(): array|false

楕円曲線暗号(ECC) の公開鍵/秘密鍵の操作に使う、 利用可能な楕円曲線の名前の一覧を取得します。 もっとも広く使われている標準的な/サポートされている曲線名は prime256v1 (NIST P-256) と secp384r1 (NIST P-384) です。

AES, RSA, DSA のキーサイズとおおよそ等しい ECC のキーサイズ
AES Symmetric Keysize (Bits) | RSA and DSA Keysize (Bits) | ECC Keysize (Bits)
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512
» NIST は ECC の楕円曲線を少なくとも256ビットで使うことを推奨しています

パラメータ

この関数にはパラメータはありません。

戻り値

利用可能な曲線名の array を返します。 失敗した場合に false を返します

例

例1 openssl_get_curve_names() の例

<?php
$curve_names = openssl_get_curve_names();
print_r($curve_names);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => secp112r1
    [1] => secp112r2
    [2] => secp128r1
    [3] => secp128r2
    [4] => secp160k1
    [5] => secp160r1
    [6] => secp160r2
    [7] => secp192k1
    [8] => secp224k1
    [9] => secp224r1
    [10] => secp256k1
    [11] => secp384r1
    [12] => secp521r1
    [13] => prime192v1
    [14] => prime192v2
    [15] => prime192v3
    [16] => prime239v1
    [17] => prime239v2
    [18] => prime239v3
    [19] => prime256v1
    [20] => sect113r1
    [21] => sect113r2
    [22] => sect131r1
    [23] => sect131r2
    [24] => sect163k1
    [25] => sect163r1
    [26] => sect163r2
    [27] => sect193r1
    [28] => sect193r2
    [29] => sect233k1
    [30] => sect233r1
    [31] => sect239k1
    [32] => sect283k1
    [33] => sect283r1
    [34] => sect409k1
    [35] => sect409r1
    [36] => sect571k1
    [37] => sect571r1
    [38] => c2pnb163v1
    [39] => c2pnb163v2
    [40] => c2pnb163v3
    [41] => c2pnb176v1
    [42] => c2tnb191v1
    [43] => c2tnb191v2
    [44] => c2tnb191v3
    [45] => c2pnb208w1
    [46] => c2tnb239v1
    [47] => c2tnb239v2
    [48] => c2tnb239v3
    [49] => c2pnb272w1
    [50] => c2pnb304w1
    [51] => c2tnb359v1
    [52] => c2pnb368w1
    [53] => c2tnb431r1
    [54] => wap-wsg-idm-ecid-wtls1
    [55] => wap-wsg-idm-ecid-wtls3
    [56] => wap-wsg-idm-ecid-wtls4
    [57] => wap-wsg-idm-ecid-wtls5
    [58] => wap-wsg-idm-ecid-wtls6
    [59] => wap-wsg-idm-ecid-wtls7
    [60] => wap-wsg-idm-ecid-wtls8
    [61] => wap-wsg-idm-ecid-wtls9
    [62] => wap-wsg-idm-ecid-wtls10
    [63] => wap-wsg-idm-ecid-wtls11
    [64] => wap-wsg-idm-ecid-wtls12
    [65] => Oakley-EC2N-3
    [66] => Oakley-EC2N-4
    [67] => brainpoolP160r1
    [68] => brainpoolP160t1
    [69] => brainpoolP192r1
    [70] => brainpoolP192t1
    [71] => brainpoolP224r1
    [72] => brainpoolP224t1
    [73] => brainpoolP256r1
    [74] => brainpoolP256t1
    [75] => brainpoolP320r1
    [76] => brainpoolP320t1
    [77] => brainpoolP384r1
    [78] => brainpoolP384t1
    [79] => brainpoolP512r1
    [80] => brainpoolP512t1
)


利用可能なダイジェスト・メソッドを取得

  • ≪ openssl_get_curve_names
  • openssl_get_privatekey ≫
  • PHP Manual
  • OpenSSL 関数
  • 利用可能なダイジェスト・メソッドを取得

openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得

説明

openssl_get_md_methods(bool $aliases = false): array

利用可能なダイジェスト・メソッドの一覧を取得します。

パラメータ

aliases

返される array にダイジェストのエイリアスを含めるべき場合、 true に設定します

戻り値

利用可能なダイジェスト・メソッドの array

例

例1 openssl_get_md_methods() の例

どのように利用可能なダイジェストが見るか、およびどのエイリアスが利用可能か示します。

<?php
$digests = openssl_get_md_methods();
$digests_and_aliases = openssl_get_md_methods(true);
$digest_aliases = array_diff($digests_and_aliases, $digests);

print_r($digests);

print_r($digest_aliases);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => DSA
    [1] => DSA-SHA
    [2] => MD2
    [3] => MD4
    [4] => MD5
    [5] => RIPEMD160
    [6] => SHA
    [7] => SHA1
    [8] => SHA224
    [9] => SHA256
    [10] => SHA384
    [11] => SHA512
    [12] => dsaEncryption
    [13] => dsaWithSHA
    [14] => ecdsa-with-SHA1
    [15] => md2
    [16] => md4
    [17] => md5
    [18] => ripemd160
    [19] => sha
    [20] => sha1
    [21] => sha224
    [22] => sha256
    [23] => sha384
    [24] => sha512
)
Array
(
    [2] => DSA-SHA1
    [3] => DSA-SHA1-old
    [4] => DSS1
    [9] => RSA-MD2
    [10] => RSA-MD4
    [11] => RSA-MD5
    [12] => RSA-RIPEMD160
    [13] => RSA-SHA
    [14] => RSA-SHA1
    [15] => RSA-SHA1-2
    [16] => RSA-SHA224
    [17] => RSA-SHA256
    [18] => RSA-SHA384
    [19] => RSA-SHA512
    [28] => dsaWithSHA1
    [29] => dss1
    [32] => md2WithRSAEncryption
    [34] => md4WithRSAEncryption
    [36] => md5WithRSAEncryption
    [37] => ripemd
    [39] => ripemd160WithRSA
    [40] => rmd160
    [43] => sha1WithRSAEncryption
    [45] => sha224WithRSAEncryption
    [47] => sha256WithRSAEncryption
    [49] => sha384WithRSAEncryption
    [51] => sha512WithRSAEncryption
    [52] => shaWithRSAEncryption
    [53] => ssl2-md5
    [54] => ssl3-md5
    [55] => ssl3-sha1
)

参考

  • openssl_digest() - ダイジェストを計算する
  • openssl_get_cipher_methods() - 利用可能な暗号メソッドを取得


openssl_pkey_get_private のエイリアス

  • ≪ openssl_get_md_methods
  • openssl_get_publickey ≫
  • PHP Manual
  • OpenSSL 関数
  • openssl_pkey_get_private のエイリアス

openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — openssl_pkey_get_private() のエイリアス

説明

この関数は次の関数のエイリアスです。 openssl_pkey_get_private().


openssl_pkey_get_public のエイリアス

  • ≪ openssl_get_privatekey
  • openssl_open ≫
  • PHP Manual
  • OpenSSL 関数
  • openssl_pkey_get_public のエイリアス

openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — openssl_pkey_get_public() のエイリアス

説明

この関数は次の関数のエイリアスです。 openssl_pkey_get_public().


シール(暗号化)されたデータをオープン(復号)する

  • ≪ openssl_get_publickey
  • openssl_pbkdf2 ≫
  • PHP Manual
  • OpenSSL 関数
  • シール(暗号化)されたデータをオープン(復号)する

openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — シール(暗号化)されたデータをオープン(復号)する

説明

openssl_open(
string $data,
#[\SensitiveParameter] string &$output,
string $encrypted_key,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
string $cipher_algo,
?string $iv = null
): bool

openssl_open() は、キー ID private_key およびエンベロープキー encrypted_key に関連する公開鍵を使用して、 data をオープン(復号)します。 その上で、output を復号化したデータで埋めます。 エンベロープキーは、データがシール(暗号化)された際に生成され、特定の 一つの公開鍵でのみ使用することが可能です。詳細な情報については、 openssl_seal() を参照ください。

パラメータ

data

output

成功した場合、オープンしたデータをここに返します。

encrypted_key

private_key

cipher_algo

暗号化方式

警告

デフォルト値 ('RC4') はセキュアでない値です。 明示的にセキュアな暗号化方式を指定することを強く推奨します。

iv

初期化ベクトル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | cipher_algo は、 オプションではなくなりました。

例

例1 openssl_open() の例

<?php
// $sealed および $env_key に暗号化されたデータおよびエンベロープキー
// が含まれていると仮定。共にシール元(暗号化側)から与えられる。

// ファイルから公開鍵を取得し、使用可能とする
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);

// データを復号化し、$open に保存
if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
echo "here is the opened data: ", $open;
} else {
echo "failed to open data";
}

// 公開鍵をメモリから開放
openssl_free_key($pkeyid);
?>

参考

  • openssl_seal() - データをシール(暗号化)する


PKCS5 v2 の PBKDF2 文字列を生成する

  • ≪ openssl_open
  • openssl_pkcs12_export ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS5 v2 の PBKDF2 文字列を生成する

openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する

説明

openssl_pbkdf2(
#[\SensitiveParameter] string $password,
string $salt,
int $key_length,
int $iterations,
string $digest_algo = "sha1"
): string|false

openssl_pbkdf2() 関数は、PBKDF2 (Password-Based Key Derivation Function 2 の略。PKCS5 v2 で定義されている鍵導出関数) 文字列を計算します

パラメータ

password

導出されるキーを生成するパスワード

salt

PBKDF2 は、暗号化のソルトとして、少なくとも64ビット(8バイト)を推奨しています。

key_length

出力されるキーの長さ

iterations

イテレーションの回数。 » NIST は少なくとも10000を推奨しています.

digest_algo

オプションのハッシュまたはダイジェストアルゴリズム。 アルゴリズムの一覧は、openssl_get_md_methods() で得られます。 デフォルトは SHA-1 です。

戻り値

生のバイナリ文字列を返します。失敗した場合に false を返します。

例

例1 openssl_pbkdf2() の例

<?php
$password = 'password';
$salt = openssl_random_pseudo_bytes(16);
$keyLength = 20;
$iterations = 600000;
$generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');
echo bin2hex($generated_key)."\n";
echo base64_encode($generated_key)."\n";
?>

参考

  • hash_pbkdf2() - PBKDF2 を使ってパスワードからキーを生成する
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得


PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

  • ≪ openssl_pbkdf2
  • openssl_pkcs12_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

説明

openssl_pkcs12_export(
OpenSSLCertificate|string $certificate,
string &$output,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
#[\SensitiveParameter] string $passphrase,
array $options = []
): bool

openssl_pkcs12_export() は、 certificate を PKCS#12 ファイルフォーマットにしたものを output で指定した文字列に格納します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output

成功した場合に、ここに PKCS#12 が保存されます。

private_key

PKCS#12 ファイルのプライベートキーコンポーネント。 正しい値の一覧については、Public/Private Key parameters を参照ください。

passphrase

PKCS#12 ファイルのロックを解除するためのパスワード。

options

オプションの配列。以下に示すキー以外は無視されます。

キー | 説明
"extracerts" | PKCS#12 ファイルに含まれる単一の証明書、または 外部の証明書の配列
"friendly_name" | 与えられた証明書とキーで使われる文字列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate インスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。


PKCS#12 互換の証明書保存ファイルをエクスポートする

  • ≪ openssl_pkcs12_export
  • openssl_pkcs12_read ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS#12 互換の証明書保存ファイルをエクスポートする

openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする

説明

openssl_pkcs12_export_to_file(
OpenSSLCertificate|string $certificate,
string $output_filename,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
#[\SensitiveParameter] string $passphrase,
array $options = []
): bool

openssl_pkcs12_export_to_file() は、 certificate をファイル output_filename に PKCS#12 フォーマットで保存します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output_filename

出力ファイルへのパス。

private_key

PKCS#12 ファイルのプライベートキーコンポーネント。 正しい値の一覧については、Public/Private Key parameters を参照ください。

passphrase

PKCS#12 ファイルのロックを解除するためのパスワード。

options

オプションの配列。以下に示すキー以外は無視されます。

キー | 説明
"extracerts" | PKCS#12 ファイルに含まれる単一の証明書、または 外部の証明書の配列
"friendly_name" | 与えられた証明書とキーで使われる文字列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。


PKCS#12 認証ストアをパースして配列形式にする

  • ≪ openssl_pkcs12_export_to_file
  • openssl_pkcs7_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS#12 認証ストアをパースして配列形式にする

openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — PKCS#12 認証ストアをパースして配列形式にする

説明

openssl_pkcs12_read(string $pkcs12, array &$certificates, #[\SensitiveParameter] string $passphrase): bool

openssl_pkcs12_read() は、 pkcs12 で指定した PKCS#12 認証ストアをパースして certificates で指定した配列に格納します。

パラメータ

pkcs12

認証ストアの内容。ファイル名ではありません。

certificates

成功した場合に、ここに認証ストアデータが格納されます。

passphrase

PKCS#12 ファイルのロックを解除するためのパスワード。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 openssl_pkcs12_read() の例

<?php
if (!$cert_store = file_get_contents("/certs/file.p12")) {
echo "Error: Unable to read the cert file\n";
exit;
}

if (openssl_pkcs12_read($cert_store, $cert_info, "my_secret_pass")) {
echo "Certificate Information\n";
print_r($cert_info);
} else {
echo "Error: Unable to read the cert store.\n";
exit;
}
?>


S/MIME 暗号化されたメッセージを復号する

  • ≪ openssl_pkcs12_read
  • openssl_pkcs7_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME 暗号化されたメッセージを復号する

openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — S/MIME 暗号化されたメッセージを復号する

説明

openssl_pkcs7_decrypt(
string $input_filename,
string $output_filename,
#[\SensitiveParameter] OpenSSLCertificate|string $certificate,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null $private_key = null
): bool

input_filename で指定したファイル中の S/MIME 暗号化されたメッセージを、 certificate と private_key で 指定した証明書とそれに関連付けられた秘密鍵を用いて復号します。

パラメータ

input_filename

output_filename

復号したメッセージは、output_filename で指定したファイルに出力されます。

certificate

private_key

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_pkcs7_decrypt() の例

<?php
// $cert および $key にはあなたの個人証明書と秘密鍵が含まれており、
// あなたはS/MIMEメッセージの受信者であると仮定します。
$infilename = "encrypted.msg"; // 暗号化されたメッセージを含むファイル
$outfilename = "decrypted.msg"; // このファイルへの書き込み権限が必要

if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
echo "復号しました!";
} else {
echo "復号に失敗しました!";
}
?>


S/MIME メッセージを暗号化する

  • ≪ openssl_pkcs7_decrypt
  • openssl_pkcs7_read ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME メッセージを暗号化する

openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — S/MIME メッセージを暗号化する

説明

openssl_pkcs7_encrypt(
string $input_filename,
string $output_filename,
OpenSSLCertificate|array|string $certificate,
?array $headers,
int $flags = 0,
int $cipher_algo = OPENSSL_CIPHER_AES_128_CBC
): bool

openssl_pkcs7_encrypt() は、 input_filename という名前のファイルの内容を RC2 40 ビット暗号により暗号化します。この内容は、 certificate で指定した意図する受信者によってのみ読むことが可能です。

パラメータ

input_filename

output_filename

certificate

X.509 証明書または X.509 証明書の配列。

headers

headers は、 暗号化された後にデータの前に付加されるヘッダの配列です。

headers はヘッダ名をキーとする連想配列または添字配列であり、 各要素には、各ヘッダ行が一行ずつ含まれています。

flags

flags は オプションとして使用可能であり、エンコード処理を変更するために指定します。 PKCS7 定数 を参照ください。

cipher_algo

暗号定数のうちの一つ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | デフォルトの暗号化アルゴリズム (cipher_algo) が、 AES-128-CBC (OPENSSL_CIPHER_AES_128_CBC) になりました。 これより前のバージョンでは、 PKCS7/CMS (OPENSSL_CIPHER_RC2_40) が使われていました。
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_pkcs7_encrypt() の例

<?php
// 暗号化するメッセージを nighthawk という名前の外部の秘密の
// エージェントに送信します。送信先の証明書をファイル nighthawk.pem に
// 有しています。
$data = <<<EOD
Nighthawk,

Top secret, for your eyes only!

The enemy is closing in! Meet me at the cafe at 8.30am
to collect your forged passport!

HQ
EOD;

// キーを読み込む
$key = file_get_contents("nighthawk.pem");

// ファイルにメッセージを保存
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);

// メッセージを暗号化
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
array("To" => "nighthawk@example.com", // 連想配列の構文
"From: HQ <hq@example.com>", // 添字配列の構文
"Subject" => "Eyes only"))) {
// メッセージを暗号化し、送信します!
exec(ini_get("sendmail_path") . " < enc.txt");
}
?>


PKCS7 ファイルを PEM証明書 の配列にエクスポートする

  • ≪ openssl_pkcs7_encrypt
  • openssl_pkcs7_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • PKCS7 ファイルを PEM証明書 の配列にエクスポートする

openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — PKCS7 ファイルを PEM証明書 の配列にエクスポートする

説明

openssl_pkcs7_read(string $data, array &$certificates): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

パースしたい文字列データ(p7b フォーマット)

certificates

p7b フォーマットの入力データからエクスポートされる、 PEM証明書の配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 P7B ファイルから、PEM証明書の配列を取得する

<?php
$file = 'certs.p7b';
$f = file_get_contents($file);
$p7 = array();
$r = openssl_pkcs7_read($f, $p7);
if ($r === false) {
printf("ERROR: %s is not a proper p7b file".PHP_EOL, $file);
for($e = openssl_error_string(), $i = 0; $e; $e = openssl_error_string(), $i++)
printf("SSL l%d: %s".PHP_EOL, $i, $e);
exit(1);
}
print_r($p7);
?>

参考

  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


S/MIME メッセージに署名する

  • ≪ openssl_pkcs7_read
  • openssl_pkcs7_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME メッセージに署名する

openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — S/MIME メッセージに署名する

説明

openssl_pkcs7_sign(
string $input_filename,
string $output_filename,
OpenSSLCertificate|string $certificate,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
?array $headers,
int $flags = PKCS7_DETACHED,
?string $untrusted_certificates_filename = null
): bool

openssl_pkcs7_sign() は input_filename という名前のファイルの内容を取得し、 パラメータ certificate と private_keyで 指定した証明書とそれに対応する秘密鍵を用いて署名します。

パラメータ

input_filename

デジタル署名したい入力ファイル

output_filename

デジタル署名が書き出されるファイル

certificate

input_filename に電子署名するために使う X.509 証明書。 有効な値のリストは、 キー/証明書パラメータ を参照ください。

private_key

private_key は、certificate に対応する秘密鍵です。 有効な値のリストは、 公開鍵/秘密鍵 のパラメータ を参照ください。

headers

headers は、ヘッダの配列です。このヘッダは、 署名された後でデータの前に付加されます (このパラメータの形式の詳細については openssl_pkcs7_encrypt() を参照ください)。

flags

flags を出力を変更するために使用することが可能です。 PKCS7 定数 を参照ください。

untrusted_certificates_filename

untrusted_certificates_filename には、 署名に含めるための他の一連の証明書を記述したファイル名を指定します。 これは、例えば送信者が使用した証明書を受信者が検証しやすくするために使用することが可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 CSR 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 CSR 型のリソースを受け入れていました。

例

例1 openssl_pkcs7_sign() の例

<?php
// 受信者が送信者を確認できるように署名したいメッセージ
$data = <<<EOD

You have my authorization to spend $10,000 on dinner expenses.

The CEO
EOD;
// ファイルにメッセージを保存
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);
// 暗号化
if (openssl_pkcs7_sign("msg.txt", "signed.txt", "file://mycert.pem",
array("file://mycert.pem", "mypassphrase"),
array("To" => "joes@example.com", // 連想配列の構文
"From: HQ <ceo@example.com>", // 添字配列の構文
"Subject" => "Eyes only")
)) {
// メッセージは署名されました。送信しましょう!
exec(ini_get("sendmail_path") . " < signed.txt");
}
?>


S/MIME で署名されたメッセージの署名を検証する

  • ≪ openssl_pkcs7_sign
  • openssl_pkey_derive ≫
  • PHP Manual
  • OpenSSL 関数
  • S/MIME で署名されたメッセージの署名を検証する

openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — S/MIME で署名されたメッセージの署名を検証する

説明

openssl_pkcs7_verify(
string $input_filename,
int $flags,
?string $signers_certificates_filename = null,
array $ca_info = [],
?string $untrusted_certificates_filename = null,
?string $content = null,
?string $output_filename = null
): bool|int

openssl_pkcs7_verify() は、 指定したファイルの S/MIME メッセージを読み込み、デジタル署名を検証します。

パラメータ

input_filename

メッセージへのパス。

flags

flags により署名の検証方法を指定することが可能です。 詳細については、PKCS7 定数 を参照ください。

signers_certificates_filename

signers_certificates_filename が指定された場合、 メッセージに署名した人の証明書が PEM 形式で保存された ファイルの名前を含む文字列でなければなりません。

ca_info

ca_info が指定された場合、 検証に使用する信頼された CA 証明書に関する情報を適用する必要があります。 このパラメータに関するより詳細な情報については、 証明書の検証 を参照ください。

untrusted_certificates_filename

untrusted_certificates_filename が指定された場合、 これは信頼されていない CA と見なす一連の証明書を含んだ ファイルの名前となります。

content

ファイル名とともに content を指定すると、検証したデータがここに格納されます。 格納する際に、署名情報は除去されます。

output_filename

戻り値

署名が検証された場合は true、正しくない場合 (メッセージが改暫されたか署名に用いられた証明書が無効) は false、 エラーの場合に -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | signers_certificates_filename, untrusted_certificates_filename, content, output_filename は、nullable になりました。
7.2.0 | output_filename パラメータが追加されました。

注意

注意: RFC 2045 にあるように、 input_filename パラメータのファイル名が 76 文字より長くなってはいけません。


リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

  • ≪ openssl_pkcs7_verify
  • openssl_pkey_export ≫
  • PHP Manual
  • OpenSSL 関数
  • リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

説明

openssl_pkey_derive(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key, #[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key, int $key_length = 0): string|false

openssl_pkey_derive() 関数は、 public_key と private_key を受け取り、 DH または EC鍵のための共有シークレットを生成します。

パラメータ

public_key

public_key は、共有シークレットを生成するための公開鍵です。 有効な値については、 キー/証明書パラメータ を参照ください。

private_key

private_key は、共有シークレットを生成するための秘密鍵です。 有効な値については、 キー/証明書パラメータ を参照ください。

key_length

0でない場合、生成するシークレットの長さを指定します。

戻り値

成功時には、生成されたシークレットを返します。 失敗した場合に false を返します.

例

例1 openssl_pkey_derive() 関数の例

<?php
// Load in private key
$priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
-----END PRIVATE KEY-----
");

// Load in public key
$pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
-----END PUBLIC KEY-----
");

// Outputs the hex version of the derived key
echo bin2hex(openssl_pkey_derive($pub,$priv));


エクスポート可能な形式で、キーを文字列に取得する

  • ≪ openssl_pkey_derive
  • openssl_pkey_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • エクスポート可能な形式で、キーを文字列に取得する

openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する

説明

openssl_pkey_export(
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $key,
string &$output,
#[\SensitiveParameter] ?string $passphrase = null,
?array $options = null
): bool

openssl_pkey_export() は、 key を PEM エンコードした文字列として取得し、 output（リファレンス渡し）に格納します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

key

output

passphrase

オプションで passphrase を使用してキーを保護することが可能です。

options

options により openssl 設定ファイルの設定を 追加したり上書きしたりすることで、エクスポート処理の詳細設定が可能です。 options についての詳細な情報は openssl_csr_new() を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。


エクスポート可能な形式で、キーをファイルに取得する

  • ≪ openssl_pkey_export
  • openssl_pkey_free ≫
  • PHP Manual
  • OpenSSL 関数
  • エクスポート可能な形式で、キーをファイルに取得する

openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — エクスポート可能な形式で、キーをファイルに取得する

説明

openssl_pkey_export_to_file(
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $key,
string $output_filename,
#[\SensitiveParameter] ?string $passphrase = null,
?array $options = null
): bool

openssl_pkey_export_to_file() は、ASCII 変換された (PEM エンコードされた) key を output_filename のファイルに保存します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

key

output_filename

出力ファイルへのパス。

passphrase

オプションで passphrase を使用してキーを保護することが可能です。

options

options により openssl 設定ファイルの設定を 追加したり上書きしたりすることで、エクスポート処理の詳細設定が可能です。 options についての詳細な情報は openssl_csr_new() を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。


秘密鍵を開放する

  • ≪ openssl_pkey_export_to_file
  • openssl_pkey_get_details ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵を開放する

openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — 秘密鍵を開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

openssl_pkey_free(OpenSSLAsymmetricKey $key): void

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

この関数は、openssl_pkey_new() で作成した秘密鍵を開放します。

パラメータ

key

キーを保持するリソース。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行しても何の効果もなくなったからです。
8.0.0 | key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。


キーの詳細の配列を返す

  • ≪ openssl_pkey_free
  • openssl_pkey_get_private ≫
  • PHP Manual
  • OpenSSL 関数
  • キーの詳細の配列を返す

openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — キーの詳細の配列を返す

説明

openssl_pkey_get_details(OpenSSLAsymmetricKey $key): array|false

この関数は、キーの詳細 (bits, key, type) を返します。

パラメータ

key

キーを保持する配列。

戻り値

成功した場合にキーの詳細を含む配列、失敗した場合に false を返します。 返される配列のキーは bits (ビット数)、 key (公開鍵を表す文字列) および type (キーの種類。 OPENSSL_KEYTYPE_RSA、 OPENSSL_KEYTYPE_DSA、 OPENSSL_KEYTYPE_DH、 OPENSSL_KEYTYPE_EC のいずれか。あるいは不明な場合は -1) となります。

使っているキーの型によって、さらに詳細が返されます。 常に存在するわけではない要素もあることに注意しましょう。

  • OPENSSL_KEYTYPE_RSA の場合は "rsa" というキーがあり、キーのデータが返されます。
    キー | 説明
    "n" | modulus
    "e" | public exponent
    "d" | private exponent
    "p" | prime 1
    "q" | prime 2
    "dmp1" | exponent1, d mod (p-1)
    "dmq1" | exponent2, d mod (q-1)
    "iqmp" | coefficient, (inverse of q) mod p
  • OPENSSL_KEYTYPE_DSA の場合は "dsa" というキーがあり、キーのデータが返されます。
    キー | 説明
    "p" | prime number (public)
    "q" | 160-bit subprime, q | p-1 (public)
    "g" | generator of subgroup (public)
    "priv_key" | private key x
    "pub_key" | public key y = g^x
  • OPENSSL_KEYTYPE_DH の場合は "dh" というキーがあり、キーのデータが返されます。
    キー | 説明
    "p" | prime number (shared)
    "g" | generator of Z_p (shared)
    "priv_key" | private DH value x
    "pub_key" | public DH value g^x
  • OPENSSL_KEYTYPE_EC の場合は "ec" というキーがあり、キーのデータが返されます。
    Key | 説明
    "curve_name" | name of curve, see openssl_get_curve_names()
    "curve_oid" | ASN1 Object identifier (OID) for EC curve.
    "x" | x coordinate (public)
    "y" | y coordinate (public)
    "d" | private key

変更履歴

バージョン | 説明
8.0.0 | key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。


秘密鍵を取得する

  • ≪ openssl_pkey_get_details
  • openssl_pkey_get_public ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵を取得する

openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — 秘密鍵を取得する

説明

openssl_pkey_get_private(#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key, #[\SensitiveParameter] ?string $passphrase = null): OpenSSLAsymmetricKey|false

openssl_pkey_get_private() は private_key をパースし、他の関数で使用できるよう準備します。

パラメータ

private_key

private_key は以下のいずれかです。

  1. file://path/to/file.pem 形式の文字列。 このファイルは、PEM エンコードされた証明書/秘密鍵である必要が あります（両方を含むことも可能です）。
  2. PEM フォーマットの秘密鍵。

passphrase

指定されたキーが（パスフレーズを用いて）暗号化されている場合は、 オプションのパラメータ passphrase を使用する必要があります。

戻り値

成功した場合に、 OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、 この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを返していました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | passphrase は、nullable になりました。


証明書から公開鍵を抽出し、使用できるようにする

  • ≪ openssl_pkey_get_private
  • openssl_pkey_new ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書から公開鍵を抽出し、使用できるようにする

openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — 証明書から公開鍵を抽出し、使用できるようにする

説明

openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() は公開鍵を public_key から抽出し、 他の関数で使用できるよう準備します。

パラメータ

public_key

public_key は以下のいずれかです。

  1. OpenSSLAsymmetricKey クラスのインスタンス
  2. file://path/to/file.pem 形式の文字列。 このファイルは、PEM エンコードされた証明書/公開鍵である必要が あります（両方を含むことも可能です）。
  3. PEM フォーマットの公開鍵。

戻り値

成功した場合に OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、 この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを返していました。
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。


新規に秘密鍵を生成する

  • ≪ openssl_pkey_get_public
  • openssl_private_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 新規に秘密鍵を生成する

openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — 新規に秘密鍵を生成する

説明

openssl_pkey_new(?array $options = null): OpenSSLAsymmetricKey|false

openssl_pkey_new() は、 新しい秘密鍵を生成します。 鍵の公開部を取得する方法は、以下の例に示します。

注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

パラメータ

options

鍵の作成方法の詳細（ビット数など）を指定するには、 options を使用します。 options の詳細な情報については openssl_csr_new() を参照ください。

戻り値

成功した場合に、OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、 この関数は OpenSSLAsymmetricKey クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを返していました。
7.1.0 | EC キーを作成できるようにするため、 options に curve_name が追加されました。

例

例1 秘密鍵から、公開鍵を取得する

<?php
$private_key = openssl_pkey_new();
$public_key_pem = openssl_pkey_get_details($private_key)['key'];
echo $public_key_pem;
$public_key = openssl_pkey_get_public($public_key_pem);
var_dump($public_key);
?>

上の例の出力は、 たとえば以下のようになります。

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArZFsmN2P6rx1Xt7YV95o
gcdlal0k3ryiIhFNzjwtRNNTXfEfBr6lUuaIJYQ8/XqEBX0hpcfuuF6tTRlonA3t
WLME0QFD93YVsAaXcy76YqjjqcRRodIBphAbYyyMI/lXkQAdn7kbAmr7neSOsMYJ
El9Wo4Hl4oG6e52ZnYHyqW9dxh4hX93eupR2TmcCdVf+r9xoHewP0KJYSHt7vDUX
AQlWYcQiWHIadFsmL0orr6mutlXFReoHbesgKY9/3YLOu0JfxflSjIZ2JeL1NTl1
MsmODsUwgAUrwnWKKx+eQUP5g3GnSB3dPkRh9zRVRiLNWbCugyjrf3e6DgQWrW7j
pwIDAQAB
-----END PUBLIC KEY-----
resource(5) of type (OpenSSL key)


秘密鍵でデータを復号する

  • ≪ openssl_pkey_new
  • openssl_private_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵でデータを復号する

openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — 秘密鍵でデータを復号する

説明

openssl_private_decrypt(
string $data,
#[\SensitiveParameter] string &$decrypted_data,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
int $padding = OPENSSL_PKCS1_PADDING
): bool

openssl_private_decrypt() は、事前に openssl_public_encrypt() で暗号化された data を復号し、それを decrypted_data に格納します。

これを使用するのは、例えばあなたにのみ送られてきたデータを復号する場合です。

パラメータ

data

decrypted_data

private_key

private_key は、 データの暗号化に使用したものに対応する秘密鍵である必要があります。

padding

padding には、 OPENSSL_PKCS1_PADDING、 OPENSSL_SSLV23_PADDING、 OPENSSL_PKCS1_OAEP_PADDING、 OPENSSL_NO_PADDING が指定可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_public_encrypt() - 公開鍵でデータを暗号化する
  • openssl_public_decrypt() - 公開鍵でデータを復号する


秘密鍵でデータを暗号化する

  • ≪ openssl_private_decrypt
  • openssl_public_decrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵でデータを暗号化する

openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — 秘密鍵でデータを暗号化する

説明

openssl_private_encrypt(
#[\SensitiveParameter] string $data,
string &$encrypted_data,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
int $padding = OPENSSL_PKCS1_PADDING
): bool

openssl_private_encrypt() は、data を秘密鍵 private_key で暗号化し、それを encrypted_data に格納します。暗号化されたデータは、 openssl_public_decrypt() を用いて復号可能です。

この関数を使用するのは、例えばデータ（あるいはその一部）に署名をし、 それが他人によって書かれたものでないことを証明する場合です。

パラメータ

data

encrypted_data

private_key

padding

padding には OPENSSL_PKCS1_PADDING あるいは OPENSSL_NO_PADDING が指定可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_public_encrypt() - 公開鍵でデータを暗号化する
  • openssl_public_decrypt() - 公開鍵でデータを復号する


公開鍵でデータを復号する

  • ≪ openssl_private_encrypt
  • openssl_public_encrypt ≫
  • PHP Manual
  • OpenSSL 関数
  • 公開鍵でデータを復号する

openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — 公開鍵でデータを復号する

説明

openssl_public_decrypt(
string $data,
#[\SensitiveParameter] string &$decrypted_data,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key,
int $padding = OPENSSL_PKCS1_PADDING
): bool

openssl_public_decrypt() は、事前に openssl_private_encrypt() で暗号化された data を復号し、それを decrypted_data に格納します。

これを使用するのは、例えばメッセージの作者が秘密鍵の所有者であるかどうかを調べる場合です。

パラメータ

data

decrypted_data

public_key

public_key は、 データの暗号化に使用したものに対応する公開鍵である必要があります。

padding

padding には OPENSSL_PKCS1_PADDING あるいは OPENSSL_NO_PADDING が指定可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_private_encrypt() - 秘密鍵でデータを暗号化する
  • openssl_private_decrypt() - 秘密鍵でデータを復号する


公開鍵でデータを暗号化する

  • ≪ openssl_public_decrypt
  • openssl_random_pseudo_bytes ≫
  • PHP Manual
  • OpenSSL 関数
  • 公開鍵でデータを暗号化する

openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — 公開鍵でデータを暗号化する

説明

openssl_public_encrypt(
#[\SensitiveParameter] string $data,
string &$encrypted_data,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key,
int $padding = OPENSSL_PKCS1_PADDING
): bool

openssl_public_encrypt() は、data を公開鍵 public_key で暗号化し、それを encrypted_data に格納します。暗号化されたデータは openssl_private_decrypt() を用いて復号可能です。

この関数を使用するのは、例えば秘密鍵の所有者にのみ読めるようにメッセージを暗号化する場合です。 また、データベースに格納するデータを安全な形式にするためにも使用されます。

パラメータ

data

encrypted_data

暗号化した結果がここに格納されます。

public_key

公開鍵。

padding

padding には OPENSSL_PKCS1_PADDING、 OPENSSL_SSLV23_PADDING、 OPENSSL_PKCS1_OAEP_PADDING、 OPENSSL_NO_PADDING が指定可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

参考

  • openssl_private_encrypt() - 秘密鍵でデータを暗号化する
  • openssl_private_decrypt() - 秘密鍵でデータを復号する


疑似ランダムなバイト文字列を生成する

  • ≪ openssl_public_encrypt
  • openssl_seal ≫
  • PHP Manual
  • OpenSSL 関数
  • 疑似ランダムなバイト文字列を生成する

openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — 疑似ランダムなバイト文字列を生成する

説明

openssl_random_pseudo_bytes(int $length, bool &$strong_result = null): string

疑似ランダムなバイト文字列を生成します。長さは length パラメータで指定します。

暗号学的に強いアルゴリズムを使って疑似乱数を生成したかどうかを知ることもできます。 オプションのパラメータ strong_result を使います。 これが false になることはまずないでしょうが、 古いシステムなどではそうなることもあります。

パラメータ

length

希望するバイト長。 2147483647 以下の正の整数でなければなりません。 PHP は、 このパラメータを非 null の整数値にキャストして利用します。

strong_result

これを渡しておくと、使ったアルゴリズムが暗号学的に強いものであるかどうかを表す bool 値が格納されます。「強い」とは、 GPG やパスワードなどに使っても安全であるという意味です。強い場合は true、そうでない場合は false となります。

戻り値

成功した場合は指定したバイト長の string を返します。

エラー / 例外

openssl_random_pseudo_bytes() は、 失敗した場合に Exception をスローします。

変更履歴

バージョン | 説明
8.0.0 | strong_result は、nullable になりました。
7.4.0 | この関数は、失敗時に false を返さなくなりました。 代わりに Exception をスローするようになっています。

例

例1 openssl_random_pseudo_bytes() の例

<?php
for ($i = 1; $i <= 4; $i++) {
$bytes = openssl_random_pseudo_bytes($i, $cstrong);
$hex = bin2hex($bytes);

echo "Lengths: Bytes: $i and Hex: " . strlen($hex) . PHP_EOL;
var_dump($hex);
var_dump($cstrong);
echo PHP_EOL;
}
?>

上の例の出力は、 たとえば以下のようになります。

Lengths: Bytes: 1 and Hex: 2
string(2) "42"
bool(true)

Lengths: Bytes: 2 and Hex: 4
string(4) "dc6e"
bool(true)

Lengths: Bytes: 3 and Hex: 6
string(6) "288591"
bool(true)

Lengths: Bytes: 4 and Hex: 8
string(8) "ab86d144"
bool(true)

参考

  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する
  • bin2hex() - バイナリのデータを16進表現に変換する
  • crypt() - 文字列の一方向のハッシュ化を行う
  • random_int() - 暗号学的にセキュアな方法で、等確率に出る整数を取得する


データをシール(暗号化)する

  • ≪ openssl_random_pseudo_bytes
  • openssl_sign ≫
  • PHP Manual
  • OpenSSL 関数
  • データをシール(暗号化)する

openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — データをシール(暗号化)する

説明

openssl_seal(
#[\SensitiveParameter] string $data,
string &$sealed_data,
array &$encrypted_keys,
array $public_key,
string $cipher_algo,
string &$iv = null
): int|false

openssl_seal() は、ランダムに生成された秘密鍵 および指定した cipher_algo を使用して data をシール(暗号化) します。このキーは、public_key を ID とする 公開鍵で暗号化されます。 それぞれの暗号化されたキーは encrypted_keys で返されます。 これは、暗号化されたデータを複数の受信者に 送信できることを意味します（この際、各受信者は送信側に公開鍵を 提供します）。各受信者は、暗号化されたデータとその受信者の 公開鍵で暗号化されたエンベロープキーを受け取る必要があります。

パラメータ

data

シールするデータ。

sealed_data

シール済みのデータ。

encrypted_keys

暗号化したキーの配列。

public_key

公開鍵を含んだ OpenSSLAsymmetricKey クラスのインスタンスの配列。

cipher_algo

暗号化方式

警告

デフォルト値 ('RC4') はセキュアでない値です。 明示的にセキュアな暗号化方式を指定することを強く推奨します。

iv

初期化ベクトル。

戻り値

成功時にシール(暗号化)されたデータの長さ、エラー時に false を返します。成功時には、暗号化されたデータが sealed_data に、エンベロープキーが encrypted_keys に返されます。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey クラスのインスタンスの配列を受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースの配列を受け入れていました。
8.0.0 | cipher_algo は、オプションではなくなりました。
8.0.0 | iv は、nullable になりました。

例

例1 openssl_seal() の例

<?php
// $data には、暗号化されるデータが含まれていると仮定

// 受信者の公開鍵を取得し、使用可能にする
$fp = fopen("/src/openssl-0.9.6/demos/maurice/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk1 = openssl_get_publickey($cert);
// 2 番目の受信者についても同様
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk2 = openssl_get_publickey($cert);

// メッセージを暗号化。$pk1 および $pk2 の所有者のみが、$sealed を
// データをそれぞれ $ekeys[0] および $ekeys[1] で復号化することが
// 可能
openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2));

// キーをメモリから開放する
openssl_free_key($pk1);
openssl_free_key($pk2);
?>

参考

  • openssl_open() - シール(暗号化)されたデータをオープン(復号)する


署名を生成する

  • ≪ openssl_seal
  • openssl_spki_export ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名を生成する

openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — 署名を生成する

説明

openssl_sign(
string $data,
string &$signature,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key,
string|int $algorithm = OPENSSL_ALGO_SHA1
): bool

openssl_sign() は、指定した data の署名を作ります。 private_key で指定した秘密鍵を使用して、暗号のデジタル署名を生成します。 data 自体は暗号化されないことに注意してください。

パラメータ

data

署名したいデータの文字列。

signature

成功した場合、署名が signature に格納されます。

private_key

OpenSSLAsymmetricKey - openssl_get_privatekey() が返す鍵。

string - PEM フォーマットの鍵。

algorithm

int - いずれかの 署名アルゴリズム。

string - openssl_get_md_methods() が返す文字列 ("sha256WithRSAEncryption" や "sha384" など)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_sign() の例

<?php
// $data に署名するデータが含まれていると仮定

// ファイルから秘密鍵を取得して準備
$pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

// 署名を計算
openssl_sign($data, $signature, $pkeyid);

// メモリからキーを開放する
openssl_free_key($pkeyid);
?>

例2 openssl_sign() の例

<?php
// 署名したいデータ
$data = 'my data';

// 新しい秘密鍵と公開鍵を作成
$new_key_pair = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));
openssl_pkey_export($new_key_pair, $private_key_pem);

$details = openssl_pkey_get_details($new_key_pair);
$public_key_pem = $details['key'];

// 署名を作成
openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

// それらを保存
file_put_contents('private_key.pem', $private_key_pem);
file_put_contents('public_key.pem', $public_key_pem);
file_put_contents('signature.dat', $signature);

// 署名を検証
$r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
var_dump($r);
?>

参考

  • openssl_verify() - 署名を検証する


署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

  • ≪ openssl_sign
  • openssl_spki_export_challenge ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

説明

openssl_spki_export(string $spki): string|false

署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートします。

パラメータ

spki

有効な署名済みの公開鍵とチャレンジ

戻り値

関連するPEMフォーマットの公開鍵を返します。 失敗した場合は false を返します。

エラー / 例外

不正な引数が spki に渡された場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_spki_export() の例

関連するPEMフォーマットの公開鍵を取り出します。 失敗した場合は null になります。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'challenge string');
$pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

if ($pubKey) {
echo $pubKey;
}
?>

例2 openssl_spki_export() を使い、<keygen> から取り出す例

<keygen> 要素から発行された、関連するPEMフォーマットの公開鍵を取り出します。

<?php
$spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));
if ($spkac != NULL) {
echo $spkac;
} else {
echo "Extraction of pub key failed";
}
?>
<keygen name="spkac" challenge="challenge string" keytype="RSA">

参考

  • openssl_spki_new() - 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_verify() - 署名済みの公開鍵とチャレンジを検証する
  • openssl_spki_export_challenge() - 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

  • ≪ openssl_spki_export
  • openssl_spki_new ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

説明

openssl_spki_export_challenge(string $spki): string|false

エンコードされた署名済みの公開鍵とチャレンジから、チャレンジをエクスポートします。

パラメータ

spki

有効な署名済みの公開鍵とチャレンジ

戻り値

関連するチャレンジを文字列で返します。失敗した場合は false を返します。

エラー / 例外

不正な引数が spki に渡された場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_spki_export_challenge() の例

関連するチャレンジの文字列を取り出します。 失敗した場合は NULL になります。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'challenge string');
$challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
?>

例2 openssl_spki_export_challenge() を使い、<keygen> から取り出す例

<keygen> 要素から発行された、関連するチャレンジ文字列を取り出します。

<?php
$challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
?>
<keygen name="spkac" challenge="challenge string" keytype="RSA">

参考

  • openssl_spki_new() - 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_verify() - 署名済みの公開鍵とチャレンジを検証する
  • openssl_spki_export() - 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


署名された公開鍵とチャレンジを新規に作成する

  • ≪ openssl_spki_export_challenge
  • openssl_spki_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名された公開鍵とチャレンジを新規に作成する

openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する

説明

openssl_spki_new(#[\SensitiveParameter] OpenSSLAsymmetricKey $private_key, string $challenge, int $digest_algo = OPENSSL_ALGO_MD5): string|false

指定されたハッシュアルゴリズムを用いて、署名された公開鍵とチャレンジを新規に作成します。

パラメータ

private_key

private_key には、事前に openssl_pkey_new() で作成した （もしくは他の openssl_pkey 関数で得た）秘密鍵を 設定しなければなりません。鍵の対応する公開部分は、 CSR に署名するために使用されます。

challenge

チャレンジは SPKAC と関連付けられます。

digest_algo

ダイジェストアルゴリズム。openssl_get_md_method() を参照ください。

戻り値

署名された公開鍵とチャレンジ文字列を返し、失敗したときは false を返します。

エラー / 例外

未知の署名アルゴリズムが digest_algo パラメータを介して渡された場合、 E_WARNING レベルのエラーを発行します。

変更履歴

バージョン | 説明
8.0.0 | private_key は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key 型のリソースを受け入れていました。

例

例1 openssl_spki_new() の例

既定のダイジェスト (MD5) で、署名された公開鍵とチャレンジを新規に作成します。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'testing');

if ($spkac !== NULL) {
echo $spkac;
} else {
echo "SPKAC generation failed";
}
?>

上の例の出力は、 たとえば以下のようになります。

MIICRzCCAS8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM3V3sS4o4
mB9dczziRnjGAmSp+JwPrHoYMAFGvDNmZGyiWfU586X4BKs++BAj7e/FsAfno0Hd
hN9FwpCNFSox30L03nQvLYJE7f/WqigwBeMRT7Op/xvFks4sT70xP2HRYv4KqP9a
WRcKU6cFH8VxhFhqM2txEIxZKdFLaL28yT7bEDmcglf4JLDdgNMb9rET1dkgtKE6
dOaJHPGjf1uvnOH4YwkQr7n4sLUR3Kdbh0ZJAFuQVDZulo+LLzxBBkqJJcB6FhF+
oXCdHTKZnqAhpWDz+NXYytAmevab6IYm5TWPWsJUv1YKJA5lg2mXbbloIZlN9Mgc
i9fi03bdw+crAgMBAAEWB3Rlc3RpbmcwDQYJKoZIhvcNAQEEBQADggEBALyUvP/o
pPSoWBlorFyZ2RnGwKf9qMpE0q2IJP7G3oDR4LyK/m933DUiZ+YnqThrH/CWb4Ek
y5I3OCyl3S4wCuU1ibZZwDVwYShr5ELp0J9PEf7qMQZOhNsizoC7k+Czb2xB6hYW
sKfsfTKm3cXBtH3fdgc/Z1Z7VSWnAzYo38snqm72NTf5yFRnrQdphNNXi+kn1zHA
lxXRyFDXHOcYsOnwAWfyXFA4QDHQ0ezz0UoCY8gJXovcZb4GRYqOLUAsF2HcNboy
29WN8VqE29sL9QxVZFlwMcqyoLcNnyw38GvNvAGqSvzzbnEFP2MAQXJVe0H0hdp/
MML5G2iNVgNozAo=

参考

  • openssl_spki_verify() - 署名済みの公開鍵とチャレンジを検証する
  • openssl_spki_export_challenge() - 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_spki_export() - 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


署名済みの公開鍵とチャレンジを検証する

  • ≪ openssl_spki_new
  • openssl_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名済みの公開鍵とチャレンジを検証する

openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する

説明

openssl_spki_verify(string $spki): bool

与えられた公開鍵とチャレンジを検証します。

パラメータ

spki

有効な署名済みの公開鍵とチャレンジ

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

不正な引数が spki に渡された場合、 E_WARNING レベルのエラーが発生します。

例

例1 openssl_spki_verify() の例

既存の署名済み公開鍵とチャレンジを検証します。

<?php
$pkey = openssl_pkey_new('secret password');
$spkac = openssl_spki_new($pkey, 'challenge string');

if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
echo $spkac;
} else {
echo "SPKAC validation failed";
}
?>

例2 <keygen> から openssl_spki_verify() を使う例

<keygen> 要素から発行された、既存の署名済み公開鍵とチャレンジを検証します。

<?php
if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
echo $spkac;
} else {
echo "SPKAC validation failed";
}
?>
<keygen name="spkac" challenge="challenge string" keytype="RSA">

参考

  • openssl_spki_new() - 署名された公開鍵とチャレンジを新規に作成する
  • openssl_spki_export_challenge() - 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
  • openssl_spki_export() - 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
  • openssl_get_md_methods() - 利用可能なダイジェスト・メソッドを取得
  • openssl_csr_new() - CSR を作成する
  • openssl_csr_sign() - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する


署名を検証する

  • ≪ openssl_spki_verify
  • openssl_x509_check_private_key ≫
  • PHP Manual
  • OpenSSL 関数
  • 署名を検証する

openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — 署名を検証する

説明

openssl_verify(
string $data,
string $signature,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key,
string|int $algorithm = OPENSSL_ALGO_SHA1
): int|false

openssl_verify() は、 public_key が指す公開鍵を使用し、 指定した data に関して signature が正しいことを確認します。 署名が正しいと判定されるためには、 その公開鍵が署名の際に使用した秘密鍵に対応している必要があります。

パラメータ

data

署名を作成するときに使ったデータの文字列。

signature

生のバイナリ文字列。openssl_sign() もしくはそれと同等の手段を使って生成したもの。

public_key

OpenSSLAsymmetricKey - openssl_get_publickey() が返す鍵。

string - PEM フォーマットの鍵 (例: -----BEGIN PUBLIC KEY----- MIIBCgK... など)。

algorithm

int - いずれかの 署名アルゴリズム。

string - openssl_get_md_methods() が返す文字列 ("sha1WithRSAEncryption" や "sha512" など)。

戻り値

署名 (signature) が正しい場合に 1、正しくない場合に 0、 エラーの場合に -1 または false を返します。

変更履歴

バージョン | 説明
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_verify() の例

<?php
// $data および $signature はデータおよび署名が含まれていると仮定

// 認証局から公開鍵を取得し、使用可能にする
$pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

// 署名が正しいかどうかを確認
$ok = openssl_verify($data, $signature, $pubkeyid);
if ($ok == 1) {
echo "正しいです";
} elseif ($ok == 0) {
echo "正しくありません";
} else {
echo "署名を確認する際にエラーが発生しました";
}
// メモリからキーを開放
openssl_free_key($pubkeyid);
?>

例2 openssl_verify() の例

<?php
// 署名したいデータ
$data = 'my data';

// 新しい秘密鍵と公開鍵を作成
$private_key_res = openssl_pkey_new(array(
"private_key_bits" => 2048,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
));
$details = openssl_pkey_get_details($private_key_res);
$public_key_res = openssl_pkey_get_public($details['key']);

// 署名を作成
openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

// 署名を検証
$ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
if ($ok == 1) {
echo "valid";
} elseif ($ok == 0) {
echo "invalid";
} else {
echo "error: ".openssl_error_string();
}
?>

参考

  • openssl_sign() - 署名を生成する


秘密鍵が証明書に対応するかを確認する

  • ≪ openssl_verify
  • openssl_x509_checkpurpose ≫
  • PHP Manual
  • OpenSSL 関数
  • 秘密鍵が証明書に対応するかを確認する

openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する

説明

openssl_x509_check_private_key(OpenSSLCertificate|string $certificate, #[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $private_key): bool

private_key が certificate に対応する秘密鍵かどうかを調べます。

警告

この関数は private_key が秘密鍵かどうかをチェックしません。 単に、公開されている材料 (例: RSA 鍵の exponent や modulus) かつ/または キーペアのキーのパラメータ (例: ECキー の EC params) を比較しているだけです。

これはたとえば、公開鍵を private_key に与えても、 関数が true を返す可能性があるということです。

パラメータ

certificate

証明書。

private_key

秘密鍵。

戻り値

private_key が certificate に対応する秘密鍵の場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | private_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。


証明書が特定の目的に使用可能かどうか確認する

  • ≪ openssl_x509_check_private_key
  • openssl_x509_export ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書が特定の目的に使用可能かどうか確認する

openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する

説明

openssl_x509_checkpurpose(
OpenSSLCertificate|string $certificate,
int $purpose,
array $ca_info = [],
?string $untrusted_certificates_file = null
): bool|int

openssl_x509_checkpurpose() は証明書を調べ、 purpose で指定した目的に使用可能であるかどうかを確認します。

パラメータ

certificate

調べたい証明書。

purpose

openssl_x509_checkpurpose() の目的
定数 | 説明
X509_PURPOSE_SSL_CLIENT | この証明書を SSL 接続のクライアント側で使用できるか?
X509_PURPOSE_SSL_SERVER | この証明書を SSL 接続のサーバー側で使用できるか?
X509_PURPOSE_NS_SSL_SERVER | この証明書を Netscape SSL サーバーで使用できるか?
X509_PURPOSE_SMIME_SIGN | この証明書を S/MIME email で使用できるか?
X509_PURPOSE_SMIME_ENCRYPT | この証明書を S/MIME email の暗号化で使用できるか?
X509_PURPOSE_CRL_SIGN | この証明書を証明書取消リスト(CRL)にサインをする際に使用できるか?
X509_PURPOSE_ANY | この証明書をあらゆる用途に使用できるか?
これらのオプションはビットフィールドではありません。 指定できるのは一つだけです!

ca_info

ca_info は、証明書の認証 で説明したような信頼できる CA ファイル/ディレクトリの配列です。

untrusted_certificates_file

指定した場合は、これが証明書を含むPEMエンコードされたファイルの名前になります。 この証明書は、検証と証明を簡単化するために使用されます。 そのファイル内にある証明書は、信頼されない(untrusted)証明書とみなされます。

戻り値

証明書が意図した目的に使用可能である場合に true、使用できない場合に false 、エラーの場合に -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | untrusted_certificates_file は、nullable になりました。


証明書を文字列としてエクスポートする

  • ≪ openssl_x509_checkpurpose
  • openssl_x509_export_to_file ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書を文字列としてエクスポートする

openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — 証明書を文字列としてエクスポートする

説明

openssl_x509_export(OpenSSLCertificate|string $certificate, string &$output, bool $no_text = true): bool

openssl_x509_export() は、 PEMエンコード形式の certificate を文字列 output に保存します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output

成功した場合に、ここに PEM が格納されます。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。


証明書をファイルにエクスポートする

  • ≪ openssl_x509_export
  • openssl_x509_fingerprint ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書をファイルにエクスポートする

openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — 証明書をファイルにエクスポートする

説明

openssl_x509_export_to_file(OpenSSLCertificate|string $certificate, string $output_filename, bool $no_text = true): bool

openssl_x509_export_to_file() は、 PEMエンコード形式の certificate をファイル output_filename に保存します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

output_filename

出力ファイルへのパス。

no_text

オプションのパラメータ notext を設定すると、出力内容の冗長性が変化します。false を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 notext のデフォルト値は true です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。


与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

  • ≪ openssl_x509_export_to_file
  • openssl_x509_free ≫
  • PHP Manual
  • OpenSSL 関数
  • 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

説明

openssl_x509_fingerprint(OpenSSLCertificate|string $certificate, string $digest_algo = "sha1", bool $binary = false): string|false

openssl_x509_fingerprint() は certificate のダイジェストを文字列で返します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

digest_algo

"sha256" といったダイジェストメソッド、またはハッシュアルゴリズム。 有効な値の一覧は、openssl_get_md_methods() で得られます。

binary

true が設定された場合、生のバイナリデータを出力します。false では小文字の8進数を出力します。

戻り値

binary が true に設定されていない場合、小文字の8進数として計算された証明書のフィンガープリントを含む文字列を返します。 binary が true に設定されている場合、メッセージダイジェストの生のバイナリ表現が返されます。

失敗したときは false を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。


証明書リソースを開放する

  • ≪ openssl_x509_fingerprint
  • openssl_x509_parse ≫
  • PHP Manual
  • OpenSSL 関数
  • 証明書リソースを開放する

openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — 証明書リソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

openssl_x509_free(OpenSSLCertificate $certificate): void

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

openssl_x509_free() は、メモリから指定した certificate リソースに関連した証明書を開放します。

パラメータ

certificate

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行しても何も起きなくなったからです。
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。


X509 証明書をパースし、配列として情報を返す

  • ≪ openssl_x509_free
  • openssl_x509_read ≫
  • PHP Manual
  • OpenSSL 関数
  • X509 証明書をパースし、配列として情報を返す

openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — X509 証明書をパースし、配列として情報を返す

説明

openssl_x509_parse(OpenSSLCertificate|string $certificate, bool $short_names = true): array|false

openssl_x509_parse() は、指定した certificate に関する情報を返します。この情報には 題名、発行者名、目的、発効日および有効期限等が含まれます。

パラメータ

certificate

X509証明書。正しい値の一覧は キー/証明書パラメータ を参照ください。

short_names

short_names は、配列中でのデータの添字付けの 方法を設定します。short_names が true の場合 (デフォルト)、フィールドは短縮型で添字が付けられます。そうでない場合、 長い名前が使用されます。例えば、CN は commonName の短縮型です。

戻り値

返されるデータの構造については（わざと）まだ文書化していません。 これは、今後もデータの構造が変更される可能性があるためです。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。


X.509 証明書をパースし、オブジェクトを返す

  • ≪ openssl_x509_parse
  • openssl_x509_verify ≫
  • PHP Manual
  • OpenSSL 関数
  • X.509 証明書をパースし、オブジェクトを返す

openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — X.509 証明書をパースし、オブジェクトを返す

説明

openssl_x509_read(OpenSSLCertificate|string $certificate): OpenSSLCertificate|false

openssl_x509_read() は、 certificate で指定した証明書をパースし、 その証明書用の OpenSSLCertificate オブジェクトを返します。

パラメータ

certificate

X509 証明書。有効な値の一覧は、 Key/Certificate parameters を参照ください。

戻り値

成功した場合に OpenSSLCertificate オブジェクトを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は OpenSSLCertificate クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを返していました。
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。


x509証明書のデジタル署名を公開鍵で検証する

  • ≪ openssl_x509_read
  • OpenSSLCertificate ≫
  • PHP Manual
  • OpenSSL 関数
  • x509証明書のデジタル署名を公開鍵で検証する

openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — x509証明書のデジタル署名を公開鍵で検証する

説明

openssl_x509_verify(OpenSSLCertificate|string $certificate, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string $public_key): int

openssl_x509_verify() 関数は、 certificate 証明書が 公開鍵 public_key に対応する秘密鍵で署名されたかどうかを検証します。

パラメータ

x509

使用できる値の一覧は キー/証明書パラメータ を参照ください。

public_key

OpenSSLAsymmetricKey - openssl_get_publickey() で返された公開鍵

string - PEMエンコードされた鍵。-----BEGIN PUBLIC KEY----- MIIBCgK... のようなものです。

戻り値

署名が正しければ 1 を。そうでなければ 0 を返し、 エラーが発生した場合は -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | certificate は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL X.509 型のリソースを受け入れていました。
8.0.0 | public_key は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 OpenSSL key または OpenSSL X.509 型のリソースを受け入れていました。

例

例1 openssl_x509_verify() の例

<?php
$hostname = "news.php.net";
$ssloptions = array(
"capture_peer_cert" => true,
"capture_peer_cert_chain" => true,
"allow_self_signed"=> false,
"CN_match" => $hostname,
"verify_peer" => true,
"SNI_enabled" => true,
"SNI_server_name" => $hostname,
);

$ctx = stream_context_create( array("ssl" => $ssloptions) );
$result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
$cont = stream_context_get_params($result);
$x509 = $cont["options"]["ssl"]["peer_certificate"];
$certparsed = openssl_x509_parse($x509);

foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
{
$chainparsed = openssl_x509_parse($chaincert);
$chain_public_key = openssl_get_publickey($chaincert);
$r = openssl_x509_verify($x509, $chain_public_key);
if ($r==1)
{
echo $certparsed['subject']['CN'];
echo " was digitally signed by ";
echo $chainparsed['subject']['CN']."\n";
}
}
?>

参考

  • openssl_verify() - 署名を検証する
  • openssl_get_publickey() - openssl_pkey_get_public のエイリアス


OpenSSLCertificate クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 OpenSSL X.509 リソースを置き換える完全不透明クラスです。

クラス概要

final class OpenSSLCertificate {
}


OpenSSLCertificateSigningRequest クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 OpenSSL X.509 CSR リソースを置き換える完全不透明クラスです。

クラス概要

final class OpenSSLCertificateSigningRequest {
}


OpenSSLAsymmetricKey クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 OpenSSL key リソースを置き換える完全不透明クラスです。

クラス概要

final class OpenSSLAsymmetricKey {
}


パスワードのハッシュ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • Password Hashing 関数
    • password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する
    • password_get_info — 指定したハッシュに関する情報を返す
    • password_hash — パスワードハッシュを作る
    • password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる
    • password_verify — パスワードがハッシュにマッチするかどうかを調べる


はじめに

パスワードハッシュ API は crypt() および他のいくつかのパスワードハッシュアルゴリズムを 手軽に使えるようにしたラッパーで、 パスワードの作成や管理を安全な方法で行えます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • パスワードのハッシュ
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

外部ライブラリは必要ありません。

ただし、Argon2 パスワードハッシュの場合、» libargon2 が必要です。 PHP 7.3.0 以降では、libargon2 バージョン 20161029 以降が必要です。


インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

ただし、Argon2 パスワードハッシュを有効にするには、--with-password-argon2 オプションを使用して、 libargon2 のサポートを有効にして PHP をビルドする必要があります。

PHP 8.1.0 より前のバージョンでは、 --with-password-argon2[=DIR] を使って argon2 のディレクトリを指定できます。


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

PASSWORD_BCRYPT (string)

PASSWORD_BCRYPT を使うと、 CRYPT_BLOWFISH アルゴリズムで新たなパスワードハッシュを作ります。

これは常に、"$2y$" crypt フォーマットを使ったハッシュになります。 長さは常に 60 文字です。

サポートするオプション

  • salt (string) - パスワードのハッシュに使うソルトを手動で設定します。 これは、自動生成されたソルトを上書きすることに注意しましょう。

    省略した場合は、パスワードをハッシュするたびに password_hash() がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。 および PHP 7.0.0 以降でソルト・オプションは非推奨になりました。

  • cost (int) - 利用するアルゴリズムのコストを表します。 値の例については crypt() のページを参照ください。

    省略した場合のデフォルトは 10 です。この値でもかまいませんが、 ハードウェアの性能が許すならもう少し高くすることもできます。

PASSWORD_BCRYPT_DEFAULT_COST (int)

PASSWORD_ARGON2I (string)

PASSWORD_ARGON2I を使うと、 Argon2i アルゴリズムで新たなパスワードハッシュを作ります。

サポートするオプション

  • memory_cost (int) - Argon2 ハッシュの計算に用いるメモリの最大値 (キロバイト数) を設定します。 デフォルトは PASSWORD_ARGON2_DEFAULT_MEMORY_COST です。

  • time_cost (int) - Argon2 ハッシュの計算にかける時間の最大値を設定します。 デフォルトは PASSWORD_ARGON2_DEFAULT_TIME_COST です。

  • threads (int) - Argon2 ハッシュの計算に用いるスレッド数を設定します。 デフォルトは PASSWORD_ARGON2_DEFAULT_THREADS です。 libargon2 を使う場合のみ利用可能で、 libsodium の実装には含まれていません。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2ID (string)

PASSWORD_ARGON2ID を使うと、 Argon2id アルゴリズムで新たなパスワードハッシュを作ります。 サポートされるオプションは、 PASSWORD_ARGON2I と同じです。

PHP 7.3.0 以降で利用可能です。

PASSWORD_ARGON2_DEFAULT_MEMORY_COST (int)

ハッシュの計算に用いるメモリのデフォルト値。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2_DEFAULT_TIME_COST (int)

ハッシュの計算にかける時間のデフォルト値。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2_DEFAULT_THREADS (int)

Argon2lib が用いるデフォルトのスレッド数。 libsodium の実装では利用できません。

PHP 7.2.0 以降で利用可能です。

PASSWORD_ARGON2_PROVIDER (string)

PHP 7.4.0 以降で利用可能です。

PASSWORD_DEFAULT (mixed)

アルゴリズムを指定しなかったときのデフォルトとして使うアルゴリズム。 PHP のバージョンが上がるときに、 その時点でより強力なハッシュアルゴリズムに対応していればデフォルトが変わる可能性があります。

この定数の値は、今後変わる可能性がある (きっと変わる) ことに注意しましょう。 つまり、生成されるハッシュの長さも変わる可能性があるということです。 したがって、PASSWORD_DEFAULT を使う場合は、 ハッシュの格納先は 60 文字以上でも格納できるようにしておく必要があります (255 文字程度にしておくことをおすすめします)。

この定数の値

  • PHP 5.5.0 - PASSWORD_BCRYPT

変更履歴

バージョン | 説明
7.4.0 | パスワードのアルゴリズムのID (PASSWORD_BCRYPT, PASSWORD_ARGON2I, PASSWORD_ARGON2ID, PASSWORD_DEFAULT) は、string に変更されました。 これより前のバージョンでは、int でした。


Password Hashing 関数

目次

  • password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する
  • password_get_info — 指定したハッシュに関する情報を返す
  • password_hash — パスワードハッシュを作る
  • password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる
  • password_verify — パスワードがハッシュにマッチするかどうかを調べる


利用可能なパスワードハッシュアルゴリズムのIDを取得する

  • ≪ Password Hashing 関数
  • password_get_info ≫
  • PHP Manual
  • Password Hashing 関数
  • 利用可能なパスワードハッシュアルゴリズムのIDを取得する

password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する

説明

password_algos(): array

登録済みのパスワードハッシュアルゴリズムのIDの完全な一覧を、 文字列の配列として返します。

パラメータ

この関数にはパラメータはありません。

戻り値

利用可能なパスワードハッシュアルゴリズムのIDを返します。

例

例1 password() の基本的な使用法

<?php
print_r(password_algos());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 2y
    [1] => argon2i
    [2] => argon2id
)


指定したハッシュに関する情報を返す

  • ≪ password_algos
  • password_hash ≫
  • PHP Manual
  • Password Hashing 関数
  • 指定したハッシュに関する情報を返す

password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — 指定したハッシュに関する情報を返す

説明

password_get_info(string $hash): array

password_hash() がサポートするアルゴリズムで生成した有効なハッシュを渡すと、 そのハッシュに関する情報の配列を返します。

パラメータ

hash

password_hash() が作ったハッシュ。

戻り値

三つの要素を持つ連想配列を返します。

  • algo には、そのハッシュの パスワードアルゴリズム定数 が含まれます。
  • algoName には、そのアルゴリズムの名前が含まれます。
  • options には、 password_hash() を呼んだときのオプションが含まれます。


パスワードハッシュを作る

  • ≪ password_get_info
  • password_needs_rehash ≫
  • PHP Manual
  • Password Hashing 関数
  • パスワードハッシュを作る

password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — パスワードハッシュを作る

説明

password_hash(#[\SensitiveParameter] string $password, string|int|null $algo, array $options = []): string

password_hash() は、 強力な一方向ハッシュアルゴリズムを使って、 新しいパスワードハッシュを作ります。

現在、以下のアルゴリズムに対応しています。

  • PASSWORD_DEFAULT - bcrypt アルゴリズムを使います (PHP 5.5.0 の時点でのデフォルトです)。 新しくてより強力なアルゴリズムが PHP に追加されれば、 この定数もそれにあわせて変わっていきます。 そのため、これを指定したときの結果の長さは、変わる可能性があります。 したがって、結果をデータベースに格納するときにはカラム幅を 60 文字以上にできるようなカラムを使うことをお勧めします (255 文字くらいが適切でしょう)。
  • PASSWORD_BCRYPT - CRYPT_BLOWFISH アルゴリズムを使ってハッシュを作ります。これは標準の crypt() 互換のハッシュで、識別子 "$2y$" を使った場合の結果を作ります。 その結果は、常に 60 文字の文字列になります。失敗した場合に false を返します。
  • PASSWORD_ARGON2I - Argon2i ハッシュアルゴリズムを使って ハッシュを作ります。このアルゴリズムは、 PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。
  • PASSWORD_ARGON2ID - Argon2id ハッシュアルゴリズムを使って ハッシュを作ります。このアルゴリズムは、 PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。

PASSWORD_BCRYPT がサポートするオプション:

  • salt (string) - パスワードのハッシュに使うソルトを手動で設定します。 これは、自動生成されたソルトを上書きすることに注意しましょう。

    省略した場合は、パスワードをハッシュするたびに password_hash() がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。

    警告

    このソルト・オプションは 非推奨になっています。 このオプションは指定せずに、デフォルトで生成されるソルトを使うことを推奨します。 PHP 8.0.0 以降は、この値を明示的に指定しても無視されます。

  • cost (int) - 利用するアルゴリズムのコストを表します。 値の例については crypt() のページを参照ください。

    省略した場合のデフォルトは 10 です。この値でもかまいませんが、 ハードウェアの性能が許すならもう少し高くすることもできます。

PASSWORD_ARGON2I と PASSWORD_ARGON2ID が サポートするオプション

  • memory_cost (int) - Argon2 ハッシュを計算するのに 使われるメモリの最大値(キロバイト単位)。 デフォルトは PASSWORD_ARGON2_DEFAULT_MEMORY_COST です。

  • time_cost (int) - Argon2 ハッシュを計算するのに 使って良い時間の最大値。 デフォルトは PASSWORD_ARGON2_DEFAULT_TIME_COST です。

  • threads (int) - Argon2 ハッシュを計算するのに使う スレッド数。 デフォルトは PASSWORD_ARGON2_DEFAULT_THREADS です。

    警告

    PHP が libargon2 を使う場合にのみ利用可能です。 libsodium の実装では利用できません。

パラメータ

password

ユーザーのパスワード。

警告

PASSWORD_BCRYPT をアルゴリズムに指定すると、 password が最大 72 バイトまでに切り詰められます。

algo

パスワードのハッシュに使うアルゴリズムを表す パスワードアルゴリズム定数。

options

オプションを含む連想配列。各アルゴリズムがサポートするオプションについては、 パスワードアルゴリズム定数 のページを参照ください。

省略した場合は、ランダムな salt を生成してデフォルトのコストを使います。

戻り値

ハッシュしたパスワードを返します。

使ったアルゴリズムやコスト、そしてソルトもハッシュの一部として返されます。 つまり、ハッシュを検証するために必要な情報は、すべてそこに含まれているということです。 そのため、password_verify() でハッシュを検証するときに、 ソルトやアルゴリズムの情報を別に保存する必要はありません。

変更履歴

バージョン | 説明
8.0.0 | password_hash() は、失敗時に false を返さなくなりました。 代わりに、パスワードハッシュのアルゴリズムが有効でなかった場合は ValueError がスローされるようになりました。 また、パスワードハッシュの作成が不明なエラーで失敗した場合は、 Error がスローされるようになっています。
8.0.0 | 引数 algo は、 nullable になりました。
7.4.0 | algo パラメータは string を期待するようになりました。 しかし、後方互換性のために int も未だ受け入れています。
7.4.0 | sodium 拡張モジュールが、 Argon2 パスワードの実装の代替を提供するようになりました。
7.3.0 | PASSWORD_ARGON2ID を使った、 Argon2id パスワードのサポートが追加されました。
7.2.0 | PASSWORD_ARGON2I を使った、 Argon2i パスワードのサポートが追加されました。

例

例1 password_hash() の例

<?php
/**
* デフォルトのアルゴリズムを使ってパスワードをハッシュします。
* 現時点でのデフォルトは BCRYPT で、その結果は 60 文字になります。
*
* デフォルトは、今後変わる可能性があることに注意しましょう。結果が
* 60 文字以上になっても対応できるようにしておきましょう (255 あたりが適切です)
*/
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
?>

上の例の出力は、 たとえば以下のようになります。

$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a

例2 password_hash() で、コストを手動で設定する例

<?php
/**
* この例では、BCRYPT のコストをデフォルトより上げて、12 にします。
* また、アルゴリズムを BCRYPT に変えたことにも注目しましょう。結果は常に 60 文字になります。
*/
$options = [
'cost' => 12,
];
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
?>

上の例の出力は、 たとえば以下のようになります。

$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K

例3 password_hash() で、適切なコストを探す例

<?php
/**
* このコードは、サーバーをベンチマークして、どの程度のコストに耐えられるかを判断します。
* サーバーに負荷をかけすぎない範囲で、できるだけ高めのコストを設定したいものです。
* 基準として 10 程度からはじめ、サーバーが十分に高速なら、できるだけ上げていきましょう。
* 以下のコードでは、ストレッチングの時間を 350 ミリ秒以内にすることを狙っています。
* 対話形式のログインを扱う際の許容時間としては、このあたりが適切でしょう。
*/
$timeTarget = 0.350; // 350 ミリ秒

$cost = 10;
do {
$cost++;
$start = microtime(true);
password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
$end = microtime(true);
} while (($end - $start) < $timeTarget);

echo "Appropriate Cost Found: " . $cost;
?>

上の例の出力は、 たとえば以下のようになります。

Appropriate Cost Found: 12

例4 Argon2i を使った password_hash() の例

<?php
echo 'Argon2i hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
?>

上の例の出力は、 たとえば以下のようになります。

Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

注意

警告

この関数で使うソルトを自前で設定するのはお勧めしません。 ソルトを省略すれば、安全なソルトをこの関数が自動的に作ってくれます。

先述のとおり、PHP 7.0 で salt オプションを指定すると、 非推奨の警告が発生します。ソルトを手動で設定する仕組みは、PHP 8.0 で削除されました。

注意:

実際にサーバー上でこの関数をテストして、コストパラメータの適切な設定値を調整することをお勧めします。 対話型のシステムなら、関数の実行時間が 350 ミリ秒くらいに収まるくらいが適切です。 先ほどの例のスクリプトは、自分のハードウェア上での適切なコストを判断するための助けとなるでしょう。

注意: この関数がサポートするアルゴリズムの更新 (あるいはデフォルトのアルゴリズムの変更) は、必ず次の手順にのっとって行われます。

  • 新しく追加されたアルゴリズムがデフォルトになるまでには、 少なくとも一度は PHP のフルリリースを経ること。 つまり、たとえば、新しいアルゴリズムが 7.5.5 で追加されたとすると、 そのアルゴリズムがデフォルトになるのは早くても 7.7 以降ということになります (7.6 は、最初のフルリリースだからです)。 しかし、もし別のアルゴリズムが 7.6.0 で追加されたとすると、 そのアルゴリズムも 7.7.0 の時点でデフォルトになる資格を得ます。
  • デフォルトを変更できるのはフルリリース (7.3.0 や 8.0.0 など) のときだけで、リビジョンリリースでは変更できない。 唯一の例外は、現在のデフォルトにセキュリティ上の致命的な欠陥が発覚した場合の緊急リリースです。

参考

  • password_verify() - パスワードがハッシュにマッチするかどうかを調べる
  • password_needs_rehash() - 指定したハッシュがオプションにマッチするかどうかを調べる
  • crypt() - 文字列の一方向のハッシュ化を行う
  • sodium_crypto_pwhash_str() - ASCII 文字でエンコードされたハッシュ値を得る


指定したハッシュがオプションにマッチするかどうかを調べる

  • ≪ password_hash
  • password_verify ≫
  • PHP Manual
  • Password Hashing 関数
  • 指定したハッシュがオプションにマッチするかどうかを調べる

password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる

説明

password_needs_rehash(string $hash, string|int|null $algo, array $options = []): bool

指定したハッシュが、特定のアルゴリズムとオプションを満たしているかどうかを調べます。 満たしていない場合は、ハッシュを再計算する必要があるとみなします。

パラメータ

hash

password_hash() が作ったハッシュ。

algo

パスワードのハッシュに使うアルゴリズムを表す パスワードアルゴリズム定数。

options

オプションを含む連想配列。各アルゴリズムがサポートするオプションについては、 パスワードアルゴリズム定数 のページを参照ください。

戻り値

指定した algo と options にマッチするためにハッシュの再計算が必要な場合は true、 それ以外の場合は false を返します。

変更履歴

バージョン | 説明
7.4.0 | algo パラメータは string を期待するようになりました。 しかし、後方互換性のために int も未だ受け入れています。

例

例1 password_needs_rehash() の使用例

<?php

$password = 'rasmuslerdorf';
$hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS';

$algorithm = PASSWORD_BCRYPT;
// bcrypt の cost パラメータは、ハードウェアの性能の向上にあわせて変えることができます
$options = ['cost' => 12];

// 格納されたハッシュを、平文のパスワードに対して検証します
if (password_verify($password, $hash)) {
// ハッシュアルゴリズムやオプションが変更されたかを確認します。
if (password_needs_rehash($hash, $algorithm, $options)) {
// 変更された場合は新しいハッシュを計算して、古いものを置き換えます
$newHash = password_hash($password, $algorithm, $options);

// ユーザーのレコードを $newHash で更新します
}

// ログイン
}
?>


パスワードがハッシュにマッチするかどうかを調べる

  • ≪ password_needs_rehash
  • Rnp ≫
  • PHP Manual
  • Password Hashing 関数
  • パスワードがハッシュにマッチするかどうかを調べる

password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — パスワードがハッシュにマッチするかどうかを調べる

説明

password_verify(#[\SensitiveParameter] string $password, string $hash): bool

指定したハッシュがパスワードにマッチするかどうかを調べます。
password_verify() は
crypt() と互換性があるので、
crypt() が作ったパスワードハッシュは
password_verify() でも使えます。

password_hash() は、 アルゴリズムやコスト、ソルトといった情報もハッシュに含めて返すことに注意しましょう。 したがって、ハッシュの検証に必要な情報はすべてそこに含まれていることになります。 これで、検証関数がハッシュの検証をするときに、ソルトやアルゴリズム情報を別の場所から取得する必要がなくなります。

この関数は、タイミング攻撃に対して安全です。

パラメータ

password

ユーザーのパスワード。

hash

password_hash() が作ったハッシュ。

戻り値

パスワードとハッシュがマッチする場合に true、それ以外の場合に false を返します。

例

例1 password_verify() の例

以下は簡略化した例です。必要に応じて、正しいパスワードのハッシュを再計算することを推奨します。 password_needs_rehash() の例も参照ください。

<?php
// これをどうやって作ったのかは、password_hash() の例を参照ください
$hash = '$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a';

if (password_verify('rasmuslerdorf', $hash)) {
echo 'Password is valid!';
} else {
echo 'Invalid password.';
}
?>

上の例の出力は以下となります。

Password is valid!

参考

  • password_needs_rehash() - 指定したハッシュがオプションにマッチするかどうかを調べる
  • password_hash() - パスワードハッシュを作る
  • » ユーザーランドでの実装
  • sodium_crypto_pwhash_str_verify() - パスワードが、ハッシュ値と一致するかを調べる


Rnp

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
    • Clearsign text
  • Rnp 関数
    • rnp_backend_string — Return cryptographic backend library name
    • rnp_backend_version — Return cryptographic backend library version
    • rnp_decrypt — Decrypt PGP message
    • rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format
    • rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string
    • rnp_ffi_create — Create the top-level object used for interacting with the library
    • rnp_ffi_destroy — Destroy the top-level object used for interacting with the library
    • rnp_ffi_set_pass_provider — Set password provider callback function
    • rnp_import_keys — Import keys from PHP string to the keyring and receive JSON describing new/updated keys
    • rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys
    • rnp_key_export — Export a key
    • rnp_key_export_autocrypt — Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)
    • rnp_key_export_revocation — Generate and export primary key revocation signature
    • rnp_key_get_info — Get information about the key
    • rnp_key_remove — Remove a key from keyring(s)
    • rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature
    • rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type
    • rnp_load_keys — Load keys from PHP string
    • rnp_load_keys_from_path — Load keys from specified path
    • rnp_locate_key — Search for the key
    • rnp_op_encrypt — Encrypt message
    • rnp_op_generate_key — Generate key
    • rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)
    • rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message
    • rnp_op_sign_detached — Perform signing operation, return detached signature(s)
    • rnp_op_verify — Verify embedded or cleartext signatures
    • rnp_op_verify_detached — Verify detached signatures
    • rnp_save_keys — Save keys to PHP string
    • rnp_save_keys_to_path — Save keys to specified path
    • rnp_supported_features — Get supported features in JSON format
    • rnp_version_string — RNP library version
    • rnp_version_string_full — Full version string of RNP library
  • RnpFFI — The RnpFFI class


はじめに

This module allows you to use » RNP library. RNP is a high performance C++ OpenPGP library used by Mozilla Thunderbird.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Rnp
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

In order to use RNP library functions you need to install the» RNP library. RNP library version >= 0.16.2 is required.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/rnp


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RNP_KEYSTORE_GPG (string)
Keystore format "GPG".
RNP_KEYSTORE_KBX (string)
Keystore format "KBX". For public keys only. A keybox is a file format used to store public keys along with meta information and indices.
RNP_KEYSTORE_G10 (string)
Keystore format "G10". For private keys.
RNP_LOAD_SAVE_PUBLIC_KEYS (integer)
Load or save public keys only. Can be OR-ed with RNP_LOAD_SAVE_SECRET_KEYS to load both public and private keys to the FFI context or save them from the context.
RNP_LOAD_SAVE_SECRET_KEYS (integer)
Load or save secret keys only. Can be OR-ed with RNP_LOAD_SAVE_PUBLIC_KEYS to load both public and private keys to the FFI context or save them from the context.
RNP_LOAD_SAVE_PERMISSIVE (integer)
Allows to ignore bad signature/key/subkey packets during key import.
RNP_LOAD_SAVE_SINGLE (integer)
If set, only the first key will be loaded.
RNP_LOAD_SAVE_BASE64 (integer)
Allow import of base64-encoded keys (autocrypt ones).
RNP_FEATURE_SYMM_ALG (string)
List available symmetric encryption algorithms.
RNP_FEATURE_AEAD_ALG (string)
List available AEAD algorithms.
RNP_FEATURE_PROT_MODE (string)
List available protection modes.
RNP_FEATURE_PK_ALG (string)
List available public key algorithms.
RNP_FEATURE_HASH_ALG (string)
List available hash algorithms.
RNP_FEATURE_COMP_ALG (string)
List available compression algorithms.
RNP_FEATURE_CURVE (string)
List available elliptic curves.
RNP_DUMP_MPI (integer)
Dump MPI (Multi-precision integer) values.
RNP_DUMP_RAW (integer)
Dump raw packet contents as well.
RNP_DUMP_GRIP (integer)
Dump key fingerprints and grips.
RNP_JSON_DUMP_MPI (integer)
Dump MPI (Multi-precision integer) values.
RNP_JSON_DUMP_RAW (integer)
Dump raw packet contents as well.
RNP_JSON_DUMP_GRIP (integer)
Dump key fingerprints and grips.
RNP_ENCRYPT_NOWRAP (integer)
Allows encryption of signed message. Message is not wrapped into literal data packet.
RNP_KEY_EXPORT_ARMORED (integer)
Enable ASCII-armoring of exported data.
RNP_KEY_EXPORT_PUBLIC (integer)
Export public key.
RNP_KEY_EXPORT_SECRET (integer)
Export secret key.
RNP_KEY_EXPORT_SUBKEYS (integer)
If primary key is being exported, all subkeys will be exported too.
RNP_KEY_EXPORT_BASE64 (integer)
Export base64-encoded autocrypt key instead of binary.
RNP_KEY_REMOVE_PUBLIC (integer)
Remove public key.
RNP_KEY_REMOVE_SECRET (integer)
Remove secret key.
RNP_KEY_REMOVE_SUBKEYS (integer)
If primary key is being deleted, all of its subkeys will be removed too.


  • ≪ 定義済み定数
  • Clearsign text ≫
  • PHP Manual
  • Rnp
  • 例

例

目次

  • Clearsign text


Clearsign text

This example will clearsign a given text.

例1 RNP clearsign example

<?php
// init FFI object
$ffi = rnp_ffi_create('GPG', 'GPG');

// generate RSA key
$key = rnp_op_generate_key($ffi, 'test@example.com', 'RSA');

// sign
$data = "Example text to sign";
$signature = rnp_op_sign_cleartext($ffi, $data, array($key));

echo $signature;

// destroy FFI object
rnp_ffi_destroy($ffi);
?>


Rnp 関数

目次

  • rnp_backend_string — Return cryptographic backend library name
  • rnp_backend_version — Return cryptographic backend library version
  • rnp_decrypt — Decrypt PGP message
  • rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format
  • rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string
  • rnp_ffi_create — Create the top-level object used for interacting with the library
  • rnp_ffi_destroy — Destroy the top-level object used for interacting with the library
  • rnp_ffi_set_pass_provider — Set password provider callback function
  • rnp_import_keys — Import keys from PHP string to the keyring and receive JSON describing new/updated keys
  • rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys
  • rnp_key_export — Export a key
  • rnp_key_export_autocrypt — Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)
  • rnp_key_export_revocation — Generate and export primary key revocation signature
  • rnp_key_get_info — Get information about the key
  • rnp_key_remove — Remove a key from keyring(s)
  • rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature
  • rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type
  • rnp_load_keys — Load keys from PHP string
  • rnp_load_keys_from_path — Load keys from specified path
  • rnp_locate_key — Search for the key
  • rnp_op_encrypt — Encrypt message
  • rnp_op_generate_key — Generate key
  • rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)
  • rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message
  • rnp_op_sign_detached — Perform signing operation, return detached signature(s)
  • rnp_op_verify — Verify embedded or cleartext signatures
  • rnp_op_verify_detached — Verify detached signatures
  • rnp_save_keys — Save keys to PHP string
  • rnp_save_keys_to_path — Save keys to specified path
  • rnp_supported_features — Get supported features in JSON format
  • rnp_version_string — RNP library version
  • rnp_version_string_full — Full version string of RNP library


Return cryptographic backend library name

  • ≪ Rnp 関数
  • rnp_backend_version ≫
  • PHP Manual
  • Rnp 関数
  • Return cryptographic backend library name

rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Return cryptographic backend library name

説明

rnp_backend_string(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Backend name string. Currently supported backends are "Botan" and "OpenSSL".


Return cryptographic backend library version

  • ≪ rnp_backend_string
  • rnp_decrypt ≫
  • PHP Manual
  • Rnp 関数
  • Return cryptographic backend library version

rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Return cryptographic backend library version

説明

rnp_backend_version(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Version string.


Decrypt PGP message

  • ≪ rnp_backend_version
  • rnp_dump_packets ≫
  • PHP Manual
  • Rnp 関数
  • Decrypt PGP message

rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Decrypt PGP message

説明

rnp_decrypt(RnpFFI $ffi, string $input): string|false

Private keys used for decryption should be loaded into the FFI object before calling this function. If password encryption was used, then password provider should be set by calling rnp_ffi_set_pass_provider().

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

input

Encrypted message.

戻り値

Decrypted message on success失敗した場合に false を返します.


Dump OpenPGP packets stream information in humand-readable format

  • ≪ rnp_decrypt
  • rnp_dump_packets_to_json ≫
  • PHP Manual
  • Rnp 関数
  • Dump OpenPGP packets stream information in humand-readable format

rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format

説明

rnp_dump_packets(string $input, int $flags): string|false

パラメータ

input

Input string containing OpenPGP data, either in binary or ASCII-armored format.

flags

See RNP_DUMP_* predefined constants.

戻り値

Text describing packet sequence失敗した場合に false を返します.


Dump OpenPGP packets stream information to the JSON string

  • ≪ rnp_dump_packets
  • rnp_ffi_create ≫
  • PHP Manual
  • Rnp 関数
  • Dump OpenPGP packets stream information to the JSON string

rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string

説明

rnp_dump_packets_to_json(string $input, int $flags): string|false

パラメータ

input

Input string containing OpenPGP data, either in binary or ASCII-armored format.

flags

See RNP_JSON_DUMP_* predefined constants.

戻り値

JSON string with dump失敗した場合に false を返します.


Create the top-level object used for interacting with the library

  • ≪ rnp_dump_packets_to_json
  • rnp_ffi_destroy ≫
  • PHP Manual
  • Rnp 関数
  • Create the top-level object used for interacting with the library

rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Create the top-level object used for interacting with the library

説明

rnp_ffi_create(string $pub_format, string $sec_format): RnpFFI|false

パラメータ

pub_format

the format of the public keyring, RNP_KEYSTORE_GPG or other RNP_KEYSTORE_* constant.

sec_format

the format of the secret keyring, RNP_KEYSTORE_GPG or other RNP_KEYSTORE_* constant

戻り値

Returns RnpFFI object on success失敗した場合に false を返します.


Destroy the top-level object used for interacting with the library

  • ≪ rnp_ffi_create
  • rnp_ffi_set_pass_provider ≫
  • PHP Manual
  • Rnp 関数
  • Destroy the top-level object used for interacting with the library

rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Destroy the top-level object used for interacting with the library

説明

rnp_ffi_destroy(RnpFFI $ffi): void

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

戻り値


Set password provider callback function

  • ≪ rnp_ffi_destroy
  • rnp_import_keys ≫
  • PHP Manual
  • Rnp 関数
  • Set password provider callback function

rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Set password provider callback function

説明

rnp_ffi_set_pass_provider(RnpFFI $ffi, callable $password_callback): bool

Sets password provider function. This function can ask for the password on a standard input (if PHP script is executed in a command line environment), display GUI dialog or provide password in any other possible ways. Requested passwords are used to encrypt or decrypt secret keys or perform symmetric encryption/decryption operations.

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

password_callback

The function that is to be called for every password request. It has the following signature:

password_callback(string $key_fp, string $pgp_context, string &$password): bool
  • $key_fp - The key fingerprint, if any. Can be empty.
  • $pgp_context - String describing why the key is being requested.
  • $password - Password string reference where provided password should be stored to.
Callback function should return true if password was successfully set失敗した場合に false を返します.

戻り値

Returns true on success失敗した場合に false を返します.

例

例1 simple callback function example

<?php
function password_callback(string $key_fp, string $pgp_context, string &$password)
{
$password = "password";

return true;
}

$ffi = rnp_ffi_create('GPG', 'GPG');

rnp_ffi_set_pass_provider($ffi, 'password_callback');


Import keys from PHP string to the keyring and receive JSON describing new/updated keys

  • ≪ rnp_ffi_set_pass_provider
  • rnp_import_signatures ≫
  • PHP Manual
  • Rnp 関数
  • Import keys from PHP string to the keyring and receive JSON describing new/updated keys

rnp_import_keys

(PECL rnp >= 0.1.1)

rnp_import_keys — Import keys from PHP string to the keyring and receive JSON describing new/updated keys

説明

rnp_import_keys(RnpFFI $ffi, string $input, int $flags): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

input

OpenPGP packets containing key(s) to be loaded. Can be either binary or ASCII armored.

flags

See RNP_LOAD_SAVE_* predefined constants.

戻り値

JSON string with information about new and updated keys on success失敗した場合に false を返します.


Import standalone signatures to the keyring and receive JSON describing updated keys

  • ≪ rnp_import_keys
  • rnp_key_export ≫
  • PHP Manual
  • Rnp 関数
  • Import standalone signatures to the keyring and receive JSON describing updated keys

rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys

説明

rnp_import_signatures(RnpFFI $ffi, string $input, int $flags): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

input

OpenPGP packets containing signatures to be imported. Can be either binary or ASCII armored.

flags

Currently must be 0.

戻り値

JSON string with information about updated keys on success失敗した場合に false を返します.


Export a key

  • ≪ rnp_import_signatures
  • rnp_key_export_autocrypt ≫
  • PHP Manual
  • Rnp 関数
  • Export a key

rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Export a key

説明

rnp_key_export(RnpFFI $ffi, string $key_fp, int $flags): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

key_fp

Key fingerprint.

flags

See RNP_KEY_EXPORT_* predefined constants (except RNP_KEY_EXPORT_BASE64).

戻り値

OpenPGP packets of exported key (binary or ASCII-armored) on success失敗した場合に false を返します.


Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)

  • ≪ rnp_key_export
  • rnp_key_export_revocation ≫
  • PHP Manual
  • Rnp 関数
  • Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)

rnp_key_export_autocrypt

(PECL rnp >= 0.1.1)

rnp_key_export_autocrypt — Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)

説明

rnp_key_export_autocrypt(
RnpFFI $ffi,
string $key_fp,
string $subkey_fp,
string $uid,
int $flags
): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

key_fp

Primary key fingerprint.

subkey_fp

Subkey to export. Can be an empty string to pick the first suitable subkey.

uid

User ID to export. Can be an empty string if exported key has only one uid.

flags

Only RNP_KEY_EXPORT_BASE64 is currently supported. Enabling it would export base64-encoded key data instead of binary.

戻り値

OpenPGP packets of exported key on success失敗した場合に false を返します.


Generate and export primary key revocation signature

  • ≪ rnp_key_export_autocrypt
  • rnp_key_get_info ≫
  • PHP Manual
  • Rnp 関数
  • Generate and export primary key revocation signature

rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Generate and export primary key revocation signature

説明

rnp_key_export_revocation(
RnpFFI $ffi,
string $key_fp,
int $flags,
array $options = ?
): string|false

Note: to revoke a key you'll need to import this signature into the keystore or use rnp_key_revoke() function.

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

key_fp

Key fingerprint of the primary key to be revoked.

flags

RNP_KEY_EXPORT_ARMORED or 0.

options

An associative array with options.

Key | Data type | 説明
"hash" | string | Set hash algorithm used during signature calculation.
"code" | string | Code reason for revocation code. Possible values: 'no', 'superseded', 'compromised', 'retired'. If not defined, then value 'no' will be used by default.
"reason" | string | Textual representation of the reason for revocation.

戻り値

Exported revocation signature on success失敗した場合に false を返します.


Get information about the key

  • ≪ rnp_key_export_revocation
  • rnp_key_remove ≫
  • PHP Manual
  • Rnp 関数
  • Get information about the key

rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Get information about the key

説明

rnp_key_get_info(RnpFFI $ffi, string $key_fp): array|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

key_fp

Key fingerprint.

戻り値

An associative array with information about the key失敗した場合に false を返します.

Key | Data type | 説明
"is_primary" | boolean | true if this key is the primary key.
"is_sub" | boolean | true if this key is a subkey.
"is_valid" | boolean | true if public key is valid. This includes checks of the self-signatures, expiration times, revocations and so on.
"is_revoked" | boolean | true if this key is revoked.
"is_superseded" | boolean | true if this key is superseded. Present only if the key is revoked.
"is_compromised" | boolean | true if this key is compromised. Present only if the key is revoked.
"is_retired" | boolean | true if this key is retired. Present only if the key is revoked.
"is_expired" | boolean | true if this key is expired.
"have_secret" | boolean | true if this key has secret part.
"is_locked" | boolean | true if this key is currently locked. Only present for secret keys.
"is_protected" | boolean | true if this key is protected. Only present for secret keys. A protected key is one that is encrypted and can be safely held in memory and locked/unlocked as needed.
"have_public" | boolean | true if this key has public part. Generally all keys would have public part.
"valid_till" | integer | The timestamp till which key can be considered as valid. Note: this will take into account not only key's expiration, but revocations as well. For the subkey primary key's validity time will be also checked.
"bits" | integer | Number of bits in the key. For EC-based keys it will contain size of the curve.
"alg" | string | Key algorithm name.
"subkeys" | array | An indexed array containing fingerprint strings of subkeys. Only present for primary keys. Could be empty if primary key has no subkeys.
"uids" | array | An indexed array containing user ID strings. Only present for primary keys. Could be empty if primary key has no user ID-s.


Remove a key from keyring(s)

  • ≪ rnp_key_get_info
  • rnp_key_revoke ≫
  • PHP Manual
  • Rnp 関数
  • Remove a key from keyring(s)

rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Remove a key from keyring(s)

説明

rnp_key_remove(RnpFFI $ffi, string $key_fp, int $flags): bool

Note: you need to call rnp_save_keys() to write updated keyring(s) out.

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

key_fp

Key fingerprint.

flags

See RNP_KEY_REMOVE_* constants. Flag RNP_KEY_REMOVE_SUBKEYS will work only for the primary key and will remove all of its subkeys as well.

戻り値

Returns true on success失敗した場合に false を返します.


Revoke a key or subkey by generating and adding revocation signature

  • ≪ rnp_key_remove
  • rnp_list_keys ≫
  • PHP Manual
  • Rnp 関数
  • Revoke a key or subkey by generating and adding revocation signature

rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature

説明

rnp_key_revoke(
RnpFFI $ffi,
string $key_fp,
int $flags,
array $options = ?
): bool

Note: you need to call rnp_save_keys() to write updated keyring(s) out.

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

key_fp

Key fingerprint.

flags

Currently must be 0.

options

An associative array with options.

Key | Data type | 説明
"hash" | string | Set hash algorithm used during signature calculation.
"code" | string | Code reason for revocation code. Possible values: 'no', 'superseded', 'compromised', 'retired'. If not defined, then value 'no' will be used by default.
"reason" | string | Textual representation of the reason for revocation.

戻り値

Returns true on success失敗した場合に false を返します.


Enumerate all keys present in a keyring by specified identifer type

  • ≪ rnp_key_revoke
  • rnp_load_keys ≫
  • PHP Manual
  • Rnp 関数
  • Enumerate all keys present in a keyring by specified identifer type

rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type

説明

rnp_list_keys(RnpFFI $ffi, string $identifier_type): array|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

identifier_type

Key identifier type ("userid", "keyid", "grip", "fingerprint").

戻り値

An associative array where key is an identifier string and value is a PGP key fingerprint失敗した場合に false を返します.


Load keys from PHP string

  • ≪ rnp_list_keys
  • rnp_load_keys_from_path ≫
  • PHP Manual
  • Rnp 関数
  • Load keys from PHP string

rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Load keys from PHP string

説明

rnp_load_keys(
RnpFFI $ffi,
string $format,
string $input,
int $flags
): bool

Note that for G10, the input must be a directory (which must already exist).

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

format

The key format of the data (GPG, KBX, G10).

input

OpenPGP packets containing key(s) to be loaded. Can be either binary or ASCII armored.

flags

See RNP_LOAD_SAVE_* flags description.

戻り値

Returns true on success失敗した場合に false を返します.


Load keys from specified path

  • ≪ rnp_load_keys
  • rnp_locate_key ≫
  • PHP Manual
  • Rnp 関数
  • Load keys from specified path

rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Load keys from specified path

説明

rnp_load_keys_from_path(
RnpFFI $ffi,
string $format,
string $input_path,
int $flags
): bool

Note that for G10, the input must be a directory (which must already exist).

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

format

The key format of the data (GPG, KBX, G10).

input_path

file or directory containing the keys.

flags

See RNP_LOAD_SAVE_* flags description.

戻り値

Returns true on success失敗した場合に false を返します.


Search for the key

  • ≪ rnp_load_keys_from_path
  • rnp_op_encrypt ≫
  • PHP Manual
  • Rnp 関数
  • Search for the key

rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Search for the key

説明

rnp_locate_key(RnpFFI $ffi, string $identifier_type, string $identifier): string|false

Note: only valid userids are checked while searching by userid.

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

identifier_type

Identifier type string: "userid", "keyid", "fingerprint", "grip".

identifier

PGP User ID (name and email) for "userid" type, hexadecimal string that represents key id, fingerprint or key grip correspondingly.

戻り値

Returns hexadecimal fingerprint of the key found on success失敗した場合に false を返します.


Encrypt message

  • ≪ rnp_locate_key
  • rnp_op_generate_key ≫
  • PHP Manual
  • Rnp 関数
  • Encrypt message

rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Encrypt message

説明

rnp_op_encrypt(
RnpFFI $ffi,
string $message,
array $recipient_keys_fp,
array $options = ?
): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

message

Message to be encrypted.

recipient_keys_fp

Array with fingerprints of recipient's keys. At least one key must be present.

options

An associative array with options.

Key | Data type | 説明
"compression_alg" | string | Compression algorithm. Both "compression_alg" and "compression_level" must be set in order to enable data compression.
"compression_level" | integer | Compression level, 0-9. 0 disables compression.
"armor" | boolean | Enable ASCII-armored output. Disabled by default.
"add_signature" | boolean | Encrypted message will be also signed.
"hash" | string | Set hash algorithm used during signature calculation. "add_signature" option should be set to true
"creation_time" | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
"expiration_time" | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).
"password" | string | Add password which is used to encrypt data.
"cipher" | string | Set symmetric encryption algorithm. Possible values are "IDEA", "TRIPLEDES", "CAST5", "BLOWFISH", "AES128", "AES192", "AES256", "TWOFISH", "CAMELLIA128", "CAMELLIA192", "CAMELLIA256", "SM4".
"aead" | string | Set AEAD mode algorithm. Possible values are "None" to disable AEAD, "EAX", "OCB".
"aead_bits" | integer | Set chunk length for AEAD mode via number of chunk size bits. Must be between 0 to 56.
"flags" | integer | Set additional encryption flags. Supported flags: RNP_ENCRYPT_NOWRAP - do not wrap the data in a literal data packet. This would allow to encrypt already signed data.
"file_name" | string | Set the internally stored file name for the data being encrypted. Special value _CONSOLE may be used to mark message as 'for your eyes only', i.e. it should not be stored anywhere but only displayed to the receiver. Default is the empty string.
"file_mtime" | integer | Set input file modification date in seconds since Jan, 1 1970 UTC.

戻り値

Encrypted data on success失敗した場合に false を返します.


Generate key

  • ≪ rnp_op_encrypt
  • rnp_op_sign ≫
  • PHP Manual
  • Rnp 関数
  • Generate key

rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Generate key

説明

rnp_op_generate_key(
RnpFFI $ffi,
string $userid,
string $key_alg,
string $sub_alg = ?,
array $options = ?
): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

userid

PGP User ID - text that is intended to represent the name and email address of the key holder.

key_alg

Primary key algorithm (i.e. 'RSA', 'DSA', etc).

sub_alg

Subkey algorithm. If not set, subkey will not be generated.

options

An associative array with options.

Key | Data type | 説明
"bits" | integer | Primary key size in bits. Applicable only to RSA, DSA and El-Gamal keys.
"hash" | string | Hash algorithm used in self signature or subkey binding signature.
"dsa_qbits" | integer | Set size of a q parameter for DSA key. Note: appropriate default value will be set, depending on key bits. However you may override it if needed.
"curve" | string | Set the curve used for ECC key. Note: this is only applicable for ECDSA, ECDH and SM2 keys.
"request_password" | boolean | Enable requesting password via password provider. This password will be used for key encryption. Password provider callback function should be set in advance by calling rnp_ffi_set_pass_provider(). Note: this setting will be ignored if password was set via"password"
"password" | string | Set the password used to encrypt the secret key data.
"expiration" | integer | Set the key and subkey expiration time in seconds.
"sub_bits" | integer | Subkey size in bits. Applicable only to RSA, DSA and El-Gamal keys.
"sub_hash" | string | Hash algorithm used in subkey self signature or subkey binding signature.
"sub_curve" | string | Set the curve used for ECC subkey. Note: this is only applicable for ECDSA, ECDH and SM2 keys.

戻り値

Fingerprint of the generated primary key失敗した場合に false を返します. This fingerprint can be used later to reference the key in sign and encrypt operations. The key data is stored in FFI memory context and can be saved using rnp_save_keys() or rnp_save_keys_to_path().


Perform signing operation on a binary data, return embedded signature(s)

  • ≪ rnp_op_generate_key
  • rnp_op_sign_cleartext ≫
  • PHP Manual
  • Rnp 関数
  • Perform signing operation on a binary data, return embedded signature(s)

rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)

説明

rnp_op_sign(
RnpFFI $ffi,
string $data,
array $keys_fp,
array $options = ?
): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

data

Data to be signed.

keys_fp

Array with key fingerprints. At least one key must be provided. Keys should be present in ffi.

options

An associative array with options.

Key | Data type | 説明
"compression_alg" | string | Compression algorithm. Both "compression_alg" and "compression_level" must be set in order to enable data compression.
"compression_level" | integer | Compression level, 0-9. 0 disables compression.
"armor" | boolean | Enable ASCII-armored output. Disabled by default.
"hash" | string | Set hash algorithm used during signature calculation.
"creation_time" | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
"expiration_time" | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).
"file_name" | string | Set input file name.Special value _CONSOLE may be used to mark message as 'for your eyes only', i.e. it should not be stored anywhere but only displayed to the receiver. Default is the empty string.
"file_mtime" | integer | Set input file modification date in seconds since Jan, 1 1970 UTC.

戻り値

Data with embedded signature(s) on success失敗した場合に false を返します.


Perform signing operation on a textual data, return cleartext signed message

  • ≪ rnp_op_sign
  • rnp_op_sign_detached ≫
  • PHP Manual
  • Rnp 関数
  • Perform signing operation on a textual data, return cleartext signed message

rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message

説明

rnp_op_sign_cleartext(
RnpFFI $ffi,
string $data,
array $keys_fp,
array $options = ?
): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

data

Data to be signed.

keys_fp

Array with key fingerprints. At least one key must be provided. Keys should be present in ffi.

options

An associative array with options.

Key | Data type | 説明
"armor" | boolean | Enable ASCII-armored output. Disabled by default.
"hash" | string | Set hash algorithm used during signature calculation.
"creation_time" | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
"expiration_time" | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).

戻り値

Cleartext signed message containing source data with additional headers and ASCII-armored signature on success失敗した場合に false を返します.


Perform signing operation, return detached signature(s)

  • ≪ rnp_op_sign_cleartext
  • rnp_op_verify ≫
  • PHP Manual
  • Rnp 関数
  • Perform signing operation, return detached signature(s)

rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Perform signing operation, return detached signature(s)

説明

rnp_op_sign_detached(
RnpFFI $ffi,
string $data,
array $keys_fp,
array $options = ?
): string|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

data

Data to be signed.

keys_fp

Array with key fingerprints. At least one key must be provided. Keys should be present in ffi.

options

An associative array with options.

Key | Data type | 説明
"armor" | boolean | Enable ASCII-armored output. Disabled by default.
"hash" | string | Set hash algorithm used during signature calculation.
"creation_time" | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
"expiration_time" | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).

戻り値

Detached signature(s) data on success失敗した場合に false を返します.


Verify embedded or cleartext signatures

  • ≪ rnp_op_sign_detached
  • rnp_op_verify_detached ≫
  • PHP Manual
  • Rnp 関数
  • Verify embedded or cleartext signatures

rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Verify embedded or cleartext signatures

説明

rnp_op_verify(RnpFFI $ffi, string $data): array|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

data

Signed data.

戻り値

An associative array with information about verification results失敗した場合に false を返します.

Key | Data type | 説明
"verification_status" | string | Overall verification result, either "Success" string or appropriate error message. "Success" result is set when at least one signature is valid and successfully verified. Individual verification results for each signature can be checked in the "signatures" array.
"file_name" | string | File name.
"file_mtime" | integer | File modification time.
"mode" | string | Data protection (encryption) mode used in processed message. Currently defined values are "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
"cipher" | string | Symmetric cipher used for data encryption.
"valid_integrity" | boolean | true if message integrity protection was used (i.e. MDC or AEAD) and it was validated successfully.
"signatures" | array | An associative array describing each signature found. See description below.

"signatures" sub-array.

Key | Data type | 説明
"verification_status" | string | Signature verification status, either "Success" string or appropriate error message.
"creation_time" | integer | Signature creation time in seconds since Jan, 1 1970 UTC.
"expiration_time" | integer | Signature expiration time in seconds since the creation time or 0 if signature never expires.
"hash" | string | Hash function algorithm used to calculate the signature.
"signing_key" | string | Fingerprint of the key used for signing. Could be "Not found" if corresponding public key is not loaded to the FFI object.
"signature_type" | string | Signature type. Currently defined values are: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.


Verify detached signatures

  • ≪ rnp_op_verify
  • rnp_save_keys ≫
  • PHP Manual
  • Rnp 関数
  • Verify detached signatures

rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Verify detached signatures

説明

rnp_op_verify_detached(RnpFFI $ffi, string $data, string $signature): array|false

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

data

Source data.

signature

Detached signature data.

戻り値

An associative array with information about verification results失敗した場合に false を返します.

Key | Data type | 説明
"verification_status" | string | Overall verification result, either "Success" string or appropriate error message. "Success" result is set when at least one signature is valid and successfully verified. Individual verification results for each signature can be checked in the "signatures" array.
"file_name" | string | File name.
"file_mtime" | integer | File modification time.
"mode" | string | Data protection (encryption) mode used in processed message. Currently defined values are "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
"cipher" | string | Symmetric cipher used for data encryption.
"valid_integrity" | boolean | true if message integrity protection was used (i.e. MDC or AEAD) and it was validated successfully.
"signatures" | array | An associative array describing each signature found. See description below.

"signatures" sub-array.

Key | Data type | 説明
"verification_status" | string | Signature verification status, either "Success" string or appropriate error message.
"creation_time" | integer | Signature creation time in seconds since Jan, 1 1970 UTC.
"expiration_time" | integer | Signature expiration time in seconds since the creation time or 0 if signature never expires.
"hash" | string | Hash function algorithm used to calculate the signature.
"signing_key" | string | Fingerprint of the key used for signing. Could be "Not found" if corresponding public key is not loaded to the FFI object.
"signature_type" | string | Signature type. Currently defined values are: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.


Save keys to PHP string

  • ≪ rnp_op_verify_detached
  • rnp_save_keys_to_path ≫
  • PHP Manual
  • Rnp 関数
  • Save keys to PHP string

rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Save keys to PHP string

説明

rnp_save_keys(
RnpFFI $ffi,
string $format,
string &$output,
int $flags
): bool

Note that for G10, the output must be a directory (which must already exist).

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

format

The key format of the data (GPG, KBX, G10).

output

key packets will be saved to the string referenced by output.

flags

See RNP_LOAD_SAVE_* flags description.

戻り値

Returns true on success失敗した場合に false を返します.


Save keys to specified path

  • ≪ rnp_save_keys
  • rnp_supported_features ≫
  • PHP Manual
  • Rnp 関数
  • Save keys to specified path

rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Save keys to specified path

説明

rnp_save_keys_to_path(
RnpFFI $ffi,
string $format,
string $output_path,
int $flags
): bool

Saves keys present in the FFI object (loaded or generated) to the specified file or directory.

パラメータ

ffi

The FFI object returned by rnp_ffi_create.

format

The key format of the data (GPG, KBX, G10).

output_path

File or directory path where keys should be saved to.

flags

See RNP_LOAD_SAVE_* flags description.

戻り値

Returns true on success失敗した場合に false を返します.


Get supported features in JSON format

  • ≪ rnp_save_keys_to_path
  • rnp_version_string ≫
  • PHP Manual
  • Rnp 関数
  • Get supported features in JSON format

rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Get supported features in JSON format

説明

rnp_supported_features(string $type): string|false

Get the JSON formatted string containing array of supported rnp feature values (algorithms, curves, etc) by type.

パラメータ

type

See RNP_FEATURE_* constants for supported values.

戻り値

String containing JSON formatted array of supported algorithms, curves, etc失敗した場合に false を返します.


RNP library version

  • ≪ rnp_supported_features
  • rnp_version_string_full ≫
  • PHP Manual
  • Rnp 関数
  • RNP library version

rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — RNP library version

説明

rnp_version_string(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns RNP library version string.


Full version string of RNP library

  • ≪ rnp_version_string
  • RnpFFI ≫
  • PHP Manual
  • Rnp 関数
  • Full version string of RNP library

rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — Full version string of RNP library

説明

rnp_version_string_full(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns full version string of RNP library.


  • ≪ rnp_version_string_full
  • Sodium ≫
  • PHP Manual
  • Rnp
  • The RnpFFI class

The RnpFFI class

(PECL rnp >= 0.1.1)

はじめに

クラス概要

class RnpFFI {
}


Sodium

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • Sodium 関数
    • sodium_add — 巨大な数を加算する
    • sodium_base642bin — base64 エンコードされた文字列を、生バイナリにデコードする
    • sodium_bin2base64 — 生バイナリを base64 文字列にエンコードする
    • sodium_bin2hex — 16進数にエンコードする
    • sodium_compare — 巨大な数を比較する
    • sodium_crypto_aead_aes256gcm_decrypt — AES-256-GCM を用いてメッセージを検証し、復号する
    • sodium_crypto_aead_aes256gcm_encrypt — AES-256-GCM を使って暗号化し、認証を行う
    • sodium_crypto_aead_aes256gcm_is_available — ハードウェアが AES256-GCM をサポートしているかを確認する
    • sodium_crypto_aead_aes256gcm_keygen — ランダムな AES-256-GCM 暗号化キーを生成する
    • sodium_crypto_aead_chacha20poly1305_decrypt — ChaCha20-Poly1305 を用いてメッセージを検証し、復号する
    • sodium_crypto_aead_chacha20poly1305_encrypt — ChaCha20-Poly1305 を使って暗号化し、認証を行う
    • sodium_crypto_aead_chacha20poly1305_ietf_decrypt — 暗号化されたテキストが、有効なタグを持っているかを調べる
    • sodium_crypto_aead_chacha20poly1305_ietf_encrypt — メッセージを暗号化する
    • sodium_crypto_aead_chacha20poly1305_ietf_keygen — ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する
    • sodium_crypto_aead_chacha20poly1305_keygen — ランダムな ChaCha20-Poly1305 暗号化キーを生成する
    • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)
    • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)
    • sodium_crypto_aead_xchacha20poly1305_ietf_keygen — ランダムな XChaCha20-Poly1305 暗号化キーを生成する
    • sodium_crypto_auth — メッセージに対応するタグを計算する
    • sodium_crypto_auth_keygen — sodium_crypto_auth で使う、ランダムな鍵を生成する
    • sodium_crypto_auth_verify — メッセージのタグが有効かどうかを検証する
    • sodium_crypto_box — 認証付きの公開鍵による暗号化
    • sodium_crypto_box_keypair — 秘密鍵と、それに対応する公開鍵をランダムに生成する
    • sodium_crypto_box_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵から、鍵ペアを生成する
    • sodium_crypto_box_open — 認証付きの公開鍵による復号
    • sodium_crypto_box_publickey — crypto_box 鍵ペアから、公開鍵を取り出す
    • sodium_crypto_box_publickey_from_secretkey — 秘密鍵から公開鍵を計算する
    • sodium_crypto_box_seal — 匿名の公開鍵暗号による暗号化
    • sodium_crypto_box_seal_open — 匿名の公開鍵暗号による復号
    • sodium_crypto_box_secretkey — crypto_box 鍵ペアから、秘密鍵を取り出す
    • sodium_crypto_box_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる
    • sodium_crypto_core_ristretto255_add — 要素を追加する
    • sodium_crypto_core_ristretto255_from_hash — ベクトルをマップする
    • sodium_crypto_core_ristretto255_is_valid_point — 座標が ristretto255 曲線上にあるかを調べる
    • sodium_crypto_core_ristretto255_random — ランダムな鍵を生成する
    • sodium_crypto_core_ristretto255_scalar_add — スカラー値を追加する
    • sodium_crypto_core_ristretto255_scalar_complement — The sodium_crypto_core_ristretto255_scalar_complement purpose
    • sodium_crypto_core_ristretto255_scalar_invert — スカラー値を反転させる
    • sodium_crypto_core_ristretto255_scalar_mul — スカラー値を乗算する
    • sodium_crypto_core_ristretto255_scalar_negate — スカラー値の論理否定を行う
    • sodium_crypto_core_ristretto255_scalar_random — ランダムな鍵を生成する
    • sodium_crypto_core_ristretto255_scalar_reduce — スカラー値を縮小する
    • sodium_crypto_core_ristretto255_scalar_sub — スカラー値を減らす
    • sodium_crypto_core_ristretto255_sub — 要素の値を減らす
    • sodium_crypto_generichash — メッセージのハッシュ値を得る
    • sodium_crypto_generichash_final — ハッシュ値を計算する
    • sodium_crypto_generichash_init — ストリーミングのためにハッシュを初期化する
    • sodium_crypto_generichash_keygen — ランダムなハッシュキーを生成する
    • sodium_crypto_generichash_update — メッセージをハッシュに追加する
    • sodium_crypto_kdf_derive_from_key — サブキーを派生させる
    • sodium_crypto_kdf_keygen — KDF インターフェイスのために、ランダムなルートキーを生成する
    • sodium_crypto_kx_client_session_keys — クライアント側のセッションキーを計算する
    • sodium_crypto_kx_keypair — 新しい sodium の鍵ペアを生成する
    • sodium_crypto_kx_publickey — crypto_kx 鍵ペアから、公開鍵を取り出す
    • sodium_crypto_kx_secretkey — crypto_kx 鍵ペアから、秘密鍵を取り出す
    • sodium_crypto_kx_seed_keypair — Description
    • sodium_crypto_kx_server_session_keys — サーバー側のセッションキーを計算する
    • sodium_crypto_pwhash — Argon2 アルゴリズムを使い、パスワードからキーを導出する
    • sodium_crypto_pwhash_scryptsalsa208sha256 — scrypt を使い、パスワードからキーを導出する
    • sodium_crypto_pwhash_scryptsalsa208sha256_str — ASCII 文字列でエンコードされたハッシュを得る
    • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — パスワードが、有効なパスワード検証文字列かを調べる
    • sodium_crypto_pwhash_str — ASCII 文字でエンコードされたハッシュ値を得る
    • sodium_crypto_pwhash_str_needs_rehash — パスワードを再計算する必要があるかを判定する
    • sodium_crypto_pwhash_str_verify — パスワードが、ハッシュ値と一致するかを調べる
    • sodium_crypto_scalarmult — ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する
    • sodium_crypto_scalarmult_base — sodium_crypto_box_publickey_from_secretkey のエイリアス
    • sodium_crypto_scalarmult_ristretto255 — 共有シークレットを計算する
    • sodium_crypto_scalarmult_ristretto255_base — 秘密鍵から公開鍵を計算する
    • sodium_crypto_secretbox — 認証付きの共有鍵による暗号化
    • sodium_crypto_secretbox_keygen — sodium_crypto_secretbox で使うランダムな鍵を生成する
    • sodium_crypto_secretbox_open — 認証付きの共有鍵による復号
    • sodium_crypto_secretstream_xchacha20poly1305_init_pull — 復号のためのシークレットストリームのコンテキストを初期化する
    • sodium_crypto_secretstream_xchacha20poly1305_init_push — 暗号化のために、シークレットストリームのコンテキストを初期化する
    • sodium_crypto_secretstream_xchacha20poly1305_keygen — ランダムなシークレットストリームのキーを生成する
    • sodium_crypto_secretstream_xchacha20poly1305_pull — 暗号化されたストリームから、データのチャンクを複号する
    • sodium_crypto_secretstream_xchacha20poly1305_push — ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する
    • sodium_crypto_secretstream_xchacha20poly1305_rekey — シークレットストリームのステート中で、鍵を入れ替える
    • sodium_crypto_shorthash — メッセージと鍵のための短いハッシュ値を計算する
    • sodium_crypto_shorthash_keygen — 鍵のためのランダムなバイト値を得る
    • sodium_crypto_sign — メッセージに署名する
    • sodium_crypto_sign_detached — メッセージに署名する
    • sodium_crypto_sign_ed25519_pk_to_curve25519 — Ed25519 公開鍵を、Curve25519 公開鍵に変換する
    • sodium_crypto_sign_ed25519_sk_to_curve25519 — Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する
    • sodium_crypto_sign_keypair — 秘密鍵と、対応する公開鍵をランダムに生成する
    • sodium_crypto_sign_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵を結合する
    • sodium_crypto_sign_open — 署名済みのメッセージが、有効な署名を持っているかを調べる
    • sodium_crypto_sign_publickey — 鍵ペアから、Ed25519 形式の公開鍵を取り出す
    • sodium_crypto_sign_publickey_from_secretkey — 秘密鍵から、Ed25519 形式の公開鍵を取り出す
    • sodium_crypto_sign_secretkey — 鍵ペアから、Ed25519 形式の秘密鍵を取り出す
    • sodium_crypto_sign_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる
    • sodium_crypto_sign_verify_detached — メッセージの署名を検証する
    • sodium_crypto_stream — シードから、結果がひとつに定まるバイト列を生成する
    • sodium_crypto_stream_keygen — sodium_crypto_stream で用いる、ランダムな鍵を生成する
    • sodium_crypto_stream_xchacha20 — 秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する
    • sodium_crypto_stream_xchacha20_keygen — ランダムな暗号化キーを生成する
    • sodium_crypto_stream_xchacha20_xor — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)
    • sodium_crypto_stream_xchacha20_xor_ic — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)
    • sodium_crypto_stream_xor — 認証を行わずにメッセージを暗号化する
    • sodium_hex2bin — 16進エンコードされたバイナリ文字列をデコードする
    • sodium_increment — 巨大な数をインクリメントする
    • sodium_memcmp — 定数時間での文字列の比較
    • sodium_memzero — 文字列をNUL文字で上書きする
    • sodium_pad — パディングデータを追加する
    • sodium_unpad — パディングを削除する
  • SodiumException — SodiumException クラス


はじめに

Sodium は、 暗号化、復号化、署名、パスワードのハッシュ化その他の用途に使える、 モダンで使いやすいソフトウェアライブラリです。 より高レベルな暗号化ツールを作るための、 コアな操作を全て提供することを目標としています。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Sodium
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

この拡張モジュールには、» libsodium ? 1.0.8 が必要です。


インストール手順

PHP 7.2.0 以降、この拡張モジュールは PHP 本体にバンドルされています。 それより前の PHP のバージョンでは、 この拡張モジュールは PECL 経由で利用可能です。

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

この拡張モジュールを使うには、 configure オプション --with-sodium[=DIR] を使い、 sodium のサポートを有効にして PHP をコンパイルしなければいけません。

Windows

この拡張モジュールを使うには、 extension=php_sodium.dll を php.ini に追加しなければなりません。

PECL 経由でのインストール

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/libsodium


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SODIUM_LIBRARY_VERSION (string)
SODIUM_LIBRARY_MAJOR_VERSION (int)
SODIUM_LIBRARY_MINOR_VERSION (int)
SODIUM_BASE64_VARIANT_ORIGINAL (int)
SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING (int)
SODIUM_BASE64_VARIANT_URLSAFE (int)
SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING (int)
SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES (int)
SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES (int)
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES (int)
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES (int)
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES (int)
SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NSECBYTES (int)
SODIUM_CRYPTO_AUTH_BYTES (int)
SODIUM_CRYPTO_AUTH_KEYBYTES (int)
SODIUM_CRYPTO_BOX_SEALBYTES (int)
SODIUM_CRYPTO_BOX_SECRETKEYBYTES (int)
SODIUM_CRYPTO_BOX_PUBLICKEYBYTES (int)
SODIUM_CRYPTO_BOX_KEYPAIRBYTES (int)
SODIUM_CRYPTO_BOX_MACBYTES (int)
SODIUM_CRYPTO_BOX_NONCEBYTES (int)
SODIUM_CRYPTO_BOX_SEEDBYTES (int)
SODIUM_CRYPTO_KDF_BYTES_MIN (int)
SODIUM_CRYPTO_KDF_BYTES_MAX (int)
SODIUM_CRYPTO_KDF_CONTEXTBYTES (int)
SODIUM_CRYPTO_KDF_KEYBYTES (int)
SODIUM_CRYPTO_KX_SEEDBYTES (int)
SODIUM_CRYPTO_KX_SESSIONKEYBYTES (int)
SODIUM_CRYPTO_KX_PUBLICKEYBYTES (int)
SODIUM_CRYPTO_KX_SECRETKEYBYTES (int)
SODIUM_CRYPTO_KX_KEYPAIRBYTES (int)
SODIUM_CRYPTO_GENERICHASH_BYTES (int)
SODIUM_CRYPTO_GENERICHASH_BYTES_MIN (int)
SODIUM_CRYPTO_GENERICHASH_BYTES_MAX (int)
SODIUM_CRYPTO_GENERICHASH_KEYBYTES (int)
SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN (int)
SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX (int)
SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13 (int)
SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13 (int)
SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (int)
SODIUM_CRYPTO_PWHASH_SALTBYTES (int)
SODIUM_CRYPTO_PWHASH_STRPREFIX (string)
SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE (int)
SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE (int)
SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE (int)
SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE (int)
SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE (int)
SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE (int)
SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES (int)
SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX (string)
SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE (int)
SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE (int)
SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE (int)
SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE (int)
SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_SCALARMULT_BYTES (int)
SODIUM_CRYPTO_SCALARMULT_SCALARBYTES (int)
SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_SHORTHASH_BYTES (int)
SODIUM_CRYPTO_SHORTHASH_KEYBYTES (int)
SODIUM_CRYPTO_SECRETBOX_KEYBYTES (int)
SODIUM_CRYPTO_SECRETBOX_MACBYTES (int)
SODIUM_CRYPTO_SECRETBOX_NONCEBYTES (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_MESSAGEBYTES_MAX (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH (int)
SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY (int)
SODIUM_CRYPTO_SIGN_BYTES (int)
SODIUM_CRYPTO_SIGN_SEEDBYTES (int)
SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES (int)
SODIUM_CRYPTO_SIGN_SECRETKEYBYTES (int)
SODIUM_CRYPTO_SIGN_KEYPAIRBYTES (int)
SODIUM_CRYPTO_STREAM_NONCEBYTES (int)
SODIUM_CRYPTO_STREAM_KEYBYTES (int)
SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES (int)
PHP 8.1.0 以降で利用可能です。
SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES (int)
PHP 8.1.0 以降で利用可能です。


Sodium 関数

目次

  • sodium_add — 巨大な数を加算する
  • sodium_base642bin — base64 エンコードされた文字列を、生バイナリにデコードする
  • sodium_bin2base64 — 生バイナリを base64 文字列にエンコードする
  • sodium_bin2hex — 16進数にエンコードする
  • sodium_compare — 巨大な数を比較する
  • sodium_crypto_aead_aes256gcm_decrypt — AES-256-GCM を用いてメッセージを検証し、復号する
  • sodium_crypto_aead_aes256gcm_encrypt — AES-256-GCM を使って暗号化し、認証を行う
  • sodium_crypto_aead_aes256gcm_is_available — ハードウェアが AES256-GCM をサポートしているかを確認する
  • sodium_crypto_aead_aes256gcm_keygen — ランダムな AES-256-GCM 暗号化キーを生成する
  • sodium_crypto_aead_chacha20poly1305_decrypt — ChaCha20-Poly1305 を用いてメッセージを検証し、復号する
  • sodium_crypto_aead_chacha20poly1305_encrypt — ChaCha20-Poly1305 を使って暗号化し、認証を行う
  • sodium_crypto_aead_chacha20poly1305_ietf_decrypt — 暗号化されたテキストが、有効なタグを持っているかを調べる
  • sodium_crypto_aead_chacha20poly1305_ietf_encrypt — メッセージを暗号化する
  • sodium_crypto_aead_chacha20poly1305_ietf_keygen — ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する
  • sodium_crypto_aead_chacha20poly1305_keygen — ランダムな ChaCha20-Poly1305 暗号化キーを生成する
  • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)
  • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)
  • sodium_crypto_aead_xchacha20poly1305_ietf_keygen — ランダムな XChaCha20-Poly1305 暗号化キーを生成する
  • sodium_crypto_auth — メッセージに対応するタグを計算する
  • sodium_crypto_auth_keygen — sodium_crypto_auth で使う、ランダムな鍵を生成する
  • sodium_crypto_auth_verify — メッセージのタグが有効かどうかを検証する
  • sodium_crypto_box — 認証付きの公開鍵による暗号化
  • sodium_crypto_box_keypair — 秘密鍵と、それに対応する公開鍵をランダムに生成する
  • sodium_crypto_box_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵から、鍵ペアを生成する
  • sodium_crypto_box_open — 認証付きの公開鍵による復号
  • sodium_crypto_box_publickey — crypto_box 鍵ペアから、公開鍵を取り出す
  • sodium_crypto_box_publickey_from_secretkey — 秘密鍵から公開鍵を計算する
  • sodium_crypto_box_seal — 匿名の公開鍵暗号による暗号化
  • sodium_crypto_box_seal_open — 匿名の公開鍵暗号による復号
  • sodium_crypto_box_secretkey — crypto_box 鍵ペアから、秘密鍵を取り出す
  • sodium_crypto_box_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる
  • sodium_crypto_core_ristretto255_add — 要素を追加する
  • sodium_crypto_core_ristretto255_from_hash — ベクトルをマップする
  • sodium_crypto_core_ristretto255_is_valid_point — 座標が ristretto255 曲線上にあるかを調べる
  • sodium_crypto_core_ristretto255_random — ランダムな鍵を生成する
  • sodium_crypto_core_ristretto255_scalar_add — スカラー値を追加する
  • sodium_crypto_core_ristretto255_scalar_complement — The sodium_crypto_core_ristretto255_scalar_complement purpose
  • sodium_crypto_core_ristretto255_scalar_invert — スカラー値を反転させる
  • sodium_crypto_core_ristretto255_scalar_mul — スカラー値を乗算する
  • sodium_crypto_core_ristretto255_scalar_negate — スカラー値の論理否定を行う
  • sodium_crypto_core_ristretto255_scalar_random — ランダムな鍵を生成する
  • sodium_crypto_core_ristretto255_scalar_reduce — スカラー値を縮小する
  • sodium_crypto_core_ristretto255_scalar_sub — スカラー値を減らす
  • sodium_crypto_core_ristretto255_sub — 要素の値を減らす
  • sodium_crypto_generichash — メッセージのハッシュ値を得る
  • sodium_crypto_generichash_final — ハッシュ値を計算する
  • sodium_crypto_generichash_init — ストリーミングのためにハッシュを初期化する
  • sodium_crypto_generichash_keygen — ランダムなハッシュキーを生成する
  • sodium_crypto_generichash_update — メッセージをハッシュに追加する
  • sodium_crypto_kdf_derive_from_key — サブキーを派生させる
  • sodium_crypto_kdf_keygen — KDF インターフェイスのために、ランダムなルートキーを生成する
  • sodium_crypto_kx_client_session_keys — クライアント側のセッションキーを計算する
  • sodium_crypto_kx_keypair — 新しい sodium の鍵ペアを生成する
  • sodium_crypto_kx_publickey — crypto_kx 鍵ペアから、公開鍵を取り出す
  • sodium_crypto_kx_secretkey — crypto_kx 鍵ペアから、秘密鍵を取り出す
  • sodium_crypto_kx_seed_keypair — Description
  • sodium_crypto_kx_server_session_keys — サーバー側のセッションキーを計算する
  • sodium_crypto_pwhash — Argon2 アルゴリズムを使い、パスワードからキーを導出する
  • sodium_crypto_pwhash_scryptsalsa208sha256 — scrypt を使い、パスワードからキーを導出する
  • sodium_crypto_pwhash_scryptsalsa208sha256_str — ASCII 文字列でエンコードされたハッシュを得る
  • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — パスワードが、有効なパスワード検証文字列かを調べる
  • sodium_crypto_pwhash_str — ASCII 文字でエンコードされたハッシュ値を得る
  • sodium_crypto_pwhash_str_needs_rehash — パスワードを再計算する必要があるかを判定する
  • sodium_crypto_pwhash_str_verify — パスワードが、ハッシュ値と一致するかを調べる
  • sodium_crypto_scalarmult — ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する
  • sodium_crypto_scalarmult_base — sodium_crypto_box_publickey_from_secretkey のエイリアス
  • sodium_crypto_scalarmult_ristretto255 — 共有シークレットを計算する
  • sodium_crypto_scalarmult_ristretto255_base — 秘密鍵から公開鍵を計算する
  • sodium_crypto_secretbox — 認証付きの共有鍵による暗号化
  • sodium_crypto_secretbox_keygen — sodium_crypto_secretbox で使うランダムな鍵を生成する
  • sodium_crypto_secretbox_open — 認証付きの共有鍵による復号
  • sodium_crypto_secretstream_xchacha20poly1305_init_pull — 復号のためのシークレットストリームのコンテキストを初期化する
  • sodium_crypto_secretstream_xchacha20poly1305_init_push — 暗号化のために、シークレットストリームのコンテキストを初期化する
  • sodium_crypto_secretstream_xchacha20poly1305_keygen — ランダムなシークレットストリームのキーを生成する
  • sodium_crypto_secretstream_xchacha20poly1305_pull — 暗号化されたストリームから、データのチャンクを複号する
  • sodium_crypto_secretstream_xchacha20poly1305_push — ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する
  • sodium_crypto_secretstream_xchacha20poly1305_rekey — シークレットストリームのステート中で、鍵を入れ替える
  • sodium_crypto_shorthash — メッセージと鍵のための短いハッシュ値を計算する
  • sodium_crypto_shorthash_keygen — 鍵のためのランダムなバイト値を得る
  • sodium_crypto_sign — メッセージに署名する
  • sodium_crypto_sign_detached — メッセージに署名する
  • sodium_crypto_sign_ed25519_pk_to_curve25519 — Ed25519 公開鍵を、Curve25519 公開鍵に変換する
  • sodium_crypto_sign_ed25519_sk_to_curve25519 — Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する
  • sodium_crypto_sign_keypair — 秘密鍵と、対応する公開鍵をランダムに生成する
  • sodium_crypto_sign_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵を結合する
  • sodium_crypto_sign_open — 署名済みのメッセージが、有効な署名を持っているかを調べる
  • sodium_crypto_sign_publickey — 鍵ペアから、Ed25519 形式の公開鍵を取り出す
  • sodium_crypto_sign_publickey_from_secretkey — 秘密鍵から、Ed25519 形式の公開鍵を取り出す
  • sodium_crypto_sign_secretkey — 鍵ペアから、Ed25519 形式の秘密鍵を取り出す
  • sodium_crypto_sign_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる
  • sodium_crypto_sign_verify_detached — メッセージの署名を検証する
  • sodium_crypto_stream — シードから、結果がひとつに定まるバイト列を生成する
  • sodium_crypto_stream_keygen — sodium_crypto_stream で用いる、ランダムな鍵を生成する
  • sodium_crypto_stream_xchacha20 — 秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する
  • sodium_crypto_stream_xchacha20_keygen — ランダムな暗号化キーを生成する
  • sodium_crypto_stream_xchacha20_xor — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)
  • sodium_crypto_stream_xchacha20_xor_ic — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)
  • sodium_crypto_stream_xor — 認証を行わずにメッセージを暗号化する
  • sodium_hex2bin — 16進エンコードされたバイナリ文字列をデコードする
  • sodium_increment — 巨大な数をインクリメントする
  • sodium_memcmp — 定数時間での文字列の比較
  • sodium_memzero — 文字列をNUL文字で上書きする
  • sodium_pad — パディングデータを追加する
  • sodium_unpad — パディングを削除する


巨大な数を加算する

  • ≪ Sodium 関数
  • sodium_base642bin ≫
  • PHP Manual
  • Sodium 関数
  • 巨大な数を加算する

sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — 巨大な数を加算する

説明

sodium_add(string &$string1, string $string2): void

この関数は、 引数 string2 を string1 に加算し、 string1 の値を上書きします。 この関数は、両方の引数が、 符号なし整数をリトルエンディアンで表現した バイナリ文字列であると想定しています。

パラメータ

string1

符号なし整数をリトルエンディアンで表現した 任意の長さの文字列。 この引数はリファレンス渡しされ、 ふたつの引数の和を保持します。

string2

符号なし整数をリトルエンディアンで表現した 任意の長さの文字列。

戻り値

値を返しません。


base64 エンコードされた文字列を、生バイナリにデコードする

  • ≪ sodium_add
  • sodium_bin2base64 ≫
  • PHP Manual
  • Sodium 関数
  • base64 エンコードされた文字列を、生バイナリにデコードする

sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — base64 エンコードされた文字列を、生バイナリにデコードする

説明

sodium_base642bin(#[\SensitiveParameter] string $string, int $id, string $ignore = ""): string

base64 エンコードされた文字列を、 生バイナリにデコードします。 base64_decode() と異なり、 sodium_base642bin() は定数時間 (この性質は、プレーンテキストや鍵のような、 暗号に関する入力に触れるあらゆるコードで重要です) で実行でき、複数のエンコード方式をサポートしています。

パラメータ

string

エンコードされた文字列。

id

  • SODIUM_BASE64_VARIANT_ORIGINAL - 標準的な base64 文字列 (A-Za-z0-9/\+) の場合に指定します。
  • SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING - 標準的な base64 文字列 (A-Za-z0-9/\+) ですが、 = でパディングされていない場合に指定します。
  • SODIUM_BASE64_VARIANT_URLSAFE - URLに埋め込んでも安全な base64 エンコーディング (A-Za-z0-9\-_)
  • SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING - URLに埋め込んでも安全な base64 エンコーディング (A-Za-z0-9\-_) ですが、 = でパディングされていない場合に指定します。

ignore

デコードする際に無視する文字(e.g. 空白文字)

戻り値

デコードされた文字列を返します。


生バイナリを base64 文字列にエンコードする

  • ≪ sodium_base642bin
  • sodium_bin2hex ≫
  • PHP Manual
  • Sodium 関数
  • 生バイナリを base64 文字列にエンコードする

sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — 生バイナリを base64 文字列にエンコードする

説明

sodium_bin2base64(#[\SensitiveParameter] string $string, int $id): string

生のバイナリ文字列を base64 エンコードされた文字列に変換します。 base64_encode() と異なり、 sodium_bin2base64() は定数時間 (この性質は、プレーンテキストや鍵のような、 暗号に関する入力に触れるあらゆるコードで重要です) で実行でき、複数のエンコード方式をサポートしています。

パラメータ

string

生のバイナリ文字列

id

  • SODIUM_BASE64_VARIANT_ORIGINAL - 標準的な base64 文字列 (A-Za-z0-9/\+) の場合に指定します。
  • SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING - 標準的な base64 文字列 (A-Za-z0-9/\+) ですが、 = でパディングしない場合に指定します。
  • SODIUM_BASE64_VARIANT_URLSAFE - URLに埋め込んでも安全な base64 エンコーディング (A-Za-z0-9\-_)
  • SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING - URLに埋め込んでも安全な base64 エンコーディング (A-Za-z0-9\-_) ですが、 = でパディングしない場合に指定します。

戻り値

base64 エンコードされた文字列を返します。


16進数にエンコードする

  • ≪ sodium_bin2base64
  • sodium_compare ≫
  • PHP Manual
  • Sodium 関数
  • 16進数にエンコードする

sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — 16進数にエンコードする

説明

sodium_bin2hex(#[\SensitiveParameter] string $string): string

生バイナリ文字列を16進文字列にエンコードします。 標準の16進文字列にエンコードする関数と異なり、 sodium_bin2hex() は定数時間 (この性質は、プレーンテキストや鍵のような、 暗号に関する入力に触れるあらゆるコードで重要です) で実行できます。

パラメータ

string

生のバイナリ文字列。

戻り値

16進数にエンコードされた文字列を返します。


巨大な数を比較する

  • ≪ sodium_bin2hex
  • sodium_crypto_aead_aes256gcm_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • 巨大な数を比較する

sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — 巨大な数を比較する

説明

sodium_compare(#[\SensitiveParameter] string $string1, #[\SensitiveParameter] string $string2): int

任意の長さの、 符号なし整数をリトルエンディアンで表現したバイナリ文字列として、 ふたつの文字列を比較します。 サイドチャネル攻撃によるリークはありません。

パラメータ

string1

左オペランド

string2

右オペランド

戻り値

string1 が string2 より小さい場合は -1 を返します。

string1 が string2 より大きい場合は 1 を返します。

ふたつの文字列が等しい場合 0 を返します。


AES-256-GCM を用いてメッセージを検証し、復号する

  • ≪ sodium_compare
  • sodium_crypto_aead_aes256gcm_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • AES-256-GCM を用いてメッセージを検証し、復号する

sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — AES-256-GCM を用いてメッセージを検証し、復号する

説明

sodium_crypto_aead_aes256gcm_decrypt(
string $ciphertext,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string|false

AES-256-GCM を用いてメッセージを検証し、復号します。 sodium_crypto_aead_aes256gcm_is_available() が true を返す場合にのみ利用可能です。

パラメータ

ciphertext

sodium_crypto_aead_aes256gcm_encrypt() が生成したフォーマット (暗号化されたテキスト、タグを連結したもの) でなければなりません。

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。

nonce

メッセージごとに一度だけ使われる数値。 長さは12バイトです。

key

暗号化キー(256ビット)

戻り値

成功時にプレーンテキストを返します。 失敗した場合に false を返します


AES-256-GCM を使って暗号化し、認証を行う

  • ≪ sodium_crypto_aead_aes256gcm_decrypt
  • sodium_crypto_aead_aes256gcm_is_available ≫
  • PHP Manual
  • Sodium 関数
  • AES-256-GCM を使って暗号化し、認証を行う

sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — AES-256-GCM を使って暗号化し、認証を行う

説明

sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter] string $message,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string

AES-256-GCM を使って暗号化し、認証を行います。 sodium_crypto_aead_aes256gcm_is_available() が true を返した場合にだけ利用可能です。

パラメータ

message

暗号化するプレーンテキスト

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されません。

nonce

メッセージごとに一度だけ使われる数値。 長さは12バイトです。

key

暗号化キー(256ビット)

戻り値

暗号化されたテキストと、 認証タグを生のバイナリのバイト列に含めた文字列を返します。 (フォーマット: 暗号化済みテキストの後に、タグが続きます)


ハードウェアが AES256-GCM をサポートしているかを確認する

  • ≪ sodium_crypto_aead_aes256gcm_encrypt
  • sodium_crypto_aead_aes256gcm_keygen ≫
  • PHP Manual
  • Sodium 関数
  • ハードウェアが AES256-GCM をサポートしているかを確認する

sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — ハードウェアが AES256-GCM をサポートしているかを確認する

説明

sodium_crypto_aead_aes256gcm_is_available(): bool

この関数の戻り値は、 ハードウェアが AES256-GCM をサポートしているかどうかに依存します。

パラメータ

この関数にはパラメータはありません。

戻り値

AES-256-GCM を使って暗号化しても安全な場合、true を返します。 そうでない場合、false を返します。


ランダムな AES-256-GCM 暗号化キーを生成する

  • ≪ sodium_crypto_aead_aes256gcm_is_available
  • sodium_crypto_aead_chacha20poly1305_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな AES-256-GCM 暗号化キーを生成する

sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — ランダムな AES-256-GCM 暗号化キーを生成する

説明

sodium_crypto_aead_aes256gcm_keygen(): string

sodium_crypto_aead_aes256gcm_encrypt() や sodium_crypto_aead_aes256gcm_decrypt() で使うランダムな鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

256ビット長のランダムな暗号化キーを返します。


ChaCha20-Poly1305 を用いてメッセージを検証し、復号する

  • ≪ sodium_crypto_aead_aes256gcm_keygen
  • sodium_crypto_aead_chacha20poly1305_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • ChaCha20-Poly1305 を用いてメッセージを検証し、復号する

sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — ChaCha20-Poly1305 を用いてメッセージを検証し、復号する

説明

sodium_crypto_aead_chacha20poly1305_decrypt(
string $ciphertext,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string|false

ChaCha20-Poly1305 を用いてメッセージを検証し、復号します。

パラメータ

ciphertext

sodium_crypto_aead_chacha20poly1305_encrypt() が生成したフォーマット (暗号化されたテキスト、タグを連結したもの) でなければなりません。

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。

nonce

メッセージごとに一度だけ使われる数値。 長さは8バイトです。

key

暗号化キー(256ビット)

戻り値

成功時にプレーンテキストを返します。 失敗した場合に false を返します


ChaCha20-Poly1305 を使って暗号化し、認証を行う

  • ≪ sodium_crypto_aead_chacha20poly1305_decrypt
  • sodium_crypto_aead_chacha20poly1305_ietf_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • ChaCha20-Poly1305 を使って暗号化し、認証を行う

sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — ChaCha20-Poly1305 を使って暗号化し、認証を行う

説明

sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter] string $message,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string

ChaCha20-Poly1305 を使って暗号化し、認証を行います。

パラメータ

message

暗号化するプレーンテキスト

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されません。

nonce

メッセージごとに一度だけ使われる数値。 長さは8バイトです。

key

暗号化キー(256ビット)

戻り値

成功時には、暗号化されたテキストと、 認証タグを返します。 失敗した場合に false を返します.


暗号化されたテキストが、有効なタグを持っているかを調べる

  • ≪ sodium_crypto_aead_chacha20poly1305_encrypt
  • sodium_crypto_aead_chacha20poly1305_ietf_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • 暗号化されたテキストが、有効なタグを持っているかを調べる

sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — 暗号化されたテキストが、有効なタグを持っているかを調べる

説明

sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string $ciphertext,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string|false

ChaCha20-Poly1305 を用いてメッセージを検証し、復号します。 (IETF バリアントです)

IETF バリアントは、96ビットの nonce と 32ビットの内部カウンタを持ちます。 標準では、nonce, 内部カウンタともに64ビットです。

パラメータ

ciphertext

sodium_crypto_aead_chacha20poly1305_ietf_encrypt() が生成したフォーマット (暗号化されたテキスト、タグを連結したもの) でなければなりません。

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。

nonce

メッセージごとに一度だけ使われる数値。 長さは12バイトです。

key

暗号化キー(256ビット)

戻り値

成功時にプレーンテキストを返します。 失敗した場合に false を返します


メッセージを暗号化する

  • ≪ sodium_crypto_aead_chacha20poly1305_ietf_decrypt
  • sodium_crypto_aead_chacha20poly1305_ietf_keygen ≫
  • PHP Manual
  • Sodium 関数
  • メッセージを暗号化する

sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — メッセージを暗号化する

説明

sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter] string $message,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string

ChaCha20-Poly1305 を使って暗号化し、認証を行います。 (IETF バリアントです)

IETF バリアントは、96ビットの nonce と 32ビットの内部カウンタを持ちます。 標準では、nonce, 内部カウンタともに64ビットです。

パラメータ

message

暗号化するプレーンテキスト

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されません。

nonce

メッセージごとに一度だけ使われる数値。 長さは12バイトです。

key

暗号化キー(256ビット)

戻り値

成功時には、 暗号化されたテキストと認証タグを返します。 失敗した場合に false を返します.


ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する

  • ≪ sodium_crypto_aead_chacha20poly1305_ietf_encrypt
  • sodium_crypto_aead_chacha20poly1305_keygen ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する

sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する

説明

sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

sodium_crypto_aead_chacha20poly1305_ietf_encrypt() や sodium_crypto_aead_chacha20poly1305_ietf_decrypt() で使うランダムな鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

256ビット長のランダムな暗号化キーを返します。


ランダムな ChaCha20-Poly1305 暗号化キーを生成する

  • ≪ sodium_crypto_aead_chacha20poly1305_ietf_keygen
  • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな ChaCha20-Poly1305 暗号化キーを生成する

sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — ランダムな ChaCha20-Poly1305 暗号化キーを生成する

説明

sodium_crypto_aead_chacha20poly1305_keygen(): string

sodium_crypto_aead_chacha20poly1305_encrypt() や sodium_crypto_aead_chacha20poly1305_decrypt() で使うランダムな鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

256ビット長のランダムな暗号化キーを返します。


XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)

  • ≪ sodium_crypto_aead_chacha20poly1305_keygen
  • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt ≫
  • PHP Manual
  • Sodium 関数
  • XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)

説明

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string $ciphertext,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string|false

ChaCha20-Poly1305 (eXtended-nonce バリアント) を用いてメッセージを検証し、復号します。

一般的には、提供されている AEADモードの中で、 XChaCha20-Poly1305 を使うのがもっとも好ましいです。

パラメータ

ciphertext

sodium_crypto_aead_chacha20poly1305_ietf_encrypt() が生成したフォーマット (暗号化されたテキスト、タグを連結したもの) でなければなりません。

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key

暗号化キー(256ビット)

戻り値

成功時にプレーンテキストを返します。 失敗した場合に false を返します


XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)

  • ≪ sodium_crypto_aead_xchacha20poly1305_ietf_decrypt
  • sodium_crypto_aead_xchacha20poly1305_ietf_keygen ≫
  • PHP Manual
  • Sodium 関数
  • XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)

説明

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter] string $message,
string $additional_data,
string $nonce,
#[\SensitiveParameter] string $key
): string

XChaCha20-Poly1305 (eXtended-nonce バリアント) を使って暗号化し、認証を行います。

一般的には、提供されている AEADモードの中で、 XChaCha20-Poly1305 を使うのがもっとも好ましいです。

パラメータ

message

暗号化するプレーンテキスト

additional_data

追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されません。

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key

暗号化キー(256ビット)

戻り値

成功時に、暗号化されたテキストとタグを返します。 失敗した場合に false を返します.


ランダムな XChaCha20-Poly1305 暗号化キーを生成する

  • ≪ sodium_crypto_aead_xchacha20poly1305_ietf_encrypt
  • sodium_crypto_auth ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな XChaCha20-Poly1305 暗号化キーを生成する

sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — ランダムな XChaCha20-Poly1305 暗号化キーを生成する

説明

sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() や sodium_crypto_aead_xchacha20poly1305_ietf_decrypt() で使うランダムな鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

256ビット長のランダムな暗号化キーを返します。


メッセージに対応するタグを計算する

  • ≪ sodium_crypto_aead_xchacha20poly1305_ietf_keygen
  • sodium_crypto_auth_keygen ≫
  • PHP Manual
  • Sodium 関数
  • メッセージに対応するタグを計算する

sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — メッセージに対応するタグを計算する

説明

sodium_crypto_auth(string $message, #[\SensitiveParameter] string $key): string

対称鍵によるメッセージ認証を行います。 sodium_crypto_auth() は完全性は提供しますが、機密性は提供しません。

(sodium_crypto_sign_detached() のような) 電子署名と異なり、 メッセージを検証する側は、 自分たちのメッセージを認証することもできます。 (つまり、対称鍵による認証です)

パラメータ

message

認証したいメッセージ

key

認証鍵

戻り値

認証タグを返します。


sodium_crypto_auth で使う、ランダムな鍵を生成する

  • ≪ sodium_crypto_auth
  • sodium_crypto_auth_verify ≫
  • PHP Manual
  • Sodium 関数
  • sodium_crypto_auth で使う、ランダムな鍵を生成する

sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — sodium_crypto_auth で使う、ランダムな鍵を生成する

説明

sodium_crypto_auth_keygen(): string

sodium_crypto_auth() や sodium_crypto_auth_verify() で使う鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

256ビット長のランダムな暗号化キーを返します。


メッセージのタグが有効かどうかを検証する

  • ≪ sodium_crypto_auth_keygen
  • sodium_crypto_box ≫
  • PHP Manual
  • Sodium 関数
  • メッセージのタグが有効かどうかを検証する

sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — メッセージのタグが有効かどうかを検証する

説明

sodium_crypto_auth_verify(string $mac, string $message, #[\SensitiveParameter] string $key): bool

指定されたメッセージと鍵に対応した認証タグが有効かどうかを検証します。

(sodium_crypto_sign_verify_detached() のような) 電子署名と異なり、 メッセージを検証する側は、 自分たちのメッセージを認証することもできます。 (つまり、対称鍵による認証です)

パラメータ

mac

sodium_crypto_auth() によって生成された認証タグ

message

メッセージ

key

認証鍵

戻り値

成功した場合に true を、失敗した場合に false を返します。


認証付きの公開鍵による暗号化

  • ≪ sodium_crypto_auth_verify
  • sodium_crypto_box_keypair ≫
  • PHP Manual
  • Sodium 関数
  • 認証付きの公開鍵による暗号化

sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — 認証付きの公開鍵による暗号化

説明

sodium_crypto_box(#[\SensitiveParameter] string $message, string $nonce, #[\SensitiveParameter] string $key_pair): string

非対称(公開鍵)暗号を使ってメッセージを暗号化します。

sodium_crypto_box() というプレフィックスが付いた関数が使うアルゴリズムは、 Elliptic Curve Diffie-Hellman over the Montgomery curve, Curve25519; 略して X25519 です。

パラメータ

message

暗号化するメッセージ

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key_pair

sodium_crypto_box_keypair_from_secretkey_and_publickey() を参照ください。 この鍵ペアには、 送信者の X25519 形式の秘密鍵と、 受信者の X25519 形式の公開鍵が含まれているべきです。

戻り値

暗号化されたメッセージ(暗号化済みのテキストと、認証タグ)を返します。 暗号化済みのテキストは、 生のバイナリ文字列の分だけ、 プレーンテキストより16バイト長くなっています。 安全なエンコード方法については、 sodium_bin2base64() を参照ください。


秘密鍵と、それに対応する公開鍵をランダムに生成する

  • ≪ sodium_crypto_box
  • sodium_crypto_box_keypair_from_secretkey_and_publickey ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵と、それに対応する公開鍵をランダムに生成する

sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — 秘密鍵と、それに対応する公開鍵をランダムに生成する

説明

sodium_crypto_box_keypair(): string

秘密鍵と公開鍵を、ひとつの文字列として生成します。

この関数で生成する鍵ペアの文字列から秘密鍵を取り出すには、 sodium_crypto_box_secretkey() を参照ください。 この関数で生成する鍵ペアの文字列から公開鍵を取り出すには、 sodium_crypto_box_publickey() を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

X25519 形式の秘密鍵と、 それに対応する公開鍵を両方含んだ文字列を返します。


秘密鍵と公開鍵から、鍵ペアを生成する

  • ≪ sodium_crypto_box_keypair
  • sodium_crypto_box_open ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵と公開鍵から、鍵ペアを生成する

sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵から、鍵ペアを生成する

説明

sodium_crypto_box_keypair_from_secretkey_and_publickey(#[\SensitiveParameter] string $secret_key, string $public_key): string

この関数は、 crypto_box() のような、 API の要件を満たすために存在しています。 一方の側の秘密鍵と、もう一方の側の公開鍵を渡すと、 会話に必要な "鍵ペア" が得られます。

パラメータ

secret_key

秘密鍵

public_key

公開鍵

戻り値

X25519 形式のキーペアを返します。


認証付きの公開鍵による復号

  • ≪ sodium_crypto_box_keypair_from_secretkey_and_publickey
  • sodium_crypto_box_publickey ≫
  • PHP Manual
  • Sodium 関数
  • 認証付きの公開鍵による復号

sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — 認証付きの公開鍵による復号

説明

sodium_crypto_box_open(string $ciphertext, string $nonce, #[\SensitiveParameter] string $key_pair): string|false

非対称(公開鍵)暗号を使って、メッセージを復号します。

パラメータ

ciphertext

復号を試みる、暗号化されたメッセージ

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key_pair

sodium_crypto_box_keypair_from_secretkey_and_publickey() を参照ください。 この鍵ペアには、送信者の公開鍵と、 受信側の秘密鍵が含まれているはずです。

戻り値

成功した場合、プレーンテキストメッセージを返します。 失敗した場合に false を返します.


crypto_box 鍵ペアから、公開鍵を取り出す

  • ≪ sodium_crypto_box_open
  • sodium_crypto_box_publickey_from_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • crypto_box 鍵ペアから、公開鍵を取り出す

sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — crypto_box 鍵ペアから、公開鍵を取り出す

説明

sodium_crypto_box_publickey(#[\SensitiveParameter] string $key_pair): string

鍵ペアを指定し、そこから公開鍵のみを取り出します。

パラメータ

key_pair

sodium_crypto_box_keypair() や sodium_crypto_box_seed_keypair() から生成した鍵ペア

戻り値

X25519 形式の公開鍵を返します。


秘密鍵から公開鍵を計算する

  • ≪ sodium_crypto_box_publickey
  • sodium_crypto_box_seal ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵から公開鍵を計算する

sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — 秘密鍵から公開鍵を計算する

説明

sodium_crypto_box_publickey_from_secretkey(#[\SensitiveParameter] string $secret_key): string

秘密鍵を指定すると、それに対する公開鍵を計算します。

この関数は、crypto_box() 関数で使われるタイプの鍵 (Elliptic Curve Diffie-Hellman over the Montgomery curve, Curve25519; 略して X25519) でのみ動作します。 crypto_sign() 関数で使われるタイプの鍵 (Edwards Digital Signature Algorithm over the Edwards Curve; 略して Ed25519) では動作しません。

パラメータ

secret_key

X25519 形式の秘密鍵

戻り値

X25519 形式の公開鍵を返します。


匿名の公開鍵暗号による暗号化

  • ≪ sodium_crypto_box_publickey_from_secretkey
  • sodium_crypto_box_seal_open ≫
  • PHP Manual
  • Sodium 関数
  • 匿名の公開鍵暗号による暗号化

sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — 匿名の公開鍵暗号による暗号化

説明

sodium_crypto_box_seal(#[\SensitiveParameter] string $message, string $public_key): string

受信側のみが復号できるやり方で、 メッセージを暗号化します。

sodium_crypto_box() と異なり、 sodium_crypto_box_seal() に必要なのは、 受信側の公開鍵だけです。 その結果として、暗号化されたメッセージは静的な公開鍵と結びつきません。 そのため、認証が必要になります。 それゆえに、匿名の公開鍵暗号と呼ばれています。

sodium_crypto_box_seal() 関数は暗号化メッセージの完全性を提供しています。 送信側の完全性の認証だけではありません。

送信側を認証したい場合、 sodium_crypto_sign() 関数が入門として最適です。

パラメータ

message

暗号化するメッセージ

public_key

メッセージを復号できる鍵に対応する、公開鍵

戻り値

暗号化された文字列。 一度限りの公開鍵、 暗号化されたメッセージ、 認証タグ というフォーマットで成ります。

例

例1 sodium_crypto_box_seal() の例

<?php
$keypair = sodium_crypto_box_keypair();
$public_key = sodium_crypto_box_publickey($keypair);

// Obfuscated plaintext to make the example more fun
$plaintext_b64 = "V3JpdGluZyBzb2Z0d2FyZSBpbiBQSFAgY2FuIGJlIGEgZGVsaWdodCE=";
$decoded_plaintext = sodium_base642bin($plaintext_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

$sealed = sodium_crypto_box_seal($decoded_plaintext, $public_key);
var_dump(base64_encode($sealed));

$opened = sodium_crypto_box_seal_open($sealed, $keypair);
var_dump($opened);
?>

上の例の出力は、 たとえば以下のようになります。

string(120) "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw="
string(41) "Writing software in PHP can be a delight!"


匿名の公開鍵暗号による復号

  • ≪ sodium_crypto_box_seal
  • sodium_crypto_box_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • 匿名の公開鍵暗号による復号

sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — 匿名の公開鍵暗号による復号

説明

sodium_crypto_box_seal_open(string $ciphertext, #[\SensitiveParameter] string $key_pair): string|false

sodium_crypto_box_seal() を使って暗号化されたメッセージを復号します。

パラメータ

ciphertext

暗号化されたメッセージ

key_pair

受信側の鍵ペア。 秘密鍵が含まれている必要があります。

戻り値

成功時にはプレーンテキストを返します。 失敗した場合に false を返します.

例

例1 sodium_crypto_box_seal_open() の例

<?php
// Ciphertext is not sensitive; base64_decode is fine
$sealed_b64 = "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw=";
$sealed = base64_decode($sealed_b64);

// Keypair contains a cryptographic secret; use a timing-safe decoder
$keypair_b64 = "KZkF8wnB7bnC2aXB3lFOqCTc0Z6MllvaQb9ASVG8o2/MsewkuE4u1uaEgTzSakeiYyIW8DGj+02/L3cWIbs9bQ==";
$keypair = sodium_base642bin($keypair_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

$opened = sodium_crypto_box_seal_open($sealed, $keypair);
var_dump($opened);
?>

上の例の出力は、 たとえば以下のようになります。

string(41) "Writing software in PHP can be a delight!"


crypto_box 鍵ペアから、秘密鍵を取り出す

  • ≪ sodium_crypto_box_seal_open
  • sodium_crypto_box_seed_keypair ≫
  • PHP Manual
  • Sodium 関数
  • crypto_box 鍵ペアから、秘密鍵を取り出す

sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — crypto_box 鍵ペアから、秘密鍵を取り出す

説明

sodium_crypto_box_secretkey(#[\SensitiveParameter] string $key_pair): string

鍵ペアを指定し、秘密鍵だけを取り出します。

パラメータ

key_pair

sodium_crypto_box_keypair() や sodium_crypto_box_seed_keypair() によって生成された鍵ペア

戻り値

X25519 形式の秘密鍵を返します。


単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

  • ≪ sodium_crypto_box_secretkey
  • sodium_crypto_core_ristretto255_add ≫
  • PHP Manual
  • Sodium 関数
  • 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

説明

sodium_crypto_box_seed_keypair(#[\SensitiveParameter] string $seed): string

秘密鍵を生成するためのシードを介して、 公開鍵を派生させ、秘密鍵と公開鍵のふたつを鍵ペアとして返します。

*_seed_keypair 関数はパスワードとソルトから鍵ペアを生成することと同じです。 seed としての結果を、 鍵を生成するために使います。

パラメータ

seed

暗号の処理をした入力。 長さは32バイトでなければなりません。

戻り値

X25519 形式のキーペア(秘密鍵と公開鍵)を返します。


要素を追加する

  • ≪ sodium_crypto_box_seed_keypair
  • sodium_crypto_core_ristretto255_from_hash ≫
  • PHP Manual
  • Sodium 関数
  • 要素を追加する

sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — 要素を追加する

説明

sodium_crypto_core_ristretto255_add(string $p, string $q): string

要素 q を p に追加します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

p

追加される要素。

q

追加する要素。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_add() の例

<?php

$foo = sodium_crypto_core_ristretto255_random();
$bar = sodium_crypto_core_ristretto255_random();

$value = sodium_crypto_core_ristretto255_add($foo, $bar);
$value = sodium_crypto_core_ristretto255_sub($value, $bar);

var_dump(hash_equals($foo, $value));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_random() - ランダムな鍵を生成する
  • sodium_crypto_core_ristretto255_sub() - 要素の値を減らす


ベクトルをマップする

  • ≪ sodium_crypto_core_ristretto255_add
  • sodium_crypto_core_ristretto255_is_valid_point ≫
  • PHP Manual
  • Sodium 関数
  • ベクトルをマップする

sodium_crypto_core_ristretto255_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — ベクトルをマップする

説明

sodium_crypto_core_ristretto255_from_hash(string $s): string

64バイト長のベクトル s をグループの要素にマップします。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

64バイト長のベクトル。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_from_hash() の例

<?php

$hashes = sodium_hex2bin(
'5d1be09e3d0c82fc538112490e35701979d99e06ca3e2b5b54bffe8b4dc772c1' .
'4d98b696a1bbfb5ca32c436cc61c16563790306c79eaca7705668b47dffe5bb6'
);
var_dump(sodium_bin2hex(sodium_crypto_core_ristretto255_from_hash($hashes)));
?>

上の例の出力は以下となります。

string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

参考

  • sodium_hex2bin() - 16進エンコードされたバイナリ文字列をデコードする
  • sodium_bin2hex() - 16進数にエンコードする
  • sodium_crypto_core_ristretto255_from_hash()


座標が ristretto255 曲線上にあるかを調べる

  • ≪ sodium_crypto_core_ristretto255_from_hash
  • sodium_crypto_core_ristretto255_random ≫
  • PHP Manual
  • Sodium 関数
  • 座標が ristretto255 曲線上にあるかを調べる

sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — 座標が ristretto255 曲線上にあるかを調べる

説明

sodium_crypto_core_ristretto255_is_valid_point(string $s): bool

ristretto255 曲線上に座標があるかを判定します。 in canonical form, on the main subgroup, and that the point doesn't have a small order. libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

楕円曲線の座標

戻り値

s が ristretto255 曲線上にある場合に true を返します。 そうでない場合、false を返します。

例

例1 sodium_crypto_core_ristretto255_is_valid_point() の例

<?php

$foo = sodium_crypto_core_ristretto255_scalar_random();
$bar = sodium_crypto_scalarmult_ristretto255_base($foo);

var_dump(sodium_crypto_core_ristretto255_is_valid_point($bar));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する
  • sodium_crypto_scalarmult_ristretto255_base() - 秘密鍵から公開鍵を計算する


ランダムな鍵を生成する

  • ≪ sodium_crypto_core_ristretto255_is_valid_point
  • sodium_crypto_core_ristretto255_scalar_add ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな鍵を生成する

sodium_crypto_core_ristretto255_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — ランダムな鍵を生成する

説明

sodium_crypto_core_ristretto255_random(): string

ランダムな鍵を生成します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_random() の例

<?php

$foo = sodium_crypto_core_ristretto255_random();
$bar = sodium_crypto_core_ristretto255_random();

$value = sodium_crypto_core_ristretto255_add($foo, $bar);
$value = sodium_crypto_core_ristretto255_sub($value, $bar);

var_dump(hash_equals($foo, $value));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_add() - 要素を追加する
  • sodium_crypto_core_ristretto255_sub() - 要素の値を減らす


スカラー値を追加する

  • ≪ sodium_crypto_core_ristretto255_random
  • sodium_crypto_core_ristretto255_scalar_complement ≫
  • PHP Manual
  • Sodium 関数
  • スカラー値を追加する

sodium_crypto_core_ristretto255_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — スカラー値を追加する

説明

sodium_crypto_core_ristretto255_scalar_add(string $x, string $y): string

要素 y を x に追加します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

x

スカラー値。 X座標を表します。

y

スカラー値。 Y座標を表します。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_scalar_add() の例

<?php

$foo = sodium_crypto_core_ristretto255_scalar_random();
$bar = sodium_crypto_core_ristretto255_scalar_random();

$value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
$value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

var_dump(hash_equals($foo, $value));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する
  • sodium_crypto_core_ristretto255_scalar_sub() - スカラー値を減らす


The sodium_crypto_core_ristretto255_scalar_complement purpose

  • ≪ sodium_crypto_core_ristretto255_scalar_add
  • sodium_crypto_core_ristretto255_scalar_invert ≫
  • PHP Manual
  • Sodium 関数
  • The sodium_crypto_core_ristretto255_scalar_complement purpose

sodium_crypto_core_ristretto255_scalar_complement

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_complement — The sodium_crypto_core_ristretto255_scalar_complement purpose

説明

sodium_crypto_core_ristretto255_scalar_complement(string $s): string

libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

スカラー値。

戻り値

32バイト長のランダムな文字列を返します。

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する


スカラー値を反転させる

  • ≪ sodium_crypto_core_ristretto255_scalar_complement
  • sodium_crypto_core_ristretto255_scalar_mul ≫
  • PHP Manual
  • Sodium 関数
  • スカラー値を反転させる

sodium_crypto_core_ristretto255_scalar_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — スカラー値を反転させる

説明

sodium_crypto_core_ristretto255_scalar_invert(string $s): string

スカラー値を反転させます。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

スカラー値。

戻り値

32バイトのランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_scalar_invert()の例

<?php

$foo = sodium_crypto_core_ristretto255_scalar_random();

$inverted = sodium_crypto_core_ristretto255_scalar_invert($foo);
$reInverted = sodium_crypto_core_ristretto255_scalar_invert($inverted);

var_dump(hash_equals($foo, $reInverted));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する


スカラー値を乗算する

  • ≪ sodium_crypto_core_ristretto255_scalar_invert
  • sodium_crypto_core_ristretto255_scalar_negate ≫
  • PHP Manual
  • Sodium 関数
  • スカラー値を乗算する

sodium_crypto_core_ristretto255_scalar_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — スカラー値を乗算する

説明

sodium_crypto_core_ristretto255_scalar_mul(string $x, string $y): string

スカラー値を乗算します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

x

スカラー値。 X座標を表します。

y

スカラー値。 Y座標を表します。

戻り値

32バイト長のランダムな文字列を返します。

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する


スカラー値の論理否定を行う

  • ≪ sodium_crypto_core_ristretto255_scalar_mul
  • sodium_crypto_core_ristretto255_scalar_random ≫
  • PHP Manual
  • Sodium 関数
  • スカラー値の論理否定を行う

sodium_crypto_core_ristretto255_scalar_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — スカラー値の論理否定を行う

説明

sodium_crypto_core_ristretto255_scalar_negate(string $s): string

スカラー値の論理否定演算を行います。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

スカラー値。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_scalar_negate() の例

<?php

$foo = sodium_crypto_core_ristretto255_scalar_random();

$negate = sodium_crypto_core_ristretto255_scalar_negate($foo);
$reNegate = sodium_crypto_core_ristretto255_scalar_negate($negate);

var_dump(hash_equals($foo, $reNegate));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する


ランダムな鍵を生成する

  • ≪ sodium_crypto_core_ristretto255_scalar_negate
  • sodium_crypto_core_ristretto255_scalar_reduce ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな鍵を生成する

sodium_crypto_core_ristretto255_scalar_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — ランダムな鍵を生成する

説明

sodium_crypto_core_ristretto255_scalar_random(): string

ランダムな鍵を生成します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_scalar_random() の例

<?php

$foo = sodium_crypto_core_ristretto255_scalar_random();
$bar = sodium_crypto_core_ristretto255_scalar_random();

$value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
$value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

var_dump(hash_equals($foo, $value));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_scalar_add() - スカラー値を追加する
  • sodium_crypto_core_ristretto255_scalar_sub() - スカラー値を減らす


スカラー値を縮小する

  • ≪ sodium_crypto_core_ristretto255_scalar_random
  • sodium_crypto_core_ristretto255_scalar_sub ≫
  • PHP Manual
  • Sodium 関数
  • スカラー値を縮小する

sodium_crypto_core_ristretto255_scalar_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — スカラー値を縮小する

説明

sodium_crypto_core_ristretto255_scalar_reduce(string $s): string

スカラー値を縮小します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

スカラー値

戻り値

32バイト長のランダムな文字列を返します。

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する


スカラー値を減らす

  • ≪ sodium_crypto_core_ristretto255_scalar_reduce
  • sodium_crypto_core_ristretto255_sub ≫
  • PHP Manual
  • Sodium 関数
  • スカラー値を減らす

sodium_crypto_core_ristretto255_scalar_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — スカラー値を減らす

説明

sodium_crypto_core_ristretto255_scalar_sub(string $x, string $y): string

x から スカラー値 y を減らします。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

x

スカラー値。 X座標を表します。

y

スカラー値。 Y座標を表します。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_scalar_sub() の例

<?php

$foo = sodium_crypto_core_ristretto255_scalar_random();
$bar = sodium_crypto_core_ristretto255_scalar_random();

$value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
$value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

var_dump(hash_equals($foo, $value));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_scalar_random() - ランダムな鍵を生成する
  • sodium_crypto_core_ristretto255_scalar_add() - スカラー値を追加する


要素の値を減らす

  • ≪ sodium_crypto_core_ristretto255_scalar_sub
  • sodium_crypto_generichash ≫
  • PHP Manual
  • Sodium 関数
  • 要素の値を減らす

sodium_crypto_core_ristretto255_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — 要素の値を減らす

説明

sodium_crypto_core_ristretto255_sub(string $p, string $q): string

p から 要素 q を減らします。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

p

減らされる要素。

q

減らす要素。

戻り値

32バイト長のランダムな文字列を返します。

例

例1 sodium_crypto_core_ristretto255_sub() の例

<?php

$foo = sodium_crypto_core_ristretto255_random();
$bar = sodium_crypto_core_ristretto255_random();

$value = sodium_crypto_core_ristretto255_add($foo, $bar);
$value = sodium_crypto_core_ristretto255_sub($value, $bar);

var_dump(hash_equals($foo, $value));
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_crypto_core_ristretto255_random() - ランダムな鍵を生成する
  • sodium_crypto_core_ristretto255_add() - 要素を追加する


メッセージのハッシュ値を得る

  • ≪ sodium_crypto_core_ristretto255_sub
  • sodium_crypto_generichash_final ≫
  • PHP Manual
  • Sodium 関数
  • メッセージのハッシュ値を得る

sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — メッセージのハッシュ値を得る

説明

sodium_crypto_generichash(string $message, #[\SensitiveParameter] string $key = "", int $length = SODIUM_CRYPTO_GENERICHASH_BYTES): string

BLAKE2b を使い、メッセージをハッシュ化します。

パラメータ

message

ハッシュ化するメッセージ

key

(オプション)暗号キー。 この値は、HMACキーと同じ役割を果たしますが、 内部的な BLAKE2 のステートの予約されたセクションに統合されています。

length

出力の長さ

戻り値

ハッシュ値を生のバイトとして返します。 16進エンコードしたい場合、 この関数の結果を sodium_bin2hex() に渡すことができます。


ハッシュ値を計算する

  • ≪ sodium_crypto_generichash
  • sodium_crypto_generichash_init ≫
  • PHP Manual
  • Sodium 関数
  • ハッシュ値を計算する

sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — ハッシュ値を計算する

説明

sodium_crypto_generichash_final(string &$state, int $length = SODIUM_CRYPTO_GENERICHASH_BYTES): string

ストリーミングハッシュAPI の処理を完了させるメソッドです。

パラメータ

state

sodium_crypto_generichash_init() から返されたハッシュステート。

length

出力の長さ

戻り値

ハッシュ値を返します。

例

例1 sodium_crypto_generichash_final() の例

<?php
$messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
$state = sodium_crypto_generichash_init('', 32);
foreach ($messages as $message) {
sodium_crypto_generichash_update($state, $message);
}

$final = sodium_crypto_generichash_final($state, 32);
var_dump(sodium_bin2hex($final));

$allAtOnce = sodium_crypto_generichash(implode('', $messages));
var_dump(sodium_bin2hex($allAtOnce));
?>

上の例の出力は、 たとえば以下のようになります。

string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"


ストリーミングのためにハッシュを初期化する

  • ≪ sodium_crypto_generichash_final
  • sodium_crypto_generichash_keygen ≫
  • PHP Manual
  • Sodium 関数
  • ストリーミングのためにハッシュを初期化する

sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — ストリーミングのためにハッシュを初期化する

説明

sodium_crypto_generichash_init(#[\SensitiveParameter] string $key = "", int $length = SODIUM_CRYPTO_GENERICHASH_BYTES): string

ストリーミングハッシュAPI の初期化メソッドです。

パラメータ

key

ハッシュキー

length

ハッシュ関数に期待する出力の長さ

戻り値

生のバイナリ文字列としてシリアライズされた、 ハッシュステートを返します。

例

例1 sodium_crypto_generichash_init() の例

<?php
$messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
$state = sodium_crypto_generichash_init('', 32);
foreach ($messages as $message) {
sodium_crypto_generichash_update($state, $message);
}
$final = sodium_crypto_generichash_final($state, 32);
var_dump(sodium_bin2hex($final));
$allAtOnce = sodium_crypto_generichash(implode('', $messages));
var_dump(sodium_bin2hex($allAtOnce));
?>

上の例の出力は、 たとえば以下のようになります。

string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"


ランダムなハッシュキーを生成する

  • ≪ sodium_crypto_generichash_init
  • sodium_crypto_generichash_update ≫
  • PHP Manual
  • Sodium 関数
  • ランダムなハッシュキーを生成する

sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — ランダムなハッシュキーを生成する

説明

sodium_crypto_generichash_keygen(): string

ハッシュAPIで使うランダムなキーを生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

ランダムな 256ビット長のキーを返します。


メッセージをハッシュに追加する

  • ≪ sodium_crypto_generichash_keygen
  • sodium_crypto_kdf_derive_from_key ≫
  • PHP Manual
  • Sodium 関数
  • メッセージをハッシュに追加する

sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — メッセージをハッシュに追加する

説明

sodium_crypto_generichash_update(string &$state, string $message): true

内部的なハッシュステートにメッセージを追加します。

パラメータ

state

sodium_crypto_generichash_init(). の戻り値

message

ハッシュステートに追加するデータ

戻り値

常に true を返します。

例

例1 sodium_crypto_generichash_update() の例

<?php
$messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
$state = sodium_crypto_generichash_init();
foreach ($messages as $message) {
sodium_crypto_generichash_update($state, $message);
}
$final = sodium_crypto_generichash_final($state);
var_dump(sodium_bin2hex($final));

$allAtOnce = sodium_crypto_generichash(implode('', $messages));
var_dump(sodium_bin2hex($allAtOnce));
?>

上の例の出力は、 たとえば以下のようになります。

string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"
string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"


サブキーを派生させる

  • ≪ sodium_crypto_generichash_update
  • sodium_crypto_kdf_keygen ≫
  • PHP Manual
  • Sodium 関数
  • サブキーを派生させる

sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — サブキーを派生させる

説明

sodium_crypto_kdf_derive_from_key(
int $subkey_length,
int $subkey_id,
string $context,
#[\SensitiveParameter] string $key
): string

ルートキーと追加のコンテクストから、サブキーを派生させます。

hash_hkdf() に似ています。

パラメータ

subkey_length

返すキーの長さ(バイト単位)

subkey_id

与えられたルートキーから返されるN番目のサブキーのID。 シークさせる時に便利です。

context

アプリケーション特有のコンテクスト

key

サブキーを派生させるルートキー

戻り値

擬似ランダムな(生のバイナリの)バイト列を文字列として返します。


KDF インターフェイスのために、ランダムなルートキーを生成する

  • ≪ sodium_crypto_kdf_derive_from_key
  • sodium_crypto_kx_client_session_keys ≫
  • PHP Manual
  • Sodium 関数
  • KDF インターフェイスのために、ランダムなルートキーを生成する

sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — KDF インターフェイスのために、ランダムなルートキーを生成する

説明

sodium_crypto_kdf_keygen(): string

sodium_crypto_kdf_derive_from_key() で使うルートキーに適合する、ランダムなキーを生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

ランダムな256ビット長のキーを返します。


クライアント側のセッションキーを計算する

  • ≪ sodium_crypto_kdf_keygen
  • sodium_crypto_kx_keypair ≫
  • PHP Manual
  • Sodium 関数
  • クライアント側のセッションキーを計算する

sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — クライアント側のセッションキーを計算する

説明

sodium_crypto_kx_client_session_keys(#[\SensitiveParameter] string $client_key_pair, string $server_key): array

X25519 + BLAKE2b 鍵交換メソッドを使い、 クライアント側のセッションキーを計算します。

パラメータ

client_key_pair

sodium_crypto_kx_keypair() で生成した、crypto_kx の鍵ペア。

server_key

crypto_kx の公開鍵

戻り値

ふたつの文字列からなる配列。 最初の文字列は、サーバーから受け取るデータとして使います。 ふたつめの文字列は、サーバーに送信するデータとして使います。


新しい sodium の鍵ペアを生成する

  • ≪ sodium_crypto_kx_client_session_keys
  • sodium_crypto_kx_publickey ≫
  • PHP Manual
  • Sodium 関数
  • 新しい sodium の鍵ペアを生成する

sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — 新しい sodium の鍵ペアを生成する

説明

sodium_crypto_kx_keypair(): string

秘密鍵(32バイト)の後に、 公開鍵(32バイト)が続く、 sodium の鍵ペアを生成します。 これらの鍵は、それぞれ sodium_crypto_kx_secretkey() と sodium_crypto_kx_publickey() を呼び出すことで取得できます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時に、新しい鍵ペアを返します。 失敗した場合、例外をスローします。

例

例1 sodium_crypto_kx_keypair() の使い方

新しい鍵ペアを生成し、 公開鍵と秘密鍵を取得します。

<?php
$keypair = sodium_crypto_kx_keypair();
$secret = sodium_crypto_kx_secretkey($keypair);
$public = sodium_crypto_kx_publickey($keypair);
printf("secret: %s\npublic: %s", sodium_bin2hex($secret), sodium_bin2hex($public));
?>

上の例の出力は、 たとえば以下のようになります。

secret: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
public: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18


crypto_kx 鍵ペアから、公開鍵を取り出す

  • ≪ sodium_crypto_kx_keypair
  • sodium_crypto_kx_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • crypto_kx 鍵ペアから、公開鍵を取り出す

sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — crypto_kx 鍵ペアから、公開鍵を取り出す

説明

sodium_crypto_kx_publickey(#[\SensitiveParameter] string $key_pair): string

crypto_kx の鍵ペアから、公開鍵を取り出します。

パラメータ

key_pair

X25519 形式の鍵ペア。 たとえば、sodium_crypto_kx_keypair() から生成されたものです。

戻り値

X25519 形式の公開鍵を返します。


crypto_kx 鍵ペアから、秘密鍵を取り出す

  • ≪ sodium_crypto_kx_publickey
  • sodium_crypto_kx_seed_keypair ≫
  • PHP Manual
  • Sodium 関数
  • crypto_kx 鍵ペアから、秘密鍵を取り出す

sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — crypto_kx 鍵ペアから、秘密鍵を取り出す

説明

sodium_crypto_kx_secretkey(#[\SensitiveParameter] string $key_pair): string

crypto_kx 鍵ペアから、秘密鍵を取り出します。

パラメータ

key_pair

X25519 形式の鍵ペア。 たとえば、 sodium_crypto_kx_keypair() から生成されたものです。

戻り値

X25519 形式の秘密鍵を返します。


Description

  • ≪ sodium_crypto_kx_secretkey
  • sodium_crypto_kx_server_session_keys ≫
  • PHP Manual
  • Sodium 関数
  • Description

sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Description

説明

sodium_crypto_kx_seed_keypair(#[\SensitiveParameter] string $seed): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

戻り値


サーバー側のセッションキーを計算する

  • ≪ sodium_crypto_kx_seed_keypair
  • sodium_crypto_pwhash ≫
  • PHP Manual
  • Sodium 関数
  • サーバー側のセッションキーを計算する

sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — サーバー側のセッションキーを計算する

説明

sodium_crypto_kx_server_session_keys(#[\SensitiveParameter] string $server_key_pair, string $client_key): array

X25519 + BLAKE2b 鍵交換メソッドを使い、 サーバー側のセッションキーを計算します。

パラメータ

server_key_pair

crypto_kx 鍵ペア。 sodium_crypto_kx_keypair() で生成されたものです。

client_key

crypto_kx の公開鍵

戻り値

ふたつの文字列からなる配列を返します。 ひとつめはクライアントから受信する文字列として使います。 ふたつめはクライアントに送信するデータとして使います。


Argon2 アルゴリズムを使い、パスワードからキーを導出する

  • ≪ sodium_crypto_kx_server_session_keys
  • sodium_crypto_pwhash_scryptsalsa208sha256 ≫
  • PHP Manual
  • Sodium 関数
  • Argon2 アルゴリズムを使い、パスワードからキーを導出する

sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Argon2 アルゴリズムを使い、パスワードからキーを導出する

説明

sodium_crypto_pwhash(
int $length,
#[\SensitiveParameter] string $password,
string $salt,
int $opslimit,
int $memlimit,
int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
): string

この関数は、 libsodium の crypto_pwhash 派生関数への低レベルのアクセスを提供します。 この関数を使う明確な理由がなければ、 sodium_crypto_pwhash_str() や password_hash() 関数を代わりに使うべきです。

この関数を使う共通の理由は、 パスワードとソルトから暗号化キーのためのシードを導出し、 その値を使うことで、特定の目的 (たとえば、sodium_crypto_sign_detached()) で使う実際の鍵を生成することです。

パラメータ

length

生成するパスワードハッシュの長さ。 バイト単位で指定します。

password

ハッシュを生成するパスワードを文字列で指定します。

salt

ハッシュ化する前に、 パスワードに追加するソルト値。 この値は予測されてはいけません。 random_bytes() のような良質な乱数のソースから生成されることが理想です。 そして、長さが正確に SODIUM_CRYPTO_PWHASH_SALTBYTES バイトである必要があります。

opslimit

実際に行う計算処理の最大量。 この値を大きくすると、 キーを計算するのに必要なCPUサイクルが増加します。 意図した使い方次第で、 適切な値の上限値を設定するために、いくつかの定数が存在します。 弱いものから強いものへと並べると、以下のとおりです: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE

memlimit

この関数が使用するメモリの最大値をバイト単位で指定します。 適切な値を選ぶために、ヘルパとなる定数が存在します。 サイズの順に、以下の通りです: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE これらの値は、opslimit と一致するものとペアになるべきです。

algo

使用するハッシュアルゴリズムのIDを指定します。 デフォルトは、 SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (現状推奨されるアルゴリズム。 これは、libsodium のバージョンによって変更されるかもしれません) です。 または、 Argon2id アルゴリズム version 1.3 を表す SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13 を明示的に使うこともできます。

戻り値

導出されたキーを返します。 返される値は、ハッシュのバイナリ文字列であり、 ASCII でエンコードされた文字列ではありませんし、 ハッシュを生成するために使われた追加のパラメータも含まれていません。 よって、将来パスワードを検証するためには、 それらの情報を保持しておく必要があります。 そうなることを避けるために、 sodium_crypto_pwhash_str() を使って下さい。

例

例1 sodium_crypto_pwhash() の例

<?php
//Need to keep the salt if we're ever going to be able to check this password
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
//Using bin2hex to keep output readable
echo bin2hex(
sodium_crypto_pwhash(
16, // == 128 bits
'password',
$salt,
SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
)
);
?>

上の例の出力は、 たとえば以下のようになります。

a18f346ba57992eb7e4ae6abf3fd30ee


scrypt を使い、パスワードからキーを導出する

  • ≪ sodium_crypto_pwhash
  • sodium_crypto_pwhash_scryptsalsa208sha256_str ≫
  • PHP Manual
  • Sodium 関数
  • scrypt を使い、パスワードからキーを導出する

sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — scrypt を使い、パスワードからキーを導出する

説明

sodium_crypto_pwhash_scryptsalsa208sha256(
int $length,
#[\SensitiveParameter] string $password,
string $salt,
int $opslimit,
int $memlimit
): string

sodium_crypto_pwhash() の scrypt 対応版です。

この特別な関数を使う理由は、 パスワードとソルトから、暗号化キーのシードを導出し、 そのシードを特定の目的に必要とされる実際のキー (たとえば sodium_crypto_sign_detached() で使う) を生成することです。

パラメータ

length

生成するパスワードハッシュの長さ。 バイト単位で指定します。

password

ハッシュを生成するパスワード

salt

ハッシュ化する前に、 パスワードに追加するソルト値。 この値は予測されてはいけません。 random_bytes() のような良質な乱数のソースから生成されることが理想です。 そして、少なくとも長さが SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES バイトである必要があります。

opslimit

実際に行う計算処理の最大量。 この値を大きくすると、 キーを計算するのに必要なCPUサイクルが増加します。 意図した使い方次第で、 適切な値の上限値を設定するために、いくつかの定数が存在します。 弱いものから強いものへと並べると、以下のとおりです: SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE と SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE です。

memlimit

この関数が使用するメモリの最大値をバイト単位で指定します。 適切な値を選ぶために、ヘルパとなる定数が存在します。 サイズの順に、以下の通りです: SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE と SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE があります。 これらの値は、opslimit と一致するものとペアになるべきです。

戻り値

指定された長さのバイト列を文字列として返します。


ASCII 文字列でエンコードされたハッシュを得る

  • ≪ sodium_crypto_pwhash_scryptsalsa208sha256
  • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify ≫
  • PHP Manual
  • Sodium 関数
  • ASCII 文字列でエンコードされたハッシュを得る

sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — ASCII 文字列でエンコードされたハッシュを得る

説明

sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter] string $password, int $opslimit, int $memlimit): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

password

opslimit

memlimit

戻り値


パスワードが、有効なパスワード検証文字列かを調べる

  • ≪ sodium_crypto_pwhash_scryptsalsa208sha256_str
  • sodium_crypto_pwhash_str ≫
  • PHP Manual
  • Sodium 関数
  • パスワードが、有効なパスワード検証文字列かを調べる

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — パスワードが、有効なパスワード検証文字列かを調べる

説明

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string $hash, #[\SensitiveParameter] string $password): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

hash

password

戻り値


ASCII 文字でエンコードされたハッシュ値を得る

  • ≪ sodium_crypto_pwhash_scryptsalsa208sha256_str_verify
  • sodium_crypto_pwhash_str_needs_rehash ≫
  • PHP Manual
  • Sodium 関数
  • ASCII 文字でエンコードされたハッシュ値を得る

sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — ASCII 文字でエンコードされたハッシュ値を得る

説明

sodium_crypto_pwhash_str(#[\SensitiveParameter] string $password, int $opslimit, int $memlimit): string

ランダムに生成されたソルト値と、 CPU とメモリへの攻撃に強いハッシュアルゴリズムを使い、 指定されたメモリとCPUの使用量の最大値に基づき、 パスワードの保存に適した ASCII 文字でエンコードされたハッシュを生成します。

パラメータ

password

ハッシュを生成するパスワードを文字列で指定します。

opslimit

実際に行う計算処理の最大量。 この値を大きくすると、 キーを計算するのに必要なCPUサイクルが増加します。 意図した使い方次第で、 適切な値の上限値を設定するために、いくつかの定数が存在します。 弱いものから強いものへと並べると、以下のとおりです: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE です。

memlimit

この関数が使用するメモリの最大値をバイト単位で指定します。 適切な値を選ぶために、ヘルパとなる定数が存在します。 サイズの順に、以下の通りです: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE があります。 これらの値は、opslimit と一致するものとペアになるべきです。

戻り値

ハッシュ化されたパスワードを返します。

同じパスワードから同じパスワードハッシュを生成するには、 opslimit と memlimit の値を同じにしなければいけません。 これらは生成されたハッシュに埋め込まれているので、 ハッシュを検証する際に必要な全てが含まれています。 これによって、 sodium_crypto_pwhash_str_verify() 関数が、他の引数に関する情報を追加で保存せずにハッシュを検証できるのです。

例

例1 sodium_crypto_pwhash_str() の例

<?php
$password = 'password';
echo sodium_crypto_pwhash_str(
$password,
SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

上の例の出力は、 たとえば以下のようになります。

$argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

注意

注意:

ハッシュ値は Argon2ID アルゴリズムを使って計算されます。 このアルゴリズムは、GPU に対する攻撃と サイドチャネル攻撃の両方に対する耐性を提供します。 password_hash() と異なり、 salt の引数は存在せず(自動生成されます)、 opslimit と memlimit の値が必須になっています。

参考

  • sodium_crypto_pwhash_str_verify() - パスワードが、ハッシュ値と一致するかを調べる
  • sodium_crypto_pwhash() - Argon2 アルゴリズムを使い、パスワードからキーを導出する
  • password_hash() - パスワードハッシュを作る
  • password_verify() - パスワードがハッシュにマッチするかどうかを調べる
  • » Libsodium Argon2 docs


パスワードを再計算する必要があるかを判定する

  • ≪ sodium_crypto_pwhash_str
  • sodium_crypto_pwhash_str_verify ≫
  • PHP Manual
  • Sodium 関数
  • パスワードを再計算する必要があるかを判定する

sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — パスワードを再計算する必要があるかを判定する

説明

sodium_crypto_pwhash_str_needs_rehash(string $password, int $opslimit, int $memlimit): bool

現在の opslimit 値と memlimit 値から、 パスワードを再計算する必要があるかを判定します。

パラメータ

password

パスワードハッシュ

opslimit

設定済みの opslimit。 sodium_crypto_pwhash_str() を参照ください。

memlimit

設定済みの memlimit。 sodium_crypto_pwhash_str() を参照ください。

戻り値

設定された memlimit/opslimit が、 保存されたハッシュ値にマッチしない場合、true を返します。 マッチする場合、false を返します。


パスワードが、ハッシュ値と一致するかを調べる

  • ≪ sodium_crypto_pwhash_str_needs_rehash
  • sodium_crypto_scalarmult ≫
  • PHP Manual
  • Sodium 関数
  • パスワードが、ハッシュ値と一致するかを調べる

sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — パスワードが、ハッシュ値と一致するかを調べる

説明

sodium_crypto_pwhash_str_verify(string $hash, #[\SensitiveParameter] string $password): bool

sodium_crypto_pwhash_str() を使って生成されたパスワードハッシュが、 指定されたプレーンテキストのパスワードとマッチするかを調べます。 この関数と似た password_verify() に指定する同じ引数と、順番が逆であることに注意して下さい。

パラメータ

hash

password_hash() が作ったハッシュ。

password

ユーザーのパスワード。

戻り値

パスワードとハッシュ値がマッチする場合 true を返します。 そうでない場合、false を返します。

注意

注意:

ハッシュ値は Argon2ID アルゴリズムを使って計算されます。 このアルゴリズムは、GPU に対する攻撃と サイドチャネル攻撃の両方に対する耐性を提供します。

参考

  • sodium_crypto_pwhash_str() - ASCII 文字でエンコードされたハッシュ値を得る
  • password_hash() - パスワードハッシュを作る
  • password_verify() - パスワードがハッシュにマッチするかどうかを調べる


ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する

  • ≪ sodium_crypto_pwhash_str_verify
  • sodium_crypto_scalarmult_base ≫
  • PHP Manual
  • Sodium 関数
  • ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する

sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する

説明

sodium_crypto_scalarmult(string $n, string $p): string

ディフィー・ヘルマン楕円曲線上で座標pをn回掛け算します。

パラメータ

n

スカラー値。 これは通常は秘密鍵です。

p

座標 (X軸上)。 これは通常は公開鍵です。

戻り値

32バイト長のランダムな文字列を返します。


sodium_crypto_box_publickey_from_secretkey のエイリアス

  • ≪ sodium_crypto_scalarmult
  • sodium_crypto_scalarmult_ristretto255 ≫
  • PHP Manual
  • Sodium 関数
  • sodium_crypto_box_publickey_from_secretkey のエイリアス

sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — sodium_crypto_box_publickey_from_secretkey() のエイリアス

説明

この関数は次の関数のエイリアスです。 sodium_crypto_box_publickey_from_secretkey().


共有シークレットを計算する

  • ≪ sodium_crypto_scalarmult_base
  • sodium_crypto_scalarmult_ristretto255_base ≫
  • PHP Manual
  • Sodium 関数
  • 共有シークレットを計算する

sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — 共有シークレットを計算する

説明

sodium_crypto_scalarmult_ristretto255(string $n, string $p): string

座標 p の n 倍にあたるスカラー値を計算します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

n

スカラー値。 通常は秘密鍵の値です。

p

座標の値(x座標)。 通常は公開鍵の値です。

戻り値

32バイト長のランダムな文字列を返します。

参考

  • sodium_crypto_scalarmult_ristretto255_base() - 秘密鍵から公開鍵を計算する


秘密鍵から公開鍵を計算する

  • ≪ sodium_crypto_scalarmult_ristretto255
  • sodium_crypto_secretbox ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵から公開鍵を計算する

sodium_crypto_scalarmult_ristretto255_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — 秘密鍵から公開鍵を計算する

説明

sodium_crypto_scalarmult_ristretto255_base(string $n): string

秘密鍵を指定すると、それに対応する公開鍵を計算します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

n

秘密鍵。

戻り値

32バイト長のランダムな文字列を返します。

参考

  • sodium_crypto_scalarmult_ristretto255() - 共有シークレットを計算する


認証付きの共有鍵による暗号化

  • ≪ sodium_crypto_scalarmult_ristretto255_base
  • sodium_crypto_secretbox_keygen ≫
  • PHP Manual
  • Sodium 関数
  • 認証付きの共有鍵による暗号化

sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — 認証付きの共有鍵による暗号化

説明

sodium_crypto_secretbox(#[\SensitiveParameter] string $message, string $nonce, #[\SensitiveParameter] string $key): string

対称(共有)鍵を使い、メッセージを暗号化します。

パラメータ

message

暗号化するプレーンテキスト

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key

暗号化キー(256ビット)

戻り値

暗号化された文字列を返します。

エラー / 例外

  • nonce の長さが SODIUM_CRYPTO_SECRETBOX_NONCEBYTES (24 バイト) と異なっている場合、 SodiumException がスローされます。
  • key の長さが、 SODIUM_CRYPTO_SECRETBOX_KEYBYTES (32 バイト) と異なっている場合、 SodiumException がスローされます。
  • 失敗時には、SodiumException がスローされます。

例

例1 sodium_crypto_secretbox() の例

<?php
// The $key must be kept confidential
$key = sodium_crypto_secretbox_keygen();
// Do not reuse $nonce with the same key
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$plaintext = "message to be encrypted";
$ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

var_dump(bin2hex($ciphertext));
// The same nonce and key are required to decrypt the $ciphertext
var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key));
?>

上の例の出力は、 たとえば以下のようになります。

string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
string(23) "message to be encrypted"

参考

  • sodium_crypto_secretbox_open() - 認証付きの共有鍵による復号
  • sodium_crypto_secretbox_keygen() - sodium_crypto_secretbox で使うランダムな鍵を生成する
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


sodium_crypto_secretbox で使うランダムな鍵を生成する

  • ≪ sodium_crypto_secretbox
  • sodium_crypto_secretbox_open ≫
  • PHP Manual
  • Sodium 関数
  • sodium_crypto_secretbox で使うランダムな鍵を生成する

sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — sodium_crypto_secretbox で使うランダムな鍵を生成する

説明

sodium_crypto_secretbox_keygen(): string

sodium_crypto_secretbox() と sodium_crypto_secretbox_open() で使うための鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

暗号学的にセキュアな、ランダムなバイト列を生成し、文字列で返します。

例

例1 sodium_crypto_secretbox_keygen() の例

<?php
$key = sodium_crypto_secretbox_keygen();
var_dump( sodium_bin2hex( $key ) );
?>

上の例の出力は、 たとえば以下のようになります。

string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

例2 sodium_crypto_secretbox_keygen() と random_bytes() の比較

<?php
$key = sodium_crypto_secretbox_keygen();
$bytes = random_bytes( SODIUM_CRYPTO_SECRETBOX_KEYBYTES );
var_dump( mb_strlen( $key, '8bit' ) === mb_strlen( $bytes, '8bit' ) );
?>

上の例の出力は以下となります。

bool(true)

参考

  • sodium_bin2hex() - 16進数にエンコードする
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


認証付きの共有鍵による復号

  • ≪ sodium_crypto_secretbox_keygen
  • sodium_crypto_secretstream_xchacha20poly1305_init_pull ≫
  • PHP Manual
  • Sodium 関数
  • 認証付きの共有鍵による復号

sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — 認証付きの共有鍵による復号

説明

sodium_crypto_secretbox_open(string $ciphertext, string $nonce, #[\SensitiveParameter] string $key): string|false

対称(共有)鍵を使い、暗号化されたメッセージを復号します。

パラメータ

ciphertext

sodium_crypto_secretbox() が生成したフォーマットでなければいけません。 (暗号化されたテキスト、タグを連結したもの)

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key

暗号化キー(256ビット)

戻り値

成功時には、復号した文字列を返します。 失敗した場合に false を返します.

エラー / 例外

  • nonce の長さが SODIUM_CRYPTO_SECRETBOX_NONCEBYTES (24 バイト) と異なっている場合、 SodiumException がスローされます。
  • key の長さが、 SODIUM_CRYPTO_SECRETBOX_KEYBYTES (32 バイト) と異なっている場合、 SodiumException がスローされます。

例

例1 sodium_crypto_secretbox_open() の例

<?php
// The $key must be kept confidential
$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
// Do not reuse $nonce with the same key
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$ciphertext = sodium_crypto_secretbox('message to be encrypted', $nonce, $key);

// The same nonce and key are required to decrypt the $ciphertext
$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
if ($plaintext !== false) {
echo $plaintext . PHP_EOL;
}
?>

上の例の出力は以下となります。

message to be encrypted

参考

  • sodium_crypto_secretbox() - 認証付きの共有鍵による暗号化
  • sodium_crypto_secretbox_keygen() - sodium_crypto_secretbox で使うランダムな鍵を生成する
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


復号のためのシークレットストリームのコンテキストを初期化する

  • ≪ sodium_crypto_secretbox_open
  • sodium_crypto_secretstream_xchacha20poly1305_init_push ≫
  • PHP Manual
  • Sodium 関数
  • 復号のためのシークレットストリームのコンテキストを初期化する

sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — 復号のためのシークレットストリームのコンテキストを初期化する

説明

sodium_crypto_secretstream_xchacha20poly1305_init_pull(string $header, #[\SensitiveParameter] string $key): string

復号のためのシークレットストリームのコンテキストを初期化します。

パラメータ

header

シークレットストリームのヘッダ。 これは、 sodium_crypto_secretstream_xchacha20poly1305_init_push() が生成する値のうちの一つを指定しなければいけません。

key

暗号化キー(256ビット)

戻り値

シークレットストリームのステートを返します。

例

例1 sodium_crypto_secretstream_xchacha20poly1305_init_pull() の例

<?php
function decrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
{
$inputFile = fopen($inputFilePath, 'rb');
$outputFile = fopen($outputFilePath, 'wb');
$header = fread($inputFile, 24);

$state = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
$inputFileSize = fstat($inputFile)['size'];

// Decrypt the file and write its contents to the output file:
for ($i = 24; $i < $inputFileSize; $i += 8192) {
$ctxt_chunk = fread($inputFile, 8192);

// We're not using $tag, but in real protocols you can use this on encrypt to e.g.
// trigger a re-key or indicate the end of file. Then, on decrypt, you can assert
// this behavior.
[$ptxt_chunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($state, $ctxt_chunk);
fwrite($outputFile, $ptxt_chunk);
}

sodium_memzero($state);
fclose($inputFile);
fclose($outputFile);
}

// sodium_crypto_secretstream_xchacha20poly1305_keygen()
$key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

$example = sodium_hex2bin('971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c');
file_put_contents('hello.enc', $example);
decrypt_file('hello.enc', 'hello.txt.decrypted', $key);
var_dump(file_get_contents('hello.txt.decrypted'));
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "Hello world!"


暗号化のために、シークレットストリームのコンテキストを初期化する

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_init_pull
  • sodium_crypto_secretstream_xchacha20poly1305_keygen ≫
  • PHP Manual
  • Sodium 関数
  • 暗号化のために、シークレットストリームのコンテキストを初期化する

sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — 暗号化のために、シークレットストリームのコンテキストを初期化する

説明

sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter] string $key): array

暗号化のために、シークレットストリームのコンテキストを初期化します。

パラメータ

key

暗号化キー。 sodium_crypto_secretstream_xchacha20poly1305_keygen() を参照ください。

戻り値

ふたつの文字列からなる配列を返します。

  • シークレットストリームのステート。後にpushを行うために必要です。
  • シークレットストリームのヘッダ。受信側がデータをpullするために必要です。

例

例1 sodium_crypto_secretstream_xchacha20poly1305_init_push() の例

<?php
function encrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
{
[$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

$inputFile = fopen($inputFilePath, 'rb');
$outputFile = fopen($outputFilePath, 'wb');
// Write the header:
fwrite($outputFile, $header);
$inputFileSize = fstat($inputFile)['size'];

// Encrypt the file and write its contents to the output file:
for ($i = 0; $i < $inputFileSize; $i += 8175) {
$ptxt_chunk = fread($inputFile, 8175);
$ctxt_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($state, $ptxt_chunk);
fwrite($outputFile, $ctxt_chunk);
}

sodium_memzero($state);
fclose($inputFile);
fclose($outputFile);
}

// sodium_crypto_secretstream_xchacha20poly1305_keygen()
$key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

file_put_contents('hello.txt', 'Hello world!');
encrypt_file('hello.txt', 'hello.txt.encrypted', $key);
var_dump(sodium_bin2hex(file_get_contents('hello.txt.encrypted')));
?>

上の例の出力は、 たとえば以下のようになります。

string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"


ランダムなシークレットストリームのキーを生成する

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_init_push
  • sodium_crypto_secretstream_xchacha20poly1305_pull ≫
  • PHP Manual
  • Sodium 関数
  • ランダムなシークレットストリームのキーを生成する

sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — ランダムなシークレットストリームのキーを生成する

説明

sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

ランダムなシークレットストリームのキーを生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

ランダムなバイト列からなる文字列を返します。


暗号化されたストリームから、データのチャンクを複号する

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_keygen
  • sodium_crypto_secretstream_xchacha20poly1305_push ≫
  • PHP Manual
  • Sodium 関数
  • 暗号化されたストリームから、データのチャンクを複号する

sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — 暗号化されたストリームから、データのチャンクを複号する

説明

sodium_crypto_secretstream_xchacha20poly1305_pull(string &$state, string $ciphertext, string $additional_data = ""): array|false

暗号化されたストリームから、データのチャンクを複号します。

パラメータ

state

sodium_crypto_secretstream_xchacha20poly1305_init_pull() と sodium_crypto_secretstream_xchacha20poly1305_init_push() を参照ください。

ciphertext

復号する、暗号化されたテキスト。

additional_data

認証タグを含んだ、 オプションの追加データ

戻り値

2つの値を含んだ配列を返します。

  • 復号したチャンクの文字列。

  • (push時に提供された場合) オプションのタグ。 あり得る値は、以下のとおりです:

    • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE: もっとも一般的なタグ。 メッセージの性質についての情報を全く追加しません。
    • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL: メッセージがストリームの終端を示しており、 これより前のシーケンスで使われていた暗号化の鍵が削除されています。
    • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH: このメッセージが、メッセージの集合の終端としてマークされていますが、 ストリームの終端ではありません。 たとえば、複数のチャンクとして送信された巨大なJSON文字列は、 アプリケーションに文字列の終端を示し、 デコードできると指示することができます。 しかし、ストリームそのものは閉じられておらず、 さらにデータが続く可能性があります。
    • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY: このメッセージを暗号化するために、 これまでに使われてきた鍵を"忘れ"ます。 そして、新しい秘密鍵を生成します。


ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_pull
  • sodium_crypto_secretstream_xchacha20poly1305_rekey ≫
  • PHP Manual
  • Sodium 関数
  • ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する

sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する

説明

sodium_crypto_secretstream_xchacha20poly1305_push(
string &$state,
#[\SensitiveParameter] string $message,
string $additional_data = "",
int $tag = SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE
): string

ストリーミングAPIで安全に復号できるように、 データのチャンクを暗号化します。

パラメータ

state

sodium_crypto_secretstream_xchacha20poly1305_init_pull() と sodium_crypto_secretstream_xchacha20poly1305_init_push() を参照ください。

message

additional_data

tag

オプション。 復号の振る舞いを指示するために使えます。 (たとえば、鍵の再生成や、ストリームの最後のチャンクを示すなど)

  • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE: もっとも一般的なタグ。 メッセージの性質についての情報を全く追加しません。
  • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL: メッセージがストリームの終端であるとマークされており、 これより前のシーケンスで使われていた暗号化の鍵が削除されています。
  • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH: このメッセージが、メッセージの集合の終端としてマークされていますが、 ストリームの終端ではありません。 たとえば、複数のチャンクとして送信された巨大なJSON文字列は、 アプリケーションに文字列の終端を示し、 デコードできると指示することができます。 しかし、ストリームそのものは閉じられておらず、 さらにデータが続く可能性があります。
  • SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY: このメッセージを暗号化するために、 これまでに使われてきた鍵を"忘れ"ます。 そして、新しい秘密鍵を生成します。

戻り値

暗号化されたテキストを返します。


シークレットストリームのステート中で、鍵を入れ替える

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_push
  • sodium_crypto_shorthash ≫
  • PHP Manual
  • Sodium 関数
  • シークレットストリームのステート中で、鍵を入れ替える

sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — シークレットストリームのステート中で、鍵を入れ替える

説明

sodium_crypto_secretstream_xchacha20poly1305_rekey(string &$state): void

シークレットストリームのステート中で、鍵を明示的に入れ替えます。 渡された値は上書きされます。

パラメータ

state

シークレットストリームのステート

戻り値

値を返しません。


メッセージと鍵のための短いハッシュ値を計算する

  • ≪ sodium_crypto_secretstream_xchacha20poly1305_rekey
  • sodium_crypto_shorthash_keygen ≫
  • PHP Manual
  • Sodium 関数
  • メッセージと鍵のための短いハッシュ値を計算する

sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — メッセージと鍵のための短いハッシュ値を計算する

説明

sodium_crypto_shorthash(string $message, #[\SensitiveParameter] string $key): string

sodium_crypto_shorthash() は、SipHash-2-4 と呼ばれるハッシュ関数をラップします。 このハッシュ関数は、ハッシュの衝突によるサービス拒否攻撃 (Hash-DoS) から影響を受けにくい ハッシュテーブルを実装するのに理想的なものです。

SipHash-2-4 自体は、 一般的な用途の暗号で使うハッシュ関数ではありません。

パラメータ

message

ハッシュ化するメッセージ

key

ハッシュキー

戻り値


鍵のためのランダムなバイト値を得る

  • ≪ sodium_crypto_shorthash
  • sodium_crypto_sign ≫
  • PHP Manual
  • Sodium 関数
  • 鍵のためのランダムなバイト値を得る

sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — 鍵のためのランダムなバイト値を得る

説明

sodium_crypto_shorthash_keygen(): string

sodium_crypto_shorthash() で使うための鍵を生成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


メッセージに署名する

  • ≪ sodium_crypto_shorthash_keygen
  • sodium_crypto_sign_detached ≫
  • PHP Manual
  • Sodium 関数
  • メッセージに署名する

sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — メッセージに署名する

説明

sodium_crypto_sign(string $message, #[\SensitiveParameter] string $secret_key): string

秘密鍵を用いてメッセージに署名します。 これは、秘密鍵に対応する公開鍵で検証することができます。 この関数は、メッセージに署名を付加します。 メッセージとは別に署名を持つ方法については、 sodium_crypto_sign_detached() を参照ください。

パラメータ

message

署名するメッセージ

secret_key

秘密鍵。 sodium_crypto_sign_secretkey() を参照ください。

戻り値

署名済みのメッセージ(暗号化されていません) を返します。


メッセージに署名する

  • ≪ sodium_crypto_sign
  • sodium_crypto_sign_ed25519_pk_to_curve25519 ≫
  • PHP Manual
  • Sodium 関数
  • メッセージに署名する

sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — メッセージに署名する

説明

sodium_crypto_sign_detached(string $message, #[\SensitiveParameter] string $secret_key): string

秘密鍵を使って署名します。 この署名は、対応する公開鍵で検証できます。 この関数は、メッセージとは別の署名を返します。

パラメータ

message

署名するメッセージ

secret_key

秘密鍵。 sodium_crypto_sign_secretkey() を参照ください。

戻り値

署名を返します。


Ed25519 公開鍵を、Curve25519 公開鍵に変換する

  • ≪ sodium_crypto_sign_detached
  • sodium_crypto_sign_ed25519_sk_to_curve25519 ≫
  • PHP Manual
  • Sodium 関数
  • Ed25519 公開鍵を、Curve25519 公開鍵に変換する

sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Ed25519 公開鍵を、Curve25519 公開鍵に変換する

説明

sodium_crypto_sign_ed25519_pk_to_curve25519(string $public_key): string

指定された Ed25519 形式の公開鍵から、 双有理同値な X25519 形式の公開鍵を計算します。

パラメータ

public_key

crypto_sign 関数に適合する公開鍵

戻り値

crypto_box 関数に適合する公開鍵を返します。


Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する

  • ≪ sodium_crypto_sign_ed25519_pk_to_curve25519
  • sodium_crypto_sign_keypair ≫
  • PHP Manual
  • Sodium 関数
  • Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する

sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する

説明

sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter] string $secret_key): string

指定された Ed25519 形式の秘密鍵から、 双有理同値な X25519 形式の秘密鍵を計算します。

パラメータ

secret_key

crypto_sign 関数に適合する秘密鍵

戻り値

crypto_box 関数に適合する秘密鍵を返します。


秘密鍵と、対応する公開鍵をランダムに生成する

  • ≪ sodium_crypto_sign_ed25519_sk_to_curve25519
  • sodium_crypto_sign_keypair_from_secretkey_and_publickey ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵と、対応する公開鍵をランダムに生成する

sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — 秘密鍵と、対応する公開鍵をランダムに生成する

説明

sodium_crypto_sign_keypair(): string

ランダムな Ed25519 形式の鍵ペアをひとつの文字列として生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

Ed25519 形式の鍵ペアを返します。


秘密鍵と公開鍵を結合する

  • ≪ sodium_crypto_sign_keypair
  • sodium_crypto_sign_open ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵と公開鍵を結合する

sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵を結合する

説明

sodium_crypto_sign_keypair_from_secretkey_and_publickey(#[\SensitiveParameter] string $secret_key, string $public_key): string

秘密鍵と公開鍵を結合します。

パラメータ

secret_key

Ed25519 形式の秘密鍵

public_key

Ed25519 形式の公開鍵

戻り値

鍵ペアを返します。


署名済みのメッセージが、有効な署名を持っているかを調べる

  • ≪ sodium_crypto_sign_keypair_from_secretkey_and_publickey
  • sodium_crypto_sign_publickey ≫
  • PHP Manual
  • Sodium 関数
  • 署名済みのメッセージが、有効な署名を持っているかを調べる

sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — 署名済みのメッセージが、有効な署名を持っているかを調べる

説明

sodium_crypto_sign_open(string $signed_message, string $public_key): string|false

メッセージに付加された署名を検証し、メッセージを返します。

パラメータ

signed_message

sodium_crypto_sign() を使って署名されたメッセージ

public_key

Ed25519 形式の公開鍵

戻り値

成功時には、オリジナルの署名済みメッセージを返します。 失敗した場合に false を返します


鍵ペアから、Ed25519 形式の公開鍵を取り出す

  • ≪ sodium_crypto_sign_open
  • sodium_crypto_sign_publickey_from_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • 鍵ペアから、Ed25519 形式の公開鍵を取り出す

sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — 鍵ペアから、Ed25519 形式の公開鍵を取り出す

説明

sodium_crypto_sign_publickey(#[\SensitiveParameter] string $key_pair): string

鍵ペアから、Ed25519 形式の公開鍵を取り出します。

パラメータ

key_pair

Ed25519 形式の鍵ペア (sodium_crypto_sign_keypair() を参照ください)

戻り値

Ed25519 形式の公開鍵を返します。


秘密鍵から、Ed25519 形式の公開鍵を取り出す

  • ≪ sodium_crypto_sign_publickey
  • sodium_crypto_sign_secretkey ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵から、Ed25519 形式の公開鍵を取り出す

sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — 秘密鍵から、Ed25519 形式の公開鍵を取り出す

説明

sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter] string $secret_key): string

秘密鍵から、Ed25519 形式の公開鍵を取り出します。

パラメータ

secret_key

Ed25519 形式の秘密鍵

戻り値

Ed25519 形式の公開鍵を返します。


鍵ペアから、Ed25519 形式の秘密鍵を取り出す

  • ≪ sodium_crypto_sign_publickey_from_secretkey
  • sodium_crypto_sign_seed_keypair ≫
  • PHP Manual
  • Sodium 関数
  • 鍵ペアから、Ed25519 形式の秘密鍵を取り出す

sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — 鍵ペアから、Ed25519 形式の秘密鍵を取り出す

説明

sodium_crypto_sign_secretkey(#[\SensitiveParameter] string $key_pair): string

鍵ペアから、Ed25519 形式の秘密鍵を取り出します。

パラメータ

key_pair

Ed25519 形式の鍵ペア (sodium_crypto_sign_keypair() を参照ください)

戻り値

Ed25519 形式の秘密鍵を返します。


単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

  • ≪ sodium_crypto_sign_secretkey
  • sodium_crypto_sign_verify_detached ≫
  • PHP Manual
  • Sodium 関数
  • 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

説明

sodium_crypto_sign_seed_keypair(#[\SensitiveParameter] string $seed): string

秘密鍵を生成するためのシードを介して、 公開鍵を派生させ、秘密鍵と公開鍵のふたつを鍵ペアとして返します。

*_seed_keypair 関数はパスワードとソルトから鍵ペアを生成することと同じです。 seed としての結果を、 鍵を生成するために使います。

パラメータ

seed

暗号の処理をした入力。 長さは32バイトでなければなりません。

戻り値

鍵ペア(秘密鍵と公開鍵)を返します。


メッセージの署名を検証する

  • ≪ sodium_crypto_sign_seed_keypair
  • sodium_crypto_stream ≫
  • PHP Manual
  • Sodium 関数
  • メッセージの署名を検証する

sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — メッセージの署名を検証する

説明

sodium_crypto_sign_verify_detached(string $signature, string $message, string $public_key): bool

メッセージの署名を検証します。

パラメータ

signature

sodium_crypto_sign_detached() から取得した署名

message

検証するメッセージ

public_key

Ed25519 形式の公開鍵

戻り値

成功した場合に true を、失敗した場合に false を返します。


シードから、結果がひとつに定まるバイト列を生成する

  • ≪ sodium_crypto_sign_verify_detached
  • sodium_crypto_stream_keygen ≫
  • PHP Manual
  • Sodium 関数
  • シードから、結果がひとつに定まるバイト列を生成する

sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — シードから、結果がひとつに定まるバイト列を生成する

説明

sodium_crypto_stream(int $length, string $nonce, #[\SensitiveParameter] string $key): string

シードから、結果がひとつに定まるバイト列を生成します。 XSalsa20 ストリーム暗号を用います。

パラメータ

length

長さをバイト単位で指定します。

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key

暗号化キー(256ビット)

戻り値

擬似ランダムなバイト列を文字列として返します。


sodium_crypto_stream で用いる、ランダムな鍵を生成する

  • ≪ sodium_crypto_stream
  • sodium_crypto_stream_xchacha20 ≫
  • PHP Manual
  • Sodium 関数
  • sodium_crypto_stream で用いる、ランダムな鍵を生成する

sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — sodium_crypto_stream で用いる、ランダムな鍵を生成する

説明

sodium_crypto_stream_keygen(): string

sodium_crypto_stream() や sodium_crypto_stream_xor() で用いる鍵を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

256ビット長の暗号化キーを返します。


秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する

  • ≪ sodium_crypto_stream_keygen
  • sodium_crypto_stream_xchacha20_keygen ≫
  • PHP Manual
  • Sodium 関数
  • 秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する

sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — 秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する

説明

sodium_crypto_stream_xchacha20(int $length, string $nonce, #[\SensitiveParameter] string $key): string

key と nonce を 疑似ランダムなバイト列の鍵ストリームに展開します。

パラメータ

length

バイト列の長さ。

nonce

24バイト長の nonce。

key

秘密鍵。 sodium_crypto_stream_xchacha20_keygen() によって生成されたものです。

戻り値

sodium_crypto_stream_xchacha20_xor() で使う、疑似ランダムなバイト列のストリームを返します。


ランダムな暗号化キーを生成する

  • ≪ sodium_crypto_stream_xchacha20
  • sodium_crypto_stream_xchacha20_xor ≫
  • PHP Manual
  • Sodium 関数
  • ランダムな暗号化キーを生成する

sodium_crypto_stream_xchacha20_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — ランダムな暗号化キーを生成する

説明

sodium_crypto_stream_xchacha20_keygen(): string

sodium_crypto_stream_xchacha20() で使うランダムな鍵を生成して返します。

パラメータ

この関数にはパラメータはありません。

戻り値

sodium_crypto_stream_xchacha20() で使う、 32バイト長のランダムな暗号化キーを返します。


nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

  • ≪ sodium_crypto_stream_xchacha20_keygen
  • sodium_crypto_stream_xchacha20_xor_ic ≫
  • PHP Manual
  • Sodium 関数
  • nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

説明

sodium_crypto_stream_xchacha20_xor(#[\SensitiveParameter] string $message, string $nonce, #[\SensitiveParameter] string $key): string

nonce と 秘密鍵 key を使って message を暗号化します(認証はありません)

警告

この暗号化処理は認証を行いませんし、 選択暗号文攻撃(chosen-ciphertext attack) を防ぐことができません。 必ず暗号化されたテキストを認証コードと組み合わせるようにして下さい。 たとえば、 sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() や sodium_crypto_auth() を使うことが考えられます。

パラメータ

message

暗号化するメッセージ。

nonce

24バイトの nonce。

key

暗号化キー。 sodium_crypto_stream_xchacha20_keygen() で生成されたものです。

戻り値

暗号化されたメッセージを返します。

参考

  • sodium_crypto_stream_xchacha20_xor_ic() - nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)


nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

  • ≪ sodium_crypto_stream_xchacha20_xor
  • sodium_crypto_stream_xor ≫
  • PHP Manual
  • Sodium 関数
  • nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

説明

sodium_crypto_stream_xchacha20_xor_ic(
#[\SensitiveParameter] string $message,
string $nonce,
int $counter,
#[\SensitiveParameter] string $key
): string

この関数は、sodium_crypto_stream_xchacha20_xor() に似ていますが、ブロックカウンタの初期値を非ゼロの値に設定する機能が追加されています。 これによって、以前の値を計算せずに直接任意のブロックにアクセスすることができます。

警告

この暗号化処理は認証を行いませんし、 選択暗号文攻撃(chosen-ciphertext attack) を防ぐことができません。 必ず暗号化されたテキストを認証コードと組み合わせるようにして下さい。 たとえば、 sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() や sodium_crypto_auth() を使うことが考えられます。

パラメータ

message

暗号化するメッセージ。

nonce

24バイトの nonce。

counter

ブロックカウンタの初期値。

key

暗号化キー。 sodium_crypto_stream_xchacha20_keygen() で生成されたものです。

戻り値

暗号化されたメッセージを返します。 失敗した場合に false を返します

例

例1 sodium_crypto_stream_xchacha20_xor_ic() の例

<?php
$n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
$left = str_repeat("\x01", 64);
$right = str_repeat("\xfe", 64);

// All at once:
$stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);

// Piecewise, with initial counter:
$stream7_left = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
$stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
$stream7_concat = $stream7_left . $stream7_right;

var_dump(strlen($stream7_concat));
var_dump($stream7_unified === $stream7_concat);
?>

上の例の出力は、 たとえば以下のようになります。

int(128)
bool(true)

参考

  • sodium_crypto_stream_xchacha20_xor() - nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)


認証を行わずにメッセージを暗号化する

  • ≪ sodium_crypto_stream_xchacha20_xor_ic
  • sodium_hex2bin ≫
  • PHP Manual
  • Sodium 関数
  • 認証を行わずにメッセージを暗号化する

sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — 認証を行わずにメッセージを暗号化する

説明

sodium_crypto_stream_xor(#[\SensitiveParameter] string $message, string $nonce, #[\SensitiveParameter] string $key): string

この関数は XSalsa20 を用いて暗号化を行いますが、 プレーンテキストについて、 いかなる暗号学的な保証も行いません。

パラメータ

message

暗号化するメッセージ

nonce

メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。

key

暗号化キー(256ビット)

戻り値

暗号化されたメッセージを返します。


16進エンコードされたバイナリ文字列をデコードする

  • ≪ sodium_crypto_stream_xor
  • sodium_increment ≫
  • PHP Manual
  • Sodium 関数
  • 16進エンコードされたバイナリ文字列をデコードする

sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — 16進エンコードされたバイナリ文字列をデコードする

説明

sodium_hex2bin(#[\SensitiveParameter] string $string, string $ignore = ""): string

16進エンコードされたバイナリ文字列をデコードします。

sodium_bin2hex() と同じく、 sodium_hex2bin() 関数はサイドチャネル攻撃に対する耐性がありますが、 hex2bin() はそうではありません。

パラメータ

string

データの16進表現。

ignore

オプションで指定する、無視する文字

戻り値

指定された string のバイナリ表現を返します。


巨大な数をインクリメントする

  • ≪ sodium_hex2bin
  • sodium_memcmp ≫
  • PHP Manual
  • Sodium 関数
  • 巨大な数をインクリメントする

sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — 巨大な数をインクリメントする

説明

sodium_increment(string &$string): void

文字列をリトルエンディアンで表現した符号なし整数として扱い、 その値をインクリメントします。定数時間で動作します。

パラメータ

string

インクリメントする文字列。

戻り値

値を返しません。


定数時間での文字列の比較

  • ≪ sodium_increment
  • sodium_memzero ≫
  • PHP Manual
  • Sodium 関数
  • 定数時間での文字列の比較

sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — 定数時間での文字列の比較

説明

sodium_memcmp(#[\SensitiveParameter] string $string1, #[\SensitiveParameter] string $string2): int

ふたつの文字列を、定数時間で比較します。

実際、ほとんどの場合は hash_equals() を使いたいかもしれません。 なぜなら、同じロジックを提供しているにもかかわらず、 整数型ではなく、bool を返すからです。 しかしながら、タイミング攻撃に敏感な比較計算の結果を扱う場合、 かつ、bool値から整数型への変換の際の、 タイミングに依存した情報のリークを気にする場合、 sodium_memcmp() 関数が理想的な代替になります。

パラメータ

string1

比較対象の文字列

string2

もう一つの、比較する文字列

戻り値

双方の文字列が等しければ 0 を返します。 等しくない場合 -1 を返します。


文字列をNUL文字で上書きする

  • ≪ sodium_memcmp
  • sodium_pad ≫
  • PHP Manual
  • Sodium 関数
  • 文字列をNUL文字で上書きする

sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — 文字列をNUL文字で上書きする

説明

sodium_memzero(#[\SensitiveParameter] string &$string): void

sodium_memzero() は、 リファレンス渡しされた文字列をゼロ埋めします。

パラメータ

string

文字列

戻り値

値を返しません。


パディングデータを追加する

  • ≪ sodium_memzero
  • sodium_unpad ≫
  • PHP Manual
  • Sodium 関数
  • パディングデータを追加する

sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — パディングデータを追加する

説明

sodium_pad(#[\SensitiveParameter] string $string, int $block_size): string

文字列の右側に、任意の長さのパディングを追加します。 タイミング攻撃に対しても安全です。

パラメータ

string

パディングされていない文字列。

block_size

ここで指定されたブロックサイズの偶数倍になるまで、 文字列にパディングが追加されます。

戻り値

パディングが追加された文字列。


パディングを削除する

  • ≪ sodium_pad
  • SodiumException ≫
  • PHP Manual
  • Sodium 関数
  • パディングを削除する

sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — パディングを削除する

説明

sodium_unpad(#[\SensitiveParameter] string $string, int $block_size): string

パディングされた文字列から、パディングを削除します。 タイミング攻撃に対しても安全です。

パラメータ

string

パディングされた文字列。

block_size

パディングのブロックサイズ

戻り値

パディングが削除された文字列を返します。


SodiumException クラス

(PHP 7 >= 7.2.0, PHP 8)

はじめに

sodium 関数によってスローされる例外です。

クラス概要

class SodiumException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


データベース関連

  • 抽象化レイヤー
    • DBA — データベース (dbm 形式) 抽象化レイヤ
    • ODBC — ODBC (Unified)
    • PDO — PHP Data Objects
  • ベンダー固有のモジュール
    • CUBRID
    • dBase
    • Firebird/InterBase
    • IBM DB2 — IBM DB2、Cloudscape および Apache Derby
    • MongoDB — MongoDB Extension
    • MySQL — MySQL ドライバおよびプラグイン
    • OCI8 — Oracle OCI8
    • PostgreSQL
    • SQLite3
    • SQLSRV — PHP 用 Microsoft SQL Server ドライバ


抽象化レイヤー

  • DBA — データベース (dbm 形式) 抽象化レイヤ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • DBA 関数
  • ODBC — ODBC (Unified)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ODBC 関数
  • PDO — PHP Data Objects
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 接続、および接続の管理
    • トランザクションおよび自動コミット
    • プリペアドステートメントおよびストアドプロシージャ
    • エラーおよびエラー処理
    • ラージオブジェクト (LOB)
    • PDO — PDO クラス
    • PDOStatement — PDOStatement クラス
    • PDOException — PDOException クラス
    • PDORow — PDORow クラス
    • PDO ドライバ


データベース (dbm 形式) 抽象化レイヤ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な例
  • DBA 関数
    • dba_close — DBA データベースを閉じる
    • dba_delete — キーが指す DBA エントリを削除する
    • dba_exists — キーが存在するかどうかを確認する
    • dba_fetch — キーが指すデータを取得する
    • dba_firstkey — 最初のキーを取得する
    • dba_handlers — 利用可能なハンドラの一覧を得る
    • dba_insert — エントリを挿入する
    • dba_key_split — 文字列形式のキーを配列形式に分割する
    • dba_list — オープンされている全データベースファイルのリストを得る
    • dba_nextkey — 次のキーを取得する
    • dba_open — データベースをオープンする
    • dba_optimize — データベースを最適化する
    • dba_popen — データベースを持続的にオープンする
    • dba_replace — エントリを置換または挿入する
    • dba_sync — データベースを同期する


はじめに

これらの関数は、Berkeley DB 型データベースへのアクセス用の基本関数を構成します。

これらの関数は、複数のファイルベースのデータベース用の抽象化レイヤです。 その機能は、» Oracle Berkeley DB でサポートされているような近代的なデータベースの 機能のサブセットに制限されています。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • DBA
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

各機能の動作は、使用するデータベースの実装に依存します。 dba_optimize() および dba_sync() のような関数は、特定のデータベースでは動作しますが、他のデータベースでは 機能しません。サポートされるdbaハンドラをダウンロードし、インストールする 必要があります。

DBA ハンドラのリスト
ハンドラ | 注意
dbm | dbm は最も古い(元祖の)Berkeley DB 型データベースです。可能なら ば使用しない方が良いでしょう。DB2 および gdbm に組み込まれている 互換性を保つための関数は、サポートされません。これは、実装されて いるのがソースレベルの互換性のみであり、元の dbm フォーマットを 処理することができないためです。
ndbm | ndbm は、dbm に比べて新しく、dbm よりも柔軟です。 dbm 固有の制約の多くをまだ有しています（そのため、 推奨されません）。
gdbm | Gdbm は、» GNU データベースマネージャ です。
db2 | DB2 は、» Oracle Berkeley DB 2 用です。これは、「スタンドアローンおよびクライアント/サーバー アプリケーションの両方で高性能な組込みデータベースサポートを提供する プログラム用ツールキット」として記述されています。
db3 | DB3 は、» Oracle Berkeley DB 3 用です。
db4 | DB4 は、» Oracle Berkeley DB 4 あるいは 5 用です。 BDB 5 を使用できるのは、PHP 5.3.3 以降です。
cdb | cdb は「固定データベースの作成・読込み用の、高速で高信頼性の 軽量型パッケージ」です。これは qmail の作者によるものであり、 » http://cr.yp.to/cdb.html にあります。 固定であるため、読込操作のみがサポートされます。 内部的な cdb ライブラリにより（更新ではなく） 書き込みがサポートされています。
cdb_make | 付属する cdb ライブラリを使用する場合に cdb ファイルの（更新ではなく）作成をサポートします。
flatfile | これは、古い dbm 拡張モジュールとの互換性の ためだけのものであり、使用するべきではありません。 しかし、ファイルがこの形式で作成された場所でこれを使用する ことができます。これは、configure が外部ライブラリを見付ける ことができない場合に生じます。
inifile | これは PHP スクリプトから php.ini ファイルを書き換えられるようにします。ini ファイルを扱う場合は、 array(0=>group,1=>value_name) のような配列、あるいは "[group]value_name" のような文字列を渡します（group はオプションです）。 dba_firstkey() や dba_nextkey() はキーを文字列形式で返しますが、 dba_key_split() を用いるとそれを配列形式に 変換できます。その際に false を失うこともありません。
qdbm | qdbm ライブラリは » http://fallabs.com/qdbm/index.html からダウンロードできます。
tcadb | Tokyo Cabinet ライブラリは » http://fallabs.com/tokyocabinet/ からダウンロードできます。
lmdb | PHP 7.2.0 以降で利用可能です。 Lightning Memory-Mapped Database ライブラリは » https://symas.com/lmdb/ からダウンロードできます。

dba_open() または dba_popen() 関数を実行する際、引数にハンドラ名の一つを指定する必要があります。 実際に利用可能なハンドラのリストは、 phpinfo() または dba_handlers() をコールした際に表示されます。


インストール手順

設定オプション --enable-dba=shared を使用することにより、dbm 形式のデータベースをサポートする動的に ロード可能なモジュールを有効にして PHP を構築することができます。 また、PHP の configure 行に設定スイッチ --with-XXXX または --enable-XXXX を指定することにより、少なくとも以下のハンドラの一つのサポートを 追加する必要があります。

警告

PHP の configuring とコンパイルを済ませたら、コマンドラインから次の テストを実行する必要があります: php run-tests.php ext/dba これは、指定したハンドラの組み合わせが動作するかどうかを調べます。 いちばん問題のあるのは dbm と ndbm の組み合わせで、これらは多くの場合何らかの衝突を引き起こします。 その原因は、いくつかのシステムではこれらのライブラリが他のライブラリの 一部となっていることで。configure 時のテストでは個々のハンドラについての 設定不備は調べられますが、それらの組み合わせについてはテストできません。

サポートされるDBAハンドラ
ハンドラ | configure のスイッチ
dbm dbm のサポートを有効にするには、 --with-dbm[=DIR] を追加します。

注意:

dbm は一般的にはラッパーで、しばしば失敗を引き起こします。 その動作をしっかり把握しており、ほんとうにそれを必要とする場合のみ dbm を使用するようにすべきです。

ndbm ndbm のサポートを有効にするには、 --with-ndbm[=DIR] を追加します。

注意:

ndbm は一般的にはラッパーで、しばしば失敗を引き起こします。 その動作をしっかり把握しており、ほんとうにそれを必要とする場合のみ ndbm を使用するようにすべきです。

gdbm | gdbm のサポートを有効にするには、 --with-gdbm[=DIR] を追加します。
db2 Oracle Berkeley DB のサポートを有効にするには、 --with-db2[=DIR] を追加します。

注意:

db2 は db3 および db4 とは同時に使えません。

db3 Oracle Berkeley DB 3 のサポートを有効にするには、 --with-db3[=DIR] を追加します。

注意:

db3 は db2 および db4 とは同時に使えません。

db4 Oracle Berkeley DB 4 あるいは 5 のサポートを有効にするには、 --with-db4[=DIR] を追加します。

注意:

db4 は db2 および db3 とは同時に使えません。

注意:

バージョン 4.1 から 4.1.24 までの db ライブラリは、どの PHP のバージョンでも利用できません。

BDB 5 のサポートは PHP 5.3.3 で追加されました。

cdb cdb のサポートを有効にするには、 --with-cdb[=DIR] を追加します。

注意:

付属する cdb ライブラリを使用するために DIR を省略することができます。この場合、cdb_make ハンドラが追加されます。 これにより cdb ファイルを作成したり、PHPのストリームを用いて ネットワーク上の cdb ファイルにアクセスできるようになります。

flatfile flatfile のサポートを有効にするには、 --enable-flatfile を追加します。 PHP 5.2.1 以前では、 --with-flatfile オプションを使わなければなりませんでした。

注意:

これは、古い dbm 拡張モジュール との互換性のために追加されました。 このハンドラは、他のハンドラで必要とされるライブラリをひとつも インストールすることができない場合、そして、付属する cdb ハンドラを使用することができない場合にのみ使用してください。

inifile inifile のサポートを有効にするには、 --enable-inifile を追加します。 PHP 5.2.1 以前では、 --with-inifile オプションを使わなければなりませんでした。

注意:

これは Microsoft 形式の .ini ファイル（php.ini のような）を 読み書きできるようにするために追加されました。

qdbm qdbm のサポートを有効にするには、 --with-qdbm[=DIR] を追加します。

注意:

qdbm は dbm および gdbm とは同時に使えません。

注意:

qdbm ライブラリは » http://fallabs.com/qdbm/index.html からダウンロードできます。

tcadb

Tokyo Cabinet のサポートを有効にするには、 --with-tcadb[=DIR] を追加します。

注意:

Tokyo Cabinet ライブラリは » http://fallabs.com/tokyocabinet/ からダウンロードできます。

lmdb

Lightning Memory-Mapped Database のサポートを有効にするには、 --with-lmdb[=DIR] を追加します。

注意:

これは PHP 7.2.0 で追加されました。 Lightning Memory-Mapped Database は » https://symas.com/lmdb/ からダウンロードできます。


実行時設定

php.ini の設定により動作が変化します。

DBA 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
dba.default_handler | DBA_DEFAULT | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

dba.default_handler string

デフォルトのハンドラ名。


リソース型

関数 dba_open() および dba_popen() は、指定したデータベースファイルに アクセスするためのハンドルを返します。このハンドルは、他の全ての dba 関数コールで使用されます。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

DBA_LMDB_USE_SUB_DIR (int)

LMDB ドライバ用のフラグです。 サブディレクトリを作ることを許可します。 PHP 8.2.0 以降で利用可能です。

DBA_LMDB_NO_SUB_DIR (int)

LMDB ドライバ用のフラグです。 サブディレクトリを作ることを許可しません。 PHP 8.2.0 以降で利用可能です。


  • ≪ 定義済み定数
  • 基本的な例 ≫
  • PHP Manual
  • DBA
  • 例

例

目次

  • 基本的な例


基本的な例

例1 DBA の例

<?php

$id = dba_open("/tmp/test.db", "n", "db2");

if (!$id) {
echo "dba_open failed\n";
exit;
}

dba_replace("key", "This is an example!", $id);

if (dba_exists("key", $id)) {
echo dba_fetch("key", $id);
dba_delete("key", $id);
}

dba_close($id);
?>

DBA はバイナリセーフであり、いかなる制限も受けません。しかし、 使用するデータベースの実装による全ての制約を継承します。

全てのファイルベースのデータベースは、完全に使用可能なものについて 新規に作成されたデータベースのファイルモードを設定する手段を、 提供する必要があります。 ファイルモードは、通常 dba_open() または dba_popen() に 4 番目の引数として渡されます。

dba_firstkey() および dba_nextkey() 関数を用いて全てのエントリに 連続的にアクセスすることができます。アクセスする際にデータベースを 変更できない可能性があります。

例2 データベースへのアクセス

<?php

// データベースをオープンする

$key = dba_firstkey($id);

while ($key !== false) {
if (true) { // 他の操作を後で行うためにキーを記憶する
$handle_later[] = $key;
}
$key = dba_nextkey($id);
}

foreach ($handle_later as $val) {
dba_delete($val, $id);
}

?>


DBA 関数

目次

  • dba_close — DBA データベースを閉じる
  • dba_delete — キーが指す DBA エントリを削除する
  • dba_exists — キーが存在するかどうかを確認する
  • dba_fetch — キーが指すデータを取得する
  • dba_firstkey — 最初のキーを取得する
  • dba_handlers — 利用可能なハンドラの一覧を得る
  • dba_insert — エントリを挿入する
  • dba_key_split — 文字列形式のキーを配列形式に分割する
  • dba_list — オープンされている全データベースファイルのリストを得る
  • dba_nextkey — 次のキーを取得する
  • dba_open — データベースをオープンする
  • dba_optimize — データベースを最適化する
  • dba_popen — データベースを持続的にオープンする
  • dba_replace — エントリを置換または挿入する
  • dba_sync — データベースを同期する


DBA データベースを閉じる

  • ≪ DBA 関数
  • dba_delete ≫
  • PHP Manual
  • DBA 関数
  • DBA データベースを閉じる

dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — DBA データベースを閉じる

説明

dba_close(resource $dba): void

dba_close() は確立されたデータベースを閉じ、 により指定したデータベースハンドルの全てのリソースを開放します。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

値を返しません。

参考

  • dba_open() - データベースをオープンする
  • dba_popen() - データベースを持続的にオープンする


キーが指す DBA エントリを削除する

  • ≪ dba_close
  • dba_exists ≫
  • PHP Manual
  • DBA 関数
  • キーが指す DBA エントリを削除する

dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — キーが指す DBA エントリを削除する

説明

dba_delete(string|array $key, resource $dba): bool

dba_delete() は、指定されたエントリを データベースから削除します。

パラメータ

key

削除するエントリのキー。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_fetch() - キーが指すデータを取得する
  • dba_insert() - エントリを挿入する
  • dba_replace() - エントリを置換または挿入する


キーが存在するかどうかを確認する

  • ≪ dba_delete
  • dba_fetch ≫
  • PHP Manual
  • DBA 関数
  • キーが存在するかどうかを確認する

dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — キーが存在するかどうかを確認する

説明

dba_exists(string|array $key, resource $dba): bool

dba_exists() は、指定した key がデータベースに存在するかどうかを確認します。

パラメータ

key

確認を行うキー。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

キーが存在する場合に true 、それ以外の場合に false を返します。

参考

  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_fetch() - キーが指すデータを取得する
  • dba_insert() - エントリを挿入する
  • dba_replace() - エントリを置換または挿入する


キーが指すデータを取得する

  • ≪ dba_exists
  • dba_firstkey ≫
  • PHP Manual
  • DBA 関数
  • キーが指すデータを取得する

dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — キーが指すデータを取得する

説明

dba_fetch(string|array $key, resource $dba, int $skip = 0): string|false

以下はオーバーロードされているが、PHP 8.3.0 以降では推奨されないシグネチャです:

dba_fetch(string|array $key, int $skip, resource $dba): string

dba_fetch() は、dba が指すデータベースから key が指すデータを 取得します。

パラメータ

key

データを取得するキー。

注意:

inifile を利用する際には、この関数は配列を受け入れることが可能です。 インデックス 0 にはグループ名、インデックス 1 には値の名前を格納します。 dba_key_split() も参照ください。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

skip

cdb データベースを使用する際に無視する キー / 値 の組み合わせ数。 複数のキーに同じ名前をつけることがサポートされていないデータベースです、 この値は無視されます。

戻り値

キー / データの組が見つかった場合にそれに関連する文字列、 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | dba を第3引数に渡して dba_fetch() をコールすることは、推奨されなくなりました。
8.2.0 | dba_fetch() 関数のオプションの skip 引数は、 PHP でユーザーが使える関数のセマンティクスに従い、 最後に置かれるようになりました。 以前のオーバーロードされたシグネチャも引き続き許可されますが、 使わないことをお勧めします。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_insert() - エントリを挿入する
  • dba_replace() - エントリを置換または挿入する
  • dba_key_split() - 文字列形式のキーを配列形式に分割する


最初のキーを取得する

  • ≪ dba_fetch
  • dba_handlers ≫
  • PHP Manual
  • DBA 関数
  • 最初のキーを取得する

dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — 最初のキーを取得する

説明

dba_firstkey(resource $dba): string|false

dba_firstkey() はデータベースの最初のキーを返し、 内部キーポインタをリセットします。 この関数によりデータベース全体を連続的にサーチすることが可能になります。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合にキー、失敗した場合に false を返します。

参考

  • dba_nextkey() - 次のキーを取得する
  • dba_key_split() - 文字列形式のキーを配列形式に分割する
  • DBA の例の例 2


利用可能なハンドラの一覧を得る

  • ≪ dba_firstkey
  • dba_insert ≫
  • PHP Manual
  • DBA 関数
  • 利用可能なハンドラの一覧を得る

dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — 利用可能なハンドラの一覧を得る

説明

dba_handlers(bool $full_info = false): array

dba_handlers() は、この拡張モジュールにより サポートされる全てのハンドラの一覧を返します。

パラメータ

full_info

結果の全ての情報を表示するかどうかを切り替えます。

戻り値

データベースハンドラの配列を返します。full_info が true の場合、この配列はハンドラ名をキー、そのバージョンを値とする 連想配列となります。それ以外の場合はハンドラ名を値に持つ数値添字の配列と なります。

注意:

cdb ライブラリが用いられている場合、 cdb および cdb_make が表示されます。

例

例1 dba_handlers() の例

<?php

echo "Available DBA handlers:\n";
foreach (dba_handlers(true) as $handler_name => $handler_version) {
// バージョン番号を見やすくする
$handler_version = str_replace('$', '', $handler_version);
echo " - $handler_name: $handler_version\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Available DBA handlers:
 - cdb: 0.75, Revision: 1.3.2.3
 - cdb_make: 0.75, Revision: 1.2.2.4
 - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
 - inifile: 1.0, Revision: 1.6.2.3
 - flatfile: 1.0, Revision: 1.5.2.4


エントリを挿入する

  • ≪ dba_handlers
  • dba_key_split ≫
  • PHP Manual
  • DBA 関数
  • エントリを挿入する

dba_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — エントリを挿入する

説明

dba_insert(string|array $key, string $value, resource $dba): bool

dba_insert() は、 データベースに key および value で記述されるエントリを挿入します。

パラメータ

key

挿入するエントリのキー。もしこのキーが既にデータベースに存在する場合、 この関数は失敗します。既存のキーを置き換える場合は、 dba_replace() を使用してください。

value

挿入する値。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_fetch() - キーが指すデータを取得する
  • dba_replace() - エントリを置換または挿入する


文字列形式のキーを配列形式に分割する

  • ≪ dba_insert
  • dba_list ≫
  • PHP Manual
  • DBA 関数
  • 文字列形式のキーを配列形式に分割する

dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — 文字列形式のキーを配列形式に分割する

説明

dba_key_split(string|false|null $key): array|false

dba_key_split() は、キー（文字列形式） を配列に分割します。

パラメータ

key

文字列形式のキー。

戻り値

array(0 => group, 1 => value_name) 形式の配列を返します。 key が null あるいは false の場合には この関数は false を返します。

参考

  • dba_firstkey() - 最初のキーを取得する
  • dba_nextkey() - 次のキーを取得する
  • dba_fetch() - キーが指すデータを取得する


オープンされている全データベースファイルのリストを得る

  • ≪ dba_key_split
  • dba_nextkey ≫
  • PHP Manual
  • DBA 関数
  • オープンされている全データベースファイルのリストを得る

dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — オープンされている全データベースファイルのリストを得る

説明

dba_list(): array

dba_list() は、オープンされている全ての データベースファイルの一覧を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

resourceid => filename 形式の連想配列を返します。


次のキーを取得する

  • ≪ dba_list
  • dba_open ≫
  • PHP Manual
  • DBA 関数
  • 次のキーを取得する

dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — 次のキーを取得する

説明

dba_nextkey(resource $dba): string|false

dba_nextkey() は、 が指すデータベースの次のキーを返し、内部キーポインタを進めます。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合にキー、失敗した場合に false を返します。

参考

  • dba_firstkey() - 最初のキーを取得する
  • dba_key_split() - 文字列形式のキーを配列形式に分割する
  • DBA の例の例 2


データベースをオープンする

  • ≪ dba_nextkey
  • dba_optimize ≫
  • PHP Manual
  • DBA 関数
  • データベースをオープンする

dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — データベースをオープンする

説明

dba_open(
string $path,
string $mode,
?string $handler = null,
int $permission = 0644,
int $map_size = 0,
?int $flags = null
): resource|false

dba_open() は、handler を用いて mode を指定し、path にデータベースインスタンスを生成します。

パラメータ

path

通常のファイルシステムのパス。

mode

既存のデータベースへの読み込みアクセスには "r"、読込み/書き込み アクセスには "w" を指定します。 読み込み/書き込みアクセスおよび存在しない場合にデータベースの作成を するには "c" を、そして作成、削除、読込み/書き込みアクセス用には "n" を指定します。データベースは BTree モードで作られます。 その他のモード (Hash や Queue) には対応していません。

さらに、次の文字でデータベースのロック方法を指定することができます。 .lck でデータベースをロックする場合には "l"、 データベースファイル自体をロックする場合は "d" を使用してください。 アプリケーション全体で統一した方法を用いることが重要です。

アクセスのテストを行う際にロックのために待ちたくない場合、"t" を 3 番目の文字に追加することができます。明らかにデータベースのロックが 不要な場合には、"l" や "d" の代わりに "-" を使用してロックを 行わないことができます。"d"、"l" または "-" のどれも指定されない場合、 "d"が指定されたものとしてデータベースファイルをロックします。

注意:

ひとつのデータベースファイルに同時に書き込めるのは、ひとつだけです。 dba を Web サーバーで使用している際に複数のリクエストが書き込み処理を 行う必要がある場合、他の書き込みが終わってからでないと次の書き込みを 行うことができません。また、書き込み中に読み込むことはできません。 dba 拡張モジュールは、このようなことを防止するためにロックを使用します。 以下の表を参照ください:

DBA のロック処理
既にオープンしているデータベース | mode = "rl" | mode = "rlt" | mode = "wl" | mode = "wlt" | mode = "rd" | mode = "rdt" | mode = "wd" | mode = "wdt"
not open | ok | ok | ok | ok | ok | ok | ok | ok
mode = "rl" | ok | ok | wait | false | illegal | illegal | illegal | illegal
mode = "wl" | wait | false | wait | false | illegal | illegal | illegal | illegal
mode = "rd" | illegal | illegal | illegal | illegal | ok | ok | wait | false
mode = "wd" | illegal | illegal | illegal | illegal | wait | false | wait | false
  • ok: 2 番目のコールは成功します。
  • wait: 2 番目のコールは、最初のデータベースで dba_close() がコールされるまで待ちます。
  • false: 2 番目のコールは、false を返します。
  • illegal: mode パラメータで "l" および "d" を同時に使用することはできません。

handler

path にアクセスする際に使用する ハンドラの名前。 dba_open() に指定したすべてのオプションが渡され、 その機能を用いることができます。 handler が null の場合、 デフォルトのハンドラが使われます。

permission

ドライバに渡されるオプションの整数パラメータ。 chmod() の permissions を同じ意味です。 デフォルトは 0644 です。

db1, db2, db3, db4, dbm, gdbm, ndbm, lmdb ドライバが permission パラメータをサポートしています。

map_size

ドライバに渡されるオプションの整数パラメータ。 OS のページサイズの倍数を指定すべきです。 ゼロを指定すると、デフォルトのマップサイズが使われます。

lmdb ドライバだけが map_size パラメータを受け入れます。

flags

データベースドライバに渡すフラグ。 null の場合、 デフォルトのフラグが渡されます。 現状、LMDB ドライバだけが DBA_LMDB_USE_SUB_DIR と DBA_LMDB_NO_SUB_DIR をサポートしています。

戻り値

成功した場合に正のハンドルを返します。 失敗した場合に false を返します。

エラー / 例外

handler に null が指定されているのにデフォルトのハンドラが存在しない場合、 E_WARNING レベルのエラーが発生し、 false が返されます。

変更履歴

バージョン | 説明
8.2.0 | flags が追加されました。
8.2.0 | handler は、nullable になりました。
7.3.14, 7.4.2 | lmdb ドライバは、 map_size パラメータを追加でサポートしました。

参考

  • dba_popen() - データベースを持続的にオープンする
  • dba_close() - DBA データベースを閉じる


データベースを最適化する

  • ≪ dba_open
  • dba_popen ≫
  • PHP Manual
  • DBA 関数
  • データベースを最適化する

dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — データベースを最適化する

説明

dba_optimize(resource $dba): bool

dba_optimize() は、指定されたデータベースを最適化します。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_sync() - データベースを同期する


データベースを持続的にオープンする

  • ≪ dba_optimize
  • dba_replace ≫
  • PHP Manual
  • DBA 関数
  • データベースを持続的にオープンする

dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — データベースを持続的にオープンする

説明

dba_popen(
string $path,
string $mode,
?string $handler = null,
int $permission = 0644,
int $map_size = 0,
?int $flags = null
): resource|false

dba_popen() は、handler を用いて mode で path に持続的なデータベースインスタンスを確立します。

パラメータ

path

通常のファイルシステムのパス。

mode

既存のデータベースへの読み込みアクセスには "r"、読込み/書き込み アクセスには "w" を指定します。 読み込み/書き込みアクセスおよび存在しない場合にデータベースの作成を するには "c" を、そして作成、削除、読込み/書き込みアクセス用には "n" を指定します。

handler

path にアクセスする際に使用する ハンドラの名前。 dba_popen() に指定したすべてのオプションが 渡され、その機能を用いることができます。 handler が null の場合、 デフォルトのハンドラが使われます。

permission

ドライバに渡されるオプションの整数パラメータ。 chmod() の permissions を同じ意味です。 デフォルトは 0644 です。

db1, db2, db3, db4, dbm, gdbm, ndbm, lmdbドライバが permission パラメータをサポートしています。

map_size

ドライバに渡されるオプションの整数パラメータ。 OS のページサイズの倍数を指定すべきです。 ゼロを指定すると、デフォルトのマップサイズが使われます。

lmdb ドライバだけが map_size パラメータを受け入れます。

flags

データベースドライバに渡すフラグ。 現状、LMDB ドライバだけが DBA_LMDB_USE_SUB_DIR と DBA_LMDB_NO_SUB_DIR をサポートしています。

戻り値

成功した場合に正のハンドルを返します。 失敗した場合に false を返します。

エラー / 例外

handler に null が指定されているのにデフォルトのハンドラが存在しない場合、 E_WARNING レベルのエラーが発生し、 false が返されます。

変更履歴

バージョン | 説明
8.2.0 | flags が追加されました。
8.1.0 | handler は、nullable になりました。
7.3.14, 7.4.2 | lmdb ドライバは、 map_size パラメータを追加でサポートしました。

参考

  • dba_open() - データベースをオープンする
  • dba_close() - DBA データベースを閉じる


エントリを置換または挿入する

  • ≪ dba_popen
  • dba_sync ≫
  • PHP Manual
  • DBA 関数
  • エントリを置換または挿入する

dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — エントリを置換または挿入する

説明

dba_replace(string|array $key, string $value, resource $dba): bool

dba_replace() は、dba で 指定したデータベースに key および value で記述されるエントリを 置換または挿入します。

パラメータ

key

置換するエントリのキー。

value

置換される値。

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_exists() - キーが存在するかどうかを確認する
  • dba_delete() - キーが指す DBA エントリを削除する
  • dba_fetch() - キーが指すデータを取得する
  • dba_insert() - エントリを挿入する


データベースを同期する

  • ≪ dba_replace
  • ODBC ≫
  • PHP Manual
  • DBA 関数
  • データベースを同期する

dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — データベースを同期する

説明

dba_sync(resource $dba): bool

dba_sync() は データベースを同期します。サポートされる場合には、 おそらくディスクへの物理的アクセスへのきっかけとなることでしょう。

パラメータ

dba

dba_open() あるいは dba_popen() によって返されたデータベースハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • dba_optimize() - データベースを最適化する


ODBC (Unified)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ODBC 関数
    • odbc_autocommit — 自動コミットの動作をオンまたはオフにする
    • odbc_binmode — バイナリカラムデータを処理する
    • odbc_close — ODBC 接続を閉じる
    • odbc_close_all — 全ての ODBC 接続を閉じる
    • odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
    • odbc_columns — 指定したテーブルにあるカラム名のリストを取得する
    • odbc_commit — ODBC トランザクションをコミットする
    • odbc_connect — データソースに接続する
    • odbc_connection_string_is_quoted — ODBC の接続文字列の値が、クオートされているかを調べる
    • odbc_connection_string_quote — ODBC の接続文字列をクオートする
    • odbc_connection_string_should_quote — ODBC の接続文字列を、クオートすべきかを調べる
    • odbc_cursor — カーソル名を得る
    • odbc_data_source — 利用可能なDSNについての情報を返す
    • odbc_do — odbc_exec のエイリアス
    • odbc_error — 直近のエラーコードを得る
    • odbc_errormsg — 直近のエラーメッセージを得る
    • odbc_exec — SQL文を直接実行する
    • odbc_execute — プリペアドステートメントを実行する
    • odbc_fetch_array — 連想配列として結果の行を取得する
    • odbc_fetch_into — 一行ぶんの結果を配列に取り込む
    • odbc_fetch_object — オブジェクトとして結果の行を取得する
    • odbc_fetch_row — 行を取り込む
    • odbc_field_len — フィールドの長さ (精度) を得る
    • odbc_field_name — カラム名を得る
    • odbc_field_num — カラム番号を返す
    • odbc_field_precision — odbc_field_len のエイリアス
    • odbc_field_scale — フィールドの精度を得る
    • odbc_field_type — フィールドのデータ型を返す
    • odbc_foreignkeys — 外部キーのリストを取得する
    • odbc_free_result — 結果を保持するリソースを開放する
    • odbc_gettypeinfo — データソースがサポートするデータ型についての情報を取得する
    • odbc_longreadlen — LONG カラムを処理する
    • odbc_next_result — 複数の結果が利用可能などうか確認する
    • odbc_num_fields — 結果のカラム数を返す
    • odbc_num_rows — 結果における行数を返す
    • odbc_pconnect — 持続的なデータベース接続を開く
    • odbc_prepare — 実行用に文を準備する
    • odbc_primarykeys — テーブルの主キーを取得する
    • odbc_procedurecolumns — プロシージャへのパラメータに関する情報を取得する
    • odbc_procedures — 指定したデータソースに保存されているプロシージャのリストを取得する
    • odbc_result — 結果データを得る
    • odbc_result_all — HTML テーブルとして結果を出力する
    • odbc_rollback — トランザクションをロールバックする
    • odbc_setoption — ODBC の設定を変更する
    • odbc_specialcolumns — 特殊カラムを取得する
    • odbc_statistics — テーブルに関する統計情報を取得する
    • odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する
    • odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する


はじめに

通常の ODBC サポートに加えて、PHP の Unified ODBC 関数では、各々の API を実装するために ODBC API のセマンティックスを借用する複数の データベースにアクセスすることが可能です。ほとんど同じ複数のデータベース ドライバを維持管理する代わりに、これらのドライバは単一の ODBC 関数セットに 統合されています。

以下のデータベースが Unified ODBC でサポートされています。 » Adabas D, » IBM DB2, » iODBC, » Solid, » Sybase SQL Anywhere

注意:

iODBC を除き、上のデータベースと接続する際には ODBC は使用しません。 内部ではネイティブに通信しており、単に ODBC 関数と同じ名前や構文を用いているだけです。 しかし、PHP を iODBC サポートつきでビルドすると、 任意の ODBC 準拠のドライバを PHP アプリケーションから使用できるようになります。 iODBC についてのより詳細な情報は » www.iodbc.org にあります。 またもうひとつの方法である unixODBC は » www.unixodbc.org にあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • ODBC
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

サポートされるデータベースにアクセスするためには、 所定のライブラリがインストールされている必要があります。


インストール手順

--with-adabas[=DIR]

Adabas D サポートを有効にします。DIR はAdabas をインストールしたディレクトリで、 /usr/local がデフォルトです。

--with-sapdb[=DIR]

SAP DB サポートを有効にします。DIR は SAP DB のベースインストールディレクトリで、 /usr/local がデフォルトです。

--with-solid[=DIR]

Solidサポートを有効にします。DIR は Solid のベースインストールディレクトリで、 /usr/local/solid がデフォルトです。

--with-ibm-db2[=DIR]

IBM DB2 サポートを有効にします。DIR は IBM DB2 のベースインストールディレクトリで、 /home/db2inst1/sqllib がデフォルトです。

--with-empress[=DIR]

Empress サポートを有効にします。DIR は Empress のベースインストールディレクトリで、 $EMPRESSPATH がデフォルトです。 このオプションは Empress バージョン 8.60 以降のみをサポートします。

--with-empress-bcs[=DIR]

"Empress ローカルアクセス"のサポートを有効にします。DIR は Empress の ベースインストールディレクトリで、$EMPRESSPATH がデフォルトです。 このオプションは Empress バージョン 8.60 以降のみをサポートします。

--with-birdstep[=DIR]

Birdstep サポートを有効にします。DIR は Birdstep のベースインストールディレクトリで、 /usr/local/birdstep がデフォルトです。

--with-custom-odbc[=DIR]

ユーザー定義の ODBC サポートを有効にします。DIR は ODBC のベースインストールディレクトリで、 /usr/local がデフォルトです。 CUSTOM_ODBC_LIBS が定義され、odbc.h がインクルードパスに あることを確認してください。 例えば、QNX上 の Sybase SQL Anywhere 5.5.00 では、configure スクリプトを実行する 前に以下を定義する必要があります。

   CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
   LDFLAGS=-lunix
   CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

iODBC サポートを有効にします。DIR は iODBC のベースインストールディレクトリで、 /usr/local がデフォルトです。

--with-esoob[=DIR]

Easysoft OOB サポートを有効にします。DIR は OOB のベースインストールディレクトリで、 /usr/local/easysoft/oob/client がデフォルトです。

--with-unixODBC[=DIR]

unixODBC サポートを有効にします。DIR は unixODBC のベースインストールディレクトリで、 /usr/local がデフォルトです。

--with-openlink[=DIR]

OpenLink ODBC サポートを有効にします。DIR は OpenLink のベースインストールディレクトリで、 /usr/local がデフォルトです。 これは、iODBC と同じものです。

--with-dbmaker[=DIR]

DBMaker サポートを有効にします。DIR は DBMaker のベースインストールディレクトリで、 デフォルトは最新版の DBMaker がインストールされている場所 (例えば /home/dbmaker/3.6)です。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

ただし、Windows ユーザーはこの拡張を使用するために php_odbc.dll を有効にする必要があります。


実行時設定

php.ini の設定により動作が変化します。

Unified ODBC 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
odbc.allow_persistent | "1" | INI_SYSTEM |
odbc.check_persistent | "1" | INI_SYSTEM |
odbc.max_persistent | "-1" | INI_SYSTEM |
odbc.max_links | "-1" | INI_SYSTEM |
odbc.defaultlrl | "4096" | INI_ALL |
odbc.defaultbinmode | "1" | INI_ALL |
odbc.default_cursortype | "3" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

odbc.default_db string

odbc_connect() または odbc_pconnect()でODBCデータソースが 指定されない場合に使用される ODBC データソース。

odbc.default_user string

odbc_connect() または odbc_pconnect() で名前が指定されない場合 に使用される名前。

odbc.default_pw string

odbc_connect() または odbc_pconnect() でパスワードが指定されない場合 に使用されるパスワード。

odbc.allow_persistent bool

持続的 ODBC 接続を許可するかどうか。

odbc.check_persistent bool

再利用する前に接続が有効であることを確認します。

odbc.max_persistent int

プロセス毎の持続的 ODBC 接続の最大数。

odbc.max_links int

プロセス毎の持続的接続を含む ODBC 接続の最大数。

odbc.defaultlrl int

LONG フィールドの処理。変数に返されるバイト数を指定します。 詳細は odbc_longreadlen() を参照ください。

intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。
odbc.defaultbinmode int

バイナリデータの処理モード。 詳細は odbc_binmode() を参照ください。

odbc.default_cursortype int

ODBC のカーソルモデルを制御します。 使用できる値は SQL_CURSOR_FORWARD_ONLY、 SQL_CURSOR_KEYSET_DRIVEN、 SQL_CURSOR_DYNAMIC および SQL_CURSOR_STATIC (デフォルト) です。


リソース型

この拡張モジュールでは、ODBC 接続 ID および ODBC 結果 ID の二種類のリソースを定義しています。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

ODBC_TYPE (string)
ODBC_BINMODE_PASSTHRU (int)
ODBC_BINMODE_RETURN (int)
ODBC_BINMODE_CONVERT (int)
SQL_ODBC_CURSORS (int)
SQL_CUR_USE_DRIVER (int)
SQL_CUR_USE_IF_NEEDED (int)
SQL_CUR_USE_ODBC (int)
SQL_CONCURRENCY (int)
SQL_CONCUR_READ_ONLY (int)
SQL_CONCUR_LOCK (int)
SQL_CONCUR_ROWVER (int)
SQL_CONCUR_VALUES (int)
SQL_CURSOR_TYPE (int)
SQL_CURSOR_FORWARD_ONLY (int)
SQL_CURSOR_KEYSET_DRIVEN (int)
SQL_CURSOR_DYNAMIC (int)
SQL_CURSOR_STATIC (int)
SQL_KEYSET_SIZE (int)
SQL_CHAR (int)
SQL_VARCHAR (int)
SQL_LONGVARCHAR (int)
SQL_WCHAR (int)
固定の文字列長を持つユニコード文字 Unicode character string of fixed string length.
SQL_WVARCHAR (int)
ユニコードのVARCHAR文字列
SQL_WLONGVARCHAR (int)
ユニコードのVARCHARデータ。 最大の長さは、データソース依存です。
SQL_DECIMAL (int)
SQL_NUMERIC (int)
SQL_BIT (int)
SQL_TINYINT (int)
SQL_SMALLINT (int)
SQL_INTEGER (int)
SQL_BIGINT (int)
SQL_REAL (int)
SQL_FLOAT (int)
SQL_DOUBLE (int)
SQL_BINARY (int)
SQL_VARBINARY (int)
SQL_LONGVARBINARY (int)
SQL_DATE (int)
SQL_TIME (int)
SQL_TIMESTAMP (int)
SQL_TYPE_DATE (int)
SQL_TYPE_TIME (int)
SQL_TYPE_TIMESTAMP (int)
SQL_BEST_ROWID (int)
SQL_ROWVER (int)
SQL_SCOPE_CURROW (int)
SQL_SCOPE_TRANSACTION (int)
SQL_SCOPE_SESSION (int)
SQL_NO_NULLS (int)
SQL_NULLABLE (int)
SQL_INDEX_UNIQUE (int)
SQL_INDEX_ALL (int)
SQL_ENSURE (int)
SQL_QUICK (int)
SQL_FETCH_FIRST (int)
最初の行セットを返します
SQL_FETCH_NEXT (int)
次の行セットを返します


ODBC 関数

目次

  • odbc_autocommit — 自動コミットの動作をオンまたはオフにする
  • odbc_binmode — バイナリカラムデータを処理する
  • odbc_close — ODBC 接続を閉じる
  • odbc_close_all — 全ての ODBC 接続を閉じる
  • odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
  • odbc_columns — 指定したテーブルにあるカラム名のリストを取得する
  • odbc_commit — ODBC トランザクションをコミットする
  • odbc_connect — データソースに接続する
  • odbc_connection_string_is_quoted — ODBC の接続文字列の値が、クオートされているかを調べる
  • odbc_connection_string_quote — ODBC の接続文字列をクオートする
  • odbc_connection_string_should_quote — ODBC の接続文字列を、クオートすべきかを調べる
  • odbc_cursor — カーソル名を得る
  • odbc_data_source — 利用可能なDSNについての情報を返す
  • odbc_do — odbc_exec のエイリアス
  • odbc_error — 直近のエラーコードを得る
  • odbc_errormsg — 直近のエラーメッセージを得る
  • odbc_exec — SQL文を直接実行する
  • odbc_execute — プリペアドステートメントを実行する
  • odbc_fetch_array — 連想配列として結果の行を取得する
  • odbc_fetch_into — 一行ぶんの結果を配列に取り込む
  • odbc_fetch_object — オブジェクトとして結果の行を取得する
  • odbc_fetch_row — 行を取り込む
  • odbc_field_len — フィールドの長さ (精度) を得る
  • odbc_field_name — カラム名を得る
  • odbc_field_num — カラム番号を返す
  • odbc_field_precision — odbc_field_len のエイリアス
  • odbc_field_scale — フィールドの精度を得る
  • odbc_field_type — フィールドのデータ型を返す
  • odbc_foreignkeys — 外部キーのリストを取得する
  • odbc_free_result — 結果を保持するリソースを開放する
  • odbc_gettypeinfo — データソースがサポートするデータ型についての情報を取得する
  • odbc_longreadlen — LONG カラムを処理する
  • odbc_next_result — 複数の結果が利用可能などうか確認する
  • odbc_num_fields — 結果のカラム数を返す
  • odbc_num_rows — 結果における行数を返す
  • odbc_pconnect — 持続的なデータベース接続を開く
  • odbc_prepare — 実行用に文を準備する
  • odbc_primarykeys — テーブルの主キーを取得する
  • odbc_procedurecolumns — プロシージャへのパラメータに関する情報を取得する
  • odbc_procedures — 指定したデータソースに保存されているプロシージャのリストを取得する
  • odbc_result — 結果データを得る
  • odbc_result_all — HTML テーブルとして結果を出力する
  • odbc_rollback — トランザクションをロールバックする
  • odbc_setoption — ODBC の設定を変更する
  • odbc_specialcolumns — 特殊カラムを取得する
  • odbc_statistics — テーブルに関する統計情報を取得する
  • odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する
  • odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する


自動コミットの動作をオンまたはオフにする

  • ≪ ODBC 関数
  • odbc_binmode ≫
  • PHP Manual
  • ODBC 関数
  • 自動コミットの動作をオンまたはオフにする

odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — 自動コミットの動作をオンまたはオフにする

説明

odbc_autocommit(resource $odbc, ?bool $enable = null): int|bool

自動コミットの挙動を切り替えます。

デフォルトで接続の自動コミットはオンとなっています。自動コミットを 使用不可にするのは、トランザクションを開始することと等価です。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

enable

enable が true の場合は自動コミットが可能であり、 false の場合は自動コミットが使用不可となっています。 null を渡した場合、この関数は odbc の自動コミットに関する状態を返します。

戻り値

enable パラメータに null を指定した場合、 この関数は、odbc に関する 自動コミットの状態を返します。自動コミットがオンの場合に 非ゼロ、オフの場合にゼロ、エラーを生じた場合に false を返します。

enable が null でない値の場合、 この関数は成功時に true、失敗したときに false を返します。

変更履歴

バージョン | 説明
8.3.0 | enable は、nullable になりました。

参考

  • odbc_commit() - ODBC トランザクションをコミットする
  • odbc_rollback() - トランザクションをロールバックする


バイナリカラムデータを処理する

  • ≪ odbc_autocommit
  • odbc_close ≫
  • PHP Manual
  • ODBC 関数
  • バイナリカラムデータを処理する

odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — バイナリカラムデータを処理する

説明

odbc_binmode(resource $statement, int $mode): true

バイナリカラムデータを処理する方法を制御します。 (関係するODBC SQL型: BINARY, VARBINARY, LONGVARBINARY)。 デフォルトの処理モードは、php.ini の uodbc.defaultbinmode 経由で設定できます。

バイナリ SQL データが文字データに変換される時 (ODBC_BINMODE_CONVERT)、ソースデータの 各バイト (8 ビット) は、2 つのアスキー文字で表現されます。 これらの文字は、16 進表現で数値をアスキー文字で表現したものです。 例えば、2 進数 00000001 は "01" に変換され、 11111111 は "FF" に変換されます。

BINARY と VARBINARY 型のカラムを処理する方法は binmode によって決まります。LONGVARBINARY 型のカラムを処理する方法は、 longreadlen にも依存します:

LONGVARBINARY 処理
binmode | longreadlen | 結果
ODBC_BINMODE_PASSTHRU | >0 | 通過
ODBC_BINMODE_RETURN | >0 | 通過
ODBC_BINMODE_CONVERT | >0 | 通過
ODBC_BINMODE_PASSTHRU | 0 | 通過
ODBC_BINMODE_RETURN | >0 | そのまま返す
ODBC_BINMODE_CONVERT | >0 | char として返す

odbc_fetch_into() を使用した場合、 「通過」は空文字列が対応するカラムに返されることを意味します。 odbc_result() を使用した場合、 「通過」はデータがクライアントに直接送信されることを意味します(つまり、表示されます)。

パラメータ

statement

結果 ID。

statement に 0 を指定した場合、 ここで設定した値は、新規の結果に関するデフォルト値として用いられます。

mode

mode には、以下の値が指定できます。

  • ODBC_BINMODE_PASSTHRU: BINARY データとして通過
  • ODBC_BINMODE_RETURN: そのまま返す
  • ODBC_BINMODE_CONVERT: char に変換し返す

注意: LONGVARBINARY 型のカラムを処理する方法は odbc_longreadlen() によっても影響を受けます。

戻り値

常に true を返します。


ODBC 接続を閉じる

  • ≪ odbc_binmode
  • odbc_close_all ≫
  • PHP Manual
  • ODBC 関数
  • ODBC 接続を閉じる

odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — ODBC 接続を閉じる

説明

odbc_close(resource $odbc): void

指定された接続 ID が指すデータベースサーバーへの接続を閉じます。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

戻り値

値を返しません。

注意

注意:

この関数の処理は、この接続に関してオープンされたトランザクションがある場合に失敗します。 この場合、接続はオープンされたままとなります。


全ての ODBC 接続を閉じる

  • ≪ odbc_close
  • odbc_columnprivileges ≫
  • PHP Manual
  • ODBC 関数
  • 全ての ODBC 接続を閉じる

odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — 全ての ODBC 接続を閉じる

説明

odbc_close_all(): void

odbc_close_all()は、 データベースサーバーへの全ての接続を閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

注意

注意:

この関数は、ある接続においてオープンされたトランザクションがある場合に失敗します。 この場合、この接続はオープンされたままとなります。


指定したテーブルに関するカラムおよび付随する権限のリストを取得する

  • ≪ odbc_close_all
  • odbc_columns ≫
  • PHP Manual
  • ODBC 関数
  • 指定したテーブルに関するカラムおよび付随する権限のリストを取得する

odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する

説明

odbc_columnprivileges(
resource $odbc,
?string $catalog,
string $schema,
string $table,
string $column
): resource|false

指定したテーブルに関するカラムおよび付随する権限のリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

テーブル名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

column

カラム名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

戻り値

ODBC 結果 ID を返します。失敗した場合に false を返します。 この結果 ID を使用して、カラムや関連する権限の一覧を取得します。

結果は以下のカラムを有します。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • COLUMN_NAME
  • GRANTOR
  • GRANTEE
  • PRIVILEGE
  • IS_GRANTABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, COLUMN_NAME, PRIVILEGE でソートされます。

例

例1 カラムの権限の一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$privileges = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
while (($row = odbc_fetch_array($privileges))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => test
    [COLUMN_NAME] => id
    [GRANTOR] => dbo
    [GRANTEE] => dbo
    [PRIVILEGE] => INSERT
    [IS_GRANTABLE] => YES
)


指定したテーブルにあるカラム名のリストを取得する

  • ≪ odbc_columnprivileges
  • odbc_commit ≫
  • PHP Manual
  • ODBC 関数
  • 指定したテーブルにあるカラム名のリストを取得する

odbc_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — 指定したテーブルにあるカラム名のリストを取得する

説明

odbc_columns(
resource $odbc,
?string $catalog = null,
?string $schema = null,
?string $table = null,
?string $column = null
): resource|false

指定したテーブルにあるカラム名のリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

テーブル名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

column

カラム名。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

戻り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットは以下のカラムを有しています。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • COLUMN_NAME
  • DATA_TYPE
  • TYPE_NAME
  • COLUMN_SIZE
  • BUFFER_LENGTH
  • DECIMAL_DIGITS
  • NUM_PREC_RADIX
  • NULLABLE
  • REMARKS
  • COLUMN_DEF
  • SQL_DATA_TYPE
  • SQL_DATETIME_SUB
  • CHAR_OCTET_LENGTH
  • ORDINAL_POSITION
  • IS_NULLABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, ORDINAL_POSITION でソートされます。

変更履歴

バージョン | 説明
8.0.0 | schema, table, column は、nullable になりました。

例

例1 テーブルのカラム一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');
while (($row = odbc_fetch_array($columns))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => TEST
    [COLUMN_NAME] => id
    [DATA_TYPE] => 4
    [TYPE_NAME] => int
    [COLUMN_SIZE] => 10
    [BUFFER_LENGTH] => 4
    [DECIMAL_DIGITS] => 0
    [NUM_PREC_RADIX] => 10
    [NULLABLE] => 0
    [REMARKS] =>
    [COLUMN_DEF] =>
    [SQL_DATA_TYPE] => 4
    [SQL_DATETIME_SUB] =>
    [CHAR_OCTET_LENGTH] =>
    [ORDINAL_POSITION] => 1
    [IS_NULLABLE] => NO
)

参考

  • odbc_columnprivileges() - 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
  • odbc_procedurecolumns() - プロシージャへのパラメータに関する情報を取得する


ODBC トランザクションをコミットする

  • ≪ odbc_columns
  • odbc_connect ≫
  • PHP Manual
  • ODBC 関数
  • ODBC トランザクションをコミットする

odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — ODBC トランザクションをコミットする

説明

odbc_commit(resource $odbc): bool

その接続におけるすべての実行中のトランザクションをコミットします。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。


データソースに接続する

  • ≪ odbc_commit
  • odbc_connection_string_is_quoted ≫
  • PHP Manual
  • ODBC 関数
  • データソースに接続する

odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — データソースに接続する

説明

odbc_connect(
string $dsn,
string $user,
string $password,
int $cursor_option = SQL_CUR_USE_DRIVER
): resource|false

他の ODBC 関数を使用するには、 この関数が返す接続 ID が必要となります。 異なる db や異なる権限を使用する限り、 複数の接続を同時にオープンすることができます。

いくつかの ODBC ドライバでは、 複雑なストアド・プロシージャの実行時に次のようなエラーにより失敗する可能性があります。 "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it" SQL_CUR_USE_ODBC を使用することにより、 このようなエラーを回避できる可能性があります。 また、いくつかのドライバは odbc_fetch_row() においてオプションの row_number パラメータをサポートしません。 この場合でも、SQL_CUR_USE_ODBC により解決できる可能性があります。

パラメータ

dsn

接続に使用するデータベースソース名。 あるいは、DSNではない接続文字列を使用することもできます。

user

ユーザー名。

password

パスワード。

cursor_option

この接続で使用するカーソルの型。 通常はこのパラメータは必要ありませんが、いくつかの ODBC ドライバの問題に対処する際には有用です。

次のような定数がカーソル型として定義されています。

  • SQL_CUR_USE_IF_NEEDED
  • SQL_CUR_USE_ODBC
  • SQL_CUR_USE_DRIVER

戻り値

ODBC 接続を返します。 失敗した場合に false を返します

例

例1 DSN なしの接続

<?php
// Microsoft SQL Server using the SQL Native Client 10.0 ODBC Driver - allows connection to SQL 7, 2000, 2005 and 2008
$connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);

// Microsoft Access
$connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

// Microsoft Excel
$excelFile = realpath('C:/ExcelData.xls');
$excelDir = dirname($excelFile);
$connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
?>

参考

  • 持続的な接続の場合: odbc_pconnect() - 持続的なデータベース接続を開く


ODBC の接続文字列の値が、クオートされているかを調べる

  • ≪ odbc_connect
  • odbc_connection_string_quote ≫
  • PHP Manual
  • ODBC 関数
  • ODBC の接続文字列の値が、クオートされているかを調べる

odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — ODBC の接続文字列の値が、クオートされているかを調べる

説明

odbc_connection_string_is_quoted(string $str): bool

ODBC の接続文字列の値が、適切にクオートされているかを調べます。 ODBC の接続文字列は、波括弧を使ってクオートされます。 よって、文字列中に含まれる右括弧は、 SQL文のクオートと同じように、二回繰り返すことでエスケープしなければいけません。

パラメータ

str

クオートされているかをチェックする文字列

戻り値

適切にクオートされている場合は true を返します。 そうでない場合は、false を返します。

参考

  • odbc_connection_string_quote() - ODBC の接続文字列をクオートする
  • odbc_connection_string_should_quote() - ODBC の接続文字列を、クオートすべきかを調べる


ODBC の接続文字列をクオートする

  • ≪ odbc_connection_string_is_quoted
  • odbc_connection_string_should_quote ≫
  • PHP Manual
  • ODBC 関数
  • ODBC の接続文字列をクオートする

odbc_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — ODBC の接続文字列をクオートする

説明

odbc_connection_string_quote(string $str): string

接続文字列の値を、ODBC のルールに従ってクオートします。 つまり、波括弧で文字列を囲み、右括弧はエスケープします。 この操作は、ユーザーが入力する接続文字列の値に対して常に行うべきです。 そうしないと、接続文字列をパースする際に問題が発生したり、 接続文字列に値を注入される可能性があります。

この関数は、 文字列が既にクオートされているかをチェックしませんし、 文字列にクオートが必要かどうかもチェックしないことに注意してください。 それらの用途には、それぞれ odbc_connection_string_is_quoted() と、 odbc_connection_string_should_quote() をコールしてください。

パラメータ

str

クオートされていない文字列

戻り値

波括弧で囲まれた、クオートされた文字列。 適切にエスケープも行われます。

例

例1 odbc_connection_string_quote() の例

この例は文字列をクオートし、接続文字列に追加します。 文字列がクオートされ、文字列中の右括弧もエスケープされることに注意してください。

<?php
$value = odbc_connection_string_quote("foo}bar");
$connection_string = "DSN=PHP;UserValue=$value";
echo $connection_string;
?>

上の例の出力は、 たとえば以下のようになります。

DSN=PHP;UserValue={foo}}bar}

参考

  • odbc_connection_string_is_quoted() - ODBC の接続文字列の値が、クオートされているかを調べる
  • odbc_connection_string_should_quote() - ODBC の接続文字列を、クオートすべきかを調べる


ODBC の接続文字列を、クオートすべきかを調べる

  • ≪ odbc_connection_string_quote
  • odbc_cursor ≫
  • PHP Manual
  • ODBC 関数
  • ODBC の接続文字列を、クオートすべきかを調べる

odbc_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — ODBC の接続文字列を、クオートすべきかを調べる

説明

odbc_connection_string_should_quote(string $str): bool

ODBC の接続文字列に、クオートが必要かどうかを調べます。 つまり、特別な文字が含まれているかを調べます。

この関数は、文字列が既にクオートされているかをチェックしないことに注意してください。 つまり、既にクオートされた文字列には、 この関数が true を返す文字が含まれているということです。 既にクオートされているかどうかをチェックするには、 odbc_connection_string_is_quoted() をコールしてください。

パラメータ

str

チェックする文字列

戻り値

文字列をクオートすべき場合は true を返します。 そうでない場合は、false を返します。

参考

  • odbc_connection_string_quote() - ODBC の接続文字列をクオートする
  • odbc_connection_string_is_quoted() - ODBC の接続文字列の値が、クオートされているかを調べる


カーソル名を得る

  • ≪ odbc_connection_string_should_quote
  • odbc_data_source ≫
  • PHP Manual
  • ODBC 関数
  • カーソル名を得る

odbc_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — カーソル名を得る

説明

odbc_cursor(resource $statement): string|false

指定された接続 ID に関するカーソル名を返します。 Gets the cursorname for the given result_id.

パラメータ

statement

結果 ID。

戻り値

カーソル名を文字列で返します。 失敗した場合に false を返します


利用可能なDSNについての情報を返す

  • ≪ odbc_cursor
  • odbc_do ≫
  • PHP Manual
  • ODBC 関数
  • 利用可能なDSNについての情報を返す

odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — 利用可能なDSNについての情報を返す

説明

odbc_data_source(resource $odbc, int $fetch_type): array|null|false

この関数は、有効な DSN（複数回のコールの後）のリストを返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

fetch_type

fetch_type は次のふたつの定数 SQL_FETCH_FIRST, SQL_FETCH_NEXT のうちのどちらかです。 この関数を最初にコールする際には SQL_FETCH_FIRST を、それ以降は SQL_FETCH_NEXT を使用します。

戻り値

エラー時には false、成功時には配列を返します。 最後の利用可能なDSNを取得した後は、null を返します。

例

例1 利用可能なDSNの一覧を表示する

<?php
$conn = odbc_connect('dsn', 'user', 'pass');
$dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
while ($dsn_info) {
print_r($dsn_info);
$dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [server] => dsn
    [description] => ODBC Driver 17 for SQL Server
)
Array
(
    [server] => other_dsn
    [description] => Microsoft Access Driver (*.mdb, *.accdb)
)


odbc_exec のエイリアス

  • ≪ odbc_data_source
  • odbc_error ≫
  • PHP Manual
  • ODBC 関数
  • odbc_exec のエイリアス

odbc_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — odbc_exec() のエイリアス

説明

この関数は次の関数のエイリアスです。 odbc_exec().


直近のエラーコードを得る

  • ≪ odbc_do
  • odbc_errormsg ≫
  • PHP Manual
  • ODBC 関数
  • 直近のエラーコードを得る

odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — 直近のエラーコードを得る

説明

odbc_error(?resource $odbc = null): string

6 桁の ODBC ステートを返します。エラーがない場合には、空の文字列を返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

戻り値

odbc が指定された場合、 その接続の直近の状態が返されます。そうでない場合、 他の接続の直近の状態が返されます。

この関数の戻り値が意味を持つのは、直近の odbc クエリが失敗した場合 (すなわち odbc_exec() が false を返した場合) のみです。

変更履歴

バージョン | 説明
8.0.0 | odbc は、nullable になりました。

参考

  • odbc_errormsg() - 直近のエラーメッセージを得る
  • odbc_exec() - SQL文を直接実行する


直近のエラーメッセージを得る

  • ≪ odbc_error
  • odbc_exec ≫
  • PHP Manual
  • ODBC 関数
  • 直近のエラーメッセージを得る

odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — 直近のエラーメッセージを得る

説明

odbc_errormsg(?resource $odbc = null): string

直近の ODBC エラーメッセージを含む文字列を返します。 エラーが発生していない場合は、空の文字列を返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

戻り値

odbc が指定された場合、 その接続の直近の状態が返されます。さもなくば、他の接続の直近の状態が返されます。

この関数の戻り値が意味を持つのは、直近の odbc クエリが失敗した場合 (すなわち odbc_exec() が false を返した場合) のみです。

変更履歴

バージョン | 説明
8.0.0 | odbc は、nullable になりました。

参考

  • odbc_error() - 直近のエラーコードを得る
  • odbc_exec() - SQL文を直接実行する


SQL文を直接実行する

  • ≪ odbc_errormsg
  • odbc_execute ≫
  • PHP Manual
  • ODBC 関数
  • SQL文を直接実行する

odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — SQL文を直接実行する

説明

odbc_exec(resource $odbc, string $query): resource|false

SQL 命令を データベースサーバーに送ります。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

query

SQL 文。

戻り値

SQL コマンドの実行に成功した場合には、 ODBC 結果 ID を返します。エラー時には、falseを返します。

変更履歴

バージョン | 説明
8.0.0 | flags は削除されました。

参考

  • odbc_prepare() - 実行用に文を準備する
  • odbc_execute() - プリペアドステートメントを実行する


プリペアドステートメントを実行する

  • ≪ odbc_exec
  • odbc_fetch_array ≫
  • PHP Manual
  • ODBC 関数
  • プリペアドステートメントを実行する

odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — プリペアドステートメントを実行する

説明

odbc_execute(resource $statement, array $params = []): bool

odbc_prepare() で準備された命令を実行します。

パラメータ

statement

odbc_prepare() で取得した結果 ID リソース。

params

プリペアドステートメントの中のプレースホルダが、 params 内のパラメータで順に置き換えられます。 この関数をコールした際に、配列の要素は文字列に変換されます。

params の中でシングルクォートで括られたデータがある場合、 それはファイル名と解釈されます。そのファイルの内容が、 該当するプレースホルダのデータとしてデータベースサーバーに送信されます。

シングルクォートで括られたデータを純粋に文字列として使用したい場合は、 空白などの別の文字を前後に付加する必要があります。 それにより、パラメータがファイル名とみなされることがなくなります (もしこのオプションが不要なら、別の仕組み、たとえば odbc_exec() で直接クエリを実行するなどを使用する必要があります)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 odbc_execute() および odbc_prepare() の例

次のコードは、myproc の 3 つのパラメータがすべて IN パラメータである場合にのみ $success が true となります。

<?php
$a = 1;
$b = 2;
$c = 3;
$stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)');
$success = odbc_execute($stmt, array($a, $b, $c));
?>

INOUT や OUT パラメータを用いるストアドプロシージャをコールしたい場合は、 各データベース専用の拡張モジュール (たとえば Oracle なら oci8) を使うようにしましょう。

参考

  • odbc_prepare() - 実行用に文を準備する


連想配列として結果の行を取得する

  • ≪ odbc_execute
  • odbc_fetch_into ≫
  • PHP Manual
  • ODBC 関数
  • 連想配列として結果の行を取得する

odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — 連想配列として結果の行を取得する

説明

odbc_fetch_array(resource $statement, int $row = -1): array|false

ODBC クエリから、連想配列を取得します。

パラメータ

statement

odbc_exec() の結果リソース。

row

どの行番号を取得するのかを任意で指定する。

戻り値

取得した行に対応する配列を返します。もう行がない場合には false を返します。

注意

注意: この関数は、DBMaker、IBM DB2 あるいは UnixODBC のサポートを有効にして コンパイルした場合に使用可能です。

参考

  • odbc_fetch_row() - 行を取り込む
  • odbc_fetch_object() - オブジェクトとして結果の行を取得する
  • odbc_num_rows() - 結果における行数を返す


一行ぶんの結果を配列に取り込む

  • ≪ odbc_fetch_array
  • odbc_fetch_object ≫
  • PHP Manual
  • ODBC 関数
  • 一行ぶんの結果を配列に取り込む

odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — 一行ぶんの結果を配列に取り込む

説明

odbc_fetch_into(resource $statement, array &$array, int $row = 0): int|false

結果の行を array に取得します。

パラメータ

statement

結果リソース。

array

結果の配列。型変換によってい配列型となるので、どんな型であっても構いません。 この配列には、添字 0 から始まるカラム番号が代入されます。

row

行番号。

戻り値

結果におけるカラム番号を返します。また、エラーの場合に false を返します。

例

例1 odbc_fetch_into() の例

<?php
$rc = odbc_fetch_into($res_id, $my_array);
?>

あるいは

<?php
$rc = odbc_fetch_into($res_id, $my_array, 2);
?>


オブジェクトとして結果の行を取得する

  • ≪ odbc_fetch_into
  • odbc_fetch_row ≫
  • PHP Manual
  • ODBC 関数
  • オブジェクトとして結果の行を取得する

odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — オブジェクトとして結果の行を取得する

説明

odbc_fetch_object(resource $statement, int $row = -1): stdClass|false

ODBC クエリから、オブジェクトを取得します。

パラメータ

statement

odbc_exec() の結果リソース。

row

どの行番号を取得するのかを任意で指定する。

戻り値

取得した行に対応するオブジェクトを返します。もう行がない場合には false を返します。

注意

注意: この関数は、DBMaker、IBM DB2 あるいは UnixODBC のサポートを有効にして コンパイルした場合に使用可能です。

参考

  • odbc_fetch_row() - 行を取り込む
  • odbc_fetch_array() - 連想配列として結果の行を取得する
  • odbc_num_rows() - 結果における行数を返す


行を取り込む

  • ≪ odbc_fetch_object
  • odbc_field_len ≫
  • PHP Manual
  • ODBC 関数
  • 行を取り込む

odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — 行を取り込む

説明

odbc_fetch_row(resource $statement, ?int $row = null): bool

odbc_do() や
odbc_exec() から返された行データを取得します。
odbc_fetch_row() がコールされた後、この行のフィールドは、
odbc_result() でアクセス可能となります。

パラメータ

statement

結果 ID。

row

row が指定されない場合、 odbc_fetch_row() は、 結果セットにおける次の行を取り込もうと試みます。 row を指定した odbc_fetch_row() のコールと指定しないコールを混用することができます。

結果を複数回走査したい場合、odbc_fetch_row() を row に 1 を指定してコールし、 続いて結果を再度見るために row を指定せずに odbc_fetch_row() を実行しつづけます。 行を番号で取り込むことをドライバがサポートしていない場合、 row パラメータは無視されます。

戻り値

行があった場合には true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | row は、nullable になりました。


フィールドの長さ (精度) を得る

  • ≪ odbc_fetch_row
  • odbc_field_name ≫
  • PHP Manual
  • ODBC 関数
  • フィールドの長さ (精度) を得る

odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — フィールドの長さ (精度) を得る

説明

odbc_field_len(resource $statement, int $field): int|false

指定した ODBC 結果 ID の番号で参照されるフィールドの長さを取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。フィールド番号は 1 から始まります。

戻り値

フィールドの長さ、あるいはエラー時に false を返します。

参考

  • 浮動小数点の精度を得るには odbc_field_scale() - フィールドの精度を得る


カラム名を得る

  • ≪ odbc_field_len
  • odbc_field_num ≫
  • PHP Manual
  • ODBC 関数
  • カラム名を得る

odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — カラム名を得る

説明

odbc_field_name(resource $statement, int $field): string|false

指定された ODBC 結果 ID において指定されたカラム番号にあるフィールドの名前を取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。フィールド番号は、1 から始まります。

戻り値

フィールド名を表す文字列、あるいはエラー時に false を返します。


カラム番号を返す

  • ≪ odbc_field_name
  • odbc_field_precision ≫
  • PHP Manual
  • ODBC 関数
  • カラム番号を返す

odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — カラム番号を返す

説明

odbc_field_num(resource $statement, string $field): int|false

指定したODBC 結果 ID におけるフィールド名に対応するカラムスロットの数を取得します。

パラメータ

statement

結果 ID。

field

フィールド名。

戻り値

フィールド番号、あるいはエラー時に false を返します。 フィールド番号は、1 から始まります。


odbc_field_len のエイリアス

  • ≪ odbc_field_num
  • odbc_field_scale ≫
  • PHP Manual
  • ODBC 関数
  • odbc_field_len のエイリアス

odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — odbc_field_len() のエイリアス

説明

この関数は次の関数のエイリアスです。 odbc_field_len().

参考

  • 浮動小数点の精度を得るには odbc_field_scale() - フィールドの精度を得る


フィールドの精度を得る

  • ≪ odbc_field_precision
  • odbc_field_type ≫
  • PHP Manual
  • ODBC 関数
  • フィールドの精度を得る

odbc_field_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — フィールドの精度を得る

説明

odbc_field_scale(resource $statement, int $field): int|false

指定した ODBC 結果 ID の番号で指定したフィールドの精度を取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。 フィールド番号は、1 から始まります。

戻り値

フィールド番号、あるいはエラー時に false を返します。


フィールドのデータ型を返す

  • ≪ odbc_field_scale
  • odbc_foreignkeys ≫
  • PHP Manual
  • ODBC 関数
  • フィールドのデータ型を返す

odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — フィールドのデータ型を返す

説明

odbc_field_type(resource $statement, int $field): string|false

指定された ODBC 結果 ID において指定番号で参照されるフィールドの SQL 型を取得します。

パラメータ

statement

結果 ID。

field

フィールド番号。フィールド番号は 1 から始まります。

戻り値

フィールドの型を表す文字列、あるいはエラー時に false を返します。


外部キーのリストを取得する

  • ≪ odbc_field_type
  • odbc_free_result ≫
  • PHP Manual
  • ODBC 関数
  • 外部キーのリストを取得する

odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — 外部キーのリストを取得する

説明

odbc_foreignkeys(
resource $odbc,
?string $pk_catalog,
string $pk_schema,
string $pk_table,
string $fk_catalog,
string $fk_schema,
string $fk_table
): resource|false

指定したテーブルの外部キーのリスト、 または指定したテーブルの主キーを参照する他のテーブルの外部キーのリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

pk_catalog

主キーテーブルのカタログ (ODBC 2 の用語では '修飾子')

pk_schema

主キーテーブルのスキーマ(ODBC 2 の用語では '所有者')

pk_table

主キーのテーブル。

fk_catalog

外部キーテーブルのカタログ (ODBC 2 の用語では '修飾子')

fk_schema

外部キーテーブルのスキーマ(ODBC 2 の用語では '所有者')

fk_table

外部キーのテーブル。

戻り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果は、以下のようなカラムを持つものとなります。

  • PKTABLE_CAT
  • PKTABLE_SCHEM
  • PKTABLE_NAME
  • PKCOLUMN_NAME
  • FKTABLE_CAT
  • FKTABLE_SCHEM
  • FKTABLE_NAME
  • FKCOLUMN_NAME
  • KEY_SEQ
  • UPDATE_RULE
  • DELETE_RULE
  • FK_NAME
  • PK_NAME
  • DEFERRABILITY
ドライバは追加のカラムを返すことが出来ます。

プライマリーキーと関連がある外部キーが指定された場合、 結果セットは FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, KEY_SEQ でソートされます。 外部キーと関連がある主キーが指定された場合、 結果セットは PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME, KEY_SEQ でソートされます。

pk_table がテーブル名を有している場合、 odbc_foreignkeys() は指定したテーブルの主キー およびそのキーを参照する全ての外部キーのリストを結果として返します。

fk_table がテーブル名を有している場合、 odbc_foreignkeys() は指定したテーブルにある全ての 外部キーおよびそのキーが参照する(他のテーブルの)主キーのリストを 結果として返します。

pk_table および fk_table が共にテーブル名を有している場合、 odbc_foreignkeys() は pk_table で指定されたテーブルの主キーを参照する fk_table で指定されたテーブルの外部キーを返します。 返されるキーは最大でも一つだけです。

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する
  • odbc_primarykeys() - テーブルの主キーを取得する


結果を保持するリソースを開放する

  • ≪ odbc_foreignkeys
  • odbc_gettypeinfo ≫
  • PHP Manual
  • ODBC 関数
  • 結果を保持するリソースを開放する

odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — 結果を保持するリソースを開放する

説明

odbc_free_result(resource $statement): true

結果を保持するリソースを開放します。

odbc_free_result()は、スクリプトのメモリ消費量が 多すぎることが懸念される場合にのみコールする必要があります。 全ての結果保持用メモリは、スクリプト実行が終了した際に自動的に開放されます。

パラメータ

statement

結果 ID。

戻り値

常に true を返します。

注意

注意:

自動コミットが無効（odbc_autocommit() を 参照ください）な時にコミットの前に odbc_free_result() をコールすると、全ての 未解決のトランザクションは、ロールバックされます。


データソースがサポートするデータ型についての情報を取得する

  • ≪ odbc_free_result
  • odbc_longreadlen ≫
  • PHP Manual
  • ODBC 関数
  • データソースがサポートするデータ型についての情報を取得する

odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — データソースがサポートするデータ型についての情報を取得する

説明

odbc_gettypeinfo(resource $odbc, int $data_type = 0): resource|false

データソースがサポートするデータ型についての情報を取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

data_type

データ型。単一のデータ型に情報を制限するために使用します。

戻り値

ODBC 結果 ID または失敗した場合に false を返します。

結果は、以下のようなカラムを持つものとなります。

  • TYPE_NAME
  • DATA_TYPE
  • PRECISION
  • LITERAL_PREFIX
  • LITERAL_SUFFIX
  • CREATE_PARAMS
  • NULLABLE
  • CASE_SENSITIVE
  • SEARCHABLE
  • UNSIGNED_ATTRIBUTE
  • MONEY
  • AUTO_INCREMENT
  • LOCAL_TYPE_NAME
  • MINIMUM_SCALE
  • MAXIMUM_SCALE

結果セットは、DATA_TYPE および TYPE_NAME でソートされます。


LONG カラムを処理する

  • ≪ odbc_gettypeinfo
  • odbc_next_result ≫
  • PHP Manual
  • ODBC 関数
  • LONG カラムを処理する

odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — LONG カラムを処理する

説明

odbc_longreadlen(resource $statement, int $length): true

LONG および LONGVARBINARY のカラムを処理する方法を制御します。 デフォルトの長さは、php.ini の uodbc.defaultlrl 経由で設定できます。

パラメータ

statement

結果 ID。

length

PHP に返されるバイト数は、パラメータ length により制御されます。 これを 0 をセットした場合、ロングカラムデータは、 odbc_result() で取得する際に、クライアントにそのまま渡されます(つまり、表示されます)。

戻り値

常に true を返します。

注意

注意:

LONGVARBINARY カラムの処理は、odbc_binmode() にも影響を受けます。


複数の結果が利用可能などうか確認する

  • ≪ odbc_longreadlen
  • odbc_num_fields ≫
  • PHP Manual
  • ODBC 関数
  • 複数の結果が利用可能などうか確認する

odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — 複数の結果が利用可能などうか確認する

説明

odbc_next_result(resource $statement): bool

まだ結果セットが存在して odbc_fetch_array()、odbc_fetch_row()、 odbc_result() などで次の結果セットにアクセスできるかどうかを調べます。

パラメータ

statement

結果 ID。

戻り値

結果セットがまだある場合に true、それ以外の場合に false を返します。

例

例1 odbc_next_result()

<?php
$r_Connection = odbc_connect($dsn, $username, $password);

$s_SQL = <<<END_SQL
SELECT 'A'
SELECT 'B'
SELECT 'C'
END_SQL;

$r_Results = odbc_exec($r_Connection, $s_SQL);

$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "最初の結果セットを出力します";
var_dump($a_Row1, $a_Row2);

echo "二番目の結果セットを取得します ";
var_dump(odbc_next_result($r_Results));

$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "二番目の結果セットを出力します ";
var_dump($a_Row1, $a_Row2);

echo "三番目の結果セットを取得します ";
var_dump(odbc_next_result($r_Results));

$a_Row1 = odbc_fetch_array($r_Results);
$a_Row2 = odbc_fetch_array($r_Results);
echo "三番目の結果セットを出力します ";
var_dump($a_Row1, $a_Row2);

echo "四番目の結果セットを調べてみます ";
var_dump(odbc_next_result($r_Results));
?>

上の例の出力は以下となります。

最初の結果セットを出力します array(1) {
  ["A"]=>
  string(1) "A"
}
bool(false)
二番目の結果セットを取得します bool(true)
二番目の結果セットを出力します array(1) {
  ["B"]=>
  string(1) "B"
}
bool(false)
三番目の結果セットを取得します bool(true)
三番目の結果セットを出力します array(1) {
  ["C"]=>
  string(1) "C"
}
bool(false)
四番目の結果セットを調べてみます bool(false)


結果のカラム数を返す

  • ≪ odbc_next_result
  • odbc_num_rows ≫
  • PHP Manual
  • ODBC 関数
  • 結果のカラム数を返す

odbc_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — 結果のカラム数を返す

説明

odbc_num_fields(resource $statement): int

ODBC 結果におけるフィールド (カラム) の数を取得します。

パラメータ

statement

odbc_exec() が返す結果 ID。

戻り値

フィールド数、あるいはエラー時に -1 を返します。


結果における行数を返す

  • ≪ odbc_num_fields
  • odbc_pconnect ≫
  • PHP Manual
  • ODBC 関数
  • 結果における行数を返す

odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — 結果における行数を返す

説明

odbc_num_rows(resource $statement): int

ODBC 結果における行の数を取得します。 INSERT、UPDATE および DELETE 命令に関しては、 odbc_num_rows() は、変更された行の数を返します。 SELECT 文の場合、この関数は利用可能な行の数を返します。

パラメータ

statement

odbc_exec() が返す結果 ID。

戻り値

ODBC 結果における行の数を返します。 この関数は、エラー時に-1を返します。

注意

注意:

SELECT の後に利用可能な行の数を定義するために odbc_num_rows() を使用した場合、 多くのドライバにおいて、-1 が返されます。


持続的なデータベース接続を開く

  • ≪ odbc_num_rows
  • odbc_prepare ≫
  • PHP Manual
  • ODBC 関数
  • 持続的なデータベース接続を開く

odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — 持続的なデータベース接続を開く

説明

odbc_pconnect(
string $dsn,
string $user,
string $password,
int $cursor_option = SQL_CUR_USE_DRIVER
): resource|false

持続的なデータベース接続を開きます。

この関数は odbc_connect() に非常に似ていますが、 スクリプトが終了した時に接続が閉じられないという点が異なります。 同じ dsn、user、 password の組み合わせ （odbc_connect() および odbc_pconnect() による）接続の場合は、 持続的な接続を再利用することが可能です。

パラメータ

詳細は odbc_connect() を参照ください。

戻り値

ODBC 接続 ID を返します。 失敗した場合に false を返します

注意

注意: 持続的な接続は、PHP を CGI プログラムとして使用する場合には使用できません。

参考

  • odbc_connect() - データソースに接続する
  • 持続的データベース接続


実行用に文を準備する

  • ≪ odbc_pconnect
  • odbc_primarykeys ≫
  • PHP Manual
  • ODBC 関数
  • 実行用に文を準備する

odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — 実行用に文を準備する

説明

odbc_prepare(resource $odbc, string $query): resource|false

実行用に文を準備します。 結果 ID は、この後 odbc_execute() で命令を実行する際に使用することができます。

(IBM DB2、MS SQL Server および Oracle のように) ストアドプロシージャが利用可能で、ODBC 仕様で定義されている IN、INOUT および OUT が利用できるものもあります。 しかし、Unified ODBC ドライバでは現在 IN 型のパラメータしかサポートしていません。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

query

準備するクエリ文字列。

戻り値

SQL コマンドの準備に成功した場合は、ODBC 結果 ID を返します。 エラー時には、false を返します。

例

例1 odbc_execute() および odbc_prepare() の例

次のコードは、myproc の 3 つのパラメータがすべて IN パラメータである場合にのみ $success が true となります。

<?php
$a = 1;
$b = 2;
$c = 3;
$stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)');
$success = odbc_execute($stmt, array($a, $b, $c));
?>

INOUT や OUT パラメータを用いるストアドプロシージャをコールしたい場合は、 各データベース専用の拡張モジュール (たとえば Oracle なら oci8) を使うようにしましょう。

参考

  • odbc_execute() - プリペアドステートメントを実行する


テーブルの主キーを取得する

  • ≪ odbc_prepare
  • odbc_procedurecolumns ≫
  • PHP Manual
  • ODBC 関数
  • テーブルの主キーを取得する

odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — テーブルの主キーを取得する

説明

odbc_primarykeys(
resource $odbc,
?string $catalog,
string $schema,
string $table
): resource|false

テーブルの主キーを有するカラムの名前を取得する際に使用可能な結果 ID を返します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。

table

戻り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果は以下のカラムを有します。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • COLUMN_NAME
  • KEY_SEQ
  • PK_NAME
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, KEY_SEQ でソートされます。

例

例1 プライマリーキーの一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');
while (($row = odbc_fetch_array($primarykeys))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => TEST
    [COLUMN_NAME] => id
    [KEY_SEQ] => 1
    [PK_NAME] => PK__TEST__3213E83FE141F843
)

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する
  • odbc_foreignkeys() - 外部キーのリストを取得する


プロシージャへのパラメータに関する情報を取得する

  • ≪ odbc_primarykeys
  • odbc_procedures ≫
  • PHP Manual
  • ODBC 関数
  • プロシージャへのパラメータに関する情報を取得する

odbc_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — プロシージャへのパラメータに関する情報を取得する

説明

odbc_procedurecolumns(
resource $odbc,
?string $catalog = null,
?string $schema = null,
?string $procedure = null,
?string $column = null
): resource|false

プロシージャへのパラメータに関する情報を取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

procedure

プロシージャ。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

column

カラム。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

戻り値

指定したプロシージャに関して入出力パラメータのリストとその結果を構成するカラムを返します。 ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • PROCEDURE_CAT
  • PROCEDURE_SCHEM
  • PROCEDURE_NAME
  • COLUMN_NAME
  • COLUMN_TYPE
  • DATA_TYPE
  • TYPE_NAME
  • COLUMN_SIZE
  • BUFFER_LENGTH
  • DECIMAL_DIGITS
  • NUM_PREC_RADIX
  • NULLABLE
  • REMARKS
  • COLUMN_DEF
  • SQL_DATA_TYPE
  • SQL_DATETIME_SUB
  • CHAR_OCTET_LENGTH
  • ORDINAL_POSITION
  • IS_NULLABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME, COLUMN_TYPE でソートされます。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 この関数は引数をひとつ、または5個指定した場合のみ、呼び出すことが可能でした。

例

例1 プロシージャーのカラムを表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');
while (($row = odbc_fetch_array($columns))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [PROCEDURE_CAT] => TutorialDB
    [PROCEDURE_SCHEM] => dbo
    [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
    [COLUMN_NAME] => @SalesPerson
    [COLUMN_TYPE] => 1
    [DATA_TYPE] => -9
    [TYPE_NAME] => nvarchar
    [COLUMN_SIZE] => 50
    [BUFFER_LENGTH] => 100
    [DECIMAL_DIGITS] =>
    [NUM_PREC_RADIX] =>
    [NULLABLE] => 1
    [REMARKS] =>
    [COLUMN_DEF] =>
    [SQL_DATA_TYPE] => -9
    [SQL_DATETIME_SUB] =>
    [CHAR_OCTET_LENGTH] => 100
    [ORDINAL_POSITION] => 1
    [IS_NULLABLE] => YES
)

参考

  • odbc_columns() - 指定したテーブルにあるカラム名のリストを取得する


指定したデータソースに保存されているプロシージャのリストを取得する

  • ≪ odbc_procedurecolumns
  • odbc_result ≫
  • PHP Manual
  • ODBC 関数
  • 指定したデータソースに保存されているプロシージャのリストを取得する

odbc_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — 指定したデータソースに保存されているプロシージャのリストを取得する

説明

odbc_procedures(
resource $odbc,
?string $catalog = null,
?string $schema = null,
?string $procedure = null
): resource|false

指定した範囲の全てのプロシージャのリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

procedure

名前。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

戻り値

情報を含む ODBC 結果 ID を返します。 失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • PROCEDURE_CAT
  • PROCEDURE_SCHEM
  • PROCEDURE_NAME
  • NUM_INPUT_PARAMS
  • NUM_OUTPUT_PARAMS
  • NUM_RESULT_SETS
  • REMARKS
  • PROCEDURE_TYPE
ドライバは追加のカラムを返すことが出来ます。

結果セットは PROCEDURE_CAT, PROCEDURE_SCHEMA, PROCEDURE_NAME でソートされます。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 この関数は引数をひとつ、または4個指定した場合のみ、呼び出すことが可能でした。

例

例1 データベースのプロシージャ一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$procedures = odbc_procedures($conn, $catalog, $schema, '%');
while (($row = odbc_fetch_array($procedures))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [PROCEDURE_CAT] => TutorialDB
    [PROCEDURE_SCHEM] => dbo
    [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
    [NUM_INPUT_PARAMS] => -1
    [NUM_OUTPUT_PARAMS] => -1
    [NUM_RESULT_SETS] => -1
    [REMARKS] =>
    [PROCEDURE_TYPE] => 2
)

参考

  • odbc_procedurecolumns() - プロシージャへのパラメータに関する情報を取得する
  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する


結果データを得る

  • ≪ odbc_procedures
  • odbc_result_all ≫
  • PHP Manual
  • ODBC 関数
  • 結果データを得る

odbc_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — 結果データを得る

説明

odbc_result(resource $statement, string|int $field): string|bool|null

結果データを取得します。

パラメータ

statement

ODBC リソース。

field

取得するフィールド。 カラム番号を表す整数またはフィールド名を表す文字列のどちらを指定できます。

戻り値

フィールドの内容を表す文字列を返します。エラー時には false、NULL データの場合は null、そしてバイナリデータの場合は true を返します。

例

最初の odbc_result() コールにより、クエリー結果の 現在のレコードにおける 3 番目のフィールドの値が返されます。 2 番目の odbc_result() コールにより、クエリーの 結果の現在のレコードにおける "val" というフィールド名のフィールドの 値を返します。あるフィールドのカラム番号パラメータが 1 より小さいか 現在のレコードのカラム(またはフィールド)の数を超える場合、 エラーを生じます。同様に、クエリーを行ったテーブルのフィールド名には ない名前をフィールドとして指定した場合にもエラーを生じます。

例1 odbc_result() の例

<?php
$item_3 = odbc_result($Query_ID, 3);
$item_val = odbc_result($Query_ID, "val");
?>

注意

フィールドインデックスは 1 から始まります。 バイナリまたはロングカラムデータの返し方に関しては、 odbc_binmode() および odbc_longreadlen() を参照ください。


HTML テーブルとして結果を出力する

  • ≪ odbc_result
  • odbc_rollback ≫
  • PHP Manual
  • ODBC 関数
  • HTML テーブルとして結果を出力する

odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — HTML テーブルとして結果を出力する

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

odbc_result_all(resource $statement, string $format = ""): int|false

odbc_exec() により作成された結果 ID から全ての行を出力します。結果は、HTML テーブル形式で出力されます。 データはエスケープされません。

この関数は、本番環境で使うことを想定していません。 つまり、開発中に結果セットを素早く描画させるためだけに使うものだということです。

パラメータ

statement

結果 ID。

format

テーブルのフォーマット指定。

戻り値

成功の場合に結果の行数、エラーの場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。


トランザクションをロールバックする

  • ≪ odbc_result_all
  • odbc_setoption ≫
  • PHP Manual
  • ODBC 関数
  • トランザクションをロールバックする

odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — トランザクションをロールバックする

説明

odbc_rollback(resource $odbc): bool

この接続における全ての未解決の命令をロールバックします。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。


ODBC の設定を変更する

  • ≪ odbc_rollback
  • odbc_specialcolumns ≫
  • PHP Manual
  • ODBC 関数
  • ODBC の設定を変更する

odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — ODBC の設定を変更する

説明

odbc_setoption(
resource $odbc,
int $which,
int $option,
int $value
): bool

この関数により特定の接続またはクエリー結果に関する ODBC オプションを変更することが可能となります。この関数は、気まぐれな ODBC ドライバの問題に対処する際の道具として作成されたものです。自分が ODBC プログラマであり、様々なオプションが有する効果を理解している場合にのみこの関数を使用するべきでしょう。 使用可能な全てのオプションおよび値を理解するためには、良い ODBC リファレンスが必要です。ドライバーのバージョンが違うと、 サポートされるオプションも異なります。

この関数の効果は ODBC ドライバに依存する可能性があるので、 一般に公開するスクリプトでは、この関数の使用は避けましょう。 また、いくつかの ODBC オプションはこの関数では利用できません。 それは、これらを接続の確立またはクエリの準備の前に設定する必要があるからです。 しかし、特定の業務において自分の上司が商用製品の使用を指示しなかったために PHP を使用する場合、このことは実際的な問題となります。

パラメータ

odbc

設定を変更する接続 ID または 結果 ID。SQLSetConnectOption() の場合、これは接続 ID です。 SQLSetStmtOption() の場合、これは結果 ID です。

which

使用する ODBC 関数。 値は SQLSetConnectOption() の場合 1、 SQLSetStmtOption() の場合 2 である必要があります。

option

設定するオプション。

value

指定した option の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 odbc_setoption() の例

<?php
// 1. SQLSetConnectOption() のオプション 102 は SQL_AUTOCOMMIT です。
// SQL_AUTOCOMMIT の値 1 は SQL_AUTOCOMMIT_ON です。
// この例は odbc_autocommit($conn, true); と同じ結果
// となります。

odbc_setoption($conn, 1, 102, 1);

// 2. SQLSetStmtOption() のオプション 0 は SQL_QUERY_TIMEOUT です。
// この例は 30 秒後に時間切れとなるクエリーを設定します。

$result = odbc_prepare($conn, $sql);
odbc_setoption($result, 2, 0, 30);
odbc_execute($result);
?>


特殊カラムを取得する

  • ≪ odbc_setoption
  • odbc_statistics ≫
  • PHP Manual
  • ODBC 関数
  • 特殊カラムを取得する

odbc_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — 特殊カラムを取得する

説明

odbc_specialcolumns(
resource $odbc,
int $type,
?string $catalog,
string $schema,
string $table,
int $scope,
int $nullable
): resource|false

テーブルのレコードを特定する最適なカラムの組合せ、 またはレコードの値がトランザクションにより更新される際に自動的に更新されるカラムを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

type
引数 type が SQL_BEST_ROWID の場合、 odbc_specialcolumns() はテーブルの各レコードを特定するカラムを返します。 引数 type が SQL_ROWVER の場合、 odbc_specialcolumns() はカラムから値を取得する ことにより指定したテーブルでレコードを特定できる最適なカラムまたはカラムの組を返します。
catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。

table

テーブル。

scope

スコープ。これは結果セットを並べかえる際に使用します。 SQL_SCOPE_CURROW, SQL_SCOPE_TRANSACTION, SQL_SCOPE_SESSION のいずれかを指定します。

nullable

NULL を持つ特別なカラムを返却するかどうかを指定します。 SQL_NO_NULLS, SQL_NULLABLE のいずれかを指定します。

戻り値

ODBC 結果 ID または失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • SCOPE
  • COLUMN_NAME
  • DATA_TYPE
  • TYPE_NAME
  • COLUMN_SIZE
  • BUFFER_LENGTH
  • DECIMAL_DIGITS
  • PSEUDO_COLUMN
ドライバは追加のカラムを返すことが出来ます。

結果セットは SCOPE でソートされます。

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する


テーブルに関する統計情報を取得する

  • ≪ odbc_specialcolumns
  • odbc_tableprivileges ≫
  • PHP Manual
  • ODBC 関数
  • テーブルに関する統計情報を取得する

odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — テーブルに関する統計情報を取得する

説明

odbc_statistics(
resource $odbc,
?string $catalog,
string $schema,
string $table,
int $unique,
int $accuracy
): resource|false

テーブルおよびインデックスに関する統計情報を取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。

table

テーブル名。

unique

インデックスのタイプ。 SQL_INDEX_UNIQUE, SQL_INDEX_ALL のいずれかを指定します。

accuracy

SQL_ENSURE, SQL_QUICK のいずれかを指定します。 後者は、サーバーで利用できる場合に限り、CARDINALITY と PAGES をドライバが取得するように要求します。

戻り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • NON_UNIQUE
  • INDEX_QUALIFIER
  • INDEX_NAME
  • TYPE
  • ORDINAL_POSITION
  • COLUMN_NAME
  • ASC_OR_DESC
  • CARDINALITY
  • PAGES
  • FILTER_CONDITION
ドライバは追加のカラムを返すことが出来ます。

結果セットは NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION でソートされます。

例

例1 テーブルの統計情報を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);
while (($row = odbc_fetch_array($statistics))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => TutorialDB
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => TEST
    [NON_UNIQUE] =>
    [INDEX_QUALIFIER] =>
    [INDEX_NAME] =>
    [TYPE] => 0
    [ORDINAL_POSITION] =>
    [COLUMN_NAME] =>
    [ASC_OR_DESC] =>
    [CARDINALITY] => 15
    [PAGES] => 3
    [FILTER_CONDITION] =>
)

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する


各テーブルのリストおよび関連する権限のリストを取得する

  • ≪ odbc_statistics
  • odbc_tables ≫
  • PHP Manual
  • ODBC 関数
  • 各テーブルのリストおよび関連する権限のリストを取得する

odbc_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する

説明

odbc_tableprivileges(
resource $odbc,
?string $catalog,
string $schema,
string $table
): resource|false

指定した範囲にあるテーブルおよび各テーブルに関連する権限のリストを取得します。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

名前。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

戻り値

ODBC 結果 ID を返します。失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • GRANTOR
  • GRANTEE
  • PRIVILEGE
  • IS_GRANTABLE
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, PRIVILEGE, GRANTEE でソートされます。

例

例1 テーブルの権限を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');
while (($row = odbc_fetch_array($privileges))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => SalesOrders
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => Orders
    [GRANTOR] => dbo
    [GRANTEE] => dbo
    [PRIVILEGE] => DELETE
    [IS_GRANTABLE] => YES
)

参考

  • odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する


指定したデータソースに保存されたテーブルの名前のリストを取得する

  • ≪ odbc_tableprivileges
  • PDO ≫
  • PHP Manual
  • ODBC 関数
  • 指定したデータソースに保存されたテーブルの名前のリストを取得する

odbc_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する

説明

odbc_tables(
resource $odbc,
?string $catalog = null,
?string $schema = null,
?string $table = null,
?string $types = null
): resource|false

指定した範囲の全てのテーブルリストを得ます。

限定子、所有者、テーブル名を数えるために、 catalog、schema、 table、table_type について以下のような特別な記号が使用可能です。

  • catalog がパーセント記号 (%) のみで、 schema および table が空文字列であった場合、結果にはそのデータソースに関する 有効な限定子のリスト (null を有する TABLE_QUALIFIER カラム以外の 全てのカラム)が含まれます。
  • schema がパーセント記号 (%) のみで、 catalog および table が空文字列の場合、結果にはその データソースに関する有効な所有者のリスト (null を有する TABLE_OWNER カラム以外の全てのカラム) が含まれます。
  • table_type がパーセント記号 (%) のみで、 catalog、schema、 table が空文字列の場合、結果にはそのデータソースに 関する有効なテーブル型のリスト (null を有する TABLE_TYPE カラム以外の全てのカラム) が含まれます。

パラメータ

odbc

ODBC 接続 ID。詳細は odbc_connect() を参照ください。

catalog

カタログ(ODBC 2 の用語では '修飾子')。

schema

スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

table

名前。 このパラメータには以下の検索パターンを使用できます。 % はゼロ個以上の文字にマッチし、 _ はひとつの文字にマッチします。

types

table_type が空の文字列ではない場合、検索する型に ついてカンマで区切った値のリストを指定する必要があります。 各値は、シングルクオート(')で括るかまたは括らない形で指定可能です。 例えば、'TABLE','VIEW' または TABLE, VIEW となります。 データソースが指定したテーブル型をサポートしていない場合、 odbc_tables() はその型についていかなる結果も 返しません。

戻り値

情報を含んでいる ODBC 結果 ID を返します。 失敗した場合に false を返します。

結果セットのカラムは次のようになります。

  • TABLE_CAT
  • TABLE_SCHEM
  • TABLE_NAME
  • TABLE_TYPE
  • REMARKS
ドライバは追加のカラムを返すことが出来ます。

結果セットは TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, TABLE_NAME でソートされます。

変更履歴

バージョン | 説明
8.0.0 | schema, table, types は、nullable になりました。

例

例1 カタログのテーブル一覧を表示する

<?php
$conn = odbc_connect($dsn, $user, $pass);
$tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');
while (($row = odbc_fetch_array($tables))) {
print_r($row);
break; // further rows omitted for brevity
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [TABLE_CAT] => SalesOrders
    [TABLE_SCHEM] => dbo
    [TABLE_NAME] => Orders
    [TABLE_TYPE] => TABLE
    [REMARKS] =>
)

参考

  • odbc_tableprivileges() - 各テーブルのリストおよび関連する権限のリストを取得する
  • odbc_columns() - 指定したテーブルにあるカラム名のリストを取得する
  • odbc_specialcolumns() - 特殊カラムを取得する
  • odbc_statistics() - テーブルに関する統計情報を取得する
  • odbc_procedures() - 指定したデータソースに保存されているプロシージャのリストを取得する


PHP Data Objects

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 接続、および接続の管理
  • トランザクションおよび自動コミット
  • プリペアドステートメントおよびストアドプロシージャ
  • エラーおよびエラー処理
  • ラージオブジェクト (LOB)
  • PDO — PDO クラス
    • PDO::beginTransaction — トランザクションを開始する
    • PDO::commit — トランザクションをコミットする
    • PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する
    • PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
    • PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
    • PDO::exec — SQL ステートメントを実行し、作用した行数を返す
    • PDO::getAttribute — データベース接続の属性を取得する
    • PDO::getAvailableDrivers — 利用可能な PDO ドライバの配列を返す
    • PDO::inTransaction — トランザクション内かどうかを調べる
    • PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す
    • PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す
    • PDO::query — プレースホルダを指定せずに、SQL ステートメントを準備して実行する
    • PDO::quote — クエリ用の文字列をクオートする
    • PDO::rollBack — トランザクションをロールバックする
    • PDO::setAttribute — 属性を設定する
  • PDOStatement — PDOStatement クラス
    • PDOStatement::bindColumn — カラムを PHP 変数にバインドする
    • PDOStatement::bindParam — 指定された変数名にパラメータをバインドする
    • PDOStatement::bindValue — 値をパラメータにバインドする
    • PDOStatement::closeCursor — カーソルを閉じてステートメントを再実行できるようにする
    • PDOStatement::columnCount — 結果セット中のカラム数を返す
    • PDOStatement::debugDumpParams — SQL プリペアドコマンドを出力する
    • PDOStatement::errorCode — 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
    • PDOStatement::errorInfo — 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する
    • PDOStatement::execute — プリペアドステートメントを実行する
    • PDOStatement::fetch — 結果セットから次の行を取得する
    • PDOStatement::fetchAll — 結果セットから、残っている行を取得する
    • PDOStatement::fetchColumn — 結果セットの次行から単一カラムを返す
    • PDOStatement::fetchObject — 次の行を取得し、それをオブジェクトとして返す
    • PDOStatement::getAttribute — 文の属性を取得する
    • PDOStatement::getColumnMeta — 結果セットのカラムに対するメタデータを返す
    • PDOStatement::getIterator — 結果セットのイテレータを取得する
    • PDOStatement::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する
    • PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す
    • PDOStatement::setAttribute — 文の属性を設定する
    • PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する
  • PDOException — PDOException クラス
  • PDORow — PDORow クラス
  • PDO ドライバ
    • CUBRID (PDO) — CUBRID 関数 (PDO_CUBRID)
    • MS SQL Server (PDO) — Microsoft SQL Server および Sybase 関数 (PDO_DBLIB)
    • Firebird (PDO) — Firebird 関数 (PDO_FIREBIRD)
    • IBM (PDO) — IBM 関数 (PDO_IBM)
    • Informix (PDO) — Informix 関数 (PDO_INFORMIX)
    • MySQL (PDO) — MySQL 関数 (PDO_MYSQL)
    • MS SQL Server (PDO) — Microsoft SQL Server 関数 (PDO_SQLSRV)
    • Oracle (PDO) — Oracle 関数 (PDO_OCI)
    • ODBC and DB2 (PDO) — ODBC および DB2 関数 (PDO_ODBC)
    • PostgreSQL (PDO) — PostgreSQL 関数 (PDO_PGSQL)
    • SQLite (PDO) — SQLite 関数 (PDO_SQLITE)


はじめに

PHP Data Objects (PDO) 拡張モジュールは、 PHP の中からデータベースにアクセスするための軽量で高性能な インターフェイスを定義します。 PDO インターフェイスを実装する各データベースドライバは、 正規表現関数のようなデータベース固有の機能を提供することができます。 PDO 拡張モジュールによりそのデータベースの全てのデータベース関数を 実行できるわけではないことに注意してください。 データベースサーバーにアクセスするには、 データベース固有の PDO ドライバ を使用する必要があります。

PDO は、データアクセスの抽象化レイヤを提供します。 つまり、使用しているデータベースが何であるかにかかわらず、同じ 関数を使用してクエリの発行やデータの取得が行えるということです。 PDO は、データベースの抽象化を行うのでは ありません。つまり、SQL を書き直したり 存在しない機能をエミュレートしたりはしないということです。 もしそのような機能が必要なら、全体を網羅する (full-blown) 別の抽象化レイヤを使用すべきです。

PDO は PHP 本体にバンドルされています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • PDO
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

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

  1. PDO および PDO_SQLITE ドライバは、デフォルトで有効となっています。 必要に応じて、使用するデータベース用の PDO ドライバを有効にすることができます。 データベースごとの PDO ドライバについてのドキュメント を参照ください。

    注意:

    PDO を共有モジュールとしてビルドする場合 (非推奨です)、 すべての PDO ドライバは PDO 自体の後に ロードしなければなりません。

  2. PDO を共有モジュールとしてインストールする場合は、php.ini ファイルを変更し、PHP の実行時に PDO 拡張モジュールが自動的に読み込まれるようにしなければなりません。 データベースごとのドライバについても同様です。 ドライバは、pdo.so ファイルの後に記述するようにしましょう。 ドライバを読み込む前に PDO の初期化を済ませておく必要があるからです。 PDO およびデータベースドライバを静的にビルドした場合は、この部分は読み飛ばしてかまいません。

    extension=pdo.so

Windows ユーザー

  1. php_pdo.dll をはじめに指定し、 さらにその他のデータベース固有の DLL について、実行時に dl() で読み込むか php.ini の中で php_pdo.dll に引き続いて指定します。たとえば次のようになります。

    extension=php_pdo.dll
extension=php_pdo_firebird.dll
extension=php_pdo_informix.dll
extension=php_pdo_mssql.dll
extension=php_pdo_mysql.dll
extension=php_pdo_oci.dll
extension=php_pdo_oci8.dll
extension=php_pdo_odbc.dll
extension=php_pdo_pgsql.dll
extension=php_pdo_sqlite.dll

    これらの DLL は、システムの extension_dir になければなりません。

注意:

php.ini ファイルを変更したら、 新しい設定を有効にするために PHP を再起動する必要があります。


実行時設定

php.ini の設定により動作が変化します。

PDO 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pdo.dsn.* |  | php.ini のみ |

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo.dsn.* string

DSN の別名を定義します。完全な説明については PDO::__construct() を参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PDO::PARAM_BOOL (int)
ブールデータ型を表します。
PDO::PARAM_NULL (int)
SQL NULL データ型を表します。
PDO::PARAM_INT (int)
SQL INTEGER データ型を表します。
PDO::PARAM_STR (int)
SQL CHAR, VARCHAR, または他の文字列データ型を表します。
PDO::PARAM_STR_NATL (int)
事前定義された文字セットを使用する文字列であることを示すフラグです。 PHP 7.2.0 以降で利用可能です。
PDO::PARAM_STR_CHAR (int)
通常の文字セットを使用する文字列であることを示すフラグです。 PHP 7.2.0 以降で利用可能です。
PDO::PARAM_LOB (int)
SQL ラージオブジェクト型を表します。
PDO::PARAM_STMT (int)
レコードセット型を表します。この型は現在どのドライバでもサポートされていません。
PDO::PARAM_INPUT_OUTPUT (int)
パラメータがストアドプロシージャ用の入力パラメータであることを指定します。 この値は、PDO::PARAM_* データ型とのビットORとして指定する必要があります。
PDO::FETCH_DEFAULT (int)
デフォルトの取得方法を使うことを指定します。 PHP 8.0.7 以降で利用可能です。
PDO::FETCH_LAZY (int)
取得する方法として、 結果セットが返すカラム名と同じ名前のプロパティを有するオブジェクトとして各行を返す方法を 指定します。 PDO::FETCH_LAZY は、アクセスされたものと同じ名前のプロパティ名を作成する PDORow オブジェクトを返します。 PDOStatement::fetchAll() の中では使えません。
PDO::FETCH_ASSOC (int)
結果セットの対応するカラム名にふられているものと同じキーを付けた 連想配列として各行を返す取得方法を指定します。 もし結果セットが複数のカラムを同名で含む場合、 PDO::FETCH_ASSOC はカラム名毎に 1 つの値のみ返します。
PDO::FETCH_NAMED (int)
結果セットの対応するカラム名にふられているものと同じキーを付けた 連想配列として各行を返す取得方法を指定します。 もし結果セットが複数のカラムを同名で含む場合、 PDO::FETCH_NAMED はカラム名毎に値の配列を返します。
PDO::FETCH_NUM (int)
結果セットの対応するカラム番号にふられているものと同じ添字を付けた 配列として各行を返す取得方法を指定します。番号は0から始まります。
PDO::FETCH_BOTH (int)
結果セットと同じカラム名と0から始まるカラム番号を付けた配列として各行を返す 方法を指定します。
PDO::FETCH_OBJ (int)
結果セットが返すカラム名と同じ名前のプロパティを有する オブジェクトとして各行を返す方法を指定します。
PDO::FETCH_BOUND (int)
結果セットのカラムの値を PDOStatement::bindParam() または PDOStatement::bindColumn() メソッドでバインドされた PHP変数に代入し、TRUEを返すという取得方法を指定します。
PDO::FETCH_COLUMN (int)
結果セットの次の行から指定された一つのカラムのみを返す取得方法を指定します。
PDO::FETCH_CLASS (int)
カラムをクラスのプロパティにマップしつつ、 指定されたクラスの新規インスタンスを返す取得方法を指定します。

注意: 要求されたクラスにプロパティが存在しない場合は、マジックメソッド __set() がコールされます。

PDO::FETCH_INTO (int)
カラムをクラスのプロパティにマップしつつ、 指定されたクラスの既存のインスタンスを更新する取得方法を指定します。
PDO::FETCH_FUNC (int)
データをその場で扱う方法を完全にカスタマイズできるようにします (PDOStatement::fetchAll() の中でしか使えません)。
PDO::FETCH_GROUP (int)
値で返すグループ。 PDO::FETCH_COLUMN あるいは PDO::FETCH_KEY_PAIR と組み合わせます。
PDO::FETCH_UNIQUE (int)
一意な値だけを取得します。
PDO::FETCH_KEY_PAIR (int)
ふたつのカラムからなる結果を配列で取得します。最初のカラムの値がキー、二番目のカラムの内容が値となります。
PDO::FETCH_CLASSTYPE (int)
最初のカラムの値からクラス名を決定します。
PDO::FETCH_SERIALIZE (int)
PDO::FETCH_INTO と同様ですが、 シリアライズした文字列としてオブジェクトを提供します。 このフラグを設定した場合はコンストラクタが呼ばれません。 PHP 8.1.0 以降は、この定数は推奨されなくなりました。
PDO::FETCH_PROPS_LATE (int)
コンストラクタを呼んでからプロパティを設定します。
PDO::ATTR_AUTOCOMMIT (int)
この値が false の場合、PDO は接続がトランザクションを開始できるように オートコミットを無効にしようとします。
PDO::ATTR_PREFETCH (int)
独自アプリケーションにおけるメモリ使用量に対する速度のバランスを 調整するためのプリフェッチサイズを設定します。 全てのデータベースとドライバの組み合わせでプリフェッチサイズの設定を サポートしているわけではありません。
PDO::ATTR_TIMEOUT (int)
データベースとの通信に対するタイムアウト値を秒で設定します。
PDO::ATTR_ERRMODE (int)
PDO::ATTR_SERVER_VERSION (int)
PDO::ATTR_CLIENT_VERSION (int)
PDO::ATTR_SERVER_INFO (int)
PDO::ATTR_CONNECTION_STATUS (int)
PDO::ATTR_CASE (int)
PDO::CASE_* 定数で指定されたケースにカラム名を変更します。
PDO::ATTR_CURSOR_NAME (int)
PDO::ATTR_CURSOR (int)
PDO::ATTR_DRIVER_NAME (int)
ドライバ名を返します。

例1 PDO::ATTR_DRIVER_NAME の使用例

<?php
if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
echo "mysql 上で動作しています。何か mysql 固有のことをここで行います\n";
}
?>

PDO::ATTR_ORACLE_NULLS (int)
空文字を SQL の NULL 値に変換します。
PDO::ATTR_PERSISTENT (int)
新規接続を生成するよりもむしろ持続的接続を要求します。
PDO::ATTR_STATEMENT_CLASS (int)
Sets the class name of which statements are returned as.
PDO::ATTR_FETCH_CATALOG_NAMES (int)
結果セット中の各カラム名にカタログ名を追加します。 カタログ名とカラム名は、小数点 (.) で区切られます。
PDO::ATTR_FETCH_TABLE_NAMES (int)
結果セット中の各カラム名にテーブル名を追加します。 テーブル名とカラム名は、小数点 (.) で区切られます。
PDO::ATTR_STRINGIFY_FETCHES (int)
全てのフェッチする値を強制的に文字列として扱います。
PDO::ATTR_MAX_COLUMN_LEN (int)
カラム名の最大の長さを設定します。
PDO::ATTR_DEFAULT_FETCH_MODE (int)
PDO::ATTR_EMULATE_PREPARES (int)
PDO::ATTR_DEFAULT_STR_PARAM (int)
デフォルトの文字列のパラメータタイプを設定します。 PDO::PARAM_STR_NATL と PDO::PARAM_STR_CHAR のうち、いずれかひとつを選べます。 PHP 7.2.0 以降で利用可能です。
PDO::ERRMODE_SILENT (int)
エラー時にエラーもしくは例外を発生しません。 開発者の方は明示的にエラーをチェックするようにしてください。 これはデフォルトのモードです。
PDO::ERRMODE_WARNING (int)
エラーが発生した場合、PHP の E_WARNING メッセージを発行します。
PDO::ERRMODE_EXCEPTION (int)
エラーが発生した場合、PDOException をスローします。
PDO::CASE_NATURAL (int)
カラム名をデータベースドライバにより返されたままにします。
PDO::CASE_LOWER (int)
カラム名を小文字にします。
PDO::CASE_UPPER (int)
カラム名を大文字にします。
PDO::NULL_NATURAL (int)
PDO::NULL_EMPTY_STRING (int)
PDO::NULL_TO_STRING (int)
PDO::FETCH_ORI_NEXT (int)
結果セットの次の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_PRIOR (int)
結果セットの前の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_FIRST (int)
結果セットの先頭の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_LAST (int)
結果セットの最後の行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_ABS (int)
結果セットから行番号で指定した行を取得します。スクローラブルなカーソルでのみ有効です。
PDO::FETCH_ORI_REL (int)
結果セットのカーソルの現在の位置を基準とする相対位置により指定された行を 取得します。スクローラブルなカーソルでのみ有効です。
PDO::CURSOR_FWDONLY (int)
前進のみ可能なカーソルを有する PDOStatement オブジェクトを生成します。 これにより、アプリケーションの性能は改善しますが、 PDOStatementオブジェクトは前方にある結果セットから一度に一行を 取得するという制約を受けます。
PDO::CURSOR_SCROLL (int)
スクローラブルカーソルを有する PDOStatement オブジェクトを作成します。 結果セットから取得した行を制御するための PDO::FETCH_ORI_* 定数を指定して ください。
PDO::ERR_CANT_MAP (int)
PDO::ERR_SYNTAX (int)
PDO::ERR_CONSTRAINT (int)
PDO::ERR_NOT_FOUND (int)
PDO::ERR_ALREADY_EXISTS (int)
PDO::ERR_NOT_IMPLEMENTED (int)
PDO::ERR_MISMATCH (int)
PDO::ERR_TRUNCATED (int)
PDO::ERR_DISCONNECTED (int)
PDO::ERR_NO_PERM (int)
PDO::ERR_NONE (string)
SQLSTATE '00000' は SQL ステートメントがエラーや警告がなく発行に成功したことを意味します。 この定数はエラーが発生したかどうかを判別するために PDO::errorCode() もしくは PDOStatement::errorCode() をチェックする際に 便利です。この場合、通常はエラー状態を発生したメソッドからの戻りコードを 検査することによって検知します。
PDO::PARAM_EVT_ALLOC (int)
割り当てられたときに発生するイベント。
PDO::PARAM_EVT_FREE (int)
割り当てが解除されたときに発生するイベント。
PDO::PARAM_EVT_EXEC_PRE (int)
プリペアドステートメントの実行前に発生するイベント。
PDO::PARAM_EVT_EXEC_POST (int)
プリペアドステートメントの実行後に発生するイベント。
PDO::PARAM_EVT_FETCH_PRE (int)
結果セットから結果を取得する前に発生するイベント。
PDO::PARAM_EVT_FETCH_POST (int)
結果セットから結果を取得した後に発生するイベント。
PDO::PARAM_EVT_NORMALIZE (int)
バインドパラメータの登録時に発生するイベント。 これにより、ドライバがパラメータ名を正規化できるようになります。
PDO::SQLITE_DETERMINISTIC (int)
PDO::sqliteCreateFunction() で作られる関数が決定論的であることを指定します。 つまり、同じ入力が与えられると、単一のSQLステートメントの範疇では同じ結果が常に返されます。 (PHP 7.1.4 以降で使用可能です)


接続、および接続の管理

PDO 基底クラスのインスタンスを作成することにより、接続が確立されます。 どのドライバを使用するのかにかかわらず、常に PDO クラスを指定します。 コンストラクタに渡す引数により、データソース (いわゆる DSN) の指定や (もしあれば、オプションで) ユーザー名およびパスワードの指定を行います。

例1 MySQL への接続

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
?>

接続時になんらかのエラーが発生した場合、PDOException オブジェクトがスローされます。エラー処理を行いたい場合はこの例外を キャッチします。あるいはこれを無視して、 set_exception_handler() で設定した グローバル例外ハンドラに処理を任せることもできます。

例2 接続エラーの処理

<?php
try {
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
} catch (PDOException $e) {
// たとえば、タイムアウトしたあとに再接続を試みます
}
?>

警告

他の 例外 と同様に、 PDOException は catch を使って 明示的にキャッチすることもできますし、 set_exception_handler() を使って暗黙的にキャッチすることもできます。 そうしない場合、例外をキャッチしない場合のデフォルトの動作として E_FATAL_ERROR が発生します。 この致命的なエラーはデータベース接続の詳細を含むバックトレースを含みます。 このバックトレースを見れば、データベースへの接続の詳細がわかってしまいます。 そのため、本番環境のサーバーでは、 php.ini の display_errors を 0 に設定しておきましょう。

データベースへの接続に成功すると、PDO クラスのインスタンスが スクリプトに返されます。この PDO オブジェクトが存在する間、 接続がアクティブであり続けます。接続を閉じるには、他から 参照されていないことを保障することでオブジェクトを破棄する 必要があります。それには、オブジェクトを保持している変数に対して null を代入します。 明示的にこれを行わなかった場合は、スクリプトの終了時に自動的に 接続が閉じられます。

注意: この PDO インスタンスへの参照 (PDOStatement インスタンスからの参照や、同じ PDO インスタンスを参照する別の変数からの参照など) が他にも残っているなら、それらもあわせて削除する必要があります (PDOStatement を参照する変数に null を代入するなど)。

例3 接続を閉じる

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
// ここで接続を使用します
$sth = $dbh->query('SELECT * FROM foo');

// 使用を終了したので、閉じます
$sth = null;
$dbh = null;
?>

データベースサーバーへの持続的な接続による恩恵をこうむる web アプリケーションは多いでしょう。持続的な接続は、スクリプトが 終了しても閉じられずにキャッシュされ、他のスクリプトが同じ内容の 接続を要求してきた際にそれが再利用されます。持続的接続の キャッシュにより、スクリプトがデータベースを使用するたびに 新しい接続を確立するオーバーヘッドを避けることができます。 それにより、結果として web アプリケーションを高速化できるように なります。

例4 持続的な接続

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
PDO::ATTR_PERSISTENT => true
));
?>

PDO::ATTR_PERSISTENT オプションの値は、 数値でない string の値が設定されない限り、(持続的な接続が有効/無効かを示す) bool に変換されます。 数値でない string を設定する場合、複数の接続プールを使うことができます。 これは互換性がない異なる接続設定を使う場合に便利です。たとえば、 異なる PDO::MYSQL_ATTR_USE_BUFFERED_QUERY の値を設定する場合が挙げられます。

注意:

持続的な接続を使用したい場合は、ドライバのオプションを表す配列に PDO::ATTR_PERSISTENT を設定して PDO のコンストラクタに渡す必要があります。この属性を PDO::setAttribute() を用いてインスタンス作成後に設定した場合は、 そのドライバは持続的な接続を使用しません。

注意:

PDO ODBC ドライバを使用しており、ODBC ライブラリが ODBC 接続プーリングをサポートしている場合 (unixODBC および Windows はこれをサポートしています。他にもあるかもしれません) は、 PDO の持続的接続を使用せずに ODBC の接続プーリングに 接続キャッシュ処理を任せることを推奨します。 ODBC の接続プールは、プロセス内で他のモジュールと共有されています。 PDO が接続をキャッシュしてしまうと、その接続は ODBC の 接続プールに返されなくなり、他のモジュールによって新たな接続が 作成されてしまうようになります。


トランザクションおよび自動コミット

さあ、PDO を使用してデータベースに接続することができました。 クエリを発行する前に、PDO がトランザクションをどのように扱うのかを 理解しなければなりません。トランザクションについてよくわからない方の ために説明すると、これは以下の 4 つの機能、つまり 原子性 - Atomicity、一貫性 - Consistency、独立性 - Isolation および 永続性 - Durability (ACID) を提供するものです。 一般的な言葉で言うと、トランザクション内で実行された作業は たとえ段階的に行われたものであってもデータベースに安全に反映される ことが保証されています。トランザクションのコミット時に他の接続の 干渉を受けることはありません。また、トランザクション内での作業は (まだコミットされていなければ) いつでも自動的に取り消すことが できます。これにより、スクリプト内でのエラー処理がより楽になります。

トランザクションの一般的な実装は、変更内容を一時的に「蓄えて」おき、 それを一気に適用するようになっています。この実装には、更新処理の 性能を劇的に向上させるという効果もあります。つまり、 トランザクションによってあなたの書くスクリプトはより高速になり、 また、より堅牢になるということです (これらの恩恵をうけるためには、トランザクションを正しく使用する 必要があります)。

残念ながら、すべてのデータベースがトランザクションをサポートしていると いうわけではありません。そのため、PDO で最初に接続をオープンした際には、 いわゆる「自動コミット」モードで動作します。自動コミットモードとは、 もしデータベースがトランザクションをサポートしていたら個々のクエリが 暗黙的なトランザクションのもとで実行され、サポートしていなかったら トランザクションを使用せずに実行されることを意味します。 トランザクションを使用する場合は、 PDO::beginTransaction() メソッドを使用して トランザクションを初期化する必要があります。使用しているドライバが トランザクションをサポートしていない場合は PDOException が スローされます (これは深刻な状態であるため、エラー処理の設定に かかわらず常にスローされます)。初期化した後でトランザクションを 終了させるには、トランザクション内でのコードが成功したか否かに応じて PDO::commit() あるいは PDO::rollBack() を使用します。

警告

PDO は、トランザクション機能をドライバレベルでしかチェックしません。 実行時に何らかの条件でトランザクションが使えない場合でも、 データベースサーバーがトランザクション開始要求を受け付けた場合には PDO::beginTransaction() は true を返します。エラーとはなりません。

たとえば、MySQL データベースの MyISAM テーブルでトランザクションを使おうとした場合にこの現象が発生します。

スクリプトが終了したり接続が閉じられようとした際に、もし処理が 完了していないトランザクションがあれば PDO が自動的に ロールバックします。これは、スクリプトが予期せぬ状態で終了した場合に データの不整合が発生するのを避けるための安全装置です。もし 明示的にコミットしていなければ、おそらく何かおかしなことが 起こったのだろうと推測されます。そのため、データを守るために ロールバックが行われるのです。

警告

自動的にロールバックが行われるのは、トランザクションを PDO::beginTransaction() で開始した場合のみです。 トランザクションを開始するクエリを手動で発行した場合、 PDO はそれを知ることができません。そのため、何か問題が発生しても ロールバックすることはできないのです。

例1 トランザクション内で一括処理を行う

以下の例では、新しい従業員のデータを作成しているものとします。 この従業員には ID 番号 23 を割り当てます。この人物についての 基礎データを入力するだけでなく、その給与についても登録する 必要があります。以下では単純に 2 つの別々の更新を行っていますが、 それらは PDO::beginTransaction() および PDO::commit() のコールで囲まれています。 これにより、変更が完了するまでは他からは一切変更内容が 見えないことが保証されます。もし何か問題が発生すれば、 catch ブロック内でトランザクション開始以降のすべての変更が ロールバックされます。そしてエラーメッセージを表示します。

<?php
try {
$dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
array(PDO::ATTR_PERSISTENT => true));
echo "接続しました\n";
} catch (Exception $e) {
die("接続できません: " . $e->getMessage());
}

try {
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

$dbh->beginTransaction();
$dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
$dbh->exec("insert into salarychange (id, amount, changedate)
values (23, 50000, NOW())");
$dbh->commit();

} catch (Exception $e) {
$dbh->rollBack();
echo "失敗しました。" . $e->getMessage();
}
?>

トランザクション内で行える処理は、更新には限りません。たとえば 何か複雑なクエリを発行してデータを抽出し、その情報をもとに データの更新をしたり別のクエリを実行したりすることも可能です。 トランザクションがアクティブな間は、作業中のデータについては 他から一切変更が加えられないことが保証されます。 トランザクションについての詳細は、 使用するデータベースサーバーのドキュメントを参照ください。


プリペアドステートメントおよびストアドプロシージャ

より成熟したデータベースの多くは、プリペアドステートメントという 概念をサポートしています。プリペアドステートメントとはいったい何の ことでしょう? これは、実行したい SQL をコンパイルした 一種のテンプレートのようなものです。パラメータ変数を使用することで SQL をカスタマイズすることが可能です。プリペアドステートメントには 2 つの大きな利点があります。

  • クエリのパース (あるいは準備) が必要なのは最初の一回だけで、 同じパラメータ (あるいは別のパラメータ) を指定して何度でも クエリを実行することができます。クエリを実行するには、準備として クエリの解析やコンパイル、そして実行プランの最適化が行われます。 クエリが複雑になると、この処理には時間がかかるようになります。 同じクエリを異なったパラメータで何度も実行すると、アプリケーションの 動作は目に見えて遅くなるでしょう。 プリペアドステートメントを使用すると、この 解析/コンパイル/最適化 の繰り返しを避けることができます。 端的に言うと、プリペアドステートメントは使用するリソースが少ないため 高速に動作するということです。
  • プリペアドステートメントに渡すパラメータは、引用符で括る必要は ありません。それはドライバが自動的に行います。 アプリケーションで明示的にプリペアドステートメントを使用するように すれば、SQL インジェクションは決して発生しません (しかし、もし信頼できない入力をもとにクエリの他の部分を構築している のならば、その部分に対するリスクを負うことになります)。

プリペアドステートメントは非常に有用な機能なので、もしドライバが サポートしていなくても、例外的に PDO がこの機能をエミュレートします。 これにより、データベースの機能にかかわらず同じ仕組みで データベースへのアクセスができることが保証されます。

例1 プリペアドステートメントを使用して、繰り返し挿入処理を行う

この例は、name および value を名前つきプレースホルダで置き換えて INSERT クエリを実行します。

<?php
$stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
$stmt->bindParam(':name', $name);
$stmt->bindParam(':value', $value);

// 行を挿入します
$name = 'one';
$value = 1;
$stmt->execute();

// パラメータを変更し、別の行を挿入します
$name = 'two';
$value = 2;
$stmt->execute();
?>

例2 プリペアドステートメントを使用して、繰り返し挿入処理を行う

この例は、name および value をプレースホルダ ? で置き換えて INSERT クエリを実行します。

<?php
$stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
$stmt->bindParam(1, $name);
$stmt->bindParam(2, $value);

// 行を挿入します
$name = 'one';
$value = 1;
$stmt->execute();

// パラメータを変更し、別の行を挿入します
$name = 'two';
$value = 2;
$stmt->execute();
?>

例3 プリペアドステートメントを使用してデータを取得する

この例では、フォームで入力したキーの値に応じたデータを取得します。 ユーザーの入力内容は自動的に引用符で括られるので、SQL インジェクション攻撃の 恐れはありません。

<?php
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
$stmt->execute([$_GET['name']]);
foreach ($stmt as $row) {
print_r($row);
}
?>

例4 出力パラメータを指定してストアドプロシージャをコールする

データベースドライバがサポートしていれば、入力パラメータだけでなく 出力パラメータもバインドすることが可能です。出力パラメータは、 一般にストアドプロシージャから値を受け取るために使用します。この場合、 返される値の大きさがどの程度になるのかをバインド時に知っておく必要が あります。指定した大きさよりも大きな値が返されると、エラーが発生します。

<?php
$stmt = $dbh->prepare("CALL sp_returns_string(?)");
$stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

// ストアドプロシージャをコールします
$stmt->execute();

print "プロシージャが返した値は $return_value です\n";
?>

例5 入出力パラメータを指定してストアドプロシージャをコールする

入出力の両方に使用するパラメータを指定することもできます。 このパラメータの書式は、出力パラメータと同じです。 次の例では、ストアドプロシージャに文字列 'hello' を渡しています。 プロシージャの結果が返ってくると、 この文字列はプロシージャの返す値に置き換えられます。

<?php
$stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
$value = 'hello';
$stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

// ストアドプロシージャをコールします
$stmt->execute();

print "プロシージャが返した値は $value です\n";
?>

例6 プレースホルダの間違った使用法

<?php
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
$stmt->execute([$_GET['name']]);

// プレースホルダは、値全体に対して使用しなければなりません
$stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
$stmt->execute(["%$_GET[name]%"]);
?>


エラーおよびエラー処理

PDO が提供するエラー処理方法は 3 通り存在し、 アプリケーションの開発形態によって使い分けることができます。

  • PDO::ERRMODE_SILENT

    PHP 8.0.0 より前のバージョンでは、これがデフォルトのモードでした。 ステートメントおよびデータベースオブジェクトの エラーについて、PDO は単にそのエラーコードのみを設定します。 これを取得するには PDO::errorCode() および PDO::errorInfo() メソッドを使用します。 ステートメントオブジェクトへのコールによってエラーが発生した場合は、 そのオブジェクトの PDOStatement::errorCode() あるいは PDOStatement::errorInfo() メソッドを呼び出します。 データベースオブジェクトへのコールによってエラーが発生した場合は、 その代わりにデータベースオブジェクト上の同じメソッドを呼び出します。

  • PDO::ERRMODE_WARNING

    エラーコードを設定することに加え、PDO は 伝統的な E_WARNING メッセージも出力します。この設定はデバッグ/テストの際に有用で、 アプリケーションの動作を妨げることなしに問題点を確認できるように なります。

  • PDO::ERRMODE_EXCEPTION

    PHP 8.0.0 以降では、これがデフォルトのモードです。 エラーコードを設定することに加え、PDO は PDOException をスローします。エラーコードや 関連情報が、クラスのプロパティとして設定されます。 この設定もまたデバッグ時に有用で、エラーが発生した時点で スクリプトの実行を停止させることによりコード内の問題点を 見つけやすくなります (例外によりスクリプトが終了した際には、トランザクションは自動的に ロールバックされることを覚えておきましょう)。

    このモードが有用である理由のひとつとして、伝統的な PHP 形式の警告よりも より明確にエラー処理コードが書けることがあります。例外を発生させず、 データベースへのコールのたびに毎回明示的に戻り値をチェックすることに 比べると、コードの量やネストを減らすことができます。

    PHP の例外についての詳細な情報は、 例外 を参照ください。

PDO のエラーコードは、SQL-92 の SQLSTATE エラーコード文字列に 標準化されています。 ネイティブのコードを適切な SQLSTATE コードに変換するのは、個々の PDO ドライバの仕事となります。 PDO::errorCode() メソッドは SQLSTATE コードを返します。 エラーについての詳細な銃尾法が知りたい場合、PDO では PDO::errorInfo() メソッドも提供しており、 これは SQLSTATE コード、ドライバ固有のエラーコードおよびドライバ固有の エラーメッセージを含む配列を返します。

例1 PDO インスタンスの作成およびエラーモードの設定

<?php
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

// (テーブルが存在しない場合) PDOException がスローされます
$dbh->query("SELECT wrongcolumn FROM wrongtable");

上の例の出力は以下となります。

Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
Stack trace:
#0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
#1 {main}
  thrown in /tmp/pdo_test.php on line 10

注意:

PDO::__construct() は、接続に失敗した場合は常に PDOException をスローします。 これは、現在設定されている PDO::ATTR_ERRMODE が何であっても同じです。

例2 PDO インスタンスの作成およびコンストラクタでのエラーモードの設定

<?php
$dsn = 'mysql:dbname=test;host=127.0.0.1';
$user = 'googleguy';
$password = 'googleguy';

$dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

// (テーブルが存在しない場合) 例外をスローする代わりに、E_WARNING レベルのエラーが発生します
$dbh->query("SELECT wrongcolumn FROM wrongtable");

上の例の出力は以下となります。

Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
/tmp/pdo_test.php on line 9


ラージオブジェクト (LOB)

アプリケーション内で、データベースに「大きな」データを格納する 必要を感じることがあるかもしれません。「大きな」とは、一般的には 「4kb 程度以上」を指しますが、データベースによっては 32kb くらいまでは 「大きい」と判断されずにすむこともあります。ラージオブジェクトは テキストあるいはバイナリの両方の形式をとり得ます。 PDO でこのラージデータ型を扱うには、 PDOStatement::bindParam() や PDOStatement::bindColumn() のコール時に 型コードとして PDO::PARAM_LOB を使用します。 PDO::PARAM_LOB を指定すると、PDO は データをストリームにマップします。これにより、 PHP ストリーム API を使用してデータを扱えるようになります。

例1 データベース内の画像を表示する

この例では $lob という名前の変数に LOB をバインドし、 fpassthru() を使用してそれをブラウザに送信します LOB はストリームで表されるので、 fgets()、fread() および stream_get_contents() といった関数を 使用することができます。

<?php
$db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
$stmt = $db->prepare("select contenttype, imagedata from images where id=?");
$stmt->execute(array($_GET['id']));
$stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
$stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
$stmt->fetch(PDO::FETCH_BOUND);

header("Content-Type: $type");
fpassthru($lob);
?>

例2 画像をデータベースに挿入する

この例では、ファイルをオープンしてそのハンドルを PDO に渡し、 LOB としてデータベースに挿入します。PDO は、データベースに応じた もっとも適切な方法でデータを取得します。

<?php
$db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
$stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
$id = get_new_id(); // 新しい ID を割り当てるための何らかの関数

// フォームからファイルをアップロードしていると仮定します。
// 詳細な情報は PHP のドキュメントを参照ください。

$fp = fopen($_FILES['file']['tmp_name'], 'rb');

$stmt->bindParam(1, $id);
$stmt->bindParam(2, $_FILES['file']['type']);
$stmt->bindParam(3, $fp, PDO::PARAM_LOB);

$db->beginTransaction();
$stmt->execute();
$db->commit();
?>

例3 画像をデータベースに挿入する: Oracle

Oracle は、ファイルから LOB を挿入する方法が他とは少し違います。 また、必ずトランザクション内で挿入しなければなりません。 それ以外の場合、新しく挿入された LOB は長さゼロとなり、クエリの 実行時に暗黙的にコミットされます。

<?php
$db = new PDO('oci:', 'scott', 'tiger');
$stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
"VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?");
$id = get_new_id(); // 新しい ID を割り当てるための何らかの関数

// フォームからファイルをアップロードしていると仮定します。
// 詳細な情報は PHP のドキュメントを参照ください。

$fp = fopen($_FILES['file']['tmp_name'], 'rb');

$stmt->bindParam(1, $id);
$stmt->bindParam(2, $_FILES['file']['type']);
$stmt->bindParam(3, $fp, PDO::PARAM_LOB);

$db->beginTransaction();
$stmt->execute();
$db->commit();
?>


PDO クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

はじめに

PHP とデータベースサーバーの間の接続を表します。

クラス概要

class PDO {
/* 定数 */
public const int PARAM_NULL;
public const int PARAM_BOOL = 5;
public const int PARAM_INT = 1;
public const int PARAM_STR = 2;
public const int PARAM_LOB = 3;
public const int PARAM_STMT = 4;
public const int PARAM_INPUT_OUTPUT;
public const int PARAM_STR_NATL;
public const int PARAM_STR_CHAR;
public const int PARAM_EVT_ALLOC;
public const int PARAM_EVT_FREE;
public const int PARAM_EVT_EXEC_PRE;
public const int PARAM_EVT_EXEC_POST;
public const int PARAM_EVT_FETCH_PRE;
public const int PARAM_EVT_FETCH_POST;
public const int PARAM_EVT_NORMALIZE;
public const int FETCH_DEFAULT;
public const int FETCH_LAZY;
public const int FETCH_ASSOC;
public const int FETCH_NUM;
public const int FETCH_BOTH;
public const int FETCH_OBJ;
public const int FETCH_BOUND;
public const int FETCH_COLUMN;
public const int FETCH_CLASS;
public const int FETCH_INTO;
public const int FETCH_FUNC;
public const int FETCH_GROUP;
public const int FETCH_UNIQUE;
public const int FETCH_KEY_PAIR;
public const int FETCH_CLASSTYPE;
public const int FETCH_SERIALIZE;
public const int FETCH_PROPS_LATE;
public const int FETCH_NAMED;
public const int ATTR_AUTOCOMMIT;
public const int ATTR_PREFETCH;
public const int ATTR_TIMEOUT;
public const int ATTR_ERRMODE;
public const int ATTR_SERVER_VERSION;
public const int ATTR_CLIENT_VERSION;
public const int ATTR_SERVER_INFO;
public const int ATTR_CONNECTION_STATUS;
public const int ATTR_CASE;
public const int ATTR_CURSOR_NAME;
public const int ATTR_CURSOR;
public const int ATTR_ORACLE_NULLS;
public const int ATTR_PERSISTENT;
public const int ATTR_STATEMENT_CLASS;
public const int ATTR_FETCH_TABLE_NAMES;
public const int ATTR_FETCH_CATALOG_NAMES;
public const int ATTR_DRIVER_NAME;
public const int ATTR_STRINGIFY_FETCHES;
public const int ATTR_MAX_COLUMN_LEN;
public const int ATTR_EMULATE_PREPARES;
public const int ATTR_DEFAULT_FETCH_MODE;
public const int ATTR_DEFAULT_STR_PARAM;
public const int ERRMODE_SILENT;
public const int ERRMODE_WARNING;
public const int ERRMODE_EXCEPTION;
public const int CASE_NATURAL;
public const int CASE_LOWER;
public const int CASE_UPPER;
public const int NULL_NATURAL;
public const int NULL_EMPTY_STRING;
public const int NULL_TO_STRING;
public const string ERR_NONE;
public const int FETCH_ORI_NEXT;
public const int FETCH_ORI_PRIOR;
public const int FETCH_ORI_FIRST;
public const int FETCH_ORI_LAST;
public const int FETCH_ORI_ABS;
public const int FETCH_ORI_REL;
public const int CURSOR_FWDONLY;
public const int CURSOR_SCROLL;
/* メソッド */
public __construct(
string $dsn,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?array $options = null
)
public beginTransaction(): bool
public commit(): bool
public errorCode(): ?string
public errorInfo(): array
public exec(string $statement): int|false
public getAttribute(int $attribute): mixed
public static getAvailableDrivers(): array
public inTransaction(): bool
public lastInsertId(?string $name = null): string|false
public prepare(string $query, array $options = []): PDOStatement|false
public query(string $query, ?int $fetchMode = null): PDOStatement|false
public query(string $query, ?int $fetchMode = PDO::FETCH_COLUMN, int $colno): PDOStatement|false
public query(
string $query,
?int $fetchMode = PDO::FETCH_CLASS,
string $classname,
array $constructorArgs
): PDOStatement|false
public query(string $query, ?int $fetchMode = PDO::FETCH_INTO, object $object): PDOStatement|false
public quote(string $string, int $type = PDO::PARAM_STR): string|false
public rollBack(): bool
public setAttribute(int $attribute, mixed $value): bool
}

目次

  • PDO::beginTransaction — トランザクションを開始する
  • PDO::commit — トランザクションをコミットする
  • PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する
  • PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDO::exec — SQL ステートメントを実行し、作用した行数を返す
  • PDO::getAttribute — データベース接続の属性を取得する
  • PDO::getAvailableDrivers — 利用可能な PDO ドライバの配列を返す
  • PDO::inTransaction — トランザクション内かどうかを調べる
  • PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す
  • PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す
  • PDO::query — プレースホルダを指定せずに、SQL ステートメントを準備して実行する
  • PDO::quote — クエリ用の文字列をクオートする
  • PDO::rollBack — トランザクションをロールバックする
  • PDO::setAttribute — 属性を設定する


トランザクションを開始する

  • ≪ PDO
  • PDO::commit ≫
  • PHP Manual
  • PDO
  • トランザクションを開始する

PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — トランザクションを開始する

説明

public PDO::beginTransaction(): bool

オートコミットモードをオフにします。オートコミットモードがオフの間、 PDO オブジェクトを通じてデータベースに加えた変更は PDO::commit() をコールするまでコミットされません。 PDO::rollBack() をコールすると、 データベースへの全ての変更をロールバックし、 オートコミットモードに設定された接続を返します。

MySQL を含むいくつかのデータベースでは、DROP TABLE や CREATE TABLE のようなデータベース定義言語 (DDL) ステートメントがトランザクション中に 発行される場合、暗黙的なコミットが自動的に発行されます。 この暗黙的なコミットにより、そのトランザクション境界で 他のあらゆる変更をロールバックすることができなくなるでしょう。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

トランザクションが既に開始されている場合や、ドライバがトランザクションに対応していない場合に PDOException をスローします。

注意: 例外は、PDO::ATTR_ERRMODE 属性が PDO::ERRMODE_EXCEPTION ではない場合でも発生します。

例

例1 トランザクションをロールバックする

以下の例は、トランザクションを開始し、 変更をロールバックする前にデータベースを修正する 2 つのステートメントを発行します。 しかしながら MySQL では、DROP TABLE ステートメントは 自動的にトランザクションをコミットするので、 トランザクション中のどの変更もロールバックされません。

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* データベーススキーマとデータを変更する */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
SET name = 'hamburger'");

/* ミスに気づき、変更をロールバックする */
$dbh->rollBack();

/* データベース接続はオートコミットモードに戻る */
?>

参考

  • PDO::commit() - トランザクションをコミットする
  • PDO::rollBack() - トランザクションをロールバックする
  • トランザクションおよび自動コミット


トランザクションをコミットする

  • ≪ PDO::beginTransaction
  • PDO::__construct ≫
  • PHP Manual
  • PDO
  • トランザクションをコミットする

PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — トランザクションをコミットする

説明

public PDO::commit(): bool

トランザクションをコミットし、 次に PDO::beginTransaction() で新たなトランザクションが開始されるまで、 データベース接続をオートコミットモードに戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

有効なトランザクションがない場合に PDOException をスローします。

注意: 例外は、PDO::ATTR_ERRMODE 属性が PDO::ERRMODE_EXCEPTION ではない場合でも発生します。

例

例1 基本的なトランザクションをコミットする

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* 複数レコードを追加する。全部成功か全部失敗のどちらかになる */
$sql = 'INSERT INTO fruit
(name, colour, calories)
VALUES (?, ?, ?)';

$sth = $dbh->prepare($sql);

foreach ($fruits as $fruit) {
$sth->execute(array(
$fruit->name,
$fruit->colour,
$fruit->calories,
));
}

/* 変更をコミットする */
$dbh->commit();

/* データベース接続はオートコミットモードに戻る */
?>

例2 DDL トランザクションをコミットする

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* データベーススキーマを変更する */
$sth = $dbh->exec("DROP TABLE fruit");

/* 変更をコミットする */
$dbh->commit();

/* データベース接続はオートコミットモードに戻る */
?>

注意: DDL 文の操作にトランザクションが使えないデータベースもあります。 単にエラーになるだけのものもあれば、(MySQL などのように) DDL 文が実行された時点で自動的にトランザクションをコミットしてしまうものもあります。

参考

  • PDO::beginTransaction() - トランザクションを開始する
  • PDO::rollBack() - トランザクションをロールバックする
  • トランザクションおよび自動コミット


データベースへの接続を表す PDO インスタンスを生成する

  • ≪ PDO::commit
  • PDO::errorCode ≫
  • PHP Manual
  • PDO
  • データベースへの接続を表す PDO インスタンスを生成する

PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する

説明

public PDO::__construct(
string $dsn,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?array $options = null
)

指定されたデータベースへの接続を表す PDO インスタンスを生成します。

パラメータ

dsn

データソース名(Data Source Name)またはDSN。データベースに接続するために 必要な情報が含まれます。

一般に、DSNはPDOドライバ名の後にコロンが続き、 各PDOドライバに固有の接続構文が続きます。より多くの情報は PDO driver-specific documentation にあります。

dsn パラメータは、データベースへの接続を生成する ために必要な引数を指定する方法として、3種類の方法をサポートします。

ドライバ呼び出し

dsn に完全な DSN を指定します。

URI 呼び出し

dsn は、uri: の後に DSN 文字列を含むファイルの位置を定義する URI が続く形式となります。 この URI には、ローカルファイルまたはリモート URL を指定することができます。

uri:file:///path/to/dsnfile

エイリアス

dsn は、DSN 文字列を定義する php.ini の pdo.dsn.name へマップする名前 name からなります。

注意:

エイリアスは、.htaccess や httpd.conf ではなく、 php.ini で定義する必要があります。

username

DSN 文字列のユーザー名。このパラメータは、いくつかの PDO ドライバではオプションです。

password

DSN 文字列のパスワード。このパラメータは、いくつかの PDO ドライバではオプションです。

options

ドライバ固有の接続オプションを指定するキー=> 値の配列。

エラー / 例外

PDO::__construct() は、 指定されたデータベースへの接続に失敗した場合、 PDO::ATTR_ERRMODE が設定されているかどうかに関わらず、 PDOException をスローします。

例

例1 ドライバ呼び出しにより PDO インスタンスを生成する

<?php

$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);

?>

例2 URI 呼び出しにより PDO インスタンスを生成する

以下の例では、ファイル /usr/local/dbconnect が存在し、 PHP がこのファイルを読み込む権限を有していることを仮定します。 このファイルには、 PDO_ODBC により DB2 データベースに接続するための PDO DSN が含まれています。

odbc:DSN=SAMPLE;UID=john;PWD=mypass

これにより、PHP スクリプトでは、単に uri: パラメータを渡し、 ファイルの URI を示すだけでデータベース接続を作成することができるようになります。

<?php

$dsn = 'uri:file:///usr/local/dbconnect';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>

例3 エイリアスにより PDO インスタンスを生成する

以下の例では、php.ini にエイリアス mydb のみで MySQL データベースに接続できるようにするための以下のエントリが含まれることを 仮定します。

[PDO]
pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"
<?php

$dsn = 'mydb';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>


データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

  • ≪ PDO::__construct
  • PDO::errorInfo ≫
  • PHP Manual
  • PDO
  • データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

説明

public PDO::errorCode(): ?string

パラメータ

この関数にはパラメータはありません。

戻り値

SQLSTATE を返します。これは、ANSI SQL-92 標準で定義された英数 5 文字の ID です。簡潔に言えば、SQLSTATE は 2文字のクラス値の後に 3 文字のサブクラス値が続きます。クラス値 01 はワーニングを表し、 戻り値のコード SQL_SUCCESS_WITH_INFO を伴います。 クラス 'IM' を除く '01' 以外のクラス値はエラーを表します。 クラス 'IM' は PDO 自身の実装 (もしくは ODBC ドライバを使用している場合は ODBC かも知れません) に由来するワーニングやエラーに固有の値です。 あらゆるクラスでのサブクラス値 '000' は SQLSTATE に対するサブクラスがない事を示しています。

PDO::errorCode() はデータベースハンドラに 直接行った操作に対するエラーコードのみを取得します。 もし PDO::prepare() や PDO::query() を通して PDOStatement オブジェクトを生成し、 文でエラーが発生した場合、PDO::errorCode() はエラーを反映しません。 特定の文ハンドラに対して実行された操作についてのエラーコードを返すには PDOStatement::errorCode() をコールしなければなりません。

そのデータベースハンドル上で何も操作が行われていない場合は null を返します。

例

例1 SQLSTATE コードを取得する

<?php
/* エラーを発生させる -- BONES テーブルは存在しない */
$dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

echo "\nPDO::errorCode(): ", $dbh->errorCode();
?>

上の例の出力は以下となります。

PDO::errorCode(): 42S02

参考

  • PDO::errorInfo() - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::errorCode() - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorInfo() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する


データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

  • ≪ PDO::errorCode
  • PDO::exec ≫
  • PHP Manual
  • PDO
  • データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

説明

public PDO::errorInfo(): array

パラメータ

この関数にはパラメータはありません。

戻り値

PDO::errorInfo() は、 このデータベースハンドラによって実行された直近の操作に関するエラー情報を 配列として返します。この配列は少なくとも次のフィールドを含みます。

要素 | 情報
0 | SQLSTATE エラーコード (これは、ANSI SQL 標準で定義された英数 5 文字の ID)
1 | ドライバ固有のエラーコード
2 | ドライバ固有のエラーメッセージ

注意:

SQLSTATE エラーコードが設定されていない場合やドライバ固有のエラーがない場合は、 要素 0 に続く要素は null となります。

PDO::errorInfo() はデータベースハンドラに 直接行った操作に対するエラーコードのみを取得します。 もし PDO::prepare() や PDO::query() を通して PDOStatement オブジェクトを生成し、 文でエラーが発生した場合、PDO::errorInfo() はそのエラーを反映しません。 特定の文ハンドラに対して実行された操作についてのエラーコードを返すには PDOStatement::errorInfo() をコールしなければなりません。

例

例1 DB2 データベースに対する PDO_ODBC 接続の errorInfo() フィールドを表示する

<?php
/* エラーを発生させる -- 無効な SQL シンタックス */
$stmt = $dbh->prepare('bogus sql');
if (!$stmt) {
echo "\nPDO::errorInfo():\n";
print_r($dbh->errorInfo());
}
?>

上の例の出力は以下となります。

PDO::errorInfo():
Array
(
    [0] => HY000
    [1] => 1
    [2] => near "bogus": syntax error
)

参考

  • PDO::errorCode() - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorCode() - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorInfo() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する


SQL ステートメントを実行し、作用した行数を返す

  • ≪ PDO::errorInfo
  • PDO::getAttribute ≫
  • PHP Manual
  • PDO
  • SQL ステートメントを実行し、作用した行数を返す

PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — SQL ステートメントを実行し、作用した行数を返す

説明

public PDO::exec(string $statement): int|false

PDO::exec() は、一度の関数コールで SQL 文を実行し、文によって作用した行数を返します。

PDO::exec() は SELECT 文からは結果を返しません。 プログラム中で一度だけ発行が必要になる SELECT 文に対しては、 PDO::query() の発行を検討してください。 複数回発行が必要な文については、PDO::prepare() による PDOStatement オブジェクトの準備と PDOStatement::execute() による文の発行を行ってください。

パラメータ

statement

準備、実行する SQL ステートメントを指定します。

クエリ内のデータは 適切にエスケープ する必要があります。

戻り値

PDO::exec() は、発行した SQL ステートメントによって更新もしくは 削除された行数を返します。 1 行も作用しなかった場合、PDO::exec() は 0 を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

以下の例は PDO::exec() の戻り値の使用法を間違っています。結果として一行も更新されなかった場合に die() がコールされてしまうからです。

<?php
$db->exec() or die(print_r($db->errorInfo(), true)); // 間違っている
?>

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 DELETE 文の発行

WHERE 句を伴う DELETE 文によって削除された行数をカウントします。

<?php
$dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

/* FRUIT テーブルから全ての行を削除する */
$count = $dbh->exec("DELETE FROM fruit");

/* 削除された行数を返す */
print "Deleted $count rows.\n";
?>

上の例の出力は以下となります。

Deleted 1 rows.

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する
  • PDOStatement::execute() - プリペアドステートメントを実行する


データベース接続の属性を取得する

  • ≪ PDO::exec
  • PDO::getAvailableDrivers ≫
  • PHP Manual
  • PDO
  • データベース接続の属性を取得する

PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — データベース接続の属性を取得する

説明

public PDO::getAttribute(int $attribute): mixed

この関数はデータベース接続の属性値を返します。PDOStatement 属性を取得する場合、PDOStatement::getAttribute() を参照ください。

いくつかのデータベースもしくはドライバは、 データベース接続の属性の全てのをサポートしていないかも知れないことに 注意してください。

パラメータ

attribute

PDO_ATTR_* 定数の 1 つを指定します。 データベース接続に適用される一般的な属性は以下の通りです。

  • PDO::ATTR_AUTOCOMMIT
  • PDO::ATTR_CASE
  • PDO::ATTR_CLIENT_VERSION
  • PDO::ATTR_CONNECTION_STATUS
  • PDO::ATTR_DRIVER_NAME
  • PDO::ATTR_ERRMODE
  • PDO::ATTR_ORACLE_NULLS
  • PDO::ATTR_PERSISTENT
  • PDO::ATTR_PREFETCH
  • PDO::ATTR_SERVER_INFO
  • PDO::ATTR_SERVER_VERSION
  • PDO::ATTR_TIMEOUT

ドライバによっては、 そのドライバ固有の属性を使っているかもしれません。 そういう属性は、他のドライバでは使っては いけない ことに注意して下さい。

戻り値

コールに成功した場合は要求された PDO 属性の値を返します。 コールに失敗した場合は null を返します。

エラー / 例外

ドライバが要求された attribute をサポートしていない場合、 PDO::getAttribute() は PDOException をスローします。

例

例1 データベース接続の属性を取得する

<?php
$conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
$attributes = array(
"AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
"ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
"TIMEOUT"
);

foreach ($attributes as $val) {
echo "PDO::ATTR_$val: ";
echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
}
?>

参考

  • PDO::setAttribute() - 属性を設定する
  • PDOStatement::getAttribute() - 文の属性を取得する
  • PDOStatement::setAttribute() - 文の属性を設定する


利用可能な PDO ドライバの配列を返す

  • ≪ PDO::getAttribute
  • PDO::inTransaction ≫
  • PHP Manual
  • PDO
  • 利用可能な PDO ドライバの配列を返す

PDO::getAvailableDrivers

pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — 利用可能な PDO ドライバの配列を返す

説明

public static PDO::getAvailableDrivers(): array
pdo_drivers(): array

この関数は、PDO::__construct() の DSN パラメータで利用可能な全ての有効な PDO ドライバを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

PDO::getAvailableDrivers() は PDO ドライバ名の配列を返します。 もしドライバが何も利用できない場合、空の配列を返します。

例

例1 PDO::getAvailableDrivers() の例

<?php
print_r(PDO::getAvailableDrivers());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql
    [1] => sqlite
)


トランザクション内かどうかを調べる

  • ≪ PDO::getAvailableDrivers
  • PDO::lastInsertId ≫
  • PHP Manual
  • PDO
  • トランザクション内かどうかを調べる

PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — トランザクション内かどうかを調べる

説明

public PDO::inTransaction(): bool

ドライバ内で、現在トランザクションがアクティブになっているかどうかを調べます。 このメソッドが機能するのは、トランザクションをサポートしているデータベースドライバのみです。

パラメータ

この関数にはパラメータはありません。

戻り値

トランザクションが現在アクティブな場合に true、 そうでないときに false を返します。


最後に挿入された行の ID あるいはシーケンスの値を返す

  • ≪ PDO::inTransaction
  • PDO::prepare ≫
  • PHP Manual
  • PDO
  • 最後に挿入された行の ID あるいはシーケンスの値を返す

PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す

説明

public PDO::lastInsertId(?string $name = null): string|false

最後に挿入された行の ID、 あるいはシーケンスオブジェクトから次の値を返します。 これは、構成しているドライバに依存します。例えば PDO_PGSQL の場合、name パラメータにシーケンスオブジェクト名を指定することができます。

注意:

このメソッドは、異なる PDO ドライバ間で意味のあるもしくは 一貫性のある結果を返さないかも知れません。 構成しているデータベースが自動インクリメントフィールド、 もしくはシーケンスの概念をサポートしていないかも知れないためです。

パラメータ

name

ID が返されるべきシーケンスオブジェクト名を指定します。

戻り値

もし name パラメータにシーケンス名が指定されなかった場合、 PDO::lastInsertId() はデータベースに挿入された最後の行の行IDに相当する文字列を返します。

もし name パラメータにシーケンス名が指定された場合、 PDO::lastInsertId() は指定されたシーケンスオブジェクトから取得した最後の値に相当する 文字列を返します。

もし PDO ドライバがサポートしていない場合、 PDO::lastInsertId() は IM001 SQLSTATE を発生させます。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。


文を実行する準備を行い、文オブジェクトを返す

  • ≪ PDO::lastInsertId
  • PDO::query ≫
  • PHP Manual
  • PDO
  • 文を実行する準備を行い、文オブジェクトを返す

PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す

説明

public PDO::prepare(string $query, array $options = []): PDOStatement|false

PDOStatement::execute() メソッドによって実行される SQL ステートメントを準備します。 ステートメントのテンプレートは、文が実行されるときに実際の値に置き換えられる 0 個もしくはそれ以上の名前 (:name) もしくは疑問符 (?) パラメータマークを含むことができます。 名前と疑問符パラメータを同一の ステートメントのテンプレート中で使用することはできません。 どちらか一方か、他のパラメータ形式を使用してください。 ユーザーの入力をバインドする際にはこれらのパラメータを使います。 ユーザーの入力を直接クエリに含めてはいけません。

PDOStatement::execute() をコールする際には、 文に渡すパラメータにはそれぞれ固有のパラメータマークを設定する必要があります。 エミュレーションモードが有効になっていない限り、 ひとつのプリペアドステートメントの中で、同じ名前のパラメータマークを 複数使用することはできません。

注意:

パラメータマーカーが表せるのは、データリテラルだけです。 リテラルの一部やキーワード、識別子、その他のクエリのパーツをパラメータにバインドすることはできません。 たとえば、SQL 文の IN() 句などで、 ひとつのパラメータに複数の値を割り当てることはできません。

異なるパラメータを用いて複数回実行されるような文に対し PDO::prepare() と PDOStatement::execute() をコールすることで、 ドライバがクライアントまたはサーバー側にクエリプランやメタ情報を キャッシュさせるよう調整するため、 アプリケーションのパフォーマンスを最適化します。また、 パラメータに手動でクオートする必要がなくなるので SQL インジェクション攻撃から保護する助けになります。

PDO は元々この機能をサポートしていないドライバに対して プリペアドステートメントとバインドパラメータをエミュレートします。 このため、ある形式をサポートしているがその他の形式をサポートしていない ドライバの場合、名前もしくは疑問符形式のパラメータを他の適当な値に 書き換えることも可能です。

注意: エミュレートされたプリペアドステートメントと、 名前パラメータやクエスチョンマークを書き換えるパーサは、[シングル|ダブル]クォート に対して標準とは異なるエスケープをサポートしています。 これによって、バックスラッシュのすぐ後にクォートで終了するクエリは そのままの形では認識されず、間違ったパラメータとして認識され、 実行されたときにプリペアドステートメントが失敗してしまいます。 回避策は、プリペアドステートメントのエミュレートをこの手のSQLクエリでは使わないようにしつつ、 ドライバによってサポートされているパラメータの書き換えを避けることです。

PHP 7.4.0 以降では、クエスチョンマークを2回続けることで、 クエスチョンマークそのものをエスケープすることができます。 これは、?? という文字列が、 クエリをデータベースに送信する時に ? に変換されるということです。

パラメータ

query

これは対象のデータベースサーバーに対して有効な SQL 文のテンプレートでなければなりません。

options

この配列は、このメソッドによって返される PDOStatement オブジェクトに対して 1 もしくはそれ以上の key=>value の組を含みます。 通常、スクロール可能なカーソルを要求するために PDO::ATTR_CURSOR に PDO::CURSOR_SCROLL を設定する場合に使用することになるでしょう。 いくつかのドライバには、準備する際に利用可能なドライバ固有の オプションがあります。

戻り値

もしデータベースサーバーが正常に文を準備する場合、 PDO::prepare() は PDOStatement オブジェクトを返します。 もしデータベースサーバーが文を準備できなかった場合、 PDO::prepare() は false を返すか PDOException を発行します (エラー処理 の方法に依存します)。

注意:

プリペアドステートメントをエミュレートする際にデータベースサーバーとの通信は行いません。 したがって PDO::prepare() はステートメントのチェックを行いません。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 名前付きパラメータを用いて SQL ステートメントのテンプレートを準備する

<?php
/* 値の配列を渡してプリペアドステートメントを実行する */
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
$sth->execute(['calories' => 150, 'colour' => 'red']);
$red = $sth->fetchAll();
/* 配列のキーの前にも、コロン ":" を付けることができます(オプション) */
$sth->execute([':calories' => 175, ':colour' => 'yellow']);
$yellow = $sth->fetchAll();
?>

例2 疑問符パラメータを用いて SQL ステートメントのテンプレートを準備する

<?php
/* 値の配列を渡してプリペアドステートメントを実行する */
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute([150, 'red']);
$red = $sth->fetchAll();
$sth->execute([175, 'yellow']);
$yellow = $sth->fetchAll();
?>

例3 クエスチョンマークをエスケープした、SQLステートメントのテンプレート

<?php
/* 注意: 以下は PostgreSQL の場合にのみ有効です */
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
$sth->execute(['feature']);
$featureIssues = $sth->fetchAll();
$sth->execute(['performance']);
$performanceIssues = $sth->fetchAll();
?>

参考

  • PDO::exec() - SQL ステートメントを実行し、作用した行数を返す
  • PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する
  • PDOStatement::execute() - プリペアドステートメントを実行する


プレースホルダを指定せずに、SQL ステートメントを準備して実行する

  • ≪ PDO::prepare
  • PDO::quote ≫
  • PHP Manual
  • PDO
  • プレースホルダを指定せずに、SQL ステートメントを準備して実行する

PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — プレースホルダを指定せずに、SQL ステートメントを準備して実行する

説明

public PDO::query(string $query, ?int $fetchMode = null): PDOStatement|false
public PDO::query(string $query, ?int $fetchMode = PDO::FETCH_COLUMN, int $colno): PDOStatement|false
public PDO::query(
string $query,
?int $fetchMode = PDO::FETCH_CLASS,
string $classname,
array $constructorArgs
): PDOStatement|false
public PDO::query(string $query, ?int $fetchMode = PDO::FETCH_INTO, object $object): PDOStatement|false

PDO::query() は、一回の関数コールの中で SQL ステートメントを準備して実行し、 結果を PDOStatement オブジェクトとして返します。

複数回発行する必要があるステートメントの場合、 PDO::prepare() で PDOStatement ステートメントを準備し、 PDOStatement::execute() でそのステートメントを 複数回発行する方がより良いパフォーマンスを得られると実感するでしょう。

PDO::query() を次にコールする前に 結果セット内の全てのデータを取得しない場合、そのコールは失敗します。 PDOStatement::closeCursor() をコールし、 次に PDO::query() をコールする前に PDOStatement オブジェクトに関連付けられたリソースを解放してください。

注意:

query にプレースホルダーが含まれている場合、 準備と実行は別々に行う必要があります。 つまり、PDO::prepare() を使って準備し、 PDOStatement::execute() を実行しなければいけません。

パラメータ

query

準備、発行する SQL ステートメント。

SQL にプレースホルダーが含まれている場合、 PDO::prepare() と PDOStatement::execute() を代わりに使う必要があります。 それとは別のやり方として、 PDO::query() を呼び出す前に、 PDO::quote() を使って適切にフォーマットしたデータを使って SQL文を手動で準備することができます。 但し、PDO::quote() は、ドライバがサポートしている場合に限り使えます。

fetchMode

返される PDOStatement のためのデフォルトのフェッチモード。 定数 PDO::FETCH_* のうちのひとつを設定しなければいけません。

この引数を渡すと、残りの引数は、 結果のステートメントオブジェクトに対して、 PDOStatement::setFetchMode() を呼び出したのと同じような扱いになります。 残りの引数は、選択するフェッチモードに応じて変化します。

戻り値

PDOStatement オブジェクトを返します。 失敗した場合に false を返します

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 プレースホルダーがないSQLを、PDO::query() で実行できます

<?php
$sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
foreach ($conn->query($sql) as $row) {
print $row['name'] . "\t";
print $row['color'] . "\t";
print $row['calories'] . "\n";
}
?>

上の例の出力は以下となります。

apple   red     150
banana  yellow  250
kiwi    brown   75
lemon   yellow  25
orange  orange  300
pear    green   150
watermelon      pink    90

参考

  • PDO::exec() - SQL ステートメントを実行し、作用した行数を返す
  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::execute() - プリペアドステートメントを実行する


クエリ用の文字列をクオートする

  • ≪ PDO::query
  • PDO::rollBack ≫
  • PHP Manual
  • PDO
  • クエリ用の文字列をクオートする

PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — クエリ用の文字列をクオートする

説明

public PDO::quote(string $string, int $type = PDO::PARAM_STR): string|false

PDO::quote() は入力文字列のまわりに引用符を付け (必要であれば) 、 入力文字列にあるシングルクオートをエスケープします。その場合、 構成しているドライバに適したクオート形式が使用されます。

この関数を SQL の構築に使用する場合、 SQL ステートメントにユーザーの入力値を埋め込むための PDO::quote() を使用する代わりに、 バインドパラメータを用いて SQL を準備するための PDO::prepare() を使用することが強く推奨されます。 バインドパラメータを用いるプリペアドステートメントは、 補間されたクエリした場合に比べ、 移植性や利便性に優れ、SQL インジェクションに対する免疫力を持つだけでなく しばしばより高速で、サーバーやクライアント側でコンパイル済みの形式でクエリを キャッシュする事が可能です。

全ての PDO ドライバがこのメソッドを実装しているわけではありません (たとえば PDO_ODBC などの例があります)。 代わりにプリペアドステートメントを使用することを検討してください。

警告

セキュリティ: デフォルトの文字セット

サーバーレベルで設定するなりデータベース接続自身に設定させる (ドライバに依存します) なりして、 文字セットを明示しておく必要があります。この文字セットが PDO::quote() に影響を及ぼします。詳細は 各ドライバのドキュメント を参照ください。

パラメータ

string

クオートされる文字列を指定します。

type

クオートするスタイルを変更するため、 ドライバにデータ型のヒントを提供します。 たとえば PDO_PARAM_LOB は、 ドライバにバイナリデータをエスケープするように伝えます。

戻り値

理論上安全なクオートされた SQL ステートメントの文字列を返します。 ドライバがこの方法での引用符付けをサポートしていない場合は false を返します。

例

例1 通常の文字列をクオートする

<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');

/* 単純な文字列 */
$string = 'Nice';
print "Unquoted string: $string\n";
print "Quoted string: " . $conn->quote($string) . "\n";
?>

上の例の出力は以下となります。

Unquoted string: Nice
Quoted string: 'Nice'

例2 危険な文字列をクオートする

<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');

/* 危険な文字列 */
$string = 'Naughty \' string';
print "Unquoted string: $string\n";
print "Quoted string:" . $conn->quote($string) . "\n";
?>

上の例の出力は以下となります。

Unquoted string: Naughty ' string
Quoted string: 'Naughty '' string'

例3 複雑な文字列をクオートする

<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');

/* 複雑な文字列 */
$string = "Co'mpl''ex \"st'\"ring";
print "Unquoted string: $string\n";
print "Quoted string: " . $conn->quote($string) . "\n";
?>

上の例の出力は以下となります。

Unquoted string: Co'mpl''ex "st'"ring
Quoted string: 'Co''mpl''''ex "st''"ring'

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::execute() - プリペアドステートメントを実行する


トランザクションをロールバックする

  • ≪ PDO::quote
  • PDO::setAttribute ≫
  • PHP Manual
  • PDO
  • トランザクションをロールバックする

PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — トランザクションをロールバックする

説明

public PDO::rollBack(): bool

PDO::beginTransaction() によって開始された 現在のトランザクションをロールバックします。

データベースがオートコミットモードに設定されている場合、 この関数はトランザクションをロールバックした後に オートコミットモードを元に戻します。

MySQL を含むいくつかのデータベースでは、DROP TABLE や CREATE TABLE のようなデータベース定義言語 (DDL) ステートメントがトランザクション中に 発行される場合、暗黙的なコミットが自動的に発行されます。 この暗黙的なコミットにより、そのトランザクション境界で 他のあらゆる変更をロールバックすることができなくなるでしょう。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

有効なトランザクションがない場合に PDOException をスローします。

注意: 例外は、PDO::ATTR_ERRMODE 属性が PDO::ERRMODE_EXCEPTION ではない場合でも発生します。

例

例1 トランザクションをロールバックする

以下の例は、トランザクションを開始し、 変更をロールバックする前にデータベースを修正する 2 つのステートメントを発行します。 しかしながら MySQL では、DROP TABLE ステートメントは 自動的にトランザクションをコミットするので、 トランザクション中のどの変更もロールバックされません。

<?php
/* トランザクションを開始する。オートコミットがオフになる */
$dbh->beginTransaction();

/* データベーススキーマとデータを変更する */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
SET name = 'hamburger'");

/* ミスに気づき、変更をロールバックする */
$dbh->rollBack();

/* データベース接続はオートコミットモードに戻る */
?>

参考

  • PDO::beginTransaction() - トランザクションを開始する
  • PDO::commit() - トランザクションをコミットする
  • トランザクションおよび自動コミット


属性を設定する

  • ≪ PDO::rollBack
  • PDOStatement ≫
  • PHP Manual
  • PDO
  • 属性を設定する

PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — 属性を設定する

説明

public PDO::setAttribute(int $attribute, mixed $value): bool

データベースハンドルの属性を設定します。 利用可能な通常の属性は以下の通りです。いくつかのドライバでは、 ドライバ固有の属性を使用することが可能です。 ドライバ固有の属性は、 他のドライバでは使っては いけない ことに注意して下さい。

PDO::ATTR_CASE

強制的にカラム名を指定したケースにします。 以下の値のうち、ひとつを指定できます:

PDO::CASE_LOWER
強制的にカラム名を小文字にする。
PDO::CASE_NATURAL
データベースドライバによって返されるカラム名をそのままにする。
PDO::CASE_UPPER
強制的にカラム名を大文字にする。
PDO::ATTR_ERRMODE

PDO のエラーレポートモード。 以下の値のうち、ひとつを指定できます:

PDO::ERRMODE_SILENT
エラーコードのみを設定する。
PDO::ERRMODE_WARNING
E_WARNING を発生させる。
PDO::ERRMODE_EXCEPTION
PDOException をスローします。
PDO::ATTR_ORACLE_NULLS

注意: この属性は Oracle だけでなく、全てのドライバで利用可能です。

null と空文字列を変換するかどうか、 および、どのように変換するかを指定します。 以下の値のうち、ひとつを指定できます:

PDO::NULL_NATURAL
変換を行わない。
PDO::NULL_EMPTY_STRING
空文字列を null に変換する。
PDO::NULL_TO_STRING
null を空文字列に変換する。
PDO::ATTR_STRINGIFY_FETCHES

フェッチする際、数値を文字列に変換するかどうかを指定します。 bool の値を指定します: 変換を有効にする場合 true、 無効にする場合、false にします。

PDO::ATTR_STATEMENT_CLASS

PDOStatement から派生した、 ユーザーが提供するステートメントクラスを設定する。 array(string classname, array(mixed constructor_args)) の形式でなければいけません。

警告

永続的な PDO インスタンスは使用できません。

PDO::ATTR_TIMEOUT

タイムアウト秒数を指定します。 数値を指定します。

注意:

すべてのドライバがこのオプションに対応しているわけではありません。 また、ドライバによっては意味が異なることがあります。 たとえば SQLite は書き込み可能なロックを確保するのをこの秒数まで待ち続けますが、 他のドライバでは、 この秒数を接続時のタイムアウトや読み込みのタイムアウトとして扱うことがあります。

PDO::ATTR_AUTOCOMMIT

注意: OCI, Firebird, MySQL でのみ利用可能です。

それぞれの単一文で自動コミットするかどうか。 bool の値を指定します: 自動コミットを有効にする場合 true、 無効にする場合、false にします。 デフォルトは true です。

PDO::ATTR_EMULATE_PREPARES

注意: OCI, Firebird, MySQL でのみ利用可能です。

プリペアドステートメントのエミュレーションを有効または無効にします。 ドライバによっては、 ネイティブのプリペアドステートメントをサポートしていなかったり 完全には対応していなかったりするものがあります。 true を指定すると、 プリペアドステートメントを常にエミュレートします。 そうでない場合、 ネイティブのプリペアドステートメントを使おうとします。 ドライバが現在のクエリを正しく準備できなかった場合は、 常にエミュレート方式を使います。

PDO::MYSQL_ATTR_USE_BUFFERED_QUERY

注意: MySQL でのみ利用可能です。

バッファされたクエリを使うかどうかを指定します。 bool の値を指定します: バッファされたクエリを有効にする場合 true、 無効にする場合、false にします。 デフォルトは true です。

PDO::ATTR_DEFAULT_FETCH_MODE

デフォルトのフェッチモードを設定します。 このモードと使い方についての説明は、 PDOStatement::fetch() のドキュメントを参照ください。

パラメータ

attribute

変更する属性。

value

attribute に設定する値。 属性によっては、特定の型が必要かもしれません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • PDO::getAttribute() - データベース接続の属性を取得する
  • PDOStatement::getAttribute() - 文の属性を取得する
  • PDOStatement::setAttribute() - 文の属性を設定する


PDOStatement クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

はじめに

プリペアドステートメントを表します。ステートメント実行後は関連する結果セットを表します。

クラス概要

class PDOStatement implements IteratorAggregate {
/* プロパティ */
public string $queryString;
/* メソッド */
public bindColumn(
string|int $column,
mixed &$var,
int $type = PDO::PARAM_STR,
int $maxLength = 0,
mixed $driverOptions = null
): bool
public bindParam(
string|int $param,
mixed &$var,
int $type = PDO::PARAM_STR,
int $maxLength = 0,
mixed $driverOptions = null
): bool
public bindValue(string|int $param, mixed $value, int $type = PDO::PARAM_STR): bool
public closeCursor(): bool
public columnCount(): int
public debugDumpParams(): ?bool
public errorCode(): ?string
public errorInfo(): array
public execute(?array $params = null): bool
public fetch(int $mode = PDO::FETCH_DEFAULT, int $cursorOrientation = PDO::FETCH_ORI_NEXT, int $cursorOffset = 0): mixed
public fetchAll(int $mode = PDO::FETCH_DEFAULT): array
public fetchAll(int $mode = PDO::FETCH_COLUMN, int $column): array
public fetchAll(int $mode = PDO::FETCH_CLASS, string $class, ?array $constructorArgs): array
public fetchAll(int $mode = PDO::FETCH_FUNC, callable $callback): array
public fetchColumn(int $column = 0): mixed
public fetchObject(?string $class = "stdClass", array $constructorArgs = []): object|false
public getAttribute(int $name): mixed
public getColumnMeta(int $column): array|false
public getIterator(): Iterator
public nextRowset(): bool
public rowCount(): int
public setAttribute(int $attribute, mixed $value): bool
public setFetchMode(int $mode): bool
public setFetchMode(int $mode = PDO::FETCH_COLUMN, int $colno): bool
public setFetchMode(int $mode = PDO::FETCH_CLASS, string $class, ?array $constructorArgs = null): bool
public setFetchMode(int $mode = PDO::FETCH_INTO, object $object): bool
}

プロパティ

queryString

使ったクエリ文字列。

変更履歴

バージョン | 説明
8.0.0 | PDOStatement は、 Traversable ではなく、 IteratorAggregate を実装するようになりました。

目次

  • PDOStatement::bindColumn — カラムを PHP 変数にバインドする
  • PDOStatement::bindParam — 指定された変数名にパラメータをバインドする
  • PDOStatement::bindValue — 値をパラメータにバインドする
  • PDOStatement::closeCursor — カーソルを閉じてステートメントを再実行できるようにする
  • PDOStatement::columnCount — 結果セット中のカラム数を返す
  • PDOStatement::debugDumpParams — SQL プリペアドコマンドを出力する
  • PDOStatement::errorCode — 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDOStatement::errorInfo — 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::execute — プリペアドステートメントを実行する
  • PDOStatement::fetch — 結果セットから次の行を取得する
  • PDOStatement::fetchAll — 結果セットから、残っている行を取得する
  • PDOStatement::fetchColumn — 結果セットの次行から単一カラムを返す
  • PDOStatement::fetchObject — 次の行を取得し、それをオブジェクトとして返す
  • PDOStatement::getAttribute — 文の属性を取得する
  • PDOStatement::getColumnMeta — 結果セットのカラムに対するメタデータを返す
  • PDOStatement::getIterator — 結果セットのイテレータを取得する
  • PDOStatement::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する
  • PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す
  • PDOStatement::setAttribute — 文の属性を設定する
  • PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する


カラムを PHP 変数にバインドする

  • ≪ PDOStatement
  • PDOStatement::bindParam ≫
  • PHP Manual
  • PDOStatement
  • カラムを PHP 変数にバインドする

PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — カラムを PHP 変数にバインドする

説明

public PDOStatement::bindColumn(
string|int $column,
mixed &$var,
int $type = PDO::PARAM_STR,
int $maxLength = 0,
mixed $driverOptions = null
): bool

PDOStatement::bindColumn() は、 クエリからの結果セット中にあるカラムにバインドされた特定の値を 取得するための準備をします。 PDOStatement::fetch() もしくは PDOStatement::fetchAll() がコールされる度に、カラムにバインドされた全ての変数は更新されます。

注意:

カラムに関する情報はステートメントが実行されるまで常に PDO から利用できないため、移植可能なアプリケーションでは PDOStatement::execute(). の 後に この関数をコールするようにしてください。

しかし、LOB カラムをストリームにバインドする際に PgSQL ドライバ を使用するときには、 このメソッドを PDOStatement::execute() の 前に コールしなければなりません。 そうしないと、ラージオブジェクトの OID が integer で返されます。

パラメータ

column

結果セット中のカラム番号 (1 から始まる) を指定します。 カラム名を使用する場合、 ドライバによって返されるカラムの大文字小文字が一致する必要が あることをご承知おきください。

var

カラムがバインドされる PHP 変数名を指定します。

type

パラメータのデータ型を PDO::PARAM_* 定数 で指定します。

maxLength

領域を事前に確保するためのヒント。

driverOptions

ドライバのオプションパラメータ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 バインドした結果セットを PHP 変数に出力する

PHP 変数にバインドしている結果セットのカラムは、 アプリケーションで利用可能な各行に含まれるデータを作成するための 効果的な方法です。 以下のサンプルは、どうやって PDO が様々なオプションやを理にかなったデフォルト値を用いて カラムをバインド、取得するかを例示しています。

<?php
$stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
$stmt->execute();

/* カラム番号によってバインドする */
$stmt->bindColumn(1, $name);
$stmt->bindColumn(2, $colour);

/* カラム名によってバインドする */
$stmt->bindColumn('calories', $cals);

while ($stmt->fetch(PDO::FETCH_BOUND)) {
print $name . "\t" . $colour . "\t" . $cals . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

apple   red     150
banana  yellow  175
kiwi    green   75
orange  orange  150
mango   red     200
strawberry      red     25

参考

  • PDOStatement::execute() - プリペアドステートメントを実行する
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchAll() - 結果セットから、残っている行を取得する
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す


指定された変数名にパラメータをバインドする

  • ≪ PDOStatement::bindColumn
  • PDOStatement::bindValue ≫
  • PHP Manual
  • PDOStatement
  • 指定された変数名にパラメータをバインドする

PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — 指定された変数名にパラメータをバインドする

説明

public PDOStatement::bindParam(
string|int $param,
mixed &$var,
int $type = PDO::PARAM_STR,
int $maxLength = 0,
mixed $driverOptions = null
): bool

準備された SQL ステートメント中で、 対応する名前もしくは疑問符プレースホルダにパラメータをバインドします。 PDOStatement::bindValue() と異なり、 変数は参照としてバインドされ、PDOStatement::execute() がコールされたときのみ評価されます。

ほとんどのパラメータは入力パラメータです。つまり、クエリを構築する際、 パラメータは読み込み専用で使用されます(とはいえ、 type によってはキャストされる可能性もあります)。 いくつかのドライバは、出力パラメータとしてデータを返す ストアドプロシージャの実行をサポートしており、 またいくつかのドライバは、データを渡し更新された値を受け取る、 といった入出力パラメータもサポートしています。

パラメータ

param

パラメータ ID を指定します。名前付けされたプレースホルダを使った文に 対しては、:name 形式のパラメータ名となります。 疑問符プレースホルダを使った文に対しては、1 から始まるパラメータの 位置となります。

var

SQL ステートメントパラメータにバインドする PHP 変数名を指定します。

type

パラメータに対して PDO::PARAM_* 定数 を使った明示的なデータ型を指定します。 ストアドプロシージャからの INOUT パラメータの場合、 type パラメータに PDO::PARAM_INPUT_OUTPUT ビットを設定するためにビット OR を使用してください。

maxLength

データ型の長さを指定します。パラメータがストアドプロシージャからの OUT パラメータであることを示す場合、 明示的に長さを設定しなければなりません。 この値は、type パラメータに PDO::PARAM_INPUT_OUTPUT を指定した場合のみ意味があります。

driverOptions

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 名前付けされたプレースホルダを用いてプリペアドステートメントを実行する

<?php
/* バインドされた PHP 変数によってプリペアドステートメントを実行する */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->bindParam('calories', $calories, PDO::PARAM_INT);
/* 名前の前にも、コロン ":" を付けることができます(オプション) */
$sth->bindParam(':colour', $colour, PDO::PARAM_STR);
$sth->execute();
?>

例2 疑問符プレースホルダを用いてプリペアドステートメントを実行する

<?php
/* バインドされた PHP 変数によってプリペアドステートメントを実行する */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindParam(2, $colour, PDO::PARAM_STR);
$sth->execute();
?>

例3 INOUT パラメータを持つストアドプロシージャをコールする

<?php
/* INOUT パラメータを持つストアドプロシージャをコールする */
$colour = 'red';
$sth = $dbh->prepare('CALL puree_fruit(?)');
$sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
$sth->execute();
print "After pureeing fruit, the colour is: $colour";
?>

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::execute() - プリペアドステートメントを実行する
  • PDOStatement::bindValue() - 値をパラメータにバインドする


値をパラメータにバインドする

  • ≪ PDOStatement::bindParam
  • PDOStatement::closeCursor ≫
  • PHP Manual
  • PDOStatement
  • 値をパラメータにバインドする

PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — 値をパラメータにバインドする

説明

public PDOStatement::bindValue(string|int $param, mixed $value, int $type = PDO::PARAM_STR): bool

プリペアドステートメントで使用する SQL 文の中で、 対応する名前あるいは疑問符のプレースホルダに値をバインドします。

パラメータ

param

パラメータ ID。名前つきプレースホルダを使用する プリペアドステートメントの場合は、 :name 形式のパラメータ名となります。 疑問符プレースホルダを使用するプリペアドステートメントの場合は、 1 から始まるパラメータの位置となります。

value

パラメータにバインドする値。

type

パラメータに対して PDO::PARAM_* 定数 を使った明示的なデータ型を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 名前付けされたプレースホルダを用いてプリペアドステートメントを実行する

<?php
/* バインドされた PHP 変数によってプリペアドステートメントを実行する */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');

/* カラム名を使ってパラメータの値を設定します */
$sth->bindValue('calories', $calories, PDO::PARAM_INT);
/* 名前の前にも、コロン ":" を付けることができます(オプション) */
$sth->bindValue(':colour', $colour, PDO::PARAM_STR);
$sth->execute();
?>

例2 疑問符プレースホルダを用いてプリペアドステートメントを実行する

<?php
/* バインドされた PHP 変数によってプリペアドステートメントを実行する */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindValue(1, $calories, PDO::PARAM_INT);
$sth->bindValue(2, $colour, PDO::PARAM_STR);
$sth->execute();
?>

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::execute() - プリペアドステートメントを実行する
  • PDOStatement::bindParam() - 指定された変数名にパラメータをバインドする


カーソルを閉じてステートメントを再実行できるようにする

  • ≪ PDOStatement::bindValue
  • PDOStatement::columnCount ≫
  • PHP Manual
  • PDOStatement
  • カーソルを閉じてステートメントを再実行できるようにする

PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — カーソルを閉じてステートメントを再実行できるようにする

説明

public PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() は、 他の SQL ステートメントを発行できるようにサーバーへの接続を解放しますが、 ステートメントは再実行可能な状態のまま残されます。

このメソッドは以前に実行された PDOStatement オブジェクトが行をまだフェッチしていない場合に PDOStatement オブジェクトの実行をサポートしていないデータベースドライバに対して有用です。 もし使用しているデータベースドライバがこの制限を受ける場合、 out-of-sequence エラーが出力されます。

PDOStatement::closeCursor() は、 オプションのドライバ固有のメソッド (最大の効率を得るため) もしくはドライバ固有の関数がインストールされていない場合の汎用的な PDO フォールバックとして実装されています。 汎用的な PDO フォールバックは、PHP スクリプト中に以下のようなコードを書くことと意味的に等価です。

<?php
do {
while ($stmt->fetch())
;
if (!$stmt->nextRowset())
break;
} while (true);
?>

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 PDOStatement::closeCursor() の例

以下の例では、PDOStatement オブジェクト $stmt は複数の行を返しますが、このアプリケーションは先頭行のみフェッチし、 PDOStatement オブジェクトをフェッチしていない行がある状態のままにします。 このアプリケーションがが全てのデータベースドライバで動作するよう、 PDOStatement オブジェクト $otherStmt を実行する前に $stmt に対して PDOStatement::closeCursor() の呼び出しを挿入しています。

<?php
/* PDOStatement オブジェクトを生成する */
$stmt = $dbh->prepare('SELECT foo FROM bar');

/* 第二の PDOStatement オブジェクトを生成する */
$otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

/* 最初の文を実行する */
$stmt->execute();

/* 結果から先頭行のみフェッチする */
$stmt->fetch();

/* 続く closeCursor() のコールはいくつかのドライバでは必要となる */
$stmt->closeCursor();

/* ここで第二の文を実行することができる */
$otherStmt->execute();
?>

参考

  • PDOStatement::execute() - プリペアドステートメントを実行する


結果セット中のカラム数を返す

  • ≪ PDOStatement::closeCursor
  • PDOStatement::debugDumpParams ≫
  • PHP Manual
  • PDOStatement
  • 結果セット中のカラム数を返す

PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — 結果セット中のカラム数を返す

説明

public PDOStatement::columnCount(): int

PDOStatement オブジェクトに相当する結果セットにあるカラム数を返すために PDOStatement::columnCount() を使用します。

もし PDOStatement オブジェクトが PDO::query() から返された場合、カラム数は直ちに利用可能です。

もし PDOStatement オブジェクトが PDO::prepare() から返された場合、正確なカラム数は PDOStatement::execute() を実行するまで利用可能になりません。

パラメータ

この関数にはパラメータはありません。

戻り値

PDOStatement オブジェクトに相当する結果セットにあるカラム数を返します。 結果セットが空である場合でも同様です。 もし結果セットがなければ、PDOStatement::columnCount() は 0 を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 カラム数を数える

この例は、結果セットがある場合とない場合で、 PDOStatement::columnCount() がどのように動作するかを例示しています。

<?php
$dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

$sth = $dbh->prepare("SELECT name, colour FROM fruit");

/* (存在しない) 結果セットにあるカラム数を数える */
$colcount = $sth->columnCount();
print "Before execute(), result set has $colcount columns (should be 0)\n";

$sth->execute();

/* 結果セットにあるカラム数を数える */
$colcount = $sth->columnCount();
print "After execute(), result set has $colcount columns (should be 2)\n";

?>

上の例の出力は以下となります。

Before execute(), result set has 0 columns (should be 0)
After execute(), result set has 2 columns (should be 2)

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::execute() - プリペアドステートメントを実行する
  • PDOStatement::rowCount() - 直近の SQL ステートメントによって作用した行数を返す


SQL プリペアドコマンドを出力する

  • ≪ PDOStatement::columnCount
  • PDOStatement::errorCode ≫
  • PHP Manual
  • PDOStatement
  • SQL プリペアドコマンドを出力する

PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — SQL プリペアドコマンドを出力する

説明

public PDOStatement::debugDumpParams(): ?bool

プリペアドステートメントに含まれる以下のような情報を直接出力します。 使用する SQL クエリ、使用するパラメータ数 (Params)、パラメータリスト、パラメータ名、 パラメータの型 (paramtype) をあらわす整数値、 そのキーの名前あるいは位置、そしてクエリ内での位置 (PDO ドライバがサポートしている場合のみ。サポートしていない場合は -1 となります) 、型 (param_type) を表す整数値、boolean 値 is_param。

これはデバッグ用関数です。結果を標準出力にそのまま出力します。

ヒント

ブラウザに直接結果を出力する すべてのものと同様に、出力制御関数 を使用してこの関数の出力をキャプチャーし、(例えば)文字列 (string)に保存することが可能です。

これは、出力時にステートメント内にあるパラメータのみを出力します。 追加パラメータはステートメントに格納されておらず、出力されません。

パラメータ

この関数にはパラメータはありません。

戻り値

null を返します。エラーの場合は false を返します。

変更履歴

バージョン | 説明
7.2.0 | PDOStatement::debugDumpParams() は、データベースに送られた 完全な、(プレースホルダーをバインドされた値で置き換えた) 生のSQLクエリを返すようになりました。 これは、プリペアドステートメントがエミュレートされていた場合のみ利用できることに注意してください。

例

例1 名前つきパラメータを用いた PDOStatement::debugDumpParams() の例

<?php
/* プリペアドステートメントを、PHP の変数をバインドして実行します */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);
$sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
$sth->execute();

$sth->debugDumpParams();

?>

上の例の出力は以下となります。

SQL: [96] SELECT name, colour, calories
    FROM fruit
    WHERE calories < :calories AND colour = :colour
Params:  2
Key: Name: [9] :calories
paramno=-1
name=[9] ":calories"
is_param=1
param_type=1
Key: Name: [7] :colour
paramno=-1
name=[7] ":colour"
is_param=1
param_type=2

例2 名前なしパラメータを用いた PDOStatement::debugDumpParams() の例

<?php

/* プリペアドステートメントを、PHP の変数をバインドして実行します */
$calories = 150;
$colour = 'red';
$name = 'apple';

$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindValue(2, $colour, PDO::PARAM_STR);
$sth->execute();

$sth->debugDumpParams();

?>

上の例の出力は以下となります。

SQL: [82] SELECT name, colour, calories
    FROM fruit
    WHERE calories < ? AND colour = ?
Params:  2
Key: Position #0:
paramno=0
name=[0] ""
is_param=1
param_type=1
Key: Position #1:
paramno=1
name=[0] ""
is_param=1
param_type=2

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::bindParam() - 指定された変数名にパラメータをバインドする
  • PDOStatement::bindValue() - 値をパラメータにバインドする


文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

  • ≪ PDOStatement::debugDumpParams
  • PDOStatement::errorInfo ≫
  • PHP Manual
  • PDOStatement
  • 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

説明

public PDOStatement::errorCode(): ?string

パラメータ

この関数にはパラメータはありません。

戻り値

PDOStatement::errorCode() は PDOStatement オブジェクトを用いて実行された操作に対する エラーコードを取得することを除き、 PDO::errorCode() と等価です。

例

例1 SQLSTATE コードを取得する

<?php
/* エラーを発生させる -- BONES テーブルは存在しない */
$err = $dbh->prepare('SELECT skull FROM bones');
$err->execute();

echo "\nPDOStatement::errorCode(): ";
print $err->errorCode();
?>

上の例の出力は以下となります。

PDOStatement::errorCode(): 42S02

参考

  • PDO::errorCode() - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDO::errorInfo() - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::errorInfo() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する


文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

  • ≪ PDOStatement::errorCode
  • PDOStatement::execute ≫
  • PHP Manual
  • PDOStatement
  • 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

説明

public PDOStatement::errorInfo(): array

パラメータ

この関数にはパラメータはありません。

戻り値

PDOStatement::errorInfo() は、 この文ハンドラによって実行された直近の操作に関するエラー情報を 配列として返します。この配列は少なくとも次のフィールドを含みます。

要素 | 情報
0 | SQLSTATE エラーコード (これは、ANSI SQL 標準で定義された英数 5 文字の ID)
1 | ドライバ固有のエラーコード
2 | ドライバ固有のエラーメッセージ

例

例1 DB2 データベースに対する PDO_ODBC 接続の errorInfo() フィールドを表示する

<?php
/* エラーを発生させる -- BONES テーブルは存在しない */
$sth = $dbh->prepare('SELECT skull FROM bones');
$sth->execute();

echo "\nPDOStatement::errorInfo():\n";
$arr = $sth->errorInfo();
print_r($arr);
?>

上の例の出力は以下となります。

PDOStatement::errorInfo():
Array
(
    [0] => 42S02
    [1] => -204
    [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
)

参考

  • PDO::errorCode() - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
  • PDO::errorInfo() - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
  • PDOStatement::errorCode() - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する


プリペアドステートメントを実行する

  • ≪ PDOStatement::errorInfo
  • PDOStatement::fetch ≫
  • PHP Manual
  • PDOStatement
  • プリペアドステートメントを実行する

PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — プリペアドステートメントを実行する

説明

public PDOStatement::execute(?array $params = null): bool

プリペアドステートメントを実行します。 もし、プリペアドステートメントがパラメータマーカを含む場合、次のいずれかを行わなければなりません。

  • パラメータマーカに PHP 変数や値を(それぞれ)バインドするため PDOStatement::bindParam() や PDOStatement::bindValue() をコールする。 関連づけされたパラメータマーカがあれば、バインドされた変数は入力値を渡す もしくは出力値を受け取ります。

  • あるいは、入力専用のパラメータ値の配列を渡す

パラメータ

params

実行される SQL 文の中のバインドパラメータと同数の要素からなる、 値の配列。すべての値は PDO::PARAM_STR として扱われます。

ひとつのパラメータに対して複数の値をバインドすることはできません。 例えば、IN() 句の中のひとつのパラメータに対して 2 つの値をバインドすることはできません。

指定した数よりも多い値をバインドすることはできません。 params のキーが PDO::prepare() で指定した SQL にある数より多い場合は、 ステートメントが失敗してエラーが発生します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 変数や値のバインドを伴うプリペアドステートメントの実行

<?php
/* 変数や値のバインドを伴うプリペアドステートメントの実行 */
$calories = 150;
$colour = 'gre';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour LIKE :colour');
$sth->bindParam('calories', $calories, PDO::PARAM_INT);
/* 名前の前にも、コロン ":" を付けることができます(オプション) */
$sth->bindValue(':colour', "%$colour%");
$sth->execute();
?>

例2 名前付きの値を伴うプリペアドステートメントの実行

<?php
/* 入力値の配列を伴うプリペアドステートメントの実行 */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->execute(array('calories' => $calories, 'colour' => $colour));
/* 配列のキーの前にも、コロン ":" を付けることができます(オプション) */
$sth->execute(array(':calories' => $calories, ':colour' => $colour));
?>

例3 位置を指定した値を伴うプリペアドステートメントの実行

<?php
/* 入力値の配列を伴うプリペアドステートメントの実行 */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute(array($calories, $colour));
?>

例4 位置を指定したプレースホルダに、値をバインドした形でのプリペアドステートメントの実行

<?php
/* バインド変数を伴うプリペアドステートメントの実行 */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindParam(2, $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>

例5 IN 句で配列を使うプリペアドステートメントの実行

<?php
/* IN 句で配列を使うプリペアドステートメントの実行 */
$params = array(1, 21, 63, 171);
/* パラメータのプレースホルダ用の文字列を、パラメータ数に合わせて作ります */
$place_holders = implode(',', array_fill(0, count($params), '?'));

/*
これは、配列 $params のすべての値のための名前なしプレースホルダを含む
ステートメントを準備します。配列 $params の値をそこにバインドし、それから
ステートメントを実行します。これは PDOStatement::bindParam() を使うのとは
違います。こちらの場合は変数への参照が必要になるからです。
PDOStatement::execute() は、単に値だけをバインドします。
*/
$sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
$sth->execute($params);
?>

注意

注意:

ドライバによっては、次のステートメントを実行する前に カーソルを閉じ なければならないものもあります。

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::bindParam() - 指定された変数名にパラメータをバインドする
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchAll() - 結果セットから、残っている行を取得する
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す


結果セットから次の行を取得する

  • ≪ PDOStatement::execute
  • PDOStatement::fetchAll ≫
  • PHP Manual
  • PDOStatement
  • 結果セットから次の行を取得する

PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — 結果セットから次の行を取得する

説明

public PDOStatement::fetch(int $mode = PDO::FETCH_DEFAULT, int $cursorOrientation = PDO::FETCH_ORI_NEXT, int $cursorOffset = 0): mixed

PDOStatementオブジェクトに関連付けられた結果セットから1行取得します。 mode パラメータは、PDO がその行をどの様に返すかを決定します。

パラメータ

mode

次のレコードを呼び出し元に返す方法を制御します。
この値は、PDO::FETCH_* 定数のどれかで、
デフォルトは PDO::ATTR_DEFAULT_FETCH_MODE の値
(そのデフォルトは PDO::FETCH_BOTH) です。

  • PDO::FETCH_ASSOC: は、結果セットに 返された際のカラム名で添字を付けた配列を返します。

  • PDO::FETCH_BOTH (デフォルト): 結果セットに返された際のカラム名と 0 で始まるカラム番号で添字を付けた配列を返します。

  • PDO::FETCH_BOUND: true を返し、結果セットのカラムの値を PDOStatement::bindColumn() メソッドでバインドされた PHP 変数に代入します。

  • PDO::FETCH_CLASS: 結果セットのカラムがクラス内の名前付けされたプロパティに マッピングされている、要求されたクラスの新規インスタンスを返します。 PDO::FETCH_PROPS_LATE を指定していない限りは、 カラムをマッピングしてからクラスのコンストラクタを呼び出します。 mode に PDO::FETCH_CLASSTYPE が 含まれている場合 (例: PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE) は、最初のカラムの値から クラス名を決定します。

  • PDO::FETCH_INTO: 結果セットのカラムがクラス内の名前付けされたプロパティに マッピングされている要求された既存インスタンスを更新します。

  • PDO::FETCH_LAZY: PDO::FETCH_BOTH とPDO::FETCH_OBJの 組合せで、アクセスされるオブジェクトプロパティ名を作成する PDORow オブジェクトを返します。

  • PDO::FETCH_NAMED: PDO::FETCH_ASSOC と同じ形式の配列を返します。 ただし、同じ名前のカラムが複数あった場合は、そのキーが指す値は、 同じ名前のカラムのすべての値を含む配列になります。

  • PDO::FETCH_NUM: 結果セットに返された際の 0 から始まるカラム番号を添字とする配列を返します。

  • PDO::FETCH_OBJ: 結果セットに返された際のカラム名と同名のプロパティを有する 匿名のオブジェクトを返します。

  • PDO::FETCH_PROPS_LATE: PDO::FETCH_CLASS とともに使用すると、 まずクラスのコンストラクタを呼び出してから、カラムの値をプロパティに代入します。

cursorOrientation

スクロール可能なカーソルを表す PDOStatement オブジェクトの場合、 この値により呼び出し側に返される行を定義します。 この値は、PDO::FETCH_ORI_* 定数のどれかと する必要があり、 PDO::FETCH_ORI_NEXT がデフォルトとなっています。 PDOStatement に対してスクロール可能なカーソルを要求するためには、 PDO::prepare() を用いて SQL ステートメントを 準備する際、 PDO::CURSOR_SCROLL に PDO::ATTR_CURSOR 属性を設定する必要があります。

cursorOffset

スクロール可能なカーソルを表すPDOStatementオブジェクトの場合で、 cursorOrientation パラメータが PDO::FETCH_ORI_ABSに設定された場合、この値により 取得される結果セットの行の絶対位置が指定されます。

スクロール可能なカーソルを表すPDOStatementオブジェクトの場合で、 cursorOrientation パラメータが PDO::FETCH_ORI_RELに設定された場合、この値は、 PDOStatement::fetch() がコールされる前のカーソルの 位置を基準として取得する行の位置を指定します。

戻り値

この関数が成功した場合の戻り値は、取得形式によって異なります。 失敗した場合、または行が残っていない場合は、常に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 異なる取得方法で行を取得する

<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

/* Exercise PDOStatement::fetch styles */
print "PDO::FETCH_ASSOC: ";
print "Return next row as an array indexed by column name\n";
$result = $sth->fetch(PDO::FETCH_ASSOC);
print_r($result);
print "\n";

print "PDO::FETCH_BOTH: ";
print "Return next row as an array indexed by both column name and number\n";
$result = $sth->fetch(PDO::FETCH_BOTH);
print_r($result);
print "\n";

print "PDO::FETCH_LAZY: ";
print "Return next row as a PDORow object with column names as properties\n";
$result = $sth->fetch(PDO::FETCH_LAZY);
print $result->name;
print "\n";

print "PDO::FETCH_OBJ: ";
print "Return next row as an anonymous object with column names as properties\n";
$result = $sth->fetch(PDO::FETCH_OBJ);
print $result->NAME;
print "\n";
?>

上の例の出力は以下となります。

PDO::FETCH_ASSOC: Return next row as an array indexed by column name
Array
(
    [name] => apple
    [colour] => red
)

PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
Array
(
    [name] => banana
    [0] => banana
    [colour] => yellow
    [1] => yellow
)

PDO::FETCH_LAZY: Return next row as a PDORow object with column names as properties
PDORow Object
(
    [name] => orange
    [colour] => orange
)

PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
kiwi

例2 スクロール可能なカーソルで行を取得する

<?php
function readDataForwards($dbh) {
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
$stmt->execute();
while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
print $data;
}
}
function readDataBackwards($dbh) {
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
$stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
$stmt->execute();
$row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
do {
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
print $data;
} while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
}

print "Reading forwards:\n";
readDataForwards($conn);

print "Reading backwards:\n";
readDataBackwards($conn);
?>

上の例の出力は以下となります。

Reading forwards:
21    10    5
16    0     5
19    20    10

Reading backwards:
19    20    10
16    0     5
21    10    5

例3 構築の順序

PDO::FETCH_CLASS でオブジェクトを取得するときには、 まずオブジェクトのプロパティへの代入を終えてから、そのクラスのコンストラクタを実行します。 PDO::FETCH_PROPS_LATE を指定した場合はこの順序が逆転します。 つまり、まずコンストラクタを呼び出してから、プロパティへの代入を行います。

<?php
class Person
{
private $name;

public function __construct()
{
$this->tell();
}

public function tell()
{
if (isset($this->name)) {
echo "I am {$this->name}.\n";
} else {
echo "I don't have a name yet.\n";
}
}
}

$sth = $dbh->query("SELECT * FROM people");
$sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
$person = $sth->fetch();
$person->tell();
$sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
$person = $sth->fetch();
$person->tell();
?>

上の例の出力は、 たとえば以下のようになります。

I am Alice.
I am Alice.
I don't have a name yet.
I am Bob.

参考

  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::execute() - プリペアドステートメントを実行する
  • PDOStatement::fetchAll() - 結果セットから、残っている行を取得する
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す
  • PDOStatement::fetchObject() - 次の行を取得し、それをオブジェクトとして返す
  • PDOStatement::setFetchMode() - この文に対するデフォルトのフェッチモードを設定する


結果セットから、残っている行を取得する

  • ≪ PDOStatement::fetch
  • PDOStatement::fetchColumn ≫
  • PHP Manual
  • PDOStatement
  • 結果セットから、残っている行を取得する

PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — 結果セットから、残っている行を取得する

説明

public PDOStatement::fetchAll(int $mode = PDO::FETCH_DEFAULT): array
public PDOStatement::fetchAll(int $mode = PDO::FETCH_COLUMN, int $column): array
public PDOStatement::fetchAll(int $mode = PDO::FETCH_CLASS, string $class, ?array $constructorArgs): array
public PDOStatement::fetchAll(int $mode = PDO::FETCH_FUNC, callable $callback): array

パラメータ

mode

PDOStatement::fetch() で説明されている、返される配列の内容を制御します。
デフォルトは PDO::ATTR_DEFAULT_FETCH_MODE の値
(そのデフォルトは PDO::FETCH_BOTH) です。

結果セットから単一カラムの全ての値を含む配列を返す場合、 PDO::FETCH_COLUMN を指定します。 column パラメータにどのカラムを返すかを 指定することができます。

結果セットから単一カラムの一意な値のみ取得する場合、 PDO::FETCH_UNIQUE をビット OR した PDO::FETCH_COLUMN を指定します。

指定したカラムの値によってグループ化した連想配列を返す場合、 PDO::FETCH_GROUP をビット OR した PDO::FETCH_COLUMN を指定します。

以下は mode の値によって決まる動的なパラメータです。 これらは、名前付き引数と一緒に使うことは出来ません。
column

PDO::FETCH_COLUMN と一緒に使います。0 から始まる番号のカラムを返します。

class

PDO::FETCH_CLASS と一緒に使います。 ここで指定したクラスのインスタンスを返します。 各行のカラムがクラスのプロパティ名にマッピングされます。

constructorArg

mode が PDO::FETCH_CLASS のときに使う、独自のクラスコンストラクタへの引数。

callback

PDO::FETCH_FUNC と一緒に使います。 ここで指定した関数をコールした結果を返します。 各行のカラムを関数コール時のパラメータとします。

戻り値

PDOStatement::fetchAll() は、 結果セットに残っている全ての行を含む配列を返します。 この配列は、カラム値の配列もしくは各カラム名に対応するプロパティを持つオブジェクトとして各行を表します。 取得結果がゼロ件だった場合は空の配列を返します。

大きな結果セットをフェッチするためにこのメソッドを使用することは、 システムとネットワークリソースに大量の要求を行うことになります。 PHP で全てのデータ処理と操作を行うよりも、データベースサーバー側で 結果セットを操作することを検討してください。例えば、PHP で処理を行う前に SQL で WHERE 句や ORDER BY 句を使用し、結果を制限することです。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

変更履歴

バージョン | 説明
8.0.0 | このメソッドは、常に配列を返すようになりました。 これより前のバージョンでは、失敗した場合に false を返す可能性がありました。

例

例1 結果セットに残っている全ての行をフェッチする

<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

/* 結果セットに残っている全ての行をフェッチする */
print "Fetch all of the remaining rows in the result set:\n";
$result = $sth->fetchAll();
print_r($result);
?>

上の例の出力は、 たとえば以下のようになります。

Fetch all of the remaining rows in the result set:
Array
(
    [0] => Array
        (
            [name] => apple
            [0] => apple
            [colour] => red
            [1] => red
        )

    [1] => Array
        (
            [name] => pear
            [0] => pear
            [colour] => green
            [1] => green
        )

    [2] => Array
        (
            [name] => watermelon
            [0] => watermelon
            [colour] => pink
            [1] => pink
        )

)

例2 結果セットから単一カラムの全ての値を取得する

以下の例は、 SQL ステートメント自身が行毎に複数のカラムを返す場合において、 どのように結果セットから単一カラムの全ての値を取得するかを 例示しています。

<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

/* 最初のカラムの全ての値を取得する */
$result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

Array(3)
(
    [0] =>
    string(5) => apple
    [1] =>
    string(4) => pear
    [2] =>
    string(10) => watermelon
)

例3 単一カラムによる全ての値のグループ化

以下の例は、どのように結果セット中の特定のカラムの値によって グループ化された連想配列を返すかを例示しています。 その配列は 3 つのキーを有します。値 apple、 pear は異なる 2 つの異なる色を有する配列として返され、 一方 watermelon は 1 つの色のみ有する配列として返されます。

<?php
$insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
$insert->execute(array('apple', 'green'));
$insert->execute(array('pear', 'yellow'));

$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

/* 最初のカラムの値によってグループ化する */
var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["apple"]=>
  array(2) {
    [0]=>
    string(5) "green"
    [1]=>
    string(3) "red"
  }
  ["pear"]=>
  array(2) {
    [0]=>
    string(5) "green"
    [1]=>
    string(6) "yellow"
  }
  ["watermelon"]=>
  array(1) {
    [0]=>
    string(5) "pink"
  }
}

例4 各結果用のクラスのインスタンス作成

次の例は、 PDO::FETCH_CLASS の振る舞いを示すものです。

<?php
class fruit {
public $name;
public $colour;
}

$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

$result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  object(fruit)#1 (2) {
    ["name"]=>
    string(5) "apple"
    ["colour"]=>
    string(5) "green"
  }
  [1]=>
  object(fruit)#2 (2) {
    ["name"]=>
    string(4) "pear"
    ["colour"]=>
    string(6) "yellow"
  }
  [2]=>
  object(fruit)#3 (2) {
    ["name"]=>
    string(10) "watermelon"
    ["colour"]=>
    string(4) "pink"
  }
  [3]=>
  object(fruit)#4 (2) {
    ["name"]=>
    string(5) "apple"
    ["colour"]=>
    string(3) "red"
  }
  [4]=>
  object(fruit)#5 (2) {
    ["name"]=>
    string(4) "pear"
    ["colour"]=>
    string(5) "green"
  }
}

例5 各結果に対する関数コール

次の例は、 PDO::FETCH_FUNC の振る舞いを示すものです。

<?php
function fruit($name, $colour) {
return "{$name}: {$colour}";
}

$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

$result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(12) "apple: green"
  [1]=>
  string(12) "pear: yellow"
  [2]=>
  string(16) "watermelon: pink"
  [3]=>
  string(10) "apple: red"
  [4]=>
  string(11) "pear: green"
}

参考

  • PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す
  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::setFetchMode() - この文に対するデフォルトのフェッチモードを設定する


結果セットの次行から単一カラムを返す

  • ≪ PDOStatement::fetchAll
  • PDOStatement::fetchObject ≫
  • PHP Manual
  • PDOStatement
  • 結果セットの次行から単一カラムを返す

PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — 結果セットの次行から単一カラムを返す

説明

public PDOStatement::fetchColumn(int $column = 0): mixed

結果セットの次行から単一カラムを返します。 行がもうない場合には false を返します。

注意:

PDOStatement::fetchColumn() は、boolean のカラムを取得するときに使っていけません。 boolean 値としての false と、もう取得する行がない場合の false を区別できないからです。 かわりに PDOStatement::fetch() を使いましょう。

パラメータ

column

行から処理したい 0 で始まるカラム番号を指定します。 何も値が与えられない場合、 PDOStatement::fetchColumn() は最初のカラムをフェッチします。

戻り値

PDOStatement::fetchColumn() は結果セットの次行から単一カラムを返します。 それ以上行がない場合、false を返します。

警告

PDOStatement::fetchColumn() を使用してデータを処理する場合、同一行から 他のカラムを返す方法はありません。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 次行の最初のカラムを返す

<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();

print "Fetch the first column from the first row in the result set:\n";
$result = $sth->fetchColumn();
print "name = $result\n";

print "Fetch the second column from the second row in the result set:\n";
$result = $sth->fetchColumn(1);
print "colour = $result\n";
?>

上の例の出力は以下となります。

Fetch the first column from the first row in the result set:
name = lemon
Fetch the second column from the second row in the result set:
colour = red

参考

  • PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する
  • PDOStatement::fetch() - 結果セットから次の行を取得する
  • PDOStatement::fetchAll() - 結果セットから、残っている行を取得する
  • PDO::prepare() - 文を実行する準備を行い、文オブジェクトを返す
  • PDOStatement::setFetchMode() - この文に対するデフォルトのフェッチモードを設定する


次の行を取得し、それをオブジェクトとして返す

  • ≪ PDOStatement::fetchColumn
  • PDOStatement::getAttribute ≫
  • PHP Manual
  • PDOStatement
  • 次の行を取得し、それをオブジェクトとして返す

PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — 次の行を取得し、それをオブジェクトとして返す

説明

public PDOStatement::fetchObject(?string $class = "stdClass", array $constructorArgs = []): object|false

次の行を取得し、それをオブジェクトとして返します。この関数は、
PDOStatement::fetch() で
PDO::FETCH_CLASS あるいは
PDO::FETCH_OBJ を指定することの代替関数となります。

オブジェクトを取得する際には、各カラムの値を対応するプロパティに代入してから、 そのコンストラクタを実行します。

パラメータ

class

作成されるクラスの名前。

constructorArgs

この配列の要素がコンストラクタに渡されます。

戻り値

カラム名に対応するプロパティを保持する、要求されたクラスの インスタンスを返します。失敗した場合に false を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

参考

  • PDOStatement::fetch() - 結果セットから次の行を取得する


文の属性を取得する

  • ≪ PDOStatement::fetchObject
  • PDOStatement::getColumnMeta ≫
  • PHP Manual
  • PDOStatement
  • 文の属性を取得する

PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — 文の属性を取得する

説明

public PDOStatement::getAttribute(int $name): mixed

文の属性を取得します。現時点で共通の属性は存在しませんが、 ドライバ固有の属性のみ存在します。

  • PDO::ATTR_CURSOR_NAME (Firebird と ODBC 固有): UPDATE ... WHERE CURRENT OF に対するカーソル名を取得する

ドライバ固有の属性は、 他のドライバでは使っては いけない ことに注意して下さい。

パラメータ

name

問い合わせる属性の名前。

戻り値

属性の値を返します。

参考

  • PDO::getAttribute() - データベース接続の属性を取得する
  • PDO::setAttribute() - 属性を設定する
  • PDOStatement::setAttribute() - 文の属性を設定する


結果セットのカラムに対するメタデータを返す

  • ≪ PDOStatement::getAttribute
  • PDOStatement::getIterator ≫
  • PHP Manual
  • PDOStatement
  • 結果セットのカラムに対するメタデータを返す

PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — 結果セットのカラムに対するメタデータを返す

説明

public PDOStatement::getColumnMeta(int $column): array|false

結果セットの 0 から始まるカラムに対するメタデータを連想配列で取得します。

警告

PDO ドライバによっては、 PDOStatement::getColumnMeta() を実装していないかもしれません。 なぜなら、これはオプションだからです。 しかし、このマニュアルでドキュメント化されている全ての PDO ドライバ はこの関数を実装しています。

パラメータ

column

結果セットの 0 から始まるカラムを指定します。

戻り値

1つのカラムについてのメタデータに相当する次の値を含んだ連想配列を返します。

カラムのメタデータ
名前 | 値
native_type | カラム値を表現するために使用される PHP のネイティブ型
driver:decl_type | データベースにおけるカラム値を表現するために使用される SQL 型。 もし、結果セットのカラムが関数から返される場合、 この値は PDOStatement::getColumnMeta(). よって返されません。
flags | このカラムにセットされているあらゆるフラグ
name | データベースによって返されるこのカラムの名前
table | データベースによって返されるこのカラムのテーブル名
len | カラム長。浮動小数点数以外の型については通常 -1 となる。
precision | カラムの数値精度。浮動小数点数以外の型については通常 0 となる。
pdo_type | PDO::PARAM_* 定数 によって表現されるカラムの型

要求されたカラムが結果セットに存在しない、 もしくは結果セットが存在しない場合、false を返します。

例

例1 カラムのメタデータを取得する

以下の例は、PDO_SQLITE ドライバでの関数 (COUNT) によって生成された単一のカラムに対するメタデータの 取得結果を表示します。

<?php
$select = $DB->query('SELECT COUNT(*) FROM fruit');
$meta = $select->getColumnMeta(0);
var_dump($meta);
?>

上の例の出力は以下となります。

array(6) {
  ["native_type"]=>
  string(7) "integer"
  ["flags"]=>
  array(0) {
  }
  ["name"]=>
  string(8) "COUNT(*)"
  ["len"]=>
  int(-1)
  ["precision"]=>
  int(0)
  ["pdo_type"]=>
  int(2)
}

参考

  • PDOStatement::columnCount() - 結果セット中のカラム数を返す
  • PDOStatement::rowCount() - 直近の SQL ステートメントによって作用した行数を返す


結果セットのイテレータを取得する

  • ≪ PDOStatement::getColumnMeta
  • PDOStatement::nextRowset ≫
  • PHP Manual
  • PDOStatement
  • 結果セットのイテレータを取得する

PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — 結果セットのイテレータを取得する

説明

public PDOStatement::getIterator(): Iterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


複数の行セットを返す文ハンドラで次の行セットに移動する

  • ≪ PDOStatement::getIterator
  • PDOStatement::rowCount ≫
  • PHP Manual
  • PDOStatement
  • 複数の行セットを返す文ハンドラで次の行セットに移動する

PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する

説明

public PDOStatement::nextRowset(): bool

いくつかのデータベースサーバーは、1つ以上の行セット (結果セットとしても知られる) を返すストアドプロシージャをサポートしています。 PDOStatement::nextRowSet() により、2 番目以降の PDOStatement オブジェクトに関連する行セットにアクセスすることができます。 それぞれの行セットは、 前の行セットと異なるカラムセットを含むことができます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ストアドプロシージャから複数の行セットをフェッチする

以下のサンプルは、3つの行セット (MULTIPLE_ROWSETS) を返すストアドプロシージャのコールの仕方を示しています。 PDOStatement::nextRowset() が false を返し、 行セットが返されなくなったとき、 do-while ループ を終了させています。

<?php
$sql = 'CALL multiple_rowsets()';
$stmt = $conn->query($sql);
$i = 1;
do {
$rowset = $stmt->fetchAll(PDO::FETCH_NUM);
if ($rowset) {
printResultSet($rowset, $i);
}
$i++;
} while ($stmt->nextRowset());

function printResultSet(&$rowset, $i) {
print "Result set $i:\n";
foreach ($rowset as $row) {
foreach ($row as $col) {
print $col . "\t";
}
print "\n";
}
print "\n";
}
?>

上の例の出力は以下となります。

Result set 1:
apple    red
banana   yellow

Result set 2:
orange   orange    150
banana   yellow    175

Result set 3:
lime     green
apple    red
banana   yellow

参考

  • PDOStatement::columnCount() - 結果セット中のカラム数を返す
  • PDOStatement::execute() - プリペアドステートメントを実行する
  • PDOStatement::getColumnMeta() - 結果セットのカラムに対するメタデータを返す
  • PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する


直近の SQL ステートメントによって作用した行数を返す

  • ≪ PDOStatement::nextRowset
  • PDOStatement::setAttribute ≫
  • PHP Manual
  • PDOStatement
  • 直近の SQL ステートメントによって作用した行数を返す

PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す

説明

public PDOStatement::rowCount(): int

PDOStatement::rowCount() は 相当する PDOStatement オブジェクトによって実行された 直近の DELETE, INSERT, UPDATE 文によって作用した行数を返します。

SELECT文のような、結果セットを生成するSQLステートメントについては動作が未定義です。 動作はドライバによって異なる可能性があります。 データベース(例: MySQL のバッファリングモード)によっては、文によって返された行数を返すかもしれません。しかしながら、 この振る舞いは全てのデータベースで保証されていません。 さまざまな場所で使用するアプリケーションでは、 これに頼ってはいけません。

注意:

このメソッドは SQLite ドライバの場合はあらゆる場合に "0" (ゼロ) を返します。 PostgreSQL ドライバの場合は ステートメント属性 PDO::ATTR_CURSOR の設定が PDO::CURSOR_SCROLL の場合にだけ "0" (ゼロ) を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

行の数を返します。

エラー / 例外

PDO::ATTR_ERRMODE が PDO::ERRMODE_WARNING に設定されていた場合、E_WARNING レベルのエラーが発生します。

PDO::ATTR_ERRMODE が PDO::ERRMODE_EXCEPTION に設定されていた場合、PDOException がスローされます。

例

例1 削除された行数を返す

PDOStatement::rowCount() は DELETE, INSERT, UPDATE 文によって作用した行数を返します。

<?php
/* FRUIT テーブルから全ての行を削除する */
$del = $dbh->prepare('DELETE FROM fruit');
$del->execute();

/* 削除された行数を返す */
print "Return number of rows that were deleted:\n";
$count = $del->rowCount();
print "Deleted $count rows.\n";
?>

上の例の出力は、 たとえば以下のようになります。

Return number of rows that were deleted:
Deleted 9 rows.

例2 SELECT 文によって返された行をカウントする

ほとんどのデータベースでは、PDOStatement::rowCount() は SELECT 文によって作用した行数を返しません。代わりに、 PDO::query() を使って 意図する SELECT 文として同様の述部を持つ SELECT COUNT(*) 文を発行し、PDOStatement::fetchColumn() を使って返される行数を取得することができます。

<?php
$sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
$res = $conn->query($sql);
$count = $res->fetchColumn();
print "There are " . $count . " matching records.";

上の例の出力は、 たとえば以下のようになります。

There are 2 matching records.

参考

  • PDOStatement::columnCount() - 結果セット中のカラム数を返す
  • PDOStatement::fetchColumn() - 結果セットの次行から単一カラムを返す
  • PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する


文の属性を設定する

  • ≪ PDOStatement::rowCount
  • PDOStatement::setFetchMode ≫
  • PHP Manual
  • PDOStatement
  • 文の属性を設定する

PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — 文の属性を設定する

説明

public PDOStatement::setAttribute(int $attribute, mixed $value): bool

文の属性を設定します。現時点で共通の属性は存在しませんが、 ドライバ固有の属性のみ存在します。

  • PDO::ATTR_CURSOR_NAME (Firebird と ODBC 固有): UPDATE ... WHERE CURRENT OF に対するカーソル名を取得する

ドライバ固有の属性は、 他のドライバでは使っては いけない ことに注意して下さい。

パラメータ

attribute

変更する属性。

value

attribute に設定する値。 属性によっては、特定の型が必要かもしれません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • PDO::getAttribute() - データベース接続の属性を取得する
  • PDO::setAttribute() - 属性を設定する
  • PDOStatement::getAttribute() - 文の属性を取得する


この文に対するデフォルトのフェッチモードを設定する

  • ≪ PDOStatement::setAttribute
  • PDOException ≫
  • PHP Manual
  • PDOStatement
  • この文に対するデフォルトのフェッチモードを設定する

PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する

説明

public PDOStatement::setFetchMode(int $mode): bool
public PDOStatement::setFetchMode(int $mode = PDO::FETCH_COLUMN, int $colno): bool
public PDOStatement::setFetchMode(int $mode = PDO::FETCH_CLASS, string $class, ?array $constructorArgs = null): bool
public PDOStatement::setFetchMode(int $mode = PDO::FETCH_INTO, object $object): bool

パラメータ

mode

フェッチモードは、PDO::FETCH_* 定数の 1つでなければなりません。

colno

カラム番号。

class

クラス名。

constructorArgs

コンストラクタの引数。

object

オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 フェッチモードを設定する

以下の例は PDOStatement::setFetchMode() がどの様に PDOStatementオブジェクトに対するデフォルトのフェッチモードを 変更するかを例示しています。

<?php
$stmt = $dbh->query('SELECT name, colour, calories FROM fruit');
$stmt->setFetchMode(PDO::FETCH_NUM);
foreach ($stmt as $row) {
print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
}

上の例の出力は以下となります。

apple   red     150
banana  yellow  250
orange  orange  300
kiwi    brown   75
lemon   yellow  25
pear    green   150


PDOException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

PDO が発するエラーを表します。あなた自身が書いたコードから PDOException をスローしてはいけません。 PHP の例外についての詳細な情報は、 例外 を参照ください。

クラス概要

class PDOException extends RuntimeException {
/* プロパティ */
protected int|string $code;
public ?array $errorInfo = null;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

errorInfo

PDO::errorInfo() あるいは PDOStatement::errorInfo() に対応します。

code

SQLSTATE エラーコード。 Exception::getCode() でアクセスします。


PDORow クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

はじめに

フェッチモード PDO_FETCH_LAZY を使って PDOStatement::fetch() をコールした場合に返される 結果セットの行を表します。

このクラスのオブジェクトは、インスタンス化できませんし、 シリアライズもできません。 デフォルトの queryString プロパティに加えて PDORow オブジェクトは アクセスした結果セットに存在するカラム名に対応するプロパティを作成します。

PDORow は、 PDO::FETCH_OBJ と PDO::FETCH_BOTH のモードを両方使ったかのように、返されるデータにアクセスできます。 つまり、返されるデータはオブジェクトのプロパティのようにアクセスできますし、 カラム名やカラムのオフセット番号でインデックスされた配列としてもアクセスできます。

プロパティが未定義の場合は、警告を発生させることなく null を返します。

クラス概要

final class PDORow {
/* プロパティ */
public string $queryString;
}

プロパティ

queryString

PDORow オブジェクトを返した PDOStatement が使うクエリストリング

エラー / 例外

任意のプロパティに書き込んだり、 unset() を行おうとすると Error がスローされます。


PDO ドライバ

目次

  • CUBRID (PDO)
  • MS SQL Server (PDO)
  • Firebird (PDO)
  • IBM (PDO)
  • Informix (PDO)
  • MySQL (PDO)
  • MS SQL Server (PDO)
  • Oracle (PDO)
  • ODBC and DB2 (PDO)
  • PostgreSQL (PDO)
  • SQLite (PDO)

以下のドライバが現在 PDO インターフェイスを実装しています。

ドライバ名 | サポートされるデータベース
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.x/5.x/8.x
PDO_OCI | Oracle Call Interface
PDO_ODBC | ODBC v3 (IBM DB2、unixODBC そして win32 ODBC)
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 と SQLite 2
PDO_SQLSRV | Microsoft SQL Server / SQL Azure


CUBRID 関数 (PDO_CUBRID)

はじめに

PDO_CUBRID は PHP Data Objects (PDO) インターフェイス を実装したドライバで、PHP から CUBRID データベースにアクセスするためのものです。

注意:

現在のバージョンの PDO_CUBRID は、持続的接続に対応していません。

インストール手順

PDO_CUBRID 拡張モジュールをビルドするには、PHP を動かしているシステム上に CUBRID DBMS をインストールしなければなりません。 PDO_CUBRID は » PECL 拡張モジュールなので、 PECL 拡張モジュールのインストール の手順に従えば PDO_CUBRID をインストールできます。configure コマンドを実行するときに、次のようにして CUBRID のベースディレクトリの場所を指定します。

   $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]
configure コマンドはデフォルトで、環境変数 CUBRID の値を使います。

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください Linux や Windows への手動でのインストールに関する詳細な情報は、 PECL の CUBRID パッケージに含まれる build-guide.html を参照ください。

PDO_CUBRID の機能

スクロール可能なカーソル

PDO_CUBRID はスクロール可能なカーソルをサポートしており、デフォルトの型は前進のみのカーソルです。 PDO::prepare() の driver_options パラメータを使えばカーソルの型を変えることができます。

タイムアウト

PDO_CUBRID は sql ステートメントの実行時のタイムアウトの設定をサポートしています。 PDO::setAttribute() を使えばタイムアウトの値を設定できます。

Autocommit_mode およびトランザクション

PDO_CUBRID は自動コミットとトランザクションをサポートしており、 自動コミットモードがデフォルトで有効になっています。 PDO::setAttribute() を使えば状態を変更することができます。

PDO::beginTransaction() でトランザクションを開始すると
autocommit_mode は自動的に無効となり、PDO::commit() あるいは
PDO::rollBack() の後で元の状態に戻します。

注意: autocommit_mode を無効にする前に、 それまでの作業は自動的にコミットされることに注意しましょう。

複数の SQL 文

PDO_CUBRID は複数の SQL 文をサポートしています。 複数の SQL 文はセミコロン (;) で区切られます。

スキーマ情報

PDO_CUBRID では PDO::cubrid_schema() 関数を用意しており、これでスキーマ情報を取得します。

LOBs

PDO_CUBRID は BLOB/CLOB データ型をサポートしています。PDO における LOB はストリームで表現されているので、LOB を追加するにはストリームをバインドし、 LOB を取得するには CUBRID PDO が返すストリームを読み込みます。

例1 CUBRID PDO での LOB の追加

<?php
$fp = fopen('lob_test.png', 'rb');

$sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

$stmt = $dbh->prepare($sql_stmt);
$ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
$ret = $stmt->execute();
?>

例2 CUBRID PDO での LOB の取得

<?php
$sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

$stmt = $dbh->prepare($sql_stmt);
$stmt->execute();
$result = $stmt->fetch(PDO::FETCH_NUM);

header("Content-Type: image/png");
fpassthru($result[0]);
?>

カラムのメタ情報

CUBRID PDO における PDOStatement::getColumnMeta() は、次の値を含む連想配列を返します。

  • type
  • name
  • table
  • def
  • precision
  • scale
  • not_null
  • auto_increment
  • unique_key
  • multiple_key
  • primary_key
  • foreign_key
  • reverse_index
  • reverse_unique

コレクションデータ型

PDO_CUBRID は SET/MULTISET/SEQUENCE といったコレクションに対応しています。 データ型を省略した場合のデフォルトは char で、次の例のようになります。

例3 CUBRID PDO で、デフォルトのデータ型のセットを追加する例

<?php
$conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
$cubrid_pdo = new PDO($conn_str, 'dba', '');

$cubrid_pdo->exec("DROP TABLE if exists test_tbl");
$cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

$sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
$stmt = $cubrid_pdo->prepare($sql_stmt_insert);
$data = array("abc","def","ghi");
$ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);
$ret = $stmt->execute();
var_Dump($ret);
?>

例4 CUBRID PDO でのセットの追加でデータ型を指定する例

<?php
$conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
$cubrid_pdo = new PDO($conn_str, 'dba', '');

$cubrid_pdo->exec("DROP TABLE if exists test_tbl");
$cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

$sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
$stmt = $cubrid_pdo->prepare($sql_stmt_insert);
$data = array(1,2,3,4);
$ret = $stmt->bindParam(1, $data, 0,0,"int");
$ret = $stmt->execute();
var_Dump($ret);
?>

CUBRID のバインドデータ型 (PDOStatement::bindParam() の五番目のパラメータ):

  • CHAR
  • STRING
  • NCHAR
  • VARNCHAR
  • BIT
  • VARBIT
  • NUMERIC
  • NUMBER
  • INT
  • SHORT
  • BIGINT
  • MONETARY
  • FLOAT
  • DOUBLE
  • DATE
  • TIME
  • DATETIME
  • TIMESTAMP

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

これらの定数を使ってデータベースの属性を設定します。これらの定数は PDO::getAttribute() あるいは PDO::setAttribute() に渡します。

PDO::CUBRID 属性フラグ
定数 | 説明
PDO::CUBRID_ATTR_ISOLATION_LEVEL | データベース接続に指定するトランザクション分離レベル。
PDO::CUBRID_ATTR_LOCK_TIMEOUT | トランザクションのタイムアウト秒数。
PDO::CUBRID_ATTR_MAX_STRING_LENGTH | 読み込み専用。CUBRID PDO API を使うときの bit, varbit, char, varchar, nchar, nchar varying データ型の最大文字数。

これらの定数を使ってトランザクション分離レベルを設定します。これらの定数は PDO::getAttribute() に渡したり PDO::setAttribute() から返されたりします。

PDO::CUBRID 分離レベルフラグ
定数 | 説明
PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE | 最も低い分離レベル (1)。タプルについて ダーティリード、ノンリピータブルリード、ファントムリードが発生し、 テーブルについてもノンリピータブルリードが発生します。
PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE | 比較的低い分離レベル (2)。ダーティリードは発生しませんが、 ノンリピータブルリードやファントムリードは発生します。
PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE | CUBRID のデフォルトの分離レベル (3)。タプルについては ダーティリード、ノンリピータブルリード、ファントムリードが発生しますが、 テーブルについてはリピータブルリードが保証されています。
PDO::TRAN_REP_CLASS_COMMIT_INSTANCE | 比較的低い分離レベル (4)。ダーティリードは発生しませんが、 ノンリピータブルリードやファントムリードは発生します。
PDO::TRAN_REP_CLASS_REP_INSTANCE | 比較的高い分離レベル (5)。ダーティリードやノンリピータブルリードは発生しませんが、 ファントムリードは発生します。
PDO::TRAN_SERIALIZABLE | 最も高い分離レベル (6)。並行性に関する問題 (ダーティリード、ノンリピータブルリード、ファントムリードなど) は発生しません。

これらの定数を使ってスキーマ情報を取得します。これらの定数は PDO::cubrid_schema() に渡します。

PDO::CUBRID スキーマフラグ
定数 | 説明
PDO::CUBRID_SCH_TABLE | CUBRID のテーブルの名前と型を取得します。
PDO::CUBRID_SCH_VIEW | CUBRID のビューの名前と型を取得します。
PDO::CUBRID_SCH_QUERY_SPEC | ビューのクエリ定義を取得します。
PDO::CUBRID_SCH_ATTRIBUTE | テーブルのカラムの属性を取得します。
PDO::CUBRID_SCH_TABLE_ATTRIBUTE | テーブルの属性を取得します。
PDO::CUBRID_SCH_METHOD | インスタンスメソッドを取得します。インスタンスメソッドはクラスのインスタンスからコールされるメソッドです。 たいていの操作はインスタンス上で行われるので、クラスメソッドよりも頻繁に使います。
PDO::CUBRID_SCH_TABLE_METHOD | クラスメソッドを取得します。クラスメソッドはクラスオブジェクトからコールされるメソッドです。 新しいクラスのインスタンスを作ったり初期化したりするときによく使います。 また、クラスの属性にアクセスしたりそれを更新したりするときにも使います。
PDO::CUBRID_SCH_METHOD_FILE | テーブルのメソッドが定義されているファイルの情報を取得します。
PDO::CUBRID_SCH_SUPER_TABLE | このテーブルの属性の継承元のテーブルの名前と型を取得します。
PDO::CUBRID_SCH_SUB_TABLE | このテーブルの属性を継承しているテーブルの名前と型を取得します。
PDO::CUBRID_SCH_CONSTRAINT | テーブルの制約を取得します。
PDO::CUBRID_SCH_TRIGGER | テーブルのトリガーを取得します。
PDO::CUBRID_SCH_TABLE_PRIVILEGE | テーブルの権限情報を取得します。
PDO::CUBRID_SCH_COL_PRIVILEGE | カラムの権限情報を取得します。
PDO::CUBRID_SCH_DIRECT_SUPER_TABLE | 直接の親テーブルを取得します。
PDO::CUBRID_SCH_PRIMARY_KEY | テーブルの主キーを取得します。
PDO::CUBRID_SCH_IMPORTED_KEYS | テーブルのインポートしたキーを取得します。
PDO::CUBRID_SCH_EXPORTED_KEYS | テーブルのエクスポートしたキーを取得します。
PDO::CUBRID_SCH_CROSS_REFERENCE | ふたつのテーブルの参照関係を取得します。

目次

  • PDO_CUBRID DSN — CUBRID データベースへの接続
  • PDO::cubrid_schema — 指定したスキーマ情報を取得する


CUBRID データベースへの接続

  • ≪ CUBRID (PDO)
  • PDO::cubrid_schema ≫
  • PHP Manual
  • CUBRID (PDO)
  • CUBRID データベースへの接続

PDO_CUBRID DSN

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO_CUBRID DSN — CUBRID データベースへの接続

説明

PDO_CUBRID のデータソース名 (DSN) は次の要素をセミコロン区切りで表したものです:

DSN プレフィックス

DSN プレフィックスは cubrid: です。

host

データベースサーバーのあるホスト名。

port

データベースサーバーが動いているポート。

dbname

データベースの名前。

注意

注意:

CUBRID との接続を確立するには、DSN 以外にもユーザー名とパスワードが必要です。

例

例1 PDO_CUBRID DSN の例

CUBRID データベースに接続するための PDO_CUBRID DSN の例です:

cubrid:host=localhost;port=33000;dbname=demodb


指定したスキーマ情報を取得する

  • ≪ PDO_CUBRID DSN
  • MS SQL Server (PDO) ≫
  • PHP Manual
  • CUBRID (PDO)
  • 指定したスキーマ情報を取得する

PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — 指定したスキーマ情報を取得する

説明

public PDO::cubrid_schema(int $schema_type, string $table_name = ?, string $col_name = ?): array

指定したスキーマ情報をデータベースから取得します。 テーブルの情報を知りたい場合は table_name を指定しなければなりません。また、 カラムの情報を知りたければ col_name を指定しなければなりません (PDO::CUBRID_SCH_COL_PRIVILEGE とともにしか使えません)。

この関数の返す結果は二次元の配列になります (column (associative array) * row (numeric array))。 次の表は、スキーマの型と戻り値の構造を示したものです。

型ごとの戻り値の構造
スキーマ | カラム番号 | カラム名 | 値
PDO::CUBRID_SCH_TABLE | 1 | NAME |
 | 2 | TYPE | 0:システムテーブル 1:ビュー 2:テーブル
PDO::CUBRID_SCH_VIEW | 1 | NAME |
 | 2 | TYPE | 1:ビュー
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
 | 2 | DOMAIN |
 | 3 | SCALE |
 | 4 | PRECISION |
 | 5 | INDEXED | 1:インデックス
 | 6 | NOT NULL | 1:not null
 | 7 | SHARED | 1:共有
 | 8 | UNIQUE | 1:unique
 | 9 | DEFAULT |
 | 10 | ATTR_ORDER | base:1
 | 11 | CLASS_NAME |
 | 12 | SOURCE_CLASS |
 | 13 | IS_KEY | 1:キー
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
 | 2 | RET_DOMAIN |
 | 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
 | 2 | TYPE | 0:システムテーブル 1:ビュー 2:テーブル
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
 | 2 | NAME |
 | 3 | ATTR_NAME |
 | 4 | NUM_PAGES |
 | 5 | NUM_KEYS |
 | 6 | PRIMARY_KEY | 1:主キー
 | 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
 | 2 | STATUS |
 | 3 | EVENT |
 | 4 | TARGET_CLASS |
 | 5 | TARGET_ATTR |
 | 6 | ACTION_TIME |
 | 7 | ACTION |
 | 8 | PRIORITY |
 | 9 | CONDITION_TIME |
 | 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
 | 2 | PRIVILEGE |
 | 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
 | 2 | ATTR_NAME |
 | 3 | KEY_SEQ | base:1
 | 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
 | 2 | PKCOLUMN_NAME |
 | 3 | FKTABLE_NAME | base:1
 | 4 | FKCOLUMN_NAME |
 | 5 | KEY_SEQ | base:1
 | 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
 | 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
 | 8 | FK_NAME |
 | 9 | PK_NAME |

パラメータ

schema_type

知りたいスキーマの型。

table_name

スキーマを知りたいテーブル。

col_name

スキーマを知りたいカラム。

戻り値

処理に成功すると、スキーマ情報を含む配列を返します。

処理に失敗した場合は FALSE を返します。

例

例1 PDO::cubrid_schema() の例

これは、game テーブルの主キーと外部キーを取得する例です。

<?php
$pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
print_r($pk_list);

$fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
print_r($fk_list);
?>

上の例の出力は以下となります。

Result:
Array
(
    [0] => Array
        (
            [CLASS_NAME] => game
            [ATTR_NAME] => athlete_code
            [KEY_SEQ] => 3
            [KEY_NAME] => pk_game_host_year_event_code_athlete_code
        )

    [1] => Array
        (
            [CLASS_NAME] => game
            [ATTR_NAME] => event_code
            [KEY_SEQ] => 2
            [KEY_NAME] => pk_game_host_year_event_code_athlete_code
        )

    [2] => Array
        (
            [CLASS_NAME] => game
            [ATTR_NAME] => host_year
            [KEY_SEQ] => 1
            [KEY_NAME] => pk_game_host_year_event_code_athlete_code
        )

)
Array
(
    [0] => Array
        (
            [PKTABLE_NAME] => athlete
            [PKCOLUMN_NAME] => code
            [FKTABLE_NAME] => game
            [FKCOLUMN_NAME] => athlete_code
            [KEY_SEQ] => 1
            [UPDATE_RULE] => 1
            [DELETE_RULE] => 1
            [FK_NAME] => fk_game_athlete_code
            [PK_NAME] => pk_athlete_code
        )

    [1] => Array
        (
            [PKTABLE_NAME] => event
            [PKCOLUMN_NAME] => code
            [FKTABLE_NAME] => game
            [FKCOLUMN_NAME] => event_code
            [KEY_SEQ] => 1
            [UPDATE_RULE] => 1
            [DELETE_RULE] => 1
            [FK_NAME] => fk_game_event_code
            [PK_NAME] => pk_event_code
        )

)


Microsoft SQL Server および Sybase 関数 (PDO_DBLIB)

はじめに

PDO_DBLIB は PHP Data Objects (PDO) インターフェイスを実装したドライバで、 PHP から Microsoft SQL Server および Sybase データベースに対して FreeTDS ライブラリを使用したアクセスが可能となります。

この拡張モジュールは、Windows 版では使えません。

Windows では、Microsoft が » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx で公開しているもうひとつの MS SQL 用ドライバである SqlSrv を使わなければなりません。

SqlSrv を使うことができない場合は、 PDO_ODBC ドライバを使えば Microsoft SQL Server や Sybase データベースに接続することができます。 Windows ネイティブの DB-LIB は既に古くなっており、 スレッドセーフでもなく Microsoft ももうサポートしていません。

目次

  • PDO_DBLIB DSN — Microsoft SQL Server および Sybase データベースに接続する


Microsoft SQL Server および Sybase データベースに接続する

  • ≪ MS SQL Server (PDO)
  • Firebird (PDO) ≫
  • PHP Manual
  • MS SQL Server (PDO)
  • Microsoft SQL Server および Sybase データベースに接続する

PDO_DBLIB DSN

(PECL PDO_DBLIB >= 0.9.0)

PDO_DBLIB DSN — Microsoft SQL Server および Sybase データベースに接続する

説明

PDO_DBLIB データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

PDO_DBLIB が Sybase ct-lib ライブラリに対してリンクされている場合は DSN 接頭辞は sybase: です。 Microsoft SQL Server ライブラリに対してリンクされている場合は mssql:、そして FreeTDS ライブラリに対してリンクされている場合は dblib: となります。

host

データベースサーバーが存在するホスト名を指定します。 デフォルトは 127.0.0.1 です。

dbname

データベース名を指定します。

charset

クライアントの文字セットを指定します。

appname

アプリケーション名を指定します (sysprocesses で使用します)。 デフォルトは "PHP Generic DB-lib" あるいは "PHP freetds" です。

secure

現在は未使用です。

例

例1 PDO_DBLIB DSN の例

以下の例は、Microsoft SQL Server および Sybase データベースに接続するための PDO_DBLIB DSN を表します。

mssql:host=localhost;dbname=testdb
sybase:host=localhost;dbname=testdb
dblib:host=localhost;dbname=testdb


Firebird 関数 (PDO_FIREBIRD)

はじめに

PDO_FIREBIRD は、PHP から Firebird データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

インストール手順

--with-pdo-firebird[=DIR] で PDO Firebird 拡張モジュールをインストールします。オプションの [=DIR] には、Firebird の基底インストールディレクトリを指定することができます。

$ ./configure --with-pdo-firebird

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::FB_ATTR_DATE_FORMAT (int)

日付フォーマットを設定します。

PDO::FB_ATTR_TIME_FORMAT (int)

時刻フォーマットを設定します。

PDO::FB_ATTR_TIMESTAMP_FORMAT (int)

タイムスタンプフォーマットを設定します。

目次

  • PDO_FIREBIRD DSN — Firebird データベースに接続する


Firebird データベースに接続する

  • ≪ Firebird (PDO)
  • IBM (PDO) ≫
  • PHP Manual
  • Firebird (PDO)
  • Firebird データベースに接続する

PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Firebird データベースに接続する

説明

PDO_FIREBIRD データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は firebird: です。

dbname

データベース名を指定します。

charset

文字セット。

role

SQL のロール名。

dialect

データベースの方言。1 または 3 の値を取ります。 指定されなかった場合は、デフォルトの 3 が使われます。 PHP 7.4.0 以降で利用可能です。

例

例1 PDO_FIREBIRD DSN でのパス指定の例

以下の例は、Firebird データベースに接続するための PDO_FIREBIRD DSN を表します。

firebird:dbname=/path/to/DATABASE.FDB

例2 PDO_FIREBIRD DSN でのポートとパス指定の例

以下の例は、ポートとパスを指定して Firebird データベースに接続するための PDO_FIREBIRD DSN を表します。

firebird:dbname=hostname/port:/path/to/DATABASE.FDB

例3 PDO_FIREBIRD DSN で Debian システムのローカルホストと employee.fdb へのパスを使う例

以下の例は、ローカルホストの Firebird データベース employee.fdb に接続するための PDO_FIREBIRD DSN を表します。

firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

例4 方言が 1 のデータベースに接続するための PDO_FIREBIRD の DSN

次の例は、方言 1 を使って作られた Firebird データベース test.fdb に対して 接続するための PDO_FIREBIRD DSN を示しています。 これは、PHP 7.4.0 以降でのみ利用可能です。

firebird:dbname=localhost:/var/lib/firebird/2.5/data/test.fdb;CHARSET=shift-jis;dialect=1


IBM 関数 (PDO_IBM)

はじめに

PDO_IBM は PHP Data Objects (PDO) インターフェイスを実装したドライバで、 PHP から IBM のデータベースにアクセスできるようになります。

インストール手順

PDO_IBM 拡張モジュールをビルドするには、DB2 クライアントの v9.1 以降がシステムにインストールされている必要があります。 DB2 クライアントは、IBM の » Application Development Site からダウンロードできます。

注意: 注意

DB2 クライアント v9.1 以降では、DB2 for Linux、 UNIX および Windows の v8、v9.1 サーバーへの直接接続がサポートされています。

DB2 クライアント v9.1 は、DB2 UDB for i5 および DB2 UDB for z/OS servers への接続もサポートしています。この接続には、 別途 » DB2 Connect product を購入します。

PDO_IBM は » PECL 拡張モジュールです。 PECL 拡張モジュールのインストール の手順に従って PDO_IBM 拡張モジュールをインストールします。configure コマンドを発行し、 DB2 クライアントのヘッダファイルやライブラリの位置を以下のように指定します。

bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]
configure コマンドは、デフォルトでは環境変数 DB2DIR の値を使用します。

実行時設定

php.ini の設定により動作が変化します。

PDO_IBM の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pdo_ibm.i5_dbcs_alloc | "0" | INI_SYSTEM | PDO_IBM 1.5.0 で追加
pdo_ibm.i5_override_ccsid | "0" | INI_SYSTEM | PDO_IBM 1.5.0 で追加
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo_ibm.i5_dbcs_alloc int

IBM i 上ででの内部バッファを確保する戦略に影響します。 デフォルトでは、このオプションは 0です。 このオプションを設定すると、 エンコーディングを変換する際に文字サイズをデータベースが誤解した場合に備えて、 より大きなバッファサイズを確保します。 このオプションは(UTF-8 のありうる最大サイズを考慮して) 6倍大きなメモリを使いますが、 切り捨てられたデータを返す場合に必要な場合があります。

  • 0 - 最小サイズのバッファを確保します

  • 1 - より大きなサイズのバッファを確保します

pdo_ibm.i5_override_ccsid int

IBM i 上の EBCDIC からの変換に使う ASCII CCSID。 この値を 1208 に設定すると、UTF-8 を使います。 デフォルトでは、この値は 0 です。 この場合、デフォルトの ASCII job CCSID を選択します。

IBM i 上での CCSID について更に学ぶには、 » IBM documentation を調べて下さい。

目次

  • PDO_IBM DSN — IBM データベースへの接続


IBM データベースへの接続

  • ≪ IBM (PDO)
  • Informix (PDO) ≫
  • PHP Manual
  • IBM (PDO)
  • IBM データベースへの接続

PDO_IBM DSN

(PECL PDO_IBM >= 0.9.0)

PDO_IBM DSN — IBM データベースへの接続

説明

PDO_IBM のデータソース名 (DSN) は、IBM CLI DSN にもとづいています。 PDO_IBM DSN は、主に以下の部分から構成されます。

DSN プレフィックス

DSN プレフィックスは ibm: です。

DSN

DSN は、次のうちのいずれかです。

  • a) db2cli.ini あるいは odbc.ini を使用したデータソースの設定

  • b) カタログされたデータベース名、つまり、 DB2 クライアントにおけるデータベースエイリアス

  • c) 完全な接続文字列。次のような形式になります。 DRIVER={IBM DB2 ODBC DRIVER};DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password; 各パラメータは次の内容を表します。

    database

    データベースの名前。

    hostname

    データベースサーバーのホスト名あるいは IP アドレス。

    port

    データベースが要求を待ち受けている TCP/IP ポート。

    username

    データベースに接続する際のユーザー名。

    password

    データベースに接続する際のパスワード。

例

例1 db2cli.ini を使用した PDO_IBM DSN の例

この例は、PDO_IBM DSN で DB2 データベースに接続する方法を示すものです。 このデータベースは、DB2_9 という名前で db2cli.ini にカタログされています。

$db = new PDO("ibm:DSN=DB2_9", "", "");

[DB2_9]
Database=testdb
Protocol=tcpip
Hostname=11.22.33.444
Servicename=56789

例2 接続文字列を使用した PDO_IBM DSN の例

この例は、PDO_IBM DSN で DB2 データベースに接続する方法を示すものです。 このデータベースの名前は testdb で、DB2 CLI の接続文字列構文を使用します。

$db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
  "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");


Informix 関数 (PDO_INFORMIX)

はじめに

PDO_INFORMIX は、PHP から Informix データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

インストール手順

PDO_INFORMIX 拡張モジュールをビルドするには、PHP と同じシステムに Informix Client SDK 2.81 UC1 以降がインストールされている必要があります。 Informix Client SDK は、» IBM Informix Support Site で入手できます。

PDO_INFORMIX は » PECL 拡張モジュールです。 そのため、PDO_INFORMIX 拡張モジュールをインストールするには PECL 拡張モジュールのインストール の手順に従います。 Informix Client SDK ヘッダファイルおよびライブラリの場所を指定するため、 次のように configure コマンドを実行します。

   bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]
configure コマンドのデフォルトは、 環境変数 INFORMIXDIR の値となります。

スクロール可能なカーソル

PDO_INFORMIX は、スクロール可能なカーソルをサポートしています。 しかし、デフォルトでは有効になっていません。 スクロール可能なカーソルのサポートを有効にするには、 odbc.ini での対応する ODBC 接続設定で ENABLESCROLLABLECURSORS=1 を設定するか、 DSN 接続文字列に EnableScrollableCursors=1 句を指定しなければなりません。

目次

  • PDO_INFORMIX DSN — Informix データベースに接続する


Informix データベースに接続する

  • ≪ Informix (PDO)
  • MySQL (PDO) ≫
  • PHP Manual
  • Informix (PDO)
  • Informix データベースに接続する

PDO_INFORMIX DSN

(PECL PDO_INFORMIX >= 0.1.0)

PDO_INFORMIX DSN — Informix データベースに接続する

説明

PDO_INFORMIX データソース名 (DSN) は、Informix ODBC DSN 文字列を基にしています。 Informix ODBC DSN の設定についての詳細は、 » Informix Dynamic Server Information Center にあります。PDO_INFORMIX DSN の主要な部分は以下のようになります。

DSN 接頭辞

DSN 接頭辞は informix: です。

DSN

DSN は、odbc.ini を使用したデータソース設定、あるいは完全な » 接続文字列 のいずれかです。

例

例1 odbc.ini を使用した PDO_INFORMIX DSN の例

以下の例は、odbc.ini で Infdrv33 として登録されている Informix データベースに接続するための PDO_INFORMIX DSN を表します。

$db = new PDO("informix:DSN=Infdrv33", "", "");

[ODBC Data Sources]
Infdrv33=INFORMIX 3.3 32-BIT

[Infdrv33]
Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
Description=INFORMIX 3.3 32-BIT
Database=common_db
LogonID=testuser
pwd=testpass
Servername=ids_server
DB_LOCALE=en_US.819
OPTIMIZEAUTOCOMMIT=1
ENABLESCROLLABLECURSORS=1

例2 接続文字列を使用した PDO_INFORMIX DSN の例

以下の例は、common_db という名前の Informix データベースに接続文字列を使用して接続するための PDO_INFORMIX DSN を表します。

$db = new PDO("informix:host=host.domain.com; service=9800;
    database=common_db; server=ids_server; protocol=onsoctcp;
    EnableScrollableCursors=1", "testuser", "tespass");


MySQL 関数 (PDO_MYSQL)

はじめに

PDO_MYSQL は、PHP から MySQL データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

PDO_MYSQLは、 デフォルトでエミュレートされたプリペアドステートメントを使います。

MySQL 8

PHP 7.1.16 より前のバージョン、もしくは PHP 7.2.4 より前の 7.2系の PHP では、 MySQL 8 サーバーのデフォルトパスワードプラグインを mysql_native_password に設定するようにしてください。 さもないと、 The server requested authentication method unknown to the client [caching_sha2_password] のようなエラーを見ることになります。たとえあなたが caching_sha2_password を使っていなくても、です。

これは MySQL 8 のデフォルトが 古い PHP (mysqlnd) のリリースが認識していないプラグイン caching_sha2_password だからです。 かわりに、my.cnf の設定を default_authentication_plugin=mysql_native_password と変更してください。 caching_sha2_password プラグインは、 PHP 7.4.4 以降で完全にサポートされました。 これより前のバージョンでは、 mysql_xdevapi 拡張モジュールでサポートされています。

警告

注意: MySQL のテーブル型 (ストレージエンジン) の中には、 トランザクションをサポートしていないものがあります。 トランザクションをサポートしていないテーブル型を使用して トランザクションを使用するコードを書くと、 MySQL はトランザクションが正常に使用できたかのように振舞います。 さらに、DDL クエリを実行する際には、 実行中のトランザクションが暗黙的にコミットされます。

注意:

MySQL ドライバは、 PDOStatement::bindParam() メソッドで PDO::PARAM_INPUT_OUTPUT を適切にサポートしていません。使うことはできますが、 値が更新されません。(つまり、出力が無視されています)

インストール手順

一般的な Unix ディストリビューションには、バイナリ版の PHP がインストールされています。 これらのバイナリ版は、通常は MySQL 拡張モジュールを有効にしてビルドされています。 しかし、拡張モジュールのライブラリ自身を別パッケージでインストールする必要があるでしょう。 使用しているディストリビューションのパッケージマネージャで確認してみましょう。

たとえば Ubuntu なら、php5-mysql パッケージをインストールすれば、 ext/mysql、ext/mysqli、そして pdo_mysql をインストールできます。CentOS の場合は php-mysql パッケージを使えば、同じものをインストールできます。

この拡張モジュールを自分でコンパイルすることもできます。 PHP をソースからビルドすれば、使いたい MySQL 拡張モジュールを指定したり 各拡張モジュールが使用するクライアントライブラリを選択したりすることができます。

--with-pdo-mysql[=DIR] で PDO MySQL 拡張モジュールをインストールします。オプションの [=DIR] は、MySQL ベースライブラリの場所です。 Mysqlnd がデフォルトのベースライブラリです。 どのライブラリを選べばいいのかについての詳細は MySQL ライブラリの選択 を参照ください。

オプションの --with-mysql-sock[=DIR] で MySQL unix ソケットの場所を指定することができます。これは PDO_MYSQL を含むすべての MySQL 拡張モジュールで利用します。省略した場合はデフォルトの場所を検索します。

オプションの --with-zlib-dir[=DIR] で、 libz のインストールプレフィックスを指定することができます。

$ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

SSL サポートを有効にするには、適切な PDO_MySQL 定数 を指定します。これは » MySQL C API 関数 mysql_ssl_set() をコールするのと同じ意味になります。また、SSL を PDO::setAttribute で有効にすることはできません。というのも、この時点ではすでに接続が確立されてしまっているからです。 MySQL のドキュメントで » SSL を使った MySQL への接続 について確認しましょう。

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::MYSQL_ATTR_USE_BUFFERED_QUERY (bool)
デフォルトでは、全てのステートメントが バッファモード. で実行されます。 この値を false に設定すると、 PDO オブジェクトの場合、 MySQL ドライバは非バッファモードを使います。

例1 MySQL の非バッファモードを使う

<?php
$pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
$pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);
$unbufferedResult = $pdo->query("SELECT Name FROM City");
foreach ($unbufferedResult as $row) {
echo $row['Name'] . PHP_EOL;
}
?>

PDO::MYSQL_ATTR_LOCAL_INFILE (int)

LOAD LOCAL INFILE を有効にします。

この定数を使うのは、新しいデータベースハンドルを作るときの driver_options 配列内だけであることに注意しましょう。

PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY (string)

LOCAL DATA 文によるファイルのロードを、 ここで指定したディレクトリに制限する機能を有効にします。 PHP 8.1.0 以降で利用可能です。

この定数を使うのは、新しいデータベースハンドルを作るときの driver_options 配列内だけであることに注意しましょう。

PDO::MYSQL_ATTR_INIT_COMMAND (string)

MySQL サーバーへの接続時に実行するコマンドを指定します。 再接続の際には自動的に再実行されます。

この定数を使うのは、新しいデータベースハンドルを作るときの driver_options 配列内だけであることに注意しましょう。

PDO::MYSQL_ATTR_READ_DEFAULT_FILE (int)

my.cnf ではなく、 指定した名前のファイルからオプションを読み込みます。 このオプションは、mysqlnd を使っている場合は利用できません。 mysqlnd は mysql の設定ファイルを読んでいないからです。

PDO::MYSQL_ATTR_READ_DEFAULT_GROUP (int)

my.cnf あるいは 別のファイル (MYSQL_READ_DEFAULT_FILE で指定したもの) の中の、指定した名前のグループからオプションを読み込みます。 このオプションは、mysqlnd を使っている場合は利用できません。 mysqlnd は mysql の設定ファイルを読んでいないからです。

PDO::MYSQL_ATTR_MAX_BUFFER_SIZE (int)

バッファの最大サイズ。デフォルトは 1 MiB です。 mysqlnd を指定してコンパイルした場合は、この定数はサポートされていません。

PDO::MYSQL_ATTR_DIRECT_QUERY (int)

プリペアドステートメントではなく、直接クエリを実行します。

PDO::MYSQL_ATTR_FOUND_ROWS (int)

変更された行数ではなく、見つかった (マッチした) 行数を返します。

PDO::MYSQL_ATTR_IGNORE_SPACE (int)

関数名の後に続く空白を許可します。 すべての関数名を予約語にします。

PDO::MYSQL_ATTR_COMPRESS (int)

ネットワーク通信の圧縮を有効にします。

PDO::MYSQL_ATTR_SSL_CA (int)

SSL 認証局のファイルパス。

PDO::MYSQL_ATTR_SSL_CAPATH (int)

信頼済みのSSL認証局の証明書が入ったディレクトリパス。 証明書は、PEM フォーマットで格納されています。

PDO::MYSQL_ATTR_SSL_CERT (int)

SSL 証明書のファイルパス。

PDO::MYSQL_ATTR_SSL_CIPHER (int)

SSL 暗号化に使うひとつ以上の暗号の一覧。 OpenSSL で有効なフォーマットで指定します。 例: DHE-RSA-AES256-SHA:AES128-SHA

PDO::MYSQL_ATTR_SSL_KEY (int)

SSL キーのファイルパス。

PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT (int)

サーバーの SSL 証明書の検証を無効にする方法を提供します。 このオプションは、mysqlnd でのみ利用可能です。

これが使えるようになった PHP のバージョンは 7.0.18 および PHP 7.1.4.

PDO::MYSQL_ATTR_MULTI_STATEMENTS (int)

false にすると、PDO::prepare() や PDO::query() でのマルチクエリの実行を無効にします。

この定数が使えるのは、データベースハンドルを新規作成する際の driver_options 配列内だけであることに注意しましょう。

実行時設定

php.ini の設定により動作が変化します。

PDO_MYSQL 設定オプション
名前 | デフォルト | 変更可能
pdo_mysql.default_socket | "/tmp/mysql.sock" | INI_SYSTEM
pdo_mysql.debug | NULL | INI_SYSTEM
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo_mysql.default_socket string

Unix ドメインソケットを設定します。 configure の際にドメインソケットが見つかれば、 この値はコンパイル時にも設定されます。この ini 設定は Unix でのみ使えます。

pdo_mysql.debug bool

PDO_MYSQL のデバッグ機能を有効にします。 この設定が有効になるのは、mysqlnd を使って PDO_MYSQL をでコンパイルし、 かつ PDO がデバッグモードであるときだけです。

目次

  • PDO_MYSQL DSN — MySQL データベースに接続する


MySQL データベースに接続する

  • ≪ MySQL (PDO)
  • MS SQL Server (PDO) ≫
  • PHP Manual
  • MySQL (PDO)
  • MySQL データベースに接続する

PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — MySQL データベースに接続する

説明

PDO_MYSQL データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は mysql: です。

host

データベースサーバーが存在するホスト名を指定します。

port

データベースサーバーが待機しているポートを指定します。

dbname

データベース名を指定します。

unix_socket

MySQL の unix ソケットを指定します (host あるいは port と同時に使用することはできません)。

charset

文字セット。詳細は、 文字セットの概念 を参照ください。

例

例1 PDO_MYSQL DSN の例

以下の例は、MySQL データベースに接続するための PDO_MYSQL DSN を表します。

mysql:host=localhost;dbname=testdb
より完全な例は、このようになります。
mysql:host=localhost;port=3307;dbname=testdb
mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

注意

注意: Unix のみ

ホスト名を "localhost" にすると、 サーバーへの接続はドメインソケットを使って行われます。 libmysqlclient を使って PDO_MYSQL をコンパイルした場合は、 ソケットファイルの場所は libmysqlclient のコンパイル時の場所になります。 mysqlnd を使って PDO_MYSQL をコンパイルした場合は、デフォルトのソケットは pdo_mysql.default_socket の設定を使って作られます。


Microsoft SQL Server 関数 (PDO_SQLSRV)

はじめに

PDO_SQLSRV は、PHP Data Objects (PDO) インターフェイス を実装したドライバです。 PHP から、MS SQL Server (SQL Server 2005 以降) および SQL Azure データベースにアクセスできるようになります。

インストール手順

最新版のドライバのダウンロードは » SQLSRV download のページでできます。 ドライバのソースコードは、 » 公開リポジトリ でホストされています。

システム要件に関する詳細は » SQLSRV System Requirements を参照ください。

Windows では、PDO_SQLSRV 拡張モジュールは適切な DLL ファイルをダウンロードして PHP の extension ディレクトリに置き、対応するエントリを php.ini に追記することで有効にできます。

Linux と macOS では、PDO_SQLSRV 拡張モジュールは » PECL を使うとインストールできます。 詳細は » installation tutorial を参照ください。

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::SQLSRV_TXN_READ_UNCOMMITTED (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Read Uncommitted に設定します。
PDO::SQLSRV_TXN_READ_COMMITTED (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Read Committed に設定します。
PDO::SQLSRV_TXN_REPEATABLE_READ (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Repeateable Read に設定します。
PDO::SQLSRV_TXN_SNAPSHOT (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Snapshot に設定します。
PDO::SQLSRV_TXN_SERIALIZABLE (int)
この定数は、SQLSRV DSN のキー TransactionIsolation で使えます。 この接続のトランザクション隔離レベルを、Serializable に設定します。
PDO::SQLSRV_ENCODING_BINARY (int)
サーバーとの間のデータの送受信を生のバイトストリームで行い、 符号化や変換を一切しないように指示します。 この定数は、 PDOStatement::setAttribute、PDO::prepare、PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ENCODING_SYSTEM (int)
サーバーとの間のデータの送受信を 8 ビット文字として行い、 システムに設定された Windows のロケールのコードページを利用します。 このコードページにマップできない文字はすべて、シングルバイトのクエスチョンマークに置き換えられます。 この定数は、PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、 PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ENCODING_UTF8 (int)
サーバーとの間のデータの送受信を UTF-8 エンコーディングで行います。 これが、デフォルトの符号化方式です。この定数は、 PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、 PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ENCODING_DEFAULT (int)
サーバーとの間のデータの送受信を、接続時に指定した PDO::SQLSRV_ENCODING_SYSTEM に従って行います。プリペアドステートメントの中で指定された場合は、 その接続で設定されているエンコーディングを利用します。この定数は、 PDOStatement::setAttribute、PDO::setAttribute、PDO::prepare、 PDOStatement::bindColumn および PDOStatement::bindParam に渡せます。
PDO::SQLSRV_ATTR_QUERY_TIMEOUT (int)
非負の整数で、タイムアウト秒数を指定します。ゼロがデフォルトで、これはタイムアウトしないことを意味します。 この定数は、PDOStatement::setAttribute、PDO::setAttribute および PDO::prepare に渡せます。
PDO::SQLSRV_ATTR_DIRECT_QUERY (int)
クエリを直接実行し、準備しないことを指示します。 この定数は、PDO::setAttribute および PDO::prepare に渡せます。詳細な情報は » Direct and Prepared Statement Execution を参照ください。

目次

  • PDO_SQLSRV DSN — MS SQL Server および SQL Azure データベースに接続する


MS SQL Server および SQL Azure データベースに接続する

  • ≪ MS SQL Server (PDO)
  • Oracle (PDO) ≫
  • PHP Manual
  • MS SQL Server (PDO)
  • MS SQL Server および SQL Azure データベースに接続する

PDO_SQLSRV DSN

(PECL pdo_sqlsrv >= 2.0.1)

PDO_SQLSRV DSN — MS SQL Server および SQL Azure データベースに接続する

説明

PDO_SQLSRV データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は sqlsrv: です。

APP

トレースに使うアプリケーション名を指定します。

ConnectionPooling

接続をコネクションプールから確保する (1 あるいは true) のかしない (0 あるいは false) のかを指定します。

Database

データベースの名前を指定します。

Encrypt

SQL Server との通信を暗号化する (1 あるいは true) のかしない (0 あるいは false) のかを指定します。

Failover_Partner

サーバーと、データベースのインスタンスのミラー (有効になっていて、かつ使える場合) を指定して、プライマリーサーバーが使えないときに利用します。

LoginTimeout

接続の試行のタイムアウト秒数を指定します。

MultipleActiveResultSets

マルチアクティブ結果セット (MARS) のサポートを無効にするか、明示的に有効にします。

QuotedId

SQL-92 の規則に従った識別子のクォートを使う (1 あるいは true) か、レガシーな Transact-SQL のルールを使う (0 あるいは false) かを指定します。

Server

データベースサーバーの名前を指定します。

TraceFile

データのトレースに使うファイルのパスを指定します。

TraceOn

確立した接続用の ODBC のトレースを有効にする (1 あるいは true) か無効にする (0 あるいは false) かを指定します。

TransactionIsolation

トランザクション隔離レベルを指定します。このオプションに指定できる値は
PDO::SQLSRV_TXN_READ_UNCOMMITTED、PDO::SQLSRV_TXN_READ_COMMITTED、
PDO::SQLSRV_TXN_REPEATABLE_READ、PDO::SQLSRV_TXN_SNAPSHOT および
PDO::SQLSRV_TXN_SERIALIZABLE のいずれかです。

TrustServerCertificate

自己署名のサーバー証明書をクライアントに信頼させる (1 あるいは true) か させない (0 あるいは false) かを指定します。

WSID

トレース用のコンピューター名を指定します。

例

例1 PDO_SQLSRV DSN の例

以下の例は、MS SQL Server データベースに接続する方法を示します。

$c = new PDO("sqlsrv:Server=localhost;Database=testdb", "UserName", "Password");

以下の例は、ポートを指定して MS SQL Server データベースに接続する方法を示します。

$c = new PDO("sqlsrv:Server=localhost,1521;Database=testdb", "UserName", "Password");

以下の例は、サーバー ID 12345abcde の SQL Azure データベースに接続する方法を示します。 SQL Azure に PDO で接続するときは、ユーザー名が UserName@12345abcde (UserName@ServerId) となることに注意しましょう。

$c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=testdb", "UserName@12345abcde", "Password");


Oracle 関数 (PDO_OCI)

インストール手順

Oracle データベースがPHPと同じマシンにインストールされている場合、 必要なライブラリはデータベースソフトウェアに既に含まれています。 PHP が Oracle データベースと違うマシンにある場合、 フリーの » Oracle インスタントクライアント ライブラリを使ってください。 詳細は OCI8 のインストール要件 のセクションを参照ください。

--with-pdo-oci[=DIR] で PDO Oracle OCI 拡張モジュールをインストールします。オプションの [=DIR] には、Oracle のホームディレクトリを指定することができます。 [=DIR] のデフォルトは、環境変数 $ORACLE_HOME の値です。

--with-pdo-oci=instantclient,prefix,version で、Oracle Instant Client SDK を指定します。prefix および version は環境にあわせて設定します。

// $ORACLE_HOME を使う例
$ ./configure --with-pdo-oci

// OIC for Linux 10.2.0.3 の RPM を /usr プレフィックスで使う例
$ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::OCI_ATTR_ACTION (int)

Provides a way to specify the action on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

PDO::OCI_ATTR_CLIENT_INFO (int)

Provides a way to specify the client info on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

PDO::OCI_ATTR_CLIENT_IDENTIFIER (int)

Provides a way to specify the client identifier on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

PDO::OCI_ATTR_MODULE (int)

Provides a way to specify the module on the database session.

これが使えるようになった PHP のバージョンは 7.2.16 and 7.3.3

目次

  • PDO_OCI DSN — Oracle データベースに接続する


Oracle データベースに接続する

  • ≪ Oracle (PDO)
  • ODBC and DB2 (PDO) ≫
  • PHP Manual
  • Oracle (PDO)
  • Oracle データベースに接続する

PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Oracle データベースに接続する

説明

PDO_OCI データソース名 (DSN) は以下の要素で構成されます:

DSN 接頭辞

DSN 接頭辞は oci: です。

dbname (Oracle Instant Client)

Oracle Instant Client 接続に対する URI は dbname=//hostname:port-number/database のような形式です。 もし tnsnames.ora で定義されたデータベースに接続する場合は、データベース名のみを使用して dbname=database とします。

charset

現在の環境ハンドルにおける、クライアント側の文字セットです。

例

例1 PDO_OCI DSN の例

以下の例は、Oracle データベースに接続するための PDO_OCI DSN を表します:

// tnsnames.ora で定義したデータベースに接続します
oci:dbname=mydb

// Oracle Instant Client を使用して接続します
oci:dbname=//localhost:1521/mydb


ODBC および DB2 関数 (PDO_ODBC)

はじめに

PDO_ODBC は PHP Data Objects (PDO) インターフェイスを実装したドライバで、 PHP から ODBC ドライバあるいは IBM DB2 Call Level Interface (DB2 CLI) ライブラリを使用した データベースへのアクセスが可能となります。 PDO_ODBC は、現在 3 種類のデータベースドライバをサポートしています。

ibm-db2

フリーの DB2 express-C クライアントを使用した、 IBM DB2 Universal Database、Cloudscape および Apache Derby サーバーへのアクセスをサポートします。

unixODBC

unixODBC ドライバマネージャおよびデータベースごとの ODBC ドライバを使用した、データベースサーバーへのアクセスをサポートします。

generic

PDO_ODBC が明示的にサポートしていない ODBC ドライバマネージャのためのコンパイルオプションを提供します。

Windows では、php_pdo_odbc.dll を拡張モジュールとして php.ini で有効にする必要があります。 これは Windows ODBC ドライバマネージャに対してリンクされており、 システムの DSN に登録されているあらゆるデータベースに対して PHP から接続することができます。

インストール手順

UNIX システムでの PDO_ODBC

  1. PDO_ODBC は PHP ソースの中に含まれています。 PDO_ODBC 拡張モジュールを静的モジュールあるいは共有モジュールとして コンパイルするには次のような configure コマンドを実行します。

    ibm_db2

    ./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/
    PDO_ODBC を ibm-db2 形式でビルドするには、PDO_ODBC をコンパイルするのと同じマシンに DB2 アプリケーション開発用ヘッダが インストールされていなければなりません。DB2 アプリケーション開発ヘッダは DB2 サーバーのインストールオプションに 含まれており、また IBM developerWorks の » Web サイト からフリーでダウンロードできる DB2 Application Development Client にも含まれています。

    configure コマンドに DB2 ライブラリおよび ヘッダの場所を指定しなかった場合は、PDO_ODBC はデフォルトとして /home/db2inst1/sqllib を使用します。

    unixODBC

    ./configure --with-pdo-odbc=unixODBC,/usr/local
    configure コマンドに unixODBC ライブラリおよび ヘッダの場所を指定しなかった場合は、PDO_ODBC はデフォルトとして /usr/local を使用します。

    generic
    ./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO_ODBC_TYPE (string)

PDO::ODBC_ATTR_USE_CURSOR_LIBRARY (int)

このオプションは、ODBC のカーソルライブラリが使うかを制御します。 ODBC カーソルライブラリは、ドライバが実装していない高度なODBCの機能 (例: スクロール可能なブロックカーソル) をいくつかサポートします。 サポートしている値は以下の通りです:

  • PDO::ODBC_SQL_USE_IF_NEEDED (デフォルト): ODBC カーソルライブラリを必要な時に使います。

  • PDO::ODBC_SQL_USE_DRIVER: ODBC カーソルライブラリを使いません。

  • PDO::ODBC_SQL_USE_ODBC: ODBC カーソルライブラリを常に使います。

PDO::ODBC_ATTR_ASSUME_UTF8 (bool)

Windows のみ有効です。 true の場合、UTF-16 でエンコードされた文字データ( CHAR, VARCHAR, LONGVARCHAR) を データベースから読み取ったり、書き込んだりする際に UTF-8 に変換します。 false の場合(デフォルト)、 エンコーディングの変換はドライバが行う可能性があります。

実行時設定

php.ini の設定により動作が変化します。

PDO_ODBC 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pdo_odbc.connection_pooling | "strict" | INI_ALL |
pdo_odbc.db2_instance_name | NULL | INI_SYSTEM | この非推奨の機能は、きっと 将来 削除 されるでしょう。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pdo_odbc.connection_pooling string

ODBC 接続のプール方法を指定します。"strict"、"relaxed" あるいは "off" ("" と同じ) のいずれかです。このパラメータは、 プールされている既存の接続との比較をどの程度厳密に行うのかを 接続マネージャに指定します。 strict は推奨されているデフォルト設定で、 接続パラメータが完全に一致する場合にのみ既存の接続を使用します。 relaxed は、接続パラメータが似ている場合に 既存の接続を使用します。これはキャッシュの再利用率を高めますが、 (例えば) 仮想ホスト間での接続情報がおかしくなってしまう恐れがあります。

この設定は php.ini ファイルでのみ変更可能で、 その内容はプロセス全体に影響します。同じ ODBC ライブラリを使用している すべてのモジュール、たとえば Unified ODBC 拡張モジュール などが影響を受けます。

警告

relaxed を共有サーバーで使用してはいけません。 これはセキュリティの問題があるためです。

ヒント

どうしても変更する必要がない限り、この設定はデフォルトの strict のままにしておきましょう。

pdo_odbc.db2_instance_name string

db2 方式で PDO_ODBC をコンパイルした場合、 Linux および UNIX 上で DB2 インスタンスを指定するための環境変数 DB2INSTANCE の値を設定します。これによって PDO_ODBC が DB2 ライブラリの場所を見つけられるようになり、 DB2 データベースへのカタログ接続が可能になります。

この設定は php.ini ファイルでのみ変更可能で、 その内容はプロセス全体に影響します。同じ ODBC ライブラリを使用している すべてのモジュール、たとえば Unified ODBC 拡張モジュール などが影響を受けます。

この設定は、Windows 上では何の意味も持ちません。

目次

  • PDO_ODBC DSN — ODBC あるいは DB2 データベースに接続する


ODBC あるいは DB2 データベースに接続する

  • ≪ ODBC and DB2 (PDO)
  • PostgreSQL (PDO) ≫
  • PHP Manual
  • ODBC and DB2 (PDO)
  • ODBC あるいは DB2 データベースに接続する

PDO_ODBC DSN

(PECL PDO_ODBC >= 0.1.0)

PDO_ODBC DSN — ODBC あるいは DB2 データベースに接続する

説明

PDO_ODBC データソース名 (DSN) は以下の要素で構成されます。

DSN 接頭辞

DSN 接頭辞は odbc: です。 ODBC ドライバマネージャや DB2 カタログに登録されている データベースに接続する際には、登録されている名前を DSN に追加することができます。

DSN

ODBC ドライバマネージャあるいは DB2 カタログに登録されている データベース名を指定します。それ以外の方法として、 » http://www.connectionstrings.com/ で説明されている完全な ODBC 接続文字列を使用して データベースに接続することもできます。

UID

接続に使用するユーザーの名前を指定します。DSN と同じユーザー名を指定した場合は、PDO はコンストラクタの引数で指定された ユーザー名を無視します。

PWD

接続するユーザーのパスワードを指定します。DSN と同じパスワードを指定した場合は、PDO はコンストラクタの引数で指定された パスワードを無視します。

例

例1 PDO_ODBC DSN の例 (ODBC ドライバマネージャ)

以下の例は、ODBC ドライバマネージャで testdb として登録されている ODBC データベースに接続するための PDO_ODBC DSN を表します。

odbc:testdb

例2 PDO_ODBC DSN の例 (IBM DB2 非カタログ接続)

以下の例は、完全な ODBC DSN 構文を使用して SAMPLE という名前の IBM DB2 データベースに接続するための PDO_ODBC DSN を表します。

odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

例3 PDO_ODBC DSN の例 (Microsoft Access 非カタログ接続)

以下の例は、完全な ODBC DSN 構文を使用して C:\db.mdb にある Microsoft Access データベースに接続するための PDO_ODBC DSN を表します。

odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin


PostgreSQL 関数 (PDO_PGSQL)

はじめに

PDO_PGSQL は、PHP から PostgreSQL データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

リソース型

この拡張モジュールでは、ストリームリソースを定義しています。これは PDO::pgsqlLOBOpen() が返すものです。

インストール手順

--with-pdo-pgsql[=DIR] で PDO PostgreSQL 拡張モジュールをインストールします。オプションの [=DIR] には、PostgreSQL の基底インストールディレクトリあるいは pg_config へのパスを指定することができます。

$ ./configure --with-pdo-pgsql

定義済み定数

このドライバでは以下の定数が定義されて います。これは拡張モジュールが PHP に組み込まれているか、実行時に動的にロード されている場合のみ使用可能です。さらに、これらのドライバ固有の定数は そのドライバを使用している場合にのみ使用されます。 あるドライバ固有の属性を別のドライバで使うと、予期せぬ結果を引き起こします。 もし複数のドライバを使用しているコードを実行している場合、 PDO::getAttribute() で PDO::ATTR_DRIVER_NAME 属性を使用することで、使用中のドライバ名を調べることが可能です。

PDO::PGSQL_ATTR_DISABLE_PREPARES (int)

SQL文とパラメータを一緒に、一回のコールでサーバーに送信します。 これによって、名前付きのプリペアドステートメントを別々に作ることを避けられます。 SQL文が一度しか実行されない場合、 不要なサーバーとの通信を避けられるので、レイテンシを抑えることができます。

General notes

注意:

bytea フィールドはストリームとして返されます。

目次

  • PDO_PGSQL DSN — PostgreSQL データベースに接続する
  • PDO::pgsqlCopyFromArray — PHP の配列から、データをテーブルにコピーする
  • PDO::pgsqlCopyFromFile — ファイルからデータをテーブルにコピーする
  • PDO::pgsqlCopyToArray — データベーステーブルからのデータをPHPの配列にコピーする
  • PDO::pgsqlCopyToFile — テーブルからのデータをファイルにコピーする
  • PDO::pgsqlGetNotify — 非同期に通知を取得する
  • PDO::pgsqlGetPid — サーバーのPIDを取得する
  • PDO::pgsqlLOBCreate — 新しいラージオブジェクトを作成する
  • PDO::pgsqlLOBOpen — 既存のラージオブジェクトのストリームをオープンする
  • PDO::pgsqlLOBUnlink — ラージオブジェクトを削除する


PostgreSQL データベースに接続する

  • ≪ PostgreSQL (PDO)
  • PDO::pgsqlCopyFromArray ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • PostgreSQL データベースに接続する

PDO_PGSQL DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_PGSQL >= 0.1.0)

PDO_PGSQL DSN — PostgreSQL データベースに接続する

説明

PDO_PGSQL データソース名 (DSN) は以下の要素で構成され、 スペースあるいはセミコロンで区切られます:

DSN 接頭辞

DSN 接頭辞は pgsql: です。

host

データベースサーバーが存在するホスト名を指定します。

port

データベースサーバーが起動しているポートを指定します。

dbname

データベース名を指定します。

user

接続するユーザー名を指定します。もし DSN でユーザー名を指定する場合、 PDO は PDO コンストラクタにおけるユーザー名引数の値を無視します。

password

接続するユーザーのパスワードを指定します。もし DSN でパスワードを指定する場合、 PDO は PDO コンストラクタにおけるパスワード引数の値を無視します。

sslmode

SSLモード。サポートされている値とその意味については、 » PostgreSQL Documentation を参照ください。

注意: DSN 文字列における全てのセミコロンは、スペースで置き換えられます。 なぜなら、PostgreSQL はそのように置き換えられたフォーマットを期待しているからです。 このことは、DSN におけるあらゆるコンポーネント (例: password や dbname) で、セミコロンはサポートされていないということです。

例

例1 PDO_PGSQL DSN の例

以下の例は、PostgreSQL データベースに接続するための PDO_PGSQL DSN を示します:

pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

以下の例は、unix ソケット経由で PostgreSQL データベースに接続するための PDO_PGSQL DSN を示します:

pgsql:host=/tmp;port=5432;dbname=testdb;user=bruce;password=mypass


PHP の配列から、データをテーブルにコピーする

  • ≪ PDO_PGSQL DSN
  • PDO::pgsqlCopyFromFile ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • PHP の配列から、データをテーブルにコピーする

PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — PHP の配列から、データをテーブルにコピーする

説明

public PDO::pgsqlCopyFromArray(
string $table_name,
array $rows,
string $delimiter = "\t",
string $null_as = "\\\\N",
string $fields = ?
): bool

rows 配列からデータをテーブル table_name にコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

rows

delimiter で区切られたフィールドの文字列の配列

delimiter

rows 配列で使われているデリミタ

null_as

どのように null 値を扱うかを指定します

fields

挿入するフィールドの一覧

戻り値

成功したら true を返します。 失敗した場合に false を返します


ファイルからデータをテーブルにコピーする

  • ≪ PDO::pgsqlCopyFromArray
  • PDO::pgsqlCopyToArray ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • ファイルからデータをテーブルにコピーする

PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — ファイルからデータをテーブルにコピーする

説明

public PDO::pgsqlCopyFromFile(
string $table_name,
string $filename,
string $delimiter = "\t",
string $null_as = "\\\\N",
string $fields = ?
): bool

filename で指定されたファイルからデータをテーブル table_name にコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

filename

インポートするデータを含むファイル名

delimiter

filename で指定されたファイルで使われているデリミタ

null_as

どのように null 値を扱うかを指定します

fields

挿入するフィールドの一覧

戻り値

成功したら true を返します。 失敗した場合に false を返します


データベーステーブルからのデータをPHPの配列にコピーする

  • ≪ PDO::pgsqlCopyFromFile
  • PDO::pgsqlCopyToFile ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • データベーステーブルからのデータをPHPの配列にコピーする

PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — データベーステーブルからのデータをPHPの配列にコピーする

説明

public PDO::pgsqlCopyToArray(
string $table_name,
string $delimiter = "\t",
string $null_as = "\\\\N",
string $fields = ?
): array|false

table からのデータを配列にコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

delimiter

列で使われるデリミタ

null_as

どのように null 値を扱うかを指定します

fields

エクスポートするフィールドの一覧

戻り値

行の配列を返します。 失敗した場合に false を返します


テーブルからのデータをファイルにコピーする

  • ≪ PDO::pgsqlCopyToArray
  • PDO::pgsqlGetNotify ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • テーブルからのデータをファイルにコピーする

PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — テーブルからのデータをファイルにコピーする

説明

public PDO::pgsqlCopyToFile(
string $table_name,
string $filename,
string $delimiter = "\t",
string $null_as = "\\\\N",
string $fields = ?
): bool

filename で指定されたファイルに、テーブルからデータをコピーします。 その際、delimiter をフィールドのデリミタ、そして fields のリストを使います。

パラメータ

table_name

テーブル名を含む文字列

filename

エキスポートするファイル名

delimiter

filename で指定されたファイルで使われているデリミタ

null_as

どのように null 値を扱うかを指定します

fields

挿入するフィールドの一覧

戻り値

成功したら true を返します。 失敗した場合に false を返します


非同期に通知を取得する

  • ≪ PDO::pgsqlCopyToFile
  • PDO::pgsqlGetPid ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • 非同期に通知を取得する

PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — 非同期に通知を取得する

説明

public PDO::pgsqlGetNotify(int $result_type = PDO::FETCH_USE_DEFAULT, int $ms_timeout = 0): array|false

保留中の非同期な通知を示す結果セットを返します。

パラメータ

result_type

結果セットを返すフォーマット。 PDO::FETCH_* 定数で表現します。

ms_timeout

レスポンスを待つ時間の長さ。ミリ秒で指定します。

戻り値

ひとつ以上の通知が保留中だった場合、 message と pid のフィールドが入った一行を返します。 そうでなければ false を返します。


サーバーのPIDを取得する

  • ≪ PDO::pgsqlGetNotify
  • PDO::pgsqlLOBCreate ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • サーバーのPIDを取得する

PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — サーバーのPIDを取得する

説明

public PDO::pgsqlGetPid(): int

サーバーのPIDを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

サーバーのPIDを返します。


新しいラージオブジェクトを作成する

  • ≪ PDO::pgsqlGetPid
  • PDO::pgsqlLOBOpen ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • 新しいラージオブジェクトを作成する

PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — 新しいラージオブジェクトを作成する

説明

public PDO::pgsqlLOBCreate(): string

PDO::pgsqlLOBCreate() は、 ラージオブジェクトを作成してその OID を返します。 このオブジェクトに対するデータの読み書きを行う際には、 PDO::pgsqlLOBOpen() を使用してストリームをオープンします。 OID は OID 型のカラムに格納され、ラージオブジェクトを参照するために使用されます。 これにより、行のサイズがどんどん拡大してしまうことを防ぎます。 PDO::pgsqlLOBUnlink() をコールして削除するまで、 ラージオブジェクトはデータベース内に残り続けます。

ラージオブジェクトの大きさは最大 2GB まで拡大できますが、扱い方はめんどうです。 オブジェクトの OID を参照している行をデータベースから削除する際には、 必ず事前に PDO::pgsqlLOBUnlink() がコールされていなければなりません。 さらに、ラージオブジェクトにはアクセス権の設定がありません。 ラージオブジェクトの代替策として、bytea 型のカラムも検討ください。 最近のバージョンの PostgreSQL では bytea 型のカラムに最大 1GB まで保存でき、行サイズを最適化したうえでデータを透過的に扱うことができます。

注意: この関数は、トランザクション内でコールしなければなりません。

パラメータ

PDO::pgsqlLOBCreate() は、パラメータを受け取りません。

戻り値

新しく作成されたラージオブジェクトの OID、あるいは失敗した場合に false を返します。

例

例1 PDO::pgsqlLOBCreate() の例

この例では、新しいラージオブジェクトを作成し、 ファイルの内容をそこにコピーします。その後、OID がテーブルに保存されます。

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$oid = $db->pgsqlLOBCreate();
$stream = $db->pgsqlLOBOpen($oid, 'w');
$local = fopen($filename, 'rb');
stream_copy_to_stream($local, $stream);
$local = null;
$stream = null;
$stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
$stmt->execute(array($some_id, $oid));
$db->commit();
?>

参考

  • PDO::pgsqlLOBOpen() - 既存のラージオブジェクトのストリームをオープンする
  • PDO::pgsqlLOBUnlink() - ラージオブジェクトを削除する
  • pg_lo_create() - ラージオブジェクトを生成する


既存のラージオブジェクトのストリームをオープンする

  • ≪ PDO::pgsqlLOBCreate
  • PDO::pgsqlLOBUnlink ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • 既存のラージオブジェクトのストリームをオープンする

PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — 既存のラージオブジェクトのストリームをオープンする

説明

public PDO::pgsqlLOBOpen(string $oid, string $mode = "rb"): resource|false

PDO::pgsqlLOBOpen() は、oid が指すデータにアクセスするためのストリームをオープンします。 mode が r の場合、 ストリームは読み込み用にオープンされます。 mode が w の場合、 ストリームは書き込み用にオープンされます。 fread()、fwrite() および fgets() のような通常のファイルシステム関数を使用して、 ストリームの内容を操作することができます。

注意: この関数およびラージオブジェクトに対するすべての操作は、 トランザクション内で処理される必要があります。

パラメータ

oid

ラージオブジェクトの ID。

mode

モードが r の場合、読み込み用のストリームをオープンします。 モードが w の場合、書き込み用のストリームをオープンします。

戻り値

成功した場合にストリームリソース、失敗した場合に false を返します。

例

例1 PDO::pgsqlLOBOpen() の例

PDO::pgsqlLOBCreate() の例に引き続き、 このコード片はデータベースからラージオブジェクトを取得して それをブラウザに出力します。

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$stmt = $db->prepare("select oid from BLOBS where ident = ?");
$stmt->execute(array($some_id));
$stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
$stmt->fetch(PDO::FETCH_BOUND);
$stream = $db->pgsqlLOBOpen($oid, 'r');
header("Content-type: application/octet-stream");
fpassthru($stream);
?>

参考

  • PDO::pgsqlLOBCreate() - 新しいラージオブジェクトを作成する
  • PDO::pgsqlLOBUnlink() - ラージオブジェクトを削除する
  • pg_lo_open() - ラージオブジェクトをオープンする


ラージオブジェクトを削除する

  • ≪ PDO::pgsqlLOBOpen
  • SQLite (PDO) ≫
  • PHP Manual
  • PostgreSQL (PDO)
  • ラージオブジェクトを削除する

PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — ラージオブジェクトを削除する

説明

public PDO::pgsqlLOBUnlink(string $oid): bool

OID が指すラージオブジェクトをデータベースから削除します。

注意: この関数は、トランザクション内でコールしなければなりません。

パラメータ

oid

ラージオブジェクトの ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PDO::pgsqlLOBUnlink() の例

PDO::pgsqlLOBCreate() および PDO::pgsqlLOBOpen() の例で使用した blob テーブルからラージオブジェクトを参照している行を削除する前に、 この例ではラージオブジェクトをデータベースから削除します。

<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$db->pgsqlLOBUnlink($oid);
$stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
$stmt->execute(array($some_id));
$db->commit();
?>

参考

  • PDO::pgsqlLOBOpen() - 既存のラージオブジェクトのストリームをオープンする
  • PDO::pgsqlLOBCreate() - 新しいラージオブジェクトを作成する


SQLite 関数 (PDO_SQLITE)

はじめに

PDO_SQLITE は、PHP から SQLite 2 や SQLite 3 データベースへのアクセスを可能にするための PHP Data Objects (PDO) インターフェイス を実装したドライバです。

注意:

PDO_SQLITE は、文字列と PDO::PARAM_LOB のストリームを区別して使うことができます。

インストール手順

PDO_SQLITE PDO ドライバはデフォルトで有効になります。無効にするには --without-pdo-sqlite[=DIR] を使います。 オプションの [=DIR] は sqlite の基底インストールディレクトリです。 PHP 7.4.0 以降では、» libsqlite ? 3.5.0 が必須です。 それより前のバージョンでは、[=DIR] が省略された場合は バンドル済みの libsqlite が代わりに使われていましたし、 またそれがデフォルトでした。

注意: PHP 7.4.0 以降の、Windows における追加セットアップ

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsqlite3.dll.

目次

  • PDO_SQLITE DSN — SQLite データベースに接続する
  • PDO::sqliteCreateAggregate — SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する
  • PDO::sqliteCreateCollation — SQL文で collate 関数として使うユーザー定義関数を登録する
  • PDO::sqliteCreateFunction — SQL 文で使用するユーザー定義関数 (UDF) を登録する


SQLite データベースに接続する

  • ≪ SQLite (PDO)
  • PDO::sqliteCreateAggregate ≫
  • PHP Manual
  • SQLite (PDO)
  • SQLite データベースに接続する

PDO_SQLITE DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_SQLITE >= 0.2.0)

PDO_SQLITE DSN — SQLite データベースに接続する

説明

PDO_SQLITE データソース名 (DSN) は以下の要素で構成されます:

DSN 接頭辞 (SQLite 3)

DSN 接頭辞は sqlite: です。

  • ディスク上のデータベースにアクセスするには、 DSN 接頭辞に絶対パスを付加してください。

  • メモリ内にデータベースを生成するには、 DSN 接頭辞に :memory: を付加してください。

  • DSN がDSN接頭辞のみの場合、一時的なデータベースが作られます。 これは、接続が閉じられると削除されます。

例

例1 PDO_SQLITE DSN の例

以下の例は、SQLite データベースへの接続するための PDO_SQLITE DSN を表します:

sqlite:/opt/databases/mydb.sq3
sqlite::memory:
sqlite:


SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する

  • ≪ PDO_SQLITE DSN
  • PDO::sqliteCreateCollation ≫
  • PHP Manual
  • SQLite (PDO)
  • SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する

PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する

説明

public PDO::sqliteCreateAggregate(
string $function_name,
callable $step_func,
callable $finalize_func,
int $num_args = ?
): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

このメソッドは PDO::sqliteCreateFunction と似ていますが、 この関数で登録した関数は、クエリのすべての行の内容を集約する関数を登録します。

この関数と PDO::sqliteCreateFunction の最大の違いは、 集約関数を作成するためには 2 つの関数が必要であるということです。

パラメータ

function_name

SQL 文で使用する関数の名前。

step_func

結果セットの各行についてコールされるコールバック関数。 この PHP 関数は、結果を蓄積して集約コンテキストに保存しなければなりません。

この関数は次のように定義しなければなりません。

step(
mixed $context,
int $rownumber,
mixed $value,
mixed ...$values
): mixed
context

最初の行では null 二行目以降では、ステップ関数から以前返された値を持ちます。 この値を、集約の状態を管理するのに使うべきです。

rownumber

現在の行番号

value

集約関数に渡されるはじめの引数

values

集約関数に渡されるふたつめ以降の引数

この関数の戻り値を、次のステップあるいはファイナライズ関数の context 引数として使います。

finalize_func

すべての行が処理された後でコールされるコールバック関数。 ここでは、集約コンテキストからデータを取得して結果を返します。 コールバック関数の返す値は、SQLite が理解できる形式 (すなわち スカラー型) でなければなりません。

この関数は次のように定義しなければなりません。

fini(mixed $context, int $rowcount): mixed
context

ステップ関数を最後に呼んだ時の戻り値を保持します。

rowcount

集約関数が実行された行数を保持します。

この関数の戻り値が、集約の戻り値となります。

num_args

コールバック関数があらかじめ定義済みの引数を受け取る場合に、 SQLite のパーサに渡すヒント。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 集約関数 max_length の例

<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
$insert->execute(array($str));
}
$insert = null;

function max_len_step($context, $rownumber, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
return $context;
}

function max_len_finalize($context, $rownumber)
{
return $context === null ? 0 : $context;
}

$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');

var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

?>

この例では、 テーブルのカラムの中で一番長い文字列の長さを計算する集約関数を作成します。 各行について max_len_step 関数がコールされ、 $context パラメータが渡されます。 このパラメータには、他の PHP 変数と同様に、配列やオブジェクトが設定されます。 この例では、これまでに登場した値のうち長さが最大のものの長さを保持しています。 $string が現在の最大値より長い場合に、 その値で現在の最大値を更新します。

すべての行に対する処理が終わると、SQLite は max_len_finalize 関数をコールして集約結果を決定します。 ここでは、$context の内容に基づいた、 なんらかの計算を行うことができます。 しかし、この例ではクエリを処理している過程で既に結果が決定しているので、 ここでは単に context の値を返しているだけです。

ヒント

結果の値を context に溜め込んでおき、最後に一括して処理するという方法は推奨 「しません」。これは、SQLite のメモリ消費量が大きくなるからです。 仮に 32 バイトの長さのデータが百万件あったとして、 それを溜め込むためにどれだけのメモリが必要になるか考えてみましょう。

ヒント

PDO::sqliteCreateFunction および PDO::sqliteCreateAggregate を使用して、 SQLite のネイティブ SQL 関数を上書きすることができます。

参考

  • PDO::sqliteCreateFunction
  • sqlite_create_function()
  • sqlite_create_aggregate()


SQL文で collate 関数として使うユーザー定義関数を登録する

  • ≪ PDO::sqliteCreateAggregate
  • PDO::sqliteCreateFunction ≫
  • PHP Manual
  • SQLite (PDO)
  • SQL文で collate 関数として使うユーザー定義関数を登録する

PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — SQL文で collate 関数として使うユーザー定義関数を登録する

説明

public PDO::sqliteCreateCollation(string $name, callable $callback): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

name

作成または再定義する SQL collate 関数の名前

callback

collation の振る舞いを定義する、PHP関数または、 コールバックとして適用するユーザー定義関数。 2つの値を受けとり、strcmp() 関数が返すのと同じ値を返します。つまり、 はじめの文字列が前の文字列より前にソートされる場合に-1、 後にソートされる場合に1、等しい場合に0を返します。

この関数は、次のように定義する必要があります:

collation(string $string1, string $string2): int

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PDO::sqliteCreateCollation() の例

<?php
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE test (col1 string)");
$db->exec("INSERT INTO test VALUES ('a1')");
$db->exec("INSERT INTO test VALUES ('a10')");
$db->exec("INSERT INTO test VALUES ('a2')");

$db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
echo $row['col1'] . "\n";
}
echo "\n";
foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
echo $row['col1'] . "\n";
}
?>

上の例の出力は以下となります。

a1
a10
a2

a1
a2
a10


SQL 文で使用するユーザー定義関数 (UDF) を登録する

  • ≪ PDO::sqliteCreateCollation
  • ベンダー固有のモジュール ≫
  • PHP Manual
  • SQLite (PDO)
  • SQL 文で使用するユーザー定義関数 (UDF) を登録する

PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — SQL 文で使用するユーザー定義関数 (UDF) を登録する

説明

public PDO::sqliteCreateFunction(
string $function_name,
callable $callback,
int $num_args = -1,
int $flags = 0
): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

このメソッドを使用すると、 PHP の関数を、UDF (User Defined Function: ユーザー定義関数) として SQLite に登録できるようになります。 登録した関数は、SQL 文の中で使用することが可能です。

UDF は、関数をコールできるあらゆる SQL 文 (SELECT および UPDATE 文、そしてトリガなど) で使用することが可能です。

パラメータ

function_name

SQL 文で使用する関数の名前。

callback

定義した SQL 関数を処理するコールバック関数。

注意: コールバック関数の返す値は、SQLite が理解できる形式 (すなわち スカラー型) でなければなりません。

コールバック関数は、以下のように定義する必要があります:

callback(mixed $value, mixed ...$values): mixed
value

SQL関数に渡す最初の引数

values

SQL関数に渡す2つ目以降の引数

num_args

SQL 関数がとる引数の数。 このパラメータが -1 の場合、 SQL 関数は任意の数の引数を取ることができます。

flags

ビット単位のフラグの組み合わせ。 現状は、PDO::SQLITE_DETERMINISTIC だけがサポートされています。 これは、単一のSQLステートメント内では、同じ入力に対して常に同じ結果を返すことを指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.4 | flags パラメータが追加されました。

例

例1 PDO::sqliteCreateFunction() の例

<?php
function md5_and_reverse($string)
{
return strrev(hash('md5', $string));
}

$db = new PDO('sqlite:sqlitedb');
$db->sqliteCreateFunction('md5rev', 'md5_and_reverse', 1);
$rows = $db->query('SELECT md5rev(filename) FROM files')->fetchAll();
?>

この例では、文字列の md5 を計算してそれを反転させる関数を定義しています。 SQL 文が実行されると、filename をこの関数で変換した値が返されます。 $rows に返されるデータの中に、処理結果が含まれます。

この方法を使用すると、データを取得した後に foreach で結果をひとつひとつ処理していく必要がなくなり、美しいコードが記述できます。

ヒント

PDO::sqliteCreateFunction および PDO::sqliteCreateAggregate を使用して、 SQLite のネイティブ SQL 関数を上書きすることができます。

参考

  • PDO::sqliteCreateAggregate
  • sqlite_create_function()
  • sqlite_create_aggregate()


ベンダー固有のモジュール

  • CUBRID
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • CUBRID 関数
    • CUBRID MySQL 互換関数
    • CUBRID 廃止されたエイリアスと関数
  • dBase
    • はじめに
    • インストール/設定
    • 定義済み定数
    • dBase 関数
  • Firebird/InterBase
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Firebird/InterBase 関数
  • IBM DB2 — IBM DB2、Cloudscape および Apache Derby
    • はじめに
    • インストール/設定
    • 定義済み定数
    • IBM DB2 関数
  • MongoDB — MongoDB Extension
    • インストール/設定
    • Tutorials
    • Driver Architecture and Internals — Explains the driver architecture, and special features
    • Security
    • MongoDB\Driver — MongoDB Extension Classes
    • MongoDB\BSON — MongoDB BSON Classes and Functions
    • MongoDB\Driver\Monitoring — Monitoring classes and subscriber functions
    • MongoDB\Driver\Exception — Exception classes
  • MySQL — MySQL ドライバおよびプラグイン
    • MySQL 用 PHP ドライバの概要
    • MySQLi — MySQL 改良版拡張モジュール
    • Mysql_xdevapi
    • MySQL (最初の API) — 最初の MySQL API
    • Mysqlnd — MySQL Native Driver
  • OCI8 — Oracle OCI8
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • OCI8 接続のハンドリングおよびプーリング
    • OCI8 高速アプリケーション通知 (FAN) サポート
    • OCI8 Transparent Application Failover (TAF) Support
    • OCI8 および DTrace 動的トレーシング
    • ドライバでサポートされるデータ型
    • OCI8 関数
    • OCICollection — OCICollection クラス
    • OCILob — OCILob クラス
    • OCI8 廃止されたエイリアスと関数
  • PostgreSQL
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PostgreSQL 関数
    • PgSql\Connection — PgSql\Connection クラス
    • PgSql\Result — The PgSql\Result class
    • PgSql\Lob — The PgSql\Lob class
  • SQLite3
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SQLite3 — SQLite3 クラス
    • SQLite3Exception — SQLite3Exception クラス
    • SQLite3Stmt — SQLite3Stmt クラス
    • SQLite3Result — SQLite3Result クラス
  • SQLSRV — PHP 用 Microsoft SQL Server ドライバ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SQLSRV 関数


CUBRID

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • CUBRID 関数
    • cubrid_bind — Bind variables to a prepared statement as parameters
    • cubrid_close_prepare — Close the request handle
    • cubrid_close_request — Close the request handle
    • cubrid_col_get — Get contents of collection type column using OID
    • cubrid_col_size — Get the number of elements in collection type column using OID
    • cubrid_column_names — Get the column names in result
    • cubrid_column_types — Get column types in result
    • cubrid_commit — Commit a transaction
    • cubrid_connect — Open a connection to a CUBRID Server
    • cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
    • cubrid_current_oid — Get OID of the current cursor location
    • cubrid_disconnect — Close a database connection
    • cubrid_drop — Delete an instance using OID
    • cubrid_error_code — Get error code for the most recent function call
    • cubrid_error_code_facility — Get the facility code of error
    • cubrid_error_msg — Get last error message for the most recent function call
    • cubrid_execute — Execute a prepared SQL statement
    • cubrid_fetch — Fetch the next row from a result set
    • cubrid_free_result — Free the memory occupied by the result data
    • cubrid_get — Get a column using OID
    • cubrid_get_autocommit — Get auto-commit mode of the connection
    • cubrid_get_charset — Return the current CUBRID connection charset
    • cubrid_get_class_name — Get the class name using OID
    • cubrid_get_client_info — Return the client library version
    • cubrid_get_db_parameter — Returns the CUBRID database parameters
    • cubrid_get_query_timeout — Get the query timeout value of the request
    • cubrid_get_server_info — Return the CUBRID server version
    • cubrid_insert_id — Return the ID generated for the last updated AUTO_INCREMENT column
    • cubrid_is_instance — Check whether the instance pointed by OID exists
    • cubrid_lob_close — Close BLOB/CLOB data
    • cubrid_lob_export — Export BLOB/CLOB data to file
    • cubrid_lob_get — Get BLOB/CLOB data
    • cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
    • cubrid_lob_size — Get BLOB/CLOB data size
    • cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters
    • cubrid_lob2_close — Close LOB object
    • cubrid_lob2_export — Export the lob object to a file
    • cubrid_lob2_import — Import BLOB/CLOB data from a file
    • cubrid_lob2_new — Create a lob object
    • cubrid_lob2_read — Read from BLOB/CLOB data
    • cubrid_lob2_seek — Move the cursor of a lob object
    • cubrid_lob2_seek64 — Move the cursor of a lob object
    • cubrid_lob2_size — Get a lob object's size
    • cubrid_lob2_size64 — Get a lob object's size
    • cubrid_lob2_tell — Tell the cursor position of the LOB object
    • cubrid_lob2_tell64 — Tell the cursor position of the LOB object
    • cubrid_lob2_write — Write to a lob object
    • cubrid_lock_read — Set a read lock on the given OID
    • cubrid_lock_write — Set a write lock on the given OID
    • cubrid_move_cursor — Move the cursor in the result
    • cubrid_next_result — Get result of next query when executing multiple SQL statements
    • cubrid_num_cols — Return the number of columns in the result set
    • cubrid_num_rows — Get the number of rows in the result set
    • cubrid_pconnect — Open a persistent connection to a CUBRID server
    • cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
    • cubrid_prepare — Prepare a SQL statement for execution
    • cubrid_put — Update a column using OID
    • cubrid_rollback — Roll back a transaction
    • cubrid_schema — Get the requested schema information
    • cubrid_seq_drop — Delete an element from sequence type column using OID
    • cubrid_seq_insert — Insert an element to a sequence type column using OID
    • cubrid_seq_put — Update the element value of sequence type column using OID
    • cubrid_set_add — Insert a single element to set type column using OID
    • cubrid_set_autocommit — Set autocommit mode of the connection
    • cubrid_set_db_parameter — Sets the CUBRID database parameters
    • cubrid_set_drop — Delete an element from set type column using OID
    • cubrid_set_query_timeout — Set the timeout time of query execution
    • cubrid_version — Get the CUBRID PHP module's version
  • CUBRID MySQL 互換関数
    • cubrid_affected_rows — Return the number of rows affected by the last SQL statement
    • cubrid_client_encoding — Return the current CUBRID connection charset
    • cubrid_close — Close CUBRID connection
    • cubrid_data_seek — Move the internal row pointer of the CUBRID result
    • cubrid_db_name — Get db name from results of cubrid_list_dbs
    • cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
    • cubrid_error — Get the error message
    • cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
    • cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
    • cubrid_fetch_field — Get column information from a result and return as an object
    • cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
    • cubrid_fetch_object — Fetch the next row and return it as an object
    • cubrid_fetch_row — Return a numerical array with the values of the current row
    • cubrid_field_flags — Return a string with the flags of the given field offset
    • cubrid_field_len — Get the maximum length of the specified field
    • cubrid_field_name — Return the name of the specified field index
    • cubrid_field_seek — Move the result set cursor to the specified field offset
    • cubrid_field_table — Return the name of the table of the specified field
    • cubrid_field_type — Return the type of the column corresponding to the given field offset
    • cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
    • cubrid_num_fields — Return the number of columns in the result set
    • cubrid_ping — Ping a server connection or reconnect if there is no connection
    • cubrid_query — Send a CUBRID query
    • cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
    • cubrid_result — Return the value of a specific field in a specific row
    • cubrid_unbuffered_query — Perform a query without fetching the results into memory
  • CUBRID 廃止されたエイリアスと関数
    • cubrid_load_from_glo — Read data from a GLO instance and save it in a file
    • cubrid_new_glo — Create a glo instance
    • cubrid_save_to_glo — Save requested file in a GLO instance
    • cubrid_send_glo — Read data from glo and send it to std output


はじめに

これらの関数により、CUBRID データベースサーバーにアクセスできます。 CUBRID についての詳細は、» CUBRIDで見つかります。

CUBRID についてのドキュメントは、» CUBRID ドキュメント で見つかります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • CUBRID
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

In order to have these functions available, you must install CUBRID, and compile CUBRID PHP Library with CUBRID support.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/cubrid.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

Linux および Windows システムでの手動インストールについて詳しくは、 パッケージに含まれるファイル build-guide.html をお読みください。


  • ≪ インストール手順
  • リソース型 ≫
  • PHP Manual
  • インストール/設定
  • 実行時設定

実行時設定

There is no runtime configuration now.


リソース型

There are four resource types used in CUBRID. The first one is the link identifier for a database connection, the second is the a resource which holds the result of a query, and the last two a resource which holds the query results of BLOB/CLOB data types.

connection identifier

A connection identifier returned by cubrid_connect(),
cubrid_connect_with_url(),
cubrid_pconnect() and
cubrid_pconnect_with_url().

request identifier

A request identifier returned by cubrid_prepare() and cubrid_execute().

LOB identifier

A LOB identifier returned by cubrid_lob_get().

LOB2 identifier

A LOB identifier returned by cubrid_lob2_new() or get from the result set.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

The following constants can be used when executing SQL statement. They can be passed to cubrid_prepare() and cubrid_execute().

CUBRID SQL execution flags
Constant | Description
CUBRID_INCLUDE_OID | Determine whether to get OID during query execution.
CUBRID_ASYNC | Execute the query in asynchronous mode.
CUBRID_EXEC_QUERY_ALL | Execute the query in synchronous mode. This flag must be set when executing multiple SQL statements.

The following constants can be used when fetching the results to specify fetch behaviour. They can be passed to cubrid_fetch() and cubrid_fetch_array().

CUBRID fetch flags
Constant | Description
CUBRID_NUM | Get query result as a numeric array (0-default).
CUBRID_ASSOC | Get query result as an associative array.
CUBRID_BOTH | Get query result as both numeric and associative arrays (default value).
CUBRID_OBJECT | Get query result an object.
CUBRID_LOB | The constant CUBRID_LOB can be used when you want to operate the lob object. It can be passed to cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() and cubrid_fetch_object().

The following constants can be used when positioning the cursor in query results. They can be passed to or returned by cubrid_move_cursor().

CUBRID cursor position flags
Constant | Description
CUBRID_CURSOR_FIRST | Move current cursor to the first position in the result.
CUBRID_CURSOR_CURRENT | Move current cursor as a default value if the origin is not specified.
CUBRID_CURSOR_LAST | Move current cursor to the last position in the result.
CUBRID_CURSOR_SUCCESS | Returned value of cubrid_move_cursor() function in case of success. This flag has been removed from 8.4.1.
CUBRID_NO_MORE_DATA | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1.
CUBRID_CURSOR_ERROR | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1.

The following constants can be used when setting the auto-commit mode for the database connection. They can be passed to cubrid_set_autocommit() or returned by cubrid_get_autocommit().

CUBRID auto-commit mode flags
Constant | Description
CUBRID_AUTOCOMMIT_TRUE | Enable the auto-commit mode.
CUBRID_AUTOCOMMIT_FALSE | Disable the auto-commit mode.

The following constants can be used when setting the database parameter. They can be passed to cubrid_set_db_parameter().

CUBRID parameter flags
Constant | Description
CUBRID_PARAM_ISOLATION_LEVEL | Transaction isolation level for the database connection.
CUBRID_PARAM_LOCK_TIMEOUT | Transaction timeout in seconds.

The following constants can be used when setting the transaction isolation level. They can be passed to cubrid_set_db_parameter() or returned by cubrid_get_db_parameter().

CUBRID isolation level flags
Constant | Description
TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE | The lowest isolation level (1). A dirty, non-repeatable or phantom read may occur for the tuple and a non-repeatable read may occur for the table as well.
TRAN_COMMIT_CLASS_COMMIT_INSTANCE | A relatively low isolation level (2). A dirty read does not occur, but non-repeatable or phantom read may occur.
TRAN_REP_CLASS_UNCOMMIT_INSTANCE | The default isolation of CUBRID (3). A dirty, non-repeatable or phantom read may occur for the tuple, but repeatable read is ensured for the table.
TRAN_REP_CLASS_COMMIT_INSTANCE | A relatively low isolation level (4). A dirty read does not occur, but non-repeatable or phantom read may.
TRAN_REP_CLASS_REP_INSTANCE | A relatively high isolation level (5). A dirty or non-repeatable read does not occur, but a phantom read may.
TRAN_SERIALIZABLE | The highest isolation level (6). Problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur.

The following constants can be used when getting schema information. They can be passed to cubrid_schema().

CUBRID schema flags
Constant | Description
CUBRID_SCH_CLASS | Get name and type of table in CUBRID.
CUBRID_SCH_VCLASS | Get name and type of view in CUBRID.
CUBRID_SCH_QUERY_SPEC | Get the query definition of view.
CUBRID_SCH_ATTRIBUTE | Get the attributes of table column.
CUBRID_SCH_CLASS_ATTRIBUTE | Get the attributes of table.
CUBRID_SCH_METHOD | Get the instance method. The instance method is a method called by a class instance. It is used more often than the class method because most operations are executed in the instance.
CUBRID_SCH_CLASS_METHOD | Get the class method. The class method is a method called by a class object. It is usually used to create a new class instance or to initialize it. It is also used to access or update class attributes.
CUBRID_SCH_METHOD_FILE | Get the information of the file where the method of the table is defined.
CUBRID_SCH_SUPERCLASS | Get the name and type of table which table inherites attributes from.
CUBRID_SCH_SUBCLASS | Get the name and type of table which inherites attributes from this table.
CUBRID_SCH_CONSTRAINT | Get the table constraints.
CUBRID_SCH_TRIGGER | Get the table triggers.
CUBRID_SCH_CLASS_PRIVILEGE | Get the privilege information of table.
CUBRID_SCH_ATTR_PRIVILEGE | Get the privilege information of column.
CUBRID_SCH_DIRECT_SUPER_CLASS | Get the direct super table of table.
CUBRID_SCH_PRIMARY_KEY | Get the table primary key.
CUBRID_SCH_IMPORTED_KEYS | Get imported keys of table.
CUBRID_SCH_EXPORTED_KEYS | Get exported keys of table.
CUBRID_SCH_CROSS_REFERENCE | Get reference relationship of tow tables.

The following constants can be used when reporting errors. They can be returned from cubrid_error_code_facility().

CUBRID error facility code
Constant | Description
CUBRID_FACILITY_DBMS | The error occurred in CUBRID dbms.
CUBRID_FACILITY_CAS | The error occurred in CUBRID broker cas.
CUBRID_FACILITY_CCI | The error occurred in CUBRID cci.
CUBRID_FACILITY_CLIENT | The error occurred in CUBRID PHP client.


例

The following is a simple example that establishes a connection between PHP and CUBRID. This section will cover the most basic and notable features. The following code required to connect to CUBRID database, which means CUBRID Server and CUBRID Broker have to be running.

The example below uses the demodb database as an examples. By default it is created during the installation. Make sure it has been created.

例1 Example of Data Retrieval

<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=euc-kr">
</head>
<body>
<center>
<table border=2>
<?php
/**
* Set server information for CUBRID connection. host_ip is the IP
* address where the CUBRID Broker is installed (localhost in this
* example), and host_port is the port number of the CUBRID Broker.
* The port number is the default given during the installation.
* For details, see "Administrator's Guide."
*/
$host_ip = "localhost";
$host_port = 33000;
$db_name = "demodb";
/**
* Connect to CUBRID Server. Do not make the actual connection, but
* only retain the connection information. The reason for not making
* the actual connection is to handle transaction more efficiently
* in the 3-tier architecture.
*/
$cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

if (!$cubrid_con) {
echo "Database Connection Error";
exit;
}
?>
 <?php
$sql = "select sports, count(players) as players from event group by sports";
/**
* Request the CUBRID Server for the results of the SQL statement.
* Now make the actual connection to the CUBRID Server.
*/
$result = cubrid_execute($cubrid_con, $sql);

if ($result) {
/**
* Get the column names from the result set created by the SQL query.
*/
$columns = cubrid_column_names($result);
/**
* Get the number of columns in the result set created by the SQL query.
*/
$num_fields = cubrid_num_cols($result);
/**
* List the column names of the result set on the screen.
*/
echo "<tr>";

while (list($key, $colname) = each($columns)) {
echo "<td align=center>$colname</td>";
}

echo "</tr>";

/**
* Get the results from the result set.
*/
while ($row = cubrid_fetch($result)) {
echo "<tr>";

for ($i = 0; $i < $num_fields; $i++) {
echo "<td align=center>";
echo $row[$i];
echo "</td>";
}

echo "</tr>";
}
}
/**
* The PHP module in the CUBRID runs in a 3-tier architecture. Even when
* calling SELECT for transaction processing, it is processed as a part
* of the transaction. Therefore, the transaction needs to be rolled back
* by calling commit or rollback even though SELECT was called for smooth
* performance.
*/
cubrid_commit($cubrid_con);
cubrid_disconnect($cubrid_con);
?>
 </body>
</html>

例2 Example of Data Insertion

<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=euc- kr">
</head>
<body>
<center>
<table border=2>
<?php
/**
* host_ip is the IP address where the CUBRID Broker is installed
* host_port is the port number of the CUBRID Broker
* db_name is the name of CUBRID Database
*/
$host_ip = "localhost";
$host_port = 33000;
$db_name = "demodb";
$cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

if (!$cubrid_con) {
echo "Database Connection Error";
exit;
}
?>
 <?php
$sql = "insert into olympic (host_year,host_nation,host_city,"
. "opening_date,closing_date) values (2008, 'China', 'Beijing',"
. "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;";
$result = cubrid_execute($cubrid_con, $sql);
if ($result) {
/**
* Handled successfully, so commit.
*/
cubrid_commit($cubrid_con);
echo "Inserted successfully ";
} else {
/**
* Error occurred, so the error message is output and rollback is called.
*/
echo cubrid_error_msg();
cubrid_rollback($cubrid_con);
}
cubrid_disconnect($cubrid_con);
?>
 </body>
</html>


CUBRID 関数

目次

  • cubrid_bind — Bind variables to a prepared statement as parameters
  • cubrid_close_prepare — Close the request handle
  • cubrid_close_request — Close the request handle
  • cubrid_col_get — Get contents of collection type column using OID
  • cubrid_col_size — Get the number of elements in collection type column using OID
  • cubrid_column_names — Get the column names in result
  • cubrid_column_types — Get column types in result
  • cubrid_commit — Commit a transaction
  • cubrid_connect — Open a connection to a CUBRID Server
  • cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
  • cubrid_current_oid — Get OID of the current cursor location
  • cubrid_disconnect — Close a database connection
  • cubrid_drop — Delete an instance using OID
  • cubrid_error_code — Get error code for the most recent function call
  • cubrid_error_code_facility — Get the facility code of error
  • cubrid_error_msg — Get last error message for the most recent function call
  • cubrid_execute — Execute a prepared SQL statement
  • cubrid_fetch — Fetch the next row from a result set
  • cubrid_free_result — Free the memory occupied by the result data
  • cubrid_get — Get a column using OID
  • cubrid_get_autocommit — Get auto-commit mode of the connection
  • cubrid_get_charset — Return the current CUBRID connection charset
  • cubrid_get_class_name — Get the class name using OID
  • cubrid_get_client_info — Return the client library version
  • cubrid_get_db_parameter — Returns the CUBRID database parameters
  • cubrid_get_query_timeout — Get the query timeout value of the request
  • cubrid_get_server_info — Return the CUBRID server version
  • cubrid_insert_id — Return the ID generated for the last updated AUTO_INCREMENT column
  • cubrid_is_instance — Check whether the instance pointed by OID exists
  • cubrid_lob_close — Close BLOB/CLOB data
  • cubrid_lob_export — Export BLOB/CLOB data to file
  • cubrid_lob_get — Get BLOB/CLOB data
  • cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
  • cubrid_lob_size — Get BLOB/CLOB data size
  • cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters
  • cubrid_lob2_close — Close LOB object
  • cubrid_lob2_export — Export the lob object to a file
  • cubrid_lob2_import — Import BLOB/CLOB data from a file
  • cubrid_lob2_new — Create a lob object
  • cubrid_lob2_read — Read from BLOB/CLOB data
  • cubrid_lob2_seek — Move the cursor of a lob object
  • cubrid_lob2_seek64 — Move the cursor of a lob object
  • cubrid_lob2_size — Get a lob object's size
  • cubrid_lob2_size64 — Get a lob object's size
  • cubrid_lob2_tell — Tell the cursor position of the LOB object
  • cubrid_lob2_tell64 — Tell the cursor position of the LOB object
  • cubrid_lob2_write — Write to a lob object
  • cubrid_lock_read — Set a read lock on the given OID
  • cubrid_lock_write — Set a write lock on the given OID
  • cubrid_move_cursor — Move the cursor in the result
  • cubrid_next_result — Get result of next query when executing multiple SQL statements
  • cubrid_num_cols — Return the number of columns in the result set
  • cubrid_num_rows — Get the number of rows in the result set
  • cubrid_pconnect — Open a persistent connection to a CUBRID server
  • cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
  • cubrid_prepare — Prepare a SQL statement for execution
  • cubrid_put — Update a column using OID
  • cubrid_rollback — Roll back a transaction
  • cubrid_schema — Get the requested schema information
  • cubrid_seq_drop — Delete an element from sequence type column using OID
  • cubrid_seq_insert — Insert an element to a sequence type column using OID
  • cubrid_seq_put — Update the element value of sequence type column using OID
  • cubrid_set_add — Insert a single element to set type column using OID
  • cubrid_set_autocommit — Set autocommit mode of the connection
  • cubrid_set_db_parameter — Sets the CUBRID database parameters
  • cubrid_set_drop — Delete an element from set type column using OID
  • cubrid_set_query_timeout — Set the timeout time of query execution
  • cubrid_version — Get the CUBRID PHP module's version


Bind variables to a prepared statement as parameters

  • ≪ CUBRID 関数
  • cubrid_close_prepare ≫
  • PHP Manual
  • CUBRID 関数
  • Bind variables to a prepared statement as parameters

cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Bind variables to a prepared statement as parameters

説明

cubrid_bind(
resource $req_identifier,
int $bind_index,
mixed $bind_value,
string $bind_value_type = ?
): bool

The cubrid_bind() function is used to bind values to a corresponding named or question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If bind_value_type is not given, string will be the default.

注意:

If the type of data to be bound is BLOB/CLOB, CUBRID will try to map the data as a PHP stream. If the actually bind value type is not stream, CUBRID will convert it to string, and use it as the full path and file name of a file on the client filesystem.

If the type of data to be bound explicitly is ENUM, the bind_value argument should be the enum element which is in string format.

In CUBRID shard envrioment, the bind_value_type must be included in the cubrid_bind() function.

The following table shows the types of substitute values.

CUBRID Bind Date Types
Support | Bind Type | Corresponding SQL Type
Supported | STRING | CHAR, VARCHAR
 | NCHAR | NCHAR, NVARCHAR
 | BIT | BIT, VARBIT
 | NUMERIC or NUMBER | SHORT, INT, NUMERIC
 | FLOAT | FLOAT
 | DOUBLE | DOUBLE
 | TIME | TIME
 | DATE | DATE
 | TIMESTAMP | TIMESTAMP
 | OBJECT | OBJECT
 | ENUM | ENUM
 | BLOB | BLOB
 | CLOB | CLOB
 | NULL | NULL
Not supported | SET | SET
 | MULTISET | MULTISET
 | SEQUENCE | SEQUENCE

パラメータ

req_identifier

Request identifier as a result of cubrid_prepare().

bind_index

Location of binding parameters. It starts with 1.

bind_value

Actual value for binding.

bind_value_type

A type of the value to bind. (It is omitted by default. Thus, the system internally uses string by default. However, you need to specify the exact type of the value as an argument when they are NCHAR, BIT, or BLOB/CLOB).

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.1 | Added BLOB/CLOB data types support.

例

例1 cubrid_bind() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
$row = cubrid_fetch_array($result, CUBRID_ASSOC);
$event_code = $row["code"];

cubrid_close_request($result);

$game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
cubrid_bind($game_req, 1, $event_code, "number");
cubrid_execute($game_req);

printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
$athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
cubrid_execute($athlete_req);
$row = cubrid_fetch_assoc($athlete_req);
printf("%s\n", $row["name"]);
}

cubrid_close_request($game_req);
cubrid_close_request($athlete_req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

--- Dream Team (1992 United States men's Olympic basketball team) ---
Stockton John
Robinson David
Pippen Scottie
Mullin C.
Malone Karl
Laettner C.
Jordan Michael
Johnson Earvin
Ewing Patrick
Drexler Clyde
Bird Larry
Barkley Charles

例2 cubrid_bind() BLOB/CLOB example

<?php
$con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
if ($con) {
cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
$sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
$req = cubrid_prepare($con, $sql);

$fp = fopen("book.txt", "rb");

cubrid_bind($req, 1, $fp, "clob");
cubrid_execute($req);
}
?>

例3 cubrid_bind() BLOB/CLOB example

<?php
$con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
if ($con) {
cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
$sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
$req = cubrid_prepare($con, $sql);

cubrid_bind($req, 1, "cubrid_logo.png", "blob");
cubrid_execute($req);
}
?>

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_prepare() - Prepare a SQL statement for execution


Close the request handle

  • ≪ cubrid_bind
  • cubrid_close_request ≫
  • PHP Manual
  • CUBRID 関数
  • Close the request handle

cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Close the request handle

説明

cubrid_close_prepare(resource $req_identifier): bool

The cubrid_close_prepare() function closes the request handle given by the req_identifier argument, and releases the memory region related to the handle. It is an alias of cubrid_close_request().

パラメータ

req_identifier

Request identifier.

戻り値

Return true on success.

例

例1 cubrid_close_prepare() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
if ($con) {
echo "connected successfully";
$req = cubrid_execute ( $con, "select * from members",
CUBRID_INCLUDE_OID | CUBRID_ASYNC);
if ($req) {
while ( list ($id, $name) = cubrid_fetch ($req) ){
echo $id;
echo $name;
}
cubrid_close_prepare($req); // or you can use cubrid_close_request($req)
}
cubrid_disconnect($con);
}
?>

参考

  • cubrid_close_request() - Close the request handle


Close the request handle

  • ≪ cubrid_close_prepare
  • cubrid_col_get ≫
  • PHP Manual
  • CUBRID 関数
  • Close the request handle

cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Close the request handle

説明

cubrid_close_request(resource $req_identifier): bool

The cubrid_close_request() function closes the request handle given by the req_identifier argument, and releases the memory region related to the handle. It is an alias of cubrid_close_prepare().

パラメータ

req_identifier

Request identifier.

戻り値

Return true on success.

例

例1 cubrid_close_request() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
if ($con) {
echo "connected successfully";
$req = cubrid_execute ( $con, "select * from members",
CUBRID_INCLUDE_OID | CUBRID_ASYNC);
if ($req) {
while ( list ($id, $name) = cubrid_fetch ($req) ){
echo $id;
echo $name;
}
cubrid_close_request($req); // or you can use cubrid_close_prepare($req)
}
cubrid_disconnect($con);
}
?>

参考

  • cubrid_close_prepare() - Close the request handle


Get contents of collection type column using OID

  • ≪ cubrid_close_request
  • cubrid_col_size ≫
  • PHP Manual
  • CUBRID 関数
  • Get contents of collection type column using OID

cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Get contents of collection type column using OID

説明

cubrid_col_get(resource $conn_identifier, string $oid, string $attr_name): array

The cubrid_col_get() function is used to get contents of the elements of the collection type (set, multiset, sequence) attribute you requested as an array.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to read.

attr_name

Attribute name that you want to read from the instance.

戻り値

Array (0-based numerical array) containing the elements you requested, when process is successful;

false (to distinguish the error from the situation of attribute having empty collection or NULL, in case of error, a warning message is shown; in such case you can check the error by using cubrid_error_code()), when process is unsuccessful.

例

例1 cubrid_col_get() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

$size = cubrid_col_size($conn, $oid, "b");
var_dump($size);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
int(3)


Get the number of elements in collection type column using OID

  • ≪ cubrid_col_get
  • cubrid_column_names ≫
  • PHP Manual
  • CUBRID 関数
  • Get the number of elements in collection type column using OID

cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Get the number of elements in collection type column using OID

説明

cubrid_col_size(resource $conn_identifier, string $oid, string $attr_name): int

The cubrid_col_size() function is used to get the number of elements in a collection type (set, multiset, sequence) attribute.

パラメータ

conn_identifier

Connection identifier.

oid

OID the instance that you want to work with.

attr_name

Name of the attribute that you want to work with.

戻り値

Number of elements, when process is successful,失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.3.1 | Change return value: when process is unsuccessful, return false, not -1.

例

例1 cubrid_col_size() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

$size = cubrid_col_size($conn, $oid, "b");
var_dump($size);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
int(3)


Get the column names in result

  • ≪ cubrid_col_size
  • cubrid_column_types ≫
  • PHP Manual
  • CUBRID 関数
  • Get the column names in result

cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Get the column names in result

説明

cubrid_column_names(resource $req_identifier): array

The cubrid_column_names() function is used to get the column names of the query result by using req_identifier.

パラメータ

req_identifier

Request identifier.

戻り値

Array of string values containing the column names, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_column_names() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);

printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
$column_len = cubrid_field_len($result, $i);
printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Column Names                   Column Types                   Column Maxlen
host_year                      integer                        11
event_code                     integer                        11
athlete_code                   integer                        11
stadium_code                   integer                        11
nation_code                    char                           3
medal                          char                           1
game_date                      date                           10

参考

  • cubrid_prepare() - Prepare a SQL statement for execution
  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_column_types() - Get column types in result


Get column types in result

  • ≪ cubrid_column_names
  • cubrid_commit ≫
  • PHP Manual
  • CUBRID 関数
  • Get column types in result

cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Get column types in result

説明

cubrid_column_types(resource $req_identifier): array

The cubrid_column_types() function gets column types of query results by using req_identifier.

パラメータ

req_identifier

Request identifier.

戻り値

Array of string values containing the column types, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_column_types() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);

printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
$column_len = cubrid_field_len($result, $i);
printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Column Names                   Column Types                   Column Maxlen
host_year                      integer                        11
event_code                     integer                        11
athlete_code                   integer                        11
stadium_code                   integer                        11
nation_code                    char                           3
medal                          char                           1
game_date                      date                           10

参考

  • cubrid_column_names() - Get the column names in result
  • cubrid_prepare() - Prepare a SQL statement for execution
  • cubrid_execute() - Execute a prepared SQL statement


Commit a transaction

  • ≪ cubrid_column_types
  • cubrid_connect ≫
  • PHP Manual
  • CUBRID 関数
  • Commit a transaction

cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Commit a transaction

説明

cubrid_commit(resource $conn_identifier): bool

The cubrid_commit() function is used to execute commit on the transaction pointed by conn_identifier, currently in progress. Connection to the server is closed after the cubrid_commit() function is called; However, the connection handle is still valid.

In CUBRID PHP, auto-commit mode is disabled by default for transaction management. You can set it by using cubrid_set_autocommit(). You can get its status by using cubrid_get_autocommit(). Before you start a transaction, remember to disable the auto-commit mode.

パラメータ

conn_identifier

Connection identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_commit() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE publishers");

$sql = <<<EOD
CREATE TABLE publishers(
pub_id CHAR(3),
pub_name VARCHAR(20),
city VARCHAR(15),
state CHAR(2),
country VARCHAR(15)
)
EOD;
cubrid_set_autocommit($conn,false);
if (!cubrid_execute($conn, $sql)) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

cubrid_disconnect($conn);
exit;
}

$req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

$id_list = array("P01", "P02", "P03", "P04");
$name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
$city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
$state_list = array("NY", "CA", NULL, "CA");
$country_list = array("USA", "USA", "Germany", "USA");

for ($i = 0, $size = count($id_list); $i < $size; $i++) {
cubrid_bind($req, 1, $id_list[$i]);
cubrid_bind($req, 2, $name_list[$i]);
cubrid_bind($req, 3, $city_list[$i]);
cubrid_bind($req, 4, $state_list[$i]);
cubrid_bind($req, 5, $country_list[$i]);

if (!($ret = cubrid_execute($req))) {
break;
}
}

if (!$ret) {
cubrid_rollback($conn);
} else {
cubrid_commit($conn);

$req = cubrid_execute($conn, "SELECT * FROM publishers");
while ($result = cubrid_fetch_assoc($req)) {
printf("%-3s %-20s %-15s %-3s %-15s\n",
$result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
}
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

P01 Abatis Publishers    New York        NY  USA
P02 Core Dump Books      San Francisco   CA  USA
P03 Schadenfreude Press  Hamburg             Germany
P04 Tenterhooks Press    Berkeley        CA  USA

参考

  • cubrid_rollback() - Roll back a transaction
  • cubrid_get_autocommit() - Get auto-commit mode of the connection
  • cubrid_set_autocommit() - Set autocommit mode of the connection


Open a connection to a CUBRID Server

  • ≪ cubrid_commit
  • cubrid_connect_with_url ≫
  • PHP Manual
  • CUBRID 関数
  • Open a connection to a CUBRID Server

cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Open a connection to a CUBRID Server

説明

cubrid_connect(
string $host,
int $port,
string $dbname,
string $userid = ?,
string $passwd = ?,
bool $new_link = false
): resource

The cubrid_connect() function is used to establish the environment for connecting to your server by using your server address, port number, database name, user name, and password. If the user name and password is not given, then the "PUBLIC" connection will be made by default.

パラメータ

host

Host name or IP address of CUBRID CAS server.

port

Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).

dbname

Name of database.

userid

User name for the database. If not given, the default value is "public".

passwd

User password. If not given, the default value is "".

new_link

If a second call is made to cubrid_connect() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The new_link parameter modifies this behavior and makes cubrid_connect() always open a new connection, even if cubrid_connect() was called before with the same parameters.

戻り値

Connection identifier, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_connect() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1

参考

  • cubrid_pconnect() - Open a persistent connection to a CUBRID server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
  • cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
  • cubrid_disconnect() - Close a database connection
  • cubrid_close() - Close CUBRID connection


Establish the environment for connecting to CUBRID server

  • ≪ cubrid_connect
  • cubrid_current_oid ≫
  • PHP Manual
  • CUBRID 関数
  • Establish the environment for connecting to CUBRID server

cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Establish the environment for connecting to CUBRID server

説明

cubrid_connect_with_url(
string $conn_url,
string $userid = ?,
string $passwd = ?,
bool $new_link = false
): resource

The cubrid_connect_with_url() function is used to establish the environment for connecting to your server by using connection information passed with an url string argument. If the HA feature is enabled in CUBRID, you must specify the connection information of the standby server, which is used for failover when failure occurs, in the url string argument of this function. If the user name and password is not given, then the "PUBLIC" connection will be made by default.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

  • host : A host name or IP address of the master database
  • db_name : A name of the database
  • db_user : A name of the database user
  • db_password : A database user password
  • alhosts : Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
  • rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
  • login_timeout : Timeout value (unit: msec.) for database login. The default value is 0, which means infinite postponement.
  • query_timeout : Timeout value (unit: msec.) for query request. Upon timeout, a message to cancel requesting a query transferred to server is sent. The return value can depend on the disconnect_on_query_timeout configuration; even though the message to cancel a request is sent to server, that request may succeed.
  • disconnect_on_query_timeout : Configures a value whether to immediately return an error of function being executed upon timeout. The default value is false.

注意:

? and : that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "?:".

$url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100";

Passwords that contain ? or : may be passed as a separate parameter.

$url = "CUBRID:localhost:33000:tbd:::?login_timeout=100";

$conn = cubrid_connect_with_url($url, "dba", "12?");

If user or password is empty,you can't delete ":",the following is an example.

$url = "CUBRID:localhost:33000:demodb:::";

パラメータ

conn_url

A character string that contains server connection information.

userid

User name for the database.

passwd

User password.

new_link

If a second call is made to cubrid_connect_with_url() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The new_link parameter modifies this behavior and makes cubrid_connect_with_url() always open a new connection, even if cubrid_connect_with_url() was called before with the same parameters.

戻り値

Connection identifier, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_connect_with_url() url without properties example

<?php
$conn_url = "CUBRID:localhost:33000:demodb:dba::";
$con = cubrid_connect_with_url($conn_url);

if ($con) {
echo "connected successfully";
cubrid_execute($con, "create table person(id int,name char(16))");
$req =cubrid_execute($con, "insert into person values(1,'James')");

if ($req) {
cubrid_close_request($req);
cubrid_commit($con);
} else {
cubrid_rollback($con);
}
cubrid_disconnect($con);
}
?>

例2 cubrid_connect_with_url() url with properties example

<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?login_timeout=100";
$con = cubrid_connect_with_url ($conn_url);

if ($con) {
echo "connected successfully";
cubrid_execute($con, "create table person(id int,name char(16))");
$req =cubrid_execute($con, "insert into person values(1,'James')");

if ($req) {
cubrid_close_request($req);
cubrid_commit($con);
} else {
cubrid_rollback($con);
}
cubrid_disconnect($con);
}
?>

参考

  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_pconnect() - Open a persistent connection to a CUBRID server
  • cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
  • cubrid_disconnect() - Close a database connection
  • cubrid_close() - Close CUBRID connection


Get OID of the current cursor location

  • ≪ cubrid_connect_with_url
  • cubrid_disconnect ≫
  • PHP Manual
  • CUBRID 関数
  • Get OID of the current cursor location

cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Get OID of the current cursor location

説明

cubrid_current_oid(resource $req_identifier): string

The cubrid_current_oid() function is used to get the oid of the current cursor location from the query result. To use cubrid_current_oid(), the query executed must be a updatable query, and the CUBRID_INCLUDE_OID option must be included during the query execution.

パラメータ

req_identifier

Request identifier.

戻り値

Oid of current cursor location, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_current_oid() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);
$res = cubrid_get($conn, $oid);

print_r($res);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Array
(
    [s_name] => X
    [f_name] => Mixed
)

参考

  • cubrid_execute() - Execute a prepared SQL statement


Close a database connection

  • ≪ cubrid_current_oid
  • cubrid_drop ≫
  • PHP Manual
  • CUBRID 関数
  • Close a database connection

cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Close a database connection

説明

cubrid_disconnect(resource $conn_identifier = ?): bool

The cubrid_disconnect() function closes the connection handle and disconnects from server. If any request handle is not closed at this point, it will be closed. It is similar to the CUBRID MySQL compatible function cubrid_close().

パラメータ

conn_identifier

Connection identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_disconnect() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb");
if ($con) {
echo "connected successfully";

$req = cubrid_execute( $con, "create table person(id int,name char(10))");
if ($req) {
cubrid_close_request($req);
cubrid_commit($con);
} else {
cubrid_rollback($con);
}

$req = cubrid_execute( $con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request($req);
cubrid_commit($con);
} else {
cubrid_rollback($con);
}
cubrid_disconnect($con);
}
?>

参考

  • cubrid_close() - Close CUBRID connection
  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server


Delete an instance using OID

  • ≪ cubrid_disconnect
  • cubrid_error_code ≫
  • PHP Manual
  • CUBRID 関数
  • Delete an instance using OID

cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Delete an instance using OID

説明

cubrid_drop(resource $conn_identifier, string $oid): bool

The cubrid_drop() function is used to delete an instance from database by using the oid of the instance.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the instance that you want to delete.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_drop() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

printf("--- Before Drop: ---\n");
$attr = cubrid_get($conn, $oid);
var_dump($attr);

if (cubrid_drop($conn, $oid)) {
cubrid_commit($conn);
} else {
cubrid_rollback($conn);
}

cubrid_close_request($req);

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

printf("\n--- After Drop: ---\n");
$attr = cubrid_get($conn, $oid);
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

--- Before Drop: ---
array(4) {
  ["a"]=>
  string(1) "1"
  ["b"]=>
  array(3) {
    [0]=>
    string(1) "1"
    [1]=>
    string(1) "2"
    [2]=>
    string(1) "3"
  }
  ["c"]=>
  array(4) {
    [0]=>
    string(2) "11"
    [1]=>
    string(2) "22"
    [2]=>
    string(2) "33"
    [3]=>
    string(3) "333"
  }
  ["d"]=>
  string(10) "a         "
}

--- After Drop: ---
array(4) {
  ["a"]=>
  string(1) "2"
  ["b"]=>
  array(3) {
    [0]=>
    string(1) "4"
    [1]=>
    string(1) "5"
    [2]=>
    string(1) "7"
  }
  ["c"]=>
  array(4) {
    [0]=>
    string(2) "44"
    [1]=>
    string(2) "55"
    [2]=>
    string(2) "66"
    [3]=>
    string(3) "666"
  }
  ["d"]=>
  string(10) "b         "
}

参考

  • cubrid_is_instance() - Check whether the instance pointed by OID exists


Get error code for the most recent function call

  • ≪ cubrid_drop
  • cubrid_error_code_facility ≫
  • PHP Manual
  • CUBRID 関数
  • Get error code for the most recent function call

cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Get error code for the most recent function call

説明

cubrid_error_code(): int

The cubrid_error_code() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.

パラメータ

この関数にはパラメータはありません。

戻り値

Error code of the error that occurred, or 0 (zero) if no error occurred.

例

例1 cubrid_error_code() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

$req = @cubrid_execute($req);
if (!$req) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n",
cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

cubrid_disconnect($conn);
exit;
}
?>

上の例の出力は以下となります。

Error facility: 4
Error code: -30015
Error msg: Some parameter not binded

参考

  • cubrid_error_code_facility() - Get the facility code of error
  • cubrid_error_msg() - Get last error message for the most recent function call


Get the facility code of error

  • ≪ cubrid_error_code
  • cubrid_error_msg ≫
  • PHP Manual
  • CUBRID 関数
  • Get the facility code of error

cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Get the facility code of error

説明

cubrid_error_code_facility(): int

The cubrid_error_code_facility() function is used to get the facility code (level in which the error occurred) from the error code of the error that occurred during the API execution. Usually, you can get the error code when API returns false as its return value.

パラメータ

この関数にはパラメータはありません。

戻り値

Facility code of the error code that occurred: CUBRID_FACILITY_DBMS, CUBRID_FACILITY_CAS, CUBRID_FACILITY_CCI, CUBRID_FACILITY_CLIENT.

例

例1 cubrid_error_code_facility() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = @cubrid_execute($conn, "SELECT * FROM unknown");
if (!$req) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n",
cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

cubrid_disconnect($conn);
exit;
}
?>

上の例の出力は以下となります。

Error facility: 1
Error code: -493
Error msg: Syntax: In line 1, column 15 before END OF STATEMENT
Syntax error: unexpected 'unknown'

参考

  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_msg() - Get last error message for the most recent function call


Get last error message for the most recent function call

  • ≪ cubrid_error_code_facility
  • cubrid_execute ≫
  • PHP Manual
  • CUBRID 関数
  • Get last error message for the most recent function call

cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Get last error message for the most recent function call

説明

cubrid_error_msg(): string

The cubrid_error_msg() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.

パラメータ

この関数にはパラメータはありません。

戻り値

Error message that occurred.

例

例1 cubrid_error_msg() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

if (!@cubrid_schema($conn, 100000)) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n",
cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

cubrid_disconnect($conn);
exit;
}
?>

上の例の出力は以下となります。

Error facility: 2
Error code: -10015
Error msg: Invalid T_CCI_SCH_TYPE value

参考

  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_code_facility() - Get the facility code of error


Execute a prepared SQL statement

  • ≪ cubrid_error_msg
  • cubrid_fetch ≫
  • PHP Manual
  • CUBRID 関数
  • Execute a prepared SQL statement

cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Execute a prepared SQL statement

説明

cubrid_execute(resource $conn_identifier, string $sql, int $option = 0): resource
cubrid_execute(resource $request_identifier, int $option = 0): bool

The cubrid_execute() function is used to execute the given SQL statement. It executes the query by using conn_identifier and SQL, and then returns the request identifier created. It is used for simple execution of query, where the parameter binding is not needed. In addition, the cubrid_execute() function is used to execute the prepared statement by means of cubrid_prepare() and cubrid_bind(). At this time, you need to specify arguments of request_identifier and option.

The option is used to determine whether to get OID after query execution and whether to execute the query in synchronous or asynchronous mode. CUBRID_INCLUDE_OID and CUBRID_ASYNC (or CUBRID_EXEC_QUERY_ALL if you want to execute multiple SQL statements) can be specified by using a bitwise OR operator. If not specified, neither of them isselected. If the flag CUBRID_EXEC_QUERY_ALL is set, a synchronous mode (sync_mode) is used to retrieve query results, and in such cases the following rules are applied:

  • The return value is the result of the first query.
  • If an error occurs in any query, the execution is processed as a failure.
  • In a query composed of q1 q2 q3, if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.
  • If a query is executed successfully, the result of the second query can be obtained using cubrid_next_result().

If the first argument is request_identifier to execute the cubrid_prepare() function, you can specify an option, CUBRID_ASYNC only.

パラメータ

conn_identifier

Connection identifier.

sql

SQL to be executed.

option

Query execution option CUBRID_INCLUDE_OID, CUBRID_ASYNC, CUBRID_EXEC_QUERY_ALL.

request_identifier

cubrid_prepare() identifier.

戻り値

Request identifier, when process is successful and first param is conn_identifier; true, when process is successful and first argument is request_identifier,失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.4.0 | Add new option CUBRID_EXEC_QUERY_ALL.

例

例1 cubrid_execute() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
$row = cubrid_fetch_array($result, CUBRID_ASSOC);
$event_code = $row["code"];

cubrid_close_request($result);

$history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
cubrid_bind($history_req, 1, $event_code, "number");
cubrid_execute($history_req);

printf("%-20s %-9s %-10s %-5s\n", "athlete", "host_year", "score", "unit");
while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
printf("%-20s %-9s %-10s %-5s\n",
$row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
}

cubrid_close_request($history_req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

athlete              host_year score      unit
Phelps Michael       2004      51.25      time

参考

  • cubrid_prepare() - Prepare a SQL statement for execution
  • cubrid_bind() - Bind variables to a prepared statement as parameters
  • cubrid_next_result() - Get result of next query when executing multiple SQL statements
  • cubrid_close_request() - Close the request handle
  • cubrid_commit() - Commit a transaction
  • cubrid_rollback() - Roll back a transaction


Fetch the next row from a result set

  • ≪ cubrid_execute
  • cubrid_free_result ≫
  • PHP Manual
  • CUBRID 関数
  • Fetch the next row from a result set

cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Fetch the next row from a result set

説明

cubrid_fetch(resource $result, int $type = CUBRID_BOTH): mixed

The cubrid_fetch() function is used to get a single row from the query result. The cursor automatically moves to the next row after getting the result.

パラメータ

result

result comes from a call to cubrid_execute()

type

Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT. If you want to operate the lob object, you can use CUBRID_LOB.

戻り値

Result array or object, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

The result can be received either as an array or as an object, and you can decide which data type to use by setting the type argument. The type variable can be set to one of the following values:

  • CUBRID_NUM : Numerical array (0-based)
  • CUBRID_ASSOC : Associative array
  • CUBRID_BOTH : Numerical & Associative array (default)
  • CUBRID_OBJECT : object that has the attribute name as the column name of query result

When type argument is omitted, the result will be received using CUBRID_BOTH option as default. When you want to receive query result in object data type, the column name of the result must obey the naming rules for identifiers in PHP. For example, column name such as "count(*)" cannot be received in object type.

例

例1 cubrid_fetch() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch($req)) {
printf("%-40s %-10s %-6s %-20s\n",
$row["name"], $row["area"], $row["seats"], $row["address"]);
}

// if you want to operate lob object, you can use cubrid_fetch($req, CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_row() - Return a numerical array with the values of the current row
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_object() - Fetch the next row and return it as an object


Free the memory occupied by the result data

  • ≪ cubrid_fetch
  • cubrid_get ≫
  • PHP Manual
  • CUBRID 関数
  • Free the memory occupied by the result data

cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Free the memory occupied by the result data

説明

cubrid_free_result(resource $req_identifier): bool

This function frees the memory occupied by the result data. It returns true on success or false on failure. Note that it can only frees the client fetch buffer now, and if you want free all memory, use function cubrid_close_request().

パラメータ

req_identifier

This is the request identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_free_result() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
$row = cubrid_fetch_assoc($req);
var_dump($row);

cubrid_free_result($req);
cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(5) {
  ["event_code"]=>
  string(5) "20005"
  ["athlete"]=>
  string(12) "Hayes Joanna"
  ["host_year"]=>
  string(4) "2004"
  ["score"]=>
  string(5) "12.37"
  ["unit"]=>
  string(4) "time"
}


Get a column using OID

  • ≪ cubrid_free_result
  • cubrid_get_autocommit ≫
  • PHP Manual
  • CUBRID 関数
  • Get a column using OID

cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Get a column using OID

説明

cubrid_get(resource $conn_identifier, string $oid, mixed $attr = ?): mixed

The cubrid_get() function is used to get the attribute of the instance of the given oid. You can get single attribute by using string data type for the attr argument, or many attributes by using array data type for the attr argument.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to read.

attr

Name of the attribute that you want to read.

戻り値

Content of the requested attribute, when process is successful; When attr is set with string data type, the result is returned as a string; when attr is set with array data type (0-based numerical array), then the result is returned in associative array. When attr is omitted, then all attributes are received in array form.

false when process is unsuccessful or result is NULL (If error occurs to distinguish empty string from NULL, then it prints the warning message. You can check the error by using cubrid_error_code())

例

例1 cubrid_get() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_get($conn, $oid, "b");
var_dump($attr);

$attr = cubrid_get($conn, $oid);
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(9) "{1, 2, 3}"
array(4) {
  ["a"]=>
  string(1) "1"
  ["b"]=>
  array(3) {
    [0]=>
    string(1) "1"
    [1]=>
    string(1) "2"
    [2]=>
    string(1) "3"
  }
  ["c"]=>
  array(4) {
    [0]=>
    string(2) "11"
    [1]=>
    string(2) "22"
    [2]=>
    string(2) "33"
    [3]=>
    string(3) "333"
  }
  ["d"]=>
  string(10) "a         "
}

参考

  • cubrid_put() - Update a column using OID


Get auto-commit mode of the connection

  • ≪ cubrid_get
  • cubrid_get_charset ≫
  • PHP Manual
  • CUBRID 関数
  • Get auto-commit mode of the connection

cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Get auto-commit mode of the connection

説明

cubrid_get_autocommit(resource $conn_identifier): bool

The cubrid_get_autocommit() function is used to get the status of CUBRID database connection auto-commit mode.

For CUBRID 8.4.0, auto-commit mode is disabled by default for transaction management.

For CUBRID 8.4.1, auto-commit mode is enabled by default for transaction management.

パラメータ

conn_identifier

Connection identifier.

戻り値

true, when auto-commit is on.

false, when auto-commit is off.

null on error.

参考

  • cubrid_set_autocommit() - Set autocommit mode of the connection
  • cubrid_commit() - Commit a transaction


Return the current CUBRID connection charset

  • ≪ cubrid_get_autocommit
  • cubrid_get_class_name ≫
  • PHP Manual
  • CUBRID 関数
  • Return the current CUBRID connection charset

cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Return the current CUBRID connection charset

説明

cubrid_get_charset(resource $conn_identifier): string

This function returns the current CUBRID connection charset and is similar to the CUBRID MySQL compatible function cubrid_client_encoding().

パラメータ

conn_identifier

The CUBRID connection.

戻り値

A string that represents the CUBRID connection charset on success,失敗した場合に false を返します.

例

例1 cubrid_get_charset() example

<?php

$con = cubrid_connect("localhost", 33000, "demodb");
if (!$con)
{
die('Could not connect.');
}

printf("CUBRID current charset: %s\n", cubrid_get_charset($con));

?>

上の例の出力は以下となります。

CUBRID current charset: iso8859-1

参考

  • cubrid_client_encoding() - Return the current CUBRID connection charset


Get the class name using OID

  • ≪ cubrid_get_charset
  • cubrid_get_client_info ≫
  • PHP Manual
  • CUBRID 関数
  • Get the class name using OID

cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Get the class name using OID

説明

cubrid_get_class_name(resource $conn_identifier, string $oid): string

The cubrid_get_class_name() function is used to get the class name from oid. It doesn't work when selecting data from the system tables, for example db_class.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to check the existence.

戻り値

Class name when process is successful,失敗した場合に false を返します.

例

例1 cubrid_get_class_name() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);
$class_name = cubrid_get_class_name($conn, $oid);

print_r($class_name);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

code

参考

  • cubrid_is_instance() - Check whether the instance pointed by OID exists
  • cubrid_drop() - Delete an instance using OID


Return the client library version

  • ≪ cubrid_get_class_name
  • cubrid_get_db_parameter ≫
  • PHP Manual
  • CUBRID 関数
  • Return the client library version

cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Return the client library version

説明

cubrid_get_client_info(): string

This function returns a string that represents the client library version.

パラメータ

戻り値

A string that represents the client library version on success,失敗した場合に false を返します.

例

例1 cubrid_get_client_info() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_connect("localhost", 33088, "demodb");

if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);

?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1


Returns the CUBRID database parameters

  • ≪ cubrid_get_client_info
  • cubrid_get_query_timeout ≫
  • PHP Manual
  • CUBRID 関数
  • Returns the CUBRID database parameters

cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Returns the CUBRID database parameters

説明

cubrid_get_db_parameter(resource $conn_identifier): array

This function returns the CUBRID database parameters,失敗した場合に false を返します. It returns an associative array with the values for the following parameters:

  • PARAM_ISOLATION_LEVEL
  • PARAM_LOCK_TIMEOUT
  • PARAM_MAX_STRING_LENGTH
  • PARAM_AUTO_COMMIT

Database parameters
Parameter | Description
PARAM_ISOLATION_LEVEL | The transaction isolation level.
LOCK_TIMEOUT | CUBRID provides the lock timeout feature, which sets the waiting time (in seconds) for the lock until the transaction lock setting is allowed. The default value of the lock_timeout_in_secs parameter is -1, which means the application client will wait indefinitely until the transaction lock is allowed.
PARAM_AUTO_COMMIT | In CUBRID PHP, auto-commit mode is disabled by default for transaction management. It can be set by using cubrid_set_autocommit().

The following table shows the isolation levels from 1 to 6. It consists of table schema (row) and isolation level:

Levels of Isolation Supported by CUBRID
Name | Description
SERIALIZABLE (6) | In this isolation level, problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur.
REPEATABLE READ CLASS with REPEATABLE READ INSTANCES (5) | Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience phantom read for the record R that was inserted by another transaction T2 when it is repeatedly retrieving a specific record.
REPEATABLE READ CLASS with READ COMMITTED INSTANCES (or CURSOR STABILITY) (4) | Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience R read (non-repeatable read) that was updated and committed by another transaction T2 when it is repeatedly retrieving the record R.
REPEATABLE READ CLASS with READ UNCOMMITTED INSTANCES (3) | Default isolation level. Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience R' read (dirty read) for the record that was updated but not committed by another transaction T2.
READ COMMITTED CLASS with READ COMMITTED INSTANCES (2) | Transaction T1 may experience A' read (non-repeatable read) for the table that was updated and committed by another transaction T2 while it is viewing table A repeatedly. Transaction T1 may experience R' read (non-repeatable read) for the record that was updated and committed by another transaction T2 while it is retrieving the record R repeatedly.
READ COMMITTED CLASS with READ UNCOMMITTED INSTANCES (1) | Transaction T1 may experience A' read (non-repeatable read) for the table that was updated and committed by another transaction T2 while it is repeatedly viewing table A. Transaction T1 may experience R' read (dirty read) for the record that was updated but not committed by another transaction T2.

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

戻り値

An associative array with CUBRID database parameters; on success,失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.4.0 | Change LOCK_TIMEOUT to PARAM_LOCK_TIMEOUT, and MAX_STRING_LENGTH to PARAM_MAX_STRING_LENGTH in result.

例

例1 cubrid_get_db_parameter() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_connect("localhost", 33088, "demodb");

if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);

?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1

参考

  • cubrid_set_db_parameter() - Sets the CUBRID database parameters
  • cubrid_get_autocommit() - Get auto-commit mode of the connection


Get the query timeout value of the request

  • ≪ cubrid_get_db_parameter
  • cubrid_get_server_info ≫
  • PHP Manual
  • CUBRID 関数
  • Get the query timeout value of the request

cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Get the query timeout value of the request

説明

cubrid_get_query_timeout(resource $req_identifier): int

The cubrid_get_query_timeout() function is used to get the query timeout of the request.

パラメータ

req_identifier

Request identifier.

戻り値

Returns the query timeout value in milliseconds of the current request on success,失敗した場合に false を返します.

例

例1 cubrid_get_query_timeout() example

<?php

$host = "localhost";
$port = 33000;
$db = "demodb";

$conn =
cubrid_connect_with_url("CUBRID:$host:$port:$db:::?login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");

$req = cubrid_prepare($conn, "SELECT * FROM code");

$timeout = cubrid_get_query_timeout($req);
var_dump($timeout);

cubrid_set_query_timeout($req, 1000);
$timeout = cubrid_get_query_timeout($req);
var_dump($timeout);

cubrid_close($conn);
?>

上の例の出力は以下となります。

int(5000)
int(1000)

参考

  • cubrid_set_query_timeout() - Set the timeout time of query execution


Return the CUBRID server version

  • ≪ cubrid_get_query_timeout
  • cubrid_insert_id ≫
  • PHP Manual
  • CUBRID 関数
  • Return the CUBRID server version

cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Return the CUBRID server version

説明

cubrid_get_server_info(resource $conn_identifier): string

This function returns a string that represents the CUBRID server version.

パラメータ

conn_identifier

The CUBRID connection.

戻り値

A string that represents the CUBRID server version on success,失敗した場合に false を返します.

例

例1 cubrid_get_server_info() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_connect("localhost", 33088, "demodb");

if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);

?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1


Return the ID generated for the last updated AUTO_INCREMENT column

  • ≪ cubrid_get_server_info
  • cubrid_is_instance ≫
  • PHP Manual
  • CUBRID 関数
  • Return the ID generated for the last updated AUTO_INCREMENT column

cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Return the ID generated for the last updated AUTO_INCREMENT column

説明

cubrid_insert_id(resource $conn_identifier = ?): string

The cubrid_insert_id() function retrieves the ID generated for the AUTO_INCREMENT column which is updated by the previous INSERT query. It returns 0 if the previous query does not generate new rows, or FALSE on failure.

注意:

CUBRID supports AUTO_INCREMENT for more than one columns in a table. In most cases, there will be a single AUTO_INCREMENT column in a table. If there are multiple AUTO_INCREMENT columns, this function should not be used even if it will return a value.

パラメータ

conn_identifier

The connection identifier previously obtained by a call to cubrid_connect().

戻り値

A string representing the ID generated for an AUTO_INCREMENT column by the previous query, on success.

0, if the previous query does not generate new rows.

false on failure.

変更履歴

バージョン | 説明
8.4.0 | Change the return value from an array to string; Remove the first parameter class_name.

例

例1 cubrid_insert_id() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

for ($i = 0; $i < 10; $i++) {
cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
}

$id = cubrid_insert_id();
var_dump($id);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(2) "19"


Check whether the instance pointed by OID exists

  • ≪ cubrid_insert_id
  • cubrid_lob_close ≫
  • PHP Manual
  • CUBRID 関数
  • Check whether the instance pointed by OID exists

cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Check whether the instance pointed by OID exists

説明

cubrid_is_instance(resource $conn_identifier, string $oid): int

The cubrid_is_instance() function is used to check whether the instance pointed by the given oid exists or not.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to check the existence.

戻り値

1, if such instance exists;

0, if such instance does not exist;

-1, in case of error

例

例1 cubrid_is_instance() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$sql = <<<EOD
SELECT host_year, medal, game_date
FROM game
WHERE athlete_code IN
(SELECT code FROM athlete WHERE name='Thorpe Ian');
EOD;

$req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
$oid = cubrid_current_oid($req);

$res = cubrid_is_instance ($conn, $oid);
if ($res == 1) {
echo "Instance pointed by $oid exists.\n";
} else if ($res == 0){
echo "Instance pointed by $oid doesn't exist.\n";
} else {
echo "error\n";
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Instance pointed by @0|0|0 doesn't exist.

参考

  • cubrid_drop() - Delete an instance using OID
  • cubrid_get_class_name() - Get the class name using OID


Close BLOB/CLOB data

  • ≪ cubrid_is_instance
  • cubrid_lob_export ≫
  • PHP Manual
  • CUBRID 関数
  • Close BLOB/CLOB data

cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Close BLOB/CLOB data

説明

cubrid_lob_close(array $lob_identifier_array): bool

cubrid_lob_close() is used to close all BLOB/CLOB returned from cubrid_lob_get().

パラメータ

lob_identifier_array

LOB identifier array returned from cubrid_lob_get().

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob_close() example

<?php
$conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

cubrid_execute($conn,"DROP TABLE if exists doc");
cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

$lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob_get() - Get BLOB/CLOB data
  • cubrid_lob_size() - Get BLOB/CLOB data size
  • cubrid_lob_export() - Export BLOB/CLOB data to file
  • cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser


Export BLOB/CLOB data to file

  • ≪ cubrid_lob_close
  • cubrid_lob_get ≫
  • PHP Manual
  • CUBRID 関数
  • Export BLOB/CLOB data to file

cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Export BLOB/CLOB data to file

説明

cubrid_lob_export(resource $conn_identifier, resource $lob_identifier, string $path_name): bool

cubrid_lob_export() is used to get BLOB/CLOB data from CUBRID database, and saves its contents to a file. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.

パラメータ

conn_identifier

Connection identifier.

lob_identifier

LOB identifier.

path_name

Path name of the file.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob_export() example

<?php
$conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

cubrid_execute($conn,"DROP TABLE if exists doc");
cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

$lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob_get() - Get BLOB/CLOB data
  • cubrid_lob_close() - Close BLOB/CLOB data
  • cubrid_lob_size() - Get BLOB/CLOB data size
  • cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser


Get BLOB/CLOB data

  • ≪ cubrid_lob_export
  • cubrid_lob_send ≫
  • PHP Manual
  • CUBRID 関数
  • Get BLOB/CLOB data

cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Get BLOB/CLOB data

説明

cubrid_lob_get(resource $conn_identifier, string $sql): array

cubrid_lob_get() is used to get BLOB/CLOB meta info from CUBRID database, CUBRID gets BLOB/CLOB by executing the SQL statement, and returns all LOBs as a resource array. Be sure that the SQL retrieves only one column and its data type is BLOB or CLOB.

Remember to use cubrid_lob_close() to release the LOBs if you don't need it any more.

パラメータ

conn_identifier

Connection identifier.

sql

SQL statement to be executed.

戻り値

Return an array of LOB resources, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_lob_get() example

<?php
$conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

cubrid_execute($conn,"DROP TABLE if exists doc");
cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

$lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob_close() - Close BLOB/CLOB data
  • cubrid_lob_size() - Get BLOB/CLOB data size
  • cubrid_lob_export() - Export BLOB/CLOB data to file
  • cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser


Read BLOB/CLOB data and send straight to browser

  • ≪ cubrid_lob_get
  • cubrid_lob_size ≫
  • PHP Manual
  • CUBRID 関数
  • Read BLOB/CLOB data and send straight to browser

cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Read BLOB/CLOB data and send straight to browser

説明

cubrid_lob_send(resource $conn_identifier, resource $lob_identifier): bool

cubrid_lob_send() reads BLOB/CLOB data and passes it straight through to the browser. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.

パラメータ

conn_identifier

Connection identifier.

lob_identifier

LOB identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob_send() example

<?php
$conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

cubrid_execute($conn,"DROP TABLE if exists doc");
cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

$lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");

cubrid_lob_send($conn, $lobs[0]);
cubrid_lob_close($lobs);
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob_get() - Get BLOB/CLOB data
  • cubrid_lob_close() - Close BLOB/CLOB data
  • cubrid_lob_size() - Get BLOB/CLOB data size
  • cubrid_lob_export() - Export BLOB/CLOB data to file


Get BLOB/CLOB data size

  • ≪ cubrid_lob_send
  • cubrid_lob2_bind ≫
  • PHP Manual
  • CUBRID 関数
  • Get BLOB/CLOB data size

cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Get BLOB/CLOB data size

説明

cubrid_lob_size(resource $lob_identifier): string

cubrid_lob_size() is used to get BLOB/CLOB data size.

パラメータ

lob_identifier

LOB identifier.

戻り値

A string representing LOB data size, when process is successful,失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.4.0 | Change return value type from int to string.

例

例1 cubrid_lob_size() example

<?php
$lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
echo "Doc size:".cubrid_lob_size($lobs[0]);
cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
cubrid_lob_close($lobs);
?>

参考

  • cubrid_lob_get() - Get BLOB/CLOB data
  • cubrid_lob_close() - Close BLOB/CLOB data
  • cubrid_lob_export() - Export BLOB/CLOB data to file
  • cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser


Bind a lob object or a string as a lob object to a prepared statement as parameters

  • ≪ cubrid_lob_size
  • cubrid_lob2_close ≫
  • PHP Manual
  • CUBRID 関数
  • Bind a lob object or a string as a lob object to a prepared statement as parameters

cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters

説明

cubrid_lob2_bind(
resource $req_identifier,
int $bind_index,
mixed $bind_value,
string $bind_value_type = ?
): bool

The cubrid_lob2_bind() function is used to bind BLOB/CLOB datas to a corresponding question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If bind_value_type is not given, string will be "BLOB" as the default. But if you use cubrid_lob2_new() before, bind_value_type will be consistent with type in cubrid_lob2_new() as the default.

パラメータ

req_identifier

Request identifier as a result of cubrid_prepare().

bind_index

Location of binding parameters. It starts with 1.

bind_value

Actual value for binding.

bind_value_type

It must be "BLOB" or "CLOB" and it won't be case-sensitive. If it not be given, the default value is "BLOB".

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob2_bind() example

<?php
// Table: test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists test_lob");
cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

cubrid_bind($req,1, 3);

$lob = cubrid_lob2_new($conn, 'CLOB');
cubrid_lob2_bind($req, 2, $lob);

cubrid_execute($req);

cubrid_bind($req, 1, 4);

cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

cubrid_execute($req);

cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_new() - Create a lob object
  • cubrid_lob2_close() - Close LOB object


Close LOB object

  • ≪ cubrid_lob2_bind
  • cubrid_lob2_export ≫
  • PHP Manual
  • CUBRID 関数
  • Close LOB object

cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Close LOB object

説明

cubrid_lob2_close(resource $lob_identifier): bool

The cubrid_lob2_close() function is used to close LOB object returned from cubrid_lob2_new() or got from the result set.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • cubrid_lob2_new() - Create a lob object


Export the lob object to a file

  • ≪ cubrid_lob2_close
  • cubrid_lob2_import ≫
  • PHP Manual
  • CUBRID 関数
  • Export the lob object to a file

cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Export the lob object to a file

説明

cubrid_lob2_export(resource $lob_identifier, string $file_name): bool

The cubrid_lob2_export() function is used to save the contents of BLOB/CLOB data to a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file already exists, the operation will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

filename

File name you want to store BLOB/CLOB data. It also supports the path of the file.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob2_export() example

<?php
// Table: test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists doc");
cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

$req = cubrid_prepare($conn, "select * from doc");

cubrid_execute($req);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);

$row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

cubrid_lob2_export($row[1], "doc_3.txt");

cubrid_lob2_close($row[1]);
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_new() - Create a lob object
  • cubrid_lob2_close() - Close LOB object
  • cubrid_lob2_import() - Import BLOB/CLOB data from a file
  • cubrid_lob2_bind() - Bind a lob object or a string as a lob object to a prepared statement as parameters


Import BLOB/CLOB data from a file

  • ≪ cubrid_lob2_export
  • cubrid_lob2_new ≫
  • PHP Manual
  • CUBRID 関数
  • Import BLOB/CLOB data from a file

cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Import BLOB/CLOB data from a file

説明

cubrid_lob2_import(resource $lob_identifier, string $file_name): bool

The cubrid_lob2_import() function is used to save the contents of BLOB/CLOB data from a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file already exists, the operation will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

filename

File name you want to import BLOB/CLOB data. It also supports the path of the file.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob2_export() example

<?php

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists test_lob");
cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
cubrid_bind($req, 1, 1);

$lob = cubrid_lob2_new($conn, "clob");
cubrid_lob2_import($lob, "doc_1.txt");
cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // or cubrid_lob2_bind($req, 2, $lob);

cubrid_execute($req);

cubrid_lob2_close($lob);
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_new() - Create a lob object
  • cubrid_lob2_close() - Close LOB object
  • cubrid_lob2_export() - Export the lob object to a file
  • cubrid_lob2_bind() - Bind a lob object or a string as a lob object to a prepared statement as parameters


Create a lob object

  • ≪ cubrid_lob2_import
  • cubrid_lob2_read ≫
  • PHP Manual
  • CUBRID 関数
  • Create a lob object

cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Create a lob object

説明

cubrid_lob2_new(resource $conn_identifier = ?, string $type = "BLOB"): resource

The cubrid_lob2_new() function is used to create a lob object (both BLOB and CLOB). This function should be used before you bind a lob object.

パラメータ

conn_identifier

Connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() or cubrid_connect_with_url() is assumed.

type

It may be "BLOB" or "CLOB", it won't be case-sensitive. The default value is "BLOB".

戻り値

Lob identifier when it is successful,失敗した場合に false を返します.

参考

  • cubrid_lob2_close() - Close LOB object


Read from BLOB/CLOB data

  • ≪ cubrid_lob2_new
  • cubrid_lob2_seek ≫
  • PHP Manual
  • CUBRID 関数
  • Read from BLOB/CLOB data

cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Read from BLOB/CLOB data

説明

cubrid_lob2_read(resource $lob_identifier, int $len): string

The cubrid_lob2_read() function reads len bytes from the LOB data and returns the bytes read.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

len

Length from buffer you want to read from the lob data.

戻り値

Returns the contents as a string, false when there is no more data, or null on failure.

例

例1 cubrid_lob2_read() example 1

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

$req = cubrid_execute($conn, "select * from test_lob");

$row = cubrid_fetch_row($req, CUBRID_LOB);

print "position now is " . cubrid_lob2_tell($row[1]) . "\n";

cubrid_lob2_seek($row[1], 10, CUBRID_CURSOR_FIRST);

print "\nposition after moving farword is " . cubrid_lob2_tell($row[1]) . "\n";

$data = cubrid_lob2_read($row[1], 12);

print "\nposition after reading is " . cubrid_lob2_tell($row[1]) . "\n";

print $data . "\n";

cubrid_lob2_seek($row[1], 5, CUBRID_CURSOR_CURRENT);

print "\nposition after moving again is " . cubrid_lob2_tell($row[1]) . "\n";

$data = cubrid_lob2_read($row[1], 20);
print $data . "\n";

cubrid_disconnect($conn);
?>

例2 cubrid_lob2_read() example 2

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

$req = cubrid_execute($conn, "select * from test_lob");

$row = cubrid_fetch_row($req, CUBRID_LOB);

while (true) {
if ($data = cubrid_lob2_read($row[1], 1024)) {
print $data . "\n";
}
elseif ($data === false) {
print "There is no more data\n";
break;
}
else {
print "There must some errors\n";
break;
}
}

cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size
  • cubrid_lob2_size64() - Get a lob object's size


Move the cursor of a lob object

  • ≪ cubrid_lob2_read
  • cubrid_lob2_seek64 ≫
  • PHP Manual
  • CUBRID 関数
  • Move the cursor of a lob object

cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Move the cursor of a lob object

説明

cubrid_lob2_seek(resource $lob_identifier, int $offset, int $origin = CUBRID_CURSOR_CURRENT): bool

The cubrid_lob2_seek() function is used to move the cursor position of a lob object by the value set in the offset argument, to the direction set in the origin argument.

To set the origin argument, you can use CUBRID_CURSOR_FIRST to set the cursor position moving forward offset units from the first beginning. In this case, offset must be a positive value.

If you use CUBRID_CURSOR_CURRENT for origin, you can move forward or backward. and offset can be positive or negative.

If you use CUBRID_CURSOR_LAST for origin, you can move backward offset units from the end of LOB object and offset only can be positive.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

offset

Number of units you want to move the cursor.

origin

This parameter can be the following values:

CUBRID_CURSOR_FIRST: move forward from the first beginning.

CUBRID_CURSOR_CURRENT: move forward or backward from the current position.

CUBRID_CURSOR_LAST: move backward at the end of LOB object.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob2_seek() example

<?php
// test_lob (id INT, contents CLOB)
$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists test_lob");
cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");
$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

$lob = cubrid_lob2_new($conn, 'CLOB');
$len = cubrid_lob2_write($lob, "Hello world");

cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
cubrid_lob2_write($lob, "beautiful");

cubrid_lob2_seek($lob, 15, CUBRID_CURSOR_FIRST);
$data = cubrid_lob2_read($lob, 5);

echo $data."\n";

cubrid_lob2_bind($req, 1, $lob);
cubrid_execute($req);

cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size
  • cubrid_lob2_size64() - Get a lob object's size


Move the cursor of a lob object

  • ≪ cubrid_lob2_seek
  • cubrid_lob2_size ≫
  • PHP Manual
  • CUBRID 関数
  • Move the cursor of a lob object

cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Move the cursor of a lob object

説明

cubrid_lob2_seek64(resource $lob_identifier, string $offset, int $origin = CUBRID_CURSOR_CURRENT): bool

The cubrid_lob2_seek64() function is used to move the cursor position of a lob object by the value set in the offset argument, to the direction set in the origin argument. If the offset you want to move is larger than an integer data can be stored, you can use this function.

To set the origin argument, you can use CUBRID_CURSOR_FIRST to set the cursor position moving forward offset units from the first beginning. In this case, offset must be a positive value.

If you use CUBRID_CURSOR_CURRENT for origin, you can move forward or backward. and offset can be positive or negative.

If you use CUBRID_CURSOR_LAST for origin, you can move backward offset units from the end of LOB object and offset only can be positive.

注意:

If you use this function to move the cursor position of the lob object, you should pass offset as a string.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

offset

Number of units you want to move the cursor.

origin

This parameter can be the following values:

CUBRID_CURSOR_FIRST: move forward from the first beginning.

CUBRID_CURSOR_CURRENT: move forward or backward from the current position.

CUBRID_CURSOR_LAST: move backward at the end of LOB object.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob2_seek64() example

<?php
// test_lob (id INT, contents CLOB)
// Data length of doc_1.txt should be greater than 20101029056306120215.

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists test_lob");
cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
cubrid_bind($req, 1, 1);

$lob = cubrid_lob2_new($conn, "clob");
cubrid_lob2_import($lob, "doc_1.txt");
cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // or cubrid_lob2_bind($req, 2, $lob);

cubrid_execute($req);

cubrid_lob2_close($lob);

$req = cubrid_execute($conn, "select * from test_lob");
$row = cubrid_fetch_row($req, CUBRID_LOB);
$lob = $row[1];

cubrid_lob2_seek64($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
$data = cubrid_lob2_read($lob, 20);
echo $data."\n";
cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size
  • cubrid_lob2_size64() - Get a lob object's size


Get a lob object's size

  • ≪ cubrid_lob2_seek64
  • cubrid_lob2_size64 ≫
  • PHP Manual
  • CUBRID 関数
  • Get a lob object's size

cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Get a lob object's size

説明

cubrid_lob2_size(resource $lob_identifier): int

The cubrid_lob2_size() function is used to get the size of a lob object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

戻り値

It will return the size of the LOB object when it processes successfully,失敗した場合に false を返します.

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size64() - Get a lob object's size


Get a lob object's size

  • ≪ cubrid_lob2_size
  • cubrid_lob2_tell ≫
  • PHP Manual
  • CUBRID 関数
  • Get a lob object's size

cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Get a lob object's size

説明

cubrid_lob2_size64(resource $lob_identifier): string

The cubrid_lob2_size64() function is used to get the size of a lob object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the size as a string.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

戻り値

It will return the size of the LOB object as a string when it processes successfully,失敗した場合に false を返します.

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size


Tell the cursor position of the LOB object

  • ≪ cubrid_lob2_size64
  • cubrid_lob2_tell64 ≫
  • PHP Manual
  • CUBRID 関数
  • Tell the cursor position of the LOB object

cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Tell the cursor position of the LOB object

説明

cubrid_lob2_tell(resource $lob_identifier): int

The cubrid_lob2_tell() function is used to tell the cursor position of the LOB object.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

戻り値

It will return the cursor position on the LOB object when it processes successfully,失敗した場合に false を返します.

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size
  • cubrid_lob2_size64() - Get a lob object's size


Tell the cursor position of the LOB object

  • ≪ cubrid_lob2_tell
  • cubrid_lob2_write ≫
  • PHP Manual
  • CUBRID 関数
  • Tell the cursor position of the LOB object

cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Tell the cursor position of the LOB object

説明

cubrid_lob2_tell64(resource $lob_identifier): string

The cubrid_lob2_tell64() function is used to tell the cursor position of the LOB object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the position information as a string.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

戻り値

It will return the cursor position on the LOB object as a string when it processes successfully,失敗した場合に false を返します.

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_write() - Write to a lob object
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size
  • cubrid_lob2_size64() - Get a lob object's size


Write to a lob object

  • ≪ cubrid_lob2_tell64
  • cubrid_lock_read ≫
  • PHP Manual
  • CUBRID 関数
  • Write to a lob object

cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Write to a lob object

説明

cubrid_lob2_write(resource $lob_identifier, string $buf): bool

The cubrid_lob2_write() function reads as much as data from buf and stores it to the LOB object. Note that this function can only append characters now.

パラメータ

lob_identifier

Lob identifier as a result of cubrid_lob2_new() or get from the result set.

buf

Data that need to be written to the lob object.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lob2_write() example 1

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists test_lob");
cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

$lob = cubrid_lob2_new($conn, 'CLOB');
$len = cubrid_lob2_write($lob, "Hello world");

cubrid_lob2_bind($req, 1, $lob);
cubrid_execute($req);

cubrid_disconnect($conn);
?>

例2 cubrid_lob2_write() example 2

<?php
// test_lob (id INT, contents CLOB)

$conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

cubrid_execute($conn,"DROP TABLE if exists test_lob");
cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

$req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(1, ?)");
$lob1 = cubrid_lob2_new($conn, 'CLOB');
$len = cubrid_lob2_write($lob1, "cubrid php driver");
cubrid_lob2_bind($req, 1, $lob1);
cubrid_execute($req);

$req = cubrid_execute($conn, "select * from test_lob");

$row = cubrid_fetch_row($req, CUBRID_LOB);
$lob2 = $row[1];
cubrid_lob2_seek($lob2, 0, CUBRID_CURSOR_LAST);

$pos = cubrid_lob2_tell($lob2);
print "pos before write: $pos\n";

cubrid_lob2_write($lob2, "Hello world");

$pos = cubrid_lob2_tell($lob2);
print "pos after write: $pos\n";

cubrid_disconnect($conn);
?>

参考

  • cubrid_lob2_read() - Read from BLOB/CLOB data
  • cubrid_lob2_seek() - Move the cursor of a lob object
  • cubrid_lob2_seek64() - Move the cursor of a lob object
  • cubrid_lob2_tell() - Tell the cursor position of the LOB object
  • cubrid_lob2_tell64() - Tell the cursor position of the LOB object
  • cubrid_lob2_size() - Get a lob object's size
  • cubrid_lob2_size64() - Get a lob object's size


Set a read lock on the given OID

  • ≪ cubrid_lob2_write
  • cubrid_lock_write ≫
  • PHP Manual
  • CUBRID 関数
  • Set a read lock on the given OID

cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Set a read lock on the given OID

説明

cubrid_lock_read(resource $conn_identifier, string $oid): bool

The cubrid_lock_read() function is used to put read lock on the instance pointed by given oid.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to put read lock on.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lock_read() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

cubrid_lock_read($conn, $oid);

$attr = cubrid_get($conn, $oid, "b");
var_dump($attr);

$attr = cubrid_get($conn, $oid);
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(9) "{1, 2, 3}"
array(4) {
  ["a"]=>
  string(1) "1"
  ["b"]=>
  array(3) {
    [0]=>
    string(1) "1"
    [1]=>
    string(1) "2"
    [2]=>
    string(1) "3"
  }
  ["c"]=>
  array(4) {
    [0]=>
    string(2) "11"
    [1]=>
    string(2) "22"
    [2]=>
    string(2) "33"
    [3]=>
    string(3) "333"
  }
  ["d"]=>
  string(10) "a         "
}

参考

  • cubrid_lock_write() - Set a write lock on the given OID


Set a write lock on the given OID

  • ≪ cubrid_lock_read
  • cubrid_move_cursor ≫
  • PHP Manual
  • CUBRID 関数
  • Set a write lock on the given OID

cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Set a write lock on the given OID

説明

cubrid_lock_write(resource $conn_identifier, string $oid): bool

The cubrid_lock_write() function is used to put write lock on the instance pointed by the given oid.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to put write lock on.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_lock_write() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

cubrid_lock_write($conn, $oid);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_put($conn, $oid, "b", array(2, 4, 8));

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
array(3) {
  [0]=>
  string(1) "2"
  [1]=>
  string(1) "4"
  [2]=>
  string(1) "8"
}

参考

  • cubrid_lock_read() - Set a read lock on the given OID


Move the cursor in the result

  • ≪ cubrid_lock_write
  • cubrid_next_result ≫
  • PHP Manual
  • CUBRID 関数
  • Move the cursor in the result

cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Move the cursor in the result

説明

cubrid_move_cursor(resource $req_identifier, int $offset, int $origin = CUBRID_CURSOR_CURRENT): bool

The cubrid_move_cursor() function is used to move the current cursor location of req_identifier by the value set in the offset argument, to the direction set in the origin argument. To set the origin argument, you can use CUBRID_CURSOR_FIRST for the first part of the result, CUBRID_CURSOR_CURRENT for the current location of the result, or CUBRID_CURSOR_LAST for the last part of the result. If origin argument is not explicitly designated, then the function uses CUBRID_CURSOR_CURRENT as its default value.

If the value of cursor movement range goes over the valid limit, then the cursor moves to the next location after the valid range for the cursor. For example, if you move 20 units in the result with the size of 10, then the cursor will move to 11th place and return CUBRID_NO_MORE_DATA.

パラメータ

req_identifier

Request identifier.

offset

Number of units you want to move the cursor.

origin

Location where you want to move the cursor from CUBRID_CURSOR_FIRST, CUBRID_CURSOR_CURRENT, CUBRID_CURSOR_LAST.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_move_cursor() example

<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

$req = cubrid_execute($conn, "SELECT * FROM code");
cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);

$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  string(1) "G"
  [1]=>
  string(4) "Gold"
}
array(2) {
  [0]=>
  string(1) "X"
  [1]=>
  string(5) "Mixed"
}
array(2) {
  [0]=>
  string(1) "M"
  [1]=>
  string(3) "Man"
}

参考

  • cubrid_execute() - Execute a prepared SQL statement


Get result of next query when executing multiple SQL statements

  • ≪ cubrid_move_cursor
  • cubrid_num_cols ≫
  • PHP Manual
  • CUBRID 関数
  • Get result of next query when executing multiple SQL statements

cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Get result of next query when executing multiple SQL statements

説明

cubrid_next_result(resource $result): bool

The cubrid_next_result() function is used to get results of next query if multiple SQL statements are executed and CUBRID_EXEC_QUERY_ALL flag is set upon cubrid_execute().

パラメータ

result

result comes from a call to cubrid_execute()

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_next_result() example

<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

$sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
$res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);

get_result_info($res);
cubrid_next_result($res);
get_result_info($res);

function get_result_info($req)
{
printf("\n------------ get_result_info --------------------\n");

$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);

$column_name_list = cubrid_column_names($req);
$column_type_list = cubrid_column_types($req);

$column_last_name = cubrid_field_name($req, $col_num - 1);
$column_last_table = cubrid_field_table($req, $col_num - 1);

$column_last_type = cubrid_field_type($req, $col_num - 1);
$column_last_len = cubrid_field_len($req, $col_num - 1);

$column_1_flags = cubrid_field_flags($req, 1);

printf("%-30s %d\n", "Row count:", $row_num);
printf("%-30s %d\n", "Column count:", $col_num);
printf("\n");

printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Len");
printf("------------------------------------------------------------------------------\n");

$size = count($column_name_list);
for($i = 0; $i < $size; $i++) {
$column_len = cubrid_field_len($req, $i);
printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
}
printf("\n\n");

printf("%-30s %s\n", "Last Column Name:", $column_last_name);
printf("%-30s %s\n", "Last Column Table:", $column_last_table);
printf("%-30s %s\n", "Last Column Type:", $column_last_type);
printf("%-30s %d\n", "Last Column Len:", $column_last_len);
printf("%-30s %s\n", "Second Column Flags:", $column_1_flags);

printf("\n\n");
}
?>

上の例の出力は以下となります。

------------ get_result_info --------------------
Row count:                     6
Column count:                  2

Column Names                   Column Types                   Column Len
------------------------------------------------------------------------------
s_name                         char                           1
f_name                         varchar                        6

Last Column Name:              f_name
Last Column Table:             code
Last Column Type:              varchar
Last Column Len:               6
Second Column Flags:

------------ get_result_info --------------------
Row count:                     4
Column count:                  5

Column Names                   Column Types                   Column Len
------------------------------------------------------------------------------
event_code                     integer                        11
athlete                        varchar                        40
host_year                      integer                        11
score                          varchar                        10
unit                           varchar                        5

Last Column Name:              unit
Last Column Table:             history
Last Column Type:              varchar
Last Column Len:               5
Second Column Flags:           not_null primary_key unique_key

参考

  • cubrid_execute() - Execute a prepared SQL statement


Return the number of columns in the result set

  • ≪ cubrid_next_result
  • cubrid_num_rows ≫
  • PHP Manual
  • CUBRID 関数
  • Return the number of columns in the result set

cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Return the number of columns in the result set

説明

cubrid_num_cols(resource $result): int

The cubrid_num_cols() function is used to get the number of columns from the query result. It can only be used when the query executed is a SELECT statement.

パラメータ

result

Result.

戻り値

Number of columns, when process is successful.

false, if SQL statement is not SELECT.

例

例1 cubrid_num_cols() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$req = cubrid_execute($conn, "SELECT * FROM code");

$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);

printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Row Num: 6
Column Num: 2

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_num_rows() - Get the number of rows in the result set


Get the number of rows in the result set

  • ≪ cubrid_num_cols
  • cubrid_pconnect ≫
  • PHP Manual
  • CUBRID 関数
  • Get the number of rows in the result set

cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Get the number of rows in the result set

説明

cubrid_num_rows(resource $result): int

The cubrid_num_rows() function is used to get the number of rows from the query result. It can be used for SELECT statements. For INSERT, UPDATE, or DELETE queries, use the cubrid_affected_rows() function.

Note: The cubrid_num_rows() function can only be used for synchronous query; it returns 0 when it is used for asynchronous query.

パラメータ

result

result comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

戻り値

Number of rows, when process is successful.

0 when the query was done in async mode.

-1, if SQL statement is not SELECT.

false when process is unsuccessful.

例

例1 cubrid_num_rows() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$req = cubrid_execute($conn, "SELECT * FROM code");

$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_cols($req);

printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Row Num: 6
Column Num: 2

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_num_cols() - Return the number of columns in the result set
  • cubrid_affected_rows() - Return the number of rows affected by the last SQL statement


Open a persistent connection to a CUBRID server

  • ≪ cubrid_num_rows
  • cubrid_pconnect_with_url ≫
  • PHP Manual
  • CUBRID 関数
  • Open a persistent connection to a CUBRID server

cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Open a persistent connection to a CUBRID server

説明

cubrid_pconnect(
string $host,
int $port,
string $dbname,
string $userid = ?,
string $passwd = ?
): resource

Establishes a persistent connection to a CUBRID server.

cubrid_pconnect() acts very much like cubrid_connect() with two major differences.

First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.

Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect()).

This type of link is therefore called 'persistent'.

パラメータ

host

Host name or IP address of CUBRID CAS server.

port

Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).

dbname

Name of database.

userid

User name for the database.

passwd

User password.

戻り値

Connection identifier, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_connect() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1

参考

  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
  • cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
  • cubrid_disconnect() - Close a database connection
  • cubrid_close() - Close CUBRID connection


Open a persistent connection to CUBRID server

  • ≪ cubrid_pconnect
  • cubrid_prepare ≫
  • PHP Manual
  • CUBRID 関数
  • Open a persistent connection to CUBRID server

cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Open a persistent connection to CUBRID server

説明

cubrid_pconnect_with_url(string $conn_url, string $userid = ?, string $passwd = ?): resource

Establishes a persistent connection to a CUBRID server.

cubrid_pconnect_with_url() acts very much like cubrid_connect_with_url() with two major differences.

First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.

Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect_with_url()).

This type of link is therefore called 'persistent'.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

  • host : A host name or IP address of the master database
  • db_name : A name of the database
  • db_user : A name of the database user
  • db_password : A database user password
  • alhosts : Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
  • rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
  • login_timeout : Timeout value (unit: msec.) for database login. The default value is 0, which means infinite postponement.
  • query_timeout : Timeout value (unit: msec.) for query request. Upon timeout, a message to cancel requesting a query transferred to server is sent. The return value can depend on the disconnect_on_query_timeout configuration; even though the message to cancel a request is sent to server, that request may succeed.
  • disconnect_on_query_timeout : Configures a value whether to immediately return an error of function being executed upon timeout. The default value is false.

注意:

? and : that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "?:".

$url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100";

Passwords that contain ? or : may be passed as a separate parameter.

$url = "CUBRID:localhost:33000:tbd:::?login_timeout=100";

$conn = cubrid_pconnect_with_url ($url, "dba", "12?");

If user or password is empty,you can't delete ":",the following is an example.

$url = "CUBRID:localhost:33000:demodb:::";

パラメータ

conn_url

A character string that contains server connection information.

userid

User name for the database.

passwd

User password.

戻り値

Connection identifier, when process is successful,失敗した場合に false を返します.

例

例1 cubrid_pconnect_with_url() url without properties example

<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::";
$con = cubrid_pconnect_with_url ($conn_url);

if ($con) {
echo "connected successfully";
cubrid_execute($con, "create table person(id int,name char(16))");
$req =cubrid_execute($con, "insert into person values(1,'James')");

if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_disconnect ($con);
}
?>

例2 cubrid_pconnect_with_url() url with properties example

<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100";
$con = cubrid_pconnect_with_url ($conn_url);

if ($con) {
echo "connected successfully";
$req =cubrid_execute($con, "insert into person values(1,'James')");

if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_disconnect ($con);
}
?>

参考

  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
  • cubrid_pconnect() - Open a persistent connection to a CUBRID server
  • cubrid_disconnect() - Close a database connection
  • cubrid_close() - Close CUBRID connection


Prepare a SQL statement for execution

  • ≪ cubrid_pconnect_with_url
  • cubrid_put ≫
  • PHP Manual
  • CUBRID 関数
  • Prepare a SQL statement for execution

cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prepare a SQL statement for execution

説明

cubrid_prepare(resource $conn_identifier, string $prepare_stmt, int $option = 0): resource

The cubrid_prepare() function is a sort of API which represents SQL statements compiled previously to a given connection handle. This pre-compiled SQL statement will be included in the cubrid_prepare().

Accordingly, you can use this statement effectively to execute several times repeatedly or to process long data. Only a single statement can be used and a parameter may put a question mark (?) to appropriate area in the SQL statement. Add a parameter when you bind a value in the VALUES clause of INSERT statement or in the WHERE clause. Note that it is allowed to bind a value to a MARK(?) by using the cubrid_bind() function only.

パラメータ

conn_identifier

Connection identifier.

prepare_stmt

Prepare query.

option

OID return option CUBRID_INCLUDE_OID.

戻り値

Request identifier, if process is successful,失敗した場合に false を返します.

例

例1 cubrid_prepare() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$sql = <<<EOD
SELECT g.event_code, e.name
FROM game g
JOIN event e ON g.event_code=e.code
WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
EOD;

$req = cubrid_prepare($conn, $sql);

cubrid_bind($req, 1, 2004);
cubrid_bind($req, 2, 2000);
cubrid_execute($req);

$row_num = cubrid_num_rows($req);
printf("There are %d event that exits in 2004 olympic but not in 2000. For example:\n\n", $row_num);

printf("%-15s %s\n", "Event_code", "Event_name");
printf("----------------------------\n");

$row = cubrid_fetch_assoc($req);
printf("%-15d %s\n", $row["event_code"], $row["name"]);
$row = cubrid_fetch_assoc($req);
printf("%-15d %s\n", $row["event_code"], $row["name"]);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

There are 27 event that exits in 2004 olympic but not in 2000. For example:

Event_code      Event_name
----------------------------
20063           +91kg
20070           64kg

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_bind() - Bind variables to a prepared statement as parameters


Update a column using OID

  • ≪ cubrid_prepare
  • cubrid_rollback ≫
  • PHP Manual
  • CUBRID 関数
  • Update a column using OID

cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Update a column using OID

説明

cubrid_put(
resource $conn_identifier,
string $oid,
string $attr = ?,
mixed $value
): bool

The cubrid_put() function is used to update an attribute of the instance of the given oid.

You can update single attribute by using string data type to set attr. In such case, you can use integer, floating point or string type data for the value argument. To update multiple number of attributes, you can disregard the attr argument, and set value argument with associative array data type.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance that you want to update.

attr

Name of the attribute that you want to update.

value

New value that you want to assign to the attribute.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_put() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_put($conn, $oid, "b", array(2, 4, 8));

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
array(3) {
  [0]=>
  string(1) "2"
  [1]=>
  string(1) "4"
  [2]=>
  string(1) "8"
}

参考

  • cubrid_get() - Get a column using OID
  • cubrid_set_add() - Insert a single element to set type column using OID
  • cubrid_set_drop() - Delete an element from set type column using OID
  • cubrid_seq_insert() - Insert an element to a sequence type column using OID
  • cubrid_seq_drop() - Delete an element from sequence type column using OID
  • cubrid_seq_put() - Update the element value of sequence type column using OID


Roll back a transaction

  • ≪ cubrid_put
  • cubrid_schema ≫
  • PHP Manual
  • CUBRID 関数
  • Roll back a transaction

cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Roll back a transaction

説明

cubrid_rollback(resource $conn_identifier): bool

The cubrid_rollback() function executes rollback on the transaction pointed by conn_identifier, currently in progress.

Connection to server is closed after calling cubrid_rollback(). Connection handle, however, is still valid.

パラメータ

conn_identifier

Connection identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_rollback() example

<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");
cubrid_set_autocommit($conn,false);

@cubrid_execute($conn, "DROP TABLE publishers");

$sql = <<<EOD
CREATE TABLE publishers(
pub_id CHAR(3),
pub_name VARCHAR(20),
city VARCHAR(15),
state CHAR(2),
country VARCHAR(15)
)
EOD;

if (!cubrid_execute($conn, $sql)) {
printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

cubrid_disconnect($conn);
exit;
}

$req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

$id_list = array("P01", "P02", "P03", "P04");
$name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
$city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
$state_list = array("NY", "CA", NULL, "CA");
$country_list = array("USA", "USA", "Germany", "USA");

for ($i = 0, $size = count($id_list); $i < $size; $i++) {
cubrid_bind($req, 1, $id_list[$i]);
cubrid_bind($req, 2, $name_list[$i]);
cubrid_bind($req, 3, $city_list[$i]);
cubrid_bind($req, 4, $state_list[$i]);
cubrid_bind($req, 5, $country_list[$i]);

if (!($ret = cubrid_execute($req))) {
break;
}
}

if (!$ret) {
cubrid_rollback($conn);
} else {
cubrid_commit($conn);

$req = cubrid_execute($conn, "SELECT * FROM publishers");
while ($result = cubrid_fetch_assoc($req)) {
printf("%-3s %-20s %-15s %-3s %-15s\n",
$result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
}
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

P01 Abatis Publishers    New York        NY  USA
P02 Core Dump Books      San Francisco   CA  USA
P03 Schadenfreude Press  Hamburg             Germany
P04 Tenterhooks Press    Berkeley        CA  USA

参考

  • cubrid_commit() - Commit a transaction
  • cubrid_disconnect() - Close a database connection


Get the requested schema information

  • ≪ cubrid_rollback
  • cubrid_seq_drop ≫
  • PHP Manual
  • CUBRID 関数
  • Get the requested schema information

cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Get the requested schema information

説明

cubrid_schema(
resource $conn_identifier,
int $schema_type,
string $class_name = ?,
string $attr_name = ?
): array

The cubrid_schema() function is used to get the requested schema information from database. To get information about specific class, set the class_name, to get information about specific attribute (can be used only with CUBRID_SCH_ATTR_PRIVILEGE), set the attr_name.

The result of the cubrid_schema() function is returned as a two-dimensional array (column (associative array) * row (numeric array)). The following tables shows types of schema and the column structure of the result array to be returned based on the schema type.

Result Composition of Each Type
Schema | Column Number | Column Name | Value
CUBRID_SCH_CLASS | 1 | NAME |
 | 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_VCLASS | 1 | NAME |
 | 2 | TYPE | 1:vclass
CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME |
 | 2 | DOMAIN |
 | 3 | SCALE |
 | 4 | PRECISION |
 | 5 | INDEXED | 1:indexed
 | 6 | NOT NULL | 1:not null
 | 7 | SHARED | 1:shared
 | 8 | UNIQUE | 1:unique
 | 9 | DEFAULT |
 | 10 | ATTR_ORDER | base:1
 | 11 | CLASS_NAME |
 | 12 | SOURCE_CLASS |
 | 13 | IS_KEY | 1:key
CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME |
 | 2 | RET_DOMAIN |
 | 3 | ARG_DOMAIN |
CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME |
 | 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
 | 2 | NAME |
 | 3 | ATTR_NAME |
 | 4 | NUM_PAGES |
 | 5 | NUM_KEYS |
 | 6 | PRIMARY_KEY | 1:primary key
 | 7 | KEY_ORDER | base:1
CUBRID_SCH_TRIGGER | 1 | NAME |
 | 2 | STATUS |
 | 3 | EVENT |
 | 4 | TARGET_CLASS |
 | 5 | TARGET_ATTR |
 | 6 | ACTION_TIME |
 | 7 | ACTION |
 | 8 | PRIORITY |
 | 9 | CONDITION_TIME |
 | 10 | CONDITION |
CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
 | 2 | PRIVILEGE |
 | 3 | GRANTABLE |
CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
 | 2 | ATTR_NAME |
 | 3 | KEY_SEQ | base:1
 | 4 | KEY_NAME |
CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
 | 2 | PKCOLUMN_NAME |
 | 3 | FKTABLE_NAME | base:1
 | 4 | FKCOLUMN_NAME |
 | 5 | KEY_SEQ | base:1
 | 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
 | 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
 | 8 | FK_NAME |
 | 9 | PK_NAME |

パラメータ

conn_identifier

Connection identifier.

schema_type

Schema data that you want to know.

class_name

Class you want to know the schema of.

attr_name

Attribute you want to know the schema of.

戻り値

Array containing the schema information, when process is successful,失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.3.1 | Change return value: when process is unsuccessful, return false, not -1.

例

例1 cubrid_schema() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

printf("\n--- Primary Key ---\n");
$pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
var_dump($pk);

printf("\n--- Foreign Keys ---\n");
$fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
var_dump($fk);

printf("\n--- Column Attribute ---\n");
$attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
var_dump($attr);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

--- Primary Key ---
array(3) {
  [0]=>
  array(4) {
    ["CLASS_NAME"]=>
    string(4) "game"
    ["ATTR_NAME"]=>
    string(12) "athlete_code"
    ["KEY_SEQ"]=>
    string(1) "3"
    ["KEY_NAME"]=>
    string(41) "pk_game_host_year_event_code_athlete_code"
  }
  [1]=>
  array(4) {
    ["CLASS_NAME"]=>
    string(4) "game"
    ["ATTR_NAME"]=>
    string(10) "event_code"
    ["KEY_SEQ"]=>
    string(1) "2"
    ["KEY_NAME"]=>
    string(41) "pk_game_host_year_event_code_athlete_code"
  }
  [2]=>
  array(4) {
    ["CLASS_NAME"]=>
    string(4) "game"
    ["ATTR_NAME"]=>
    string(9) "host_year"
    ["KEY_SEQ"]=>
    string(1) "1"
    ["KEY_NAME"]=>
    string(41) "pk_game_host_year_event_code_athlete_code"
  }
}

--- Foreign Keys ---
array(2) {
  [0]=>
  array(9) {
    ["PKTABLE_NAME"]=>
    string(7) "athlete"
    ["PKCOLUMN_NAME"]=>
    string(4) "code"
    ["FKTABLE_NAME"]=>
    string(4) "game"
    ["FKCOLUMN_NAME"]=>
    string(12) "athlete_code"
    ["KEY_SEQ"]=>
    string(1) "1"
    ["UPDATE_RULE"]=>
    string(1) "1"
    ["DELETE_RULE"]=>
    string(1) "1"
    ["FK_NAME"]=>
    string(20) "fk_game_athlete_code"
    ["PK_NAME"]=>
    string(15) "pk_athlete_code"
  }
  [1]=>
  array(9) {
    ["PKTABLE_NAME"]=>
    string(5) "event"
    ["PKCOLUMN_NAME"]=>
    string(4) "code"
    ["FKTABLE_NAME"]=>
    string(4) "game"
    ["FKCOLUMN_NAME"]=>
    string(10) "event_code"
    ["KEY_SEQ"]=>
    string(1) "1"
    ["UPDATE_RULE"]=>
    string(1) "1"
    ["DELETE_RULE"]=>
    string(1) "1"
    ["FK_NAME"]=>
    string(18) "fk_game_event_code"
    ["PK_NAME"]=>
    string(13) "pk_event_code"
  }
}

--- Column Attribute ---
array(1) {
  [0]=>
  array(13) {
    ["ATTR_NAME"]=>
    string(4) "area"
    ["DOMAIN"]=>
    string(1) "7"
    ["SCALE"]=>
    string(1) "2"
    ["PRECISION"]=>
    string(2) "10"
    ["INDEXED"]=>
    string(1) "0"
    ["NON_NULL"]=>
    string(1) "0"
    ["SHARED"]=>
    string(1) "0"
    ["UNIQUE"]=>
    string(1) "0"
    ["DEFAULT"]=>
    NULL
    ["ATTR_ORDER"]=>
    string(1) "4"
    ["CLASS_NAME"]=>
    string(7) "stadium"
    ["SOURCE_CLASS"]=>
    string(7) "stadium"
    ["IS_KEY"]=>
    string(1) "0"
  }
}


Delete an element from sequence type column using OID

  • ≪ cubrid_schema
  • cubrid_seq_insert ≫
  • PHP Manual
  • CUBRID 関数
  • Delete an element from sequence type column using OID

cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Delete an element from sequence type column using OID

説明

cubrid_seq_drop(
resource $conn_identifier,
string $oid,
string $attr_name,
int $index
): bool

The cubrid_seq_drop() function is used to delete an element you request from the given sequence type attribute in the database.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute that you want to delete an element from.

index

Index of the element that you want to delete (1-based).

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_seq_drop() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);

cubrid_seq_drop($conn, $oid, "c", 4);

$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(2) "11"
  [1]=>
  string(2) "22"
  [2]=>
  string(2) "33"
  [3]=>
  string(3) "333"
}
array(3) {
  [0]=>
  string(2) "11"
  [1]=>
  string(2) "22"
  [2]=>
  string(2) "33"
}

参考

  • cubrid_seq_insert() - Insert an element to a sequence type column using OID
  • cubrid_seq_put() - Update the element value of sequence type column using OID


Insert an element to a sequence type column using OID

  • ≪ cubrid_seq_drop
  • cubrid_seq_put ≫
  • PHP Manual
  • CUBRID 関数
  • Insert an element to a sequence type column using OID

cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Insert an element to a sequence type column using OID

説明

cubrid_seq_insert(
resource $conn_identifier,
string $oid,
string $attr_name,
int $index,
string $seq_element
): bool

The cubrid_col_insert() function is used to insert an element to a sequence type attribute in a requested location.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute you want to insert an instance to.

index

Location of the element, you want to insert the element to (1-based).

seq_element

Content of the element that you want to insert.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_seq_insert() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);

cubrid_seq_insert($conn, $oid, "c", 5, "44");

$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(2) "11"
  [1]=>
  string(2) "22"
  [2]=>
  string(2) "33"
  [3]=>
  string(3) "333"
}
array(5) {
  [0]=>
  string(2) "11"
  [1]=>
  string(2) "22"
  [2]=>
  string(2) "33"
  [3]=>
  string(3) "333"
  [4]=>
  string(2) "44"
}

参考

  • cubrid_seq_drop() - Delete an element from sequence type column using OID
  • cubrid_seq_put() - Update the element value of sequence type column using OID


Update the element value of sequence type column using OID

  • ≪ cubrid_seq_insert
  • cubrid_set_add ≫
  • PHP Manual
  • CUBRID 関数
  • Update the element value of sequence type column using OID

cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Update the element value of sequence type column using OID

説明

cubrid_seq_put(
resource $conn_identifier,
string $oid,
string $attr_name,
int $index,
string $seq_element
): bool

The cubrid_seq_put() function is used to update the content of the requested element in a sequent type attribute using OID.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute that you want to update an element.

index

Index (1-based) of the element that you want to update.

seq_element

New content that you want to use for the update.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_seq_put() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);

cubrid_seq_put($conn, $oid, "c", 1, "111");

$attr = cubrid_col_get($conn, $oid, "c");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(2) "11"
  [1]=>
  string(2) "22"
  [2]=>
  string(2) "33"
  [3]=>
  string(3) "333"
}
array(4) {
  [0]=>
  string(3) "111"
  [1]=>
  string(2) "22"
  [2]=>
  string(2) "33"
  [3]=>
  string(3) "333"
}

参考

  • cubrid_seq_drop() - Delete an element from sequence type column using OID
  • cubrid_seq_insert() - Insert an element to a sequence type column using OID


Insert a single element to set type column using OID

  • ≪ cubrid_seq_put
  • cubrid_set_autocommit ≫
  • PHP Manual
  • CUBRID 関数
  • Insert a single element to set type column using OID

cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insert a single element to set type column using OID

説明

cubrid_set_add(
resource $conn_identifier,
string $oid,
string $attr_name,
string $set_element
): bool

The cubrid_set_add() function is used to insert a single element to a set type attribute (set, multiset, sequence) you requested.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute you want to insert an element.

set_element

Content of the element you want to insert.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_set_add() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_set_add($conn, $oid, "b", "4");

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
array(4) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
  [3]=>
  string(1) "4"
}

参考

  • cubrid_seq_drop() - Delete an element from sequence type column using OID


Set autocommit mode of the connection

  • ≪ cubrid_set_add
  • cubrid_set_db_parameter ≫
  • PHP Manual
  • CUBRID 関数
  • Set autocommit mode of the connection

cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Set autocommit mode of the connection

説明

cubrid_set_autocommit(resource $conn_identifier, bool $mode): bool

The cubrid_set_autocommit() function is used to set the CUBRID database auto-commit mode of the current database connection.

In CUBRID PHP, auto-commit mode is disabled by default for transaction management. When auto-commit mode is truned from off to on, any pending work is automatically committed.

パラメータ

conn_identifier

Connection identifier.

mode

Auto-commit mode. The following constants can be used:

  • CUBRID_AUTOCOMMIT_FALSE
  • CUBRID_AUTOCOMMIT_TRUE

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • cubrid_get_autocommit() - Get auto-commit mode of the connection
  • cubrid_commit() - Commit a transaction


Sets the CUBRID database parameters

  • ≪ cubrid_set_autocommit
  • cubrid_set_drop ≫
  • PHP Manual
  • CUBRID 関数
  • Sets the CUBRID database parameters

cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Sets the CUBRID database parameters

説明

cubrid_set_db_parameter(resource $conn_identifier, int $param_type, int $param_value): bool

The cubrid_set_db_parameter() function is used to set the CUBRID database parameters. It can set the following CUBRID database parameters:

  • PARAM_ISOLATION_LEVEL
  • PARAM_LOCK_TIMEOUT

注意:

The auto-commit mode can be set by using cubrid_set_autocommit().

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

param_type

Database parameter type.

param_value

Isolation level value (1-6) or lock timeout (in seconds) value.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_get_db_parameter() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$params = cubrid_get_db_parameter($conn);
var_dump($params);

cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);

$params_new = cubrid_get_db_parameter($conn);
var_dump($params_new);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  ["PARAM_ISOLATION_LEVEL"]=>
  int(3)
  ["PARAM_LOCK_TIMEOUT"]=>
  int(-1)
  ["PARAM_MAX_STRING_LENGTH"]=>
  int(1073741823)
  ["PARAM_AUTO_COMMIT"]=>
  int(0)
}
array(4) {
  ["PARAM_ISOLATION_LEVEL"]=>
  int(2)
  ["PARAM_LOCK_TIMEOUT"]=>
  int(-1)
  ["PARAM_MAX_STRING_LENGTH"]=>
  int(1073741823)
  ["PARAM_AUTO_COMMIT"]=>
  int(1)
}

参考

  • cubrid_get_db_parameter() - Returns the CUBRID database parameters
  • cubrid_set_autocommit() - Set autocommit mode of the connection


Delete an element from set type column using OID

  • ≪ cubrid_set_db_parameter
  • cubrid_set_query_timeout ≫
  • PHP Manual
  • CUBRID 関数
  • Delete an element from set type column using OID

cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Delete an element from set type column using OID

説明

cubrid_set_drop(
resource $conn_identifier,
string $oid,
string $attr_name,
string $set_element
): bool

The cubrid_set_drop() function is used to delete an element that you request from the given set type (set, multiset) attribute of the database.

パラメータ

conn_identifier

Connection identifier.

oid

OID of the instance you want to work with.

attr_name

Name of the attribute you want to delete an element from.

set_element

Content of the element you want to delete.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 cubrid_set_drop() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

@cubrid_execute($conn, "DROP TABLE foo");
cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

$req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$oid = cubrid_current_oid($req);

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_set_drop($conn, $oid, "b", "1");

$attr = cubrid_col_get($conn, $oid, "b");
var_dump($attr);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(1) "1"
  [1]=>
  string(1) "2"
  [2]=>
  string(1) "3"
}
array(2) {
  [0]=>
  string(1) "2"
  [1]=>
  string(1) "3"
}

参考

  • cubrid_set_add() - Insert a single element to set type column using OID


Set the timeout time of query execution

  • ≪ cubrid_set_drop
  • cubrid_version ≫
  • PHP Manual
  • CUBRID 関数
  • Set the timeout time of query execution

cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Set the timeout time of query execution

説明

cubrid_set_query_timeout(resource $req_identifier, int $timeout): bool

The cubrid_set_query_timeout() function is used to set the timeout time of query execution.

パラメータ

req_identifier

Request identifier.

timeout

Timeout time in milliseconds.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • cubrid_get_query_timeout() - Get the query timeout value of the request


Get the CUBRID PHP module's version

  • ≪ cubrid_set_query_timeout
  • CUBRID MySQL 互換関数 ≫
  • PHP Manual
  • CUBRID 関数
  • Get the CUBRID PHP module's version

cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Get the CUBRID PHP module's version

説明

cubrid_version(): string

The cubrid_version() function is used to get the CUBRID PHP module's version.

パラメータ

この関数にはパラメータはありません。

戻り値

Version information (eg. "8.3.1.0001").

例

例1 cubrid_version() example

<?php
printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

printf("\n");

$conn = cubrid_connect("localhost", 33088, "demodb", "dba");

if (!$conn) {
die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
}

$db_params = cubrid_get_db_parameter($conn);

while (list($param_name, $param_value) = each($db_params)) {
printf("%-30s %s\n", $param_name, $param_value);
}

printf("\n");

$server_info = cubrid_get_server_info($conn);
$client_info = cubrid_get_client_info();

printf("%-30s %s\n", "Server Info:", $server_info);
printf("%-30s %s\n", "Client Info:", $client_info);

printf("\n");

$charset = cubrid_get_charset($conn);

printf("%-30s %s\n", "CUBRID Charset:", $charset);

cubrid_disconnect($conn);

?>

上の例の出力は以下となります。

CUBRID PHP Version:            9.1.0.0001

PARAM_ISOLATION_LEVEL          3
LOCK_TIMEOUT                   -1
MAX_STRING_LENGTH              1073741823
PARAM_AUTO_COMMIT              1

Server Info:                   9.1.0.0212
Client Info:                   9.1.0

CUBRID Charset:                iso8859-1

参考

  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_code_facility() - Get the facility code of error


CUBRID MySQL 互換関数

目次

  • cubrid_affected_rows — Return the number of rows affected by the last SQL statement
  • cubrid_client_encoding — Return the current CUBRID connection charset
  • cubrid_close — Close CUBRID connection
  • cubrid_data_seek — Move the internal row pointer of the CUBRID result
  • cubrid_db_name — Get db name from results of cubrid_list_dbs
  • cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
  • cubrid_error — Get the error message
  • cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
  • cubrid_fetch_field — Get column information from a result and return as an object
  • cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
  • cubrid_fetch_object — Fetch the next row and return it as an object
  • cubrid_fetch_row — Return a numerical array with the values of the current row
  • cubrid_field_flags — Return a string with the flags of the given field offset
  • cubrid_field_len — Get the maximum length of the specified field
  • cubrid_field_name — Return the name of the specified field index
  • cubrid_field_seek — Move the result set cursor to the specified field offset
  • cubrid_field_table — Return the name of the table of the specified field
  • cubrid_field_type — Return the type of the column corresponding to the given field offset
  • cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
  • cubrid_num_fields — Return the number of columns in the result set
  • cubrid_ping — Ping a server connection or reconnect if there is no connection
  • cubrid_query — Send a CUBRID query
  • cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
  • cubrid_result — Return the value of a specific field in a specific row
  • cubrid_unbuffered_query — Perform a query without fetching the results into memory


Return the number of rows affected by the last SQL statement

  • ≪ CUBRID MySQL 互換関数
  • cubrid_client_encoding ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the number of rows affected by the last SQL statement

cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Return the number of rows affected by the last SQL statement

説明

cubrid_affected_rows(resource $conn_identifier = ?): int
cubrid_affected_rows(resource $req_identifier = ?): int

The cubrid_affected_rows() function is used to get the number of rows affected by the SQL statement (INSERT, DELETE, UPDATE).

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opend by cubrid_connect() is assumed.

req_identifier

Request Identifier, could be returned from either cubrid_prepare() or cubrid_execute(). If the request identifier is not specified, the last identifier requested by cubrid_prepare() or cubrid_execute() is assumed.

戻り値

Number of rows affected by the SQL statement, when process is successful.

-1, when SQL statement is not INSERT, DELETE or UPDATE.

false, when the request identifier is not specified, and there is no last request.

例

例1 cubrid_affected_rows() example

<?php
$conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
$sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
$req = cubrid_prepare($conn, $sql_stmt);

for ($i = 0; $i < 10; $i++) {
cubrid_execute($req);
}
cubrid_commit($conn);

$req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
var_dump(cubrid_affected_rows());
var_dump(cubrid_affected_rows($conn));
var_dump(cubrid_affected_rows($req));

cubrid_disconnect($conn);

print "done!";
?>

上の例の出力は以下となります。

Rows deleted: 5

参考

  • cubrid_execute() - Execute a prepared SQL statement


Return the current CUBRID connection charset

  • ≪ cubrid_affected_rows
  • cubrid_close ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the current CUBRID connection charset

cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Return the current CUBRID connection charset

説明

cubrid_client_encoding(resource $conn_identifier = ?): string

This function returns the current CUBRID connection charset and is similar to the CUBRID function cubrid_get_charset().

パラメータ

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

戻り値

A string that represents the CUBRID connection charset; on success.

false on failure.

例

例1 cubrid_client_encoding() example

<?php

$con = cubrid_connect("localhost", 33000, "demodb");
if (!$con)
{
die('Could not connect.');
}

printf("CUBRID current charset: %s\n", cubrid_client_encoding($con));

?>

上の例の出力は以下となります。

CUBRID current charset: iso8859-1

参考

  • cubrid_get_charset() - Return the current CUBRID connection charset


Close CUBRID connection

  • ≪ cubrid_client_encoding
  • cubrid_data_seek ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Close CUBRID connection

cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Close CUBRID connection

説明

cubrid_close(resource $conn_identifier = ?): bool

The cubrid_close() function ends the transaction currently in process, closes the connection handle and disconnects from server. If there is any request handles not closed yet at this point, they will be closed. It is similar to the CUBRID function cubrid_disconnect().

パラメータ

conn_identifier

The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

戻り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_close() example

<?php
$con = cubrid_connect ("localhost", 33000, "demodb");
if ($con) {
echo "connected successfully";
$req = cubrid_execute ( $con, "insert into person values(1,'James')");
if ($req) {
cubrid_close_request ($req);
cubrid_commit ($con);
} else {
cubrid_rollback ($con);
}
cubrid_close ($con);
}
?>

参考

  • cubrid_disconnect() - Close a database connection
  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server


Move the internal row pointer of the CUBRID result

  • ≪ cubrid_close
  • cubrid_db_name ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Move the internal row pointer of the CUBRID result

cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Move the internal row pointer of the CUBRID result

説明

cubrid_data_seek(resource $result, int $row_number): bool

This function performs the moving of the internal row pointer of the CUBRID result (associated with the specified result identifier) to point to a specific row number. There are functions, such as cubrid_fetch_assoc(), which use the current stored value of row number.

パラメータ

result

The result.

row_number

This is the desired row number of the new result pointer.

戻り値

Returns true on success or false on failure.

例

例1 cubrid_data_seek() example

<?php
$conn = cubrid_connect("127.0.0.1", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM code");
cubrid_data_seek($req, 0);

$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_data_seek($req, 2);
$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_data_seek($req, 4);
$result = cubrid_fetch_row($req);
var_dump($result);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  string(1) "X"
  [1]=>
  string(5) "Mixed"
}
array(2) {
  [0]=>
  string(1) "M"
  [1]=>
  string(3) "Man"
}
array(2) {
  [0]=>
  string(1) "S"
  [1]=>
  string(6) "Silver"
}


Get db name from results of cubrid_list_dbs

  • ≪ cubrid_data_seek
  • cubrid_errno ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get db name from results of cubrid_list_dbs

cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Get db name from results of cubrid_list_dbs

説明

cubrid_db_name(array $result, int $index): string

Retrieve the database name from a call to cubrid_list_dbs().

パラメータ

result

The result pointer from a call to cubrid_list_dbs().

index

The index into the result set.

戻り値

Returns the database name on success, and false on failure. If false is returned, use cubrid_error() to determine the nature of the error.

例

例1 cubrid_db_name() example

<?php
error_reporting(E_ALL);

$conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$db_list = cubrid_list_dbs($conn);

$i = 0;
$cnt = count($db_list);
while ($i < $cnt) {
echo cubrid_db_name($db_list, $i) . "\n";
$i++;
}
?>

上の例の出力は以下となります。

demodb

参考

  • cubrid_list_dbs() - Return an array with the list of all existing CUBRID databases


Return the numerical value of the error message from previous CUBRID operation

  • ≪ cubrid_db_name
  • cubrid_error ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the numerical value of the error message from previous CUBRID operation

cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Return the numerical value of the error message from previous CUBRID operation

説明

cubrid_errno(resource $conn_identifier = ?): int

Returns the error number from the last CUBRID function.

The cubrid_errno() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.

パラメータ

conn_identifier

The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

戻り値

Returns the error number from the last CUBRID function, or 0 (zero) if no error occurred.

例

例1 cubrid_errno() example

<?php
$con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$req = cubrid_execute($con, "select id, name from person");
if ($req) {
while (list ($id, $name) = cubrid_fetch($req))
echo $id, $name;
} else {
echo "Error Code: ", cubrid_errno($con);
echo "Error Message: ", cubrid_error($con);
}
?>

上の例の出力は以下となります。

Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

参考

  • cubrid_error() - Get the error message
  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_msg() - Get last error message for the most recent function call


Get the error message

  • ≪ cubrid_errno
  • cubrid_fetch_array ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get the error message

cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Get the error message

説明

cubrid_error(resource $connection = ?): string

The cubrid_error() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.

パラメータ

connection

The CUBRID connection.

戻り値

Error message that occurred.

例

例1 cubrid_error() example

<?php
$con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$req = cubrid_execute($con, "select id, name from person");
if ($req) {
while (list ($id, $name) = cubrid_fetch($req))
echo $id, $name;
} else {
echo "Error Code: ", cubrid_errno($con);
echo "Error Message: ", cubrid_error($con);
}
?>

上の例の出力は以下となります。

Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

参考

  • cubrid_errno() - Return the numerical value of the error message from previous CUBRID operation
  • cubrid_error_code() - Get error code for the most recent function call
  • cubrid_error_msg() - Get last error message for the most recent function call


Fetch a result row as an associative array, a numeric array, or both

  • ≪ cubrid_error
  • cubrid_fetch_assoc ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Fetch a result row as an associative array, a numeric array, or both

cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both

説明

cubrid_fetch_array(resource $result, int $type = CUBRID_BOTH): array

The cubrid_fetch_array() function is used to get a single row from the query result and returns an array. The cursor automatically moves to the next row after getting the result.

パラメータ

result

Result comes from a call to cubrid_execute()

type

Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. If you need to operate the lob object, you can use CUBRID_LOB.

戻り値

Returns an array of strings that corresponds to the fetched row, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

The type of returned array depends on how type is defined. By using CUBRID_BOTH (default), you'll get an array with both associative and number indices, and you can decide which data type to use by setting the type argument. The type variable can be set to one of the following values:

  • CUBRID_NUM : Numerical array (0-based)
  • CUBRID_ASSOC : Associative array
  • CUBRID_BOTH : Numerical & Associative array (default)

例

例1 cubrid_fetch_array() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
}

// if you want to operate LOB object, you can use cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_row() - Return a numerical array with the values of the current row
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_object() - Fetch the next row and return it as an object


Return the associative array that corresponds to the fetched row

  • ≪ cubrid_fetch_array
  • cubrid_fetch_field ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the associative array that corresponds to the fetched row

cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row

説明

cubrid_fetch_assoc(resource $result, int $type = ?): array

This function returns the associative array, that corresponds to the fetched row, and then moves the internal data pointer ahead, or returns FALSE when the end is reached.

パラメータ

result

result comes from a call to cubrid_execute()

type

Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

戻り値

Associative array, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

例

例1 cubrid_fetch_assoc() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_assoc($req)) {
printf("%-40s %-10s %-6s %-20s\n",
$row["name"], $row["area"], $row["seats"], $row["address"]);
}

// if you want to operate LOB object, you can use cubrid_fetch_assoc($req, CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_row() - Return a numerical array with the values of the current row
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_object() - Fetch the next row and return it as an object


Get column information from a result and return as an object

  • ≪ cubrid_fetch_assoc
  • cubrid_fetch_lengths ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get column information from a result and return as an object

cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Get column information from a result and return as an object

説明

cubrid_fetch_field(resource $result, int $field_offset = 0): object

This function returns an object with certain properties of the specific column. The properties of the object are:

name

column name

table

name of the table that the column belongs to

def

default value of the column

max_length

maximum length of the column

not_null

1 if the column cannot be NULL

primary_key

1 if the column is a primary key

unique_key

1 if the column is an unique key

multiple_key

1 if the column is a non-unique key

numeric

1 if the column is numeric

blob

1 if the column is a BLOB

type

the type of the column

unsigned

1 if the column is unsigned

zerofill

1 if the column is zero-filled

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. If the field offset is not specified, the next field (that was not yet retrieved by this function) is retrieved. The field_offset starts at 0.

戻り値

Object with certain properties of the specific column, when process is successful.

false on failure.

例

例1 cubrid_fetch_field() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

var_dump(cubrid_fetch_row($req));

cubrid_field_seek($req, 1);
$field = cubrid_fetch_field($req);

printf("\n--- Field Properties ---\n");
printf("%-30s %s\n", "name:", $field->name);
printf("%-30s %s\n", "table:", $field->table);
printf("%-30s \"%s\"\n", "default value:", $field->def);
printf("%-30s %d\n", "max length:", $field->max_length);
printf("%-30s %d\n", "not null:", $field->not_null);
printf("%-30s %d\n", "primary key:", $field->primary_key);
printf("%-30s %d\n", "unique key:", $field->unique_key);
printf("%-30s %d\n", "multiple key:", $field->multiple_key);
printf("%-30s %d\n", "numeric:", $field->numeric);
printf("%-30s %d\n", "blob:", $field->blob);
printf("%-30s %s\n", "type:", $field->type);
printf("%-30s %d\n", "unsigned:", $field->unsigned);
printf("%-30s %d\n", "zerofill:", $field->zerofill);

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(5) "20001"
  [1]=>
  string(5) "16681"
  [2]=>
  string(3) "KOR"
  [3]=>
  string(9) "1988-9-30"
}

--- Field Properties ---
name:                          athlete_code
table:                         game
default value:                 ""
max length:                    0
not null:                      1
primary key:                   1
unique key:                    1
multiple key:                  0
numeric:                       1
blob:                          0
type:                          integer
unsigned:                      0
zerofill:                      0


Return an array with the lengths of the values of each field from the current row

  • ≪ cubrid_fetch_field
  • cubrid_fetch_object ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return an array with the lengths of the values of each field from the current row

cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row

説明

cubrid_fetch_lengths(resource $result): array

This function returns a numeric array with the lengths of the values of each field from the current row of the result set or it returns FALSE on failure.

注意:

If field data type is BLOB/CLOB, you should get its length by using cubrid_lob_size().

パラメータ

result

result comes from a call to cubrid_execute()

戻り値

A numeric array, when process is successful.

false on failure.

例

例1 cubrid_fetch_lengths() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$row = cubrid_fetch_row($result);
print_r($row);

$lens = cubrid_fetch_lengths($result);
print_r($lens);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Array
(
    [0] => 2004
    [1] => 20085
    [2] => 15118
    [3] => 30134
    [4] => AUS
    [5] => G
    [6] => 2004-8-20
)
Array
(
    [0] => 4
    [1] => 5
    [2] => 5
    [3] => 5
    [4] => 3
    [5] => 1
    [6] => 10
)


Fetch the next row and return it as an object

  • ≪ cubrid_fetch_lengths
  • cubrid_fetch_row ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Fetch the next row and return it as an object

cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Fetch the next row and return it as an object

説明

cubrid_fetch_object(
resource $result,
string $class_name = ?,
array $params = ?,
int $type = ?
): object

This function returns an object with the column names of the result set as properties. The values of these properties are extracted from the current row of the result.

パラメータ

result

result comes from a call to cubrid_execute()

class_name

The name of the class to instantiate. If not specified, a stdClass (stdClass is PHP's generic empty class that's used when casting other types to objects) object is returned.

params

An optional array of parameters to pass to the constructor for class_name objects.

type

Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

戻り値

An object, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

例

例1 cubrid_fetch_object() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$res = cubrid_execute($conn, "SELECT * FROM code");

var_dump(cubrid_fetch_object($res));

// if you want to operate LOB object, you can use cubrid_fetch_object($res, CUBRID_LOB)

class demodb_code {
public $s_name = null;
public $f_name = null;

public function toString() {
var_dump($this);
}
}

var_dump(cubrid_fetch_object($res, "demodb_code"));

// if you want to operate LOB object, you can use cubrid_fetch_object($res, "demodb_code", CUBRID_LOB)

class demodb_code_construct extends demodb_code {
public function __construct($s, $f) {
$this->s_name = $s;
$this->f_name = $f;
}
}

var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

// if you want to operate LOB object, you can use cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

var_dump(cubrid_fetch_object($res));

cubrid_close_request($res);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

object(stdClass)#1 (2) {
  ["s_name"]=>
  string(1) "X"
  ["f_name"]=>
  string(5) "Mixed"
}
object(demodb_code)#1 (2) {
  ["s_name"]=>
  string(1) "W"
  ["f_name"]=>
  string(5) "Woman"
}
object(demodb_code_construct)#1 (2) {
  ["s_name"]=>
  string(6) "s_name"
  ["f_name"]=>
  string(6) "f_name"
}
object(stdClass)#1 (2) {
  ["s_name"]=>
  string(1) "B"
  ["f_name"]=>
  string(6) "Bronze"
}

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_row() - Return a numerical array with the values of the current row


Return a numerical array with the values of the current row

  • ≪ cubrid_fetch_object
  • cubrid_field_flags ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return a numerical array with the values of the current row

cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Return a numerical array with the values of the current row

説明

cubrid_fetch_row(resource $result, int $type = ?): array

This function returns a numerical array with the values of the current row from the result set, starting from 0, and moves the internal data pointer ahead.

パラメータ

result

result comes from a call to cubrid_execute()

type

Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

戻り値

A numerical array, when process is successful.

false, when there are no more rows; NULL, when process is unsuccessful.

例

例1 cubrid_fetch_row() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
while ($row = cubrid_fetch_row($req)) {
printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
}

// if you want to operate LOB object, you can use cubrid_fetch_row($req, CUBRID_LOB)

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

name                                     area       seats  address
Panathinaiko Stadium                     86300.00   50000  Athens, Greece
Olympic Stadium                          54700.00   13000  Athens, Greece
Olympic Indoor Hall                      34100.00   18800  Athens, Greece
Olympic Hall                             52400.00   21000  Athens, Greece
Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

参考

  • cubrid_execute() - Execute a prepared SQL statement
  • cubrid_fetch() - Fetch the next row from a result set
  • cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_fetch_object() - Fetch the next row and return it as an object


Return a string with the flags of the given field offset

  • ≪ cubrid_fetch_row
  • cubrid_field_len ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return a string with the flags of the given field offset

cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Return a string with the flags of the given field offset

説明

cubrid_field_flags(resource $result, int $field_offset): string

This function returns a string with the flags of the given field offset separated by space. You can split the returned value using explode. The possible flags could be: not_null, primary_key, unique_key, foreign_key, auto_increment, shared, reverse_index, reverse_unique and timestamp.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

戻り値

A string with flags, when process is successful.

false when invalid field_offset value.

-1 if SQL sentence is not SELECT.

例

例1 cubrid_field_flags() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$col_num = cubrid_num_cols($result);

printf("%-30s %s\n", "Field Name", "Field Flags");
for($i = 0; $i < $col_num; $i++) {
printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Name                     Field Flags
host_year                      not_null primary_key unique_key
event_code                     not_null primary_key unique_key foreign_key
athlete_code                   not_null primary_key unique_key foreign_key
stadium_code                   not_null
nation_code
medal
game_date


Get the maximum length of the specified field

  • ≪ cubrid_field_flags
  • cubrid_field_name ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Get the maximum length of the specified field

cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Get the maximum length of the specified field

説明

cubrid_field_len(resource $result, int $field_offset): int

This function returns the maximum length of the specified field on success, or it returns FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

戻り値

Maximum length, when process is successful.

false on failure.

例

例1 cubrid_field_len() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$column_names = cubrid_column_names($result);
$column_types = cubrid_column_types($result);

printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
for($i = 0, $size = count($column_names); $i < $size; $i++) {
$column_len = cubrid_field_len($result, $i);
printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Column Names                   Column Types                   Column Maxlen
host_year                      integer                        11
event_code                     integer                        11
athlete_code                   integer                        11
stadium_code                   integer                        11
nation_code                    char                           3
medal                          char                           1
game_date                      date                           10


Return the name of the specified field index

  • ≪ cubrid_field_len
  • cubrid_field_seek ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the name of the specified field index

cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Return the name of the specified field index

説明

cubrid_field_name(resource $result, int $field_offset): string

This function returns the name of the specified field index on success or it returns FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

戻り値

Name of specified field index, on success.

false on failure.

例

例1 cubrid_field_name() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

$col_num = cubrid_num_cols($result);

printf("%-30s %s\n", "Field Name", "Field Flags");
for($i = 0; $i < $col_num; $i++) {
printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Name                     Field Flags
host_year                      not_null primary_key unique_key
event_code                     not_null primary_key unique_key foreign_key
athlete_code                   not_null primary_key unique_key foreign_key
stadium_code                   not_null
nation_code
medal
game_date


Move the result set cursor to the specified field offset

  • ≪ cubrid_field_name
  • cubrid_field_table ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Move the result set cursor to the specified field offset

cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Move the result set cursor to the specified field offset

説明

cubrid_field_seek(resource $result, int $field_offset = 0): bool

This function moves the result set cursor to the specified field offset. This offset is used by cubrid_fetch_field() if it doesn't include a field offset. It returns TRUE on success or FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

戻り値

true on success.

false on failure.

例

例1 cubrid_field_seek() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

var_dump(cubrid_fetch_row($req));

cubrid_field_seek($req, 1);
$field = cubrid_fetch_field($req);

printf("\n--- Field Properties ---\n");
printf("%-30s %s\n", "name:", $field->name);
printf("%-30s %s\n", "table:", $field->table);
printf("%-30s \"%s\"\n", "default value:", $field->def);
printf("%-30s %d\n", "max length:", $field->max_length);
printf("%-30s %d\n", "not null:", $field->not_null);
printf("%-30s %d\n", "unique key:", $field->unique_key);
printf("%-30s %d\n", "multiple key:", $field->multiple_key);
printf("%-30s %d\n", "numeric:", $field->numeric);
printf("%-30s %s\n", "type:", $field->type);

cubrid_close_request($req);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(5) "20001"
  [1]=>
  string(5) "16132"
  [2]=>
  string(3) "KOR"
  [3]=>
  string(9) "1988-09-30"
}

--- Field Properties ---
name:                          athlete_code
table:                         game
default value:                 ""
max length:                    0
not null:                      1
unique key:                    1
multiple key:                  0
numeric:                       1
type:                          integer


Return the name of the table of the specified field

  • ≪ cubrid_field_seek
  • cubrid_field_type ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the name of the table of the specified field

cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Return the name of the table of the specified field

説明

cubrid_field_table(resource $result, int $field_offset): string

This function returns the name of the table of the specified field. This is useful when using large select queries with JOINS.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

戻り値

Name of the table of the specified field, on success.

false when invalid field_offset value.

-1 if SQL sentence is not SELECT.

例

例1 cubrid_field_table() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM code");

$col_num = cubrid_num_cols($result);

printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
for($i = 0; $i < $col_num; $i++) {
printf("%-15s %-15s %s\n",
cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Table     Field Name      Field Type
code            s_name          char
code            f_name          varchar


Return the type of the column corresponding to the given field offset

  • ≪ cubrid_field_table
  • cubrid_list_dbs ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the type of the column corresponding to the given field offset

cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Return the type of the column corresponding to the given field offset

説明

cubrid_field_type(resource $result, int $field_offset): string

This function returns the type of the column corresponding to the given field offset. The returned field type could be one of the following: "int", "real", "string", etc.

パラメータ

result

result comes from a call to cubrid_execute()

field_offset

The numerical field offset. The field_offset starts at 0. If field_offset does not exist, an error of level E_WARNING is also issued.

戻り値

Type of the column, on success.

false when invalid field_offset value.

-1 if SQL sentence is not SELECT.

例

例1 cubrid_field_type() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");
$result = cubrid_execute($conn, "SELECT * FROM code");

$col_num = cubrid_num_cols($result);

printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
for($i = 0; $i < $col_num; $i++) {
printf("%-15s %-15s %s\n",
cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
}

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Field Table     Field Name      Field Type
code            s_name          char
code            f_name          varchar


Return an array with the list of all existing CUBRID databases

  • ≪ cubrid_field_type
  • cubrid_num_fields ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return an array with the list of all existing CUBRID databases

cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Return an array with the list of all existing CUBRID databases

説明

cubrid_list_dbs(resource $conn_identifier = ?): array

This function returns an array with the list of all existing Cubrid databases.

パラメータ

conn_identifier

The CUBRID connection.

戻り値

An numeric array with all existing Cubrid databases; on success.

false on failure.

例

例1 cubrid_list_dbs() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$db_list = cubrid_list_dbs($conn);
var_dump($db_list);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(6) "demodb"
}


Return the number of columns in the result set

  • ≪ cubrid_list_dbs
  • cubrid_ping ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the number of columns in the result set

cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Return the number of columns in the result set

説明

cubrid_num_fields(resource $result): int

This function returns the number of columns in the result set, on success, or it returns FALSE on failure.

パラメータ

result

result comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

戻り値

Number of columns, on success.

-1 if SQL sentence is not SELECT.

false when process is unsuccessful.

例

例1 cubrid_num_fields() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM code");

$row_num = cubrid_num_rows($req);
$col_num = cubrid_num_fields($req);

printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

Row Num: 6
Column Num: 2


Ping a server connection or reconnect if there is no connection

  • ≪ cubrid_num_fields
  • cubrid_query ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Ping a server connection or reconnect if there is no connection

cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Ping a server connection or reconnect if there is no connection

説明

cubrid_ping(resource $conn_identifier = ?): bool

Checks whether or not the connection to the server is working.

パラメータ

conn_identifier

The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

戻り値

Returns true if the connection to the server CUBRID server is working, otherwise false.

例

例1 cubrid_ping() example

<?php
set_time_limit(0);

$conn = cubrid_connect('localhost', 33000, 'demodb');

/* Assuming this query will take a long time */
$sql = "select * from athlete";
$result = cubrid_query($sql);
if (!$result) {
echo 'Query #1 failed, exiting.';
exit;
}

/* Make sure the connection is still alive, if not, try to reconnect */
if (!cubrid_ping($conn)) {
echo 'Lost connection, exiting after query #1';
exit;
}
cubrid_free_result($result);

/* So the connection is still alive, let's run another query */
$sql2 = "select * from code";
$result2 = cubrid_query($sql2);
?>


Send a CUBRID query

  • ≪ cubrid_ping
  • cubrid_real_escape_string ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Send a CUBRID query

cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Send a CUBRID query

説明

cubrid_query(string $query, resource $conn_identifier = ?): resource

cubrid_query() sends a unique query (multiple queries are not supported) to the currently active database on the server that's associated with the specified conn_identifier.

パラメータ

query

An SQL query

Data inside the query should be properly escaped.

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

戻り値

For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset, cubrid_query() returns a resource on success, or false on error.

For other type of SQL statements, INSERT, UPDATE, DELETE, DROP, etc, cubrid_query() returns true on success or false on error.

The returned result resource should be passed to cubrid_fetch_array(), and other functions for dealing with result tables, to access the returned data.

Use cubrid_num_rows() to find out how many rows were returned for a SELECT statement or cubrid_affected_rows() to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.

cubrid_query() will also fail and return false if the user does not have permission to access the table(s) referenced by the query.

例

例1 Invalid Query

The following query is syntactically invalid, so cubrid_query() fails and returns false.

<?php
$conn = cubrid_connect('localhost', 33000, 'demodb');

$result = cubrid_query('SELECT * WHERE 1=1');
if (!$result) {
die('Invalid query: ' . cubrid_error());
}

?>

例2 Valid Query

The following query is valid, so cubrid_query() returns a resource.

<?php
// This could be supplied by a user, for example
$firstname = 'fred';
$lastname = 'fox';

$conn = cubrid_connect('localhost', 33000, 'demodb');

cubrid_execute($conn,"DROP TABLE if exists friends");
cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");
// Formulate Query
// This is the best way to perform an SQL query
// For more examples, see cubrid_real_escape_string()
$query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
cubrid_real_escape_string($firstname),
cubrid_real_escape_string($lastname));

// Perform Query
$result = cubrid_query($query);

// Check result
// This shows the actual query sent to CUBRID, and the error. Useful for debugging.
if (!$result) {
$message = 'Invalid query: ' . cubrid_error() . "\n";
$message .= 'Whole query: ' . $query;
die($message);
}

// Use result
// Attempting to print $result won't allow access to information in the resource
// One of the cubrid result functions must be used
// See also cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
while ($row = cubrid_fetch_assoc($result)) {
echo $row['firstname'];
echo $row['lastname'];
echo $row['address'];
echo $row['age'];
}

// Free the resources associated with the result set
// This is done automatically at the end of the script
cubrid_free_result($result);
?>

参考

  • cubrid_connect() - Open a connection to a CUBRID Server
  • cubrid_error() - Get the error message
  • cubrid_real_escape_string() - Escape special characters in a string for use in an SQL statement
  • cubrid_result() - Return the value of a specific field in a specific row
  • cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
  • cubrid_unbuffered_query() - Perform a query without fetching the results into memory


Escape special characters in a string for use in an SQL statement

  • ≪ cubrid_query
  • cubrid_result ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Escape special characters in a string for use in an SQL statement

cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement

説明

cubrid_real_escape_string(string $unescaped_string, resource $conn_identifier = ?): string

This function returns the escaped string version of the given string. It will escape the following characters: '. In general, single quotations are used to enclose character string. Double quotations may be used as well depending on the value of ansi_quotes, which is a parameter related to SQL statement. If the ansi_quotes value is set to no, character string enclosed by double quotations is handled as character string, not as an identifier. The default value is yes. If you want to include a single quote as part of a character string, enter two single quotes in a row.

パラメータ

unescaped_string

The string that is to be escaped.

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

戻り値

Escaped string version of the given string, on success.

false on failure.

例

例1 cubrid_real_escape_string() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
$escaped_str = cubrid_real_escape_string($unescaped_str);

$len = strlen($unescaped_str);

@cubrid_execute($conn, "DROP TABLE cubrid_test");
cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

$req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
$row = cubrid_fetch_assoc($req);

var_dump($row);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

array(1) {
  ["t"]=>
  string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
}


Return the value of a specific field in a specific row

  • ≪ cubrid_real_escape_string
  • cubrid_unbuffered_query ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Return the value of a specific field in a specific row

cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Return the value of a specific field in a specific row

説明

cubrid_result(resource $result, int $row, mixed $field = 0): string

This function returns the value of a specific field in a specific row from a result set.

パラメータ

result

result comes from a call to cubrid_execute()

row

The row number from the result that is being retrieved. Row numbers start at 0.

field

The name or offset of the field being retrieved. It can be the field's offset, the field's name, or the field's table dot field name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. If undefined, the first field is retrieved.

戻り値

Value of a specific field, on success (NULL if value if null).

false on failure.

例

例1 cubrid_result() example

<?php
$conn = cubrid_connect("localhost", 33000, "demodb");

$req = cubrid_execute($conn, "SELECT * FROM code");

$result = cubrid_result($req, 0);
var_dump($result);

$result = cubrid_result($req, 0, 1);
var_dump($result);

$result = cubrid_result($req, 5, "f_name");
var_dump($result);

cubrid_close_request($req);
cubrid_disconnect($conn);
?>

上の例の出力は以下となります。

string(1) "X"
string(5) "Mixed"
string(4) "Gold"


Perform a query without fetching the results into memory

  • ≪ cubrid_result
  • CUBRID 廃止されたエイリアスと関数 ≫
  • PHP Manual
  • CUBRID MySQL 互換関数
  • Perform a query without fetching the results into memory

cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Perform a query without fetching the results into memory

説明

cubrid_unbuffered_query(string $query, resource $conn_identifier = ?): resource

This function performs a query without waiting for that all query results have been complete. It will return when the results are being generated.

パラメータ

query

A SQL query.

conn_identifier

The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

戻り値

For SELECT, SHOW, DESCRIBE or EXPLAIN statements returns a request identifier resource on success.

For other type of SQL statements, UPDATE, DELETE, DROP, etc, returns true on success.

false on failure.

例

例1 cubrid_unbuffered_query() example

<?php
$link = cubrid_connect("localhost", 30000, "demodb", "dba", "");
if (!$link)
{
die('Could not connect.');
}
$query = "select * from code";
$result = cubrid_unbuffered_query($query, $link);

while ($row = cubrid_fetch($result))
{
var_dump($row);
}

cubrid_close_request($result);
cubrid_disconnect($link);
?>

注意

注意:

The benefits of cubrid_unbuffered_query() come at a cost: you cannot use cubrid_num_rows() and cubrid_data_seek() on a result set returned from cubrid_unbuffered_query().


CUBRID 廃止されたエイリアスと関数

目次

  • cubrid_load_from_glo — Read data from a GLO instance and save it in a file
  • cubrid_new_glo — Create a glo instance
  • cubrid_save_to_glo — Save requested file in a GLO instance
  • cubrid_send_glo — Read data from glo and send it to std output


Read data from a GLO instance and save it in a file

  • ≪ CUBRID 廃止されたエイリアスと関数
  • cubrid_new_glo ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Read data from a GLO instance and save it in a file

cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Read data from a GLO instance and save it in a file

説明

cubrid_load_from_glo(resource $conn_identifier, string $oid, string $file_name): int

The cubrid_load_from_glo() function is used to read a data from a glo instance, and saves it in a designated file.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the glo instance that you want to read the data from.

file_name

Name of the file where you want to save the data in.

戻り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_load_from_glo() example

<?php
$req = cubrid_execute ($con, "select image from person where id=1");
if ($req) {
list ($oid) = cubrid_fetch($req);
cubrid_close_request($req);
$res = cubrid_load_from_glo ($con, $oid, "output.jpg");
if ($res) {
echo "image changed successfully";
}
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_load_from_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_new_glo() - Create a glo instance
  • cubrid_save_to_glo() - Save requested file in a GLO instance
  • cubrid_send_glo() - Read data from glo and send it to std output


Create a glo instance

  • ≪ cubrid_load_from_glo
  • cubrid_save_to_glo ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Create a glo instance

cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Create a glo instance

説明

cubrid_new_glo(resource $conn_identifier, string $class_name, string $file_name): string

The cubrid_new_glo() function is used to create a glo instance in the requested class (glo class). The glo created is a LO type, and is stored in the file_name file.

パラメータ

conn_identifier

Connection identifier.

class_name

Name of the class that you want to create a glo in.

file_name

The file name that you want to save in the newly created glo.

戻り値

Oid of the instance created, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_new_glo() example

<?php
$oid = cubrid_new_glo ($con, "glo", "input.jpg");
if ($oid){
// the type of column "image" is "object"
$req = cubrid_execute ($con, "insert into person(image) values($oid)");
if ($req) {
echo "image inserted successfully";
cubrid_close_request ($req);
cubrid_commit($con);
}
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_new_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_save_to_glo() - Save requested file in a GLO instance
  • cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
  • cubrid_send_glo() - Read data from glo and send it to std output


Save requested file in a GLO instance

  • ≪ cubrid_new_glo
  • cubrid_send_glo ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Save requested file in a GLO instance

cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Save requested file in a GLO instance

説明

cubrid_save_to_glo(resource $conn_identifier, string $oid, string $file_name): int

The cubrid_save_to_glo() function is used to save requested file in a glo instance.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the glo instance that you want to save a file in.

file_name

The name of the file that you want to save.

戻り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_save_to_glo() example

<?php
$req = cubrid_execute ($con, "select image from person where id=1");
if ($req) {
list ($oid) = cubrid_fetch($req);
cubrid_close_request($req);
$res = cubrid_save_to_glo ($con, $oid, "input.jpg");
if ($res) {
echo "image changed successfully";
}
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_save_to_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_new_glo() - Create a glo instance
  • cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
  • cubrid_send_glo() - Read data from glo and send it to std output


Read data from glo and send it to std output

  • ≪ cubrid_save_to_glo
  • dBase ≫
  • PHP Manual
  • CUBRID 廃止されたエイリアスと関数
  • Read data from glo and send it to std output

cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Read data from glo and send it to std output

説明

cubrid_send_glo(resource $conn_identifier, string $oid): int

The cubrid_send_glo() function is used to read data from glo instance and sends it to the PHP standard output.

パラメータ

conn_identifier

Connection identifier.

oid

Oid of the glo instance that you want to read data from.

戻り値

true, when process is successful.

false, when process is unsuccessful.

例

例1 cubrid_send_glo() example

<?php
$req = cubrid_execute ($con, "select image from person where id =1");
if ($req) {
list ($oid) = cubrid_fetch($req);
cubrid_close_request($req);
Header ("Content-type: image/jpeg");
cubrid_send_glo ($con, $oid);
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 cubrid_send_glo()

注意:

This function is removed from CUBRID 3.1.

参考

  • cubrid_new_glo() - Create a glo instance
  • cubrid_save_to_glo() - Save requested file in a GLO instance
  • cubrid_load_from_glo() - Read data from a GLO instance and save it in a file


dBase

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • dBase 関数
    • dbase_add_record — Adds a record to a database
    • dbase_close — Closes a database
    • dbase_create — Creates a database
    • dbase_delete_record — Deletes a record from a database
    • dbase_get_header_info — Gets the header info of a database
    • dbase_get_record — Gets a record from a database as an indexed array
    • dbase_get_record_with_names — Gets a record from a database as an associative array
    • dbase_numfields — Gets the number of fields of a database
    • dbase_numrecords — Gets the number of records in a database
    • dbase_open — Opens a database
    • dbase_pack — Packs a database
    • dbase_replace_record — Replaces a record in a database


はじめに

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.3.0.

These functions allow you to access records stored in dBase-format (dbf) databases.

警告

We recommend against using dBase files as your production database. Use » SQLite or choose any real SQL server instead; » MySQL or » Postgres are common choices with PHP. dBase support is here to allow you to import and export data to and from your web database, because the file format is commonly understood by Windows spreadsheets and organizers.

警告

As of dbase 7.0.0 the databases are automatically locked via flock(). There has been no support for locking earlier, so two concurrent web server processes modifying the same dBase file would have very likely ruined your database. This can happen even with dbase 7.0.0+ on systems which implement the locks at the process level with multithreaded SAPIs.

dBase files are simple sequential files of fixed length records. Records are appended to the end of the file and deleted records are kept until you call dbase_pack().

Only dbf file levels 3 (dBASE III+) - 5 (dBASE V) are supported. The types of dBase fields available are:

Available types of fields
Field | dBase Type | Format | Additional information
M | Memo | n/a | This type is not supported by PHP, such field will be ignored
D | Date | YYYYMMDD | The field length is limited to 8
T | DateTime | YYYYMMDDhhmmss.uuu | (FoxPro) No validity checks are done. Available as of dbase 7.0.0.
N | Number | A number | You must declare a length and a precision (the number of digits after the decimal point).
F | Float | A float number | Same as N.
C | String | A string | You must declare a length. When retrieving data, the string will be right-padded with spaces to fit the declared length. Overlong strings will be silently truncated when storing data.
L | Boolean | T or Y for true, F or N for false, ? for uninitialized. | As of dbase 7.0.0, returned as a bool (true or false), or null for uninitialized fields. Formerly, returned as an int (1 or 0).

注意:

As of dbase 7.0.0 nullable fields are supported for DBASE_TYPE_FOXPRO databases. If a field is nullable, passing null will set the respective flag, and on later retrieval the field value will be null.

注意:

There is no support for indexes or memo fields.


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • dBase
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/dbase.


リソース型

As of dbase 7.0.0, the resource type dbase is defined, which is returned by dbase_open() and dbase_create().


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

DBASE_VERSION (string)
The extension version. (Available as of dbase 7.0.0)
DBASE_RDONLY (int)
Open database for reading only. Used with dbase_open(). (Available as of dbase 7.0.0)
DBASE_RDWR (int)
Open database for reading and writing. Used with dbase_open(). (Available as of dbase 7.0.0)
DBASE_TYPE_DBASE (int)
Create dBASE style database. Used with dbase_create(). (Available as of dbase 7.0.0)
DBASE_TYPE_FOXPRO (int)
Create FoxPro style database. Used with dbase_create(). (Available as of dbase 7.0.0)


dBase 関数

例

Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create().

目次

  • dbase_add_record — Adds a record to a database
  • dbase_close — Closes a database
  • dbase_create — Creates a database
  • dbase_delete_record — Deletes a record from a database
  • dbase_get_header_info — Gets the header info of a database
  • dbase_get_record — Gets a record from a database as an indexed array
  • dbase_get_record_with_names — Gets a record from a database as an associative array
  • dbase_numfields — Gets the number of fields of a database
  • dbase_numrecords — Gets the number of records in a database
  • dbase_open — Opens a database
  • dbase_pack — Packs a database
  • dbase_replace_record — Replaces a record in a database


Adds a record to a database

  • ≪ dBase 関数
  • dbase_close ≫
  • PHP Manual
  • dBase 関数
  • Adds a record to a database

dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Adds a record to a database

説明

dbase_add_record(resource $database, array $data): bool

Adds the given data to the database.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

data

An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.

注意:

If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Inserting a record in a dBase database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
dbase_add_record($db, array(
date('Ymd'),
'Maxim Topolov',
'23',
'max@example.com',
'T'));
dbase_close($db);
}

?>

参考

  • dbase_delete_record() - Deletes a record from a database
  • dbase_replace_record() - Replaces a record in a database


Closes a database

  • ≪ dbase_add_record
  • dbase_create ≫
  • PHP Manual
  • dBase 関数
  • Closes a database

dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Closes a database

説明

dbase_close(resource $database): bool

Closes the given database resource.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Closing a dBase database file

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
// read some data ..

dbase_close($db);
}

?>

参考

  • dbase_open() - Opens a database
  • dbase_create() - Creates a database


Creates a database

  • ≪ dbase_close
  • dbase_delete_record ≫
  • PHP Manual
  • dBase 関数
  • Creates a database

dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Creates a database

説明

dbase_create(string $path, array $fields, int $type = DBASE_TYPE_DBASE): resource

dbase_create() creates a dBase database with the given definition. If the file already exists, it is not truncated. dbase_pack() can be called to force truncation.

注意:

この関数の動作は、open_basedir の設定に依存します。

パラメータ

path

The path of the database. It can be a relative or absolute path to the file where dBase will store your data.

fields

An array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, a precision and a nullable flag. The supported field types are listed in the introduction section.

注意:

The fieldnames are limited in length and must not exceed 10 chars.

type

The type of database to be created. Either DBASE_TYPE_DBASE or DBASE_TYPE_FOXPRO.

戻り値

Returns a database resource if the database is successfully created, or false if an error occurred.

変更履歴

バージョン | 説明
dbase 7.0.0 | The type parameter has been added.
dbase 7.0.0 | The return value is now a resource instead of an int.

例

例1 Creating a dBase database file

<?php

// database "definition"
$def = array(
array("date", "D"),
array("name", "C", 50),
array("age", "N", 3, 0),
array("email", "C", 128),
array("ismember", "L")
);

// creation
if (!dbase_create('/tmp/test.dbf', $def)) {
echo "Error, can't create the database\n";
}

?>

参考

  • dbase_open() - Opens a database
  • dbase_close() - Closes a database


Deletes a record from a database

  • ≪ dbase_create
  • dbase_get_header_info ≫
  • PHP Manual
  • dBase 関数
  • Deletes a record from a database

dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Deletes a record from a database

説明

dbase_delete_record(resource $database, int $number): bool

Marks the given record to be deleted from the database.

注意:

To actually remove the record from the database, you must also call dbase_pack().

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

number

An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

参考

  • dbase_add_record() - Adds a record to a database
  • dbase_replace_record() - Replaces a record in a database


Gets the header info of a database

  • ≪ dbase_delete_record
  • dbase_get_record ≫
  • PHP Manual
  • dBase 関数
  • Gets the header info of a database

dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Gets the header info of a database

説明

dbase_get_header_info(resource $database): array

Returns information on the column structure of the given database resource.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

戻り値

An indexed array with an entry for each column in the database. The array index starts at 0.

Each array element contains an associative array of column information, as described here:

name
The name of the column
type
The human-readable name for the dbase type of the column (i.e. date, boolean, etc.) The supported field types are listed in the introduction section.
length
The number of bytes this column can hold
precision
The number of digits of decimal precision for the column
format
A suggested printf() format specifier for the column
offset
The byte offset of the column from the start of the row

If the database header information cannot be read, false is returned.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Showing header information for a dBase database file

<?php
// Path to dbase file
$db_path = "/tmp/test.dbf";

// Open dbase file
$dbh = dbase_open($db_path, 0)
or die("Error! Could not open dbase database file '$db_path'.");

// Get column information
$column_info = dbase_get_header_info($dbh);

// Display information
print_r($column_info);
?>


Gets a record from a database as an indexed array

  • ≪ dbase_get_header_info
  • dbase_get_record_with_names ≫
  • PHP Manual
  • dBase 関数
  • Gets a record from a database as an indexed array

dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Gets a record from a database as an indexed array

説明

dbase_get_record(resource $database, int $number): array

Gets a record from a database as an indexed array.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

number

The index of the record between 1 and dbase_numrecords($dbase_identifier).

戻り値

An indexed array with the record. This array will also include an associative key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).

各フィールドは適切な PHP の型に変換されますが、以下に挙げる例外があります。

  • Date は文字列のままになります。
  • DateTime は文字列に変換されます。
  • PHP_INT_MIN..PHP_INT_MAX の範囲外の Integer は文字列になります。
  • dbase 7.0.0 より前のバージョンでは、boolean (L) が 1 あるいは 0 に変換されていました。

On error, dbase_get_record() will return false.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

参考

  • dbase_get_record_with_names() - Gets a record from a database as an associative array


Gets a record from a database as an associative array

  • ≪ dbase_get_record
  • dbase_numfields ≫
  • PHP Manual
  • dBase 関数
  • Gets a record from a database as an associative array

dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Gets a record from a database as an associative array

説明

dbase_get_record_with_names(resource $database, int $number): array

Gets a record from a dBase database as an associative array.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

number

The index of the record between 1 and dbase_numrecords($dbase_identifier).

戻り値

An associative array with the record. This will also include a key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()). Therefore it is not possible to retrieve the value of a field named deleted with this function.

各フィールドは適切な PHP の型に変換されますが、以下に挙げる例外があります。

  • Date は文字列のままになります。
  • DateTime は文字列に変換されます。
  • PHP_INT_MIN..PHP_INT_MAX の範囲外の Integer は文字列になります。
  • dbase 7.0.0 より前のバージョンでは、boolean (L) が 1 あるいは 0 に変換されていました。

On error, dbase_get_record_with_names() will return false.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Listing all the registered members in the database

<?php
// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
$record_numbers = dbase_numrecords($db);
for ($i = 1; $i <= $record_numbers; $i++) {
$row = dbase_get_record_with_names($db, $i);
if ($row['ismember'] == 1) {
echo "Member #$i: " . trim($row['name']) . "\n";
}
}
}
?>

参考

  • dbase_get_record() - Gets a record from a database as an indexed array


Gets the number of fields of a database

  • ≪ dbase_get_record_with_names
  • dbase_numrecords ≫
  • PHP Manual
  • dBase 関数
  • Gets the number of fields of a database

dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Gets the number of fields of a database

説明

dbase_numfields(resource $database): int

Gets the number of fields (columns) in the specified database.

注意:

Field numbers are between 0 and dbase_numfields($db)-1, while record numbers are between 1 and dbase_numrecords($db).

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

戻り値

The number of fields in the database, or false if an error occurs.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 dbase_numfields() Example

<?php

$rec = dbase_get_record($db, $recno);
$nf = dbase_numfields($db);
for ($i = 0; $i < $nf; $i++) {
echo $rec[$i], "\n";
}

?>

参考

  • dbase_numrecords() - Gets the number of records in a database


Gets the number of records in a database

  • ≪ dbase_numfields
  • dbase_open ≫
  • PHP Manual
  • dBase 関数
  • Gets the number of records in a database

dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Gets the number of records in a database

説明

dbase_numrecords(resource $database): int

Gets the number of records (rows) in the specified database.

注意:

Records which are marked as deleted are counted as well.

注意:

Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

戻り値

The number of records in the database, or false if an error occurs.

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Looping over all the records of the database

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
$record_numbers = dbase_numrecords($db);
for ($i = 1; $i <= $record_numbers; $i++) {
$record = dbase_get_record($db, $i);
if (!$record['deleted']) {
// do something with the $record
} else {
// do something with the deleted $record or ignore it
}
}
}

?>

参考

  • dbase_numfields() - Gets the number of fields of a database


Opens a database

  • ≪ dbase_numrecords
  • dbase_pack ≫
  • PHP Manual
  • dBase 関数
  • Opens a database

dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Opens a database

説明

dbase_open(string $path, int $mode): resource|false

dbase_open() opens a dBase database with the given access mode.

注意:

この関数の動作は、open_basedir の設定に依存します。

パラメータ

path

The path of the database. It can be a relative or absolute path to the file where dBase will store your data.

mode

An integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).

注意:

You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as mode.

As of dbase 7.0.0 you can use DBASE_RDONLY and DBASE_RDWR, respectively, to specify the mode.

戻り値

Returns a database resource on success, 失敗した場合に false を返します.

変更履歴

バージョン | 説明
dbase 7.0.0 | The return value is now a resource instead of an int.

例

例1 Opening a dBase database file

<?php

// open in read-only mode
$db = dbase_open('/tmp/test.dbf', 0);

if ($db) {
// read some data ..

dbase_close($db);
}

?>

参考

  • dbase_create() - Creates a database
  • dbase_close() - Closes a database


Packs a database

  • ≪ dbase_open
  • dbase_replace_record ≫
  • PHP Manual
  • dBase 関数
  • Packs a database

dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Packs a database

説明

dbase_pack(resource $database): bool

Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record(). Note that the file will be truncated after successful packing (contrary to dBASE III's PACK command).

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Emptying a dBase database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
$record_numbers = dbase_numrecords($db);
for ($i = 1; $i <= $record_numbers; $i++) {
dbase_delete_record($db, $i);
}
// expunge the database
dbase_pack($db);
}

?>

参考

  • dbase_delete_record() - Deletes a record from a database


Replaces a record in a database

  • ≪ dbase_pack
  • Firebird/InterBase ≫
  • PHP Manual
  • dBase 関数
  • Replaces a record in a database

dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Replaces a record in a database

説明

dbase_replace_record(resource $database, array $data, int $number): bool

Replaces the given record in the database with the given data.

パラメータ

database

The database resource, returned by dbase_open() or dbase_create().

data

An indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_replace_record() will fail.

注意:

If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.

number

An integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
dbase 7.0.0 | database is now a resource instead of an int.

例

例1 Updating a record in the database

<?php

// open in read-write mode
$db = dbase_open('/tmp/test.dbf', 2);

if ($db) {
// gets the old row
$row = dbase_get_record_with_names($db, 1);

// remove the 'deleted' entry
unset($row['deleted']);

// Update the date field with the current timestamp
$row['date'] = date('Ymd');

// convert the row to an indexed array
$row = array_values($row);

// Replace the record
dbase_replace_record($db, $row, 1);
dbase_close($db);
}

?>

注意

注意:

Boolean fields result in an int element value (0 or 1) when retrieved via dbase_get_record() or dbase_get_record_with_names(). If they are written back, this results in the value becoming 0, so care has to be taken to properly adjust the values.

参考

  • dbase_add_record() - Adds a record to a database
  • dbase_delete_record() - Deletes a record from a database


Firebird/InterBase

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Firebird/InterBase 関数
    • fbird_add_user — のエイリアス ibase_add_user
    • fbird_affected_rows — のエイリアス ibase_affected_rows
    • fbird_backup — のエイリアス ibase_backup
    • fbird_blob_add — のエイリアス ibase_blob_add
    • fbird_blob_cancel — Cancel creating blob
    • fbird_blob_close — のエイリアス ibase_blob_close
    • fbird_blob_create — のエイリアス ibase_blob_create
    • fbird_blob_echo — のエイリアス ibase_blob_echo
    • fbird_blob_get — のエイリアス ibase_blob_get
    • fbird_blob_import — のエイリアス ibase_blob_import
    • fbird_blob_info — のエイリアス ibase_blob_info
    • fbird_blob_open — のエイリアス ibase_blob_open
    • fbird_close — のエイリアス ibase_close
    • fbird_commit — のエイリアス ibase_commit
    • fbird_commit_ret — のエイリアス ibase_commit_ret
    • fbird_connect — のエイリアス ibase_connect
    • fbird_db_info — のエイリアス ibase_db_info
    • fbird_delete_user — のエイリアス ibase_delete_user
    • fbird_drop_db — のエイリアス ibase_drop_db
    • fbird_errcode — のエイリアス ibase_errcode
    • fbird_errmsg — のエイリアス ibase_errmsg
    • fbird_execute — のエイリアス ibase_execute
    • fbird_fetch_assoc — のエイリアス ibase_fetch_assoc
    • fbird_fetch_object — のエイリアス ibase_fetch_object
    • fbird_fetch_row — のエイリアス ibase_fetch_row
    • fbird_field_info — のエイリアス ibase_field_info
    • fbird_free_event_handler — のエイリアス ibase_free_event_handler
    • fbird_free_query — のエイリアス ibase_free_query
    • fbird_free_result — のエイリアス ibase_free_result
    • fbird_gen_id — のエイリアス ibase_gen_id
    • fbird_maintain_db — のエイリアス ibase_maintain_db
    • fbird_modify_user — のエイリアス ibase_modify_user
    • fbird_name_result — のエイリアス ibase_name_result
    • fbird_num_fields — のエイリアス ibase_num_fields
    • fbird_num_params — のエイリアス ibase_num_params
    • fbird_param_info — のエイリアス ibase_param_info
    • fbird_pconnect — のエイリアス ibase_pconnect
    • fbird_prepare — のエイリアス ibase_prepare
    • fbird_query — のエイリアス ibase_query
    • fbird_restore — のエイリアス ibase_restore
    • fbird_rollback — のエイリアス ibase_rollback
    • fbird_rollback_ret — のエイリアス ibase_rollback_ret
    • fbird_server_info — のエイリアス ibase_server_info
    • fbird_service_attach — のエイリアス ibase_service_attach
    • fbird_service_detach — のエイリアス ibase_service_detach
    • fbird_set_event_handler — のエイリアス ibase_set_event_handler
    • fbird_trans — のエイリアス ibase_trans
    • fbird_wait_event — のエイリアス ibase_wait_event
    • ibase_add_user — Add a user to a security database
    • ibase_affected_rows — 直近のクエリで変更された行の数を返す
    • ibase_backup — Initiates a backup task in the service manager and returns immediately
    • ibase_blob_add — 生成された blob にデータを追加する
    • ibase_blob_cancel — blob の生成を取り消す
    • ibase_blob_close — blob を閉じる
    • ibase_blob_create — データを追加するために blob を生成する
    • ibase_blob_echo — ブラウザに blob の内容を出力する
    • ibase_blob_get — オープンした blob から len バイト分のデータを取得する
    • ibase_blob_import — blob を生成し、ファイルをコピーし、閉じる
    • ibase_blob_info — blob の長さと他の便利な情報を返す
    • ibase_blob_open — データの一部を取得するために blob をオープンする
    • ibase_close — InterBase データベースへの接続を閉じる
    • ibase_commit — トランザクションをコミットする
    • ibase_commit_ret — トランザクションを閉じずにコミットする
    • ibase_connect — データベースへの接続をオープンする
    • ibase_db_info — データベースについての統計情報を要求する
    • ibase_delete_user — Delete a user from a security database
    • ibase_drop_db — データベースを削除する
    • ibase_errcode — エラーコードを返す
    • ibase_errmsg — エラーメッセージを返す
    • ibase_execute — 準備されたクエリを実行する
    • ibase_fetch_assoc — クエリの結果から、行を連想配列として取得する
    • ibase_fetch_object — InterBase データベースからオブジェクトを得る
    • ibase_fetch_row — InterBase データベースから 1 行分の結果を取得する
    • ibase_field_info — フィールドに関する情報を得る
    • ibase_free_event_handler — 登録済みのイベントハンドラをキャンセルする
    • ibase_free_query — プリペアドクエリにより確保されたメモリを解放する
    • ibase_free_result — 結果セットを解放する
    • ibase_gen_id — 指定した名前のジェネレータをひとつ加算し、その新しい値を返す
    • ibase_maintain_db — データベースサーバーでメンテナンスコマンドを実行する
    • ibase_modify_user — Modify a user to a security database
    • ibase_name_result — 結果セットに名前を割り当てる
    • ibase_num_fields — 結果セットにおけるフィールド数を得る
    • ibase_num_params — プリペアドクエリのパラメータ数を返す
    • ibase_param_info — プリペアドクエリのパラメータに関する情報を返す
    • ibase_pconnect — InterBase データベースへの持続的接続をオープンする
    • ibase_prepare — Prepare a query for later binding of parameter placeholders and execution
    • ibase_query — InterBase データベースでクエリを実行する
    • ibase_restore — Initiates a restore task in the service manager and returns immediately
    • ibase_rollback — トランザクションをロールバックする
    • ibase_rollback_ret — トランザクションを閉じずにロールバックする
    • ibase_server_info — データベースサーバーについての情報を要求する
    • ibase_service_attach — サービスマネージャに接続する
    • ibase_service_detach — サービスマネージャとの接続を切断する
    • ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する
    • ibase_trans — トランザクションを開始する
    • ibase_wait_event — データベースでイベントが発生するのを待つ


はじめに

警告

この拡張モジュールは、メンテナンスされておらず開発が止まっています。 しかし、ソースコードは PECL GIT から取得できます。 » https://github.com/php/pecl-database-interbase.

Firebird は ISO SQL-2003 の多くの機能をサポートする リレーショナルデータベースで、Linux・Windows その他多くの Unix プラットフォーム上で動作します。Firebird は 優れた同時実行性・パフォーマンス、そしてストアドプロシージャや トリガでの強力な言語サポートを提供します。1981 年以降、このデータベースは さまざまな名前の製品として使用されています。

InterBase はこの RDBMS のクローズドソース版の名前で、Embarcadero/Inprise によって開発されました。InterBase についての詳細な情報は » http://www.embarcadero.com/products/interbase にあります。

Firebird は C++プログラマーやテクニカルアドバイザやサポーターたちによる 商業的に独立したプロジェクトです。Inprise Corp（現在は Embarcadero という名で知られています）が 2000 年 7 月 25 日に InterBase Public License v.1.0 の下で公開したソースコードをもとにして、 マルチプラットフォームなリレーショナルデータベースの開発と機能拡張を 行っています。Firebird についての詳細な情報は » http://www.firebirdsql.org/ にあります。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.4.0

この拡張モジュールは、InterBase のバージョン 6 以降と Firebird のバージョン 2.0 以降をサポートします。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Firebird/InterBase
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ibase.

PHP で Firebird/InterBase サポートを有効にするには、 --with-interbase[=DIR] を指定して 設定を行います。ただし、DIR は Firebird/InterBase のベースインストールディレクトリで、 デフォルトは /usr です。

注意: Win32/Win64 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 fbclient.dll,gds32.dll

Firebird/InterBase データベースサーバーを PHP と同じマシンにインストールしている場合は、 すでに DLL が存在するはずです。その場合は特に何も考える必要はありません。 というのも fbclient.dll,gds32.dll (gds32.dll は、レガシーアプリケーション用にインストーラーが生成するもの) はすでに PATH の通った場所に存在するからです。


実行時設定

php.ini の設定により動作が変化します。

InterBase設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ibase.allow_persistent | "1" | INI_SYSTEM |
ibase.max_persistent | "-1" | INI_SYSTEM |
ibase.max_links | "-1" | INI_SYSTEM |
ibase.default_db | NULL | INI_SYSTEM |
ibase.default_user | NULL | INI_ALL |
ibase.default_password | NULL | INI_ALL |
ibase.default_charset | NULL | INI_ALL |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | INI_ALL |
ibase.dateformat | "%Y-%m-%d" | INI_ALL |
ibase.timeformat | "%H:%M:%S" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ibase.allow_persistent bool

Firebird/InterBase 持続的な接続 を許可するかどうか。

ibase.max_persistent int

プロセスごとの、Firebird/InterBase の持続的接続の最大数。 この数を超えた場合、ibase_pconnect() による新しい接続は 持続的ではない接続になります。

ibase.max_links int

プロセスごとの Firebird/InterBase の接続の最大数。持続的な接続の数も 含みます。

ibase.default_db string

データベース名を指定せずに ibase_[p]connect() がコールされた場合に 接続するデフォルトのデータベース。この値が設定されており、かつ SQL セーフモードが有効な場合、このデータベース以外への接続は一切許可されません。

ibase.default_user string

ユーザー名を指定せずにデータベースに接続した際に使用されるユーザー名。

ibase.default_password string

パスワードを指定せずにデータベースに接続した際に使用されるパスワード。

ibase.default_charset string

文字セットを指定せずにデータベースに接続した際に使用される文字セット。

ibase.timestampformat string

ibase.dateformat string

ibase.timeformat string

これらのディレクティブは日付や時間のフォーマットを指定します。 結果セットの中の日付や時間のデータ、そしてパラメータとしてバインドする 日付や時間のデータに適用されます。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

トランザクションの挙動を設定するため、以下の定数を ibase_trans() に渡すことが可能です。

Firebird/InterBase トランザクションフラグ
定数 | 説明
IBASE_DEFAULT | デフォルトのトランザクション設定が使用されます。デフォルト設定は クライアントライブラリによって決定され、たいていの場合は IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT です。
IBASE_READ | 読み込み専用のトランザクションを開始します。
IBASE_WRITE | 読み書き可能なトランザクションを開始します。
IBASE_CONSISTENCY | 分離レベルを 'consistency' にしてトランザクションを開始します。 他のトランザクションによって変更中のテーブルを読み込むことは できません。
IBASE_CONCURRENCY | 分離レベルを 'concurrency' (あるいは 'snapshot') にして トランザクションを開始します。すべてのテーブルへのアクセスが 可能ですが、トランザクションの開始以降に別のトランザクションに よってコミットされた内容を見ることはできません。
IBASE_COMMITTED | 分離レベルを 'read committed' にしてトランザクションを開始します。 このフラグは IBASE_REC_VERSION あるいは IBASE_REC_NO_VERSION とともに使用する必要があります。 トランザクションの開始以降にコミットされた内容についてもアクセス可能と なります。IBASE_REC_NO_VERSION が指定された場合、 最新バージョンのデータのみが読み込み可能となります。 IBASE_REC_VERSION が指定された場合、他の トランザクションで処理が完了していない変更についても読み込むことが できます。
IBASE_WAIT | 衝突が発生した場合に、トランザクションが処理を再試行することを示します。
IBASE_NOWAIT | 衝突が発生した場合に、トランザクションがその場で処理を中断して 処理が失敗することを示します。

データの取得方法を指定するために、以下の定数を ibase_fetch_row()、 ibase_fetch_assoc() あるいは ibase_fetch_object() に渡すことが可能です。

Firebird/InterBase フェッチフラグ
定数 | 説明
IBASE_FETCH_BLOBS | 過去との互換性を保持するため、IBASE_TEXT としても使用可能です。BLOB データを読み込む際に、BLOB ID ではなく 直接データそのものを読み込みます。
IBASE_FETCH_ARRAYS | 配列をインラインで読み込みます。指定しなかった場合は、配列の ID を返します。配列 ID は INSERT 操作への引数としてのみ使用可能で、 配列 ID を処理できる関数は現在存在しません。
IBASE_UNIXTIME | 日付や時刻のフィールド値を、文字列ではなく UNIX タイムスタンプ (1-Jan-1970 0:00 UTC からの経過秒数)で返します。 1970 年より前の日付に対してこれを使用すると、環境によっては 問題を引き起こす可能性があります。

要求内容やオプションを指定するために、以下の定数を サービス API 関数(ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() および ibase_maintain_db())に渡すことが可能です。 これらのオプションの意味については Firebird/InterBase のマニュアルを 参照ください。

IBASE_BKP_IGNORE_CHECKSUMS
ibase_backup() のオプション
IBASE_BKP_IGNORE_LIMBO
ibase_backup() のオプション
IBASE_BKP_METADATA_ONLY
ibase_backup() のオプション
IBASE_BKP_NO_GARBAGE_COLLECT
ibase_backup() のオプション
IBASE_BKP_OLD_DESCRIPTIONS
ibase_backup() のオプション
IBASE_BKP_NON_TRANSPORTABLE
ibase_backup() のオプション
IBASE_BKP_CONVERT
ibase_backup() のオプション
IBASE_RES_DEACTIVATE_IDX
ibase_restore() のオプション
IBASE_RES_NO_SHADOW
ibase_restore() のオプション
IBASE_RES_NO_VALIDITY
ibase_restore() のオプション
IBASE_RES_ONE_AT_A_TIME
ibase_restore() のオプション
IBASE_RES_REPLACE
IBASE_RES_CREATE
Options to ibase_restore()
IBASE_RES_USE_ALL_SPACE
ibase_restore() のオプション
IBASE_PRP_PAGE_BUFFERS
IBASE_PRP_SWEEP_INTERVAL
IBASE_PRP_SHUTDOWN_DB
IBASE_PRP_DENY_NEW_TRANSACTIONS
IBASE_PRP_DENY_NEW_ATTACHMENTS
IBASE_PRP_RESERVE_SPACE
IBASE_PRP_RES_USE_FULL
IBASE_PRP_RES
IBASE_PRP_WRITE_MODE
IBASE_PRP_WM_ASYNC
IBASE_PRP_WM_SYNC
IBASE_PRP_ACCESS_MODE
IBASE_PRP_AM_READONLY
IBASE_PRP_AM_READWRITE
IBASE_PRP_SET_SQL_DIALECT
IBASE_PRP_ACTIVATE
IBASE_PRP_DB_ONLINE
IBASE_RPR_CHECK_DB
IBASE_RPR_IGNORE_CHECKSUM
IBASE_RPR_KILL_SHADOWS
IBASE_RPR_MEND_DB
IBASE_RPR_VALIDATE_DB
IBASE_RPR_FULL
IBASE_RPR_SWEEP_DB
ibase_maintain_db() のオプション
IBASE_STS_DATA_PAGES
IBASE_STS_DB_LOG
IBASE_STS_HDR_PAGES
IBASE_STS_IDX_PAGES
IBASE_STS_SYS_RELATIONS
ibase_db_info() のオプション
IBASE_SVC_SERVER_VERSION
Options to ibase_server_info()
IBASE_SVC_IMPLEMENTATION
Options to ibase_server_info()
IBASE_SVC_GET_ENV
Options to ibase_server_info()
IBASE_SVC_GET_ENV_LOCK
IBASE_SVC_GET_ENV_MSG
IBASE_SVC_USER_DBPATH
IBASE_SVC_SVR_DB_INFO
IBASE_SVC_GET_USERS
ibase_server_info() のオプション


Firebird/InterBase 関数

目次

  • fbird_add_user — のエイリアス ibase_add_user
  • fbird_affected_rows — のエイリアス ibase_affected_rows
  • fbird_backup — のエイリアス ibase_backup
  • fbird_blob_add — のエイリアス ibase_blob_add
  • fbird_blob_cancel — Cancel creating blob
  • fbird_blob_close — のエイリアス ibase_blob_close
  • fbird_blob_create — のエイリアス ibase_blob_create
  • fbird_blob_echo — のエイリアス ibase_blob_echo
  • fbird_blob_get — のエイリアス ibase_blob_get
  • fbird_blob_import — のエイリアス ibase_blob_import
  • fbird_blob_info — のエイリアス ibase_blob_info
  • fbird_blob_open — のエイリアス ibase_blob_open
  • fbird_close — のエイリアス ibase_close
  • fbird_commit — のエイリアス ibase_commit
  • fbird_commit_ret — のエイリアス ibase_commit_ret
  • fbird_connect — のエイリアス ibase_connect
  • fbird_db_info — のエイリアス ibase_db_info
  • fbird_delete_user — のエイリアス ibase_delete_user
  • fbird_drop_db — のエイリアス ibase_drop_db
  • fbird_errcode — のエイリアス ibase_errcode
  • fbird_errmsg — のエイリアス ibase_errmsg
  • fbird_execute — のエイリアス ibase_execute
  • fbird_fetch_assoc — のエイリアス ibase_fetch_assoc
  • fbird_fetch_object — のエイリアス ibase_fetch_object
  • fbird_fetch_row — のエイリアス ibase_fetch_row
  • fbird_field_info — のエイリアス ibase_field_info
  • fbird_free_event_handler — のエイリアス ibase_free_event_handler
  • fbird_free_query — のエイリアス ibase_free_query
  • fbird_free_result — のエイリアス ibase_free_result
  • fbird_gen_id — のエイリアス ibase_gen_id
  • fbird_maintain_db — のエイリアス ibase_maintain_db
  • fbird_modify_user — のエイリアス ibase_modify_user
  • fbird_name_result — のエイリアス ibase_name_result
  • fbird_num_fields — のエイリアス ibase_num_fields
  • fbird_num_params — のエイリアス ibase_num_params
  • fbird_param_info — のエイリアス ibase_param_info
  • fbird_pconnect — のエイリアス ibase_pconnect
  • fbird_prepare — のエイリアス ibase_prepare
  • fbird_query — のエイリアス ibase_query
  • fbird_restore — のエイリアス ibase_restore
  • fbird_rollback — のエイリアス ibase_rollback
  • fbird_rollback_ret — のエイリアス ibase_rollback_ret
  • fbird_server_info — のエイリアス ibase_server_info
  • fbird_service_attach — のエイリアス ibase_service_attach
  • fbird_service_detach — のエイリアス ibase_service_detach
  • fbird_set_event_handler — のエイリアス ibase_set_event_handler
  • fbird_trans — のエイリアス ibase_trans
  • fbird_wait_event — のエイリアス ibase_wait_event
  • ibase_add_user — Add a user to a security database
  • ibase_affected_rows — 直近のクエリで変更された行の数を返す
  • ibase_backup — Initiates a backup task in the service manager and returns immediately
  • ibase_blob_add — 生成された blob にデータを追加する
  • ibase_blob_cancel — blob の生成を取り消す
  • ibase_blob_close — blob を閉じる
  • ibase_blob_create — データを追加するために blob を生成する
  • ibase_blob_echo — ブラウザに blob の内容を出力する
  • ibase_blob_get — オープンした blob から len バイト分のデータを取得する
  • ibase_blob_import — blob を生成し、ファイルをコピーし、閉じる
  • ibase_blob_info — blob の長さと他の便利な情報を返す
  • ibase_blob_open — データの一部を取得するために blob をオープンする
  • ibase_close — InterBase データベースへの接続を閉じる
  • ibase_commit — トランザクションをコミットする
  • ibase_commit_ret — トランザクションを閉じずにコミットする
  • ibase_connect — データベースへの接続をオープンする
  • ibase_db_info — データベースについての統計情報を要求する
  • ibase_delete_user — Delete a user from a security database
  • ibase_drop_db — データベースを削除する
  • ibase_errcode — エラーコードを返す
  • ibase_errmsg — エラーメッセージを返す
  • ibase_execute — 準備されたクエリを実行する
  • ibase_fetch_assoc — クエリの結果から、行を連想配列として取得する
  • ibase_fetch_object — InterBase データベースからオブジェクトを得る
  • ibase_fetch_row — InterBase データベースから 1 行分の結果を取得する
  • ibase_field_info — フィールドに関する情報を得る
  • ibase_free_event_handler — 登録済みのイベントハンドラをキャンセルする
  • ibase_free_query — プリペアドクエリにより確保されたメモリを解放する
  • ibase_free_result — 結果セットを解放する
  • ibase_gen_id — 指定した名前のジェネレータをひとつ加算し、その新しい値を返す
  • ibase_maintain_db — データベースサーバーでメンテナンスコマンドを実行する
  • ibase_modify_user — Modify a user to a security database
  • ibase_name_result — 結果セットに名前を割り当てる
  • ibase_num_fields — 結果セットにおけるフィールド数を得る
  • ibase_num_params — プリペアドクエリのパラメータ数を返す
  • ibase_param_info — プリペアドクエリのパラメータに関する情報を返す
  • ibase_pconnect — InterBase データベースへの持続的接続をオープンする
  • ibase_prepare — Prepare a query for later binding of parameter placeholders and execution
  • ibase_query — InterBase データベースでクエリを実行する
  • ibase_restore — Initiates a restore task in the service manager and returns immediately
  • ibase_rollback — トランザクションをロールバックする
  • ibase_rollback_ret — トランザクションを閉じずにロールバックする
  • ibase_server_info — データベースサーバーについての情報を要求する
  • ibase_service_attach — サービスマネージャに接続する
  • ibase_service_detach — サービスマネージャとの接続を切断する
  • ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する
  • ibase_trans — トランザクションを開始する
  • ibase_wait_event — データベースでイベントが発生するのを待つ


のエイリアス ibase_add_user

  • ≪ Firebird/InterBase 関数
  • fbird_affected_rows ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_add_user

fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — のエイリアス ibase_add_user()

説明

この関数は次の関数のエイリアスです。 ibase_add_user().

参考

  • fbird_modify_user() - のエイリアス ibase_modify_user
  • fbird_delete_user() - のエイリアス ibase_delete_user


のエイリアス ibase_affected_rows

  • ≪ fbird_add_user
  • fbird_backup ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_affected_rows

fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — のエイリアス ibase_affected_rows()

説明

この関数は次の関数のエイリアスです。 ibase_affected_rows().

参考

  • fbird_query() - のエイリアス ibase_query
  • fbird_execute() - のエイリアス ibase_execute


のエイリアス ibase_backup

  • ≪ fbird_affected_rows
  • fbird_blob_add ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_backup

fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — のエイリアス ibase_backup()

説明

この関数は次の関数のエイリアスです。 ibase_backup().


のエイリアス ibase_blob_add

  • ≪ fbird_backup
  • fbird_blob_cancel ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_add

fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — のエイリアス ibase_blob_add()

説明

この関数は次の関数のエイリアスです。 ibase_blob_add().

参考

  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_create() - のエイリアス ibase_blob_create
  • fbird_blob_import() - のエイリアス ibase_blob_import


Cancel creating blob

  • ≪ fbird_blob_add
  • fbird_blob_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Cancel creating blob

fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancel creating blob

説明

fbird_blob_cancel(resource $blob_handle): bool

This function will discard a BLOB if it has not yet been closed by fbird_blob_close().

パラメータ

blob_handle

A BLOB handle opened with fbird_blob_create().

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_create() - のエイリアス ibase_blob_create
  • fbird_blob_import() - のエイリアス ibase_blob_import


のエイリアス ibase_blob_close

  • ≪ fbird_blob_cancel
  • fbird_blob_create ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_close

fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — のエイリアス ibase_blob_close()

説明

この関数は次の関数のエイリアスです。 ibase_blob_close().

参考

  • fbird_blob_create() - のエイリアス ibase_blob_create
  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_open() - のエイリアス ibase_blob_open
  • fbird_blob_import() - のエイリアス ibase_blob_import


のエイリアス ibase_blob_create

  • ≪ fbird_blob_close
  • fbird_blob_echo ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_create

fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — のエイリアス ibase_blob_create()

説明

この関数は次の関数のエイリアスです。 ibase_blob_create().

参考

  • fbird_blob_add() - のエイリアス ibase_blob_add
  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_import() - のエイリアス ibase_blob_import


のエイリアス ibase_blob_echo

  • ≪ fbird_blob_create
  • fbird_blob_get ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_echo

fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — のエイリアス ibase_blob_echo()

説明

この関数は次の関数のエイリアスです。 ibase_blob_echo().

参考

  • fbird_blob_open() - のエイリアス ibase_blob_open
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_get() - のエイリアス ibase_blob_get


のエイリアス ibase_blob_get

  • ≪ fbird_blob_echo
  • fbird_blob_import ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_get

fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — のエイリアス ibase_blob_get()

説明

この関数は次の関数のエイリアスです。 ibase_blob_get().

参考

  • fbird_blob_open() - のエイリアス ibase_blob_open
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_echo() - のエイリアス ibase_blob_echo


のエイリアス ibase_blob_import

  • ≪ fbird_blob_get
  • fbird_blob_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_import

fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — のエイリアス ibase_blob_import()

説明

この関数は次の関数のエイリアスです。 ibase_blob_import().

参考

  • fbird_blob_add() - のエイリアス ibase_blob_add
  • fbird_blob_cancel() - Cancel creating blob
  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_create() - のエイリアス ibase_blob_create


のエイリアス ibase_blob_info

  • ≪ fbird_blob_import
  • fbird_blob_open ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_info

fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — のエイリアス ibase_blob_info()

説明

この関数は次の関数のエイリアスです。 ibase_blob_info().


のエイリアス ibase_blob_open

  • ≪ fbird_blob_info
  • fbird_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_blob_open

fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — のエイリアス ibase_blob_open()

説明

この関数は次の関数のエイリアスです。 ibase_blob_open().

参考

  • fbird_blob_close() - のエイリアス ibase_blob_close
  • fbird_blob_echo() - のエイリアス ibase_blob_echo
  • fbird_blob_get() - のエイリアス ibase_blob_get


のエイリアス ibase_close

  • ≪ fbird_blob_open
  • fbird_commit ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_close

fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — のエイリアス ibase_close()

説明

この関数は次の関数のエイリアスです。 ibase_close().

参考

  • fbird_connect() - のエイリアス ibase_connect
  • fbird_pconnect() - のエイリアス ibase_pconnect


のエイリアス ibase_commit

  • ≪ fbird_close
  • fbird_commit_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_commit

fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — のエイリアス ibase_commit()

説明

この関数は次の関数のエイリアスです。 ibase_commit().


のエイリアス ibase_commit_ret

  • ≪ fbird_commit
  • fbird_connect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_commit_ret

fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — のエイリアス ibase_commit_ret()

説明

この関数は次の関数のエイリアスです。 ibase_commit_ret().


のエイリアス ibase_connect

  • ≪ fbird_commit_ret
  • fbird_db_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_connect

fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — のエイリアス ibase_connect()

説明

この関数は次の関数のエイリアスです。 ibase_connect().

参考

  • fbird_pconnect() - のエイリアス ibase_pconnect
  • fbird_close() - のエイリアス ibase_close


のエイリアス ibase_db_info

  • ≪ fbird_connect
  • fbird_delete_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_db_info

fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — のエイリアス ibase_db_info()

説明

この関数は次の関数のエイリアスです。 ibase_db_info().


のエイリアス ibase_delete_user

  • ≪ fbird_db_info
  • fbird_drop_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_delete_user

fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — のエイリアス ibase_delete_user()

説明

この関数は次の関数のエイリアスです。 ibase_delete_user().

参考

  • fbird_add_user() - のエイリアス ibase_add_user
  • fbird_modify_user() - のエイリアス ibase_modify_user


のエイリアス ibase_drop_db

  • ≪ fbird_delete_user
  • fbird_errcode ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_drop_db

fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — のエイリアス ibase_drop_db()

説明

この関数は次の関数のエイリアスです。 ibase_drop_db().

参考

  • fbird_connect() - のエイリアス ibase_connect
  • fbird_pconnect() - のエイリアス ibase_pconnect


のエイリアス ibase_errcode

  • ≪ fbird_drop_db
  • fbird_errmsg ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_errcode

fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — のエイリアス ibase_errcode()

説明

この関数は次の関数のエイリアスです。 ibase_errcode().

参考

  • fbird_errmsg() - のエイリアス ibase_errmsg


のエイリアス ibase_errmsg

  • ≪ fbird_errcode
  • fbird_execute ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_errmsg

fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — のエイリアス ibase_errmsg()

説明

この関数は次の関数のエイリアスです。 ibase_errmsg().

参考

  • fbird_errcode() - のエイリアス ibase_errcode


のエイリアス ibase_execute

  • ≪ fbird_errmsg
  • fbird_fetch_assoc ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_execute

fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — のエイリアス ibase_execute()

説明

この関数は次の関数のエイリアスです。 ibase_execute().

参考

  • fbird_query() - のエイリアス ibase_query


のエイリアス ibase_fetch_assoc

  • ≪ fbird_execute
  • fbird_fetch_object ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_fetch_assoc

fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — のエイリアス ibase_fetch_assoc()

説明

この関数は次の関数のエイリアスです。 ibase_fetch_assoc().

参考

  • fbird_fetch_row() - のエイリアス ibase_fetch_row
  • fbird_fetch_object() - のエイリアス ibase_fetch_object


のエイリアス ibase_fetch_object

  • ≪ fbird_fetch_assoc
  • fbird_fetch_row ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_fetch_object

fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — のエイリアス ibase_fetch_object()

説明

この関数は次の関数のエイリアスです。 ibase_fetch_object().

参考

  • fbird_fetch_row() - のエイリアス ibase_fetch_row
  • fbird_fetch_assoc() - のエイリアス ibase_fetch_assoc


のエイリアス ibase_fetch_row

  • ≪ fbird_fetch_object
  • fbird_field_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_fetch_row

fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — のエイリアス ibase_fetch_row()

説明

この関数は次の関数のエイリアスです。 ibase_fetch_row().

参考

  • fbird_fetch_assoc() - のエイリアス ibase_fetch_assoc
  • fbird_fetch_object() - のエイリアス ibase_fetch_object


のエイリアス ibase_field_info

  • ≪ fbird_fetch_row
  • fbird_free_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_field_info

fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — のエイリアス ibase_field_info()

説明

この関数は次の関数のエイリアスです。 ibase_field_info().

参考

  • fbird_num_fields() - のエイリアス ibase_num_fields


のエイリアス ibase_free_event_handler

  • ≪ fbird_field_info
  • fbird_free_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_free_event_handler

fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — のエイリアス ibase_free_event_handler()

説明

この関数は次の関数のエイリアスです。 ibase_free_event_handler().

参考

  • fbird_set_event_handler() - のエイリアス ibase_set_event_handler


のエイリアス ibase_free_query

  • ≪ fbird_free_event_handler
  • fbird_free_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_free_query

fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — のエイリアス ibase_free_query()

説明

この関数は次の関数のエイリアスです。 ibase_free_query().


のエイリアス ibase_free_result

  • ≪ fbird_free_query
  • fbird_gen_id ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_free_result

fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — のエイリアス ibase_free_result()

説明

この関数は次の関数のエイリアスです。 ibase_free_result().


のエイリアス ibase_gen_id

  • ≪ fbird_free_result
  • fbird_maintain_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_gen_id

fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — のエイリアス ibase_gen_id()

説明

この関数は次の関数のエイリアスです。 ibase_gen_id().


のエイリアス ibase_maintain_db

  • ≪ fbird_gen_id
  • fbird_modify_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_maintain_db

fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — のエイリアス ibase_maintain_db()

説明

この関数は次の関数のエイリアスです。 ibase_maintain_db().


のエイリアス ibase_modify_user

  • ≪ fbird_maintain_db
  • fbird_name_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_modify_user

fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — のエイリアス ibase_modify_user()

説明

この関数は次の関数のエイリアスです。 ibase_modify_user().

参考

  • fbird_add_user() - のエイリアス ibase_add_user
  • fbird_delete_user() - のエイリアス ibase_delete_user


のエイリアス ibase_name_result

  • ≪ fbird_modify_user
  • fbird_num_fields ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_name_result

fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — のエイリアス ibase_name_result()

説明

この関数は次の関数のエイリアスです。 ibase_name_result().

参考

  • fbird_prepare() - のエイリアス ibase_prepare
  • fbird_execute() - のエイリアス ibase_execute


のエイリアス ibase_num_fields

  • ≪ fbird_name_result
  • fbird_num_params ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_num_fields

fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — のエイリアス ibase_num_fields()

説明

この関数は次の関数のエイリアスです。 ibase_num_fields().

参考

  • fbird_field_info() - のエイリアス ibase_field_info


のエイリアス ibase_num_params

  • ≪ fbird_num_fields
  • fbird_param_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_num_params

fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — のエイリアス ibase_num_params()

説明

この関数は次の関数のエイリアスです。 ibase_num_params().

参考

  • fbird_prepare() - のエイリアス ibase_prepare
  • fbird_param_info() - のエイリアス ibase_param_info


のエイリアス ibase_param_info

  • ≪ fbird_num_params
  • fbird_pconnect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_param_info

fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — のエイリアス ibase_param_info()

説明

この関数は次の関数のエイリアスです。 ibase_param_info().

参考

  • fbird_field_info() - のエイリアス ibase_field_info
  • fbird_num_params() - のエイリアス ibase_num_params


のエイリアス ibase_pconnect

  • ≪ fbird_param_info
  • fbird_prepare ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_pconnect

fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — のエイリアス ibase_pconnect()

説明

この関数は次の関数のエイリアスです。 ibase_pconnect().

参考

  • fbird_close() - のエイリアス ibase_close
  • fbird_connect() - のエイリアス ibase_connect


のエイリアス ibase_prepare

  • ≪ fbird_pconnect
  • fbird_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_prepare

fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — のエイリアス ibase_prepare()

説明

この関数は次の関数のエイリアスです。 ibase_prepare().


のエイリアス ibase_query

  • ≪ fbird_prepare
  • fbird_restore ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_query

fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — のエイリアス ibase_query()

説明

この関数は次の関数のエイリアスです。 ibase_query().

参考

  • fbird_errmsg() - のエイリアス ibase_errmsg
  • fbird_fetch_row() - のエイリアス ibase_fetch_row
  • fbird_fetch_object() - のエイリアス ibase_fetch_object
  • fbird_free_result() - のエイリアス ibase_free_result


のエイリアス ibase_restore

  • ≪ fbird_query
  • fbird_rollback ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_restore

fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — のエイリアス ibase_restore()

説明

この関数は次の関数のエイリアスです。 ibase_restore().


のエイリアス ibase_rollback

  • ≪ fbird_restore
  • fbird_rollback_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_rollback

fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — のエイリアス ibase_rollback()

説明

この関数は次の関数のエイリアスです。 ibase_rollback().


のエイリアス ibase_rollback_ret

  • ≪ fbird_rollback
  • fbird_server_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_rollback_ret

fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — のエイリアス ibase_rollback_ret()

説明

この関数は次の関数のエイリアスです。 ibase_rollback_ret().


のエイリアス ibase_server_info

  • ≪ fbird_rollback_ret
  • fbird_service_attach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_server_info

fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — のエイリアス ibase_server_info()

説明

この関数は次の関数のエイリアスです。 ibase_server_info().


のエイリアス ibase_service_attach

  • ≪ fbird_server_info
  • fbird_service_detach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_service_attach

fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — のエイリアス ibase_service_attach()

説明

この関数は次の関数のエイリアスです。 ibase_service_attach().


のエイリアス ibase_service_detach

  • ≪ fbird_service_attach
  • fbird_set_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_service_detach

fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — のエイリアス ibase_service_detach()

説明

この関数は次の関数のエイリアスです。 ibase_service_detach().


のエイリアス ibase_set_event_handler

  • ≪ fbird_service_detach
  • fbird_trans ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_set_event_handler

fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — のエイリアス ibase_set_event_handler()

説明

この関数は次の関数のエイリアスです。 ibase_set_event_handler().

参考

  • fbird_free_event_handler() - のエイリアス ibase_free_event_handler
  • fbird_wait_event() - のエイリアス ibase_wait_event


のエイリアス ibase_trans

  • ≪ fbird_set_event_handler
  • fbird_wait_event ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_trans

fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — のエイリアス ibase_trans()

説明

この関数は次の関数のエイリアスです。 ibase_trans().


のエイリアス ibase_wait_event

  • ≪ fbird_trans
  • ibase_add_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • のエイリアス ibase_wait_event

fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — のエイリアス ibase_wait_event()

説明

この関数は次の関数のエイリアスです。 ibase_wait_event().

参考

  • fbird_set_event_handler() - のエイリアス ibase_set_event_handler
  • fbird_free_event_handler() - のエイリアス ibase_free_event_handler


Add a user to a security database

  • ≪ fbird_wait_event
  • ibase_affected_rows ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Add a user to a security database

ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Add a user to a security database

説明

ibase_add_user(
resource $service_handle,
string $user_name,
string $password,
string $first_name = ?,
string $middle_name = ?,
string $last_name = ?
): bool

パラメータ

service_handle

The handle on the database server service.

user_name

The login name of the new database user.

password

The password of the new user.

first_name

The first name of the new database user.

middle_name

The middle name of the new database user.

last_name

The last name of the new database user.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_modify_user() - Modify a user to a security database
  • ibase_delete_user() - Delete a user from a security database


直近のクエリで変更された行の数を返す

  • ≪ ibase_add_user
  • ibase_backup ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 直近のクエリで変更された行の数を返す

ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — 直近のクエリで変更された行の数を返す

説明

ibase_affected_rows(resource $link_identifier = ?): int

この関数は、link_identifier で指定された トランザクション内で実行された直近のクエリ(INSERT、UPDATE あるいは DELETE)によって変更された行の数を返します。

パラメータ

link_identifier

トランザクションのコンテキスト。 link_identifier が接続リソースの場合、 そのデフォルトのトランザクションが使用されます。

戻り値

変更された行数を整数値で返します。

参考

  • ibase_query() - InterBase データベースでクエリを実行する
  • ibase_execute() - 準備されたクエリを実行する


Initiates a backup task in the service manager and returns immediately

  • ≪ ibase_affected_rows
  • ibase_blob_add ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Initiates a backup task in the service manager and returns immediately

ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Initiates a backup task in the service manager and returns immediately

説明

ibase_backup(
resource $service_handle,
string $source_db,
string $dest_file,
int $options = 0,
bool $verbose = false
): mixed

This function passes the arguments to the (remote) database server. There it starts a new backup process. Therefore you won't get any responses.

パラメータ

service_handle

A previously opened connection to the database server.

source_db

The absolute file path to the database on the database server. You can also use a database alias.

dest_file

The path to the backup file on the database server.

options

Additional options to pass to the database server for backup. The options parameter can be a combination of the following constants: IBASE_BKP_IGNORE_CHECKSUMS, IBASE_BKP_IGNORE_LIMBO, IBASE_BKP_METADATA_ONLY, IBASE_BKP_NO_GARBAGE_COLLECT, IBASE_BKP_OLD_DESCRIPTIONS, IBASE_BKP_NON_TRANSPORTABLE or IBASE_BKP_CONVERT. Read the section about 定義済み定数 for further information.

verbose

Since the backup process is done on the database server, you don't have any chance to get its output. This argument is useless.

戻り値

成功した場合に true を、失敗した場合に false を返します。

Since the backup process is done on the (remote) server, this function just passes the arguments to it. While the arguments are legal, you won't get false.

例

例1 ibase_backup() example

<?php

// Attach to database server by ip address and port
$service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

// Start the backup process on database server
// Backup employee database using full path to /srv/backup/employees.fbk
// Don't use any special arguments
ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

// Free the attached connection
ibase_service_detach ($service);
?>

例2 ibase_backup() example with arguments

<?php

// Attach to database server by name and default port
$service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

// Start the backup process on database server
// Backup employee database using alias to /srv/backup/employees.fbk.
// Backup only the metadata. Don't create a transportable backup.
ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

// Free the attached connection
ibase_service_detach ($service);
?>

参考

  • ibase_restore() - Initiates a restore task in the service manager and returns immediately


生成された blob にデータを追加する

  • ≪ ibase_backup
  • ibase_blob_cancel ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 生成された blob にデータを追加する

ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — 生成された blob にデータを追加する

説明

ibase_blob_add(resource $blob_handle, string $data): void

ibase_blob_add() は、 ibase_blob_create() で作成した blob にデータを追加します。

パラメータ

blob_handle

ibase_blob_create() でオープンした blob ハンドル。

data

追加するデータ。

戻り値

値を返しません。

参考

  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_create() - データを追加するために blob を生成する
  • ibase_blob_import() - blob を生成し、ファイルをコピーし、閉じる


blob の生成を取り消す

  • ≪ ibase_blob_add
  • ibase_blob_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob の生成を取り消す

ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — blob の生成を取り消す

説明

ibase_blob_cancel(resource $blob_handle): bool

この関数は、まだ ibase_blob_close() で閉じられていない場合に BLOB を捨てます。

パラメータ

blob_handle

ibase_blob_create() でオープンした blob ハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_blob_close() - blob を閉じる
  • ibase_blob_create() - データを追加するために blob を生成する
  • ibase_blob_import() - blob を生成し、ファイルをコピーし、閉じる


blob を閉じる

  • ≪ ibase_blob_cancel
  • ibase_blob_create ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob を閉じる

ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — blob を閉じる

説明

ibase_blob_close(resource $blob_handle): mixed

この関数は、読み込み用に ibase_blob_open() でオープンされたかあるいは書き込み用に ibase_blob_create() でオープンされた BLOB を閉じます。

パラメータ

blob_handle

ibase_blob_create() あるいは ibase_blob_open() でオープンした blob ハンドル。

戻り値

BLOB が読み込み用であった場合、 この関数は成功時に true を返します。一方 BLOB が書き込み用であった場合、 データベースによって割り当てられた BLOB ID を文字列で返します。 失敗した場合は、この関数は false を返します。

参考

  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_open() - データの一部を取得するために blob をオープンする


データを追加するために blob を生成する

  • ≪ ibase_blob_close
  • ibase_blob_echo ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データを追加するために blob を生成する

ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — データを追加するために blob を生成する

説明

ibase_blob_create(resource $link_identifier = null): resource|false

ibase_blob_create() は、 データを書き込むための新しい BLOB を生成します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

戻り値

ibase_blob_add() で使用するための BLOB ハンドルを返します。失敗した場合に false を返します。

参考

  • ibase_blob_add() - 生成された blob にデータを追加する
  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_import() - blob を生成し、ファイルをコピーし、閉じる


ブラウザに blob の内容を出力する

  • ≪ ibase_blob_create
  • ibase_blob_get ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • ブラウザに blob の内容を出力する

ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — ブラウザに blob の内容を出力する

説明

ibase_blob_echo(string $blob_id): bool
ibase_blob_echo(resource $link_identifier, string $blob_id): bool

この関数は読み込み用に BLOB をオープンし、直接その内容を標準出力 (たいていの場合はブラウザ) に送信します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

blob_id

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_blob_open() - データの一部を取得するために blob をオープンする
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_get() - オープンした blob から len バイト分のデータを取得する


オープンした blob から len バイト分のデータを取得する

  • ≪ ibase_blob_echo
  • ibase_blob_import ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • オープンした blob から len バイト分のデータを取得する

ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — オープンした blob から len バイト分のデータを取得する

説明

ibase_blob_get(resource $blob_handle, int $len): string

この関数は、ibase_blob_open() によって読み込み用に オープンした BLOB から最大 len バイトを返します。

注意:

ibase_blob_create() で書き込み用にオープンした BLOB から読み込むことはできません。

パラメータ

blob_handle

ibase_blob_open() でオープンした BLOB ハンドル。

len

返されるデータのサイズ。

戻り値

BLOB から最大 len バイトを返します。 失敗した場合は false を返します。

例

例1 ibase_blob_get() の例

<?php
$result = ibase_query("SELECT blob_value FROM table");
$data = ibase_fetch_object($result);
$blob_data = ibase_blob_info($data->BLOB_VALUE);
$blob_hndl = ibase_blob_open($data->BLOB_VALUE);
echo ibase_blob_get($blob_hndl, $blob_data[0]);
?>
この例では 'ibase_blob_echo($data->BLOB_VALUE)' が行う以上のことは 行っていませんが、結果を変数に代入して操作する方法を示しています。

参考

  • ibase_blob_open() - データの一部を取得するために blob をオープンする
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_echo() - ブラウザに blob の内容を出力する


blob を生成し、ファイルをコピーし、閉じる

  • ≪ ibase_blob_get
  • ibase_blob_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob を生成し、ファイルをコピーし、閉じる

ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — blob を生成し、ファイルをコピーし、閉じる

説明

ibase_blob_import(resource $link_identifier, resource $file_handle): string
ibase_blob_import(resource $file_handle): string

この関数は BLOB を作成し、その中にファイルのすべての内容を読み込み、 それを閉じ、関連付けられた BLOB ID を返します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

file_handle

fopen() が返すファイルハンドル。

戻り値

成功した場合に BLOB の ID、エラー時に false を返します。

例

例1 ibase_blob_import() の例

<?php
$dbh = ibase_connect($host, $username, $password);
$filename = '/tmp/bar';

$fd = fopen($filename, 'r');
if ($fd) {

$blob = ibase_blob_import($dbh, $fd);
fclose($fd);

if (!is_string($blob)) {
// インポートに失敗しました
} else {
$query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
$prepared = ibase_prepare($dbh, $query);
if (!ibase_execute($prepared, $blob)) {
// レコードの挿入に失敗しました
}
}
} else {
// データファイルをオープンできませんでした
}
?>

参考

  • ibase_blob_add() - 生成された blob にデータを追加する
  • ibase_blob_cancel() - blob の生成を取り消す
  • ibase_blob_close() - blob を閉じる
  • ibase_blob_create() - データを追加するために blob を生成する


blob の長さと他の便利な情報を返す

  • ≪ ibase_blob_import
  • ibase_blob_open ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • blob の長さと他の便利な情報を返す

ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — blob の長さと他の便利な情報を返す

説明

ibase_blob_info(resource $link_identifier, string $blob_id): array
ibase_blob_info(string $blob_id): array

BLOB の長さや他の便利な情報を返します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

blob_id

BLOB の ID。

戻り値

BLOB についての情報を含む配列を返します。返される情報には BLOB の長さ・含んでいるセグメントの数・最大のセグメントのサイズ・ ストリーム BLOB とセグメント BLOB のどちらであるかなどがあります。


データの一部を取得するために blob をオープンする

  • ≪ ibase_blob_info
  • ibase_close ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データの一部を取得するために blob をオープンする

ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — データの一部を取得するために blob をオープンする

説明

ibase_blob_open(resource $link_identifier, string $blob_id): resource|false
ibase_blob_open(string $blob_id): resource|false

既存の BLOB を読み込み用にオープンします。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

blob_id

BLOB の ID。

戻り値

後で ibase_blob_get() とともに使用する BLOB ハンドルを返します。失敗した場合に false を返します。

参考

  • ibase_blob_close() - blob を閉じる
  • ibase_blob_echo() - ブラウザに blob の内容を出力する
  • ibase_blob_get() - オープンした blob から len バイト分のデータを取得する


InterBase データベースへの接続を閉じる

  • ≪ ibase_blob_open
  • ibase_commit ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースへの接続を閉じる

ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — InterBase データベースへの接続を閉じる

説明

ibase_close(resource $connection_id = null): bool

ibase_connect() から返された接続 ID が指す InterBase データベースへのリンクを閉じます。 接続 ID が省略された場合、最後にオープンされたリンクが仮定されます。 リンクにおけるデフォルトのトランザクションがコミットされ、 他のトランザクションはロールバックされます。

パラメータ

connection_id

ibase_connect() が返す InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_connect() - データベースへの接続をオープンする
  • ibase_pconnect() - InterBase データベースへの持続的接続をオープンする


トランザクションをコミットする

  • ≪ ibase_close
  • ibase_commit_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションをコミットする

ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — トランザクションをコミットする

説明

ibase_commit(resource $link_or_trans_identifier = null): bool

トランザクションをコミットします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクの デフォルトのトランザクションをコミットします。引数が接続 ID であった場合は、対応する接続のデフォルトのトランザクションを コミットします。引数がトランザクション ID であった場合は、 対応するトランザクションがコミットされます。

戻り値

成功した場合に true を、失敗した場合に false を返します。


トランザクションを閉じずにコミットする

  • ≪ ibase_commit
  • ibase_connect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションを閉じずにコミットする

ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — トランザクションを閉じずにコミットする

説明

ibase_commit_ret(resource $link_or_trans_identifier = null): bool

トランザクションを閉じずにコミットします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをコミットします。引数が接続 ID だった場合、対応する 接続のデフォルトのトランザクションをコミットします。引数が トランザクション ID だった場合、対応するトランザクションをコミットします。 トランザクションコンテキストはそのまま維持され、このトランザクション内で 実行された文は取り消されません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


データベースへの接続をオープンする

  • ≪ ibase_commit_ret
  • ibase_db_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースへの接続をオープンする

ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — データベースへの接続をオープンする

説明

ibase_connect(
string $database = ?,
string $username = ?,
string $password = ?,
string $charset = ?,
int $buffers = ?,
int $dialect = ?,
string $role = ?,
int $sync = ?
): resource

Firebird/InterBase サーバーへの接続を確立します。

同じ引数で ibase_connect() が再度コールされた場合、 新規のリンクは作成されず、代わりに既にオープンされているリンクの リンク ID が返されます。 ibase_close() を明示的にコールしない限り、 サーバーへのリンクはスクリプトの実行終了時に閉じられます。

パラメータ

database

databaseは接続するサーバー上のデータベース ファイルへの正しいパスである必要があります。ローカルなサーバーへの 接続でない場合、使用する接続プロトコルに応じてこの引数の前に 'hostname:' (TCP/IP)、'hostname/port:' (カスタム TCP ポート上での interbase サーバーでの TCP/IP)、'//hostname/' (NetBEUI) のどれかをつける必要があります。

username

ユーザー名。php.ini ディレクティブ ibase.default_user で設定します。

password

username のパスワード。 php.ini ディレクティブ ibase.default_password で設定します。

charset

charset はデータベースに関するデフォルトの文字セットです。

buffers

buffers はサーバー側のキャッシュに確保されるデータベースバッファの数です。0 または省略された場合、サーバーはデフォルト値を用います。

dialect

dialect は、接続時に実行される全ての命令に 関する SQL 方言のデフォルト値を選択し、デフォルトではクライアント ライブラリでサポートされる方言のうち、最高位のものになります。

role

InterBase 5 以降でのみ有効です。

sync

戻り値

成功した場合に Firebird/InterBase リンク ID、エラー時に false を返します。

エラー / 例外

この関数を使用して ibase_query() をコールした後に "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" のようなエラーが発生した場合 (たとえばアクセント記号つきの文字を使用した場合などに発生します)、 文字セットを指定する必要があります (例: ISO8859_1 あるいは現在の文字セット)。

例

例1 ibase_connect() の例

<?php
$host = 'localhost:/path/to/your.gdb';

$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
echo $row->email, "\n";
}
ibase_free_result($sth);
ibase_close($dbh);
?>

参考

  • ibase_pconnect() - InterBase データベースへの持続的接続をオープンする
  • ibase_close() - InterBase データベースへの接続を閉じる


データベースについての統計情報を要求する

  • ≪ ibase_connect
  • ibase_delete_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースについての統計情報を要求する

ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — データベースについての統計情報を要求する

説明

ibase_db_info(
resource $service_handle,
string $db,
int $action,
int $argument = 0
): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


Delete a user from a security database

  • ≪ ibase_db_info
  • ibase_drop_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Delete a user from a security database

ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Delete a user from a security database

説明

ibase_delete_user(resource $service_handle, string $user_name): bool

パラメータ

service_handle

The handle on the database server service.

user_name

The login name of the user you want to delete from the database.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_add_user() - Add a user to a security database
  • ibase_modify_user() - Modify a user to a security database


データベースを削除する

  • ≪ ibase_delete_user
  • ibase_errcode ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースを削除する

ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — データベースを削除する

説明

ibase_drop_db(resource $connection = null): bool

この関数は、ibase_connect() あるいは ibase_pconnect() のいずれかによってオープンされたデータベースを削除します。 データベースがクローズされ、サーバーから削除されます。

パラメータ

connection

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_connect() - データベースへの接続をオープンする
  • ibase_pconnect() - InterBase データベースへの持続的接続をオープンする


エラーコードを返す

  • ≪ ibase_drop_db
  • ibase_errmsg ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • エラーコードを返す

ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — エラーコードを返す

説明

ibase_errcode(): int

直近の InterBase 関数のコールによって得られたエラーコードを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーコードを表す整数、あるいはエラーが発生しなかった場合は false を返します。

参考

  • ibase_errmsg() - エラーメッセージを返す


エラーメッセージを返す

  • ≪ ibase_errcode
  • ibase_execute ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • エラーメッセージを返す

ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — エラーメッセージを返す

説明

ibase_errmsg(): string

直近の InterBase 関数コールの結果として得られるエラーメッセージを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーメッセージを表す文字列、あるいはエラーが発生しなかった場合は false を返します。

参考

  • ibase_errcode() - エラーコードを返す


準備されたクエリを実行する

  • ≪ ibase_errmsg
  • ibase_fetch_assoc ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 準備されたクエリを実行する

ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — 準備されたクエリを実行する

説明

ibase_execute(resource $query, mixed ...$values): resource

ibase_prepare() で準備したクエリを実行します。

いくつかのパラメータが変わるだけで同じクエリを 複数回実行する場合には、この関数は ibase_query() を使用するよりもずっと効率的です。

パラメータ

query

ibase_prepare() で準備した InterBase クエリ。

values

戻り値

クエリがエラーを発生させた場合は false を返します。 クエリが成功し、結果セット(空のセットとなる可能性もありえます)を 返した場合(SELECT クエリなど)は結果 ID を返します。クエリが成功し、 結果セットが返されなかった場合は true を返します。

注意:

この関数はクエリによって変更された行の数を 返します(行を変更するクエリで、結果が 0 より大きかった場合)。 クエリは成功したが、どの行も変更されなかった場合(例: 存在しない 行に対する UPDATE)は true を返します。

例

例1 ibase_execute() の例

<?php

$dbh = ibase_connect($host, $username, $password);

$updates = array(
1 => 'Eric',
5 => 'Filip',
7 => 'Larry'
);

$query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

foreach ($updates as $baz => $bar) {
ibase_execute($query, $bar, $baz);
}

?>

参考

  • ibase_query() - InterBase データベースでクエリを実行する


クエリの結果から、行を連想配列として取得する

  • ≪ ibase_execute
  • ibase_fetch_object ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • クエリの結果から、行を連想配列として取得する

ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — クエリの結果から、行を連想配列として取得する

説明

ibase_fetch_assoc(resource $result, int $fetch_flag = 0): array

クエリの結果の行を連想配列で返します。

ibase_fetch_assoc() は、 result から結果を 1 行取得します。 同じフィールド名のカラムが 2 つ以上存在する場合、最後のカラムが 優先されます。同名のその他のカラムにアクセスするには、 ibase_fetch_row() を使用して数値添字を用いるか あるいはクエリ中でカラムに別名をつけます。

パラメータ

result

結果ハンドル。

fetch_flag

fetch_flag は、定数 IBASE_TEXT および IBASE_UNIXTIME を論理和で指定します。IBASE_TEXT を渡すと、BLOB ID のかわりに BLOB の内容自体を返します。IBASE_UNIXTIME を渡すと、日付/時刻の値を文字列ではなく Unix タイムスタンプで返します。

戻り値

ibase_fetch_assoc() は、取得した行に対応する連想配列を返します。 続けてコールすると、結果セットの次の行を返し、 行がもうない場合には false を返します。

参考

  • ibase_fetch_row() - InterBase データベースから 1 行分の結果を取得する
  • ibase_fetch_object() - InterBase データベースからオブジェクトを得る


InterBase データベースからオブジェクトを得る

  • ≪ ibase_fetch_assoc
  • ibase_fetch_row ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースからオブジェクトを得る

ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — InterBase データベースからオブジェクトを得る

説明

ibase_fetch_object(resource $result_id, int $fetch_flag = 0): object

指定した結果 ID から、行を疑似オブジェクトとして取得します。

ibase_fetch_object() を続けてコールすると、 結果セットの次の行を返します。

パラメータ

result_id

ibase_query() あるいは ibase_execute() で取得した InterBase 結果 ID。

fetch_flag

fetch_flag は、定数 IBASE_TEXT および IBASE_UNIXTIME を論理和で指定します。IBASE_TEXT を渡すと、BLOB ID のかわりに BLOB の内容自体を返します。IBASE_UNIXTIME を渡すと、日付/時刻の値を文字列ではなく Unix タイムスタンプで返します。

戻り値

次の行の情報を含むオブジェクト、 あるいは行がもうない場合には false を返します。

例

例1 ibase_fetch_object() の例

<?php
$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
echo $row->email . "\n";
}
ibase_close($dbh);
?>

参考

  • ibase_fetch_row() - InterBase データベースから 1 行分の結果を取得する
  • ibase_fetch_assoc() - クエリの結果から、行を連想配列として取得する


InterBase データベースから 1 行分の結果を取得する

  • ≪ ibase_fetch_object
  • ibase_field_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースから 1 行分の結果を取得する

ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — InterBase データベースから 1 行分の結果を取得する

説明

ibase_fetch_row(resource $result_identifier, int $fetch_flag = 0): array

ibase_fetch_row() は、指定した result_identifier に関連付けられた結果からデータを 1 行取得します。

ibase_fetch_row() を続けてコールすると、 結果セットの次の行を返します。行がもうない場合には false を返します。

パラメータ

result_identifier

InterBase 結果 ID。

fetch_flag

fetch_flag は、定数 IBASE_TEXT および IBASE_UNIXTIME を論理和で指定します。IBASE_TEXT を渡すと、BLOB ID のかわりに BLOB の内容自体を返します。IBASE_UNIXTIME を渡すと、日付/時刻の値を文字列ではなく Unix タイムスタンプで返します。

戻り値

取得した行に対応する配列を返します。行がもうない場合には false を返します。 結果の各行は配列のオフセットに格納され、 このオフセットは 0 から始まります。

参考

  • ibase_fetch_assoc() - クエリの結果から、行を連想配列として取得する
  • ibase_fetch_object() - InterBase データベースからオブジェクトを得る


フィールドに関する情報を得る

  • ≪ ibase_fetch_row
  • ibase_free_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • フィールドに関する情報を得る

ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — フィールドに関する情報を得る

説明

ibase_field_info(resource $result, int $field_number): array

select クエリが実行された後、フィールドに関する情報を配列として返します。

パラメータ

result

InterBase 結果 ID。

field_number

フィールドのオフセット。

戻り値

配列を返します。配列に含まれるキーは name、 alias、relation、 length そして type です。

例

例1 ibase_field_info() の例

<?php
$rs = ibase_query("SELECT * FROM tablename");
$coln = ibase_num_fields($rs);
for ($i = 0; $i < $coln; $i++) {
$col_info = ibase_field_info($rs, $i);
echo "name: ". $col_info['name']. "\n";
echo "alias: ". $col_info['alias']. "\n";
echo "relation: ". $col_info['relation']. "\n";
echo "length: ". $col_info['length']. "\n";
echo "type: ". $col_info['type']. "\n";
}
?>

参考

  • ibase_num_fields() - 結果セットにおけるフィールド数を得る


登録済みのイベントハンドラをキャンセルする

  • ≪ ibase_field_info
  • ibase_free_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 登録済みのイベントハンドラをキャンセルする

ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — 登録済みのイベントハンドラをキャンセルする

説明

ibase_free_event_handler(resource $event): bool

この関数は、event で指定した登録済みの イベントハンドラをキャンセルします。イベントに対応して登録されていた コールバック関数は、もはやコールされません。

パラメータ

event

ibase_set_event_handler() で作成したイベントリソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_set_event_handler() - イベントが発生した際にコールされるコールバック関数を登録する


プリペアドクエリにより確保されたメモリを解放する

  • ≪ ibase_free_event_handler
  • ibase_free_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • プリペアドクエリにより確保されたメモリを解放する

ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — プリペアドクエリにより確保されたメモリを解放する

説明

ibase_free_query(resource $query): bool

プリペアドクエリを解放します。

パラメータ

query

ibase_prepare() で準備したクエリ。

戻り値

成功した場合に true を、失敗した場合に false を返します。


結果セットを解放する

  • ≪ ibase_free_query
  • ibase_gen_id ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 結果セットを解放する

ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — 結果セットを解放する

説明

ibase_free_result(resource $result_identifier): bool

結果セットを解放します。

パラメータ

result_identifier

ibase_query() あるいは ibase_execute() で作成した結果セット。

戻り値

成功した場合に true を、失敗した場合に false を返します。


指定した名前のジェネレータをひとつ加算し、その新しい値を返す

  • ≪ ibase_free_result
  • ibase_maintain_db ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 指定した名前のジェネレータをひとつ加算し、その新しい値を返す

ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — 指定した名前のジェネレータをひとつ加算し、その新しい値を返す

説明

ibase_gen_id(string $generator, int $increment = 1, resource $link_identifier = null): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

戻り値

新しいジェネレータの値を整数で返します。値が大きくなりすぎた場合は文字列で返します。


データベースサーバーでメンテナンスコマンドを実行する

  • ≪ ibase_gen_id
  • ibase_modify_user ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースサーバーでメンテナンスコマンドを実行する

ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — データベースサーバーでメンテナンスコマンドを実行する

説明

ibase_maintain_db(
resource $service_handle,
string $db,
int $action,
int $argument = 0
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。


Modify a user to a security database

  • ≪ ibase_maintain_db
  • ibase_name_result ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Modify a user to a security database

ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modify a user to a security database

説明

ibase_modify_user(
resource $service_handle,
string $user_name,
string $password,
string $first_name = ?,
string $middle_name = ?,
string $last_name = ?
): bool

パラメータ

service_handle

The handle on the database server service.

user_name

The login name of the database user to modify.

password

The user's new password.

first_name

The user's new first name.

middle_name

The user's new middle name.

last_name

The user's new last name.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ibase_add_user() - Add a user to a security database
  • ibase_delete_user() - Delete a user from a security database


結果セットに名前を割り当てる

  • ≪ ibase_modify_user
  • ibase_num_fields ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 結果セットに名前を割り当てる

ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — 結果セットに名前を割り当てる

説明

ibase_name_result(resource $result, string $name): bool

この関数は、結果セットに新しい名前を割り当てます。この名前は、後で UPDATE|DELETE ... WHERE CURRENT OF name 文で使用します。

パラメータ

result

InterBase 結果セット。

name

割り当てる名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ibase_name_result() の例

<?php
$result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
ibase_name_result($result, "my_cursor");

$updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

for ($i = 0; ibase_fetch_row($result); ++$i) {
ibase_execute($updateqry, $i);
}
?>

参考

  • ibase_prepare() - Prepare a query for later binding of parameter placeholders and execution
  • ibase_execute() - 準備されたクエリを実行する


結果セットにおけるフィールド数を得る

  • ≪ ibase_name_result
  • ibase_num_params ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • 結果セットにおけるフィールド数を得る

ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — 結果セットにおけるフィールド数を得る

説明

ibase_num_fields(resource $result_id): int

結果セットにおけるフィールド数を整数として返します。

パラメータ

result_id

InterBase 結果 ID。

戻り値

フィールドの数を整数値で返します。

例

例1 ibase_num_fields() の例

<?php
$rs = ibase_query("SELECT * FROM tablename");
$coln = ibase_num_fields($rs);
for ($i = 0; $i < $coln; $i++) {
$col_info = ibase_field_info($rs, $i);
echo "name: " . $col_info['name'] . "\n";
echo "alias: " . $col_info['alias'] . "\n";
echo "relation: " . $col_info['relation'] . "\n";
echo "length: " . $col_info['length'] . "\n";
echo "type: " . $col_info['type'] . "\n";
}
?>

参考

  • ibase_field_info() - フィールドに関する情報を得る


プリペアドクエリのパラメータ数を返す

  • ≪ ibase_num_fields
  • ibase_param_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • プリペアドクエリのパラメータ数を返す

ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — プリペアドクエリのパラメータ数を返す

説明

ibase_num_params(resource $query): int

この関数は、query で指定した プリペアドクエリのパラメータの数を返します。 ibase_execute() をコールする際に、 この数と同じだけのバインド引数が割り当てられている必要があります。

パラメータ

query

プリペアドクエリのハンドル。

戻り値

パラメータの数を整数値で返します。

参考

  • ibase_prepare() - Prepare a query for later binding of parameter placeholders and execution
  • ibase_param_info() - プリペアドクエリのパラメータに関する情報を返す


プリペアドクエリのパラメータに関する情報を返す

  • ≪ ibase_num_params
  • ibase_pconnect ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • プリペアドクエリのパラメータに関する情報を返す

ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — プリペアドクエリのパラメータに関する情報を返す

説明

ibase_param_info(resource $query, int $param_number): array

クエリが準備された後に、パラメータについての情報を配列で返します。

パラメータ

query

InterBase プリペアドクエリのハンドル。

param_number

パラメータのオフセット。

戻り値

配列を返します。配列に含まれるキーは name、 alias、relation、 length および type となります。

参考

  • ibase_field_info() - フィールドに関する情報を得る
  • ibase_num_params() - プリペアドクエリのパラメータ数を返す


InterBase データベースへの持続的接続をオープンする

  • ≪ ibase_param_info
  • ibase_prepare ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースへの持続的接続をオープンする

ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — InterBase データベースへの持続的接続をオープンする

説明

ibase_pconnect(
string $database = ?,
string $username = ?,
string $password = ?,
string $charset = ?,
int $buffers = ?,
int $dialect = ?,
string $role = ?,
int $sync = ?
): resource

InterBase データベースへの持続的な接続をオープンします。

ibase_pconnect() の動作は ibase_connect() と非常に似ていますが、 大きな違いが二つあります。

まず、この関数は接続時に同じパラメータで既にオープンされている (持続的)リンクを探します。見つかった場合、新規接続をオープンする 代わりにそのリンクの ID が返されます。

2 番目の違いとしては、InterBase サーバーへの接続は スクリプト終了時にも閉じられないということです。 代わりに、そのリンクは今後使用するためにオープンされたままとなります (ibase_close() は ibase_pconnect() によりオープンされたリンクを閉じません)。 このため、この型のリンクは'持続的(persistent)'と呼ばれます。

パラメータ

database

databaseは接続するサーバー上のデータベース ファイルへの正しいパスである必要があります。ローカルなサーバーへの 接続でない場合、使用する接続プロトコルに応じてこの引数の前に' hostname:' (TCP/IP)、'//hostname/' (NetBEUI)、'hostname@' (IPX/SPX)のどれかをつける必要があります。

username

ユーザー名。php.ini ディレクティブ ibase.default_user で設定します。

password

username のパスワード。 php.ini ディレクティブ ibase.default_password で設定します。

charset

charset はデータベースに関するデフォルトの文字セットです。

buffers

buffers はサーバー側のキャッシュに確保されるデータベースバッファの数です。0 または省略された場合、サーバーはデフォルト値を用います。

dialect

dialect は、接続時に実行される全ての命令に 関する SQL 方言のデフォルト値を選択し、デフォルトではクライアント ライブラリでサポートされる方言のうち、最高位のものになります。 InterBase 6 以降でのみ有効です。

role

InterBase 5 以降でのみ有効です。

sync

戻り値

成功した場合に InterBase リンク ID、エラー時に false を返します。

参考

  • ibase_close() - InterBase データベースへの接続を閉じる
  • ibase_connect() - データベースへの接続をオープンする


Prepare a query for later binding of parameter placeholders and execution

  • ≪ ibase_pconnect
  • ibase_query ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Prepare a query for later binding of parameter placeholders and execution

ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prepare a query for later binding of parameter placeholders and execution

説明

ibase_prepare(string $query): resource
ibase_prepare(resource $link_identifier, string $query): resource
ibase_prepare(resource $link_identifier, string $trans, string $query): resource

Prepare a query for later binding of parameter placeholders and execution (via ibase_execute()).

パラメータ

query

An InterBase query.

link_identifier

An InterBase link identifier returned from ibase_connect(). If omitted, the last opened link is assumed.

trans

An InterBase transaction handle the query should be associated with. If omitted, the default transaction of the connection is assumed.

戻り値

Returns a prepared query handle, or false on error.


InterBase データベースでクエリを実行する

  • ≪ ibase_prepare
  • ibase_restore ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • InterBase データベースでクエリを実行する

ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — InterBase データベースでクエリを実行する

説明

ibase_query(resource $link_identifier = ?, string $query, int $bind_args = ?): resource

InterBase データベース上でクエリを実行します。

パラメータ

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

query

InterBase クエリ。

bind_args

戻り値

クエリが失敗した場合、false を返します。成功した場合、 (SELECT クエリのような) 結果の行がある場合、結果 ID を返します。 クエリが成功し、結果がない場合は true を返します。

注意:

PHP 5.0.0 以降では、INSERT・UPDATE・DELETE 文に対してはこの関数は 変更された行数を返します。後方互換性を確保するため、これらの文で クエリが成功したものの 1 行も更新されなかった場合には true を返します。

エラー / 例外

ibase_query() の実行後に "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" のようなエラーに遭遇した場合 (アクセント記号つきの文字を使用した場合などに起こります)、 文字セットを(ISO8859_1 あるいは現在の文字セットに)設定する必要があります。

例

例1 ibase_query() の例

<?php

$host = 'localhost:/path/to/your.gdb';

$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';

$sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

?>

参考

  • ibase_errmsg() - エラーメッセージを返す
  • ibase_fetch_row() - InterBase データベースから 1 行分の結果を取得する
  • ibase_fetch_object() - InterBase データベースからオブジェクトを得る
  • ibase_free_result() - 結果セットを解放する


Initiates a restore task in the service manager and returns immediately

  • ≪ ibase_query
  • ibase_rollback ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • Initiates a restore task in the service manager and returns immediately

ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Initiates a restore task in the service manager and returns immediately

説明

ibase_restore(
resource $service_handle,
string $source_file,
string $dest_db,
int $options = 0,
bool $verbose = false
): mixed

This function passes the arguments to the (remote) database server. There it starts a new restore process. Therefore you won't get any responses.

パラメータ

service_handle

A previously opened connection to the database server.

source_file

The absolute path on the server where the backup file is located.

dest_db

The path to create the new database on the server. You can also use database alias.

options

Additional options to pass to the database server for restore. The options parameter can be a combination of the following constants: IBASE_RES_DEACTIVATE_IDX, IBASE_RES_NO_SHADOW, IBASE_RES_NO_VALIDITY, IBASE_RES_ONE_AT_A_TIME, IBASE_RES_REPLACE, IBASE_RES_CREATE, IBASE_RES_USE_ALL_SPACE, IBASE_PRP_PAGE_BUFFERS, IBASE_PRP_SWEEP_INTERVAL, IBASE_RES_CREATE. Read the section about 定義済み定数 for further information.

verbose

Since the restore process is done on the database server, you don't have any chance to get its output. This argument is useless.

戻り値

成功した場合に true を、失敗した場合に false を返します。

Since the restore process is done on the (remote) server, this function just passes the arguments to it. While the arguments are legal, you won't get false.

例

例1 ibase_restore() example

<?php

// Attach to database server by ip address and port
$service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

// Start the restore process on database server
// Restore employee backup to the new emps.fdb database
// Don't use any special arguments
ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

// Free the attached connection
ibase_service_detach ($service);
?>

例2 ibase_restore() example with arguments

<?php

// Attach to database server by name and default port
$service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

// Start the restore process on database server
// Restore to employee database using alias.
// Restore without indixes. Replace existing database.
ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

// Free the attached connection
ibase_service_detach ($service);
?>

参考

  • ibase_backup() - Initiates a backup task in the service manager and returns immediately


トランザクションをロールバックする

  • ≪ ibase_restore
  • ibase_rollback_ret ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションをロールバックする

ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — トランザクションをロールバックする

説明

ibase_rollback(resource $link_or_trans_identifier = null): bool

トランザクションをロールバックします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをロールバックします。引数として接続 ID が渡された場合、 対応する接続のデフォルトのトランザクションをロールバックします。 引数としてトランザクション ID が渡された場合、対応するトランザクションを ロールバックします。

戻り値

成功した場合に true を、失敗した場合に false を返します。


トランザクションを閉じずにロールバックする

  • ≪ ibase_rollback
  • ibase_server_info ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションを閉じずにロールバックする

ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — トランザクションを閉じずにロールバックする

説明

ibase_rollback_ret(resource $link_or_trans_identifier = null): bool

トランザクションを閉じずにロールバックします。

パラメータ

link_or_trans_identifier

引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをロールバックします。引数が接続 ID だった場合、対応する 接続のデフォルトのトランザクションをロールバックします。引数が トランザクション ID だった場合、対応するトランザクションをロールバックします。 トランザクションコンテキストはそのまま維持され、このトランザクション内で 実行された文は取り消されません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


データベースサーバーについての情報を要求する

  • ≪ ibase_rollback_ret
  • ibase_service_attach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースサーバーについての情報を要求する

ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — データベースサーバーについての情報を要求する

説明

ibase_server_info(resource $service_handle, int $action): string

パラメータ

service_handle

データベースサーバーへの接続

action

有効な定数

戻り値

コンテクストに応じて様々な型の値を返します。

例

例1 ibase_service_attach() の例

<?php
// リモートの Firebird サーバーにアタッチする
if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

// アタッチ成功

// 情報を出力
echo "Server version: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
echo "Server implementation: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
echo "Server users: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
echo "Server directory: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
echo "Server lock path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
echo "Server lib path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
echo "Path of user db: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
echo "Established connections: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

// サーバーからデタッチ(切断)
ibase_service_detach($service);

}
else {
// エラー時にはメッセージを出力
$conn_error = ibase_errmsg();
die($conn_error);
}
?>

上の例の出力は以下となります。

Server version: LI-V3.0.4.33054 Firebird 3.0
Server implementation: Firebird/Linux/AMD/Intel/x64
Server users: Array
(
    [0] => Array
        (
            [user_name] => SYSDBA
            [first_name] => Sql
            [middle_name] => Server
            [last_name] => Administrator
            [user_id] => 0
            [group_id] => 0
        )

)

Server directory: /etc/firebird/
Server lock path: /tmp/firebird/
Server lib path: /usr/lib64/firebird/lib/
Path of user db: /var/lib/firebird/secdb/security3.fdb
Established connections: Array
(
    [attachments] => 3
    [databases] => 2
    [0] => /srv/firebird/poss.fdb
    [1] => /srv/firebird/employees.fdb
)


サービスマネージャに接続する

  • ≪ ibase_server_info
  • ibase_service_detach ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • サービスマネージャに接続する

ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — サービスマネージャに接続する

説明

ibase_service_attach(string $host, string $dba_username, string $dba_password): resource|false

パラメータ

host

データベースホストのIPアドレスまたは名前。 '/' とポート番号を追加することでポートを定義できます。 ポートが指定されない場合、3050 が使われます。

dba_username

有効なユーザー名

dba_password

ユーザーのパスワード

戻り値

成功時には、Interbase / Firebird へのリンクの識別子を返します。 失敗した場合に false を返します

例

例1 ibase_service_attach() の例

<?php
// リモートの Firebird サーバーにIPアドレスでアタッチ
if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

// アタッチ成功
// サーバーのバージョン('LI-V3.0.4.33054 Firebird 3.0'のようなもの)を取得
$server_version = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

// サーバーの実装を取得 ('Firebird/Linux/AMD/Intel/x64' のようなもの)
$server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

// サーバーからデタッチ(切断)
ibase_service_detach($service);

// 情報を出力
echo "Server version: " . $server_version . "<br/>";
echo "Server implementation: " . $server_implementation;
}
else {
// エラー時にはメッセージを出力
$conn_error = ibase_errmsg();
die($conn_error);
}

?>

例2 hostname/port を使った ibase_service_attach() の例

<?php
// リモートの Firebird サーバーに名前とポート3050を使ってアタッチ
if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

// アタッチ成功
// サーバーのバージョン('LI-V3.0.4.33054 Firebird 3.0'のようなもの)を取得
$server_version = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

// サーバーの実装を取得 ('Firebird/Linux/AMD/Intel/x64' のようなもの)
$server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

// サーバーからデタッチ(切断)
ibase_service_detach($service);

// 情報を出力
echo "Server version: " . $server_version . "<br/>";
echo "Server implementation: " . $server_implementation;
}
else {
// エラー時にはメッセージを出力
$conn_error = ibase_errmsg();
die($conn_error);
}

?>

参考

  • ibase_service_detach() - サービスマネージャとの接続を切断する


サービスマネージャとの接続を切断する

  • ≪ ibase_service_attach
  • ibase_set_event_handler ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • サービスマネージャとの接続を切断する

ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — サービスマネージャとの接続を切断する

説明

ibase_service_detach(resource $service_handle): bool

パラメータ

service_handle

データベースサーバーへの接続

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ibase_service_detach() の例

<?php
// リモートの Firebird サーバーにIPアドレスでアタッチ
if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

// アタッチ成功
// サーバーのバージョン('LI-V3.0.4.33054 Firebird 3.0'のようなもの)を取得
$server_version = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

// サーバーの実装を取得 ('Firebird/Linux/AMD/Intel/x64' のようなもの)
$server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

// サーバーからデタッチ(切断)
if(ibase_service_detach($service) == FALSE) {
echo "Error on service detach.";
}
else {
echo "Successfully detached from service.";
}

}
else {
// エラー時にはメッセージを出力
$conn_error = ibase_errmsg();
die($conn_error);
}

?>


イベントが発生した際にコールされるコールバック関数を登録する

  • ≪ ibase_service_detach
  • ibase_trans ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • イベントが発生した際にコールされるコールバック関数を登録する

ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する

説明

ibase_set_event_handler(callable $event_handler, string $event_name, string ...$even_names): resource
ibase_set_event_handler(
resource $connection,
callable $event_handler,
string $event_name,
string ...$event_names
): resource

この関数は、指定したイベントのハンドラとして PHP ユーザー関数を登録します。

パラメータ

event_handler

コールバックは、データベースから特定のイベントが送信された場合に、 イベント名とリンクリソースを引数としてコールされます。

イベントハンドラがキャンセルされた場合は、 コールバックは false を返す必要があります。 その他の戻り値は無視されます。 この関数は、最大 15 のイベントを引数として受け取ります。

event_name

イベントの名前。

event_names

最大で 15 のイベントを指定できます。

戻り値

返される値はイベントのリソースです。このリソースは、 ibase_free_event_handler() でイベントハンドラを開放する際に使用可能です。

例

例1 ibase_set_event_handler() の例

<?php

function event_handler($event_name, $link)
{
if ($event_name == "NEW ORDER") {
// 新しい注文を処理します
ibase_query($link, "UPDATE orders SET status='handled'");
} else if ($event_name == "DB_SHUTDOWN") {
// イベントハンドラを解放します
return false;
}
}

ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
?>

参考

  • ibase_free_event_handler() - 登録済みのイベントハンドラをキャンセルする
  • ibase_wait_event() - データベースでイベントが発生するのを待つ


トランザクションを開始する

  • ≪ ibase_set_event_handler
  • ibase_wait_event ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • トランザクションを開始する

ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — トランザクションを開始する

説明

ibase_trans(int $trans_args = ?, resource $link_identifier = ?): resource
ibase_trans(resource $link_identifier = ?, int $trans_args = ?): resource

トランザクションを開始します。

注意:

ibase_trans() を最初にコールした際には、接続の
デフォルトのトランザクションを返しません。ibase_trans()
によって開始されたすべてのトランザクションは、ibase_commit()
や ibase_rollback() を使用してコミットあるいは
ロールバックを明示的に行わない限り、スクリプトの終了時に自動的に
ロールバックされます。

注意:

この関数は複数の trans_args および link_identifier を指定することが可能です。これにより、 複数のデータベース接続にまたがるトランザクションを扱えるようになり、 2 フェーズコミット機能を使用したコミットが可能になります。つまり、複数の データベースの更新内容が成功したか失敗したかによる判断ができるということです。 これは、ひとつのクエリで異なるデータベースのテーブルを同時に使用できるという ことではありません!

複数データベースにまたがるトランザクションを使用する場合、 ibase_query() および ibase_prepare() をコールする際には link_id および transaction_id の両方を指定する必要があります。

パラメータ

trans_args

trans_args は、以下の IBASE_READ、 IBASE_WRITE、 IBASE_COMMITTED、 IBASE_CONSISTENCY、 IBASE_CONCURRENCY、 IBASE_REC_VERSION、 IBASE_REC_NO_VERSION、 IBASE_WAIT および IBASE_NOWAIT の組み合わせとなります。

link_identifier

InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

戻り値

トランザクションハンドル、あるいはエラー時に false を返します。


データベースでイベントが発生するのを待つ

  • ≪ ibase_trans
  • IBM DB2 ≫
  • PHP Manual
  • Firebird/InterBase 関数
  • データベースでイベントが発生するのを待つ

ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — データベースでイベントが発生するのを待つ

説明

ibase_wait_event(string $event_name, string ...$event_names): string
ibase_wait_event(resource $connection, string $event_name, string ...$event_names): string

この関数は、指定したイベントのうちのひとつがデータベースで発生するまで スクリプトの実行を停止します。発生したイベントの名前を返します。 この関数は、最大 15 のイベントを指定可能です。

パラメータ

event_name

イベントの名前。

event_names

戻り値

発生したイベントの名前を返します。

参考

  • ibase_set_event_handler() - イベントが発生した際にコールされるコールバック関数を登録する
  • ibase_free_event_handler() - 登録済みのイベントハンドラをキャンセルする


IBM DB2、Cloudscape および Apache Derby

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • IBM DB2 関数
    • db2_autocommit — データベース接続の AUTOCOMMIT の状態を取得または設定する
    • db2_bind_param — PHP 変数を SQL 文のパラメータにバインドする
    • db2_client_info — DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す
    • db2_close — データベース接続を閉じる
    • db2_column_privileges — テーブルのカラムおよび関連する権限情報を含む結果セットを返す
    • db2_columns — テーブルのカラムおよび関連するメタデータを含む結果セットを返す
    • db2_commit — トランザクションをコミットする
    • db2_conn_error — 直近の接続から返された SQLSTATE を含む文字列を返す
    • db2_conn_errormsg — 直近の接続エラーメッセージおよび SQLCODE を返す
    • db2_connect — データベースへの接続を返す
    • db2_cursor_type — ステートメントリソースが使用しているカーソルの型を返す
    • db2_escape_string — 特定の文字をエスケープする
    • db2_exec — SQL 文を直接実行する
    • db2_execute — プリペアドステートメントを実行する
    • db2_fetch_array — 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
    • db2_fetch_assoc — 結果セット内の行を表す、カラム名をインデックスとする配列を返す
    • db2_fetch_both — 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
    • db2_fetch_object — 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
    • db2_fetch_row — 結果セットポインタを次の行あるいは要求された行に設定する
    • db2_field_display_size — カラムを表示するために必要な最大のバイト数を返す
    • db2_field_name — 結果セット内のカラムの名前を返す
    • db2_field_num — 結果セット内の指定したカラムの位置を返す
    • db2_field_precision — 結果セット内の指定したカラムの精度を返す
    • db2_field_scale — 結果セット内の指定したカラムの位取りを返す
    • db2_field_type — 結果セット内の指定したカラムのデータ型を返す
    • db2_field_width — 結果セット内の指定したカラムの現在値の幅を返す
    • db2_foreign_keys — テーブルの外部キーを含む結果セットを返す
    • db2_free_result — 結果セットに関連付けられたリソースを開放する
    • db2_free_stmt — 指定されたステートメントリソースに関連付けられたリソースを開放する
    • db2_get_option — ステートメントリソースあるいは接続リソースからオプションの値を取得する
    • db2_last_insert_id — この接続上で最後に成功した insert クエリが自動生成した ID を返す
    • db2_lob_read — LOB ファイルから、ユーザーが定義したサイズの内容を取得する
    • db2_next_result — ストアドプロシージャから、次の結果セットを要求する
    • db2_num_fields — 結果セットに含まれるフィールドの数を返す
    • db2_num_rows — SQL 文によって変更された行の数を返す
    • db2_pclose — 持続的データベース接続を閉じる
    • db2_pconnect — データベースへの持続的接続を返す
    • db2_prepare — 実行する SQL 文を準備する
    • db2_primary_keys — テーブルの主キーを含む結果セットを返す
    • db2_procedure_columns — ストアドプロシージャのパラメータを含む結果セットを返す
    • db2_procedures — データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
    • db2_result — 結果セットの行からひとつのカラムを返す
    • db2_rollback — トランザクションをロールバックする
    • db2_server_info — DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す
    • db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する
    • db2_special_columns — テーブルのユニーク行 ID カラムを含む結果セットを返す
    • db2_statistics — インデックスの情報およびテーブルの統計情報を含む結果セットを返す
    • db2_stmt_error — SQL 文が返す SQLSTATE を含む文字列を返す
    • db2_stmt_errormsg — 直近の SQL 文のエラーメッセージを含む文字列を返す
    • db2_table_privileges — データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
    • db2_tables — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


はじめに

これらの関数により、DB2 Call Level Interface (DB2 CLI) を使用した IBM DB2 Universal Database、IBM Cloudscape および Apache Derby データベースへのアクセスが可能となります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • IBM DB2
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

IBM DB2 Universal Database for Linux・UNIX・Windows、 IBM Cloudscape、Apache Derby に接続するには、 PHP を稼動させるコンピュータ上に IBM DB2 Universal Database client がインストールされていなければなりません。 この拡張モジュールは、DB2 バージョン 8.2 を対象にして開発およびテストが行われています。

IBM DB2 Universal Database for z/OS・iSeries に接続するには、IBM DB2 Connect あるいはそれと同等の DRDA ゲートウェイソフトウェアも必要となります。

Linux あるいは Unix についての要件

これらの関数を使用する前には、PHP 実行ファイルあるいは SAPI を実行するユーザーで DB2 インスタンスを指定する必要があります。 php.ini で ibm_db2.instance_name を使用して DB2 インスタンス名を指定するか、 PHP 実行ファイルの起動前に DB2 インスタンスプロファイルを 読み込むことができます。

例えば、db2inst1 という名前の DB2 インスタンスを /home/db2inst1/ に作成した場合には php.ini に以下の行を追加します。

ibm_db2.instance_name=db2inst1
php.ini にこれを指定しない場合は、 DB2 へのアクセス用の環境変数を設定するために 以下のコマンドを実行しなければなりません。
bash$ source /home/db2inst1/sqllib/db2profile
PHP が使用できる Web サーバーからこれらの関数を使用するには、 php.ini で ibm_db2.instance_name を設定するか、 Web サーバーの起動スクリプト (/etc/init.d/httpd あるいは /etc/init.d/apache であることが多いでしょう) で DB2 インスタンス環境変数を読み込む必要があります。


インストール手順

ibm_db2 拡張モジュールをビルドするには、 DB2 アプリケーション開発用のヘッダファイルおよびライブラリが システムにインストールされていなければなりません。 これらのファイルはデフォルトではインストールされないので、 DB2 のインストーラをもう一度起動して このオプションを追加する必要があります。 IBM DB2 Universal Database の » サポートサイト にてフリーで公開されている DB2 Application Development Client に、これらのヘッダファイルが含まれています。

既に DB2 がインストールされている Linux や Unix 上に DB2 アプリケーション開発用のヘッダおよびライブラリを追加した場合は、 DB2 インスタンス内のヘッダファイルやライブラリに対する シンボリックリンクを更新するため、 コマンド db2iupdt -e を実行しなければなりません。

ibm_db2 は » PECL 拡張モジュールなので、 PECL 拡張モジュールのインストール の手順にしたがって PHP にインストールすることができます。 まず、DB2 ヘッダファイルおよびライブラリの場所を指定するために 次のように configure コマンドを実行します。

bash$ ./configure --with-IBM_DB2=/path/to/DB2
configure コマンドのデフォルト値は /opt/IBM/db2/V8.1 となっています。

注意: IIS ユーザー向けの注意

ibm_db2 ドライバを Microsoft Internet Information Server (IIS) で使用する場合は、以下ようにする必要があります。

  • DB2 を、拡張オペレーティングセキュリティ (extended operating system security) つきでインストールします。
  • PHP のバイナリへのパス (デフォルトは C:\php\) を、システムの環境変数 PATH に追加します。
  • システムの環境変数をもうひとつ作成し、PHP.INI のある場所を指定します (例: PHPRC = C:\php\)。
  • IUSR_COMPUTERNAME を DB2USERS グループに追加します。


実行時設定

php.ini の設定により動作が変化します。

ibm_db2 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ibm_db2.binmode | "1" | INI_ALL |
ibm_db2.i5_all_pconnect | "0" | INI_SYSTEM | ibm_db2 1.6.5 以降で利用可能
ibm_db2.i5_allow_commit | "0" | INI_SYSTEM | ibm_db2 1.4.9 以降で利用可能
ibm_db2.i5_blank_userid | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_char_trim | "0" | INI_SYSTEM | ibm_db2 2.1.0 以降で利用可能
ibm_db2.i5_dbcs_alloc | "0" | INI_SYSTEM | ibm_db2 1.5.0 以降で利用可能
ibm_db2.i5_guard_profile | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_ignore_userid | "0" | INI_SYSTEM | ibm_db2 1.8.0 以降で利用可能
ibm_db2.i5_job_sort | "0" | INI_SYSTEM | ibm_db2 1.8.4 以降で利用可能
ibm_db2.i5_log_verbose | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_max_pconnect | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_override_ccsid | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_servermode_subsystem | NULL | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_sys_naming | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.instance_name | NULL | INI_SYSTEM | ibm_db2 1.0.2 以降で利用可能

以下に設定ディレクティブに関する 簡単な説明を示します。

ibm_db2.binmode int

このオプションは、バイナリデータを PHP アプリケーションで 使用する際のモードを制御します。

  • 1 (DB2_BINARY)

  • 2 (DB2_CONVERT)

  • 3 (DB2_PASSTHRU)

ibm_db2.i5_all_pconnect int

このオプションは、IBM i 上での接続を強制的にすべて持続的接続にします。 基本的に、すべての db2_connect() 関数のコールは透過的に db2_pconnect() のコールになります。 デフォルトでは、このオプションの値は 0 です。 このオプションは、持続的接続が高速な場合のために便宜上提供されています。 新しいアプリケーションでは、このオプションを使うべきではありません。

  • 0 - 持続的接続、およびそうでない接続の両方を作成できます

  • 1 - すべての接続を持続的接続にします

ibm_db2.i5_allow_commit int

このオプションは、トランザクションの分離レベルを制御します。 デフォルトでは、このオプションの値は 0 です。 よって、コミットの制御は使いません。 このオプションは、配列のキー i5_commit を接続オプションの配列に設定し、 db2_connect() や db2_pconnect() に渡すことで上書きできます。

  • 0 - コミット制御を使いません。

  • 1 - read uncommitted。ダーティリードの可能性があります。

  • 2 - read committed。ダーティリードは発生しません。

  • 3 - repeatable read。ダーティリードや非再現リードは発生しません。

  • 4 - serializeable。ダーティリードや非再現リードやファントムリードは発生しません。

ibm_db2.i5_blank_userid int

IBM i 上で空のユーザーIDを許可すべきかどうかを制御します。 デフォルトでは、このオプションの値は 0 です。 ibm_db2.i5_ignore_userid と異なり、 このオプションはすべてのユーザーIDを強制的に空にしたり、 ジョブの振る舞いを変えたりはしません。 ただ単に、Db2 に現在のユーザーとしてする際、 空のユーザーIDを渡すことを許可するだけです。

  • 0 - ユーザーIDを空で渡すことを許可しません

  • 1 - ユーザーIDを空で渡すことを許可します。

ibm_db2.i5_char_trim int

このオプションは、IBM i における文字列の右端をトリム処理するかを制御します。 多くのテーブルは固定のカラムサイズを持ち、スペースで埋められているため、 このオプションが便宜のため提供されています。 デフォルトでは、このオプションの値は 0 です。

  • 0 - カラムの値はトリム処理されません。

  • 1 - 返される文字カラムの右端のスペースが削除されます。

ibm_db2.i5_dbcs_alloc int

This options affects the internal buffer allocation strategy on IBM i. By default, this option is 0. When this option is set, buffers are allocated with a much larger size, in case the database underestimates a string's size when converting between encodings. This option uses six times as much memory for buffers (to account for the largest possible UTF-8 sequences), but may be needed if truncated data is returned.

  • 0 - Minimum size buffers are allocated.

  • 1 - Larger size buffers are allocated.

ibm_db2.i5_guard_profile int

IBM i 上のデータベースに持続的接続する際、 ユーザーのデータベースのプロファイルを切り替えるかどうかをチェックします。 切り替える場合、データベースから切断します。 デフォルトでは、このオプションの値は 0 です。

  • 0 - プロファイルの切換をチェックしません

  • 1 - プロファイルの切換をチェックし、切り替える場合は切断します

ibm_db2.i5_log_verbose int

This option sets if SQL diagnostic messages like warnings and errors are always sent to the PHP error log on IBM i. Normally, only a brief message on failure is sent (such as "statement execute failed") to the PHP error log, as this option is set to 0 by default. Note that you can still and should call i.e. db2_stmt_errormsg() manually as part of checking if functions fail.

  • 0 - Only logs brief messages.

  • 1 - Logs the SQL diagnostic message in addition to the brief message.

ibm_db2.i5_ignore_userid int

IBM i 上で実行される際、かつデータベースに接続する際に、 このオプションはユーザーID を無視します。 また、別々のジョブではなく、PHPジョブの内部でSQL/CLI の機能を実行します。 デフォルトでは、このオプションの値は 0 です。 このオプションを有効にすると、 別々のデータベースサーバのジョブを使わず、 常に現在のユーザープロファイルを使います。 そして、db2_connect() と db2_pconnect() に渡されるユーザー名とパスワードを無視します。

  • 0 - 指定されたクレデンシャルを使い、SQL/CLI サーバのジョブを使います。

  • 1 - 常に空のクレデンシャルを使い、PHP のジョブ中でSQL/CLI ジョブを実行します

ibm_db2.i5_job_sort int

IBM i におけるジョブソートを制御します。 デフォルトでは、このオプションの値は 0 です。 これは IBM i SQL/CLI の SQL_ATTR_CONN_SORT_SEQUENCE 属性に対応します。

  • 0 - *HEX ソートオプションを使い、 バイト単位でソートを行います。

  • 1 - PHP のジョブ向けにジョブソートのシーケンスを使います。

  • 2 - データベースのジョブ向けにジョブソートのシーケンスを使います。

ibm_db2.i5_max_pconnect int

このオプションは、IBM i 上で実行する際、 何回持続的接続が再利用されるかに影響します。 デフォルトでは、この値は 0 です。 つまり、持続的接続は常に再利用されるということです。 このオプションは、 長時間実行されるデータベースのジョブで起こる問題 (つまり、プロシージャでメモリリークが起きた場合など) を回避されるのに役立ちますが、明らかに長期的に役立つものではないでしょう。

ibm_db2.i5_override_ccsid int

The PASE CCSID to use for character conversions from EBCDIC on IBM i. By default, this is 0, which will select the default PASE job CCSID, which comes from the PASE locale settings. For example, setting this to 1208 will use UTF-8. This should only be modified if the PASE job CCSID isn't the expected CCSID, and the locale cannot be modified.

To learn more about CCSIDs on IBM i, consult the » IBM documentation. To learn how locales on IBM i PASE are mapped to CCSIDs, consult the » IBM documentation.

ibm_db2.i5_sys_naming int

This option controls the naming mode when connecting to an IBM i system. By default, this option is 0. The naming mode affects how names are resolved and the allowed syntax for names. When set to 0, this uses periods to qualify names and uses the default library or user ID to resolve names. When set to 1, this uses slashes to qualify names and uses the job library list to resolve names.

  • 0 - Uses the SQL naming mode ("SCHEMA.TABLE").

  • 1 - Uses the system naming mode ("LIBRARY/FILE").

To learn more about naming modes on IBM i, consult the » IBM documentation.

ibm_db2.i5_servermode-subsystem string

This option changes which subsystem database server jobs run under on IBM i. By default, this option is null, so jobs will run under the default subsystem for QSQSRVR jobs.

ibm_db2.instance_name string

Linux や UNIX オペレーティングシステムにおいて、 このオプションはカタログされたデータベースへの接続で使う、 インスタンス名を定義します。 デフォルトでは、このオプションの値は null です。 このオプションを設定すると、 環境変数 DB2INSTANCE の値を上書きします。

Windows では、このオプションの値は無視されます。


  • ≪ 実行時設定
  • 定義済み定数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型

ibm_db2 拡張モジュールは、接続リソース・ステートメントリソース および結果セットリソースを返します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

DB2_BINARY (int)
バイナリデータをそのままの形式で返します。デフォルトのモードです。
DB2_CONVERT (int)
バイナリデータを十六進表現にエンコードし、ASCII 文字列として返します。
DB2_PASSTHRU (int)
バイナリデータを null 値に変換します。
DB2_SCROLLABLE (int)
ステートメントのリソースとして、スクロール可能なカーソルを指定します。 このモードでは結果セット内の行へのランダムアクセスが可能となりますが、 現在は IBM DB2 Universal Database でしかサポートされていません。
DB2_FORWARD_ONLY (int)
ステートメントのリソースとして、前進のみ可能なカーソルを指定します。 これはデフォルトのカーソル型であり、 すべてのデータベースサーバーでサポートされています。
DB2_PARAM_IN (int)
PHP 変数を、ストアドプロシージャの IN パラメータとしてバインドします。
DB2_PARAM_OUT (int)
PHP 変数を、ストアドプロシージャの OUT パラメータとしてバインドします。
DB2_PARAM_INOUT (int)
PHP 変数を、ストアドプロシージャの INOUT パラメータとしてバインドします。
DB2_PARAM_FILE (int)
カラムを直接ファイルにバインドし、そのデータを読み込みます。
DB2_AUTOCOMMIT_ON (int)
自動コミットを有効にします。
DB2_AUTOCOMMIT_OFF (int)
自動コミットを無効にします。
DB2_DOUBLE (int)
変数を、データ型 DOUBLE、FLOAT あるいは REAL にバインドします。
DB2_LONG (int)
変数を、データ型 SMALLINT、INTEGER あるいは BIGINT にバインドします。
DB2_CHAR (int)
変数を、データ型 CHAR あるいは VARCHAR にバインドします。
DB2_CASE_NATURAL (int)
カラム名の大文字小文字を変換せずに返します。
DB2_CASE_LOWER (int)
カラム名を小文字に変換して返します。
DB2_CASE_UPPER (int)
カラム名を大文字に変換して返します。
DB2_DEFERRED_PREPARE_ON (int)
指定したステートメントリソースについて、遅延プリペアを有効にします。
DB2_DEFERRED_PREPARE_OFF (int)
指定したステートメントリソースについて、遅延プリペアを無効にします。


IBM DB2 関数

目次

  • db2_autocommit — データベース接続の AUTOCOMMIT の状態を取得または設定する
  • db2_bind_param — PHP 変数を SQL 文のパラメータにバインドする
  • db2_client_info — DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す
  • db2_close — データベース接続を閉じる
  • db2_column_privileges — テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns — テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_commit — トランザクションをコミットする
  • db2_conn_error — 直近の接続から返された SQLSTATE を含む文字列を返す
  • db2_conn_errormsg — 直近の接続エラーメッセージおよび SQLCODE を返す
  • db2_connect — データベースへの接続を返す
  • db2_cursor_type — ステートメントリソースが使用しているカーソルの型を返す
  • db2_escape_string — 特定の文字をエスケープする
  • db2_exec — SQL 文を直接実行する
  • db2_execute — プリペアドステートメントを実行する
  • db2_fetch_array — 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc — 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both — 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_object — 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_fetch_row — 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_field_display_size — カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name — 結果セット内のカラムの名前を返す
  • db2_field_num — 結果セット内の指定したカラムの位置を返す
  • db2_field_precision — 結果セット内の指定したカラムの精度を返す
  • db2_field_scale — 結果セット内の指定したカラムの位取りを返す
  • db2_field_type — 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width — 結果セット内の指定したカラムの現在値の幅を返す
  • db2_foreign_keys — テーブルの外部キーを含む結果セットを返す
  • db2_free_result — 結果セットに関連付けられたリソースを開放する
  • db2_free_stmt — 指定されたステートメントリソースに関連付けられたリソースを開放する
  • db2_get_option — ステートメントリソースあるいは接続リソースからオプションの値を取得する
  • db2_last_insert_id — この接続上で最後に成功した insert クエリが自動生成した ID を返す
  • db2_lob_read — LOB ファイルから、ユーザーが定義したサイズの内容を取得する
  • db2_next_result — ストアドプロシージャから、次の結果セットを要求する
  • db2_num_fields — 結果セットに含まれるフィールドの数を返す
  • db2_num_rows — SQL 文によって変更された行の数を返す
  • db2_pclose — 持続的データベース接続を閉じる
  • db2_pconnect — データベースへの持続的接続を返す
  • db2_prepare — 実行する SQL 文を準備する
  • db2_primary_keys — テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns — ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures — データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_result — 結果セットの行からひとつのカラムを返す
  • db2_rollback — トランザクションをロールバックする
  • db2_server_info — DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す
  • db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する
  • db2_special_columns — テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics — インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_stmt_error — SQL 文が返す SQLSTATE を含む文字列を返す
  • db2_stmt_errormsg — 直近の SQL 文のエラーメッセージを含む文字列を返す
  • db2_table_privileges — データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


データベース接続の AUTOCOMMIT の状態を取得または設定する

  • ≪ IBM DB2 関数
  • db2_bind_param ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース接続の AUTOCOMMIT の状態を取得または設定する

db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — データベース接続の AUTOCOMMIT の状態を取得または設定する

説明

db2_autocommit(resource $connection, int $value = ?): int|bool

指定した接続リソースについての AUTOCOMMIT の状態を設定あるいは取得します。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

value

以下の定数のいずれか。

DB2_AUTOCOMMIT_OFF

AUTOCOMMIT を無効にします。

DB2_AUTOCOMMIT_ON

AUTOCOMMIT を有効にします。

戻り値

db2_autocommit() に connection パラメータのみを渡した場合、 指定した接続の AUTOCOMMIT の状態を整数値で返します。 DB2_AUTOCOMMIT_OFF の場合は無効、 DB2_AUTOCOMMIT_ON の場合は有効です。

db2_autocommit() に connection および autocommit の両方のパラメータを渡した場合、 指定した接続の AUTOCOMMIT を対応する状態に設定します。 成功した場合に true を、失敗した場合に false を返します。

例

例1 接続の AUTOCOMMIT 値の取得

以下の例では、AUTOCOMMIT を無効にした接続について db2_autocommit() 関数で調べます。

<?php
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
$conn = db2_connect($database, $user, $password, $options);
$ac = db2_autocommit($conn);
if ($ac == DB2_AUTOCOMMIT_OFF) {
print "$ac -- AUTOCOMMIT は無効です。";
} else {
print "$ac -- AUTOCOMMIT が有効です。";
}
?>

上の例の出力は以下となります。

0 -- AUTOCOMMIT は無効です。

例2 接続の AUTOCOMMIT 値の設定

以下の例では、AUTOCOMMIT を無効にして作成した接続の AUTOCOMMIT を変更し、有効にします。

<?php
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
$conn = db2_connect($database, $user, $password, $options);

// AUTOCOMMIT を有効にします
$rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
if ($rc) {
print "AUTOCOMMIT を有効にしました。\n";
}

// AUTOCOMMIT の状態を調べます
$ac = db2_autocommit($conn);
if ($ac == DB2_AUTOCOMMIT_OFF) {
print "$ac -- AUTOCOMMIT は無効です。";
} else {
print "$ac -- AUTOCOMMIT が有効です。";
}
?>

上の例の出力は以下となります。

AUTOCOMMIT を有効にしました。
1 -- AUTOCOMMIT が有効です。

参考

  • db2_connect() - データベースへの接続を返す
  • db2_pconnect() - データベースへの持続的接続を返す


PHP 変数を SQL 文のパラメータにバインドする

  • ≪ db2_autocommit
  • db2_client_info ≫
  • PHP Manual
  • IBM DB2 関数
  • PHP 変数を SQL 文のパラメータにバインドする

db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — PHP 変数を SQL 文のパラメータにバインドする

説明

db2_bind_param(
resource $stmt,
int $parameter_number,
string $variable_name,
int $parameter_type = DB2_PARAM_IN,
int $data_type = 0,
int $precision = -1,
int $scale = 0
): bool

db2_prepare() が返したステートメントリソース内の SQL 文のパラメータに PHP 変数をバインドします。 db2_execute() へのオプション配列の一部として 変数を渡すのに比べ、この関数を使用すると パラメータの型、データの型、精度、位取りなどの詳細を制御できるようになります。

パラメータ

stmt

db2_prepare() が返すプリペアドステートメント。

parameter_number

プリペアドステートメントのパラメータの位置。 1 から始まります。

variable_name

parameter_number で指定したパラメータに バインドする PHP 変数の名前を表す文字列。

parameter_type

PHP 変数を SQL パラメータにバインドする際に 入力パラメータとするのか (DB2_PARAM_IN) 出力パラメータとするのか (DB2_PARAM_OUT) あるいは入出力両方を許可するのか (DB2_PARAM_INOUT) を指定する定数。 メモリのオーバーヘッドを避けるため、DB2_PARAM_FILE を指定して PHP 変数をファイルにバインドし、 ファイルからラージオブジェクト (BLOB、CLOB あるいは DBCLOB) データを読み込むようにするすることも可能です。

data_type

PHP 変数をどの SQL データ型にバインドするのかを指定する定数。 DB2_BINARY、 DB2_CHAR、DB2_DOUBLE あるいは DB2_LONG のうちのいずれか。

precision

変数をデータベースにバインドする際の精度を指定します。 このパラメータは、ストアドプロシージャから XML 出力の値を取得する際にも使用します。 非負の値を指定すると、それがデータベースから取得する XML データの最大サイズとなります。 このパラメータを使用しない場合は、 ストアドプロシージャから XML 出力を取得する際の最大サイズを デフォルトの 1MB とみなします。

scale

変数をデータベースにバインドする際の位取りを指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 PHP 変数をプリペアドステートメントにバインドする

以下の例の SQL 文では、WHERE 句の中で 2 つの入力パラメータを使用しています。 この 2 つのパラメータに PHP 変数をバインドするために db2_bind_param() をコールします。 db2_bind_param() をコールする前に PHP 変数を宣言したり代入したりする必要がないことに注意しましょう。 この例では、$lower_limit については db2_bind_param() がコールされる前に 値が代入されていますが、$upper_limit については db2_bind_param() をコールした後で代入されています。 db2_execute() をコールする前には、 必ず変数をバインドしなければなりません。また、入力パラメータについては 何らかの値を代入しておく必要があります。

<?php

$sql = 'SELECT name, breed, weight FROM animals
WHERE weight > ? AND weight < ?';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);

// db2_bind_param() のコール前に変数を宣言できます
$lower_limit = 1;

db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

// また、db2_bind_param() をコールした後で変数を宣言することも可能です
$upper_limit = 15.0;

if (db2_execute($stmt)) {
while ($row = db2_fetch_array($stmt)) {
print "{$row[0]}, {$row[1]}, {$row[2]}\n";
}
}
?>

上の例の出力は以下となります。

Pook, cat, 3.2
Rickety Ride, goat, 9.7
Peaches, dog, 12.3

例2 IN および OUT パラメータを使用したストアドプロシージャのコール

以下の例のストアドプロシージャ match_animal は、 3 つのさまざまなパラメータを受け取ります。

  1. 最初の動物の名前を入力として受け取る 入力 (IN) パラメータ。

  2. 2 番目の動物の名前を入力として受け取り、その名前に一致する動物が データベースに存在する場合に文字列 TRUE を返す、入出力 (INOUT) パラメータ。

  3. 指定した 2 匹の動物の合計体重を返す、出力 (OUT) パラメータ。

さらにこのストアドプロシージャは結果セットを返します。その内容は、 最初のパラメータで指定した動物から 2 番目のパラメータで指定した動物までの 動物の一覧をアルファベット順に並べたものとなります。

<?php

$sql = 'CALL match_animal(?, ?, ?)';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);

$name = "Peaches";
$second_name = "Rickety Ride";
$weight = 0;

db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

print "コール前のバインド変数の値:\n";
print " 1: {$name} 2: {$second_name} 3: {$weight}\n\n";

if (db2_execute($stmt)) {
print "コール後のバインド変数の値:\n";
print " 1: {$name} 2: {$second_name} 3: {$weight}\n\n";

print "結果:\n";
while ($row = db2_fetch_array($stmt)) {
print " {$row[0]}, {$row[1]}, {$row[2]}\n";
}
}
?>

上の例の出力は以下となります。

コール前のバインド変数の値:
  1: Peaches 2: Rickety Ride 3: 0

コール後のバインド変数の値:
  1: Peaches 2: TRUE 3: 22

結果:
  Peaches, dog, 12.3
  Pook, cat, 3.2
  Rickety Ride, goat, 9.7

例3 バイナリラージオブジェクト (BLOB) をファイルから直接挿入する

ラージオブジェクトのデータは、通常は XML ドキュメントあるいは 音声ファイルのようなファイルに保存されています。 いったんファイルの内容を PHP 変数に読み込んだうえで SQL 文にバインドする代わりに、ファイルを直接 sql 文の入力パラメータに バインドすることでメモリのオーバーヘッドを避けることができます。 以下の例で、BLOB カラムにファイルを直接バインドする方法を説明します。

<?php
$stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

$picture = "/opt/albums/spook/grooming.jpg";
$rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
$rc = db2_execute($stmt);
?>

参考

  • db2_execute() - プリペアドステートメントを実行する
  • db2_prepare() - 実行する SQL 文を準備する


DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

  • ≪ db2_bind_param
  • db2_close ≫
  • PHP Manual
  • IBM DB2 関数
  • DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

説明

db2_client_info(resource $connection): stdClass|false

この関数は、DB2 データベースクライアントについての情報を 読み取り専用のプロパティに保持するオブジェクトを返します。 以下の表は、DB2 クライアントプロパティの一覧です。

DB2 クライアントプロパティ
プロパティ名 | 戻り値の型 | 説明
APPL_CODEPAGE | int | アプリケーションのコードページ。
CONN_CODEPAGE | int | 現在の接続のコードページ。
DATA_SOURCE_NAME | string | 現在のデータベース接続に使用されているデータソース名 (DSN)。
DRIVER_NAME | string | DB2 コールレベルインターフェイス (CLI) の仕様を実装した ライブラリの名前。
DRIVER_ODBC_VER | string | DB2 クライアントがサポートしている ODBC のバージョン。 "MM.mm" という形式の文字列で、MM がメジャーバージョン、mm がマイナーバージョンを表します。DB2 クライアントは、 常に "03.51" を返します。
DRIVER_VER | string | クライアントのバージョン。"MM.mm.uuuu" という形式の文字列で、 MM がメジャーバージョン、 mm がマイナーバージョン、 そして uuuu がアップデートを表します。 例えば "08.02.0001" は メジャーバージョン 8、マイナーバージョン 2、アップデート 1 を表します。
ODBC_SQL_CONFORMANCE string クライアントがサポートする ODBC SQL 構文レベル。
MINIMUM

最小限の ODBC SQL 構文をサポートします。

CORE

コア ODBC SQL をサポートします。

EXTENDED

拡張 ODBC SQL 構文をサポートします。

ODBC_VER | string | ODBC ドライバマネージャがサポートする ODBC のバージョン。 "MM.mm.rrrr" という形式の文字列で、 MM がメジャーバージョン、 mm がマイナーバージョン、 そして rrrr がリリースを表します。 DB2 クライアントは、常に "03.01.0000" を返します。

パラメータ

connection

アクティブな DB2 クライアント接続を指定します。

戻り値

成功した場合にオブジェクトを返します。 失敗した場合に false を返します

例

例1 db2_client_info() の例

クライアントの情報を取得するには、有効なデータベース接続リソースを db2_client_info() に渡す必要があります。

<?php
$conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
$client = db2_client_info( $conn );

if ($client) {
echo "DRIVER_NAME: "; var_dump( $client->DRIVER_NAME );
echo "DRIVER_VER: "; var_dump( $client->DRIVER_VER );
echo "DATA_SOURCE_NAME: "; var_dump( $client->DATA_SOURCE_NAME );
echo "DRIVER_ODBC_VER: "; var_dump( $client->DRIVER_ODBC_VER );
echo "ODBC_VER: "; var_dump( $client->ODBC_VER );
echo "ODBC_SQL_CONFORMANCE: "; var_dump( $client->ODBC_SQL_CONFORMANCE );
echo "APPL_CODEPAGE: "; var_dump( $client->APPL_CODEPAGE );
echo "CONN_CODEPAGE: "; var_dump( $client->CONN_CODEPAGE );
}
else {
echo "クライアント情報の取得エラー。
おそらくデータベース接続が無効です。";
}
db2_close($conn);

?>

上の例の出力は以下となります。

DRIVER_NAME: string(8) "libdb2.a"
DRIVER_VER: string(10) "08.02.0001"
DATA_SOURCE_NAME: string(6) "SAMPLE"
DRIVER_ODBC_VER: string(5) "03.51"
ODBC_VER: string(10) "03.01.0000"
ODBC_SQL_CONFORMANCE: string(8) "EXTENDED"
APPL_CODEPAGE: int(819)
CONN_CODEPAGE: int(819)

参考

  • db2_server_info() - DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す


データベース接続を閉じる

  • ≪ db2_client_info
  • db2_column_privileges ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース接続を閉じる

db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — データベース接続を閉じる

説明

db2_close(resource $connection): bool

この関数は、db2_connect() で作成した DB2 クライアント接続を閉じ、データベースサーバーへのリソースを返します。

db2_pconnect() で作成した持続的 DB2 クライアント接続を閉じようとするとその要求は無視され、 次にコールされるときまで持続的 DB2 クライアント接続はそのまま残ります。

パラメータ

connection

アクティブな DB2 クライアント接続を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 接続を閉じる

以下では IBM DB2、Cloudscape あるいは Apache Derby データベースとの接続が正常に閉じられた場合の例を示します。

<?php
$conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
$rc = db2_close($conn);
if ($rc) {
echo "接続が正しく閉じられました。";
}
?>

上の例の出力は以下となります。

接続が正しく閉じられました。

参考

  • db2_connect() - データベースへの接続を返す
  • db2_pclose() - 持続的データベース接続を閉じる
  • db2_pconnect() - データベースへの持続的接続を返す


テーブルのカラムおよび関連する権限情報を含む結果セットを返す

  • ≪ db2_close
  • db2_columns ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルのカラムおよび関連する権限情報を含む結果セットを返す

db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — テーブルのカラムおよび関連する権限情報を含む結果セットを返す

説明

db2_column_privileges(
resource $connection,
?string $qualifier = null,
?string $schema = null,
?string $table_name = null,
?string $column_name = null
): resource

テーブルのカラムおよび関連する権限情報を含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。すべてのスキーマに一致させるには、 null あるいは空の文字列を渡します。

table_name

テーブルあるいはビューの名前。データベース内のすべてのテーブルに一致させるには、 null あるいは空の文字列を渡します。

column_name

カラムの名前。テーブル内のすべてのカラムに一致させるには、 null あるいは空の文字列を渡します。

戻り値

指定したパラメータに一致するカラムの権限情報を含むステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | カタログの名前。テーブルがカタログを保持していない場合は NULL。
TABLE_SCHEM | スキーマの名前。
TABLE_NAME | テーブルあるいはビューの名前。
COLUMN_NAME | カラムの名前。
GRANTOR | その権限を与えたユーザーの認証 ID。
GRANTEE | その権限を与えられたユーザーの認証 ID。
PRIVILEGE | カラムの権限。
IS_GRANTABLE | GRANTEE が、この権限を他のユーザーに与えることができるかどうか。

参考

  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


テーブルのカラムおよび関連するメタデータを含む結果セットを返す

  • ≪ db2_column_privileges
  • db2_commit ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルのカラムおよび関連するメタデータを含む結果セットを返す

db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — テーブルのカラムおよび関連するメタデータを含む結果セットを返す

説明

db2_columns(
resource $connection,
?string $qualifier = null,
?string $schema = null,
?string $table_name = null,
?string $column_name = null
): resource

テーブルのカラムおよび関連するメタデータを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。すべてのスキーマに一致させるには、 '%' を渡します。

table_name

テーブルあるいはビューの名前。データベース内のすべてのテーブルに一致させるには、 null あるいは空の文字列を渡します。

column_name

カラムの名前。テーブル内のすべてのカラムに一致させるには、 null あるいは空の文字列を渡します。

戻り値

指定したパラメータに一致するカラムの情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | カタログの名前。テーブルがカタログを保持していない場合は NULL。
TABLE_SCHEM | スキーマの名前。
TABLE_NAME | テーブルあるいはビューの名前。
COLUMN_NAME | カラムの名前。
DATA_TYPE | カラムの SQL データ型を整数値で表したもの。
TYPE_NAME | カラムのデータ型を文字列で表したもの。
COLUMN_SIZE | カラムのサイズを表す整数値。
BUFFER_LENGTH | このカラムのデータを保存するために必要な最大のバイト数。
DECIMAL_DIGITS | カラムの位取り。位取りが適用できない場合は null。
NUM_PREC_RADIX | 10 (正確な数値データ型を表す)、 2 (概数データ型を表す)、 あるいは null (基数が適用できないデータ型を表す) のいずれか。
NULLABLE | カラムが null 値をとることができるかどうかを表す整数値。
REMARKS | カラムの説明。
COLUMN_DEF | カラムのデフォルト値。
SQL_DATA_TYPE | カラムのサイズを表す整数値。
SQL_DATETIME_SUB | datetime 型のコードを表す整数値、 あるいはこれが適用できない SQL データ型である場合に null。
CHAR_OCTET_LENGTH | 文字型のカラムにおける最大のオクテット数。 シングルバイト文字セットのデータの場合、これは COLUMN_SIZE に一致します。文字型でないカラムの場合は null となります。
ORDINAL_POSITION | テーブル内でのカラムの位置を表す、1 から始まるインデックス。
IS_NULLABLE | カラムが null 値をとることができるかどうかを表す文字列。 'YES' の場合は null 値をとることができ、 'NO' の場合はできません。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


トランザクションをコミットする

  • ≪ db2_columns
  • db2_conn_error ≫
  • PHP Manual
  • IBM DB2 関数
  • トランザクションをコミットする

db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — トランザクションをコミットする

説明

db2_commit(resource $connection): bool

指定した接続リソース上で実行中のトランザクションをコミットし、 新しいトランザクションを開始します。PHP アプリケーションのデフォルトは AUTOCOMMIT モードなので、接続リソースに対して AUTOCOMMIT を無効にしていない限り db2_commit() は必要ありません。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • db2_autocommit() - データベース接続の AUTOCOMMIT の状態を取得または設定する
  • db2_rollback() - トランザクションをロールバックする


直近の接続から返された SQLSTATE を含む文字列を返す

  • ≪ db2_commit
  • db2_conn_errormsg ≫
  • PHP Manual
  • IBM DB2 関数
  • 直近の接続から返された SQLSTATE を含む文字列を返す

db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — 直近の接続から返された SQLSTATE を含む文字列を返す

説明

db2_conn_error(?resource $connection = null): string

db2_conn_error() は、データベースへの直近の接続が 失敗した原因を表す SQLSTATE を返します。接続が失敗した場合には、 db2_connect() は false を返します。 この場合、SQLSTATE の値を取得するために db2_conn_error() に何もパラメータを渡す必要はありません。

しかし、接続は成功したもののその後に無効になった場合は、 パラメータ connection を指定することで 特定の接続についての SQLSTATE を取得することができます。

SQLSTATE の値の意味を調べるには、DB2 コマンドラインプロセッサのプロンプトで 次のコマンドを発行します。 db2 '? sqlstate-value' また、db2_conn_errormsg() をコールして、 明示的なエラーメッセージと、それに関連する SQLCODE の値を取得することも可能です。

パラメータ

connection

当初は成功したものの、その後に無効になった接続に 関連付けられた接続リソース。

戻り値

失敗した接続試行の結果を表す SQLSTATE を返します。 直近の接続試行に関連するエラーがない場合には空の文字列を返します。

例

例1 失敗した接続試行からの SQLSTATE の取得

以下の例では、db2_connect() に わざと無効なパラメータを渡し、SQLSTATE を取得しています。

<?php
$conn = db2_connect('badname', 'baduser', 'badpassword');
if (!$conn) {
print "SQLSTATE の値: " . db2_conn_error();
}
?>

上の例の出力は以下となります。

SQLSTATE の値: 08001

参考

  • db2_conn_errormsg() - 直近の接続エラーメッセージおよび SQLCODE を返す
  • db2_connect() - データベースへの接続を返す
  • db2_stmt_error() - SQL 文が返す SQLSTATE を含む文字列を返す
  • db2_stmt_errormsg() - 直近の SQL 文のエラーメッセージを含む文字列を返す


直近の接続エラーメッセージおよび SQLCODE を返す

  • ≪ db2_conn_error
  • db2_connect ≫
  • PHP Manual
  • IBM DB2 関数
  • 直近の接続エラーメッセージおよび SQLCODE を返す

db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — 直近の接続エラーメッセージおよび SQLCODE を返す

説明

db2_conn_errormsg(?resource $connection = null): string

db2_conn_errormsg() は、データベースへの直近の接続が 失敗した原因を表す SQLCODE およびエラーメッセージを返します。 接続が失敗した場合には、db2_connect() は false を返します。 この場合、エラーメッセージおよび SQLSTATE の値を取得するために db2_conn_errormsg() に何もパラメータを渡す必要はありません。

しかし、接続は成功したもののその後に無効になった場合は、 パラメータ connection を指定することで 特定の接続についてのエラーメッセージおよび SQLSTATE を取得することができます。

パラメータ

connection

当初は成功したものの、その後に無効になった接続に 関連付けられた接続リソース。

戻り値

失敗した接続試行の結果を表すエラーメッセージおよび SQLSTATE を返します。 直近の接続試行に関連するエラーがない場合には、 db2_conn_errormsg() はn空の文字列を返します。

例

例1 失敗した接続試行からのエラーメッセージの取得

以下の例では、db2_connect() に わざと無効なパラメータを渡し、エラーメッセージおよび SQLSTATE を取得しています。

<?php
$conn = db2_connect('badname', 'baduser', 'badpassword');
if (!$conn) {
print db2_conn_errormsg();
}
?>

上の例の出力は以下となります。

[IBM][CLI Driver] SQL1013N  The database alias name
or database name "BADNAME" could not be found.  SQLSTATE=42705
 SQLCODE=-1013

参考

  • db2_conn_error() - 直近の接続から返された SQLSTATE を含む文字列を返す
  • db2_connect() - データベースへの接続を返す
  • db2_stmt_error() - SQL 文が返す SQLSTATE を含む文字列を返す
  • db2_stmt_errormsg() - 直近の SQL 文のエラーメッセージを含む文字列を返す


データベースへの接続を返す

  • ≪ db2_conn_errormsg
  • db2_cursor_type ≫
  • PHP Manual
  • IBM DB2 関数
  • データベースへの接続を返す

db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — データベースへの接続を返す

説明

db2_connect(
string $database,
?string $username,
?string $password,
array $options = []
): resource|false

IBM DB2 Universal Database、IBM Cloudscape あるいは Apache Derby データベースへの新しい接続を作成します。

パラメータ

database

データベースへのカタログ接続の場合には、database は DB2 クライアントカタログ内でのデータベースエイリアスを表します。

データベースへの非カタログ接続の場合には、 database は以下のような形式の接続文字列を表します。

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;
それぞれのパラメータは以下の内容を表します。

注意:

IBM i 上の Db2 に接続する場合、以下のシステムコール » SQLDriverConnect は、DSN, UID, PWD のみを » connection string として受け入れます。たとえば以下のようになります:

DSN=database;UID=username;PWD=password;

database

データベースの名前。

hostname

データベースサーバーのホスト名あるいは IP アドレス。

port

データベースが要求を待ち受ける TCP/IP ポート。

username

データベースに接続するユーザー名。

password

データベースに接続するパスワード。

username

データベースに接続するユーザー名。

カタログでない接続の場合は、null あるいは空の文字列を渡す必要があります。

password

データベースに接続するパスワード。

カタログでない接続の場合は、null あるいは空の文字列を渡す必要があります。

options

接続の振る舞いを指定する接続オプションの連想配列。 使用可能なキーは以下のとおりです。

autocommit

DB2_AUTOCOMMIT_ON を渡すと、 この接続ハンドルで自動コミットを有効にします。

DB2_AUTOCOMMIT_OFF を渡すと、 この接続ハンドルで自動コミットを無効にします。

DB2_ATTR_CASE

DB2_CASE_NATURAL を渡すと、 カラム名の大文字小文字を変換せずに返します。

DB2_CASE_LOWER を渡すと、 カラム名を小文字に変換して返します。

DB2_CASE_UPPER を渡すと、 カラム名を大文字に変換して返します。

CURSOR

DB2_FORWARD_ONLY を渡すと、 ステートメントリソースで前進のみのカーソルを使用します。 これはデフォルトのカーソル型であり、 すべてのデータベースサーバーでサポートされています。

DB2_SCROLLABLE を渡すと、 ステートメントリソースでスクロール可能なカーソルを使用します。 このモードでは結果セット内の行へのランダムアクセスが可能となりますが、 現在は IBM DB2 Universal Database でしかサポートされていません。

以下の新しいオプションは、ibm_db2 のバージョン 1.7.0 以降で使用可能です。

trustedcontext

DB2_TRUSTED_CONTEXT_ENABLE を渡すと、この接続ハンドルでの信頼済みコンテキストを有効にします。 このパラメータを db2_set_option() で設定することはできません。

このキーは、カタログ接続の場合 (たとえローカルデータベースであっても) あるいは接続時に完全な DSN を指定した場合にのみ動作します。

データベースをカタログするには次のコマンドを実行します。

db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
db2 "update dbm cfg using svcename <SERVICENAME>"
db2set DB2COMM=TCPIP

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。

i5_lib

未解決のファイル参照を解決する際に使用するデフォルトのライブラリを指定します。 システムのネーミングモードを使用している接続の場合は、これは無効です。

i5_naming

DB2_I5_NAMING_ON は、DB2 UDB CLI iSeries のシステムネーミングモードを有効にします。ファイルの識別の際、 区切り文字としてスラッシュ (/) を使用します。 識別されないファイルの解決には、ジョブのライブラリ一覧を使用します。

DB2_I5_NAMING_OFF は、DB2 UDB CLI のデフォルトのネーミングモード (SQL ネーミング) を無効にします。 ファイルの識別の際、区切り文字としてピリオド (.) を使用します。 識別されないファイルの解決には、 デフォルトのライブラリあるいは現在のユーザー ID を使用します。

i5_commit

i5_commit 属性は、 db2_connect() の前に設定しなければなりません。 接続が確立された後にこの値が変更され、その接続がリモートデータソースに対するものだった場合は、 その接続ハンドルに対してもう一度 db2_connect() がコールされるまで変更は反映されません。

注意:

php.ini の設定は ibm_db2.i5_allow_commit==0 あるいは DB2_I5_TXN_NO_COMMIT がデフォルトです。 しかし、その設定よりも i5_commit オプションの内容のほうが優先されます。

DB2_I5_TXN_NO_COMMIT - コミットの管理を使用しません。

DB2_I5_TXN_READ_UNCOMMITTED - ダーティリード、 反復不能読み取り、ファントムリードが発生する可能性があります。

DB2_I5_TXN_READ_COMMITTED - ダーティリードは発生しません。 反復不能読み取り、ファントムリードが発生する可能性があります。

DB2_I5_TXN_REPEATABLE_READ - ダーティリード、 反復不能読み取りは発生しません。 ファントムリードが発生する可能性があります。

DB2_I5_TXN_SERIALIZABLE - トランザクションの一貫性を保持します。 ダーティリード、反復不能読み取り、ファントムリードは発生しません。

i5_query_optimize

DB2_FIRST_IO すべてのクエリは、結果の一行目をできるだけ早く返すように最適化されます。 これが有効なのは、出力の制御をユーザーが行う場合です。出力の制御とは、 たとえば、出力の最初のページを見てそこで処理を停止させるなどのことです。 OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。

DB2_ALL_IO すべてのクエリは、結果全体をできるだけ短時間で取得できるように最適化されます。 これは、結果をファイルや帳票に書き出す場合に有用なオプションです。 あるいは出力データを順次処理するインターフェイスなどにも有用です。 OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。 これはデフォルトの設定です。

i5_dbcs_alloc

DB2_I5_DBCS_ALLOC_ON は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを有効にします。

DB2_I5_DBCS_ALLOC_OFF は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを無効にします。

注意: php.ini では ibm_db2.i5_dbcs_alloc==0 あるいは DB2_I5_DBCS_ALLOC_OFF がデフォルト設定となっています。 しかし、i5_dbcs_alloc の値のほうが優先されます。

i5_date_fmt

DB2_I5_FMT_ISO - 国際標準化機構 (ISO) の日付書式 yyyy-mm-dd を使用します。デフォルトです。

DB2_I5_FMT_USA - 合衆国の日付書式 mm/dd/yyyy を使用します。

DB2_I5_FMT_EUR - 欧州の日付書式 dd.mm.yyyy を使用します。

DB2_I5_FMT_JIS - 日本工業規格 (JIS) の日付書式 yyyy-mm-dd を使用します。

DB2_I5_FMT_MDY - 日付書式 mm/dd/yyyy を使用します。

DB2_I5_FMT_DMY - 日付書式 dd/mm/yyyy を使用します。

DB2_I5_FMT_YMD - 日付書式 yy/mm/dd を使用します。

DB2_I5_FMT_JUL - ユリウス日 yy/ddd を使用します。

DB2_I5_FMT_JOB - そのジョブのデフォルトを使用します。

i5_date_sep

DB2_I5_SEP_SLASH - スラッシュ ( / ) を日付の区切り文字として使用します。 デフォルトです。

DB2_I5_SEP_DASH - ダッシュ ( - ) を日付の区切り文字として使用します。

DB2_I5_SEP_PERIOD - ピリオド ( . ) を日付の区切り文字として使用します。

DB2_I5_SEP_COMMA - カンマ ( , ) を日付の区切り文字として使用します。

DB2_I5_SEP_BLANK - ブランクを日付の区切り文字として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

i5_time_fmt

DB2_I5_FMT_ISO - 国際標準化機構 (ISO) の時刻書式 hh.mm.ss を使用します。デフォルトです。

DB2_I5_FMT_USA - 合衆国の時刻書式 hh:mmxx を使用します。xx には AM あるいは PM が入ります。

DB2_I5_FMT_EUR - 欧州の時刻書式 hh.mm.ss を使用します。

DB2_I5_FMT_JIS - 日本工業規格 (JIS) の時刻書式 hh:mm:ss を使用します。

DB2_I5_FMT_HMS - hh:mm:ss を使用します。

i5_time_sep

DB2_I5_SEP_COLON - コロン ( : ) を時刻の区切り文字として使用します。 デフォルトです。

DB2_I5_SEP_PERIOD - ピリオド ( . ) を時刻の区切り文字として使用します。

DB2_I5_SEP_COMMA - カンマ ( , ) を時刻の区切り文字として使用します。

DB2_I5_SEP_BLANK - ブランクを時刻の区切り文字として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

i5_decimal_sep

DB2_I5_SEP_PERIOD - ピリオド ( . ) を小数点として使用します。 デフォルトです。

DB2_I5_SEP_COMMA - カンマ ( , ) を小数点として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.8.0 以降で使用可能です。

i5_libl

ファイル参照を解決する際に用いるライブラリ一覧を表す文字。 ライブラリ一覧の項目を指定する際は、空白で区切って 'i5_libl'=>"MYLIB YOURLIB ANYLIB" のようにします。

注意:

i5_libl は qsys2/qcmdexc('cmd',cmdlen) をコールします。 これは i5/OS V5R4 以降でのみ使用可能です。

戻り値

接続に成功した場合は接続ハンドルリソースを返します。 接続に失敗した場合は、db2_connect() は false を返します。

例

例1 カタログ接続の作成

カタログ接続を行うには、DB2 コマンドラインプロセッサ (CLP) あるいは DB2 Configuration Assistant を使用して 事前に対象データベースをカタログしておく必要があります。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$conn = db2_connect($database, $user, $password);

if ($conn) {
echo "接続に成功しました。";
db2_close($conn);
}
else {
echo "接続に失敗しました。";
}
?>

上の例の出力は以下となります。

接続に成功しました。

例2 非カタログ接続の作成

非カタログ接続の場合は、データベースに動的に接続することができます。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$hostname = 'localhost';
$port = 50000;

$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
"HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
$conn = db2_connect($conn_string, '', '');

if ($conn) {
echo "接続に成功しました。";
db2_close($conn);
}
else {
echo "接続に失敗しました。";
}
?>

上の例の出力は以下となります。

接続に成功しました。

例3 自動コミットをデフォルトで無効にした接続の作成

オプションの配列を db2_connect() に渡すことで、接続ハンドルのデフォルトの振る舞いを変更できます。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

$conn = db2_connect($database, $user, $password, $options);

if ($conn) {
echo "接続に成功しました。\n";
if (db2_autocommit($conn)) {
echo "自動コミットが有効です。\n";
}
else {
echo "自動コミットは無効です。\n";
}
db2_close($conn);
}
else {
echo "接続に失敗しました。";
}
?>

上の例の出力は以下となります。

接続に成功しました。
自動コミットは無効です。

例4 i5/OS best performance

i5/OS で最高のパフォーマンスを引き出すためには、ibm_db2 1.5.1 を使用した PHP アプリケーションで db2_connect() にデフォルトのホスト、ユーザー ID およびパスワードを使用します。

<?php
$library = "ADC";
$i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
$result = db2_exec($i5,
"select * from systables where table_schema = '$library'");
while ($row = db2_fetch_both($result)) {
echo $row['TABLE_NAME']."</br>";
}
db2_close($i5);
?>

上の例の出力は以下となります。

ANIMALS
NAMES
PICTURES

例5 信頼済みコンテキストの使用

次の例は、信頼済みのコンテキストを有効にしてユーザーを変更し、現在のユーザー ID を取得するものです。

<?php

$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";

$tc_user = "tcuser";
$tc_pass = "tcpassword";

$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

$tc_conn = db2_connect($dsn, "", "", $options);
if($tc_conn) {
echo "Explicit trusted connection succeeded.\n";

if(db2_get_option($tc_conn, "trustedcontext")) {
$userBefore = db2_get_option($tc_conn, "trusted_user");

// user 1 で何らかの作業をします

// 信頼済みユーザーに切り替えます
$parameters = array("trusted_user" => $tc_user,
"trusted_password" => $tcuser_pass);
$res = db2_set_option ($tc_conn, $parameters, 1);

$userAfter = db2_get_option($tc_conn, "trusted_user");
// 信頼済みユーザーとして何らかの作業をします

if($userBefore != $userAfter) {
echo "User has been switched." . "\n";
}
}

db2_close($tc_conn);
}
else {
echo "Explicit trusted connection failed.\n";
}
?>

上の例の出力は以下となります。

Explicit trusted connection succeeded.
User has been switched.

参考

  • db2_close() - データベース接続を閉じる
  • db2_pconnect() - データベースへの持続的接続を返す


ステートメントリソースが使用しているカーソルの型を返す

  • ≪ db2_connect
  • db2_escape_string ≫
  • PHP Manual
  • IBM DB2 関数
  • ステートメントリソースが使用しているカーソルの型を返す

db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — ステートメントリソースが使用しているカーソルの型を返す

説明

db2_cursor_type(resource $stmt): int

ステートメントリソースが使用しているカーソルの型を返します。 使用中のカーソルが前進のみなのかスクロール可能なのかを調べるために、 これを使用します。

パラメータ

stmt

有効なステートメントリソース。

戻り値

ステートメントリソースが前進のみのカーソルを使用している場合に DB2_FORWARD_ONLY、スクロール可能なカーソルを 使用している場合に DB2_SCROLLABLE を返します。

参考

  • db2_prepare() - 実行する SQL 文を準備する


特定の文字をエスケープする

  • ≪ db2_cursor_type
  • db2_exec ≫
  • PHP Manual
  • IBM DB2 関数
  • 特定の文字をエスケープする

db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — 特定の文字をエスケープする

説明

db2_escape_string(string $string_literal): string

引数で指定した文字列中の特殊文字の前にバックスラッシュを追加します。

パラメータ

string_literal

変更すべき特殊文字を含む文字列。 \x00、 \n、\r、\、 '、" および \x1a について、その前にバックスラッシュを追加します。

戻り値

string_literal の中の上で挙げた文字について、 その前にバックスラッシュを追加した文字列を返します。

例

例1 db2_escape_string() の例

db2_escape_string() 関数を使用した結果

<?php

$conn = db2_connect($database, $user, $password);

if ($conn) {
$str[0] = "All characters: \x00 , \n , \r , \ , ' , \" , \x1a .";
$str[1] = "Backslash (\). Single quote ('). Double quote (\")";
$str[2] = "The NULL character \0 must be quoted as well";
$str[3] = "Intersting characters: \x1a , \x00 .";
$str[4] = "Nothing to quote";
$str[5] = 200676;
$str[6] = "";

foreach( $str as $string ) {
echo "db2_escape_string: " . db2_escape_string($string). "\n";
}
}
?>

上の例の出力は以下となります。

db2_escape_string: All characters: \0 , \n , \r , \\ , \' , \" , \Z .
db2_escape_string: Backslash (\\). Single quote (\'). Double quote (\")
db2_escape_string: The NULL character \0 must be quoted as well
db2_escape_string: Intersting characters: \Z , \0 .
db2_escape_string: Nothing to quote
db2_escape_string: 200676
db2_escape_string:

参考

  • db2_prepare() - 実行する SQL 文を準備する


SQL 文を直接実行する

  • ≪ db2_escape_string
  • db2_execute ≫
  • PHP Manual
  • IBM DB2 関数
  • SQL 文を直接実行する

db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — SQL 文を直接実行する

説明

db2_exec(resource $connection, string $statement, array $options = []): resource|false

SQL 文を直接実行します。

PHP 変数の内容を SQL 文に組み込みたい場合は、この関数を使用すると 典型的なセキュリティ上の問題を引き起こしかねないことを知っておきましょう。 db2_prepare() をコールして入力パラメータつきの SQL 文を準備することを検討してください。その後で db2_execute() をコールして入力値を渡すことで、 SQL インジェクション攻撃を避けることができます。

同じ SQL 文にさまざまなパラメータを指定して何度も発行する場合は、 db2_prepare() および db2_execute() の使用を検討してください。 これにより、データベースサーバーが実行計画を再利用することができて データベースアクセスの効率が向上します。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

statement

SQL 文。パラメータマーカを含めることはできません。

options

文のオプションを含む連想配列。 データベースサーバーがその機能をサポートしている場合に、 このパラメータを使用してスクロール可能なカーソルの使用を 要求することができます。

オプションについての説明は db2_set_option() を参照ください。

戻り値

SQL 文の実行に成功した場合にステートメントリソース、 SQL 文の実行に失敗した場合に false を返します。

例

例1 db2_exec() でのテーブルの作成

以下の例では、db2_exec() を使用して テーブルを作成する DDL 文を発行します。

<?php
$conn = db2_connect($database, $user, $password);

// テストテーブルを作成します
$create = 'CREATE TABLE animals (id INTEGER, breed VARCHAR(32),
name CHAR(16), weight DECIMAL(7,2))';
$result = db2_exec($conn, $create);
if ($result) {
print "テーブルの作成に成功しました。\n";
}

// テストテーブルに値を投入します
$animals = array(
array(0, 'cat', 'Pook', 3.2),
array(1, 'dog', 'Peaches', 12.3),
array(2, 'horse', 'Smarty', 350.0),
array(3, 'gold fish', 'Bubbles', 0.1),
array(4, 'budgerigar', 'Gizmo', 0.2),
array(5, 'goat', 'Rickety Ride', 9.7),
array(6, 'llama', 'Sweater', 150)
);

foreach ($animals as $animal) {
$rc = db2_exec($conn, "INSERT INTO animals (id, breed, name, weight)
VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
if ($rc) {
print "Insert... ";
}
}
?>

上の例の出力は以下となります。

テーブルの作成に成功しました。
Insert... Insert... Insert... Insert... Insert... Insert... Insert...

例2 スクロール可能なカーソルでの SELECT 文の実行

以下の例では、db2_exec() で発行された SQL 文にスクロール可能なカーソルを要求する方法を説明します。

<?php
$conn = db2_connect($database, $user, $password);
$sql = "SELECT name FROM animals
WHERE weight < 10.0
ORDER BY name";
if ($conn) {
require_once 'prepare.inc';
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_array($stmt)) {
print "$row[0]\n";
}
}
?>

上の例の出力は以下となります。

Bubbles
Gizmo
Pook
Rickety Ride

例3 XML データを SQL の結果セットとして返す

次の例は、XML カラムに格納されたデータの扱い方を、SAMPLE データベースを用いて説明するものです。ごく単純な SQL/XML を使用して、この例では XML ドキュメントのいくつかのノードを みなさんおなじみの SQL 結果セット形式で返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = 'SELECT * FROM XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" VARCHAR (50) PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) AS T
WHERE NAME = \'Kathy Smith\'
';
$stmt = db2_exec($conn, $query);

while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE\n");
}
db2_close($conn);

?>

上の例の出力は以下となります。

1000     Kathy Smith     416-555-1358
1001     Kathy Smith     905-555-7258

例4 XML データの "JOIN"

次の例は、SAMPLE データベースの 2 つの異なる XML カラムに格納されたドキュメントを使用します。 まず、2 つの異なるカラムの XML ドキュメントをもとにして 2 つのテンポラリテーブルを作成します。 そして特定の顧客の配送情報を SQL 結果セットで返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = '
SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
FROM
XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" BIGINT PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) as A,
PURCHASEORDER AS B,
XMLTABLE (
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
COLUMNS
"PONUM" BIGINT PATH \'@PoNum\',
"STATUS" VARCHAR (50) PATH \'@Status\'
) as C
WHERE A.CID = B.CUSTID AND
B.POID = C.PONUM AND
A.NAME = \'Kathy Smith\'
';

$stmt = db2_exec($conn, $query);

while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE $row->PONUM $row->STATUS\n");
}

db2_close($conn);

?>

上の例の出力は以下となります。

1001     Kathy Smith     905-555-7258     5002     Shipped

例5 大きな XML ドキュメントの一部を SQL データとして返す

次の例は、SAMPLE データベースのドキュメント PRODUCT.DESCRIPTION の一部を使用します。これは、商品の説明 (XML データ) および価格情報 (SQL データ) を含む XML ドキュメントを返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = '
SELECT
XMLSERIALIZE(
XMLQUERY(\'
declare boundary-space strip;
declare default element namespace "http://posample.org";
<promoList> {
for $prod in $doc/product
where $prod/description/price < 10.00
order by $prod/description/price ascending
return(
<promoitem> {
$prod,
<startdate> {$start} </startdate>,
<enddate> {$end} </enddate>,
<promoprice> {$promo} </promoprice>
} </promoitem>
)
} </promoList>
\' passing by ref DESCRIPTION AS "doc",
PROMOSTART as "start",
PROMOEND as "end",
PROMOPRICE as "promo"
RETURNING SEQUENCE)
AS CLOB (32000))
AS NEW_PRODUCT_INFO
FROM PRODUCT
WHERE PID = \'100-100-01\'
';

$stmt = db2_exec($conn, $query);

while($row = db2_fetch_array($stmt)){
printf("$row[0]\n");
}
db2_close($conn);

?>

上の例の出力は以下となります。

<promoList xmlns="http://posample.org">
    <promoitem>
    <product pid="100-100-01">
        <description>
            <name>Snow Shovel, Basic 22 inch</name>
            <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
            <price>9.99</price>
            <weight>1 kg</weight>
        </description>
    </product>
    <startdate>2004-11-19</startdate>
    <enddate>2004-12-19</enddate>
    <promoprice>7.25</promoprice>
    </promoitem>
</promoList>

参考

  • db2_execute() - プリペアドステートメントを実行する
  • db2_prepare() - 実行する SQL 文を準備する


プリペアドステートメントを実行する

  • ≪ db2_exec
  • db2_fetch_array ≫
  • PHP Manual
  • IBM DB2 関数
  • プリペアドステートメントを実行する

db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — プリペアドステートメントを実行する

説明

db2_execute(resource $stmt, array $parameters = []): bool

db2_execute() は、 db2_prepare() で準備された SQL 文を実行します。

SQL 文が結果セットを返す場合、例えば SELECT 文であったり 結果セットを返すストアドプロシージャの CALL であったりした場合には、 stmt から結果の行を配列として取得することができます。 取得には db2_fetch_assoc()、 db2_fetch_both() あるいは db2_fetch_array() を使用します。 あるいは、db2_fetch_row() を使用して 結果セットポインタを次の行に移動させ、 db2_result() で行の内容をその都度取得することも可能です。

db2_exec() の代わりに
db2_prepare() および
db2_execute() を使用することの利点については、
db2_prepare() での簡単な説明を参照ください。

パラメータ

stmt

db2_prepare() が返すプリペアドステートメント。

parameters

プリペアドステートメント内に含まれるパラメータマーカに対応する、 入力パラメータの配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 パラメータマーカを使用した SQL 文の準備と実行

以下の例では、4 つのパラメータマーカを含む INSERT 文を準備し、 入力値の配列を含む配列を順に処理しながら db2_execute() に値を渡します。

<?php
$pet = array(0, 'cat', 'Pook', 3.2);

$insert = 'INSERT INTO animals (id, breed, name, weight)
VALUES (?, ?, ?, ?)';

$stmt = db2_prepare($conn, $insert);
if ($stmt) {
$result = db2_execute($stmt, $pet);
if ($result) {
print "新しいペットの追加に成功しました。";
}
}
?>

上の例の出力は以下となります。

新しいペットの追加に成功しました。

例2 OUT パラメータを使用したストアドプロシージャのコール

以下の例では、まずひとつの OUT パラメータをパラメータマーカで受け取る CALL 文を準備し、db2_bind_param() を使用して PHP 変数 $my_pets をそのパラメータにバインドし、 db2_execute() で CALL 文を実行します。 ストアドプロシージャの CALL 終了後は、$num_pets にはストアドプロシージャの OUT パラメータに返された値が反映されています。

<?php
$num_pets = 0;
$res = db2_prepare($conn, "CALL count_my_pets(?)");
$rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
$rc = db2_execute($res);
print "私の飼っているペットの数は $num_pets です!";
?>

上の例の出力は以下となります。

私の飼っているペットの数は 7 です!

例3 XML データを SQL の結果セットとして返す

次の例は、XML カラムに格納されたデータの扱い方を、SAMPLE データベースを用いて説明するものです。ごく単純な SQL/XML を使用して、この例では XML ドキュメントのいくつかのノードを みなさんおなじみの SQL 結果セット形式で返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = 'SELECT * FROM XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" VARCHAR (50) PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) AS T
WHERE NAME = ?
';

$stmt = db2_prepare($conn, $query);

$name = 'Kathy Smith';

if ($stmt) {
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_execute($stmt);

while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE\n");
}
}
db2_close($conn);

?>

上の例の出力は以下となります。

1000     Kathy Smith     416-555-1358
1001     Kathy Smith     905-555-7258

例4 XML データの "JOIN"

次の例は、SAMPLE データベースの 2 つの異なる XML カラムに格納されたドキュメントを使用します。 まず、2 つの異なるカラムの XML ドキュメントをもとにして 2 つのテンポラリテーブルを作成します。 そして特定の顧客の配送情報を SQL 結果セットで返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = '
SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
FROM
XMLTABLE(
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
COLUMNS
"CID" BIGINT PATH \'@Cid\',
"NAME" VARCHAR (50) PATH \'name\',
"PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
) as A,
PURCHASEORDER AS B,
XMLTABLE (
XMLNAMESPACES (DEFAULT \'http://posample.org\'),
\'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
COLUMNS
"PONUM" BIGINT PATH \'@PoNum\',
"STATUS" VARCHAR (50) PATH \'@Status\'
) as C
WHERE A.CID = B.CUSTID AND
B.POID = C.PONUM AND
A.NAME = ?
';

$stmt = db2_prepare($conn, $query);

$name = 'Kathy Smith';

if ($stmt) {
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_execute($stmt);

while($row = db2_fetch_object($stmt)){
printf("$row->CID $row->NAME $row->PHONE $row->PONUM $row->STATUS\n");
}
}

db2_close($conn);

?>

上の例の出力は以下となります。

1001     Kathy Smith     905-555-7258     5002     Shipped

例5 大きな XML ドキュメントの一部を SQL データとして返す

次の例は、SAMPLE データベースのドキュメント PRODUCT.DESCRIPTION の一部を使用します。これは、商品の説明 (XML データ) および価格情報 (SQL データ) を含む XML ドキュメントを返します。

<?php

$conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

$query = '
SELECT
XMLSERIALIZE(
XMLQUERY(\'
declare boundary-space strip;
declare default element namespace "http://posample.org";
<promoList> {
for $prod in $doc/product
where $prod/description/price < 10.00
order by $prod/description/price ascending
return(
<promoitem> {
$prod,
<startdate> {$start} </startdate>,
<enddate> {$end} </enddate>,
<promoprice> {$promo} </promoprice>
} </promoitem>
)
} </promoList>
\' passing by ref DESCRIPTION AS "doc",
PROMOSTART as "start",
PROMOEND as "end",
PROMOPRICE as "promo"
RETURNING SEQUENCE)
AS CLOB (32000))
AS NEW_PRODUCT_INFO
FROM PRODUCT
WHERE PID = ?
';

$stmt = db2_prepare($conn, $query);

$pid = "100-100-01";

if ($stmt) {
db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
db2_execute($stmt);

while($row = db2_fetch_array($stmt)){
printf("$row[0]\n");
}
}

db2_close($conn);

?>

上の例の出力は以下となります。

<promoList xmlns="http://posample.org">
    <promoitem>
    <product pid="100-100-01">
        <description>
            <name>Snow Shovel, Basic 22 inch</name>
            <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
            <price>9.99</price>
            <weight>1 kg</weight>
        </description>
    </product>
    <startdate>2004-11-19</startdate>
    <enddate>2004-12-19</enddate>
    <promoprice>7.25</promoprice>
    </promoitem>
</promoList>

参考

  • db2_exec() - SQL 文を直接実行する
  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_prepare() - 実行する SQL 文を準備する
  • db2_result() - 結果セットの行からひとつのカラムを返す


結果セット内の行を表す、カラム位置をインデックスとする配列を返す

  • ≪ db2_execute
  • db2_fetch_assoc ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、カラム位置をインデックスとする配列を返す

db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — 結果セット内の行を表す、カラム位置をインデックスとする配列を返す

説明

db2_fetch_array(resource $stmt, int $row_number = -1): array|false

結果セット内の行を表す、カラム位置をインデックスとする配列を返します。 インデックスは 0 から始まります。

パラメータ

stmt

結果セットを含む有効な stmt リソース。

row_number

結果セット内の 1 から始まる行番号を指定します。 結果セットで前進のみのカーソルを使用している場合にこのパラメータを渡すと、 PHP の警告が発生します。

戻り値

結果セットの次の行あるいは要求した行のデータを表す配列を返します。 配列の 0 から始まるインデックスが、カラムの位置を表します。 結果セットに行がもうない場合、あるいは row_number で指定された行が結果セットに存在しない場合に false を返します。

例

例1 前進のみのカーソルを使用して順に処理する

行番号を指定せずに db2_fetch_array() をコールすると、 自動的に結果セットの次の行を取得します。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);

while ($row = db2_fetch_array($stmt)) {
printf ("%-5d %-16s %-32s %10s\n",
$row[0], $row[1], $row[2], $row[3]);
}
?>

上の例の出力は以下となります。

0     Pook             cat                                    3.20
5     Rickety Ride     goat                                   9.70
2     Smarty           horse                                350.00

例2 スクロール可能なカーソルから、指定した行を db2_fetch_array() で取得する

スクロール可能なカーソルを使用している場合は、行番号を指定して db2_fetch_array() をコールすることができます。 次の例は、結果セットの 2 行目から始めて 1 行おきにデータを取得します。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

$i=2;
while ($row = db2_fetch_array($result, $i)) {
printf ("%-5d %-16s %-32s %10s\n",
$row[0], $row[1], $row[2], $row[3]);
$i = $i + 2;
}
?>

上の例の出力は以下となります。

0     Pook             cat                                    3.20
5     Rickety Ride     goat                                   9.70
2     Smarty           horse                                350.00

参考

  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_object() - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_result() - 結果セットの行からひとつのカラムを返す


結果セット内の行を表す、カラム名をインデックスとする配列を返す

  • ≪ db2_fetch_array
  • db2_fetch_both ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、カラム名をインデックスとする配列を返す

db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — 結果セット内の行を表す、カラム名をインデックスとする配列を返す

説明

db2_fetch_assoc(resource $stmt, int $row_number = -1): array|false

結果セット内の行を表す、カラム名をインデックスとする配列を返します。

パラメータ

stmt

結果セットを含む有効な stmt リソース。

row_number

結果セット内の 1 から始まる行番号を指定します。 結果セットで前進のみのカーソルを使用している場合にこのパラメータを渡すと、 PHP の警告が発生します。

戻り値

結果セットの次の行あるいは要求した行のデータを表す、 カラム名をインデックスとした連想配列を返します。 結果セットに行がもうない場合、あるいは row_number で指定された行が結果セットに存在しない場合に false を返します。

例

例1 前進のみのカーソルを使用して順に処理する

行番号を指定せずに db2_fetch_assoc() をコールすると、 自動的に結果セットの次の行を取得します。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);

while ($row = db2_fetch_assoc($stmt)) {
printf ("%-5d %-16s %-32s %10s\n",
$row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
}
?>

上の例の出力は以下となります。

0     Pook             cat                                    3.20
5     Rickety Ride     goat                                   9.70
2     Smarty           horse                                350.00

例2 スクロール可能なカーソルから、指定した行を db2_fetch_assoc() で取得する

スクロール可能なカーソルを使用している場合は、行番号を指定して db2_fetch_assoc() をコールすることができます。 次の例は、結果セットの 2 行目から始めて 1 行おきにデータを取得します。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

$i=2;
while ($row = db2_fetch_assoc($result, $i)) {
printf ("%-5d %-16s %-32s %10s\n",
$row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
$i = $i + 2;
}
?>

上の例の出力は以下となります。

0     Pook             cat                                    3.20
5     Rickety Ride     goat                                   9.70
2     Smarty           horse                                350.00

参考

  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_object() - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_result() - 結果セットの行からひとつのカラムを返す


結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

  • ≪ db2_fetch_assoc
  • db2_fetch_object ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

説明

db2_fetch_both(resource $stmt, int $row_number = -1): array|false

結果セット内の行を表す、
カラム位置およびカラム名の両方をインデックスとする配列を返します。
db2_fetch_both() が返す行は、
一種類のインデックスしか返さない db2_fetch_assoc() あるいは
db2_fetch_array() よりもメモリを消費することに注意しましょう。

パラメータ

stmt

結果セットを含む有効な stmt リソース。

row_number

結果セット内の 1 から始まる行番号を指定します。 結果セットで前進のみのカーソルを使用している場合にこのパラメータを渡すと、 PHP の警告が発生します。

戻り値

結果セットの次の行あるいは要求した行のデータを表す、 カラム名および (0 から始まる) カラム番号の両方をインデックスとした連想配列を返します。 結果セットに行がもうない場合、あるいは row_number で指定された行が結果セットに存在しない場合に false を返します。

例

例1 前進のみのカーソルを使用して順に処理する

行番号を指定せずに db2_fetch_both() をコールすると、 自動的に結果セットの次の行を取得します。次の例では、 返された配列に対してカラム名および数値インデックスの両方でアクセスします。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
$result = db2_execute($stmt);

while ($row = db2_fetch_both($stmt)) {
printf ("%-5d %-16s %-32s %10s\n",
$row['ID'], $row[0], $row['BREED'], $row[3]);
}
?>

上の例の出力は以下となります。

0     Pook             cat                                    3.20
5     Rickety Ride     goat                                   9.70
2     Smarty           horse                                350.00

例2 スクロール可能なカーソルから、指定した行を db2_fetch_both() で取得する

スクロール可能なカーソルを使用している場合は、行番号を指定して db2_fetch_both() をコールすることができます。 次の例は、結果セットの 2 行目から始めて 1 行おきにデータを取得します。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

$i=2;
while ($row = db2_fetch_both($result, $i)) {
printf ("%-5d %-16s %-32s %10s\n",
$row[0], $row['NAME'], $row[2], $row['WEIGHT']);
$i = $i + 2;
}
?>

上の例の出力は以下となります。

0     Pook             cat                                    3.20
5     Rickety Ride     goat                                   9.70
2     Smarty           horse                                350.00

参考

  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_object() - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_result() - 結果セットの行からひとつのカラムを返す


結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

  • ≪ db2_fetch_both
  • db2_fetch_row ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

説明

db2_fetch_object(resource $stmt, int $row_number = -1): stdClass|false

結果セット内の行を表す、カラムをプロパティとするオブジェクトを返します。

パラメータ

stmt

結果セットを含む有効な stmt リソース。

row_number

結果セット内の 1 から始まる行番号を指定します。 結果セットで前進のみのカーソルを使用している場合にこのパラメータを渡すと、 PHP の警告が発生します。

戻り値

結果セット内の行を表すオブジェクトを返します。 オブジェクトのプロパティが、結果セット内のカラム名に対応します。

IBM DB2、Cloudscape および Apache Derby データベースサーバーは、 通常はカラム名を大文字として扱います。そのため、 オブジェクトのプロパティも同じようになります。

SELECT 文の中でスカラ関数をコールすることでカラムの値を変更している場合、 データベースサーバーは、そのカラムの名前としてカラム番号を返します。 もし何らかの意味のある名前をオブジェクトのプロパティとして使用したいのなら、 AS 句を使用して結果セット内のカラムに名前を割り当てる必要があります。

行が取得されなかった場合は false を返します。

例

例1 db2_fetch_object() の例

次の例では、スカラ関数 RTRIM を使用した SELECT 文を発行します。 この関数は、カラムの最後の空白を取り除きます。プロパティ "BREED" および "2" を持つオブジェクトを作成するのではなく、 SELECT 文で AS 句を使用し、変更したカラムに "name" という名前をつけます。 データベースサーバーはカラム名を大文字に変換するので、 返されるオブジェクトのプロパティは "BREED" および "NAME" となります。

<?php
$conn = db2_connect($database, $user, $password);

$sql = "SELECT breed, RTRIM(name) AS name
FROM animals
WHERE id = ?";

if ($conn) {
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(0));

while ($pet = db2_fetch_object($stmt)) {
echo "Come here, {$pet->NAME}, my little {$pet->BREED}!";
}
db2_close($conn);
}
?>

上の例の出力は以下となります。

Come here, Pook, my little cat!

参考

  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_result() - 結果セットの行からひとつのカラムを返す


結果セットポインタを次の行あるいは要求された行に設定する

  • ≪ db2_fetch_object
  • db2_field_display_size ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットポインタを次の行あるいは要求された行に設定する

db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — 結果セットポインタを次の行あるいは要求された行に設定する

説明

db2_fetch_row(resource $stmt, int $row_number = -1): bool

db2_fetch_row() を使用して結果セットを順に処理します。 あるいは、スクロール可能なカーソルを使用している場合は 指定した行を指すようにします。

結果セットから個々のフィールドを取得するには db2_result() 関数をコールします。

db2_fetch_row() および db2_result() をコールするのではなく、 ほとんどのアプリケーションでは db2_fetch_assoc()、db2_fetch_both()、 および db2_fetch_array() のいずれかをコールするでしょう。 これらは、結果セットのポインタを前に進めたうえで行の内容を配列として取得します。

パラメータ

stmt

有効な stmt リソース。

row_number

スクロール可能なカーソルの場合に、結果セットの行番号を指定します。 行番号は 1 から始まります。

戻り値

結果セットに指定した行が存在する場合に true、存在しない場合に false を返します。

例

例1 結果セットを順に処理する

次の例では、db2_fetch_row() を使用して結果セットを順に処理し、db2_result() で結果セットからカラムを取得する方法を示します。

<?php
$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(10));
while (db2_fetch_row($stmt)) {
$name = db2_result($stmt, 0);
$breed = db2_result($stmt, 1);
print "$name $breed";
}
?>

上の例の出力は以下となります。

cat Pook
gold fish Bubbles
budgerigar Gizmo
goat Rickety Ride

例2 i5/OS recommended alternatives to db2_fetch_row/db2_result

i5/OS では、db2_fetch_row()/db2_result()
ではなく db2_fetch_both()、
db2_fetch_array() あるいは db2_fetch_object()
を使用することを推奨します。一般に
db2_fetch_row()/db2_result() は、さまざまなカラム型で
EBCIDIC から ASCII への変換の際に問題が発生します。
DBCS アプリケーションではデータが切り捨てられてしまう可能性もあります。
また、パフォーマンス面でも db2_fetch_both()、
db2_fetch_array() および db2_fetch_object()
は db2_fetch_row()/db2_result()
よりすぐれています。

<?php
$conn = db2_connect("","","");
$sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_both($stmt)){
echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
}
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_array($stmt)){
echo "<br>db2_fetch_array {$row[1]} {$row[5]}";
}
$stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
while ($row = db2_fetch_object($stmt)){
echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
}
db2_close($conn);
?>

上の例の出力は以下となります。

db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

参考

  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_object() - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_result() - 結果セットの行からひとつのカラムを返す


カラムを表示するために必要な最大のバイト数を返す

  • ≪ db2_fetch_row
  • db2_field_name ≫
  • PHP Manual
  • IBM DB2 関数
  • カラムを表示するために必要な最大のバイト数を返す

db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — カラムを表示するために必要な最大のバイト数を返す

説明

db2_field_display_size(resource $stmt, int|string $column): int|false

結果セット内のカラムを表示するために必要な最大のバイト数を返す

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

指定したカラムを表示するために必要な最大バイト数を表す整数値を返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_display_size() は false を返します。

参考

  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


結果セット内のカラムの名前を返す

  • ≪ db2_field_display_size
  • db2_field_num ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内のカラムの名前を返す

db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — 結果セット内のカラムの名前を返す

説明

db2_field_name(resource $stmt, int|string $column): string|false

結果セット内の指定したカラムの名前を返します。

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

指定したカラムの名前を含む文字列を返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_name() は false を返します。

参考

  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


結果セット内の指定したカラムの位置を返す

  • ≪ db2_field_name
  • db2_field_precision ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの位置を返す

db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — 結果セット内の指定したカラムの位置を返す

説明

db2_field_num(resource $stmt, int|string $column): int|false

結果セット内の指定したカラムの位置を返します。

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

結果セット内でのカラムの位置を、0 から始まる整数値で返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_num() は false を返します。

参考

  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


結果セット内の指定したカラムの精度を返す

  • ≪ db2_field_num
  • db2_field_scale ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの精度を返す

db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — 結果セット内の指定したカラムの精度を返す

説明

db2_field_precision(resource $stmt, int|string $column): int|false

結果セット内の指定したカラムの精度を返します。

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

指定したカラムの精度を表す整数値を返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_precision() は false を返します。

参考

  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


結果セット内の指定したカラムの位取りを返す

  • ≪ db2_field_precision
  • db2_field_type ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの位取りを返す

db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — 結果セット内の指定したカラムの位取りを返す

説明

db2_field_scale(resource $stmt, int|string $column): int|false

結果セット内の指定したカラムの位取りを返します。

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

指定したカラムの位取りを整数値で返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_scale() は false を返します。

参考

  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


結果セット内の指定したカラムのデータ型を返す

  • ≪ db2_field_scale
  • db2_field_width ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムのデータ型を返す

db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — 結果セット内の指定したカラムのデータ型を返す

説明

db2_field_type(resource $stmt, int|string $column): string|false

結果セット内の指定したカラムのデータ型を返します。

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

指定したカラムに定義されているデータ型を表す文字列を返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_type() は false を返します。

参考

  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


結果セット内の指定したカラムの現在値の幅を返す

  • ≪ db2_field_type
  • db2_foreign_keys ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セット内の指定したカラムの現在値の幅を返す

db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — 結果セット内の指定したカラムの現在値の幅を返す

説明

db2_field_width(resource $stmt, int|string $column): int|false

結果セット内の指定したカラムの現在値の幅を返します。 固定長のデータ型では、この値はカラムの最大幅になります。 可変長のデータ型では、実際のカラムの幅となります。

パラメータ

stmt

結果セットを含むステートメントリソースを指定します。

column

結果セット内のカラムを指定します。0 から始まるインデックス、 あるいはカラム名を表す文字列のいずれかが使用可能です。

戻り値

結果セット内の文字型あるいはバイナリデータ型のカラムについて、 その幅を整数値で返します。 結果セット内にそのカラムが存在しない場合には、 db2_field_width() は false を返します。

参考

  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す


テーブルの外部キーを含む結果セットを返す

  • ≪ db2_field_width
  • db2_free_result ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルの外部キーを含む結果セットを返す

db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — テーブルの外部キーを含む結果セットを返す

説明

db2_foreign_keys(
resource $connection,
?string $qualifier,
?string $schema,
string $table_name
): resource

テーブルの外部キーを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。schema が null の場合は、db2_foreign_keys() 現在の接続のスキーマに一致します。

table_name

テーブルの名前。

戻り値

指定したテーブルの外部キーを含む結果セットのステートメントリソースを返します。 結果セットは、以下のカラムで構成されています。

カラム名 | 説明
PKTABLE_CAT | 主キーを含むテーブルのカタログの名前。 テーブルがカタログを保持していない場合は NULL。
PKTABLE_SCHEM | 主キーを含むテーブルのスキーマの名前。
PKTABLE_NAME | 主キーを含むテーブルの名前。
PKCOLUMN_NAME | 主キーを含むカラムの名前。
FKTABLE_CAT | 外部キーを含むテーブルのカタログの名前。 テーブルがカタログを保持していない場合は NULL。
FKTABLE_SCHEM | 外部キーを含むテーブルのスキーマの名前。
FKTABLE_NAME | 外部キーを含むテーブルの名前。
FKCOLUMN_NAME | 外部キーを含むカラムの名前。
KEY_SEQ | 1 から始まる数字で表した、キー内のカラムの位置。
UPDATE_RULE | SQL で UPDATE 操作を行った際に外部キーに適用される動作を表す整数値。
DELETE_RULE | SQL で DELETE 操作を行った際に外部キーに適用される動作を表す整数値。
FK_NAME | 外部キーの名前。
PK_NAME | 主キーの名前。
DEFERRABILITY | 外部キーの遅延度を表す整数値。 SQL_INITIALLY_DEFERRED、SQL_INITIALLY_IMMEDIATE あるいは SQL_NOT_DEFERRABLE のいずれか。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


結果セットに関連付けられたリソースを開放する

  • ≪ db2_foreign_keys
  • db2_free_stmt ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットに関連付けられたリソースを開放する

db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — 結果セットに関連付けられたリソースを開放する

説明

db2_free_result(resource $stmt): bool

結果セットに関連付けられたシステムリソースおよびデータベースリソースを 開放します。これらのリソースはスクリプトの終了時に暗黙的に開放されますが、 スクリプトの終了前に db2_free_result() をコールすることで、明示的に結果セットリソースを開放することができます。

パラメータ

stmt

有効なステートメントリソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • db2_free_stmt() - 指定されたステートメントリソースに関連付けられたリソースを開放する


指定されたステートメントリソースに関連付けられたリソースを開放する

  • ≪ db2_free_result
  • db2_get_option ≫
  • PHP Manual
  • IBM DB2 関数
  • 指定されたステートメントリソースに関連付けられたリソースを開放する

db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — 指定されたステートメントリソースに関連付けられたリソースを開放する

説明

db2_free_stmt(resource $stmt): bool

ステートメントリソースに関連付けられたシステムリソースおよびデータベースリソースを 開放します。これらのリソースはスクリプトの終了時に暗黙的に開放されますが、 スクリプトの終了前に db2_stmt_result() をコールすることで、明示的にステートメントリソースを開放することができます。

パラメータ

stmt

有効なステートメントリソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • db2_free_result() - 結果セットに関連付けられたリソースを開放する


ステートメントリソースあるいは接続リソースからオプションの値を取得する

  • ≪ db2_free_stmt
  • db2_last_insert_id ≫
  • PHP Manual
  • IBM DB2 関数
  • ステートメントリソースあるいは接続リソースからオプションの値を取得する

db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — ステートメントリソースあるいは接続リソースからオプションの値を取得する

説明

db2_get_option(resource $resource, string $option): string|false

ステートメントリソースあるいは接続リソースから、指定したオプションの値を取得します。

パラメータ

resource

db2_prepare() が返す有効なステートメントリソース、 あるいは db2_connect() や db2_pconnect() が返す有効な接続リソース。

option

ステートメントや接続の、有効なオプション。 以下の新しいオプションが、ibm_db2 バージョン 1.6.0 以降で使用可能です。 これらは、有用な情報を提供します。これらの情報は、 db2_get_option() によって取得します。

注意:

以前のバージョンの ibm_db2 では、これらの新しいオプションはサポートしていません。

各オプションの値を設定する際、 サーバーによっては指定したすべての内容を処理できないことがあります。 その場合、値が切り詰められます。

指定したオプションが正しく変換されてホストシステムに送信されることを確実にするには、 A から Z までの文字と 0 から 9 までの数字、そしてアンダースコア (_) とピリオド (.) のみを使用するようにします。

userid

SQL_ATTR_INFO_USERID - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのユーザー ID として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 16 文字までの長さをサポートしています。 このユーザー ID を、認証時に使用するユーザー ID と混同しないでください。 これは識別のためだけに使用するものであり、認証には用いられません。

acctstr

SQL_ATTR_INFO_ACCTSTR - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアカウンティング・ストリングとして使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 200 文字までの長さをサポートしています。

applname

SQL_ATTR_INFO_APPLNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアプリケーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 32 文字までの長さをサポートしています。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのワークステーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 18 文字までの長さをサポートしています。

次の表は、どのオプションがどのリソース型で使用できるのかをまとめたものです。

リソースとパラメータの対応
キー | 値 | リソース型
 |  | 接続 | ステートメント | 結果セット
userid | SQL_ATTR_INFO_USERID | X | X | -
acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | -
applname | SQL_ATTR_INFO_APPLNAME | X | X | -
wrkstnname | SQL_ATTR_INFO_WRKSTNNAME | X | X | -

戻り値

成功した場合に接続属性の現在の設定内容、 失敗した場合に false を返します。

例

例1 接続リソースのパラメータの設定および取得

<?php
/* データベースへの接続パラメータ */
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

/* 接続リソースの取得 */
$conn = db2_connect($database, $user, $password);

echo "Client attributes passed through connection string:\n";

/* 有効なキーと値のペアを持つ連想配列を作成 */
/* 接続文字列を介して属性をアサイン */
/* 指定されたオプションにアクセス */
$options1 = array('userid' => 'db2inst1');
$conn1 = db2_connect($database, $user, $password, $options1);
$val = db2_get_option($conn1, 'userid');
echo $val . "\n";

$options2 = array('acctstr' => 'account');
$conn2 = db2_connect($database, $user, $password, $options2);
$val = db2_get_option($conn2, 'acctstr');
echo $val . "\n";

$options3 = array('applname' => 'myapp');
$conn3 = db2_connect($database, $user, $password, $options3);
$val = db2_get_option($conn3, 'applname');
echo $val . "\n";

$options4 = array('wrkstnname' => 'workstation');
$conn4 = db2_connect($database, $user, $password, $options4);
$val = db2_get_option($conn4, 'wrkstnname');
echo $val . "\n";

echo "Client attributes passed post-connection:\n";

/* 有効なキーと値のペアを持つ連想配列を作成 */
/* 接続作成後に属性をアサイン */
/* 指定されたオプションにアクセス */
$options5 = array('userid' => 'db2inst1');
$conn5 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn5, $options5, 1);
$val = db2_get_option($conn5, 'userid');
echo $val . "\n";

$options6 = array('acctstr' => 'account');
$conn6 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn6, $options6, 1);
$val = db2_get_option($conn6, 'acctstr');
echo $val . "\n";

$options7 = array('applname' => 'myapp');
$conn7 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn7, $options7, 1);
$val = db2_get_option($conn7, 'applname');
echo $val . "\n";

$options8 = array('wrkstnname' => 'workstation');
$conn8 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn8, $options8, 1);
$val = db2_get_option($conn8, 'wrkstnname');
echo $val . "\n";
?>

上の例の出力は以下となります。

Client attributes passed through connection string:
db2inst1
account
myapp
workstation
Client attributes passed post-connection:
db2inst1
account
myapp
workstation

参考

  • db2_connect() - データベースへの接続を返す
  • db2_cursor_type() - ステートメントリソースが使用しているカーソルの型を返す
  • db2_exec() - SQL 文を直接実行する
  • db2_set_option() - 接続リソースあるいはステートメントリソースのオプションを設定する
  • db2_pconnect() - データベースへの持続的接続を返す
  • db2_prepare() - 実行する SQL 文を準備する


この接続上で最後に成功した insert クエリが自動生成した ID を返す

  • ≪ db2_get_option
  • db2_lob_read ≫
  • PHP Manual
  • IBM DB2 関数
  • この接続上で最後に成功した insert クエリが自動生成した ID を返す

db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — この接続上で最後に成功した insert クエリが自動生成した ID を返す

説明

db2_last_insert_id(resource $resource): ?string

この接続上で最後に成功した insert クエリが自動生成した ID を返します。

この関数の結果は、以下のいずれにも影響を受けません。

  • VALUE 句を使用した単一行の INSERT 文で、ID カラムを指定していないもの

  • VALUE 句を使用した複数行の INSERT 文

  • 全選択からの INSERT 文

  • ROLLBACK TO SAVEPOINT 文

パラメータ

resource

db2_connect() あるいは db2_pconnect() が返す接続リソース。 このパラメータにはステートメントリソースや結果セットリソースを指定することはできません。

戻り値

この接続上で最後に成功した insert クエリが自動生成した ID を返します。

例

例1 db2_last_insert_id() の例

次の例は、この接続上で最後に成功した insert クエリが自動生成した ID を返す方法を示します。

<?php

$database = "SAMPLE";
$user = "db2inst1";
$password = "ibmdb2";

$conn = db2_connect($database, $user, $password);
if($conn) {
$createTable = "CREATE TABLE lastInsertID
(id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
$insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

$stmt = @db2_exec($conn, $createTable);

/* Checking for single row inserted. */
$stmt = db2_exec($conn, $insertTable);
$ret = db2_last_insert_id($conn);
if($ret) {
echo "Last Insert ID is : " . $ret . "\n";
} else {
echo "No Last insert ID.\n";
}

db2_close($conn);
}
else {
echo "Connection failed.";
}
?>

上の例の出力は以下となります。

Last Insert ID is : 1


LOB ファイルから、ユーザーが定義したサイズの内容を取得する

  • ≪ db2_last_insert_id
  • db2_next_result ≫
  • PHP Manual
  • IBM DB2 関数
  • LOB ファイルから、ユーザーが定義したサイズの内容を取得する

db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — LOB ファイルから、ユーザーが定義したサイズの内容を取得する

説明

db2_lob_read(resource $stmt, int $colnum, int $length): string|false

db2_lob_read() により、 結果セットの指定したカラムから、指定したサイズの LOB データを取得します。

パラメータ

stmt

LOB データを含む有効な stmt リソース。

colnum

stmt リソースの結果セット内の、有効なカラム番号。

length

stmt リソースから取得する LOB データのサイズ。

戻り値

指定したサイズのデータを返します。データが取得できない場合は false を返します。

例

例1 さまざまな型のデータの取得

<?php

/* データベースへの接続パラメータ */
$db = 'SAMPLE';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続リソースの取得 */
$conn = db2_connect($db,$username,$password);

if ($conn) {
$drop = 'DROP TABLE clob_stream';
$result = @db2_exec( $conn, $drop );

$create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
$result = db2_exec( $conn, $create );

$variable = "";
$stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
$variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
db2_execute($stmt);

$sql = "SELECT id,my_clob FROM clob_stream";
$result = db2_prepare($conn, $sql);
db2_execute($result);
db2_fetch_row($result);
$i = 0;
/* LOB データの読み込み */
while ($data = db2_lob_read($result, 2, 6)) {
echo "Loop $i: $data\n";
$i = $i + 1;
}

$drop = 'DROP TABLE blob_stream';
$result = @db2_exec( $conn, $drop );

$create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
$result = db2_exec( $conn, $create );

$variable = "";
$stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
$variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
db2_execute($stmt);

$sql = "SELECT id,my_blob FROM blob_stream";
$result = db2_prepare($conn, $sql);
db2_execute($result);
db2_fetch_row($result);
$i = 0;
/* LOB データの読み込み */
while ($data = db2_lob_read($result, 2, 6)) {
echo "Loop $i: $data\n";
$i = $i + 1;
}
} else {
echo '接続に失敗しました: ' . db2_conn_errormsg();
}

?>

上の例の出力は以下となります。

Loop 0: THIS I
Loop 1: S A CL
Loop 2: OB TES
Loop 3: T. THI
Loop 4: S IS A
Loop 5:  CLOB
Loop 6: TEST.
Loop 0: THIS I
Loop 1: S A BL
Loop 2: OB TES
Loop 3: T. THI
Loop 4: S IS A
Loop 5:  BLOB
Loop 6: TEST.

参考

  • db2_bind_param() - PHP 変数を SQL 文のパラメータにバインドする
  • db2_exec() - SQL 文を直接実行する
  • db2_execute() - プリペアドステートメントを実行する
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する
  • db2_prepare() - 実行する SQL 文を準備する
  • db2_result() - 結果セットの行からひとつのカラムを返す


ストアドプロシージャから、次の結果セットを要求する

  • ≪ db2_lob_read
  • db2_num_fields ≫
  • PHP Manual
  • IBM DB2 関数
  • ストアドプロシージャから、次の結果セットを要求する

db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — ストアドプロシージャから、次の結果セットを要求する

説明

db2_next_result(resource $stmt): resource|false

ストアドプロシージャは、複数の結果セットを返すことができます。 単純な SELECT 文が返す結果を処理するのと同じように最初の結果セットを 扱った後でそれ以降の結果セットを処理する際には、 db2_next_result() 関数をコールして その戻り値を PHP 変数に代入しなければなりません。

パラメータ

stmt

db2_exec() あるいは db2_execute() から返されるプリペアドステートメント。

戻り値

ストアドプロシージャが別の結果セットを返している場合には 次の結果セットを含む新しいステートメントリソース、 別の結果セットを返していない場合には false を返します。

例

例1 複数の結果セットを返すストアドプロシージャをコールする

次の例では、3 つの結果セットを返すストアドプロシージャをコールします。 最初の結果セットは CALL 文を起動したのと同じステートメントリソースから 直接取得できますが、2 番目および 3 番目の結果セットは db2_next_result() が返すステートメントリソースから取得します。

<?php
$conn = db2_connect($database, $user, $password);

if ($conn) {
$stmt = db2_exec($conn, 'CALL multiResults()');

print "最初の結果セットを取得します\n";
while ($row = db2_fetch_array($stmt)) {
var_dump($row);
}

print "\n2 番目の結果セットを取得します\n";
$res = db2_next_result($stmt);
if ($res) {
while ($row = db2_fetch_array($res)) {
var_dump($row);
}
}

print "\n3 番目の結果セットを取得します\n";
$res2 = db2_next_result($stmt);
if ($res2) {
while ($row = db2_fetch_array($res2)) {
var_dump($row);
}
}

db2_close($conn);
}
?>

上の例の出力は以下となります。

最初の結果セットを取得します
array(2) {
  [0]=>
  string(16) "Bubbles         "
  [1]=>
  int(3)
}
array(2) {
  [0]=>
  string(16) "Gizmo           "
  [1]=>
  int(4)
}

2 番目の結果セットを取得します
array(4) {
  [0]=>
  string(16) "Sweater         "
  [1]=>
  int(6)
  [2]=>
  string(5) "llama"
  [3]=>
  string(6) "150.00"
}
array(4) {
  [0]=>
  string(16) "Smarty          "
  [1]=>
  int(2)
  [2]=>
  string(5) "horse"
  [3]=>
  string(6) "350.00"
}

3 番目の結果セットを取得します
array(1) {
  [0]=>
  string(16) "Bubbles         "
}
array(1) {
  [0]=>
  string(16) "Gizmo           "
}


結果セットに含まれるフィールドの数を返す

  • ≪ db2_next_result
  • db2_num_rows ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットに含まれるフィールドの数を返す

db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — 結果セットに含まれるフィールドの数を返す

説明

db2_num_fields(resource $stmt): int|false

結果セットに含まれるフィールドの数を返します。動的に生成されたクエリが返す 結果セットを処理する場合、あるいはストアドプロシージャから返された結果セットを 処理する場合など、結果セットの使用法がアプリケーションにわからない場合に有用です。

パラメータ

stmt

結果セットを含む有効なステートメントリソース。

戻り値

指定したステートメントリソースに関連付けられた結果セット内の フィールドの数を表す整数値を返します。ステートメントリソースが 不正な値の場合には false を返します。

例

例1 結果セットのフィールド数の取得

以下の例では、結果セットが返すフィールドの数を取得する方法を説明します。

<?php

$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, $sql);
$columns = db2_num_fields($stmt);

echo "結果セット内には {$columns} つのカラムがあります。";
?>

上の例の出力は以下となります。

結果セット内には 4 つのカラムがあります。

参考

  • db2_execute() - プリペアドステートメントを実行する
  • db2_field_display_size() - カラムを表示するために必要な最大のバイト数を返す
  • db2_field_name() - 結果セット内のカラムの名前を返す
  • db2_field_num() - 結果セット内の指定したカラムの位置を返す
  • db2_field_precision() - 結果セット内の指定したカラムの精度を返す
  • db2_field_scale() - 結果セット内の指定したカラムの位取りを返す
  • db2_field_type() - 結果セット内の指定したカラムのデータ型を返す
  • db2_field_width() - 結果セット内の指定したカラムの現在値の幅を返す


SQL 文によって変更された行の数を返す

  • ≪ db2_num_fields
  • db2_pclose ≫
  • PHP Manual
  • IBM DB2 関数
  • SQL 文によって変更された行の数を返す

db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — SQL 文によって変更された行の数を返す

説明

db2_num_rows(resource $stmt): int|false

SQL 文によって削除、挿入あるいは更新された行の数を返します。

SELECT 文が返す行の数を取得するには、調べたい SELECT 文と同じ述部を持つ SELECT COUNT(*) を発行し、その値を取得します。

SELECT 文が返す行の数を調べて 0 の場合には別の処理を行うようなロジックを アプリケーションで使用している場合、その代わりに db2_fetch_assoc()、db2_fetch_both()、 db2_fetch_array() あるいは db2_fetch_row() を使用して最初の行を取得し、 結果が false の場合には別の処理を行うという方法を検討してください。

注意:

スクロール可能なカーソルを使用して SELECT 文を発行した場合は、 db2_num_rows() は SELECT 文の結果の行数を返します。 しかし、スクロール可能なカーソルを使用すると、 アプリケーションのパフォーマンスが急激に低下します。 そのため、SELECT 文の結果の行数を知りたいというだけの理由で スクロール可能なカーソルを使用するのは避けましょう。 前進のみのカーソルを使用し、SELECT COUNT(*) をコールするか フェッチ関数の返す bool 値を調べるほうが、 同じ機能をずっと高速に実現できます。

パラメータ

stmt

結果セットを含む有効な stmt リソース。

戻り値

指定したステートメントハンドルによって発行された、 直近の SQL 文によって変更された行の数を返します。 失敗した場合に false を返します


持続的データベース接続を閉じる

  • ≪ db2_num_rows
  • db2_pconnect ≫
  • PHP Manual
  • IBM DB2 関数
  • 持続的データベース接続を閉じる

db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — 持続的データベース接続を閉じる

説明

db2_pclose(resource $connection): bool

この関数は、 db2_pconnect() で作成した DB2 クライアント接続を閉じ、 対応するリソースをデータベースサーバーに返します。

注意:

この関数は、i5/OS で i5/OS システム管理リクエストに対する応答としてのみ使用可能です。

持続的 DB2 クライアント接続を db2_pconnect() で作成した場合は、 この関数で接続を閉じることができるでしょう。それ以降の接続のパフォーマンスのことを考えて、 この関数使うのは特別な場合だけにしておかなければなりません。 たとえば持続的接続が無反応になったり 当分の間は持続的接続が不要になったりした場合です。

パラメータ

connection

アクティブな DB2 クライアント接続。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 持続的接続の終了

次の例は、IBM DB2 i5/OS データベースへの接続を閉じるものです。

<?php
$conn = db2_pconnect('', '', '');
$rc = db2_pclose($conn);
if ($rc) {
echo "Connection was successfully closed.";
}
?>

上の例の出力は以下となります。

Connection was successfully closed.

参考

  • db2_close() - データベース接続を閉じる
  • db2_pconnect() - データベースへの持続的接続を返す


データベースへの持続的接続を返す

  • ≪ db2_pclose
  • db2_prepare ≫
  • PHP Manual
  • IBM DB2 関数
  • データベースへの持続的接続を返す

db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — データベースへの持続的接続を返す

説明

db2_pconnect(
string $database,
?string $username,
?string $password,
array $options = []
): resource|false

IBM DB2 Universal Database、IBM Cloudscape あるいは Apache Derby データベースへの持続的接続を返します。

持続的接続についての詳細な情報は、 持続的データベース接続 を参照ください。

持続的接続に対して db2_close() をコールすると、 常に true を返します。しかし DB2 クライアント接続はオープンされたままであり、 条件に一致する次の db2_pconnect() リクエストを待ち続けます。

ibm_db2 のバージョン 1.9.0 以降を使っている場合は、 持続的接続上ではリクエストが終了するたびにトランザクションがロールバックされることに気をつけましょう。 リクエストが終了するたびにトランザクションも終了します。 これは、トランザクションによるブロックが次のリクエストまで持ち越されてしまって 同じ接続を利用する別のスクリプトの実行に影響するのを防ぐためです。

パラメータ

database

データベースへのカタログ接続向けでは、 database は、DB2 クライアントカタログ内のデータベースエイリアスを表します。

データベースへのカタログ接続向けでない場合、 database は、以下のフォーマットからなる完全な接続文字列を表します:

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

注意:

IBM i 上の Db2 に接続する場合、 以下のシステムコール » SQLDriverConnect は、DSN, UID, PWD だけを » connection string として受け入れます。たとえば以下のようになります:

DSN=database;UID=username;PWD=password;

この場合、パラメータは以下の値からなります:
database

データベースの名前

hostname

データベースサーバーのホスト名あるいは IP アドレス。

port

データベースが要求を待ち受ける TCP/IP ポート。

username

データベースに接続するユーザー名。

password

データベースに接続するパスワード。

username

データベースに接続するユーザー名。

password

データベースに接続するパスワード。

options

接続の振る舞いを指定する接続オプションの連想配列。 使用可能なキーは以下のとおりです。

autocommit

DB2_AUTOCOMMIT_ON を渡すと、 この接続ハンドルで自動コミットを有効にします。

DB2_AUTOCOMMIT_OFF を渡すと、 この接続ハンドルで自動コミットを無効にします。

DB2_ATTR_CASE

DB2_CASE_NATURAL を渡すと、 カラム名の大文字小文字を変換せずに返します。

DB2_CASE_LOWER を渡すと、 カラム名を小文字に変換して返します。

DB2_CASE_UPPER を渡すと、 カラム名を大文字に変換して返します。

CURSOR

DB2_FORWARD_ONLY を渡すと、 ステートメントリソースで前進のみのカーソルを使用します。 これはデフォルトのカーソル型であり、 すべてのデータベースサーバーでサポートされています。

DB2_SCROLLABLE を渡すと、 ステートメントリソースでスクロール可能なカーソルを使用します。 このモードでは結果セット内の行へのランダムアクセスが可能となりますが、 現在は IBM DB2 Universal Database でしかサポートされていません。

以下の新しいオプションは、ibm_db2 のバージョン 1.7.0 以降で使用可能です。

trustedcontext

DB2_TRUSTED_CONTEXT_ENABLE を渡すと、この接続ハンドルでの信頼済みコンテキストを有効にします。 このパラメータを db2_set_option() で設定することはできません。

このキーは、カタログ接続の場合 (たとえローカルデータベースであっても) あるいは接続時に完全な DSN を指定した場合にのみ動作します。

データベースをカタログするには次のコマンドを実行します。

db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
db2 "update dbm cfg using svcename <SERVICENAME>"
db2set DB2COMM=TCPIP

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。

ヒント

持続的接続と衝突する属性を使用すると、i5/OS では結果は未定義となります。 持続的接続のユーザープロファイルを使用するすべてのアプリケーションについて、 サイトポリシーを確立しておく必要があります。持続的接続を使用する場合は、 デフォルトの DB2_AUTOCOMMIT_ON をおすすめします。

i5_lib

未解決のファイル参照を解決する際に使用するデフォルトのライブラリを指定します。 システムのネーミングモードを使用している接続の場合は、これは無効です。

i5_naming

DB2_I5_NAMING_ON は、DB2 UDB CLI iSeries のシステムネーミングモードを有効にします。ファイルの識別の際、 区切り文字としてスラッシュ (/) を使用します。 識別されないファイルの解決には、ジョブのライブラリ一覧を使用します。

DB2_I5_NAMING_OFF は、DB2 UDB CLI のデフォルトのネーミングモード (SQL ネーミング) を無効にします。 ファイルの識別の際、区切り文字としてピリオド (.) を使用します。 識別されないファイルの解決には、 デフォルトのライブラリあるいは現在のユーザー ID を使用します。

i5_commit

i5_commit 属性は、 db2_pconnect() の前に設定しなければなりません。 接続が確立された後にこの値が変更され、その接続がリモートデータソースに対するものだった場合は、 その接続ハンドルに対してもう一度 db2_pconnect() がコールされるまで変更は反映されません。

注意:

php.ini の設定は ibm_db2.i5_allow_commit==0 あるいは DB2_I5_TXN_NO_COMMIT がデフォルトです。 しかし、その設定よりも i5_commit オプションの内容のほうが優先されます。

DB2_I5_TXN_NO_COMMIT - コミットの管理を使用しません。

DB2_I5_TXN_READ_UNCOMMITTED - ダーティリード、 反復不能読み取り、ファントムリードが発生する可能性があります。

DB2_I5_TXN_READ_COMMITTED - ダーティリードは発生しません。 反復不能読み取り、ファントムリードが発生する可能性があります。

DB2_I5_TXN_REPEATABLE_READ - ダーティリード、 反復不能読み取りは発生しません。 ファントムリードが発生する可能性があります。

DB2_I5_TXN_SERIALIZABLE - トランザクションの一貫性を保持します。 ダーティリード、反復不能読み取り、ファントムリードは発生しません。

i5_query_optimize

DB2_FIRST_IO すべてのクエリは、結果の一行目をできるだけ早く返すように最適化されます。 これが有効なのは、出力の制御をユーザーが行う場合です。出力の制御とは、 たとえば、出力の最初のページを見てそこで処理を停止させるなどのことです。 OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。

DB2_ALL_IO すべてのクエリは、結果全体をできるだけ短時間で取得できるように最適化されます。 これは、結果をファイルや帳票に書き出す場合に有用なオプションです。 あるいは出力データを順次処理するインターフェイスなどにも有用です。 OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。 これはデフォルトの設定です。

i5_dbcs_alloc

DB2_I5_DBCS_ALLOC_ON は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを有効にします。

DB2_I5_DBCS_ALLOC_OFF は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを無効にします。

注意:

php.ini では ibm_db2.i5_dbcs_alloc==0 あるいは DB2_I5_DBCS_ALLOC_OFF がデフォルト設定となっています。 しかし、i5_dbcs_alloc の値のほうが優先されます。

i5_date_fmt

DB2_I5_FMT_ISO - 国際標準化機構 (ISO) の日付書式 yyyy-mm-dd を使用します。デフォルトです。

DB2_I5_FMT_USA - 合衆国の日付書式 mm/dd/yyyy を使用します。

DB2_I5_FMT_EUR - 欧州の日付書式 dd.mm.yyyy を使用します。

DB2_I5_FMT_JIS - 日本工業規格 (JIS) の日付書式 yyyy-mm-dd を使用します。

DB2_I5_FMT_MDY - 日付書式 mm/dd/yyyy を使用します。

DB2_I5_FMT_DMY - 日付書式 dd/mm/yyyy を使用します。

DB2_I5_FMT_YMD - 日付書式 yy/mm/dd を使用します。

DB2_I5_FMT_JUL - ユリウス日 yy/ddd を使用します。

DB2_I5_FMT_JOB - そのジョブのデフォルトを使用します。

i5_date_sep

DB2_I5_SEP_SLASH - スラッシュ ( / ) を日付の区切り文字として使用します。 デフォルトです。

DB2_I5_SEP_DASH - ダッシュ ( - ) を日付の区切り文字として使用します。

DB2_I5_SEP_PERIOD - ピリオド ( . ) を日付の区切り文字として使用します。 separator.

DB2_I5_SEP_COMMA - カンマ ( , ) を日付の区切り文字として使用します。

DB2_I5_SEP_BLANK - ブランクを日付の区切り文字として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

i5_time_fmt

DB2_I5_FMT_ISO - 国際標準化機構 (ISO) の時刻書式 hh.mm.ss を使用します。デフォルトです。

DB2_I5_FMT_USA - 合衆国の時刻書式 hh:mmxx を使用します。xx には AM あるいは PM が入ります。

DB2_I5_FMT_EUR - 欧州の時刻書式 hh.mm.ss を使用します。

DB2_I5_FMT_JIS - 日本工業規格 (JIS) の時刻書式 hh:mm:ss を使用します。

DB2_I5_FMT_HMS - hh:mm:ss を使用します。

i5_time_sep

DB2_I5_SEP_COLON - コロン ( : ) を時刻の区切り文字として使用します。 デフォルトです。

DB2_I5_SEP_PERIOD - ピリオド ( . ) を時刻の区切り文字として使用します。

DB2_I5_SEP_COMMA - カンマ ( , ) を時刻の区切り文字として使用します。

DB2_I5_SEP_BLANK - ブランクを時刻の区切り文字として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

i5_decimal_sep

DB2_I5_SEP_PERIOD - ピリオド ( . ) を小数点として使用します。 デフォルトです。

DB2_I5_SEP_COMMA - カンマ ( , ) を小数点として使用します。

DB2_I5_SEP_JOB - そのジョブのデフォルトを使用します。

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.8.0 以降で使用可能です。

i5_libl

ファイル参照を解決する際に用いるライブラリ一覧を表す文字。 ライブラリ一覧の項目を指定する際は、空白で区切って 'i5_libl'=>"MYLIB YOURLIB ANYLIB" のようにします。

注意:

i5_libl は qsys2/qcmdexc('cmd',cmdlen) をコールします。 これは i5/OS V5R4 以降でのみ使用可能です。

戻り値

接続に成功した場合は接続ハンドルリソースを返します。 パラメータ database、username および password に完全に一致する接続が 既に存在した場合、db2_pconnect() はそれを再利用します。接続に失敗した場合は db2_pconnect() は false を返します。

変更履歴

バージョン | 説明
ibm_db2 1.9.0 | 持続的接続上のアクティブなトランザクションは、各接続の終了時にロールバックされるようになりました。
ibm_db2 1.8.0 | i5/OS ユーザーは i5_libl オプションが使えるようになりました。
ibm_db2 1.7.0 | trustedcontext オプションが使えるようになりました。
ibm_db2 1.5.1 | i5/OS ユーザーは i5_lib, i5_naming, i5_commit, i5_query_optimize, i5_dbcs_alloc, i5_date_fmt, i5_date_sep, i5_time_fmt, i5_time_sep および i5_decimal_sep が使えるようになりました。

例

例1 db2_pconnect() の例

以下の例で、最初に db2_pconnect() をコールした際には新しい持続的接続リソースを返します。 二度目に db2_pconnect() をコールすると、 最初の持続的接続のリソースが再利用されます。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$pconn = db2_pconnect($database, $user, $password);

if ($pconn) {
echo "持続的接続に成功しました。";
}
else {
echo "持続的接続に失敗しました。";
}

$pconn2 = db2_pconnect($database, $user, $password);
if ($pconn) {
echo "2 回目の持続的接続に成功しました。";
}
else {
echo "2 回目の持続的接続に失敗しました。";
}
?>

上の例の出力は以下となります。

持続的接続に成功しました。
2 回目の持続的接続に成功しました。

例2 信頼済みコンテキストの使用

次の例は、信頼済みのコンテキストを有効にしてユーザーを変更し、現在のユーザー ID を取得するものです。

<?php

$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";

$tc_user = "tcuser";
$tc_pass = "tcpassword";

$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
$options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

$tc_conn = db2_pconnect($dsn, "", "", $options);
if($tc_conn) {
echo "Explicit trusted connection succeeded.\n";

if(db2_get_option($tc_conn, "trustedcontext")) {
$userBefore = db2_get_option($tc_conn, "trusted_user");

// user 1 で何らかの作業をします

// 信頼済みユーザーに切り替えます
$parameters = array("trusted_user" => $tc_user,
"trusted_password" => $tcuser_pass);
$res = db2_set_option ($tc_conn, $parameters, 1);

$userAfter = db2_get_option($tc_conn, "trusted_user");
// 信頼済みユーザーとして何らかの作業をします

if($userBefore != $userAfter) {
echo "User has been switched." . "\n";
}
}

db2_close($tc_conn);
}
else {
echo "Explicit trusted connection failed.\n";
}
?>

上の例の出力は以下となります。

Explicit trusted connection succeeded.
User has been switched.

参考

  • db2_connect() - データベースへの接続を返す


実行する SQL 文を準備する

  • ≪ db2_pconnect
  • db2_primary_keys ≫
  • PHP Manual
  • IBM DB2 関数
  • 実行する SQL 文を準備する

db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — 実行する SQL 文を準備する

説明

db2_prepare(resource $connection, string $statement, array $options = []): resource|false

db2_prepare() は、プリペアドステートメントを作成します。 このプリペアドステートメントには、入力パラメータ・出力パラメータ あるいは入出力パラメータを表すパラメータマーカ (?) を含めることができます。プリペアドステートメントにパラメータを渡すには db2_bind_param() を使用します。 入力パラメータの場合についてのみ、db2_execute() に渡す配列で指定することも可能です。

アプリケーション内でプリペアドステートメントを使用する利点は、 以下の 3 つです。

  • パフォーマンス: 事前に文を準備しておくと、 その文によってデータを取得するための実行計画をデータベースサーバーが 最適化します。その後 db2_execute() でプリペアドステートメントを実行する際にはこの実行計画が再利用され、 実行時に実行計画を毎回作成することによるオーバーヘッドを避けられます。

  • セキュリティ: 事前に文を準備する際に、 入力値にパラメータマーカを含めることができます。 入力値にプレースホルダを使用してプリペアドステートメントを実行すると、 入力値の型がカラム定義あるいはパラメータ定義と一致することを データベースサーバーがチェックします。

  • 高機能: パラメータマーカの機能は、 単に入力値をプリペアドステートメントに渡すだけではありません。 db2_bind_param() を使用すると、 ストアドプロシージャの OUT パラメータおよび INOUT パラメータから 値を取得することも可能です。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

statement

ひとつ以上のパラメータマーカを含む SQL 文。

options

文のオプションを含む連想配列。 データベースサーバーがその機能をサポートしている場合に、 このパラメータを使用してスクロール可能なカーソルの使用を 要求することができます。

オプションについての説明は db2_set_option() を参照ください。

戻り値

SQL 文のパースに成功し、データベースサーバー内で正しく準備された場合に ステートメントリソースを返します。データベースサーバーがエラーを返した場合に false を返します。返されたエラーの詳細を調べるには、 db2_stmt_error() あるいは db2_stmt_errormsg() をコールします。

例

例1 パラメータマーカを使用した SQL 文の準備と実行

以下の例では、4 つのパラメータマーカを含む INSERT 文を準備し、 入力値の配列を含む配列を順に処理しながら db2_execute() に値を渡します。

<?php
$animals = array(
array(0, 'cat', 'Pook', 3.2),
array(1, 'dog', 'Peaches', 12.3),
array(2, 'horse', 'Smarty', 350.0),
);

$insert = 'INSERT INTO animals (id, breed, name, weight)
VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
foreach ($animals as $animal) {
$result = db2_execute($stmt, $animal);
}
}
?>

参考

  • db2_bind_param() - PHP 変数を SQL 文のパラメータにバインドする
  • db2_execute() - プリペアドステートメントを実行する
  • db2_stmt_error() - SQL 文が返す SQLSTATE を含む文字列を返す
  • db2_stmt_errormsg() - 直近の SQL 文のエラーメッセージを含む文字列を返す


テーブルの主キーを含む結果セットを返す

  • ≪ db2_prepare
  • db2_procedure_columns ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルの主キーを含む結果セットを返す

db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — テーブルの主キーを含む結果セットを返す

説明

db2_primary_keys(
resource $connection,
?string $qualifier,
?string $schema,
string $table_name
): resource

テーブルの主キーを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。schema が null の場合、db2_primary_keys() は現在の接続のスキーマを使用します。

table_name

テーブルの名前。

戻り値

指定したテーブルの主キーを含む結果セットのステートメントリソースを返します。 結果セットは、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | 主キーを含むテーブルのカタログの名前。 テーブルがカタログを保持していない場合は NULL。
TABLE_SCHEM | 主キーを含むテーブルのスキーマの名前。
TABLE_NAME | 主キーを含むテーブルの名前。
COLUMN_NAME | 主キーを含むカラムの名前。
KEY_SEQ | 1 から始まる数字で表した、キー内のカラムの位置。
PK_NAME | 主キーの名前。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


ストアドプロシージャのパラメータを含む結果セットを返す

  • ≪ db2_primary_keys
  • db2_procedures ≫
  • PHP Manual
  • IBM DB2 関数
  • ストアドプロシージャのパラメータを含む結果セットを返す

db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — ストアドプロシージャのパラメータを含む結果セットを返す

説明

db2_procedure_columns(
resource $connection,
?string $qualifier,
string $schema,
string $procedure,
?string $parameter
): resource

ストアドプロシージャのパラメータを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

プロシージャを含むスキーマ。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

procedure

プロシージャの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

parameter

パラメータの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。 このパラメータが null の場合、指定したストアドプロシージャの すべてのパラメータが返されます。

戻り値

指定したパラメータに一致するストアドプロシージャのパラメータ情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
PROCEDURE_CAT | プロシージャを含むカタログ。テーブルがカタログを保持していない場合は null。
PROCEDURE_SCHEM | ストアドプロシージャを含むスキーマの名前。
PROCEDURE_NAME | プロシージャの名前。
COLUMN_NAME | パラメータの名前。
COLUMN_TYPE

パラメータの型を表す整数値。

返される値 | パラメータの型
1 (SQL_PARAM_INPUT) | 入力 (IN) パラメータ。
2 (SQL_PARAM_INPUT_OUTPUT) | 入力/出力 (INOUT) パラメータ。
3 (SQL_PARAM_OUTPUT) | 出力 (OUT) パラメータ。
DATA_TYPE | パラメータの SQL データ型を表す整数値。
TYPE_NAME | パラメータのデータ型を表す文字列。
COLUMN_SIZE | パラメータのサイズを表す整数値。
BUFFER_LENGTH | このパラメータのデータを保存するために必要な最大バイト数。
DECIMAL_DIGITS | パラメータの位取り。位取りが適用できない場合は null。
NUM_PREC_RADIX | 10 (正確な数値データ型を表す)、 2 (概数データ型を表す)、 あるいは null (基数が適用できないデータ型を表す) のいずれか。
NULLABLE | パラメータが null 値をとることができるかどうかを表す整数値。
REMARKS | パラメータの説明。
COLUMN_DEF | パラメータのデフォルト値。
SQL_DATA_TYPE | パラメータのサイズを表す整数値。
SQL_DATETIME_SUB | datetime 型のコードを表す整数値、 あるいはこれが適用できない SQL データ型である場合に null。
CHAR_OCTET_LENGTH | 文字型のパラメータにおける最大のオクテット数。 シングルバイト文字セットのデータの場合、これは COLUMN_SIZE に一致します。文字型でないカラムの場合は null となります。
ORDINAL_POSITION | CALL 文の中でのパラメータの位置を表す、1 から始まるインデックス。
IS_NULLABLE | パラメータが null 値をとることができるかどうかを表す文字列。 'YES' の場合は null 値をとることができ、 'NO' の場合はできません。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

  • ≪ db2_procedure_columns
  • db2_result ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

説明

db2_procedures(
resource $connection,
?string $qualifier,
string $schema,
string $procedure
): resource

データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

プロシージャを含むスキーマ。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

procedure

プロシージャの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

戻り値

指定したパラメータに一致するストアドプロシージャの情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
PROCEDURE_CAT | プロシージャを含むカタログ。テーブルがカタログを保持していない場合は null。
PROCEDURE_SCHEM | ストアドプロシージャを含むスキーマの名前。
PROCEDURE_NAME | プロシージャの名前。
NUM_INPUT_PARAMS | ストアドプロシージャの入力 (IN) パラメータの数。
NUM_OUTPUT_PARAMS | ストアドプロシージャの出力 (OUT) パラメータの数。
NUM_RESULT_SETS | ストアドプロシージャが返す結果セットの数。
REMARKS | ストアドプロシージャのコメント。
PROCEDURE_TYPE | 常に 1 を返します。これは、 ストアドプロシージャが戻り値を返さないことを意味します。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


結果セットの行からひとつのカラムを返す

  • ≪ db2_procedures
  • db2_rollback ≫
  • PHP Manual
  • IBM DB2 関数
  • 結果セットの行からひとつのカラムを返す

db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — 結果セットの行からひとつのカラムを返す

説明

db2_result(resource $stmt, int|string $column): ?mixed

db2_result() を使用して、 結果セットの現在の行から指定したカラムの値を取得します。 結果セットポインタの位置を指定するため、db2_result() のコール前には db2_fetch_row() をコールする必要があります。

パラメータ

stmt

有効な stmt リソース。

column

結果セット内のカラムの位置を表す 0 から始まるインデックス、 あるいはカラム名を表す文字列。

戻り値

指定したフィールドが結果セットに存在する場合にそのフィールドの値を返します。 フィールドが存在しない場合には null を返し、警告を発生させます。

例

例1 db2_result() の例

以下の例では、db2_fetch_row() で結果セットを 順に処理し、db2_result() で結果セットから カラムを取得する方法を説明します。

<?php
$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
$stmt = db2_prepare($conn, $sql);
db2_execute($stmt, array(10));
while (db2_fetch_row($stmt)) {
$name = db2_result($stmt, 0);
$breed = db2_result($stmt, 'BREED');
print "$name $breed";
}
?>

上の例の出力は以下となります。

cat Pook
gold fish Bubbles
budgerigar Gizmo
goat Rickety Ride

参考

  • db2_fetch_array() - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
  • db2_fetch_assoc() - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
  • db2_fetch_both() - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
  • db2_fetch_object() - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
  • db2_fetch_row() - 結果セットポインタを次の行あるいは要求された行に設定する


トランザクションをロールバックする

  • ≪ db2_result
  • db2_server_info ≫
  • PHP Manual
  • IBM DB2 関数
  • トランザクションをロールバックする

db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — トランザクションをロールバックする

説明

db2_rollback(resource $connection): bool

指定した接続リソース上で実行中のトランザクションをロールバックし、 新しいトランザクションを開始します。PHP アプリケーションのデフォルトは AUTOCOMMIT モードなので、接続リソースに対して AUTOCOMMIT を無効にしていない限り db2_rollback() は何の意味もありません。

パラメータ

connection

db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 DELETE 文のロールバック

以下の例では、テーブルの行数を数えた後にデータベース接続の AUTOCOMMIT を無効にし、テーブルのすべての行を削除した上で、 行数が 0 となっていることを確認します。 それから、db2_rollback() を発行して再度行数を取得し、 DELETE 文の発行前の状態に戻っていることを確認します。 これにより、トランザクションのロールバックが正常に行われたことを示します。

<?php
$conn = db2_connect($database, $user, $password);

if ($conn) {
$stmt = db2_exec($conn, "SELECT count(*) FROM animals");
$res = db2_fetch_array( $stmt );
echo $res[0] . "\n";

// AUTOCOMMIT を無効にします
db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

// ANIMALS のすべての行を削除します
db2_exec($conn, "DELETE FROM animals");

$stmt = db2_exec($conn, "SELECT count(*) FROM animals");
$res = db2_fetch_array( $stmt );
echo $res[0] . "\n";

// DELETE 文をロールバックします
db2_rollback( $conn );

$stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
$res = db2_fetch_array( $stmt );
echo $res[0] . "\n";
db2_close($conn);
}
?>

上の例の出力は以下となります。

7
0
7

参考

  • db2_autocommit() - データベース接続の AUTOCOMMIT の状態を取得または設定する
  • db2_commit() - トランザクションをコミットする


DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

  • ≪ db2_rollback
  • db2_set_option ≫
  • PHP Manual
  • IBM DB2 関数
  • DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

説明

db2_server_info(resource $connection): stdClass|false

この関数は、IBM DB2、Cloudscape あるいは Apache Derby データベースサーバーについての情報を 読み取り専用のプロパティに保持するオブジェクトを返します。 以下の表は、データベースサーバーのプロパティの一覧です。

データベースサーバーのプロパティ
プロパティ名 | 戻り値の型 | 説明
DBMS_NAME | string | 接続中のデータベースサーバーの名前。DB2 サーバーの場合は、 DB2 の後にサーバーが稼動している OS の名前が続きます。
DBMS_VER | string | データベースサーバーのバージョン。"MM.mm.uuuu" という形式の文字列で、 MM がメジャーバージョン、 mm がマイナーバージョン、 そして uuuu がアップデートを表します。 例えば "08.02.0001" は メジャーバージョン 8、マイナーバージョン 2、アップデート 1 を表します。
DB_CODEPAGE | int | 接続中のデータベースのコードページ。
DB_NAME | string | 接続中のデータベースの名前。
DFT_ISOLATION string サーバーがサポートしているデフォルトのトランザクション分離レベル。
UR

非コミット読み取り: 変更内容は、他のトランザクションからも すぐに見えるようになります。

CS

カーソル固定: あるトランザクションで読み込まれた行を、 別のトランザクションから変更してコミットすることができます。

RS

読み取り固定: 検索条件あるいは実行中のトランザクションに 一致する行を、トランザクションから追加したり削除したりできます。

RR

反復可能読み取り: 実行中のトランザクションに影響を受けるデータは、 他のトランザクションからは見えません。

NC

コミット不可: 変更内容は、操作が終了した時点で見えるようになります。 明示的なコミットやロールバックはできません。

IDENTIFIER_QUOTE_CHAR | string | 識別子を区切るための文字。
INST_NAME | string | データベースを含むデータベースサーバーのインスタンス名。
ISOLATION_OPTION | array | データベースサーバーがサポートする分離オプション。 分離オプションについては DFT_ISOLATION プロパティの説明を参照ください。
KEYWORDS | array | データベースサーバーの予約語の配列。
LIKE_ESCAPE_CLAUSE | bool | データベースサーバーがワイルドカード文字 % および _ の使用をサポートしている場合に true、 これらのワイルドカードをサポートしていない場合に false。
MAX_COL_NAME_LEN | int | データベースサーバーがサポートするカラム名の最大バイト数。
MAX_IDENTIFIER_LEN | int | データベースサーバーがサポートする SQL 識別子の最大文字数。
MAX_INDEX_SIZE | int | データベースサーバーがサポートするインデックスつきカラムの最大バイト数。
MAX_PROC_NAME_LEN | int | データベースサーバーがサポートするプロシージャ名の最大バイト数。
MAX_ROW_SIZE | int | データベースサーバーがサポートするベーステーブルの行の最大バイト数。
MAX_SCHEMA_NAME_LEN | int | データベースサーバーがサポートするスキーマ名の最大バイト数。
MAX_STATEMENT_LEN | int | データベースサーバーがサポートする SQL 文の最大バイト数。
MAX_TABLE_NAME_LEN | int | データベースサーバーがサポートするテーブル名の最大バイト数。
NON_NULLABLE_COLUMNS | bool | データベースサーバーがカラムの NOT NULL 定義をサポートしている場合に true、サポートしていない場合に false。
PROCEDURES | bool | データベースサーバーがストアドプロシージャをコールするための CALL 文をサポートしている場合に true、サポートしていない場合に false。
SPECIAL_CHARS | string | 識別子として使用可能な文字のうち、 a-Z、0-9 およびアンダースコア以外の文字。
SQL_CONFORMANCE string データベースサーバーの ANSI/ISO SQL-92 仕様への対応レベル。
ENTRY

SQL-92 エントリレベルに準拠しています。

FIPS127

FIPS-127-2 transitional に準拠しています。

FULL

SQL-92 完全レベルに準拠しています。

INTERMEDIATE

SQL-92 中間レベルに準拠しています。

パラメータ

connection

アクティブな DB2 クライアント接続を指定します。

戻り値

成功した場合にオブジェクトを返します。 失敗した場合に false を返します

例

例1 db2_server_info() の例

サーバーの情報を取得するには、有効なデータベース接続リソースを db2_server_info() に渡す必要があります。

<?php

$conn = db2_connect('sample', 'db2inst1', 'ibmdb2');

$server = db2_server_info( $conn );

if ($server) {
echo "DBMS_NAME: "; var_dump( $server->DBMS_NAME );
echo "DBMS_VER: "; var_dump( $server->DBMS_VER );
echo "DB_CODEPAGE: "; var_dump( $server->DB_CODEPAGE );
echo "DB_NAME: "; var_dump( $server->DB_NAME );
echo "INST_NAME: "; var_dump( $server->INST_NAME );
echo "SPECIAL_CHARS: "; var_dump( $server->SPECIAL_CHARS );
echo "KEYWORDS: "; var_dump( sizeof($server->KEYWORDS) );
echo "DFT_ISOLATION: "; var_dump( $server->DFT_ISOLATION );
echo "ISOLATION_OPTION: ";
$il = '';
foreach( $server->ISOLATION_OPTION as $opt )
{
$il .= $opt." ";
}
var_dump( $il );
echo "SQL_CONFORMANCE: "; var_dump( $server->SQL_CONFORMANCE );
echo "PROCEDURES: "; var_dump( $server->PROCEDURES );
echo "IDENTIFIER_QUOTE_CHAR: "; var_dump( $server->IDENTIFIER_QUOTE_CHAR );
echo "LIKE_ESCAPE_CLAUSE: "; var_dump( $server->LIKE_ESCAPE_CLAUSE );
echo "MAX_COL_NAME_LEN: "; var_dump( $server->MAX_COL_NAME_LEN );
echo "MAX_ROW_SIZE: "; var_dump( $server->MAX_ROW_SIZE );
echo "MAX_IDENTIFIER_LEN: "; var_dump( $server->MAX_IDENTIFIER_LEN );
echo "MAX_INDEX_SIZE: "; var_dump( $server->MAX_INDEX_SIZE );
echo "MAX_PROC_NAME_LEN: "; var_dump( $server->MAX_PROC_NAME_LEN );
echo "MAX_SCHEMA_NAME_LEN: "; var_dump( $server->MAX_SCHEMA_NAME_LEN );
echo "MAX_STATEMENT_LEN: "; var_dump( $server->MAX_STATEMENT_LEN );
echo "MAX_TABLE_NAME_LEN: "; var_dump( $server->MAX_TABLE_NAME_LEN );
echo "NON_NULLABLE_COLUMNS: "; var_dump( $server->NON_NULLABLE_COLUMNS );

db2_close($conn);
}
?>

上の例の出力は以下となります。

DBMS_NAME: string(9) "DB2/LINUX"
DBMS_VER: string(10) "08.02.0000"
DB_CODEPAGE: int(1208)
DB_NAME: string(6) "SAMPLE"
INST_NAME: string(8) "db2inst1"
SPECIAL_CHARS: string(2) "@#"
KEYWORDS: int(179)
DFT_ISOLATION: string(2) "CS"
ISOLATION_OPTION: string(12) "UR CS RS RR "
SQL_CONFORMANCE: string(7) "FIPS127"
PROCEDURES: bool(true)
IDENTIFIER_QUOTE_CHAR: string(1) """
LIKE_ESCAPE_CLAUSE: bool(true)
MAX_COL_NAME_LEN: int(30)
MAX_ROW_SIZE: int(32677)
MAX_IDENTIFIER_LEN: int(18)
MAX_INDEX_SIZE: int(1024)
MAX_PROC_NAME_LEN: int(128)
MAX_SCHEMA_NAME_LEN: int(30)
MAX_STATEMENT_LEN: int(2097152)
MAX_TABLE_NAME_LEN: int(128)
NON_NULLABLE_COLUMNS: bool(true)

参考

  • db2_client_info() - DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す


接続リソースあるいはステートメントリソースのオプションを設定する

  • ≪ db2_server_info
  • db2_special_columns ≫
  • PHP Manual
  • IBM DB2 関数
  • 接続リソースあるいはステートメントリソースのオプションを設定する

db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する

説明

db2_set_option(resource $resource, array $options, int $type): bool

ステートメントリソースあるいは接続リソースのオプションを設定します。 結果セットリソースのオプションを設定することはできません。

パラメータ

resource

db2_prepare() が返す有効なステートメントリソースか、
あるいは db2_connect() や
db2_pconnect() が返す有効な接続リソース。

options

ステートメントあるいは接続のオプションを含む連想配列。 このパラメータは、自動コミットの値を変更したりカーソルの型を (スクロール可能、あるいは前進のみに) 変更したり、結果セットに表示されるカラム名を (小文字、大文字、あるいは元のままに) 設定したりする際に使用します。

autocommit

DB2_AUTOCOMMIT_ON を渡すと、 指定した接続リソースの自動コミットをオンにします。

DB2_AUTOCOMMIT_OFF を渡すと、 指定した接続リソースの自動コミットをオフにします。

cursor

DB2_FORWARD_ONLY を渡すと、 ステートメントリソースに前進のみのカーソルを指定します。 これはデフォルトのカーソル型であり、 すべてのデータベースサーバーでサポートされています。

DB2_SCROLLABLE を渡すと、 ステートメントリソースにスクロール可能なカーソルを指定します。 このカーソルは、順番どおり以外の方法で結果セットの行にアクセス可能です。 しかし、IBM DB2 Universal Database でしかサポートされていません。

binmode

DB2_BINARY を渡すと、 バイナリデータがそのままの形式で返されるようになります。 これはデフォルトのモードです。php.ini で ibm_db2.binmode=1 とするのと同じことです。

DB2_CONVERT を渡すと、 バイナリデータを十六進エンコーディングで変換して返します。 これは、php.ini で ibm_db2.binmode=2 とするのと同じことです。

DB2_PASSTHRU を渡すと、 バイナリデータを null に変換するようになります。これは php.ini で ibm_db2.binmode=3 とするのと同じことです。

db2_attr_case

DB2_CASE_LOWER を渡すと、 結果セットのカラム名を小文字で返します。

DB2_CASE_UPPER を渡すと、 結果セットのカラム名を大文字で返します。

DB2_CASE_NATURAL を渡すと、 結果セットのカラム名をそのまま何もせずに返します。

deferred_prepare

DB2_DEFERRED_PREPARE_ON を渡すと、 指定したステートメントリソースについて遅延プリペアを有効にします。

DB2_DEFERRED_PREPARE_OFF を渡すと、 指定したステートメントリソースについて遅延プリペアを無効にします。

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。 これらのオプションが適用されるのは、PHP と ibm_db2 が i5 システム上でネイティブに動作している場合のみです。

i5_fetch_only

DB2_I5_FETCH_ON - カーソルは読み込み専用となり、場所を指定しての更新や削除には使用できません。 これは、SQL_ATTR_FOR_FETCH_ONLY が SQL_FALSE に設定されていない場合のデフォルト設定です。

DB2_I5_FETCH_OFF - カーソルは、場所を指定しての更新や削除に使用できるようになります。

以下の新しいオプションが、ibm_db2 バージョン 1.8.0 以降で使用可能です。

rowcount

DB2_ROWCOUNT_PREFETCH_ON - クライアントは、取得する前に全行数を問い合わせることができます。つまり、 ROLLFORWARD_ONLY カーソルを使っている場合でも 選択された行数を db2_num_rows() で取得することができます。

DB2_ROWCOUNT_PREFETCH_OFF - クライアントは、取得する前に全行数を問い合わせることができません。

以下の新しいオプションが、ibm_db2 バージョン 1.7.0 以降で使用可能です。

trusted_user

ユーザーを信頼済みユーザーに変更する際に、信頼済みユーザーのユーザー ID (文字列) をこのキーの値として渡します。 このオプションは、接続リソース上でのみ設定可能です。 このオプションを使用するには、 信頼済みコンテキストを接続リソース上で有効にしなければなりません。

trusted_password

trusted_user キーで指定したユーザーに対応するパスワード (文字列)。

以下の新しいオプションが、ibm_db2 バージョン 1.6.0 以降で使用可能です。 これらは、有用な情報を提供します。これらの情報は、 db2_get_option() によって取得します。

注意:

各オプションの値を設定する際、 サーバーによっては指定したすべての内容を処理できないことがあります。 その場合、値が切り詰められます。

指定したオプションが正しく変換されてホストシステムに送信されることを確実にするには、 A から Z までの文字と 0 から 9 までの数字、そしてアンダースコア (_) とピリオド (.) のみを使用するようにします。

userid

SQL_ATTR_INFO_USERID - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのユーザー ID として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 16 文字までの長さをサポートしています。 このユーザー ID を、認証時に使用するユーザー ID と混同しないでください。 これは識別のためだけに使用するものであり、認証には用いられません。

acctstr

SQL_ATTR_INFO_ACCTSTR - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアカウンティング・ストリングとして使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 200 文字までの長さをサポートしています。

applname

SQL_ATTR_INFO_APPLNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのアプリケーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 32 文字までの長さをサポートしています。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信する クライアントのワークステーション名として使用します。

注意:

z/OS および OS/390 サーバー版の DB2 は 18 文字までの長さをサポートしています。

type

この関数に渡すリソースの型を、整数値で指定します。 リソースの型とこの値は必ず一致していなければなりません。

1 は、 接続リソースがこの関数に渡されることを表します。

1 以外の整数を指定すると、 ステートメントリソースがこの関数に渡されることを表します。

次の表は、それぞれのオプションがどのリソース型で使用可能かをまとめたものです。

リソースとパラメータの対応
キー | 値 | リソースの型
 |  | 接続 | ステートメント | 結果セット
autocommit | DB2_AUTOCOMMIT_ON | X | - | -
autocommit | DB2_AUTOCOMMIT_OFF | X | - | -
cursor | DB2_SCROLLABLE | - | X | -
cursor | DB2_FORWARD_ONLY | - | X | -
binmode | DB2_BINARY | X | X | -
binmode | DB2_CONVERT | X | X | -
binmode | DB2_PASSTHRU | X | X | -
db2_attr_case | DB2_CASE_LOWER | X | X | -
db2_attr_case | DB2_CASE_UPPER | X | X | -
db2_attr_case | DB2_CASE_NATURAL | X | X | -
deferred_prepare | DB2_DEFERRED_PREPARE_ON | - | X | -
deferred_prepare | DB2_DEFERRED_PREPARE_OFF | - | X | -
i5_fetch_only | DB2_I5_FETCH_ON | - | X | -
i5_fetch_only | DB2_I5_FETCH_OFF | - | X | -
rowcount | DB2_ROWCOUNT_PREFETCH_ON | - | X | -
rowcount | DB2_ROWCOUNT_PREFETCH_OFF | - | X | -
trusted_user | <USER NAME> (文字列) | X | - | -
trusted_password | <PASSWORD> (文字列) | X | - | -
userid | SQL_ATTR_INFO_USERID | X | X | -
acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | -
applname | SQL_ATTR_INFO_APPLNAME | X | X | -
wrkstnname | SQL_ATTR_INFO_WRKSTNNAME | X | X | -

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 接続リソースにひとつのパラメータを設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
echo 'オプションの設定に成功しました';
}
else
{
echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションの設定に成功しました

例2 接続リソースに複数のパラメータを設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
echo 'オプションの設定に成功しました';
}
else
{
echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションの設定に成功しました

例3 複数のパラメータを間違ったキーで設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'MY_INVALID_KEY' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
echo 'オプションの設定に成功しました';
}
else
{
echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例4 複数のパラメータを間違った値で設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => 'INVALID_VALUE',
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
echo 'オプションの設定に成功しました';
}
else
{
echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例5 複数のパラメータを接続リソースに設定する (間違った型を指定する)

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして間違った型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 2);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
echo 'オプションの設定に成功しました';
}
else
{
echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例6 複数のパラメータを間違ったリソースに設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

/* 間違ったリソース、そして正しいオプションの配列と型を表す値を指定して関数をコールします */
$result = db2_set_option($stmt, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
echo 'オプションの設定に成功しました';
}
else
{
echo 'オプションが設定できませんでした';
}
?>

上の例の出力は以下となります。

オプションが設定できませんでした

例7 すべてひとつにまとめる

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));

/* スクロール可能なカーソルのため、1 行目より先に 2 行目を取得します */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));

?>

上の例の出力は以下となります。

Array
(
    [empno] => 000140
    [firstnme] => HEATHER
    [midinit] => A
    [lastname] => NICHOLLS
    [workdept] => C01
    [phoneno] => 1793
    [hiredate] => 1976-12-15
    [job] => ANALYST
    [edlevel] => 18
    [sex] => F
    [birthdate] => 1946-01-19
    [salary] => 28420.00
    [bonus] => 600.00
    [comm] => 2274.00
)

Array
(
    [empno] => 000130
    [firstnme] => DELORES
    [midinit] => M
    [lastname] => QUINTANA
    [workdept] => C01
    [phoneno] => 4578
    [hiredate] => 1971-07-28
    [job] => ANALYST
    [edlevel] => 16
    [sex] => F
    [birthdate] => 1925-09-15
    [salary] => 23800.00
    [bonus] => 500.00
    [comm] => 1904.00
)

例8 i5/OS カーソルは読み込み専用

<?php
$conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
$stmt = db2_prepare($conn, 'select * from names where first = ?');
$name = "first2";
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
$options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
db2_set_option($stmt,$options,0);
if (db2_execute($stmt)) {
while ($row = db2_fetch_array($stmt)) {
echo "{$row[0]} {$row[1]}";
}
}
?>

上の例の出力は以下となります。

first2 last2

参考

  • db2_connect() - データベースへの接続を返す
  • db2_pconnect() - データベースへの持続的接続を返す
  • db2_exec() - SQL 文を直接実行する
  • db2_prepare() - 実行する SQL 文を準備する
  • db2_cursor_type() - ステートメントリソースが使用しているカーソルの型を返す


テーブルのユニーク行 ID カラムを含む結果セットを返す

  • ≪ db2_set_option
  • db2_statistics ≫
  • PHP Manual
  • IBM DB2 関数
  • テーブルのユニーク行 ID カラムを含む結果セットを返す

db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — テーブルのユニーク行 ID カラムを含む結果セットを返す

説明

db2_special_columns(
resource $connection,
?string $qualifier,
string $schema,
string $table_name,
int $scope
): resource

テーブルのユニーク行 ID カラムを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。

table_name

テーブルの名前。

scope

ユニーク行 ID の有効期間の最小値を表す整数値。 以下の値のいずれかとなります。

整数値 | SQL 定数 | 説明
0 | SQL_SCOPE_CURROW | 行 ID は、カーソルがその行にある場合にのみ有効です。
1 | SQL_SCOPE_TRANSACTION | 行 ID は、そのトランザクションの間のみ有効です。
2 | SQL_SCOPE_SESSION | 行 ID は、その接続の間のみ有効です。

戻り値

テーブルのユニーク行 ID 情報を含む結果セットの ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
SCOPE

整数値 | SQL 定数 | 説明
0 | SQL_SCOPE_CURROW | 行 ID は、カーソルがその行にある場合にのみ有効です。
1 | SQL_SCOPE_TRANSACTION | 行 ID は、そのトランザクションの間のみ有効です。
2 | SQL_SCOPE_SESSION | 行 ID は、その接続の間のみ有効です。
COLUMN_NAME | ユニークカラムの名前。
DATA_TYPE | カラムの SQL データ型。
TYPE_NAME | カラムの SQL データ型を文字列で表したもの。
COLUMN_SIZE | カラムのサイズを表す整数値。
BUFFER_LENGTH | このカラムのデータを保存するために必要な最大のバイト数。
DECIMAL_DIGITS | カラムの位取り。位取りが適用できない場合は null。
NUM_PREC_RADIX | 10 (正確な数値データ型を表す)、 2 (概数データ型を表す)、 あるいは null (基数が適用できないデータ型を表す) のいずれか。
PSEUDO_COLUMN | 常に 1 を返します。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


インデックスの情報およびテーブルの統計情報を含む結果セットを返す

  • ≪ db2_special_columns
  • db2_stmt_error ≫
  • PHP Manual
  • IBM DB2 関数
  • インデックスの情報およびテーブルの統計情報を含む結果セットを返す

db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — インデックスの情報およびテーブルの統計情報を含む結果セットを返す

説明

db2_statistics(
resource $connection,
?string $qualifier,
?string $schema,
string $table_name,
bool $unique
): resource

インデックスの情報およびテーブルの統計情報を含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

対象となるテーブルを含むスキーマ。 このパラメータを null にすると、現在のユーザーのスキーマについての 統計およびインデックスが返されます。

table_name

テーブルの名前。

unique

unique が true の場合、 テーブルのすべてのインデックス情報を返します。 そうでない場合、 テーブルのユニークインデックスに関する情報だけを返します。

戻り値

指定したパラメータに一致するテーブルの統計およびインデックスを含む ステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | テーブルを含むカタログの名前。テーブルがカタログを保持していない場合は null。
TABLE_SCHEM | テーブルを含むスキーマの名前。
TABLE_NAME | テーブルの名前。
NON_UNIQUE

インデックスが一意でなければならないかどうか、 あるいはその行がテーブルの統計情報であるかどうかを表す整数値。

戻り値 | パラメータの型
0 (SQL_FALSE) | インデックスは、重複した値をとることができます。
1 (SQL_TRUE) | インデックスは、一意でなければなりません。
null | この行は、テーブル自身についての統計情報です。
INDEX_QUALIFIER | インデックスの資格を満たすため、INDEX_NAME の先頭に付加しなければならない修飾子を表す文字列。
INDEX_NAME | インデックスの名前を表す文字列。
TYPE

結果セットのこの行に含まれる情報の型を表す整数値。

戻り値 | パラメータの型
0 (SQL_TABLE_STAT) | この行は、テーブル自身の統計情報を含みます。
1 (SQL_INDEX_CLUSTERED) | この行は、クラスタ化インデックスについての情報を含みます。
2 (SQL_INDEX_HASH) | この行は、ハッシュインデックスについての情報を含みます。
3 (SQL_INDEX_OTHER) | この行は、クラスタ化もハッシュも行われていない インデックスについての情報を含みます。
ORDINAL_POSITION | インデックス内の、1 から始まるカラムの位置。 その行がテーブル自身についての統計情報を含んでいる場合は null。
COLUMN_NAME | インデックス内のカラムの名前。 その行がテーブル自身についての統計情報を含んでいる場合は null。
ASC_OR_DESC | カラムの並び順が昇順の場合は A、 降順の場合は D、 その行がテーブル自身についての統計情報を含んでいる場合は null。
CARDINALITY

その行がインデックスの情報を含んでいる場合、このカラムには インデックス内の一意な値の数を表す整数値が含まれます。

その行がテーブル自身についての情報を含んでいる場合、 このカラムにはテーブルの行数を表す整数値が含まれます。

PAGES

その行がインデックスの情報を含んでいる場合、このカラムには インデックスを保存するために使用しているページ数を表す整数値が含まれます。

その行がテーブル自身についての情報を含んでいる場合、このカラムには テーブルを保存するために使用しているページ数を表す整数値が含まれます。

FILTER_CONDITION | 常に null。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


SQL 文が返す SQLSTATE を含む文字列を返す

  • ≪ db2_statistics
  • db2_stmt_errormsg ≫
  • PHP Manual
  • IBM DB2 関数
  • SQL 文が返す SQLSTATE を含む文字列を返す

db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — SQL 文が返す SQLSTATE を含む文字列を返す

説明

db2_stmt_error(?resource $stmt = null): string

SQL 文が返す SQLSTATE を含む文字列を返します。

db2_stmt_error() の引数にステートメントリソースを 渡さなかった場合は、直近で (例えば db2_prepare() あるいは db2_exec() を使用して) 返そうとしたステートメントリソースに関連する SQLSTATE を返します。

SQLSTATE の値の意味を調べるには、DB2 コマンドラインプロセッサのプロンプトで 次のコマンドを発行します。 db2 '? sqlstate-value' また、db2_stmt_errormsg() をコールして、 明示的なエラーメッセージと、それに関連する SQLCODE の値を取得することも可能です。

パラメータ

stmt

有効なステートメントリソース。

戻り値

SQLSTATE を含む文字列を返します。

参考

  • db2_conn_error() - 直近の接続から返された SQLSTATE を含む文字列を返す
  • db2_conn_errormsg() - 直近の接続エラーメッセージおよび SQLCODE を返す
  • db2_stmt_errormsg() - 直近の SQL 文のエラーメッセージを含む文字列を返す


直近の SQL 文のエラーメッセージを含む文字列を返す

  • ≪ db2_stmt_error
  • db2_table_privileges ≫
  • PHP Manual
  • IBM DB2 関数
  • 直近の SQL 文のエラーメッセージを含む文字列を返す

db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — 直近の SQL 文のエラーメッセージを含む文字列を返す

説明

db2_stmt_errormsg(?resource $stmt = null): string

直近の SQL 文のエラーメッセージを含む文字列を返します。

db2_stmt_errormsg() の引数にステートメントリソースを 渡さなかった場合は、直近で (例えば db2_prepare() あるいは db2_exec() を使用して) 返そうとしたステートメントリソースに関連するエラーメッセージを返します。

パラメータ

stmt

有効なステートメントリソース。

戻り値

SQL 文の発行により直近に発生したエラーを表す エラーメッセージおよび SQLSTATE を返します。

参考

  • db2_conn_error() - 直近の接続から返された SQLSTATE を含む文字列を返す
  • db2_conn_errormsg() - 直近の接続エラーメッセージおよび SQLCODE を返す
  • db2_stmt_error() - SQL 文が返す SQLSTATE を含む文字列を返す


データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

  • ≪ db2_stmt_errormsg
  • db2_tables ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

説明

db2_table_privileges(
resource $connection,
?string $qualifier = null,
?string $schema = null,
?string $table_name = null
): resource

データベース内のテーブルおよび関連する権限情報を含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。このパラメータには、ワイルドカードとして _ および % を含む検索パターンを指定することができます。

table_name

テーブルの名前。このパラメータには、ワイルドカードとして _ および % を含む検索パターンを指定することができます。

戻り値

指定したパラメータに一致するテーブルの権限情報を含むステートメントリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | テーブルを含むカタログの名前。テーブルがカタログを保持していない場合は null。
TABLE_SCHEM | テーブルを含むスキーマの名前。
TABLE_NAME | テーブルの名前。
GRANTOR | その権限を与えたユーザーの認証 ID。
GRANTEE | その権限を与えられたユーザーの認証 ID。
PRIVILEGE | 与えられた権限。ALTER、 CONTROL、DELETE、INDEX、INSERT、REFERENCES、SELECT あるいは UPDATE のいずれかです。
IS_GRANTABLE | grantee が、この権限を他のユーザーに与えることができるかどうかを、 文字列 "YES" あるいは "NO" で表す。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_tables() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す


データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

  • ≪ db2_table_privileges
  • MongoDB ≫
  • PHP Manual
  • IBM DB2 関数
  • データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

説明

db2_tables(
resource $connection,
?string $qualifier = null,
?string $schema = null,
?string $table_name = null,
?string $table_type = null
): resource

データベース内のテーブルおよび関連するメタデータを含む結果セットを返します。

パラメータ

connection

IBM DB2、Cloudscape あるいは Apache Derby データベースへの有効な接続。

qualifier

OS/390 あるいは z/OS サーバー上で稼動している DB2 データベースの修飾子。 その他のデータベースの場合には null あるいは空の文字列を渡します。

schema

テーブルを含むスキーマ。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

table_name

テーブルの名前。このパラメータでは、ワイルドカードとして _ および % を含む検索パターンを使用可能です。

table_type

テーブル型の識別子をカンマで区切ったリスト。 すべてのテーブル型を指定するには、null あるいは空の文字列を指定します。 有効なテーブル型識別子は ALIAS、HIERARCHY TABLE、INOPERATIVE VIEW、NICKNAME、 MATERIALIZED QUERY TABLE、SYSTEM TABLE、TABLE、TYPED TABLE、TYPED VIEW および VIEW です。

戻り値

指定したパラメータに一致するテーブルの情報を含む結果セットのリソースを返します。 行の内容は、以下のカラムで構成されています。

カラム名 | 説明
TABLE_CAT | テーブルを含むカタログ。テーブルがカタログを保持していない場合は null。
TABLE_SCHEM | テーブルを含むスキーマの名前。
TABLE_NAME | テーブルの名前。
TABLE_TYPE | テーブルの型識別子。
REMARKS | テーブルの説明。

参考

  • db2_column_privileges() - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
  • db2_columns() - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
  • db2_foreign_keys() - テーブルの外部キーを含む結果セットを返す
  • db2_primary_keys() - テーブルの主キーを含む結果セットを返す
  • db2_procedure_columns() - ストアドプロシージャのパラメータを含む結果セットを返す
  • db2_procedures() - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
  • db2_special_columns() - テーブルのユニーク行 ID カラムを含む結果セットを返す
  • db2_statistics() - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
  • db2_table_privileges() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す


MongoDB Extension

This extension is developed atop the » libmongoc and » libbson libraries. It provides a minimal API for core driver functionality: commands, queries, writes, connection management, and BSON serialization.

Userland PHP libraries that depend on this extension may provide higher level APIs, such as query builders, individual command helper methods, and GridFS. Application developers should consider using this extension in conjunction with the » MongoDB PHP library, which implements the same higher level APIs found in MongoDB drivers for other languages. This separation of concerns allows the extension to focus on essential features for which an extension implementation is paramount for performance.

  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • 定義済み定数
  • Tutorials
    • Using the PHP Library for MongoDB (PHPLIB)
    • Application Performance Monitoring (APM)
  • Driver Architecture and Internals — Explains the driver architecture, and special features
    • Architecture — Architecture Overview
    • Connections — Connection handling and persistence
    • Persisting Data — Serialization and deserialization of PHP variables into MongoDB
  • Security
    • Request Injection Attacks
    • Script Injection Attacks
  • MongoDB\Driver — MongoDB Extension Classes
    • MongoDB\Driver\Manager — The MongoDB\Driver\Manager class
    • MongoDB\Driver\Command — The MongoDB\Driver\Command class
    • MongoDB\Driver\Query — The MongoDB\Driver\Query class
    • MongoDB\Driver\BulkWrite — The MongoDB\Driver\BulkWrite class
    • MongoDB\Driver\Session — The MongoDB\Driver\Session class
    • MongoDB\Driver\ClientEncryption — The MongoDB\Driver\ClientEncryption class
    • MongoDB\Driver\ServerApi — The MongoDB\Driver\ServerApi class
    • MongoDB\Driver\WriteConcern — The MongoDB\Driver\WriteConcern class
    • MongoDB\Driver\ReadPreference — The MongoDB\Driver\ReadPreference class
    • MongoDB\Driver\ReadConcern — The MongoDB\Driver\ReadConcern class
    • MongoDB\Driver\Cursor — The MongoDB\Driver\Cursor class
    • MongoDB\Driver\CursorId — The MongoDB\Driver\CursorId class
    • MongoDB\Driver\CursorInterface — The MongoDB\Driver\CursorInterface interface
    • MongoDB\Driver\Server — The MongoDB\Driver\Server class
    • MongoDB\Driver\ServerDescription — The MongoDB\Driver\ServerDescription class
    • MongoDB\Driver\TopologyDescription — The MongoDB\Driver\TopologyDescription class
    • MongoDB\Driver\WriteConcernError — The MongoDB\Driver\WriteConcernError class
    • MongoDB\Driver\WriteError — The MongoDB\Driver\WriteError class
    • MongoDB\Driver\WriteResult — The MongoDB\Driver\WriteResult class
  • MongoDB\BSON — MongoDB BSON Classes and Functions
    • 関数
    • MongoDB\BSON\Document — The MongoDB\BSON\Document class
    • MongoDB\BSON\PackedArray — The MongoDB\BSON\PackedArray class
    • MongoDB\BSON\Iterator — The MongoDB\BSON\Iterator class
    • MongoDB\BSON\Binary — The MongoDB\BSON\Binary class
    • MongoDB\BSON\Decimal128 — The MongoDB\BSON\Decimal128 class
    • MongoDB\BSON\Javascript — The MongoDB\BSON\Javascript class
    • MongoDB\BSON\MaxKey — The MongoDB\BSON\MaxKey class
    • MongoDB\BSON\MinKey — The MongoDB\BSON\MinKey class
    • MongoDB\BSON\ObjectId — The MongoDB\BSON\ObjectId class
    • MongoDB\BSON\Regex — The MongoDB\BSON\Regex class
    • MongoDB\BSON\Timestamp — The MongoDB\BSON\Timestamp class
    • MongoDB\BSON\UTCDateTime — The MongoDB\BSON\UTCDateTime class
    • MongoDB\BSON\Type — The MongoDB\BSON\Type interface
    • MongoDB\BSON\Persistable — The MongoDB\BSON\Persistable interface
    • MongoDB\BSON\Serializable — The MongoDB\BSON\Serializable interface
    • MongoDB\BSON\Unserializable — The MongoDB\BSON\Unserializable interface
    • MongoDB\BSON\BinaryInterface — The MongoDB\BSON\BinaryInterface interface
    • MongoDB\BSON\Decimal128Interface — The MongoDB\BSON\Decimal128Interface interface
    • MongoDB\BSON\JavascriptInterface — The MongoDB\BSON\JavascriptInterface interface
    • MongoDB\BSON\MaxKeyInterface — The MongoDB\BSON\MaxKeyInterface interface
    • MongoDB\BSON\MinKeyInterface — The MongoDB\BSON\MinKeyInterface interface
    • MongoDB\BSON\ObjectIdInterface — The MongoDB\BSON\ObjectIdInterface interface
    • MongoDB\BSON\RegexInterface — The MongoDB\BSON\RegexInterface interface
    • MongoDB\BSON\TimestampInterface — The MongoDB\BSON\TimestampInterface interface
    • MongoDB\BSON\UTCDateTimeInterface — The MongoDB\BSON\UTCDateTimeInterface interface
    • MongoDB\BSON\DBPointer — The MongoDB\BSON\DBPointer class (deprecated)
    • MongoDB\BSON\Int64 — The MongoDB\BSON\Int64 class
    • MongoDB\BSON\Symbol — The MongoDB\BSON\Symbol class (deprecated)
    • MongoDB\BSON\Undefined — The MongoDB\BSON\Undefined class (deprecated)
  • MongoDB\Driver\Monitoring — Monitoring classes and subscriber functions
    • 関数
    • MongoDB\Driver\Monitoring\CommandFailedEvent — The MongoDB\Driver\Monitoring\CommandFailedEvent class
    • MongoDB\Driver\Monitoring\CommandStartedEvent — The MongoDB\Driver\Monitoring\CommandStartedEvent class
    • MongoDB\Driver\Monitoring\CommandSucceededEvent — The MongoDB\Driver\Monitoring\CommandSucceededEvent class
    • MongoDB\Driver\Monitoring\ServerChangedEvent — The MongoDB\Driver\Monitoring\ServerChangedEvent class
    • MongoDB\Driver\Monitoring\ServerClosedEvent — The MongoDB\Driver\Monitoring\ServerClosedEvent class
    • MongoDB\Driver\Monitoring\ServerOpeningEvent — The MongoDB\Driver\Monitoring\ServerOpeningEvent class
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class
    • MongoDB\Driver\Monitoring\TopologyChangedEvent — The MongoDB\Driver\Monitoring\TopologyChangedEvent class
    • MongoDB\Driver\Monitoring\TopologyClosedEvent — The MongoDB\Driver\Monitoring\TopologyClosedEvent class
    • MongoDB\Driver\Monitoring\TopologyOpeningEvent — The MongoDB\Driver\Monitoring\TopologyOpeningEvent class
    • MongoDB\Driver\Monitoring\CommandSubscriber — The MongoDB\Driver\Monitoring\CommandSubscriber interface
    • MongoDB\Driver\Monitoring\LogSubscriber — The MongoDB\Driver\Monitoring\LogSubscriber interface
    • MongoDB\Driver\Monitoring\SDAMSubscriber — The MongoDB\Driver\Monitoring\SDAMSubscriber interface
    • MongoDB\Driver\Monitoring\Subscriber — The MongoDB\Driver\Monitoring\Subscriber interface
  • MongoDB\Driver\Exception — Exception classes
    • MongoDB\Driver\Exception\AuthenticationException — The MongoDB\Driver\Exception\AuthenticationException class
    • MongoDB\Driver\Exception\BulkWriteException — The MongoDB\Driver\Exception\BulkWriteException class
    • MongoDB\Driver\Exception\CommandException — The MongoDB\Driver\Exception\CommandException class
    • MongoDB\Driver\Exception\ConnectionException — The MongoDB\Driver\Exception\ConnectionException class
    • MongoDB\Driver\Exception\ConnectionTimeoutException — The MongoDB\Driver\Exception\ConnectionTimeoutException class
    • MongoDB\Driver\Exception\EncryptionException — The MongoDB\Driver\Exception\EncryptionException class
    • MongoDB\Driver\Exception\Exception — The MongoDB\Driver\Exception\Exception interface
    • MongoDB\Driver\Exception\ExecutionTimeoutException — The MongoDB\Driver\Exception\ExecutionTimeoutException class
    • MongoDB\Driver\Exception\InvalidArgumentException — The MongoDB\Driver\Exception\InvalidArgumentException class
    • MongoDB\Driver\Exception\LogicException — The MongoDB\Driver\Exception\LogicException class
    • MongoDB\Driver\Exception\RuntimeException — The MongoDB\Driver\Exception\RuntimeException class
    • MongoDB\Driver\Exception\ServerException — The MongoDB\Driver\Exception\ServerException class
    • MongoDB\Driver\Exception\SSLConnectionException — The MongoDB\Driver\Exception\SSLConnectionException class (deprecated)
    • MongoDB\Driver\Exception\UnexpectedValueException — The MongoDB\Driver\Exception\UnexpectedValueException class
    • MongoDB\Driver\Exception\WriteException — The MongoDB\Driver\Exception\WriteException class
    • Class Tree — MongoDB Exception Class Tree


インストール/設定

  • 要件
  • インストール手順
    • Installing the MongoDB PHP Extension with PECL
    • Installing the MongoDB PHP Extension on macOS with Homebrew
    • Installing the MongoDB PHP Extension on Windows
    • Building the MongoDB PHP Driver from source
  • 実行時設定
  • 定義済み定数


要件

As of version 1.16.0, the extension requires PHP 7.2 or higher. Previous versions of the extension allow compatibility with older PHP versions.

The extension requires » libbson and » libmongoc, and will use bundled versions of both libraries by default. System libraries may also be used, as discussed in the manual installation documentation.

The extension, via libmongoc, optionally depends on a TLS library (e.g. OpenSSL) and will use it if available. If the build process fails to find a TLS library, users should check that the appropriate development package (e.g. libssl-dev) and » pkg-config are both installed. The process for detecting and configuring TLS libraries is discussed in more detail in the manual installation documentation.

» Cyrus SASL is an optional dependency to support Kerberos authentication and will be used if available.

注意: Due to potential problems representing 64-bit integers on 32-bit platforms, users are advised to use 64-bit environments. When using a 32-bit platform, be aware that any 64-bit integer read from the database will be returned as a MongoDB\BSON\Int64 instance instead of a PHP integer type.


インストール手順

目次

  • Installing the MongoDB PHP Extension with PECL
  • Installing the MongoDB PHP Extension on macOS with Homebrew
  • Installing the MongoDB PHP Extension on Windows
  • Building the MongoDB PHP Driver from source


Installing the MongoDB PHP Extension with PECL

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mongodb

Linux, Unix, and macOS users may run the following command to install the extension:

$ sudo pecl install mongodb

On systems with multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), each version of PHP will have its own pecl command and php.ini file(s). Additionally, each PHP environments (e.g. CLI, web) may use separate php.ini files.

As of extension version 1.17.0, PECL will prompt for various configure options. To install the extension with default options in a non-interactive script, empty string input may be piped to pecl install using the yes command:

$ yes '' | sudo pecl install mongodb

A complete list of supported configure options can be found in the package.xml file included in the PECL package. To install the extension with specific configure options in a non-interactive script, the --configureoptions option for pecl install may be used:

$ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

By default, installing the extension via PECL will use bundled versions of » libbson, » libmongoc, and » libmongocrypt and attempt to automatically configure them.

注意: If the build process fails to find an SSL library, check that the development packages (e.g. libssl-dev) and » pkg-config are both installed. If that does not resolve the problem, consider using the manual installation process.

Finally, add the following line to the php.ini file for each environment that will need to use the extension:

extension=mongodb.so


Installing the MongoDB PHP Extension on macOS with Homebrew

» Homebrew 1.5.0 deprecated the » Homebrew/php tap and removed formulae for individual PHP extensions. Going forward, macOS users are advised to install the » php formula and follow the standard PECL installation instructions using the pecl command provided by the Homebrew PHP installation.


Installing the MongoDB PHP Extension on Windows

Precompiled binaries are attached to the project's » Github releases. Archives are published for various combinations of PHP version, thread safety (TS or NTS), and architecture (x86 or x64). Determining the correct archive for the PHP environment and extract the php_mongodb.dll file to the extension directory ("ext" by default).

Add the following line to the php.ini file for each environment that will need to use the extension:

extension=php_mongodb.dll

Failure to select the correct binary will result in an error when attempting to load the extension DLL at runtime:

PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Ensure that the downloaded DLL corresponds to the following PHP runtime properties:

  • PHP version (PHP_VERSION)
  • Thread safety (PHP_ZTS)
  • Architecture (PHP_INT_SIZE)

In addition to the aforementioned constants, these properties can also be inferred from phpinfo(). If a system has multiple PHP runtimes installed, double-check that the phpinfo() output is for the correct environment.

注意: Additional DLL dependencies for Windows Users

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsasl.dll


Building the MongoDB PHP Driver from source

For developers and users interested in the latest bugfixes, the extension may be compiled from the latest source code on » Github. Run the following commands to clone and build the project:

$ git clone https://github.com/mongodb/mongo-php-driver.git
$ cd mongo-php-driver
$ git submodule update --init
$ phpize
$ ./configure
$ make all
$ sudo make install

On systems with multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), each version of PHP will have its own phpize command and php.ini file(s). Additionally, each PHP environments (e.g. CLI, web) may use separate php.ini files.

By default, the extension will use bundled versions of » libbson, » libmongoc, and » libmongocrypt and attempt to configure them automatically. If these libraries are already installed as system libraries, the extension can utilize them by specifying --with-mongodb-system-libs=yes as an option to configure.

For a complete list of configure options, run configure --help.

When using bundled versions of libmongoc and libmongocrypt, the extension will also attempt to select an SSL library according to the --with-mongodb-ssl configure option. As of extension version 1.17.0, OpenSSL is always preferred by default. Previously, Secure Transport was the default on macOS and OpenSSL was the default on all other platforms.

注意:

If the build process fails to find an SSL library, check that the development packages (e.g. libssl-dev) and » pkg-config are both installed.

When using Homebrew on macOS, it is common for a system to have multiple versions of OpenSSL installed. To ensure that the desired version of OpenSSL is selected, the PKG_CONFIG_PATH environment variable may be used to control the search path for pkg-config. If pkg-config is not used, configure also supports a --with-openssl-dir=DIR argument, which can be used to specify a manual search path (for OpenSSL only).

The final build step, make install, will report where mongodb.so has been installed, similar to:

Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Ensure that the extension_dir option in php.ini points to the directory where mongodb.so was installed. The option may be queried by running:

$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                   /usr/lib/php/extensions/debug-non-zts-20220829

If the directories differ, either change extension_dir in php.ini or manually move mongodb.so to the correct directory.

Finally, add the following line to the php.ini file for each environment that will need to use the extension:

extension=mongodb.so


実行時設定

php.ini の設定により動作が変化します。

mongodb 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mongodb.debug | "" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

mongodb.debug string

This option can be used to enable or disable trace-level debug logging in the extension (and libmongoc).

Specify an empty string, "0", "off", "no", or "false" to disable logging.

Specify "stderr" or "stdout" to log to stderr or stdout, respectively.

Specify "1", "on", "yes", or "true" to log to a new temporary file within the default system temp directory (i.e. sys_get_temp_dir()).

Specify any other string to log to a new temporary file within that directory. If the directory cannot be used, the default system temp directory will be used instead.

注意:

Please note that the debug log can contain sensitive information, such as credentials to the MongoDB server and full documents written to or read from the server. Please review any debug logs before sharing them with other people.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MONGODB_VERSION (string)
x.y.z style version number of the extension
MONGODB_STABILITY (string)
Current stability (alpha/beta/stable)


Tutorials

In this section you will find several tutorials on how to use the MongoDB driver for PHP.

  • Using the PHP Library for MongoDB (PHPLIB)
  • Application Performance Monitoring (APM)


Using the PHP Library for MongoDB (PHPLIB)

After the initial extension set-up, we will continue explaining how to get started with the corresponding userland library to write our first project.

Installing the PHP Library with Composer

The last thing we still need to install to get started on the application itself, is the PHP library.

The library needs to be installed with » Composer, a package manager for PHP. Instructions for installing Composer on various platforms may be found on its website.

Install the library by running:

$ composer require mongodb/mongodb

It will output something akin to:

./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing mongodb/mongodb (1.0.0)
    Downloading: 100%

Writing lock file
Generating autoload files

Composer will create several files: composer.json, composer.lock, and a vendor directory that will contain the library and any other dependencies your project might require.

Using the PHP Library

In addition to managing your dependencies, Composer will also provide you with an autoloader (for those dependencies' classes). Ensure that it is included at the start of your script or in your application's bootstrap code:

<?php
// This path should point to Composer's autoloader
require 'vendor/autoload.php';

With this done, you can now use any of the functionality as described in the » library documentation.

If you have used MongoDB drivers in other languages, the library's API should look familiar. It contains a » Client class for connecting to MongoDB, a » Database class for database-level operations (e.g. commands, collection management), and a » Collection class for collection-level operations (e.g. » CRUD methods, index management).

As an example, this is how you insert a document into the beers collection of the demo database:

<?php
require 'vendor/autoload.php'; // include Composer's autoloader

$client = new MongoDB\Client("mongodb://localhost:27017");
$collection = $client->demo->beers;

$result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

echo "Inserted with Object ID '{$result->getInsertedId()}'";
?>

Since the inserted document did not contain an _id field, the extension will generate an MongoDB\BSON\ObjectId for the server to use as the _id. This value is also made available to the caller via the result object returned by the insertOne method.

After insertion, you can query for the data that you have just inserted. For that, you use the find method, which returns an iterable cursor:

<?php
require 'vendor/autoload.php'; // include Composer's autoloader

$client = new MongoDB\Client("mongodb://localhost:27017");
$collection = $client->demo->beers;

$result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

foreach ($result as $entry) {
echo $entry['_id'], ': ', $entry['name'], "\n";
}
?>

While it may not be apparent in the examples, BSON documents and arrays are unserialized as special classes in the library by default. These classes extend ArrayObject for usability and implement the extension's MongoDB\BSON\Serializable and MongoDB\BSON\Unserializable interfaces to ensure that values preserve their type when serialized back into BSON. This avoids a caveat in the legacy mongo extension where arrays might turn into documents, and vice versa. See the Persisting Data specification for more information on how values are converted between PHP and BSON.


Application Performance Monitoring (APM)

The extension contains an event subscriber API, which allows applications to monitor commands and internal activity pertaining to the » Server Discovery and Monitoring Specification. This tutorial will demonstrate command monitoring using the MongoDB\Driver\Monitoring\CommandSubscriber interface.

The MongoDB\Driver\Monitoring\CommandSubscriber interface defines three methods: commandStarted, commandSucceeded, and commandFailed. Each of these three methods accept a single event argument of a specific class for the respective event. For example, the commandSucceeded's $event argument is a MongoDB\Driver\Monitoring\CommandSucceededEvent object.

In this tutorial we will implement a subscriber that creates a list of all the query profiles and the average time they took.

Subscriber Class Scaffolding

We start with the framework for our subscriber:

<?php

class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
{
public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
{
}

public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
{
}

public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
{
}
}

?>

Registering the Subscriber

Once a subscriber object is instantiated, it needs to be registered with the extensions's monitoring system. This is done by calling MongoDB\Driver\Monitoring\addSubscriber() or MongoDB\Driver\Manager::addSubscriber() to register the subscriber globally or with a specific Manager, respectively.

<?php

\MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

?>

Implementing the Logic

With the object registered, the only thing left is to implement the logic in the subscriber class. To correlate the two events that make up a successfully executed command (commandStarted and commandSucceeded), each event object exposes a requestId field.

To record the average time per query shape, we will start by checking for a find command in the commandStarted event. We will then add an item to the pendingCommands property indexed by its requestId and with its value representing the query shape.

If we receive a corresponding commandSucceeded event with the same requestId, we add the duration of the event (from durationMicros) to the total time and increment the operation count.

If a corresponding commandFailed event is encountered, we just remove the entry from the pendingCommands property.

<?php

class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
{
private $pendingCommands = [];
private $queryShapeStats = [];

/* Creates a query shape out of the filter argument. Right now it only
* takes the top level fields into account */
private function createQueryShape( array $filter )
{
return json_encode( array_keys( $filter ) );
}

public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
{
if ( 'find' === $event->getCommandName() )
{
$queryShape = $this->createQueryShape( (array) $event->getCommand()->filter );
$this->pendingCommands[$event->getRequestId()] = $queryShape;
}
}

public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
{
$requestId = $event->getRequestId();
if ( array_key_exists( $requestId, $this->pendingCommands ) )
{
$this->queryShapeStats[$this->pendingCommands[$requestId]]['count']++;
$this->queryShapeStats[$this->pendingCommands[$requestId]]['duration'] += $event->getDurationMicros();
unset( $this->pendingCommands[$requestId] );
}
}

public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
{
if ( array_key_exists( $event->getRequestId(), $this->pendingCommands ) )
{
unset( $this->pendingCommands[$event->getRequestId()] );
}
}

public function __destruct()
{
foreach( $this->queryShapeStats as $shape => $stats )
{
echo "Shape: ", $shape, " (", $stats['count'], ")\n ",
$stats['duration'] / $stats['count'], "μs\n\n";
}
}
}

$m = new \MongoDB\Driver\Manager( 'mongodb://localhost:27016' );

/* Add the subscriber */
\MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

/* Do a bunch of queries */
$query = new \MongoDB\Driver\Query( [
'region_slug' => 'scotland-highlands', 'age' => [ '$gte' => 20 ]
] );
$cursor = $m->executeQuery( 'dramio.whisky', $query );

$query = new \MongoDB\Driver\Query( [
'region_slug' => 'scotland-lowlands', 'age' => [ '$gte' => 15 ]
] );
$cursor = $m->executeQuery( 'dramio.whisky', $query );

$query = new \MongoDB\Driver\Query( [ 'region_slug' => 'scotland-lowlands' ] );
$cursor = $m->executeQuery( 'dramio.whisky', $query );

?>


Explains the driver architecture, and special features

  • Architecture — Architecture Overview
  • Connections — Connection handling and persistence
  • Persisting Data — Serialization and deserialization of PHP variables into MongoDB
    • Serialization to BSON
    • Deserialization from BSON


Architecture Overview

This article explains how all the different components of the PHP driver fit together, from base system libraries, through the extension, and to the PHP libraries on top.

At the top of this stack sits a » PHP library, which is distributed as a » Composer package. This library provides an API consistent with other MongoDB » drivers and implements various cross-driver » specifications. While the extension can be used directly, the library has minimal overhead and should be a common dependency for most applications built with MongoDB.

Sitting below that library is a PHP extension, which is distributed through » PECL. The extension forms the glue between PHP and our system libraries (» libmongoc, » libbson, and » libmongocrypt). Its public API provides only the most essential functionality:

  • Connection management
  • BSON encoding and decoding
  • Object document serialization (to support ODM libraries)
  • Executing commands, queries, and write operations
  • Handling cursors for command and query results

Driver Source Code and JIRA Projects
Project | GitHub | JIRA
PHP Library | » mongodb/mongo-php-library | » PHPLIB
PHP Extension | » mongodb/mongo-php-driver | » PHPC


Connection handling and persistence

注意: On Unix platforms, the extension is sensitive to scripts that use the fork() system call without also calling exec(). Users are advised not to re-use MongoDB\Driver\Manager instances in a forked child process.

Connection and topology persistence (PHP version since 1.2.0)

All versions of the extension since 1.2.0 persist the » libmongoc client object in the PHP worker process, which allows it to re-use database connections, authentication states, and topology information across multiple requests.

When MongoDB\Driver\Manager::__construct() is invoked, a hash is created from its arguments (i.e. URI string and array options). The extension will attempt to find a previously persisted » libmongoc client object for that hash. If an existing client cannot be found for the hash, a new client will be created and persisted for future use. This behavior can be disabled via the "disableClientPersistence" driver option.

Each client contains its own database connections and a view of the server topology (e.g. standalone, replica set, shard cluster). By persisting the client between PHP requests, the extension is able to re-use established database connections and remove the need for » discovering the server topology on each request.

Consider the following example:

<?php

$managers = [
new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017'),
new MongoDB\Driver\Manager('mongodb://rs1.example.com,rs2.example.com/', ['replicaSet' => 'myReplicaSet']),
];

foreach ($managers as $manager) {
$manager->executeCommand('test', new MongoDB\Driver\Command(['ping' => 1]));
}

?>

The first two Manager objects will share the same » libmongoc client since their constructor arguments are identical. The third and fourth objects will each use their own client. In total, three clients will be created and the PHP worker executing this script will open two connections to 127.0.0.1 and one connection to each of rs1.example.com and rs2.example.com. If the extension discovers additional members of the replica set after issuing hello commands, it will open additional connections to those servers as well.

If the same worker executes the script again in a second request, the three clients will be re-used and no new connections will be made. Depending on how long ago the previous request was served, the extension may need to issue additional hello commands to update its view of the topologies.

Socket persistence (PHP versions before 1.2.0)

Versions of the extension before 1.2.0 utilize PHP's Streams API for database connections, using an API within » libmongoc to designate custom handlers for socket communication; however, a new libmongoc client is created for each MongoDB\Driver\Manager. As a result, the extension persists individual database connections but not authentication state or topology information. This means that the extension needs to issue commands at the start of each request to authenticate and » discover the server topology.

Database connections are persisted by a hash derived from the server's host, port, and the URI string used to construct the MongoDB\Driver\Manager. The constructor's array options are not included in this hash.

注意: Versions of the extension >= 1.1.8 and < 1.2.0 do not persist sockets for SSL connections. See » PHPC-720 for additional information.

Despite its shortcomings with persisting SSL connections when and topology information, this version of the extension supports all SSL context options since it uses PHP's Streams API.


Serialization and deserialization of PHP variables into MongoDB

目次

  • Serialization to BSON
  • Deserialization from BSON

This document discusses how compound structures (i.e. documents, arrays, and objects) are converted between BSON and PHP values.


Serialization to BSON

Arrays

If an array is a packed array — i.e. empty array or the keys start at 0 and are sequential without gaps: BSON array.

If the array is not packed — i.e. having associative (string) keys, the keys don't start at 0, or when there are gaps:: BSON object

A top-level (root) document, always serializes as a BSON document.

Examples

These serialize as a BSON array:

[ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
[ 0 => 4, 1 => 9 ] => [ 4, 9 ]

These serialize as a BSON document:

[ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
[ "foo" => 42 ] => { "foo" : 42 }
[ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }

Note that the five examples are extracts of a full document, and represent only one value inside a document.

Objects

If an object is of the stdClass class, serialize as a BSON document.

If an object is a supported class that implements MongoDB\BSON\Type, then use the BSON serialization logic for that specific type. MongoDB\BSON\Type instances (excluding MongoDB\BSON\Serializable may only be serialized as a document field value. Attempting to serialize such an object as a root document will throw a MongoDB\Driver\Exception\UnexpectedValueException

If an object is of an unknown class implementing the MongoDB\BSON\Type interface, then throw a MongoDB\Driver\Exception\UnexpectedValueException

If an object is of any other class, without implementing any special interface, serialize as a BSON document. Keep only public properties, and ignore protected and private properties.

If an object is of a class that implements the MongoDB\BSON\Serializable interface, call MongoDB\BSON\Serializable::bsonSerialize() and use the returned array or stdClass to serialize as a BSON document or array. The BSON type will be determined by the following:

  1. Root documents must be serialized as a BSON document.

  2. MongoDB\BSON\Persistable objects must be serialized as a BSON document.

  3. If MongoDB\BSON\Serializable::bsonSerialize() returns a packed array, serialize as a BSON array.

  4. If MongoDB\BSON\Serializable::bsonSerialize() returns a non-packed array or stdClass, serialize as a BSON document.

  5. If MongoDB\BSON\Serializable::bsonSerialize() did not return an array or stdClass, throw an MongoDB\Driver\Exception\UnexpectedValueException exception.

If an object is of a class that implements the MongoDB\BSON\Persistable interface (which implies MongoDB\BSON\Serializable), obtain the properties in a similar way as in the previous paragraphs, but also add an additional property __pclass as a Binary value, with subtype 0x80 and data bearing the fully qualified class name of the object that is being serialized.

The __pclass property is added to the array or object returned by MongoDB\BSON\Serializable::bsonSerialize(), which means it will overwrite any __pclass key/property in the MongoDB\BSON\Serializable::bsonSerialize() return value. If you want to avoid this behaviour and set your own __pclass value, you must not implement MongoDB\BSON\Persistable and should instead implement MongoDB\BSON\Serializable directly.

Examples

<?php

class stdClass
{
public $foo = 42;
} // => {"foo": 42}

class MyClass
{
public $foo = 42;
protected $prot = 'wine';
private $fpr = 'cheese';
} // => {"foo": 42}

class AnotherClass1 implements MongoDB\BSON\Serializable
{
public $foo = 42;
protected $prot = 'wine';
private $fpr = 'cheese';

public function bsonSerialize(): array
{
return ['foo' => $this->foo, 'prot' => $this->prot];
}
} // => {"foo": 42, "prot": "wine"}

class AnotherClass2 implements MongoDB\BSON\Serializable
{
public $foo = 42;

public function bsonSerialize(): self
{
return $this;
}
} // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

class AnotherClass3 implements MongoDB\BSON\Serializable
{
private $elements = ['foo', 'bar'];

public function bsonSerialize(): array
{
return $this->elements;
}
} // => {"0": "foo", "1": "bar"}

/**
* Nesting Serializable classes
*/

class AnotherClass4 implements MongoDB\BSON\Serializable
{
private $elements = [0 => 'foo', 2 => 'bar'];

public function bsonSerialize(): array
{
return $this->elements;
}
} // => {"0": "foo", "2": "bar"}

class ContainerClass1 implements MongoDB\BSON\Serializable
{
public $things;

public function __construct()
{
$this->things = new AnotherClass4();
}

function bsonSerialize(): array
{
return ['things' => $this->things];
}
} // => {"things": {"0": "foo", "2": "bar"}}

class AnotherClass5 implements MongoDB\BSON\Serializable
{
private $elements = [0 => 'foo', 2 => 'bar'];

public function bsonSerialize(): array
{
return array_values($this->elements);
}
} // => {"0": "foo", "1": "bar"} as a root class
["foo", "bar"] as a nested value

class ContainerClass2 implements MongoDB\BSON\Serializable
{
public $things;

public function __construct()
{
$this->things = new AnotherClass5();
}

public function bsonSerialize(): array
{
return ['things' => $this->things];
}
} // => {"things": ["foo", "bar"]}

class AnotherClass6 implements MongoDB\BSON\Serializable
{
private $elements = ['foo', 'bar'];

function bsonSerialize(): object
{
return (object) $this->elements;
}
} // => {"0": "foo", "1": "bar"}

class ContainerClass3 implements MongoDB\BSON\Serializable
{
public $things;

public function __construct()
{
$this->things = new AnotherClass6();
}

public function bsonSerialize(): array
{
return ['things' => $this->things];
}
} // => {"things": {"0": "foo", "1": "bar"}}

class UpperClass implements MongoDB\BSON\Persistable
{
public $foo = 42;
protected $prot = 'wine';
private $fpr = 'cheese';

private $data;

public function bsonUnserialize(array $data): void
{
$this->data = $data;
}

public function bsonSerialize(): array
{
return ['foo' => $this->foo, 'prot' => $this->prot];
}
} // => {"foo": 42, "prot": "wine", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

?>


Deserialization from BSON

警告

BSON documents can technically contain duplicate keys because documents are stored as a list of key-value pairs; however, applications should refrain from generating documents with duplicate keys as server and driver behavior may be undefined. Since PHP objects and arrays cannot have duplicate keys, data could also be lost when decoding a BSON document with duplicate keys.

The legacy mongo extension deserialized both BSON documents and arrays as PHP arrays. While PHP arrays are convenient to work with, this behavior was problematic because different BSON types could deserialize to the same PHP value (e.g. {"0": "foo"} and ["foo"]) and make it impossible to infer the original BSON type. By default, the mongodb extension addresses this concern by ensuring that BSON arrays and documents are converted to PHP arrays and objects, respectively.

For compound types, there are three data types:

root

refers to the top-level BSON document only

document

refers to embedded BSON documents only

array

refers to a BSON array

Besides the three collective types, it is also possible to configure specific fields in your document to map to the data types mentioned below. As an example, the following type map allows you to map each embedded document within an "addresses" array to an Address class and each "city" field within those embedded address documents to a City class:

[
    'fieldPaths' => [
        'addresses.$' => 'MyProject\Address',
        'addresses.$.city' => 'MyProject\City',
    ],
]

Each of those three data types, as well as the field specific mappings, can be mapped against different PHP types. The possible mapping values are:

not set or NULL (default)

  • A BSON array will be deserialized as a PHP array.

  • A BSON document (root or embedded) without a __pclass property [1] becomes a PHP stdClass object, with each BSON document key set as a public stdClass property.

  • A BSON document (root or embedded) with a __pclass property [1] becomes a PHP object of the class name as defined by the __pclass property.

    If the named class implements the MongoDB\BSON\Persistable interface, then the properties of the BSON document, including the __pclass property, are sent as an associative array to the MongoDB\BSON\Unserializable::bsonUnserialize() function to initialise the object's properties.

    If the named class does not exist or does not implement the MongoDB\BSON\Persistable interface, stdClass will be used and each BSON document key (including __pclass) will be set as a public stdClass property.

    The __pclass functionality relies on the property being part of a retrieved MongoDB document. If you use a projection when querying for documents, you need to include the __pclass field in the projection for this functionality to work.

"array"

Turns a BSON array or BSON document into a PHP array. There will be no special treatment of a __pclass property [1], but it may be set as an element in the returned array if it was present in the BSON document.

"object" or "stdClass"

Turns a BSON array or BSON document into a stdClass object. There will be no special treatment of a __pclass property [1], but it may be set as a public property in the returned object if it was present in the BSON document.

"bson"

Turns a BSON array into a MongoDB\BSON\PackedArray and a BSON document into a MongoDB\BSON\Document, regardless of whether the BSON document has a __pclass property [1].

注意: The bson value is only available for the three root types, not in the field specific mappings.

any other string

Defines the class name that the BSON array or BSON object should be deserialized as. For BSON objects that include __pclass properties, that class will take priority.

If the named class does not exist, is not concrete (i.e. it is abstract or an interface), or does not implement MongoDB\BSON\Unserializable then an MongoDB\Driver\Exception\InvalidArgumentException exception is thrown.

If the BSON object has a __pclass property and that class exists and implements MongoDB\BSON\Persistable it will supersede the class provided in the type map.

The properties of the BSON document, including the __pclass property if it exists, will be sent as an associative array to the MongoDB\BSON\Unserializable::bsonUnserialize() function to initialise the object's properties.

TypeMaps

TypeMaps can be set through the MongoDB\Driver\Cursor::setTypeMap() method on a MongoDB\Driver\Cursor object, or the $typeMap argument of MongoDB\BSON\toPHP(), MongoDB\BSON\Document::toPHP(), and MongoDB\BSON\PackedArray::toPHP(). Each of the three classes (root, document, and array) can be individually set, in addition to the field specific types.

If the value in the map is NULL, it means the same as the default value for that item.

Examples

These examples use the following classes:

MyClass

which does not implement any interface

YourClass

which implements MongoDB\BSON\Unserializable

OurClass

which implements MongoDB\BSON\Persistable

TheirClass

which extends OurClass

The MongoDB\BSON\Unserializable::bsonUnserialize() method of YourClass, OurClass, TheirClass iterate over the array and set the properties without modifications. It also sets the $unserialized property to true:

<?php

function bsonUnserialize( array $map )
{
foreach ( $map as $k => $value )
{
$this->$k = $value;
}
$this->unserialized = true;
}

/* typemap: [] (all defaults) */
{ "foo": "yes", "bar" : false }
  -> stdClass { $foo => 'yes', $bar => false }

{ "foo": "no", "array" : [ 5, 6 ] }
  -> stdClass { $foo => 'no', $array => [ 5, 6 ] }

{ "foo": "no", "obj" : { "embedded" : 3.14 } }
  -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }

{ "foo": "yes", "__pclass": "MyClass" }
  -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }

{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
  -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }

{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
  -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }

{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
  -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true }

{ "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
  -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }

/* typemap: [ "root" => "MissingClass" ] */
{ "foo": "yes" }
  -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

/* typemap: [ "root" => "MyClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
  -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

/* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
{ "foo": "yes" }
  -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MongoDB\BSON\Unserializable" } }
  -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true }

/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
  -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true }

/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
  -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true }

/* typemap: [ "root" => "YourClass" ] */
{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
  -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

/* typemap: [ "root" => "OurClass" ] */
{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
  -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

/* typemap: [ 'root' => 'YourClass' ] */
{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
  -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true }

/* typemap: [ 'root' => 'array', 'document' => 'array' ] */
{ "foo": "yes", "bar" : false }
  -> [ "foo" => "yes", "bar" => false ]

{ "foo": "no", "array" : [ 5, 6 ] }
  -> [ "foo" => "no", "array" => [ 5, 6 ] ]

{ "foo": "no", "obj" : { "embedded" : 3.14 } }
  -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]

{ "foo": "yes", "__pclass": "MyClass" }
  -> [ "foo" => "yes", "__pclass" => "MyClass" ]

{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
  -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]

{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
  -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]

/* typemap: [ 'root' => 'object', 'document' => 'object' ] */
{ "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
  -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }


  • ≪ Deserialization from BSON
  • Request Injection Attacks ≫
  • PHP Manual
  • MongoDB
  • Security

Security

  • Request Injection Attacks
  • Script Injection Attacks


Request Injection Attacks

If you are passing $_GET (or $_POST) parameters to your queries, make sure that they are cast to strings first. Users can insert associative arrays in GET and POST requests, which could then become unwanted $-queries.

A fairly innocuous example: suppose you are looking up a user's information with the request http://www.example.com?username=bob. Your application creates the query $q = new \MongoDB\Driver\Query( [ 'username' => $_GET['username'] ]).

Someone could subvert this by getting http://www.example.com?username[$ne]=foo, which PHP will magically turn into an associative array, turning your query into $q = new \MongoDB\Driver\Query( [ 'username' => [ '$ne' => 'foo' ] ] ), which will return all users not named "foo" (all of your users, probably).

This is a fairly easy attack to defend against: make sure $_GET and $_POST parameters are the type you expect before you send them to the database. PHP has the filter_var() function to assist with this.

Note that this type of attack can be used with any database interaction that locates a document, including updates, upserts, deletes, and findAndModify commands.

See » the main documentation for more information about SQL-injection-like issues with MongoDB.


Script Injection Attacks

If you are using JavaScript, make sure that any variables that cross the PHP- to-JavaScript boundry are passed in the scope field of MongoDB\BSON\Javascript, not interpolated into the JavaScript string. This can come up when using $where clauses in queries, mapReduce and group commands, and any other time you may pass JavaScript into the database.

For example, suppose we have some JavaScript to greet a user in the database logs. We could do:

<?php
$m = new MongoDB\Driver\Manager;

// Don't do this!!!
$username = $_GET['field'];

$cmd = new \MongoDB\Driver\Command( [
'eval' => "print('Hello, $username!');"
] );

$r = $m->executeCommand( 'dramio', $cmd );
?>

However, what if a malicious user passes in some JavaScript?

<?php
$m = new MongoDB\Driver\Manager;

// Don't do this!!!
$username = $_GET['field'];
// $username is set to "'); db.users.drop(); print('"

$cmd = new \MongoDB\Driver\Command( [
'eval' => "print('Hello, $username!');"
] );

$r = $m->executeCommand( 'dramio', $cmd );
?>

Now MongoDB executes the JavaScript string "print('Hello, '); db.users.drop(); print('!');". This attack is easy to avoid: use args to pass variables from PHP to JavaScript:

<?php
$m = new MongoDB\Driver\Manager;

$_GET['field'] = 'derick';
$args = [ $_GET['field'] ];

$cmd = new \MongoDB\Driver\Command( [
'eval' => "function greet(username) { print('Hello, ' + username + '!'); }",
'args' => $args,
] );

$r = $m->executeCommand( 'dramio', $cmd );
?>

This adds an argument to the JavaScript scope, which gets used as argument for the greet function. Now if someone tries to send malicious code, MongoDB will harmlessly print Hello, '); db.dropDatabase(); print('!.

Using arguments helps to prevent malicious input from being executed by the database. However, you must make sure that your code does not turn around and execute the input anyway! It is best to avoid executing any JavaScript on the server in the first place.

You are strongly recommended to stay clear of the » $where clause with queries, as it impacts performance significantly. Where possible, use either normal query operators, or the » Aggregation Framework.

As alternative to » MapReduce, which uses JavaScript, consider using the » Aggregation Framework. Unlike Map/Reduce, it uses an idiomatic language to construct queries, without having to write, and use, the slower JavaScript approach that Map/Reduce requires.

The » eval command has been deprecated since MongoDB 3.0, and should also be avoided.


MongoDB Extension Classes

  • MongoDB\Driver\Manager — The MongoDB\Driver\Manager class
    • MongoDB\Driver\Manager::addSubscriber — Registers a monitoring event subscriber with this Manager
    • MongoDB\Driver\Manager::__construct — Create new MongoDB Manager
    • MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object
    • MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations
    • MongoDB\Driver\Manager::executeCommand — Execute a database command
    • MongoDB\Driver\Manager::executeQuery — Execute a database query
    • MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads
    • MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes
    • MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes
    • MongoDB\Driver\Manager::getEncryptedFieldsMap — Return the encryptedFieldsMap auto encryption option for the Manager
    • MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager
    • MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager
    • MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected
    • MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager
    • MongoDB\Driver\Manager::removeSubscriber — Unregisters a monitoring event subscriber with this Manager
    • MongoDB\Driver\Manager::selectServer — Select a server matching a read preference
    • MongoDB\Driver\Manager::startSession — Start a new client session for use with this client
  • MongoDB\Driver\Command — The MongoDB\Driver\Command class
    • MongoDB\Driver\Command::__construct — Create a new Command
  • MongoDB\Driver\Query — The MongoDB\Driver\Query class
    • MongoDB\Driver\Query::__construct — Create a new Query
  • MongoDB\Driver\BulkWrite — The MongoDB\Driver\BulkWrite class
    • MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite
    • MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk
    • MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk
    • MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk
    • MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk
  • MongoDB\Driver\Session — The MongoDB\Driver\Session class
    • MongoDB\Driver\Session::abortTransaction — Aborts a transaction
    • MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session
    • MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session
    • MongoDB\Driver\Session::commitTransaction — Commits a transaction
    • MongoDB\Driver\Session::__construct — Create a new Session (not used)
    • MongoDB\Driver\Session::endSession — Terminates a session
    • MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session
    • MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session
    • MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session
    • MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned
    • MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction
    • MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session
    • MongoDB\Driver\Session::isDirty — Returns whether the session has been marked as dirty
    • MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress
    • MongoDB\Driver\Session::startTransaction — Starts a transaction
  • MongoDB\Driver\ClientEncryption — The MongoDB\Driver\ClientEncryption class
    • MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document
    • MongoDB\Driver\ClientEncryption::__construct — Create a new ClientEncryption object
    • MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document
    • MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value
    • MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document
    • MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value
    • MongoDB\Driver\ClientEncryption::encryptExpression — Encrypts a match or aggregate expression
    • MongoDB\Driver\ClientEncryption::getKey — Gets a key document
    • MongoDB\Driver\ClientEncryption::getKeyByAltName — Gets a key document by an alternate name
    • MongoDB\Driver\ClientEncryption::getKeys — Gets all key documents
    • MongoDB\Driver\ClientEncryption::removeKeyAltName — Removes an alternate name from a key document
    • MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Rewraps data keys
  • MongoDB\Driver\ServerApi — The MongoDB\Driver\ServerApi class
    • MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance
    • MongoDB\Driver\ServerApi::serialize — Serialize a ServerApi
    • MongoDB\Driver\ServerApi::unserialize — Unserialize a ServerApi
  • MongoDB\Driver\WriteConcern — The MongoDB\Driver\WriteConcern class
    • MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern
    • MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option
    • MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option
    • MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option
    • MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern
    • MongoDB\Driver\WriteConcern::serialize — Serialize a WriteConcern
    • MongoDB\Driver\WriteConcern::unserialize — Unserialize a WriteConcern
  • MongoDB\Driver\ReadPreference — The MongoDB\Driver\ReadPreference class
    • MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference
    • MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option
    • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option
    • MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option
    • MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option as a string
    • MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option
    • MongoDB\Driver\ReadPreference::serialize — Serialize a ReadPreference
    • MongoDB\Driver\ReadPreference::unserialize — Unserialize a ReadPreference
  • MongoDB\Driver\ReadConcern — The MongoDB\Driver\ReadConcern class
    • MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization
    • MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern
    • MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option
    • MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern
    • MongoDB\Driver\ReadConcern::serialize — Serialize a ReadConcern
    • MongoDB\Driver\ReadConcern::unserialize — Unserialize a ReadConcern
  • MongoDB\Driver\Cursor — The MongoDB\Driver\Cursor class
    • MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)
    • MongoDB\Driver\Cursor::current — Returns the current element
    • MongoDB\Driver\Cursor::getId — Returns the ID for this cursor
    • MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor
    • MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results
    • MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor
    • MongoDB\Driver\Cursor::next — Advances the cursor to the next result
    • MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result
    • MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization
    • MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor
    • MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid
  • MongoDB\Driver\CursorId — The MongoDB\Driver\CursorId class
    • MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)
    • MongoDB\Driver\CursorId::serialize — Serialize a CursorId
    • MongoDB\Driver\CursorId::__toString — String representation of the cursor ID
    • MongoDB\Driver\CursorId::unserialize — Unserialize a CursorId
  • MongoDB\Driver\CursorInterface — The MongoDB\Driver\CursorInterface interface
    • MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor
    • MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor
    • MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results
    • MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization
    • MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor
  • MongoDB\Driver\Server — The MongoDB\Driver\Server class
    • MongoDB\Driver\Server::__construct — Create a new Server (not used)
    • MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server
    • MongoDB\Driver\Server::executeCommand — Execute a database command on this server
    • MongoDB\Driver\Server::executeQuery — Execute a database query on this server
    • MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server
    • MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server
    • MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server
    • MongoDB\Driver\Server::getHost — Returns the hostname of this server
    • MongoDB\Driver\Server::getInfo — Returns an array of information describing this server
    • MongoDB\Driver\Server::getLatency — Returns the latency of this server in milliseconds
    • MongoDB\Driver\Server::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Server::getServerDescription — Returns a ServerDescription for this server
    • MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set
    • MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server
    • MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set
    • MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set
    • MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set
    • MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set
    • MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set
  • MongoDB\Driver\ServerDescription — The MongoDB\Driver\ServerDescription class
    • MongoDB\Driver\ServerDescription::getHelloResponse — Returns the server's most recent "hello" response
    • MongoDB\Driver\ServerDescription::getHost — Returns the hostname of this server
    • MongoDB\Driver\ServerDescription::getLastUpdateTime — Returns the server's last update time in microseconds
    • MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\ServerDescription::getRoundTripTime — Returns the server's round trip time in milliseconds
    • MongoDB\Driver\ServerDescription::getType — Returns a string denoting the type of this server
  • MongoDB\Driver\TopologyDescription — The MongoDB\Driver\TopologyDescription class
    • MongoDB\Driver\TopologyDescription::getServers — Returns the servers in the topology
    • MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology
    • MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server
    • MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server
  • MongoDB\Driver\WriteConcernError — The MongoDB\Driver\WriteConcernError class
    • MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code
    • MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError
    • MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message
  • MongoDB\Driver\WriteError — The MongoDB\Driver\WriteError class
    • MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code
    • MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError
    • MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError
    • MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message
  • MongoDB\Driver\WriteResult — The MongoDB\Driver\WriteResult class
    • MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted
    • MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)
    • MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update
    • MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated
    • MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result
    • MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert
    • MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents
    • MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred
    • MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred
    • MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged


The MongoDB\Driver\Manager class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\Manager is the main entry point to the extension. It is responsible for maintaining connections to MongoDB (be it standalone server, replica set, or sharded cluster).

No connection to MongoDB is made upon instantiating the Manager. This means the MongoDB\Driver\Manager can always be constructed, even though one or more MongoDB servers are down.

Any write or query can throw connection exceptions as connections are created lazily. A MongoDB server may also become unavailable during the life time of the script. It is therefore important that all actions on the Manager to be wrapped in try/catch statements.

クラス概要

final class MongoDB\Driver\Manager {
/* メソッド */
final public addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void
final public __construct(?string $uri = null, ?array $uriOptions = null, ?array $driverOptions = null)
final public createClientEncryption(array $options): MongoDB\Driver\ClientEncryption
final public executeBulkWrite(string $namespace, MongoDB\Driver\BulkWrite $bulk, array|MongoDB\Driver\WriteConcern|null $options = null): MongoDB\Driver\WriteResult
final public executeCommand(string $db, MongoDB\Driver\Command $command, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor
final public executeQuery(string $namespace, MongoDB\Driver\Query $query, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor
final public executeReadCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
final public executeReadWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
final public executeWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
final public getEncryptedFieldsMap(): array|object|null
final public getReadConcern(): MongoDB\Driver\ReadConcern
final public getReadPreference(): MongoDB\Driver\ReadPreference
final public getServers(): array
final public getWriteConcern(): MongoDB\Driver\WriteConcern
final public removeSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void
final public selectServer(?MongoDB\Driver\ReadPreference $readPreference = null): MongoDB\Driver\Server
final public startSession(?array $options = null): MongoDB\Driver\Session
}

例

例1 MongoDB\Driver\Manager::__construct() basic example

var_dump()ing a MongoDB\Driver\Manager will print out various details about the manager that are otherwise not normally exposed. This can be useful to debug how the driver views your MongoDB setup, and which options are used.

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
var_dump($manager);

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\Manager)#1 (2) {
  ["uri"]=>
  string(26) "mongodb://127.0.0.1:27017/"
  ["cluster"]=>
  array(0) {
  }
}

目次

  • MongoDB\Driver\Manager::addSubscriber — Registers a monitoring event subscriber with this Manager
  • MongoDB\Driver\Manager::__construct — Create new MongoDB Manager
  • MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object
  • MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations
  • MongoDB\Driver\Manager::executeCommand — Execute a database command
  • MongoDB\Driver\Manager::executeQuery — Execute a database query
  • MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads
  • MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes
  • MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes
  • MongoDB\Driver\Manager::getEncryptedFieldsMap — Return the encryptedFieldsMap auto encryption option for the Manager
  • MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager
  • MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager
  • MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected
  • MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager
  • MongoDB\Driver\Manager::removeSubscriber — Unregisters a monitoring event subscriber with this Manager
  • MongoDB\Driver\Manager::selectServer — Select a server matching a read preference
  • MongoDB\Driver\Manager::startSession — Start a new client session for use with this client


Registers a monitoring event subscriber with this Manager

  • ≪ MongoDB\Driver\Manager
  • MongoDB\Driver\Manager::__construct ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Registers a monitoring event subscriber with this Manager

MongoDB\Driver\Manager::addSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Registers a monitoring event subscriber with this Manager

説明

final public MongoDB\Driver\Manager::addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void

Registers a monitoring event subscriber with this Manager. The subscriber will be notified of all events for this Manager.

注意: If subscriber is already registered with this Manager, this function is a no-op. If subscriber is also registered globally, it will still only be notified once of each event for this Manager.

パラメータ

subscriber (MongoDB\Driver\Monitoring\Subscriber)

A monitoring event subscriber to register with this Manager.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if subscriber is a MongoDB\Driver\Monitoring\LogSubscriber, since loggers can only be registered globally.

参考

  • MongoDB\Driver\Manager::removeSubscriber() - Unregisters a monitoring event subscriber with this Manager
  • MongoDB\Driver\Monitoring\Subscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • Application Performance Monitoring (APM)


Create new MongoDB Manager

  • ≪ MongoDB\Driver\Manager::addSubscriber
  • MongoDB\Driver\Manager::createClientEncryption ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Create new MongoDB Manager

MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Create new MongoDB Manager

説明

final public MongoDB\Driver\Manager::__construct(?string $uri = null, ?array $uriOptions = null, ?array $driverOptions = null)

Constructs a new MongoDB\Driver\Manager object with the specified options.

注意: Per the » Server Discovery and Monitoring Specification, this constructor performs no I/O. Connections will be initialized on demand, when the first operation is executed.

注意: When specifying any SSL or TLS URI options via the connection string or uriOptions parameter, the extension will implicitly enable TLS for its connections. To avoid this, either explicitly disable the tls option or don't specify any TLS options.

注意: On Unix platforms, the extension is sensitive to scripts that use the fork() system call without also calling exec(). Users are advised not to re-use MongoDB\Driver\Manager instances in a forked child process.

パラメータ

uri

A » mongodb:// connection URI:

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

For details on supported URI options, see » Connection String Options in the MongoDB manual. » Connection pool options are not supported, as the extension does not implement connection pools.

The uri is a URL, hence any special characters in its components need to be URL encoded according to » RFC 3986. This is particularly relevant to the username and password, which can often include special characters such as @, :, or %. When connecting via a Unix domain socket, the socket path may contain special characters such as slashes and must be encoded. The rawurlencode() function may be used to encode constituent parts of the URI.

The defaultAuthDb component may be used to specify the database name associated with the user's credentials; however the authSource URI option will take priority if specified. If neither defaultAuthDb nor authSource are specified, the admin database will be used by default. The defaultAuthDb component has no effect in the absence of user credentials.

uriOptions

Additional » connection string options, which will overwrite any options with the same name in the uri parameter.

uriOptions
Option | Type | Description
appname string

MongoDB 3.4+ has the ability to annotate connections with metadata provided by the connecting client. This metadata is included in the server's logs upon establishing a connection and also recorded in slow query logs when database profiling is enabled.

This option may be used to specify an application name, which will be included in the metadata. The value cannot exceed 128 characters in length.

authMechanism string

The authentication mechanism that MongoDB will use to authenticate the connection. For additional details and a list of supported values, see » Authentication Options in the MongoDB manual.

authMechanismProperties array

Properties for the selected authentication mechanism. For additional details and a list of supported properties, see the » Driver Authentication Specification.

注意: When not specified in the URI string, this option is expressed as an array of key/value pairs. The keys and values in this array should be strings.

authSource string

The database name associated with the user's credentials. Defaults to the database component of the connection URI, or the admin database if both are unspecified.

For authentication mechanisms that delegate credential storage to other services (e.g. GSSAPI), this should be "$external".

canonicalizeHostname bool

If true, the driver will resolve the real hostname for the server IP address before authenticating via SASL. Some underlying GSSAPI layers already do this, but the functionality may be disabled in their config (e.g. krb.conf). Defaults to false.

This option is a deprecated alias for the "CANONICALIZE_HOST_NAME" property of the "authMechanismProperties" URI option.

compressors string

A prioritized, comma-delimited list of compressors that the client wants to use. Messages are only compressed if the client and server share any compressors in common, and the compressor used in each direction will depend on the individual configuration of the server or driver. See the » Driver Compression Specification for more information.

connectTimeoutMS int

The time in milliseconds to attempt a connection before timing out. Defaults to 10,000 milliseconds.

directConnection bool

This option can be used to control replica set discovery behavior when only a single host is provided in the connection string. By default, providing a single member in the connection string will establish a direct connection or discover additional members depending on whether the "replicaSet" URI option is omitted or present, respectively. Specify false to force discovery to occur (if "replicaSet" is omitted) or specify true to force a direct connection (if "replicaSet" is present).

gssapiServiceName string

Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances (i.e. » saslServiceName server parameter). Defaults to "mongodb".

This option is a deprecated alias for the "SERVICE_NAME" property of the "authMechanismProperties" URI option.

heartbeatFrequencyMS int

Specifies the interval in milliseconds between the driver's checks of the MongoDB topology, counted from the end of the previous check until the beginning of the next one. Defaults to 60,000 milliseconds.

Per the » Server Discovery and Monitoring Specification, this value cannot be less than 500 milliseconds.

journal bool

Corresponds to the default write concern's journal parameter. If true, writes will require acknowledgement from MongoDB that the operation has been written to the journal. For details, see MongoDB\Driver\WriteConcern.

loadBalanced bool

Specifies whether the driver is connecting to a MongoDB cluster through a load balancer. If true, the driver may only connect to a single host (specified by either the connection string or SRV lookup), the "directConnection" URI option cannot be true, and the "replicaSet" URI option must be omitted. Defaults to false.

localThresholdMS int

The size in milliseconds of the latency window for selecting among multiple suitable MongoDB instances while resolving a read preference. Defaults to 15 milliseconds.

maxStalenessSeconds int

Corresponds to the read preference's "maxStalenessSeconds". Specifies, in seconds, how stale a secondary can be before the client stops using it for read operations. By default, there is no maximum staleness and clients will not consider a secondary's lag when choosing where to direct a read operation. For details, see MongoDB\Driver\ReadPreference.

If specified, the max staleness must be a signed 32-bit integer greater than or equal to MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS (i.e. 90 seconds).

password | string | The password for the user being authenticated. This option is useful if the password contains special characters, which would otherwise need to be URL encoded for the connection URI.
readConcernLevel | string | Corresponds to the read concern's level parameter. Specifies the level of read isolation. For details, see MongoDB\Driver\ReadConcern.
readPreference string

Corresponds to the read preference's mode parameter. Defaults to "primary". For details, see MongoDB\Driver\ReadPreference.

readPreferenceTags array

Corresponds to the read preference's tagSets parameter. Tag sets allow you to target read operations to specific members of a replica set. For details, see MongoDB\Driver\ReadPreference.

注意: When not specified in the URI string, this option is expressed as an array consistent with the format expected by MongoDB\Driver\ReadPreference::__construct().

replicaSet string

Specifies the name of the replica set.

retryReads bool

Specifies whether or not the driver should automatically retry certain read operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to true.

See the » Retryable Reads Specification for more information.

retryWrites bool

Specifies whether or not the driver should automatically retry certain write operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to true.

See » Retryable Writes in the MongoDB manual for more information.

safe bool

If true, specifies 1 for the default write concern's w parameter. If false, 0 is specified. For details, see MongoDB\Driver\WriteConcern.

This option is deprecated and should not be used.

serverSelectionTimeoutMS int

Specifies how long in milliseconds to block for server selection before throwing an exception. Defaults to 30,000 milliseconds.

serverSelectionTryOnce bool

When true, instructs the driver to scan the MongoDB deployment exactly once after server selection fails and then either select a server or raise an error. When false, the driver blocks and searches for a server up to the "serverSelectionTimeoutMS" value. Defaults to true.

socketCheckIntervalMS int

If a socket has not been used recently, the driver must check it via a hello command before using it for any operation. Defaults to 5,000 milliseconds.

socketTimeoutMS int

The time in milliseconds to attempt a send or receive on a socket before timing out. Defaults to 300,000 milliseconds (i.e. five minutes).

srvMaxHosts int

The maximum number of SRV results to randomly select when initially populating the seedlist or, during SRV polling, adding new hosts to the topology. Defaults to 0 (i.e. no maximum).

srvServiceName string

The service name to use for SRV lookup in initial DNS seedlist discovery and SRV polling. Defaults to "mongodb".

ssl bool

Initiates the connection with TLS/SSL if true. Defaults to false.

This option is a deprecated alias for the "tls" URI option.

tls bool

Initiates the connection with TLS/SSL if true. Defaults to false.

tlsAllowInvalidCertificates bool

Specifies whether or not the driver should error when the server's TLS certificate is invalid. Defaults to false.

警告

Disabling certificate validation creates a vulnerability.

tlsAllowInvalidHostnames bool

Specifies whether or not the driver should error when there is a mismatch between the server's hostname and the hostname specified by the TLS certificate. Defaults to false.

警告

Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

tlsCAFile string

Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection. The system certificate store will be used by default.

tlsCertificateKeyFile string

Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated.

tlsCertificateKeyFilePassword string

Password to decrypt the client private key (i.e. "tlsCertificateKeyFile" URI option) to be used for TLS connections.

tlsDisableCertificateRevocationCheck bool

If true, the driver will not attempt to check certificate revocation status (e.g. OCSP, CRL). Defaults to false.

tlsDisableOCSPEndpointCheck bool

If true, the driver will not attempt to contact an OCSP responder endpoint if needed (i.e. an OCSP response is not stapled). Defaults to false.

tlsInsecure bool

Relax TLS constraints as much as possible. Specifying true for this option has the same effect as specifying true for both the "tlsAllowInvalidCertificates" and "tlsAllowInvalidHostnames" URI options. Defaults to false.

警告

Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

username | string | The username for the user being authenticated. This option is useful if the username contains special characters, which would otherwise need to be URL encoded for the connection URI.
w int|string

Corresponds to the default write concern's w parameter. For details, see MongoDB\Driver\WriteConcern.

wTimeoutMS int|string

Corresponds to the default write concern's wtimeout parameter. Specifies a time limit, in milliseconds, for the write concern. For details, see MongoDB\Driver\WriteConcern.

If specified, wTimeoutMS must be a signed 32-bit integer greater than or equal to zero.

zlibCompressionLevel int

Specifies the compression level to use for the zlib compressor. This option has no effect if zlib is not included in the "compressors" URI option. See the » Driver Compression Specification for more information.

driverOptions

driverOptions
Option | Type | Description
allow_invalid_hostname bool

Disables hostname validation if true. Defaults to false.

Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

This option is a deprecated alias for the "tlsAllowInvalidHostnames" URI option.

autoEncryption array

Provides options to enable automatic client-side field level encryption.

注意:

Automatic encryption is an enterprise-only feature that only applies to operations on a collection. Automatic encryption is not supported for operations on a database or view, and operations that are not bypassed will result in error (see » libmongocrypt: Auto Encryption Allow-List). To bypass automatic encryption for all operations, set bypassAutoEncryption to true.

Automatic encryption requires the authenticated user to have the » listCollections privilege action.

Explicit encryption/decryption and automatic decryption is a community feature. The driver can still automatically decrypt when bypassAutoEncryption is true.

The following options are supported:

Options for automatic encryption
Option | Type | Description
keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
keyVaultNamespace | string | A fully qualified namespace (e.g. "databaseName.collectionName") denoting the collection that contains all data keys used for encryption and decryption.
kmsProviders array

A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include "aws", "azure", "gcp", "kmip", and "local" and at least one must be specified.

If an empty document is specified for "aws", "azure", or "gcp", the driver will attempt to configure the provider using » Automatic Credentials.

The format for "aws" is as follows:

aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>,
    sessionToken: <optional string>
}

The format for "azure" is as follows:

azure: {
    tenantId: <string>,
    clientId: <string>,
    clientSecret: <string>,
    identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
}

The format for "gcp" is as follows:

gcp: {
    email: <string>,
    privateKey: <base64 string>|<MongoDB\BSON\Binary>,
    endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
}

The format for "kmip" is as follows:

kmip: {
    endpoint: <string>
}

The format for "local" is as follows:

local: {
    // 96-byte master key used to encrypt/decrypt data keys
    key: <base64 string>|<MongoDB\BSON\Binary>
}
tlsOptions array

A document containing the TLS configuration for one or more KMS providers. Supported providers include "aws", "azure", "gcp", and "kmip". All providers support the following options:

<provider>: {
    tlsCaFile: <optional string>,
    tlsCertificateKeyFile: <optional string>,
    tlsCertificateKeyFilePassword: <optional string>,
    tlsDisableOCSPEndpointCheck: <optional bool>
}
schemaMap array|object

Map of collection namespaces to a local JSON schema. This is used to configure automatic encryption. See » Automatic Encryption Rules in the MongoDB manual for more information. It is an error to specify a collection in both schemaMap and encryptedFieldsMap.

注意: Supplying a schemaMap provides more security than relying on JSON schemas obtained from the server. It protects against a malicious server advertising a false JSON schema, which could trick the client into sending unencrypted data that should be encrypted.

注意: Schemas supplied in the schemaMap only apply to configuring automatic encryption for client side encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.

bypassAutoEncryption | bool | If true, mongocryptd will not be spawned automatically. This is used to disable automatic encryption. Defaults to false.
bypassQueryAnalysis bool

If true, automatic analysis of outgoing commands will be disabled and mongocryptd will not be spawned automatically. This enables the use case of explicit encryption for querying indexed fields without requiring the enterprise licensed crypt_shared library or mongocryptd process. Defaults to false.

encryptedFieldsMap array|object

Map of collection namespaces to an encryptedFields document. This is used to configure queryable encryption. See » Field Encryption and Queryability in the MongoDB manual for more information. It is an error to specify a collection in both encryptedFieldsMap and schemaMap.

注意: Supplying an encryptedFieldsMap provides more security than relying on an encryptedFields obtained from the server. It protects against a malicious server advertising a false encryptedFields.

extraOptions array

The extraOptions relate to the mongocryptd process. The following options are supported:

  • mongocryptdURI (string): URI to connect to an existing mongocryptd process. Defaults to "mongodb://localhost:27020".
  • mongocryptdBypassSpawn (bool): If true, prevent the driver from spawning mongocryptd. Defaults to false.
  • mongocryptdSpawnPath (string): Absolute path to search for mongocryptd binary. Defaults to empty string and consults system paths.
  • mongocryptdSpawnArgs (array): Array of string arguments to pass to mongocryptd when spawning. Defaults to ["--idleShutdownTimeoutSecs=60"].
  • cryptSharedLibPath (string): Absolute path to crypt_shared shared library. Defaults to empty string and consults system paths.
  • cryptSharedLibRequired (bool): If true, require the driver to load crypt_shared. Defaults to false.

See the » Client-Side Encryption Specification for more information.

注意: Automatic encryption is an enterprise only feature that only applies to operations on a collection. Automatic encryption is not supported for operations on a database or view, and operations that are not bypassed will result in error. To bypass automatic encryption for all operations, set bypassAutoEncryption=true in autoEncryption. For more information on allowed operations, see the » Client-Side Encryption Specification.

ca_dir string

Path to a correctly hashed certificate directory. The system certificate store will be used by default.

ca_file string

Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection. The system certificate store will be used by default.

This option is a deprecated alias for the "tlsCAFile" URI option.

context resource

SSL context options to be used as fallbacks if a driver option or its equivalent URI option, if any, is not specified. Note that the extension does not consult the default stream context (i.e. stream_context_get_default()). The following context options are supported:

SSL context option fallbacks
Driver option | Context option (fallback)
ca_dir | capath
ca_file | cafile
pem_file | local_cert
pem_pwd | passphrase
weak_cert_validation | allow_self_signed

This option is supported for backwards compatibility, but should be considered deprecated.

crl_file | string | Path to a certificate revocation list file.
disableClientPersistence bool

If true, this Manager will use a new libmongoc client, which will not be persisted or shared with other Manager objects. When this Manager object is freed, its client will be destroyed and any connections will be closed. Defaults to false.

注意: Disabling client persistence is not generally recommended.

driver array

Allows a higher level library to append its own metadata to the server handshake. By default, the extension submits its own name, version, and platform (i.e. PHP version) in the handshake. Strings can be specified for the "name", "version", and "platform" keys of this array, and will be appended to the respective field(s) in the handshake document.

注意: Handshake information is limited to 512 bytes. The extension will truncate handshake data to fit within this 512-byte string. Higher level libraries are encouraged to keep their own metadata concise.

pem_file string

Path to a PEM encoded certificate to use for client authentication.

This option is a deprecated alias for the "tlsCertificateKeyFile" URI option.

pem_pwd string

Passphrase for the PEM encoded certificate (if applicable).

This option is a deprecated alias for the "tlsCertificateKeyFilePassword" URI option.

serverApi MongoDB\Driver\ServerApi

This option is used to declare a server API version for the manager. If omitted, no API version is declared.

weak_cert_validation bool

Disables certificate validation if true. Defaults to false

This option is a deprecated alias for the "tlsAllowInvalidCertificates" URI option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the uri format is invalid

変更履歴

バージョン 説明
PECL mongodb 1.16.0

The AWS KMS provider for client-side encryption now accepts a "sessionToken" option, which can be used to authenticate with temporary AWS credentials.

Added "tlsDisableOCSPEndpointCheck" to the "tlsOptions" field of the "autoEncryption" driver option.

If an empty document is specified for the "azure" or "gcp" KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

PECL mongodb 1.15.0

If an empty document is specified for the "aws" KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

PECL mongodb 1.14.0

Added the "bypassQueryAnalysis" and "encryptedFieldsMap" auto encryption options. Additional options pertaining to crypt_shared are now supported in the "extraOptions" auto encryption option.

PECL mongodb 1.13.0

Added the "srvMaxHosts" and "srvServiceName" URI options.

PECL mongodb 1.12.0

KMIP is now supported as a KMS provider for client-side encryption and may be configured in the "kmsProviders" field of the "autoEncryption" driver option. Additionally, TLS options for KMS providers may now be configured in the "tlsOptions" field of the "autoEncryption" driver option.

PECL mongodb 1.11.0

Added the "loadBalanced" URI option.

PECL mongodb 1.10.0

Added the "disableClientPersistence" driver option.

Azure and GCP are now supported as KMS providers for client-side encryption and may be configured in the "kmsProviders" field of the "autoEncryption" driver option. Base64-encoded strings are now accepted as an alternative to MongoDB\BSON\Binary for options within "kmsProviders".

PECL mongodb 1.8.0

Added the "directConnection", "tlsDisableCertificateRevocationCheck", and "tlsDisableOCSPEndpointCheck" URI options.

Added the "driver" driver option.

PECL mongodb 1.7.0

Added the "autoEncryption" driver option.

Specifying any SSL or TLS option via the driverOptions parameter will now implicitly enable TLS, as is done for the corresponding URI options.

PECL mongodb 1.6.0

Added the "retryReads", "tls", "tlsAllowInvalidCertificates", "tlsAllowInvalidHostnames", "tlsCAFile", "tlsCertificateKeyFile", "tlsCertificateKeyFilePassword", and "tlsInsecure" URI options.

The "retryWrites" URI option defaults to true.

Specifying any SSL or TLS URI option via the connection string or uriOptions parameter will now implicitly enable TLS unless ssl or tls is false. TLS is not implicitly enabled for any options in the driverOptions parameter, which is unchanged from previous versions.

PECL mongodb 1.5.0

"wtimeoutMS" is now always validated and applied to the write concern. Previously, the option was ignored if "w" was <= 1, since the timeout only applies to replication.

PECL mongodb 1.4.0

Added the "compressors", "retryWrites", and "zlibCompressionLevel" URI options.

PECL mongodb 1.3.0

The uriOptions argument now accepts "authMechanism" and "authMechanismProperties" options. Previously, these options were only supported in the uri argument.

PECL mongodb 1.2.0

The uri argument defaults to "mongodb://127.0.0.1/". The default port remains 27017.

Added the "appname" URI option.

Added the "allow_invalid_hostname", "ca_file", "ca_dir", "clr_file", "pem_file", "pem_pwd", and "weak_cert_validation" driver options.

The PHP Streams API is no longer used for socket communication. The "connectTimeoutMS" URI option now defaults to 10 seconds instead of default_socket_timeout in previous versions. Additionally, the extension no longer supports all SSL context options via the "context" driver option.

PECL mongodb 1.1.0

The uri argument is optional and defaults to "mongodb://localhost:27017/".

例

例1 MongoDB\Driver\Manager::__construct() basic examples

Connecting to standalone MongoDB node:

<?php

$manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

?>

Connecting to standalone MongoDB node via a Unix domain socket. The socket path may include special characters such as slashes and should be encoded with rawurlencode().

<?php

$manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

?>

Connecting to a replica set:

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

?>

Connecting to a sharded cluster (i.e. one or more mongos instances):

<?php

$manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

?>

Connecting to MongoDB with authentication credentials for a particular user and database:

<?php

$manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");

?>

Connecting to MongoDB with authentication credentials for a particular user and database, where the username or password includes special characters (e.g. @, :, %). In the following example, the password string myp@ss:w%rd has been manually escaped; however, rawurlencode() may also be used to escape URI components that may contain special characters.

<?php

$manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/?authSource=databaseName");

?>

Connecting to MongoDB with X509 authentication:

<?php

$manager = new MongoDB\Driver\Manager(
"mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
[],
[
"pem_file" => "/path/to/client.pem",
]
);
?>

参考

  • Connection handling and persistence
  • » MongoDB Connection String Format


Create a new ClientEncryption object

  • ≪ MongoDB\Driver\Manager::__construct
  • MongoDB\Driver\Manager::executeBulkWrite ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Create a new ClientEncryption object

MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object

説明

final public MongoDB\Driver\Manager::createClientEncryption(array $options): MongoDB\Driver\ClientEncryption

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

パラメータ

options

options
Option | Type | Description
keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
keyVaultNamespace | string | A fully qualified namespace (e.g. "databaseName.collectionName") denoting the collection that contains all data keys used for encryption and decryption.
kmsProviders array

A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include "aws", "azure", "gcp", "kmip", and "local" and at least one must be specified.

If an empty document is specified for "aws", "azure", or "gcp", the driver will attempt to configure the provider using » Automatic Credentials.

The format for "aws" is as follows:

aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>,
    sessionToken: <optional string>
}

The format for "azure" is as follows:

azure: {
    tenantId: <string>,
    clientId: <string>,
    clientSecret: <string>,
    identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
}

The format for "gcp" is as follows:

gcp: {
    email: <string>,
    privateKey: <base64 string>|<MongoDB\BSON\Binary>,
    endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
}

The format for "kmip" is as follows:

kmip: {
    endpoint: <string>
}

The format for "local" is as follows:

local: {
    // 96-byte master key used to encrypt/decrypt data keys
    key: <base64 string>|<MongoDB\BSON\Binary>
}
tlsOptions array

A document containing the TLS configuration for one or more KMS providers. Supported providers include "aws", "azure", "gcp", and "kmip". All providers support the following options:

<provider>: {
    tlsCaFile: <optional string>,
    tlsCertificateKeyFile: <optional string>,
    tlsCertificateKeyFilePassword: <optional string>,
    tlsDisableOCSPEndpointCheck: <optional bool>
}

戻り値

Returns a new MongoDB\Driver\ClientEncryption instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

変更履歴

バージョン | 説明
PECL mongodb 1.16.0

The AWS KMS provider for client-side encryption now accepts a "sessionToken" option, which can be used to authenticate with temporary AWS credentials.

Added "tlsDisableOCSPEndpointCheck" to the "tlsOptions" option.

If an empty document is specified for the "azure" or "gcp" KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

PECL mongodb 1.15.0

If an empty document is specified for the "aws" KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

PECL mongodb 1.12.0

KMIP is now supported as a KMS provider for client-side encryption and may be configured in the "kmsProviders" option.

Added the "tlsOptions" option.

PECL mongodb 1.10.0 | Azure and GCP are now supported as KMS providers for client-side encryption and may be configured in the "kmsProviders" option. Base64-encoded strings are now accepted as an alternative to MongoDB\BSON\Binary for options within "kmsProviders".

参考

  • MongoDB\Driver\ClientEncryption::__construct() - Create a new ClientEncryption object
  • » Explicit (Manual) Client-Side Field Level Encryption in the MongoDB manual


Execute one or more write operations

  • ≪ MongoDB\Driver\Manager::createClientEncryption
  • MongoDB\Driver\Manager::executeCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute one or more write operations

MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations

説明

final public MongoDB\Driver\Manager::executeBulkWrite(string $namespace, MongoDB\Driver\BulkWrite $bulk, array|MongoDB\Driver\WriteConcern|null $options = null): MongoDB\Driver\WriteResult

Executes one or more write operations on the primary server.

A MongoDB\Driver\BulkWrite can be constructed with one or more write operations of varying types (e.g. updates, deletes, and inserts). The driver will attempt to send operations of the same type to the server in as few requests as possible to optimize round trips.

The default value for the "writeConcern" option will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

パラメータ

namespace (string)

A fully qualified namespace (e.g. "databaseName.collectionName").

bulk (MongoDB\Driver\BulkWrite)

The write(s) to execute.

options

options
Option Type Description
session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

戻り値

Returns MongoDB\Driver\WriteResult on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk does not contain any write operations.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk has already been executed. MongoDB\Driver\BulkWrite objects may not be executed multiple times.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\BulkWriteException on any write failure (e.g. write error, failure to apply a write concern)
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\WriteConcern object.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is now thrown if bulk does not contain any write operations. Previously, a MongoDB\Driver\Exception\BulkWriteException was thrown.

例

例1 MongoDB\Driver\Manager::executeBulkWrite() example

<?php

$bulk = new MongoDB\Driver\BulkWrite();

$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);

$bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
$bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
$bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

$bulk->insert(['_id' => 4, 'x' => 2]);

$bulk->delete(['x' => 1], ['limit' => 1]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
$result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Matched %d document(s)\n", $result->getMatchedCount());
printf("Updated %d document(s)\n", $result->getModifiedCount());
printf("Upserted %d document(s)\n", $result->getUpsertedCount());
printf("Deleted %d document(s)\n", $result->getDeletedCount());

foreach ($result->getUpsertedIds() as $index => $id) {
printf('upsertedId[%d]: ', $index);
var_dump($id);
}

/* If the WriteConcern could not be fulfilled */
if ($writeConcernError = $result->getWriteConcernError()) {
printf("%s (%d): %s\n", $writeConcernError->getMessage(), $writeConcernError->getCode(), var_export($writeConcernError->getInfo(), true));
}

/* If a write could not happen at all */
foreach ($result->getWriteErrors() as $writeError) {
printf("Operation#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
}
?>

上の例の出力は、 たとえば以下のようになります。

Inserted 3 document(s)
Matched  1 document(s)
Updated  1 document(s)
Upserted 2 document(s)
Deleted  1 document(s)
upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
  ["oid"]=>
  string(24) "54d3adc3ce7a792f4d703756"
}
upsertedId[4]: int(3)

参考

  • MongoDB\Driver\BulkWrite
  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\Server::executeBulkWrite() - Execute one or more write operations on this server


Execute a database command

  • ≪ MongoDB\Driver\Manager::executeBulkWrite
  • MongoDB\Driver\Manager::executeQuery ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command

MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Execute a database command

説明

final public MongoDB\Driver\Manager::executeCommand(string $db, MongoDB\Driver\Command $command, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the command on that server.

This method applies no special logic to the command. The Default values for the "readPreference", "readConcern", and "writeConcern" options will be inferred from an active transaction (indicated by the "session" option). If there is no active transaction, a primary read preference will be used for server selection.

Default values will not be inferred from the connection URI. Users are therefore encouraged to use specific read and/or write command methods if possible.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

例

例1 MongoDB\Driver\Manager::executeCommand() with a command returning a single result document

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$command = new MongoDB\Driver\Command(['ping' => 1]);

try {
$cursor = $manager->executeCommand('admin', $command);
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}

/* The ping command returns a single result document, so we need to access the
* first result in the cursor. */
$response = $cursor->toArray()[0];

var_dump($response);

?>

上の例の出力は以下となります。

array(1) {
  ["ok"]=>
  float(1)
}

例2 MongoDB\Driver\Manager::executeCommand() with a command returning a cursor

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1, 'y' => 'foo']);
$bulk->insert(['x' => 2, 'y' => 'bar']);
$bulk->insert(['x' => 3, 'y' => 'bar']);
$manager->executeBulkWrite('db.collection', $bulk);

$command = new MongoDB\Driver\Command([
'aggregate' => 'collection',
'pipeline' => [
['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
],
'cursor' => new stdClass,
]);
$cursor = $manager->executeCommand('db', $command);

/* The aggregate command can optionally return its results in a cursor instead
* of a single result document. In this case, we can iterate on the cursor
* directly to access those results. */
foreach ($cursor as $document) {
var_dump($document);
}

?>

上の例の出力は以下となります。

object(stdClass)#6 (2) {
  ["_id"]=>
  string(3) "bar"
  ["sum"]=>
  int(10)
}
object(stdClass)#7 (2) {
  ["_id"]=>
  string(3) "foo"
  ["sum"]=>
  int(2)
}

例3 Limiting execution time for a command

The execution time of a command may be limited by specifying a value for "maxTimeMS" in the MongoDB\Driver\Command document. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

$command = new MongoDB\Driver\Command([
'count' => 'collection',
'query' => ['x' => ['$gt' => 1]],
'maxTimeMS' => 1000,
]);

$cursor = $manager->executeCommand('db', $command);

var_dump($cursor->toArray()[0]);

?>

If the command fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

注意

注意: If a secondary readPreference is used, it is the caller's responsibility to ensure that the command can be executed on a secondary. No validation is done by the driver.

注意: This method does not default to using the read preference from the MongoDB Connection URI. Applications in need of that behavior should consider using MongoDB\Driver\Manager::executeReadCommand().

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads
  • MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes
  • MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes
  • MongoDB\Driver\Server::executeCommand() - Execute a database command on this server


Execute a database query

  • ≪ MongoDB\Driver\Manager::executeCommand
  • MongoDB\Driver\Manager::executeReadCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database query

MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Execute a database query

説明

final public MongoDB\Driver\Manager::executeQuery(string $namespace, MongoDB\Driver\Query $query, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the query on that server.

Default values for the "readPreference" option and Query's "readConcern" option will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

パラメータ

namespace (string)

A fully qualified namespace (e.g. "databaseName.collectionName").

query (MongoDB\Driver\Query)

The query to execute.

options

options
Option Type Description
readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

例

例1 MongoDB\Driver\Manager::executeQuery() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$filter = ['x' => ['$gt' => 1]];
$options = [
'projection' => ['_id' => 0],
'sort' => ['x' => -1],
];

$query = new MongoDB\Driver\Query($filter, $options);
$cursor = $manager->executeQuery('db.collection', $query);

foreach ($cursor as $document) {
var_dump($document);
}

?>

上の例の出力は以下となります。

object(stdClass)#6 (1) {
  ["x"]=>
  int(3)
}
object(stdClass)#7 (1) {
  ["x"]=>
  int(2)
}

例2 Limiting execution time for a query

The "maxTimeMS" MongoDB\Driver\Query option may be used to limit the execution time of a query. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

$filter = ['x' => ['$gt' => 1]];
$options = [
'maxTimeMS' => 1000,
];

$query = new MongoDB\Driver\Query($filter, $options);
$cursor = $manager->executeQuery('db.collection', $query);

foreach ($cursor as $document) {
var_dump($document);
}

?>

If the query fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

参考

  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Query
  • MongoDB\Driver\ReadPreference
  • MongoDB\Driver\Server::executeQuery() - Execute a database query on this server


Execute a database command that reads

  • ≪ MongoDB\Driver\Manager::executeQuery
  • MongoDB\Driver\Manager::executeReadWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command that reads

MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads

説明

final public MongoDB\Driver\Manager::executeReadCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor

Selects a server according to the "readPreference" option and executes the command on that server.

This method will apply logic that is specific to commands that read (e.g. » distinct). Default values for the "readPreference" and "readConcern" options will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Manager::executeCommand() - Execute a database command
  • MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes
  • MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes
  • MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server


Execute a database command that reads and writes

  • ≪ MongoDB\Driver\Manager::executeReadCommand
  • MongoDB\Driver\Manager::executeWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command that reads and writes

MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes

説明

final public MongoDB\Driver\Manager::executeReadWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor

Executes the command on the primary server.

This method will apply logic that is specific to commands that read and write (e.g. » aggregate). Default values for the "readConcern" and "writeConcern" options will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Manager::executeCommand() - Execute a database command
  • MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads
  • MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes
  • MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server


Execute a database command that writes

  • ≪ MongoDB\Driver\Manager::executeReadWriteCommand
  • MongoDB\Driver\Manager::getEncryptedFieldsMap ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Execute a database command that writes

MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes

説明

final public MongoDB\Driver\Manager::executeWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor

Executes the command on the primary server.

This method will apply logic that is specific to commands that write (e.g. » drop). The default value for the "writeConcern" option will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

注意: This method is not intended to be used to execute » insert, » update, or » delete commands. Users are encouraged to use MongoDB\Driver\Manager::executeBulkWrite() for those operations.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Manager::executeCommand() - Execute a database command
  • MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads
  • MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes
  • MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server


Return the encryptedFieldsMap auto encryption option for the Manager

  • ≪ MongoDB\Driver\Manager::executeWriteCommand
  • MongoDB\Driver\Manager::getReadConcern ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the encryptedFieldsMap auto encryption option for the Manager

MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Return the encryptedFieldsMap auto encryption option for the Manager

説明

final public MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Returns the encryptedFieldsMap auto encryption option for the Manager, if specified.

パラメータ

この関数にはパラメータはありません。

戻り値

The encryptedFieldsMap auto encryption option for the Manager, or null if it was not specified.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager


Return the ReadConcern for the Manager

  • ≪ MongoDB\Driver\Manager::getEncryptedFieldsMap
  • MongoDB\Driver\Manager::getReadPreference ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the ReadConcern for the Manager

MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager

説明

final public MongoDB\Driver\Manager::getReadConcern(): MongoDB\Driver\ReadConcern

Returns the MongoDB\Driver\ReadConcern for the Manager, which is derived from its URI options. This is the default read concern for queries and commands executed on the Manager.

パラメータ

この関数にはパラメータはありません。

戻り値

The MongoDB\Driver\ReadConcern for the Manager.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Manager::getReadConcern() example

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
var_dump($manager->getReadConcern());

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readConcernLevel=local');
var_dump($manager->getReadConcern());

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\ReadConcern)#2 (0) {
}
object(MongoDB\Driver\ReadConcern)#1 (1) {
  ["level"]=>
  string(5) "local"
}

参考

  • MongoDB\Driver\ReadConcern
  • MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager


Return the ReadPreference for the Manager

  • ≪ MongoDB\Driver\Manager::getReadConcern
  • MongoDB\Driver\Manager::getServers ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the ReadPreference for the Manager

MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager

説明

final public MongoDB\Driver\Manager::getReadPreference(): MongoDB\Driver\ReadPreference

Returns the MongoDB\Driver\ReadPreference for the Manager, which is derived from its URI options. This is the default read preference for queries and commands executed on the Manager.

パラメータ

この関数にはパラメータはありません。

戻り値

The MongoDB\Driver\ReadPreference for the Manager.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Manager::getReadPreference() example

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
var_dump($manager->getReadPreference());

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=');
var_dump($manager->getReadPreference());

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\ReadPreference)#2 (1) {
  ["mode"]=>
  string(7) "primary"
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(18) "secondaryPreferred"
  ["tags"]=>
  array(3) {
    [0]=>
    object(stdClass)#3 (2) {
      ["dc"]=>
      string(2) "ny"
      ["rack"]=>
      string(1) "1"
    }
    [1]=>
    object(stdClass)#4 (1) {
      ["dc"]=>
      string(2) "ny"
    }
    [2]=>
    object(stdClass)#5 (0) {
    }
  }
}

参考

  • MongoDB\Driver\ReadPreference
  • MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager


Return the servers to which this manager is connected

  • ≪ MongoDB\Driver\Manager::getReadPreference
  • MongoDB\Driver\Manager::getWriteConcern ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the servers to which this manager is connected

MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected

説明

final public MongoDB\Driver\Manager::getServers(): array

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

注意: Since the driver connects to the database lazily, this method may return an empty array if called before executing an operation on the MongoDB\Driver\Manager.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Manager::getServers() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

/* The driver connects to the database server lazily, so Manager::getServers()
* may initially return an empty array. */
var_dump($manager->getServers());

$command = new MongoDB\Driver\Command(['ping' => 1]);
$manager->executeCommand('db', $command);

var_dump($manager->getServers());

?>

上の例の出力は、 たとえば以下のようになります。

array(0) {
}
array(1) {
  [0]=>
  object(MongoDB\Driver\Server)#3 (10) {
    ["host"]=>
    string(9) "localhost"
    ["port"]=>
    int(27017)
    ["type"]=>
    int(1)
    ["is_primary"]=>
    bool(false)
    ["is_secondary"]=>
    bool(false)
    ["is_arbiter"]=>
    bool(false)
    ["is_hidden"]=>
    bool(false)
    ["is_passive"]=>
    bool(false)
    ["last_hello_response"]=>
    array(8) {
      ["isWritablePrimary"]=>
      bool(true)
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["maxMessageSizeBytes"]=>
      int(48000000)
      ["maxWriteBatchSize"]=>
      int(1000)
      ["localTime"]=>
      object(MongoDB\BSON\UTCDateTime)#4 (1) {
        ["milliseconds"]=>
        int(1447267964517)
      }
      ["maxWireVersion"]=>
      int(3)
      ["minWireVersion"]=>
      int(0)
      ["ok"]=>
      float(1)
    }
    ["round_trip_time"]=>
    int(554)
  }
}

参考

  • MongoDB\Driver\Server
  • MongoDB\Driver\Manager::selectServer() - Select a server matching a read preference


Return the WriteConcern for the Manager

  • ≪ MongoDB\Driver\Manager::getServers
  • MongoDB\Driver\Manager::removeSubscriber ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Return the WriteConcern for the Manager

MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager

説明

final public MongoDB\Driver\Manager::getWriteConcern(): MongoDB\Driver\WriteConcern

Returns the MongoDB\Driver\WriteConcern for the Manager, which is derived from its URI options. This is the default write concern for writes and commands executed on the Manager.

パラメータ

この関数にはパラメータはありません。

戻り値

The MongoDB\Driver\WriteConcern for the Manager.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Manager::getWriteConcern() example

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
var_dump($manager->getWriteConcern());

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?w=majority&wtimeoutMS=2000');
var_dump($manager->getWriteConcern());

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\WriteConcern)#2 (0) {
}
object(MongoDB\Driver\WriteConcern)#1 (2) {
  ["w"]=>
  string(8) "majority"
  ["wtimeout"]=>
  int(2000)
}

参考

  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager


Unregisters a monitoring event subscriber with this Manager

  • ≪ MongoDB\Driver\Manager::getWriteConcern
  • MongoDB\Driver\Manager::selectServer ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Unregisters a monitoring event subscriber with this Manager

MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Unregisters a monitoring event subscriber with this Manager

説明

final public MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void

Unregisters a monitoring event subscriber with this Manager.

注意: If subscriber is not already registered with this Manager, this function is a no-op.

パラメータ

subscriber (MongoDB\Driver\Monitoring\Subscriber)

A monitoring event subscriber to unregister with this Manager.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
  • MongoDB\Driver\Monitoring\Subscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Monitoring\removeSubscriber() - Unregisters a monitoring event subscriber globally
  • Application Performance Monitoring (APM)


Select a server matching a read preference

  • ≪ MongoDB\Driver\Manager::removeSubscriber
  • MongoDB\Driver\Manager::startSession ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Select a server matching a read preference

MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Select a server matching a read preference

説明

final public MongoDB\Driver\Manager::selectServer(?MongoDB\Driver\ReadPreference $readPreference = null): MongoDB\Driver\Server

Selects a MongoDB\Driver\Server matching readPreference. If readPreference is null or omitted, the primary server will be selected by default. This may be used to preselect a server in order to perform version checking before executing an operation.

注意: Unlike MongoDB\Driver\Manager::getServers(), this method will initialize database connections and perform server discovery if necessary. See the » Server Selection Specification for additional information.

パラメータ

readPreference (MongoDB\Driver\ReadPreference)

The read preference to use for selecting a server. If null or omitted, the primary server will be selected by default.

戻り値

Returns a MongoDB\Driver\Server matching the read preference.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException if a server matching the read preference could not be found.

変更履歴

バージョン | 説明
PECL mongodb 1.11.0 | The readPreference is now optional. If null or omitted, the primary server will be selected by default.

参考

  • MongoDB\Driver\Server
  • MongoDB\Driver\Manager::getServers() - Return the servers to which this manager is connected
  • » Server Selection Specification


Start a new client session for use with this client

  • ≪ MongoDB\Driver\Manager::selectServer
  • MongoDB\Driver\Command ≫
  • PHP Manual
  • MongoDB\Driver\Manager
  • Start a new client session for use with this client

MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Start a new client session for use with this client

説明

final public MongoDB\Driver\Manager::startSession(?array $options = null): MongoDB\Driver\Session

Creates a MongoDB\Driver\Session for the given options. The session may then be specified when executing commands, queries, and write operations.

注意: A MongoDB\Driver\Session can only be used with the MongoDB\Driver\Manager from which it was created.

パラメータ

options

options
Option Type Description Default
causalConsistency bool

Configure causal consistency in a session. If true, each operation in the session will be causally ordered after the previous read or write operation. Set to false to disable causal consistency.

See » Casual Consistency in the MongoDB manual for more information.

true
defaultTransactionOptions array

Default options to apply to newly created transactions. These options are used unless they are overridden when a transaction is started with different value for each option.

options
Option Type Description
maxCommitTimeMS integer

The maximum amount of time in milliseconds to allow a single commitTransaction command to run.

If specified, maxCommitTimeMS must be a signed 32-bit integer greater than or equal to zero.

readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

This option is available in MongoDB 4.0+.

[]
snapshot bool

Configure snapshot reads in a session. If true, a timestamp will be obtained from the first supported read operation in the session (i.e. find, aggregate, or unsharded distinct). Subsequent read operations within the session will then utilize a "snapshot" read concern level to read majority-committed data from that timestamp. Set to false to disable snapshot reads.

Snapshot reads require MongoDB 5.0+ and cannot be used with causal consistency, transactions, or write operations. If "snapshot" is true, "causalConsistency" will default to false.

See » Read Concern "snapshot" in the MongoDB manual for more information.

false

戻り値

Returns a MongoDB\Driver\Session.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "causalConsistency" and "snapshot" options are both true.
  • Throws MongoDB\Driver\Exception\RuntimeException if the session could not be created (e.g. libmongoc does not support crypto).

変更履歴

バージョン | 説明
PECL mongodb 1.11.0 | The "snapshot" option was added.
PECL mongodb 1.6.0 | The "maxCommitTimeMS" option was added to "defaultTransactionOptions".
PECL mongodb 1.5.0 | The "defaultTransactionOptions" option was added.

参考

  • MongoDB\Driver\Session
  • » Casual Consistency in the MongoDB manual


The MongoDB\Driver\Command class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\Command class is a value object that represents a database command.

To provide Command Helpers the MongoDB\Driver\Command object should be composed.

クラス概要

final class MongoDB\Driver\Command {
/* メソッド */
final public __construct(array|object $document, ?array $commandOptions = null)
}

例

例1 Composing MongoDB\Driver\Command to provide a helper to create collections

<?php
class CreateCollection {
protected $cmd = array();

function __construct($collectionName) {
$this->cmd["create"] = (string)$collectionName;
}
function setCappedCollection($maxBytes, $maxDocuments = false) {
$this->cmd["capped"] = true;
$this->cmd["size"] = (int)$maxBytes;

if ($maxDocuments) {
$this->cmd["max"] = (int)$maxDocuments;
}
}
function usePowerOf2Sizes($bool) {
if ($bool) {
$this->cmd["flags"] = 1;
} else {
$this->cmd["flags"] = 0;
}
}
function setFlags($flags) {
$this->cmd["flags"] = (int)$flags;
}
function getCommand() {
return new MongoDB\Driver\Command($this->cmd);
}
function getCollectionName() {
return $this->cmd["create"];
}
}

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$createCollection = new CreateCollection("cappedCollection");
$createCollection->setCappedCollection(64 * 1024);

try {
$command = $createCollection->getCommand();
$cursor = $manager->executeCommand("databaseName", $command);
$response = $cursor->toArray()[0];
var_dump($response);

$collstats = ["collstats" => $createCollection->getCollectionName()];
$cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
$response = $cursor->toArray()[0];
var_dump($response);
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}

?>

上の例の出力は以下となります。

object(MongoDB\Driver\Command)#3 (1) {
  ["command"]=>
  array(3) {
    ["create"]=>
    string(16) "cappedCollection"
    ["capped"]=>
    bool(true)
    ["size"]=>
    int(65536)
  }
}
array(1) {
  ["ok"]=>
  float(1)
}
array(16) {
  ["ns"]=>
  string(29) "databaseName.cappedCollection"
  ["count"]=>
  int(0)
  ["size"]=>
  int(0)
  ["numExtents"]=>
  int(1)
  ["storageSize"]=>
  int(65536)
  ["nindexes"]=>
  int(1)
  ["lastExtentSize"]=>
  float(65536)
  ["paddingFactor"]=>
  float(1)
  ["paddingFactorNote"]=>
  string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
  ["userFlags"]=>
  int(0)
  ["capped"]=>
  bool(true)
  ["max"]=>
  int(9223372036854775807)
  ["maxSize"]=>
  int(65536)
  ["totalIndexSize"]=>
  int(8176)
  ["indexSizes"]=>
  object(stdClass)#4 (1) {
    ["_id_"]=>
    int(8176)
  }
  ["ok"]=>
  float(1)
}

目次

  • MongoDB\Driver\Command::__construct — Create a new Command


Create a new Command

  • ≪ MongoDB\Driver\Command
  • MongoDB\Driver\Query ≫
  • PHP Manual
  • MongoDB\Driver\Command
  • Create a new Command

MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Create a new Command

説明

final public MongoDB\Driver\Command::__construct(array|object $document, ?array $commandOptions = null)

Constructs a new MongoDB\Driver\Command, which is an immutable value object that represents a database command. The command may then be executed with MongoDB\Driver\Manager::executeCommand().

The complete command document, which includes the command name and its options, should be expressed in the document parameter. The commandOptions parameter is only used to specify options related to the execution of the command and the resulting MongoDB\Driver\Cursor.

パラメータ

document

The complete command document, which will be sent to the server.

commandOptions

注意: Do not use this parameter to specify options described in the command's reference in the MongoDB manual. This parameter should only be used for the options explicitly listed below.

commandOptions
Option Type Description
maxAwaitTimeMS int

Positive integer denoting the time limit in milliseconds for the server to block a getMore operation if no data is available. This option should only be used in conjunction with commands that return a tailable cursor (e.g. » Change Streams).

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | Added a second commandOptions argument, which supports the "maxAwaitTimeMS" option.

例

例1 MongoDB\Driver\Command::__construct() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$command = new MongoDB\Driver\Command(array("buildinfo" => 1));

try {
$cursor = $manager->executeCommand("admin", $command);
$response = $cursor->toArray()[0];
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}
var_dump($response);

?>

上の例の出力は、 たとえば以下のようになります。

array(13) {
  ["version"]=>
  string(14) "2.8.0-rc2-pre-"
  ["gitVersion"]=>
  string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
  ["OpenSSLVersion"]=>
  string(25) "OpenSSL 1.0.1f 6 Jan 2014"
  ["sysInfo"]=>
  string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
  ["loaderFlags"]=>
  string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
  ["compilerFlags"]=>
  string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
  ["allocator"]=>
  string(8) "tcmalloc"
  ["versionArray"]=>
  array(4) {
    [0]=>
    int(2)
    [1]=>
    int(8)
    [2]=>
    int(0)
    [3]=>
    int(-8)
  }
  ["javascriptEngine"]=>
  string(2) "V8"
  ["bits"]=>
  int(64)
  ["debug"]=>
  bool(false)
  ["maxBsonObjectSize"]=>
  int(16777216)
  ["ok"]=>
  float(1)
}

例2 MongoDB\Driver\Command::__construct() example

Commands can accept options as well, as part of the normal structure that you create to send to the server. For example, the maxTimeMS option can be passed with most commands to restrict the amount of time a specific command can run for on the server.

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$command = new MongoDB\Driver\Command(
array(
"distinct" => "beer",
"key" => "beer_name",
"maxTimeMS" => 10,
)
);

try {
$cursor = $manager->executeCommand("beerdb", $command);
$response = $cursor->toArray()[0];
} catch(MongoDB\Driver\Exception\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}
var_dump($response);

?>

上の例の出力は、 たとえば以下のようになります。

operation exceeded time limit

参考

  • MongoDB\Driver\Manager::executeCommand() - Execute a database command
  • MongoDB\Driver\Cursor


The MongoDB\Driver\Query class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\Query class is a value object that represents a database query.

クラス概要

final class MongoDB\Driver\Query {
/* メソッド */
final public __construct(array|object $filter, ?array $queryOptions = null)
}

目次

  • MongoDB\Driver\Query::__construct — Create a new Query


Create a new Query

  • ≪ MongoDB\Driver\Query
  • MongoDB\Driver\BulkWrite ≫
  • PHP Manual
  • MongoDB\Driver\Query
  • Create a new Query

MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Create a new Query

説明

final public MongoDB\Driver\Query::__construct(array|object $filter, ?array $queryOptions = null)

Constructs a new MongoDB\Driver\Query, which is an immutable value object that represents a database query. The query may then be executed with MongoDB\Driver\Manager::executeQuery().

パラメータ

filter (array|object)

The » query predicate. An empty predicate will match all documents in the collection.

注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

queryOptions

queryOptions
Option | Type | Description
allowDiskUse bool

Allows MongoDB to use temporary disk files to store data exceeding the 100 megabyte system memory limit while processing a blocking sort operation.

allowPartialResults bool

For queries against a sharded collection, returns partial results from the mongos if some shards are unavailable instead of throwing an error.

Falls back to the deprecated "partial" option if not specified.

awaitData | bool | Use in conjunction with the "tailable" option to block a getMore operation on the cursor temporarily if at the end of data rather than returning no data. After a timeout period, the query returns as normal.
batchSize int

The number of documents to return in the first batch. Defaults to 101. A batch size of 0 means that the cursor will be established, but no documents will be returned in the first batch.

In versions of MongoDB before 3.2, where queries use the legacy wire protocol OP_QUERY, a batch size of 1 will close the cursor irrespective of the number of matched documents.

collation array|object

» Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the "locale" field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document.

If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.

comment mixed

An arbitrary comment to help trace the operation through the database profiler, currentOp output, and logs.

The comment can be any valid BSON type for MongoDB 4.4+. Earlier server versions only support string values.

Falls back to the deprecated "$comment" modifier if not specified.

exhaust bool

Stream the data down full blast in multiple "more" packages, on the assumption that the client will fully read all data queried. Faster when you are pulling a lot of data and know you want to pull it all down. Note: the client is not allowed to not read all the data unless it closes the connection.

This option is not supported by the find command in MongoDB 3.2+ and will force the driver to use the legacy wire protocol version (i.e. OP_QUERY).

explain bool

If true, the returned MongoDB\Driver\Cursor will contain a single document that describes the process and indexes used to return the query.

Falls back to the deprecated "$explain" modifier if not specified.

This option is not supported by the find command in MongoDB 3.2+ and will only be respected when using the legacy wire protocol version (i.e. OP_QUERY). The » explain command should be used on MongoDB 3.0+.

hint string|array|object

Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

Falls back to the deprecated "hint" option if not specified.

let array|object

Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. $$var).

This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.

limit int

The maximum number of documents to return. If unspecified, then defaults to no limit. A limit of 0 is equivalent to setting no limit.

A negative limit is will be interpreted as a positive limit with the "singleBatch" option set to true. This behavior is supported for backwards compatibility, but should be considered deprecated.

max array|object

The exclusive upper bound for a specific index.

Falls back to the deprecated "$max" modifier if not specified.

maxAwaitTimeMS int

Positive integer denoting the time limit in milliseconds for the server to block a getMore operation if no data is available. This option should only be used in conjunction with the "tailable" and "awaitData" options.

maxScan int
警告

This option is deprecated and should not be used.

Positive integer denoting the maximum number of documents or index keys to scan when executing the query.

Falls back to the deprecated "$maxScan" modifier if not specified.

maxTimeMS int

The cumulative time limit in milliseconds for processing operations on the cursor. MongoDB aborts the operation at the earliest following interrupt point.

Falls back to the deprecated "$maxTimeMS" modifier if not specified.

min array|object

The inclusive lower bound for a specific index.

Falls back to the deprecated "$min" modifier if not specified.

modifiers | array | » Meta operators modifying the output or behavior of a query. Use of these operators is deprecated in favor of named options.
noCursorTimeout | bool | Prevents the server from timing out idle cursors after an inactivity period (10 minutes).
oplogReplay bool

Internal use for replica sets. To use oplogReplay, you must include the following condition in the filter:

[ 'ts' => [ '$gte' => <timestamp> ] ]

注意: This option is deprecated as of the 1.8.0 release.
projection array|object

The » projection specification to determine which fields to include in the returned documents.

If you are using the ODM functionality to deserialise documents as their original PHP class, make sure that you include the __pclass field in the projection. This is required for the deserialization to work and without it, the extension will return (by default) a stdClass object instead.

readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation. By default, the read concern from the MongoDB Connection URI will be used.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

returnKey bool

If true, returns only the index keys in the resulting documents. Default value is false. If true and the find command does not use an index, the returned documents will be empty.

Falls back to the deprecated "$returnKey" modifier if not specified.

showRecordId bool

Determines whether to return the record identifier for each document. If true, adds a top-level "$recordId" field to the returned documents.

Falls back to the deprecated "$showDiskLoc" modifier if not specified.

singleBatch | bool | Determines whether to close the cursor after the first batch. Defaults to false.
skip | int | Number of documents to skip. Defaults to 0.
snapshot bool
警告

This option is deprecated and should not be used.

Prevents the cursor from returning a document more than once because of an intervening write operation.

Falls back to the deprecated "$snapshot" modifier if not specified.

sort array|object

The sort specification for the ordering of the results.

Falls back to the deprecated "$orderby" modifier if not specified.

tailable | bool | Returns a tailable cursor for a capped collection.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.14.0

Added the "let" option. The "comment" option now accepts any type.

PECL mongodb 1.8.0

Added the "allowDiskUse" option.

The "oplogReplay" option is deprecated.

PECL mongodb 1.5.0

The "maxScan" and "snapshot" options are deprecated.

PECL mongodb 1.3.0

Added the "maxAwaitTimeMS" option.

PECL mongodb 1.2.0

Added the "allowPartialResults", "collation", "comment", "hint", "max", "maxScan", "maxTimeMS", "min", "returnKey", "showRecordId", and "snapshot" options.

Renamed the "partial" option to "allowPartialResults". For backwards compatibility, "partial" will still be read if "allowPartialResults" is not specified.

Removed the legacy "secondaryOk" option, which is obsolete. For queries using the legacy wire protocol OP_QUERY, the driver will set the secondaryOk bit as needed in accordance with the » Server Selection Specification.

PECL mongodb 1.1.0 | Added the "readConcern" option.

例

例1 MongoDB\Driver\Query::__construct() example

<?php
/* Select only documents authord by "bjori" with at least 100 views */
$filter = [
'author' => 'bjori',
'views' => [
'$gte' => 100,
],
];

$options = [
/* Only return the following fields in the matching documents */
'projection' => [
'title' => 1,
'article' => 1,
],
/* Return the documents in descending order of views */
'sort' => [
'views' => -1
],
];

$query = new MongoDB\Driver\Query($filter, $options);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$cursor = $manager->executeQuery('databaseName.collectionName', $query, $readPreference);

foreach($cursor as $document) {
var_dump($document);
}

?>

参考

  • MongoDB\Driver\Manager::executeQuery() - Execute a database query
  • MongoDB\Driver\Cursor


The MongoDB\Driver\BulkWrite class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\BulkWrite collects one or more write operations that should be sent to the server. After adding any number of insert, update, and delete operations, the collection may be executed via MongoDB\Driver\Manager::executeBulkWrite().

Write operations may either be ordered (default) or unordered. Ordered write operations are sent to the server, in the order provided, for serial execution. If a write fails, any remaining operations will be aborted. Unordered operations are sent to the server in an arbitrary order where they may be executed in parallel. Any errors that occur are reported after all operations have been attempted.

クラス概要

final class MongoDB\Driver\BulkWrite implements Countable {
/* メソッド */
public __construct(?array $options = null)
public count(): int
public delete(array|object $filter, ?array $deleteOptions = null): void
public insert(array|object $document): mixed
public update(array|object $filter, array|object $newObj, ?array $updateOptions = null): void
}

例

例1 Mixed write operations are grouped by type

Mixed write operations (i.e. inserts, updates, and deletes) will be assembled into typed write commands to be sent sequentially to the server.

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);
$bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
$bulk->insert(['_id' => 3, 'x' => 3]);
$bulk->delete(['x' => 1]);

?>

Will result in four write commands (i.e. roundtrips) being executed. Since the operations are ordered, the third insertion cannot be sent until the preceding update is executed.

例2 Ordered write operations causing an error

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->delete([]);
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 3, 'hello' => 'world']);
$bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
$bulk->insert(['_id' => 4, 'hello' => 'pluto']);
$bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
$bulk->insert(['_id' => 3]);
$bulk->insert(['_id' => 4]);
$bulk->insert(['_id' => 5]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

try {
$result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
$result = $e->getWriteResult();

// Check if the write concern could not be fulfilled
if ($writeConcernError = $result->getWriteConcernError()) {
printf("%s (%d): %s\n",
$writeConcernError->getMessage(),
$writeConcernError->getCode(),
var_export($writeConcernError->getInfo(), true)
);
}

// Check if any write operations did not complete at all
foreach ($result->getWriteErrors() as $writeError) {
printf("Operation#%d: %s (%d)\n",
$writeError->getIndex(),
$writeError->getMessage(),
$writeError->getCode()
);
}
} catch (MongoDB\Driver\Exception\Exception $e) {
printf("Other error: %s\n", $e->getMessage());
exit;
}

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Updated %d document(s)\n", $result->getModifiedCount());

?>

上の例の出力は以下となります。

Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated  2 document(s)

If the write concern could not be fullfilled, the example above would output something like:

waiting for replication timed out (64): array (
  'wtimeout' => true,
)
Operation#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
Inserted 4 document(s)
Updated  2 document(s)

If we execute the example above, but allow for unordered writes:

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
/* ... */

?>

上の例の出力は以下となります。

Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
Operation#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
Inserted 5 document(s)
Updated  2 document(s)

参考

  • MongoDB\Driver\Manager::executeBulkWrite()
  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\WriteConcernError
  • MongoDB\Driver\WriteError

目次

  • MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite
  • MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk
  • MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk
  • MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk
  • MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk


Create a new BulkWrite

  • ≪ MongoDB\Driver\BulkWrite
  • MongoDB\Driver\BulkWrite::count ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Create a new BulkWrite

MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite

説明

public MongoDB\Driver\BulkWrite::__construct(?array $options = null)

Constructs a new MongoDB\Driver\BulkWrite, which is a mutable object to which one or more write operations may be added. The write(s) may then be executed with MongoDB\Driver\Manager::executeBulkWrite().

パラメータ

options (array)

options
Option | Type | Description | Default
bypassDocumentValidation bool

If true, allows insert and update operations to circumvent document level validation.

This option is available in MongoDB 3.2+ and is ignored for older server versions, which do not support document level validation.

false
comment mixed

An arbitrary comment to help trace the operation through the database profiler, currentOp output, and logs.

This option is available in MongoDB 4.4+ and will result in an exception at execution time if specified for an older server version.

let array|object

Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. $$var).

This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.

ordered | bool | Ordered operations (true) are executed serially on the MongoDB server, while unordered operations (false) are sent to the server in an arbitrary order and may be executed in parallel. | true

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.14.0 | Added the "comment" and "let" options.
PECL mongodb 1.1.0 | Added the "bypassDocumentValidation" option.

例

例1 MongoDB\Driver\BulkWrite::__construct() example

<?php

$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
$bulk->delete([]);
$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);
$bulk->update(
['x' => 2],
['$set' => ['x' => 1]],
['limit' => 1, 'upsert' => false]
);
$bulk->delete(['x' => 1], ['limit' => 1]);
$bulk->update(
['_id' => 3],
['$set' => ['x' => 3]],
['limit' => 1, 'upsert' => true]
);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$writeConcern = new MongoDB\Driver\WriteConcern(1);

try {
$result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
$result = $e->getWriteResult();

// Check if the write concern could not be fulfilled
if ($writeConcernError = $result->getWriteConcernError()) {
printf("%s (%d): %s\n",
$writeConcernError->getMessage(),
$writeConcernError->getCode(),
var_export($writeConcernError->getInfo(), true)
);
}

// Check if any write operations did not complete at all
foreach ($result->getWriteErrors() as $writeError) {
printf("Operation#%d: %s (%d)\n",
$writeError->getIndex(),
$writeError->getMessage(),
$writeError->getCode()
);
}
} catch (MongoDB\Driver\Exception\Exception $e) {
printf("Other error: %s\n", $e->getMessage());
exit;
}

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Updated %d document(s)\n", $result->getModifiedCount());
printf("Upserted %d document(s)\n", $result->getUpsertedCount());
printf("Deleted %d document(s)\n", $result->getDeletedCount());

?>

上の例の出力は以下となります。

Inserted 2 document(s)
Updated  1 document(s)
Upserted 1 document(s)
Deleted  1 document(s)

参考

  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
  • MongoDB\Driver\WriteResult


Count number of write operations in the bulk

  • ≪ MongoDB\Driver\BulkWrite::__construct
  • MongoDB\Driver\BulkWrite::delete ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Count number of write operations in the bulk

MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk

説明

public MongoDB\Driver\BulkWrite::count(): int

Returns the number of write operations added to the MongoDB\Driver\BulkWrite object.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns number of write operations added to the MongoDB\Driver\BulkWrite object.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.2.0 | Returns the number of write operations added to the MongoDB\Driver\BulkWrite object. Earlier versions returned the expected number of client-to-server roundtrips required to execute all write operations.

例

例1 MongoDB\Driver\BulkWrite::count() example

<?php

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1, 'x' => 1]);
$bulk->insert(['_id' => 2, 'x' => 2]);
$bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
$bulk->delete(['x' => 1]);

var_dump(count($bulk));

?>

上の例の出力は以下となります。

int(4)


Add a delete operation to the bulk

  • ≪ MongoDB\Driver\BulkWrite::count
  • MongoDB\Driver\BulkWrite::insert ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Add a delete operation to the bulk

MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk

説明

public MongoDB\Driver\BulkWrite::delete(array|object $filter, ?array $deleteOptions = null): void

Adds a delete operation to the MongoDB\Driver\BulkWrite.

パラメータ

filter (array|object)

The » query predicate. An empty predicate will match all documents in the collection.

注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

deleteOptions

deleteOptions
Option | Type | Description | Default
collation array|object

» Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the "locale" field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document.

If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.

hint string|array|object

Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

This option is available in MongoDB 4.4+ and will result in an exception at execution time if specified for an older server version.

limit | bool | Delete all matching documents (false), or only the first matching document (true) | false

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.8.0 | Added the "hint" option.
PECL mongodb 1.2.0 | Added the "collation" option.

例

例1 MongoDB\Driver\BulkWrite::delete() example

<?php

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->delete(['x' => 1], ['limit' => 1]);
$bulk->delete(['x' => 2], ['limit' => 0]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$result = $manager->executeBulkWrite('db.collection', $bulk);

?>

参考

  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
  • MongoDB\Driver\WriteResult


Add an insert operation to the bulk

  • ≪ MongoDB\Driver\BulkWrite::delete
  • MongoDB\Driver\BulkWrite::update ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Add an insert operation to the bulk

MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk

説明

public MongoDB\Driver\BulkWrite::insert(array|object $document): mixed

Adds an insert operation to the MongoDB\Driver\BulkWrite.

パラメータ

document (array|object)

A document to insert.

戻り値

Returns the _id of the inserted document. If the document did not have an _id, the MongoDB\BSON\ObjectId generated for the insert will be returned.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | The _id of the inserted document is always returned. Previously, the method only returned a value if a MongoDB\BSON\ObjectId was generated.

例

例1 MongoDB\Driver\BulkWrite::insert() example

<?php

$bulk = new MongoDB\Driver\BulkWrite;

$document1 = ['title' => 'one'];
$document2 = ['_id' => 'custom ID', 'title' => 'two'];
$document3 = ['_id' => new MongoDB\BSON\ObjectId, 'title' => 'three'];

$_id1 = $bulk->insert($document1);
$_id2 = $bulk->insert($document2);
$_id3 = $bulk->insert($document3);

var_dump($_id1, $_id2, $_id3);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$result = $manager->executeBulkWrite('db.collection', $bulk);

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\BSON\ObjectId)#3 (1) {
  ["oid"]=>
  string(24) "54d51146bd21b91405401d92"
}
NULL
NULL

参考

  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
  • MongoDB\Driver\WriteResult
  • MongoDB\BSON\ObjectId
  • MongoDB\BSON\Persistable


Add an update operation to the bulk

  • ≪ MongoDB\Driver\BulkWrite::insert
  • MongoDB\Driver\Session ≫
  • PHP Manual
  • MongoDB\Driver\BulkWrite
  • Add an update operation to the bulk

MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk

説明

public MongoDB\Driver\BulkWrite::update(array|object $filter, array|object $newObj, ?array $updateOptions = null): void

Adds an update operation to the MongoDB\Driver\BulkWrite.

パラメータ

filter (array|object)

The » query predicate. An empty predicate will match all documents in the collection.

注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

newObj (array|object)

A document containing either update operators (e.g. $set), a replacement document (i.e. only field:value expressions), or an » aggregation pipeline.

updateOptions

updateOptions
Option | Type | Description | Default
arrayFilters array

An array of filter documents that determines which array elements to modify for an update operation on an array field. See » Specify arrayFilters for Array Update Operations in the MongoDB manual for more information.

This option is available in MongoDB 3.6+ and will result in an exception at execution time if specified for an older server version.

collation array|object

» Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the "locale" field is mandatory; all other collation fields are optional. For descriptions of the fields, see » Collation Document.

If the collation is unspecified but the collection has a default collation, the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operation, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

This option is available in MongoDB 3.4+ and will result in an exception at execution time if specified for an older server version.

hint string|array|object

Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

This option is available in MongoDB 4.2+ and will result in an exception at execution time if specified for an older server version.

multi | bool | Update only the first matching document if false, or all matching documents true. This option cannot be true if newObj is a replacement document. | false
upsert | bool | If filter does not match an existing document, insert a single document. The document will be created from newObj if it is a replacement document (i.e. no update operators); otherwise, the operators in newObj will be applied to filter to create the new document. | false

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Added the "hint" option.
PECL mongodb 1.6.0 | The newObj parameter now accepts an aggregation pipeline. This feature requires MongoDB 4.2+ and will result in an exception at execution time if specified for an older server version.
PECL mongodb 1.5.0 | Using the "arrayFilters" option will result in an exception at execution time if unsupported by the server. Previously, no exception would be thrown and the option may have been ignored.
PECL mongodb 1.4.0 | Added the "arrayFilters" option.
PECL mongodb 1.2.0 | Added the "collation" option.

例

例1 MongoDB\Driver\BulkWrite::update() example

<?php

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->update(
['x' => 2],
['$set' => ['y' => 3]],
['multi' => false, 'upsert' => false]
);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$result = $manager->executeBulkWrite('db.collection', $bulk);

?>

参考

  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
  • MongoDB\Driver\WriteResult


The MongoDB\Driver\Session class

(mongodb >=1.4.0)

はじめに

The MongoDB\Driver\Session class represents a client session and is returned by MongoDB\Driver\Manager::startSession(). Commands, queries, and write operations may then be associated the session.

クラス概要

final class MongoDB\Driver\Session {
/* 定数 */
const string TRANSACTION_NONE = none;
const string TRANSACTION_STARTING = starting;
const string TRANSACTION_IN_PROGRESS = in_progress;
const string TRANSACTION_COMMITTED = committed;
const string TRANSACTION_ABORTED = aborted;
/* メソッド */
final public abortTransaction(): void
final public advanceClusterTime(array|object $clusterTime): void
final public advanceOperationTime(MongoDB\BSON\TimestampInterface $operationTime): void
final public commitTransaction(): void
final private __construct()
final public endSession(): void
final public getClusterTime(): ?object
final public getLogicalSessionId(): object
final public getOperationTime(): ?MongoDB\BSON\Timestamp
final public getServer(): ?MongoDB\Driver\Server
final public getTransactionOptions(): ?array
final public getTransactionState(): string
final public isDirty(): bool
final public isInTransaction(): bool
final public startTransaction(?array $options = null): void
}

定義済み定数

MongoDB\Driver\Session::TRANSACTION_NONE

There is no transaction in progress.

MongoDB\Driver\Session::TRANSACTION_STARTING

A transaction has been started, but no operation has been sent to the server.

MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS

A transaction is in progress.

MongoDB\Driver\Session::TRANSACTION_COMMITTED

The transaction was committed.

MongoDB\Driver\Session::TRANSACTION_ABORTED

The transaction was aborted.

目次

  • MongoDB\Driver\Session::abortTransaction — Aborts a transaction
  • MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session
  • MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session
  • MongoDB\Driver\Session::commitTransaction — Commits a transaction
  • MongoDB\Driver\Session::__construct — Create a new Session (not used)
  • MongoDB\Driver\Session::endSession — Terminates a session
  • MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session
  • MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session
  • MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session
  • MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned
  • MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction
  • MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session
  • MongoDB\Driver\Session::isDirty — Returns whether the session has been marked as dirty
  • MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress
  • MongoDB\Driver\Session::startTransaction — Starts a transaction


Aborts a transaction

  • ≪ MongoDB\Driver\Session
  • MongoDB\Driver\Session::advanceClusterTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Aborts a transaction

MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Aborts a transaction

説明

final public MongoDB\Driver\Session::abortTransaction(): void

Terminates the multi-document transaction and rolls back any data changes made by the operations within the transaction. That is, the transaction ends without saving any of the changes made by the operations in the transaction.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be aborted (e.g. a transaction was not started).

参考

  • MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
  • MongoDB\Driver\Session::commitTransaction() - Commits a transaction
  • MongoDB\Driver\Session::startTransaction() - Starts a transaction


Advances the cluster time for this session

  • ≪ MongoDB\Driver\Session::abortTransaction
  • MongoDB\Driver\Session::advanceOperationTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Advances the cluster time for this session

MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session

説明

final public MongoDB\Driver\Session::advanceClusterTime(array|object $clusterTime): void

Advances the cluster time for this session. If the cluster time is less than or equal to the session's current cluster time, this function is a no-op.

By using this method in conjunction with MongoDB\Driver\Session::advanceOperationTime() to copy the cluster and operation times from another session, you can ensure that operations in this session are causally consistent with the last operation in the other session.

パラメータ

clusterTime

The cluster time is a document containing a logical timestamp and server signature. Typically, this value will be obtained by calling MongoDB\Driver\Session::getClusterTime() on another session object.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::advanceOperationTime() - Advances the operation time for this session
  • MongoDB\Driver\Session::getClusterTime() - Returns the cluster time for this session


Advances the operation time for this session

  • ≪ MongoDB\Driver\Session::advanceClusterTime
  • MongoDB\Driver\Session::commitTransaction ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Advances the operation time for this session

MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session

説明

final public MongoDB\Driver\Session::advanceOperationTime(MongoDB\BSON\TimestampInterface $operationTime): void

Advances the operation time for this session. If the operation time is less than or equal to the session's current operation time, this function is a no-op.

By using this method in conjunction with MongoDB\Driver\Session::advanceClusterTime() to copy the operation and cluster times from another session, you can ensure that operations in this session are causally consistent with the last operation in the other session.

パラメータ

operationTime

The operation time is a logical timestamp. Typically, this value will be obtained by calling MongoDB\Driver\Session::getOperationTime() on another session object.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::advanceClusterTime() - Advances the cluster time for this session
  • MongoDB\Driver\Session::getClusterTime() - Returns the cluster time for this session


Commits a transaction

  • ≪ MongoDB\Driver\Session::advanceOperationTime
  • MongoDB\Driver\Session::__construct ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Commits a transaction

MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Commits a transaction

説明

final public MongoDB\Driver\Session::commitTransaction(): void

Saves the changes made by the operations in the multi-document transaction and ends the transaction. Until the commit, none of the data changes made from within the transaction are visible outside the transaction.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\CommandException if the server could not commit the transaction (e.g. due to conflicts, network issues). In case the exception's MongoDB\Driver\Exception\CommandException::getResultDocument() has a "errorLabels" element, and this array contains a "TransientTransactionError" or "UnUnknownTransactionCommitResult" value, it is safe to re-try the whole transaction. In newer versions of the extension, MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() should be used to test for this situation instead.
  • Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be commited (e.g. a transaction was not started).

参考

  • MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
  • MongoDB\Driver\Session::abortTransaction() - Aborts a transaction
  • MongoDB\Driver\Session::startTransaction() - Starts a transaction
  • MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() - Returns whether an error label is associated with an exception


Create a new Session (not used)

  • ≪ MongoDB\Driver\Session::commitTransaction
  • MongoDB\Driver\Session::endSession ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Create a new Session (not used)

MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Create a new Session (not used)

説明

final private MongoDB\Driver\Session::__construct()

MongoDB\Driver\Session objects are returned by MongoDB\Driver\Manager::startSession() and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client


Terminates a session

  • ≪ MongoDB\Driver\Session::__construct
  • MongoDB\Driver\Session::getClusterTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Terminates a session

MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Terminates a session

説明

final public MongoDB\Driver\Session::endSession(): void

This method closes an existing session. If a transaction was associated with this session, the transaction will be aborted. After calling this method, applications should not invoke other methods on the session.

注意: Sessions are also closed during garbage collection. It should not be necessary to call this method under normal circumstances.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
  • MongoDB\Driver\Session::abortTransaction() - Aborts a transaction
  • MongoDB\Driver\Session::commitTransaction() - Commits a transaction
  • MongoDB\Driver\Session::startTransaction() - Starts a transaction


Returns the cluster time for this session

  • ≪ MongoDB\Driver\Session::endSession
  • MongoDB\Driver\Session::getLogicalSessionId ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the cluster time for this session

MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session

説明

final public MongoDB\Driver\Session::getClusterTime(): ?object

Returns the cluster time for this session. If the session has not been used for any operation and MongoDB\Driver\Session::advanceClusterTime() has not been called, the cluster time will be null.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the cluster time for this session, or null if the session has no cluster time.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::advanceClusterTime() - Advances the cluster time for this session


Returns the logical session ID for this session

  • ≪ MongoDB\Driver\Session::getClusterTime
  • MongoDB\Driver\Session::getOperationTime ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the logical session ID for this session

MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session

説明

final public MongoDB\Driver\Session::getLogicalSessionId(): object

Returns the logical session ID for this session, which may be used to identify this session's operations on the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the logical session ID for this session.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the operation time for this session

  • ≪ MongoDB\Driver\Session::getLogicalSessionId
  • MongoDB\Driver\Session::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the operation time for this session

MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session

説明

final public MongoDB\Driver\Session::getOperationTime(): ?MongoDB\BSON\Timestamp

Returns the operation time for this session. If the session has not been used for any operation and MongoDB\Driver\Session::advanceOperationTime() has not been called, the operation time will be null

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the operation time for this session, or null if the session has no operation time.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::advanceOperationTime() - Advances the operation time for this session


Returns the server to which this session is pinned

  • ≪ MongoDB\Driver\Session::getOperationTime
  • MongoDB\Driver\Session::getTransactionOptions ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the server to which this session is pinned

MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned

説明

final public MongoDB\Driver\Session::getServer(): ?MongoDB\Driver\Server

Returns the MongoDB\Driver\Server to which this session is pinned. If the session is not pinned to a server, null will be returned.

Session pinning is primarily used for sharded transactions, as all commands within a sharded transaction must be sent to the same mongos instance. This method is intended to be used by libraries built atop the extension to allow use of a pinned server instead of invoking server selection.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server to which this session is pinned, or null if the session is not pinned to any server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns options for the currently running transaction

  • ≪ MongoDB\Driver\Session::getServer
  • MongoDB\Driver\Session::getTransactionState ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns options for the currently running transaction

MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction

説明

final public MongoDB\Driver\Session::getTransactionOptions(): ?array

Returns options for the currently running transaction.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a array containing current transaction options, or null if no transaction is running.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::getTransactionState() - Returns the current transaction state for this session


Returns the current transaction state for this session

  • ≪ MongoDB\Driver\Session::getTransactionOptions
  • MongoDB\Driver\Session::isDirty ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns the current transaction state for this session

MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session

説明

final public MongoDB\Driver\Session::getTransactionState(): string

Returns the transaction state for this session.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current transaction state for this session.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::isInTransaction() - Returns whether a multi-document transaction is in progress
  • MongoDB\Driver\Session::getTransactionOptions() - Returns options for the currently running transaction


Returns whether the session has been marked as dirty

  • ≪ MongoDB\Driver\Session::getTransactionState
  • MongoDB\Driver\Session::isInTransaction ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns whether the session has been marked as dirty

MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Returns whether the session has been marked as dirty

説明

final public MongoDB\Driver\Session::isDirty(): bool

Returns whether the session has been marked as dirty (i.e. it has been used with a command that encountered a network error).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns whether the session has been marked as dirty.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns whether a multi-document transaction is in progress

  • ≪ MongoDB\Driver\Session::isDirty
  • MongoDB\Driver\Session::startTransaction ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Returns whether a multi-document transaction is in progress

MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress

説明

final public MongoDB\Driver\Session::isInTransaction(): bool

Returns whether a multi-document transaction is currently in progress for this session. A transaction is considered "in progress" if it has been started but has not been committed or aborted.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if a transaction is currently in progress for this session, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Session::getTransactionState() - Returns the current transaction state for this session


Starts a transaction

  • ≪ MongoDB\Driver\Session::isInTransaction
  • MongoDB\Driver\ClientEncryption ≫
  • PHP Manual
  • MongoDB\Driver\Session
  • Starts a transaction

MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Starts a transaction

説明

final public MongoDB\Driver\Session::startTransaction(?array $options = null): void

Starts a multi-document transaction associated with the session. At any given time, you can have at most one open transaction for a session. After starting a transaction, the session object must be passed to each operation via the "session" option (e.g. MongoDB\Driver\Manager::executeBulkWrite()) in order to associate that operation with the transaction.

Transactions can be committed through MongoDB\Driver\Session::commitTransaction(), and aborted with MongoDB\Driver\Session::abortTransaction(). Transactions are also automatically aborted when the session is closed from garbage collection or by explicitly calling MongoDB\Driver\Session::endSession().

パラメータ

options

Options can be passed as argument to this method. Each element in this options array overrides the corresponding option from the "defaultTransactionOptions" option, if set when starting the session with MongoDB\Driver\Manager::startSession().

options
Option Type Description
maxCommitTimeMS integer

The maximum amount of time in milliseconds to allow a single commitTransaction command to run.

If specified, maxCommitTimeMS must be a signed 32-bit integer greater than or equal to zero.

readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\CommandException if the transaction could not be started because of a server-side problem (e.g. a lock could not be obtained).
  • Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be started (e.g. a transaction was already started).

変更履歴

バージョン | 説明
PECL mongodb 1.6.0 | The "maxCommitTimeMS" option was added.

参考

  • MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
  • MongoDB\Driver\Session::commitTransaction() - Commits a transaction
  • MongoDB\Driver\Session::abortTransaction() - Aborts a transaction


The MongoDB\Driver\ClientEncryption class

(mongodb >=1.7.0)

はじめに

The MongoDB\Driver\ClientEncryption class handles creation of data keys for client-side encryption, as well as manually encrypting and decrypting values.

クラス概要

final class MongoDB\Driver\ClientEncryption {
/* 定数 */
const string AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC = AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic;
const string AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM = AEAD_AES_256_CBC_HMAC_SHA_512-Random;
const string ALGORITHM_INDEXED = Indexed;
const string ALGORITHM_UNINDEXED = Unindexed;
const string ALGORITHM_RANGE = Range;
const string ALGORITHM_RANGE_PREVIEW = RangePreview;
const string QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
const string QUERY_TYPE_RANGE_PREVIEW = rangePreview;
/* メソッド */
final public addKeyAltName(MongoDB\BSON\Binary $keyId, string $keyAltName): ?object
final public __construct(array $options)
final public createDataKey(string $kmsProvider, ?array $options = null): MongoDB\BSON\Binary
final public decrypt(MongoDB\BSON\Binary $value): mixed
final public deleteKey(MongoDB\BSON\Binary $keyId): object
final public encrypt(mixed $value, ?array $options = null): MongoDB\BSON\Binary
final public encryptExpression(array|object $expr, ?array $options = null): object
final public getKey(MongoDB\BSON\Binary $keyId): ?object
final public getKeyByAltName(string $keyAltName): ?object
final public getKeys(): MongoDB\Driver\Cursor
final public removeKeyAltName(MongoDB\BSON\Binary $keyId, string $keyAltName): ?object
final public rewrapManyDataKey(array|object $filter, ?array $options = null): object
}

定義済み定数

MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC

Specifies an algorithm for » deterministic encryption, which is suitable for querying.

MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM

Specifies an algorithm for » randomized encryption

MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED

Specifies an algorithm for an indexed, encrypted payload, which can be used with queryable encryption.

To insert or query with an indexed, encrypted payload, the MongoDB\Driver\Manager must be configured with the "autoEncryption" driver option. The "bypassQueryAnalysis" auto encryption option may be true. The "bypassAutoEncryption" auto encryption option must be false.

MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED

Specifies an algorithm for an unindexed, encrypted payload.

MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE

Specifies an algorithm for a range encrypted payload, which can be used with queryable encryption.

To query with a range encrypted payload, the MongoDB\Driver\Manager must be configured with the "autoEncryption" driver option. The "bypassQueryAnalysis" auto encryption option may be true. The "bypassAutoEncryption" auto encryption option must be false.

注意:

The range algorithm is experimental only. It is not intended for public use.

The extension does not yet support range queries for Decimal128 BSON field types.

MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW

This constant is deprecated and will be removed in a future major version.

MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY

Specifies an equality query type, which is used in conjunction with MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED.

MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE

Specifies a range query type, which is used in conjunction with MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE.

MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW

This constant is deprecated and will be removed in a future major version.

変更履歴

バージョン | 説明
PECL mongodb 1.20.0

Added MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE and MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE.

Deprecated MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW and MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW.

PECL mongodb 1.16.0 | Added MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW and MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW.
PECL mongodb 1.14.0 | Added MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED, MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED, and MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY.

参考

  • MongoDB\Driver\Manager::createClientEncryption()

目次

  • MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document
  • MongoDB\Driver\ClientEncryption::__construct — Create a new ClientEncryption object
  • MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document
  • MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value
  • MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document
  • MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value
  • MongoDB\Driver\ClientEncryption::encryptExpression — Encrypts a match or aggregate expression
  • MongoDB\Driver\ClientEncryption::getKey — Gets a key document
  • MongoDB\Driver\ClientEncryption::getKeyByAltName — Gets a key document by an alternate name
  • MongoDB\Driver\ClientEncryption::getKeys — Gets all key documents
  • MongoDB\Driver\ClientEncryption::removeKeyAltName — Removes an alternate name from a key document
  • MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Rewraps data keys


Adds an alternate name to a key document

  • ≪ MongoDB\Driver\ClientEncryption
  • MongoDB\Driver\ClientEncryption::__construct ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Adds an alternate name to a key document

MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document

説明

final public MongoDB\Driver\ClientEncryption::addKeyAltName(MongoDB\BSON\Binary $keyId, string $keyAltName): ?object

Adds keyAltName to the set of alternate names for the key document with the given UUID keyId.

パラメータ

keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

keyAltName

Alternate name to add to the key document.

戻り値

Returns the previous version of the key document, or null if no document matched.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

参考

  • MongoDB\Driver\ClientEncryption::getKeyByAltName() - Gets a key document by an alternate name
  • MongoDB\Driver\ClientEncryption::removeKeyAltName() - Removes an alternate name from a key document


Create a new ClientEncryption object

  • ≪ MongoDB\Driver\ClientEncryption::addKeyAltName
  • MongoDB\Driver\ClientEncryption::createDataKey ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Create a new ClientEncryption object

MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Create a new ClientEncryption object

説明

final public MongoDB\Driver\ClientEncryption::__construct(array $options)

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

パラメータ

options

options
Option | Type | Description
keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries. This option is required (unlike with MongoDB\Driver\Manager::createClientEncryption()).
keyVaultNamespace | string | A fully qualified namespace (e.g. "databaseName.collectionName") denoting the collection that contains all data keys used for encryption and decryption.
kmsProviders array

A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include "aws", "azure", "gcp", "kmip", and "local" and at least one must be specified.

If an empty document is specified for "aws", "azure", or "gcp", the driver will attempt to configure the provider using » Automatic Credentials.

The format for "aws" is as follows:

aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>,
    sessionToken: <optional string>
}

The format for "azure" is as follows:

azure: {
    tenantId: <string>,
    clientId: <string>,
    clientSecret: <string>,
    identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com"
}

The format for "gcp" is as follows:

gcp: {
    email: <string>,
    privateKey: <base64 string>|<MongoDB\BSON\Binary>,
    endpoint: <optional string> // Defaults to "oauth2.googleapis.com"
}

The format for "kmip" is as follows:

kmip: {
    endpoint: <string>
}

The format for "local" is as follows:

local: {
    // 96-byte master key used to encrypt/decrypt data keys
    key: <base64 string>|<MongoDB\BSON\Binary>
}
tlsOptions array

A document containing the TLS configuration for one or more KMS providers. Supported providers include "aws", "azure", "gcp", and "kmip". All providers support the following options:

<provider>: {
    tlsCaFile: <optional string>,
    tlsCertificateKeyFile: <optional string>,
    tlsCertificateKeyFilePassword: <optional string>,
    tlsDisableOCSPEndpointCheck: <optional bool>
}

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

変更履歴

バージョン 説明
PECL mongodb 1.16.0

The AWS KMS provider for client-side encryption now accepts a "sessionToken" option, which can be used to authenticate with temporary AWS credentials.

Added "tlsDisableOCSPEndpointCheck" to the "tlsOptions" option.

If an empty document is specified for the "azure" or "gcp" KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

PECL mongodb 1.15.0

If an empty document is specified for the "aws" KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

参考

  • MongoDB\Driver\Manager::createClientEncryption() - Create a new ClientEncryption object
  • » Explicit (Manual) Client-Side Field Level Encryption in the MongoDB manual


Creates a key document

  • ≪ MongoDB\Driver\ClientEncryption::__construct
  • MongoDB\Driver\ClientEncryption::decrypt ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Creates a key document

MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document

説明

final public MongoDB\Driver\ClientEncryption::createDataKey(string $kmsProvider, ?array $options = null): MongoDB\BSON\Binary

Creates a new key document and inserts it into the key vault collection.

パラメータ

kmsProvider

The KMS provider (e.g. "local", "aws") that will be used to encrypt the new data key.

options

Data key options
Option Type Description
masterKey array

The masterKey document identifies a KMS-specific key used to encrypt the new data key. This option is required unless kmsProvider is "local".

"aws" provider options
Option | Type | Description
region | string | Required.
key | string | Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).
endpoint | string | Optional. An alternate host identifier to send KMS requests to. May include port number.

"azure" provider options
Option | Type | Description
keyVaultEndpoint | string | Required. Host with optional port (e.g. "example.vault.azure.net").
keyName | string | Required.
keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.

"gcp" provider options
Option | Type | Description
projectId | string | Required.
location | string | Required.
keyRing | string | Required.
keyName | string | Required.
keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
endpoint | string | Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".

"kmip" provider options
Option | Type | Description
keyId | string | Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.
endpoint | string | Optional. Host with optional port.

keyAltNames array

An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by _id.

keyMaterial MongoDB\BSON\Binary

An optional 96-byte value to use as custom key material for the data key being created. If keyMaterial is given, the custom key material is used for encrypting and decrypting data. Otherwise, the key material for the new data key is generated from a cryptographically secure random device.

戻り値

Returns the identifier of the new key as a MongoDB\BSON\Binary object with subtype 4 (UUID).

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Added the "keyMaterial" option.
PECL mongodb 1.10.0 | Azure and GCP are now supported as KMS providers for client-side encryption.


Decrypt a value

  • ≪ MongoDB\Driver\ClientEncryption::createDataKey
  • MongoDB\Driver\ClientEncryption::deleteKey ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Decrypt a value

MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value

説明

final public MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary $value): mixed

Decrypts the value.

パラメータ

value

A MongoDB\BSON\Binary instance with subtype 6 containing the encrypted value.

戻り値

Returns the decrypted value as it was passed to MongoDB\Driver\ClientEncryption::encrypt().

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while decrypting the value

参考

  • MongoDB\Driver\ClientEncryption::encrypt() - Encrypt a value


Deletes a key document

  • ≪ MongoDB\Driver\ClientEncryption::decrypt
  • MongoDB\Driver\ClientEncryption::encrypt ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Deletes a key document

MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document

説明

final public MongoDB\Driver\ClientEncryption::deleteKey(MongoDB\BSON\Binary $keyId): object

Removes the key document with the given UUID keyId from the key vault collection.

パラメータ

keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

戻り値

Returns the result of the internal deleteOne operation on the key vault collection.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.


Encrypt a value

  • ≪ MongoDB\Driver\ClientEncryption::deleteKey
  • MongoDB\Driver\ClientEncryption::encryptExpression ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Encrypt a value

MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value

説明

final public MongoDB\Driver\ClientEncryption::encrypt(mixed $value, ?array $options = null): MongoDB\BSON\Binary

Encrypts the value.

パラメータ

value

The value to be encrypted. Any value that can be inserted into MongoDB can be encrypted using this method.

options

Encryption options
Option Type Description
algorithm string

The encryption algorithm to be used. This option is required. Specify one of the following ClientEncryption constants:

  • MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC
  • MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM
  • MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED
  • MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED
  • MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE
contentionFactor int

The contention factor for evaluating queries with indexed, encrypted payloads.

This option only applies and may only be specified when algorithm is MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED or MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE.

keyAltName string

Identifies a key vault collection document by keyAltName. This option is mutually exclusive with keyId and exactly one is required.

keyId MongoDB\BSON\Binary

Identifies a data key by _id. The value is a UUID (binary subtype 4). This option is mutually exclusive with keyAltName and exactly one is required.

queryType string

The query type for evaluating queries with indexed, encrypted payloads. Specify one of the following ClientEncryption constants:

  • MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY
  • MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW

This option only applies and may only be specified when algorithm is MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED or MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE.

rangeOpts array

Index options for a queryable encryption field supporting "range" queries. The options below must match the values set in the encryptedFields of the target collection. For double and decimal128 BSON field types, min, max, and precision must all be set, or all be unset.

Range index options
Option | Type | Description
min | mixed | Required if precision is set. The minimum BSON value of the range.
max | mixed | Required if precision is set. The maximum BSON value of the range.
sparsity | int | Required. Positive 64-bit integer.
precision | int | Optional. Positive 32-bit integer specifying precision to use for explicit encryption. May only be set for double or decimal128 BSON field types.
trimFactor | int | Required. Positive 32-bit integer.

戻り値

Returns the encrypted value as MongoDB\BSON\Binary object with subtype 6.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the value

変更履歴

バージョン | 説明
PECL mongodb 1.14.0 | Added the "contentionFactor" and "queryType" options.

参考

  • MongoDB\Driver\ClientEncryption::decrypt() - Decrypt a value


Encrypts a match or aggregate expression

  • ≪ MongoDB\Driver\ClientEncryption::encrypt
  • MongoDB\Driver\ClientEncryption::getKey ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Encrypts a match or aggregate expression

MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Encrypts a match or aggregate expression

説明

final public MongoDB\Driver\ClientEncryption::encryptExpression(array|object $expr, ?array $options = null): object

Encrypts a match or aggregate expression to query a range index.

To query with a range encrypted payload, the MongoDB\Driver\Manager must be configured with the "autoEncryption" driver option. The "bypassQueryAnalysis" auto encryption option may be true. The "bypassAutoEncryption" auto encryption option must be false.

注意:

The range algorithm is experimental only. It is not intended for public use.

The extension does not yet support range queries for Decimal128 BSON field types.

パラメータ

expr

The match or aggregate expression to be encrypted. Expressions must use at least one of the $gt, $gte, $lt, or $lte operators. A top-level $and operator is required, even if only a single comparison operator is used.

An example of a supported match expression (applies to queries and the $match aggregation stage) is as follows:

[
    '$and' => [
        [ '<field>' => [ '$gt'  => '<value1>' ] ],
        [ '<field>' => [ '$lte' => '<value2>' ] ],
    ],
]

An example of a supported aggregate expression is as follows:

[
    '$and' => [
        [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
        [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
    ],
]
options

Encryption options
Option Type Description
algorithm string

The encryption algorithm to be used. This option is required. Specify one of the following ClientEncryption constants:

  • MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC
  • MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM
  • MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED
  • MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED
  • MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE
contentionFactor int

The contention factor for evaluating queries with indexed, encrypted payloads.

This option only applies and may only be specified when algorithm is MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED or MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE.

keyAltName string

Identifies a key vault collection document by keyAltName. This option is mutually exclusive with keyId and exactly one is required.

keyId MongoDB\BSON\Binary

Identifies a data key by _id. The value is a UUID (binary subtype 4). This option is mutually exclusive with keyAltName and exactly one is required.

queryType string

The query type for evaluating queries with indexed, encrypted payloads. Specify one of the following ClientEncryption constants:

  • MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY
  • MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW

This option only applies and may only be specified when algorithm is MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED or MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE.

rangeOpts array

Index options for a queryable encryption field supporting "range" queries. The options below must match the values set in the encryptedFields of the target collection. For double and decimal128 BSON field types, min, max, and precision must all be set, or all be unset.

Range index options
Option | Type | Description
min | mixed | Required if precision is set. The minimum BSON value of the range.
max | mixed | Required if precision is set. The maximum BSON value of the range.
sparsity | int | Required. Positive 64-bit integer.
precision | int | Optional. Positive 32-bit integer specifying precision to use for explicit encryption. May only be set for double or decimal128 BSON field types.
trimFactor | int | Required. Positive 32-bit integer.

戻り値

Returns the encrypted expression as an object.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the expression

参考

  • MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager


Gets a key document

  • ≪ MongoDB\Driver\ClientEncryption::encryptExpression
  • MongoDB\Driver\ClientEncryption::getKeyByAltName ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Gets a key document

MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Gets a key document

説明

final public MongoDB\Driver\ClientEncryption::getKey(MongoDB\BSON\Binary $keyId): ?object

Finds a single key document in the key vault collection with the given UUID keyId.

パラメータ

keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

戻り値

Returns the key document, or null if no document matched.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.


Gets a key document by an alternate name

  • ≪ MongoDB\Driver\ClientEncryption::getKey
  • MongoDB\Driver\ClientEncryption::getKeys ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Gets a key document by an alternate name

MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Gets a key document by an alternate name

説明

final public MongoDB\Driver\ClientEncryption::getKeyByAltName(string $keyAltName): ?object

Finds a single key document in the key vault collection with the given alternate name keyAltName.

パラメータ

keyAltName

Alternate name for the key document.

戻り値

Returns the key document, or null if no document matched.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

参考

  • MongoDB\Driver\ClientEncryption::addKeyAltName() - Adds an alternate name to a key document
  • MongoDB\Driver\ClientEncryption::removeKeyAltName() - Removes an alternate name from a key document


Gets all key documents

  • ≪ MongoDB\Driver\ClientEncryption::getKeyByAltName
  • MongoDB\Driver\ClientEncryption::removeKeyAltName ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Gets all key documents

MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Gets all key documents

説明

final public MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Finds all key documents in the key vault collection.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.


Removes an alternate name from a key document

  • ≪ MongoDB\Driver\ClientEncryption::getKeys
  • MongoDB\Driver\ClientEncryption::rewrapManyDataKey ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Removes an alternate name from a key document

MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Removes an alternate name from a key document

説明

final public MongoDB\Driver\ClientEncryption::removeKeyAltName(MongoDB\BSON\Binary $keyId, string $keyAltName): ?object

Removes keyAltName from the set of alternate names for the key document with the given UUID keyId.

パラメータ

keyId

A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

keyAltName

Alternate name to remove from the key document.

戻り値

Returns the previous version of the key document, or null if no document matched.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

参考

  • MongoDB\Driver\ClientEncryption::addKeyAltName() - Adds an alternate name to a key document
  • MongoDB\Driver\ClientEncryption::getKeyByAltName() - Gets a key document by an alternate name


Rewraps data keys

  • ≪ MongoDB\Driver\ClientEncryption::removeKeyAltName
  • MongoDB\Driver\ServerApi ≫
  • PHP Manual
  • MongoDB\Driver\ClientEncryption
  • Rewraps data keys

MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Rewraps data keys

説明

final public MongoDB\Driver\ClientEncryption::rewrapManyDataKey(array|object $filter, ?array $options = null): object

Rewraps (i.e. decrypts and re-encrypts) zero or more data keys in the key vault collection that match the given filter.

If the "provider" option is not specified, matching data keys will be rewrapped with their current KMS provider. Otherwise, matching data keys will be re-encrypted according to the specified "provider" and "masterKey" options.

パラメータ

filter (array|object)

The » query predicate. An empty predicate will match all documents in the collection.

注意: When evaluating query criteria, MongoDB compares types and values according to its own » comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class (e.g. use MongoDB\BSON\ObjectId to match an » ObjectId).

options

RewrapManyDataKey options
Option Type Description
provider string

The KMS provider (e.g. "local", "aws") that will be used to re-encrypt the matched data keys.

If a KMS provider is not specified, matched data keys will be re-encrypted with their current KMS provider.

masterKey array

The masterKey identifies a KMS-specific key used to encrypt the new data key. This option should not be specified without the "provider" option. This option is required if "provider" is specified and not "local".

"aws" provider options
Option | Type | Description
region | string | Required.
key | string | Required. The Amazon Resource Name (ARN) to the AWS customer master key (CMK).
endpoint | string | Optional. An alternate host identifier to send KMS requests to. May include port number.

"azure" provider options
Option | Type | Description
keyVaultEndpoint | string | Required. Host with optional port (e.g. "example.vault.azure.net").
keyName | string | Required.
keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.

"gcp" provider options
Option | Type | Description
projectId | string | Required.
location | string | Required.
keyRing | string | Required.
keyName | string | Required.
keyVersion | string | Optional. A specific version of the named key. Defaults to using the key's primary version.
endpoint | string | Optional. Host with optional port. Defaults to "cloudkms.googleapis.com".

"kmip" provider options
Option | Type | Description
keyId | string | Optional. Unique identifier to a 96-byte KMIP secret data managed object. If unspecified, the driver creates a random 96-byte KMIP secret data managed object.
endpoint | string | Optional. Host with optional port.

戻り値

Returns an object, which will have an optional bulkWriteResult property containing the result of the internal bulkWrite operation as an object. If no data keys matched the filter or the write was unacknowledged, the bulkWriteResult property will be null.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while decrypting or re-encrypting a data key.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.


The MongoDB\Driver\ServerApi class

(mongodb >=1.10.0)

はじめに

クラス概要

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* 定数 */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* メソッド */
final public bsonSerialize(): stdClass
final public __construct(string $version, ?bool $strict = null, ?bool $deprecationErrors = null)
final public serialize(): string
final public unserialize(string $data): void
}

定義済み定数

MongoDB\Driver\ServerApi::V1

Server API version 1.

例

例1 Declare an API version on a manager

<?php

use MongoDB\Driver\Manager;
use MongoDB\Driver\ServerApi;

$v1 = new ServerApi(ServerApi::v1);
$manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

$command = new MongoDB\Driver\Command(['buildInfo' => 1]);

try {
$cursor = $manager->executeCommand('admin', $command);
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}

/* The buildInfo command returns a single result document, so we need to access
* the first result in the cursor. */
$buildInfo = $cursor->toArray()[0];

echo $buildInfo->version, "\n";

?>

上の例の出力は以下となります。

4.9.0-alpha7-49-gb968ca0

例2 Declare a strict API version on a manager

The following example sets the strict flag, which tells the server to reject any command that is not part of the declared API version. This results in an error when running the buildInfo command.

<?php

use MongoDB\Driver\Manager;
use MongoDB\Driver\ServerApi;

$v1 = new ServerApi(ServerApi::v1, true);
$manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

$command = new MongoDB\Driver\Command(['buildInfo' => 1]);

try {
$cursor = $manager->executeCommand('admin', $command);
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}

/* The buildInfo command returns a single result document, so we need to access
* the first result in the cursor. */
$buildInfo = $cursor->toArray()[0];

echo $buildInfo->version, "\n";

?>

上の例の出力は以下となります。

Provided apiStrict:true, but the command buildInfo is not in API Version 1

目次

  • MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance
  • MongoDB\Driver\ServerApi::serialize — Serialize a ServerApi
  • MongoDB\Driver\ServerApi::unserialize — Unserialize a ServerApi


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\ServerApi
  • MongoDB\Driver\ServerApi::__construct ≫
  • PHP Manual
  • MongoDB\Driver\ServerApi
  • Returns an object for BSON serialization

MongoDB\Driver\ServerApi::bsonSerialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an object for serializing the ServerApi as BSON.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON


Create a new ServerApi instance

  • ≪ MongoDB\Driver\ServerApi::bsonSerialize
  • MongoDB\Driver\ServerApi::serialize ≫
  • PHP Manual
  • MongoDB\Driver\ServerApi
  • Create a new ServerApi instance

MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance

説明

final public MongoDB\Driver\ServerApi::__construct(string $version, ?bool $strict = null, ?bool $deprecationErrors = null)

Creates a new MongoDB\Driver\ServerApi instance used to declare an API version when creating a MongoDB\Driver\Manager.

パラメータ

version

A server API version.

Supported API versions are provided as constants in MongoDB\Driver\ServerApi. The only supported API version is MongoDB\Driver\ServerApi::V1.

strict

If the strict parameter is set to true, the server will yield an error for any command that is not part of the specified API version. If no value is provided, the server default value (false) is used.

deprecationErrors

If the deprecationErrors parameter is set to true, the server will yield an error when using a command that is deprecated in the specified API version. If no value is provided, the server default value (false) is used.


Serialize a ServerApi

  • ≪ MongoDB\Driver\ServerApi::__construct
  • MongoDB\Driver\ServerApi::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\ServerApi
  • Serialize a ServerApi

MongoDB\Driver\ServerApi::serialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::serialize — Serialize a ServerApi

説明

final public MongoDB\Driver\ServerApi::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\Driver\ServerApi.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\ServerApi::unserialize() - Unserialize a ServerApi
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Unserialize a ServerApi

  • ≪ MongoDB\Driver\ServerApi::serialize
  • MongoDB\Driver\WriteConcern ≫
  • PHP Manual
  • MongoDB\Driver\ServerApi
  • Unserialize a ServerApi

MongoDB\Driver\ServerApi::unserialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::unserialize — Unserialize a ServerApi

説明

final public MongoDB\Driver\ServerApi::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\Driver\ServerApi.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\ServerApi::serialize() - Serialize a ServerApi
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\Driver\WriteConcern class

(mongodb >=1.0.0)

はじめに

MongoDB\Driver\WriteConcern describes the level of acknowledgement requested from MongoDB for write operations to a standalone mongod or to replica sets or to sharded clusters. In sharded clusters, mongos instances will pass the write concern on to the shards.

クラス概要

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* 定数 */
const string MAJORITY = "majority";
/* メソッド */
final public bsonSerialize(): stdClass
final public __construct(string|int $w, ?int $wtimeout = null, ?bool $journal = null)
final public getJournal(): ?bool
final public getW(): string|int|null
final public getWtimeout(): int
final public isDefault(): bool
final public serialize(): string
final public unserialize(string $data): void
}

定義済み定数

MongoDB\Driver\WriteConcern::MAJORITY

Majority of all the members in the set; arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.2.0 | Implements MongoDB\BSON\Serializable.

目次

  • MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern
  • MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option
  • MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option
  • MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option
  • MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern
  • MongoDB\Driver\WriteConcern::serialize — Serialize a WriteConcern
  • MongoDB\Driver\WriteConcern::unserialize — Unserialize a WriteConcern


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\WriteConcern
  • MongoDB\Driver\WriteConcern::__construct ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns an object for BSON serialization

MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an object for serializing the WriteConcern as BSON.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcern::bsonSerialize() with majority write concern

<?php

$wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
var_dump($wc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($wc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (1) {
  ["w"]=>
  string(8) "majority"
}

{ "w" : "majority" }

例2 MongoDB\Driver\WriteConcern::bsonSerialize() with wtimeout and journal

<?php

$wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
var_dump($wc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($wc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (3) {
  ["w"]=>
  int(2)
  ["j"]=>
  bool(true)
  ["wtimeout"]=>
  int(1000)
}

{ "w" : 2, "j" : true, "wtimeout" : 1000 }

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • » Write Concern reference


Create a new WriteConcern

  • ≪ MongoDB\Driver\WriteConcern::bsonSerialize
  • MongoDB\Driver\WriteConcern::getJournal ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Create a new WriteConcern

MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern

説明

final public MongoDB\Driver\WriteConcern::__construct(string|int $w, ?int $wtimeout = null, ?bool $journal = null)

Constructs a new MongoDB\Driver\WriteConcern, which is an immutable value object.

パラメータ

w

Write concern
Value | Description
1 | Requests acknowledgement that the write operation has propagated to the standalone mongod or the primary in a replica set. This is the default write concern for MongoDB.
0 | Requests no acknowledgment of the write operation. However, this may return information about socket exceptions and networking errors to the application.
<integer greater than 1> | Numbers greater than 1 are valid only for replica sets to request acknowledgement from specified number of members, including the primary.
MongoDB\Driver\WriteConcern::MAJORITY

Requests acknowledgment that write operations have propagated to the majority of voting nodes, including the primary, and have been written to the on-disk journal for these nodes.

Prior to MongoDB 3.0, this refers to the majority of replica set members (not just voting nodes).

string | A string value is interpereted as a tag set. Requests acknowledgement that the write operations have propagated to a replica set member with the specified tag.

wtimeout

How long to wait (in milliseconds) for secondaries before failing.

wtimeout causes write operations to return with an error (WriteConcernError) after the specified limit, even if the required write concern will eventually succeed. When these write operations return, MongoDB does not undo successful data modifications performed before the write concern exceeded the wtimeout time limit.

If specified, wtimeout must be a signed 64-bit integer greater than or equal to zero.

Write concern timeout
Value | Description
0 | Block indefinitely. This is the default.
<integer greater than 0> | Milliseconds to wait until returning.

journal

Wait until mongod has applied the write to the journal.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if w is invalid or wtimeout is either negative or greater than the bounds of a signed 32-bit integer.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | The wTimeout parameter now accepts 64-bit values.

例

例1 MongoDB\Driver\WriteConcern::__construct() example

<?php

/* Request write acknowledgement from the majority of the replica set nodes */
$wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 500);

/* Request write acknowledgement from a node configured with the "MultipleDC" tag */
$wc = new MongoDB\Driver\WriteConcern("MultipleDC", 500);

?>

参考

  • » Write Concern reference


Returns the WriteConcern's "journal" option

  • ≪ MongoDB\Driver\WriteConcern::__construct
  • MongoDB\Driver\WriteConcern::getW ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns the WriteConcern's "journal" option

MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option

説明

final public MongoDB\Driver\WriteConcern::getJournal(): ?bool

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteConcern's "journal" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcern::getJournal() example

<?php

$wc = new MongoDB\Driver\WriteConcern(1);
var_dump($wc->getJournal());

$wc = new MongoDB\Driver\WriteConcern(1, 0, true);
var_dump($wc->getJournal());

$wc = new MongoDB\Driver\WriteConcern(1, 0, false);
var_dump($wc->getJournal());

?>

上の例の出力は以下となります。

NULL
bool(true)
bool(false)

参考

  • » Write Concern reference


Returns the WriteConcern's "w" option

  • ≪ MongoDB\Driver\WriteConcern::getJournal
  • MongoDB\Driver\WriteConcern::getWtimeout ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns the WriteConcern's "w" option

MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option

説明

final public MongoDB\Driver\WriteConcern::getW(): string|int|null

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteConcern's "w" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcern::getW() example

<?php

$wc = new MongoDB\Driver\WriteConcern(1);
var_dump($wc->getW());

$wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
var_dump($wc->getW());

?>

上の例の出力は以下となります。

int(1)
string(8) "majority"

参考

  • » Write Concern reference


Returns the WriteConcern's "wtimeout" option

  • ≪ MongoDB\Driver\WriteConcern::getW
  • MongoDB\Driver\WriteConcern::isDefault ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Returns the WriteConcern's "wtimeout" option

MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option

説明

final public MongoDB\Driver\WriteConcern::getWtimeout(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteConcern's "wtimeout" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | On 32-bit systems, this method will always truncate the wTimeout value if it exceeds the 32-bit range. In that case, a warning will be emitted.

例

例1 MongoDB\Driver\WriteConcern::getWtimeout() example

<?php

$wc = new MongoDB\Driver\WriteConcern(1);
var_dump($wc->getWtimeout());

$wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 3000);
var_dump($wc->getWtimeout());

?>

上の例の出力は以下となります。

int(0)
int(3000)

参考

  • » Write Concern reference


Checks if this is the default write concern

  • ≪ MongoDB\Driver\WriteConcern::getWtimeout
  • MongoDB\Driver\WriteConcern::serialize ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Checks if this is the default write concern

MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern

説明

final public MongoDB\Driver\WriteConcern::isDefault(): bool

Returns whether this is the default write concern (i.e. no options are specified). This method is primarily intended to be used in conjunction with MongoDB\Driver\Manager::getWriteConcern() to determine whether the Manager has been constructed without any write concern options.

The driver will not include a default write concern in its write operations (e.g. MongoDB\Driver\Manager::executeBulkWrite()) in order to allow the server to apply its own default, which may have been » modified. Libraries that access the Manager's write concern to include it in their own write commands should use this method to ensure that default write concerns are left unset.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this is the default write concern and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcern::isDefault() example

<?php

$wc = new MongoDB\Driver\WriteConcern(1);
var_dump($wc->isDefault());

$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?w=majority');
$wc = $manager->getWriteConcern();
var_dump($wc->isDefault());

$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
$wc = $manager->getWriteConcern();
var_dump($wc->isDefault());

?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(true)

参考

  • MongoDB\Driver\Manager::getWriteConcern() - Return the WriteConcern for the Manager
  • » Modify Default Write Concern in the MongoDB manual
  • » Write Concern reference


Serialize a WriteConcern

  • ≪ MongoDB\Driver\WriteConcern::isDefault
  • MongoDB\Driver\WriteConcern::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Serialize a WriteConcern

MongoDB\Driver\WriteConcern::serialize

(mongodb >=1.7.0)

MongoDB\Driver\WriteConcern::serialize — Serialize a WriteConcern

説明

final public MongoDB\Driver\WriteConcern::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\Driver\WriteConcern.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\WriteConcern::unserialize() - Unserialize a WriteConcern
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Unserialize a WriteConcern

  • ≪ MongoDB\Driver\WriteConcern::serialize
  • MongoDB\Driver\ReadPreference ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcern
  • Unserialize a WriteConcern

MongoDB\Driver\WriteConcern::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\WriteConcern::unserialize — Unserialize a WriteConcern

説明

final public MongoDB\Driver\WriteConcern::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\Driver\WriteConcern.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\WriteConcern::serialize() - Serialize a WriteConcern
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\Driver\ReadPreference class

(mongodb >=1.0.0)

はじめに

クラス概要

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* 定数 */
const int RP_PRIMARY = 1;
const int RP_PRIMARY_PREFERRED = 5;
const int RP_SECONDARY = 2;
const int RP_SECONDARY_PREFERRED = 6;
const int RP_NEAREST = 10;
const string PRIMARY = primary;
const string PRIMARY_PREFERRED = primaryPreferred;
const string SECONDARY = secondary;
const string SECONDARY_PREFERRED = secondaryPreferred;
const string NEAREST = nearest;
const int NO_MAX_STALENESS = -1;
const int SMALLEST_MAX_STALENESS_SECONDS = 90;
/* メソッド */
final public bsonSerialize(): stdClass
final public __construct(string|int $mode, ?array $tagSets = null, ?array $options = null)
final public getHedge(): ?object
final public getMaxStalenessSeconds(): int
final public getMode(): int
final public getModeString(): string
final public getTagSets(): array
final public serialize(): string
final public unserialize(string $data): void
}

定義済み定数

MongoDB\Driver\ReadPreference::RP_PRIMARY

All operations read from the current replica set primary. This is the default read preference for MongoDB.

MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

MongoDB\Driver\ReadPreference::RP_SECONDARY

All operations read from the secondary members of the replica set.

MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

MongoDB\Driver\ReadPreference::RP_NEAREST

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

MongoDB\Driver\ReadPreference::PRIMARY

All operations read from the current replica set primary. This is the default read preference for MongoDB.

MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

MongoDB\Driver\ReadPreference::SECONDARY

All operations read from the secondary members of the replica set.

MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

MongoDB\Driver\ReadPreference::NEAREST

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

MongoDB\Driver\ReadPreference::NO_MAX_STALENESS

The default value for the "maxStalenessSeconds" option is to specify no limit on maximum staleness, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.

MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS

The minimum value for the "maxStalenessSeconds" option is 90 seconds. The driver estimates secondaries' staleness by periodically checking the latest write date of each replica set member. Since these checks are infrequent, the staleness estimate is coarse. Thus, the driver cannot enforce a max staleness value of less than 90 seconds.

変更履歴

バージョン | 説明
PECL mongodb 1.7.0 | Added the MongoDB\Driver\ReadPreference::PRIMARY, MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED, MongoDB\Driver\ReadPreference::SECONDARY, MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED, MongoDB\Driver\ReadPreference::NEAREST constants. Implements Serializable.
PECL mongodb 1.2.0 | Added the MongoDB\Driver\ReadPreference::NO_MAX_STALENESS and MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS constants. Implements MongoDB\BSON\Serializable.

目次

  • MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference
  • MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option
  • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option
  • MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option
  • MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option as a string
  • MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option
  • MongoDB\Driver\ReadPreference::serialize — Serialize a ReadPreference
  • MongoDB\Driver\ReadPreference::unserialize — Unserialize a ReadPreference


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\ReadPreference
  • MongoDB\Driver\ReadPreference::__construct ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns an object for BSON serialization

MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an object for serializing the ReadPreference as BSON.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadPreference::bsonSerialize() with primary read preference

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
var_dump($rp->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (1) {
  ["mode"]=>
  string(7) "primary"
}

{ "mode" : "primary" }

例2 MongoDB\Driver\ReadPreference::bsonSerialize() with secondary read preference and tag sets

<?php

$rp = new MongoDB\Driver\ReadPreference(
MongoDB\Driver\ReadPreference::RP_SECONDARY,
[
['dc' => 'ny'],
['dc' => 'sf', 'use' => 'reporting'],
[]
]
);
var_dump($rp->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["tags"]=>
  array(3) {
    [0]=>
    object(stdClass)#1 (1) {
      ["dc"]=>
      string(2) "ny"
    }
    [1]=>
    object(stdClass)#5 (2) {
      ["dc"]=>
      string(2) "sf"
      ["use"]=>
      string(9) "reporting"
    }
    [2]=>
    object(stdClass)#4 (0) {
    }
  }
}

{ "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

例3 MongoDB\Driver\ReadPreference::bsonSerialize() with secondary read preference and max staleness

<?php

$rp = new MongoDB\Driver\ReadPreference(
MongoDB\Driver\ReadPreference::RP_SECONDARY,
null,
['maxStalenessSeconds' => 120]
);
var_dump($rp->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["maxStalenessSeconds"]=>
  int(120)
}

{ "mode" : "secondary", "maxStalenessSeconds" : 120 }

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • » Read Preference reference


Create a new ReadPreference

  • ≪ MongoDB\Driver\ReadPreference::bsonSerialize
  • MongoDB\Driver\ReadPreference::getHedge ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Create a new ReadPreference

MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference

説明

final public MongoDB\Driver\ReadPreference::__construct(string|int $mode, ?array $tagSets = null, ?array $options = null)

Constructs a new MongoDB\Driver\ReadPreference, which is an immutable value object.

パラメータ

mode

Read preference mode
Value Description
MongoDB\Driver\ReadPreference::RP_PRIMARY or "primary"

All operations read from the current replica set primary. This is the default read preference for MongoDB.

MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED or "primaryPreferred"

In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.

MongoDB\Driver\ReadPreference::RP_SECONDARY or "secondary"

All operations read from the secondary members of the replica set.

MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED or "secondaryPreferred"

In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.

MongoDB\Driver\ReadPreference::RP_NEAREST or "nearest"

Operations read from member of the replica set with the least network latency, irrespective of the member's type.

tagSets

Tag sets allow you to target read operations to specific members of a replica set. This parameter should be an array of associative arrays, each of which contain zero or more key/value pairs. When selecting a server for a read operation, the driver attempt to select a node having all tags in a set (i.e. the associative array of key/value pairs). If selection fails, the driver will attempt subsequent sets. An empty tag set (array()) will match any node and may be used as a fallback.

Tags are not compatible with the MongoDB\Driver\ReadPreference::RP_PRIMARY mode and, in general, only apply when selecting a secondary member of a set for a read operation. However, the MongoDB\Driver\ReadPreference::RP_NEAREST mode, when combined with a tag set, selects the matching member with the lowest network latency. This member may be a primary or secondary.

options

options
Option Type Description
hedge object|array

Specifies whether to use » hedged reads, which are supported by MongoDB 4.4+ for sharded queries.

Server hedged reads are available for all non-primary read preferences and are enabled by default when using the "nearest" mode. This option allows explicitly enabling server hedged reads for non-primary read preferences by specifying ['enabled' => true], or explicitly disabling server hedged reads for the "nearest" read preference by specifying ['enabled' => false].

maxStalenessSeconds int

Specifies a maximum replication lag, or "staleness", for reads from secondaries. When a secondary's estimated staleness exceeds this value, the driver stops using it for read operations.

If specified, the max staleness must be a signed 32-bit integer greater than or equal to MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS.

Defaults to MongoDB\Driver\ReadPreference::NO_MAX_STALENESS, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.

This option is not compatible with the MongoDB\Driver\ReadPreference::RP_PRIMARY mode. Specifying a max staleness also requires all MongoDB instances in the deployment to be using MongoDB 3.4+. An exception will be thrown at execution time if any MongoDB instances in the deployment are of an older server version.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if mode is invalid.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if tagSets is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "maxStalenessSeconds" option is provided for a primary read preference or is out of range.

変更履歴

バージョン | 説明
PECL mongodb 1.8.0 | Added the "hedge" option.
PECL mongodb 1.3.0 | The mode argument now accepts a string value, which is consistent with the "readPreference" URI option for MongoDB\Driver\Manager::__construct().
PECL mongodb 1.2.0 | Added a third options argument, which supports the "maxStalenessSeconds" option.

例

例1 MongoDB\Driver\ReadPreference::__construct() example

<?php

/* Prefer a secondary node but fall back to a primary. */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED));

/* Prefer a node in the New York data center with lowest latency. */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST, [['dc' => 'ny']]));

/* Require a secondary node whose replication lag is within two minutes of the primary */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['maxStalenessSeconds' => 120]));

/* Explicitly enable server hedged reads */
var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['hedge' => ['enabled' => true]]));

?>

上の例の出力は以下となります。

object(MongoDB\Driver\ReadPreference)#1 (1) {
  ["mode"]=>
  string(18) "secondaryPreferred"
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(7) "nearest"
  ["tags"]=>
  array(1) {
    [0]=>
    object(stdClass)#2 (1) {
      ["dc"]=>
      string(2) "ny"
    }
  }
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["maxStalenessSeconds"]=>
  int(120)
}
object(MongoDB\Driver\ReadPreference)#1 (2) {
  ["mode"]=>
  string(9) "secondary"
  ["hedge"]=>
  object(stdClass)#1 (1) {
    ["enabled"]=>
    bool(true)
  }
}

参考

  • » Read Preference reference


Returns the ReadPreference's "hedge" option

  • ≪ MongoDB\Driver\ReadPreference::__construct
  • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "hedge" option

MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option

説明

final public MongoDB\Driver\ReadPreference::getHedge(): ?object

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the ReadPreference's "hedge" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • » Read Preference reference


Returns the ReadPreference's "maxStalenessSeconds" option

  • ≪ MongoDB\Driver\ReadPreference::getHedge
  • MongoDB\Driver\ReadPreference::getMode ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "maxStalenessSeconds" option

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option

説明

final public MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the ReadPreference's "maxStalenessSeconds" option. If no max staleness has been specified, MongoDB\Driver\ReadPreference::NO_MAX_STALENESS will be returned.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadPreference::getMaxStalenessSeconds() example

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY);
var_dump($rp->getMaxStalenessSeconds());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [
'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
]);
var_dump($rp->getMaxStalenessSeconds());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [
'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
]);
var_dump($rp->getMaxStalenessSeconds());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [
'maxStalenessSeconds' => 1000,
]);
var_dump($rp->getMaxStalenessSeconds());

?>

上の例の出力は以下となります。

int(-1)
int(-1)
int(90)
int(1000)

参考

  • » Read Preference reference


Returns the ReadPreference's "mode" option

  • ≪ MongoDB\Driver\ReadPreference::getMaxStalenessSeconds
  • MongoDB\Driver\ReadPreference::getModeString ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "mode" option

MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option

説明

final public MongoDB\Driver\ReadPreference::getMode(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the ReadPreference's "mode" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadPreference::getMode() example

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED);
var_dump($rp->getMode());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST);
var_dump($rp->getMode());

?>

上の例の出力は以下となります。

int(1)
int(5)
int(2)
int(6)
int(10)

参考

  • MongoDB\Driver\ReadPreference::getModeString() - Returns the ReadPreference's "mode" option as a string
  • » Read Preference reference


Returns the ReadPreference's "mode" option as a string

  • ≪ MongoDB\Driver\ReadPreference::getMode
  • MongoDB\Driver\ReadPreference::getTagSets ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "mode" option as a string

MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option as a string

説明

final public MongoDB\Driver\ReadPreference::getModeString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the ReadPreference's "mode" option as a string.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadPreference::getModeString() example

<?php

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
var_dump($rp->getModeString());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
var_dump($rp->getModeString());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
var_dump($rp->getModeString());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
var_dump($rp->getModeString());

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
var_dump($rp->getModeString());

?>

上の例の出力は以下となります。

string(7) "primary"
string(16) "primaryPreferred"
string(9) "secondary"
string(18) "secondaryPreferred"
string(7) "nearest"

参考

  • MongoDB\Driver\ReadPreference::getMode() - Returns the ReadPreference's "mode" option
  • » Read Preference reference


Returns the ReadPreference's "tagSets" option

  • ≪ MongoDB\Driver\ReadPreference::getModeString
  • MongoDB\Driver\ReadPreference::serialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Returns the ReadPreference's "tagSets" option

MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option

説明

final public MongoDB\Driver\ReadPreference::getTagSets(): array

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the ReadPreference's "tagSets" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadPreference::getTagSets() example

<?php

$mode = MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED;

/* Null and an empty array both denote no tag set preference. */
$rp = new MongoDB\Driver\ReadPreference($mode, null);
var_dump($rp->getTagSets());

$rp = new MongoDB\Driver\ReadPreference($mode, []);
var_dump($rp->getTagSets());

/* Prefer a node in New York, but fall back to any available node. */
$rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
var_dump($rp->getTagSets());

/* Prefer a node in the New York, followed by a node in San Francisco that is
labeled for reporting usage, and finally fall back to any available node. */
$rp = new MongoDB\Driver\ReadPreference($mode, [
['dc' => 'ny'],
['dc' => 'sf', 'use' => 'reporting'],
[],
]);
var_dump($rp->getTagSets());

?>

上の例の出力は以下となります。

array(0) {
}
array(0) {
}
array(2) {
  [0]=>
  array(1) {
    ["dc"]=>
    string(2) "ny"
  }
  [1]=>
  array(0) {
  }
}
array(3) {
  [0]=>
  array(1) {
    ["dc"]=>
    string(2) "ny"
  }
  [1]=>
  array(2) {
    ["dc"]=>
    string(2) "sf"
    ["use"]=>
    string(9) "reporting"
  }
  [2]=>
  array(0) {
  }
}

参考

  • » Read Preference reference


Serialize a ReadPreference

  • ≪ MongoDB\Driver\ReadPreference::getTagSets
  • MongoDB\Driver\ReadPreference::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Serialize a ReadPreference

MongoDB\Driver\ReadPreference::serialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::serialize — Serialize a ReadPreference

説明

final public MongoDB\Driver\ReadPreference::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\Driver\ReadPreference.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\ReadPreference::unserialize() - Unserialize a ReadPreference
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Unserialize a ReadPreference

  • ≪ MongoDB\Driver\ReadPreference::serialize
  • MongoDB\Driver\ReadConcern ≫
  • PHP Manual
  • MongoDB\Driver\ReadPreference
  • Unserialize a ReadPreference

MongoDB\Driver\ReadPreference::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::unserialize — Unserialize a ReadPreference

説明

final public MongoDB\Driver\ReadPreference::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\Driver\ReadPreference.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\ReadPreference::serialize() - Serialize a ReadPreference
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\Driver\ReadConcern class

(mongodb >=1.1.0)

はじめに

MongoDB\Driver\ReadConcern controls the level of isolation for read operations for replica sets and replica set shards. This option requires MongoDB 3.2 or later.

クラス概要

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* 定数 */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* メソッド */
final public bsonSerialize(): stdClass
final public __construct(?string $level = null)
final public getLevel(): ?string
final public isDefault(): bool
final public serialize(): string
final public unserialize(string $data): void
}

定義済み定数

MongoDB\Driver\ReadConcern::AVAILABLE

Default for reads against secondaries when afterClusterTimeand level are unspecified.

The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).

For unsharded collections (including collections in a standalone deployment or a replica set deployment), "local" and "available" read concerns behave identically.

For a sharded cluster, "available" read concern provides greater tolerance for partitions since it does not wait to ensure consistency guarantees. However, a query with "available" read concern may return orphan documents if the shard is undergoing chunk migrations since the "available" read concern, unlike "local" read concern, does not contact the shard's primary nor the config servers for updated metadata.

MongoDB\Driver\ReadConcern::LINEARIZABLE

The query returns data that reflects all successful writes issued with a write concern of "majority" and acknowledged prior to the start of the read operation. For replica sets that run with writeConcernMajorityJournalDefault set to true, linearizable read concern returns data that will never be rolled back.

With writeConcernMajorityJournalDefault set to false, MongoDB will not wait for w: "majority" writes to be durable before acknowledging the writes. As such, "majority" write operations could possibly roll back in the event of a loss of a replica set member.

You can specify linearizable read concern for read operations on the primary only.

Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document.

ヒント

Always use maxTimeMS with linearizable read concern in case a majority of data bearing members are unavailable. maxTimeMS ensures that the operation does not block indefinitely and instead ensures that the operation returns an error if the read concern cannot be fulfilled.

Linearizable read concern requires MongoDB 3.4.

MongoDB\Driver\ReadConcern::LOCAL

Default for reads against primary if level is unspecified and for reads against secondaries if level is unspecified but afterClusterTime is specified.

The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).

MongoDB\Driver\ReadConcern::MAJORITY

The query returns the instance's most recent data acknowledged as having been written to a majority of members in the replica set.

To use read concern level of "majority", replica sets must use WiredTiger storage engine and election protocol version 1.

MongoDB\Driver\ReadConcern::SNAPSHOT

Read concern "snapshot" is available for multi-document transactions, and starting in MongoDB 5.0, certain read operations outside of multi-document transactions.

If the transaction is not part of a causally consistent session, upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.

If the transaction is part of a causally consistent session, upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data that provides causal consistency with the operation immediately preceding the transaction start.

Outside of multi-document transactions, read concern "snapshot" is available on primaries and secondaries for the following read operations: find, aggregate, and distinct (on unsharded collections). All other read commands prohibit "snapshot".

変更履歴

バージョン | 説明
PECL mongodb 1.11.0 | Added the MongoDB\Driver\ReadConcern::SNAPSHOT constant.
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.4.0 | Added the MongoDB\Driver\ReadConcern::AVAILABLE constant.
PECL mongodb 1.2.0 | Added the MongoDB\Driver\ReadConcern::LINEARIZABLE constant. Implements MongoDB\BSON\Serializable.

参考

  • » Read Concern reference

目次

  • MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization
  • MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern
  • MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option
  • MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern
  • MongoDB\Driver\ReadConcern::serialize — Serialize a ReadConcern
  • MongoDB\Driver\ReadConcern::unserialize — Unserialize a ReadConcern


Returns an object for BSON serialization

  • ≪ MongoDB\Driver\ReadConcern
  • MongoDB\Driver\ReadConcern::__construct ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Returns an object for BSON serialization

MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization

説明

final public MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an object for serializing the ReadConcern as BSON.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadConcern::bsonSerialize() with empty read concern

<?php

$rc = new MongoDB\Driver\ReadConcern;
var_dump($rc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (0) {
}

{ }

例2 MongoDB\Driver\ReadConcern::bsonSerialize() with local read concern

<?php

$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
var_dump($rc->bsonSerialize());

echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rc));

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (1) {
  ["level"]=>
  string(5) "local"
}

{ "level" : "local" }

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • » Read Concern reference


Create a new ReadConcern

  • ≪ MongoDB\Driver\ReadConcern::bsonSerialize
  • MongoDB\Driver\ReadConcern::getLevel ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Create a new ReadConcern

MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern

説明

final public MongoDB\Driver\ReadConcern::__construct(?string $level = null)

Constructs a new MongoDB\Driver\ReadConcern, which is an immutable value object.

パラメータ

level

The » read concern level. You may use, but are not limited to, one of the class constants.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadConcern::__construct() example

<?php

/* Unspecified read isolation level (uses the server's default behavior) */
$rc = new MongoDB\Driver\ReadConcern();

/* Request read isolation from a single replica set node */
$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);

/* Request read isolation from a majority of the replica set nodes */
$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);

?>

参考

  • » Read Concern reference


Returns the ReadConcern's "level" option

  • ≪ MongoDB\Driver\ReadConcern::__construct
  • MongoDB\Driver\ReadConcern::isDefault ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Returns the ReadConcern's "level" option

MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option

説明

final public MongoDB\Driver\ReadConcern::getLevel(): ?string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the ReadConcern's "level" option.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadConcern::getLevel() example

<?php

$rc = new MongoDB\Driver\ReadConcern();
var_dump($rc->getLevel());

$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
var_dump($rc->getLevel());

$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
var_dump($rc->getLevel());

?>

上の例の出力は以下となります。

NULL
string(5) "local"
string(8) "majority"

参考

  • » Read Concern reference


Checks if this is the default read concern

  • ≪ MongoDB\Driver\ReadConcern::getLevel
  • MongoDB\Driver\ReadConcern::serialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Checks if this is the default read concern

MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern

説明

final public MongoDB\Driver\ReadConcern::isDefault(): bool

Returns whether this is the default read concern (i.e. no options are specified). This method is primarily intended to be used in conjunction with MongoDB\Driver\Manager::getReadConcern() to determine whether the Manager has been constructed without any read concern options.

The driver will not include a default read concern in its read operations (e.g. MongoDB\Driver\Manager::executeQuery()) in order order to allow the server to apply its own default. Libraries that access the Manager's read concern to include it in their own read commands should use this method to ensure that default read concerns are left unset.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this is the default read concern and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\ReadConcern::isDefault() example

<?php

$rc = new MongoDB\Driver\ReadConcern(null);
var_dump($rc->isDefault());

$rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
var_dump($rc->isDefault());

$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?readConcernLevel=majority');
$rc = $manager->getReadConcern();
var_dump($rc->isDefault());

$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
$rc = $manager->getReadConcern();
var_dump($rc->isDefault());

?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)
bool(true)

参考

  • MongoDB\Driver\Manager::getReadConcern() - Return the ReadConcern for the Manager
  • » Read Concern reference


Serialize a ReadConcern

  • ≪ MongoDB\Driver\ReadConcern::isDefault
  • MongoDB\Driver\ReadConcern::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Serialize a ReadConcern

MongoDB\Driver\ReadConcern::serialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadConcern::serialize — Serialize a ReadConcern

説明

final public MongoDB\Driver\ReadConcern::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\Driver\ReadConcern.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\ReadConcern::unserialize() - Unserialize a ReadConcern
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Unserialize a ReadConcern

  • ≪ MongoDB\Driver\ReadConcern::serialize
  • MongoDB\Driver\Cursor ≫
  • PHP Manual
  • MongoDB\Driver\ReadConcern
  • Unserialize a ReadConcern

MongoDB\Driver\ReadConcern::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\ReadConcern::unserialize — Unserialize a ReadConcern

説明

final public MongoDB\Driver\ReadConcern::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\Driver\ReadConcern.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\ReadConcern::serialize() - Serialize a ReadConcern
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\Driver\Cursor class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\Cursor class encapsulates the results of a MongoDB command or query and may be returned by MongoDB\Driver\Manager::executeCommand() or MongoDB\Driver\Manager::executeQuery(), respectively.

クラス概要

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface, Iterator {
/* メソッド */
final private __construct()
public current(): array|object|null
final public getId(): MongoDB\Driver\CursorId
final public getServer(): MongoDB\Driver\Server
final public isDead(): bool
public key(): int
public next(): void
public rewind(): void
final public setTypeMap(array $typemap): void
final public toArray(): array
public valid(): bool
}

変更履歴

バージョン | 説明
PECL mongodb 1.9.0 | Implements Iterator.
PECL mongodb 1.6.0 | Implements MongoDB\Driver\CursorInterface, which extends Traversable.

例

例1 Reading a result set

MongoDB\Driver\Manager::executeCommand() and MongoDB\Driver\Manager::executeQuery() both return their result(s) as a MongoDB\Driver\Cursor object. This object can be used to iterate over the result set of the command or query.

Because MongoDB\Driver\Cursor implements the Traversable interface, you can simply iterate over the result set with foreach.

<?php

$manager = new MongoDB\Driver\Manager();

/* Insert some documents so that our query returns information */
$bulkWrite = new MongoDB\Driver\BulkWrite;
$bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
$bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
$manager->executeBulkWrite("test.asteroids", $bulkWrite);

/* Query for all the items in the collection */
$query = new MongoDB\Driver\Query( [] );

/* Query the "asteroids" collection of the "test" database */
$cursor = $manager->executeQuery("test.asteroids", $query);

/* $cursor now contains an object that wraps around the result set. Use
* foreach() to iterate over all the result */
foreach($cursor as $document) {
print_r($document);
}

?>

上の例の出力は、 たとえば以下のようになります。

stdClass Object
(
    [_id] => MongoDB\BSON\ObjectId Object
        (
            [oid] => 5a4cff2f122d3321565d8cc2
        )

    [name] => Ceres
    [size] => 946
    [distance] => 2.766
)
stdClass Object
(
    [_id] => MongoDB\BSON\ObjectId Object
        (
            [oid] => 5a4cff2f122d3321565d8cc3
        )

    [name] => Vesta
    [size] => 525
    [distance] => 2.362
}

例2 Reading a result set for a tailable cursor

» Tailable cursors are a special type of MongoDB cursor that allows the client to read some results and then wait until more documents become available. These cursors are primarily used with » Capped Collections and » Change Streams.

While normal cursors can be iterated once with foreach, that approach will not work with tailable cursors. When foreach is used with a tailable cursor, the loop will stop upon reaching the end of the initial result set. Attempting to continue iteration on the cursor with a second foreach would throw an exception, since PHP attempts to rewind the cursor. Similar to result objects in other database drivers, cursors in MongoDB only support forward iteration, which means they cannot be rewound.

In order to continuously read from a tailable cursor, the Cursor object must be wrapped with an IteratorIterator. This allows the application to directly control the cursor's iteration, avoid inadvertently rewinding the cursor, and decide when to wait for new results or stop iteration entirely.

In order to demonstrate a tailable cursor in action, two scripts will be used: a "producer" and a "consumer". The producer script will create a new capped collection using the » create command and proceed to insert a new document into that collection each second.

<?php

$manager = new MongoDB\Driver\Manager;

$manager->executeCommand('test', new MongoDB\Driver\Command([
'create' => 'asteroids',
'capped' => true,
'size' => 1048576,
]));

while (true) {
$bulkWrite = new MongoDB\Driver\BulkWrite;
$bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
$manager->executeBulkWrite('test.asteroids', $bulkWrite);

sleep(1);
}

?>

With the producer script still running, a second consumer script may be executed to read the inserted documents using a tailable cursor, indicated by the tailable and awaitData options to MongoDB\Driver\Query::__construct().

<?php

$manager = new MongoDB\Driver\Manager;

$query = new MongoDB\Driver\Query([], [
'tailable' => true,
'awaitData' => true,
]);

$cursor = $manager->executeQuery('test.asteroids', $query);

$iterator = new IteratorIterator($cursor);

$iterator->rewind();

while (true) {
if ($iterator->valid()) {
$document = $iterator->current();
printf("Consumed document created at: %s\n", $document->createdAt);
}

$iterator->next();
}

?>

The consumer script will start by quickly printing all available documents in the capped collection (as if foreach had been used); however, it will not terminate upon reaching the end of the initial result set. Since the cursor is tailable, calling IteratorIterator::next() will block and wait for additional results. IteratorIterator::valid() is also used to check if there is actually data available to read at each step.

注意: This example uses the awaitData query option to instruct the server to block for a short period (e.g. one second) at the end of the result set before returning a response to the driver. This is used to prevent the driver from aggressively polling the server when there are no results available. The maxAwaitTimeMS option may be used in conjunction with tailable and awaitData to specify the amount of time that the server should block when it reaches the end of the result set.

エラー / 例外

When iterating over the cursor object, BSON data is converted into PHP variables. This iteration can cause the following Exceptions:

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

目次

  • MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)
  • MongoDB\Driver\Cursor::current — Returns the current element
  • MongoDB\Driver\Cursor::getId — Returns the ID for this cursor
  • MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor
  • MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results
  • MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor
  • MongoDB\Driver\Cursor::next — Advances the cursor to the next result
  • MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result
  • MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization
  • MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor
  • MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid


Create a new Cursor (not used)

  • ≪ MongoDB\Driver\Cursor
  • MongoDB\Driver\Cursor::current ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Create a new Cursor (not used)

MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)

説明

final private MongoDB\Driver\Cursor::__construct()

MongoDB\Driver\Cursor objects are returned as the result of an executed command or query and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Manager::executeCommand() - Execute a database command
  • MongoDB\Driver\Manager::executeQuery() - Execute a database query
  • MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
  • MongoDB\Driver\Server::executeQuery() - Execute a database query on this server


Returns the current element

  • ≪ MongoDB\Driver\Cursor::__construct
  • MongoDB\Driver\Cursor::getId ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the current element

MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Returns the current element

説明

public MongoDB\Driver\Cursor::current(): array|object|null

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current result document as an array or object, depending on the cursor's type map. If iteration has not started or the current position is not valid, null will be returned.

参考

  • Iterator::current() - 現在の要素を返す


Returns the ID for this cursor

  • ≪ MongoDB\Driver\Cursor::current
  • MongoDB\Driver\Cursor::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the ID for this cursor

MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Returns the ID for this cursor

説明

final public MongoDB\Driver\Cursor::getId(): MongoDB\Driver\CursorId

Returns the MongoDB\Driver\CursorId associated with this cursor. A cursor ID uniquely identifies the cursor on the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\CursorId for this cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Cursor::getId() example

<?php

/* In this example, we insert several documents into the collection and specify
* a smaller batchSize to ensure that the first batch contains only a subset of
* our results and the cursor remains open on the server. */
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$cursor = $manager->executeQuery('db.collection', $query);
var_dump($cursor->getId());

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\CursorId)#5 (1) {
  ["id"]=>
  int(94810124093)
}

参考

  • MongoDB\Driver\CursorId
  • MongoDB\Driver\CursorId::__toString() - String representation of the cursor ID


Returns the server associated with this cursor

  • ≪ MongoDB\Driver\Cursor::getId
  • MongoDB\Driver\Cursor::isDead ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the server associated with this cursor

MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor

説明

final public MongoDB\Driver\Cursor::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the MongoDB\Driver\Query or MongoDB\Driver\Command.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server associated with this cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Cursor::getServer() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$query = new MongoDB\Driver\Query([]);

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$manager->executeBulkWrite('db.collection', $bulk);

$cursor = $manager->executeQuery('db.collection', $query);
var_dump($cursor->getServer());

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\Server)#5 (10) {
  ["host"]=>
  string(9) "localhost"
  ["port"]=>
  int(27017)
  ["type"]=>
  int(1)
  ["is_primary"]=>
  bool(false)
  ["is_secondary"]=>
  bool(false)
  ["is_arbiter"]=>
  bool(false)
  ["is_hidden"]=>
  bool(false)
  ["is_passive"]=>
  bool(false)
  ["last_hello_response"]=>
  array(8) {
    ["isWritablePrimary"]=>
    bool(true)
    ["maxBsonObjectSize"]=>
    int(16777216)
    ["maxMessageSizeBytes"]=>
    int(48000000)
    ["maxWriteBatchSize"]=>
    int(1000)
    ["localTime"]=>
    object(MongoDB\BSON\UTCDateTime)#6 (1) {
      ["milliseconds"]=>
      int(1446505367907)
    }
    ["maxWireVersion"]=>
    int(3)
    ["minWireVersion"]=>
    int(0)
    ["ok"]=>
    float(1)
  }
  ["round_trip_time"]=>
  int(584)
}

参考

  • MongoDB\Driver\Server


Checks if the cursor is exhausted or may have additional results

  • ≪ MongoDB\Driver\Cursor::getServer
  • MongoDB\Driver\Cursor::key ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Checks if the cursor is exhausted or may have additional results

MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results

説明

final public MongoDB\Driver\Cursor::isDead(): bool

Checks whether there are definitely no additional results available on the cursor. This method is similar to the » cursor.isExhausted() method in the MongoDB shell and is primarily useful when iterating » tailable cursors.

A cursor has no additional results and is considered "dead" when one of the following is true:

  • The current batch has been fully iterated and the cursor ID is zero (i.e. a » getMore cannot be issued).
  • An error was encountered while iterating the cursor.
  • The cursor reached its configured limit.

By design, it is not possible to always determine whether a cursor has additional results. The cases where a cursor may have more data available is as follows:

  • There are additional documents in the current batch, which are buffered on the client side. Iterating will fetch a document from the local buffer.
  • There are no additional documents in the current batch (i.e. local buffer), but the cursor ID is non-zero. Iterating will request more documents from the server via a » getMore operation, which may or may not return additional results and/or indicate that the cursor has been closed on the server by returning zero for its ID.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if there are definitely no additional results available on the cursor, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Cursor::isDead() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$query = new MongoDB\Driver\Query([]);

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$cursor = $manager->executeQuery('db.collection', $query);

$iterator = new IteratorIterator($cursor);

$iterator->rewind();
var_dump($cursor->isDead());

$iterator->next();
var_dump($cursor->isDead());

$iterator->next();
var_dump($cursor->isDead());

$iterator->next();
var_dump($cursor->isDead());

?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(false)
bool(true)

参考

  • » Tailable Cursors in the MongoDB manual
  • » cursor.isExhausted() in the MongoDB manual


Returns the current result's index within the cursor

  • ≪ MongoDB\Driver\Cursor::isDead
  • MongoDB\Driver\Cursor::next ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns the current result's index within the cursor

MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor

説明

public MongoDB\Driver\Cursor::key(): int

パラメータ

この関数にはパラメータはありません。

戻り値

The current result's numeric index within the cursor.

参考

  • Iterator::key() - 現在の要素のキーを返す


Advances the cursor to the next result

  • ≪ MongoDB\Driver\Cursor::key
  • MongoDB\Driver\Cursor::rewind ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Advances the cursor to the next result

MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Advances the cursor to the next result

説明

public MongoDB\Driver\Cursor::next(): void

パラメータ

この関数にはパラメータはありません。

戻り値

Moves the current position to the next element in the cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.

参考

  • Iterator::next() - 次の要素に進む


Rewind the cursor to the first result

  • ≪ MongoDB\Driver\Cursor::next
  • MongoDB\Driver\Cursor::setTypeMap ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Rewind the cursor to the first result

MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result

説明

public MongoDB\Driver\Cursor::rewind(): void

If the cursor has advanced beyond its first position, it can no longer be rewound.

パラメータ

この関数にはパラメータはありません。

戻り値

null.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\LogicException if this method is called after the cursor has advanced beyond its first position.

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す


Sets a type map to use for BSON unserialization

  • ≪ MongoDB\Driver\Cursor::rewind
  • MongoDB\Driver\Cursor::toArray ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Sets a type map to use for BSON unserialization

MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization

説明

final public MongoDB\Driver\Cursor::setTypeMap(array $typemap): void

Sets the type map configuration to use when unserializing the BSON results into PHP values.

パラメータ

typeMap (array)

Type map configuration.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

When iterating over the cursor, the following exceptions can also be thrown due to an incorrect type map configuration:

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

例

例1 MongoDB\Driver\Cursor::setTypeMap() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$id = $bulk->insert(['x' => 1]);
$manager->executeBulkWrite('db.collection', $bulk);

$query = new MongoDB\Driver\Query(['_id' => $id]);
$cursor = $manager->executeQuery('db.collection', $query);
$cursor->setTypeMap(['root' => 'array']);

foreach ($cursor as $document) {
var_dump($document);
}

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["_id"]=>
  object(MongoDB\BSON\ObjectId)#6 (1) {
    ["oid"]=>
    string(24) "56424fb76118fd3267180741"
  }
  ["x"]=>
  int(1)
}

参考

  • Persisting Data


Returns an array containing all results for this cursor

  • ≪ MongoDB\Driver\Cursor::setTypeMap
  • MongoDB\Driver\Cursor::valid ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Returns an array containing all results for this cursor

MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor

説明

final public MongoDB\Driver\Cursor::toArray(): array

Iterates the cursor and returns its results in an array. MongoDB\Driver\Cursor::setTypeMap() may be used to control how documents are unserialized into PHP values.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array containing all results for this cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Cursor::toArray() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$query = new MongoDB\Driver\Query([]);
$cursor = $manager->executeQuery('db.collection', $query);

var_dump($cursor->toArray());

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  object(stdClass)#6 (2) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "564259a96118fd40b41bcf61"
    }
    ["x"]=>
    int(1)
  }
  [1]=>
  object(stdClass)#8 (2) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#7 (1) {
      ["oid"]=>
      string(24) "564259a96118fd40b41bcf62"
    }
    ["x"]=>
    int(2)
  }
  [2]=>
  object(stdClass)#10 (2) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#9 (1) {
      ["oid"]=>
      string(24) "564259a96118fd40b41bcf63"
    }
    ["x"]=>
    int(3)
  }
}

参考

  • MongoDB\Driver\Cursor::setTypeMap() - Sets a type map to use for BSON unserialization


Checks if the current position in the cursor is valid

  • ≪ MongoDB\Driver\Cursor::toArray
  • MongoDB\Driver\CursorId ≫
  • PHP Manual
  • MongoDB\Driver\Cursor
  • Checks if the current position in the cursor is valid

MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid

説明

public MongoDB\Driver\Cursor::valid(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

true if the current cursor position is valid, false otherwise.

参考

  • Iterator::valid() - 現在位置が有効かどうかを調べる


The MongoDB\Driver\CursorId class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\CursorID class is a value object that represents a cursor ID. Instances of this class are returned by MongoDB\Driver\Cursor::getId().

クラス概要

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* メソッド */
final private __construct()
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.7.0 | Implements Serializable.

目次

  • MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)
  • MongoDB\Driver\CursorId::serialize — Serialize a CursorId
  • MongoDB\Driver\CursorId::__toString — String representation of the cursor ID
  • MongoDB\Driver\CursorId::unserialize — Unserialize a CursorId


Create a new CursorId (not used)

  • ≪ MongoDB\Driver\CursorId
  • MongoDB\Driver\CursorId::serialize ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • Create a new CursorId (not used)

MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)

説明

final private MongoDB\Driver\CursorId::__construct()

MongoDB\Driver\CursorId objects are returned from MongoDB\Driver\Cursor::getId() and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor


Serialize a CursorId

  • ≪ MongoDB\Driver\CursorId::__construct
  • MongoDB\Driver\CursorId::__toString ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • Serialize a CursorId

MongoDB\Driver\CursorId::serialize

(mongodb >=1.7.0)

MongoDB\Driver\CursorId::serialize — Serialize a CursorId

説明

final public MongoDB\Driver\CursorId::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\Driver\CursorId.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\CursorId::unserialize() - Unserialize a CursorId
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


String representation of the cursor ID

  • ≪ MongoDB\Driver\CursorId::serialize
  • MongoDB\Driver\CursorId::unserialize ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • String representation of the cursor ID

MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — String representation of the cursor ID

説明

final public MongoDB\Driver\CursorId::__toString(): string

Returns the string representation of the cursor ID.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of the cursor ID.

例

例1 MongoDB\Driver\CursorId::__toString() example

<?php

/* In this example, we insert several documents into the collection and specify
* a smaller batchSize to ensure that the first batch contains only a subset of
* our results and the cursor remains open on the server. */
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->insert(['x' => 2]);
$bulk->insert(['x' => 3]);
$manager->executeBulkWrite('db.collection', $bulk);

$cursor = $manager->executeQuery('db.collection', $query);
var_dump((string) $cursor->getId());

?>

上の例の出力は、 たとえば以下のようになります。

string(11) "98061641158"

参考

  • MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor


Unserialize a CursorId

  • ≪ MongoDB\Driver\CursorId::__toString
  • MongoDB\Driver\CursorInterface ≫
  • PHP Manual
  • MongoDB\Driver\CursorId
  • Unserialize a CursorId

MongoDB\Driver\CursorId::unserialize

(mongodb >=1.7.0)

MongoDB\Driver\CursorId::unserialize — Unserialize a CursorId

説明

final public MongoDB\Driver\CursorId::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\Driver\CursorId.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\Driver\CursorId::serialize() - Serialize a CursorId
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\Driver\CursorInterface interface

(mongodb >=1.6.0)

はじめに

This interface is implemented by MongoDB\Driver\Cursor to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\Driver\CursorInterface implements Traversable {
/* メソッド */
abstract public getId(): MongoDB\Driver\CursorId
abstract public getServer(): MongoDB\Driver\Server
abstract public isDead(): bool
abstract public setTypeMap(array $typemap): void
abstract public toArray(): array
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor
  • MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor
  • MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results
  • MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization
  • MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor


Returns the ID for this cursor

  • ≪ MongoDB\Driver\CursorInterface
  • MongoDB\Driver\CursorInterface::getServer ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Returns the ID for this cursor

MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor

説明

abstract public MongoDB\Driver\CursorInterface::getId(): MongoDB\Driver\CursorId

Returns the MongoDB\Driver\CursorId associated with this cursor. A cursor ID uniquely identifies the cursor on the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\CursorId for this cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor
  • MongoDB\Driver\CursorId
  • MongoDB\Driver\CursorId::__toString() - String representation of the cursor ID


Returns the server associated with this cursor

  • ≪ MongoDB\Driver\CursorInterface::getId
  • MongoDB\Driver\CursorInterface::isDead ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Returns the server associated with this cursor

MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor

説明

abstract public MongoDB\Driver\CursorInterface::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the MongoDB\Driver\Query or MongoDB\Driver\Command.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server associated with this cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Cursor::getServer() - Returns the server associated with this cursor
  • MongoDB\Driver\Server


Checks if the cursor may have additional results

  • ≪ MongoDB\Driver\CursorInterface::getServer
  • MongoDB\Driver\CursorInterface::setTypeMap ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Checks if the cursor may have additional results

MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results

説明

abstract public MongoDB\Driver\CursorInterface::isDead(): bool

Checks whether the cursor may have additional results available to read. A cursor is initially "alive" but may become "dead" for any of the following reasons:

  • Advancing a non-tailable cursor did not return a document
  • The cursor encountered an error
  • The cursor read its last batch to completion
  • The cursor reached its configured limit
This is primarily useful with tailable cursors.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if additional results are not available, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Cursor::isDead() - Checks if the cursor is exhausted or may have additional results


Sets a type map to use for BSON unserialization

  • ≪ MongoDB\Driver\CursorInterface::isDead
  • MongoDB\Driver\CursorInterface::toArray ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Sets a type map to use for BSON unserialization

MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization

説明

abstract public MongoDB\Driver\CursorInterface::setTypeMap(array $typemap): void

Sets the type map configuration to use when unserializing the BSON results into PHP values.

パラメータ

typeMap (array)

Type map configuration.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Cursor::setTypeMap() - Sets a type map to use for BSON unserialization
  • Persisting Data


Returns an array containing all results for this cursor

  • ≪ MongoDB\Driver\CursorInterface::setTypeMap
  • MongoDB\Driver\Server ≫
  • PHP Manual
  • MongoDB\Driver\CursorInterface
  • Returns an array containing all results for this cursor

MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor

説明

abstract public MongoDB\Driver\CursorInterface::toArray(): array

Iterates the cursor and returns its results in an array. MongoDB\Driver\CursorInterface::setTypeMap() may be used to control how documents are unserialized into PHP values.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array containing all results for this cursor.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Cursor::toArray() - Returns an array containing all results for this cursor
  • MongoDB\Driver\CursorInterface::setTypeMap() - Sets a type map to use for BSON unserialization


The MongoDB\Driver\Server class

(mongodb >=1.0.0)

はじめに

クラス概要

final class MongoDB\Driver\Server {
/* 定数 */
const int TYPE_UNKNOWN = 0;
const int TYPE_STANDALONE = 1;
const int TYPE_MONGOS = 2;
const int TYPE_POSSIBLE_PRIMARY = 3;
const int TYPE_RS_PRIMARY = 4;
const int TYPE_RS_SECONDARY = 5;
const int TYPE_RS_ARBITER = 6;
const int TYPE_RS_OTHER = 7;
const int TYPE_RS_GHOST = 8;
const int TYPE_LOAD_BALANCER = 9;
/* メソッド */
final private __construct()
final public executeBulkWrite(string $namespace, MongoDB\Driver\BulkWrite $bulk, array|MongoDB\Driver\WriteConcern|null $options = null): MongoDB\Driver\WriteResult
final public executeCommand(string $db, MongoDB\Driver\Command $command, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor
final public executeQuery(string $namespace, MongoDB\Driver\Query $query, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor
final public executeReadCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
final public executeReadWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
final public executeWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor
final public getHost(): string
final public getInfo(): array
final public getLatency(): ?integer
final public getPort(): int
final public getServerDescription(): MongoDB\Driver\ServerDescription
final public getTags(): array
final public getType(): int
final public isArbiter(): bool
final public isHidden(): bool
final public isPassive(): bool
final public isPrimary(): bool
final public isSecondary(): bool
}

定義済み定数

MongoDB\Driver\Server::TYPE_UNKNOWN

Unknown server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_STANDALONE

Standalone server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_MONGOS

Mongos server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY

Replica set possible primary server type, returned by MongoDB\Driver\Server::getType().

A server may be identified as a possible primary if it has not yet been checked but another memory of the replica set thinks it is the primary.

MongoDB\Driver\Server::TYPE_RS_PRIMARY

Replica set primary server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_RS_SECONDARY

Replica set secondary server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_RS_ARBITER

Replica set arbiter server type, returned by MongoDB\Driver\Server::getType().

MongoDB\Driver\Server::TYPE_RS_OTHER

Replica set other server type, returned by MongoDB\Driver\Server::getType().

Such servers may be hidden, starting up, or recovering. They cannot be queried, but their hosts lists are useful for discovering the current replica set configuration.

MongoDB\Driver\Server::TYPE_RS_GHOST

Replica set ghost server type, returned by MongoDB\Driver\Server::getType().

Servers may be identified as such in at least three situations: briefly during server startup; in an uninitialized replica set; or when the server is shunned (i.e. removed from the replica set config). They cannot be queried, nor can their host list be used to discover the current replica set configuration; however, the client may monitor this server in hope that it transitions to a more useful state.

MongoDB\Driver\Server::TYPE_LOAD_BALANCER

Load balancer server type, returned by MongoDB\Driver\Server::getType().

変更履歴

バージョン | 説明
PECL mongodb 1.11.0 | Added the MongoDB\Driver\Server::TYPE_LOAD_BALANCER constant.

目次

  • MongoDB\Driver\Server::__construct — Create a new Server (not used)
  • MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server
  • MongoDB\Driver\Server::executeCommand — Execute a database command on this server
  • MongoDB\Driver\Server::executeQuery — Execute a database query on this server
  • MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server
  • MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server
  • MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server
  • MongoDB\Driver\Server::getHost — Returns the hostname of this server
  • MongoDB\Driver\Server::getInfo — Returns an array of information describing this server
  • MongoDB\Driver\Server::getLatency — Returns the latency of this server in milliseconds
  • MongoDB\Driver\Server::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Server::getServerDescription — Returns a ServerDescription for this server
  • MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set
  • MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server
  • MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set
  • MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set
  • MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set
  • MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set
  • MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set


Create a new Server (not used)

  • ≪ MongoDB\Driver\Server
  • MongoDB\Driver\Server::executeBulkWrite ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Create a new Server (not used)

MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Create a new Server (not used)

説明

final private MongoDB\Driver\Server::__construct()

MongoDB\Driver\Server objects are created internally by MongoDB\Driver\Manager when a database connection is established and may be returned by MongoDB\Driver\Manager::getServers() and MongoDB\Driver\Manager::selectServer().

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\Driver\Manager::getServers() - Return the servers to which this manager is connected
  • MongoDB\Driver\Manager::selectServer() - Select a server matching a read preference


Execute one or more write operations on this server

  • ≪ MongoDB\Driver\Server::__construct
  • MongoDB\Driver\Server::executeCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute one or more write operations on this server

MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server

説明

final public MongoDB\Driver\Server::executeBulkWrite(string $namespace, MongoDB\Driver\BulkWrite $bulk, array|MongoDB\Driver\WriteConcern|null $options = null): MongoDB\Driver\WriteResult

Executes one or more write operations on this server.

A MongoDB\Driver\BulkWrite can be constructed with one or more write operations of varying types (e.g. updates, deletes, and inserts). The driver will attempt to send operations of the same type to the server in as few requests as possible to optimize round trips.

The default value for the "writeConcern" option will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

パラメータ

namespace (string)

A fully qualified namespace (e.g. "databaseName.collectionName").

bulk (MongoDB\Driver\BulkWrite)

The write(s) to execute.

options

options
Option Type Description
session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

戻り値

Returns MongoDB\Driver\WriteResult on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk does not contain any write operations.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if bulk has already been executed. MongoDB\Driver\BulkWrite objects may not be executed multiple times.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\BulkWriteException on any write failure (e.g. write error, failure to apply a write concern)
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors.

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\WriteConcern object.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is now thrown if bulk does not contain any write operations. Previously, a MongoDB\Driver\Exception\BulkWriteException was thrown.

注意

注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

参考

  • MongoDB\Driver\BulkWrite
  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteConcern
  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations


Execute a database command on this server

  • ≪ MongoDB\Driver\Server::executeBulkWrite
  • MongoDB\Driver\Server::executeQuery ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command on this server

MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Execute a database command on this server

説明

final public MongoDB\Driver\Server::executeCommand(string $db, MongoDB\Driver\Command $command, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor

Executes the command on this server.

This method applies no special logic to the command. The Default values for the "readPreference", "readConcern", and "writeConcern" options will be inferred from an active transaction (indicated by the "session" option). If there is no active transaction, a primary read preference will be used for server selection.

Default values will not be inferred from the connection URI. Users are therefore encouraged to use specific read and/or write command methods if possible.

注意: The "readPreference" option does not control the server to which the driver issues the operation; it will always be executed on this server object. Instead, it may be used when issuing the operation to a secondary (from a replica set connection, not standalone) or mongos node to ensure that the driver sets the wire protocol accordingly or adds the read preference to the operation, respectively.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

注意

注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
  • MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
  • MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
  • MongoDB\Driver\Manager::executeCommand() - Execute a database command


Execute a database query on this server

  • ≪ MongoDB\Driver\Server::executeCommand
  • MongoDB\Driver\Server::executeReadCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database query on this server

MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Execute a database query on this server

説明

final public MongoDB\Driver\Server::executeQuery(string $namespace, MongoDB\Driver\Query $query, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor

Executes the query on this server.

Default values for the "readPreference" option and Query's "readConcern" option will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

注意: The "readPreference" option does not control the server to which the driver issues the operation; it will always be executed on this server object. Instead, it may be used when issuing the operation to a secondary (from a replica set connection, not standalone) or mongos node to ensure that the driver sets the wire protocol accordingly or adds the read preference to the operation, respectively.

パラメータ

namespace (string)

A fully qualified namespace (e.g. "databaseName.collectionName").

query (MongoDB\Driver\Query)

The query to execute.

options

options
Option Type Description
readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | The third parameter is now an options array. For backwards compatibility, this paramater will still accept a MongoDB\Driver\ReadPreference object.

参考

  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Query
  • MongoDB\Driver\ReadPreference
  • MongoDB\Driver\Manager::executeQuery() - Execute a database query


Execute a database command that reads on this server

  • ≪ MongoDB\Driver\Server::executeQuery
  • MongoDB\Driver\Server::executeReadWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command that reads on this server

MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server

説明

final public MongoDB\Driver\Server::executeReadCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor

Executes the command on this server, irrespective of the "readPreference" option.

This method will apply logic that is specific to commands that read (e.g. » distinct). Default values for the "readPreference" and "readConcern" options will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

注意: The "readPreference" option does not control the server to which the driver issues the operation; it will always be executed on this server object. Instead, it may be used when issuing the operation to a secondary (from a replica set connection, not standalone) or mongos node to ensure that the driver sets the wire protocol accordingly or adds the read preference to the operation, respectively.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

readPreference MongoDB\Driver\ReadPreference

A read preference to use for selecting a server for the operation.

session MongoDB\Driver\Session

A session to associate with the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
  • MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
  • MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
  • MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads


Execute a database command that reads and writes on this server

  • ≪ MongoDB\Driver\Server::executeReadCommand
  • MongoDB\Driver\Server::executeWriteCommand ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command that reads and writes on this server

MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server

説明

final public MongoDB\Driver\Server::executeReadWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor

Executes the command on this server.

This method will apply logic that is specific to commands that read and write (e.g. » aggregate). Default values for the "readConcern" and "writeConcern" options will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
readConcern MongoDB\Driver\ReadConcern

A read concern to apply to the operation.

This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.

session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.

注意

注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
  • MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
  • MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
  • MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes


Execute a database command that writes on this server

  • ≪ MongoDB\Driver\Server::executeReadWriteCommand
  • MongoDB\Driver\Server::getHost ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Execute a database command that writes on this server

MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server

説明

final public MongoDB\Driver\Server::executeWriteCommand(string $db, MongoDB\Driver\Command $command, ?array $options = null): MongoDB\Driver\Cursor

Executes the command on this server.

This method will apply logic that is specific to commands that write (e.g. » drop). The default value for the "writeConcern" option will be inferred from an active transaction (indicated by the "session" option), followed by the connection URI.

注意: This method is not intended to be used to execute » insert, » update, or » delete commands. Users are encouraged to use MongoDB\Driver\Server::executeBulkWrite() for those operations.

パラメータ

db (string)

The name of the database on which to execute the command.

command (MongoDB\Driver\Command)

The command to execute.

options

options
Option Type Description
session MongoDB\Driver\Session

A session to associate with the operation.

writeConcern MongoDB\Driver\WriteConcern

A write concern to apply to the operation.

警告

If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

戻り値

Returns MongoDB\Driver\Cursor on success.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used with an associated transaction in combination with a "readConcern" or "writeConcern" option.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the "session" option is used in combination with an unacknowledged write concern.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\ConnectionException if connection to the server fails (for reasons other than authentication).
  • Throws MongoDB\Driver\Exception\AuthenticationException if authentication is needed and fails.
  • Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

変更履歴

バージョン | 説明
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the "session" option is used in combination with an unacknowledged write concern.

注意

注意: It is the caller's responsibility to ensure that the server is capable of executing the write operation. For example, executing a write operation on a secondary (excluding its "local" database) will fail.

参考

  • MongoDB\Driver\Command
  • MongoDB\Driver\Cursor
  • MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
  • MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
  • MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
  • MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes


Returns the hostname of this server

  • ≪ MongoDB\Driver\Server::executeWriteCommand
  • MongoDB\Driver\Server::getInfo ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns the hostname of this server

MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Returns the hostname of this server

説明

final public MongoDB\Driver\Server::getHost(): string

Returns the hostname of this server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Server::getHost() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getHost());

?>

上の例の出力は以下となります。

string(9) "localhost"

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
  • MongoDB\Driver\ServerDescription::getHost() - Returns the hostname of this server


Returns an array of information describing this server

  • ≪ MongoDB\Driver\Server::getHost
  • MongoDB\Driver\Server::getLatency ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns an array of information describing this server

MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Returns an array of information describing this server

説明

final public MongoDB\Driver\Server::getInfo(): array

Returns an array of information describing the server. This array is derived from the most recent » hello command response obtained through » server monitoring.

注意:

When the driver is connected to a load balancer, this method will return the backing server's » hello command response from the initial connection handshake. This is in contrast to other methods (e.g. MongoDB\Driver\Server::getType()), which will return information about the load balancer itself.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of information describing this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Server::getInfo() example

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/');

$rp = new MongoDB\Driver\ReadPreference('primary');
$server = $manager->selectServer($rp);

var_dump($server->getInfo());

?>

上の例の出力は、 たとえば以下のようになります。

array(23) {
  ["helloOk"]=>
  bool(true)
  ["topologyVersion"]=>
  array(2) {
    ["processId"]=>
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "617b6d696a3a89d2f77e6df0"
    }
    ["counter"]=>
    int(6)
  }
  ["hosts"]=>
  array(1) {
    [0]=>
    string(15) "localhost:27017"
  }
  ["setName"]=>
  string(3) "rs0"
  ["setVersion"]=>
  int(1)
  ["ismaster"]=>
  bool(true)
  ["secondary"]=>
  bool(false)
  ["primary"]=>
  string(15) "localhost:27017"
  ["me"]=>
  string(15) "localhost:27017"
  ["electionId"]=>
  object(MongoDB\BSON\ObjectId)#5 (1) {
    ["oid"]=>
    string(24) "7fffffff0000000000000001"
  }
  ["lastWrite"]=>
  array(4) {
    ["opTime"]=>
    array(2) {
      ["ts"]=>
      object(MongoDB\BSON\Timestamp)#6 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
      ["t"]=>
      int(1)
    }
    ["lastWriteDate"]=>
    object(MongoDB\BSON\UTCDateTime)#7 (1) {
      ["milliseconds"]=>
      string(13) "1635478989000"
    }
    ["majorityOpTime"]=>
    array(2) {
      ["ts"]=>
      object(MongoDB\BSON\Timestamp)#8 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
      ["t"]=>
      int(1)
    }
    ["majorityWriteDate"]=>
    object(MongoDB\BSON\UTCDateTime)#9 (1) {
      ["milliseconds"]=>
      string(13) "1635478989000"
    }
  }
  ["maxBsonObjectSize"]=>
  int(16777216)
  ["maxMessageSizeBytes"]=>
  int(48000000)
  ["maxWriteBatchSize"]=>
  int(100000)
  ["localTime"]=>
  object(MongoDB\BSON\UTCDateTime)#10 (1) {
    ["milliseconds"]=>
    string(13) "1635478992136"
  }
  ["logicalSessionTimeoutMinutes"]=>
  int(30)
  ["connectionId"]=>
  int(3)
  ["minWireVersion"]=>
  int(0)
  ["maxWireVersion"]=>
  int(13)
  ["readOnly"]=>
  bool(false)
  ["ok"]=>
  float(1)
  ["$clusterTime"]=>
  array(2) {
    ["clusterTime"]=>
    object(MongoDB\BSON\Timestamp)#11 (2) {
      ["increment"]=>
      string(1) "1"
      ["timestamp"]=>
      string(10) "1635478989"
    }
    ["signature"]=>
    array(2) {
      ["hash"]=>
      object(MongoDB\BSON\Binary)#12 (2) {
        ["data"]=>
        string(20) ""
        ["type"]=>
        int(0)
      }
      ["keyId"]=>
      int(0)
    }
  }
  ["operationTime"]=>
  object(MongoDB\BSON\Timestamp)#13 (2) {
    ["increment"]=>
    string(1) "1"
    ["timestamp"]=>
    string(10) "1635478989"
  }
}

変更履歴

バージョン | 説明
PECL mongodb 1.11.0 | When the driver is connected to a load balancer, this method returns the backing server's hello command response from the initial connection handshake.

参考

  • MongoDB\Driver\ServerDescription::getHelloResponse() - Returns the server's most recent "hello" response
  • » hello command in the MongoDB manual
  • » Server Discovery and Monitoring Specification


Returns the latency of this server in milliseconds

  • ≪ MongoDB\Driver\Server::getInfo
  • MongoDB\Driver\Server::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns the latency of this server in milliseconds

MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Returns the latency of this server in milliseconds

説明

final public MongoDB\Driver\Server::getLatency(): ?integer

Returns the latency of this server in milliseconds. This is the client's measured » round trip time of a hello command.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the latency of this server in milliseconds, or null if no latency has been measured (e.g. client is connected to a load balancer).

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.11.0 | This method will return null if no latency has been measured. In earlier versions, an integer was always returned and an unset value might be reported as -1.

例

例1 MongoDB\Driver\Server::getLatency() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getLatency());

?>

上の例の出力は、 たとえば以下のようになります。

int(592)

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
  • MongoDB\Driver\ServerDescription::getRoundTripTime() - Returns the server's round trip time in milliseconds
  • » Server Discovery and Monitoring Specification


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Server::getLatency
  • MongoDB\Driver\Server::getServerDescription ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns the port on which this server is listening

MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Server::getPort(): int

Returns the port on which this server is listening.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\Server::getPort() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");

$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY);
$server = $manager->selectServer($rp);

var_dump($server->getPort());

?>

上の例の出力は以下となります。

int(27017)

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
  • MongoDB\Driver\ServerDescription::getPort() - Returns the port on which this server is listening


Returns a ServerDescription for this server

  • ≪ MongoDB\Driver\Server::getPort
  • MongoDB\Driver\Server::getTags ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns a ServerDescription for this server

MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Returns a ServerDescription for this server

説明

final public MongoDB\Driver\Server::getServerDescription(): MongoDB\Driver\ServerDescription

Returns a MongoDB\Driver\ServerDescription for this server. This is an immutable value object that will describe the server at the time this method is called.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a MongoDB\Driver\ServerDescription for this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns an array of tags describing this server in a replica set

  • ≪ MongoDB\Driver\Server::getServerDescription
  • MongoDB\Driver\Server::getType ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns an array of tags describing this server in a replica set

MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set

説明

final public MongoDB\Driver\Server::getTags(): array

Returns an array of » tags used to describe this server in a replica set. The array will contain zero or more string key and value pairs.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of tags used to describe this server in a replica set.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server


Returns an integer denoting the type of this server

  • ≪ MongoDB\Driver\Server::getTags
  • MongoDB\Driver\Server::isArbiter ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Returns an integer denoting the type of this server

MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server

説明

final public MongoDB\Driver\Server::getType(): int

Returns an int denoting the type of this server. The value will correlate with a MongoDB\Driver\Server constant.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an int denoting the type of this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
  • MongoDB\Driver\ServerDescription::getType() - Returns a string denoting the type of this server


Checks if this server is an arbiter member of a replica set

  • ≪ MongoDB\Driver\Server::getType
  • MongoDB\Driver\Server::isHidden ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is an arbiter member of a replica set

MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set

説明

final public MongoDB\Driver\Server::isArbiter(): bool

Returns whether this server is an » arbiter member of a replica set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this server is an arbiter member of a replica set, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server


Checks if this server is a hidden member of a replica set

  • ≪ MongoDB\Driver\Server::isArbiter
  • MongoDB\Driver\Server::isPassive ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a hidden member of a replica set

MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set

説明

final public MongoDB\Driver\Server::isHidden(): bool

Returns whether this server is a » hidden member of a replica set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this server is a hidden member of a replica set, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server


Checks if this server is a passive member of a replica set

  • ≪ MongoDB\Driver\Server::isHidden
  • MongoDB\Driver\Server::isPrimary ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a passive member of a replica set

MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set

説明

final public MongoDB\Driver\Server::isPassive(): bool

Returns whether this server is a » passive member of a replica set (i.e. its priority is 0).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this server is a passive member of a replica set, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server


Checks if this server is a primary member of a replica set

  • ≪ MongoDB\Driver\Server::isPassive
  • MongoDB\Driver\Server::isSecondary ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a primary member of a replica set

MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set

説明

final public MongoDB\Driver\Server::isPrimary(): bool

Returns whether this server is a » primary member of a replica set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this server is a primary member of a replica set, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server


Checks if this server is a secondary member of a replica set

  • ≪ MongoDB\Driver\Server::isPrimary
  • MongoDB\Driver\ServerDescription ≫
  • PHP Manual
  • MongoDB\Driver\Server
  • Checks if this server is a secondary member of a replica set

MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set

説明

final public MongoDB\Driver\Server::isSecondary(): bool

Returns whether this server is a » secondary member of a replica set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if this server is a secondary member of a replica set, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server


The MongoDB\Driver\ServerDescription class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\ServerDescription class is a value object that represents a server to which the driver is connected. Instances of this class are returned by MongoDB\Driver\Server::getServerDescription() and MongoDB\Driver\Monitoring\ServerChangedEvent methods.

クラス概要

final class MongoDB\Driver\ServerDescription {
/* 定数 */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_STANDALONE = "Standalone";
const string TYPE_MONGOS = "Mongos";
const string TYPE_POSSIBLE_PRIMARY = "PossiblePrimary";
const string TYPE_RS_PRIMARY = "RSPrimary";
const string TYPE_RS_SECONDARY = "RSSecondary";
const string TYPE_RS_ARBITER = "RSArbiter";
const string TYPE_RS_OTHER = "RSOther";
const string TYPE_RS_GHOST = "RSGhost";
const string TYPE_LOAD_BALANCER = "LoadBalancer";
/* メソッド */
final public getHelloResponse(): array
final public getHost(): string
final public getLastUpdateTime(): int
final public getPort(): int
final public getRoundTripTime(): ?int
final public getType(): string
}

定義済み定数

MongoDB\Driver\ServerDescription::TYPE_UNKNOWN

Unknown server type, returned by MongoDB\Driver\ServerDescription::getType().

MongoDB\Driver\ServerDescription::TYPE_STANDALONE

Standalone server type, returned by MongoDB\Driver\ServerDescription::getType().

MongoDB\Driver\ServerDescription::TYPE_MONGOS

Mongos server type, returned by MongoDB\Driver\ServerDescription::getType().

MongoDB\Driver\ServerDescription::TYPE_POSSIBLE_PRIMARY

Replica set possible primary server type, returned by MongoDB\Driver\ServerDescription::getType().

A server may be identified as a possible primary if it has not yet been checked but another memory of the replica set thinks it is the primary.

MongoDB\Driver\ServerDescription::TYPE_RS_PRIMARY

Replica set primary server type, returned by MongoDB\Driver\ServerDescription::getType().

MongoDB\Driver\ServerDescription::TYPE_RS_SECONDARY

Replica set secondary server type, returned by MongoDB\Driver\ServerDescription::getType().

MongoDB\Driver\ServerDescription::TYPE_RS_ARBITER

Replica set arbiter server type, returned by MongoDB\Driver\ServerDescription::getType().

MongoDB\Driver\ServerDescription::TYPE_RS_OTHER

Replica set other server type, returned by MongoDB\Driver\ServerDescription::getType().

Such servers may be hidden, starting up, or recovering. They cannot be queried, but their hosts lists are useful for discovering the current replica set configuration.

MongoDB\Driver\ServerDescription::TYPE_RS_GHOST

Replica set ghost server type, returned by MongoDB\Driver\ServerDescription::getType().

Servers may be identified as such in at least three situations: briefly during server startup; in an uninitialized replica set; or when the server is shunned (i.e. removed from the replica set config). They cannot be queried, nor can their host list be used to discover the current replica set configuration; however, the client may monitor this server in hope that it transitions to a more useful state.

MongoDB\Driver\ServerDescription::TYPE_LOAD_BALANCER

Load balancer server type, returned by MongoDB\Driver\ServerDescription::getType().

目次

  • MongoDB\Driver\ServerDescription::getHelloResponse — Returns the server's most recent "hello" response
  • MongoDB\Driver\ServerDescription::getHost — Returns the hostname of this server
  • MongoDB\Driver\ServerDescription::getLastUpdateTime — Returns the server's last update time in microseconds
  • MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\ServerDescription::getRoundTripTime — Returns the server's round trip time in milliseconds
  • MongoDB\Driver\ServerDescription::getType — Returns a string denoting the type of this server


Returns the server's most recent "hello" response

  • ≪ MongoDB\Driver\ServerDescription
  • MongoDB\Driver\ServerDescription::getHost ≫
  • PHP Manual
  • MongoDB\Driver\ServerDescription
  • Returns the server's most recent "hello" response

MongoDB\Driver\ServerDescription::getHelloResponse

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Returns the server's most recent "hello" response

説明

final public MongoDB\Driver\ServerDescription::getHelloResponse(): array

Returns an array of information describing the server. This array is derived from the most recent (at the time the MongoDB\Driver\ServerDescription was constructed) » hello command response obtained through » server monitoring.

注意:

When the driver is connected to a load balancer, this method will return an empty array since load balancers are not monitored. This is in contrast to MongoDB\Driver\Server::getInfo(), which would return the backing server's » hello command response from the initial connection handshake.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of information describing this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
  • » hello command in the MongoDB manual
  • » Server Discovery and Monitoring Specification


Returns the hostname of this server

  • ≪ MongoDB\Driver\ServerDescription::getHelloResponse
  • MongoDB\Driver\ServerDescription::getLastUpdateTime ≫
  • PHP Manual
  • MongoDB\Driver\ServerDescription
  • Returns the hostname of this server

MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Returns the hostname of this server

説明

final public MongoDB\Driver\ServerDescription::getHost(): string

Returns the hostname of this server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getHost() - Returns the hostname of this server


Returns the server's last update time in microseconds

  • ≪ MongoDB\Driver\ServerDescription::getHost
  • MongoDB\Driver\ServerDescription::getPort ≫
  • PHP Manual
  • MongoDB\Driver\ServerDescription
  • Returns the server's last update time in microseconds

MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Returns the server's last update time in microseconds

説明

final public MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Returns the server's last update time in microseconds.

注意: The returned value is a monotonic timestamp, which starts at an arbitrary point. As such, it is only suitable to compare with other return values from MongoDB\Driver\ServerDescription::getLastUpdateTime().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the server's last update time in microseconds.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\ServerDescription::getLastUpdateTime
  • MongoDB\Driver\ServerDescription::getRoundTripTime ≫
  • PHP Manual
  • MongoDB\Driver\ServerDescription
  • Returns the port on which this server is listening

MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\ServerDescription::getPort(): int

Returns the port on which this server is listening.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getPort() - Returns the port on which this server is listening


Returns the server's round trip time in milliseconds

  • ≪ MongoDB\Driver\ServerDescription::getPort
  • MongoDB\Driver\ServerDescription::getType ≫
  • PHP Manual
  • MongoDB\Driver\ServerDescription
  • Returns the server's round trip time in milliseconds

MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Returns the server's round trip time in milliseconds

説明

final public MongoDB\Driver\ServerDescription::getRoundTripTime(): ?int

Returns the server's round trip time in milliseconds. This is the client's measurement of the duration of a » hello command.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the server's round trip time in milliseconds.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getLatency() - Returns the latency of this server in milliseconds


Returns a string denoting the type of this server

  • ≪ MongoDB\Driver\ServerDescription::getRoundTripTime
  • MongoDB\Driver\TopologyDescription ≫
  • PHP Manual
  • MongoDB\Driver\ServerDescription
  • Returns a string denoting the type of this server

MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Returns a string denoting the type of this server

説明

final public MongoDB\Driver\ServerDescription::getType(): string

Returns a string denoting the type of this server. The value will correlate with a MongoDB\Driver\ServerDescription constant.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string denoting the type of this server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Server::getType() - Returns an integer denoting the type of this server


The MongoDB\Driver\TopologyDescription class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\TopologyDescription class is a value object that represents a topology to which the driver is connected. Instances of this class are returned by MongoDB\Driver\Monitoring\TopologyChangedEvent methods.

クラス概要

final class MongoDB\Driver\TopologyDescription {
/* 定数 */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_SINGLE = "Single";
const string TYPE_SHARDED = "Sharded";
const string TYPE_REPLICA_SET_NO_PRIMARY = "ReplicaSetNoPrimary";
const string TYPE_REPLICA_SET_WITH_PRIMARY = "ReplicaSetWithPrimary";
const string TYPE_LOAD_BALANCED = "LoadBalanced";
/* メソッド */
final public getServers(): array
final public getType(): string
final public hasReadableServer(?MongoDB\Driver\ReadPreference $readPreference = null): bool
final public hasWritableServer(): bool
}

定義済み定数

MongoDB\Driver\TopologyDescription::TYPE_UNKNOWN

Unknown topology type, returned by MongoDB\Driver\TopologyDescription::getType().

MongoDB\Driver\TopologyDescription::TYPE_SINGLE

Single server (i.e. direct connection), returned by MongoDB\Driver\TopologyDescription::getType().

MongoDB\Driver\TopologyDescription::TYPE_SHARDED

Sharded cluster, returned by MongoDB\Driver\TopologyDescription::getType().

MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_NO_PRIMARY

Replica set with no primary server, returned by MongoDB\Driver\TopologyDescription::getType().

MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_WITH_PRIMARY

Replica set with a primary server, returned by MongoDB\Driver\TopologyDescription::getType().

MongoDB\Driver\TopologyDescription::TYPE_LOAD_BALANCED

Load balanced topology, returned by MongoDB\Driver\TopologyDescription::getType().

目次

  • MongoDB\Driver\TopologyDescription::getServers — Returns the servers in the topology
  • MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology
  • MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server
  • MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server


Returns the servers in the topology

  • ≪ MongoDB\Driver\TopologyDescription
  • MongoDB\Driver\TopologyDescription::getType ≫
  • PHP Manual
  • MongoDB\Driver\TopologyDescription
  • Returns the servers in the topology

MongoDB\Driver\TopologyDescription::getServers

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Returns the servers in the topology

説明

final public MongoDB\Driver\TopologyDescription::getServers(): array

Returns an array of MongoDB\Driver\ServerDescription objects corresponding to the known servers in the topology.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of MongoDB\Driver\ServerDescription objects corresponding to the known servers in the topology.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns a string denoting the type of this topology

  • ≪ MongoDB\Driver\TopologyDescription::getServers
  • MongoDB\Driver\TopologyDescription::hasReadableServer ≫
  • PHP Manual
  • MongoDB\Driver\TopologyDescription
  • Returns a string denoting the type of this topology

MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology

説明

final public MongoDB\Driver\TopologyDescription::getType(): string

Returns a string denoting the type of this topology. The value will correlate with a MongoDB\Driver\TopologyDescription constant.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string denoting the type of this topology.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns whether the topology has a readable server

  • ≪ MongoDB\Driver\TopologyDescription::getType
  • MongoDB\Driver\TopologyDescription::hasWritableServer ≫
  • PHP Manual
  • MongoDB\Driver\TopologyDescription
  • Returns whether the topology has a readable server

MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server

説明

final public MongoDB\Driver\TopologyDescription::hasReadableServer(?MongoDB\Driver\ReadPreference $readPreference = null): bool

Returns whether the topology has a readable server or, if readPreference is specified, a server matching the specified read preference.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns whether the topology has a readable server or, if readPreference is specified, a server matching the specified read preference.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns whether the topology has a writable server

  • ≪ MongoDB\Driver\TopologyDescription::hasReadableServer
  • MongoDB\Driver\WriteConcernError ≫
  • PHP Manual
  • MongoDB\Driver\TopologyDescription
  • Returns whether the topology has a writable server

MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server

説明

final public MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Returns whether the topology has a writable server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns whether the topology has a writable server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\WriteConcernError class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\WriteConcernError class encapsulates information about a write concern error and may be returned by MongoDB\Driver\WriteResult::getWriteConcernError().

クラス概要

final class MongoDB\Driver\WriteConcernError {
/* メソッド */
final public getCode(): int
final public getInfo(): ?object
final public getMessage(): string
}

目次

  • MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code
  • MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError
  • MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message


Returns the WriteConcernError's error code

  • ≪ MongoDB\Driver\WriteConcernError
  • MongoDB\Driver\WriteConcernError::getInfo ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcernError
  • Returns the WriteConcernError's error code

MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code

説明

final public MongoDB\Driver\WriteConcernError::getCode(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteConcernError's error code.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcernError::getCode() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
$manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
}

?>

上の例の出力は、 たとえば以下のようになります。

int(64)

参考

  • » Write Concern reference


Returns metadata document for the WriteConcernError

  • ≪ MongoDB\Driver\WriteConcernError::getCode
  • MongoDB\Driver\WriteConcernError::getMessage ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcernError
  • Returns metadata document for the WriteConcernError

MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError

説明

final public MongoDB\Driver\WriteConcernError::getInfo(): ?object

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the metadata document for the WriteConcernError, or null if no metadata is available.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcernError::getInfo() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
$manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
}

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#1 (1) {
  ["wtimeout"]=>
  bool(true)
}

参考

  • » Write Concern reference


Returns the WriteConcernError's error message

  • ≪ MongoDB\Driver\WriteConcernError::getInfo
  • MongoDB\Driver\WriteError ≫
  • PHP Manual
  • MongoDB\Driver\WriteConcernError
  • Returns the WriteConcernError's error message

MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

説明

final public MongoDB\Driver\WriteConcernError::getMessage(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteConcernError's error message.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteConcernError::getMessage() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
$manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
}

?>

上の例の出力は、 たとえば以下のようになります。

string(33) "waiting for replication timed out"

参考

  • » Write Concern reference


The MongoDB\Driver\WriteError class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\WriteError class encapsulates information about a write error and may be returned as an array element from MongoDB\Driver\WriteResult::getWriteErrors().

クラス概要

final class MongoDB\Driver\WriteError {
/* メソッド */
final public getCode(): int
final public getIndex(): int
final public getInfo(): ?object
final public getMessage(): string
}

目次

  • MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code
  • MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError
  • MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError
  • MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message


Returns the WriteError's error code

  • ≪ MongoDB\Driver\WriteError
  • MongoDB\Driver\WriteError::getIndex ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns the WriteError's error code

MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code

説明

final public MongoDB\Driver\WriteError::getCode(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteError's error code.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteError::getCode() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 1]);

try {
$manager->executeBulkWrite('db.collection', $bulk);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteErrors()[0]->getCode());
}

?>

上の例の出力は、 たとえば以下のようになります。

int(11000)


Returns the index of the write operation corresponding to this WriteError

  • ≪ MongoDB\Driver\WriteError::getCode
  • MongoDB\Driver\WriteError::getInfo ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns the index of the write operation corresponding to this WriteError

MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError

説明

final public MongoDB\Driver\WriteError::getIndex(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the index of the write operation (from MongoDB\Driver\BulkWrite) corresponding to this WriteError.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteError::getIndex() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 1]);

try {
$manager->executeBulkWrite('db.collection', $bulk);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteErrors()[0]->getIndex());
}

?>

上の例の出力は、 たとえば以下のようになります。

int(1)

参考

  • MongoDB\Driver\BulkWrite


Returns metadata document for the WriteError

  • ≪ MongoDB\Driver\WriteError::getIndex
  • MongoDB\Driver\WriteError::getMessage ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns metadata document for the WriteError

MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError

説明

final public MongoDB\Driver\WriteError::getInfo(): ?object

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the metadata document for the WriteError, or null if no metadata is available.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the WriteError's error message

  • ≪ MongoDB\Driver\WriteError::getInfo
  • MongoDB\Driver\WriteResult ≫
  • PHP Manual
  • MongoDB\Driver\WriteError
  • Returns the WriteError's error message

MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

説明

final public MongoDB\Driver\WriteError::getMessage(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the WriteError's error message.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteError::getMessage() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 1]);

try {
$manager->executeBulkWrite('db.collection', $bulk);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteErrors()[0]->getMessage());
}

?>

上の例の出力は、 たとえば以下のようになります。

string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"


The MongoDB\Driver\WriteResult class

(mongodb >=1.0.0)

はじめに

The MongoDB\Driver\WriteResult class encapsulates information about an executed MongoDB\Driver\BulkWrite and may be returned by MongoDB\Driver\Manager::executeBulkWrite().

クラス概要

final class MongoDB\Driver\WriteResult {
/* メソッド */
final public getDeletedCount(): ?int
final public getInsertedCount(): ?int
final public getMatchedCount(): ?int
final public getModifiedCount(): ?int
final public getServer(): MongoDB\Driver\Server
final public getUpsertedCount(): ?int
final public getUpsertedIds(): array
final public getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public getWriteErrors(): array
final public isAcknowledged(): bool
}

目次

  • MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted
  • MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)
  • MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update
  • MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated
  • MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result
  • MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert
  • MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents
  • MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred
  • MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred
  • MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged


Returns the number of documents deleted

  • ≪ MongoDB\Driver\WriteResult
  • MongoDB\Driver\WriteResult::getInsertedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents deleted

MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted

説明

final public MongoDB\Driver\WriteResult::getDeletedCount(): ?int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of documents deleted, or null if the write was not acknowledged.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getDeletedCount() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
$bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
$bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
$bulk->delete(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->getDeletedCount());

?>

上の例の出力は以下となります。

int(1)

参考

  • MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged


Returns the number of documents inserted (excluding upserts)

  • ≪ MongoDB\Driver\WriteResult::getDeletedCount
  • MongoDB\Driver\WriteResult::getMatchedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents inserted (excluding upserts)

MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)

説明

final public MongoDB\Driver\WriteResult::getInsertedCount(): ?int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of documents inserted (excluding upserts), or null if the write was not acknowledged.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getInsertedCount() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
$bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
$bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
$bulk->delete(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->getInsertedCount());

?>

上の例の出力は以下となります。

int(1)

参考

  • MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged


Returns the number of documents selected for update

  • ≪ MongoDB\Driver\WriteResult::getInsertedCount
  • MongoDB\Driver\WriteResult::getModifiedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents selected for update

MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update

説明

final public MongoDB\Driver\WriteResult::getMatchedCount(): ?int

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the matched count may be greater than the value returned by MongoDB\Driver\WriteResult::getModifiedCount().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of documents selected for update, or null if the write was not acknowledged.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getMatchedCount() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
$bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
$bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
$bulk->delete(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->getMatchedCount());

?>

上の例の出力は以下となります。

int(1)

参考

  • MongoDB\Driver\WriteResult::getModifiedCount() - Returns the number of existing documents updated
  • MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged


Returns the number of existing documents updated

  • ≪ MongoDB\Driver\WriteResult::getMatchedCount
  • MongoDB\Driver\WriteResult::getServer ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of existing documents updated

MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated

説明

final public MongoDB\Driver\WriteResult::getModifiedCount(): ?int

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the modified count may be less than the value returned by MongoDB\Driver\WriteResult::getMatchedCount().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of existing documents updated, or null if the write was not acknowledged.

The modified count is not available on versions of MongoDB before 2.6, which used the legacy wire protocol version (i.e. OP_UPDATE). If this is the case, the modified count will also be null.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getModifiedCount() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
$bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
$bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
$bulk->delete(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->getModifiedCount());

?>

上の例の出力は以下となります。

int(1)

参考

  • MongoDB\Driver\WriteResult::getMatchedCount() - Returns the number of documents selected for update
  • MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged


Returns the server associated with this write result

  • ≪ MongoDB\Driver\WriteResult::getModifiedCount
  • MongoDB\Driver\WriteResult::getUpsertedCount ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the server associated with this write result

MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result

説明

final public MongoDB\Driver\WriteResult::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this write result. This is the server that executed the MongoDB\Driver\BulkWrite.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server associated with this write result.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getServer() example

<?php

$manager = new MongoDB\Driver\Manager;
$server = $manager->selectServer(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_PRIMARY));

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$result = $server->executeBulkWrite('db.collection', $bulk);

var_dump($result->getServer() == $server);

?>

上の例の出力は以下となります。

bool(true)

参考

  • MongoDB\Driver\Server


Returns the number of documents inserted by an upsert

  • ≪ MongoDB\Driver\WriteResult::getServer
  • MongoDB\Driver\WriteResult::getUpsertedIds ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns the number of documents inserted by an upsert

MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert

説明

final public MongoDB\Driver\WriteResult::getUpsertedCount(): ?int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of documents inserted by an upsert.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getUpsertedCount() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
$bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
$bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
$bulk->delete(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->getUpsertedCount());

?>

上の例の出力は以下となります。

int(2)

参考

  • MongoDB\Driver\WriteResult::getUpsertedIds() - Returns an array of identifiers for upserted documents
  • MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged


Returns an array of identifiers for upserted documents

  • ≪ MongoDB\Driver\WriteResult::getUpsertedCount
  • MongoDB\Driver\WriteResult::getWriteConcernError ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns an array of identifiers for upserted documents

MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents

説明

final public MongoDB\Driver\WriteResult::getUpsertedIds(): array

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of identifiers (i.e. "_id" field values) for upserted documents. The array keys will correspond to the index of the write operation (from MongoDB\Driver\BulkWrite) responsible for the upsert.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getUpsertedIds() example

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);
$bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
$bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
$bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
$bulk->delete(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->getUpsertedIds());

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [2]=>
  object(MongoDB\BSON\ObjectId)#4 (1) {
    ["oid"]=>
    string(24) "580e62a224f2302f191b880b"
  }
  [3]=>
  object(MongoDB\BSON\ObjectId)#5 (1) {
    ["oid"]=>
    string(24) "580e62a224f2302f191b880c"
  }
}

参考

  • MongoDB\Driver\WriteResult::getUpsertedCount() - Returns the number of documents inserted by an upsert
  • MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged


Returns any write concern error that occurred

  • ≪ MongoDB\Driver\WriteResult::getUpsertedIds
  • MongoDB\Driver\WriteResult::getWriteErrors ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns any write concern error that occurred

MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred

説明

final public MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a MongoDB\Driver\WriteConcernError if a write concern error was encountered during the write operation, and null otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getWriteConcernError() example

<?php

$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

try {
$manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch(MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteConcernError());
}

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\Driver\WriteConcernError)#6 (3) {
  ["message"]=>
  string(33) "waiting for replication timed out"
  ["code"]=>
  int(64)
  ["info"]=>
  object(stdClass)#7 (1) {
    ["wtimeout"]=>
    bool(true)
  }
}

参考

  • MongoDB\Driver\WriteConcern
  • » Write Concern reference


Returns any write errors that occurred

  • ≪ MongoDB\Driver\WriteResult::getWriteConcernError
  • MongoDB\Driver\WriteResult::isAcknowledged ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns any write errors that occurred

MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred

説明

final public MongoDB\Driver\WriteResult::getWriteErrors(): array

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of MongoDB\Driver\WriteError objects for any write errors encountered during the write operation. The array will be empty if no write errors occurred.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::getWriteErrors() with a single error

<?php

$manager = new MongoDB\Driver\Manager;

/* By default, bulk write operations are executed serially in order and
* execution will stop after the first error.
*/
$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 3]);
$bulk->insert(['_id' => 4]);
$bulk->insert(['_id' => 4]);

try {
$result = $manager->executeBulkWrite('db.collection', $bulk);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteErrors());
}

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  object(MongoDB\Driver\WriteError)#5 (4) {
    ["message"]=>
    string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
    ["code"]=>
    int(11000)
    ["index"]=>
    int(2)
    ["info"]=>
    NULL
  }
}

例2 MongoDB\Driver\WriteResult::getWriteErrors() with multiple errors

<?php

$manager = new MongoDB\Driver\Manager;

/* The "ordered" option may be used to allow bulk write operations to continue
* executing after the first error is encountered.
*/
$bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 3]);
$bulk->insert(['_id' => 4]);
$bulk->insert(['_id' => 4]);

try {
$result = $manager->executeBulkWrite('db.collection', $bulk);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
var_dump($e->getWriteResult()->getWriteErrors());
}

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  object(MongoDB\Driver\WriteError)#5 (4) {
    ["message"]=>
    string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
    ["code"]=>
    int(11000)
    ["index"]=>
    int(2)
    ["info"]=>
    NULL
  }
  [1]=>
  object(MongoDB\Driver\WriteError)#6 (4) {
    ["message"]=>
    string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 4 }"
    ["code"]=>
    int(11000)
    ["index"]=>
    int(5)
    ["info"]=>
    NULL
  }
}

参考

  • MongoDB\Driver\WriteError


Returns whether the write was acknowledged

  • ≪ MongoDB\Driver\WriteResult::getWriteErrors
  • MongoDB\BSON ≫
  • PHP Manual
  • MongoDB\Driver\WriteResult
  • Returns whether the write was acknowledged

MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

説明

final public MongoDB\Driver\WriteResult::isAcknowledged(): bool

If the write is acknowledged, other count fields will be available on the MongoDB\Driver\WriteResult object.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the write was acknowledged, and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\Driver\WriteResult::isAcknowledged() with acknowledged write concern

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk);

var_dump($result->isAcknowledged());

?>

上の例の出力は以下となります。

bool(true)

例2 MongoDB\Driver\WriteResult::isAcknowledged() with unacknowledged write concern

<?php

$manager = new MongoDB\Driver\Manager;

$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1]);

$result = $manager->executeBulkWrite('db.collection', $bulk, new MongoDB\Driver\WriteConcern(0));

var_dump($result->isAcknowledged());

?>

上の例の出力は以下となります。

bool(false)

参考

  • MongoDB\Driver\WriteConcern
  • » Write Concern reference


MongoDB BSON Classes and Functions

  • 関数
    • MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value
    • MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value
    • MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value
    • MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value
    • MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value
    • MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value
  • MongoDB\BSON\Document — The MongoDB\BSON\Document class
    • MongoDB\BSON\Document::__construct — Construct a new BSON document (unused)
    • MongoDB\BSON\Document::fromBSON — Construct a new document instance from a BSON string
    • MongoDB\BSON\Document::fromJSON — Construct a new document instance from a JSON string
    • MongoDB\BSON\Document::fromPHP — Construct a new document instance from PHP data
    • MongoDB\BSON\Document::get — Returns the value of a key in the document
    • MongoDB\BSON\Document::getIterator — Returns an iterator for the BSON document
    • MongoDB\BSON\Document::has — Returns whether a key is present in the document
    • MongoDB\BSON\Document::offsetExists — Returns whether a key is present in the document
    • MongoDB\BSON\Document::offsetGet — Returns the value of a key in the document
    • MongoDB\BSON\Document::offsetSet — Implementation of ArrayAccess
    • MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess
    • MongoDB\BSON\Document::serialize — Serialize a Document
    • MongoDB\BSON\Document::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON document
    • MongoDB\BSON\Document::toPHP — Returns the PHP representation of the BSON document
    • MongoDB\BSON\Document::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON document
    • MongoDB\BSON\Document::__toString — Returns the string representation of this BSON Document
    • MongoDB\BSON\Document::unserialize — Unserialize a BSON document
  • MongoDB\BSON\PackedArray — The MongoDB\BSON\PackedArray class
    • MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)
    • MongoDB\BSON\PackedArray::fromPHP — Construct a new BSON array instance from PHP data
    • MongoDB\BSON\PackedArray::get — Returns the value of an index in the array
    • MongoDB\BSON\PackedArray::getIterator — Returns an iterator for the BSON array
    • MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array
    • MongoDB\BSON\PackedArray::offsetExists — Returns whether a index is present in the array
    • MongoDB\BSON\PackedArray::offsetGet — Returns the value of an index in the array
    • MongoDB\BSON\PackedArray::offsetSet — Implementation of ArrayAccess
    • MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess
    • MongoDB\BSON\PackedArray::serialize — Serialize a BSON array
    • MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array
    • MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array
    • MongoDB\BSON\PackedArray::unserialize — Unserialize a BSON array
  • MongoDB\BSON\Iterator — The MongoDB\BSON\Iterator class
    • MongoDB\BSON\Iterator::__construct — Construct a new BSON iterator (unused)
    • MongoDB\BSON\Iterator::current — Returns the current element
    • MongoDB\BSON\Iterator::key — Returns the key of the current element
    • MongoDB\BSON\Iterator::next — Advances the iterator to next element
    • MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element
    • MongoDB\BSON\Iterator::valid — Checks if current position is valid
  • MongoDB\BSON\Binary — The MongoDB\BSON\Binary class
    • MongoDB\BSON\Binary::__construct — Construct a new Binary
    • MongoDB\BSON\Binary::getData — Returns the Binary's data
    • MongoDB\BSON\Binary::getType — Returns the Binary's type
    • MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Binary::serialize — Serialize a Binary
    • MongoDB\BSON\Binary::__toString — Returns the Binary's data
    • MongoDB\BSON\Binary::unserialize — Unserialize a Binary
  • MongoDB\BSON\Decimal128 — The MongoDB\BSON\Decimal128 class
    • MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128
    • MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Decimal128::serialize — Serialize a Decimal128
    • MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128
    • MongoDB\BSON\Decimal128::unserialize — Unserialize a Decimal128
  • MongoDB\BSON\Javascript — The MongoDB\BSON\Javascript class
    • MongoDB\BSON\Javascript::__construct — Construct a new Javascript
    • MongoDB\BSON\Javascript::getCode — Returns the Javascript's code
    • MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document
    • MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Javascript::serialize — Serialize a Javascript
    • MongoDB\BSON\Javascript::__toString — Returns the Javascript's code
    • MongoDB\BSON\Javascript::unserialize — Unserialize a Javascript
  • MongoDB\BSON\MaxKey — The MongoDB\BSON\MaxKey class
    • MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey
    • MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\MaxKey::serialize — Serialize a MaxKey
    • MongoDB\BSON\MaxKey::unserialize — Unserialize a MaxKey
  • MongoDB\BSON\MinKey — The MongoDB\BSON\MinKey class
    • MongoDB\BSON\MinKey::__construct — Construct a new MinKey
    • MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\MinKey::serialize — Serialize a MinKey
    • MongoDB\BSON\MinKey::unserialize — Unserialize a MinKey
  • MongoDB\BSON\ObjectId — The MongoDB\BSON\ObjectId class
    • MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId
    • MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId
    • MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\ObjectId::serialize — Serialize an ObjectId
    • MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId
    • MongoDB\BSON\ObjectId::unserialize — Unserialize an ObjectId
  • MongoDB\BSON\Regex — The MongoDB\BSON\Regex class
    • MongoDB\BSON\Regex::__construct — Construct a new Regex
    • MongoDB\BSON\Regex::getFlags — Returns the Regex's flags
    • MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern
    • MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Regex::serialize — Serialize a Regex
    • MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex
    • MongoDB\BSON\Regex::unserialize — Unserialize a Regex
  • MongoDB\BSON\Timestamp — The MongoDB\BSON\Timestamp class
    • MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp
    • MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp
    • MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp
    • MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Timestamp::serialize — Serialize a Timestamp
    • MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp
    • MongoDB\BSON\Timestamp::unserialize — Unserialize a Timestamp
  • MongoDB\BSON\UTCDateTime — The MongoDB\BSON\UTCDateTime class
    • MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime
    • MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\UTCDateTime::serialize — Serialize a UTCDateTime
    • MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::unserialize — Unserialize a UTCDateTime
  • MongoDB\BSON\Type — The MongoDB\BSON\Type interface
  • MongoDB\BSON\Persistable — The MongoDB\BSON\Persistable interface
    • MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON
  • MongoDB\BSON\Serializable — The MongoDB\BSON\Serializable interface
    • MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON
  • MongoDB\BSON\Unserializable — The MongoDB\BSON\Unserializable interface
    • MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document
  • MongoDB\BSON\BinaryInterface — The MongoDB\BSON\BinaryInterface interface
    • MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data
    • MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type
    • MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data
  • MongoDB\BSON\Decimal128Interface — The MongoDB\BSON\Decimal128Interface interface
    • MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface
  • MongoDB\BSON\JavascriptInterface — The MongoDB\BSON\JavascriptInterface interface
    • MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code
    • MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document
    • MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code
  • MongoDB\BSON\MaxKeyInterface — The MongoDB\BSON\MaxKeyInterface interface
  • MongoDB\BSON\MinKeyInterface — The MongoDB\BSON\MinKeyInterface interface
  • MongoDB\BSON\ObjectIdInterface — The MongoDB\BSON\ObjectIdInterface interface
    • MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface
    • MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface
  • MongoDB\BSON\RegexInterface — The MongoDB\BSON\RegexInterface interface
    • MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags
    • MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern
    • MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface
  • MongoDB\BSON\TimestampInterface — The MongoDB\BSON\TimestampInterface interface
    • MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface
    • MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface
    • MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface
  • MongoDB\BSON\UTCDateTimeInterface — The MongoDB\BSON\UTCDateTimeInterface interface
    • MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface
    • MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface
  • MongoDB\BSON\DBPointer — The MongoDB\BSON\DBPointer class (deprecated)
    • MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)
    • MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\DBPointer::serialize — Serialize a DBPointer
    • MongoDB\BSON\DBPointer::__toString — Returns an empty string
    • MongoDB\BSON\DBPointer::unserialize — Unserialize a DBPointer
  • MongoDB\BSON\Int64 — The MongoDB\BSON\Int64 class
    • MongoDB\BSON\Int64::__construct — Construct a new Int64
    • MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Int64::serialize — Serialize an Int64
    • MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64
    • MongoDB\BSON\Int64::unserialize — Unserialize an Int64
  • MongoDB\BSON\Symbol — The MongoDB\BSON\Symbol class (deprecated)
    • MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)
    • MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Symbol::serialize — Serialize a Symbol
    • MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string
    • MongoDB\BSON\Symbol::unserialize — Unserialize a Symbol
  • MongoDB\BSON\Undefined — The MongoDB\BSON\Undefined class (deprecated)
    • MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)
    • MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON
    • MongoDB\BSON\Undefined::serialize — Serialize a Undefined
    • MongoDB\BSON\Undefined::__toString — Returns an empty string
    • MongoDB\BSON\Undefined::unserialize — Unserialize a Undefined


関数

目次

  • MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value
  • MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value
  • MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value
  • MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value


Returns the BSON representation of a JSON value

  • ≪ 関数
  • MongoDB\BSON\fromPHP ≫
  • PHP Manual
  • 関数
  • Returns the BSON representation of a JSON value

MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value

説明

MongoDB\BSON\fromJSON(string $json): string

Converts an » extended JSON string to its BSON representation.

パラメータ

json (string)

JSON value to be converted.

戻り値

The serialized BSON document as a binary string.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to BSON (e.g. due to a syntax error).

例

例1 MongoDB\BSON\fromJSON() example

<?php

$json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
$bson = MongoDB\BSON\fromJSON($json);
$value = MongoDB\BSON\toPHP($bson);
var_dump($value);

?>

上の例の出力は以下となります。

object(stdClass)#2 (1) {
  ["_id"]=>
  object(MongoDB\BSON\ObjectId)#1 (1) {
    ["oid"]=>
    string(24) "563143b280d2387c91807965"
  }
}

参考

  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • MongoDB\BSON\toJSON() - Returns the Legacy Extended JSON representation of a BSON value
  • » MongoDB Extended JSON
  • » MongoDB BSON


Returns the BSON representation of a PHP value

  • ≪ MongoDB\BSON\fromJSON
  • MongoDB\BSON\toCanonicalExtendedJSON ≫
  • PHP Manual
  • 関数
  • Returns the BSON representation of a PHP value

MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value

説明

MongoDB\BSON\fromPHP(array|object $value): string

Serializes a PHP array or object (e.g. document) to its » BSON representation. The returned binary string will describe a BSON document.

パラメータ

value (array|object)

PHP value to be serialized.

戻り値

The serialized BSON document as a binary string.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the PHP value cannot be converted to BSON. Possible reasons include, but are not limited to, encountering an unexpected MongoDB\BSON\Type instance or MongoDB\BSON\Serializable::bsonSerialize() failing to return an array or stdClass.

例

例1 MongoDB\BSON\fromPHP() example

<?php

$bson = MongoDB\BSON\fromPHP(['foo' => 1]);
echo bin2hex($bson), "\n";

?>

上の例の出力は以下となります。

0e00000010666f6f000100000000cat

参考

  • MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
  • MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
  • » MongoDB BSON
  • Persisting Data


Returns the Canonical Extended JSON representation of a BSON value

  • ≪ MongoDB\BSON\fromPHP
  • MongoDB\BSON\toJSON ≫
  • PHP Manual
  • 関数
  • Returns the Canonical Extended JSON representation of a BSON value

MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value

説明

MongoDB\BSON\toCanonicalExtendedJSON(string $bson): string

Converts a BSON string to its » Canonical Extended JSON representation. The canonical format prefers type fidelity at the expense of concise output and is most suited for producing output that can be converted back to BSON without any loss of type information (e.g. numeric types will remain differentiated).

パラメータ

bson (string)

BSON value to be converted.

戻り値

The converted JSON value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

例

例1 MongoDB\BSON\toCanonicalExtendedJSON() example

<?php

$documents = [
[ 'null' => null ],
[ 'boolean' => true ],
[ 'string' => 'foo' ],
[ 'int32' => 123 ],
[ 'int64' => 4294967295 ],
[ 'double' => 1.0, ],
[ 'nan' => NAN ],
[ 'pos_inf' => INF ],
[ 'neg_inf' => -INF ],
[ 'array' => [ 'foo', 'bar' ]],
[ 'document' => [ 'foo' => 'bar' ]],
[ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
[ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
[ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
[ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
[ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
[ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
[ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
[ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
[ 'minkey' => new MongoDB\BSON\MinKey ],
[ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
$bson = MongoDB\BSON\fromPHP($document);
echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : { "$numberInt" : "123" } }
{ "int64" : { "$numberLong" : "4294967295"} }
{ "double" : { "$numberDouble" : "1.0" } }
{ "nan" : { "$numberDouble" : "NaN" } }
{ "pos_inf" : { "$numberDouble" : "Infinity" } }
{ "neg_inf" : { "$numberDouble" : "-Infinity" } }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
{ "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • MongoDB\BSON\Document::toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of the BSON document
  • MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » Extended JSON Specification
  • » MongoDB BSON


Returns the Legacy Extended JSON representation of a BSON value

  • ≪ MongoDB\BSON\toCanonicalExtendedJSON
  • MongoDB\BSON\toPHP ≫
  • PHP Manual
  • 関数
  • Returns the Legacy Extended JSON representation of a BSON value

MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value

説明

MongoDB\BSON\toJSON(string $bson): string

Converts a BSON string to its » Legacy Extended JSON representation.

注意: There exist several JSON formats for representing BSON. This function implements the "strict mode" defined in » MongoDB Extended JSON, which has been superseded by the canonical and relaxed formats defined in the » Extended JSON Specification and implemented by MongoDB\BSON\toCanonicalExtendedJSON() and MongoDB\BSON\toRelaxedExtendedJSON(), respectively.

警告

» JSON does not support NAN and INF and MongoDB's Legacy Extended JSON format does not define an alternative representation for these values (» libbson will output nan and inf literals, which may not be parsed as valid JSON). If you are working with BSON that may contain non-finite numbers, please use MongoDB\BSON\toCanonicalExtendedJSON() or MongoDB\BSON\toRelaxedExtendedJSON().

パラメータ

bson (string)

BSON value to be converted.

戻り値

The converted JSON value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

例

例1 MongoDB\BSON\toJSON() example

<?php

$documents = [
[ 'null' => null ],
[ 'boolean' => true ],
[ 'string' => 'foo' ],
[ 'int32' => 123 ],
[ 'int64' => 4294967295 ],
[ 'double' => 1.0, ],
[ 'nan' => NAN ],
[ 'pos_inf' => INF ],
[ 'neg_inf' => -INF ],
[ 'array' => [ 'foo', 'bar' ]],
[ 'document' => [ 'foo' => 'bar' ]],
[ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
[ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
[ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
[ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
[ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
[ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
[ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
[ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
[ 'minkey' => new MongoDB\BSON\MinKey ],
[ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
$bson = MongoDB\BSON\fromPHP($document);
echo MongoDB\BSON\toJSON($bson), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : 123 }
{ "int64" : 4294967295 }
{ "double" : 1.0 }
{ "nan" : nan }
{ "pos_inf" : inf }
{ "neg_inf" : -inf }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
{ "date" : { "$date" : 1445990400000 } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regex" : "pattern", "$options" : "i" } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON
  • » MongoDB BSON


Returns the PHP representation of a BSON value

  • ≪ MongoDB\BSON\toJSON
  • MongoDB\BSON\toRelaxedExtendedJSON ≫
  • PHP Manual
  • 関数
  • Returns the PHP representation of a BSON value

MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value

説明

MongoDB\BSON\toPHP(string $bson, array $typeMap = array()): array|object

Unserializes a BSON document (i.e. binary string) to its PHP representation. The typeMap paramater may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

警告

BSON documents can technically contain duplicate keys because documents are stored as a list of key-value pairs; however, applications should refrain from generating documents with duplicate keys as server and driver behavior may be undefined. Since PHP objects and arrays cannot have duplicate keys, data could also be lost when decoding a BSON document with duplicate keys.

パラメータ

bson (string)

BSON value to be unserialized.

typeMap (array)

Type map configuration.

戻り値

The unserialized PHP value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

変更履歴

バージョン | 説明
PECL mongodb 1.4.0 | If the input contains an unsupported, deprecated BSON type, the extension will now no longer log a warning to the debug log, but instead will create an object representing this type.
PECL mongodb 1.3.2 | MongoDB\Driver\Exception\UnexpectedValueException is no longer thrown if the input contains an unsupported, deprecated BSON type. Such types will be ignored (as they were in versions before 1.3.0), although the extension will now log a warning to the debug log (see: mongodb.debug).
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\UnexpectedValueException is thrown if the input contains an unsupported, deprecated BSON type. Previously, such types were ignored.

例

例1 MongoDB\BSON\toPHP() example

<?php

$bson = hex2bin('0e00000010666f6f000100000000');
$value = MongoDB\BSON\toPHP($bson);
var_dump($value);

?>

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["foo"]=>
  int(1)
}

参考

  • MongoDB\BSON\Document::toPHP() - Returns the PHP representation of the BSON document
  • MongoDB\BSON\fromPHP() - Returns the BSON representation of a PHP value
  • » MongoDB BSON
  • Persisting Data


Returns the Relaxed Extended JSON representation of a BSON value

  • ≪ MongoDB\BSON\toPHP
  • MongoDB\BSON\Document ≫
  • PHP Manual
  • 関数
  • Returns the Relaxed Extended JSON representation of a BSON value

MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value

説明

MongoDB\BSON\toRelaxedExtendedJSON(string $bson): string

Converts a BSON string to its » Relaxed Extended JSON representation. The relaxed format prefers use of JSON type primitives at the expense of type fidelity and is most suited for producing output that can be easily consumed by web APIs and humans.

パラメータ

bson (string)

BSON value to be converted.

戻り値

The converted JSON value.

エラー / 例外

  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the input did not contain exactly one BSON document. Possible reasons include, but are not limited to, invalid BSON, extra data (after reading one BSON document), or an unexpected » libbson error.

例

例1 MongoDB\BSON\toRelaxedExtendedJSON() example

<?php

$documents = [
[ 'null' => null ],
[ 'boolean' => true ],
[ 'string' => 'foo' ],
[ 'int32' => 123 ],
[ 'int64' => 4294967295 ],
[ 'double' => 1.0, ],
[ 'nan' => NAN ],
[ 'pos_inf' => INF ],
[ 'neg_inf' => -INF ],
[ 'array' => [ 'foo', 'bar' ]],
[ 'document' => [ 'foo' => 'bar' ]],
[ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
[ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
[ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
[ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
[ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
[ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
[ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
[ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
[ 'minkey' => new MongoDB\BSON\MinKey ],
[ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
$bson = MongoDB\BSON\fromPHP($document);
echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : 123 }
{ "int64" : 4294967295 }
{ "double" : 1.0 }
{ "nan" : { "$numberDouble" : "NaN" } }
{ "pos_inf" : { "$numberDouble" : "Infinity" } }
{ "neg_inf" : { "$numberDouble" : "-Infinity" } }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
{ "date" : { "$date" : "2015-10-28T00:00:00Z" } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • MongoDB\BSON\Document::toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of the BSON document
  • MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • » Extended JSON
  • » MongoDB BSON


The MongoDB\BSON\Document class

(mongodb >=1.16.0)

はじめに

Represents a BSON document. This class is used when reading data as raw BSON and cannot be modified.

クラス概要

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate, Serializable {
/* メソッド */
final private __construct()
final static public fromBSON(string $bson): MongoDB\BSON\Document
final static public fromJSON(string $json): MongoDB\BSON\Document
final static public fromPHP(object|array $value): MongoDB\BSON\Document
final public get(string $key): mixed
final public getIterator(): MongoDB\BSON\Iterator
final public has(string $key): bool
final public offsetExists(mixed $key): bool
final public offsetGet(mixed $key): mixed
final public offsetSet(mixed $key, mixed $value): void
final public offsetUnset(mixed $key): void
final public serialize(): string
final public toCanonicalExtendedJSON(): string
final public toPHP(?array $typeMap = null): array|object
final public toRelaxedExtendedJSON(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.17.0 | Implements MongoDB\BSON\Type.

目次

  • MongoDB\BSON\Document::__construct — Construct a new BSON document (unused)
  • MongoDB\BSON\Document::fromBSON — Construct a new document instance from a BSON string
  • MongoDB\BSON\Document::fromJSON — Construct a new document instance from a JSON string
  • MongoDB\BSON\Document::fromPHP — Construct a new document instance from PHP data
  • MongoDB\BSON\Document::get — Returns the value of a key in the document
  • MongoDB\BSON\Document::getIterator — Returns an iterator for the BSON document
  • MongoDB\BSON\Document::has — Returns whether a key is present in the document
  • MongoDB\BSON\Document::offsetExists — Returns whether a key is present in the document
  • MongoDB\BSON\Document::offsetGet — Returns the value of a key in the document
  • MongoDB\BSON\Document::offsetSet — Implementation of ArrayAccess
  • MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess
  • MongoDB\BSON\Document::serialize — Serialize a Document
  • MongoDB\BSON\Document::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON document
  • MongoDB\BSON\Document::toPHP — Returns the PHP representation of the BSON document
  • MongoDB\BSON\Document::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON document
  • MongoDB\BSON\Document::__toString — Returns the string representation of this BSON Document
  • MongoDB\BSON\Document::unserialize — Unserialize a BSON document


Construct a new BSON document (unused)

  • ≪ MongoDB\BSON\Document
  • MongoDB\BSON\Document::fromBSON ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Construct a new BSON document (unused)

MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Construct a new BSON document (unused)

説明

final private MongoDB\BSON\Document::__construct()

MongoDB\BSON\Document objects are created through static factory methods and cannot be instantiated directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
  • MongoDB\BSON\Document::fromBSON() - Construct a new document instance from a BSON string
  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • » BSON Types


Construct a new document instance from a BSON string

  • ≪ MongoDB\BSON\Document::__construct
  • MongoDB\BSON\Document::fromJSON ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Construct a new document instance from a BSON string

MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Construct a new document instance from a BSON string

説明

final static public MongoDB\BSON\Document::fromBSON(string $bson): MongoDB\BSON\Document

パラメータ

bson (string)

A string containing a document in BSON format.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if bson is an invalid BSON string or contains more than a single document.

参考

  • MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • » BSON Types


Construct a new document instance from a JSON string

  • ≪ MongoDB\BSON\Document::fromBSON
  • MongoDB\BSON\Document::fromPHP ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Construct a new document instance from a JSON string

MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Construct a new document instance from a JSON string

説明

final static public MongoDB\BSON\Document::fromJSON(string $json): MongoDB\BSON\Document

Converts an » extended JSON string to its BSON representation.

パラメータ

json (string)

JSON value to be converted.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if json is not a valid document.

参考

  • MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
  • MongoDB\BSON\Document::fromBSON() - Construct a new document instance from a BSON string
  • MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
  • » MongoDB Extended JSON
  • » BSON Types


Construct a new document instance from PHP data

  • ≪ MongoDB\BSON\Document::fromJSON
  • MongoDB\BSON\Document::get ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Construct a new document instance from PHP data

MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Construct a new document instance from PHP data

説明

final static public MongoDB\BSON\Document::fromPHP(object|array $value): MongoDB\BSON\Document

パラメータ

value (object|array)

A PHP object or array containing the document. When passing an array with numeric keys, the numeric values are converted to strings and used as document keys.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Document::fromBSON() - Construct a new document instance from a BSON string
  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • MongoDB\BSON\fromPHP() - Returns the BSON representation of a PHP value
  • » BSON Types


Returns the value of a key in the document

  • ≪ MongoDB\BSON\Document::fromPHP
  • MongoDB\BSON\Document::getIterator ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns the value of a key in the document

MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Returns the value of a key in the document

説明

final public MongoDB\BSON\Document::get(string $key): mixed

パラメータ

key (string)

The key to retrieve from the document.

戻り値

Returns the value associated with the given key. If the key is not present in the document, an exception is thrown.

注意: When encountering a value encoded as 64-bit integer in the BSON document, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the key is not present in the document.

参考

  • MongoDB\BSON\Document::has() - Returns whether a key is present in the document
  • » BSON Types


Returns an iterator for the BSON document

  • ≪ MongoDB\BSON\Document::get
  • MongoDB\BSON\Document::has ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns an iterator for the BSON document

MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Returns an iterator for the BSON document

説明

final public MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all keys in the document.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the BSON iterator could not be initialized.

参考

  • » BSON Types


Returns whether a key is present in the document

  • ≪ MongoDB\BSON\Document::getIterator
  • MongoDB\BSON\Document::offsetExists ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns whether a key is present in the document

MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Returns whether a key is present in the document

説明

final public MongoDB\BSON\Document::has(string $key): bool

パラメータ

key (string)

The key to look for in the document.

戻り値

Returns true if the key is present in the document and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Document::get() - Returns the value of a key in the document
  • » BSON Types


Returns whether a key is present in the document

  • ≪ MongoDB\BSON\Document::has
  • MongoDB\BSON\Document::offsetGet ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns whether a key is present in the document

MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Returns whether a key is present in the document

説明

final public MongoDB\BSON\Document::offsetExists(mixed $key): bool

パラメータ

key

The key to look for in the document.

戻り値

Returns true if the key is present in the document and false otherwise.

参考

  • ArrayAccess::offsetExists() - オフセットが存在するかどうか
  • MongoDB\BSON\Document::has() - Returns whether a key is present in the document


Returns the value of a key in the document

  • ≪ MongoDB\BSON\Document::offsetExists
  • MongoDB\BSON\Document::offsetSet ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns the value of a key in the document

MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Returns the value of a key in the document

説明

final public MongoDB\BSON\Document::offsetGet(mixed $key): mixed

パラメータ

key

The key to retrieve from the document.

戻り値

Returns the value associated with the given key. If the key is not present in the document, an exception is thrown.

注意: When encountering a value encoded as 64-bit integer in the BSON document, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the key is not present in the document.

参考

  • ArrayAccess::offsetGet() - オフセットを取得する
  • MongoDB\BSON\Document::get() - Returns the value of a key in the document


Implementation of ArrayAccess

  • ≪ MongoDB\BSON\Document::offsetGet
  • MongoDB\BSON\Document::offsetUnset ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Implementation of ArrayAccess

MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Implementation of ArrayAccess

説明

final public MongoDB\BSON\Document::offsetSet(mixed $key, mixed $value): void

Sets the value at the specified key to value.

パラメータ

key

The index being set.

value

The new value for the key.

戻り値

値を返しません。

エラー / 例外

  • Always throws a MongoDB\Driver\Exception\LogicException.


Implementation of ArrayAccess

  • ≪ MongoDB\BSON\Document::offsetSet
  • MongoDB\BSON\Document::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Implementation of ArrayAccess

MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess

説明

final public MongoDB\BSON\Document::offsetUnset(mixed $key): void

Unsets the value at the specified index.

パラメータ

key

The index being unset.

戻り値

値を返しません。

エラー / 例外

  • Always throws a MongoDB\Driver\Exception\LogicException.


Serialize a Document

  • ≪ MongoDB\BSON\Document::offsetUnset
  • MongoDB\BSON\Document::toCanonicalExtendedJSON ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Serialize a Document

MongoDB\BSON\Document::serialize

(mongodb >=1.16.0)

MongoDB\BSON\Document::serialize — Serialize a Document

説明

final public MongoDB\BSON\Document::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Document.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Document::unserialize() - Unserialize a BSON document
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the Canonical Extended JSON representation of the BSON document

  • ≪ MongoDB\BSON\Document::serialize
  • MongoDB\BSON\Document::toPHP ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns the Canonical Extended JSON representation of the BSON document

MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON document

説明

final public MongoDB\BSON\Document::toCanonicalExtendedJSON(): string

Converts the BSON document to its » Canonical Extended JSON representation. The canonical format prefers type fidelity at the expense of concise output and is most suited for producing output that can be converted back to BSON without any loss of type information (e.g. numeric types will remain differentiated).

パラメータ

この関数にはパラメータはありません。

例

例1 MongoDB\BSON\Document::toCanonicalExtendedJSON() example

<?php

$documents = [
[ 'null' => null ],
[ 'boolean' => true ],
[ 'string' => 'foo' ],
[ 'int32' => 123 ],
[ 'int64' => 4294967295 ],
[ 'double' => 1.0, ],
[ 'nan' => NAN ],
[ 'pos_inf' => INF ],
[ 'neg_inf' => -INF ],
[ 'array' => [ 'foo', 'bar' ]],
[ 'document' => [ 'foo' => 'bar' ]],
[ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
[ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
[ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
[ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
[ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
[ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
[ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
[ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
[ 'minkey' => new MongoDB\BSON\MinKey ],
[ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
$bson = MongoDB\BSON\Document::fromPHP($document);
echo $bson->toCanonicalExtendedJSON(), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : { "$numberInt" : "123" } }
{ "int64" : { "$numberLong" : "4294967295"} }
{ "double" : { "$numberDouble" : "1.0" } }
{ "nan" : { "$numberDouble" : "NaN" } }
{ "pos_inf" : { "$numberDouble" : "Infinity" } }
{ "neg_inf" : { "$numberDouble" : "-Infinity" } }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
{ "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • MongoDB\BSON\Document::toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of the BSON document
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • » Extended JSON Specification
  • » BSON Types


Returns the PHP representation of the BSON document

  • ≪ MongoDB\BSON\Document::toCanonicalExtendedJSON
  • MongoDB\BSON\Document::toRelaxedExtendedJSON ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns the PHP representation of the BSON document

MongoDB\BSON\Document::toPHP

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

MongoDB\BSON\Document::toPHP — Returns the PHP representation of the BSON document

説明

final public MongoDB\BSON\Document::toPHP(?array $typeMap = null): array|object

Unserializes the BSON document to its PHP representation. The typeMap paramater may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

警告

BSON documents can technically contain duplicate keys because documents are stored as a list of key-value pairs; however, applications should refrain from generating documents with duplicate keys as server and driver behavior may be undefined. Since PHP objects and arrays cannot have duplicate keys, data could also be lost when decoding a BSON document with duplicate keys.

パラメータ

typeMap (array)

Type map configuration.

戻り値

The decoded PHP value.

注意: When encountering a value encoded as 64-bit integer in the BSON document, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

参考

  • MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
  • » BSON Types


Returns the Relaxed Extended JSON representation of the BSON document

  • ≪ MongoDB\BSON\Document::toPHP
  • MongoDB\BSON\Document::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns the Relaxed Extended JSON representation of the BSON document

MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON document

説明

final public MongoDB\BSON\Document::toRelaxedExtendedJSON(): string

Converts the BSON document to its » Relaxed Extended JSON representation. The relaxed format prefers use of JSON type primitives at the expense of type fidelity and is most suited for producing output that can be easily consumed by web APIs and humans.

パラメータ

この関数にはパラメータはありません。

例

例1 MongoDB\BSON\Document::toRelaxedExtendedJSON() example

<?php

$documents = [
[ 'null' => null ],
[ 'boolean' => true ],
[ 'string' => 'foo' ],
[ 'int32' => 123 ],
[ 'int64' => 4294967295 ],
[ 'double' => 1.0, ],
[ 'nan' => NAN ],
[ 'pos_inf' => INF ],
[ 'neg_inf' => -INF ],
[ 'array' => [ 'foo', 'bar' ]],
[ 'document' => [ 'foo' => 'bar' ]],
[ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
[ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
[ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
[ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
[ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
[ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
[ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
[ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
[ 'minkey' => new MongoDB\BSON\MinKey ],
[ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
$bson = MongoDB\BSON\Document::fromPHP($document);
echo $bson->toRelaxedExtendedJSON(), "\n";
}

?>

上の例の出力は以下となります。

{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : 123 }
{ "int64" : 4294967295 }
{ "double" : 1.0 }
{ "nan" : { "$numberDouble" : "NaN" } }
{ "pos_inf" : { "$numberDouble" : "Infinity" } }
{ "neg_inf" : { "$numberDouble" : "-Infinity" } }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
{ "date" : { "$date" : "2015-10-28T00:00:00Z" } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }

参考

  • MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
  • MongoDB\BSON\Document::toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of the BSON document
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » Extended JSON Specification
  • » BSON Types


Returns the string representation of this BSON Document

  • ≪ MongoDB\BSON\Document::toRelaxedExtendedJSON
  • MongoDB\BSON\Document::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Returns the string representation of this BSON Document

MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Returns the string representation of this BSON Document

説明

final public MongoDB\BSON\Document::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this document as BSON.

参考

  • » BSON Types


Unserialize a BSON document

  • ≪ MongoDB\BSON\Document::__toString
  • MongoDB\BSON\PackedArray ≫
  • PHP Manual
  • MongoDB\BSON\Document
  • Unserialize a BSON document

MongoDB\BSON\Document::unserialize

(mongodb >=1.16.0)

MongoDB\BSON\Document::unserialize — Unserialize a BSON document

説明

final public MongoDB\BSON\Document::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Document.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. data was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Document::serialize() - Serialize a Document
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\PackedArray class

(mongodb >=1.16.0)

はじめに

Represents a BSON array. This class is used when reading data as raw BSON and cannot be modified.

クラス概要

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate, Serializable {
/* メソッド */
final private __construct()
final static public fromPHP(array $value): MongoDB\BSON\PackedArray
final public get(int $key): mixed
final public getIterator(): MongoDB\BSON\Iterator
final public has(int $index): bool
final public offsetExists(mixed $key): bool
final public offsetGet(mixed $key): mixed
final public offsetSet(mixed $key, mixed $value): void
final public offsetUnset(mixed $key): void
final public serialize(): string
final public toPHP(?array $typeMap = null): array|object
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.17.0 | Implements MongoDB\BSON\Type.
PECL mongodb 1.17.0 | MongoDB\BSON\PackedArray cannot be serialized in contexts where a BSON document is expected. In earlier versions, the BSON array would have been converted to a document.

目次

  • MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)
  • MongoDB\BSON\PackedArray::fromPHP — Construct a new BSON array instance from PHP data
  • MongoDB\BSON\PackedArray::get — Returns the value of an index in the array
  • MongoDB\BSON\PackedArray::getIterator — Returns an iterator for the BSON array
  • MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array
  • MongoDB\BSON\PackedArray::offsetExists — Returns whether a index is present in the array
  • MongoDB\BSON\PackedArray::offsetGet — Returns the value of an index in the array
  • MongoDB\BSON\PackedArray::offsetSet — Implementation of ArrayAccess
  • MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess
  • MongoDB\BSON\PackedArray::serialize — Serialize a BSON array
  • MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array
  • MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array
  • MongoDB\BSON\PackedArray::unserialize — Unserialize a BSON array


Construct a new BSON array (unused)

  • ≪ MongoDB\BSON\PackedArray
  • MongoDB\BSON\PackedArray::fromPHP ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Construct a new BSON array (unused)

MongoDB\BSON\PackedArray::__construct

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)

説明

final private MongoDB\BSON\PackedArray::__construct()

MongoDB\BSON\PackedArray objects are created through static factory methods and cannot be instantiated directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\BSON\PackedArray::fromPHP() - Construct a new BSON array instance from PHP data
  • » BSON Types


Construct a new BSON array instance from PHP data

  • ≪ MongoDB\BSON\PackedArray::__construct
  • MongoDB\BSON\PackedArray::get ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Construct a new BSON array instance from PHP data

MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Construct a new BSON array instance from PHP data

説明

final static public MongoDB\BSON\PackedArray::fromPHP(array $value): MongoDB\BSON\PackedArray

パラメータ

value (array)

The PHP array to convert to a BSON array. The array must be a list (i.e. have sequential numeric keys starting with 0).

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the given array is not a list (i.e. has sequential numeric keys starting with 0).

参考

  • MongoDB\BSON\fromPHP() - Returns the BSON representation of a PHP value
  • » BSON Types


Returns the value of an index in the array

  • ≪ MongoDB\BSON\PackedArray::fromPHP
  • MongoDB\BSON\PackedArray::getIterator ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns the value of an index in the array

MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Returns the value of an index in the array

説明

final public MongoDB\BSON\PackedArray::get(int $key): mixed

パラメータ

key (int)

The index to retrieve from the array.

戻り値

Returns the value associated with the given index. If the index is not present in the array, an exception is thrown.

注意: When encountering a value encoded as 64-bit integer in the BSON array, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the index is not present in the array.

参考

  • MongoDB\BSON\PackedArray::has() - Returns whether a index is present in the array
  • » BSON Types


Returns an iterator for the BSON array

  • ≪ MongoDB\BSON\PackedArray::get
  • MongoDB\BSON\PackedArray::has ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns an iterator for the BSON array

MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Returns an iterator for the BSON array

説明

final public MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all indexes in the array.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the BSON iterator could not be initialized.

参考

  • » BSON Types


Returns whether a index is present in the array

  • ≪ MongoDB\BSON\PackedArray::getIterator
  • MongoDB\BSON\PackedArray::offsetExists ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns whether a index is present in the array

MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array

説明

final public MongoDB\BSON\PackedArray::has(int $index): bool

パラメータ

index (int)

The index to look for in the array.

戻り値

Returns true if the index is present in the array and false otherwise.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\PackedArray::get() - Returns the value of an index in the array
  • » BSON Types


Returns whether a index is present in the array

  • ≪ MongoDB\BSON\PackedArray::has
  • MongoDB\BSON\PackedArray::offsetGet ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns whether a index is present in the array

MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Returns whether a index is present in the array

説明

final public MongoDB\BSON\PackedArray::offsetExists(mixed $key): bool

パラメータ

key

The index to look for in the array.

戻り値

Returns true if the index is present in the array and false otherwise.

参考

  • ArrayAccess::offsetExists() - オフセットが存在するかどうか
  • MongoDB\BSON\PackedArray::has() - Returns whether a index is present in the array


Returns the value of an index in the array

  • ≪ MongoDB\BSON\PackedArray::offsetExists
  • MongoDB\BSON\PackedArray::offsetSet ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns the value of an index in the array

MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Returns the value of an index in the array

説明

final public MongoDB\BSON\PackedArray::offsetGet(mixed $key): mixed

パラメータ

key

The index to retrieve from the array. Only int is supported.

戻り値

Returns the value associated with the given index. If the index is not present in the array, an exception is thrown.

注意: When encountering a value encoded as 64-bit integer in the BSON array, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\RuntimeException if the index is not present in the array.

参考

  • ArrayAccess::offsetGet() - オフセットを取得する
  • MongoDB\BSON\PackedArray::get() - Returns the value of an index in the array


Implementation of ArrayAccess

  • ≪ MongoDB\BSON\PackedArray::offsetGet
  • MongoDB\BSON\PackedArray::offsetUnset ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Implementation of ArrayAccess

MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Implementation of ArrayAccess

説明

final public MongoDB\BSON\PackedArray::offsetSet(mixed $key, mixed $value): void

Sets the value at the specified key to value.

パラメータ

key

The index being set.

value

The new value for the key.

戻り値

値を返しません。

エラー / 例外

  • Always throws a MongoDB\Driver\Exception\LogicException.


Implementation of ArrayAccess

  • ≪ MongoDB\BSON\PackedArray::offsetSet
  • MongoDB\BSON\PackedArray::serialize ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Implementation of ArrayAccess

MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess

説明

final public MongoDB\BSON\PackedArray::offsetUnset(mixed $key): void

Unsets the value at the specified index.

パラメータ

key

The index being unset.

戻り値

値を返しません。

エラー / 例外

  • Always throws a MongoDB\Driver\Exception\LogicException.


Serialize a BSON array

  • ≪ MongoDB\BSON\PackedArray::offsetUnset
  • MongoDB\BSON\PackedArray::toPHP ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Serialize a BSON array

MongoDB\BSON\PackedArray::serialize

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::serialize — Serialize a BSON array

説明

final public MongoDB\BSON\PackedArray::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\PackedArray.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\PackedArray::unserialize() - Unserialize a BSON array
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the PHP representation of the BSON array

  • ≪ MongoDB\BSON\PackedArray::serialize
  • MongoDB\BSON\PackedArray::__toString ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns the PHP representation of the BSON array

MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array

説明

final public MongoDB\BSON\PackedArray::toPHP(?array $typeMap = null): array|object

パラメータ

typeMap (array)

Type map configuration.

戻り値

The decoded PHP value.

注意: When encountering a value encoded as 64-bit integer in the BSON array, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

参考

  • MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
  • » BSON Types


Returns the string representation of this BSON array

  • ≪ MongoDB\BSON\PackedArray::toPHP
  • MongoDB\BSON\PackedArray::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Returns the string representation of this BSON array

MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array

説明

final public MongoDB\BSON\PackedArray::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this array as BSON.

参考

  • » BSON Types


Unserialize a BSON array

  • ≪ MongoDB\BSON\PackedArray::__toString
  • MongoDB\BSON\Iterator ≫
  • PHP Manual
  • MongoDB\BSON\PackedArray
  • Unserialize a BSON array

MongoDB\BSON\PackedArray::unserialize

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::unserialize — Unserialize a BSON array

説明

final public MongoDB\BSON\PackedArray::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\PackedArray.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. data was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\PackedArray::serialize() - Serialize a BSON array
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Iterator class

(mongodb >=1.16.0)

はじめに

Iterator used to iterate a BSON document or array.

クラス概要

final class MongoDB\BSON\Iterator implements Iterator {
/* メソッド */
final private __construct()
public current(): mixed
public key(): string|int
public next(): void
public rewind(): void
public valid(): bool
}

目次

  • MongoDB\BSON\Iterator::__construct — Construct a new BSON iterator (unused)
  • MongoDB\BSON\Iterator::current — Returns the current element
  • MongoDB\BSON\Iterator::key — Returns the key of the current element
  • MongoDB\BSON\Iterator::next — Advances the iterator to next element
  • MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element
  • MongoDB\BSON\Iterator::valid — Checks if current position is valid


Construct a new BSON iterator (unused)

  • ≪ MongoDB\BSON\Iterator
  • MongoDB\BSON\Iterator::current ≫
  • PHP Manual
  • MongoDB\BSON\Iterator
  • Construct a new BSON iterator (unused)

MongoDB\BSON\Iterator::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

MongoDB\BSON\Iterator::__construct — Construct a new BSON iterator (unused)

説明

final private MongoDB\BSON\Iterator::__construct()

MongoDB\BSON\Iterator objects are created by calling MongoDB\BSON\Document::getIterator() or MongoDB\BSON\PackedArray::getIterator() and cannot be instantiated directly.

パラメータ

この関数にはパラメータはありません。

参考

  • MongoDB\BSON\Document::getIterator() - Returns an iterator for the BSON document
  • MongoDB\BSON\PackedArray::getIterator() - Returns an iterator for the BSON array
  • » BSON Types


Returns the current element

  • ≪ MongoDB\BSON\Iterator::__construct
  • MongoDB\BSON\Iterator::key ≫
  • PHP Manual
  • MongoDB\BSON\Iterator
  • Returns the current element

MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Returns the current element

説明

public MongoDB\BSON\Iterator::current(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the value of the current element.

注意: When encountering a value encoded as 64-bit integer in the BSON structure, the return value of this method will be a MongoDB\BSON\Int64 instance.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\LogicException if the iterator is not valid.

参考

  • Iterator::current() - 現在の要素を返す


Returns the key of the current element

  • ≪ MongoDB\BSON\Iterator::current
  • MongoDB\BSON\Iterator::next ≫
  • PHP Manual
  • MongoDB\BSON\Iterator
  • Returns the key of the current element

MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Returns the key of the current element

説明

public MongoDB\BSON\Iterator::key(): string|int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the key of the current element. When iterating a BSON document, the key will always be a string. When iterating a BSON array, the key will be an int.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\LogicException if the iterator is not valid.

参考

  • Iterator::key() - 現在の要素のキーを返す


Advances the iterator to next element

  • ≪ MongoDB\BSON\Iterator::key
  • MongoDB\BSON\Iterator::rewind ≫
  • PHP Manual
  • MongoDB\BSON\Iterator
  • Advances the iterator to next element

MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Advances the iterator to next element

説明

public MongoDB\BSON\Iterator::next(): void

パラメータ

この関数にはパラメータはありません。

参考

  • Iterator::next() - 次の要素に進む


Rewinds the Iterator to the first element

  • ≪ MongoDB\BSON\Iterator::next
  • MongoDB\BSON\Iterator::valid ≫
  • PHP Manual
  • MongoDB\BSON\Iterator
  • Rewinds the Iterator to the first element

MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element

説明

public MongoDB\BSON\Iterator::rewind(): void

パラメータ

この関数にはパラメータはありません。

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す


Checks if current position is valid

  • ≪ MongoDB\BSON\Iterator::rewind
  • MongoDB\BSON\Binary ≫
  • PHP Manual
  • MongoDB\BSON\Iterator
  • Checks if current position is valid

MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Checks if current position is valid

説明

public MongoDB\BSON\Iterator::valid(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the current iterator position is valid, false otherwise.

参考

  • Iterator::valid() - 現在位置が有効かどうかを調べる


The MongoDB\BSON\Binary class

(mongodb >=1.0.0)

はじめに

BSON type for binary data (i.e. array of bytes). Binary values also have a subtype, which is used to indicate what kind of data is in the byte array. Subtypes from zero to 127 are predefined or reserved. Subtypes from 128-255 are user-defined.

クラス概要

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* 定数 */
const int TYPE_GENERIC = 0;
const int TYPE_FUNCTION = 1;
const int TYPE_OLD_BINARY = 2;
const int TYPE_OLD_UUID = 3;
const int TYPE_UUID = 4;
const int TYPE_MD5 = 5;
const int TYPE_ENCRYPTED = 6;
const int TYPE_COLUMN = 7;
const int TYPE_SENSITIVE = 8;
const int TYPE_USER_DEFINED = 128;
/* メソッド */
final public __construct(string $data, int $type = MongoDB\BSON\Binary::TYPE_GENERIC)
final public getData(): string
final public getType(): int
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

定義済み定数

MongoDB\BSON\Binary::TYPE_GENERIC

Generic binary data.

MongoDB\BSON\Binary::TYPE_FUNCTION

Function.

MongoDB\BSON\Binary::TYPE_OLD_BINARY

Generic binary data (deprecated in favor of MongoDB\BSON\Binary::TYPE_GENERIC).

MongoDB\BSON\Binary::TYPE_OLD_UUID

Universally unique identifier (deprecated in favor of MongoDB\BSON\Binary::TYPE_UUID). When using this type, the Binary's data should be 16 bytes in length.

Historically, other drivers encoded values with this type based on their language conventions (e.g. varying endianness), which makes it non-portable. The PHP extension applies no special handling for encoding or decoding data with this type.

MongoDB\BSON\Binary::TYPE_UUID

Universally unique identifier. When using this type, the Binary's data should be 16 bytes in length and encoded according to » RFC 4122.

MongoDB\BSON\Binary::TYPE_MD5

MD5 hash. When using this type, the Binary's data should be 16 bytes in length.

MongoDB\BSON\Binary::TYPE_ENCRYPTED

Encrypted value. This subtype is used for client-side encryption.

MongoDB\BSON\Binary::TYPE_COLUMN

Column data. This subtype is used for time-series collections.

MongoDB\BSON\Binary::TYPE_SENSITIVE

Sensitive data. This subtype is used for sensitive data that should be excluded from server-side logging when possible.

MongoDB\BSON\Binary::TYPE_USER_DEFINED

User-defined type. While types between 0 and 127 are predefined or reserved, types between 128 and 255 are user-defined and may be used for anything.

変更履歴

バージョン | 説明
PECL mongodb 1.17.0 | Added MongoDB\BSON\Binary::TYPE_SENSITIVE.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+. Added MongoDB\BSON\Binary::TYPE_COLUMN.
PECL mongodb 1.7.0 | Added MongoDB\BSON\Binary::TYPE_ENCRYPTED.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\BinaryInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Binary::__construct — Construct a new Binary
  • MongoDB\BSON\Binary::getData — Returns the Binary's data
  • MongoDB\BSON\Binary::getType — Returns the Binary's type
  • MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Binary::serialize — Serialize a Binary
  • MongoDB\BSON\Binary::__toString — Returns the Binary's data
  • MongoDB\BSON\Binary::unserialize — Unserialize a Binary


Construct a new Binary

  • ≪ MongoDB\BSON\Binary
  • MongoDB\BSON\Binary::getData ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Construct a new Binary

MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Construct a new Binary

説明

final public MongoDB\BSON\Binary::__construct(string $data, int $type = MongoDB\BSON\Binary::TYPE_GENERIC)

パラメータ

data (string)

Binary data.

type (int)

Unsigned 8-bit integer denoting the data's type. Defaults to MongoDB\BSON\Binary::TYPE_GENERIC if not specified.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if type is not an unsigned 8-bit integer.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if type is MongoDB\BSON\Binary::TYPE_UUID or MongoDB\BSON\Binary::TYPE_OLD_UUID and data is not exactly 16 bytes in length.

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | The type parameter defaults to MongoDB\BSON\Binary::TYPE_GENERIC if not specified.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is thrown if type is MongoDB\BSON\Binary::TYPE_UUID or MongoDB\BSON\Binary::TYPE_OLD_UUID and data is not exactly 16 bytes in length.
PECL mongodb 1.1.3 | MongoDB\Driver\Exception\InvalidArgumentException is thrown if type is not an unsigned 8-bit integer.

例

例1 MongoDB\BSON\Binary::__construct() example

<?php

$binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
var_dump($binary);

?>

上の例の出力は以下となります。

object(MongoDB\BSON\Binary)#1 (2) {
  ["data"]=>
  string(3) "foo"
  ["type"]=>
  int(0)
}

参考

  • » BSON Types


Returns the Binary's data

  • ≪ MongoDB\BSON\Binary::__construct
  • MongoDB\BSON\Binary::getType ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns the Binary's data

MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Returns the Binary's data

説明

final public MongoDB\BSON\Binary::getData(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Binary's data.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Binary::getData() example

<?php

$binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
var_dump($binary->getData());

?>

上の例の出力は以下となります。

string(3) "foo"

参考

  • » BSON Types


Returns the Binary's type

  • ≪ MongoDB\BSON\Binary::getData
  • MongoDB\BSON\Binary::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns the Binary's type

MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Returns the Binary's type

説明

final public MongoDB\BSON\Binary::getType(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Binary's type.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Binary::getType() example

<?php

$binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
var_dump($binary->getType());

?>

上の例の出力は以下となります。

int(0)

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Binary::getType
  • MongoDB\BSON\Binary::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Binary::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Binary.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Binary

  • ≪ MongoDB\BSON\Binary::jsonSerialize
  • MongoDB\BSON\Binary::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Serialize a Binary

MongoDB\BSON\Binary::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::serialize — Serialize a Binary

説明

final public MongoDB\BSON\Binary::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Binary.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Binary::unserialize() - Unserialize a Binary
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the Binary's data

  • ≪ MongoDB\BSON\Binary::serialize
  • MongoDB\BSON\Binary::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Returns the Binary's data

MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Returns the Binary's data

説明

final public MongoDB\BSON\Binary::__toString(): string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\Binary::getData().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Binary's data.

例

例1 MongoDB\BSON\Binary::__toString() example

<?php

var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

?>

上の例の出力は以下となります。

string(3) "foo"

参考

  • MongoDB\BSON\Binary::getData() - Returns the Binary's data
  • » BSON Types


Unserialize a Binary

  • ≪ MongoDB\BSON\Binary::__toString
  • MongoDB\BSON\Decimal128 ≫
  • PHP Manual
  • MongoDB\BSON\Binary
  • Unserialize a Binary

MongoDB\BSON\Binary::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::unserialize — Unserialize a Binary

説明

final public MongoDB\BSON\Binary::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Binary.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Binary::serialize() - Serialize a Binary
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Decimal128 class

(mongodb >=1.2.0)

はじめに

BSON type for the » Decimal128 floating-point format, which supports numbers with up to 34 decimal digits (i.e. significant digits) and an exponent range of ?6143 to +6144.

Unlike the double BSON type (i.e. float in PHP), which only stores an approximation of the decimal values, the decimal data type stores the exact value. For example, MongoDB\BSON\Decimal128('9.99') has a precise value of 9.99 where as a double 9.99 would have an approximate value of 9.9900000000000002131628....

注意: MongoDB\BSON\Decimal128 is only compatible with MongoDB 3.4+. Attempting to use the BSON type with an earlier version of MongoDB will result in an error.

クラス概要

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(string $value)
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\Decimal128Interface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128
  • MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Decimal128::serialize — Serialize a Decimal128
  • MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128
  • MongoDB\BSON\Decimal128::unserialize — Unserialize a Decimal128


Construct a new Decimal128

  • ≪ MongoDB\BSON\Decimal128
  • MongoDB\BSON\Decimal128::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Construct a new Decimal128

MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128

説明

final public MongoDB\BSON\Decimal128::__construct(string $value)

注意: MongoDB\BSON\Decimal128 is only compatible with MongoDB 3.4+. Attempting to use the BSON type with an earlier version of MongoDB will result in an error.

パラメータ

value (string)

A decimal string.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if value is not a valid decimal string.

例

例1 MongoDB\BSON\Decimal128::__construct() example

<?php

var_dump(new MongoDB\BSON\Decimal128(1234.5678));
var_dump(new MongoDB\BSON\Decimal128(NAN));
var_dump(new MongoDB\BSON\Decimal128(INF));

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\BSON\Decimal128)#1 (1) {
  ["dec"]=>
  string(9) "1234.5678"
}
object(MongoDB\BSON\Decimal128)#1 (1) {
  ["dec"]=>
  string(3) "NaN"
}
object(MongoDB\BSON\Decimal128)#1 (1) {
  ["dec"]=>
  string(8) "Infinity"
}

参考

  • » Decimal128 floating-point format
  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Decimal128::__construct
  • MongoDB\BSON\Decimal128::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Decimal128::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Decimal128.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Decimal128

  • ≪ MongoDB\BSON\Decimal128::jsonSerialize
  • MongoDB\BSON\Decimal128::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Serialize a Decimal128

MongoDB\BSON\Decimal128::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::serialize — Serialize a Decimal128

説明

final public MongoDB\BSON\Decimal128::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Decimal128.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Decimal128::unserialize() - Unserialize a Decimal128
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the string representation of this Decimal128

  • ≪ MongoDB\BSON\Decimal128::serialize
  • MongoDB\BSON\Decimal128::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Returns the string representation of this Decimal128

MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128

説明

final public MongoDB\BSON\Decimal128::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this Decimal128.

例

例1 MongoDB\BSON\Decimal128::__toString() example

<?php

var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
var_dump((string) new MongoDB\BSON\Decimal128(NAN));
var_dump((string) new MongoDB\BSON\Decimal128(INF));

?>

上の例の出力は、 たとえば以下のようになります。

string(9) "1234.5678"
string(3) "NaN"
string(8) "Infinity"

参考

  • » Decimal128 floating-point format
  • » BSON Types


Unserialize a Decimal128

  • ≪ MongoDB\BSON\Decimal128::__toString
  • MongoDB\BSON\Javascript ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128
  • Unserialize a Decimal128

MongoDB\BSON\Decimal128::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::unserialize — Unserialize a Decimal128

説明

final public MongoDB\BSON\Decimal128::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Decimal128.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Decimal128::serialize() - Serialize a Decimal128
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Javascript class

(mongodb >=1.0.0)

はじめに

BSON type for Javascript code. An optional scope document may be specified that maps identifiers to values and defines the scope in which the code should be evaluated by the server.

注意: This BSON type is mainly used when executing database commands that take a Javascript function as a parameter, such as » mapReduce.

クラス概要

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(string $code, array|object|null $scope = null)
final public getCode(): string
final public getScope(): ?object
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\JavascriptInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Javascript::__construct — Construct a new Javascript
  • MongoDB\BSON\Javascript::getCode — Returns the Javascript's code
  • MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document
  • MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Javascript::serialize — Serialize a Javascript
  • MongoDB\BSON\Javascript::__toString — Returns the Javascript's code
  • MongoDB\BSON\Javascript::unserialize — Unserialize a Javascript


Construct a new Javascript

  • ≪ MongoDB\BSON\Javascript
  • MongoDB\BSON\Javascript::getCode ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Construct a new Javascript

MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Construct a new Javascript

説明

final public MongoDB\BSON\Javascript::__construct(string $code, array|object|null $scope = null)

パラメータ

code (string)

Javascript code.

scope (array|object)

Javascript scope.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if code contains null bytes.

変更履歴

バージョン | 説明
PECL mongodb 1.2.0 | MongoDB\Driver\Exception\InvalidArgumentException is thrown if code contains null bytes. Previously, values would be truncated at the first null byte.

例

例1 MongoDB\BSON\Javascript::__construct() example

<?php

$code = new MongoDB\BSON\Javascript('function() { return 1; }');
var_dump($code);

$codews = new MongoDB\BSON\Javascript('function() { return foo; }', ['foo' => 'bar']);
var_dump($codews);

?>

上の例の出力は以下となります。

object(MongoDB\BSON\Javascript)#1 (2) {
  ["javascript"]=>
  string(24) "function() { return 1; }"
  ["scope"]=>
  object(stdClass)#2 (0) {
  }
}
object(MongoDB\BSON\Javascript)#2 (2) {
  ["javascript"]=>
  string(26) "function() { return foo; }"
  ["scope"]=>
  object(stdClass)#1 (1) {
    ["foo"]=>
    string(3) "bar"
  }
}

参考

  • » BSON Types


Returns the Javascript's code

  • ≪ MongoDB\BSON\Javascript::__construct
  • MongoDB\BSON\Javascript::getScope ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns the Javascript's code

MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Returns the Javascript's code

説明

final public MongoDB\BSON\Javascript::getCode(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Javascript's code.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Javascript::getCode() example

<?php

$js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
var_dump($js->getCode());

?>

上の例の出力は以下となります。

string(33) "function foo(bar) { return bar; }"

参考

  • » BSON Types


Returns the Javascript's scope document

  • ≪ MongoDB\BSON\Javascript::getCode
  • MongoDB\BSON\Javascript::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns the Javascript's scope document

MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document

説明

final public MongoDB\BSON\Javascript::getScope(): ?object

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Javascript's scope document, or null if the is no scope.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Javascript::getScope() example

<?php

$js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
var_dump($js->getScope());

$js = new MongoDB\BSON\Javascript('function foo() { return foo; }', ['foo' => 42]);
var_dump($js->getScope());

?>

上の例の出力は以下となります。

NULL
object(stdClass)#1 (1) {
  ["foo"]=>
  int(42)
}

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Javascript::getScope
  • MongoDB\BSON\Javascript::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Javascript::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Javascript.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Javascript

  • ≪ MongoDB\BSON\Javascript::jsonSerialize
  • MongoDB\BSON\Javascript::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Serialize a Javascript

MongoDB\BSON\Javascript::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::serialize — Serialize a Javascript

説明

final public MongoDB\BSON\Javascript::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Javascript.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Javascript::unserialize() - Unserialize a Javascript
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the Javascript's code

  • ≪ MongoDB\BSON\Javascript::serialize
  • MongoDB\BSON\Javascript::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Returns the Javascript's code

MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Returns the Javascript's code

説明

final public MongoDB\BSON\Javascript::__toString(): string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\Javascript::getCode().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Javascript's code.

例

例1 MongoDB\BSON\Javascript::__toString() example

<?php

var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

?>

上の例の出力は以下となります。

string(33) "function foo(bar) { return bar; }"

参考

  • MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code
  • » BSON Types


Unserialize a Javascript

  • ≪ MongoDB\BSON\Javascript::__toString
  • MongoDB\BSON\MaxKey ≫
  • PHP Manual
  • MongoDB\BSON\Javascript
  • Unserialize a Javascript

MongoDB\BSON\Javascript::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::unserialize — Unserialize a Javascript

説明

final public MongoDB\BSON\Javascript::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Javascript.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Javascript::serialize() - Serialize a Javascript
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\MaxKey class

(mongodb >=1.0.0)

はじめに

Special BSON type which compares higher than all other possible BSON element values.

注意: This is an internal MongoDB type used for indexing and sharding.

クラス概要

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, Serializable, JsonSerializable {
/* メソッド */
final public __construct()
final public jsonSerialize(): mixed
final public serialize(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey
  • MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\MaxKey::serialize — Serialize a MaxKey
  • MongoDB\BSON\MaxKey::unserialize — Unserialize a MaxKey


Construct a new MaxKey

  • ≪ MongoDB\BSON\MaxKey
  • MongoDB\BSON\MaxKey::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Construct a new MaxKey

MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey

説明

final public MongoDB\BSON\MaxKey::__construct()

パラメータ

この関数にはパラメータはありません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\MaxKey::__construct() example

<?php

var_dump(new MongoDB\BSON\MaxKey());

?>

上の例の出力は以下となります。

object(MongoDB\BSON\MaxKey)#1 (0) {
}

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\MaxKey::__construct
  • MongoDB\BSON\MaxKey::serialize ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Returns a representation that can be converted to JSON

MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\MaxKey::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MaxKey.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a MaxKey

  • ≪ MongoDB\BSON\MaxKey::jsonSerialize
  • MongoDB\BSON\MaxKey::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Serialize a MaxKey

MongoDB\BSON\MaxKey::serialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::serialize — Serialize a MaxKey

説明

final public MongoDB\BSON\MaxKey::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\MaxKey.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\MaxKey::unserialize() - Unserialize a MaxKey
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Unserialize a MaxKey

  • ≪ MongoDB\BSON\MaxKey::serialize
  • MongoDB\BSON\MinKey ≫
  • PHP Manual
  • MongoDB\BSON\MaxKey
  • Unserialize a MaxKey

MongoDB\BSON\MaxKey::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::unserialize — Unserialize a MaxKey

説明

final public MongoDB\BSON\MaxKey::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\MaxKey.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\MaxKey::serialize() - Serialize a MaxKey
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\MinKey class

(mongodb >=1.0.0)

はじめに

Special BSON type which compares lower than all other possible BSON element values.

注意: This is an internal MongoDB type used for indexing and sharding.

クラス概要

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, Serializable, JsonSerializable {
/* メソッド */
final public __construct()
final public jsonSerialize(): mixed
final public serialize(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\MinKey::__construct — Construct a new MinKey
  • MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\MinKey::serialize — Serialize a MinKey
  • MongoDB\BSON\MinKey::unserialize — Unserialize a MinKey


Construct a new MinKey

  • ≪ MongoDB\BSON\MinKey
  • MongoDB\BSON\MinKey::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Construct a new MinKey

MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Construct a new MinKey

説明

final public MongoDB\BSON\MinKey::__construct()

パラメータ

この関数にはパラメータはありません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\MinKey::__construct() example

<?php

var_dump(new MongoDB\BSON\MinKey());

?>

上の例の出力は以下となります。

object(MongoDB\BSON\MinKey)#1 (0) {
}

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\MinKey::__construct
  • MongoDB\BSON\MinKey::serialize ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Returns a representation that can be converted to JSON

MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\MinKey::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MinKey.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a MinKey

  • ≪ MongoDB\BSON\MinKey::jsonSerialize
  • MongoDB\BSON\MinKey::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Serialize a MinKey

MongoDB\BSON\MinKey::serialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::serialize — Serialize a MinKey

説明

final public MongoDB\BSON\MinKey::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\MinKey.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\MinKey::unserialize() - Unserialize a MinKey
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Unserialize a MinKey

  • ≪ MongoDB\BSON\MinKey::serialize
  • MongoDB\BSON\ObjectId ≫
  • PHP Manual
  • MongoDB\BSON\MinKey
  • Unserialize a MinKey

MongoDB\BSON\MinKey::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::unserialize — Unserialize a MinKey

説明

final public MongoDB\BSON\MinKey::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\MinKey.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\MinKey::serialize() - Serialize a MinKey
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\ObjectId class

(mongodb >=1.0.0)

はじめに

BSON type for an » ObjectId. The value consists of 12 bytes, where the first four bytes are a timestamp that reflect the ObjectId's creation. Specifically, the value consists of:

  • a 4-byte value representing the seconds since the Unix epoch,
  • a 5-byte random number unique to a machine and process, and
  • a 3-byte counter, starting with a random value.

In MongoDB, each document stored in a collection requires a unique _id field that acts as a primary key. If an inserted document omits the _id field, the extension automatically generates an ObjectId for the _id field.

Using ObjectIds for the _id field provides the following additional benefits:

  • The creation time of the ObjectId may be accessed using the MongoDB\BSON\ObjectId::getTimestamp() method.
  • Sorting on an _id field that stores ObjectId values is roughly equivalent to sorting by creation time.

クラス概要

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(?string $id = null)
final public getTimestamp(): int
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Renamed from MongoDB\BSON\ObjectID to MongoDB\BSON\ObjectId. Implements MongoDB\BSON\ObjectIdInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId
  • MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId
  • MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\ObjectId::serialize — Serialize an ObjectId
  • MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId
  • MongoDB\BSON\ObjectId::unserialize — Unserialize an ObjectId


Construct a new ObjectId

  • ≪ MongoDB\BSON\ObjectId
  • MongoDB\BSON\ObjectId::getTimestamp ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Construct a new ObjectId

MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId

説明

final public MongoDB\BSON\ObjectId::__construct(?string $id = null)

パラメータ

id (string)

A 24-character hexadecimal string. If not provided, the extension will generate an ObjectId.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if id is not a 24-character hexadecimal string.

例

例1 MongoDB\BSON\ObjectId::__construct() example

<?php

var_dump(new MongoDB\BSON\ObjectId());

var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\BSON\ObjectId)#1 (1) {
  ["oid"]=>
  string(24) "56732d3dda14d81214634921"
}
object(MongoDB\BSON\ObjectId)#1 (1) {
  ["oid"]=>
  string(24) "000000000000000000000001"
}

参考

  • » ObjectId Reference
  • » BSON Types: ObjectId


Returns the timestamp component of this ObjectId

  • ≪ MongoDB\BSON\ObjectId::__construct
  • MongoDB\BSON\ObjectId::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Returns the timestamp component of this ObjectId

MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId

説明

final public MongoDB\BSON\ObjectId::getTimestamp(): int

The timestamp component of an ObjectId is its most significant 32 bits, which denotes the number of seconds since the Unix epoch. This value is read as an unsigned 32-bit integer with big-endian byte order.

注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The "%u" formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the timestamp component of this ObjectId.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\ObjectId::getTimestamp() example

<?php

var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

?>

上の例の出力は、 たとえば以下のようになります。

integer(1484854719)
integer(42)

参考

  • » ObjectId Reference
  • » BSON Types: ObjectId


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\ObjectId::getTimestamp
  • MongoDB\BSON\ObjectId::serialize ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Returns a representation that can be converted to JSON

MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\ObjectId::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\ObjectId.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize an ObjectId

  • ≪ MongoDB\BSON\ObjectId::jsonSerialize
  • MongoDB\BSON\ObjectId::__toString ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Serialize an ObjectId

MongoDB\BSON\ObjectId::serialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::serialize — Serialize an ObjectId

説明

final public MongoDB\BSON\ObjectId::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\ObjectId.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\ObjectId::unserialize() - Unserialize an ObjectId
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the hexidecimal representation of this ObjectId

  • ≪ MongoDB\BSON\ObjectId::serialize
  • MongoDB\BSON\ObjectId::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Returns the hexidecimal representation of this ObjectId

MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId

説明

final public MongoDB\BSON\ObjectId::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hexidecimal representation of this ObjectId.

例

例1 MongoDB\BSON\ObjectId::__toString() example

<?php

var_dump((string) new MongoDB\BSON\ObjectId());
var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

?>

上の例の出力は、 たとえば以下のようになります。

string(24) "56731b49da14d8747d701211"
string(24) "000000000000000000000001"

参考

  • » ObjectId Reference
  • » BSON Types: ObjectId


Unserialize an ObjectId

  • ≪ MongoDB\BSON\ObjectId::__toString
  • MongoDB\BSON\Regex ≫
  • PHP Manual
  • MongoDB\BSON\ObjectId
  • Unserialize an ObjectId

MongoDB\BSON\ObjectId::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::unserialize — Unserialize an ObjectId

説明

final public MongoDB\BSON\ObjectId::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\ObjectId.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\ObjectId::serialize() - Serialize an ObjectId
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Regex class

(mongodb >=1.0.0)

はじめに

BSON type for a regular expression pattern and optional » flags.

注意: This BSON type is mainly used when querying the database. Alternatively, the » $regex query operator may be used.

クラス概要

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(string $pattern, string $flags = "")
final public getFlags(): string
final public getPattern(): string
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\RegexInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Regex::__construct — Construct a new Regex
  • MongoDB\BSON\Regex::getFlags — Returns the Regex's flags
  • MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern
  • MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Regex::serialize — Serialize a Regex
  • MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex
  • MongoDB\BSON\Regex::unserialize — Unserialize a Regex


Construct a new Regex

  • ≪ MongoDB\BSON\Regex
  • MongoDB\BSON\Regex::getFlags ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Construct a new Regex

MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Construct a new Regex

説明

final public MongoDB\BSON\Regex::__construct(string $pattern, string $flags = "")

パラメータ

pattern (string)

The regular expression pattern.

注意: The pattern should not be wrapped with delimiter characters.

flags (string)

The » regular expression flags. Characters in this argument will be sorted alphabetically.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if pattern or flags contain null bytes.

変更履歴

バージョン 説明
PECL mongodb 1.2.0

The flags argument is optional and defaults to an empty string.

Characters in the flags argument will be sorted alphabetically when a Regex is constructed. Previously, the characters were stored in the order provided.

MongoDB\Driver\Exception\InvalidArgumentException is thrown if pattern or flags contain null bytes. Previously, values would be truncated at the first null byte.

例

例1 MongoDB\BSON\Regex::__construct() example

<?php

$regex = new MongoDB\BSON\Regex('^foo', 'i');
var_dump($regex);

?>

上の例の出力は以下となります。

object(MongoDB\BSON\Regex)#1 (2) {
  ["pattern"]=>
  string(4) "^foo"
  ["flags"]=>
  string(1) "i"
}

参考

  • » BSON Types
  • » Supported regular expression flags


Returns the Regex's flags

  • ≪ MongoDB\BSON\Regex::__construct
  • MongoDB\BSON\Regex::getPattern ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns the Regex's flags

MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Returns the Regex's flags

説明

final public MongoDB\BSON\Regex::getFlags(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Regex's flags.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Regex::getFlags() example

<?php

$regex = new MongoDB\BSON\Regex('regex', 'i');
var_dump($regex->getFlags());

?>

上の例の出力は、 たとえば以下のようになります。

string(1) "i"

参考

  • » BSON Types
  • » Supported regular expression flags


Returns the Regex's pattern

  • ≪ MongoDB\BSON\Regex::getFlags
  • MongoDB\BSON\Regex::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns the Regex's pattern

MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern

説明

final public MongoDB\BSON\Regex::getPattern(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Regex's pattern.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Regex::getPattern() example

<?php

$regex = new MongoDB\BSON\Regex('regex', 'i');
var_dump($regex->getPattern());

?>

上の例の出力は、 たとえば以下のようになります。

string(5) "regex"

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Regex::getPattern
  • MongoDB\BSON\Regex::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Regex::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Regex.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Regex

  • ≪ MongoDB\BSON\Regex::jsonSerialize
  • MongoDB\BSON\Regex::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Serialize a Regex

MongoDB\BSON\Regex::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::serialize — Serialize a Regex

説明

final public MongoDB\BSON\Regex::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Regex.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Regex::unserialize() - Unserialize a Regex
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the string representation of this Regex

  • ≪ MongoDB\BSON\Regex::serialize
  • MongoDB\BSON\Regex::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Returns the string representation of this Regex

MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex

説明

final public MongoDB\BSON\Regex::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this Regex.

例

例1 MongoDB\BSON\Regex::__toString() example

<?php

$regex = new MongoDB\BSON\Regex('regex', 'i');
var_dump((string) $regex);

?>

上の例の出力は以下となります。

string(8) "/regex/i"

参考

  • » BSON Types


Unserialize a Regex

  • ≪ MongoDB\BSON\Regex::__toString
  • MongoDB\BSON\Timestamp ≫
  • PHP Manual
  • MongoDB\BSON\Regex
  • Unserialize a Regex

MongoDB\BSON\Regex::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::unserialize — Unserialize a Regex

説明

final public MongoDB\BSON\Regex::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Regex.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Regex::serialize() - Serialize a Regex
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Timestamp class

(mongodb >=1.0.0)

はじめに

Represents a » BSON timestamp, The value consists of a 4-byte timestamp (i.e. seconds since the epoch) and a 4-byte increment.

注意: This is an internal MongoDB type used for replication and sharding. It is not intended for general date storage (MongoDB\BSON\UTCDateTime should be used instead).

クラス概要

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(int $increment, int $timestamp)
final public getIncrement(): int
final public getTimestamp(): int
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\TimestampInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp
  • MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp
  • MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp
  • MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Timestamp::serialize — Serialize a Timestamp
  • MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp
  • MongoDB\BSON\Timestamp::unserialize — Unserialize a Timestamp


Construct a new Timestamp

  • ≪ MongoDB\BSON\Timestamp
  • MongoDB\BSON\Timestamp::getIncrement ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Construct a new Timestamp

MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp

説明

final public MongoDB\BSON\Timestamp::__construct(int $increment, int $timestamp)

パラメータ

increment (int)

32-bit integer denoting the incrementing ordinal for operations within a given second.

timestamp (int)

32-bit integer denoting seconds since the Unix epoch.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\Timestamp::__construct() example

<?php

$timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

?>

上の例の出力は以下となります。

object(MongoDB\BSON\Timestamp)#1 (2) {
  ["increment"]=>
  int(1234)
  ["timestamp"]=>
  int(5678)
}

参考

  • » BSON Types: Timestamps


Returns the increment component of this Timestamp

  • ≪ MongoDB\BSON\Timestamp::__construct
  • MongoDB\BSON\Timestamp::getTimestamp ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns the increment component of this Timestamp

MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp

説明

final public MongoDB\BSON\Timestamp::getIncrement(): int

The increment component of a Timestamp is its least significant 32 bits, whichs denotes the incrementing ordinal for operations within a given second. This value is read as an unsigned 32-bit integer with big-endian byte order.

注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The "%u" formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the increment component of this Timestamp.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • » BSON Types: Timestamps


Returns the timestamp component of this Timestamp

  • ≪ MongoDB\BSON\Timestamp::getIncrement
  • MongoDB\BSON\Timestamp::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns the timestamp component of this Timestamp

MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp

説明

final public MongoDB\BSON\Timestamp::getTimestamp(): int

The timestamp component of a Timestamp is its most significant 32 bits, which denotes the number of seconds since the Unix epoch. This value is read as an unsigned 32-bit integer with big-endian byte order.

注意: Because PHP's integer type is signed, some values returned by this method may appear as negative integers on 32-bit platforms. The "%u" formatter of sprintf() may be used to obtain a string representation of the unsigned decimal value.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the timestamp component of this Timestamp.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • » BSON Types: Timestamps


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Timestamp::getTimestamp
  • MongoDB\BSON\Timestamp::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Timestamp::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Timestamp.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Timestamp

  • ≪ MongoDB\BSON\Timestamp::jsonSerialize
  • MongoDB\BSON\Timestamp::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Serialize a Timestamp

MongoDB\BSON\Timestamp::serialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::serialize — Serialize a Timestamp

説明

final public MongoDB\BSON\Timestamp::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Timestamp.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Timestamp::unserialize() - Unserialize a Timestamp
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the string representation of this Timestamp

  • ≪ MongoDB\BSON\Timestamp::serialize
  • MongoDB\BSON\Timestamp::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Returns the string representation of this Timestamp

MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp

説明

final public MongoDB\BSON\Timestamp::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this Timestamp.

例

例1 MongoDB\BSON\Timestamp::__toString() example

<?php

$timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
var_dump((string) $timestamp);

?>

上の例の出力は、 たとえば以下のようになります。

string(11) "[1234:5678]"

参考

  • » BSON Types: Timestamps


Unserialize a Timestamp

  • ≪ MongoDB\BSON\Timestamp::__toString
  • MongoDB\BSON\UTCDateTime ≫
  • PHP Manual
  • MongoDB\BSON\Timestamp
  • Unserialize a Timestamp

MongoDB\BSON\Timestamp::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::unserialize — Unserialize a Timestamp

説明

final public MongoDB\BSON\Timestamp::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Timestamp.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Timestamp::serialize() - Serialize a Timestamp
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\UTCDateTime class

(mongodb >=1.0.0)

はじめに

Represents a » BSON date. The value is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). Negative values represent dates before 1970.

クラス概要

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(int|float|string|DateTimeInterface|null $milliseconds = null)
final public jsonSerialize(): mixed
final public serialize(): string
final public toDateTime(): DateTime
final public toDateTimeImmutable(): DateTimeImmutable
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\UTCDateTimeInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

目次

  • MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime
  • MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\UTCDateTime::serialize — Serialize a UTCDateTime
  • MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime
  • MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTime
  • MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime
  • MongoDB\BSON\UTCDateTime::unserialize — Unserialize a UTCDateTime


Construct a new UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime
  • MongoDB\BSON\UTCDateTime::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Construct a new UTCDateTime

MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::__construct(int|float|string|DateTimeInterface|null $milliseconds = null)

パラメータ

milliseconds (int|float|string|DateTimeInterface|null)

Number of milliseconds since the Unix epoch (Jan 1, 1970). Negative values represent dates before 1970. This value may be provided as a 64-bit int. For compatibility on 32-bit systems, this parameter may also be provided as a float or string.

If the argument is a DateTimeInterface, the number of milliseconds since the Unix epoch will be derived from that value.

If this argument is null, the current time will be used by default.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

変更履歴

バージョン | 説明
PECL mongodb 1.2.0 | The milliseconds argument is optional and defaults to null (i.e. current time). The argument also accepts a DateTimeInterface, which may be used to derive the number of milliseconds since the Unix epoch. Previously, only int, float, and string types were accepted.

例

例1 MongoDB\BSON\UTCDateTime::__construct() example

<?php

var_dump(new MongoDB\BSON\UTCDateTime);

var_dump(new MongoDB\BSON\UTCDateTime(new DateTime));

var_dump(new MongoDB\BSON\UTCDateTime(1416445411987));

?>

上の例の出力は、 たとえば以下のようになります。

object(MongoDB\BSON\UTCDateTime)#1 (1) {
  ["milliseconds"]=>
  string(13) "1484852905560"
}
object(MongoDB\BSON\UTCDateTime)#1 (1) {
  ["milliseconds"]=>
  string(13) "1484852905560"
}
object(MongoDB\BSON\UTCDateTime)#1 (1) {
  ["milliseconds"]=>
  string(13) "1416445411987"
}

参考

  • » BSON Types: Date


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\UTCDateTime::__construct
  • MongoDB\BSON\UTCDateTime::serialize ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns a representation that can be converted to JSON

MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\UTCDateTime.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::jsonSerialize
  • MongoDB\BSON\UTCDateTime::toDateTime ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Serialize a UTCDateTime

MongoDB\BSON\UTCDateTime::serialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::serialize — Serialize a UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\UTCDateTime.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\UTCDateTime::unserialize() - Unserialize a UTCDateTime
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the DateTime representation of this UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::serialize
  • MongoDB\BSON\UTCDateTime::toDateTimeImmutable ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns the DateTime representation of this UTCDateTime

MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::toDateTime(): DateTime

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the DateTime representation of this UTCDateTime. The returned DateTime will use the UTC time zone.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\UTCDatetime::toDateTime() example

<?php

$utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
$datetime = $utcdatetime->toDateTime();
var_dump($datetime->format('r'));
var_dump($datetime->format('U.u'));
var_dump($datetime->getTimezone());

?>

上の例の出力は、 たとえば以下のようになります。

string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
string(17) "1416445411.987000"
object(DateTimeZone)#3 (2) {
  ["timezone_type"]=>
  int(1)
  ["timezone"]=>
  string(6) "+00:00"
}

参考

  • MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Returns the DateTimeImmutable representation of this UTCDateTime
  • » BSON Types: Date


Returns the DateTimeImmutable representation of this UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::toDateTime
  • MongoDB\BSON\UTCDateTime::__toString ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns the DateTimeImmutable representation of this UTCDateTime

MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the DateTimeImmutable representation of this UTCDateTime. The returned DateTimeImmutable will use the UTC time zone.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

例

例1 MongoDB\BSON\UTCDatetime::toDateTimeImmutable() example

<?php

$utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
$datetime = $utcdatetime->toDateTimeImmutable();
var_dump($datetime->format('r'));
var_dump($datetime->format('U.u'));
var_dump($datetime->getTimezone());

?>

上の例の出力は、 たとえば以下のようになります。

string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
string(17) "1416445411.987000"
object(DateTimeZone)#3 (2) {
  ["timezone_type"]=>
  int(1)
  ["timezone"]=>
  string(6) "+00:00"
}

参考

  • MongoDB\BSON\UTCDateTime::toDateTime() - Returns the DateTime representation of this UTCDateTime
  • » BSON Types: Date


Returns the string representation of this UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::toDateTimeImmutable
  • MongoDB\BSON\UTCDateTime::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Returns the string representation of this UTCDateTime

MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this UTCDateTime.

例

例1 MongoDB\BSON\UTCDateTime::__toString() example

<?php

$utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
var_dump((string) $utcdatetime);

?>

上の例の出力は以下となります。

string(13) "1416445411987"

参考

  • » BSON Types: Date


Unserialize a UTCDateTime

  • ≪ MongoDB\BSON\UTCDateTime::__toString
  • MongoDB\BSON\Type ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTime
  • Unserialize a UTCDateTime

MongoDB\BSON\UTCDateTime::unserialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::unserialize — Unserialize a UTCDateTime

説明

final public MongoDB\BSON\UTCDateTime::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\UTCDateTime.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\UTCDateTime::serialize() - Serialize a UTCDateTime
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Type interface

(mongodb >=1.0.0)

はじめに

Abstract base interface that should not be implemented directly.

インターフェイス概要

class MongoDB\BSON\Type {
}

This interface has no methods. Its only purpose is to be the base interface for all BSON type classes.


The MongoDB\BSON\Persistable interface

(mongodb >=1.0.0)

はじめに

Classes may implement this interface to take advantage of automatic ODM (object document mapping) behavior in the extension. During serialization, the extension will inject a __pclass property containing the PHP class name into the data returned by MongoDB\BSON\Serializable::bsonSerialize(). During unserialization, the same __pclass property will then be used to infer the PHP class (independent of any type map configuration) to be constructed before MongoDB\BSON\Unserializable::bsonUnserialize() is invoked. See Persisting Data for additional information.

注意: Even if MongoDB\BSON\Serializable::bsonSerialize() would return a sequential array, injection of the __pclass property will cause the object to be serialized as a BSON document.

インターフェイス概要

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* メソッド */
abstract public bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* 継承したメソッド */
abstract public MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public MongoDB\BSON\Unserializable::bsonUnserialize(array $data): void
}

目次

  • MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON


Provides an array or document to serialize as BSON

  • ≪ MongoDB\BSON\Persistable
  • MongoDB\BSON\Serializable ≫
  • PHP Manual
  • MongoDB\BSON\Persistable
  • Provides an array or document to serialize as BSON

MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON

説明

abstract public MongoDB\BSON\Persistable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document

Called during serialization of the object to BSON. The method must return an array, stdClass, or MongoDB\BSON\Document.

The return value will always be serialized as a BSON document. The serialized document will include a field containing the class name of the object. For this reason, it is not possible to return a MongoDB\BSON\PackedArray instance in this method.

Users are encouraged to include an _id property (e.g. a MongoDB\BSON\ObjectId initialized in the constructor) when returning data for a BSON root document. In the absence of an _id property, the extension or server will generate a MongoDB\BSON\ObjectId for insert or upsert operations, respectively.

パラメータ

この関数にはパラメータはありません。

戻り値

An array, stdClass, or MongoDB\BSON\Document to be serialized as a BSON document.

変更履歴

バージョン | 説明
PECL mongodb 1.17.0 | This method may now also return MongoDB\BSON\Document instances in addition to array and stdClass.

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
  • MongoDB\BSON\Persistable
  • Persisting Data


The MongoDB\BSON\Serializable interface

(mongodb >=1.0.0)

はじめに

Classes that implement this interface may return data to be serialized as a BSON array or document in lieu of the object's public properties.

インターフェイス概要

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* メソッド */
abstract public bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON


Provides an array or document to serialize as BSON

  • ≪ MongoDB\BSON\Serializable
  • MongoDB\BSON\Unserializable ≫
  • PHP Manual
  • MongoDB\BSON\Serializable
  • Provides an array or document to serialize as BSON

MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

説明

abstract public MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Called during serialization of the object to BSON. The method must return an array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray.

Root documents (e.g. a MongoDB\BSON\Serializable passed to MongoDB\BSON\fromPHP()) will always be serialized as a BSON document. For field values, associative arrays and stdClass instances will be serialized as a BSON document and sequential arrays (i.e. sequential, numeric indexes starting at 0) will be serialized as a BSON array.

Users are encouraged to include an _id property (e.g. a MongoDB\BSON\ObjectId initialized in the constructor) when returning data for a BSON root document. In the absence of an _id property, the extension or server will generate a MongoDB\BSON\ObjectId for insert or upsert operations, respectively.

パラメータ

この関数にはパラメータはありません。

戻り値

An array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray to be serialized as a BSON array or document.

変更履歴

バージョン 説明
PECL mongodb 1.17.0

The return type was changed from array|object. Instead of object, the return type now specifies stdClass. Classes that implement this interface must be changed to no longer declare an object return type. As the return type is tentative, a deprecation warning is emitted on PHP 8.1 and newer.

In addition to the changes above, the extension now also supports returning instances of MongoDB\BSON\Document and MongoDB\BSON\PackedArray. Please note that any MongoDB\BSON\PackedArray instances returned are silently converted to objects when stored as root documents. They are stored as arrays when used as an embedded field value.

例

例1 MongoDB\BSON\Serializable::bsonSerialize() returning an associative array for root document

<?php

class MyDocument implements MongoDB\BSON\Serializable
{
private $id;

function __construct()
{
$this->id = new MongoDB\BSON\ObjectId;
}

function bsonSerialize(): array
{
return ['_id' => $this->id, 'foo' => 'bar'];
}
}

$bson = MongoDB\BSON\fromPHP(new MyDocument);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は、 たとえば以下のようになります。

{ "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

例2 MongoDB\BSON\Serializable::bsonSerialize() returning a sequential array for root document

<?php

class MyArray implements MongoDB\BSON\Serializable
{
function bsonSerialize(): array
{
return [1, 2, 3];
}
}

$bson = MongoDB\BSON\fromPHP(new MyArray);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

{ "0" : 1, "1" : 2, "2" : 3 }

例3 MongoDB\BSON\Serializable::bsonSerialize() returning an associative array for document field

<?php

class MyDocument implements MongoDB\BSON\Serializable
{
function bsonSerialize(): array
{
return ['foo' => 'bar'];
}
}

$value = ['document' => new MyDocument];
$bson = MongoDB\BSON\fromPHP($value);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

{ "document" : { "foo" : "bar" } }

例4 MongoDB\BSON\Serializable::bsonSerialize() returning a sequential array for document field

<?php

class MyArray implements MongoDB\BSON\Serializable
{
function bsonSerialize(): array
{
return [1, 2, 3];
}
}

$value = ['array' => new MyArray];
$bson = MongoDB\BSON\fromPHP($value);
echo MongoDB\BSON\toJSON($bson), "\n";

?>

上の例の出力は以下となります。

{ "array" : [ 1, 2, 3 ] }

参考

  • MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
  • MongoDB\BSON\Persistable
  • Persisting Data


The MongoDB\BSON\Unserializable interface

(mongodb >=1.0.0)

はじめに

Classes that implement this interface may be specified in a type map for unserializing BSON arrays and documents (both root and embedded).

インターフェイス概要

class MongoDB\BSON\Unserializable {
/* メソッド */
abstract public bsonUnserialize(array $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document


Constructs the object from a BSON array or document

  • ≪ MongoDB\BSON\Unserializable
  • MongoDB\BSON\BinaryInterface ≫
  • PHP Manual
  • MongoDB\BSON\Unserializable
  • Constructs the object from a BSON array or document

MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

説明

abstract public MongoDB\BSON\Unserializable::bsonUnserialize(array $data): void

Called during unserialization of the object from BSON. The properties of the BSON array or document will be passed to the method as an array.

Remember to check for an _id property when handling data from a BSON document.

注意: This method acts as the constructor of the object. The __construct() method will not be called after this method.

パラメータ

data (array)

Properties within the BSON array or document.

戻り値

The return value from this method is ignored.

例

例1 MongoDB\BSON\Unserializable::bsonUnserialize() example

<?php

class MyDocument implements MongoDB\BSON\Unserializable
{
private $data = [];

function bsonUnserialize(array $data): void
{
$this->data = $data;
}
}

$bson = MongoDB\BSON\fromJSON('{ "foo": "bar" }');
$value = MongoDB\BSON\toPHP($bson, ['root' => 'MyDocument']);
var_dump($value);

?>

上の例の出力は以下となります。

object(MyDocument)#1 (1) {
  ["data":"MyDocument":private]=>
  array(1) {
    ["foo"]=>
    string(3) "bar"
  }
}

参考

  • MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
  • MongoDB\BSON\Persistable
  • Persisting Data


The MongoDB\BSON\BinaryInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Binary to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\BinaryInterface {
/* メソッド */
abstract public getData(): string
abstract public getType(): int
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data
  • MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type
  • MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data


Returns the BinaryInterface's data

  • ≪ MongoDB\BSON\BinaryInterface
  • MongoDB\BSON\BinaryInterface::getType ≫
  • PHP Manual
  • MongoDB\BSON\BinaryInterface
  • Returns the BinaryInterface's data

MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data

説明

abstract public MongoDB\BSON\BinaryInterface::getData(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the BinaryInterface's data.

参考

  • MongoDB\BSON\Binary::getData() - Returns the Binary's data


Returns the BinaryInterface's type

  • ≪ MongoDB\BSON\BinaryInterface::getData
  • MongoDB\BSON\BinaryInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\BinaryInterface
  • Returns the BinaryInterface's type

MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type

説明

abstract public MongoDB\BSON\BinaryInterface::getType(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the BinaryInterface's type.

参考

  • MongoDB\BSON\Binary::getType() - Returns the Binary's type


Returns the BinaryInterface's data

  • ≪ MongoDB\BSON\BinaryInterface::getType
  • MongoDB\BSON\Decimal128Interface ≫
  • PHP Manual
  • MongoDB\BSON\BinaryInterface
  • Returns the BinaryInterface's data

MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data

説明

abstract public MongoDB\BSON\BinaryInterface::__toString(): string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\BinaryInterface::getData().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the BinaryInterface's data.

参考

  • MongoDB\BSON\BinaryInterface::getData() - Returns the BinaryInterface's data
  • MongoDB\BSON\Binary::__toString() - Returns the Binary's data


The MongoDB\BSON\Decimal128Interface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Decimal128 to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\Decimal128Interface {
/* メソッド */
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface


Returns the string representation of this Decimal128Interface

  • ≪ MongoDB\BSON\Decimal128Interface
  • MongoDB\BSON\JavascriptInterface ≫
  • PHP Manual
  • MongoDB\BSON\Decimal128Interface
  • Returns the string representation of this Decimal128Interface

MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

説明

abstract public MongoDB\BSON\Decimal128Interface::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this Decimal128Interface.

参考

  • MongoDB\BSON\Decimal128::__toString() - Returns the string representation of this Decimal128


The MongoDB\BSON\JavascriptInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Javascript to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\JavascriptInterface {
/* メソッド */
abstract public getCode(): string
abstract public getScope(): ?object
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code
  • MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document
  • MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code


Returns the JavascriptInterface's code

  • ≪ MongoDB\BSON\JavascriptInterface
  • MongoDB\BSON\JavascriptInterface::getScope ≫
  • PHP Manual
  • MongoDB\BSON\JavascriptInterface
  • Returns the JavascriptInterface's code

MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code

説明

abstract public MongoDB\BSON\JavascriptInterface::getCode(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the JavascriptInterface's code.

参考

  • MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code


Returns the JavascriptInterface's scope document

  • ≪ MongoDB\BSON\JavascriptInterface::getCode
  • MongoDB\BSON\JavascriptInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\JavascriptInterface
  • Returns the JavascriptInterface's scope document

MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document

説明

abstract public MongoDB\BSON\JavascriptInterface::getScope(): ?object

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the JavascriptInterface's scope document.

参考

  • MongoDB\BSON\Javascript::getScope() - Returns the Javascript's scope document


Returns the JavascriptInterface's code

  • ≪ MongoDB\BSON\JavascriptInterface::getScope
  • MongoDB\BSON\MaxKeyInterface ≫
  • PHP Manual
  • MongoDB\BSON\JavascriptInterface
  • Returns the JavascriptInterface's code

MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code

説明

abstract public MongoDB\BSON\JavascriptInterface::__toString(): string

このメソッドは次のメソッドのエイリアスです。 MongoDB\BSON\JavascriptInterface::getCode().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the JavascriptInterface's code.

参考

  • MongoDB\BSON\JavascriptInterface::getCode() - Returns the JavascriptInterface's code
  • MongoDB\BSON\Javascript::__toString() - Returns the Javascript's code


The MongoDB\BSON\MaxKeyInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\MaxKey to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\MaxKeyInterface {
}

This interface has no methods.


The MongoDB\BSON\MinKeyInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\MinKey to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\MinKeyInterface {
}

This interface has no methods.


The MongoDB\BSON\ObjectIdInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\ObjectId to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\ObjectIdInterface {
/* メソッド */
abstract public getTimestamp(): int
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface
  • MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface


Returns the timestamp component of this ObjectIdInterface

  • ≪ MongoDB\BSON\ObjectIdInterface
  • MongoDB\BSON\ObjectIdInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\ObjectIdInterface
  • Returns the timestamp component of this ObjectIdInterface

MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface

説明

abstract public MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the timestamp component of this ObjectIdInterface.

参考

  • MongoDB\BSON\ObjectId::getTimestamp() - Returns the timestamp component of this ObjectId


Returns the hexidecimal representation of this ObjectIdInterface

  • ≪ MongoDB\BSON\ObjectIdInterface::getTimestamp
  • MongoDB\BSON\RegexInterface ≫
  • PHP Manual
  • MongoDB\BSON\ObjectIdInterface
  • Returns the hexidecimal representation of this ObjectIdInterface

MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface

説明

abstract public MongoDB\BSON\ObjectIdInterface::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hexidecimal representation of this ObjectIdInterface.

参考

  • MongoDB\BSON\ObjectId::__toString() - Returns the hexidecimal representation of this ObjectId


The MongoDB\BSON\RegexInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Regex to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\RegexInterface {
/* メソッド */
abstract public getFlags(): string
abstract public getPattern(): string
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags
  • MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern
  • MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface


Returns the RegexInterface's flags

  • ≪ MongoDB\BSON\RegexInterface
  • MongoDB\BSON\RegexInterface::getPattern ≫
  • PHP Manual
  • MongoDB\BSON\RegexInterface
  • Returns the RegexInterface's flags

MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags

説明

abstract public MongoDB\BSON\RegexInterface::getFlags(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the RegexInterface's flags.

参考

  • MongoDB\BSON\Regex::getFlags() - Returns the Regex's flags


Returns the RegexInterface's pattern

  • ≪ MongoDB\BSON\RegexInterface::getFlags
  • MongoDB\BSON\RegexInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\RegexInterface
  • Returns the RegexInterface's pattern

MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern

説明

abstract public MongoDB\BSON\RegexInterface::getPattern(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the RegexInterface's pattern.

参考

  • MongoDB\BSON\Regex::getPattern() - Returns the Regex's pattern


Returns the string representation of this RegexInterface

  • ≪ MongoDB\BSON\RegexInterface::getPattern
  • MongoDB\BSON\TimestampInterface ≫
  • PHP Manual
  • MongoDB\BSON\RegexInterface
  • Returns the string representation of this RegexInterface

MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface

説明

abstract public MongoDB\BSON\RegexInterface::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this RegexInterface.

参考

  • MongoDB\BSON\Regex::__toString() - Returns the string representation of this Regex


The MongoDB\BSON\TimestampInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\Timestamp to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\TimestampInterface {
/* メソッド */
abstract public getIncrement(): int
abstract public getTimestamp(): int
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface
  • MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface
  • MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface


Returns the increment component of this TimestampInterface

  • ≪ MongoDB\BSON\TimestampInterface
  • MongoDB\BSON\TimestampInterface::getTimestamp ≫
  • PHP Manual
  • MongoDB\BSON\TimestampInterface
  • Returns the increment component of this TimestampInterface

MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface

説明

abstract public MongoDB\BSON\TimestampInterface::getIncrement(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the increment component of this TimestampInterface.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

参考

  • MongoDB\BSON\Timestamp::getIncrement() - Returns the increment component of this Timestamp


Returns the timestamp component of this TimestampInterface

  • ≪ MongoDB\BSON\TimestampInterface::getIncrement
  • MongoDB\BSON\TimestampInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\TimestampInterface
  • Returns the timestamp component of this TimestampInterface

MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface

説明

abstract public MongoDB\BSON\TimestampInterface::getTimestamp(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the timestamp component of this TimestampInterface.

警告

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

参考

  • MongoDB\BSON\Timestamp::getTimestamp() - Returns the timestamp component of this Timestamp


Returns the string representation of this TimestampInterface

  • ≪ MongoDB\BSON\TimestampInterface::getTimestamp
  • MongoDB\BSON\UTCDateTimeInterface ≫
  • PHP Manual
  • MongoDB\BSON\TimestampInterface
  • Returns the string representation of this TimestampInterface

MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface

説明

abstract public MongoDB\BSON\TimestampInterface::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this TimestampInterface.

参考

  • MongoDB\BSON\Timestamp::__toString() - Returns the string representation of this Timestamp


The MongoDB\BSON\UTCDateTimeInterface interface

(mongodb >=1.3.0)

はじめに

This interface is implemented by MongoDB\BSON\UTCDateTime to be used as a parameter, return, or property type in userland classes.

クラス概要

class MongoDB\BSON\UTCDateTimeInterface {
/* メソッド */
abstract public toDateTime(): DateTime
abstract public __toString(): string
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface
  • MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface


Returns the DateTime representation of this UTCDateTimeInterface

  • ≪ MongoDB\BSON\UTCDateTimeInterface
  • MongoDB\BSON\UTCDateTimeInterface::__toString ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTimeInterface
  • Returns the DateTime representation of this UTCDateTimeInterface

MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface

説明

abstract public MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the DateTime representation of this UTCDateTimeInterface. The returned DateTime should use the UTC time zone.

参考

  • MongoDB\BSON\UTCDateTime::toDateTime() - Returns the DateTime representation of this UTCDateTime


Returns the string representation of this UTCDateTimeInterface

  • ≪ MongoDB\BSON\UTCDateTimeInterface::toDateTime
  • MongoDB\BSON\DBPointer ≫
  • PHP Manual
  • MongoDB\BSON\UTCDateTimeInterface
  • Returns the string representation of this UTCDateTimeInterface

MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

説明

abstract public MongoDB\BSON\UTCDateTimeInterface::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this UTCDateTimeInterface.

参考

  • MongoDB\BSON\UTCDateTime::__toString() - Returns the string representation of this UTCDateTime


The MongoDB\BSON\DBPointer class (deprecated)

(mongodb >=1.4.0)

はじめに

BSON type for the "DBPointer" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON DBPointer type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

クラス概要

final class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final private __construct()
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

目次

  • MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)
  • MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\DBPointer::serialize — Serialize a DBPointer
  • MongoDB\BSON\DBPointer::__toString — Returns an empty string
  • MongoDB\BSON\DBPointer::unserialize — Unserialize a DBPointer


Construct a new DBPointer (unused)

  • ≪ MongoDB\BSON\DBPointer
  • MongoDB\BSON\DBPointer::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Construct a new DBPointer (unused)

MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)

説明

final private MongoDB\BSON\DBPointer::__construct()

MongoDB\BSON\DBPointer objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\DBPointer::__construct
  • MongoDB\BSON\DBPointer::serialize ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Returns a representation that can be converted to JSON

MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\DBPointer::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\DBPointer.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a DBPointer

  • ≪ MongoDB\BSON\DBPointer::jsonSerialize
  • MongoDB\BSON\DBPointer::__toString ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Serialize a DBPointer

MongoDB\BSON\DBPointer::serialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::serialize — Serialize a DBPointer

説明

final public MongoDB\BSON\DBPointer::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\DBPointer.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\DBPointer::unserialize() - Unserialize a DBPointer
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns an empty string

  • ≪ MongoDB\BSON\DBPointer::serialize
  • MongoDB\BSON\DBPointer::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Returns an empty string

MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Returns an empty string

説明

final public MongoDB\BSON\DBPointer::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an empty string.

参考

  • » BSON Types


Unserialize a DBPointer

  • ≪ MongoDB\BSON\DBPointer::__toString
  • MongoDB\BSON\Int64 ≫
  • PHP Manual
  • MongoDB\BSON\DBPointer
  • Unserialize a DBPointer

MongoDB\BSON\DBPointer::unserialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::unserialize — Unserialize a DBPointer

説明

final public MongoDB\BSON\DBPointer::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\DBPointer.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\DBPointer::serialize() - Serialize a DBPointer
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Int64 class

(mongodb >=1.5.0)

はじめに

BSON type for a 64-bit integer. When decoding BSON to PHP data, this class is used when a 64-bit integer cannot be represented as a PHP integer on 32-bit platforms. These objects support overloaded arithmetic, bitwise, and comparison operators.

When working with raw BSON data through the MongoDB\BSON\Document, MongoDB\BSON\PackedArray, and MongoDB\BSON\Iterator classes, any 64-bit integer will be returned as an instance of this class, regardless of platform and whether the value can be represented as a PHP integer. This ensures that values can be roundtripped without changing the type.

During BSON encoding, objects of this class will convert back to a 64-bit integer type, even when the value would fit in a 32-bit integer. This allows explicitly storing values as 64-bit integers in BSON.

クラス概要

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final public __construct(int|string $value)
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.16.0 | The class can now be instantiated on all platforms. Added support for overloaded arithmetic, bitwise, and comparison operators.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

目次

  • MongoDB\BSON\Int64::__construct — Construct a new Int64
  • MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Int64::serialize — Serialize an Int64
  • MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64
  • MongoDB\BSON\Int64::unserialize — Unserialize an Int64


Construct a new Int64

  • ≪ MongoDB\BSON\Int64
  • MongoDB\BSON\Int64::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Construct a new Int64

MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Construct a new Int64

説明

final public MongoDB\BSON\Int64::__construct(int|string $value)

Creates a new MongoDB\BSON\Int64 instance for the given integer value.

パラメータ

value (int|string)

The value to assign to the Int64 instance. This value can be provided as an int or string, the latter being required on 32-bit platforms to represent 64-bit values.

変更履歴

バージョン | 説明
PECL mongodb 1.16.0 | This method was made public to support creating Int64 instances when working with raw BSON.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if string value cannot be parsed as a 64-bit integer.

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Int64::__construct
  • MongoDB\BSON\Int64::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Int64::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Int64.

注意: The output is consistent with the MongoDB\BSON\toCanonicalExtendedJSON() function, which uses the » canonical extended JSON format. This differs from other BSON classes, which use the driver-specific legacy extended JSON format (MongoDB\BSON\toJSON()), in order to ensure that the 64-bit integer value is correctly represented on 32-bit platforms.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize an Int64

  • ≪ MongoDB\BSON\Int64::jsonSerialize
  • MongoDB\BSON\Int64::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Serialize an Int64

MongoDB\BSON\Int64::serialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::serialize — Serialize an Int64

説明

final public MongoDB\BSON\Int64::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Int64.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Int64::unserialize() - Unserialize an Int64
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the string representation of this Int64

  • ≪ MongoDB\BSON\Int64::serialize
  • MongoDB\BSON\Int64::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Returns the string representation of this Int64

MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64

説明

final public MongoDB\BSON\Int64::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this Int64.

例

例1 MongoDB\BSON\Int64::__toString() example

<?php

$int64 = new MongoDB\BSON\Int64('9223372036854775807');

var_dump((string) $int64);

?>

上の例の出力は、 たとえば以下のようになります。

string(19) "9223372036854775807"

参考

  • » BSON Types


Unserialize an Int64

  • ≪ MongoDB\BSON\Int64::__toString
  • MongoDB\BSON\Symbol ≫
  • PHP Manual
  • MongoDB\BSON\Int64
  • Unserialize an Int64

MongoDB\BSON\Int64::unserialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::unserialize — Unserialize an Int64

説明

final public MongoDB\BSON\Int64::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Int64.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
  • Throws MongoDB\Driver\Exception\UnexpectedValueException if the properties cannot be unserialized (i.e. serialized was malformed).
  • Throws MongoDB\Driver\Exception\InvalidArgumentException if the properties are invalid (e.g. missing fields or invalid values).

参考

  • MongoDB\BSON\Int64::serialize() - Serialize an Int64
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Symbol class (deprecated)

(mongodb >=1.4.0)

はじめに

BSON type for the "Symbol" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON symbol type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

クラス概要

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final private __construct()
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

目次

  • MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)
  • MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Symbol::serialize — Serialize a Symbol
  • MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string
  • MongoDB\BSON\Symbol::unserialize — Unserialize a Symbol


Construct a new Symbol (unused)

  • ≪ MongoDB\BSON\Symbol
  • MongoDB\BSON\Symbol::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Construct a new Symbol (unused)

MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)

説明

final private MongoDB\BSON\Symbol::__construct()

MongoDB\BSON\Symbol objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Symbol::__construct
  • MongoDB\BSON\Symbol::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Symbol::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Symbol.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Symbol

  • ≪ MongoDB\BSON\Symbol::jsonSerialize
  • MongoDB\BSON\Symbol::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Serialize a Symbol

MongoDB\BSON\Symbol::serialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::serialize — Serialize a Symbol

説明

final public MongoDB\BSON\Symbol::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Symbol.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Symbol::unserialize() - Unserialize a Symbol
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns the Symbol as a string

  • ≪ MongoDB\BSON\Symbol::serialize
  • MongoDB\BSON\Symbol::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Returns the Symbol as a string

MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string

説明

final public MongoDB\BSON\Symbol::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string representation of this Symbol.

参考

  • » BSON Types


Unserialize a Symbol

  • ≪ MongoDB\BSON\Symbol::__toString
  • MongoDB\BSON\Undefined ≫
  • PHP Manual
  • MongoDB\BSON\Symbol
  • Unserialize a Symbol

MongoDB\BSON\Symbol::unserialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::unserialize — Unserialize a Symbol

説明

final public MongoDB\BSON\Symbol::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Symbol.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Symbol::serialize() - Serialize a Symbol
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


The MongoDB\BSON\Undefined class (deprecated)

(mongodb >=1.4.0)

はじめに

BSON type for the "Undefined" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON undefined type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

クラス概要

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable {
/* メソッド */
final private __construct()
final public jsonSerialize(): mixed
final public serialize(): string
final public __toString(): string
final public unserialize(string $data): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

目次

  • MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)
  • MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON
  • MongoDB\BSON\Undefined::serialize — Serialize a Undefined
  • MongoDB\BSON\Undefined::__toString — Returns an empty string
  • MongoDB\BSON\Undefined::unserialize — Unserialize a Undefined


Construct a new Undefined (unused)

  • ≪ MongoDB\BSON\Undefined
  • MongoDB\BSON\Undefined::jsonSerialize ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Construct a new Undefined (unused)

MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)

説明

final private MongoDB\BSON\Undefined::__construct()

MongoDB\BSON\Undefined objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。

参考

  • » BSON Types


Returns a representation that can be converted to JSON

  • ≪ MongoDB\BSON\Undefined::__construct
  • MongoDB\BSON\Undefined::serialize ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Returns a representation that can be converted to JSON

MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON

説明

final public MongoDB\BSON\Undefined::jsonSerialize(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Undefined.

注意: The output is consistent with the MongoDB\BSON\toJSON() function, which uses the driver-specific legacy extended JSON format. This does not necessarily match the » relaxed or » canonical extended JSON representations used by MongoDB\BSON\toRelaxedExtendedJSON() and MongoDB\BSON\toCanonicalExtendedJSON(), respectively.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • JsonSerializable::jsonSerialize() - JSON にシリアライズしたいデータを指定する
  • json_encode() - 値を JSON 形式にして返す
  • MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
  • MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
  • » MongoDB Extended JSON


Serialize a Undefined

  • ≪ MongoDB\BSON\Undefined::jsonSerialize
  • MongoDB\BSON\Undefined::__toString ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Serialize a Undefined

MongoDB\BSON\Undefined::serialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::serialize — Serialize a Undefined

説明

final public MongoDB\BSON\Undefined::serialize(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the serialized representation of the MongoDB\BSON\Undefined.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Undefined::unserialize() - Unserialize a Undefined
  • serialize() - 値の保存可能な表現を生成する
  • Serializing Objects


Returns an empty string

  • ≪ MongoDB\BSON\Undefined::serialize
  • MongoDB\BSON\Undefined::unserialize ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Returns an empty string

MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Returns an empty string

説明

final public MongoDB\BSON\Undefined::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an empty string.

参考

  • » BSON Types


Unserialize a Undefined

  • ≪ MongoDB\BSON\Undefined::__toString
  • MongoDB\Driver\Monitoring ≫
  • PHP Manual
  • MongoDB\BSON\Undefined
  • Unserialize a Undefined

MongoDB\BSON\Undefined::unserialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::unserialize — Unserialize a Undefined

説明

final public MongoDB\BSON\Undefined::unserialize(string $data): void

パラメータ

data

The serialized MongoDB\BSON\Undefined.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\BSON\Undefined::serialize() - Serialize a Undefined
  • unserialize() - 保存用表現から PHP の値を生成する
  • Serializing Objects


Monitoring classes and subscriber functions

  • 関数
    • MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally
    • MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally
  • MongoDB\Driver\Monitoring\CommandFailedEvent — The MongoDB\Driver\Monitoring\CommandFailedEvent class
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Returns the server connection ID for the command
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Returns the load balancer service ID for the command
  • MongoDB\Driver\Monitoring\CommandStartedEvent — The MongoDB\Driver\Monitoring\CommandStartedEvent class
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Returns the server connection ID for the command
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Returns the load balancer service ID for the command
  • MongoDB\Driver\Monitoring\CommandSucceededEvent — The MongoDB\Driver\Monitoring\CommandSucceededEvent class
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Returns the server connection ID for the command
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Returns the load balancer service ID for the command
  • MongoDB\Driver\Monitoring\ServerChangedEvent — The MongoDB\Driver\Monitoring\ServerChangedEvent class
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server
  • MongoDB\Driver\Monitoring\ServerClosedEvent — The MongoDB\Driver\Monitoring\ServerClosedEvent class
    • MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server
  • MongoDB\Driver\Monitoring\ServerOpeningEvent — The MongoDB\Driver\Monitoring\ServerOpeningEvent class
    • MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Returns the heartbeat's duration in microseconds
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Returns the heartbeat's duration in microseconds
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Returns whether the heartbeat used a streaming protocol
  • MongoDB\Driver\Monitoring\TopologyChangedEvent — The MongoDB\Driver\Monitoring\TopologyChangedEvent class
    • MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Returns the new description for the topology
    • MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology
    • MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID
  • MongoDB\Driver\Monitoring\TopologyClosedEvent — The MongoDB\Driver\Monitoring\TopologyClosedEvent class
    • MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID
  • MongoDB\Driver\Monitoring\TopologyOpeningEvent — The MongoDB\Driver\Monitoring\TopologyOpeningEvent class
    • MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID
  • MongoDB\Driver\Monitoring\CommandSubscriber — The MongoDB\Driver\Monitoring\CommandSubscriber interface
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command
  • MongoDB\Driver\Monitoring\LogSubscriber — The MongoDB\Driver\Monitoring\LogSubscriber interface
    • MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message
  • MongoDB\Driver\Monitoring\SDAMSubscriber — The MongoDB\Driver\Monitoring\SDAMSubscriber interface
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Notification method for closing a server
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Notification method for a failed server heartbeat
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Notification method for a started server heartbeat
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Notification method for a successful server heartbeat
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Notification method for opening a server
    • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Notification method for a topology description change
    • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Notification method for closing the topology
    • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Notification method for opening the topology
  • MongoDB\Driver\Monitoring\Subscriber — The MongoDB\Driver\Monitoring\Subscriber interface


関数

目次

  • MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally
  • MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally


Registers a monitoring event subscriber globally

  • ≪ 関数
  • MongoDB\Driver\Monitoring\removeSubscriber ≫
  • PHP Manual
  • 関数
  • Registers a monitoring event subscriber globally

MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally

説明

MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void

Registers a monitoring event subscriber globally. The subscriber will be notified of all events in the extension for any Manager.

注意: If subscriber is already registered globally, this function is a no-op. If subscriber is also registered with one or more Managers, it will still only be notified once of each event for each Manager.

パラメータ

subscriber (MongoDB\Driver\Monitoring\Subscriber)

A monitoring event subscriber to register globally.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\removeSubscriber() - Unregisters a monitoring event subscriber globally
  • MongoDB\Driver\Monitoring\Subscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
  • Application Performance Monitoring (APM)


Unregisters a monitoring event subscriber globally

  • ≪ MongoDB\Driver\Monitoring\addSubscriber
  • MongoDB\Driver\Monitoring\CommandFailedEvent ≫
  • PHP Manual
  • 関数
  • Unregisters a monitoring event subscriber globally

MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally

説明

MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber $subscriber): void

Unregisters a monitoring event subscriber globally.

注意: If subscriber is not already registered globally, this function is a no-op.

パラメータ

subscriber (MongoDB\Driver\Monitoring\Subscriber)

A monitoring event subscriber to unregister globally.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Monitoring\Subscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Manager::removeSubscriber() - Unregisters a monitoring event subscriber with this Manager
  • Application Performance Monitoring (APM)


The MongoDB\Driver\Monitoring\CommandFailedEvent class

(mongodb >=1.3.0)

はじめに

The MongoDB\Driver\Monitoring\CommandFailedEvent class encapsulates information about a failed command.

クラス概要

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* メソッド */
final public getCommandName(): string
final public getDatabaseName(): string
final public getDurationMicros(): int
final public getError(): Exception
final public getOperationId(): string
final public getReply(): object
final public getRequestId(): string
final public getServer(): MongoDB\Driver\Server
final public getServerConnectionId(): ?int
final public getServiceId(): ?MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Returns the database on which the command was executed
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Returns the server connection ID for the command
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Returns the load balancer service ID for the command


Returns the command name

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command name

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Returns the command name (e.g. "find", "aggregate").

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command name.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the database on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the database on which the command was executed

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Returns the database on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the database on which the command was executed.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the command's duration in microseconds

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getError ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command's duration in microseconds

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros(): int

The command's duration is a calculated value that includes the time to send the message and receive the reply from the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's duration in microseconds.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the Exception associated with the failed command

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the Exception associated with the failed command

MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Exception associated with the failed command.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the command's operation ID

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getError
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command's operation ID

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId(): string

The operation ID is generated by the extension and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level.

注意: Since multiple commands may share the same operation ID, it is not reliable to use this value to associate event objects with each other. The request ID returned by MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() should be used instead.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's operation ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)


Returns the command reply document

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command reply document

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getReply(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command reply document as a stdClass object.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)
  • Persisting Data


Returns the command's request ID

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getReply
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the command's request ID

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId(): string

The request ID is generated by the extension and may be used to associate this MongoDB\Driver\Monitoring\CommandFailedEvent with a previous MongoDB\Driver\Monitoring\CommandStartedEvent.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's request ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)


Returns the Server on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the Server on which the command was executed

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server on which the command was executed.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Returns the Server on which the command was executed
  • Application Performance Monitoring (APM)


Returns the server connection ID for the command

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getServer
  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the server connection ID for the command

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Returns the server connection ID for the command

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId(): ?int

Returns the server connection ID for the command. The server connection ID is distinct from server (i.e. MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) and is returned in the "connectionId" field of a hello command response MongoDB 4.2+.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the server connection ID, or null if it is not available.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the load balancer service ID for the command

  • ≪ MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId
  • MongoDB\Driver\Monitoring\CommandStartedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • Returns the load balancer service ID for the command

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Returns the load balancer service ID for the command

説明

final public MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

When the driver is connected to a MongoDB cluster through a load balancer, the service ID corresponds to the serviceId field in the hello command response.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the load balancer service ID, or null if the driver is not connected to a load balancer.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\CommandStartedEvent class

(mongodb >=1.3.0)

はじめに

The MongoDB\Driver\Monitoring\CommandStartedEvent class encapsulates information about a started command.

クラス概要

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* メソッド */
final public getCommand(): object
final public getCommandName(): string
final public getDatabaseName(): string
final public getOperationId(): string
final public getRequestId(): string
final public getServer(): MongoDB\Driver\Server
final public getServerConnectionId(): ?int
final public getServiceId(): ?MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Returns the server connection ID for the command
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Returns the load balancer service ID for the command


Returns the command document

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command document

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command document as a stdClass object.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)
  • Persisting Data


Returns the command name

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command name

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Returns the command name (e.g. "find", "aggregate").

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command name.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the database on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the database on which the command was executed

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the database on which the command was executed.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the command's operation ID

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command's operation ID

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId(): string

The operation ID is generated by the extension and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level.

注意: Since multiple commands may share the same operation ID, it is not reliable to use this value to associate event objects with each other. The request ID returned by MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() should be used instead.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's operation ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId() - Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId() - Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)


Returns the command's request ID

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the command's request ID

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId(): string

The request ID is generated by the extension and may be used to associate this MongoDB\Driver\Monitoring\CommandStartedEvent with a later MongoDB\Driver\Monitoring\CommandFailedEvent or MongoDB\Driver\Monitoring\CommandSucceededEvent.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's request ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)


Returns the Server on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the Server on which the command was executed

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server on which the command was executed.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer() - Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer() - Returns the Server on which the command was executed
  • Application Performance Monitoring (APM)


Returns the server connection ID for the command

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getServer
  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the server connection ID for the command

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Returns the server connection ID for the command

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId(): ?int

Returns the server connection ID for the command. The server connection ID is distinct from server (i.e. MongoDB\Driver\Monitoring\CommandStartedEvent::getServer()) and is returned in the "connectionId" field of a hello command response MongoDB 4.2+.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the server connection ID, or null if it is not available.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the load balancer service ID for the command

  • ≪ MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId
  • MongoDB\Driver\Monitoring\CommandSucceededEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • Returns the load balancer service ID for the command

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Returns the load balancer service ID for the command

説明

final public MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

When the driver is connected to a MongoDB cluster through a load balancer, the service ID corresponds to the serviceId field in the hello command response.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the load balancer service ID, or null if the driver is not connected to a load balancer.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\CommandSucceededEvent class

(mongodb >=1.3.0)

はじめに

The MongoDB\Driver\Monitoring\CommandSucceededEvent class encapsulates information about a successful command.

クラス概要

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* メソッド */
final public getCommandName(): string
final public getDatabaseName(): string
final public getDurationMicros(): int
final public getOperationId(): string
final public getReply(): object
final public getRequestId(): string
final public getServer(): MongoDB\Driver\Server
final public getServerConnectionId(): ?int
final public getServiceId(): ?MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Returns the database on which the command was executed
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Returns the server connection ID for the command
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Returns the load balancer service ID for the command


Returns the command name

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command name

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Returns the command name (e.g. "find", "aggregate").

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command name.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the database on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the database on which the command was executed

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Returns the database on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the database on which the command was executed.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the command's duration in microseconds

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command's duration in microseconds

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros(): int

The command's duration is a calculated value that includes the time to send the message and receive the reply from the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's duration in microseconds.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)


Returns the command's operation ID

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command's operation ID

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId(): string

The operation ID is generated by the extension and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level.

注意: Since multiple commands may share the same operation ID, it is not reliable to use this value to associate event objects with each other. The request ID returned by MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() should be used instead.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's operation ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Returns the command's operation ID
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)


Returns the command reply document

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command reply document

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command reply document as a stdClass object.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)
  • Persisting Data


Returns the command's request ID

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the command's request ID

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId(): string

The request ID is generated by the extension and may be used to associate this MongoDB\Driver\Monitoring\CommandSucceededEvent with a previous MongoDB\Driver\Monitoring\CommandStartedEvent.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the command's request ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
  • Application Performance Monitoring (APM)


Returns the Server on which the command was executed

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the Server on which the command was executed

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the MongoDB\Driver\Server on which the command was executed.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Returns the Server on which the command was executed
  • MongoDB\Driver\Cursor::getServer() - Returns the server associated with this cursor
  • MongoDB\Driver\WriteResult::getServer() - Returns the server associated with this write result
  • Application Performance Monitoring (APM)


Returns the server connection ID for the command

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer
  • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the server connection ID for the command

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Returns the server connection ID for the command

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId(): ?int

Returns the server connection ID for the command. The server connection ID is distinct from server (i.e. MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer()) and is returned in the "connectionId" field of a hello command response MongoDB 4.2+.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the server connection ID, or null if it is not available.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the load balancer service ID for the command

  • ≪ MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId
  • MongoDB\Driver\Monitoring\ServerChangedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • Returns the load balancer service ID for the command

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Returns the load balancer service ID for the command

説明

final public MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId(): ?MongoDB\BSON\ObjectId

When the driver is connected to a MongoDB cluster through a load balancer, the service ID corresponds to the serviceId field in the hello command response.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the load balancer service ID, or null if the driver is not connected to a load balancer.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\ServerChangedEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\ServerChangedEvent class encapsulates information about a changed server description.

クラス概要

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* メソッド */
final public getHost(): string
final public getNewDescription(): MongoDB\Driver\ServerDescription
final public getPort(): int
final public getPreviousDescription(): MongoDB\Driver\ServerDescription
final public getTopologyId(): MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Returns the hostname of the server
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server


Returns the hostname of the server

  • ≪ MongoDB\Driver\Monitoring\ServerChangedEvent
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerChangedEvent
  • Returns the hostname of the server

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Returns the hostname of the server

説明

final public MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the new description for the server

  • ≪ MongoDB\Driver\Monitoring\ServerChangedEvent::getHost
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerChangedEvent
  • Returns the new description for the server

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server

説明

final public MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the new MongoDB\Driver\ServerDescription for the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerChangedEvent
  • Returns the port on which this server is listening

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the previous description for the server

  • ≪ MongoDB\Driver\Monitoring\ServerChangedEvent::getPort
  • MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerChangedEvent
  • Returns the previous description for the server

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server

説明

final public MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the previous MongoDB\Driver\ServerDescription for the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the topology ID associated with this server

  • ≪ MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription
  • MongoDB\Driver\Monitoring\ServerClosedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerChangedEvent
  • Returns the topology ID associated with this server

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server

説明

final public MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the topology ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\ServerClosedEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\ServerClosedEvent class encapsulates information about a closed server.

クラス概要

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* メソッド */
final public getHost(): string
final public getPort(): int
final public getTopologyId(): MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Returns the hostname of the server
  • MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server


Returns the hostname of the server

  • ≪ MongoDB\Driver\Monitoring\ServerClosedEvent
  • MongoDB\Driver\Monitoring\ServerClosedEvent::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerClosedEvent
  • Returns the hostname of the server

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Returns the hostname of the server

説明

final public MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Monitoring\ServerClosedEvent::getHost
  • MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerClosedEvent
  • Returns the port on which this server is listening

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the topology ID associated with this server

  • ≪ MongoDB\Driver\Monitoring\ServerClosedEvent::getPort
  • MongoDB\Driver\Monitoring\ServerOpeningEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerClosedEvent
  • Returns the topology ID associated with this server

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server

説明

final public MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the topology ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\ServerOpeningEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\ServerOpeningEvent class encapsulates information about an opened server.

クラス概要

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* メソッド */
final public getHost(): string
final public getPort(): int
final public getTopologyId(): MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Returns the hostname of the server
  • MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server


Returns the hostname of the server

  • ≪ MongoDB\Driver\Monitoring\ServerOpeningEvent
  • MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerOpeningEvent
  • Returns the hostname of the server

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Returns the hostname of the server

説明

final public MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost
  • MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerOpeningEvent
  • Returns the port on which this server is listening

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the topology ID associated with this server

  • ≪ MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerOpeningEvent
  • Returns the topology ID associated with this server

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server

説明

final public MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the topology ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class encapsulates information about a failed server heartbeat.

クラス概要

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* メソッド */
final public getDurationMicros(): int
final public getError(): Exception
final public getHost(): string
final public getPort(): int
final public isAwaited(): bool
}

目次

  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Returns the heartbeat's duration in microseconds
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol


Returns the heartbeat's duration in microseconds

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • Returns the heartbeat's duration in microseconds

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Returns the heartbeat's duration in microseconds

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros(): int

The heartbeat's duration is a calculated value that includes the time to send the message and receive the reply from the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the heartbeat's duration in microseconds.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the Exception associated with the failed heartbeat

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • Returns the Exception associated with the failed heartbeat

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the Exception associated with the failed heartbeat.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the hostname of the server

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • Returns the hostname of the server

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • Returns the port on which this server is listening

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns whether the heartbeat used a streaming protocol

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • Returns whether the heartbeat used a streaming protocol

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited(): bool

Returns whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return false.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns false.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class encapsulates information about a started server heartbeat.

クラス概要

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* メソッド */
final public getHost(): string
final public getPort(): int
final public isAwaited(): bool
}

目次

  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Returns the hostname of the server
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol


Returns the hostname of the server

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  • Returns the hostname of the server

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Returns the hostname of the server

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  • Returns the port on which this server is listening

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns whether the heartbeat used a streaming protocol

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  • Returns whether the heartbeat used a streaming protocol

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited(): bool

Returns whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return false.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns false.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class encapsulates information about a successful server heartbeat.

クラス概要

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* メソッド */
final public getDurationMicros(): int
final public getHost(): string
final public getPort(): int
final public getReply(): object
final public isAwaited(): bool
}

目次

  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Returns the heartbeat's duration in microseconds
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Returns the port on which this server is listening
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Returns whether the heartbeat used a streaming protocol


Returns the heartbeat's duration in microseconds

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • Returns the heartbeat's duration in microseconds

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Returns the heartbeat's duration in microseconds

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros(): int

The heartbeat's duration is a calculated value that includes the time to send the message and receive the reply from the server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the heartbeat's duration in microseconds.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the hostname of the server

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • Returns the hostname of the server

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the hostname of the server.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the port on which this server is listening

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • Returns the port on which this server is listening

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Returns the port on which this server is listening

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the port on which this server is listening.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the heartbeat reply document

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • Returns the heartbeat reply document

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the heartbeat reply document as a stdClass object.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • Application Performance Monitoring (APM)
  • Persisting Data


Returns whether the heartbeat used a streaming protocol

  • ≪ MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply
  • MongoDB\Driver\Monitoring\TopologyChangedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • Returns whether the heartbeat used a streaming protocol

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

説明

final public MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited(): bool

Returns whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return false.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns false.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\TopologyChangedEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\TopologyChangedEvent class encapsulates information about a changed topology description.

クラス概要

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* メソッド */
final public getNewDescription(): MongoDB\Driver\TopologyDescription
final public getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public getTopologyId(): MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Returns the new description for the topology
  • MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology
  • MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID


Returns the new description for the topology

  • ≪ MongoDB\Driver\Monitoring\TopologyChangedEvent
  • MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\TopologyChangedEvent
  • Returns the new description for the topology

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Returns the new description for the topology

説明

final public MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the new MongoDB\Driver\TopologyDescription for the topology.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the previous description for the topology

  • ≪ MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription
  • MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\TopologyChangedEvent
  • Returns the previous description for the topology

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology

説明

final public MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the previous MongoDB\Driver\TopologyDescription for the topology.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


Returns the topology ID

  • ≪ MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription
  • MongoDB\Driver\Monitoring\TopologyClosedEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\TopologyChangedEvent
  • Returns the topology ID

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID

説明

final public MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the topology ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\TopologyClosedEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\TopologyClosedEvent class encapsulates information about a closed topology.

クラス概要

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* メソッド */
final public getTopologyId(): MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID


Returns the topology ID

  • ≪ MongoDB\Driver\Monitoring\TopologyClosedEvent
  • MongoDB\Driver\Monitoring\TopologyOpeningEvent ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\TopologyClosedEvent
  • Returns the topology ID

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID

説明

final public MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the topology ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\TopologyOpeningEvent class

(mongodb >=1.13.0)

はじめに

The MongoDB\Driver\Monitoring\TopologyOpeningEvent class encapsulates information about an opened topology.

クラス概要

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* メソッド */
final public getTopologyId(): MongoDB\BSON\ObjectId
}

目次

  • MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID


Returns the topology ID

  • ≪ MongoDB\Driver\Monitoring\TopologyOpeningEvent
  • MongoDB\Driver\Monitoring\CommandSubscriber ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\TopologyOpeningEvent
  • Returns the topology ID

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID

説明

final public MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the topology ID.

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.


The MongoDB\Driver\Monitoring\CommandSubscriber interface

(mongodb >=1.3.0)

はじめに

Classes may implement this interface to register an event subscriber that is notified for each started, successful, and failed command event. See Application Performance Monitoring (APM) for additional information.

インターフェイス概要

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* メソッド */
abstract public commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void
abstract public commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event): void
abstract public commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command
  • MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command
  • MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command


Notification method for a failed command

  • ≪ MongoDB\Driver\Monitoring\CommandSubscriber
  • MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • Notification method for a failed command

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command

説明

abstract public MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void

If the subscriber is registered, this method is called when a command fails.

パラメータ

event (MongoDB\Driver\Monitoring\CommandFailedEvent)

An event object encapsulating information about the failed command.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandFailedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
  • Application Performance Monitoring (APM)


Notification method for a started command

  • ≪ MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed
  • MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • Notification method for a started command

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command

説明

abstract public MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event): void

If the subscriber is registered, this method is called when a command is sent to the server.

パラメータ

event (MongoDB\Driver\Monitoring\CommandStartedEvent)

An event object encapsulating information about the started command.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandStartedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
  • Application Performance Monitoring (APM)


Notification method for a successful command

  • ≪ MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted
  • MongoDB\Driver\Monitoring\LogSubscriber ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\CommandSubscriber
  • Notification method for a successful command

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command

説明

abstract public MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void

If the subscriber is registered, this method is called when a command succeeds.

パラメータ

event (MongoDB\Driver\Monitoring\CommandSucceededEvent)

An event object encapsulating information about the successful command.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\CommandSucceededEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
  • Application Performance Monitoring (APM)


The MongoDB\Driver\Monitoring\LogSubscriber interface

(mongodb >=1.17.0)

はじめに

Classes implementing this interface may be registered as a subscriber and receive log messages from the extension. This is similar to stream-based debug logging (i.e. mongodb.debug) except that trace-level log messages are not received.

As with stream-based logging, it is only possible to register a logger globally using MongoDB\Driver\Monitoring\addSubscriber(). The extension is not able to distinguish log messages for individual MongoDB\Driver\Manager objects.

インターフェイス概要

class MongoDB\Driver\Monitoring\LogSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* 定数 */
const int LEVEL_ERROR = 0;
const int LEVEL_CRITICAL = 1;
const int LEVEL_WARNING = 2;
const int LEVEL_MESSAGE = 3;
const int LEVEL_INFO = 4;
const int LEVEL_DEBUG = 5;
/* メソッド */
abstract public log(int $level, string $domain, string $message): void
}

定義済み定数

MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_ERROR

Error log level. An error condition that the extension is unable to report through its API. This is the most severe log level in the extension.

MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_CRITICAL

Critical log level. An error condition with slightly less severity. This constant exists for consistency with libmongoc; however, the extension is unlikely to use it in practice.

MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_WARNING

Warning log level. Indicates a situation where undesirable application behavior may occur.

MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_MESSAGE

Message or notice log level. Indicates an event that is unusual but not problematic.

MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_INFO

Info log level. High-level information about normal driver behavior.

MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_DEBUG

Debug log level. Detailed information that may be helpful when debugging an application.

目次

  • MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message


Notification method for a log message

  • ≪ MongoDB\Driver\Monitoring\LogSubscriber
  • MongoDB\Driver\Monitoring\SDAMSubscriber ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\LogSubscriber
  • Notification method for a log message

MongoDB\Driver\Monitoring\LogSubscriber::log

(mongodb >=1.17.0)

MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message

説明

abstract public MongoDB\Driver\Monitoring\LogSubscriber::log(int $level, string $domain, string $message): void

If the subscriber is registered, this method is called for each logged message.

パラメータ

level

The severity level. This will be one of the interface constants.

domain

The name of the driver component that emitted the log message.

message

The log message.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally


The MongoDB\Driver\Monitoring\SDAMSubscriber interface

(mongodb >=1.13.0)

はじめに

Classes may implement this interface to register an event subscriber that is notified for various SDAM events. See the » Server Discovery and Monitoring and » SDAM Monitoring specifications for additional information.

インターフェイス概要

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* メソッド */
abstract public serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void
abstract public serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void
abstract public serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void
abstract public serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void
abstract public serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void
abstract public serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void
abstract public topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void
abstract public topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void
abstract public topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.15.0 | Return types for methods are declared as tentative on PHP 8.0 and newer, triggering deprecation notices in code that implements this interface without declaring the appropriate return types. The #[ReturnTypeWillChange] attribute can be added to silence the deprecation notice.

目次

  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Notification method for closing a server
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Notification method for a failed server heartbeat
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Notification method for a started server heartbeat
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Notification method for a successful server heartbeat
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Notification method for opening a server
  • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Notification method for a topology description change
  • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Notification method for closing the topology
  • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Notification method for opening the topology


Notification method for a server description change

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for a server description change

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void

If the subscriber is registered, this method is called when a server's description changes.

パラメータ

event (MongoDB\Driver\Monitoring\ServerChangedEvent)

An event object encapsulating information about the changed server description.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\ServerChangedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for closing a server

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for closing a server

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Notification method for closing a server

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void

If the subscriber is registered, this method is called when a server is closed.

パラメータ

event (MongoDB\Driver\Monitoring\ServerClosedEvent)

An event object encapsulating information about the closed server.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\ServerClosedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for a failed server heartbeat

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for a failed server heartbeat

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Notification method for a failed server heartbeat

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void

If the subscriber is registered, this method is called when a server heartbeat (i.e. » hello command issued through » server monitoring) fails.

パラメータ

event (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)

An event object encapsulating information about the failed server heartbeat.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for a started server heartbeat

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for a started server heartbeat

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Notification method for a started server heartbeat

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void

If the subscriber is registered, this method is called when a server heartbeat (i.e. » hello command issued through » server monitoring) is sent to the server.

パラメータ

event (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)

An event object encapsulating information about the started server heartbeat.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for a successful server heartbeat

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted
  • MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for a successful server heartbeat

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Notification method for a successful server heartbeat

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void

If the subscriber is registered, this method is called when a server heartbeat (i.e. » hello command issued through » server monitoring) succeeds.

パラメータ

event (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)

An event object encapsulating information about the successful server heartbeat.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for opening a server

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded
  • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for opening a server

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Notification method for opening a server

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void

If the subscriber is registered, this method is called when a server is opened.

パラメータ

event (MongoDB\Driver\Monitoring\ServerOpeningEvent)

An event object encapsulating information about the opened server.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\ServerOpeningEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for a topology description change

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening
  • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for a topology description change

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Notification method for a topology description change

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void

If the subscriber is registered, this method is called when the topology's description changes.

パラメータ

event (MongoDB\Driver\Monitoring\TopologyChangedEvent)

An event object encapsulating information about the changed topology description.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\TopologyChangedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for closing the topology

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged
  • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for closing the topology

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Notification method for closing the topology

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void

If the subscriber is registered, this method is called when the topology is closed.

パラメータ

event (MongoDB\Driver\Monitoring\TopologyClosedEvent)

An event object encapsulating information about the closed topology.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\TopologyClosedEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


Notification method for opening the topology

  • ≪ MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed
  • MongoDB\Driver\Monitoring\Subscriber ≫
  • PHP Manual
  • MongoDB\Driver\Monitoring\SDAMSubscriber
  • Notification method for opening the topology

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Notification method for opening the topology

説明

abstract public MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void

If the subscriber is registered, this method is called when the topology is opened.

パラメータ

event (MongoDB\Driver\Monitoring\TopologyOpeningEvent)

An event object encapsulating information about the opened topology.

戻り値

値を返しません。

エラー / 例外

  • Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

参考

  • MongoDB\Driver\Monitoring\TopologyOpeningEvent
  • MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
  • MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager


The MongoDB\Driver\Monitoring\Subscriber interface

(mongodb >=1.3.0)

はじめに

Base interface for event subscribers. This is used as a parameter type in the functions MongoDB\Driver\Monitoring\addSubscriber() and MongoDB\Driver\Monitoring\removeSubscriber() and should not be implemented directly.

インターフェイス概要

class MongoDB\Driver\Monitoring\Subscriber {
}

This interface has no methods. Its only purpose is to be the base interface for all event subscribers.


Exception classes

  • MongoDB\Driver\Exception\AuthenticationException — The MongoDB\Driver\Exception\AuthenticationException class
  • MongoDB\Driver\Exception\BulkWriteException — The MongoDB\Driver\Exception\BulkWriteException class
  • MongoDB\Driver\Exception\CommandException — The MongoDB\Driver\Exception\CommandException class
    • MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command
  • MongoDB\Driver\Exception\ConnectionException — The MongoDB\Driver\Exception\ConnectionException class
  • MongoDB\Driver\Exception\ConnectionTimeoutException — The MongoDB\Driver\Exception\ConnectionTimeoutException class
  • MongoDB\Driver\Exception\EncryptionException — The MongoDB\Driver\Exception\EncryptionException class
  • MongoDB\Driver\Exception\Exception — The MongoDB\Driver\Exception\Exception interface
  • MongoDB\Driver\Exception\ExecutionTimeoutException — The MongoDB\Driver\Exception\ExecutionTimeoutException class
  • MongoDB\Driver\Exception\InvalidArgumentException — The MongoDB\Driver\Exception\InvalidArgumentException class
  • MongoDB\Driver\Exception\LogicException — The MongoDB\Driver\Exception\LogicException class
  • MongoDB\Driver\Exception\RuntimeException — The MongoDB\Driver\Exception\RuntimeException class
    • MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception
  • MongoDB\Driver\Exception\ServerException — The MongoDB\Driver\Exception\ServerException class
  • MongoDB\Driver\Exception\SSLConnectionException — The MongoDB\Driver\Exception\SSLConnectionException class (deprecated)
  • MongoDB\Driver\Exception\UnexpectedValueException — The MongoDB\Driver\Exception\UnexpectedValueException class
  • MongoDB\Driver\Exception\WriteException — The MongoDB\Driver\Exception\WriteException class
    • MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation
  • Class Tree — MongoDB Exception Class Tree


The MongoDB\Driver\Exception\AuthenticationException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver fails to authenticate with the server.

クラス概要

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\BulkWriteException class

(mongodb >= 1.0.0)

はじめに

Thrown when a bulk write operation fails.

クラス概要

class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\WriteException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected MongoDB\Driver\WriteResult $writeResult;
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\CommandException class

(mongodb >= 1.5.0)

はじめに

Thrown when a command fails.

クラス概要

class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
protected object $resultDocument;
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
final public getResultDocument(): object
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

resultDocument

The result document associated with the failed command.

目次

  • MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command


Returns the result document for the failed command

  • ≪ MongoDB\Driver\Exception\CommandException
  • MongoDB\Driver\Exception\ConnectionException ≫
  • PHP Manual
  • MongoDB\Driver\Exception\CommandException
  • Returns the result document for the failed command

MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

説明

final public MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Returns the result document for the failed command.

パラメータ

この関数にはパラメータはありません。

戻り値

The result document for the failed command.

参考

  • MongoDB\Driver\Manager::executeCommand() - Execute a database command


The MongoDB\Driver\Exception\ConnectionException class

(mongodb >= 1.0.0)

はじめに

Base class for exceptions thrown when the driver fails to establish a database connection.

クラス概要

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\ConnectionTimeoutException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver fails to establish a database connection within a specified time limit (connectTimeoutMS) or server selection fails (serverSelectionTimeoutMS).

クラス概要

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\EncryptionException class

(mongodb >= 1.7.0)

はじめに

Base class for exceptions thrown during client-side encryption.

クラス概要

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\Exception interface

(mongodb >= 1.0.0)

はじめに

Common interface for all extension exceptions. This interface is also used by the library, and may be used to identify any exceptions originating from the MongoDB PHP driver (i.e. extension and library).

クラス概要

class MongoDB\Driver\Exception\Exception {
}


The MongoDB\Driver\Exception\ExecutionTimeoutException class

(mongodb >= 1.0.0)

はじめに

Thrown when a query or command fails to complete within a specified time limit (e.g. » maxTimeMS).

クラス概要

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

変更履歴

バージョン | 説明
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.


The MongoDB\Driver\Exception\InvalidArgumentException class

(mongodb >= 1.0.0)

はじめに

Thrown when a driver method is given invalid arguments (e.g. invalid option types).

クラス概要

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\LogicException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver is incorrectly used (e.g. rewinding a cursor).

クラス概要

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\RuntimeException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver encounters a runtime error (e.g. internal error from » libmongoc).

クラス概要

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
protected ?array $errorLabels;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
final public hasErrorLabel(string $errorLabel): bool
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

errorLabels

Contains an array of error labels to go with an exception. For example, error labels can be used to detect whether a transaction can be retried safely if the TransientTransactionError label is present. The existence of a specific error label should be tested for with the MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(), instead of interpreting this errorLabels property manually.

変更履歴

バージョン | 説明
PECL mongodb 1.6.0 | The MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() method and MongoDB\Driver\Exception\RuntimeException::errorLabels property have been added.

目次

  • MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception


Returns whether an error label is associated with an exception

  • ≪ MongoDB\Driver\Exception\RuntimeException
  • MongoDB\Driver\Exception\ServerException ≫
  • PHP Manual
  • MongoDB\Driver\Exception\RuntimeException
  • Returns whether an error label is associated with an exception

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

説明

final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool

Returns whether the errorLabel has been set for this exception. Error labels are set by either the server or the extension to indicate specific situations that may be handled by an application. A common situation might be determining whether to safely retry a transaction that failed due to a transient error (e.g. network error, transaction conflict). Examples of error labels are TransientTransactionError and UnknownTransactionCommitResult.

パラメータ

errorLabel

The name of the errorLabel to test for.

戻り値

Whether the given errorLabel is associated with this exception.

参考

  • MongoDB\Driver\Session::commitTransaction() - Commits a transaction
  • » MongoDB documentation on transactions


The MongoDB\Driver\Exception\ServerException class

(mongodb >= 1.5.0)

はじめに

Base class for exceptions thrown by the server. The code of this exception and its subclasses will correspond to the original error code from the server.

クラス概要

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\SSLConnectionException class (deprecated)

(mongodb >= 1.0.0)

警告

This exception class is deprecated and may be removed in a future major version. The extension has never thrown this exception.

はじめに

Thrown when the driver fails to establish an SSL connection with the server.

クラス概要

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\UnexpectedValueException class

(mongodb >= 1.0.0)

はじめに

Thrown when the driver encounters an unexpected value (e.g. during BSON serialization or deserialization).

クラス概要

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The MongoDB\Driver\Exception\WriteException class

(mongodb >= 1.0.0)

はじめに

Base class for exceptions thrown by a failed write operation. The exception encapsulates a MongoDB\Driver\WriteResult object.

クラス概要

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
protected MongoDB\Driver\WriteResult $writeResult;
/* 継承したプロパティ */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
final public getWriteResult(): MongoDB\Driver\WriteResult
/* 継承したメソッド */
final public MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string $errorLabel): bool
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

writeResult

The MongoDB\Driver\WriteResult associated with the failed write operation.

変更履歴

バージョン | 説明
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.

目次

  • MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation


Returns the WriteResult for the failed write operation

  • ≪ MongoDB\Driver\Exception\WriteException
  • Class Tree ≫
  • PHP Manual
  • MongoDB\Driver\Exception\WriteException
  • Returns the WriteResult for the failed write operation

MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

説明

final public MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult

Returns the MongoDB\Driver\WriteResult for the failed write operation. The MongoDB\Driver\WriteResult::getWriteErrors() and MongoDB\Driver\WriteResult::getWriteConcernError() methods may be used to get more details about the failure.

パラメータ

この関数にはパラメータはありません。

戻り値

The MongoDB\Driver\WriteResult for the failed write operation.

例

例1 MongoDB\Driver\Exception\WriteException::getWriteResult() example

<?php

$manager = new MongoDB\Driver\Manager('mongodb://localhost');
$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 1]);

try {
$manager->executeBulkWrite('db.collection', $bulk);
} catch (MongoDB\Driver\Exception\WriteException $e) {
$writeResult = $e->getWriteResult();

if ($writeConcernError = $writeResult->getWriteConcernError()) {
var_dump($writeConcernError);
}

if ($writeErrors = $writeResult->getWriteErrors()) {
var_dump($writeErrors);
}
}

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  object(MongoDB\Driver\WriteError)#5 (4) {
    ["message"]=>
    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
    ["code"]=>
    int(11000)
    ["index"]=>
    int(1)
    ["info"]=>
    NULL
  }
}

参考

  • MongoDB\Driver\WriteResult
  • MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations


MongoDB Exception Class Tree

The class hierarchy for MongoDB exceptions is modeled after that of the SPL Exceptions. Base classes extend their SPL counterpart and all exception classes in the extension implement the MongoDB\Driver\Exception\Exception interface.

  • MongoDB\Driver\Exception\LogicException (extends LogicException)
  • MongoDB\Driver\Exception\InvalidArgumentException (extends InvalidArgumentException)
  • MongoDB\Driver\Exception\UnexpectedValueException (extends UnexpectedValueException)
  • MongoDB\Driver\Exception\RuntimeException (extends RuntimeException)
    • MongoDB\Driver\Exception\ConnectionException
      • MongoDB\Driver\Exception\AuthenticationException
      • MongoDB\Driver\Exception\ConnectionTimeoutException
      • MongoDB\Driver\Exception\SSLConnectionException (deprecated)
    • MongoDB\Driver\Exception\EncryptionException
    • MongoDB\Driver\Exception\ServerException
      • MongoDB\Driver\Exception\CommandException
      • MongoDB\Driver\Exception\ExecutionTimeoutException
      • MongoDB\Driver\Exception\WriteException
        • MongoDB\Driver\Exception\BulkWriteException


MySQL ドライバおよびプラグイン

PHP で MySQL を扱うためのドライバやプラグインには、いくつかの種類があります。

それらの違いや MySQL 用拡張モジュールの機能について、ここで簡単に説明します。

ここで説明している拡張モジュールは、MySQL プロトコルをサポートしています。 それと互換性のあるデータベースサーバーは、 » MariaDB Server, » MySQL Server, » Percona Server for MySQL, » TiDB です。

  • MySQL 用 PHP ドライバの概要
    • はじめに
    • 用語説明
    • どの API を使うか
    • どのライブラリを選ぶか
    • コンセプト
  • MySQLi — MySQL 改良版拡張モジュール
    • はじめに
    • mysqli の概要
    • クイックスタートガイド
    • インストール/設定
    • mysqli 拡張モジュールでの持続的接続
    • 定義済み定数
    • ノート
    • The MySQLi Extension Function Summary
    • mysqli — mysqli クラス
    • mysqli_stmt — mysqli_stmt クラス
    • mysqli_result — mysqli_result クラス
    • mysqli_driver — mysqli_driver クラス
    • mysqli_warning — mysqli_warning クラス
    • mysqli_sql_exception — mysqli_sql_exception クラス
    • エイリアスおよび非推奨の Mysqli 関数
    • 変更履歴
  • Mysql_xdevapi
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 変更履歴
    • 例
    • Mysql_xdevapi 関数
    • mysql_xdevapi\BaseResult — BaseResult クラス
    • mysql_xdevapi\Client — クライアントクラス
    • mysql_xdevapi\Collection — Collection クラス
    • mysql_xdevapi\CollectionAdd — CollectionAdd クラス
    • mysql_xdevapi\CollectionFind — CollectionFind クラス
    • mysql_xdevapi\CollectionModify — CollectionModify クラス
    • mysql_xdevapi\CollectionRemove — CollectionRemove クラス
    • mysql_xdevapi\ColumnResult — ColumnResult クラス
    • mysql_xdevapi\CrudOperationBindable — CrudOperationBindable インターフェイス
    • mysql_xdevapi\CrudOperationLimitable — CrudOperationLimitable インターフェイス
    • mysql_xdevapi\CrudOperationSkippable — CrudOperationSkippable インターフェイス
    • mysql_xdevapi\CrudOperationSortable — CrudOperationSortable インターフェイス
    • mysql_xdevapi\DatabaseObject — DatabaseObject インターフェイス
    • mysql_xdevapi\DocResult — DocResult クラス
    • mysql_xdevapi\Exception — Exception クラス
    • mysql_xdevapi\Executable — Executable インターフェイス
    • mysql_xdevapi\ExecutionStatus — ExecutionStatus クラス
    • mysql_xdevapi\Expression — Expression クラス
    • mysql_xdevapi\Result — Result クラス
    • mysql_xdevapi\RowResult — RowResult クラス
    • mysql_xdevapi\Schema — Schema クラス
    • mysql_xdevapi\SchemaObject — SchemaObject インターフェイス
    • mysql_xdevapi\Session — Session クラス
    • mysql_xdevapi\SqlStatement — SqlStatement クラス
    • mysql_xdevapi\SqlStatementResult — SqlStatementResult クラス
    • mysql_xdevapi\Statement — Statement クラス
    • mysql_xdevapi\Table — Table クラス
    • mysql_xdevapi\TableDelete — TableDelete クラス
    • mysql_xdevapi\TableInsert — TableInsert クラス
    • mysql_xdevapi\TableSelect — TableSelect クラス
    • mysql_xdevapi\TableUpdate — TableUpdate クラス
    • mysql_xdevapi\Warning — Warning クラス
  • MySQL (最初の API) — 最初の MySQL API
    • はじめに
    • インストール/設定
    • 変更履歴
    • 定義済み定数
    • 例
    • MySQL 関数
  • Mysqlnd — MySQL Native Driver
    • はじめに
    • 概要
    • インストール
    • 実行時設定
    • 非互換性
    • 持続的接続
    • Statistics
    • メモ
    • メモリ管理
    • MySQL Native Driver プラグインAPI


MySQL 用 PHP ドライバの概要

  • はじめに
  • 用語説明
  • どの API を使うか
  • どのライブラリを選ぶか
  • コンセプト
    • バッファクエリと非バッファクエリ
    • 文字セット


はじめに

PHP から MySQL データベースにアクセスするための API は複数あります。 mysqli あるいは PDO_MySQL が利用できます。

このページでは、これらの API についての説明に登場する 用語 について解説したり、 いったいどの API を使えばいいのか を説明したり、選んだ API と組み合わせる MySQL の ライブラリ について説明したりします。


用語説明

このセクションでは、PHP アプリケーションの開発で MySQL データベースを扱う ときの選択肢について説明します。

API って何?

API は Application Programming Interface の略で、 何らかのタスクを実行するためにアプリケーションから呼び出す必要のある クラスやメソッド、関数、変数などを定義したものです。 データベースとの通信を必要とする PHP アプリケーションが使うための API は、通常は PHP の拡張モジュールとして公開されています。

API は手続き型にすることもできるし、オブジェクト指向型にすることもできます。 手続き型の API の場合は何かの処理を実行するための関数を呼ぶことになり、 オブジェクト指向型の API の場合はクラスのインスタンスを作ってそのメソッドを呼ぶことになります。 通常は、後者の方法をおすすめします。後者のほうがよりモダンであり、 きっちりとしたコードを書けるからです。

MySQL サーバーとの接続が必要な PHP アプリケーションを書く場合に 使える API はいくつかあって、その中から選べます。 このドキュメントでは、どんな API が使えてどれを選ぶのが最適なのかを解説します。

コネクタとは

MySQL のドキュメントで使われている コネクタ という用語は、 何かのアプリケーションから MySQL データベースサーバーに接続するためのソフトウェアのことを指します。 MySQL はさまざまな言語用のコネクタを提供しており、PHP もその中に含まれます。

PHP のアプリケーションでデータベースサーバーとの通信が必要になったときには、 データベースサーバーへの接続やデータベースへの問い合わせなどの関数を呼ぶ PHP コードを書くことになるでしょう。つまり、PHP アプリケーションから使える API を提供するソフトウェアが必要になるということです。 そのソフトウェアは、アプリケーションとデータベースサーバーの間の通信も処理しないといけません。 おそらくは中間ライブラリも利用することになるでしょう。 このソフトウェアのことを一般的にコネクタと呼びます。というのも、このソフトウェアのおかげで アプリケーションがデータベースサーバーに 接続 (connect) できるようになるからです。

ドライバとは

ドライバとは、特定のデータベースサーバーとの通信をするために作られたソフトウェアのことです。 ドライバはライブラリと呼ばれることもあり、 MySQL Client Library や MySQL Native Driver というように使われます。 これらのライブラリが実装するのは低レベルのプロトコルで、 これを使って MySQL データベースサーバーと通信します。

例を挙げると、データベース抽象化レイヤーの PHP Data Objects (PDO) は各データベース専用のドライバの中からひとつを選んで使います。 数あるドライバの中のひとつに PDO MYSQL ドライバがあり、これが MySQL サーバーとのインターフェイスとなります。

人によっては、コネクタとドライバを混同して使うこともあって、混乱の元となります。 MySQL 関連のドキュメントでは、 コネクタ という用語はデータベース固有の機能を提供するソフトウェアという意味で 予約されています。

拡張モジュールとは

PHP のドキュメントを読んでいると、 拡張モジュール という用語がよく出てきます。 PHP のコードには、コア機能とは別に オプションの拡張モジュールが用意されています。 PHP で使える MySQL 関連の拡張モジュールには mysqli があり、 PHP の拡張モジュール用フレームワークを使って実装されています。

拡張モジュールは一般的に PHP プログラマー向けの API を公開しており、 その機能をプログラムから使えるようになっています。 しかし、PHP 拡張モジュールフレームワークを使って書かれた拡張モジュールの中には、 PHP プログラマー向けの API を公開していないものもあります。

たとえば PDO MySQL ドライバは PHP の拡張モジュールですが、 それ自体は PHP プログラマー向けの API を公開していません。 さらに上位にある PDO レイヤーへのインターフェイスを提供しているだけです。

API と拡張モジュールとは同じ意味ではありません。 拡張モジュールが必ずしもプログラマー向けの API を公開しているとは限らないからです。


どの API を使うか

PHP には、様々な MySQL へ接続する API があります。 以下に、mysqli と PDO が提供する API を示します。 それぞれのコードは、"example.com" 上で稼働する MySQL サーバーに ユーザー名 "user"、パスワード "password" で接続するものです。 そして、クエリを実行してユーザーにあいさつします。

例1 MySQL 用 API の比較

<?php
// mysqli
$mysqli = new mysqli("example.com", "user", "password", "database");
$result = $mysqli->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = $result->fetch_assoc();
echo htmlentities($row['_message']);

// PDO
$pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
$statement = $pdo->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = $statement->fetch(PDO::FETCH_ASSOC);
echo htmlentities($row['_message']);

例2 プリペアドステートメントの比較

<?php
// mysqli
$mysqli = new mysqli("example.com", "user", "password", "database");
$statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
$statement->execute(["Amersfoort"]);
$result = $statement->get_result();
$row = $result->fetch_assoc();
echo htmlentities($row['District']);

// PDO
$pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
$statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
$statement->execute(["Amersfoort"]);
$row = $statement->fetch(PDO::FETCH_ASSOC);
echo htmlentities($row['District']);

機能の比較

全体的なパフォーマンスは、どれもほぼ同じです。 拡張モジュール自体のパフォーマンスが PHP のウェブリクエストの実行時間に及ぼす影響はごくわずかで、 たいていは 0.1% 程度に過ぎません。

 | ext/mysqli | PDO_MySQL
どのバージョンの PHP から使えるか | 5.0 | 5.1
PHP 7.x と PHP 8.x に同梱されているか | Yes | Yes
開発状況 | 進行中 | 進行中
ライフサイクル | 活動中 | 活動中
新規開発でおすすめできるか | Yes | Yes
オブジェクト指向のインターフェイス | Yes | Yes
手続き型のインターフェイス | Yes | No
mysqlnd によるノンブロッキングな非同期クエリ | Yes | No
持続的接続 | Yes | Yes
文字セット | Yes | Yes
サーバーサイドのプリペアドステートメント | Yes | Yes
クライアントサイドのプリペアドステートメント | No | Yes
ストアドプロシージャ | Yes | Yes
複数ステートメント | Yes | Most
トランザクション | Yes | Yes
SQL によるトランザクション制御 | Yes | Yes
MySQL 5.1+ の全機能への対応 | Yes | Most


どのライブラリを選ぶか

mysqli、PDO_MySQL といった PHP 拡張モジュールは、 どれも C クライアントライブラリの軽量なラッパーです。これらの拡張モジュールは、 mysqlnd ライブラリあるいは libmysqlclient ライブラリのいずれかを使えます。どちらを使うのかを決めるのは、コンパイル時です。

mysqlnd ライブラリは、PHP の一部として配布されています。 遅延接続やクエリのキャッシュなど、libmysqlclient にはない機能も搭載されているので、 この mysqlnd ライブラリを使うことを強くおすすめします。 mysqlnd のドキュメント には、さらなる詳細情報や機能一覧があります。

例1 mysqlnd あるいは libmysqlclient を使う場合の configure コマンド

// おすすめの方法。mysqlnd を使ってコンパイルします。
$ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

// もうひとつのおすすめの方法。mysqlnd を使ってコンパイルします。
$ ./configure --with-mysqli --with-pdo-mysql

// おすすめしない方法。libmysqlclient を使ってコンパイルします。
$ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

ライブラリの機能比較

mysqlnd を使うほうが、 MySQL Client Server library (libmysqlclient) よりもおすすめです。 どちらのライブラリも、開発が続いています。

 | MySQL Native Driver (mysqlnd) | MySQL クライアントサーバーライブラリ (libmysqlclient)
PHP の配布物に同梱 | Yes | No
どのバージョンの PHP から使えるか | 5.3.0 | N/A
ライセンス | PHP License 3.01 | デュアルライセンス
開発状況 | 進行中 | 進行中
ライフサイクル | 終了予定なし | 終了予定なし
コンパイルのデフォルト (すべての MySQL 拡張モジュール) | Yes | No
圧縮プロトコルへの対応 | Yes | Yes
SSL への対応 | Yes | Yes
名前付きパイプへの対応 | Yes | Yes
ノンブロッキングの非同期クエリ | Yes | No
パフォーマンス統計 | Yes | No
LOAD LOCAL INFILE での open_basedir の反映 | Yes | No
PHP ネイティブのメモリ管理システムを使う (PHP のメモリ制限などに従う) | Yes | No
数値型のカラムを double 型で返す (COM_QUERY) | Yes | No
数値型のカラムを string 型で返す (COM_QUERY) | Yes | Yes
プラグイン API | Yes | Limited
自動再接続 | No | オプション


  • ≪ どのライブラリを選ぶか
  • バッファクエリと非バッファクエリ ≫
  • PHP Manual
  • MySQL 用 PHP ドライバの概要
  • コンセプト

コンセプト

目次

  • バッファクエリと非バッファクエリ
  • 文字セット

ここで説明する内容は、PHP 用の MySQL ドライバに固有の内容です。


バッファクエリと非バッファクエリ

クエリは、デフォルトではバッファモードで実行されます。 つまり、クエリの結果がすぐに MySQL サーバーから PHP に転送され、 PHP プロセスのメモリ内に結果を保持し続けるということです。 これで、その後で行数を数えたり結果ポインタを移動 (シーク) したりといった操作ができるようになります。 また、同じ接続上でさらに別のクエリを発行しつつ、 現在の結果セットを使った作業をすることもできます。 バッファモードの弱点は、結果セットが大きくなると大量にメモリを消費するということです。 結果セットへの参照がなくなるか、結果セットを明示的に解放する (リクエストを終了すると、自動的に解放されます) まではメモリ上に残り続けます。 バッファモードは「結果を格納する」クエリとも呼ばれます。 ここでは、結果セット全体が一度に格納されます。

注意:

ライブラリとして libmysqlclient を使っている場合は、結果セットのデータを PHP の変数に代入するまで結果セットのメモリ利用量が PHP のメモリ制限にカウントされません。 mysqlnd の場合は、結果セットのメモリがすべて PHP のメモリ制限にもカウントされます。

非バッファクエリは、クエリを実行してMySQLサーバーからデータを取得するのを待ちます。 PHP 側でのメモリ消費が少なくなりますが、サーバーへの負荷は高くなります。 サーバー上の結果セットからすべての結果を取得するまで、 同じ接続上で別のクエリを実行することはできません。 非バッファクエリは「結果を使う」クエリとも呼ばれます。 結果セットから全ての行が取得されると、 結果セットは削除されるので再度ループさせることはできません。

こういった特性を考慮すると、非バッファクエリを使うのは、 結果セットの量が巨大な場合や、順番に結果を処理する場合だけに留めるべきでしょう。 非バッファクエリには、たくさんの落とし穴があり、 そのため使い方が難しいです。 たとえば、結果セットの行数が最後の行を取得するまで不明な点が挙げられます。 バッファクエリは使い方が簡単で、 結果セットをより柔軟に処理できます。

デフォルトはバッファモードなので、以下の例では それぞれの API で非バッファクエリを実行する方法を示します。

例1 非バッファクエリの例: mysqli

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
$unbufferedResult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

foreach ($unbufferedResult as $row) {
echo $row['Name'] . PHP_EOL;
}
?>

例2 非バッファクエリの例: pdo_mysql

<?php
$pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
$pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

$unbufferedResult = $pdo->query("SELECT Name FROM City");
foreach ($unbufferedResult as $row) {
echo $row['Name'] . PHP_EOL;
}
?>


文字セット

適切な文字セットをサーバーレベルで設定しておくのが理想であり、MySQL のマニュアルの » Character Set Configuration にもそうするよう書かれています。 しかしそれ以外にも、各 MySQL API には実行時に文字セットを指定する方法が用意されています。

警告

文字セットと文字のエスケープ

文字セットはきちんと理解して設定しておかないといけません。 すべての操作に影響が及び、セキュリティの問題を引き起こす可能性があるからです。 たとえば、文字列のエスケープ (mysqli なら mysqli_real_escape_string()、 PDO_MySQL なら PDO::quote()) は文字セットの設定に従った動きをします。 これらの関数は、クエリで設定した文字セットは使わないことを知っておくことが大切です。 たとえば次の例のような設定をしても、エスケープ機能は正しく動きません。

例1 文字セットを SQL で指定することによる問題

<?php

$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

// これは $mysqli->real_escape_string(); に影響を及ぼしません
$mysqli->query("SET NAMES utf8mb4");

// これも $mysqli->real_escape_string(); に影響を及ぼしません
$mysqli->query("SET CHARACTER SET utf8mb4");

// しかしこの方法なら $mysqli->real_escape_string(); にもきちんと影響します
$mysqli->set_charset('utf8mb4');

// いっぽう、こちらは影響を及ぼしません (UTF-8 と utf8mb4 の違いに注目) -- ここではハイフンを使ってはいけません
$mysqli->set_charset('UTF-8');
?>

実行時に文字セットを変更する適切な方法を、各 API について示します。

注意: UTF-8 でありがちなミス

MySQL の文字セット名はハイフンを含まないので、MySQL で (3バイト以下の UTF-8 Unicode エンコーディング という意味の) UTF-8 を表す文字セットは "utf8" が正解です。"UTF-8" ではありません。そのため、 "UTF-8" と指定しても文字セットは変わらず、エラーが発生します。

例2 文字セットの設定: mysqli

<?php

$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

echo 'Initial character set: ' . $mysqli->character_set_name() . "\n";

if (!$mysqli->set_charset('utf8mb4')) {
printf("Error loading character set utf8mb4: %s\n", $mysqli->error);
exit;
}

echo 'Your current character set is: ' . $mysqli->character_set_name() . "\n";
?>

例3 文字セットの設定: pdo_mysql

<?php
$pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
?>


MySQL 改良版拡張モジュール

  • はじめに
  • mysqli の概要
  • クイックスタートガイド
    • 手続き型とオブジェクト指向インターフェイス
    • データベース接続
    • ステートメントの実行
    • プリペアドステートメント
    • ストアドプロシージャ
    • 複数のステートメント
    • トランザクションのサポート
    • メタデータ
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • mysqli 拡張モジュールでの持続的接続
  • 定義済み定数
  • ノート
  • The MySQLi Extension Function Summary
  • mysqli — mysqli クラス
    • mysqli::$affected_rows — 直前の MySQL の操作で変更された行の数を得る
    • mysqli::autocommit — データベース更新の自動コミットをオンまたはオフにする
    • mysqli::begin_transaction — トランザクションを開始する
    • mysqli::change_user — 指定されたデータベース接続のユーザー名を変更する
    • mysqli::character_set_name — データベース接続の現在の文字コードセットを返す
    • mysqli::close — 事前にオープンしているデータベース接続を閉じる
    • mysqli::commit — 現在のトランザクションをコミットする
    • mysqli::$connect_errno — 直近の接続コールに関するエラーコードを返す
    • mysqli::$connect_error — 直近の接続エラーの説明を返す
    • mysqli::__construct — 新規に MySQL サーバーへの接続をオープンする
    • mysqli::debug — デバッグ操作を行う
    • mysqli::dump_debug_info — デバッグ情報をログに出力する
    • mysqli::$errno — 直近の関数コールによるエラーコードを返す
    • mysqli::$error — 直近のエラーの内容を文字列で返す
    • mysqli::$error_list — 直近で実行したコマンドからのエラーの一覧を返す
    • mysqli::execute_query — SQL文を準備し、変数をバインドし、実行する
    • mysqli::$field_count — 直近のクエリのカラムの数を返す
    • mysqli::get_charset — 文字セットオブジェクトを返す
    • mysqli::$client_info — MySQL クライアント情報を取得する
    • mysqli::$client_version — MySQL クライアントのバージョンを整数値で返す
    • mysqli::get_connection_stats — クライアント接続に関する統計情報を返す
    • mysqli::$host_info — 使用している接続の型を文字列で返す
    • mysqli::$protocol_version — 使用している MySQL プロトコルのバージョンを返す
    • mysqli::$server_info — MySQL サーバーのバージョンを返す
    • mysqli::$server_version — MySQL サーバーのバージョンを整数値で返す
    • mysqli::get_warnings — SHOW WARNINGS の結果を取得する
    • mysqli::$info — 直近に実行されたクエリの情報を取得する
    • mysqli::init — MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
    • mysqli::$insert_id — 直近のクエリの AUTO_INCREMENT カラムで生成した値を返す
    • mysqli::kill — サーバーに MySQL スレッドの停止を問い合わせる
    • mysqli::more_results — マルチクエリからの結果がまだ残っているかどうかを調べる
    • mysqli::multi_query — データベース上でひとつ以上のクエリを実行する
    • mysqli::next_result — multi_query の、次の結果を準備する
    • mysqli::options — オプションを設定する
    • mysqli::ping — サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる
    • mysqli::poll — 接続を問い合わせる
    • mysqli::prepare — 実行するための SQL文 を準備する
    • mysqli::query — データベース上でクエリを実行する
    • mysqli::real_connect — mysql サーバーとの接続をオープンする
    • mysqli::real_escape_string — 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
    • mysqli::real_query — SQL クエリを実行する
    • mysqli::reap_async_query — 非同期クエリから結果を取得する
    • mysqli::refresh — リフレッシュする
    • mysqli::release_savepoint — 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する
    • mysqli::rollback — 現在のトランザクションをロールバックする
    • mysqli::savepoint — トランザクションのセーブポイントを設定する
    • mysqli::select_db — クエリを実行するためのデフォルトのデータベースを選択する
    • mysqli::set_charset — クライアントの文字セットを設定する
    • mysqli::$sqlstate — 直前の MySQL の操作での SQLSTATE エラーを返す
    • mysqli::ssl_set — SSL を使用したセキュアな接続を確立する
    • mysqli::stat — 現在のシステム状態を取得する
    • mysqli::stmt_init — ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す
    • mysqli::store_result — 直近のクエリから結果セットを転送する
    • mysqli::$thread_id — 現在の接続のスレッド ID を返す
    • mysqli::thread_safe — スレッドセーフであるかどうかを返す
    • mysqli::use_result — 結果セットの取得を開始する
    • mysqli::$warning_count — 指定した接続の直近のクエリから発生した警告の数を返す
  • mysqli_stmt — mysqli_stmt クラス
    • mysqli_stmt::$affected_rows — 直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す
    • mysqli_stmt::attr_get — ステートメントの属性の現在の値を取得する
    • mysqli_stmt::attr_set — プリペアドステートメントの振る舞いを変更する
    • mysqli_stmt::bind_param — プリペアドステートメントのパラメータに変数をバインドする
    • mysqli_stmt::bind_result — 結果を保存するため、プリペアドステートメントに変数をバインドする
    • mysqli_stmt::close — プリペアドステートメントを閉じる
    • mysqli_stmt::__construct — 新しい mysqli_stmt オブジェクトを構築する
    • mysqli_stmt::data_seek — バッファリングされた結果中の、任意の行にポインタを移動する
    • mysqli_stmt::$errno — 直近のステートメントのコールに関するエラーコードを返す
    • mysqli_stmt::$error — 直近のステートメントのエラー内容を文字列で返す
    • mysqli_stmt::$error_list — 直近で実行したステートメントからのエラーの一覧を返す
    • mysqli_stmt::execute — プリペアドステートメントを実行する
    • mysqli_stmt::fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する
    • mysqli_stmt::$field_count — 指定したステートメントのカラム数を返す
    • mysqli_stmt::free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する
    • mysqli_stmt::get_result — プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
    • mysqli_stmt::get_warnings — SHOW WARNINGS の結果を取得する
    • mysqli_stmt::$insert_id — 直近の INSERT 操作で生成した ID を取得する
    • mysqli_stmt::more_results — 複数クエリで、次の結果が存在するかどうかを調べる
    • mysqli_stmt::next_result — 複数クエリから、次の結果を読み込む
    • mysqli_stmt::$num_rows — サーバーから取得した結果セットの行数を返す
    • mysqli_stmt::$param_count — 指定したステートメントのパラメータ数を返す
    • mysqli_stmt::prepare — SQL ステートメントを実行するために準備する
    • mysqli_stmt::reset — プリペアドステートメントをリセットする
    • mysqli_stmt::result_metadata — プリペアドステートメントから結果セットのメタデータを返す
    • mysqli_stmt::send_long_data — データをブロックで送信する
    • mysqli_stmt::$sqlstate — 直前のステートメントの操作での SQLSTATE エラーを返す
    • mysqli_stmt::store_result — 内部バッファに結果を保存する
  • mysqli_result — mysqli_result クラス
    • mysqli_result::__construct — mysqli_result オブジェクトを構築する
    • mysqli_result::$current_field — 結果ポインタにおける現在のフィールドオフセットを取得する
    • mysqli_result::data_seek — 結果の任意の行にポインタを移動する
    • mysqli_result::fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する
    • mysqli_result::fetch_array — 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
    • mysqli_result::fetch_assoc — 結果セットの次の行を連想配列で取得する
    • mysqli_result::fetch_column — 結果セットの次の行から、単一のカラムの値を取得する
    • mysqli_result::fetch_field — 結果セットの次のフィールドを返す
    • mysqli_result::fetch_field_direct — 単一のフィールドのメタデータを取得する
    • mysqli_result::fetch_fields — 結果セットのフィールド情報をオブジェクトの配列で返す
    • mysqli_result::fetch_object — 結果セットの次の行を取得し、オブジェクトとして返す
    • mysqli_result::fetch_row — 結果セットの次の行を数値添字配列で取得する
    • mysqli_result::$field_count — 結果セットのフィールド数を取得する
    • mysqli_result::field_seek — 結果ポインタを、指定したフィールドオフセットに設定する
    • mysqli_result::free — 結果に関連付けられたメモリを開放する
    • mysqli_result::getIterator — 外部イテレータを取得する
    • mysqli_result::$lengths — 結果セットにおける現在の行のカラムの長さを返す
    • mysqli_result::$num_rows — 結果セットの行数を取得する
  • mysqli_driver — mysqli_driver クラス
    • mysqli_driver::embedded_server_end — 組み込みサーバーを停止する
    • mysqli_driver::embedded_server_start — 組み込みサーバーを初期化して開始する
    • mysqli_driver::$report_mode — mysqli のエラー報告モードを設定する
  • mysqli_warning — mysqli_warning クラス
    • mysqli_warning::__construct — インスタンス化を禁止するための private なコンストラクタ
    • mysqli_warning::next — 次の警告を取得する
  • mysqli_sql_exception — mysqli_sql_exception クラス
    • mysqli_sql_exception::getSqlState — SQLSTATE エラーコードを含む情報を返す
  • エイリアスおよび非推奨の Mysqli 関数
    • mysqli_connect — mysqli::__construct のエイリアス
    • mysqli::escape_string — mysqli_real_escape_string のエイリアス
    • mysqli_execute — mysqli_stmt_execute のエイリアス
    • mysqli_get_client_stats — プロセスごとのクライアントの統計を返す
    • mysqli_get_links_stats — オープン済みとキャッシュ済みのリンクに関する情報を返す
    • mysqli_report — mysqli_driver->report_mode のエイリアス
    • mysqli::set_opt — mysqli_options のエイリアス
  • 変更履歴


はじめに

mysqli 拡張サポートによって MySQL 4.1 以上で提供される機能を利用することができるようになります。MySQL データベースサーバーに関する詳細は » http://www.mysql.com/ をご覧ください。

PHP から MySQL を使うために使用できるソフトウェアの概要は mysqli の概要 にあります。

MySQL に関するドキュメントは » http://dev.mysql.com/doc/ にあります。

このドキュメントの一部は、Oracle Corporation の許可を得て MySQL マニュアルから引用したものです。

このドキュメントのサンプルでは、» world データベースあるいは » sakila データベースを使っています。どちらも、無料で公開されています。


mysqli の概要

このセクションでは、 PHP アプリケーションの開発で MySQL データベースを扱うときの選択肢について説明します。

API って何?

API は Application Programming Interface の略で、 何らかのタスクを実行するためにアプリケーションから呼び出す必要のある クラスやメソッド、関数、変数などを定義したものです。 データベースとの通信を必要とする PHP アプリケーションが使うための API は、 通常は PHP の拡張モジュールとして公開されています。

API は手続き型にすることもできるし、 オブジェクト指向型にすることもできます。 手続き型の API の場合は何かの処理を実行するための関数を呼ぶことになり、 オブジェクト指向型の API の場合はクラスのインスタンスを作ってそのメソッドを呼ぶことになります。 通常は、後者の方法をおすすめします。 後者のほうがよりモダンであり、 きっちりとしたコードを書けるからです。

MySQL サーバーとの接続が必要な PHP アプリケーションを書く場合に 使える API はいくつかあって、その中から選べます。 このドキュメントでは、 どんな API が使えてどれを選ぶのが最適なのかを解説します。

コネクタとは?

MySQL のドキュメントで使われている コネクタ という用語は、 何かのアプリケーションから MySQL データベースサーバーに接続するためのソフトウェアのことを指します。 MySQL はさまざまな言語用のコネクタを提供しており、 PHP もその中に含まれます。

PHP のアプリケーションで、 データベースサーバーとの通信が必要になったときには、 データベースサーバーへの接続やデータベースへの問い合わせなどの関数を呼ぶ PHP コードを書くことになるでしょう。 つまり、PHP アプリケーションから使える API を提供するソフトウェアが必要になるということです。 そのソフトウェアは、 アプリケーションとデータベースサーバーの間の通信も処理しないといけません。 おそらくは中間ライブラリも利用することになるでしょう。 このソフトウェアのことを一般的にコネクタと呼びます。 というのも、 このソフトウェアのおかげで アプリケーションがデータベースサーバーに 接続 (connect) できるようになるからです。

ドライバとは?

ドライバとは、 特定のデータベースサーバーとの通信をするために作られたソフトウェアのことです。 ドライバはライブラリと呼ばれることもあり、 MySQL Client Library や MySQL Native ドライバ というように使われます。 これらのライブラリが実装するのは低レベルのプロトコルで、 これを使って MySQL データベースサーバーと通信します。

例を挙げると、データベース抽象化レイヤーの PHP Data Objects (PDO) は各データベース専用のドライバの中からひとつを選んで使います。 数あるドライバの中のひとつに PDO MYSQL ドライバがあり、 これが MySQL サーバーとのインターフェイスとなります。

人によっては、コネクタとドライバを混同して使うこともあって、 混乱の元となります。 MySQL 関連のドキュメントでは、ドライバ という用語は、 コネクタパッケージのうち、 データベース固有の機能を提供するソフトウェアという意味で 予約されています。

拡張モジュールとは?

PHP のドキュメントを読んでいると、拡張モジュール という用語がよく出てきます。 PHP のコードには、コア機能とは別に オプションの拡張モジュールが用意されています。 PHP で使える MySQL 関連の拡張モジュールには mysqli や PDO MySQL があり、 PHP の拡張モジュール用フレームワークを使って実装されています。

拡張モジュールは一般的に PHP プログラマー向けの API を公開しており、 その機能をプログラムから使えるようになっています。 しかし、PHP 拡張モジュールフレームワークを使って書かれた拡張モジュールの中には、 PHP プログラマー向けの API を公開していないものもあります。

たとえば PDO MySQL ドライバは PHP の拡張モジュールですが、 それ自体は PHP プログラマー向けの API を公開していません。 さらに上位にある PDO レイヤーへのインターフェイスを提供しているだけです。

API と拡張モジュールとは同じ意味ではありません。 拡張モジュールが必ずしもプログラマー向けの API を公開しているとは限らないからです。

MySQL を使うために、提供されている主要な PHP API は何ですか?

MySQL データベースサーバーに接続することを検討する際、 ふたつの主要な選択肢があります:

  • PHP の mysqli 拡張モジュール

  • PHP Data Objects (PDO)

それぞれ、長所と短所があります。 以下の説明で、それぞれの API の重要な側面を簡単に説明していきます。

PHP の mysqli 拡張モジュールとは何ですか?

mysqli 拡張モジュール、 もしくは 改良版 MySQL 拡張モジュールとしても知られているものは、 MySQL のバージョン 4.1.3 以降の新機能を利用するために開発されました。 mysqli 拡張モジュールは、 PHP 5 以降にバンドルされています。

mysqli 拡張モジュールにはたくさんの利点がありますが、 mysql 拡張モジュールに対する、 主な改良点は下記のとおりです:

  • オブジェクト指向インターフェイス

  • プリペアドステートメントのサポート

  • 複数のステートメント実行をサポート

  • トランザクションのサポート

  • 強化されたデバッグ機能

オブジェクト指向インターフェイスと同時に、 手続き型のインターフェイスも提供されています。

mysqli 拡張モジュールは、 PHP の拡張モジュール用フレームワークを使って実装されています。 ソースコードは ext/mysqli 以下にあります。

mysqli 拡張モジュールについての詳細は、 MySQLi を参照ください。

PDO とは何ですか?

PHP Data Objects, または PDO は、PHP アプリケーションのための、特別なデータベース抽象化レイヤです。 PDO は、あなたのアプリケーションが接続するデータベースサーバーに関係なく、 一貫した API を提供します。 理屈の上では、PDO の API を使えば、 たとえば Firebird から MySQL にデータベースサーバーを切り替えることができます。 PHP コードに必要な変更は少なく済むでしょう。

データベース抽象化レイヤのその他の例としては、 Java の JDBC や、Perl の DBI が挙げられます。

PDO には、綺麗で、簡潔で、 移植可能な API であるという利点がある一方で、 最新の MySQL サーバーで利用可能な高度な機能を全て利用できるとは限らない、 という重要な欠点があります。 たとえば、PDO は MySQL がサポートしている 複数ステートメントの実行を許可していません。

PDO は、PHP の拡張モジュール用フレームワークを使って実装されています。 ソースコードは ext/pdo 以下にあります。

PDO についての詳細は、 PDO を参照ください。

PDO MYSQL ドライバ とは何ですか?

PDO MySQL ドライバ 自体は、 少なくとも PHP プログラマから見ると API ではありません。 実際には、 PDO MySQL ドライバ は PDO の直下のレイヤにあって、 MySQL 特有の機能を提供しているものです。 プログラマは、PDO の API を呼ぶことは変わりませんが、 PDO は MySQL サーバーと通信するために、 PDO MySQL ドライバを使うのです。

PDO MySQL ドライバは、 数ある PDO ドライバのうち、利用できるもののひとつです。 他の PDO ドライバとして、Firebird と PostgreSQL データベースサーバーのものが含まれています。

PDO MySQL ドライバは、 PHP の拡張モジュール用フレームワークを使って実装されています。 ソースコードは ext/pdo_mysql 以下にありますが、 その API は PHP プログラマには公開されていません。

PDO MySQL ドライバについての詳細は、 MySQL (PDO) を参照ください。

PHP の MySQL Native ドライバとは何ですか?

MySQL データベースサーバーと通信するために、 mysqli と PDO MySQL ドライバは、 それぞれ必須のプロトコルを実装している低レベルのライブラリを使っています。 かつては、その低レベルのライブラリとして利用可能だったのは、 libmysqlclient とも呼ばれている MySQL Client Library だけでした。

しかし、 libmysqlclient が提供していたインターフェイスは、 PHP アプリケーションとの通信に最適化されていませんでした。 なぜなら、libmysqlclient は、C言語 で書かれたアプリケーションを念頭に置いていたからです。 このため、PHP アプリケーションのための代替として、 libmysqlclient の代わりに、 MySQL Native ドライバ、mysqlnd が開発されたのです。

mysqli 拡張モジュール と PDO MySQL ドライバはそれぞれ、 libmysqlclient や mysqlnd のいずれかを使って個別に設定できます。 mysqlnd は、 PHP システムと統合するために特別に設計されているため、 libmysqlclient と比較して、 大幅な省メモリ化や高速化が実現されています。 これらの改善を利用することを強くお勧めします。

MySQL Native ドライバ は、 PHP 拡張モジュール用フレームワークを使って実装されています。 ソースコードは ext/mysqlnd 以下にありますが、 その API は PHP プログラマには公開されていません。

機能の比較

以下の表は、PHP から MySQL に接続する主要な方法に関する、 機能の比較を示しています:

PHP 向けの MySQL API の選択肢の比較
 | PHP の mysqli 拡張モジュール | PDO (PDO MySQL ドライバ と MySQL Native ドライバ を利用)
PHP で実装されたバージョン | 5.0 | 5.0
MySQL での開発状況 | アクティブ | アクティブ
文字セットに関するAPI のサポート | Yes | Yes
サーバー側でのプリペアドステートメントの API サポート | Yes | Yes
クライアントサイドでのプリペアドステートメントの API サポート | No | Yes
ストアドプロシージャの API のサポート | Yes | Yes
複数ステートメントの API のサポート | Yes | Most
MySQL 4.1以降の機能を全てサポートしているか | Yes | Most


クイックスタートガイド

目次

  • 手続き型とオブジェクト指向インターフェイス
  • データベース接続
  • ステートメントの実行
  • プリペアドステートメント
  • ストアドプロシージャ
  • 複数のステートメント
  • トランザクションのサポート
  • メタデータ

このクイックスタートガイドを読むと、 PHP の MySQL API に親しみ、選択するのに役立ちます。

このクイックスタートガイドは、 mysqli 拡張モジュールの概要を示しています。 コードの例は API の主要な機能を全て示しています。 データベースの概念についてのページでは、 MySQL に固有の概念について、必要な程度まで説明しています。

PHP 言語によるプログラミングと、SQL 言語、 そして MySQL サーバーの基礎に親しんでいることが必須です。


手続き型とオブジェクト指向インターフェイス

mysqli 拡張モジュールは、 ふたつのインターフェイスを提供しています。 手続き型とオブジェクト指向のインターフェイスです。

古い mysql 拡張モジュールから移行するユーザーは、 手続き型のインターフェイスを好むかもしれません。 手続き型のインターフェイスは、古い mysql 拡張モジュールのそれに似ています。 多くの場合、関数名はプレフィックスのみが異なりますが、 mysqli の関数によっては、最初の引数に接続ハンドルを取るものもあります。 一方で、それと一致する古い mysql 拡張モジュールのインターフェイスは、 オプションの接続ハンドルを最後にとるようになっています。

例1 古い mysql 拡張モジュールから移行する簡単な方法

<?php
$mysqli = mysqli_connect("example.com", "user", "password", "database");
$result = mysqli_query($mysqli, "SELECT 'Please do not use the deprecated mysql extension for new development. ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($result);
echo $row['_msg'];

$mysql = mysql_connect("example.com", "user", "password");
mysql_select_db("test");
$result = mysql_query("SELECT 'Use the mysqli extension instead.' AS _msg FROM DUAL", $mysql);
$row = mysql_fetch_assoc($result);
echo $row['_msg'];

上の例の出力は以下となります。

Please do not use the deprecated mysql extension for new development. Use the mysqli extension instead.

オブジェクト指向インターフェイス

伝統的な手続き型のインターフェイスに加えて、 ユーザーはオブジェクト指向インターフェイスを選ぶことができます。 このドキュメントは、 オブジェクト指向インターフェイスも使えるように整理されています。 オブジェクト指向インターフェイスは、 目的に応じてグループ化されていますし、 使い始めるのも簡単です。リファレンスのページでは、 手続き型に加えて、オブジェクト指向インターフェイスの使い方も示しています。

この2つのインターフェイスの間に、 目立ったパフォーマンスの違いはありません。 ユーザーは、自分の好みに応じてインターフェイスを選択できます。

例2 オブジェクト指向と手続き型のインターフェイス

<?php

$mysqli = mysqli_connect("example.com", "user", "password", "database");

$result = mysqli_query($mysqli, "SELECT 'A world full of ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($result);
echo $row['_msg'];

$mysqli = new mysqli("example.com", "user", "password", "database");

$result = $mysqli->query("SELECT 'choices to please everybody.' AS _msg FROM DUAL");
$row = $result->fetch_assoc();
echo $row['_msg'];

上の例の出力は以下となります。

A world full of choices to please everybody.

このクイックスタートガイドでは、 オブジェクト指向のインターフェイスを使います。 なぜなら、リファレンスのページが、そのように整理されているからです。

ふたつのスタイルを混ぜる

手続き型と、オブジェクト指向のやり方を切り替えることもできます。 これら両方のスタイルを混ぜることは、 コードの明確さやコーディングスタイルを統一する理由から、 推奨できません。

例3 悪いコーディングスタイル

<?php

$mysqli = new mysqli("example.com", "user", "password", "database");

$result = mysqli_query($mysqli, "SELECT 'Possible but bad style.' AS _msg FROM DUAL");

if ($row = $result->fetch_assoc()) {
echo $row['_msg'];
}

上の例の出力は以下となります。

Possible but bad style.

参照

  • mysqli::__construct()
  • mysqli::query()
  • mysqli_result::fetch_assoc()
  • $mysqli::connect_errno
  • $mysqli::connect_error
  • $mysqli::errno
  • $mysqli::error
  • The MySQLi Extension Function Summary


データベース接続

MySQL は、サーバーに接続するために、 異なるトランスポート層をサポートしています。 TCP/IP, Unix ドメインソケット、 そして、Windows の名前付きパイプです。

ホスト名 localhost には特別な意味があります。 これは、Unixドメインソケットにバインドされます。 localhost に対して TCP/IP 接続を開くには、 localhost の代わりに、 127.0.0.1 を使わなければいけません。

例1 localhost が持つ特別な意味

<?php

$mysqli = new mysqli("localhost", "user", "password", "database");

echo $mysqli->host_info . "\n";

$mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);

echo $mysqli->host_info . "\n";

上の例の出力は以下となります。

Localhost via UNIX socket
127.0.0.1 via TCP/IP

デフォルトの接続パラメータ

接続関数によっては、 引数を省略できる場合があります。 引数が与えられない場合、 拡張モジュールは PHP の設定ファイルに設定されたデフォルト値を使おうとします。

例2 デフォルト値を設定する

mysqli.default_host=192.168.2.27
mysqli.default_user=root
mysqli.default_pw=""
mysqli.default_port=3306
mysqli.default_socket=/tmp/mysql.sock

結果として決まった引数の値が、 拡張モジュールが使うクライアントライブラリに渡されます。 クライアントライブラリが空、または未設定の引数を検知した場合、 ライブラリに組み込まれたデフォルト値が使われます。

ライブラリに組み込まれたデフォルト値

host の値が未設定または空の場合、 クライアントライブラリはデフォルト値を Unixドメインソケットの localhost とします。 socket の値が未設定または空の場合、 かつ Unixドメインソケットの接続がリクエストされた場合、 デフォルトのソケット /tmp/mysql.sock を使って接続を試みます。

Windows の場合、 ホスト名 . は、クライアントライブラリによって Windows の名前付きパイプベースの接続をオープンするものと解釈されます。 この場合、socket のパラメータはパイプの名前として解釈されます。 この値が未設定または空の場合、 ソケット(パイプ名)のデフォルトは \\.\pipe\MySQL となります。

Unixドメインソケットベース、 および Windows の名前付きパイプベースの接続が両方確立されず、 port パラメータが未設定の場合、 ライブラリはデフォルトのポートを 3306 に設定します。

mysqlnd ライブラリと MySQL Client Library (libmysqlclient) は、 デフォルト値を決めるためのロジックは同じです。

接続オプション

接続オプションも利用可能です。 たとえば、接続時に実行される初期化コマンドや、 特定の文字セットを使うようにリクエストするなど、です。 接続オプションはネットワーク接続が確立される前に設定しなくてはいけません。

接続オプションを設定するために、 接続操作は3つの段階を踏んで行われます。 mysqli_init() または mysqli::__construct() を使って接続ハンドルを初期化し、 mysqli::options() を使って リクエストされた接続オプションを設定し、 mysqli::real_connect() で、ネットワーク接続を確立します。

接続のプーリング

mysqli 拡張モジュールは、 データベースへの持続的接続をサポートしています。 これは、特別な種類の接続で、プーリングされます。 デフォルトでは、 スクリプトによってオープンされたデータベース接続それぞれが、 ユーザによって明示的に閉じられるか、 スクリプトによって自動的に開放されます。 持続的接続はそうではなく、 開放する代わりに、後に再利用するためにプールに戻します。 同じサーバーへの接続が同じユーザ名、 パスワード、ソケット、ポート、 そしてデフォルトデータベースを指定してオープンされた場合、 接続が再利用され、接続のオーバーヘッドが軽減されます。

PHP のプロセスごとに、mysqli の接続プールが使われます。 webサーバーがどのように運用されるかによりますが、 PHP のプロセスはひとつ以上のリクエストを処理する可能性があります。 よって、プーリングされた接続は ひとつ以上のスクリプトから後に使われる可能性があるのです。

持続的接続

あるホスト名、ユーザ名、パスワード、ソケット、ポート、 そしてデフォルトのデータベースの組み合わせについて、 未使用の持続的接続がプールに見つからない場合、 mysqli は新しい接続をオープンします。 持続的接続を使うかどうかは、 mysqli.allow_persistent を使って制御できます。 スクリプトがオープンする接続の合計数は、 mysqli.max_links で制御できます。 PHP プロセス毎に使う持続的接続の最大数は mysqli.max_persistent で制御できます。 Webサーバーは多くの PHP プロセスをforkさせる可能性があることに注意して下さい。

持続的接続についてよくある不満が、 再利用する前にステートがリセットされないというものです。 たとえば、 オープンされ、終了していないトランザクションは 自動的にロールバックされません。 しかし同時に 接続をプールに戻し、 再利用するまでの間に行われた認証情報の変更も反映されません。 これは、望ましくない副作用と見なされるかもしれません。 一方で、persistent という名前は、 ステートを維持することを約束していると理解されるかもしれません。

mysqli 拡張モジュールは、 持続的接続について、両方の解釈をサポートしています: ステートを維持するか、 再利用する前にステートをリセットするか、です。 デフォルトはリセットです。 持続的接続が再利用される前に、 mysqli 拡張モジュールは暗黙のうちに ステートをリセットするために mysqli::change_user() をコールします。 持続的接続は、 これによってちょうど今オープンされたかのようにユーザの前に出現します。 以前利用されていた状態は見えません。

mysqli::change_user() をコールすると、コストが高く付きます。 パフォーマンスを最大にするために、 ユーザーはコンパイルフラグ MYSQLI_NO_CHANGE_USER_ON_PCONNECT を設定して、拡張モジュールをリコンパイルしたいかもしれません。

安全な振る舞いと、 最大のパフォーマンスのどちらを取るかは、 ユーザに任されています。 どちらを選んでも、最適化の目的としては正当なものです。 使いやすさを求めれば、 パフォーマンスを犠牲にして安全な振る舞いを行わせる ことがデフォルトになります。

参照

  • mysqli::__construct()
  • mysqli_init()
  • mysqli::options()
  • mysqli::real_connect()
  • mysqli::change_user()
  • $mysqli::host_info
  • MySQLi Configuration Options
  • Persistent Database Connections


ステートメントの実行

ステートメントは、 mysqli::query(), mysqli::real_query(), mysqli::multi_query() を使って実行できます。 mysqli::query() がもっともよく使われますが、 ステートメントの実行と、 バッファリングされた結果セットの取得を一回の呼び出しで組み合わせることもできます。 mysqli::query() の呼び出しは、 mysqli::real_query() の後に mysqli::store_result() を呼び出すことと同じです。

例1 クエリを実行する

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");

バッファリングされた結果セット

ステートメントを実行した後、 結果は一度に全部取得するか、 一行ずつ読み取ることのどちらかができます。 クライアント側で結果セットをバッファリングすることで、 サーバーは結果セットに関連付けられたリソースをできるだけ早く開放できます。 一般的な話ですが、 クライアントが結果セットを処理する速度は遅いです。 そのため、バッファリングされた結果セットを使うことを推奨します。 mysqli::query() は、ステートメントの実行と結果セットのバッファリングを組み合わせます。

PHP アプリケーションは、 バッファリングされた結果セットを通して、結果を自由に操作できます。 そうすることで、結果セットがクライアント側のメモリに保持されるため、 高速です。 サーバー側をスケールさせるより、 クライアント側でスケールさせるほうが容易なことがある、 ということを頭に入れておいて下さい。

例2 バッファリングされた結果セットを操作する

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$result = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

echo "Reverse order...\n";
for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
$result->data_seek($row_no);
$row = $result->fetch_assoc();
echo " id = " . $row['id'] . "\n";
}

echo "Result set order...\n";
foreach ($result as $row) {
echo " id = " . $row['id'] . "\n";
}

上の例の出力は以下となります。

Reverse order...
 id = 3
 id = 2
 id = 1
Result set order...
 id = 1
 id = 2
 id = 3

結果セットをバッファリングしない場合

クライアント側のメモリが不足し、 かつサーバー側のリソースをできるだけ早く開放することで、 サーバーの負荷を下げる必要がない場合、 結果セットのバッファリングを無効にできます。 結果セットをバッファリングしない場合、 全ての行を読み取るまで、 結果を操作することはできません。

例3 結果セットをバッファリングせず、結果を操作する

<?php

$mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
$result = $mysqli->use_result();

echo "Result set order...\n";
foreach ($result as $row) {
echo " id = " . $row['id'] . "\n";
}

結果セットの値のデータ型

mysqli::query(), mysqli::real_query(), mysqli::multi_query() 関数は、準備されていないステートメントを実行するために使います。 MySQL のクライアントサーバープロトコルのレベルでは、 COM_QUERY コマンドとテキストプロトコルをステートメントの実行に使います。 テキストプロトコルでは、 MySQL サーバーは結果セットの全てのデータを、 送信する前に文字列に変換します。 この変換は、 SQL の結果セットの、 カラムのデータ型が何であっても行われます。 MySQL のクライアントライブラリは、 全てのカラムの値を文字列として受け取ります。 MySQL 側のネイティブなデータ側に戻すために、 それ以上のキャストがクライアント側で行われることはありません。 キャストするのではなく、 全ての値が PHP の文字列型として返されます。

例4 テキストプロトコルは、文字列を返すのがデフォルト

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

$result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $result->fetch_assoc();

printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

上の例の出力は以下となります。

id = 1 (string)
label = a (string)

mysqlnd ライブラリを使っている場合に、 MYSQLI_OPT_INT_AND_FLOAT_NATIVE 接続オプションを設定すると、 int や float 型のカラムの値を、 PHP の数値型に変換できます。 これを設定すると、mysqlnd ライブラリは、 結果セットのメタデータのカラム型を調べ、 PHP のデータ型の範囲が許可している場合に、 数値のSQLカラムの値を PHP の数値に変換します。 こうすることで、たとえば、 SQL の INT カラムを、数値として返すことができます。

例5 mysqlnd と接続オプションを設定することで、ネイティブのデータ型を扱う

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli();
$mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
$mysqli->real_connect("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

$result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $result->fetch_assoc();

printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

上の例の出力は以下となります。

id = 1 (integer)
label = a (string)

参照

  • mysqli::__construct()
  • mysqli::options()
  • mysqli::real_connect()
  • mysqli::query()
  • mysqli::multi_query()
  • mysqli::use_result()
  • mysqli::store_result()


プリペアドステートメント

MySQL データベースは、 プリペアドステートメントをサポートしています。 プリペアドステートメント、 またはパラメータ化したステートメントは、 同じステートメントを繰り返し、 高い効率で実行すると同時に、 SQLインジェクションから守ります。

基本的なワークフロー

プリペアドステートメントの実行は、 ふたつの段階を踏んで行われます: 準備と実行です。 準備の段階では、 ステートメントのテンプレートがデータベースサーバーに送信されます。 サーバーは文法のチェックを行い、 サーバーの内部リソースを後に再利用するために初期化しておきます。

MySQL サーバーは名前を指定せず、 位置を指定できるプレースホルダーを ? によってサポートしています。

準備の後、実行が行われます。 実行する間、 クライアントはパラメータの値をバインドし、サーバーに送信します。 サーバーはステートメントをバインドされた値とともに、 以前作成した内部リソースを使って実行します。

例1 プリペアドステートメント

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Non-prepared statement */
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");

/* Prepared statement, stage 1: prepare */
$stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

/* Prepared statement, stage 2: bind and execute */
$id = 1;
$label = 'PHP';
$stmt->bind_param("is", $id, $label); // "is" means that $id is bound as an integer and $label as a string

$stmt->execute();

繰り返し実行させる

プリペアドステートメントは、 繰り返し実行させることができます。 実行させる度に、 バインドされた現在の値が評価され、 サーバーに送られます。 ステートメントは再度パースされません。 ステートメントのテンプレートもサーバーに再度送信されません。

例2 INSERT を一度だけ準備し、複数回実行する

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Non-prepared statement */
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");

/* Prepared statement, stage 1: prepare */
$stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

/* Prepared statement, stage 2: bind and execute */
$stmt->bind_param("is", $id, $label); // "is" means that $id is bound as an integer and $label as a string

$data = [
1 => 'PHP',
2 => 'Java',
3 => 'C++'
];
foreach ($data as $id => $label) {
$stmt->execute();
}

$result = $mysqli->query('SELECT id, label FROM test');
var_dump($result->fetch_all(MYSQLI_ASSOC));

上の例の出力は以下となります。

array(3) {
  [0]=>
  array(2) {
    ["id"]=>
    string(1) "1"
    ["label"]=>
    string(3) "PHP"
  }
  [1]=>
  array(2) {
    ["id"]=>
    string(1) "2"
    ["label"]=>
    string(4) "Java"
  }
  [2]=>
  array(2) {
    ["id"]=>
    string(1) "3"
    ["label"]=>
    string(3) "C++"
  }
}

プリペアドステートメントごとに、 サーバーのリソースが消費されます。 ステートメントは、使った後はすぐに閉じるべきです。 それを明示的に行わない場合、 ステートメントハンドルが PHP によって開放された後、 ステートメントが閉じられます。

プリペアドステートメントが、 ステートメントを実行するもっとも効率が良い方法とは限りません。 プリペアドステートメントが一度しか実行されないと、 クライアントとサーバー間の通信が、 ステートメントを準備しない場合と比べて余計に行われてしまいます。 よって、上の例の SELECT は、プリペアドステートメントを使って実行していません。

また、 MySQL の複数INSERT の文法を使うことも検討してみて下さい。 たとえば、複数INSERT によって、 サーバーとクライアント間に必須の通信が、 上に示すプリペアドステートメントの例よりも少なくなります。

例3 複数INSERTを使い、クライアント・サーバー間の通信を減らす

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");

$values = [1, 2, 3, 4];

$stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?), (?), (?), (?)");
$stmt->bind_param('iiii', ...$values);
$stmt->execute();

結果セットの値のデータ型

MySQL のクライアントサーバープロトコルは、 プリペアドステートメントと、 準備しないステートメントとでは異なるデータ転送プロトコルを使います。 プリペアドステートメントは、いわゆるバイナリプロトコルを使います。 MySQL は結果セットのデータを、 バイナリフォーマットで "そのまま" 送信します。 結果セットは送信される前は文字列にシリアライズされていません。 クライアントライブラリは、 バイナリデータを受け取って値を適切なPHP のデータ型に変換しようとします。 たとえば、INT として定義されたカラムからの結果は、 PHP の整数値として提供されます。

例4 ネイティブのデータ型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Non-prepared statement */
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();
$result = $stmt->get_result();
$row = $result->fetch_assoc();

printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

上の例の出力は以下となります。

id = 1 (integer)
label = PHP (string)

この振る舞いが、準備しないステートメントの場合は異なります。 デフォルトでは、準備しないステートメントの結果は、 全て文字列として返されます。 このデフォルトは、接続オプションで変更できます。 接続オプションを使うと、この振る舞いの違いはなくなります。

バインドされた値を使って、結果を取得する

プリペアドステートメントからの結果は、 出力値をバインドして取得することもできますし、 mysqli_result から取得するようにリクエストすることもできます。

出力変数は、ステートメントの実行後にバインドしなければいけません。 ステートメントの結果セットのそれぞれのカラムごとに、 ひとつの値をバインドしなければいけません。

例5 バインドされた値を出力する

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Non-prepared statement */
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();

$stmt->bind_result($out_id, $out_label);

while ($stmt->fetch()) {
printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
}

上の例の出力は以下となります。

id = 1 (integer), label = PHP (string)

プリペアドステートメントは、 デフォルトでは、結果セットをバッファリングせずに返します。 ステートメントの結果は、 暗黙のうちに取得されることはありませんし、 サーバーからクライアントに、 バッファリングされるためにデータが送信されることもありません。 結果セットは、全ての結果がクライアントによって取得されるまで、 サーバーのリソースを消費します。 よって、結果は必要に応じて取得することが推奨されます。 クライアントが全ての結果を取得できなかったり、 クライアントが全てのデータを取得する前にステートメントを閉じたりした場合、 mysqli は暗黙のうちにデータを取得しなければいけません。

プリペアドステートメントであっても、 mysqli_stmt::store_result() を使って結果をバッファリングすることが可能です。

mysqli_result インターフェイスを使って、結果を取得する

バインドされた結果を使う代わりに、 mysqli_result インターフェイスを使って結果を取得することもできます。 mysqli_stmt::get_result() は、バッファリングされた結果セットを返します。

例6 結果を取得するために、mysqli_result を使う

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Non-prepared statement */
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();

$result = $stmt->get_result();

var_dump($result->fetch_all(MYSQLI_ASSOC));

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(2) {
    ["id"]=>
    int(1)
    ["label"]=>
    string(3) "PHP"
  }
}

mysqli_result インターフェイスを使うと、 クライアント側で結果セットを柔軟に操作することができます。

例7 柔軟に結果を読み取るために、バッファリングされた結果セットを使う

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Non-prepared statement */
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP'), (2, 'Java'), (3, 'C++')");

$stmt = $mysqli->prepare("SELECT id, label FROM test");
$stmt->execute();

$result = $stmt->get_result();

for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
$result->data_seek($row_no);
var_dump($result->fetch_assoc());
}

上の例の出力は以下となります。

array(2) {
  ["id"]=>
  int(3)
  ["label"]=>
  string(3) "C++"
}
array(2) {
  ["id"]=>
  int(2)
  ["label"]=>
  string(4) "Java"
}
array(2) {
  ["id"]=>
  int(1)
  ["label"]=>
  string(3) "PHP"
}

エスケープと SQL インジェクション

バインドされる変数は、 クエリとは別にサーバーに送信されます。 このことが、変数によって邪魔されることはありません。 サーバーはステートメントのテンプレートをパース後、 送信された値を実行時に直接使います。 バインドされたパラメータをエスケープする必要はありません。 サーバーがその値でクエリの文字列を直接置き換えることはないからです。 バインドする変数の型について、サーバーにヒントを提供しなければいけません。 これは、サーバーが適切な変換を行うために必要です。 詳しい情報は、 mysqli_stmt::bind_param() を参照ください。

このように、変数とクエリを別に扱うことが、 SQLインジェクションを防ぐ唯一のセキュリティ上の機能だと見なされることがあります。 しかし、全ての値を適切にフォーマットしておけば、 それと同程度のセキュリティを準備しないステートメントでも達成できます。 正しいフォーマットとは、 単純に値をエスケープすることではなく、 それ以上のロジックを含むことに注意すべきです。 よって、この手のデータベースセキュリティに対しては、 プリペアドステートメントが単により便利で、 エラーが起きにくいアプローチになっています。

クライアント側でプリペアドステートメントをエミュレートする

API は、クライアント側でのプリペアドステートメントのエミュレートをサポートしていません。

参照

  • mysqli::__construct()
  • mysqli::query()
  • mysqli::prepare()
  • mysqli_stmt::prepare()
  • mysqli_stmt::execute()
  • mysqli_stmt::bind_param()
  • mysqli_stmt::bind_result()


ストアドプロシージャ

MySQL データベースは、ストアドプロシージャをサポートしています。 ストアドプロシージャは、 データベースカタログに保存されたサブルーチンです。 アプリケーションは、ストアドプロシージャを呼び出し、実行できます。 ストアドプロシージャを実行するには、SQL ステートメント CALL を使います。

ストアドプロシージャへの引数

MySQL のバージョンによっては、 ストアドプロシージャで IN, INOUT, OUT という引数をとることができるものがあります。 mysqli インターフェイスは、 引数の違いについて、特別な考慮を行いません。

IN パラメータ

CALL ステートメントに渡す入力パラメータに使います。 値が適切にエスケープされていることを必ず確認するようにして下さい。

例1 ストアドプロシージャを呼び出す

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;");

$mysqli->query("CALL p(1)");

$result = $mysqli->query("SELECT id FROM test");

var_dump($result->fetch_assoc());

上の例の出力は以下となります。

array(1) {
  ["id"]=>
  string(1) "1"
}

INOUT/OUT パラメータ

INOUT/OUT パラメータに渡した値は、 セッションの値を使ってアクセスできます

例2 セッションの値を使う

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;');

$mysqli->query("SET @msg = ''");
$mysqli->query("CALL p(@msg)");

$result = $mysqli->query("SELECT @msg as _p_out");

$row = $result->fetch_assoc();
echo $row['_p_out'];

上の例の出力は以下となります。

Hi!

アプリケーションやフレームワークの開発者は、 セッションの値やデータベースカタログを調べることによって、 もっと便利なAPIを提供できます。 しかし、カタログを調べることをベースにしたカスタムのやり方は、 パフォーマンスに影響がある可能性があることに注意して下さい。

結果セットを扱う

ストアドプロシージャは、 結果セットを返すことができます。 ストアドプロシージャから返された結果セットは、 mysqli::query() を使っても正しく取得できません。 mysqli::query() は、ステートメントを実行し、 バッファリングされた結果セットから、存在する場合にだけ、 最初の結果セットを返すものです。 しかし、 mysqli::query() は、 ストアドプロシージャが返す追加の結果セットを隠してしまうため、 ユーザが期待する結果セットを返すことに失敗してしまうのです。

ストアドプロシージャから返される結果セットは、 mysqli::real_query() や mysqli::multi_query() を使うと取得できます。 これらの関数は、 CALL のような、 任意の数の結果セットを返すステートメントから結果を取得できます。 ストアドプロシージャによって返される、 結果セットが全部取得できない場合は、エラーが発生します。

例3 ストアドプロシージャから、結果を取得する

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

$mysqli->multi_query("CALL p()");

do {
if ($result = $mysqli->store_result()) {
printf("---\n");
var_dump($result->fetch_all());
$result->free();
}
} while ($mysqli->next_result());

上の例の出力は以下となります。

---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    string(1) "1"
  }
  [1]=>
  array(1) {
    [0]=>
    string(1) "2"
  }
  [2]=>
  array(1) {
    [0]=>
    string(1) "3"
  }
}
---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    string(1) "2"
  }
  [1]=>
  array(1) {
    [0]=>
    string(1) "3"
  }
  [2]=>
  array(1) {
    [0]=>
    string(1) "4"
  }
}

プリペアドステートメントを使う

上に示した、同じストアドプロシージャから結果を取得する場合に、 プリペアドステートメントを使う場合であっても、 特別な操作は必要ありません。 プリペアドステートメントと、 それを用いないインターフェイスは似ています。 全てのバージョンの MySQL サーバーが、 CALL ステートメントを準備することをサポートしているわけではないことに注意して下さい。

例4 ストアドプロシージャとプリペアドステートメント

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

$stmt = $mysqli->prepare("CALL p()");

$stmt->execute();

do {
if ($result = $stmt->get_result()) {
printf("---\n");
var_dump($result->fetch_all());
$result->free();
}
} while ($stmt->next_result());

上の例の出力は以下となります。

---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    int(1)
  }
  [1]=>
  array(1) {
    [0]=>
    int(2)
  }
  [2]=>
  array(1) {
    [0]=>
    int(3)
  }
}
---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    int(2)
  }
  [1]=>
  array(1) {
    [0]=>
    int(3)
  }
  [2]=>
  array(1) {
    [0]=>
    int(4)
  }
}

もちろん、 値を取得するためのバインドAPIもサポートしています。

例5 バインドAPIを使って、プリペアドステートメントとストアドプロシージャを実行する

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

$stmt = $mysqli->prepare("CALL p()");

$stmt->execute();

do {
if ($stmt->store_result()) {
$stmt->bind_result($id_out);
while ($stmt->fetch()) {
echo "id = $id_out\n";
}
}
} while ($stmt->next_result());

上の例の出力は以下となります。

id = 1
id = 2
id = 3
id = 2
id = 3
id = 4

参照

  • mysqli::query()
  • mysqli::multi_query()
  • mysqli::next_result()
  • mysqli::more_results()


複数のステートメント

MySQL は、ひとつのステートメントの文字列に、 複数のステートメントを埋め込むことをオプションでサポートしています。 しかし、そうするためには特別な操作が必要です。

複数のステートメント、 またはマルチクエリーは、 mysqli::multi_query() を使って実行する必要があります。 文字列に埋め込まれる個々のステートメントは、 セミコロンで区切ります。 実行されたステートメントによって返される全ての結果セットは、 取得されなければいけません。

MySQL サーバーは、 結果セットを返すステートメントと、 返さないステートメントを、 ひとつの複数のステートメントに埋め込むことができます。

例1 複数のステートメント

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");

$sql = "SELECT COUNT(*) AS _num FROM test;
INSERT INTO test(id) VALUES (1);
SELECT COUNT(*) AS _num FROM test; ";

$mysqli->multi_query($sql);

do {
if ($result = $mysqli->store_result()) {
var_dump($result->fetch_all(MYSQLI_ASSOC));
$result->free();
}
} while ($mysqli->next_result());

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(1) {
    ["_num"]=>
    string(1) "0"
  }
}
array(1) {
  [0]=>
  array(1) {
    ["_num"]=>
    string(1) "1"
  }
}

セキュリティ上の考慮

mysqli::query() や mysqli::real_query() は、 サーバーで複数のクエリを処理するための接続フラグを設定しません。 複数のステートメントを使うことで、 SQLインジェクション攻撃の被害を軽減するためには、 追加のAPI呼び出しが必要です。 攻撃者は、; DROP DATABASE mysql や ; SELECT SLEEP(999) のようなステートメントを追加しようとするかもしれません。 攻撃者がステートメントにSQLを追加することに成功したが、 mysqli::multi_query() がそれを使わなければ、 サーバーは挿入された、有害なSQLステートメントを実行することはありません。

例2 SQLインジェクション

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");
$result = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
?>

上の例の出力は以下となります。

PHP Fatal error:  Uncaught mysqli_sql_exception: You have an error in your SQL syntax;
check the manual that corresponds to your MySQL server version for the right syntax to
use near 'DROP TABLE mysql.user' at line 1

プリペアドステートメント

プリペアドステートメントを複数のステートメントで使うことは、 サポートされていません。

参照

  • mysqli::query()
  • mysqli::multi_query()
  • mysqli::next_result()
  • mysqli::more_results()


トランザクションのサポート

MySQL サーバーは、使っているストレージエンジンによっては、 トランザクションをサポートしています。 MySQL 5.5 以降は、 デフォルトのストレージエンジンは InnoDB です。 InnoDB は、トランザクションの ACID 特性を完全にサポートしています。

トランザクションは、 SQL または API を呼び出すことによって制御できます。 autocommit モードを有効にしたり、 無効にしたりする目的や、トランザクションをコミットしたり、 ロールバックする目的には、API 呼び出しを使うことを推奨します。

例1 autocommit モードをSQL と API を使って設定する

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

/* Recommended: using API to control transactional settings */
$mysqli->autocommit(false);

/* Won't be monitored and recognized by the replication and the load balancing plugin */
$mysqli->query('SET AUTOCOMMIT = 0');

レプリケーションやロードバランシングプラグインのような、 オプションの機能パッケージによっては、 API の呼び出しを容易に監視できるものもあります。 レプリケーションプラグインは、 トランザクションが API 呼び出しによって制御されている場合に、 それを考慮したロードバランシングを提供します。 トランザクションを考慮したロードバランシングは、 SQL を使って autocommit モードが設定されたり、 コミットやロールバックが行われる場合には利用できません。

例2 コミットとロールバック

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");
$mysqli->autocommit(false);

$mysqli->query("INSERT INTO test(id) VALUES (1)");
$mysqli->rollback();

$mysqli->query("INSERT INTO test(id) VALUES (2)");
$mysqli->commit();

MySQL サーバーは、 全てのステートメントをロールバックできるわけではないことに注意して下さい。 ステートメントによっては、 暗黙のうちにコミットされるものもあります。

参照

  • mysqli::autocommit()
  • mysqli::begin_transaction()
  • mysqli::commit()
  • mysqli::rollback()


メタデータ

MySQL の結果セットは、メタデータを含んでいます。 メタデータは、結果セットで見つかったカラムの情報を説明するものです。 MySQL が送信した全てのメタデータは、 mysqli のインターフェイスを通じてアクセスできます。 この拡張モジュールは、受け取った情報に対してまったく変更を行いません。 仮にしたとしても、無視できる程度のものです。 MySQL のサーバーのバージョンによる違いは調整されません。

メタデータは、 mysqli_result インターフェイスを使ってアクセスします。

例1 結果セットのメタデータにアクセスする

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$result = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
var_dump($result->fetch_fields());

上の例の出力は以下となります。

array(2) {
  [0]=>
  object(stdClass)#3 (13) {
    ["name"]=>
    string(4) "_one"
    ["orgname"]=>
    string(0) ""
    ["table"]=>
    string(0) ""
    ["orgtable"]=>
    string(0) ""
    ["def"]=>
    string(0) ""
    ["db"]=>
    string(0) ""
    ["catalog"]=>
    string(3) "def"
    ["max_length"]=>
    int(1)
    ["length"]=>
    int(1)
    ["charsetnr"]=>
    int(63)
    ["flags"]=>
    int(32897)
    ["type"]=>
    int(8)
    ["decimals"]=>
    int(0)
  }
  [1]=>
  object(stdClass)#4 (13) {
    ["name"]=>
    string(4) "_two"
    ["orgname"]=>
    string(0) ""
    ["table"]=>
    string(0) ""
    ["orgtable"]=>
    string(0) ""
    ["def"]=>
    string(0) ""
    ["db"]=>
    string(0) ""
    ["catalog"]=>
    string(3) "def"
    ["max_length"]=>
    int(5)
    ["length"]=>
    int(5)
    ["charsetnr"]=>
    int(8)
    ["flags"]=>
    int(1)
    ["type"]=>
    int(253)
    ["decimals"]=>
    int(31)
  }
}

プリペアドステートメント

プリペアドステートメントを使って作られた結果セットのメタデータは、 アクセス方法も同じです。 mysqli_stmt::result_metadata() が、 適切な mysqli_result ハンドルを返してくれます。

例2 プリペアドステートメントのメタデータ

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
$stmt->execute();
$result = $stmt->result_metadata();
var_dump($result->fetch_fields());

参照

  • mysqli::query()
  • mysqli_result::fetch_fields()


  • ≪ メタデータ
  • 要件 ≫
  • PHP Manual
  • MySQLi
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

これらの関数を有効にするには、mysqli 拡張サポートを 有効にして PHP をコンパイルする必要があります。

MySQL 8

PHP 7.1.16 より前のバージョン、もしくは PHP 7.2.4 より前の 7.2系の PHP では、 MySQL 8 サーバーのデフォルトパスワードプラグインを mysql_native_password に設定するようにしてください。 さもないと、 The server requested authentication method unknown to the client [caching_sha2_password] のようなエラーを見ることになります。たとえあなたが caching_sha2_password を使っていなくても、です。

これは MySQL 8 のデフォルトが 古い PHP (mysqlnd) のリリースが認識していないプラグイン caching_sha2_password だからです。 かわりに、my.cnf の設定を default_authentication_plugin=mysql_native_password と変更してください。 caching_sha2_password プラグインは、 PHP 7.4.4 以降で完全にサポートされました。 これより前のバージョンでは、 mysql_xdevapi 拡張モジュールでサポートされています。


インストール手順

mysqli 拡張モジュールが使えるようになったのは PHP バージョン 5.0.0 以降です。また、MySQL Native Driver が PHP に含まれるようになったのはバージョン 5.3.0 以降です。

Linux でのインストール

一般的な Unix ディストリビューションには、バイナリ版の PHP がインストールされています。 これらのバイナリ版は、通常は MySQL 拡張モジュールに対応したものになっています。 しかし、拡張モジュールライブラリ自身を別パッケージでインストールする必要があるでしょう。 使用しているディストリビューションのパッケージマネージャで確認してみましょう。

たとえば Ubuntu なら、php5-mysql パッケージをインストールすれば、 ext/mysql、ext/mysqli、そして pdo_mysql をインストールできます。CentOS の場合は php-mysql パッケージを使えば、同じものをインストールできます。

この拡張モジュールを自分でコンパイルすることもできます。 PHP をソースからビルドすれば、使いたい MySQL 拡張モジュールを指定したり 各拡張モジュールが使用するクライアントライブラリを選択したりすることができます。

クライアントライブラリには MySQL Native Driver を使うことを推奨します。 そのほうがパフォーマンスが向上し、MySQL Client Library を使用した場合には使えない機能も使用することができます。 PHP の MySQL Native Driver とは? に、MySQL Native Driver の利点が簡単にまとめられています。

/path/to/mysql_config は、MySQL Server に含まれる mysql_config プログラムの場所を表します。

mysqli のコンパイル時のサポート表
PHP バージョン | デフォルト | 設定オプション: mysqlnd | 設定オプション: libmysqlclient | 変更履歴
5.4.x 以降 | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | mysqlnd がデフォルトになりました。
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | mysqlnd が使えるようになりました。
5.0.x, 5.1.x, 5.2.x | libmysqlclient | 利用できません | --with-mysqli=/path/to/mysql_config | mysqlnd は使えません。

MySQL 拡張モジュールとクライアントライブラリの組み合わせは自由であることに注意しましょう。 たとえば、MySQL 拡張モジュールは MySQL Client Library (libmysqlclient) を使うようにして有効にし、 一方 mysqli 拡張モジュールは MySQL Native Driver を使うようにするということも可能です。 しかし、それ以外にも拡張モジュールとクライアントライブラリのすべての組み合わせが使用可能です。

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

Windows の場合、php_mysqli.dll を php.ini で有効にする必要があります。

その他の PHP 拡張モジュール (php_mysqli.dll など) を有効にするときと同様、PHP のディレクティブ extension_dir を設定して PHP 拡張モジュールのある場所を指定する必要があります。 Windows での手動インストールの手順 も参照ください。 extension_dir の値は、たとえば c:\php\ext のようになります。

注意:

ウェブサーバーの起動時に "Unable to load dynamic library './php_mysqli.dll'" のようなエラーが出たら、それは php_mysqli.dll をシステムが見つけられないことが原因です。


実行時設定

php.ini の設定により動作が変化します。

MySQLi 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqli.allow_local_infile | "0" | INI_SYSTEM | PHP 7.2.16, 7.3.3 より前のバージョンでは デフォルト値は "1" でした。
mysqli.local_infile_directory |  | INI_SYSTEM | PHP 8.1.0 以降で利用可能です。
mysqli.allow_persistent | "1" | INI_SYSTEM |
mysqli.max_persistent | "-1" | INI_SYSTEM |
mysqli.max_links | "-1" | INI_SYSTEM |
mysqli.default_port | "3306" | INI_ALL |
mysqli.default_socket | NULL | INI_ALL |
mysqli.default_host | NULL | INI_ALL |
mysqli.default_user | NULL | INI_ALL |
mysqli.default_pw | NULL | INI_ALL |
mysqli.reconnect | "0" | INI_SYSTEM | PHP 8.2.0 で削除されました。
mysqli.rollback_on_cached_plink | "0" | INI_SYSTEM |

これらの INI_* 定数の詳細と定義については、 設定の変更 を参照ください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqli.allow_local_infile int

PHP 側から、LOAD DATA 文によるローカルファイルへのアクセスを許可する。

mysqli.local_infile_directory string

LOCAL DATA 文によるファイルのロードを、 ここで指定したディレクトリに制限する機能を有効にします。

mysqli.allow_persistent int

mysqli_connect() による持続的接続の作成機能を有効にします。

mysqli.max_persistent int

作成できる持続的接続の最大数。0 を設定すると無制限となります。

mysqli.max_links int

プロセス毎の MySQL 接続の最大数。

mysqli.default_port int

他のポートが指定されない場合、データベースサーバー接続時に使用される デフォルトの TCP ポート番号。デフォルトが指定されない場合は、 環境変数 MYSQL_TCP_PORT・ /etc/services の mysql-tcpエントリ・コンパイル時の MYSQL_PORT 定数の順番でポートが取得されます。 Win32 では、MYSQL_PORT 定数のみが使用されます。

mysqli.default_socket string

他にソケット名が指定されない場合、ローカルな データベースサーバーに接続する時のデフォルトのソケット名。

mysqli.default_host string

他のサーバー名が指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのサーバー名。

mysqli.default_user string

他のユーザー名が指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのユーザー名。

mysqli.default_password string

他のパスワードが指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのパスワード。

mysqli.reconnect int

接続が失われたときに自動的に再接続するかどうか。

注意: mysqlnd ドライバは、この php.ini 設定項目を無視していました。 そして、PHP 8.2.0 で削除されました。

mysqli.rollback_on_cached_plink bool

このオプションを有効にすると、接続を閉じて時持続的接続プールに接続を戻す前に、 この接続で保留中だったあらゆるトランザクションがロールバックされます。 このオプションが無効だった場合、接続が再利用されるとき、または実際に閉じられるときだけ、 保留中のトランザクションがロールバックされます。

MYSQL_OPT_READ_TIMEOUT を、 API コールや実行時の設定で指定することはできません。 もしそんなことができてしまうと、libmysqlclient とストリームで MYSQL_OPT_READ_TIMEOUT の値の解釈する方法が違ってしまう可能性があることに注意しましょう。


mysqli 拡張モジュールでの持続的接続

持続的接続とは、クライアントプロセスとデータベースとの間の接続を 何度も作っては破棄するかわりにクライアントプロセス側で再利用しようというものです。 これにより、必要なときに毎回新規接続を作成するというオーバーヘッドが軽減でき、 未使用の接続はキャッシュされて再利用できるようになります。

他の mysql 用拡張モジュールとは異なり、mysqli には持続的接続のオープン専用の関数はありません。 持続的な接続をオープンするには、接続時にホスト名の前に p: をつけなければなりません。

持続的接続の問題は、予期せぬ状態でクライアント側に残ってしまう可能性があるということです。 たとえば、テーブルロックを行った状態でクライアントが突然終了してしまったとしましょう。 新しいクライアントプロセスがこの持続的接続を使用する際には、 そのまま の状態でこれを使うことになります。 新しいクライアントプロセスがこの持続的接続をきちんと使うためには事前になんらかの後始末が必要となります。 これはプログラマにとっては面倒な作業です。

しかし、mysqli 拡張モジュールの持続的接続には後始末を行うコードが組み込まれています。 mysqli は、以下のような後始末を行います。

  • アクティブなトランザクションのロールバック

  • 一時テーブルを閉じて drop

  • テーブルロックの解除

  • セッション変数の初期化

  • プリペアドステートメントを閉じる (PHP では常に発生)

  • ハンドラを閉じる

  • GET_LOCK() で取得したロックの開放

これにより、コネクションプールから取得する接続がクリーンな状態であることが確実になり、 そのままクライアントプロセスで使用できるようになります。

mysqli 拡張モジュールのクリーンアップ処理は、 C の API 関数 mysql_change_user() を自動的にコールすることで行っています。

しかし、自動クリーンアップ処理にはいい面もあれば悪い面もあります。 利点としては、プログラマがクリーンアップのコードを書くことを気にせずにすむということがあります。 自動的にコールされるからです。しかし、多少動作が遅くなるという 可能性 もあります。 接続がコネクションプールに戻される際に毎回クリーンアップが必要となるからです。

自動クリーンアップのコードを無効にしたい場合は、 MYSQLI_NO_CHANGE_USER_ON_PCONNECT を define して PHP をコンパイルします。

注意:

mysqli 拡張モジュールは、 MySQL Native Drive あるいは MySQL Client Library のどちらを使っている場合でも持続的接続をサポートします。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MYSQLI_READ_DEFAULT_GROUP (int)

my.cnf の指定した名前のグループか、 あるいは MYSQLI_READ_DEFAULT_FILE で指定したファイルからオプションを読み込みます。

MYSQLI_READ_DEFAULT_FILE (int)

my.cnf のかわりに、指定したファイルからオプションを 読み込みます。

MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS (int)
Indicates to the server that the client can handle sandbox mode for expired passwords. Can be used with mysqli_options().
MYSQLI_OPT_LOAD_DATA_LOCAL_DIR (int)
If enabled, this option specifies the directory from which client-side LOCAL data loading is permitted in LOAD DATA LOCAL statements.
MYSQLI_OPT_CONNECT_TIMEOUT (int)

接続のタイムアウトまでの秒数。

MYSQLI_OPT_READ_TIMEOUT (int)

コマンドの実行結果が返ってくるまでのタイムアウト秒数。PHP 7.2.0 以降で利用可能です。

MYSQLI_OPT_LOCAL_INFILE (int)

LOAD LOCAL INFILE コマンドを有効にします。

MYSQLI_OPT_INT_AND_FLOAT_NATIVE (int)

整数型と浮動小数点型のカラムをPHPの数値に変換します。mysqlnd でのみ有効です。

MYSQLI_OPT_NET_CMD_BUFFER_SIZE (int)

内部的なコマンド/ネットワークバッファのサイズを指定します。mysqlnd でのみ有効です。

MYSQLI_OPT_NET_READ_BUFFER_SIZE (int)

MySQL のコマンドパケットのボディ部分を読み取る際の、チャンクサイズをバイト単位で指定します。 mysqlnd でのみ有効です。

MYSQLI_OPT_SSL_VERIFY_SERVER_CERT (int)

MySQL 5.1.10 以降が必要です。

MYSQLI_INIT_COMMAND (int)

MySQL サーバーへの接続時に実行するコマンド。 再接続時にも自動的に再実行されます。

MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS (int)
Indicates to the server that the client can handle sandbox mode for expired passwords. Can be used with mysqli_real_connect().
MYSQLI_CLIENT_FOUND_ROWS (int)
Return number of matched rows, not the number of affected rows.
MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT (int)
Verify server certificate.
MYSQLI_CLIENT_SSL (int)

SSL（暗号化プロトコル）を使用します。このオプションは、アプリケーション プログラムで指定することはできず、MySQL クライアントライブラリの内部で設定します。

MYSQLI_CLIENT_COMPRESS (int)

圧縮プロトコルを使用します。

MYSQLI_CLIENT_INTERACTIVE (int)

（wait_timeout のかわりに）interactive_timeout の秒数を使用できるように します。クライアントセッションの wait_timeout 変数の値は、interactive_timeout 変数の値に設定されます。

MYSQLI_CLIENT_IGNORE_SPACE (int)

関数名に続く空白文字を許可します。すべての関数名を予約語とします。

MYSQLI_CLIENT_NO_SCHEMA (int)

db_name.tbl_name.col_name 形式の使用を禁止します。

MYSQLI_CLIENT_MULTI_QUERIES

セミコロンで区切られた複数のクエリを、 一度の mysqli_query() コールで実行することを許可します。

MYSQLI_STORE_RESULT (int)

結果セットをバッファに格納します。 値は 0 です。

MYSQLI_STORE_RESULT_COPY_DATA (int)
As of PHP 8.1, this constants no longer has any effect. Before PHP 8.1, this constant is used to copy results from the internal mysqlnd buffer into the PHP variables fetched. By default, mysqlnd will use a reference logic to avoid copying and duplicating results held in memory. For certain result sets, for example, result sets with many small rows, the copy approach can reduce the overall memory usage because PHP variables holding results may be released earlier. Available with mysqlnd only.
MYSQLI_USE_RESULT (int)

結果セットをバッファに格納しません。 値は 1 です。

MYSQLI_ASSOC (int)

行データを、カラム名をインデックスとする配列に格納して返します。

MYSQLI_NUM (int)

行データを、数値インデックスの配列に格納して返します。

MYSQLI_BOTH (int)

行データを、数値インデックス・カラム名インデックスの両方を 保持する配列に格納して返します。

MYSQLI_NOT_NULL_FLAG (int)

フィールドは、NOT NULL と定義されています。

MYSQLI_PRI_KEY_FLAG (int)

フィールドは、プライマリキーの一部です。

MYSQLI_UNIQUE_KEY_FLAG (int)

フィールドは、ユニークキーの一部です。

MYSQLI_MULTIPLE_KEY_FLAG (int)

フィールドは、インデックスの一部です。

MYSQLI_BLOB_FLAG (int)

フィールドは BLOB と定義されています。

MYSQLI_UNSIGNED_FLAG (int)

フィールドは UNSIGNED と定義されています。

MYSQLI_ZEROFILL_FLAG (int)

フィールドは ZEROFILL と定義されています。

MYSQLI_AUTO_INCREMENT_FLAG (int)

フィールドは AUTO_INCREMENT と定義されています。

MYSQLI_TIMESTAMP_FLAG (int)

フィールドは TIMESTAMP と定義されています。

MYSQLI_SET_FLAG (int)

フィールドは SET と定義されています。

MYSQLI_NUM_FLAG (int)

フィールドは NUMERIC と定義されています。

MYSQLI_PART_KEY_FLAG (int)

フィールドは、マルチインデックスの一部です。

MYSQLI_GROUP_FLAG (int)

フィールドは GROUP BY の一部です。

MYSQLI_NO_DEFAULT_VALUE_FLAG (int)
A column has no DEFAULT clause in its definition. This does not apply to NULL or to AUTO_INCREMENT columns because such columns have a default value of NULL and an implied default value respectively.
MYSQLI_TYPE_DECIMAL (int)

フィールドは DECIMAL と定義されています。

MYSQLI_TYPE_NEWDECIMAL (int)

精密な DECIMAL あるいは NUMERIC のフィールドです (MySQL 5.0.3 以降)。

MYSQLI_TYPE_BIT (int)

フィールドは BIT と定義されています (MySQL 5.0.3 以降)。

MYSQLI_TYPE_TINY (int)

フィールドは TINYINT と定義されています。

MYSQLI_TYPE_SHORT (int)

フィールドは SMALLINT と定義されています。

MYSQLI_TYPE_LONG (int)

フィールドは INT と定義されています。

MYSQLI_TYPE_FLOAT (int)

フィールドは FLOAT と定義されています。

MYSQLI_TYPE_DOUBLE (int)

フィールドは DOUBLE と定義されています。

MYSQLI_TYPE_NULL (int)

フィールドは DEFAULT NULL と定義されています。

MYSQLI_TYPE_TIMESTAMP (int)

フィールドは TIMESTAMP と定義されています。

MYSQLI_TYPE_LONGLONG (int)

フィールドは BIGINT と定義されています。

MYSQLI_TYPE_INT24 (int)

フィールドは MEDIUMINT と定義されています。

MYSQLI_TYPE_DATE (int)

フィールドは DATE と定義されています。

MYSQLI_TYPE_TIME (int)

フィールドは TIME と定義されています。

MYSQLI_TYPE_DATETIME (int)

フィールドは DATETIME と定義されています。

MYSQLI_TYPE_YEAR (int)

フィールドは YEAR と定義されています。

MYSQLI_TYPE_NEWDATE (int)

フィールドは DATE と定義されています。

MYSQLI_TYPE_INTERVAL (int)

フィールドは INTERVAL と定義されています。

MYSQLI_TYPE_ENUM (int)

フィールドは ENUM と定義されています。

MYSQLI_TYPE_SET (int)

フィールドは SET と定義されています。

MYSQLI_TYPE_TINY_BLOB (int)

フィールドは TINYBLOB と定義されています。

MYSQLI_TYPE_MEDIUM_BLOB (int)

フィールドは MEDIUMBLOB と定義されています。

MYSQLI_TYPE_LONG_BLOB (int)

フィールドは LONGBLOB と定義されています。

MYSQLI_TYPE_BLOB (int)

フィールドは BLOB と定義されています。

MYSQLI_TYPE_VAR_STRING (int)

フィールドは VARCHAR あるいは BINARY と定義されています。

MYSQLI_TYPE_STRING (int)

フィールドは STRING と定義されています。

MYSQLI_TYPE_CHAR (int)

フィールドは TINYINT と定義されています。 CHAR については MYSQLI_TYPE_STRING を参照ください。

MYSQLI_TYPE_GEOMETRY (int)

フィールドは GEOMETRY と定義されています。

MYSQLI_TYPE_JSON (int)

フィールドは JSON と定義されています。 mysqlnd のみ有効で、MySQL 5.7.8 以降が必要です。

MYSQLI_NEED_DATA

バインド変数に、さらにデータを使用可能です。

MYSQLI_ENUM_FLAG (int)

フィールドが ENUM として定義されています。

MYSQLI_BINARY_FLAG (int)

フィールドが BINARY として定義されています。

MYSQLI_CURSOR_TYPE_FOR_UPDATE (int)

MYSQLI_CURSOR_TYPE_NO_CURSOR (int)

MYSQLI_CURSOR_TYPE_READ_ONLY (int)

MYSQLI_CURSOR_TYPE_SCROLLABLE (int)

MYSQLI_STMT_ATTR_CURSOR_TYPE (int)

MYSQLI_STMT_ATTR_PREFETCH_ROWS (int)

MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH (int)

MYSQLI_SET_CHARSET_NAME (int)

MYSQLI_REPORT_INDEX (int)

クエリ内でインデックスが使われていなかったり間違ったインデックスを使っていたりする場合に報告します。

MYSQLI_REPORT_ERROR (int)

mysqli 関数コールのエラーを報告します。

MYSQLI_REPORT_STRICT (int)

エラー時に、警告の代わりに mysqli_sql_exception をスローします。

MYSQLI_REPORT_ALL (int)

すべてのオプションを有効にします (すべてを報告します)。

MYSQLI_REPORT_OFF (int)

報告を無効にします。

MYSQLI_DEBUG_TRACE_ENABLED (int)

mysqli_debug() 機能が有効の場合に 1 が設定されます。

MYSQLI_SERVER_PUBLIC_KEY (int)

MYSQLI_REFRESH_GRANT (int)

権限テーブルをリフレッシュします。

MYSQLI_REFRESH_LOG (int)

ログをフラッシュします。SQL 文 FLUSH LOGS を実行するのと同じです。

MYSQLI_REFRESH_TABLES (int)

テーブルキャッシュをフラッシュします。SQL 文 FLUSH TABLES を実行するのと同じです。

MYSQLI_REFRESH_HOSTS (int)

ホストキャッシュをフラッシュします。SQL 文 FLUSH HOSTS を実行するのと同じです。

MYSQLI_REFRESH_REPLICA (int)

MYSQLI_REFRESH_SLAVE のエイリアスです。 PHP 8.1.0 以降で利用可能です。

MYSQLI_REFRESH_STATUS (int)

状態変数をリセットします。SQL 文 FLUSH STATUS を実行するのと同じです。

MYSQLI_REFRESH_THREADS (int)

スレッドキャッシュをフラッシュします。

MYSQLI_REFRESH_SLAVE (int)

レプリケーションのスレーブ側のサーバーで、 マスタサーバーの情報をリセットしてスレーブを再起動します。 SQL 文 RESET SLAVE を実行するのと同じです。

MYSQLI_REFRESH_MASTER (int)

レプリケーションのマスタ側のサーバーで、 バイナリログインデックスにあるバイナリログファイルを削除してインデックスファイルを切り詰めます。 SQL 文 RESET MASTER を実行するのと同じです。

MYSQLI_REFRESH_BACKUP_LOG (int)
Closes and reopens the backup log files.
MYSQLI_TRANS_COR_AND_CHAIN (int)

"AND CHAIN" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_COR_AND_NO_CHAIN (int)

"AND NO CHAIN" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_COR_RELEASE (int)

"RELEASE" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_COR_NO_RELEASE (int)

"NO RELEASE" を mysqli_commit() あるいは mysqli_rollback() に追加します。

MYSQLI_TRANS_START_READ_ONLY (int)

mysqli_begin_transaction() で、 トランザクションを "START TRANSACTION READ ONLY" で開始します。

MYSQLI_TRANS_START_READ_WRITE (int)

mysqli_begin_transaction() で、 トランザクションを "START TRANSACTION READ WRITE" で開始します。

MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT

トランザクションを "START TRANSACTION WITH CONSISTENT SNAPSHOT" で開始します。

MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT (int)

MySQL 5.6.5 以降が必要です。

MYSQLI_IS_MARIADB (bool)

mysqli 拡張モジュールが MariaDB クライアントライブラリを使ってビルドされているかどうか。 PHP 8.1.2 以降が必要です。

MYSQLI_ASYNC (int)
The query is performed asynchronously and no result set is immediately returned. Available with mysqlnd only.
MYSQLI_ON_UPDATE_NOW_FLAG (int)
If a field is updated it will get the current time value.


ノート

若干の実装ノート

  1. MYSQL_TYPE_GEOMETRY に対するサポートが MySQLi 拡張モジュールに PHP 5.3 で追加されました。

  2. MYSQL_TYPE_GEOMETRY 型の項目を操作するために libmysqlclient および mysqlnd の中にそれぞれ別の異なる内部実装があることに注意してください。 一般的に言って、mysqlndでのメモリ割り当ては かなり少なくなります。 例えば、POINT 項目が結果セットにあると、 メモリ上で POINT 項目を保持するには 50 バイトも 必要ないのに、libmysqlclient は最高 4GB の RAM を事前に割り当てるかもしれません。 mysqlnd を使うと、 メモリの割り当てはずっと小さく、50 バイト未満です。


The MySQLi Extension Function Summary

Summary of mysqli methods
mysqli Class
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli::affected_rows | mysqli_affected_rows() | N/A | Gets the number of affected rows in a previous MySQL operation
$mysqli::client_info | mysqli_get_client_info() | N/A | Returns the MySQL client version as a string
$mysqli::client_version | mysqli_get_client_version() | N/A | Returns MySQL client version info as an integer
$mysqli::connect_errno | mysqli_connect_errno() | N/A | Returns the error code from last connect call
$mysqli::connect_error | mysqli_connect_error() | N/A | Returns a string description of the last connect error
$mysqli::errno | mysqli_errno() | N/A | Returns the error code for the most recent function call
$mysqli::error | mysqli_error() | N/A | Returns a string description of the last error
$mysqli::field_count | mysqli_field_count() | N/A | Returns the number of columns for the most recent query
$mysqli::host_info | mysqli_get_host_info() | N/A | Returns a string representing the type of connection used
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | Returns the version of the MySQL protocol used
$mysqli::server_info | mysqli_get_server_info() | N/A | Returns the version of the MySQL server
$mysqli::server_version | mysqli_get_server_version() | N/A | Returns the version of the MySQL server as an integer
$mysqli::info | mysqli_info() | N/A | Retrieves information about the most recently executed query
$mysqli::insert_id | mysqli_insert_id() | N/A | Returns the auto generated id used in the last query
$mysqli::sqlstate | mysqli_sqlstate() | N/A | Returns the SQLSTATE error from previous MySQL operation
$mysqli::warning_count | mysqli_warning_count() | N/A | Returns the number of warnings from the last query for the given link
Methods
mysqli::autocommit() | mysqli_autocommit() | N/A | Turns on or off auto-committing database modifications
mysqli::change_user() | mysqli_change_user() | N/A | Changes the user of the specified database connection
mysqli::character_set_name() | mysqli_character_set_name() | N/A | Returns the default character set for the database connection
mysqli::close() | mysqli_close() | N/A | Closes a previously opened database connection
mysqli::commit() | mysqli_commit() | N/A | Commits the current transaction
mysqli::__construct() | mysqli_connect() | N/A | Open a new connection to the MySQL server [Note: static (i.e. class) method]
mysqli::debug() | mysqli_debug() | N/A | Performs debugging operations
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Dump debugging information into the log
mysqli::get_charset() | mysqli_get_charset() | N/A | Returns a character set object
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Returns client connection statistics. mysqlnd でのみ使用可能です。
mysqli::get_client_info() | mysqli_get_client_info() | N/A | Returns the MySQL client version as a string
N/A | mysqli_get_client_stats() | N/A | Returns client per-process statistics. mysqlnd でのみ使用可能です。
mysqli::get_server_info() | mysqli_get_server_info() | N/A | Returns a string representing the version of the MySQL server that the MySQLi extension is connected to
mysqli::get_warnings() | mysqli_get_warnings() | N/A | NOT DOCUMENTED
mysqli::init() | mysqli_init() | N/A | Initializes MySQLi and returns an object for use with mysqli_real_connect.
mysqli::kill() | mysqli_kill() | N/A | Asks the server to kill a MySQL thread
mysqli::more_results() | mysqli_more_results() | N/A | Check if there are any more query results from a multi query
mysqli::multi_query() | mysqli_multi_query() | N/A | Performs a query on the database
mysqli::next_result() | mysqli_next_result() | N/A | Prepare next result from multi_query
mysqli::options() | mysqli_options() | mysqli_set_opt() | Set options
mysqli::ping() | mysqli_ping() | N/A | Pings a server connection, or tries to reconnect if the connection has gone down
mysqli::prepare() | mysqli_prepare() | N/A | Prepare an SQL statement for execution
mysqli::query() | mysqli_query() | N/A | Performs a query on the database
mysqli::real_connect() | mysqli_real_connect() | N/A | Opens a connection to a mysql server
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
mysqli::real_query() | mysqli_real_query() | N/A | Execute an SQL query
mysqli::refresh() | mysqli_refresh() | N/A | Flushes tables or caches, or resets the replication server information
mysqli::rollback() | mysqli_rollback() | N/A | Rolls back current transaction
mysqli::select_db() | mysqli_select_db() | N/A | Selects the default database for database queries
mysqli::set_charset() | mysqli_set_charset() | N/A | Sets the default client character set
mysqli::ssl_set() | mysqli_ssl_set() | N/A | Used for establishing secure connections using SSL
mysqli::stat() | mysqli_stat() | N/A | Gets the current system status
mysqli::stmt_init() | mysqli_stmt_init() | N/A | Initializes a statement and returns an object for use with mysqli_stmt_prepare
mysqli::store_result() | mysqli_store_result() | N/A | Transfers a result set from the last query
mysqli::thread_id() | mysqli_thread_id() | N/A | Returns the thread ID for the current connection
mysqli::thread_safe() | mysqli_thread_safe() | N/A | Returns whether thread safety is given or not
mysqli::use_result() | mysqli_use_result() | N/A | Initiate a result set retrieval
Summary of mysqli_stmt methods
MySQL_STMT
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | Returns the total number of rows changed, deleted, or inserted by the last executed statement
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | Returns the error code for the most recent statement call
$mysqli_stmt::error | mysqli_stmt_error() | N/A | Returns a string description for last statement error
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | Returns the number of field in the given statement - not documented
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | Get the ID generated from the previous INSERT operation
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | Return the number of rows in statements result set
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | Returns the number of parameter for the given statement
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | Returns SQLSTATE error from previous statement operation
Methods
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Used to get the current value of a statement attribute
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Used to modify the behavior of a prepared statement
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | Binds variables to a prepared statement as parameters
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | Binds variables to a prepared statement for result storage
mysqli_stmt::close() | mysqli_stmt_close() | N/A | Closes a prepared statement
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Seeks to an arbitrary row in statement result set
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Executes a prepared Query
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | Fetch results from a prepared statement into the bound variables
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Frees stored result memory for the given statement handle
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Gets a result set from a prepared statement. mysqlnd でのみ使用可能です。
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | NOT DOCUMENTED
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | Checks if there are more query results from a multiple query
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | Reads the next result from a multiple query
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | See also property $mysqli_stmt::num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Prepare an SQL statement for execution
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Resets a prepared statement
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | Returns result set metadata from a prepared statement
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | Send data in blocks
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Transfers a result set from a prepared statement
Summary of mysqli_result methods
mysqli_result
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli_result::current_field | mysqli_field_tell() | N/A | Get current field offset of a result pointer
$mysqli_result::field_count | mysqli_num_fields() | N/A | Get the number of fields in a result
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Returns the lengths of the columns of the current row in the result set
$mysqli_result::num_rows | mysqli_num_rows() | N/A | Gets the number of rows in a result
Methods
mysqli_result::data_seek() | mysqli_data_seek() | N/A | Adjusts the result pointer to an arbitrary row in the result
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Fetches all result rows and returns the result set as an associative array, a numeric array, or both. mysqlnd でのみ使用可能です。
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Fetch a result row as an associative, a numeric array, or both
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Fetch a result row as an associative array
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | Fetch a single column from the next row of a result set
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Fetch meta-data for a single field
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Returns the next field in the result set
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Returns an array of objects representing the fields in a result set
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Returns the current row of a result set as an object
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Get a result row as an enumerated array
mysqli_result::field_seek() | mysqli_field_seek() | N/A | Set result pointer to a specified field offset
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Frees the memory associated with a result
Summary of mysqli_driver methods
MySQL_Driver
OOP Interface | Procedural Interface | Alias (Do not use) | Description
Properties
$mysqli_driver::mysqli_report | mysqli_report() | N/A | Sets mysqli error reporting mode
Methods
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | NOT DOCUMENTED
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | NOT DOCUMENTED

注意:

Alias functions are provided for backward compatibility purposes only. Do not use them in new projects.


mysqli クラス

(PHP 5, PHP 7, PHP 8)

はじめに

PHP と MySQL データベースの間の接続を表します。

クラス概要

class mysqli {
/* プロパティ */
public readonly int|string $affected_rows;
public readonly string $client_info;
public readonly int $client_version;
public readonly int $connect_errno;
public readonly ?string $connect_error;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly int $field_count;
public readonly string $host_info;
public readonly ?string $info;
public readonly int|string $insert_id;
public readonly string $server_info;
public readonly int $server_version;
public readonly string $sqlstate;
public readonly int $protocol_version;
public readonly int $thread_id;
public readonly int $warning_count;
/* メソッド */
public __construct(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null
)
public autocommit(bool $enable): bool
public begin_transaction(int $flags = 0, ?string $name = null): bool
public change_user(string $username, #[\SensitiveParameter] string $password, ?string $database): bool
public character_set_name(): string
public close(): true
public commit(int $flags = 0, ?string $name = null): bool
public connect(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null
): bool
public debug(string $options): true
public dump_debug_info(): bool
public execute_query(string $query, ?array $params = null): mysqli_result|bool
public get_charset(): ?object
public get_client_info(): string
public get_connection_stats(): array
public get_server_info(): string
public get_warnings(): mysqli_warning|false
public init(): ?bool
public kill(int $process_id): bool
public more_results(): bool
public multi_query(string $query): bool
public next_result(): bool
public options(int $option, string|int $value): bool
public ping(): bool
public static poll(
?array &$read,
?array &$error,
array &$reject,
int $seconds,
int $microseconds = 0
): int|false
public prepare(string $query): mysqli_stmt|false
public query(string $query, int $result_mode = MYSQLI_STORE_RESULT): mysqli_result|bool
public real_connect(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null,
int $flags = 0
): bool
public real_escape_string(string $string): string
public real_query(string $query): bool
public reap_async_query(): mysqli_result|bool
public refresh(int $flags): bool
public release_savepoint(string $name): bool
public rollback(int $flags = 0, ?string $name = null): bool
public savepoint(string $name): bool
public select_db(string $database): bool
public set_charset(string $charset): bool
public ssl_set(
?string $key,
?string $certificate,
?string $ca_certificate,
?string $ca_path,
?string $cipher_algos
): true
public stat(): string|false
public stmt_init(): mysqli_stmt|false
public store_result(int $mode = 0): mysqli_result|false
public thread_safe(): bool
public use_result(): mysqli_result|false
}

目次

  • mysqli::$affected_rows — 直前の MySQL の操作で変更された行の数を得る
  • mysqli::autocommit — データベース更新の自動コミットをオンまたはオフにする
  • mysqli::begin_transaction — トランザクションを開始する
  • mysqli::change_user — 指定されたデータベース接続のユーザー名を変更する
  • mysqli::character_set_name — データベース接続の現在の文字コードセットを返す
  • mysqli::close — 事前にオープンしているデータベース接続を閉じる
  • mysqli::commit — 現在のトランザクションをコミットする
  • mysqli::$connect_errno — 直近の接続コールに関するエラーコードを返す
  • mysqli::$connect_error — 直近の接続エラーの説明を返す
  • mysqli::__construct — 新規に MySQL サーバーへの接続をオープンする
  • mysqli::debug — デバッグ操作を行う
  • mysqli::dump_debug_info — デバッグ情報をログに出力する
  • mysqli::$errno — 直近の関数コールによるエラーコードを返す
  • mysqli::$error — 直近のエラーの内容を文字列で返す
  • mysqli::$error_list — 直近で実行したコマンドからのエラーの一覧を返す
  • mysqli::execute_query — SQL文を準備し、変数をバインドし、実行する
  • mysqli::$field_count — 直近のクエリのカラムの数を返す
  • mysqli::get_charset — 文字セットオブジェクトを返す
  • mysqli::$client_info — MySQL クライアント情報を取得する
  • mysqli::$client_version — MySQL クライアントのバージョンを整数値で返す
  • mysqli::get_connection_stats — クライアント接続に関する統計情報を返す
  • mysqli::$host_info — 使用している接続の型を文字列で返す
  • mysqli::$protocol_version — 使用している MySQL プロトコルのバージョンを返す
  • mysqli::$server_info — MySQL サーバーのバージョンを返す
  • mysqli::$server_version — MySQL サーバーのバージョンを整数値で返す
  • mysqli::get_warnings — SHOW WARNINGS の結果を取得する
  • mysqli::$info — 直近に実行されたクエリの情報を取得する
  • mysqli::init — MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli::$insert_id — 直近のクエリの AUTO_INCREMENT カラムで生成した値を返す
  • mysqli::kill — サーバーに MySQL スレッドの停止を問い合わせる
  • mysqli::more_results — マルチクエリからの結果がまだ残っているかどうかを調べる
  • mysqli::multi_query — データベース上でひとつ以上のクエリを実行する
  • mysqli::next_result — multi_query の、次の結果を準備する
  • mysqli::options — オプションを設定する
  • mysqli::ping — サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる
  • mysqli::poll — 接続を問い合わせる
  • mysqli::prepare — 実行するための SQL文 を準備する
  • mysqli::query — データベース上でクエリを実行する
  • mysqli::real_connect — mysql サーバーとの接続をオープンする
  • mysqli::real_escape_string — 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
  • mysqli::real_query — SQL クエリを実行する
  • mysqli::reap_async_query — 非同期クエリから結果を取得する
  • mysqli::refresh — リフレッシュする
  • mysqli::release_savepoint — 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する
  • mysqli::rollback — 現在のトランザクションをロールバックする
  • mysqli::savepoint — トランザクションのセーブポイントを設定する
  • mysqli::select_db — クエリを実行するためのデフォルトのデータベースを選択する
  • mysqli::set_charset — クライアントの文字セットを設定する
  • mysqli::$sqlstate — 直前の MySQL の操作での SQLSTATE エラーを返す
  • mysqli::ssl_set — SSL を使用したセキュアな接続を確立する
  • mysqli::stat — 現在のシステム状態を取得する
  • mysqli::stmt_init — ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す
  • mysqli::store_result — 直近のクエリから結果セットを転送する
  • mysqli::$thread_id — 現在の接続のスレッド ID を返す
  • mysqli::thread_safe — スレッドセーフであるかどうかを返す
  • mysqli::use_result — 結果セットの取得を開始する
  • mysqli::$warning_count — 指定した接続の直近のクエリから発生した警告の数を返す


直前の MySQL の操作で変更された行の数を得る

  • ≪ mysqli
  • mysqli::autocommit ≫
  • PHP Manual
  • mysqli
  • 直前の MySQL の操作で変更された行の数を得る

mysqli::$affected_rows

mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — 直前の MySQL の操作で変更された行の数を得る

説明

オブジェクト指向型

int|string $mysqli->affected_rows;

手続き型

mysqli_affected_rows(mysqli $mysql): int|string

直近の INSERT、 UPDATE、REPLACE あるいは DELETE クエリにより変更された行の数を返します。

SELECT 文の場合は、 mysqli_num_rows() と同じように動作します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

正の整数が返された場合、それは変更された行数かあるいは取得された行数を 示します。ゼロが返された場合、それは UPDATE 文でレコードが更新されなかったか WHERE 条件に当てはまる行がなかった、またはクエリが実行されなかったことを 示します。-1 は、クエリがエラーを返したか、 mysqli_affected_rows() がバッファリングされていない SELECT に対してコールされたことを示します。

注意:

変更された行数が整数型の最大値 (PHP_INT_MAX) をこえた場合、 結果の行数は文字列として返されます。

例

例1 $mysqli->affected_rows の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 行を挿入します */
$mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
printf("Affected rows (INSERT): %d\n", $mysqli->affected_rows);

$mysqli->query("ALTER TABLE Language ADD Status int default 0");

/* 行を更新します */
$mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
printf("Affected rows (UPDATE): %d\n", $mysqli->affected_rows);

/* 行を削除します */
$mysqli->query("DELETE FROM Language WHERE Percentage < 50");
printf("Affected rows (DELETE): %d\n", $mysqli->affected_rows);

/* 全件選択します。 */
$result = $mysqli->query("SELECT CountryCode FROM Language");
printf("Affected rows (SELECT): %d\n", $mysqli->affected_rows);

/* Language テーブルを削除します。 */
$mysqli->query("DROP TABLE Language");

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 行を挿入します */
mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
printf("Affected rows (INSERT): %d\n", mysqli_affected_rows($link));

mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

/* 行を更新します */
mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
printf("Affected rows (UPDATE): %d\n", mysqli_affected_rows($link));

/* 行を削除します */
mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
printf("Affected rows (DELETE): %d\n", mysqli_affected_rows($link));

/* 全件選択します。 */
$result = mysqli_query($link, "SELECT CountryCode FROM Language");
printf("Affected rows (SELECT): %d\n", mysqli_affected_rows($link));

/* Language テーブルを削除します。 */
mysqli_query($link, "DROP TABLE Language");

上の例の出力は以下となります。

Affected rows (INSERT): 984
Affected rows (UPDATE): 168
Affected rows (DELETE): 815
Affected rows (SELECT): 169

参考

  • mysqli_num_rows() - 結果セットの行数を取得する
  • mysqli_info() - 直近に実行されたクエリの情報を取得する


データベース更新の自動コミットをオンまたはオフにする

  • ≪ mysqli::$affected_rows
  • mysqli::begin_transaction ≫
  • PHP Manual
  • mysqli
  • データベース更新の自動コミットをオンまたはオフにする

mysqli::autocommit

mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — データベース更新の自動コミットをオンまたはオフにする

説明

オブジェクト指向型

public mysqli::autocommit(bool $enable): bool

手続き型

mysqli_autocommit(mysqli $mysql, bool $enable): bool

指定されたデータベース接続リソースに対するクエリの 自動コミットモードをオンまたはオフにします。

現在の自動コミットモードを知るには、SQL コマンド SELECT @@autocommit を使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

enable

自動コミットを有効にするかどうか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::autocommit() の例

オブジェクト指向型

<?php
/* Tell mysqli to throw an exception if an error occurs */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* The table engine has to support transactions */
$mysqli->query("CREATE TABLE IF NOT EXISTS language (
Code text NOT NULL,
Speakers int(11) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

/* Turn autocommit off */
$mysqli->autocommit(false);

$result = $mysqli->query("SELECT @@autocommit");
$row = $result->fetch_row();
printf("Autocommit is %s\n", $row[0]);

try {
/* Prepare insert statement */
$stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
$stmt->bind_param('ss', $language_code, $native_speakers);

/* Insert some values */
$language_code = 'DE';
$native_speakers = 50_123_456;
$stmt->execute();
$language_code = 'FR';
$native_speakers = 40_546_321;
$stmt->execute();

/* Commit the data in the database. This doesn't set autocommit=true */
$mysqli->commit();
print "Committed 2 rows in the database\n";

$result = $mysqli->query("SELECT @@autocommit");
$row = $result->fetch_row();
printf("Autocommit is %s\n", $row[0]);

/* Try to insert more values */
$language_code = 'PL';
$native_speakers = 30_555_444;
$stmt->execute();
$language_code = 'DK';
$native_speakers = 5_222_444;
$stmt->execute();

/* Setting autocommit=true will trigger a commit */
$mysqli->autocommit(true);

print "Committed 2 row in the database\n";
} catch (mysqli_sql_exception $exception) {
$mysqli->rollback();

throw $exception;
}

手続き型

<?php

/* Tell mysqli to throw an exception if an error occurs */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

/* The table engine has to support transactions */
mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
Code text NOT NULL,
Speakers int(11) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

/* Turn autocommit off */
mysqli_autocommit($mysqli, false);

$result = mysqli_query($mysqli, "SELECT @@autocommit");
$row = mysqli_fetch_row($result);
printf("Autocommit is %s\n", $row[0]);

try {
/* Prepare insert statement */
$stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

/* Insert some values */
$language_code = 'DE';
$native_speakers = 50_123_456;
mysqli_stmt_execute($stmt);
$language_code = 'FR';
$native_speakers = 40_546_321;
mysqli_stmt_execute($stmt);

/* Commit the data in the database. This doesn't set autocommit=true */
mysqli_commit($mysqli);
print "Committed 2 rows in the database\n";

$result = mysqli_query($mysqli, "SELECT @@autocommit");
$row = mysqli_fetch_row($result);
printf("Autocommit is %s\n", $row[0]);

/* Try to insert more values */
$language_code = 'PL';
$native_speakers = 30_555_444;
mysqli_stmt_execute($stmt);
$language_code = 'DK';
$native_speakers = 5_222_444;
mysqli_stmt_execute($stmt);

/* Setting autocommit=true will trigger a commit */
mysqli_autocommit($mysqli, true);

print "Committed 2 row in the database\n";
} catch (mysqli_sql_exception $exception) {
mysqli_rollback($mysqli);

throw $exception;
}

上の例の出力は以下となります。

Autocommit is 0
Committed 2 rows in the database
Autocommit is 0
Committed 2 row in the database
Autocommit is 0
Committed 2 rows in the database
Autocommit is 0
Committed 2 row in the database

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

参考

  • mysqli_begin_transaction() - トランザクションを開始する
  • mysqli_commit() - 現在のトランザクションをコミットする
  • mysqli_rollback() - 現在のトランザクションをロールバックする


トランザクションを開始する

  • ≪ mysqli::autocommit
  • mysqli::change_user ≫
  • PHP Manual
  • mysqli
  • トランザクションを開始する

mysqli::begin_transaction

mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — トランザクションを開始する

説明

オブジェクト指向型

public mysqli::begin_transaction(int $flags = 0, ?string $name = null): bool

手続き型:

mysqli_begin_transaction(mysqli $mysql, int $flags = 0, ?string $name = null): bool

トランザクションを開始します。InnoDB エンジン (デフォルトで有効になっています) が必要です。 MySQL のトランザクションの詳細な動作は、 » http://dev.mysql.com/doc/mysql/en/commit.html を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

flags

以下のフラグが使えます。

  • MYSQLI_TRANS_START_READ_ONLY: "START TRANSACTION READ ONLY" でトランザクションを開始します。 MySQL 5.6 以上が必要です。

  • MYSQLI_TRANS_START_READ_WRITE: "START TRANSACTION READ WRITE" でトランザクションを開始します。 MySQL 5.6 以上が必要です。

  • MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT: "START TRANSACTION WITH CONSISTENT SNAPSHOT" でトランザクションを開始します。

name

トランザクションのセーブポイント名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | name は、nullable になりました。

例

例1 mysqli::begin_transaction() の例

オブジェクト指向型

<?php

/* Tell mysqli to throw an exception if an error occurs */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* The table engine has to support transactions */
$mysqli->query("CREATE TABLE IF NOT EXISTS language (
Code text NOT NULL,
Speakers int(11) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

/* Start transaction */
$mysqli->begin_transaction();

try {
/* Insert some values */
$mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

/* Try to insert invalid values */
$language_code = 'FR';
$native_speakers = 'Unknown';
$stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
$stmt->bind_param('ss', $language_code, $native_speakers);
$stmt->execute();

/* If code reaches this point without errors then commit the data in the database */
$mysqli->commit();
} catch (mysqli_sql_exception $exception) {
$mysqli->rollback();

throw $exception;
}

手続き型

<?php

/* Tell mysqli to throw an exception if an error occurs */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

/* The table engine has to support transactions */
mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
Code text NOT NULL,
Speakers int(11) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

/* Start transaction */
mysqli_begin_transaction($mysqli);

try {
/* Insert some values */
mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

/* Try to insert invalid values */
$language_code = 'FR';
$native_speakers = 'Unknown';
$stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
mysqli_stmt_execute($stmt);

/* If code reaches this point without errors then commit the data in the database */
mysqli_commit($mysqli);
} catch (mysqli_sql_exception $exception) {
mysqli_rollback($mysqli);

throw $exception;
}
?>

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

参考

  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする
  • mysqli_commit() - 現在のトランザクションをコミットする
  • mysqli_rollback() - 現在のトランザクションをロールバックする


指定されたデータベース接続のユーザー名を変更する

  • ≪ mysqli::begin_transaction
  • mysqli::character_set_name ≫
  • PHP Manual
  • mysqli
  • 指定されたデータベース接続のユーザー名を変更する

mysqli::change_user

mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — 指定されたデータベース接続のユーザー名を変更する

説明

オブジェクト指向型

public mysqli::change_user(string $username, #[\SensitiveParameter] string $password, ?string $database): bool

手続き型

mysqli_change_user(
mysqli $mysql,
string $username,
#[\SensitiveParameter] string $password,
?string $database
): bool

指定されたデータベース接続のユーザー名を変更し、 現在のデータベースを設定します。

ユーザーを正しく変更するには、username と password 引数を正しく渡す必要があります。 またそのユーザーが対象のデータベースに対する適切なパーミッションを 持っている必要があります。どんな理由であれ、認証に失敗するとカレントユーザーの 認証が継続されます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

username

MySQL のユーザー名。

password

MySQL のパスワード。

database

変更するデータベース。

引数には null 値を渡すこともできます。 その場合ユーザーの変更だけでデータベースの選択はされません。 そのようなケースでデータベースを選択したい場合には mysqli_select_db() 関数を使用してください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::change_user() の例

オブジェクト指向型

<?php

/* データベース test に接続します */
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

/* 接続をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* 変数 a を設定します */
$mysqli->query("SET @a:=1");

/* すべてをリセットし、新しいデータベースを選択します */
$mysqli->change_user("my_user", "my_password", "world");

if ($result = $mysqli->query("SELECT DATABASE()")) {
$row = $result->fetch_row();
printf("デフォルトデータベース: %s\n", $row[0]);
$result->close();
}

if ($result = $mysqli->query("SELECT @a")) {
$row = $result->fetch_row();
if ($row[0] === NULL) {
printf("変数 a の値は NULL\n");
}
$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
/* データベース test に接続します */
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

/* 接続をチェックします */
if (!$link) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* 変数 a を設定します */
mysqli_query($link, "SET @a:=1");

/* すべてをリセットし、新しいデータベースを選択します */
mysqli_change_user($link, "my_user", "my_password", "world");

if ($result = mysqli_query($link, "SELECT DATABASE()")) {
$row = mysqli_fetch_row($result);
printf("デフォルトデータベース: %s\n", $row[0]);
mysqli_free_result($result);
}

if ($result = mysqli_query($link, "SELECT @a")) {
$row = mysqli_fetch_row($result);
if ($row[0] === NULL) {
printf("変数 a の値は NULL\n");
}
mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

デフォルトデータベース: world
変数 a の値は NULL

注意

注意:

このコマンドを使用すると、常に、カレントのデータベース接続は あたかも完全に新しいデータベース接続であるかのようになります。 これにより、全てのアクティブなトランザクションはロールバックされ、 一時テーブルは全てクローズされ、ロックされたテーブルはすべて 開放されます。

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_select_db() - クエリを実行するためのデフォルトのデータベースを選択する


データベース接続の現在の文字コードセットを返す

  • ≪ mysqli::change_user
  • mysqli::close ≫
  • PHP Manual
  • mysqli
  • データベース接続の現在の文字コードセットを返す

mysqli::character_set_name

mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — データベース接続の現在の文字コードセットを返す

説明

オブジェクト指向型

public mysqli::character_set_name(): string

手続き型

mysqli_character_set_name(mysqli $mysql): string

データベース接続の現在の文字コードセットを返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

データベース接続の現在の文字コードセットを返します。

例

例1 mysqli::character_set_name() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* デフォルトの文字コードセットを設定します。*/
$mysqli->set_charset('utf8mb4');

/* 現在の文字コードセットを出力します */
$charset = $mysqli->character_set_name();
printf("Current character set is %s\n", $charset);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

/* デフォルトの文字コードセットを設定します。*/
mysqli_set_charset($mysqli, 'utf8mb4');

/* 現在の文字コードセットを出力します */
$charset = mysqli_character_set_name($mysqli);
printf("Current character set is %s\n", $charset);

上の例の出力は以下となります。

Current character set is utf8mb4

参考

  • mysqli_set_charset() - クライアントの文字セットを設定する
  • mysqli_real_escape_string() - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする


事前にオープンしているデータベース接続を閉じる

  • ≪ mysqli::character_set_name
  • mysqli::commit ≫
  • PHP Manual
  • mysqli
  • 事前にオープンしているデータベース接続を閉じる

mysqli::close

mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — 事前にオープンしているデータベース接続を閉じる

説明

オブジェクト指向型

public mysqli::close(): true

手続き型

mysqli_close(mysqli $mysql): true

既に開いているデータベース接続を閉じます。

既に開いている、持続的でない MySQL 接続と、 結果セットはオブジェクトが破棄されるとすぐに閉じられます。 既に開いている接続と結果セットを明示的に閉じるのはオプションですが、 データベースから結果を取得した後、大量に処理が残っている場合、 データベースに関する処理を全て実行し終わったらすぐに接続を閉じるのが望ましいです。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。

例

例1 mysqli::close() example

オブジェクト指向型

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
$result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
/* 不要になったらすぐに、接続を閉じます */
$mysqli->close();
foreach ($result as $row) {
/* データベースから取得したデータを処理します */
}

手続き型

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
$result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
/* 不要になったらすぐに、接続を閉じます */
mysqli_close($mysqli);
foreach ($result as $row) {
/* データベースから取得したデータを処理します */
}

注意

注意:

mysqli_close() は、持続的な接続を閉じません。 詳細な情報は、マニュアルの 持続的データベース接続を参照ください。

参考

  • mysqli::__construct() - 新規に MySQL サーバーへの接続をオープンする
  • mysqli_init() - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_free_result() - 結果に関連付けられたメモリを開放する


現在のトランザクションをコミットする

  • ≪ mysqli::close
  • mysqli::$connect_errno ≫
  • PHP Manual
  • mysqli
  • 現在のトランザクションをコミットする

mysqli::commit

mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — 現在のトランザクションをコミットする

説明

オブジェクト指向型

public mysqli::commit(int $flags = 0, ?string $name = null): bool

手続き型

mysqli_commit(mysqli $mysql, int $flags = 0, ?string $name = null): bool

データベース接続の現在のトランザクションをコミットします。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

flags

定数 MYSQLI_TRANS_COR_* のビットマスク。

name

指定した場合は、COMMIT/*name*/ を実行します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
8.0.0 | name は、nullable になりました。

例

mysqli::begin_transaction() の例 を参照ください。

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

参考

  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする
  • mysqli_begin_transaction() - トランザクションを開始する
  • mysqli_rollback() - 現在のトランザクションをロールバックする
  • mysqli_savepoint() - トランザクションのセーブポイントを設定する


直近の接続コールに関するエラーコードを返す

  • ≪ mysqli::commit
  • mysqli::$connect_error ≫
  • PHP Manual
  • mysqli
  • 直近の接続コールに関するエラーコードを返す

mysqli::$connect_errno

mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — 直近の接続コールに関するエラーコードを返す

説明

オブジェクト指向型

int $mysqli->connect_errno;

手続き型

mysqli_connect_errno(): int

直近で試みた接続コールに関するエラー番号を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近で試みた接続コールが失敗した場合、 エラーコードを返します。ゼロは、何もエラーが発生しなかったことを示します。

例

例1 $mysqli->connect_errno の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_OFF);
/* デフォルトのエラーメッセージを抑制するには、@ を使います。 */
$mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
if ($mysqli->connect_errno) {
/* エラーをロギングする方法はお好きなものをどうぞ */
error_log('Connection error: ' . $mysqli->connect_errno);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_OFF);
/* デフォルトのエラーメッセージを抑制するには、@ を使います。 */
$link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
if (!$link) {
/* エラーをロギングする方法はお好きなものをどうぞ */
error_log('Connection error: ' . mysqli_connect_errno());
}

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_connect_error() - 直近の接続エラーの説明を返す
  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す


直近の接続エラーの説明を返す

  • ≪ mysqli::$connect_errno
  • mysqli::__construct ≫
  • PHP Manual
  • mysqli
  • 直近の接続エラーの説明を返す

mysqli::$connect_error

mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — 直近の接続エラーの説明を返す

説明

オブジェクト指向型

?string $mysqli->connect_error;

手続き型

mysqli_connect_error(): ?string

直近の接続エラーの、エラーメッセージを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーの内容を表す文字列を返します。エラーが発生しなかった場合は null を返します。

例

例1 $mysqli->connect_error の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_OFF);
/* デフォルトのエラーメッセージを抑制するには、@ を使います。 */
$mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
if ($mysqli->connect_error) {
/* エラーをロギングする方法はお好きなものをどうぞ */
error_log('Connection error: ' . $mysqli->connect_error);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_OFF);
/* デフォルトのエラーメッセージを抑制するには、@ を使います。 */
$link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
if (!$link) {
/* エラーをロギングする方法はお好きなものをどうぞ */
error_log('Connection error: ' . mysqli_connect_error());
}

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_connect_errno() - 直近の接続コールに関するエラーコードを返す
  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す


新規に MySQL サーバーへの接続をオープンする

  • ≪ mysqli::$connect_error
  • mysqli::debug ≫
  • PHP Manual
  • mysqli
  • 新規に MySQL サーバーへの接続をオープンする

mysqli::__construct

mysqli::connect

mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — 新規に MySQL サーバーへの接続をオープンする

説明

オブジェクト指向型

public mysqli::__construct(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null
)
public mysqli::connect(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null
): bool

手続き型

mysqli_connect(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null
): mysqli|false

MySQL サーバーへの接続をオープンします。

パラメータ

hostname

ホスト名または IP アドレスです。この引数に null を渡すと mysqli.default_host から値を取得します。 可能な場合は、TCP/IP プロトコルの代わりにパイプが使用されます。 ホスト名とポートが一緒に指定された場合は、TCP/IP プロトコルが使われます。 例: localhost:3308.

ホストの前に p: をつけると、持続的な接続を開きます。 接続プールから開いた接続上で mysqli_change_user() が自動的にコールされます。

username

MySQL のユーザー名。 null の場合は、mysqli.default_user iniオプションに基づいてユーザー名が決定されます。

password

MySQL のパスワード。 null の場合は、mysqli.default_pw iniオプションに基づいてパスワードが決定されます。

database

null 以外を指定した場合は、 クエリが実行されるデフォルトのデータベースとなります。

port

MySQL サーバーに接続する際のポート番号を指定します。 null の場合は、mysqli.default_port iniオプションに基づいてポート番号が決定されます。

socket

使用するソケットあるいは名前つきパイプを指定します。 null の場合は、mysqli.default_socket iniオプションに基づいてソケットが決定されます。

注意:

socket 引数を指定しても、MySQL サーバーへの 接続時の型を明示的に定義することにはなりません。MySQL サーバーへの 接続方法については hostname 引数で定義されます。

戻り値

mysqli_connect() は、 MySQL サーバーへの接続を表すオブジェクトを返します。 失敗した場合に false を返します.

mysqli::connect() は、成功した場合に true を返します。 失敗した場合に null を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
8.1.0 | mysqli::connect() は、成功時に null ではなく true を返すようになりました。
7.4.0 | すべてのパラメータが、nullable になりました。

例

例1 mysqli::__construct() の例

オブジェクト指向型

<?php

/* You should enable error reporting for mysqli before attempting to make a connection */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');

/* Set the desired charset after establishing a connection */
$mysqli->set_charset('utf8mb4');

printf("Success... %s\n", $mysqli->host_info);

手続き型

<?php

/* You should enable error reporting for mysqli before attempting to make a connection */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');

/* Set the desired charset after establishing a connection */
mysqli_set_charset($mysqli, 'utf8mb4');

printf("Success... %s\n", mysqli_get_host_info($mysqli));

上の例の出力は、 たとえば以下のようになります。

Success... localhost via TCP/IP

例2 mysqli クラスを拡張する

<?php

class FooMysqli extends mysqli {
public function __construct($host, $user, $pass, $db, $port, $socket, $charset) {
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
parent::__construct($host, $user, $pass, $db, $port, $socket);
$this->set_charset($charset);
}
}

$db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');

例3 手動によるエラーハンドリング

エラーの報告機能が無効になっている場合、 開発者がエラーのチェックとエラー処理を行う必要があります。

オブジェクト指向型

<?php

error_reporting(0);
mysqli_report(MYSQLI_REPORT_OFF);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
if ($mysqli->connect_errno) {
throw new RuntimeException('mysqli connection error: ' . $mysqli->connect_error);
}

/* Set the desired charset after establishing a connection */
$mysqli->set_charset('utf8mb4');
if ($mysqli->errno) {
throw new RuntimeException('mysqli error: ' . $mysqli->error);
}

手続き型

<?php

error_reporting(0);
mysqli_report(MYSQLI_REPORT_OFF);
$mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
if (mysqli_connect_errno()) {
throw new RuntimeException('mysqli connection error: ' . mysqli_connect_error());
}

/* Set the desired charset after establishing a connection */
mysqli_set_charset($mysqli, 'utf8mb4');
if (mysqli_errno($mysqli)) {
throw new RuntimeException('mysqli error: ' . mysqli_error($mysqli));
}

注意

注意:

MySQLnd は常に、サーバーのデフォルト文字セットを想定しています。この文字セットは接続時の ハンドシェイク/認証 のときに送信され、これを mysqlnd が使います。

Libmysqlclient が使うデフォルトの文字セットは my.cnf で設定したものです。あるいは明示的に mysqli_options() をコールして設定することもできます。 これは、mysqli_init() のあとで mysqli_real_connect() を実行する前にコールします。

注意:

オブジェクト指向型 に関する注意: 接続に失敗した場合にもオブジェクトが返されます。 接続が失敗したかどうかを確かめるには、先ほどの例のように mysqli_connect_error() 関数あるいは mysqli->connect_error プロパティを使用しましょう。

注意:

接続タイムアウトなどのオプションを設定する必要がある場合は、かわりに mysqli_real_connect() を使わなければなりません。

注意:

コンストラクタをパラメータなしでコールするのは、 mysqli_init() をコールするのと同じ意味になります。

注意:

エラー "Can't create TCP/IP socket (10106)" が発生するのは、たいていは variables_order 設定ディレクティブに E が含まれていない場合です。 Windows では、これが含まれていなければ SYSTEMROOT 環境変数が使用できず、PHP が Winsock の読み込みに失敗します。

参考

  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_options() - オプションを設定する
  • mysqli_connect_errno() - 直近の接続コールに関するエラーコードを返す
  • mysqli_connect_error() - 直近の接続エラーの説明を返す
  • mysqli_close() - 事前にオープンしているデータベース接続を閉じる


デバッグ操作を行う

  • ≪ mysqli::__construct
  • mysqli::dump_debug_info ≫
  • PHP Manual
  • mysqli
  • デバッグ操作を行う

mysqli::debug

mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — デバッグ操作を行う

説明

オブジェクト指向型

public mysqli::debug(string $options): true

手続き型

mysqli_debug(string $options): true

Fred Fish debugging library を使用してデバッグを行います。

パラメータ

options

実行するデバッグ操作を表す文字列。

デバッグ操作を表す文字列は、 以下のようなコロン区切りでフィールドを並べたものです:

<field_1>:<field_2>:<field_N>
それぞれのフィールドは、 必須のフラグ文字の後にオプションの , と、カンマ区切りの modifier (修正子) の一覧が続きます: flag[,modifier,modifier,...,modifier]

認識するフラグ文字
options に指定する文字 | 説明
O | MYSQLND_DEBUG_FLUSH
A/a | MYSQLND_DEBUG_APPEND
F | MYSQLND_DEBUG_DUMP_FILE
i | MYSQLND_DEBUG_DUMP_PID
L | MYSQLND_DEBUG_DUMP_LINE
m | MYSQLND_DEBUG_TRACE_MEMORY_CALLS
n | MYSQLND_DEBUG_DUMP_LEVEL
o | 出力先のファイル
T | MYSQLND_DEBUG_DUMP_TIME
t | MYSQLND_DEBUG_DUMP_TRACE
x | MYSQLND_DEBUG_PROFILE_CALLS

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。

例

例1 トレースファイルの作成

<?php

/* ローカル（クライアント）マシンの '/tmp/client.trace' に
トレースファイルを作成します */
mysqli_debug("d:t:o,/tmp/client.trace");

?>

注意

注意:

mysqli_debug() 関数を使用するには、 MySQL クライアントライブラリを、デバッグ機能を有効にしてコンパイルする 必要があります。

参考

  • mysqli_dump_debug_info() - デバッグ情報をログに出力する
  • mysqli_report() - mysqli_driver->report_mode のエイリアス


デバッグ情報をログに出力する

  • ≪ mysqli::debug
  • mysqli::$errno ≫
  • PHP Manual
  • mysqli
  • デバッグ情報をログに出力する

mysqli::dump_debug_info

mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — デバッグ情報をログに出力する

説明

オブジェクト指向型

public mysqli::dump_debug_info(): bool

手続き型

mysqli_dump_debug_info(mysqli $mysql): bool

この関数は SUPER 権限を持ったユーザーによって実行されるされることを 想定しており、link で指定した接続に関連する MySQL サーバーのデバッグ情報をログに出力します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_debug() - デバッグ操作を行う


直近の関数コールによるエラーコードを返す

  • ≪ mysqli::dump_debug_info
  • mysqli::$error ≫
  • PHP Manual
  • mysqli
  • 直近の関数コールによるエラーコードを返す

mysqli::$errno

mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — 直近の関数コールによるエラーコードを返す

説明

オブジェクト指向型

int $mysqli->errno;

手続き型

mysqli_errno(mysqli $mysql): int

直近の MySQLi 関数のコールが成功あるいは失敗した際のエラーコードを返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

直近のコールが失敗した場合、エラーコードを返します。 ゼロは、何もエラーが発生しなかったことを示します。

例

例1 $mysqli->errno の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if ($mysqli->connect_errno) {
printf("Connect failed: %s\n", $mysqli->connect_error);
exit();
}

if (!$mysqli->query("SET a=1")) {
printf("Errorcode: %d\n", $mysqli->errno);
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

if (!mysqli_query($link, "SET a=1")) {
printf("Errorcode: %d\n", mysqli_errno($link));
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Errorcode: 1193

参考

  • mysqli_connect_errno() - 直近の接続コールに関するエラーコードを返す
  • mysqli_connect_error() - 直近の接続エラーの説明を返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す


直近のエラーの内容を文字列で返す

  • ≪ mysqli::$errno
  • mysqli::$error_list ≫
  • PHP Manual
  • mysqli
  • 直近のエラーの内容を文字列で返す

mysqli::$error

mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — 直近のエラーの内容を文字列で返す

説明

オブジェクト指向型

string $mysqli->error;

手続き型

mysqli_error(mysqli $mysql): string

直近の MySQLi 関数のコールが成功あるいは失敗した際のエラーメッセージを返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

エラーの内容を表す文字列を返します。エラーが発生しなかった場合は空文字列を返します。

例

例1 $mysqli->error の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if ($mysqli->connect_errno) {
printf("Connect failed: %s\n", $mysqli->connect_error);
exit();
}

if (!$mysqli->query("SET a=1")) {
printf("Error message: %s\n", $mysqli->error);
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

if (!mysqli_query($link, "SET a=1")) {
printf("Error message: %s\n", mysqli_error($link));
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error message: Unknown system variable 'a'

参考

  • mysqli_connect_errno() - 直近の接続コールに関するエラーコードを返す
  • mysqli_connect_error() - 直近の接続エラーの説明を返す
  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す


直近で実行したコマンドからのエラーの一覧を返す

  • ≪ mysqli::$error
  • mysqli::execute_query ≫
  • PHP Manual
  • mysqli
  • 直近で実行したコマンドからのエラーの一覧を返す

mysqli::$error_list

mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — 直近で実行したコマンドからのエラーの一覧を返す

説明

オブジェクト指向型

array $mysqli->error_list;

手続き型

mysqli_error_list(mysqli $mysql): array

エラーの配列を返します。この配列の内容は、直近で実行した MySQLi 関数コールで発生したエラーです。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

エラーの一覧を返します。個々のエラーは連想配列形式で、 errno、error および sqlstate のキーを含みます。

例

例1 $mysqli->error_list の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "nobody", "");

/* 接続を確認します */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

if (!$mysqli->query("SET a=1")) {
print_r($mysqli->error_list);
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続を確認します */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

if (!mysqli_query($link, "SET a=1")) {
print_r(mysqli_error_list($link));
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [errno] => 1193
            [sqlstate] => HY000
            [error] => Unknown system variable 'a'
        )

)

参考

  • mysqli_connect_errno() - 直近の接続コールに関するエラーコードを返す
  • mysqli_connect_error() - 直近の接続エラーの説明を返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す


SQL文を準備し、変数をバインドし、実行する

  • ≪ mysqli::$error_list
  • mysqli::$field_count ≫
  • PHP Manual
  • mysqli
  • SQL文を準備し、変数をバインドし、実行する

mysqli::execute_query

mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — SQL文を準備し、変数をバインドし、実行する

説明

オブジェクト指向型

public mysqli::execute_query(string $query, ?array $params = null): mysqli_result|bool

手続き型

mysqli_execute_query(mysqli $mysql, string $query, ?array $params = null): mysqli_result|bool

SQL文を準備し、変数をバインドし、実行します。
mysqli::execute_query() メソッドは
mysqli::prepare(),
mysqli_stmt::bind_param(),
mysqli_stmt::execute(),
mysqli_stmt::get_result() のショートカットです。

SQL文 のテンプレートは、 ゼロ個以上のクエスチョンマーク (?) を使ったパラメータマーカを含めることができます。 パラメータマーカは、プレースホルダとも呼ばれています。 params を使って配列で指定しなければいけません。

プリペアドステートメントは内部的に作成され、 その処理は関数の外部に公開されません。 よって、mysqli_stmt オブジェクトを使うとアクセスできる、 ステートメントのプロパティにはアクセスできません。 この制限により、状態の情報は mysqli オブジェクトにコピーされ、 たとえば mysqli_affected_rows() や mysqli_error() のようなメソッドを通じてアクセスできます。

注意:

サーバーの max_allowed_packet より長いステートメントを mysqli_execute_query() に渡した場合、 返ってくるエラーコードはオペレーティングシステムによって異なります。 それぞれ、次のように振る舞います:

  • Linux 上では、エラーコード 1153 を返します。 エラーメッセージは got a packet bigger than max_allowed_packet bytes です。

  • Windows では、エラーコード 2006 を返します。 エラーメッセージは server has gone away です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

query

クエリ表す文字列。 単一の SQL 文で構成されている必要があります。

SQL文 には、 適切な位置にゼロ個以上のパラメータマーカを含めることができます。 パラメータマーカは、クエスチョンマーク(?)で表します。

注意:

マーカーは SQL文 中の特定の場所でのみ有効です。 INSERT文 の (行のカラムの値を指定する) VALUES() のリストや、 WHERE 句でカラムのデータと比較する値などが適切な位置の例です。 しかし、識別子 (テーブルやカラムの名前) には使用できません。

params

オプションのリストを配列で指定します。 これは、実行される SQL文 中でバインドされるパラメータと同じ要素数を持ちます。 個々の値は、文字列として扱われます。

戻り値

失敗時に false を返します。 SELECT, SHOW, DESCRIBE や EXPLAIN のような、 結果セットを生成するクエリが成功した時には mysqli_result オブジェクトを返します。 それ以外のクエリの場合は、true を返します。

例

例1 mysqli::execute_query() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

$query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
$result = $mysqli->execute_query($query, ['DEU']);
foreach ($result as $row) {
printf("%s (%s)\n", $row["Name"], $row["District"]);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
$result = mysqli_execute_query($link, $query, ['DEU']);
foreach ($result as $row) {
printf("%s (%s)\n", $row["Name"], $row["District"]);
}

上の例の出力は、 たとえば以下のようになります。

Aachen (Nordrhein-Westfalen)
Augsburg (Baijeri)
Bergisch Gladbach (Nordrhein-Westfalen)
Berlin (Berliini)
Bielefeld (Nordrhein-Westfalen)

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する


直近のクエリのカラムの数を返す

  • ≪ mysqli::execute_query
  • mysqli::get_charset ≫
  • PHP Manual
  • mysqli
  • 直近のクエリのカラムの数を返す

mysqli::$field_count

mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — 直近のクエリのカラムの数を返す

説明

オブジェクト指向型

int $mysqli->field_count;

手続き型

mysqli_field_count(mysqli $mysql): int

mysql が指す接続における直近のクエリの カラムの数を返します。この関数は、クエリが空でない結果セットを 生成すべきなのかそうではないのかを判断するために mysqli_store_result() 関数を使用する際に有用です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

結果セットのフィールド数を整数で返します。

例

例1 $mysqli->field_count の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

$mysqli->query( "DROP TABLE IF EXISTS friends");
$mysqli->query( "CREATE TABLE friends (id int, name varchar(20))");

$mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

$mysqli->real_query("SELECT * FROM friends");

if ($mysqli->field_count) {
/* これは select/show あるいは describe クエリです */
$result = $mysqli->store_result();

/* 結果セットを処理します */
$row = $result->fetch_row();

/* 結果セットを開放します */
$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

mysqli_query($link, "DROP TABLE IF EXISTS friends");
mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

mysqli_real_query($link, "SELECT * FROM friends");

if (mysqli_field_count($link)) {
/* これは select/show あるいは describe クエリです */
$result = mysqli_store_result($link);

/* 結果セットを処理します */
$row = mysqli_fetch_row($result);

/* 結果セットを開放します */
mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>


文字セットオブジェクトを返す

  • ≪ mysqli::$field_count
  • mysqli::$client_info ≫
  • PHP Manual
  • mysqli
  • 文字セットオブジェクトを返す

mysqli::get_charset

mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — 文字セットオブジェクトを返す

説明

オブジェクト指向型

public mysqli::get_charset(): ?object

手続き型

mysqli_get_charset(mysqli $mysql): ?object

文字セットオブジェクトを返します。 これは、現在アクティブな文字セットについてのプロパティを提供します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

この関数は、以下のプロパティを持つ文字セットオブジェクトを返します。

charset

文字セット名

collation

照合規則名

dir

文字セットの設定を読み込むディレクトリ。組み込みの文字セットについては ""

min_length

最小の文字の長さ (バイト数)

max_length

最大の文字の長さ (バイト数)

number

内部文字セット番号

state

文字セットの状態

例

例1 mysqli::get_charset() の例

オブジェクト指向型

<?php
$db = mysqli_init();
$db->real_connect("localhost","root","","test");
var_dump($db->get_charset());
?>

手続き型

<?php
$db = mysqli_init();
mysqli_real_connect($db, "localhost","root","","test");
var_dump(mysqli_get_charset($db));
?>

上の例の出力は以下となります。

object(stdClass)#2 (7) {
  ["charset"]=>
  string(6) "latin1"
  ["collation"]=>
  string(17) "latin1_swedish_ci"
  ["dir"]=>
  string(0) ""
  ["min_length"]=>
  int(1)
  ["max_length"]=>
  int(1)
  ["number"]=>
  int(8)
  ["state"]=>
  int(801)
}

参考

  • mysqli_character_set_name() - データベース接続の現在の文字コードセットを返す
  • mysqli_set_charset() - クライアントの文字セットを設定する


MySQL クライアント情報を取得する

  • ≪ mysqli::get_charset
  • mysqli::$client_version ≫
  • PHP Manual
  • mysqli
  • MySQL クライアント情報を取得する

mysqli::$client_info

mysqli::get_client_info

mysqli_get_client_info

(PHP 5, PHP 7, PHP 8)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — MySQL クライアント情報を取得する

説明

オブジェクト指向型

string $mysqli->client_info;
public mysqli::get_client_info(): string

手続き型

mysqli_get_client_info(?mysqli $mysql = null): string

MySQL クライアントライブラリのバージョンを文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

MySQL クライアントライブラリのバージョンを文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | mysqli_get_client_info() を 引数 mysql を付けて呼ぶことは、 推奨されなくなりました。 この関数はもはや引数を取ることはありませんが、 オプションの引数として、間違って値を渡すことは許されています。
8.1.0 | オブジェクト指向版の mysqli::get_client_info() は、推奨されなくなりました。

例

例1 mysqli_get_client_info

<?php

/* mysql クライアントライブラリのバージョンを
調べるために、接続する必要はありません */

printf("Client library version: %s\n", mysqli_get_client_info());
?>

参考

  • mysqli_get_client_version() - MySQL クライアントのバージョンを整数値で返す
  • mysqli_get_server_info() - MySQL サーバーのバージョンを返す
  • mysqli_get_server_version() - MySQL サーバーのバージョンを整数値で返す


MySQL クライアントのバージョンを整数値で返す

  • ≪ mysqli::$client_info
  • mysqli::get_connection_stats ≫
  • PHP Manual
  • mysqli
  • MySQL クライアントのバージョンを整数値で返す

mysqli::$client_version

mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — MySQL クライアントのバージョンを整数値で返す

説明

オブジェクト指向型

int $mysqli->client_version;

手続き型

mysqli_get_client_version(): int

クライアントのバージョン番号を整数値で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

MySQL クライアントライブラリのバージョンを、以下の書式で返します。 main_version*10000 + minor_version *100 + sub_version 例えば、4.1.0 は 40100 となります。

これは、ある機能が使用可能かどうかを知るため、クライアントライブラリの バージョンを手っ取り早く調べたい場合に有用です。

例

例1 mysqli_get_client_version

<?php

/* mysql クライアントライブラリのバージョンを
調べるために、接続する必要はありません */

printf("Client library version: %d\n", mysqli_get_client_version());
?>

参考

  • mysqli_get_client_info() - MySQL クライアント情報を取得する
  • mysqli_get_server_info() - MySQL サーバーのバージョンを返す
  • mysqli_get_server_version() - MySQL サーバーのバージョンを整数値で返す


クライアント接続に関する統計情報を返す

  • ≪ mysqli::$client_version
  • mysqli::$host_info ≫
  • PHP Manual
  • mysqli
  • クライアント接続に関する統計情報を返す

mysqli::get_connection_stats

mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::get_connection_stats -- mysqli_get_connection_stats — クライアント接続に関する統計情報を返す

説明

オブジェクト指向型

public mysqli::get_connection_stats(): array

手続き型

mysqli_get_connection_stats(mysqli $mysql): array

クライアント接続に関する統計情報を返します。

注意:

mysqlnd でのみ使用可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

接続の統計情報を含む配列を返します。

例

例1 mysqli_get_connection_stats() の例

<?php
$link = mysqli_connect();
print_r(mysqli_get_connection_stats($link));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [bytes_sent] => 43
    [bytes_received] => 80
    [packets_sent] => 1
    [packets_received] => 2
    [protocol_overhead_in] => 8
    [protocol_overhead_out] => 4
    [bytes_received_ok_packet] => 11
    [bytes_received_eof_packet] => 0
    [bytes_received_rset_header_packet] => 0
    [bytes_received_rset_field_meta_packet] => 0
    [bytes_received_rset_row_packet] => 0
    [bytes_received_prepare_response_packet] => 0
    [bytes_received_change_user_packet] => 0
    [packets_sent_command] => 0
    [packets_received_ok] => 1
    [packets_received_eof] => 0
    [packets_received_rset_header] => 0
    [packets_received_rset_field_meta] => 0
    [packets_received_rset_row] => 0
    [packets_received_prepare_response] => 0
    [packets_received_change_user] => 0
    [result_set_queries] => 0
    [non_result_set_queries] => 0
    [no_index_used] => 0
    [bad_index_used] => 0
    [slow_queries] => 0
    [buffered_sets] => 0
    [unbuffered_sets] => 0
    [ps_buffered_sets] => 0
    [ps_unbuffered_sets] => 0
    [flushed_normal_sets] => 0
    [flushed_ps_sets] => 0
    [ps_prepared_never_executed] => 0
    [ps_prepared_once_executed] => 0
    [rows_fetched_from_server_normal] => 0
    [rows_fetched_from_server_ps] => 0
    [rows_buffered_from_client_normal] => 0
    [rows_buffered_from_client_ps] => 0
    [rows_fetched_from_client_normal_buffered] => 0
    [rows_fetched_from_client_normal_unbuffered] => 0
    [rows_fetched_from_client_ps_buffered] => 0
    [rows_fetched_from_client_ps_unbuffered] => 0
    [rows_fetched_from_client_ps_cursor] => 0
    [rows_skipped_normal] => 0
    [rows_skipped_ps] => 0
    [copy_on_write_saved] => 0
    [copy_on_write_performed] => 0
    [command_buffer_too_small] => 0
    [connect_success] => 1
    [connect_failure] => 0
    [connection_reused] => 0
    [reconnect] => 0
    [pconnect_success] => 0
    [active_connections] => 1
    [active_persistent_connections] => 0
    [explicit_close] => 0
    [implicit_close] => 0
    [disconnect_close] => 0
    [in_middle_of_command_close] => 0
    [explicit_free_result] => 0
    [implicit_free_result] => 0
    [explicit_stmt_close] => 0
    [implicit_stmt_close] => 0
    [mem_emalloc_count] => 0
    [mem_emalloc_ammount] => 0
    [mem_ecalloc_count] => 0
    [mem_ecalloc_ammount] => 0
    [mem_erealloc_count] => 0
    [mem_erealloc_ammount] => 0
    [mem_efree_count] => 0
    [mem_malloc_count] => 0
    [mem_malloc_ammount] => 0
    [mem_calloc_count] => 0
    [mem_calloc_ammount] => 0
    [mem_realloc_count] => 0
    [mem_realloc_ammount] => 0
    [mem_free_count] => 0
    [proto_text_fetched_null] => 0
    [proto_text_fetched_bit] => 0
    [proto_text_fetched_tinyint] => 0
    [proto_text_fetched_short] => 0
    [proto_text_fetched_int24] => 0
    [proto_text_fetched_int] => 0
    [proto_text_fetched_bigint] => 0
    [proto_text_fetched_decimal] => 0
    [proto_text_fetched_float] => 0
    [proto_text_fetched_double] => 0
    [proto_text_fetched_date] => 0
    [proto_text_fetched_year] => 0
    [proto_text_fetched_time] => 0
    [proto_text_fetched_datetime] => 0
    [proto_text_fetched_timestamp] => 0
    [proto_text_fetched_string] => 0
    [proto_text_fetched_blob] => 0
    [proto_text_fetched_enum] => 0
    [proto_text_fetched_set] => 0
    [proto_text_fetched_geometry] => 0
    [proto_text_fetched_other] => 0
    [proto_binary_fetched_null] => 0
    [proto_binary_fetched_bit] => 0
    [proto_binary_fetched_tinyint] => 0
    [proto_binary_fetched_short] => 0
    [proto_binary_fetched_int24] => 0
    [proto_binary_fetched_int] => 0
    [proto_binary_fetched_bigint] => 0
    [proto_binary_fetched_decimal] => 0
    [proto_binary_fetched_float] => 0
    [proto_binary_fetched_double] => 0
    [proto_binary_fetched_date] => 0
    [proto_binary_fetched_year] => 0
    [proto_binary_fetched_time] => 0
    [proto_binary_fetched_datetime] => 0
    [proto_binary_fetched_timestamp] => 0
    [proto_binary_fetched_string] => 0
    [proto_binary_fetched_blob] => 0
    [proto_binary_fetched_enum] => 0
    [proto_binary_fetched_set] => 0
    [proto_binary_fetched_geometry] => 0
    [proto_binary_fetched_other] => 0
)

参考

  • 統計情報についての説明


使用している接続の型を文字列で返す

  • ≪ mysqli::get_connection_stats
  • mysqli::$protocol_version ≫
  • PHP Manual
  • mysqli
  • 使用している接続の型を文字列で返す

mysqli::$host_info

mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — 使用している接続の型を文字列で返す

説明

オブジェクト指向型

string $mysqli->host_info;

手続き型

mysqli_get_host_info(mysqli $mysql): string

mysql が使用している接続の情報を文字列で返します（サーバーのホスト名を 含みます）。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

サーバーのホスト名と接続の型を文字列で返します。

例

例1 $mysqli->host_info の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* ホスト情報を表示します */
printf("Host info: %s\n", $mysqli->host_info);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* ホスト情報を表示します */
printf("Host info: %s\n", mysqli_get_host_info($link));

上の例の出力は以下となります。

Host info: Localhost via UNIX socket

参考

  • mysqli_get_proto_info() - 使用している MySQL プロトコルのバージョンを返す


使用している MySQL プロトコルのバージョンを返す

  • ≪ mysqli::$host_info
  • mysqli::$server_info ≫
  • PHP Manual
  • mysqli
  • 使用している MySQL プロトコルのバージョンを返す

mysqli::$protocol_version

mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — 使用している MySQL プロトコルのバージョンを返す

説明

オブジェクト指向型

int $mysqli->protocol_version;

手続き型

mysqli_get_proto_info(mysqli $mysql): int

mysql で表される接続で使用している MySQL プロトコルのバージョンを整数値で返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

プロトコルバージョンを整数値で返します。

例

例1 $mysqli->protocol_version の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password");

/* プロトコルのバージョンを表示します */
printf("Protocol version: %d\n", $mysqli->protocol_version);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password");

/* プロトコルのバージョンを表示します */
printf("Protocol version: %d\n", mysqli_get_proto_info($link));

上の例の出力は以下となります。

Protocol version: 10

参考

  • mysqli_get_host_info() - 使用している接続の型を文字列で返す


MySQL サーバーのバージョンを返す

  • ≪ mysqli::$protocol_version
  • mysqli::$server_version ≫
  • PHP Manual
  • mysqli
  • MySQL サーバーのバージョンを返す

mysqli::$server_info

mysqli::get_server_info

mysqli_get_server_info

(PHP 5, PHP 7, PHP 8)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — MySQL サーバーのバージョンを返す

説明

オブジェクト指向型

string $mysqli->server_info;
public mysqli::get_server_info(): string

手続き型

mysqli_get_server_info(mysqli $mysql): string

MySQLi 拡張モジュールが接続している MySQL サーバーのバージョンを文字列で返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

サーバーのバージョンを文字列で返します。

例

例1 $mysqli->server_info の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password");

/* サーバーのバージョンを表示します */
printf("Server version: %s\n", $mysqli->server_info);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password");

/* サーバーのバージョンを表示します */
printf("Server version: %s\n", mysqli_get_server_info($link));

上の例の出力は、 たとえば以下のようになります。

Server version: 8.0.21

参考

  • mysqli_get_client_info() - MySQL クライアント情報を取得する
  • mysqli_get_client_version() - MySQL クライアントのバージョンを整数値で返す
  • mysqli_get_server_version() - MySQL サーバーのバージョンを整数値で返す


MySQL サーバーのバージョンを整数値で返す

  • ≪ mysqli::$server_info
  • mysqli::get_warnings ≫
  • PHP Manual
  • mysqli
  • MySQL サーバーのバージョンを整数値で返す

mysqli::$server_version

mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — MySQL サーバーのバージョンを整数値で返す

説明

オブジェクト指向型

int $mysqli->server_version;

手続き型

mysqli_get_server_version(mysqli $mysql): int

mysqli_get_server_version() 関数は 接続している（mysql で表される）サーバーの バージョンを整数値で返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

サーバーのバージョンを整数値で返します。

バージョン番号の書式は以下のようになります。 main_version * 10000 + minor_version * 100 + sub_version (つまり、バージョン 4.1.0 は 40100 となります)

例

例1 $mysqli->server_version の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password");

/* print server version */
printf("Server version: %d\n", $mysqli->server_version);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password");

/* print server version */
printf("Server version: %d\n", mysqli_get_server_version($link));

上の例の出力は、 たとえば以下のようになります。

Server version: 80021

参考

  • mysqli_get_client_info() - MySQL クライアント情報を取得する
  • mysqli_get_client_version() - MySQL クライアントのバージョンを整数値で返す
  • mysqli_get_server_info() - MySQL サーバーのバージョンを返す


SHOW WARNINGS の結果を取得する

  • ≪ mysqli::$server_version
  • mysqli::$info ≫
  • PHP Manual
  • mysqli
  • SHOW WARNINGS の結果を取得する

mysqli::get_warnings

mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — SHOW WARNINGS の結果を取得する

説明

オブジェクト指向型

public mysqli::get_warnings(): mysqli_warning|false

手続き型

mysqli_get_warnings(mysqli $mysql): mysqli_warning|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


直近に実行されたクエリの情報を取得する

  • ≪ mysqli::get_warnings
  • mysqli::init ≫
  • PHP Manual
  • mysqli
  • 直近に実行されたクエリの情報を取得する

mysqli::$info

mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — 直近に実行されたクエリの情報を取得する

説明

オブジェクト指向型

?string $mysqli->info;

手続き型

mysqli_info(mysqli $mysql): ?string

mysqli_info() 関数は、直近に実行されたクエリに ついての情報を文字列で返します。文字列の詳細は以下のとおりです。

mysqli_info のとりうる戻り値
クエリの型 | 結果文字列の例
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0

注意:

これらのどれにも当てはまらない形式のクエリはサポートされません。 そのような場合、mysqli_info() は空文字列を返します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

直近に実行されたクエリについての追加情報を文字列で返します。

例

例1 $mysqli->info の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");

/* INSERT INTO ... SELECT */
$mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
printf("%s\n", $mysqli->info);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");

/* INSERT INTO ... SELECT */
mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
printf("%s\n", mysqli_info($link));

上の例の出力は以下となります。

Records: 150  Duplicates: 0  Warnings: 0

参考

  • mysqli_affected_rows() - 直前の MySQL の操作で変更された行の数を得る
  • mysqli_warning_count() - 指定した接続の直近のクエリから発生した警告の数を返す
  • mysqli_num_rows() - 結果セットの行数を取得する


MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

  • ≪ mysqli::$info
  • mysqli::$insert_id ≫
  • PHP Manual
  • mysqli
  • MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

mysqli::init

mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

説明

オブジェクト指向型

public mysqli::init(): ?bool

手続き型

mysqli_init(): mysqli|false

mysqli_options() と mysqli_real_connect() で使う MYSQLオブジェクトを割り当てるか、初期化します。

注意:

この関数が呼び出された後の、あらゆる mysqli の関数呼び出し (mysqli_options() と mysqli_ssl_set() を除く) は、mysqli_real_connect() 関数が呼び出されるまで失敗します。

パラメータ

この関数にはパラメータはありません。

戻り値

mysqli::init() は、成功時に null を返します。 失敗した場合に false を返します. mysqli_init() は、成功時にオブジェクトを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.1.0 | オブジェクト指向版の mysqli::init() メソッドは、 推奨されなくなりました。 parent::init() を、 parent::__construct() の呼び出しに置き換えて下さい。

例

mysqli_real_connect() を参照ください。

参考

  • mysqli_options() - オプションを設定する
  • mysqli_close() - 事前にオープンしているデータベース接続を閉じる
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする
  • mysqli_connect() - mysqli::__construct のエイリアス


直近のクエリの AUTO_INCREMENT カラムで生成した値を返す

  • ≪ mysqli::init
  • mysqli::kill ≫
  • PHP Manual
  • mysqli
  • 直近のクエリの AUTO_INCREMENT カラムで生成した値を返す

mysqli::$insert_id

mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — 直近のクエリの AUTO_INCREMENT カラムで生成した値を返す

説明

オブジェクト指向型

int|string $mysqli->insert_id;

手続き型

mysqli_insert_id(mysqli $mysql): int|string

AUTO_INCREMENT 属性を持つカラムがあるテーブル上での INSERT や UPDATE クエリが生成したIDを返します。 INSERT 文が複数の行を変更する場合、 最初に自動生成された値を返します。

MySQL 関数 LAST_INSERT_ID() を使って INSERT や UPDATE を実行すると、 mysqli_insert_id() が返す値も変更されます。 AUTO_INCREMENT の値を生成するために LAST_INSERT_ID(expr) を使った場合、 生成された AUTO_INCREMENT の値ではなく、 最後の expr の値を返します。

直前のクエリが AUTO_INCREMENT の値を変更しなかった場合は、 0 を返します。 クエリが値を生成した直後に、 mysqli_insert_id() をコールする必要があります。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

直前のクエリで更新された AUTO_INCREMENT フィールドの値を返します。接続での直前のクエリがない場合や クエリが AUTO_INCREMENT の値を更新しなかった場合は ゼロを返します。

現在の接続を使って発行されたクエリだけが、戻り値に影響します。 他の接続やクライアントが発行したクエリからは影響を受けません。

注意:

もし数値が int の最大値をこえた場合、 文字列で結果を返します。

例

例1 $mysqli->insert_id の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$mysqli->query("CREATE TABLE myCity LIKE City");

$query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
$mysqli->query($query);

printf("New record has ID %d.\n", $mysqli->insert_id);

/* drop table */
$mysqli->query("DROP TABLE myCity");

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

mysqli_query($link, "CREATE TABLE myCity LIKE City");

$query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
mysqli_query($link, $query);

printf("New record has ID %d.\n", mysqli_insert_id($link));

/* drop table */
mysqli_query($link, "DROP TABLE myCity");

上の例の出力は以下となります。

New record has ID 1.


サーバーに MySQL スレッドの停止を問い合わせる

  • ≪ mysqli::$insert_id
  • mysqli::more_results ≫
  • PHP Manual
  • mysqli
  • サーバーに MySQL スレッドの停止を問い合わせる

mysqli::kill

mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — サーバーに MySQL スレッドの停止を問い合わせる

説明

オブジェクト指向型

public mysqli::kill(int $process_id): bool

手続き型

mysqli_kill(mysqli $mysql, int $process_id): bool

この関数は、process_id で指定した MySQL スレッドの停止をサーバーに問い合わせます。この値は、 mysqli_thread_id() 関数で取得したものである 必要があります。

実行中のクエリを停止するには、SQL コマンド KILL QUERY processid を使用する必要があります。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::kill() の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* スレッド ID を取得します */
$thread_id = $mysqli->thread_id;

/* 接続を終了します */
$mysqli->kill($thread_id);

/* これはエラーとなります */
if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", $mysqli->error);
exit;
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* スレッド ID を取得します */
$thread_id = mysqli_thread_id($link);

/* 接続を終了します */
mysqli_kill($link, $thread_id);

/* これはエラーとなります */
if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", mysqli_error($link));
exit;
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error: MySQL server has gone away

参考

  • mysqli_thread_id() - 現在の接続のスレッド ID を返す


マルチクエリからの結果がまだ残っているかどうかを調べる

  • ≪ mysqli::kill
  • mysqli::multi_query ≫
  • PHP Manual
  • mysqli
  • マルチクエリからの結果がまだ残っているかどうかを調べる

mysqli::more_results

mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — マルチクエリからの結果がまだ残っているかどうかを調べる

説明

オブジェクト指向型

public mysqli::more_results(): bool

手続き型

mysqli_more_results(mysqli $mysql): bool

直前の mysqli_multi_query() のコール結果に ひとつ以上の結果セットが残っているかどうかを調べます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

直近の mysqli_multi_query() の呼び出しで (エラーを含めて) 1 件以上の結果セットが存在する場合に true、それ以外の場合に false を返します。

例

mysqli_multi_query() を参照ください。

参考

  • mysqli_multi_query() - データベース上でひとつ以上のクエリを実行する
  • mysqli_next_result() - multi_query の、次の結果を準備する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する


データベース上でひとつ以上のクエリを実行する

  • ≪ mysqli::more_results
  • mysqli::next_result ≫
  • PHP Manual
  • mysqli
  • データベース上でひとつ以上のクエリを実行する

mysqli::multi_query

mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — データベース上でひとつ以上のクエリを実行する

説明

オブジェクト指向型

public mysqli::multi_query(string $query): bool

手続き型

mysqli_multi_query(mysqli $mysql, string $query): bool

セミコロンで連結されたひとつまたは複数のクエリを実行します。

警告

セキュリティ上の注意: SQLインジェクション

クエリに入力値を含める場合は、プリペアドステートメント を使うべきです。使わない場合、データを適切にフォーマットし、全ての文字列は mysqli_real_escape_string() を使ってエスケープしなければいけません。

ひとつの呼び出し中に、クエリはデータベースに非同期に送信されますが、 データベースはそれらを順番に実行します。 mysqli_multi_query() は PHP に制御を戻す前に、最初のクエリの実行が完了するのを待ちます。 MySQLサーバーはその後、次のクエリを順番に実行していきます。 次の結果セットの準備が出来ると、 MySQL は PHP 側が mysqli_next_result() を実行するのを待ちます。

複数のクエリを処理するために、 do-while ループ を使うことを推奨します。 全てのクエリの実行が完了し、結果を PHP が取得するまで、 接続はビジー状態になります。 次のクエリを順番に実行するには、 mysqli_next_result() を使います。 次の結果セットの準備ができていない場合、 mysqli は MySQLサーバーからの応答を待ちます。 更に結果セットがあるかどうかを調べるには mysqli_more_results() を使います。

SELECT, SHOW, DESCRIBE や EXPLAIN のように 結果セットを生成するクエリについては、 結果セットを取得するために mysqli_use_result() や mysqli_store_result() が使えます。 結果セットを生成しないクエリについては、 影響した行数のような情報を取得するために、 同じ関数が使えます。

ヒント

ストアドプロシージャを実行するために CALL を実行すると、 複数の結果セットが生じる場合があります。 ストアドプロシージャに SELECT が含まれている場合、 結果セットは実行されるプロシージャが生成する順番で返されます。 一般的には、呼び出し側はどの程度の量、 結果セットが返されるかはわからないので、 複数の結果を取得する準備をしておかなければいけません。 プロシージャの最終的な実行結果は、結果ステータスです。 結果ステータスには、結果セットが存在しないことも含みます。 この結果ステータスは、プロシージャが成功したか、 エラーが発生したかを示します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

query

実行されるクエリを含む文字列。 複数のクエリの場合、セミコロンで区切らなければいけません。

戻り値

最初のステートメントが失敗した場合にのみ false を返します。 その他のステートメントのエラーを取得するには、まず mysqli_next_result() をコールする必要があります。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::multi_query() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* 複数のクエリを実行します */
$mysqli->multi_query($query);
do {
/* PHP 側に結果セットを保存します */
if ($result = $mysqli->store_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
}
/* 区切り線を出力します */
if ($mysqli->more_results()) {
printf("-----------------\n");
}
} while ($mysqli->next_result());

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* 複数のクエリを実行します */
mysqli_multi_query($link, $query);
do {
/* PHP 側に結果セットを保存します */
if ($result = mysqli_store_result($link)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s\n", $row[0]);
}
}
/* 区切り線を出力します */
if (mysqli_more_results($link)) {
printf("-----------------\n");
}
} while (mysqli_next_result($link));

上の例の出力は、 たとえば以下のようになります。

my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer

参考

  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_use_result() - 結果セットの取得を開始する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_next_result() - multi_query の、次の結果を準備する
  • mysqli_more_results() - マルチクエリからの結果がまだ残っているかどうかを調べる


multi_query の、次の結果を準備する

  • ≪ mysqli::multi_query
  • mysqli::options ≫
  • PHP Manual
  • mysqli
  • multi_query の、次の結果を準備する

mysqli::next_result

mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — multi_query の、次の結果を準備する

説明

オブジェクト指向型

public mysqli::next_result(): bool

手続き型

mysqli_next_result(mysqli $mysql): bool

直近の
mysqli_multi_query() コールから次の結果セットを用意します。
これは mysqli_store_result() あるいは
mysqli_use_result() で取得することが可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。 mysqli_more_results() とは異なり、次のクエリがエラーになった場合は、同様に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

mysqli_multi_query() を参照ください。

参考

  • mysqli_multi_query() - データベース上でひとつ以上のクエリを実行する
  • mysqli_more_results() - マルチクエリからの結果がまだ残っているかどうかを調べる
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する


オプションを設定する

  • ≪ mysqli::next_result
  • mysqli::ping ≫
  • PHP Manual
  • mysqli
  • オプションを設定する

mysqli::options

mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — オプションを設定する

説明

オブジェクト指向型

public mysqli::options(int $option, string|int $value): bool

手続き型

mysqli_options(mysqli $mysql, int $option, string|int $value): bool

接続に関する追加オプションを設定し、 接続の振る舞いに影響を与えるために使用します。

この関数は、いくつかのオプションを設定して複数回コールされることがあります。

mysqli_options() は、
mysqli_init() がコールされた後、
mysqli_real_connect() の前にコールしなければなりません。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

option

指定するオプション。以下の値のいずれかです。

使用可能なオプション
名前 | 説明
MYSQLI_OPT_CONNECT_TIMEOUT | 接続のタイムアウト秒数
MYSQLI_OPT_READ_TIMEOUT | コマンドの実行結果が返ってくるまでのタイムアウト秒数。PHP 7.2.0 以降で利用可能です。
MYSQLI_OPT_LOCAL_INFILE | LOAD LOCAL INFILE の使用可/不可。
MYSQLI_INIT_COMMAND | MySQL サーバーへの接続後に実行するコマンド。
MYSQLI_SET_CHARSET_NAME | 文字コードのデフォルト値
MYSQLI_READ_DEFAULT_FILE | my.cnf の代わりに、指定した名前のファイルから 設定を読み込みます。 mysqlnd ではサポートされていません。
MYSQLI_READ_DEFAULT_GROUP | my.cnf の指定した名前のグループ、あるいは MYSQL_READ_DEFAULT_FILE で指定したファイルから 設定を読み込みます。 mysqlnd ではサポートされていません。
MYSQLI_SERVER_PUBLIC_KEY | RSA 公開鍵ファイル。SHA-256 ベースの認証で使います。 PHP 5.5.0 以降で利用可能です。
MYSQLI_OPT_NET_CMD_BUFFER_SIZE | 内部のコマンド／ネットワークバッファのサイズ。 mysqlnd でのみ有効です。
MYSQLI_OPT_NET_READ_BUFFER_SIZE | MySQL コマンドパケットのボディを読み込むときの、読み込みチャンクの最大バイト数。 mysqlnd でのみ有効です。
MYSQLI_OPT_INT_AND_FLOAT_NATIVE | プリペアドステートメントを使わない場合に、 integer 型と float 型のカラムを PHP の数値に変換します。 mysqlnd でのみ有効です。
MYSQLI_OPT_SSL_VERIFY_SERVER_CERT | サーバーの証明書を検証するかしないかを指定します。

value

オプションに設定する値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

mysqli_real_connect() を参照ください。

注意

注意:

MySQLnd は常に、サーバーのデフォルト文字セットを想定しています。この文字セットは接続時の ハンドシェイク/認証 のときに送信され、これを mysqlnd が使います。

Libmysqlclient が使うデフォルトの文字セットは my.cnf で設定したものです。あるいは明示的に mysqli_options() をコールして設定することもできます。 これは、mysqli_init() のあとで mysqli_real_connect() を実行する前にコールします。

参考

  • mysqli_init() - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする


サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

  • ≪ mysqli::options
  • mysqli::poll ≫
  • PHP Manual
  • mysqli
  • サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

mysqli::ping

mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

説明

オブジェクト指向型

public mysqli::ping(): bool

手続き型

mysqli_ping(mysqli $mysql): bool

サーバーとの接続が動作中かどうかを確かめます。もし切断されており、 グローバルオプション mysqli.reconnect が有効な場合は再接続を試みます。

注意: mysqlnd ドライバは、php.ini 設定項目 mysqli.reconnect を無視します。 自動再接続は行われません。

この関数は、長期間アイドル状態にあるクライアントが、 サーバーの状態を確認して必要なら再接続するために使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::ping() の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if ($mysqli->connect_errno) {
printf("Connect failed: %s\n", $mysqli->connect_error);
exit();
}

/* サーバーが稼動中かどうかを確認します */
if ($mysqli->ping()) {
printf ("Our connection is ok!\n");
} else {
printf ("Error: %s\n", $mysqli->error);
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* サーバーが稼動中かどうかを確認します */
if (mysqli_ping($link)) {
printf ("Our connection is ok!\n");
} else {
printf ("Error: %s\n", mysqli_error($link));
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Our connection is ok!


接続を問い合わせる

  • ≪ mysqli::ping
  • mysqli::prepare ≫
  • PHP Manual
  • mysqli
  • 接続を問い合わせる

mysqli::poll

mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — 接続を問い合わせる

説明

オブジェクト指向型

public static mysqli::poll(
?array &$read,
?array &$error,
array &$reject,
int $seconds,
int $microseconds = 0
): int|false

手続き型

mysqli_poll(
?array &$read,
?array &$error,
array &$reject,
int $seconds,
int $microseconds = 0
): int|false

接続を問い合わせます。 このメソッドは static メソッドとして使えます。

注意:

mysqlnd でのみ使用可能です。

パラメータ

read

読み込める結果が残っている接続のリスト。

error

クエリが失敗した、あるいは接続が切断されたなどのエラーが発生した接続のリスト。

reject

関数から結果を取得できるような非同期クエリが実行されていないという理由で、 拒否された接続のリスト。

seconds

待ち続ける秒数の最大。非負の数でなければなりません。

microseconds

待ち続けるマイクロ秒数の最大。非負の数でなければなりません。

戻り値

成功した場合に使用できる接続の数、それ以外の場合に false を返します。

エラー / 例外

read と error を両方渡さなかった場合には、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | read と error を両方渡さなかった場合には、 ValueError がスローされるようになりました。

例

例1 mysqli_poll() の例

<?php
$link1 = mysqli_connect();
$link1->query("SELECT 'test'", MYSQLI_ASYNC);
$all_links = array($link1);
$processed = 0;
do {
$links = $errors = $reject = array();
foreach ($all_links as $link) {
$links[] = $errors[] = $reject[] = $link;
}
if (!mysqli_poll($links, $errors, $reject, 1)) {
continue;
}
foreach ($links as $link) {
if ($result = $link->reap_async_query()) {
print_r($result->fetch_row());
if (is_object($result))
mysqli_free_result($result);
} else die(sprintf("MySQLi Error: %s", mysqli_error($link)));
$processed++;
}
} while ($processed < count($all_links));
?>

上の例の出力は以下となります。

Array
(
    [0] => test
)

参考

  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_reap_async_query() - 非同期クエリから結果を取得する


実行するための SQL文 を準備する

  • ≪ mysqli::poll
  • mysqli::query ≫
  • PHP Manual
  • mysqli
  • 実行するための SQL文 を準備する

mysqli::prepare

mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — 実行するための SQL文 を準備する

説明

オブジェクト指向型

public mysqli::prepare(string $query): mysqli_stmt|false

手続き型

mysqli_prepare(mysqli $mysql, string $query): mysqli_stmt|false

SQL文を準備し、後でそれを操作するために使用する ステートメントハンドルを返します。 クエリは、単一の SQL文である必要があります。

SQL文のテンプレートには、ゼロ個以上のパラメータマーカ (?) を含めることができます。 パラメータマーカは、プレースホルダとも呼ばれています。 パラメータマーカは、SQL文を実行する前に mysqli_stmt_bind_param() を使用して アプリケーション変数にバインドする必要があります。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

query

クエリを表す文字列。 単一のSQL文である必要があります。

SQL文には、ゼロ個以上のパラメータマーカを含めることができますます。 パラメータマーカはクエスチョンマーク(?) を適切な位置に置くことで埋め込みます。

注意:

パラメータのマーカは、それが SQL 文の適切な位置にある場合のみ有効です。 例えば INSERT 文の VALUES() リストの中 (行に登録するカラムの値を指定する) や WHERE 句でカラムのデータと比較する値などが 適切な位置の例です。 しかし、識別子 (テーブルやカラムの名前) には使用できません。

戻り値

mysqli_prepare() はステートメントオブジェクトを返します。 エラー時には false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::prepare() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$city = "Amersfoort";

/* プリペアドステートメントを作成します。*/
$stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");

/* マーカにパラメータをバインドします */
$stmt->bind_param("s", $city);

/* クエリを実行します */
$stmt->execute();

/* 結果変数をバインドします */
$stmt->bind_result($district);

/* 値を取得します */
$stmt->fetch();

printf("%s is in district %s\n", $city, $district);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$city = "Amersfoort";

/* プリペアドステートメントを作成します */
$stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");

/* マーカにパラメータをバインドします */
mysqli_stmt_bind_param($stmt, "s", $city);

/* クエリを実行します */
mysqli_stmt_execute($stmt);

/* 結果変数をバインドします */
mysqli_stmt_bind_result($stmt, $district);

/* 値を取得します */
mysqli_stmt_fetch($stmt);

printf("%s is in district %s\n", $city, $district);

上の例の出力は以下となります。

Amersfoort is in district Utrecht

参考

  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_bind_result() - 結果を保存するため、プリペアドステートメントに変数をバインドする
  • mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
  • mysqli_stmt_close() - プリペアドステートメントを閉じる


データベース上でクエリを実行する

  • ≪ mysqli::prepare
  • mysqli::real_connect ≫
  • PHP Manual
  • mysqli
  • データベース上でクエリを実行する

mysqli::query

mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — データベース上でクエリを実行する

説明

オブジェクト指向型

public mysqli::query(string $query, int $result_mode = MYSQLI_STORE_RESULT): mysqli_result|bool

手続き型

mysqli_query(mysqli $mysql, string $query, int $result_mode = MYSQLI_STORE_RESULT): mysqli_result|bool

データベースに対してクエリ query を実行します。

警告

セキュリティ上の注意: SQLインジェクション

クエリに入力値を含める場合は、プリペアドステートメント を使うべきです。使わない場合、データを適切にフォーマットし、全ての文字列は mysqli_real_escape_string() を使ってエスケープしなければいけません。

DML (INSERT、UPDATE あるいは DELETE)
以外のクエリについては、
この関数は mysqli_real_query()
に続けて mysqli_use_result() あるいは
mysqli_store_result() をコールすることと同等です。

注意:

サーバーの max_allowed_packet よりも長いステートメントを mysqli_query() に渡した場合、 返ってくるエラーコードは MySQL Native Driver (mysqlnd) を使っているか MySQL Client Library (libmysqlclient) を使っているかで異なります。 それぞれ、次のように振る舞います。

  • Linux 上の mysqlnd では、エラーコード 1153 を返します。 エラーメッセージは got a packet bigger than max_allowed_packet bytes です。

  • Windows 上の mysqlnd では、エラーコード 2006 を返します。 エラーメッセージは server has gone away です。

  • すべてのプラットフォームの libmysqlclient では、エラーコード 2006 を返します。エラーメッセージは server has gone away です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

query

クエリ文字列。

result_mode

MySQLサーバーからどのように結果が返されたかを示す結果モード。 以下の3つの定数のうちのいずれかです。

MYSQLI_STORE_RESULT (デフォルト) - バッファリングされた結果セットを mysqli_result オブジェクトとして返します。

MYSQLI_USE_RESULT - バッファリングせずに結果セットを mysqli_result オブジェクトとして返します。 取得されるのを待っているレコードが存在する限り、 接続はビジーとなり、Commands out of sync エラーを返します。 このエラーを回避するには、全てのレコードをサーバーから取得するか、 結果セットを mysqli_free_result() 関数をコールすることで捨てなければいけません。

MYSQLI_ASYNC (mysqlnd で利用できます) - クエリを非同期実行します。よって結果セットはすぐには返されません。 このようなクエリから結果を取得するには、 mysqli_poll() を使います。 MYSQLI_STORE_RESULT や MYSQLI_USE_RESULT と組み合わせて使います。

戻り値

失敗した場合に false を返します。 結果セットを生成するクエリ、 つまり SELECT, SHOW, DESCRIBE あるいは EXPLAIN が成功した場合は、mysqli_query() は mysqli_result オブジェクトを返します。それ以外のクエリが成功した場合は、 mysqli_query() は true を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::query() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 結果セットを返さないテーブルを作成します。*/
$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
printf("Table myCity successfully created.\n");

/* 結果セットを返す SELECT 文 */
$result = $mysqli->query("SELECT Name FROM City LIMIT 10");
printf("Select returned %d rows.\n", $result->num_rows);

/* 大量のデータを取得しなければならない場合、MYSQLI_USE_RESULT を使います */
$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

/* 注意: 全てのレコードが取得されるか、結果セットがクローズされるまで
サーバーとやりとりを行うあらゆる関数は実行できません。あらゆる呼び出しは
'out of sync' を返します */
$mysqli->query("SET @a:='this will not work'");

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 結果セットを返さないテーブルを作成します。*/
mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
printf("Table myCity successfully created.\n");

/* 結果セットを返す SELECT 文 */
$result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
printf("Select returned %d rows.\n", mysqli_num_rows($result));

/* 大量のデータを取得しなければならない場合、MYSQLI_USE_RESULT を使います */
$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

/* 注意: 全てのレコードが取得されるか、結果セットがクローズされるまで
サーバーとやりとりを行うあらゆる関数は実行できません。あらゆる呼び出しは
'out of sync' を返します */
mysqli_query($link, "SET @a:='this will not work'");

上の例の出力は、 たとえば以下のようになります。

Table myCity successfully created.
Select returned 10 rows.

Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

参考

  • mysqli_execute_query() - SQL文を準備し、変数をバインドし、実行する
  • mysqli_real_query() - SQL クエリを実行する
  • mysqli_multi_query() - データベース上でひとつ以上のクエリを実行する
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_free_result() - 結果に関連付けられたメモリを開放する


mysql サーバーとの接続をオープンする

  • ≪ mysqli::query
  • mysqli::real_escape_string ≫
  • PHP Manual
  • mysqli
  • mysql サーバーとの接続をオープンする

mysqli::real_connect

mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — mysql サーバーとの接続をオープンする

説明

オブジェクト指向型

public mysqli::real_connect(
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null,
int $flags = 0
): bool

手続き型

mysqli_real_connect(
mysqli $mysql,
?string $hostname = null,
?string $username = null,
#[\SensitiveParameter] ?string $password = null,
?string $database = null,
?int $port = null,
?string $socket = null,
int $flags = 0
): bool

MySQL データベースエンジンとの接続を確立します。

この関数は、以下の点で mysqli_connect() とは異なります。

  • mysqli_real_connect() は、 mysqli_init() が作成した接続オブジェクトが必要です。

  • mysqli_options() 関数を使用して、 さまざまな接続オプションを設定することが可能です。

  • flags パラメータが使用できます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

hostname

ホスト名あるいは IP アドレス。 null を渡した場合、 mysqli.default_host から値を取得します。 可能な場合は、TCP/IP プロトコルの代わりにパイプが使用されます。 ホスト名とポートが一緒に指定された場合は、TCP/IP プロトコルが使われます。 例: localhost:3308.

username

MySQL ユーザー名。 null の場合は、mysqli.default_user iniオプションに基づいてユーザー名が決定されます。

password

MySQL のパスワード。 null の場合は、mysqli.default_pw iniオプションに基づいてパスワードが決定されます。

database

null 以外を指定した場合は、 クエリが実行されるデフォルトのデータベースとなります。

port

MySQL サーバーに接続する際のポート番号を指定します。 null の場合は、mysqli.default_port iniオプションに基づいてポート番号が決定されます。

socket

使用するソケットあるいは名前つきパイプを指定します。 null の場合は、mysqli.default_socket iniオプションに基づいてソケットが決定されます。

注意:

socket 引数を指定しても、MySQL サーバーへの 接続時の型を明示的に定義することにはなりません。MySQL サーバーへの 接続方法については hostname 引数で定義されます。

flags

パラメータ flags で、接続時のさまざまなオプションを設定します。

サポートするフラグ
名前 | 説明
MYSQLI_CLIENT_COMPRESS | 圧縮プロトコルを使用します。
MYSQLI_CLIENT_FOUND_ROWS | 変更された行数ではなく、マッチした行数を返します。
MYSQLI_CLIENT_IGNORE_SPACE | 関数名に続く空白文字を許可します。すべての関数名を予約語とします。
MYSQLI_CLIENT_INTERACTIVE | 接続を閉じるまでのタイムアウト時間として、 (wait_timeout のかわりに) interactive_timeout の使用を許可します。
MYSQLI_CLIENT_SSL | SSL (暗号化) を使用します。
MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT | MYSQLI_CLIENT_SSL と似ていますが、 SSL 証明書の検証は行いません。 これは、MySQL Native Driver と MySQL 5.6 以降の組み合わせでのみ使えます。

注意:

セキュリティの観点から、PHP では MULTI_STATEMENT フラグはサポートされていません。複数のクエリを実行したい場合は、 mysqli_multi_query() 関数を使用してください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
7.4.0 | すべてのパラメータが、nullable になりました。

例

例1 mysqli::real_connect() の例

オブジェクト指向型

<?php

$mysqli = mysqli_init();
if (!$mysqli) {
die('mysqli_init failed');
}

if (!$mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
die('Setting MYSQLI_INIT_COMMAND failed');
}

if (!$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}

if (!$mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db')) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}

echo 'Success... ' . $mysqli->host_info . "\n";

$mysqli->close();
?>

オブジェクト指向型 で mysqli クラスを継承する例

<?php

class foo_mysqli extends mysqli {
public function __construct($host, $user, $pass, $db) {
parent::__construct();

if (!parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
die('Setting MYSQLI_INIT_COMMAND failed');
}

if (!parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}

if (!parent::real_connect($host, $user, $pass, $db)) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}
}
}

$db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

echo 'Success... ' . $db->host_info . "\n";

$db->close();
?>

手続き型

<?php

$link = mysqli_init();
if (!$link) {
die('mysqli_init failed');
}

if (!mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
die('Setting MYSQLI_INIT_COMMAND failed');
}

if (!mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed');
}

if (!mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db')) {
die('Connect Error (' . mysqli_connect_errno() . ') '
. mysqli_connect_error());
}

echo 'Success... ' . mysqli_get_host_info($link) . "\n";

mysqli_close($link);
?>

上の例の出力は以下となります。

Success... MySQL host info: localhost via TCP/IP

注意

注意:

MySQLnd は常に、サーバーのデフォルト文字セットを想定しています。この文字セットは接続時の ハンドシェイク/認証 のときに送信され、これを mysqlnd が使います。

Libmysqlclient が使うデフォルトの文字セットは my.cnf で設定したものです。あるいは明示的に mysqli_options() をコールして設定することもできます。 これは、mysqli_init() のあとで mysqli_real_connect() を実行する前にコールします。

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_init() - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
  • mysqli_options() - オプションを設定する
  • mysqli_ssl_set() - SSL を使用したセキュアな接続を確立する
  • mysqli_close() - 事前にオープンしているデータベース接続を閉じる


接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

  • ≪ mysqli::real_connect
  • mysqli::real_query ≫
  • PHP Manual
  • mysqli
  • 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

mysqli::real_escape_string

mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli_real_escape_string — 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

説明

オブジェクト指向型

public mysqli::real_escape_string(string $string): string

手続き型

mysqli_real_escape_string(mysqli $mysql, string $string): string

この関数を使用して、SQL 文中で使用できる正当な形式の SQL 文字列を作成します。 文字列 escapestr が、エスケープされた SQL に変換されます。その際、接続で使用している現在の文字セットが考慮されます。

警告

セキュリティ: デフォルトの文字セット

サーバーレベルで設定するなり API 関数 mysqli_set_charset() を使うなりして、 文字セットを明示しておく必要があります。この文字セットが mysqli_real_escape_string() に影響を及ぼします。詳細は 文字セットの概念 を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

string

エスケープする文字列。

エンコードされる文字は NUL (ASCII 0)、 \n、\r、 \、'、 "、および CTRL+Z です。

戻り値

エスケープ済みの文字列を返します。

例

例1 mysqli::real_escape_string() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$city = "'s-Hertogenbosch";

/* $city はエスケープされ、クエリは動作します。*/
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
$mysqli->real_escape_string($city));
$result = $mysqli->query($query);
printf("Select returned %d rows.\n", $result->num_rows);

/* このクエリは失敗します。なぜなら、$city をエスケープしていないからです */
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
$result = $mysqli->query($query);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

$city = "'s-Hertogenbosch";

/* $city はエスケープされ、クエリは動作します。*/
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
mysqli_real_escape_string($mysqli, $city));
$result = mysqli_query($mysqli, $query);
printf("Select returned %d rows.\n", mysqli_num_rows($result));

/* このクエリは失敗します。なぜなら、$city をエスケープしていないからです */
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
$result = mysqli_query($mysqli, $query);

上の例の出力は、 たとえば以下のようになります。

Select returned 1 rows.

Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 's-Hertogenbosch'' at line 1 in...

参考

  • mysqli_set_charset() - クライアントの文字セットを設定する


SQL クエリを実行する

  • ≪ mysqli::real_escape_string
  • mysqli::reap_async_query ≫
  • PHP Manual
  • mysqli
  • SQL クエリを実行する

mysqli::real_query

mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — SQL クエリを実行する

説明

オブジェクト指向型

public mysqli::real_query(string $query): bool

手続き型

mysqli_real_query(mysqli $mysql, string $query): bool

データベースに対して単一のクエリを実行します。 その結果を取得したり保存したりするには、関数 mysqli_store_result() あるいは mysqli_use_result() を使用します。

警告

セキュリティ上の注意: SQLインジェクション

クエリに入力値を含める場合は、プリペアドステートメント を使うべきです。使わない場合、データを適切にフォーマットし、全ての文字列は mysqli_real_escape_string() を使ってエスケープしなければいけません。

指定したクエリが結果を返すかどうかを調べるには、 mysqli_field_count() を参照ください。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

query

クエリを表す文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

参考

  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する


非同期クエリから結果を取得する

  • ≪ mysqli::real_query
  • mysqli::refresh ≫
  • PHP Manual
  • mysqli
  • 非同期クエリから結果を取得する

mysqli::reap_async_query

mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::reap_async_query -- mysqli_reap_async_query — 非同期クエリから結果を取得する

説明

オブジェクト指向型

public mysqli::reap_async_query(): mysqli_result|bool

手続き型

mysqli_reap_async_query(mysqli $mysql): mysqli_result|bool

非同期クエリから結果を取得します。

注意:

mysqlnd でのみ使用可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

失敗した場合に false を返します。 結果セットを生成するクエリ、 つまり SELECT, SHOW, DESCRIBE あるいは EXPLAIN が成功した場合は、mysqli_reap_async_query() は mysqli_result オブジェクトを返します。それ以外のクエリが成功した場合は、 mysqli_reap_async_query() は true を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

参考

  • mysqli_poll() - 接続を問い合わせる


リフレッシュする

  • ≪ mysqli::reap_async_query
  • mysqli::release_savepoint ≫
  • PHP Manual
  • mysqli
  • リフレッシュする

mysqli::refresh

mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — リフレッシュする

説明

オブジェクト指向型

public mysqli::refresh(int $flags): bool

手続き型

mysqli_refresh(mysqli $mysql, int $flags): bool

テーブルやキャッシュのフラッシュ、あるいはレプリケーションサーバー情報のリセットを行います。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

flags

リフレッシュのオプションを定数 MYSQLI_REFRESH_* で指定します。定数の意味は MySQLi 定数 のドキュメントを参照ください。

公式ドキュメントの » MySQL Refresh も参照ください。

戻り値

リフレッシュに成功した場合に true、それ以外の場合に false を返します。

参考

  • mysqli_poll() - 接続を問い合わせる


現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

  • ≪ mysqli::refresh
  • mysqli::rollback ≫
  • PHP Manual
  • mysqli
  • 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

mysqli::release_savepoint

mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

説明

オブジェクト指向型

public mysqli::release_savepoint(string $name): bool

手続き型:

mysqli_release_savepoint(mysqli $mysql, string $name): bool

この関数は、 $mysqli->query("RELEASE SAVEPOINT `$name`"); を実行することと同等です。 この関数は、コミットやロールバックを実行しません。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

name

セーブポイントの識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_savepoint() - トランザクションのセーブポイントを設定する


現在のトランザクションをロールバックする

  • ≪ mysqli::release_savepoint
  • mysqli::savepoint ≫
  • PHP Manual
  • mysqli
  • 現在のトランザクションをロールバックする

mysqli::rollback

mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — 現在のトランザクションをロールバックする

説明

オブジェクト指向型

public mysqli::rollback(int $flags = 0, ?string $name = null): bool

手続き型

mysqli_rollback(mysqli $mysql, int $flags = 0, ?string $name = null): bool

データベースの現在のトランザクションをロールバックします。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

flags

定数 MYSQLI_TRANS_COR_* のビットマスク。

name

指定した場合は、ROLLBACK/*name*/ を実行します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
8.0.0 | name は、nullable になりました。

例

mysqli::begin_transaction() の例 を参照ください。

注意

注意:

この関数は、トランザクションに 対応していないテーブル型（MyISAM あるいは ISAM など）では 動作しません。

参考

  • mysqli_begin_transaction() - トランザクションを開始する
  • mysqli_commit() - 現在のトランザクションをコミットする
  • mysqli_autocommit() - データベース更新の自動コミットをオンまたはオフにする
  • mysqli_release_savepoint() - 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する


トランザクションのセーブポイントを設定する

  • ≪ mysqli::rollback
  • mysqli::select_db ≫
  • PHP Manual
  • mysqli
  • トランザクションのセーブポイントを設定する

mysqli::savepoint

mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — トランザクションのセーブポイントを設定する

説明

オブジェクト指向型

public mysqli::savepoint(string $name): bool

手続き型:

mysqli_savepoint(mysqli $mysql, string $name): bool

この関数は、 $mysqli->query("SAVEPOINT `$name`"); を実行することと同等です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

name

セーブポイントの識別子

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_release_savepoint() - 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する


クエリを実行するためのデフォルトのデータベースを選択する

  • ≪ mysqli::savepoint
  • mysqli::set_charset ≫
  • PHP Manual
  • mysqli
  • クエリを実行するためのデフォルトのデータベースを選択する

mysqli::select_db

mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — クエリを実行するためのデフォルトのデータベースを選択する

説明

オブジェクト指向型

public mysqli::select_db(string $database): bool

手続き型

mysqli_select_db(mysqli $mysql, string $database): bool

データベース接続に対してクエリを実行する際に使用する、 デフォルトのデータベースを設定します。

注意:

この関数は、接続のデフォルトデータベースを変更する際にのみ使用します。 デフォルトデータベースは、mysqli_connect() の 4 番目の引数でも指定可能です。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

database

データベース名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::select_db() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

/* 現在のデフォルトデータベース名を取得します */
$result = $mysqli->query("SELECT DATABASE()");
$row = $result->fetch_row();
printf("Default database is %s.\n", $row[0]);

/* データベースを world に変更します */
$mysqli->select_db("world");

/* 現在のデフォルトデータベース名を取得します */
$result = $mysqli->query("SELECT DATABASE()");
$row = $result->fetch_row();
printf("Default database is %s.\n", $row[0]);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

/* 現在のデフォルトデータベース名を取得します */
$result = mysqli_query($link, "SELECT DATABASE()");
$row = mysqli_fetch_row($result);
printf("Default database is %s.\n", $row[0]);

/* データベースを world に変更します */
mysqli_select_db($link, "world");

/* 現在のデフォルトデータベース名を取得します */
$result = mysqli_query($link, "SELECT DATABASE()");
$row = mysqli_fetch_row($result);
printf("Default database is %s.\n", $row[0]);

上の例の出力は以下となります。

Default database is test.
Default database is world.

参考

  • mysqli_connect() - mysqli::__construct のエイリアス
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする


クライアントの文字セットを設定する

  • ≪ mysqli::select_db
  • mysqli::$sqlstate ≫
  • PHP Manual
  • mysqli
  • クライアントの文字セットを設定する

mysqli::set_charset

mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — クライアントの文字セットを設定する

説明

オブジェクト指向型

public mysqli::set_charset(string $charset): bool

手続き型

mysqli_set_charset(mysqli $mysql, string $charset): bool

データベースサーバーとのデータの送受信に使用する、 文字セットを設定します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

charset

設定する文字セット。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::set_charset() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

printf("Initial character set: %s\n", $mysqli->character_set_name());

/* 文字セットを utf8mb4 に変更します */
$mysqli->set_charset("utf8mb4");

printf("Current character set: %s\n", $mysqli->character_set_name());

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

printf("Initial character set: %s\n", mysqli_character_set_name($link));

/* 文字セットを utf8mb4 に変更します */
mysqli_set_charset($link, "utf8mb4");

printf("Current character set: %s\n", mysqli_character_set_name($link));

上の例の出力は、 たとえば以下のようになります。

Initial character set: latin1
Current character set: utf8mb4

注意

注意:

Windows プラットフォームでこの関数を使用するには、MySQL クライアント ライブラリのバージョン 4.1.11 以降（MySQL 5.0 の場合は 5.0.6 以降） が必要です。

注意:

文字セットを変更するにはこの方法を使うことを推奨します。 mysqli_query() で (SET NAMES utf8 などとして) 設定する方法はお勧めできません。詳細は MySQL の文字セットの概念 を参照ください。

参考

  • mysqli_character_set_name() - データベース接続の現在の文字コードセットを返す
  • mysqli_real_escape_string() - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
  • MySQL 文字セットのコンセプト
  • » MySQL がサポートする文字セットの一覧


直前の MySQL の操作での SQLSTATE エラーを返す

  • ≪ mysqli::set_charset
  • mysqli::ssl_set ≫
  • PHP Manual
  • mysqli
  • 直前の MySQL の操作での SQLSTATE エラーを返す

mysqli::$sqlstate

mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — 直前の MySQL の操作での SQLSTATE エラーを返す

説明

オブジェクト指向型

string $mysqli->sqlstate;

手続き型

mysqli_sqlstate(mysqli $mysql): string

直近のエラーについて、SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 つの文字で構成されています。'00000' はエラーが発生しなかったことを意味します。この値は、ANSI SQL および ODBC で定義されています。とりうる値の一覧は » http://dev.mysql.com/doc/mysql/en/error-handling.html を参照ください。

注意:

すべての MySQL エラーが SQLSTATE に対応しているわけではないことに 注意してください。そのようなエラーが発生した場合は、 HY000（一般的なエラー）が返されます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

直前のエラーに関する SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 文字で構成され、'00000' はエラーが発生しなかったことを意味します。

例

例1 $mysqli->sqlstate の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* City テーブルはすでに存在します。そのためエラーとなります */
try {
$mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
} catch (mysqli_sql_exception) {
printf("Error - SQLSTATE %s.\n", $mysqli->sqlstate);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* City テーブルはすでに存在します。そのためエラーとなります */
try {
mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
} catch (mysqli_sql_exception) {
printf("Error - SQLSTATE %s.\n", mysqli_sqlstate($link));
}

上の例の出力は以下となります。

Error - SQLSTATE 42S01.

参考

  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す


SSL を使用したセキュアな接続を確立する

  • ≪ mysqli::$sqlstate
  • mysqli::stat ≫
  • PHP Manual
  • mysqli
  • SSL を使用したセキュアな接続を確立する

mysqli::ssl_set

mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — SSL を使用したセキュアな接続を確立する

説明

オブジェクト指向型

public mysqli::ssl_set(
?string $key,
?string $certificate,
?string $ca_certificate,
?string $ca_path,
?string $cipher_algos
): true

手続き型

mysqli_ssl_set(
mysqli $mysql,
?string $key,
?string $certificate,
?string $ca_certificate,
?string $ca_path,
?string $cipher_algos
): true

SSL を使用してセキュアな接続を確立します。 mysqli_real_connect() より前にコールする必要があります。この関数は、 OpenSSL サポートが有効になっていない場合は何もしません。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

key

鍵ファイルへのパス。

certificate

証明書ファイルへのパス。

ca_certificate

CA ファイルへのパス。

ca_path

信頼された SSL CA 証明書が PEM フォーマットで格納されているディレクトリへのパス。

cipher_algos

SSL の暗号化に使用可能な暗号形式の一覧。

戻り値

常に true を返します。 もし SSL が正しく設定できていない場合、 mysqli_real_connect() は接続時にエラーを返します。

参考

  • mysqli_options() - オプションを設定する
  • mysqli_real_connect() - mysql サーバーとの接続をオープンする


現在のシステム状態を取得する

  • ≪ mysqli::ssl_set
  • mysqli::stmt_init ≫
  • PHP Manual
  • mysqli
  • 現在のシステム状態を取得する

mysqli::stat

mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — 現在のシステム状態を取得する

説明

オブジェクト指向型

public mysqli::stat(): string|false

手続き型

mysqli_stat(mysqli $mysql): string|false

mysqli_stat() は、'mysqladmin status' コマンドが 返すのと同じ情報を返します。この中には、起動からの秒数・起動中の スレッドの数・リロード数および開かれているテーブルなどが含まれます。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

サーバーの状態を示す文字列を返します。エラー時には false を返します。

例

例1 mysqli::stat() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

printf("System status: %s\n", $mysqli->stat());

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

printf("System status: %s\n", mysqli_stat($link));

上の例の出力は以下となります。

System status: Uptime: 272  Threads: 1  Questions: 5340  Slow queries: 0
Opens: 13  Flush tables: 1  Open tables: 0  Queries per second avg: 19.632
Memory in use: 8496K  Max memory used: 8560K

参考

  • mysqli_get_server_info() - MySQL サーバーのバージョンを返す


ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

  • ≪ mysqli::stat
  • mysqli::store_result ≫
  • PHP Manual
  • mysqli
  • ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

mysqli::stmt_init

mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

説明

オブジェクト指向型

public mysqli::stmt_init(): mysqli_stmt|false

手続き型

mysqli_stmt_init(mysqli $mysql): mysqli_stmt|false

mysqli_stmt_prepare() で使用可能な ステートメントオブジェクトを割り当て、初期化します。

注意:

mysqli_stmt_prepare() がコールされるまで、 これ以降のあらゆる mysqli_stmt 関数のコールは失敗します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

オブジェクトを返します。

参考

  • mysqli_stmt_prepare() - SQL ステートメントを実行するために準備する


直近のクエリから結果セットを転送する

  • ≪ mysqli::stmt_init
  • mysqli::$thread_id ≫
  • PHP Manual
  • mysqli
  • 直近のクエリから結果セットを転送する

mysqli::store_result

mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — 直近のクエリから結果セットを転送する

説明

オブジェクト指向型

public mysqli::store_result(int $mode = 0): mysqli_result|false

手続き型

mysqli_store_result(mysqli $mysql, int $mode = 0): mysqli_result|false

mysqli_data_seek() で使用される、 mysql で表されたデータベース接続の直近のクエリ から結果セットを転送します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

mode

指定したいオプション。 PHP 8.1 以降では、このパラメータを指定しても意味はありません。 以下のいずれかの値を指定します。

有効なオプション
名前 | 説明
MYSQLI_STORE_RESULT_COPY_DATA | 結果を、内部の mysqlnd バッファーから PHP の変数にコピーします。 デフォルトでは、mysqlnd は参照を利用しており、メモリ内の結果をコピーしたり複製したりしないようにしています。 ある種の結果セット (短めの行を大量に保持する結果セットなど) の場合は、 コピーしたほうが、全体的なメモリ使用量を抑えることができます。 結果を保持する PHP の変数のほうが、解放されるのが早いからです。 これは mysqlnd でのみ利用可能です。

戻り値

バッファに格納した結果オブジェクトを返します。エラー時には false を返します。

注意:

mysqli_store_result() は、クエリが結果セットを 返さなかった場合（例えば、クエリが INSERT 文であった場合）に false を返します。また、結果セットの読み込みに失敗した場合にも false を返します。エラーが発生したかどうかを調べるには、 mysqli_error() が空文字列以外を返す・ mysqli_errno() がゼロ以外の値を返す・あるいは mysqli_field_count() がゼロ以外の値を返す のいずれかを確認します。それ以外にこの関数が false を返す理由としては mysqli_query() のコールに成功して返された 結果セットが大きすぎる（メモリに割り当てられない）場合がありえます。 もし mysqli_field_count() がゼロ以外の値を 返した場合、文は空でない結果セットを生成しています。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

mysqli_multi_query() を参照ください。

注意

注意:

クエリ結果が使用するメモリを mysqli_free_result() 関数で開放するのは、どんな場合でも大切です。しかし、大きい結果セットを mysqli_store_result() で転送した際は、特にこれが 重要となります。

参考

  • mysqli_real_query() - SQL クエリを実行する
  • mysqli_use_result() - 結果セットの取得を開始する


現在の接続のスレッド ID を返す

  • ≪ mysqli::store_result
  • mysqli::thread_safe ≫
  • PHP Manual
  • mysqli
  • 現在の接続のスレッド ID を返す

mysqli::$thread_id

mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — 現在の接続のスレッド ID を返す

説明

オブジェクト指向型

int $mysqli->thread_id;

手続き型

mysqli_thread_id(mysqli $mysql): int

mysqli_thread_id() 関数は、現在の接続の スレッド ID を返します。この ID を使用すると、mysqli_kill() 関数でセッションを切断することが可能です。接続が切断し mysqli_ping() で再接続した場合は、スレッド ID は別のものになります。そのため、必要になったそのときにスレッド ID を取得するべきです。

注意:

スレッド ID は接続単位で割り当てられます。そのため、もし いったん切断した接続が再度確立された場合、新しいスレッド ID が割り当てられます。

実行中のクエリを停止するには、SQL コマンド KILL QUERY processid を使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

現在の接続のスレッド ID を返します。

例

例1 $mysqli->thread_id の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* スレッド ID を取得します */
$thread_id = $mysqli->thread_id;

/* 接続を切断します */
$mysqli->kill($thread_id);

/* これはエラーとなります */
if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", $mysqli->error);
exit;
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

/* スレッド ID を取得します */
$thread_id = mysqli_thread_id($link);

/* 接続を切断します */
mysqli_kill($link, $thread_id);

/* これはエラーとなります */
if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
printf("Error: %s\n", mysqli_error($link));
exit;
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error: MySQL server has gone away

参考

  • mysqli_kill() - サーバーに MySQL スレッドの停止を問い合わせる


スレッドセーフであるかどうかを返す

  • ≪ mysqli::$thread_id
  • mysqli::use_result ≫
  • PHP Manual
  • mysqli
  • スレッドセーフであるかどうかを返す

mysqli::thread_safe

mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — スレッドセーフであるかどうかを返す

説明

オブジェクト指向型

public mysqli::thread_safe(): bool

手続き型

mysqli_thread_safe(): bool

クライアントライブラリがスレッドセーフでコンパイルされているかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

クライアントライブラリがスレッドセーフの場合に true、 そうでない場合に false を返します。


結果セットの取得を開始する

  • ≪ mysqli::thread_safe
  • mysqli::$warning_count ≫
  • PHP Manual
  • mysqli
  • 結果セットの取得を開始する

mysqli::use_result

mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — 結果セットの取得を開始する

説明

オブジェクト指向型

public mysqli::use_result(): mysqli_result|false

手続き型

mysqli_use_result(mysqli $mysql): mysqli_result|false

データベース接続上で mysqli_real_query() 関数を使用して実行した直近のクエリから、結果セットの取得を開始します。

この関数あるいは mysqli_store_result() 関数は、 クエリ結果を取得する前にコールされる必要があります。また、どちらかの 関数をコールしなければ、データベース接続上の次のクエリは失敗します。

注意:

mysqli_use_result() は、データベースから結果セットの 全体を転送するわけではありません。そのため、セット内の行を移動するために mysqli_data_seek() を使用することはできません。 この機能を使用するには、mysqli_store_result() を使用して結果をバッファに取得する必要があります。クライアント側で 大量の処理を行う際は、mysqli_use_result() を 使用すべきではありません。なぜなら、この関数はサーバーとの接続を保持 し続け、取得しているデータに関連するテーブルについて、他のスレッドから 更新ができなくなるからです。

パラメータ

この関数にはパラメータはありません。

戻り値

バッファに取得しないで結果オブジェクトを返します。 エラー時には false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli::use_result() の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* 複数のクエリを実行します */
if ($mysqli->multi_query($query)) {
do {
/* 最初の結果セットを取得します */
if ($result = $mysqli->use_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
$result->close();
}
/* 区切り線を表示します */
if ($mysqli->more_results()) {
printf("-----------------\n");
}
} while ($mysqli->next_result());
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* 複数のクエリを実行します */
if (mysqli_multi_query($link, $query)) {
do {
/* 最初の結果セットを取得します */
if ($result = mysqli_use_result($link)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s\n", $row[0]);
}
mysqli_free_result($result);
}
/* 区切り線を表示します */
if (mysqli_more_results($link)) {
printf("-----------------\n");
}
} while (mysqli_next_result($link));
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer

参考

  • mysqli_real_query() - SQL クエリを実行する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する


指定した接続の直近のクエリから発生した警告の数を返す

  • ≪ mysqli::use_result
  • mysqli_stmt ≫
  • PHP Manual
  • mysqli
  • 指定した接続の直近のクエリから発生した警告の数を返す

mysqli::$warning_count

mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — 指定した接続の直近のクエリから発生した警告の数を返す

説明

オブジェクト指向型

int $mysqli->warning_count;

手続き型

mysqli_warning_count(mysqli $mysql): int

この接続の直近のクエリについて、発生した警告の数を返します。

注意:

警告の内容を取得するには、SQL コマンド SHOW WARNINGS [limit row_count] を使用します。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

戻り値

警告の数を返します。警告がなかった場合はゼロを返します。

例

例1 $mysqli->warning_count の例

オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$mysqli->query("CREATE TABLE myCity LIKE City");

/* ウェールズの珍しい地名です */
$query = "INSERT INTO myCity (CountryCode, Name) VALUES('GBR',
'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";

$mysqli->query($query);

if ($mysqli->warning_count) {
if ($result = $mysqli->query("SHOW WARNINGS")) {
$row = $result->fetch_row();
printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
$result->close();
}
}

/* 接続を閉じます */
$mysqli->close();
?>

手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

mysqli_query($link, "CREATE TABLE myCity LIKE City");

/* ウェールズの珍しい地名です */
$query = "INSERT INTO myCity (CountryCode, Name) VALUES('GBR',
'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')";

mysqli_query($link, $query);

if (mysqli_warning_count($link)) {
if ($result = mysqli_query($link, "SHOW WARNINGS")) {
$row = mysqli_fetch_row($result);
printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
mysqli_free_result($result);
}
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Warning (1264): Data truncated for column 'Name' at row 1

参考

  • mysqli_errno() - 直近の関数コールによるエラーコードを返す
  • mysqli_error() - 直近のエラーの内容を文字列で返す
  • mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す


mysqli_stmt クラス

(PHP 5, PHP 7, PHP 8)

はじめに

プリペアドステートメントを表します。

クラス概要

class mysqli_stmt {
/* プロパティ */
public readonly int|string $affected_rows;
public readonly int|string $insert_id;
public readonly int|string $num_rows;
public readonly int $param_count;
public readonly int $field_count;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly string $sqlstate;
public int $id;
/* メソッド */
public __construct(mysqli $mysql, ?string $query = null)
public attr_get(int $attribute): int
public attr_set(int $attribute, int $value): bool
public bind_param(string $types, mixed &$var, mixed &...$vars): bool
public bind_result(mixed &$var, mixed &...$vars): bool
public close(): true
public data_seek(int $offset): void
public execute(?array $params = null): bool
public fetch(): ?bool
public free_result(): void
public get_result(): mysqli_result|false
public get_warnings(): mysqli_warning|false
public more_results(): bool
public next_result(): bool
public num_rows(): int|string
public prepare(string $query): bool
public reset(): bool
public result_metadata(): mysqli_result|false
public send_long_data(int $param_num, string $data): bool
public store_result(): bool
}

プロパティ

id

プリペアドステートメントの ID を保持します。

目次

  • mysqli_stmt::$affected_rows — 直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す
  • mysqli_stmt::attr_get — ステートメントの属性の現在の値を取得する
  • mysqli_stmt::attr_set — プリペアドステートメントの振る舞いを変更する
  • mysqli_stmt::bind_param — プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt::bind_result — 結果を保存するため、プリペアドステートメントに変数をバインドする
  • mysqli_stmt::close — プリペアドステートメントを閉じる
  • mysqli_stmt::__construct — 新しい mysqli_stmt オブジェクトを構築する
  • mysqli_stmt::data_seek — バッファリングされた結果中の、任意の行にポインタを移動する
  • mysqli_stmt::$errno — 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt::$error — 直近のステートメントのエラー内容を文字列で返す
  • mysqli_stmt::$error_list — 直近で実行したステートメントからのエラーの一覧を返す
  • mysqli_stmt::execute — プリペアドステートメントを実行する
  • mysqli_stmt::fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_stmt::$field_count — 指定したステートメントのカラム数を返す
  • mysqli_stmt::free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する
  • mysqli_stmt::get_result — プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
  • mysqli_stmt::get_warnings — SHOW WARNINGS の結果を取得する
  • mysqli_stmt::$insert_id — 直近の INSERT 操作で生成した ID を取得する
  • mysqli_stmt::more_results — 複数クエリで、次の結果が存在するかどうかを調べる
  • mysqli_stmt::next_result — 複数クエリから、次の結果を読み込む
  • mysqli_stmt::$num_rows — サーバーから取得した結果セットの行数を返す
  • mysqli_stmt::$param_count — 指定したステートメントのパラメータ数を返す
  • mysqli_stmt::prepare — SQL ステートメントを実行するために準備する
  • mysqli_stmt::reset — プリペアドステートメントをリセットする
  • mysqli_stmt::result_metadata — プリペアドステートメントから結果セットのメタデータを返す
  • mysqli_stmt::send_long_data — データをブロックで送信する
  • mysqli_stmt::$sqlstate — 直前のステートメントの操作での SQLSTATE エラーを返す
  • mysqli_stmt::store_result — 内部バッファに結果を保存する


直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す

  • ≪ mysqli_stmt
  • mysqli_stmt::attr_get ≫
  • PHP Manual
  • mysqli_stmt
  • 直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す

mysqli_stmt::$affected_rows

mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — 直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す

説明

オブジェクト指向型

int|string $mysqli_stmt->affected_rows;

手続き型

mysqli_stmt_affected_rows(mysqli_stmt $statement): int|string

INSERT、 UPDATE あるいは DELETE クエリによって変更された行の数を返します。

SELECT クエリに対しては、 mysqli_stmt_num_rows() 関数と同じように動作します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

ゼロより大きい整数の場合、変更または取得された行の数を示します。ゼロの場合は、 UPDATE で 1 行も更新されなかった・ WHERE 句にマッチする行がなかった・ あるいはまだクエリが実行されていないのいずれかであることを示します。 -1 は、クエリがエラーを返したか、 SELECT 文については、 mysqli_stmt_store_result() をコールする前に mysqli_stmt_affected_rows() がコールされたことを示します。

注意:

変更された行の数が PHP の int 型の最大値をこえる場合は、変更された 行の数は文字列として返されます。

例

例1 mysqli_stmt_affected_rows() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 一時テーブルを作成します */
$mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

$query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

/* 文を準備します */
$stmt = $mysqli->prepare($query);

/* プレースホルダに変数をバインドします */
$code = 'A%';
$stmt->bind_param("s", $code);

/* 文を実行します */
$stmt->execute();

printf("Rows inserted: %d\n", $stmt->affected_rows);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 一時テーブルを作成します */
mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

$query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

/* 文を準備します */
$stmt = mysqli_prepare($link, $query);

/* プレースホルダに変数をバインドします */
$code = 'A%';
mysqli_stmt_bind_param($stmt, "s", $code);

/* 文を実行します */
mysqli_stmt_execute($stmt);

printf("Rows inserted: %d\n", mysqli_stmt_affected_rows($stmt));

上の例の出力は以下となります。

Rows inserted: 17

参考

  • mysqli_stmt_num_rows() - サーバーから取得した結果セットの行数を返す
  • mysqli_stmt_store_result() - 内部バッファに結果を保存する


ステートメントの属性の現在の値を取得する

  • ≪ mysqli_stmt::$affected_rows
  • mysqli_stmt::attr_set ≫
  • PHP Manual
  • mysqli_stmt
  • ステートメントの属性の現在の値を取得する

mysqli_stmt::attr_get

mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — ステートメントの属性の現在の値を取得する

説明

オブジェクト指向型

public mysqli_stmt::attr_get(int $attribute): int

手続き型

mysqli_stmt_attr_get(mysqli_stmt $statement, int $attribute): int

ステートメントの属性の現在の値を取得します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

attribute

取得したい属性。

戻り値

属性の値を返します。


プリペアドステートメントの振る舞いを変更する

  • ≪ mysqli_stmt::attr_get
  • mysqli_stmt::bind_param ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントの振る舞いを変更する

mysqli_stmt::attr_set

mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — プリペアドステートメントの振る舞いを変更する

説明

オブジェクト指向型

public mysqli_stmt::attr_set(int $attribute, int $value): bool

手続き型

mysqli_stmt_attr_set(mysqli_stmt $statement, int $attribute, int $value): bool

プリペアドステートメントの振る舞いを変更します。 複数の属性を設定するには、この関数を複数回コールします。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

attribute

設定したい属性。次のいずれかの値となります。

属性の値
文字 | 説明
MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | true に設定すると、mysqli_stmt_store_result() は メタデータ MYSQL_FIELD->max_length の値を上書きします。
MYSQLI_STMT_ATTR_CURSOR_TYPE | mysqli_stmt_execute() が起動された際にステートメントをオープンするためのカーソル型。 value は、MYSQLI_CURSOR_TYPE_NO_CURSOR (デフォルト) あるいは MYSQLI_CURSOR_TYPE_READ_ONLY となります。
MYSQLI_STMT_ATTR_PREFETCH_ROWS | カーソルの使用時にサーバーからいちどに取得する行数。 value に指定できる値の範囲は 1 から unsigned long の最大値までで、デフォルトは 1 です。

MYSQLI_STMT_ATTR_CURSOR_TYPE オプションで MYSQLI_CURSOR_TYPE_READ_ONLY を使用すると、 mysqli_stmt_execute() を起動した際にそのステートメント用のカーソルをオープンします。 以前に mysqli_stmt_execute() をコールした際にオープンしたカーソルが残っている場合は、 それを閉じてから新しいカーソルをオープンします。また mysqli_stmt_reset() も、オープンしているカーソルをすべて閉じてからステートメント再実行の準備をします。 mysqli_stmt_free_result() は、オープンしているカーソルをすべて閉じます。

プリペアドステートメント用のカーソルをオープンするのなら mysqli_stmt_store_result() は不要です。

value

属性に割り当てるモード。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

参考

  • » Connector/MySQL mysql_stmt_attr_set()


プリペアドステートメントのパラメータに変数をバインドする

  • ≪ mysqli_stmt::attr_set
  • mysqli_stmt::bind_result ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントのパラメータに変数をバインドする

mysqli_stmt::bind_param

mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — プリペアドステートメントのパラメータに変数をバインドする

説明

オブジェクト指向型

public mysqli_stmt::bind_param(string $types, mixed &$var, mixed &...$vars): bool

手続き型

mysqli_stmt_bind_param(
mysqli_stmt $statement,
string $types,
mixed &$var,
mixed &...$vars
): bool

mysqli_prepare() や mysqli_stmt_prepare() で準備された、 SQLステートメントのパラメータマーカに変数をバインドします。

注意:

データのサイズがパケットサイズの最大値（max_allowed_packet）を こえた場合、types に b を 指定して mysqli_stmt_send_long_data() を使用し、 データをパケットに分割して送信する必要があります。

注意:

mysqli_stmt_bind_param() と
call_user_func_array() を組み合わせて使う場合は注意が必要です。
mysqli_stmt_bind_param() へのパラメータは参照渡しでなければなりませんが、
call_user_func_array() には変数のリストをパラメータとして渡すことができます。
この変数は参照であっても値であってもかまいません。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

types

ひとつあるいは複数の文字で、対応するバインド変数の型を表します。

型指定文字
文字 | 説明
i | 対応する変数の型は int です。
d | 対応する変数の型は float です。
s | 対応する変数の型は string です。
b | 対応する変数の型は blob で、複数のパケットに分割して送信されます。

var
vars

変数の数。文字列 types の長さは、ステートメント中のパラメータの数と一致する必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli_stmt::bind_param() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

$stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
$stmt->bind_param('sssd', $code, $language, $official, $percent);

$code = 'DEU';
$language = 'Bavarian';
$official = "F";
$percent = 11.2;

$stmt->execute();

printf("%d row inserted.\n", $stmt->affected_rows);

/* CountryLanguage テーブルを削除します */
$mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
printf("%d row deleted.\n", $mysqli->affected_rows);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

$stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);

$code = 'DEU';
$language = 'Bavarian';
$official = "F";
$percent = 11.2;

mysqli_stmt_execute($stmt);

printf("%d row inserted.\n", mysqli_stmt_affected_rows($stmt));

/* CountryLanguage テーブルを削除します */
mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
printf("%d row deleted.\n", mysqli_affected_rows($link));

上の例の出力は以下となります。

1 row inserted.
1 row deleted.

例2 引数を渡すために ... を使う

可変長の引数を渡すために、 ... 演算子を使うことができます。 たとえば WHERE IN 条件で使えます。

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

$stmt = $mysqli->prepare("SELECT Language FROM CountryLanguage WHERE CountryCode IN (?, ?)");
/* Using ... to provide arguments */
$stmt->bind_param('ss', ...['DEU', 'POL']);
$stmt->execute();
$stmt->store_result();

printf("%d rows found.\n", $stmt->num_rows());

上の例の出力は以下となります。

10 rows found.

参考

  • mysqli_stmt_bind_result() - 結果を保存するため、プリペアドステートメントに変数をバインドする
  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_send_long_data() - データをブロックで送信する
  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す


結果を保存するため、プリペアドステートメントに変数をバインドする

  • ≪ mysqli_stmt::bind_param
  • mysqli_stmt::close ≫
  • PHP Manual
  • mysqli_stmt
  • 結果を保存するため、プリペアドステートメントに変数をバインドする

mysqli_stmt::bind_result

mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — 結果を保存するため、プリペアドステートメントに変数をバインドする

説明

オブジェクト指向型

public mysqli_stmt::bind_result(mixed &$var, mixed &...$vars): bool

手続き型

mysqli_stmt_bind_result(mysqli_stmt $statement, mixed &$var, mixed &...$vars): bool

結果セットのカラムを変数にバインドします。

データを取得するために mysqli_stmt_fetch() がコールされた場合、MySQL クライアント/ サーバー プロトコルはバインドされたカラムのデータを var/vars に格納します。

結果セットが一部取得された後であっても、 カラムはいつでもバインドしたり、再バインドしたりできます。 新しいバインドは、 mysqli_stmt_fetch() が次回コールされた時に効力を発揮します。

注意:

すべてのカラムを、mysqli_stmt_execute() をコールしてから mysqli_stmt_fetch() をコールするまでの間に バインドしておく必要があることに注意しましょう。

注意:

カラムの型に応じて、 バインド変数の型も対応する PHP の型に自動的に変換されます。

ヒント

この関数は、結果が単一の値の場合に役立つものです。 反復可能な結果セットを取得したり、 行をオブジェクトや配列で取得したい場合は、 mysqli_stmt_get_result() を使って下さい。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

var

バインドする最初の変数。

vars

バインドする残りの変数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* ステートメントを準備します */
$stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
$stmt->execute();

/* 変数をプリペアドステートメントにバインドします */
$stmt->bind_result($col1, $col2);

/* 値を取得します */
while ($stmt->fetch()) {
printf("%s %s\n", $col1, $col2);
}

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* ステートメントを準備します */
$stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
mysqli_stmt_execute($stmt);

/* 変数をプリペアドステートメントにバインドします */
mysqli_stmt_bind_result($stmt, $col1, $col2);

/* 値を取得します */
while (mysqli_stmt_fetch($stmt)) {
printf("%s %s\n", $col1, $col2);
}

上の例の出力は、 たとえば以下のようになります。

AFG Afghanistan
ALB Albania
DZA Algeria
ASM American Samoa
AND Andorra

参考

  • mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_prepare() - SQL ステートメントを実行するために準備する


プリペアドステートメントを閉じる

  • ≪ mysqli_stmt::bind_result
  • mysqli_stmt::__construct ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントを閉じる

mysqli_stmt::close

mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — プリペアドステートメントを閉じる

説明

オブジェクト指向型

public mysqli_stmt::close(): true

手続き型

mysqli_stmt_close(mysqli_stmt $statement): true

プリペアドステートメントを閉じます。また、mysqli_stmt_close() は stmt が指すステートメントハンドルを開放します。 現在のステートメントが実行中あるいはまだ結果を取得していない場合、 この関数はキャンセルされ、次のクエリが実行されます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する


新しい mysqli_stmt オブジェクトを構築する

  • ≪ mysqli_stmt::close
  • mysqli_stmt::data_seek ≫
  • PHP Manual
  • mysqli_stmt
  • 新しい mysqli_stmt オブジェクトを構築する

mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — 新しい mysqli_stmt オブジェクトを構築する

説明

public mysqli_stmt::__construct(mysqli $mysql, ?string $query = null)

このメソッドは、新しい mysqli_stmt オブジェクトを構築します。

パラメータ

link

有効な mysqli オブジェクト

query

クエリを文字列で渡します。 この引数が null の場合、コンストラクタは mysqli_stmt_init() と同じ振る舞いをします。 null でない場合、 mysqli_prepare() と同じ振る舞いをします。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
8.0.0 | query は、nullable になりました。

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_init() - ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す


バッファリングされた結果中の、任意の行にポインタを移動する

  • ≪ mysqli_stmt::__construct
  • mysqli_stmt::$errno ≫
  • PHP Manual
  • mysqli_stmt
  • バッファリングされた結果中の、任意の行にポインタを移動する

mysqli_stmt::data_seek

mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — バッファリングされた結果中の、任意の行にポインタを移動する

説明

オブジェクト指向型

public mysqli_stmt::data_seek(int $offset): void

手続き型

mysqli_stmt_data_seek(mysqli_stmt $statement, int $offset): void

この関数は、バッファリングされた結果セットのポインタを、 offset で指定した任意の行に移動させます。

この関数は、バッファリング済みの内部結果セットに対してのみ動作します。 mysqli_stmt_store_result() は、 mysqli_stmt_data_seek() より前にコールしなければなりません。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

offset

ゼロから行の総数 - 1（0..mysqli_stmt_num_rows() - 1） までの間である必要があります。

戻り値

値を返しません。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
$stmt = $mysqli->prepare($query);
$stmt->execute();

$stmt->bind_result($name, $code);

$stmt->store_result();

/* 行番号 400 に移動します */
$stmt->data_seek(399);

$stmt->fetch();

printf("City: %s Countrycode: %s\n", $name, $code);

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
$stmt = mysqli_prepare($link, $query);

mysqli_stmt_execute($stmt);

mysqli_stmt_bind_result($stmt, $name, $code);

mysqli_stmt_store_result($stmt);

/* 行番号 400 に移動します */
mysqli_stmt_data_seek($stmt, 399);

mysqli_stmt_fetch($stmt);

printf("City: %s Countrycode: %s\n", $name, $code);

上の例の出力は以下となります。

City: Benin City  Countrycode: NGA

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_store_result() - 内部バッファに結果を保存する
  • mysqli_stmt_num_rows() - サーバーから取得した結果セットの行数を返す
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する


直近のステートメントのコールに関するエラーコードを返す

  • ≪ mysqli_stmt::data_seek
  • mysqli_stmt::$error ≫
  • PHP Manual
  • mysqli_stmt
  • 直近のステートメントのコールに関するエラーコードを返す

mysqli_stmt::$errno

mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — 直近のステートメントのコールに関するエラーコードを返す

説明

オブジェクト指向型

int $mysqli_stmt->errno;

手続き型

mysqli_stmt_errno(mysqli_stmt $statement): int

直近に実行されたステートメントが 成功あるいは失敗した際のエラーコードを返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

エラーコードの値を返します。ゼロはエラーが発生しなかったことを示します。

例

例1 オブジェクト指向型

<?php
/* 接続をオープンします */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {

/* テーブルを削除します */
$mysqli->query("DROP TABLE myCountry");

/* クエリを実行します */
$stmt->execute();

printf("Error: %d.\n", $stmt->errno);

/* ステートメントを閉じます */
$stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
/* 接続をオープンします */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {

/* テーブルを削除します */
mysqli_query($link, "DROP TABLE myCountry");

/* クエリを実行します */
mysqli_stmt_execute($stmt);

printf("Error: %d.\n", mysqli_stmt_errno($stmt));

/* ステートメントを閉じます */
mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error: 1146.

参考

  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す
  • mysqli_stmt_sqlstate() - 直前のステートメントの操作での SQLSTATE エラーを返す


直近のステートメントのエラー内容を文字列で返す

  • ≪ mysqli_stmt::$errno
  • mysqli_stmt::$error_list ≫
  • PHP Manual
  • mysqli_stmt
  • 直近のステートメントのエラー内容を文字列で返す

mysqli_stmt::$error

mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — 直近のステートメントのエラー内容を文字列で返す

説明

オブジェクト指向型

string $mysqli_stmt->error;

手続き型

mysqli_stmt_error(mysqli_stmt $statement): string

直近に実行されたステートメントが 成功あるいは失敗した際のエラーメッセージを文字列で返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

エラーの内容を文字列で返します。エラーが発生しなかった場合は空文字列を返します。

例

例1 オブジェクト指向型

<?php
/* 接続をオープンします */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {

/* テーブルを削除します */
$mysqli->query("DROP TABLE myCountry");

/* クエリを実行します */
$stmt->execute();

printf("Error: %s.\n", $stmt->error);

/* ステートメントを閉じます */
$stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
/* 接続をオープンします */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {

/* テーブルを削除します */
mysqli_query($link, "DROP TABLE myCountry");

/* クエリを実行します */
mysqli_stmt_execute($stmt);

printf("Error: %s.\n", mysqli_stmt_error($stmt));

/* ステートメントを閉じます */
mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error: Table 'world.myCountry' doesn't exist.

参考

  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_sqlstate() - 直前のステートメントの操作での SQLSTATE エラーを返す


直近で実行したステートメントからのエラーの一覧を返す

  • ≪ mysqli_stmt::$error
  • mysqli_stmt::execute ≫
  • PHP Manual
  • mysqli_stmt
  • 直近で実行したステートメントからのエラーの一覧を返す

mysqli_stmt::$error_list

mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — 直近で実行したステートメントからのエラーの一覧を返す

説明

オブジェクト指向型

array $mysqli_stmt->error_list;

手続き型

mysqli_stmt_error_list(mysqli_stmt $statement): array

エラーの配列を返します。この配列の内容は、直近で実行したステートメント関数で発生したエラーです。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

エラーの一覧を返します。個々のエラーは連想配列形式で、 errno、error および sqlstate のキーを含みます。

例

例1 オブジェクト指向型

<?php
/* 接続を開きます */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続を確認します */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {

/* テーブルを削除します */
$mysqli->query("DROP TABLE myCountry");

/* クエリを実行します */
$stmt->execute();

echo "Error:\n";
print_r($stmt->error_list);

/* 接続を閉じます */
$stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
/* 接続を開きます */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続を確認します */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {

/* テーブルを削除します */
mysqli_query($link, "DROP TABLE myCountry");

/* クエリを実行します */
mysqli_stmt_execute($stmt);

echo "Error:\n";
print_r(mysql_stmt_error_list($stmt));

/* 接続を閉じます */
mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error:
Array
(
    [0] => Array
        (
            [errno] => 1146
            [sqlstate] => 42S02
            [error] => Table 'world.myCountry' doesn't exist
        )

)

参考

  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す
  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_sqlstate() - 直前のステートメントの操作での SQLSTATE エラーを返す


プリペアドステートメントを実行する

  • ≪ mysqli_stmt::$error_list
  • mysqli_stmt::fetch ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントを実行する

mysqli_stmt::execute

mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — プリペアドステートメントを実行する

説明

オブジェクト指向型

public mysqli_stmt::execute(?array $params = null): bool

手続き型

mysqli_stmt_execute(mysqli_stmt $statement, ?array $params = null): bool

事前に準備したSQL文を実行します。
SQL文は実行する前に、正常に準備されていなければいけません。
準備は、mysqli_prepare() または
mysqli_stmt_prepare() を実行するか、
mysqli_stmt::__construct() に第二引数を渡すことで行います。

SQL文が UPDATE、DELETE あるいは INSERT であった場合、 変更された行の総数は mysqli_stmt_affected_rows() 関数を使用することで取得可能です。 クエリが結果セットを返す場合、 mysqli_stmt_get_result() 関数を使って取得するか、 ステートメント から直接一行ずつ mysqli_stmt_fetch() 関数を使って取得することもできます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

params

実行されるSQL文にバインドする引数を指定する、 オプションの(連想配列でない)リスト形式の配列。 それぞれの値は文字列として扱われます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
8.1.0 | オプションの引数 params が追加されました。

例

例1 プリペアドステートメントに値をバインドして実行する

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");

/* insert 文を準備します */
$stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

/* 変数をパラメータにバインドします */
$stmt->bind_param("sss", $val1, $val2, $val3);

$val1 = 'Stuttgart';
$val2 = 'DEU';
$val3 = 'Baden-Wuerttemberg';

/* SQL文を実行します */
$stmt->execute();

$val1 = 'Bordeaux';
$val2 = 'FRA';
$val3 = 'Aquitaine';

/* SQL文を実行します */
$stmt->execute();

/* myCity テーブルから全ての行を取得します */
$query = "SELECT Name, CountryCode, District FROM myCity";
$result = $mysqli->query($query);
while ($row = $result->fetch_row()) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

/* insert 文を準備します */
$stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

/* 変数をパラメータにバインドします */
mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);

$val1 = 'Stuttgart';
$val2 = 'DEU';
$val3 = 'Baden-Wuerttemberg';

/* SQL文を実行します */
mysqli_stmt_execute($stmt);

$val1 = 'Bordeaux';
$val2 = 'FRA';
$val3 = 'Aquitaine';

/* SQL文を実行します */
mysqli_stmt_execute($stmt);

/* myCity テーブルから全ての行を取得します */
$query = "SELECT Name, CountryCode, District FROM myCity";
$result = mysqli_query($link, $query);
while ($row = mysqli_fetch_row($result)) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}

上の例の出力は以下となります。

Stuttgart (DEU,Baden-Wuerttemberg)
Bordeaux (FRA,Aquitaine)

例2 プリペアドステートメントに、値を配列で指定して実行する

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

$mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City');

/* insert 文を準備します */
$stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

/* SQL文を実行します */
$stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

/* myCity テーブルから全ての行を取得します */
$query = 'SELECT Name, CountryCode, District FROM myCity';
$result = $mysqli->query($query);
while ($row = $result->fetch_row()) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City');

/* insert 文を準備します */
$stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

/* SQL文を実行します */
mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

/* myCity テーブルから全ての行を取得します */
$query = 'SELECT Name, CountryCode, District FROM myCity';
$result = mysqli_query($link, $query);
while ($row = mysqli_fetch_row($result)) {
printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
}

上の例の出力は以下となります。

Stuttgart (DEU,Baden-Wuerttemberg)

参考

  • mysqli_execute_query() - SQL文を準備し、変数をバインドし、実行する
  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する


プリペアドステートメントから結果を取得し、バインド変数に格納する

  • ≪ mysqli_stmt::execute
  • mysqli_stmt::$field_count ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントから結果を取得し、バインド変数に格納する

mysqli_stmt::fetch

mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する

説明

オブジェクト指向型

public mysqli_stmt::fetch(): ?bool

手続き型

mysqli_stmt_fetch(mysqli_stmt $statement): ?bool

プリペアドステートメントから結果を読み込み、 mysqli_stmt_bind_result() でバインドした変数に格納します。

注意:

mysqli_stmt_fetch() をコールする前に、すべての カラムがバインド済みである必要があることに注意しましょう。

注意:

データの転送はバッファを用いずに行います。 mysqli_stmt_store_result() をコールするとバッファを使用し、パフォーマンスが減少します (しかしメモリのコストは下がります)。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

戻り値
値 | 説明
true | 成功。データが取得されました。
false | エラーが発生しました。
null | 行/データがもうありません。あるいは、データの切り詰めが発生しました。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

if ($stmt = $mysqli->prepare($query)) {

/* ステートメントを実行します */
$stmt->execute();

/* 結果変数をバインドします */
$stmt->bind_result($name, $code);

/* 値を取得します */
while ($stmt->fetch()) {
printf ("%s (%s)\n", $name, $code);
}

/* ステートメントを閉じます */
$stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

if ($stmt = mysqli_prepare($link, $query)) {

/* ステートメントを実行します */
mysqli_stmt_execute($stmt);

/* 結果変数をバインドします */
mysqli_stmt_bind_result($stmt, $name, $code);

/* 値を取得します */
while (mysqli_stmt_fetch($stmt)) {
printf ("%s (%s)\n", $name, $code);
}

/* ステートメントを閉じます */
mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Rockford (USA)
Tallahassee (USA)
Salinas (USA)
Santa Clarita (USA)
Springfield (USA)

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す
  • mysqli_stmt_bind_result() - 結果を保存するため、プリペアドステートメントに変数をバインドする


指定したステートメントのカラム数を返す

  • ≪ mysqli_stmt::fetch
  • mysqli_stmt::free_result ≫
  • PHP Manual
  • mysqli_stmt
  • 指定したステートメントのカラム数を返す

mysqli_stmt::$field_count

mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — 指定したステートメントのカラム数を返す

説明

オブジェクト指向型

int $mysqli_stmt->field_count;

手続き型

mysqli_stmt_field_count(mysqli_stmt $statement): int

プリペアドステートメントで指定されたカラムの数を返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

カラム数を示す整数値を返します。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$code = 'FR';

$stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Code=?");
$stmt->bind_param('s', $code);
$stmt->execute();
$row = $stmt->get_result()->fetch_row();
for ($i = 0; $i < $stmt->field_count; $i++) {
printf("Value of column number %d is %s", $i, $row[$i]);
}

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

$code = 'FR';

$stmt = mysqli_prepare($mysqli, "SELECT Name FROM Country WHERE Code=?");
mysqli_stmt_bind_param($stmt, 's', $code);
mysqli_stmt_execute($stmt);
$result = mysqli_stmt_get_result($stmt);
$row = mysqli_fetch_row($result);
for ($i = 0; $i < mysqli_stmt_field_count($stmt); $i++) {
printf("Value of column number %d is %s", $i, $row[$i]);
}

上の例の出力は、 たとえば以下のようになります。

Value of column number 0 is France

参考

  • mysqli_stmt_num_rows() - サーバーから取得した結果セットの行数を返す


指定したステートメントハンドルの結果を格納したメモリを開放する

  • ≪ mysqli_stmt::$field_count
  • mysqli_stmt::get_result ≫
  • PHP Manual
  • mysqli_stmt
  • 指定したステートメントハンドルの結果を格納したメモリを開放する

mysqli_stmt::free_result

mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する

説明

オブジェクト指向型

public mysqli_stmt::free_result(): void

手続き型

mysqli_stmt_free_result(mysqli_stmt $statement): void

ステートメントに関連する結果のメモリを開放します。このメモリは mysqli_stmt_store_result() によって割り当てられたものです。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

値を返しません。

参考

  • mysqli_stmt_store_result() - 内部バッファに結果を保存する


プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する

  • ≪ mysqli_stmt::free_result
  • mysqli_stmt::get_warnings ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する

mysqli_stmt::get_result

mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::get_result -- mysqli_stmt_get_result — プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する

説明

オブジェクト指向型

public mysqli_stmt::get_result(): mysqli_result|false

手続き型

mysqli_stmt_get_result(mysqli_stmt $statement): mysqli_result|false

プリペアドステートメントから結果を mysqli_result オブジェクトとして取得します。 データは MySQLサーバー からPHPへ転送されます。 このメソッドは結果セットを生成するクエリの場合にだけコールされるべきです。

注意:

mysqlnd でのみ使用可能です。

注意:

この関数は、 mysqli_stmt_store_result() と一緒に使うことはできません。 これらの関数は両方、MySQLサーバー から完全な結果セットを取得します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

失敗した場合に false を返します。 結果セットを生成するクエリ、 つまり SELECT, SHOW, DESCRIBE あるいは EXPLAIN が成功した場合は、mysqli_stmt_get_result() は mysqli_result オブジェクトを返します。それ以外のクエリが成功した場合は、 mysqli_stmt_get_result() は false を返します。 PHP 7.4.13 より前のバージョンでは、 その他の DML クエリを実行したのかクエリの実行に失敗したのかを区別するのに、 mysqli_errno() 関数を使わなければなりませんでした。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

$stmt = $mysqli->prepare($query);
$stmt->bind_param("s", $continent);

$continentList = array('Europe', 'Africa', 'Asia', 'North America');

foreach ($continentList as $continent) {
$stmt->execute();
$result = $stmt->get_result();
while ($row = $result->fetch_array(MYSQLI_NUM)) {
foreach ($row as $r) {
print "$r ";
}
print "\n";
}
}

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

$stmt = mysqli_prepare($link, $query);
mysqli_stmt_bind_param($stmt, "s", $continent);

$continentList= array('Europe', 'Africa', 'Asia', 'North America');

foreach ($continentList as $continent) {
mysqli_stmt_execute($stmt);
$result = mysqli_stmt_get_result($stmt);
while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
foreach ($row as $r) {
print "$r ";
}
print "\n";
}
}

上の例の出力は、 たとえば以下のようになります。

Albania 3401200 Europe
Algeria 31471000 Africa
Afghanistan 22720000 Asia
Anguilla 8000 North America

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_result_metadata() - プリペアドステートメントから結果セットのメタデータを返す
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_stmt_store_result() - 内部バッファに結果を保存する


SHOW WARNINGS の結果を取得する

  • ≪ mysqli_stmt::get_result
  • mysqli_stmt::$insert_id ≫
  • PHP Manual
  • mysqli_stmt
  • SHOW WARNINGS の結果を取得する

mysqli_stmt::get_warnings

mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — SHOW WARNINGS の結果を取得する

説明

オブジェクト指向型

public mysqli_stmt::get_warnings(): mysqli_warning|false

手続き型

mysqli_stmt_get_warnings(mysqli_stmt $statement): mysqli_warning|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


直近の INSERT 操作で生成した ID を取得する

  • ≪ mysqli_stmt::get_warnings
  • mysqli_stmt::more_results ≫
  • PHP Manual
  • mysqli_stmt
  • 直近の INSERT 操作で生成した ID を取得する

mysqli_stmt::$insert_id

mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — 直近の INSERT 操作で生成した ID を取得する

説明

オブジェクト指向型

int|string $mysqli_stmt->insert_id;

手続き型

mysqli_stmt_insert_id(mysqli_stmt $statement): int|string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


複数クエリで、次の結果が存在するかどうかを調べる

  • ≪ mysqli_stmt::$insert_id
  • mysqli_stmt::next_result ≫
  • PHP Manual
  • mysqli_stmt
  • 複数クエリで、次の結果が存在するかどうかを調べる

mysqli_stmt::more_results

mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::more_results -- mysqli_stmt_more_results — 複数クエリで、次の結果が存在するかどうかを調べる

説明

オブジェクト指向型

public mysqli_stmt::more_results(): bool

手続き型:

mysqli_stmt_more_results(mysqli_stmt $statement): bool

複数クエリで、次の結果が存在するかどうかを調べます。

注意:

mysqlnd でのみ使用可能です。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

結果がさらに存在する場合に true、それ以外の場合に false を返します。

参考

  • mysqli_stmt::next_result() - 複数クエリから、次の結果を読み込む
  • mysqli::multi_query() - データベース上でひとつ以上のクエリを実行する


複数クエリから、次の結果を読み込む

  • ≪ mysqli_stmt::more_results
  • mysqli_stmt::$num_rows ≫
  • PHP Manual
  • mysqli_stmt
  • 複数クエリから、次の結果を読み込む

mysqli_stmt::next_result

mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — 複数クエリから、次の結果を読み込む

説明

オブジェクト指向型

public mysqli_stmt::next_result(): bool

手続き型:

mysqli_stmt_next_result(mysqli_stmt $statement): bool

複数クエリから、次の結果を読み込みます。

注意:

PHP 8.1.0 より前のバージョンでは、 この関数は mysqlnd でのみ利用可能でした。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

変更履歴

バージョン | 説明
8.1.0 | libmysqlclient をリンクしている場合でも、 この関数を使えるようになりました。

参考

  • mysqli_stmt::more_results() - 複数クエリで、次の結果が存在するかどうかを調べる
  • mysqli::multi_query() - データベース上でひとつ以上のクエリを実行する


サーバーから取得した結果セットの行数を返す

  • ≪ mysqli_stmt::next_result
  • mysqli_stmt::$param_count ≫
  • PHP Manual
  • mysqli_stmt
  • サーバーから取得した結果セットの行数を返す

mysqli_stmt::$num_rows

mysqli_stmt::num_rows

mysqli_stmt_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — サーバーから取得した結果セットの行数を返す

説明

オブジェクト指向型

int|string $mysqli_stmt->num_rows;
public mysqli_stmt::num_rows(): int|string

手続き型

mysqli_stmt_num_rows(mysqli_stmt $statement): int|string

ステートメントハンドルにバッファリングされた 結果セットの行数を返します。この関数は、 mysqli_stmt_store_result() を用いて結果全体をステートメントハンドルにバッファリングした後に使えます。

全ての行をサーバーから取得していない場合、 この関数は 0 を返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

バッファリングされた行数を整数値で返します。 アンバッファリングモードでは、 全ての行をサーバーから取得していない場合、 0 を返します。

注意:

行数が PHP_INT_MAX より大きい場合、 行数の数値は文字列で返されます。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
$stmt = $mysqli->prepare($query);
$stmt->execute();

/* 内部バッファに結果を格納します */
$stmt->store_result();

printf("Number of rows: %d.\n", $stmt->num_rows);

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
$stmt = mysqli_prepare($link, $query);
mysqli_stmt_execute($stmt);

/* 内部バッファに結果を格納します */
mysqli_stmt_store_result($stmt);

printf("Number of rows: %d.\n", mysqli_stmt_num_rows($stmt));

上の例の出力は以下となります。

Number of rows: 20.

参考

  • mysqli_stmt_store_result() - 内部バッファに結果を保存する
  • mysqli_stmt_affected_rows() - 直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す
  • mysqli_prepare() - 実行するための SQL文 を準備する


指定したステートメントのパラメータ数を返す

  • ≪ mysqli_stmt::$num_rows
  • mysqli_stmt::prepare ≫
  • PHP Manual
  • mysqli_stmt
  • 指定したステートメントのパラメータ数を返す

mysqli_stmt::$param_count

mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — 指定したステートメントのパラメータ数を返す

説明

オブジェクト指向型

int $mysqli_stmt->param_count;

手続き型

mysqli_stmt_param_count(mysqli_stmt $statement): int

プリペアドステートメント内のパラメータマーカの数を返します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

パラメータの数を整数で返します。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

$marker = $stmt->param_count;
printf("Statement has %d markers.\n", $marker);

/* ステートメントを閉じます */
$stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {

$marker = mysqli_stmt_param_count($stmt);
printf("Statement has %d markers.\n", $marker);

/* ステートメントを閉じます */
mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Statement has 2 markers.

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する


SQL ステートメントを実行するために準備する

  • ≪ mysqli_stmt::$param_count
  • mysqli_stmt::reset ≫
  • PHP Manual
  • mysqli_stmt
  • SQL ステートメントを実行するために準備する

mysqli_stmt::prepare

mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — SQL ステートメントを実行するために準備する

説明

オブジェクト指向型

public mysqli_stmt::prepare(string $query): bool

手続き型

mysqli_stmt_prepare(mysqli_stmt $statement, string $query): bool

実行する前にSQL文を準備します。 指定するクエリは、単一のSQL文でなければいけません。

SQL文のテンプレートには、ゼロ個以上のパラメータマーカ (?) を含めることができます。 パラメータマーカは、プレースホルダとも呼ばれています。 パラメータマーカは、ステートメントを実行する前に mysqli_stmt_bind_param() を使用して アプリケーション変数にバインドする必要があります。

注意:

サーバーの max_allowed_packet よりも長いステートメントを mysqli_stmt_prepare() に渡した場合、 返ってくるエラーコードは MySQL Native Driver (mysqlnd) を使っているか MySQL Client Library (libmysqlclient) を使っているかで異なります。 それぞれ、次のように振る舞います。

  • Linux 上の mysqlnd では、エラーコード 1153 を返します。 エラーメッセージは got a packet bigger than max_allowed_packet bytes です。

  • Windows 上の mysqlnd では、エラーコード 2006 を返します。 エラーメッセージは server has gone away です。

  • すべてのプラットフォームの libmysqlclient では、エラーコード 2006 を返します。エラーメッセージは server has gone away です。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

query

クエリを表す文字列。単一の SQL 文で構成されている必要があります。

SQL文には、適切な位置にゼロ個以上のパラメータマーカを含めることができます。 パラメータマーカは、クエスチョンマーク(?)で表します。

注意:

パラメータのマーカは、それが SQL 文の適切な位置にある場合のみ 有効です。例えば INSERT 文の VALUES() リストの中 (行に登録するカラムの値を指定する) や WHERE 句でカラムのデータと比較する値などが適切な位置の例です。 しかし、識別子 (テーブルやカラムの名前) には使用できません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli_stmt::prepare() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$city = "Amersfoort";

/* プリペアドステートメントを作成します */
$stmt = $mysqli->stmt_init();
$stmt->prepare("SELECT District FROM City WHERE Name=?");

/* マーカにパラメータをバインドします */
$stmt->bind_param("s", $city);

/* クエリを実行します */
$stmt->execute();

/* 結果変数をバインドします */
$stmt->bind_result($district);

/* 値を取得します */
$stmt->fetch();

printf("%s is in district %s\n", $city, $district);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$city = "Amersfoort";

/* プリペアドステートメントを作成します */
$stmt = mysqli_stmt_init($link);
mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

/* マーカにパラメータをバインドします */
mysqli_stmt_bind_param($stmt, "s", $city);

/* クエリを実行します */
mysqli_stmt_execute($stmt);

/* 結果変数をバインドします */
mysqli_stmt_bind_result($stmt, $district);

/* 値を取得します */
mysqli_stmt_fetch($stmt);

printf("%s is in district %s\n", $city, $district);

上の例の出力は以下となります。

Amersfoort is in district Utrecht

参考

  • mysqli_stmt_init() - ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す
  • mysqli_stmt_execute() - プリペアドステートメントを実行する
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする
  • mysqli_stmt_bind_result() - 結果を保存するため、プリペアドステートメントに変数をバインドする
  • mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
  • mysqli_stmt_close() - プリペアドステートメントを閉じる


プリペアドステートメントをリセットする

  • ≪ mysqli_stmt::prepare
  • mysqli_stmt::result_metadata ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントをリセットする

mysqli_stmt::reset

mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — プリペアドステートメントをリセットする

説明

オブジェクト指向型

public mysqli_stmt::reset(): bool

手続き型

mysqli_stmt_reset(mysqli_stmt $statement): bool

クライアントおよびサーバーで、実行後のプリペアドステートメントをリセットします。

サーバー上のステートメント、mysqli_stmt_send_long_data() で送信したデータ、バッファリングされていない結果、そして現在のエラーをリセットします。 バインド内容や保存された結果セットはクリアされません。保存された結果がクリアされるのは、 プリペアドステートメントを実行した (あるいは閉じた) ときです。

別のクエリを元にプリペアドステートメントを用意する場合は、 mysqli_stmt_prepare() 関数を使用します。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する


プリペアドステートメントから結果セットのメタデータを返す

  • ≪ mysqli_stmt::reset
  • mysqli_stmt::send_long_data ≫
  • PHP Manual
  • mysqli_stmt
  • プリペアドステートメントから結果セットのメタデータを返す

mysqli_stmt::result_metadata

mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — プリペアドステートメントから結果セットのメタデータを返す

説明

オブジェクト指向型

public mysqli_stmt::result_metadata(): mysqli_result|false

手続き型

mysqli_stmt_result_metadata(mysqli_stmt $statement): mysqli_result|false

mysqli_prepare() に渡したステートメントが 結果セットを返すものであった場合、mysqli_stmt_result_metadata() はオブジェクトを返します。このオブジェクトは、結果のフィールド数や 各フィールドの情報などのメタ情報を取得するために使用可能です。

注意:

メタデータを取得するには、この結果セットポインタを、以下のいずれかの (フィールドベースの) 関数に渡します。

  • mysqli_num_fields()

  • mysqli_fetch_field()

  • mysqli_fetch_field_direct()

  • mysqli_fetch_fields()

  • mysqli_field_count()

  • mysqli_field_seek()

  • mysqli_field_tell()

  • mysqli_free_result()

結果セットは、使用終了後に開放すべきです。そのためには、結果セットを mysqli_free_result() に渡します。

注意:

mysqli_stmt_result_metadata() が返す結果セットには メタデータのみが含まれています。実際の行データは含まれません。行データを 取得するには、ステートメントハンドルを mysqli_stmt_fetch() に渡してください。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

結果のオブジェクトを返します。エラー時には false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "test");

$mysqli->query("DROP TABLE IF EXISTS friends");
$mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

$mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

$stmt = $mysqli->prepare("SELECT id, name FROM friends");
$stmt->execute();

/* メタデータの結果セットを取得します */
$result = $stmt->result_metadata();

/* メタデータ結果セットからフィールド情報を取得します */
$field = $result->fetch_field();

printf("Fieldname: %s\n", $field->name);

/* 結果セットを閉じます */
$result->close();

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "test");

mysqli_query($link, "DROP TABLE IF EXISTS friends");
mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

$stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
mysqli_stmt_execute($stmt);

/* メタデータの結果セットを取得します */
$result = mysqli_stmt_result_metadata($stmt);

/* メタデータ結果セットからフィールド情報を取得します */
$field = mysqli_fetch_field($result);

printf("Fieldname: %s\n", $field->name);

/* 結果セットを閉じます */
mysqli_free_result($result);

/* 接続を閉じます */
mysqli_close($link);
?>

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_free_result() - 結果に関連付けられたメモリを開放する


データをブロックで送信する

  • ≪ mysqli_stmt::result_metadata
  • mysqli_stmt::$sqlstate ≫
  • PHP Manual
  • mysqli_stmt
  • データをブロックで送信する

mysqli_stmt::send_long_data

mysqli_stmt_send_long_data

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — データをブロックで送信する

説明

オブジェクト指向型

public mysqli_stmt::send_long_data(int $param_num, string $data): bool

手続き型

mysqli_stmt_send_long_data(mysqli_stmt $statement, int $param_num, string $data): bool

パラメータのデータを、サーバーに分割して送信します。例えば blob のサイズが max_allowed_packet を越えてしまう場合などに使用します。 この関数は、カラムに文字やバイナリのデータを送信するために複数回 コールすることが可能です。そのカラムの型は TEXT あるいは BLOB である 必要があります。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

param_num

データに関連付けるパラメータを示します。 パラメータの番号は 0 から始まります。

data

送信するデータを含む文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php
$stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
$null = NULL;
$stmt->bind_param("b", $null);
$fp = fopen("messages.txt", "r");
while (!feof($fp)) {
$stmt->send_long_data(0, fread($fp, 8192));
}
fclose($fp);
$stmt->execute();
?>

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_bind_param() - プリペアドステートメントのパラメータに変数をバインドする


直前のステートメントの操作での SQLSTATE エラーを返す

  • ≪ mysqli_stmt::send_long_data
  • mysqli_stmt::store_result ≫
  • PHP Manual
  • mysqli_stmt
  • 直前のステートメントの操作での SQLSTATE エラーを返す

mysqli_stmt::$sqlstate

mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — 直前のステートメントの操作での SQLSTATE エラーを返す

説明

オブジェクト指向型

string $mysqli_stmt->sqlstate;

手続き型

mysqli_stmt_sqlstate(mysqli_stmt $statement): string

直近に実行されたプリペアドステートメントのエラーについて、 SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 つの文字で構成されています。'00000' はエラーが発生しなかったことを意味します。この値は、ANSI SQL および ODBC で定義されています。とりうる値の一覧は » http://dev.mysql.com/doc/mysql/en/error-handling.html を参照ください。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

直前のエラーに関する SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5 文字で構成され、'00000' はエラーが発生しなかったことを意味します。

例

例1 オブジェクト指向型

<?php
/* 接続をオープンします */
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$mysqli->query("CREATE TABLE myCountry LIKE Country");
$mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = $mysqli->prepare($query)) {

/* テーブルを削除します */
$mysqli->query("DROP TABLE myCountry");

/* クエリを実行します */
$stmt->execute();

printf("Error: %s.\n", $stmt->sqlstate);

/* ステートメントを閉じます */
$stmt->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
/* 接続をオープンします */
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

$query = "SELECT Name, Code FROM myCountry ORDER BY Name";
if ($stmt = mysqli_prepare($link, $query)) {

/* テーブルを削除します */
mysqli_query($link, "DROP TABLE myCountry");

/* クエリを実行します */
mysqli_stmt_execute($stmt);

printf("Error: %s.\n", mysqli_stmt_sqlstate($stmt));

/* ステートメントを閉じます */
mysqli_stmt_close($stmt);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Error: 42S02.

注意

注意:

すべての MySQL エラーが SQLSTATE に対応しているわけではないことに 注意してください。そのようなエラーが発生した場合は、 HY000（一般的なエラー）が返されます。

参考

  • mysqli_stmt_errno() - 直近のステートメントのコールに関するエラーコードを返す
  • mysqli_stmt_error() - 直近のステートメントのエラー内容を文字列で返す


内部バッファに結果を保存する

  • ≪ mysqli_stmt::$sqlstate
  • mysqli_result ≫
  • PHP Manual
  • mysqli_stmt
  • 内部バッファに結果を保存する

mysqli_stmt::store_result

mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — 内部バッファに結果を保存する

説明

オブジェクト指向型

public mysqli_stmt::store_result(): bool

手続き型

mysqli_stmt_store_result(mysqli_stmt $statement): bool

有効な結果セットを生成するクエリの場合（SELECT, SHOW, DESCRIBE, EXPLAIN）、かつ 完全な結果セットをバッファリングする必要がある場合のみ、 この関数をコールすべきです。 バッファリングされたデータを取得するには続けて mysqli_stmt_fetch() をコールします。

注意:

その他のクエリでは mysqli_stmt_store_result() をコールする必要はありません。しかし、もしコールしてしまったとしても パフォーマンスへの悪影響は一切ありません。クエリが結果セットを 返すかどうかは、mysqli_stmt_result_metadata() が false を返すかどうかで調べられます。

パラメータ

stmt

手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
$stmt = $mysqli->prepare($query);
$stmt->execute();

/* 結果を内部バッファに保存します */
$stmt->store_result();

printf("Number of rows: %d.\n", $stmt->num_rows);

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
$stmt = mysqli_prepare($link, $query);
mysqli_stmt_execute($stmt);

/* 結果を内部バッファに保存します */
mysqli_stmt_store_result($stmt);

printf("Number of rows: %d.\n", mysqli_stmt_num_rows($stmt));

上の例の出力は以下となります。

Number of rows: 20.

参考

  • mysqli_prepare() - 実行するための SQL文 を準備する
  • mysqli_stmt_result_metadata() - プリペアドステートメントから結果セットのメタデータを返す
  • mysqli_stmt_fetch() - プリペアドステートメントから結果を取得し、バインド変数に格納する


mysqli_result クラス

(PHP 5, PHP 7, PHP 8)

はじめに

データベースへのクエリにより得られた結果セットを表します。

クラス概要

class mysqli_result implements IteratorAggregate {
/* プロパティ */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* メソッド */
public __construct(mysqli $mysql, int $result_mode = MYSQLI_STORE_RESULT)
public data_seek(int $offset): bool
public fetch_all(int $mode = MYSQLI_NUM): array
public fetch_array(int $mode = MYSQLI_BOTH): array|null|false
public fetch_assoc(): array|null|false
public fetch_column(int $column = 0): null|int|float|string|false
public fetch_field(): object|false
public fetch_field_direct(int $index): object|false
public fetch_fields(): array
public fetch_object(string $class = "stdClass", array $constructor_args = []): object|null|false
public fetch_row(): array|null|false
public field_seek(int $index): true
public free(): void
public close(): void
public free_result(): void
public getIterator(): Iterator
}

プロパティ

type

結果セットをバッファリングするか、しないかを整数で設定します。 (バッファリングする場合は MYSQLI_STORE_RESULT を、 しない場合は MYSQLI_USE_RESULT を それぞれ設定します)

変更履歴

バージョン | 説明
8.0.0 | mysqli_result は、 IteratorAggregate を実装するようになりました。 これより前のバージョンでは、 Traversable を実装していました。

目次

  • mysqli_result::__construct — mysqli_result オブジェクトを構築する
  • mysqli_result::$current_field — 結果ポインタにおける現在のフィールドオフセットを取得する
  • mysqli_result::data_seek — 結果の任意の行にポインタを移動する
  • mysqli_result::fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_result::fetch_array — 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_result::fetch_assoc — 結果セットの次の行を連想配列で取得する
  • mysqli_result::fetch_column — 結果セットの次の行から、単一のカラムの値を取得する
  • mysqli_result::fetch_field — 結果セットの次のフィールドを返す
  • mysqli_result::fetch_field_direct — 単一のフィールドのメタデータを取得する
  • mysqli_result::fetch_fields — 結果セットのフィールド情報をオブジェクトの配列で返す
  • mysqli_result::fetch_object — 結果セットの次の行を取得し、オブジェクトとして返す
  • mysqli_result::fetch_row — 結果セットの次の行を数値添字配列で取得する
  • mysqli_result::$field_count — 結果セットのフィールド数を取得する
  • mysqli_result::field_seek — 結果ポインタを、指定したフィールドオフセットに設定する
  • mysqli_result::free — 結果に関連付けられたメモリを開放する
  • mysqli_result::getIterator — 外部イテレータを取得する
  • mysqli_result::$lengths — 結果セットにおける現在の行のカラムの長さを返す
  • mysqli_result::$num_rows — 結果セットの行数を取得する


mysqli_result オブジェクトを構築する

  • ≪ mysqli_result
  • mysqli_result::$current_field ≫
  • PHP Manual
  • mysqli_result
  • mysqli_result オブジェクトを構築する

mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — mysqli_result オブジェクトを構築する

説明

public mysqli_result::__construct(mysqli $mysql, int $result_mode = MYSQLI_STORE_RESULT)

このメソッドは、新しい mysqli_result オブジェクトを構築します。

mysqli_real_query() や mysqli_multi_query() 関数をコールした後に mysqli_result を作成するために使います。 このオブジェクトを手動で作成することは、 mysqli_store_result() や mysqli_use_result() をコールすることと同じです。

パラメータ

link

手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

result_mode

MySQL サーバーから結果をどう返すかを、 以下の定数のいずれかで指定できます。

MYSQLI_STORE_RESULT (デフォルト) - バッファリングされた結果セットを使って、 mysqli_result オブジェクトを作成します。

MYSQLI_USE_RESULT - バッファリングされていない結果セットを使って、 mysqli_result オブジェクトを構築します。 取得されるのを待っている保留中のレコードが存在する限り、 接続はビジーとなり、 それ以後のクエリの呼び出しは Commands out of sync エラーが発生します。 このエラーを避けるには、 全てのレコードをサーバーから取得するか、 mysqli_free_result() をコールして結果セットを破棄しなければいけません。 行を取得するために、接続はオープンしたままでなければいけません。

エラー / 例外

mysqli のエラー報告 (MYSQLI_REPORT_ERROR) が有効になっており、かつ要求された操作が失敗した場合は、警告が発生します。さらに、エラー報告のモードが MYSQLI_REPORT_STRICT に設定されていた場合は、mysqli_sql_exception が代わりにスローされます。

例

例1 mysqli_result オブジェクトを作る

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* Select queries return a result set */
$mysqli->real_query("SELECT Name FROM City LIMIT 10");

$result = new mysqli_result($mysqli);
printf("Select returned %d rows.\n", $result->num_rows);

上の例の出力は、 たとえば以下のようになります。

Select returned 10 rows.

参考

  • mysqli_multi_query() - データベース上でひとつ以上のクエリを実行する
  • mysqli_real_query() - SQL クエリを実行する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する


結果ポインタにおける現在のフィールドオフセットを取得する

  • ≪ mysqli_result::__construct
  • mysqli_result::data_seek ≫
  • PHP Manual
  • mysqli_result
  • 結果ポインタにおける現在のフィールドオフセットを取得する

mysqli_result::$current_field

mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — 結果ポインタにおける現在のフィールドオフセットを取得する

説明

オブジェクト指向型

int $mysqli_result->current_field;

手続き型

mysqli_field_tell(mysqli_result $result): int

直近の mysqli_fetch_field() のコールで使用した フィールドカーソルの位置を返します。この値は mysqli_field_seek() の引数として使用可能です。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

フィールドカーソルの現在のオフセットを返します。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

if ($result = $mysqli->query($query)) {

/* すべてのカラムのフィールド情報を取得します */
while ($finfo = $result->fetch_field()) {

/* フィールドポインタのオフセットを取得します */
$currentfield = $result->current_field;

printf("Column %d:\n", $currentfield);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

if ($result = mysqli_query($link, $query)) {

/* すべてのカラムのフィールド情報を取得します */
while ($finfo = mysqli_fetch_field($result)) {

/* フィールドポインタのオフセットを取得します */
$currentfield = mysqli_field_tell($result);

printf("Column %d:\n", $currentfield);
printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Column 1:
Name:     Name
Table:    Country
max. Len: 11
Flags:    1
Type:     254

Column 2:
Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

参考

  • mysqli_fetch_field() - 結果セットの次のフィールドを返す
  • mysqli_field_seek() - 結果ポインタを、指定したフィールドオフセットに設定する


結果の任意の行にポインタを移動する

  • ≪ mysqli_result::$current_field
  • mysqli_result::fetch_all ≫
  • PHP Manual
  • mysqli_result
  • 結果の任意の行にポインタを移動する

mysqli_result::data_seek

mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — 結果の任意の行にポインタを移動する

説明

オブジェクト指向型

public mysqli_result::data_seek(int $offset): bool

手続き型

mysqli_data_seek(mysqli_result $result, int $offset): bool

mysqli_data_seek() 関数は、 結果セットの任意の行 offset にポインタを移動します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

offset

行のオフセット。ゼロから全行数 - 1 までの間 （0..mysqli_num_rows() - 1）である必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysqli::data_seek() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name";
$result = $mysqli->query($query);

/* 401 番目の行にシークします */
$result->data_seek(400);

/* 1行取得します */
$row = $result->fetch_row();

printf("City: %s Countrycode: %s\n", $row[0], $row[1]);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name";

$result = mysqli_query($link, $query);

/* 401 番目の行にシークします */
mysqli_data_seek($result, 400);

/* 1行取得します */
$row = mysqli_fetch_row($result);

printf ("City: %s Countrycode: %s\n", $row[0], $row[1]);

上の例の出力は以下となります。

City: Benin City  Countrycode: NGA

例2 繰り返し処理を行う際に、結果セットのポインタを調整する

この関数は、 結果セットに対して処理を繰り返す時にカスタムの順序に並び替えたり、 結果セット全体に複数回処理を繰り返す時に、 結果セットを巻き戻すのに便利です。

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 15,4";
$result = $mysqli->query($query);

/* 結果セットを逆順に処理します */
for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
$result->data_seek($row_no);

/* 1行取得します */
$row = $result->fetch_row();

printf("City: %s Countrycode: %s\n", $row[0], $row[1]);
}

/* 結果セットの最初にポインタをリセットします */
$result->data_seek(0);

print "\n";

/* 同じ結果セットを再度処理します */
while ($row = $result->fetch_row()) {
printf("City: %s Countrycode: %s\n", $row[0], $row[1]);
}

上の例の出力は以下となります。

City: Acmbaro  Countrycode: MEX
City: Abuja  Countrycode: NGA
City: Abu Dhabi  Countrycode: ARE
City: Abottabad  Countrycode: PAK

City: Abottabad  Countrycode: PAK
City: Abu Dhabi  Countrycode: ARE
City: Abuja  Countrycode: NGA
City: Acmbaro  Countrycode: MEX

注意

注意:

この関数は、mysqli_store_result()、
mysqli_query()、
mysqli_stmt_get_result()
によって取得した、
バッファリングされた結果に対してのみ使えます。

参考

  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_fetch_row() - 結果セットの次の行を数値添字配列で取得する
  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_assoc() - 結果セットの次の行を連想配列で取得する
  • mysqli_fetch_object() - 結果セットの次の行を取得し、オブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_num_rows() - 結果セットの行数を取得する


結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

  • ≪ mysqli_result::data_seek
  • mysqli_result::fetch_array ≫
  • PHP Manual
  • mysqli_result
  • 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

mysqli_result::fetch_all

mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_all(int $mode = MYSQLI_NUM): array

手続き型

mysqli_fetch_all(mysqli_result $result, int $mode = MYSQLI_NUM): array

すべての結果の行を取得し、その結果セットを 連想配列・数値添字配列あるいはその両方の二次元配列で返します。

注意:

PHP 8.1.0 より前のバージョンでは、 この関数は mysqlnd でのみ利用可能でした。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

mode

このオプションは、 結果の行データから返す配列の型を指定します。ここで指定可能な値は 定数 MYSQLI_ASSOC、 MYSQLI_NUM あるいは MYSQLI_BOTH. のいずれかです。

戻り値

結果の行を含む連想配列あるいは数値添字配列の配列を返します。

変更履歴

バージョン | 説明
8.1.0 | libmysqlclient をリンクしている場合でも、 この関数を使えるようになりました。

例

例1 mysqli_result::fetch_all() の例

オブジェクト指向型

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
$result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
$rows = $result->fetch_all(MYSQLI_ASSOC);
foreach ($rows as $row) {
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}

手続き型

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
$result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");
$rows = mysqli_fetch_all($result, MYSQLI_ASSOC);
foreach ($rows as $row) {
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}

上の例の出力は以下となります。

Kabul (AFG)
Qandahar (AFG)
Herat (AFG)

参考

  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_column() - 結果セットの次の行から、単一のカラムの値を取得する
  • mysqli_query() - データベース上でクエリを実行する


結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する

  • ≪ mysqli_result::fetch_all
  • mysqli_result::fetch_assoc ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する

mysqli_result::fetch_array

mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_array(int $mode = MYSQLI_BOTH): array|null|false

手続き型

mysqli_fetch_array(mysqli_result $result, int $mode = MYSQLI_BOTH): array|null|false

結果セットから1行取得し、それを配列として返します。 値を取得した後は、この関数をコールするたびに結果セットの次の行の値を返します 結果セットに対して行がなければ、null を返します。

データを数値添字の 配列に格納することに加えて、この関数は 結果セットのフィールド名をキーとする連想配列にもデータを格納できます。

もし2つ以上のカラムが同じ名前であった場合は、最後に現れた カラムが優先され、以前のあらゆるデータを上書きします。同名の複数のカラムに アクセスする場合、数値添字版の行データを使用しなければなりません。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

mode

このオプションは、 結果の行データから返す配列の型を指定します。ここで指定可能な値は 定数 MYSQLI_ASSOC、 MYSQLI_NUM あるいは MYSQLI_BOTH. のいずれかです。

MYSQLI_ASSOC 定数を指定すると、この関数は mysqli_fetch_assoc() と同じ結果を返します。一方 MYSQLI_NUM を指定すると、mysqli_fetch_row() 関数と同じ結果となります。最後の MYSQLI_BOTH を指定すると、 ひとつの配列にこれら両方の属性を含めます。

戻り値

取得した行を表す値の配列を返します。結果セットにもう行がない場合には null を返します。失敗した場合に false を返します

例

例1 mysqli_result::fetch_array() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3";
$result = $mysqli->query($query);

/* 数値添字配列 */
$row = $result->fetch_array(MYSQLI_NUM);
printf("%s (%s)\n", $row[0], $row[1]);

/* 連想配列 */
$row = $result->fetch_array(MYSQLI_ASSOC);
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

/* 連想配列および数値添字配列 */
$row = $result->fetch_array(MYSQLI_BOTH);
printf("%s (%s)\n", $row[0], $row["CountryCode"]);

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
$result = mysqli_query($mysqli, $query);

/* 数値添字配列 */
$row = mysqli_fetch_array($result, MYSQLI_NUM);
printf("%s (%s)\n", $row[0], $row[1]);

/* 連想配列 */
$row = mysqli_fetch_array($result, MYSQLI_ASSOC);
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

/* 連想配列および数値添字配列 */
$row = mysqli_fetch_array($result, MYSQLI_BOTH);
printf("%s (%s)\n", $row[0], $row["CountryCode"]);

上の例の出力は、 たとえば以下のようになります。

Kabul (AFG)
Qandahar (AFG)
Herat (AFG)

参考

  • mysqli_fetch_assoc() - 結果セットの次の行を連想配列で取得する
  • mysqli_fetch_column() - 結果セットの次の行から、単一のカラムの値を取得する
  • mysqli_fetch_row() - 結果セットの次の行を数値添字配列で取得する
  • mysqli_fetch_object() - 結果セットの次の行を取得し、オブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する


結果セットの次の行を連想配列で取得する

  • ≪ mysqli_result::fetch_array
  • mysqli_result::fetch_column ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次の行を連想配列で取得する

mysqli_result::fetch_assoc

mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — 結果セットの次の行を連想配列で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_assoc(): array|null|false

手続き型

mysqli_fetch_assoc(mysqli_result $result): array|null|false

結果セットから1行取得し、それを連想配列として返します。 値を取得した後は、この関数をコールするたびに結果セットの次の行の値を返します。 もう結果セットに行がない場合には null を返します。

もし2つ以上のカラムが同じ名前であった場合は、最後に現れた カラムが優先され、以前のあらゆるデータを上書きします。同名の複数のカラムに アクセスする場合、mysqli_fetch_row() を用いて 数値添字配列を使用するか、あるいは SQL クエリ中の SELECT リストに異なる名前を与えるために、カラムにエイリアスを指定する 必要があります。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

取得した行を表す連想配列を返します。 連想配列の各キーが、結果セットのカラムを表します。 結果セットにもう行がない場合には null を返します。 失敗した場合に false を返します

例

例1 mysqli_result::fetch_assoc() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

$result = $mysqli->query($query);

/* 連想配列を取得します */
while ($row = $result->fetch_assoc()) {
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

$result = mysqli_query($mysqli, $query);

/* 連想配列を取得します */
while ($row = mysqli_fetch_assoc($result)) {
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}

上の例の出力は、 たとえば以下のようになります。

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

例2 mysqli_result, iterator, mysqli_result::fetch_assoc() の使い方の比較

mysqli_result は、foreach を使って繰り返し処理をすることができます。 結果セットは、現在の位置に関わらず、最初の行から処理されます。

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = 'SELECT Name, CountryCode FROM City ORDER BY ID DESC';

// イテレータを使う場合
$result = $mysqli->query($query);
foreach ($result as $row) {
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}

echo "\n==================\n";

// イテレータを使わない場合
$result = $mysqli->query($query);
while ($row = $result->fetch_assoc()) {
printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
}

上の例の出力は、 たとえば以下のようになります。

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

==================
Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

参考

  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_column() - 結果セットの次の行から、単一のカラムの値を取得する
  • mysqli_fetch_row() - 結果セットの次の行を数値添字配列で取得する
  • mysqli_fetch_object() - 結果セットの次の行を取得し、オブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する


結果セットの次の行から、単一のカラムの値を取得する

  • ≪ mysqli_result::fetch_assoc
  • mysqli_result::fetch_field ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次の行から、単一のカラムの値を取得する

mysqli_result::fetch_column

mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — 結果セットの次の行から、単一のカラムの値を取得する

説明

オブジェクト指向型

public mysqli_result::fetch_column(int $column = 0): null|int|float|string|false

手続き型

mysqli_fetch_column(mysqli_result $result, int $column = 0): null|int|float|string|false

結果セットから1行取得し、 0から始まるインデックスで指定されたカラムの値を返します。 値を取得した後は、この関数をコールするたびに結果セットの次の行の値を返します。 行がもう存在しない場合は false を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

column

行から取得する、0から始まるカラムの番号。 値を指定しない場合は、最初のカラムの値が返されます。

戻り値

結果セットの次の行から、単一カラムの値を返します。 もう行が存在しない場合は false を返します。

警告

この関数を使ってデータを取得する場合、同じ行から別のカラムの値を取得する方法はありません。

例

例1 mysqli_result::fetch_column() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

$result = $mysqli->query($query);

/* fetch a single value from the second column */
while ($Name = $result->fetch_column(1)) {
printf("%s\n", $Name);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

$result = mysqli_query($mysqli, $query);

/* fetch a single value from the second column */
while ($Name = mysqli_fetch_column($result, 1)) {
printf("%s\n", $Name);
}

上の例の出力は、 たとえば以下のようになります。

Rafah
Nablus
Jabaliya
Hebron
Khan Yunis

参考

  • mysqli_fetch_all() - 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_assoc() - 結果セットの次の行を連想配列で取得する
  • mysqli_fetch_object() - 結果セットの次の行を取得し、オブジェクトとして返す
  • mysqli_fetch_row() - 結果セットの次の行を数値添字配列で取得する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する


結果セットの次のフィールドを返す

  • ≪ mysqli_result::fetch_column
  • mysqli_result::fetch_field_direct ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次のフィールドを返す

mysqli_result::fetch_field

mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — 結果セットの次のフィールドを返す

説明

オブジェクト指向型

public mysqli_result::fetch_field(): object|false

手続き型

mysqli_fetch_field(mysqli_result $result): object|false

結果セットから ひとつのカラムの情報をオブジェクトとして返します。この関数を 繰り返しコールすることで、結果セットのすべてのカラムについての情報が 取得可能です。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

フィールド定義情報を含むオブジェクトを返します。もし フィールドの情報が取得できない場合は、false を返します。

オブジェクトのプロパティ
プロパティ | 説明
name | カラムの名前。
orgname | エイリアスが指定されている場合の、本来の名前。
table | フィールドが属するテーブルの名前 (演算をしていない場合)。
orgtable | エイリアスが指定されている場合の、本来のテーブル名。
def | 未使用。常に空文字列になります。
db | データベースの名前。
catalog | 未使用。常に "def" になります。
max_length | 結果セットにおけるフィールドの最大幅。PHP 8.1 以降では、この値は常に 0 です。
length | テーブルの定義で指定されているフィールド幅 (バイト単位)。 文字列型のカラムの場合、 値の長さは接続の文字セットによって異なります。 たとえば文字セットが latin1、 つまりシングルバイトの文字セットの場合、 クエリ SELECT 'abc' の値の長さは3になります。 一方で文字セットが utf8mb4 の場合、 つまりマルチバイトの文字セットの場合、 文字は4バイトまでの長さをとります。値の長さは12になります。
charsetnr | フィールドの文字セット番号。
flags | フィールドのビットフラグを整数型で表す。
type | フィールドのデータ型。
decimals | 数値型のフィールドの場合の桁数。時間フィールドの場合は、秒単位の精度。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

if ($result = $mysqli->query($query)) {

/* すべてのカラムのフィールド情報を取得します */
while ($finfo = $result->fetch_field()) {

printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

if ($result = mysqli_query($link, $query)) {

/* すべてのカラムのフィールド情報を取得します */
while ($finfo = mysqli_fetch_field($result)) {

printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);
}
mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Name:     Name
Table:    Country
max. Len: 11
Flags:    1
Type:     254

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

参考

  • mysqli_num_fields() - 結果セットのフィールド数を取得する
  • mysqli_fetch_field_direct() - 単一のフィールドのメタデータを取得する
  • mysqli_fetch_fields() - 結果セットのフィールド情報をオブジェクトの配列で返す
  • mysqli_field_seek() - 結果ポインタを、指定したフィールドオフセットに設定する


単一のフィールドのメタデータを取得する

  • ≪ mysqli_result::fetch_field
  • mysqli_result::fetch_fields ≫
  • PHP Manual
  • mysqli_result
  • 単一のフィールドのメタデータを取得する

mysqli_result::fetch_field_direct

mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — 単一のフィールドのメタデータを取得する

説明

オブジェクト指向型

public mysqli_result::fetch_field_direct(int $index): object|false

手続き型

mysqli_fetch_field_direct(mysqli_result $result, int $index): object|false

指定した結果セットから、フィールド定義情報を含むオブジェクトを返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

index

フィールド番号。この値は 0 から フィールド数 - 1 までの範囲でなければなりません。

戻り値

フィールド定義情報を含むオブジェクトを返します。もし、指定した index のフィールドの情報が取得できない場合は false を返します。

オブジェクトのプロパティ
プロパティ | 説明
name | カラムの名前。
orgname | エイリアスが指定されている場合の、本来の名前。
table | フィールドが属するテーブルの名前 (演算をしていない場合)。
orgtable | エイリアスが指定されている場合の、本来のテーブル名。
def | 未使用。常に空文字列になります。
db | データベースの名前。
catalog | 未使用。常に "def" になります。
max_length | 結果セットにおけるフィールドの最大幅。PHP 8.1 以降では、この値は常に 0 です。
length | テーブルの定義で指定されているフィールド幅 (バイト単位)。 文字列型のカラムの場合、 値の長さは接続の文字セットによって異なります。 たとえば文字セットが latin1、 つまりシングルバイトの文字セットの場合、 クエリ SELECT 'abc' の値の長さは3になります。 一方で文字セットが utf8mb4 の場合、 つまりマルチバイトの文字セットの場合、 文字は4バイトまでの長さをとります。値の長さは12になります。
charsetnr | フィールドの文字セット番号。
flags | フィールドのビットフラグを整数型で表す。
type | フィールドのデータ型。
decimals | 数値型のフィールドの場合の桁数。時間フィールドの場合は、秒単位の精度。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

if ($result = $mysqli->query($query)) {

/* カラム 'SurfaceArea' のフィールド情報を取得します */
$finfo = $result->fetch_field_direct(1);

printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n", $finfo->type);

$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

if ($result = mysqli_query($link, $query)) {

/* カラム 'SurfaceArea' のフィールド情報を取得します */
$finfo = mysqli_fetch_field_direct($result, 1);

printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n", $finfo->type);

mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

参考

  • mysqli_num_fields() - 結果セットのフィールド数を取得する
  • mysqli_fetch_field() - 結果セットの次のフィールドを返す
  • mysqli_fetch_fields() - 結果セットのフィールド情報をオブジェクトの配列で返す


結果セットのフィールド情報をオブジェクトの配列で返す

  • ≪ mysqli_result::fetch_field_direct
  • mysqli_result::fetch_object ≫
  • PHP Manual
  • mysqli_result
  • 結果セットのフィールド情報をオブジェクトの配列で返す

mysqli_result::fetch_fields

mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — 結果セットのフィールド情報をオブジェクトの配列で返す

説明

オブジェクト指向型

public mysqli_result::fetch_fields(): array

手続き型

mysqli_fetch_fields(mysqli_result $result): array

この関数は mysqli_fetch_field() 関数と同じ目的で 使用しますが、ひとつ違いがあります。一度にひとつずつフィールド情報を 取得するのではなく、複数のカラムの情報をオブジェクトの配列で返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

フィールド定義情報を含むオブジェクトの配列を返します。

オブジェクトのプロパティ
プロパティ | 説明
name | カラムの名前。
orgname | エイリアスが指定されている場合の、本来の名前。
table | フィールドが属するテーブルの名前 (演算をしていない場合)。
orgtable | エイリアスが指定されている場合の、本来のテーブル名。
def | 未使用。常に空文字列になります。
db | データベースの名前。
catalog | 未使用。常に "def" になります。
max_length | 結果セットにおけるフィールドの最大幅。PHP 8.1 以降では、この値は常に 0 です。
length | テーブルの定義で指定されているフィールド幅 (バイト単位)。 文字列型のカラムの場合、 値の長さは接続の文字セットによって異なります。 たとえば文字セットが latin1、 つまりシングルバイトの文字セットの場合、 クエリ SELECT 'abc' の値の長さは3になります。 一方で文字セットが utf8mb4 の場合、 つまりマルチバイトの文字セットの場合、 文字は4バイトまでの長さをとります。値の長さは12になります。
charsetnr | フィールドの文字セット番号。
flags | フィールドのビットフラグを整数型で表す。
type | フィールドのデータ型。
decimals | 数値型のフィールドの場合の桁数。時間フィールドの場合は、秒単位の精度。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

/* 接続状況をチェックします */
if ($mysqli->connect_errno) {
printf("Connect failed: %s\n", $mysqli->connect_error);
exit();
}

foreach (array('latin1', 'utf8') as $charset) {

// 文字セットを設定します。これは、バイト単位の長さなどいくつかの値に影響を及ぼします
$mysqli->set_charset($charset);

$query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

echo "======================\n";
echo "Character Set: $charset\n";
echo "======================\n";

if ($result = $mysqli->query($query)) {

/* すべてのカラムのフィールド情報を取得します */
$finfo = $result->fetch_fields();

foreach ($finfo as $val) {
printf("Name: %s\n", $val->name);
printf("Table: %s\n", $val->table);
printf("Max. Len: %d\n", $val->max_length);
printf("Length: %d\n", $val->length);
printf("charsetnr: %d\n", $val->charsetnr);
printf("Flags: %d\n", $val->flags);
printf("Type: %d\n\n", $val->type);
}
$result->free();
}
}
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

foreach (array('latin1', 'utf8') as $charset) {

// 文字セットを設定します。これは、バイト単位の長さなどいくつかの値に影響を及ぼします
mysqli_set_charset($link, $charset);

$query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

echo "======================\n";
echo "Character Set: $charset\n";
echo "======================\n";

if ($result = mysqli_query($link, $query)) {

/* すべてのカラムのフィールド情報を取得します */
$finfo = mysqli_fetch_fields($result);

foreach ($finfo as $val) {
printf("Name: %s\n", $val->name);
printf("Table: %s\n", $val->table);
printf("Max. Len: %d\n", $val->max_length);
printf("Length: %d\n", $val->length);
printf("charsetnr: %d\n", $val->charsetnr);
printf("Flags: %d\n", $val->flags);
printf("Type: %d\n\n", $val->type);
}
mysqli_free_result($result);
}
}

mysqli_close($link);
?>

上の例の出力は以下となります。

======================
Character Set: latin1
======================
Name:      actor_id
Table:     actor
Max. Len:  3
Length:    5
charsetnr: 63
Flags:     49699
Type:      2

Name:      last_name
Table:     actor
Max. Len:  12
Length:    45
charsetnr: 8
Flags:     20489
Type:      253

======================
Character Set: utf8
======================
Name:      actor_id
Table:     actor
Max. Len:  3
Length:    5
charsetnr: 63
Flags:     49699
Type:      2

Name:      last_name
Table:     actor
Max. Len:  12
Length:    135
charsetnr: 33
Flags:     20489

参考

  • mysqli_num_fields() - 結果セットのフィールド数を取得する
  • mysqli_fetch_field_direct() - 単一のフィールドのメタデータを取得する
  • mysqli_fetch_field() - 結果セットの次のフィールドを返す


結果セットの次の行を取得し、オブジェクトとして返す

  • ≪ mysqli_result::fetch_fields
  • mysqli_result::fetch_row ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次の行を取得し、オブジェクトとして返す

mysqli_result::fetch_object

mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — 結果セットの次の行を取得し、オブジェクトとして返す

説明

オブジェクト指向型

public mysqli_result::fetch_object(string $class = "stdClass", array $constructor_args = []): object|null|false

手続き型

mysqli_fetch_object(mysqli_result $result, string $class = "stdClass", array $constructor_args = []): object|null|false

結果セットから1行取得し、それをオブジェクトとして返します。 このオブジェクトは、結果セットのカラム名をプロパティとして持ちます。 値を取得した後は、この関数をコールするたびに結果セットの次の行の値を返します。 もう結果セットに行がない場合には null を返します。

もし2つ以上のカラムが同じ名前であった場合は、最後に現れた カラムが優先され、以前のあらゆるデータを上書きします。同名の複数のカラムに アクセスする場合、mysqli_fetch_row() を用いて 数値添字配列を使用するか、あるいは SQL クエリ中の SELECT リストに異なる名前を与えるために、カラムにエイリアスを指定する 必要があります。

注意: この関数がオブジェクトのプロパティを設定するのは、 オブジェクトのコンストラクタをコールする前であることに注意しましょう。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

class

インスタンス化してプロパティを設定後に返すクラスの名前。 省略した場合は stdClass オブジェクトを返します。

constructor_args

オプションのパラメータの配列で、 class オブジェクトのコンストラクタに渡します。

戻り値

取得した行を表すオブジェクトを返します。 これは、個別のプロパティが結果セットのカラム名を表します。 結果セットにもう行がない場合には null を返します。 失敗した場合に false を返します

エラー / 例外

constructor_args が空でないのに、 そのクラスがコンストラクタを持たない場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | constructor_args が空でないのに、 そのクラスがコンストラクタを持たない場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 Exception がスローされていました。
8.0.0 | constructor_args は、 引数を指定しない場合に [] を受け入れるようになりました。 これより前のバージョンでは、例外がスローされていました。

例

例1 mysqli_result::fetch_object() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

$result = $mysqli->query($query);

while ($obj = $result->fetch_object()) {
printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

$result = mysqli_query($link, $query);

while ($obj = mysqli_fetch_object($result)) {
printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
}

上の例の出力は、 たとえば以下のようになります。

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

参考

  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_assoc() - 結果セットの次の行を連想配列で取得する
  • mysqli_fetch_column() - 結果セットの次の行から、単一のカラムの値を取得する
  • mysqli_fetch_row() - 結果セットの次の行を数値添字配列で取得する
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する


結果セットの次の行を数値添字配列で取得する

  • ≪ mysqli_result::fetch_object
  • mysqli_result::$field_count ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの次の行を数値添字配列で取得する

mysqli_result::fetch_row

mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — 結果セットの次の行を数値添字配列で取得する

説明

オブジェクト指向型

public mysqli_result::fetch_row(): array|null|false

手続き型

mysqli_fetch_row(mysqli_result $result): array|null|false

結果セットからデータを 1 行取得し、それを数値添字の配列で 返します。各カラムは 0（ゼロ）から始まる添字に格納されます。 mysqli_fetch_row() 関数を続けてコールすると、 結果セットの次の行を返します。もう行がない場合には null を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

mysqli_fetch_row() は取得した行のカラムを列挙した配列を 返します。結果セットにもう行がない場合には null を返します。 失敗した場合に false を返します

例

例1 mysqli_result::fetch_row() の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

$result = $mysqli->query($query);

/* オブジェクトの配列を取得します */
while ($row = $result->fetch_row()) {
printf("%s (%s)\n", $row[0], $row[1]);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

$result = mysqli_query($mysqli, $query);

/* 連想配列を取得します */
while ($row = mysqli_fetch_row($result)) {
printf("%s (%s)\n", $row[0], $row[1]);
}

上の例の出力は、 たとえば以下のようになります。

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

参考

  • mysqli_fetch_array() - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
  • mysqli_fetch_assoc() - 結果セットの次の行を連想配列で取得する
  • mysqli_fetch_column() - 結果セットの次の行から、単一のカラムの値を取得する
  • mysqli_fetch_object() - 結果セットの次の行を取得し、オブジェクトとして返す
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_data_seek() - 結果の任意の行にポインタを移動する


結果セットのフィールド数を取得する

  • ≪ mysqli_result::fetch_row
  • mysqli_result::field_seek ≫
  • PHP Manual
  • mysqli_result
  • 結果セットのフィールド数を取得する

mysqli_result::$field_count

mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — 結果セットのフィールド数を取得する

説明

オブジェクト指向型

int $mysqli_result->field_count;

手続き型

mysqli_num_fields(mysqli_result $result): int

結果セットからフィールドの数を返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

フィールド数を数値で返します。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$result = $mysqli->query("SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

/* 結果セットのフィールド数を取得します*/
$field_cnt = $result->field_count;

printf("Result set has %d fields.\n", $field_cnt);

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$result = mysqli_query($link, "SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

/* 結果セットのフィールド数を取得します*/
$field_cnt = mysqli_num_fields($result);

printf("Result set has %d fields.\n", $field_cnt);

上の例の出力は以下となります。

Result set has 4 fields.

参考

  • mysqli_fetch_field() - 結果セットの次のフィールドを返す


結果ポインタを、指定したフィールドオフセットに設定する

  • ≪ mysqli_result::$field_count
  • mysqli_result::free ≫
  • PHP Manual
  • mysqli_result
  • 結果ポインタを、指定したフィールドオフセットに設定する

mysqli_result::field_seek

mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — 結果ポインタを、指定したフィールドオフセットに設定する

説明

オブジェクト指向型

public mysqli_result::field_seek(int $index): true

手続き型

mysqli_field_seek(mysqli_result $result, int $index): true

フィールドカーソルを指定したオフセットに設定します。 mysqli_fetch_field() を次にコールした際に、 設定したオフセットに関連するカラムのフィールド定義を取得します。

注意:

行のはじめに移動するには、オフセットとしてゼロを指定します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

index

フィールド番号。これは 0 から フィールド数 - 1 までの範囲でなければなりません。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

if ($result = $mysqli->query($query)) {

/* 2 番目のカラムのフィールド情報を取得します */
$result->field_seek(1);
$finfo = $result->fetch_field();

printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);

$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

if ($result = mysqli_query($link, $query)) {

/* 2 番目のカラムのフィールド情報を取得します */
mysqli_field_seek($result, 1);
$finfo = mysqli_fetch_field($result);

printf("Name: %s\n", $finfo->name);
printf("Table: %s\n", $finfo->table);
printf("max. Len: %d\n", $finfo->max_length);
printf("Flags: %d\n", $finfo->flags);
printf("Type: %d\n\n", $finfo->type);

mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

参考

  • mysqli_fetch_field() - 結果セットの次のフィールドを返す


結果に関連付けられたメモリを開放する

  • ≪ mysqli_result::field_seek
  • mysqli_result::getIterator ≫
  • PHP Manual
  • mysqli_result
  • 結果に関連付けられたメモリを開放する

mysqli_result::free

mysqli_result::close

mysqli_result::free_result

mysqli_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — 結果に関連付けられたメモリを開放する

説明

オブジェクト指向型

public mysqli_result::free(): void
public mysqli_result::close(): void
public mysqli_result::free_result(): void

手続き型

mysqli_free_result(mysqli_result $result): void

結果に関連付けられたメモリを開放します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

値を返しません。

参考

  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_stmt_store_result() - 内部バッファに結果を保存する
  • mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する


外部イテレータを取得する

  • ≪ mysqli_result::free
  • mysqli_result::$lengths ≫
  • PHP Manual
  • mysqli_result
  • 外部イテレータを取得する

mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — 外部イテレータを取得する

説明

public mysqli_result::getIterator(): Iterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


結果セットにおける現在の行のカラムの長さを返す

  • ≪ mysqli_result::getIterator
  • mysqli_result::$num_rows ≫
  • PHP Manual
  • mysqli_result
  • 結果セットにおける現在の行のカラムの長さを返す

mysqli_result::$lengths

mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — 結果セットにおける現在の行のカラムの長さを返す

説明

オブジェクト指向型

?array $mysqli_result->lengths;

手続き型

mysqli_fetch_lengths(mysqli_result $result): array|false

mysqli_fetch_lengths() 関数は、result が指す結果セットの現在の行について、すべてのカラムの長さを含む 配列を返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

各カラムのサイズ（終端の null 文字は含みません）を表す整数の配列を 返します。エラー時には false を返します。

mysqli_fetch_lengths() は、結果セットの現在の行に ついてのみ有効です。mysqli_fetch_row/array/object をコールする前、あるいは 結果のすべての行を取得した後にこの関数をコールすると、false を返します。

例

例1 オブジェクト指向型

<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT * from Country ORDER BY Code LIMIT 1";

if ($result = $mysqli->query($query)) {

$row = $result->fetch_row();

/* カラムの長さを表示します */
foreach ($result->lengths as $i => $val) {
printf("Field %2d has Length %2d\n", $i+1, $val);
}
$result->close();
}

/* 接続を閉じます */
$mysqli->close();
?>

例2 手続き型

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* 接続状況をチェックします */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}

$query = "SELECT * from Country ORDER BY Code LIMIT 1";

if ($result = mysqli_query($link, $query)) {

$row = mysqli_fetch_row($result);

/* カラムの長さを表示します */
foreach (mysqli_fetch_lengths($result) as $i => $val) {
printf("Field %2d has Length %2d\n", $i+1, $val);
}
mysqli_free_result($result);
}

/* 接続を閉じます */
mysqli_close($link);
?>

上の例の出力は以下となります。

Field  1 has Length  3
Field  2 has Length  5
Field  3 has Length 13
Field  4 has Length  9
Field  5 has Length  6
Field  6 has Length  1
Field  7 has Length  6
Field  8 has Length  4
Field  9 has Length  6
Field 10 has Length  6
Field 11 has Length  5
Field 12 has Length 44
Field 13 has Length  7
Field 14 has Length  3
Field 15 has Length  2


結果セットの行数を取得する

  • ≪ mysqli_result::$lengths
  • mysqli_driver ≫
  • PHP Manual
  • mysqli_result
  • 結果セットの行数を取得する

mysqli_result::$num_rows

mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — 結果セットの行数を取得する

説明

オブジェクト指向型

int|string $mysqli_result->num_rows;

手続き型

mysqli_num_rows(mysqli_result $result): int|string

結果セットの行数を返します。

mysqli_num_rows() の振る舞いは、 結果セットをバッファに格納しているかどうかに依存します。 この関数は、結果セットをバッファに格納していない場合、 全ての行をサーバーから取得していない限り 0 を返します。

パラメータ

result

手続き型のみ: mysqli_query()、mysqli_store_result()、mysqli_use_result()、mysqli_stmt_get_result() が返す mysqli_result オブジェクト。

戻り値

取得した行の数を数値で返します。 結果セットをバッファしないモードの場合、 全ての行をサーバーから取得していない限り 0 を返します。

注意:

行数が PHP_INT_MAX より大きい場合、 行数の数値は文字列で返されます。

例

例1 オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name");

/* 結果セットの行数を取得します */
$row_cnt = $result->num_rows;

printf("Result set has %d rows.\n", $row_cnt);

例2 手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name");

/* 結果セットの行数を取得します */
$row_cnt = mysqli_num_rows($result);

printf("Result set has %d rows.\n", $row_cnt);

上の例の出力は以下となります。

Result set has 239 rows.

注意

注意:

mysqli_stmt_num_rows() と異なり、 この関数にはオブジェクト指向のメソッドがありません。 オブジェクト指向のやり方の場合、getter のプロパティ (mysqli_result::$num_rows) を使って下さい。

参考

  • mysqli_affected_rows() - 直前の MySQL の操作で変更された行の数を得る
  • mysqli_store_result() - 直近のクエリから結果セットを転送する
  • mysqli_use_result() - 結果セットの取得を開始する
  • mysqli_query() - データベース上でクエリを実行する
  • mysqli_stmt_num_rows() - サーバーから取得した結果セットの行数を返す


mysqli_driver クラス

(PHP 5, PHP 7, PHP 8)

はじめに

mysqli_driver クラスは、monostate パターンのインスタンスです。 つまり、任意の数の mysqli_driver インスタンスからアクセスできるドライバはたったひとつということです。

クラス概要

final class mysqli_driver {
/* プロパティ */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

プロパティ

client_info

クライアント API ヘッダのバージョン

client_version

クライアントのバージョン

driver_version

MySQLi ドライバのバージョン

警告

このプロパティは、PHP 8.1.0 で 非推奨 になります。このプロパティに頼らないことを強く推奨します。

embedded

MySQLi Embedded のサポートが有効かどうか

警告

このプロパティは、PHP 8.0.0 で 削除 されました。

reconnect

再接続を許可するかどうか (INI 設定 mysqli.reconnect を参照ください)

警告

このプロパティは、INI ディレクティブ mysqli.reconnect と一緒に、PHP 8.2.0 で 削除されました。

report_mode

MYSQLI_REPORT_OFF、 MYSQLI_REPORT_ALL あるいは以下の MYSQLI_REPORT_STRICT (エラー時に例外をスローする)、 MYSQLI_REPORT_ERROR (エラーを報告する) および MYSQLI_REPORT_INDEX (インデックス関連のエラーを報告する) の組み合わせを設定します。 mysqli_report() も参照ください。

変更履歴

バージョン | 説明
8.2.0 | mysqli_driver::$reconnect が削除されました。
8.1.0 | mysqli_driver::$driver_version は推奨されなくなりました。
8.0.0 | mysqli_driver::$embedded が削除されました。
7.4.0 | mysqli_driver::embedded_server_start() と mysqli_driver:embedded_server_end() が削除されました。

目次

  • mysqli_driver::embedded_server_end — 組み込みサーバーを停止する
  • mysqli_driver::embedded_server_start — 組み込みサーバーを初期化して開始する
  • mysqli_driver::$report_mode — mysqli のエラー報告モードを設定する


組み込みサーバーを停止する

  • ≪ mysqli_driver
  • mysqli_driver::embedded_server_start ≫
  • PHP Manual
  • mysqli_driver
  • 組み込みサーバーを停止する

mysqli_driver::embedded_server_end

mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — 組み込みサーバーを停止する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

オブジェクト指向型

public mysqli_driver::embedded_server_end(): void

手続き型

mysqli_embedded_server_end(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


組み込みサーバーを初期化して開始する

  • ≪ mysqli_driver::embedded_server_end
  • mysqli_driver::$report_mode ≫
  • PHP Manual
  • mysqli_driver
  • 組み込みサーバーを初期化して開始する

mysqli_driver::embedded_server_start

mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — 組み込みサーバーを初期化して開始する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

オブジェクト指向型

public mysqli_driver::embedded_server_start(int $start, array $arguments, array $groups): bool

手続き型

mysqli_embedded_server_start(int $start, array $arguments, array $groups): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


mysqli のエラー報告モードを設定する

  • ≪ mysqli_driver::embedded_server_start
  • mysqli_warning ≫
  • PHP Manual
  • mysqli_driver
  • mysqli のエラー報告モードを設定する

mysqli_driver::$report_mode

mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — mysqli のエラー報告モードを設定する

説明

オブジェクト指向型

int $mysqli_driver->report_mode;

手続き型

mysqli_report(int $flags): bool

フラグに応じて、mysqli のエラー報告モードを設定します。 例外をスローするモードや、警告を発生させるモード、エラーを報告しないモードを設定できます。 MYSQLI_REPORT_ALL や MYSQLI_REPORT_INDEX に設定すると、 インデックスを使わない(または、インデックスの使い方が良くない) クエリも報告します。

PHP 8.1.0 以降では、デフォルトの設定は MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT です。 それより前のバージョンでは、MYSQLI_REPORT_OFF でした。

パラメータ

flags

サポートするフラグ
名前 | 説明
MYSQLI_REPORT_OFF | レポートをオフにする
MYSQLI_REPORT_ERROR | mysqli の関数呼び出しからのエラーを報告する
MYSQLI_REPORT_STRICT | 警告の代わりに mysqli_sql_exception をスローする
MYSQLI_REPORT_INDEX | クエリでインデックスを使っていない (あるいは不適切なインデックスを使っている) 場合にレポートする
MYSQLI_REPORT_ALL | すべてのオプションを設定する (すべてレポートする)

戻り値

true を返します。

変更履歴

バージョン | 説明
8.1.0 | デフォルト値が MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT になりました。 これより前のバージョンでは、 MYSQLI_REPORT_OFF でした。

例

例1 オブジェクト指向型

<?php

/* レポートを有効にします。 */
$driver = new mysqli_driver();
$driver->report_mode = MYSQLI_REPORT_ALL;

try {
/* 接続が失敗すると, mysqli_sql_exception がスローされます。*/
$mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

/* このクエリは、エラーを報告するはずです。 */
$result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

/* このクエリは、カラムがインデックスを持っていた場合、エラーを報告するはずです。*/
$result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
} catch (mysqli_sql_exception $e) {
error_log($e->__toString());
}

例2 手続き型

<?php

/* activate reporting */
mysqli_report(MYSQLI_REPORT_ALL);

try {
/* 接続が失敗すると, mysqli_sql_exception がスローされます。*/
$link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

/* このクエリは、エラーを報告するはずです。 */
$result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

/* このクエリは、カラムがインデックスを持っていた場合、エラーを報告するはずです。*/
$result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
} catch (mysqli_sql_exception $e) {
error_log($e->__toString());
}

例3 インデックスに関するエラー以外を全て報告する

<?php

/* activate reporting */
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
/* 接続が失敗すると, mysqli_sql_exception がスローされます。*/
$mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");
$mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

/* このクエリは、エラーを報告するはずです。 */
$result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

/* このクエリは、インデックスが使えなかったとしても、一切エラーを報告しません */
$result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
} catch (mysqli_sql_exception $e) {
error_log($e->__toString());
}

参考

  • mysqli_sql_exception
  • set_exception_handler() - ユーザー定義の例外ハンドラ関数を設定する
  • error_reporting() - 出力する PHP エラーの種類を設定する


mysqli_warning クラス

(PHP 5, PHP 7, PHP 8)

はじめに

MySQL の警告を表します。

クラス概要

final class mysqli_warning {
/* プロパティ */
public string $message;
public string $sqlstate;
public int $errno;
/* メソッド */
private __construct()
public next(): bool
}

プロパティ

message

メッセージ文字列

sqlstate

SQL state

errno

エラー番号

目次

  • mysqli_warning::__construct — インスタンス化を禁止するための private なコンストラクタ
  • mysqli_warning::next — 次の警告を取得する


インスタンス化を禁止するための private なコンストラクタ

  • ≪ mysqli_warning
  • mysqli_warning::next ≫
  • PHP Manual
  • mysqli_warning
  • インスタンス化を禁止するための private なコンストラクタ

mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — インスタンス化を禁止するための private なコンストラクタ

説明

private mysqli_warning::__construct()

パラメータ

この関数にはパラメータはありません。


次の警告を取得する

  • ≪ mysqli_warning::__construct
  • mysqli_sql_exception ≫
  • PHP Manual
  • mysqli_warning
  • 次の警告を取得する

mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — 次の警告を取得する

説明

public mysqli_warning::next(): bool

可能であれば、次の警告の情報を変更します。

次の警告に情報が送信されると、 mysqli_warning の 新しいプロパティ message, sqlstate および errno の値が利用可能になります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

次の警告の取得に成功すれば true を返します。 警告がない場合は、false を返します。


mysqli_sql_exception クラス

(PHP 5, PHP 7, PHP 8)

はじめに

mysqli の例外を処理するクラスです。

クラス概要

final class mysqli_sql_exception extends RuntimeException {
/* プロパティ */
protected string $sqlstate = "00000";
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public getSqlState(): string
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

sqlstate

エラーの SQLSTATE。

目次

  • mysqli_sql_exception::getSqlState — SQLSTATE エラーコードを含む情報を返す


SQLSTATE エラーコードを含む情報を返す

  • ≪ mysqli_sql_exception
  • エイリアスおよび非推奨の Mysqli 関数 ≫
  • PHP Manual
  • mysqli_sql_exception
  • SQLSTATE エラーコードを含む情報を返す

mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — SQLSTATE エラーコードを含む情報を返す

説明

public mysqli_sql_exception::getSqlState(): string

直近で実行したクエリに関する、 SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5つの文字から構成されます。 エラーコードの値は、ANSI SQL と ODBC で規定されたものです。 取りうる値は、 » http://dev.mysql.com/doc/mysql/en/error-handling.html を参照ください。

注意:

すべての MySQL で発生するエラーが、 SQLSTATE エラーコードに対応しているわけではありません。 対応していないエラーコードについては、 HY000 (一般エラー) が使われます。

パラメータ

この関数にはパラメータはありません。

戻り値

直近で実行したクエリに関する、 SQLSTATE エラーコードを含む文字列を返します。 エラーコードは 5つの文字から構成されます。


エイリアスおよび非推奨の Mysqli 関数

目次

  • mysqli_connect — mysqli::__construct のエイリアス
  • mysqli::escape_string — mysqli_real_escape_string のエイリアス
  • mysqli_execute — mysqli_stmt_execute のエイリアス
  • mysqli_get_client_stats — プロセスごとのクライアントの統計を返す
  • mysqli_get_links_stats — オープン済みとキャッシュ済みのリンクに関する情報を返す
  • mysqli_report — mysqli_driver->report_mode のエイリアス
  • mysqli::set_opt — mysqli_options のエイリアス


mysqli::__construct のエイリアス

  • ≪ エイリアスおよび非推奨の Mysqli 関数
  • mysqli::escape_string ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli::__construct のエイリアス

mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — mysqli::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli::__construct()

注意:

mysqli の例外モードが無効な場合、かつ接続に失敗した場合、 mysqli_connect() 関数はオブジェクトではなく false を返します。 接続エラーの内容を取得するのに、 mysqli_connect_error() 関数が使えます。


mysqli_real_escape_string のエイリアス

  • ≪ mysqli_connect
  • mysqli_execute ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_real_escape_string のエイリアス

mysqli::escape_string

mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — mysqli_real_escape_string() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_real_escape_string().


mysqli_stmt_execute のエイリアス

  • ≪ mysqli::escape_string
  • mysqli_get_client_stats ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_stmt_execute のエイリアス

mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — mysqli_stmt_execute() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_stmt_execute()

注意

注意:

mysqli_execute() は非推奨で、廃止予定です。

参考

  • mysqli_stmt_execute() - プリペアドステートメントを実行する


プロセスごとのクライアントの統計を返す

  • ≪ mysqli_execute
  • mysqli_get_links_stats ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • プロセスごとのクライアントの統計を返す

mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — プロセスごとのクライアントの統計を返す

説明

mysqli_get_client_stats(): array

プロセスごとのクライアントの統計を返します。

注意:

mysqlnd でのみ使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

クライアントの統計を配列で返します。

例

例1 A mysqli_get_client_stats() の例

<?php
$link = mysqli_connect();
print_r(mysqli_get_client_stats());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [bytes_sent] => 43
    [bytes_received] => 80
    [packets_sent] => 1
    [packets_received] => 2
    [protocol_overhead_in] => 8
    [protocol_overhead_out] => 4
    [bytes_received_ok_packet] => 11
    [bytes_received_eof_packet] => 0
    [bytes_received_rset_header_packet] => 0
    [bytes_received_rset_field_meta_packet] => 0
    [bytes_received_rset_row_packet] => 0
    [bytes_received_prepare_response_packet] => 0
    [bytes_received_change_user_packet] => 0
    [packets_sent_command] => 0
    [packets_received_ok] => 1
    [packets_received_eof] => 0
    [packets_received_rset_header] => 0
    [packets_received_rset_field_meta] => 0
    [packets_received_rset_row] => 0
    [packets_received_prepare_response] => 0
    [packets_received_change_user] => 0
    [result_set_queries] => 0
    [non_result_set_queries] => 0
    [no_index_used] => 0
    [bad_index_used] => 0
    [slow_queries] => 0
    [buffered_sets] => 0
    [unbuffered_sets] => 0
    [ps_buffered_sets] => 0
    [ps_unbuffered_sets] => 0
    [flushed_normal_sets] => 0
    [flushed_ps_sets] => 0
    [ps_prepared_never_executed] => 0
    [ps_prepared_once_executed] => 0
    [rows_fetched_from_server_normal] => 0
    [rows_fetched_from_server_ps] => 0
    [rows_buffered_from_client_normal] => 0
    [rows_buffered_from_client_ps] => 0
    [rows_fetched_from_client_normal_buffered] => 0
    [rows_fetched_from_client_normal_unbuffered] => 0
    [rows_fetched_from_client_ps_buffered] => 0
    [rows_fetched_from_client_ps_unbuffered] => 0
    [rows_fetched_from_client_ps_cursor] => 0
    [rows_skipped_normal] => 0
    [rows_skipped_ps] => 0
    [copy_on_write_saved] => 0
    [copy_on_write_performed] => 0
    [command_buffer_too_small] => 0
    [connect_success] => 1
    [connect_failure] => 0
    [connection_reused] => 0
    [reconnect] => 0
    [pconnect_success] => 0
    [active_connections] => 1
    [active_persistent_connections] => 0
    [explicit_close] => 0
    [implicit_close] => 0
    [disconnect_close] => 0
    [in_middle_of_command_close] => 0
    [explicit_free_result] => 0
    [implicit_free_result] => 0
    [explicit_stmt_close] => 0
    [implicit_stmt_close] => 0
    [mem_emalloc_count] => 0
    [mem_emalloc_ammount] => 0
    [mem_ecalloc_count] => 0
    [mem_ecalloc_ammount] => 0
    [mem_erealloc_count] => 0
    [mem_erealloc_ammount] => 0
    [mem_efree_count] => 0
    [mem_malloc_count] => 0
    [mem_malloc_ammount] => 0
    [mem_calloc_count] => 0
    [mem_calloc_ammount] => 0
    [mem_realloc_count] => 0
    [mem_realloc_ammount] => 0
    [mem_free_count] => 0
    [proto_text_fetched_null] => 0
    [proto_text_fetched_bit] => 0
    [proto_text_fetched_tinyint] => 0
    [proto_text_fetched_short] => 0
    [proto_text_fetched_int24] => 0
    [proto_text_fetched_int] => 0
    [proto_text_fetched_bigint] => 0
    [proto_text_fetched_decimal] => 0
    [proto_text_fetched_float] => 0
    [proto_text_fetched_double] => 0
    [proto_text_fetched_date] => 0
    [proto_text_fetched_year] => 0
    [proto_text_fetched_time] => 0
    [proto_text_fetched_datetime] => 0
    [proto_text_fetched_timestamp] => 0
    [proto_text_fetched_string] => 0
    [proto_text_fetched_blob] => 0
    [proto_text_fetched_enum] => 0
    [proto_text_fetched_set] => 0
    [proto_text_fetched_geometry] => 0
    [proto_text_fetched_other] => 0
    [proto_binary_fetched_null] => 0
    [proto_binary_fetched_bit] => 0
    [proto_binary_fetched_tinyint] => 0
    [proto_binary_fetched_short] => 0
    [proto_binary_fetched_int24] => 0
    [proto_binary_fetched_int] => 0
    [proto_binary_fetched_bigint] => 0
    [proto_binary_fetched_decimal] => 0
    [proto_binary_fetched_float] => 0
    [proto_binary_fetched_double] => 0
    [proto_binary_fetched_date] => 0
    [proto_binary_fetched_year] => 0
    [proto_binary_fetched_time] => 0
    [proto_binary_fetched_datetime] => 0
    [proto_binary_fetched_timestamp] => 0
    [proto_binary_fetched_string] => 0
    [proto_binary_fetched_blob] => 0
    [proto_binary_fetched_enum] => 0
    [proto_binary_fetched_set] => 0
    [proto_binary_fetched_geometry] => 0
    [proto_binary_fetched_other] => 0
)

参考

  • Stats description


オープン済みとキャッシュ済みのリンクに関する情報を返す

  • ≪ mysqli_get_client_stats
  • mysqli_report ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • オープン済みとキャッシュ済みのリンクに関する情報を返す

mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — オープン済みとキャッシュ済みのリンクに関する情報を返す

説明

mysqli_get_links_stats(): array

mysqli_get_links_stats() 関数は、 オープン済みとキャッシュ済みの MySQL リンクに関する情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

mysqli_get_links_stats() 関数は、3つの要素からなる連想配列を返します。 キーは次のとおりです:

total

オープンされているリンクの合計数を示す int

active_plinks

アクティブな永続的な接続の数を示す int

cached_plinks

アクティブでない永続的な接続の数を示す int


mysqli_driver->report_mode のエイリアス

  • ≪ mysqli_get_links_stats
  • mysqli::set_opt ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_driver->report_mode のエイリアス

mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — mysqli_driver->report_mode のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_driver->report_mode


mysqli_options のエイリアス

  • ≪ mysqli_report
  • 変更履歴 ≫
  • PHP Manual
  • エイリアスおよび非推奨の Mysqli 関数
  • mysqli_options のエイリアス

mysqli::set_opt

mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — mysqli_options() のエイリアス

説明

この関数は次の関数のエイリアスです。 mysqli_options()


  • ≪ mysqli::set_opt
  • Mysql_xdevapi ≫
  • PHP Manual
  • MySQLi
  • 変更履歴

変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

Version Function 説明


Mysql_xdevapi

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • ソースコードからビルド / コンパイルする
  • 定義済み定数
  • 変更履歴
  • 例
  • Mysql_xdevapi 関数
    • expression — プリペアドステートメントの変数をパラメータとしてバインドする
    • getSession — MySQL サーバーに接続する
  • mysql_xdevapi\BaseResult — BaseResult クラス
    • BaseResult::getWarnings — 直近の操作の警告を取得する
    • BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する
  • mysql_xdevapi\Client — クライアントクラス
    • mysql_xdevapi\Client::close — クライアントの接続を閉じる
    • Client::__construct — Client のコンストラクタ
    • Client::getClient — クライアントのセッションを取得する
  • mysql_xdevapi\Collection — Collection クラス
    • Collection::add — コレクションにドキュメントを追加する
    • Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する
    • Collection::__construct — Collection のコンストラクタ
    • Collection::count — ドキュメントの数を取得する
    • Collection::createIndex — コレクションにインデックスを作成
    • Collection::dropIndex — コレクションのインデックスを削除
    • Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする
    • Collection::find — ドキュメントを検索する
    • Collection::getName — コレクションの名前を得る
    • Collection::getOne — ドキュメントをひとつ取得
    • Collection::getSchema — スキーマオブジェクトを得る
    • Collection::getSession — セッションオブジェクトを取得
    • Collection::modify — コレクションのドキュメントを変更する
    • Collection::remove — コレクションを削除する
    • Collection::removeOne — コレクションからドキュメントをひとつ削除する
    • Collection::replaceOne — コレクションのドキュメントをひとつ置き換える
  • mysql_xdevapi\CollectionAdd — CollectionAdd クラス
    • CollectionAdd::__construct — CollectionAdd のコンストラクタ
    • CollectionAdd::execute — ステートメントを実行する
  • mysql_xdevapi\CollectionFind — CollectionFind クラス
    • CollectionFind::bind — クエリのプレースホルダーに値をバインドする
    • CollectionFind::__construct — CollectionFind のコンストラクタ
    • CollectionFind::execute — ステートメントを実行する
    • CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する
    • CollectionFind::groupBy — グループ化の条件を設定する
    • CollectionFind::having — 集約関数の条件を設定する
    • CollectionFind::limit — 返されるドキュメントの数を限定する
    • CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK
    • CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する
    • CollectionFind::offset — 返される要素の数から、与えられた数をスキップする
    • CollectionFind::sort — ソート条件を設定する
  • mysql_xdevapi\CollectionModify — CollectionModify クラス
    • CollectionModify::arrayAppend — 配列のフィールドに要素を追加する
    • CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する
    • CollectionModify::bind — クエリのプレースホルダーに値をバインドする
    • CollectionModify::__construct — CollectionModify のコンストラクタ
    • CollectionModify::execute — 変更の操作を実行する
    • CollectionModify::limit — 変更されるドキュメントの数を限定する
    • CollectionModify::patch — document にパッチを当てる
    • CollectionModify::replace — ドキュメントのフィールドを置き換える
    • CollectionModify::set — ドキュメントの属性を設定する
    • CollectionModify::skip — 要素をスキップする
    • CollectionModify::sort — ソート条件を設定する
    • CollectionModify::unset — ドキュメントのフィールドの値を削除する
  • mysql_xdevapi\CollectionRemove — CollectionRemove クラス
    • CollectionRemove::bind — プレースホルダーに値をバインドする
    • CollectionRemove::__construct — CollectionRemove のコンストラクタ
    • CollectionRemove::execute — 削除操作を実行する
    • CollectionRemove::limit — 削除するドキュメントの数を限定する
    • CollectionRemove::sort — ソート条件を設定する
  • mysql_xdevapi\ColumnResult — ColumnResult クラス
    • ColumnResult::__construct — ColumnResult のコンストラクタ
    • ColumnResult::getCharacterSetName — キャラクタセットを取得する
    • ColumnResult::getCollationName — 照合順序名を取得する
    • ColumnResult::getColumnLabel — カラムのラベルを取得する
    • ColumnResult::getColumnName — カラム名を取得する
    • ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する
    • ColumnResult::getLength — カラムのフィールドの長さを取得する
    • ColumnResult::getSchemaName — スキーマ名を取得する
    • ColumnResult::getTableLabel — テーブルラベルを取得する
    • ColumnResult::getTableName — テーブル名を取得する
    • ColumnResult::getType — カラムの型を取得する
    • ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる
    • ColumnResult::isPadded — パディングされているかを調べる
  • mysql_xdevapi\CrudOperationBindable — CrudOperationBindable インターフェイス
    • CrudOperationBindable::bind — プレースホルダーに値をバインドする
  • mysql_xdevapi\CrudOperationLimitable — CrudOperationLimitable インターフェイス
    • CrudOperationLimitable::limit — 結果を限定する
  • mysql_xdevapi\CrudOperationSkippable — CrudOperationSkippable インターフェイス
    • CrudOperationSkippable::skip — スキップする操作の数
  • mysql_xdevapi\CrudOperationSortable — CrudOperationSortable インターフェイス
    • CrudOperationSortable::sort — 結果をソートする
  • mysql_xdevapi\DatabaseObject — DatabaseObject インターフェイス
    • DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする
    • DatabaseObject::getName — オブジェクトの名前を取得する
    • DatabaseObject::getSession — セッションの名前を取得する
  • mysql_xdevapi\DocResult — DocResult クラス
    • DocResult::__construct — DocResult のコンストラクタ
    • DocResult::fetchAll — 全ての行を取得する
    • DocResult::fetchOne — 一行取得する
    • DocResult::getWarnings — 直近の操作から発生した警告を取得する
    • DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する
  • mysql_xdevapi\Exception — Exception クラス
  • mysql_xdevapi\Executable — Executable インターフェイス
    • Executable::execute — ステートメントを実行する
  • mysql_xdevapi\ExecutionStatus — ExecutionStatus クラス
    • ExecutionStatus::__construct — ExecutionStatus のコンストラクタ
  • mysql_xdevapi\Expression — Expression クラス
    • Expression::__construct — Expression のコンストラクタ
  • mysql_xdevapi\Result — Result クラス
    • Result::__construct — Result のコンストラクタ
    • Result::getAffectedItemsCount — 影響を受けた行数を得る
    • Result::getAutoIncrementValue — 自動インクリメントされた値を取得する
    • Result::getGeneratedIds — 生成された id を取得する
    • Result::getWarnings — 直近の操作から発生した警告を取得する
    • Result::getWarningsCount — 直近の操作から生じた警告の数を取得する
  • mysql_xdevapi\RowResult — RowResult クラス
    • RowResult::__construct — RowResult のコンストラクタ
    • RowResult::fetchAll — 結果セットから全ての行を取得する
    • RowResult::fetchOne — 結果セットから行を取得する
    • RowResult::getColumnsCount — カラムの数を取得する
    • RowResult::getColumnNames — 全てのカラム名を取得する
    • RowResult::getColumns — カラムのメタデータを取得する
    • RowResult::getWarnings — 直近の操作から生じた警告を取得する
    • RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する
  • mysql_xdevapi\Schema — Schema クラス
    • Schema::__construct — Schema のコンストラクタ
    • Schema::createCollection — スキーマにコレクションを追加する
    • Schema::dropCollection — スキーマからコレクションを削除する
    • Schema::existsInDatabase — データベースに存在するかをチェックする
    • Schema::getCollection — スキーマからコレクションを取得する
    • Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する
    • Schema::getCollections — スキーマに属する全てのコレクションを取得する
    • Schema::getName — スキーマの名前を取得する
    • Schema::getSession — スキーマのセッションを取得する
    • Schema::getTable — スキーマのテーブルを取得する
    • Schema::getTables — スキーマのテーブルを取得する
  • mysql_xdevapi\SchemaObject — SchemaObject インターフェイス
    • SchemaObject::getSchema — スキーマオブジェクトを得る
  • mysql_xdevapi\Session — Session クラス
    • Session::close — セッションを閉じる
    • Session::commit — トランザクションをコミットする
    • Session::__construct — Session のコンストラクタ
    • Session::createSchema — 新しいスキーマを作成する
    • Session::dropSchema — スキーマを削除します
    • Session::generateUUID — 新しいUUIDを取得する
    • Session::getDefaultSchema — デフォルトのスキーマ名を取得する
    • Session::getSchema — 新しいスキーマオブジェクトを取得する
    • Session::getSchemas — スキーマを取得する
    • Session::getServerVersion — サーバーのバージョンを取得する
    • Session::listClients — クライアントの一覧を取得する
    • Session::quoteName — クォートを追加する
    • Session::releaseSavepoint — 設定されたセーブポイントをリリースする
    • Session::rollback — トランザクションをロールバックする
    • Session::rollbackTo — セーブポイントまでトランザクションをロールバックする
    • Session::setSavepoint — セーブポイントを作成する
    • Session::sql — SQLクエリを作成する
    • Session::startTransaction — トランザクションを開始する
  • mysql_xdevapi\SqlStatement — SqlStatement クラス
    • SqlStatement::bind — ステートメントのパラメータをバインドする
    • SqlStatement::__construct — SqlStatement のコンストラクタ
    • SqlStatement::execute — 操作を実行する
    • SqlStatement::getNextResult — 次の結果を取得する
    • SqlStatement::getResult — 結果を取得する
    • SqlStatement::hasMoreResults — さらに結果があるかを調べる
  • mysql_xdevapi\SqlStatementResult — SqlStatementResult クラス
    • SqlStatementResult::__construct — SqlStatementResult のコンストラクタ
    • SqlStatementResult::fetchAll — 結果セットから全行取得する
    • SqlStatementResult::fetchOne — 単一の行を取得する
    • SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する
    • SqlStatementResult::getColumnsCount — カラムの数を取得する
    • SqlStatementResult::getColumnNames — カラム名を取得する
    • SqlStatementResult::getColumns — カラムを取得する
    • SqlStatementResult::getGeneratedIds — 生成された id を取得する
    • SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する
    • SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する
    • SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する
    • SqlStatementResult::hasData — 結果がデータを持っているかを調べる
    • SqlStatementResult::nextResult — 次の結果を取得する
  • mysql_xdevapi\Statement — Statement クラス
    • Statement::__construct — Statement のコンストラクタ
    • Statement::getNextResult — 次の結果を取得する
    • Statement::getResult — 結果を取得する
    • Statement::hasMoreResults — さらに結果があるかを調べる
  • mysql_xdevapi\Table — Table クラス
    • Table::__construct — Table のコンストラクタ
    • Table::count — 行の数を取得する
    • Table::delete — テーブルから行を削除する
    • Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする
    • Table::getName — テーブル名を取得する
    • Table::getSchema — テーブルスキーマを取得する
    • Table::getSession — テーブルを操作するためのセッションを取得する
    • Table::insert — テーブルに行を挿入する
    • Table::isView — テーブルがビューかどうかを調べる
    • Table::select — テーブルから行を選択する
    • Table::update — テーブルの行を更新する
  • mysql_xdevapi\TableDelete — TableDelete クラス
    • TableDelete::bind — delete のクエリパラメータをバインドする
    • TableDelete::__construct — TableDelete のコンストラクタ
    • TableDelete::execute — delete文を実行する
    • TableDelete::limit — 削除する行を限定する
    • TableDelete::orderby — 削除の際のソート条件を設定する
    • TableDelete::where — 削除時の検索条件を設定する
  • mysql_xdevapi\TableInsert — TableInsert クラス
    • TableInsert::__construct — TableInsert クラスのコンストラクタ
    • TableInsert::execute — insert クエリを実行する
    • TableInsert::values — 挿入する行の値を追加する
  • mysql_xdevapi\TableSelect — TableSelect クラス
    • TableSelect::bind — select のクエリパラメータをバインドする
    • TableSelect::__construct — TableSelect のコンストラクタ
    • TableSelect::execute — select ステートメントを実行する
    • TableSelect::groupBy — select 時のグループ化の条件を設定する
    • TableSelect::having — select 句の having 条件を設定する
    • TableSelect::limit — 選択される行の数を限定する
    • TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する
    • TableSelect::lockShared — SHARED LOCK を実行する
    • TableSelect::offset — スキップするoffsetを設定する
    • TableSelect::orderby — select 文のソート条件を設定する
    • TableSelect::where — select 文の検索条件を設定する
  • mysql_xdevapi\TableUpdate — TableUpdate クラス
    • TableUpdate::bind — update のクエリパラメータをバインドする
    • TableUpdate::__construct — TableUpdate のコンストラクタ
    • TableUpdate::execute — update クエリを実行する
    • TableUpdate::limit — 更新する行の数を限定する
    • TableUpdate::orderby — ソート条件を設定する
    • TableUpdate::set — 更新されるフィールドを追加する
    • TableUpdate::where — 検索フィルタを設定する
  • mysql_xdevapi\Warning — Warning クラス
    • Warning::__construct — Warning のコンストラクタ


はじめに

この拡張モジュールは、MySQLドキュメントストアに X DevAPI 経由でアクセスできるようにします。 X DevAPI は、複数の MySQLコネクタ によって提供されている、共通のAPIです。 これらのコネクタは、リレーショナルなテーブルだけでなく、JSONで表現されたドキュメントのコレクションに対しても、 CRUDスタイルの操作を持つAPIを通して簡単にアクセスできます。

X DevAPI は Xプロトコルを使っています。 これは MySQL 8.0 サーバーの、新世代のクライアント-サーバープロトコルです。

MySQLドキュメントストアに関する一般的な情報については、 MySQLマニュアル の » MySQL Document Store の章を参照ください。


インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • ソースコードからビルド / コンパイルする


要件

この拡張モジュールは、X プラグインを有効にした(デフォルトで有効になっています) MySQL 8 以上のサーバーが必須です。

この拡張モジュールをコンパイルするために前提となるライブラリは以下です: Boost (1.53.0 以上), OpenSSL, and Protobuf


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

Ubuntu 18.04 上の PHP 7.2 でインストールする例:

// 依存するものをインストール
$ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

// 望ましい拡張モジュールと一緒にPHPをインストール; php7.2-dev はコンパイルに必須
$ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

// 拡張モジュールをコンパイル
$ pecl install mysql_xdevapi

pecl install コマンドは、PHP の拡張モジュールを有効にしません(デフォルト) し、PHP の拡張モジュールを有効にする方法は複数あります。 Ubuntu 18.04 上の PHP 7.2 でインストールする別の例を以下に示します:

// 自分の ini ファイルを作る
$ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

// 'phpenmod' コマンドを使う (注意: Debian/Ubuntu 特有のコマンドです)
$ phpenmod -v 7.2 -s ALL mysql_xdevapi

// 'phpenmod' の代わりに、手動でシンボリックリンクを張る
// $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

// MySQL 拡張モジュールが有効になっているかどうかをチェックしよう
$ php -m |grep mysql

mysql_xdevapi
mysqli
mysqlnd
pdo_mysql

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mysql_xdevapi


実行時設定

php.ini の設定により動作が変化します。

Mysql_xdevapi 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
xmysqlnd.collect_memory_statistics | 0 | INI_SYSTEM |
xmysqlnd.collect_statistics | 1 | INI_ALL |
xmysqlnd.debug |  | INI_SYSTEM |
xmysqlnd.mempool_default_size | 16000 | INI_ALL |
xmysqlnd.net_read_timeout | 31536000 | INI_SYSTEM |
xmysqlnd.trace_alloc |  | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

xmysqlnd.collect_memory_statistics int

xmysqlnd.collect_statistics int

xmysqlnd.debug string

xmysqlnd.mempool_default_size int

xmysqlnd.net_read_timeout int

xmysqlnd.trace_alloc string


ソースコードからビルド / コンパイルする

この拡張モジュールをソースコードからコンパイルする際に、考慮すべき事項は以下です。

  • 拡張モジュールの名前は 'mysql_xdevapi' です。 よって、 --enable-mysql-xdevapi を使ってください。

  • Boost が必須です。 オプションで configure オプション --with-boost=DIR や MYSQL_XDEVAPI_BOOST_ROOT 環境変数が使えます。 boost のヘッダファイルのみが必須で、ライブラリファイルは必要ありません。

  • Google の Protocol Buffers (protobuf) が必須です。 オプションで configure オプション --with-protobuf=DIR や MYSQL_XDEVAPI_PROTOBUF_ROOT 環境変数が使えます。

    protobuf ファイル (*.pb.cc/.h) を生成するのに オプションで make protobufs が使えますし、 生成された protobuf ファイルを削除するのに make clean-protobufs が使えます。

    Windows 特有の protobuf に関する注意: 環境によっては、マルチスレッドに対応した DLL ランタイムが含まれる静的ライブラリが必要かもしれません。 これを準備するには、以下のオプションを使ってください: -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

  • Google の Protocol Buffers / protocol コンパイラ (protoc) が必須です。 適切な 'protoc' コマンドが ビルド中に PATH が通った場所に置いておいてください。 このことは、Windows PHP SDK バッチスクリプトが この環境変数を上書きする可能性があるため特に重要です。

  • Bison は必須です。PATH が通った場所に置いておいてください。

    Window 特有の bison に関する注意: PHP SDK と同梱されている bison を使うことを強く推奨します。 さもなければ、次のメッセージに似たエラーが出る可能性があります。 "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'" Windows PHP SDK バッチスクリプトが 環境変数を上書きする可能性があることにも注意してください。

  • Windows 特有の注意: 環境を準備するために、オフィシャルな Windows ビルドドキュメント (» 現行のSDK) を参照ください

    全てのファイルpathについて、スラッシュ '/' ではなく、 バックスラッシュ '\\' を使うことを推奨します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MYSQLX_CLIENT_SSL (int)
MYSQLX_TYPE_DECIMAL (int)
MYSQLX_TYPE_TINY (int)
MYSQLX_TYPE_SHORT (int)
MYSQLX_TYPE_SMALLINT (int)
MYSQLX_TYPE_MEDIUMINT (int)
MYSQLX_TYPE_INT (int)
MYSQLX_TYPE_BIGINT (int)
MYSQLX_TYPE_LONG (int)
MYSQLX_TYPE_FLOAT (int)
MYSQLX_TYPE_DOUBLE (int)
MYSQLX_TYPE_NULL (int)
MYSQLX_TYPE_TIMESTAMP (int)
MYSQLX_TYPE_LONGLONG (int)
MYSQLX_TYPE_INT24 (int)
MYSQLX_TYPE_DATE (int)
MYSQLX_TYPE_TIME (int)
MYSQLX_TYPE_DATETIME (int)
MYSQLX_TYPE_YEAR (int)
MYSQLX_TYPE_NEWDATE (int)
MYSQLX_TYPE_ENUM (int)
MYSQLX_TYPE_SET (int)
MYSQLX_TYPE_TINY_BLOB (int)
MYSQLX_TYPE_MEDIUM_BLOB (int)
MYSQLX_TYPE_LONG_BLOB (int)
MYSQLX_TYPE_BLOB (int)
MYSQLX_TYPE_VAR_STRING (int)
MYSQLX_TYPE_STRING (int)
MYSQLX_TYPE_CHAR (int)
MYSQLX_TYPE_BYTES (int)
MYSQLX_TYPE_INTERVAL (int)
MYSQLX_TYPE_GEOMETRY (int)
MYSQLX_TYPE_JSON (int)
MYSQLX_TYPE_NEWDECIMAL (int)
MYSQLX_TYPE_BIT (int)
MYSQLX_LOCK_DEFAULT (int)
MYSQLX_LOCK_NOWAIT (int)
MYSQLX_LOCK_SKIP_LOCKED (int)


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

Mysql_xdevapi 拡張モジュールの変更履歴

Mysql_xdevapi 拡張モジュールの変更履歴を以下に示します。

ext/mysql_xdevapi 全体の変更

バージョン | 説明
8.0.28 | TLSv1 と TLSv1.1 のサポートが削除されました。 "TLSv1", "TLSv1.0", "TLSv1.1" を、 接続の属性 "tls-versions" に設定すると無効とみなされます。
8.0.26 | TLSv1 と TLSv1.1 のサポートが非推奨になりました。


例

X DevAPI の中心的なエントリポイントは、 mysql_xdevapi\getSession() 関数です。 これは MySQL 8.0 サーバーへの URI を受取り、 mysql_xdevap\Session オブジェクトを返します。

例1 MySQL Serverへの接続

<?php
try {
$session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
die("Connection could not be established: " . $e->getMessage());
}

// ... use $session
?>

セッションは、API への完全なアクセスを提供します。 新しい MySQL サーバーをインストールした後の最初のステップは、 データを保存するために、コレクションを使ってデータベースのスキーマを作ることです:

例2 MySQL サーバー上で、スキーマとコレクションを作る

<?php
$schema = $session->createSchema("test");
$collection = $schema->createCollection("example");
?>

データを保存する際には、 json_encode() 関数を使い、データを JSON にエンコードします。 JSON はコレクションに保存するのに使います。

次の例は、既に述べた例で作ったコレクションにデータを保存します。 そして、その一部を再度取得します。

例3 データを保存し、取得する

<?php
$marco = [
"name" => "Marco",
"age" => 19,
"job" => "Programmer"
];
$mike = [
"name" => "Mike",
"age" => 39,
"job" => "Manager"
];

$schema = $session->getSchema("test");
$collection = $schema->getCollection("example");

$collection->add($marco, $mike)->execute();

var_dump($collection->find("name = 'Mike'")->execute()->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  string(28) "00005ad66aaf0000000000000003"
  ["age"]=>
  int(39)
  ["job"]=>
  string(7) "Manager"
  ["name"]=>
  string(4) "Mike"
}

この例では、文書へのプライマリーキーの役割を果たす _id という追加フィールドを MySQL サーバーが追加していることを示しています。

さらにこの例は、取得したデータがアルファベット順にソートされていることも示しています。 この特定の並び順は、MySQL サーバー内の効率的なバイナリストレージから来ていますが、 それに依存すべきではありません。詳細は、MySQL の JSON データ型のドキュメントを参照ください。

オプションで、複数の文書を取得するのに、PHP のイテレータが使えます。

例4 複数の文書を取得し、それを走査する

<?php
$result = $collection->find()->execute();
foreach ($result as $doc) {
echo "{$doc["name"]} is a {$doc["job"]}.\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Marco is a Programmer.
Mike is a Manager.


Mysql_xdevapi 関数

目次

  • expression — プリペアドステートメントの変数をパラメータとしてバインドする
  • getSession — MySQL サーバーに接続する


プリペアドステートメントの変数をパラメータとしてバインドする

  • ≪ Mysql_xdevapi 関数
  • getSession ≫
  • PHP Manual
  • Mysql_xdevapi 関数
  • プリペアドステートメントの変数をパラメータとしてバインドする

expression

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

expression — プリペアドステートメントの変数をパラメータとしてバインドする

説明

mysql_xdevapi\expression(string $expression): object

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

expression

戻り値

例

例1 mysql_xdevapi\Expression() の例

<?php
$expression = mysql_xdevapi\Expression("[age,job]");

$res = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
$data = $res->fetchAll();

print_r($data);
?>

上の例の出力は、 たとえば以下のようになります。

<?php


MySQL サーバーに接続する

  • ≪ expression
  • mysql_xdevapi\BaseResult ≫
  • PHP Manual
  • Mysql_xdevapi 関数
  • MySQL サーバーに接続する

getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

getSession — MySQL サーバーに接続する

説明

mysql_xdevapi\getSession(string $uri): mysql_xdevapi\Session

MySQL サーバーに接続します。

パラメータ

uri

mysqlx://user:password@host のような、MySQL サーバーへのURI。

URI のフォーマットは下記のとおりです:

scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...

  • scheme は必須です。接続プロトコルです

    mysql_xdevapi では、常に 'mysqlx' です(X プロトコル)

  • user: オプションです。認証される MySQL アカウント

  • password: オプションです。認証に使う MySQL ユーザのパスワード

  • target: 必須です。 接続が参照する サーバーインスタンスです:

    * TCP接続 (ホスト名, IPv4 アドレス, または IPv6 アドレス)

    * Unix ソケットのパス (ローカルファイルのパス)

    * Windows 名前付きパイプ (ローカルファイルのパス)

  • port: オプションです。MySQL サーバーのネットワーク ポート

    X プロトコルのデフォルトのポートは 33060 です

  • ?attribute=value: この要素はオプションで、異なるオプションを含む 次のような辞書データを指定します:

    • auth (認証メカニズム) 属性は、接続の暗号化に関連があります。 追加の情報については、 » Command Options for Encrypted Connections を参照ください。 'auth' 属性については、次の値がサポートされています: plain, mysql41, external, sha256_mem.

    • connect-timeout 属性は、接続時と接続後の操作に影響します。 単一、複数のホストへの接続かに関わらず、接続単位で設定します。

      接続タイムアウトは秒単位で正の整数を渡します。 0 を渡すと、タイムアウトを無効(つまり無限) にします。 connect-timeout を定義しないと、デフォルト値10を使います。

      関連事項として、 MYSQLX_CONNECTION_TIMEOUT (秒単位のタイムアウト) および、 MYSQLX_TEST_CONNECTION_TIMEOUT (テスト時に使います) 環境変数を、URI に connect-timeout を設定する代わりに設定し、使うことができます。 connect-timeout URI オプションは、これらの環境変数に優先します。

    • オプションの compression は、以下の値を受け付けます: preferred (クライアントとサーバーが、お互いがサポートしているアルゴリズムを見つけるために交渉します。つまり、サポートされたアルゴリズムが見つからない場合は圧縮されません), required ("preferred" と似ていますが、お互いがサポートしているアルゴリズムが見つからない場合は接続を終了します), または disabled (この接続では圧縮が行われません)。 デフォルトは preferred です。

      このオプションは 8.0.20 で追加されました。

    • オプションの compression-algorithms 属性は、 好みの圧縮アルゴリズム(および好みの優先順) を定義します: zstd_stream (エイリアス: zstd), lz4_message (エイリアス: lz4), deflate_stream (エイリアス: deflate, zlib) が指定できます。 デフォルトでは、(システムで利用可能かどうかに依存しますが) lz4_message, zstd_stream, deflate_stream の順番が使われます。 たとえば、compression-algorithms=[lz4,zstd_stream] という値を渡した場合、 lz4 が利用可能であれば lz4 を使いますが、そうでない場合は、zstd_stream が使われます。 lz4, zstd_stream 双方が利用できない場合、振る舞いは compression の値に依存します。 たとえば、compression=required の場合、エラーが出て接続は失敗します。

      このオプションは 8.0.22 で追加されました。

例1 URI の例

mysqlx://foobar
mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
mysqlx://foo:bar@localhost:33060
mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
mysqlx://foo:bar@localhost:33260?ssl-mode=required
mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
mysqlx://foo:bar@(/path/to/socket)
mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
mysqlx://foo:bar@localhost:33160/?connect-timeout=0
mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

関連する情報については、MySQL Shell の » Connecting using a URI String を参照ください

戻り値

Session オブジェクト

エラー / 例外

接続に失敗した場合は、Exception がスローされます。

例

例2 mysql_xdevapi\getSession() の例

<?php
try {
$session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
die("Connection could not be established: " . $e->getMessage());
}

$schemas = $session->getSchemas();
print_r($schemas);

$mysql_version = $session->getServerVersion();
print_r($mysql_version);

var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Schema Object
        (
            [name] => helloworld
        )
    [1] => mysql_xdevapi\Schema Object
        (
            [name] => information_schema
        )
    [2] => mysql_xdevapi\Schema Object
        (
            [name] => mysql
        )
    [3] => mysql_xdevapi\Schema Object
        (
            [name] => performance_schema
        )
    [4] => mysql_xdevapi\Schema Object
        (
            [name] => sys
        )
)

80012

array(4) {
  ["_id"]=>
  string(28) "00005ad66abf0001000400000003"
  ["age"]=>
  int(42)
  ["job"]=>
  string(7) "Butler"
  ["name"]=>
  string(4) "Alfred"
}


BaseResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\BaseResult {
/* メソッド */
abstract public getWarnings(): array
abstract public getWarningsCount(): int
}

目次

  • BaseResult::getWarnings — 直近の操作の警告を取得する
  • BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する


直近の操作の警告を取得する

  • ≪ mysql_xdevapi\BaseResult
  • BaseResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\BaseResult
  • 直近の操作の警告を取得する

BaseResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

BaseResult::getWarnings — 直近の操作の警告を取得する

説明

abstract public mysql_xdevapi\BaseResult::getWarnings(): array

MySQL サーバーに対する直近の操作によって生成された警告を取得します

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から生成される Warning オブジェクトの配列を返します。 各々のオブジェクトはエラーの 'message', 'level', そして 'code' を定義しています。 エラーが発生していなければ、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::getWarnings() example

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();
$warnings = $res->getWarnings();

print_r($warnings);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
)


直近の操作から発生した警告の数を取得する

  • ≪ BaseResult::getWarnings
  • mysql_xdevapi\Client ≫
  • PHP Manual
  • mysql_xdevapi\BaseResult
  • 直近の操作から発生した警告の数を取得する

BaseResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する

説明

abstract public mysql_xdevapi\BaseResult::getWarningsCount(): int

直近の操作から発生した警告の数を取得します。 特に、これらの警告は MySQL サーバーから発生します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から発生した警告の数を返します。

例

例1 mysql_xdevapi\RowResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS foo")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();

echo $res->getWarningsCount();
?>

上の例の出力は、 たとえば以下のようになります。

2


クライアントクラス

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

コネクションプールへのアクセスを提供します。

クラス概要

class mysql_xdevapi\Client {
/* メソッド */
public close(): bool
public getSession(): mysql_xdevapi\Session
}

目次

  • mysql_xdevapi\Client::close — クライアントの接続を閉じる
  • Client::__construct — Client のコンストラクタ
  • Client::getClient — クライアントのセッションを取得する


クライアントの接続を閉じる

  • ≪ mysql_xdevapi\Client
  • Client::__construct ≫
  • PHP Manual
  • mysql_xdevapi\Client
  • クライアントの接続を閉じる

mysql_xdevapi\Client::close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

mysql_xdevapi\Client::close — クライアントの接続を閉じる

説明

public mysql_xdevapi\Client::close(): bool

サーバーとのクライアントの接続を全て閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

接続が閉じられれば true を返します。


Client のコンストラクタ

  • ≪ mysql_xdevapi\Client::close
  • Client::getClient ≫
  • PHP Manual
  • mysql_xdevapi\Client
  • Client のコンストラクタ

Client::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Client::__construct — Client のコンストラクタ

説明

private mysql_xdevapi\Client::__construct()

クライアントオブジェクトを構築します

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Client::__construct() の例

<?php
$pooling_options = '{
"enabled": true,
"maxSize": 10,
"maxIdleTime": 3600,
"queueTimeOut": 1000
}';
$client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
$session = $client->getSession();


クライアントのセッションを取得する

  • ≪ Client::__construct
  • mysql_xdevapi\Collection ≫
  • PHP Manual
  • mysql_xdevapi\Client
  • クライアントのセッションを取得する

Client::getClient

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Client::getClient — クライアントのセッションを取得する

説明

public mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

クライアントと関連付けられたセッションを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

セッションオブジェクトを返します。


Collection クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* プロパティ */
public $name;
/* メソッド */
public add(mixed $document): mysql_xdevapi\CollectionAdd
public addOrReplaceOne(string $id, string $doc): mysql_xdevapi\Result
public count(): int
public createIndex(string $index_name, string $index_desc_json): void
public dropIndex(string $index_name): bool
public existsInDatabase(): bool
public find(string $search_condition = ?): mysql_xdevapi\CollectionFind
public getName(): string
public getOne(string $id): Document
public getSchema(): Schema Object
public getSession(): Session
public modify(string $search_condition): mysql_xdevapi\CollectionModify
public remove(string $search_condition): mysql_xdevapi\CollectionRemove
public removeOne(string $id): mysql_xdevapi\Result
public replaceOne(string $id, string $doc): mysql_xdevapi\Result
}

プロパティ

name

目次

  • Collection::add — コレクションにドキュメントを追加する
  • Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する
  • Collection::__construct — Collection のコンストラクタ
  • Collection::count — ドキュメントの数を取得する
  • Collection::createIndex — コレクションにインデックスを作成
  • Collection::dropIndex — コレクションのインデックスを削除
  • Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする
  • Collection::find — ドキュメントを検索する
  • Collection::getName — コレクションの名前を得る
  • Collection::getOne — ドキュメントをひとつ取得
  • Collection::getSchema — スキーマオブジェクトを得る
  • Collection::getSession — セッションオブジェクトを取得
  • Collection::modify — コレクションのドキュメントを変更する
  • Collection::remove — コレクションを削除する
  • Collection::removeOne — コレクションからドキュメントをひとつ削除する
  • Collection::replaceOne — コレクションのドキュメントをひとつ置き換える


コレクションにドキュメントを追加する

  • ≪ mysql_xdevapi\Collection
  • Collection::addOrReplaceOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションにドキュメントを追加する

Collection::add

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::add — コレクションにドキュメントを追加する

説明

public mysql_xdevapi\Collection::add(mixed $document): mysql_xdevapi\CollectionAdd

与えられたドキュメントをドキュメントに追加します。 このメソッドでは、複数のバリエーションがサポートされています。 オプションは以下です:

  1. JSON 文字列として単一のドキュメントを追加する

  2. 単一のドキュメントを次のようにして配列で追加する: [ 'field' => 'value', 'field2' => 'value2' ... ]

  3. 上記２つの組み合わせ。 そして、複数のドキュメントが同じ操作で追加できます。

パラメータ

document

ひとつまたは複数のドキュメント。そして、ドキュメントは JSON または フィールドとそれに関連した値を格納した配列 として表現できます。 空の配列は受け入れられません。

MySQL サーバーは、ドキュメントごとに(推奨)自動的にユニークな _id 値を生成します。 しかし、これは手動でも追加できます。 この値はユニークでなければなりません。ユニークでない場合、操作は失敗します。

戻り値

CollectionAdd オブジェクトを返します。 影響を受けた行を調べたり、操作によって生成された警告の数を得たり、 挿入されたドキュメントのために生成された _id のリストを得るための Result オブジェクトを得るためには、 execute() を使ってください。

例

例1 mysql_xdevapi\Collection::add() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// ふたつのドキュメントを追加
$collection->add('{"name": "Fred", "age": 21, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

// JSON オブジェクトをひとつ使い、ドキュメントを2つ追加
$result = $collection->add(
'{"name": "Bernie",
"jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
"hobbies": ["Sports","Making cupcakes"]}',
'{"name": "Jane",
"jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
"hobbies": ["Walking","Making pies"]}')->execute();

// 最後の add() から生成されたIDのリストを取得
$ids = $result->getGeneratedIds();
print_r($ids);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)

注意

注意:

例で示しているように、ユニークな _id が MySQL サーバー8.0以降では生成されます。 _id フィールドは MySQLサーバー 5.7 を使っている場合は手動で定義しなければなりません。


コレクションのドキュメントを追加または置換する

  • ≪ Collection::add
  • Collection::__construct ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのドキュメントを追加または置換する

Collection::addOrReplaceOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する

説明

public mysql_xdevapi\Collection::addOrReplaceOne(string $id, string $doc): mysql_xdevapi\Result

新しいドキュメントを追加するか、既に存在する場合は置換します。

このメソッドには、複数のシナリオがあります:

  • _id やユニークキーの値がコレクション中のどのドキュメントとも衝突する場合、 ドキュメントは追加されます。

  • id がどのドキュメントともマッチしないものの、 ひとつ以上のユニークキーの値がコレクション中のドキュメントと衝突する場合、 エラーが発生します。

  • id が既に存在するドキュメントにマッチし、ユニークキーもコレクションに定義されていない場合、 ドキュメントは置き換えられます。

  • id が既に存在するドキュメントにマッチする場合、 または 同じドキュメントの全てのユニークキーのうちいずれかとマッチし id がコレクション中のドキュメントと衝突しない場合、 そのドキュメントは置き換えられます。

  • id が既に存在するドキュメントとマッチし、 ひとつ以上のユニークキーが異なるドキュメントにマッチする場合、 エラーが発生します。

パラメータ

id

フィルタid。この id または、 ユニークインデックスを持つ他のフィールドが既にコレクションに存在している場合は、 それにマッチするドキュメントを更新します。

デフォルトでは、この id はレコードが追加された時に自動的に MySQL サーバーが生成します。 そして、フィールド名 '_id' で参照されます。

doc

追加または置き換えるドキュメント。JSON文字列です。

戻り値

Result オブジェクト

例

例1 mysql_xdevapi\Collection::addOrReplaceOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// add() を使う場合
$result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

// addOrReplaceOne() を使う場合
// 注意: ここでは、既知の _id 値を渡しています
$result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred", "age": 21, "job": "Construction"}');

?>


Collection のコンストラクタ

  • ≪ Collection::addOrReplaceOne
  • Collection::count ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • Collection のコンストラクタ

Collection::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::__construct — Collection のコンストラクタ

説明

private mysql_xdevapi\Collection::__construct()

コレクションオブジェクトを構築します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Collection::getOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

// ユニークな _id が(デフォルト、そして推奨) MySQL サーバーによって生成されます
// 以下の操作で、生成された _id を取得します。この例ではひとつしかないので、 $ids[0] になります
$ids = $result->getGeneratedIds();
$alfreds_id = $ids[0];

// ...

print_r($alfreds_id);
print_r($collection->getOne($alfreds_id));
?>

上の例の出力は、 たとえば以下のようになります。

00005b6b536100000000000000b1

Array
(
    [_id] => 00005b6b536100000000000000b1
    [age] => 42
    [job] => Butler
    [name] => Alfred
)


ドキュメントの数を取得する

  • ≪ Collection::__construct
  • Collection::createIndex ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • ドキュメントの数を取得する

Collection::count

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::count — ドキュメントの数を取得する

説明

public mysql_xdevapi\Collection::count(): int

この機能は、 MySQL サーバーの現在のスキーマとコレクションに対して SELECT COUNT(*) SQL を発行する操作に似ています。 言い換えると、コレクションに存在するドキュメントの数を数えます。

パラメータ

この関数にはパラメータはありません。

戻り値

コレクションに存在するドキュメントの数

例

例1 mysql_xdevapi\Collection::count() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"jobs": [
{"title":"Cat Herder","Salary":42000},
{"title":"Father","Salary":0}
],
"hobbies": ["Sports","Making cupcakes"]}',
'{"name": "Jane",
"jobs": [
{"title":"Scientist","Salary":18000},
{"title":"Mother","Salary":0}
],
"hobbies": ["Walking","Making pies"]}')
->execute();

var_dump($collection->count());
?>

上の例の出力は以下となります。

int(2)


コレクションにインデックスを作成

  • ≪ Collection::count
  • Collection::dropIndex ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションにインデックスを作成

Collection::createIndex

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::createIndex — コレクションにインデックスを作成

説明

public mysql_xdevapi\Collection::createIndex(string $index_name, string $index_desc_json): void

コレクションにインデックスを作成します。

指定された名前と同じインデックスが既に存在していた場合、 もしくはインデックスの定義が正しくなかった場合は、 例外がスローされます。

パラメータ

index_name

作成するインデックスの名前。 この名前は、 CREATE INDEX SQLクエリが受け入れられる、 正しいものでなければなりません。

index_desc_json

作成するインデックスの定義。 IndexField オブジェクトの配列を含み、 個々のオブジェクトはインデックスに含まれる単一のドキュメントを記述します。 そして、オプションで、インデックスのタイプを示すオプションの文字列を含めます。 インデックスのタイプは、INDEX(デフォルト) または SPATIAL です。

IndexField の記述は、以下のフィールドを含みます:

  • field: 文字列。インデックスされるドキュメンメンバまたはフィールドの完全なパス

  • type: 文字列。フィールドにマップされる、サポートされたSQLカラムの型のうちひとつ。 数値型のために、オプションで UNSIGNED を後ろに続けることができます。 テキスト型のために、インデックスのために考慮する長さを追加できます。

  • required: bool。 (オプション) フィールドがドキュメントで必須である場合、trueを指定します。 デフォルトは false です。 GEOJSON では例外的に、デフォルトが true です。

  • options: integer, (オプション) GEOJSON データをデコードする時に使う特別なのオプションフラグ

  • srid: integer, (オプション) GEOJSON データをデコードする時に使う srid の値

IndexDefinition や IndexField に、上記で説明していないフィールドを含めるとエラーになります。

戻り値

例

例1 mysql_xdevapi\Collection::createIndex() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

// text index を作る
$collection->createIndex(
'myindex1',
'{"fields": [{
"field": "$.name",
"type": "TEXT(25)",
"required": true}],
"unique": false}'
);

// spatial インデックスを作る
$collection->createIndex(
'myindex2',
'{"fields": [{
"field": "$.home",
"type": "GEOJSON",
"required": true}],
"type": "SPATIAL"}'
);

// 複数のフィルードを持つインデックス
$collection->createIndex(
'myindex3',
'{"fields": [
{
"field": "$.name",
"type": "TEXT(20)",
"required": true
},
{
"field": "$.age",
"type": "INTEGER"
},
{
"field": "$.job",
"type": "TEXT(30)",
"required": false
}
],
"unique": true
}'
);


コレクションのインデックスを削除

  • ≪ Collection::createIndex
  • Collection::existsInDatabase ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのインデックスを削除

Collection::dropIndex

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::dropIndex — コレクションのインデックスを削除

説明

public mysql_xdevapi\Collection::dropIndex(string $index_name): bool

コレクションのインデックスを削除します。

この操作は、インデックスが存在しなくてもエラーは発生しません。 しかし、その場合には false を返します。

パラメータ

index_name

削除するコレクションのインデックスの名前

戻り値

DROP INDEX の操作が成功したら true そうでなければ false

例

例1 mysql_xdevapi\Collection::dropIndex() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

// ...

$collection = $schema->getCollection("people");

$collection->createIndex(
'myindex',
'{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
);

// ...

if ($collection->dropIndex('myindex')) {
echo "An index named 'myindex' was found, and dropped.";
}
?>

上の例の出力は以下となります。

An index named 'myindex' was found, and dropped.


コレクションがデータベースに存在するかをチェックする

  • ≪ Collection::dropIndex
  • Collection::find ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションがデータベースに存在するかをチェックする

Collection::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする

説明

public mysql_xdevapi\Collection::existsInDatabase(): bool

コレクションオブジェクトが、データベース(スキーマ)内のコレクションを参照しているかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

コレクションがデータベースに存在していれば true を返します。 そうでなければ、false を返します。

2つのカラム (doc と _id) で定義されたテーブルは、 コレクションと見なされます。 MySQL 8.0.21 以降では、doc, _id, _json_schema の3つのカラムで構成されたテーブルが コレクションと見なされます。 これに対してカラムを追加すると、 existsInDatabase() はコレクションとは見なさなくなります。

例

例1 mysql_xdevapi\Collection::existsInDatabase() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

// ...

$collection = $schema->getCollection("people");

// ...

if (!$collection->existsInDatabase()) {
echo "The collection no longer exists in the database named addressbook. What happened?";
}
?>


ドキュメントを検索する

  • ≪ Collection::existsInDatabase
  • Collection::getName ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • ドキュメントを検索する

Collection::find

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::find — ドキュメントを検索する

説明

public mysql_xdevapi\Collection::find(string $search_condition = ?): mysql_xdevapi\CollectionFind

ドキュメントが属するデータベースコレクションやドキュメントの集合を検索します。 見つかったドキュメントは CollectionFind オブジェクトとして返され、 後の変更や結果の取得に使えます。

パラメータ

search_condition

オプションですが、通常はドキュメントのサブセットの結果を限定するために条件を定義します。

複数の要素が条件を構成できますし、条件の文法はパラメータのバインドもサポートしています。 検索条件として使える式は MySQL で有効なものでなければなりません。 検索条件が与えられない(フィールドが空)場合、find('true') が与えられたと見做されます。

戻り値

操作を検証したり、見つかったドキュメントを取得するための CollectionFind オブジェクト

例

例1 mysql_xdevapi\Collection::find() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob", "age": 19, "job": "Swimmer"}')->execute();
$collection->add('{"name": "Fred", "age": 20, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma", "age": 21, "job": "Teacher"}')->execute();
$collection->add('{"name": "Suki", "age": 22, "job": "Teacher"}')->execute();

$find = $collection->find('job LIKE :job AND age > :age');
$result = $find
->bind(['job' => 'Teacher', 'age' => 20])
->sort('age DESC')
->limit(2)
->execute();

print_r($result->fetchAll());
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b536100000000000000a8
            [age] => 22
            [job] => Teacher
            [name] => Suki
        )
    [1] => Array
        (
            [_id] => 00005b6b536100000000000000a7
            [age] => 21
            [job] => Teacher
            [name] => Wilma
        )
)


コレクションの名前を得る

  • ≪ Collection::find
  • Collection::getOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションの名前を得る

Collection::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getName — コレクションの名前を得る

説明

public mysql_xdevapi\Collection::getName(): string

コレクションの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

コレクションの名前を文字列で返します。

例

例1 mysql_xdevapi\Collection::getName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

// ...

var_dump($collection->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(6) "people"


ドキュメントをひとつ取得

  • ≪ Collection::getName
  • Collection::getSchema ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • ドキュメントをひとつ取得

Collection::getOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getOne — ドキュメントをひとつ取得

説明

public mysql_xdevapi\Collection::getOne(string $id): Document

コレクションから、ドキュメントをひとつ取得します。

これは、以下のコードのショートカットです: Collection.find("_id = :id").bind("id", id).execute().fetchOne();

パラメータ

id

コレクションのドキュメントの _id

戻り値

コレクションオブジェクトを返します。 _id にドキュメントがマッチしなければ、null を返します。

例

例1 mysql_xdevapi\Collection::getOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

// A unique _id is (by default, and recommended) generated by MySQL Server
// This retrieves the generated _id's; only one in this example, so $ids[0]
$ids = $result->getGeneratedIds();
$alfreds_id = $ids[0];

// ...

print_r($alfreds_id);
print_r($collection->getOne($alfreds_id));
?>

上の例の出力は、 たとえば以下のようになります。

00005b6b536100000000000000b1

Array
(
    [_id] => 00005b6b536100000000000000b1
    [age] => 42
    [job] => Butler
    [name] => Alfred
)


スキーマオブジェクトを得る

  • ≪ Collection::getOne
  • Collection::getSession ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • スキーマオブジェクトを得る

Collection::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getSchema — スキーマオブジェクトを得る

説明

public mysql_xdevapi\Collection::getSchema(): Schema Object

コレクションを含むスキーマオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功すれば、スキーマオブジェクト。 与えられたコレクションのスキーマオブジェクトを取得できなければ、null を返します。

例

例1 mysql_xdevapi\Collection::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

var_dump($collection->getSchema());
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Schema)#9 (1) {
  ["name"]=>
  string(11) "addressbook"
}


セッションオブジェクトを取得

  • ≪ Collection::getSchema
  • Collection::modify ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • セッションオブジェクトを取得

Collection::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::getSession — セッションオブジェクトを取得

説明

public mysql_xdevapi\Collection::getSession(): Session

コレクションオブジェクトから、新しいセッションオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

セッションオブジェクトを返します。

例

例1 mysql_xdevapi\Collection::getSession() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

// ...

$newsession = $collection->getSession();

var_dump($session);
var_dump($newsession);
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Session)#1 (0) {
}
object(mysql_xdevapi\Session)#4 (0) {
}


コレクションのドキュメントを変更する

  • ≪ Collection::getSession
  • Collection::remove ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのドキュメントを変更する

Collection::modify

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::modify — コレクションのドキュメントを変更する

説明

public mysql_xdevapi\Collection::modify(string $search_condition): mysql_xdevapi\CollectionModify

特定の検索条件にマッチするドキュメントのコレクションを変更します。 複数の操作が可能であり、パラメータのバインドもサポートされています。

パラメータ

search_condition

変更するドキュメントに マッチさせるために使う、有効な MySQL の式でなければなりません。 この式は、true と評価される単純なものであれば可能です。 true と評価された全てのドキュメントにマッチします。 もしくは、関数と指揮を次のように使うこともできます。 'CAST(_id AS SIGNED) >= 10', 'age MOD 2 = 0 OR age MOD 3 = 0', '_id IN ["2","5","7","10"]'.

戻り値

操作が実行されない場合、この関数は追加の変更操作を追加できる Modify オブジェクトを返します。

変更操作が実行された場合、返されるオブジェクトには操作結果が含まれます。

例

例1 mysql_xdevapi\Collection::modify() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob", "age": 19, "job": "Painter"}')->execute();

// 全ての Painter のばめに、ふたつ job を追加: Artist と Crafter です
$collection
->modify("job in ('Butler', 'Painter')")
->arrayAppend('job', 'Artist')
->arrayAppend('job', 'Crafter')
->execute();

// age が 21 の全てのドキュメントから、'beer' フィールドを削除
$collection
->modify('age < 21')
->unset(['beer'])
->execute();
?>


コレクションを削除する

  • ≪ Collection::modify
  • Collection::removeOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションを削除する

Collection::remove

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::remove — コレクションを削除する

説明

public mysql_xdevapi\Collection::remove(string $search_condition): mysql_xdevapi\CollectionRemove

特定の検索条件に合致するドキュメントのコレクションを削除します。 複数の操作が可能で、パラメータのバインドもサポートしています。

パラメータ

search_condition

削除するドキュメントに マッチさせるために使う、有効な MySQL の式でなければなりません。 この式は、true と評価される単純なものであれば可能です。 true と評価された全てのドキュメントにマッチします。 もしくは、関数と指揮を次のように使うこともできます。 'CAST(_id AS SIGNED) >= 10', 'age MOD 2 = 0 OR age MOD 3 = 0', '_id IN ["2","5","7","10"]'.

戻り値

操作が実行されない場合、この関数は追加の削除操作を追加できる Remove オブジェクトを返します。

削除操作が実行された場合、返されるオブジェクトには操作結果が含まれます。

例

例1 mysql_xdevapi\Collection::remove() example

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob", "age": 19, "job": "Painter"}')->execute();

// 全ての Painter を削除
$collection
->remove("job in ('Painter')")
->execute();

// もっとも古い Bulter を削除
$collection
->remove("job in ('Butler')")
->sort('age desc')
->limit(1)
->execute();

// age が一番低いレコードを削除
$collection
->remove('true')
->sort('age desc')
->limit(1)
->execute();
?>


コレクションからドキュメントをひとつ削除する

  • ≪ Collection::remove
  • Collection::replaceOne ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションからドキュメントをひとつ削除する

Collection::removeOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::removeOne — コレクションからドキュメントをひとつ削除する

説明

public mysql_xdevapi\Collection::removeOne(string $id): mysql_xdevapi\Result

指定したIDに対応するドキュメントをコレクションから削除する。 これは、Collection.remove("_id = :id").bind("id", id).execute() のショートカットです。

パラメータ

id

削除するコレクションのドキュメントのID。 これは、通常はレコードが追加されたときに MySQLサーバー が生成した _id の値です。

戻り値

影響を受けたアイテムの数、 または、操作によって発生した警告の数 を問い合わせるために使われる Resultオブジェクト。

例

例1 mysql_xdevapi\Collection::removeOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

// Normally the _id is known by other means,
// but for this example let's fetch the generated id and use it
$ids = $result->getGeneratedIds();
$alfred_id = $ids[0];

$result = $collection->removeOne($alfred_id);

if(!$result->getAffectedItemsCount()) {
echo "Alfred with id $alfred_id was not removed.";
} else {
echo "Goodbye, Alfred, you can take _id $alfred_id with you.";
}
?>

上の例の出力は、 たとえば以下のようになります。

Goodbye, Alfred, you can take _id 00005b6b536100000000000000cb with you.


コレクションのドキュメントをひとつ置き換える

  • ≪ Collection::removeOne
  • mysql_xdevapi\CollectionAdd ≫
  • PHP Manual
  • mysql_xdevapi\Collection
  • コレクションのドキュメントをひとつ置き換える

Collection::replaceOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Collection::replaceOne — コレクションのドキュメントをひとつ置き換える

説明

public mysql_xdevapi\Collection::replaceOne(string $id, string $doc): mysql_xdevapi\Result

ID で特定されたドキュメントが存在すれば、それを更新(置き換え)します。

パラメータ

id

置き換え、または更新するドキュメントのID。 通常、これは レコードを追加した時に MySQL サーバーが生成した _id です。

doc

id パラメータにマッチするドキュメントを更新したり 置換したりするためのコレクションのドキュメント

このドキュメントは、ドキュメントオブジェクトか、 新しいドキュメントを表現する 有効な JSON 文字列のどちらかです。

戻り値

影響を受けた行を調べたり、 操作によって生成された警告の数を得ることができる Result オブジェクトを返します。

例

例1 mysql_xdevapi\Collection::replaceOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

// 通常、_id は他の手段によって知ることができますが、
// この例のために、生成された id を取得し、それを使います。
$ids = $result->getGeneratedIds();
$alfred_id = $ids[0];

// ...

$alfred = $collection->getOne($alfred_id);
$alfred['age'] = 81;
$alfred['job'] = 'Guru';

$collection->replaceOne($alfred_id, $alfred);

?>


CollectionAdd クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* メソッド */
public execute(): mysql_xdevapi\Result
}

目次

  • CollectionAdd::__construct — CollectionAdd のコンストラクタ
  • CollectionAdd::execute — ステートメントを実行する


CollectionAdd のコンストラクタ

  • ≪ mysql_xdevapi\CollectionAdd
  • CollectionAdd::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionAdd
  • CollectionAdd のコンストラクタ

CollectionAdd::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionAdd::__construct — CollectionAdd のコンストラクタ

説明

private mysql_xdevapi\CollectionAdd::__construct()

コレクションにドキュメントを追加するために使います。 ;コレクションオブジェクトから呼び出されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\CollectionAdd::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// ドキュメントをふたつ追加
$collection
->add('{"name": "Fred", "age": 21, "job": "Construction"}')
->execute();

$collection
->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
->execute();

// 単一のJSONオブジェクトを使い、ドキュメントをふたつ追加
$result = $collection
->add(
'{"name": "Bernie",
"jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
"hobbies": ["Sports","Making cupcakes"]}',
'{"name": "Jane",
"jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
"hobbies": ["Walking","Making pies"]}')
->execute();

// 最後の add() から生成された ID のリストを取得
$ids = $result->getGeneratedIds();
print_r($ids);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)

注意

注意:

例で示したように、MySQL 8.0 以上では、ユニークな _id が生成されます。 _id フィールドは、MySQLサーバー 5.7 を使っている場合、手動で定義しなければなりません。


ステートメントを実行する

  • ≪ CollectionAdd::__construct
  • mysql_xdevapi\CollectionFind ≫
  • PHP Manual
  • mysql_xdevapi\CollectionAdd
  • ステートメントを実行する

CollectionAdd::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionAdd::execute — ステートメントを実行する

説明

public mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

CRUD操作のリクエストを MySQL サーバーに送信するために execute メソッドは必須です。

パラメータ

この関数にはパラメータはありません。

戻り値

影響を受けた行数のような、操作の状態を確認するのに使われる Result オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionAdd::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

// ドキュメントをふたつ追加
$collection
->add('{"name": "Fred", "age": 21, "job": "Construction"}')
->execute();

$collection
->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
->execute();

// 単一のJSONオブジェクトを使い、ドキュメントをふたつ追加
$result = $collection
->add(
'{"name": "Bernie",
"jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
"hobbies": ["Sports","Making cupcakes"]}',
'{"name": "Jane",
"jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
"hobbies": ["Walking","Making pies"]}')
->execute();

// 最後の add() から生成された ID のリストを取得
$ids = $result->getGeneratedIds();
print_r($ids);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 00005b6b53610000000000000056
    [1] => 00005b6b53610000000000000057
)


CollectionFind クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* メソッド */
public bind(array $placeholder_values): mysql_xdevapi\CollectionFind
public execute(): mysql_xdevapi\DocResult
public fields(string $projection): mysql_xdevapi\CollectionFind
public groupBy(string $sort_expr): mysql_xdevapi\CollectionFind
public having(string $sort_expr): mysql_xdevapi\CollectionFind
public limit(int $rows): mysql_xdevapi\CollectionFind
public lockExclusive(int $lock_waiting_option = ?): mysql_xdevapi\CollectionFind
public lockShared(int $lock_waiting_option = ?): mysql_xdevapi\CollectionFind
public offset(int $position): mysql_xdevapi\CollectionFind
public sort(string $sort_expr): mysql_xdevapi\CollectionFind
}

目次

  • CollectionFind::bind — クエリのプレースホルダーに値をバインドする
  • CollectionFind::__construct — CollectionFind のコンストラクタ
  • CollectionFind::execute — ステートメントを実行する
  • CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する
  • CollectionFind::groupBy — グループ化の条件を設定する
  • CollectionFind::having — 集約関数の条件を設定する
  • CollectionFind::limit — 返されるドキュメントの数を限定する
  • CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK
  • CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する
  • CollectionFind::offset — 返される要素の数から、与えられた数をスキップする
  • CollectionFind::sort — ソート条件を設定する


クエリのプレースホルダーに値をバインドする

  • ≪ mysql_xdevapi\CollectionFind
  • CollectionFind::__construct ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • クエリのプレースホルダーに値をバインドする

CollectionFind::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::bind — クエリのプレースホルダーに値をバインドする

説明

public mysql_xdevapi\CollectionFind::bind(array $placeholder_values): mysql_xdevapi\CollectionFind

ユーザーは、検索条件または検索の操作の中で、 プレースホルダーに対してパラメータをバインドできます。 プレースホルダーは :NAME というフォーマットで、 ':' は NAME の前に常に存在しなければいけない 共通のプレフィックスです。NAME はプレースホルダーの実際の名前です。 この関数は、複数のエンティティを検索時に置き換える必要がある場合、 プレースホルダーのリストを受け付けます。

パラメータ

placeholder_values

検索条件の中で置き換える値。 複数の値が許されていますし、配列の中で "PLACEHOLDER_NAME => PLACEHOLDER_VALUE" のような形で渡すこともできます。

戻り値

CollectionFind オブジェクト。 または、Result オブジェクトを取得するために execute() とチェインさせることもできます。

例

例1 mysql_xdevapi\CollectionFind::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$result = $create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000cf"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
}


CollectionFind のコンストラクタ

  • ≪ CollectionFind::bind
  • CollectionFind::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • CollectionFind のコンストラクタ

CollectionFind::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::__construct — CollectionFind のコンストラクタ

説明

private mysql_xdevapi\CollectionFind::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 CollectionFind の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$result = $create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000cf"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
}


ステートメントを実行する

  • ≪ CollectionFind::__construct
  • CollectionFind::fields ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • ステートメントを実行する

CollectionFind::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::execute — ステートメントを実行する

説明

public mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

find 操作を実行します。 この操作は、メソッドのチェインも許可しています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果を取得したり、操作の状態を問い合わせるための mysql_xdevapi\DocResult オブジェクトを返します。

例

例1 CollectionFind の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000cf"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
}


ドキュメントのフィールドのフィルタを設定する

  • ≪ CollectionFind::execute
  • CollectionFind::groupBy ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • ドキュメントのフィールドのフィルタを設定する

CollectionFind::fields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する

説明

public mysql_xdevapi\CollectionFind::fields(string $projection): mysql_xdevapi\CollectionFind

クエリによって返されるカラムを設定します。 設定されない場合は、全てのカラムが使われます。

パラメータ

projection

単一の文字列か、文字列の配列。 検索条件にマッチするドキュメント単位で返されるカラムを識別します。

戻り値

後の処理に使える CollectionFind を返します。

例

例1 mysql_xdevapi\CollectionFind::fields() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->fields('name')
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(1) {
    ["name"]=>
    string(6) "Alfred"
  }
}


グループ化の条件を設定する

  • ≪ CollectionFind::fields
  • CollectionFind::having ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • グループ化の条件を設定する

CollectionFind::groupBy

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::groupBy — グループ化の条件を設定する

説明

public mysql_xdevapi\CollectionFind::groupBy(string $sort_expr): mysql_xdevapi\CollectionFind

この関数は、結果セットをひとつまたはそれ以上のカラムによってグループ化するのに使えます。 COUNT, MAX, MIN, SUM のような集約関数とともによく使います。

パラメータ

sort_expr

グループ化の操作のために使われるカラム。 これは文字列か、カラムをあらわす文字列の配列のうちのどちらかです。

戻り値

その後の処理に使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::groupBy() の例

<?php

// Assuming $coll is a valid Collection object

// Extract all the documents from the Collection and group the results by the 'name' field
$res = $coll->find()->groupBy('name')->execute();

?>


集約関数の条件を設定する

  • ≪ CollectionFind::groupBy
  • CollectionFind::limit ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • 集約関数の条件を設定する

CollectionFind::having

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::having — 集約関数の条件を設定する

説明

public mysql_xdevapi\CollectionFind::having(string $sort_expr): mysql_xdevapi\CollectionFind

この関数は、展開するドキュメントを選択するために、 'field' 操作の後で使えます。

パラメータ

sort_expr

有効な SQL の式でなければなりません。 集約関数を使うこともできます。

戻り値

後の操作で使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::having() の例

<?php

// $coll は、有効な Collection オブジェクトとします

// 'age' が40以上の全てのドキュメントを検索し、
// カラム 'name' と 'age' のみを Result オブジェクトとして返します。
$res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

?>


返されるドキュメントの数を限定する

  • ≪ CollectionFind::having
  • CollectionFind::lockExclusive ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • 返されるドキュメントの数を限定する

CollectionFind::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::limit — 返されるドキュメントの数を限定する

説明

public mysql_xdevapi\CollectionFind::limit(int $rows): mysql_xdevapi\CollectionFind

返されるドキュメントの最大数を設定します。

パラメータ

rows

ドキュメントの最大数

戻り値

追加の操作に使える CollectionFind オブジェクトを返します。 DocResult オブジェクトを返す execute() メソッドとチェインできます。

例

例1 mysql_xdevapi\CollectionFind::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();
$create
->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->sort('age desc')
->limit(1)
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000f3"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}


Execute operation with EXCLUSIVE LOCK

  • ≪ CollectionFind::limit
  • CollectionFind::lockShared ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • Execute operation with EXCLUSIVE LOCK

CollectionFind::lockExclusive

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK

説明

public mysql_xdevapi\CollectionFind::lockExclusive(int $lock_waiting_option = ?): mysql_xdevapi\CollectionFind

ドキュメントを排他ロックします。 ドキュメントがロックされている間、 他のトランザクションはドキュメントを更新できませんし、 SELECT ... LOCK IN SHARE MODE を使ったり、 トランザクション分離レベルにあるデータの読み取りができません。 一貫性のある読み取りはあらゆるロックを無視します。

並列処理の問題を避けるために、この機能は mysql_xdevapi\Collection::modify() コマンドから直接使うのが有用です。 基本的に、このコマンドは行ロックを通してアクセスを直列化します。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

戻り値

後の処理に使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::lockExclusive() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$session->startTransaction();

$result = $collection
->find("age > 50")
->lockExclusive()
->execute();

// ... do an operation on the object

// Complete the transaction and unlock the document
$session->commit();
?>


SHARED LOCK 付きで操作を実行する

  • ≪ CollectionFind::lockExclusive
  • CollectionFind::offset ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • SHARED LOCK 付きで操作を実行する

CollectionFind::lockShared

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する

説明

public mysql_xdevapi\CollectionFind::lockShared(int $lock_waiting_option = ?): mysql_xdevapi\CollectionFind

ロックを共有モードで使う複数のトランザクション間で、ドキュメントを共有することができます。

他のセッションからは行を読めますが、あなたがトランザクションをコミットするまで変更できません。

もしまだコミットしていない別のトランザクションから、これらの行が変更された場合、クエリは、トランザクションが終了し、最新の値を使うまで待たされます。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

戻り値

後の処理で使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::lockShared() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$session->startTransaction();

$result = $collection
->find("age > 50")
->lockShared()
->execute();

// ... read the object in shared mode

// Complete the transaction and unlock the document
$session->commit();
?>


返される要素の数から、与えられた数をスキップする

  • ≪ CollectionFind::lockShared
  • CollectionFind::sort ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • 返される要素の数から、与えられた数をスキップする

CollectionFind::offset

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::offset — 返される要素の数から、与えられた数をスキップする

説明

public mysql_xdevapi\CollectionFind::offset(int $position): mysql_xdevapi\CollectionFind

find 操作によって返されたはずの要素から、指定された数の要素(offset) をスキップします。 limit() メソッドと一緒に使います。

結果セットのサイズとよりも大きな offset を指定すると、空の結果セットが返されます。

パラメータ

position

limit() 操作のためにスキップする要素の数

戻り値

追加の操作に使える CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::offset() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();
$create
->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find()
->sort('age asc')
->offset(1)
->limit(1)
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000f3"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}


ソート条件を設定する

  • ≪ CollectionFind::offset
  • mysql_xdevapi\CollectionModify ≫
  • PHP Manual
  • mysql_xdevapi\CollectionFind
  • ソート条件を設定する

CollectionFind::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionFind::sort — ソート条件を設定する

説明

public mysql_xdevapi\CollectionFind::sort(string $sort_expr): mysql_xdevapi\CollectionFind

sort_expr 引数で、選択されるフィールドによって結果をソートします。 可能なソート順は ASC(昇順) または DESC (降順) です。 この操作は SQL の 'ORDER BY' と同等で、同じルールに従います。

パラメータ

sort_expr

ひとつ以上のソート式が指定できます。 評価は左から右に行われ、個別の式はコンマで区切ります。

戻り値

コマンドを実行したり、追加の操作を追加できる CollectionFind オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionFind::sort() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");
$create
->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
->execute();
$create
->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
->execute();

// ...

$collection = $schema->getCollection("people");

$result = $collection
->find()
->sort('job desc', 'age asc')
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000106"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }
  [1]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000107"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}


CollectionModify クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* メソッド */
public arrayAppend(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify
public arrayInsert(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify
public bind(array $placeholder_values): mysql_xdevapi\CollectionModify
public execute(): mysql_xdevapi\Result
public limit(int $rows): mysql_xdevapi\CollectionModify
public patch(string $document): mysql_xdevapi\CollectionModify
public replace(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify
public set(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify
public skip(int $position): mysql_xdevapi\CollectionModify
public sort(string $sort_expr): mysql_xdevapi\CollectionModify
public unset(array $fields): mysql_xdevapi\CollectionModify
}

目次

  • CollectionModify::arrayAppend — 配列のフィールドに要素を追加する
  • CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する
  • CollectionModify::bind — クエリのプレースホルダーに値をバインドする
  • CollectionModify::__construct — CollectionModify のコンストラクタ
  • CollectionModify::execute — 変更の操作を実行する
  • CollectionModify::limit — 変更されるドキュメントの数を限定する
  • CollectionModify::patch — document にパッチを当てる
  • CollectionModify::replace — ドキュメントのフィールドを置き換える
  • CollectionModify::set — ドキュメントの属性を設定する
  • CollectionModify::skip — 要素をスキップする
  • CollectionModify::sort — ソート条件を設定する
  • CollectionModify::unset — ドキュメントのフィールドの値を削除する


配列のフィールドに要素を追加する

  • ≪ mysql_xdevapi\CollectionModify
  • CollectionModify::arrayInsert ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 配列のフィールドに要素を追加する

CollectionModify::arrayAppend

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::arrayAppend — 配列のフィールドに要素を追加する

説明

public mysql_xdevapi\CollectionModify::arrayAppend(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify

ドキュメントのフィールドに要素を追加します。 フィールドの複数の要素は配列として表現されます。 arrayInsert() と異なり、arrayAppend() は常に新しい要素を配列の最後に追加します。 一方で、arrayInsert() は挿入する位置を指定できます。

パラメータ

collection_field

新しい要素を挿入するフィールドの識別子

expression_or_literal

ドキュメントフィールドの配列の最後に挿入する新しい要素

戻り値

コマンドを実行したり、追加の操作を追加できる CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::arrayAppend() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"traits": ["Friend", "Brother", "Human"]}')
->execute();

$collection
->modify("name in ('Bernie', 'Jane')")
->arrayAppend('traits', 'Happy')
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b5361000000000000010c
            [name] => Bernie
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                    [3] => Happy
                )
        )
)


配列のフィールドに要素を挿入する

  • ≪ CollectionModify::arrayAppend
  • CollectionModify::bind ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 配列のフィールドに要素を挿入する

CollectionModify::arrayInsert

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する

説明

public mysql_xdevapi\CollectionModify::arrayInsert(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify

ドキュメントのフィールドに要素を追加します。 フィールドの複数の要素は配列として表現されます。 mysql_xdevapi\CollectionModify::arrayAppend() と異なり、このメソッドは新しい要素をどこに挿入するかを指定できます。常に新しい要素を配列の最後に追加します。 一方で、mysql_xdevapi\CollectionModify::arrayAppend() は新しい要素を常に配列の最後に追加します。

パラメータ

collection_field

新しい要素が挿入される配列中の要素を識別します。 このパラメータのフォーマットは FIELD_NAME[ INDEX ] です。 FIELD_NAME は、要素を削除するドキュメントフィールドの名前で、 INDEX はフィールド内の要素のインデックスです。

INDEX フィールドは0から始まります。 よって、配列の最初のインデックスは0です。

expression_or_literal

FIELD_NAME[ INDEX ] の後に挿入する新しい要素

戻り値

コマンドを実行したり、追加の操作を追加できる CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::arrayInsert() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"traits": ["Friend", "Brother", "Human"]}')
->execute();

$collection
->modify("name in ('Bernie', 'Jane')")
->arrayInsert('traits[1]', 'Happy')
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b5361000000000000010d
            [name] => Bernie
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Happy
                    [2] => Brother
                    [3] => Human
                )
        )
)


クエリのプレースホルダーに値をバインドする

  • ≪ CollectionModify::arrayInsert
  • CollectionModify::__construct ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • クエリのプレースホルダーに値をバインドする

CollectionModify::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::bind — クエリのプレースホルダーに値をバインドする

説明

public mysql_xdevapi\CollectionModify::bind(array $placeholder_values): mysql_xdevapi\CollectionModify

変更操作の検索条件のプレースホルダーにパラメータをバインドします。

プレースホルダーは :NAME というフォーマットで、 ':' は NAME の前に常に存在しなければいけない 共通のプレフィックスです。NAME はプレースホルダーの実際の名前です。 この関数は、複数のエンティティを変更操作の検索時に置き換える必要がある場合、 プレースホルダーのリストを受け付けます。

パラメータ

placeholder_values

検索条件の中で置き換える値。 複数の値が許されていますし、配列の中で "PLACEHOLDER_NAME => PLACEHOLDER_VALUE" のような形で渡すこともできます。

戻り値

コマンドを実行したり、追加の操作を追加するために使う CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"traits": ["Friend", "Brother", "Human"]}')
->execute();

$collection
->modify("name = :name")
->bind(['name' => 'Bernie'])
->arrayAppend('traits', 'Happy')
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b53610000000000000110
            [name] => Bernie
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                    [3] => Happy
                )
        )
)


CollectionModify のコンストラクタ

  • ≪ CollectionModify::bind
  • CollectionModify::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • CollectionModify のコンストラクタ

CollectionModify::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::__construct — CollectionModify のコンストラクタ

説明

private mysql_xdevapi\CollectionModify::__construct()

コレクションを変更 (更新) します。 そして、mysql_xdevapi\Collection::modify() によってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\CollectionModify::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"traits": ["Friend", "Brother", "Human"]}')
->execute();

$collection
->modify("name in ('Bernie', 'Jane')")
->arrayAppend('traits', 'Happy')
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b5361000000000000010c
            [name] => Bernie
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                    [3] => Happy
                )
        )
)


変更の操作を実行する

  • ≪ CollectionModify::__construct
  • CollectionModify::limit ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 変更の操作を実行する

CollectionModify::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::execute — 変更の操作を実行する

説明

public mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

MySQLサーバーに CRUD 操作のリクエストを送信するために、 execute メソッドは必須です。

パラメータ

この関数にはパラメータはありません。

戻り値

影響を受けた行数のような、操作の状態を確認するために使われる Result オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::execute() の例

<?php

/* ... */

?>


変更されるドキュメントの数を限定する

  • ≪ CollectionModify::execute
  • CollectionModify::patch ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 変更されるドキュメントの数を限定する

CollectionModify::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::limit — 変更されるドキュメントの数を限定する

説明

public mysql_xdevapi\CollectionModify::limit(int $rows): mysql_xdevapi\CollectionModify

この操作によって、変更されるドキュメントの数を限定します。 オプションで、skip() と組み合わせることで、オフセット値を定義します。

パラメータ

rows

変更するドキュメントの最大数

戻り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Fred", "age": 21, "job": "Construction"}')->execute();
$collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
$collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

$collection
->modify("job = :job")
->bind(['job' => 'Teacher'])
->set('job', 'Principal')
->limit(1)
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b53610000000000000118
            [age] => 21
            [job] => Construction
            [name] => Fred
        )
    [1] => Array
        (
            [_id] => 00005b6b53610000000000000119
            [age] => 23
            [job] => Principal
            [name] => Wilma
        )
    [2] => Array
        (
            [_id] => 00005b6b5361000000000000011a
            [age] => 24
            [job] => Teacher
            [name] => Betty
        )
)


document にパッチを当てる

  • ≪ CollectionModify::limit
  • CollectionModify::replace ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • document にパッチを当てる

CollectionModify::patch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::patch — document にパッチを当てる

説明

public mysql_xdevapi\CollectionModify::patch(string $document): mysql_xdevapi\CollectionModify

Patch オブジェクトを取得し、ひとつ以上のドキュメントに適用し、 そして複数のドキュメントのプロパティを更新します。

パラメータ

document

マッチするドキュメントに適用するプロパティを持ったドキュメント

戻り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::patch() の例

<?php

$res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

?>


ドキュメントのフィールドを置き換える

  • ≪ CollectionModify::patch
  • CollectionModify::set ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ドキュメントのフィールドを置き換える

CollectionModify::replace

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::replace — ドキュメントのフィールドを置き換える

説明

public mysql_xdevapi\CollectionModify::replace(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify

与えられたフィールドの値を、新しいもので置き換え(更新し)ます。

パラメータ

collection_field

設定するアイテムのドキュメントパス

expression_or_literal

指定された属性に設定する値

戻り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::replace() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"traits": ["Friend", "Brother", "Human"]}')
->execute();

$collection
->modify("name = :name")
->bind(['name' => 'Bernie'])
->replace("name", "Bern")
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b5361000000000000011b
            [name] => Bern
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                )
        )
)


ドキュメントの属性を設定する

  • ≪ CollectionModify::replace
  • CollectionModify::skip ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ドキュメントの属性を設定する

CollectionModify::set

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::set — ドキュメントの属性を設定する

説明

public mysql_xdevapi\CollectionModify::set(string $collection_field, string $expression_or_literal): mysql_xdevapi\CollectionModify

コレクション中のドキュメントの属性を設定、または更新します。

パラメータ

collection_field

設定するアイテムのドキュメントパス(名前)

expression_or_literal

設定する値

戻り値

CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::set() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$result = $collection
->add(
'{"name": "Bernie",
"traits": ["Friend", "Brother", "Human"]}')
->execute();

$collection
->modify("name = :name")
->bind(['name' => 'Bernie'])
->set("name", "Bern")
->execute();

$result = $collection
->find()
->execute();

print_r($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [_id] => 00005b6b53610000000000000111
            [name] => Bern
            [traits] => Array
                (
                    [0] => Friend
                    [1] => Brother
                    [2] => Human
                )
        )
)


要素をスキップする

  • ≪ CollectionModify::set
  • CollectionModify::sort ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • 要素をスキップする

CollectionModify::skip

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::skip — 要素をスキップする

説明

public mysql_xdevapi\CollectionModify::skip(int $position): mysql_xdevapi\CollectionModify

スキップしなければ find によって返される最初の N 要素をスキップします。 スキップされる要素の数が、結果セットのサイズより大きかった場合は、 空の結果セットが返されます。

パラメータ

position

スキップする要素数

戻り値

後の操作で使われる CollectionModify オブジェクト。

例

例1 mysql_xdevapi\CollectionModify::skip() の例

<?php

$coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

?>


ソート条件を設定する

  • ≪ CollectionModify::skip
  • CollectionModify::unset ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ソート条件を設定する

CollectionModify::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::sort — ソート条件を設定する

説明

public mysql_xdevapi\CollectionModify::sort(string $sort_expr): mysql_xdevapi\CollectionModify

sort_expr 引数によって指定されたフィールドによって、結果セットをソートします。 可能なソート順は ASC(昇順) または DESC (降順) です。 この操作は SQL の 'ORDER BY' と同等で、同じルールに従います。

パラメータ

sort_expr

ひとつ以上のソート式が指定できます。 評価は左から右に行われ、個別の式はコンマで区切ります。

戻り値

以後の操作に使える CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::sort() の例

<?php

$res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

?>


ドキュメントのフィールドの値を削除する

  • ≪ CollectionModify::sort
  • mysql_xdevapi\CollectionRemove ≫
  • PHP Manual
  • mysql_xdevapi\CollectionModify
  • ドキュメントのフィールドの値を削除する

CollectionModify::unset

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionModify::unset — ドキュメントのフィールドの値を削除する

説明

public mysql_xdevapi\CollectionModify::unset(array $fields): mysql_xdevapi\CollectionModify

コレクションのドキュメントから、属性を削除します。

パラメータ

fields

コレクションのドキュメントから削除する属性

戻り値

その後の処理で使える CollectionModify オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionModify::unset() の例

<?php

$res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

?>


CollectionRemove クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* メソッド */
public bind(array $placeholder_values): mysql_xdevapi\CollectionRemove
public execute(): mysql_xdevapi\Result
public limit(int $rows): mysql_xdevapi\CollectionRemove
public sort(string $sort_expr): mysql_xdevapi\CollectionRemove
}

目次

  • CollectionRemove::bind — プレースホルダーに値をバインドする
  • CollectionRemove::__construct — CollectionRemove のコンストラクタ
  • CollectionRemove::execute — 削除操作を実行する
  • CollectionRemove::limit — 削除するドキュメントの数を限定する
  • CollectionRemove::sort — ソート条件を設定する


プレースホルダーに値をバインドする

  • ≪ mysql_xdevapi\CollectionRemove
  • CollectionRemove::__construct ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • プレースホルダーに値をバインドする

CollectionRemove::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::bind — プレースホルダーに値をバインドする

説明

public mysql_xdevapi\CollectionRemove::bind(array $placeholder_values): mysql_xdevapi\CollectionRemove

削除操作の検索条件のプレースホルダーにパラメータをバインドします。

プレースホルダーは :NAME というフォーマットで、 ':' は NAME の前に常に存在しなければいけない 共通のプレフィックスです。NAME はプレースホルダーの実際の名前です。 この関数は、複数のエンティティを削除操作の検索時に置き換える必要がある場合、 プレースホルダーのリストを受け付けます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

placeholder_values

検索条件の中で置き換える値。 複数の値が許されていますし、配列の中で "PLACEHOLDER_NAME => PLACEHOLDER_VALUE" のような形で渡すこともできます。

戻り値

コマンドを実行したり、追加の操作を追加するために使う CollectionRemove オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionRemove::bind() の例

<?php

$res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

?>


CollectionRemove のコンストラクタ

  • ≪ CollectionRemove::bind
  • CollectionRemove::execute ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • CollectionRemove のコンストラクタ

CollectionRemove::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::__construct — CollectionRemove のコンストラクタ

説明

private mysql_xdevapi\CollectionRemove::__construct()

コレクションのドキュメントを削除します。 mysql_xdevapi\Collection::remove() によってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Collection::remove() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("people");

$collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$collection->add('{"name": "Bob", "age": 19, "job": "Painter"}')->execute();

// すべての Painter を削除する
$collection
->remove("job in ('Painter')")
->execute();

// もっとも古い Butler を削除する
$collection
->remove("job in ('Butler')")
->sort('age desc')
->limit(1)
->execute();

// age が一番若いレコードを削除する
$collection
->remove('true')
->sort('age desc')
->limit(1)
->execute();
?>


削除操作を実行する

  • ≪ CollectionRemove::__construct
  • CollectionRemove::limit ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • 削除操作を実行する

CollectionRemove::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::execute — 削除操作を実行する

説明

public mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

クライアントがサーバーに CRUD 操作のリクエストを送信させるためには、 execute 関数を呼び出す必要があります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

Result オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionRemove::execute() の例

<?php

$res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

?>


削除するドキュメントの数を限定する

  • ≪ CollectionRemove::execute
  • CollectionRemove::sort ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • 削除するドキュメントの数を限定する

CollectionRemove::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::limit — 削除するドキュメントの数を限定する

説明

public mysql_xdevapi\CollectionRemove::limit(int $rows): mysql_xdevapi\CollectionRemove

削除するドキュメントの数の最大値を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rows

削除するドキュメントの数の最大値

戻り値

コマンドを実行したり、追加の操作を追加するのに使える CollectionRemove オブジェクト。

例

例1 mysql_xdevapi\CollectionRemove::limit() example

<?php

$res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

?>


ソート条件を設定する

  • ≪ CollectionRemove::limit
  • mysql_xdevapi\ColumnResult ≫
  • PHP Manual
  • mysql_xdevapi\CollectionRemove
  • ソート条件を設定する

CollectionRemove::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CollectionRemove::sort — ソート条件を設定する

説明

public mysql_xdevapi\CollectionRemove::sort(string $sort_expr): mysql_xdevapi\CollectionRemove

sort_expr 引数で、選択されるフィールドによって結果をソートします。 可能なソート順は ASC(昇順) または DESC (降順) です。 この操作は SQL の 'ORDER BY' と同等で、同じルールに従います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sort_expr

ひとつ以上のソート式が指定できます。 評価は左から右に行われ、個別の式はコンマで区切ります。

戻り値

コマンドを実行したり、追加の操作を追加できる CollectionRemove オブジェクトを返します。

例

例1 mysql_xdevapi\CollectionRemove::sort() の例

<?php

$res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

?>


ColumnResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\ColumnResult {
/* メソッド */
public getCharacterSetName(): string
public getCollationName(): string
public getColumnLabel(): string
public getColumnName(): string
public getFractionalDigits(): int
public getLength(): int
public getSchemaName(): string
public getTableLabel(): string
public getTableName(): string
public getType(): int
public isNumberSigned(): int
public isPadded(): int
}

目次

  • ColumnResult::__construct — ColumnResult のコンストラクタ
  • ColumnResult::getCharacterSetName — キャラクタセットを取得する
  • ColumnResult::getCollationName — 照合順序名を取得する
  • ColumnResult::getColumnLabel — カラムのラベルを取得する
  • ColumnResult::getColumnName — カラム名を取得する
  • ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する
  • ColumnResult::getLength — カラムのフィールドの長さを取得する
  • ColumnResult::getSchemaName — スキーマ名を取得する
  • ColumnResult::getTableLabel — テーブルラベルを取得する
  • ColumnResult::getTableName — テーブル名を取得する
  • ColumnResult::getType — カラムの型を取得する
  • ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる
  • ColumnResult::isPadded — パディングされているかを調べる


ColumnResult のコンストラクタ

  • ≪ mysql_xdevapi\ColumnResult
  • ColumnResult::getCharacterSetName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • ColumnResult のコンストラクタ

ColumnResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::__construct — ColumnResult のコンストラクタ

説明

private mysql_xdevapi\ColumnResult::__construct()

キャラクタセットのような、カラムのメタデータを取得します。 mysql_xdevapi\RowResult::getColumns() によってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\ColumnResult::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS nonsense")->execute();
$session->sql("CREATE DATABASE nonsense")->execute();
$session->sql("CREATE TABLE nonsense.numbers (hello int, world float unsigned)")->execute();
$session->sql("INSERT INTO nonsense.numbers values (42, 42)")->execute();

$schema = $session->getSchema("nonsense");
$table = $schema->getTable("numbers");

$result1 = $table->select('hello','world')->execute();

// Returns an array of ColumnResult objects
$columns = $result1->getColumns();

foreach ($columns as $column) {
echo "\nColumn label " , $column->getColumnLabel();
echo " is type " , $column->getType();
echo " and is ", ($column->isNumberSigned() === 0) ? "unsigned." : "signed.";
}

// Alternatively
$result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

// Returns an array of FieldMetadata objects
print_r($result2->getColumns());

上の例の出力は、 たとえば以下のようになります。

Column label hello is type 19 and is signed.
Column label world is type 4  and is unsigned.

Array
(
    [0] => mysql_xdevapi\FieldMetadata Object
        (
            [type] => 1
            [type_name] => SINT
            [name] => hello
            [original_name] => hello
            [table] => numbers
            [original_table] => numbers
            [schema] => nonsense
            [catalog] => def
            [collation] => 0
            [fractional_digits] => 0
            [length] => 11
            [flags] => 0
            [content_type] => 0
        )
    [1] => mysql_xdevapi\FieldMetadata Object
        (
            [type] => 6
            [type_name] => FLOAT
            [name] => world
            [original_name] => world
            [table] => numbers
            [original_table] => numbers
            [schema] => nonsense
            [catalog] => def
            [collation] => 0
            [fractional_digits] => 31
            [length] => 12
            [flags] => 1
            [content_type] => 0
        )
)


キャラクタセットを取得する

  • ≪ ColumnResult::__construct
  • ColumnResult::getCollationName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • キャラクタセットを取得する

ColumnResult::getCharacterSetName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getCharacterSetName — キャラクタセットを取得する

説明

public mysql_xdevapi\ColumnResult::getCharacterSetName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getCharacterSetName() の例

<?php

/* ... */

?>


照合順序名を取得する

  • ≪ ColumnResult::getCharacterSetName
  • ColumnResult::getColumnLabel ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • 照合順序名を取得する

ColumnResult::getCollationName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getCollationName — 照合順序名を取得する

説明

public mysql_xdevapi\ColumnResult::getCollationName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getCollationName() の例

<?php

/* ... */

?>


カラムのラベルを取得する

  • ≪ ColumnResult::getCollationName
  • ColumnResult::getColumnName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムのラベルを取得する

ColumnResult::getColumnLabel

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getColumnLabel — カラムのラベルを取得する

説明

public mysql_xdevapi\ColumnResult::getColumnLabel(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getColumnLabel() の例

<?php

/* ... */

?>


カラム名を取得する

  • ≪ ColumnResult::getColumnLabel
  • ColumnResult::getFractionalDigits ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラム名を取得する

ColumnResult::getColumnName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getColumnName — カラム名を取得する

説明

public mysql_xdevapi\ColumnResult::getColumnName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getColumnName() の例

<?php

/* ... */

?>


カラムの小数の桁数を取得する

  • ≪ ColumnResult::getColumnName
  • ColumnResult::getLength ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムの小数の桁数を取得する

ColumnResult::getFractionalDigits

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する

説明

public mysql_xdevapi\ColumnResult::getFractionalDigits(): int

カラムの小数の桁数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getFractionalDigits() の例

<?php

/* ... */

?>


カラムのフィールドの長さを取得する

  • ≪ ColumnResult::getFractionalDigits
  • ColumnResult::getSchemaName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムのフィールドの長さを取得する

ColumnResult::getLength

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getLength — カラムのフィールドの長さを取得する

説明

public mysql_xdevapi\ColumnResult::getLength(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getLength() の例

<?php

/* ... */

?>


スキーマ名を取得する

  • ≪ ColumnResult::getLength
  • ColumnResult::getTableLabel ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • スキーマ名を取得する

ColumnResult::getSchemaName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getSchemaName — スキーマ名を取得する

説明

public mysql_xdevapi\ColumnResult::getSchemaName(): string

カラムが保存されているスキーマの名前を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getSchemaName() の例

<?php

/* ... */

?>


テーブルラベルを取得する

  • ≪ ColumnResult::getSchemaName
  • ColumnResult::getTableName ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • テーブルラベルを取得する

ColumnResult::getTableLabel

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getTableLabel — テーブルラベルを取得する

説明

public mysql_xdevapi\ColumnResult::getTableLabel(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getTableLabel() の例

<?php

/* ... */

?>


テーブル名を取得する

  • ≪ ColumnResult::getTableLabel
  • ColumnResult::getType ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • テーブル名を取得する

ColumnResult::getTableName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getTableName — テーブル名を取得する

説明

public mysql_xdevapi\ColumnResult::getTableName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトに対応するテーブル名を返します。

例

例1 mysql_xdevapi\ColumnResult::getTableName() の例

<?php

/* ... */

?>


カラムの型を取得する

  • ≪ ColumnResult::getTableName
  • ColumnResult::isNumberSigned ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • カラムの型を取得する

ColumnResult::getType

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::getType — カラムの型を取得する

説明

public mysql_xdevapi\ColumnResult::getType(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\ColumnResult::getType() の例

<?php

/* ... */

?>


符号付きの型かどうかを調べる

  • ≪ ColumnResult::getType
  • ColumnResult::isPadded ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • 符号付きの型かどうかを調べる

ColumnResult::isNumberSigned

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる

説明

public mysql_xdevapi\ColumnResult::isNumberSigned(): int

テーブルのカラム情報を取得します。 mysql_xdevapi\RowResult::getColumns() によってインスタンス化されます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

与えられたカラムが符号付きの場合、true を返します。

例

例1 mysql_xdevapi\ColumnResult::isNumberSigned() の例

<?php

/* ... */

?>


パディングされているかを調べる

  • ≪ ColumnResult::isNumberSigned
  • mysql_xdevapi\CrudOperationBindable ≫
  • PHP Manual
  • mysql_xdevapi\ColumnResult
  • パディングされているかを調べる

ColumnResult::isPadded

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ColumnResult::isPadded — パディングされているかを調べる

説明

public mysql_xdevapi\ColumnResult::isPadded(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

与えられたカラムがパディングされていれば true を返します。

例

例1 mysql_xdevapi\ColumnResult::isPadded() の例

<?php

/* ... */

?>


CrudOperationBindable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CrudOperationBindable {
/* メソッド */
abstract public bind(array $placeholder_values): mysql_xdevapi\CrudOperationBindable
}

目次

  • CrudOperationBindable::bind — プレースホルダーに値をバインドする


プレースホルダーに値をバインドする

  • ≪ mysql_xdevapi\CrudOperationBindable
  • mysql_xdevapi\CrudOperationLimitable ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationBindable
  • プレースホルダーに値をバインドする

CrudOperationBindable::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationBindable::bind — プレースホルダーに値をバインドする

説明

abstract public mysql_xdevapi\CrudOperationBindable::bind(array $placeholder_values): mysql_xdevapi\CrudOperationBindable

特定のプレースホルダーに値をバインドします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

placeholder_values

プレースホルダーの名前と、バインドする値

戻り値

CrudOperationBindable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationBindable::bind() の例

<?php

$res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
$res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

?>


CrudOperationLimitable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CrudOperationLimitable {
/* メソッド */
abstract public limit(int $rows): mysql_xdevapi\CrudOperationLimitable
}

目次

  • CrudOperationLimitable::limit — 結果を限定する


結果を限定する

  • ≪ mysql_xdevapi\CrudOperationLimitable
  • mysql_xdevapi\CrudOperationSkippable ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationLimitable
  • 結果を限定する

CrudOperationLimitable::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationLimitable::limit — 結果を限定する

説明

abstract public mysql_xdevapi\CrudOperationLimitable::limit(int $rows): mysql_xdevapi\CrudOperationLimitable

返されるドキュメントまたはレコードの最大数を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rows

レコードまたはドキュメントの最大数

戻り値

CrudOperationLimitable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationLimitable::limit() の例

<?php

$res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
$res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

?>


CrudOperationSkippable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CrudOperationSkippable {
/* メソッド */
abstract public skip(int $skip): mysql_xdevapi\CrudOperationSkippable
}

目次

  • CrudOperationSkippable::skip — スキップする操作の数


スキップする操作の数

  • ≪ mysql_xdevapi\CrudOperationSkippable
  • mysql_xdevapi\CrudOperationSortable ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationSkippable
  • スキップする操作の数

CrudOperationSkippable::skip

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationSkippable::skip — スキップする操作の数

説明

abstract public mysql_xdevapi\CrudOperationSkippable::skip(int $skip): mysql_xdevapi\CrudOperationSkippable

結果を返す操作で、ここで指定するレコードの数をスキップします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

skip

スキップする要素数

戻り値

CrudOperationSkippable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationSkippable::skip() の例

<?php

$res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

?>


CrudOperationSortable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\CrudOperationSortable {
/* メソッド */
abstract public sort(string $sort_expr): mysql_xdevapi\CrudOperationSortable
}

目次

  • CrudOperationSortable::sort — 結果をソートする


結果をソートする

  • ≪ mysql_xdevapi\CrudOperationSortable
  • mysql_xdevapi\DatabaseObject ≫
  • PHP Manual
  • mysql_xdevapi\CrudOperationSortable
  • 結果をソートする

CrudOperationSortable::sort

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

CrudOperationSortable::sort — 結果をソートする

説明

abstract public mysql_xdevapi\CrudOperationSortable::sort(string $sort_expr): mysql_xdevapi\CrudOperationSortable

結果セットを sort_expr 引数で指定されたフィールドでソートします。 可能なソート順は ASC (昇順) か DESC (降順) です。 この操作は、SQL における 'ORDER BY' と同等で、それと同じルールセットに従います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sort_expr

ひとつまたはそれ以上のソートを行う指揮を指定できます。 評価は左から右へと行われ、それぞれの四季はコンマで区切ります。

戻り値

CrudOperationSortable オブジェクトを返します。

例

例1 mysql_xdevapi\CrudOperationSortable::sort() の例

<?php

$res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

?>


DatabaseObject インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\DatabaseObject {
/* メソッド */
abstract public existsInDatabase(): bool
abstract public getName(): string
abstract public getSession(): mysql_xdevapi\Session
}

目次

  • DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする
  • DatabaseObject::getName — オブジェクトの名前を取得する
  • DatabaseObject::getSession — セッションの名前を取得する


オブジェクトがデータベースに存在するかをチェックする

  • ≪ mysql_xdevapi\DatabaseObject
  • DatabaseObject::getName ≫
  • PHP Manual
  • mysql_xdevapi\DatabaseObject
  • オブジェクトがデータベースに存在するかをチェックする

DatabaseObject::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする

説明

abstract public mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

データベースオブジェクトが、データベース内に存在するオブジェクトを参照しているかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトがデータベースに存在していれば true を返します。 そうでなければ、false を返します。

例

例1 mysql_xdevapi\DatabaseObject::existsInDatabase() の例

<?php

$existInDb = $dbObj->existsInDatabase();

?>


オブジェクトの名前を取得する

  • ≪ DatabaseObject::existsInDatabase
  • DatabaseObject::getSession ≫
  • PHP Manual
  • mysql_xdevapi\DatabaseObject
  • オブジェクトの名前を取得する

DatabaseObject::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DatabaseObject::getName — オブジェクトの名前を取得する

説明

abstract public mysql_xdevapi\DatabaseObject::getName(): string

このデータベースオブジェクトの名前を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

データベースオブジェクトの名前を返します。

例

例1 mysql_xdevapi\DatabaseObject::getName() の例

<?php

$dbObjName = $dbObj->getName();

?>


セッションの名前を取得する

  • ≪ DatabaseObject::getName
  • mysql_xdevapi\DocResult ≫
  • PHP Manual
  • mysql_xdevapi\DatabaseObject
  • セッションの名前を取得する

DatabaseObject::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DatabaseObject::getSession — セッションの名前を取得する

説明

abstract public mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

データベースオブジェクトに紐付いたセッションを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

Session オブジェクトを返します。

例

例1 mysql_xdevapi\DatabaseObject::getSession() の例

<?php

$session = $dbObj->getSession();

?>


DocResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public fetchAll(): array
public fetchOne(): array
public getWarnings(): Array
public getWarningsCount(): int
}

目次

  • DocResult::__construct — DocResult のコンストラクタ
  • DocResult::fetchAll — 全ての行を取得する
  • DocResult::fetchOne — 一行取得する
  • DocResult::getWarnings — 直近の操作から発生した警告を取得する
  • DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する


DocResult のコンストラクタ

  • ≪ mysql_xdevapi\DocResult
  • DocResult::fetchAll ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • DocResult のコンストラクタ

DocResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::__construct — DocResult のコンストラクタ

説明

private mysql_xdevapi\DocResult::__construct()

ドキュメントの結果と警告を取得します。 CollectionFind クラスによってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 DocResult の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->sort('age desc')
->limit(1)
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b536100000000000000f3"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }
}


全ての行を取得する

  • ≪ DocResult::__construct
  • DocResult::fetchOne ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 全ての行を取得する

DocResult::fetchAll

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::fetchAll — 全ての行を取得する

説明

public mysql_xdevapi\DocResult::fetchAll(): array

結果セットから全ての行を取得する

パラメータ

この関数にはパラメータはありません。

戻り値

クエリからの結果全てを含む、数値をキーとする配列。 それぞれの結果は連想配列です。 行が存在しない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\DocResult::fetchAll() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->sort('age desc')
->execute();

var_dump($result->fetchAll());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {

  [0]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000123"
    ["age"]=>
    int(42)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(8) "Reginald"
  }

  [1]=>
  array(4) {
    ["_id"]=>
    string(28) "00005b6b53610000000000000122"
    ["age"]=>
    int(18)
    ["job"]=>
    string(6) "Butler"
    ["name"]=>
    string(6) "Alfred"
  }

}


一行取得する

  • ≪ DocResult::fetchAll
  • DocResult::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 一行取得する

DocResult::fetchOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::fetchOne — 一行取得する

説明

public mysql_xdevapi\DocResult::fetchOne(): array

結果セットから一行だけ取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

一行を表一行を表す連想配列。 結果がなければ null となります。

例

例1 mysql_xdevapi\DocResult::fetchOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->sort('age desc')
->execute();

var_dump($result->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  string(28) "00005b6b53610000000000000125"
  ["age"]=>
  int(42)
  ["job"]=>
  string(6) "Butler"
  ["name"]=>
  string(8) "Reginald"
}


直近の操作から発生した警告を取得する

  • ≪ DocResult::fetchOne
  • DocResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 直近の操作から発生した警告を取得する

DocResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::getWarnings — 直近の操作から発生した警告を取得する

説明

public mysql_xdevapi\DocResult::getWarnings(): Array

MySQL サーバーに対する直近の操作から発生した警告を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から発生した警告オブジェクトの配列。 個々のオブジェクトはエラーの 'message' と 'level' と 'code' を定義しています。 エラーが発生していない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\DocResult::getWarnings() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// DocResult オブジェクトを生成
$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->sort('age desc')
->execute();

if (!$result->getWarningsCount()) {
echo "There was an error:\n";
print_r($result->getWarnings());
exit;
}

var_dump($result->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

There was an error:

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Something bad and so on
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Something bad and so on
            [level] => 2
            [code] => 1365
        )
)


直近の操作で発生した警告の数を取得する

  • ≪ DocResult::getWarnings
  • mysql_xdevapi\Exception ≫
  • PHP Manual
  • mysql_xdevapi\DocResult
  • 直近の操作で発生した警告の数を取得する

DocResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

説明

public mysql_xdevapi\DocResult::getWarningsCount(): int

直近の操作によって発生した警告の数を返します。 具体的には、これらの警告は MySQL サーバーが発生させたものです。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作によって発生した警告の数を返します。

例

例1 mysql_xdevapi\DocResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
$create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

// ...

$collection = $schema->getCollection("people");

// Yields a DocResult object
$result = $collection
->find('job like :job and age > :age')
->bind(['job' => 'Butler', 'age' => 16])
->sort('age desc')
->execute();

if (!$result->getWarningsCount()) {
echo "There was an error:\n";
print_r($result->getWarnings());
exit;
}

var_dump($result->fetchOne());
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["_id"]=>
  string(28) "00005b6b53610000000000000135"
  ["age"]=>
  int(42)
  ["job"]=>
  string(6) "Butler"
  ["name"]=>
  string(8) "Reginald"
}


Exception クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}


Executable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Executable {
/* メソッド */
abstract public execute(): mysql_xdevapi\Result
}

目次

  • Executable::execute — ステートメントを実行する


ステートメントを実行する

  • ≪ mysql_xdevapi\Executable
  • mysql_xdevapi\ExecutionStatus ≫
  • PHP Manual
  • mysql_xdevapi\Executable
  • ステートメントを実行する

Executable::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Executable::execute — ステートメントを実行する

説明

abstract public mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

コレクションへの操作、またはテーブルへのクエリから、ステートメントを実行します。 この機能によるメソッドのチェインが可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

Result または SqlStatementResult のような Result オブジェクトを返します。

例

例1 execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

var_dump($result_sql);

$schema = $session->getSchema("addressbook");
$collection = $schema->createCollection("humans");

$result_collection = $collection->add(
'{"name": "Jane",
"jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
"hobbies": ["Walking","Making pies"]}');

$result_collection_executed = $result_collection->execute();

var_dump($result_collection);
var_dump($result_collection_executed);
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\SqlStatementResult)#3 (0) {
}

object(mysql_xdevapi\CollectionAdd)#5 (0) {
}

object(mysql_xdevapi\Result)#7 (0) {
}


ExecutionStatus クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\ExecutionStatus {
/* プロパティ */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private __construct()
}

プロパティ

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

目次

  • ExecutionStatus::__construct — ExecutionStatus のコンストラクタ


ExecutionStatus のコンストラクタ

  • ≪ mysql_xdevapi\ExecutionStatus
  • mysql_xdevapi\Expression ≫
  • PHP Manual
  • mysql_xdevapi\ExecutionStatus
  • ExecutionStatus のコンストラクタ

ExecutionStatus::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ExecutionStatus::__construct — ExecutionStatus のコンストラクタ

説明

private mysql_xdevapi\ExecutionStatus::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\ExecutionStatus::__construct() の例

<?php

/* ... */

?>


Expression クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Expression {
/* プロパティ */
public $name;
/* Constructor */
public __construct(string $expression)
}

プロパティ

name

目次

  • Expression::__construct — Expression のコンストラクタ


Expression のコンストラクタ

  • ≪ mysql_xdevapi\Expression
  • mysql_xdevapi\Result ≫
  • PHP Manual
  • mysql_xdevapi\Expression
  • Expression のコンストラクタ

Expression::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Expression::__construct — Expression のコンストラクタ

説明

public mysql_xdevapi\Expression::__construct(string $expression)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

expression

例

例1 mysql_xdevapi\Expression::__construct() の例

<?php

/* ... */

?>


Result クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public getAffectedItemsCount(): int
public getAutoIncrementValue(): int
public getGeneratedIds(): array
public getWarnings(): array
public getWarningsCount(): int
}

目次

  • Result::__construct — Result のコンストラクタ
  • Result::getAffectedItemsCount — 影響を受けた行数を得る
  • Result::getAutoIncrementValue — 自動インクリメントされた値を取得する
  • Result::getGeneratedIds — 生成された id を取得する
  • Result::getWarnings — 直近の操作から発生した警告を取得する
  • Result::getWarningsCount — 直近の操作から生じた警告の数を取得する


Result のコンストラクタ

  • ≪ mysql_xdevapi\Result
  • Result::getAffectedItemsCount ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • Result のコンストラクタ

Result::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::__construct — Result のコンストラクタ

説明

private mysql_xdevapi\Result::__construct()

生成された ID や AUTO_INCREMENT の値、 警告を 結果セットから取得するためのオブジェクトです。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Result::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("
CREATE TABLE addressbook.names
(id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
$result = $table->insert("name", "age")->values(["Suki", 34])->execute();

$ai = $result->getAutoIncrementValue();
var_dump($ai);
?>

上の例の出力は以下となります。

int(3)


影響を受けた行数を得る

  • ≪ Result::__construct
  • Result::getAutoIncrementValue ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 影響を受けた行数を得る

Result::getAffectedItemsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getAffectedItemsCount — 影響を受けた行数を得る

説明

public mysql_xdevapi\Result::getAffectedItemsCount(): int

直近の操作によって、影響を受けた行数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

影響を受けた行数(整数)を返します。

例

例1 mysql_xdevapi\Result::getAffectedItemsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

$result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

var_dump( $res->getAffectedItemsCount() );
?>

上の例の出力は以下となります。

int(1)


自動インクリメントされた値を取得する

  • ≪ Result::getAffectedItemsCount
  • Result::getGeneratedIds ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 自動インクリメントされた値を取得する

Result::getAutoIncrementValue

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getAutoIncrementValue — 自動インクリメントされた値を取得する

説明

public mysql_xdevapi\Result::getAutoIncrementValue(): int

最新の AUTO_INCREMENT の値 (最後に挿入されたid) を取得します

パラメータ

この関数にはパラメータはありません。

戻り値

最新の AUTO_INCREMENT の値 を返します。

例

例1 mysql_xdevapi\Result::getAutoIncrementValue() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("
CREATE TABLE addressbook.names
(id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
$result = $table->insert("name", "age")->values(["Suki", 34])->execute();

$ai = $result->getAutoIncrementValue();
var_dump($ai);
?>

上の例の出力は以下となります。

int(3)


生成された id を取得する

  • ≪ Result::getAutoIncrementValue
  • Result::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 生成された id を取得する

Result::getGeneratedIds

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getGeneratedIds — 生成された id を取得する

説明

public mysql_xdevapi\Result::getGeneratedIds(): array

直近の操作から生成された _id の値を取得します。 ユニークな _id フィールドは MySQL サーバーによって生成されます。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作によって生成された _id の配列を返します。 生成された _id がない場合は、空の配列を返します。

例

例1 mysql_xdevapi\Result::getGeneratedIds() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$create = $schema->createCollection("people");

$collection = $schema->getCollection("people");

$result = $collection->add(
'{"name": "Bernie",
"jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
"hobbies": ["Sports","Making cupcakes"]}',
'{"name": "Jane",
"jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
"hobbies": ["Walking","Making pies"]}')->execute();

$ids = $result->getGeneratedIds();
var_dump($ids);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  string(28) "00005b6b53610000000000000064"
  [1]=>
  string(28) "00005b6b53610000000000000065"
}


直近の操作から発生した警告を取得する

  • ≪ Result::getGeneratedIds
  • Result::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 直近の操作から発生した警告を取得する

Result::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getWarnings — 直近の操作から発生した警告を取得する

説明

public mysql_xdevapi\Result::getWarnings(): array

直近の Result に対するの操作から発生した警告を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から発生した警告オブジェクトの配列。 個々のオブジェクトはエラーの 'message' と 'level' と 'code' を定義しています。 エラーが発生していない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::getWarnings() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();
$warnings = $res->getWarnings();

print_r($warnings);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
)


直近の操作から生じた警告の数を取得する

  • ≪ Result::getWarnings
  • mysql_xdevapi\RowResult ≫
  • PHP Manual
  • mysql_xdevapi\Result
  • 直近の操作から生じた警告の数を取得する

Result::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Result::getWarningsCount — 直近の操作から生じた警告の数を取得する

説明

public mysql_xdevapi\Result::getWarningsCount(): int

直近の操作から生じた警告の数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から生じた警告の数を返します。

例

例1 mysql_xdevapi\RowResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS foo")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();

echo $res->getWarningsCount();
?>

上の例の出力は、 たとえば以下のようになります。

2


RowResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public fetchAll(): array
public fetchOne(): array
public getColumnsCount(): int
public getColumnNames(): array
public getColumns(): array
public getWarnings(): array
public getWarningsCount(): int
}

目次

  • RowResult::__construct — RowResult のコンストラクタ
  • RowResult::fetchAll — 結果セットから全ての行を取得する
  • RowResult::fetchOne — 結果セットから行を取得する
  • RowResult::getColumnsCount — カラムの数を取得する
  • RowResult::getColumnNames — 全てのカラム名を取得する
  • RowResult::getColumns — カラムのメタデータを取得する
  • RowResult::getWarnings — 直近の操作から生じた警告を取得する
  • RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する


RowResult のコンストラクタ

  • ≪ mysql_xdevapi\RowResult
  • RowResult::fetchAll ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • RowResult のコンストラクタ

RowResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::__construct — RowResult のコンストラクタ

説明

private mysql_xdevapi\RowResult::__construct()

データベースへの問い合わせから得られる結果セットを表現します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\RowResult::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)


結果セットから全ての行を取得する

  • ≪ RowResult::__construct
  • RowResult::fetchOne ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 結果セットから全ての行を取得する

RowResult::fetchAll

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::fetchAll — 結果セットから全ての行を取得する

説明

public mysql_xdevapi\RowResult::fetchAll(): array

結果セットから全ての行を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クエリで取得した全ての結果を含む、数値インデックスの配列。 個々の結果は連想配列です。行が存在しない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::fetchAll() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$row = $table->select('name', 'age')->execute()->fetchAll();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)


結果セットから行を取得する

  • ≪ RowResult::fetchAll
  • RowResult::getColumnsCount ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 結果セットから行を取得する

RowResult::fetchOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::fetchOne — 結果セットから行を取得する

説明

public mysql_xdevapi\RowResult::fetchOne(): array

結果セットから一行取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果を連想配列として返します。 結果が存在しない場合は null を返します。

例

例1 mysql_xdevapi\RowResult::fetchOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => Sam
    [age] => 33
)


カラムの数を取得する

  • ≪ RowResult::fetchOne
  • RowResult::getColumnNames ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • カラムの数を取得する

RowResult::getColumnsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getColumnsCount — カラムの数を取得する

説明

public mysql_xdevapi\RowResult::getColumnsCount(): int

結果セットに存在するカラムの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

カラムの数を返します。カラムが存在しない場合は 0 を返します。

変更履歴

バージョン | 説明
8.0.14 | メソッド名が getColumnCount() から getColumnsCount() に変わりました。

例

例1 mysql_xdevapi\RowResult::getColumnsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$sql = $session->sql("SELECT * from addressbook.names")->execute();

echo $sql->getColumnsCount();

上の例の出力は、 たとえば以下のようになります。

2


全てのカラム名を取得する

  • ≪ RowResult::getColumnsCount
  • RowResult::getColumns ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 全てのカラム名を取得する

RowResult::getColumnNames

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getColumnNames — 全てのカラム名を取得する

説明

public mysql_xdevapi\RowResult::getColumnNames(): array

結果セットに存在するカラム名を全て取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

インデックスが数字のカラム名の配列を返します。 結果セットが空の場合は、空の配列を返します。

例

例1 mysql_xdevapi\RowResult::getColumnNames() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$sql = $session->sql("SELECT * from addressbook.names")->execute();

$colnames = $sql->getColumnNames();

print_r($colnames);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => name
    [1] => age
)


カラムのメタデータを取得する

  • ≪ RowResult::getColumnNames
  • RowResult::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • カラムのメタデータを取得する

RowResult::getColumns

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getColumns — カラムのメタデータを取得する

説明

public mysql_xdevapi\RowResult::getColumns(): array

結果セットに存在するカラムのメタデータを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果のカラムを表現する FieldMetadata オブジェクトの配列を返します。 結果セットが空の場合は、空の配列を返します。

例

例1 mysql_xdevapi\RowResult::getColumns() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE addressbook")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$sql = $session->sql("SELECT * from addressbook.names")->execute();

$cols = $sql->getColumns();

print_r($cols);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\FieldMetadata Object
        (
            [type] => 7
            [type_name] => BYTES
            [name] => name
            [original_name] => name
            [table] => names
            [original_table] => names
            [schema] => addressbook
            [catalog] => def
            [collation] => 255
            [fractional_digits] => 0
            [length] => 65535
            [flags] => 0
            [content_type] => 0
        )
    [1] => mysql_xdevapi\FieldMetadata Object
        (
            [type] => 1
            [type_name] => SINT
            [name] => age
            [original_name] => age
            [table] => names
            [original_table] => names
            [schema] => addressbook
            [catalog] => def
            [collation] => 0
            [fractional_digits] => 0
            [length] => 11
            [flags] => 0
            [content_type] => 0
        )
)


直近の操作から生じた警告を取得する

  • ≪ RowResult::getColumns
  • RowResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 直近の操作から生じた警告を取得する

RowResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getWarnings — 直近の操作から生じた警告を取得する

説明

public mysql_xdevapi\RowResult::getWarnings(): array

直近の RowResult の操作から生じた警告を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から発生した警告オブジェクトの配列。 個々のオブジェクトはエラーの 'message' と 'level' と 'code' を定義しています。 エラーが発生していない場合は、空の配列が返されます。

例

例1 mysql_xdevapi\RowResult::getWarnings() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();
$warnings = $res->getWarnings();

print_r($warnings);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
    [1] => mysql_xdevapi\Warning Object
        (
            [message] => Division by 0
            [level] => 2
            [code] => 1365
        )
)


直近の操作から生じた警告の数を取得する

  • ≪ RowResult::getWarnings
  • mysql_xdevapi\Schema ≫
  • PHP Manual
  • mysql_xdevapi\RowResult
  • 直近の操作から生じた警告の数を取得する

RowResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する

説明

public mysql_xdevapi\RowResult::getWarningsCount(): int

直近の RowResult への操作から生じた警告の数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作から生じた警告の数を返します。

例

例1 mysql_xdevapi\RowResult::getWarningsCount() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS foo")->execute();
$session->sql("CREATE DATABASE foo")->execute();
$session->sql("CREATE TABLE foo.test_table(x int)")->execute();

$schema = $session->getSchema("foo");
$table = $schema->getTable("test_table");

$table->insert(['x'])->values([1])->values([2])->execute();

$res = $table->select(['x/0 as bad_x'])->execute();

echo $res->getWarningsCount();
?>

上の例の出力は、 たとえば以下のようになります。

2


Schema クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* プロパティ */
public $name;
/* メソッド */
public createCollection(string $name): mysql_xdevapi\Collection
public dropCollection(string $collection_name): bool
public existsInDatabase(): bool
public getCollection(string $name): mysql_xdevapi\Collection
public getCollectionAsTable(string $name): mysql_xdevapi\Table
public getCollections(): array
public getName(): string
public getSession(): mysql_xdevapi\Session
public getTable(string $name): mysql_xdevapi\Table
public getTables(): array
}

プロパティ

name

目次

  • Schema::__construct — Schema のコンストラクタ
  • Schema::createCollection — スキーマにコレクションを追加する
  • Schema::dropCollection — スキーマからコレクションを削除する
  • Schema::existsInDatabase — データベースに存在するかをチェックする
  • Schema::getCollection — スキーマからコレクションを取得する
  • Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する
  • Schema::getCollections — スキーマに属する全てのコレクションを取得する
  • Schema::getName — スキーマの名前を取得する
  • Schema::getSession — スキーマのセッションを取得する
  • Schema::getTable — スキーマのテーブルを取得する
  • Schema::getTables — スキーマのテーブルを取得する


Schema のコンストラクタ

  • ≪ mysql_xdevapi\Schema
  • Schema::createCollection ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • Schema のコンストラクタ

Schema::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::__construct — Schema のコンストラクタ

説明

private mysql_xdevapi\Schema::__construct()

スキーマオブジェクトは、スキーマ(データベース)への完全なアクセスを提供します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Schema::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS food")->execute();
$session->sql("CREATE DATABASE food")->execute();
$session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

$schema = $session->getSchema("food");
$schema->createCollection("trees");

print_r($schema->gettables());
print_r($schema->getcollections());

上の例の出力は、 たとえば以下のようになります。

Array
(
    [fruit] => mysql_xdevapi\Table Object
        (
            [name] => fruit
        )
)
Array
(
    [trees] => mysql_xdevapi\Collection Object
        (
            [name] => trees
        )
)


スキーマにコレクションを追加する

  • ≪ Schema::__construct
  • Schema::dropCollection ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマにコレクションを追加する

Schema::createCollection

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::createCollection — スキーマにコレクションを追加する

説明

public mysql_xdevapi\Schema::createCollection(string $name): mysql_xdevapi\Collection

スキーマ内にコレクションを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

コレクションの名前。

validate

バリデーションの定義を JSON オブジェクトとして指定します。

戻り値

コレクションオブジェクトを返します。

変更履歴

バージョン | 説明
8.0.20 | オプションの validate 引数が追加されました。

例

例1 mysql_xdevapi\Schema::createCollection() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS food")->execute();
$session->sql("CREATE DATABASE food")->execute();
$session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

$schema = $session->getSchema("food");
$schema->createCollection("trees");

print_r($schema->gettables());
print_r($schema->getcollections());

上の例の出力は、 たとえば以下のようになります。

Array
(
    [fruit] => mysql_xdevapi\Table Object
        (
            [name] => fruit
        )
)
Array
(
    [trees] => mysql_xdevapi\Collection Object
        (
            [name] => trees
        )
)

例2 mysql_xdevapi\Schema::createCollection() の例

<?php
$collection = $schema->createCollection("mycollection", '{
"validation": {
"level": "strict",
"schema": {
"id": "http://json-schema.org/geo",
"description": "A geographical coordinate",
"type": "object",
"properties": {
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
}
},
"required": ["latitude", "longitude"]
}
}
}');
// Succeeds
$collection->add('{"latitude": 10, "longitude": 20}')->execute();

// Fails, invalid types (not numbers)
$collection->add('{"latitude": "lat", "longitude": "long"}')->execute();


スキーマからコレクションを削除する

  • ≪ Schema::createCollection
  • Schema::existsInDatabase ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマからコレクションを削除する

Schema::dropCollection

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::dropCollection — スキーマからコレクションを削除する

説明

public mysql_xdevapi\Schema::dropCollection(string $collection_name): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

collection_name

戻り値

例

例1 mysql_xdevapi\Schema::dropCollection() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS food")->execute();
$session->sql("CREATE DATABASE food")->execute();
$session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

$schema = $session->getSchema("food");

$schema->createCollection("trees");
$schema->dropCollection("trees");
$schema->createCollection("buildings");

print_r($schema->gettables());
print_r($schema->getcollections());

上の例の出力は、 たとえば以下のようになります。

Array
(
    [fruit] => mysql_xdevapi\Table Object
        (
            [name] => fruit
        )
)
Array
(
    [buildings] => mysql_xdevapi\Collection Object
        (
            [name] => buildings
        )
)


データベースに存在するかをチェックする

  • ≪ Schema::dropCollection
  • Schema::getCollection ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • データベースに存在するかをチェックする

Schema::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::existsInDatabase — データベースに存在するかをチェックする

説明

public mysql_xdevapi\Schema::existsInDatabase(): bool

現在のオブジェクト(スキーマ、テーブル、コレクション、またはビュー)が、 スキーマオブジェクト内に存在しているかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

スキーマ、コレクション、テーブル、またはビューがスキーマに存在していれば true そうでなければ false を返します。

例

例1 mysql_xdevapi\Schema::existsInDatabase() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS food")->execute();
$session->sql("CREATE DATABASE food")->execute();
$session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

$schema = $session->getSchema("food");
$schema->createCollection("trees");

// ...

$trees = $schema->getCollection("trees");

// ...

// Is this collection still in the database (schema)?
if ($trees->existsInDatabase()) {
echo "Yes, the 'trees' collection is still present.";
}

上の例の出力は、 たとえば以下のようになります。

Yes, the 'trees' collection is still present.


スキーマからコレクションを取得する

  • ≪ Schema::existsInDatabase
  • Schema::getCollectionAsTable ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマからコレクションを取得する

Schema::getCollection

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getCollection — スキーマからコレクションを取得する

説明

public mysql_xdevapi\Schema::getCollection(string $name): mysql_xdevapi\Collection

スキーマからコレクションを取得します。

パラメータ

name

取得するコレクションの名前

戻り値

選択したコレクションを指す Collection オブジェクトを返します。

例

例1 mysql_xdevapi\Schema::getCollection() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS food")->execute();
$session->sql("CREATE DATABASE food")->execute();

$schema = $session->getSchema("food");
$schema->createCollection("trees");

// ...

$trees = $schema->getCollection("trees");

var_dump($trees);

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Collection)#3 (1) {
  ["name"]=>
  string(5) "trees"
}


コレクションをテーブルオブジェクトとして取得する

  • ≪ Schema::getCollection
  • Schema::getCollections ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • コレクションをテーブルオブジェクトとして取得する

Schema::getCollectionAsTable

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する

説明

public mysql_xdevapi\Schema::getCollectionAsTable(string $name): mysql_xdevapi\Table

コレクションをコレクションオブジェクトではなく、テーブルオブジェクトとして取得します。

パラメータ

name

テーブルオブジェクトとしてインスタンス化するためのコレクション名

戻り値

コレクションに対応する mysql_xdevapi\Table オブジェクトを返します。

例

例1 mysql_xdevapi\Schema::getCollectionAsTable() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collect = $schema->createCollection("people");
$collect->add('{"name": "Fred", "age": 21, "job": "Construction"}')->execute();
$collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

$table = $schema->getCollectionAsTable("people");
$collection = $schema->getCollection("people");

var_dump($table);
var_dump($collection);

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Table)#4 (1) {
  ["name"]=>
  string(6) "people"
}

object(mysql_xdevapi\Collection)#5 (1) {
  ["name"]=>
  string(6) "people"
}


スキーマに属する全てのコレクションを取得する

  • ≪ Schema::getCollectionAsTable
  • Schema::getName ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマに属する全てのコレクションを取得する

Schema::getCollections

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getCollections — スキーマに属する全てのコレクションを取得する

説明

public mysql_xdevapi\Schema::getCollections(): array

このスキーマに属するコレクションのリストを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

このスキーマに属する全てのコレクションを配列にして返します。 個々の要素は、コレクション名をキーとし、コレクションオブジェクトが値となります。

例

例1 mysql_xdevapi\Schema::getCollections() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");
$collect = $schema->createCollection("people");
$collect->add('{"name": "Fred", "age": 21, "job": "Construction"}')->execute();
$collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

$collections = $schema->getCollections();
var_dump($collections);
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["people"]=>
  object(mysql_xdevapi\Collection)#4 (1) {
    ["name"]=>
    string(6) "people"
  }
}


スキーマの名前を取得する

  • ≪ Schema::getCollections
  • Schema::getSession ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマの名前を取得する

Schema::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getName — スキーマの名前を取得する

説明

public mysql_xdevapi\Schema::getName(): string

スキーマの名前を取得します

パラメータ

この関数にはパラメータはありません。

戻り値

スキーマオブジェクトに接続しているスキーマの名前を文字列として返します。

例

例1 mysql_xdevapi\Schema::getName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");

// ...

var_dump($schema->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "addressbook"


スキーマのセッションを取得する

  • ≪ Schema::getName
  • Schema::getTable ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマのセッションを取得する

Schema::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getSession — スキーマのセッションを取得する

説明

public mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

スキーマオブジェクトから、新しいセッションオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Session オブジェクトを返します。

例

例1 mysql_xdevapi\Schema::getSession() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$schema = $session->getSchema("addressbook");

// ...

$newsession = $schema->getSession();

var_dump($session);
var_dump($newsession);
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Session)#1 (0) {
}

object(mysql_xdevapi\Session)#3 (0) {
}


スキーマのテーブルを取得する

  • ≪ Schema::getSession
  • Schema::getTables ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマのテーブルを取得する

Schema::getTable

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getTable — スキーマのテーブルを取得する

説明

public mysql_xdevapi\Schema::getTable(string $name): mysql_xdevapi\Table

スキーマで与えられたテーブルの Table オブジェクトを取得します。

パラメータ

name

テーブルの名前

戻り値

Table オブジェクトを返します

例

例1 mysql_xdevapi\Schema::getTable() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$row = $table->select('name', 'age')->execute()->fetchAll();

print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)


スキーマのテーブルを取得する

  • ≪ Schema::getTable
  • mysql_xdevapi\SchemaObject ≫
  • PHP Manual
  • mysql_xdevapi\Schema
  • スキーマのテーブルを取得する

Schema::getTables

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Schema::getTables — スキーマのテーブルを取得する

説明

public mysql_xdevapi\Schema::getTables(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

このスキーマにある全てのテーブル名を配列として返します。 個々の要素は、テーブル名をキーとする Table オブジェクトです。

例

例1 mysql_xdevapi\Schema::getTables() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();

$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

$schema = $session->getSchema("addressbook");
$tables = $schema->getTables();

var_dump($tables);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["cities"]=>
  object(mysql_xdevapi\Table)#3 (1) {
    ["name"]=>
    string(6) "cities"
  }

  ["names"]=>
  object(mysql_xdevapi\Table)#4 (1) {
    ["name"]=>
    string(5) "names"
  }
}


SchemaObject インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* メソッド */
abstract getSchema(): mysql_xdevapi\Schema
}

目次

  • SchemaObject::getSchema — スキーマオブジェクトを得る


スキーマオブジェクトを得る

  • ≪ mysql_xdevapi\SchemaObject
  • mysql_xdevapi\Session ≫
  • PHP Manual
  • mysql_xdevapi\SchemaObject
  • スキーマオブジェクトを得る

SchemaObject::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SchemaObject::getSchema — スキーマオブジェクトを得る

説明

abstract mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

スキーマオブジェクトを取得するために、他のオブジェクトから使われます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のスキーマオブジェクトを返します。

例

例1 mysql_xdevapi\Session::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$schema = $session->getSchema("addressbook");

print_r($schema);

上の例の出力は、 たとえば以下のようになります。

mysql_xdevapi\Schema Object
(
    [name] => addressbook
)


Session クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Session {
/* メソッド */
public close(): bool
public commit(): Object
public createSchema(string $schema_name): mysql_xdevapi\Schema
public dropSchema(string $schema_name): bool
public generateUUID(): string
public getDefaultSchema(): string
public getSchema(string $schema_name): mysql_xdevapi\Schema
public getSchemas(): array
public getServerVersion(): int
public listClients(): array
public quoteName(string $name): string
public releaseSavepoint(string $name): void
public rollback(): void
public rollbackTo(string $name): void
public setSavepoint(string $name = ?): string
public sql(string $query): mysql_xdevapi\SqlStatement
public startTransaction(): void
}

目次

  • Session::close — セッションを閉じる
  • Session::commit — トランザクションをコミットする
  • Session::__construct — Session のコンストラクタ
  • Session::createSchema — 新しいスキーマを作成する
  • Session::dropSchema — スキーマを削除します
  • Session::generateUUID — 新しいUUIDを取得する
  • Session::getDefaultSchema — デフォルトのスキーマ名を取得する
  • Session::getSchema — 新しいスキーマオブジェクトを取得する
  • Session::getSchemas — スキーマを取得する
  • Session::getServerVersion — サーバーのバージョンを取得する
  • Session::listClients — クライアントの一覧を取得する
  • Session::quoteName — クォートを追加する
  • Session::releaseSavepoint — 設定されたセーブポイントをリリースする
  • Session::rollback — トランザクションをロールバックする
  • Session::rollbackTo — セーブポイントまでトランザクションをロールバックする
  • Session::setSavepoint — セーブポイントを作成する
  • Session::sql — SQLクエリを作成する
  • Session::startTransaction — トランザクションを開始する


セッションを閉じる

  • ≪ mysql_xdevapi\Session
  • Session::commit ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • セッションを閉じる

Session::close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::close — セッションを閉じる

説明

public mysql_xdevapi\Session::close(): bool

サーバーとのセッションを閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

セッションが閉じられたら true を返します。

例

例1 mysql_xdevapi\Session::close() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$session->close();


トランザクションをコミットする

  • ≪ Session::close
  • Session::__construct ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • トランザクションをコミットする

Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — トランザクションをコミットする

説明

public mysql_xdevapi\Session::commit(): Object

トランザクションをコミットします。

パラメータ

この関数にはパラメータはありません。

戻り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::commit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("friends");

$session->startTransaction();

$collection->add('{"John":42, "Sam":33}')->execute();
$savepoint = $session->setSavepoint();

$session->commit();
$session->close();


Session のコンストラクタ

  • ≪ Session::commit
  • Session::createSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • Session のコンストラクタ

Session::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::__construct — Session のコンストラクタ

説明

private mysql_xdevapi\Session::__construct()

セッションオブジェクトです。 getSession() によってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Session::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->close();
?>


新しいスキーマを作成する

  • ≪ Session::__construct
  • Session::dropSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 新しいスキーマを作成する

Session::createSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::createSchema — 新しいスキーマを作成する

説明

public mysql_xdevapi\Session::createSchema(string $schema_name): mysql_xdevapi\Schema

  新しいスキーマを作成します。

パラメータ

schema_name

作成するスキーマの名前

戻り値

成功した場合はスキーマオブジェクトを返します。 失敗した場合は例外がスローされます。

例

例1 mysql_xdevapi\Session::createSchema() の例

<?php
$uri = 'mysqlx://happyuser:password@127.0.0.1:33060/';
$sess = mysql_xdevapi\getSession($uri);

try {

if ($schema = $sess->createSchema('fruit')) {
echo "Info: I created a schema named 'fruit'\n";
}

} catch (Exception $e) {

echo $e->getMessage();

}
?>

上の例の出力は、 たとえば以下のようになります。

Info: I created a schema named 'fruit'


スキーマを削除します

  • ≪ Session::createSchema
  • Session::generateUUID ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • スキーマを削除します

Session::dropSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::dropSchema — スキーマを削除します

説明

public mysql_xdevapi\Session::dropSchema(string $schema_name): bool

スキーマ(データベース)を削除します。

パラメータ

schema_name

削除するスキーマ

戻り値

スキーマが削除されたら true を返します。 スキーマが存在しないか、削除できない場合は false を返します。

An E_WARNING level error is generated if the schema does not exist.

例

例1 mysql_xdevapi\Session::dropSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->dropSchema("addressbook");

$session->close();
?>


新しいUUIDを取得する

  • ≪ Session::dropSchema
  • Session::getDefaultSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 新しいUUIDを取得する

Session::generateUUID

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::generateUUID — 新しいUUIDを取得する

説明

public mysql_xdevapi\Session::generateUUID(): string

» RFC 4122 に従って UUID を生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

UUID を返します。長さが32の文字列です。

例

例1 mysql_xdevapi\Session::generateUuid() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$uuid = $session->generateUuid();

var_dump($uuid);

上の例の出力は、 たとえば以下のようになります。

string(32) "484B18AC7980F8D4FE84613CDA5EE84B"


デフォルトのスキーマ名を取得する

  • ≪ Session::generateUUID
  • Session::getSchema ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • デフォルトのスキーマ名を取得する

Session::getDefaultSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getDefaultSchema — デフォルトのスキーマ名を取得する

説明

public mysql_xdevapi\Session::getDefaultSchema(): string

通常接続URIに設定される、デフォルトのスキーマ名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

接続に定義されているデフォルトのスキーマ名を返します。 設定されていない場合は、null を返します。

例

例1 mysql_xdevapi\Session::getSchema() の例

<?php
$uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
$session = mysql_xdevapi\getSession($uri);

$schema = $session->getDefaultSchema();
echo $schema;
?>

上の例の出力は以下となります。

testx


新しいスキーマオブジェクトを取得する

  • ≪ Session::getDefaultSchema
  • Session::getSchemas ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 新しいスキーマオブジェクトを取得する

Session::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getSchema — 新しいスキーマオブジェクトを取得する

説明

public mysql_xdevapi\Session::getSchema(string $schema_name): mysql_xdevapi\Schema

与えられたスキーマ名に対応する新しいスキーマオブジェクトを返します。

パラメータ

schema_name

スキーマオブジェクトを取得するためのスキーマ(データベース) の名前

戻り値

Schema オブジェクトを返します。

例

例1 mysql_xdevapi\Session::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$schema = $session->getSchema("addressbook");

print_r($schema);

上の例の出力は、 たとえば以下のようになります。

mysql_xdevapi\Schema Object
(
    [name] => addressbook
)


スキーマを取得する

  • ≪ Session::getSchema
  • Session::getServerVersion ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • スキーマを取得する

Session::getSchemas

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getSchemas — スキーマを取得する

説明

public mysql_xdevapi\Session::getSchemas(): array

セッションで利用可能な全てのスキーマを、スキーマオブジェクトとして取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

セッションで利用可能な全てのスキーマを表現するオブジェクトを含んだ配列を返します。

例

例1 mysql_xdevapi\Session::getSchemas() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$schemas = $session->getSchemas();

print_r($schemas);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => mysql_xdevapi\Schema Object
        (
            [name] => addressbook
        )
    [1] => mysql_xdevapi\Schema Object
        (
            [name] => information_schema
        )
    ...


サーバーのバージョンを取得する

  • ≪ Session::getSchemas
  • Session::listClients ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • サーバーのバージョンを取得する

Session::getServerVersion

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::getServerVersion — サーバーのバージョンを取得する

説明

public mysql_xdevapi\Session::getServerVersion(): int

このセッションにおける MySQL サーバーのバージョンを取得する

パラメータ

この関数にはパラメータはありません。

戻り値

このセッションにおける MySQL サーバーのバージョンを数値として返します。 たとえば "80012" のような値になります。

例

例1 mysql_xdevapi\Session::getServerVersion() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$version = $session->getServerVersion();

var_dump($version);

上の例の出力は、 たとえば以下のようになります。

int(80012)


クライアントの一覧を取得する

  • ≪ Session::getServerVersion
  • Session::quoteName ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • クライアントの一覧を取得する

Session::listClients

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::listClients — クライアントの一覧を取得する

説明

public mysql_xdevapi\Session::listClients(): array

MySQL サーバーのセッションに紐付いたクライアント接続の一覧を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在接続しているクライアントを含んだ配列を返します。 配列の要素には、"client_id", "user", "host", および "sql_session" が含まれています。

例

例1 mysql_xdevapi\Session::listClients() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$ids = $session->listClients();

var_dump($ids);
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["client_id"]=>
    int(61)
    ["user"]=>
    string(4) "root"
    ["host"]=>
    string(9) "localhost"
    ["sql_session"]=>
    int(72)
  }
}


クォートを追加する

  • ≪ Session::listClients
  • Session::releaseSavepoint ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • クォートを追加する

Session::quoteName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::quoteName — クォートを追加する

説明

public mysql_xdevapi\Session::quoteName(string $name): string

SQL の名前や識別子をエスケープするためのクォート関数です。 現在の接続の設定に従って、与えられた識別子をエスケープします。 このエスケープ関数は、値のエスケープに使うべきではありません。

パラメータ

name

クォートする文字列

戻り値

クォートされた文字列を返します。

例

例1 mysql_xdevapi\Session::quoteName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$first = "MySQL's test";
var_dump($first);
var_dump($session->quoteName($first));

$second = 'Another `test` "like" `this`';
var_dump($second);
var_dump($session->quoteName($second));
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "MySQL's test"
string(14) "`MySQL's test`"

string(28) "Another `test` "like" `this`"
string(34) "`Another ``test`` "like" ``this```"


設定されたセーブポイントをリリースする

  • ≪ Session::quoteName
  • Session::rollback ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • 設定されたセーブポイントをリリースする

Session::releaseSavepoint

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::releaseSavepoint — 設定されたセーブポイントをリリースする

説明

public mysql_xdevapi\Session::releaseSavepoint(string $name): void

以前設定したセーブポイントをリリースします。

パラメータ

name

リリースするセーブポイントの名前

戻り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::releaseSavepoint() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("friends");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>


トランザクションをロールバックする

  • ≪ Session::releaseSavepoint
  • Session::rollbackTo ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • トランザクションをロールバックする

Session::rollback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::rollback — トランザクションをロールバックする

説明

public mysql_xdevapi\Session::rollback(): void

トランザクションをロールバックします。

パラメータ

この関数にはパラメータはありません。

戻り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::rollback() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("names");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>


セーブポイントまでトランザクションをロールバックする

  • ≪ Session::rollback
  • Session::setSavepoint ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • セーブポイントまでトランザクションをロールバックする

Session::rollbackTo

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::rollbackTo — セーブポイントまでトランザクションをロールバックする

説明

public mysql_xdevapi\Session::rollbackTo(string $name): void

セーブポイントまでトランザクションをロールバックします。

パラメータ

name

ロールバックされる時点を示すセーブポイントの名前。大文字小文字は区別されません。

戻り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::rollbackTo() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("names");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint1 = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$savepoint2 = $session->setSavepoint();

$session->rollbackTo($savepoint1);
?>


セーブポイントを作成する

  • ≪ Session::rollbackTo
  • Session::sql ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • セーブポイントを作成する

Session::setSavepoint

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::setSavepoint — セーブポイントを作成する

説明

public mysql_xdevapi\Session::setSavepoint(string $name = ?): string

トランザクションのための新しいセーブポイントを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

セーブポイントの名前。 オプションの name パラメータが定義されない場合は、 自動的に作成されます。'SAVEPOINT1', 'SAVEPOINT2' のようなものです。

戻り値

セーブポイントの名前を返します。

例

例1 mysql_xdevapi\Session::setSavepoint() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("names");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>


SQLクエリを作成する

  • ≪ Session::setSavepoint
  • Session::startTransaction ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • SQLクエリを作成する

Session::sql

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::sql — SQLクエリを作成する

説明

public mysql_xdevapi\Session::sql(string $query): mysql_xdevapi\SqlStatement

ネイティブなSQLステートメントを作成します。 プレースホルダーはネイティブな "?" を使ってサポートされます。 SQLステートメントを実行するには、execute メソッドを使ってください。

パラメータ

query

実行するSQLステートメント

戻り値

SqlStatement オブジェクトを返します。

例

例1 mysql_xdevapi\Session::sql() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("CREATE DATABASE addressbook")->execute();
?>


トランザクションを開始する

  • ≪ Session::sql
  • mysql_xdevapi\SqlStatement ≫
  • PHP Manual
  • mysql_xdevapi\Session
  • トランザクションを開始する

Session::startTransaction

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Session::startTransaction — トランザクションを開始する

説明

public mysql_xdevapi\Session::startTransaction(): void

新しいトランザクションを開始します。

パラメータ

この関数にはパラメータはありません。

戻り値

SqlStatementResult オブジェクトを返します。

例

例1 mysql_xdevapi\Session::startTransaction() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$collection = $session->getSchema("addressbook")->getCollection("friends");

$session->startTransaction();
$collection->add( '{"test1":1, "test2":2}' )->execute();

$savepoint = $session->setSavepoint();

$collection->add( '{"test3":3, "test4":4}' )->execute();

$session->releaseSavepoint($savepoint);
$session->rollback();
?>


SqlStatement クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\SqlStatement {
/* 定数 */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* プロパティ */
public $statement;
/* メソッド */
public bind(string $param): mysql_xdevapi\SqlStatement
public execute(): mysql_xdevapi\Result
public getNextResult(): mysql_xdevapi\Result
public getResult(): mysql_xdevapi\Result
public hasMoreResults(): bool
}

プロパティ

statement

定義済み定数

mysql_xdevapi\SqlStatement::EXECUTE_ASYNC

mysql_xdevapi\SqlStatement::BUFFERED

目次

  • SqlStatement::bind — ステートメントのパラメータをバインドする
  • SqlStatement::__construct — SqlStatement のコンストラクタ
  • SqlStatement::execute — 操作を実行する
  • SqlStatement::getNextResult — 次の結果を取得する
  • SqlStatement::getResult — 結果を取得する
  • SqlStatement::hasMoreResults — さらに結果があるかを調べる


ステートメントのパラメータをバインドする

  • ≪ mysql_xdevapi\SqlStatement
  • SqlStatement::__construct ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • ステートメントのパラメータをバインドする

SqlStatement::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::bind — ステートメントのパラメータをバインドする

説明

public mysql_xdevapi\SqlStatement::bind(string $param): mysql_xdevapi\SqlStatement

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

param

戻り値

例

例1 mysql_xdevapi\SqlStatement::bind() の例

<?php

/* ... */

?>


SqlStatement のコンストラクタ

  • ≪ SqlStatement::bind
  • SqlStatement::execute ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • SqlStatement のコンストラクタ

SqlStatement::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::__construct — SqlStatement のコンストラクタ

説明

private mysql_xdevapi\SqlStatement::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\SqlStatement::__construct() の例

<?php

/* ... */

?>


操作を実行する

  • ≪ SqlStatement::__construct
  • SqlStatement::getNextResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • 操作を実行する

SqlStatement::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::execute — 操作を実行する

説明

public mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\SqlStatement::execute() の例

<?php

/* ... */

?>


次の結果を取得する

  • ≪ SqlStatement::execute
  • SqlStatement::getResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • 次の結果を取得する

SqlStatement::getNextResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::getNextResult — 次の結果を取得する

説明

public mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\SqlStatement::getNextResult() の例

<?php

/* ... */

?>


結果を取得する

  • ≪ SqlStatement::getNextResult
  • SqlStatement::hasMoreResults ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • 結果を取得する

SqlStatement::getResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::getResult — 結果を取得する

説明

public mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\SqlStatement::getResult() の例

<?php

/* ... */

?>


さらに結果があるかを調べる

  • ≪ SqlStatement::getResult
  • mysql_xdevapi\SqlStatementResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatement
  • さらに結果があるかを調べる

SqlStatement::hasMoreResults

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatement::hasMoreResults — さらに結果があるかを調べる

説明

public mysql_xdevapi\SqlStatement::hasMoreResults(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果セットがさらにフェッチするオブジェクトを持っていれば true を返します

例

例1 mysql_xdevapi\SqlStatement::hasMoreResults() の例

<?php

/* ... */

?>


SqlStatementResult クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public fetchAll(): array
public fetchOne(): array
public getAffectedItemsCount(): int
public getColumnsCount(): int
public getColumnNames(): array
public getColumns(): Array
public getGeneratedIds(): array
public getLastInsertId(): String
public getWarnings(): array
public getWarningCounts(): int
public hasData(): bool
public nextResult(): mysql_xdevapi\Result
}

目次

  • SqlStatementResult::__construct — SqlStatementResult のコンストラクタ
  • SqlStatementResult::fetchAll — 結果セットから全行取得する
  • SqlStatementResult::fetchOne — 単一の行を取得する
  • SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する
  • SqlStatementResult::getColumnsCount — カラムの数を取得する
  • SqlStatementResult::getColumnNames — カラム名を取得する
  • SqlStatementResult::getColumns — カラムを取得する
  • SqlStatementResult::getGeneratedIds — 生成された id を取得する
  • SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する
  • SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する
  • SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する
  • SqlStatementResult::hasData — 結果がデータを持っているかを調べる
  • SqlStatementResult::nextResult — 次の結果を取得する


SqlStatementResult のコンストラクタ

  • ≪ mysql_xdevapi\SqlStatementResult
  • SqlStatementResult::fetchAll ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • SqlStatementResult のコンストラクタ

SqlStatementResult::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::__construct — SqlStatementResult のコンストラクタ

説明

private mysql_xdevapi\SqlStatementResult::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\SqlStatementResult::__construct() の例

<?php

/* ... */

?>


結果セットから全行取得する

  • ≪ SqlStatementResult::__construct
  • SqlStatementResult::fetchOne ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 結果セットから全行取得する

SqlStatementResult::fetchAll

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::fetchAll — 結果セットから全行取得する

説明

public mysql_xdevapi\SqlStatementResult::fetchAll(): array

結果セットから全ての行を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

クエリから取得した全ての行を数値インデックスの配列として返します。 個々の要素は連想配列です。行が存在しない場合は空の配列を返します。

例

例1 mysql_xdevapi\SqlStatementResult::fetchAll() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
$session->sql("CREATE DATABASE dbtest")->execute();
$session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
$session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

$schema = $session->getSchema("dbtest");
$table = $schema->getTable("workers");

$rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

print_r($rows);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)


単一の行を取得する

  • ≪ SqlStatementResult::fetchAll
  • SqlStatementResult::getAffectedItemsCount ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 単一の行を取得する

SqlStatementResult::fetchOne

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::fetchOne — 単一の行を取得する

説明

public mysql_xdevapi\SqlStatementResult::fetchOne(): array

結果セットから一行取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果を連想配列で返します。 結果がなかった場合は、null が返されます。

例

例1 mysql_xdevapi\SqlStatementResult::fetchOne() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
$session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
$session->sql("CREATE DATABASE dbtest")->execute();
$session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
$session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

$schema = $session->getSchema("dbtest");
$table = $schema->getTable("workers");

$rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

print_r($rows);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => John
    [age] => 42
    [job] => bricklayer
)


影響を受けた行数を取得する

  • ≪ SqlStatementResult::fetchOne
  • SqlStatementResult::getColumnsCount ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 影響を受けた行数を取得する

SqlStatementResult::getAffectedItemsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する

説明

public mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\SqlStatementResult::getAffectedItemsCount() の例

<?php

/* ... */

?>


カラムの数を取得する

  • ≪ SqlStatementResult::getAffectedItemsCount
  • SqlStatementResult::getColumnNames ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • カラムの数を取得する

SqlStatementResult::getColumnsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getColumnsCount — カラムの数を取得する

説明

public mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

カラムの数を返します。存在しない場合は、0を返します。

変更履歴

バージョン | 説明
8.0.14 | メソッド名が、getColumnCount() から getColumnsCount() に変わりました。

例

例1 mysql_xdevapi\SqlStatementResult::getColumnsCount() の例

<?php

/* ... */

?>


カラム名を取得する

  • ≪ SqlStatementResult::getColumnsCount
  • SqlStatementResult::getColumns ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • カラム名を取得する

SqlStatementResult::getColumnNames

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getColumnNames — カラム名を取得する

説明

public mysql_xdevapi\SqlStatementResult::getColumnNames(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\SqlStatementResult::getColumnNames() の例

<?php

/* ... */

?>


カラムを取得する

  • ≪ SqlStatementResult::getColumnNames
  • SqlStatementResult::getGeneratedIds ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • カラムを取得する

SqlStatementResult::getColumns

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getColumns — カラムを取得する

説明

public mysql_xdevapi\SqlStatementResult::getColumns(): Array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\SqlStatementResult::getColumns() の例

<?php

/* ... */

?>


生成された id を取得する

  • ≪ SqlStatementResult::getColumns
  • SqlStatementResult::getLastInsertId ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 生成された id を取得する

SqlStatementResult::getGeneratedIds

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getGeneratedIds — 生成された id を取得する

説明

public mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作で生成された _id の配列を返します。 生成された _id がなければ、空の配列を返します。

例

例1 mysql_xdevapi\SqlStatementResult::getGeneratedIds() の例

<?php

/* ... */

?>


最後に挿入されたidを取得する

  • ≪ SqlStatementResult::getGeneratedIds
  • SqlStatementResult::getWarnings ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 最後に挿入されたidを取得する

SqlStatementResult::getLastInsertId

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する

説明

public mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

最後に挿入された操作のIDを返します。

例

例1 mysql_xdevapi\SqlStatementResult::getLastInsertId() の例

<?php

/* ... */

?>


直近の操作から発生した警告を取得する

  • ≪ SqlStatementResult::getLastInsertId
  • SqlStatementResult::getWarningsCount ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 直近の操作から発生した警告を取得する

SqlStatementResult::getWarnings

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する

説明

public mysql_xdevapi\SqlStatementResult::getWarnings(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の操作によって発生した警告の数を返します。 個々のオブジェクトは、エラーの 'message', 'level' そして 'code' を定義しています。 エラーが発生しなかった場合は空の配列が返されます。

例

例1 mysql_xdevapi\SqlStatementResult::getWarnings() の例

<?php

/* ... */

?>


直近の操作で発生した警告の数を取得する

  • ≪ SqlStatementResult::getWarnings
  • SqlStatementResult::hasData ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 直近の操作で発生した警告の数を取得する

SqlStatementResult::getWarningsCount

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

説明

public mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

直近のCRUD操作の間に発生した警告の数を返します。

例

例1 mysql_xdevapi\SqlStatementResult::getWarningsCount() の例

<?php

/* ... */

?>


結果がデータを持っているかを調べる

  • ≪ SqlStatementResult::getWarningsCount
  • SqlStatementResult::nextResult ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 結果がデータを持っているかを調べる

SqlStatementResult::hasData

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::hasData — 結果がデータを持っているかを調べる

説明

public mysql_xdevapi\SqlStatementResult::hasData(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果がデータを持っていれば true を返します。

例

例1 mysql_xdevapi\SqlStatementResult::hasData() の例

<?php

/* ... */

?>


次の結果を取得する

  • ≪ SqlStatementResult::hasData
  • mysql_xdevapi\Statement ≫
  • PHP Manual
  • mysql_xdevapi\SqlStatementResult
  • 次の結果を取得する

SqlStatementResult::nextResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SqlStatementResult::nextResult — 次の結果を取得する

説明

public mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

結果セットから、次の Result オブジェクトを返します。

例

例1 mysql_xdevapi\SqlStatementResult::nextResult() の例

<?php

/* ... */

?>


Statement クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Statement {
/* 定数 */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* メソッド */
public getNextResult(): mysql_xdevapi\Result
public getResult(): mysql_xdevapi\Result
public hasMoreResults(): bool
}

定義済み定数

mysql_xdevapi\Statement::EXECUTE_ASYNC

mysql_xdevapi\Statement::BUFFERED

目次

  • Statement::__construct — Statement のコンストラクタ
  • Statement::getNextResult — 次の結果を取得する
  • Statement::getResult — 結果を取得する
  • Statement::hasMoreResults — さらに結果があるかを調べる


Statement のコンストラクタ

  • ≪ mysql_xdevapi\Statement
  • Statement::getNextResult ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • Statement のコンストラクタ

Statement::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::__construct — Statement のコンストラクタ

説明

private mysql_xdevapi\Statement::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Statement::__construct() の例

<?php

/* ... */

?>


次の結果を取得する

  • ≪ Statement::__construct
  • Statement::getResult ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • 次の結果を取得する

Statement::getNextResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::getNextResult — 次の結果を取得する

説明

public mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\Statement::getNextResult() の例

<?php

/* ... */

?>


結果を取得する

  • ≪ Statement::getNextResult
  • Statement::hasMoreResults ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • 結果を取得する

Statement::getResult

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::getResult — 結果を取得する

説明

public mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\Statement::getResult() の例

<?php

/* ... */

?>


さらに結果があるかを調べる

  • ≪ Statement::getResult
  • mysql_xdevapi\Table ≫
  • PHP Manual
  • mysql_xdevapi\Statement
  • さらに結果があるかを調べる

Statement::hasMoreResults

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Statement::hasMoreResults — さらに結果があるかを調べる

説明

public mysql_xdevapi\Statement::hasMoreResults(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 mysql_xdevapi\Statement::hasMoreResults() の例

<?php

/* ... */

?>


Table クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

INSERT/SELECT/UPDATE/DELETE ステートメントを通じて、テーブルへのアクセスを提供します。

クラス概要

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* プロパティ */
public $name;
/* メソッド */
public count(): int
public delete(): mysql_xdevapi\TableDelete
public existsInDatabase(): bool
public getName(): string
public getSchema(): mysql_xdevapi\Schema
public getSession(): mysql_xdevapi\Session
public insert(mixed $columns, mixed ...$more_columns): mysql_xdevapi\TableInsert
public isView(): bool
public select(mixed $columns, mixed ...$more_columns): mysql_xdevapi\TableSelect
public update(): mysql_xdevapi\TableUpdate
}

プロパティ

name

目次

  • Table::__construct — Table のコンストラクタ
  • Table::count — 行の数を取得する
  • Table::delete — テーブルから行を削除する
  • Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする
  • Table::getName — テーブル名を取得する
  • Table::getSchema — テーブルスキーマを取得する
  • Table::getSession — テーブルを操作するためのセッションを取得する
  • Table::insert — テーブルに行を挿入する
  • Table::isView — テーブルがビューかどうかを調べる
  • Table::select — テーブルから行を選択する
  • Table::update — テーブルの行を更新する


Table のコンストラクタ

  • ≪ mysql_xdevapi\Table
  • Table::count ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • Table のコンストラクタ

Table::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::__construct — Table のコンストラクタ

説明

private mysql_xdevapi\Table::__construct()

テーブルオブジェクトを構築します。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Table::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");
?>


行の数を取得する

  • ≪ Table::__construct
  • Table::delete ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • 行の数を取得する

Table::count

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::count — 行の数を取得する

説明

public mysql_xdevapi\Table::count(): int

テーブルの行数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

テーブルの合計の行数を返します。

例

例1 mysql_xdevapi\Table::count() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

var_dump($table->count());
?>

上の例の出力は以下となります。

int(2)


テーブルから行を削除する

  • ≪ Table::count
  • Table::existsInDatabase ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルから行を削除する

Table::delete

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::delete — テーブルから行を削除する

説明

public mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

テーブルから行を削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

TableDelete オブジェクトを返します。 delete 文を実行するには、execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::delete() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
?>


テーブルがデータベースに存在するかをチェックする

  • ≪ Table::delete
  • Table::getName ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルがデータベースに存在するかをチェックする

Table::existsInDatabase

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする

説明

public mysql_xdevapi\Table::existsInDatabase(): bool

このテーブルがデータベースに存在するかを検証します。

パラメータ

この関数にはパラメータはありません。

戻り値

テーブルがデータベースに存在していれば true を返します。 そうでなければ、false を返します。

例

例1 mysql_xdevapi\Table::existsInDatabase() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

if ($table->existsInDatabase()) {
echo "Yes, this table still exists in the session's schema.";
}
?>

上の例の出力は、 たとえば以下のようになります。

Yes, this table still exists in the session's schema.


テーブル名を取得する

  • ≪ Table::existsInDatabase
  • Table::getSchema ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブル名を取得する

Table::getName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::getName — テーブル名を取得する

説明

public mysql_xdevapi\Table::getName(): string

このデータベースオブジェクトの名前を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

データベースオブジェクトの名前を返します。

例

例1 mysql_xdevapi\Table::getName() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

var_dump($table->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "names"


テーブルスキーマを取得する

  • ≪ Table::getName
  • Table::getSession ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルスキーマを取得する

Table::getSchema

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::getSchema — テーブルスキーマを取得する

説明

public mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

テーブルに紐付いたスキーマを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Schema オブジェクトを返します。

例

例1 mysql_xdevapi\Table::getSchema() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

var_dump($table->getSchema());
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Schema)#9 (1) {
  ["name"]=>
  string(11) "addressbook"
}


テーブルを操作するためのセッションを取得する

  • ≪ Table::getSchema
  • Table::insert ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルを操作するためのセッションを取得する

Table::getSession

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::getSession — テーブルを操作するためのセッションを取得する

説明

public mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

テーブルに紐付いたセッションを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Session オブジェクトを返します。

例

例1 mysql_xdevapi\Table::getSession() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

var_dump($table->getSession());
?>

上の例の出力は、 たとえば以下のようになります。

object(mysql_xdevapi\Session)#9 (0) {
}


テーブルに行を挿入する

  • ≪ Table::getSession
  • Table::isView ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルに行を挿入する

Table::insert

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::insert — テーブルに行を挿入する

説明

public mysql_xdevapi\Table::insert(mixed $columns, mixed ...$more_columns): mysql_xdevapi\TableInsert

テーブルに行を挿入します。

パラメータ

columns

データを挿入するカラム。 ひとつ以上の値を持つ配列か、文字列です。

more_columns

追加のカラム定義

戻り値

TableInsert オブジェクトを返します。 insert 文を実行するには、 execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::insert() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table ->insert("name", "age")
->values(["Suzanne", 31],["Julie", 43])
->execute();
?>


テーブルがビューかどうかを調べる

  • ≪ Table::insert
  • Table::select ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルがビューかどうかを調べる

Table::isView

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::isView — テーブルがビューかどうかを調べる

説明

public mysql_xdevapi\Table::isView(): bool

オブジェクトがビューかそうでないかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトがビューであるなら true そうでないなら false を返します。

例

例1 mysql_xdevapi\Table::isView() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

if ($table->isView()) {
echo "This is a view.";
} else {
echo "This is not a view.";
}
?>

上の例の出力は以下となります。

This is not a view.


テーブルから行を選択する

  • ≪ Table::isView
  • Table::update ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルから行を選択する

Table::select

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::select — テーブルから行を選択する

説明

public mysql_xdevapi\Table::select(mixed $columns, mixed ...$more_columns): mysql_xdevapi\TableSelect

テーブルからデータを取得します。

パラメータ

columns

データを選択するカラム。 一つ以上の値を持つ配列、または文字列。

more_columns

追加のカラムパラメータ

戻り値

TableSelect オブジェクトを返します。 select 文を実行し、RowResult オブジェクトを得るには、 execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::count() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$row = $table->select('name', 'age')->execute()->fetchAll();

print_r($row);

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 33
        )
)


テーブルの行を更新する

  • ≪ Table::select
  • mysql_xdevapi\TableDelete ≫
  • PHP Manual
  • mysql_xdevapi\Table
  • テーブルの行を更新する

Table::update

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Table::update — テーブルの行を更新する

説明

public mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

テーブルのカラムを更新します。

パラメータ

この関数にはパラメータはありません。

戻り値

TableUpdate オブジェクトを返します。 update 文を実行するには、execute() メソッドを使ってください。

例

例1 mysql_xdevapi\Table::update() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
?>


TableDelete クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブルのレコードを削除する操作を行うためのステートメントです。

クラス概要

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* メソッド */
public bind(array $placeholder_values): mysql_xdevapi\TableDelete
public execute(): mysql_xdevapi\Result
public limit(int $rows): mysql_xdevapi\TableDelete
public orderby(string $orderby_expr): mysql_xdevapi\TableDelete
public where(string $where_expr): mysql_xdevapi\TableDelete
}

目次

  • TableDelete::bind — delete のクエリパラメータをバインドする
  • TableDelete::__construct — TableDelete のコンストラクタ
  • TableDelete::execute — delete文を実行する
  • TableDelete::limit — 削除する行を限定する
  • TableDelete::orderby — 削除の際のソート条件を設定する
  • TableDelete::where — 削除時の検索条件を設定する


delete のクエリパラメータをバインドする

  • ≪ mysql_xdevapi\TableDelete
  • TableDelete::__construct ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • delete のクエリパラメータをバインドする

TableDelete::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::bind — delete のクエリパラメータをバインドする

説明

public mysql_xdevapi\TableDelete::bind(array $placeholder_values): mysql_xdevapi\TableDelete

特定のプレースホルダーの値をバインドします。

パラメータ

placeholder_values

プレースホルダーの名前、およびバインドする値です。

戻り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()
->where("name = :name")
->bind(['name' => 'John'])
->orderby("age DESC")
->limit(1)
->execute();

?>


TableDelete のコンストラクタ

  • ≪ TableDelete::bind
  • TableDelete::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • TableDelete のコンストラクタ

TableDelete::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::__construct — TableDelete のコンストラクタ

説明

private mysql_xdevapi\TableDelete::__construct()

delete() メソッドを使ってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableDelete::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()
->where("name = :name")
->bind(['name' => 'John'])
->orderby("age DESC")
->limit(1)
->execute();

?>


delete文を実行する

  • ≪ TableDelete::__construct
  • TableDelete::limit ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • delete文を実行する

TableDelete::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::execute — delete文を実行する

説明

public mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

delete文を実行します。

パラメータ

この関数にはパラメータはありません。

戻り値

Result オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()
->where("name = :name")
->bind(['name' => 'John'])
->orderby("age DESC")
->limit(1)
->execute();

?>


削除する行を限定する

  • ≪ TableDelete::execute
  • TableDelete::orderby ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • 削除する行を限定する

TableDelete::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::limit — 削除する行を限定する

説明

public mysql_xdevapi\TableDelete::limit(int $rows): mysql_xdevapi\TableDelete

削除するレコードまたはドキュメントの最大数を設定します

パラメータ

rows

削除するレコードまたはドキュメントの最大数

戻り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()
->where("name = :name")
->bind(['name' => 'John'])
->orderby("age DESC")
->limit(1)
->execute();

?>


削除の際のソート条件を設定する

  • ≪ TableDelete::limit
  • TableDelete::where ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • 削除の際のソート条件を設定する

TableDelete::orderby

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::orderby — 削除の際のソート条件を設定する

説明

public mysql_xdevapi\TableDelete::orderby(string $orderby_expr): mysql_xdevapi\TableDelete

結果セットのソート条件を設定します。

パラメータ

orderby_expr

ソート条件

戻り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::orderBy() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()
->where("age = :age")
->bind(['age' => 42])
->orderby("name DESC")
->limit(1)
->execute();

?>


削除時の検索条件を設定する

  • ≪ TableDelete::orderby
  • mysql_xdevapi\TableInsert ≫
  • PHP Manual
  • mysql_xdevapi\TableDelete
  • 削除時の検索条件を設定する

TableDelete::where

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableDelete::where — 削除時の検索条件を設定する

説明

public mysql_xdevapi\TableDelete::where(string $where_expr): mysql_xdevapi\TableDelete

フィルタのための検索条件を設定します。

パラメータ

where_expr

ドキュメントまたはレコードをフィルタする検索条件を定義します。

戻り値

TableDelete オブジェクトを返します。

例

例1 mysql_xdevapi\TableDelete::where() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->delete()
->where("id = :id")
->bind(['id' => 42])
->limit(1)
->execute();

?>


TableInsert クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブルにレコードを挿入する操作を行うステートメントです

クラス概要

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* メソッド */
public execute(): mysql_xdevapi\Result
public values(array $row_values): mysql_xdevapi\TableInsert
}

目次

  • TableInsert::__construct — TableInsert クラスのコンストラクタ
  • TableInsert::execute — insert クエリを実行する
  • TableInsert::values — 挿入する行の値を追加する


TableInsert クラスのコンストラクタ

  • ≪ mysql_xdevapi\TableInsert
  • TableInsert::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableInsert
  • TableInsert クラスのコンストラクタ

TableInsert::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableInsert::__construct — TableInsert クラスのコンストラクタ

説明

private mysql_xdevapi\TableInsert::__construct()

insert() メソッドを使ってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableInsert::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table
->insert("name", "age")
->values(["Suzanne", 31],["Julie", 43])
->execute();
?>


insert クエリを実行する

  • ≪ TableInsert::__construct
  • TableInsert::values ≫
  • PHP Manual
  • mysql_xdevapi\TableInsert
  • insert クエリを実行する

TableInsert::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableInsert::execute — insert クエリを実行する

説明

public mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

insert 文を実行します。

パラメータ

この関数にはパラメータはありません。

戻り値

Result オブジェクトを返します。

例

例1 mysql_xdevapi\TableInsert::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table
->insert("name", "age")
->values(["Suzanne", 31],["Julie", 43])
->execute();
?>


挿入する行の値を追加する

  • ≪ TableInsert::execute
  • mysql_xdevapi\TableSelect ≫
  • PHP Manual
  • mysql_xdevapi\TableInsert
  • 挿入する行の値を追加する

TableInsert::values

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableInsert::values — 挿入する行の値を追加する

説明

public mysql_xdevapi\TableInsert::values(array $row_values): mysql_xdevapi\TableInsert

挿入する値を設定します。

パラメータ

row_values

挿入するカラムの値(の配列)

戻り値

TableInsert オブジェクトを返します。

例

例1 mysql_xdevapi\TableInsert::values() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table
->insert("name", "age")
->values(["Suzanne", 31],["Julie", 43])
->execute();
?>


TableSelect クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブルからレコードを取得する操作を行うステートメントです

クラス概要

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* メソッド */
public bind(array $placeholder_values): mysql_xdevapi\TableSelect
public execute(): mysql_xdevapi\RowResult
public groupBy(mixed $sort_expr): mysql_xdevapi\TableSelect
public having(string $sort_expr): mysql_xdevapi\TableSelect
public limit(int $rows): mysql_xdevapi\TableSelect
public lockExclusive(int $lock_waiting_option = ?): mysql_xdevapi\TableSelect
public lockShared(int $lock_waiting_option = ?): mysql_xdevapi\TableSelect
public offset(int $position): mysql_xdevapi\TableSelect
public orderby(mixed $sort_expr, mixed ...$sort_exprs): mysql_xdevapi\TableSelect
public where(string $where_expr): mysql_xdevapi\TableSelect
}

目次

  • TableSelect::bind — select のクエリパラメータをバインドする
  • TableSelect::__construct — TableSelect のコンストラクタ
  • TableSelect::execute — select ステートメントを実行する
  • TableSelect::groupBy — select 時のグループ化の条件を設定する
  • TableSelect::having — select 句の having 条件を設定する
  • TableSelect::limit — 選択される行の数を限定する
  • TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する
  • TableSelect::lockShared — SHARED LOCK を実行する
  • TableSelect::offset — スキップするoffsetを設定する
  • TableSelect::orderby — select 文のソート条件を設定する
  • TableSelect::where — select 文の検索条件を設定する


select のクエリパラメータをバインドする

  • ≪ mysql_xdevapi\TableSelect
  • TableSelect::__construct ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select のクエリパラメータをバインドする

TableSelect::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::bind — select のクエリパラメータをバインドする

説明

public mysql_xdevapi\TableSelect::bind(array $placeholder_values): mysql_xdevapi\TableSelect

特定のプレースホルダーの値をバインドします。

パラメータ

placeholder_values

プレースホルダーの名前、およびバインドする値

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name','age')
->where('name like :name and age > :age')
->bind(['name' => 'John', 'age' => 42])
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)


TableSelect のコンストラクタ

  • ≪ TableSelect::bind
  • TableSelect::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • TableSelect のコンストラクタ

TableSelect::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::__construct — TableSelect のコンストラクタ

説明

private mysql_xdevapi\TableSelect::__construct()

select() メソッドによって返されるオブジェクトです。 クエリを実行するには execute() を使ってください。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableSelect::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name','age')
->where('name like :name and age > :age')
->bind(['name' => 'John', 'age' => 42])
->orderBy('age desc')
->execute();

$row = $result->fetchAll();
print_r($row);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)


select ステートメントを実行する

  • ≪ TableSelect::__construct
  • TableSelect::groupBy ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select ステートメントを実行する

TableSelect::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::execute — select ステートメントを実行する

説明

public mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

execute() メソッドとチェインすることで、select ステートメントを実行します。

パラメータ

この関数にはパラメータはありません。

戻り値

RowResult オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name','age')
->where('name like :name and age > :age')
->bind(['name' => 'John', 'age' => 42])
->orderBy('age desc')
->execute();

$row = $result->fetchAll();
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)


select 時のグループ化の条件を設定する

  • ≪ TableSelect::execute
  • TableSelect::having ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 時のグループ化の条件を設定する

TableSelect::groupBy

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::groupBy — select 時のグループ化の条件を設定する

説明

public mysql_xdevapi\TableSelect::groupBy(mixed $sort_expr): mysql_xdevapi\TableSelect

結果セットのグループ化条件を設定します。

パラメータ

sort_expr

グループ化条件

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::groupBy() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
$session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('count(*) as count', 'age')
->groupBy('age')->orderBy('age asc')
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [count] => 1
            [age] => 31
        )
    [1] => Array
        (
            [count] => 2
            [age] => 42
        )
)


select 句の having 条件を設定する

  • ≪ TableSelect::groupBy
  • TableSelect::limit ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 句の having 条件を設定する

TableSelect::having

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::having — select 句の having 条件を設定する

説明

public mysql_xdevapi\TableSelect::having(string $sort_expr): mysql_xdevapi\TableSelect

集約関数の操作において考慮すべき、レコードの条件を設定します。

パラメータ

sort_expr

グループ化の条件で使われる、集約関数の条件

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::having() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
$session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('count(*) as count', 'age')
->groupBy('age')->orderBy('age asc')
->having('count > 1')
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [count] => 2
            [age] => 42
        )
)


選択される行の数を限定する

  • ≪ TableSelect::having
  • TableSelect::lockExclusive ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • 選択される行の数を限定する

TableSelect::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::limit — 選択される行の数を限定する

説明

public mysql_xdevapi\TableSelect::limit(int $rows): mysql_xdevapi\TableSelect

返されるレコードまたはドキュメントの数の最大値を設定します。

パラメータ

rows

レコードまたはドキュメントの数の最大値

戻り値

TableSelect オブジェクトを返します

例

例1 mysql_xdevapi\TableSelect::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name', 'age')
->limit(1)
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)


EXCLUSIVE LOCK を実行する

  • ≪ TableSelect::limit
  • TableSelect::lockShared ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • EXCLUSIVE LOCK を実行する

TableSelect::lockExclusive

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する

説明

public mysql_xdevapi\TableSelect::lockExclusive(int $lock_waiting_option = ?): mysql_xdevapi\TableSelect

EXCLUSIVE LOCK 付きで読み取り操作を実行します。 一度にアクティブになれるロックはひとつだけです。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::lockExclusive() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$session->startTransaction();

$result = $table->select('name', 'age')
->lockExclusive(MYSQLX_LOCK_NOWAIT)
->execute();

$session->commit();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 42
        )
)


SHARED LOCK を実行する

  • ≪ TableSelect::lockExclusive
  • TableSelect::offset ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • SHARED LOCK を実行する

TableSelect::lockShared

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::lockShared — SHARED LOCK を実行する

説明

public mysql_xdevapi\TableSelect::lockShared(int $lock_waiting_option = ?): mysql_xdevapi\TableSelect

読み取り操作を SHARED LOCK 付きで実行します。 アクティブになれるロックは一度にひとつだけです。

パラメータ

lock_waiting_option

オプションで指定できる、ロック待ちのオプション。 デフォルトは MYSQLX_LOCK_DEFAULT です。 有効な値は以下のとおりです:

  • MYSQLX_LOCK_DEFAULT

  • MYSQLX_LOCK_NOWAIT

  • MYSQLX_LOCK_SKIP_LOCKED

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::lockShared() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$session->startTransaction();

$result = $table->select('name', 'age')
->lockShared(MYSQLX_LOCK_NOWAIT)
->execute();

$session->commit();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
    [1] => Array
        (
            [name] => Sam
            [age] => 42
        )
)


スキップするoffsetを設定する

  • ≪ TableSelect::lockShared
  • TableSelect::orderby ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • スキップするoffsetを設定する

TableSelect::offset

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::offset — スキップするoffsetを設定する

説明

public mysql_xdevapi\TableSelect::offset(int $position): mysql_xdevapi\TableSelect

結果セットの行を、与えられた数だけスキップします

パラメータ

position

スキップするオフセットの数

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::offset() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
$session->sql("CREATE DATABASE addressbook")->execute();
$session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
$session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name', 'age')
->limit(1)
->offset(1)
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => Sam
            [age] => 42
        )
)


select 文のソート条件を設定する

  • ≪ TableSelect::offset
  • TableSelect::where ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 文のソート条件を設定する

TableSelect::orderby

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::orderby — select 文のソート条件を設定する

説明

public mysql_xdevapi\TableSelect::orderby(mixed $sort_expr, mixed ...$sort_exprs): mysql_xdevapi\TableSelect

ソート順の条件を設定します。

パラメータ

sort_expr

ソート順の条件を定義した式。 単一の文字列化、ひとつ以上の式を持つ配列。

sort_exprs

追加の sort_expr パラメータ

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::orderBy() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name', 'age')
->orderBy('name desc')
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => Sam
            [age] => 42
        )
    [1] => Array
        (
            [name] => John
            [age] => 42
        )
)


select 文の検索条件を設定する

  • ≪ TableSelect::orderby
  • mysql_xdevapi\TableUpdate ≫
  • PHP Manual
  • mysql_xdevapi\TableSelect
  • select 文の検索条件を設定する

TableSelect::where

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableSelect::where — select 文の検索条件を設定する

説明

public mysql_xdevapi\TableSelect::where(string $where_expr): mysql_xdevapi\TableSelect

フィルタのための検索条件を設定します。

パラメータ

where_expr

ドキュメントまたはレコードをフィルタするための検索条件

戻り値

TableSelect オブジェクトを返します。

例

例1 mysql_xdevapi\TableSelect::where() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$result = $table->select('name','age')
->where('name like :name and age > :age')
->bind(['name' => 'John', 'age' => 42])
->execute();

$row = $result->fetchAll();
print_r($row);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [name] => John
            [age] => 42
        )
)


TableUpdate クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

テーブル上のレコードを更新する操作を行うステートメントです。

クラス概要

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* メソッド */
public bind(array $placeholder_values): mysql_xdevapi\TableUpdate
public execute(): mysql_xdevapi\TableUpdate
public limit(int $rows): mysql_xdevapi\TableUpdate
public orderby(mixed $orderby_expr, mixed ...$orderby_exprs): mysql_xdevapi\TableUpdate
public set(string $table_field, string $expression_or_literal): mysql_xdevapi\TableUpdate
public where(string $where_expr): mysql_xdevapi\TableUpdate
}

目次

  • TableUpdate::bind — update のクエリパラメータをバインドする
  • TableUpdate::__construct — TableUpdate のコンストラクタ
  • TableUpdate::execute — update クエリを実行する
  • TableUpdate::limit — 更新する行の数を限定する
  • TableUpdate::orderby — ソート条件を設定する
  • TableUpdate::set — 更新されるフィールドを追加する
  • TableUpdate::where — 検索フィルタを設定する


update のクエリパラメータをバインドする

  • ≪ mysql_xdevapi\TableUpdate
  • TableUpdate::__construct ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • update のクエリパラメータをバインドする

TableUpdate::bind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::bind — update のクエリパラメータをバインドする

説明

public mysql_xdevapi\TableUpdate::bind(array $placeholder_values): mysql_xdevapi\TableUpdate

特定のプレースホルダーの値をバインドします。

パラメータ

placeholder_values

プレースホルダーの名前、およびバインドする値です。 JSON の配列として定義されます。

戻り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::bind() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$table->update()
->set('status', 'admin')
->where('name = :name and age > :age')
->bind(['name' => 'Bernie', 'age' => 2000])
->execute();

?>


TableUpdate のコンストラクタ

  • ≪ TableUpdate::bind
  • TableUpdate::execute ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • TableUpdate のコンストラクタ

TableUpdate::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::__construct — TableUpdate のコンストラクタ

説明

private mysql_xdevapi\TableUpdate::__construct()

update() メソッドを使ってインスタンス化されます。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\TableUpdate::__construct() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$res = $table->update()
->set('level', 3)
->where('age > 15 and age < 22')
->limit(4)
->orderby(['age asc','name desc'])
->execute();

?>


update クエリを実行する

  • ≪ TableUpdate::__construct
  • TableUpdate::limit ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • update クエリを実行する

TableUpdate::execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::execute — update クエリを実行する

説明

public mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

update 文を実行します。

パラメータ

この関数にはパラメータはありません。

戻り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::execute() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$res = $table->update()
->set('level', 3)
->where('age > 15 and age < 22')
->limit(4)
->orderby(['age asc','name desc'])
->execute();

?>


更新する行の数を限定する

  • ≪ TableUpdate::execute
  • TableUpdate::orderby ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • 更新する行の数を限定する

TableUpdate::limit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::limit — 更新する行の数を限定する

説明

public mysql_xdevapi\TableUpdate::limit(int $rows): mysql_xdevapi\TableUpdate

更新するレコードまたはドキュメントの数の最大値を設定します。

パラメータ

rows

更新するレコードまたはドキュメントの数の最大値

戻り値

TableUpdate オブジェクトを返します

例

例1 mysql_xdevapi\TableUpdate::limit() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$res = $table->update()
->set('level', 3)
->where('age > 15 and age < 22')
->limit(4)
->orderby(['age asc','name desc'])
->execute();

?>


ソート条件を設定する

  • ≪ TableUpdate::limit
  • TableUpdate::set ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • ソート条件を設定する

TableUpdate::orderby

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::orderby — ソート条件を設定する

説明

public mysql_xdevapi\TableUpdate::orderby(mixed $orderby_expr, mixed ...$orderby_exprs): mysql_xdevapi\TableUpdate

ソート条件を設定します。

パラメータ

orderby_expr

ソート条件を定義する式。 ひとつまたはそれ以上の式の配列、または文字列。

orderby_exprs

追加のソート条件のパラメータ

戻り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::orderby() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$res = $table->update()
->set('level', 3)
->where('age > 15 and age < 22')
->limit(4)
->orderby(['age asc','name desc'])
->execute();
?>


更新されるフィールドを追加する

  • ≪ TableUpdate::orderby
  • TableUpdate::where ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • 更新されるフィールドを追加する

TableUpdate::set

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::set — 更新されるフィールドを追加する

説明

public mysql_xdevapi\TableUpdate::set(string $table_field, string $expression_or_literal): mysql_xdevapi\TableUpdate

テーブルのレコード上のカラムの値を更新します。

パラメータ

table_field

更新されるカラム名

expression_or_literal

指定されたカラムに設定する値

戻り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::set() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$res = $table->update()
->set('level', 3)
->where('age > 15 and age < 22')
->limit(4)
->orderby(['age asc','name desc'])
->execute();

?>


検索フィルタを設定する

  • ≪ TableUpdate::set
  • mysql_xdevapi\Warning ≫
  • PHP Manual
  • mysql_xdevapi\TableUpdate
  • 検索フィルタを設定する

TableUpdate::where

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

TableUpdate::where — 検索フィルタを設定する

説明

public mysql_xdevapi\TableUpdate::where(string $where_expr): mysql_xdevapi\TableUpdate

フィルタのための検索条件を設定します。

パラメータ

where_expr

ドキュメントまたはレコードをフィルタする検索条件

戻り値

TableUpdate オブジェクトを返します。

例

例1 mysql_xdevapi\TableUpdate::where() の例

<?php
$session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

$schema = $session->getSchema("addressbook");
$table = $schema->getTable("names");

$res = $table->update()
->set('level', 3)
->where('age > 15 and age < 22')
->limit(4)
->orderby(['age asc','name desc'])
->execute();

?>


Warning クラス

(PECL mysql-xdevapi >= 8.0.11)

はじめに

クラス概要

class mysql_xdevapi\Warning {
/* プロパティ */
public $message;
public $level;
public $code;
/* Constructor */
private __construct()
}

プロパティ

message

level

code

目次

  • Warning::__construct — Warning のコンストラクタ


Warning のコンストラクタ

  • ≪ mysql_xdevapi\Warning
  • MySQL (最初の API) ≫
  • PHP Manual
  • mysql_xdevapi\Warning
  • Warning のコンストラクタ

Warning::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Warning::__construct — Warning のコンストラクタ

説明

private mysql_xdevapi\Warning::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 mysql_xdevapi\Warning::__construct() の例

<?php

/* ... */

?>


最初の MySQL API

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 変更履歴
  • 定義済み定数
  • 例
    • MySQL 拡張モジュールの概要を示す例
  • MySQL 関数
    • mysql_affected_rows — 一番最近の操作で変更された行の数を得る
    • mysql_client_encoding — 文字セット名を返す
    • mysql_close — MySQL 接続を閉じる
    • mysql_connect — MySQL サーバーへの接続をオープンする
    • mysql_create_db — MySQL データベースを作成する
    • mysql_data_seek — 内部的な結果ポインタを移動する
    • mysql_db_name — mysql_list_dbs のコール結果からデータベース名を取得する
    • mysql_db_query — データベースを選択し、そこでクエリーを実行する
    • mysql_drop_db — MySQLデータベースを破棄(削除)する
    • mysql_errno — 直近の MySQL 処理からエラーメッセージのエラー番号を返す
    • mysql_error — 直近に実行された MySQL 操作のエラーメッセージを返す
    • mysql_escape_string — mysql_query で使用するために文字列をエスケープする
    • mysql_fetch_array — 連想配列、添字配列、またはその両方として結果の行を取得する
    • mysql_fetch_assoc — 連想配列として結果の行を取得する
    • mysql_fetch_field — 結果からカラム情報を取得し、オブジェクトとして返す
    • mysql_fetch_lengths — 結果における各出力の長さを得る
    • mysql_fetch_object — 結果の行をオブジェクトとして取得する
    • mysql_fetch_row — 結果を添字配列として取得する
    • mysql_field_flags — 結果において指定したフィールドのフラグを取得する
    • mysql_field_len — 指定したフィールドの長さを返す
    • mysql_field_name — 結果において指定したフィールド名を取得する
    • mysql_field_seek — 結果ポインタを指定したフィールドオフセットにセットする
    • mysql_field_table — 指定したフィールドが含まれるテーブルの名前を取得する
    • mysql_field_type — 結果において指定したフィールドの型を取得する
    • mysql_free_result — 結果保持用メモリを開放する
    • mysql_get_client_info — MySQL クライアント情報を取得する
    • mysql_get_host_info — MySQL ホスト情報を取得する
    • mysql_get_proto_info — MySQL プロトコル情報を取得する
    • mysql_get_server_info — MySQL サーバー情報を取得する
    • mysql_info — 直近のクエリについての情報を得る
    • mysql_insert_id — 直近のクエリで生成された ID を得る
    • mysql_list_dbs — MySQL サーバー上で利用可能なデータベースのリストを得る
    • mysql_list_fields — MySQL テーブルのフィールドのリストを得る
    • mysql_list_processes — MySQL プロセスのリストを得る
    • mysql_list_tables — MySQL データベース上のテーブルのリストを得る
    • mysql_num_fields — 結果におけるフィールドの数を得る
    • mysql_num_rows — 結果における行の数を得る
    • mysql_pconnect — MySQL サーバーへの持続的な接続をオープンする
    • mysql_ping — サーバーとの接続状況を調べ、接続されていない場合は再接続する
    • mysql_query — MySQL クエリを送信する
    • mysql_real_escape_string — SQL 文中で用いる文字列の特殊文字をエスケープする
    • mysql_result — 結果データを得る
    • mysql_select_db — MySQL データベースを選択する
    • mysql_set_charset — クライアントの文字セットを設定する
    • mysql_stat — 現在のシステムの状態を取得する
    • mysql_tablename — フィールドのテーブル名を得る
    • mysql_thread_id — カレントのスレッド ID を返す
    • mysql_unbuffered_query — MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない


はじめに

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 新しくコードを書くときには mysqli や PDO_MySQL を使うべきです。 MySQL API Overview が、MySQL API を選択する際の参考となります。

以下の関数は、MySQL データベースサーバーへのアクセスを可能にします。 MySQL に関するより詳細な情報は、 » http://www.mysql.com/ にあります。

MySQL のドキュメントは、» http://dev.mysql.com/doc/にあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • MySQL (最初の API)
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

以下の関数を利用可能とするには、MySQL サポートを指定して PHP を コンパイルする必要があります。

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。


インストール手順

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

コンパイルするには、単純に --with-mysql[=DIR] 設定オプションを利用してください。ここで、オプションの [DIR] は MySQL がインストールされているディレクトリを表します。

この MySQL 拡張モジュールは MySQL 4.1.0 以降とも互換性がありますが、 それ以降のバージョンが提供する新機能はサポートしていません。 この機能を使用するには、 MySQLi 拡張モジュールを使用してください。

もし mysql 拡張モジュールと mysqli 拡張モジュールを同時にインストールしたい場合は、 衝突を避けるために両方で同じクライアントライブラリを用いる必要があります。

Linux へのインストール

注意: [DIR] は MySQL クライアントライブラリファイル (ヘッダやライブラリファイル) へのパスです。 これらのファイルは » MySQL からダウンロードできます。

ext/mysql のコンパイル時のサポート表
PHP バージョン | デフォルト | 設定オプション: mysqlnd | 設定オプション: libmysqlclient | 変更履歴
4.x.x | libmysqlclient | 利用できません | --without-mysql で無効化 | MySQL はデフォルトで有効になります。MySQL クライアントライブラリも同梱されています。
5.0.x, 5.1.x, 5.2.x | libmysqlclient | 利用できません | --with-mysql=[DIR] | MySQL はデフォルトでは有効にならなくなりました。また、MySQL クライアントライブラリも同梱されなくなりました。
5.3.x | libmysqlclient | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd が使えるようになりました。
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd がデフォルトになりました。

Windows へのインストール

PHP 5.0.x, 5.1.x, 5.2.x

MySQL はもはやデフォルトでは有効となりません。したがって php.ini で php_mysql.dll DLL を有効にしておく必要があります。 また、PHP が MySQL クライアントライブラリにアクセスできなければなりません。 libmysqlclient.dll というファイルが Windows 版の PHP 配布ファイルに含まれており、PHP が MySQL と話すためにはこのファイルが Windows の PATH にある必要があります。そのための方法については、 "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" という FAQ を参照ください。 libmysqlclient.dll を Windows のシステムディレクトリにコピーしても動作しますが (システムディレクトリは、デフォルトでシステムの PATH に含まれています)、お勧めしません。

(php_mysql.dll も含めた) PHP 拡張モジュールを有効にするには、PHP ディレクティブ extension_dir に拡張モジュールの存在する場所を設定するべきです。 Windows へのマニュアルインストール方法 も参照ください。PHP 5 での extension_dir の例は c:\php\ext です。

注意:

Web サーバーの起動時に以下のようなエラーが発生する場合： "Unable to load dynamic library './php_mysql.dll'" これは php_mysql.dll や libmysqlclient.dll がシステムによって見つけられなかったことが原因です。

PHP 5.3.0+

MySQL Native Driver がデフォルトで有効になります。 php_mysql.dll は含まれますが、libmysqlclient.dll はもはや必須ではなく、使われません。

MySQL インストールの注意

警告

この拡張モジュールと recode 拡張モジュールを同時にロードした場合、 PHP のクラッシュと起動に関する問題が発生する可能性があります。 より詳細な情報については、recode 拡張モジュールを参照ください。

注意:

latin（デフォルト）以外の文字セットを必要とする場合、 使用する文字セットのサポートを有効にしてコンパイルした（バンドル版でない） libmysqlclient をインストールする必要があります。


実行時設定

php.ini の設定により動作が変化します。

MySQL 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysql.allow_local_infile | "1" | INI_SYSTEM |
mysql.allow_persistent | "1" | INI_SYSTEM |
mysql.max_persistent | "-1" | INI_SYSTEM |
mysql.max_links | "-1" | INI_SYSTEM |
mysql.trace_mode | "0" | INI_ALL |
mysql.default_port | NULL | INI_ALL |
mysql.default_socket | NULL | INI_ALL |
mysql.default_host | NULL | INI_ALL |
mysql.default_user | NULL | INI_ALL |
mysql.default_password | NULL | INI_ALL |
mysql.connect_timeout | "60" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mysql.allow_local_infile int

PHP 側から、LOAD DATA 文によるローカルファイルへのアクセスを許可する。

mysql.allow_persistent bool

MySQL への 持続的接続 を可能にするかどうか。

mysql.max_persistent int

プロセス毎の持続的 MySQL 接続の最大数。

mysql.max_links int

持続的接続を含むプロセス毎の MySQL 接続の最大数。

mysql.trace_mode bool

トレースモード。mysql.trace_mode が有効の場合、 テーブル/インデックスのスキャン時の警告・結果セットの未開放・SQL エラー などが画面に表示されます（PHP 4.3.0 以降で使用可能です）。

mysql.default_port string

他のポートが指定されない場合、データベースサーバー接続時に使用される デフォルトの TCP ポート番号。デフォルトが指定されない場合は、 環境変数 MYSQL_TCP_PORT・ /etc/services の mysql-tcpエントリ・コンパイル時の MYSQL_PORT 定数の順番でポートが取得されます。 Win32 では、MYSQL_PORT 定数のみが使用されます。

mysql.default_socket string

他にソケット名が指定されない場合、ローカルなデータベースサーバーに 接続する時のデフォルトのソケット名。

mysql.default_host string

他のサーバー名が指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのサーバー名。 SQL セーフモード では適用されません。

mysql.default_user string

他のユーザー名が指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのユーザー名。 SQL セーフモード では適用されません。

mysql.default_password string

他のパスワードが指定されない場合に、データベースサーバーへの接続時に 使用されるデフォルトのパスワード。 SQL セーフモード では適用されません。

mysql.connect_timeout int

接続の有効時間(単位:秒)。Linux では、この有効時間はサーバーからの 最初の応答の待ち時間としても使用されます。


リソース型

MySQL モジュールでは、2 種類のリソース型が使用されています。 最初のリソースはデータベース接続のリンク ID で、2 番目のリソースは クエリ結果を保持するリソースです。


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

ext/mysql 拡張モジュールの変更履歴

ext/mysql 拡張モジュールの変更履歴をまとめました。

ext/mysql の全体的な変更点

ext/mysql 拡張モジュールの全体的な変更点を、以下にまとめます。

バージョン | 説明
7.0.0 | この拡張モジュールは PHP 本体から削除されました。詳細は どの API を使うか を参照ください。

既存の関数の変更点

ext/mysql の関数に対する変更点を、以下にまとめます。

Version Function 説明


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

mysql_connect() や mysql_pconnect() で追加のクライアントフラグを 指定することができます。以下の定数が定義されています。

MySQL クライアント定数
定数 | 説明
MYSQL_CLIENT_COMPRESS | 圧縮プロトコルを利用します。
MYSQL_CLIENT_IGNORE_SPACE | 関数名の後のスペースを許可します。
MYSQL_CLIENT_INTERACTIVE | interactive_timeout で指定された秒数（wait_timeout のかわり） の無通信が続くまで接続を閉じません。
MYSQL_CLIENT_SSL | SSL による暗号化を使用します。このフラグは、バージョン 4.x 以降の MySQL クライアントライブラリを利用している場合にのみ有効です。 PHP 4 や、Windows 版の PHP 5 にバンドルされているのは、バージョン 3.23.x のライブラリです。

mysql_fetch_array() 関数は、結果の配列の形式を 指定するための定数を使用します。以下の定数が定義されています。

MySQL フェッチ定数
定数 | 説明
MYSQL_ASSOC | カラムは、フィールド名を添字とする配列形式で返されます。
MYSQL_BOTH | カラムは、数値の添字とフィールド名の添字のどちらでもアクセスできる 配列形式で返されます。
MYSQL_NUM | カラムは、数値の添字を持つ配列形式で返されます。添字は 0 からはじまり、 結果の最初のフィールドです。


  • ≪ 定義済み定数
  • MySQL 拡張モジュールの概要を示す例 ≫
  • PHP Manual
  • MySQL (最初の API)
  • 例

例

目次

  • MySQL 拡張モジュールの概要を示す例


MySQL 拡張モジュールの概要を示す例

以下は、MySQL データベースに接続し、クエリを実行し、結果レコードを 出力、接続を切断する例です。

例1 MySQL 拡張モジュールに関する例

<?php
// データベースに接続し、選択する
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
or die('Could not connect: ' . mysql_error());
echo 'Connected successfully';
mysql_select_db('my_database') or die('Could not select database');

// SQL クエリを実行する
$query = 'SELECT * FROM my_table';
$result = mysql_query($query) or die('Query failed: ' . mysql_error());

// HTML に結果を出力する
echo "<table>\n";
while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
echo "\t<tr>\n";
foreach ($line as $col_value) {
echo "\t\t<td>$col_value</td>\n";
}
echo "\t</tr>\n";
}
echo "</table>\n";

// 結果セットを開放する
mysql_free_result($result);

// 接続を閉じる
mysql_close($link);
?>


MySQL 関数

注意

注意:

ほとんどの MySQL 関数は、link_identifier を 最後のパラメータとしてオプションで受け付けます。これを指定しなかった場合、 直近にオープンされた接続が使用されます。もし直近の接続が存在しない場合、 php.ini のデフォルトパラメータを使用して接続を確立しようとします。 この試行にも失敗した場合、関数は false を返します。

目次

  • mysql_affected_rows — 一番最近の操作で変更された行の数を得る
  • mysql_client_encoding — 文字セット名を返す
  • mysql_close — MySQL 接続を閉じる
  • mysql_connect — MySQL サーバーへの接続をオープンする
  • mysql_create_db — MySQL データベースを作成する
  • mysql_data_seek — 内部的な結果ポインタを移動する
  • mysql_db_name — mysql_list_dbs のコール結果からデータベース名を取得する
  • mysql_db_query — データベースを選択し、そこでクエリーを実行する
  • mysql_drop_db — MySQLデータベースを破棄(削除)する
  • mysql_errno — 直近の MySQL 処理からエラーメッセージのエラー番号を返す
  • mysql_error — 直近に実行された MySQL 操作のエラーメッセージを返す
  • mysql_escape_string — mysql_query で使用するために文字列をエスケープする
  • mysql_fetch_array — 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc — 連想配列として結果の行を取得する
  • mysql_fetch_field — 結果からカラム情報を取得し、オブジェクトとして返す
  • mysql_fetch_lengths — 結果における各出力の長さを得る
  • mysql_fetch_object — 結果の行をオブジェクトとして取得する
  • mysql_fetch_row — 結果を添字配列として取得する
  • mysql_field_flags — 結果において指定したフィールドのフラグを取得する
  • mysql_field_len — 指定したフィールドの長さを返す
  • mysql_field_name — 結果において指定したフィールド名を取得する
  • mysql_field_seek — 結果ポインタを指定したフィールドオフセットにセットする
  • mysql_field_table — 指定したフィールドが含まれるテーブルの名前を取得する
  • mysql_field_type — 結果において指定したフィールドの型を取得する
  • mysql_free_result — 結果保持用メモリを開放する
  • mysql_get_client_info — MySQL クライアント情報を取得する
  • mysql_get_host_info — MySQL ホスト情報を取得する
  • mysql_get_proto_info — MySQL プロトコル情報を取得する
  • mysql_get_server_info — MySQL サーバー情報を取得する
  • mysql_info — 直近のクエリについての情報を得る
  • mysql_insert_id — 直近のクエリで生成された ID を得る
  • mysql_list_dbs — MySQL サーバー上で利用可能なデータベースのリストを得る
  • mysql_list_fields — MySQL テーブルのフィールドのリストを得る
  • mysql_list_processes — MySQL プロセスのリストを得る
  • mysql_list_tables — MySQL データベース上のテーブルのリストを得る
  • mysql_num_fields — 結果におけるフィールドの数を得る
  • mysql_num_rows — 結果における行の数を得る
  • mysql_pconnect — MySQL サーバーへの持続的な接続をオープンする
  • mysql_ping — サーバーとの接続状況を調べ、接続されていない場合は再接続する
  • mysql_query — MySQL クエリを送信する
  • mysql_real_escape_string — SQL 文中で用いる文字列の特殊文字をエスケープする
  • mysql_result — 結果データを得る
  • mysql_select_db — MySQL データベースを選択する
  • mysql_set_charset — クライアントの文字セットを設定する
  • mysql_stat — 現在のシステムの状態を取得する
  • mysql_tablename — フィールドのテーブル名を得る
  • mysql_thread_id — カレントのスレッド ID を返す
  • mysql_unbuffered_query — MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない


一番最近の操作で変更された行の数を得る

  • ≪ MySQL 関数
  • mysql_client_encoding ≫
  • PHP Manual
  • MySQL 関数
  • 一番最近の操作で変更された行の数を得る

mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — 一番最近の操作で変更された行の数を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_affected_rows()
  • PDOStatement::rowCount()

説明

mysql_affected_rows(resource $link_identifier = NULL): int

link_identifier と関連付けられた直近の INSERT、UPDATE、REPLACE、DELETE クエリによって変更された行の数を取得します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に変更された行の数を、直近のクエリが失敗した場合に -1 を返します。

直近のクエリが WHERE 句を含まない DELETE だった場合、テーブルから すべてのレコードが削除されますが、MySQL 4.1.2 以前のバージョンでは この関数はゼロを返します。

UPDATE を使用する場合、MySQL では新旧の値が同じときには更新処理を行いません。 このことから、必ずしも mysql_affected_rows() の返す値が マッチする行の数と一致するとは限りません。返す値は実際に更新処理が行われた 行の数です。

REPLACE ステートメントは、まず最初に同じ主キーのレコードを削除した後に 新しいレコードを挿入します。この関数は、削除された行の数と 挿入された行の数を足したものを返します。

"INSERT ... ON DUPLICATE KEY UPDATE" クエリの場合の戻り値は、 新しい行を追加した場合が 1 で既存の行を更新した場合が 2 となります。

例

例1 mysql_affected_rows() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

/* これは、削除されたレコードの正しい数をかえずはず */
mysql_query('DELETE FROM mytable WHERE id < 10');
printf("Records deleted: %d\n", mysql_affected_rows());

/* 決して真にはならない where 条件なので、結果は 0 となるはず */
mysql_query('DELETE FROM mytable WHERE 0');
printf("Records deleted: %d\n", mysql_affected_rows());
?>

上の例の出力は、 たとえば以下のようになります。

Records deleted: 10
Records deleted: 0

例2 トランザクションを利用した mysql_affected_rows() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

/* レコードの更新 */
mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
printf ("Updated records: %d\n", mysql_affected_rows());
mysql_query("COMMIT");
?>

上の例の出力は、 たとえば以下のようになります。

Updated Records: 10

注意

注意: トランザクション

トランザクションを使用する場合には、コミット後ではなく INSERT, UPDATE, DELETE クエリの後に mysql_affected_rows() をコールする必要があります。

注意: SELECT ステートメント

SELECT から返される行の数を得る際には、 mysql_num_rows() が利用できます。

注意: 外部キーによる連鎖

mysql_affected_rows() は、外部キー制約の ON DELETE CASCADE や ON UPDATE CASCADE で暗黙のうちに変更された行については数えません。

参考

  • mysql_num_rows() - 結果における行の数を得る
  • mysql_info() - 直近のクエリについての情報を得る


文字セット名を返す

  • ≪ mysql_affected_rows
  • mysql_close ≫
  • PHP Manual
  • MySQL 関数
  • 文字セット名を返す

mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — 文字セット名を返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_character_set_name()

説明

mysql_client_encoding(resource $link_identifier = NULL): string

MySQL の character_set 変数の値を取得します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

カレントの接続から、デフォルトの文字セット名を返します。

例

例1 mysql_client_encoding() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$charset = mysql_client_encoding($link);

echo "カレントの文字セットは: $charset\n";
?>

上の例の出力は、 たとえば以下のようになります。

カレントの文字セットは: latin1

参考

  • mysql_set_charset() - クライアントの文字セットを設定する
  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする


MySQL 接続を閉じる

  • ≪ mysql_client_encoding
  • mysql_connect ≫
  • PHP Manual
  • MySQL 関数
  • MySQL 接続を閉じる

mysql_close

(PHP 4, PHP 5)

mysql_close — MySQL 接続を閉じる

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_close()
  • PDO: PDO オブジェクトへの null の代入

説明

mysql_close(resource $link_identifier = NULL): bool

mysql_close() は、指定した link_identifier が指す MySQL データベースへの非持続的リンクを閉じます。 link_identifier が指定されない場合、最後に オープンされたリンクが使用されます。

持続的でない MySQL 接続や結果セットは、PHP スクリプトの実行が終了する時点で自動的に破棄されます。 そのため、オープンした接続をクローズしたり結果セットを開放したりすることは必須ではありませんが、 そうしておくことを推奨します。 その時点ですぐに PHP や MySQL にリソースを返せ、パフォーマンスの向上につながるからです。 関連する除法は リソースの開放を参照ください。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。接続が見つからない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_close() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);
?>

上の例の出力は以下となります。

接続に成功しました

注意

注意:

mysql_close() は、mysql_pconnect() により生成された持続的リンクを閉じません。 詳細な情報は、マニュアルの 持続的データベース接続を参照ください。

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_free_result() - 結果保持用メモリを開放する


MySQL サーバーへの接続をオープンする

  • ≪ mysql_close
  • mysql_create_db ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバーへの接続をオープンする

mysql_connect

(PHP 4, PHP 5)

mysql_connect — MySQL サーバーへの接続をオープンする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_connect()
  • PDO::__construct()

説明

mysql_connect(
string $server = ini_get("mysql.default_host"),
string $username = ini_get("mysql.default_user"),
string $password = ini_get("mysql.default_password"),
bool $new_link = false,
int $client_flags = 0
): resource|false

MySQL サーバーへの接続をオープンあるいは再利用します。

パラメータ

server

MySQL サーバー。"hostname:port" のようにポート番号を 指定することが可能で、localhost では ":/path/to/socket" のようにソケットへのパスを指定することも可能です。

PHP ディレクティブ mysql.default_host が指定されない場合（デフォルト）、 'localhost:3306' が使用されます。 SQL セーフモード の場合はこのパラメータは無視され、常に 'localhost:3306' が用いられます。

username

ユーザー名。デフォルト値は mysql.default_user で定義されている値です。SQL セーフモード の場合はこのパラメータは無視され、 サーバープロセスの所有ユーザー名が用いられます。

password

パスワード。デフォルト値は mysql.default_password で定義されている値です。SQL セーフモード の場合はこのパラメータは無視され、 空のパスワードが用いられます。

new_link

同じ引数で 2 回 mysql_connect() をコールした場合、 2 回目は新規のリンクが確立されるのではなく、代わりにすでにオープンされた リンクのリンク ID が返されます。 パラメータ new_link はこの動作を変更し、既に mysql_connect() が同じパラメータでコールされて いる場合でも常に新規のリンクがオープンされるようにします。 SQL セーフモード の場合はこのパラメータは無視されます。

client_flags

パラメータ client_flags は、 以下の定数の組み合わせです： 128 (LOAD DATA LOCAL の処理を有効にする)、 MYSQL_CLIENT_SSL、 MYSQL_CLIENT_COMPRESS、 MYSQL_CLIENT_IGNORE_SPACE または MYSQL_CLIENT_INTERACTIVE。 詳細な情報については MySQL クライアント定数 を参照ください。 SQL セーフモード の場合はこのパラメータは無視されます。

戻り値

成功した場合に MySQL リンク ID を、失敗した場合に false を返します。

例

例1 mysql_connect() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);
?>

例2 mysql_connect() で hostname:port 構文を使用する例

<?php
// example.com のポート 3307 に接続します
$link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);

// localhost のポート 3307 に接続します
$link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);
?>

例3 mysql_connect() で ":/path/to/socket" 構文を使用する例

<?php
// localhost のソケット（例: /tmp/mysql.sock）に接続します

// 方法 1: localhost を省略する
$link = mysql_connect(':/tmp/mysql', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);

// 方法 2: localhost を指定する
$link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
echo '接続に成功しました';
mysql_close($link);
?>

注意

注意:

サーバー名に "localhost" や "localhost:port" を指定した場合、MySQL クライアントライブラリはそれをオーバーライドし、 ローカルソケット（Windows では名前つきパイプ）に接続しようとします。 TCP/IP を用いたい場合は、"localhost" のかわりに "127.0.0.1" を用いてください。もし MySQL クライアントライブラリが 間違ったローカルソケットへ接続しようとしている場合、これを修正するには php.ini の mysql.default_host に正しいパスを指定したうえでサーバー名を空白にしておくべきです。

注意:

サーバーへのリンクは、mysql_close() のコールにより 明示的に閉じられない限り、スクリプトの実行終了と同時に閉じられます。

注意:

エラー "Can't create TCP/IP socket (10106)" が発生するのは、たいていは variables_order 設定ディレクティブに E が含まれていない場合です。 Windows では、これが含まれていなければ SYSTEMROOT 環境変数が使用できず、PHP が Winsock の読み込みに失敗します。

参考

  • mysql_pconnect() - MySQL サーバーへの持続的な接続をオープンする
  • mysql_close() - MySQL 接続を閉じる


MySQL データベースを作成する

  • ≪ mysql_connect
  • mysql_data_seek ≫
  • PHP Manual
  • MySQL 関数
  • MySQL データベースを作成する

mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — MySQL データベースを作成する

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_query()
  • PDO::query()

説明

mysql_create_db(string $database_name, resource $link_identifier = NULL): bool

mysql_create_db() は、指定したリンク ID が指す サーバー上に新規のデータベースを作成します。

パラメータ

database_name

作成されるデータベースの名前です。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_create_db() の別の例

mysql_create_db() は廃止予定です。代わりに mysql_query() を用いて CREATE DATABASE ステートメントを発行する方法が 推奨されます。

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できません: ' . mysql_error());
}

$sql = 'CREATE DATABASE my_db';
if (mysql_query($sql, $link)) {
echo "データベース my_db の作成に成功しました\n";
} else {
echo 'データベースの作成に失敗しました: ' . mysql_error() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

データベース my_db の作成に成功しました

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_createdb()

注意:

MySQL 4.x クライアントライブラリを用いて MySQL 拡張モジュールを ビルドした場合、この関数は利用できません。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_select_db() - MySQL データベースを選択する


内部的な結果ポインタを移動する

  • ≪ mysql_create_db
  • mysql_db_name ≫
  • PHP Manual
  • MySQL 関数
  • 内部的な結果ポインタを移動する

mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — 内部的な結果ポインタを移動する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_data_seek()
  • PDO::FETCH_ORI_ABS

説明

mysql_data_seek(resource $result, int $row_number): bool

mysql_data_seek() は、指定した結果 ID （result_identifier）が指す MySQL 結果の内部ポインタが指定した行番号 （row_number）を指すように移動します。 この後、たとえば mysql_fetch_assoc() のような MySQL のフェッチ関数をコールした場合には、 ここで指定した行の内容が返されます。

row_number は 0 から始まります。 row_number は 0 から mysql_num_rows() - 1 までの範囲にあるべきです。 しかし、もし結果セットが空（mysql_num_rows() == 0） の場合、0 へのシークは E_WARNING を発生して失敗し、mysql_data_seek() は false を返します。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

row_number

新しく結果ポインタを設定したい行番号です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_data_seek() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('接続できませんでした: ' . mysql_error());
}
$db_selected = mysql_select_db('sample_db');
if (!$db_selected) {
die('データベースを選択できませんでした: ' . mysql_error());
}
$query = 'SELECT last_name, first_name FROM friends';
$result = mysql_query($query);
if (!$result) {
die('クエリは失敗しました: ' . mysql_error());
}
/* 行を逆順で取得する */
for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
if (!mysql_data_seek($result, $i)) {
echo "行 $i をシークできません: " . mysql_error() . "\n";
continue;
}

if (!($row = mysql_fetch_assoc($result))) {
continue;
}

echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
}

mysql_free_result($result);
?>

注意

注意:

mysql_data_seek() は、
mysql_query() との組み合わせでのみ利用可能です。
mysql_unbuffered_query() と組み合わせることはできません。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_num_rows() - 結果における行の数を得る
  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_object() - 結果の行をオブジェクトとして取得する


mysql_list_dbs のコール結果からデータベース名を取得する

  • ≪ mysql_data_seek
  • mysql_db_query ≫
  • PHP Manual
  • MySQL 関数
  • mysql_list_dbs のコール結果からデータベース名を取得する

mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — mysql_list_dbs() のコール結果からデータベース名を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • クエリー: SELECT DATABASE()

説明

mysql_db_name(resource $result, int $row, mixed $field = NULL): string

mysql_list_dbs() をコールした結果からデータベース名を取得します。

パラメータ

result

mysql_list_dbs() をコールして 得られた結果ポインタ。

row

結果セット内のインデックス。

field

フィールド名。

戻り値

成功した場合にデータベース名を、失敗した場合に false を返します。 false が返された場合、エラーの発生源を特定するには mysql_error() を使用してください。

例

例1 mysql_db_name() の例

<?php
error_reporting(E_ALL);

$link = mysql_connect('dbhost', 'username', 'password');
$db_list = mysql_list_dbs($link);

$i = 0;
$cnt = mysql_num_rows($db_list);
while ($i < $cnt) {
echo mysql_db_name($db_list, $i) . "\n";
$i++;
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_dbname()

参考

  • mysql_list_dbs() - MySQL サーバー上で利用可能なデータベースのリストを得る
  • mysql_tablename() - フィールドのテーブル名を得る


データベースを選択し、そこでクエリーを実行する

  • ≪ mysql_db_name
  • mysql_drop_db ≫
  • PHP Manual
  • MySQL 関数
  • データベースを選択し、そこでクエリーを実行する

mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — データベースを選択し、そこでクエリーを実行する

警告

この関数は PHP 5.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_select_db() してからクエリーを実行
  • PDO::__construct()

説明

mysql_db_query(string $database, string $query, resource $link_identifier = NULL): resource|bool

mysql_db_query() はデータベースを選択し、 そこでクエリーを実行します。

パラメータ

database

選択するデータベース名。

query

MySQL クエリー。

クエリ内のデータは 適切にエスケープ する必要があります。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

クエリーの結果を指す MySQL 結果リソースを正の値で返します。 エラー時には false を返します。また、 INSERT/UPDATE/DELETE クエリーの場合には true または false を返し、これらはそれぞれ クエリーが 成功した / 失敗した ことを示します。

例

例1 mysql_db_query() の別の例

<?php

if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
echo 'Could not connect to mysql';
exit;
}

if (!mysql_select_db('mysql_dbname', $link)) {
echo 'Could not select database';
exit;
}

$sql = 'SELECT foo FROM bar WHERE id = 42';
$result = mysql_query($sql, $link);

if (!$result) {
echo "DB Error, could not query the database\n";
echo 'MySQL Error: ' . mysql_error();
exit;
}

while ($row = mysql_fetch_assoc($result)) {
echo $row['foo'];
}

mysql_free_result($result);

?>

注意

注意:

この関数の終了後、直前に選択されていたデータベースに自動的に戻ることは ないということに注意してください。 言い換えれば、一時的に別のデータベース上でクエリーを 実行するという目的でこの関数を利用することはできないということです。 もしそのような場合は、もとのデータベースに改めて接続しなおす必要があります。 この関数のかわりに、SQL クエリーの中で database.table 構文を用いたり mysql_select_db() を利用したりすることが 強く推奨されています。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_select_db() - MySQL データベースを選択する


MySQLデータベースを破棄(削除)する

  • ≪ mysql_db_query
  • mysql_errno ≫
  • PHP Manual
  • MySQL 関数
  • MySQLデータベースを破棄(削除)する

mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — MySQLデータベースを破棄(削除)する

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • DROP DATABASE クエリーを実行

説明

mysql_drop_db(string $database_name, resource $link_identifier = NULL): bool

mysql_drop_db() は、指定した link_identifier が指す データベース全体をサーバーから破棄(削除)しようとします。 この関数は非推奨です。かわりに、 mysql_query() を用いて DROP DATABASE 文を発行する方法が推奨されます。

パラメータ

database_name

削除するデータベースの名前。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_drop_db() の別の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}

$sql = 'DROP DATABASE my_db';
if (mysql_query($sql, $link)) {
echo "Database my_db was successfully dropped\n";
} else {
echo 'Error dropping database: ' . mysql_error() . "\n";
}
?>

注意

警告

MySQL 4.x のクライアントライブラリを用いて MySQL 拡張モジュールを ビルドした場合、この関数は利用できません。

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_dropdb()

参考

  • mysql_query() - MySQL クエリを送信する


直近の MySQL 処理からエラーメッセージのエラー番号を返す

  • ≪ mysql_drop_db
  • mysql_error ≫
  • PHP Manual
  • MySQL 関数
  • 直近の MySQL 処理からエラーメッセージのエラー番号を返す

mysql_errno

(PHP 4, PHP 5)

mysql_errno — 直近の MySQL 処理からエラーメッセージのエラー番号を返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_errno()
  • PDO::errorCode()

説明

mysql_errno(resource $link_identifier = NULL): int

直近の MySQL 関数で発生したエラーの番号を返します。

MySQL データベースバックエンドから返ってくるエラーは、 警告を発生しません。代わりに mysql_errno() を用いて エラー番号を取得してください。この関数が返すのは、直近に実行された MySQL 関数（mysql_error() と mysql_errno() は除く）のエラーコードだけであることに 注意しましょう。この関数を利用するなら、別の MySQL 関数をコールする前に 値を調べることを忘れないようにしましょう。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

直近の MySQL 関数からのエラー番号を返します。エラーが発生していない 場合は、0 (ゼロ)を返します。

例

例1 mysql_errno() の例

<?php
$link = mysql_connect("localhost", "mysql_user", "mysql_password");

if (!mysql_select_db("nonexistentdb", $link)) {
echo mysql_errno($link) . ": " . mysql_error($link). "\n";
}

mysql_select_db("kossu", $link);
if (!mysql_query("SELECT * FROM nonexistenttable", $link)) {
echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

1049: Unknown database 'nonexistentdb'
1146: Table 'kossu.nonexistenttable' doesn't exist

参考

  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す
  • » MySQL エラーコード


直近に実行された MySQL 操作のエラーメッセージを返す

  • ≪ mysql_errno
  • mysql_escape_string ≫
  • PHP Manual
  • MySQL 関数
  • 直近に実行された MySQL 操作のエラーメッセージを返す

mysql_error

(PHP 4, PHP 5)

mysql_error — 直近に実行された MySQL 操作のエラーメッセージを返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_error()
  • PDO::errorInfo()

説明

mysql_error(resource $link_identifier = NULL): string

直近の MySQL 関数からのエラー文字列を返します。 MySQL データベースバックエンドから返ってくるエラーは、 警告を発生しません。代わりに mysql_error() を用いて エラー文字列を取得してください。この関数が返すのは、直近に実行された MySQL 関数（mysql_error() と mysql_errno() は除く）のエラー文字列だけであることに 注意しましょう。この関数を利用するなら、別の MySQL 関数をコールする前に 値を調べることを忘れないようにしましょう。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

直近の MySQL 関数からのエラー文字列を返します。エラーが発生していない 場合には、'' (空文字列) を返します。

例

例1 mysql_error() の例

<?php
$link = mysql_connect("localhost", "mysql_user", "mysql_password");

mysql_select_db("nonexistentdb", $link);
echo mysql_errno($link) . ": " . mysql_error($link). "\n";

mysql_select_db("kossu", $link);
mysql_query("SELECT * FROM nonexistenttable", $link);
echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1049: Unknown database 'nonexistentdb'
1146: Table 'kossu.nonexistenttable' doesn't exist

参考

  • mysql_errno() - 直近の MySQL 処理からエラーメッセージのエラー番号を返す
  • » MySQL エラーコード


mysql_query で使用するために文字列をエスケープする

  • ≪ mysql_error
  • mysql_fetch_array ≫
  • PHP Manual
  • MySQL 関数
  • mysql_query で使用するために文字列をエスケープする

mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — mysql_query で使用するために文字列をエスケープする

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_escape_string()
  • PDO::quote()

説明

mysql_escape_string(string $unescaped_string): string

この関数は、mysql_query() で指定可能なように unescaped_string をエスケープします。 この関数は非推奨です。

この関数は mysql_real_escape_string() とほぼ同じです。ただ mysql_real_escape_string() はコネクションハンドラを用い、 カレントの文字セットを考慮したエスケープを行うという点が違います。 mysql_escape_string() はコネクションに関する引数を 持たず、カレントの文字セット設定を考慮しません。

パラメータ

unescaped_string

エスケープされる文字列。

戻り値

エスケープされた文字列を返します。

例

例1 mysql_escape_string() の例

<?php
$item = "Zak's Laptop";
$escaped_item = mysql_escape_string($item);
printf("Escaped string: %s\n", $escaped_item);
?>

上の例の出力は以下となります。

Escaped string: Zak\'s Laptop

注意

注意:

mysql_escape_string() は、 % および _ をエスケープしません。

参考

  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする


連想配列、添字配列、またはその両方として結果の行を取得する

  • ≪ mysql_escape_string
  • mysql_fetch_assoc ≫
  • PHP Manual
  • MySQL 関数
  • 連想配列、添字配列、またはその両方として結果の行を取得する

mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — 連想配列、添字配列、またはその両方として結果の行を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_array()
  • PDOStatement::fetch()

説明

mysql_fetch_array(resource $result, int $result_type = MYSQL_BOTH): array

取得した行に対応する配列を返し、内部のデータポインタを前に進めます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

result_type

取得する配列の形式です。以下の定数値をとります。: MYSQL_ASSOC, MYSQL_NUM, そして MYSQL_BOTH

戻り値

取得した行をあらわす文字列の配列を返します。もし行が存在しない場合は false を返します。返される配列の形式は、result_type がどのように指定されているかによります。MYSQL_BOTH（デフォルト） を利用すると、連想添字と数値添字を共に持つ配列を取得します。 MYSQL_ASSOC を利用すると（ mysql_fetch_assoc() の動作と同様に）連想添字のみが取得され、 MYSQL_NUM を利用すると （mysql_fetch_row() の動作と同様に）数値添字のみが 取得されます。

結果の中で同じフィールド名のカラムが 2 つ以上ある場合、 最後のカラムが優先されます。 同名の他のカラムにアクセスするには、そのカラムの数値インデックスを 使うかまたはカラムの別名を定義する必要があります。 カラムの別名を定義した場合は、本来の列名でそのカラムにアクセスすることは できません。

例

例1 重複した列名に対して別名を定義する問い合わせ

SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

例2 mysql_fetch_array() を MYSQL_NUM とともに利用する

<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
printf("ID: %s Name: %s", $row[0], $row[1]);
}

mysql_free_result($result);
?>

例3 mysql_fetch_array() を MYSQL_ASSOC とともに利用する

<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
printf("ID: %s Name: %s", $row["id"], $row["name"]);
}

mysql_free_result($result);
?>

例4 mysql_fetch_array() を MYSQL_BOTH とともに利用する

<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
printf ("ID: %s Name: %s", $row[0], $row["name"]);
}

mysql_free_result($result);
?>

注意

注意: パフォーマンス

特筆すべき点として、mysql_fetch_array() が 著しい付加価値があるにもかかわらず、 mysql_fetch_row()より それほど遅くはないということが言えます。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_query() - MySQL クエリを送信する


連想配列として結果の行を取得する

  • ≪ mysql_fetch_array
  • mysql_fetch_field ≫
  • PHP Manual
  • MySQL 関数
  • 連想配列として結果の行を取得する

mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — 連想配列として結果の行を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_assoc()
  • PDOStatement::fetch() の mode に PDO::FETCH_ASSOC を指定する

説明

mysql_fetch_assoc(resource $result): array

取得した行に対応する連想配列を返し、内部のデータポインタを前に進めます。 mysql_fetch_assoc() は、 mysql_fetch_array() の 2 番目のパラメータを MYSQL_ASSOC に指定してコールするのと同じ働きをします。つまり、 連想配列のみを返します。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

戻り値

取得した行に対応する文字列の連想配列を返します。行がもうない場合には false を返します。

結果の複数のカラムが同じフィールド名を有している場合、最後のカラ ムが優先されます。同じ名前を有する他のカラムにアクセスするには、 mysql_fetch_row()を使用して数値添字を返すか、 エイリアス名を追加する必要があります。エイリアスの説明については、 mysql_fetch_array()の例を参照ください。

例

例1 mysql_fetch_assoc() のいろいろな例

<?php

$conn = mysql_connect("localhost", "mysql_user", "mysql_password");

if (!$conn) {
echo "Unable to connect to DB: " . mysql_error();
exit;
}

if (!mysql_select_db("mydbname")) {
echo "Unable to select mydbname: " . mysql_error();
exit;
}

$sql = "SELECT id as userid, fullname, userstatus
FROM sometable
WHERE userstatus = 1";

$result = mysql_query($sql);

if (!$result) {
echo "Could not successfully run query ($sql) from DB: " . mysql_error();
exit;
}

if (mysql_num_rows($result) == 0) {
echo "No rows found, nothing to print so am exiting";
exit;
}

// データ行が存在する間、それを $row に連想配列形式でセットする
// 注: 結果が 1 行であることがわかっているのなら、ループを利用しなくてもよい
// 注: ループ内で extract($row); を実行すれば、
// $userid, $fullname, そして $userstatus を利用できる
while ($row = mysql_fetch_assoc($result)) {
echo $row["userid"];
echo $row["fullname"];
echo $row["userstatus"];
}

mysql_free_result($result);

?>

注意

注意: パフォーマンス

特筆すべき点として、mysql_fetch_assoc() が 著しい付加価値があるにもかかわらず、 mysql_fetch_row()より それほど遅くはないということが言えます。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_query() - MySQL クエリを送信する
  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す


結果からカラム情報を取得し、オブジェクトとして返す

  • ≪ mysql_fetch_assoc
  • mysql_fetch_lengths ≫
  • PHP Manual
  • MySQL 関数
  • 結果からカラム情報を取得し、オブジェクトとして返す

mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — 結果からカラム情報を取得し、オブジェクトとして返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field()
  • PDOStatement::getColumnMeta()

説明

mysql_fetch_field(resource $result, int $field_offset = 0): object

フィールド情報を含むオブジェクトを返します。特定のクエリー結果の中の フィールドに関する情報を得るために使用可能です。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数字で表したフィールドの位置です。もし指定されなければ、 まだこの関数で情報を取得していないフィールドのうち最初のものが 選択されます。field_offset は、 0 からはじまります。

戻り値

フィールド情報を含むobjectを返します。オブジェクトの プロパティは次のとおりです。

  • name - カラム名
  • table - カラムが属しているテーブルの名前。エイリアスを定義している場合はエイリアスの名前
  • max_length - カラムの最大長
  • not_null - カラムが null 値をとることができない場合 1
  • primary_key - カラムが主キーであれば 1
  • unique_key - カラムがユニークキーであれば 1
  • multiple_key - カラムが非ユニークキーであれば 1
  • numeric - カラムが数値(numeric)であれば 1
  • blob - カラムがBLOBであれば 1
  • type - カラムの型
  • unsigned - カラムが符号無し(unsigned)であれば 1
  • zerofill - カラムがゼロで埋められている(zero-filled)場合に 1

例

例1 mysql_fetch_field() の例

<?php
$conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$conn) {
die('Could not connect: ' . mysql_error());
}
mysql_select_db('database');
$result = mysql_query('select * from table');
if (!$result) {
die('Query failed: ' . mysql_error());
}
/* カラムのメタデータを取得する */
$i = 0;
while ($i < mysql_num_fields($result)) {
echo "Information for column $i:<br />\n";
$meta = mysql_fetch_field($result, $i);
if (!$meta) {
echo "No information available<br />\n";
}
echo "<pre>
blob: $meta->blob
max_length: $meta->max_length
multiple_key: $meta->multiple_key
name: $meta->name
not_null: $meta->not_null
numeric: $meta->numeric
primary_key: $meta->primary_key
table: $meta->table
type: $meta->type
unique_key: $meta->unique_key
unsigned: $meta->unsigned
zerofill: $meta->zerofill
</pre>";
$i++;
}
mysql_free_result($result);
?>

注意

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意:

SQL クエリでフィールド名やテーブル名のエイリアスを設定している場合は、 エイリアスを返します。本来の名前を取得するには、 mysqli_result::fetch_field() を使いましょう。

参考

  • mysql_field_seek() - 結果ポインタを指定したフィールドオフセットにセットする


結果における各出力の長さを得る

  • ≪ mysql_fetch_field
  • mysql_fetch_object ≫
  • PHP Manual
  • MySQL 関数
  • 結果における各出力の長さを得る

mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — 結果における各出力の長さを得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_lengths()
  • PDOStatement::getColumnMeta()

説明

mysql_fetch_lengths(resource $result): array|false

MySQL により一番最近に取得された行における各フィールドの長さを 格納した配列を返します。

mysql_fetch_lengths()は、
mysql_fetch_row(),
mysql_fetch_assoc(),
mysql_fetch_array(), そして
mysql_fetch_object() により一番最近に返された
各結果カラムの長さを格納した配列を返します。この配列のオフセットは
0 から始まります。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

戻り値

成功した場合に長さの配列（array）を、 失敗した場合に false を返します。

例

例1 mysql_fetch_lengths() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}
$row = mysql_fetch_assoc($result);
$lengths = mysql_fetch_lengths($result);

print_r($row);
print_r($lengths);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [id] => 42
    [email] => user@example.com
)
Array
(
    [0] => 2
    [1] => 16
)

参考

  • mysql_field_len() - 指定したフィールドの長さを返す
  • mysql_fetch_row() - 結果を添字配列として取得する
  • strlen() - 文字列の長さを得る


結果の行をオブジェクトとして取得する

  • ≪ mysql_fetch_lengths
  • mysql_fetch_row ≫
  • PHP Manual
  • MySQL 関数
  • 結果の行をオブジェクトとして取得する

mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — 結果の行をオブジェクトとして取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_object()
  • PDOStatement::fetch() の mode に PDO::FETCH_OBJ を指定する

説明

mysql_fetch_object(resource $result, string $class_name = ?, array $params = ?): object

取得された行を表すプロパティを有するオブジェクトを返し、 内部のデータポインタを前に進めます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

class_name

インスタンス化し、プロパティを設定して返すクラスの名前。 指定しなかった場合は stdClass オブジェクトが返されます。

params

class_name オブジェクトのコンストラクタに渡す オプションのパラメータの配列。

戻り値

取得された行を表す文字列プロパティを有するオブジェクト(object)を返します。 もう行が残っていない場合は、false を返します。

例

例1 mysql_fetch_object() の例

<?php
mysql_connect("hostname", "user", "password");
mysql_select_db("mydb");
$result = mysql_query("select * from mytable");
while ($row = mysql_fetch_object($result)) {
echo $row->user_id;
echo $row->fullname;
}
mysql_free_result($result);
?>

例2 mysql_fetch_object() の例

<?php
class foo {
public $name;
}

mysql_connect("hostname", "user", "password");
mysql_select_db("mydb");

$result = mysql_query("select name from mytable limit 1");
$obj = mysql_fetch_object($result, 'foo');
var_dump($obj);

注意

注意: パフォーマンス

速度面では、この関数は mysql_fetch_array() と同等で、 mysql_fetch_row() とほぼ同等です(違いはわずかです)。

注意:

mysql_fetch_object()は、配列の代わりに オブジェクトが返されるという一つの違いを除いて mysql_fetch_array()と類似しています。 つまり、オフセットによってではなく、フィールド名によってのみ データにアクセスすることができます (数字は、プロパティ名として使用できません)。

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_query() - MySQL クエリを送信する


結果を添字配列として取得する

  • ≪ mysql_fetch_object
  • mysql_field_flags ≫
  • PHP Manual
  • MySQL 関数
  • 結果を添字配列として取得する

mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — 結果を添字配列として取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_row()
  • PDOStatement::fetch() の mode に PDO::FETCH_NUM を指定する

説明

mysql_fetch_row(resource $result): array

取得された行に対応する配列を返し、内部のデータポインタを前に進めます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

戻り値

取得された行に対応する文字列の配列を返します。もう行がない場合は、 false を返します。

mysql_fetch_row()は、指定した結果 ID が指す結果から 1 行分のデータを取得します。 各結果カラムは、オフセット 0 から始まる配列に格納されます。

例

例1 mysql_fetch_row() で行を取得する

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}
$row = mysql_fetch_row($result);

echo $row[0]; // 42
echo $row[1]; // 'email' の値
?>

注意

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

参考

  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_object() - 結果の行をオブジェクトとして取得する
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_fetch_lengths() - 結果における各出力の長さを得る
  • mysql_result() - 結果データを得る


結果において指定したフィールドのフラグを取得する

  • ≪ mysql_fetch_row
  • mysql_field_len ≫
  • PHP Manual
  • MySQL 関数
  • 結果において指定したフィールドのフラグを取得する

mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — 結果において指定したフィールドのフラグを取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [flags]
  • PDOStatement::getColumnMeta() [flags]

説明

mysql_field_flags(resource $result, int $field_offset): string|false

mysql_field_flags()は、指定したフィールドの フィールドフラグを返します。個々のフラグは、空白一つで区切られた 形式で返されます。このため、返された値を explode() で分割することができます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。field_offset は 0 から始まります。field_offset が存在しない場合、E_WARNING レベルのエラーが発行されます。

戻り値

結果についてのフラグを文字列で返します。失敗した場合に false を返します。

運用システム上のMySQLがサポートしている場合、次のフラグがレポート されます。 "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", "binary", "enum", "auto_increment" そして "timestamp"

例

例1 mysql_field_flags() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}
$flags = mysql_field_flags($result, 0);

echo $flags;
print_r(explode(' ', $flags));
?>

上の例の出力は、 たとえば以下のようになります。

not_null primary_key auto_increment
Array
(
    [0] => not_null
    [1] => primary_key
    [2] => auto_increment
)

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldflags()

参考

  • mysql_field_type() - 結果において指定したフィールドの型を取得する
  • mysql_field_len() - 指定したフィールドの長さを返す


指定したフィールドの長さを返す

  • ≪ mysql_field_flags
  • mysql_field_name ≫
  • PHP Manual
  • MySQL 関数
  • 指定したフィールドの長さを返す

mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — 指定したフィールドの長さを返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [length]
  • PDOStatement::getColumnMeta() [len]

説明

mysql_field_len(resource $result, int $field_offset): int|false

mysql_field_len()は指定したフィールドの長さを 返します。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。field_offset は 0 から始まります。field_offset が存在しない場合、E_WARNING レベルのエラーが発行されます。

戻り値

成功した場合には指定したフィールドの長さ、失敗した場合に false を返します。

例

例1 mysql_field_len() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}

// データベーススキーマで定義されている、id フィールドの
// 長さを取得する
$length = mysql_field_len($result, 0);
echo $length;
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldlen()

参考

  • mysql_fetch_lengths() - 結果における各出力の長さを得る
  • strlen() - 文字列の長さを得る


結果において指定したフィールド名を取得する

  • ≪ mysql_field_len
  • mysql_field_seek ≫
  • PHP Manual
  • MySQL 関数
  • 結果において指定したフィールド名を取得する

mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — 結果において指定したフィールド名を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [name] あるいは [orgname]
  • PDOStatement::getColumnMeta() [name]

説明

mysql_field_name(resource $result, int $field_offset): string|false

mysql_field_name()は、指定したフィールドの 名前を返します。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。field_offset は 0 から始まります。field_offset が存在しない場合、E_WARNING レベルのエラーが発行されます。

戻り値

成功した場合に指定したフィールドの名前を、失敗した場合に false を返します。

例

例1 mysql_field_name() の例

<?php
/* users テーブルには以下の 3 つのフィールドがある
* user_id
* username
* password.
*/
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect to MySQL server: ' . mysql_error());
}
$dbname = 'mydb';
$db_selected = mysql_select_db($dbname, $link);
if (!$db_selected) {
die("Could not set $dbname: " . mysql_error());
}
$res = mysql_query('select * from users', $link);

echo mysql_field_name($res, 0) . "\n";
echo mysql_field_name($res, 2);
?>

上の例の出力は以下となります。

user_id
password

注意

注意: この関数により返されるフィー ルド名は 大文字小文字を区別 します。

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldname()

参考

  • mysql_field_type() - 結果において指定したフィールドの型を取得する
  • mysql_field_len() - 指定したフィールドの長さを返す


結果ポインタを指定したフィールドオフセットにセットする

  • ≪ mysql_field_name
  • mysql_field_table ≫
  • PHP Manual
  • MySQL 関数
  • 結果ポインタを指定したフィールドオフセットにセットする

mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — 結果ポインタを指定したフィールドオフセットにセットする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_field_seek()
  • PDOStatement::fetch() で cursor_orientation パラメータおよび offset パラメータを使う

説明

mysql_field_seek(resource $result, int $field_offset): bool

指定したフィールドオフセットに移動します。 mysql_field_seek() をコールした後、 mysql_fetch_field() をフィールドオフセットを付けずに コールした場合、このフィールドが返されます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。field_offset は 0 から始まります。field_offset が存在しない場合、E_WARNING レベルのエラーが発行されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mysql_fetch_field() - 結果からカラム情報を取得し、オブジェクトとして返す


指定したフィールドが含まれるテーブルの名前を取得する

  • ≪ mysql_field_seek
  • mysql_field_type ≫
  • PHP Manual
  • MySQL 関数
  • 指定したフィールドが含まれるテーブルの名前を取得する

mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — 指定したフィールドが含まれるテーブルの名前を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [table] あるいは [orgtable]
  • PDOStatement::getColumnMeta() [table]

説明

mysql_field_table(resource $result, int $field_offset): string

指定したフィールドが含まれるテーブルの名前を返します。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。field_offset は 0 から始まります。field_offset が存在しない場合、E_WARNING レベルのエラーが発行されます。

戻り値

成功した場合にテーブルの名前を返します。

例

例1 mysql_field_table() の例

<?php

$query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

// 結果を DB から取得します
$result = mysql_query($query);

// テーブル名とフィールド名を一覧表示します
for ($i = 0; $i < mysql_num_fields($result); ++$i) {
$table = mysql_field_table($result, $i);
$field = mysql_field_name($result, $i);

echo "$table: $field\n";
}

?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldtable()

参考

  • mysql_list_tables() - MySQL データベース上のテーブルのリストを得る


結果において指定したフィールドの型を取得する

  • ≪ mysql_field_table
  • mysql_free_result ≫
  • PHP Manual
  • MySQL 関数
  • 結果において指定したフィールドの型を取得する

mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — 結果において指定したフィールドの型を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_fetch_field_direct() [type]
  • PDOStatement::getColumnMeta() [driver:decl_type] あるいは [pdo_type]

説明

mysql_field_type(resource $result, int $field_offset): string

mysql_field_type() は、 mysql_field_name() 関数に似ています。 引数は同じですが、この関数ではフィールドの型が返されます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

field_offset

数値フィールドオフセット。field_offset は 0 から始まります。field_offset が存在しない場合、E_WARNING レベルのエラーが発行されます。

戻り値

返されるフィールド型は "int", "real", "string", "blob", そして その他 » MySQL ドキュメント で詳細が規定されている型のうちのひとつになります。

例

例1 mysql_field_type() の例

<?php
mysql_connect("localhost", "mysql_username", "mysql_password");
mysql_select_db("mysql");
$result = mysql_query("SELECT * FROM func");
$fields = mysql_num_fields($result);
$rows = mysql_num_rows($result);
$table = mysql_field_table($result, 0);
echo "Your '" . $table . "' table has " . $fields . " fields and " . $rows . " record(s)\n";
echo "The table has the following fields:\n";
for ($i=0; $i < $fields; $i++) {
$type = mysql_field_type($result, $i);
$name = mysql_field_name($result, $i);
$len = mysql_field_len($result, $i);
$flags = mysql_field_flags($result, $i);
echo $type . " " . $name . " " . $len . " " . $flags . "\n";
}
mysql_free_result($result);
mysql_close();
?>

上の例の出力は、 たとえば以下のようになります。

Your 'func' table has 4 fields and 1 record(s)
The table has the following fields:
string name 64 not_null primary_key binary
int ret 1 not_null
string dl 128 not_null
string type 9 not_null enum

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_fieldtype()

参考

  • mysql_field_name() - 結果において指定したフィールド名を取得する
  • mysql_field_len() - 指定したフィールドの長さを返す


結果保持用メモリを開放する

  • ≪ mysql_field_type
  • mysql_get_client_info ≫
  • PHP Manual
  • MySQL 関数
  • 結果保持用メモリを開放する

mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — 結果保持用メモリを開放する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_free_result()
  • null を PDO オブジェクトに代入、あるいは PDOStatement::closeCursor()

説明

mysql_free_result(resource $result): bool

mysql_free_result() は、結果 ID result に関するすべてのメモリを開放します。

mysql_free_result() は、 スクリプト実行のメモリの使用量が多すぎると懸念される場合にのみ 必要になります。指定した結果 ID に関する全ての結果保持用メモリは、 スクリプトの実行後に自動的に開放されます。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

result がリソースではなかった場合、 E_WARNING レベルのエラーが発生します。 mysql_query() が resource を返すのは SELECT, SHOW, EXPLAIN, そして DESCRIBE の場合だけであることに注意しましょう。

例

例1 mysql_free_result() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}
/* 結果を利用する。ここでは、その後結果を利用したものと仮定する */
$row = mysql_fetch_assoc($result);

/* 結果を開放し、さらにスクリプトの処理を進める */
mysql_free_result($result);

echo $row['id'];
echo $row['email'];
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_freeresult()

参考

  • mysql_query() - MySQL クエリを送信する
  • is_resource() - 変数がリソースかどうかを調べる


MySQL クライアント情報を取得する

  • ≪ mysql_free_result
  • mysql_get_host_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL クライアント情報を取得する

mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — MySQL クライアント情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_client_info()
  • PDO::getAttribute() の attribute に PDO::ATTR_CLIENT_VERSION を指定する

説明

mysql_get_client_info(): string

mysql_get_client_info() は、 クライアントライブラリのバージョンを表す文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

MySQL クライアントのバージョンを返します。

例

例1 mysql_get_client_info() の例

<?php
printf("MySQL client info: %s\n", mysql_get_client_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL client info: 3.23.39

参考

  • mysql_get_host_info() - MySQL ホスト情報を取得する
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する
  • mysql_get_server_info() - MySQL サーバー情報を取得する


MySQL ホスト情報を取得する

  • ≪ mysql_get_client_info
  • mysql_get_proto_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL ホスト情報を取得する

mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — MySQL ホスト情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_host_info()
  • PDO::getAttribute() の attribute に PDO::ATTR_CONNECTION_STATUS を指定する

説明

mysql_get_host_info(resource $link_identifier = NULL): string|false

使用されている接続の型を返します。その中にはサーバーのホスト名も含まれます。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

使用されている MySQL 接続の型を表す文字列を返します。 失敗した場合に false を返します。

例

例1 mysql_get_host_info() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
printf("MySQL host info: %s\n", mysql_get_host_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL host info: Localhost via UNIX socket

参考

  • mysql_get_client_info() - MySQL クライアント情報を取得する
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する
  • mysql_get_server_info() - MySQL サーバー情報を取得する


MySQL プロトコル情報を取得する

  • ≪ mysql_get_host_info
  • mysql_get_server_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL プロトコル情報を取得する

mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — MySQL プロトコル情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_proto_info()

説明

mysql_get_proto_info(resource $link_identifier = NULL): int|false

MySQL プロトコルを取得します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に MySQL プロトコル、失敗した場合に false を返します。

例

例1 mysql_get_proto_info() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
printf("MySQL protocol version: %s\n", mysql_get_proto_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL protocol version: 10

参考

  • mysql_get_client_info() - MySQL クライアント情報を取得する
  • mysql_get_host_info() - MySQL ホスト情報を取得する
  • mysql_get_server_info() - MySQL サーバー情報を取得する


MySQL サーバー情報を取得する

  • ≪ mysql_get_proto_info
  • mysql_info ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバー情報を取得する

mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — MySQL サーバー情報を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_get_server_info()
  • PDO::getAttribute() の attribute に PDO::ATTR_SERVER_VERSION を指定する

説明

mysql_get_server_info(resource $link_identifier = NULL): string|false

MySQL サーバーのバージョンを取得します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に MySQL サーバーのバージョン、失敗した場合に false を返します。

例

例1 mysql_get_server_info() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
printf("MySQL server version: %s\n", mysql_get_server_info());
?>

上の例の出力は、 たとえば以下のようになります。

MySQL server version: 4.0.1-alpha

参考

  • mysql_get_client_info() - MySQL クライアント情報を取得する
  • mysql_get_host_info() - MySQL ホスト情報を取得する
  • mysql_get_proto_info() - MySQL プロトコル情報を取得する
  • phpversion() - 現在の PHP バージョンを取得する


直近のクエリについての情報を得る

  • ≪ mysql_get_server_info
  • mysql_insert_id ≫
  • PHP Manual
  • MySQL 関数
  • 直近のクエリについての情報を得る

mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — 直近のクエリについての情報を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_info()

説明

mysql_info(resource $link_identifier = NULL): string

直近のクエリについての詳細な情報を返します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に文についての情報、失敗した場合に false を返します。 どんな文が情報を返し、またそれがどのように見えるのかについては、以下の 例を参照ください。ここに挙げられていない文では false が返されます。

例

例1 該当する MySQL 文

情報を返す文の例です。数値はあくまで説明用の例で、実際の値は クエリの内容によって変わります。

INSERT INTO ... SELECT ...
String format: Records: 23 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
String format: Records: 37 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...
String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
String format: Records: 60 Duplicates: 0 Warnings: 0
UPDATE
String format: Rows matched: 65 Changed: 65 Warnings: 0

注意

注意:

INSERT ... VALUES 文で mysql_info() が非 false 値を 返すのは、文中で複数の値のリストが指定された場合に限ります。

参考

  • mysql_affected_rows() - 一番最近の操作で変更された行の数を得る
  • mysql_insert_id() - 直近のクエリで生成された ID を得る
  • mysql_stat() - 現在のシステムの状態を取得する


直近のクエリで生成された ID を得る

  • ≪ mysql_info
  • mysql_list_dbs ≫
  • PHP Manual
  • MySQL 関数
  • 直近のクエリで生成された ID を得る

mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — 直近のクエリで生成された ID を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_insert_id()
  • PDO::lastInsertId()

説明

mysql_insert_id(resource $link_identifier = NULL): int

直近のクエリ (通常は INSERT) により AUTO_INCREMENT カラム用に生成された ID を取得します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

直近のクエリにより AUTO_INCREMENT カラム用に生成された ID を返します。直近のクエリが AUTO_INCREMENT な値を生成しなかった 場合に 0、MySQL 接続が確立されていなかった 場合に false を返します。

例

例1 mysql_insert_id() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');

mysql_query("INSERT INTO mytable (product) values ('kossu')");
printf("最後に挿入されたレコードの ID は、%d\n", mysql_insert_id());
?>

注意

警告

mysql_insert_id() は、MySQL C API 関数 mysql_insert_id() の戻り値の型を long 型（PHP では int と呼ばれる） に変換します。 AUTO_INCREMENT カラムが BIGINT 型 (64 ビット) である場合、 変換結果は不正確になります。 かわりに、MySQL の SQL 関数 LAST_INSERT_ID() を SQL 内で使いましょう。 PHP の integer 型の最大値に関する詳細な説明は、 integer のドキュメントをごらんください。

注意:

mysql_insert_id() は直近のクエリに対して働くので、 値を生成したクエリの直後に mysql_insert_id() をコールすることを忘れないようにしてください。

注意:

MySQL の SQL 関数 LAST_INSERT_ID() の値には、 常に直近の AUTO_INCREMENT の値が含まれており、クエリの間では リセットされません。

参考

  • mysql_query() - MySQL クエリを送信する
  • mysql_info() - 直近のクエリについての情報を得る


MySQL サーバー上で利用可能なデータベースのリストを得る

  • ≪ mysql_insert_id
  • mysql_list_fields ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバー上で利用可能なデータベースのリストを得る

mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — MySQL サーバー上で利用可能なデータベースのリストを得る

警告

この関数は PHP 5.4.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW DATABASES

説明

mysql_list_dbs(resource $link_identifier = NULL): resource

現在の mysql デーモンで利用可能なデータベースの結果ポインタを返します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に結果ポインタ resource を、失敗した場合に false を返します。結果ポインタの中身を調べるために mysql_tablename() 関数を利用し、取得したテーブルを 利用するには mysql_fetch_array() などの関数を 利用してください。

例

例1 mysql_list_dbs() の例

<?php
// mysql_list_dbs() を使わない方法
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$res = mysql_query("SHOW DATABASES");

while ($row = mysql_fetch_assoc($res)) {
echo $row['Database'] . "\n";
}

// PHP 5.4.0 からは非推奨
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$db_list = mysql_list_dbs($link);

while ($row = mysql_fetch_object($db_list)) {
echo $row->Database . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

database1
database2
database3

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_listdbs()

参考

  • mysql_db_name() - mysql_list_dbs のコール結果からデータベース名を取得する
  • mysql_select_db() - MySQL データベースを選択する


MySQL テーブルのフィールドのリストを得る

  • ≪ mysql_list_dbs
  • mysql_list_processes ≫
  • PHP Manual
  • MySQL 関数
  • MySQL テーブルのフィールドのリストを得る

mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — MySQL テーブルのフィールドのリストを得る

警告

この関数は PHP 5.4.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW COLUMNS FROM sometable

説明

mysql_list_fields(string $database_name, string $table_name, resource $link_identifier = NULL): resource

指定された名前のテーブルについての情報を取得します。

この関数は非推奨です。かわりに mysql_query() を利用して SHOW COLUMNS FROM table [LIKE 'name'] 文を発行することを推奨します。

パラメータ

database_name

クエリの対象となるデータベース名。

table_name

クエリの対象となるテーブル名。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に結果ポインタ resource 、失敗した場合に false を返します。

返された結果は mysql_field_flags(),
mysql_field_len(),
mysql_field_name() そして
mysql_field_type() で利用可能です。

例

例1 非推奨である mysql_list_fields() の代替例

<?php
$result = mysql_query("SHOW COLUMNS FROM sometable");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}
if (mysql_num_rows($result) > 0) {
while ($row = mysql_fetch_assoc($result)) {
print_r($row);
}
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Field] => id
    [Type] => int(7)
    [Null] =>
    [Key] => PRI
    [Default] =>
    [Extra] => auto_increment
)
Array
(
    [Field] => email
    [Type] => varchar(100)
    [Null] =>
    [Key] =>
    [Default] =>
    [Extra] =>
)

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_listfields()

参考

  • mysql_field_flags() - 結果において指定したフィールドのフラグを取得する
  • mysql_info() - 直近のクエリについての情報を得る


MySQL プロセスのリストを得る

  • ≪ mysql_list_fields
  • mysql_list_tables ≫
  • PHP Manual
  • MySQL 関数
  • MySQL プロセスのリストを得る

mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — MySQL プロセスのリストを得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_thread_id()

説明

mysql_list_processes(resource $link_identifier = NULL): resource|false

現在の MySQL サーバーのスレッドを取得します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に結果ポインタ resource 、 失敗した場合に false を返します。

例

例1 mysql_list_processes() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');

$result = mysql_list_processes($link);
while ($row = mysql_fetch_assoc($result)){
printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
$row["Command"], $row["Time"]);
}
mysql_free_result($result);
?>

上の例の出力は、 たとえば以下のようになります。

1 localhost test Processlist 0
4 localhost mysql sleep 5

参考

  • mysql_thread_id() - カレントのスレッド ID を返す
  • mysql_stat() - 現在のシステムの状態を取得する


MySQL データベース上のテーブルのリストを得る

  • ≪ mysql_list_processes
  • mysql_num_fields ≫
  • PHP Manual
  • MySQL 関数
  • MySQL データベース上のテーブルのリストを得る

mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — MySQL データベース上のテーブルのリストを得る

警告

この関数は PHP 4.3.0 で非推奨になり、PHP 7.0.0 で MySQL 拡張モジュール 全体とあわせて削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW TABLES FROM dbname

説明

mysql_list_tables(string $database, resource $link_identifier = NULL): resource|false

MySQL データベースから、テーブル名のリストを取得します。

この関数は非推奨となりました。かわりに mysql_query() を利用して SHOW TABLES [FROM db_name] [LIKE 'pattern'] 文を発行することを推奨します。

パラメータ

database

データベース名。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に結果ポインタ resource 、 失敗した場合に false を返します。

結果ポインタの中身を調べるためには mysql_tablename() 関数を利用し、 取得したテーブルを利用するには mysql_fetch_array() などの関数を利用してください。

変更履歴

バージョン | 説明
4.3.7 | この関数は非推奨となりました。

例

例1 mysql_list_tables() の別の例

<?php
$dbname = 'mysql_dbname';

if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
echo 'Could not connect to mysql';
exit;
}

$sql = "SHOW TABLES FROM $dbname";
$result = mysql_query($sql);

if (!$result) {
echo "DB Error, could not list tables\n";
echo 'MySQL Error: ' . mysql_error();
exit;
}

while ($row = mysql_fetch_row($result)) {
echo "Table: {$row[0]}\n";
}

mysql_free_result($result);
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_listtables()

参考

  • mysql_list_dbs() - MySQL サーバー上で利用可能なデータベースのリストを得る
  • mysql_tablename() - フィールドのテーブル名を得る


結果におけるフィールドの数を得る

  • ≪ mysql_list_tables
  • mysql_num_rows ≫
  • PHP Manual
  • MySQL 関数
  • 結果におけるフィールドの数を得る

mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — 結果におけるフィールドの数を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_num_fields()
  • PDOStatement::columnCount()

説明

mysql_num_fields(resource $result): int|false

クエリから、フィールドの数を取得します。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

戻り値

成功した場合に結果セット resource のフィールド数、 失敗した場合に false を返します。

例

例1 mysql_num_fields() の例

<?php
$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
if (!$result) {
echo 'Could not run query: ' . mysql_error();
exit;
}

/* id,email の 2 つのフィールドがあるので、2 を返す */
echo mysql_num_fields($result);
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_numfields()

参考

  • mysql_select_db() - MySQL データベースを選択する
  • mysql_query() - MySQL クエリを送信する
  • mysql_fetch_field() - 結果からカラム情報を取得し、オブジェクトとして返す
  • mysql_num_rows() - 結果における行の数を得る


結果における行の数を得る

  • ≪ mysql_num_fields
  • mysql_pconnect ≫
  • PHP Manual
  • MySQL 関数
  • 結果における行の数を得る

mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — 結果における行の数を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_num_rows()
  • mysqli_stmt_num_rows()
  • PDOStatement::rowCount()

説明

mysql_num_rows(resource $result): int|false

結果セットから行の数を取得します。このコマンドは、 SELECT や SHOW のような、実際に結果セットを返す文に対してのみ有効です。 INSERT、UPDATE、REPLACE、DELETE クエリで変更された行の数を得るには、 mysql_affected_rows() を使用してください。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

戻り値

成功した場合に結果セットの行の数、失敗した場合に false を返します。

例

例1 mysql_num_rows() の例

<?php

$link = mysql_connect("localhost", "mysql_user", "mysql_password");
mysql_select_db("database", $link);

$result = mysql_query("SELECT * FROM table1", $link);
$num_rows = mysql_num_rows($result);

echo "$num_rows Rows\n";

?>

注意

注意:

mysql_unbuffered_query() を使用した場合、 結果セットのすべての行を取得するまで mysql_num_rows() は正しい値を返しません。

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_numrows()

参考

  • mysql_affected_rows() - 一番最近の操作で変更された行の数を得る
  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_data_seek() - 内部的な結果ポインタを移動する
  • mysql_select_db() - MySQL データベースを選択する
  • mysql_query() - MySQL クエリを送信する


MySQL サーバーへの持続的な接続をオープンする

  • ≪ mysql_num_rows
  • mysql_ping ≫
  • PHP Manual
  • MySQL 関数
  • MySQL サーバーへの持続的な接続をオープンする

mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — MySQL サーバーへの持続的な接続をオープンする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_connect() にホストプレフィックス p: を指定
  • PDO::__construct() のドライバオプションで PDO::ATTR_PERSISTENT を指定

説明

mysql_pconnect(
string $server = ini_get("mysql.default_host"),
string $username = ini_get("mysql.default_user"),
string $password = ini_get("mysql.default_password"),
int $client_flags = 0
): resource

MySQL サーバーとの持続的な接続を確立します。

mysql_pconnect()は、 mysql_connect()とよく似た動作をしますが、 2 つの大きな違いがあります。

1 番目の違いとして、この関数は接続時にまず 同じホスト、ユーザー名、パスワードを有する(持続的)リンクが すでにオープンされていないかどうかを調べます。 それがみつかった場合、新規の接続をオープンする代わりに そのリンクの ID が返されます。

2 番目の違いは、スクリプトの実行が終了しても SQL サーバーとの接続が 閉じられないということです。そのかわりに、将来再利用されるために リンクがオープンされたままとなります（mysql_close() は、mysql_pconnect() によって確立されたリンクを 閉じません）。

このため、この型のリンクは、'持続的(persistent)'であると言われます。

パラメータ

server

MySQL サーバー。"hostname:port" のようにポート番号を 指定することが可能で、localhost では ":/path/to/socket" のようにソケットへのパスを指定することも可能です。

PHP ディレクティブ mysql.default_host が指定されない場合（デフォルト）、 'localhost:3306' が使用されます。

username

ユーザー名。デフォルト値はサーバープロセスの所有ユーザー名です。

password

パスワード。デフォルト値は空のパスワードです。

client_flags

パラメータ client_flags は、 以下の定数の組み合わせです： 128 (LOAD DATA LOCAL の処理を有効にする)、 MYSQL_CLIENT_SSL、 MYSQL_CLIENT_COMPRESS、 MYSQL_CLIENT_IGNORE_SPACE または MYSQL_CLIENT_INTERACTIVE

戻り値

成功した場合に MySQL 持続的リンク ID を、失敗した場合に false を返します。

注意

注意:

この接続方法は、モジュールバージョンの PHP でのみ使用可能であることに 注意しましょう。詳しい情報は 持続的 データベース接続 を参照ください。

警告

持続的接続を利用する場合、MySQL の同時接続数の制限をこえないように Apache や MySQL の設定を多少変更する必要があるかも知れません。

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • Persistent Database Connections


サーバーとの接続状況を調べ、接続されていない場合は再接続する

  • ≪ mysql_pconnect
  • mysql_query ≫
  • PHP Manual
  • MySQL 関数
  • サーバーとの接続状況を調べ、接続されていない場合は再接続する

mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — サーバーとの接続状況を調べ、接続されていない場合は再接続する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_ping()

説明

mysql_ping(resource $link_identifier = NULL): bool

サーバーとの接続が有効かどうかを調べます。 もし接続が切れていた場合、自動的に再接続が試みられます。 この関数は、アイドル期間が長いスクリプトで利用し、 サーバーが接続を切断したかどうかを確認するために用いられます。

注意:

MySQL 5.0.3 以降、自動再接続機能は使えなくなりました。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

MySQL サーバーとの接続が有効な場合に true そうでない場合に false を返します。

例

例1 mysql_ping() の例

<?php
set_time_limit(0);

$conn = mysql_connect('localhost', 'mysqluser', 'mypass');
$db = mysql_select_db('mydb');

/* このクエリは非常に時間がかかるものと仮定する */
$result = mysql_query($sql);
if (!$result) {
echo 'Query #1 failed, exiting.';
exit;
}

/* 接続が有効かどうかを確かめる。切断されていたら再接続する */
if (!mysql_ping($conn)) {
echo 'Lost connection, exiting after query #1';
exit;
}
mysql_free_result($result);

/* 接続が有効であることが確かめられたので、別のクエリを実行する */
$result2 = mysql_query($sql2);
?>

参考

  • mysql_thread_id() - カレントのスレッド ID を返す
  • mysql_list_processes() - MySQL プロセスのリストを得る


MySQL クエリを送信する

  • ≪ mysql_ping
  • mysql_real_escape_string ≫
  • PHP Manual
  • MySQL 関数
  • MySQL クエリを送信する

mysql_query

(PHP 4, PHP 5)

mysql_query — MySQL クエリを送信する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_query()
  • PDO::query()

説明

mysql_query(string $query, resource $link_identifier = NULL): mixed

mysql_query() は、 ひとつのクエリを送信します (複数クエリの送信はサポートしません)。 送信先は、link_identifier で指定したサーバー上にある、現在アクティブなデータベースです。

パラメータ

query

SQL クエリ。

クエリ文字列は、セミコロンで終えてはいけません。 クエリ内のデータは 適切にエスケープ する必要があります。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

SELECT, SHOW, DESCRIBE や EXPLAIN 文、その他結果セットを返す文では、 mysql_query() は成功した場合に resource を返します。エラー時には false を返します。

それ以外の SQL 文 INSERT, UPDATE, DELETE, DROP などでは、 mysql_query() は成功した場合に true 、エラー時に false を返します。

返された結果にアクセスするためには、結果リソースを mysql_fetch_array() やその他の関数に渡します。

SELECT 文によって返された行の数を知るには mysql_num_rows() を用います。また DELETE, INSERT, REPLACE, または UPDATE 文で変更された行の数を 知るには mysql_affected_rows() を用います。

クエリが参照するテーブルにアクセスする権限がない場合も mysql_query()は失敗し、false が返されます。

例

例1 間違ったクエリ

次のクエリは文法的に間違っているので、 mysql_query()は失敗し falseを返します。

<?php
$result = mysql_query('SELECT * WHERE 1=1');
if (!$result) {
die('Invalid query: ' . mysql_error());
}

?>

例2 正しいクエリ

次のクエリは正しいので、mysql_query() は resource を返します。

<?php
// これはユーザーが指定する。たとえば
$firstname = 'fred';
$lastname = 'fox';

// クエリの作成
// これは SQL クエリを実行する最良の方法です。
// さらなる例は、mysql_real_escape_string() を参照ください。
$query = sprintf("SELECT firstname, lastname, address, age FROM friends
WHERE firstname='%s' AND lastname='%s'",
mysql_real_escape_string($firstname),
mysql_real_escape_string($lastname));

// クエリの実行
$result = mysql_query($query);

// 結果のチェック
// MySQL に送られたクエリと返ってきたエラーをそのまま表示します。デバッグに便利です。
if (!$result) {
$message = 'Invalid query: ' . mysql_error() . "\n";
$message .= 'Whole query: ' . $query;
die($message);
}

// 結果の利用
// $result をそのまま出力してもリソースの内部の情報にはアクセスできません。
// 結果に対して MySQL の関数を適用する必要があります。
// mysql_result(), mysql_fetch_array(), mysql_fetch_row() なども参照ください。
while ($row = mysql_fetch_assoc($result)) {
echo $row['firstname'];
echo $row['lastname'];
echo $row['address'];
echo $row['age'];
}

// 結果セットに関連付けられているリソースの開放
// これは、スクリプトが終了する際に自動的に実行されます。
mysql_free_result($result);
?>

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_error() - 直近に実行された MySQL 操作のエラーメッセージを返す
  • mysql_real_escape_string() - SQL 文中で用いる文字列の特殊文字をエスケープする
  • mysql_result() - 結果データを得る
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_unbuffered_query() - MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない


SQL 文中で用いる文字列の特殊文字をエスケープする

  • ≪ mysql_query
  • mysql_result ≫
  • PHP Manual
  • MySQL 関数
  • SQL 文中で用いる文字列の特殊文字をエスケープする

mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — SQL 文中で用いる文字列の特殊文字をエスケープする

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_real_escape_string()
  • PDO::quote()

説明

mysql_real_escape_string(string $unescaped_string, resource $link_identifier = NULL): string

現在の接続の文字セットで unescaped_string の特殊文字をエスケープし、 mysql_query() で安全に利用できる形式に変換します。バイナリデータを挿入しようとしている場合、 必ずこの関数を利用しなければなりません。

mysql_real_escape_string() は、MySQL のライブラリ関数 mysql_real_escape_string をコールしています。 これは以下の文字について先頭にバックスラッシュを付加します。 \x00, \n, \r, \, ', " そして \x1a.

データの安全性を確保するため、MySQL へクエリを送信する場合には （わずかな例外を除いて）常にこの関数を用いなければなりません。

警告

セキュリティ: デフォルトの文字セット

サーバーレベルで設定するなり API 関数 mysql_set_charset() を使うなりして、 文字セットを明示しておく必要があります。この文字セットが mysql_real_escape_string() に影響を及ぼします。詳細は 文字セットの概念 を参照ください。

パラメータ

unescaped_string

エスケープされる文字列。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合にエスケープ後の文字列、失敗した場合に false を返します。

エラー / 例外

MySQL 接続が存在しない状態でこの関数を実行すると、 E_WARNING レベルのエラーが発生します。 この関数は、MySQL 接続が確立した状態でのみ実行するようにしましょう。

例

例1 単純な mysql_real_escape_string() の例

<?php
// 接続
$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
OR die(mysql_error());

// クエリ
$query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
mysql_real_escape_string($user),
mysql_real_escape_string($password));
?>

例2 mysql_real_escape_string() には接続が必須であることを示す例

この例では、MySQL 接続が存在しない状態でこの関数を実行したときにどうなるかを示します。

<?php
// まだ MySQL に接続していません

$lastname = "O'Reilly";
$_lastname = mysql_real_escape_string($lastname);

$query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

var_dump($_lastname);
var_dump($query);
?>

上の例の出力は、 たとえば以下のようになります。

Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

bool(false)
string(41) "SELECT * FROM actors WHERE last_name = ''"

例3 SQL インジェクション攻撃の例

<?php
// $_POST['password'] をチェックしなければ、このような例でユーザーに望みどおりの情報を取得されてしまう
$_POST['username'] = 'aidan';
$_POST['password'] = "' OR ''='";

// データベース上のユーザーに一致するかどうかを調べる
$query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
mysql_query($query);

// MySQL に送信されたクエリは、
echo $query;
?>

MySQL に送信されたクエリは次のとおり:

SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

これでは、パスワードを知らなくても誰でもログインできてしまいます。

注意

注意:

mysql_real_escape_string() を利用する前に、MySQL 接続が確立されている必要があります。もし存在しなければ、 E_WARNING レベルのエラーが生成され、false が返されます。link_identifier が指定されなかった場合は、 直近の MySQL 接続が用いられます。

注意:

この関数を用いてデータをエスケープしなければ、クエリは SQL インジェクション攻撃 に対しての脆弱性を持ったものになります。

注意: mysql_real_escape_string() は % や _ をエスケープしません。 MySQL では、これらの文字を LIKE, GRANT, または REVOKE とともに用いることで、 ワイルドカードを表現します。

参考

  • mysql_set_charset() - クライアントの文字セットを設定する
  • mysql_client_encoding() - 文字セット名を返す


結果データを得る

  • ≪ mysql_real_escape_string
  • mysql_select_db ≫
  • PHP Manual
  • MySQL 関数
  • 結果データを得る

mysql_result

(PHP 4, PHP 5)

mysql_result — 結果データを得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_data_seek() を
mysqli_field_seek() や
mysqli_fetch_field() と組み合わせる
  • PDOStatement::fetchColumn()

説明

mysql_result(resource $result, int $row, mixed $field = 0): string

MySQL の結果セットからひとつのセルの内容を取得します。

大量の結果セットで作業を行う際は、行全体を取り込む関数のうちひとつを 使用することを検討するべきです（以下で説明します）。 これらの関数は一回の関数コールで複数のセルの内容を返すので、 mysql_result() よりもかなり高速です。 また、フィールド引数としてオフセット数値を指定する方が フィールド名やテーブル名.フィールド名のように指定するよりも かなり高速です。

パラメータ

result

評価された結果 リソース。この結果は、mysql_query() のコールにより得られたものです。

row

結果から取得する行の番号。行番号は 0 からはじまります。

field

取得したいフィールド名またはフィールドのオフセット。

フィールドのオフセット、フィールド名またはテーブル名.フィールド名を 指定可能です。カラム名のエイリアスが定義されている （'select foo as bar from...'）場合、そのカラム名の代わりに エイリアスを使用してください。指定しなかった場合は最初のフィールドを 取得します。

戻り値

成功した場合に MySQL 結果セットのひとつのセルの内容、 失敗した場合に false を返します。

例

例1 mysql_result() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
if (!mysql_select_db('database_name')) {
die('Could not select database: ' . mysql_error());
}
$result = mysql_query('SELECT name FROM work.employee');
if (!$result) {
die('Could not query:' . mysql_error());
}
echo mysql_result($result, 2); // 3 番目の employee の name を出力する

mysql_close($link);
?>

注意

注意:

mysql_result() は、 結果セットを処理するほかの関数と混用することはできません。

参考

  • mysql_fetch_row() - 結果を添字配列として取得する
  • mysql_fetch_array() - 連想配列、添字配列、またはその両方として結果の行を取得する
  • mysql_fetch_assoc() - 連想配列として結果の行を取得する
  • mysql_fetch_object() - 結果の行をオブジェクトとして取得する


MySQL データベースを選択する

  • ≪ mysql_result
  • mysql_set_charset ≫
  • PHP Manual
  • MySQL 関数
  • MySQL データベースを選択する

mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — MySQL データベースを選択する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_select_db()
  • PDO::__construct() (dsn で指定)

説明

mysql_select_db(string $database_name, resource $link_identifier = NULL): bool

指定したリンク ID が指すサーバー上のデータベースを、アクティブな データベースに設定します。それ以降にコールされる mysql_query() は、すべてアクティブなデータベース上で 実行されます。

パラメータ

database_name

選択するデータベース名。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mysql_select_db() の例

<?php

$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Not connected : ' . mysql_error());
}

// foo をカレントの db に指定する
$db_selected = mysql_select_db('foo', $link);
if (!$db_selected) {
die ('Can\'t use foo : ' . mysql_error());
}
?>

注意

注意:

下位互換のために、次の非推奨別名を使用してもいいでしょう。 mysql_selectdb()

参考

  • mysql_connect() - MySQL サーバーへの接続をオープンする
  • mysql_pconnect() - MySQL サーバーへの持続的な接続をオープンする
  • mysql_query() - MySQL クエリを送信する


クライアントの文字セットを設定する

  • ≪ mysql_select_db
  • mysql_stat ≫
  • PHP Manual
  • MySQL 関数
  • クライアントの文字セットを設定する

mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — クライアントの文字セットを設定する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_set_charset()
  • PDO: 接続文字列に charset を追加して charset=utf8 などとする

説明

mysql_set_charset(string $charset, resource $link_identifier = NULL): bool

現在の接続における、デフォルトの文字セットを設定します。

パラメータ

charset

有効な文字セット名。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、MySQL 5.0.7 以降でないと使用できません。

注意:

文字セットを変更するにはこの方法を使うことを推奨します。 mysql_query() で (SET NAMES utf8 などとして) 設定する方法はお勧めできません。詳細は MySQL の文字セットの概念 を参照ください。

参考

  • MySQL での文字セットの設定
  • » MySQL がサポートする文字セットの一覧
  • mysql_client_encoding() - 文字セット名を返す


現在のシステムの状態を取得する

  • ≪ mysql_set_charset
  • mysql_tablename ≫
  • PHP Manual
  • MySQL 関数
  • 現在のシステムの状態を取得する

mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — 現在のシステムの状態を取得する

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_stat()
  • PDO::getAttribute() の attribute に PDO::ATTR_SERVER_INFO を指定する

説明

mysql_stat(resource $link_identifier = NULL): string

mysql_stat() は現在のサーバーの状態を返します。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

稼働時間、スレッド、クエリ、オープンされているテーブル、フラッシュされた テーブル、そして 1 秒あたりのクエリ数を文字列で返します。その他のデータも 含めた完全な状態を得るには、SHOW STATUS SQL コマンドを 実行する必要があります。link_identifier が不正な 場合には null が返されます。

例

例1 mysql_stat() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$status = explode(' ', mysql_stat($link));
print_r($status);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Uptime: 5380
    [1] => Threads: 2
    [2] => Questions: 1321299
    [3] => Slow queries: 0
    [4] => Opens: 26
    [5] => Flush tables: 1
    [6] => Open tables: 17
    [7] => Queries per second avg: 245.595
)

例2 mysql_stat() の別の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$result = mysql_query('SHOW STATUS', $link);
while ($row = mysql_fetch_assoc($result)) {
echo $row['Variable_name'] . ' = ' . $row['Value'] . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

back_log = 50
basedir = /usr/local/
bdb_cache_size = 8388600
bdb_log_buffer_size = 32768
bdb_home = /var/db/mysql/
bdb_max_lock = 10000
bdb_logdir =
bdb_shared_data = OFF
bdb_tmpdir = /var/tmp/
...

参考

  • mysql_get_server_info() - MySQL サーバー情報を取得する
  • mysql_list_processes() - MySQL プロセスのリストを得る


フィールドのテーブル名を得る

  • ≪ mysql_stat
  • mysql_thread_id ≫
  • PHP Manual
  • MySQL 関数
  • フィールドのテーブル名を得る

mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — フィールドのテーブル名を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • SQL クエリー: SHOW TABLES

説明

mysql_tablename(resource $result, int $i): string|false

result からテーブル名を取得します。

この関数は非推奨です。かわりに mysql_query() を利用して SHOW TABLES [FROM db_name] [LIKE 'pattern'] 文を発行することを推奨します。

パラメータ

result

mysql_list_tables() から返される 結果ポインタ resource 。

i

整数のインデックス（行/テーブル 番号）。

戻り値

成功した場合にテーブル名、失敗した場合に false を返します。

結果ポインタの中身を調べるために mysql_tablename() 関数を利用し、取得したテーブルを 利用するには mysql_fetch_array() などの関数を 利用してください。

例

例1 mysql_tablename() の例

<?php
mysql_connect("localhost", "mysql_user", "mysql_password");
$result = mysql_list_tables("mydb");
$num_rows = mysql_num_rows($result);
for ($i = 0; $i < $num_rows; $i++) {
echo "Table: ", mysql_tablename($result, $i), "\n";
}

mysql_free_result($result);
?>

注意

注意:

結果ポインタに含まれるテーブル数を調べるには mysql_num_rows() 関数を利用します。

参考

  • mysql_list_tables() - MySQL データベース上のテーブルのリストを得る
  • mysql_field_table() - 指定したフィールドが含まれるテーブルの名前を取得する
  • mysql_db_name() - mysql_list_dbs のコール結果からデータベース名を取得する


カレントのスレッド ID を返す

  • ≪ mysql_tablename
  • mysql_unbuffered_query ≫
  • PHP Manual
  • MySQL 関数
  • カレントのスレッド ID を返す

mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — カレントのスレッド ID を返す

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • mysqli_thread_id()

説明

mysql_thread_id(resource $link_identifier = NULL): int|false

カレントのスレッド ID を取得します。接続が一度切断され、 mysql_ping() によって再接続された場合には、 スレッド ID は変わります。つまり、スレッド ID は必要になったその時点で 取得すべきだということです。

パラメータ

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

成功した場合にスレッド ID 、失敗した場合に false を返します。

例

例1 mysql_thread_id() の例

<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$thread_id = mysql_thread_id($link);
if ($thread_id){
printf("current thread id is %d\n", $thread_id);
}
?>

上の例の出力は、 たとえば以下のようになります。

current thread id is 73

参考

  • mysql_ping() - サーバーとの接続状況を調べ、接続されていない場合は再接続する
  • mysql_list_processes() - MySQL プロセスのリストを得る


MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

  • ≪ mysql_thread_id
  • Mysqlnd ≫
  • PHP Manual
  • MySQL 関数
  • MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

  • Buffered and Unbuffered queries を参照

説明

mysql_unbuffered_query(string $query, resource $link_identifier = NULL): resource

mysql_unbuffered_query() は SQL クエリ query を MySQL に送信します。その際、 mysql_query() が行っているような自動バッファリングを 行いません。一方、この挙動により SQL クエリが消費するメモリの量を おさえられます。また、最初の 1 行目が取得されたらすぐに処理を はじめることができます。SQL の処理が完全に終わるまで待つ必要がありません。 複数の DB 接続を利用する場合には、オプションのパラメータ link_identifier を指定する必要があります。

パラメータ

query

実行する SQL クエリ。

クエリ内のデータは 適切にエスケープ する必要があります。

link_identifier

MySQL 接続。指定されない場合、mysql_connect() により直近にオープンされたリンクが指定されたと仮定されます。そのようなリンクがない場合、引数を指定せずに mysql_connect() がコールした時と同様にリンクを確立します。リンクが見付からない、または、確立できない場合、E_WARNING レベルのエラーが生成されます。

戻り値

SELECT, SHOW, DESCRIBE あるいは EXPLAIN では、 mysql_unbuffered_query() は 成功した場合に resource 、エラー時に false を返します。

UPDATE, DELETE, DROP, などその他の SQL 文では、 mysql_unbuffered_query() は 成功した場合に true 、エラー時に false を返します。

注意

注意:

mysql_unbuffered_query() の利点には、以下のような 代償があります: mysql_unbuffered_query() から返される結果セットには、 すべての行をフェッチするまでは mysql_num_rows() や mysql_data_seek() を使用できません。また、結果の行をすべてフェッチするまで、 同じ link_identifier を使って MySQL に新しいクエリを送信することができません。

参考

  • mysql_query() - MySQL クエリを送信する


MySQL Native Driver

  • はじめに
  • 概要
  • インストール
  • 実行時設定
  • 非互換性
  • 持続的接続
  • Statistics
  • メモ
  • メモリ管理
  • MySQL Native Driver プラグインAPI
    • mysqlndプラグイン と MySQL Proxyの比較
    • mysqlnd plugin APIを取得する
    • MySQL Native Driverプラグイン のアーキテクチャ
    • mysqlnd のプラグインAPI
    • mysqlndプラグインの開発をはじめよう


はじめに

MySQL Native Driver(mysqlnd) は、MySQL Client Library (libmysqlclient) の後継です。 MySQL Native Driver は、PHP 5.3.0 以降の公式のソースコードに同梱されています。

MySQL データベース用の拡張モジュールである MySQL や mysqli そして PDO MYSQL は、 すべて MySQL サーバーと通信します。 かつては、これらの拡張モジュールがサーバーと通信するときには MySQL Client Library が提供するサービスを使っていました。 これらの拡張モジュールをコンパイルするときに MySQL Client Library を組み込み、そのクライアント・サーバープロトコルを使っていたのです。

今や MySQL Native Driver がその代替として登場したので、 MySQL データベース用の拡張モジュールをコンパイルするときに MySQL Native Driver を使えば MySQL Client Library なしでもコンパイルできるようになったのです。

MySQL Native Driver は、C 言語で書かれた PHP 用拡張モジュールです。


概要

何ではないか

MySQL Native Driver は PHP の拡張モジュールとして作られていますが、 PHP を使って開発をする人たちに新しい API を提供するものではないことに注意しましょう。 MySQL データベースに接続するための API を提供するのは、 MySQL 拡張モジュールや mysqli そして PDO MYSQL です。これらの拡張モジュールが、MySQL Native Driver を使って MySQL サーバーと通信できるようになったということです。 したがって、MySQL Native Driver を新たな API と考えてはいけません。

使うべき理由

MySQL Native Driver には、 MySQL Client Library に比べて数多くの利点があります。

旧来の MySQL Client Library は MySQL AB (現在の Oracle Corporation) が書いたものであり、MySQL ライセンスのもとでリリースされていました。 それが原因で、最終的には PHP がデフォルトで MySQL をサポートしなくなってしまいました。 しかし MySQL Native Driver は PHP プロジェクトの一部として開発されており、 PHP ライセンスのもとでリリースされています。 これで、かつて存在したライセンス問題も解決しました。

また、かつては MySQL データベース用の拡張モジュールをビルドするには MySQL Client Library が必要でした。 これはつまり、PHP をソースからビルドしようとすると、 そのマシン上に MySQL をインストールしておく必要があったということです。 また、PHP のアプリケーションを動かす際に、 MySQL データベース用の拡張モジュールは最終的に MySQL Client Library のファイルを呼び出すことになるので、 システム上にそのファイルをインストールしておくことも必要でした。 MySQL Native Driver ならその必要はありません。 すべてが標準の配布ファイルに組み込まれているからです。 PHP をビルドしたり PHP のアプリケーションを動かしたりするときに、 MySQL をインストールする必要がなくなったのです。

MySQL Native Driver は PHP の拡張モジュールとして作られているので、 PHP 本体の動作と密につながっています。つまり、 特にメモリ管理などの点で効率があがります。 というのも、ドライバが PHP のメモリ管理システムを使えるからです。 また、PHP のメモリ制限もサポートします。 MySQL Native Driver を使うと MySQL Client Library と同等あるいはそれを上回るパフォーマンスを得られますが、 メモリの使い方はずっと効率的です。その一例をあげましょう。 MySQL Client Library を使うと各行がメモリに二度格納されることになりますが、 MySQL Native Driver の場合は各行がメモリに格納されるのは一度だけです。

注意: メモリ使用量の報告

MySQL Native Driver は PHP のメモリ管理システムを使っているので、 そのメモリ使用量を memory_get_usage() で追えます。 これは libmysqlclient では不可能なことです。なぜなら libmysqlclient は C の malloc() 関数を使っているからです。

おすすめ機能

MySQL Native Driver には、それ特有の機能もあります。 以下にまとめるこれらの機能は、MySQL Client Library を使った MySQL データベース用の拡張モジュールでは利用できないものです。

  • 持続的接続の改善

  • mysqli_fetch_all() 関数

  • パフォーマンス統計用の関数 mysqli_get_client_stats()、 mysqli_get_connection_stats()

パフォーマンス統計機能を活用すれば、 パフォーマンス上のボトルネックを見つけるのに大いに役立つでしょう。

MySQL Native Driver を mysqli 拡張モジュールで使うと、持続的接続も可能です。

SSL サポート

MySQL Native Driver は、SSL をサポートしています。

圧縮プロトコルのサポート

MySQL Native Driver は、圧縮済みのクライアントサーバープロトコルをサポートします。 ext/mysql や ext/mysqli では、MySQL Native Driver を使うように設定すればこの機能を使えるようになります。 ただし、PDO_MYSQL については mysqlnd と組み合わせても圧縮機能が使えないことに注意しましょう。

名前付きパイプのサポート

Windows では、接続に名前付きパイプが使えます。


インストール

Unix へのインストール

MySQL Native Driver を使うには、MySQL データベース拡張モジュールを MySQL Native Driver のサポート付でコンパイルすることを指定して PHP をビルドする必要があります。 これは、PHP のソースコードをビルドする前に、設定オプションを通じて行なわれます。

例えば MySQL Native Driver を用いて、 MySQL 拡張モジュール mysqli と、 PDO MYSQL をビルドするには、以下のコマンドを使います。

./configure --with-mysql=mysqlnd \
--with-mysqli=mysqlnd \
--with-pdo-mysql=mysqlnd \
[other options]

Windows へのインストール

公式な Windows 版の PHP では、 MySQL Native Driver がデフォルトで使用可能です。 そのため、使用するための追加の構成は不要です。 この場合は MySQLデータベース拡張モジュールは全て MySQL Native Driver を使用します。

SHA-256 認証プラグインのサポート

MySQL Native Driver で MySQL SHA-256 認証プラグインを使ったアカウントによる MySQL への接続をするには、PHP の OpenSSL 機能を組み込んで有効にしておく必要があります。 たとえば、PHP を次のような設定でビルドします。

./configure --with-mysql=mysqlnd \
--with-mysqli=mysqlnd \
--with-pdo-mysql=mysqlnd \
--with-openssl
[その他のオプション]


実行時設定

php.ini の設定により動作が変化します。

MySQL Native Driver 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mysqlnd.collect_statistics | "1" | INI_SYSTEM |
mysqlnd.collect_memory_statistics | "0" | INI_SYSTEM |
mysqlnd.debug | "" | INI_SYSTEM |
mysqlnd.log_mask | 0 | INI_ALL |
mysqlnd.mempool_default_size | 16000 | INI_ALL |
mysqlnd.net_read_timeout | "86400" | INI_ALL | PHP 7.2.0 より前のバージョンでは、 デフォルト値は "31536000" で、変更可能な範囲が INI_SYSTEM でした。
mysqlnd.net_cmd_buffer_size | "4096" | INI_SYSTEM |
mysqlnd.net_read_buffer_size | "32768" | INI_SYSTEM |
mysqlnd.sha256_server_public_key | "" | INI_PERDIR |
mysqlnd.trace_alloc | "" | INI_SYSTEM |
mysqlnd.fetch_data_copy | 0 | INI_ALL | PHP 8.1.0 で削除されました。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mysqlnd.collect_statistics bool

さまざまなクライアント統計情報の収集を有効にします。収集した情報には
mysqli_get_client_stats() や
mysqli_get_connection_stats() でアクセスでき、
phpinfo() 関数の出力の
mysqlnd セクションにも表示されます。

この設定項目は、メモリ管理に関するもの以外のすべての MySQL Native Driver 統計情報 を有効にします。

mysqlnd.collect_memory_statistics bool

さまざまなメモリ統計情報の収集を有効にします。収集した情報には
mysqli_get_client_stats() や
mysqli_get_connection_stats() でアクセスでき、
phpinfo() 関数の出力の
mysqlnd セクションにも表示されます。

この設定項目は、MySQL Native Driver 統計情報 全体の中でメモリ管理に関する統計を有効にします。

mysqlnd.debug string

mysqlnd を使うすべての拡張モジュールからの通信を、指定したログファイルに記録します。

この項目の書式は mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]" となります。

書式文字列のオプションは、次のとおりです。

  • A[,file] - トレース出力を指定したファイルに追記します。 また、データの追記はデータベースへの書き込みのたびに発生することを保証します。 それを実現するために、トレースファイルをいったん閉じてから開きなおします (速度は遅くなります)。 これで、アプリケーションがクラッシュしたときにも完全なログファイルを残せます。

  • a[,file] - トレース出力を指定したファイルに追記します。

  • d - DBUG_<N> マクロからの、現在の状態に関する出力を有効にします。 キーワードのリストが後に続くことがあり、その場合は 指定したキーワードの DBUG マクロからだけ出力させます。 空のキーワードリストを指定すると、すべてのマクロを出力します。

  • f[,functions] - デバッガの動作を、リストで指定した関数だけに絞り込みます。 空の関数リストを指定すると、すべての関数を選択したことになります。

  • F - デバッガからの出力の各行に、その出力の元となったマクロが含まれるソースファイル名を付加します。

  • i - デバッガからの出力の各行に、現在のプロセスの PID を付加します。

  • L - デバッガからの出力の各行に、その出力の元となったマクロが含まれるソースファイル内の行番号を付加します。

  • n - デバッガからの出力の各行に、現在の関数のネストレベルを付加します。

  • o[,file] - a[,file] と似ていますが、既存のファイルに追記するのではなく既存のファイルを上書きします。

  • O[,file] - A[,file] と似ていますが、既存のファイルに追記するのではなく既存のファイルを上書きします。

  • t[,N] - 関数の制御フローのトレースを有効にします。最大のネストレベルを N で指定します。 N のデフォルトは 200 です。

  • x - このオプションはプロファイリングを有効にします。

  • m - 呼び出しに関連する、メモリの確保と解放をトレースします。

利用例は、このようになります。

d:t:x:O,/tmp/mysqlnd.trace

注意:

この機能は、デバッグビルド版の PHP でしか使えません。 Microsoft Windows で使う場合は、Microsoft Visual C バージョン 9 以降でデバッグビルドした PHP を使わなければなりません。

mysqlnd.log_mask int

どのクエリをログに記録するかを定義します。デフォルトは 0 で、これはクエリをログに記録しません。 値は静数値で定義します。PHP の定数はありません。 たとえば 48 (16 + 32) を設定すると、インデックスの選択が悪かったり (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) まったくインデックスを使っていなかったり (SERVER_QUERY_NO_INDEX_USED = 32) といった理由で遅くなっているクエリをログに記録します。 2043 (1 + 2 + 8 + ... + 1024) を指定すると、あらゆる型の遅いクエリを記録します。

使える型は、次のとおりです。
SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2,
SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32,
SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256,
SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, SERVER_QUERY_WAS_SLOW=1024

mysqlnd.mempool_default_size int

mysqlnd メモリプールのデフォルトサイズ。これは結果セットが使います。

mysqlnd.net_read_timeout int

mysqlnd は、MySQL Client Library すなわち libmysqlclient とは異なるネットワーク API を使います。 mysqlnd は PHP ストリームを使いますが、 libmysqlclient は自前のラッパーを用意して操作レベルでのネットワークコールをしています。 PHP のデフォルト設定では、ストリームの読み込みタイムアウトは 60 秒です。これは php.ini の default_socket_timeout で設定します。 タイムアウト値を設定しなければ、すべてのストリームに対してデフォルト値が適用されます。 mysqlnd は何も値を設定しないので、長いクエリを実行して default_socket_timeout 秒が経過すると、接続を切断して 2006 - MySQL Server has gone away というエラーが発生します。 MySQL Client Library のデフォルトのタイムアウトは 24 * 3600 秒 (1 日) で、TCP/IP のタイムアウトなどのその他のタイムアウトが発生するのを待ちます。 mysqlnd も同様に、非常に長いタイムアウトを使うことができます。この値は、 php.ini の新しい項目 mysqlnd.net_read_timeout で設定します。 mysqlnd.net_read_timeout は、mysqlnd を使うすべての拡張モジュール (ext/mysql や ext/mysqli、PDO_MySQL) が利用します。 mysqlnd は、PHP ストリームに対して mysqlnd.net_read_timeout を使うよう指示します。 MySQL Client Library および PHP ストリームの MYSQL_OPT_READ_TIMEOUT とは微妙に違いがあることに注意しましょう。 MYSQL_OPT_READ_TIMEOUT は TCP/IP 接続でしか動作しないとドキュメントに記載されており、 MySQL 5.1.2 より前のバージョンでは Windows でしか使えません。 PHP ストリームにはこの制限はありません。 信じられないならストリームのドキュメントを調べるとよいでしょう。

mysqlnd.net_cmd_buffer_size int

mysqlnd は、内部のコマンド/ネットワークバッファとして php.ini の mysqlnd.net_cmd_buffer_size で指定しただけのバイト数をすべての接続に対して確保します。 MySQL Client Server プロトコルのコマンド、たとえば COM_QUERY (通常のクエリ) がこのバッファに収まらない場合、mysqlnd はコマンドの送信に必要なだけバッファを拡張します。 ひとつの接続でバッファの拡張が発生するたびに command_buffer_too_small をひとつ加算します。

ほとんどすべての接続で mysqlnd が mysqlnd.net_cmd_buffer_size の初期値よりバッファを拡張せざるを得なくなったら、 デフォルトのサイズを大きくしてバッファの再割り当てを回避すべきでしょう。

デフォルトのバッファサイズは 4096 バイトです。これは、設定可能な最小値です。

この値は mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size) でも変更できます。

mysqlnd.net_read_buffer_size int

MySQL コマンドパケットのボディを読み込むときの、読み込みチャンクの最大バイト数。 MySQL クライアントサーバープロトコルは、すべてのコマンドをパケット内にカプセル化します。 パケットは、小さなヘッダと実際の本体を含むボディで構成されています。 ボディのサイズはヘッダに書き込まれています。 mysqlnd はこのボディを、 MIN(header.size, mysqlnd.net_read_buffer_size) バイトごとに分割して読み込みます。パケットのボディが mysqlnd.net_read_buffer_size バイトより長い場合は、 mysqlnd は read() を複数回コールする必要があります。

この値は mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size) でも設定できます。

mysqlnd.sha256_server_public_key string

SHA-256 認証プラグイン関連の設定。MySQL サーバーの RSA 公開鍵ファイル。

クライアントで RSA 公開鍵の設定をせずに済ませることができます。 そのためには、この設定項目で公開鍵を設定するか、実行時に mysqli_options() で鍵を指定します。 RSA 公開鍵をクライアントから渡さなかった場合は、 ここで指定した鍵を使って SHA-256 認証プラグインの認証手続きを進めます。

mysqlnd.trace_alloc string

mysqlnd.fetch_data_copy int

デフォルトの参照とコピーオンライトのロジックを使わずに、 内部結果セットのバッファから PHP の変数に結果セットをコピーします。 詳細は メモリ管理の実装についての説明 を参照ください。

結果セットを PHP の変数から参照させるのではなくコピーすることで、 PHP の変数に割り当てたメモリを早めに解放できます。 ユーザー API のコードやクエリの内容、そして結果セットの大きさにも依存しますが、 これは mysqlnd のメモリ使用量の削減につながります。

PDO_MySQL を使う場合は設定しないでください。PDO_MySQL は、まだこの新しいフェッチモードに対応していません。

注意: この設定は、PHP 8.1.0 で削除されました。


非互換性

MySQL Native Driver は、MySQL Client Library (libmysql) とほぼ互換性があります。 このセクションでは、互換性のない部分について説明します。

  • bit 型の値は、libmysql では二進文字列 ("\0" や "\x1F") として返しますが、mysqlnd の場合は十進文字列 ("0" や "31") として返します。どちらのライブラリでも同じように動くようにするには、 bit 型のフィールドを常に数値として返すようなクエリを書きましょう。たとえば SELECT bit + 0 FROM table のようにします。


持続的接続

持続的接続の使用

mysqli と mysqlnd の組み合わせで使っている場合は、 持続的接続を作るときにサーバー上で COM_CHANGE_USER (mysql_change_user()) を呼び出します。これで、接続の認証が再び行われることになります。

COM_CHANGE_USER の呼び出しと関連するオーバーヘッドが若干あるので、 コンパイル時にこれをオフにすることができます。 持続的接続を再利用すると、接続が再利用できるかどうか簡単にテストするために、 COM_PING (mysql_ping) の呼び出しが生成されます。

COM_CHANGE_USER を呼び出さないようにするには、コンパイルのときに MYSQLI_NO_CHANGE_USER_ON_PCONNECT フラグを使います。たとえば次のようになります。 例えば、

shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6

またはその代わりに、以下のようにします。

shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
shell# configure --whatever-option
shell# make clean
shell# make

mysqlnd 上の mysqli だけが COM_CHANGE_USER を使用することに注意してください。 他の拡張モジュールとドライバーの組み合わせでは、持続的な接続を最初に使用する際に、 COM_PING を使用します。


Statistics

MySQL Native Driver contains support for gathering statistics on the communication between the client and the server. The statistics gathered are of two main types:

  • Client statistics
  • Connection statistics

When using the mysqli extension, these statistics can be obtained through two API calls:

  • mysqli_get_client_stats()
  • mysqli_get_connection_stats()

注意: Statistics are aggregated among all extensions that use the MySQL Native Driver. For example, if the mysqli extension and the PDO MySQL driver are both set-up to use MySQLnd, then function calls from mysqli and method calls from PDO will affect the statistics. There is no way to find out how much a certain API call of any extension that has been compiled against MySQL Native Driver has impacted a certain statistic.

Retrieving statistics

Client statistics can be retrieved by calling the mysqli_get_client_stats() function.

Connection statistics can be retrieved by calling the mysqli_get_connection_stats() function.

Both functions return an associative array, where the name of a statistic is the key for the corresponding statistical data.

MySQL Native Driver Statistics

Most statistics are associated to a connection, but some are associated to the process in which case this will be mentioned.

The following statistics are produced by the MySQL Native Driver:

Network Related Statistics
bytes_sent
Number of bytes sent from PHP to the MySQL server.
bytes_received
Number of bytes received from the MySQL server.
packets_sent
Number of packets sent by the MySQL Client Server protocol.
packets_received
Number of packets received from the MySQL Client Server protocol.
protocol_overhead_in
MySQL Client Server protocol overhead in bytes for incoming traffic. Currently only the Packet Header (4 bytes) is considered as overhead. protocol_overhead_in = packets_received * 4
protocol_overhead_out
MySQL Client Server protocol overhead in bytes for outgoing traffic. Currently only the Packet Header (4 bytes) is considered as overhead. protocol_overhead_out = packets_received * 4
bytes_received_ok_packet
Total size of bytes of MySQL Client Server protocol OK packets received. OK packets can contain a status message. The length of the status message can vary and thus the size of an OK packet is not fixed.

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_ok
Number of MySQL Client Server protocol OK packets received.
bytes_received_eof_packet
Total size in bytes of MySQL Client Server protocol EOF packets received. EOF can vary in size depending on the server version. Also, EOF can transport an error message.

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_eof
Number of MySQL Client Server protocol EOF packets. Like with other packet statistics the number of packets will be increased even if PHP does not receive the expected packet but, for example, an error message.
bytes_received_rset_header_packet
Total size in bytes of MySQL Client Server protocol result set header packets. The size of the packets varies depending on the payload (LOAD LOCAL INFILE, INSERT, UPDATE, SELECT, error message).

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_rset_header
Number of MySQL Client Server protocol result set header packets.
bytes_received_rset_field_meta_packet
Total size in bytes of MySQL Client Server protocol result set metadata (field information) packets. Of course the size varies with the fields in the result set. The packet may also transport an error or an EOF packet in case of COM_LIST_FIELDS.

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_rset_field_meta
Number of MySQL Client Server protocol result set metadata (field information) packets.
bytes_received_rset_row_packet
Total size in bytes of MySQL Client Server protocol result set row data packets. The packet may also transport an error or an EOF packet. One can compute the number of error and EOF packets by subtracting rows_fetched_from_server_normal and rows_fetched_from_server_ps from bytes_received_rset_row_packet.

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_rset_row
Number of MySQL Client Server protocol result set row data packets.
bytes_received_prepare_response_packet
Total size in bytes of MySQL Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets). The packet may also transport an error. The packet size depends on the MySQL version.

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_prepare_response
Number of MySQL Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets).
bytes_received_change_user_packet
Total size in bytes of MySQL Client Server protocol COM_CHANGE_USER packets. The packet may also transport an error or EOF.

注意: The total size in bytes includes the size of the header packet (4 bytes, see protocol overhead).

packets_received_change_user
Number of MySQL Client Server protocol COM_CHANGE_USER packets.
packets_sent_command
Number of MySQL Client Server protocol commands sent from PHP to MySQL. There is no way to know which specific commands and how many of them have been sent.
bytes_received_real_data_normal
Number of bytes of payload fetched by the PHP client from mysqlnd using the text protocol. This is the size of the actual data contained in result sets that do not originate from prepared statements and which have been fetched by the PHP client. Note that although a full result set may have been pulled from MySQL by mysqlnd, this statistic only counts actual data pulled from mysqlnd by the PHP client.

An example of a code sequence that will increase the value is as follows:

$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->fetch_assoc();
$res->close();
Every fetch operation will increase the value.

However, the statistic will not be increased if the result set is only buffered on the client, but not fetched, such as in the following example:

$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->close();

bytes_received_real_data_ps
Number of bytes of the payload fetched by the PHP client from mysqlnd using the prepared statement protocol. This is the size of the actual data contained in result sets that originate from prepared statements and which have been fetched by the PHP client. The value will not be increased if the result set is not subsequently read by the PHP client. Note that although a full result set may have been pulled from MySQL by mysqlnd, this statistic only counts actual data pulled from mysqlnd by the PHP client. See also bytes_received_real_data_normal.
Result Set Related Statistics
result_set_queries
Number of queries that have generated a result set. Examples of queries that generate a result set: SELECT, SHOW. The statistic will not be incremented if there is an error reading the result set header packet from the line.

注意: This statistic can be used as an indirect measure for the number of queries PHP has sent to MySQL. This could help identifying a client that causes a high database load.

non_result_set_queries
Number of queries that did not generate a result set. Examples of queries that do not generate a result set: INSERT, UPDATE, LOAD DATA. The statistic will not be incremented if there is an error reading the result set header packet from the line.

注意: This statistic can be used as an indirect measure for the number of queries PHP has sent to MySQL. This could help identifying a client that causes a high database load.

no_index_used
Number of queries that have generated a result set but did not use an index. (See also the mysqld start option --log-queries-not-using-indexes).

注意: Those queries can be reported via an exception by calling mysqli_report(MYSQLI_REPORT_INDEX);. It is possible to have them be reported via a warning instead by calling mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);.

bad_index_used
Number of queries that have generated a result set and did not use a good index. (See also the mysqld start option --log-slow-queries).

注意: Those queries can be reported via an exception by calling mysqli_report(MYSQLI_REPORT_INDEX);. It is possible to have them be reported via a warning instead by calling mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);.

slow_queries
SQL statements that took more than long_query_time seconds to execute and required at least min_examined_row_limit rows to be examined.
警告

Not reported through mysqli_report().

buffered_sets
Number of buffered result sets returned by normal (i.e. not via a prepared statement) queries.

Examples of API calls that will buffer result sets on the client: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

unbuffered_sets
Number of unbuffered result sets returned by normal (i.e. not via a prepared statement) queries.

Examples of API calls that will not buffer result sets on the client: mysqli_use_result()

ps_buffered_sets
Number of buffered result sets returned by prepared statements.

Examples of API calls that will buffer result sets on the client: mysqli_stmt_store_result()

ps_unbuffered_sets
Number of unbuffered result sets returned by prepared statements. By default prepared statements are unbuffered, thus most prepared statements will be accounted in this statistic.
flushed_normal_sets
Number of result sets returned by normal (i.e. not via a prepared statement) queries with unread data that have been silently flushed.

注意: Flushing happens only with unbuffered result sets. Unbuffered result sets must be fetched completely before a new query can be run on the connection otherwise MySQL will throw an error. If the application does not fetch all rows from an unbuffered result set, mysqlnd does implicitly fetch the result set to clear the line. See also rows_skipped_normal, rows_skipped_ps.

Some possible causes for an implicit flush:

  • Faulty client application
  • Client stopped reading after it found what it was looking for but has made MySQL calculate more records than needed
  • Client application has stopped unexpectedly

flushed_ps_sets
Number of result sets from prepared statements with unread data that have been silently flushed.

注意: Flushing happens only with unbuffered result sets. Unbuffered result sets must be fetched completely before a new query can be run on the connection otherwise MySQL will throw an error. If the application does not fetch all rows from an unbuffered result set, mysqlnd does implicitly fetch the result set to clear the line. See also rows_skipped_normal, rows_skipped_ps.

Some possible causes for an implicit flush:

  • Faulty client application
  • Client stopped reading after it found what it was looking for but has made MySQL calculate more records than needed
  • Client application has stopped unexpectedly

ps_prepared_never_executed
Number of statements prepared but never executed.
ps_prepared_once_executed
Number of prepared statements executed only once.
rows_fetched_from_server_normal
rows_fetched_from_server_ps
Total number of result set rows fetched from the server. This includes the rows which were not read by the client but had been implicitly fetched due to flushed unbuffered result sets. See also packets_received_rset_row.
rows_buffered_from_client_normal
Total number of buffered rows originating from a normal query. This is the number of rows that have been fetched from MySQL and buffered on client.

Examples of queries that will buffer results:

  • mysqli_query()
  • mysqli_store_result()

rows_buffered_from_server_ps
Same as rows_buffered_from_client_normal but for prepared statements.
rows_fetched_from_client_normal_buffered
Total number of rows fetched by the client from a buffered result set created by a normal query.
rows_fetched_from_client_ps_buffered
Total number of rows fetched by the client from a buffered result set created by a prepared statement.
rows_fetched_from_client_normal_unbuffered
Total number of rows fetched by the client from an unbuffered result set created by a normal query.
rows_fetched_from_client_ps_unbuffered
Total number of rows fetched by the client from an unbuffered result set created by a prepared statement.
rows_fetched_from_client_ps_cursor
Total number of rows fetch by the client from a cursor created by a prepared statement.
rows_skipped_normal
rows_skipped_ps
Reserved for future use (currently not supported).
copy_on_write_saved
copy_on_write_performed
This is a process level scope statistic. With mysqlnd, variables returned by the extensions point into mysqlnd internal network result buffers. If the data are not changed, the fetched data is kept only once in memory. However, any modification to the data will require mysqlnd to perform a copy-on-write operation.
explicit_free_result
implicit_free_result
This is a connection and process level scope statistic. Total number of freed result sets.
proto_text_fetched_null
Total number of columns of type MYSQL_TYPE_NULL fetched from a normal query (MySQL text protocol).
proto_binary_fetched_null
Total number of columns of type MYSQL_TYPE_NULL fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_bit
Total number of columns of type MYSQL_TYPE_BIT fetched from a normal query (MySQL text protocol).
proto_binary_fetched_bit
Total number of columns of type MYSQL_TYPE_BIT fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_tinyint
Total number of columns of type MYSQL_TYPE_TINY fetched from a normal query (MySQL text protocol).
proto_binary_fetched_tinyint
Total number of columns of type MYSQL_TYPE_TINY fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_short
Total number of columns of type MYSQL_TYPE_SHORT fetched from a normal query (MySQL text protocol).
proto_binary_fetched_short
Total number of columns of type MYSQL_TYPE_SHORT fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_int24
Total number of columns of type MYSQL_TYPE_INT24 fetched from a normal query (MySQL text protocol).
proto_binary_fetched_int24
Total number of columns of type MYSQL_TYPE_INT24 fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_int
Total number of columns of type MYSQL_TYPE_LONG fetched from a normal query (MySQL text protocol).
proto_binary_fetched_int
Total number of columns of type MYSQL_TYPE_LONG fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_bigint
Total number of columns of type MYSQL_TYPE_LONGLONG fetched from a normal query (MySQL text protocol).
proto_binary_fetched_bigint
Total number of columns of type MYSQL_TYPE_LONGLONG fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_decimal
Total number of columns of type MYSQL_TYPE_DECIMAL, or MYSQL_TYPE_NEWDECIMAL fetched from a normal query (MySQL text protocol).
proto_binary_fetched_decimal
Total number of columns of type MYSQL_TYPE_DECIMAL, or MYSQL_TYPE_NEWDECIMAL fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_float
Total number of columns of type MYSQL_TYPE_FLOAT fetched from a normal query (MySQL text protocol).
proto_binary_fetched_float
Total number of columns of type MYSQL_TYPE_FLOAT fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_double
Total number of columns of type MYSQL_TYPE_DOUBLE fetched from a normal query (MySQL text protocol).
proto_binary_fetched_double
Total number of columns of type MYSQL_TYPE_DOUBLE fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_date
Total number of columns of type MYSQL_TYPE_DATE, or MYSQL_TYPE_NEWDATE fetched from a normal query (MySQL text protocol).
proto_binary_fetched_date
Total number of columns of type MYSQL_TYPE_DATE, or MYSQL_TYPE_NEWDATE fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_year
Total number of columns of type MYSQL_TYPE_YEAR fetched from a normal query (MySQL text protocol).
proto_binary_fetched_year
Total number of columns of type MYSQL_TYPE_YEAR fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_time
Total number of columns of type MYSQL_TYPE_TIME fetched from a normal query (MySQL text protocol).
proto_binary_fetched_time
Total number of columns of type MYSQL_TYPE_TIME fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_datetime
Total number of columns of type MYSQL_TYPE_DATETIME fetched from a normal query (MySQL text protocol).
proto_binary_fetched_datetime
Total number of columns of type MYSQL_TYPE_DATETIME fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_timestamp
Total number of columns of type MYSQL_TYPE_TIMESTAMP fetched from a normal query (MySQL text protocol).
proto_binary_fetched_timestamp
Total number of columns of type MYSQL_TYPE_TIMESTAMP fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_string
Total number of columns of type MYSQL_TYPE_STRING, MYSQL_TYPE_VARSTRING, or MYSQL_TYPE_VARCHAR fetched from a normal query (MySQL text protocol).
proto_binary_fetched_string
Total number of columns of type MYSQL_TYPE_STRING, MYSQL_TYPE_VARSTRING, or MYSQL_TYPE_VARCHAR fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_blob
Total number of columns of type MYSQL_TYPE_TINY_BLOB, MYSQL_TYPE_MEDIUM_BLOB, MYSQL_TYPE_LONG_BLOB, or MYSQL_TYPE_BLOB fetched from a normal query (MySQL text protocol).
proto_binary_fetched_blob
Total number of columns of type MYSQL_TYPE_TINY_BLOB, MYSQL_TYPE_MEDIUM_BLOB, MYSQL_TYPE_LONG_BLOB, or MYSQL_TYPE_BLOB fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_enum
Total number of columns of type MYSQL_TYPE_ENUM fetched from a normal query (MySQL text protocol).
proto_binary_fetched_enum
Total number of columns of type MYSQL_TYPE_ENUM fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_set
Total number of columns of type MYSQL_TYPE_SET fetched from a normal query (MySQL text protocol).
proto_binary_fetched_set
Total number of columns of type MYSQL_TYPE_SET fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_geometry
Total number of columns of type MYSQL_TYPE_GEOMETRY fetched from a normal query (MySQL text protocol).
proto_binary_fetched_geometry
Total number of columns of type MYSQL_TYPE_GEOMETRY fetched from a prepared statement (MySQL binary protocol).
proto_text_fetched_other
Total number of columns of types MYSQL_TYPE_* not listed previously fetched from a normal query (MySQL text protocol).

注意: In theory, this should always be 0.

proto_binary_fetched_other
Total number of columns of type MYSQL_TYPE_* not listed previously fetched from a prepared statement (MySQL binary protocol).

注意: In theory, this should always be 0.

Connection Related Statistics
connect_success
Total number of successful connection attempts.

注意: connect_success holds the sum of successful persistent and non-persistent connection attempts. Therefore, the number of successful non-persistent connection attempts is connect_success - pconnect_success.

pconnect_success
Total number of successful persistent connection attempts.
connect_failure
Total number of failed connection attempts.
reconnect
This is a process level scope statistic.
active_connections
This is a process level scope statistic. Total number of active persistent and non-persistent connections.

注意: The total number of active non-persistent connections is active_connections - active_persistent_connections.

active_persistent_connections
This is a process level scope statistic. Total number of active persistent connections.
explicit_close
Total number of explicitly closed connections.

例1 Examples of code snippets that cause an explicit close

  • $link = new mysqli(/* ... */);
$link->close(/* ... */);

  • $link = new mysqli(/* ... */);
$link->connect(/* ... */);
implicit_close
Total number of implicitly closed connections.

例2 Examples of code snippets that cause an implicit close

  • $link = new mysqli(/* ... */);
$link->real_connect(/* ... */);
  • unset($link)
  • Persistent connection: pooled connection has been created with real_connect and there may be unknown options set - close implicitly to avoid returning a connection with unknown options
  • Persistent connection: ping/change_user fails and ext/mysqli closes the connection
  • End of script execution: close connections that have not been closed by the user
disconnect_close
Connection failures indicated by the C API call mysql_real_connect during an attempt to establish a connection.
in_middle_of_command_close
This is a process level scope statistic. A connection has been closed in the middle of a command execution (outstanding result sets not fetched, after sending a query and before retrieving an answer, while fetching data, while transferring data with LOAD DATA).
警告

Unless asynchronous queries are used, this should only happen if the PHP application terminated unexpectedly, and PHP shuts down the connection automatically.

init_command_executed_count
Total number of init command executions. For example: mysqli_options(MYSQLI_INIT_COMMAND , $value). The number of successful executions is init_command_executed_count - init_command_failed_count.
init_command_failed_count
Total number of failed init commands.
COM_* Command Related Statistics
com_quit
com_init_db
com_query
com_field_list
com_create_db
com_drop_db
com_refresh
com_shutdown
com_statistics
com_process_info
com_connect
com_process_kill
com_debug
com_ping
com_time
com_delayed_insert
com_change_user
com_binlog_dump
com_table_dump
com_connect_out
com_register_slave
com_stmt_prepare
com_stmt_execute
com_stmt_send_long_data
com_stmt_close
com_stmt_reset
com_stmt_set_option
com_stmt_fetch
com_daemon
Total number of attempts to send a certain COM_* command from PHP to MySQL. The statistics are incremented after checking the line and immediately before sending the corresponding MySQL client server protocol packet.
警告

If MySQLnd fails to send the packet over the wire the statistics will not be decremented. In case of a failure MySQLnd emits a PHP warning Error while sending %s packet. PID=%d.

例3 Usage examples

  • Check if PHP sends certain commands to MySQL, for example, check if a client sends COM_PROCESS_KILL

  • Calculate the average number of prepared statement executions by comparing COM_EXECUTE with COM_PREPARE

  • Check if PHP has run any non-prepared SQL statements by checking if COM_QUERY is zero

  • Identify PHP scripts that run an excessive number of SQL statements by checking COM_QUERY and COM_EXECUTE

Miscellaneous Statistics
explicit_stmt_close
implicit_stmt_close
This is a process level scope statistic. Total number of closed prepared statements.

注意: A prepared statement is always explicitly closed. The only time it's closed implicitly is when preparing it fails.

mem_emalloc_count
mem_emalloc_ammount
mem_ecalloc_count
mem_ecalloc_ammount
mem_realloc_count
mem_realloc_ammount
mem_efree_count
mem_malloc_count
mem_malloc_ammount
mem_calloc_count
mem_calloc_ammount
mem_ealloc_count
mem_ealloc_ammount
mem_free_count
This is a process level scope statistic. Memory management calls.
command_buffer_too_small
Number of network command buffer extensions while sending commands from PHP to MySQL. MySQLnd allocates an internal command/network buffer of mysqlnd.net_cmd_buffer_size bytes for every connection. If a MySQL Client Server protocol command, e.g. COM_QUERY (normal query), does not fit into the buffer, MySQLnd will grow the buffer to what is needed for sending the command. Whenever the buffer gets extended for one connection command_buffer_too_small will be incremented by one. If MySQLnd has to grow the buffer beyond its initial size of mysqlnd.net_cmd_buffer_size bytes for almost every connection, considerations to increase the default size should be made to avoid re-allocations.
connection_reused
The total number of times a persistent connection has been reused.


メモ

このセクションでは、MySQL Native Driver の使い方についての様々なメモをまとめます。

  • mysqlnd を使うということは、 そのベースとして PHP のストリームを使って接続するということです。 mysqlnd のタイムアウト設定などの詳細に関しては、 MySQL Client Library のマニュアルではなく、 PHP のストリームのマニュアル (ストリーム) を参照しなければいけません。


メモリ管理

はじめに

MySQL Native Driver は、MySQL Client Library とは異なるやり方でメモリを管理します。 メモリを確保し、解放するやり方が異なります。 つまり、MySQL から結果を読み取る際にメモリをチャンクで確保するやり方や、 デバッグや開発時のオプションが存在するかどうかや、 MySQL から結果を読み取り、PHP の変数に結びつけるやり方が違うということです。

以下の説明では、 C言語のコードレベルで MySQL Native Driver を理解することに関心があるユーザ向けに、メモリ管理の紹介とまとめを示します。

利用するメモリ管理関数

メモリの確保や解放は、 PHP のメモリ管理関数を使って行います。 よって、mysqlnd のメモリ消費量は、 memory_get_usage() のような PHP の API をコールすることで追跡できます。 PHP のメモリ管理機構を使ってメモリが確保され、かつ解放されるので、 メモリを変更してもオペレーティングシステムからはすぐに見えない可能性があります。 PHP のメモリ管理の仕組みは、プロキシとして振る舞うため、 システムのメモリの解放が遅延する可能性があります。 よって、MySQL Native Driver と MySQL Client Library のメモリ利用状況を比較することは困難です。 MySQL Client Library はオペレーティングシステムのメモリ管理機構を直接コールするので、 オペレーティングシステムからメモリへの変更が直接見えるからです。

PHP によって強制されるあらゆるメモリに対する制限が、 MySQL Native Driver にも影響します。 このため、 PHP が利用できるメモリの残量を超える大きな結果セットを取得しようとした場合に、 メモリ不足エラーが発生する可能性があります。 MySQL Client Library は PHP のメモリ管理関数を使っていないため、 PHP のメモリ制限に従いません。 MySQL Client Library を使っている場合、 PHP の配置の仕方によっては、 PHP プロセスのメモリのフットプリントが PHP のメモリ制限を超えるかもしれません。 しかしながら、PHP エンジンの制御を超えた結果セット分のメモリを確保するため、 PHP スクリプトも大きな結果セットを扱える可能性があります。

PHP のメモリ管理関数は、薄いラッパーを通じて MySQL Native Driver からコールされます。ラッパーによって、デバッグが容易になります。

結果セットの処理

様々な MySQL サーバー と クライアントAPI が、 結果セットを バッファリングするかしないか という点で違いがあります。 結果セットをバッファリングしない場合、 結果セットは一行ずつ MySQL からクライアントに送られ、 クライアントはそれらの結果を走査します。 結果セットをバッファリングした場合、 クライアントライブラリが結果全体を取得し、それらをクライアントに渡します。

MySQL Native Driver は、 MySQL とのネットワーク通信のために PHP ストリームを使います。 MySQL が送信した結果セットは、 PHP ストリームのネットワークバッファから取得され、 mysqlnd の結果バッファに格納されます。 結果セットは zval で構築されます。 次のステップとして、結果セットが PHP スクリプトから利用できるようになります。 結果セットのバッファから PHP の変数に転送される最後のタイミングがメモリ消費量に影響し、 結果セットをバッファリングした場合にほとんどの違いが出る部分です。

デフォルトでは、MySQL Native Driver はバッファリング済みの結果セットをメモリに2度保持するのを避けようとします。 結果は内部的な結果バッファと zval に一度だけ保持されます。 PHP スクリプトによって 結果が PHP の変数に転送される際、 PHP の変数は内部的な結果バッファを参照しています。 データベースへの問い合わせ結果はコピーされることなく、 メモリ上に一度だけ保持されます。 ユーザーがデータベースへの問い合わせ結果を保持する変数を変更する際は、 内部的な結果バッファが変更されるのを避けるため、 コピーオンライトが実行されるはずです。 バッファの内容を変更してはいけません。なぜなら、 ユーザーが結果セットを再度読み取るかもしれないからです。 コピーオンライトの仕組みは、追加の参照リストを管理する仕組みと、 zval 標準のリファレンスカウンタを使って実装されています。 コピーオンライトは、ユーザーが結果セットを PHP の変数を読み取る際と、 変数を unset する前に結果セットを解放する前に行わなければいけません。

一般的に、 このパターンは PHP スクリプトが結果セットを一度だけ読み取り、 保持している結果の変数を変更しない場合にうまくいきます。 このパターンの一番の欠点は、mysqlnd の参照管理の仕組みがその変数を参照するのをやめるまで、保持している結果全体を解放できないことから、 追加の参照管理のためにメモリへのオーバーヘッドが増えることです。 MySQL Native Driver は、結果が解放されたりコピーオンライトが実行された場合にユーザー変数への参照を削除します。 メモリ使用量を観察していると、結果セットが開放されるまで使用量が増えることがわかるでしょう。 PHPスクリプト が結果セットを明示的に解放しているかどうかや、 ドライバが暗黙のうちに解放しているためにメモリが必要以上に長く使われていないかを調べるのに、統計情報 を使いましょう。 統計情報を見ると、コピーオンライトが何回行われているかを調べるのにも役立ちます。

while ($row = $res->fetch_assoc()) { ... } と同じ意味のコードを使い、 バッファリング済みの結果セットから小さな行をたくさん読み取っている場合、 参照ではなくコピーを要求することでメモリ使用量を最適化できるかもしれません。 コピーを要求するということは、 結果を二回メモリに格納するということではありますが、 結果セットを走査し、結果セットそれ自体を解放する前の $row のコピーを PHP が解放できるからです。 サーバーが高負荷の場合は、 ピーク時のメモリ使用量を最適化することでシステム全体のパフォーマンスを改善できるかもしれません。 但し、個別のスクリプトがコピーするアプローチは、 追加のメモリ確保やメモリコピーの操作によって速度が落ちる可能性があります。

メモリのモニタリングとデバッグ

MySQL Native Driver のメモリ使用状況を追跡する方法は複数あります。 高レベルの使用状況の概要をすばやく取得したり、 PHP スクリプトの効率性を検証するのが目的な場合は、 ライブラリが収集する 統計情報 をチェックしましょう。 統計情報を使うと、 たとえば PHPスクリプトが処理する以上の結果を生成する SQL文 を見つけたりできます。

メモリ管理機構の呼び出しを記録するために、 debug トレースログを設定できます。 これを使うと、 メモリがいつ確保されたり、解放されたりしているかがわかります。 しかし、リクエストされたメモリのチャンクのサイズはわからないかもしれません。

MySQL Native Driver の最近のバージョンによっては、 メモリ不足の状況をランダムにエミュレートする機能があります。 この機能は、C言語を使うライブラリの開発者や、 mysqlnd プラグイン を書く人だけが使うものです。 詳細については、 対応する PHP 設定のソースコードを検索して下さい。 この機能は外部に公開されていないため、 事前に警告することなく変更される可能性があります。


MySQL Native Driver プラグインAPI

目次

  • mysqlndプラグイン と MySQL Proxyの比較
  • mysqlnd plugin APIを取得する
  • MySQL Native Driverプラグイン のアーキテクチャ
  • mysqlnd のプラグインAPI
  • mysqlndプラグインの開発をはじめよう

The MySQL Native Driver プラグインAPI は MySQL Native Driver、略して mysqlnd が持つ機能の一つです。mysqlnd プラグインは、PHPアプリケーションと MySQL サーバーの間にあるレイヤで動きます。これは MySQL Proxy と比較できます。MySQL Proxy はあらゆる MySQL クライアントアプリケーション、たとえば PHPアプリケーション と MySQL サーバーの間のレイヤで動きます。mysqlnd プラグインは典型的な MySQL Proxy のタスク、たとえばロードバランシングやモニタリング、パフォーマンスの最適化をこなせます。アーキテクチャや置かれる場所が異なるため、mysqlnd プラグインは MySQL Proxy が持ついくつかの欠点がありません。たとえば、プラグインを使えば、単一障害点が存在しませんし、専用のプロキシサーバーをデプロイする必要もありませんし、新しいプログラミング言語(Lua) を学ぶ必要もありません。

mysqlndプラグインは mysqlndの拡張と考えることができます。プラグインは 多くの mysqlnd 関数の制御を奪い取ることができます。mysqlnd 関数は ext/mysql や ext/mysqli、PDO_MYSQL のような PHP の MySQL拡張モジュールによって呼び出されます。その結果として、mysqlndプラグイン はクライアントアプリケーションからこれらの拡張モジュールへの呼び出しの制御をすべて奪うことができるのです。

内部的な mysqlnd 関数の呼び出しも制御を奪ったり、処理を置き換えたりすることができます。mysqlnd の内部的な関数テーブルを管理することに関しても全く制限がありません。ある mysqlnd 関数が mysqlnd を使う拡張モジュールによって呼び出される場合に、適切な mysqlndプラグインの適切な関数に処理を転送するようにセットアップすることが可能です。このように、mysqlnd の内部関数テーブルを管理できることで、プラグインの柔軟性が最大限に発揮できるのです。

mysqlndプラグインは、実際は mysqlnd のプラグインAPI (これは MySQL Native Driver, 略して mysqlnd に組み込まれています) を使い、C言語 で書かれた PHP拡張モジュール です。 プラグインは PHPアプリケーションに対して 100% 透過的です。つまり、プラグインがPHPアプリケーションとは異なるレイヤで動作するため、アプリケーションを変更する必要がないのです。mysqlndプラグイン は、mysqlnd のひとつ下のレイヤで動くと考えることができます。

mysqlndプラグインで実現可能なアプリケーションのリストをいくつか以下に示します

  • ロードバランシング

    • 読み取り/書き込み の分割。例として、PECL/mysqlnd_ms (Master Slave) が挙げられます。この 拡張モジュール は 読み取り/書き込み のクエリをレプリケーションのセットアップ向けに分割します。

    • フェイルオーバー

    • ラウンドロビン, 負荷が一番低いサーバーへの転送

  • サーバーの監視

    • クエリのロギング

    • クエリの分析

    • クエリの監査。例として、PECL/mysqlnd_sip (SQL Injection Protection) が挙げられます。この 拡張モジュール はクエリを調べ、ルールセットに従って許可されたクエリのみを実行します。

  • パフォーマンスの向上

    • キャッシュ。例として、PECL/mysqlnd_qc (Query Cache) が挙げられます。

    • トラフィックの調整

    • シャーディング。例として、PECL/mysqlnd_mc (Multi Connect) が挙げられます。この拡張モジュール は、SELECT ステートメントを SELECT ... LIMIT part1, SELECT LIMIT part_n という形でn個に分割します。そしてクエリを別々の MySQLサーバーに送り、結果をクライアント側でマージします。

利用可能な MySQL Native Driverプラグイン

既にたくさんの mysqlnd プラグインが利用可能になっています。以下が含まれます。

  • PECL/mysqlnd_mc - 複数接続ができるプラグイン

  • PECL/mysqlnd_ms - マスタースレーブ構成用のプラグイン

  • PECL/mysqlnd_qc - クエリキャッシュプラグイン

  • PECL/mysqlnd_pscache - プリペアドステートメントハンドルをキャッシュするプラグイン

  • PECL/mysqlnd_sip - SQLインジェクションから防御するためのプラグイン

  • PECL/mysqlnd_uh - ユーザーハンドラープラグイン


mysqlndプラグイン と MySQL Proxyの比較

mysqlndプラグインと MySQL Proxyは、異なるアプローチを用いた異なる技術です。どちらもロードバランシングや監視、パフォーマンスの向上のような共通の様々な課題を解決するのに適したツールです。重要な違いは、MySQL Proxyがあらゆる MySQLクライアント と協調して動作するのに対して、mysqlndプラグインは PHPアプリケーション との協調動作に特化しているということです。

PHP拡張モジュールとして、mysqlndプラグイン はPHPの残りの部分とともに、PHPのアプリケーションサーバーにインストールされます。MySQL Proxy はPHPアプリケーションサーバー上でも動作しますし、複数のPHPアプリケーションサーバーを扱う専用マシンにもインストールできます。

MySQL Proxyをアプリケーションサーバーにデプロイすることにはふたつの利点があります:

  1. 単一障害点がありません

  2. スケールアウトしやすい (水平方向へのスケールアウト、クライアントによるスケーリング)

MySQL Proxy (と、mysqlndプラグイン) は、他のやり方だと既存のアプリケーションを変更しなければならない問題にも容易に対処することができます。

しかし、MySQL Proxyにはいくつか欠点があります:

  • MySQL Proxy のコンポーネントと技術について新たにマスターし、デプロイしなければなりません。

  • MySQL Proxy は Lua スクリプト言語の知識が必要です。

MySQL Proxy は C言語と プログラミング言語 Lua によってカスタマイズできます。Lua は MySQL Proxy において好ましいスクリプト言語です。ほとんどのPHPエキスパートにとって、Lua は新しく学ばなければならない言語です。mysqlndプラグインは C言語で書くことができます。» PECL/mysqlnd_uh を使って、プラグインを PHP で書くこともできます。

MySQL Proxy はデーモン - バックグラウンドのプロセスとして動作します。MySQL Proxy は初期の決定を取り消すこともできますが、すべての状態を保持することできます。しかしながら mysqlndプラグインは、PHPのリクエスト単位のライフサイクルに結びついています。MySQL Proxy は一度計算された結果を複数のアプリケーションサーバーで共有できます。mysqlndプラグインでこれを行うには、永続的なストレージにデータを保存する必要があります。この目的のためには Memcache のような別のデーモンが必要です。この場合は、MySQL Proxy に有利です。

MySQL Proxy は wire protocol (訳注：ネットワークを通じてデータを転送するプロトコル。» WikipediaでのWire Protocolの説明, » StackOverflow でのWire Protocolの説明) の上で動作します。MySQL Proxy を使うと、MySQLクライアントサーバープロトコルを解析し、リバースエンジニアリングしなければなりません。MySQL Proxy でできることは、通信プロトコルを管理することで達成できることに限られます。wire protocol が変更(滅多にありませんが)されると、MySQL Proxy のスクリプトも変更する必要があります。

mysqlndプラグインは C言語のAPI上で動作します。このAPIは libmysqlclientクライアント の動きをそのままコピーしています。この C言語のAPI は、 基本的に MySQLクライアントサーバープロトコル、時に wire protocol と呼ばれるもののラッパーです。開発者は C言語のAPI呼び出しの制御を奪うことができます。それゆえに、wire protocol レベルのプログラムに一切変更を加えることなく、すべてのPHP呼び出しをフックできるのです。

mysqlnd は wire protocol を実装しています。そのため、プラグインは通信プロトコルを解析し、リバースエンジニアリングし、管理できるばかりか、通信プロトコルを置き換えることだってできます。ただ、こんなことをする必要は通常ありません。

プラグインが 2つのレベル(C言語のAPI と wire protocol) を使って実装できるので、MySQL Proxy よりも大きな柔軟性を得られます。 mysqlndプラグインが C言語のAPI を使って実装されれば、wire protocol に対していかなる変更が行われても、プラグインへの変更は必要ありません。


mysqlnd plugin APIを取得する

mysqlndプラグインAPI は、MySQL Native Driver PHP拡張モジュールである ext/mysqlnd の一部です。2009年12月に mysqlndプラグインAPI の開発がスタートしました。これは PHP のソースリポジトリの一部として開発が進められ、git経由で公開されたり、ソースコードのスナップショットがダウンロード可能になっています。

プラグインの開発者は mysqlnd のバージョンを MYSQLND_VERSION にアクセスすることで決めることができます。この値は、mysqlnd 5.0.7-dev - 091210 - $Revision: 300535 という文字列フォーマットです。MYSQLND_VERSION_ID という値にもアクセスできます。これはたとえば、50007 のような数値です。 開発者は次のようにしてバージョン番号を計算することができます:

MYSQLND_VERSION_ID 計算テーブル
Version (一部) | 例
Major*10000 | 5*10000 = 50000
Minor*100 | 0*100 = 0
Patch | 7 = 7
MYSQLND_VERSION_ID | 50007

開発している間は、開発者は mysqlnd のバージョン番号を互換性と対応バージョンのテストとして参照すべきです。PHP本体のひとつのバージョンにおける開発のライフサイクルの間に、mysqlnd の開発イテレーションは複数行われる場合があるためです。


MySQL Native Driverプラグイン のアーキテクチャ

このセクションでは、mysqlndプラグイン のアーキテクチャについての概要を示します。

MySQL Native Driver の概要

mysqlndプラグイン を開発する前に、mysqlnd そのものがどのように成り立っているのかを少し知っておくと役に立ちます。mysqlnd は次に示すモジュールからなります:

mysqlnd のモジュール毎のソースコードの組み合わせを示した表
モジュールの統計情報 | mysqlnd_statistics.c
データベース接続 | mysqlnd.c
結果セット | mysqlnd_result.c
結果セットのメタデータ | mysqlnd_result_meta.c
プリペアドステートメント | mysqlnd_ps.c
ネットワーク | mysqlnd_net.c
Wire protocol | mysqlnd_wireprotocol.c

C言語のオブジェクト指向パラダイム

ソースコードレベルで、mysqlnd は オブジェクト指向を実装するためのパターンを採用しています。

C言語では、オブジェクトを表現するために struct(構造体) を使います。struct のメンバがオブジェクトのプロパティを表現します。関数を指している struct のメンバがメソッドを表現します。

C++ や Java のような言語と異なり、C言語におけるオブジェクト指向のパラダイムでは決まった継承のルールがありませんが、従う必要があるルールがいくつかあります。このルールについては後に述べます。

PHP のライフサイクル

PHP のライフサイクルを考えるとき、ふたつの基本的なサイクルが存在します。

  • PHPエンジンの起動と終了までのサイクル

  • リクエスト毎のライフサイクル

PHPエンジンが起動するとき、PHP はモジュールを初期化する (MINIT) 関数を登録された拡張モジュールごとに呼び出します。これによって、各々のモジュールが PHPエンジンが処理を行うライフサイクルの間存在するリソースを割り当てたり、変数を定義することができます。PHPエンジンが終了するときには、 エンジンが終了(MSHUTDOWN)関数を拡張モジュール毎に呼び出します。

PHPエンジンが起動している間、エンジンはたくさんのリクエストを受けとります。それぞれのリクエストは別のライフサイクルを構成します。リクエスト毎にPHPエンジンはリクエストの初期化関数を拡張モジュール毎に呼び出します。拡張モジュール側では、リクエストの処理に必要な変数の定義やリソースの割り当てを行うことができます。リクエストのサイクルが終了するときは、PHPエンジンがリクエストの終了(RSHUTDOWN)関数を拡張モジュール毎に呼び出します。これによって、拡張モジュールは必要となるあらゆるクリーンアップ処理を行うことができます。

プラグインはどうやって動くか

mysqlndプラグイン は mysqlnd を使う拡張モジュールが mysqlnd を呼び出すときの制御を奪うことによって動作します。これは mysqlnd の関数テーブルを取得し、バックアップし、カスタムの関数テーブルと置き換えることによって実現されます。この関数テーブルが、プラグインが必要とする関数を呼び出すのです。

次のコードは、mysqlnd の関数テーブルを置き換える方法を示しています:

/* a place to store original function table */
struct st_mysqlnd_conn_methods org_methods;

void minit_register_hooks(TSRMLS_D) {
  /* active function table */
  struct st_mysqlnd_conn_methods * current_methods
    = mysqlnd_conn_get_methods();

  /* backup original function table */
  memcpy(&org_methods, current_methods,
    sizeof(struct st_mysqlnd_conn_methods);

  /* install new methods */
  current_methods->query = MYSQLND_METHOD(my_conn_class, query);
}

接続関数テーブルの管理は、モジュールを初期化(MINIT)している間に行わなければなりません。関数テーブルはグローバルに共有されるリソースです。マルチスレッド環境で、TSRMを有効にしてPHPをビルドした環境では、グローバルに共有されたリソースをリクエストを処理している間に操作すると、ほぼ確実に衝突が起こります。

注意:

mysqlnd の関数テーブルを管理するときに、固定サイズを割り当てるロジックは絶対に使わないでください。新しいメソッドが関数テーブルの最後に追加される可能性があるからです。関数テーブルは将来どんな場合でも変更される可能性があります。

親クラスのメソッドを呼び出す

オリジナルの関数テーブルをバックアップしている場合、オリジナルの関数テーブルのエントリに含まれる関数を呼び出すことができます - これが親メソッドです。

場合によっては、Connection::stmt_init() のように、派生メソッドで他のあらゆる処理より先に親メソッドを呼び出すことが決定的に重要な場合があります。

MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
  const char *query, unsigned int query_len TSRMLS_DC) {

  php_printf("my_conn_class::query(query = %s)\n", query);

  query = "SELECT 'query rewritten' FROM DUAL";
  query_len = strlen(query);

  return org_methods.query(conn, query, query_len); /* return with call to parent */
}

プロパティを拡張する

mysqlndオブジェクトは C言語の構造体で表現されます。実行時に、C言語の構造体に新たにメンバを追加することは不可能です。mysqlndオブジェクト のユーザーは、プロパティを単純にオブジェクトに追加することはできません。

mysqlnd_plugin_get_plugin_<object>_data()ファミリーの適切な関数を使って、任意のデータ (プロパティ) を mysqlnd オブジェクトに追加することができます。オブジェクトをメモリに割り付ける際に、mysqlnd はオブジェクトの最後に 任意のデータ向けの void * ポインタを保持するためのメモリ空間を予約しておきます。 mysqlnd は プラグインひとつにつき、ひとつの void *ポインタ を保持する空間を予約しています。

次の表で、特定のプラグインでポインタの位置を計算する方法を示します:

mysqlnd のポインタの位置を計算する方法
メモリアドレス | メモリの内容
0 | mysqlndオブジェクト を表現する構造体の開始
n | mysqlndオブジェクト を表現する構造体の終了
n + (m x sizeof(void*)) | m 番目のプラグインのオブジェクトデータを表現する void* ポインタ

mysqlndオブジェクト のコンストラクタを継承する計画がある場合、それが許可されていることを必ず頭にいれておいてください！

次のコードはプロパティを拡張する方法を示しています:

/* any data we want to associate */
typedef struct my_conn_properties {
  unsigned long query_counter;
} MY_CONN_PROPERTIES;

/* plugin id */
unsigned int my_plugin_id;

void minit_register_hooks(TSRMLS_D) {
  /* obtain unique plugin ID */
  my_plugin_id = mysqlnd_plugin_register();
  /* snip - see Extending Connection: methods */
}

static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
  MY_CONN_PROPERTIES** props;
  props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
    conn, my_plugin_id);
  if (!props || !(*props)) {
    *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
    (*props)->query_counter = 0;
  }
  return props;
}

プラグインの開発者には、プラグイン用のデータに使われるメモリを管理する責任があります。

mysqlnd のメモリアロケータを使うことを推奨します。これらのメモリアロケータ関数は次のような規約に従って命名されています: mnd_*loc() mysqlnd のメモリアロケーターには役に立つ機能がいくつかあります。たとえばデバッグビルドでない環境でデバッグ用のアロケータを使う機能などです。

いつ、どのように継承するか
 | いつ継承するか? | 各々のインスタンスが自分のプライベートな関数テーブルを持っているか? | どのように継承するか?
Connection (MYSQLND) | MINIT | No | mysqlnd_conn_get_methods()
Resultset (MYSQLND_RES) | MINIT (モジュール初期化) 時 またはその後 | Yes | mysqlnd_result_get_methods() または、オブジェクトのメソッド関数テーブルを変更する
Resultset Meta (MYSQLND_RES_METADATA) | MINIT (モジュール初期化) 時 | No | mysqlnd_result_metadata_get_methods()
Statement (MYSQLND_STMT) | MINIT (モジュール初期化) 時 | No | mysqlnd_stmt_get_methods()
Network (MYSQLND_NET) | MINIT (モジュール初期化) 時 またはその後 | Yes | mysqlnd_net_get_methods() または、オブジェクトのメソッド関数テーブルを変更する
Wire protocol (MYSQLND_PROTOCOL) | MINIT (モジュール初期化) 時 またはその後 | Yes | mysqlnd_protocol_get_methods() または、オブジェクトのメソッド関数テーブルを変更する

上記の表で許可されていない場合は、モジュールを初期化した(MINIT)後のいかなる場合であっても関数テーブルを変更してはいけません。

クラスによっては、メソッドの関数テーブルへのポインタが含まれている場合があります。このようなクラスのインスタンスはすべて、同じ関数テーブルを共有しています。混乱を避けるため、特にマルチスレッドの環境下では、このような関数テーブルは MINIT (モジュール初期化) 時にだけ変更するようにしてください。

そうでないクラスでは、グローバルに共有された関数テーブルのコピーを使っています。クラスの関数テーブルのコピーがオブジェクトとともに作成されます。それぞれのオブジェクトは自分の関数テーブルを使います。これによって開発者は二つの選択肢が得られます: MINIT(モジュール初期化) 時にオブジェクトのデフォルトの関数テーブルを変更するか、同じクラスの他のインスタンスに影響を与えることなくオブジェクトのメソッドを追加で変更することができます。

関数テーブルを共有する利点は、パフォーマンスの向上です。関数テーブルをそれぞれの、すべてのオブジェクトにコピーする必要がないからです。

コンストラクタの状態
メモリ割り当て、オブジェクトの生成、リセット | 変更可能か? | 呼び出し元
Connection (MYSQLND) | mysqlnd_init() | No | mysqlnd_connect()
Resultset(MYSQLND_RES)

メモリ割り当て:

  • Connection::result_init()

リセットし、再初期化されるタイミング:

  • Result::use_result()

  • Result::store_result

Yes, ただし親メソッドを呼び出すこと！

  • Connection::list_fields()

  • Statement::get_result()

  • Statement::prepare() (メタデータのみ)

  • Statement::resultMetaData()

Resultset Meta (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Yes, ただし親メソッドを呼び出すこと！ | Result::read_result_metadata()
Statement (MYSQLND_STMT) | Connection::stmt_init() | Yes, ただし親メソッドを呼び出すこと！ | Connection::stmt_init()
Network (MYSQLND_NET) | mysqlnd_net_init() | No | Connection::init()
Wire protocol (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | No | Connection::init()

コンストラクタを全面的に置き換えないことを強く推奨します。コンストラクタはメモリへの割り当てを実行します。mysqlndプラグインAPI と オブジェクトのロジックにとってメモリへの割り当ては決定的に重要です。開発者が警告を無視してコンストラクタへのフックを強行する場合、コンストラクタで何かをする前に親のコンストラクタを少なくとも呼び出すべきです。

すべての警告に関わらず、コンストラクタを継承することが役に立つ場合があります。コンストラクタは、オブジェクトの関数テーブルを共有されていないオブジェクトの関数テーブルと一緒に修正するのにぴったりな場所です。共有されていないオブジェクトの関数テーブルの例としては、結果セットやネットワーク、wire protocol が挙げられます。

オブジェクトの破棄に関する状態
Type | 継承したメソッドは親メソッドを呼ばねばならないか? | デストラクタ
Connection | Yes, メソッドの実行後に呼び出さなければなりません | free_contents(), end_psession()
Resultset | Yes, メソッドの実行後に呼び出さなければなりません | free_result()
Resultset Meta | Yes, メソッドの実行後に呼び出さなければなりません | free()
Statement | Yes, メソッドの実行後に呼び出さなければなりません | dtor(), free_stmt_content()
Network | Yes, メソッドの実行後に呼び出さなければなりません | free()
Wire protocol | Yes, メソッドの実行後に呼び出さなければなりません | free()

デストラクタは、mysqlnd_plugin_get_plugin_<object>_data() で取得したプロパティを破棄するのに適切な場所です。

ここで挙げたデストラクタは、オブジェクトそのものを破棄する 実際の mysqlnd メソッドと一致しないかもしれません。しかし、これらのデストラクタは、開発者がフックし、プラグインデータを解放する最良の場所なのです。コンストラクタに関しては、開発者がメソッドを完全に置き換えることができるものの、推奨されません。上の表に複数のメソッドが示されていた場合、mysqlnd がどのメソッドをはじめに呼び出したかに関わらず、開発者はここで示されているすべてのメソッドをフックし、プラグインのデータを解放する必要があります。

プラグインに推奨されるやり方は、単純にメソッドをフックし、メモリを解放した後に親クラスの実装を速やかに呼び出すことです。


mysqlnd のプラグインAPI

mysqlndプラグインAPI で提供されている関数のリストを以下に示します:

  • mysqlnd_plugin_register()

  • mysqlnd_plugin_count()

  • mysqlnd_plugin_get_plugin_connection_data()

  • mysqlnd_plugin_get_plugin_result_data()

  • mysqlnd_plugin_get_plugin_stmt_data()

  • mysqlnd_plugin_get_plugin_net_data()

  • mysqlnd_plugin_get_plugin_protocol_data()

  • mysqlnd_conn_get_methods()

  • mysqlnd_result_get_methods()

  • mysqlnd_result_meta_get_methods()

  • mysqlnd_stmt_get_methods()

  • mysqlnd_net_get_methods()

  • mysqlnd_protocol_get_methods()

プラグインが何かとか、どのようにプラグインが機能するのか、という疑問に対する公式な定義はありません。

プラグインのメカニズムでよく見つかるコンポーネントは以下の通りです:

  • プラグインマネージャー

  • プラグインAPI

  • アプリケーションサービス(またはモジュール)

  • アプリケーションサービスAPI (またはモジュールAPI)

mysqlndプラグインのコンセプトにはこれらが取り入れられており、追加でオープンなアーキテクチャの恩恵を受けています。

mysqlnd の内部には無制限にアクセスできる

プラグインは mysqlnd の内部にすべてアクセスできます。セキュリティ上の限界や制限はありません。mysqlnd に親和性が高い、または不利なアルゴリズムを実装するためにすべてを置き換えることができます。よって、信頼できる配布元からのプラグインだけをデプロイすることを推奨します。

以前議論したとおり、プラグインはポインタを自由に使えます。これらのポインタはあらゆる点で制限されていないので、別のプラグインのデータを指すこともできます。簡単にオフセットを計算するだけで別のプラグインのデータを使うことができます。

mysqlnd と協調的なプラグインを書くこと、そして開発者はいつも親メソッドを呼び出すことを推奨します。プラグインはいつも mysqlnd と協調的であるべきです。

問題: 呼び出しの連鎖と協調の例
拡張モジュール | mysqlnd.query() の関数ポインタ | 親メソッドを呼んだ場合のコールスタック
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache mysqlnd_cache.query()

  1. mysqlnd_cache.query()

  2. mysqlnd.query

ext/mysqlnd_monitor mysqlnd_monitor.query()

  1. mysqlnd_monitor.query()

  2. mysqlnd_cache.query()

  3. mysqlnd.query

このシナリオでは、キャッシュ(ext/mysqlnd_cache) と モニタ(ext/mysqlnd_monitor) プラグインが読み込まれています。両方とも Connection::query() を継承しています。プラグインの登録が 以前説明したロジックを使って MINIT(モジュール初期化) 時に発生します。PHP は拡張モジュールをデフォルトではアルファベット順に呼び出します。プラグインはお互いのことを知りませんし、拡張モジュールの依存性についても設定しません。

デフォルトで、プラグインは派生したメソッドの中で query メソッドの親クラスの実装を呼び出します。

PHP 拡張モジュールの動きを再現する

サンプルのプラグイン ext/mysqlnd_plugin を使うと何が起こるかを以下で再現します。このプラグインは、mysqlnd の CプラグインAPI をPHPに公開しています。

  • PHP で書かれた MySQL アプリケーションが 192.168.2.29 に接続を確立しようとします。

  • PHP アプリケーションは ext/mysql, ext/mysqli または PDO_MYSQL のいずれかを使うでしょう。これら３つの PHP MySQL 拡張モジュールは mysqlnd を使って 192.168.2.29 に接続を確立しようとします。

  • mysqlnd は ext/mysqlnd_plugin を継承した自分自身の connect メソッドを呼び出します。

  • ext/mysqlnd_plugin は ユーザーが登録した ユーザースペースのフックである proxy::connect() を呼び出します。

  • ユーザースペースのフックは接続先のホストIPアドレスを 192.168.2.29 から 127.0.0.1 に書き換え、parent::connect() によって確立された接続を返します。

  • ext/mysqlnd_plugin は オリジナルの mysqlndのメソッドを接続を確立するために呼び出します。これによって、parent::connect(127.0.0.1) を実行するのと同じことをします。

  • ext/mysqlnd は、接続を確立し、ext/mysqlnd_plugin に接続を返します。ext/mysqlnd_plugin も同じことをします。

  • どんな PHP MySQL 拡張モジュールをアプリケーションで使っていても、127.0.0.1 への接続を受け取ります。PHP MySQL 拡張モジュールそれ自体は、PHPアプリケーションにそれを返し、実行は終了します。


mysqlndプラグインの開発をはじめよう

mysqlndプラグイン それ自体が PHP拡張モジュール であることを覚えておくことが重要です。

次のコードは、典型的な mysqlnd プラグインで使われる MINIT 関数の基本構造を示します。

/* my_php_mysqlnd_plugin.c */

 static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
  /* globals, ini entries, resources, classes */

  /* register mysqlnd plugin */
  mysqlnd_plugin_id = mysqlnd_plugin_register();

  conn_m = mysqlnd_get_conn_methods();
  memcpy(org_conn_m, conn_m,
    sizeof(struct st_mysqlnd_conn_methods));

  conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
  conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
}

/* my_mysqlnd_plugin.c */

 enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
  /* ... */
}
enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
  /* ... */
}

タスクの解析: C言語からユーザースペースへ

 class proxy extends mysqlnd_plugin_connection {
  public function connect($host, ...) { .. }
}
mysqlnd_plugin_set_conn_proxy(new proxy());

プロセス:

  1. PHP: ユーザーがプラグインのコールバックを登録する

  2. PHP: ユーザーがMySQLに接続するため、任意の PHP MySQL API を呼び出す

  3. C: ext/*mysql* が mysqlnd のメソッドを呼び出す

  4. C: mysqlnd が ext/mysqlnd_plugin の中で終了する

  5. C: ext/mysqlnd_plugin

    1. ユーザースペースで登録されたコールバックを呼び出す

    2. また、ユーザースペースのコールバックが登録されていない場合は、mysqlnd のメソッドを呼び出す。

次のことを実行する必要があります:

  1. "mysqlnd_plugin_connection" というクラスを C言語で書く

  2. "mysqlnd_plugin_set_conn_proxy()" 関数を使って、プロキシオブジェクトを受け入れ、登録する

  3. C言語から、ユーザースペースへのプロキシメソッドを呼び出す (最適化 - zend_interface.h)

ユーザースペースのオブジェクトメソッドは、call_user_function() を使うか、zend_call_method() を使って Zend Engine に近いレベルで操作を行うことができます。

最適化: C言語から zend_call_method を使ってメソッドを呼び出す

次に示すコードの断片は、zend_call_method のプロトタイプを示しています。これは zend_interface.h からとってきたものです。

 ZEND_API zval* zend_call_method(
  zval **object_pp, zend_class_entry *obj_ce,
  zend_function **fn_proxy, char *function_name,
  int function_name_len, zval **retval_ptr_ptr,
  int param_count, zval* arg1, zval* arg2 TSRMLS_DC
);

Zend API は2つの引数しかサポートしていません。それ以上必要な場合は、たとえば次のようにします。

 enum_func_status (*func_mysqlnd_conn__connect)(
  MYSQLND *conn, const char *host,
  const char * user, const char * passwd,
  unsigned int passwd_len, const char * db,
  unsigned int db_len, unsigned int port,
  const char * socket, unsigned int mysql_flags TSRMLS_DC
);

この問題に対処するには、zend_call_method() のコピーを作り、追加の引数の入れ物を追加する必要があるでしょう。これは、MY_ZEND_CALL_METHOD_WRAPPER マクロの組を作ることで実現できます。

PHP のユーザースペースを呼び出す

以下のコードは、C言語からユーザースペースの関数を呼ぶための最適化されたやり方を示しています:

/* my_mysqlnd_plugin.c */

MYSQLND_METHOD(my_conn_class,connect)(
  MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {
  enum_func_status ret = FAIL;
  zval * global_user_conn_proxy = fetch_userspace_proxy();
  if (global_user_conn_proxy) {
    /* call userspace proxy */
    ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
  } else {
    /* or original mysqlnd method = do nothing, be transparent */
    ret = org_methods.connect(conn, host, user, passwd,
          passwd_len, db, db_len, port,
          socket, mysql_flags TSRMLS_CC);
  }
  return ret;
}

ユーザースペースを呼び出す: 引数が一つの場合

/* my_mysqlnd_plugin.c */

 MYSQLND_METHOD(my_conn_class,connect)(
  /* ... */, const char *host, /* ...*/) {
  /* ... */
  if (global_user_conn_proxy) {
    /* ... */
    zval* zv_host;
    MAKE_STD_ZVAL(zv_host);
    ZVAL_STRING(zv_host, host, 1);
    MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
    zval_ptr_dtor(&zv_host);
    /* ... */
  }
  /* ... */
}

ユーザースペースを呼び出す: 構造体を引数にする場合

/* my_mysqlnd_plugin.c */

MYSQLND_METHOD(my_conn_class, connect)(
  MYSQLND *conn, /* ...*/) {
  /* ... */
  if (global_user_conn_proxy) {
    /* ... */
    zval* zv_conn;
    ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
    MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
    zval_ptr_dtor(&zv_conn);
    /* ... */
  }
  /* ... */
}

多くの mysqlnd のメソッドがはじめに引数としてとるのが C の "object" です。たとえば、 connect() メソッドのはじめの引数は MYSQLND構造体 へのポインタです。MYSQNND構造体 は、mysqlnd 接続オブジェクトを表現します。

mysqlnd接続オブジェクトへのポインタは、標準のI/Oファイルハンドルと比較できます。標準の I/Oファイルハンドルのように mysqlnd接続オブジェクトは PHP のリソース変数タイプを使ってユーザースペースに結びついていなければならないのです。

C言語とユーザースペースを行き来する

 class proxy extends mysqlnd_plugin_connection {
  public function connect($conn, $host, ...) {
    /* "pre" hook */
    printf("Connecting to host = '%s'\n", $host);
    debug_print_backtrace();
    return parent::connect($conn);
  }

  public function query($conn, $query) {
    /* "post" hook */
    $ret = parent::query($conn, $query);
    printf("Query = '%s'\n", $query);
    return $ret;
  }
}
mysqlnd_plugin_set_conn_proxy(new proxy());

PHP ユーザーは、オーバーライドしたメソッドの親の実装を呼び出し可能にしなければいけません。

継承することで、ユーザーが選択したメソッドだけを改善し、"pre" や "post" フックを持たせるかどうかを選択できます。

ビルトインのクラス: mysqlnd_plugin_connection::connect()

/*  my_mysqlnd_plugin_classes.c */

 PHP_METHOD("mysqlnd_plugin_connection", connect) {
  /* ... simplified! ... */
  zval* mysqlnd_rsrc;
  MYSQLND* conn;
  char* host; int host_len;
  if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
    &mysqlnd_rsrc, &host, &host_len) == FAILURE) {
    RETURN_NULL();
  }
  ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,
    "Mysqlnd Connection", le_mysqlnd_plugin_conn);
  if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC))
    RETVAL_TRUE;
  else
    RETVAL_FALSE;
}


Oracle OCI8

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • テスト
    • 実行時設定
  • 定義済み定数
  • 例
  • OCI8 接続のハンドリングおよびプーリング
  • OCI8 高速アプリケーション通知 (FAN) サポート
  • OCI8 Transparent Application Failover (TAF) Support
  • OCI8 および DTrace 動的トレーシング
  • ドライバでサポートされるデータ型
  • OCI8 関数
    • oci_bind_array_by_name — PHP の配列を Oracle PL/SQL の配列に名前でバインドする
    • oci_bind_by_name — Oracle プレースホルダに PHP 変数をバインドする
    • oci_cancel — カーソルからの読み込みをキャンセルする
    • oci_client_version — Oracle クライアント・ライブラリのバージョンを返す
    • oci_close — Oracleとの接続を閉じる
    • oci_commit — 未解決のトランザクションをコミットする
    • oci_connect — Oracle データベースに接続する
    • oci_define_by_name — PHP の変数を、クエリで取得するカラムに関連づける
    • oci_error — 最後に見つかったエラーを返す
    • oci_execute — 文を実行する
    • oci_fetch — クエリの次の行を内部バッファに取得する
    • oci_fetch_all — クエリからの複数の行を二次元配列に取得する
    • oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す
    • oci_fetch_assoc — クエリの次の行を連想配列で返す
    • oci_fetch_object — クエリの次の行をオブジェクトとして返す
    • oci_fetch_row — クエリの次の行を配列で返す
    • oci_field_is_null — フェッチしたフィールドが null であるかどうかを確認する
    • oci_field_name — 文からのフィールド名を返す
    • oci_field_precision — フィールドの精度を問い合わせる
    • oci_field_scale — フィールドの桁数を問い合わせる
    • oci_field_size — フィールドサイズを返す
    • oci_field_type — フィールドのデータ型の名前を返す
    • oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる
    • oci_free_descriptor — ディスクリプタを解放する
    • oci_free_statement — 文やカーソルに関連付けられた全てのリソースを解放する
    • oci_get_implicit_resultset — Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す
    • oci_lob_copy — ラージオブジェクトをコピーする
    • oci_lob_is_equal — 2 つの LOB/FILE ロケータの等価性を比較する
    • oci_new_collection — 新しいコレクションオブジェクトを割り当てる
    • oci_new_connect — 一意な接続を使って Oracle サーバーへ接続する
    • oci_new_cursor — 新規カーソル (ステートメントハンドル) を割り当て、それを返す
    • oci_new_descriptor — 空の新規 LOB あるいは FILE ディスクリプタを初期化する
    • oci_num_fields — ある文における結果のカラム数を返す
    • oci_num_rows — 文の実行で作用された行数を取得する
    • oci_parse — 実行のために Oracle の文をパースする
    • oci_password_change — Oracle ユーザーのパスワードを変更する
    • oci_pconnect — 持続的接続を使用してOracle データベースに接続する
    • oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF
    • oci_result — フェッチした行からフィールドの値を取得する
    • oci_rollback — 未解決のデータベーストランザクションをロールバックする
    • oci_server_version — Oracle データベースのバージョンを返す
    • oci_set_action — アクション名を設定します
    • oci_set_call_timeout — Sets a millisecond timeout for database calls
    • oci_set_client_identifier — クライアント識別子を設定します
    • oci_set_client_info — クライアント情報を設定する
    • oci_set_db_operation — Sets the database operation
    • oci_set_edition — データベース・エディション を設定します
    • oci_set_module_name — モジュール名を設定します
    • oci_set_prefetch — クエリがプリフェッチする行数を設定する
    • oci_set_prefetch_lob — CLOB や BLOB ごとにプリフェッチするデータサイズを設定する
    • oci_statement_type — ステートメントの種類を返す
    • oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF
  • OCICollection — OCICollection クラス
    • OCICollection::append — コレクションに要素を追加する
    • OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる
    • OCICollection::assignElem — コレクションの要素に値を割り当てる
    • OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する
    • OCICollection::getElem — 要素の値を返す
    • OCICollection::max — コレクション内の要素の最大数を取得する
    • OCICollection::size — コレクションのサイズを返す
    • OCICollection::trim — コレクションの最後から要素を切り取る
  • OCILob — OCILob クラス
    • OCILob::append — ラージオブジェクトのデータを他のラージオブジェクトに追加する
    • OCILob::close — LOB ディスクリプタを閉じる
    • OCILob::eof — ラージオブジェクトのディスクリプタが EOF かどうかを調べる
    • OCILob::erase — 内部 LOB データの特定の位置を消去する
    • OCILob::export — LOB の内容をファイルに出力する
    • OCILob::flush — LOB のバッファをサーバーにフラッシュする、あるいは書き込む
    • OCILob::free — LOB ディスクリプタに関連付けられたりソースを解放する
    • OCILob::getBuffering — ラージオブジェクトに対する現在のバッファリングの状態を返す
    • OCILob::import — ファイルデータを LOB にインポートする
    • OCILob::load — ラージオブジェクトの内容を返す
    • OCILob::read — ラージオブジェクトの一部を読み込む
    • OCILob::rewind — 内部ポインタをラージオブジェクトの先頭に移動する
    • OCILob::save — データをラージオブジェクトに保存する
    • OCILob::saveFile — のエイリアス OCILob::import
    • OCILob::seek — ラージオブジェクトの内部ポインタをセットする
    • OCILob::setBuffering — 現在のラージオブジェクト用のバッファリング状態を変更する
    • OCILob::size — ラージオブジェクトのサイズを返す
    • OCILob::tell — ラージオブジェクトの内部ポインタの現在位置を返す
    • OCILob::truncate — ラージオブジェクトを切りつめる
    • OCILob::write — データをラージオブジェクトに書き込む
    • OCILob::writeTemporary — 一時的なラージオブジェクトを書き込む
    • OCILob::writeToFile — のエイリアス OCILob::export
  • OCI8 廃止されたエイリアスと関数
    • oci_internal_debug — 内部的なデバッグ出力を有効/無効にする
    • ocibindbyname — oci_bind_by_name のエイリアス
    • ocicancel — oci_cancel のエイリアス
    • ocicloselob — OCILob::close のエイリアス
    • ocicollappend — のエイリアス OCICollection::append
    • ocicollassign — のエイリアス OCICollection::assign
    • ocicollassignelem — のエイリアス OCICollection::assignElem
    • ocicollgetelem — のエイリアス OCICollection::getElem
    • ocicollmax — のエイリアス OCICollection::max
    • ocicollsize — のエイリアス OCICollection::size
    • ocicolltrim — のエイリアス OCICollection::trim
    • ocicolumnisnull — oci_field_is_null のエイリアス
    • ocicolumnname — oci_field_name のエイリアス
    • ocicolumnprecision — oci_field_precision のエイリアス
    • ocicolumnscale — oci_field_scale のエイリアス
    • ocicolumnsize — oci_field_size のエイリアス
    • ocicolumntype — oci_field_type のエイリアス
    • ocicolumntyperaw — oci_field_type_raw のエイリアス
    • ocicommit — oci_commit のエイリアス
    • ocidefinebyname — oci_define_by_name のエイリアス
    • ocierror — oci_error のエイリアス
    • ociexecute — oci_execute のエイリアス
    • ocifetch — oci_fetch のエイリアス
    • ocifetchinto — 廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種
    • ocifetchstatement — oci_fetch_all のエイリアス
    • ocifreecollection — のエイリアス OCICollection::free
    • ocifreecursor — oci_free_statement のエイリアス
    • ocifreedesc — OCILob::free のエイリアス
    • ocifreestatement — oci_free_statement のエイリアス
    • ociinternaldebug — oci_internal_debug のエイリアス
    • ociloadlob — OCILob::load のエイリアス
    • ocilogoff — oci_close のエイリアス
    • ocilogon — oci_connect のエイリアス
    • ocinewcollection — oci_new_collection のエイリアス
    • ocinewcursor — oci_new_cursor のエイリアス
    • ocinewdescriptor — oci_new_descriptor のエイリアス
    • ocinlogon — oci_new_connect のエイリアス
    • ocinumcols — oci_num_fields のエイリアス
    • ociparse — oci_parse のエイリアス
    • ociplogon — oci_pconnect のエイリアス
    • ociresult — oci_result のエイリアス
    • ocirollback — oci_rollback のエイリアス
    • ocirowcount — oci_num_rows のエイリアス
    • ocisavelob — OCILob::save のエイリアス
    • ocisavelobfile — OCILob::import のエイリアス
    • ociserverversion — oci_server_version のエイリアス
    • ocisetprefetch — oci_set_prefetch のエイリアス
    • ocistatementtype — oci_statement_type のエイリアス
    • ociwritelobtofile — OCILob::export のエイリアス
    • ociwritetemporarylob — OCILob::writeTemporary のエイリアス


はじめに

これらの関数により、 Oracle データベースにアクセスできます。 これらは SQL 及び PL/SQL 文をサポートします。基本的なフィーチャーには、 トランザクション制御、 PHP 変数の Oracle プレースホルダへのバインディング、 及び、ラージ・オブジェクト (LOB) 型やコレクションのサポートが含まれます。 データベース常駐接続プーリング(DRCP)や結果キャッシングのような、 オラクルのスケーラビリティ・フィーチャーもサポートされます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • OCI8
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • テスト
  • 実行時設定


要件

OCI8 3.0 が PHP 8 には含まれています。 » PECL からも利用できます。 PHP 7 については、OCI8 2.2 が » PECL から利用できます。 OCI8 は、Oracle 10g 以降のクライアントライブラリが必要です。

Oracle Database が PHP と同じマシンにある場合、 データベースのソフトウェアには必要なライブラリとヘッダファイルが含まれています。 PHP が違うマシンにある場合、 無料の » Oracle Instant Client ライブラリを使って下さい。

Oracle Database と PHP が同じマシンで動いている場合は、必要なライブラリはデータベースソフトウェアの中にすべて含まれています。 PHP を別のマシンで動かしている場合は、無料の » Oracle Instant Client ライブラリを使います。

Oracle Instant Client を使うには、basic あるいは Basic Light の Oracle Instant Client ZIP ファイルあるいは RPM パッケージ、または DMG パッケージをインストールします。OCI8 をソースコードからビルドする場合は、さらに Instant Client の SDK もインストールして下さい。

PHP を動かすときには、少なくとも OCI8 をビルドしたときと同じバージョン以降の Oracle ライブラリを使わなければなりません。

注意:

Oracle の標準のクライアント-サーバーの ネットワークの相互運用性によって、 Oracle のクライアントとデータベースのバージョンが違っていても 接続することが出来ます。 Oracle の正式なサポート文書 ID 207303.1.を要約すると、 Oracle Client 19, 18 と 12.2 は、 Oracle Database 11.2 以降にも接続できるとのことです。 Oracle Client 12.1 は Oracle Database 10.2 以降に接続できます。 Oracle Client 11.2 は Oracle Database 9.2 以降に接続できます。

注意:

OCI8 の全機能が使えるのは、 最新バージョンの Oracle クライアントライブラリとデータベースを使っているときだけです。


インストール手順

OCI8 とともに PHP を構成する

OCI8 を構成する前に前述の 要件 節に 目を通してください。

Web サーバーを開始する前に、一般的に OCI8 はいくつかの Oracle 環境変数（下記参照）が必要です。 それらはライブラリの場所を指定したり、構成ファイルを指示したり、 Oracle ライブラリで使用する文字セットのような基本的ないくつかのプロパティを設定します。 あらゆる PHP プロセスが開始される 前にそれらの変数を設定しなければいけません。

PHP を構成したのと同じか、またはより最新の Oracle ライブラリのメジャー・バージョンとともに PHP バイナリをリンクしなければいけません。 例えば Oracle 19 ライブラリで OCI8 をビルドするなら、 PHP も Oracle 19 ライブラリとともにデプロイして実行すべきです。 PHP のアプリケーションは、それ以外のバージョンの Oracle データベースにも接続できます。 Oracle のクライアントとサーバーの間には、異なるバージョン間での互換性があるからです。

OCI8 を PECL から(pecl コマンド経由で) インストールする

OCI8 拡張モジュールは、 » PECL リポジトリを使えば 既存の PHP のインストールに追加できます。

以下の手順で、自動インストールを行えます

  • ファイアウォールの後ろにいる場合、以下のようにしてプロキシを設定します:

    pear config-set http_proxy http://my-proxy.example.com:80/

  • 以下を実行します。

    pecl install oci8

    PHP 7 以降では、pecl install oci8-2.2.0 とします。

  • プロンプトが出たら、 $ORACLE_HOME または、 instantclient,/path/to/instant/client/lib を入力して下さい。

    注意: $ORACLE_HOME という値を入力しないで下さい。 pecl はそれを展開しないからです。 代わりに、展開済みのパスを入力するようにして下さい。 たとえば、/opt/oracle/product/19c/dbhome_1 や instantclient,/Users/myname/Downloads/instantclient_19_8 のようなものです。

  • oci8_dtrace_gen.h: No such file or directory というエラーが発生した場合、 PHP が DTrace を有効にしてビルドされているということです。 この場合、以下のようにしてインストールして下さい:

    $ export PHP_DTRACE=yes
$ pecl install oci8

  • php.ini ファイルを編集し、以下の一行を追加して下さい。

    extension=oci8.so

    php.ini のディレクティブ extension_dir が oci8.so をインストールしたディレクトリを差しているかを確認して下さい。

OCI8 を PECL から(phpize 経由で) インストールする

pecl コマンドが利用できない場合に、 OCI8 を既存の PHP のインストールに追加するには、 » PECL OCI8 パッケージを手動でダウンロードして下さい。 たとえば、oci8-3.0.0.tgz をダウンロードします。

  • パッケージを展開します:

    tar -zxf oci8-3.0.0.tgz
cd oci8-3.0.0

  • パッケージを準備します:

    phpize

  • $ORACLE_HOME または Instant Client を使ってパッケージを設定します。

    ./configure -with-oci8=shared,$ORACLE_HOME

    または

    ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib

  • パッケージをインストールします:

    make install

  • oci8_dtrace_gen.h: No such file or directory というエラーが発生した場合、 PHP が DTrace を有効にしてビルドされているということです。 この場合、以下のようにして環境変数を設定してから、 configure と make を再実行して下さい。

    $ export PHP_DTRACE=yes

  • php.ini ファイルを編集し、以下の一行を追加して下さい。

    extension=oci8.so

    php.ini のディレクティブ extension_dir が oci8.so をインストールしたディレクトリを差しているかを確認して下さい。

PHP をビルドする際に、OCI8 を共有ライブラリとしてインストールする

PHP をソースコードからビルドしている場合、 OCI8 を共有ライブラリとしてビルドするために shared オプションが使えます。 これを使うと、PHP に動的にライブラリを読み込ませることが出来ます。 共有ライブありとしてビルドすると、 PHP の本体に影響を与えることなく、OCI8 をアップグレードできます。

以下のオプションを使って、OCI8 を設定できます。

  • 無料の » Oracle Instant Client ライブラリを使っている場合は、以下のようにします:

    ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib

    Instant Client 12.2 (または前のバージョン) が ZIP ファイルからインストールされている場合、 ライブラリへのシンボリックリンクが作られていることをまず確認して下さい。 たとえば ln -s libclntsh.so.12.1 libclntsh.so のようにします。

    RPM を使って Oracle Instant Client をインストールしている場合、 configure コマンドは、以下のようになるでしょう:

    ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

    --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib のようにして、オプションを指定します。

  • Oracle Database を使っているか、 Oracle Client が完全にインストールされている場合は、以下のようにします:

    ./configure --with-oci8=shared,$ORACLE_HOME

    Webサーバーのユーザ (nobody, www) が、ライブラリへのアクセス権を持っていることを確認して下さい。 $ORACLE_HOME 内にある初期化ファイルと (もし使っていれば) tnsnames.ora です。 Oracle 10gR2 を使っている場合、 ディレクトリアクセスを与えるために $ORACLE_HOME/install/changePerm.sh を実行する必要があるかもしれません。

設定が終わった後は、いつもの PHP のビルドの手続きに従って下さい。 たとえば make install コマンドの実行です。 OCI8 の共有ライブラリ oci8.so が作成されます。 このファイルは、PHP の extension ディレクトリに手動で移動する必要があるかもしれません。 このディレクトリは、php.ini の extension_dir で指定します。

OCI8 のインストールを完了するには、 php.ini を編集し、以下の一行を追加します。

extension=oci8.so

PHP をビルドする際、OCI8 を静的リンクしてインストールする

PHP をソースコードからビルドしている場合、 以下の configure オプションを使って、 OCI8 を静的ライブラリとして PHP に含めることが出来ます。

  • Oracle Instant Client を使っている場合、以下のようにします:

    ./configure --with-oci8=instantclient,/path/to/instant/client/lib

  • Oracle Database を使っているか、 Oracle Client が完全にインストールされている場合は、以下のようにします:

    ./configure --with-oci8=$ORACLE_HOME

設定が終わった後は、いつもの PHP のビルドの手続きに従って下さい。 たとえば make install コマンドの実行です。 コンパイルが終わった後は、 oci8.so を php.ini に追加する必要はありません。 追加のビルドステップも不要です。

Windows で OCI8 をインストールする

OCI8 拡張モジュールは、 » PECL リポジトリのDLLや、 インストールされた PHP の ext ディレクトリにあるライブラリを使うことで追加出来ます。

Oracle 12c (以降) のライブラリを使う場合、 php.ini の extension=php_oci8_12c.dll, extension=php_oci8_11g.dll, extension=php_oci8.dll のいずれかをコメントアウトして下さい。 これらの DLL のうち、ひとつだけを1度に有効にできます。 バージョンが上のDLLには、より多くの機能が含まれています。 必ずしも全てのDLLが、全てのバージョンのPHPで利用できるとは限りません。 extension_dir が、PHP の拡張モジュールの DLL を含んだディレクトリを指していることを確認して下さい。

もし Instant Client を使用する場合、システムの PATH 環境変数を Oracle ライブラリ・ディレクトリに設定します。

Oracle の実行環境を設定する

この拡張モジュールを使用する前に、 Web デーモンのユーザーのために Oracle の環境変数が 適切に設定されたか確認してください。 もし Web サーバーがブート時に自動起動される場合は、ブート時の環境も正しく設定されていることを 確認してください。

注意:

PHP スクリプトで putenv() を使って Oracle の環境変数を 設定しないでください。それは、スクリプトが実行される前に Oracle のライブラリがロードされて 初期化されるかもしれないからです。 putenv() で変数を設定すると、コンフリクト、クラッシュ、 または予測出来ない動作の原因となるかもしれません。 ある関数は動作し、他の関数は捉えがたいエラーを示すかもしれません。 Web サーバー開始前に変数を設定するべきです。

Red Hat Linux と変種では、 /etc/sysconfig/httpd の最後で変数を export してください。 Apache 2 を伴う他のシステムでは Apache bin ディレクトリーで envvars スクリプトを使用するかもしれません。 ３番目のオプション、 httpd.conf の Apache SetEnv ディレクティブは、一部のシステムでは 動作するかもしれませんが、他のシステムでは不適切であることが知られています。

環境変数が正しく設定されたかチェックするには、 phpinfo() を使って Environment セクション (Apache Environment ではありません) に期待される変数が含まれるかどうかチェックしてください。

必要かもしれない変数が下記の表に含まれます。 どんな変数が使えるのかについての詳細は Oracle ドキュメントを参照ください。

一般的な Oracle 環境変数
名前 | 目的
ORACLE_HOME | フルの Oracle データベース・ソフトウェアのディレクトリを含みます。 Oracle Instant Client を使用する際は、これを設定しないでください。 設定することは余計なことで、インストール時に問題を引き起こすかもしれませんので。
ORACLE_SID | ローカルマシン上の、接続されるデータベース名を含みます。 Oracle Instant Client を使用するか、または oci_connect() に常に接続パラメータを渡す場合は、この設定は不要です。
LD_LIBRARY_PATH | この値(プラットフォームによっては、 LIBPATH や SHLIB_PATH の場合があります) を Oracle ライブラリが入っている場所に設定します。 たとえば $ORACLE_HOME/lib や /usr/lib/oracle/18.5/client/lib などです。 Linux 用の Instant Client 19 の ZIP ファイルについては、 ldconfig を代わりに使うことで、 さらに信頼性があがるよになっています。詳細は Instant Client の インストール手順書を参照ください。 Instant Client 19 (またはそれ以降) の RPM ファイルでは、 ldconfig が自動で実行されるようになっています。 ユーザーによっては、LD_LIBRARY_PATH のかわりに LD_PRELOAD を使うかもしれません。
NLS_LANG | これは Oracle ライブラリで使用される文字セットや 国際化情報を設定するためのプライマリ変数です。
ORA_SDTZ | Oracle セッションのタイムゾーンを設定します。
TNS_ADMIN | tnsnames.ora や sqlnet.ora のような Oracle Net Service の設定ファイルが置かれたディレクトリを指定します。 oci_connect() に指定する接続文字列が、 localhost/XE のような 簡易接続の名前付けの文法を使っている場合、この設定は不要です。 また、ネットワーク設定ファイルがデフォルトの位置に置かれている場合も不要です。 たとえば、 /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin, または /etc に置かれている場合です。
頻度は高くありませんが、 TWO_TASK 、 ORA_TZFILE 、及び NLS* や ORA_NLS_* 変数のような 様々な Oracle 国際化設定値を含む Oracle 環境変数が使用されます。

トラブルシューティング

OCI8 をインストールする際に最も一般的な問題は、 Oracle 環境が 正しく設定されないことです。通常、これは oci_connect() や oci_pconnect() 使用上の問題として現れます。 このエラーは Call to undefined function oci_connect() のような PHP エラーや、 ORA-12705 のような Oracle エラー、さらには Apache のクラッシュになるかもしれません。 この問題を解決するために、起動時のエラーについて Apache のログファイルをチェックして、 上記のセクションをご覧下さい。

ORA-12154 または ORA-12514 のようなネットワークエラーは Oracle のネットワーク・ネーミングまたは構成の問題を示唆する反面、 根本の原因は、 PHP 環境が誤って設定されたことや、 Oracle ライブラリが tnsnames.ora 構成ファイルの場所を指定できないためかもしれません。

Windows では、一つのマシン上に Oracle の複数のバージョンを持つと、 PHP が Oracle の正しいバージョンだけを使用することを確認するために注意を払わない限り、 すぐにライブラリのクラッシュを引き起こします。

特に Windows 上では、どのライブラリが検索されてロードされるか調べるユーティリティは、 欠けていたりクラッシュしているライブラリの問題の解決に役立ちます。

注意: Web サーバーが開始しないか、または起動時にクラッシュする場合

Apache が pthread ライブラリとリンクされていることをチェックします。

# ldd /www/apache/bin/httpd
  libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
  libm.so.6 => /lib/libm.so.6 (0x4002f000)
  libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
  libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
  libc.so.6 => /lib/libc.so.6 (0x4007e000)
  /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

libpthread が一覧に表示されなければ、 Apache を再インストールします。

# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install

UnixWare のような一部のシステムでは、それは libpthread の代わりに libthread であることに注意してください。 PHP 及び Apache を EXTRA_LIBS=-lthread とともに構成しなければいけません。


テスト

OCI8 のテストスイートは ext/oci8/tests にあります。 OCI8 のテストを実行すると、テストが失敗したときのログがこのディレクトリに記録されます。

PHP のテストを実行する前に、details.inc を編集して $user、$password と接続文字列 $dbase を編集します。 OCI8 のテストスイートでは SYSTEM アカウントを利用します。 テストユーザーにそれと同等の権限がなければ、いくつかのテストが失敗します。

Oracle Database Resident Connection Pooling をテストする場合は $test_drcp を true に設定し、 適切な DRCP プールサーバーに接続するための接続文字列を指定します。

details.inc を編集する以外の方法として、 次のように環境変数で設定することもできます。

    $ export PHP_OCI8_TEST_USER=system
    $ export PHP_OCI8_TEST_PASS=oracle
    $ export PHP_OCI8_TEST_DB=localhost/XE
    $ export PHP_OCI8_TEST_DRCP=FALSE
シェルによっては、これらの変数が適切に PHP のプロセスに展開されず、 この方法ではテストに失敗することもあります。

次に、Oracle データベース用の環境を適切に設定します。 PHP を Oracle データベースと同じマシンで実行している場合、以下を実行します。

    $ . /usr/local/bin/oraenv

Oracle 11gR2 XE の場合は次のようにします。

    $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

シェルによっては、php.ini の variables_order parameter パラメータに E を設定しておかなければならないこともあります。

    variables_order = "EGPCS"

すべての PHP のテストを実行するには、次のようにします。

    $ cd your_php_src_directory
    $ make test
OCI8 のテストだけを実行する場合は、このようにします。
    $ cd your_php_src_directory
    $ make test TESTS=ext/oci8

テストが終了したら、失敗したテストを見直します。 遅いシステムで実行した場合は、run-tests.php のデフォルトのタイムアウトよりも長い時間がかかるテストも出てくるかもしれません。 その場合は、環境変数 TEST_TIMEOUT を大きめに設定します。

高速なマシンで、軽量な設定のデータベース (Oracle 11gR2 XE など) をローカルで動かしていると、いくつかのテストが ORA-12516 あるいは ORA-12520 エラーで終了することがあります。 これを避けるには、データベースのパラメータ PROCESSES を次の手順で増やします。

Oracle ソフトウェアのオーナーとして接続します。

    $ su - oracle

Oracle 用の環境を、上で説明した oracle_env.sh あるいは oraenv で設定します。

SQL*Plus を立ち上げ、 PROCESSES を増やします。

    $ sqlplus / as sysdba
    SQL> alter system set processes=100 scope=spfile

データベースを再起動します。

    SQL> startup force


実行時設定

php.ini の設定により動作が変化します。

OCI8 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
oci8.connection_class | "" | INI_ALL |
oci8.default_prefetch | "100" | INI_SYSTEM |
oci8.events | Off | INI_SYSTEM |
oci8.max_persistent | "-1" | INI_SYSTEM |
oci8.old_oci_close_semantics | Off | INI_SYSTEM | PHP 8.1.0 以降は非推奨。
oci8.persistent_timeout | "-1" | INI_SYSTEM |
oci8.ping_interval | "60" | INI_SYSTEM |
oci8.prefetch_lob_size | "0" | INI_ALL | PECL OCI8 3.2 以降で利用可能
oci8.privileged_connect | Off | INI_SYSTEM |
oci8.statement_cache_size | "20" | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

oci8.connection_class string

このユーザー定義テキストは、接続プールの下位区画への Oracle データベース常駐接続プーリング (DRCP) 接続によって使用されます。 これにより、DRCP コネクションプールのサブパーティショニングが可能になり、 アプリケーションによる OCI8 持続的接続で、 前の PHP スクリプト由来のデータベース・セッションを再利用できます。 その結果、より良い拡張性が得られます。 異なる接続クラスで以前に使用された処理をプールしたデータベースをアプリケーションで使用する際に、 既定の Oracle 日付フォーマットのようなセッション設定はリセットされます。 これにより、異なるアプリケーションの間で情報を思いがけずに共有することを防ぎます。

接続する前に、 ini_set() で実行時に 値を設定できます。

DRCP を使用するには、 OCI8 は Oracle 11g (またはそれ以降の) ライブラリとリンクされ、 データベースは Oracle 11g (またはそれ以降)でなければいけません。 接続プールはデータベース内で有効にしなければいけません。 oci8.connection_class は、 同一のアプリケーションを稼動する web サーバーの全てで同じ文字列を設定しなければいけません。 そして、 OCI8 接続文字列 はプールされたサーバーを使用することを指定しなければいけません。 アプリケーションは持続的接続を使うべきです。

oci8.default_prefetch int

このオプションは、データベースからのデータに対する低レベルの 要求が作成されたときにいつでも自動的にフェッチされ、キャッシュ されるデフォルトの追加行数を設定します。 プリフェッチを無効にするには、値を 0 に 設定します。

プリフェッチ値は、 oci_fetch_array() のような関数がユーザーに返す行数を変えません。 行のプリフェッチ及びキャッシングは OCI8 の内部で取り扱われます。

その値は、ステートメント実行の前に oci_set_prefetch() でステートメントごとに設定できます。

Oracle Database 12c (またはそれ以降)では、PHP で設定したプリフェッチの値を Oracle のクライアント設定ファイル oraaccess.xml で上書きできます。 詳細は、Oracle のドキュメントを参照ください。

注意: プリフェッチをより大きくすると、メモリ使用量の増加と引き替えに パフォーマンスの改善につながります。 大量のデータを返す照会に対しては、パフォーマンスの利点は重要な意義を持てます。

oci8.events bool

On を使うと、 PHP でデータベースの Fast Application Notification (FAN) イベントが通知されます。

FAN 無しでは、データベース・インスタンスやマシン・ノードが予期せず故障した際、 PHP アプリケーションは、 TCP タイムアウトの満期になるまでデータペースのレスポンスを待って ブロックされてしまうかもしれません。 FAN イベントにより、確立したデータベース接続に影響する故障が PHP アプリケーションに素早く通知されます。 OCI8 拡張モジュールでは、 持続的接続キャッシュ内の利用されていない接続をクリーンアップします。

On を使う際は、 FAN イベントをポストするように データベースも構成しなければいけません。

FAN サポートは、 OCI8 が Oracle 10gR2 以降のライブラリとリンクされ、 Oracle データベース 10gR2 以降に接続する場合に利用できます。

oci8.max_persistent int

PHP プロセスあたりの持続的な OCI8 接続の最大値を指定します。 このオプションを -1 に設定することは、制限なしを意味します。

oci8.old_oci_close_semantics bool

このオプションは oci_close() の動作を制御します。有効にすると、oci_close() は何も行いません。接続はスクリプトの終了まで閉じられません。 これは後方互換性のためのみに存在しています。 この設定を有効にする必要があると判明した場合、 このオプションを有効にする代わりに、 アプリケーションで oci_close() を調整することが 強く推奨されます。

oci8.persistent_timeout int

アイドル状態の持続的接続を PHP プロセスが開いたままにする最大秒数 を指定します。 このオプションを -1 に設定すると、 PHP 処理が終了するか、または 接続が oci_close() で明示的に終了されるまで、 アイドル状態の持続的接続が保持されます。

注意: PHP では、アイドル状態のリソースの消滅は、警報ベースではありません。 PHP がスクリプト処理を終了して、リソースの最終使用タイムスタンプをチェックする際に発生します。 そのため、 (OCI8 関係に限らず) PHP 処理内で何らかの活動がある場合にのみ、 アイドル状態の接続が閉じられるというパラドックスがあります。 PHP のプロセスが複数ある場合は、 それぞれを個別にアクティブにしないと アイドル状態のリソースを消すことができません。 Oracle 11g でデータベース常駐接続プーリング (DRCP) が導入されたことにより、 oci8.max_persistent や oci8.persistent_timeout が以前に克服しようとしたメモリ及びリソースの問題が解決されます。

oci8.ping_interval int

oci_pconnect() の間、ping を発行するまでに経過させる秒数を指定します。 ping はデータベース接続が有効か確認します。 0 に設定した場合、持続的接続は oci_pconnect() が 呼び出される度に ping を発行します。 ping を完全に無効にするためには、このオプションを -1 に設定します。

注意: ping を無効にすることにより oci_pconnect() は最高の効率で処理できますが、ネットワークの脱落や PHP が接続した後に Oracle データベースがダウンした場合、 その後のスクリプトで接続が使われるまで 利用できない接続を PHP は検出できないでしょう。 詳細な情報は oci_pconnect() を参照ください。

oci8.prefetch_lob_size int

これは、LOB データの内部バッファに影響するチューニングパラメータです。 この値を増やすと、PHP とデータベース間の小さな LOB データの読み書きに掛かる時間が減り、パフォーマンスが向上します。 メモリ使用量も変化します。

この値は、OCILob のインスタンスが返す LOB や、 OCI_RETURN_LOBS を使って返される LOB に影響します。

この値は、ステートメントを実行する前に、 oci_set_prefetch_lob() を使ってステートメント単位で設定できます。

注意: Oracle Database 12.2 以降で利用可能です。

oci8.privileged_connect bool

このオプションにより特権のある外部の信用 (OCI_SYSOPER, OCI_SYSDBA) を利用して接続できます。

注意: これを On に設定することにより、 適切な OS ユーザー権限で稼動している Web サーバー上のスクリプトで データベースのパスワードを必要とせずに、 特権を持つデータベース・ユーザーとして接続できます。 これはセキュリティーのリスクになりえます。

oci8.statement_cache_size int

このオプションはステートメントキャッシュを有効にします。 また、キャッシュするステートメントの数を指定します。 ステートメントキャッシュを無効にする場合、このオプションを 0 に設定してください。

ステートメントキャッシングにより、 ステートメント・テキストをデータベースに渡したり、 ステートメントに関するあらゆるメタデータを PHP に戻したりする必要性がなくなります。 これにより、接続の有効期間中、ステートメントを再利用するアプリケーションで、 全体的なシステム・パフォーマンスを大幅に向上させられます。 一部の特別なデータベース "カーソル" では、 ステートメントが再利用されるであろうという仮定の下に、 開いたまま保たれるかもしれません。

アプリケーションで使用されるステートメントのワーキングセットのサイズに この値を設定します。小さすぎる値を設定すると、 それらが再利用される前にキャッシュからステートメントがフラッシュされる結果になります。

このオプションは、持続的接続の利用の多くの場合に役立ちます。

Oracle Database 12c (またはそれ以降) では、 この値はOracle クライアントの oraaccess.xml で自動的に設定されます。 詳細は、Oracle のドキュメントを参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

OCI8 関数およびメソッドのモード
定数 | 説明
OCI_ASSOC | oci_fetch_all() と oci_fetch_array() で結果を連想配列で取得するために使います。
OCI_BOTH | oci_fetch_all() と oci_fetch_array() で結果を配列と連想配列の両方で取得するために使います。
OCI_COMMIT_ON_SUCCESS | oci_execute() のステートメント実行モード。 ステートメントが成功したときに、自動的に変更をコミットします。
OCI_CRED_EXT | oci_connect() と組み合わせ、 Oracles の External 認証あるいは OS 認証を利用します。
OCI_DEFAULT | OCI_NO_AUTO_COMMIT を参照ください。
OCI_DESCRIBE_ONLY | oci_execute() のステートメント実行モード。 このモードをは、カラム名などのメタデータは欲しいけれど クエリから行を取得したくないという場合に使います。
OCI_EXACT_FETCH | 現在はサポートされていません。文の取得モードを指定します。 アプリケーションがあらかじめ何行取得すればよいか分かっている場合に使います。 このモードは Oracle リリース 8 以降ではプリフェッチ機能をオフにします。 カーソルは希望する行を取得した後キャンセルされ、 サーバー側のリソースの使用は軽減されます。
OCI_FETCHSTATEMENT_BY_COLUMN | oci_fetch_all() のデフォルトのモード。
OCI_FETCHSTATEMENT_BY_ROW | oci_fetch_all() でのもうひとつのモード。
OCI_LOB_BUFFER_FREE | 使用されたバッファを解放するために OCILob::flush と併用します。
OCI_NO_AUTO_COMMIT | oci_execute() のステートメント実行モード。 このモードでは、トランザクションの自動コミットは行われません。 コードの可読性を考慮して、今までの OCI_DEFAULT ではなくこちらを使うようにしましょう。
OCI_NUM | oci_fetch_all() と oci_fetch_array() で結果を配列で取得するために使います。
OCI_RETURN_LOBS | oci_fetch_array() でディスクリプタの代わりに LOB の値を取得するために使います。
OCI_RETURN_NULLS | oci_fetch_array() でフィールド値が null の場合に空の配列要素を取得するために使います。
OCI_SEEK_CUR | OCILob::seek でシーク位置を設定するために使います。
OCI_SEEK_END | OCILob::seek でシーク位置を設定するために使います。
OCI_SEEK_SET | OCILob::seek でシーク位置を設定するために使います。
OCI_SYSDATE | サポートされなくなりました。
OCI_SYSDBA | oci_connect() で、SYSDBA として接続するために使います。 php.ini 設定 oci8.privileged_connect を有効にしないと使えません。
OCI_SYSOPER | oci_connect() で、SYSOPER として接続するために使います。 php.ini 設定 oci8.privileged_connect を有効にしないと使えません。
OCI_TEMP_BLOB | 一時的な BLOB が生成されるよう明示的に指定するため OCILob::writeTemporary と併用します。
OCI_TEMP_CLOB | 一時的な CLOB が生成されるよう明示的に指定するため OCILob::writeTemporary と併用します。
OCI8 バインドおよび定義の型
定数 | 説明
OCI_B_BFILE | oci_bind_by_name() で BFILE をバインドする場合に使います。
OCI_B_BIN | oci_bind_by_name() で RAW 値をバインドする際に使います。
OCI_B_BLOB | oci_bind_by_name() で BLOB をバインドする場合に使います。
OCI_B_BOL | oci_bind_by_name() で PL/SQL の BOOLEAN 変数をバインドする場合に使います。
OCI_B_CFILEE | oci_bind_by_name() で CFILE をバインドする場合に使います。
OCI_B_CLOB | oci_bind_by_name() で CLOB をバインドする場合に使います。
OCI_B_CURSOR | oci_bind_by_name() で oci_new_descriptor() によってあらかじめ割り当てられたカーソルをバインドする場合に使います。
OCI_B_INT | oci_bind_array_by_name() で INTEGER の配列をバインドする場合に使います。
OCI_B_NTY | oci_bind_by_name() で 名前付けされたデータ型をバインドする場合に使います。
OCI_B_NUM | oci_bind_array_by_name() で NUMBER の配列をバインドする場合に使います。
OCI_B_ROWID | oci_bind_by_name() で ROWID をバインドする場合に使います。
SQLT_AFC | oci_bind_array_by_name() で CHAR の配列をバインドする場合に使います。
SQLT_AVC | oci_bind_array_by_name() で CHARZ の配列をバインドする場合に使います。
SQLT_BDOUBLE | サポートされていません。
SQLT_BFILEE | OCI_B_BFILE と等価です。
SQLT_BFLOAT | サポートされていません。
SQLT_BIN | OCI_B_BIN と等価です。
SQLT_BLOB | OCI_B_BLOB と等価です。
SQLT_BOL | OCI_B_BOL と等価です。
SQLT_CFILEE | OCI_B_CFILEE と等価です。
SQLT_CHR | oci_bind_array_by_name() で VARCHAR2 の配列をバインドする場合に使います。 oci_bind_by_name() でも使います。
SQLT_CLOB | OCI_B_CLOB と等価です。
SQLT_FLT | oci_bind_array_by_name() で FLOAT の配列をバインドする場合に使います。
SQLT_INT | OCI_B_INT と等価です。
SQLT_LBI | oci_bind_by_name() で LONG RAW 値をバインドする際に使います。
SQLT_LNG | oci_bind_by_name() で LONG 値をバインドする際に使います。
SQLT_LVC | oci_bind_array_by_name() で LONG VARCHAR の配列をバインドする場合に使います。
SQLT_NTY | OCI_B_NTY と等価です。
SQLT_NUM | OCI_B_NUM と等価です。
SQLT_ODT | oci_bind_array_by_name() で LONG の配列をバインドする場合に使います。
SQLT_RDD | OCI_B_ROWID と等価です。
SQLT_RSET | OCI_B_CURSOR と等価です。
SQLT_STR | oci_bind_array_by_name() で STRING の配列をバインドする場合に使います。
SQLT_UIN | サポートされていません。
SQLT_VCS | oci_bind_array_by_name() で VARCHAR の配列をバインドする際に使います。
OCI8 ディスクリプタの型
定数 | 説明
OCI_DTYPE_FILE | このフラグは oci_new_descriptor() に新しい FILE ディスクリプタを初期化するように伝えます。
OCI_DTYPE_LOB | このフラグは oci_new_descriptor() に新しい LOB ディスクリプタを初期化するように伝えます。
OCI_DTYPE_ROWID | このフラグは oci_new_descriptor() に新しい ROWID ディスクリプタを初期化するように伝えます。
OCI_D_FILE | OCI_DTYPE_FILE と等価です。
OCI_D_LOB | OCI_DTYPE_LOB と等価です。
OCI_D_ROWID | OCI_DTYPE_ROWID と等価です。
OCI8 Transparent Application Failover (TAF) Constants
定数 | 説明
OCI_FO_ABORT (int) | Failover was unsuccessful and there is no option of retrying.
OCI_FO_BEGIN (int) | Failover has detected a lost connection and failover is starting.
OCI_FO_END (int) | Failover completed successfully.
OCI_FO_ERROR (int) | Failover was unsuccessful but it gives the application the opportunity to handle the error and return OCI_FO_RETRY to retry failover.
OCI_FO_NONE (int) | The user has not requested a failover type.
OCI_FO_REAUTH (int) | An Oracle user has been re-authenticated.
OCI_FO_RETRY (int) | The failover should be attempted again by Oracle. In case of an error while failing over to a new connection, TAF is able to retry the failover. Typically, the application code should sleep for a while before returning OCI_FO_RETRY.
OCI_FO_SELECT (int) | The user has requested SELECT failover as well. It allows users with open cursors to continue fetching from them after failure.
OCI_FO_SESSION (int) | The user has requested only session failover. For example, if a user's connection is lost, then a new session is automatically created for the user on the backup. This type of failover does not attempt to recover SELECTs.
OCI_FO_TXNAL (int) | The user has requested a transaction failover.


例

これらの例では HR として接続しています。 これは、Oracle データベースに付属するサンプルのスキーマ "Human Resources" 用のユーザーです。このユーザーを使うには、 ユーザーのロックを解除してパスワードをリセットしなければなりません。

このサンプルでは、ローカルマシン上にある XE データベースに接続しています。それぞれの環境にあわせて 接続文字列を変更してください。

例1 基本的なクエリ

ここでは、クエリの結果を表示させます。OCI8 のステートメントは 準備-実行-フェッチ という手順をとります。

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// 文を準備します
$stid = oci_parse($conn, 'SELECT * FROM departments');
if (!$stid) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// クエリを実行します
$r = oci_execute($stid);
if (!$r) {
$e = oci_error($stid);
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// クエリの結果を取得します
print "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
print "<tr>\n";
foreach ($row as $item) {
print " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
print "</tr>\n";
}
print "</table>\n";

oci_free_statement($stid);
oci_close($conn);

?>

例2 バインド変数を用いた挿入

バインド変数を使うと、実行コンテキストをキャッシュして再利用できるので パフォーマンスが向上します。また、バインド変数を使うと SQL インジェクション対策にもなって安全性が向上します。

<?php

// 実行前に表を作成します
// CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');

$id = 60;
$data = 'Some data';

oci_bind_by_name($stid, ':myid', $id);
oci_bind_by_name($stid, ':mydata', $data);

$r = oci_execute($stid); // 実行してコミットします

if ($r) {
print "One row inserted";
}

oci_free_statement($stid);
oci_close($conn);

?>

例3 クエリの WHERE 句でのバインド

単一のスカラー値のバインドの例です。

<?php

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
$stid = oci_parse($conn, $sql);
$didbv = 60;
oci_bind_by_name($stid, ':didbv', $didbv);
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
echo $row['LAST_NAME'] ."<br>\n";
}

// 出力は
// Austin
// Ernst
// Hunold
// Lorentz
// Pataballa

oci_free_statement($stid);
oci_close($conn);

?>

例4 CLOB カラムにデータを挿入する

巨大なデータに対しては、バイナリラージオブジェクト (BLOB) あるいはキャラクタラージオブジェクト (CLOB) 型を使います。 この例では CLOB を使います。

<?php

// 実行前に表を作成します
// CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$mykey = 12343; // この例で用いる任意のキー

$sql = "INSERT INTO mytable (mykey, myclob)
VALUES (:mykey, EMPTY_CLOB())
RETURNING myclob INTO :myclob";

$stid = oci_parse($conn, $sql);
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
oci_execute($stid, OCI_NO_AUTO_COMMIT);
$clob->save("A very long string");

oci_commit($conn);

// CLOB データを取得します

$query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

$stid = oci_parse ($conn, $query);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_execute($stid);

print '<table border="1">';
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
// ループ内で、大きなサイズの変数を解放してから次のフェッチに進めます。
// これで、PHP のピークメモリ利用量を抑えます。
unset($row);
}
print '</table>';

?>

例5 PL/SQL ストアドファンクションの使用

戻り値に変数をバインドしなければなりません。 オプションで PL/SQL 関数の引数がある場合はそこにも変数をバインドしなければなりません。

<?php

/*
PHP プログラムを実行する前に、ストアドファンクションを
SQL*Plus あるいは SQL Developer で作成します

CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
BEGIN
RETURN p * 3;
END;

*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$p = 8;

$stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
oci_bind_by_name($stid, ':p', $p);
oci_bind_by_name($stid, ':r', $r, 40);

oci_execute($stid);

print "$r\n"; // 24 と表示します

oci_free_statement($stid);
oci_close($conn);

?>

例6 PL/SQL ストアドプロシージャの使用

ストアドプロシージャでは、すべての引数に変数をバインドしなければなりません。

<?php

/*
PHP プログラムを実行する前に、ストアドプロシージャを
SQL*Plus あるいは SQL Developer で作成します

CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
BEGIN
p2 := p1 * 2;
END;

*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$p1 = 8;

$stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
oci_bind_by_name($stid, ':p1', $p1);
oci_bind_by_name($stid, ':p2', $p2, 40);

oci_execute($stid);

print "$p2\n"; // 16 と表示します

oci_free_statement($stid);
oci_close($conn);

?>

例7 REF CURSOR を返す PL/SQL ファンクションのコール

クエリが返す値が REF CURSOR となり、そこから値を取得することができます。

<?php
/*
このような PL/SQL ストアドファンクションを作成します

CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
rc SYS_REFCURSOR;
BEGIN
OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
RETURN rc;
END;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
oci_execute($stid);

echo "<table border='1'>\n";
while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
echo "<tr>\n";
$rc = $row['MFRC'];
oci_execute($rc); // returned column value from the query is a ref cursor
while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
echo " <td>" . $rc_row['CITY'] . "</td>\n";
}
oci_free_statement($rc);
echo "</tr>\n";
}
echo "</table>\n";

// 出力は
// Beijing
// Bern
// Bombay
// Geneva

oci_free_statement($stid);
oci_close($conn);

?>


OCI8 接続のハンドリングおよびプーリング

接続関数

oci8 拡張モジュールは Oracle に接続するための 3 つの異なる関数を提供しています。標準の接続関数は oci_connect() です。これは Oracle データベースへの接続を作成し、 それ以降のデータベースで使うリソースを返します。

Oracle サーバーへの接続は、完了まで要する時間という点から見ると、 かなりコストのかかる操作です。oci_pconnect() 関数は、 異なるスクリプトリクエスト間で接続の再利用が可能な 持続的キャッシュを使用します。 これは、PHP プロセス (もしくは Apache の子プロセス) 毎の接続に関するオーバーヘッドを一度のみ負うということを意味しています。

もしアプリケーションが信用された異なる Web ユーザー毎に Oracle に接続する場合、oci_pconnect() による持続的キャッシュは、 同時ユーザー数の増加と共に有効ではなくなるでしょう。 これは、多くのアイドル状態の接続が維持されることが原因で、 Oracle サーバー全体のパフォーマンスに不利な影響を与え始めるためです。 もしアプリケーションがこの方法で構成されている場合、 oci8.max_persistent や oci8.persistent_timeout (持続的接続のキャッシュサイズや生存期間の制御が可能になります) を使用してアプリケーションをチューニングする、あるいは Oracle Database Resident Connection Pooling を使う (Oracle Database 11g 以降の場合)、もしくは oci_connect() を使用することが推奨されます。

oci_connect() と oci_pconnect() の両者とも接続キャッシュを使用します。もし、同一パラメータと共に oci_connect() を複数回コールする場合、 2 番目以降は既存の接続ハンドルを返します。oci_connect() によって使用されるキャッシュは、スクリプト実行終了時、 もしくは明示的に接続ハンドルを閉じた時にクリアされます。 oci_pconnect() も同様の動作をしますが、 キャッシュは独立して維持され、リクエスト間で残存します。

このキャッシュ機能は忘れてはならないほど重要です。 それは、2 つのハンドルがトランザクション的に独立していない (実際には同じ接続なので、どのような種類の独立もありません) ためです。もしアプリケーションが 2 つの別々でトランザクション的に独立した接続を必要とする場合、 oci_new_connect() を使用すべきです。

PHP プロセス終了時に oci_pconnect() キャッシュは消去され、 データベース接続は全て閉じられます。 そのため、持続的接続を効果的に使用するには、 PHP は Apache のモジュールであるか、または FPM によって使用されるか、 または同様のものでなければいけません。 PHP が CGI によって、またはコマンドラインを介して使用される場合、 持続的接続には oci_connect() 以上に全く利益がありません。

oci_new_connect() は、他の既存の接続が存在したとしても 常に Oracle サーバーへの新規接続を生成します。 特にアプリケーションの最も負荷が高い部分など、 高トラフィックな Web アプリケーションに対しては oci_new_connect() の使用を避けてください。

持続的接続をユーザーが閉じることができます。 これにより、接続リソースの使い方をユーザーがより強く制御できます。 持続的接続は、PHP の変数が参照していない場合にも、 自動的に閉じられるようになっています。 たとえば、PHP のユーザ関数のスコープの最後に到達した場合です。 これによって、コミットされていないトランザクションは全てロールバックされます。 持続的接続に対するこれらの変更によって、 持続的接続でない、通常の接続と似たような振る舞いをするようになります。 さらに、インターフェイスがシンプルになり、 アプリケーションの一貫性と予測可能性が改善されます。 歴史的な振る舞いを維持するには、 oci8.old_oci_close_semantics の設定を On にして下さい。

Apache や FPM のプロセスが再度 fork した後、 PHP の持続的接続は再接続されます。 これは、Oracle　Database の LOGON トリガに セッション属性を設定するべきであり、 アプリケーションのユーザー接続単位で設定すべきではないということです。

DRCP 接続プーリング

PHP は、Oracle 11g のデータベース常駐接続プーリング (DRCP) をサポートします。 DRCP によりデータベースマシンのメモリをより効率的に使用し、 高い拡張性が得られます。 DRCP を使うためにアプリケーションを変更する必要はないか、または 最小限です。

DRCP は、ごく少数のデータベーススキーマを使用し、データベース接続を短時間オープン状態に 保つアプリケーションに適しています。 その他のアプリケーションは、 Oracle のデフォルトの Dedicated データベースサーバープロセスか、または Shared サーバーを使用しなければいけません。

DRCP は３つの接続機能全てに有益ですが、 oci_pconnect() で接続を作成すると最高の拡張性が得られます。

OCI8 で DRCP を利用可能にするには、 PHP で使用する Oracle クライアントライブラリ、 及び Oracle データベースのバージョンが共に 11g 以降でなければいけません。

DRCP についてのドキュメントはいくつかの Oracle マニュアルに見つかります。 例えば、使用法の情報のために、 Oracle ドキュメントで » データベース常駐接続プーリングの構成 をご覧ください。 » DRCP ホワイトペーパー には、 DRCP についての 予備知識となる情報が含まれています。

DRCP を使用するには、 OCI8 拡張モジュール及び Oracle 11g 以降のライブラリをインストールし、 以下のステップを続けます。

  • データベース内の接続プールを開始するために、 特権を持つデータベース管理者として SQL*Plus のようなプログラムを使います。

        SQL> execute dbms_connection_pool.start_pool;

  • DRCP の設定を構成するために、 任意で dbms_connection_pool.alter_param() を使用します。 現行のプール設定は、 DBA_CPOOL_INFO ビューで照会できます。

  • 使用する接続文字列を更新します。 MYDB のようなネットワーク接続名を使って現在接続する PHP アプリケーションでは、

        $c = oci_pconnect("myuser", "mypassword", "MYDB");

    tnsnames.ora ファイルを修正して、 (SERVER=POOLED) 節を追加します。 例えば、

        MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
           (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
           (SERVER=POOLED)))

    あるいは、 PHP で Easy Connect 構文を修正して、サービス名の後に :POOLED を追加します。

        $c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED");

  • php.ini を編集して、接続クラス名を選択してください。 この名前は、接続プールの論理的なディビジョンを指示し、 個別のアプリケーションごとにプーリングを分離するために使われます。 同一のユーザー名と接続クラスをもつ PHP アプリケーションは、 プール内の接続を共有できます。これにより、より大きな拡張性が得られます。

        oci8.connection_class = "MY_APPLICATION_NAME"

  • アプリケーションを実行して、 11g 以降のデータベースに接続します。

注意:

持続的接続のパフォーマンスを必要とする Oracle クライアントライブラリ 10g を使うアプリケーションでは、 Oracle Shared サーバー(マルチスレッドサーバーとして既知)を使用することにより、 必要なデータベース・メモリー量を減らせます。 詳細は Oracle ドキュメントを参照ください。

注意:

DRCP 接続に対するパスワードを変更すると、 ORA-56609: Usage not supported with DRCP というエラーで失敗します。 これは Oracle データベース 11g の制約に典拠が示されています。


OCI8 高速アプリケーション通知 (FAN) サポート

FAN サポートは、高速接続フェイルオーバーという Oracle Database 高可用性機能を提供します。 これにより、データベースマシンまたはデータベースインスタンスが使用不能になると、 PHP OCI8 スクリプトに通知されるようになります。 FAN を使用しないと、数分間かもしれませんが、 TCP タイムアウトが発生してエラーが返されるまで OCI8 がハングアップすることがありえます。 OCI8 で FAN を有効にすると、 Web ユーザーが機能停止に気づかないように アプリケーションがエラーを検出し、 使用可能なデータベースインスタンスに再接続できるようになります。

FAN サポートは、PHP とリンクする Oracle クライアントライブラリ、 および Oracle Database の両方のバージョンが 10gR2 以降の場合に使用可能です。

データベースインスタンスを生き残らせるための接続がただちに作成されるので、 FAN は、Oracle のクラスタリング技術 (RAC) のユーザーに役立ちます。 ブローカーがある場合の Oracle Data Guard のユーザーは、 スタンバイ用のデータベースがオンラインになる際に FAN イベントが生成されることに気づくでしょう。 スタンドアローンのデータベースは、データベース再始動の際に FAN イベントを送信します。

アクティブな接続の場合、 データベースマシンまたはデータベースインスタンスが使用できなくなると、 現在呼び出されている OCI8 拡張モジュールの関数により 接続失敗エラーが返されます。 後続の PHP スクリプト再接続時には、 残存するデータベースインスタンスへの接続が確立されます。 OCI8 拡張モジュールはまた、 いかなるサービスの中断もスクリプトで意識しないように PHP 接続呼び出しが新鮮な接続を確立するよう、 データベースマシンまたはデータベースインスタンスの障害の影響を受けた すべてのアイドル状態の接続を透過的にクリーンアップします。

FAN イベントを有効にすると、サービスの中断により無効にされた アイドル状態の接続の積極的な接続管理が提供されるため、 oci8.events が On の場合、ping を無効にするには oci8.ping_interval を -1 に 設定することがお勧めです。

PHP OCI8 で FAN サポートを有効にするには、 Oracle 10gR2 以降のライブラリとともに PHP OCI8 をビルドし、 以下のステップに従います。

  • データベースサービスが FAN イベントをポストできるようにするには、 特権を持つデータベース管理者として SQL*Plus のようなプログラムを使用します。 たとえば下記のように使用します。

        SQL> execute dbms_service.modify_service(
                   SERVICE_NAME        => 'sales',
                   AQ_HA_NOTIFICATIONS => TRUE);

  • php.ini を編集して以下のように追加します。

        oci8.events = On

  • もし OCI8 のエラー条件をアプリケーションがすでに正しく処理していなければ、 障害を検出し、適切なアクションを取るように変更します。 これは、再接続や再実行のステートメントを含むかもしれません。
  • アプリケーションを実行し、Oracle Database 10gR2 以降に接続します。


OCI8 Transparent Application Failover (TAF) Support

TAF is an Oracle Database feature that provides high availability. It enables PHP OCI8 applications to automatically reconnect to a preconfigured database when database connectivity fails due to instance or network failure.

In a configured Oracle Database system, TAF occurs when the PHP application detects that the database instance is down or unreachable. It establishes a connection to another node in an Oracle » RAC configuration, a hot standby database, or the same database instance itself. See » Oracle Call Interface Programmer's Guide for more information about OCI TAF.

An application callback can be registered with oci_register_taf_callback(). During failover, normal application processing stops and the registered callback is invoked. The callback notifies the application of the failover events. If the failover succeeds, normal processing will be resumed. If the failover aborts, any following database operations in the application will fail due to no connection being available.

When a connection fails over to another database, the callback can reset any necessary connection state, for example replaying any necessary ALTER SESSION commands if the database service did not have -failover_restore enabled.

An application callback can be removed by calling oci_unregister_taf_callback().

Configuring Transparent Application Failover

TAF can be configured on the PHP OCI8 side or in the database configuration. If both are configured, database-side settings take precedence.

Configure TAF in PHP OCI8 (the client side) by including the FAILOVER_MODE parameter in the CONNECT_DATA portion of a connect descriptor. See Configuring Transparent Application Failover in » Oracle Database Net Services Administrator's Guide for more information about client side configuration of TAF.

An example tnsnames.ora to configure TAF reconnecting to the same database instance:

    ORCL =
      (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
        (CONNECT_DATA =
          (SERVICE_NAME = orclpdb1)
          (FAILOVER_MODE =
            (TYPE = SELECT)
            (METHOD = BASIC)
            (RETRIES = 20)
            (DELAY = 15))))

Alternatively configure TAF on the database side by modifying the target service with » srvctl (for RAC) or the » DBMS_SERVICE.MODIFY_SERVICE packaged procedure (for single instance databases).

Using TAF Callbacks in OCI8

A TAF callback is an application function that can be registered to be called during failover. It is called several times while re-establishing the application's connection.

Callback first occurs when a loss of connection is detected. This allows the application to act accordingly for the upcoming delay of the failover. If the failover is successful, the callback is invoked after connection is re-established and usable. At this time, the application can resynchronize session settings and take actions such as informing the user that failover occurred. If failover is unsuccessful, a callback occurs to inform the application that a failover did not take place and the connection is unusable.

The interface of a TAF user-defined callback function is as follows:

userCallbackFn(resource $connection, int $event, int $type): int

connection

The Oracle connection on which the TAF callback was registered via oci_register_taf_callback(). The connection is not valid until the failover completes successfully.

event

The failover event indicates the current status of the failover.

  • OCI_FO_BEGIN indicates that failover has detected a lost connection and failover is starting.

  • OCI_FO_END indicates successful completion of failover.

  • OCI_FO_ABORT indicates that failover was unsuccessful, and there is no option of retrying.

  • OCI_FO_ERROR also indicates that failover was unsuccessful, but it gives the application the opportunity to handle the error and return OCI_FO_RETRY to retry failover.

  • OCI_FO_REAUTH indicates that an Oracle user has been re-authenticated.

type

The failover type. This lets the callback know what type of failover the application has requested. The usual values are as follows:

  • OCI_FO_SESSION indicates that the user has requested only session failover. For example, if a user's connection is lost, then a new session is automatically created for the user on the backup. This type of failover does not attempt to recover SELECTs.

  • OCI_FO_SELECT indicates that the user has requested SELECT failover as well. It allows users with open cursors to continue fetching from them after failure.

return value

  • 0 indicates the failover steps should continue normally.

  • OCI_FO_RETRY indicates that the failover should be attempted again by Oracle. In case of an error while failing over to a new connection, TAF is able to retry the failover. Typically, the application code should sleep for a while before returning OCI_FO_RETRY.

例1 Registering a TAF callback

<?php

// Define userspace callback
class MyClass {
public static $retry_count;
public static function TAFCallback($conn, $event, $type)
{
switch ($event) {
case OCI_FO_BEGIN:
printf(" Failing Over ... Please stand by\n");
printf(" Failover type was found to be %s \n",
(($type==OCI_FO_SESSION) ? "SESSION"
:(($type==OCI_FO_SELECT) ? "SELECT" : "UNKNOWN!")));
self::$retry_count = 0;
break;
case OCI_FO_ABORT:
// The application cannot continue using the database
printf(" Failover aborted. Failover will not take place.\n");
break;
case OCI_FO_END:
// Failover completes successfully. Inform users a failover occurs.
printf(" Failover ended ... resuming services\n");
break;
case OCI_FO_REAUTH:
printf(" Failed over user ... resuming services\n");
// Replay any ALTER SESSION commands associated with this connection
// eg. oci_parse($conn, 'ALTER SESSION ...') ;
break;
case OCI_FO_ERROR:
// Stop retrying if we have already attempted for 20 times.
if (self::$retry_count >= 20)
return 0;
printf(" Failover error received. Sleeping...\n");
sleep(10);
self::$retry_count++;
return OCI_FO_RETRY; // retry failover
break;
default:
printf("Bad Failover Event: %d.\n", $event);
break;
}
return 0;
}
}

$fn_name = 'MyClass::TAFCallback';

$conn = oci_connect('hr', 'welcome', 'orcl');
$sysconn = oci_connect('system', 'oracle', 'orcl');

// Use a privileged connection to construct a SQL statement that will initiate failover
$sql = <<< 'END'
select unique 'alter system disconnect session '''||sid||','||serial#||''''
from v$session_connect_info
where sid = sys_context('USERENV', 'SID')
END;

$s = oci_parse($conn, $sql);
oci_execute($s);
$r = oci_fetch_array($s);
$disconnectssql = $r[0];

oci_register_taf_callback($conn, $fn_name); // Register TAFCallback to Oracle TAF

print "Parsing user query\n";
$sql = "select systimestamp from dual";
$stmt = oci_parse($conn, $sql);

// For example, if a connection loss occurs at this point, oci_execute() will
// detect the loss and failover begins. During failover, oci_execute() will
// invoke the TAF callback function several times. If the failover is successful,
// a new connection is transparently created and oci_execute() will continue as
// usual. The connection session settings can be reset in the TAF callback
// function. If the failover is aborted, oci_execute() will return an error
// because a valid connection is not available.

// Disconnect the user, which initiates failover
print "Disconnecting the user\n";
$discsql = oci_parse($sysconn, $disconnectssql);
oci_execute($discsql);

print "Executing user query\n";
$e = oci_execute($stmt);
if (!$e) {
$m = oci_error($stmt);
trigger_error("Could not execute statement: ". $m['message'], E_USER_ERROR);
}
$row = oci_fetch_array($stmt);
print $row[0] . "\n";

// do other SQL statements with the new connection, if it is valid
// $stmt = oci_parse($conn, . . .);

?>

参考

  • oci_register_taf_callback()
  • oci_unregister_taf_callback()


OCI8 および DTrace 動的トレーシング

OCI8 2.0 では、DTrace をサポートする OS 上で使用できる 静的な DTrace プローブが導入されました。 PHP および DTrace の概要については、DTrace 動的トレーシング をご覧ください。

DTrace サポート付きで OCI8 をインストール

PHP OCI8 で DTrace のサポートを有効にするには、 PHP_DTRACE を設定後、 OCI8 を共用拡張モジュールとしてビルドします。

$ export PHP_DTRACE=yes
$ pecl install oci8

php.ini を編集し、作成された oci8.so がある ディレクトリを extension_dir に 設定します。 さらに以下のように追加してその拡張モジュールを有効にします。

extension=oci8.so

もし、phpize および configure を （ pecl の代わりに） 使用して PECL から PHP OCI8 をインストールする場合、 さらに PHP_DTRACE=yes を設定する必要があります。 それは、--enable-dtrace オプションが、PECL バンドルの 制限された configure スクリプトにより 無視されるからです。

一般的な PECL インストール手順については、PECL 拡張モジュールのインストール をご覧ください。

PHP OCI8 の DTrace 静的プローブ

PHP OCI8 では、以下の静的プローブが使用できます
プローブ名 | プローブの説明 | プローブの引数
oci8-connect-entry | oci_connect()、oci_pconnect() および oci_new_connect() により開始されます。データベース接続が確立する前に発射されます。 | char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
oci8-connect-return | 接続終了時に発射されます。 | void *connection
oci8-check-connection | Oracle のエラーにより、接続が不正になったかもしれない場合に発射されます。 | void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
oci8-sqltext | oci_parse() が実行された際に発射されます。 | void *connection, char *client_id, void *statement, char *sql
oci8-connection-close | データベースへの接続が完全に破壊された際に発射されます。 | void *connection
oci8-error | Oracle のエラーが生じた場合に発射されます。 | int status, long errcode
oci8-execute-mode | 実行モードを示す oci_execute() のたびに発射されます。 | void *connection, char *client_id, void *statement, unsigned int mode

これらのプローブは、OCI8 スクリプトのトレーシングで有用です。

connection および statement は、 PHP の接続および実行されたステートメントを追跡するために使用される内部構造への ポインタです。

client_id は、 oci_set_client_identifier() により設定される値です。

コア PHP にも静的プローブがあります。 コア PHP の DTrace 静的プローブ をご覧ください。

OCI8 の DTrace プローブ内部デバッギング
プローブ名
oci8-connect-expiry
oci8-connect-lookup
oci8-connect-p-dtor-close
oci8-connect-p-dtor-release
oci8-connect-type
oci8-sesspool-create
oci8-sesspool-stats
oci8-sesspool-type

これらのプローブは、OCI8 メンテナにとって有用です。 引数およびいつ発射されるかについては、OCI8 のソースコードを参照ください。

PHP OCI8 の DTrace 静的プローブ一覧

使用できるプローブを一覧表示するには、 PHP プロセスを開始して以下のように実行します。

# dtrace -l

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

   ID   PROVIDER            MODULE                          FUNCTION NAME
   [ . . . ]
   17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
   18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
   19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
   20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
   21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
   22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
   23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
   24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
   25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
   26 phpoci22116           oci8.so                     php_oci_error oci8-error
   27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
   28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
   29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
   30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
   31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

PROVIDER 列の値は、phpoci および 現在実行中の PHP プロセスのプロセス ID から構成されます。

FUNCTION 列は、各プロバイダが配置された PHP 内部の C 実装関数名を参照します。

PHP プロセスが実行されていない場合、PHP プローブは表示されません。

PHP OCI8 についての DTrace の例

この例では、DTrace の D スクリプト言語の基本を示します。

例1 DTrace を使用して すべてのユーザーレベルの PHP OCI8 静的プローブをトレースするための user_oci8_probes.d

#!/usr/sbin/dtrace -Zs

#pragma D option quiet

php*:::oci8-connect-entry
{
    printf("%lld: PHP connect-entry\n", walltimestamp);
    printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
    printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
    printf("  session_mode=%ld\n", (long)arg3);
    printf("  persistent=%d\n", (int)arg4);
    printf("  exclusive=%d\n", (int)arg5);
}

php*:::oci8-connect-return
{
    printf("%lld: PHP oci8-connect-return\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
}

php*:::oci8-connection-close
{
    printf("%lld: PHP oci8-connect-close\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
}

php*:::oci8-error
{
    printf("%lld: PHP oci8-error\n", walltimestamp);
    printf("  status=%d\n", (int)arg0);
    printf("  errcode=%ld\n", (long)arg1);
}

php*:::oci8-check-connection
{
    printf("%lld: PHP oci8-check-connection\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
    printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
    printf("  is_open=%d\n", arg2);
    printf("  errcode=%ld\n", (long)arg3);
    printf("  server_status=%lu\n", (unsigned long)arg4);
}

php*:::oci8-sqltext
{
    printf("%lld: PHP oci8-sqltext\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
    printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
    printf("  statement=0x%p\n", (void *)arg2);
    printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
}

php*:::oci8-execute-mode
{
    printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
    printf("  connection=0x%p\n", (void *)arg0);
    printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
    printf("  statement=0x%p\n", (void *)arg2);
    printf("  mode=0x%x\n", arg3);
}

このスクリプトは、dtrace に対して -Z オプションを使用します。 それにより、実行中の PHP プロセスがない場合に実行できるようになります。 もしこのオプションが書き落とされた場合、 モニターされているプローブがどれも存在しないことがわかっているので、 PHP の実行可能ファイルが実行されていない場合、 スクリプトは即座に終了します。

マルチ CPU マシンでは、プローブの順序は規則的に連続して表示されないことがあります。 これは、どの CPU がプローブを処理し、 CPU の間をスレッドがどのように移動したかに依存します。 プローブのタイムスタンプを表示すると、 混乱を減らすことができます。

スクリプトは、PHP スクリプト実行中の期間全体にわたって、 すべてのユーザーレベルの PHP OCI8 静的プローブ・ポイントをトレースします。 D スクリプトを実行します。

# ./user_oci8_probes.d

PHP スクリプトまたはアプリケーションを実行します。 モニタリングの D スクリプトは、各プローブが発射されるたびに その引数を出力します。 例えば、テーブルを照会する単純な PHP スクリプトにより 以下のトレース出力がもたらされるでしょう。

1381794982092854582: PHP connect-entry
  credentials="hr@localhost/pdborcl"
  charset=""
  session_mode=0
  persistent=0
  exclusive=0
1381794982183158766: PHP oci8-connect-return
  connection=0x7f4a7907bfb8
1381794982183594576: PHP oci8-sqltext
  connection=0x7f4a7907bfb8
  client_id="Chris"
  statement=0x7f4a7907c2a0
  sql="select * from employees"
1381794982183783706: PHP oci8-execute-mode
  connection=0x7f4a7907bfb8
  client_id="Chris"
  statement=0x7f4a7907c2a0
  mode=0x20
1381794982444344390: PHP oci8-connect-close
  connection=0x7f4a7907bfb8

モニタリングが完了した際には、CTRL+C を使用して D スクリプトを終わらせることができます。

参考

  • DTrace 動的トレーシング


ドライバでサポートされるデータ型

oci_bind_by_name() 関数を使用してパラメータをバインドする場合、 ドライバは次の型をサポートします
型 | マッピング
SQLT_NTY | oci_new_collection() によって生成されたような PHP のコレクションオブジェクトからネイティブのコレクション型に マップします
SQLT_BFILEE | oci_new_descriptor() によって生成されたような PHP のディスクリプタオブジェクトからネイティブのディスクリプタ型に マップします
SQLT_CFILEE | oci_new_descriptor() によって生成されたような PHP のディスクリプタオブジェクトからネイティブのディスクリプタ型に マップします
SQLT_CLOB | oci_new_descriptor() によって生成されたような PHP のディスクリプタオブジェクトからネイティブのディスクリプタ型に マップします
SQLT_BLOB | oci_new_descriptor() によって生成されたような PHP のディスクリプタオブジェクトからネイティブのディスクリプタ型に マップします
SQLT_RDD | oci_new_descriptor() によって生成されたような PHP のディスクリプタオブジェクトからネイティブのディスクリプタ型に マップします
SQLT_NUM | PHP パラメータを 'C' の long 型に変換し、 その値をバインドします
SQLT_RSET | oci_parse() によって生成されたもしくは他の OCI クエリから処理されたような PHP のステートメントハンドルからネイティブのステートメントハンドルに マップします
SQLT_BOL | PHP パラメータを PL/SQL の BOOLEAN にバインドします
SQLT_CHR とその他の型 | PHP パラメータを文字列型に変換し、その文字列をバインドします
以下の型は結果セットからカラムを処理する際にサポートされます
型 | マッピング
SQLT_RSET | カーソルを表す OCI ステートメントリソースを生成します
SQLT_RDD | ROWID オブジェクトを生成します
SQLT_BLOB | LOB オブジェクトを生成します
SQLT_CLOB | LOB オブジェクトを生成します
SQLT_BFILE | LOB オブジェクトを生成します
SQLT_LNG | SQLT_CHR としてバインドし、文字列として返します
SQLT_LBI | SQLT_BIN としてバインドし、文字列として返します
その他の型 | SQLT_CHR としてバインドし、文字列として返します


OCI8 関数

目次

  • oci_bind_array_by_name — PHP の配列を Oracle PL/SQL の配列に名前でバインドする
  • oci_bind_by_name — Oracle プレースホルダに PHP 変数をバインドする
  • oci_cancel — カーソルからの読み込みをキャンセルする
  • oci_client_version — Oracle クライアント・ライブラリのバージョンを返す
  • oci_close — Oracleとの接続を閉じる
  • oci_commit — 未解決のトランザクションをコミットする
  • oci_connect — Oracle データベースに接続する
  • oci_define_by_name — PHP の変数を、クエリで取得するカラムに関連づける
  • oci_error — 最後に見つかったエラーを返す
  • oci_execute — 文を実行する
  • oci_fetch — クエリの次の行を内部バッファに取得する
  • oci_fetch_all — クエリからの複数の行を二次元配列に取得する
  • oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc — クエリの次の行を連想配列で返す
  • oci_fetch_object — クエリの次の行をオブジェクトとして返す
  • oci_fetch_row — クエリの次の行を配列で返す
  • oci_field_is_null — フェッチしたフィールドが null であるかどうかを確認する
  • oci_field_name — 文からのフィールド名を返す
  • oci_field_precision — フィールドの精度を問い合わせる
  • oci_field_scale — フィールドの桁数を問い合わせる
  • oci_field_size — フィールドサイズを返す
  • oci_field_type — フィールドのデータ型の名前を返す
  • oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる
  • oci_free_descriptor — ディスクリプタを解放する
  • oci_free_statement — 文やカーソルに関連付けられた全てのリソースを解放する
  • oci_get_implicit_resultset — Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す
  • oci_lob_copy — ラージオブジェクトをコピーする
  • oci_lob_is_equal — 2 つの LOB/FILE ロケータの等価性を比較する
  • oci_new_collection — 新しいコレクションオブジェクトを割り当てる
  • oci_new_connect — 一意な接続を使って Oracle サーバーへ接続する
  • oci_new_cursor — 新規カーソル (ステートメントハンドル) を割り当て、それを返す
  • oci_new_descriptor — 空の新規 LOB あるいは FILE ディスクリプタを初期化する
  • oci_num_fields — ある文における結果のカラム数を返す
  • oci_num_rows — 文の実行で作用された行数を取得する
  • oci_parse — 実行のために Oracle の文をパースする
  • oci_password_change — Oracle ユーザーのパスワードを変更する
  • oci_pconnect — 持続的接続を使用してOracle データベースに接続する
  • oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF
  • oci_result — フェッチした行からフィールドの値を取得する
  • oci_rollback — 未解決のデータベーストランザクションをロールバックする
  • oci_server_version — Oracle データベースのバージョンを返す
  • oci_set_action — アクション名を設定します
  • oci_set_call_timeout — Sets a millisecond timeout for database calls
  • oci_set_client_identifier — クライアント識別子を設定します
  • oci_set_client_info — クライアント情報を設定する
  • oci_set_db_operation — Sets the database operation
  • oci_set_edition — データベース・エディション を設定します
  • oci_set_module_name — モジュール名を設定します
  • oci_set_prefetch — クエリがプリフェッチする行数を設定する
  • oci_set_prefetch_lob — CLOB や BLOB ごとにプリフェッチするデータサイズを設定する
  • oci_statement_type — ステートメントの種類を返す
  • oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF


PHP の配列を Oracle PL/SQL の配列に名前でバインドする

  • ≪ OCI8 関数
  • oci_bind_by_name ≫
  • PHP Manual
  • OCI8 関数
  • PHP の配列を Oracle PL/SQL の配列に名前でバインドする

oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — PHP の配列を Oracle PL/SQL の配列に名前でバインドする

説明

oci_bind_array_by_name(
resource $statement,
string $param,
array &$var,
int $max_array_length,
int $max_item_length = -1,
int $type = SQLT_AFC
): bool

oci_bind_array_by_name() は、PHP の配列 var を Oracle のプレースホルダ param にバインドします。 このプレースホルダは Oracle PL/SQL の配列を指しています。 入力変数あるいは出力変数のどちらとして使用されるのかは、 実行時に決められます。

パラメータ

statement

有効な OCI ステートメント識別子

param

Oracle のプレースホルダ

var

配列

max_array_length

入力配列および結果の配列の両方の最大長を設定する

max_item_length

配列要素の最大長を設定する。もし指定されない、もしくは -1 が指定された場合、oci_bind_array_by_name() は入力の配列の中で最も長い要素を探し、その長さを最大長とする。

type

PL/SQL 配列の項目の型を指定するために利用される。 指定可能な型については以下を参照のこと。

  • SQLT_NUM - NUMBER の配列

  • SQLT_INT - INTEGER の配列 (注意: INTEGER は、実際には NUMBER(38) のシノニムだが、 SQLT_NUM ではこの場合うまく動作しない)。

  • SQLT_FLT - FLOAT の配列

  • SQLT_AFC - CHAR の配列

  • SQLT_CHR - VARCHAR2 の配列

  • SQLT_VCS - VARCHAR の配列

  • SQLT_AVC - CHARZ の配列

  • SQLT_STR - STRING の配列

  • SQLT_LVC - LONG VARCHAR の配列

  • SQLT_ODT - DATE の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_bind_array_by_name() の例

<?php

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$create = "CREATE TABLE bind_example(name VARCHAR(20))";
$stid = oci_parse($conn, $create);
oci_execute($stid);

$create_pkg = "
CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
PROCEDURE iobind(c1 IN OUT ARRTYPE);
END ARRAYBINDPKG1;";
$stid = oci_parse($conn, $create_pkg);
oci_execute($stid);

$create_pkg_body = "
CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
CURSOR CUR IS SELECT name FROM bind_example;
PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
BEGIN
-- Bulk Insert
FORALL i IN INDICES OF c1
INSERT INTO bind_example VALUES (c1(i));

-- Fetch and reverse
IF NOT CUR%ISOPEN THEN
OPEN CUR;
END IF;
FOR i IN REVERSE 1..5 LOOP
FETCH CUR INTO c1(i);
IF CUR%NOTFOUND THEN
CLOSE CUR;
EXIT;
END IF;
END LOOP;
END iobind;
END ARRAYBINDPKG1;";
$stid = oci_parse($conn, $create_pkg_body);
oci_execute($stid);

$stid = oci_parse($conn, "BEGIN arraybindpkg1.iobind(:c1); END;");
$array = array("one", "two", "three", "four", "five");
oci_bind_array_by_name($stid, ":c1", $array, 5, -1, SQLT_CHR);
oci_execute($stid);

var_dump($array);

?>


Oracle プレースホルダに PHP 変数をバインドする

  • ≪ oci_bind_array_by_name
  • oci_cancel ≫
  • PHP Manual
  • OCI8 関数
  • Oracle プレースホルダに PHP 変数をバインドする

oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Oracle プレースホルダに PHP 変数をバインドする

説明

oci_bind_by_name(
resource $statement,
string $param,
mixed &$var,
int $max_length = -1,
int $type = 0
): bool

PHP の変数 var を Oracle プレースホルダ param にバインドします。 バインドは Oracle データベースのパフォーマンスに影響を及ぼす重要な仕組みで、 SQL インジェクション攻撃を防ぐための方法にもなります。

バインドを使うとデータベースでステートメントのコンテキストを (たとえ別のユーザーやプロセスが実行したものであっても) 再利用することができるようになります。 バインドによって SQL インジェクションの心配を軽減できる理由は、 バインド変数で代入したデータが決して SQL 文の一部と見なされることがないからです。 クォートやエスケープは不要です。

バインドする PHP 変数の中身を変更してステートメントを再実行するときにも、 ステートメントをパースしなおしたり変数をバインドしなおしたりする必要はありません。

Oracle のバインド変数は、データベースに渡す値に使う IN 変数と PHP に返される値に使う OUT 変数のふたつに大別できます。 バインド変数は IN あるいは OUT のどちらかの形式になります。バインド変数を入力用に使うか出力用に使うかは、 実行時に決まります。

OUT 変数を使う場合は max_length を指定しなければなりません。 これを用いて、返される値を格納するのに必要なメモリを PHP が確保します。

IN 変数の場合も、もし PHP の変数にさまざまな値を格納してステートメントを何度も実行するのであれば max_length を設定しておくことを推奨します。 そうしないと、最初に渡した PHP の変数の値にあわせて Oracle がデータの長さを切り詰めてしまう可能性があります。 最大長がどの程度になるかわからない場合は現在のデータサイズで oci_bind_by_name() を再コールしてから oci_execute() を実行するようにしましょう。 不必要に大きなサイズでバインドすると、 データベースのプロセスのメモリ使用量に影響を及ぼします。

バインドは、Oracle にデータをどのメモリアドレスから読み込むのかを指示します。 IN 変数の場合、oci_execute() がコールされたときにそのメモリアドレスに正しいデータがなければなりません。 つまり、バインドされる変数は実行時までスコープ内に残っていなければならないということです。 もしそうでなければ、 "ORA-01460: unimplemented or unreasonable conversion requested" のような予期せぬエラーが発生します。 OUT 変数の場合は、PHP の変数に何も値が格納されないといったことになるでしょう。

繰り返し実行されるステートメントで決して値が変わることのないバインド変数を使っていると、 Oracle のオプティマイザが最適な実行プランを選びにくくなる可能性があります。 実行に長い時間がかかり、再実行されることもめったにないようなステートメントは、 バインドの恩恵を受けられないでしょう。 しかし、どちらの場合であっても、文字列を連結して SQL 文を作るよりはバインドを使ったほうが安全です。 ユーザーの入力をフィルタリングせずに埋め込んでしまうというリスクをなくせるからです。

パラメータ

statement

有効な OCI8 ステートメント識別子。

param

コロンを先頭につけたバインド変数プレースホルダをステートメント内で使います。 コロンは param では必須ではありません。 Oracle はクエスチョンマークをプレースホルダとして使いません。

var

param に関連づける PHP の変数。

max_length

バインド時の最大長。-1 に設定した場合、 var の現在の長さを最大長として設定します。 この場合は、oci_bind_by_name() がコールされたときに var が存在してデータが格納されている必要があります。

type

Oracle がデータを扱うときのデータ型。デフォルトの type は SQLT_CHR です。 Oracle は、可能な場合はこの型とデータベースのカラム (あるいは PL/SQL の変数) の型の間で変換を行います。

抽象データ型 (LOB/ROWID/BFILE) をバインドする必要がある場合、まず oci_new_descriptor() 関数を使用してこれを確保する必要があります。 length は抽象データ型用には 使用されず、-1 を設定する必要があります。

type に設定できる値は以下のとおりです。

  • SQLT_BFILEE or OCI_B_BFILE - BFILE 用

  • SQLT_CFILEE or OCI_B_CFILEE - CFILE 用

  • SQLT_CLOB or OCI_B_CLOB - CLOB 用

  • SQLT_BLOB or OCI_B_BLOB - BLOB 用

  • SQLT_RDD or OCI_B_ROWID - ROWID 用

  • SQLT_NTY or OCI_B_NTY - 名前付けされたデータ型用

  • SQLT_INT or OCI_B_INT - integer 用

  • SQLT_CHR - VARCHAR 用

  • SQLT_BIN or OCI_B_BIN - RAW カラム用

  • SQLT_LNG - LONG カラム用

  • SQLT_LBI - LONG RAW カラム用

  • SQLT_RSET - カーソル用。 oci_new_cursor() により、前もって生成されたもの。

  • SQLT_BOL あるいは OCI_B_BOL PL/SQL の BOOLEAN 用 (Oracle Database 12c 以降が必要)

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_bind_by_name() によるデータの挿入

<?php

// このようなテーブルを作ります
// CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");

$id = 1;
$text = "Data to insert ";
oci_bind_by_name($stid, ":id_bv", $id);
oci_bind_by_name($stid, ":text_bv", $text);
oci_execute($stid);

// テーブルに入る内容: 1, 'Data to insert '

?>

例2 一度組み立てたものを複数回実行

<?php

// このようなテーブルを作ります
// CREATE TABLE mytab (id NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$a = array(1,3,5,7,11); // 挿入するデータ

$stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
oci_bind_by_name($stid, ':bv', $v, 20);
foreach ($a as $v) {
$r = oci_execute($stid, OCI_DEFAULT); // 自動コミットはしません
}
oci_commit($conn); // すべてをここでコミットします

// テーブルには次の 5 行が含まれます: 1, 3, 5, 7, 11

oci_free_statement($stid);
oci_close($conn);

?>

例3 foreach ループでのバインド

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
$stid = oci_parse($conn, $sql);

$ba = array(':dname' => 'IT Support', ':loc' => 1700);

foreach ($ba as $key => $val) {

// oci_bind_by_name($stid, $key, $val) ではうまくいきません。
// これは、すべてのプレースホルダを同じ内容にバインドしてしまうからです。
// $val ではなく、データの実際の位置を表す $ba[$key] を使いましょう。
oci_bind_by_name($stid, $key, $ba[$key]);
}

oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
foreach ($row as $item) {
print $item."<br>\n";
}

oci_free_statement($stid);
oci_close($conn);

?>

例4 WHERE 句でのバインド

<?php

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
$stid = oci_parse($conn, $sql);
$didbv = 60;
oci_bind_by_name($stid, ':didbv', $didbv);
oci_execute($stid);
while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
echo $row['LAST_NAME'] ."<br>\n";
}

// 出力は
// Austin
// Ernst
// Hunold
// Lorentz
// Pataballa

oci_free_statement($stid);
oci_close($conn);

?>

例5 LIKE 句でのバインド

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

// 'South' からはじまるすべての都市を探します
$stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
$city = 'South%'; // '%' は SQL でのワイルドカードです
oci_bind_by_name($stid, ":bv", $city);
oci_execute($stid);
oci_fetch_all($stid, $res);

foreach ($res['CITY'] as $c) {
print $c . "<br>\n";
}
// 出力は
// South Brunswick
// South San Francisco
// Southlake

oci_free_statement($stid);
oci_close($conn);

?>

例6 REGEXP_LIKE でのバインド

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

// 'ing' を含むすべての都市を探します
$stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
$city = '.*ing.*';
oci_bind_by_name($stid, ":bv", $city);
oci_execute($stid);
oci_fetch_all($stid, $res);

foreach ($res['CITY'] as $c) {
print $c . "<br>\n";
}
// 出力は
// Beijing
// Singapore

oci_free_statement($stid);
oci_close($conn);

?>

IN 句の中の条件数が少なくて固定なのであれば、個々にバインド変数を割り当てればいいでしょう。 実行時に不明な値は NULL が設定されます。 こうすればひとつのステートメントをすべてのユーザーで使い回すことができ、 Oracle の DB キャッシュの効率を最大化させることができます。

例7 IN 句での複数の値のバインド

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
$stid = oci_parse($conn, $sql);
$mye1 = 103;
$mye2 = 104;
$mye3 = NULL; // pretend we were not given this value
oci_bind_by_name($stid, ':e1', $mye1);
oci_bind_by_name($stid, ':e2', $mye2);
oci_bind_by_name($stid, ':e3', $mye3);
oci_execute($stid);
oci_fetch_all($stid, $res);
foreach ($res['LAST_NAME'] as $name) {
print $name ."<br>\n";
}

// 出力は
// Ernst
// Hunold

oci_free_statement($stid);
oci_close($conn);

?>

例8 クエリが返す ROWID のバインド

<?php

// このようなテーブルを作ります
// CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
// INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
// COMMIT;

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
$id = 1;
oci_bind_by_name($stid, ':id_bv', $id);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
$rid = $row['ROWID'];
$name = $row['NAME'];

// 名前を大文字に変換してそれを保存します
$name = strtoupper($name);
$stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
oci_bind_by_name($stid, ':n_bv', $name);
oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
oci_execute($stid);

// テーブルに入る内容: 1, 100, CHRIS

oci_free_statement($stid);
oci_close($conn);

?>

例9 INSERT での ROWID のバインド

<?php

// この例では id と name を挿入し、それから salary を更新します
// このようなテーブルを作ります
// CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
//
// Based on original ROWID example by thies at thieso dot net (980221)

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
RETURNING ROWID INTO :rid";

$ins_stid = oci_parse($conn, $sql);

$rowid = oci_new_descriptor($conn, OCI_D_ROWID);
oci_bind_by_name($ins_stid, ":id_bv", $id, 10);
oci_bind_by_name($ins_stid, ":name_bv", $name, 32);
oci_bind_by_name($ins_stid, ":rid", $rowid, -1, OCI_B_ROWID);

$sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
$upd_stid = oci_parse($conn, $sql);
oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
oci_bind_by_name($upd_stid, ":salary", $salary, 32);

// 挿入する id と name
$data = array(1111 => "Larry",
2222 => "Bill",
3333 => "Jim");

// それぞれの salary
$salary = 10000;

// 挿入し、その後すぐに各行を更新します
foreach ($data as $id => $name) {
oci_execute($ins_stid);
oci_execute($upd_stid);
}

$rowid->free();
oci_free_statement($upd_stid);
oci_free_statement($ins_stid);

// 新しい行を表示します
$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid);
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
var_dump($row);
}

oci_free_statement($stid);
oci_close($conn);

?>

例10 PL/SQL ストアドファンクションでのバインド

<?php

// PHP プログラムを実行する前に、ストアドファンクションを
// SQL*Plus あるいは SQL Developer で作ります
//
// CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
// BEGIN
// RETURN p * 3;
// END;

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$p = 8;

$stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
oci_bind_by_name($stid, ':p', $p);

// 戻り値は OUT 変数に格納されます。デフォルトの型は文字列型なので、
// length が 40 ということは最大で 40 まで返される可能性があるということです
oci_bind_by_name($stid, ':r', $r, 40);

oci_execute($stid);

print "$r\n"; // 24 と表示します

oci_free_statement($stid);
oci_close($conn);

?>

例11 PL/SQL ストアドプロシージャでのパラメータのバインド

<?php

// PHP プログラムを実行する前に、ストアドプロシージャを
// SQL*Plus あるいは SQL Developer で作ります
//
// CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
// BEGIN
// p2 := p1 * 2;
// END;

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$p1 = 8;

$stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
oci_bind_by_name($stid, ':p1', $p1);

// プロシージャの 2 番目のパラメータは OUT 変数です。デフォルトの型は文字列型なので、
// length が 40 ということは最大で 40 まで返される可能性があるということです
oci_bind_by_name($stid, ':p2', $p2, 40);

oci_execute($stid);

print "$p2\n"; // 16 と表示します

oci_free_statement($stid);
oci_close($conn);

?>

例12 CLOB 列のバインド

<?php

// 実行する前にテーブルを作成します。
// CREATE TABLE mytab (mykey NUMBER, myclob CLOB);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$mykey = 12343; // この例のための任意のキー

$sql = "INSERT INTO mytab (mykey, myclob)
VALUES (:mykey, EMPTY_CLOB())
RETURNING myclob INTO :myclob";

$stid = oci_parse($conn, $sql);
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
oci_execute($stid, OCI_DEFAULT);
$clob->save("A very long string");

oci_commit($conn);

// CLOB データを取得します

$query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';

$stid = oci_parse ($conn, $query);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_execute($stid);

print '<table border="1">';
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
// ループ内で、大きなサイズの変数を解放してから次のフェッチに進めます。
// これで、PHP のピークメモリ利用量を抑えます。
unset($row);
}
print '</table>';

?>

例13 PL/SQL の BOOLEAN のバインド

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$plsql =
"begin
:output1 := true;
:output2 := false;
end;";

$s = oci_parse($c, $plsql);
oci_bind_by_name($s, ':output1', $output1, -1, OCI_B_BOL);
oci_bind_by_name($s, ':output2', $output2, -1, OCI_B_BOL);
oci_execute($s);
var_dump($output1); // true
var_dump($output2); // false

?>

注意

警告

クォートは不要なので、 addslashes() を oci_bind_by_name() と同時に使わないでください。 自動的に追加されたクォートはデータベースの中にそのまま書き込まれてしまいます。 oci_bind_by_name() はデータをそのままの形で追加し、クォートやエスケープ文字の除去は行わないからです。

注意:

WHERE 句の中の CHAR 型のカラムに文字列をバインドするときには、 Oracle における CHAR 型のカラムの比較が スペースで埋めた (固定長形式で) 行われることを覚えておきましょう。 WHERE 句を期待通りに動作させるには、 PHP の変数側でもスペースを追加してカラムの幅と同じにしておく必要があります。

注意:

PHP の var 引数は参照渡しです。 ループの形式によっては期待通りの動きをしないこともあります。

<?php
foreach ($myarray as $key => $value) {
oci_bind_by_name($stid, $key, $value);
}
?>

これは、それぞれのキーに対して $value の指す場所をバインドします。 つまり、すべてのバインド変数の値は ループの最後の処理で $value が指す値となります。 期待通りに動かすには、次のようにします。

<?php
foreach ($myarray as $key => $value) {
oci_bind_by_name($stid, $key, $myarray[$key]);
}
?>

参考

  • oci_bind_array_by_name() - PHP の配列を Oracle PL/SQL の配列に名前でバインドする
  • oci_parse() - 実行のために Oracle の文をパースする


カーソルからの読み込みをキャンセルする

  • ≪ oci_bind_by_name
  • oci_client_version ≫
  • PHP Manual
  • OCI8 関数
  • カーソルからの読み込みをキャンセルする

oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — カーソルからの読み込みをキャンセルする

説明

oci_cancel(resource $statement): bool

カーソルを無効にして関連付けられた全てのリソースを開放し、 読み込みをキャンセルします。

パラメータ

statement

OCI ステートメント

戻り値

成功した場合に true を、失敗した場合に false を返します。


Oracle クライアント・ライブラリのバージョンを返す

  • ≪ oci_cancel
  • oci_close ≫
  • PHP Manual
  • OCI8 関数
  • Oracle クライアント・ライブラリのバージョンを返す

oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Oracle クライアント・ライブラリのバージョンを返す

説明

oci_client_version(): string

PHP がリンクされている Oracle C クライアント・ライブラリのバージョン番号を含む文字列を返します。

パラメータ

ありません

戻り値

文字列としてバージョン番号を返します。

例

例1 oci_client_version() の例

<?php
echo "Client Version: " . oci_client_version(); // Client version: 19.9.0.0.0
?>

注意

注意:

10gR2 より前の Oracle ライブラリには、クライアント・ライブラリのバージョン番号を取得するための 基礎となる機能がありません。この場合、文字列 "Unknown" が返されます。

参考

  • oci_server_version() - Oracle データベースのバージョンを返す


Oracleとの接続を閉じる

  • ≪ oci_client_version
  • oci_commit ≫
  • PHP Manual
  • OCI8 関数
  • Oracleとの接続を閉じる

oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Oracleとの接続を閉じる

説明

oci_close(resource $connection): ?bool

接続 connection を閉じます。 他のいかなるリソースも利用しない、なおかつ oci_connect() または oci_new_connect() で作成された場合、 基礎となるデータベース接続が閉じられます。

もはや不要となった接続を閉じることを推奨します。 なぜなら、これにより他のユーザーがデータベースリソースを利用できるようになるからです。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

戻り値

oci8.old_oci_close_semantics が有効な場合、null を返します。 そうでない場合、true を返します。

例

例1 接続を閉じる

基礎となるデータベース接続がきちんと終了され、データベースリソースが解放されることを確実にするために、 接続に関連したリソースは閉じられるべきです。

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM departments');
$r = oci_execute($stid);
oci_fetch_all($stid, $res);
var_dump($res);

// 接続を閉じるときにステートメント識別子を解放します
oci_free_statement($stid);
oci_close($conn);

?>

例2 参照の全てが閉じられるまでデータベース接続は閉じられません

基礎となるデータベースへの接続が閉じられる前に 接続の内部的な参照回数識別子はゼロで無ければいけません

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM departments'); // これは $conn の参照回数を増やします
oci_execute($stid);
oci_fetch_all($stid, $res);
var_dump($res);

oci_close($conn);

// $conn はもはやスクリプトで使用できませんが、基礎となるデータベース接続は
// $stid が解放されるまで開かれたまま保たれます。
var_dump($conn); // NULL を出力

// PHP が活動していない間にターミナルウィンドウで Oracle の V$SESSION ビューを
// 参照すると、データベースユーザーがまだ接続されていると表示します。
sleep(10);

// $stid が解放されると、データベース接続は物理的に閉じられます。
oci_free_statement($stid);

// PHP が活動していない間にターミナルウィンドウで Oracle の V$SESSION ビューを
// 参照すると、データベースユーザーが切断されたと表示します。
sleep(10);

?>

例3 一回以上開かれた接続を閉じる

データベースクレデンシャルが再利用されるときは、基礎となるデータベース接続が閉じられる前に、 両方の接続がともに閉じられていなければいけません。

<?php

$conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

// 同じ基礎となるデータベース接続を再利用するクレデンシャルを使用すると、
// $conn1 上でなされたコミットされていない変更は全て、 $conn2 で認識できます。
$conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

// PHP が活動していない間にターミナルウィンドウで Oracle の V$SESSION ビューを
// 参照すると、データベースユーザーが一つだけ接続されたと表示します。
sleep(10);

oci_close($conn1); // 基礎となるデータベース接続を閉じません。
var_dump($conn1); // 変数 $conn1 がもはや利用できないので NULL を出力します
var_dump($conn2); // $conn2 はまだ有効な接続リソースと表示されます。

?>

例4 変数がスコープから外れると接続が閉じられます

接続を参照する変数の全てがスコープを外れてPHPにより解放されると、 （必要に応じて）ロールバックが発生します。 そしてデータベースへの基礎となる接続が閉じられます。

<?php

function myfunc() {
$conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
oci_execute($stid, OCI_NO_AUTO_COMMIT);
return "Finished";
}

$r = myfunc();
// この時点でロールバックが発生し、基礎となるデータベース接続が閉じられます。

print $r; // 関数の戻り値 "Finished" を表示します

?>

注意

注意:

接続識別子に依存する変数、たとえば oci_parse() により返される ステートメント識別子のような変数は、基礎となるデータベース接続が閉じられる前に 解放されなければいけません。

注意:

oci_close() 関数は oci_pconnect() で作成された基礎となるデータベース接続を 閉じません。

参考

  • oci_connect() - Oracle データベースに接続する
  • oci_free_statement() - 文やカーソルに関連付けられた全てのリソースを解放する


未解決のトランザクションをコミットする

  • ≪ oci_close
  • oci_connect ≫
  • PHP Manual
  • OCI8 関数
  • 未解決のトランザクションをコミットする

oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — 未解決のトランザクションをコミットする

説明

oci_commit(resource $connection): bool

Oracle接続connection 上の未解決なトランザクションをコミットします。 コミットすると、現在のトランザクションを終了してすべての変更を確定させます。 また、保持しているロックをすべて解放します。

トランザクションが始まるのは、データを変更する最初の SQL 文が OCI_NO_AUTO_COMMIT フラグつきで oci_execute() によって実行されたときです。 それ以降、他の文によるデータの変更も同じトランザクションの一部となります。 トランザクション内でのデータの変更は、 そのトランザクションがコミットあるいはロールバックされるまでは一時的なものとなります。 データベース上の他のユーザーは、 トランザクションがコミットされるまでその変更内容を見ることができません。

データを追加したり更新したりする際には、 リレーショナルデータの一貫性やパフォーマンスなどを考慮して トランザクションを使うことを推奨します。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_commit() の例

<?php

// 複数のテーブルに挿入し、エラーが発生したときにはロールバックします

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

// OCI_NO_AUTO_COMMIT フラグは、INSERT の直後にコミットしないよう Oracle に指示します
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
oci_rollback($conn); // 両方のテーブルへの変更をロールバックします
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

// 両方のテーブルへの変更をコミットします
$r = oci_commit($conn);
if (!$r) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

?>

注意

注意:

トランザクションは接続を閉じたとき、 もしくはスクリプトの終了時のいずれの場合でも すぐに自動的にロールバックされます。 トランザクションをコミットするには oci_commit() をコールする必要があります。

OCI_COMMIT_ON_SUCCESS モードを指定するか、 あるいはデフォルトの状態で oci_execute() をコールすると、 それ以前の未コミットのトランザクションをコミットします。

CREATE や DROP といった Oracle の DDL は、未コミットのトランザクションを自動的にコミットします。

参考

  • oci_execute() - 文を実行する
  • oci_rollback() - 未解決のデータベーストランザクションをロールバックする


Oracle データベースに接続する

  • ≪ oci_commit
  • oci_define_by_name ≫
  • PHP Manual
  • OCI8 関数
  • Oracle データベースに接続する

oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Oracle データベースに接続する

説明

oci_connect(
string $username,
string $password,
?string $connection_string = null,
string $encoding = "",
int $session_mode = OCI_DEFAULT
): resource|false

他のほとんどの OCI8 コールで必要な接続 ID を返します。

パフォーマンスを向上させるため、 ほとんどのアプリケーションは oci_connect() ではなく、 oci_pconnect() 経由で持続的接続を使うべきです。 接続の管理及び接続プーリングについての一般的な情報は 接続のハンドリングをご覧下さい。

同一の引数で oci_connect() を呼び出すと、 ２回目以降は最初の呼び出しで返された接続ハンドルを返します。 これは、あるハンドル内のトランザクションが、他のハンドル内にも あることを意味します、なぜなら、それらは同一の 基礎となるデータベース接続を使用するからです。 もし２つのハンドルを互いにトランザクション的に分離する必要があれば、 替わりに oci_new_connect() を使用してください。

パラメータ

username

Oracle ユーザー名

password

username に対するパスワード

connection_string

接続先の Oracle インスタンス。 » Easy Connect 文字列、tnsnames.ora ファイルの接続文字列、あるいはローカルの Oracle インスタンス名を指定します。

省略した場合、または null の場合、PHP は環境変数 TWO_TASK (Linux) あるいは LOCAL (Windows) と ORACLE_SID を用いて接続先の Oracle インスタンス を判断します。

Easy Connect 方式を使うには、PHP を Oracle 10g 以降のクライアントライブラリとリンクさせる必要があります。Oracle 10g の Easy Connect 文字列の形式は [//]host_name[:port][/service_name] です。Oracle 11g 以降の場合は、この構文は [//]host_name[:port][/service_name][:server_type][/instance_name] となります。 Oracle 19c では、さらにオプションが追加されています。 タイムアウトや keep-alive の設定を含みます。詳細は Oracle のドキュメントを参照して下さい。 サービス名を調べるには、Oracle のユーティリティ lsnrctl status をデータベースサーバー上で実行します。

tnsnames.ora ファイルは Oracle Net のサーチパス上にあります。 サーチパスに含まれるのは /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin, /etc です。 もうひとつの方法として、 TNS_ADMIN を指定して $TNS_ADMIN/tnsnames.ora を読み込ませることもできます。 ウェブデーモンにそのファイルの読み込み権限を与えておきましょう。

encoding

Oracle クライアントライブラリが使う文字セットを指定します。 これは、データベースが用いる文字セットと一致させる必要はありません。 一致していない場合は、Oracle が最善を尽くしてデータベースの文字セットとの間の変換を行います。 文字セットによっては、この変換結果がうまく使えないこともあります。 また、変換にはそれなりの時間を要します。

省略した場合は、 Oracle クライアントライブラリは環境変数 NLS_LANG の値をもとに文字セットを判断します。

このパラメータを渡すことで、 接続に要する時間を短縮できます。

session_mode

このパラメータは PHP 5 (PECL OCI8 1.1) 以降で使え、 OCI_DEFAULT、 OCI_SYSOPER そして OCI_SYSDBA といった値を指定することができます。OCI_SYSOPER あるいは OCI_SYSDBA を指定した場合は、 この関数は外部の証明書を使った特権接続の確立を試みます。 特権接続は、デフォルトでは無効になっています。有効にするには oci8.privileged_connect を On に設定しなければなりません。

PHP 5.3 (PECL OCI8 1.3.4) 以降、 OCI_CRED_EXT モードを使えるようになりました。 これは、Oracle に外部認証あるいは OS 認証を使うよう指示します。 どちらかをデータベースで設定しておかなければなりません。 OCI_CRED_EXT フラグを使えるのは、ユーザー名が "/" でパスワードが空のときだけです。 oci8.privileged_connect は On あるいは Off のどちらでもかまいません。

OCI_CRED_EXT は、 OCI_SYSOPER あるいは OCI_SYSDBA モードと組み合わせて使います。

OCI_CRED_EXT は、セキュリティ上の理由により Windows ではサポートされていません。

戻り値

接続 ID、もしくはエラー時は false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | connection_string は、 nullable になりました。

例

例1 Easy Connect 構文を使った基本的な oci_connect() の使用例

<?php

// "localhost" マシン上の XE サービス(例えばデータベース)に接続します。
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

?>

例2 Network Connect 名を使った基本的な oci_connect() の使用例

<?php

// tnsnames.ora ファイルに記載された MYDB データベースに接続します。
// MYDB 用の tnsnames.ora エントリーの一例です。
// MYDB =
// (DESCRIPTION =
// (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
// (CONNECT_DATA =
// (SERVER = DEDICATED)
// (SERVICE_NAME = XE)
// )
// )

$conn = oci_connect('hr', 'welcome', 'MYDB');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

?>

例3 oci_connect() での明示的な文字セットの指定

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

?>

例4 oci_connect() での複数コールの使用

<?php

$c1 = oci_connect("hr", "welcome", 'localhost/XE');
$c2 = oci_connect("hr", "welcome", 'localhost/XE');

// 同一の基礎となるデータベース接続を使用することを意味する、
// 同一の PHP リソース id を $c1 及び $c2 の両方が示します。
echo "c1 is $c1<br>\n";
echo "c2 is $c2<br>\n";

function create_table($conn)
{
$stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
oci_execute($stmt);
echo "Created table<br>\n";
}

function drop_table($conn)
{
$stmt = oci_parse($conn, "drop table hallo");
oci_execute($stmt);
echo "Dropped table<br>\n";
}

function insert_data($connname, $conn)
{
$stmt = oci_parse($conn, "insert into hallo
values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
oci_execute($stmt, OCI_DEFAULT);
echo "$connname inserted row without committing<br>\n";
}

function rollback($connname, $conn)
{
oci_rollback($conn);
echo "$connname rollback<br>\n";
}

function select_data($connname, $conn)
{
$stmt = oci_parse($conn, "select * from hallo");
oci_execute($stmt, OCI_DEFAULT);
echo "$connname ----selecting<br>\n";
while (oci_fetch($stmt)) {
echo " " . oci_result($stmt, "TEST") . "<br>\n";
}
echo "$connname ----done<br>\n";
}

create_table($c1);

insert_data('c1', $c1); // c1 を使用して行を挿入
sleep(2); // ２行目で異なるタイムスタンプを表示するためにスリープします
insert_data('c2', $c2); // c2 を使用して行を挿入

select_data('c1', $c1); // 両方の挿入結果が返されます
select_data('c2', $c2); // 両方の挿入結果が返されます

rollback('c1', $c1); // c1 を使用してロールパック

select_data('c1', $c1); // 両方の挿入行為がロールバックされました
select_data('c2', $c2);

drop_table($c1);

// 接続のうちの一つを閉じると、その PHP 変数が利用できなくなりますが、
// もう一つは使用できます。
oci_close($c1);
echo "c1 is $c1<br>\n";
echo "c2 is $c2<br>\n";

// 出力です。
// c1 is Resource id #5
// c2 is Resource id #5
// Created table
// c1 inserted row without committing
// c2 inserted row without committing
// c1 ----selecting
// 09-DEC-09 12:14:43
// 09-DEC-09 12:14:45
// c1 ----done
// c2 ----selecting
// 09-DEC-09 12:14:43
// 09-DEC-09 12:14:45
// c2 ----done
// c1 rollback
// c1 ----selecting
// c1 ----done
// c2 ----selecting
// c2 ----done
// Dropped table
// c1 is
// c2 is Resource id #5

?>

注意

注意:

OCI8 拡張モジュールのインストールや設定に不備があると、 接続時に問題やエラーが発生します。解決策は インストール/設定 を参照ください。

参考

  • oci_pconnect() - 持続的接続を使用してOracle データベースに接続する
  • oci_new_connect() - 一意な接続を使って Oracle サーバーへ接続する
  • oci_close() - Oracleとの接続を閉じる


PHP の変数を、クエリで取得するカラムに関連づける

  • ≪ oci_connect
  • oci_error ≫
  • PHP Manual
  • OCI8 関数
  • PHP の変数を、クエリで取得するカラムに関連づける

oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — PHP の変数を、クエリで取得するカラムに関連づける

説明

oci_define_by_name(
resource $statement,
string $column,
mixed &$var,
int $type = 0
): bool

PHP の変数を、oci_fetch() で取得するクエリのカラムに関連づけます。

oci_define_by_name() は、 oci_execute() を実行する前にコールしなければなりません。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

column

クエリで使用するカラム名。

Oracle のデフォルトである大文字小文字を区別しないカラム名では大文字を使います。 大文字小文字を区別するカラム名の場合は、正確なカラム名を使います。

var

返されるカラムの値を格納する PHP 変数。

type

返されるデータの型。一般的には不要です。 Oracle 式のデータ変換は行われないことに注意しましょう。たとえば、 SQLT_INT は無視され、返されるデータの型は SQLT_CHR のままとなります。

オプションで、oci_new_descriptor() を使って LOB/ROWID/BFILE の領域を確保することもできます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_define_by_name() の例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);

// 実行する前に定義しなければなりません
oci_define_by_name($stid, 'LOCATION_ID', $locid);
oci_define_by_name($stid, 'CITY', $city);

oci_execute($stid);

// フェッチするたびに、さきほど定義した変数に次の行のデータが格納されます
while (oci_fetch($stid)) {
echo "Location id $locid is $city<br>\n";
}

// 表示:
// Location id 1000 is Roma
// Location id 1100 is Venice

oci_free_statement($stid);
oci_close($conn);

?>

例2 oci_define_by_name() での大文字小文字を区別するカラム名の使用

<?php

/*
実行する前に、大文字小文字を区別するカラム名のテーブルを作っておきます
CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM mytab');

// 大文字小文字を区別しないカラム名の場合は、大文字を使います
oci_define_by_name($stid, 'ID', $id);

// 大文字小文字を区別するカラム名の場合は、カラム名にあわせます
oci_define_by_name($stid, 'MyDescription', $mydesc);

oci_execute($stid);

while (oci_fetch($stid)) {
echo "id $id is $mydesc<br>\n";
}

// 表示:
// id 1 is Iced Coffee

oci_free_statement($stid);
oci_close($conn);

?>

例3 oci_define_by_name() での LOB カラムの使用

<?php

/*
実行する前にテーブルを作ります
CREATE TABLE mytab (id NUMBER, fruit CLOB);
INSERT INTO mytab (id, fruit) values (1, 'apple');
INSERT INTO mytab (id, fruit) values (2, 'orange');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM mytab');

// 実行する前に定義しなければなりません
oci_define_by_name($stid, 'ID', $id);
oci_define_by_name($stid, 'FRUIT', $fruit); // $fruit will become a LOB descriptor

oci_execute($stid);

while (oci_fetch($stid)) {
echo $id . " is " . $fruit->load(100) . "<br>\n";
}

// 表示:
// 1 is apple
// 2 is orange

$fruit->free();
oci_free_statement($stid);
oci_close($conn);

?>

例4 oci_define_by_name() での型の明示

<?php

/*
実行する前にテーブルを作ります
CREATE TABLE mytab (id NUMBER, fruit CLOB);
INSERT INTO mytab (id, fruit) values (1, 'apple');
INSERT INTO mytab (id, fruit) values (2, 'orange');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM mytab');

// 実行する前に定義しなければなりません
oci_define_by_name($stid, 'ID', $id);

$fruit = oci_new_descriptor($conn, OCI_D_LOB);
oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

oci_execute($stid);

while (oci_fetch($stid)) {
echo $id . " is " . $fruit->load(100) . "<br>\n";
}

// 表示:
// 1 is apple
// 2 is orange

$fruit->free();
oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_fetch() - クエリの次の行を内部バッファに取得する
  • oci_new_descriptor() - 空の新規 LOB あるいは FILE ディスクリプタを初期化する


最後に見つかったエラーを返す

  • ≪ oci_define_by_name
  • oci_execute ≫
  • PHP Manual
  • OCI8 関数
  • 最後に見つかったエラーを返す

oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — 最後に見つかったエラーを返す

説明

oci_error(?resource $connection_or_statement = null): array|false

最後に見つかったエラーを返します。

この関数は、エラーが発生した直後にコールしなければなりません。 文の実行が成功すると、エラーはクリアされてしまいます。

パラメータ

connection_or_statement

大半のエラーでは、connection_or_statement
は関数コール時に渡されたリソースハンドルとなります。
oci_connect() や
oci_new_connect()、
oci_pconnect() の接続エラーの場合は null を渡します。

戻り値

もしエラーが見つからない場合、oci_error() は false を返します。それ以外の場合は、 oci_error() はエラーの情報を連想配列で返します。

oci_error() の配列の形式
配列のキー | 型 | 説明
code | int | Oracle のエラーコード。
message | string | Oracle のエラーメッセージ。
offset | int | SQL 文の中でのエラーが発生した場所のバイト位置。SQL 文がない場合は 0 となります。
sqltext | string | SQL 文のテキスト。SQL 文がない場合は空文字列となります。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | connection_or_statement は、nullable になりました。

例

例1 接続エラー後の Oracle エラーメッセージの表示

<?php
$conn = oci_connect("hr", "welcome", "localhost/XE");
if (!$conn) {
$e = oci_error(); // oci_connect のエラーの場合、ハンドルを渡しません
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
?>

例2 パースエラー時の Oracle エラーメッセージの表示

<?php
$stid = oci_parse($conn, "select ' from dual"); // クォートが間違っていることに注意
if (!$stid) {
$e = oci_error($conn); // oci_parse エラーの場合は接続ハンドルを渡します
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}
?>

例3 実行エラー時の、 Oracle エラーメッセージと問題となった文の表示

<?php
$stid = oci_parse($conn, "select does_not_exist from dual");
$r = oci_execute($stid);
if (!$r) {
$e = oci_error($stid); // oci_execute のエラーの場合、ステートメントハンドルを渡します
print htmlentities($e['message']);
print "\n<pre>\n";
print htmlentities($e['sqltext']);
printf("\n%".($e['offset']+1)."s", "^");
print "\n</pre>\n";
}
?>


文を実行する

  • ≪ oci_error
  • oci_fetch ≫
  • PHP Manual
  • OCI8 関数
  • 文を実行する

oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — 文を実行する

説明

oci_execute(resource $statement, int $mode = OCI_COMMIT_ON_SUCCESS): bool

oci_parse() が返した statement を実行します。

実行後、INSERT 文などの場合はデフォルトでデータをデータベースにコミットします。 SELECT 文などの場合は問い合わせを実行します。 問い合わせの結果をその後 PHP で取得するには oci_fetch_array() などの関数を使います。

一度パースした文は何度でも実行することができ、 これを使えば毎回パースするコストを節約することができます。 この方法は、oci_bind_by_name() でデータをバインドした INSERT 文で一般的に使われています。

パラメータ

statement

有効な OCI ステートメント ID。

mode

オプションの二番目のパラメータは、次の定数のいずれかとなります。

実行モード
定数 | 説明
OCI_COMMIT_ON_SUCCESS | ステートメントの実行に成功すると、 この接続においてまだ確定していない変更をすべてコミットします。 これがデフォルトです。
OCI_DESCRIBE_ONLY | oci_field_name() 関数などでクエリのメタデータを使えるようにしますが、 結果セットは作りません。続けて oci_fetch_array() などをコールすると失敗します。
OCI_NO_AUTO_COMMIT | 変更を自動的にはコミットしません

OCI_NO_AUTO_COMMIT モードを使うとトランザクションを開始あるいは続行します。 接続を閉じたりスクリプトが終了したりしたときに、 トランザクションは自動的にロールバックされます。 トランザクションをコミットするには oci_commit() を、破棄するには oci_rollback() をコールします。

データを追加したり更新したりする際には、 リレーショナルデータの一貫性やパフォーマンスなどを考慮して トランザクションを使うことを推奨します。

OCI_NO_AUTO_COMMIT モードを使った文を実行した後に oci_commit() あるいは oci_rollback() をコールしなかった場合、 たとえデータが変更されていなくても スクリプトの終了時に OCI8 がロールバックを実行します。 不要なロールバックを避けるために、多くのスクリプトはクエリや PL/SQL で OCI_NO_AUTO_COMMIT モードを使いません。 同じスクリプトの中で異なるモードで oci_execute() を実行する場合は、 アプリケーション内で適切なトランザクションの一貫性を確保するよう注意しましょう。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_execute() での問い合わせの例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

?>

例2 モードを指定せずに oci_execute() を実行する例

<?php

// 実行する前にテーブルを作成します。
// CREATE TABLE MYTABLE (col1 NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

oci_execute($stid); // 結果はコミットされ、他のユーザーからもすぐに見えるようになります

?>

例3 oci_execute() で OCI_NO_AUTO_COMMIT を使う例

<?php

// 実行する前にテーブルを作成します。
// CREATE TABLE MYTABLE (col1 NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
oci_bind_by_name($stid, ':bv', $i, 10);
for ($i = 1; $i <= 5; ++$i) {
oci_execute($stid, OCI_NO_AUTO_COMMIT);
}
oci_commit($conn); // 新しい値 1, 2, 3, 4, 5 をすべてコミットします

?>

例4 oci_execute() でさまざまなコミットモードを使う例

<?php

// 実行する前にテーブルを作成します。
// CREATE TABLE MYTABLE (col1 NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
oci_execute($stid, OCI_NO_AUTO_COMMIT); // データはコミットされません

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
oci_execute($stid); // 123 と 456 が両方コミットされます

?>

例5 oci_execute() で OCI_DESCRIBE_ONLY を使う例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT * FROM locations');
oci_execute($s, OCI_DESCRIBE_ONLY);
for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
echo oci_field_name($stid, $i) . "<br>\n";
}

?>

注意

注意:

トランザクションは接続を閉じたとき、 もしくはスクリプトの終了時のいずれの場合でも すぐに自動的にロールバックされます。 トランザクションをコミットするには oci_commit() をコールする必要があります。

OCI_COMMIT_ON_SUCCESS モードを指定するか、 あるいはデフォルトの状態で oci_execute() をコールすると、 それ以前の未コミットのトランザクションをコミットします。

CREATE や DROP といった Oracle の DDL は、未コミットのトランザクションを自動的にコミットします。

注意:

oci_execute() 関数は 通常はステートメントをデータベースに送信するので、 ステートメントの構文エラーなどを特定することもできます。 軽量なローカル版の oci_parse() ではこれはできません。

参考

  • oci_parse() - 実行のために Oracle の文をパースする


クエリの次の行を内部バッファに取得する

  • ≪ oci_execute
  • oci_fetch_all ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を内部バッファに取得する

oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — クエリの次の行を内部バッファに取得する

説明

oci_fetch(resource $statement): bool

クエリの次の行を内部バッファに取得します。このバッファへは oci_result() でアクセスできます。あるいは、 oci_define_by_name() で事前に定義した変数を使ってアクセスすることもできます。

データの取得に関する全般的な情報は oci_fetch_array() を参照ください。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

戻り値

成功した場合に true、 statement にもう行がない場合に false を返します。

例

例1 oci_fetch() での定義済みの変数の使用

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);

// 実行前に定義しておく必要があります
oci_define_by_name($stid, 'LOCATION_ID', $locid);
oci_define_by_name($stid, 'CITY', $city);

oci_execute($stid);

// フェッチするたびに、次の行のデータが定義済みの変数に格納されます
while (oci_fetch($stid)) {
echo "Location id $locid is $city<br>\n";
}

// 表示:
// Location id 1000 is Roma
// Location id 1100 is Venice

oci_free_statement($stid);
oci_close($conn);

?>

例2 oci_fetch() と oci_result() の使用例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);
oci_execute($stid);

while (oci_fetch($stid)) {
echo oci_result($stid, 'LOCATION_ID') . " is ";
echo oci_result($stid, 'CITY') . "<br>\n";
}

// 表示:
// 1000 is Roma
// 1100 is Venice

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

Oracle Database の暗黙の結果セットからの行は返しません。 代わりに oci_fetch_array() を使いましょう。

参考

  • oci_define_by_name() - PHP の変数を、クエリで取得するカラムに関連づける
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する
  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す
  • oci_result() - フェッチした行からフィールドの値を取得する


クエリからの複数の行を二次元配列に取得する

  • ≪ oci_fetch
  • oci_fetch_array ≫
  • PHP Manual
  • OCI8 関数
  • クエリからの複数の行を二次元配列に取得する

oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — クエリからの複数の行を二次元配列に取得する

説明

oci_fetch_all(
resource $statement,
array &$output,
int $offset = 0,
int $limit = -1,
int $flags = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

クエリからの複数の行を二次元配列に取得します。 デフォルトでは、すべての行を返します。

この関数は、クエリを oci_execute() で実行した後でのみコールすることができます。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

output

返された行を格納する変数。

LOB 列は文字列として返されます。 Oracle は変換をサポートしています。

データや型の取得についての詳細な情報は oci_fetch_array() を参照ください。

offset

結果を取得する際に無視する行数 (デフォルトの値は 0 で、最初の行から開始されます)。

limit

読み込む行数。デフォルトは -1 で、これは offset + 1 番目の行以降のすべての行を意味します。

flags

パラメータ flags は、 配列の構造をあらわし、また連想配列を使うかどうかもあらわします。

oci_fetch_all() の配列構造モード
定数 | 説明
OCI_FETCHSTATEMENT_BY_ROW | 配列の配列で、内側の配列はクエリの行単位となります。
OCI_FETCHSTATEMENT_BY_COLUMN | 配列の配列で、内側の配列はクエリの列単位となります。 これがデフォルトです。

配列のインデックスには、カラム名あるいは数値を使うことができます。 結果は、どれか一つのモードでだけ返されます。

oci_fetch_all() の配列インデックスモード
定数 | 説明
OCI_NUM | 各列の配列に数値添字を使います。
OCI_ASSOC | 各カラムを連想配列にします。 これがデフォルトです。

加算演算子 "+" を使って、 配列の構造とインデックス形式の組み合わせを選択します。

Oracle のデフォルトである大文字小文字を区別しないカラム名の場合は、 配列のキーは大文字となります。大文字小文字を区別するカラム名の場合は、 配列のキーの大文字小文字は実際のカラム名と同じになります。 var_dump() で output を確認し、大文字小文字を適切に指定するようにしましょう。

同じ名前のカラムが複数あるクエリでは、カラムの別名を使わなければなりません。 そうしないと、連想配列にあらわれるのはその中の一つのカラムだけとなってしまいます。

戻り値

output の行数を返します。 これは 0 以上の値となります。

例

例1 oci_fetch_all() の例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);

$nrows = oci_fetch_all($stid, $res);

echo "$nrows rows fetched<br>\n";
var_dump($res);

// var_dump 出力は
// 2 rows fetched
// array(2) {
// ["POSTAL_CODE"]=>
// array(2) {
// [0]=>
// string(6) "00989x"
// [1]=>
// string(6) "10934x"
// }
// ["CITY"]=>
// array(2) {
// [0]=>
// string(4) "Roma"
// [1]=>
// string(6) "Venice"
// }
// }

// 結果を見やすく表示します
echo "<table border='1'>\n";
foreach ($res as $col) {
echo "<tr>\n";
foreach ($col as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($stid);
oci_close($conn);

?>

例2 oci_fetch_all() で OCI_FETCHSTATEMENT_BY_ROW を使う例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);

$nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

echo "$nrows rows fetched<br>\n";
var_dump($res);

// 出力は
// 2 rows fetched
// array(2) {
// [0]=>
// array(2) {
// ["POSTAL_CODE"]=>
// string(6) "00989x"
// ["CITY"]=>
// string(4) "Roma"
// }
// [1]=>
// array(2) {
// ["POSTAL_CODE"]=>
// string(6) "10934x"
// ["CITY"]=>
// string(6) "Venice"
// }
// }

oci_free_statement($stid);
oci_close($conn);

?>

例3 oci_fetch_all() で OCI_NUM を使う例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);

$nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

echo "$nrows rows fetched<br>\n";
var_dump($res);

// 出力は
// 2 rows fetched
// array(2) {
// [0]=>
// array(2) {
// [0]=>
// string(6) "00989x"
// [1]=>
// string(4) "Roma"
// }
// [1]=>
// array(2) {
// [0]=>
// string(6) "10934x"
// [1]=>
// string(6) "Venice"
// }
// }

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

offset を使うのは、非常に非効率的です。 読み飛ばす行もすべて PHP がデータベースから受け取る結果セットに含まれ、 そのあとで読み飛ばす部分が捨てられます。 それよりは、SQL を使って取得開始位置と取得範囲をはじめから指定した方がより効率的です。 oci_fetch_array() の例を参照ください。

注意:

大量の行を返すクエリでは、oci_fetch_array() のような単一行の取得関数を使ったほうがメモリを浪費せずに済みます。

注意:

大量の行を返すクエリの場合、 oci8.default_prefetch を増やすか oci_set_prefetch() を使えばパフォーマンスが劇的に向上します。

注意:

Oracle Database 12c の暗黙の結果セットからの行は返しません。 代わりに oci_fetch_array() を使いましょう。

参考

  • oci_fetch() - クエリの次の行を内部バッファに取得する
  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す
  • oci_set_prefetch() - クエリがプリフェッチする行数を設定する


クエリの次の行を連想配列あるいは数値添字配列で返す

  • ≪ oci_fetch_all
  • oci_fetch_assoc ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を連想配列あるいは数値添字配列で返す

oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す

説明

oci_fetch_array(resource $statement, int $mode = OCI_BOTH | OCI_RETURN_NULLS): array|false

クエリから、結果セットの次の行を含む配列を返します。 配列の各エントリが行の各カラムをあらわします。 この関数の典型的な使い方は、ループの中で false を返すまでコールすることです。 false は、もう行がないことを意味します。

statement が Oracle Database の暗黙の結果セットを返す PL/SQL ブロックである場合、 すべてのセットからの行を続けて取得します。 statement が oci_get_implicit_resultset() の戻す値である場合、 ひとつの子クエリーからの行のサブセットだけを返します。

OCI8 拡張モジュールによるデータ型マッピングの 詳細については、ドライバが サポートするデータ型 を参照ください。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

oci_get_implicit_resultset() が戻すステートメント ID も指定できます。

mode

オプションの第2引数は、次の定数の組み合わせが可能です。

oci_fetch_array() のモード
定数 | 説明
OCI_BOTH | 連想配列と配列の両方を返します。 これは OCI_ASSOC + OCI_NUM と同等で、 デフォルトの動作です。
OCI_ASSOC | 連想配列を返します。
OCI_NUM | 数値添字配列を返します。
OCI_RETURN_NULLS | null フィールドの要素も作成します。この要素の値は PHP の null となります。
OCI_RETURN_LOBS | LOB ディスクリプタではなく LOB の中身を返します。

デフォルトの mode は OCI_BOTH です。

加算演算子 "+" を使うと、複数のモードを同時に指定できます。

戻り値

連想配列や数値添字配列を返します。 statement にもう行がない場合は false を返します。

デフォルトでは、LOB カラムは LOB ディスクリプタを返します。

DATE カラムは、現行のデータフォーマットにフォーマットされた 文字列として返されます。既定のフォーマットは NLS_LANG のような Oracle 環境変数で変更したり、またはあらかじめ ALTER SESSION SET NLS_DATE_FORMAT コマンドを実行して変更します。

Oracle のデフォルトでは、大文字小文字を区別しないカラム名はすべて大文字となり、 結果の連想配列のインデックスも大文字になります。 大文字小文字を区別するカラム名は、配列のインデックスもそれと同じになります。 結果の配列を var_dump() すれば、 各クエリの大文字小文字を確かめることができます。

テーブル名は配列のインデックスには含まれません。 もし同じ名前の別カラムを複数取得するクエリを実行する場合は、 OCI_NUM を使うか、あるいはカラムのエイリアスを指定して名前の一意性を保ちましょう。 例 7 を参照ください。そうしなければ、PHP からはひとつのカラムだけしか見えなくなります。

例

例1 oci_fetch_array() での OCI_BOTH の使用例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_BOTH)) != false) {
// 連想配列の指標として大文字のカラム名を使用します
echo $row[0] . " and " . $row['DEPARTMENT_ID'] . " are the same<br>\n";
echo $row[1] . " and " . $row['DEPARTMENT_NAME'] . " are the same<br>\n";
}

oci_free_statement($stid);
oci_close($conn);

?>

例2 oci_fetch_array() での OCI_NUM の使用例

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_NUM)) != false) {
echo $row[0] . "<br>\n";
echo $row[1]->read(11) . "<br>\n"; // DESCRIPTION から最初の 11 バイトを出力します
}

// 出力です。
// 1
// A very long

oci_free_statement($stid);
oci_close($conn);

?>

例3 oci_fetch_array() での OCI_ASSOC の使用例

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
echo $row['ID'] . "<br>\n";
echo $row['DESCRIPTION']->read(11) . "<br>\n"; // DESCRIPTION から最初の 11 バイトを出力します
}

// 出力です。
// 1
// A very long

oci_free_statement($stid);
oci_close($conn);

?>

例4 oci_fetch_array() での OCI_RETURN_NULLS の使用例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT 1, null FROM dual');
oci_execute($stid);
while (($row = oci_fetch_array ($stid, OCI_ASSOC)) != false) { // NULL を無視
var_dump($row);
}

/*
上記のコードの出力です。
array(1) {
[1]=>
string(1) "1"
}
*/

$stid = oci_parse($conn, 'SELECT 1, null FROM dual');
oci_execute($stid);
while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { // NULL をフェッチ
var_dump($row);
}

/*
上記のコードの出力です。
array(2) {
[1]=>
string(1) "1"
["NULL"]=>
NULL
}
*/

?>

例5 oci_fetch_array() での OCI_RETURN_LOBS の使用例

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) != false) {
echo $row['ID'] . "<br>\n";
echo $row['DESCRIPTION'] . "<br>\n"; // DESCRIPTION の全てが含まれます
// ループ内で、大きなサイズの変数を解放してから次のフェッチに進めます。
// これで、PHP のピークメモリ利用量を抑えます。
unset($row);
}

// 出力です。
// 1
// A very long string

oci_free_statement($stid);
oci_close($conn);

?>

例6 oci_fetch_array() での文字の大小を区別するカラムの使用例

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'select * from mytab');
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

// 'Name' は文字の大小を区別するカラムとして作成されたので、配列の指標として
// 同一のケースを使用します。しかしながら、文字の大小を区別しないカラムの
// 指標としては、大文字の 'CITY' を使わなければいけません。
print $row['Name'] . "<br>\n"; // Chris を出力
print $row['CITY'] . "<br>\n"; // Melbourne を出力

oci_free_statement($stid);
oci_close($conn);

?>

例7 oci_fetch_array() での同じ名前のカラムの使用例

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
INSERT INTO mycity (id, name) values (1, 'Melbourne');
CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
INSERT INTO mycountry (id, name) values (1, 'Australia');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT mycity.name, mycountry.name
FROM mycity, mycountry
WHERE mycity.id = mycountry.id';
$stid = oci_parse($conn, $sql);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
var_dump($row);

// 出力には "NAME" 項目一つだけが含まれます。
// array(1) {
// ["NAME"]=>
// string(9) "Australia"
// }

// 度重なるカラム名を照会するには、 "AS ctnm" のような SQL カラムのエイリアスを使います。
$sql = 'SELECT mycity.name AS ctnm, mycountry.name
FROM mycity, mycountry
WHERE mycity.id = mycountry.id';
$stid = oci_parse($conn, $sql);
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
var_dump($row);

// これで出力には選択したカラムが両方含まれます。
// array(2) {
// ["CTNM"]=>
// string(9) "Melbourne"
// ["NAME"]=>
// string(9) "Australia"
// }

oci_free_statement($stid);
oci_close($conn);

?>

例8 oci_fetch_array() での DATE カラムの使用例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// この接続に対して日付フォーマットを設定します。
// パフォーマンス上の理由で、トリガー、またはその代わりに環境変数で
// フォーマットを変更することを検討します
$stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
oci_execute($stid);

$stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
oci_execute($stid);
$row = oci_fetch_array($stid, OCI_ASSOC);
echo $row['HIRE_DATE'] . "<br>\n"; // 1997-06-14 を出力

oci_free_statement($stid);
oci_close($conn);

?>

例9 oci_fetch_array() での REF CURSOR の使用例

<?php
/*
下記のようにして PL/SQL ストアド・プロシジャーを作成します。

CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
BEGIN
OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
END;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

// 返された REF CURSOR を実行して、ステートメント識別子のようにそこからフェッチします
oci_execute($refcur);
echo "<table border='1'>\n";
while (($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($refcur);
oci_free_statement($stid);
oci_close($conn);

?>

例10 oci_fetch_array() での LIMIT 風のクエリによるページング

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// データベースのバージョンを調べます
preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
$oracleversion = $matches[1];

// これがページングさせたいクエリーです
$sql = 'SELECT city, postal_code FROM locations ORDER BY city';

if ($oracleversion >= 12) {
// Oracle 12c の OFFSET / FETCH NEXT 構文を使います
$sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
} else {
// 古いバージョンの Oracle では、ネストしたクエリーを作り、$sql から
// 行のサブセットを選択する必要があります。あるいは、開発時に SQL 文が
// わかっているのなら、この方法ではなく row_number() 関数を使うことを
// 検討しましょう。運用環境では、文字列の連結にともなう SQL インジェクション
// の問題に気をつけましょう。
$sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
FROM ($sql) a
WHERE ROWNUM <= :offset + :numrows)
WHERE my_rnum > :offset";
}

$offset = 0; // この行数だけ飛ばす
$numrows = 5; // 5 行を返す
$stid = oci_parse($conn, $sql);
oci_bind_by_name($stid, ':numrows', $numrows);
oci_bind_by_name($stid, ':offset', $offset);
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
}

// 出力は
// Beijing 190518
// Bern 3095
// Bombay 490231
// Geneva 1730
// Hiroshima 6823

oci_free_statement($stid);
oci_close($conn);

?>

例11 oci_fetch_array() で Oracle Database の暗黙の結果セットを使う例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// OCI8 2.0 (またはそれ以降) と Oracle Database 12c が必要です。
// oci_get_implicit_resultset() も参照ください。
$sql = 'DECLARE
c1 SYS_REFCURSOR;
BEGIN
OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
END;';

$stid = oci_parse($conn, $sql);
oci_execute($stid);

// 注意: oci_fetch_all と oci_fetch() は、この場合は使えません
echo "<table>\n";
while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

// 出力です。
// Beijing 190518
// Bern 3095
// Bombay 490231
// CN
// CH
// IN

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

大文字小文字を区別せずにつくった Oracle のカラムでは、 連想配列のインデックスはすべて大文字となることに注意しましょう。

注意:

大量の行を返すクエリの場合、 oci8.default_prefetch を増やすか oci_set_prefetch() を使えばパフォーマンスが劇的に向上します。

注意:

oci_fetch_array() は ほんの少しだけ oci_fetch_assoc() や oci_fetch_row() より低速ですが、 ずっと柔軟性があります。

参考

  • oci_fetch() - クエリの次の行を内部バッファに取得する
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す
  • oci_set_prefetch() - クエリがプリフェッチする行数を設定する


クエリの次の行を連想配列で返す

  • ≪ oci_fetch_array
  • oci_fetch_object ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を連想配列で返す

oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — クエリの次の行を連想配列で返す

説明

oci_fetch_assoc(resource $statement): array|false

クエリの次の結果セット行を含む連想配列を返します。 配列の各エントリが、カラムに対応します。 この関数の典型的な使い方は、ループの中でコールすることです。 false が返された場合は、もう行がないことをあらわします。

oci_fetch_assoc() をコールするのは、 oci_fetch_array() で OCI_ASSOC + OCI_RETURN_NULLS を指定してコールするのと同じです。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

戻り値

連想配列を返します。 statement にもう行がない場合は false を返します。

例

例1 oci_fetch_assoc() の例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
oci_execute($stid);

while (($row = oci_fetch_assoc($stid)) != false) {
echo $row['DEPARTMENT_ID'] . " " . $row['DEPARTMENT_NAME'] . "<br>\n";
}

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

行の取得例は oci_fetch_array() も参照ください。

参考

  • oci_fetch() - クエリの次の行を内部バッファに取得する
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する
  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す


クエリの次の行をオブジェクトとして返す

  • ≪ oci_fetch_assoc
  • oci_fetch_row ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行をオブジェクトとして返す

oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — クエリの次の行をオブジェクトとして返す

説明

oci_fetch_object(resource $statement, int $mode = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

クエリから、結果セットの次の行を含むオブジェクトを返します。 オブジェクトの各属性が行の各カラムをあらわします。 この関数の典型的な使い方は、ループの中で false を返すまでコールすることです。 false は、もう行がないことを意味します。

OCI8 拡張モジュールによるデータ型マッピングの 詳細については、ドライバが サポートするデータ型 を参照ください。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

戻り値

オブジェクトを返します。 オブジェクトの属性は文中のフィールドと一致しています。 statement にもう行がない場合は false を返します。

LOB カラムは LOB ディスクリプタを返します。

DATE カラムは、現行のデータフォーマットにフォーマットされた 文字列として返されます。既定のフォーマットは NLS_LANG のような Oracle 環境変数で変更したり、またはあらかじめ ALTER SESSION SET NLS_DATE_FORMAT コマンドを実行して変更します。

Oracle のデフォルトでは、文字の大小を区別しないカラム名はすべて大文字となります。 文字の大小を区別するカラム名は、属性の名前もそれと同じになります。 結果のオブジェクト配列を var_dump() すれば、 属性にアクセスするための大文字小文字の区別を確かめられます。

NULL データ・フィールドの全てに対して、属性の値は null になります。

例

例1 oci_fetch_object() の例

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
INSERT INTO mytab (id, description) values (1, 'Fish and Chips');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);

while (($row = oci_fetch_object($stid)) != false) {
// 標準的な Oracle カラム それぞれに対して大文字の属性名を使います
echo $row->ID . "<br>\n";
echo $row->DESCRIPTION . "<br>\n";
}

// 出力です。
// 1
// Fish and Chips

oci_free_statement($stid);
oci_close($conn);

?>

例2 文字の大小を区別するカラム名を持つ oci_fetch_object()

<?php

/*
実行する前に、文字の大小を区別するカラム名を持つテーブルを作成します。
CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
oci_execute($stid);

while (($row = oci_fetch_object($stid)) != false) {
// 標準的な Oracle カラム それぞれに対して大文字の属性名を使います
echo $row->ID . "<br>\n";
// 文字の大小を区別するカラム名と同じケースを使います
echo $row->MyDescription . "<br>\n";
}

// 出力です。
// 1
// Iced Coffee

oci_free_statement($stid);
oci_close($conn);

?>

例3 LOB を持つ oci_fetch_object()

<?php

/*
実行する前にテーブルを作成します。
CREATE TABLE mytab (id NUMBER, description CLOB);
INSERT INTO mytab (id, description) values (1, 'A very long string');
COMMIT;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
oci_execute($stid);

while (($row = oci_fetch_object($stid)) != false) {
echo $row->ID . "<br>\n";
// 下記では、 DESCRIPTION から最初の 11 バイトを出力します
echo $row->DESCRIPTION->read(11) . "<br>\n";
}

// 出力です。
// 1
// A very long

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_fetch() - クエリの次の行を内部バッファに取得する
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_row() - クエリの次の行を配列で返す


クエリの次の行を配列で返す

  • ≪ oci_fetch_object
  • oci_field_is_null ≫
  • PHP Manual
  • OCI8 関数
  • クエリの次の行を配列で返す

oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — クエリの次の行を配列で返す

説明

oci_fetch_row(resource $statement): array|false

クエリから、結果セットの次の行を含む数値添字配列を返します。 配列の各エントリが行の各カラムに対応します。 この関数の典型的な使用法は、ループの中で false を返すまで繰り返すことです。 false は、もう行がないことをあらわします。

oci_fetch_row() をコールすることは、 oci_fetch_array() で OCI_NUM + OCI_RETURN_NULLS を指定してコールすることと同じです。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

戻り値

数値添字配列を返します。 statement にもう行がない場合は false を返します。

例

例1 oci_fetch_row() の例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
oci_execute($stid);

while (($row = oci_fetch_row($stid)) != false) {
echo $row[0] . " " . $row[1] . "<br>\n";
}

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

行の取得例は oci_fetch_array() も参照ください。

参考

  • oci_fetch() - クエリの次の行を内部バッファに取得する
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する
  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す


フェッチしたフィールドが null であるかどうかを確認する

  • ≪ oci_fetch_row
  • oci_field_name ≫
  • PHP Manual
  • OCI8 関数
  • フェッチしたフィールドが null であるかどうかを確認する

oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — フェッチしたフィールドが null であるかどうかを確認する

説明

oci_field_is_null(resource $statement, string|int $column): bool

statement の現在の行の、 指定したフィールド column が null であるかどうかを調べます。

パラメータ

statement

有効な OCI ステートメント ID。

column

(1 から始まる) フィールド番号、またはフィールド名。

戻り値

column が null の場合に true、 それ以外の場合に false を返します。

例

例1 oci_field_name() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (c1 NUMBER);
// INSERT INTO mytab VALUES (1);
// INSERT INTO mytab VALUES (NULL);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) != false) {
$ncols = oci_num_fields($stid);
for ($col = 1; $col <= $ncols; $col++) {
var_dump(oci_field_is_null($stid, $col));
}
}

// 出力は
// bool(false)
// bool(true)

oci_free_statement($stid);
oci_close($conn);

?>


文からのフィールド名を返す

  • ≪ oci_field_is_null
  • oci_field_precision ≫
  • PHP Manual
  • OCI8 関数
  • 文からのフィールド名を返す

oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — 文からのフィールド名を返す

説明

oci_field_name(resource $statement, string|int $column): string|false

column の名前を返します。

パラメータ

statement

有効な OCI ステートメント ID。

column

フィールド番号 (1 から始まる) あるいは名前のいずれか。

戻り値

名前を表す文字列を返します。 失敗した場合に false を返します

例

例1 oci_field_name() の例

<?php

// Create the table with:
// CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
// clob_col CLOB, date_col DATE);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

echo "<table border=\"1\">";
echo "<tr>";
echo "<th>名前</th>";
echo "<th>型</th>";
echo "</tr>\n";

$ncols = oci_num_fields($stid);

for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stid, $i);
$column_type = oci_field_type($stid, $i);

echo "<tr>";
echo "<td>$column_name</td>";
echo "<td>$column_type</td>";
echo "</tr>\n";
}

echo "</table>\n";

// 出力は
// 名前 型
// NUMBER_COL NUMBER
// VARCHAR2_COL VARCHAR2
// CLOB_COL CLOB
// DATE_COL DATE

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_num_fields() - ある文における結果のカラム数を返す
  • oci_field_type() - フィールドのデータ型の名前を返す
  • oci_field_size() - フィールドサイズを返す


フィールドの精度を問い合わせる

  • ≪ oci_field_name
  • oci_field_scale ≫
  • PHP Manual
  • OCI8 関数
  • フィールドの精度を問い合わせる

oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — フィールドの精度を問い合わせる

説明

oci_field_precision(resource $statement, string|int $column): int|false

column の精度を返します。

FLOAT 型カラムの精度は 0 でなく桁数は -127 となります。 もし精度が 0 の場合、カラムは NUMBER 型、そうでなければ NUMBER(精度, 桁数) となります。

パラメータ

statement

有効な OCI ステートメント ID。

column

フィールド番号 (1 から始まる) あるいは名前のいずれか。

戻り値

精度を表す整数値を返します。 失敗した場合に false を返します

例

例1 oci_field_precision() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

$ncols = oci_num_fields($stid);
for ($i = 1; $i <= $ncols; $i++) {
echo oci_field_name($stid, $i) . " "
. oci_field_precision($stid, $i) . " "
. oci_field_scale($stid, $i) . "<br>\n";
}

// 出力は
// C1 0 -127
// C2 126 -127
// C3 4 0
// C4 5 3

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_field_scale() - フィールドの桁数を問い合わせる
  • oci_field_type() - フィールドのデータ型の名前を返す


フィールドの桁数を問い合わせる

  • ≪ oci_field_precision
  • oci_field_size ≫
  • PHP Manual
  • OCI8 関数
  • フィールドの桁数を問い合わせる

oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — フィールドの桁数を問い合わせる

説明

oci_field_scale(resource $statement, string|int $column): int|false

column に対応するカラムの桁数を返します。

FLOAT 型カラムの精度は 0 でなく桁数は -127 となります。 もし精度が 0 の場合、カラムは NUMBER 型、そうでなければ NUMBER(精度, 桁数) となります。

パラメータ

statement

有効な OCI ステートメント ID。

column

フィールド番号 (1 から始まる) あるいは名前のいずれか。

戻り値

桁数を表す整数値を返します。 失敗した場合に false を返します

例

例1 oci_field_scale() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // 行をフェッチしない場合は OCI_DESCRIBE_ONLY を使います

$ncols = oci_num_fields($stid);
for ($i = 1; $i <= $ncols; $i++) {
echo oci_field_name($stid, $i) . " "
. oci_field_precision($stid, $i) . " "
. oci_field_scale($stid, $i) . "<br>\n";
}

// 出力は
// C1 0 -127
// C2 126 -127
// C3 4 0
// C4 5 3

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_field_precision() - フィールドの精度を問い合わせる
  • oci_field_type() - フィールドのデータ型の名前を返す


フィールドサイズを返す

  • ≪ oci_field_scale
  • oci_field_type ≫
  • PHP Manual
  • OCI8 関数
  • フィールドサイズを返す

oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — フィールドサイズを返す

説明

oci_field_size(resource $statement, string|int $column): int|false

フィールド column のサイズを返します。

パラメータ

statement

有効な OCI ステートメント ID。

column

フィールドのインデックス (1 から始まるもの) あるいは名前。

戻り値

フィールド column のサイズを表すバイト数を返します。 失敗した場合に false を返します

例

例1 oci_field_size() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
// clob_col CLOB, date_col DATE);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // 行をフェッチしない場合は OCI_DESCRIBE_ONLY を使います

echo "<table border=\"1\">\n";
echo "<tr>";
echo "<th>Name</th>";
echo "<th>Type</th>";
echo "<th>Length</th>";
echo "</tr>\n";

$ncols = oci_num_fields($stid);

for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stid, $i);
$column_type = oci_field_type($stid, $i);
$column_size = oci_field_size($stid, $i);

echo "<tr>";
echo "<td>$column_name</td>";
echo "<td>$column_type</td>";
echo "<td>$column_size</td>";
echo "</tr>\n";
}

echo "</table>\n";

// 出力は
// Name Type Length
// NUMBER_COL NUMBER 22
// VARCHAR2_COL VARCHAR2 1
// CLOB_COL CLOB 4000
// DATE_COL DATE 7

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_num_fields() - ある文における結果のカラム数を返す
  • oci_field_name() - 文からのフィールド名を返す


フィールドのデータ型の名前を返す

  • ≪ oci_field_size
  • oci_field_type_raw ≫
  • PHP Manual
  • OCI8 関数
  • フィールドのデータ型の名前を返す

oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — フィールドのデータ型の名前を返す

説明

oci_field_type(resource $statement, string|int $column): string|int|false

フィールドのデータ型の名前を返します。

パラメータ

statement

有効な OCI ステートメント ID。

column

フィールド番号 (1 から始まる) あるいは名前のいずれか。

戻り値

フィールドのデータ型を表す文字列または数値を返します。 失敗した場合に false を返します

例

例1 oci_field_type() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
// clob_col CLOB, date_col DATE);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // 行をフェッチしない場合は OCI_DESCRIBE_ONLY を使います

echo "<table border=\"1\">";
echo "<tr>";
echo "<th>名前</th>";
echo "<th>型</th>";
echo "<th>長さ</th>";
echo "</tr>\n";

$ncols = oci_num_fields($stid);

for ($i = 1; $i <= $ncols; $i++) {
$column_name = oci_field_name($stid, $i);
$column_type = oci_field_type($stid, $i);
$column_size = oci_field_size($stid, $i);

echo "<tr>";
echo "<td>$column_name</td>";
echo "<td>$column_type</td>";
echo "<td>$column_size</td>";
echo "</tr>\n";
}

echo "</table>\n";

// 出力は
// 名前 型 長さ
// NUMBER_COL NUMBER 22
// VARCHAR2_COL VARCHAR2 1
// CLOB_COL CLOB 4000
// DATE_COL DATE 7

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_num_fields() - ある文における結果のカラム数を返す
  • oci_field_name() - 文からのフィールド名を返す
  • oci_field_size() - フィールドサイズを返す


Oracle におけるフィールドの型を問い合わせる

  • ≪ oci_field_type
  • oci_free_descriptor ≫
  • PHP Manual
  • OCI8 関数
  • Oracle におけるフィールドの型を問い合わせる

oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる

説明

oci_field_type_raw(resource $statement, string|int $column): int|false

フィールド column の、Oracle における生の "SQLT" データ型を返します。

フィールドの型の名前を取得したい場合は oci_field_type() を使いましょう。

パラメータ

statement

有効な OCI ステートメント ID。

column

フィールド番号 (1 から始まる) あるいは名前のいずれか。

戻り値

Oracle のデータ型を表す数値を返します。 失敗した場合に false を返します

例

例1 oci_field_type_raw() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1), clob_col CLOB, date_col DATE);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, 'select * from mytab');
oci_execute($stid, OCI_DESCRIBE_ONLY); // 行をフェッチしない場合は OCI_DESCRIBE_ONLY を使います
$n = oci_num_fields($stid);
for ($i = 1; $i <= $n; ++$i) {
echo oci_field_name($stid, $i) . " is raw type: " . oci_field_type_raw($stid, $i) . "<br>\n";
}

// 出力は
// NUMBER_COL is raw type: 2
// VARCHAR2_COL is raw type: 1
// CLOB_COL is raw type: 112
// DATE_COL is raw type: 12

oci_free_statement($stid);
oci_close($conn);

?>


ディスクリプタを解放する

  • ≪ oci_field_type_raw
  • oci_free_statement ≫
  • PHP Manual
  • OCI8 関数
  • ディスクリプタを解放する

oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — ディスクリプタを解放する

説明

oci_free_descriptor(OCILob $lob): bool

oci_new_descriptor() で確保したディスクリプタを解放します。

パラメータ

descriptor

oci_new_descriptor() で確保したディスクリプタ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

この関数は、一般に OCILOB::free メソッドとして使います。

参考

  • OCILOB::free


文やカーソルに関連付けられた全てのリソースを解放する

  • ≪ oci_free_descriptor
  • oci_get_implicit_resultset ≫
  • PHP Manual
  • OCI8 関数
  • 文やカーソルに関連付けられた全てのリソースを解放する

oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — 文やカーソルに関連付けられた全てのリソースを解放する

説明

oci_free_statement(resource $statement): bool

oci_parse() の結果や Oracle から取得した、 Oracle のカーソルおよび文に関連付けられた全てのリソースを解放します。

パラメータ

statement

有効な OCI ステートメント ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。


Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

  • ≪ oci_free_statement
  • oci_lob_copy ≫
  • PHP Manual
  • OCI8 関数
  • Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

説明

oci_get_implicit_resultset(resource $statement): resource|false

ストアドまたは匿名の Oracle PL/SQL ブロックを実行後、 クエリの結果の連続したセットを取得するために使用されます。 そのブロックは、Oracle Database 12 (またはそれ以降) の DBMS_SQL.RETURN_RESULT PL/SQL 関数によりクエリの結果を返します。 これにより、PL/SQL ブロックはクエリ結果を簡単に返すことができます。

子ステートメントは、任意の OCI8 取得関数とともに使用できます。
その関数は、oci_fetch()、oci_fetch_all()、
oci_fetch_array()、oci_fetch_object()、
oci_fetch_assoc() または oci_fetch_row() です。

子ステートメントは、それらの親ステートメントのプリフェッチ値を継承するか、 または oci_set_prefetch() により明示的に設定することができます。

パラメータ

statement

oci_parse() により作成され、 oci_execute() により実行される 有効な OCI8 ステートメント ID 。 そのステートメント ID は、 暗黙の結果セットを返す SQL 文に関連づけられているかもしれませんし、 いないかもしれません。

戻り値

statement 上で使用可能な 次の子ステートメントに対する文ハンドラを返します。 子ステートメントが存在しないか、 または oci_get_implicit_resultset() への前の呼び出しにより、 すべての子ステートメントが返されていた場合、 false を返します。

例

例1 ループ内で暗黙の結果セットを取得

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'DECLARE
c1 SYS_REFCURSOR;
BEGIN
OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
END;';

$stid = oci_parse($conn, $sql);
oci_execute($stid);

while (($stid_c = oci_get_implicit_resultset($stid))) {
echo "<h2>新規の暗黙の結果セット:</h2>\n";
echo "<table>\n";
while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";
}

// 出力です。
// 新規の暗黙の結果セット:
// Beijing 190518
// Bern 3095
// Bombay 490231
// 新規の暗黙の結果セット:
// CN
// CH
// IN

oci_free_statement($stid);
oci_close($conn);

?>

例2 子ステートメントのハンドラをそれぞれ取得

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'DECLARE
c1 SYS_REFCURSOR;
BEGIN
OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
END;';

$stid = oci_parse($conn, $sql);
oci_execute($stid);

$stid_1 = oci_get_implicit_resultset($stid);
$stid_2 = oci_get_implicit_resultset($stid);

$row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
var_dump($row);
$row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
var_dump($row);
$row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
var_dump($row);
$row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
var_dump($row);

// 出力です。
// array(2) {
// ["CITY"]=>
// string(7) "Beijing"
// ["POSTAL_CODE"]=>
// string(6) "190518"
// }
// array(1) {
// ["COUNTRY_ID"]=>
// string(2) "CN"
// }
// array(2) {
// ["CITY"]=>
// string(4) "Bern"
// ["POSTAL_CODE"]=>
// string(4) "3095"
// }
// array(1) {
// ["COUNTRY_ID"]=>
// string(2) "CH"
// }

oci_free_statement($stid);
oci_close($conn);

?>

例3 プリフェッチ数を明示的に設定

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'DECLARE
c1 SYS_REFCURSOR;
BEGIN
OPEN c1 FOR SELECT city, postal_code FROM locations ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
END;';

$stid = oci_parse($conn, $sql);
oci_execute($stid);

$stid_c = oci_get_implicit_resultset($stid);
oci_set_prefetch($stid_c, 200); // 子ステートメントから取得する前にプリフェッチを設定
echo "<table>\n";
while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($stid);
oci_close($conn);

?>

例4 oci_get_implicit_resultset() を使用しない暗黙の結果セットの例

すべてのクエリからすべての結果が連続して返されます。

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'DECLARE
c1 SYS_REFCURSOR;
BEGIN
OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
DBMS_SQL.RETURN_RESULT(c1);
END;';

$stid = oci_parse($conn, $sql);
oci_execute($stid);

// 注意: oci_fetch_all および oci_fetch() はこの方法では使用できません
echo "<table>\n";
while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

// 出力です。
// Beijing 190518
// Bern 3095
// Bombay 490231
// CN
// CH
// IN

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

大量の行を返すクエリの場合、 oci8.default_prefetch を増やすか oci_set_prefetch() を使えばパフォーマンスが劇的に向上します。


ラージオブジェクトをコピーする

  • ≪ oci_get_implicit_resultset
  • oci_lob_is_equal ≫
  • PHP Manual
  • OCI8 関数
  • ラージオブジェクトをコピーする

oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — ラージオブジェクトをコピーする

説明

oci_lob_copy(OCILob $to, OCILob $from, ?int $length = null): bool

ラージオブジェクトあるいはラージオブジェクトの一部を 他のラージオブジェクトにコピーします。 受け取り側の LOB の古いデータは上書きされます。

もし LOB の特定部分を LOB の特定の位置にコピーする必要がある場合、 OCILob::seek() を使用して LOB の内部ポインタを移動させることができます。

パラメータ

to

コピー先の LOB。

from

コピー元の LOB。

length

コピーされるデータの長さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | length は、nullable になりました。

注意

注意:

OCILob クラスは、PHP 8 と PECL OCI8 3.0.0 より前のバージョンでは、OCI-Lob と呼ばれていました。


2 つの LOB/FILE ロケータの等価性を比較する

  • ≪ oci_lob_copy
  • oci_new_collection ≫
  • PHP Manual
  • OCI8 関数
  • 2 つの LOB/FILE ロケータの等価性を比較する

oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — 2 つの LOB/FILE ロケータの等価性を比較する

説明

oci_lob_is_equal(OCILob $lob1, OCILob $lob2): bool

2 つの LOB/FILE ロケータを比較します。

パラメータ

lob1

LOB の ID。

lob2

LOB の ID。

戻り値

これらのオブジェクトが等しい場合 true を返し、 そうでなければ false を返します。

注意

注意:

OCILob クラスは、PHP 8 と PECL OCI8 3.0.0 より前のバージョンでは、OCI-Lob と呼ばれていました。


新しいコレクションオブジェクトを割り当てる

  • ≪ oci_lob_is_equal
  • oci_new_connect ≫
  • PHP Manual
  • OCI8 関数
  • 新しいコレクションオブジェクトを割り当てる

oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — 新しいコレクションオブジェクトを割り当てる

説明

oci_new_collection(resource $connection, string $type_name, ?string $schema = null): OCICollection|false

新しいコレクションオブジェクトを割り当てます。

パラメータ

connection

oci_connect() あるいは oci_pconnect() が返す Oracle 接続 ID。

type_name

有効な型名 (大文字)。

schema

型を作成したスキーマを指定しなければなりません。 null を渡すと、現在のユーザー名が使われます。

戻り値

新しい OCICollection オブジェクト、 あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | schema は、nullable になりました。

注意

注意:

PHP 8 と PECL OCI8 3.0.0 より前のバージョンでは、 OCICollection クラスは OCI-Collection と呼ばれていました。


一意な接続を使って Oracle サーバーへ接続する

  • ≪ oci_new_collection
  • oci_new_cursor ≫
  • PHP Manual
  • OCI8 関数
  • 一意な接続を使って Oracle サーバーへ接続する

oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — 一意な接続を使って Oracle サーバーへ接続する

説明

oci_new_connect(
string $username,
string $password,
?string $connection_string = null,
string $encoding = "",
int $session_mode = OCI_DEFAULT
): resource|false

Oracle サーバーへの新規接続を確立し、ログオンします。

oci_connect() や oci_pconnect() と異なり、oci_new_connect() は接続をキャッシュしません。また、 常に新しくオープンされた接続ハンドルを返します。 これは、もしアプリケーションが 2 セットのクエリ間でトランザクション的な独立を必要とする場合に有効です。

パラメータ

username

Oracle のユーザー名。

password

username のパスワード。

connection_string

接続先の Oracle インスタンス。 » Easy Connect 文字列、tnsnames.ora ファイルの接続文字列、あるいはローカルの Oracle インスタンス名を指定します。

省略した場合、または null の場合、PHP は環境変数 TWO_TASK (Linux) あるいは LOCAL (Windows) と ORACLE_SID を用いて接続先の Oracle インスタンス を判断します。

Easy Connect 方式を使うには、PHP を Oracle 10g 以降のクライアントライブラリとリンクさせる必要があります。Oracle 10g の Easy Connect 文字列の形式は [//]host_name[:port][/service_name] です。Oracle 11g 以降の場合は、この構文は [//]host_name[:port][/service_name][:server_type][/instance_name] となります。 Oracle 19c では、さらにオプションが追加されています。 タイムアウトや keep-alive の設定を含みます。詳細は Oracle のドキュメントを参照して下さい。 サービス名を調べるには、Oracle のユーティリティ lsnrctl status をデータベースサーバー上で実行します。

tnsnames.ora ファイルは Oracle Net のサーチパス上にあります。 サーチパスに含まれるのは /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin, /etc です。 もうひとつの方法として、 TNS_ADMIN を指定して $TNS_ADMIN/tnsnames.ora を読み込ませることもできます。 ウェブデーモンにそのファイルの読み込み権限を与えておきましょう。

encoding

Oracle クライアントライブラリが使う文字セットを指定します。 これは、データベースが用いる文字セットと一致させる必要はありません。 一致していない場合は、Oracle が最善を尽くしてデータベースの文字セットとの間の変換を行います。 文字セットによっては、この変換結果がうまく使えないこともあります。 また、変換にはそれなりの時間を要します。

省略した場合は、 Oracle クライアントライブラリは環境変数 NLS_LANG の値をもとに文字セットを判断します。

このパラメータを渡すことで、 接続に要する時間を短縮できます。

session_mode

このパラメータは PHP 5 (PECL OCI8 1.1) 以降で使え、 OCI_DEFAULT、 OCI_SYSOPER そして OCI_SYSDBA といった値を指定することができます。OCI_SYSOPER あるいは OCI_SYSDBA を指定した場合は、 この関数は外部の証明書を使った特権接続の確立を試みます。 特権接続は、デフォルトでは無効になっています。有効にするには oci8.privileged_connect を On に設定しなければなりません。

PHP 5.3 (PECL OCI8 1.3.4) 以降、 OCI_CRED_EXT モードを使えるようになりました。 これは、Oracle に外部認証あるいは OS 認証を使うよう指示します。 どちらかをデータベースで設定しておかなければなりません。 OCI_CRED_EXT フラグを使えるのは、ユーザー名が "/" でパスワードが空のときだけです。 oci8.privileged_connect は On あるいは Off のどちらでもかまいません。

OCI_CRED_EXT は、 OCI_SYSOPER あるいは OCI_SYSDBA モードと組み合わせて使います。

OCI_CRED_EXT は、セキュリティ上の理由により Windows ではサポートされていません。

戻り値

接続 ID、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | connection_string は、nullable になりました。

例

以下の例は、接続がどのように分割されるかを示すものです。

例1 oci_new_connect() の例

<?php

// create table mytab (mycol number);

function query($name, $c)
{
echo "Querying $name\n";
$s = oci_parse($c, "select * from mytab");
oci_execute($s, OCI_NO_AUTO_COMMIT);
$row = oci_fetch_array($s, OCI_ASSOC);
if (!$row) {
echo "No rows\n";
} else {
do {
foreach ($row as $item)
echo $item . " ";
echo "\n";
} while (($row = oci_fetch_array($s, OCI_ASSOC)) != false);
}
}

$c1 = oci_connect("hr", "welcome", "localhost/orcl");
$c2 = oci_new_connect("hr", "welcome", "localhost/orcl");

$s = oci_parse($c1, "insert into mytab values(1234)");
oci_execute($s, OCI_NO_AUTO_COMMIT);

query("basic connection", $c1);
query("new connection", $c2);
oci_commit($c1);
query("new connection after commit", $c2);

// 出力:
// Querying basic connection
// 1234
// Querying new connection
// No rows
// Querying new connection after commit
// 1234

?>

パラメータの使いかたについては、oci_connect() の例も参照ください。

参考

  • oci_connect() - Oracle データベースに接続する
  • oci_pconnect() - 持続的接続を使用してOracle データベースに接続する


新規カーソル (ステートメントハンドル) を割り当て、それを返す

  • ≪ oci_new_connect
  • oci_new_descriptor ≫
  • PHP Manual
  • OCI8 関数
  • 新規カーソル (ステートメントハンドル) を割り当て、それを返す

oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — 新規カーソル (ステートメントハンドル) を割り当て、それを返す

説明

oci_new_cursor(resource $connection): resource|false

指定された接続に新規カーソルを割り当てます。

パラメータ

connection

oci_connect() あるいは oci_pconnect() が返す Oracle 接続 ID。

戻り値

新しいステートメントハンドル、あるいはエラー時に false を返します。

例

例1 Oracle ストアドプロシージャにおける REF CURSOR のバインド

<?php

// 以下のプロシージャを用意します
// create or replace procedure myproc(myrc out sys_refcursor) as
// begin
// open myrc for select first_name from employees;
// end;

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$curs = oci_new_cursor($conn);
$stid = oci_parse($conn, "begin myproc(:cursbv); end;");
oci_bind_by_name($stid, ":cursbv", $curs, -1, OCI_B_CURSOR);
oci_execute($stid);

oci_execute($curs); // REF CURSOR を、ステートメント ID のように利用します
while (($row = oci_fetch_array($curs, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
echo $row['FIRST_NAME'] . "<br />\n";
}

oci_free_statement($stid);
oci_free_statement($curs);
oci_close($conn);

?>


空の新規 LOB あるいは FILE ディスクリプタを初期化する

  • ≪ oci_new_cursor
  • oci_num_fields ≫
  • PHP Manual
  • OCI8 関数
  • 空の新規 LOB あるいは FILE ディスクリプタを初期化する

oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — 空の新規 LOB あるいは FILE ディスクリプタを初期化する

説明

oci_new_descriptor(resource $connection, int $type = OCI_DTYPE_LOB): ?OCILob

ディスクリプタあるいは LOB ロケータを保持するリソースを確保します。

パラメータ

connection

oci_connect() あるいは oci_pconnect() が返す Oracle 接続 ID。

type

type として有効な値は、 OCI_DTYPE_FILE、OCI_DTYPE_LOB および OCI_DTYPE_ROWID です。

戻り値

成功した場合に新しい LOB あるいは FILE ディスクリプタ、 エラー時に null を返します。

例

例1 oci_new_descriptor() の例

<?php
/* このスクリプトは HTML フォームからコールされるよう設計されています。
* また、$user, $passwor, $table, $where, $commitsizeがフォームから
* 渡されることを前提にしています。このスクリプトは、ROWID を用いて
* 選択された行を削除し、$commitsize 行毎にコミットします。
* (ロールバックがないので、注意して使用してください。)
*/
$conn = oci_connect($user, $password);
$stmt = oci_parse($conn, "select rowid from $table $where");
$rowid = oci_new_descriptor($conn, OCI_D_ROWID);
oci_define_by_name($stmt, "ROWID", $rowid);
oci_execute($stmt);
while (oci_fetch($stmt)) {
$nrows = oci_num_rows($stmt);
$delete = oci_parse($conn, "delete from $table where ROWID = :rid");
oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
oci_execute($delete);
echo "$nrows\n";
if (($nrows % $commitsize) == 0) {
oci_commit($conn);
}
}
$nrows = oci_num_rows($stmt);
echo "$nrows deleted...\n";
oci_free_statement($stmt);
oci_close($conn);
?>
<?php
/* このスクリプトは LOB カラムにファイルをアップロードする例を示します。
* LOBカラムにアップロードを行うこの例に関するフォームは、
* <form action="upload.php3" method="post" enctype="multipart/form-data">
* <input type="file" name="lob_upload" />
* ... のようなものが使用されます。
*/
if (!isset($lob_upload) || $lob_upload == 'none'){
?>
<form action="upload.php" method="post" enctype="multipart/form-data">
Upload file: <input type="file" name="lob_upload" /><br />
<input type="submit" value="Upload" /> - <input type="reset" value="Reset" />
</form>
<?php
} else {

// $lob_upload には、アップロードされたファイルの一時的なファイル名が含まれます

// 安全にアップロードしたい場合は、マニュアルの
// ファイルアップロードに関する節を参照ください

$conn = oci_connect($user, $password);
$lob = oci_new_descriptor($conn, OCI_D_LOB);
$stmt = oci_parse($conn, "insert into $table (id, the_blob)
values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
oci_execute($stmt, OCI_DEFAULT);
if ($lob->savefile($lob_upload)){
oci_commit($conn);
echo "Blob のアップロードは成功しました\n";
}else{
echo "Blob をアップロードできませんでした\n";
}
$lob->free();
oci_free_statement($stmt);
oci_close($conn);
}
?>

例2 oci_new_descriptor() の例

<?php
/* 入力パラメータとして clob を含む PL/SQLストアドプロシージャを
* コールする。
* PL/SQL ストアドプロシージャのシグネチャは次の通り。
*
* PROCEDURE save_data
* Argument Name Type In/Out Default?
* ------------------------------ ----------------------- ------ --------
* KEY NUMBER(38) IN
* DATA CLOB IN
*
*/

$conn = oci_connect($user, $password);
$stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stmt, ':key', $key);
oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
$clob->write($data);
oci_execute($stmt, OCI_DEFAULT);
oci_commit($conn);
$clob->free();
oci_free_statement($stmt);
?>

参考

  • oci_bind_by_name() - Oracle プレースホルダに PHP 変数をバインドする


ある文における結果のカラム数を返す

  • ≪ oci_new_descriptor
  • oci_num_rows ≫
  • PHP Manual
  • OCI8 関数
  • ある文における結果のカラム数を返す

oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — ある文における結果のカラム数を返す

説明

oci_num_fields(resource $statement): int

指定した文 statement におけるカラムの数を返します。

パラメータ

statement

有効な OCI ステートメント ID。

戻り値

カラムの数を表す整数値、あるいはエラー時に false を返します。

例

例1 oci_num_fields() の例

<?php

// 以下のテーブルを用意します
// CREATE TABLE mytab (id NUMBER, quantity NUMBER);

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "SELECT * FROM mytab");
oci_execute($stid, OCI_DESCRIBE_ONLY); // 行をフェッチしない場合は OCI_DESCRIBE_ONLY を使います

$ncols = oci_num_fields($stid);
for ($i = 1; $i <= $ncols; $i++) {
echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
}

// 出力は
// ID NUMBER
// QUANTITY NUMBER

oci_free_statement($stid);
oci_close($conn);

?>


文の実行で作用された行数を取得する

  • ≪ oci_num_fields
  • oci_parse ≫
  • PHP Manual
  • OCI8 関数
  • 文の実行で作用された行数を取得する

oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — 文の実行で作用された行数を取得する

説明

oci_num_rows(resource $statement): int|false

文の実行で作用された行数を取得します。

パラメータ

statement

有効な OCI ステートメント ID。

戻り値

作用された行の数を表す整数値を返します。 失敗した場合に false を返します

例

例1 oci_num_rows() の例

<?php

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
if (!$conn) {
$m = oci_error();
trigger_error(htmlentities($m['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, "create table emp2 as select * from employees");
oci_execute($stid);
echo oci_num_rows($stid) . " rows inserted.<br />\n";
oci_free_statement($stid);

$stid = oci_parse($conn, "delete from emp2");
oci_execute($stid, OCI_DEFAULT);
echo oci_num_rows($stid) . " rows deleted.<br />\n";
oci_commit($conn);
oci_free_statement($stid);

$stid = oci_parse($conn, "drop table emp2");
oci_execute($stid);
oci_free_statement($stid);

oci_close($conn);

?>

注意

注意:

この関数は、select が返す行の数は 返しません ! SELECT 文の場合、この関数は oci_fetch*() 関数によってバッファに取得された行数を返します。


実行のために Oracle の文をパースする

  • ≪ oci_num_rows
  • oci_password_change ≫
  • PHP Manual
  • OCI8 関数
  • 実行のために Oracle の文をパースする

oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — 実行のために Oracle の文をパースする

説明

oci_parse(resource $connection, string $sql): resource|false

connection を使って sql をパースし、ステートメント ID を返します。この ID は、oci_bind_by_name(), oci_execute() や他の関数で使用されます。

ステートメント ID を解放するには、 oci_free_statement() を使うか、あるいは 変数に null を代入します。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

sql

SQL あるいは PL/SQL ステートメント。

SQL の最後にセミコロン (";") をつけては いけません。一方、PL/SQL ステートメントの最後はセミコロン (";") を つけなければなりません。

戻り値

成功した場合にステートメントハンドル、あるいはエラー時に false を返します。

例

例1 oci_parse() での SQL 文の例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

// パースします。SQL 文の最後にはセミコロンがないことに注意しましょう
$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

?>

例2 oci_parse() での PL/SQL の例

<?php

/*
この PHP プログラムを実行する前に、SQL*Plus や SQL Developer で
ストアドプロシージャを作っておきます

CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
BEGIN
p2 := p1 * 2;
END;

*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$p1 = 8;

// PL/SQL プログラムをパースするには、文字列の最後にセミコロンが必要です
$stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
oci_bind_by_name($stid, ':p1', $p1);
oci_bind_by_name($stid, ':p2', $p2, 40);

oci_execute($stid);

print "$p2\n"; // 16 と表示します

oci_free_statement($stid);
oci_close($conn);

?>

注意

注意:

この関数は sql を検証 しません。 sql が有効な SQL あるいは PL/SQL 文かどうかを検証する唯一の方法 - それは実行することです。

参考

  • oci_execute() - 文を実行する
  • oci_free_statement() - 文やカーソルに関連付けられた全てのリソースを解放する


Oracle ユーザーのパスワードを変更する

  • ≪ oci_parse
  • oci_pconnect ≫
  • PHP Manual
  • OCI8 関数
  • Oracle ユーザーのパスワードを変更する

oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Oracle ユーザーのパスワードを変更する

説明

oci_password_change(
resource $connection,
string $username,
string $old_password,
string $new_password
): bool
oci_password_change(
string $database_name,
string $username,
string $old_password,
string $new_password
): resource

ユーザー username のパスワードを変更します。

oci_password_change() が役立つのは、 PHP コマンドラインスクリプトで使う場合や PHP アプリケーションで持続的でない接続を使う場合です。

パラメータ

connection

oci_connect() あるいは oci_pconnect() が返す Oracle 接続 ID。

username

Oracle のユーザー名。

old_password

旧パスワード。

new_password

設定したい、新しいパスワード。

database_name

データベース名。

戻り値

database_name が指定された場合、 oci_password_change() は 成功時に true を返します。 失敗した場合に false を返します。 connection が指定された場合、 oci_password_change() は 成功時に接続リソースを返します。 失敗した場合に false を返します。

例

例1 oci_password_change() で、接続中のユーザーのパスワードを変更する例

<?php

$dbase = 'localhost/orcl';
$user = 'cj';
$current_pw = 'welcome';
$new_pw = 'geelong';

$c = oci_pconnect($user, $current_pw, $dbase);
oci_password_change($c, $user, $current_pw, $new_pw);
echo "New password is : " . $new_pw . "\n";

?>

例2 oci_password_change() で、接続とパスワードの変更を一度に行う例

<?php

$dbase = 'localhost/orcl';
$user = 'cj';
$current_pw = 'welcome';
$new_pw = 'geelong';

$c = oci_pconnect($user, $current_pw, $dbase);
if (!$c) {
$m = oci_error();
if ($m['code'] == 28001) { // "ORA-28001: the password has expired"
// ログインとパスワードリセットを同時に行います
$c = oci_password_change($dbase, $user, $current_pw, $new_pw);
if ($c) {
echo "New password is : " . $new_pw . "\n";
}
}
}

if (!$c) { // 28001 以外のエラーが発生したり、パスワードの変更に失敗したりした場合
$m = oci_error();
trigger_error('Could not connect to database: '. $m['message'], E_USER_ERROR);
}

// 接続 $c が使えます
// ...

?>

注意

注意:

この関数を使うにせよ Oracle から直接操作するにせよ、 パスワードを変更する際には十分注意しましょう。 持続的接続を使っている場合、PHP アプリケーションからは古いパスワードでも認証できてしまいます。 ユーザーのパスワードを変更したら、ウェブサーバーをすべて再起動させるのがお勧めの方法です。

注意:

Oracle クライアントライブラリあるいはデータベースを 11.2.0.3 より前のリリースから 11.2.0.3 以降のバージョンにアップグレードするときには、クライアントとサーバーのバージョンを同時に上げないと oci_password_change() は "ORA-1017: invalid username/password" エラーとなってしまいます。

注意:

oci_password_change() の 2 番目の書式は OCI8 バージョン 1.1 から利用可能です。


持続的接続を使用してOracle データベースに接続する

  • ≪ oci_password_change
  • oci_register_taf_callback ≫
  • PHP Manual
  • OCI8 関数
  • 持続的接続を使用してOracle データベースに接続する

oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — 持続的接続を使用してOracle データベースに接続する

説明

oci_pconnect(
string $username,
string $password,
?string $connection_string = null,
string $encoding = "",
int $session_mode = OCI_DEFAULT
): resource|false

Oracle サーバーへの持続的接続を生成し、ログオンします。

持続的接続はキャッシュされ、リクエスト間で再利用されることで、 各ページロードのオーバーヘッドを軽減します。 典型的な PHP アプリケーションでは、Apache の子プロセス (もしくは PHP FPM プロセス) ごとに Oracle サーバーに対してオープンされた単一の持続的接続を有します。 より詳細な情報については、 OCI8 接続のハンドリングおよびプーリング のセクションを参照ください。

パラメータ

username

Oracle のユーザー名。

password

username のパスワード。

connection_string

接続先の Oracle インスタンス。 » Easy Connect 文字列、tnsnames.ora ファイルの接続文字列、あるいはローカルの Oracle インスタンス名を指定します。

省略した場合、または null の場合、PHP は環境変数 TWO_TASK (Linux) あるいは LOCAL (Windows) と ORACLE_SID を用いて接続先の Oracle インスタンス を判断します。

Easy Connect 方式を使うには、PHP を Oracle 10g 以降のクライアントライブラリとリンクさせる必要があります。Oracle 10g の Easy Connect 文字列の形式は [//]host_name[:port][/service_name] です。Oracle 11g 以降の場合は、この構文は [//]host_name[:port][/service_name][:server_type][/instance_name] となります。 Oracle 19c では、さらにオプションが追加されています。 タイムアウトや keep-alive の設定を含みます。詳細は Oracle のドキュメントを参照して下さい。 サービス名を調べるには、Oracle のユーティリティ lsnrctl status をデータベースサーバー上で実行します。

tnsnames.ora ファイルは Oracle Net のサーチパス上にあります。 サーチパスに含まれるのは /your/path/to/instantclient/network/admin, $ORACLE_HOME/network/admin, /etc です。 もうひとつの方法として、 TNS_ADMIN を指定して $TNS_ADMIN/tnsnames.ora を読み込ませることもできます。 ウェブデーモンにそのファイルの読み込み権限を与えておきましょう。

encoding

Oracle クライアントライブラリが使う文字セットを指定します。 これは、データベースが用いる文字セットと一致させる必要はありません。 一致していない場合は、Oracle が最善を尽くしてデータベースの文字セットとの間の変換を行います。 文字セットによっては、この変換結果がうまく使えないこともあります。 また、変換にはそれなりの時間を要します。

省略した場合は、 Oracle クライアントライブラリは環境変数 NLS_LANG の値をもとに文字セットを判断します。

このパラメータを渡すことで、 接続に要する時間を短縮できます。

session_mode

このパラメータは PHP 5 (PECL OCI8 1.1) 以降で使え、 OCI_DEFAULT、 OCI_SYSOPER そして OCI_SYSDBA といった値を指定することができます。OCI_SYSOPER あるいは OCI_SYSDBA を指定した場合は、 この関数は外部の証明書を使った特権接続の確立を試みます。 特権接続は、デフォルトでは無効になっています。有効にするには oci8.privileged_connect を On に設定しなければなりません。

PHP 5.3 (PECL OCI8 1.3.4) 以降、 OCI_CRED_EXT モードを使えるようになりました。 これは、Oracle に外部認証あるいは OS 認証を使うよう指示します。 どちらかをデータベースで設定しておかなければなりません。 OCI_CRED_EXT フラグを使えるのは、ユーザー名が "/" でパスワードが空のときだけです。 oci8.privileged_connect は On あるいは Off のどちらでもかまいません。

OCI_CRED_EXT は、 OCI_SYSOPER あるいは OCI_SYSDBA モードと組み合わせて使います。

OCI_CRED_EXT は、セキュリティ上の理由により Windows ではサポートされていません。

戻り値

接続 ID、あるいはエラー時に false を返します。

例

例1 Easy Connect 構文を使った oci_pconnect() の例

<?php

// "localhost" 上の XE サービス (データベース) に接続します
$conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT * FROM employees');
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

?>

パラメータの使いかたについては、oci_connect() の例も参照ください。

注意

注意: 持続的な Oracle接続の生存時間と最大数は、PHP のプロセス単位で調節できます。 次の設定値を利用します。 oci8.persistent_timeout, oci8.ping_interval, oci8.max_persistent 。

参考

  • oci_connect() - Oracle データベースに接続する
  • oci_new_connect() - 一意な接続を使って Oracle サーバーへ接続する


Register a user-defined callback function for Oracle Database TAF

  • ≪ oci_pconnect
  • oci_result ≫
  • PHP Manual
  • OCI8 関数
  • Register a user-defined callback function for Oracle Database TAF

oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF

説明

oci_register_taf_callback(resource $connection, ?callable $callback): bool

Registers a user-defined callback function to connection. If connection fails due to instance or network failure, the registered callback function will be invoked for several times during failover. See OCI8 Transparent Application Failover (TAF) Support for information.

When oci_register_taf_callback() is called multiple times, each registration overwrites the previous one.

Use oci_unregister_taf_callback() to explicitly unregister a user-defined callback.

TAF callback registration will NOT be saved across persistent connections, therefore the callback needs to be re-registered for a new persistent connection.

パラメータ

connection

An Oracle connection identifier.

callback

A user-defined callback to register for Oracle TAF. It can be a string of the function name or a Closure (anonymous function).

The interface of a TAF user-defined callback function is as follows:

userCallbackFn(resource $connection, int $event, int $type): int

See the parameter description and an example on OCI8 Transparent Application Failover (TAF) Support page.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • oci_unregister_taf_callback() - Unregister a user-defined callback function for Oracle Database TAF


フェッチした行からフィールドの値を取得する

  • ≪ oci_register_taf_callback
  • oci_rollback ≫
  • PHP Manual
  • OCI8 関数
  • フェッチした行からフィールドの値を取得する

oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — フェッチした行からフィールドの値を取得する

説明

oci_result(resource $statement, string|int $column): mixed

oci_fetch() によってフェッチされた現在の行のフィールド columnからデータを返します。

OCI8 拡張モジュールによるデータ型マッピングの 詳細については、ドライバが サポートするデータ型 を参照ください。

パラメータ

statement

column

カラム番号 (1から始まる) またはカラム名 (大文字) のどちらかを使用可能です。 カラム名の大文字小文字は、Oracle のメタデータで定義されているものに会わせる必要があります。 カラムの作成時に大文字小文字を明示しなかった場合、メタデータ上は大文字で記録されています。

戻り値

抽象型 (ROWID, LOB, FILE) を除き、全てを文字列として返します。 エラーの場合、false を返します。

例

例1 oci_fetch() と oci_result() を組み合わせる例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
$stid = oci_parse($conn, $sql);
oci_execute($stid);

while (oci_fetch($stid)) {
echo oci_result($stid, 'LOCATION_ID') . " is ";
echo oci_result($stid, 'CITY') . "<br>\n";
}

// 表示:
// 1000 is Roma
// 1100 is Venice

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci_fetch_array() - クエリの次の行を連想配列あるいは数値添字配列で返す
  • oci_fetch_assoc() - クエリの次の行を連想配列で返す
  • oci_fetch_object() - クエリの次の行をオブジェクトとして返す
  • oci_fetch_row() - クエリの次の行を配列で返す
  • oci_fetch_all() - クエリからの複数の行を二次元配列に取得する


未解決のデータベーストランザクションをロールバックする

  • ≪ oci_result
  • oci_server_version ≫
  • PHP Manual
  • OCI8 関数
  • 未解決のデータベーストランザクションをロールバックする

oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — 未解決のデータベーストランザクションをロールバックする

説明

oci_rollback(resource $connection): bool

Oracle 接続 connection について、 コミットされていないすべての変更を取り消します。 取得しているロックはすべて解放します。また、すべての Oracle SAVEPOINTS を削除します。

トランザクションが始まるのは、データを変更する最初の SQL 文が OCI_NO_AUTO_COMMIT フラグつきの oci_execute() で実行されたときです。 それ以降、他の文で実行されたデータの変更は、同じトランザクションの一部となります。 トランザクション内でのデータの変更は、 コミットあるいはロールバックされるまでは一時的なものとなります。 トランザクションがコミットされるまで、 データベースの他のユーザーはその変更を見ることができません。

データを追加したり更新したりする場合にはトランザクションを使うことを推奨します。 これは、データの一貫性やパフォーマンスを考慮したものです。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect(). が返す Oracle 接続 ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 oci_rollback() の例

<?php

// 複数のテーブルにデータを追加し、エラーが発生したらロールバックします

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

// OCI_NO_AUTO_COMMIT フラグで、INSERT 直後にコミットしないよう Oracle に指示します。
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
if (!$r) {
$e = oci_error($stid);
oci_rollback($conn); // 両方のテーブルへの変更をロールバックします
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

// 両方のテーブルへの変更をコミットします
$r = oci_commit($conn);
if (!r) {
$e = oci_error($conn);
trigger_error(htmlentities($e['message']), E_USER_ERROR);
}

?>

例2 SAVEPOINT へのロールバックの例

<?php
$stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

// セーブポイントを作成します
$stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

$stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

// セーブポイントにロールバックする SQL 文を使います
$stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
oci_execute($stid, OCI_NO_AUTO_COMMIT);

oci_commit($conn); // mytab の id は、この時点で 1111 となります
?>

注意

注意:

トランザクションは接続を閉じたとき、 もしくはスクリプトの終了時のいずれの場合でも すぐに自動的にロールバックされます。 トランザクションをコミットするには oci_commit() をコールする必要があります。

oci_execute() を、 OCI_COMMIT_ON_SUCCESS モードや デフォルト状態でコールすると、 その時点までの未確定のトランザクションをすべてコミットします。

Oracle の DDL 文 (CREATE や DROP など) を実行すると、 その時点までの未確定のトランザクションをすべてコミットします。

参考

  • oci_commit() - 未解決のトランザクションをコミットする
  • oci_execute() - 文を実行する


Oracle データベースのバージョンを返す

  • ≪ oci_rollback
  • oci_set_action ≫
  • PHP Manual
  • OCI8 関数
  • Oracle データベースのバージョンを返す

oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Oracle データベースのバージョンを返す

説明

oci_server_version(resource $connection): string|false

Oracle データベースのバージョンと利用可能なオプションを返します。

パラメータ

connection

戻り値

バージョン情報を表す文字列、あるいはエラー時に false を返します。

例

例1 oci_server_version() の例

<?php

$conn = oci_connect("hr", "hrpwd", "localhost/XE");
echo "サーバーのバージョン: " . oci_server_version($conn);

// 出力は
// サーバーのバージョン: Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
// With the Partitioning, OLAP, Data Mining and Real Application Testing option

oci_close($conn);

?>

参考

  • oci_client_version() - Oracle クライアント・ライブラリのバージョンを返す


アクション名を設定します

  • ≪ oci_server_version
  • oci_set_call_timeout ≫
  • PHP Manual
  • OCI8 関数
  • アクション名を設定します

oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — アクション名を設定します

説明

oci_set_action(resource $connection, string $action): bool

Oracle が追跡するアクション名を設定します

PHP からデータベースへの次の「ラウンドトリップ」が起きると、 アクション名がデータベースに登録されます。これは一般的にSQLステートメントが実行されるときに起こります。

V$SESSION のようなデータベース管理ビューから、 アクション名を後に問い合わせることができます。 それは例えば、 V$SQLAREA 及び DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE と一緒に追跡とモニタリングのために使われることができます。

この関数で設定した値は、持続的接続をまたがって保持される可能性があります。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

action

ユーザーが選んだ、長さが最高32バイトの文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 アクションを設定する

<?php

$c = oci_connect('hr', 'welcome', 'localhost/XE');

// アクションを登録する
oci_set_action($c, 'Friend Lookup');

// クエリを実行することで、ラウンドトリップを起こすコードの例:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);

sleep(30);

?>
// スクリプトを実行中、管理者は実行されるアクションを見ることができる

sqlplus system/welcome
SQL> select action from v$session;

注意

注意: Oracle のバージョン

この関数が使えるのは、PHP をバージョン 10g 以降の Oracle データベースライブラリとリンクさせた場合だけです。

ヒント

パフォーマンス

古いバージョンの OCI8 や Oracle データベースでは、クライアントの情報を Oracle の DBMS_APPLICATION_INFO パッケージで設定することができました。 それよりも oci_set_client_info() を使うほうが効率的です。

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

参考

  • oci_set_module_name() - モジュール名を設定します
  • oci_set_client_info() - クライアント情報を設定する
  • oci_set_client_identifier() - クライアント識別子を設定します
  • oci_set_db_operation() - Sets the database operation


Sets a millisecond timeout for database calls

  • ≪ oci_set_action
  • oci_set_client_identifier ≫
  • PHP Manual
  • OCI8 関数
  • Sets a millisecond timeout for database calls

oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Sets a millisecond timeout for database calls

説明

oci_set_call_timeout(resource $connection, int $timeout): bool

Sets a timeout limiting the maxium time a database round-trip using this connection may take.

Each OCI8 operation may make zero or more calls to Oracle's client library. These internal calls may then may make zero or more round-trips to Oracle Database. If any one of those round-trips takes more than time_out milliseconds, then the operation is cancelled and an error is returned to the application.

The time_out value applies to each round-trip individually, not to the sum of all round-trips. Time spent processing in PHP OCI8 before or after the completion of each round-trip is not counted.

When a call is interrupted, Oracle will attempt to clean up the connection for reuse. This operation is allowed to run for another time_out period. Depending on the outcome of the cleanup, the connection may or may not be reusable.

When persistent connections are used, the timeout value will be retained across PHP requests.

The oci_set_call_timeout() function is available when OCI8 uses Oracle 18 (or later) Client libraries.

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

timeout

The maximum time in milliseconds that any single round-trip between PHP and Oracle Database may take.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Setting the timeout

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
oci_set_call_timeout($conn, 5000);

?>


クライアント識別子を設定します

  • ≪ oci_set_call_timeout
  • oci_set_client_info ≫
  • PHP Manual
  • OCI8 関数
  • クライアント識別子を設定します

oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — クライアント識別子を設定します

説明

oci_set_client_identifier(resource $connection, string $client_id): bool

同一のデータベース・ユーザーとして認証するライトウェイト・アプリケーションのユーザーを識別するために、 様々なデータベースコンポーネントによって使用されるクライアント識別子を設定します。

PHP からデータベースへの次の「ラウンドトリップ」が起きると、 クライアント識別子がデータベースに登録されます。これは一般的にSQLステートメントが実行されるときに起こります。

SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM DUAL などとして、クライアント識別子を後に問い合わせることができます。 V$SESSION のようなデータベース管理ビューにも同じ値が含まれています。 それは DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE と一緒に追跡のために使われることができます。 それは監査のために使われることができます。

この関数で設定した値は、同じ持続的接続を使っている複数のページリクエストにまたがって保持される可能性があります。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

client_id

ユーザーが選んだ、長さが最高64バイトの文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 クライアント識別子をアプリケーションのユーザーに設定する

<?php

// アプリケーションのユーザーログイン名を検索
session_start();
$un = my_validate_session($_SESSION['username']);
$c = oci_connect('myschema', 'welcome', 'localhost/XE');

// そのユーザーが誰であるか Oracle に通知
oci_set_client_identifier($c, $un);

// データベースへの次の「ラウンドトリップ」がその識別子を背負うでしょう
$s = oci_parse($c, 'select mydata from mytable');
oci_execute($s);

// ...

?>

注意

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

参考

  • oci_set_module_name() - モジュール名を設定します
  • oci_set_action() - アクション名を設定します
  • oci_set_client_info() - クライアント情報を設定する
  • oci_set_db_operation() - Sets the database operation


クライアント情報を設定する

  • ≪ oci_set_client_identifier
  • oci_set_db_operation ≫
  • PHP Manual
  • OCI8 関数
  • クライアント情報を設定する

oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — クライアント情報を設定する

説明

oci_set_client_info(resource $connection, string $client_info): bool

Oracle が追跡するクライアント情報を設定します。

PHP からデータベースへの次の「ラウンドトリップ」が起きると、 クライアント情報がデータベースに登録されます。これは一般的にSQLステートメントが実行されるときに起こります。

V$SESSION のようなデータベース管理ビューから、 クライアント情報を後に問い合わせることができます。

この関数で設定した値は、持続的接続をまたがって保持される可能性があります。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

client_info

ユーザーが選んだ、長さが最高64バイトの文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 クライアント情報を設定する

<?php

$c = oci_connect('hr', 'welcome', 'localhost/XE');

// クライアント情報を登録する
oci_set_client_info($c, 'My Application Version 2');

// クエリを実行することで、ラウンドトリップを起こすコードの例:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);

sleep(30);

?>
// スクリプトを実行中、管理者はクライアント情報を見ることができる

sqlplus system/welcome
SQL> select client_info from v$session;

注意

注意: Oracle のバージョン

この関数が使えるのは、PHP をバージョン 10g 以降の Oracle データベースライブラリとリンクさせた場合だけです。

ヒント

パフォーマンス

古いバージョンの OCI8 や Oracle データベースでは、クライアントの情報を Oracle の DBMS_APPLICATION_INFO パッケージで設定することができました。 それよりも oci_set_client_info() を使うほうが効率的です。

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

参考

  • oci_set_module_name() - モジュール名を設定します
  • oci_set_action() - アクション名を設定します
  • oci_set_client_identifier() - クライアント識別子を設定します
  • oci_set_db_operation() - Sets the database operation


Sets the database operation

  • ≪ oci_set_client_info
  • oci_set_edition ≫
  • PHP Manual
  • OCI8 関数
  • Sets the database operation

oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Sets the database operation

説明

oci_set_db_operation(resource $connection, string $action): bool

Sets the DBOP for Oracle tracing.

The database operation name is registered with the database when the next 'round-trip' from PHP to the database occurs, typically when a SQL statement is executed.

The database operation can subsequently be queried from database administration views such as V$SQL_MONITOR.

The oci_set_db_operation() function is available when OCI8 uses Oracle 12 (or later) Client libraries and Oracle Database 12 (or later).

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

action

User chosen string.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Setting the DBOP

<?php

$c = oci_connect('hr', 'welcome', 'localhost/XE');

// Record the operation
oci_set_db_operation($c, 'main query');

// Code that causes a round-trip, for example a query:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);

sleep(30);

?>
// While the script is running, the administrator can see the database operations
// being performed:

sqlplus system/welcome
SQL> select dbop_name from v$sql_monitor;

注意

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

参考

  • oci_set_action() - アクション名を設定します
  • oci_set_module_name() - モジュール名を設定します
  • oci_set_client_info() - クライアント情報を設定する
  • oci_set_client_identifier() - クライアント識別子を設定します


データベース・エディション を設定します

  • ≪ oci_set_db_operation
  • oci_set_module_name ≫
  • PHP Manual
  • OCI8 関数
  • データベース・エディション を設定します

oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — データベース・エディション を設定します

説明

oci_set_edition(string $edition): bool

後続の接続で使用する、オブジェクトのデータベース・エディション を設定します。

オラクル・エディション により、同じスキーマ名とオブジェクト名を使って、複数のバージョンのアプリケーションが稼動できます。これは、稼動中のシステムをアップグレードするときに便利です。

oci_connect(), oci_pconnect() や oci_new_connect() を呼び出す前に、oci_set_edition() をコールして下さい。

データベースで無効なエディションが設定されると、たとえ oci_set_edition() が成功しても接続は失敗します。

持続的接続を使用している場合、リクエストされたエディション設定値による接続がもしすでにあれば、それが再利用されます。それ以外の場合、持続的接続が別途作成されます。

パラメータ

edition

SQLコマンド "CREATE EDITION" であらかじめ作成されたオラクル・データベース・エディション名

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 異なるバージョンの myfunc() が利用できる例

<?php

// File 1

echo "Version 1 of application\n";

oci_set_edition('ORA$BASE');
$c = oci_connect('hr', 'welcome', 'localhost/XE');

$s = oci_parse($c, "begin :r := myfunc(); end;");
oci_bind_by_name($s, ":r", $r, 20);
oci_execute($s);
echo "The result is $r\n";

?>
<?php

// File 2

echo "Version 2 of application\n";

oci_set_edition('E1');
$c = oci_connect('hr', 'welcome', 'localhost/XE');

$s = oci_parse($c, "begin :r := myfunc(); end;");
oci_bind_by_name($s, ":r", $r, 20);
oci_execute($s);
echo "The result is $r\n";

?>

注意

注意: Oracle バージョン必要条件

この関数は Oracle 11gR2 以降で利用可能です

警告

持続的接続

持続的接続を使用しているときに "ALTER SESSION SET EDITION" を使ってデータベース・エディションを変更してはいけません。これは設定の不整合や予想外のエラーを避けるためです。

警告

DRCP 接続プーリング

Oracle 11.2.0.1 でエディションや DRCP を使用する際の設定の不整合や予想外のエラーを避けるため、oci8.connection_class と アプリケーションで使用されるエディション名との間が１対１の対応になるように保ってください。 与えられた接続クラスのプールされたサーバーはそれぞれ、１つのエディションだけで使われるべきです。 この制約は、Oracle 11.2.0.2 以降ではなくなりました。


モジュール名を設定します

  • ≪ oci_set_edition
  • oci_set_prefetch ≫
  • PHP Manual
  • OCI8 関数
  • モジュール名を設定します

oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — モジュール名を設定します

説明

oci_set_module_name(resource $connection, string $name): bool

Oracle が追跡するモジュール名を設定します

PHP からデータベースへの次の「ラウンドトリップ」が起きると、 モジュール名がデータベースに登録されます。これは一般的にSQLステートメントが実行されるときに起こります。

V$SESSION のようなデータベース管理ビューから、 名称を後に問い合わせることができます。 それは例えば、 V$SQLAREA 及び DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE と一緒に追跡とモニタリングのために使われることができます。

この関数で設定した値は、持続的接続をまたがって保持される可能性があります。

パラメータ

connection

oci_connect()、oci_pconnect() あるいは oci_new_connect() が返す Oracle 接続 ID。

name

ユーザーが選んだ、長さが最高48バイトの string 。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 モジュール名を設定する

<?php

$c = oci_connect('hr', 'welcome', 'localhost/XE');

// モジュールを登録する
oci_set_module_name($c, 'Home Page');

// クエリを実行することで、ラウンドトリップを起こすコードの例:
$s = oci_parse($c, 'select * from dual');
oci_execute($s);
oci_fetch_all($s, $res);

sleep(30);
?>
// スクリプトを実行中、管理者は使用中のモジュールを見ることができる

sqlplus system/welcome
SQL> select module from v$session;

注意

注意: Oracle のバージョン

この関数が使えるのは、PHP をバージョン 10g 以降の Oracle データベースライブラリとリンクさせた場合だけです。

ヒント

パフォーマンス

古いバージョンの OCI8 や Oracle データベースでは、クライアントの情報を Oracle の DBMS_APPLICATION_INFO パッケージで設定することができました。 それよりも oci_set_client_info() を使うほうが効率的です。

警告

データベースとのやりとりに関するメモ

OCI8 関数の中には、データベースとのやりとりを伴わないものもあります。 たとえば、結果のキャッシングが有効になっている場合、 クエリを実行してもデータベースとのやりとりを行わない可能性があります。

参考

  • oci_set_action() - アクション名を設定します
  • oci_set_client_info() - クライアント情報を設定する
  • oci_set_client_identifier() - クライアント識別子を設定します
  • oci_set_db_operation() - Sets the database operation


クエリがプリフェッチする行数を設定する

  • ≪ oci_set_module_name
  • oci_set_prefetch_lob ≫
  • PHP Manual
  • OCI8 関数
  • クエリがプリフェッチする行数を設定する

oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — クエリがプリフェッチする行数を設定する

説明

oci_set_prefetch(resource $statement, int $rows): bool

oci_execute() のコール、およびそれに伴う内部的なデータベースへのリクエストがすべて成功した後に Oracle Client ライブラリがバッファに取り込む行数を設定します。 クエリが返す結果の行数が多くなる場合は、プリフェッチ行数をデフォルトの oci8.default_prefetch より大きくしておくとパフォーマンスが劇的に向上します。

プリフェッチは、Oracle がデータベースからデータを取得する際の効率的な方法で、 一回のネットワークリクエストで複数の行を取得します。こうすれば、 ネットワークや CPU の利用効率がよくなります。 行のバッファリングは OCI8 の内部的なものであり、 プリフェッチ行数が変わっても OCI8 のフェッチ関数群の挙動は変わりません。 たとえば、oci_fetch_row() は、常に一行だけを返します。 プリフェッチバッファはステートメント単位で設定されるものであり、 ステートメントを再実行したときや他の接続から実行したときには使われません。

oci_set_prefetch() は oci_execute() の前にコールします。

ネットワークやデータベースの状況を考慮して、 プリフェッチの値を適切な大きさに設定することがチューニングの目標です。 大量の行を返すクエリの場合は、データベースからの行の取得を いくつかの塊に分けて行うとシステム全体の効率が良くなるかもしれません (つまり、プリフェッチの値を行数より小さめに設定するということです)。 こうすれば、PHP スクリプトが現在の行を処理している間にも データベースが別のユーザーからのステートメントを処理できるようになります。

クエリのプリフェッチが導入されたのは、Oracle 8i からです。 REF CURSOR のプリフェッチが導入されたのは Oracle 11gR2 からで、 PHP を Oracle 11gR2 以降のクライアントライブラリとリンクすれば使えます。 ネストしたカーソルのプリフェッチが導入されたのは Oracle 11gR2 からで、 これを使うには Oracle クライアントライブラリと接続先のデータベースがどちらも 11gR2 以降でなければなりません。

プリフェッチは、LONG あるいは LOB 列を含むクエリには対応していません。 プリフェッチに対応していないクエリの場合はプリフェッチの値は無視され、 どんな場合でも一行単位でフェッチします。

Oracle Database 12c では、PHP で設定したプリフェッチの値を Oracle のクライアント設定ファイル oraaccess.xml で上書きできます。 詳細は、Oracle のドキュメントを参照ください。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

rows

プリフェッチする行数。>= 0

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 クエリのデフォルトプリフェッチ値の変更

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
oci_set_prefetch($stid, 300); // oci_execute() のコール前に設定します
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($stid);
oci_close($conn);

?>

例2 REF CURSOR のデフォルトプリフェッチの変更

<?php
/*
下記のようにして PL/SQL ストアド・プロシジャーを作成します。

CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
BEGIN
OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
END;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

// プリフェッチはカーソルの実行前に変更します。
// REF CURSOR のプリフェッチが使えるのは、PHP を Oracle 11R2 以降のクライアントライブラリとリンクしたときです。
oci_set_prefetch($refcur, 200);
oci_execute($refcur);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($refcur);
oci_free_statement($stid);
oci_close($conn);

?>

PHP OCI8 で REF CURSOR からフェッチした内容を別の PL/SQL プロシージャに渡すときには、REF CURSOR のプリフェッチ行数を 0 に設定して行が結果セットから "失われる" ことを防ぎます。 プリフェッチの値は OCI8 内部でのデータベースへのリクエスト時に余計に取得する行数です。 つまり、0 に設定すると一度に一行だけ取得するということになります。

例3 REF CURSOR を Oracle に戻すときのプリフェッチの設定

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/orcl');

// REF CURSOR を取得します
$stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

// ふたつの行を表示しますが、それ以上の余計な行はプリフェッチしません。
// 余計な行は myproc_use_rc() には戻されません。
oci_set_prefetch($refcur, 0);
oci_execute($refcur);
$row = oci_fetch_array($refcur);
var_dump($row);
$row = oci_fetch_array($refcur);
var_dump($row);

// REF CURSOR を myproc_use_rc() に渡して、
// 結果セットに対してさらにデータ処理を行います
$stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

?>

参考

  • oci8.default_prefetch ini オプション


CLOB や BLOB ごとにプリフェッチするデータサイズを設定する

  • ≪ oci_set_prefetch
  • oci_statement_type ≫
  • PHP Manual
  • OCI8 関数
  • CLOB や BLOB ごとにプリフェッチするデータサイズを設定する

oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — CLOB や BLOB ごとにプリフェッチするデータサイズを設定する

説明

oci_set_prefetch_lob(resource $statement, int $prefetch_lob_size): bool

oci_execute() を使って成功したクエリや、 その後に実行されるデータベースへの内部的なフェッチリクエストによって、 内部的な Oracle LOB ロケータを取得する際に、 CLOB や BLOB ごとにフェッチする内部バッファサイズを設定します。 この値を増やすと、LOB のサイズが小さい場合に、 PHP と データベース間の問い合わせの数を減らすことができ、パフォーマンスを向上させることができます。 メモリ消費量は増加します。

ここで設定する値は、OCILob インスタンスとして返されるLOB や OCI_RETURN_LOBS を使って返される LOB に影響します。

oci_execute() をコールする前に、 oci_set_prefetch_lob() をコールするようにして下さい。 コールされない場合、oci8.prefetch_lob_size の値を使います。

LOB のプリフェッチサイズの値は、Oracle Database 12.2 以降でのみ設定できます。

パラメータ

statement

oci_parse() で作成して oci_execute() で実行した有効な OCI8 ステートメント ID、 あるいは REF CURSOR ステートメント ID。

prefetch_lob_size

LOB ごとにプリフェッチするバイト数を、0以上の値として設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 LOB のプリフェッチサイズをクエリ毎に変更する

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT myclob FROM mytable');
oci_set_prefetch_lob($stid, 100000); // Set before calling oci_execute()
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS+OCI_RETURN_LOBS)) {
echo "<tr>\n";
foreach ($row as $item) {
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
}
echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($stid);
oci_close($conn);

?>

参考

  • oci8.prefetch_lob_size ini オプション


ステートメントの種類を返す

  • ≪ oci_set_prefetch_lob
  • oci_unregister_taf_callback ≫
  • PHP Manual
  • OCI8 関数
  • ステートメントの種類を返す

oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — ステートメントの種類を返す

説明

oci_statement_type(resource $statement): string|false

OCI ステートメント statement の種類をあらわすキーワードを返します。

パラメータ

statement

oci_parse() が返す、有効な OCI8 ステートメント ID。

戻り値

ステートメント statement の種類を次のいずれかの値で返します。

ステートメントの種類
返される文字列 | 注意
ALTER |
BEGIN |
CALL |
CREATE |
DECLARE |
DELETE |
DROP |
INSERT |
SELECT |
UPDATE |
UNKNOWN |

エラー時には false を返します。

例

例1 oci_statement_type() の例

<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
if (oci_statement_type($stid) == "DELETE") {
trigger_error('このテーブルを削除する権限がありません', E_USER_ERROR);
}
else {
oci_execute($stid); // 行を削除します
}

oci_free_statement($stid);
oci_close($conn);

?>


Unregister a user-defined callback function for Oracle Database TAF

  • ≪ oci_statement_type
  • OCICollection ≫
  • PHP Manual
  • OCI8 関数
  • Unregister a user-defined callback function for Oracle Database TAF

oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF

説明

oci_unregister_taf_callback(resource $connection): bool

Unregister the user-defined callback function registered to connection by oci_register_taf_callback(). See OCI8 Transparent Application Failover (TAF) Support for information.

パラメータ

connection

An Oracle connection identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • oci_register_taf_callback() - Register a user-defined callback function for Oracle Database TAF


OCICollection クラス

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

はじめに

OCI8 コレクション機能です。

注意:

OCI-Collection クラスは、 PHP 8 と OCI8 3.0.0 で、 PHP の名前付けの規約に従い OCICollection に名前が変更されました。

クラス概要

class OCICollection {
/* メソッド */
public append(string $value): bool
public assign(OCICollection $from): bool
public assignElem(int $index, string $value): bool
public free(): bool
public getElem(int $index): string|float|null|false
public max(): int|false
public size(): int|false
public trim(int $num): bool
}

目次

  • OCICollection::append — コレクションに要素を追加する
  • OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる
  • OCICollection::assignElem — コレクションの要素に値を割り当てる
  • OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する
  • OCICollection::getElem — 要素の値を返す
  • OCICollection::max — コレクション内の要素の最大数を取得する
  • OCICollection::size — コレクションのサイズを返す
  • OCICollection::trim — コレクションの最後から要素を切り取る


コレクションに要素を追加する

  • ≪ OCICollection
  • OCICollection::assign ≫
  • PHP Manual
  • OCICollection
  • コレクションに要素を追加する

OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — コレクションに要素を追加する

説明

public OCICollection::append(string $value): bool

コレクションの最後に要素を追加します。

パラメータ

value

コレクションに追加する値を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::assign


コレクションに他の存在するコレクションから値を割り当てる

  • ≪ OCICollection::append
  • OCICollection::assignElem ≫
  • PHP Manual
  • OCICollection
  • コレクションに他の存在するコレクションから値を割り当てる

OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる

説明

public OCICollection::assign(OCICollection $from): bool

事前に生成された他のコレクションからコレクションの値を割り当てます。 両方のコレクションは、使用する前に oci_new_collection() を使って生成される必要があります。

パラメータ

from

OCICollection インスタンスを指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::append


コレクションの要素に値を割り当てる

  • ≪ OCICollection::assign
  • OCICollection::free ≫
  • PHP Manual
  • OCICollection
  • コレクションの要素に値を割り当てる

OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — コレクションの要素に値を割り当てる

説明

public OCICollection::assignElem(int $index, string $value): bool

インデックス index の要素に値を割り当てます。

パラメータ

index

要素のインデックス。最初のインデックスは 0 です。

value

文字列あるいは数値です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::getElem


コレクションオブジェクトに関連付けられたリソースを解放する

  • ≪ OCICollection::assignElem
  • OCICollection::getElem ≫
  • PHP Manual
  • OCICollection
  • コレクションオブジェクトに関連付けられたリソースを解放する

OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する

説明

public OCICollection::free(): bool

コレクションオブジェクトに関連付けられたリソースを解放します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • oci_new_collection


要素の値を返す

  • ≪ OCICollection::free
  • OCICollection::max ≫
  • PHP Manual
  • OCICollection
  • 要素の値を返す

OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — 要素の値を返す

説明

public OCICollection::getElem(int $index): string|float|null|false

インデックス index (0 から始まる) を持つ要素の値を返します。

パラメータ

index

要素のインデックス。最初のインデックスは 0 です。

戻り値

もし要素が存在しない場合 false 、要素が null 文字列なら null 、要素が文字データ型なら文字列、 要素が数値フィールドなら数値を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::assignElem


コレクション内の要素の最大数を取得する

  • ≪ OCICollection::getElem
  • OCICollection::size ≫
  • PHP Manual
  • OCICollection
  • コレクション内の要素の最大数を取得する

OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — コレクション内の要素の最大数を取得する

説明

public OCICollection::max(): int|false

コレクション内の要素の最大数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

コレクション内の要素の最大数、あるいはエラー時に false を返します。

戻り値が 0 の場合、要素の数に制限はありません。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::size


コレクションのサイズを返す

  • ≪ OCICollection::max
  • OCICollection::trim ≫
  • PHP Manual
  • OCICollection
  • コレクションのサイズを返す

OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — コレクションのサイズを返す

説明

public OCICollection::size(): int|false

コレクションのサイズを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

コレクション内の要素の数、もしくはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::max


コレクションの最後から要素を切り取る

  • ≪ OCICollection::size
  • OCILob ≫
  • PHP Manual
  • OCICollection
  • コレクションの最後から要素を切り取る

OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — コレクションの最後から要素を切り取る

説明

public OCICollection::trim(int $num): bool

コレクションの最後から num 個の要素を切り取ります。

パラメータ

num

切り取る要素の数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

参考

  • OCICollection::size


OCILob クラス

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

はじめに

ラージバイナリ (BLOB) および キャラクタオブジェクト (CLOB) に対する OCI8 ラージオブジェクト (LOB) 機能です。

注意:

OCI-Lob クラスは、 PHP 8 および PECL OCI8 3.0.0 以降、 PHP の名前付けの規約に従って OCILobに名前が変更されました。

クラス概要

class OCILob {
/* メソッド */
public append(OCILob $from): bool
public close(): bool
public eof(): bool
public erase(?int $offset = null, ?int $length = null): int|false
public export(string $filename, ?int $offset = null, ?int $length = null): bool
public flush(int $flag = 0): bool
public free(): bool
public getBuffering(): bool
public import(string $filename): bool
public load(): string|false
public read(int $length): string|false
public rewind(): bool
public save(string $data, int $offset = 0): bool
public seek(int $offset, int $whence = OCI_SEEK_SET): bool
public setBuffering(bool $mode): bool
public size(): int|false
public tell(): int|false
public truncate(int $length = 0): bool
public write(string $data, ?int $length = null): int|false
public writeTemporary(string $data, int $type = OCI_TEMP_CLOB): bool
}

目次

  • OCILob::append — ラージオブジェクトのデータを他のラージオブジェクトに追加する
  • OCILob::close — LOB ディスクリプタを閉じる
  • OCILob::eof — ラージオブジェクトのディスクリプタが EOF かどうかを調べる
  • OCILob::erase — 内部 LOB データの特定の位置を消去する
  • OCILob::export — LOB の内容をファイルに出力する
  • OCILob::flush — LOB のバッファをサーバーにフラッシュする、あるいは書き込む
  • OCILob::free — LOB ディスクリプタに関連付けられたりソースを解放する
  • OCILob::getBuffering — ラージオブジェクトに対する現在のバッファリングの状態を返す
  • OCILob::import — ファイルデータを LOB にインポートする
  • OCILob::load — ラージオブジェクトの内容を返す
  • OCILob::read — ラージオブジェクトの一部を読み込む
  • OCILob::rewind — 内部ポインタをラージオブジェクトの先頭に移動する
  • OCILob::save — データをラージオブジェクトに保存する
  • OCILob::saveFile — のエイリアス OCILob::import
  • OCILob::seek — ラージオブジェクトの内部ポインタをセットする
  • OCILob::setBuffering — 現在のラージオブジェクト用のバッファリング状態を変更する
  • OCILob::size — ラージオブジェクトのサイズを返す
  • OCILob::tell — ラージオブジェクトの内部ポインタの現在位置を返す
  • OCILob::truncate — ラージオブジェクトを切りつめる
  • OCILob::write — データをラージオブジェクトに書き込む
  • OCILob::writeTemporary — 一時的なラージオブジェクトを書き込む
  • OCILob::writeToFile — のエイリアス OCILob::export


ラージオブジェクトのデータを他のラージオブジェクトに追加する

  • ≪ OCILob
  • OCILob::close ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトのデータを他のラージオブジェクトに追加する

OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — ラージオブジェクトのデータを他のラージオブジェクトに追加する

説明

public OCILob::append(OCILob $from): bool

ラージオブジェクトのデータを他のラージオブジェクトに追加します。

前もってバッファリングが有効になっている場合、 ラージオブジェクトの書き込みは失敗するでしょう。 追加の前にバッファリングを無効にしなければなりません。 バッファリングを無効にする前に、 OCILob::flush によってバッファをフラッシュする必要があるかも知れません。

パラメータ

from

コピーする LOB。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::flush
  • OCILob::setBuffering
  • OCILob::getBuffering


LOB ディスクリプタを閉じる

  • ≪ OCILob::append
  • OCILob::eof ≫
  • PHP Manual
  • OCILob
  • LOB ディスクリプタを閉じる

OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — LOB ディスクリプタを閉じる

説明

public OCILob::close(): bool

LOB あるいは FILE のディスクリプタを閉じます。 この関数は OCILob::writeTemporary を併用した場合のみ使用されるべきです。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::writeTemporary


ラージオブジェクトのディスクリプタが EOF かどうかを調べる

  • ≪ OCILob::close
  • OCILob::erase ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトのディスクリプタが EOF かどうかを調べる

OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — ラージオブジェクトのディスクリプタが EOF かどうかを調べる

説明

public OCILob::eof(): bool

ラージオブジェクトの内部ポインタが LOB の最後にあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

もし、ラージオブジェクトの内部ポインタが LOB の最後にあるとき、 true を返します。その他の場合は false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

注意

注意:

OCILob::setBuffering が LOB で有効になっていない場合は、Oracle のエラーを返します。

参考

  • OCILob::size


内部 LOB データの特定の位置を消去する

  • ≪ OCILob::eof
  • OCILob::export ≫
  • PHP Manual
  • OCILob
  • 内部 LOB データの特定の位置を消去する

OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — 内部 LOB データの特定の位置を消去する

説明

public OCILob::erase(?int $offset = null, ?int $length = null): int|false

指定された offset から始まる内部 LOB データの特定の位置を消去します。 パラメータなしでコールすると、すべての LOB データを消去します。

BLOB の場合、消去するということは存在する LOB の値が 0 バイトで上書きされる、ということを意味します。 CLOB の場合、存在する LOB の値はスペースで上書きされる、ということです。

パラメータ

offset

length

戻り値

消去された実際の文字数あるいはバイト数、失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | offset と length は、 nullable になりました。
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::truncate


LOB の内容をファイルに出力する

  • ≪ OCILob::erase
  • OCILob::flush ≫
  • PHP Manual
  • OCILob
  • LOB の内容をファイルに出力する

OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — LOB の内容をファイルに出力する

説明

public OCILob::export(string $filename, ?int $offset = null, ?int $length = null): bool

LOB の内容をファイルに出力します。

パラメータ

filename

ファイルへのパス。

offset

出力を開始する位置。

length

出力するデータの長さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | offset と length は、nullable になりました。
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::import


LOB のバッファをサーバーにフラッシュする、あるいは書き込む

  • ≪ OCILob::export
  • OCILob::free ≫
  • PHP Manual
  • OCILob
  • LOB のバッファをサーバーにフラッシュする、あるいは書き込む

OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — LOB のバッファをサーバーにフラッシュする、あるいは書き込む

説明

public OCILob::flush(int $flag = 0): bool

OCILob::flush() は実際にサーバーにデータを書き込みます。

パラメータ

flag

デフォルトではリソースは解放されませんが、フラグ OCI_LOB_BUFFER_FREE を使用することで明示的に行うことができます。 あなたが何をしようとしているかを理解しておいてください - 次に LOB の同じ箇所に読み書きしようとする場合、 サーバーへのラウンドトリップを伴い、 新しいバッファリソースが初期化されるでしょう。 もはや LOB に対して何も行わない場合のみ、 OCI_LOB_BUFFER_FREE フラグを使用することが推奨されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

バッファリングが有効でない、あるいはエラーが発生した場合、 false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::getBuffering
  • OCILob::setBuffering


LOB ディスクリプタに関連付けられたりソースを解放する

  • ≪ OCILob::flush
  • OCILob::getBuffering ≫
  • PHP Manual
  • OCILob
  • LOB ディスクリプタに関連付けられたりソースを解放する

OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — LOB ディスクリプタに関連付けられたりソースを解放する

説明

public OCILob::free(): bool

事前に oci_new_descriptor() を使用して割り当てられた ディスクリプタに関連付けられたりソースを解放します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。


ラージオブジェクトに対する現在のバッファリングの状態を返す

  • ≪ OCILob::free
  • OCILob::import ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトに対する現在のバッファリングの状態を返す

OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — ラージオブジェクトに対する現在のバッファリングの状態を返す

説明

public OCILob::getBuffering(): bool

ラージオブジェクトに対するバッファリングが有効か無効かを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

もしラージオブジェクトに対するバッファリングが無効な場合は false、 有効な場合は true を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::setBuffering


ファイルデータを LOB にインポートする

  • ≪ OCILob::getBuffering
  • OCILob::load ≫
  • PHP Manual
  • OCILob
  • ファイルデータを LOB にインポートする

OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — ファイルデータを LOB にインポートする

説明

public OCILob::import(string $filename): bool

filename からのデータをラージオブジェクトの現在の位置に書き込みます。

パラメータ

filename

ファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::export
  • OCILob::write


ラージオブジェクトの内容を返す

  • ≪ OCILob::import
  • OCILob::read ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの内容を返す

OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — ラージオブジェクトの内容を返す

説明

public OCILob::load(): string|false

ラージオブジェクトの内容を返します。 memory_limit に達した場合、 スクリプトの実行が終了されますので、 LOB がこの制限を超えないことを確認してください。 多くの場合、代わりに OCILob::read を使用することが推奨されます。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトの内容、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::read


ラージオブジェクトの一部を読み込む

  • ≪ OCILob::load
  • OCILob::rewind ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの一部を読み込む

OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — ラージオブジェクトの一部を読み込む

説明

public OCILob::read(int $length): string|false

LOB の内部ポインタの現在位置から length バイト(BLOB) または、 length 文字 (CLOB) を読み込みます。

現在の LOB の内部ポイントから、 length バイト(BLOB) や length 文字(CLOB) を読み取った場合、 あるいはラージオブジェクトの終わりに達したとき、読み込みを停止します。 ラージオブジェクトの内部ポインタは、 読み込まれたバイト/文字数分だけシフトされます。

パラメータ

length

読み込むバイト数(BLOB) または文字数 (CLOB)。 大きな値を指定すると、1 MB に切り捨てられます。

戻り値

読み込んだ内容を表す文字列、失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::load
  • OCILob::write


内部ポインタをラージオブジェクトの先頭に移動する

  • ≪ OCILob::read
  • OCILob::save ≫
  • PHP Manual
  • OCILob
  • 内部ポインタをラージオブジェクトの先頭に移動する

OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — 内部ポインタをラージオブジェクトの先頭に移動する

説明

public OCILob::rewind(): bool

内部ポインタをラージオブジェクトの先頭にセットします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::seek
  • OCILob::tell


データをラージオブジェクトに保存する

  • ≪ OCILob::rewind
  • OCILob::saveFile ≫
  • PHP Manual
  • OCILob
  • データをラージオブジェクトに保存する

OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — データをラージオブジェクトに保存する

説明

public OCILob::save(string $data, int $offset = 0): bool

data をラージオブジェクトに保存します。

パラメータ

data

保存するデータ。

offset

ラージオブジェクトの先頭からのオフセットを指定するために利用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::write
  • OCILob::import


のエイリアス OCILob::import

  • ≪ OCILob::save
  • OCILob::seek ≫
  • PHP Manual
  • OCILob
  • のエイリアス OCILob::import

OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — のエイリアス OCILob::import()

説明

この関数は次の関数のエイリアスです。 OCILob::import()

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。


ラージオブジェクトの内部ポインタをセットする

  • ≪ OCILob::saveFile
  • OCILob::setBuffering ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの内部ポインタをセットする

OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — ラージオブジェクトの内部ポインタをセットする

説明

public OCILob::seek(int $offset, int $whence = OCI_SEEK_SET): bool

ラージオブジェクトの内部ポインタをセットします。

パラメータ

offset

内部ポインタを whence で示された位置から移動させるバイト数を表します。

whence

以下のいずれかです。

  • OCI_SEEK_SET - offset と等しい位置にセットします
  • OCI_SEEK_CUR - 現在の位置に offset バイト追加します
  • OCI_SEEK_END - ラージオブジェクトの終端に offset バイト追加します (ラージオブジェクトの終端より前の位置に移動するには負の値を指定します)

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::rewind
  • OCILob::tell
  • OCILob::eof


現在のラージオブジェクト用のバッファリング状態を変更する

  • ≪ OCILob::seek
  • OCILob::size ≫
  • PHP Manual
  • OCILob
  • 現在のラージオブジェクト用のバッファリング状態を変更する

OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — 現在のラージオブジェクト用のバッファリング状態を変更する

説明

public OCILob::setBuffering(bool $mode): bool

ラージオブジェクト用のバッファリングを mode パラメータの値で設定します。

この関数を使用することで、LOB の細かな読み込みや書き込みがバッファリングされことにより ネットワークのラウンドトリップや LOB バージョニングの回数が低減され、 パフォーマンスが改善されます。 OCILob::flush() はラージオブジェクトの処理が完了した際、 バッファをフラッシュするために使用します。

パラメータ

mode

true は有効、false は無効を表します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 同じフラグで繰り返しコールすると true を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::getBuffering


ラージオブジェクトのサイズを返す

  • ≪ OCILob::setBuffering
  • OCILob::tell ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトのサイズを返す

OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — ラージオブジェクトのサイズを返す

説明

public OCILob::size(): int|false

ラージオブジェクトのサイズを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ラージオブジェクトのサイズを返します。 失敗した場合に false を返します。 空のオブジェクトは長さ 0 となります。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。


ラージオブジェクトの内部ポインタの現在位置を返す

  • ≪ OCILob::size
  • OCILob::truncate ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトの内部ポインタの現在位置を返す

OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — ラージオブジェクトの内部ポインタの現在位置を返す

説明

public OCILob::tell(): int|false

LOB の内部ポインタの現在位置を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

LOB の内部ポインタの現在位置を返します。 エラーの場合、false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::rewind
  • OCILob::size
  • OCILob::eof


ラージオブジェクトを切りつめる

  • ≪ OCILob::tell
  • OCILob::write ≫
  • PHP Manual
  • OCILob
  • ラージオブジェクトを切りつめる

OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — ラージオブジェクトを切りつめる

説明

public OCILob::truncate(int $length = 0): bool

LOB を切りつめます。

パラメータ

length

指定した場合は、このメソッドはラージオブジェクトを length バイトに切りつめます。 そうでない場合は、LOB を完全に消去します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::erase


データをラージオブジェクトに書き込む

  • ≪ OCILob::truncate
  • OCILob::writeTemporary ≫
  • PHP Manual
  • OCILob
  • データをラージオブジェクトに書き込む

OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — データをラージオブジェクトに書き込む

説明

public OCILob::write(string $data, ?int $length = null): int|false

パラメータ data からのデータを LOB の内部ポインタの現在位置に書き込みます。

パラメータ

data

LOB に書き込むデータ。

length

このパラメータに整数を指定すると、 length バイト書き込むか data の終端に達するか、 いずれか早い方の後に書き込みが停止します。

戻り値

書き込んだバイト数、失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | length は、nullable になりました。
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::read


一時的なラージオブジェクトを書き込む

  • ≪ OCILob::write
  • OCILob::writeToFile ≫
  • PHP Manual
  • OCILob
  • 一時的なラージオブジェクトを書き込む

OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — 一時的なラージオブジェクトを書き込む

説明

public OCILob::writeTemporary(string $data, int $type = OCI_TEMP_CLOB): bool

一時的なラージオブジェクトを生成し、 data を書き込みます。

オブジェクトの使用後、OCILob::close を使用するべきです。

パラメータ

data

書き込むデータ。

type

以下のいずれかです。

  • OCI_TEMP_BLOB が一時的な BLOB を生成するために使われます
  • OCI_TEMP_CLOB が一時的な CLOB を生成するために使われます

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

参考

  • OCILob::close


のエイリアス OCILob::export

  • ≪ OCILob::writeTemporary
  • OCI8 廃止されたエイリアスと関数 ≫
  • PHP Manual
  • OCILob
  • のエイリアス OCILob::export

OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — のエイリアス OCILob::export()

説明

この関数は次の関数のエイリアスです。 OCILob::export().

変更履歴

バージョン | 説明
8.0.0, PECL OCI8 3.0.0 | offset と length は、nullable になりました。
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。


OCI8 廃止されたエイリアスと関数

目次

  • oci_internal_debug — 内部的なデバッグ出力を有効/無効にする
  • ocibindbyname — oci_bind_by_name のエイリアス
  • ocicancel — oci_cancel のエイリアス
  • ocicloselob — OCILob::close のエイリアス
  • ocicollappend — のエイリアス OCICollection::append
  • ocicollassign — のエイリアス OCICollection::assign
  • ocicollassignelem — のエイリアス OCICollection::assignElem
  • ocicollgetelem — のエイリアス OCICollection::getElem
  • ocicollmax — のエイリアス OCICollection::max
  • ocicollsize — のエイリアス OCICollection::size
  • ocicolltrim — のエイリアス OCICollection::trim
  • ocicolumnisnull — oci_field_is_null のエイリアス
  • ocicolumnname — oci_field_name のエイリアス
  • ocicolumnprecision — oci_field_precision のエイリアス
  • ocicolumnscale — oci_field_scale のエイリアス
  • ocicolumnsize — oci_field_size のエイリアス
  • ocicolumntype — oci_field_type のエイリアス
  • ocicolumntyperaw — oci_field_type_raw のエイリアス
  • ocicommit — oci_commit のエイリアス
  • ocidefinebyname — oci_define_by_name のエイリアス
  • ocierror — oci_error のエイリアス
  • ociexecute — oci_execute のエイリアス
  • ocifetch — oci_fetch のエイリアス
  • ocifetchinto — 廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種
  • ocifetchstatement — oci_fetch_all のエイリアス
  • ocifreecollection — のエイリアス OCICollection::free
  • ocifreecursor — oci_free_statement のエイリアス
  • ocifreedesc — OCILob::free のエイリアス
  • ocifreestatement — oci_free_statement のエイリアス
  • ociinternaldebug — oci_internal_debug のエイリアス
  • ociloadlob — OCILob::load のエイリアス
  • ocilogoff — oci_close のエイリアス
  • ocilogon — oci_connect のエイリアス
  • ocinewcollection — oci_new_collection のエイリアス
  • ocinewcursor — oci_new_cursor のエイリアス
  • ocinewdescriptor — oci_new_descriptor のエイリアス
  • ocinlogon — oci_new_connect のエイリアス
  • ocinumcols — oci_num_fields のエイリアス
  • ociparse — oci_parse のエイリアス
  • ociplogon — oci_pconnect のエイリアス
  • ociresult — oci_result のエイリアス
  • ocirollback — oci_rollback のエイリアス
  • ocirowcount — oci_num_rows のエイリアス
  • ocisavelob — OCILob::save のエイリアス
  • ocisavelobfile — OCILob::import のエイリアス
  • ociserverversion — oci_server_version のエイリアス
  • ocisetprefetch — oci_set_prefetch のエイリアス
  • ocistatementtype — oci_statement_type のエイリアス
  • ociwritelobtofile — OCILob::export のエイリアス
  • ociwritetemporarylob — OCILob::writeTemporary のエイリアス


内部的なデバッグ出力を有効/無効にする

  • ≪ OCI8 廃止されたエイリアスと関数
  • ocibindbyname ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • 内部的なデバッグ出力を有効/無効にする

oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — 内部的なデバッグ出力を有効/無効にする

説明

oci_internal_debug(bool $onoff): void

内部的なデバッグ出力を有効/無効にします。

パラメータ

onoff

この値を false にすると、デバッグ出力がオフになり、 true にするとオンになります。

戻り値

値を返しません。

注意

注意:

この関数は PHP 8 と PECL OCI8 3.0 からは削除されています。


oci_bind_by_name のエイリアス

  • ≪ oci_internal_debug
  • ocicancel ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_bind_by_name のエイリアス

ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — oci_bind_by_name() のエイリアス

説明

oci_bind_by_name() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_cancel のエイリアス

  • ≪ ocibindbyname
  • ocicloselob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_cancel のエイリアス

ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — oci_cancel() のエイリアス

説明

oci_cancel() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::close のエイリアス

  • ≪ ocicancel
  • ocicollappend ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::close のエイリアス

ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — OCILob::close() のエイリアス

説明

OCILob::close() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::append

  • ≪ ocicloselob
  • ocicollassign ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::append

ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — のエイリアス OCICollection::append()

説明

のエイリアス OCICollection::append()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::assign

  • ≪ ocicollappend
  • ocicollassignelem ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::assign

ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — のエイリアス OCICollection::assign()

説明

のエイリアス OCICollection::assign()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::assignElem

  • ≪ ocicollassign
  • ocicollgetelem ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::assignElem

ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — のエイリアス OCICollection::assignElem()

説明

のエイリアス OCICollection::assignElem()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::getElem

  • ≪ ocicollassignelem
  • ocicollmax ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::getElem

ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — のエイリアス OCICollection::getElem()

説明

のエイリアス OCICollection::getElem()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::max

  • ≪ ocicollgetelem
  • ocicollsize ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::max

ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — のエイリアス OCICollection::max()

説明

のエイリアス OCICollection::max()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::size

  • ≪ ocicollmax
  • ocicolltrim ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::size

ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — のエイリアス OCICollection::size()

説明

のエイリアス OCICollection::size()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::trim

  • ≪ ocicollsize
  • ocicolumnisnull ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::trim

ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — のエイリアス OCICollection::trim()

説明

のエイリアス OCICollection::trim()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_is_null のエイリアス

  • ≪ ocicolltrim
  • ocicolumnname ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_is_null のエイリアス

ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — oci_field_is_null() のエイリアス

説明

oci_field_is_null() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_name のエイリアス

  • ≪ ocicolumnisnull
  • ocicolumnprecision ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_name のエイリアス

ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — oci_field_name() のエイリアス

説明

oci_field_name() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_precision のエイリアス

  • ≪ ocicolumnname
  • ocicolumnscale ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_precision のエイリアス

ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — oci_field_precision() のエイリアス

説明

oci_field_precision() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_scale のエイリアス

  • ≪ ocicolumnprecision
  • ocicolumnsize ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_scale のエイリアス

ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — oci_field_scale() のエイリアス

説明

oci_field_scale() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_size のエイリアス

  • ≪ ocicolumnscale
  • ocicolumntype ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_size のエイリアス

ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — oci_field_size() のエイリアス

説明

oci_field_size() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_type のエイリアス

  • ≪ ocicolumnsize
  • ocicolumntyperaw ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_type のエイリアス

ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — oci_field_type() のエイリアス

説明

oci_field_type() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_field_type_raw のエイリアス

  • ≪ ocicolumntype
  • ocicommit ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_field_type_raw のエイリアス

ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — oci_field_type_raw() のエイリアス

説明

oci_field_type_raw() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_commit のエイリアス

  • ≪ ocicolumntyperaw
  • ocidefinebyname ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_commit のエイリアス

ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — oci_commit() のエイリアス

説明

oci_commit() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_define_by_name のエイリアス

  • ≪ ocicommit
  • ocierror ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_define_by_name のエイリアス

ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — oci_define_by_name() のエイリアス

説明

oci_define_by_name() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_error のエイリアス

  • ≪ ocidefinebyname
  • ociexecute ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_error のエイリアス

ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — oci_error() のエイリアス

説明

oci_error() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_execute のエイリアス

  • ≪ ocierror
  • ocifetch ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_execute のエイリアス

ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — oci_execute() のエイリアス

説明

oci_execute() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_fetch のエイリアス

  • ≪ ociexecute
  • ocifetchinto ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_fetch のエイリアス

ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — oci_fetch() のエイリアス

説明

oci_fetch() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種

  • ≪ ocifetch
  • ocifetchstatement ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • 廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種

ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — 廃止された関数。oci_fetch_array() や oci_fetch_object()、
   oci_fetch_assoc()、
   oci_fetch_row() の変種

説明

oci_fetch_array() や oci_fetch_object()、
  oci_fetch_assoc()、
  oci_fetch_row() の変種です。

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_fetch_all のエイリアス

  • ≪ ocifetchinto
  • ocifreecollection ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_fetch_all のエイリアス

ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — oci_fetch_all() のエイリアス

説明

oci_fetch_all() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


のエイリアス OCICollection::free

  • ≪ ocifetchstatement
  • ocifreecursor ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • のエイリアス OCICollection::free

ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — のエイリアス OCICollection::free()

説明

のエイリアス OCICollection::free()

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_free_statement のエイリアス

  • ≪ ocifreecollection
  • ocifreedesc ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_free_statement のエイリアス

ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — oci_free_statement() のエイリアス

説明

oci_free_statement() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::free のエイリアス

  • ≪ ocifreecursor
  • ocifreestatement ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::free のエイリアス

ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — OCILob::free() のエイリアス

説明

OCILob::free() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_free_statement のエイリアス

  • ≪ ocifreedesc
  • ociinternaldebug ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_free_statement のエイリアス

ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — oci_free_statement() のエイリアス

説明

oci_free_statement() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_internal_debug のエイリアス

  • ≪ ocifreestatement
  • ociloadlob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_internal_debug のエイリアス

ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — oci_internal_debug() のエイリアス

説明

oci_internal_debug() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::load のエイリアス

  • ≪ ociinternaldebug
  • ocilogoff ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::load のエイリアス

ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — OCILob::load() のエイリアス

説明

OCILob::load() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_close のエイリアス

  • ≪ ociloadlob
  • ocilogon ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_close のエイリアス

ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — oci_close() のエイリアス

説明

oci_close() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_connect のエイリアス

  • ≪ ocilogoff
  • ocinewcollection ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_connect のエイリアス

ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — oci_connect() のエイリアス

説明

oci_connect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_new_collection のエイリアス

  • ≪ ocilogon
  • ocinewcursor ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_collection のエイリアス

ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — oci_new_collection() のエイリアス

説明

oci_new_collection() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_new_cursor のエイリアス

  • ≪ ocinewcollection
  • ocinewdescriptor ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_cursor のエイリアス

ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — oci_new_cursor() のエイリアス

説明

oci_new_cursor() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_new_descriptor のエイリアス

  • ≪ ocinewcursor
  • ocinlogon ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_descriptor のエイリアス

ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — oci_new_descriptor() のエイリアス

説明

oci_new_descriptor() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_new_connect のエイリアス

  • ≪ ocinewdescriptor
  • ocinumcols ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_new_connect のエイリアス

ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — oci_new_connect() のエイリアス

説明

oci_new_connect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_num_fields のエイリアス

  • ≪ ocinlogon
  • ociparse ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_num_fields のエイリアス

ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — oci_num_fields() のエイリアス

説明

oci_num_fields() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_parse のエイリアス

  • ≪ ocinumcols
  • ociplogon ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_parse のエイリアス

ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — oci_parse() のエイリアス

説明

oci_parse() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_pconnect のエイリアス

  • ≪ ociparse
  • ociresult ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_pconnect のエイリアス

ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — oci_pconnect() のエイリアス

説明

oci_pconnect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_result のエイリアス

  • ≪ ociplogon
  • ocirollback ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_result のエイリアス

ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — oci_result() のエイリアス

説明

oci_result() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_rollback のエイリアス

  • ≪ ociresult
  • ocirowcount ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_rollback のエイリアス

ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — oci_rollback() のエイリアス

説明

oci_rollback() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_num_rows のエイリアス

  • ≪ ocirollback
  • ocisavelob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_num_rows のエイリアス

ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — oci_num_rows() のエイリアス

説明

oci_num_rows() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::save のエイリアス

  • ≪ ocirowcount
  • ocisavelobfile ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::save のエイリアス

ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — OCILob::save() のエイリアス

説明

OCILob::save() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::import のエイリアス

  • ≪ ocisavelob
  • ociserverversion ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::import のエイリアス

ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — OCILob::import() のエイリアス

説明

OCILob::import() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_server_version のエイリアス

  • ≪ ocisavelobfile
  • ocisetprefetch ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_server_version のエイリアス

ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — oci_server_version() のエイリアス

説明

oci_server_version() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_set_prefetch のエイリアス

  • ≪ ociserverversion
  • ocistatementtype ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_set_prefetch のエイリアス

ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — oci_set_prefetch() のエイリアス

説明

oci_set_prefetch() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


oci_statement_type のエイリアス

  • ≪ ocisetprefetch
  • ociwritelobtofile ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • oci_statement_type のエイリアス

ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — oci_statement_type() のエイリアス

説明

oci_statement_type() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::export のエイリアス

  • ≪ ocistatementtype
  • ociwritetemporarylob ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::export のエイリアス

ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — OCILob::export() のエイリアス

説明

OCILob::export() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


OCILob::writeTemporary のエイリアス

  • ≪ ociwritelobtofile
  • PostgreSQL ≫
  • PHP Manual
  • OCI8 廃止されたエイリアスと関数
  • OCILob::writeTemporary のエイリアス

ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — OCILob::writeTemporary() のエイリアス

説明

OCILob::writeTemporary() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。


PostgreSQL

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
    • 基本的な使い方
  • PostgreSQL 関数
    • pg_affected_rows — 変更されたレコード(タプル)の数を返す
    • pg_cancel_query — 非同期クエリを取り消す
    • pg_client_encoding — クライアントのエンコーディングを取得する
    • pg_close — PostgreSQL 接続をクローズする
    • pg_connect — PostgreSQL 接続をオープンする
    • pg_connect_poll — 進行中の非同期接続のステータスをポーリングする
    • pg_connection_busy — 接続がビジーかどうか調べる
    • pg_connection_reset — 接続をリセット(再接続)する
    • pg_connection_status — 接続ステータスを取得する
    • pg_consume_input — 接続の入力を読み取る
    • pg_convert — 連想配列の値を、SQL 文として実行可能な形式に変換する
    • pg_copy_from — 配列からテーブルに挿入する
    • pg_copy_to — 配列にテーブルをコピーする
    • pg_dbname — データベース名を取得する
    • pg_delete — レコードを削除する
    • pg_end_copy — PostgreSQL バックエンドと同期する
    • pg_escape_bytea — bytea フィールドに挿入するために文字列をエスケープする
    • pg_escape_identifier — テキスト型フィールドに挿入するために、識別子をエスケープする
    • pg_escape_literal — テキスト型フィールドに挿入するために、リテラルをエスケープする
    • pg_escape_string — クエリに使う文字列をエスケープする
    • pg_execute — 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
    • pg_fetch_all — 取得されたすべての行を配列として取得する
    • pg_fetch_all_columns — 指定したカラムの全ての行を配列として取得する
    • pg_fetch_array — 行を配列として取得する
    • pg_fetch_assoc — 行を連想配列として取得する
    • pg_fetch_object — 行をオブジェクトとして得る
    • pg_fetch_result — 結果インスタンスから値を返す
    • pg_fetch_row — 数値添字の配列として行を得る
    • pg_field_is_null — フィールドが SQL の NULL かどうか調べる
    • pg_field_name — フィールドの名前を返す
    • pg_field_num — 指定されたフィールドのフィールド番号を返す
    • pg_field_prtlen — 表示される長さを返す
    • pg_field_size — 指定したフィールドの内部記憶領域におけるサイズを返す
    • pg_field_table — tables フィールドの名前あるいは oid を返す
    • pg_field_type — フィールド番号に対応する型名を返す
    • pg_field_type_oid — フィールド番号に対応する型 ID（OID）を返す
    • pg_flush — 送信を待っているクエリデータをフラッシュする
    • pg_free_result — クエリ結果のメモリを開放する
    • pg_get_notify — SQL NOTIFY メッセージを取得する
    • pg_get_pid — バックエンドのプロセス ID を得る
    • pg_get_result — 非同期クエリの結果を取得する
    • pg_host — 接続に関連するホスト名を返す
    • pg_insert — テーブルに配列を挿入する
    • pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する
    • pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す
    • pg_last_oid — 直近の行のオブジェクト ID を返す
    • pg_lo_close — ラージオブジェクトをクローズする
    • pg_lo_create — ラージオブジェクトを生成する
    • pg_lo_export — ラージオブジェクトをファイルにエクスポートする
    • pg_lo_import — ファイルからラージオブジェクトをインポートする
    • pg_lo_open — ラージオブジェクトをオープンする
    • pg_lo_read — ラージオブジェクトを読み込む
    • pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する
    • pg_lo_seek — ラージオブジェクトの位置をシークする
    • pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す
    • pg_lo_truncate — ラージオブジェクトを切り詰める
    • pg_lo_unlink — ラージオブジェクトを削除する
    • pg_lo_write — ラージオブジェクトに書き込む
    • pg_meta_data — テーブルからメタデータを取得する
    • pg_num_fields — フィールド数を返す
    • pg_num_rows — 行数を返す
    • pg_options — 接続に関連するオプションを取得する
    • pg_parameter_status — サーバーのパラメータ設定を検索する
    • pg_pconnect — 持続的な PostgreSQL 接続をオープンする
    • pg_ping — データベース接続を調べる
    • pg_port — 接続に関連するポート番号を返す
    • pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
    • pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する
    • pg_query — クエリを実行する
    • pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
    • pg_result_error — 結果に関連するエラーメッセージを取得する
    • pg_result_error_field — エラー報告の各フィールドを返す
    • pg_result_seek — 結果インスタンスの内部行オフセットを設定する
    • pg_result_status — クエリ結果のステータスを取得する
    • pg_select — レコードを選択する
    • pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
    • pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
    • pg_send_query — 非同期クエリを送信する
    • pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
    • pg_set_client_encoding — クライアントのエンコーディングを設定する
    • pg_set_error_context_visibility — pg_last_error が返すコンテクストのエラーメッセージのアクセス権を設定する
    • pg_set_error_verbosity — pg_last_error および pg_result_error が返すメッセージの詳細度を指定する
    • pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する
    • pg_trace — PostgreSQL 接続のトレースを有効にする
    • pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す
    • pg_tty — 接続に関する TTY 名を返す
    • pg_unescape_bytea — bytea 型のバイナリをアンエスケープする
    • pg_untrace — PostgreSQL 接続のトレースを無効にする
    • pg_update — テーブルを更新する
    • pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す
  • PgSql\Connection — PgSql\Connection クラス
  • PgSql\Result — The PgSql\Result class
  • PgSql\Lob — The PgSql\Lob class


はじめに

PostgreSQL データベースはオープンソースの製品であり、無料で 使用可能です。Postgres は元々 UCB（カリフォルニア大学バークレイ校） コンピュータ・サイエンス学部で開発されたものです。この Postgres は、 現在いくつかの商用データベースにおいてサポートされつつある オブジェクトリレーショナルデータベース的概念の多くの先駆けでした。 Postgres は、SQL92/SQL99 言語サポート・トランザクション・参照整合性・ ストアドプロシージャ・拡張可能な型を提供しています。PostgreSQL は、 バークレイ校での Postgres のオリジナルコードの、オープンソースの 子孫にあたります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • PostgreSQL
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

PostgreSQL サポートを使用するには、PostgreSQL 6.5 以降が必要です。 PostgreSQL 8.0 以降では PostgreSQL モジュールの全ての機能を使用可能 です。PostgreSQL は、マルチバイト文字エンコーディングを含む多くの 文字エンコーディングをサポートしています。現在のバージョン及び PostgreSQLに関するより詳細な情報は、 » http://www.postgresql.org/ と » PostgreSQL Documentation で入手可能です。


インストール手順

PostgreSQLサポートを利用可能とするには、PHPコンパイル時に --with-pgsql[=DIR] を指定することが必要です。DIR は PostgreSQL のインストールディレクトリで、デフォルトは /usr/local/pgsql です。 共有オブジェクトモジュールが利用可能な場合、php.ini の extension ディレクティブ または dl() 関数によりPostgreSQLモジュール をロードすることが可能です。


実行時設定

php.ini の設定により動作が変化します。

PostgreSQL設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pgsql.allow_persistent | "1" | INI_SYSTEM |
pgsql.max_persistent | "-1" | INI_SYSTEM |
pgsql.max_links | "-1" | INI_SYSTEM |
pgsql.auto_reset_persistent | "0" | INI_SYSTEM |
pgsql.ignore_notice | "0" | INI_ALL |
pgsql.log_notice | "0" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pgsql.allow_persistent bool

持続的な Postgres 接続を可能にするかどうか。

pgsql.max_persistent int

プロセス毎の持続的 Postgres 接続の最大数。

pgsql.max_links int

持続的接続を含むプロセス毎の Postgres 接続の最大数。

pgsql.auto_reset_persistent int

pg_pconnect() で作成した持続的接続の障害を 検出する。少々のオーバーヘッドを要します。

pgsql.ignore_notice int

PostgreSQL バックエンドの通知メッセージを無視するかどうか。

pgsql.log_notice int

PostgreSQL バックエンドの通知メッセージをログに記録するかしないか。 ログに記録するには、PHP ディレクティブ pgsql.ignore_notice を off にする必要があります。


リソース型

PHP 8.1.0 より前のバージョンでは、 PostgreSQL モジュールで使用されているリソース型が 2種類 ありました。 ひとつは、データベース接続のリンク ID で、 もうひとつはクエリの結果を保持するリソースです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PGSQL_LIBPQ_VERSION (string)
短い形式の libpq バージョン情報。数字とドットだけの形式です。
PGSQL_LIBPQ_VERSION_STR (string)
PHP 8.0.0 より前のバージョンでは、 コンパイラの情報も含む 長い形式の libpq バージョン情報を表していました。 PHP 8.0.0 以降は、 この値は PGSQL_LIBPQ_VERSION の値と等しくなりました。 よって、PGSQL_LIBPQ_VERSION_STR を使うことは推奨されなくなっています。
PGSQL_ASSOC (int)
pg_fetch_array() に渡します。 フィールド名と値の連想配列を返します。
PGSQL_NUM (int)
pg_fetch_array() に渡します。 フィールド番号と値の数値添字配列を返します。
PGSQL_BOTH (int)
pg_fetch_array() に渡します。 フィールド値の配列を、数値添字（フィールド番号で）と 連想配列（フィールド名で）の両方で返します。
PGSQL_CONNECT_FORCE_NEW (int)
pg_connect() に渡し、既存の同一接続を無視して 新しい接続を確立させるようにします。
PGSQL_CONNECT_ASYNC (int)
pg_connect() に渡し、非同期接続を確立させます。
PGSQL_CONNECTION_AUTH_OK (int)
PGSQL_CONNECTION_AWAITING_RESPONSE (int)
PGSQL_CONNECTION_BAD (int)
pg_connection_status() から返され、データベースとの 接続が不正な状態になっていることを示します。
PGSQL_CONNECTION_MADE (int)
PGSQL_CONNECTION_OK (int)
pg_connection_status() から返され、データベースとの 接続が正常であることを示します。
PGSQL_CONNECTION_SETENV (int)
PGSQL_CONNECTION_SSL_STARTUP (int)
PGSQL_CONNECTION_STARTED (int)
PGSQL_SEEK_SET (int)
pg_lo_seek() に渡します。シーク操作は オブジェクトの先頭から始められます。
PGSQL_SEEK_CUR (int)
pg_lo_seek() に渡します。シーク操作は カレントの位置から始められます。
PGSQL_SEEK_END (int)
pg_lo_seek() に渡します。シーク操作は オブジェクトの最後から始められます。
PGSQL_EMPTY_QUERY (int)
pg_result_status() から返されます。 サーバーに送信された文字列が空でした。
PGSQL_COMMAND_OK (int)
pg_result_status() から返されます。 コマンドは正常に終了し、何もデータを返しませんでした。
PGSQL_TUPLES_OK (int)
pg_result_status() から返されます。 コマンドは正常に終了し、データを返しました （SELECT や SHOW など）。
PGSQL_COPY_OUT (int)
pg_result_status() から返されます。 （サーバーからの）データのコピーが始まりました。
PGSQL_COPY_IN (int)
pg_result_status() から返されます。 （サーバーへの）データのコピーが始まりました。
PGSQL_BAD_RESPONSE (int)
pg_result_status() から返されます。 サーバーからの応答を判別できませんでした。
PGSQL_NONFATAL_ERROR (int)
pg_result_status() から返されます。 致命的ではないエラー（通知や警告など）が発生しました。
PGSQL_FATAL_ERROR (int)
pg_result_status() から返されます。 致命的なエラーが発生しました。
PGSQL_TRANSACTION_IDLE (int)
pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクション内ではありません。
PGSQL_TRANSACTION_ACTIVE (int)
pg_transaction_status() から返されます。 接続内でコマンドを実行中です。クエリが接続を通じて送信され、 まだ完了していません。
PGSQL_TRANSACTION_INTRANS (int)
pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクションブロック内にあります。
PGSQL_TRANSACTION_INERROR (int)
pg_transaction_status() から返されます。 接続は現在アイドル状態で、トランザクション処理に失敗しています。
PGSQL_TRANSACTION_UNKNOWN (int)
pg_transaction_status() から返されます。 接続が正常ではありません。
PGSQL_DIAG_SEVERITY (int)
pg_result_error_field() に渡します。 深刻度です。その内容は ERROR、 FATAL、あるいは PANIC （エラーメッセージ内）、あるいは WARNING、 NOTICE、DEBUG、 INFO、あるいは LOG （通知メッセージ内）、あるいはこれらの各国語版のうちのどれかです。 常に存在します。
PGSQL_DIAG_SQLSTATE (int)
pg_result_error_field() に渡します。 エラーの SQLSTATE コードです。SQLSTATE コードは発生したエラーの種別を 特定します。これは、データベースエラーに対してフロントエンドの アプリケーションが適切な操作（エラー処理など）をできるようにするために 使用されます。このフィールドはローカライズされていません。また、 常に存在します。
PGSQL_DIAG_MESSAGE_PRIMARY (int)
pg_result_error_field() に渡します。 人間が判読できる最初のエラーメッセージ（たいてい 1 行）です。常に存在します。
PGSQL_DIAG_MESSAGE_DETAIL (int)
pg_result_error_field() に渡します。 オプションの 2 番目のエラーメッセージで、問題に対する詳細な情報を 含みます。複数行にまたがることもあります。
PGSQL_DIAG_MESSAGE_HINT (int)
pg_result_error_field() に渡します。 オプションのメッセージで、問題に対してどのように対応すべきかを指摘 します。エラーの詳細情報と違う点は、発生した事実ではなくアドバイス （時に不適切な場合もある）をするところです。複数行にまたがることも あります。
PGSQL_DIAG_STATEMENT_POSITION (int)
pg_result_error_field() に渡します。 エラーカーソルの位置を、もとのステートメント中の位置として表す 整数値を保持する文字列です。 最初の文字の位置は 1 で、それ以降（バイト数ではなく）文字数で 位置を数えます。
PGSQL_DIAG_INTERNAL_POSITION (int)
pg_result_error_field() に渡します。 PG_DIAG_STATEMENT_POSITION と同じ定義ですが、 こちらはカーソル位置が内部で生成されたコマンドを参照している場合に 使用されます。このフィールドが存在する場合は、常に PG_DIAG_INTERNAL_QUERY フィールドも存在します。
PGSQL_DIAG_INTERNAL_QUERY (int)
pg_result_error_field() に渡します。 失敗した内部生成コマンドのテキストです。例としては、PL/pgSQL 関数で 発行された SQL クエリなどがあてはまります。
PGSQL_DIAG_CONTEXT (int)
pg_result_error_field() に渡します。 エラーが発生した状況を指定します。現在ここに含まれているのは、 アクティブなプロシージャの関数や内部生成クエリのコール履歴です。 これはエントリごとに 1 行のデータとなっており、直近のデータが 先頭にきます。
PGSQL_DIAG_SOURCE_FILE (int)
pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでのファイル名です。
PGSQL_DIAG_SOURCE_LINE (int)
pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでの行番号です。
PGSQL_DIAG_SOURCE_FUNCTION (int)
pg_result_error_field() に渡します。 エラーが報告された箇所の、PostgreSQL ソースコードでの関数名です。
PGSQL_DIAG_SCHEMA_NAME (int)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_TABLE_NAME (int)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_COLUMN_NAME (int)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_DATATYPE_NAME (int)
PHP 7.3.0 以降で利用可能です。
PGSQL_DIAG_CONSTRAINT_NAME (int)
PHP 7.3.0 以降で利用可能です。
PGSQL_ERRORS_TERSE (int)
pg_set_error_verbosity() に渡します。 返されるメッセージを指定します。ここには深刻度・短い説明および 発生位置のみを含めます。通常は 1 行に収まるでしょう。
PGSQL_ERRORS_DEFAULT (int)
pg_set_error_verbosity() に渡します。 デフォルトで返されるメッセージで、上の内容に加えて詳細・ ヒントあるいは詳細情報を含めます（複数行にまたがるかもしれません）。
PGSQL_ERRORS_VERBOSE (int)
pg_set_error_verbosity() に渡します。 詳細モードでのメッセージで、有効なフィールドをすべて含めます。
PGSQL_ERRORS_SQLSTATE (int)
pg_set_error_verbosity() に渡します。 エラーの深刻度と SQLSTATE エラーコードのみを含めます。 エラーコードが利用できない場合、出力は PGSQL_ERRORS_TERSE モードと似たものになります。 PostgreSQL 11.1 より前のバージョンでは、 PGSQL_ERRORS_TERSE モードと出力が常に同じでした。
PGSQL_NOTICE_LAST (int)
pg_last_notice() で使用されます。 PHP 7.1.0 以降で使用可能です。
PGSQL_NOTICE_ALL (int)
pg_last_notice() で使用されます。 PHP 7.1.0 以降で使用可能です。
PGSQL_NOTICE_CLEAR (int)
pg_last_notice() で使用されます。 PHP 7.1.0 以降で使用可能です。
PGSQL_STATUS_LONG (int)
pg_result_status() に渡します。 結果として数値が要求されていることを示します。
PGSQL_STATUS_STRING (int)
pg_result_status() に渡します。 結果としてテキストのコマンドタグが要求されていることを示します。
PGSQL_CONV_IGNORE_DEFAULT (int)
pg_convert() に渡します。 変換時に、テーブルのデフォルト値を無視します。
PGSQL_CONV_FORCE_NULL (int)
pg_convert() に渡します。 空文字列に対して、SQL の NULL を使用します。
PGSQL_CONV_IGNORE_NOT_NULL (int)
pg_convert() に渡します。 null を SQL の NOT NULL に変換しないように します。
PGSQL_DML_NO_CONV (int)
pg_insert() や pg_select()、 pg_update()、pg_delete() に渡します。 すべてのパラメータを、そのままの形式で渡します。ユーザーから受け取ったデータを渡す際には、手動でのエスケープが必要になります。 pg_escape_string() を使いましょう。
PGSQL_DML_EXEC (int)
pg_insert() や pg_select()、 pg_update()、pg_delete() に渡します。 これらの関数を使って、クエリを実行します。
PGSQL_DML_ASYNC (int)
pg_insert() や pg_select()、 pg_update()、pg_delete() に渡します。 これらの関数を使って、非同期クエリを実行します。
PGSQL_DML_STRING (int)
pg_insert() や pg_select()、 pg_update()、pg_delete() に渡します。 実行したクエリ文字列を返します。
PGSQL_DML_ESCAPE (int)
pg_insert() や pg_select()、
pg_update()、pg_delete() に渡します。
内部的に pg_convert() を呼ぶ代わりに、すべてのパラメータをエスケープします。
このオプションは、メタデータのルックアップを除外します。
pg_query() や pg_send_query()
と同程度の速度になります。
PGSQL_POLLING_FAILED (int)
pg_connect_poll() が返す値です。 接続の試行に失敗したことを示します。
PGSQL_POLLING_READING (int)
pg_connect_poll() が返す値です。 接続が、PostgreSQL のソケットが読み込み可能になるのを待っていることを示します。
PGSQL_POLLING_WRITING (int)
pg_connect_poll() が返す値です。 接続が、PostgreSQL のソケットが書き込み可能になるのを待っていることを示します。
PGSQL_POLLING_OK (int)
pg_connect_poll() が返す値です。 接続が、利用可能になったことを示します。
PGSQL_POLLING_ACTIVE (int)
pg_connect_poll() が返す値です。 接続が、現在アクティブであることを示します。
PGSQL_DIAG_SEVERITY_NONLOCALIZED (int)
深刻度。 このフィールドの内容は(エラーメッセージの場合)ERROR、FATAL、もしくは、PANIC、 (注意喚起メッセージの場合)WARNING、NOTICE、DEBUG、INFO、もしくは、LOGです。 これは、内容が多言語化されないことを除き、PG_DIAG_SEVERITY と同一です。 これはPostgreSQLのバージョン9.6以降で生成された報告にのみ存在します / PHP 7.3.0 以降で利用可能です。
PGSQL_SHOW_CONTEXT_NEVER (int)
pg_set_error_context_visibility() に指定するために使います。コンテクストは決して表示されません。 PHP 8.3.0 以降で利用可能です。
PGSQL_SHOW_CONTEXT_ERRORS (int)
pg_set_error_context_visibility() に指定するために使います。コンテクストのフィールドはエラーメッセージのみです。 これがデフォルトの動作です。 PHP 8.3.0 以降で利用可能です。
PGSQL_SHOW_CONTEXT_ALWAYS (int)
pg_set_error_context_visibility() に指定するために使います。コンテクストのフィールドには error, notice, warning メッセージが含まれます。 PHP 8.3.0 以降で利用可能です。
PGSQL_TRACE_SUPPRESS_TIMESTAMPS (int)
pg_trace() に指定するために使います。 トレースのメッセージにタイムスタンプを含めません。 PHP 8.3.0 以降で利用可能です。
PGSQL_TRACE_REGRESS_MODE (int)
pg_trace() に指定するために使います。 OID のようなフィールドを、トレースのメッセージに含めます。 PHP 8.3.0 以降で利用可能です。


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • PostgreSQL
  • 例

例

目次

  • 基本的な使用法
  • 基本的な使い方


基本的な使用法

この例では、PostgreSQL への接続・クエリの実行・結果の表示 そして切断の方法を説明します。

例1 PostgreSQL 拡張モジュールの概要

<?php
// 接続し、データベースを選択する
$dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
or die('Could not connect: ' . pg_last_error());

// SQL クエリを実行する
$query = 'SELECT * FROM authors';
$result = pg_query($query) or die('Query failed: ' . pg_last_error());

// 結果を HTML で表示する
echo "<table>\n";
while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
echo "\t<tr>\n";
foreach ($line as $col_value) {
echo "\t\t<td>$col_value</td>\n";
}
echo "\t</tr>\n";
}
echo "</table>\n";

// 結果セットを開放する
pg_free_result($result);

// 接続をクローズする
pg_close($dbconn);
?>


基本的な使い方

以下の例には、レガシーなMySQL関数に似た、ユーザー定義関数が含まれています。

例1 PostgreSQL のユーザー定義関数の例

<?php
// この関数は、PostgreSQL 接続がデータベースにバインドしているので必要
// This function should be needed, since PostgreSQL connection binds database.
function pg_list_dbs($db)
{
assert(is_resource($db));
$query = '
SELECT
d.datname as "Name",
u.usename as "Owner",
pg_encoding_to_char(d.encoding) as "Encoding"
FROM
pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
ORDER BY 1;
';
return pg_query($db, $query);
}

// テーブルを一覧にする
function pg_list_tables($db)
{
assert(is_resource($db));
$query = "
SELECT
c.relname as \"Name\",
CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
u.usename as \"Owner\"
FROM
pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
WHERE
c.relkind IN ('r','v','S','')
AND c.relname !~ '^pg_'
ORDER BY 1;
";
return pg_query($db, $query);
}

// pg_meta_data() も参照ください。フィールド定義を配列で返します。
function pg_list_fields($db, $table)
{
assert(is_resource($db));
$query = "
SELECT
a.attname,
format_type(a.atttypid, a.atttypmod),
a.attnotnull,
a.atthasdef,
a.attnum
FROM
pg_class c,
pg_attribute a
WHERE
c.relname = '".$table."'
AND a.attnum > 0 AND a.attrelid = c.oid
ORDER BY a.attnum;
";
return pg_query($db, $query);
}
?>


PostgreSQL 関数

注意

注意:

すべての関数がすべての構築環境でサポートされるわけではありません。 サポートされる関数は、使用する libpq（PostgreSQL の C クライアント ライブラリ）のバージョンと libpq のコンパイル方法に依存します。 もし PHP の PostgreSQL 拡張モジュールに足りない関数がある場合、 原因は libpq がその関数をサポートしていないことです。

注意:

ほとんどの PostgreSQL 関数は、オプションの第 1 引数として connection を受け付けます。もしこれを 指定しなかった場合、直近にオープンされた接続を使用します。 そのような接続が存在しなかった場合、関数は false を返します。

注意:

PostgreSQL は、オブジェクトの生成時やクエリの実行時に 識別子（例: テーブル名・カラム名）を自動的に小文字に変換します。 この自動変換を防ぐには、識別子をダブルクォート（""）でエスケープする 必要があります。

注意:

PostgreSQL には、データベースのスキーマ情報（例: データベース内の すべてのテーブルなど）を取得するための特別なコマンドがありません。 その代わりに、PostgreSQL 7.4 以降では information_schema という標準スキーマが存在し、必要な情報が検索しやすい形式で格納されています。 詳しい情報は » PostgreSQL Documentation を参照ください。

目次

  • pg_affected_rows — 変更されたレコード(タプル)の数を返す
  • pg_cancel_query — 非同期クエリを取り消す
  • pg_client_encoding — クライアントのエンコーディングを取得する
  • pg_close — PostgreSQL 接続をクローズする
  • pg_connect — PostgreSQL 接続をオープンする
  • pg_connect_poll — 進行中の非同期接続のステータスをポーリングする
  • pg_connection_busy — 接続がビジーかどうか調べる
  • pg_connection_reset — 接続をリセット(再接続)する
  • pg_connection_status — 接続ステータスを取得する
  • pg_consume_input — 接続の入力を読み取る
  • pg_convert — 連想配列の値を、SQL 文として実行可能な形式に変換する
  • pg_copy_from — 配列からテーブルに挿入する
  • pg_copy_to — 配列にテーブルをコピーする
  • pg_dbname — データベース名を取得する
  • pg_delete — レコードを削除する
  • pg_end_copy — PostgreSQL バックエンドと同期する
  • pg_escape_bytea — bytea フィールドに挿入するために文字列をエスケープする
  • pg_escape_identifier — テキスト型フィールドに挿入するために、識別子をエスケープする
  • pg_escape_literal — テキスト型フィールドに挿入するために、リテラルをエスケープする
  • pg_escape_string — クエリに使う文字列をエスケープする
  • pg_execute — 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
  • pg_fetch_all — 取得されたすべての行を配列として取得する
  • pg_fetch_all_columns — 指定したカラムの全ての行を配列として取得する
  • pg_fetch_array — 行を配列として取得する
  • pg_fetch_assoc — 行を連想配列として取得する
  • pg_fetch_object — 行をオブジェクトとして得る
  • pg_fetch_result — 結果インスタンスから値を返す
  • pg_fetch_row — 数値添字の配列として行を得る
  • pg_field_is_null — フィールドが SQL の NULL かどうか調べる
  • pg_field_name — フィールドの名前を返す
  • pg_field_num — 指定されたフィールドのフィールド番号を返す
  • pg_field_prtlen — 表示される長さを返す
  • pg_field_size — 指定したフィールドの内部記憶領域におけるサイズを返す
  • pg_field_table — tables フィールドの名前あるいは oid を返す
  • pg_field_type — フィールド番号に対応する型名を返す
  • pg_field_type_oid — フィールド番号に対応する型 ID（OID）を返す
  • pg_flush — 送信を待っているクエリデータをフラッシュする
  • pg_free_result — クエリ結果のメモリを開放する
  • pg_get_notify — SQL NOTIFY メッセージを取得する
  • pg_get_pid — バックエンドのプロセス ID を得る
  • pg_get_result — 非同期クエリの結果を取得する
  • pg_host — 接続に関連するホスト名を返す
  • pg_insert — テーブルに配列を挿入する
  • pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する
  • pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す
  • pg_last_oid — 直近の行のオブジェクト ID を返す
  • pg_lo_close — ラージオブジェクトをクローズする
  • pg_lo_create — ラージオブジェクトを生成する
  • pg_lo_export — ラージオブジェクトをファイルにエクスポートする
  • pg_lo_import — ファイルからラージオブジェクトをインポートする
  • pg_lo_open — ラージオブジェクトをオープンする
  • pg_lo_read — ラージオブジェクトを読み込む
  • pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する
  • pg_lo_seek — ラージオブジェクトの位置をシークする
  • pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す
  • pg_lo_truncate — ラージオブジェクトを切り詰める
  • pg_lo_unlink — ラージオブジェクトを削除する
  • pg_lo_write — ラージオブジェクトに書き込む
  • pg_meta_data — テーブルからメタデータを取得する
  • pg_num_fields — フィールド数を返す
  • pg_num_rows — 行数を返す
  • pg_options — 接続に関連するオプションを取得する
  • pg_parameter_status — サーバーのパラメータ設定を検索する
  • pg_pconnect — 持続的な PostgreSQL 接続をオープンする
  • pg_ping — データベース接続を調べる
  • pg_port — 接続に関連するポート番号を返す
  • pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
  • pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する
  • pg_query — クエリを実行する
  • pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
  • pg_result_error — 結果に関連するエラーメッセージを取得する
  • pg_result_error_field — エラー報告の各フィールドを返す
  • pg_result_seek — 結果インスタンスの内部行オフセットを設定する
  • pg_result_status — クエリ結果のステータスを取得する
  • pg_select — レコードを選択する
  • pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
  • pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
  • pg_send_query — 非同期クエリを送信する
  • pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
  • pg_set_client_encoding — クライアントのエンコーディングを設定する
  • pg_set_error_context_visibility — pg_last_error が返すコンテクストのエラーメッセージのアクセス権を設定する
  • pg_set_error_verbosity — pg_last_error および pg_result_error が返すメッセージの詳細度を指定する
  • pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する
  • pg_trace — PostgreSQL 接続のトレースを有効にする
  • pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す
  • pg_tty — 接続に関する TTY 名を返す
  • pg_unescape_bytea — bytea 型のバイナリをアンエスケープする
  • pg_untrace — PostgreSQL 接続のトレースを無効にする
  • pg_update — テーブルを更新する
  • pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す


変更されたレコード(タプル)の数を返す

  • ≪ PostgreSQL 関数
  • pg_cancel_query ≫
  • PHP Manual
  • PostgreSQL 関数
  • 変更されたレコード(タプル)の数を返す

pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — 変更されたレコード(タプル)の数を返す

説明

pg_affected_rows(PgSql\Result $result): int

pg_affected_rows() は、INSERT, UPDATE, DELETE クエリにより変更されたタプル(インスタンス/レコード/行)の数を 返します。

PostgreSQL 9.0 以降は、SELECT を実行したときには選択された行の数を返すようになりました。 それ以前のバージョンでは、SELECT が返す結果は 0 でした。

注意:

この関数は、以前は pg_cmdtuples() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

戻り値

クエリによって変更された行の数を返します。もし変更されたタプルがない場合は 0 を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_affected_rows() の例

<?php
$result = pg_query($conn, "INSERT INTO authors VALUES ('オーウェル', 2002, '動物農場')");

$cmdtuples = pg_affected_rows($result);

echo $cmdtuples . " タプルが変更されました。\n";
?>

上の例の出力は以下となります。

1 タプルが変更されました。

参考

  • pg_query() - クエリを実行する
  • pg_query_params() - SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
  • pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
  • pg_num_rows() - 行数を返す


非同期クエリを取り消す

  • ≪ pg_affected_rows
  • pg_client_encoding ≫
  • PHP Manual
  • PostgreSQL 関数
  • 非同期クエリを取り消す

pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — 非同期クエリを取り消す

説明

pg_cancel_query(PgSql\Connection $connection): bool

pg_cancel_query() は、
pg_send_query()・pg_send_query_params()
あるいは pg_send_execute() により送信された非同期クエリを
キャンセルします。pg_query() により実行されたクエリを
キャンセルすることはできません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_cancel_query() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
}

$res1 = pg_get_result($dbconn);
echo "First call to pg_get_result(): $res1\n";
$rows1 = pg_num_rows($res1);
echo "$res1 has $rows1 records\n\n";

// 実行中のクエリをキャンセルする。もしまだ実行中なら、2 番目のクエリが
// 対象となるだろう。
pg_cancel_query($dbconn);
?>

上の例の出力は以下となります。

First call to pg_get_result(): Resource id #3
Resource id #3 has 3 records

参考

  • pg_send_query() - 非同期クエリを送信する
  • pg_connection_busy() - 接続がビジーかどうか調べる


クライアントのエンコーディングを取得する

  • ≪ pg_cancel_query
  • pg_close ≫
  • PHP Manual
  • PostgreSQL 関数
  • クライアントのエンコーディングを取得する

pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — クライアントのエンコーディングを取得する

説明

pg_client_encoding(?PgSql\Connection $connection = null): string

PostgreSQL は、ある種の文字セットについてはサーバーとクライアントの間の 自動文字コード変換をサポートしています。 pg_client_encoding() は、クライアントの エンコーディングを文字列として返します。返される値は、標準の PostgreSQL エンコーディング識別子のなかのひとつとなります。

注意:

この関数を使用するには、PostgreSQL 7.0 以降が必要です。 libpq がマルチバイトエンコーディングのサポートを有効にせずに コンパイルされている場合、pg_client_encoding() は常に SQL_ASCII を返します。サポートされる エンコーディングは PostgreSQL のバージョンに依存します。サポートされる エンコーディングの詳細については PostgreSQL のドキュメントを参照ください。

この関数は、以前は pg_clientencoding() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

クライアントのエンコーディングを返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_client_encoding() の例

<?php
// $conn の接続先のエンコーディングは ISO-8859-1 であるとする
$encoding = pg_client_encoding($conn);

echo "Client encoding is: ", $encoding, "\n";
?>

上の例の出力は以下となります。

Client encoding is: ISO-8859-1

参考

  • pg_set_client_encoding() - クライアントのエンコーディングを設定する


PostgreSQL 接続をクローズする

  • ≪ pg_client_encoding
  • pg_connect ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続をクローズする

pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — PostgreSQL 接続をクローズする

説明

pg_close(?PgSql\Connection $connection = null): true

pg_close() は、 connection インスタンスで指定した PostgreSQL データベースへの持続的でない接続を閉じます。

注意:

持続的でない接続はスクリプトの実行終了時に自動的にクローズされるため、 pg_close() は通常は必要ありません。

接続の中でオープンされている PgSql\Lob のインスタンスが存在する場合、すべての PgSql\Lob のインスタンスを クローズするまで接続を閉じないでください。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_close() の例

<?php
$dbconn = pg_connect("host=localhost port=5432 dbname=mary")
or die("Could not connect");
echo "Connected successfully";
pg_close($dbconn);
?>

上の例の出力は以下となります。

Connected successfully

参考

  • pg_connect() - PostgreSQL 接続をオープンする


PostgreSQL 接続をオープンする

  • ≪ pg_close
  • pg_connect_poll ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続をオープンする

pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — PostgreSQL 接続をオープンする

説明

pg_connect(string $connection_string, int $flags = 0): PgSql\Connection|false

pg_connect() は、connection_string で指定された情報を用いてデータベースとの接続をオープンします。

同じ connection_string 引数で 2 回 pg_connect() 関数がコールされた場合は、 flags に PGSQL_CONNECT_FORCE_NEW を指定していない限り 既存の接続が返されます。

複数のパラメータをサポートする古い構文 $conn = pg_connect("host", "port", "options", "tty", "dbname") は推奨されません。

パラメータ

connection_string

すべてデフォルトのパラメータを使用する場合には connection_string を空にすることが可能です。 または 1 つ以上のパラメータを空白で区切って指定することも可能です。 個々のパラメータは keyword = value の形式で 設定します。等号の前後の空白はあってもなくてもかまいません。 空の値や空白を含む値を指定する場合は、その値をシングルクォートで 囲みます（例: keyword = 'a value'）。値の中に シングルクォートやバックスラッシュが含まれる場合は、それらを バックスラッシュでエスケープする必要があります（例: \' および \\）。

現在利用できるパラメータは以下のとおりです。 host, hostaddr, port, dbname (デフォルトは user の値), user, password, connect_timeout, options, tty（無視されます）, sslmode, requiressl（非推奨。代わりに sslmode を推奨します） および service 。これらのうち実際にどの パラメータが使えるかは、PostgreSQL のバージョンに依存します。

options パラメータを使うと、 サーバー側で実行されるコマンドラインパラメータを指定することができます。

flags

PGSQL_CONNECT_FORCE_NEW が渡された場合は、 たとえ connection_string が既存の接続と まったく同一であっても新しい接続をオープンします。

PGSQL_CONNECT_ASYNC を指定すると、 非同期接続を確立します。この接続の状態は、 pg_connect_poll() あるいは pg_connection_status() で確認できます。

戻り値

成功した場合に PgSql\Connection クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PgSql\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。

例

例1 pg_connect() の使用法

<?php
$dbconn = pg_connect("dbname=mary");
// "mary"という名前のデータベースに接続

$dbconn2 = pg_connect("host=localhost port=5432 dbname=mary");
// "localhost"のポート"5432"にて"mary"という名前のデータベースに接続

$dbconn3 = pg_connect("host=sheep port=5432 dbname=mary user=lamb password=foo");
// ユーザー名とパスワードを指定してホスト"sheep"上の"mary"という名前のデータベースに接続

$conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
$dbconn4 = pg_connect($conn_string);
// ユーザー名とパスワードを指定してホスト"sheep"上の"test"という名前のデータベースへ接続

$dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");
// "localhost" のデータベースに接続する際に、エンコーディングを UTF-8 に指定
?>

参考

  • pg_pconnect() - 持続的な PostgreSQL 接続をオープンする
  • pg_close() - PostgreSQL 接続をクローズする
  • pg_host() - 接続に関連するホスト名を返す
  • pg_port() - 接続に関連するポート番号を返す
  • pg_tty() - 接続に関する TTY 名を返す
  • pg_options() - 接続に関連するオプションを取得する
  • pg_dbname() - データベース名を取得する


進行中の非同期接続のステータスをポーリングする

  • ≪ pg_connect
  • pg_connection_busy ≫
  • PHP Manual
  • PostgreSQL 関数
  • 進行中の非同期接続のステータスをポーリングする

pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — 進行中の非同期接続のステータスをポーリングする

説明

pg_connect_poll(PgSql\Connection $connection): int

pg_connect_poll() は、 PGSQL_CONNECT_ASYNC オプションを使用して コールされた pg_connect() で作成された PostgreSQL 接続のステータスをポーリングします。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

PGSQL_POLLING_FAILED、 PGSQL_POLLING_READING、 PGSQL_POLLING_WRITING、 PGSQL_POLLING_OK、 または PGSQL_POLLING_ACTIVE を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


接続がビジーかどうか調べる

  • ≪ pg_connect_poll
  • pg_connection_reset ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続がビジーかどうか調べる

pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — 接続がビジーかどうか調べる

説明

pg_connection_busy(PgSql\Connection $connection): bool

pg_connection_busy() は、接続がビジーかどうかを調べます。 接続がビジーである場合、以前のクエリがまだ実行中です。 もしこの接続に pg_get_result() がコールされた場合、 それはブロックされます。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

接続がビジーの場合に true 、そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_connection_busy() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
$bs = pg_connection_busy($dbconn);
if ($bs) {
echo 'connection is busy';
} else {
echo 'connection is not busy';
}
?>

参考

  • pg_connection_status() - 接続ステータスを取得する
  • pg_get_result() - 非同期クエリの結果を取得する


接続をリセット(再接続)する

  • ≪ pg_connection_busy
  • pg_connection_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続をリセット(再接続)する

pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — 接続をリセット(再接続)する

説明

pg_connection_reset(PgSql\Connection $connection): bool

pg_connection_reset() は接続をリセットします。 エラーからの復旧の際に有用です。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_connection_reset() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
$dbconn2 = pg_connection_reset($dbconn);
if ($dbconn2) {
echo "reset successful\n";
} else {
echo "reset failed\n";
}
?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする
  • pg_pconnect() - 持続的な PostgreSQL 接続をオープンする
  • pg_connection_status() - 接続ステータスを取得する


接続ステータスを取得する

  • ≪ pg_connection_reset
  • pg_consume_input ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続ステータスを取得する

pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — 接続ステータスを取得する

説明

pg_connection_status(PgSql\Connection $connection): int

pg_connection_status() は、 connection で指定した接続のステータスを返します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

PGSQL_CONNECTION_OK あるいは PGSQL_CONNECTION_BAD 。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_connection_status() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
$stat = pg_connection_status($dbconn);
if ($stat === PGSQL_CONNECTION_OK) {
echo 'Connection status ok';
} else {
echo 'Connection status bad';
}
?>

参考

  • pg_connection_busy() - 接続がビジーかどうか調べる


接続の入力を読み取る

  • ≪ pg_connection_status
  • pg_convert ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続の入力を読み取る

pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — 接続の入力を読み取る

説明

pg_consume_input(PgSql\Connection $connection): bool

pg_consume_input() は、データベースサーバーからの 読み取りを待っているすべての入力を消費します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

エラーが発生しなかった場合 true、 エラーがあった場合 false。 true が返されたからといって、入力が読み取り待機中であるとは限らないことに注意してください。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


連想配列の値を、SQL 文として実行可能な形式に変換する

  • ≪ pg_consume_input
  • pg_copy_from ≫
  • PHP Manual
  • PostgreSQL 関数
  • 連想配列の値を、SQL 文として実行可能な形式に変換する

pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — 連想配列の値を、SQL 文として実行可能な形式に変換する

説明

pg_convert(
PgSql\Connection $connection,
string $table_name,
array $values,
int $flags = 0
): array|false

pg_convert() は、values の中の値をチェックし、SQL 文の中で使用可能な形式に変換します。 少なくとも values の要素数以上のカラムを持つ テーブル table_name が存在することが前提条件と なります。values の要素名が table_name のフィールド名と一致し、また 要素に対応する値はフィールドのデータ型と互換性がなければなりません。 成功した場合に変換後の値の配列、それ以外の場合に false を返します。

注意:

この関数は、boolean 値も受付けることができ、 PostgreSQL の boolean 型に変換します。 boolean 値の文字列表現にも対応しています。 null は、PostgreSQL の NULL に変換します。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

変換対象となるテーブルの名前。

values

変換されるデータ。

flags

PGSQL_CONV_IGNORE_DEFAULT, PGSQL_CONV_FORCE_NULL あるいは PGSQL_CONV_IGNORE_NOT_NULL の組み合わせ。

戻り値

変換された値の配列を返します。 失敗した場合に false を返します

エラー / 例外

フィールドの値や型が PostgreSQL の型と一致しない場合、 ValueError または TypeError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | フィールドの値や型が PostgreSQL の型と一致しない場合、 ValueError または TypeError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_convert() の例

<?php
$dbconn = pg_connect('dbname=foo');

$tmp = array(
'author' => 'Joe Thackery',
'year' => 2005,
'title' => 'My Life, by Joe Thackery'
);

$vals = pg_convert($dbconn, 'authors', $tmp);
?>

参考

  • pg_meta_data() - テーブルからメタデータを取得する
  • pg_insert() - テーブルに配列を挿入する
  • pg_select() - レコードを選択する
  • pg_update() - テーブルを更新する
  • pg_delete() - レコードを削除する


配列からテーブルに挿入する

  • ≪ pg_convert
  • pg_copy_to ≫
  • PHP Manual
  • PostgreSQL 関数
  • 配列からテーブルに挿入する

pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — 配列からテーブルに挿入する

説明

pg_copy_from(
PgSql\Connection $connection,
string $table_name,
array $rows,
string $separator = "\t",
string $null_as = "\\\\N"
): bool

pg_copy_from() は、rows の内容をテーブルに挿入します。レコードを挿入するために、内部では COPY FROM SQL コマンドを発行します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

rows をコピーするテーブルの名前。

rows

table_name にコピーするデータの配列。 rows の個々の値が table_name のひとつの行となります。rows の個々の値は、 それぞれのフィールドに対応する値が区切り文字で区切られており、最後は 改行で終了していなければなりません。

separator

rows の要素内で、各フィールドに対応する値を 区切る文字。デフォルトは \t です。

null_as

rows の中で、SQL の NULL をどのように表現するか。デフォルトは \\N ("\\\\N") です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_copy_from() の例

<?php
$db = pg_connect("dbname=publisher") or die("Could not connect");

$rows = pg_copy_to($db, $table_name);

pg_query($db, "DELETE FROM $table_name");

pg_copy_from($db, $table_name, $rows);
?>

参考

  • pg_copy_to() - 配列にテーブルをコピーする


配列にテーブルをコピーする

  • ≪ pg_copy_from
  • pg_dbname ≫
  • PHP Manual
  • PostgreSQL 関数
  • 配列にテーブルをコピーする

pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — 配列にテーブルをコピーする

説明

pg_copy_to(
PgSql\Connection $connection,
string $table_name,
string $separator = "\t",
string $null_as = "\\\\N"
): array|false

pg_copy_to() は、テーブルを配列にコピーします。 レコードを取得するために、内部では COPY TO SQL コマンドを発行します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

データを rows にコピーするテーブルの名前。

separator

rows の要素内で、各フィールドに対応する値を 区切る文字。デフォルトは \t です。

null_as

rows の中で、SQL の NULL をどのように表現するか。デフォルトは \\N ("\\\\N") です。

戻り値

COPY されたデータが 1 行ごとにひとつの要素と なっている配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_copy_to() の例

<?php
$db = pg_connect("dbname=publisher") or die("Could not connect");

$rows = pg_copy_to($db, $table_name);

pg_query($db, "DELETE FROM $table_name");

pg_copy_from($db, $table_name, $rows);
?>

参考

  • pg_copy_from() - 配列からテーブルに挿入する


データベース名を取得する

  • ≪ pg_copy_to
  • pg_delete ≫
  • PHP Manual
  • PostgreSQL 関数
  • データベース名を取得する

pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — データベース名を取得する

説明

pg_dbname(?PgSql\Connection $connection = null): string

pg_dbname() は、 PostgreSQL の connection インスタンスで指定した データベースの名前を返します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

connection が指すデータベースの名前を表す 文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_dbname() の例

<?php
error_reporting(E_ALL);

pg_connect("host=localhost port=5432 dbname=mary");
echo pg_dbname(); // mary
?>


レコードを削除する

  • ≪ pg_dbname
  • pg_end_copy ≫
  • PHP Manual
  • PostgreSQL 関数
  • レコードを削除する

pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — レコードを削除する

説明

pg_delete(
PgSql\Connection $connection,
string $table_name,
array $conditions,
int $flags = PGSQL_DML_EXEC
): string|bool

pg_delete() は、conditions で指定したキーと値を用いてテーブルからレコードを削除します。

flags が指定された場合、指定したオプションを つけて pg_convert() が conditions に適用されます。

デフォルトでは、 pg_delete() は生の値を渡します。 値はエスケープするか、 PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、 エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

行を削除するテーブルの名前。

conditions

そのキーが table_name テーブルのフィールド名、 値が削除したいフィールドの値となっている配列。

flags

PGSQL_CONV_FORCE_NULL、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING を組み合わせた数。 flags に PGSQL_DML_STRING が含まれている場合、クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

戻り値

成功した場合に true を、失敗した場合に false を返します。 flags で PGSQL_DML_STRING が渡された場合は文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_delete() の例

<?php
$db = pg_connect('dbname=foo');
// これは少しだけ安全です。なぜなら、全ての値がエスケープされるからです。
// しかし、PostgreSQL は JSON/Array をサポートしています。これらの型に
// ついてはエスケープされたクエリや、プリペアドクエリでも安全ではありません。
$res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
if ($res) {
echo "POST data is deleted: $res\n";
} else {
echo "User must have sent wrong inputs\n";
}
?>

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する


PostgreSQL バックエンドと同期する

  • ≪ pg_delete
  • pg_escape_bytea ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL バックエンドと同期する

pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — PostgreSQL バックエンドと同期する

説明

pg_end_copy(?PgSql\Connection $connection = null): bool

pg_end_copy() は、pg_put_line() によるコピー操作の後で PostgreSQL フロントエンド（通常は Web サーバー プロセス）と PostgreSQL サーバーを同期させます。 pg_end_copy() を実行しなければ、PostgreSQL サーバーが フロントエンドとの同期を失ってしまい、エラーが発生します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_end_copy() の例

<?php
$conn = pg_pconnect("dbname=foo");
pg_query($conn, "create table bar (a int4, b char(16), d float8)");
pg_query($conn, "copy bar from stdin");
pg_put_line($conn, "3\thello world\t4.5\n");
pg_put_line($conn, "4\tgoodbye world\t7.11\n");
pg_put_line($conn, "\\.\n");
pg_end_copy($conn);
?>

参考

  • pg_put_line() - NULL で終わる文字列を PostgreSQL バックエンドに送信する


bytea フィールドに挿入するために文字列をエスケープする

  • ≪ pg_end_copy
  • pg_escape_identifier ≫
  • PHP Manual
  • PostgreSQL 関数
  • bytea フィールドに挿入するために文字列をエスケープする

pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — bytea フィールドに挿入するために文字列をエスケープする

説明

pg_escape_bytea(PgSql\Connection $connection = ?, string $data): string

pg_escape_bytea() は、bytea 型のために文字列を エスケープし、エスケープした文字列を返します。

注意:

bytea 型を SELECT した場合、PostgreSQL は '\' で 始まる 8 進数のバイト値（例: \032）を返します。これをユーザーが手動で コンバートすることを期待されています。

この関数は PostgreSQL 7.2 以降のバージョンが必要です。PostgreSQL 7.2.0 および 7.2.1 では、マルチバイトのサポートを有効にした場合は bytea の値をキャストする必要があります。例: INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 以降ではキャストする必要はありません。 クライアントとバックエンドの文字エンコーディングが一致しない場合は 例外で、この場合はマルチバイトストリームエラーが発生します。この エラーを避けるためには bytea 型へのキャストが必要になります。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

data

bytea 型のカラムに挿入するテキストまたはバイナリデータを含む 文字列。

戻り値

エスケープされたデータを文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_escape_bytea() の例

<?php
// データベースに接続する
$dbconn = pg_connect('dbname=foo');

// バイナリファイルを読み込む
$data = file_get_contents('image1.jpg');

// バイナリデータをエスケープする
$escaped = pg_escape_bytea($data);

// それをデータベースに挿入する
pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
?>

参考

  • pg_unescape_bytea() - bytea 型のバイナリをアンエスケープする
  • pg_escape_string() - クエリに使う文字列をエスケープする


テキスト型フィールドに挿入するために、識別子をエスケープする

  • ≪ pg_escape_bytea
  • pg_escape_literal ≫
  • PHP Manual
  • PostgreSQL 関数
  • テキスト型フィールドに挿入するために、識別子をエスケープする

pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — テキスト型フィールドに挿入するために、識別子をエスケープする

説明

pg_escape_identifier(PgSql\Connection $connection = ?, string $data): string

pg_escape_identifier() は、データベースへの問い合わせに使う識別子 (テーブル名やフィールド名など) をエスケープします。 PostgreSQL サーバー用にエスケープされた識別子を返します。 pg_escape_identifier() は、データの前後にダブルクォートを追加します。 ユーザーが自分で追加してはいけません。 この関数は、クエリ内で使う識別子のパラメータに有用です。SQL リテラル (bytea 以外のパラメータ) には、pg_escape_literal() あるいは pg_escape_string() を使わなければなりません。 bytea 型のフィールドには、pg_escape_bytea() を使わなければなりません。

注意:

この関数は内部的なエスケープコードを使い、PostgreSQL 8.4 より前のバージョンでも使えます。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

data

エスケープするテキスト文字列。

戻り値

エスケープされたデータを文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_escape_identifier() の例

<?php
// データベースに接続します
$dbconn = pg_connect('dbname=foo');

// テーブル名をエスケープします
$escaped = pg_escape_identifier($table_name);

// $table_name から行を取得します
pg_query("SELECT * FROM {$escaped};");
?>

参考

  • pg_escape_literal() - テキスト型フィールドに挿入するために、リテラルをエスケープする
  • pg_escape_bytea() - bytea フィールドに挿入するために文字列をエスケープする
  • pg_escape_string() - クエリに使う文字列をエスケープする


テキスト型フィールドに挿入するために、リテラルをエスケープする

  • ≪ pg_escape_identifier
  • pg_escape_string ≫
  • PHP Manual
  • PostgreSQL 関数
  • テキスト型フィールドに挿入するために、リテラルをエスケープする

pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — テキスト型フィールドに挿入するために、リテラルをエスケープする

説明

pg_escape_literal(PgSql\Connection $connection = ?, string $data): string

pg_escape_literal() は、 PostgreSQL データベースへの問い合わせに使うリテラルをエスケープします。 PostgreSQL フォーマットでエスケープされたリテラルを返します。 pg_escape_literal() は、データの前後にクォートを追加します。 ユーザーが自分で追加してはいけません。 pg_escape_string() ではなくこの関数を使うことを推奨します。 カラム型が bytea の場合は、代わりに pg_escape_bytea() を使わなければなりません。 識別子 (テーブル名やフィールド名など) のエスケープには pg_escape_identifier() を使わなければなりません。

注意:

この関数は内部的なエスケープコードを使い、PostgreSQL 8.4 より前のバージョンでも使えます。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

data

エスケープするテキスト文字列。

戻り値

エスケープされたデータを文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_escape_literal() の例

<?php
// データベースに接続します
$dbconn = pg_connect('dbname=foo');

// (アポストロフィやバックスラッシュが含まれている) テキストファイルを読み込みます
$data = file_get_contents('letter.txt');

// テキストデータをエスケープします
$escaped = pg_escape_literal($data);

// それをデータベースに挿入します。{$escaped} の前後にクォートがないことに注目
pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
?>

参考

  • pg_escape_identifier() - テキスト型フィールドに挿入するために、識別子をエスケープする
  • pg_escape_bytea() - bytea フィールドに挿入するために文字列をエスケープする
  • pg_escape_string() - クエリに使う文字列をエスケープする


クエリに使う文字列をエスケープする

  • ≪ pg_escape_literal
  • pg_execute ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリに使う文字列をエスケープする

pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — クエリに使う文字列をエスケープする

説明

pg_escape_string(PgSql\Connection $connection = ?, string $data): string

pg_escape_string() は、データベースへの問い合わせに使う文字列をエスケープします。 PostgreSQL フォーマットにエスケープされた文字列を、クォートなしの形式で返します。 PostgreSQL に使う SQL パラメータをエスケープするときには pg_escape_literal() を使うほうがよいでしょう。 addslashes() を PostgreSQL で使ってはいけません。 カラム型が bytea の場合は、代わりに pg_escape_bytea() を使わなければなりません。 識別子 (テーブル名やフィールド名など) のエスケープには pg_escape_identifier() を使わなければなりません。

注意:

この関数は、PostgreSQL 7.2 以降が必要です。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

data

エスケープするテキスト文字列。

戻り値

エスケープされたデータを文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_escape_string() の例

<?php
// データベースに接続する
$dbconn = pg_connect('dbname=foo');

// テキストファイルを読み込む（アポストロフィやスラッシュが含まれている）
$data = file_get_contents('letter.txt');

// テキストデータをエスケープする
$escaped = pg_escape_string($data);

// それをデータベースに挿入する
pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', '{$escaped}')");
?>

参考

  • pg_escape_bytea() - bytea フィールドに挿入するために文字列をエスケープする


指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

  • ≪ pg_escape_string
  • pg_fetch_all ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

説明

pg_execute(PgSql\Connection $connection = ?, string $stmtname, array $params): PgSql\Result|false

指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待ちます。

pg_execute() は pg_query_params() と似ています。しかし、実行するコマンドはクエリを指定することで 決まるのではなく、事前に準備されたステートメントに値を指定する ことによって決まります。この機能のおかげで、繰り返し使用される コマンドに構文解析や実行計画作成が最初の一度だけで済みます。 実行するステートメントは、カレントのセッションで事前に準備しておく 必要があります。pg_execute() は、PostgreSQL 7.4 以降のバージョンの接続にのみ対応しています。それ以前のバージョンでは 失敗します。

パラメータは pg_query_params() と同じですが、 クエリ文字列のかわりにプリペアドステートメントの名前を指定する という点だけが違います。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

stmtname

実行するプリペアドステートメントの名前。"" が指定された場合は 無名ステートメントが実行されます。名前は、事前に pg_prepare()・pg_send_prepare() あるいは PREPARE SQL コマンドで準備されたものである 必要があります。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

警告

この関数をコールする際に、要素の内容は文字列に変換されます。

戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_execute() の使用法

<?php
// "mary"という名前のデータベースに接続
$dbconn = pg_connect("dbname=mary");

// 実行するクエリを準備
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

// プリペアドクエリの実行。文字列 "Joe's Widgets" のエスケープ処理は
// 一切必要ないことに注意
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

// 同じプリペアドクエリを違うパラメータで実行
$result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

?>

参考

  • pg_prepare() - 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
  • pg_send_prepare() - 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
  • pg_query_params() - SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ


取得されたすべての行を配列として取得する

  • ≪ pg_execute
  • pg_fetch_all_columns ≫
  • PHP Manual
  • PostgreSQL 関数
  • 取得されたすべての行を配列として取得する

pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — 取得されたすべての行を配列として取得する

説明

pg_fetch_all(PgSql\Result $result, int $mode = PGSQL_ASSOC): array

pg_fetch_all()は、 PgSql\Result インスタンスのすべての行 （レコード）を保持する配列を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

mode

返される配列のインデックスを制御するオプションの引数です。 mode は定数で、以下の値を取ることができます。: PGSQL_ASSOC, PGSQL_NUM, PGSQL_BOTH。 PGSQL_NUM を使うと、配列のインデックスを数値にした配列を返します。PGSQL_ASSOC を使うと、連想配列のインデックスを返します。PGSQL_BOTH を指定すると、数値と連想配列のインデックスを両方含めた形で配列を返します。

戻り値

結果のすべての行を含む配列を返します。それぞれの行は、フィールド名を 添字とするフィールド値の配列です。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | pg_fetch_all() は 結果セットが0行の場合、false ではなく、 空の配列を返すようになりました。
7.1.0 | mode パラメータが追加されました。

例

例1 PostgreSQL fetch all

<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

$result = pg_query($conn, "SELECT * FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

$arr = pg_fetch_all($result);

print_r($arr);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [id] => 1
            [name] => Fred
        )

    [1] => Array
        (
            [id] => 2
            [name] => Bob
        )

)

参考

  • pg_fetch_row() - 数値添字の配列として行を得る
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_fetch_result() - 結果インスタンスから値を返す


指定したカラムの全ての行を配列として取得する

  • ≪ pg_fetch_all
  • pg_fetch_array ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したカラムの全ての行を配列として取得する

pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — 指定したカラムの全ての行を配列として取得する

説明

pg_fetch_all_columns(PgSql\Result $result, int $field = 0): array

pg_fetch_all_columns() は、 PgSql\Result クラスのインスタンスで 指定したカラムについて、 全ての行（レコード）を含む配列を返します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

カラムの番号。 指定しない場合のデフォルトは最初のカラムです。

戻り値

結果カラムの全ての値を配列で返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_fetch_all_columns() の例

<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

$result = pg_query($conn, "SELECT title, name, address FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

// 全ての著者名を配列で得る
$arr = pg_fetch_all_columns($result, 1);

var_dump($arr);

?>

参考

  • pg_fetch_all() - 取得されたすべての行を配列として取得する


行を配列として取得する

  • ≪ pg_fetch_all_columns
  • pg_fetch_assoc ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行を配列として取得する

pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — 行を配列として取得する

説明

pg_fetch_array(PgSql\Result $result, ?int $row = null, int $mode = PGSQL_BOTH): array|false

pg_fetch_array() は、取得した行（レコード）を 配列で返します。

pg_fetch_array() は拡張版の pg_fetch_row() です。結果配列のフィールド番号に 対応する要素にデータを格納し、それに加えてフィールド名をキーとした 連想配列にも格納します。デフォルトで、両方ともが有効になっています。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

pg_fetch_array() は、 pg_fetch_row() に比べてきわめて遅いというわけでは 「ありません」。そして、きわめて簡単に使用できます。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

mode

返される配列のインデックスを制御するオプションの引数です。 mode は定数で、以下の値を取ることができます。: PGSQL_ASSOC, PGSQL_NUM, PGSQL_BOTH。 PGSQL_NUM を使うと、配列のインデックスを数値にした配列を返します。PGSQL_ASSOC を使うと、連想配列のインデックスを返します。PGSQL_BOTH を指定すると、数値と連想配列のインデックスを両方含めた形で配列を返します。

戻り値

0 から始まる数値添字の配列か連想配列（フィールド名をキーとする）、 あるいはその両方を返します。配列の各要素の値は文字列です。 データベースの NULL 値は、null として返します。

row が結果の行数より大きい場合や、行が存在しない場合、 そしてそれ以外のエラーが発生した場合は false を返します。 SELECT 以外のクエリから結果を取得しようとした場合も、false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_fetch_array() の例

<?php

$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

$arr = pg_fetch_array($result, 0, PGSQL_NUM);
echo $arr[0] . " <- Row 1 Author\n";
echo $arr[1] . " <- Row 1 E-mail\n";

// row パラメータはオプションです。result_type を指定
// したい場合は NULL を渡しておきます。pg_fetch_array を続けてコール
// すると、次の行を取得します。
$arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
echo $arr["author"] . " <- Row 2 Author\n";
echo $arr["email"] . " <- Row 2 E-mail\n";

$arr = pg_fetch_array($result);
echo $arr["author"] . " <- Row 3 Author\n";
echo $arr[1] . " <- Row 3 E-mail\n";

?>

参考

  • pg_fetch_row() - 数値添字の配列として行を得る
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_fetch_result() - 結果インスタンスから値を返す


行を連想配列として取得する

  • ≪ pg_fetch_array
  • pg_fetch_object ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行を連想配列として取得する

pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — 行を連想配列として取得する

説明

pg_fetch_assoc(PgSql\Result $result, ?int $row = null): array|false

pg_fetch_assoc() は、取得した行（レコード）を 保持する連想配列を返します。

pg_fetch_assoc() は、オプションの第 3 パラメータに PGSQL_ASSOC を指定して pg_fetch_array() をコールするのと同じです。連想配列のみを返します。もし数値添字の配列が 必要な場合は pg_fetch_row() を使用してください。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

pg_fetch_assoc() は、 pg_fetch_row() に比べてきわめて遅いというわけでは 「ありません」。そして、きわめて簡単に使用できます。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

戻り値

連想配列（フィールド名をキーとする）を返します。 配列の各要素の値は文字列です。 データベースの NULL 値は、null として返します。

row が結果の行数より大きい場合、行が存在しない場合、 そしてそれ以外のエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_fetch_assoc() の例

<?php
$conn = pg_connect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

$result = pg_query($conn, "SELECT id, author, email FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

while ($row = pg_fetch_assoc($result)) {
echo $row['id'];
echo $row['author'];
echo $row['email'];
}
?>

参考

  • pg_fetch_row() - 数値添字の配列として行を得る
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_fetch_result() - 結果インスタンスから値を返す


行をオブジェクトとして得る

  • ≪ pg_fetch_assoc
  • pg_fetch_result ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行をオブジェクトとして得る

pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — 行をオブジェクトとして得る

説明

pg_fetch_object(
PgSql\Result $result,
?int $row = null,
string $class = "stdClass",
array $constructor_args = []
): object|false

pg_fetch_object() は、取得した行のフィールド名に 対応するプロパティを有するオブジェクトを返します。オプションとして、 指定したクラスのコンストラクタにパラメータを渡してインスタンス化する ことも可能です。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

速度面では、この関数は pg_fetch_array() と同じであり、 pg_fetch_row() とほとんど同じ程度です （違いはわずかです）。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

class

インスタンス化し、プロパティを設定して戻り値とするクラスの名前。 指定しない場合は stdClass オブジェクトが返されます。

constructor_args

class オブジェクトのコンストラクタに 渡すオプションの配列。

戻り値

結果の各フィールドに対応する属性を持つ object を返します。 データベースの NULL 値は null として返します。

row が結果の行数より大きい場合・行が存在しない場合 、そしてそれ以外のエラーが発生した場合は false を返します。

エラー / 例外

constructor_args が空ではないのに、 クラスにコンストラクタが存在しない場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | constructor_args が空ではないのに、 クラスにコンストラクタが存在しない場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、Exception がスローされていました。
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_fetch_object() の例

<?php

$database = "store";

$db_conn = pg_connect("host=localhost port=5432 dbname=$database");
if (!$db_conn) {
echo "Failed connecting to postgres database $database\n";
exit;
}

$qu = pg_query($db_conn, "SELECT * FROM books ORDER BY author");

while ($data = pg_fetch_object($qu)) {
echo $data->author . " (";
echo $data->year . "): ";
echo $data->title . "<br />";
}

pg_free_result($qu);
pg_close($db_conn);

?>

参考

  • pg_query() - クエリを実行する
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_assoc() - 行を連想配列として取得する
  • pg_fetch_row() - 数値添字の配列として行を得る
  • pg_fetch_result() - 結果インスタンスから値を返す


結果インスタンスから値を返す

  • ≪ pg_fetch_object
  • pg_fetch_row ≫
  • PHP Manual
  • PostgreSQL 関数
  • 結果インスタンスから値を返す

pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — 結果インスタンスから値を返す

説明

pg_fetch_result(PgSql\Result $result, string|false|null $row, mixed $field): string|false|null
pg_fetch_result(PgSql\Result $result, mixed $field): string|false|null

pg_fetch_result() は、 PgSql\Result クラスのインスタンスから 特定の行とフィールド（カラム）の値を返します。

注意:

この関数は、以前は pg_result() という名前でした。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

結果から取得する行の番号。行番号は 0 から始まります。指定しなかった 場合は、次の行が読み込まれます。

field

取得するフィールド（カラム）の名前を表す文字列、あるいは取得する フィールドの番号。フィールド番号は 0 から始まります。

戻り値

論理型の値は "t" あるいは "f" の形式で返します。 配列を含むそれ以外の型は、PostgreSQL のやりかたにしたがって文字列として フォーマットされた形式で返します。これは psql プログラムの出力と同じ形式です。データベースの NULL 値は、null として返します。

row が結果の行数より大きい場合、 あるいはそれ以外のエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.3.0 | row は、nullable になりました。
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_fetch_result() の例

<?php
$db = pg_connect("dbname=users user=me") || die();

$res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

$val = pg_fetch_result($res, 1, 0);

echo "First field in the second row is: ", $val, "\n";
?>

上の例の出力は以下となります。

First field in the second row is: 2

参考

  • pg_query() - クエリを実行する
  • pg_fetch_array() - 行を配列として取得する


数値添字の配列として行を得る

  • ≪ pg_fetch_result
  • pg_field_is_null ≫
  • PHP Manual
  • PostgreSQL 関数
  • 数値添字の配列として行を得る

pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — 数値添字の配列として行を得る

説明

pg_fetch_row(PgSql\Result $result, ?int $row = null, int $mode = PGSQL_NUM): array|false

pg_fetch_row() は、 指定した result インスタンスが指す結果から 1 行分のデータを取得します。

注意: この関数は、 NULL フィールドに PHPの null 値を設定します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

取得する行番号。最初の行は 0 です。省略したり null を指定したりした場合は、 次の行を取得します。

mode

返される配列のインデックスを制御するオプションの引数です。 mode は定数で、以下の値を取ることができます。: PGSQL_ASSOC, PGSQL_NUM, PGSQL_BOTH。 PGSQL_NUM を使うと、配列のインデックスを数値にした配列を返します。PGSQL_ASSOC を使うと、連想配列のインデックスを返します。PGSQL_BOTH を指定すると、数値と連想配列のインデックスを両方含めた形で配列を返します。

戻り値

個々の値を文字列として格納した配列を返します。配列の添字は 0 から 始まります。データベースの NULL 値は null として返します。

row が結果の行数より大きい場合・行が存在しない場合 、そしてそれ以外のエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_fetch_row() の例

<?php

$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

while ($row = pg_fetch_row($result)) {
echo "Author: $row[0] E-mail: $row[1]";
echo "<br />\n";
}

?>

参考

  • pg_query() - クエリを実行する
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_fetch_result() - 結果インスタンスから値を返す


フィールドが SQL の NULL かどうか調べる

  • ≪ pg_fetch_row
  • pg_field_name ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールドが SQL の NULL かどうか調べる

pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — フィールドが SQL の NULL かどうか調べる

説明

pg_field_is_null(PgSql\Result $result, string|false|null $row, mixed $field): int
pg_field_is_null(PgSql\Result $result, mixed $field): int

pg_field_is_null() は、 PgSql\Result クラスのインスタンスの フィールドが SQL の NULL であるかどうかを調べます。

注意:

この関数は、以前は pg_fieldisnull() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

取得する結果の行番号。行番号は 0 から始まります。指定しなかった場合は カレントの行を取得します。

field

（0 から始まる）フィールド番号を表す数値、 あるいはフィールド名を表す文字列。

戻り値

指定した行のフィールドが SQL の NULL だった場合に 1、そうでない場合に 0 を返します。 もし範囲外の行を指定したりその他のエラーが発生したりした場合には false を返します。

変更履歴

バージョン | 説明
8.3.0 | row は、nullable になりました。
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_field_is_null() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die ("Could not connect");
$res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
if ($res) {
if (pg_field_is_null($res, 0, "year") == 1) {
echo "The value of the field year is null.\n";
}
if (pg_field_is_null($res, 0, "year") == 0) {
echo "The value of the field year is not null.\n";
}
}
?>


フィールドの名前を返す

  • ≪ pg_field_is_null
  • pg_field_num ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールドの名前を返す

pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — フィールドの名前を返す

説明

pg_field_name(PgSql\Result $result, int $field): string

pg_field_name() は、 指定した result インスタンスの指定した field にあるフィールドの名前を 返します。フィールド番号は 0 から始まります。

注意:

この関数は、以前は pg_fieldname() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

フィールド番号。0 から始まります。

戻り値

フィールド名を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールド情報を取得する

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

$res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
$i = pg_num_fields($res);
for ($j = 0; $j < $i; $j++) {
echo "column $j\n";
$fieldname = pg_field_name($res, $j);
echo "fieldname: $fieldname\n";
echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
echo "field type: " . pg_field_type($res, $j) . " \n\n";
}
?>

上の例の出力は以下となります。

column 0
fieldname: author
printed length: 6 characters
storage length: -1 bytes
field type: varchar

column 1
fieldname: year
printed length: 4 characters
storage length: 2 bytes
field type: int2

column 2
fieldname: title
printed length: 24 characters
storage length: -1 bytes
field type: varchar

参考

  • pg_field_num() - 指定されたフィールドのフィールド番号を返す


指定されたフィールドのフィールド番号を返す

  • ≪ pg_field_name
  • pg_field_prtlen ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定されたフィールドのフィールド番号を返す

pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — 指定されたフィールドのフィールド番号を返す

説明

pg_field_num(PgSql\Result $result, string $field): int

pg_field_num() は、 指定した結果 (result) インスタンスにおいて field に相当するカラム(フィールド) のフィールド番号を返します。

注意:

この関数は、以前は pg_fieldnum() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

フィールドの名前。 ここで指定された名前は、SQL コマンド内の識別子として扱われます。 つまり、ダブルクォートで囲まれない限り小文字に変換されます。

戻り値

フィールド番号（0 から始まります）を返します。エラー時には -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールドの情報を取得する

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

$res = pg_query($dbconn, "select author, year, title from authors where author = 'Orwell'");

echo "Column 'title' is field number: ", pg_field_num($res, 'title');
?>

上の例の出力は以下となります。

Column 'title' is field number: 2

参考

  • pg_field_name() - フィールドの名前を返す


表示される長さを返す

  • ≪ pg_field_num
  • pg_field_size ≫
  • PHP Manual
  • PostgreSQL 関数
  • 表示される長さを返す

pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — 表示される長さを返す

説明

pg_field_prtlen(PgSql\Result $result, string|false|null $row, mixed $field_name_or_number): int
pg_field_prtlen(PgSql\Result $result, mixed $field_name_or_number): int

pg_field_prtlen() は、 result で指定した値に関して、実際に 表示した場合の長さ(文字の数)を返します。行番号(row_number)は 0 から始まります。この関数は、エラーの場合に false を返します。

field_name_or_number は、int または string のどちらかで渡すことが可能です。 int で渡された場合、PHP はそれをフィールド番号と判断 します。それ以外の場合はフィールド名と判断します。

pg_field_name() ページの例を参照ください。

注意:

この関数は、以前は pg_fieldprtlen() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

結果の行番号。行番号は 0 から始まります。指定しなかった場合は カレントの行を取得します。

戻り値

フィールドの表示される長さを返します。

変更履歴

バージョン | 説明
8.3.0 | row は、nullable になりました。
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールドの情報を取得する

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

$res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
$i = pg_num_fields($res);
for ($j = 0; $j < $i; $j++) {
echo "column $j\n";
$fieldname = pg_field_name($res, $j);
echo "fieldname: $fieldname\n";
echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
echo "field type: " . pg_field_type($res, $j) . " \n\n";
}
?>

上の例の出力は以下となります。

column 0
fieldname: author
printed length: 6 characters
storage length: -1 bytes
field type: varchar

column 1
fieldname: year
printed length: 4 characters
storage length: 2 bytes
field type: int2

column 2
fieldname: title
printed length: 24 characters
storage length: -1 bytes
field type: varchar

参考

  • pg_field_size() - 指定したフィールドの内部記憶領域におけるサイズを返す


指定したフィールドの内部記憶領域におけるサイズを返す

  • ≪ pg_field_prtlen
  • pg_field_table ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したフィールドの内部記憶領域におけるサイズを返す

pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — 指定したフィールドの内部記憶領域におけるサイズを返す

説明

pg_field_size(PgSql\Result $result, int $field): int

pg_field_size() は、指定した PostgreSQL の 結果において、指定したフィールド番号の内部記憶領域のサイズを (バイト数で)返します。

注意:

この関数は、以前は pg_fieldsize() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

フィールド番号。0 から始まります。

戻り値

内部記憶領域のサイズ（バイト数）を返します。-1 は可変長フィールドを 示します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールドの情報を取得する

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

$res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
$i = pg_num_fields($res);
for ($j = 0; $j < $i; $j++) {
echo "column $j\n";
$fieldname = pg_field_name($res, $j);
echo "fieldname: $fieldname\n";
echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
echo "field type: " . pg_field_type($res, $j) . " \n\n";
}
?>

上の例の出力は以下となります。

column 0
fieldname: author
printed length: 6 characters
storage length: -1 bytes
field type: varchar

column 1
fieldname: year
printed length: 4 characters
storage length: 2 bytes
field type: int2

column 2
fieldname: title
printed length: 24 characters
storage length: -1 bytes
field type: varchar

参考

  • pg_field_prtlen() - 表示される長さを返す
  • pg_field_type() - フィールド番号に対応する型名を返す


tables フィールドの名前あるいは oid を返す

  • ≪ pg_field_size
  • pg_field_type ≫
  • PHP Manual
  • PostgreSQL 関数
  • tables フィールドの名前あるいは oid を返す

pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — tables フィールドの名前あるいは oid を返す

説明

pg_field_table(PgSql\Result $result, int $field, bool $oid_only = false): string|int|false

pg_field_table() は、フィールドが属するテーブルの名前か あるいは oid_only が true の場合にテーブルの oid を返します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

0 から始まるフィールド番号。

oid_only

デフォルトでは、フィールドが属するテーブルの名前が返されます。 しかし oid_only をtrue に設定すると、 その代わりに oid が返されます。

戻り値

成功した場合にフィールドのテーブル名あるいは oid を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールドについてのテーブル情報の取得

<?php
$dbconn = pg_connect("dbname=publisher") or die("接続できません");

$res = pg_query($dbconn, "SELECT bar FROM foo");

echo pg_field_table($res, 0);
echo pg_field_table($res, 0, true);

$res = pg_query($dbconn, "SELECT version()");
var_dump(pg_field_table($res, 0));
?>

上の例の出力は、 たとえば以下のようになります。

foo
14379580

bool(false)

注意

注意:

テーブル名を返すよりも oid を返すほうがずっと高速です。 なぜなら、テーブル名を取得するには、 データベースのシステムテーブルにクエリを発行しなければならないからです。

参考

  • pg_field_name() - フィールドの名前を返す
  • pg_field_type() - フィールド番号に対応する型名を返す


フィールド番号に対応する型名を返す

  • ≪ pg_field_table
  • pg_field_type_oid ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールド番号に対応する型名を返す

pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — フィールド番号に対応する型名を返す

説明

pg_field_type(PgSql\Result $result, int $field): string

pg_field_type() は、指定した result インスタンスにおいて、指定した field の型名を保持する文字列を 返します。

注意:

フィールドが（基本型ではなく）PostgreSQL ドメインを使用している場合は、 ドメインそのものの名前ではなくドメインの元となっている型の名前を返します。

注意:

この関数は、以前は pg_fieldtype() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

フィールド番号。0 から始まります。

戻り値

フィールド型の名前を文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールドの情報を取得する

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

// 'title' は varchar 型と仮定する
$res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

echo "Title field type: ", pg_field_type($res, 0);
?>

上の例の出力は以下となります。

Title field type: varchar

参考

  • pg_field_prtlen() - 表示される長さを返す
  • pg_field_name() - フィールドの名前を返す
  • pg_field_type_oid() - フィールド番号に対応する型 ID（OID）を返す


フィールド番号に対応する型 ID（OID）を返す

  • ≪ pg_field_type
  • pg_flush ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールド番号に対応する型 ID（OID）を返す

pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — フィールド番号に対応する型 ID（OID）を返す

説明

pg_field_type_oid(PgSql\Result $result, int $field): string|int

pg_field_type_oid() は、指定した result インスタンスにおける指定した field の型の OID を返します。

フィールド型についての詳細な情報を得るには、PostgreSQL のシステムテーブル pg_type に対して、この関数で取得した OID を用いて 問い合わせます。PostgreSQL の format_type() 関数は、 型の OID を SQL の型名に変換します。

注意:

フィールドが（基本型ではなく）PostgreSQL ドメインを使用している場合は、 ドメインそのものの OID ではなくドメインの元となっている型の OID を返します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field

フィールド番号。0 から始まります。

戻り値

フィールドの型に対応する OID を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 フィールドの情報を得る

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

// 'title' は varchar 型であると仮定する
$res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

echo "Title field type OID: ", pg_field_type_oid($res, 0);
?>

上の例の出力は以下となります。

Title field type OID: 1043

参考

  • pg_field_type() - フィールド番号に対応する型名を返す
  • pg_field_prtlen() - 表示される長さを返す
  • pg_field_name() - フィールドの名前を返す


送信を待っているクエリデータをフラッシュする

  • ≪ pg_field_type_oid
  • pg_free_result ≫
  • PHP Manual
  • PostgreSQL 関数
  • 送信を待っているクエリデータをフラッシュする

pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — 送信を待っているクエリデータをフラッシュする

説明

pg_flush(PgSql\Connection $connection): int|bool

pg_flush() は、送信を待機中のすべての クエリデータを接続へフラッシュします。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

フラッシュが成功したか、またはフラッシュを待機中のデータがなかった場合 true、 保留中のデータの一部がフラッシュされたが、まだ残りがある場合、0。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


クエリ結果のメモリを開放する

  • ≪ pg_flush
  • pg_get_notify ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリ結果のメモリを開放する

pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — クエリ結果のメモリを開放する

説明

pg_free_result(PgSql\Result $result): bool

pg_free_result() は、指定された クエリ結果 PgSql\Result インスタンスに関するメモリとデータを開放します。

この関数は、スクリプト実行中のメモリ使用量を抑制したい場合にのみ コールする必要があります。それ以外の場合は、すべての結果保持用 メモリは、スクリプトが終了する際に自動的に開放されます。

注意:

この関数は、以前は pg_freeresult() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_free_result() の例

<?php
$db = pg_connect("dbname=users user=me") || die();

$res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

$val = pg_fetch_result($res, 1, 0);

echo "First field in the second row is: ", $val, "\n";

pg_free_result($res);
?>

上の例の出力は以下となります。

First field in the second row is: 2

参考

  • pg_query() - クエリを実行する
  • pg_query_params() - SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
  • pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ


SQL NOTIFY メッセージを取得する

  • ≪ pg_free_result
  • pg_get_pid ≫
  • PHP Manual
  • PostgreSQL 関数
  • SQL NOTIFY メッセージを取得する

pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — SQL NOTIFY メッセージを取得する

説明

pg_get_notify(PgSql\Connection $connection, int $mode = PGSQL_ASSOC): array|false

pg_get_notify()は、NOTIFY SQL コマンドにより送信された通知メッセージを取得します。 通知メッセージを取得するには、LISTEN SQL コマンドを発行する必要があります。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

mode

返される配列のインデックスを制御するオプションの引数です。 mode は定数で、以下の値を取ることができます。: PGSQL_ASSOC, PGSQL_NUM, PGSQL_BOTH。 PGSQL_NUM を使うと、配列のインデックスを数値にした配列を返します。PGSQL_ASSOC を使うと、連想配列のインデックスを返します。PGSQL_BOTH を指定すると、数値と連想配列のインデックスを両方含めた形で配列を返します。

戻り値

NOTIFY メッセージ名とバックエンドの PID を含む 配列を返します。 サーバーでサポートされている場合は、 配列にはサーバーのバージョンおよびペイロードも含まれます。 もし待ち受ける NOTIFY が存在しない場合は、 false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 PostgreSQL NOTIFY メッセージ

<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

// 他のプロセスからの 'author_updated' メッセージを監視する
pg_query($conn, 'LISTEN author_updated;');
$notify = pg_get_notify($conn);
if (!$notify) {
echo "No messages\n";
} else {
print_r($notify);
}
?>

参考

  • pg_get_pid() - バックエンドのプロセス ID を得る


バックエンドのプロセス ID を得る

  • ≪ pg_get_notify
  • pg_get_result ≫
  • PHP Manual
  • PostgreSQL 関数
  • バックエンドのプロセス ID を得る

pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — バックエンドのプロセス ID を得る

説明

pg_get_pid(PgSql\Connection $connection): int

pg_get_pid() は、バックエンド(データベースサーバ のプロセス)のプロセス ID を取得します。プロセス ID は、 NOTIFY メッセージが他のプロセスから送信されている かどうかを調べるために有用です。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

バックエンドのデータベースのプロセス ID 。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 PostgreSQL バックエンドの PID

<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

// バックエンドのプロセスIDを取得。このプロセスIDをpg_get_notify()で使用
$pid = pg_get_pid($conn);
?>

参考

  • pg_get_notify() - SQL NOTIFY メッセージを取得する


非同期クエリの結果を取得する

  • ≪ pg_get_pid
  • pg_host ≫
  • PHP Manual
  • PostgreSQL 関数
  • 非同期クエリの結果を取得する

pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — 非同期クエリの結果を取得する

説明

pg_get_result(PgSql\Connection $connection): PgSql\Result|false

pg_get_result() は、
pg_send_query(),
pg_send_query_params()
あるいは pg_send_execute()
で実行した非同期クエリから
PgSql\Result クラスのインスタンスを取得します。

pg_send_query() およびその他の非同期クエリ関数は、 複数のクエリを PostgreSQL サーバーに送信することが可能です。クエリの結果を ひとつずつ取得するには、pg_get_result() を使用します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

PgSql\Result クラスのインスタンスを返します。 結果がもうない場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_get_result() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
}

$res1 = pg_get_result($dbconn);
echo "First call to pg_get_result(): $res1\n";
$rows1 = pg_num_rows($res1);
echo "$res1 has $rows1 records\n\n";

$res2 = pg_get_result($dbconn);
echo "Second call to pg_get_result(): $res2\n";
$rows2 = pg_num_rows($res2);
echo "$res2 has $rows2 records\n";
?>

上の例の出力は以下となります。

First call to pg_get_result(): Resource id #3
Resource id #3 has 3 records

Second call to pg_get_result(): Resource id #4
Resource id #4 has 1 records

参考

  • pg_send_query() - 非同期クエリを送信する


接続に関連するホスト名を返す

  • ≪ pg_get_result
  • pg_insert ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関連するホスト名を返す

pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — 接続に関連するホスト名を返す

説明

pg_host(?PgSql\Connection $connection = null): string

pg_host() は、指定した connection インスタンスが接続しているホストの 名前を返します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

connection が接続しているホストの名前を 文字列で返します。エラー時には空の文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_host() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");

if ($pgsql_conn) {
print "Successfully connected to: " . pg_host($pgsql_conn) . "<br/>\n";
} else {
print pg_last_error($pgsql_conn);
exit;
}
?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする
  • pg_pconnect() - 持続的な PostgreSQL 接続をオープンする


テーブルに配列を挿入する

  • ≪ pg_host
  • pg_last_error ≫
  • PHP Manual
  • PostgreSQL 関数
  • テーブルに配列を挿入する

pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — テーブルに配列を挿入する

説明

pg_insert(
PgSql\Connection $connection,
string $table_name,
array $values,
int $flags = PGSQL_DML_EXEC
): PgSql\Result|string|bool

pg_insert() は、 table_name で指定したテーブルに values の値を挿入します。

flags が指定されている場合、そのオプションと ともに pg_convert() が values に適用されます。

デフォルトでは、 pg_insert() は生の値を渡します。 値はエスケープするか、 flags に PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、 エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

行を挿入するテーブルの名前。テーブル table_name は、少なくとも values の要素数ぶんのカラムを 保持している必要があります。

values

テーブル table_name のフィールド名をキーに、 挿入する内容を値にもつ配列。

flags

PGSQL_CONV_OPTS、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING を組み合わせた数。 PGSQL_DML_STRING が flags に含まれていた場合、 クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

戻り値

成功した場合に true を、失敗した場合に false を返します。 flags で PGSQL_DML_STRING が渡された場合は、成功時に文字列を返します。

エラー / 例外

指定したテーブルが無効な場合、ValueError がスローされます。

値やフィールドの型が PostgreSQL の型と一致しない場合、 ValueError または TypeError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | 指定されたテーブルが無効な場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生していました。
8.3.0 | 値やフィールドの型が PostgreSQL の型と一致しない場合、 ValueError または TypeError がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生していました。
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_insert() の例

<?php
$dbconn = pg_connect('dbname=foo');
// これは少しだけ安全です。なぜなら、全ての値がエスケープされるからです。
// しかし、PostgreSQL は JSON/Array をサポートしています。これらの型に
// ついてはエスケープされたクエリや、プリペアドクエリでも安全ではありません。
$res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
if ($res) {
echo "POST data is successfully logged\n";
} else {
echo "User must have sent wrong inputs\n";
}
?>

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する


特定の接続から直近のエラーメッセージ文字列を取得する

  • ≪ pg_insert
  • pg_last_notice ≫
  • PHP Manual
  • PostgreSQL 関数
  • 特定の接続から直近のエラーメッセージ文字列を取得する

pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する

説明

pg_last_error(?PgSql\Connection $connection = null): string

pg_last_error() は、指定した connection から直近のエラーメッセージを返します。

エラーメッセージは、内部的な PostgreSQL(libpq) 関数コールにより 上書きされる可能性があります。PostgreSQL モジュール関数の中で複数の エラーが発生した場合には、この関数は適切なエラーメッセージを返さない 可能性があります。

エラー処理を改善するために
pg_result_error()、pg_result_error_field()、
pg_result_status() および
pg_connection_status() を使用ください。

注意:

この関数は、以前は pg_errormessage() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

指定した connection の直近のエラーメッセージを 含む文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_last_error() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("接続できませんでした");

// 失敗するクエリ
$res = pg_query($dbconn, "select * from doesnotexist");

echo pg_last_error($dbconn);
?>

参考

  • pg_result_error() - 結果に関連するエラーメッセージを取得する
  • pg_result_error_field() - エラー報告の各フィールドを返す


PostgreSQL サーバーからの直近の通知メッセージを返す

  • ≪ pg_last_error
  • pg_last_oid ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL サーバーからの直近の通知メッセージを返す

pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す

説明

pg_last_notice(PgSql\Connection $connection, int $mode = PGSQL_NOTICE_LAST): array|string|bool

pg_last_notice() は、connection で指定した PostgreSQL サーバーからの直近の通知メッセージを返します。 たとえば、テーブルに SERIAL カラムを作成する場合などに PostgreSQL サーバーは通知メッセージを送信します。

pg_last_notice() でトランザクションに関連する通知 メッセージがあるかないかをチェックすることで、無意味なクエリの発行を 避けることが可能です。

php.ini で pgsql.ignore_notice に 1 を指定することで、通知メッセージの追跡をしないようにすることが可能です。

php.ini で pgsql.log_notice に 0 を指定することで、通知メッセージをログに記録しないようにすることが可能です。 pgsql.ignore_notice が 0 に設定されていない限り、 通知メッセージをログに記録することはできません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

mode

直近の通知を返す PGSQL_NOTICE_LAST、 すべての通知を返す PGSQL_NOTICE_ALL、 または通知をクリアする PGSQL_NOTICE_CLEAR のいずれか

戻り値

PGSQL_NOTICE_LAST 使用時は、 指定された connection の直近の通知を含む string、 PGSQL_NOTICE_ALL 使用時は array、 PGSQL_NOTICE_CLEAR 使用時は bool を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.1.0 | mode パラメータが追加されました。

例

例1 pg_last_notice() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");

$res = pg_query("CREATE TABLE test (id SERIAL)");

$notice = pg_last_notice($pgsql_conn);

echo $notice;
?>

上の例の出力は以下となります。

CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

参考

  • pg_query() - クエリを実行する
  • pg_last_error() - 特定の接続から直近のエラーメッセージ文字列を取得する


直近の行のオブジェクト ID を返す

  • ≪ pg_last_notice
  • pg_lo_close ≫
  • PHP Manual
  • PostgreSQL 関数
  • 直近の行のオブジェクト ID を返す

pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — 直近の行のオブジェクト ID を返す

説明

pg_last_oid(PgSql\Result $result): string|int|false

pg_last_oid() は、挿入された行に割り当てられた OID を取得します。

OID フィールドは PostgreSQL 7.2 からはオプションとなり、 PostgreSQL 8.1 ではデフォルトで存在しません。OID フィールドが テーブルに存在しない場合、プログラマは pg_result_status() を使用して挿入が成功したことを 確かめる必要があります。

挿入された行の SERIAL フィールドの値を取得するには、 PostgreSQL の CURRVAL 関数を使用してシーケンス内で 直近に要求された値を取得する必要があります。シーケンス名がわからない 場合は、PostgreSQL 8.0 の関数 pg_get_serial_sequence が必要になります。

PostgreSQL 8.1 には LASTVAL 関数が存在し、セッション内で 直近に使用されたシーケンスの値を返します。これを用いれば、シーケンスや テーブルやカラムの名前を指定する必要がなくなります。

注意:

この関数は、以前は pg_getlastoid() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

戻り値

指定された connection で、直近に挿入された行に 割り当てられた OID を数値または文字列で返します。エラー時や有効な OID のない場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_last_oid() の例

<?php
// データベースに接続します
pg_connect("dbname=mark host=localhost");

// サンプルのテーブルを作ります
pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

// データを追加します
$res = pg_query("INSERT INTO test VALUES (1)");

$oid = pg_last_oid($res);
?>

参考

  • pg_query() - クエリを実行する
  • pg_result_status() - クエリ結果のステータスを取得する


ラージオブジェクトをクローズする

  • ≪ pg_last_oid
  • pg_lo_create ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトをクローズする

pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — ラージオブジェクトをクローズする

説明

pg_lo_close(PgSql\Lob $lob): bool

pg_lo_close() はラージオブジェクトをクローズします。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、かつて pg_loclose() という名前でした。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_close() example

<?php
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$oid = pg_lo_create($database);
echo "$oid\n";
$handle = pg_lo_open($database, $oid, "w");
echo "$handle\n";
pg_lo_write($handle, "large object data");
pg_lo_close($handle);
pg_query($database, "commit");
?>

参考

  • pg_lo_open() - ラージオブジェクトをオープンする
  • pg_lo_create() - ラージオブジェクトを生成する
  • pg_lo_import() - ファイルからラージオブジェクトをインポートする


ラージオブジェクトを生成する

  • ≪ pg_lo_close
  • pg_lo_export ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを生成する

pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — ラージオブジェクトを生成する

説明

pg_lo_create(PgSql\Connection $connection = ?, mixed $object_id = ?): int
pg_lo_create(mixed $object_id): int

pg_lo_create() はラージオブジェクトを 生成し、そのラージオブジェクトの OID を返します。 PostgreSQL アクセスモード INV_READ、INV_WRITE および INV_ARCHIVE はサポートされません。オブジェクトは 常に読み書き可のアクセス権で生成されます。 INV_ARCHIVE は PostgreSQL 自身からも削除されました （バージョン 6.3 以降）。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

ラージオブジェクトインターフェイス（アクセス制御もできないし使用が面倒） を使用するかわりに、PostgreSQL の bytea カラム型と pg_escape_bytea() を試してください。

注意:

この関数は、以前は pg_locreate() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

object_id

object_id が指定されると、 この関数は指定された ID のラージオブジェクトを作成しようとします。 それ以外の場合は、サーバーから割り当てられたオブジェクト ID を使用します。 このパラメータは PostgreSQL 8.1 以降の新機能に依存しています。

戻り値

ラージオブジェクトの OID を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_create() の例

<?php
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$oid = pg_lo_create($database);
echo "$oid\n";
$handle = pg_lo_open($database, $oid, "w");
echo "$handle\n";
pg_lo_write($handle, "large object data");
pg_lo_close($handle);
pg_query($database, "commit");
?>


ラージオブジェクトをファイルにエクスポートする

  • ≪ pg_lo_create
  • pg_lo_import ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトをファイルにエクスポートする

pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — ラージオブジェクトをファイルにエクスポートする

説明

pg_lo_export(PgSql\Connection $connection = ?, int $oid, string $pathname): bool

pg_lo_export() は PostgreSQL データベースから ラージオブジェクトを取得し、その内容をローカルファイルシステム上の ファイルに保存します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loexport() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

oid

データベース内のラージオブジェクトの OID 。

pathname

ラージオブジェクトをクライアントのファイルシステムに書き込む際の フルパスとファイル名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_export() の例

<?php
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$oid = pg_lo_create($database);
$handle = pg_lo_open($database, $oid, "w");
pg_lo_write($handle, "large object data");
pg_lo_close($handle);
pg_lo_export($database, $oid, '/tmp/lob.dat');
pg_query($database, "commit");
?>

参考

  • pg_lo_import() - ファイルからラージオブジェクトをインポートする


ファイルからラージオブジェクトをインポートする

  • ≪ pg_lo_export
  • pg_lo_open ≫
  • PHP Manual
  • PostgreSQL 関数
  • ファイルからラージオブジェクトをインポートする

pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — ファイルからラージオブジェクトをインポートする

説明

pg_lo_import(PgSql\Connection $connection = ?, string $pathname, mixed $object_id = ?): int

pg_lo_import() は、ファイルシステム上のファイルの データをもとにして新しいラージオブジェクトをデータベース内に作成します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loimport() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

pathname

クライアントのファイルシステムからラージオブジェクト用データを 読み込む際のフルパスとファイル名。

object_id

object_id が指定されると、 この関数は指定された ID のラージオブジェクトを作成しようとします。 それ以外の場合は、サーバーから割り当てられたオブジェクト ID を使用します。 このパラメータは PostgreSQL 8.1 以降の新機能に依存しています。

戻り値

作成されたラージオブジェクトの OID を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_import() の例

<?php
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$oid = pg_lo_import($database, '/tmp/lob.dat');
pg_query($database, "commit");
?>

参考

  • pg_lo_export() - ラージオブジェクトをファイルにエクスポートする
  • pg_lo_open() - ラージオブジェクトをオープンする


ラージオブジェクトをオープンする

  • ≪ pg_lo_import
  • pg_lo_read ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトをオープンする

pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — ラージオブジェクトをオープンする

説明

pg_lo_open(PgSql\Connection $connection, int $oid, string $mode): PgSql\Lob|false

pg_lo_open() はデータベース内にラージオブジェクトを オープンし、それを操作するための PgSql\Lob クラスのインスタンスを返します。

警告

PgSql\Lob のインスタンスを閉じる前にデータベースへの接続を 閉じないでください。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loopen() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

oid

データベース内のラージオブジェクトの OID 。

mode

読み込み専用の "r"、書き込み専用の "w"、読み書き可能な "rw" のいずれか。

戻り値

PgSql\Lob クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PgSql\Lob クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_open() の例

<?php
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$oid = pg_lo_create($database);
echo "$oid\n";
$handle = pg_lo_open($database, $oid, "w");
echo "$handle\n";
pg_lo_write($handle, "large object data");
pg_lo_close($handle);
pg_query($database, "commit");
?>

参考

  • pg_lo_close() - ラージオブジェクトをクローズする
  • pg_lo_create() - ラージオブジェクトを生成する


ラージオブジェクトを読み込む

  • ≪ pg_lo_open
  • pg_lo_read_all ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを読み込む

pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — ラージオブジェクトを読み込む

説明

pg_lo_read(PgSql\Lob $lob, int $length = 8192): string|false

pg_lo_read()は、ラージオブジェクトから最大 length バイト分読み込み、文字列として返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loread() と呼ばれていました。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

length

返すデータの最大バイト数（オプション）。

戻り値

ラージオブジェクトから length バイトのデータを 文字列で返します。エラー時には false を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_read() の例

<?php
$doc_oid = 189762345;
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$handle = pg_lo_open($database, $doc_oid, "r");
$data = pg_lo_read($handle, 50000);
pg_query($database, "commit");
echo $data;
?>

参考

  • pg_lo_read_all() - ラージオブジェクト全体を読み込みブラウザに直接送信する


ラージオブジェクト全体を読み込みブラウザに直接送信する

  • ≪ pg_lo_read
  • pg_lo_seek ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクト全体を読み込みブラウザに直接送信する

pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する

説明

pg_lo_read_all(PgSql\Lob $lob): int

pg_lo_read_all() は、ラージオブジェクトを読み込み 未送信のヘッダを全て送信した後、ブラウザに直接ラージオブジェクトを 送信します。これは主に、イメージや音などのバイナリデータを送信するために 使用します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_loreadall() と呼ばれていました。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

戻り値

読み込んだバイト数を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_read_all() の例

<?php
header('Content-type: image/jpeg');
$image_oid = 189762345;
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$handle = pg_lo_open($database, $image_oid, "r");
pg_lo_read_all($handle);
pg_query($database, "commit");
?>

参考

  • pg_lo_read() - ラージオブジェクトを読み込む


ラージオブジェクトの位置をシークする

  • ≪ pg_lo_read_all
  • pg_lo_tell ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトの位置をシークする

pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — ラージオブジェクトの位置をシークする

説明

pg_lo_seek(PgSql\Lob $lob, int $offset, int $whence = SEEK_CUR): bool

pg_lo_seek() は PgSql\Lob インスタンスの位置をシークします。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

offset

シークするバイト数。

whence

定数 PGSQL_SEEK_SET（オブジェクトの先頭からシークする）、 PGSQL_SEEK_CUR（カレントの位置からシークする）、 あるいは PGSQL_SEEK_END（オブジェクトの最後からシークする） の中のひとつ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_seek() の例

<?php
$doc_oid = 189762345;
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$handle = pg_lo_open($database, $doc_oid, "r");
// 最初の 50000 バイトをスキップする
pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
// 次の 10000 バイトを読み込む
$data = pg_lo_read($handle, 10000);
pg_query($database, "commit");
echo $data;
?>

参考

  • pg_lo_tell() - ラージオブジェクトのカレントのシーク位置を返す


ラージオブジェクトのカレントのシーク位置を返す

  • ≪ pg_lo_seek
  • pg_lo_truncate ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトのカレントのシーク位置を返す

pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す

説明

pg_lo_tell(PgSql\Lob $lob): int

pg_lo_tell() は、ラージオブジェクトのカレントの位置 （先頭からのオフセット）を返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

戻り値

ラージオブジェクトの先頭からのカレントのシーク位置（バイト数）を返します。 エラーが発生した場合は、負の数を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_tell() の例

<?php
$doc_oid = 189762345;
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$handle = pg_lo_open($database, $doc_oid, "r");
// 最初の 50000 バイトをスキップする
pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
// どれだけスキップしたのかを調べる
$offset = pg_lo_tell($handle);
echo "Seek position is: $offset";
pg_query($database, "commit");
?>

上の例の出力は以下となります。

Seek position is: 50000

参考

  • pg_lo_seek() - ラージオブジェクトの位置をシークする


ラージオブジェクトを切り詰める

  • ≪ pg_lo_tell
  • pg_lo_unlink ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを切り詰める

pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — ラージオブジェクトを切り詰める

説明

pg_lo_truncate(PgSql\Lob $lob, int $size): bool

pg_lo_truncate() は、PgSql\Lob クラスのインスタンスを切り詰めます。

ラージオブジェクトのインターフェイスを使うには、トランザクションブロックで囲む必要があります。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

size

切り詰めるバイトサイズ

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_truncate() の例

<?php
$doc_oid = 189762345;
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$handle = pg_lo_open($database, $doc_oid, "r");
// Truncate to 0
pg_lo_truncate($handle, 0);
pg_query($database, "commit");
echo $data;
?>

参考

  • pg_lo_tell() - ラージオブジェクトのカレントのシーク位置を返す


ラージオブジェクトを削除する

  • ≪ pg_lo_truncate
  • pg_lo_write ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトを削除する

pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — ラージオブジェクトを削除する

説明

pg_lo_unlink(PgSql\Connection $connection, int $oid): bool

pg_lo_unlink()は、oidで 関連付けられたラージオブジェクトを削除します。成功した場合に true を、失敗した場合に false を返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_lounlink() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

oid

データベース内のラージオブジェクトの OID 。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_lo_unlink() の例

<?php
// 削除するラージオブジェクトの OID
$doc_oid = 189762345;
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
pg_lo_unlink($database, $doc_oid);
pg_query($database, "commit");
?>

参考

  • pg_lo_create() - ラージオブジェクトを生成する
  • pg_lo_import() - ファイルからラージオブジェクトをインポートする


ラージオブジェクトに書き込む

  • ≪ pg_lo_unlink
  • pg_meta_data ≫
  • PHP Manual
  • PostgreSQL 関数
  • ラージオブジェクトに書き込む

pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — ラージオブジェクトに書き込む

説明

pg_lo_write(PgSql\Lob $lob, string $data, ?int $length = null): int|false

pg_lo_write() は、ラージオブジェクトの カレントのシーク位置にデータを書き込みます。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

注意:

この関数は、以前は pg_lowrite() と呼ばれていました。

パラメータ

lob

pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

data

ラージオブジェクトに書き込むデータ。length が 数値で、かつ data の長さより小さく指定されている場合、 length バイトのみが書き込まれます。

length

書き込むデータの最大バイト数（オプション）。0 より大きく、かつ data のサイズ以下でなければなりません。 デフォルトは data の長さです。

戻り値

ラージオブジェクトに書き込んだバイト数を返します。 エラー時には false を返します。

変更履歴

バージョン | 説明
8.1.0 | lob は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | length は、nullable になりました。

例

例1 pg_lo_write() の例

<?php
$doc_oid = 189762345;
$data = "This will overwrite the start of the large object.";
$database = pg_connect("dbname=jacarta");
pg_query($database, "begin");
$handle = pg_lo_open($database, $doc_oid, "w");
$data = pg_lo_write($handle, $data);
pg_query($database, "commit");
?>

参考

  • pg_lo_create() - ラージオブジェクトを生成する
  • pg_lo_open() - ラージオブジェクトをオープンする


テーブルからメタデータを取得する

  • ≪ pg_lo_write
  • pg_num_fields ≫
  • PHP Manual
  • PostgreSQL 関数
  • テーブルからメタデータを取得する

pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — テーブルからメタデータを取得する

説明

pg_meta_data(PgSql\Connection $connection, string $table_name, bool $extended = false): array|false

pg_meta_data() は、table_name のテーブル定義を配列として返します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

テーブルの名前。

extended

拡張メタデータを返すかどうかを表すフラグ。デフォルトは false。

戻り値

テーブル定義の配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 テーブルのメタデータを得る

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

$meta = pg_meta_data($dbconn, 'authors');
if (is_array($meta)) {
echo '<pre>';
var_dump($meta);
echo '</pre>';
}
?>

上の例の出力は以下となります。

array(3) {
["author"]=>
array(5) {
  ["num"]=>
  int(1)
  ["type"]=>
  string(7) "varchar"
  ["len"]=>
  int(-1)
  ["not null"]=>
  bool(false)
  ["has default"]=>
  bool(false)
}
["year"]=>
array(5) {
  ["num"]=>
  int(2)
  ["type"]=>
  string(4) "int2"
  ["len"]=>
  int(2)
  ["not null"]=>
  bool(false)
  ["has default"]=>
  bool(false)
}
["title"]=>
array(5) {
  ["num"]=>
  int(3)
  ["type"]=>
  string(7) "varchar"
  ["len"]=>
  int(-1)
  ["not null"]=>
  bool(false)
  ["has default"]=>
  bool(false)
}
}

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する


フィールド数を返す

  • ≪ pg_meta_data
  • pg_num_rows ≫
  • PHP Manual
  • PostgreSQL 関数
  • フィールド数を返す

pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — フィールド数を返す

説明

pg_num_fields(PgSql\Result $result): int

pg_num_fields() は、 PgSql\Result クラスのインスタンスから フィールド（カラム）の数を返します。

注意:

この関数は、以前は pg_numfields() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

戻り値

結果のフィールド（カラム）数を返します。エラー時には -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_num_fields() の例

<?php
$result = pg_query($conn, "SELECT 1, 2");

$num = pg_num_fields($result);

echo $num . " field(s) returned.\n";
?>

上の例の出力は以下となります。

2 field(s) returned.

参考

  • pg_num_rows() - 行数を返す
  • pg_affected_rows() - 変更されたレコード(タプル)の数を返す


行数を返す

  • ≪ pg_num_fields
  • pg_options ≫
  • PHP Manual
  • PostgreSQL 関数
  • 行数を返す

pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — 行数を返す

説明

pg_num_rows(PgSql\Result $result): int

pg_num_rows() は、 PgSql\Result クラスのインスタンスに含まれる行数を返します。

注意:

この関数は、以前は pg_numrows() と呼ばれていました。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

戻り値

結果の行数を返します。エラー時には -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_num_rows() の例

<?php
$result = pg_query($conn, "SELECT 1");

$rows = pg_num_rows($result);

echo $rows . " row(s) returned.\n";
?>

上の例の出力は以下となります。

1 row(s) returned.

参考

  • pg_num_fields() - フィールド数を返す
  • pg_affected_rows() - 変更されたレコード(タプル)の数を返す


接続に関連するオプションを取得する

  • ≪ pg_num_rows
  • pg_parameter_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関連するオプションを取得する

pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — 接続に関連するオプションを取得する

説明

pg_options(?PgSql\Connection $connection = null): string

pg_options() は、指定した connection インスタンスの オプションを保持する文字列を返します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

connection のオプションを文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_options() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");
echo pg_options($pgsql_conn);
?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする


サーバーのパラメータ設定を検索する

  • ≪ pg_options
  • pg_pconnect ≫
  • PHP Manual
  • PostgreSQL 関数
  • サーバーのパラメータ設定を検索する

pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — サーバーのパラメータ設定を検索する

説明

pg_parameter_status(PgSql\Connection $connection = ?, string $param_name): string

サーバーのパラメータ設定を検索します。

いくつかのパラメータについては、接続の確立時や値の変更時にサーバーから 自動的に通知されます。pg_parameter_status() は これらの設定問い合わせるために使用可能です。指定したパラメータが存在する 場合にその値を、存在しない場合に false を返します。

PostgreSQL 8.0 で指定できるパラメータには以下が含まれます。 server_version、 server_encoding、client_encoding、 is_superuser、session_authorization、 DateStyle、TimeZone および integer_datetimes （server_encoding、TimeZone および integer_datetimes は 8.0 より前のバージョンでは指定できません）。 server_version、server_encoding および integer_datetimes は、PostgreSQL の稼動中には変更できないことに注意しましょう。

PostgreSQL 7.3 以前のサーバーはパラメータ設定を通知する機能を持っていません。 しかし、pg_parameter_status() には server_version および client_encoding を取得する機能を組み込んでいます。これらの値を取得するためにアプリケーションで アドホックなコードを書くのではなく、pg_parameter_status() を使用することを推奨します。

警告

7.4 より前の PostgreSQL サーバーでは、接続の確立後に SET を用いて client_encoding を変更しても pg_parameter_status() には反映されません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

param_name

指定可能な param_name には以下が含まれます。 server_version、 server_encoding、client_encoding、 is_superuser、session_authorization、 DateStyle、TimeZone および integer_datetimes。 この値は、大文字小文字を区別するので注意して下さい。

戻り値

パラメータの値を文字列で返します。失敗した場合や param_name が間違っている場合には false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_parameter_status() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

echo "Server encoding: ", pg_parameter_status($dbconn, "server_encoding");
?>

上の例の出力は以下となります。

Server encoding: SQL_ASCII


持続的な PostgreSQL 接続をオープンする

  • ≪ pg_parameter_status
  • pg_ping ≫
  • PHP Manual
  • PostgreSQL 関数
  • 持続的な PostgreSQL 接続をオープンする

pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — 持続的な PostgreSQL 接続をオープンする

説明

pg_pconnect(string $connection_string, int $flags = 0): PgSql\Connection|false

pg_pconnect() は PostgreSQL への接続を オープンします。この関数は、他の PostgreSQL関数 が必要とする PgSql\Connection クラスのインスタンスを返します。

既存の接続と同じ connection_string を用いて pg_pconnect() が 2 回目にコールされた場合は、 既存の接続を返します。ただし、flags に PGSQL_CONNECT_FORCE_NEW を指定している場合は 除きます。

持続的接続を有効にするには、php.ini のディレクティブ pgsql.allow_persistent を "On" に設定する必要があります（デフォルトは On です）。 持続的接続の最大数は php.ini ディレクティブ pgsql.max_persistent で設定可能です（デフォルトは制限無しを意味する -1 です）。 接続全体の数は php.ini ディレクティブ pgsql.max_links で設定可能です。

pg_close() は、 pg_pconnect() によりオープンされた持続的接続は 閉じません。

パラメータ

connection_string

すべてデフォルトのパラメータを使用する場合には connection_string を空にすることが可能です。 または 1 つ以上のパラメータを空白で区切って指定することも可能です。 個々のパラメータは keyword = value の形式で 設定します。等号の前後の空白はあってもなくてもかまいません。 空の値や空白を含む値を指定する場合は、その値をシングルクォートで 囲みます（例: keyword = 'a value'）。値の中に シングルクォートやバックスラッシュが含まれる場合は、それらを バックスラッシュでエスケープする必要があります（例: \' および \\）。

現在利用できるパラメータは以下のとおりです。 host, hostaddr, port, dbname, user, password, connect_timeout, options, tty（無視されます）, sslmode, requiressl（非推奨。代わりに sslmode を推奨します） および service 。これらのうち実際にどの パラメータが使えるかは、PostgreSQL のバージョンに依存します。

flags

PGSQL_CONNECT_FORCE_NEW が渡された場合は、 たとえ connection_string が既存の接続と まったく同一であっても新しい接続をオープンします。

戻り値

成功した場合に PgSql\Connection クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PgSql\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。

例

例1 pg_pconnect() の使用法

<?php
$dbconn = pg_pconnect("dbname=mary");
// "mary"という名前のデータベースに接続

$dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");
// "localhost"のポート"5432"にて"mary"という名前のデータベースに接続

$dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");
// ユーザー名とパスワードを指定してホスト"sheep"上の"mary"という名前のデータベースに接続

$conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
$dbconn4 = pg_pconnect($conn_string);
// ユーザー名とパスワードを指定してホスト"sheep"上の"test"という名前のデータベースへ接続
?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする
  • 持続的データベース接続


データベース接続を調べる

  • ≪ pg_pconnect
  • pg_port ≫
  • PHP Manual
  • PostgreSQL 関数
  • データベース接続を調べる

pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — データベース接続を調べる

説明

pg_ping(?PgSql\Connection $connection = null): bool

pg_ping() はデータベース接続を調べ、その接続が 壊れている場合には再度接続を試みます。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_ping() の例

<?php
$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "エラーが発生しました。\n";
exit;
}

if (!pg_ping($conn))
die("接続は壊れています。\n");
?>

参考

  • pg_connection_status() - 接続ステータスを取得する
  • pg_connection_reset() - 接続をリセット(再接続)する


接続に関連するポート番号を返す

  • ≪ pg_ping
  • pg_prepare ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関連するポート番号を返す

pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — 接続に関連するポート番号を返す

説明

pg_port(?PgSql\Connection $connection = null): string

pg_port() は、指定した connection インスタンスが接続している ポートの番号を返します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

connection が指しているデータベースのポート番号を文字列で返します。 エラー時には空文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_port() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");

if ($pgsql_conn) {
print "Successfully connected to port: " . pg_port($pgsql_conn) . "<br/>\n";
} else {
print pg_last_error($pgsql_conn);
exit;
}
?>


指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ

  • ≪ pg_port
  • pg_put_line ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ

pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ

説明

pg_prepare(PgSql\Connection $connection = ?, string $stmtname, string $query): PgSql\Result|false

pg_prepare() は、 pg_execute() あるいは pg_send_execute() で後に実行するためのプリペアドステートメントを作成します。これにより、 繰り返し使用されるコマンドについての構文解析や実行計画作成が最初の 一度だけですみます。pg_prepare() は PostgreSQL 7.4 以降の接続でのみ使用可能です。それ以前のバージョンでは失敗します。

この関数は stmtname という名前の プリペアドステートメントを query 文字列から作成します。 この文字列には 1 つの SQL コマンドが含まれている必要があります。 stmtname を "" にすることで無名ステートメントを 作成することが可能で、既存の無名ステートメントは自動的に上書きされます。 それ以外の場合、もしカレントのセッションで既に定義済みのステートメント名を 使用した場合にはエラーとなります。パラメータを使用する際は、 query 内で $1、$2 のような形式で参照されます。

pg_prepare() で使用するプリペアドステートメントは、 SQLの PREPARE 文を実行することでも作成可能です （しかし、パラメータの型を事前に指定する必要がないという点で pg_prepare() のほうがより柔軟です）。 また、PHP にはプリペアドステートメントを削除する関数がありませんが、 この目的のためには SQLの DEALLOCATE 文が使用可能です。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

stmtname

プリペアドステートメントにつける名前。接続内で一意である必要があります。 "" が指定された場合は無名ステートメントが作成され、以前に定義された 無名ステートメントを上書きします。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_prepare() の使用法

<?php
// "mary"という名前のデータベースに接続
$dbconn = pg_connect("dbname=mary");

// 実行するクエリの準備
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

// プリペアドクエリを実行する。文字列 "Joe's Widgets" は
// エスケープの必要がないことに注意
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

// 同一プリペアドクエリを別のパラメータで実行する
$result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

?>

参考

  • pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
  • pg_send_execute() - 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない


NULL で終わる文字列を PostgreSQL バックエンドに送信する

  • ≪ pg_prepare
  • pg_query ≫
  • PHP Manual
  • PostgreSQL 関数
  • NULL で終わる文字列を PostgreSQL バックエンドに送信する

pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する

説明

pg_put_line(PgSql\Connection $connection = ?, string $data): bool

pg_put_line() は、NULL で終わる文字列を PostgreSQL バックエンドサーバーに送信します。これは、PostgreSQL の COPY FROM コマンドとともに使用する場合に必要となります。

COPY は、PostgreSQL によってサポートされている 高速なデータ読み込みインターフェイスです。データの内容はパースされず、 一度のトランザクションで実行されます。

低レベルな pg_put_line() コマンドを用いない別の方法は、 pg_copy_from() を使用することです。これは、はるかに シンプルなインターフェイスです。

注意:

pg_end_copy() を実行する際には、送信データの最後に 明示的に "\." の 2 文字を送信する必要があります。これによって、 バックエンドに対してデータ送信の終了を通知します。

警告

pg_put_line() の使用は、pg_lo_read() や pg_lo_tell() などを含むラージオブジェクトの操作を 発生させ、これが失敗することもあります。そのような場合、かわりに pg_copy_from() および pg_copy_to() が使用可能です。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

data

PostgreSQL バックエンドに直接送信されるテキストデータ。 最後に NULL が自動的に付加されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_put_line() の例

<?php
$conn = pg_pconnect("dbname=foo");
pg_query($conn, "create table bar (a int4, b char(16), d float8)");
pg_query($conn, "copy bar from stdin");
pg_put_line($conn, "3\thello world\t4.5\n");
pg_put_line($conn, "4\tgoodbye world\t7.11\n");
pg_put_line($conn, "\\.\n");
pg_end_copy($conn);
?>

参考

  • pg_end_copy() - PostgreSQL バックエンドと同期する


クエリを実行する

  • ≪ pg_put_line
  • pg_query_params ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリを実行する

pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — クエリを実行する

説明

pg_query(PgSql\Connection $connection = ?, string $query): PgSql\Result|false

pg_query() は、指定したデータベース connection 上で query を実行します。 特別な理由がない限り、この関数よりも pg_query_params() を使うほうがいいでしょう。

エラーが発生して false が返された場合、もし接続が正常なら pg_last_error() 関数を使用してエラーの詳細情報が 取得可能です。

注意: connectionは省略可能ですが、それは推奨されません。 なぜならスクリプトのバグが発見しにくくなるためです。

注意:

この関数は、以前は pg_exec() と呼ばれていました。 pg_exec() は互換性確保のためにまだ使用可能ですが、 新しい名前を使用することが推奨されています。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

query

実行する 1 つまたは複数の SQL 文。複数の文が関数に渡された場合は、 明示的に BEGIN/COMMIT コマンドを指定していない限りはそれらの文は ひとつのトランザクションとして実行されます。しかし、1 回のコールで 複数のトランザクションを実行することは推奨されません。

警告

ユーザーから受け取ったデータを文字列に直接組み込むのは危険で、SQL インジェクション の脆弱性を引き起こしがちです。クエリ文字列に直接埋め込むのではなく、 pg_query_params() を使ってパラメータとして指定することを推奨します。

ユーザーから受け取ったデータをクエリ文字列に直接埋め込む場合は、 適切にエスケープ する必要があります。

戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_query() の例

<?php

$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

while ($row = pg_fetch_row($result)) {
echo "Author: $row[0] E-mail: $row[1]";
echo "<br />\n";
}

?>

例2 pg_query() で複数の文を使用する例

<?php

$conn = pg_pconnect("dbname=publisher");

// これらの文がひとつのトランザクションとして実行されます

$query = "UPDATE authors SET author=UPPER(author) WHERE id=1;";
$query .= "UPDATE authors SET author=LOWER(author) WHERE id=2;";
$query .= "UPDATE authors SET author=NULL WHERE id=3;";

pg_query($conn, $query);

?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする
  • pg_pconnect() - 持続的な PostgreSQL 接続をオープンする
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_num_rows() - 行数を返す
  • pg_affected_rows() - 変更されたレコード(タプル)の数を返す


SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

  • ≪ pg_query
  • pg_result_error ≫
  • PHP Manual
  • PostgreSQL 関数
  • SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

説明

pg_query_params(PgSql\Connection $connection = ?, string $query, array $params): PgSql\Result|false

コマンドをサーバーに送信し、その結果を待ちます。パラメータを SQL コマンド とは別に渡すことが可能です。

pg_query_params() は pg_query() と似ていますが、追加の機能を有しています。それはパラメータ値が コマンド文字列と分離しているということです。 pg_query_params() は PostgreSQL 7.4 以降の接続でのみ サポートされます。それ以前のバージョンでは失敗します。

パラメータを使用する際は、query 文字列内で $1、$2 のように参照されます。 query の中で同じパラメータを何度も使えます。 その場合は、それぞれに同じ値が渡されます。 params で 実際の値を指定します。null を指定すると、SQL の NULL とみなされます。

pg_query() に対する pg_query_params() の最大の利点は、パラメータの値を query 文字列から 分離できることです。そのため、退屈でエラーの元となりやすいクォート・ エスケープなどをしなくてもよくなります。pg_query() と異なり、pg_query_params() ではひとつの SQL コマンドしか実行できません（クエリ文字列にセミコロンを含めることは 可能です。しかしそれ以降にコマンドを続けることはできません）。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

ユーザーから受け取った値は常にパラメータとして渡すべきです。 直接クエリ文字列に組み込んではいけません。そうしてしまうと、 SQL インジェクション 攻撃を受けてしまう可能性があります。また、クォート文字を含むデータの処理でバグの原因になります。 何らかの理由でパラメータが使えない場合は、値を 適切にエスケープするようにしましょう。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

bytea フィールド用の値は、パラメータとして指定できません。 pg_escape_bytea() を使うか、ラージオブジェクト関数を使うようにしましょう。

戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_query_params() の使用法

<?php
// "mary"という名前のデータベースに接続
$dbconn = pg_connect("dbname=mary");

// Joe's Widgets という名前の店を探す。"Joe's Widgets" を
// エスケープする必要がないことに注意
$result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

// pg_query を使用した場合と比較
$str = pg_escape_string("Joe's Widgets");
$result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

?>

参考

  • pg_query() - クエリを実行する


結果に関連するエラーメッセージを取得する

  • ≪ pg_query_params
  • pg_result_error_field ≫
  • PHP Manual
  • PostgreSQL 関数
  • 結果に関連するエラーメッセージを取得する

pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — 結果に関連するエラーメッセージを取得する

説明

pg_result_error(PgSql\Result $result): string|false

pg_result_error() は、結果インスタンス (result)に関連したエラーメッセージを返します。 このため、ユーザーが pg_last_error() よりも適切な エラーメッセージを得る可能性があります。

pg_result_error_field() は、 pg_result_error() よりもさらに詳細なエラー情報を 返します。

pg_query() はクエリが失敗した場合に false を返すので、
結果ハンドルを取得するには pg_send_query() および
pg_get_result() を使用する必要があります。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

戻り値

文字列を返します。エラーがない場合は空文字列を返します。 result パラメータに関連付けられたエラーがある場合は それを文字列で返します。それ以外の場合は false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_result_error() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("接続できませんでした");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from doesnotexist;");
}

$res1 = pg_get_result($dbconn);
echo pg_result_error($res1);
?>

参考

  • pg_result_error_field() - エラー報告の各フィールドを返す
  • pg_query() - クエリを実行する
  • pg_send_query() - 非同期クエリを送信する
  • pg_get_result() - 非同期クエリの結果を取得する
  • pg_last_error() - 特定の接続から直近のエラーメッセージ文字列を取得する
  • pg_last_notice() - PostgreSQL サーバーからの直近の通知メッセージを返す


エラー報告の各フィールドを返す

  • ≪ pg_result_error
  • pg_result_seek ≫
  • PHP Manual
  • PostgreSQL 関数
  • エラー報告の各フィールドを返す

pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — エラー報告の各フィールドを返す

説明

pg_result_error_field(PgSql\Result $result, int $field_code): string|false|null

pg_result_error_field() は、 result インスタンスに関するエラーメッセージの特定のフィールドを返します。 PostgreSQL 7.4 以降のサーバーでのみ有効です。エラーフィールドは field_code で定義します。

pg_query() や pg_query_params() はクエリが失敗した場合に false を返すので、結果のハンドルを得るには pg_send_query() および pg_get_result() を使用する必要があります。

失敗した pg_query() クエリから詳細なエラー情報を
取得する必要がある場合は、pg_set_error_verbosity()
および pg_last_error() を使用してその結果をパース
します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

field_code

以下の field_code が使用可能です。 PGSQL_DIAG_SEVERITY、 PGSQL_DIAG_SQLSTATE、PGSQL_DIAG_MESSAGE_PRIMARY、 PGSQL_DIAG_MESSAGE_DETAIL、 PGSQL_DIAG_MESSAGE_HINT、PGSQL_DIAG_STATEMENT_POSITION、 PGSQL_DIAG_INTERNAL_POSITION（PostgreSQL 8.0+ のみ）、 PGSQL_DIAG_INTERNAL_QUERY（PostgreSQL 8.0+ のみ）、 PGSQL_DIAG_CONTEXT、PGSQL_DIAG_SOURCE_FILE、 PGSQL_DIAG_SOURCE_LINE あるいは PGSQL_DIAG_SOURCE_FUNCTION 。

戻り値

エラーフィールドの内容を文字列で返します。 フィールドが存在しない場合に null 、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_result_error_field() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from doesnotexist;");
}

$res1 = pg_get_result($dbconn);
echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
?>

参考

  • pg_result_error() - 結果に関連するエラーメッセージを取得する


結果インスタンスの内部行オフセットを設定する

  • ≪ pg_result_error_field
  • pg_result_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • 結果インスタンスの内部行オフセットを設定する

pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — 結果インスタンスの内部行オフセットを設定する

説明

pg_result_seek(PgSql\Result $result, int $row): bool

pg_result_seek()は、結果インスタンスの行の位置を 指定された offset にセットします。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

row

PgSql\Result クラスのインスタンス内で、内部オフセットを移動させる行。 行番号はゼロから始まります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_result_seek() の例

<?php

// データベースに接続する
$conn = pg_pconnect("dbname=publisher");

// クエリを実行する
$result = pg_query($conn, "SELECT author, email FROM authors");

// 3 行目をシークする（結果が 3 行あると仮定する）
pg_result_seek($result, 2);

// 3 行目を取得する
$row = pg_fetch_row($result);

?>

参考

  • pg_fetch_row() - 数値添字の配列として行を得る
  • pg_fetch_assoc() - 行を連想配列として取得する
  • pg_fetch_array() - 行を配列として取得する
  • pg_fetch_object() - 行をオブジェクトとして得る
  • pg_fetch_result() - 結果インスタンスから値を返す


クエリ結果のステータスを取得する

  • ≪ pg_result_seek
  • pg_select ≫
  • PHP Manual
  • PostgreSQL 関数
  • クエリ結果のステータスを取得する

pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — クエリ結果のステータスを取得する

説明

pg_result_status(PgSql\Result $result, int $mode = PGSQL_STATUS_LONG): string|int

pg_result_status() は、 PgSql\Result インスタンスのステータス あるいは結果に関するコマンド補完タグを返します。

パラメータ

result

pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

mode

result の数値ステータスを返す PGSQL_STATUS_LONG、あるいは result のコマンドタグを返す PGSQL_STATUS_STRING のいずれかです。 指定しない場合は PGSQL_STATUS_LONG がデフォルトです。

戻り値

PGSQL_STATUS_LONG が指定された場合の戻り値は 以下のいずれかです。 PGSQL_EMPTY_QUERY、 PGSQL_COMMAND_OK、PGSQL_TUPLES_OK、PGSQL_COPY_OUT、 PGSQL_COPY_IN、PGSQL_BAD_RESPONSE、PGSQL_NONFATAL_ERROR および PGSQL_FATAL_ERROR 。 それ以外の場合は、PostgreSQL コマンドタグを含む文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | result は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_result_status() の例

<?php

// データベースに接続する
$conn = pg_pconnect("dbname=publisher");

// COPY を実行する
$result = pg_query($conn, "COPY authors FROM STDIN;");

// 結果ステータスを得る
$status = pg_result_status($result);

// ステータスの内容を調べる
if ($status == PGSQL_COPY_IN)
echo "Copy began.";
else
echo "Copy failed.";

?>

上の例の出力は以下となります。

Copy began.

参考

  • pg_connection_status() - 接続ステータスを取得する


レコードを選択する

  • ≪ pg_result_status
  • pg_send_execute ≫
  • PHP Manual
  • PostgreSQL 関数
  • レコードを選択する

pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — レコードを選択する

説明

pg_select(
PgSql\Connection $connection,
string $table_name,
array $conditions,
int $flags = PGSQL_DML_EXEC,
int $mode = PGSQL_ASSOC
): array|string|false

pg_select() は、field=>value 形式の conditions で指定したレコードを選択します。 クエリに成功した場合、conditions で指定した条件に マッチする全てのレコードとフィールドを含む配列が返されます。

flags が指定された場合、 指定したフラグとともに pg_convert() が conditions に適用されます。

mode が指定された場合、 戻り値は PGSQL_NUM の場合配列、 PGSQL_ASSOC の場合連想配列(これがデフォルトです)、 PGSQL_BOTH の場合数値と連想配列のインデックスが両方含まれた配列になります。

pg_update() は生の値を渡します。 値はエスケープするか、PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

行を選択するテーブルの名前。

conditions

テーブル table_name のフィールド名をキーに、 取得対象となる行にマッチするデータを値にもつ配列。

flags

PGSQL_CONV_FORCE_NULL, PGSQL_DML_NO_CONV, PGSQL_DML_ESCAPE, PGSQL_DML_EXEC, PGSQL_DML_ASYNC, PGSQL_DML_STRING の組み合わせ。 flags の一部に PGSQL_DML_STRING が含まれていた場合、クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、 内部的に pg_convert() を呼び出しません。

mode

PGSQL_ASSOC, PGSQL_NUM, PGSQL_BOTH の組み合わせ。 PGSQL_ASSOC が設定されている場合、 戻り値は連想配列になります。 PGSQL_NUM が設定されている場合、 戻り値は配列になります。 PGSQL_BOTH が設定されている場合、 戻り値は数値と連想配列のインデックスが両方含まれた配列になります。

戻り値

flags に PGSQL_DML_STRING が渡された場合は文字列を返します。 それ以外の場合は、成功時に配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.1.0 | mode パラメータが追加されました。

例

例1 pg_select() の例

<?php
$db = pg_connect('dbname=foo');
// これは少しだけ安全です。なぜなら、全ての値がエスケープされるからです。
// しかし、PostgreSQL は JSON/Array をサポートしています。これらの型に
// ついてはエスケープされたクエリや、プリペアドクエリでも安全ではありません。
$rec = pg_select($db, 'post_log', $_POST);
if ($rec) {
echo "選択されたレコード:\n";
var_dump($rec);
} else {
echo "ユーザーが誤った入力を送信しました。\n";
}
?>

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する


指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

  • ≪ pg_select
  • pg_send_prepare ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

説明

pg_send_execute(PgSql\Connection $connection, string $statement_name, array $params): int|bool

指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待ちません。

これは pg_send_query_params() と似ています。 しかし、実行するコマンドは指定したクエリ文字列で決まるのではなく 事前に準備されたステートメントの名前で決まります。関数のパラメータは pg_execute() と同じように処理されます。 pg_execute() と同様に、7.4 より前のバージョンの PostgreSQL では動作しません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

statement_name

実行するプリペアドステートメントの名前。"" が指定された場合は 無名ステートメントが実行されます。名前は、事前に pg_prepare()・pg_send_prepare() あるいは PREPARE SQL コマンドで準備されたものである 必要があります。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

戻り値

成功した場合に true 、失敗した場合に 0 を返します。 クエリの結果を確認するには pg_get_result() を使用します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_send_execute() の使用法

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

// 実行するクエリを準備する
if (!pg_connection_busy($dbconn)) {
pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
$res1 = pg_get_result($dbconn);
}

// プリペアドクエリを実行する。 文字列 "Joe's Widgets" は
// エスケープの必要がないことに注意
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
$res2 = pg_get_result($dbconn);
}

// 同じプリペアドクエリを異なるパラメータで実行する
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
$res3 = pg_get_result($dbconn);
}

?>

参考

  • pg_prepare() - 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
  • pg_send_prepare() - 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
  • pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ


指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

  • ≪ pg_send_execute
  • pg_send_query ≫
  • PHP Manual
  • PostgreSQL 関数
  • 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

説明

pg_send_prepare(PgSql\Connection $connection, string $statement_name, string $query): int|bool

指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待ちません。

これは pg_prepare() の非同期バージョンです。 リクエストが受け付けられた場合に true 、そうでない場合に false を返します。コールが成功した後、実際にプリペアドステートメントが 作成されたかどうかを調べるには pg_get_result() を使用します。関数のパラメータは pg_prepare() と同じように処理されます。pg_prepare() と同様、 7.4 より前の PostgreSQL のバージョンでは正しく動作しません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

statement_name

プリペアドステートメントにつける名前。接続内で一意である必要があります。 "" が指定された場合は無名ステートメントが作成され、以前に定義された 無名ステートメントを上書きします。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

戻り値

成功した場合に true 、失敗した場合に 0 を返します。 クエリの結果を確かめるには pg_get_result() を使用します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_send_prepare() の使用法

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

// 実行するクエリを準備する
if (!pg_connection_busy($dbconn)) {
pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
$res1 = pg_get_result($dbconn);
}

// プリペアドクエリを実行する。文字列 "Joe's Widgets" は
// エスケープの必要がないことに注意
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
$res2 = pg_get_result($dbconn);
}

// 同一プリペアドクエリを別のパラメータで実行する
if (!pg_connection_busy($dbconn)) {
pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
$res3 = pg_get_result($dbconn);
}

?>

参考

  • pg_connect() - PostgreSQL 接続をオープンする
  • pg_pconnect() - 持続的な PostgreSQL 接続をオープンする
  • pg_execute() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
  • pg_send_execute() - 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
  • pg_send_query_params() - コマンドとパラメータを分割してサーバーに送信し、その結果を待たない


非同期クエリを送信する

  • ≪ pg_send_prepare
  • pg_send_query_params ≫
  • PHP Manual
  • PostgreSQL 関数
  • 非同期クエリを送信する

pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — 非同期クエリを送信する

説明

pg_send_query(PgSql\Connection $connection, string $query): int|bool

pg_send_query() は、connection に非同期クエリを送信します。pg_query() とは異なり、 PostgreSQL へ一度に複数のクエリを送信することができ、 pg_get_result() を用いて結果を一つずつ取得することが可能です。

スクリプトの実行は、クエリを実行中もブロックされません。 接続がビジーである(すなわち、クエリが実行中である)ことを調べるには、 pg_connection_busy() を使用してください。 クエリは、pg_cancel_query() をコールすることによりキャンセルすることが可能です。

ユーザーは複数のクエリを一度に送信することができますが、 複数のクエリをビジー状態の接続に送信することはできません。 クエリがビジー状態の接続に送信された場合、 最後のクエリが終了するまで待ち、全ての結果は破棄されます。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

query

実行するひとつまたは複数の SQL 文。

クエリ内のデータは 適切にエスケープ する必要があります。

戻り値

成功した場合に true 、失敗した場合に 0 を返します。 クエリの結果を確かめるには pg_get_result() を使用します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_send_query() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
}

$res1 = pg_get_result($dbconn);
echo "First call to pg_get_result(): $res1\n";
$rows1 = pg_num_rows($res1);
echo "$res1 has $rows1 records\n\n";

$res2 = pg_get_result($dbconn);
echo "Second call to pg_get_result(): $res2\n";
$rows2 = pg_num_rows($res2);
echo "$res2 has $rows2 records\n";
?>

上の例の出力は以下となります。

First call to pg_get_result(): Resource id #3
Resource id #3 has 3 records

Second call to pg_get_result(): Resource id #4
Resource id #4 has 1 records

参考

  • pg_query() - クエリを実行する
  • pg_cancel_query() - 非同期クエリを取り消す
  • pg_get_result() - 非同期クエリの結果を取得する
  • pg_connection_busy() - 接続がビジーかどうか調べる


コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

  • ≪ pg_send_query
  • pg_set_client_encoding ≫
  • PHP Manual
  • PostgreSQL 関数
  • コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

説明

pg_send_query_params(PgSql\Connection $connection, string $query, array $params): int|bool

コマンドとパラメータを分割してサーバーに送信します。その結果を待つことは しません。

これは pg_send_query() とほぼ同じですが、パラメータが query とは別に分かれている点が違います。 関数のパラメータは、pg_query_params() によって 完全に制御されます。pg_query_params() と同様、 7.4 より前の PostgreSQL では動作しません。またクエリ文字列には ひとつのコマンドのみを含めることができます。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は $1、$2 などの形式で参照されます。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

戻り値

成功した場合に true 、失敗した場合に 0 を返します。 クエリの結果を確かめるには pg_get_result() を使用します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_send_query_params() の使用法

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

// パラメータを使用する。パラメータにはクォートやエスケープが
// 必要ないことに注意
pg_send_query_params($dbconn, 'select count(*) from authors where city = $1', array('Perth'));

// 基本的な pg_send_query の使用法との比較
$str = pg_escape_string('Perth');
pg_send_query($dbconn, "select count(*) from authors where city = '{$str}'");
?>

参考

  • pg_send_query() - 非同期クエリを送信する


クライアントのエンコーディングを設定する

  • ≪ pg_send_query_params
  • pg_set_error_context_visibility ≫
  • PHP Manual
  • PostgreSQL 関数
  • クライアントのエンコーディングを設定する

pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — クライアントのエンコーディングを設定する

説明

pg_set_client_encoding(PgSql\Connection $connection = ?, string $encoding): int

pg_set_client_encoding() はクライアントの エンコーディングを設定し、成功した場合に 0、エラー時に -1 を 返します。

PostgreSQL は、バックエンドのデータベースエンコーディングを自動的に フロントエンドのエンコーディングに変換します。

注意:

この関数は、以前は pg_setclientencoding() と呼ばれていました。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

encoding

クライアントエンコーディング。以下のうちのひとつです。SQL_ASCII、EUC_JP、 EUC_CN、EUC_KR、EUC_TW、 UNICODE、MULE_INTERNAL、LATINX (X=1...9)、 KOI8、WIN、ALT、SJIS、 BIG5 あるいは WIN1250 。

利用可能なエンコーディングの完全なリストは、使用している PostgreSQL のバージョンに依存します。詳細な情報については PostgreSQL のマニュアルを 参照ください。

戻り値

成功した場合に 0、 エラー時に -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_set_client_encoding() の例

<?php

$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
echo "An error occurred.\n";
exit;
}

// クライアントのエンコーディングを UNICODE にする。
// データは、バックエンドのエンコーディングから自動的に変換される。
pg_set_client_encoding($conn, "UNICODE");

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
echo "An error occurred.\n";
exit;
}

// UTF-8 データを書き出す。
while ($row = pg_fetch_row($result)) {
echo "Author: $row[0] E-mail: $row[1]";
echo "<br />\n";
}

?>

参考

  • pg_client_encoding() - クライアントのエンコーディングを取得する


pg_last_error が返すコンテクストのエラーメッセージのアクセス権を設定する

  • ≪ pg_set_client_encoding
  • pg_set_error_verbosity ≫
  • PHP Manual
  • PostgreSQL 関数
  • pg_last_error が返すコンテクストのエラーメッセージのアクセス権を設定する

pg_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — pg_last_error() が返すコンテクストのエラーメッセージのアクセス権を設定する

説明

pg_set_error_context_visibility(PgSql\Connection $connection, int $visibility): int

pg_last_error() と pg_result_error() が返す、コンテクストのエラーメッセージのアクセス権を設定します

パラメータ

connection

PgSql\Connection クラスのインスタンス。

visibility

必要なアクセス権を指定します: PGSQL_SHOW_CONTEXT_NEVER, PGSQL_SHOW_CONTEXT_ERRORS, PGSQL_SHOW_CONTEXT_ALWAYS

戻り値

直前のアクセス権レベルを返します: PGSQL_SHOW_CONTEXT_NEVER, PGSQL_SHOW_CONTEXT_ERRORS, PGSQL_SHOW_CONTEXT_ALWAYS

例

例1 pg_set_error_context_visibility() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from doesnotexist;");
}

pg_set_error_context_visibility($dbconn, PGSQL_SHOW_CONTEXT_ALWAYS);
$res1 = pg_get_result($dbconn);
echo pg_result_error($res1);
?>

参考

  • pg_last_error() - 特定の接続から直近のエラーメッセージ文字列を取得する
  • pg_result_error() - 結果に関連するエラーメッセージを取得する


pg_last_error および pg_result_error が返すメッセージの詳細度を指定する

  • ≪ pg_set_error_context_visibility
  • pg_socket ≫
  • PHP Manual
  • PostgreSQL 関数
  • pg_last_error および pg_result_error が返すメッセージの詳細度を指定する

pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — pg_last_error() および pg_result_error() が返すメッセージの詳細度を指定する

説明

pg_set_error_verbosity(PgSql\Connection $connection = ?, int $verbosity): int

pg_last_error() および pg_result_error() が返すメッセージの詳細度を指定します。

pg_set_error_verbosity() は詳細度を設定し、その接続の これまでの設定を返します。PGSQL_ERRORS_TERSE モードでは、返されるメッセージは深刻度・概要 および 発生位置のみです。 これはたいていの場合 1 行に収まります。デフォルトのモード （PGSQL_ERRORS_DEFAULT）では、それに加えて何らかの 詳細情報・ヒントあるいは状況フィールドを含みます（これらは複数行に またがる可能性があります）。PGSQL_ERRORS_VERBOSE モードは、有効なフィールドをすべて含みます。詳細度の設定変更内容は それ以降に新しく作成した結果オブジェクトにのみ反映され、既存の 結果オブジェクトには影響を与えません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

verbosity

指定する詳細度。PGSQL_ERRORS_TERSE、 PGSQL_ERRORS_DEFAULT あるいは PGSQL_ERRORS_VERBOSE 。

戻り値

変更前の詳細度レベル。PGSQL_ERRORS_TERSE、 PGSQL_ERRORS_DEFAULT あるいは PGSQL_ERRORS_VERBOSE のいずれかを 返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_set_error_verbosity() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");

if (!pg_connection_busy($dbconn)) {
pg_send_query($dbconn, "select * from doesnotexist;");
}

pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
$res1 = pg_get_result($dbconn);
echo pg_result_error($res1);
?>

参考

  • pg_last_error() - 特定の接続から直近のエラーメッセージ文字列を取得する
  • pg_result_error() - 結果に関連するエラーメッセージを取得する


PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

  • ≪ pg_set_error_verbosity
  • pg_trace ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

説明

pg_socket(PgSql\Connection $connection): resource|false

pg_socket() は、 与えられた PostgreSQL 接続の下層にあるソケットに対応した、 読み取り専用の resource を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

成功した場合は、ソケットのリソース。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


PostgreSQL 接続のトレースを有効にする

  • ≪ pg_socket
  • pg_transaction_status ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続のトレースを有効にする

pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — PostgreSQL 接続のトレースを有効にする

説明

pg_trace(
string $filename,
string $mode = "w",
?PgSql\Connection $connection = null,
int $trace_mode = 0
): bool

pg_trace() は、PostgreSQL フロントエンド/ バックエンド間の通信をデバック用のファイルにトレースすることを有効にします。 このトレース結果を完全に理解するためには、PostgreSQL 通信プロトコルの詳細に 精通している必要があります。

そうでない人にとっても、サーバーに送られたクエリのエラーを トレースすることは有用です。試しに grep '^To backend' trace.log を実行し、実際に PostgreSQL サーバーに送信される クエリを見てみるとよいでしょう。詳細な情報は » PostgreSQL Documentation を 参照ください。

パラメータ

filename

トレースログを書き込むファイルの名前（フルパスを含む）。 fopen() と同じ。

mode

オプションのファイルアクセスモード。fopen() と同じです。

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

trace_mode

オプションのトレースモード。 定数 PGSQL_TRACE_SUPPRESS_TIMESTAMPS と PGSQL_TRACE_REGRESS_MODE を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | trace_mode が追加されました。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_trace() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");

if ($pgsql_conn) {
pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
pg_query("SELECT 1");
pg_untrace($pgsql_conn);
// /tmp/trace.log にバックエンドの通信が記録される
} else {
print pg_last_error($pgsql_conn);
exit;
}
?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • pg_untrace() - PostgreSQL 接続のトレースを無効にする


サーバー上で実行中のトランザクションの状態を返す

  • ≪ pg_trace
  • pg_tty ≫
  • PHP Manual
  • PostgreSQL 関数
  • サーバー上で実行中のトランザクションの状態を返す

pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す

説明

pg_transaction_status(PgSql\Connection $connection): int

サーバー上で実行中のトランザクションの状態を返します。

警告

PostgreSQL 7.3 サーバーで autocommit を off に 設定している場合、pg_transaction_status() は 不正確な値を返します。サーバー側での自動コミット機能は非推奨と されており、最近のバージョンのサーバーでは存在しません。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

戻り値

PGSQL_TRANSACTION_IDLE（アイドル状態）、 PGSQL_TRANSACTION_ACTIVE（コマンドの実行中）、 PGSQL_TRANSACTION_INTRANS（正常なトランザクション内でアイドル状態）、 あるいは PGSQL_TRANSACTION_INERROR（失敗したトランザクション内でアイドル状態） のいずれかを返します。 接続が異常な場合は PGSQL_TRANSACTION_UNKNOWN を返します。 PGSQL_TRANSACTION_ACTIVE が返されるのは、クエリを サーバーに送信した後まだそれが完了していない場合のみです。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_transaction_status() の例

<?php
$dbconn = pg_connect("dbname=publisher") or die("Could not connect");
$stat = pg_transaction_status($dbconn);
if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
echo 'Connection is bad';
} else if ($stat === PGSQL_TRANSACTION_IDLE) {
echo 'Connection is currently idle';
} else {
echo 'Connection is in a transaction state';
}
?>


接続に関する TTY 名を返す

  • ≪ pg_transaction_status
  • pg_unescape_bytea ≫
  • PHP Manual
  • PostgreSQL 関数
  • 接続に関する TTY 名を返す

pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — 接続に関する TTY 名を返す

説明

pg_tty(?PgSql\Connection $connection = null): string

pg_tty() は、指定した PostgreSQL connection インスタンスで、 サーバー側のデバッグ出力が送られる tty 名を返します。

注意:

pg_tty() は現在は使用されません。今はサーバーが TTY 設定を気にする必要がないからです。しかし、過去との互換性を 保持するためにこの関数は残されています。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

connection のデバッグ TTY を文字列で返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_tty() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");

if ($pgsql_conn) {
print "Server debug TTY is: " . pg_tty($pgsql_conn) . "<br/>\n";
} else {
print pg_last_error($pgsql_conn);
exit;
}
?>


bytea 型のバイナリをアンエスケープする

  • ≪ pg_tty
  • pg_untrace ≫
  • PHP Manual
  • PostgreSQL 関数
  • bytea 型のバイナリをアンエスケープする

pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — bytea 型のバイナリをアンエスケープする

説明

pg_unescape_bytea(string $string): string

pg_unescape_bytea() は、bytea 型のデータ文字列を アンエスケープし、エスケープしていない文字列、 場合によってはバイナリデータを返します。

注意:

bytea 型を SELECT した場合、PostgreSQL は '\' で 始まる 8 進数のバイト値（例: \032）を返します。これをユーザーが手動で コンバートすることを期待されています。

この関数は PostgreSQL 7.2 以降のバージョンが必要です。PostgreSQL 7.2.0 および 7.2.1 では、マルチバイトのサポートを有効にした場合は bytea の値をキャストする必要があります。例: INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea); PostgreSQL 7.2.2 以降ではキャストする必要はありません。 クライアントとバックエンドの文字エンコーディングが一致しない場合は 例外で、この場合はマルチバイトストリームエラーが発生します。この エラーを避けるためには bytea 型へのキャストが必要になります。

パラメータ

string

PHP のバイナリ文字列に変換される PostgreSQL の bytea データを含む 文字列。

戻り値

アンエスケープされたデータを文字列で返します。

例

例1 pg_unescape_bytea() の例

<?php
// データベースに接続する
$dbconn = pg_connect('dbname=foo');

// bytea データを取得する
$res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
$raw = pg_fetch_result($res, 'data');

// バイナリに変換し、ブラウザに送信する
header('Content-type: image/jpeg');
echo pg_unescape_bytea($raw);
?>

参考

  • pg_escape_bytea() - bytea フィールドに挿入するために文字列をエスケープする
  • pg_escape_string() - クエリに使う文字列をエスケープする


PostgreSQL 接続のトレースを無効にする

  • ≪ pg_unescape_bytea
  • pg_update ≫
  • PHP Manual
  • PostgreSQL 関数
  • PostgreSQL 接続のトレースを無効にする

pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — PostgreSQL 接続のトレースを無効にする

説明

pg_untrace(?PgSql\Connection $connection = null): true

pg_trace() で開始したトレースを停止します。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_untrace() の例

<?php
$pgsql_conn = pg_connect("dbname=mark host=localhost");

if ($pgsql_conn) {
pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
pg_query("SELECT 1");
pg_untrace($pgsql_conn);
// バックエンド通信のトレースを無効にする
} else {
print pg_last_error($pgsql_conn);
exit;
}
?>

参考

  • pg_trace() - PostgreSQL 接続のトレースを有効にする


テーブルを更新する

  • ≪ pg_untrace
  • pg_version ≫
  • PHP Manual
  • PostgreSQL 関数
  • テーブルを更新する

pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — テーブルを更新する

説明

pg_update(
PgSql\Connection $connection,
string $table_name,
array $values,
array $conditions,
int $flags = PGSQL_DML_EXEC
): string|bool

pg_update() は、 conditions にマッチするレコードを values に更新します。

flags が指定された場合、指定したオプションとともに pg_convert() が data に適用されます。

デフォルトでは、 pg_update() は生の値を渡します。 値はエスケープするか、 flags に PGSQL_DML_ESCAPE オプションを指定しなければいけません。 PGSQL_DML_ESCAPE はパラメータや識別子をクォートし、 エスケープします。 よって、テーブル/カラム名は大文字小文字を区別します。

エスケープやプリペアドクエリであっても、 LIKE, JSON, Array, Regex などのクエリを守れない可能性があることに注意してください。 これらのパラメータはコンテクストに応じて処理されるべきです。 たとえば、値をエスケープ/検証する処理を行うことなどです。

パラメータ

connection

PgSql\Connection クラスのインスタンス。

table_name

行を更新するテーブルの名前。

values

テーブル table_name のフィールド名をキーに、 そしてマッチした対象を更新するデータを値にもつ配列。

conditions

テーブル table_name のフィールド名をキーに、 そして取得対象となる行にマッチするデータを値にもつ配列。

flags

PGSQL_CONV_FORCE_NULL、 PGSQL_DML_NO_CONV、 PGSQL_DML_ESCAPE、 PGSQL_DML_EXEC、 PGSQL_DML_ASYNC あるいは PGSQL_DML_STRING の組み合わせ。 flags の一部に PGSQL_DML_STRING が含まれていた場合、 クエリ文字列が返されます。 PGSQL_DML_NO_CONV あるいは PGSQL_DML_ESCAPE が設定されている場合は、内部的に pg_convert() を呼びません。

戻り値

成功した場合に true を、失敗した場合に false を返します。 flags に PGSQL_DML_STRING が渡された場合は文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pg_update() の例

<?php
$db = pg_connect('dbname=foo');
$data = array('field1'=>'AA', 'field2'=>'BB');

// これは少しだけ安全です。なぜなら、全ての値がエスケープされるからです。
// しかし、PostgreSQL は JSON/Array をサポートしています。これらの型に
// ついてはエスケープされたクエリや、プリペアドクエリでも安全ではありません。
$res = pg_update($db, 'post_log', $_POST, $data);
if ($res) {
echo "データが更新されました: $res\n";
} else {
echo "ユーザーが誤った入力を送信しました。\n";
}
?>

参考

  • pg_convert() - 連想配列の値を、SQL 文として実行可能な形式に変換する


クライアント・プロトコル・サーバーのバージョンを配列で返す

  • ≪ pg_update
  • PgSql\Connection ≫
  • PHP Manual
  • PostgreSQL 関数
  • クライアント・プロトコル・サーバーのバージョンを配列で返す

pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す

説明

pg_version(?PgSql\Connection $connection = null): array

pg_version() はクライアント・プロトコル およびサーバーのバージョンを配列で返します。プロトコルおよびサーバーの バージョンは、PHP が PostgreSQL 7.4 以降とともにコンパイルされている 場合のみ有効です。

詳細なサーバー情報を取得するには pg_parameter_status() を参照ください。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が null, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

戻り値

client, protocol および server のキーとその値を持つ配列を 返します（有効な場合）。

変更履歴

バージョン | 説明
8.1.0 | connection は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | connection は、nullable になりました。

例

例1 pg_version() の例

<?php
$dbconn = pg_connect("host=localhost port=5432 dbname=mary")
or die("Could not connect");

$v = pg_version($dbconn);

echo $v['client'];
?>

上の例の出力は以下となります。

7.4

参考

  • pg_parameter_status() - サーバーのパラメータ設定を検索する


PgSql\Connection クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、pgsql link リソースを置き換える、完全不定形クラスです。

クラス概要

final class PgSql\Connection {
}


The PgSql\Result class

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、pgsql result リソースを置き換える、完全不定形クラスです。

クラス概要

final class PgSql\Result {
}


The PgSql\Lob class

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、pgsql large object リソースを置き換える、完全不定形クラスです。

クラス概要

final class PgSql\Lob {
}


SQLite3

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • SQLite3 — SQLite3 クラス
    • SQLite3::backup — あるデータベースを、別のデータベースにバックアップする
    • SQLite3::busyTimeout — 接続がビジー状態のときのハンドラを設定する
    • SQLite3::changes — 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す
    • SQLite3::close — データベースとの接続を閉じる
    • SQLite3::__construct — SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする
    • SQLite3::createAggregate — SQL の集約関数として使用する PHP 関数を登録する
    • SQLite3::createCollation — SQLのcollate関数として使うPHP関数を登録する
    • SQLite3::createFunction — SQL のスカラー関数として使用する PHP 関数を登録する
    • SQLite3::enableExceptions — 例外のスローを有効にする
    • SQLite3::escapeString — 適切にエスケープされた文字列を返す
    • SQLite3::exec — 指定したデータベースに、結果を返さないクエリを実行する
    • SQLite3::lastErrorCode — 直近で失敗した SQLite リクエストの結果コードを数値で返す
    • SQLite3::lastErrorMsg — 直近で失敗した SQLite リクエストについての英文テキストの説明を返す
    • SQLite3::lastInsertRowID — 直近の INSERT 文でデータベースに追加された行の ID を返す
    • SQLite3::loadExtension — SQLite 拡張ライブラリを読み込む
    • SQLite3::open — SQLite データベースをオープンする
    • SQLite3::openBlob — BLOB を読み取るためのストリームリソースを開く
    • SQLite3::prepare — 実行する SQL 文を準備する
    • SQLite3::query — SQL クエリを実行する
    • SQLite3::querySingle — クエリを実行し、単一の結果を返す
    • SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する
    • SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す
  • SQLite3Exception — SQLite3Exception クラス
  • SQLite3Stmt — SQLite3Stmt クラス
    • SQLite3Stmt::bindParam — パラメータを変数にバインドする
    • SQLite3Stmt::bindValue — パラメータの値を変数にバインドする
    • SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする
    • SQLite3Stmt::close — プリペアドステートメントを閉じる
    • SQLite3Stmt::__construct — SQLite3Stmt オブジェクトを構築する
    • SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す
    • SQLite3Stmt::getSQL — ステートメントのSQLを取得する
    • SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す
    • SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す
    • SQLite3Stmt::reset — プリペアドステートメントをリセットする
  • SQLite3Result — SQLite3Result クラス
    • SQLite3Result::columnName — n 番目のカラムの名前を返す
    • SQLite3Result::columnType — n 番目のカラムの型を返す
    • SQLite3Result::__construct — SQLite3Result を構築する
    • SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する
    • SQLite3Result::finalize — 結果セットを閉じる
    • SQLite3Result::numColumns — 結果セットのカラム数を返す
    • SQLite3Result::reset — 結果セットを最初の行に戻す


  • ≪ SQLite3
  • インストール/設定 ≫
  • PHP Manual
  • SQLite3
  • はじめに

はじめに

SQLite バージョン 3 のデータベースをサポートします。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SQLite3
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

PHP 7.4.0 以降では、 » libsqlite ? 3.7.4 が必須です。 それより前のバージョンでは、バンドルされた libsqlite が代わりに使われていました。


インストール手順

SQLite3 拡張モジュールはデフォルトで有効になっています。 無効にするには、コンパイル時に --without-sqlite3 を指定します。

Windows ユーザーは、この拡張モジュールを使用するには php_sqlite3.dll を有効にしなければなりません。 この DLL は、Windows 版 PHP に含まれています。

注意: PHP 7.4.0 以降の、Windows における追加セットアップ

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libsqlite3.dll.


実行時設定

php.ini の設定により動作が変化します。

SQLite3 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sqlite3.extension_dir | "" | INI_SYSTEM |
sqlite3.defensive | 1 | INI_USER | PHP 7.2.17 ,7.3.4 以降、かつ libsqlite ? 3.26.0 でビルドした場合に利用可能 PHP 8.2.0 より前のバージョンでは、この値は INI_SYSTEM のモードでのみ変更可能でした。

以下に設定ディレクティブに関する 簡単な説明を示します。

sqlite3.extension_dir string

SQLite 用のロードモジュールが存在するディレクトリへのパス。

sqlite3.defensive bool

defensive フラグを有効にした場合、データベースファイルを意図的に破壊することができる通常のSQLの機能が無効になります。これにより、スキーマ や シャドウテーブル (e.g FTS データテーブル) や sqlite_dbpage 仮想テーブルに直接に直接書き込むことを禁止します。 この php.ini 設定は、libsqlite ? 3.26.0 以降でビルドした場合だけ有効です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SQLITE3_ASSOC (int)
SQLite3_result::fetchArray() が返す結果セットが、 カラム名をインデックスとする配列であることを指定します。
SQLITE3_NUM (int)
SQLite3_result::fetchArray() が返す結果セットが、 カラム番号をインデックスとする配列であることを指定します。 カラム番号は 0 からはじまります。
SQLITE3_BOTH (int)
SQLite3_result::fetchArray() が返す結果セットが、 カラム名とカラム番号の両方をインデックスとする配列であることを指定します。 カラム番号は 0 からはじまります。
SQLITE3_INTEGER (int)
SQLite3 INTEGER 型を表します。
SQLITE3_FLOAT (int)
SQLite3 REAL (FLOAT) 型を表します。
SQLITE3_TEXT (int)
SQLite3 TEXT 型を表します。
SQLITE3_BLOB (int)
SQLite3 BLOB 型を表します。
SQLITE3_NULL (int)
SQLite3 NULL 型を表します。
SQLITE3_OPEN_READONLY (int)
SQLite3 データベースを読み込み専用でオープンすることを指定します。
SQLITE3_OPEN_READWRITE (int)
SQLite3 データベースを読み書き両用でオープンすることを指定します。
SQLITE3_OPEN_CREATE (int)
データベースが存在しない場合に SQLite3 データベースを新規作成することを指定します。
SQLITE3_DETERMINISTIC (int)
SQLite3::createFunction() で作成する関数が決定論的であることを指定します。 つまり、単一のSQL文の範囲では、同じ入力に対して常に同じ結果が返されるということです。 (PHP 7.1.4 以降で使用可能)


SQLite3 クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SQLite 3 データベースとのインターフェイスとなるクラスです。

クラス概要

class SQLite3 {
/* 定数 */
public const int OK;
public const int DENY;
public const int IGNORE;
public const int CREATE_INDEX;
public const int CREATE_TABLE;
public const int CREATE_TEMP_INDEX;
public const int CREATE_TEMP_TABLE;
public const int CREATE_TEMP_TRIGGER;
public const int CREATE_TEMP_VIEW;
public const int CREATE_TRIGGER;
public const int CREATE_VIEW;
public const int DELETE;
public const int DROP_INDEX;
public const int DROP_TABLE;
public const int DROP_TEMP_INDEX;
public const int DROP_TEMP_TABLE;
public const int DROP_TEMP_TRIGGER;
public const int DROP_TEMP_VIEW;
public const int DROP_TRIGGER;
public const int DROP_VIEW;
public const int INSERT;
public const int PRAGMA;
public const int READ;
public const int SELECT;
public const int TRANSACTION;
public const int UPDATE;
public const int ATTACH;
public const int DETACH;
public const int ALTER_TABLE;
public const int REINDEX;
public const int ANALYZE;
public const int CREATE_VTABLE;
public const int DROP_VTABLE;
public const int FUNCTION;
public const int SAVEPOINT;
public const int COPY;
public const int RECURSIVE;
/* メソッド */
public __construct(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = "")
public backup(SQLite3 $destination, string $sourceDatabase = "main", string $destinationDatabase = "main"): bool
public busyTimeout(int $milliseconds): bool
public changes(): int
public close(): bool
public createAggregate(
string $name,
callable $stepCallback,
callable $finalCallback,
int $argCount = -1
): bool
public createCollation(string $name, callable $callback): bool
public createFunction(
string $name,
callable $callback,
int $argCount = -1,
int $flags = 0
): bool
public enableExceptions(bool $enable = false): bool
public static escapeString(string $string): string
public exec(string $query): bool
public lastErrorCode(): int
public lastErrorMsg(): string
public lastInsertRowID(): int
public loadExtension(string $name): bool
public open(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = ""): void
public openBlob(
string $table,
string $column,
int $rowid,
string $database = "main",
int $flags = SQLITE3_OPEN_READONLY
): resource|false
public prepare(string $query): SQLite3Stmt|false
public query(string $query): SQLite3Result|false
public querySingle(string $query, bool $entireRow = false): mixed
public setAuthorizer(?callable $callback): bool
public static version(): array
}

定義済み定数

SQLite3::OK

SQLite3::DENY

SQLite3::IGNORE

SQLite3::CREATE_INDEX

SQLite3::CREATE_TABLE

SQLite3::CREATE_TEMP_INDEX

SQLite3::CREATE_TEMP_TABLE

SQLite3::CREATE_TEMP_TRIGGER

SQLite3::CREATE_TEMP_VIEW

SQLite3::CREATE_TRIGGER

SQLite3::CREATE_VIEW

SQLite3::DELETE

SQLite3::DROP_INDEX

SQLite3::DROP_TABLE

SQLite3::DROP_TEMP_INDEX

SQLite3::DROP_TEMP_TABLE

SQLite3::DROP_TEMP_TRIGGER

SQLite3::DROP_TEMP_VIEW

SQLite3::DROP_TRIGGER

SQLite3::DROP_VIEW

SQLite3::INSERT

SQLite3::PRAGMA

SQLite3::READ

SQLite3::SELECT

SQLite3::TRANSACTION

SQLite3::UPDATE

SQLite3::ATTACH

SQLite3::DETACH

SQLite3::ALTER_TABLE

SQLite3::REINDEX

SQLite3::ANALYZE

SQLite3::CREATE_VTABLE

SQLite3::DROP_VTABLE

SQLite3::FUNCTION

SQLite3::SAVEPOINT

SQLite3::COPY

SQLite3::RECURSIVE

目次

  • SQLite3::backup — あるデータベースを、別のデータベースにバックアップする
  • SQLite3::busyTimeout — 接続がビジー状態のときのハンドラを設定する
  • SQLite3::changes — 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す
  • SQLite3::close — データベースとの接続を閉じる
  • SQLite3::__construct — SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする
  • SQLite3::createAggregate — SQL の集約関数として使用する PHP 関数を登録する
  • SQLite3::createCollation — SQLのcollate関数として使うPHP関数を登録する
  • SQLite3::createFunction — SQL のスカラー関数として使用する PHP 関数を登録する
  • SQLite3::enableExceptions — 例外のスローを有効にする
  • SQLite3::escapeString — 適切にエスケープされた文字列を返す
  • SQLite3::exec — 指定したデータベースに、結果を返さないクエリを実行する
  • SQLite3::lastErrorCode — 直近で失敗した SQLite リクエストの結果コードを数値で返す
  • SQLite3::lastErrorMsg — 直近で失敗した SQLite リクエストについての英文テキストの説明を返す
  • SQLite3::lastInsertRowID — 直近の INSERT 文でデータベースに追加された行の ID を返す
  • SQLite3::loadExtension — SQLite 拡張ライブラリを読み込む
  • SQLite3::open — SQLite データベースをオープンする
  • SQLite3::openBlob — BLOB を読み取るためのストリームリソースを開く
  • SQLite3::prepare — 実行する SQL 文を準備する
  • SQLite3::query — SQL クエリを実行する
  • SQLite3::querySingle — クエリを実行し、単一の結果を返す
  • SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する
  • SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す


あるデータベースを、別のデータベースにバックアップする

  • ≪ SQLite3
  • SQLite3::busyTimeout ≫
  • PHP Manual
  • SQLite3
  • あるデータベースを、別のデータベースにバックアップする

SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — あるデータベースを、別のデータベースにバックアップする

説明

public SQLite3::backup(SQLite3 $destination, string $sourceDatabase = "main", string $destinationDatabase = "main"): bool

SQLite3::backup() は、あるデータベースの内容を別のデータベースにコピーし、 コピー先のデータベースの内容を上書きします。 このメソッドは、データベースのバックアップを作成したり、 インメモリのデータベースを永続的なファイルにコピーしたり、その逆を行う場合に便利です。

ヒント

SQLite 3.27.0 (2019-02-07) 以降のバージョンでは、 データベースを新しいファイルにバックアップするSQLとして VACUUM INTO 'file.db'; も使えます。

パラメータ

destination

SQLite3::open() でオープンされたデータベース接続

sourceDatabase

メインデータベースの場合、データベース名は "main" です。 一時的なデータベースの場合は、"temp" になります。 また、ATTACH 文の AS キーワードの後に指定された名前が使えます。

destinationDatabase

sourceDatabase に似ていますが、 destination で接続したコピー先のデータベースを表します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 既存のデータベースをバックアップする

<?php
// $conn は、既にオープンされた sqlite3 データベースへの接続です。

$backup = new SQLite3('backup.sqlite');
$conn->backup($backup);
?>


接続がビジー状態のときのハンドラを設定する

  • ≪ SQLite3::backup
  • SQLite3::changes ≫
  • PHP Manual
  • SQLite3
  • 接続がビジー状態のときのハンドラを設定する

SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — 接続がビジー状態のときのハンドラを設定する

説明

public SQLite3::busyTimeout(int $milliseconds): bool

ビジーハンドラを設定します。 これは、データベースのロックが解除されるかあるいはタイムアウトに達するまでスリープさせます。

パラメータ

milliseconds

スリープさせる時間 (ミリ秒)。この値をゼロ以下にすると、 すでに設定されているタイムアウトハンドラを無効にします。

戻り値

成功した場合に true、失敗した場合に false を返します


直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

  • ≪ SQLite3::busyTimeout
  • SQLite3::close ≫
  • PHP Manual
  • SQLite3
  • 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

説明

public SQLite3::changes(): int

直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の SQL 文で変更 (あるいは挿入、削除) された行の数を表す int 値を返します。

例

例1 SQLite3::changes() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
if ($query) {
echo '変更された行の数: ', $db->changes();
}
?>


データベースとの接続を閉じる

  • ≪ SQLite3::changes
  • SQLite3::__construct ≫
  • PHP Manual
  • SQLite3
  • データベースとの接続を閉じる

SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — データベースとの接続を閉じる

説明

public SQLite3::close(): bool

データベースとの接続を閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SQLite3::close() の例

<?php
$db = new SQLite3('mysqlitedb.db');
$db->close();
?>


SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

  • ≪ SQLite3::close
  • SQLite3::createAggregate ≫
  • PHP Manual
  • SQLite3
  • SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

説明

public SQLite3::__construct(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = "")

SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンします。 暗号化込みでビルドされている場合は、キーの使用を試みます。

パラメータ

filename

SQLite データベースへのパス。インメモリデータベースを使う場合は :memory: を指定します。 filename に空文字列を指定すると、 プライベート、かつ一時的なデータベースがディスク上に作成されます。 このプライベートなデータベースは、データベース接続が閉じられるとすぐに自動的に削除されます。

flags

SQLite データベースのオープン方法を指定するフラグ。 デフォルトでは SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE を使用してオープンします。

  • SQLITE3_OPEN_READONLY: データベースを読み込み専用でオープンする

  • SQLITE3_OPEN_READWRITE: データベースを読み書き共用でオープンする

  • SQLITE3_OPEN_CREATE: データベースが存在しない場合は作成する

encryptionKey

オプションの暗号キー。SQLite データベースの暗号化と復号に使用します。 暗号化モジュールがインストールされていない場合は、このパラメータは何の影響も及ぼしません。

エラー / 例外

失敗した場合に Exception をスローします。

変更履歴

バージョン | 説明
7.0.10 | filename は、空文字列を指定できるようになりました。 この場合、プライベート、かつ一時的なデータベースがディスク上に作成されます。

例

例1 SQLite3::__construct() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$db->exec('CREATE TABLE foo (bar TEXT)');
$db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

$result = $db->query('SELECT bar FROM foo');
var_dump($result->fetchArray());
?>


SQL の集約関数として使用する PHP 関数を登録する

  • ≪ SQLite3::__construct
  • SQLite3::createCollation ≫
  • PHP Manual
  • SQLite3
  • SQL の集約関数として使用する PHP 関数を登録する

SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — SQL の集約関数として使用する PHP 関数を登録する

説明

public SQLite3::createAggregate(
string $name,
callable $stepCallback,
callable $finalCallback,
int $argCount = -1
): bool

SQL の集約関数として使用する PHP 関数を登録します。 これは SQL 文の中で使用されるものです。

パラメータ

name

作成あるいは再定義したい SQL 集約関数の名前。

stepCallback

結果セットの各行ごとにコールされるコールバック関数。 この関数で結果を集約し、集約処理のコンテキストに保存すべきです。

このコールバック関数は、以下のように定義すべきです:

step(
mixed $context,
int $rownumber,
mixed $value,
mixed ...$values
): mixed
context

最初の行では null です。 2行目以降は、step 関数から返された値をとります。 これは、集約の状況を管理するのに使います。

rownumber

現在の行番号

value

集約に渡されるはじめの引数

values

集約に渡されるふたつめ以降の引数

この関数の戻り値は、 次のステップで呼ばれる際、または finalize 関数での context の引数として使われます。

finalCallback

各行からの "段階的に処理された" データを集約するコールバック関数です。 いったん全データが処理されると、この関数が呼ばれます。 集約処理のコンテキストからデータを取り出し、結果を返すべきです。 このコールバック関数は SQLite が理解する型を返します。 (例: スカラー型)

このコールバック関数は、以下のように定義すべきです:

fini(mixed $context, int $rownumber): mixed
context

最後に呼ばれた step 関数から返された値を保持します。

rownumber

常に 0.

この関数の戻り値は、集約の戻り値として使われます。

argCount

SQL 集約関数が受け取るパラメータの数。 負の値を指定すると、SQL 集約関数は任意の数の引数を受け取るようになります。

戻り値

集約関数の作成に成功した場合に true、失敗した場合に false を返します

例

例1 max_length 集約関数の例

<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = new SQLite3(':memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
$insert->bindValue(1, $str);
$insert->execute();
}
$insert = null;

function max_len_step($context, $rownumber, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
return $context;
}

function max_len_finalize($context, $rownumber)
{
return $context === null ? 0 : $context;
}

$db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

var_dump($db->querySingle('SELECT max_len(a) from strings'));
?>

上の例の出力は以下となります。

int(5)

この例では、テーブルのカラムに入っている一番長い文字列を集約する関数を作っています。 1行ごとに、max_len_step 関数が呼ばれ、 $context パラメータが渡されます。 context パラメータ は他のPHPの変数のように振る舞いますし、配列やオブジェクトを格納することさえできます。 この例では、単にこれまで見てきたものの中から一番大きな長さを保持するのに使っています。 つまり、$string が現在の最大値より大きな長さをもっていたら、 context を新しい最大値に更新しています。

全ての行を処理し終わったら、SQLite は 集約結果を決めるために max_len_finalize 関数を呼び出します。 ここでは、$context で見つかったデータを基にして、 ある種の計算を行うことができます。 私達のシンプルな例では、結果を段階的に計算してきているので、 単に context に入っている値を返すだけで済みます。

ヒント

値のコピーを context に保存し、一番最後に処理することは推奨できません。 なぜなら、SQLite がクエリを処理するのにたくさんのメモリを使うことになるからです。 - 100万行の情報がメモリに格納されていたとして、 それぞれの行が32バイトの長さを持っていたとすると、 どれくらいのメモリが必要になるのかを考えてみてください。

ヒント

SQLite のネイティブなSQL関数を上書きするために SQLite3::createAggregate() を使うことができます。


SQLのcollate関数として使うPHP関数を登録する

  • ≪ SQLite3::createAggregate
  • SQLite3::createFunction ≫
  • PHP Manual
  • SQLite3
  • SQLのcollate関数として使うPHP関数を登録する

SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — SQLのcollate関数として使うPHP関数を登録する

説明

public SQLite3::createCollation(string $name, callable $callback): bool

SQL文の中でcollate関数として使うPHP関数、またはユーザー定義の関数を登録します。

パラメータ

name

作成、または再定義するSQL collate 関数の名前

callback

collation の振る舞いを定義する、PHP関数または、 コールバックとして適用するユーザー定義関数。 2つの値を受けとり、strcmp() 関数が返すのと同じ値を返します。つまり、 はじめの文字列が前の文字列より前にソートされる場合に-1、 後にソートされる場合に1、等しい場合に0を返します。

この関数は、以下のように定義されるべきです:

collation(mixed $value1, mixed $value2): int

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SQLite3::createCollation() の例

SQLite3 データベースの中で、シーケンスを並べる strnatcmp() 関数を登録します。

<?php

$db = new SQLite3(":memory:");
$db->exec("CREATE TABLE test (col1 string)");
$db->exec("INSERT INTO test VALUES ('a1')");
$db->exec("INSERT INTO test VALUES ('a10')");
$db->exec("INSERT INTO test VALUES ('a2')");

$db->createCollation('NATURAL_CMP', 'strnatcmp');

$defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
$naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

echo "default:\n";
while ($row = $defaultSort->fetchArray()){
echo $row['col1'], "\n";
}

echo "\nnatural:\n";
while ($row = $naturalSort->fetchArray()){
echo $row['col1'], "\n";
}

$db->close();

?>

上の例の出力は以下となります。

default:
a1
a10
a2

natural:
a1
a2
a10

参考

  • SQLite collation ドキュメント: » http://sqlite.org/datatype3.html#collation


SQL のスカラー関数として使用する PHP 関数を登録する

  • ≪ SQLite3::createCollation
  • SQLite3::enableExceptions ≫
  • PHP Manual
  • SQLite3
  • SQL のスカラー関数として使用する PHP 関数を登録する

SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — SQL のスカラー関数として使用する PHP 関数を登録する

説明

public SQLite3::createFunction(
string $name,
callable $callback,
int $argCount = -1,
int $flags = 0
): bool

SQL のスカラー関数として使用する PHP 関数を登録します。 これは SQL 文の中で使用されるものです。

パラメータ

name

作成あるいは再定義したい SQL 関数の名前。

callback

コールバックとして指定する、 PHP の関数あるいはユーザー定義関数の名前。 これが SQL 関数の振る舞いを定義します。

この関数は、以下のように定義されるべきです:

callback(mixed $value, mixed ...$values): mixed
value

SQL 関数に渡される最初の引数

values

SQL 関数に渡されるふたつめ以降の引数

argCount

SQL 関数が受け取るパラメータの数。 -1 を指定すると、SQL 関数は任意の数の引数を受け取るようになります。

flags

フラグのビット単位の組み合わせ。 現状では、 SQLITE3_DETERMINISTIC だけがサポートされています。 これは、単一のSQLの範囲の中では、同じ入力を与えると常に同じ結果が返るということを指定します。

戻り値

関数の作成に成功した場合に true、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.4 | flags パラメータが追加されました。

例

例1 SQLite3::createFunction() の例

<?php
function my_udf_md5($string) {
return hash('md5', $string);
}

$db = new SQLite3('mysqlitedb.db');
$db->createFunction('my_udf_md5', 'my_udf_md5');

var_dump($db->querySingle('SELECT my_udf_md5("test")'));
?>

上の例の出力は、 たとえば以下のようになります。

string(32) "098f6bcd4621d373cade4e832627b4f6"


例外のスローを有効にする

  • ≪ SQLite3::createFunction
  • SQLite3::escapeString ≫
  • PHP Manual
  • SQLite3
  • 例外のスローを有効にする

SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — 例外のスローを有効にする

説明

public SQLite3::enableExceptions(bool $enable = false): bool

SQLite3 が、エラー時に警告や例外をスローするかどうかを制御します。

パラメータ

enable

true の場合、 SQLite3 のインスタンスと、 SQLite3Stmt および SQLite3Result から派生したインスタンスは、エラー時に例外をスローします

false の場合、 SQLite3 のインスタンスと、 SQLite3Stmt および SQLite3Result から派生したインスタンスは、エラー時に警告を発生させます。

どちらのモードであっても、エラーコードやメッセージがもしあれば、 SQLite3::lastErrorCode() と SQLite3::lastErrorMsg() で利用できます。

戻り値

古い値を返します。つまり、例外が有効であったなら true そうでなければ false を返します。

変更履歴

バージョン | 説明
8.3.0 | enable を false にして SQLite3::enableExceptions() をコールすると、E_DEPRECATED が発生するようになりました。

例

例1 SQLite3::enableExceptions() の例

<?php
$sqlite = new SQLite3(':memory:');
try {
$sqlite->exec('create table foo');
$sqlite->enableExceptions(true);
$sqlite->exec('create table bar');
} catch (Exception $e) {
echo 'Caught exception: ' . $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Warning: SQLite3::exec(): near "foo": syntax error in example.php on line 4
Caught exception: near "bar": syntax error


適切にエスケープされた文字列を返す

  • ≪ SQLite3::enableExceptions
  • SQLite3::exec ≫
  • PHP Manual
  • SQLite3
  • 適切にエスケープされた文字列を返す

SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — 適切にエスケープされた文字列を返す

説明

public static SQLite3::escapeString(string $string): string

SQL 文の中で使えるよう適切にエスケープされた文字列を返します。

警告

この関数は (まだ)バイナリデータ対応ではありません!

BLOB フィールドには NUL 文字が含まれる可能性があります。BLOB フィールドを適切に処理するには、かわりに SQLite3Stmt::bindParam() を用いましょう。

パラメータ

string

エスケープしたい文字列。

戻り値

SQL 文の中で安全に使えるよう適切にエスケープされた文字列を返します。

注意

警告

SQLite クエリの文字列をクォートする際に addslashes() を使っては いけません。 予期せぬ結果を引き起こしてしまいます。


指定したデータベースに、結果を返さないクエリを実行する

  • ≪ SQLite3::escapeString
  • SQLite3::lastErrorCode ≫
  • PHP Manual
  • SQLite3
  • 指定したデータベースに、結果を返さないクエリを実行する

SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — 指定したデータベースに、結果を返さないクエリを実行する

説明

public SQLite3::exec(string $query): bool

指定したデータベースに、結果を返さないクエリを実行します。

注意: SQLite3 は、クエリの実行中に » 一時ファイル を作る必要があるかもしれません。 よって、それぞれのディレクトリは書き込み可能でなければならない可能性があります。

パラメータ

query

実行したい SQL クエリ (通常は INSERT、UPDATE あるいは DELETE クエリ)。

戻り値

クエリが成功した場合に true、失敗した場合に false を返します。

例

例1 SQLite3::exec() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$db->exec('CREATE TABLE bar (bar TEXT)');
?>


直近で失敗した SQLite リクエストの結果コードを数値で返す

  • ≪ SQLite3::exec
  • SQLite3::lastErrorMsg ≫
  • PHP Manual
  • SQLite3
  • 直近で失敗した SQLite リクエストの結果コードを数値で返す

SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — 直近で失敗した SQLite リクエストの結果コードを数値で返す

説明

public SQLite3::lastErrorCode(): int

直近で失敗した SQLite リクエストの結果コードを数値で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近で失敗した SQLite リクエストの結果コードを数値で返します。


直近で失敗した SQLite リクエストについての英文テキストの説明を返す

  • ≪ SQLite3::lastErrorCode
  • SQLite3::lastInsertRowID ≫
  • PHP Manual
  • SQLite3
  • 直近で失敗した SQLite リクエストについての英文テキストの説明を返す

SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — 直近で失敗した SQLite リクエストについての英文テキストの説明を返す

説明

public SQLite3::lastErrorMsg(): string

直近で失敗した SQLite リクエストについての英文テキストの説明を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近で失敗した SQLite リクエストについての英文テキストの説明を返します。


直近の INSERT 文でデータベースに追加された行の ID を返す

  • ≪ SQLite3::lastErrorMsg
  • SQLite3::loadExtension ≫
  • PHP Manual
  • SQLite3
  • 直近の INSERT 文でデータベースに追加された行の ID を返す

SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — 直近の INSERT 文でデータベースに追加された行の ID を返す

説明

public SQLite3::lastInsertRowID(): int

直近の INSERT 文でデータベースに追加された行の ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の INSERT 文でデータベースに追加された行の ID を返します。 現在の接続で、rowid テーブルへの INSERT が成功しなかったことがある場合は、 SQLite3::lastInsertRowID() は 0 を返します。


SQLite 拡張ライブラリを読み込む

  • ≪ SQLite3::lastInsertRowID
  • SQLite3::open ≫
  • PHP Manual
  • SQLite3
  • SQLite 拡張ライブラリを読み込む

SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — SQLite 拡張ライブラリを読み込む

説明

public SQLite3::loadExtension(string $name): bool

SQLite 拡張ライブラリを読み込みます。

パラメータ

name

読み込みたいライブラリの名前。ライブラリは、設定オプション sqlite3.extension_dir で指定したディレクトリになければなりません。

戻り値

拡張ライブラリの読み込みに成功した場合に true、 失敗した場合に false を返します。

例

例1 SQLite3::loadExtension() の例

<?php
$db = new SQLite3('mysqlitedb.db');
$db->loadExtension('libagg.so');
?>


SQLite データベースをオープンする

  • ≪ SQLite3::loadExtension
  • SQLite3::openBlob ≫
  • PHP Manual
  • SQLite3
  • SQLite データベースをオープンする

SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — SQLite データベースをオープンする

説明

public SQLite3::open(string $filename, int $flags = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string $encryptionKey = ""): void

SQLite 3 データベースをオープンします。 暗号化込みでビルドされている場合は、キーの使用を試みます。

パラメータ

filename

SQLite データベースへのパス。インメモリデータベースを使う場合は :memory: を指定します。

flags

SQLite データベースのオープン方法を指定するフラグ。 デフォルトでは SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE を使用してオープンします。

  • SQLITE3_OPEN_READONLY: データベースを読み込み専用でオープンする

  • SQLITE3_OPEN_READWRITE: データベースを読み書き共用でオープンする

  • SQLITE3_OPEN_CREATE: データベースが存在しない場合は作成する

encryptionKey

オプションの暗号キー。SQLite データベースの暗号化と復号に使用します。 暗号化モジュールがインストールされていない場合は、このパラメータは何の影響も及ぼしません。

戻り値

値を返しません。

例

例1 SQLite3::open() の例

<?php
/**
* SQLite3 クラスを継承して __construct を変更し、
* open メソッドで DB を初期化します
*/
class MyDB extends SQLite3
{
function __construct()
{
$this->open('mysqlitedb.db');
}
}

$db = new MyDB();

$db->exec('CREATE TABLE foo (bar STRING)');
$db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

$result = $db->query('SELECT bar FROM foo');
var_dump($result->fetchArray());
?>


BLOB を読み取るためのストリームリソースを開く

  • ≪ SQLite3::open
  • SQLite3::prepare ≫
  • PHP Manual
  • SQLite3
  • BLOB を読み取るためのストリームリソースを開く

SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — BLOB を読み取るためのストリームリソースを開く

説明

public SQLite3::openBlob(
string $table,
string $column,
int $rowid,
string $database = "main",
int $flags = SQLITE3_OPEN_READONLY
): resource|false

BLOB を読み書きするためのストリームリソースを開きます。 これは、以下によって選択されます:

SELECT column FROM database.table WHERE rowid = rowid

注意: ストリームに書き込むことで、BLOBのサイズを変更することは不可能です。 BLOB のサイズを望んだサイズに設定するには、代わりに UPDATE 文を実行するか、 SQLite の zeroblob() 関数を使ってください。

パラメータ

table

テーブル名

column

カラム名

rowid

行ID

database

DB のシンボリック名

flags

SQLITE3_OPEN_READONLY または SQLITE3_OPEN_READWRITE を指定します。 それぞれ、読み取り専用でストリームを開くか、 読み取りと書き込みができるようにストリームを開きます。

戻り値

ストリームリソースを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.2.0 | flags が追加されました。 BLOB に書き込むことができます。これより前のバージョンでは、読み取りのみがサポートされていました。

例

例1 SQLite3::openBlob() の例

<?php
$conn = new SQLite3(':memory:');
$conn->exec('CREATE TABLE test (text text)');
$conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
$stream = $conn->openBlob('test', 'text', 1);
echo stream_get_contents($stream);
fclose($stream); // mandatory, otherwise the next line would fail
$conn->close();
?>

上の例の出力は以下となります。

Lorem ipsum

例2 インクリメンタルにBLOBに書き込む

<?php
$conn = new SQLite3(':memory:');
$conn->exec('CREATE TABLE test (text text)');
$conn->exec("INSERT INTO test VALUES (zeroblob(36))");
$stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
for ($i = 0; $i < 3; $i++) {
fwrite($stream, "Lorem ipsum\n");
}
fclose($stream);
echo $conn->querySingle("SELECT text FROM test");
$conn->close();
?>

上の例の出力は以下となります。

Lorem ipsum
Lorem ipsum
Lorem ipsum


実行する SQL 文を準備する

  • ≪ SQLite3::openBlob
  • SQLite3::query ≫
  • PHP Manual
  • SQLite3
  • 実行する SQL 文を準備する

SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — 実行する SQL 文を準備する

説明

public SQLite3::prepare(string $query): SQLite3Stmt|false

実行する SQL 文を準備し、SQLite3Stmt オブジェクトを返します。

パラメータ

query

準備したい SQL クエリ。

戻り値

成功した場合に SQLite3Stmt オブジェクト、失敗した場合に false を返します。

例

例1 SQLite3::prepare() の例

<?php
unlink('mysqlitedb.db');
$db = new SQLite3('mysqlitedb.db');

$db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
$db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

$stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
$stmt->bindValue(':id', 1, SQLITE3_INTEGER);

$result = $stmt->execute();
var_dump($result->fetchArray());
?>

参考

  • SQLite3Stmt::paramCount() - プリペアドステートメント内のパラメータの数を返す
  • SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
  • SQLite3Stmt::bindParam() - パラメータを変数にバインドする


SQL クエリを実行する

  • ≪ SQLite3::prepare
  • SQLite3::querySingle ≫
  • PHP Manual
  • SQLite3
  • SQL クエリを実行する

SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — SQL クエリを実行する

説明

public SQLite3::query(string $query): SQLite3Result|false

SQL クエリを実行し、SQLite3Result オブジェクトを返します。 クエリが(DML文のように)結果を生成しない場合は、 返される SQLite3Result オブジェクトは役に立ちません。 そのようなクエリでは、SQLite3::exec() を代わりに使ってください。

パラメータ

query

実行したい SQL クエリ。

戻り値

SQLite3Result オブジェクトを返します。 失敗した場合に false を返します

例

例1 SQLite3::query() の例

<?php
$db = new SQLite3('mysqlitedb.db');

$results = $db->query('SELECT bar FROM foo');
while ($row = $results->fetchArray()) {
var_dump($row);
}
?>


クエリを実行し、単一の結果を返す

  • ≪ SQLite3::query
  • SQLite3::setAuthorizer ≫
  • PHP Manual
  • SQLite3
  • クエリを実行し、単一の結果を返す

SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — クエリを実行し、単一の結果を返す

説明

public SQLite3::querySingle(string $query, bool $entireRow = false): mixed

クエリを実行し、単一の結果を返します。

パラメータ

query

実行したい SQL クエリ。

entireRow

デフォルトでは、querySingle() はクエリが返す結果の最初のカラムの値を返します。 entireRow が true の場合は、最初の行全体を配列で返します。

戻り値

結果の最初のカラムの値あるいは最初の行全体の配列 (entireRow が true の場合) を返します。

クエリ自体は有効であるけれども結果が返されなかった場合の戻り値は、 entireRow が false なら null、 そうでなければ空の配列となります。

クエリが無効な場合やクエリの実行に失敗した場合は false を返します。

例

例1 SQLite3::querySingle() の例

<?php
$db = new SQLite3('mysqlitedb.db');

var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "Scott"
Array
(
    [username] => Scott
    [email] => scott@example.com
)


SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

  • ≪ SQLite3::querySingle
  • SQLite3::version ≫
  • PHP Manual
  • SQLite3
  • SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

説明

public SQLite3::setAuthorizer(?callable $callback): bool

SQLite に対して毎回アクション(読み取り、削除、更新など) が実行される度に呼び出されるコールバックを設定します。 これは信頼できないソースがSQL文を準備する時に、 自分たちが許可していないデータにアクセスさせないとか、 データベースに損害を与える不正なSQL文を実行させないといった用途に使います。 たとえば、アプリケーションはデータベースの評価の際は 任意のSQL文の実行を許可しています。しかし、 データベースに対する変更は許可したくありません。 ユーザーが入力したSQL文が準備される間に、 authorizer が割って入り、SELECT 文以外のSQL文を許可しないようにできます。

authorizer コールバックは、 SQLite が文を準備するたびに複数回呼ばれる可能性があります。 SELECT や UPDATE 文は 個別のカラムが読み取られたり、更新されたりするたびに authorizer を呼び出します。

authorizer は引数を5つまで指定して呼び出すことが出来ます。 最初の引数は常に与えられます。 これは SQLite3 の定数に一致する int の値(アクションコード) です。 それ以外の引数は、アクションによっては与えられないことがあります。 以下の表が、アクションに応じた2番目と3番目の引数に関する説明を記しています:

アクションコードと引数の一覧
アクション | 第2引数 | 第3引数
sqlite3::create_index | インデックス名 | テーブル名
sqlite3::create_table | テーブル名 | null
sqlite3::create_temp_index | インデックス名 | テーブル名
sqlite3::create_temp_table | テーブル名 | null
sqlite3::create_temp_trigger | トリガ名 | テーブル名
sqlite3::create_temp_view | view名 | null
sqlite3::create_trigger | トリガ名 | テーブル名
sqlite3::create_view | view名 | null
sqlite3::delete | テーブル名 | null
sqlite3::drop_index | インデックス名 | テーブル名
sqlite3::drop_table | テーブル名 | null
sqlite3::drop_temp_index | インデックス名 | テーブル名
sqlite3::drop_temp_table | テーブル名 | null
sqlite3::drop_temp_trigger | トリガ名 | テーブル名
sqlite3::drop_temp_view | view名 | null
sqlite3::drop_trigger | トリガ名 | テーブル名
sqlite3::drop_view | view名 | null
sqlite3::insert | テーブル名 | null
sqlite3::pragma | プラグマの名前 | プラグマに渡す最初の引数。もしくは null
sqlite3::read | テーブル名 | カラム名
sqlite3::select | null | null
sqlite3::transaction | 操作 | null
sqlite3::update | テーブル名 | カラム名
sqlite3::attach | ファイル名 | null
sqlite3::detach | データベース名 | null
sqlite3::alter_table | データベース名 | テーブル名
sqlite3::reindex | インデックス名 | null
sqlite3::analyze | テーブル名 | null
sqlite3::create_vtable | テーブル名 | モジュール名
sqlite3::drop_vtable | テーブル名 | モジュール名
sqlite3::function | null | ファンクション名
sqlite3::savepoint | 操作 | セーブポイントの名前
sqlite3::recursive | null | null

4番目の引数は、適切な場合にだけ指定する("main", "temp", などの) データベースの名前です。

authorizer コールバックに与える5番目の引数は、 トップレベルのSQLコードから直接アクセスが行われる場合に、 アクセスを試みる責任を持つ一番奥の view やトリガの名前です。

コールバックが SQLite3::OK を返すと、操作のリクエストが承認されたことになります。 コールバックが SQLite3::DENY を返すと、authorizer を動かした呼び出しは失敗し、 なぜアクセスが失敗したのかを説明するメッセージが残ります。

アクションが SQLite3::READ で、 さらにコールバックが SQLite3::IGNORE を返す場合、 準備されたSQL文は、 SQLite3::OK が返された場合に読まれていたテーブルのカラムを null で置き換えるように文を組み立てます。 SQLite3::IGNORE は、 信頼できないユーザーのアクセスが、 テーブルの個別のカラムへのアクセスを拒否する場合に使うことが出来ます。

テーブルを SELECT 文で参照しているが、 そのテーブルからカラムの値を抜き出さない場合 (たとえば、"SELECT count(*) FROM table" のようなクエリの場合)、 SQLite3::READ の authorizer コールバックは カラムの情報が空文字列になった状態で一度だけ呼び出されます。

アクションコードが SQLite3::DELETE で、 さらにコールバックが SQLite3::IGNORE を返した場合、 DELETE の操作は継続しますが、truncate による最適化は無効になります。 この場合、全ての行は個別に削除されます。

接続ひとつにつき、authorizer ひとつだけがデータベースに存在できます。 SQLite3::setAuthorizer() が呼び出されるたびに、 以前の呼び出しは上書きされます。 null をコールバックに指定することで、 authorizer を無効に出来ます。authorizer はデフォルトで無効になっています。

authorizer コールバックは、コールバックを呼び出すデータベース接続に対していかなる変更もしてはいけません。

authorizer はSQL文が準備される時にだけ呼び出されることに注意して下さい。 実行時ではありません。

さらなる詳細は » SQLite3 のドキュメント を参照ください。

パラメータ

callback

呼び出される callable。

null が渡されると、 現在の authorizer のコールバックが無効になります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドは例外をスローしません。 しかし、いったん authorizer が有効になり、不正な値を返すと、 SQL文の準備がエラー (または例外。 SQLite3::enableExceptions() の使い方によります) を発生させるようになります。

例

例1 SQLite3::setAuthorizer() の例

この例は、読み取りだけを許可します。 さらに、users テーブルのいくつかのカラムだけを返します。 他のカラムは null で置き換えられます。

<?php
$db = new SQLite3('data.sqlite');
$db->exec('CREATE TABLE users (id, name, password);');
$db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');

$allowed_columns = ['id', 'name'];

$db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
if ($action === SQLite3::READ) {
list($table, $column) = $args;

if ($table === 'users' && in_array($column, $allowed_columns) {
return SQLite3::OK;
}

return SQLite3::IGNORE;
}

return SQLite3::DENY;
});

print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));

上の例の出力は以下となります。

Array
(
    [id] => 1
    [name] => Pauline
    [password] =>
)


SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

  • ≪ SQLite3::setAuthorizer
  • SQLite3Exception ≫
  • PHP Manual
  • SQLite3
  • SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

説明

public static SQLite3::version(): array

SQLite3 ライブラリのバージョンを、文字列定数と数値で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

キー "versionString" および "versionNumber" を持つ連想配列を返します。

例

例1 SQLite3::version() の例

<?php
print_r(SQLite3::version());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [versionString] => 3.5.9
    [versionNumber] => 3005009
)


SQLite3Exception クラス

(PHP 8 >= 8.3.0)

はじめに

SQLite3 特有の例外を表します。

クラス概要

class SQLite3Exception extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


SQLite3Stmt クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SQLite 3 拡張モジュールのプリペアドステートメントを扱うクラスです。

クラス概要

class SQLite3Stmt {
/* メソッド */
private __construct(SQLite3 $sqlite3, string $query)
public bindParam(string|int $param, mixed &$var, int $type = SQLITE3_TEXT): bool
public bindValue(string|int $param, mixed $value, int $type = SQLITE3_TEXT): bool
public clear(): bool
public close(): bool
public execute(): SQLite3Result|false
public getSQL(bool $expand = false): string|false
public paramCount(): int
public readOnly(): bool
public reset(): bool
}

目次

  • SQLite3Stmt::bindParam — パラメータを変数にバインドする
  • SQLite3Stmt::bindValue — パラメータの値を変数にバインドする
  • SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする
  • SQLite3Stmt::close — プリペアドステートメントを閉じる
  • SQLite3Stmt::__construct — SQLite3Stmt オブジェクトを構築する
  • SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す
  • SQLite3Stmt::getSQL — ステートメントのSQLを取得する
  • SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す
  • SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す
  • SQLite3Stmt::reset — プリペアドステートメントをリセットする


パラメータを変数にバインドする

  • ≪ SQLite3Stmt
  • SQLite3Stmt::bindValue ≫
  • PHP Manual
  • SQLite3Stmt
  • パラメータを変数にバインドする

SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — パラメータを変数にバインドする

説明

public SQLite3Stmt::bindParam(string|int $param, mixed &$var, int $type = SQLITE3_TEXT): bool

パラメータを変数にバインドします。

警告

PHP 7.2.14 と 7.3.0 より前のバージョンでは、
バインドされた値が適切に後の SQLite3Stmt::execute()
の呼び出しで更新されるべき場合、
SQLite3Stmt::execute() をはじめて呼んだ後に
SQLite3Stmt::reset() を呼び出さなければなりませんでした。
SQLite3Stmt::reset() が呼び出されなかった場合、
SQLite3Stmt::bindParam() に渡された変数に代入された値が変化したり、
SQLite3Stmt::bindParam() を再度呼び出したりしても、
バインドされた値は決して変わりませんでした。

パラメータ

param

バインドされるべき文中の値を識別する string (名前付きパラメータの場合) または (位置パラメータの場合) int。 名前付きパラメータがコロン (:) や アットマーク (@) ではじまっていない場合、コロンが自動的に名前の前に付加されます。 位置パラメータは 1 から始まります。

var

変数にバインドするパラメータ。

type

バインドするパラメータのデータ型。

  • SQLITE3_INTEGER: 符号付き整数。 値の大きさに応じて 1, 2, 3, 4, 6, あるいは 8 バイトで格納されます。

  • SQLITE3_FLOAT: 浮動小数点数値。 8 バイトの IEEE 浮動小数点数値として格納されます。

  • SQLITE3_TEXT: テキスト文字列。 データベースのエンコーディング (UTF-8, UTF-16BE あるいは UTF-16-LE) を用いて格納されます。

  • SQLITE3_BLOB: blob データ。 入力がそのままの形式で格納されます。

  • SQLITE3_NULL: NULL 値。

PHP 7.0.7 以降では、 type が省略されると、 自動的に var の型から検出します: bool と int 型は SQLITE3_INTEGER として扱われ、 float は SQLITE3_FLOAT、 null は SQLITE3_NULL、 そして、これら以外は全て SQLITE3_TEXT として扱われます。 これより前のバージョンでは、type が省略されると、 デフォルトの型 SQLITE3_TEXT になっていました。

注意:

var が null の場合、 与えられた type に関わらず、 常に SQLITE3_NULL として扱われます。

戻り値

パラメータを変数にバインドした場合に true、 失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.4.0 | param は、 @param 記法もサポートするようになりました。

例

例1 SQLite3Stmt::bindParam() の使い方

この例は、バインドするパラメータがひとつだけのプリペアドステートメントを使い、 どのようにして異なる値を持つ複数の行を挿入するかを示しています。

<?php
$db = new SQLite3(':memory:');
$db->exec("CREATE TABLE foo (bar TEXT)");

$stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
$stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

$bar = 'baz';
$stmt->execute();

$bar = 42;
$stmt->execute();

$res = $db->query("SELECT * FROM foo");
while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
var_dump($row);
}
?>

上の例の出力は以下となります。

array(1) {
  ["bar"]=>
  string(3) "baz"
}
array(1) {
  ["bar"]=>
  string(2) "42"
}

参考

  • SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
  • SQLite3::prepare() - 実行する SQL 文を準備する


パラメータの値を変数にバインドする

  • ≪ SQLite3Stmt::bindParam
  • SQLite3Stmt::clear ≫
  • PHP Manual
  • SQLite3Stmt
  • パラメータの値を変数にバインドする

SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — パラメータの値を変数にバインドする

説明

public SQLite3Stmt::bindValue(string|int $param, mixed $value, int $type = SQLITE3_TEXT): bool

パラメータの値を変数にバインドします。

警告

PHP 7.2.14 と 7.3.0 より前のバージョンでは、 ステートメントがいったん実行されると、 バインドされたパラメータの値を変えられるようにするために SQLite3Stmt::reset() を呼び出す必要がありました。

パラメータ

param

バインドされるべき文中の値を識別する string (名前付きパラメータの場合) または (位置パラメータの場合) int。 名前付きパラメータがコロン (:) や アットマーク (@) ではじまっていない場合、コロンが自動的に名前の前に付加されます。 位置パラメータは 1 から始まります。

value

変数にバインドする値。

type

バインドする値のデータ型。

  • SQLITE3_INTEGER: 符号付き整数。 値の大きさに応じて 1, 2, 3, 4, 6, あるいは 8 バイトで格納されます。

  • SQLITE3_FLOAT: 浮動小数点数値。 8 バイトの IEEE 浮動小数点数値として格納されます。

  • SQLITE3_TEXT: テキスト文字列。 データベースのエンコーディング (UTF-8, UTF-16BE あるいは UTF-16-LE) を用いて格納されます。

  • SQLITE3_BLOB: blob データ。 入力がそのままの形式で格納されます。

  • SQLITE3_NULL: NULL 値。

PHP 7.0.7 以降では、type が省略されると、 自動的に value の型から検出します: bool と int 型は SQLITE3_INTEGER として扱われ、 float は SQLITE3_FLOAT、 null は SQLITE3_NULL、 そして、これら以外は全て SQLITE3_TEXT として扱われます。 これより前のバージョンでは、type が省略されると、 デフォルトの型 SQLITE3_TEXT になっていました。

注意:

value が null の場合、 与えられた type に関わらず、 常に SQLITE3_NULL として扱われます。

戻り値

値を変数にバインドした場合に true、失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | param が、新たに @param 記法をサポートしました。

例

例1 SQLite3Stmt::bindValue() の例

<?php
$db = new SQLite3(':memory:');

$db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
$db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

$stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
$stmt->bindValue(':id', 1, SQLITE3_INTEGER);

$result = $stmt->execute();
var_dump($result->fetchArray(SQLITE3_ASSOC));
?>

上の例の出力は以下となります。

array(1) {
  ["bar"]=>
  string(14) "This is a test"
}

参考

  • SQLite3Stmt::bindParam() - パラメータを変数にバインドする
  • SQLite3::prepare() - 実行する SQL 文を準備する


現在バインドされているすべてのパラメータをクリアする

  • ≪ SQLite3Stmt::bindValue
  • SQLite3Stmt::close ≫
  • PHP Manual
  • SQLite3Stmt
  • 現在バインドされているすべてのパラメータをクリアする

SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする

説明

public SQLite3Stmt::clear(): bool

現在バインドされているすべてのパラメータをクリアします。 (それらを null に設定します)

警告

このメソッドは SQLite3Stmt::reset() と一緒に使う必要があります。 単独で使うと、 SQLite3Stmt::bindValue() や SQLite3Stmt::bindParam() の呼び出しが無意味になり、 全てのバインドされたパラメータが null になってしまいます。

パラメータ

この関数にはパラメータはありません。

戻り値

バインドされているパラメータのクリアに成功した場合に true、 失敗した場合に false を返します。


プリペアドステートメントを閉じる

  • ≪ SQLite3Stmt::clear
  • SQLite3Stmt::__construct ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメントを閉じる

SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — プリペアドステートメントを閉じる

説明

public SQLite3Stmt::close(): bool

プリペアドステートメントを閉じます。

注意: このプリペアドステートメントから取得したすべての SQLite3Result は、プリペアドステートメントを閉じた時点で無効になることに注意しましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

true を返します。


SQLite3Stmt オブジェクトを構築する

  • ≪ SQLite3Stmt::close
  • SQLite3Stmt::execute ≫
  • PHP Manual
  • SQLite3Stmt
  • SQLite3Stmt オブジェクトを構築する

SQLite3Stmt::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SQLite3Stmt::__construct — SQLite3Stmt オブジェクトを構築する

説明

private SQLite3Stmt::__construct(SQLite3 $sqlite3, string $query)

SQLite3Stmt のインスタンスは、 SQLite3::prepare() によって作られます。

パラメータ

sqlite3

query


プリペアドステートメントを実行し、結果セットオブジェクトを返す

  • ≪ SQLite3Stmt::__construct
  • SQLite3Stmt::getSQL ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメントを実行し、結果セットオブジェクトを返す

SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す

説明

public SQLite3Stmt::execute(): SQLite3Result|false

プリペアドステートメントを実行し、結果セットオブジェクトを返します。

警告

同じステートメントオブジェクトに対して、 このメソッドを呼び出すことによって得られる結果セットは独立したものではありません。 むしろ、同じ基礎的な構造を共有しています。 よって、同じステートメントオブジェクトに対して SQLite3Stmt::execute() を再び呼ぶ前には、 SQLite3Result::finalize() を呼び出すことを推奨します。

パラメータ

この関数にはパラメータはありません。

戻り値

プリペアドステートメントの実行に成功した場合に SQLite3Result オブジェクト、 失敗した場合に false を返します。

参考

  • SQLite3::prepare() - 実行する SQL 文を準備する
  • SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
  • SQLite3Stmt::bindParam() - パラメータを変数にバインドする


ステートメントのSQLを取得する

  • ≪ SQLite3Stmt::execute
  • SQLite3Stmt::paramCount ≫
  • PHP Manual
  • SQLite3Stmt
  • ステートメントのSQLを取得する

SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — ステートメントのSQLを取得する

説明

public SQLite3Stmt::getSQL(bool $expand = false): string|false

プリペアドステートメントのSQLを取得します。 expand が false の場合、 変更されていないSQLを取得します。 expand が true の場合、 全てのクエリパラメータがバインド済みの値で、 何もバインドされていない場合は NULL で置き換えられます。

パラメータ

expand

展開済みのSQLを取得するかどうか。 true を渡すのは、libsqlite 3.14 以降でのみサポートされています。

戻り値

プリペアドステートメントのSQLを返します。 失敗した場合に false を返します

エラー / 例外

expand を true に指定したが、libsqlite のバージョンが 3.14 より前の場合、 SQLite3::enableExceptions() に応じて、 E_WARNING レベルの警告または Exception が発生します。

例

例1 展開済みのSQLを調べる

<?php
$db = new SQLite3(':memory:');
$stmt = $db->prepare("SELECT :a, ?, :c");
$stmt->bindValue(':a', 'foo');
$answer = 42;
$stmt->bindParam(2, $answer);
var_dump($stmt->getSQL(true));
?>

上の例の出力は、 たとえば以下のようになります。

string(24) "SELECT 'foo', '42', NULL"


プリペアドステートメント内のパラメータの数を返す

  • ≪ SQLite3Stmt::getSQL
  • SQLite3Stmt::readOnly ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメント内のパラメータの数を返す

SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す

説明

public SQLite3Stmt::paramCount(): int

プリペアドステートメント内のパラメータの数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

プリペアドステートメント内のパラメータの数を返します。

参考

  • SQLite3::prepare() - 実行する SQL 文を準備する


ステートメントが読み取り専用かどうかを返す

  • ≪ SQLite3Stmt::paramCount
  • SQLite3Stmt::reset ≫
  • PHP Manual
  • SQLite3Stmt
  • ステートメントが読み取り専用かどうかを返す

SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す

説明

public SQLite3Stmt::readOnly(): bool

ステートメントが読み取り専用かどうかを返します。 ステートメントは、それが 直接 データベースファイルの内容を変更しなければ、読み取り専用と見なされます。 ユーザー定義のSQL関数は、間接的に 副作用としてデータベースを変更する可能性があることに注意してください。

パラメータ

この関数にはパラメータはありません。

戻り値

ステートメントが読み取り専用であれば true を返します。 そうでなければ false を返します。


プリペアドステートメントをリセットする

  • ≪ SQLite3Stmt::readOnly
  • SQLite3Result ≫
  • PHP Manual
  • SQLite3Stmt
  • プリペアドステートメントをリセットする

SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — プリペアドステートメントをリセットする

説明

public SQLite3Stmt::reset(): bool

プリペアドステートメントをリセットし、実行前の状態に戻します。 バインドした内容は、リセットしてもそのまま残ります。

パラメータ

この関数にはパラメータはありません。

戻り値

ステートメントのリセットに成功した場合に true、失敗した場合に false を返します


SQLite3Result クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SQLite 3 拡張モジュールの結果セットを扱うクラスです。

クラス概要

class SQLite3Result {
/* メソッド */
private __construct()
public columnName(int $column): string|false
public columnType(int $column): int|false
public fetchArray(int $mode = SQLITE3_BOTH): array|false
public finalize(): bool
public numColumns(): int
public reset(): bool
}

目次

  • SQLite3Result::columnName — n 番目のカラムの名前を返す
  • SQLite3Result::columnType — n 番目のカラムの型を返す
  • SQLite3Result::__construct — SQLite3Result を構築する
  • SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する
  • SQLite3Result::finalize — 結果セットを閉じる
  • SQLite3Result::numColumns — 結果セットのカラム数を返す
  • SQLite3Result::reset — 結果セットを最初の行に戻す


n 番目のカラムの名前を返す

  • ≪ SQLite3Result
  • SQLite3Result::columnType ≫
  • PHP Manual
  • SQLite3Result
  • n 番目のカラムの名前を返す

SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — n 番目のカラムの名前を返す

説明

public SQLite3Result::columnName(int $column): string|false

column で指定したカラムの名前を返します。 返されるカラムの名前は AS 句が指定された場合、そこで指定された値になります。 AS 句の指定がない場合、カラムの名前は不定となり、 libsqlite3 のリリースによって変わる可能性があります。

パラメータ

column

0 から始まるカラムの数値インデックス。

戻り値

column で指定したカラムの名前を文字列で返します。 カラムが存在しない場合は、false を返します。


n 番目のカラムの型を返す

  • ≪ SQLite3Result::columnName
  • SQLite3Result::__construct ≫
  • PHP Manual
  • SQLite3Result
  • n 番目のカラムの型を返す

SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — n 番目のカラムの型を返す

説明

public SQLite3Result::columnType(int $column): int|false

column で指定したカラムの型を返します。

パラメータ

column

0 から始まるカラムの数値インデックス。

戻り値

column で指定したカラムのデータ型インデックス (SQLITE3_INTEGER、SQLITE3_FLOAT、 SQLITE3_TEXT、SQLITE3_BLOB あるいは SQLITE3_NULL のいずれか) を返します。 カラムが存在しない場合は、false を返します。


SQLite3Result を構築する

  • ≪ SQLite3Result::columnType
  • SQLite3Result::fetchArray ≫
  • PHP Manual
  • SQLite3Result
  • SQLite3Result を構築する

SQLite3Result::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SQLite3Result::__construct — SQLite3Result を構築する

説明

private SQLite3Result::__construct()

SQLite3Result のインスタンスは、 SQLite3::query() と SQLite3Stmt::execute() によって作られます。

パラメータ

この関数にはパラメータはありません。


結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

  • ≪ SQLite3Result::__construct
  • SQLite3Result::finalize ≫
  • PHP Manual
  • SQLite3Result
  • 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

説明

public SQLite3Result::fetchArray(int $mode = SQLITE3_BOTH): array|false

結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得します。 デフォルトでは両方で取得します。

パラメータ

mode

次の行をどのように返すかを制御します。値は SQLITE3_ASSOC か SQLITE3_NUM、SQLITE3_BOTH のいずれかでなければなりません。

  • SQLITE3_ASSOC: 返された結果セットのカラム名をインデックスとする配列を返します。

  • SQLITE3_NUM: 返された結果セットのカラム番号をインデックスとする配列を返します。 カラム番号は 0 から始まります。

  • SQLITE3_BOTH: 返された結果セットのカラム名とカラム番号の両方をインデックスとする配列を返します。 カラム番号は 0 から始まります。

戻り値

結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得します。 行がない場合は false を返します。

返される配列の値の型は、SQLite3 のデータ型と以下のようにマッピングされます: 数値型の場合、PHP_INT_MIN..PHP_INT_MAX の範囲に入れば、int にマッピングされます。そうでなければ、 string になります。Float 型は float に、 NULL 値は null に、 そして文字列型や Blob 型は string にマップされます。


結果セットを閉じる

  • ≪ SQLite3Result::fetchArray
  • SQLite3Result::numColumns ≫
  • PHP Manual
  • SQLite3Result
  • 結果セットを閉じる

SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — 結果セットを閉じる

説明

public SQLite3Result::finalize(): bool

結果セットを閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

true を返します。


結果セットのカラム数を返す

  • ≪ SQLite3Result::finalize
  • SQLite3Result::reset ≫
  • PHP Manual
  • SQLite3Result
  • 結果セットのカラム数を返す

SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — 結果セットのカラム数を返す

説明

public SQLite3Result::numColumns(): int

結果セットのカラム数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

結果セットのカラム数を返します。


結果セットを最初の行に戻す

  • ≪ SQLite3Result::numColumns
  • SQLSRV ≫
  • PHP Manual
  • SQLite3Result
  • 結果セットを最初の行に戻す

SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — 結果セットを最初の行に戻す

説明

public SQLite3Result::reset(): bool

結果セットを最初の行に戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

結果セットを最初の行に戻すことに成功した場合に true、 失敗した場合に false を返します。


PHP 用 Microsoft SQL Server ドライバ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • SQLSRV 関数
    • sqlsrv_begin_transaction — Begins a database transaction
    • sqlsrv_cancel — Cancels a statement
    • sqlsrv_client_info — Returns information about the client and specified connection
    • sqlsrv_close — Closes an open connection and releases resourses associated with the connection
    • sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
    • sqlsrv_configure — Changes the driver error handling and logging configurations
    • sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
    • sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
    • sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
    • sqlsrv_fetch — Makes the next row in a result set available for reading
    • sqlsrv_fetch_array — 行を配列として返す
    • sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
    • sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
    • sqlsrv_free_stmt — Frees all resources for the specified statement
    • sqlsrv_get_config — Returns the value of the specified configuration setting
    • sqlsrv_get_field — Gets field data from the currently selected row
    • sqlsrv_has_rows — Indicates whether the specified statement has rows
    • sqlsrv_next_result — Makes the next result of the specified statement active
    • sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
    • sqlsrv_num_rows — Retrieves the number of rows in a result set
    • sqlsrv_prepare — Prepares a query for execution
    • sqlsrv_query — Prepares and executes a query
    • sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction
    • sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
    • sqlsrv_send_stream_data — Sends data from parameter streams to the server
    • sqlsrv_server_info — Returns information about the server


はじめに

SQLSRV 拡張モジュールを使えば、PHP を実行する際に Microsoft SQL Server や SQL Azure データベースにアクセスできるようになります。 リリース 3.0 のドライバがサポートするのは SQL Server 2005 以降のバージョンで、SQL Server 2012 や SQL Server 2012 LocalDB にも対応します (LocalDB についての詳細な情報は » PHP Driver for SQL Server Support for LocalDB や » SQL Server 2012 Express LocalDB を参照ください)。

SQLSRV 拡張モジュールは Microsoft がサポートしており、 » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx からダウンロードできます。 SQL Server 2012 LocalDB は » http://go.microsoft.com/fwlink/?LinkID=237665 からダウンロードできます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SQLSRV
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

The SQLSRV extension can be used on the following operating systems:

  • Windows Vista Service Pack 2 or later
  • Windows Server 2008 Service Pack 2 or later
  • Windows Server 2008 R2
  • Windows 7

The SQLSRV extension requires that the Microsoft SQL Server 2012 Native Client be installed on the same computer that is running PHP. If the Microsoft SQL Server 2012 Native Client is not already installed, click the appropriate link below to download it:

  • » Download the x86 package
  • » Download the x64 package

The SQLSRV download comes 8 driver files, four of which are for PDO support.

The most recent version of the driver is available for download here: » SQLSRV download.

For more information about SQLSRV requirements, see » SQLSRV System Requirements.


インストール手順

The SQLSRV extension is enabled by adding appropriate DLL file to your PHP extension directory and the corresponding entry to the php.ini file. The SQLSRV download comes with 8 driver files, four of which are for PDO support.

The most recent version of the driver is available for download here: » SQLSRV download.

For more information about SQLSRV requirements, see » SQLSRV System Requirements.

Since version 4.0 the SQLSRV extension is compatible only with PHP 7.0 running on Linux or Windows.


実行時設定

php.ini の設定により動作が変化します。

下表では、SQLSRV 拡張モジュールで使用可能な構成オプションを一覧表示します。 これらのオプションについて詳しくは、 » Handling SQLSRV Warnings and Errors をご覧下さい。

SQLSRV 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sqlsrv.WarningsReturnAsErrors | 1 (true) | INI_ALL | SQLSRV 1.0 以降で使用可能
sqlsrv.LogSubsystems | 0 | INI_ALL | SQLSRV 1.0 以降で使用可能
sqlsrv.LogSeverity | 1 | INI_ALL | SQLSRV 1.0 以降で使用可能


リソース型

Connection resource

A connection resource returned by sqlsrv_connect().

Statement resource

A statement resource returned by sqlsrv_query() or by sqlsrv_prepare().


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SQLSRV_FETCH_ASSOC (int)
Forces sqlsrv_fetch_array() to return an associative array when passed as a parameter.
SQLSRV_FETCH_NUMERIC (int)
Forces sqlsrv_fetch_array() to return an array with numeric when passed as a parameter.
SQLSRV_FETCH_BOTH (int)
Forces sqlsrv_fetch_array() to return an array with both associative and numeric keys when passed as a parameter (the default behavior).
SQLSRV_ERR_ALL (int)
Forces sqlsrv_errors() to return both errors and warings when passed as a parameter (the default behavior).
SQLSRV_ERR_ERRORS (int)
Forces sqlsrv_errors() to return errors only (no warnings) when passed as a parameter.
SQLSRV_ERR_WARNINGS (int)
Forces sqlsrv_errors() to return warnings only (no errors) when passed as a parameter.
SQLSRV_LOG_SYSTEM_ALL (int)
Turns on logging of all subsystems when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_CONN (int)
Turns on logging of connection activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_INIT (int)
Turns on logging of initialization activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_OFF (int)
Turns off logging of all subsystems when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_STMT (int)
Turns on logging of statement activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SYSTEM_UTIL (int)
Turns on logging of error function activity when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_ALL (int)
Specifies that errors, warnings, and notices will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_ERROR (int)
Specifies that errors will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_NOTICE (int)
Specifies that notices will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_LOG_SEVERITY_WARNING (int)
Specifies that warnings will be logged when passed to sqlsrv_configure() as a parameter.
SQLSRV_NULLABLE_YES (int)
Indicates that a column is nullable.
SQLSRV_NULLABLE_NO (int)
Indicates that a column is not nullable.
SQLSRV_NULLABLE_UNKNOWN (int)
Indicates that it is not known if a column is nullable.
SQLSRV_PARAM_IN (int)
Indicates an input parameter when passed to sqlsrv_query() or sqlsrv_prepare().
SQLSRV_PARAM_INOUT (int)
Indicates a bidirectional parameter when passed to sqlsrv_query() or sqlsrv_prepare().
SQLSRV_PARAM_OUT (int)
Indicates an output parameter when passed to sqlsrv_query() or sqlsrv_prepare().
SQLSRV_PHPTYPE_INT (int)
Specifies an integer PHP data type. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_DATETIME (int)
Specifies a datetime PHP data type. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_FLOAT (int)
Specifies a float PHP data type. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_STREAM (int)
Specifies a PHP stream. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
SQLSRV_PHPTYPE_STRING (int)
Specifies a string PHP data type. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
SQLSRV_ENC_BINARY (int)
Specifies that data is returned as a raw byte stream from the server without performing encoding or translation. For usage information, see » How to: Specify PHP Types.
SQLSRV_ENC_CHAR (int)
Data is returned in 8-bit characters as specified in the code page of the Windows locale that is set on the system. Any multi-byte characters or characters that do not map into this code page are substituted with a single byte question mark (?) character. This is the default encoding. For usage information, see » How to: Specify PHP Types.
UTF-8 (int)
Specifies that data is returned with UTF-8 encoding. For usage information, see » How to: Specify PHP Types.
SQLSRV_SQLTYPE_BIGINT (int)
Describes the bigint SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_BINARY (int)
Describes the binary SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_BIT (int)
Describes the bit SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_CHAR (int)
Describes the char SQL Server data type. This constant works like a function and accepts a parameter indicating the number characters. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATE (int)
Describes the date SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATETIME (int)
Describes the datetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATETIME2 (int)
Describes the datetime2 SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DATETIMEOFFSET (int)
Describes the datetimeoffset SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_DECIMAL (int)
Describes the decimal SQL Server data type. This constant works like a function and accepts two parameters indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_FLOAT (int)
Describes the float SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_IMAGE (int)
Describes the image SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_INT (int)
Describes the int SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_MONEY (int)
Describes the money SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NCHAR (int)
Describes the nchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NUMERIC (int)
Describes the numeric SQL Server data type. This constant works like a function and accepts two parameter indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NVARCHAR (int)
Describes the nvarchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NVARCHAR('max') (int)
Describes the nvarchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_NTEXT (int)
Describes the ntext SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_REAL (int)
Describes the real SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_SMALLDATETIME (int)
Describes the smalldatetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_SMALLINT (int)
Describes the smallint SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_SMALLMONEY (int)
Describes the smallmoney SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TEXT (int)
Describes the text SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TIME (int)
Describes the time SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TIMESTAMP (int)
Describes the timestamp SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_TINYINT (int)
Describes the tinyint SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_UNIQUEIDENTIFIER (int)
Describes the uniqueidentifier SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_UDT (int)
Describes the UDT SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARBINARY (int)
Describes the varbinary SQL Server data type. This constant works like a function and accepts a single parameter indicating the byte count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARBINARY('max') (int)
Describes the varbinary(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARCHAR (int)
Describes the varchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_VARCHAR('max') (int)
Describes the varchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_SQLTYPE_XML (int)
Describes the XML SQL Server data type. For usage information, see » How to: Specify SQL Types.
SQLSRV_TXN_READ_UNCOMMITTED (int)
Indicates a transaction isolation level of READ UNCOMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_READ_COMMITTED (int)
Indicates a transaction isolation level of READ COMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_REPEATABLE_READ (int)
Indicates a transaction isolation level of REPEATABLE READ. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_SNAPSHOT (int)
Indicates a transaction isolation level of SNAPSHOT. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_TXN_READ_SERIALIZABLE (int)
Indicates a transaction isolation level of SERIALIZABLE. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
SQLSRV_CURSOR_FORWARD (int)
Indicates a forward-only cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_STATIC (int)
Indicates a static cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_DYNAMIC (int)
Indicates a dynamic cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_KEYSET (int)
Indicates a keyset cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_CURSOR_BUFFERED (int)
Creates a client-side cursor query. Lets you access rows in any order. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_NEXT (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_PRIOR (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_FIRST (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_LAST (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_ABSOLUTE (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
SQLSRV_SCROLL_RELATIVE (int)
Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.


SQLSRV 関数

目次

  • sqlsrv_begin_transaction — Begins a database transaction
  • sqlsrv_cancel — Cancels a statement
  • sqlsrv_client_info — Returns information about the client and specified connection
  • sqlsrv_close — Closes an open connection and releases resourses associated with the connection
  • sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
  • sqlsrv_configure — Changes the driver error handling and logging configurations
  • sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
  • sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
  • sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
  • sqlsrv_fetch — Makes the next row in a result set available for reading
  • sqlsrv_fetch_array — 行を配列として返す
  • sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
  • sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
  • sqlsrv_free_stmt — Frees all resources for the specified statement
  • sqlsrv_get_config — Returns the value of the specified configuration setting
  • sqlsrv_get_field — Gets field data from the currently selected row
  • sqlsrv_has_rows — Indicates whether the specified statement has rows
  • sqlsrv_next_result — Makes the next result of the specified statement active
  • sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
  • sqlsrv_num_rows — Retrieves the number of rows in a result set
  • sqlsrv_prepare — Prepares a query for execution
  • sqlsrv_query — Prepares and executes a query
  • sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction
  • sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
  • sqlsrv_send_stream_data — Sends data from parameter streams to the server
  • sqlsrv_server_info — Returns information about the server


Begins a database transaction

  • ≪ SQLSRV 関数
  • sqlsrv_cancel ≫
  • PHP Manual
  • SQLSRV 関数
  • Begins a database transaction

sqlsrv_begin_transaction

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_begin_transaction — Begins a database transaction

説明

sqlsrv_begin_transaction(resource $conn): bool

The transaction begun by sqlsrv_begin_transaction() includes all statements that were executed after the call to sqlsrv_begin_transaction() and before calls to sqlsrv_rollback() or sqlsrv_commit(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and commit/roll back transactions. For more information, see » SQLSRV Transactions.

パラメータ

conn

The connection resource returned by a call to sqlsrv_connect().

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_begin_transaction() example

The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true ));
}

/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
die( print_r( sqlsrv_errors(), true ));
}

/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;

/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
SET Quantity = (Quantity - ?)
WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
sqlsrv_commit( $conn );
echo "Transaction committed.<br />";
} else {
sqlsrv_rollback( $conn );
echo "Transaction rolled back.<br />";
}
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction
  • sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction


Cancels a statement

  • ≪ sqlsrv_begin_transaction
  • sqlsrv_client_info ≫
  • PHP Manual
  • SQLSRV 関数
  • Cancels a statement

sqlsrv_cancel

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_cancel — Cancels a statement

説明

sqlsrv_cancel(resource $stmt): bool

Cancels a statement. Any results associated with the statement that have not been consumed are deleted. After sqlsrv_cancel() has been called, the specified statement can be re-executed if it was created with sqlsrv_prepare(). Calling sqlsrv_cancel() is not necessary if all the results associated with the statement have been consumed.

パラメータ

stmt

The statement resource to be cancelled.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_cancel() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT Sales FROM Table_1";

$stmt = sqlsrv_prepare( $conn, $sql);

if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}

if( sqlsrv_execute( $stmt ) === false) {
die( print_r( sqlsrv_errors(), true));
}

$salesTotal = 0;
$count = 0;

while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
{
$qty = $row[0];
$price = $row[1];
$salesTotal += ( $price * $qty);
$count++;
}

echo "$count sales accounted for the first $$salesTotal in revenue.<br />";

// Cancel the pending results. The statement can be reused.
sqlsrv_cancel( $stmt);
?>

注意

The main difference between sqlsrv_cancel() and sqlsrv_free_stmt() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.

参考

  • sqlsrv_free_stmt() - Frees all resources for the specified statement
  • sqlsrv_prepare() - Prepares a query for execution


Returns information about the client and specified connection

  • ≪ sqlsrv_cancel
  • sqlsrv_close ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns information about the client and specified connection

sqlsrv_client_info

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_client_info — Returns information about the client and specified connection

説明

sqlsrv_client_info(resource $conn): array

Returns information about the client and specified connection

パラメータ

conn

The connection about which information is returned.

戻り値

Returns an associative array with keys described in the table below. Returns false otherwise.

Array returned by sqlsrv_client_info
Key | Description
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | ODBC version (xx.yy)
DriverVer | SQL Server Native Client DLL version (10.5.xxx)
ExtensionVer | php_sqlsrv.dll version (2.0.xxx.x)

例

例1 sqlsrv_client_info() example

<?php
$serverName = "serverName\sqlexpress";
$connOptions = array("UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connOptions );

if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

if( $client_info = sqlsrv_client_info( $conn)) {
foreach( $client_info as $key => $value) {
echo $key.": ".$value."<br />";
}
} else {
echo "Error in retrieving client info.<br />";
}
?>

参考

  • sqlsrv_server_info() - Returns information about the server


Closes an open connection and releases resourses associated with the connection

  • ≪ sqlsrv_client_info
  • sqlsrv_commit ≫
  • PHP Manual
  • SQLSRV 関数
  • Closes an open connection and releases resourses associated with the connection

sqlsrv_close

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_close — Closes an open connection and releases resourses associated with the connection

説明

sqlsrv_close(resource $conn): bool

Closes an open connection and releases resourses associated with the connection.

パラメータ

conn

The connection to be closed.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_close() example

<?php
$serverName = "serverName\sqlexpres";
$connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
$conn = sqlsrv_connect( $serverName, $connOptions );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

//-------------------------------------
// Perform database operations here.
//-------------------------------------

// Close the connection.
sqlsrv_close( $conn );
?>

参考

  • sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database


Commits a transaction that was begun with sqlsrv_begin_transaction

  • ≪ sqlsrv_close
  • sqlsrv_configure ≫
  • PHP Manual
  • SQLSRV 関数
  • Commits a transaction that was begun with sqlsrv_begin_transaction

sqlsrv_commit

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction()

説明

sqlsrv_commit(resource $conn): bool

Commits a transaction that was begun with sqlsrv_begin_transaction(). The connection is returned to auto-commit mode after sqlsrv_commit() is called. The transaction that is committed includes all statements that were executed after the call to sqlsrv_begin_transaction(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and commit/roll back transactions. For more information, see » SQLSRV Transactions.

パラメータ

conn

The connection on which the transaction is to be committed.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_commit() example

The following example demonstrates how to use sqlsrv_commit() together with sqlsrv_begin_transaction() and sqlsrv_rollback().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true ));
}

/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
die( print_r( sqlsrv_errors(), true ));
}

/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;

/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
SET Quantity = (Quantity - ?)
WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
sqlsrv_commit( $conn );
echo "Transaction committed.<br />";
} else {
sqlsrv_rollback( $conn );
echo "Transaction rolled back.<br />";
}
?>

参考

  • sqlsrv_begin_transaction() - Begins a database transaction
  • sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction


Changes the driver error handling and logging configurations

  • ≪ sqlsrv_commit
  • sqlsrv_connect ≫
  • PHP Manual
  • SQLSRV 関数
  • Changes the driver error handling and logging configurations

sqlsrv_configure

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_configure — Changes the driver error handling and logging configurations

説明

sqlsrv_configure(string $setting, mixed $value): bool

Changes the driver error handling and logging configurations.

パラメータ

setting

The name of the setting to set. The possible values are "WarningsReturnAsErrors", "LogSubsystems", and "LogSeverity".

value

The value of the specified setting. The following table shows possible values:

Error and Logging Setting Options
Setting | Options
WarningsReturnAsErrors | 1 (true) or 0 (false)
LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • » SQLSRV Error Handling.
  • » Logging SQLSRV Activity.


Opens a connection to a Microsoft SQL Server database

  • ≪ sqlsrv_configure
  • sqlsrv_errors ≫
  • PHP Manual
  • SQLSRV 関数
  • Opens a connection to a Microsoft SQL Server database

sqlsrv_connect

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_connect — Opens a connection to a Microsoft SQL Server database

説明

sqlsrv_connect(string $serverName, array $connectionInfo = ?): resource

Opens a connection to a Microsoft SQL Server database. By default, the connection is attempted using Windows Authentication. To connect using SQL Server Authentication, include "UID" and "PWD" in the connection options array.

パラメータ

serverName

The name of the server to which a connection is established. To connect to a specific instance, follow the server name with a backward slash and the instance name (e.g. serverName\sqlexpress).

connectionInfo

An associative array that specifies options for connecting to the server. If values for the UID and PWD keys are not specified, the connection will be attempted using Windows Authentication. For a complete list of supported keys, see » SQLSRV Connection Options.

戻り値

A connection resource. If a connection cannot be successfully opened, false is returned.

例

例1 Connect using Windows Authentication.

<?php
$serverName = "serverName\\sqlexpress"; //serverName\instanceName

// Since UID and PWD are not specified in the $connectionInfo array,
// The connection will be attempted using Windows Authentication.
$connectionInfo = array( "Database"=>"dbName");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

if( $conn ) {
echo "Connection established.<br />";
}else{
echo "Connection could not be established.<br />";
die( print_r( sqlsrv_errors(), true));
}
?>

例2 Connect by specifying a user name and password.

<?php
$serverName = "serverName\\sqlexpress"; //serverName\instanceName
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

if( $conn ) {
echo "Connection established.<br />";
}else{
echo "Connection could not be established.<br />";
die( print_r( sqlsrv_errors(), true));
}
?>

例3 Connect on a specified port.

<?php
$serverName = "serverName\\sqlexpress, 1542"; //serverName\instanceName, portNumber (default is 1433)
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

if( $conn ) {
echo "Connection established.<br />";
}else{
echo "Connection could not be established.<br />";
die( print_r( sqlsrv_errors(), true));
}
?>

注意

By default, the sqlsrv_connect() uses connection pooling to improve connection performance. To turn off connection pooling (i.e. force a new connection on each call), set the "ConnectionPooling" option in the $connectionOptions array to 0 (or false). For more information, see » SQLSRV Connection Pooling.

The SQLSRV extension does not have a dedicated function for changing which database is connected to. The target database is specified in the $connectionOptions array that is passed to sqlsrv_connect. To change the database on an open connection, execute the following query "USE dbName" (e.g. sqlsrv_query($conn, "USE dbName")).

参考

  • sqlsrv_close() - Closes an open connection and releases resourses associated with the connection
  • sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
  • sqlsrv_query() - Prepares and executes a query


Returns error and warning information about the last SQLSRV operation performed

  • ≪ sqlsrv_connect
  • sqlsrv_execute ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns error and warning information about the last SQLSRV operation performed

sqlsrv_errors

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed

説明

sqlsrv_errors(int $errorsOrWarnings = ?): mixed

Returns error and warning information about the last SQLSRV operation performed.

パラメータ

errorsOrWarnings

Determines whether error information, warning information, or both are returned. If this parameter is not supplied, both error information and warning information are returned. The following are the supported values for this parameter: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

戻り値

If errors and/or warnings occurred on the last sqlsrv operation, an array of arrays containing error information is returned. If no errors and/or warnings occurred on the last sqlsrv operation, null is returned. The following table describes the structure of the returned arrays:

Array returned by sqlsrv_errors
Key | Description
SQLSTATE | For errors that originate from the ODBC driver, the SQLSTATE returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of IMSSP. For warnings that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of 01SSP.
code | For errors that originate from SQL Server, the native SQL Server error code. For errors that originate from the ODBC driver, the error code returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, the Microsoft Drivers for PHP for SQL Server error code.
message | A description of the error.

例

例1 functionname() example

<?php
$serverName = "serverName/sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

/* Set up a query to select an invalid column name. */
$sql = "SELECT BadColumnName FROM Table_1";

/* Execution of the query will fail because of the bad column name. */
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false ) {
if( ($errors = sqlsrv_errors() ) != null) {
foreach( $errors as $error ) {
echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
echo "code: ".$error[ 'code']."<br />";
echo "message: ".$error[ 'message']."<br />";
}
}
}
?>

注意

By default, warnings generated on a call to any SQLSRV function are treated as errors. This means that if a warning occurs on a call to a SQLSRV function, the function returns false. However, warnings that correspond to SQLSTATE values 01000, 01001, 01003, and 01S02 are never treated as errors. For information about changing this behavior, see sqlsrv_configure() and the WarningsReturnAsErrors setting.

参考

  • sqlsrv_configure() - Changes the driver error handling and logging configurations


Executes a statement prepared with sqlsrv_prepare

  • ≪ sqlsrv_errors
  • sqlsrv_fetch ≫
  • PHP Manual
  • SQLSRV 関数
  • Executes a statement prepared with sqlsrv_prepare

sqlsrv_execute

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare()

説明

sqlsrv_execute(resource $stmt): bool

Executes a statement prepared with sqlsrv_prepare(). This function is ideal for executing a prepared statement multiple times with different parameter values.

パラメータ

stmt

A statement resource returned by sqlsrv_prepare().

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_execute() example

This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1
SET OrderQty = ?
WHERE SalesOrderID = ?";

// Initialize parameters and prepare the statement.
// Variables $qty and $id are bound to the statement, $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
die( print_r( sqlsrv_errors(), true));
}

// Set up the SalesOrderDetailID and OrderQty information.
// This array maps the order ID to order quantity in key=>value pairs.
$orders = array( 1=>10, 2=>20, 3=>30);

// Execute the statement for each order.
foreach( $orders as $id => $qty) {
// Because $id and $qty are bound to $stmt1, their updated
// values are used with each execution of the statement.
if( sqlsrv_execute( $stmt ) === false ) {
die( print_r( sqlsrv_errors(), true));
}
}
?>

注意

When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().

参考

  • sqlsrv_prepare() - Prepares a query for execution
  • sqlsrv_query() - Prepares and executes a query


Makes the next row in a result set available for reading

  • ≪ sqlsrv_execute
  • sqlsrv_fetch_array ≫
  • PHP Manual
  • SQLSRV 関数
  • Makes the next row in a result set available for reading

sqlsrv_fetch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_fetch — Makes the next row in a result set available for reading

説明

sqlsrv_fetch(resource $stmt, int $row = ?, int $offset = ?): mixed

Makes the next row in a result set available for reading. Use sqlsrv_get_field() to read the fields of the row.

パラメータ

stmt

A statement resource created by executing sqlsrv_query() or sqlsrv_execute().

row

The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:

  • SQLSRV_SCROLL_NEXT
  • SQLSRV_SCROLL_PRIOR
  • SQLSRV_SCROLL_FIRST
  • SQLSRV_SCROLL_LAST
  • SQLSRV_SCROLL_ABSOLUTE
  • SQLSRV_SCROLL_RELATIVE

offset

Specifies the row to be accessed if the row parameter is set to SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE. Note that the first row in a result set has index 0.

戻り値

Returns true if the next row of a result set was successfully retrieved, false if an error occurs, and null if there are no more rows in the result set.

例

例1 sqlsrv_fetch() example

The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT Name, Comment
FROM Table_1
WHERE ReviewID=1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}

// Make the first (and in this case, only) row of the result set available for reading.
if( sqlsrv_fetch( $stmt ) === false) {
die( print_r( sqlsrv_errors(), true));
}

// Get the row fields. Field indices start at 0 and must be retrieved in order.
// Retrieving row fields by name is not supported by sqlsrv_get_field.
$name = sqlsrv_get_field( $stmt, 0);
echo "$name: ";

$comment = sqlsrv_get_field( $stmt, 1);
echo $comment;
?>

参考

  • sqlsrv_get_field() - Gets field data from the currently selected row
  • sqlsrv_fetch_array() - 行を配列として返す
  • sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object


行を配列として返す

  • ≪ sqlsrv_fetch
  • sqlsrv_fetch_object ≫
  • PHP Manual
  • SQLSRV 関数
  • 行を配列として返す

sqlsrv_fetch_array

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_fetch_array — 行を配列として返す

説明

sqlsrv_fetch_array(
resource $stmt,
int $fetchType = ?,
int $row = ?,
int $offset = ?
): array

クエリ結果から列データを順に返します。列データの型は連想配列、配列、またはその両方(デフォルト)を選択できます。

パラメータ

stmt

sqlsrv_query あるいは sqlsrv_prepare が返すステートメントリソース。

fetchType

戻り値の型を指定します。連想配列SQLSRV_FETCH_ASSOC, 配列SQLSRV_FETCH_NUMERIC, and 連想配列と配列の両方SQLSRV_FETCH_BOTH (デフォルト) のうち1つを指定します。

SQLSRV_FETCH_ASSOC(連想配列)は同じ名前の列が複数存在する結果セットを扱う際に使ってはいけません(連想配列のキーが重複するため)。

row

スクロール可能なカーソルを用いた結果セットから、取得する列を指定します。 定義済み定数は、 SQLSRV_SCROLL_NEXT(次の列), SQLSRV_SCROLL_PRIOR(前の列), SQLSRV_SCROLL_FIRST(最初の列), SQLSRV_SCROLL_LAST(最後の列), SQLSRV_SCROLL_ABSOLUTE(列番号の絶対指定) and, SQLSRV_SCROLL_RELATIVE(列番号の相対指定) (デフォルト値). この引数を指定する場合は、fetchType を指定しなくてはなりません。

offset

引数rowに SQLSRV_SCROLL_ABSOLUTE または SQLSRV_SCROLL_RELATIVE を指定する際に、この引数で取得する列を指定します。 列番号は0から始まります。

戻り値

成功時に配列を返します。 返す列がない場合はnull を返します。エラーが起きた場合は falseを返します。

例

例1 連想配列を扱う場合の例

<?php
$serverName = "serverName\instanceName";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT FirstName, LastName FROM SomeTable";
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false) {
die( print_r( sqlsrv_errors(), true) );
}

while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
echo $row['LastName'].", ".$row['FirstName']."<br />";
}

sqlsrv_free_stmt( $stmt);
?>

例2 配列を扱う場合の例

<?php
$serverName = "serverName\instanceName";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo );
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT FirstName, LastName FROM SomeTable";
$stmt = sqlsrv_query( $conn, $sql );
if( $stmt === false) {
die( print_r( sqlsrv_errors(), true) );
}

while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
echo $row[0].", ".$row[1]."<br />";
}

sqlsrv_free_stmt( $stmt);
?>

注意

上の例で fetchType の指定を省略したり、定数 SQLSRV_FETCH_TYPE を明示的に指定した場合は、 連想配列と数値添字の両方のキーを含む配列を返します。

同じ名前のカラムが複数存在する場合は、最後に現れたカラムがそれまでのすべてを上書きします。 名前の衝突を回避するには、別名を指定しましょう。

無名のカラムが返された場合、連想配列のキーは空文字列("")になります。

参考

  • sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database
  • sqlsrv_query() - Prepares and executes a query
  • sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
  • sqlsrv_fetch() - Makes the next row in a result set available for reading


Retrieves the next row of data in a result set as an object

  • ≪ sqlsrv_fetch_array
  • sqlsrv_field_metadata ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves the next row of data in a result set as an object

sqlsrv_fetch_object

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object

説明

sqlsrv_fetch_object(
resource $stmt,
string $className = ?,
array $ctorParams = ?,
int $row = ?,
int $offset = ?
): mixed

Retrieves the next row of data in a result set as an instance of the specified class with properties that match the row field names and values that correspond to the row field values.

パラメータ

stmt

A statement resource created by sqlsrv_query() or sqlsrv_execute().

className

The name of the class to instantiate. If no class name is specified, stdClass is instantiated.

ctorParams

Values passed to the constructor of the specified class. If the constructor of the specified class takes parameters, the ctorParams array must be supplied.

row

The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:

  • SQLSRV_SCROLL_NEXT
  • SQLSRV_SCROLL_PRIOR
  • SQLSRV_SCROLL_FIRST
  • SQLSRV_SCROLL_LAST
  • SQLSRV_SCROLL_ABSOLUTE
  • SQLSRV_SCROLL_RELATIVE

offset

Specifies the row to be accessed if the row parameter is set to SQLSRV_SCROLL_ABSOLUTE or SQLSRV_SCROLL_RELATIVE. Note that the first row in a result set has index 0.

戻り値

Returns an object on success, null if there are no more rows to return, and false if an error occurs or if the specified class does not exist.

例

例1 sqlsrv_fetch_object() example

The following example demonstrates how to retrieve a row as a stdClass object.

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT fName, lName FROM Table_1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}

// Retrieve each row as an object.
// Because no class is specified, each row will be retrieved as a stdClass object.
// Property names correspond to field names.
while( $obj = sqlsrv_fetch_object( $stmt)) {
echo $obj->fName.", ".$obj->lName."<br />";
}
?>

注意

If a class name is specified with the optional $className parameter and the class has properties whose names match the result set field names, the corresponding result set values are applied to the properties. If a result set field name does not match a class property, a property with the result set field name is added to the object and the result set value is applied to the property. The following rules apply when using the $className parameter:

  • Field-property name matching is case-sensitive.
  • Field-property matching occurs regardless of access modifiers.
  • Class property data types are ignored when applying a field value to a property.
  • If the class does not exist, the function returns false and adds an error to the error collection.
Regardless of whether the $className parameter is supplied, if a field with no name is returned, the field value will be ignored and a warning will be added to the error collection.

When consuming a result set that has multiple columns with the same name, it may be better to use sqlsrv_fetch_array() or the combination of sqlsrv_fetch() and sqlsrv_get_field().

参考

  • sqlsrv_fetch() - Makes the next row in a result set available for reading
  • sqlsrv_fetch_array() - 行を配列として返す


Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query

  • ≪ sqlsrv_fetch_object
  • sqlsrv_free_stmt ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query

sqlsrv_field_metadata

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query()

説明

sqlsrv_field_metadata(resource $stmt): mixed

Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query(). sqlsrv_field_metadata() can be called on a statement before or after statement execution.

パラメータ

stmt

The statement resource for which metadata is returned.

戻り値

Returns an array of arrays on success. Otherwise, false is returned. Each returned array is described by the following table:

Array returned by sqlsrv_field_metadata
Key | Description
Name | The name of the field.
Type | The numeric value for the SQL type.
Size | The number of characters for fields of character type, the number of bytes for fields of binary type, or null for other types.
Precision | The precision for types of variable precision, null for other types.
Scale | The scale for types of variable scale, null for other types.
Nullable | An enumeration indicating whether the column is nullable, not nullable, or if it is not known.
For more information, see » sqlsrv_field_metadata in the Microsoft SQLSRV documentation.

例

例1 sqlsrv_field_metadata() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT * FROM Table_1";
$stmt = sqlsrv_prepare( $conn, $sql );

foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
foreach( $fieldMetadata as $name => $value) {
echo "$name: $value<br />";
}
echo "<br />";
}
?>

参考

  • sqlsrv_client_info() - Returns information about the client and specified connection


Frees all resources for the specified statement

  • ≪ sqlsrv_field_metadata
  • sqlsrv_get_config ≫
  • PHP Manual
  • SQLSRV 関数
  • Frees all resources for the specified statement

sqlsrv_free_stmt

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_free_stmt — Frees all resources for the specified statement

説明

sqlsrv_free_stmt(resource $stmt): bool

Frees all resources for the specified statement. The statement cannot be used after sqlsrv_free_stmt() has been called on it. If sqlsrv_free_stmt() is called on an in-progress statement that alters server state, statement execution is terminated and the statement is rolled back.

パラメータ

stmt

The statement for which resources are freed. Note that null is a valid parameter value. This allows the function to be called multiple times in a script.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_free_stmt() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}

/*-------------------------------
Process query results here.
-------------------------------*/

/* Free the statement resources. */
sqlsrv_free_stmt( $stmt);

?>

注意

The main difference between sqlsrv_free_stmt() and sqlsrv_cancel() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.

参考

  • sqlsrv_cancel() - Cancels a statement


Returns the value of the specified configuration setting

  • ≪ sqlsrv_free_stmt
  • sqlsrv_get_field ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns the value of the specified configuration setting

sqlsrv_get_config

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_get_config — Returns the value of the specified configuration setting

説明

sqlsrv_get_config(string $setting): mixed

Returns the value of the specified configuration setting.

パラメータ

setting

The name of the setting for which the value is returned. For a list of configurable settings, see sqlsrv_configure().

戻り値

Returns the value of the specified setting. If an invalid setting is specified, false is returned.

参考

  • sqlsrv_configure() - Changes the driver error handling and logging configurations


Gets field data from the currently selected row

  • ≪ sqlsrv_get_config
  • sqlsrv_has_rows ≫
  • PHP Manual
  • SQLSRV 関数
  • Gets field data from the currently selected row

sqlsrv_get_field

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_get_field — Gets field data from the currently selected row

説明

sqlsrv_get_field(resource $stmt, int $fieldIndex, int $getAsType = ?): mixed

Gets field data from the currently selected row. Fields must be accessed in order. Field indices start at 0.

パラメータ

stmt

A statement resource returned by sqlsrv_query() or sqlsrv_execute().

fieldIndex

The index of the field to be retrieved. Field indices start at 0. Fields must be accessed in order. i.e. If you access field index 1, then field index 0 will not be available.

getAsType

The PHP data type for the returned field data. If this parameter is not set, the field data will be returned as its default PHP data type. For information about default PHP data types, see » Default PHP Data Types in the Microsoft SQLSRV documentation.

戻り値

Returns data from the specified field on success. Returns false otherwise.

例

例1 sqlsrv_get_field() example

The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT Name, Comment
FROM Table_1
WHERE ReviewID=1";
$stmt = sqlsrv_query( $conn, $sql);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}

// Make the first (and in this case, only) row of the result set available for reading.
if( sqlsrv_fetch( $stmt ) === false) {
die( print_r( sqlsrv_errors(), true));
}

// Get the row fields. Field indices start at 0 and must be retrieved in order.
// Retrieving row fields by name is not supported by sqlsrv_get_field.
$name = sqlsrv_get_field( $stmt, 0);
echo "$name: ";

$comment = sqlsrv_get_field( $stmt, 1);
echo $comment;
?>

参考

  • sqlsrv_fetch() - Makes the next row in a result set available for reading
  • sqlsrv_fetch_array() - 行を配列として返す
  • sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object


Indicates whether the specified statement has rows

  • ≪ sqlsrv_get_field
  • sqlsrv_next_result ≫
  • PHP Manual
  • SQLSRV 関数
  • Indicates whether the specified statement has rows

sqlsrv_has_rows

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_has_rows — Indicates whether the specified statement has rows

説明

sqlsrv_has_rows(resource $stmt): bool

Indicates whether the specified statement has rows.

パラメータ

stmt

A statement resource returned by sqlsrv_query() or sqlsrv_execute().

戻り値

Returns true if the specified statement has rows and false if the statement does not have rows or if an error occurred.

例

例1 sqlsrv_has_rows() example

<?php
$server = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $server, $connectionInfo );

$stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

if ($stmt) {
$rows = sqlsrv_has_rows( $stmt );
if ($rows === true)
echo "There are rows. <br />";
else
echo "There are no rows. <br />";
}
?>

参考

  • sqlsrv_num_rows() - Retrieves the number of rows in a result set
  • sqlsrv_query() - Prepares and executes a query


Makes the next result of the specified statement active

  • ≪ sqlsrv_has_rows
  • sqlsrv_num_fields ≫
  • PHP Manual
  • SQLSRV 関数
  • Makes the next result of the specified statement active

sqlsrv_next_result

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_next_result — Makes the next result of the specified statement active

説明

sqlsrv_next_result(resource $stmt): mixed

Makes the next result of the specified statement active. Results include result sets, row counts, and output parameters.

パラメータ

stmt

The statement on which the next result is being called.

戻り値

Returns true if the next result was successfully retrieved, false if an error occurred, and null if there are no more results to retrieve.

例

例1 sqlsrv_next_result() example

The following example executes a batch query that inserts into a table and then selects from the table. This produces two results on the statement: one for the rows affected by the INSERT and one for the rows returned by the SELECT. To get to the rows returned by the SELECT, sqlsrv_next_result() must be called to move past the first result.

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);

$query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
$params = array(1, "some data");
$stmt = sqlsrv_query($conn, $query, $params);

// Consume the first result (rows affected by INSERT) without calling sqlsrv_next_result.
echo "Rows affected: ".sqlsrv_rows_affected($stmt)."<br />";

// Move to the next result and display results.
$next_result = sqlsrv_next_result($stmt);
if( $next_result ) {
while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
echo $row['id'].": ".$row['data']."<br />";
}
} elseif( is_null($next_result)) {
echo "No more results.<br />";
} else {
die(print_r(sqlsrv_errors(), true));
}
?>

参考

  • sqlsrv_query() - Prepares and executes a query
  • sqlsrv_fetch_array() - 行を配列として返す
  • sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed


Retrieves the number of fields (columns) on a statement

  • ≪ sqlsrv_next_result
  • sqlsrv_num_rows ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves the number of fields (columns) on a statement

sqlsrv_num_fields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement

説明

sqlsrv_num_fields(resource $stmt): mixed

Retrieves the number of fields (columns) on a statement.

パラメータ

stmt

The statement for which the number of fields is returned. sqlsrv_num_fields() can be called on a statement before or after statement execution.

戻り値

Returns the number of fields on success. Returns false otherwise.

例

例1 sqlsrv_num_fields() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "SELECT * FROM Table_1";
$stmt = sqlsrv_query($conn, $sql);
if( $stmt === false) {
die( print_r( sqlsrv_errors(), true));
}

$numFields = sqlsrv_num_fields( $stmt );

while( sqlsrv_fetch( $stmt )) {
// Iterate through the fields of each row.
for($i = 0; $i < $numFields; $i++) {
echo sqlsrv_get_field($stmt, $i)." ";
}
echo "<br />";
}
?>

参考

  • sqlsrv_field_metadata() - Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
  • sqlsrv_fetch() - Makes the next row in a result set available for reading
  • sqlsrv_get_field() - Gets field data from the currently selected row


Retrieves the number of rows in a result set

  • ≪ sqlsrv_num_fields
  • sqlsrv_prepare ≫
  • PHP Manual
  • SQLSRV 関数
  • Retrieves the number of rows in a result set

sqlsrv_num_rows

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_num_rows — Retrieves the number of rows in a result set

説明

sqlsrv_num_rows(resource $stmt): mixed

Retrieves the number of rows in a result set. This function requires that the statement resource be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

パラメータ

stmt

The statement for which the row count is returned. The statement resource must be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

戻り値

Returns the number of rows retrieved on success and false if an error occurred. If a forward cursor (the default) or dynamic cursor is used, false is returned.

例

例1 sqlsrv_num_rows() example

<?php
$server = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $server, $connectionInfo );

$sql = "SELECT * FROM Table_1";
$params = array();
$options = array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
$stmt = sqlsrv_query( $conn, $sql , $params, $options );

$row_count = sqlsrv_num_rows( $stmt );

if ($row_count === false)
echo "Error in retrieveing row count.";
else
echo $row_count;
?>

参考

  • sqlsrv_has_rows() - Indicates whether the specified statement has rows
  • sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed


Prepares a query for execution

  • ≪ sqlsrv_num_rows
  • sqlsrv_query ≫
  • PHP Manual
  • SQLSRV 関数
  • Prepares a query for execution

sqlsrv_prepare

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_prepare — Prepares a query for execution

説明

sqlsrv_prepare(
resource $conn,
string $sql,
array $params = ?,
array $options = ?
): mixed

Prepares a query for execution. This function is ideal for preparing a query that will be executed multiple times with different parameter values.

パラメータ

conn

A connection resource returned by sqlsrv_connect().

sql

The string that defines the query to be prepared and executed.

params

An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:

  • A literal value
  • A PHP variable
  • An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
The following table describes the elements in the array structure above:

Array structure
Element | Description
$value | A literal value, a PHP variable, or a PHP by-reference variable.
$direction (optional) | One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN.
$phpType (optional) | A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value.
$sqlType (optional) | A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value.
options

An array specifying query property options. The supported keys are described in the following table:

Query Options
Key | Values | Description
QueryTimeout | A positive integer value. | Sets the query timeout in seconds. By default, the driver will wait indefinitely for results.
SendStreamParamsAtExec | true or false (the default is true) | Configures the driver to send all stream data at execution (true), or to send stream data in chunks (false). By default, the value is set to true. For more information, see sqlsrv_send_stream_data().
Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET | See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

戻り値

Returns a statement resource on success and false if an error occurred.

例

例1 sqlsrv_prepare() example

This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1
SET OrderQty = ?
WHERE SalesOrderID = ?";

// Initialize parameters and prepare the statement.
// Variables $qty and $id are bound to the statement, $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
die( print_r( sqlsrv_errors(), true));
}

// Set up the SalesOrderDetailID and OrderQty information.
// This array maps the order ID to order quantity in key=>value pairs.
$orders = array( 1=>10, 2=>20, 3=>30);

// Execute the statement for each order.
foreach( $orders as $id => $qty) {
// Because $id and $qty are bound to $stmt1, their updated
// values are used with each execution of the statement.
if( sqlsrv_execute( $stmt ) === false ) {
die( print_r( sqlsrv_errors(), true));
}
}
?>

注意

When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().

参考

  • sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare
  • sqlsrv_query() - Prepares and executes a query


Prepares and executes a query

  • ≪ sqlsrv_prepare
  • sqlsrv_rollback ≫
  • PHP Manual
  • SQLSRV 関数
  • Prepares and executes a query

sqlsrv_query

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_query — Prepares and executes a query

説明

sqlsrv_query(
resource $conn,
string $sql,
array $params = ?,
array $options = ?
): mixed

Prepares and executes a query.

パラメータ

conn

A connection resource returned by sqlsrv_connect().

sql

The string that defines the query to be prepared and executed.

params

An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:

  • A literal value
  • A PHP variable
  • An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
The following table describes the elements in the array structure above:

Array structure
Element | Description
$value | A literal value, a PHP variable, or a PHP by-reference variable.
$direction (optional) | One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN.
$phpType (optional) | A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value.
$sqlType (optional) | A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value.
options

An array specifying query property options. The supported keys are described in the following table:

Query Options
Key | Values | Description
QueryTimeout | A positive integer value. | Sets the query timeout in seconds. By default, the driver will wait indefinitely for results.
SendStreamParamsAtExec | true or false (the default is true) | Configures the driver to send all stream data at execution (true), or to send stream data in chunks (false). By default, the value is set to true. For more information, see sqlsrv_send_stream_data().
Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET | See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

戻り値

Returns a statement resource on success and false if an error occurred.

例

例1 sqlsrv_query() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
$params = array(1, "some data");

$stmt = sqlsrv_query( $conn, $sql, $params);
if( $stmt === false ) {
die( print_r( sqlsrv_errors(), true));
}
?>

注意

For statements that you plan to execute only once, use sqlsrv_query(). If you intend to re-execute a statement with different parameter values, use the combination of sqlsrv_prepare() and sqlsrv_execute().

参考

  • sqlsrv_prepare() - Prepares a query for execution
  • sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare


Rolls back a transaction that was begun with sqlsrv_begin_transaction

  • ≪ sqlsrv_query
  • sqlsrv_rows_affected ≫
  • PHP Manual
  • SQLSRV 関数
  • Rolls back a transaction that was begun with sqlsrv_begin_transaction

sqlsrv_rollback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction()

説明

sqlsrv_rollback(resource $conn): bool

Rolls back a transaction that was begun with sqlsrv_begin_transaction() and returns the connection to auto-commit mode.

パラメータ

conn

The connection resource returned by a call to sqlsrv_connect().

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sqlsrv_rollback() example

The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true ));
}

/* Begin the transaction. */
if ( sqlsrv_begin_transaction( $conn ) === false ) {
die( print_r( sqlsrv_errors(), true ));
}

/* Initialize parameter values. */
$orderId = 1; $qty = 10; $productId = 100;

/* Set up and execute the first query. */
$sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
VALUES (?, ?, ?)";
$params1 = array( $orderId, $qty, $productId );
$stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

/* Set up and execute the second query. */
$sql2 = "UPDATE InventoryTable
SET Quantity = (Quantity - ?)
WHERE ProductID = ?";
$params2 = array($qty, $productId);
$stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

/* If both queries were successful, commit the transaction. */
/* Otherwise, rollback the transaction. */
if( $stmt1 && $stmt2 ) {
sqlsrv_commit( $conn );
echo "Transaction committed.<br />";
} else {
sqlsrv_rollback( $conn );
echo "Transaction rolled back.<br />";
}
?>

参考

  • sqlsrv_begin_transaction() - Begins a database transaction
  • sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction


Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

  • ≪ sqlsrv_rollback
  • sqlsrv_send_stream_data ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

sqlsrv_rows_affected

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

説明

sqlsrv_rows_affected(resource $stmt): int|false

Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed. For information about the number of rows returned by a SELECT query, see sqlsrv_num_rows().

パラメータ

stmt

The executed statement resource for which the number of affected rows is returned.

戻り値

Returns the number of rows affected by the last INSERT, UPDATE, or DELETE query. If no rows were affected, 0 is returned. If the number of affected rows cannot be determined, -1 is returned. If an error occurred, false is returned.

例

例1 sqlsrv_rows_affected() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1 SET data = ? WHERE id = ?";

$params = array("updated data", 1);

$stmt = sqlsrv_query( $conn, $sql, $params);

$rows_affected = sqlsrv_rows_affected( $stmt);
if( $rows_affected === false) {
die( print_r( sqlsrv_errors(), true));
} elseif( $rows_affected == -1) {
echo "No information available.<br />";
} else {
echo $rows_affected." rows were updated.<br />";
}
?>

参考

  • sqlsrv_num_rows() - Retrieves the number of rows in a result set


Sends data from parameter streams to the server

  • ≪ sqlsrv_rows_affected
  • sqlsrv_server_info ≫
  • PHP Manual
  • SQLSRV 関数
  • Sends data from parameter streams to the server

sqlsrv_send_stream_data

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_send_stream_data — Sends data from parameter streams to the server

説明

sqlsrv_send_stream_data(resource $stmt): bool

Send data from parameter streams to the server. Up to 8 KB of data is sent with each call.

パラメータ

stmt

A statement resource returned by sqlsrv_query() or sqlsrv_execute().

戻り値

Returns true if there is more data to send and false if there is not.

例

例1 sqlsrv_send_stream_data() example

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

// Open parameter data as a stream and put it in the $params array.
$data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
$params = array( &$data);

// Prepare the statement. Use the $options array to turn off the
// default behavior, which is to send all stream data at the time of query
// execution.
$options = array("SendStreamParamsAtExec"=>0);
$stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

sqlsrv_execute( $stmt);

// Send up to 8K of parameter data to the server
// with each call to sqlsrv_send_stream_data.
$i = 1;
while( sqlsrv_send_stream_data( $stmt)) {
$i++;
}
echo "$i calls were made.";
?>

参考

  • sqlsrv_prepare() - Prepares a query for execution
  • sqlsrv_query() - Prepares and executes a query


Returns information about the server

  • ≪ sqlsrv_send_stream_data
  • 日付および時刻関連 ≫
  • PHP Manual
  • SQLSRV 関数
  • Returns information about the server

sqlsrv_server_info

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

sqlsrv_server_info — Returns information about the server

説明

sqlsrv_server_info(resource $conn): array

Returns information about the server.

パラメータ

conn

The connection resource that connects the client and the server.

戻り値

Returns an array as described in the following table:

Returned Array
CurrentDatabase | The connected-to database.
SQLServerVersion | The SQL Server version.
SQLServerName | The name of the server.

例

例1 sqlsrv_server_info() example

<?php
$serverName = "serverName\sqlexpress";
$conn = sqlsrv_connect( $serverName);
if( $conn === false ) {
die( print_r( sqlsrv_errors(), true));
}

$server_info = sqlsrv_server_info( $conn);
if( $server_info )
{
foreach( $server_info as $key => $value) {
echo $key.": ".$value."<br />";
}
} else {
die( print_r( sqlsrv_errors(), true));
}
?>

参考

  • sqlsrv_client_info() - Returns information about the client and specified connection


日付および時刻関連

  • カレンダー
    • はじめに
    • インストール/設定
    • 定義済み定数
    • カレンダー 関数
  • Date/Time — 日付・時刻
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • DateTime — DateTime クラス
    • DateTimeImmutable — DateTimeImmutable クラス
    • DateTimeInterface — DateTimeInterface インターフェイス
    • DateTimeZone — DateTimeZone クラス
    • DateInterval — DateInterval クラス
    • DatePeriod — DatePeriod クラス
    • 日付・時刻 関数
    • 日付・時刻 に関するエラーと例外
    • サポートする日付と時刻の書式
    • サポートされるタイムゾーンのリスト
    • DateError — DateError クラス
    • DateObjectError — DateObjectError クラス
    • DateRangeError — DateRangeError クラス
    • DateException — DateException クラス
    • DateInvalidOperationException — DateInvalidOperationException クラス
    • DateInvalidTimeZoneException — DateInvalidTimeZoneException クラス
    • DateMalformedIntervalStringException — DateMalformedIntervalStringException クラス
    • DateMalformedPeriodStringException — DateMalformedPeriodStringException クラス
    • DateMalformedStringException — DateMalformedStringException クラス
  • HRTime — High resolution timing
    • はじめに
    • インストール/設定
    • 例
    • HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
    • HRTime\StopWatch — The HRTime\StopWatch class
    • HRTime\Unit — The HRTime\Unit class


カレンダー

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
  • カレンダー 関数
    • 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 タイムスタンプをユリウス歴に変換する


はじめに

カレンダー拡張モジュールは異なったカレンダーフォーマット間の変換処理をシンプルにする関数の集まりです。標準としているのは、ユリウス積算日です。 ユリウス積算日は、紀元前 4713 年 1 月 1 日から数え始められています。 複数のカレンダーシステム間の変換を行うには、ユリウス積算日に変換した後 に選択したカレンダーシステムに変換しなければなりません。 ユリウス積算日はユリウス暦とはまったく異なります! ユリウス積算日の詳細を知りたいのであれば、 » http://www.hermetic.ch/cal_stud/jdn.htm を参照ください。 カレンダーシステムに関する情報を知りたいのであれば、 » http://www.fourmilab.ch/documents/calendar/ を参照ください。 本説明にはこのページからの引用が含まれています。 このページの内容はこのチュートリアルにも反映/引用されています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • カレンダー
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

これらの関数を動作させるには、 --enable-calendar を指定して PHP をコンパイルする必要があります。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

CAL_EASTER_DEFAULT (int)
easter_days() で、1753年より前はユリウス暦に従って、 それ以降はグレゴリオ暦に従って復活祭の日付を計算する。
CAL_EASTER_ROMAN (int)
easter_days() で、1583年より前はユリウス暦に従って、 それ以降はグレゴリオ暦に従って復活祭の日付を計算する。
CAL_EASTER_ALWAYS_GREGORIAN (int)
easter_days() で、先発グレゴリオ暦に従って、 復活祭の日付を計算する。
CAL_EASTER_ALWAYS_JULIAN (int)
easter_days() で、ユリウス暦に従って、 復活祭の日付を計算する。
CAL_GREGORIAN (int)
cal_days_in_month()、
cal_from_jd()、cal_info() および
cal_to_jd() で、先発グレゴリオ暦を使う。
CAL_JULIAN (int)
cal_days_in_month()、
cal_from_jd()、cal_info() および
cal_to_jd() で、ユリウス暦を使う。
CAL_JEWISH (int)
cal_days_in_month()、
cal_from_jd()、cal_info() および
cal_to_jd() で、ユダヤ暦を使う。
CAL_FRENCH (int)
cal_days_in_month()、
cal_from_jd()、cal_info() および
cal_to_jd() で、フランス革命暦を使う。
CAL_NUM_CALS (int)
利用可能なカレンダーの数。
CAL_JEWISH_ADD_ALAFIM_GERESH (int)
jdtojewish() で、年の桁区切りとして、 ゲレシュ記号（シングルクォートに似た記号）を追加する。
CAL_JEWISH_ADD_ALAFIM (int)
jdtojewish() で、年の桁区切りとして、 「alafim」という語を追加する。
CAL_JEWISH_ADD_GERESHAYIM (int)
jdtojewish() で、年と日の最後の文字の前に、 ゲルシャイム記号（ダブルクォートに似た記号）を追加する。
CAL_DOW_DAYNO (int)
jddayofweek() で、曜日を int で返す。 0 は日曜を、6 は土曜を意味する。
CAL_DOW_SHORT (int)
jddayofweek() で、曜日の省略形英語名を返す。
CAL_DOW_LONG (int)
jddayofweek() で、曜日の英語名を返す。
CAL_MONTH_GREGORIAN_SHORT (int)
jdmonthname() で、省略形のグレゴリオ歴月名を返す。
CAL_MONTH_GREGORIAN_LONG (int)
jdmonthname() で、グレゴリオ歴月名を返す。
CAL_MONTH_JULIAN_SHORT (int)
jdmonthname() で、省略形のユリウス歴月名を返す。
CAL_MONTH_JULIAN_LONG (int)
jdmonthname() で、ユリウス歴月名を返す。
CAL_MONTH_JEWISH (int)
jdmonthname() で、ユダヤ歴月名を返す。
CAL_MONTH_FRENCH (int)
jdmonthname() で、フランス革命歴月名を返す。


カレンダー 関数

目次

  • 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 タイムスタンプをユリウス歴に変換する


指定した年とカレンダーについて、月の日数を返す

  • ≪ カレンダー 関数
  • cal_from_jd ≫
  • PHP Manual
  • カレンダー 関数
  • 指定した年とカレンダーについて、月の日数を返す

cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — 指定した年とカレンダーについて、月の日数を返す

説明

cal_days_in_month(int $calendar, int $month, int $year): int

この関数は、指定した calendar について year 年 month 月の日数を返します。

パラメータ

calendar

計算に使用するカレンダー。

month

選択したカレンダーにおける月。

year

選択したカレンダーにおける年。

戻り値

指定したカレンダーの、その月の日数を返します。

例

例1 cal_days_in_month() の例

<?php
$number = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
echo "2003 年 8 月の日数は {$number} 日です";
?>


ユリウス積算日からサポートされるカレンダーに変換する

  • ≪ cal_days_in_month
  • cal_info ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日からサポートされるカレンダーに変換する

cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — ユリウス積算日からサポートされるカレンダーに変換する

説明

cal_from_jd(int $julian_day, int $calendar): array

cal_from_jd() は、 julian_day で指定したユリウス日を 指定した calendar に変換します。 サポートされる calendar の値は、 CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH および CAL_FRENCH です。

パラメータ

julian_day

ユリウス日を表す整数値。

calendar

変換するカレンダー。

戻り値

カレンダーの情報を含む配列を返します。この配列には、 年、月、日、週(dow)、曜日名、月名、"月/日/年" 形式の文字列 などが含まれます。 曜日は 0 (日曜日) から 6 (土曜日) までの値を取ります。

例

例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_from_jd
  • cal_to_jd ≫
  • PHP Manual
  • カレンダー 関数
  • 特定のカレンダーに関する情報を返す

cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — 特定のカレンダーに関する情報を返す

説明

cal_info(int $calendar = -1): array

cal_info() は、指定した calendar についての情報を返します。

カレンダーの情報は配列として返され、その要素は calname、calsymbol、 month、abbrevmonth および maxdaysinmonth となります。 calendar として指定可能なカレンダー名は以下のとおりです。

  • 0 あるいは CAL_GREGORIAN - グレゴリウス暦
  • 1 あるいは CAL_JULIAN - ユリウス暦
  • 2 あるいは CAL_JEWISH - ユダヤ暦
  • 3 あるいは CAL_FRENCH - フランス革命暦

calendar が指定されなかった場合は、 サポートするすべてのカレンダーの情報を配列で返します。

パラメータ

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_info
  • easter_date ≫
  • PHP Manual
  • カレンダー 関数
  • サポートされるカレンダーからユリウス積算日に変換する

cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — サポートされるカレンダーからユリウス積算日に変換する

説明

cal_to_jd(
int $calendar,
int $month,
int $day,
int $year
): int

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 タイムスタンプをユリウス歴に変換する


指定した年における復活祭の真夜中のUnix時を得る

  • ≪ cal_to_jd
  • easter_days ≫
  • PHP Manual
  • カレンダー 関数
  • 指定した年における復活祭の真夜中のUnix時を得る

easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — 指定した年における復活祭の真夜中のUnix時を得る

説明

easter_date(?int $year = null, int $mode = CAL_EASTER_DEFAULT): int

指定した年yearにおける復活祭の真夜中のUnix時を返します。

復活祭の日付は、西暦325年の Nicaea 会議で春分の日の後の 最初の満月の後の日曜日として定められました。 満月とその次の日曜日の日付の計算を簡単にするために 春分の日は常に3月21日になるとして計算されます。 ここで用いるアルゴリズムは、532年頃、Dionysius Exiguus により 導出されたものです。(1753年より前の年に関して)ユリウス暦の元では 月の周期を追うために簡単な19年周期が用いられます。グレゴリウス暦 (1753年以降。この暦は、ClaviusとLiliusにより考案され、 教皇グレゴリウス13世により1582年10月に導入、イギリス及びその植民地に 1752年9月に導入された。) のもとで、二つの補正係数が周期をより正確に作成するために追加されました。

パラメータ

year

年の値。32ビットのシステムでは、 1970 から 2037 までである必要があります。 64ビットのシステムでは、 1970 から 2,000,000,000 までである必要があります。 省略した場合、もしくは null の場合は、 デフォルトとしてローカルタイムにおける現在の年を使います。

mode

CAL_EASTER_ALWAYS_JULIAN を設定すると、 ユリウス暦のカレンダをベースにして復活祭の日付が計算できます。 calendar の定数 を参照ください。

戻り値

復活祭の日を Unix タイムスタンプで返します。

エラー / 例外

32ビットのシステムでは、year の値が 1970 より前か 2037 より後の場合、 ValueError がスローされます。 64ビットのシステムでは、year の値が 1970 より前か 2,000,000,000 より後の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.3.0 | 64ビットのシステムでは、 year の値として 1970 から 2,000,000,000 までの値を受け入れるようになりました。
8.0.0 | year は、nullable になりました。
8.0.0 | year が範囲外の値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生して false を返していました。

例

例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

?>

例2 easter_date() を DateTime と一緒に使う

<?php
$timestamp = easter_date(2023);
$datetime = new \DateTime();
$datetime->setTimestamp($timestamp);
echo $datetime->format('M-d-Y'); // Apr-09-2023

?>

注意

注意:

easter_date() は、システムの C ライブラリの関数を利用します。 PHP 組み込みの日付・時刻関数を使うわけではなりません。 つまり、easter_date() が利用するタイムゾーンは環境変数 TZ の値であり、PHP の デフォルトのタイムゾーンは考慮しません。 その結果、PHP の他の日付関数と組み合わせて使ったときに予期せぬ結果になる可能性があります。

回避策として、easter_days() を DateTime や DateInterval と組み合わせて使えば、PHP で設定したタイムゾーンにおける復活祭の開始時刻を算出できます。

<?php
function get_easter_datetime($year) {
$base = new DateTime("$year-03-21");
$days = easter_days($year);

return $base->add(new DateInterval("P{$days}D"));
}

foreach (range(2012, 2015) as $year) {
printf("Easter in %d is on %s\n",
$year,
get_easter_datetime($year)->format('F j'));
}
?>

上の例の出力は以下となります。

Easter in 2012 is on April 8
Easter in 2013 is on March 31
Easter in 2014 is on April 20
Easter in 2015 is on April 5

参考

  • 1970年以前または2037年以降の復活祭の計算に関しては、 easter_days() - 指定した年において、3 月 21 日から復活祭までの日数を得る を参照ください。


指定した年において、3 月 21 日から復活祭までの日数を得る

  • ≪ easter_date
  • frenchtojd ≫
  • PHP Manual
  • カレンダー 関数
  • 指定した年において、3 月 21 日から復活祭までの日数を得る

easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — 指定した年において、3 月 21 日から復活祭までの日数を得る

説明

easter_days(?int $year = null, int $mode = CAL_EASTER_DEFAULT): int

指定した年 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

正の数値で表した年。省略した場合、もしくは null の場合は、 ローカルタイムにおける現在の年を使います。

mode

CAL_EASTER_ROMAN に設定すると 1582 年から 1752 年までの復活祭の日付をグレゴリオ暦にもとづいて 計算します。それ以外に使用可能な定数については カレンダー定数を参照ください。

戻り値

指定した年 year において、3 月 21 日から復活祭までの日数を返します。

変更履歴

バージョン | 説明
8.0.0 | year は、nullable になりました。

例

例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時を得る


フランス革命暦をユリウス積算日に変換する

  • ≪ easter_days
  • gregoriantojd ≫
  • PHP Manual
  • カレンダー 関数
  • フランス革命暦をユリウス積算日に変換する

frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — フランス革命暦をユリウス積算日に変換する

説明

frenchtojd(int $month, int $day, int $year): int

日付けをフランス革命暦からユリウス積算日に変換します。

これらのルーチンは、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() - サポートされるカレンダーからユリウス積算日に変換する


グレゴリウス日をユリウス積算日に変換する

  • ≪ frenchtojd
  • jddayofweek ≫
  • PHP Manual
  • カレンダー 関数
  • グレゴリウス日をユリウス積算日に変換する

gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — グレゴリウス日をユリウス積算日に変換する

説明

gregoriantojd(int $month, int $day, int $year): int

有効なグレゴリウス暦の範囲は紀元前 4714 年 11月25日から、少なくとも紀元 9999 年 12月31日までです。

このソフトウェアは日付けを全て紀元前 4714 年にさかのぼることが 出来ますが、この様な使い方は特に意味があるわけではありません。 グレゴリウス暦は 1582 年 10 月 15 日(ユリウス暦では 1582 年 10 月 5 日)まで制定されていませんでした。 この暦は、いくつかの国でもっと後まで受け入れられませんでした。 例えば、イギリスは 1752 年、ロシア(USSR)は 1918 年、ギリシャは 1923 年に 移行しました。 ほとんどのヨーロッパの国々では、グレゴリウス暦の前は ユリウス暦を使用していました。

パラメータ

month

月を表す、1 (January) から 12 (December) までの数字。 月の最後の日が与えられた日より少ない場合、オーバーフローが発生します; 例を参照ください。

day

日を表す、1 から 31 までの数字。

year

年を表す、-4714 から 9999 までの数字。 負の値は B.C を意味し、正の値は A.D を意味しています。 0 という年はないことに注意してください。 つまり、B.C 元年の12月31日の次は、A.D 元年の1月1日です。

戻り値

指定したグレゴリウス日をユリウス積算日になおした結果を返します。 範囲外の日付については 0 を返します。

例

例1 カレンダー関数

<?php
$jd = gregoriantojd(10, 11, 1970);
echo "$jd\n";
$gregorian = jdtogregorian($jd);
echo "$gregorian\n";
?>

上の例の出力は以下となります。

2440871
10/11/1970

例2 Overflow behavior

<?php
echo gregoriantojd(2, 31, 2018), PHP_EOL,
gregoriantojd(3, 3, 2018), PHP_EOL;
?>

上の例の出力は以下となります。

2458181
2458181

参考

  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する


曜日を返す

  • ≪ gregoriantojd
  • jdmonthname ≫
  • PHP Manual
  • カレンダー 関数
  • 曜日を返す

jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — 曜日を返す

説明

jddayofweek(int $julian_day, int $mode = CAL_DOW_DAYNO): int|string

曜日を返します。 モードに依存した文字あるいは整数を返す事が出来ます。

パラメータ

julian_day

ユリウス積算日を表す整数値。

mode
暦の曜日モード
モード | 意味
0 (デフォルト) | 整数で曜日番号 (0=Sunday, 1=Monday, 等)を返します。
1 | 曜日(英グレゴリウス)を含む文字列を返します。
2 | 曜日の省略形(英グレゴリウス)を含む文字列を返します。

戻り値

グレゴリウス暦の曜日を表す数値あるいは文字列を返します。


月の名前を返す

  • ≪ jddayofweek
  • jdtofrench ≫
  • PHP Manual
  • カレンダー 関数
  • 月の名前を返す

jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — 月の名前を返す

説明

jdmonthname(int $julian_day, int $mode): string

月の名前を含んだ文字列を返します。 modeはユリウス積算日をどの暦に変換するか、 どんなタイプの月名を返すかを関数に伝えます。

暦モード
モード | 意味 | 値
CAL_MONTH_GREGORIAN_SHORT | グレゴリウス暦 - 省略形 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
CAL_MONTH_GREGORIAN_LONG | グレゴリウス暦 | January, February, March, April, May, June, July, August, September, October, November, December
CAL_MONTH_JULIAN_SHORT | ユリウス暦 - 省略形 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
CAL_MONTH_JULIAN_LONG | ユリウス暦 | January, February, March, April, May, June, July, August, September, October, November, December
CAL_MONTH_JEWISH | ユダヤ暦 | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, Adar I, Adar II, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
CAL_MONTH_FRENCH | フランス革命暦 | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

パラメータ

jday

変換したいユリウス積算日。

mode

カレンダーのモード(上の表を参照)

戻り値

指定したユリウス積算日と mode にもとづく月名を返します。


ユリウス積算日をフランス革命暦(共和暦)に変換する

  • ≪ jdmonthname
  • jdtogregorian ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をフランス革命暦(共和暦)に変換する

jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — ユリウス積算日をフランス革命暦(共和暦)に変換する

説明

jdtofrench(int $julian_day): string

ユリウス積算日をフランス革命暦に変換します。

パラメータ

julian_day

ユリウス積算日を表す整数値。

戻り値

フランス革命暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • frenchtojd() - フランス革命暦をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する


ユリウス積算日をグレゴリウス日に変換する

  • ≪ jdtofrench
  • jdtojewish ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をグレゴリウス日に変換する

jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — ユリウス積算日をグレゴリウス日に変換する

説明

jdtogregorian(int $julian_day): string

ユリウス積算日を "月/日/年" の形式でグレゴリウス日を含む文字列に変換します。

パラメータ

julian_day

ユリウス積算日を表す整数値。

戻り値

グレゴリウス暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • gregoriantojd() - グレゴリウス日をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する


ユリウス積算日をユダヤ暦に変換する

  • ≪ jdtogregorian
  • jdtojulian ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をユダヤ暦に変換する

jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — ユリウス積算日をユダヤ暦に変換する

説明

jdtojewish(int $julian_day, bool $hebrew = false, int $flags = 0): string

ユリウス積算日をユダヤ暦に変換します。

パラメータ

julian_day

ユリウス積算日を表す整数値。

hebrew

パラメータ hebrew が true に設定されている場合、 ヘブライ語の ISO-8859-8 ベースの文字列形式での出力のために flags が使用されます。

flags

組み合わせ可能なビットマスクは CAL_JEWISH_ADD_ALAFIM_GERESH、 CAL_JEWISH_ADD_ALAFIM および CAL_JEWISH_ADD_GERESHAYIM です。

戻り値

ユダヤ暦の日付を "月/日/年" 形式の文字列で返します。 または、hebrew に応じて ISO-8859-8 でエンコードされたヘブライ語の文字列を返します。

例

例1 jdtojewish() の例

<?php
$jd = gregoriantojd(10, 8, 2002);
echo jdtojewish($jd, true), PHP_EOL,
jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM), PHP_EOL,
jdtojewish($jd, true, CAL_JEWISH_ADD_ALAFIM), PHP_EOL,
jdtojewish($jd, true,CAL_JEWISH_ADD_ALAFIM_GERESH), PHP_EOL;
?>

上の例の出力は以下となります。

? ???? ?????
?' ???? ????"?
? ???? ? ????? ????
? ???? ?'????

参考

  • jewishtojd() - ユダヤ暦の日付けをユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する


ユリウス積算日をユリウス暦に変換する

  • ≪ jdtojewish
  • jdtounix ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス積算日をユリウス暦に変換する

jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — ユリウス積算日をユリウス暦に変換する

説明

jdtojulian(int $julian_day): string

ユリウス積算日を "月/日/年" の形式でユリウス暦を含む文字列に変換します。

パラメータ

julian_day

ユリウス積算日を表す整数値。

戻り値

ユリウス暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • juliantojd() - ユリウス暦をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する


ユリウス歴を Unix タイムスタンプに変換する

  • ≪ jdtojulian
  • jewishtojd ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス歴を Unix タイムスタンプに変換する

jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — ユリウス歴を Unix タイムスタンプに変換する

説明

jdtounix(int $julian_day): int

この関数は、julian_day で指定したユリウス歴に 対応する Unix タイムスタンプを返します。 返される時刻はUTCです。

パラメータ

julian_day

64bit のシステムでは、2440588 から 106751993607888 までのユリウス積算日。 32bit のシステムでは、2440588 から 2465443 までの値です。

戻り値

指定したユリウス積算日の開始(昼ではなく夜中)時の Unix タイムスタンプを返します。

エラー / 例外

julian_day が範囲外の値の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。 代わりに ValueError をスローするようになっています。
7.3.24, 7.4.12 | julian_day の上限が拡張されました。 これより前のバージョンでは、アーキテクチャに関わらず、 2465342 が上限でした。

参考

  • unixtojd() - Unix タイムスタンプをユリウス歴に変換する


ユダヤ暦の日付けをユリウス積算日に変換する

  • ≪ jdtounix
  • juliantojd ≫
  • PHP Manual
  • カレンダー 関数
  • ユダヤ暦の日付けをユリウス積算日に変換する

jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — ユダヤ暦の日付けをユリウス積算日に変換する

説明

jewishtojd(int $month, int $day, int $year): int

この関数では1年(紀元前3761年)に遡って全ての日々を扱うこと が出来ますが、この様な使い方は特に意味があるわけではありません。 ユダヤ暦は数千年に渡って使われていますが、当初は月の 始まりが決められていませんでいた。新しい月は新月が最初に観測 された日に始まりました。

パラメータ

month

月を表す、1 から 13 までの数値。 1 は Tishri を、 13 s Elul という意味です。 そして 6 と 7 は 通常の年では Adar を意味していますが、 うるう年では Adar I と Adar II をそれぞれ意味しています。

day

日を表す、1 から 30 までの数値。 月が29日しかない場合、次の月のはじめの日と見なされます。

year

年を表す、1 から 9999 までの数値。

戻り値

指定したユダヤ暦の日付に対応するユリウス積算日を返します。

参考

  • jdtojewish() - ユリウス積算日をユダヤ暦に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する


ユリウス暦をユリウス積算日に変換する

  • ≪ jewishtojd
  • unixtojd ≫
  • PHP Manual
  • カレンダー 関数
  • ユリウス暦をユリウス積算日に変換する

juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — ユリウス暦をユリウス積算日に変換する

説明

juliantojd(int $month, int $day, int $year): int

ユリウス暦は紀元前 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() - サポートされるカレンダーからユリウス積算日に変換する


Unix タイムスタンプをユリウス歴に変換する

  • ≪ juliantojd
  • Date/Time ≫
  • PHP Manual
  • カレンダー 関数
  • Unix タイムスタンプをユリウス歴に変換する

unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Unix タイムスタンプをユリウス歴に変換する

説明

unixtojd(?int $timestamp = null): int|false

Unix タイムスタンプ(1970/1/1 からの秒数)timestamp をユリウス歴に変換して返します。timestamp が 指定されない場合は現在の日付が使用されます。 どちらの場合でも、時刻は地方時間と見なされます(UTCではありません)。

パラメータ

timestamp

変換したい Unix タイムスタンプ。

戻り値

ユリウス積算日を表す整数値を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

参考

  • jdtounix() - ユリウス歴を Unix タイムスタンプに変換する


日付・時刻

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
    • 日付/時刻 の算術
  • DateTime — DateTime クラス
    • DateTime::add — 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
    • DateTime::__construct — 新しい DateTime オブジェクトを返す
    • DateTime::createFromFormat — 指定した書式で時刻文字列をパースする
    • DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す
    • DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
    • DateTime::getLastErrors — DateTimeImmutable::getLastErrors のエイリアス
    • DateTime::modify — タイムスタンプを変更する
    • DateTime::__set_state — __set_state ハンドラ
    • DateTime::setDate — 日付を設定する
    • DateTime::setISODate — ISO 形式の日付を設定する
    • DateTime::setTime — 時刻を設定する
    • DateTime::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
    • DateTime::setTimezone — DateTime オブジェクトのタイムゾーンを設定する
    • DateTime::sub — 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTimeImmutable — DateTimeImmutable クラス
    • DateTimeImmutable::add — 年月日時分秒の値を加え、新しいオブジェクトを返す
    • DateTimeImmutable::__construct — 新しい DateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::createFromFormat — 時刻の文字列を指定されたフォーマットに従ってパースする
    • DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す
    • DateTimeImmutable::getLastErrors — 警告およびエラーを返す
    • DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る
    • DateTimeImmutable::__set_state — __set_state ハンドラ
    • DateTimeImmutable::setDate — 日付を設定する
    • DateTimeImmutable::setISODate — ISO 日付を設定する
    • DateTimeImmutable::setTime — 時刻を設定する
    • DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
    • DateTimeImmutable::setTimezone — タイムゾーンを設定する
    • DateTimeImmutable::sub — 年月日時分秒の値を引く
  • DateTimeInterface — DateTimeInterface インターフェイス
    • DateTimeInterface::diff — ふたつの DateTime オブジェクトの差を返す
    • DateTimeInterface::format — 指定した書式でフォーマットした日付を返す
    • DateTimeInterface::getOffset — タイムゾーンのオフセットを返す
    • DateTimeInterface::getTimestamp — Unix タイムスタンプを取得する
    • DateTimeInterface::getTimezone — 指定した DateTime に関連するタイムゾーンを返す
    • DateTime::__wakeup — __wakeup ハンドラ
  • DateTimeZone — DateTimeZone クラス
    • DateTimeZone::__construct — 新しい DateTimeZone オブジェクトを作成する
    • DateTimeZone::getLocation — タイムゾーンの位置情報を返す
    • DateTimeZone::getName — タイムゾーンの名前を返す
    • DateTimeZone::getOffset — GMT からのタイムゾーンのオフセットを返す
    • DateTimeZone::getTransitions — タイムゾーンの変遷を返す
    • DateTimeZone::listAbbreviations — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す
    • DateTimeZone::listIdentifiers — すべてのタイムゾーン識別子を含む配列を返す
  • DateInterval — DateInterval クラス
    • DateInterval::__construct — 新しい DateInterval オブジェクトを作成する
    • DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する
    • DateInterval::format — 間隔をフォーマットする
  • DatePeriod — DatePeriod クラス
    • DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する
    • DatePeriod::createFromISO8601String — ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する
    • DatePeriod::getDateInterval — 間隔を取得する
    • DatePeriod::getEndDate — 終了日を取得する
    • DatePeriod::getRecurrences — 繰り返しの数を取得する
    • DatePeriod::getStartDate — 開始日を取得する
  • 日付・時刻 関数
    • checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します
    • date — Unixタイムスタンプを書式化する
    • date_add — DateTime::add のエイリアス
    • date_create — 新しい DateTime オブジェクトを作成する
    • date_create_from_format — DateTime::createFromFormat のエイリアス
    • date_create_immutable — 新しい DateTimeImmutable オブジェクトを作成する
    • date_create_immutable_from_format — DateTimeImmutable::createFromFormat のエイリアス
    • date_date_set — DateTime::setDate のエイリアス
    • date_default_timezone_get — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する
    • date_default_timezone_set — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する
    • date_diff — DateTime::diff のエイリアス
    • date_format — DateTime::format のエイリアス
    • date_get_last_errors — DateTimeImmutable::getLastErrors のエイリアス
    • date_interval_create_from_date_string — DateInterval::createFromDateString のエイリアス
    • date_interval_format — DateInterval::format のエイリアス
    • date_isodate_set — DateTime::setISODate のエイリアス
    • date_modify — DateTime::modify のエイリアス
    • date_offset_get — DateTime::getOffset のエイリアス
    • date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す
    • date_parse_from_format — 指定した書式でフォーマットされた日付についての情報を取得する
    • date_sub — DateTime::sub のエイリアス
    • date_sun_info — 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す
    • date_sunrise — 指定した日付と場所についての日の出時刻を返す
    • date_sunset — 指定した日付と場所についての日の入り時刻を返す
    • date_time_set — DateTime::setTime のエイリアス
    • date_timestamp_get — DateTime::getTimestamp のエイリアス
    • date_timestamp_set — DateTime::setTimestamp のエイリアス
    • date_timezone_get — DateTime::getTimezone のエイリアス
    • date_timezone_set — DateTime::setTimezone のエイリアス
    • getdate — 日付/時刻情報を取得する
    • gettimeofday — 現在の時間を得る
    • gmdate — GMT/UTC の日付/時刻を書式化する
    • gmmktime — GMT 日付から Unix タイムスタンプを取得する
    • gmstrftime — ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする
    • idate — ローカルな時刻/日付の一部を整数として整形する
    • localtime — ローカルタイムを得る
    • microtime — 現在の Unix タイムスタンプをマイクロ秒まで返す
    • mktime — 日付を Unix のタイムスタンプとして取得する
    • strftime — ロケールの設定に基づいてローカルな日付・時間をフォーマットする
    • strptime — strftime が生成した日付/時刻をパースする
    • strtotime — 英文形式の日付を Unix タイムスタンプに変換する
    • time — 現在の Unix タイムスタンプを返す
    • timezone_abbreviations_list — DateTimeZone::listAbbreviations のエイリアス
    • timezone_identifiers_list — DateTimeZone::listIdentifiers のエイリアス
    • timezone_location_get — DateTimeZone::getLocation のエイリアス
    • timezone_name_from_abbr — 略称とUTCオフセットから、タイムゾーン名を推測して返す
    • timezone_name_get — DateTimeZone::getName のエイリアス
    • timezone_offset_get — DateTimeZone::getOffset のエイリアス
    • timezone_open — DateTimeZone::__construct のエイリアス
    • timezone_transitions_get — DateTimeZone::getTransitions のエイリアス
    • timezone_version_get — timezonedb のバージョンを取得する
  • 日付・時刻 に関するエラーと例外
  • サポートする日付と時刻の書式
  • サポートされるタイムゾーンのリスト
    • アフリカ
    • アメリカ
    • 南極
    • 北極
    • アジア
    • 大西洋
    • オーストラリア
    • ヨーロッパ
    • インド
    • 太平洋
    • その他
  • DateError — DateError クラス
  • DateObjectError — DateObjectError クラス
  • DateRangeError — DateRangeError クラス
  • DateException — DateException クラス
  • DateInvalidOperationException — DateInvalidOperationException クラス
  • DateInvalidTimeZoneException — DateInvalidTimeZoneException クラス
  • DateMalformedIntervalStringException — DateMalformedIntervalStringException クラス
  • DateMalformedPeriodStringException — DateMalformedPeriodStringException クラス
  • DateMalformedStringException — DateMalformedStringException クラス


はじめに

DateTimeImmutable と、 それに関連するクラスを使うと、日付/時刻 に関する情報を表現できます。 このオブジェクトは、日付/時刻 の文字列表現か、 現在のシステム時刻から作成できます。

この情報を変更したり、 フォーマット化するために豊富なメソッドが提供されています。 この情報には、タイムゾーンや夏時間の遷移情報も含まれます。

PHP の日付/時刻 は ISO 8601 のカレンダー、つまり » proleptic Gregorian calendar (先発グレゴリオ暦) を実装しています。 これは、現在のうるう年のルールをグレゴリオ暦より前であっても実装し、 -1 BCE と 1 CE の間を 0 年として扱います。 うるう秒はサポートされていません。

日付と時刻の情報は内部的には 64 ビット数値で保持されているので、 (負の年も含めて) 考え得る限りのあらゆる日付を扱うことができます。 扱える範囲は、過去およそ2920億年と未来の同じくらいの年です。

注意: この節で参照しているタイムゾーンは、 サポートされるタイムゾーンのリスト で見つけられます。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Date/Time
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

注意: 最新のタイムゾーンデータベースの取得

最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。


実行時設定

php.ini の設定により動作が変化します。

Date/Time 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
date.default_latitude | "31.7667" | INI_ALL |
date.default_longitude | "35.2333" | INI_ALL |
date.sunrise_zenith | "90.833333" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "90.583333" でした。
date.sunset_zenith | "90.833333" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "90.583333" でした。
date.timezone | "UTC" | INI_ALL | PHP 8.2 以降では、この値に無効な値や空文字列を設定すると、警告が発生します。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

date.default_latitude float

デフォルトの緯度。 赤道にあたる 0 から、 北緯は +90 まで、 南緯は -90 までの値をとります。

date.default_longitude float

デフォルトの経度。 グリニッジ子午線にあたる 0 から、 東経は +180 まで、 西経は ?180 までの値をとります。

date.sunrise_zenith float

デフォルトの日出点

デフォルト値は 90°50' です。 50' の値は、2つの要素からなります。 ひとつは太陽の視半径 16' です。 もうひとつは大気差の値で、34' です。

date.sunset_zenith float

デフォルトの日没点

date.timezone string

全ての日付/時刻関数で使用されるデフォルトのタイムゾーン。 明示的に指定しなかったときにどのタイムゾーンを利用するのかについての優先順位は date_default_timezone_get() のページで解説されています。サポートしているタイムゾーンについては サポートされるタイムゾーンのリスト を参照ください。

注意: 最初の 4 つの設定オプションは現時点で date_sunrise() と date_sunset() でのみ使用されます。


定義済み定数

DATE_* 定数 は、標準的な日付の書式を表します。 日付フォーマット関数（date() など）で使用します。

以下の定数は、関数 date_sunrise() および date_sunset() が返す結果の書式を指定します。

SUNFUNCS_RET_TIMESTAMP (int)
タイムスタンプ
SUNFUNCS_RET_STRING (int)
時:分 (例: 08:02)
SUNFUNCS_RET_DOUBLE (int)
時刻を表す浮動小数点値 (例 8.75)
DATE_* 定数
定数 | 説明
DATE_ATOM | Atom (例: 2005-08-15T15:52:01+00:00)
DATE_COOKIE | HTTP Cookies (例: Monday, 15-Aug-2005 15:52:01 UTC)
DATE_ISO8601 ISO-8601 (例: 2005-08-15T15:52:01+0000)

注意: このフォーマットは、ISO-8601 と互換性がありません。 しかし、後方互換性を保つために残されています。 ISO-8601 と互換性を保つためには、 DATE_ISO8601_EXPANDED, DATE_ATOM を使うようにしてください。 (ISO8601:2004 section 4.3.3 clause d も参照ください)

DATE_ISO8601_EXPANDED ISO-8601 拡張形式 (例: +10191-07-26T08:59:52+01:00)

注意: 年に常に符号を含めることで、ISO-8601 の通常の範囲 0000-9999 以外の値が許されています。 タイムゾーンの部分 (+01:00) については、 ISO-8601 と互換性をとるようにもなっています。

DATE_RFC822 | RFC 822 (例: Mon, 15 Aug 05 15:52:01 +0000)
DATE_RFC850 | RFC 850 (例: Monday, 15-Aug-05 15:52:01 UTC)
DATE_RFC1036 | RFC 1036 (例: Mon, 15 Aug 05 15:52:01 +0000)
DATE_RFC1123 | RFC 1123 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DATE_RFC7231 | RFC 7231 (as of PHP 7.0.19 and 7.1.5) (例: Sat, 30 Apr 2016 17:52:13 GMT)
DATE_RFC2822 | RFC 2822 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DATE_RFC3339 | DATE_ATOM と同じです
DATE_RFC3339_EXTENDED | RFC 3339 EXTENDED フォーマット (例: 2005-08-15T15:52:01.000+00:00)
DATE_RSS | RSS (例: Mon, 15 Aug 2005 15:52:01 +0000). のエイリアス DATE_RFC1123.
DATE_W3C | World Wide Web Consortium (例: 2005-08-15T15:52:01+00:00). のエイリアス DATE_RFC3339.


  • ≪ 定義済み定数
  • 日付/時刻 の算術 ≫
  • PHP Manual
  • Date/Time
  • 例

例

目次

  • 日付/時刻 の算術


日付/時刻 の算術

以下の例は、DST(夏時間) への移行や、 異なった日を持つ月に関する 日付/時刻 の算術の罠をいくつか紹介します。

例1 DateTimeImmutable::add/sub は、経過時間を含む区間を足してしまう

DST (夏時間) への移行タイミングをまたいで 24時間を足してしまうと、 (ほとんどのタイムゾーンでは) 23/25時間を足しているように見える

<?php
$dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->add(new DateInterval("PT3H"));
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
?>

上の例の出力は以下となります。

Start: 2015-11-01 00:00:00 -04:00
End:   2015-11-01 02:00:00 -05:00

例2 DateTimeImmutable::modify と strtotime を使い、個々のコンポーネントの値をインクリメント/デクリメントする

DST (夏時間) の移行のタイミングをまたいで24時間を足すと、日付/時刻 文字列に正確に24時間足されることになります (開始時刻と終了時刻が同じ移行ポイントにない場合) point).

<?php
$dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("+24 hours");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
?>

上の例の出力は以下となります。

Start: 2015-11-01 00:00:00 -04:00
End:   2015-11-02 00:00:00 -05:00

例3 時刻を引き算すると、日付がオーバー/アンダーフローする可能性がある

1月31日 + 1ヶ月 のような計算をすると、(うるう年のときは) 3月2日、 または (通常の年は) 3月3日になります。

<?php
echo "Normal year:\n"; // February has 28 days
$dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("+1 month");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

echo "Leap year:\n"; // February has 29 days
$dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("+1 month");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
?>

上の例の出力は以下となります。

Normal year:
Start: 2015-01-31 00:00:00 -05:00
End:   2015-03-03 00:00:00 -05:00
Leap year:
Start: 2016-01-31 00:00:00 -05:00
End:   2016-03-02 00:00:00 -05:00

次の月の最後の日を得るために(つまり、オーバーフローを避けるため)、 last day of フォーマットも利用できます。

<?php
echo "Normal year:\n"; // February has 28 days
$dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("last day of next month");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

echo "Leap year:\n"; // February has 29 days
$dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("last day of next month");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
?>

上の例の出力は以下となります。

Normal year:
Start: 2015-01-31 00:00:00 -05:00
End:   2015-02-28 00:00:00 -05:00
Leap year:
Start: 2016-01-31 00:00:00 -05:00
End:   2016-02-29 00:00:00 -05:00


DateTime クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

日付と時刻を表現するクラスです。

このクラスは、 DateTimeImmutable と同じ振る舞いをします。 但し、DateTime::modify() のような、 オブジェクトそのものを変更するメソッドが呼び出された時を除きます。

警告

DateTime クラスのメソッドをコールすると、 そのインスタンスにカプセル化された情報が変更されます。 そうした変更を防ぎたい場合には、新しいオブジェクトを作るために clone 演算子を使わなければいけません。 オブジェクトの変更を防ぐ、望ましい挙動をデフォルトで実現するには、 DateTime ではなく、 DateTimeImmutable を使います。

クラス概要

class DateTime implements DateTimeInterface {
/* 継承した定数 */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* メソッド */
public __construct(string $datetime = "now", ?DateTimeZone $timezone = null)
public add(DateInterval $interval): DateTime
public static createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false
public static createFromImmutable(DateTimeImmutable $object): static
public static createFromInterface(DateTimeInterface $object): DateTime
public modify(string $modifier): DateTime|false
public static __set_state(array $array): DateTime
public setDate(int $year, int $month, int $day): DateTime
public setISODate(int $year, int $week, int $dayOfWeek = 1): DateTime
public setTime(
int $hour,
int $minute,
int $second = 0,
int $microsecond = 0
): DateTime
public setTimestamp(int $timestamp): DateTime
public setTimezone(DateTimeZone $timezone): DateTime
public sub(DateInterval $interval): DateTime
public diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval
public format(string $format): string
public getOffset(): int
public getTimestamp(): int
public getTimezone(): DateTimeZone|false
public __wakeup(): void
}

変更履歴

バージョン | 説明
7.2.0 | DateTime クラスの定数は、 DateTimeInterface で定義されるようになりました。
7.1.0 | DateTime のコンストラクタで構築される値に、 現在時刻のマイクロ秒が含まれるようになりました。 これより前のバージョンでは、このマイクロ秒の情報は常に 0 で初期化されていました。

目次

  • DateTime::add — 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
  • DateTime::__construct — 新しい DateTime オブジェクトを返す
  • DateTime::createFromFormat — 指定した書式で時刻文字列をパースする
  • DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す
  • DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
  • DateTime::getLastErrors — DateTimeImmutable::getLastErrors のエイリアス
  • DateTime::modify — タイムスタンプを変更する
  • DateTime::__set_state — __set_state ハンドラ
  • DateTime::setDate — 日付を設定する
  • DateTime::setISODate — ISO 形式の日付を設定する
  • DateTime::setTime — 時刻を設定する
  • DateTime::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTime::setTimezone — DateTime オブジェクトのタイムゾーンを設定する
  • DateTime::sub — 年月日時分秒の値を DateTime オブジェクトから引く


年月日時分秒の値を加えることで、DateTime オブジェクトを変更する

  • ≪ DateTime
  • DateTime::__construct ≫
  • PHP Manual
  • DateTime
  • 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する

DateTime::add

date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する

説明

オブジェクト指向型

public DateTime::add(DateInterval $interval): DateTime

手続き型

date_add(DateTime $object, DateInterval $interval): DateTime

指定した DateInterval オブジェクトを、 指定した DateTime オブジェクトに加えます。

DateTimeImmutable::add() と似ていますが、 DateTime オブジェクトを使って動作します。

手続き型のバージョンは、 DateTime を最初の引数に取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

interval

DateInterval オブジェクト

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

参考

  • DateTimeImmutable::add() - 年月日時分秒の値を加え、新しいオブジェクトを返す


新しい DateTime オブジェクトを返す

  • ≪ DateTime::add
  • DateTime::createFromFormat ≫
  • PHP Manual
  • DateTime
  • 新しい DateTime オブジェクトを返す

DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — 新しい DateTime オブジェクトを返す

説明

public DateTime::__construct(string $datetime = "now", ?DateTimeZone $timezone = null)

DateTimeImmutable::__construct() と似ていますが、 DateTime を用いて動作します。 DateTimeImmutable を代わりに使うことを検討して下さい。

新しい DateTime オブジェクトを返します。

パラメータ

datetime

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

ここに "now" を指定して $timezone パラメータを使うと、現在時刻を取得できます。

timezone

$datetime のタイムゾーンを表す DateTimeZone オブジェクト。

$timezone を省略した場合、または null の場合、 現在のタイムゾーンを使います。

注意:

$datetime パラメータが UNIX タイムスタンプ (@946684800 など) であったりタイムゾーンつきで指定した場合 (2010-01-28T15:00:00+02:00 など) は、 $timezone パラメータや現在のタイムゾーンは無視されます。

戻り値

新しい DateTime のインスタンスを返します。

エラー / 例外

無効な日付/時刻の文字列が渡された場合、 DateMalformedStringException がスローされます。 PHP 8.3 より前のバージョンでは、 Exception がスローされていました。

変更履歴

バージョン | 説明
8.3.0 | 無効な文字列が渡された場合、 Exception ではなく DateMalformedStringException がスローされるようになりました。

参考

  • DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す


指定した書式で時刻文字列をパースする

  • ≪ DateTime::__construct
  • DateTime::createFromImmutable ≫
  • PHP Manual
  • DateTime
  • 指定した書式で時刻文字列をパースする

DateTime::createFromFormat

date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — 指定した書式で時刻文字列をパースする

説明

オブジェクト指向型

public static DateTime::createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

手続き型

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

新しい DateTime オブジェクトを返します。 このオブジェクトは、datetime で指定した文字列を format で指定した書式に沿って解釈した時刻を表します。

DateTimeImmutable::createFromFormat() や date_create_immutable_from_format() と似ていますが、 DateTime オブジェクトを生成します。

このメソッドドキュメントは、パラメータや使用例、注意点も含めて DateTimeImmutable::createFromFormat のページにあります。

パラメータ

DateTimeImmutable::createFromFormat も参照ください。

戻り値

新しい DateTime のインスタンスを返します。失敗した場合に false を返します。

エラー / 例外

datetime に NULLバイトが含まれている場合は、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.21, 8.1.8, 8.2.0 | datetime に NULLバイトが含まれている場合は、 ValueError がスローされるようになりました。 これより前のバージョンでは、こうした値は静かに無視されていました。

例

豊富な例が、DateTimeImmutable::createFromFormat のページにあるので参照ください。

参考

  • DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする


与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す

  • ≪ DateTime::createFromFormat
  • DateTime::createFromInterface ≫
  • PHP Manual
  • DateTime
  • 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す

DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す

説明

public static DateTime::createFromImmutable(DateTimeImmutable $object): static

パラメータ

object

変更可能なバージョンに変換が必要な、 DateTimeImmutable オブジェクト。 このオブジェクトは変更されませんが、 代わりに同じ日付、時刻、タイムゾーンの情報を含んだ 新しい DateTime のインスタンスが作られます。

戻り値

新しい DateTime インスタンスを返します。

変更履歴

バージョン | 説明
8.0.0 | このメソッドは、現在呼び出されたクラスのインスタンスを返すようになりました。 これより前のバージョンでは、 新しい DateTime のインスタンスを生成していました。

例

例1 変更可能な日付オブジェクトを作る

<?php
$date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");

$mutable = DateTime::createFromImmutable( $date );
?>


指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

  • ≪ DateTime::createFromImmutable
  • DateTime::getLastErrors ≫
  • PHP Manual
  • DateTime
  • 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

説明

public static DateTime::createFromInterface(DateTimeInterface $object): DateTime

パラメータ

object

変更可能なバージョンに変換する DateTimeInterface オブジェクト。 このオブジェクトは変更されませんが、 同じ日付、時刻、タイムゾーンの情報が入った新しい DateTime オブジェクトが作成されます。

戻り値

新しいDateTime クラスのインスタンスを返します。

例

例1 変更可能な DateTime オブジェクトを作る

<?php
$date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");

$mutable = DateTime::createFromInterface($date);

$date = new DateTime("2014-06-20 11:45 Europe/London");
$also_mutable = DateTime::createFromInterface($date);
?>


DateTimeImmutable::getLastErrors のエイリアス

  • ≪ DateTime::createFromInterface
  • DateTime::modify ≫
  • PHP Manual
  • DateTime
  • DateTimeImmutable::getLastErrors のエイリアス

DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — DateTimeImmutable::getLastErrors() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::getLastErrors()


タイムスタンプを変更する

  • ≪ DateTime::getLastErrors
  • DateTime::__set_state ≫
  • PHP Manual
  • DateTime
  • タイムスタンプを変更する

DateTime::modify

date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — タイムスタンプを変更する

説明

オブジェクト指向型

public DateTime::modify(string $modifier): DateTime|false

手続き型

date_modify(DateTime $object, string $modifier): DateTime|false

DateTimeImmutable::__construct() 形式で加算あるいは減算することによって DateTime オブジェクトのタイムスタンプを変更します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

modifier

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。失敗した場合に false を返します。

エラー / 例外

オブジェクト指向のAPIのみ、 無効な日付/時刻の文字列が渡された場合に DateMalformedStringException がスローされます。

変更履歴

バージョン | 説明
8.3.0 | 無効な文字列が渡された場合、DateTime::modify() については警告を発生させるのではなく DateMalformedStringException がスローされるようになりました。 date_modify() は変更されていません。

例

例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

例3 全ての日付と時刻のフォーマットがサポートされています

<?php
$date = new DateTime('2020-12-31');

$date->modify('July 1st, 2023');
echo $date->format('Y-m-d H:i') . "\n";

$date->modify('Monday next week');
echo $date->format('Y-m-d H:i') . "\n";

$date->modify('17:30');
echo $date->format('Y-m-d H:i') . "\n";
?>

上の例の出力は以下となります。

2023-07-01 00:00
2023-07-03 00:00
2023-07-03 17:30

参考

  • strtotime() - 英文形式の日付を Unix タイムスタンプに変換する
  • DateTimeImmutable::modify() - タイムスタンプを変更した新しいオブジェクトを作る
  • DateTime::add() - 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTime::setDate() - 日付を設定する
  • DateTime::setISODate() - ISO 形式の日付を設定する
  • DateTime::setTime() - 時刻を設定する
  • DateTime::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する


__set_state ハンドラ

  • ≪ DateTime::modify
  • DateTime::setDate ≫
  • PHP Manual
  • DateTime
  • __set_state ハンドラ

DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — __set_state ハンドラ

説明

public static DateTime::__set_state(array $array): DateTime

__set_state() ハンドラを処理します。

DateTimeImmutable::__set_state() に似ていますが、 DateTime を使って動作します。

パラメータ

array

初期化配列。

戻り値

新しい DateTime オブジェクトのインスタンスを返します。


日付を設定する

  • ≪ DateTime::__set_state
  • DateTime::setISODate ≫
  • PHP Manual
  • DateTime
  • 日付を設定する

DateTime::setDate

date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — 日付を設定する

説明

オブジェクト指向型

public DateTime::setDate(int $year, int $month, int $day): DateTime

手続き型

date_date_set(
DateTime $object,
int $year,
int $month,
int $day
): DateTime

DateTime オブジェクトの現在の日付をリセットし、別の日付にします。

DateTimeImmutable::setDate() に似ていますが、 DateTime を用いて動作し、 既存のオブジェクトを変更します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数として取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

month

その日付の月。

day

その日付の日。

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

参考

  • DateTimeImmutable::setDate() - 日付を設定する


ISO 形式の日付を設定する

  • ≪ DateTime::setDate
  • DateTime::setTime ≫
  • PHP Manual
  • DateTime
  • ISO 形式の日付を設定する

DateTime::setISODate

date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — ISO 形式の日付を設定する

説明

オブジェクト指向型

public DateTime::setISODate(int $year, int $week, int $dayOfWeek = 1): DateTime

手続き型

date_isodate_set(
DateTime $object,
int $year,
int $week,
int $dayOfWeek = 1
): DateTime

ISO 8601 標準形式、つまり特定の日付ではなく、週と日のオフセットで日付を設定します。

DateTimeImmutable::setISODate() に似ていますが、 DateTime を使って動作します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数に取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

week

その日付の週。

dayOfWeek

週の最初の日からのオフセット。

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

参考

  • DateTimeImmutable::setISODate() - ISO 日付を設定する


時刻を設定する

  • ≪ DateTime::setISODate
  • DateTime::setTimestamp ≫
  • PHP Manual
  • DateTime
  • 時刻を設定する

DateTime::setTime

date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — 時刻を設定する

説明

オブジェクト指向型

public DateTime::setTime(
int $hour,
int $minute,
int $second = 0,
int $microsecond = 0
): DateTime

手続き型

date_time_set(
DateTime $object,
int $hour,
int $minute,
int $second = 0,
int $microsecond = 0
): DateTime

DateTime オブジェクトの現在時刻を別の時刻にリセットします。

DateTimeImmutable::setTime() に似ていますが、 DateTime を使って動作します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数として取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

hour

その時刻の時。

minute

その時刻の分。

second

その時刻の秒。

microsecond

その時刻のマイクロ秒。

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

変更履歴

バージョン | 説明
8.1.0 | (夏時間遷移のフォールバック期間中に) 二重に存在する hour に関する振る舞いが変更されました。 これより前のバージョンでは、 (夏時間遷移が起こる前の)最初の hour ではなく、 (夏時間遷移が起きた後の)二番目の hour を取得していました。
7.1.0 | パラメータ microsecond が追加されました。

参考

  • DateTimeImmutable::setTime() - 時刻を設定する


Unix タイムスタンプを用いて日付と時刻を設定する

  • ≪ DateTime::setTime
  • DateTime::setTimezone ≫
  • PHP Manual
  • DateTime
  • Unix タイムスタンプを用いて日付と時刻を設定する

DateTime::setTimestamp

date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Unix タイムスタンプを用いて日付と時刻を設定する

説明

オブジェクト指向型

public DateTime::setTimestamp(int $timestamp): DateTime

手続き型

date_timestamp_set(DateTime $object, int $timestamp): DateTime

Unix タイムスタンプを用いて日付と時刻を設定します。

DateTimeImmutable::setTimestamp() に似ていますが、 DateTime を使って動作します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数に取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

timestamp

日付を表す Unix タイムスタンプ。 DateTimeImmutable::modify() を @ フォーマットと共に使うと、 数値型の範囲外のタイムスタンプを設定できます。

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

参考

  • DateTimeImmutable::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する


DateTime オブジェクトのタイムゾーンを設定する

  • ≪ DateTime::setTimestamp
  • DateTime::sub ≫
  • PHP Manual
  • DateTime
  • DateTime オブジェクトのタイムゾーンを設定する

DateTime::setTimezone

date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — DateTime オブジェクトのタイムゾーンを設定する

説明

オブジェクト指向型

public DateTime::setTimezone(DateTimeZone $timezone): DateTime

手続き型

date_timezone_set(DateTime $object, DateTimeZone $timezone): DateTime

新しいタイムゾーンを DateTime オブジェクトに設定します。

DateTimeImmutable::setTimezone() に似ていますが、 DateTime を使って動作します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数に取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

戻り値

メソッドをチェインできるようにするため、 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

参考

  • DateTimeImmutable::setTimezone() - タイムゾーンを設定する
  • DateTime::getTimezone() - 指定した DateTime に関連するタイムゾーンを返す
  • DateTimeZone::__construct() - 新しい DateTimeZone オブジェクトを作成する


年月日時分秒の値を DateTime オブジェクトから引く

  • ≪ DateTime::setTimezone
  • DateTimeImmutable ≫
  • PHP Manual
  • DateTime
  • 年月日時分秒の値を DateTime オブジェクトから引く

DateTime::sub

date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — 年月日時分秒の値を DateTime オブジェクトから引く

説明

オブジェクト指向型

public DateTime::sub(DateInterval $interval): DateTime

手続き型

date_sub(DateTime $object, DateInterval $interval): DateTime

指定した DateInterval オブジェクトを引くことで、 指定した DateTime オブジェクトを変更します。

DateTimeImmutable::sub() に似ていますが、 DateTime を使って動作します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数に取ります。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

interval

DateInterval オブジェクト。

戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

エラー / 例外

オブジェクト指向のAPIのみ、 サポートされていない操作を試みた場合に DateInvalidOperationException がスローされます。 サポートされていない操作の例としては、 next weekday のような相対時刻を表現する DateInterval を使った場合が挙げられます。

変更履歴

バージョン | 説明
8.3.0 | サポートされていない操作を試みた場合に、警告を発生させるのではなく、 DateInvalidOperationException がスローされるようになりました。 date_sub() は変更されていません。

参考

  • DateTimeImmutable::sub() - 年月日時分秒の値を引く


DateTimeImmutable クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

日付と時刻を表現します。

このクラスは DateTime と同じ振る舞いをします。 但し、DateTime::modify() のような、 状態を変更して新しいオブジェクトを返すメソッドが呼び出された時を除きます。

クラス概要

class DateTimeImmutable implements DateTimeInterface {
/* 継承した定数 */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* メソッド */
public __construct(string $datetime = "now", ?DateTimeZone $timezone = null)
public add(DateInterval $interval): DateTimeImmutable
public static createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false
public static createFromInterface(DateTimeInterface $object): DateTimeImmutable
public static createFromMutable(DateTime $object): static
public static getLastErrors(): array|false
public modify(string $modifier): DateTimeImmutable|false
public static __set_state(array $array): DateTimeImmutable
public setDate(int $year, int $month, int $day): DateTimeImmutable
public setISODate(int $year, int $week, int $dayOfWeek = 1): DateTimeImmutable
public setTime(
int $hour,
int $minute,
int $second = 0,
int $microsecond = 0
): DateTimeImmutable
public setTimestamp(int $timestamp): DateTimeImmutable
public setTimezone(DateTimeZone $timezone): DateTimeImmutable
public sub(DateInterval $interval): DateTimeImmutable
public diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval
public format(string $format): string
public getOffset(): int
public getTimestamp(): int
public getTimezone(): DateTimeZone|false
public __wakeup(): void
}

変更履歴

バージョン | 説明
7.1.0 | DateTimeImmutable のコンストラクタで構築される値に、 現在時刻のマイクロ秒が含まれるようになりました。 これより前のバージョンでは、このマイクロ秒の情報は常に 0 で初期化されていました。

目次

  • DateTimeImmutable::add — 年月日時分秒の値を加え、新しいオブジェクトを返す
  • DateTimeImmutable::__construct — 新しい DateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::createFromFormat — 時刻の文字列を指定されたフォーマットに従ってパースする
  • DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す
  • DateTimeImmutable::getLastErrors — 警告およびエラーを返す
  • DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る
  • DateTimeImmutable::__set_state — __set_state ハンドラ
  • DateTimeImmutable::setDate — 日付を設定する
  • DateTimeImmutable::setISODate — ISO 日付を設定する
  • DateTimeImmutable::setTime — 時刻を設定する
  • DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTimeImmutable::setTimezone — タイムゾーンを設定する
  • DateTimeImmutable::sub — 年月日時分秒の値を引く


年月日時分秒の値を加え、新しいオブジェクトを返す

  • ≪ DateTimeImmutable
  • DateTimeImmutable::__construct ≫
  • PHP Manual
  • DateTimeImmutable
  • 年月日時分秒の値を加え、新しいオブジェクトを返す

DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — 年月日時分秒の値を加え、新しいオブジェクトを返す

説明

public DateTimeImmutable::add(DateInterval $interval): DateTimeImmutable

新しい DateTimeImmutable オブジェクトを作成し、 指定された DateInterval をこれに加え、 新しい値を返します。

パラメータ

interval

DateInterval オブジェクト。

戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

例

例1 DateTimeImmutable::add() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable('2000-01-01');
$newDate = $date->add(new DateInterval('P10D'));
echo $newDate->format('Y-m-d') . "\n";
?>

例2 DateTimeImmutable::add() の高度な例

<?php
$date = new DateTimeImmutable('2000-01-01');
$newDate = $date->add(new DateInterval('PT10H30S'));
echo $newDate->format('Y-m-d H:i:s') . "\n";

$date = new DateTimeImmutable('2000-01-01');
$newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S'));
echo $newDate->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2000-01-01 10:00:30
2007-06-05 04:03:02

例3 月を足す場合は注意

<?php
$date = new DateTimeImmutable('2000-12-31');
$interval = new DateInterval('P1M');

$newDate1 = $date->add($interval);
echo $newDate1->format('Y-m-d') . "\n";

$newDate2 = $newDate1->add($interval);
echo $newDate2->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-01-31
2001-03-03

参考

  • DateTimeImmutable::sub() - 年月日時分秒の値を引く
  • DateTimeImmutable::diff() - ふたつの DateTime オブジェクトの差を返す
  • DateTimeImmutable::modify() - タイムスタンプを変更した新しいオブジェクトを作る


新しい DateTimeImmutable オブジェクトを返す

  • ≪ DateTimeImmutable::add
  • DateTimeImmutable::createFromFormat ≫
  • PHP Manual
  • DateTimeImmutable
  • 新しい DateTimeImmutable オブジェクトを返す

DateTimeImmutable::__construct

date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — 新しい DateTimeImmutable オブジェクトを返す

説明

オブジェクト指向型

public DateTimeImmutable::__construct(string $datetime = "now", ?DateTimeZone $timezone = null)

手続き型

date_create_immutable(string $datetime = "now", ?DateTimeZone $timezone = null): DateTimeImmutable|false

新しい DateTimeImmutable オブジェクトを返します。

パラメータ

datetime

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

ここに "now" を指定して $timezone パラメータを使うと、現在時刻を取得できます。

timezone

$datetime のタイムゾーンを表す DateTimeZone オブジェクト。

$timezone を省略した場合、 または null の場合、 現在のタイムゾーンを使います。

注意:

$datetime パラメータが UNIX タイムスタンプ (@946684800 など) であったりタイムゾーン付きで指定した場合 (2010-01-28T15:00:00+02:00 や 2010-07-05T06:00:00Z など) は、 $timezone パラメータや現在のタイムゾーンは無視されます。

戻り値

新しい DateTimeImmutable のインスタンスを返します。

エラー / 例外

無効な日付/時刻の文字列が渡された場合、 DateMalformedStringException がスローされます。 PHP 8.3 より前のバージョンでは、 Exception がスローされていました。

変更履歴

バージョン | 説明
8.3.0 | 無効な文字列が渡された場合、 Exception ではなく DateMalformedStringException がスローされるようになりました。
7.1.0 | マイクロ秒が '00000' ではなく、実際の値で埋められるようになりました。

例

例1 DateTimeImmutable::__construct() の例

オブジェクト指向型

<?php
try {
$date = new DateTimeImmutable('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 DateTimeImmutable::__construct() の複雑な例

<?php
// そのコンピュータのタイムゾーンでの日時の指定
$date = new DateTimeImmutable('2000-01-01');
echo $date->format('Y-m-d H:i:sP') . "\n";

// 指定したタイムゾーンでの日時の指定
$date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

// そのコンピュータのタイムゾーンでの現在日時
$date = new DateTimeImmutable();
echo $date->format('Y-m-d H:i:sP') . "\n";

// 指定したタイムゾーンでの現在日時
$date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

// UNIX タイムスタンプの使用例。結果のタイムゾーンは UTC となることに注意しましょう。
$date = new DateTimeImmutable('@946684800');
echo $date->format('Y-m-d H:i:sP') . "\n";

// 存在しない値は繰り上がります
$date = new DateTimeImmutable('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

例3 関連付けられたタイムゾーンを変更する

<?php
$timeZone = new \DateTimeZone('Asia/Tokyo');
$time = new \DateTimeImmutable();
$time = $time->setTimezone($timeZone);
echo $time->format('Y/m/d H:i:s'), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2022/08/12 23:49:23

例4 相対日付/時刻 の文字列を使う

<?php
$time = new \DateTimeImmutable("-1 year");
echo $time->format('Y/m/d H:i:s'), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2021/08/12 15:43:51


時刻の文字列を指定されたフォーマットに従ってパースする

  • ≪ DateTimeImmutable::__construct
  • DateTimeImmutable::createFromInterface ≫
  • PHP Manual
  • DateTimeImmutable
  • 時刻の文字列を指定されたフォーマットに従ってパースする

DateTimeImmutable::createFromFormat

date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — 時刻の文字列を指定されたフォーマットに従ってパースする

説明

オブジェクト指向型

public static DateTimeImmutable::createFromFormat(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false

手続き型

date_create_immutable_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTimeImmutable|false

新しい DateTimeImmutable オブジェクトを返します。 このオブジェクトは、datetime で指定した文字列を format で指定した書式に沿って解釈した時刻を表します。

パラメータ

format

書式を文字列で渡します。以下の書式オプションを参照ください。 大半は、date() で使える文字と同じです。

全てのフィールドは現在の日付/時刻で初期化されます。 ほとんどの場合、これらの値を "ゼロ" (Unix タイムのエポック 1970-01-01 00:00:00 UTC) でリセットしたいはずです。 これは、format の最初の文字に ! を入れるか、 最後の文字に | を入れることで実現できます。 詳細な情報は、以下で示すそれぞれの文字に関するドキュメントを参照ください。

フォーマットの解釈は左から右に行われます。 これは、フォーマット文字が現れる順番が結果に影響する場合があるということです。 たとえば z(1年における何番目の日か)　の場合、 Y や y を使って年が既にパースされた後に使わなければなりません。

数値の解釈に使われる文字については、広範な値が許されています。 これには、論理的に許される範囲以上のものも含みます。 たとえば、d (ある月における何番目の日か) の場合、 00 から 99 までの値が許されています。これに対する唯一の制約は、桁数のみです。 範囲外の値が指定された場合、 日付/時刻のパーサーのオーバーフローの仕組みが使われます。 オーバーフローのふるまいについては、 後にいくつかのサンプルを示します。

データは、フォーマット文字に従って貪欲にパースされます。 つまり、そのフォーマットが許している最大の長さまで読みこまれます。 これによって、次のフォーマット文字に十分な文字数が datetime にもう残っていないことがありえます。 このことが引き起こす問題については、このページのサンプルでも触れます。

format パラメータに渡せる文字
format 文字 | 説明 | 取りうる値の例
日 --- ---
d および j | 2桁の日付。先頭のゼロを含むものと含まないもの | 01 から 31 あるいは 1 から 31 (その月の日数分以上の2桁の数値も指定可能ですが、 その月はオーバーフローします。 たとえば January において 33 を指定した場合、 February 2nd という意味になります)
D および l | 曜日を表す文字列 | Mon から Sun あるいは Sunday から Saturday。 指定された曜日が、パースされた(またはデフォルトの)日付と異なっていた場合、 指定された曜日の 次の 日にオーバーフローします。詳細は後に示すサンプルを参照ください。
S | 日付の後につける英語の接尾辞。二文字。処理中には無視されます。 | st、nd、rd あるいは th
z | 年始からの通算日数 (最初は 0)。 Y または y の後に続けて置かなければいけません。 | 0 から 365 (1年の日数分以上の3桁の数値も指定可能ですが、 その年はオーバーフローします。 たとえば 2022年において 366 を指定した場合は、 January 2nd, 2023 という意味になります)
月 --- ---
F および M | 月を表す文字列。January あるいは Sept など | January から December あるいは Jan から Dec
m および n | 月を表す数値。先頭のゼロを含むものと含まないもの | 01 から 12 あるいは 1 から 12 (12 以上の2桁の数値も指定可能ですが、 その年についてはオーバーフローします。 たとえば 13 の場合は、 翌年の1月という意味になります)
年 --- ---
X および x | 年の数値表現。19桁まで指定可能。オプションで + や - を先頭に指定可能です。 | 例: 0055, 787, 1999, -2003, +10191
Y | 4 桁以下の数値で表した年 | 例: 0055, 787, 1999, 2003
y | 2 桁の数値で表した年 (1970年から2069年の間だとみなされます) | 例: 99 あるいは 03 (それぞれ、 1999 および 2003 と見なされます)
時刻 --- ---
a および A | 午前および午後 | am あるいは pm
g および h | 12 時間制での時間。先頭のゼロを含むものと含まないもの | 1 から 12 あるいは 01 から 12 (12 以上の2桁の数値も指定可能ですが、 日の指定がオーバーフローします。 たとえば 14 の場合は、 次の午前/午後の 02 時という意味になります)
G および H | 24 時間制での時間。先頭のゼロを含むものと含まないもの | 0 から 23、あるいは 00 から 23 (24 より大きな、2桁の値も指定可能ですが、 この場合、日の指定がオーバーフローします。 たとえば、26 は翌日の 02:00 という意味になります)
i | 分。先頭のゼロを含む | 00 から 59 (59 以上の2桁の数値も指定可能ですが、 次の1時間にオーバーフローします。 たとえば 66 の場合は、 次の1時間の :06 という意味になります)
s | 秒。先頭のゼロを含む | 00 から 59 (59 以上の2桁の数値も指定可能ですが、 次の分にオーバーフローします。 たとえば 90 の場合は、 次の分の :30 という意味になります)
v | ミリ秒 (最大 3桁) | 例: 12 (0.12 秒という意味), 345 (0.345 秒という意味)
u | マイクロ秒 (最大 6 桁) | 例: 45 (0.45 秒という意味), 654321 (0.654321 秒という意味)
タイムゾーン --- ---
e, O, p, P および T | タイムゾーン識別子、UTC からの時差 (時間単位)、 UTC からの時差 (コロン区切りでの時間と分)、そしてタイムゾーンの短縮形 | 例: UTC、GMT、 Atlantic/Azores、 +0200、+02:00、 EST、MDT
完全な日付/時刻 --- ---
U | Unix エポック (January 1 1970 00:00:00 GMT) からの経過秒数 | 例: 1292177455
空白および区切り --- ---
(空白) | ゼロ文字以上のスペース、タブ、NBSP(U+A0)、NNBSP(U+202F) | 例: "\t", " "
# 次の区切り文字のいずれか: ;, :, /, ., ,, -, (, ) 例: /
;, :, /, ., ,, -, (, ) 指定した文字 例: -
? ランダムなバイト 例: ^ (UTF-8 文字の場合は複数の ? が必要になるでしょう。この場合、おそらく * を使うと要望が満たせるはずです)
* 次の区切り文字あるいは数字までのランダムなバイト列 例: Y-*-d の中の * は、文字列 2009-aWord-08 の中の aWord にマッチします
! すべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を ゼロ相当の値 (時、分、秒、マイクロ秒については 0。 月、日については 1。 年については 1970。 タイムゾーンについては UTC) にリセットします。 ! がなければ、すべてのフィールドは現在の日時に設定されます。
| まだパースされていないすべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を ゼロ相当の値にリセットします。 Y-m-d| は、文字列をパースした結果から年月日を設定し 時分秒には 0 を設定します。
+ この文字があると、文字列のそれ以降のデータではエラーが発生せず、 かわりに警告を発生させる それ以降のデータが存在したかどうかを調べるには DateTime::getLastErrors() を使います。

書式文字列の中に解釈不能な文字が含まれていると処理は失敗し、 戻り値にはエラーメッセージが付加されます。エラーメッセージを調べるには DateTime::getLastErrors() を使います。

format にリテラル文字を含めるには、 バックスラッシュ (\) でエスケープする必要があります。

format に文字 ! が含まれない場合は、作成した時刻値のうち format で指定されていない部分を 現在のシステム時刻で初期化します。

format に文字 ! が含まれる場合は、作成した時刻値のうち format で指定されていない部分と ! の左側の部分を Unix エポックの対応する箇所の値で初期化します。

Unix エポックは 1970-01-01 00:00:00 です。

datetime

時刻を表す文字列。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

timezone を省略されるか、または null の場合、 かつ datetime にタイムゾーンが含まれない場合は、 現在のタイムゾーンを使います。

注意:

datetime パラメータが UNIX タイムスタンプ (例: 946684800) だったり、タイムゾーンを含んでいたり (例: 2010-01-28T15:00:00+02:00) する場合は、 timezone パラメータや現在のタイムゾーンは無視します。

戻り値

新しい DateTimeImmutable のインスタンスを返します。 失敗した場合に false を返します.

エラー / 例外

datetime に NULLバイトが含まれている場合は、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.2.9 | (空白) 文字は、 新たに NBSP(U+A0) と NNBSP(U+202F) をサポートするようになりました。
8.2.0 | format に指定できる文字に、 X と x が追加されました。
8.0.21, 8.1.8, 8.2.0 | datetime に NULLバイトが含まれている場合は、 ValueError がスローされるようになりました。 これより前のバージョンでは、こうした値は静かに無視されていました。
7.3.0 | format に指定できる文字に、 v が追加されました。

例

例1 DateTimeImmutable::createFromFormat() の例

オブジェクト指向型

<?php
$date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>

例2 定義済みのフォーマットの定数を DateTimeImmutable::createFromFormat() で使う

オブジェクト指向型

<?php
$date = DateTimeImmutable::createFromFormat(DateTimeInterface::ISO8601, '2004-02-12T15:19:21+00:00');
$date = DateTimeImmutable::createFromFormat(DateTimeInterface::RFC3339_EXTENDED, '2013-10-14T09:00:00.000+02:00');
?>

この例で使われている 定義済みの定数 は、DateTimeImmutable の フォーマット 文字からなる文字列です。 ほとんどの場合、それらのフォーマット文字は 上の パラメータ で定義されている 日付/時刻 の要素とマッチしますが、 カバーしている範囲は狭いです。

例3 DateTimeImmutable::createFromFormat() の複雑な例

<?php
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTimeImmutable::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 = DateTimeImmutable::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 = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'i';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Current time: 2022-06-02 15:50:46
Format: Y-m-d; 2009-02-15 15:50:46
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
Format: i; 2022-06-02 00:15:00

例4 リテラル文字を含む書式文字列

<?php
echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
?>

上の例の出力は、 たとえば以下のようになります。

23:15:03

例5 オーバーフローした際のふるまい

<?php
echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);
?>

上の例の出力は、 たとえば以下のようになります。

Sat, 04 Jun 2022 17:01:37 +0000

上の結果は奇妙に見えますが、正しい動作です。 なぜなら、以下のようなオーバーフローが発生しているからです:

  1. 97 秒は 1 分オーバーフローしており、37 秒が残ります。
  2. 61 分は 1 時間オーバーフローしており、1 分が残ります。
  3. 35 日は、1 ヶ月分オーバーフローしており、4 日が残ります。 どれだけの日が残るかは月に依存します。 なぜなら、すべての月が同じ日数を持つとは限らないからです。
  4. 18 ヶ月は、1 年分オーバーフローしており、6 ヶ月が残ります。

例6 曜日がオーバーフローした場合のふるまい

<?php
$d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
echo $d->format(DateTime::RFC1123), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Mon, 10 Aug 2020 01:00:00 +0000

上の結果は奇妙に見えますが、正しい動作です。 なぜなら、以下のようなオーバーフローが発生しているからです:

  1. 3 Aug 2020 25:00:00 はオーバーフローしており、(Tue) 4 Aug 2020 01:00 となります。
  2. Mon が適用されます。 これは、日付が Mon, 10 Aug 2020 01:00:00 まで進むからです。 Mon のような相対的なキーワード指定については、 相対的な書式 で説明されています。

日付のオーバーフローを検出するために、 DateTimeImmutable::getLastErrors() が使えます。 このメソッドの結果には、オーバーフローが発生した場合に警告が含まれます。

例7 オーバーフローした日付を検出する

<?php
$d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

var_dump(DateTimeImmutable::GetLastErrors());
?>

上の例の出力は、 たとえば以下のようになります。

Sat, 04 Jun 2022 17:01:37 +0000

array(4) {
  'warning_count' =>
  int(2)
  'warnings' =>
  array(1) {
    [19] =>
    string(27) "The parsed date was invalid"
  }
  'error_count' =>
  int(0)
  'errors' =>
  array(0) {
  }
}

例8 貪欲なパースの振る舞い

<?php
print_r(date_parse_from_format('Gis', '60101'));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [year] =>
    [month] =>
    [day] =>
    [hour] => 60
    [minute] => 10
    [second] => 0
    [fraction] => 0
    [warning_count] => 1
    [warnings] => Array
        (
            [5] => The parsed time was invalid
        )

    [error_count] => 1
    [errors] => Array
        (
            [4] => A two digit second could not be found
        )

    [is_localtime] =>
)

フォーマット文字 G は、 24時間制での時間をパースします。 先頭のゼロを含んでいても、含まなくてもパースを行います。 このフォーマットは、1桁か2桁の数値が必要ですが、 2桁の数値が存在するので、ここでは貪欲に 60 を読み込みます。

その後に続く i と s フォーマット文字は、両方2桁の数値が必要です。 つまり、10 が (フォーマット文字 i の) 分として渡されるので、 (フォーマット文字 s の) 秒としてパースする十分な桁数が残っていません。

配列の errors キーの内容が、 この問題を説明しています。

さらに、24時間制の時は、 0-24 の範囲であるため、 60 は範囲外の値です。 よって、warnings キーに、 指定された時間が正しくない旨の警告が含まれています。

参考

  • DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::getLastErrors() - 警告およびエラーを返す
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strptime() - strftime が生成した日付/時刻をパースする


指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

  • ≪ DateTimeImmutable::createFromFormat
  • DateTimeImmutable::createFromMutable ≫
  • PHP Manual
  • DateTimeImmutable
  • 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

説明

public static DateTimeImmutable::createFromInterface(DateTimeInterface $object): DateTimeImmutable

パラメータ

object

変更できないバージョンに変換する DateTimeInterface オブジェクト。 このオブジェクトは変更されませんが、 同じ日付、時刻、タイムゾーンの情報が入った新しい DateTimeImmutable オブジェクトが作成されます。

戻り値

新しいDateTimeImmutable クラスのインスタンスを返します。

例

例1 DateTimeImmutable オブジェクトを作る

<?php
$date = new DateTime("2014-06-20 11:45 Europe/London");

$immutable = DateTimeImmutable::createFromInterface($date);

$date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
$also_immutable = DateTimeImmutable::createFromInterface($date);
?>


与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す

  • ≪ DateTimeImmutable::createFromInterface
  • DateTimeImmutable::getLastErrors ≫
  • PHP Manual
  • DateTimeImmutable
  • 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す

DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す

説明

public static DateTimeImmutable::createFromMutable(DateTime $object): static

パラメータ

object

変更不能なバージョンに変換が必要な、 DateTime オブジェクト。 このオブジェクトは変更されませんが、 代わりに同じ日付、時刻、タイムゾーンの情報を含んだ 新しい DateTimeImmutable のインスタンスが作られます。

戻り値

新しい DateTimeImmutable インスタンスを返します。

変更履歴

バージョン | 説明
8.0.0 | このメソッドは、現在呼び出されたクラスのインスタンスを返すようになりました。 これより前のバージョンでは、 新しい DateTimeImmutable のインスタンスを生成していました。

例

例1 変更不能な日付オブジェクトを作る

<?php
$date = new DateTime("2014-06-20 11:45 Europe/London");

$immutable = DateTimeImmutable::createFromMutable( $date );
?>


警告およびエラーを返す

  • ≪ DateTimeImmutable::createFromMutable
  • DateTimeImmutable::modify ≫
  • PHP Manual
  • DateTimeImmutable
  • 警告およびエラーを返す

DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — 警告およびエラーを返す

説明

public static DateTimeImmutable::getLastErrors(): array|false

日付/時刻文字列のパース時に見つかった警告やエラーの配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

警告やエラーに関する情報を含む配列を返します。 警告やエラーがない場合は false を返します。

変更履歴

バージョン | 説明
8.2.0 | PHP 8.2.0 より前のバージョンでは、 この関数は警告やエラーがない場合でも false を返しませんでした。 代わりに、例に示している、警告やエラーに関する情報を含む配列を常に返していました。

例

例1 DateTimeImmutable::getLastErrors() の例

<?php
try {
$date = new DateTimeImmutable('asdfasdf');
} catch (Exception $e) {
// 使用例を出したかっただけ...
print_r(DateTimeImmutable::getLastErrors());

// オブジェクト指向流にやるなら、本来は以下のように書くべき
// echo $e->getMessage();
}
?>

上の例の出力は以下となります。

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
       )

)

この出力のインデックス 6 と 0 は、エラーが発生した文字列内での文字の位置を表します。


タイムスタンプを変更した新しいオブジェクトを作る

  • ≪ DateTimeImmutable::getLastErrors
  • DateTimeImmutable::__set_state ≫
  • PHP Manual
  • DateTimeImmutable
  • タイムスタンプを変更した新しいオブジェクトを作る

DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る

説明

public DateTimeImmutable::modify(string $modifier): DateTimeImmutable|false

タイムスタンプを変更した新しい DateTimeImmutable オブジェクトを作ります。 元のオブジェクトは変更されません。

パラメータ

modifier

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

戻り値

新しく作った DateTimeImmutable オブジェクトを返します。 失敗した場合に false を返します

エラー / 例外

不正な日付/時刻の文字列が渡された場合、 DateMalformedStringException がスローされます。 PHP 8.3.0 より前のバージョンでは、警告が発生していました。

変更履歴

バージョン | 説明
8.3.0 | 不正な文字列が渡された場合に、警告を発生させるのではなく、 DateMalformedStringException がスローされるようになりました。

例

例1 DateTimeImmutable::modify() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable('2006-12-12');
$newDate = $date->modify('+1 day');
echo $newDate->format('Y-m-d');
?>

上の例の出力は以下となります。

2006-12-13

例2 月の加減算には注意

<?php
$date = new DateTimeImmutable('2000-12-31');

$newDate1 = $date->modify('+1 month');
echo $newDate1->format('Y-m-d') . "\n";

$newDate2 = $newDate1->modify('+1 month');
echo $newDate2->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-01-31
2001-03-03

参考

  • DateTimeImmutable::add() - 年月日時分秒の値を加え、新しいオブジェクトを返す
  • DateTimeImmutable::sub() - 年月日時分秒の値を引く
  • DateTimeImmutable::setDate() - 日付を設定する
  • DateTimeImmutable::setISODate() - ISO 日付を設定する
  • DateTimeImmutable::setTime() - 時刻を設定する
  • DateTimeImmutable::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する


__set_state ハンドラ

  • ≪ DateTimeImmutable::modify
  • DateTimeImmutable::setDate ≫
  • PHP Manual
  • DateTimeImmutable
  • __set_state ハンドラ

DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — __set_state ハンドラ

説明

public static DateTimeImmutable::__set_state(array $array): DateTimeImmutable

__set_state() ハンドラを処理します。

パラメータ

array

初期化配列。

戻り値

新しい DateTimeImmutable オブジェクトのインスタンスを返します。


日付を設定する

  • ≪ DateTimeImmutable::__set_state
  • DateTimeImmutable::setISODate ≫
  • PHP Manual
  • DateTimeImmutable
  • 日付を設定する

DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — 日付を設定する

説明

public DateTimeImmutable::setDate(int $year, int $month, int $day): DateTimeImmutable

DateTimeImmutable オブジェクトの現在の日付を、指定された日付にします。 指定した日付を設定した、新しい DateTimeImmutable オブジェクトを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

month

その日付の月。

day

その日付の日。

戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

例

例1 DateTimeImmutable::setDate() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable();
$newDate = $date->setDate(2001, 2, 3);
echo $newDate->format('Y-m-d');
?>

上の例の出力は以下となります。

2001-02-03

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTimeImmutable();

$newDate = $date->setDate(2001, 2, 28);
echo $newDate->format('Y-m-d') . "\n";

$newDate = $date->setDate(2001, 2, 29);
echo $newDate->format('Y-m-d') . "\n";

$newDate = $date->setDate(2001, 14, 3);
echo $newDate->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-02-28
2001-03-01
2002-02-03

参考

  • DateTimeImmutable::setISODate() - ISO 日付を設定する
  • DateTimeImmutable::setTime() - 時刻を設定する


ISO 日付を設定する

  • ≪ DateTimeImmutable::setDate
  • DateTimeImmutable::setTime ≫
  • PHP Manual
  • DateTimeImmutable
  • ISO 日付を設定する

DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — ISO 日付を設定する

説明

public DateTimeImmutable::setISODate(int $year, int $week, int $dayOfWeek = 1): DateTimeImmutable

ISO 8601 標準形式、 つまり週と日オフセットで日付を設定する形式に従って日付を設定した、 新しい DateTimeImmutable オブジェクトを返します。

パラメータ

year

その日付の年。

week

その日付の週。

dayOfWeek

週の最初の日からのオフセット。

戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

例

例1 DateTimeImmutable::setISODate() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable();

$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 DateTimeImmutable();

$newDate = $date->setISODate(2008, 2, 7);
echo $newDate->format('Y-m-d') . "\n";

$newDate = $date->setISODate(2008, 2, 8);
echo $newDate->format('Y-m-d') . "\n";

$newDate = $date->setISODate(2008, 53, 7);
echo $newDate->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2008-01-13
2008-01-14
2009-01-04

例3 その週が存在する月を探す例

<?php
$date = new DateTimeImmutable();
$newDate = $date->setISODate(2008, 14);
echo $newDate->format('n');
?>

上の例の出力は以下となります。

3

参考

  • DateTimeImmutable::setDate() - 日付を設定する
  • DateTimeImmutable::setTime() - 時刻を設定する


時刻を設定する

  • ≪ DateTimeImmutable::setISODate
  • DateTimeImmutable::setTimestamp ≫
  • PHP Manual
  • DateTimeImmutable
  • 時刻を設定する

DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — 時刻を設定する

説明

public DateTimeImmutable::setTime(
int $hour,
int $minute,
int $second = 0,
int $microsecond = 0
): DateTimeImmutable

指定された時刻を設定した、 新しい DateTimeImmutable オブジェクト を返します。

パラメータ

hour

その時刻の時。

minute

その時刻の分。

second

その時刻の秒。

microsecond

その時刻のマイクロ秒。

戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

変更履歴

バージョン | 説明
8.1.0 | (夏時間遷移のフォールバック期間中に) 二重に存在する hour に関する振る舞いが変更されました。 これより前のバージョンでは、 (夏時間遷移が起こる前の)最初の hour ではなく、 (夏時間遷移が起きた後の)二番目の hour を取得していました。
7.1.0 | microsecond パラメータが追加されました。

例

例1 DateTimeImmutable::setTime() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable('2001-01-01');

$newDate = $date->setTime(14, 55);
echo $newDate->format('Y-m-d H:i:s') . "\n";

$newDate = $date->setTime(14, 55, 24);
echo $newDate->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2001-01-01 14:55:00
2001-01-01 14:55:24

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTimeImmutable('2001-01-01');

$newDate = $date->setTime(14, 55, 24);
echo $newDate->format('Y-m-d H:i:s') . "\n";

$newDate = $date->setTime(14, 55, 65);
echo $newDate->format('Y-m-d H:i:s') . "\n";

$newDate = $date->setTime(14, 65, 24);
echo $newDate->format('Y-m-d H:i:s') . "\n";

$newDate = $date->setTime(25, 55, 24);
echo $newDate->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

参考

  • DateTimeImmutable::setDate() - 日付を設定する
  • DateTimeImmutable::setISODate() - ISO 日付を設定する


Unix タイムスタンプを用いて日付と時刻を設定する

  • ≪ DateTimeImmutable::setTime
  • DateTimeImmutable::setTimezone ≫
  • PHP Manual
  • DateTimeImmutable
  • Unix タイムスタンプを用いて日付と時刻を設定する

DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する

説明

public DateTimeImmutable::setTimestamp(int $timestamp): DateTimeImmutable

Unix タイムスタンプを用いて日付と時刻を設定し、 古いものから新しい DateTimeImmutable オブジェクトを作成して返します。

パラメータ

timestamp

Unix タイムスタンプ。 DateTimeImmutable::modify() を @ フォーマットと共に使うと、 数値型の範囲外のタイムスタンプを設定できます。

戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

例

例1 DateTimeImmutable::setTimestamp() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable();
echo $date->format('U = Y-m-d H:i:s') . "\n";

$newDate = $date->setTimestamp(1171502725);
echo $newDate->format('U = Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1272508903 = 2010-04-28 22:41:43
1171502725 = 2007-02-14 20:25:25

参考

  • DateTimeImmutable::getTimestamp() - Unix タイムスタンプを取得する


タイムゾーンを設定する

  • ≪ DateTimeImmutable::setTimestamp
  • DateTimeImmutable::sub ≫
  • PHP Manual
  • DateTimeImmutable
  • タイムゾーンを設定する

DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — タイムゾーンを設定する

説明

public DateTimeImmutable::setTimezone(DateTimeZone $timezone): DateTimeImmutable

新しいタイムゾーンを設定した、 新しい DateTimeImmutable オブジェクトを返します。

パラメータ

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

戻り値

メソッドをチェインできるようにするため、 変更された新しい DateTimeImmutable オブジェクトを返します。 このメソッドをコールした際に指していた時刻は変わりません。

例

例1 DateTimeImmutable::setTimeZone() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

$newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
echo $newDate->format('Y-m-d H:i:sP') . "\n";
?>

上の例の出力は以下となります。

2000-01-01 00:00:00+12:00
2000-01-01 01:45:00+13:45

参考

  • DateTimeImmutable::getTimezone() - 指定した DateTime に関連するタイムゾーンを返す
  • DateTimeZone::__construct() - 新しい DateTimeZone オブジェクトを作成する


年月日時分秒の値を引く

  • ≪ DateTimeImmutable::setTimezone
  • DateTimeInterface ≫
  • PHP Manual
  • DateTimeImmutable
  • 年月日時分秒の値を引く

DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — 年月日時分秒の値を引く

説明

public DateTimeImmutable::sub(DateInterval $interval): DateTimeImmutable

指定した DateInterval オブジェクトを、 指定した DateTimeImmutable オブジェクトから引き、 新しい DateTimeImmutable オブジェクトを返します。

パラメータ

interval

DateInterval オブジェクト。

戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

エラー / 例外

サポートされていない操作を試みた場合、 DateInvalidOperationExceptionがスローされます。 サポートされていない操作の例としては、 next weekday のような相対時刻を表現する DateInterval を使った場合が挙げられます。

変更履歴

バージョン | 説明
8.3.0 | サポートされていない操作を試みた場合に、警告を発生させるのではなく、 DateInvalidOperationException がスローされるようになりました。

例

例1 DateTimeImmutable::sub() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable('2000-01-20');
$newDate = $date->sub(new DateInterval('P10D'));
echo $newDate->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2000-01-10

例2 DateTimeImmutable::sub() の別な例

<?php
$date = new DateTimeImmutable('2000-01-20');
$newDate = $date->sub(new DateInterval('PT10H30S'));
echo $newDate->format('Y-m-d H:i:s') . "\n";

$date = new DateTimeImmutable('2000-01-20');
$newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
echo $newDate->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2000-01-19 13:59:30
1992-08-15 19:56:58

例3 月を減算する際は注意

<?php
$date = new DateTimeImmutable('2001-04-30');
$interval = new DateInterval('P1M');

$newDate1 = $date->sub($interval);
echo $newDate1->format('Y-m-d') . "\n";

$newDate2 = $newDate1->sub($interval);
echo $newDate2->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-03-30
2001-03-02

参考

  • DateTimeImmutable::add() - 年月日時分秒の値を加え、新しいオブジェクトを返す
  • DateTimeImmutable::diff() - ふたつの DateTime オブジェクトの差を返す
  • DateTimeImmutable::modify() - タイムスタンプを変更した新しいオブジェクトを作る


DateTimeInterface インターフェイス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

DateTimeInterface は、 DateTimeImmutable や DateTime を引数や戻り値、プロパティの型宣言で使えるようにするために作られたものです。 このインターフェイスを実装したクラスをユーザー側で作ることはできません。

DateTimeImmutable::format() や DateTime::format() を通じて、 DateTimeImmutable や DateTime をフォーマットするための共通の定数も、 このインターフェイスに定義されています。

インターフェイス概要

interface DateTimeInterface {
/* 定数 */
public const string ATOM = "Y-m-d\\TH:i:sP";
public const string COOKIE = "l, d-M-Y H:i:s T";
public const string ISO8601 = "Y-m-d\\TH:i:sO";
public const string ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string RFC822 = "D, d M y H:i:s O";
public const string RFC850 = "l, d-M-y H:i:s T";
public const string RFC1036 = "D, d M y H:i:s O";
public const string RFC1123 = "D, d M Y H:i:s O";
public const string RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string RFC2822 = "D, d M Y H:i:s O";
public const string RFC3339 = "Y-m-d\\TH:i:sP";
public const string RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string RSS = "D, d M Y H:i:s O";
public const string W3C = "Y-m-d\\TH:i:sP";
/* メソッド */
public diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval
public format(string $format): string
public getOffset(): int
public getTimestamp(): int
public getTimezone(): DateTimeZone|false
public __wakeup(): void
}

定義済み定数

DateTimeInterface::ATOM
DATE_ATOM
Atom (例: 2005-08-15T15:52:01+00:00)
DateTimeInterface::COOKIE
DATE_COOKIE
HTTP Cookie (例: Monday, 15-Aug-2005 15:52:01 UTC)
DateTimeInterface::ISO8601
DATE_ISO8601
ISO-8601 (例: 2005-08-15T15:52:01+0000)

注意: このフォーマットは、ISO-8601 と互換性がありません。 しかし、後方互換性を保つために残されています。 ISO-8601 と互換性を保つためには、 DateTimeInterface::ISO8601_EXPANDED, DateTimeInterface::ATOM を使うようにしてください。 (ISO8601:2004 section 4.3.3 clause d も参照ください)

DateTimeInterface::ISO8601_EXPANDED
DATE_ISO8601_EXPANDED
ISO-8601 拡張形式 (例: +10191-07-26T08:59:52+01:00)

注意: 年に常に符号を含めることで、ISO-8601 の通常の範囲 0000-9999 以外の値が許されています。 タイムゾーンの部分 (+01:00) については、 ISO-8601 と互換性をとるようにもなっています。

DateTimeInterface::RFC822
DATE_RFC822
RFC 822 (例: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC850
DATE_RFC850
RFC 850 (例: Monday, 15-Aug-05 15:52:01 UTC)
DateTimeInterface::RFC1036
DATE_RFC1036
RFC 1036 (例: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC1123
DATE_RFC1123
RFC 1123 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC7231
DATE_RFC7231
RFC 7231 (PHP 7.0.19 と 7.1.5以降) (例: Sat, 30 Apr 2016 17:52:13 GMT)
DateTimeInterface::RFC2822
DATE_RFC2822
RFC 2822 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC3339
DATE_RFC3339
DATE_ATOM と同じです
DateTimeInterface::RFC3339_EXTENDED
DATE_RFC3339_EXTENDED
RFC 3339 EXTENDED フォーマット (例: 2005-08-15T15:52:01.000+00:00)
DateTimeInterface::RSS
DATE_RSS
RSS (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::W3C
DATE_W3C
World Wide Web Consortium (例: 2005-08-15T15:52:01+00:00)

変更履歴

バージョン | 説明
8.2.0 | 定数 DateTimeInterface::ISO8601_EXPANDED が追加されました。
7.2.0 | DateTime クラスの定数は、 DateTimeInterface で定義されるようになりました。

目次

  • DateTimeInterface::diff — ふたつの DateTime オブジェクトの差を返す
  • DateTimeInterface::format — 指定した書式でフォーマットした日付を返す
  • DateTimeInterface::getOffset — タイムゾーンのオフセットを返す
  • DateTimeInterface::getTimestamp — Unix タイムスタンプを取得する
  • DateTimeInterface::getTimezone — 指定した DateTime に関連するタイムゾーンを返す
  • DateTime::__wakeup — __wakeup ハンドラ


ふたつの DateTime オブジェクトの差を返す

  • ≪ DateTimeInterface
  • DateTimeInterface::format ≫
  • PHP Manual
  • DateTimeInterface
  • ふたつの DateTime オブジェクトの差を返す

DateTimeInterface::diff

DateTimeImmutable::diff

DateTime::diff

date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — ふたつの DateTime オブジェクトの差を返す

説明

オブジェクト指向型

public DateTimeInterface::diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval
public DateTimeImmutable::diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval
public DateTime::diff(DateTimeInterface $targetObject, bool $absolute = false): DateInterval

手続き型

date_diff(DateTimeInterface $baseObject, DateTimeInterface $targetObject, bool $absolute = false): DateInterval

ふたつの DateTime オブジェクトの差を返します。

パラメータ

datetime

比較する日付。

absolute

間隔が正の数になるようにするか否か。

戻り値

ふたつの日付の差をあらわす DateInterval オブジェクトを返します。

さらに厳密に言うと、戻り値はもともとのオブジェクト ($this または $originObject) を $targetObject にするために適用すべき経過時間の差分を示しています。 このプロセスは可逆とは限りません。

このメソッドは夏時間の切り替えを認識するため、 24 hours and 30 minutes という時間差を返す可能性があります。 以下で例示するサンプルコードでそれを示します。 完全な時間差を計算したい場合、 $this/$baseObject と $targetObject をUTC に変換する必要があります。

例

例1 DateTimeImmutable::diff() の例

オブジェクト指向型

<?php
$origin = new DateTimeImmutable('2009-10-11');
$target = new DateTimeImmutable('2009-10-13');
$interval = $origin->diff($target);
echo $interval->format('%R%a days');
?>

手続き型

<?php
$origin = date_create('2009-10-11');
$target = date_create('2009-10-13');
$interval = date_diff($origin, $target);
echo $interval->format('%R%a days');
?>

上の例の出力は以下となります。

+2 days

例2 夏時間の切り替え期間中の DateTimeInterface::diff() の動き

<?php
$originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
$targedTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
$interval = $originalTime->diff($targedTime);
echo $interval->format("%H:%I:%S (Full days: %a)"), "\n";
?>

上の例の出力は以下となります。

24:30:00 (Full days: 0)

例3 DateTimeInterface::diff() range

このメソッドが返す値は、 $this から $targetObject までの範囲から取得した正確な時間です。 よって、（うるう年でない場合) 1月1日から12月31日までを比較すると、 365 ではなく、364 が返ってきます。

<?php
$originalTime = new DateTimeImmutable("2023-01-01 UTC");
$targedTime = new DateTimeImmutable("2023-12-31 UTC");
$interval = $originalTime->diff($targedTime);
echo "Full days: ", $interval->format("%a"), "\n";
?>

上の例の出力は以下となります。

Full days: 364

例4 DateTime オブジェクトの比較

注意:

DateTimeImmutable と 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)

参考

  • DateInterval::format() - 間隔をフォーマットする
  • DateTime::add() - 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く


指定した書式でフォーマットした日付を返す

  • ≪ DateTimeInterface::diff
  • DateTimeInterface::getOffset ≫
  • PHP Manual
  • DateTimeInterface
  • 指定した書式でフォーマットした日付を返す

DateTimeInterface::format

DateTimeImmutable::format

DateTime::format

date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_format — 指定した書式でフォーマットした日付を返す

説明

オブジェクト指向型

public DateTimeInterface::format(string $format): string
public DateTimeImmutable::format(string $format): string
public DateTime::format(string $format): string

手続き型

date_format(DateTimeInterface $object, string $format): string

指定した書式でフォーマットした日付を返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

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 形式の、曜日の数値表現 | 1（月曜日）から 7（日曜日）
S | 英語形式の序数を表すサフィックス。2 文字。 | st, nd, rd または th。 jと一緒に使用する ことができる。
w | 曜日。数値。 | 0 (日曜)から 6 (土曜)
z | 年間の通算日。数字。(ゼロから開始) | 0 から 365
週 --- ---
W | ISO 8601 月曜日に始まる年単位の週番号 | 例: 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）が前年あるいは翌年に属する場合はそちらの年を使うという点が異なる。 | 例: 1999 あるいは 2003
X | 拡張された年の数値表現。少なくとも4桁からなる数値。紀元前の場合は、- が付きます。西暦の場合は + が付きます。 | 例: -0055, +0787, +1999, +10191
x | 必要に応じて拡張された年の数値表現。 拡張する必要がない場合は、通常の年の数値 (Y と同じ)。 少なくとも4桁からなる数値。紀元前の場合は、- が付きます。10000 (10000を含みます) を超える場合は、+ が付きます。 | 例: -0055, 0787, 1999, +10191
Y | 年。少なくとも4桁からなる数値。紀元前の場合は、- が付きます。 | 例: -0055, 0787, 1999, 2003, 10191
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 | マイクロ秒。 date() の場合、これは常に 000000 となることに注意しましょう。というのも、 この関数が受け取るパラメータは int 型だからです。 一方 DateTime をマイクロ秒つきで作成した場合は、 DateTime::format() はマイクロ秒にも対応しています。 | 例: 654321
v | ミリ秒。 uと同じ注釈が当てはまります。 | 例: 654
タイムゾーン --- ---
e | タイムゾーン識別子 | 例: UTC, GMT, Atlantic/Azores
I (大文字の i) | サマータイム中か否か | 1ならサマータイム中。 0ならそうではない。
O | グリニッジ標準時 (GMT) との時差。時間と分の間にコロンは入りません。 | 例: +0200
P | グリニッジ標準時 (GMT) との時差。時間と分をコロンで区切った形式 | 例: +02:00
p | P と同じですが、+00:00 ではなく Z を返します。 (PHP 8.0.0 以降で利用可能) | 例: Z または +02:00
T | 既知のものについては、タイムゾーンの略称。そうでないものについては、GMT からのオフセット | 例: EST, MDT, +05
Z | タイムゾーンのオフセット秒数。 UTC の西側のタイムゾーン用のオフセットは常に負です。そして、 UTC の東側のオフセットは常に正です。 | -43200 から 50400
全ての日付/時刻 --- ---
c | ISO 8601 日付 | 2004-02-12T15:19:21+00:00
r | » RFC 2822/» RFC 5322 形式でフォーマットされた日付 | 例: Thu, 21 Dec 2000 16:01:07 +0200
U | Unix Epoch (1970 年 1 月 1 日 0 時 0 分 0 秒) からの秒数 | time() も参照

フォーマット文字列中の認識されない文字は、そのまま表示されます。 Z 形式は、 gmdate() で使用した場合、常に 0 を返します。

注意:

この関数が受け付けるのは int のタイムスタンプだけです。したがって、書式指定文字 u が有用となるのは date_create() で作成したタイムスタンプを用いて date_format() を使用した場合のみです。

戻り値

成功した場合にフォーマット済みの日付文字列を返します。

変更履歴

バージョン | 説明
8.2.0 | フォーマット文字に X と x が追加されました。
8.0.0 | フォーマット文字 p が追加されました。

例

例1 DateTimeInterface::format() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable('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

例2 例をもう少し

<?php
// デフォルトのタイムゾーンを設定します
date_default_timezone_set('UTC');
// 現在時刻で初期化
$date = new DateTimeImmutable();
// Wednesday のような値を出力
echo $date->format('l'), "\n";
// Wednesday 19th of October 2022 08:40:48 AM のような値を出力
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";
/* フォーマット文字で定数を使う */
// Wed, 19 Oct 2022 08:40:48 +0000 のような値を出力
echo $date->format(DateTimeInterface::RFC2822), "\n";
?>

フォーマット文字列の中で既知の文字が展開されることを防ぐために、 バックスラッシュでエスケープすることができます。 バックスラッシュ付きの文字が既に特殊な意味を持つ場合は、 バックスラッシュもエスケープする必要があるでしょう。

例3 フォーマット中に文字をエスケープする

<?php
$date = new DateTimeImmutable();
// prints something like: Wednesday the 19th
echo $date->format('l \t\h\e jS');
?>

他の言語で日付をフォーマットするには、 DateTimeInterface::format() ではなく IntlDateFormatter::format() を使います。

注意

このメソッドはロケールを考慮しません。出力結果はすべて英語となります。

参考

  • IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする


タイムゾーンのオフセットを返す

  • ≪ DateTimeInterface::format
  • DateTimeInterface::getTimestamp ≫
  • PHP Manual
  • DateTimeInterface
  • タイムゾーンのオフセットを返す

DateTimeInterface::getOffset

DateTimeImmutable::getOffset

DateTime::getOffset

date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getOffset -- DateTimeImmutable::getOffset -- DateTime::getOffset -- date_offset_get — タイムゾーンのオフセットを返す

説明

オブジェクト指向型

public DateTimeInterface::getOffset(): int
public DateTimeImmutable::getOffset(): int
public DateTime::getOffset(): int

手続き型

date_offset_get(DateTimeInterface $object): int

タイムゾーンのオフセットを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

戻り値

成功した場合には UTC からのタイムゾーンオフセット秒数、

例

例1 DateTime::getOffset() の例

オブジェクト指向型

<?php
$winter = new DateTimeImmutable('2010-12-21', new DateTimeZone('America/New_York'));
$summer = new DateTimeImmutable('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.


Unix タイムスタンプを取得する

  • ≪ DateTimeInterface::getOffset
  • DateTimeInterface::getTimezone ≫
  • PHP Manual
  • DateTimeInterface
  • Unix タイムスタンプを取得する

DateTimeInterface::getTimestamp

DateTimeImmutable::getTimestamp

DateTime::getTimestamp

date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTime::getTimestamp -- date_timestamp_get — Unix タイムスタンプを取得する

説明

オブジェクト指向型

public DateTimeInterface::getTimestamp(): int
public DateTimeImmutable::getTimestamp(): int
public DateTime::getTimestamp(): int

手続き型

date_timestamp_get(DateTimeInterface $object): int

Unix タイムスタンプを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

その日付をあらわす Unix タイムスタンプを返します。

エラー / 例外

タイムスタンプが整数として表現できない場合、 DateRangeError がスローされます。 PHP 8.3.0 より前のバージョンでは、ValueError がスローされていました。また、PHP 8.0.0 より前のバージョンでは同様の場合に false を返していました。 さらに、DateTimeInterface::format() に U を指定すると、タイムスタンプは文字列として取得できます。

変更履歴

バージョン | 説明
8.3.0 | 範囲外の例外が DateRangeError になりました。
8.0.0 | これらの関数は、失敗時に false を返さなくなりました。

例

例1 DateTime::getTimestamp() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable();
echo $date->getTimestamp();
?>

手続き型

<?php
$date = date_create();
echo date_timestamp_get($date);
?>

上の例の出力は、 たとえば以下のようになります。

1272509157

ミリ秒やマイクロ秒の精度でタイムスタンプを取得したい場合、 DateTimeInterface::format() が使えます。

例2 ミリ秒とマイクロ秒の精度でタイムスタンプを取得する

オブジェクト指向型

<?php
$date = new DateTimeImmutable();
$milli = (int)$date->format('Uv'); // タイムスタンプをミリ秒で取得
$micro = (int)$date->format('Uu'); // タイムスタンプをマイクロ秒で取得

echo $milli, "\n", $micro, "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1674057635586
1674057635586918

参考

  • DateTime::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTimeImmutable::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する
  • DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す


指定した DateTime に関連するタイムゾーンを返す

  • ≪ DateTimeInterface::getTimestamp
  • DateTime::__wakeup ≫
  • PHP Manual
  • DateTimeInterface
  • 指定した DateTime に関連するタイムゾーンを返す

DateTimeInterface::getTimezone

DateTimeImmutable::getTimezone

DateTime::getTimezone

date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getTimezone -- DateTimeImmutable::getTimezone -- DateTime::getTimezone -- date_timezone_get — 指定した DateTime に関連するタイムゾーンを返す

説明

オブジェクト指向型

public DateTimeInterface::getTimezone(): DateTimeZone|false
public DateTimeImmutable::getTimezone(): DateTimeZone|false
public DateTime::getTimezone(): DateTimeZone|false

手続き型

date_timezone_get(DateTimeInterface $object): DateTimeZone|false

指定した DateTime に関連するタイムゾーンを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

戻り値

成功した場合に DateTimeZone オブジェクト、失敗した場合に false を返します。

例

例1 DateTime::getTimezone() の例

オブジェクト指向型

<?php
$date = new DateTimeImmutable(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::setTimezone() - DateTime オブジェクトのタイムゾーンを設定する


__wakeup ハンドラ

  • ≪ DateTimeInterface::getTimezone
  • DateTimeZone ≫
  • PHP Manual
  • DateTimeInterface
  • __wakeup ハンドラ

DateTime::__wakeup

DateTimeImmutable::__wakeup

DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — __wakeup ハンドラ

説明

public DateTime::__wakeup(): void
public DateTimeImmutable::__wakeup(): void
public DateTimeInterface::__wakeup(): void

__wakeup() を処理します。

パラメータ

この関数にはパラメータはありません。

戻り値

DateTime オブジェクトを初期化します。


DateTimeZone クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

タイムゾーンをあらわします。

クラス概要

class DateTimeZone {
/* 定数 */
public const int AFRICA;
public const int AMERICA;
public const int ANTARCTICA;
public const int ARCTIC;
public const int ASIA;
public const int ATLANTIC;
public const int AUSTRALIA;
public const int EUROPE;
public const int INDIAN;
public const int PACIFIC;
public const int UTC;
public const int ALL;
public const int ALL_WITH_BC;
public const int PER_COUNTRY;
/* メソッド */
public __construct(string $timezone)
public getLocation(): array|false
public getName(): string
public getOffset(DateTimeInterface $datetime): int
public getTransitions(int $timestampBegin = PHP_INT_MIN, int $timestampEnd = PHP_INT_MAX): array|false
public static listAbbreviations(): array
public static listIdentifiers(int $timezoneGroup = DateTimeZone::ALL, ?string $countryCode = null): array
}

定義済み定数

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 — 新しい DateTimeZone オブジェクトを作成する
  • DateTimeZone::getLocation — タイムゾーンの位置情報を返す
  • DateTimeZone::getName — タイムゾーンの名前を返す
  • DateTimeZone::getOffset — GMT からのタイムゾーンのオフセットを返す
  • DateTimeZone::getTransitions — タイムゾーンの変遷を返す
  • DateTimeZone::listAbbreviations — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す
  • DateTimeZone::listIdentifiers — すべてのタイムゾーン識別子を含む配列を返す


新しい DateTimeZone オブジェクトを作成する

  • ≪ DateTimeZone
  • DateTimeZone::getLocation ≫
  • PHP Manual
  • DateTimeZone
  • 新しい DateTimeZone オブジェクトを作成する

DateTimeZone::__construct

timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — 新しい DateTimeZone オブジェクトを作成する

説明

オブジェクト指向型

public DateTimeZone::__construct(string $timezone)

手続き型

timezone_open(string $timezone): DateTimeZone|false

新しい DateTimeZone オブジェクトを作成します。

DateTimeZone オブジェクトは、 3つの異なるタイムゾーンルールへのアクセスを提供します。 ひとつは UTC からのオフセット (type 1), もうひとつはタイムゾーンの省略形 (type 2), そして IANA タイムゾーンデータベースで公開されている タイムゾーン名 (type 3) です。

DateTimeZone オブジェクトは、 DateTime や DateTimeImmutable に設定できます。 こうすることで、 ローカルのタイムゾーンとしてカプセル化された、 タイムゾーンを表示させることができます。

パラメータ

timezone

サポートするタイムゾーン名 のいずれかや、 オフセット値 (+0200)、 またはタイムゾーンの省略名(BST)。

戻り値

成功した場合に DateTimeZone を返します。 手続き型 の場合は、失敗したときに false を返します。

エラー / 例外

指定されたタイムゾーンが有効なタイムゾーンとして認識できない場合、 DateInvalidTimeZoneException をスローします。PHP 8.3 より前のバージョンでは、 Exception をスローしていました。

変更履歴

バージョン | 説明
8.3.0 | 無効な値を指定した場合、 一般的な Exception ではなく、DateInvalidTimeZoneException がスローされるようになりました。

例

例1 DateTimeZone を作成し、DateTimeImmutable に設定する

<?php
$d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");

$timezones = [ 'Europe/London', 'GMT+04:45', '-06:00', 'CEST' ];

foreach ($timezones as $tz) {
$tzo = new DateTimeZone($tz);

$local = $d->setTimezone($tzo);
echo $local->format(DateTimeInterface::RFC2822 . ' — e'), "\n";
}
?>

上の例の出力は以下となります。

Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
Thu, 02 Jun 2022 17:44:48 +0200 — CEST

例2 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::__construct
  • DateTimeZone::getName ≫
  • PHP Manual
  • DateTimeZone
  • タイムゾーンの位置情報を返す

DateTimeZone::getLocation

timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — タイムゾーンの位置情報を返す

説明

オブジェクト指向型

public DateTimeZone::getLocation(): array|false

手続き型

timezone_location_get(DateTimeZone $object): array|false

タイムゾーンの位置情報 (国コード、緯度/経度、コメント) を返します。

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

戻り値

タイムゾーンについての位置情報を含む配列を返します。失敗した場合に false を返します

例

例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::listIdentifiers() - すべてのタイムゾーン識別子を含む配列を返す


タイムゾーンの名前を返す

  • ≪ DateTimeZone::getLocation
  • DateTimeZone::getOffset ≫
  • PHP Manual
  • DateTimeZone
  • タイムゾーンの名前を返す

DateTimeZone::getName

timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — タイムゾーンの名前を返す

説明

オブジェクト指向型

public DateTimeZone::getName(): string

手続き型

timezone_name_get(DateTimeZone $object): string

タイムゾーンの名前を返します。

パラメータ

object

名前を取得したい DateTimeZone。

戻り値

タイムゾーンのタイプによって、異なる値を返します。 UTC オフセット(type 1 の場合)、 タイムゾーンの省略形(type 2 の場合)、 および IANA タイムゾーンデータベースに登録されているタイムゾーン識別子(type 3 の場合) です。これらは、同じオフセット かつ/または ルールで DateTimeZone オブジェクトを作るための文字列です。 たとえば 02:00、 CEST、 タイムゾーン一覧 のタイムゾーン名のひとつを返します。


GMT からのタイムゾーンのオフセットを返す

  • ≪ DateTimeZone::getName
  • DateTimeZone::getTransitions ≫
  • PHP Manual
  • DateTimeZone
  • GMT からのタイムゾーンのオフセットを返す

DateTimeZone::getOffset

timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — GMT からのタイムゾーンのオフセットを返す

説明

オブジェクト指向型

public DateTimeZone::getOffset(DateTimeInterface $datetime): int

手続き型

timezone_offset_get(DateTimeZone $object, DateTimeInterface $datetime): int

この関数は、datetime パラメータで指定した 日付/時刻 についての GMT へのオフセットを返します。GMT オフセットの計算の際には、 使用する DateTimeZone オブジェクトに含まれるタイムゾーン情報を使用します。

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

datetime

オフセットを計算する 日付/時刻 を含む DateTime。

戻り値

成功した場合にタイムゾーンのオフセット秒数を返します。

例

例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::getOffset
  • DateTimeZone::listAbbreviations ≫
  • PHP Manual
  • DateTimeZone
  • タイムゾーンの変遷を返す

DateTimeZone::getTransitions

timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — タイムゾーンの変遷を返す

説明

オブジェクト指向型

public DateTimeZone::getTransitions(int $timestampBegin = PHP_INT_MIN, int $timestampEnd = PHP_INT_MAX): array|false

手続き型

timezone_transitions_get(DateTimeZone $object, int $timestampBegin = PHP_INT_MIN, int $timestampEnd = PHP_INT_MAX): array|false

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

timestampBegin

開始時のタイムスタンプ。

timestampEnd

終了時のタイムスタンプ。

戻り値

成功した場合にタイムゾーンの遷移を表す、数値インデックスの配列を返します。 失敗した場合に false を返します。 DateTimeZone オブジェクト の type 1 (UTC オフセット) と、type 2 (タイムゾーンの省略形) の場合は、 タイムゾーンの遷移情報は含まれません。 その場合にこのメソッドをコールしても false を返します。

timestampBegin を指定すると、 返される配列の最初のエントリに timestampBegin の時点における遷移の情報が含まれるようになります。

タイムゾーンの遷移を表す配列の構造
キー | 型 | 説明
ts | int | Unixタイムスタンプ
time | string | DateTimeInterface::ISO8601_EXPANDED (PHP 8.2 以降) または、DateTimeInterface::ISO8601 (PHP 8.1 以前) 形式の文字列
offset | int | UTC からのオフセット(秒単位)
isdst | bool | 夏時間が有効かどうか
abbr | string | タイムゾーンの省略形

例

例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
        )

)

例2 timestampBegin を設定して timezone_transitions_get() を使う例

<?php
$timezone = new DateTimeZone("Europe/London");
$transitions = $timezone->getTransitions(time());
print_r(array_slice($transitions, 0, 3));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [ts] => 1654184161
            [time] => 2022-06-02T15:36:01+0000
            [offset] => 3600
            [isdst] => 1
            [abbr] => BST
        )

    [1] => Array
        (
            [ts] => 1667091600
            [time] => 2022-10-30T01:00:00+0000
            [offset] => 0
            [isdst] =>
            [abbr] => GMT
        )

    [2] => Array
        (
            [ts] => 1679792400
            [time] => 2023-03-26T01:00:00+0000
            [offset] => 3600
            [isdst] => 1
            [abbr] => BST
        )

)


夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

  • ≪ DateTimeZone::getTransitions
  • DateTimeZone::listIdentifiers ≫
  • PHP Manual
  • DateTimeZone
  • 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

DateTimeZone::listAbbreviations

timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

説明

オブジェクト指向型

public static DateTimeZone::listAbbreviations(): array

手続き型

timezone_abbreviations_list(): array

この関数が返す省略形のリストは、 歴史的に使われてきた値を全て含んでいます。 これは正しい値ではあるものの、混乱を招くものがあります。 値が衝突しているものもあります。たとえば PST はアメリカ合衆国(US)とフィリピンの双方で使われています。

よって、この関数が返すリストは、ユーザーにタイムゾーンを選択させる表示オプションを構築する目的には適していません。

注意:

この関数で使われるデータは、パフォーマンス上の理由でプリコンパイルされています。 よって、より新しい » timezonedb を使っていても更新されません。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に、タイムゾーンの情報を含んだ配列を返します。

例

例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
        )

)

参考

  • timezone_identifiers_list() - DateTimeZone::listIdentifiers のエイリアス


すべてのタイムゾーン識別子を含む配列を返す

  • ≪ DateTimeZone::listAbbreviations
  • DateInterval ≫
  • PHP Manual
  • DateTimeZone
  • すべてのタイムゾーン識別子を含む配列を返す

DateTimeZone::listIdentifiers

timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — すべてのタイムゾーン識別子を含む配列を返す

説明

オブジェクト指向型

public static DateTimeZone::listIdentifiers(int $timezoneGroup = DateTimeZone::ALL, ?string $countryCode = null): array

手続き型

timezone_identifiers_list(int $timezoneGroup = DateTimeZone::ALL, ?string $countryCode = null): array

パラメータ

timezoneGroup

DateTimeZone のクラス定数のいずれか (または定数の組み合わせ)。

countryCode

2 文字の (大文字の) ISO 3166-1 互換の国コード。

注意: このオプションを使用するのは、timezoneGroup に DateTimeZone::PER_COUNTRY を設定した場合のみです。

戻り値

成功した場合に、タイムゾーンの識別子を含んだ配列を返します。 期限切れになっていない識別子のみを返します。 期限切れになったものも含めて、全ての識別子を取得するには、 timezoneGroup の値に DateTimeZone::ALL_WITH_BC を指定します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、失敗時に false を返していました。
7.1.0 | countryCode は、nullable になりました。

例

例1 DateTimeZone::listIdentifiers() の例

<?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

例2 特定の地域を指定して、識別子の一覧を取得する

<?php
$timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
for ($i=0; $i < 5; $i++) {
echo "$timezone_identifiers[$i]\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Asia/Aden
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau

例3 複数の地域を指定して、識別子の一覧を取得する

<?php
$timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
echo join( ', ', $timezone_identifiers );
?>

上の例の出力は、 たとえば以下のようになります。

Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, 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/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
Pacific/Honolulu, Pacific/Kanton, 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/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis

例4 特定の国をひとつ指定して、識別子の一覧を取得する

<?php
$timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
foreach( $timezone_identifiers as $identifier ) {
echo "$identifier\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Europe/Kyiv
Europe/Simferopol
Europe/Uzhgorod
Europe/Zaporozhye

参考

  • timezone_abbreviations_list() - DateTimeZone::listAbbreviations のエイリアス


DateInterval クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

日付の間隔をあらわします。

格納方式は、固定値 (年、月、日、時など) あるいは相対時刻 (DateTimeImmutable と DateTime のコンストラクタがサポートしている書式) となります。

さらに厳密に言うと、 DateInterval オブジェクトが保持している情報は、 ある date/time オブジェクトから別の date/time オブジェクトに情報を移す手順です。 この過程は必ずしも可逆ではありません。

DateInterval オブジェクトを生成する一般的なやり方は、 2つの date/time オブジェクトの差分を DateTimeInterface::diff() 経由で計算することです。

日付の間隔を比較する良い方法は定義されていません。 よって、DateInterval のインスタンスは 比較できません。

クラス概要

class DateInterval {
/* プロパティ */
public int $y;
public int $m;
public int $d;
public int $h;
public int $i;
public int $s;
public float $f;
public int $invert;
public mixed $days;
public bool $from_string;
public string $date_string;
/* メソッド */
public __construct(string $duration)
public static createFromDateString(string $datetime): DateInterval|false
public format(string $format): string
}

プロパティ

警告

以下に示すプロパティが使えるかどうかは、 PHP のバージョンに依存します。 そして、readonly と見なすべきです。

y

年。

m

月。

d

日。

h

時間。

i

分。

s

秒。

f

マイクロ秒。1秒の100万分の1です。

invert

間隔が負の数になっている場合は 1、そうでない場合は 0。 DateInterval::format() を参照ください。

days

DateTimeImmutable::diff() や DateTime::diff() で作られた DateInterval オブジェクトの場合は、開始日と終了日の間の(丸一日、つまり0時から24時までの一日全体という意味での)日の数。 それ以外の場合は days は false となります。

from_string

DateInterval::createFromDateString() で作られた DateInterval オブジェクトの場合は、 このプロパティの値は true になり、 date_string の値が収集されます。 そうでない場合、この値は false になり、 y, f, invert, days の値が収集されます。

date_string

DateInterval::createFromDateString() の引数として使われる文字列。

変更履歴

バージョン | 説明
8.2.0 | DateInterval::createFromDateString() で作られた DateInterval のインスタンスのために、 プロパティ from_string と date_string が追加されました。
8.2.0 | プロパティ y から f, invert, days のみがアクセス可能になりました。
7.4.0 | DateInterval インスタンスは、 比較できなくなりました。 これより前のバージョンでは、 全ての DateInterval のインスタンスが等しいとみなされていました。
7.1.0 | f プロパティが追加されました

目次

  • DateInterval::__construct — 新しい DateInterval オブジェクトを作成する
  • DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する
  • DateInterval::format — 間隔をフォーマットする


新しい DateInterval オブジェクトを作成する

  • ≪ DateInterval
  • DateInterval::createFromDateString ≫
  • PHP Manual
  • DateInterval
  • 新しい DateInterval オブジェクトを作成する

DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — 新しい DateInterval オブジェクトを作成する

説明

public DateInterval::__construct(string $duration)

新しい DateInterval オブジェクトを作成します。

パラメータ

duration

間隔。

最初は P から始まります。これは period を表します。 間隔の単位は、整数値の後に間隔指示子をつけて表します。 時間の要素を含む場合は、時間部分の前に文字 T を入れます。

duration の間隔指示子
間隔指示子 | 説明
Y | 年
M | 月
D | 日
W | 週。日付に変換されます。 PHP 8.0.0 より前のバージョンでは、 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 に基づくものです。

エラー / 例外

duration が間隔の値としてパースできない場合、 DateMalformedIntervalStringException がスローされます。 PHP 8.3 より前のバージョンでは、Exception がスローされていました。

変更履歴

バージョン | 説明
8.3.0 | Exception の代わりに、 DateMalformedIntervalStringException がスローされるようになりました。
8.2.0 | アクセス可能なプロパティは y から f, invert, days だけになりました。 新しい boolean プロパティ from_string もアクセス可能です。
8.0.0 | W が、D と組み合わせて使えるようになりました。

例

例1 DateInterval オブジェクトを作成して使う例

<?php
// Create a specific date
$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

// Create interval
$interval = new \DateInterval("P7D");

// Add interval
$someDate->add($interval);

// Convert interval to string
echo $interval->format("%d");

上の例の出力は以下となります。

7

例2 DateInterval の例

<?php

$interval = new DateInterval('P1W2D');
var_dump($interval);

?>

上の例の PHP 8.2 での出力は、このようになります。:

object(DateInterval)#1 (10) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(9)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["from_string"]=>
  bool(false)
}

上の例の PHP 8 での出力は、このようになります。:

object(DateInterval)#1 (16) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(9)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["weekday"]=>
  int(0)
  ["weekday_behavior"]=>
  int(0)
  ["first_last_day_of"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["special_type"]=>
  int(0)
  ["special_amount"]=>
  int(0)
  ["have_weekday_relative"]=>
  int(0)
  ["have_special_relative"]=>
  int(0)
}

上の例の PHP 7 での出力は、このようになります。

object(DateInterval)#1 (16) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(2)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["weekday"]=>
  int(0)
  ["weekday_behavior"]=>
  int(0)
  ["first_last_day_of"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["special_type"]=>
  int(0)
  ["special_amount"]=>
  int(0)
  ["have_weekday_relative"]=>
  int(0)
  ["have_special_relative"]=>
  int(0)
}

参考

  • DateInterval::format() - 間隔をフォーマットする
  • DateTime::add() - 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く
  • DateTime::diff() - ふたつの DateTime オブジェクトの差を返す


相対指定文字列から DateInterval を作成する

  • ≪ DateInterval::__construct
  • DateInterval::format ≫
  • PHP Manual
  • DateInterval
  • 相対指定文字列から DateInterval を作成する

DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する

説明

オブジェクト指向型

public static DateInterval::createFromDateString(string $datetime): DateInterval|false

手続き型

date_interval_create_from_date_string(string $datetime): DateInterval|false

DateTimeImmutable のコンストラクタで使われている日付パーサを用いて、パースされた相対指定文字列から DateInterval を作成します。

パラメータ

datetime

相対部分を含む日付。 特に、strtotime() や DateTimeImmutable、 DateTime が使うパーサーがサポートする 相対書式 を使って DateInterval を作ることができます。

P7D のような ISO-8601 フォーマットの文字列を使うには、 DateInterval のコンストラクタを使わなければいけません。

戻り値

新しい DateInterval のインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.2.0 | このメソッドを使って DateInterval を作った場合、 アクセス可能なプロパティは from_string と date_string だけになりました。

例

例1 日付の間隔のパース

<?php
// セットになっているふたつは、それぞれ同じ間隔を表します。
$i = new DateInterval('P1D');
$i = DateInterval::createFromDateString('1 day');

$i = new DateInterval('P2W');
$i = DateInterval::createFromDateString('2 weeks');

$i = new DateInterval('P3M');
$i = DateInterval::createFromDateString('3 months');

$i = new DateInterval('P4Y');
$i = DateInterval::createFromDateString('4 years');

$i = new DateInterval('P1Y1D');
$i = DateInterval::createFromDateString('1 year + 1 day');

$i = new DateInterval('P1DT12H');
$i = DateInterval::createFromDateString('1 day + 12 hours');

$i = new DateInterval('PT3600S');
$i = DateInterval::createFromDateString('3600 seconds');
?>

例2 パース処理の組み合わせと、負の間隔

<?php
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
echo $i->format('%d %h %i'), "\n";

$i = DateInterval::createFromDateString('1 year - 10 days');
echo $i->format('%y %d'), "\n";
?>

上の例の出力は以下となります。

449 2 70
1 -10

例3 特別な相対書式の間隔をパースする

<?php
$i = DateInterval::createFromDateString('last day of next month');
var_dump($i);

$i = DateInterval::createFromDateString('last weekday');
var_dump($i);

上の例の PHP 8.2 での出力は、このようになります。:

object(DateInterval)#1 (2) {
  ["from_string"]=>
  bool(true)
  ["date_string"]=>
  string(22) "last day of next month"
}
object(DateInterval)#2 (2) {
  ["from_string"]=>
  bool(true)
  ["date_string"]=>
  string(12) "last weekday"
}

上の例の PHP 8 での出力は、たとえば以下のようになります。:

object(DateInterval)#1 (16) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(1)
  ["d"]=>
  int(0)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["weekday"]=>
  int(0)
  ["weekday_behavior"]=>
  int(0)
  ["first_last_day_of"]=>
  int(2)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["special_type"]=>
  int(0)
  ["special_amount"]=>
  int(0)
  ["have_weekday_relative"]=>
  int(0)
  ["have_special_relative"]=>
  int(0)
}
object(DateInterval)#2 (16) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(0)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["weekday"]=>
  int(0)
  ["weekday_behavior"]=>
  int(0)
  ["first_last_day_of"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["special_type"]=>
  int(1)
  ["special_amount"]=>
  int(-1)
  ["have_weekday_relative"]=>
  int(0)
  ["have_special_relative"]=>
  int(1)
}


間隔をフォーマットする

  • ≪ DateInterval::createFromDateString
  • DatePeriod ≫
  • PHP Manual
  • DateInterval
  • 間隔をフォーマットする

DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — 間隔をフォーマットする

説明

public DateInterval::format(string $format): string

間隔をフォーマットします。

パラメータ

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 | DateTime::diff() の結果に使った場合は総日数、それ以外の場合は (unknown) | 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
F | マイクロ秒、少なくとも6桁。足りない分は先頭が0埋めされます。 | 007701, 052738, 428291
f | マイクロ秒、数値 | 7701, 52738, 428291
R 負の値の場合は "-"、正の値の場合は "+" -, +
r 負の値の場合は "-"、正の値の場合は空文字 -,

戻り値

フォーマットされた間隔を返します。

変更履歴

バージョン | 説明
7.2.12 | F と f フォーマットの値は、常に正の数値になりました。
7.1.0 | フォーマット文字 F と f が追加されました。

例

例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

注意

注意:

DateInterval::format() メソッドは、 時刻文字列や日付セグメントでの繰り越しを再計算しません。 これは意図的な仕様です。なぜなら "32 days" のようにオーバーフローした値は "1 month and 4 days" から "1 month and 1 day" までのどれとでも解釈可能だからです。

参考

  • DateTime::diff() - ふたつの DateTime オブジェクトの差を返す


DatePeriod クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

日付の期間をあらわします。

日付の期間を使うと、指定した期間に定期的に発生する内容を反復処理できます。

クラス概要

class DatePeriod implements IteratorAggregate {
/* 定数 */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* プロパティ */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* メソッド */
public __construct(
DateTimeInterface $start,
DateInterval $interval,
int $recurrences,
int $options = 0
)
public __construct(
DateTimeInterface $start,
DateInterval $interval,
DateTimeInterface $end,
int $options = 0
)
public __construct(string $isostr, int $options = 0)
public static createFromISO8601String(string $specification, int $options = 0): static
public getDateInterval(): DateInterval
public getEndDate(): ?DateTimeInterface
public getRecurrences(): ?int
public getStartDate(): DateTimeInterface
}

定義済み定数

DatePeriod::EXCLUDE_START_DATE

開始日を含まない。DatePeriod::__construct() で使用します。

DatePeriod::INCLUDE_END_DATE

終了日を含む。DatePeriod::__construct() で使用します。

プロパティ

recurrences

イテレータが返す最小のインスタンスの数。

DatePeriod のコンストラクタの recurrences に繰り返しの回数を明示的に渡した場合、 このプロパティにはその値が含まれます。 DatePeriod::EXCLUDE_START_DATE によって開始日が無効にされていない場合、 このプロパティには それよりひとつ多い 値が設定されます。 DatePeriod::INCLUDE_END_DATE で終了日が有効になっている場合、 このプロパティには さらにひとつ多い 値が設定されます。

繰り返しの回数を明示的に渡さなかった場合、 このプロパティには返される最小のインスタンスの数が含まれます。 この値は 0 になるはずですが、 DatePeriod::EXCLUDE_START_DATE によって開始日が無効にされていない場合、 このプロパティには それよりひとつ多い 値が設定されます。 DatePeriod::INCLUDE_END_DATE で終了日が有効になっている場合、 このプロパティには さらにひとつ多い 値が設定されます。

<?php
$start = new DateTime('2018-12-31 00:00:00');
$end = new DateTime('2021-12-31 00:00:00');
$interval = new DateInterval('P1M');
$recurrences = 5;
// コンストラクタで明示的に繰り返し回数を設定
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
echo $period->recurrences, "\n";
$period = new DatePeriod($start, $interval, $recurrences);
echo $period->recurrences, "\n";
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
echo $period->recurrences, "\n";
// コンストラクタで繰り返し回数を設定しない場合
$period = new DatePeriod($start, $interval, $end);
echo $period->recurrences, "\n";
$period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
echo $period->recurrences, "\n";
?>

上の例の出力は以下となります。

5
6
7
1
0

DatePeriod::getRecurrences() もご覧ください。

include_end_date

終了日を反復日のセットに含めるかどうか。

include_start_date

開始日を反復日のセットに含めるかどうか。

start

期間の開始日。

current

反復中に期間内の現在の日付が含まれます。

end

期間の終了日。

interval

ISO 8601 の繰り返し間隔の指定。

変更履歴

バージョン | 説明
8.2.0 | 定数 DatePeriod::INCLUDE_END_DATE と プロパティ include_end_date が追加されました。
8.0.0 | DatePeriod は、 IteratorAggregate を実装するようになりました。 これより前のバージョンでは、 Traversable を実装していました。

目次

  • DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する
  • DatePeriod::createFromISO8601String — ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する
  • DatePeriod::getDateInterval — 間隔を取得する
  • DatePeriod::getEndDate — 終了日を取得する
  • DatePeriod::getRecurrences — 繰り返しの数を取得する
  • DatePeriod::getStartDate — 開始日を取得する


新しい DatePeriod オブジェクトを作成する

  • ≪ DatePeriod
  • DatePeriod::createFromISO8601String ≫
  • PHP Manual
  • DatePeriod
  • 新しい DatePeriod オブジェクトを作成する

DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する

説明

public DatePeriod::__construct(
DateTimeInterface $start,
DateInterval $interval,
int $recurrences,
int $options = 0
)
public DatePeriod::__construct(
DateTimeInterface $start,
DateInterval $interval,
DateTimeInterface $end,
int $options = 0
)
警告
public DatePeriod::__construct(string $isostr, int $options = 0)

このコンストラクタのバリエーションは、推奨されなくなりました。 代わりに、DatePeriod::createFromISO8601String() を使いましょう。

新しい DatePeriod オブジェクトを作成します。

DatePeriod オブジェクトは、 たくさんの DateTimeImmutable や DateTime を生成するイテレータとして使えます。 パラメータ start, interval, end, および recurrences の数を指定できます。

返されるオブジェクトのクラスは、 start の祖先になるオブジェクトで、 DateTimeImmutable や DateTime に等しくなります。

パラメータ

start

期間の開始日。デフォルトでは、 結果セットに含まれています。

interval

期間内での発生間隔。

recurrences

反復回数。 返される結果の数は、この値よりひとつ大きくなります。 なぜなら、デフォルトでは結果セットに開始日が含まれているからです。 0 より大きな値でなければいけません。

end

期間の終了日。 デフォルトでは、結果セットから除外されています。

isostr

» ISO 8601 repeating interval specification のサブセットを指定します。

PHP がサポートしていない、サブセットの機能の例を以下に示します:

  1. 0回の繰り返し (R0/)
  2. UTC 以外の時間のオフセット(Z)。 たとえば +02:00 のようなものです。
options

開始日と終了日に関する振る舞いを制御するビットフィールド

DatePeriod::EXCLUDE_START_DATE を指定すると、開始日を期間の結果セットから除外できます。

DatePeriod::INCLUDE_END_DATE を指定すると、終了日を期間の結果セットに含めることができます。

エラー / 例外

isostr が有効な ISO 8601 の期間としてパースできない場合、 DateMalformedPeriodStringException をスローします。 これより前のバージョンでは、Exception がスローされていました。

変更履歴

バージョン | 説明
8.3.0 | Exception ではなく、 DateMalformedPeriodStringException がスローされるようになりました。
8.2.0 | 定数 DatePeriod::INCLUDE_END_DATE が追加されました。
7.2.19, 7.3.6, 7.4.0 | recurrences は、0 より大きな値が必須になりました。

例

例1 DatePeriod の例

<?php
$start = new DateTime('2012-07-01');
$interval = new DateInterval('P7D');
$end = new DateTime('2012-07-31');
$recurrences = 4;
$iso = 'R4/2012-07-01T00:00:00Z/P7D';

// これらはすべて同じ意味です
$period = new DatePeriod($start, $interval, $recurrences);
$period = new DatePeriod($start, $interval, $end);
$period = new DatePeriod($iso);

// DatePeriod の反復処理をすると、
// 期間内のすべての発生日が表示されます。
foreach ($period as $date) {
echo $date->format('Y-m-d')."\n";
}
?>

上の例の出力は以下となります。

2012-07-01
2012-07-08
2012-07-15
2012-07-22
2012-07-29

例2 DatePeriod で DatePeriod::EXCLUDE_START_DATE を使う例

<?php
$start = new DateTime('2012-07-01');
$interval = new DateInterval('P7D');
$end = new DateTime('2012-07-31');

$period = new DatePeriod($start, $interval, $end,
DatePeriod::EXCLUDE_START_DATE);

// DatePeriod の反復処理をすると、
// 期間内のすべての発生日が表示されます。
// ただし、今回の場合は 2012-07-01 が表示されません。
foreach ($period as $date) {
echo $date->format('Y-m-d')."\n";
}
?>

上の例の出力は以下となります。

2012-07-08
2012-07-15
2012-07-22
2012-07-29

例3 一年間に含まれる、月の最後の木曜日を全て表示する、DatePeriod の例

<?php
$begin = new DateTime('2021-12-31');
$end = new DateTime('2022-12-31 23:59:59');

$interval = DateInterval::createFromDateString('last thursday of next month');
$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

foreach ($period as $dt) {
echo $dt->format('l Y-m-d'), "\n";
}
?>

上の例の出力は以下となります。

Thursday 2022-01-27
Thursday 2022-02-24
Thursday 2022-03-31
Thursday 2022-04-28
Thursday 2022-05-26
Thursday 2022-06-30
Thursday 2022-07-28
Thursday 2022-08-25
Thursday 2022-09-29
Thursday 2022-10-27
Thursday 2022-11-24
Thursday 2022-12-29

注意

ISO 8601 のセクション 4.5 "Recurring time interval" に記載されている無限回数の繰り返しには対応していません。 つまり、isostr に "R/..." を渡したり end に null を渡したりしても動作しません。


ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する

  • ≪ DatePeriod::__construct
  • DatePeriod::getDateInterval ≫
  • PHP Manual
  • DatePeriod
  • ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する

DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する

説明

public static DatePeriod::createFromISO8601String(string $specification, int $options = 0): static

ISO8601 形式の文字列から、specification の指定に従い、新しい DatePeriod オブジェクトを作成します。

パラメータ

specification

» ISO 8601 repeating interval specification のサブセットを指定します。

有効な ISO8601 形式の期間指定のサンプルとして、 　R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M のようなものがあります。これは、以下を指定しています:

  • 5 回繰り返す (R5/)
  • 2008-03-01T13:00:00Z から開始
  • それぞれの繰り返しは、 1 year, 2 months, 10 days, 2 hours, 30 minute の間隔を持つ。 (/P1Y2M10DT2H30M).

ISO8601 形式の期間指定によっては、PHP がサポートしていないものがあります。 たとえば以下のようなものがあります:

  1. 繰り返しが0回 (R0/)
  2. UTC (Z) 以外のタイムオフセット。 たとえば +02:00 のようなものです。
options

開始日と、終了日についての振る舞いを制御するのに使うビットフィールドです。

DatePeriod::EXCLUDE_START_DATE を指定すると、期間内に繰り返される集合から開始日を除外できます。

DatePeriod::INCLUDE_END_DATE を指定すると、期間内に繰り返される集合に終了日を含めることができます。

戻り値

新しい DatePeriod オブジェクトを作成します。

このメソッドを使って作成された DatePeriod オブジェクトは、多くの DateTimeImmutable オブジェクトを生成するイテレータとして使えます。

エラー / 例外

specification が、有効な ISO8601 形式の期間として パースできない場合、DateMalformedPeriodStringException がスローされます。

例

例1 DatePeriod::createFromISO8601String の例

<?php
$iso = 'R4/2023-07-01T00:00:00Z/P7D';

$period = DatePeriod::createFromISO8601String($iso);

// DatePeriod オブジェクトを走査することで、
// その期間内で発生する日付を全て出力します
foreach ($period as $date) {
echo $date->format('Y-m-d'), "\n";
}
?>

上の例の出力は以下となります。

2023-07-01
2023-07-08
2023-07-15
2023-07-22
2023-07-29


間隔を取得する

  • ≪ DatePeriod::createFromISO8601String
  • DatePeriod::getEndDate ≫
  • PHP Manual
  • DatePeriod
  • 間隔を取得する

DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — 間隔を取得する

説明

オブジェクト指向型

public DatePeriod::getDateInterval(): DateInterval

期間に適用される間隔を表す DateInterval object を取得する。

パラメータ

この関数にはパラメータはありません。

戻り値

DateInterval object を返す。

例

例1 DatePeriod::getDateInterval() の例

<?php
$period = new DatePeriod('R7/2016-05-16T00:00:00Z/P1D');
$interval = $period->getDateInterval();
echo $interval->format('%d day');
?>

上の例の出力は以下となります。

1 day

参考

  • DatePeriod::getStartDate() - 開始日を取得する
  • DatePeriod::getEndDate() - 終了日を取得する


終了日を取得する

  • ≪ DatePeriod::getDateInterval
  • DatePeriod::getRecurrences ≫
  • PHP Manual
  • DatePeriod
  • 終了日を取得する

DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — 終了日を取得する

説明

オブジェクト指向型

public DatePeriod::getEndDate(): ?DateTimeInterface

期間の終了日を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

DatePeriod が終了日を持たない場合は null を返します。 たとえば、recurrences パラメータや、終了日のない isostr パラメータを用いて初期化されている場合です。

DatePeriod が DateTimeImmutable オブジェクトを end に指定して初期化されている場合は DateTimeImmutable オブジェクト を返します。

それ以外の場合は、 終了日を表す、コピーされた DateTime オブジェクトを返します。

例

例1 DatePeriod::getEndDate() の例

<?php
$period = new DatePeriod(
new DateTime('2016-05-16T00:00:00Z'),
new DateInterval('P1D'),
new DateTime('2016-05-20T00:00:00Z')
);
$start = $period->getEndDate();
echo $start->format(DateTime::ISO8601);
?>

上の例の出力は以下となります。

2016-05-20T00:00:00+0000

例2 終了日のない DatePeriod::getEndDate()

<?php
$period = new DatePeriod(
new DateTime('2016-05-16T00:00:00Z'),
new DateInterval('P1D'),
7
);
var_dump($period->getEndDate());
?>

上の例の出力は以下となります。

NULL

参考

  • DatePeriod::getStartDate() - 開始日を取得する
  • DatePeriod::getDateInterval() - 間隔を取得する


繰り返しの数を取得する

  • ≪ DatePeriod::getEndDate
  • DatePeriod::getStartDate ≫
  • PHP Manual
  • DatePeriod
  • 繰り返しの数を取得する

DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — 繰り返しの数を取得する

説明

オブジェクト指向型

public DatePeriod::getRecurrences(): ?int

繰り返しの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

DatePeriod のコンストラクタの $recurrences に明示的に渡すことで設定した 繰り返しの数を返します。設定されていない場合、null を返します。

例

例1 DatePeriod::getRecurrences() が異なる値を返す例

<?php
$start = new DateTime('2018-12-31 00:00:00');
$end = new DateTime('2021-12-31 00:00:00');
$interval = new DateInterval('P1M');
$recurrences = 5;
// コンストラクタで明示的に繰り返し回数を設定
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
echo $period->getRecurrences(), "\n";
$period = new DatePeriod($start, $interval, $recurrences);
echo $period->getRecurrences(), "\n";
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
echo $period->getRecurrences(), "\n\n";
// コンストラクタで繰り返し回数を設定しない場合
$period = new DatePeriod($start, $interval, $end);
var_dump($period->getRecurrences());
$period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
var_dump($period->getRecurrences());
?>

上の例の出力は以下となります。

5
5
5

NULL
NULL

参考

  • DatePeriod::$recurrences


開始日を取得する

  • ≪ DatePeriod::getRecurrences
  • 日付・時刻 関数 ≫
  • PHP Manual
  • DatePeriod
  • 開始日を取得する

DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — 開始日を取得する

説明

オブジェクト指向型

public DatePeriod::getStartDate(): DateTimeInterface

期間の開始日を取得する。

パラメータ

この関数にはパラメータはありません。

戻り値

DatePeriod が DateTimeImmutable object を start パラメータに用いて初期化されている場合は DateTimeImmutable object を返す。

それ例外の場合は DateTime object を返す。

例

例1 DatePeriod::getStartDate() の例

<?php
$period = new DatePeriod('R7/2016-05-16T00:00:00Z/P1D');
$start = $period->getStartDate();
echo $start->format(DateTime::ISO8601);
?>

上の例の出力は以下となります。

2016-05-16T00:00:00+0000

参考

  • DatePeriod::getEndDate() - 終了日を取得する
  • DatePeriod::getDateInterval() - 間隔を取得する


日付・時刻 関数

目次

  • checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します
  • date — Unixタイムスタンプを書式化する
  • date_add — DateTime::add のエイリアス
  • date_create — 新しい DateTime オブジェクトを作成する
  • date_create_from_format — DateTime::createFromFormat のエイリアス
  • date_create_immutable — 新しい DateTimeImmutable オブジェクトを作成する
  • date_create_immutable_from_format — DateTimeImmutable::createFromFormat のエイリアス
  • date_date_set — DateTime::setDate のエイリアス
  • date_default_timezone_get — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する
  • date_default_timezone_set — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する
  • date_diff — DateTime::diff のエイリアス
  • date_format — DateTime::format のエイリアス
  • date_get_last_errors — DateTimeImmutable::getLastErrors のエイリアス
  • date_interval_create_from_date_string — DateInterval::createFromDateString のエイリアス
  • date_interval_format — DateInterval::format のエイリアス
  • date_isodate_set — DateTime::setISODate のエイリアス
  • date_modify — DateTime::modify のエイリアス
  • date_offset_get — DateTime::getOffset のエイリアス
  • date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す
  • date_parse_from_format — 指定した書式でフォーマットされた日付についての情報を取得する
  • date_sub — DateTime::sub のエイリアス
  • date_sun_info — 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す
  • date_sunrise — 指定した日付と場所についての日の出時刻を返す
  • date_sunset — 指定した日付と場所についての日の入り時刻を返す
  • date_time_set — DateTime::setTime のエイリアス
  • date_timestamp_get — DateTime::getTimestamp のエイリアス
  • date_timestamp_set — DateTime::setTimestamp のエイリアス
  • date_timezone_get — DateTime::getTimezone のエイリアス
  • date_timezone_set — DateTime::setTimezone のエイリアス
  • getdate — 日付/時刻情報を取得する
  • gettimeofday — 現在の時間を得る
  • gmdate — GMT/UTC の日付/時刻を書式化する
  • gmmktime — GMT 日付から Unix タイムスタンプを取得する
  • gmstrftime — ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする
  • idate — ローカルな時刻/日付の一部を整数として整形する
  • localtime — ローカルタイムを得る
  • microtime — 現在の Unix タイムスタンプをマイクロ秒まで返す
  • mktime — 日付を Unix のタイムスタンプとして取得する
  • strftime — ロケールの設定に基づいてローカルな日付・時間をフォーマットする
  • strptime — strftime が生成した日付/時刻をパースする
  • strtotime — 英文形式の日付を Unix タイムスタンプに変換する
  • time — 現在の Unix タイムスタンプを返す
  • timezone_abbreviations_list — DateTimeZone::listAbbreviations のエイリアス
  • timezone_identifiers_list — DateTimeZone::listIdentifiers のエイリアス
  • timezone_location_get — DateTimeZone::getLocation のエイリアス
  • timezone_name_from_abbr — 略称とUTCオフセットから、タイムゾーン名を推測して返す
  • timezone_name_get — DateTimeZone::getName のエイリアス
  • timezone_offset_get — DateTimeZone::getOffset のエイリアス
  • timezone_open — DateTimeZone::__construct のエイリアス
  • timezone_transitions_get — DateTimeZone::getTransitions のエイリアス
  • timezone_version_get — timezonedb のバージョンを取得する


グレゴリオ暦の日付/時刻の妥当性を確認します

  • ≪ 日付・時刻 関数
  • date ≫
  • PHP Manual
  • 日付・時刻 関数
  • グレゴリオ暦の日付/時刻の妥当性を確認します

checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します

説明

checkdate(int $month, int $day, int $year): bool

引数で指定された日付の妥当性をチェックします。 各パラメータが適切に指定されている場合に、妥当であると判断されます。

パラメータ

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 タイムスタンプに変換する


Unixタイムスタンプを書式化する

  • ≪ checkdate
  • date_add ≫
  • PHP Manual
  • 日付・時刻 関数
  • Unixタイムスタンプを書式化する

date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — Unixタイムスタンプを書式化する

説明

date(string $format, ?int $timestamp = null): string

指定された引数 timestamp (Unixタイムスタンプ) を、与えられた フォーマット文字列によりフォーマットし、日付文字列を返します。 タイムスタンプが与えられない場合は、現在の時刻が使われます。 つまり timestamp はオプションであり そのデフォルト値は time() の値です。

警告

Unixタイムスタンプはタイムゾーンを処理しません。 タイムゾーン情報が付加された日付/時刻の情報を書式化するには、 DateTimeImmutable クラスや、 DateTimeInterface::format() を使って下さい。

パラメータ

format

DateTimeInterface::format() が受け入れるフォーマット。

注意: date() 関数は、マイクロ秒については常に 000000 を生成します。 というのも、この関数が受け取るパラメータは int 型だからです。 一方 DateTime をマイクロ秒つきで作成した場合は、 DateTime::format() はマイクロ秒にも対応しています。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

戻り値

フォーマットされた日付を表す文字列を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例1 date() の例

<?php
// 使用するデフォルトのタイムゾーンを指定します。
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));

/* 書式指定パラメータに、定数を使用します。 */
// 結果は、たとえば Wed, 25 Sep 2013 15:28:57 -0700 のようになります。
echo date(DATE_RFC2822);

// 結果は、たとえば 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
$today = date("Y-m-d H:i:s"); // 2001-03-10 17:16:18 (MySQL の DATETIME フォーマット)
?>

他の言語で日付をフォーマットする用途には、 date() のかわりに IntlDateFormatter::format() が使えます。

注意

注意:

日付の文字列表現からタイムスタンプを生成するには、 strtotime() が使用できるでしょう。 さらに、いくつかのデータベースは（MySQL の » UNIX_TIMESTAMP 関数の ような）日付フォーマットからタイムスタンプへの変換関数を有しています。

ヒント

$_SERVER['REQUEST_TIME'] によって、リクエスト開始時のタイムスタンプが取得できます。

参考

  • DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す
  • DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
  • gmdate() - GMT/UTC の日付/時刻を書式化する
  • idate() - ローカルな時刻/日付の一部を整数として整形する
  • getdate() - 日付/時刻情報を取得する
  • getlastmod() - 最終更新時刻を取得する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする
  • time() - 現在の Unix タイムスタンプを返す
  • 定義済みの定数


DateTime::add のエイリアス

  • ≪ date
  • date_create ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::add のエイリアス

date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — DateTime::add() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::add()


新しい DateTime オブジェクトを作成する

  • ≪ date_add
  • date_create_from_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • 新しい DateTime オブジェクトを作成する

date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — 新しい DateTime オブジェクトを作成する

説明

date_create(string $datetime = "now", ?DateTimeZone $timezone = null): DateTime|false

DateTime::__construct() の手続き型バージョンです。

DateTime のコンストラクタと異なり、 datetime に渡された文字列が不正な場合には、 例外をスローする代わりに false を返します。

パラメータ

DateTimeImmutable::__construct も参照ください。

戻り値

新しい DateTime クラスのインスタンスを返します。失敗した場合に false を返します

参考

  • DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す
  • DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする
  • DateTime::__construct() - 新しい DateTime オブジェクトを返す


DateTime::createFromFormat のエイリアス

  • ≪ date_create
  • date_create_immutable ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::createFromFormat のエイリアス

date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — DateTime::createFromFormat() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::createFromFormat()


新しい DateTimeImmutable オブジェクトを作成する

  • ≪ date_create_from_format
  • date_create_immutable_from_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • 新しい DateTimeImmutable オブジェクトを作成する

date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — 新しい DateTimeImmutable オブジェクトを作成する

説明

date_create_immutable(string $datetime = "now", ?DateTimeZone $timezone = null): DateTimeImmutable|false

これは DateTimeImmutable::__construct() の手続き型バージョンです。

DateTimeImmutable のコンストラクタと異なり、 datetime が不正な文字列だった場合には 例外をスローする代わりに false を返します。

パラメータ

DateTimeImmutable::__construct を参照ください。

戻り値

新しい DateTimeImmutable のインスタンスを返します。失敗した場合に false を返します

参考

  • DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする


DateTimeImmutable::createFromFormat のエイリアス

  • ≪ date_create_immutable
  • date_date_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeImmutable::createFromFormat のエイリアス

date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — DateTimeImmutable::createFromFormat() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::createFromFormat()


DateTime::setDate のエイリアス

  • ≪ date_create_immutable_from_format
  • date_default_timezone_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setDate のエイリアス

date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — DateTime::setDate() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setDate()


スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

  • ≪ date_date_set
  • date_default_timezone_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

説明

date_default_timezone_get(): string

この関数は、デフォルトのタイムゾーンを以下の優先順位で取得して返します。

  • date_default_timezone_set() 関数を使用して 設定したタイムゾーン (もし何か設定されていれば) を読み込む

  • date.timezone ini オプション (設定されていれば) を読み込む

上のすべてが失敗した場合は、date_default_timezone_get() はデフォルトのタイムゾーンである UTC を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

string を返します。

例

例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() - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する
  • サポートされるタイムゾーンのリスト


スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

  • ≪ date_default_timezone_get
  • date_diff ≫
  • PHP Manual
  • 日付・時刻 関数
  • スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

説明

date_default_timezone_set(string $timezoneId): bool

date_default_timezone_set() は、日付/時刻関数で 使用されるデフォルトタイムゾーンを設定します。

スクリプト内でこの関数を使用してデフォルトタイムゾーンを設定するかわりに、 INI 設定 date.timezone でデフォルトタイムゾーンを設定することもできます。

パラメータ

timezoneId

タイムゾーン ID 。例えば UTC, Africa/Lagos, Asia/Hong_Kong や Europe/Lisbon など。有効な ID の一覧は サポートされるタイムゾーンのリスト にあります。

戻り値

この関数は、timezoneId が 無効なものである場合に 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.';
}
?>

参考

  • date_default_timezone_get() - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する
  • サポートされるタイムゾーンのリスト


DateTime::diff のエイリアス

  • ≪ date_default_timezone_set
  • date_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::diff のエイリアス

date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — DateTime::diff() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::diff()


DateTime::format のエイリアス

  • ≪ date_diff
  • date_get_last_errors ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::format のエイリアス

date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — DateTime::format() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::format()


DateTimeImmutable::getLastErrors のエイリアス

  • ≪ date_format
  • date_interval_create_from_date_string ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeImmutable::getLastErrors のエイリアス

date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — DateTimeImmutable::getLastErrors() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::getLastErrors()


DateInterval::createFromDateString のエイリアス

  • ≪ date_get_last_errors
  • date_interval_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateInterval::createFromDateString のエイリアス

date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — DateInterval::createFromDateString() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateInterval::createFromDateString()


DateInterval::format のエイリアス

  • ≪ date_interval_create_from_date_string
  • date_isodate_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateInterval::format のエイリアス

date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — DateInterval::format() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateInterval::format()


DateTime::setISODate のエイリアス

  • ≪ date_interval_format
  • date_modify ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setISODate のエイリアス

date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — DateTime::setISODate() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setISODate()


DateTime::modify のエイリアス

  • ≪ date_isodate_set
  • date_offset_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::modify のエイリアス

date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — DateTime::modify() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::modify()


DateTime::getOffset のエイリアス

  • ≪ date_modify
  • date_parse ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getOffset のエイリアス

date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — DateTime::getOffset() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getOffset()


指定した日付/時刻の詳細な情報を連想配列で返す

  • ≪ date_offset_get
  • date_parse_from_format ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した日付/時刻の詳細な情報を連想配列で返す

date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す

説明

date_parse(string $datetime): array

date_parse() は、 strtotime() や DateTimeImmutable::__construct() と同じルールに従って datetime をパースします。 Unixタイムスタンプ (strtotime() の場合) や DateTimeImmutable (DateTimeImmutable::__construct() の場合) を返す代わりに、指定した datetime から検知できた情報を連想配列として返します。

あるグループの要素に関する情報が見つからなかった場合、 そうした情報は false に設定されたり、存在しない状態になります。 datetime に指定する文字列から、 同等のタイムスタンプや DateTimeImmutable オブジェクトを構築する必要がある場合、 より多くのフィールドを false でない値に設定できます。 そうしたことが起こる場合については、 以下に示す例を参照ください。

パラメータ

datetime

DateTimeImmutable::__construct() が理解できる書式の日付/時刻。

戻り値

パースした日付/時刻情報を含む配列を返します。

返される配列は、 year, month, day, hour, minute, second, fraction, is_localtime というキーを持ちます。

is_localtime が存在する場合、 zone_type がタイムゾーンのタイプを示します。 タイプ 1 (UTC オフセット) の場合、 zone と is_dst フィールドが追加されます。 タイプ 2 (省略形) の場合、 tz_abbr と is_dst フィールドが追加されます。 タイプ 3 (タイムゾーン識別子) の場合、 tz_abbr, tz_id が追加されます。

+3 days のような、 相対時刻の文字列が datetime に存在する場合、返される配列には、relative をキーとしたネストされた配列が含まれます。 この配列には、year, month, day, hour, minute, second が含まれ、 渡される文字列に応じて、必要があれば weekday, weekdays も含まれます。

warning_count と warnings が配列に含まれます。 最初のフィールドは、警告が何個発生したかを示します。 warnings 配列は、 警告を説明する文字列と一緒に、指定された datetime のどの場所で警告が発生したかの位置を示します。

error_count, errors フィールドも配列に含まれます。 最初のフィールドは、エラーが何個発生したかを示します。 errors 配列は、 警告を説明する文字列と一緒に、指定された datetime のどの場所でエラーが発生したかの位置を示します。

警告

warnings と errors に含まれる配列の要素数は、 同じ箇所でエラーや警告が発生した場合、 warning_count や error_count よりも少なくなる可能性があります。

エラー / 例外

日付/時刻フォーマットにエラーがある場合は、 'errors' 要素にエラーメッセージが格納されます。

変更履歴

バージョン | 説明
7.2.0 | 返される配列の zone 要素が、 分ではなく秒を表すようになり、 符号が逆になりました。 たとえば、 -120 は 7200 を表すようになります。

例

例1 datetime に包括的な情報を指定した date_parse() の例

<?php
var_dump(date_parse("2006-12-12 10:00:00.5"));
?>

上の例の出力は以下となります。

array(12) {
  ["year"]=>
  int(2006)
  ["month"]=>
  int(12)
  ["day"]=>
  int(12)
  ["hour"]=>
  int(10)
  ["minute"]=>
  int(0)
  ["second"]=>
  int(0)
  ["fraction"]=>
  float(0.5)
  ["warning_count"]=>
  int(0)
  ["warnings"]=>
  array(0) {
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(false)
}

指定された datetime にタイムゾーン情報が含まれた場合にのみ、 タイムゾーンの要素が現れるようになります。 この場合、zone_type 要素が常に存在し、 値によっては少し多くの要素が含まれます。

例2 タイムゾーンの省略形を与えた場合の date_parse() の例

<?php
var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));
?>

上の例の出力は以下となります。

array(16) {
  ["year"]=>
  int(2022)
  ["month"]=>
  int(6)
  ["day"]=>
  int(2)
  ["hour"]=>
  int(10)
  ["minute"]=>
  int(28)
  ["second"]=>
  int(17)
  ["fraction"]=>
  float(0)
  ["warning_count"]=>
  int(0)
  ["warnings"]=>
  array(0) {
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(true)
  ["zone_type"]=>
  int(2)
  ["zone"]=>
  int(0)
  ["is_dst"]=>
  bool(true)
  ["tz_abbr"]=>
  string(3) "BST"
}

例3 タイムゾーン情報を与えた date_parse() の例

<?php
var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));
?>

上の例の出力は以下となります。

array(14) {
  ["year"]=>
  int(2022)
  ["month"]=>
  int(6)
  ["day"]=>
  int(2)
  ["hour"]=>
  int(10)
  ["minute"]=>
  int(28)
  ["second"]=>
  int(17)
  ["fraction"]=>
  float(0)
  ["warning_count"]=>
  int(0)
  ["warnings"]=>
  array(0) {
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(true)
  ["zone_type"]=>
  int(3)
  ["tz_id"]=>
  string(13) "Europe/London"
}

さらに最低限の文字列を datetime に与えてパースさせた場合、 情報量はさらに少なくなります。以下の例では、 全ての時刻に関する情報が false になります。

例4 最低限の文字列だけを与えた date_parse() の例

<?php
var_dump(date_parse("June 2nd, 2022"));
?>

上の例の出力は以下となります。

array(12) {
  ["year"]=>
  int(2022)
  ["month"]=>
  int(6)
  ["day"]=>
  int(2)
  ["hour"]=>
  bool(false)
  ["minute"]=>
  bool(false)
  ["second"]=>
  bool(false)
  ["fraction"]=>
  bool(false)
  ["warning_count"]=>
  int(0)
  ["warnings"]=>
  array(0) {
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(false)
}

相対的な書式 は 絶対的な書式のパース結果に影響を及ぼさず、別途 "relative" 要素にまとめられます。

例5 "relative" フォーマットを使った date_parse() の例

<?php
var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));
?>

上の例の出力は以下となります。

array(13) {
  ["year"]=>
  int(2006)
  ["month"]=>
  int(12)
  ["day"]=>
  int(12)
  ["hour"]=>
  int(10)
  ["minute"]=>
  int(0)
  ["second"]=>
  int(0)
  ["fraction"]=>
  float(0.5)
  ["warning_count"]=>
  int(0)
  ["warnings"]=>
  array(0) {
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(false)
  ["relative"]=>
  array(6) {
    ["year"]=>
    int(0)
    ["month"]=>
    int(0)
    ["day"]=>
    int(7)
    ["hour"]=>
    int(1)
    ["minute"]=>
    int(0)
    ["second"]=>
    int(0)
  }
}

Thursday のように、 語句によっては、文字列の時刻の部分に 0 を設定するものがあります。 Thursday を DateTimeImmutable::__construct() に与えた場合、hour, minute, second は 0 に設定されます。 以下の例では、year の要素は false に設定されます。

例6 date_parse() の副作用

<?php
var_dump(date_parse("Thursday, June 2nd"));
?>

上の例の出力は以下となります。

array(13) {
  ["year"]=>
  bool(false)
  ["month"]=>
  int(6)
  ["day"]=>
  int(2)
  ["hour"]=>
  int(0)
  ["minute"]=>
  int(0)
  ["second"]=>
  int(0)
  ["fraction"]=>
  float(0)
  ["warning_count"]=>
  int(0)
  ["warnings"]=>
  array(0) {
  }
  ["error_count"]=>
  int(0)
  ["errors"]=>
  array(0) {
  }
  ["is_localtime"]=>
  bool(false)
  ["relative"]=>
  array(7) {
    ["year"]=>
    int(0)
    ["month"]=>
    int(0)
    ["day"]=>
    int(0)
    ["hour"]=>
    int(0)
    ["minute"]=>
    int(0)
    ["second"]=>
    int(0)
    ["weekday"]=>
    int(4)
  }
}

参考

  • 指定されたフォーマットに従って datetime をパースする DateTimeImmutable::parseFromFormat()
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • getdate() - 日付/時刻情報を取得する


指定した書式でフォーマットされた日付についての情報を取得する

  • ≪ date_parse
  • date_sub ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した書式でフォーマットされた日付についての情報を取得する

date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — 指定した書式でフォーマットされた日付についての情報を取得する

説明

date_parse_from_format(string $format, string $datetime): array

指定した日付/時刻についての詳細情報を連想配列で返します。

パラメータ

format

format の使い方に関するドキュメントは、 DateTimeImmutable::createFromFormat() のそれを参照ください。同じルールが適用されます。

datetime

日付/時刻をあらわす文字列。

戻り値

指定した日付/時刻についての詳細情報を連想配列で返します。

返される配列は、 year, month, day, hour, minute, second, fraction, is_localtime というキーを持ちます。

is_localtime が存在する場合、 zone_type がタイムゾーンのタイプを示します。 タイプ 1 (UTC オフセット) の場合、 zone と is_dst フィールドが追加されます。 タイプ 2 (省略形) の場合、 tz_abbr と is_dst フィールドが追加されます。 タイプ 3 (タイムゾーン識別子) の場合、 tz_abbr, tz_id が追加されます。

warning_count と warnings が配列に含まれます。 最初のフィールドは、警告が何個発生したかを示します。 warnings 配列は、 警告を説明する文字列と一緒に、指定された datetime のどの場所で警告が発生したかの位置を示します。 下記の例で、警告の例を示します。

error_count, errors フィールドも配列に含まれます。 最初のフィールドは、エラーが何個発生したかを示します。 errors 配列のキーは、 警告を説明する文字列と一緒に、指定された datetime のどの場所でエラーが発生したかの位置を示します。 下記の例で、エラーの例を示します。

警告

warnings と errors に含まれる配列の要素数は、 同じ箇所でエラーや警告が発生した場合、 warning_count や error_count よりも少なくなる可能性があります。

エラー / 例外

datetime に NULLバイトが含まれている場合は、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.21, 8.1.8, 8.2.0 | datetime に NULLバイトが含まれている場合は、 ValueError がスローされるようになりました。 これより前のバージョンでは、こうした値は静かに無視されていました。
7.2.0 | 返される配列の zone 要素が、 分ではなく秒を表すようになり、 符号が逆になりました。 たとえば、 -120 は 7200 を表すようになります。

例

例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] => 3600
    [is_dst] =>
)

例2 date_parse_from_format() の結果に警告が含まれる例

<?php
$date = "26 August 2022 22:30 pm";
$parsed = date_parse_from_format("j F Y G:i a", $date);

echo "Warnings count: ", $parsed['warning_count'], "\n";
foreach ($parsed['warnings'] as $position => $message) {
echo "\tOn position {$position}: {$message}\n";
}
?>

上の例の出力は以下となります。

Warnings count: 1
    On position 23: The parsed time was invalid

例3 date_parse_from_format() の結果にエラーが含まれる例

<?php
$date = "26 August 2022 CEST";
$parsed = date_parse_from_format("j F Y H:i", $date);

echo "Errors count: ", $parsed['error_count'], "\n";
foreach ($parsed['errors'] as $position => $message) {
echo "\tOn position {$position}: {$message}\n";
}
?>

上の例の出力は以下となります。

Errors count: 3
    On position 15: A two digit hour could not be found
    On position 19: Data missing

参考

  • DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します


DateTime::sub のエイリアス

  • ≪ date_parse_from_format
  • date_sun_info ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::sub のエイリアス

date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — DateTime::sub() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::sub()

参考

  • DateTimeImmutable::sub() - 年月日時分秒の値を引く
  • DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く


日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

  • ≪ date_sub
  • date_sunrise ≫
  • PHP Manual
  • 日付・時刻 関数
  • 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

説明

date_sun_info(int $timestamp, float $latitude, float $longitude): array

パラメータ

timestamp

Unixタイムスタンプ。

latitude

緯度を表す度数。

longitude

経度を表す度数。

戻り値

配列を返します。配列の構造の詳細は、以下のリストのとおりです:

sunrise
日の出のタイムスタンプ (天頂角 = 90°50' )
sunset
日の入りのタイムスタンプ (天頂角 = 90°35' )
transit
太陽が天頂に達するタイムスタンプ。 つまり、もっとも上部に達した時刻です。
civil_twilight_begin
夜明けの始まり(天頂角 = 96°) sunrise の時刻に終了します。
civil_twilight_end
夕暮れの終わり(天頂角 = 96°) sunset の時刻に始まります。
nautical_twilight_begin
航海上の夜明け (天頂角 = 102°) civil_twilight_begin に終了します。
nautical_twilight_end
航海上の夕暮れ (天頂角 = 102°) civil_twilight_end の時刻に始まります。
astronomical_twilight_begin
天文学上の夜明け (天頂角 = 108°) nautical_twilight_begin に終了します。
astronomical_twilight_end
天文学上の夕暮れ (天頂角 = 108°) nautical_twilight_end の時刻に始まります。

配列の要素の値は、UNIXタイムスタンプ、または 太陽が天頂より一日中下にある場合、false です。 また、一日中天頂より上にある場合、 true です。

変更履歴

バージョン | 説明
7.2.0 | ローカルの昼ではなく、 夜中に関する計算結果が修正されました。 これによって、結果が少し変わります。

例

例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

例2 極夜のデータに処理を少し行う例

<?php
$tz = new \DateTimeZone('America/Anchorage');

$si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
foreach ($si as $key => $value) {
echo
match ($value) {
true => 'always',
false => 'never',
default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
},
": {$key}",
"\n";
}
?>

上の例の出力は以下となります。

never: sunrise
never: sunset
12:52:18 AKST: transit
10:53:19 AKST: civil_twilight_begin
14:51:17 AKST: civil_twilight_end
09:01:47 AKST: nautical_twilight_begin
16:42:48 AKST: nautical_twilight_end
07:40:47 AKST: astronomical_twilight_begin
18:03:49 AKST: astronomical_twilight_end

例3 Midnight sun の例(Tromso, Norway)

<?php
$si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
print_r($si);
?>

上の例の出力は以下となります。

Array
(
    [sunrise] => 1
    [sunset] => 1
    [transit] => 1656240426
    [civil_twilight_begin] => 1
    [civil_twilight_end] => 1
    [nautical_twilight_begin] => 1
    [nautical_twilight_end] => 1
    [astronomical_twilight_begin] => 1
    [astronomical_twilight_end] => 1
)

例4 一日の長さを計算する例 (Kyiv)

<?php
$si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
$diff = $si['sunset'] - $si['sunrise'];
echo "Length of day: ",
floor($diff / 3600), "h ",
floor(($diff % 3600) / 60), "s\n";
?>

上の例の出力は以下となります。

Length of day: 13h 56s


指定した日付と場所についての日の出時刻を返す

  • ≪ date_sun_info
  • date_sunset ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した日付と場所についての日の出時刻を返す

date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — 指定した日付と場所についての日の出時刻を返す

警告

この関数は PHP 8.1.0 で 非推奨 になります。 この機能に頼らないことを強く推奨します。 代わりに date_sun_info() を使ってください。

説明

date_sunrise(
int $timestamp,
int $returnFormat = SUNFUNCS_RET_STRING,
?float $latitude = null,
?float $longitude = null,
?float $zenith = null,
?float $utcOffset = null
): string|int|float|false

date_sunrise() は、与えられた日付 (timestamp で指定する) と場所についての日の出の時刻を返します。

パラメータ

timestamp

日の出時刻を取得する日の timestamp。

returnFormat

returnFormat 定数
定数 | 説明 | 例
SUNFUNCS_RET_STRING | 結果を string で返します。 | 16:46
SUNFUNCS_RET_DOUBLE | 結果を float で返します。 | 16.78243132
SUNFUNCS_RET_TIMESTAMP | 結果を int (タイムスタンプ) で返します。 | 1095034606

latitude

デフォルトは北緯で、南緯は負の値で表します。 date.default_latitude も参照ください。

longitude

デフォルトは東経で、西経は負の値で表します。 date.default_longitude も参照ください。

zenith

zenith は 太陽の中心と、地球の表面からの垂線の間になす角度です。 デフォルトは date.sunrise_zenith です。

一般的な zenith の角度
角度 | 説明
90°50' | 日の出: 太陽が見えるようになる点
96° | 薄明かり: 夜明けの始まりを示すのに慣習的に使われます
102° | 航海上の薄明かり: 海の上で、水平線が見えはじめる点
108° | 天文学上の薄明かり: 太陽があらゆる明かりの光源になりはじめる点

utcOffset

時間単位で指定します。 returnFormat が SUNFUNCS_RET_TIMESTAMP の場合は、 utcOffset は無視されます。

戻り値

日の出時刻を、指定した returnFormat で返します。 失敗した場合に false を返します。 失敗する潜在的な可能性があります。太陽が全く昇らない場合です。 これは一年のある時期、極圏の中にある場合に起こります。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 date_sun_info() を代わりに使って下さい。
8.0.0 | latitude, longitude, zenith, utcOffset は、nullable になりました。

例

例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

例2 No sunrise

<?php
$solstice = strtotime('2017-12-21');
var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
?>

上の例の出力は以下となります。

bool(false)

参考

  • date_sun_info() - 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す


指定した日付と場所についての日の入り時刻を返す

  • ≪ date_sunrise
  • date_time_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • 指定した日付と場所についての日の入り時刻を返す

date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — 指定した日付と場所についての日の入り時刻を返す

警告

この関数は PHP 8.1.0 で 非推奨 になります。 この機能に頼らないことを強く推奨します。 代わりに date_sun_info() を使ってください。

説明

date_sunset(
int $timestamp,
int $returnFormat = SUNFUNCS_RET_STRING,
?float $latitude = null,
?float $longitude = null,
?float $zenith = null,
?float $utcOffset = null
): string|int|float|false

date_sunset() は、与えられた日付 (timestamp で指定する) と場所についての日の入り時刻を返します。

パラメータ

timestamp

日の入り時刻を取得する日の timestamp。

returnFormat

returnFormat 定数
定数 | 説明 | 例
SUNFUNCS_RET_STRING | 結果を string で返します。 | 16:46
SUNFUNCS_RET_DOUBLE | 結果を float で返します。 | 16.78243132
SUNFUNCS_RET_TIMESTAMP | 結果を int (タイムスタンプ) で返します。 | 1095034606

latitude

デフォルトは北緯で、南緯は負の値で表します。 date.default_latitude も参照ください。

longitude

デフォルトは東経で、西経は負の値で表します。 date.default_longitude も参照ください。

zenith

zenith は 太陽の中心と、地球の表面からの垂線の間になす角度です。 デフォルトは date.sunset_zenith です。

一般的な zenith の角度
角度 | 説明
90°50' | 日の入り: 太陽が見えなくなる点
96° | 薄明かり: 夕暮れの終わりを示すのに慣習的に使われます
102° | 航海上の薄明かり: 海の上で、水平線が見えなくなった点
108° | 天文学上の薄明かり: 太陽があらゆる明かりの光源ではなくなった点

utcOffset

時間単位で指定します。 returnFormat が SUNFUNCS_RET_TIMESTAMP の場合は、 utcOffset は無視されます。

戻り値

日の入り時刻を、指定した returnFormat で返します。 失敗した場合に false を返します。 失敗する潜在的な可能性があります。太陽が全く昇らない場合です。 これは一年のある時期、極圏の中にある場合に起こります。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 date_sun_info() を使って下さい。
8.0.0 | latitude, longitude, zenith, utcOffset は、nullable になりました。

例

例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

例2 No sunset

<?php
$solstice = strtotime('2017-12-21');
var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
?>

上の例の出力は以下となります。

bool(false)

参考

  • date_sun_info() - 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す


DateTime::setTime のエイリアス

  • ≪ date_sunset
  • date_timestamp_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setTime のエイリアス

date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — DateTime::setTime() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTime()


DateTime::getTimestamp のエイリアス

  • ≪ date_time_set
  • date_timestamp_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getTimestamp のエイリアス

date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — DateTime::getTimestamp() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getTimestamp()


DateTime::setTimestamp のエイリアス

  • ≪ date_timestamp_get
  • date_timezone_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setTimestamp のエイリアス

date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — DateTime::setTimestamp() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTimestamp()


DateTime::getTimezone のエイリアス

  • ≪ date_timestamp_set
  • date_timezone_set ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::getTimezone のエイリアス

date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — DateTime::getTimezone() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getTimezone()


DateTime::setTimezone のエイリアス

  • ≪ date_timezone_get
  • getdate ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTime::setTimezone のエイリアス

date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — DateTime::setTimezone() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTimezone()


日付/時刻情報を取得する

  • ≪ date_timezone_set
  • gettimeofday ≫
  • PHP Manual
  • 日付・時刻 関数
  • 日付/時刻情報を取得する

getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — 日付/時刻情報を取得する

説明

getdate(?int $timestamp = null): array

timestamp に関する日付情報を有する連想配列を返します。 timestamp が省略されたり、null だった場合、現在のローカルな時間に関する情報を返します。

パラメータ

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは 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.

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例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() - Unixタイムスタンプを書式化する
  • idate() - ローカルな時刻/日付の一部を整数として整形する
  • localtime() - ローカルタイムを得る
  • time() - 現在の Unix タイムスタンプを返す
  • setlocale() - ロケール情報を設定する


現在の時間を得る

  • ≪ getdate
  • gmdate ≫
  • PHP Manual
  • 日付・時刻 関数
  • 現在の時間を得る

gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — 現在の時間を得る

説明

gettimeofday(bool $as_float = false): array|float

この関数は、gettimeofday(2) へのインターフェイスです。 この関数は、システムコールから返されたデータを有する連想配列を返します。

パラメータ

as_float

true を指定すると、配列ではなく float で返します。

戻り値

デフォルトでは配列を返します。as_float が設定されている場合は float を返します。

配列のキー:

  • "sec" - UNIX エポックからの秒
  • "usec" - マイクロ秒
  • "minuteswest" - グリニッジ基準の分
  • "dsttime" - 夏時間補正の型

例

例1 gettimeofday() の例

<?php
print_r(gettimeofday());

echo gettimeofday(true);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [sec] => 1073504408
    [usec] => 238215
    [minuteswest] => 0
    [dsttime] => 1
)

1073504408.23910


GMT/UTC の日付/時刻を書式化する

  • ≪ gettimeofday
  • gmmktime ≫
  • PHP Manual
  • 日付・時刻 関数
  • GMT/UTC の日付/時刻を書式化する

gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — GMT/UTC の日付/時刻を書式化する

説明

gmdate(string $format, ?int $timestamp = null): string

date() 関数と同じですが、返される時刻が グリニッジ標準時 (GMT) であるところが異なります。

パラメータ

format

出力される文字列の書式。date() 関数の書式オプションを参照ください。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

戻り値

日付を表す文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例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));
?>

参考

  • DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す
  • DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
  • date() - Unixタイムスタンプを書式化する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • gmmktime() - GMT 日付から Unix タイムスタンプを取得する
  • IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする


GMT 日付から Unix タイムスタンプを取得する

  • ≪ gmdate
  • gmstrftime ≫
  • PHP Manual
  • 日付・時刻 関数
  • GMT 日付から Unix タイムスタンプを取得する

gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — GMT 日付から Unix タイムスタンプを取得する

説明

gmmktime(
int $hour,
?int $minute = null,
?int $second = null,
?int $month = null,
?int $day = null,
?int $year = null
): int|false

指定されるパラメータが GMT 日付を表すこと以外は mktime() と同じです。 gmmktime() は内部で mktime() を使用しているので、ローカル時刻として有効な値のみが使用可能です。

mktime() と同様に、 オプションの引数は右から順に省略することができます。 省略された引数は、GMT の日付と時刻に従って、現在の値にセットされます。

引数なしで gmmktime() を呼び出すことはサポートされていません。 引数なしで呼び出すと、ArgumentCountError がスローされます。 現在のタイムスタンプを取得する目的には、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

年

戻り値

成功時に、Unix タイムスタンプを int で返します。 タイムスタンプの値が PHP の整数型に合わない場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | hour はオプションではなくなりました。 Unixタイムスタンプ が必要な場合、time() 関数を使います。
8.0.0 | minute, second, month, day, year は、nullable になりました。

例

例1 gmmktime() の基本的な例

<?php
// 出力: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));
?>

参考

  • DateTimeImmutable
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • date() - Unixタイムスタンプを書式化する
  • time() - 現在の Unix タイムスタンプを返す


ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

  • ≪ gmmktime
  • idate ≫
  • PHP Manual
  • 日付・時刻 関数
  • ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

警告

この関数は PHP 8.1.0 で 非推奨 になります。この関数に頼らないことを強く推奨します。

この関数の代替として、これらが使えます:

  • gmdate()
  • IntlDateFormatter::format()

説明

gmstrftime(string $format, ?int $timestamp = null): string|false

グリニッジ標準時を返すこと以外は、 strftime() と同じ動作をします。例えば、東部標準時 (GMT -0500) で実行した場合、以下の最初の行は "Dec 31 1998 20:00:00" を出力し、二行目は "Jan 01 1999 01:00:00" を出力します。

警告

この関数は、オペレーティングシステムのロケールの情報に依存しており、 情報が一貫していなかったり、全く利用できない可能性があります。 代わりに、IntlDateFormatter::format() を使いましょう。

パラメータ

format

strftime() の説明を参照ください。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

戻り値

指定した timestamp または timestamp が指定されていない場合に現在のローカル時間を用いて、 指定したフォーマット文字列に基づき文字列をフォーマットして返します。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。 失敗時には、false を返します。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例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";
?>

参考

  • IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする
  • DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする


ローカルな時刻/日付の一部を整数として整形する

  • ≪ gmstrftime
  • localtime ≫
  • PHP Manual
  • 日付・時刻 関数
  • ローカルな時刻/日付の一部を整数として整形する

idate

(PHP 5, PHP 7, PHP 8)

idate — ローカルな時刻/日付の一部を整数として整形する

説明

idate(string $format, ?int $timestamp = null): int|false

指定された引数 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 を返す
N | ISO-8601 形式の曜日 (1 は月曜日で、 7 が日曜日)
o | ISO-8601 形式の年 (4 桁の数値)
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 は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

戻り値

整数値を返します。 失敗した場合に false を返します

idate() が返す値の型は常に int であり、 先頭に "0" がくることはありません。そのため、idate() の返す結果が予想より少ない桁数になることもあります。以下の例を参照ください。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.2.0 | フォーマット文字 N (ISO-8601 形式の曜日) と o (ISO-8601 形式の年) が追加されました。
8.0.0 | timestamp は、nullable になりました。

例

例1 idate() の例

<?php
$timestamp = strtotime('1st January 2004'); //1072915200

// これは、年を 2 桁で表示します。
// しかし、ここでは年が "0" から始まるので、
// "4" だけが表示されます。
echo idate('y', $timestamp);
?>

参考

  • DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
  • date() - Unixタイムスタンプを書式化する
  • getdate() - 日付/時刻情報を取得する
  • time() - 現在の Unix タイムスタンプを返す


ローカルタイムを得る

  • ≪ idate
  • microtime ≫
  • PHP Manual
  • 日付・時刻 関数
  • ローカルタイムを得る

localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — ローカルタイムを得る

説明

localtime(?int $timestamp = null, bool $associative = false): array

localtime() 関数は、C 言語の 同名の関数コールにより返される構造体と同じ内容の配列を返します。

パラメータ

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

associative

この関数が数値のインデックスによる通常の配列を返すか、 連想配列を返すかを指定します。

戻り値

associative が false に設定されるか省略された場合は、 数値のインデックスにょる通常の配列を返します。 associative が 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_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

例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() - 日付/時刻情報を取得する


現在の Unix タイムスタンプをマイクロ秒まで返す

  • ≪ localtime
  • mktime ≫
  • PHP Manual
  • 日付・時刻 関数
  • 現在の Unix タイムスタンプをマイクロ秒まで返す

microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — 現在の Unix タイムスタンプをマイクロ秒まで返す

説明

microtime(bool $as_float = false): string|float

microtime() は、現在の Unix タイムスタンプをマイクロ秒単位で返します。 この関数は、gettimeofday() システムコールをサポートする オペレーティングシステムでのみ使用できます。

パフォーマンスの計測には、hrtime() を使うことをお勧めします。

パラメータ

as_float

true を指定すると、microtime() は文字列ではなく float を返すようになります。詳細は、戻り値の説明を参照ください。

戻り値

デフォルトでは、microtime() は "msec sec" 形式の文字列を返します。ただし、sec は Unix エポック (1970 年 1 月 1 日 0:00:00 GMT) からの経過秒数、msec は sec から経過したマイクロ秒数を秒単位、つまり小数で表したものです。

as_float を true に設定すると、microtime() は Unixエポック からの経過秒数を マイクロ秒で正確になるように float で表したものを返します。

例

例1 タイマスクリプト実行

<?php
$time_start = microtime(true);

// しばらくスリープ
usleep(100);

$time_end = microtime(true);
$time = $time_end - $time_start;

echo "Did nothing in $time seconds\n";
?>

例2 microtime() と REQUEST_TIME_FLOAT の例

<?php
// ランダムな時間のスリープ
usleep(mt_rand(100, 10000));

// REQUEST_TIME_FLOAT をスーパーグローバル $_SERVER から取得できます。
// ここにはリクエスト開始時のタイムスタンプがマイクロ秒の精度で記録されています。
$time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

echo "Did nothing in $time seconds\n";
?>

参考

  • time() - 現在の Unix タイムスタンプを返す
  • hrtime() - システムの高精度な時刻を取得する


日付を Unix のタイムスタンプとして取得する

  • ≪ microtime
  • strftime ≫
  • PHP Manual
  • 日付・時刻 関数
  • 日付を Unix のタイムスタンプとして取得する

mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — 日付を Unix のタイムスタンプとして取得する

説明

mktime(
int $hour,
?int $minute = null,
?int $second = null,
?int $month = null,
?int $day = null,
?int $year = null
): int|false

与えられた引数に従って UNIX のタイムスタンプを返します。 このタイムスタンプは、Unix epoch(1970年1月1日00:00:00 GMT)から 指定された時刻までの通算秒を表す長整数です。

省略されたり、null が指定されたオプションの引数は、 ローカルの日付と時刻に従って、現在の値にセットされます。

警告

引数の順番が変なので注意して下さい: month, day, year の順になっており、 理にかなった year, month, day の順になっていません。

引数なしで mktime() を呼び出すことはサポートされていません。 引数なしで呼び出すと、ArgumentCountError がスローされます。 現在のタイムスタンプを取得する目的には、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 の間です。

戻り値

mktime() は与えられた引数の Unix タイムスタンプを返します。 タイムスタンプの値が PHP の整数型に合わない場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | hour は、オプションではなくなりました。 Unixタイムスタンプ が必要な場合、time() を使います。
8.0.0 | minute, second, month, day, year は、nullable になりました。

例

例1 mktime() の基本的な例

<?php
// デフォルトのタイムゾーンを設定します。
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 'Last day in Feb 2000 is: ', date('d', $lastday);

$lastday = mktime(0, 0, 0, 4, -31, 2000);
echo 'Last day in Feb 2000 is: ', date('d', $lastday);

?>

参考

  • DateTimeImmutable
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • gmmktime() - GMT 日付から Unix タイムスタンプを取得する
  • date() - Unixタイムスタンプを書式化する
  • time() - 現在の Unix タイムスタンプを返す


ロケールの設定に基づいてローカルな日付・時間をフォーマットする

  • ≪ mktime
  • strptime ≫
  • PHP Manual
  • 日付・時刻 関数
  • ロケールの設定に基づいてローカルな日付・時間をフォーマットする

strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — ロケールの設定に基づいてローカルな日付・時間をフォーマットする

警告

この関数は PHP 8.1.0 で 非推奨 になります。この関数に頼らないことを強く推奨します。

この関数の代替として、これらが使えます:

  • date()
  • IntlDateFormatter::format()

説明

strftime(string $format, ?int $timestamp = null): string|false

ローカルの時刻・日付を、ロケール設定にもとづいてフォーマットします。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。

警告

使用する C ライブラリで、すべての変換指定子がサポートされているとは限りません。 そのような場合、該当する変換指定子は PHP の strftime() ではサポートされません。 また、全てのプラットフォームが負のタイムスタンプをサポートしているわけではないため、 Unix Epoch (1970 年 1 月 1 日）以前の日付を扱えないかもしれません。 つまり、Windows や一部の Linux ディストリビューション、そしてその他のごく一部の オペレーティングシステム上では %e、%T、%R および %D (あるいはこれ以外も) が Jan 1, 1970 より前の日付について動作しないということです。 Windwos システム上でサポートされる変換指定子の概要については、 » MSDN に掲載されています。 Instead use the IntlDateFormatter::format() method.

パラメータ

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
%k | 24 時間制の時間で、1 桁の場合は先頭にスペースをつけたもの | 0 から 23
%I | 2 桁であらわした 12 時間制の時間 | 01 から 12
%l (小文字の 'L') | 12 時間制の時間で、1 桁の場合は先頭にスペースをつけたもの | 1 から 12
%M | 2 桁であらわした分 | 00 から 59
%p | 指定した時刻に応じた大文字の 'AM' あるいは 'PM' | 00:31 なら AM、22:23 なら PM。 正確な結果はオペレーティングシステムに依存します。 (a.m. のような) 小文字やドット付きの結果を返すこともあります。
%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 | ロケールに基づいた時刻の表現。日付は含まない | 03:59:16 あるいは 15:59:16
%z | タイムゾーンオフセット。Windows では違う実装になっています。詳細は後述します。 | 東海岸時刻なら -0500
%Z | タイムゾーンの略称。Windows では違う実装になっています。詳細は後述します。 | 東海岸時刻なら 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") ---
%% パーセント文字 ("%") ---

警告

ISO-9889:1999 に反して、Sun Solaris は日曜日を 1 としています。 そのため、%u はこのマニュアルの説明どおりに機能しないかもしれません。

警告

Windows 限定:

Windows 上では %e に対応していません。 この値が欲しければ、代わりに %#d を使いましょう。 クロスプラットフォーム対応の関数を書く方法をこの後の例で示します。

%z と %Z は、どちらもタイムゾーン名を返します。オフセットや略称は返しません。

警告

macOS と musl 限定: %P 修飾子は macOS 版の実装ではサポートされていません。

timestamp

オプションのパラメータ timestamp は、 int 型の Unix タイムスタンプです。 timestamp が指定されなかったり、null だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

戻り値

指定した timestamp または timestamp が指定されていない場合に現在のローカル時間を用いて、 指定したフォーマット文字列に基づき文字列をフォーマットして返します。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。 この関数は、format が空だったり、 サポートされていない変換指定子が含まれていたり、 返される文字列の長さが 4095 より大きい場合は、false を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

出力内容は元となった C ライブラリに依存するため、サポートしていない変換指定子もあります。 Windows では、対応していない変換指定子を渡すと 5 つの E_WARNING メッセージが出て false を返します。 その他のオペレーティングシステムでは特に E_WARNING メッセージは出ず、 変換指定子が (変換されずに) そのまま出力されます。

変更履歴

バージョン | 説明
8.0.0 | timestamp は、nullable になりました。

例

この例は、それぞれのロケールがシステムにインストールされている場合にのみ動作します。

例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' => 'Hour in 24-hour format, with a space preceding single digits',
'l' => 'Hour in 12-hour format, with a space preceding 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'                       ( Hour in 24-hour format, with a space preceding single digits )
Unknown format : 'l'                       ( Hour in 12-hour format, with a space preceding 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 の例を参照ください。

参考

  • IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする
  • DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
  • » オンラインの strftime() 書式デザインツール
  • setlocale() - ロケール情報を設定する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • strptime() - strftime が生成した日付/時刻をパースする
  • gmstrftime() - ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする
  • » Open Group による strftime() の定義


strftime が生成した日付/時刻をパースする

  • ≪ strftime
  • strtotime ≫
  • PHP Manual
  • 日付・時刻 関数
  • strftime が生成した日付/時刻をパースする

strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — strftime() が生成した日付/時刻をパースする

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

strptime(string $timestamp, string $format): array|false

strptime() は timestamp をパースした結果を配列で返します。エラー時には false を返します。

月名や曜日、そしてその他の言語依存な文字列は setlocale() (LC_TIME) で設定された現在の ロケールを考慮して返します。

パラメータ

timestamp (string)

パースする文字列（例: strftime() の戻り値）。

format (string)

timestamp で使用されているフォーマット （例: 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" | timestamp の中で、指定された format で判断できなかった部分

変更履歴

バージョン | 説明
8.1.0 | この関数は、推奨されなくなりました。 date_parse_from_format() (ロケールに依存しないパースを行う場合) または、 IntlDateFormatter::parse() (ロケールに依存するパースを行う場合) を使って下さい。

例

例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() はこの問題の影響を受けないので、 date_parse_from_format() を使うことを推奨します。

注意:

"tm_sec" には、うるう秒も組み込まれています (現在は、年間 2 秒まで)。うるう秒についての詳細な情報は » Wikipedia の記事 を参照ください。

注意:

PHP 5.2.0 より前のバージョンでは、この関数が未定義の挙動をすることがありました。 特に "tm_sec"、"tm_min" および "tm_hour" が未定義の値になることがありました。

参考

  • IntlDateFormatter::parse() - 文字列をパースしてタイムスタンプにする
  • DateTime::createFromFormat() - 指定した書式で時刻文字列をパースする
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
  • date_parse_from_format() - 指定した書式でフォーマットされた日付についての情報を取得する


英文形式の日付を Unix タイムスタンプに変換する

  • ≪ strptime
  • time ≫
  • PHP Manual
  • 日付・時刻 関数
  • 英文形式の日付を Unix タイムスタンプに変換する

strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — 英文形式の日付を Unix タイムスタンプに変換する

説明

strtotime(string $datetime, ?int $baseTimestamp = null): int|false

この関数は英語の書式での日付を含む文字列が指定されることを期待しており、 その書式を Unix タイムスタンプ (1970 年 1 月 1 日 00:00:00 UTC からの経過秒数) に変換しようとします。 baseTimestamp が指定された場合は、そのタイムスタンプを基準とした相対時刻のタイムスタンプに変換します。 baseTimestamp が指定されていない場合は、現在時刻を基準とした相対時刻のタイムスタンプに変換します。 パースされる日付を含む文字列の書式は、 サポートする日付と時刻の書式 で定義されており、考慮すべき微妙な点がいくつかあります。 サポートする日付と時刻の書式について、読んでおくことを強く推奨します。

警告

この関数が返す Unixタイムスタンプ は、タイムゾーンの情報を含んでいません。 日付/時刻の情報を含めて計算するには、 より多くの機能がある DateTimeImmutable を使うべきです。

この関数の各パラメータでは、パラメータ内でタイムゾーンを指定しない限りはデフォルトのタイムゾーンを使います。 意図的にそうする場合は別として、パラメータごとにタイムゾーンを変えてしまったりしないように気をつけましょう。 デフォルトのタイムゾーンを定義する方法については date_default_timezone_get() を参照ください。

パラメータ

datetime

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

baseTimestamp

返される値を計算するために使用されるタイムスタンプ。

戻り値

成功時はタイムスタンプ、そうでなければ false を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン | 説明
8.0.0 | baseTimestamp は、nullable になりました。

例

例1 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';

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);
}
?>

注意

注意:

"相対的な" 日付とは、 日付/時刻の一部の情報が与えられていないということでもあります。 与えられていない情報は baseTimestamp から取得されます。 つまり、2022年5月31日 (31st of May 2022) に strtotime('February') を実行すると、 31 February 2022 と解釈されて日付がオーバーフローし、 3 March になります(うるう年の場合、2 March になります)。 strtotime('1 February') や strtotime('first day of February') を使うことで、この問題は回避できます。

注意:

年を 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 ビット符号付整数の最大及び最小に一致します)。

64 ビット版の PHP では、タイムスタンプの有効範囲は事実上無制限です。 というのも、64 ビットでは過去側も未来側も約 2930 億年を表せるからです。

注意:

この関数を使って日付の足し算や引き算を行うことはおすすめできません。 DateTime::add() や DateTime::sub() を使いましょう。

参考

  • DateTimeImmutable
  • DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする
  • 日付と時刻の書式
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strptime() - strftime が生成した日付/時刻をパースする


現在の Unix タイムスタンプを返す

  • ≪ strtotime
  • timezone_abbreviations_list ≫
  • PHP Manual
  • 日付・時刻 関数
  • 現在の Unix タイムスタンプを返す

time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — 現在の Unix タイムスタンプを返す

説明

time(): int

現在時刻を Unix エポック (1970 年 1 月 1 日 00:00:00 GMT) からの通算秒として返します。

注意:

Unixタイムスタンプは、ローカルタイムゾーンに関する情報を含んでいません。 Unixタイムスタンプに付随する落とし穴を避けつつ、 日付/時刻に関する情報を扱うために DateTimeImmutable を使うことを推奨します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のタイムスタンプを返します。

例

例1 time() の例

<?php
echo 'Now: '. time();
?>

上の例の出力は、 たとえば以下のようになります。

Now: 1660338149

注意

ヒント

$_SERVER['REQUEST_TIME'] によって、リクエスト開始時のタイムスタンプが取得できます。

参考

  • DateTimeImmutable
  • date() - Unixタイムスタンプを書式化する
  • microtime() - 現在の Unix タイムスタンプをマイクロ秒まで返す


DateTimeZone::listAbbreviations のエイリアス

  • ≪ time
  • timezone_identifiers_list ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::listAbbreviations のエイリアス

timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — DateTimeZone::listAbbreviations() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::listAbbreviations()


DateTimeZone::listIdentifiers のエイリアス

  • ≪ timezone_abbreviations_list
  • timezone_location_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::listIdentifiers のエイリアス

timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — DateTimeZone::listIdentifiers() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::listIdentifiers()


DateTimeZone::getLocation のエイリアス

  • ≪ timezone_identifiers_list
  • timezone_name_from_abbr ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getLocation のエイリアス

timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — DateTimeZone::getLocation() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getLocation()


略称とUTCオフセットから、タイムゾーン名を推測して返す

  • ≪ timezone_location_get
  • timezone_name_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • 略称とUTCオフセットから、タイムゾーン名を推測して返す

timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — 略称とUTCオフセットから、タイムゾーン名を推測して返す

説明

timezone_name_from_abbr(string $abbr, int $utcOffset = -1, int $isDST = -1): string|false

パラメータ

abbr

タイムゾーンの略称。

utcOffset

GMT からのオフセット秒数。デフォルトは -1 で、 この場合は abbr に対応するタイムゾーンのうち最初に見つかったものを返します。 それ以外の場合は指定したオフセットを探し、 そこで見つからなかった場合には 他のオフセットも含めて最初に見つかったものを返します。

isDST

夏時間のインジケータ。デフォルトは -1 で、 タイムゾーンが夏時間を持っているかどうかは考慮せずに検索します。 この値を 1 にすると、utcOffset は夏時間を考慮したオフセットと見なします。 0 の場合は、utcOffset は夏時間を考慮しないオフセットと見なします。 abbr が存在しない場合、 タイムゾーンの検索は utcOffset と 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_abbreviations_list() - DateTimeZone::listAbbreviations のエイリアス


DateTimeZone::getName のエイリアス

  • ≪ timezone_name_from_abbr
  • timezone_offset_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getName のエイリアス

timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — DateTimeZone::getName() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getName()


DateTimeZone::getOffset のエイリアス

  • ≪ timezone_name_get
  • timezone_open ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getOffset のエイリアス

timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — DateTimeZone::getOffset() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getOffset()


DateTimeZone::__construct のエイリアス

  • ≪ timezone_offset_get
  • timezone_transitions_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::__construct のエイリアス

timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — DateTimeZone::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::__construct()


DateTimeZone::getTransitions のエイリアス

  • ≪ timezone_open
  • timezone_version_get ≫
  • PHP Manual
  • 日付・時刻 関数
  • DateTimeZone::getTransitions のエイリアス

timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — DateTimeZone::getTransitions() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getTransitions()


timezonedb のバージョンを取得する

  • ≪ timezone_transitions_get
  • 日付・時刻 に関するエラーと例外 ≫
  • PHP Manual
  • 日付・時刻 関数
  • timezonedb のバージョンを取得する

timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — timezonedb のバージョンを取得する

説明

timezone_version_get(): string

timezonedb の現在のバージョンを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

2022.2 のような、 YYYY.increment のフォーマットを文字列で返します。

古いバージョンのタイムゾーンデータベースを持っている場合 (たとえば、今年のバージョンが表示されない場合)、 タイムゾーンの情報は PHP のバージョンを上げるか、 PECL パッケージの » timezonedb をインストールすることで更新することができます。

Linux ディストリビューションによっては、 他のタイムゾーンの情報ソースを使うように PHP の date/time サポートにパッチをあてているものがあります。その場合、この関数は 0.system という値を返します。 この場合も、PECL パッケージの » timezonedb をインストールすることをお勧めします。

例

例1 timezonedb のバージョンの取得

<?php
echo timezone_version_get();
?>

上の例の出力は、 たとえば以下のようになります。

2022.2

参考

  • サポートするタイムゾーンの一覧


日付・時刻 に関するエラーと例外

  • DateError (extends Error)
    • DateObjectError DateRangeError
  • DateException (extends Exception)
      • DateInvalidOperationException
      • DateInvalidTimezoneException
      • DateMalformedIntervalStringException
      • DateMalformedPeriodStringException
      • DateMalformedStringException


サポートする日付と時刻の書式

この節では DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse() および strtotime() が解釈可能な、全てのBNFライクな書式について説明します。 これらの書式はセクションごとにグループ分けされています。 たいていの場合、一つの日付・時刻文字列の中でホワイトスペース、 コンマまたはドットで区切られた異なるセクションの書式を併用することができます。 それぞれの書式について、説明と一緒に1個以上の例を示してあります。 シングルクォートで囲まれたフォーマットは大文字小文字を区別しません。 ('t' は t とも T とも書けます)。 ダブルクォートで囲まれたフォーマットは大文字小文字を区別します。 ("T" は T としか書けません)。

DateTimeImmutable と DateTime オブジェクトをフォーマットするには、 DateTimeInterface::format() のドキュメントを参照ください。

以下の一般的なルールを考慮すべきです。

  1. 日付/時刻のパーサーは、 個別の単位(年月日時分秒)ごとに許される値の範囲を持っています。 年については4桁の数値、 月については 0-12。 日は 0-31、 時 は 0-24。分は 0-59 の範囲を持ちます。
  2. 秒に60を入れても構いません。 なぜなら、うるう秒を含んだ日付の文字列が現れる場合があるからです。 しかし、PHP は "60" を不正な秒として扱う UnixTime を実装しているため、 60 を入れるとオーバーフローします。
  3. strtotime() は、 いずれかの数値が範囲外の場合に false を返します。 DateTimeImmutable::__construct() はその場合に例外をスローします。
  4. 文字列が日付の場合、時刻に関する全ての要素は 0 にリセットされます。
  5. 時刻の一部が指定された文字列に含まれている場合、 重要でない時刻の要素は全て0にリセットされます。
  6. 日付/時刻のパーサーはお馬鹿なので、 高速にするためのチェックは行いません (そのため、より汎用的です)。
  7. 個別の時刻フォーマット以外にも、 日付/時刻のパーサーは 複合的な書式 を理解します。たとえば Unixタイムスタンプ (@1690388256) や、ISO の週番号 (2008-W28-3) などです。

  8. 不正な日付を渡していないかどうかについて、追加のチェックが行われます:

    <?php
    $res     = date_parse("2015-09-31");
    var_dump($res["warnings"]);
    ?>

    上の例の出力は以下となります。

    array(1) {
  [11] =>
  string(27) "The parsed date was invalid"
}

  9. エッジケースも処理できます。 ただ、処理するためには、 DateTimeImmutable::createFromFormat() を使い、正しいフォーマットを指定する必要があります。

    <?php
    $res     = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
    var_dump($res);

    上の例の出力は以下となります。

    object(DateTimeImmutable)#1 (3) {
  ["date"]=>
  string(26) "2015-10-04 17:24:43.000000"
  ["timezone_type"]=>
  int(3)
  ["timezone"]=>
  string(13) "Europe/London"
}

時刻の書式

このページでは、 DateTimeImmutable, DateTime, date_create(), date_create_immutable(), そして strtotime() のパーサーが理解する、 BNFライクな時刻フォーマットを説明します。

DateTimeImmutable と DateTime オブジェクトをフォーマットするには、 DateTimeInterface::format() のドキュメントを参照ください。

シンボル一覧
シンボル | 書式 | 例
frac | . [0-9]+ | ".21342", ".85"
hh | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
HH | [01][0-9] | "2"[0-4] | "04", "07", "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 (時、分、秒、端数、午前/午後) | 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"

日付の書式

このページでは、 DateTimeImmutable, DateTime, date_create(), date_create_immutable() および strtotime() のパーサーが理解する、 BNFライクな日付フォーマットを説明します。

DateTimeImmutable と DateTime オブジェクトをフォーマットするには、 DateTimeInterface::format() のドキュメントを参照ください。

シンボル一覧
シンボル | 書式 | 例
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"
YYY | [0-9]{5,19} | "81412", "20192"
各国ごとの表記法
説明 | 書式 | 例
アメリカ式の月、日 | 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.1978"
ドットかタブで区切られた、日、月、2桁の年 | dd [.\t] mm "." yy | "30.6.08", "22\t12.78"
日、月の文字表記、年 | 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"
日、月の文字表記 | dd ([ .\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"
年 (拡張表記、5-19 桁。符号付き) | [+-] YYY | "-81120", "+20192"
月の文字表記 (月だけの指定) | 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"
符号が必須。5桁の年、月、日 | [+-] YYY "-" MM "-" DD | "-81120-02-26", "+20192-04-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 日までしかないので)。

「日」の範囲が 0 から 31 までに絞られていることに注意しましょう。 先ほどの正規表現が示すとおりです。 したがって、たとえば "2008-06-32" は日付文字列として妥当な形式ではなくなります。

また、シンボル 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 年になります。)

複合的な書式

このページでは、 DateTimeImmutable, DateTime, date_create(), date_create_immutable() および strtotime() のパーサーが理解する、 BNFライクな日付/時刻 複合フォーマットを説明します。

DateTimeImmutable と DateTime オブジェクトをフォーマットするには、 DateTimeInterface::format() のドキュメントを参照ください。

シンボル一覧
シンボル | 書式 | 例
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] | "001", "012", "180", "350", "366"
frac | . [0-9]+ | ".21342", ".85"
hh | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
HH | [01][0-9] | "2"[0-4] | "04", "07", "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-1][0-9] | "00", "12"
space | [ \t] |
ss | ([0-5]?[0-9])|60 | "04", "8", "59", "60" (うるう秒)
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 ":"? II? | "+0400", "GMT-07:00", "-07:00"
YY | [0-9]{4} | "2000", "2008", "1978"
標準のフォーマット
説明 | 例
ATOM | "2022-06-02T16:58:35+00:00"
COOKIE | "Thursday, 02-Jun-2022 16:58:35 UTC"
ISO8601 | "2022-06-02T16:58:35+0000"
» RFC 822 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 850 | "Thursday, 02-Jun-22 16:58:35 UTC"
» RFC 1036 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 1123 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 2822 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 3339 | "2022-06-02T16:58:35+00:00"
» RFC 3339 Extended | "2022-06-02T16:58:35.698+00:00"
» RFC 7231 | "Thu, 02 Jun 2022 16:58:35 GMT"
RSS | "Thu, 02 Jun 2022 16:58:35 +0000"
W3C | "2022-06-02T16:58:35+00:00"
ローカライズされた表記法
説明 | 書式 | 例
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"
マイクロ秒付きのUnix タイムスタンプ | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
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 」、「 XMLRPC 」および「 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 週に属します。

相対的な書式

このページでは、 DateTimeImmutable, DateTime, date_create(), date_create_immutable(), そして strtotime() のパーサーが理解する、 BNFライクな相対日付/時刻フォーマットを説明します。

DateTimeImmutable と DateTime オブジェクトをフォーマットするには、 DateTimeInterface::format() のドキュメントを参照ください。

シンボル一覧
シンボル | 書式
dayname | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
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 | 'ms' | 'μs' | (( 'msec' | 'millisecond' | 'μsec' | 'microsecond' | 'usec' | '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 | reltext) space unit | 値を英単語で指定するような、相対的な時間指定を処理します。 last と previous は、-1 に等しく、this に等しいものはありません。そして next は +1 に等しいです。 | "fifth day", "second month", "last day", "previous year"
'ago' | 直前に指定された相対的な時間指定について、正負反転します。 | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days 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つの記述が現在時刻に直接影響するためです。

"first day of" のようなキーワードは、 相対的な書式文字列が使われるコンテクストに依存します。 static メソッドや関数で使われた場合、 参照されるのは現在のタイムスタンプですが、 DateTime::modify() や DateTimeImmutable::modify() で使われた場合、参照されるのは modify() メソッドがコールされたオブジェクトです。

注意:

日付/時刻文字列中の曜日指定が現在の曜日と同じ場合は、 以下の点に注意してください。 この場合、日付文字列中の曜日は、曜日を明示的に指定しなかった場合に 日付文字列の相対的でない部分から計算される曜日と同一ではありますが、 指定しなくても同じというわけではありません。

  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 日後となるわけです。

注意:

number は 整数値 です。 つまり、小数値が与えられると、ドット(またはコンマ) はデリミタとして解釈されがちです。 たとえば、'+1.5 hours' は '+1 hour +30 minutes' ではなく '+1 5 hours' のようにパースされます。

変更履歴

バージョン | 説明
8.2.0 | number シンボルは、複数の符号を受け入れなくなりました。 たとえば、+-2 のようなフォーマットです。
7.0.8 | 週の始まりが常に月曜日となりました。 これより前のバージョンでは、日曜日も週の始まりとみなされていました。


サポートされるタイムゾーンのリスト

目次

  • アフリカ
  • アメリカ
  • 南極
  • 北極
  • アジア
  • 大西洋
  • オーストラリア
  • ヨーロッパ
  • インド
  • 太平洋
  • その他

これは、PHP がサポートしているタイムゾーンの完全なリストです。例えば date_default_timezone_set() などで使用します。

警告

ここに挙げられていないタイムゾーンの挙動は未定義です。

注意: 最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。

注意: このリストの元になっているのは、タイムゾーンデータベース バージョン 2024.1.


アフリカ

アフリカ
Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers
Africa/Asmara | 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/Tripoli | Africa/Tunis | Africa/Windhoek


アメリカ

アメリカ
America/Adak | America/Anchorage | America/Anguilla | America/Antigua
America/Araguaina | America/Argentina/Buenos_Aires | America/Argentina/Catamarca | 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/Bahia | America/Bahia_Banderas | America/Barbados | America/Belem
America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota
America/Boise | America/Cambridge_Bay | America/Campo_Grande | America/Cancun
America/Caracas | America/Cayenne | America/Cayman | America/Chicago
America/Chihuahua | America/Ciudad_Juarez | 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/Fort_Nelson
America/Fortaleza | America/Glace_Bay | 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/Inuvik | America/Iqaluit | America/Jamaica | America/Juneau
America/Kentucky/Louisville | America/Kentucky/Monticello | America/Kralendijk | America/La_Paz
America/Lima | America/Los_Angeles | America/Lower_Princes | America/Maceio
America/Managua | America/Manaus | America/Marigot | America/Martinique
America/Matamoros | America/Mazatlan | America/Menominee | America/Merida
America/Metlakatla | America/Mexico_City | America/Miquelon | America/Moncton
America/Monterrey | America/Montevideo | America/Montserrat | America/Nassau
America/New_York | America/Nome | America/Noronha | America/North_Dakota/Beulah
America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk | America/Ojinaga
America/Panama | America/Paramaribo | America/Phoenix | America/Port-au-Prince
America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico | America/Punta_Arenas
America/Rankin_Inlet | America/Recife | America/Regina | America/Resolute
America/Rio_Branco | America/Santarem | America/Santiago | America/Santo_Domingo
America/Sao_Paulo | America/Scoresbysund | 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/Tijuana | America/Toronto | America/Tortola | America/Vancouver
America/Whitehorse | America/Winnipeg | America/Yakutat |


南極

南極
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |


  • ≪ 南極
  • アジア ≫
  • PHP Manual
  • サポートされるタイムゾーンのリスト
  • 北極

北極

北極
Arctic/Longyearbyen


アジア

アジア
Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr
Asia/Aqtau | Asia/Aqtobe | Asia/Ashgabat | Asia/Atyrau
Asia/Baghdad | Asia/Bahrain | Asia/Baku | Asia/Bangkok
Asia/Barnaul | Asia/Beirut | Asia/Bishkek | Asia/Brunei
Asia/Chita | Asia/Choibalsan | Asia/Colombo | Asia/Damascus
Asia/Dhaka | Asia/Dili | Asia/Dubai | Asia/Dushanbe
Asia/Famagusta | Asia/Gaza | Asia/Hebron | Asia/Ho_Chi_Minh
Asia/Hong_Kong | Asia/Hovd | Asia/Irkutsk | Asia/Jakarta
Asia/Jayapura | Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka
Asia/Karachi | Asia/Kathmandu | Asia/Khandyga | Asia/Kolkata
Asia/Krasnoyarsk | Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait
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/Qostanay | Asia/Qyzylorda
Asia/Riyadh | Asia/Sakhalin | Asia/Samarkand | Asia/Seoul
Asia/Shanghai | Asia/Singapore | Asia/Srednekolymsk | Asia/Taipei
Asia/Tashkent | Asia/Tbilisi | Asia/Tehran | Asia/Thimphu
Asia/Tokyo | Asia/Tomsk | Asia/Ulaanbaatar | Asia/Urumqi
Asia/Ust-Nera | Asia/Vientiane | Asia/Vladivostok | Asia/Yakutsk
Asia/Yangon | Asia/Yekaterinburg | Asia/Yerevan |


大西洋

大西洋
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |


オーストラリア

オーストラリア
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |


ヨーロッパ

ヨーロッパ
Europe/Amsterdam | Europe/Andorra | Europe/Astrakhan | Europe/Athens
Europe/Belgrade | Europe/Berlin | Europe/Bratislava | Europe/Brussels
Europe/Bucharest | Europe/Budapest | Europe/Busingen | Europe/Chisinau
Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey
Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey
Europe/Kaliningrad | Europe/Kirov | Europe/Kyiv | Europe/Lisbon
Europe/Ljubljana | Europe/London | Europe/Luxembourg | Europe/Madrid
Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco
Europe/Moscow | Europe/Oslo | Europe/Paris | Europe/Podgorica
Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara
Europe/San_Marino | Europe/Sarajevo | Europe/Saratov | Europe/Simferopol
Europe/Skopje | Europe/Sofia | Europe/Stockholm | Europe/Tallinn
Europe/Tirane | Europe/Ulyanovsk | Europe/Vaduz | Europe/Vatican
Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw
Europe/Zagreb | 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/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Fakaofo
Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos | Pacific/Gambier
Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Kanton
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/Port_Moresby | Pacific/Rarotonga
Pacific/Saipan | Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu
Pacific/Wake | Pacific/Wallis |  |


その他

警告

ここに挙げられているタイムゾーン (UTC 以外のもの) は使用しないでください。 これらは過去のバージョンとの互換性のためにのみ残されているものであり、おかしな挙動を引き起こすかもしれません。 さらに、ここに挙げられているタイムゾーンは、IANA のタイムゾーンデータベースからいつ削除されてもおかしくありません。

警告

上の警告を無視する場合は、PHP のタイムゾーンサポートで使っている IANA タイムゾーンデータベースが POSIX スタイルの符号を使っていることに気をつけましょう。つまり、 Etc/GMT+n や Etc/GMT-n といったタイムゾーンの符号が、一般的な使いかたとは逆転するのです。

たとえば、GMT より8時間進んでいるタイムゾーン (中国やオーストラリア西部など) は、このデータベースでは Etc/GMT-8 となります。ふつうは Etc/GMT+8 であろうと想定するでしょうが、そうではありません。

改めて言いますが、その場所にあわせた正確なタイムゾーンを使うことを推奨します。すなわち、先の例なら Asia/Shanghai や Australia/Perth を使うということです。

その他
Africa/Asmera | Africa/Timbuktu | America/Argentina/ComodRivadavia | America/Atka
America/Buenos_Aires | America/Catamarca | America/Coral_Harbour | America/Cordoba
America/Ensenada | America/Fort_Wayne | America/Godthab | America/Indianapolis
America/Jujuy | America/Knox_IN | America/Louisville | America/Mendoza
America/Montreal | America/Nipigon | America/Pangnirtung | America/Porto_Acre
America/Rainy_River | America/Rosario | America/Santa_Isabel | America/Shiprock
America/Thunder_Bay | America/Virgin | America/Yellowknife | Antarctica/South_Pole
Asia/Ashkhabad | Asia/Calcutta | Asia/Chongqing | Asia/Chungking
Asia/Dacca | Asia/Harbin | Asia/Istanbul | Asia/Kashgar
Asia/Katmandu | Asia/Macao | Asia/Rangoon | Asia/Saigon
Asia/Tel_Aviv | Asia/Thimbu | Asia/Ujung_Pandang | Asia/Ulan_Bator
Atlantic/Faeroe | Atlantic/Jan_Mayen | Australia/ACT | Australia/Canberra
Australia/Currie | Australia/LHI | Australia/North | Australia/NSW
Australia/Queensland | Australia/South | Australia/Tasmania | Australia/Victoria
Australia/West | Australia/Yancowinna | Brazil/Acre | Brazil/DeNoronha
Brazil/East | Brazil/West | Canada/Atlantic | Canada/Central
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 | Europe/Belfast
Europe/Kiev | Europe/Nicosia | Europe/Tiraspol | Europe/Uzhgorod
Europe/Zaporozhye | 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 | Pacific/Enderbury
Pacific/Johnston | Pacific/Ponape | Pacific/Samoa | Pacific/Truk
Pacific/Yap | 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/Samoa | UTC
W-SU | WET | Zulu |


DateError クラス

(PHP 8 >= 8.3.0)

はじめに

タイムゾーンデータベースが見つからなかったり、不正なデータが含まれている場合にスローされます。

このエラーは決して発生しないはずです。 発生する場合、ユーザーが書いたコード以外が原因です。 このエラーには2つの子クラス(DateObjectError と DateRangeError) があり、それらはプログラマーの間違いや期間に関する問題が原因でスローされます。

クラス概要

class DateError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}

参考

  • DateObjectError
  • DateRangeError


DateObjectError クラス

(PHP 8 >= 8.3.0)

はじめに

日付/時刻に関するクラスが、正しく初期化されていない場合にスローされます。

日付/時刻に関するクラスには final が指定されていないので、継承可能です。 親クラスのコンストラクタがコールされない場合、このエラーがスローされます。 これは常に、プログラミング時の誤りです。

クラス概要

class DateObjectError extends DateError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}

参考

  • DateError
  • DateRangeError


DateRangeError クラス

(PHP 8 >= 8.3.0)

はじめに

32ビットプラットフォーム上で、 日付オブジェクトが符号付き32ビットの範囲外の日付を表していた場合にスローされます。 このエラーをスローするのは、 DateTime::getTimestamp(), DateTimeImmutable::getTimestamp(), date_timestamp_get() です。

クラス概要

class DateRangeError extends DateError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}

参考

  • DateError
  • DateObjectError


DateException クラス

(PHP 8 >= 8.3.0)

はじめに

日付/時刻に関する例外の親クラスです。 ユーザーの入力や、パースが必要な自由入力のテキスト引数によって生じる問題に対応するものです。

以下の子クラスの例外がスローされます:

  • DateInvalidOperationException
  • DateInvalidTimezoneException
  • DateMalformedIntervalStringException
  • DateMalformedPeriodStringException
  • DateMalformedStringException

クラス概要

class DateException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


DateInvalidOperationException クラス

(PHP 8 >= 8.3.0)

はじめに

サポートされていない操作が行われた場合に、 DateTimeImmutable::sub() と DateTime::sub() がスローします。

サポートされていない操作の例として、 next weekday のような相対時間を表現する DateInterval を使った場合が挙げられます。 サポートされない理由は、論理的に逆の式が構築できないからです。

クラス概要

class DateInvalidOperationException extends DateException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


DateInvalidTimeZoneException クラス

(PHP 8 >= 8.3.0)

はじめに

DateTimeZone::__construct() に無効な値が渡された場合にスローされます。

クラス概要

class DateInvalidTimeZoneException extends DateException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


DateMalformedIntervalStringException クラス

(PHP 8 >= 8.3.0)

はじめに

DateInterval::__construct() に無効な duration が渡された場合にスローされます。

クラス概要

class DateMalformedIntervalStringException extends DateException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


DateMalformedPeriodStringException クラス

(PHP 8 >= 8.3.0)

はじめに

DatePeriod::__construct() に無効な isostr が渡された場合にスローされます。

クラス概要

class DateMalformedPeriodStringException extends DateException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


DateMalformedStringException クラス

(PHP 8 >= 8.3.0)

はじめに

無効な日付/時刻の文字列が検知された場合にスローされます。

これをスローする可能性があるのは
DateTimeImmutable::__construct(),
DateTimeImmutable::modify(),
DateTime::__construct(),
DateTime::modify() です。

クラス概要

class DateMalformedStringException extends DateException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


High resolution timing

  • はじめに
  • インストール/設定
    • インストール手順
  • 例
    • Basic usage
  • HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
    • HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second
    • HRTime\PerformanceCounter::getTicks — Current ticks from the system
    • HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value
  • HRTime\StopWatch — The HRTime\StopWatch class
    • HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals
    • HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals
    • HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval
    • HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval
    • HRTime\StopWatch::isRunning — Whether the measurement is running
    • HRTime\StopWatch::start — Start time measurement
    • HRTime\StopWatch::stop — Stop time measurement
  • HRTime\Unit — The HRTime\Unit class


はじめに

The HRTime extension implements a high resolution StopWatch class. It uses the best possible APIs on different platforms which brings resolution up to nanoseconds. It also makes possible to implement a custom stopwatch using low level ticks delivered by the underlying APIs.

注意: As of PHP 7.3.0 the related function hrtime() is part of the core.


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • HRTime
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/hrtime.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/hrtime/.


  • ≪ インストール手順
  • Basic usage ≫
  • PHP Manual
  • HRTime
  • 例

例

目次

  • Basic usage


Basic usage

The example illustrates the basic StopWatch class usage

例1 Measure several code blocks execution and get the total

<?php

$c = new HRTime\StopWatch;

$c->start();
/* measure this code block execution */
for ($i = 0; $i < 1024*1024; $i++);
$c->stop();
$elapsed0 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

/* measurement is not running here*/
for ($i = 0; $i < 1024*1024; $i++);

$c->start();
/* measure this code block execution */
for ($i = 0; $i < 1024*1024; $i++);
$c->stop();
$elapsed1 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

$elapsed_total = $c->getElapsedTime(HRTime\Unit::NANOSECOND);

?>


The HRTime\PerformanceCounter class

(PECL hrtime >= 0.4.3)

はじめに

クラス概要

class HRTime\PerformanceCounter {
/* メソッド */
public static getFrequency(): int
public static getTicks(): int
public static getTicksSince(int $start): int
}

目次

  • HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second
  • HRTime\PerformanceCounter::getTicks — Current ticks from the system
  • HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value


Timer frequency in ticks per second

  • ≪ HRTime\PerformanceCounter
  • HRTime\PerformanceCounter::getTicks ≫
  • PHP Manual
  • HRTime\PerformanceCounter
  • Timer frequency in ticks per second

HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second

説明

public static HRTime\PerformanceCounter::getFrequency(): int

Returns the timer frequency in ticks per second. This value is constant after the system start on almost any operating system.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns int indicating the timer frequency.


Current ticks from the system

  • ≪ HRTime\PerformanceCounter::getFrequency
  • HRTime\PerformanceCounter::getTicksSince ≫
  • PHP Manual
  • HRTime\PerformanceCounter
  • Current ticks from the system

HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Current ticks from the system

説明

public static HRTime\PerformanceCounter::getTicks(): int

Returns the ticks count.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns int indicating the ticks count.


Ticks elapsed since the given value

  • ≪ HRTime\PerformanceCounter::getTicks
  • HRTime\StopWatch ≫
  • PHP Manual
  • HRTime\PerformanceCounter
  • Ticks elapsed since the given value

HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

説明

public static HRTime\PerformanceCounter::getTicksSince(int $start): int

Returns the ticks count elapsed since the given start value.

パラメータ

start

Starting ticks value.

戻り値

Returns int indicating the ticks count.


The HRTime\StopWatch class

(PECL hrtime >= 0.4.3)

はじめに

クラス概要

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* メソッド */
public getElapsedTicks(): int
public getElapsedTime(int $unit = ?): float
public getLastElapsedTicks(): int
public getLastElapsedTime(int $unit = ?): float
public isRunning(): bool
public start(): void
public stop(): void
/* 継承したメソッド */
public static HRTime\PerformanceCounter::getFrequency(): int
public static HRTime\PerformanceCounter::getTicks(): int
public static HRTime\PerformanceCounter::getTicksSince(int $start): int
}

目次

  • HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals
  • HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals
  • HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval
  • HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval
  • HRTime\StopWatch::isRunning — Whether the measurement is running
  • HRTime\StopWatch::start — Start time measurement
  • HRTime\StopWatch::stop — Stop time measurement


Get elapsed ticks for all intervals

  • ≪ HRTime\StopWatch
  • HRTime\StopWatch::getElapsedTime ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed ticks for all intervals

HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals

説明

public HRTime\StopWatch::getElapsedTicks(): int

Get elapsed ticks for all the previously closed intervals.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns int indicating elapsed ticks.


Get elapsed time for all intervals

  • ≪ HRTime\StopWatch::getElapsedTicks
  • HRTime\StopWatch::getLastElapsedTicks ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed time for all intervals

HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals

説明

public HRTime\StopWatch::getElapsedTime(int $unit = ?): float

Get elapsed time for all the previously closed intervals.

パラメータ

unit

Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

戻り値

Returns float indicating elapsed time.


Get elapsed ticks for the last interval

  • ≪ HRTime\StopWatch::getElapsedTime
  • HRTime\StopWatch::getLastElapsedTime ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed ticks for the last interval

HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval

説明

public HRTime\StopWatch::getLastElapsedTicks(): int

Get elapsed ticks for the previously closed interval.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns int indicating elapsed ticks.


Get elapsed time for the last interval

  • ≪ HRTime\StopWatch::getLastElapsedTicks
  • HRTime\StopWatch::isRunning ≫
  • PHP Manual
  • HRTime\StopWatch
  • Get elapsed time for the last interval

HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval

説明

public HRTime\StopWatch::getLastElapsedTime(int $unit = ?): float

Get elapsed time for the previously closed interval.

パラメータ

unit

Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

戻り値

Returns float indicating elapsed time.


Whether the measurement is running

  • ≪ HRTime\StopWatch::getLastElapsedTime
  • HRTime\StopWatch::start ≫
  • PHP Manual
  • HRTime\StopWatch
  • Whether the measurement is running

HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Whether the measurement is running

説明

public HRTime\StopWatch::isRunning(): bool

Reveals whether the measurement was started.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns bool indicating whether the measurement is running.


Start time measurement

  • ≪ HRTime\StopWatch::isRunning
  • HRTime\StopWatch::stop ≫
  • PHP Manual
  • HRTime\StopWatch
  • Start time measurement

HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Start time measurement

説明

public HRTime\StopWatch::start(): void

Starts the time measurement. It has no effect if the measurement was already started. The measurement will be continued if it was previously stopped.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns void.


Stop time measurement

  • ≪ HRTime\StopWatch::start
  • HRTime\Unit ≫
  • PHP Manual
  • HRTime\StopWatch
  • Stop time measurement

HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Stop time measurement

説明

public HRTime\StopWatch::stop(): void

Stop the time measurement for the previously started interval.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns void.


The HRTime\Unit class

(PECL hrtime >= 0.4.3)

はじめに

クラス概要

class HRTime\Unit {
/* 定数 */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* メソッド */
}

定義済み定数

HRTime\Unit::SECOND

HRTime\Unit::MILLISECOND

HRTime\Unit::MICROSECOND

HRTime\Unit::NANOSECOND


ファイルシステム

  • ダイレクト IO
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ダイレクト IO 関数
  • ディレクトリ
    • 定義済み定数
    • Directory — Directory クラス
    • ディレクトリ 関数
  • Fileinfo — ファイル情報
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Fileinfo 関数
    • finfo — finfo クラス
  • ファイルシステム
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ファイルシステム 関数
  • Inotify
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Inotify 関数
  • xattr
    • はじめに
    • インストール/設定
    • 定義済み定数
    • xattr 関数
  • xdiff
    • はじめに
    • インストール/設定
    • 定義済み定数
    • xdiff 関数


ダイレクト IO

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • ダイレクト IO 関数
    • dio_close — fd で指定したファイル記述子を閉じる
    • dio_fcntl — fd について C ライブラリの fcntl を実行する
    • dio_open — C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)
    • dio_read — ファイル記述子からバイトデータを読み込む
    • dio_seek — fd 上で whence から pos に移動する
    • dio_stat — ファイル記述子 fd に関する stat 情報を取得する
    • dio_tcsetattr — シリアルポートの端末属性とボーレートを設定する
    • dio_truncate — ファイル記述子 fd をオフセットバイトへ丸める
    • dio_write — オプションで丸め長さを指定してデータを書き込む


はじめに

PHP は、POSIX 標準(第 6 章)に記述されたダイレクト IO 関数をサポートします。 これらは、C 言語のストリーム I/O 関数 (fopen(), fread(),..) よりも低レベルの I/O 関数の実装です。 DIO 関数の使用は、あるデバイスを直接制御することが必要な場合のみ考えるべきです。 その他の場合は、標準の ファイルシステム関数の方が適切です。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • ダイレクト IO
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/dio.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


リソース型

この拡張モジュールでは、1 種類のリソース型、すなわち dio_open() により返されるファイル記述子が定義されています。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

F_DUPFD (int)

F_GETFD (int)

F_GETFL (int)

F_GETLK (int)

F_GETOWN (int)

F_RDLCK (int)

F_SETFL (int)

F_SETLK (int)

F_SETLKW (int)

F_SETOWN (int)

F_UNLCK (int)

F_WRLCK (int)

O_APPEND (int)

O_ASYNC (int)

O_CREAT (int)

O_EXCL (int)

O_NDELAY (int)

O_NOCTTY (int)

O_NONBLOCK (int)

O_RDONLY (int)

O_RDWR (int)

O_SYNC (int)

O_TRUNC (int)

O_WRONLY (int)

S_IRGRP (int)

S_IROTH (int)

S_IRUSR (int)

S_IRWXG (int)

S_IRWXO (int)

S_IRWXU (int)

S_IWGRP (int)

S_IWOTH (int)

S_IWUSR (int)

S_IXGRP (int)

S_IXOTH (int)

S_IXUSR (int)


ダイレクト IO 関数

目次

  • dio_close — fd で指定したファイル記述子を閉じる
  • dio_fcntl — fd について C ライブラリの fcntl を実行する
  • dio_open — C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)
  • dio_read — ファイル記述子からバイトデータを読み込む
  • dio_seek — fd 上で whence から pos に移動する
  • dio_stat — ファイル記述子 fd に関する stat 情報を取得する
  • dio_tcsetattr — シリアルポートの端末属性とボーレートを設定する
  • dio_truncate — ファイル記述子 fd をオフセットバイトへ丸める
  • dio_write — オプションで丸め長さを指定してデータを書き込む


fd で指定したファイル記述子を閉じる

  • ≪ ダイレクト IO 関数
  • dio_fcntl ≫
  • PHP Manual
  • ダイレクト IO 関数
  • fd で指定したファイル記述子を閉じる

dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — fd で指定したファイル記述子を閉じる

説明

dio_close(resource $fd): void

関数 dio_close() は、ファイル記述子 fd を閉じます。

パラメータ

fd

dio_open() が返すファイル記述子。

戻り値

値を返しません。

例

例1 開いているファイル記述子を閉じる

<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);

dio_close($fd);
?>

参考

  • dio_open() - C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)


fd について C ライブラリの fcntl を実行する

  • ≪ dio_close
  • dio_open ≫
  • PHP Manual
  • ダイレクト IO 関数
  • fd について C ライブラリの fcntl を実行する

dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — fd について C ライブラリの fcntl を実行する

説明

dio_fcntl(resource $fd, int $cmd, mixed $args = ?): mixed

関数 dio_fcntl() は、ファイル記述子 fd において cmd で指定された処理を行います。いくつかのコマンドでは、オプションの引数 args の指定が必要となります。

パラメータ

fd

dio_open() が返すファイル記述子。

cmd

以下の処理のいずれか。

  • F_SETLK - ロックが設定あるいはクリアされます。 ロックが他の誰かに設定されている場合、dio_fcntl() は -1 を返します。

  • F_SETLKW - F_SETLK と似ていますが、ロックが他の誰かに設定されている場合は dio_fcntl() はそのロックが開放されるまで待ちます。

  • F_GETLK - dio_fcntl() は、他の誰かがロックを妨げる場合、（後述の）連想配列を返します。 妨げるものがない場合、キー "type" は F_UNLCK に設定されます。

  • F_DUPFD - args 以上で最小のファイル記述子を探し、それを返します。

  • F_SETFL - ファイル記述子のフラグを args で指定した値に設定します。指定できる値は O_APPEND、O_NONBLOCK あるいは O_ASYNC のいずれかです。 O_ASYNC を使用するには、 PCNTL 拡張モジュールが必要です。

args

args は連想配列で、 cmd が F_SETLK あるいは F_SETLLW の際に以下のキーを保持します。

  • start - ロックを開始するオフセット。

  • length - ロックする領域の大きさ。ゼロはファイルの終端までを意味します。

  • wenth - l_start の相対位置指定。 SEEK_SET、 SEEK_END および SEEK_CUR のいずれか。

  • type - ロックの種類。F_RDLCK（読み込み ロック）、F_WRLCK（書き込みロック）あるいは F_UNLCK（ロック解除）のいずれか。

戻り値

C ライブラリをコールした結果を返します。

例

例1 ロックの設定と解除

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR);

if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
// ファイル記述子がロックされている
echo "ロックを解除できません。別のプロセスによってロックされています。";
} else {
echo "ロックが正常に設定/解除できました。";
}

dio_close($fd);
?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。


C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

  • ≪ dio_fcntl
  • dio_read ≫
  • PHP Manual
  • ダイレクト IO 関数
  • C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

説明

dio_open(string $filename, int $flags, int $mode = 0): resource

dio_open() は、ファイルをオープンして そのファイル記述子を返します。

パラメータ

filename

オープンするファイルのパス。

flags

flags パラメータには、 以下のフラグの組み合わせを指定します。 この値は、O_RDONLY、O_WRONLY、 あるいは O_RDWR のいずれかでなければなりません。 さらに、このリストからその他の値を組み合わせることもできます。

  • O_RDONLY - 読み込み専用でファイルをオープンします。

  • O_WRONLY - 書き込み専用でファイルをオープンします。

  • O_RDWR - 読み書き両用でファイルをオープンします。

  • O_CREAT - ファイルが存在しなければ 新しいファイルを作成します。

  • O_EXCL - O_CREAT および O_EXCL をともに指定すると、 すでにファイルが存在する場合に dio_open() が失敗します。

  • O_TRUNC - すでにファイルが存在し、書き込み アクセス用にオープンされている場合、ファイルの長さをゼロに切り詰めます。

  • O_APPEND - 書き込み時は、ファイルの終端に 追記します。

  • O_NONBLOCK - 非ブロッキングモードを指定します。

  • O_NOCTTY - TTY デバイスファイルをオープンするときに、 オープンしたファイルをプロセスが自動的に制御端末としないようにします。

mode

flags が O_CREAT を含む場合に、mode でファイルのモード (作成許可) を指定します。O_CREAT が flags に指定されている場合には mode が必須となり、それ以外の場合は無視されます。

ファイルを作成したときに実際に設定されるモードは、プロセスの umask 設定によって変わります。

戻り値

ファイル記述子を返します。エラー時には false を返します。

例

例1 ファイル記述子をオープンする

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_close($fd);
?>

参考

  • dio_close() - fd で指定したファイル記述子を閉じる


ファイル記述子からバイトデータを読み込む

  • ≪ dio_open
  • dio_seek ≫
  • PHP Manual
  • ダイレクト IO 関数
  • ファイル記述子からバイトデータを読み込む

dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — ファイル記述子からバイトデータを読み込む

説明

dio_read(resource $fd, int $len = 1024): string

関数 dio_read() は 記述子 fd で示されるファイルから len バイトを読み込み、それを返します。

パラメータ

fd

dio_open() が返すファイル記述子。

len

読み込むバイト数。指定されなかった場合は dio_read() は 1K サイズのブロックを読み込みます。

戻り値

fd から読み込んだバイトデータを返します。

参考

  • dio_write() - オプションで丸め長さを指定してデータを書き込む


fd 上で whence から pos に移動する

  • ≪ dio_read
  • dio_stat ≫
  • PHP Manual
  • ダイレクト IO 関数
  • fd 上で whence から pos に移動する

dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — fd 上で whence から pos に移動する

説明

dio_seek(resource $fd, int $pos, int $whence = SEEK_SET): int

関数 dio_seek() は、指定されたファイル記述子の ファイル内の位置を変更する際に使用されます。

パラメータ

fd

dio_open() が返すファイル記述子。

pos

新しい位置。

whence

位置 pos をどのように解釈するかを指示します。

  • SEEK_SET（デフォルト）- pos がファイル先頭からの位置であることを 指定します。

  • SEEK_CUR - pos が現在のファイル位置からの文字数である ことを指定します。このカウントは正にも負にもなりえます。

  • SEEK_END - pos がファイル終端からの文字数であることを 指定します。負の値は、現在のファイルの範囲内の位置を指定します。 正の値は、現在のファイル終端を越えた位置を指定します。ファイル終端を 超える位置を指定して実際にデータを書き込んだ場合、ファイルは その位置までゼロバイトで埋めて拡張されます。

戻り値

例

例1 ファイル内の位置の指定

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR);

dio_seek($fd, 10, SEEK_SET);
// ファイル先頭から 10 文字目

dio_seek($fd, -2, SEEK_CUR);
// ファイル先頭から 8 文字目

dio_seek($fd, -5, SEEK_END);
// ファイル終端から 5 文字戻ったところ

dio_seek($fd, 10, SEEK_END);
// ファイル終端からさらに 10 文字進んだところ。
// ファイル終端と現在の位置の間は ゼロ で埋められる。

dio_close($fd);
?>


ファイル記述子 fd に関する stat 情報を取得する

  • ≪ dio_seek
  • dio_tcsetattr ≫
  • PHP Manual
  • ダイレクト IO 関数
  • ファイル記述子 fd に関する stat 情報を取得する

dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — ファイル記述子 fd に関する stat 情報を取得する

説明

dio_stat(resource $fd): array

dio_stat() は、与えられたファイル記述子に関する 情報を返します。

パラメータ

fd

dio_open() が返すファイル記述子。

戻り値

以下のキーを含む連想配列を返します。

  • "device" - デバイス

  • "inode" - i ノード

  • "mode" - モード

  • "nlink" - ハードリンク数

  • "uid" - ユーザー ID

  • "gid" - グループ ID

  • "device_type" - デバイス型（inode デバイスの場合）

  • "size" - サイズ（バイト数）

  • "blocksize" - ブロック長

  • "blocks" - 割り当てられたブロック数

  • "atime" - 最終アクセス時刻

  • "mtime" - 最終更新時刻

  • "ctime" - 最終変更時刻

エラー時には dio_stat() は null を返します。


シリアルポートの端末属性とボーレートを設定する

  • ≪ dio_stat
  • dio_truncate ≫
  • PHP Manual
  • ダイレクト IO 関数
  • シリアルポートの端末属性とボーレートを設定する

dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — シリアルポートの端末属性とボーレートを設定する

説明

dio_tcsetattr(resource $fd, array $options): bool

dio_tcsetattr() は、オープンした fd の端末属性とボーレートを指定します。

パラメータ

fd

dio_open() が返すファイル記述子。

options

現在使用可能なオプションは以下のとおりです。

  • 'baud' - ポートのボーレート - とりうる値は 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 あるいは 50 で、デフォルト値は 9600 。

  • 'bits' - データビット - とりうる値は 8,7,6 あるいは 5 で、デフォルト値は 8 。

  • 'stop' - ストップビット - とりうる値は 1 あるいは 2 で、デフォルト値は 1 。

  • 'parity' - とりうる値は 0,1 あるいは 2 で、デフォルト値は 0 。

戻り値

値を返しません。

例

例1 シリアルポートのボーレートを設定する

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_fcntl($fd, F_SETFL, O_SYNC);

dio_tcsetattr($fd, array(
'baud' => 9600,
'bits' => 8,
'stop' => 1,
'parity' => 0
));

while (1) {

$data = dio_read($fd, 256);

if ($data) {
echo $data;
}
}

?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。


ファイル記述子 fd をオフセットバイトへ丸める

  • ≪ dio_tcsetattr
  • dio_write ≫
  • PHP Manual
  • ダイレクト IO 関数
  • ファイル記述子 fd をオフセットバイトへ丸める

dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — ファイル記述子 fd をオフセットバイトへ丸める

説明

dio_truncate(resource $fd, int $offset): bool

dio_truncate() は、ファイルの大きさを 最大 offset バイトまでに丸めます。

ファイルがこのサイズより大きかった場合は、残りのデータは失われます。 ファイルがこのサイズより小さかった場合は、ファイルがそのままになるか 拡張されるかは未定義です。後者の場合、拡張された部分のデータはゼロと なります。

パラメータ

fd

dio_open() が返すファイル記述子。

offset

オフセットのバイト数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意: この関数は Windows 環境にはまだ実装されていません。


オプションで丸め長さを指定してデータを書き込む

  • ≪ dio_truncate
  • ディレクトリ ≫
  • PHP Manual
  • ダイレクト IO 関数
  • オプションで丸め長さを指定してデータを書き込む

dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — オプションで丸め長さを指定してデータを書き込む

説明

dio_write(resource $fd, string $data, int $len = 0): int

dio_write() は、data から最大 len バイトを ファイル fd に書き込みます。

パラメータ

fd

dio_open() が返すファイル記述子。

data

書き込むデータ。

len

書き込むデータのバイト長。指定しなかった場合は、データ全体を 指定したファイルに書き込みます。

戻り値

fd に書き込んだバイト数を返します。

参考

  • dio_read() - ファイル記述子からバイトデータを読み込む


ディレクトリ

  • 定義済み定数
  • Directory — Directory クラス
    • Directory::close — ディレクトリハンドルをクローズする
    • Directory::read — ディレクトリハンドルからエントリを読み込む
    • Directory::rewind — ディレクトリハンドルを元に戻す
  • ディレクトリ 関数
    • chdir — ディレクトリを変更する
    • chroot — ルートディレクトリを変更する
    • closedir — ディレクトリハンドルをクローズする
    • dir — ディレクトリクラスのインスタンスを返す
    • getcwd — カレントのワーキングディレクトリを取得する
    • opendir — ディレクトリハンドルをオープンする
    • readdir — ディレクトリハンドルからエントリを読み込む
    • rewinddir — ディレクトリハンドルを元に戻す
    • scandir — 指定されたパスのファイルとディレクトリのリストを取得する


定義済み定数

DIRECTORY_SEPARATOR (string)
PATH_SEPARATOR (string)
Windows の場合はセミコロン、それ以外の場合はコロンとなります。


Directory クラス

(PHP 4, PHP 5, PHP 7, PHP 8)

はじめに

Directory クラスのインスタンスを作るには dir() 関数を使います。new 演算子は使いません。

クラス概要

class Directory {
/* プロパティ */
public readonly string $path;
public readonly resource $handle;
/* メソッド */
public close(): void
public read(): string|false
public rewind(): void
}

プロパティ

path

オープンされたディレクトリ。

handle

readdir() や rewinddir()、 closedir() などのディレクトリ関数で使います。

変更履歴

バージョン | 説明
8.1.0 | The path and handle properties are now readonly.

目次

  • Directory::close — ディレクトリハンドルをクローズする
  • Directory::read — ディレクトリハンドルからエントリを読み込む
  • Directory::rewind — ディレクトリハンドルを元に戻す


ディレクトリハンドルをクローズする

  • ≪ Directory
  • Directory::read ≫
  • PHP Manual
  • Directory
  • ディレクトリハンドルをクローズする

Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — ディレクトリハンドルをクローズする

説明

public Directory::close(): void

変更履歴

バージョン | 説明
8.0.0 | 引数を取らなくなりました。 これより前のバージョンでは、 ディレクトリハンドルを引数に渡すことができました。


ディレクトリハンドルからエントリを読み込む

  • ≪ Directory::close
  • Directory::rewind ≫
  • PHP Manual
  • Directory
  • ディレクトリハンドルからエントリを読み込む

Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — ディレクトリハンドルからエントリを読み込む

説明

public Directory::read(): string|false

変更履歴

バージョン | 説明
8.0.0 | 引数を取らなくなりました。 これより前のバージョンでは、 ディレクトリハンドルを引数に渡すことができました。


ディレクトリハンドルを元に戻す

  • ≪ Directory::read
  • ディレクトリ 関数 ≫
  • PHP Manual
  • Directory
  • ディレクトリハンドルを元に戻す

Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — ディレクトリハンドルを元に戻す

説明

public Directory::rewind(): void

変更履歴

バージョン | 説明
8.0.0 | 引数を取らなくなりました。 これより前のバージョンでは、 ディレクトリハンドルを引数に渡すことができました。


ディレクトリ 関数

参考

dirname(), is_dir(), mkdir(), rmdir()等の関数については、 ファイルシステム の節を参照ください。

目次

  • chdir — ディレクトリを変更する
  • chroot — ルートディレクトリを変更する
  • closedir — ディレクトリハンドルをクローズする
  • dir — ディレクトリクラスのインスタンスを返す
  • getcwd — カレントのワーキングディレクトリを取得する
  • opendir — ディレクトリハンドルをオープンする
  • readdir — ディレクトリハンドルからエントリを読み込む
  • rewinddir — ディレクトリハンドルを元に戻す
  • scandir — 指定されたパスのファイルとディレクトリのリストを取得する


ディレクトリを変更する

  • ≪ ディレクトリ 関数
  • chroot ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリを変更する

chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — ディレクトリを変更する

説明

chdir(string $directory): bool

PHP のカレントディレクトリを directory に変更します。

パラメータ

directory

新しいカレントディレクトリ

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

失敗した場合は E_WARNING レベルのエラーが発生します。

例

例1 chdir() の例

<?php

// カレントディレクトリ
echo getcwd() . "\n";

chdir('public_html');

// カレントディレクトリ
echo getcwd() . "\n";

?>

上の例の出力は、 たとえば以下のようになります。

/home/vincent
/home/vincent/public_html

注意

警告

PHP インタプリタが ZTS (Zend Thread Safety) を有効にしてビルドされている場合、 chdir() 関数を使って行った現在のディレクトリの変更はオペレーティングシステムには見えません。 全てのPHPのビルトイン関数は、現在のディレクトリの変更を尊重しますが、 FFI を使って呼び出された外部ライブラリはそうではありません。 あなたの PHP で ZTS が有効かどうかを調べるには、php -i コマンドを使うか、 ビルトイン定数PHP_ZTS を確認してください。

参考

  • getcwd() - カレントのワーキングディレクトリを取得する


ルートディレクトリを変更する

  • ≪ chdir
  • closedir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ルートディレクトリを変更する

chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — ルートディレクトリを変更する

説明

chroot(string $directory): bool

カレントプロセスのルートディレクトリを directory に変更し、 作業ディレクトリを "/" に変更します。

この関数が使えるのは GNU および BSD システムのみで、 かつ CLI, CGI, Embed SAPI を使用している場合のみです。

この関数をコールしても、マジック定数 __DIR__ と __FILE__ の値は変更されません。

パラメータ

directory

ルートディレクトリの変更先のパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 chroot() の例

<?php
chroot("/path/to/your/chroot/");
echo getcwd();
?>

上の例の出力は以下となります。

/

注意

注意: この関数は Windows 環境にはまだ実装されていません。

注意: この関数は ZTS (Zend Thread Safety) を有効にしてビルドした PHPインタプリタでは利用できません。あなたの PHP で ZTS が有効かどうかを調べるには、php -i コマンドを使うか、ビルトイン定数PHP_ZTS を確認してください。


ディレクトリハンドルをクローズする

  • ≪ chroot
  • dir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルをクローズする

closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — ディレクトリハンドルをクローズする

説明

closedir(?resource $dir_handle = null): void

dir_handle で指定したディレクトリのストリームをクローズします。このストリームは、 opendir()により事前にオープンされていなければ なりません。

パラメータ

dir_handle

opendir() が事前にオープンした ディレクトリハンドルリソース。 ディレクトリハンドルを指定しなかった場合は、 opendir() が最後にオープンしたものを使用します。

戻り値

値を返しません。

例

例1 closedir() の例

<?php
$dir = "/etc/php5/";

// 既知のディレクトリをオープンし、変数にディレクトリを読み込んで閉じる
if (is_dir($dir)) {
if ($dh = opendir($dir)) {
$directory = readdir($dh);
closedir($dh);
}
}
?>


ディレクトリクラスのインスタンスを返す

  • ≪ closedir
  • getcwd ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリクラスのインスタンスを返す

dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — ディレクトリクラスのインスタンスを返す

説明

dir(string $directory, ?resource $context = null): Directory|false

ディレクトリを読むための疑似オブジェクト指向の機構です。 指定した directory がオープンされます。

パラメータ

directory

オープンするディレクトリ。

context

ストリームコンテキストリソース

戻り値

Directory のインスタンスを返します。 エラーの場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | context は、nullable になりました。

例

例1 dir() の例

以下の例で、Directory::read() の戻り値をどのように調べているかに 注目してください。戻り値が false と一致することを、明示的に （値が等しく、かつ型も等しい - 詳細は 比較演算子 を参照ください）調べています。なぜなら、そうしないと false と評価されてしまうディレクトリエントリがあった場合にループが とまってしまうからです。

<?php
$d = dir("/etc/php5");
echo "Handle: " . $d->handle . "\n";
echo "Path: " . $d->path . "\n";
while (false !== ($entry = $d->read())) {
echo $entry."\n";
}
$d->close();
?>

上の例の出力は、 たとえば以下のようになります。

Handle: Resource id #2
Path: /etc/php5
.
..
apache
cgi
cli

注意

注意:

読み込みにより返されるディレクトリエントリの順番は、システムに依存します。


カレントのワーキングディレクトリを取得する

  • ≪ dir
  • opendir ≫
  • PHP Manual
  • ディレクトリ 関数
  • カレントのワーキングディレクトリを取得する

getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — カレントのワーキングディレクトリを取得する

説明

getcwd(): string|false

カレントのワーキングディレクトリを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時はカレントのワーキングディレクトリを返します。 失敗時は false を返します。

いくつかの UNIX の派生系では、親ディレクトリが読み込めない、 もしくは検索モードが設定されている場合、カレントディレクトリが可能だとしても getcwd() は false を返します。 モードと権限についての詳細は、chmod() を参照ください。

例

例1 getcwd() の例

<?php

// カレントディレクトリ
echo getcwd() . "\n";

chdir('cvs');

// カレントディレクトリ
echo getcwd() . "\n";

?>

上の例の出力は、 たとえば以下のようになります。

/home/didou
/home/didou/cvs

注意

警告

PHP インタプリタが ZTS (Zend Thread Safety) を有効にしてビルドされていると、 getcwd() 関数が返した現在のカレントディレクトリは、 オペレーティングシステムが返すそれとは異なる可能性があります。 この振る舞いは、カレントディレクトリに依存した (FFI を通じて呼び出される) 外部ライブラリが影響を受けます。

参考

  • chdir() - ディレクトリを変更する
  • chmod() - ファイルのモードを変更する


ディレクトリハンドルをオープンする

  • ≪ getcwd
  • readdir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルをオープンする

opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — ディレクトリハンドルをオープンする

説明

opendir(string $directory, ?resource $context = null): resource|false

ディレクトリハンドルをオープンします。このハンドルは、この後 closedir(), readdir(), rewinddir() 関数コールで使用されます。

パラメータ

directory

オープンするディレクトリのパス。

context

context パラメータの詳細については マニュアルのストリーム を参照ください。

戻り値

成功した場合にディレクトリハンドルの resource 、 失敗した場合に false を返します

エラー / 例外

失敗したときは E_WARNING が発生します。

directory が有効なディレクトリでない場合、 権限の制限によりディレクトリがオープンできない場合、 またはファイルシステムのエラー時に起こりえます。

変更履歴

バージョン | 説明
8.0.0 | context は、nullable になりました。

例

例1 opendir() の例

<?php
$dir = "/etc/php5/";

// 既知のディレクトリをオープンし、その内容を読み込みます。
if (is_dir($dir)) {
if ($dh = opendir($dir)) {
while (($file = readdir($dh)) !== false) {
echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
}
closedir($dh);
}
}
?>

上の例の出力は、 たとえば以下のようになります。

filename: . : filetype: dir
filename: .. : filetype: dir
filename: apache : filetype: dir
filename: cgi : filetype: dir
filename: cli : filetype: dir

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • readdir() - ディレクトリハンドルからエントリを読み込む
  • dir() - ディレクトリクラスのインスタンスを返す


ディレクトリハンドルからエントリを読み込む

  • ≪ opendir
  • rewinddir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルからエントリを読み込む

readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — ディレクトリハンドルからエントリを読み込む

説明

readdir(?resource $dir_handle = null): string|false

ディレクトリから次のエントリの名前を返します。 エントリ名はファイルシステム上に格納されている順番で返されます。

パラメータ

dir_handle

opendir() が事前にオープンした ディレクトリハンドルリソース。 ディレクトリハンドルを指定しなかった場合は、 opendir() が最後にオープンしたものを使用します。

戻り値

成功した場合にエントリ名、失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | dir_handle は、nullable になりました。

例

例1 ディレクトリ内の全てのエントリのリストを得る

以下の例で、readdir() の戻り値をどのように調べているかに 注目してください。戻り値が false と一致することを、明示的に （値が等しく、かつ型も等しい - 詳細は 比較演算子 を参照ください）調べています。なぜなら、そうしないと false と評価されてしまうディレクトリエントリ （例: "0" という名前のディレクトリ）があった場合にループが とまってしまうからです。

<?php

if ($handle = opendir('/path/to/files')) {
echo "Directory handle: $handle\n";
echo "Entries:\n";

/* ディレクトリをループする際の正しい方法です */
while (false !== ($entry = readdir($handle))) {
echo "$entry\n";
}

/* ディレクトリをループする際の「間違った」方法です */
while ($entry = readdir($handle)) {
echo "$entry\n";
}

closedir($handle);
}
?>

例2 カレントディレクトリの全てのエントリを一覧する。ただし . および .. は取り除く

<?php
if ($handle = opendir('.')) {
while (false !== ($entry = readdir($handle))) {
if ($entry != "." && $entry != "..") {
echo "$entry\n";
}
}
closedir($handle);
}
?>

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • glob() - パターンにマッチするパス名を探す
  • opendir() - ディレクトリハンドルをオープンする
  • scandir() - 指定されたパスのファイルとディレクトリのリストを取得する


ディレクトリハンドルを元に戻す

  • ≪ readdir
  • scandir ≫
  • PHP Manual
  • ディレクトリ 関数
  • ディレクトリハンドルを元に戻す

rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — ディレクトリハンドルを元に戻す

説明

rewinddir(?resource $dir_handle = null): void

dir_handle で指定されたディレクトリの ストリームをディレクトリの先頭にリセットします。

パラメータ

dir_handle

opendir() が事前にオープンした ディレクトリハンドルリソース。 ディレクトリハンドルを指定しなかった場合は、 opendir() が最後にオープンしたものを使用します。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | dir_handle は、nullable になりました。


指定されたパスのファイルとディレクトリのリストを取得する

  • ≪ rewinddir
  • Fileinfo ≫
  • PHP Manual
  • ディレクトリ 関数
  • 指定されたパスのファイルとディレクトリのリストを取得する

scandir

(PHP 5, PHP 7, PHP 8)

scandir — 指定されたパスのファイルとディレクトリのリストを取得する

説明

scandir(string $directory, int $sorting_order = SCANDIR_SORT_ASCENDING, ?resource $context = null): array|false

directory 内のファイルおよびディレクトリを 配列で返します。

パラメータ

directory

調べるディレクトリ。

sorting_order

デフォルトでは、ソート順はアルファベット昇順です。 オプションの sorting_order に SCANDIR_SORT_DESCENDING を設定した場合、 ソート順はアルファベット降順になります。 SCANDIR_SORT_NONE を設定すると、 結果をソートせずに返します。

context

context パラメータの説明については、 マニュアルのストリーム を参照ください。

戻り値

成功した場合にファイル名の配列、失敗した場合に false を返します。 directory がディレクトリではない場合は、 false を返し、E_WARNING レベルのエラーを 発行します。

変更履歴

バージョン | 説明
8.0.0 | context は、nullable になりました。

例

例1 scandir() の簡単な例

<?php
$dir = '/tmp';
$files1 = scandir($dir);
$files2 = scandir($dir, SCANDIR_SORT_DESCENDING);

print_r($files1);
print_r($files2);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => .
    [1] => ..
    [2] => bar.php
    [3] => foo.txt
    [4] => somedir
)
Array
(
    [0] => somedir
    [1] => foo.txt
    [2] => bar.php
    [3] => ..
    [4] => .
)

注意

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

参考

  • opendir() - ディレクトリハンドルをオープンする
  • readdir() - ディレクトリハンドルからエントリを読み込む
  • glob() - パターンにマッチするパス名を探す
  • is_dir() - ファイルがディレクトリかどうかを調べる
  • sort() - 配列を昇順にソートする


ファイル情報

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • Fileinfo 関数
    • finfo_buffer — 文字列バッファの情報を返す
    • finfo_close — fileinfo インスタンスを閉じる
    • finfo_file — ファイルについての情報を返す
    • finfo_open — 新しい fileinfo インスタンスを作成する
    • finfo_set_flags — libmagic のオプションを設定する
    • mime_content_type — ファイルの MIME Content-type を検出する
  • finfo — finfo クラス
    • finfo::buffer — finfo_buffer() のエイリアス
    • finfo::__construct — finfo_open のエイリアス
    • finfo::file — finfo_file() のエイリアス
    • finfo::set_flags — finfo_set_flags() のエイリアス


はじめに

このモジュールの関数は、ファイル内の特定の位置から magic バイトシーケンスを見つけることで、 ファイルの content type とエンコーディングを推測します。 これは完全な手法ではありませんが、経験上かなりうまく動作しています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Fileinfo
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

この拡張モジュールは、デフォルトで有効になっています。

Windows ユーザーがこの拡張モジュールを使うには、同梱されている DLL ファイル php_fileinfo.dll を php.ini で有効にしなければなりません。

libmagic ライブラリは PHP に同梱されていますが、PHP 用に変更されています。 libmagic へのパッチは libmagic.patch で、これは PHP fileinfo 拡張モジュールのソースの中に含まれています。


リソース型

PHP 8.1.0 より前のバージョンでは、 Fileinfo 拡張モジュールは、一種類のリソースを使っていました。 finfo_open() が返す magic データベース記述子です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FILEINFO_NONE (int)
特別な処理を行いません。
FILEINFO_SYMLINK (int)
シンボリックリンクのリンク先をたどります。
FILEINFO_MIME_TYPE (int)
mime タイプを返します。
FILEINFO_MIME_ENCODING (int)
ファイルの mime エンコーディングを返します。
FILEINFO_MIME (int)
RFC 2045 で定義された mime タイプと mime エンコーディングを返します。
FILEINFO_COMPRESS (int)
圧縮されたファイルを伸張します。 スレッドセーフに関連する問題のため、無効化されています。
FILEINFO_DEVICES (int)
ブロックデバイスあるいはキャラクタデバイスの内容を探します。
FILEINFO_CONTINUE (int)
最初に見つかったものだけでなく、一致するものをすべて返します。
FILEINFO_PRESERVE_ATIME (int)
可能な限り、元の最終アクセス時刻を保持します。
FILEINFO_RAW (int)
表示できない文字を \ooo 形式の 8 進表現に変換しません。
FILEINFO_EXTENSION (int)
ファイルから検出した MIME タイプに対応する適切な拡張子を返します。 the file. 一般的な拡張子が複数存在するもの (たとえば JPEG 画像など) の場合は、複数の拡張子をスラッシュで連結した値 ("jpeg/jpg/jpe/jfif" など) を返します。 magic.mime データベースに存在しない MIME タイプの場合は "???" を返します。 PHP 7.2.0 以降で使用可能です。
FILEINFO_APPLE (int)
Apple creator と type を返します


Fileinfo 関数

目次

  • finfo_buffer — 文字列バッファの情報を返す
  • finfo_close — fileinfo インスタンスを閉じる
  • finfo_file — ファイルについての情報を返す
  • finfo_open — 新しい fileinfo インスタンスを作成する
  • finfo_set_flags — libmagic のオプションを設定する
  • mime_content_type — ファイルの MIME Content-type を検出する


文字列バッファの情報を返す

  • ≪ Fileinfo 関数
  • finfo_close ≫
  • PHP Manual
  • Fileinfo 関数
  • 文字列バッファの情報を返す

finfo_buffer

finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — 文字列バッファの情報を返す

説明

手続き型

finfo_buffer(
finfo $finfo,
string $string,
int $flags = FILEINFO_NONE,
?resource $context = null
): string|false

オブジェクト指向型

public finfo::buffer(string $string, int $flags = FILEINFO_NONE, ?resource $context = null): string|false

この関数は、バイナリデータの情報を文字列形式で返すために使用します。

パラメータ

finfo

finfo_open() が返す、finfo クラスのインスタンス。

string

調べるファイルの内容。

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

context

戻り値

string のテキスト表現、あるいはエラーが発生した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 finfo は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | context は、nullable になりました。

例

例1 finfo_buffer() の例

<?php
$finfo = new finfo(FILEINFO_MIME);
echo $finfo->buffer($_POST["script"]) . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

application/x-sh; charset=us-ascii

参考

  • finfo_file() - ファイルについての情報を返す


fileinfo インスタンスを閉じる

  • ≪ finfo_buffer
  • finfo_file ≫
  • PHP Manual
  • Fileinfo 関数
  • fileinfo インスタンスを閉じる

finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — fileinfo インスタンスを閉じる

説明

finfo_close(finfo $finfo): bool

この関数は、finfo_open() がオープンしたインスタンスを閉じます。

パラメータ

finfo

finfo_open() が返す、finfo クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 finfo は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


ファイルについての情報を返す

  • ≪ finfo_close
  • finfo_open ≫
  • PHP Manual
  • Fileinfo 関数
  • ファイルについての情報を返す

finfo_file

finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — ファイルについての情報を返す

説明

手続き型

finfo_file(
finfo $finfo,
string $filename,
int $flags = FILEINFO_NONE,
?resource $context = null
): string|false

オブジェクト指向型

public finfo::file(string $filename, int $flags = FILEINFO_NONE, ?resource $context = null): string|false

この関数は、ファイルについての情報を返すために使用します。

パラメータ

finfo

finfo_open() が返す、finfo クラスのインスタンス。

filename

調べるファイルの名前。

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

context

contexts の説明については、ストリーム 関数 を参照ください。

戻り値

filename のテキスト表現、あるいはエラーが発生した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 finfo は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.0.0 | context は、nullable になりました。

例

例1 finfo_file() の例

<?php
$finfo = finfo_open(FILEINFO_MIME_TYPE); // mimetype 拡張モジュール風に mime タイプを返します
foreach (glob("*") as $filename) {
echo finfo_file($finfo, $filename) . "\n";
}
finfo_close($finfo);
?>

上の例の出力は、 たとえば以下のようになります。

text/html
image/gif
application/vnd.ms-excel

参考

  • finfo_buffer() - 文字列バッファの情報を返す


新しい fileinfo インスタンスを作成する

  • ≪ finfo_file
  • finfo_set_flags ≫
  • PHP Manual
  • Fileinfo 関数
  • 新しい fileinfo インスタンスを作成する

finfo_open

finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — 新しい fileinfo インスタンスを作成する

説明

手続き型

finfo_open(int $flags = FILEINFO_NONE, ?string $magic_database = null): finfo|false

オブジェクト指向型 (コンストラクタ)

public finfo::__construct(int $flags = FILEINFO_NONE, ?string $magic_database = null)

この関数は、magic データベースをオープンしてそのインスタンスを返します。

パラメータ

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

magic_database

magic データベースファイルの名前。通常は /path/to/magic.mime のようになります。 指定されなかった場合は、環境変数 MAGIC の値が使用されます。この環境変数も設定されていない場合は、 PHP の組み込みの magic データベースを使います。

null あるいは空文字列は、デフォルト値と同じ意味となります。

戻り値

成功した場合に finfo クラスのインスタンスを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.1.0 | finfo クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。
8.0.3 | magic_database は、nullable になりました。

例

例1 オブジェクト指向型

<?php
$finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // mime タイプを mimetype 拡張形式で返します

/* 指定したファイルの mime タイプを取得します */
$filename = "/usr/local/something.txt";
echo $finfo->file($filename);

?>

例2 手続き型

<?php
$finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // mime タイプを mimetype 拡張形式で返します

if (!$finfo) {
echo "fileinfo データベースのオープンに失敗しました";
exit();
}

/* 指定したファイルの mime タイプを取得します */
$filename = "/usr/local/something.txt";
echo finfo_file($finfo, $filename);

/* 接続を閉じます */
finfo_close($finfo);
?>

上の例の出力は以下となります。

text/plain; charset=us-ascii

注意

注意:

一般的には、独自の magic データベースを使う必要がある場合を除いて、 組み込みの magic データベースを使うのが一番いい方法です (magic_database を省略し、環境変数 MAGIC も設定しないようにします)。

参考

  • finfo_close() - fileinfo インスタンスを閉じる


libmagic のオプションを設定する

  • ≪ finfo_open
  • mime_content_type ≫
  • PHP Manual
  • Fileinfo 関数
  • libmagic のオプションを設定する

finfo_set_flags

finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — libmagic のオプションを設定する

説明

手続き型

finfo_set_flags(finfo $finfo, int $flags): true

オブジェクト指向型

public finfo::set_flags(int $flags): bool

この関数は、さまざまな Fileinfo オプションを設定します。 finfo_open() やその他の Fileinfo 関数で、 オプションを直接指定することも可能です。

パラメータ

finfo

finfo_open() が返す、finfo クラスのインスタンス。

flags

ひとつあるいは複数のFileinfo 定数の組み合わせ。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 finfo は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


ファイルの MIME Content-type を検出する

  • ≪ finfo_set_flags
  • finfo ≫
  • PHP Manual
  • Fileinfo 関数
  • ファイルの MIME Content-type を検出する

mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — ファイルの MIME Content-type を検出する

説明

mime_content_type(resource|string $filename): string|false

magic.mime ファイルの情報を用いて、 ファイルの MIME content type を返します。

パラメータ

filename

調べるファイルへのパス。

戻り値

Content type を MIME 形式で返します。 たとえば text/plain あるいは application/octet-stream のような形式です。 失敗した場合に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 mime_content_type() の例

<?php
echo mime_content_type('php.gif') . "\n";
echo mime_content_type('test.php');
?>

上の例の出力は以下となります。

image/gif
text/plain

参考

  • finfo_file() - ファイルについての情報を返す
  • finfo_buffer() - 文字列バッファの情報を返す


finfo クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

はじめに

このクラスは、fileinfo 関数にオブジェクト指向のインターフェイスを提供します。

クラス概要

class finfo {
/* メソッド */
public __construct(int $flags = FILEINFO_NONE, ?string $magic_database = null)
public buffer(string $string, int $flags = FILEINFO_NONE, ?resource $context = null): string|false
public file(string $filename, int $flags = FILEINFO_NONE, ?resource $context = null): string|false
public set_flags(int $flags): bool
}

目次

  • finfo::buffer — finfo_buffer() のエイリアス
  • finfo::__construct — finfo_open のエイリアス
  • finfo::file — finfo_file() のエイリアス
  • finfo::set_flags — finfo_set_flags() のエイリアス


finfo_buffer() のエイリアス

  • ≪ finfo
  • finfo::__construct ≫
  • PHP Manual
  • finfo
  • finfo_buffer() のエイリアス

finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — finfo_buffer() のエイリアス

説明

public finfo::buffer(string $string, int $flags = FILEINFO_NONE, ?resource $context = null): string|false

この関数は次の関数のエイリアスです。 finfo_buffer()


finfo_open のエイリアス

  • ≪ finfo::buffer
  • finfo::file ≫
  • PHP Manual
  • finfo
  • finfo_open のエイリアス

finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — finfo_open() のエイリアス

説明

public finfo::__construct(int $flags = FILEINFO_NONE, ?string $magic_database = null)

この関数は次の関数のエイリアスです。 finfo_open()

変更履歴

バージョン | 説明
8.0.3 | magic_database は、nullable になりました。


finfo_file() のエイリアス

  • ≪ finfo::__construct
  • finfo::set_flags ≫
  • PHP Manual
  • finfo
  • finfo_file() のエイリアス

finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — finfo_file() のエイリアス

説明

public finfo::file(string $filename, int $flags = FILEINFO_NONE, ?resource $context = null): string|false

この関数は次の関数のエイリアスです。 finfo_file()


finfo_set_flags() のエイリアス

  • ≪ finfo::file
  • ファイルシステム ≫
  • PHP Manual
  • finfo
  • finfo_set_flags() のエイリアス

finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — finfo_set_flags() のエイリアス

説明

public finfo::set_flags(int $flags): bool

この関数は次の関数のエイリアスです。 finfo_set_flags()


ファイルシステム

  • はじめに
  • インストール/設定
    • 実行時設定
    • リソース型
  • 定義済み定数
  • ファイルシステム 関数
    • basename — パスの最後にある名前の部分を返す
    • chgrp — ファイルのグループを変更する
    • chmod — ファイルのモードを変更する
    • chown — ファイルの所有者を変更する
    • clearstatcache — ファイルのステータスのキャッシュをクリアする
    • copy — ファイルをコピーする
    • delete — unlink か unset を参照ください
    • dirname — 親ディレクトリのパスを返す
    • disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す
    • disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す
    • diskfreespace — disk_free_space のエイリアス
    • fclose — オープンされたファイルポインタをクローズする
    • fdatasync — データをファイルに同期する(但しメタデータは除く)
    • feof — ファイルポインタがファイル終端に達しているかどうか調べる
    • fflush — 出力をファイルにフラッシュする
    • fgetc — ファイルポインタから1文字取り出す
    • fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する
    • fgets — ファイルポインタから 1 行取得する
    • fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く
    • file — ファイル全体を読み込んで配列に格納する
    • file_exists — ファイルまたはディレクトリが存在するかどうか調べる
    • file_get_contents — ファイルの内容を全て文字列に読み込む
    • file_put_contents — データをファイルに書き込む
    • fileatime — ファイルの最終アクセス時刻を取得する
    • filectime — ファイルの inode 変更時刻を取得する
    • filegroup — ファイルのグループを取得する
    • fileinode — ファイルの inode を取得する
    • filemtime — ファイルの更新時刻を取得する
    • fileowner — ファイルの所有者を取得する
    • fileperms — ファイルのパーミッションを取得する
    • filesize — ファイルのサイズを取得する
    • filetype — ファイルタイプを取得する
    • flock — 汎用のファイルロックを行う
    • fnmatch — ファイル名がパターンにマッチするか調べる
    • fopen — ファイルまたは URL をオープンする
    • fpassthru — ファイルポインタ上に残っているすべてのデータを出力する
    • fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
    • fputs — fwrite のエイリアス
    • fread — バイナリセーフなファイルの読み込み
    • fscanf — フォーマットに基づきファイルからの入力を処理する
    • fseek — ファイルポインタを移動する
    • fstat — オープンしたファイルポインタからファイルに関する情報を取得する
    • fsync — データをファイルに同期する(メタデータも含む)
    • ftell — ファイルの読み書き用ポインタの現在位置を返す
    • ftruncate — ファイルを指定した長さに丸める
    • fwrite — バイナリセーフなファイル書き込み処理
    • glob — パターンにマッチするパス名を探す
    • is_dir — ファイルがディレクトリかどうかを調べる
    • is_executable — ファイルが実行可能かどうかを調べる
    • is_file — 通常ファイルかどうかを調べる
    • is_link — ファイルがシンボリックリンクかどうかを調べる
    • is_readable — ファイルが存在し、読み込み可能であるかどうかを知る
    • is_uploaded_file — HTTP POST でアップロードされたファイルかどうかを調べる
    • is_writable — ファイルが書き込み可能かどうかを調べる
    • is_writeable — is_writable のエイリアス
    • lchgrp — シンボリックリンクのグループ所有権を変更する
    • lchown — シンボリックリンクの所有者を変更する
    • link — ハードリンクを作成する
    • linkinfo — リンクに関する情報を取得する
    • lstat — ファイルあるいはシンボリックリンクの情報を取得する
    • mkdir — ディレクトリを作る
    • move_uploaded_file — アップロードされたファイルを新しい位置に移動する
    • parse_ini_file — 設定ファイルをパースする
    • parse_ini_string — 設定文字列をパースする
    • pathinfo — ファイルパスに関する情報を返す
    • pclose — プロセスのファイルポインタをクローズする
    • popen — プロセスへのファイルポインタをオープンする
    • readfile — ファイルを出力する
    • readlink — シンボリックリンク先を返す
    • realpath — 正規化された絶対パス名を返す
    • realpath_cache_get — realpath キャッシュ・エントリーを取得
    • realpath_cache_size — realpath キャッシュサイズを取得
    • rename — ファイルをリネームする
    • rewind — ファイルポインタの位置を先頭に戻す
    • rmdir — ディレクトリを削除する
    • set_file_buffer — stream_set_write_buffer のエイリアス
    • stat — ファイルに関する情報を取得する
    • symlink — シンボリックリンクを作成する
    • tempnam — 一意なファイル名を生成する
    • tmpfile — テンポラリファイルを作成する
    • touch — ファイルの最終アクセス時刻および最終更新日をセットする
    • umask — 現在の umask を変更する
    • unlink — ファイルを削除する


はじめに

この拡張モジュールを構築するには外部ライブラリは必要ありませんが、 Linux 上で LFS (ラージファイル) をサポートする PHP を希望する場合は、 最新の glibc を入手し、次のコンパイラフラグ -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 を付けて PHP をコンパイルする必要があります。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • ファイルシステム
  • インストール/設定

インストール/設定

目次

  • 実行時設定
  • リソース型


実行時設定

php.ini の設定により動作が変化します。

ファイルシステムおよびストリーム設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
allow_url_fopen | "1" | INI_SYSTEM |
allow_url_include | "0" | INI_SYSTEM | PHP 7.4.0 以降は非推奨になりました。
user_agent | NULL | INI_ALL |
default_socket_timeout | "60" | INI_ALL |
from | "" | INI_ALL |
auto_detect_line_endings | "0" | INI_ALL | PHP 8.1.0 以降は非推奨になりました。
sys_temp_dir | "" | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

allow_url_fopen bool

このオプションにより、URL対応のfopenラッパーが使用可能となり、 ファイルのようにURLオブジェクトをアクセスできるようになります。 デフォルトのラッパーが、ftpまたはhttpプロトコルを用いて リモートファイルに アクセスするために提供されています。zlibのようないくつかの拡張モジュールが ラッパーを追加することがあります。

allow_url_include bool

このオプションを指定すると include, include_once, require, require_once で URL 対応の fopen ラッパーが使用できるようになります。

注意:

この設定を使用するには、allow_url_fopen が on でないといけません。

user_agent string

送信する PHP 用のユーザーエージェントを定義します。

default_socket_timeout int

ソケットベースのストリームのデフォルトの有効時間(単位は秒)を定義します。 負の値を指定した場合、タイムアウトしません。

from string

認証なしの FTP 接続で使ったり、あるいは HTTP 接続の From ヘッダで使ったりするためのメールアドレス。 それぞれ、ftp ラッパーおよび http ラッパーに対応します。

auto_detect_line_endings bool

onにした場合、PHPは fgets() および file() により読み込まれたデータを評価し、UNIX、MS-DOS、Machintoshの行末 表記を使用しているかどうかを調べます。

これにより、PHPがMacintoshシステムと相互運用できるようになりますが、 デフォルトはOffとなっています。これは、最初の行の行末表記を検出 する際にごく僅かな性能劣化があるためと、UNIXシステムのもとで復改 文字を項目セパレータとして使用している人が従来のバージョンと互換 性がない動作であると感じる可能性があるためです。

sys_temp_dir string


リソース型

ファイルシステム関数では、ストリームリソースを用います。 ストリームに関するドキュメントは、ひとつの章として独立しています。 ストリーム を参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SEEK_SET (int)
SEEK_CUR (int)
SEEK_END (int)
LOCK_SH (int)
LOCK_EX (int)
LOCK_UN (int)
LOCK_NB (int)
GLOB_BRACE (int)
{a,b,c} を 'a', 'b', 'c' にマッチさせるように展開します。

注意: GLOB_BRACE は GNU システムでないシステムによっては使えない場合があります。 使えないシステムの例として、Solaris や Alpine Linux があてはまります。

GLOB_ERR (int)
(ディレクトリが読み取れない場合のような) 読み取りエラーの場合に停止します。 デフォルトでは、エラーは無視されます。
GLOB_ONLYDIR (int)
パターンにマッチするディレクトリエントリのみを返します。
GLOB_MARK (int)
スラッシュ(Windows の場合はバックスラッシュ) を返されるディレクトリに個別に追加します。
GLOB_NOSORT (int)
ディレクトリ内に存在するかのように、ファイルを返します(ソートは行いません)。 このフラグを使わない場合、パス名はアルファベット順でソートされます。
GLOB_NOCHECK (int)
マッチするファイルが見つからない場合に、検索パターンを返します。
GLOB_NOESCAPE (int)
バックスラッシュは、メタキャラクタをクォートしません。
GLOB_AVAILABLE_FLAGS (int)
すべての GLOB_* フラグの組み合わせです。 0 | GLOB_BRACE | GLOB_MARK | GLOB_NOSORT | GLOB_NOCHECK | GLOB_NOESCAPE | GLOB_ERR | GLOB_ONLYDIR と等しくなります。
定数 | 説明
PATHINFO_ALL (int) | pathinfo の全ての情報です。 連想配列として返されます。
PATHINFO_DIRNAME (int) | ファイルのディレクトリパス
PATHINFO_BASENAME (int) | ディレクトリ名、またはファイル名とその拡張子
PATHINFO_EXTENSION (int) | ファイルの拡張子
PATHINFO_FILENAME (int) | ファイル名（拡張子なし)またはディレクトリ名
FILE_USE_INCLUDE_PATH (int) | filename を include_path から探します。
FILE_NO_DEFAULT_CONTEXT (int)
FILE_APPEND (int) | 既存のファイルに追記します。
FILE_IGNORE_NEW_LINES (int) | EOL (行末) 文字を取り除きます。
FILE_SKIP_EMPTY_LINES (int) | 空行を読み飛ばします。
FILE_BINARY (int)

バイナリモード

注意:

この定数は何の効果もありません。 前方互換性 のためだけに用意されています。

FILE_TEXT (int)

テキストモード

注意:

この定数は何の効果もありません。 前方互換性 のためだけに用意されています。

INI_SCANNER_NORMAL (int) | 通常の INI スキャナモード
INI_SCANNER_RAW (int) | 生の INI スキャナモード
INI_SCANNER_TYPED (int) | 型つきの INI スキャナモード
FNM_NOESCAPE (int) | バックスラッシュのエスケープを無効にする。
FNM_PATHNAME (int) | 文字列中のスラッシュが、指定したパターン内のスラッシュにのみマッチする。
FNM_PERIOD (int) | 文字列の先頭のピリオドが、指定したパターン内のピリオドにのみマッチする。
FNM_CASEFOLD (int) | 大文字小文字を区別しないマッチを行う。GNU 拡張の一部。
定数 | 説明
UPLOAD_ERR_CANT_WRITE | ファイルをディスクに書き込めませんでした。
UPLOAD_ERR_EXTENSION | PHP 拡張機能がファイルアップロードを停止させました PHP はどの拡張機能がファイルアップロードを止めたのかを検出する手段を提供していません。phpinfo() で表示される、ロード済みの拡張機能の一覧が手掛かりになるかもしれません。
UPLOAD_ERR_FORM_SIZE | アップロードされたファイルが、 HTML フォームで指定された MAX_FILE_SIZE を超えています。
UPLOAD_ERR_INI_SIZE | アップロードされたファイルが、 php.ini の upload_max_filesize を超えています。
UPLOAD_ERR_NO_FILE | アップロードされたファイルはありません。
UPLOAD_ERR_NO_TMP_DIR | テンポラリフォルダがありません。
UPLOAD_ERR_OK | エラーはありません。ファイルのアップロードは成功しました。
UPLOAD_ERR_PARTIAL | アップロードされたファイルは一部だけでした。


ファイルシステム 関数

参考

関連する関数については、ディレクトリ およびプログラム実行の節を 参照ください。

リモートファイルとして使用することができる種々のURLラッパーの一覧 と説明については、サポートするプロトコル/ラッパーも参照ください。

目次

  • basename — パスの最後にある名前の部分を返す
  • chgrp — ファイルのグループを変更する
  • chmod — ファイルのモードを変更する
  • chown — ファイルの所有者を変更する
  • clearstatcache — ファイルのステータスのキャッシュをクリアする
  • copy — ファイルをコピーする
  • delete — unlink か unset を参照ください
  • dirname — 親ディレクトリのパスを返す
  • disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す
  • disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す
  • diskfreespace — disk_free_space のエイリアス
  • fclose — オープンされたファイルポインタをクローズする
  • fdatasync — データをファイルに同期する(但しメタデータは除く)
  • feof — ファイルポインタがファイル終端に達しているかどうか調べる
  • fflush — 出力をファイルにフラッシュする
  • fgetc — ファイルポインタから1文字取り出す
  • fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する
  • fgets — ファイルポインタから 1 行取得する
  • fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • file — ファイル全体を読み込んで配列に格納する
  • file_exists — ファイルまたはディレクトリが存在するかどうか調べる
  • file_get_contents — ファイルの内容を全て文字列に読み込む
  • file_put_contents — データをファイルに書き込む
  • fileatime — ファイルの最終アクセス時刻を取得する
  • filectime — ファイルの inode 変更時刻を取得する
  • filegroup — ファイルのグループを取得する
  • fileinode — ファイルの inode を取得する
  • filemtime — ファイルの更新時刻を取得する
  • fileowner — ファイルの所有者を取得する
  • fileperms — ファイルのパーミッションを取得する
  • filesize — ファイルのサイズを取得する
  • filetype — ファイルタイプを取得する
  • flock — 汎用のファイルロックを行う
  • fnmatch — ファイル名がパターンにマッチするか調べる
  • fopen — ファイルまたは URL をオープンする
  • fpassthru — ファイルポインタ上に残っているすべてのデータを出力する
  • fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
  • fputs — fwrite のエイリアス
  • fread — バイナリセーフなファイルの読み込み
  • fscanf — フォーマットに基づきファイルからの入力を処理する
  • fseek — ファイルポインタを移動する
  • fstat — オープンしたファイルポインタからファイルに関する情報を取得する
  • fsync — データをファイルに同期する(メタデータも含む)
  • ftell — ファイルの読み書き用ポインタの現在位置を返す
  • ftruncate — ファイルを指定した長さに丸める
  • fwrite — バイナリセーフなファイル書き込み処理
  • glob — パターンにマッチするパス名を探す
  • is_dir — ファイルがディレクトリかどうかを調べる
  • is_executable — ファイルが実行可能かどうかを調べる
  • is_file — 通常ファイルかどうかを調べる
  • is_link — ファイルがシンボリックリンクかどうかを調べる
  • is_readable — ファイルが存在し、読み込み可能であるかどうかを知る
  • is_uploaded_file — HTTP POST でアップロードされたファイルかどうかを調べる
  • is_writable — ファイルが書き込み可能かどうかを調べる
  • is_writeable — is_writable のエイリアス
  • lchgrp — シンボリックリンクのグループ所有権を変更する
  • lchown — シンボリックリンクの所有者を変更する
  • link — ハードリンクを作成する
  • linkinfo — リンクに関する情報を取得する
  • lstat — ファイルあるいはシンボリックリンクの情報を取得する
  • mkdir — ディレクトリを作る
  • move_uploaded_file — アップロードされたファイルを新しい位置に移動する
  • parse_ini_file — 設定ファイルをパースする
  • parse_ini_string — 設定文字列をパースする
  • pathinfo — ファイルパスに関する情報を返す
  • pclose — プロセスのファイルポインタをクローズする
  • popen — プロセスへのファイルポインタをオープンする
  • readfile — ファイルを出力する
  • readlink — シンボリックリンク先を返す
  • realpath — 正規化された絶対パス名を返す
  • realpath_cache_get — realpath キャッシュ・エントリーを取得
  • realpath_cache_size — realpath キャッシュサイズを取得
  • rename — ファイルをリネームする
  • rewind — ファイルポインタの位置を先頭に戻す
  • rmdir — ディレクトリを削除する
  • set_file_buffer — stream_set_write_buffer のエイリアス
  • stat — ファイルに関する情報を取得する
  • symlink — シンボリックリンクを作成する
  • tempnam — 一意なファイル名を生成する
  • tmpfile — テンポラリファイルを作成する
  • touch — ファイルの最終アクセス時刻および最終更新日をセットする
  • umask — 現在の umask を変更する
  • unlink — ファイルを削除する


パスの最後にある名前の部分を返す

  • ≪ ファイルシステム 関数
  • chgrp ≫
  • PHP Manual
  • ファイルシステム 関数
  • パスの最後にある名前の部分を返す

basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — パスの最後にある名前の部分を返す

説明

basename(string $path, string $suffix = ""): string

ファイルあるいはディレクトリへのパスを含む文字列を受け取って、 最後にある名前の部分を返します。

注意:

basename() は、入力文字列を単純にそのまま処理します。 実際のファイルシステムを確認したり ".." のようなパスを気にしたりすることはありません。

警告

basename() はロケールに依存します。 マルチバイト文字を含むパスで正しい結果を得るには、それと一致するロケールを setlocale() で設定しておかなければなりません。 現在のロケールから見て不正な文字が path に含まれていた場合、 basename() の動作は未定義です。

パラメータ

path

パス。

Windows では、スラッシュ(/) とバックスラッシュ (\) の両方がディレクトリ区切り文字として使われます。 その他の環境ではスラッシュ(/)になります。

suffix

名前の部分が suffix で終了する場合、 この部分もカットされます。

戻り値

指定した path のベース名を返します。

例

例1 basename() の例

<?php
echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
echo "3) ".basename("/etc/passwd").PHP_EOL;
echo "4) ".basename("/etc/").PHP_EOL;
echo "5) ".basename(".").PHP_EOL;
echo "6) ".basename("/");
?>

上の例の出力は以下となります。

1) sudoers
2) sudoers.d
3) passwd
4) etc
5) .
6)

参考

  • dirname() - 親ディレクトリのパスを返す
  • pathinfo() - ファイルパスに関する情報を返す


ファイルのグループを変更する

  • ≪ basename
  • chmod ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのグループを変更する

chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — ファイルのグループを変更する

説明

chgrp(string $filename, string|int $group): bool

(名前または番号で指定した)ファイル filename のグループを group に変更しようと試みます。

スーパーユーザーのみがファイルのグループを任意に変更できます。 その他のユーザーは、ファイルのグループをそのユーザーがメンバーとして 属しているグループに変更できます。

パラメータ

filename

ファイルへのパス。

group

グループ名あるいはグループ番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルのグループの変更

<?php
$filename = 'shared_file.txt';
$format = "%s's Group ID @ %s: %d\n";
printf($format, $filename, date('r'), filegroup($filename));
chgrp($filename, 8);
clearstatcache(); // filegroup() の結果はキャッシュしない
printf($format, $filename, date('r'), filegroup($filename));
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: Windows で通常ファイルに対してこの関数を実行すると、静かに失敗します。

参考

  • chown() - ファイルの所有者を変更する
  • chmod() - ファイルのモードを変更する


ファイルのモードを変更する

  • ≪ chgrp
  • chown ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのモードを変更する

chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — ファイルのモードを変更する

説明

chmod(string $filename, int $permissions): bool

指定されたファイルのモードを permissions で指定したものに変更しようと試みます。

パラメータ

filename

ファイルへのパス。

permissions

permissions は自動的には 8 進数と見なされないので注意してください。 意図した操作を行うには、permissions の前にゼロ(0)を付ける必要があります。 "g+w" のような文字列は正常に動作しません。

<?php
chmod("/somedir/somefile", 755); // 10 進数; おそらく間違い
chmod("/somedir/somefile", "u+rwx,go+rx"); // 文字列; 正しくない
chmod("/somedir/somefile", 0755); // 8 進数; 正しいモードの値
?>

permissions 引数は 3 つの 8 進法による数値で構成され、 所有者自身、所有者が属するグループ、その他のユーザーの順で アクセス制限を設定します。一つ一つの数字はそのターゲットに対し 許可を与えます。1 は実行権限、2 はファイルに対する書き込み権限、 4 はファイルに対する読み込み権限を与えます。 必要な権限にあわせ数値を加算してください。 許可モードに関する詳細は Unix システムの 「man 1 chmod」や「man 2 chmod」をご覧ください。

<?php
// 所有者に読み込み、書き込みの権限を与え、その他には何も許可しない。
chmod("/somedir/somefile", 0600);

// 所有者に読み込み、書き込みの権限を与え、その他には読み込みだけ許可する。
chmod("/somedir/somefile", 0644);

// 所有者に全ての権限を与え、その他には読み込みと実行を許可する。
chmod("/somedir/somefile", 0755);

// 所有者に全ての権限を与え、所有者が属するグループに読み込みと実行を許可する。
chmod("/somedir/somefile", 0750);
?>

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

失敗時には E_WARNING が発生します。

注意

注意:

現在のユーザーは PHP を実行しているユーザーです。 これは普通のシェルや FTP アクセスでのユーザーとはたいてい違います。 たいていのシステムでは、ファイルの所有者のみがそのモードを 変更可能です。

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

参考

  • chown() - ファイルの所有者を変更する
  • chgrp() - ファイルのグループを変更する
  • fileperms() - ファイルのパーミッションを取得する
  • stat() - ファイルに関する情報を取得する


ファイルの所有者を変更する

  • ≪ chmod
  • clearstatcache ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの所有者を変更する

chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — ファイルの所有者を変更する

説明

chown(string $filename, string|int $user): bool

ファイルfilenameの所有者を(名前または番号で指定した) ユーザーuserに変更しようと試みます。 スーパーユーザーのみがファイルの所有者を変更できます。

パラメータ

filename

ファイルへのパス。

user

ユーザー名あるいはユーザー番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンプルな chown() の例

<?php

// 使用するファイル名とユーザー名
$file_name= "foo.php";
$path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
$user_name = "root";

// ユーザーを設定します
chown($path, $user_name);

// 結果を確認します
$stat = stat($path);
print_r(posix_getpwuid($stat['uid']));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name] => root
    [passwd] => x
    [uid] => 0
    [gid] => 0
    [gecos] => root
    [dir] => /root
    [shell] => /bin/bash
)

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: Windows で通常ファイルに対してこの関数を実行すると、静かに失敗します。

参考

  • chmod() - ファイルのモードを変更する
  • chgrp() - ファイルのグループを変更する


ファイルのステータスのキャッシュをクリアする

  • ≪ chown
  • copy ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのステータスのキャッシュをクリアする

clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — ファイルのステータスのキャッシュをクリアする

説明

clearstatcache(bool $clear_realpath_cache = false, string $filename = ""): void

statやlstat、 またはその他の関数（後述）を使用すると、PHPはパフォーマンス向上のために それらの関数の戻り値をキャッシュします。しかし、ケースによっては、 キャッシュされた情報を消去したい場合もあるでしょう。 例えば、一つのスクリプト上で同じファイルが何度もチェックされ、 そのファイルが変更されたり削除されたりする可能性がある場合、 ステータスキャッシュを消去しなければならないと感じるでしょう。 このようなケースでは、clearstatcache()を使用することで ファイルの情報に関してPHPが持っているキャッシュをクリアすることができます。

PHP は存在しないファイルについての情報はキャッシュしないことにも 注意してください。もし存在しないファイルに対して file_exists() をコールする場合、ファイルを作成するまで この関数は false を返します。もしファイルを作成した場合、 たとえファイルを削除したとしても true を返します。 しかし、unlink() はキャッシュを自動的にクリアします。

注意:

この関数は特定のファイルに関する情報をキャッシュします。したがって、 同じファイルについて複数回の操作を行いそのファイルに関する情報を キャッシュされないようにするためには、 clearstatcache()をコールするだけです。

影響を受ける関数を以下に示します。
stat(),
lstat(),
file_exists(),
is_writable(),
is_readable(),
is_executable(),
is_file(),
is_dir(),
is_link(),
filectime(),
fileatime(),
filemtime(),
fileinode(),
filegroup(),
fileowner(),
filesize(),
filetype(), および
fileperms().

パラメータ

clear_realpath_cache

realpath キャッシュもクリアするかどうか。

filename

realpath キャッシュを特定のファイル名だけに対してクリアする。 clear_realpath_cache が true の場合にのみ使用。

戻り値

値を返しません。

例

例1 clearstatcache() の例

<?php
$file = 'output_log.txt';

function get_owner($file)
{
$stat = stat($file);
$user = posix_getpwuid($stat['uid']);
return $user['name'];
}

$format = "UID @ %s: %s\n";

printf($format, date('r'), get_owner($file));

chown($file, 'ross');
printf($format, date('r'), get_owner($file));

clearstatcache();
printf($format, date('r'), get_owner($file));
?>

上の例の出力は、 たとえば以下のようになります。

UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross


ファイルをコピーする

  • ≪ clearstatcache
  • delete ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルをコピーする

copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — ファイルをコピーする

説明

copy(string $from, string $to, ?resource $context = null): bool

ファイル from を to にコピーします。

ファイルを移動したいならば、rename() 関数を使用してください。

パラメータ

from

コピー元ファイルへのパス。

to

コピー先のパス。to が URL の場合、 既存ファイルへの上書きをラッパーがサポートしていない場合にはコピーが失敗します。

警告

コピー先のファイルが既に存在する場合、上書きされます。

context

stream_context_create() で作成した有効なコンテキストリソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 copy() の例

<?php
$file = 'example.txt';
$newfile = 'example.txt.bak';

if (!copy($file, $newfile)) {
echo "failed to copy $file...\n";
}
?>

参考

  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する
  • rename() - ファイルをリネームする
  • マニュアルの ファイルアップロード処理


unlink か unset を参照ください

  • ≪ copy
  • dirname ≫
  • PHP Manual
  • ファイルシステム 関数
  • unlink か unset を参照ください

delete

delete — unlink() か unset() を参照ください

説明

PHP には、delete というキーワードや関数は存在しません。 もしあなたがファイルを削除する方法を探してこのページにたどり着いたのなら、 unlink() を試してください。 ローカルスコープから変数を削除する場合は、 unset() を参照ください。

参考

  • unlink() - ファイルを削除する
  • unset() - 指定した変数の割当を解除する


親ディレクトリのパスを返す

  • ≪ delete
  • disk_free_space ≫
  • PHP Manual
  • ファイルシステム 関数
  • 親ディレクトリのパスを返す

dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — 親ディレクトリのパスを返す

説明

dirname(string $path, int $levels = 1): string

ファイルあるいはディレクトリへのパスを含む文字列を受け取って、 カレントディレクトリから levels レベルさかのぼった親ディレクトリのパスを返します。

注意:

dirname() は、入力文字列を単純にそのまま処理します。 実際のファイルシステムを確認したり ".." のようなパスを気にしたりすることはありません。

警告

Windows では、dirname() は現在設定されているコードページに依存します。 よって、マルチバイト文字が含まれたパスを正しく表示するには、 それと一致するコードページが設定されていなければいけません。 現在のコードページから見て不正な文字が path に含まれていた場合、 basename() の動作は未定義です。

Windows 以外のシステムでは、 path はASCII と互換性があるエンコーディングでエンコードされていると想定されています。 そうでない場合、この関数の動作は未定義です。

パラメータ

path

パス。

Windows では、スラッシュ(/)とバックスラッシュ (\)の両方がディレクトリ区切り文字として使われます。 その他の環境ではスラッシュ(/)になります。

levels

親ディレクトリをどこまでさかのぼるか。

正の整数でなければいけません。

戻り値

親ディレクトリのパスを返します。 path にスラッシュが無い場合は、 カレントディレクトリを示すドット ('.') を返します。それ以外の場合は、スラッシュ以降の /component 部分を取り除いた path を返します。

警告

この関数をトップレベルディレクトリまで走査するループで使う場合は、 注意が必要です。なぜなら、無限ループに陥る可能性があるからです。

<?php
dirname('.'); // '.' を返します。
dirname('/'); // Windows では `\` を、*nix システムでは '/' を返します。
dirname('\\'); // Windows では `\` を、*nix システムでは '.' を返します。
dirname('C:\\'); // Windows では 'C:\' を、*nix システムでは '.' を返します。
?>

変更履歴

バージョン | 説明
7.0.0 | オプションのパラメータ levels が追加されました。

例

例1 dirname() の例

<?php
echo dirname("/etc/passwd") . PHP_EOL;
echo dirname("/etc/") . PHP_EOL;
echo dirname(".") . PHP_EOL;
echo dirname("C:\\") . PHP_EOL;
echo dirname("/usr/local/lib", 2);
?>

上の例の出力は、 たとえば以下のようになります。

/etc
/ (Windows の場合は \)
.
C:\
/usr

参考

  • basename() - パスの最後にある名前の部分を返す
  • pathinfo() - ファイルパスに関する情報を返す
  • realpath() - 正規化された絶対パス名を返す


ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

  • ≪ dirname
  • disk_total_space ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

説明

disk_free_space(string $directory): float|false

ディレクトリを指定することにより、 この関数は対応するファイルシステムまたはディスクパーティションで 利用可能なバイト数を返します。

パラメータ

directory

ファイルシステムのディレクトリあるいはディスクパーティション。

注意:

ディレクトリのかわりにファイル名を指定したときの挙動は未定義です。 OS や PHP のバージョンによって結果は異なります。

戻り値

利用可能なバイト数を float 型で返します。 失敗した場合に false を返します。

例

例1 disk_free_space() の例

<?php
// $df は「/」で利用可能なバイト数となります。
$df = disk_free_space("/");

// Windows の場合:
$df_c = disk_free_space("C:");
$df_d = disk_free_space("D:");
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

参考

  • disk_total_space() - ファイルシステムあるいはディスクパーティションの全体サイズを返す


ファイルシステムあるいはディスクパーティションの全体サイズを返す

  • ≪ disk_free_space
  • diskfreespace ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルシステムあるいはディスクパーティションの全体サイズを返す

disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す

説明

disk_total_space(string $directory): float|false

ディレクトリを含む文字列を指定してください。この関数は、 ファイルシステムまたはディスクパーティションに対応する全体バイト数を返します。

パラメータ

directory

ファイルシステムのディレクトリあるいはディスクパーティション。

戻り値

総バイト数を float 型で返します。 失敗した場合に false を返します。

例

例1 disk_total_space() の例

<?php
// $ds は、「/」で利用可能な全体バイト数
$ds = disk_total_space("/");

// Windows の場合:
$ds = disk_total_space("C:");
$ds = disk_total_space("D:");
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

参考

  • disk_free_space() - ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す


disk_free_space のエイリアス

  • ≪ disk_total_space
  • fclose ≫
  • PHP Manual
  • ファイルシステム 関数
  • disk_free_space のエイリアス

diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — disk_free_space() のエイリアス

説明

この関数は次の関数のエイリアスです。 disk_free_space().


オープンされたファイルポインタをクローズする

  • ≪ diskfreespace
  • fdatasync ≫
  • PHP Manual
  • ファイルシステム 関数
  • オープンされたファイルポインタをクローズする

fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — オープンされたファイルポインタをクローズする

説明

fclose(resource $stream): bool

streamが指しているファイルをクローズします。

パラメータ

stream

ファイルポインタは有効なものでなければならず、また fopen()またはfsockopen() で正常にオープンされたファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンプルな fclose() の例

<?php

$handle = fopen('somefile.txt', 'r');

fclose($handle);

?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする


データをファイルに同期する(但しメタデータは除く)

  • ≪ fclose
  • feof ≫
  • PHP Manual
  • ファイルシステム 関数
  • データをファイルに同期する(但しメタデータは除く)

fdatasync

(PHP 8 >= 8.1.0)

fdatasync — データをファイルに同期する(但しメタデータは除く)

説明

fdatasync(resource $stream): bool

この関数は、 stream の内容をストレージに同期します。 fsync() に似ていますが、ファイルのメタデータは同期しません。 この点だけが、POSIX システムで唯一異なることに注意して下さい。 Windows では、この関数は fsync() のエイリアスになっています。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fdatasync() の例

<?php

$file = 'test.txt';

$stream = fopen($file, 'w');
fwrite($stream, 'test data');
fwrite($stream, "\r\n");
fwrite($stream, 'additional data');

fdatasync($stream);
fclose($stream);
?>

参考

  • fflush() - 出力をファイルにフラッシュする
  • fsync() - データをファイルに同期する(メタデータも含む)


ファイルポインタがファイル終端に達しているかどうか調べる

  • ≪ fdatasync
  • fflush ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタがファイル終端に達しているかどうか調べる

feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — ファイルポインタがファイル終端に達しているかどうか調べる

説明

feof(resource $stream): bool

ファイルポインタがファイル終端に達しているかどうかを調べます。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

戻り値

ファイルポインタが EOF に達しているかまたはエラー (ソケットタイムアウトを含みます) の場合に true 、 その他の場合に false を返します。

注意

警告

fsockopen() でオープンした接続がサーバーによって閉じられていない場合、feof() はハングします。回避策は以下の例を参照ください。

例1 feof() のタイムアウト処理

<?php
function safe_feof($fp, &$start = NULL) {
$start = microtime(true);

return feof($fp);
}

/* $fp は事前に fsockopen() でオープンしているものとします */

$start = NULL;
$timeout = ini_get('default_socket_timeout');

while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
{
/* 処理 */
}
?>

警告

無効なファイルポインタを渡した場合、無限ループに陥ることがあります。 なぜなら feof() が true を返すことができないからです。

例2 feof() に無効なファイルポインタを使用する例

<?php
// ファイルを読み込めなかったりファイルが存在しなかったりした場合、
// fopen 関数は FALSE を返します。
$file = @fopen("no_such_file", "r");

// fopen からの FALSE が警告を発生させ、ここで無限ループとなります。
while (!feof($file)) {
}

fclose($file);
?>


出力をファイルにフラッシュする

  • ≪ feof
  • fgetc ≫
  • PHP Manual
  • ファイルシステム 関数
  • 出力をファイルにフラッシュする

fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — 出力をファイルにフラッシュする

説明

fflush(resource $stream): bool

この関数は、バッファリングされた全ての出力をファイルハンドル stream が指すリソースに強制的に書き込みます。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fflush() を使用するファイル書き込みの例

<?php
$filename = 'bar.txt';

$file = fopen($filename, 'r+');
rewind($file);
fwrite($file, 'Foo');
fflush($file);
ftruncate($file, ftell($file));
fclose($file);
?>

参考

  • clearstatcache() - ファイルのステータスのキャッシュをクリアする
  • fwrite() - バイナリセーフなファイル書き込み処理


ファイルポインタから1文字取り出す

  • ≪ fflush
  • fgetcsv ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから1文字取り出す

fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — ファイルポインタから1文字取り出す

説明

fgetc(resource $stream): string|false

指定したファイルポインタから 1 文字読み出します。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

戻り値

streamが指すファイルポインタから 1 文字読み出し、 その文字からなる文字列を返します。EOF の場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 fgetc() の例

<?php
$fp = fopen('somefile.txt', 'r');
if (!$fp) {
echo 'somefile.txt をオープンできませんでした';
}
while (false !== ($char = fgetc($fp))) {
echo "$char\n";
}
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • fgets() - ファイルポインタから 1 行取得する


ファイルポインタから行を取得し、CSVフィールドを処理する

  • ≪ fgetc
  • fgets ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから行を取得し、CSVフィールドを処理する

fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する

説明

fgetcsv(
resource $stream,
?int $length = null,
string $separator = ",",
string $enclosure = "\"",
string $escape = "\\"
): array|false

fgets() に動作は似ていますが、 fgetcsv() は行を CSV フォーマットのフィールドとして読込み処理を行い、 読み込んだフィールドを含む配列を返すという違いがあります。

注意:

この関数はロケール設定を考慮します。もし LC_CTYPE が例えば en_US.UTF-8 の場合、 1 バイトエンコーディングのファイルは間違って読み込まれるかもしれません。

パラメータ

stream

ファイルポインタは有効なものでなければならず、また fopen(), popen(), もしくは fsockopen() で正常にオープンされたファイルを指している必要があります。

length

(行末文字を考慮して) CSV ファイルにある最も長い行よりも大きい必要があります。 そうでない場合は、ひとつの行が length 文字ずつのチャンクに分割されてしまいます。 ただし、フィールド囲いこみ文字の内部では、この分割は発生しません。

このパラメータを省略 (もしくは 0 を設定、 PHP 8.0.0 以降では null を設定) すると、 最大行長は制限されません。この場合、若干動作が遅くなります。

separator

オプションの separator パラメータで、フィールドのデリミタ (シングルバイト文字 1 文字のみ) を設定します。

enclosure

オプションの enclosure パラメータで、フィールド囲いこみ文字 (シングルバイト文字 1 文字のみ) を設定します。

escape

オプションの escape パラメータで、エスケープ文字 (シングルバイト文字 最大で1文字) を設定します。 空文字列("") を指定すると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

注意: enclosure の文字は、フィールド内で2回出力される ことでエスケープされます。しかし、 escape 文字はその代替として使えます。 デフォルトのパラメータの値 "" と \" は同じ意味を持ちます。 enclosure の文字を escape 文字でエスケープすることには、 特別な意味はありません。それ自身をエスケープする意味ですらありません。

戻り値

読み込んだフィールドの内容を含む数値添字配列を返します。 失敗した場合に false を返します

注意:

CSV ファイルの空行は null フィールドを一つだけ含む配列として返され、 エラーにはなりません。

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。
7.4.0 | escape パラメータが空文字列を受け入れるようになりました。 この場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

例

例1 CSV ファイルの全てのコンテンツを読み込み、表示する

<?php
$row = 1;
if (($handle = fopen("test.csv", "r")) !== FALSE) {
while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
$num = count($data);
echo "<p> $num fields in line $row: <br /></p>\n";
$row++;
for ($c=0; $c < $num; $c++) {
echo $data[$c] . "<br />\n";
}
}
fclose($handle);
}
?>

参考

  • str_getcsv() - CSV 文字列をパースして配列に格納する
  • explode() - 文字列を文字列により分割する
  • file() - ファイル全体を読み込んで配列に格納する
  • pack() - データをバイナリ文字列にパックする
  • fputcsv() - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む


ファイルポインタから 1 行取得する

  • ≪ fgetcsv
  • fgetss ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから 1 行取得する

fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — ファイルポインタから 1 行取得する

説明

fgets(resource $stream, ?int $length = null): string|false

ファイルポインタから 1 行取得します。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

length

読み出しは、length - 1 バイト読み出したか、(戻り値に含まれる) 改行文字を検出したか、EOF に達したかのいずれかが起こった時点で終了します。 length が指定されない場合は、行末に達するまで読み続けます。

戻り値

stream で指定したファイルポインタから最大 length - 1 バイト読み出し、 その文字列を返します。ファイルポインタから読み込むデータがもうない場合は false を返します。

エラーが起こった場合、false を返します。

例

例1 行毎にファイルを読み込む

<?php

$fp = @fopen("/tmp/inputfile.txt", "r");

if ($fp) {
while (($buffer = fgets($fp, 4096)) !== false) {
echo $buffer, PHP_EOL;
}

if (!feof($fp)) {
echo "Error: unexpected fgets() fail\n";
}

fclose($fp);
}

?>

注意

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

注意:

C 言語の fgets() の動作に慣れている人は、 EOF を返す条件の違いについて注意する必要があります。

参考

  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fread() - バイナリセーフなファイルの読み込み
  • fgetc() - ファイルポインタから1文字取り出す
  • stream_get_line() - 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む
  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • stream_set_timeout() - ストリームにタイムアウトを設定する


ファイルポインタから 1 行取り出し、HTML タグを取り除く

  • ≪ fgets
  • file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタから 1 行取り出し、HTML タグを取り除く

fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

fgetss(resource $handle, int $length = ?, string $allowable_tags = ?): string

fgets() と同じですが、 fgetss() は読み込んだテキストから NUL バイト や HTML および PHP のタグを取り除こうとすることが異なります。 この関数は、ある呼び出しから別の呼び出しの間のパースの状態を保持します。 したがって、これは fgets() の戻り値に対して strip_tags() 関数を呼び出すのと同じではありません。

パラメータ

handle

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

length

取得したいデータの長さ。

allowable_tags

オプションの 3 番目の引数を使用して、 取り除く必要がないタグを指定することができます。 allowable_tags について詳しくは strip_tags() を参照ください。

戻り値

handle で指定したファイルポインタから最大 length - 1 バイト読み出し、 HTML や PHP コードを取り除いた文字列を返します。

エラーが発生した場合は false を返します。

例

例1 PHP ファイルの 1 行ごとの読み込み

<?php
$str = <<<EOD
<html><body>
<p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
</body></html>
Text outside of the HTML block.
EOD;
file_put_contents('sample.php', $str);

$handle = @fopen("sample.php", "r");
if ($handle) {
while (!feof($handle)) {
$buffer = fgetss($handle, 4096);
echo $buffer;
}
fclose($handle);
}
?>

上の例の出力は、 たとえば以下のようになります。

Welcome! Today is the  of .

Text outside of the HTML block.

注意

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

参考

  • fgets() - ファイルポインタから 1 行取得する
  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • strip_tags() - 文字列から HTML および PHP タグを取り除く
  • SplFileObject::fgetss() - ファイルから 1 行取り出し HTML タグを取り除く
  • The string.strip_tags filter


ファイル全体を読み込んで配列に格納する

  • ≪ fgetss
  • file_exists ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイル全体を読み込んで配列に格納する

file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — ファイル全体を読み込んで配列に格納する

説明

file(string $filename, int $flags = 0, ?resource $context = null): array|false

ファイル全体を配列に読み込みます。

注意:

ファイルの内容を文字列として返すには file_get_contents() を使用します。

パラメータ

filename

ファイルへのパス。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

flags

オプションのパラメータ flags は、以下の定数のうちのひとつ、あるいは複数の組み合わせとなります。

FILE_USE_INCLUDE_PATH
include_path のファイルを探します。
FILE_IGNORE_NEW_LINES
配列の各要素の最後の改行を省略します。
FILE_SKIP_EMPTY_LINES
空行を読み飛ばします。
FILE_NO_DEFAULT_CONTEXT
デフォルトのストリームコンテキストを使いません。

context

ストリームコンテキストリソース

戻り値

ファイルを配列に入れて返します。 配列の各要素はファイルの各行に対応します。改行記号はついたままとなります。 失敗すると file() は false を返します。

注意:

FILE_IGNORE_NEW_LINES を指定しない限り、 配列に取り込まれた各行は行末文字も含みます。

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

エラー / 例外

ファイルが存在しない場合は E_WARNING レベルのエラーが発生します。

例

例1 file() の例

<?php
// ファイルの内容を配列に取り込みます。
// この例ではHTTPを通してURL上のHTMLソースを取得します。
$lines = file('http://www.example.com/');

// 配列をループしてHTMLをHTMLソースとして表示し、行番号もつけます。
foreach ($lines as $line_num => $line) {
echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
}

// オプションのパラメータを使う
$trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
?>

注意

警告

IIS のような、いくつかの標準に 対応してない Web サーバーは、PHP に警告を発生させるような手順でデータを送信します。 このようなサーバーを使用する場合は、 error_reporting を警告を発生しないレベルまで小さくする必要があります。 PHP では、https:// ラッパーでストリームをオープンする際に バグがある IIS サーバーソフトウエアを検出することができ、この警告を抑制することができます。 あなたが ssl:// ソケットを作成するために fsockopen() を使用している場合、 自らこの警告を検出し、抑制する必要があります。

参考

  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • readfile() - ファイルを出力する
  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • include - include
  • stream_context_create() - ストリームコンテキストを作成する


ファイルまたはディレクトリが存在するかどうか調べる

  • ≪ file
  • file_get_contents ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルまたはディレクトリが存在するかどうか調べる

file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — ファイルまたはディレクトリが存在するかどうか調べる

説明

file_exists(string $filename): bool

ファイルあるいはディレクトリが存在するかどうかを調べます。

パラメータ

filename

ファイルあるいはディレクトリへのパス。

Windows 上でネットワーク共有上のファイルを調べるには、 //computername/share/filename または \\computername\share\filename のように指定してください。

戻り値

filename で指定したファイルまたはディレクトリが存在すれば true を返し、そうでなければ false を返します。

注意:

この関数は、シンボリックリンクの指す先のファイルが存在しない場合は false を返します。

注意:

チェックは、実効ユーザーではなく実ユーザーの UID/GID で行います。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 あるファイルが存在するかどうか調べる

<?php
$filename = '/path/to/foo.txt';

if (file_exists($filename)) {
echo "$filename が存在します";
} else {
echo "$filename は存在しません";
}
?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • is_writable() - ファイルが書き込み可能かどうかを調べる
  • is_file() - 通常ファイルかどうかを調べる
  • file() - ファイル全体を読み込んで配列に格納する
  • SplFileInfo


ファイルの内容を全て文字列に読み込む

  • ≪ file_exists
  • file_put_contents ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの内容を全て文字列に読み込む

file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — ファイルの内容を全て文字列に読み込む

説明

file_get_contents(
string $filename,
bool $use_include_path = false,
?resource $context = null,
int $offset = 0,
?int $length = null
): string|false

この関数は file() と似ていますが、 offset で指定した場所から開始し length バイト分だけ ファイルの内容を文字列に読み込むという点が異なります。 失敗した場合、file_get_contents() は false を返します。

file_get_contents()はファイルの内容を文字列に読み込む 方法として好ましいものです。もしOSがサポートしていれば パフォーマンス向上のためにメモリマッピング技術が使用されます。

注意:

空白のような特殊な文字を有する URI をオープンする場合には、 urlencode() でその URI をエンコードする必要があります。

パラメータ

filename

データを読み込みたいファイルの名前。

use_include_path

注意:

定数 FILE_USE_INCLUDE_PATH を使用して インクルードパス から探すことができます。 この定数を使うことは、強い型付け が有効になっている場合は不可能です。なぜなら、 FILE_USE_INCLUDE_PATH が int だからです。 true を代わりに使いましょう。

context

stream_context_create() で作成したコンテキストリソース。 独自のコンテキストを使用する必要がない場合は、このパラメータに null を指定します。

offset

元のストリーム上で、読み込みを開始するオフセット位置。 負のオフセットは、ストリームの末尾からのオフセットと解釈されます。

リモートファイルに対するシーク (offset 指定) はサポートしていません。 オフセットが小さい場合はリモートファイルでのシークがうまくいくこともありますが、 これはバッファリングされたストリーム上で動作しているだけのことです。

length

読み込むデータの最大バイト数。 デフォルトは、ファイル終端に達するまで読み込みます。 このパラメータは、フィルタが処理した後のストリームに適用されることに注意しましょう。

戻り値

読み込んだデータを返します。失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

エラー / 例外

filename が見つからない場合、length がゼロより小さい場合、あるいはストリーム内での指定した offset へのシークが失敗した場合に E_WARNING レベルのエラーが発生します。

file_get_contents() 関数がディレクトリに対して呼び出されると、 Windows では E_WARNING レベルのエラーが発生していました。 PHP 7.4 以降では、Windows 以外のオペレーティングシステムでも同じ動きになっています。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。
7.1.0 | 負の offset をサポートするようになりました。

例

例1 とあるウェブサイトのホームページのソースの取得と出力

<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>

例2 include_path の検索

<?php
// 厳密な型検査が有効な場合。つまり、declare(strict_types=1) の場合
$file = file_get_contents('./people.txt', true);
// 厳密な型検査が有効でない場合
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>

例3 ファイルの一部の読み込み

<?php
// 21 文字目から 14 文字ぶん読み込みます
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($section);
?>

上の例の出力は、 たとえば以下のようになります。

string(14) "lle Bjori Ro"

例4 ストリームコンテキストの使用

<?php
// ストリームを作成します
$opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar\r\n"
)
);

$context = stream_context_create($opts);

// 上で設定した HTTP ヘッダを使用してファイルをオープンします
$file = file_get_contents('http://www.example.com/', false, $context);
?>

注意

注意: この関数はバイナリデータに対応しています。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

警告

IIS のような、いくつかの標準に 対応してない Web サーバーは、PHP に警告を発生させるような手順でデータを送信します。 このようなサーバーを使用する場合は、 error_reporting を警告を発生しないレベルまで小さくする必要があります。 PHP では、https:// ラッパーでストリームをオープンする際に バグがある IIS サーバーソフトウエアを検出することができ、この警告を抑制することができます。 あなたが ssl:// ソケットを作成するために fsockopen() を使用している場合、 自らこの警告を検出し、抑制する必要があります。

参考

  • file() - ファイル全体を読み込んで配列に格納する
  • fgets() - ファイルポインタから 1 行取得する
  • fread() - バイナリセーフなファイルの読み込み
  • readfile() - ファイルを出力する
  • file_put_contents() - データをファイルに書き込む
  • stream_get_contents() - 残りのストリームを文字列に読み込む
  • stream_context_create() - ストリームコンテキストを作成する
  • $http_response_header


データをファイルに書き込む

  • ≪ file_get_contents
  • fileatime ≫
  • PHP Manual
  • ファイルシステム 関数
  • データをファイルに書き込む

file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — データをファイルに書き込む

説明

file_put_contents(
string $filename,
mixed $data,
int $flags = 0,
?resource $context = null
): int|false

この関数は、fopen()、fwrite()、 fclose() を続けてコールしてデータをファイルに書き込むのと等価です。

filename が存在しない場合はファイルを作成します。 存在する場合はそのファイルを上書きします。ただし FILE_APPEND フラグが設定されている場合は別です。

パラメータ

filename

データを書き込むファイルへのパス。

data

書き込むデータ。文字列, 配列 もしくは ストリーム リソースのいずれかを指定可能です。

data が ストリーム リソースの場合は、 ストリームのバッファに残っている内容が指定したファイルにコピーされます。 これは、stream_copy_to_stream() の挙動と似ています。

data に一次元の配列を指定することもできます。この場合は file_put_contents($filename, implode('', $array)) と同じ意味になります。

flags

flags の値は、以下のフラグを組み合わせたものとなります 組み合わせる際には、論理 OR (|) 演算子で連結します。

使用できるフラグ
フラグ | 説明
FILE_USE_INCLUDE_PATH | filename をインクルードディレクトリから探します。 詳細な情報は include_path を参照ください。
FILE_APPEND | filename がすでに存在する場合に、 データをファイルに上書きするするのではなく追記します。
LOCK_EX | 書き込み処理中に、ファイルに対する排他ロックを確保します。 つまり、fopen() の呼び出しから fwrite() の呼び出しまでの間に flock() の呼び出しが発生するということです。 これは、モード "x" で fopen() を呼び出すことと同等ではありません。

context

stream_context_create() で作成したコンテキストリソース。

戻り値

この関数はファイルに書き込まれたバイト数を返します。 あるいは失敗した場合には false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 シンプルな使用例

<?php
$file = 'people.txt';
// ファイルをオープンして既存のコンテンツを取得します
$current = file_get_contents($file);
// 新しい人物をファイルに追加します
$current .= "John Smith\n";
// 結果をファイルに書き出します
file_put_contents($file, $current);
?>

例2 フラグの使用

<?php
$file = 'people.txt';
// 新しい人物をファイルに追加します
$person = "John Smith\n";
// 中身をファイルに書き出します。
// FILE_APPEND フラグはファイルの最後に追記することを表し、
// LOCK_EX フラグは他の人が同時にファイルに書き込めないことを表します。
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>

注意

注意: この関数はバイナリデータに対応しています。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

参考

  • fopen() - ファイルまたは URL をオープンする
  • fwrite() - バイナリセーフなファイル書き込み処理
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • stream_context_create() - ストリームコンテキストを作成する


ファイルの最終アクセス時刻を取得する

  • ≪ file_put_contents
  • filectime ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの最終アクセス時刻を取得する

fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — ファイルの最終アクセス時刻を取得する

説明

fileatime(string $filename): int|false

指定したファイルの最終アクセス時刻を取得します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルの最終アクセス時刻を返し、失敗した場合に false を返します。 時間は Unix タイムスタンプとして返されます。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 fileatime() の例

<?php

// 出力例 somefile.txt was last accessed: December 29 2002 22:16:23.

$filename = 'somefile.txt';
if (file_exists($filename)) {
echo "$filename was last accessed: " . date("F d Y H:i:s.", fileatime($filename));
}

?>

注意

注意:

ファイルの atime は、 ファイルのデータブロックが読み込まれる度に変更されるとみなされます。 この仕様は、アプリケーションが非常に多くのファイルまたはディレクトリに 常にアクセスする場合に性能上の負荷となる可能性があります。

Unix のファイルシステムの中には、 このようなアプリケーションの性能を向上させるために atime の更新を無効としてマウントできるものもあります。 USENET のニューススプールが一般的な例です。 このようなファイルシステムでは、この関数は使用できません。

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filemtime() - ファイルの更新時刻を取得する
  • fileinode() - ファイルの inode を取得する
  • date() - Unixタイムスタンプを書式化する


ファイルの inode 変更時刻を取得する

  • ≪ fileatime
  • filegroup ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの inode 変更時刻を取得する

filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — ファイルの inode 変更時刻を取得する

説明

filectime(string $filename): int|false

ファイルの inode 変更時刻を取得します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルの最終更新時刻を返し、失敗した場合に false を返します。 時間は Unix タイムスタンプとして返されます。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 filectime() の例

<?php

// 出力例 somefile.txt was last changed: December 29 2002 22:16:23.

$filename = 'somefile.txt';
if (file_exists($filename)) {
echo "$filename was last changed: " . date("F d Y H:i:s.", filectime($filename));
}

?>

注意

注意:

注意: 多くの Unix ファイルシステムでは、i-ノードが変更された際、つまり、 パーミッション、所有者、グループ、または他のメタデータが書き込まれた際に、 ファイルが変更されたとみなされます。 filemtime() (この関数は、Web ページ上に "最終更新時刻" を表示させたい場合に使用するものです) および fileatime() も参照ください。

注意:

いくつかの Unix では、ファイルの ctime はファイルの作成時間として参照されます。 これは間違っています。多くの Unix ファイルシステムでは Unix ファイルの作成時間は存在しません。

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filemtime() - ファイルの更新時刻を取得する


ファイルのグループを取得する

  • ≪ filectime
  • fileinode ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのグループを取得する

filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — ファイルのグループを取得する

説明

filegroup(string $filename): int|false

ファイルのグループを取得します。戻り値は、数値形式のグループ ID です。 グループ名を取得するには posix_getgrgid() を使用します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルの所有者のグループ ID を返し、エラーの場合は false を返します。 グループ ID は数値で返されます。グループ名に変換するには posix_getgrgid() を使用してください。 失敗すると false を返します。

エラー / 例外

失敗時には E_WARNING レベルのエラーを発行します。

例

例1 ファイルのグループの取得

<?php
$filename = 'index.php';
print_r(posix_getgrgid(filegroup($filename)));
?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • fileowner() - ファイルの所有者を取得する
  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す


ファイルの inode を取得する

  • ≪ filegroup
  • filemtime ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの inode を取得する

fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — ファイルの inode を取得する

説明

fileinode(string $filename): int|false

ファイルの inode を取得します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルの inode 番号を返し、失敗した場合に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 現在のファイルとのファイルの inode の比較

<?php
$filename = 'index.php';
if (getmyinode() == fileinode($filename)) {
echo 'You are checking the current file.';
}
?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • getmyinode() - 現在のスクリプトの inode を取得する
  • stat() - ファイルに関する情報を取得する


ファイルの更新時刻を取得する

  • ≪ fileinode
  • fileowner ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの更新時刻を取得する

filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — ファイルの更新時刻を取得する

説明

filemtime(string $filename): int|false

この関数は、ファイルのブロックデータが書き込まれた時間を返します。 これは、ファイルの内容が変更された際の時間です。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルの最終更新時刻を返し、失敗した場合に false を返します。 時間は Unix タイムスタンプとして返されます。 この関数の結果は date() 等で使用できます。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 filemtime() の例

<?php
// 出力例 somefile.txt was last modified: December 29 2002 22:16:23.

$filename = 'somefile.txt';
if (file_exists($filename)) {
echo "$filename was last modified: " . date ("F d Y H:i:s.", filemtime($filename));
}
?>

注意

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filectime() - ファイルの inode 変更時刻を取得する
  • stat() - ファイルに関する情報を取得する
  • touch() - ファイルの最終アクセス時刻および最終更新日をセットする
  • getlastmod() - 最終更新時刻を取得する


ファイルの所有者を取得する

  • ≪ filemtime
  • fileperms ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの所有者を取得する

fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — ファイルの所有者を取得する

説明

fileowner(string $filename): int|false

ファイルの所有者を取得します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルの所有者のユーザー ID を返し、失敗した場合に false を返します。 ユーザー ID は数値で返されます。ユーザー名に変換するには posix_getpwuid() を使用してください。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 ファイルの所有者の取得

<?php
$filename = 'index.php';
print_r(posix_getpwuid(fileowner($filename)));
?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • filegroup() - ファイルのグループを取得する
  • stat() - ファイルに関する情報を取得する
  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す


ファイルのパーミッションを取得する

  • ≪ fileowner
  • filesize ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのパーミッションを取得する

fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — ファイルのパーミッションを取得する

説明

fileperms(string $filename): int|false

指定したファイルのパーミッションを取得します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルのパーミッションを数値モードで返します。このモードの下位ビットは chmod() に渡すのと同じ形式です。 しかし、大半のプラットフォームでは、それだけではなく filename のファイル形式に関する情報も含まれます。 以下の例で示すのは、ファイルのパーミッションやファイル形式を POSIX システム (Linux や macOS など) で調べる方法です。

ローカルファイルの場合、その戻り値は C ライブラリ関数 stat() が返す構造体の st_mode メンバーの値となります。 どのビットがセットされるかはプラットフォームによって異なるので、 パーミッション部分以外のビットをパースしたい場合は各プラットフォームのドキュメントを参照することをおすすめします。

失敗時に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 八進形式でのパーミッションの表示

<?php
echo substr(sprintf('%o', fileperms('/tmp')), -4);
echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
?>

上の例の出力は以下となります。

1777
0644

例2 完全なパーミッションの表示

<?php
$perms = fileperms('/etc/passwd');

switch ($perms & 0xF000) {
case 0xC000: // ソケット
$info = 's';
break;
case 0xA000: // シンボリックリンク
$info = 'l';
break;
case 0x8000: // 通常のファイル
$info = 'r';
break;
case 0x6000: // ブロックスペシャルファイル
$info = 'b';
break;
case 0x4000: // ディレクトリ
$info = 'd';
break;
case 0x2000: // キャラクタスペシャルファイル
$info = 'c';
break;
case 0x1000: // FIFO パイプ
$info = 'p';
break;
default: // 不明
$info = 'u';
}

// 所有者
$info .= (($perms & 0x0100) ? 'r' : '-');
$info .= (($perms & 0x0080) ? 'w' : '-');
$info .= (($perms & 0x0040) ?
(($perms & 0x0800) ? 's' : 'x' ) :
(($perms & 0x0800) ? 'S' : '-'));

// グループ
$info .= (($perms & 0x0020) ? 'r' : '-');
$info .= (($perms & 0x0010) ? 'w' : '-');
$info .= (($perms & 0x0008) ?
(($perms & 0x0400) ? 's' : 'x' ) :
(($perms & 0x0400) ? 'S' : '-'));

// 全体
$info .= (($perms & 0x0004) ? 'r' : '-');
$info .= (($perms & 0x0002) ? 'w' : '-');
$info .= (($perms & 0x0001) ?
(($perms & 0x0200) ? 't' : 'x' ) :
(($perms & 0x0200) ? 'T' : '-'));

echo $info;
?>

上の例の出力は以下となります。

-rw-r--r--

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • chmod() - ファイルのモードを変更する
  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • stat() - ファイルに関する情報を取得する


ファイルのサイズを取得する

  • ≪ fileperms
  • filetype ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルのサイズを取得する

filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — ファイルのサイズを取得する

説明

filesize(string $filename): int|false

指定したファイルのサイズを取得します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルのサイズを返し、エラーの場合は false を返します (また E_WARNING レベルのエラーを発生させます) 。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 filesize() の例

<?php

// 出力例 somefile.txt: 1024 bytes

$filename = 'somefile.txt';
echo $filename . ': ' . filesize($filename) . ' bytes';

?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる


ファイルタイプを取得する

  • ≪ filesize
  • flock ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルタイプを取得する

filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — ファイルタイプを取得する

説明

filetype(string $filename): string|false

指定したファイルのタイプを返します。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルのタイプを返します。返される値は fifo、char、dir、 block、link、file、socket および unknown のいずれかです。

エラーが発生すると false を返します。 また filetype() は stat コールに失敗したり、 未知のファイルタイプであったりした場合に E_NOTICE メッセージを発行します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 filetype() の例

<?php

echo filetype('/etc/passwd');
echo "\n";
echo filetype('/etc/');

?>

上の例の出力は以下となります。

file
dir

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • is_file() - 通常ファイルかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • mime_content_type() - ファイルの MIME Content-type を検出する
  • pathinfo() - ファイルパスに関する情報を返す
  • stat() - ファイルに関する情報を取得する


汎用のファイルロックを行う

  • ≪ filetype
  • fnmatch ≫
  • PHP Manual
  • ファイルシステム 関数
  • 汎用のファイルロックを行う

flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — 汎用のファイルロックを行う

説明

flock(resource $stream, int $operation, int &$would_block = null): bool

flock() を使うと、(ほとんどの Unix、そして Windows さえ含む) 事実上すべてのプラットフォームで使用可能な、簡易な読み手/書き手モデルを実現できます。

ロックの解放は、fclose() が実行されるか、 stream がガベージコレクションされた段階で行われます。

PHP は、恣意的にファイルをロックする汎用の手段を提供します (これは、アクセスする全プログラムが同一のロックの方法を使用する必要があり、 そうでない場合は動作しないことを意味します)。 デフォルトでは、要求したロックが確保されるまでこの関数はブロックします。 以下で説明する LOCK_NB オプションでこの挙動を制御することができます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

operation

operation は以下のいずれかとなります。

  • 共有ロック(読み手)とするには LOCK_SH をセットします。
  • 排他的ロック(書き手)とするには LOCK_EX をセットします。
  • (共有または排他的)ロックを開放するには LOCK_UN をセットします。

ロックを試みている間に flock() がブロックすべきでない場合は、上の操作のいずれかに LOCK_NB をビットマスクとして追加できます。

would_block

ロックがブロックされた (errno が EWOULDBLOCK となった) 場合に、オプションの 3 番目の引数に 1 が設定されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 flock() の例

<?php

$fp = fopen("/tmp/lock.txt", "r+");

if (flock($fp, LOCK_EX)) { // 排他ロックを確保します
ftruncate($fp, 0); // ファイルを切り詰めます
fwrite($fp, "ここで何かを書きます\n");
fflush($fp); // 出力をフラッシュしてからロックを解放します
flock($fp, LOCK_UN); // ロックを解放します
} else {
echo "ファイルを取得できません!";
}

fclose($fp);

?>

例2 flock() で LOCK_NB オプションを使う例

<?php
$fp = fopen('/tmp/lock.txt', 'r+');

/* LOCK_NB オプションを LOCK_EX で有効にします */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
echo 'Unable to obtain lock';
exit(-1);
}

/* ... */

fclose($fp);
?>

注意

注意:

flock() は、Windows 上ではアドバイザリロックではなく 強制ロックを使います。強制ロックは Linux や System V 系の OS でもサポートされています。 これは、そのファイルに setgid パーミッションが設定されていて グループの実行ビットがクリアされている場合に fcntl() システムコールが通常サポートしている方式です。 Linux では、これを行うには mand オプションつきでファイルシステムをマウントしておく必要があります。

注意:

flock()は、ファイルポインタを必要とするため、 (fopen()へ引数"w"または"w+"を指定して)書き込 みモードでオープンすることにより丸めるファイルにアクセス保護する 特別なロックファイルを使用する必要があるかもしれません。

注意:

fopen() が返すローカルファイルへのポインタ、あるいは streamWrapper::stream_lock() メソッドを実装した ユーザー空間のストリームを指すファイルポインタに対してのみ使うことができます。

警告

一連のコードで別の値を stream 引数に代入すると、 それ以降のコードでロックを解放します。

警告

いくつかのオーペレーティングシステムでflock() はプロセスレベルで実装されています。マルチスレッド 型のサーバーAPIを使用している場合、同じサーバーインスタンスの並 列スレッドで実行されている他のPHPスクリプトに対してファイルを保 護する際に flock()を使用することはできません!

flock()はFATのような 旧式のファイルシステムではサポートされていないため、 これらの環境の場合は常にfalseを返すことになります。

注意:

Windows では、 ロックするプロセスが同じファイルを二回オープンする場合、 ファイルをアンロックするまで二番目のハンドルではアクセスできません。


ファイル名がパターンにマッチするか調べる

  • ≪ flock
  • fopen ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイル名がパターンにマッチするか調べる

fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — ファイル名がパターンにマッチするか調べる

説明

fnmatch(string $pattern, string $filename, int $flags = 0): bool

fnmatch()はfilename で指定された文字列が pattern で指定されたシェルワイルドカードにマッチするかどうかチェックします。

パラメータ

pattern

マッチさせるパターン。 通常、pattern には '?' や '*' のようなワイルドカードを含めます。

pattern で使えるワイルドカード
ワイルドカード 説明
? クエスチョンマークは、1文字にマッチします。 たとえば、 "file?.txt" は "file1.txt" や "fileA.txt" にはマッチしますが、 "file10.txt" にはマッチしません。
* アスタリスクは、0文字以上の文字にマッチします。 たとえば、 "foo*.xml" は "foo.xml" や "foobar.xml" にマッチします。
[ ] 角括弧は、アスキー文字のコードポイントや、 文字の集合を表すのに使います。 たとえば、"index.php[45]" は "index.php4" や "index.php5" にマッチしますが、 "index.phpt" にはマッチしません。 よく知られている文字の範囲として [0-9], [a-z], [A-Z] が挙げられます。 複数の集合や範囲は、同時に使うことができます。 たとえば [0-9a-zABC] のように使えます。
! エクスクラメーションマークは、 角括弧内の文字を否定するのに使います。 たとえば、"[!A-Z]*.html" は "demo.html" にマッチしますが、 "Demo.html" にはマッチしません。
\ バックスラッシュは、特別な文字をエスケープするのに使います。 たとえば、"Name\?" は "Name?" にマッチしますが、 "Names" にはマッチしません。

filename

調べたい文字列。この機能は特にファイル名のマッチに便利ですが、 通常の文字列に関しても使用できます。

一般的なユーザーにとって、シェルパターンやあるいは少なくとも '?'と'*'によるワイルドカードのほうが 慣れていると思われます。そのため、 preg_match() の代わりに fnmatch() をフロントエンドの検索表現として使うことは、 プログラマではないユーザーにとってより便利でしょう。

flags

flags の値は、以下のフラグを 論理 OR (|) 演算子 で連結した任意の組み合わせです。

fnmatch() で使えるフラグ
フラグ | 説明
FNM_NOESCAPE | バックスラッシュのエスケープを無効にする。
FNM_PATHNAME | 文字列内のスラッシュは、指定したパターン内のスラッシュにのみマッチする。
FNM_PERIOD | 文字列の先頭のピリオドは、指定したパターン内のピリオドにマッチしなければならない。
FNM_CASEFOLD | 大文字小文字を区別しないマッチ。GNU 拡張の一部。

戻り値

マッチした場合に true、それ以外の場合に false を返します。

例

例1 シェルのワイルドカードパターンによる色の名前のチェック

<?php
if (fnmatch("*gr[ae]y", $color)) {
echo "some form of gray ...";
}
?>

注意

警告

今のところ、この機能は POSIX に準拠していないシステムで利用できません (ただし、Windows では利用できます)。

参考

  • glob() - パターンにマッチするパス名を探す
  • preg_match() - 正規表現によるマッチングを行う
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す


ファイルまたは URL をオープンする

  • ≪ fnmatch
  • fpassthru ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルまたは URL をオープンする

fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — ファイルまたは URL をオープンする

説明

fopen(
string $filename,
string $mode,
bool $use_include_path = false,
?resource $context = null
): resource|false

fopen() は、filename で指定されたリソースをストリームに結び付けます。

パラメータ

filename

filename が "スキーム://..." の形式である場合、 それは URL とみなされ、PHP はそのプロトコルのハンドラ (ラッパーともいいます) を探します。 もしもそのプロトコルに対するラッパーが登録されていない場合、 PHP はスクリプトに潜在的な問題があることを示す NOTICE を発行したうえで、 filename を通常のファイルとみなしてオープンすることを試みます。

PHP は、filename がローカルのファイルを示しているとみなすと、 そのファイルへのストリームをオープンします。 そのファイルはPHPからアクセスできるものでなければなりません。 ファイルのパーミッションが (パラメータで指定された) アクセスを許可されているかどうか確認する必要があります。 open_basedir を有効にしている場合は、更なるアクセス制限が加えられることがあります。

filename が登録されているプロトコルを示していると PHP が判断し、かつそのプロトコルがネットワーク URL として登録されていれば、 PHP は allow_url_fopen が有効となっているかどうかチェックします。 もしこれがオフになっていると、PHP は warning を発行し fopen() は失敗します。

注意:

サポートされているプロトコルのリストは サポートするプロトコル/ラッパー にあります。 いくつかのプロトコル (wrappersにも関連する) は context かつ/または php.ini のオプションをサポートします。 使用するプロトコルについてセットされるオプションのリストについては、 それぞれのページを見てください (例えば、 php.ini 上の user_agent の値は http ラッパーが使用します)。

Windows 環境では、ファイルパスで用いる全てのバックスラッシュを エスケープするかフォワードスラッシュを使用することに注意してください。

<?php
$handle = fopen("c:\\folder\\resource.txt", "r");
?>

mode

パラメータ mode は、 そのストリームに要するアクセス形式を指定します。 この指定は、下表のうちのどれかとなります。

fopen() で使用可能な mode のリスト
mode | 説明
'r' | 読み込みのみでオープンします。ファイルポインタをファイルの先頭に置きます。
'r+' | 読み込み／書き出し用にオープンします。 ファイルポインタをファイルの先頭に置きます。
'w' | 書き出しのみでオープンします。ファイルポインタをファイルの先頭に置き、 ファイルサイズをゼロにします。ファイルが存在しない場合には、 作成を試みます。
'w+' | 読み込み／書き出し用でオープンします。 それ以外の振る舞いは、'w' と同じです。
'a' | 書き出し用のみでオープンします。ファイルポインタをファイルの終端に置きます。 ファイルが存在しない場合には、作成を試みます。 このモードは、fseek() では何の効果もありません。 書き込みは、常に追記となります。
'a+' | 読み込み／書き出し用でオープンします。 ファイルポインタをファイルの終端に置きます。 ファイルが存在しない場合には、作成を試みます。 このモードは、fseek() では読み込み位置のみに影響します。 書き込みは、常に追記となります。
'x' | 書き込みのみでオープンします。ファイルポインタをファイルの先頭に置きます。 ファイルが既に存在する場合には fopen() は失敗し、 E_WARNING レベルのエラーを発行します。 ファイルが存在しない場合には新規作成を試みます。 これは open(2) システムコールにおける O_EXCL|O_CREAT フラグの指定と等価です。 このオプションはPHP4.3.2以降でサポートされ、また、 ローカルファイルに対してのみ有効です。
'x+' | 読み込み／書き出し用でオープンします。 それ以外の振る舞いは 'x' と同じです。
'c' | 書き込みのみでオープンします。ファイルが存在しない場合には新規作成を試みます。 ファイルが既に存在する場合でもそれを ('w' のように) 切り詰めたりせず、 また ('x' のように) 関数のコールが失敗することもありません。 ファイルポインタをファイルの先頭に置きます。これは、アドバイザリ・ロック (flock() を参照ください) を確保してからファイルを変更したい場合に便利です。 'w' を使うと、ロックを取得する前にファイルを切り詰めてしまいます (もしファイルを切り詰めたいのなら、ロックを要求した後で ftruncate() を使うこともできます)。
'c+' | 読み込み／書き出し用でオープンします。 それ以外の振る舞いは 'c' と同じです。
'e' | オープンされたファイル記述子に close-on-exec フラグを設定します。 POSIX.1-2008 準拠のシステムでコンパイルされた PHP でのみ利用可能です。

注意:

オペレーティングシステムファミリが異なると行末も異なります。 テキストファイルに書き出し、そこに改行を加えたいとき、 オペレーティングシステムにあわせた正しい改行コードを使用する必要があります。 Unix ベースのシステムでは改行に \n キャラクタを使用します。 Windows ベースのシステムでは \r\n を使用します。 マッキントッシュベースのシステム (Mac OS Classic) では \r を使用します。

間違った改行コードでファイルに書き込むと、 他のアプリケーション上でそのファイルを開いた際に変な風に見えてしまいます。

Windows上では、\nを\r\nに透過的に変換する text-mode変換フラグ('t')が提供されます。 それに対し、'b'を使って強制的にバイナリモードにすることもできます。 その場合データの変換はされません。 このフラグを使用するには、'b' または 't'を mode引数の最後に追加してください。

デフォルトの変換モードは 'b' です。 plain-text ファイルを使用する場合には 't' モードを指定できますし、 改行に \n を使用すると、 古いバージョンのメモ帳のようなアプリケーションで読めることを期待できます。 それ以外のケースでは 'b' を使うべきです。

バイナリファイルを扱っている際に 't' フラグを指定した場合、 画像ファイルが壊れたり、\r\n キャラクタがおかしくなる等の問題を抱えてしまうでしょう。

注意:

互換性維持のために、't' モードを使用または依存しているコードを書き直し、 正しい改行コードと 'b' モードを代わりに使用することが、 強く推奨されます。

注意: php://output, php://input, php://stdin, php://stdout, php://stderr, php://fd ストリームラッパーについては、 mode は無視されます。

use_include_path

オプションの３番目の引数use_include_pathに true を設定することにより、include_path のファイルの検索も行うこともできます。

context

ストリームコンテキストリソース

戻り値

成功した場合にファイルポインタリソース、 失敗した場合に false を返します

エラー / 例外

失敗したときは E_WARNING が発生します。

変更履歴

バージョン | 説明
7.0.16, 7.1.2 | 'e' が追加されました。

例

例1 fopen() の例

<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>

注意

警告

IIS のような、いくつかの標準に 対応してない Web サーバーは、PHP に警告を発生させるような手順でデータを送信します。 このようなサーバーを使用する場合は、 error_reporting を警告を発生しないレベルまで小さくする必要があります。 PHP では、https:// ラッパーでストリームをオープンする際に バグがある IIS サーバーソフトウエアを検出することができ、この警告を抑制することができます。 あなたが ssl:// ソケットを作成するために fsockopen() を使用している場合、 自らこの警告を検出し、抑制する必要があります。

注意:

ファイルの読みこみ・書きこみ時に問題が発生し、 サーバーモジュール版のPHPを使用している場合、 使用するファイル・ディレクトリがサーバープロセスからアクセス可能かどうかを確認してください。

注意:

この関数は、filename がディレクトリの場合でも成功することがあります。 filename がファイルなのかディレクトリなのかがはっきりしない場合は、 まず is_dir() を使ってから fopen() を呼ぶようにしましょう。

参考

  • サポートするプロトコル/ラッパー
  • fclose() - オープンされたファイルポインタをクローズする
  • fgets() - ファイルポインタから 1 行取得する
  • fread() - バイナリセーフなファイルの読み込み
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • file() - ファイル全体を読み込んで配列に格納する
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • popen() - プロセスへのファイルポインタをオープンする
  • stream_context_create() - ストリームコンテキストを作成する
  • umask() - 現在の umask を変更する
  • SplFileObject


ファイルポインタ上に残っているすべてのデータを出力する

  • ≪ fopen
  • fputcsv ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタ上に残っているすべてのデータを出力する

fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — ファイルポインタ上に残っているすべてのデータを出力する

説明

fpassthru(resource $stream): int

与えられたファイルポインタを EOF まで読み、結果を出力バッファに書き出します。

ファイルに既にデータを書き終えている場合で ファイルポインタをファイルの先頭にリセットするには rewind() をコールする必要があります。

ファイルを更新したり特定のオフセットを探すのではなく 内容を出力バッファにダンプしたいだけの場合、 readfile() を使用することが可能です。 この場合、fopen() コールは必要ありません。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

戻り値

fpassthru() は stream から読み込み、出力に渡した文字数を返します。

例

例1 バイナリファイルに対する fpassthru() の使用例

<?php

// バイナリモードでファイルをオープンする
$name = './img/ok.png';
$fp = fopen($name, 'rb');

// 正しいヘッダを送出する
header("Content-Type: image/png");
header("Content-Length: " . filesize($name));

// 画像をダンプしスクリプトを終了する
fpassthru($fp);
exit;

?>

注意

注意:

fpassthru() を Windows システムのバイナリファイルで 使用する場合、fopen() をコールする際に モードに b を追加してバイナリモードでファイルを オープンするようにしてください。

バイナリファイルを扱う場合は、必要でなくても b フラグを使用するようにしましょう。 それにより、スクリプトの可搬性がより高くなります。

参考

  • readfile() - ファイルを出力する
  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする


行を CSV 形式にフォーマットし、ファイルポインタに書き込む

  • ≪ fpassthru
  • fputs ≫
  • PHP Manual
  • ファイルシステム 関数
  • 行を CSV 形式にフォーマットし、ファイルポインタに書き込む

fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む

説明

fputcsv(
resource $stream,
array $fields,
string $separator = ",",
string $enclosure = "\"",
string $escape = "\\",
string $eol = "\n"
): int|false

fputcsv() は、行（fields 配列として渡されたもの）を CSV としてフォーマットし、それを stream で指定したファイルに書き込みます (いちばん最後に改行を追加します)。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

fields

文字列の配列。

separator

オプションの separator はフィールド区切り文字 (シングルバイト文字 一文字だけ) を指定します。

enclosure

オプションの enclosure はフィールドを囲む文字 (シングルバイト文字 一文字だけ) を指定します。

escape

オプションの escape は、エスケープ文字 (シングルバイト文字 最大で一文字) を指定します。 空文字("") を指定すると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

eol

eol は、 カスタムの行末シーケンスを設定するオプションの引数です。

注意:

enclosure がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。 ただし、その直前に escape がある場合は別です。

戻り値

書き込んだ文字列の長さを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | オプションの引数 eol が追加されました。
7.4.0 | escape パラメータが、 (RFC 4180 に準拠していない) 独自仕様のエスケープ機構を無効にするため、 空文字列を受け入れるようになりました。

例

例1 fputcsv() の例

<?php

$list = array (
array('aaa', 'bbb', 'ccc', 'dddd'),
array('123', '456', '789'),
array('"aaa"', '"bbb"')
);

$fp = fopen('file.csv', 'w');

foreach ($list as $fields) {
fputcsv($fp, $fields);
}

fclose($fp);
?>

上の例が書き出す file.csv の内容は、このようになります。

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

注意

注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 PHP が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

参考

  • fgetcsv() - ファイルポインタから行を取得し、CSVフィールドを処理する


fwrite のエイリアス

  • ≪ fputcsv
  • fread ≫
  • PHP Manual
  • ファイルシステム 関数
  • fwrite のエイリアス

fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — fwrite() のエイリアス

説明

この関数は次の関数のエイリアスです。 fwrite().


バイナリセーフなファイルの読み込み

  • ≪ fputs
  • fscanf ≫
  • PHP Manual
  • ファイルシステム 関数
  • バイナリセーフなファイルの読み込み

fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — バイナリセーフなファイルの読み込み

説明

fread(resource $stream, int $length): string|false

fread() は、stream が指すファイルポインタから最高 length バイト読み込みます。 以下のいずれかの条件を満たしたら、読み込みを終了します。

  • length バイトぶん読み込んだ
  • EOF (ファイルの終端) に達した
  • パケットが利用可能になるか、あるいは ソケットのタイムアウト が発生した (ネットワークストリームの場合)
  • バッファつきで読み込まれた、プレーンなファイルでないストリームの場合に、 一回の読み込みバイト数がチャンクサイズ (通常は 8192) に達した。 それまでにバッファされていたデータの内容によって、返されるデータのサイズはチャンクサイズより大きくなることがあります。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

length

最大 length バイトまで読み込む。

戻り値

読み込んだ文字列を返します。失敗した場合に false を返します。

例

例1 シンプルな fread() の例

<?php
// ファイルの中身を読んで文字列に格納する
$filename = "/usr/local/something.txt";
$handle = fopen($filename, "r");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

例2 バイナリの fread() の例

警告

バイナリとテキストファイルの形式が異なるシステム(すなわち Windows)では、fopen()の mode パラメータに 'b' を指定してファイルをオープンする必要があります。

<?php
$filename = "c:\\files\\somepic.gif";
$handle = fopen($filename, "rb");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

例3 リモートファイルの fread() の例

警告

通常のローカルファイル以外のもの、例えば リモートファイル や popen()、fsockopen() が返す ストリームを読み込んでいる場合には、 パケットが有効になった後に読み込みはストップします。 つまり以下の例のように分割されたデータを結合すべきであるということです。

<?php
$handle = fopen("http://www.example.com/", "rb");
$contents = stream_get_contents($handle);
fclose($handle);
?>
<?php
$handle = fopen("http://www.example.com/", "rb");
if (FALSE === $handle) {
exit("Failed to open stream to URL");
}

$contents = '';

while (!feof($handle)) {
$contents .= fread($handle, 8192);
}
fclose($handle);
?>

注意

注意:

ファイルの中身を文字列に格納したいだけならば、file_get_contents() を使うほうが上記の例よりも効率的です。

注意:

fread() は、 ファイルポインタが現在指している位置から読み込みを開始することに注意しましょう。 ポインタの現在位置を調べるには ftell() を、 そしてポインタの位置を巻き戻すには rewind() を使用します。

参考

  • fwrite() - バイナリセーフなファイル書き込み処理
  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • file() - ファイル全体を読み込んで配列に格納する
  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する
  • fseek() - ファイルポインタを移動する
  • ftell() - ファイルの読み書き用ポインタの現在位置を返す
  • rewind() - ファイルポインタの位置を先頭に戻す
  • unpack() - バイナリ文字列からデータを切り出す


フォーマットに基づきファイルからの入力を処理する

  • ≪ fread
  • fseek ≫
  • PHP Manual
  • ファイルシステム 関数
  • フォーマットに基づきファイルからの入力を処理する

fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — フォーマットに基づきファイルからの入力を処理する

説明

fscanf(resource $stream, string $format, mixed &...$vars): array|int|false|null

関数fscanf() は sscanf() に似ていますが、stream が指すファイルから入力を取得し、 指定したフォーマット format に基づき解釈を行います。

フォーマット文字列におけるあらゆる空白は 入力ストリームのあらゆる空白にマッチします。 これはつまりフォーマット文字列のタブ (\t) すらも 入力ストリームの空白1個にマッチしてしまうことを意味します。

fscanf() をコールするたびに、ファイルから 1 行ずつ読み込みます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

format

string を解釈するフォーマット。 sprintf() のドキュメントにある説明と比べて、以下の違いがあります。

  • ロケールに対応していません。
  • F、g、G および b はサポートしていません。
  • D は十進数値を表します。
  • i は基数検出つきの整数値を表します。
  • n は処理する文字数を表します。
  • s は、空白文字を読み取ると停止することを示します。
  • argnum$ の代わりに * を指定すると、 この変換仕様に従った値の代入を抑制します。

vars

オプションで代入する値。

戻り値

この関数のパラメータが二つだけの場合、処理された値は配列として返されます。 他方、オプションのパラメータが指定された場合、 この関数は、代入された値の数を返します。 オプション引数は参照渡しとする必要があります。

string で利用可能な部分文字列よりも、 format で期待された部分文字列の数が多い場合は、null が返されます。 その他のエラーが発生した場合は、false が返されます。

例

例1 fscanf() の例

<?php
$handle = fopen("users.txt", "r");
while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
list ($name, $profession, $countrycode) = $userinfo;
//... これらの値を使用して何か行う
}
fclose($handle);
?>

例2 users.txt の内容

javier  argonaut        pe
hiroshi sculptor        jp
robert  slacker us
luigi   florist it

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す


ファイルポインタを移動する

  • ≪ fscanf
  • fstat ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタを移動する

fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — ファイルポインタを移動する

説明

fseek(resource $stream, int $offset, int $whence = SEEK_SET): int

stream が指しているファイルのファイル位置識別子を ファイル・ストリーム中の offset バイト目に セットします。新規位置は、ファイルの先頭からのバイト数で 測られます。これは whence で指定した位置に offset を追加することにより得られます。

一般的に、ファイルの終端より先の位置に移動することも許されています。 そこにデータを書き込んだ場合、ファイルの終端からシーク位置までの範囲を読み込むと 値 0 が埋められたバイトを返します。しかし、ストリームの種類によっては この挙動をサポートしていないものもあります。 ストリームのもとになっているストレージが固定長である場合などです。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

offset

オフセット。

ファイルの終端から数えた位置に移動するには、負の値を offset に渡して whence を SEEK_END に設定しなければなりません。

whence

whence の値は以下のようになります。

  • SEEK_SET - 位置を offset バイト目に設定する
  • SEEK_CUR - 現在の位置に offset を加えた位置に設定する
  • SEEK_END - ファイル終端に offset を加えた位置に設定する

戻り値

成功すると 0 を返し、そうでなければ -1 を返します。

例

例1 fseek() の例

<?php

$fp = fopen('somefile.txt', 'r');

// データを読み込む
$data = fgets($fp, 4096);

// ファイルの先頭に移動する。
// rewind($fp); と等価。
fseek($fp, 0);

?>

注意

注意:

追加モード (a あるいは a+) でファイルをオープンした場合、 ファイル位置によらず、ファイルに書き込むあらゆるデータが追加されます。また fseek() の結果は未定義となります。

注意:

すべてのストリームがシーク処理に対応しているわけではありません。 シークに対応していないストリームで現在位置から前方へのシークを行うには、 データを読み込んでそれを捨てていくしかありません。それ以外のやり方は失敗します。

参考

  • ftell() - ファイルの読み書き用ポインタの現在位置を返す
  • rewind() - ファイルポインタの位置を先頭に戻す


オープンしたファイルポインタからファイルに関する情報を取得する

  • ≪ fseek
  • fsync ≫
  • PHP Manual
  • ファイルシステム 関数
  • オープンしたファイルポインタからファイルに関する情報を取得する

fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — オープンしたファイルポインタからファイルに関する情報を取得する

説明

fstat(resource $stream): array|false

ファイルポインタstreamによりオープンされたファイルの統計情報を取得します。 この関数は関数stat()に似ていますが、 ファイル名の代わりにオープンされたファイルポインタを指定するところが異なります。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

戻り値

ファイルの統計情報の配列を返します。配列のフォーマットについては stat()のマニュアルをご覧ください。 失敗時に false を返します。

例

例1 fstat() の例

<?php

// ファイルをオープンする
$fp = fopen("/etc/passwd", "r");

// 統計情報を収集する
$fstat = fstat($fp);

// ファイルをクローズする
fclose($fp);

// 連想配列部のみ表示する
print_r(array_slice($fstat, 13));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [dev] => 771
    [ino] => 488704
    [mode] => 33188
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 1114
    [atime] => 1061067181
    [mtime] => 1056136526
    [ctime] => 1056136526
    [blksize] => 4096
    [blocks] => 8
)

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。


データをファイルに同期する(メタデータも含む)

  • ≪ fstat
  • ftell ≫
  • PHP Manual
  • ファイルシステム 関数
  • データをファイルに同期する(メタデータも含む)

fsync

(PHP 8 >= 8.1.0)

fsync — データをファイルに同期する(メタデータも含む)

説明

fsync(resource $stream): bool

この関数は、 変更をメタデータも含めてファイルに同期します。 fflush() に似ていますが、 この関数はオペレーティングシステムに対し、 ストレージに書き込むことを指示することも行います。

パラメータ

stream

ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 fsync() の例

<?php

$file = 'test.txt';

$stream = fopen($file, 'w');
fwrite($stream, 'test data');
fwrite($stream, "\r\n");
fwrite($stream, 'additional data');

fsync($stream);
fclose($stream);
?>

参考

  • fdatasync() - データをファイルに同期する(但しメタデータは除く)
  • fflush() - 出力をファイルにフラッシュする


ファイルの読み書き用ポインタの現在位置を返す

  • ≪ fsync
  • ftruncate ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの読み書き用ポインタの現在位置を返す

ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — ファイルの読み書き用ポインタの現在位置を返す

説明

ftell(resource $stream): int|false

stream ファイルの読み書き用ポインタの現在位置を返します。

パラメータ

stream

ファイルポインタは有効なものでなければならず、また fopen()、popen() で正常にオープンされたファイルを指している必要があります。 ftell() は、("a" フラグ付きでオープンされた) 追加のみ可能なストリームに対する結果も未定義です。

戻り値

stream が示すファイルポインタの位置、 すなわちファイル・ストリーム上のオフセットを整数値で返します。

エラーが起こった場合 false を返します。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 ftell() の例

<?php

// ファイルをオープンし、データを読み込む
$fp = fopen("/etc/passwd", "r");
$data = fgets($fp, 12);

// どこにいるんだ ?
echo ftell($fp); // 11

fclose($fp);

?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • fseek() - ファイルポインタを移動する
  • rewind() - ファイルポインタの位置を先頭に戻す


ファイルを指定した長さに丸める

  • ≪ ftell
  • fwrite ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルを指定した長さに丸める

ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — ファイルを指定した長さに丸める

説明

ftruncate(resource $stream, int $size): bool

ファイルポインタstreamを引数とし、 ファイルを指定した長さ、サイズに丸めます。

パラメータ

stream

ファイルポインタ。

注意:

stream は書き込みモードでオープンする必要があります。

size

丸める大きさ。

注意:

size がファイルのサイズより大きい場合は、 null バイトを用いてファイルを拡大します。

size がファイルのサイズより小さい場合は、 余分なデータは失われます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルの丸めの例

<?php
$filename = 'lorem_ipsum.txt';

$handle = fopen($filename, 'r+');
ftruncate($handle, rand(1, filesize($filename)));
rewind($handle);
echo fread($handle, filesize($filename));
fclose($handle);
?>

注意

注意:

ファイルポインタは変更 されません。

参考

  • fopen() - ファイルまたは URL をオープンする
  • fseek() - ファイルポインタを移動する


バイナリセーフなファイル書き込み処理

  • ≪ ftruncate
  • glob ≫
  • PHP Manual
  • ファイルシステム 関数
  • バイナリセーフなファイル書き込み処理

fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — バイナリセーフなファイル書き込み処理

説明

fwrite(resource $stream, string $data, ?int $length = null): int|false

fwrite()はdataの内容を streamが指しているファイル・ストリームに書き込みます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

data

書き込む文字列。

length

lengthパラメータが数値の場合、 lengthバイト数分の書き込みが完了したか、 dataが終わりに達したかのいずれか早い方の 事象により書き込みは中止されます。

戻り値

fwrite() は、 書き込んだバイト数を返します。 失敗した場合に false を返します

エラー / 例外

fwrite() は、 失敗した場合に E_WARNING を発生させます。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 簡単な fwrite() の例

<?php
$filename = 'test.txt';
$somecontent = "Add this to the file\n";

// ファイルが存在しかつ書き込み可能かどうか確認します
if (is_writable($filename)) {

// この例では$filenameを追加モードでオープンします。
// ファイルポインタはファイルの終端になりますので
// そこがfwrite()で$somecontentが追加される位置になります。
if (!$fp = fopen($filename, 'a')) {
echo "Cannot open file ($filename)";
exit;
}

// オープンしたファイルに$somecontentを書き込みます
if (fwrite($fp, $somecontent) === FALSE) {
echo "Cannot write to file ($filename)";
exit;
}

echo "Success, wrote ($somecontent) to file ($filename)";

fclose($fp);

} else {
echo "The file $filename is not writable";
}
?>

注意

注意:

ネットワークストリームへの書き込みは、 すべての文字列を書き込み終える前に終了する可能性があります。 fwrite() の戻り値を確かめるようにしましょう。

<?php
function fwrite_stream($fp, $string) {
for ($written = 0; $written < strlen($string); $written += $fwrite) {
$fwrite = fwrite($fp, substr($string, $written));
if ($fwrite === false) {
return $written;
}
}
return $written;
}
?>

注意:

(Windowsのように)バイナリとテキストファイルの形式が異なるシステムにおいては、ファイルをオープンする際に fopen()の mode パラメータに 'b' を指定する必要があります。

注意:

fopen() を使用して追記モードでオープンした stream の場合、 fwrite() はアトミックになります (ただし、一部のプラットフォームにおいて data がファイルシステムのブロックサイズを超えない場合、 そしてローカルファイルシステム上のファイルである場合に限ります)。 アトミックであるとは、つまり fwrite() をコールする前にリソースを flock() する必要がないということです。データの書き込みが中断されることはありません。

注意:

同じファイルポインタに 2 回書き込みを行うと、 データはファイルの末尾に追記されます。

<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);

// 'data.txt' の中身は 123 となります。23 ではありません!
?>

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fopen() - ファイルまたは URL をオープンする
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • popen() - プロセスへのファイルポインタをオープンする
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • pack() - データをバイナリ文字列にパックする


パターンにマッチするパス名を探す

  • ≪ fwrite
  • is_dir ≫
  • PHP Manual
  • ファイルシステム 関数
  • パターンにマッチするパス名を探す

glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — パターンにマッチするパス名を探す

説明

glob(string $pattern, int $flags = 0): array|false

glob() 関数は libc の glob() 関数で使われるルールに基づいて pattern にマッチする全てのパス名を検索します。 ルールは、一般のシェルで使われるルールと似ています。

パラメータ

pattern

パターン。チルダの展開やパラメータ置換は行いません。

Special characters:

  • * - ゼロ文字以上の文字にマッチします。
  • ? - 正確に(任意の)一文字にだけマッチします。
  • [...] - グループ化された文字のうち、一文字にマッチします。 はじめの文字が ! だった場合、 グループにないあらゆる文字にマッチします。
  • \ - 次に来る文字をエスケープします。 但し、GLOB_NOESCAPE が使われている場合は除きます。

flags

有効なフラグは次のとおりです。

GLOB_BRACE (int)
{a,b,c} を 'a', 'b', 'c' にマッチさせるように展開します。

注意: GLOB_BRACE は GNU システムでないシステムによっては使えない場合があります。 使えないシステムの例として、Solaris や Alpine Linux があてはまります。

GLOB_ERR (int)
(ディレクトリが読み取れない場合のような) 読み取りエラーの場合に停止します。 デフォルトでは、エラーは無視されます。
GLOB_ONLYDIR (int)
パターンにマッチするディレクトリエントリのみを返します。
GLOB_MARK (int)
スラッシュ(Windows の場合はバックスラッシュ) を返されるディレクトリに個別に追加します。
GLOB_NOSORT (int)
ディレクトリ内に存在するかのように、ファイルを返します(ソートは行いません)。 このフラグを使わない場合、パス名はアルファベット順でソートされます。
GLOB_NOCHECK (int)
マッチするファイルが見つからない場合に、検索パターンを返します。
GLOB_NOESCAPE (int)
バックスラッシュは、メタキャラクタをクォートしません。
GLOB_AVAILABLE_FLAGS (int)
すべての GLOB_* フラグの組み合わせです。 0 | GLOB_BRACE | GLOB_MARK | GLOB_NOSORT | GLOB_NOCHECK | GLOB_NOESCAPE | GLOB_ERR | GLOB_ONLYDIR と等しくなります。

戻り値

マッチするファイル／ディレクトリを含む配列を返します。 マッチするファイルがなかった場合には空の配列、 そして失敗した場合には false を返します。

注意:

システムによっては、何もマッチしなかった場合とエラーが発生した場合を区別できないものもあります。

例

例1 glob() が opendir() と関連する関数群の代替策になるかを示す簡便な方法

<?php
foreach (glob("*.txt") as $filename) {
echo "$filename size " . filesize($filename) . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

funclist.txt size 44686
funcsummary.txt size 267625
quickref.txt size 137820

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: この関数が使用できないシステムも存在します (例: 昔の Sun OS など)。

参考

  • opendir() - ディレクトリハンドルをオープンする
  • readdir() - ディレクトリハンドルからエントリを読み込む
  • closedir() - ディレクトリハンドルをクローズする
  • fnmatch() - ファイル名がパターンにマッチするか調べる


ファイルがディレクトリかどうかを調べる

  • ≪ glob
  • is_executable ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルがディレクトリかどうかを調べる

is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — ファイルがディレクトリかどうかを調べる

説明

is_dir(string $filename): bool

指定したファイルがディレクトリかどうかを調べます。

パラメータ

filename

ファイルへのパス。filename が相対パスの場合は、現在の作業ディレクトリからの相対パスとして処理します。 filename がシンボリックリンクあるいはハードリンクの場合は、 リンク先を解決して処理します。 open_basedir を有効にすると、 さらに制限がかかるでしょう。

戻り値

ファイルが存在して、かつそれがディレクトリであれば true、それ以外の場合は false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 is_dir() の例

<?php
var_dump(is_dir('a_file.txt'));
var_dump(is_dir('bogus_dir/abc'));

var_dump(is_dir('..')); //一つ上のディレクトリ
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(true)

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • chdir() - ディレクトリを変更する
  • dir() - ディレクトリクラスのインスタンスを返す
  • opendir() - ディレクトリハンドルをオープンする
  • is_file() - 通常ファイルかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる


ファイルが実行可能かどうかを調べる

  • ≪ is_dir
  • is_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルが実行可能かどうかを調べる

is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — ファイルが実行可能かどうかを調べる

説明

is_executable(string $filename): bool

ファイルが実行可能かどうかを調べます。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルが存在し、かつそれが実行可能な場合に true、 エラー時に false を返します。 POSIX 準拠のシステムでは、 ファイルパーミッションの実行ビットが立っているものが実行可能です。 Windows については、下記を参照ください。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 is_executable() の例

<?php

$file = '/home/vincent/somefile.sh';

if (is_executable($file)) {
echo $file.' は実行可能です';
} else {
echo $file.' は実行可能ではありません';
}

?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

注意: Windows では、Windows API GetBinaryType() が適切に実行可能ファイルと報告した場合に、実行可能と見なされます。 後方互換のため、拡張子 .bat や .cmd が付いたファイルも同様に実行可能と見なされます。 PHP 7.4.0 より前のバージョンでは、 拡張子 .bat や .cmd が付いた空でないファイルは実行可能と見なされていました。 環境変数 PATHEXT は、is_executable() と無関係なことに注意が必要です。

参考

  • is_file() - 通常ファイルかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる


通常ファイルかどうかを調べる

  • ≪ is_executable
  • is_link ≫
  • PHP Manual
  • ファイルシステム 関数
  • 通常ファイルかどうかを調べる

is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — 通常ファイルかどうかを調べる

説明

is_file(string $filename): bool

指定したファイルが通常のファイルかどうかを調べます。

パラメータ

filename

ファイルへのパス。

戻り値

ファイルが存在し、かつそれが通常のファイルである場合に true、 それ以外の場合に false を返します。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 is_file() の例

<?php
var_dump(is_file('a_file.txt')) . "\n";
var_dump(is_file('/usr/bin/')) . "\n";
?>

上の例の出力は以下となります。

bool(true)
bool(false)

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • is_link() - ファイルがシンボリックリンクかどうかを調べる
  • SplFileInfo


ファイルがシンボリックリンクかどうかを調べる

  • ≪ is_file
  • is_readable ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルがシンボリックリンクかどうかを調べる

is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — ファイルがシンボリックリンクかどうかを調べる

説明

is_link(string $filename): bool

指定したファイルがシンボリックリンクかどうかを調べます。

パラメータ

filename

ファイルへのパス。

戻り値

filename が存在し、かつシンボリックリンクであれば true、 それ以外の場合に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 シンボリックリンクの作成と、ファイルがシンボリックリンクかどうかの確認

<?php
$link = 'uploads';

if (is_link($link)) {
echo readlink($link);
} else {
symlink('uploads.php', $link);
}
?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • is_file() - 通常ファイルかどうかを調べる
  • readlink() - シンボリックリンク先を返す


ファイルが存在し、読み込み可能であるかどうかを知る

  • ≪ is_link
  • is_uploaded_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルが存在し、読み込み可能であるかどうかを知る

is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — ファイルが存在し、読み込み可能であるかどうかを知る

説明

is_readable(string $filename): bool

ファイルが存在し、読み込み可能であるかどうかを調べます。

パラメータ

filename

ファイルへのパス。

戻り値

filename で指定したファイルあるいはディレクトリが存在し、 それが読み込み可能であれば true、それ以外の場合に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 is_readable() の例

<?php
$filename = 'test.txt';
if (is_readable($filename)) {
echo 'このファイルは読み込み可能です';
} else {
echo 'このファイルは読み込み可能ではありません';
}
?>

注意

PHP は、Web サーバーを実行しているユーザー ID (たいていは 'nobody') でファイルにアクセスすることを覚えておいてください。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

注意:

チェックは、実効ユーザーではなく実ユーザーの UID/GID で行います。

この関数は、ディレクトリに対しても true を返すかもしれません。 ファイルとディレクトリを区別するには is_dir() を使いましょう。

参考

  • is_writable() - ファイルが書き込み可能かどうかを調べる
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • fgets() - ファイルポインタから 1 行取得する


HTTP POST でアップロードされたファイルかどうかを調べる

  • ≪ is_readable
  • is_writable ≫
  • PHP Manual
  • ファイルシステム 関数
  • HTTP POST でアップロードされたファイルかどうかを調べる

is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — HTTP POST でアップロードされたファイルかどうかを調べる

説明

is_uploaded_file(string $filename): bool

filename という名前のファイルが HTTP POST によりアップロードされたものである場合に true を返します。 悪意のあるユーザーがスクリプトをだまして、 本来見られてはいけないはずのファイル (/etc/passwd など) にアクセスすることを防止したい場合に、この関数は有用です。

この種の確認は、アップロードされたファイルに関して何でもできる場合には、 その内容をユーザー、または同じシステム上の他のユーザーにさえ 暴かれる可能性があるため、特に重要です。

適切に動作させるために、関数 is_uploaded_file() には $_FILES['userfile']['tmp_name'] のような引数が必要です。 アップロードされたファイルのクライアントマシン上での名前 $_FILES['userfile']['name'] では動作しません。

パラメータ

filename

調べたいファイル名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 is_uploaded_file() の例

<?php

if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
echo "ファイル ". $_FILES['userfile']['name'] ." のアップロードに成功しました。\n";
echo "その中身を表示します\n";
readfile($_FILES['userfile']['tmp_name']);
} else {
echo "おそらく何らかの攻撃を受けました。";
echo "ファイル名 '". $_FILES['userfile']['tmp_name'] . "'.";
}

?>

参考

  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する
  • $_FILES
  • 簡単な使用例については ファイルアップロードの処理


ファイルが書き込み可能かどうかを調べる

  • ≪ is_uploaded_file
  • is_writeable ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルが書き込み可能かどうかを調べる

is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — ファイルが書き込み可能かどうかを調べる

説明

is_writable(string $filename): bool

filenameが存在して、かつそれが書き込み可能であれば trueを返します。引数filenameはディレクトリ名とすることができ、 ディレクトリが書き込み可能であることを調べることが可能です。

PHP は、Web サーバーが実行されているユーザー ID('nobody' が多い) でファイルにアクセスすることを覚えておいてください。

パラメータ

filename

調べたいファイル名。

戻り値

filename が存在して書き込み可能な場合に true を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 is_writable() の例

<?php
$filename = 'test.txt';
if (is_writable($filename)) {
echo 'このファイルは書き込み可能です';
} else {
echo 'このファイルは書き込みできません';
}
?>

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • is_readable() - ファイルが存在し、読み込み可能であるかどうかを知る
  • file_exists() - ファイルまたはディレクトリが存在するかどうか調べる
  • fwrite() - バイナリセーフなファイル書き込み処理


is_writable のエイリアス

  • ≪ is_writable
  • lchgrp ≫
  • PHP Manual
  • ファイルシステム 関数
  • is_writable のエイリアス

is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — is_writable() のエイリアス

説明

この関数は次の関数のエイリアスです。 is_writable().


シンボリックリンクのグループ所有権を変更する

  • ≪ is_writeable
  • lchown ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンクのグループ所有権を変更する

lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — シンボリックリンクのグループ所有権を変更する

説明

lchgrp(string $filename, string|int $group): bool

シンボリックリンク filename のグループを group に変更しようと試みます。

スーバーユーザーは、 シンボリックリンクのグループを任意のものに変更できます。 その他のユーザーは、自分自身がメンバーの一員となっているグループにのみ変更できます。

パラメータ

filename

シンボリックリンクへのパス。

group

グループ名あるいはグループ番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンボリックリンクのグループの変更

<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);

lchgrp($link, 8);
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • chgrp() - ファイルのグループを変更する
  • lchown() - シンボリックリンクの所有者を変更する
  • chown() - ファイルの所有者を変更する
  • chmod() - ファイルのモードを変更する


シンボリックリンクの所有者を変更する

  • ≪ lchgrp
  • link ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンクの所有者を変更する

lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — シンボリックリンクの所有者を変更する

説明

lchown(string $filename, string|int $user): bool

シンボリックリンク filename の所有者を user に変更しようと試みます。

シンボリックリンクの所有者を変更できるのは、スーパーユーザーのみです。

パラメータ

filename

ファイルへのパス。

user

ユーザー名あるいはユーザー番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンボリックリンクの所有者の変更

<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);

lchown($link, 8);
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • chown() - ファイルの所有者を変更する
  • lchgrp() - シンボリックリンクのグループ所有権を変更する
  • chgrp() - ファイルのグループを変更する
  • chmod() - ファイルのモードを変更する


ハードリンクを作成する

  • ≪ lchown
  • linkinfo ≫
  • PHP Manual
  • ファイルシステム 関数
  • ハードリンクを作成する

link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — ハードリンクを作成する

説明

link(string $target, string $link): bool

link() はハードリンクを作成します。

パラメータ

target

リンクの対象。

link

リンクの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

link が既に存在していたり、 target が存在しない場合には、 この関数は失敗し E_WARNING が発生します。

例

例1 シンプルなハードリンクの作成

<?php
$target = 'source.ext'; // これは、既存のファイル名です
$link = 'newfile.ext'; // これは、リンク先としたいファイル名です

link($target, $link);
?>

注意

注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

注意: Windows のみ: この関数を使用するには、 権限を昇格させたモード、あるいは UAC を無効にした状態で PHP を実行しなければなりません。

参考

  • symlink() - シンボリックリンクを作成する
  • readlink() - シンボリックリンク先を返す
  • linkinfo() - リンクに関する情報を取得する
  • unlink() - ファイルを削除する


リンクに関する情報を取得する

  • ≪ link
  • lstat ≫
  • PHP Manual
  • ファイルシステム 関数
  • リンクに関する情報を取得する

linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — リンクに関する情報を取得する

説明

linkinfo(string $path): int|false

リンクに関する情報を取得します。

この関数を使用して (pathが指している) リンクが実際に存在するかどうかを、 (stat.h で定義されている S_ISLNK マクロと同じ方法で) チェックします。

パラメータ

path

リンクへのパス。

戻り値

linkinfo()は、lstat システムコールで返された Unix C 言語の stat 構造体の st_dev フィールドを返します。 成功した場合は負でない数値を返します。 リンクが存在しない場合は -1 を返し、open.base_dir の違反が起きた場合は false を返します。

例

例1 linkinfo() の例

<?php

echo linkinfo('/vmlinuz'); // 835

?>

参考

  • symlink() - シンボリックリンクを作成する
  • link() - ハードリンクを作成する
  • readlink() - シンボリックリンク先を返す


ファイルあるいはシンボリックリンクの情報を取得する

  • ≪ linkinfo
  • mkdir ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルあるいはシンボリックリンクの情報を取得する

lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — ファイルあるいはシンボリックリンクの情報を取得する

説明

lstat(string $filename): array|false

filename という名前のファイル、 またはシンボリックリンクの情報を得ます。

パラメータ

filename

ファイルあるいはシンボリックリンクへのパス。

戻り値

lstat() が返す配列の内容については stat() のマニュアルをご覧ください。 この関数の動作は stat() 関数と同じですが、 パラメータ filename がシンボリックリンクであった場合に、 シンボリック先のファイルのステータスではなく、 シンボリックリンクのステータスが返されるところが異なります。

失敗時に false を返します。

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 stat() と lstat() の比較

<?php
symlink('uploads.php', 'uploads');

// uploads.php と uploads の情報の比較
array_diff(stat('uploads'), lstat('uploads'));
?>

上の例の出力は、 たとえば以下のようになります。

ふたつのファイルの相違点が表示されます。

Array
(
    [ino] => 97236376
    [mode] => 33188
    [size] => 34
    [atime] => 1223580003
    [mtime] => 1223581848
    [ctime] => 1223581848
    [blocks] => 8
)

注意

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • stat() - ファイルに関する情報を取得する


ディレクトリを作る

  • ≪ lstat
  • move_uploaded_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • ディレクトリを作る

mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — ディレクトリを作る

説明

mkdir(
string $directory,
int $permissions = 0777,
bool $recursive = false,
?resource $context = null
): bool

directory で指定したディレクトリを作成します。

パラメータ

directory

ディレクトリのパス。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

permissions

パーミッションは 0777 がデフォルトです。 これは最も緩やかなアクセス制限を意味します。 パーミッションに関する詳細は chmod() をご覧ください。

注意:

Windows では permissions は無視されます。

permissions を八進数で指定したくなることもあるかもしれません。 その場合は先頭にゼロをつける必要があります。 また permissions は、 現在設定されている umask の影響も受けます。 umask を変更するには umask() を使用します。

recursive

true を指定すると、 directory で指定されたディレクトリの、 全ての親ディレクトリも同じパーミッションで作成されます。

context

ストリームコンテキストリソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意:

作成しようとしたディレクトリが既に存在している場合、 エラーとみなされ、false が返されます。 作成しようとする前に、既にディレクトリが存在するかをチェックするには is_dir() や file_exists() を使ってください。

エラー / 例外

ディレクトリが既に存在する場合は E_WARNING レベルのエラーが発生します。

ディレクトリの作成権限がない場合は E_WARNING レベルのエラーが発生します。

例

例1 mkdir() の例

<?php
mkdir("/path/to/my/dir", 0700);
?>

例2 mkdir() での recursive パラメータの使用例

<?php
// 作りたいディレクトリ構造
$structure = './depth1/depth2/depth3/';

// 入れ子構造を作るには、$recursive パラメータを
// mkdir() に指定しなければなりません

if (!mkdir($structure, 0777, true)) {
die('Failed to create directories...');
}

// ...
?>

参考

  • rmdir() - ディレクトリを削除する
  • umask() - 現在の umask を変更する


アップロードされたファイルを新しい位置に移動する

  • ≪ mkdir
  • parse_ini_file ≫
  • PHP Manual
  • ファイルシステム 関数
  • アップロードされたファイルを新しい位置に移動する

move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — アップロードされたファイルを新しい位置に移動する

説明

move_uploaded_file(string $from, string $to): bool

この関数は、from で指定されたファイルが (PHP の HTTP POST アップロード機構によりアップロードされたという意味で) 有効なアップロードファイルであるかどうかを確認します。 そのファイルが有効な場合、to で指定したファイル名に移動されます。

この種の確認は、アップロードされたファイルに関して何でもできる場 合には、その内容をユーザー、または同じシステム上の他のユーザーにさえ 暴かれる可能性があるため、特に重要です。

パラメータ

from

アップロードしたファイルのファイル名。

to

ファイルの移動先。

戻り値

成功した場合に true を返します。

from が有効なアップロードファイルでない場合、 処理は行われず、move_uploaded_file() は false を返します。

from が有効なアップロードファイルであるが、 何らかの理由により、移動できない場合、処理は行われず、 move_uploaded_file() は false を返します。加えて、警告が出力されます。

例

例1 複数のファイルのアップロード

<?php
$uploads_dir = '/uploads';
foreach ($_FILES["pictures"]["error"] as $key => $error) {
if ($error == UPLOAD_ERR_OK) {
$tmp_name = $_FILES["pictures"]["tmp_name"][$key];
// basename() で、ひとまずファイルシステムトラバーサル攻撃は防げるでしょう。
// ファイル名についてのその他のバリデーションも、適切に行いましょう。
$name = basename($_FILES["pictures"]["name"][$key]);
move_uploaded_file($tmp_name, "$uploads_dir/$name");
}
}
?>

注意

注意:

move_uploaded_file() は open_basedir を考慮しています。 しかしながら、アップロードされたファイルを移動する to パスのみ制限が設けられます。 そこでは from がそれらの制限に抵触する可能性があるためです。 move_uploaded_file() は PHP を通じてアップロードされたファイルのみを移動できるようにすることで この操作の安全性を保証しています。

警告

コピー先のファイルが既に存在する場合、上書きされます。

参考

  • is_uploaded_file() - HTTP POST でアップロードされたファイルかどうかを調べる
  • rename() - ファイルをリネームする
  • 簡単な使用例については ファイルアップロードの処理


設定ファイルをパースする

  • ≪ move_uploaded_file
  • parse_ini_string ≫
  • PHP Manual
  • ファイルシステム 関数
  • 設定ファイルをパースする

parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — 設定ファイルをパースする

説明

parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array|false

parse_ini_file() は、 filename で指定した ini ファイルをロードし、 連想配列としてその設定値を返します。

ini ファイルの構造は、php.ini の構造と同じです。

パラメータ

filename

パースしたい ini ファイルのファイル名。 相対パスが指定された場合、 現在のディレクトリから相対的な位置として評価され、 さらに include_path からファイルを探します。

process_sections

process_sections パラメータに true を設定すると、セクション名と設定が含まれた多次元の配列を得ることができます。 デフォルトでは、process_sections は false です。

scanner_mode

INI_SCANNER_NORMAL (デフォルト) あるいは INI_SCANNER_RAW。INI_SCANNER_RAW を指定すると、オプションの値はパースされません。

PHP 5.6.1 以降では INI_SCANNER_TYPED も指定できるようになりました。 このモードでは、boolean や null そして integer の型を、可能な限り維持します。 文字列 "true"、"on" そして "yes" は true に変換されます。"false"、"off"、"no" そして "none" は false だとみなされます。このモードでは、"null" は null に変換されます。また数値形式の文字列も、可能な限り integer 型に変換されます。

戻り値

成功した場合に設定を連想配列形式で返します。 失敗した場合に false を返します。

例

例1 sample.ini の内容

; これは設定ファイルのサンプルです。
; php.ini と同様、';' で始まる行はコメントです。

[first_section]
one = 1
five = 5
animal = BIRD

[second_section]
path = "/usr/local/bin"
URL = "http://www.example.com/~username"

[third_section]
phpversion[] = "5.0"
phpversion[] = "5.1"
phpversion[] = "5.2"
phpversion[] = "5.3"

urls[svn] = "http://svn.php.net"
urls[git] = "http://git.php.net"

例2 parse_ini_file() の例

定数 (但し __FILE__ のような "マジック定数" は除く) も ini ファイル上でパースされます。 そのため、parse_ini_file() をコールする前に ini ファイル上の値として定数を定義した場合、戻り値に統合されます。 ini ファイル上の値だけが評価されます。この値は定数でなければなりません。以下は例です：

<?php

define('BIRD', 'Dodo bird');

// セクションを無視してパースします。
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);

// セクションを意識してパースします。
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [one] => 1
    [five] => 5
    [animal] => Dodo bird
    [path] => /usr/local/bin
    [URL] => http://www.example.com/~username
    [phpversion] => Array
        (
            [0] => 5.0
            [1] => 5.1
            [2] => 5.2
            [3] => 5.3
        )

    [urls] => Array
        (
            [svn] => http://svn.php.net
            [git] => http://git.php.net
        )

)
Array
(
    [first_section] => Array
        (
            [one] => 1
            [five] => 5
            [animal] => Dodo bird
        )

    [second_section] => Array
        (
            [path] => /usr/local/bin
            [URL] => http://www.example.com/~username
        )

    [third_section] => Array
        (
            [phpversion] => Array
                (
                    [0] => 5.0
                    [1] => 5.1
                    [2] => 5.2
                    [3] => 5.3
                )

            [urls] => Array
                (
                    [svn] => http://svn.php.net
                    [git] => http://git.php.net
                )

        )

)

例3 parse_ini_file() による php.ini ファイルのパース

<?php
// 以下の結果を比較するための簡単な関数
function yesno($expression)
{
return($expression ? 'Yes' : 'No');
}

// php.ini へのパスを the php_ini_loaded_file() 関数で取得します
$ini_path = php_ini_loaded_file();

// php.ini をパースします
$ini = parse_ini_file($ini_path);

// 結果を表示して比較します。get_cfg_var() を使用すると、
// ここでパースして読み込んだのと同じ結果が得られることに注意しましょう
echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

(parsed) magic_quotes_gpc = Yes
(loaded) magic_quotes_gpc = Yes

例4 ini ファイルの値の補完

定数を評価することに加えて、文字によっては ini ファイルの値として特別な意味を持つものがあります。 さらに、環境変数や以前定義された設定オプション (get_cfg_var() も参照ください) は、 ${} を使って読み取ることができます。

; | は ビット演算の OR
is used for bitwise OR
three = 2|3

; & は ビット演算の AND
four = 6&5

; ^ は ビット演算の XOR
five = 3^6

; ~ は ビット演算の NOT
negative_two = ~1

; () はグループ化に使います
seven = (8|7)&(6|5)

; 環境変数 PATH を展開します
path = ${PATH}

; 設定オプション 'memory_limit' を展開します
configured_memory_limit = ${memory_limit}

例5 文字をエスケープする

文字によっては、ダブルクォートで囲まれた文字列の中で特別な意味を持つ場合があり、 その場合、バックスラッシュでエスケープしなければなりません。 特別な意味を持つのは、文字列の境目の印となるダブルクォート "、 および、バックスラッシュ \ (この文字の後に特別な文字がひとつ続きます) そのものです。

quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote

Windows ライクなパスについては例外があります。 クォートされた文字列のすぐ後に改行文字が続いた場合、 末尾のバックスラッシュはエスケープする必要がないというものです。

save_path = "C:\Temp\"

複数行にまたがる値で、改行文字が直後にあるダブルクォート文字をエスケープする必要がある場合、 次のようにして値を連結することでそれを実現できます。 (ダブルクォートで囲まれた文字列がひとつあり、その直後にもうひとつの文字列が続きます)

long_text = "Lorem \"ipsum\"""
 dolor" ; Results in: Lorem "ipsum"\n dolor

特別な意味を持つ別の文字として、$ (ドル記号) があります。 これは、開き括弧が続く場合、エスケープしなければいけません:

code = "\${test}"

文字のエスケープは、 INI_SCANNER_RAW モードではサポートされていません。 (このモードでは、全ての文字が "そのまま" 処理されます)

ini ファイルのパーサーは、標準的なエスケープシーケンス (\n, \t, など) をサポートしていないことに注意して下さい。 そのサポートが必要な場合、parse_ini_file() の処理結果を stripcslashes() で処理するようにして下さい。

注意

注意:

この関数は、php.ini ファイルには何もしません。 このファイルはスクリプトを実行している時には既に処理されています。 この関数は、アプリケーション個有の設定ファイルを読み込む際に使用可能です。

注意:

ini ファイル上の値に英数字ではないものがある場合、 ダブルクォート(")で囲う必要があります。

注意: ini ファイル上でキーとして使ってはいけない単語があります。 null, yes, no, true, false, on, off, none などです。 null, off, no および false は "" となり、 on, yes および true は "1" となります。 ただし、INI_SCANNER_TYPED モードを使っている場合は別です。 次の文字 ?{}|&~!()^" は、キーで使ってはいけません。 また、値の中で特別な意味を持ちます。

注意:

等号が含まれないエントリは無視されます。 つまり、"foo" というエントリは無視されますが、 "bar =" は、空の値を持つエントリとして追加されます。 たとえば MySQL の my.cnf には "no-auto-rehash" という設定項目がありますが、この項目には何も値を設定しません。 そのため、この項目は無視されます。

注意:

ini ファイルは、一般的にWebサーバーからはプレーンテキストとして扱われます。 よって、ini ファイルにリクエストがあった場合、ブラウザにそのまま表示されます。 これは、セキュリティを考慮すると、 ini ファイルはドキュメントルートの外側に置くか、 Webサーバーがそれを返さないように設定を変更しなければならないということです。 そうしないと、セキュリティ上のリスクが発生する可能性があります。

参考

  • parse_ini_string() - 設定文字列をパースする


設定文字列をパースする

  • ≪ parse_ini_file
  • pathinfo ≫
  • PHP Manual
  • ファイルシステム 関数
  • 設定文字列をパースする

parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — 設定文字列をパースする

説明

parse_ini_string(string $ini_string, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array|false

parse_ini_string() は、文字列 ini_string の設定を連想配列で返します。

文字列の構造は、php.ini の構造と同じです。

パラメータ

ini_string

パースしたい ini ファイルの内容。

process_sections

process_sections を true に設定すると、セクション名と設定を含む多次元配列を返します。 process_sections のデフォルトは false です。

scanner_mode

INI_SCANNER_NORMAL (デフォルト) あるいは INI_SCANNER_RAW。INI_SCANNER_RAW を指定すると、オプションの値はパースされません。

PHP 5.6.1 以降では INI_SCANNER_TYPED も指定できるようになりました。 このモードでは、boolean や null そして integer の型を、可能な限り維持します。 文字列 "true"、"on" そして "yes" は true に変換されます。"false"、"off"、"no" そして "none" は false だとみなされます。このモードでは、"null" は null に変換されます。また数値形式の文字列も、可能な限り integer 型に変換されます。

戻り値

成功した場合に設定を連想配列形式で返します。 失敗した場合に false を返します。

注意

注意: ini ファイル上でキーとして使ってはいけない単語があります。 null, yes, no, true, false, on, off, none などです。 null, off, no および false は "" となり、 on, yes および true は "1" となります。 ただし INI_SCANNER_TYPED モードを使っている場合は別です。 次の文字 ?{}|&~![()^" は、キーで使ってはいけません。 また、値の中で特別な意味を持ちます。

参考

  • parse_ini_file() - 設定ファイルをパースする


ファイルパスに関する情報を返す

  • ≪ parse_ini_string
  • pclose ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルパスに関する情報を返す

pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — ファイルパスに関する情報を返す

説明

pathinfo(string $path, int $flags = PATHINFO_ALL): array|string

pathinfo() は、path に関する情報を返します。flags によって連想配列あるいは文字列のどちらかとなります。

注意:

カレントのパスに関する情報を取得するには、 定義済みの変数 のセクションをご覧ください。

注意:

pathinfo() は入力された文字列をそのまま扱います。 よって、実際のファイルシステムや ".." のようなパスコンポーネントも認識しません。

注意:

Windows システムでのみ、\ 文字はディレクトリのセパレータとして解釈されます。 それ以外のシステムでは、他の文字と同じように扱われます。

警告

pathinfo() はロケールを考慮して処理を行います。 マルチバイト文字を含むパスを正しく処理するには、正しいロケールを setlocale() 関数で設定しておかなければなりません。

パラメータ

path

調べたいパス。

flags

指定する場合は、どの要素を返すのかを PATHINFO_DIRNAME、 PATHINFO_BASENAME、 PATHINFO_EXTENSION あるいは PATHINFO_FILENAME のいずれかで指定します。

flags を省略した場合はすべての要素を返します。

戻り値

flags パラメータを渡さなかった場合は、次の要素を含む連想配列を返します。 dirname、basename、 extension (存在すれば)、そして filename。

注意:

path に複数の拡張子が含まれる場合は、 PATHINFO_EXTENSION は最後の拡張子だけを返します。また、 PATHINFO_FILENAME は最後の拡張子だけを取り除きます (最初のサンプルを参照ください)。

注意:

path に拡張子がない場合は、 extension 要素は返されません (以下の二番目の例を参照ください)。

注意:

path の basename がドットで始まる場合は、それに続く文字は extension とみなされます。そして filename は空文字列となります (以下の三番目の例を参照ください)。

flags を指定すると、 要求した要素を文字列で返します。

例

例1 pathinfo() の例

<?php
$path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');

echo $path_parts['dirname'], "\n";
echo $path_parts['basename'], "\n";
echo $path_parts['extension'], "\n";
echo $path_parts['filename'], "\n";
?>

上の例の出力は以下となります。

/www/htdocs/inc
lib.inc.php
php
lib.inc

例2 pathinfo() での、拡張子を空にしたときと拡張子がないときの違いの例

<?php
$path_parts = pathinfo('/path/emptyextension.');
var_dump($path_parts['extension']);

$path_parts = pathinfo('/path/noextension');
var_dump($path_parts['extension']);
?>

上の例の出力は、 たとえば以下のようになります。

string(0) ""

Notice: Undefined index: extension in test.php on line 6
NULL

例3 pathinfo() での、ドットファイルの例

<?php
print_r(pathinfo('/some/path/.test'));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [dirname] => /some/path
    [basename] => .test
    [extension] => test
    [filename] =>
)

例4 配列の分解機能を、pathinfo() と一緒に使う例

flags パラメータは、ビットマスクではありません。 単一の値だけを指定できます。 パース済みの値の限られた一部を選択したい場合、 配列を分解する機能を以下のようにして使います:

<?php
['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');

var_dump($basename, $dirname);
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "lib.inc.php"
string(15) "/www/htdocs/inc"

参考

  • dirname() - 親ディレクトリのパスを返す
  • basename() - パスの最後にある名前の部分を返す
  • parse_url() - URL を解釈し、その構成要素を返す
  • realpath() - 正規化された絶対パス名を返す


プロセスのファイルポインタをクローズする

  • ≪ pathinfo
  • popen ≫
  • PHP Manual
  • ファイルシステム 関数
  • プロセスのファイルポインタをクローズする

pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — プロセスのファイルポインタをクローズする

説明

pclose(resource $handle): int

popen() でオープンしたパイプへの ファイルポインタをクローズします。

パラメータ

handle

ファイルポインタは有効なものでなければならず、また popen() で正常にオープンされたものである必要があります。

戻り値

実行していたプロセスの終了ステータスを返します。 エラーが発生した場合は -1 を返します。

注意:

PHP のコンパイル時に --enable-sigchild を指定した場合は、この関数の返り値は未定義となります。

例

例1 pclose() の例

<?php
$handle = popen('/bin/ls', 'r');
pclose($handle);
?>

注意

注意: Unix のみ

pclose() の内部的な実装は、
waitpid(3) システムコールを使っています。
実際の終了ステータスを知るには、pcntl_wexitstatus()
関数を使わなければなりません。

参考

  • popen() - プロセスへのファイルポインタをオープンする


プロセスへのファイルポインタをオープンする

  • ≪ pclose
  • readfile ≫
  • PHP Manual
  • ファイルシステム 関数
  • プロセスへのファイルポインタをオープンする

popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — プロセスへのファイルポインタをオープンする

説明

popen(string $command, string $mode): resource|false

command で指定したコマンドのフォークによってできたプロセスへのパイプをオープンします。

パラメータ

command

コマンド。

mode

モード。読み取りを行う場合は 'r' を。 書き込みを行う場合は 'w' を指定します。

Windows では、popen() はデフォルトでテキストモードになります。 つまり、パイプから \n 文字を読み込んだり、書き込んだりすると、 \r\n に変換されるということです。 この振る舞いを望まない場合は、 mode にバイナリモードを指定し、強制することが出来ます。 読み取りのバイナリモードは 'rb' を。 書き込みのバイナリモードは'wb' をそれぞれ指定します。

戻り値

fopen() により返されたファイルポインタと同様のものを返しますが、 それは(読み書きのいずれか一方でのみ使われる)片方向ストリームであり、 pclose() によりクローズされなければならないところが異なります。 このポインタは、fgets()、fgetss() および fwrite() のいずれかで使うことができます。 モードが 'r' のときは、返されるファイルポインタは そのコマンドの STDOUT と等しくなります。また、モードが 'w' のときは、返されるファイルポインタは そのコマンドの STDIN と等しくなります。

エラーが発生した場合は false を返します。

例

例1 popen() の例

<?php
$handle = popen("/bin/ls", "r");
?>

実行すべきコマンドが見つからない場合には、正常なリソースが返されます。 おかしなことと思われるかもしれませんが、これには意味があります。 これによってシェルから返されたエラーメッセージにアクセスすることができるのです。

例2 popen() の例

<?php
error_reporting(E_ALL);

/* リダイレクトにより、標準エラー出力を取得します */
$handle = popen('/path/to/executable 2>&1', 'r');
echo "'$handle'; " . gettype($handle) . "\n";
$read = fread($handle, 2096);
echo $read;
pclose($handle);
?>

注意

注意:

双方向(two-way)のサポートを求めているのなら、 proc_open() を使用してください。

参考

  • pclose() - プロセスのファイルポインタをクローズする
  • fopen() - ファイルまたは URL をオープンする
  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く


ファイルを出力する

  • ≪ popen
  • readlink ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルを出力する

readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — ファイルを出力する

説明

readfile(string $filename, bool $use_include_path = false, ?resource $context = null): int|false

ファイルを読んで標準出力に書き出します。

パラメータ

filename

読み込もうとするファイルの名前。

use_include_path

オプションの2番目の引数を使用して、これにtrueを設定することにより、 include_path のファイルの検索も行うことができます。

context

ストリームコンテキストリソース

戻り値

ファイルから読み込んだバイト数を返します。 失敗した場合に false を返します

エラー / 例外

失敗したときは E_WARNING が発生します。

例

例1 readfile() によるダウンロードの強制

<?php
$file = 'monkey.gif';

if (file_exists($file)) {
header('Content-Description: File Transfer');
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="'.basename($file).'"');
header('Expires: 0');
header('Cache-Control: must-revalidate');
header('Pragma: public');
header('Content-Length: ' . filesize($file));
readfile($file);
exit;
}
?>

上の例の出力は、 たとえば以下のようになります。

開く / 保存 ダイアログ

注意

注意:

readfile() 自体にはメモリに関する問題はなく、 巨大なファイルを送ってもかまいません。out of memoryエラーが出る場合は、 ob_get_level() で出力バッファリングを無効にしてください。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

参考

  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する
  • file() - ファイル全体を読み込んで配列に格納する
  • fopen() - ファイルまたは URL をオープンする
  • include - include
  • require - require
  • virtual() - Apache サブリクエストを実行する
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • サポートするプロトコル/ラッパー


シンボリックリンク先を返す

  • ≪ readfile
  • realpath ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンク先を返す

readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — シンボリックリンク先を返す

説明

readlink(string $path): string|false

readlink() は同名の C 関数と同じ動作をします。

パラメータ

path

シンボリックリンクのパス。

戻り値

シンボリックリンク・パスの内容を返します。エラーの場合は false を返します。

注意: この関数は、path がシンボリックリンクでない場合は失敗します。但し、Windows を除きます。 Windows では、正規化されたパスを返します。

例

例1 readlink() の例

<?php

// 出力例 /boot/vmlinux-2.4.20-xfs
echo readlink('/vmlinuz');

?>

参考

  • is_link() - ファイルがシンボリックリンクかどうかを調べる
  • symlink() - シンボリックリンクを作成する
  • linkinfo() - リンクに関する情報を取得する


正規化された絶対パス名を返す

  • ≪ readlink
  • realpath_cache_get ≫
  • PHP Manual
  • ファイルシステム 関数
  • 正規化された絶対パス名を返す

realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — 正規化された絶対パス名を返す

説明

realpath(string $path): string|false

realpath() は、 入力 path のシンボリックリンクをすべて展開し、 /./、/../ および / などの参照をすべて解決することにより、正規化された絶対パスを返します。

パラメータ

path

調べたいパス。

注意:

path の指定は必須ですが、空の文字列を指定することもできます。 その場合はカレントディレクトリを指定したものとみなします。

戻り値

成功した場合は、正規化された絶対パス名を返します。 返されるパスはシンボリックリンク、/./ および /../ 要素を含みません。 パスの末尾の区切り文字 (\ や / など) は削除されます。

realpath() は、 たとえばファイルが存在しないなどの失敗時に false を返します。

注意:

指定した階層にあるすべてのディレクトリに対して、 実行中のスクリプトからの実行権限が必要です。もし権限がなければ realpath() は false を返します。

注意:

大文字小文字を区別しないファイルシステムの場合は、realpath() が大文字小文字をどちらかにそろえるかもしれないし、そろえないかもしれません。

注意:

realpath() 関数は、Phar の内部にあるファイルに対しては機能しません。 そのようなパスは、実際のパスではなく仮想パスになるからです。

注意:

Windows では、ディレクトリへのシンボリックリンクとジャンクションは、ひとつ分しか展開されません。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

例

例1 realpath() の例

<?php
chdir('/var/www/');
echo realpath('./../../etc/passwd') . PHP_EOL;

echo realpath('/tmp/') . PHP_EOL;
?>

上の例の出力は以下となります。

/etc/passwd
/tmp

例2 Windows 上での realpath()

Windows 上で realpath() を実行すると、Unix 形式のパスを Windows 形式に変更します。

<?php
echo realpath('/windows/system32'), PHP_EOL;

echo realpath('C:\Program Files\\'), PHP_EOL;
?>

上の例の出力は以下となります。

C:\WINDOWS\System32
C:\Program Files

参考

  • basename() - パスの最後にある名前の部分を返す
  • dirname() - 親ディレクトリのパスを返す
  • pathinfo() - ファイルパスに関する情報を返す


realpath キャッシュ・エントリーを取得

  • ≪ realpath
  • realpath_cache_size ≫
  • PHP Manual
  • ファイルシステム 関数
  • realpath キャッシュ・エントリーを取得

realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — realpath キャッシュ・エントリーを取得

説明

realpath_cache_get(): array

realpath キャッシュ内容を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

realpath キャッシュ・エントリーの配列を返します。キーは元のパス・エントリーで、 値はデータ項目の配列です。それには、解決されたパス、失効日、キャッシュに保持されるその他のオプションを含みます。

例

例1 realpath_cache_get() 例

<?php
var_dump(realpath_cache_get());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["/test"]=>
  array(4) {
    ["key"]=>
    int(123456789)
    ["is_dir"]=>
    bool(true)
    ["realpath"]=>
    string(5) "/test"
    ["expires"]=>
    int(1260318939)
  }
  ["/test/test.php"]=>
  array(4) {
    ["key"]=>
    int(987654321)
    ["is_dir"]=>
    bool(false)
    ["realpath"]=>
    string(12) "/root/test.php"
    ["expires"]=>
    int(1260318939)
  }
}

参考

  • realpath_cache_size() - realpath キャッシュサイズを取得


realpath キャッシュサイズを取得

  • ≪ realpath_cache_get
  • rename ≫
  • PHP Manual
  • ファイルシステム 関数
  • realpath キャッシュサイズを取得

realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — realpath キャッシュサイズを取得

説明

realpath_cache_size(): int

realpath キャッシュで使用されるメモリー量を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

realpath キャッシュが使用中のメモリ量を返します。

例

例1 realpath_cache_size() 例

<?php
var_dump(realpath_cache_size());
?>

上の例の出力は、 たとえば以下のようになります。

int(412)

参考

  • realpath_cache_get() - realpath キャッシュ・エントリーを取得
  • 設定オプション realpath_cache_size


ファイルをリネームする

  • ≪ realpath_cache_size
  • rewind ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルをリネームする

rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — ファイルをリネームする

説明

rename(string $from, string $to, ?resource $context = null): bool

from を to にリネームし、必要ならディレクトリを移動しようと試みます。 ファイル名の変更かつ to が存在する場合、上書きされます。 ディレクトリ名の変更かつ to が存在する場合、 この関数は警告を発します。

パラメータ

from

変更前の名前。

注意:

from で使用されるラッパーは、 to で使用するラッパーと適合 している必要があります 。

to

変更後の名前。

注意: Windows では、to が既に存在する場合、 そのファイルは書き込み可能でなければなりません。 書き込み可能でない場合、rename() は失敗し、 E_WARNING が発生します。

context

ストリームコンテキストリソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 rename() の例

<?php
rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
?>

参考

  • copy() - ファイルをコピーする
  • unlink() - ファイルを削除する
  • move_uploaded_file() - アップロードされたファイルを新しい位置に移動する


ファイルポインタの位置を先頭に戻す

  • ≪ rename
  • rmdir ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルポインタの位置を先頭に戻す

rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — ファイルポインタの位置を先頭に戻す

説明

rewind(resource $stream): bool

stream のファイル位置指示子を、 ファイルストリームの先頭にセットします。

注意:

追記モード ("a" もしくは "a+") でファイルをオープンした場合、 ファイルのポインターの位置とは無関係に、 ファイルに書き込まれるデータは常に追加されます。

パラメータ

stream

ファイルポインタは有効なものでなければならず、 また fopen() で正常にオープンされたファイルを指している必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 rewind() での上書きの例

<?php
$handle = fopen('output.txt', 'r+');

fwrite($handle, 'Really long sentence.');
rewind($handle);
fwrite($handle, 'Foo');
rewind($handle);

echo fread($handle, filesize('output.txt'));

fclose($handle);
?>

上の例の出力は、 たとえば以下のようになります。

Foolly long sentence.

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fseek() - ファイルポインタを移動する
  • ftell() - ファイルの読み書き用ポインタの現在位置を返す
  • fwrite() - バイナリセーフなファイル書き込み処理


ディレクトリを削除する

  • ≪ rewind
  • set_file_buffer ≫
  • PHP Manual
  • ファイルシステム 関数
  • ディレクトリを削除する

rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — ディレクトリを削除する

説明

rmdir(string $directory, ?resource $context = null): bool

directoryで指定されたディレクトリを 削除しようと試みます。ディレクトリは空でなくてはならず、また 適切なパーミッションが設定されていなければなりません。 失敗した場合は E_WARNING レベルのエラーが発生します。

パラメータ

directory

ディレクトリへのパス。

context

ストリームコンテキストリソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 rmdir() の例

<?php
if (!is_dir('examples')) {
mkdir('examples');
}

rmdir('examples');
?>

参考

  • is_dir() - ファイルがディレクトリかどうかを調べる
  • mkdir() - ディレクトリを作る
  • unlink() - ファイルを削除する


stream_set_write_buffer のエイリアス

  • ≪ rmdir
  • stat ≫
  • PHP Manual
  • ファイルシステム 関数
  • stream_set_write_buffer のエイリアス

set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — stream_set_write_buffer() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_set_write_buffer().


ファイルに関する情報を取得する

  • ≪ set_file_buffer
  • symlink ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルに関する情報を取得する

stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — ファイルに関する情報を取得する

説明

stat(string $filename): array|false

filenameで指定されたファイルに ついての統計情報を取得します。 filename がシンボリックリンクの場合、 シンボリックリンクではなくファイルの実体の統計情報が返されます。 Windows 環境、かつ PHP 7.4.0 より前の NTS ビルドでは、 size, atime, mtime, ctime の統計情報は、シンボリックリンクの値が返されていました。

lstat() はシンボリックリンクの統計情報を返すという違いを除いて stat() と等価です。

パラメータ

filename

ファイルへのパス。

戻り値

stat() と fstat() の結果のフォーマット
数値 | 連想配列 | 説明
0 | dev | デバイス番号 (***)
1 | ino | inode 番号(****)
2 | mode | inode プロテクトモード(*****)
3 | nlink | リンク数
4 | uid | 所有者のユーザー ID(*)
5 | gid | 所有者のグループ ID(*)
6 | rdev | inode デバイス の場合、デバイスの種類
7 | size | バイト単位のサイズ
8 | atime | 最終アクセス時間 (Unix タイムスタンプ)
9 | mtime | 最終修正時間 (Unix タイムスタンプ)
10 | ctime | 最終 inode 変更時間 (Unix タイムスタンプ)
11 | blksize | ファイル IO のブロックサイズ(**)
12 | blocks | 512 バイトのブロックの確保数(**)

* Windows では常に 0 となります。

** st_blksize タイプをサポートするシステムでのみ有効です。 その他のシステム(例えば Windows)では -1 を返します。

*** PHP 7.4.0 以降、Windows では、この値はファイルが含まれるボリュームのシリアル番号です。 これは64ビットの 符号なし 整数です。 よって、オーバーフローする可能性があります。 これより前のバージョンでは、stat() 関数ではドライブレターを数値で表現した値 (たとえば、C: では 2) でした。 lstat() 関数では 0 でした。

**** PHP 7.4.0 以降、Windows では、この値はファイルに関連付けられた識別子です。 これは64ビットの 符号なし 整数です。 よって、オーバーフローする可能性があります。 これより前のバージョンでは、この値は常に 0 でした。

***** Windows では、 読み取り専用のファイル属性に従って、 書き込み可能のパーミッションビットが設定されます。 そして、この値は全てのユーザ、グループ、 オーナーについて、同じ値が報告されます。 is_writable() とは異なり、ACL は考慮されません。

mode の値は、複数の関数によって読まれる情報が含まれています。 8進数の場合、一番右の桁から評価され、はじめの3桁が chmod() によって返されます。 次の桁は PHP によって無視されます。その次の2桁は以下のファイルタイプを示します:

mode のファイルタイプ
mode が8進数だった場合 | 意味
0140000 | ソケット
0120000 | リンク
0100000 | 通常のファイル
0060000 | ブロックデバイス
0040000 | ディレクトリ
0020000 | キャラクタデバイス
0010000 | fifo
よって、たとえば 通常のファイルは 0100644 のような値になりますし、 ディレクトリは 0040755 のような値になります。

stat() はエラーの場合 false を返します。

注意: PHP の数値型は符号付整数であり、 多くのプラットフォームでは 32 ビットの整数を取るため、 ファイルシステム関数の中には 2GB より大きなファイルについては期待とは違う値を返すものがあります。

エラー / 例外

失敗した場合は E_WARNING が発生します。

変更履歴

バージョン | 説明
7.4.0 | Windows では、 デバイス番号は、ファイルが含まれるボリュームのシリアル番号を返すようになりました。 そして、inode 番号は、ファイルに関連付けられた識別子を返すようになりました。
7.4.0 | シンボリックリンクの場合、 size, atime, mtime, ctime の統計情報は、ファイルの実体の値が返されるようになりました。 これより前のバージョンの Windows NTS ビルドはそうではありませんでした。

例

例1 stat() の例

<?php
/* ファイルの状態を取得します */
$stat = stat('C:\php\php.exe');

/*
* ファイルのアクセス日時を表示します。
* これは fileatime() をコールするのと同じです
*/
echo 'アクセス日時: ' . $stat['atime'];

/*
* ファイルの更新日時を表示します。
* これは filemtime() をコールするのと同じです
*/
echo '更新日時: ' . $stat['mtime'];

/* デバイス番号を表示します */
echo 'デバイス番号: ' . $stat['dev'];
?>

例2 stat() の情報を touch() と組み合わせる例

<?php
/* ファイルの状態を取得します */
$stat = stat('C:\php\php.exe');

/* 情報の取得に失敗した? */
if (!$stat) {
echo 'stat() のコールに失敗しました...';
} else {
/*
* アクセス日時を、現在のアクセス日時の
* 一週間後に設定します
*/
$atime = $stat['atime'] + 604800;

/* ファイルを作成します */
if (!touch('some_file.txt', time(), $atime)) {
echo 'ファイルの作成に失敗しました...';
} else {
echo 'touch() が成功しました...';
}
}
?>

注意

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。

注意: この関数の結果は キャッシュされます。詳細は、clearstatcache() を参照してください。

ヒント

PHP 5.0.0 以降、この関数は、 何らかの URL ラッパーと組合せて使用することができます。 どのラッパーが stat() ファミリーをサポートしているかを調べるには サポートするプロトコル/ラッパー を参照してください。

参考

  • lstat() - ファイルあるいはシンボリックリンクの情報を取得する
  • fstat() - オープンしたファイルポインタからファイルに関する情報を取得する
  • filemtime() - ファイルの更新時刻を取得する
  • filegroup() - ファイルのグループを取得する
  • SplFileInfo


シンボリックリンクを作成する

  • ≪ stat
  • tempnam ≫
  • PHP Manual
  • ファイルシステム 関数
  • シンボリックリンクを作成する

symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — シンボリックリンクを作成する

説明

symlink(string $target, string $link): bool

symlink()は、指定されたリンク名 link で既存のファイル target へのシンボリックリンクを作成します。

パラメータ

target

リンクの対象。

link

リンクの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

link が既に存在する場合には、この関数は失敗し、 E_WARNING が発生します。 Windows では target が存在しない場合にも、この関数は失敗し、 E_WARNING が発生します。

例

例1 シンボリックリンクの作成

<?php
$target = 'uploads.php';
$link = 'uploads';
symlink($target, $link);

echo readlink($link);
?>

参考

  • link() - ハードリンクを作成する
  • readlink() - シンボリックリンク先を返す
  • linkinfo() - リンクに関する情報を取得する
  • unlink() - ファイルを削除する


一意なファイル名を生成する

  • ≪ symlink
  • tmpfile ≫
  • PHP Manual
  • ファイルシステム 関数
  • 一意なファイル名を生成する

tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — 一意なファイル名を生成する

説明

tempnam(string $directory, string $prefix): string|false

一意なテンポラリファイル名を、パーミッションを 0600 に設定し、 指定したディレクトリに作成します。 指定したディレクトリが存在しない場合やディレクトリに書き込めない場合は、tempnam() はシステムのテンポラリディレクトリにあるファイル名を生成し、 そのファイルへのフルパスを (名前を含めて) 返します。

パラメータ

directory

テンポラリファイルを作成したいディレクトリ。

prefix

作成されるテンポラリファイルのプレフィックス。

注意: プレフィックスの最初の63文字のみを使用し、残りは無視されます。 Windows では、プレフィックスの最初の 3 文字のみを使用します。

戻り値

新しいテンポラリファイル名 (パスを含む) を返し、失敗した場合には false を返します。

変更履歴

バージョン | 説明
7.1.0 | tempnam() は、 システムのテンポラリディレクトリにフォールバックした場合に 警告を生成するようになりました。

例

例1 tempnam() の例

<?php
$tmpfname = tempnam("/tmp", "FOO");

$handle = fopen($tmpfname, "w");
fwrite($handle, "writing to tempfile");
fclose($handle);

// ここで何か行う

unlink($tmpfname);
?>

注意

注意: PHP が指定されたパラメータ directory にファイルを生成することができない場合、 システム標準のフォールバックが実行されます。 NTFS では、指定した directory に 65534 を超える数のファイルが存在する場合にも同じことが起こります。

参考

  • tmpfile() - テンポラリファイルを作成する
  • sys_get_temp_dir() - 一時ファイル用に使用されるディレクトリのパスを返す
  • unlink() - ファイルを削除する


テンポラリファイルを作成する

  • ≪ tempnam
  • touch ≫
  • PHP Manual
  • ファイルシステム 関数
  • テンポラリファイルを作成する

tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — テンポラリファイルを作成する

説明

tmpfile(): resource|false

読み書き可、かつバイナリモード (w+b) でユニークな名前を有するテンポラリファイルを作成し、 ファイルハンドルを返します。

(fclose()を呼んだり、tmpfile() が返すファイルハンドルへの参照がなくなったりして) ファイルをクローズした場合や、スクリプトが終了したりしたときに、このファイルは自動的に削除されます。

警告

スクリプトが予期せず終了した場合、テンポラリファイルが削除されないかもしれません。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルのハンドルを返します。 これは、 fopen() により返されるハンドルと同じものです。 失敗した場合に false を返します。

例

例1 tmpfile() の例

<?php
$temp = tmpfile();
fwrite($temp, "writing to tempfile");
fseek($temp, 0);
echo fread($temp, 1024);
fclose($temp); // ファイルを削除します
?>

上の例の出力は以下となります。

writing to tempfile

参考

  • tempnam() - 一意なファイル名を生成する
  • sys_get_temp_dir() - 一時ファイル用に使用されるディレクトリのパスを返す


ファイルの最終アクセス時刻および最終更新日をセットする

  • ≪ tmpfile
  • umask ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルの最終アクセス時刻および最終更新日をセットする

touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — ファイルの最終アクセス時刻および最終更新日をセットする

説明

touch(string $filename, ?int $mtime = null, ?int $atime = null): bool

filename で指定されたファイルの最終更新日を、 mtime で指定された値に セットしようと試みます。 パラメータの数にかかわらず、アクセス時刻は 常に変更されることに注意しましょう。

ファイルが存在しない場合、ファイルが生成されます。

パラメータ

filename

処理したいファイルの名前。

mtime

設定する時刻。 mtime が null の場合は、 現在時刻 (time()) を使用します。

atime

この値が null でない場合、 指定されたファイルの最終アクセス時刻が atime にセットされます。 存在しない場合は mtime に渡した値となります。 どちらも null の場合は、現在のシステム時刻を使います。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | mtime と atime は、nullable になりました。

例

例1 touch() の例

<?php
if (touch($filename)) {
echo $filename . ' modification time has been changed to present time';
} else {
echo 'Sorry, could not change modification time of ' . $filename;
}
?>

例2 touch() で mtime パラメータを使用する例

<?php
// 作成時刻を、ここでは 1 時間前に設定します
$time = time() - 3600;

// ファイルを作成します
if (!touch('some_file.txt', $time)) {
echo 'おっと、何かがおかしいようです...';
} else {
echo 'ファイルの作成に成功しました';
}
?>

注意

注意:

時刻の精度は、 ファイルシステムによって異なることがあります。


現在の umask を変更する

  • ≪ touch
  • unlink ≫
  • PHP Manual
  • ファイルシステム 関数
  • 現在の umask を変更する

umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — 現在の umask を変更する

説明

umask(?int $mask = null): int

umask() は PHP の umask を mask & 0777 にセットし、 元の umask 値を返します。 PHP がサーバー・モジュールとして動作中の場合、 各リクエストが終了するたびに umask は元の値に戻されます。

パラメータ

mask

新しい umask。

戻り値

mask が null の場合、 umask()は単に現在の umask 値を返します。 そうでない場合、元の umask 値を返します。

変更履歴

バージョン | 説明
8.0.0 | mask は、nullable になりました。

例

例1 umask() の例

<?php
$old = umask(0);
chmod("/path/some_dir/some_file.txt", 0755);
umask($old);

// チェック
if ($old != umask()) {
die('An error occurred while changing back the umask');
}
?>

注意

注意:

マルチスレッドな Web サーバーでこの関数を使用することは避けてください。 ファイルを生成後、chmod() を使用してファイル権限を 変更するのがより良い方法です。全て同じ umask が使用されるので、 umask() の使用は、スクリプトを同時に実行する場合や Web サーバー自身の予期しない動作を引き起こす原因になる可能性があります。


ファイルを削除する

  • ≪ umask
  • Inotify ≫
  • PHP Manual
  • ファイルシステム 関数
  • ファイルを削除する

unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — ファイルを削除する

説明

unlink(string $filename, ?resource $context = null): bool

filename を削除します。 Unix C 言語の関数 unlink() と動作は同じです。 失敗した場合は E_WARNING レベルのエラーが発生します。

パラメータ

filename

ファイルへのパス。

ファイルがシンボリックリンクの場合、シンボリックリンクが削除されます。 Windows では、ディレクトリへのシンボリックリンクを削除するには rmdir() を使う必要があります。

context

ストリームコンテキストリソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | Windows で、使用中のハンドルを使ってファイルを unlink() できるようになりました。 これより前のバージョンでは、失敗していました。 但し、unlink されたファイルを再生成できるようになっているわけでは未だありません。 そうするには、全てのハンドルが閉じられている必要があります。

例

例1 基本的な unlink() の使用法

<?php
$fh = fopen('test.html', 'a');
fwrite($fh, '<h1>Hello world!</h1>');
fclose($fh);

unlink('test.html');
?>

参考

  • rmdir() - ディレクトリを削除する


Inotify

  • はじめに
  • インストール/設定
    • 要件
    • インストール/設定
    • リソース型
  • 定義済み定数
  • Inotify 関数
    • inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する
    • inotify_init — inotify インスタンスを初期化する
    • inotify_queue_len — 待機中のイベントがある場合に正の数を返す
    • inotify_read — inotify インスタンスからイベントを読み込む
    • inotify_rm_watch — 既存の監視を inotify インスタンスから削除する


はじめに

inotify 拡張モジュールは、inotify 関数 inotify_init()、 inotify_add_watch() および inotify_rm_watch() を公開しています。

C の inotify_init() 関数はファイル記述子を返しますが、PHP の
inotify_init() はストリームリソースを返します。これは、標準のストリーム関数
stream_select() や stream_set_blocking()、
fclose() などで利用することができます。
inotify_read() は、C の流儀での inotify イベントの読み込みを置き換えるものです。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Inotify
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール/設定
  • リソース型


  • ≪ インストール/設定
  • インストール/設定 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

この拡張モジュールには、Linux 2.6.13 以降と最新の libC が必要です。


インストール/設定

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/inotify.


  • ≪ インストール/設定
  • 定義済み定数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型

この拡張モジュールでは、 inotify_init() が返すストリームリソースを定義しています。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

inotify_add_watch() で使ったり inotify_read() が返したりする inotify 定数
IN_ACCESS (int)
ファイルがアクセスされた (読み込み) (*)
IN_MODIFY (int)
ファイルが変更された (*)
IN_ATTRIB (int)
メタデータ (パーミッションや修正時刻など) が変更された (*)
IN_CLOSE_WRITE (int)
書き込みモードで開いたファイルが閉じられた (*)
IN_CLOSE_NOWRITE (int)
非書き込みモードで開いたファイルが閉じられた (*)
IN_OPEN (int)
ファイルが開かれた (*)
IN_MOVED_TO (int)
ファイルが監視対象ディレクトリ内に移動された (*)
IN_MOVED_FROM (int)
ファイルが監視対象ディレクトリ外に移動された (*)
IN_CREATE (int)
ファイルあるいはディレクトリが監視対象ディレクトリ内で作成された (*)
IN_DELETE (int)
ファイルあるいはディレクトリが監視対象ディレクトリ内で削除された (*)
IN_DELETE_SELF (int)
監視対象のファイルあるいはディレクトリが削除された
IN_MOVE_SELF (int)
監視対象のファイルあるいはディレクトリが移動した
IN_CLOSE (int)
IN_CLOSE_WRITE | IN_CLOSE_NOWRITE と同等
IN_MOVE (int)
IN_MOVED_FROM | IN_MOVED_TO と同等
IN_ALL_EVENTS (int)
上記の定数すべてのビットマスク
IN_UNMOUNT (int)
監視対象オブジェクトを含むファイルシステムがアンマウントされた
IN_Q_OVERFLOW (int)
イベントキューがオーバーフローした (このイベントの監視記述子は -1)
IN_IGNORED (int)
監視が削除された (明示的に inotify_rm_watch() したか、ファイルが削除されたりファイルシステムがアンマウントされたりした)
IN_ISDIR (int)
このイベントの対象はディレクトリ
IN_ONLYDIR (int)
ディレクトリの場合はパス名のみを監視する (Linux 2.6.15 以降)
IN_DONT_FOLLOW (int)
シンボリックリンクの場合にパス名の参照先を解決しない (Linux 2.6.15 以降)
IN_MASK_ADD (int)
このパス名が既に存在する場合に、(マスクを上書きするのではなく) マスクにイベントを追加する
IN_ONESHOT (int)
単一のイベントについてのみパス名を監視し、その後は監視リストから削除する

注意: 上のイベントのうちアスタリスク (*) がついているものは、 監視対象ディレクトリ内のファイルごとに発生する可能性があります。


Inotify 関数

目次

  • inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する
  • inotify_init — inotify インスタンスを初期化する
  • inotify_queue_len — 待機中のイベントがある場合に正の数を返す
  • inotify_read — inotify インスタンスからイベントを読み込む
  • inotify_rm_watch — 既存の監視を inotify インスタンスから削除する


初期化済みの inotify インスタンスに監視対象を追加する

  • ≪ Inotify 関数
  • inotify_init ≫
  • PHP Manual
  • Inotify 関数
  • 初期化済みの inotify インスタンスに監視対象を追加する

inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する

説明

inotify_add_watch(resource $inotify_instance, string $pathname, int $mask): int|false

inotify_add_watch() は、pathname で指定したファイルあるいはディレクトリへの監視を追加あるいは変更します。

既存の監視対象に対して inotify_add_watch() を使用すると、 監視内容を上書きします。定数 IN_MASK_ADD を使用すると、 既存の監視対象を上書きせずにイベントを追加します。

パラメータ

inotify_instance

inotify_init() が返すリソース

pathname

監視対象のファイルあるいはディレクトリ。

mask

監視するイベント。定義済みの定数 を参照ください。

戻り値

戻り値は、(inotify インスタンス内で) 一意な監視記述子です。 失敗した場合に false を返します

参考

  • inotify_init() - inotify インスタンスを初期化する


inotify インスタンスを初期化する

  • ≪ inotify_add_watch
  • inotify_queue_len ≫
  • PHP Manual
  • Inotify 関数
  • inotify インスタンスを初期化する

inotify_init

(PECL inotify >= 0.1.2)

inotify_init — inotify インスタンスを初期化する

説明

inotify_init(): resource|false

inotify_add_watch() で使用するための inotify インスタンスを初期化します。

パラメータ

この関数にはパラメータはありません。

戻り値

ストリームリソース、あるいはエラー時に false を返します。

例

例1 inotify の使用例

<?php
// inotify インスタンスを開きます
$fd = inotify_init();

// __FILE__ のメタデータ (変更時刻など) の変更を監視します
$watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);

// イベントを発生させます
touch(__FILE__);

// イベントを読み込みます
$events = inotify_read($fd);
print_r($events);

// 以下の方法を使うと、inotify_read() でブロックせずに inotify 関数を使用できます

// - stream_select() を $fd で使用します
$read = array($fd);
$write = null;
$except = null;
stream_select($read,$write,$except,0);

// - stream_set_blocking() を $fd で使用します
stream_set_blocking($fd, 0);
inotify_read($fd); // ブロックしません。待ち状態のイベントがなければ false を返します

// - inotify_queue_len() を使用して、イベントキューが空でないかどうかを調べます
$queue_len = inotify_queue_len($fd); // If > 0, inotify_read() will not block

// __FILE__ のメタデータ変更の監視を終了します
inotify_rm_watch($fd, $watch_descriptor);

// inotify インスタンスを閉じます
// 未完了の監視があれば、それらもすべて閉じられます
fclose($fd);

?>

上の例の出力は、 たとえば以下のようになります。

array(
  array(
    'wd' => 1,     // Equals $watch_descriptor
    'mask' => 4,   // IN_ATTRIB bit is set
    'cookie' => 0, // unique id to connect related events (e.g.
                   // IN_MOVE_FROM and IN_MOVE_TO events)
    'name' => '',  // the name of a file (e.g. if we monitored changes
                   // in a directory)
  ),
);

参考

  • inotify_add_watch() - 初期化済みの inotify インスタンスに監視対象を追加する
  • inotify_rm_watch() - 既存の監視を inotify インスタンスから削除する
  • inotify_queue_len() - 待機中のイベントがある場合に正の数を返す
  • inotify_read() - inotify インスタンスからイベントを読み込む
  • fclose() - オープンされたファイルポインタをクローズする


待機中のイベントがある場合に正の数を返す

  • ≪ inotify_init
  • inotify_read ≫
  • PHP Manual
  • Inotify 関数
  • 待機中のイベントがある場合に正の数を返す

inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — 待機中のイベントがある場合に正の数を返す

説明

inotify_queue_len(resource $inotify_instance): int

この関数で、inotify_read() がブロックされるかどうかを知ることができます。 ゼロより大きい数が返された場合は待機中のイベントがあることを意味し、 この場合 inotify_read() はブロックされません。

パラメータ

inotify_instance

inotify_init() が返すリソース

戻り値

待機中のイベントがある場合に正の数を返します。

参考

  • inotify_init() - inotify インスタンスを初期化する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する


inotify インスタンスからイベントを読み込む

  • ≪ inotify_queue_len
  • inotify_rm_watch ≫
  • PHP Manual
  • Inotify 関数
  • inotify インスタンスからイベントを読み込む

inotify_read

(PECL inotify >= 0.1.2)

inotify_read — inotify インスタンスからイベントを読み込む

説明

inotify_read(resource $inotify_instance): array

inotify イベントを inotify インスタンスから読み込みます。

パラメータ

inotify_instance

inotify_init() が返すリソース

戻り値

inotify イベントの配列、を返します。待機中のイベントがなく、かつ inotify_instance が非ブロックモードである場合は false を返します。各イベントは次のキーを持つ配列となります。

  • wd は、inotify_add_watch() が返す監視記述子です
  • mask は、events のビットマスクです
  • cookie は、接続関連のイベント (たとえば IN_MOVE_FROM や IN_MOVE_TO) の一意な ID です
  • name は、ファイル名 (たとえば 監視対象のディレクトリ内でファイルが変更された場合) です

参考

  • inotify_init() - inotify インスタンスを初期化する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • inotify_queue_len() - 待機中のイベントがある場合に正の数を返す


既存の監視を inotify インスタンスから削除する

  • ≪ inotify_read
  • xattr ≫
  • PHP Manual
  • Inotify 関数
  • 既存の監視を inotify インスタンスから削除する

inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

説明

inotify_rm_watch(resource $inotify_instance, int $watch_descriptor): bool

inotify_rm_watch() は、 watch_descriptor がさす監視を inotify インスタンス inotify_instance から削除します。

パラメータ

inotify_instance

inotify_init() が返すリソース

watch_descriptor

インスタンスから削除したい監視。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • inotify_init() - inotify インスタンスを初期化する


xattr

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • xattr 関数
    • xattr_get — 拡張属性を取得する
    • xattr_list — 拡張属性の一覧を取得する
    • xattr_remove — 拡張属性を削除する
    • xattr_set — 拡張属性を設定する
    • xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる


  • ≪ xattr
  • インストール/設定 ≫
  • PHP Manual
  • xattr
  • はじめに

はじめに

xattr 拡張モジュールは、ファイルシステムの拡張属性を操作します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • xattr
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

xattr を使用するには、libattr がインストールされている必要があります。 これは » http://savannah.nongnu.org/projects/attr/ から取得可能です。

注意:

これらの関数は、ファイルシステムが拡張属性をサポートしており、 マウント時にそれを有効にしている場合にのみ動作します。 一般に使用されているファイルシステムのうち、拡張属性を サポートしているものには ext2, ext3, reiserfs, jfs, および xfs などがあります。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xattr.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XATTR_ROOT (int)
root (信頼された) 名前空間に属性を設定します。 root 権限が必要です。
XATTR_DONTFOLLOW (int)
シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_CREATE (int)
拡張属性が既に存在する場合、関数は失敗します。
XATTR_REPLACE (int)
拡張属性が存在しない場合、関数は失敗します。


xattr 関数

目次

  • xattr_get — 拡張属性を取得する
  • xattr_list — 拡張属性の一覧を取得する
  • xattr_remove — 拡張属性を削除する
  • xattr_set — 拡張属性を設定する
  • xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる


拡張属性を取得する

  • ≪ xattr 関数
  • xattr_list ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性を取得する

xattr_get

(PECL xattr >= 0.9.0)

xattr_get — 拡張属性を取得する

説明

xattr_get(string $filename, string $name, int $flags = 0): string

この関数は、ファイルの拡張属性の値を取得します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

属性を取得するファイル。

name

属性の名前。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

戻り値

値を含む文字列、あるいは属性が存在しない場合には false を返します。

例

例1 システム管理者がファイルに署名をしているかどうかを調べる

<?php
$file = '/usr/local/sbin/some_binary';
$signature = xattr_get($file, 'Root signature', XATTR_ROOT);

/* ... $signature が正しいものかどうかを調べます ... */

?>

参考

  • xattr_list() - 拡張属性の一覧を取得する
  • xattr_set() - 拡張属性を設定する
  • xattr_remove() - 拡張属性を削除する


拡張属性の一覧を取得する

  • ≪ xattr_get
  • xattr_remove ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性の一覧を取得する

xattr_list

(PECL xattr >= 0.9.0)

xattr_list — 拡張属性の一覧を取得する

説明

xattr_list(string $filename, int $flags = 0): array

この関数は、ファイルの拡張属性の名前の一覧を取得します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

ファイルのパス。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

戻り値

この関数は、拡張属性の名前を配列で返します。

例

例1 ファイルのすべての拡張属性の名前を表示する

<?php
$file = 'some_file';
$root_attributes = xattr_list($file, XATTR_ROOT);
$user_attributes = xattr_list($file);

echo "Root 属性: \n";
foreach ($root_attributes as $attr_name) {
printf("%s\n", $attr_name);
}

echo "\n User 属性: \n";
foreach ($attributes as $attr_name) {
printf("%s\n", $attr_name);
}

?>

参考

  • xattr_get() - 拡張属性を取得する


拡張属性を削除する

  • ≪ xattr_list
  • xattr_set ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性を削除する

xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — 拡張属性を削除する

説明

xattr_remove(string $filename, string $name, int $flags = 0): bool

この関数は、ファイルの拡張属性を削除します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

属性を削除するファイル。

name

削除する属性の名前。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルのすべての拡張属性を削除する

<?php
$file = 'some_file';
$attributes = xattr_list($file);

foreach ($attributes as $attr_name) {
xattr_remove($file, $attr_name);
}
?>

参考

  • xattr_list() - 拡張属性の一覧を取得する
  • xattr_set() - 拡張属性を設定する
  • xattr_get() - 拡張属性を取得する


拡張属性を設定する

  • ≪ xattr_remove
  • xattr_supported ≫
  • PHP Manual
  • xattr 関数
  • 拡張属性を設定する

xattr_set

(PECL xattr >= 0.9.0)

xattr_set — 拡張属性を設定する

説明

xattr_set(
string $filename,
string $name,
string $value,
int $flags = 0
): bool

この関数は、ファイルの拡張属性の値を設定します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 xattr はデフォルトでユーザー名前空間で処理を行いますが、 flags 引数によりこれを変更することができます。

パラメータ

filename

属性を設定するファイル。

name

拡張属性の名前。もし属性が存在しない場合は新しく作成され、 存在する場合は上書きされます。この振る舞いは、 flags パラメータを使用することで変更可能です。

value

属性の値。

flags

サポートされる xattr のフラグ
XATTR_CREATE | 拡張属性が既に存在する場合、関数は失敗します。
XATTR_REPLACE | 拡張属性が存在しない場合、関数は失敗します。
XATTR_DONTFOLLOW | シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。
XATTR_ROOT | root (信頼された) 名前空間に属性を設定します。root 権限が必要です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 .wav ファイルに拡張属性を設定する

<?php
$file = 'my_favourite_song.wav';
xattr_set($file, 'Artist', 'Someone');
xattr_set($file, 'My ranking', 'Good');
xattr_set($file, 'Listen count', '34');

/* ... その他のコード ... */

printf("あなたは、この曲を %d 回再生しました", xattr_get($file, 'Listen count'));
?>

参考

  • xattr_get() - 拡張属性を取得する
  • xattr_remove() - 拡張属性を削除する


ファイルシステムが拡張属性をサポートしているかどうかを調べる

  • ≪ xattr_set
  • xdiff ≫
  • PHP Manual
  • xattr 関数
  • ファイルシステムが拡張属性をサポートしているかどうかを調べる

xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

説明

xattr_supported(string $filename, int $flags = 0): bool

この関数は、指定したファイルを保持するファイルシステムが 拡張属性をサポートしているかどうかを調べます。ファイルに対する 読み込みアクセス権限が必要です。

パラメータ

filename

調べるファイルのパス。

flags

サポートされる xattr のフラグ
XATTR_DONTFOLLOW シンボリックリンクのリンク先をたどらず、リンクそのものを操作します。

戻り値

この関数は、ファイルシステムが拡張属性をサポートしている場合に true、 していない場合に false、そして判断できない場合 (たとえばパスが 間違っていたりファイルへのアクセス権限がない場合) には null を返します。

例

例1 xattr_supported() の例

以下のコードは、拡張属性が使用可能かどうかを調べます。

<?php
$file = 'some_file';

if (xattr_supported($file)) {
/* ... xattr_* 関数が使用できます ... */
}

?>

参考

  • xattr_get() - 拡張属性を取得する
  • xattr_list() - 拡張属性の一覧を取得する


xdiff

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • xdiff 関数
    • xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する
    • xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
    • xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する
    • xdiff_file_diff — 2 つのファイルの unified diff を作成する
    • xdiff_file_diff_binary — xdiff_file_bdiff のエイリアス
    • xdiff_file_merge3 — 3 つのファイルをひとつに統合する
    • xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する
    • xdiff_file_patch_binary — xdiff_file_bpatch のエイリアス
    • xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
    • xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する
    • xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
    • xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する
    • xdiff_string_diff — 2 つの文字列の unified diff を作成する
    • xdiff_string_diff_binary — xdiff_string_bdiff のエイリアス
    • xdiff_string_merge3 — 3 つの文字列をひとつに統合する
    • xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する
    • xdiff_string_patch_binary — xdiff_string_bpatch のエイリアス
    • xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する


はじめに

xdiff 拡張モジュールを使用すると、 異なるリビジョンのファイルの差分を含むパッチファイルの作成やその適用ができるようになります。

この拡張モジュールは、文字列に対する操作とファイルに対する操作の 2 通りのモードに対応しています。また、unified 形式とバイナリ形式の 2 通りのパッチフォーマットに対応しています。 Unified 形式のパッチはテキストファイルに最適です。 人間が読みやすい形式であることから、容易にレビューできるようになります。 アーカイブファイルや画像ファイルなどのバイナリファイルの場合は バイナリ形式を使うのがよいでしょう。この形式はバイナリセーフであり、 非表示文字も扱えるからです。

バージョン 1.5.0 以降、バイナリ形式のパッチを作成するための方法が 2 通り用意されています。新しい関数である xdiff_string_rabdiff() と xdiff_file_rabdiff() の出力は、 以前の関数と互換性のあるものとなります。 しかし、より高速でよりサイズが小さいものとなります。 どのようにバイナリパッチを作成しているのかや これまでの関数とどのように違うのかといった情報については » libxdiff のウェブサイトを参照ください。

この拡張モジュールは、libxdiff を用いてこれらの機能を実装しています。 詳細な情報は » http://www.xmailserver.org/xdiff-lib.html を参照ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • xdiff
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

xdiff を使用するには libxdiff がインストールされている必要があります。 これは libxdiff のホームページ » http://www.xmailserver.org/xdiff-lib.html で取得可能です。

注意:

memory_limit を考慮してこれらの関数を使用するには、すくなくとも libxdiff 0.7 が必要です。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xdiff.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XDIFF_PATCH_NORMAL (int)
このフラグは、xdiff_string_patch() 関数および xdiff_file_patch() 関数が元のファイルにパッチを適用して新しいバージョンのファイルを作成することを意味します。 デフォルトの操作モードです。
XDIFF_PATCH_REVERSE (int)
このフラグは、xdiff_string_patch() 関数および xdiff_file_patch() 関数がパッチを逆に適用し、新しいバージョンから元のバージョンを作成することを意味します。


xdiff 関数

目次

  • xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
  • xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する
  • xdiff_file_diff — 2 つのファイルの unified diff を作成する
  • xdiff_file_diff_binary — xdiff_file_bdiff のエイリアス
  • xdiff_file_merge3 — 3 つのファイルをひとつに統合する
  • xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する
  • xdiff_file_patch_binary — xdiff_file_bpatch のエイリアス
  • xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
  • xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む
  • xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する
  • xdiff_string_diff — 2 つの文字列の unified diff を作成する
  • xdiff_string_diff_binary — xdiff_string_bdiff のエイリアス
  • xdiff_string_merge3 — 3 つの文字列をひとつに統合する
  • xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する
  • xdiff_string_patch_binary — xdiff_string_bpatch のエイリアス
  • xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する


2 つのファイルのバイナリ diff を作成する

  • ≪ xdiff 関数
  • xdiff_file_bdiff_size ≫
  • PHP Manual
  • xdiff 関数
  • 2 つのファイルのバイナリ diff を作成する

xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する

説明

xdiff_file_bdiff(string $old_file, string $new_file, string $dest): bool

ふたつのファイルのバイナリ diff を作成し、その結果をパッチファイルとして保存します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_file_bpatch()/xdiff_string_bpatch() を使用します。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。 "旧" ファイルと "新" ファイルの差分がこのファイルの内容となります。 このファイルはバイナリフォーマットで、人間には読めない形式です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_bdiff() の例

以下のコードは 2 つのアーカイブのバイナリ diff を作成します。

<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';

xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
?>

注意

注意:

両方のファイルがメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する


バイナリ diff を適用して作成するファイルのサイズを読み込む

  • ≪ xdiff_file_bdiff
  • xdiff_file_bpatch ≫
  • PHP Manual
  • xdiff 関数
  • バイナリ diff を適用して作成するファイルのサイズを読み込む

xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む

説明

xdiff_file_bdiff_size(string $file): int

ファイル file のバイナリパッチを 元ファイルに適用して作成するファイルのサイズを返します。

パラメータ

file

xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() 関数で作成したバイナリパッチファイルへのパス。

戻り値

作成されるファイルのサイズを返します。

例

例1 xdiff_file_bdiff_size() の例

次のコードは、バイナリ diff を適用してできあがるファイルのサイズを読み込みます。

<?php
$length = xdiff_string_bdiff_size('file.bdiff');
echo "Resulting file will be $length bytes long";
?>

参考

  • xdiff_file_bdiff() - 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_rabdiff() - 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する


ファイルにバイナリ diff 形式のパッチを適用する

  • ≪ xdiff_file_bdiff_size
  • xdiff_file_diff ≫
  • PHP Manual
  • xdiff 関数
  • ファイルにバイナリ diff 形式のパッチを適用する

xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する

説明

xdiff_file_bpatch(string $file, string $patch, string $dest): bool

ファイル file にバイナリ形式のパッチファイル patch を適用し、結果をファイル dest に保存します。 この関数は、xdiff_file_bdiff() 関数あるいは xdiff_file_rabdiff()、 そしてそれぞれの文字列版が作成したパッチを受け取ることができます。

パラメータ

file

元のファイル。

patch

バイナリのパッチファイル。

dest

結果のファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_bpatch() の例

以下のコードはバイナリ diff 形式のパッチをファイルに適用します。

<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';

$result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
echo "パッチが適用されました";
} else {
echo "パッチが適用できませんでした";
}

?>

注意

注意:

両方のファイル (file および patch) がメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bdiff() - 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_rabdiff() - 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する


2 つのファイルの unified diff を作成する

  • ≪ xdiff_file_bpatch
  • xdiff_file_diff_binary ≫
  • PHP Manual
  • xdiff 関数
  • 2 つのファイルの unified diff を作成する

xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — 2 つのファイルの unified diff を作成する

説明

xdiff_file_diff(
string $old_file,
string $new_file,
string $dest,
int $context = 3,
bool $minimal = false
): bool

old_file と new_file の差分を含む unified diff を作成し、ファイル dest に保存します。結果は可読形式のファイルとなります。 オプションのパラメータ context で、 変更部分の前後にどれだけの行を含めるかを指定します。 パラメータ minimal を true にすると、 できる限り短い長さのパッチファイルを出力します (長い時間がかかります)。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。

context

diff の結果の前後に含める行の数を指定します。

minimal

このパラメータを true にすると、結果のファイルが最小になります (長い時間がかかります)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_diff() の例

以下のコードは 2 つの php ファイルの unified diff を context length 2 で作成します。

<?php
$old_version = 'my_script.php';
$new_version = 'my_new_script.php';

xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
?>

注意

注意:

この関数はバイナリファイルに対しては動作しません。バイナリファイルの 差分を作成するには xdiff_file_bdiff()/xdiff_file_rabdiff() 関数を使用してください。

参考

  • xdiff_file_patch() - ファイルに unified diff 形式のパッチを適用する


xdiff_file_bdiff のエイリアス

  • ≪ xdiff_file_diff
  • xdiff_file_merge3 ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_file_bdiff のエイリアス

xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — xdiff_file_bdiff() のエイリアス

説明

xdiff_file_diff_binary(string $old_file, string $new_file, string $dest): bool

ふたつのファイルのバイナリ diff を作成し、その結果をパッチファイルとして保存します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_file_bpatch(). を使用します。

バージョン 1.5.0 以降では、この関数は xdiff_file_bdiff() のエイリアスです。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。 "旧" ファイルと "新" ファイルの差分がこのファイルの内容となります。 このファイルはバイナリフォーマットで、人間には読めない形式です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_diff_binary() の例

以下のコードは 2 つのアーカイブのバイナリ diff を作成します。

<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';

xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
?>

注意

注意:

両方のファイルがメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bdiff() - 2 つのファイルのバイナリ diff を作成する
  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する


3 つのファイルをひとつに統合する

  • ≪ xdiff_file_diff_binary
  • xdiff_file_patch ≫
  • PHP Manual
  • xdiff 関数
  • 3 つのファイルをひとつに統合する

xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — 3 つのファイルをひとつに統合する

説明

xdiff_file_merge3(
string $old_file,
string $new_file1,
string $new_file2,
string $dest
): mixed

3 つのファイルをひとつに統合し、結果をファイル dest に保存します。 old_file が元のバージョンで、new_file1 と new_file2 が修正したバージョンとなります。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file1

2 番目のファイルへのパス。old_file の修正版です。

new_file2

3 番目のファイルへのパス。old_file の修正版です。

dest

結果のファイルへのパス。new_file1 と new_file2 の両方の変更点をマージした結果が保存されます。

戻り値

成功した場合に true 、もし拒否された部分がある場合にはその文字列、 内部エラーが発生した場合に false を返します。

例

例1 xdiff_file_merge3() の例

以下のコードは、3 つのファイルをひとつに統合します。

<?php
$old_version = 'original_script.php';
$fix1 = 'script_with_fix1.php';
$fix2 = 'script_with_fix2.php';

$errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>

参考

  • xdiff_string_merge3() - 3 つの文字列をひとつに統合する


ファイルに unified diff 形式のパッチを適用する

  • ≪ xdiff_file_merge3
  • xdiff_file_patch_binary ≫
  • PHP Manual
  • xdiff 関数
  • ファイルに unified diff 形式のパッチを適用する

xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する

説明

xdiff_file_patch(
string $file,
string $patch,
string $dest,
int $flags = DIFF_PATCH_NORMAL
): mixed

ファイル file にパッチファイル patch を適用し、結果をファイルに保存します。 patch は、 xdiff_file_diff()/xdiff_string_diff() 関数で作成した unified diff 形式でなければなりません。 オプションのパラメータ flags で、操作モードを指定します。

パラメータ

file

元のファイル。

patch

unified 形式のパッチファイル。 xdiff_string_diff() 関数や xdiff_file_diff() 関数、 あるいは互換性のあるツールで作成したものでなければなりません。

dest

結果のファイルへのパス。

flags

XDIFF_PATCH_NORMAL（デフォルト。通常のパッチ）あるいは XDIFF_PATCH_REVERSE（逆パッチ） のいずれか。

バージョン 1.5.0 以降では、バイナリ OR を使用して XDIFF_PATCH_IGNORESPACE フラグを有効にすることもできます。

戻り値

内部エラーが発生した場合に false を返します。 パッチの適用に失敗した場合はパッチが拒否された部分の文字列、 そして成功した場合は true を返します。

例

例1 xdiff_file_patch() の例

以下のコードは、unified diff 形式のパッチをファイルに適用します。

<?php
$old_version = 'my_script-1.0.php';
$patch = 'my_script.patch';

$errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}

?>

例2 逆パッチの例

以下のコードは、パッチを逆方向に適用します。

<?php
$new_version = 'my_script-1.1.php';
$patch = 'my_script.patch';

$errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}

?>

参考

  • xdiff_file_diff() - 2 つのファイルの unified diff を作成する


xdiff_file_bpatch のエイリアス

  • ≪ xdiff_file_patch
  • xdiff_file_rabdiff ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_file_bpatch のエイリアス

xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — xdiff_file_bpatch() のエイリアス

説明

xdiff_file_patch_binary(string $file, string $patch, string $dest): bool

ファイル file にバイナリ形式のパッチファイル patch を適用し、結果をファイル dest に保存します。 この関数は、xdiff_file_bdiff() 関数あるいは xdiff_file_rabdiff()、 そしてそれぞれの文字列版が作成したパッチを受け取ることができます。

バージョン 1.5.0 以降、この関数は xdiff_file_bpatch() のエイリアスとなりました。

パラメータ

file

元のファイル。

patch

バイナリのパッチファイル。

dest

結果のファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_patch_binary() の例

以下のコードはバイナリ diff 形式のパッチをファイルに適用します。

<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';

$result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
echo "パッチが適用されました";
} else {
echo "パッチが適用できませんでした";
}

?>

注意

注意:

両方のファイル (file および patch) がメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_string_patch_binary() - xdiff_string_bpatch のエイリアス


2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

  • ≪ xdiff_file_patch_binary
  • xdiff_string_bdiff ≫
  • PHP Manual
  • xdiff 関数
  • 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

説明

xdiff_file_rabdiff(string $old_file, string $new_file, string $dest): bool

ふたつのファイルのバイナリ diff を作成し、その結果をパッチファイルとして保存します。 この関数と xdiff_file_bdiff() との違いは、 使用するアルゴリズムです。この関数のほうが実行速度が速く、より小さな diff を生成します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_file_bpatch()/xdiff_string_bpatch() を使用します。

アルゴリズムの違いについての詳細は、 » libxdiff のウェブサイトを参照ください。

パラメータ

old_file

最初のファイルへのパス。"旧" ファイルです。

new_file

2 番目のファイルへのパス。"新" ファイルです。

dest

結果のパッチファイルへのパス。 "旧" ファイルと "新" ファイルの差分がこのファイルの内容となります。 このファイルはバイナリフォーマットで、人間には読めない形式です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 xdiff_file_rabdiff() の例

以下のコードは 2 つのアーカイブのバイナリ diff を作成します。

<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';

xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
?>

注意

注意:

両方のファイルがメモリに読み込まれるので、 memory_limit が十分大きな値に設定されていることを確認しましょう。

参考

  • xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する


2 つの文字列のバイナリ diff を作成する

  • ≪ xdiff_file_rabdiff
  • xdiff_string_bdiff_size ≫
  • PHP Manual
  • xdiff 関数
  • 2 つの文字列のバイナリ diff を作成する

xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する

説明

xdiff_string_bdiff(string $old_data, string $new_data): string

ふたつの文字列のバイナリ diff を作成して結果を返します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_string_bpatch()/xdiff_file_bpatch() を使用します。

パラメータ

old_data

バイナリデータを含む最初の文字列。"旧" データです。

new_data

バイナリデータを含む 2 番目の文字列。"新" データです。

戻り値

"旧" データと "新" データの差分を含むバイナリ diff 文字列、 あるいは内部エラーが発生した場合は false を返します。

参考

  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する


バイナリ diff を適用して作成するファイルのサイズを読み込む

  • ≪ xdiff_string_bdiff
  • xdiff_string_bpatch ≫
  • PHP Manual
  • xdiff 関数
  • バイナリ diff を適用して作成するファイルのサイズを読み込む

xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む

説明

xdiff_string_bdiff_size(string $patch): int

バイナリパッチ patch を元ファイルに適用して作成するファイルのサイズを返します。

パラメータ

patch

xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() 関数で作成したバイナリパッチ。

戻り値

作成されるファイルのサイズを返します。

例

例1 xdiff_string_bdiff_size() の例

次のコードは、バイナリ diff を適用してできあがるファイルのサイズを読み込みます。

<?php
$binary_patch = file_get_contents('file.bdiff');
$length = xdiff_string_bdiff_size($binary_patch);
echo "Resulting file will be $length bytes long";
?>

参考

  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_rabdiff() - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する


文字列にバイナリ diff 形式のパッチを適用する

  • ≪ xdiff_string_bdiff_size
  • xdiff_string_diff ≫
  • PHP Manual
  • xdiff 関数
  • 文字列にバイナリ diff 形式のパッチを適用する

xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する

説明

xdiff_string_bpatch(string $str, string $patch): string

文字列 str に、バイナリ形式のパッチ patch を適用します。 この関数は、xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() そしてそれぞれのファイル版が作成したパッチを受け取ることができます。

パラメータ

str

元のバイナリ文字列。

patch

バイナリパッチ文字列。

戻り値

パッチ適用後の文字列、あるいはエラー時に false を返します。

参考

  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_rabdiff() - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する


2 つの文字列の unified diff を作成する

  • ≪ xdiff_string_bpatch
  • xdiff_string_diff_binary ≫
  • PHP Manual
  • xdiff 関数
  • 2 つの文字列の unified diff を作成する

xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — 2 つの文字列の unified diff を作成する

説明

xdiff_string_diff(
string $old_data,
string $new_data,
int $context = 3,
bool $minimal = false
): string

old_data 文字列と new_data 文字列の差分を含む unified diff を作成し、 結果を返します。結果は可読形式となります。 オプションのパラメータ context で、 変更部分の前後にどれだけの行を含めるかを指定します。 パラメータ minimal を true にすると、 できる限り短い長さのパッチファイルを出力します (長い時間がかかります)。

パラメータ

old_data

データを含む最初の文字列。"旧" データです。

new_data

データを含む 2 番目の文字列。"新" データです。

context

diff の結果の前後に含める行の数を指定します。

minimal

このパラメータを true にすると、結果のファイルが最小になります (非常に時間がかかります)。結果のファイルは可読形式となります。

戻り値

成功した場合はその結果の diff、内部エラーが発生した場合に false を返します。

例

例1 xdiff_string_diff() の例

以下のコードは 2 つの記事の unified diff を作成します。

<?php
$old_article = file_get_contents('./old_article.txt');
$new_article = $_REQUEST['article']; /* Let's say that someone pasted a new article to html form */

$diff = xdiff_string_diff($old_article, $new_article, 1);
if (is_string($diff)) {
echo "2 つの記事の差分:\n";
echo $diff;
}

?>

注意

注意:

この関数はバイナリ文字列に対しては動作しません。バイナリ文字列の 差分を作成するには xdiff_string_bdiff()/xdiff_string_rabdiff() を使用してください。

参考

  • xdiff_string_patch() - 文字列に unified diff 形式のパッチを適用する


xdiff_string_bdiff のエイリアス

  • ≪ xdiff_string_diff
  • xdiff_string_merge3 ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_string_bdiff のエイリアス

xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — xdiff_string_bdiff() のエイリアス

説明

xdiff_string_bdiff(string $old_data, string $new_data): string

ふたつの文字列のバイナリ diff を作成して結果を返します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_string_bpatch()/xdiff_file_bpatch() を使用します。

バージョン 1.5.0 以降では、この関数は xdiff_string_bdiff() のエイリアスです。

パラメータ

old_data

バイナリデータを含む最初の文字列。"旧" データです。

new_data

バイナリデータを含む 2 番目の文字列。"新" データです。

戻り値

成功した場合に結果の文字列、内部エラーが発生した場合に false を返します。

参考

  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する


3 つの文字列をひとつに統合する

  • ≪ xdiff_string_diff_binary
  • xdiff_string_patch ≫
  • PHP Manual
  • xdiff 関数
  • 3 つの文字列をひとつに統合する

xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — 3 つの文字列をひとつに統合する

説明

xdiff_string_merge3(
string $old_data,
string $new_data1,
string $new_data2,
string &$error = ?
): mixed

3 つの文字列をひとつに結合し、その結果を返します。 old_data が元のバージョンで、 new_data1 と new_data2 が修正したバージョンとなります。オプションの error を使用すると、結合時に拒否された部分がそこに渡されます。

パラメータ

old_data

最初のデータ文字列。"旧" データです。

new_data1

2 番目のデータ文字列。old_data の修正版です。

new_data2

3 番目のデータ文字列。old_data の修正版です。

error

指定した場合、パッチを拒否された部分がこの変数に保存されます。

戻り値

統合された文字列を返します。内部エラーが発生した場合は false、 統合された文字列が空の文字列の場合は true を返します。

参考

  • xdiff_file_merge3() - 3 つのファイルをひとつに統合する


文字列に unified diff 形式のパッチを適用する

  • ≪ xdiff_string_merge3
  • xdiff_string_patch_binary ≫
  • PHP Manual
  • xdiff 関数
  • 文字列に unified diff 形式のパッチを適用する

xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する

説明

xdiff_string_patch(
string $str,
string $patch,
int $flags = ?,
string &$error = ?
): string

ある文字列 str に、unified 形式のパッチ文字列 patch を適用してその結果を返します。 patch は、 xdiff_file_diff()/xdiff_string_diff() 関数で作成した unified diff 形式でなければなりません。 オプションのパラメータ flags で、操作モードを指定します。パッチが拒否された部分については、 もし error を指定していればそこに保存されます。

パラメータ

str

元の文字列。

patch

unified 形式のパッチ文字列。 xdiff_string_diff() 関数や xdiff_file_diff() 関数、 あるいは互換性のあるツールで作成したものでなければなりません。

flags

flags は XDIFF_PATCH_NORMAL (デフォルト。通常のパッチ) あるいは XDIFF_PATCH_REVERSE (逆パッチ) のいずれかです。

バージョン 1.5.0 以降では、バイナリ OR を使用して XDIFF_PATCH_IGNORESPACE フラグを有効にすることもできます。

error

これを指定すると、パッチを拒否された部分がここに保存されます。

戻り値

パッチ適用後の文字列、あるいはエラー時に false を返します。

例

例1 xdiff_string_patch() の例

以下のコードは、ある記事に対して変更を適用します。

<?php
$old_article = file_get_contents('./old_article.txt');
$diff = $_SERVER['patch']; /* だれかが html フォームからパッチを投稿したとしましょう */

$errors = '';

$new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
if (is_string($new_article)) {
echo "新しい記事:\n";
echo $new_article;
}

if (strlen($errors)) {
echo "Rejects: \n";
echo $errors;
}

?>

参考

  • xdiff_string_diff() - 2 つの文字列の unified diff を作成する


xdiff_string_bpatch のエイリアス

  • ≪ xdiff_string_patch
  • xdiff_string_rabdiff ≫
  • PHP Manual
  • xdiff 関数
  • xdiff_string_bpatch のエイリアス

xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — xdiff_string_bpatch() のエイリアス

説明

xdiff_string_patch_binary(string $str, string $patch): string

文字列 str に、バイナリ形式のパッチ patch を適用します。 この関数は、xdiff_string_bdiff() 関数あるいは xdiff_string_rabdiff() そしてそれぞれのファイル版が作成したパッチを受け取ることができます。

バージョン 1.5.0 以降、この関数は xdiff_string_bpatch() のエイリアスとなりました。

パラメータ

str

元のバイナリ文字列。

patch

バイナリパッチ文字列。

戻り値

パッチ適用後の文字列、あるいはエラー時に false を返します。

参考

  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する
  • xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
  • xdiff_string_rabdiff() - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する


2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

  • ≪ xdiff_string_patch_binary
  • 自然言語および文字エンコーディング ≫
  • PHP Manual
  • xdiff 関数
  • 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

説明

xdiff_string_bdiff(string $old_data, string $new_data): string

ふたつの文字列のバイナリ diff を作成して結果を返します。 この関数と xdiff_string_bdiff() との違いは、 使用するアルゴリズムです。この関数のほうが実行速度が速く、より小さな diff を生成します。 この関数はテキストファイルとバイナリファイルの両方に適用可能です。 できあがったパッチファイルを後で適用するには xdiff_string_bpatch()/xdiff_file_bpatch() を使用します。

アルゴリズムの違いについての詳細は、 » libxdiff のウェブサイトを参照ください。

パラメータ

old_data

バイナリデータを含む最初の文字列。"旧" データです。

new_data

バイナリデータを含む 2 番目の文字列。"新" データです。

戻り値

"旧" データと "新" データの差分を含むバイナリ diff 文字列、 あるいは内部エラーが発生した場合は false を返します。

参考

  • xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する


自然言語および文字エンコーディング

  • Enchant — Enchant スペリングライブラリ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Enchant 関数
    • EnchantBroker — EnchantBroker クラス
    • EnchantDictionary — EnchantDictionary クラス
  • Gender — 名前の性別の判別
    • はじめに
    • インストール/設定
    • 例
    • Gender\Gender — Gender\Gender クラス
  • Gettext
    • はじめに
    • インストール/設定
    • Gettext 関数
  • iconv
    • はじめに
    • インストール/設定
    • 定義済み定数
    • iconv 関数
  • intl — 国際化関数
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Collator — Collator クラス
    • NumberFormatter — NumberFormatter クラス
    • Locale — Locale クラス
    • Normalizer — Normalizer クラス
    • MessageFormatter — MessageFormatter クラス
    • IntlCalendar — IntlCalendar クラス
    • IntlGregorianCalendar — IntlGregorianCalendar クラス
    • IntlTimeZone — IntlTimeZone クラス
    • IntlDateFormatter — IntlDateFormatter クラス
    • ResourceBundle — ResourceBundle クラス
    • Spoofchecker — Spoofchecker クラス
    • Transliterator — Transliterator クラス
    • IntlBreakIterator — IntlBreakIterator クラス
    • IntlRuleBasedBreakIterator — IntlRuleBasedBreakIterator クラス
    • IntlCodePointBreakIterator — IntlCodePointBreakIterator クラス
    • IntlDatePatternGenerator — IntlDatePatternGenerator クラス
    • IntlPartsIterator — IntlPartsIterator クラス
    • UConverter — UConverter クラス
    • Grapheme 関数
    • IDN 関数
    • IntlChar — IntlChar クラス
    • IntlException — intl のエラー用の例外クラス
    • IntlIterator — IntlIterator クラス
    • 国際化 関数
  • マルチバイト文字列
    • はじめに
    • インストール/設定
    • 定義済み定数
    • サポートされるエンコーディングの概要
    • 日本語のマルチバイト文字に関する基本事項
    • HTTP 入出力
    • サポートされる文字エンコーディング
    • 関数のオーバーロード機能
    • PHP の文字エンコーディングに関する要件
    • マルチバイト文字列 関数
  • Pspell
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Pspell 関数
    • PSpell\Dictionary — PSpell\Dictionary クラス
    • PSpell\Config — PSpell\Config クラス
  • Recode — GNU Recode
    • はじめに
    • インストール/設定
    • Recode 関数


Enchant スペリングライブラリ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
  • Enchant 関数
    • enchant_broker_describe — Enchant プロバイダを列挙する
    • enchant_broker_dict_exists — 辞書が存在するかどうかを調べる。空でないタグを使用する
    • enchant_broker_free — ブローカーリソースおよびその辞書を開放する
    • enchant_broker_free_dict — 辞書リソースを開放する
    • enchant_broker_get_dict_path — 指定されたバックエンドの辞書のパスを取得する
    • enchant_broker_get_error — ブローカーの直近のエラーを返す
    • enchant_broker_init — 要求を満たすブローカーオブジェクトを作成する
    • enchant_broker_list_dicts — 使用可能な辞書の一覧を返す
    • enchant_broker_request_dict — タグを使用して新しい辞書を作成する
    • enchant_broker_request_pwl_dict — PWL ファイルを使用して辞書を作成する
    • enchant_broker_set_dict_path — 指定されたバックエンドの辞書のパスを設定する
    • enchant_broker_set_ordering — その言語で使用する辞書の優先順位を宣言する
    • enchant_dict_add — 単語リストに単語を追加する
    • enchant_dict_add_to_personal — のエイリアス enchant_dict_add
    • enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する
    • enchant_dict_check — 単語のスペルが正しいかどうかを調べる
    • enchant_dict_describe — 個々の辞書について説明する
    • enchant_dict_get_error — 現在のスペリングセッションの直近のエラーを返す
    • enchant_dict_is_added — 現在のセッションに、単語が存在するかどうかを調べる
    • enchant_dict_is_in_session — のエイリアス enchant_dict_is_added
    • enchant_dict_quick_check — 単語のスペルが正しいかどうかを調べ、修正候補を提供する
    • enchant_dict_store_replacement — 単語の修正候補を追加する
    • enchant_dict_suggest — 修正候補となる値の一覧を返す
  • EnchantBroker — EnchantBroker クラス
  • EnchantDictionary — EnchantDictionary クラス


はじめに

Enchant は、» Enchant ライブラリ を PHP から利用できるようにしたものです。Enchant は、 すべてのスペリングライブラリの上位に位置するもので、 統一された操作性を提供します。 また、各ライブラリが搭載していないかもしれない機能についても実装しています。 すべての機能が "動作します"。 いろんな意味で、あらゆる意味で "動作しています"。

Enchant は以下のバックエンドをサポートしています。

  • Aspell/Pspell (Ispell の後継です)

  • Ispell (昔からあり、デファクトスタンダードとされています)

  • MySpell/Hunspell (OOo プロジェクトや Mozilla が使用しています)

  • Uspell (イディッシュ語、ヘブライ語および東欧諸国語用のもので、AbiWord の CVS 内で "uspell" モジュールとしてホストされています)

  • Hspell (ヘブライ語)

  • AppleSpell (Mac OSX)


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Enchant
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

このバージョンは、Dom Lachowicz による » Enchant ライブラリ の関数を使用しています。 Enchant 1.2.4 以降が必要です。 Enchant 2.0.0 以降は、PHP 8.0.0 以降でのみサポートされています。

Enchant には » Glib 2.6 以降も必要です。 Windows 用のコンパイル済みのライブラリは » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/ にあります。


インストール手順

必須ライブラリ がインストールされていれば、PHP のコンパイル時に --with-enchant[=dir] オプションを追加するだけで enchant を有効にできます。

Windows ユーザーがこの拡張モジュールを使うには、 php_enchant.dll を有効にしなければいけません。

注意: Windows で必要な追加のセットアップ

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libenchant.dll, glib-2.dll, gmodule-2.dll.

さらに、 lib/enchant/ に同梱されている プロバイダを少なくともひとつ、 \usr\local\lib\enchant-2 にコピーする必要があります (これは、現在のドライブ のルートからの絶対パスです)。 PHP 8.0.0 より前のバージョン、 つまり Enchant v1 では、 プロバイダを C:\enchant_plugins にコピーする必要がありました。 このパスは、レジストリ HKEY_CURRENT_USER\SOFTWARE\Enchant\Config\Module_Dir の値を任意のパスに設定することでカスタマイズできます。


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張モジュールでは二種類のリソースを使用しています。ひとつは ブローカー (バックエンドマネージャ) で、もうひとつが辞書です。


定義済み定数

LIBENCHANT_VERSION (string)
libenchant のバージョン。 PHP 8.0.0 以降で利用可能です。
ENCHANT_MYSPELL (int)
MySpell 用の辞書の型。 enchant_broker_get_dict_path() や enchant_broker_set_dict_path() で利用します。 PHP 8.0.0 以降では推奨されません。
ENCHANT_ISPELL (int)
Ispell 用の辞書の型。 enchant_broker_get_dict_path() や enchant_broker_set_dict_path() で利用します。 PHP 8.0.0 以降では推奨されません。


例

例1 Enchant の使用例

<?php
$tag = 'en_US';
$r = enchant_broker_init();
$bprovides = enchant_broker_describe($r);
echo "現在のブローカーは、次のバックエンドを提供します。\n";
print_r($bprovides);

$dicts = enchant_broker_list_dicts($r);
print_r($dicts);
if (enchant_broker_dict_exists($r,$tag)) {
$d = enchant_broker_request_dict($r, $tag);
$dprovides = enchant_dict_describe($d);
echo "dictionary $tag provides:\n";
$wordcorrect = enchant_dict_check($d, "soong");
print_r($dprovides);
if (!$wordcorrect) {
$suggs = enchant_dict_suggest($d, "soong");
echo "'soong' の修正候補:";
print_r($suggs);
}
enchant_broker_free_dict($d);
} else {
}
enchant_broker_free($r);
?>


Enchant 関数

目次

  • enchant_broker_describe — Enchant プロバイダを列挙する
  • enchant_broker_dict_exists — 辞書が存在するかどうかを調べる。空でないタグを使用する
  • enchant_broker_free — ブローカーリソースおよびその辞書を開放する
  • enchant_broker_free_dict — 辞書リソースを開放する
  • enchant_broker_get_dict_path — 指定されたバックエンドの辞書のパスを取得する
  • enchant_broker_get_error — ブローカーの直近のエラーを返す
  • enchant_broker_init — 要求を満たすブローカーオブジェクトを作成する
  • enchant_broker_list_dicts — 使用可能な辞書の一覧を返す
  • enchant_broker_request_dict — タグを使用して新しい辞書を作成する
  • enchant_broker_request_pwl_dict — PWL ファイルを使用して辞書を作成する
  • enchant_broker_set_dict_path — 指定されたバックエンドの辞書のパスを設定する
  • enchant_broker_set_ordering — その言語で使用する辞書の優先順位を宣言する
  • enchant_dict_add — 単語リストに単語を追加する
  • enchant_dict_add_to_personal — のエイリアス enchant_dict_add
  • enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する
  • enchant_dict_check — 単語のスペルが正しいかどうかを調べる
  • enchant_dict_describe — 個々の辞書について説明する
  • enchant_dict_get_error — 現在のスペリングセッションの直近のエラーを返す
  • enchant_dict_is_added — 現在のセッションに、単語が存在するかどうかを調べる
  • enchant_dict_is_in_session — のエイリアス enchant_dict_is_added
  • enchant_dict_quick_check — 単語のスペルが正しいかどうかを調べ、修正候補を提供する
  • enchant_dict_store_replacement — 単語の修正候補を追加する
  • enchant_dict_suggest — 修正候補となる値の一覧を返す


Enchant プロバイダを列挙する

  • ≪ Enchant 関数
  • enchant_broker_dict_exists ≫
  • PHP Manual
  • Enchant 関数
  • Enchant プロバイダを列挙する

enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enchant プロバイダを列挙する

説明

enchant_broker_describe(EnchantBroker $broker): array

Enchant プロバイダを列挙し、その基本情報を通知します。 同じ情報が phpinfo() からでも取得できます。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

戻り値

利用可能な Enchant プロバイダの一覧と、その詳細を array として返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | このバージョンより前では、この関数は失敗時に false を返していました。

例

例1 指定したブローカーが提供するバックエンドの一覧

<?php
$r = enchant_broker_init();
$bprovides = enchant_broker_describe($r);
echo "現在のブローカーは、次のバックエンドを提供します。\n";
print_r($bprovides);

?>

上の例の出力は、 たとえば以下のようになります。

現在のブローカーは、次のバックエンドを提供します。
Array
(
    [0] => Array
        (
            [name] => aspell
            [desc] => Aspell Provider
            [file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [1] => Array
        (
            [name] => hspell
            [desc] => Hspell Provider
            [file] => /usr/lib/enchant/libenchant_hspell.so
        )

    [2] => Array
        (
            [name] => ispell
            [desc] => Ispell Provider
            [file] => /usr/lib/enchant/libenchant_ispell.so
        )

    [3] => Array
        (
            [name] => myspell
            [desc] => Myspell Provider
            [file] => /usr/lib/enchant/libenchant_myspell.so
        )

)


辞書が存在するかどうかを調べる。空でないタグを使用する

  • ≪ enchant_broker_describe
  • enchant_broker_free ≫
  • PHP Manual
  • Enchant 関数
  • 辞書が存在するかどうかを調べる。空でないタグを使用する

enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — 辞書が存在するかどうかを調べる。空でないタグを使用する

説明

enchant_broker_dict_exists(EnchantBroker $broker, string $tag): bool

辞書が存在するかどうかを調べます。空でないタグを使用します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

tag

空でない、LOCALE 形式のタグ。例: us_US、ch_DE など。

戻り値

タグが存在する場合に true、存在しない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 enchant_broker_dict_exists() の例

<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
echo $tag . " の辞書が見つかりました。\n";
}
?>

参考

  • enchant_broker_describe() - Enchant プロバイダを列挙する


ブローカーリソースおよびその辞書を開放する

  • ≪ enchant_broker_dict_exists
  • enchant_broker_free_dict ≫
  • PHP Manual
  • Enchant 関数
  • ブローカーリソースおよびその辞書を開放する

enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — ブローカーリソースおよびその辞書を開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_free(EnchantBroker $broker): bool

ブローカーをその辞書とともに開放します。 PHP 8.0.0 以降では、この関数を呼び出さず、オブジェクト自体を unset することを推奨します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_broker_init() - 要求を満たすブローカーオブジェクトを作成する


辞書リソースを開放する

  • ≪ enchant_broker_free
  • enchant_broker_get_dict_path ≫
  • PHP Manual
  • Enchant 関数
  • 辞書リソースを開放する

enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — 辞書リソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_free_dict(EnchantDictionary $dictionary): bool

辞書を開放します。 PHP 8.0.0 以降では、この関数を呼び出す代わりに、オブジェクト自体を unset することを推奨します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_broker_request_dict() - タグを使用して新しい辞書を作成する
  • enchant_broker_request_pwl_dict() - PWL ファイルを使用して辞書を作成する


指定されたバックエンドの辞書のパスを取得する

  • ≪ enchant_broker_free_dict
  • enchant_broker_get_error ≫
  • PHP Manual
  • Enchant 関数
  • 指定されたバックエンドの辞書のパスを取得する

enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — 指定されたバックエンドの辞書のパスを取得する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_get_dict_path(EnchantBroker $broker, int $type): string|false

指定されたバックエンドの辞書のパスを取得します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

type

辞書のタイプ。たとえば、ENCHANT_MYSPELL または ENCHANT_ISPELL。

戻り値

成功した場合、辞書のディレクトリパスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

注意

注意:

この関数は、拡張モジュールが Enchant v1 を使ってコンパイルされた場合にのみ利用可能です。

参考

  • enchant_broker_set_dict_path() - 指定されたバックエンドの辞書のパスを設定する


ブローカーの直近のエラーを返す

  • ≪ enchant_broker_get_dict_path
  • enchant_broker_init ≫
  • PHP Manual
  • Enchant 関数
  • ブローカーの直近のエラーを返す

enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — ブローカーの直近のエラーを返す

説明

enchant_broker_get_error(EnchantBroker $broker): string|false

このブローカーで発生した直近のエラーを返します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

戻り値

エラーが見つかった場合にメッセージ文字列、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。


要求を満たすブローカーオブジェクトを作成する

  • ≪ enchant_broker_get_error
  • enchant_broker_list_dicts ≫
  • PHP Manual
  • Enchant 関数
  • 要求を満たすブローカーオブジェクトを作成する

enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — 要求を満たすブローカーオブジェクトを作成する

説明

enchant_broker_init(): EnchantBroker|false

パラメータ

戻り値

成功した場合にブローカーリソース、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は EnchantBroker のインスタンスを返すようになりました。 これより前のバージョンでは、リソース が返されていました。

参考

  • enchant_broker_free() - ブローカーリソースおよびその辞書を開放する


使用可能な辞書の一覧を返す

  • ≪ enchant_broker_init
  • enchant_broker_request_dict ≫
  • PHP Manual
  • Enchant 関数
  • 使用可能な辞書の一覧を返す

enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — 使用可能な辞書の一覧を返す

説明

enchant_broker_list_dicts(EnchantBroker $broker): array

使用可能な辞書の一覧と、その詳細を返します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

戻り値

使用可能な辞書の一覧と、その詳細を array として返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | このバージョンより前では、この関数は失敗時に false を返していました。

例

例1 あるブローカーで使用可能なすべての辞書を表示する

<?php
$r = enchant_broker_init();
$dicts = enchant_broker_list_dicts($r);
print_r($dicts);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [lang_tag] => de
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [1] => Array
        (
            [lang_tag] => de_DE
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [3] => Array
        (
            [lang_tag] => en
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [4] => Array
        (
            [lang_tag] => en_GB
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [5] => Array
        (
            [lang_tag] => en_US
            [provider_name] => aspell
            [provider_desc] => Aspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_aspell.so
        )

    [6] => Array
        (
            [lang_tag] => hi_IN
            [provider_name] => myspell
            [provider_desc] => Myspell Provider
            [provider_file] => /usr/lib/enchant/libenchant_myspell.so
        )

)

参考

  • enchant_broker_describe() - Enchant プロバイダを列挙する


タグを使用して新しい辞書を作成する

  • ≪ enchant_broker_list_dicts
  • enchant_broker_request_pwl_dict ≫
  • PHP Manual
  • Enchant 関数
  • タグを使用して新しい辞書を作成する

enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — タグを使用して新しい辞書を作成する

説明

enchant_broker_request_dict(EnchantBroker $broker, string $tag): EnchantDictionary|false

タグを使用して新しい辞書を作成します。空でない言語タグで、 使用したい辞書を指定します ("en_US"、"de_DE"、...)。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

tag

ロケールを表すタグ。例えば en_US、de_DE など。

戻り値

成功した場合に辞書リソース、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | 成功時に、この関数は EnchantDictionary のインスタンスを返すようになりました。 これより前のバージョンでは、リソース が返されていました。

例

例1 enchant_broker_request_dict() の例

辞書が存在するかどうかを enchant_broker_dict_exists() で調べ、それを要求します。

<?php
$tag = 'en_US';
$broker = enchant_broker_init();
if (enchant_broker_dict_exists($broker,$tag)) {
$dict = enchant_broker_request_dict($r, $tag);
}
?>

参考

  • enchant_dict_describe() - 個々の辞書について説明する
  • enchant_broker_dict_exists() - 辞書が存在するかどうかを調べる。空でないタグを使用する
  • enchant_broker_free_dict() - 辞書リソースを開放する


PWL ファイルを使用して辞書を作成する

  • ≪ enchant_broker_request_dict
  • enchant_broker_set_dict_path ≫
  • PHP Manual
  • Enchant 関数
  • PWL ファイルを使用して辞書を作成する

enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — PWL ファイルを使用して辞書を作成する

説明

enchant_broker_request_pwl_dict(EnchantBroker $broker, string $filename): EnchantDictionary|false

PWL ファイルを使用して辞書を作成します。 PWL ファイルは、一行にひとつの単語を記述したパーソナル単語ファイルです。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

filename

PWL ファイルへのパス。 ファイルが存在しない場合は、可能であれば新しいファイルを作ります。

戻り値

成功した場合に辞書リソース、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | 成功時に、この関数は EnchantDictionary のインスタンスを返すようになりました。 これより前のバージョンでは、リソース が返されていました。

参考

  • enchant_dict_describe() - 個々の辞書について説明する
  • enchant_broker_dict_exists() - 辞書が存在するかどうかを調べる。空でないタグを使用する
  • enchant_broker_free_dict() - 辞書リソースを開放する


指定されたバックエンドの辞書のパスを設定する

  • ≪ enchant_broker_request_pwl_dict
  • enchant_broker_set_ordering ≫
  • PHP Manual
  • Enchant 関数
  • 指定されたバックエンドの辞書のパスを設定する

enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — 指定されたバックエンドの辞書のパスを設定する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

enchant_broker_set_dict_path(EnchantBroker $broker, int $type, string $path): bool

指定されたバックエンドの辞書のパスを設定します。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

type

辞書のタイプ。たとえば、ENCHANT_MYSPELL または ENCHANT_ISPELL。

path

辞書のディレクトリパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

注意

注意:

この関数は、拡張モジュールが Enchant v1 を使ってコンパイルされた場合にのみ利用可能です。

参考

  • enchant_broker_get_dict_path() - 指定されたバックエンドの辞書のパスを取得する


その言語で使用する辞書の優先順位を宣言する

  • ≪ enchant_broker_set_dict_path
  • enchant_dict_add ≫
  • PHP Manual
  • Enchant 関数
  • その言語で使用する辞書の優先順位を宣言する

enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — その言語で使用する辞書の優先順位を宣言する

説明

enchant_broker_set_ordering(EnchantBroker $broker, string $tag, string $ordering): bool

'タグ' で表される言語で使用する辞書の優先順位を宣言します。 順位は、プロバイダ名をカンマ区切りでつないだリストで表します。 例外として、言語タグに "*" を使用すると、あらゆる言語についての デフォルトの順位を宣言します。 明示的に順位を指定しなかった言語についてはこれが使用されます。

パラメータ

broker

enchant_broker_init() によって返される Enchant ブローカー。

tag

言語タグ。"*" を使用すると、あらゆる言語についての デフォルトの順位を宣言します。 明示的に順位を指定しなかった言語についてはこれが使用されます。

ordering

プロバイダ名をカンマ区切りでつないだリスト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | broker は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。


単語リストに単語を追加する

  • ≪ enchant_broker_set_ordering
  • enchant_dict_add_to_personal ≫
  • PHP Manual
  • Enchant 関数
  • 単語リストに単語を追加する

enchant_dict_add

(PHP 8)

enchant_dict_add — 単語リストに単語を追加する

説明

enchant_dict_add(EnchantDictionary $dictionary, string $word): void

指定した辞書の単語リストに単語を追加します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

追加する単語。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 辞書リストに単語を追加する

<?php

$filename = './my_word_list.pwl';
$word = 'Supercalifragilisticexpialidocious';

$broker = enchant_broker_init();
$dict = enchant_broker_request_pwl_dict($broker, $filename);

enchant_dict_add($dict, $word);

enchant_broker_free($broker);

?>

参考

  • enchant_broker_request_pwl_dict() - PWL ファイルを使用して辞書を作成する
  • enchant_broker_request_dict() - タグを使用して新しい辞書を作成する


のエイリアス enchant_dict_add

  • ≪ enchant_dict_add
  • enchant_dict_add_to_session ≫
  • PHP Manual
  • Enchant 関数
  • のエイリアス enchant_dict_add

enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — のエイリアス enchant_dict_add()

警告

このエイリアスは PHP 8.0.0 で 非推奨 になりました。

説明

この関数は次の関数のエイリアスです。 enchant_dict_add().


'単語' を、このスペルチェックセッションに追加する

  • ≪ enchant_dict_add_to_personal
  • enchant_dict_check ≫
  • PHP Manual
  • Enchant 関数
  • '単語' を、このスペルチェックセッションに追加する

enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する

説明

enchant_dict_add_to_session(EnchantDictionary $dictionary, string $word): void

指定した辞書に単語を追加します。 追加されるのは、アクティブなスペルチェックセッションについてのみです。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

追加する単語。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_broker_request_dict() - タグを使用して新しい辞書を作成する


単語のスペルが正しいかどうかを調べる

  • ≪ enchant_dict_add_to_session
  • enchant_dict_describe ≫
  • PHP Manual
  • Enchant 関数
  • 単語のスペルが正しいかどうかを調べる

enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — 単語のスペルが正しいかどうかを調べる

説明

enchant_dict_check(EnchantDictionary $dictionary, string $word): bool

単語のスペルが正しい場合に true、 そうでない場合に false を返します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

調べる単語。

戻り値

単語のスペルが正しい場合に true、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。


個々の辞書について説明する

  • ≪ enchant_dict_check
  • enchant_dict_get_error ≫
  • PHP Manual
  • Enchant 関数
  • 個々の辞書について説明する

enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — 個々の辞書について説明する

説明

enchant_dict_describe(EnchantDictionary $dictionary): array

辞書の詳細を返します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。
8.0.0 | このバージョンより前では、この関数は失敗時に false を返していました。

例

例1 enchant_broker_dict_describe() の例

辞書が存在するかどうかを enchant_broker_dict_exists() で調べ、 その詳細を表示します。

<?php
$tag = 'en_US';
$broker = enchant_broker_init();
if (enchant_broker_dict_exists($broker,$tag)) {
$dict = enchant_broker_request_dict($r, $tag);
$dict_details = enchant_dict_describe($dict);
print_r($dict_details);
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [lang] => en_US
    [name] => aspell
    [desc] => Aspell Provider
    [file] => /usr/lib/enchant/libenchant_aspell.so
)


現在のスペリングセッションの直近のエラーを返す

  • ≪ enchant_dict_describe
  • enchant_dict_is_added ≫
  • PHP Manual
  • Enchant 関数
  • 現在のスペリングセッションの直近のエラーを返す

enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — 現在のスペリングセッションの直近のエラーを返す

説明

enchant_dict_get_error(EnchantDictionary $dictionary): string|false

現在のスペリングセッションの、直近のエラーを返します。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

戻り値

エラーメッセージを表す文字列、あるいはエラーが発生していない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。


現在のセッションに、単語が存在するかどうかを調べる

  • ≪ enchant_dict_get_error
  • enchant_dict_is_in_session ≫
  • PHP Manual
  • Enchant 関数
  • 現在のセッションに、単語が存在するかどうかを調べる

enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — 現在のセッションに、単語が存在するかどうかを調べる

説明

enchant_dict_is_added(EnchantDictionary $dictionary, string $word): bool

現在のセッションに、指定された単語が存在するかを調べる。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

調べる単語。

戻り値

単語が存在した場合、true を返します。 存在しない場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

参考

  • enchant_dict_add_to_session() - '単語' を、このスペルチェックセッションに追加する


のエイリアス enchant_dict_is_added

  • ≪ enchant_dict_is_added
  • enchant_dict_quick_check ≫
  • PHP Manual
  • Enchant 関数
  • のエイリアス enchant_dict_is_added

enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — のエイリアス enchant_dict_is_added()

警告

このエイリアスは PHP 8.0.0 で 非推奨 になりました。

説明

この関数は次の関数のエイリアスです。 enchant_dict_is_added().


単語のスペルが正しいかどうかを調べ、修正候補を提供する

  • ≪ enchant_dict_is_in_session
  • enchant_dict_store_replacement ≫
  • PHP Manual
  • Enchant 関数
  • 単語のスペルが正しいかどうかを調べ、修正候補を提供する

enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — 単語のスペルが正しいかどうかを調べ、修正候補を提供する

説明

enchant_dict_quick_check(EnchantDictionary $dictionary, string $word, array &$suggestions = null): bool

単語のスペルが正しい場合は true、そうでない場合は false を返します。変数 suggestions を指定している場合は、 そこに修正候補が格納されます。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

調べる単語。

suggestions

単語のスペルが間違っている場合に、 この変数の中に修正候補の配列が格納されます。

戻り値

単語のスペルが正しい場合に true、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 enchant_dict_quick_check() の例

<?php
$tag = 'en_US';
$r = enchant_broker_init();

if (enchant_broker_dict_exists($r,$tag)) {
$d = enchant_broker_request_dict($r, $tag);
enchant_dict_quick_check($d, 'soong', $suggs);
print_r($suggs);
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => song
    [1] => snog
    [2] => soon
    [3] => Sang
    [4] => Sung
    [5] => sang
    [6] => sung
    [7] => sponge
    [8] => spongy
    [9] => snag
    [10] => snug
    [11] => sonic
    [12] => sing
    [13] => songs
    [14] => Son
    [15] => Sonja
    [16] => Synge
    [17] => son
    [18] => Sejong
    [19] => sarong
    [20] => sooner
    [21] => Sony
    [22] => sown
    [23] => scone
    [24] => song's
)

参考

  • enchant_dict_check() - 単語のスペルが正しいかどうかを調べる
  • enchant_dict_suggest() - 修正候補となる値の一覧を返す


単語の修正候補を追加する

  • ≪ enchant_dict_quick_check
  • enchant_dict_suggest ≫
  • PHP Manual
  • Enchant 関数
  • 単語の修正候補を追加する

enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — 単語の修正候補を追加する

説明

enchant_dict_store_replacement(EnchantDictionary $dictionary, string $misspelled, string $correct): void

'mis' の修正候補として 'cor' を使用します。 @mis が @cor に置き換えられることに注意しましょう。 今後 @mis が登場すると、それは @cor で置き換えられます。 そのため、@cor が修正候補の中で衝突するかもしれません。

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

misspelled

修正する単語。

correct

正しい単語。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。


修正候補となる値の一覧を返す

  • ≪ enchant_dict_store_replacement
  • EnchantBroker ≫
  • PHP Manual
  • Enchant 関数
  • 修正候補となる値の一覧を返す

enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — 修正候補となる値の一覧を返す

説明

enchant_dict_suggest(EnchantDictionary $dictionary, string $word): array

パラメータ

dictionary

enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

word

修正候補を調べる単語。

戻り値

単語のスペルが間違っている場合に、修正候補の配列を返します。

変更履歴

バージョン | 説明
8.0.0 | dictionary は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース が期待されていました。

例

例1 enchant_dict_suggest() の例

<?php
$tag = 'en_US';
$r = enchant_broker_init();
if (enchant_broker_dict_exists($r,$tag)) {
$d = enchant_broker_request_dict($r, $tag);

$wordcorrect = enchant_dict_check($d, "soong");
if (!$wordcorrect) {
$suggs = enchant_dict_suggest($d, "soong");
echo "'soong' の修正候補:";
print_r($suggs);
}
enchant_broker_free_dict($d);
}
enchant_broker_free($r);
?>

参考

  • enchant_dict_check() - 単語のスペルが正しいかどうかを調べる
  • enchant_dict_quick_check() - 単語のスペルが正しいかどうかを調べ、修正候補を提供する


EnchantBroker クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 enchant_broker リソースを置き換える完全不透明クラスです。

クラス概要

final class EnchantBroker {
}


EnchantDictionary クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 enchant_dict リソースを置き換える完全不透明クラスです。

クラス概要

final class EnchantDictionary {
}


名前の性別の判別

  • はじめに
  • インストール/設定
    • インストール手順
  • 例
    • 利用例
  • Gender\Gender — Gender\Gender クラス
    • Gender\Gender::connect — 外部の名前ディレクトリに接続する
    • Gender\Gender::__construct — Gender オブジェクトを作る
    • Gender\Gender::country — 国を表すテキストを取得する
    • Gender\Gender::get — 性別を取得する
    • Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる
    • Gender\Gender::similarNames — 似た名前を取得する


はじめに

Gender 拡張モジュールは、Joerg Michael によるプログラム gender.c を PHP に移植したものです。主目的は、ファーストネームから性別を判断することです。 データベースには、現時点で 54か国から 40000 を超えるファーストネームが含まれています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Gender
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gender

この PECL 拡張モジュールの DLL は » http://windows.php.net/downloads/pecl/releases/gender/ にあります。


  • ≪ インストール手順
  • 利用例 ≫
  • PHP Manual
  • Gender
  • 例

例

目次

  • 利用例


利用例

Gender クラスの利用例です。

例1 利用例

<?php

namespace Gender;

$gender = new Gender;

$name = "Milene";
$country = Gender::FRANCE;

$result = $gender->get($name, $country);

$data = $gender->country($country);

switch($result) {
case Gender::IS_FEMALE:
printf("%sは、%sでは女性の名前です。\n", $name, $data['country']);
break;

case Gender::IS_MOSTLY_FEMALE:
printf("%sは、%sではおそらく女性の名前です。\n", $name, $data['country']);
break;

case Gender::IS_MALE:
printf("%sは、%sでは男性の名前です。\n", $name, $data['country']);
break;

case Gender::IS_MOSTLY_MALE:
printf("%sは、%sではおそらく男性の名前です。\n", $name, $data['country']);
break;

case Gender::IS_UNISEX_NAME:
printf("%sは、%sでは男女どちらも区別しません。\n", $name, $data['country']);
break;

case Gender::IS_A_COUPLE:
printf("%sは、%sでは男性の名前としても女性の名前としても使います。\n", $name, $data['country']);
break;

case Gender::NAME_NOT_FOUND:
printf("%sは、%sでは見つかりません。\n", $name, $data['country']);
break;

case Gender::ERROR_IN_NAME:
echo "名前にエラーが発生しました!\n";
break;

default:
echo "エラーが発生しました!\n";
break;

}


Gender\Gender クラス

(PECL gender >= 0.6.0)

はじめに

クラス概要

class Gender\Gender {
/* 定数 */
const int IS_FEMALE = 70;
const int IS_MOSTLY_FEMALE = 102;
const int IS_MALE = 77;
const int IS_MOSTLY_MALE = 109;
const int IS_UNISEX_NAME = 63;
const int IS_A_COUPLE = 67;
const int NAME_NOT_FOUND = 32;
const int ERROR_IN_NAME = 69;
const int ANY_COUNTRY = 0;
const int BRITAIN = 1;
const int IRELAND = 2;
const int USA = 3;
const int SPAIN = 4;
const int PORTUGAL = 5;
const int ITALY = 6;
const int MALTA = 7;
const int FRANCE = 8;
const int BELGIUM = 9;
const int LUXEMBOURG = 10;
const int NETHERLANDS = 11;
const int GERMANY = 12;
const int EAST_FRISIA = 13;
const int AUSTRIA = 14;
const int SWISS = 15;
const int ICELAND = 16;
const int DENMARK = 17;
const int NORWAY = 18;
const int SWEDEN = 19;
const int FINLAND = 20;
const int ESTONIA = 21;
const int LATVIA = 22;
const int LITHUANIA = 23;
const int POLAND = 24;
const int CZECH_REP = 25;
const int SLOVAKIA = 26;
const int HUNGARY = 27;
const int ROMANIA = 28;
const int BULGARIA = 29;
const int BOSNIA = 30;
const int CROATIA = 31;
const int KOSOVO = 32;
const int MACEDONIA = 33;
const int MONTENEGRO = 34;
const int SERBIA = 35;
const int SLOVENIA = 36;
const int ALBANIA = 37;
const int GREECE = 38;
const int RUSSIA = 39;
const int BELARUS = 40;
const int MOLDOVA = 41;
const int UKRAINE = 42;
const int ARMENIA = 43;
const int AZERBAIJAN = 44;
const int GEORGIA = 45;
const int KAZAKH_UZBEK = 46;
const int TURKEY = 47;
const int ARABIA = 48;
const int ISRAEL = 49;
const int CHINA = 50;
const int INDIA = 51;
const int JAPAN = 52;
const int KOREA = 53;
/* メソッド */
public __construct(string $dsn = ?)
public connect(string $dsn): bool
public country(int $country): array|false
public get(string $name, int $country = ?): int
public isNick(string $name0, string $name1, int $country = ?): array
public similarNames(string $name, int $country = ?): array
}

定義済み定数

Gender\Gender::IS_FEMALE

Gender\Gender::IS_MOSTLY_FEMALE

Gender\Gender::IS_MALE

Gender\Gender::IS_MOSTLY_MALE

Gender\Gender::IS_UNISEX_NAME

Gender\Gender::IS_A_COUPLE

Gender\Gender::NAME_NOT_FOUND

Gender\Gender::ERROR_IN_NAME

Gender\Gender::ANY_COUNTRY

Gender\Gender::BRITAIN

Gender\Gender::IRELAND

Gender\Gender::USA

Gender\Gender::SPAIN

Gender\Gender::PORTUGAL

Gender\Gender::ITALY

Gender\Gender::MALTA

Gender\Gender::FRANCE

Gender\Gender::BELGIUM

Gender\Gender::LUXEMBOURG

Gender\Gender::NETHERLANDS

Gender\Gender::GERMANY

Gender\Gender::EAST_FRISIA

Gender\Gender::AUSTRIA

Gender\Gender::SWISS

Gender\Gender::ICELAND

Gender\Gender::DENMARK

Gender\Gender::NORWAY

Gender\Gender::SWEDEN

Gender\Gender::FINLAND

Gender\Gender::ESTONIA

Gender\Gender::LATVIA

Gender\Gender::LITHUANIA

Gender\Gender::POLAND

Gender\Gender::CZECH_REP

Gender\Gender::SLOVAKIA

Gender\Gender::HUNGARY

Gender\Gender::ROMANIA

Gender\Gender::BULGARIA

Gender\Gender::BOSNIA

Gender\Gender::CROATIA

Gender\Gender::KOSOVO

Gender\Gender::MACEDONIA

Gender\Gender::MONTENEGRO

Gender\Gender::SERBIA

Gender\Gender::SLOVENIA

Gender\Gender::ALBANIA

Gender\Gender::GREECE

Gender\Gender::RUSSIA

Gender\Gender::BELARUS

Gender\Gender::MOLDOVA

Gender\Gender::UKRAINE

Gender\Gender::ARMENIA

Gender\Gender::AZERBAIJAN

Gender\Gender::GEORGIA

Gender\Gender::KAZAKH_UZBEK

Gender\Gender::TURKEY

Gender\Gender::ARABIA

Gender\Gender::ISRAEL

Gender\Gender::CHINA

Gender\Gender::INDIA

Gender\Gender::JAPAN

Gender\Gender::KOREA

目次

  • Gender\Gender::connect — 外部の名前ディレクトリに接続する
  • Gender\Gender::__construct — Gender オブジェクトを作る
  • Gender\Gender::country — 国を表すテキストを取得する
  • Gender\Gender::get — 性別を取得する
  • Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる
  • Gender\Gender::similarNames — 似た名前を取得する


外部の名前ディレクトリに接続する

  • ≪ Gender\Gender
  • Gender\Gender::__construct ≫
  • PHP Manual
  • Gender\Gender
  • 外部の名前ディレクトリに接続する

Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — 外部の名前ディレクトリに接続する

説明

public Gender\Gender::connect(string $dsn): bool

外部の名前ディレクトリに接続します。 今のところ、サポートしているのはストリームだけです。

パラメータ

dsn

開きたい DSN。

戻り値

成功したかどうかを boolean で返します。


Gender オブジェクトを作る

  • ≪ Gender\Gender::connect
  • Gender\Gender::country ≫
  • PHP Manual
  • Gender\Gender
  • Gender オブジェクトを作る

Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Gender オブジェクトを作る

説明

public Gender\Gender::__construct(string $dsn = ?)

Gender オブジェクトを作ります。オプションで、外部の名前ディレクトリに接続することもできます。 外部データベースを指定しなかったときは、コンパイル時に組み込まれたデータを使います。

パラメータ

dsn

開きたい DSN。


国を表すテキストを取得する

  • ≪ Gender\Gender::__construct
  • Gender\Gender::get ≫
  • PHP Manual
  • Gender\Gender
  • 国を表すテキストを取得する

Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — 国を表すテキストを取得する

説明

public Gender\Gender::country(int $country): array|false

Gender クラスの定数から、国を表す文字列を取得します。

パラメータ

country

Gender\Gender クラスの定数で表される国 ID。

戻り値

成功した場合は、短い国名と完全な国名の配列を返します。 失敗した場合に false を返します。

例

例1 Gender\Gender::country() の使用例

$gender = new Gender\Gender;
var_dump($gender->country(Gender\Gender::BRITAIN));

上の例の出力は以下となります。

array(2) {
  'country_short' =>
  string(2) "UK"
  'country' =>
  string(13) "Great Britain"
}


性別を取得する

  • ≪ Gender\Gender::country
  • Gender\Gender::isNick ≫
  • PHP Manual
  • Gender\Gender
  • 性別を取得する

Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — 性別を取得する

説明

public Gender\Gender::get(string $name, int $country = ?): int

指定した名前について、特定の国における性別を取得します。

パラメータ

name

調べたい名前。

country

Gender クラスの定数で表される国 ID。

戻り値

性別を返します。


name0 が name1 のエイリアスかどうかを調べる

  • ≪ Gender\Gender::get
  • Gender\Gender::similarNames ≫
  • PHP Manual
  • Gender\Gender
  • name0 が name1 のエイリアスかどうかを調べる

Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる

説明

public Gender\Gender::isNick(string $name0, string $name1, int $country = ?): array

name0 が name1 のエイリアスかどうかを調べます。

パラメータ

name0

調べる名前。

name1

調べる名前。

country

Gender クラスの定数で指定する国 ID。省略した場合は ANY_COUNTRY を使います。

戻り値

成功した場合に true を、失敗した場合に false を返します。


似た名前を取得する

  • ≪ Gender\Gender::isNick
  • Gettext ≫
  • PHP Manual
  • Gender\Gender
  • 似た名前を取得する

Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — 似た名前を取得する

説明

public Gender\Gender::similarNames(string $name, int $country = ?): array

名前と国を指定して、似た名前を取得します。

パラメータ

name

調べる名前。

country

Gender クラスの定数で指定する国 ID。省略した場合は ANY_COUNTRY を使います。

戻り値

似ている名前の配列を返します。


Gettext

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Gettext 関数
    • _ — のエイリアス gettext
    • bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
    • bindtextdomain — ドメインのパスを取得/設定する
    • dcgettext — 単一の参照に関するドメインを上書きする
    • dcngettext — dcgettext の複数形版
    • dgettext — 現在のドメインを上書きする
    • dngettext — dgettext の複数形版
    • gettext — 現在のドメインのメッセージを参照する
    • ngettext — gettext の複数形版
    • textdomain — デフォルトドメインを設定する


はじめに

gettext 関数は、NLS (Native Language Support) API を実装するもので、 PHP アプリケーションを国際化する際に使用することが可能です。 これらの関数の詳細については、システムの gettext ドキュメントを 参照するか、 » http://www.gnu.org/software/gettext/manual/gettext.html のドキュメントをごらんください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Gettext
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

以下の関数を使用するには、» http://www.gnu.org/software/gettext/gettext.html から GNU gettext パッケージをダウンロードし、インストールする必要があります。


インストール手順

PHP で GNU gettext サポートを有効にするには、オプション --with-gettext[=DIR] を追加する必要が あります。ただし、DIR は gettext をインストールするディレクトリで、 デフォルトは /usr/local です。


Gettext 関数

目次

  • _ — のエイリアス gettext
  • bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
  • bindtextdomain — ドメインのパスを取得/設定する
  • dcgettext — 単一の参照に関するドメインを上書きする
  • dcngettext — dcgettext の複数形版
  • dgettext — 現在のドメインを上書きする
  • dngettext — dgettext の複数形版
  • gettext — 現在のドメインのメッセージを参照する
  • ngettext — gettext の複数形版
  • textdomain — デフォルトドメインを設定する


のエイリアス gettext

  • ≪ Gettext 関数
  • bind_textdomain_codeset ≫
  • PHP Manual
  • Gettext 関数
  • のエイリアス gettext

_

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — のエイリアス gettext()

説明

この関数は次の関数のエイリアスです。 gettext().


DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

  • ≪ _
  • bindtextdomain ≫
  • PHP Manual
  • Gettext 関数
  • DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

説明

bind_textdomain_codeset(string $domain, ?string $codeset): string|false

bind_textdomain_codeset() を使用することで、 gettext() やその類似の関数において返される、 domain からのメッセージの文字エンコーディングを 設定したり、取得することが可能です。

パラメータ

domain

ドメイン。

codeset

コードセット。 null を指定すると、現在設定されているエンコーディングが返されます。

戻り値

成功した場合に文字列を返します。

変更履歴

バージョン | 説明
8.0.3 | codeset は、nullable になりました。 これより前のバージョンでは、 現在設定されているエンコーディングは取得できませんでした。

注意

注意:

bind_textdomain_codeset() 関数の情報はプロセス単位で管理されます。 スレッドではありません。


ドメインのパスを取得/設定する

  • ≪ bind_textdomain_codeset
  • dcgettext ≫
  • PHP Manual
  • Gettext 関数
  • ドメインのパスを取得/設定する

bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — ドメインのパスを取得/設定する

説明

bindtextdomain(string $domain, ?string $directory): string|false

bindtextdomain() 関数は、ドメインへのパスを取得/設定します。

パラメータ

domain

ドメイン。

directory

ディレクトリのパス。 空文字列を指定すると、現在のディレクトリを指定したことになります。 null を指定すると、現在設定されているディレクトリが返されます。

戻り値

現在設定されているドメインへのフルパスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.3 | directory は、nullable になりました。 これより前のバージョンでは、現在設定されているディレクトリを取得できませんでした。

例

例1 bindtextdomain() の例

<?php

$domain = 'myapp';
echo bindtextdomain($domain, '/usr/share/myapp/locale');

?>

上の例の出力は以下となります。

/usr/share/myapp/locale

注意

注意:

bindtextdomain() 関数の情報はプロセス単位で管理されます。 スレッドではありません。


単一の参照に関するドメインを上書きする

  • ≪ bindtextdomain
  • dcngettext ≫
  • PHP Manual
  • Gettext 関数
  • 単一の参照に関するドメインを上書きする

dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — 単一の参照に関するドメインを上書きする

説明

dcgettext(string $domain, string $message, int $category): string

この関数により単一の参照についてカレントのドメインを上書きすることができます。

パラメータ

domain

ドメイン。

message

メッセージ。

category

カテゴリ。

戻り値

成功した場合に文字列を返します。

参考

  • gettext() - 現在のドメインのメッセージを参照する


dcgettext の複数形版

  • ≪ dcgettext
  • dgettext ≫
  • PHP Manual
  • Gettext 関数
  • dcgettext の複数形版

dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — dcgettext の複数形版

説明

dcngettext(
string $domain,
string $singular,
string $plural,
int $count,
int $category
): string

この関数により単一の複数形メッセージの参照について カレントのドメインを上書きすることができます。

パラメータ

domain

ドメイン。

singular

plural

count

category

戻り値

成功した場合に文字列を返します。

参考

  • ngettext() - gettext の複数形版


現在のドメインを上書きする

  • ≪ dcngettext
  • dngettext ≫
  • PHP Manual
  • Gettext 関数
  • 現在のドメインを上書きする

dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — 現在のドメインを上書きする

説明

dgettext(string $domain, string $message): string

dgettext() 関数により、単一のメッセージ参照について 現在のドメインを上書きすることができます。

パラメータ

domain

ドメイン。

message

メッセージ。

戻り値

成功した場合に文字列を返します。

参考

  • gettext() - 現在のドメインのメッセージを参照する


dgettext の複数形版

  • ≪ dgettext
  • gettext ≫
  • PHP Manual
  • Gettext 関数
  • dgettext の複数形版

dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — dgettext の複数形版

説明

dngettext(
string $domain,
string $singular,
string $plural,
int $count
): string

dngettext() 関数により、単一の複数形メッセージ参照について 現在のドメインを上書きすることができます。

パラメータ

domain

ドメイン。

singular

plural

count

戻り値

成功した場合に文字列を返します。

参考

  • ngettext() - gettext の複数形版


現在のドメインのメッセージを参照する

  • ≪ dngettext
  • ngettext ≫
  • PHP Manual
  • Gettext 関数
  • 現在のドメインのメッセージを参照する

gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — 現在のドメインのメッセージを参照する

説明

gettext(string $message): string

現在のドメインのメッセージを参照します。

パラメータ

message

翻訳するメッセージ。

戻り値

翻訳テーブルに翻訳文字列が見つかった場合にその文字列、 あるいは見つからなかった場合に元の文字列を返します。

例

例1 gettext() のチェック

<?php
// ドイツ語に設定します
putenv('LC_ALL=de_DE');
setlocale(LC_ALL, 'de_DE');

// 変換テーブルの場所を指定します
bindtextdomain("myPHPApp", "./locale");

// ドメインを選択します
textdomain("myPHPApp");

// 翻訳内容は ./locale/de_DE/LC_MESSAGES/myPHPApp.mo から検索されます

// テストメッセージを出力します
echo gettext("Welcome to My PHP Application");

// あるいは、gettext() のかわりに _() も使用可能です
echo _("Have a nice day");
?>

注意

注意:

この関数のエイリアスとして、アンダースコア文字 '_' を使用することができます。

注意:

言語を設定するだけではだめなシステムもあり、 putenv() を使って正しいロケールを定義しなければなりません。

参考

  • _() - のエイリアス gettext
  • setlocale() - ロケール情報を設定する


gettext の複数形版

  • ≪ gettext
  • textdomain ≫
  • PHP Manual
  • Gettext 関数
  • gettext の複数形版

ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — gettext の複数形版

説明

ngettext(string $singular, string $plural, int $count): string

複数形版の gettext() です。 言語によっては、数量に応じていくつかの複数形が存在することがあります。

パラメータ

singular

単数形のメッセージ ID。

plural

複数形のメッセージ ID。

count

数 (件数など)。この数にあわせて翻訳を決定します。

戻り値

singular および plural で表されるメッセージの、数 count に対応する複数形を返します。

例

例1 ngettext() の例

<?php

setlocale(LC_ALL, 'cs_CZ');
printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken

?>


デフォルトドメインを設定する

  • ≪ ngettext
  • iconv ≫
  • PHP Manual
  • Gettext 関数
  • デフォルトドメインを設定する

textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — デフォルトドメインを設定する

説明

textdomain(string $text_domain = null): string

この関数は、gettext() がコールされた際に検索を 行うドメインを設定します。このドメインは、通常はアプリケーション名から 付けられます。

パラメータ

domain

新しいメッセージドメイン。null を指定すると、現在の設定をそのまま 取得し、変更しません。

戻り値

成功すると、この関数はドメインを変更した後に現在のメッセージドメインを 返します。

注意

注意:

textdomain() 関数の情報はプロセス単位で管理されます。 スレッドではありません。


iconv

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • iconv 関数
    • iconv — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
    • iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する
    • iconv_mime_decode — MIME ヘッダフィールドをデコードする
    • iconv_mime_decode_headers — 複数の MIME ヘッダフィールドを一度にデコードする
    • iconv_mime_encode — MIME ヘッダフィールドを作成する
    • iconv_set_encoding — 文字エンコーディング変換用の設定を行なう
    • iconv_strlen — 文字列の文字数を返す
    • iconv_strpos — 文字列が最初に現れる場所を見つける
    • iconv_strrpos — 文字列が最後に現れる場所を見つける
    • iconv_substr — 文字列の一部を切り出す
    • ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する


はじめに

このモジュールには、iconv による文字集合の変換機能へのインターフェイスが含まれています。 このモジュールにより、ローカルな文字集合で表された文字列を、Unicode 文字集合のような 他の文字集合で表わされた文字列に変換することができます。 サポートされる文字集合は、使用するシステムの iconv の実装に依存します。 いくつかのシステムでは iconv 関数は意図した通りに動作しない可能性があることに注意してください。 この場合は、» GNU libiconv ライブラリをインストール すると良いでしょう。 このライブラリの出力は、多くの場合、より妥当なものとなります。

この拡張モジュールには、 多言語スクリプトを書く際に有用な種々のユーティリティが附属しています。 この新機能については、以下のセクションを参照ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • iconv
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

使用しているシステムが、最近のPOSIX対応システムのどれかである場合には、標準C 言語ライブラリの中にiconv機能が含まれているため、何かをする必要はありません。 そうでない場合は、 » libiconvライブラリを入手して使用する システムにインストールする必要があります。


インストール手順

この拡張モジュールはデフォルトで有効となります。無効にしたい場合は、コンパイル時に --without-iconv を指定します。

オプションのディレクティブ --with-iconv[=DIR] を使うと、PHP のコンパイル時に使うシステム上の iconv の場所を指定できます。指定しなかった場合はデフォルトの場所を探します。


実行時設定

php.ini の設定により動作が変化します。

Iconv 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
iconv.input_encoding | "" | INI_ALL | PHP 5.6.0 で非推奨となりました。
iconv.output_encoding | "" | INI_ALL | PHP 5.6.0 で非推奨となりました。
iconv.internal_encoding | "" | INI_ALL | PHP 5.6.0 で非推奨となりました。

以下に設定ディレクティブに関する 簡単な説明を示します。

警告

(IBM AIX のように)いくつかのシステムでは "ISO-8859-1" ではなく "ISO8859-1" を使用することがあります。そのような場合は、設定オプションや 関数のパラメータにはこの値を使用しなければなりません。

iconv.input_encoding string
警告

この機能は PHP 5.6.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

PHP 5.6 以降のユーザーは、これを空のままにしておいて、代わりに input_encoding を設定すべきです。

iconv.output_encoding string
警告

この機能は PHP 5.6.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

PHP 5.6 以降のユーザーは、これを空のままにしておいて、代わりに output_encoding を設定すべきです。

iconv.internal_encoding string
警告

この機能は PHP 5.6.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

PHP 5.6 以降のユーザーは、これを空のままにしておいて、代わりに default_charset を設定すべきです。


定義済み定数

この拡張モジュールで使用される iconv 実装の種類を実行時に調べることができます。

iconv で実装されている定数
名前 | 型 | 説明
ICONV_IMPL | string | 実装の名前
ICONV_VERSION | string | 実装のバージョン

注意:

これらの定数を用いて実装に依存するスクリプトを書くことは全く推奨されません。

以下の定数も利用可能です。

その他の iconv定数
名前 | 型 | 説明
ICONV_MIME_DECODE_STRICT | int | iconv_mime_decode()で使用されるビットマスク
ICONV_MIME_DECODE_CONTINUE_ON_ERROR | int | iconv_mime_decode()で使用されるビットマスク


iconv 関数

参考

GNU Recode 関数も参照ください。

目次

  • iconv — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する
  • iconv_mime_decode — MIME ヘッダフィールドをデコードする
  • iconv_mime_decode_headers — 複数の MIME ヘッダフィールドを一度にデコードする
  • iconv_mime_encode — MIME ヘッダフィールドを作成する
  • iconv_set_encoding — 文字エンコーディング変換用の設定を行なう
  • iconv_strlen — 文字列の文字数を返す
  • iconv_strpos — 文字列が最初に現れる場所を見つける
  • iconv_strrpos — 文字列が最後に現れる場所を見つける
  • iconv_substr — 文字列の一部を切り出す
  • ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する


ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

  • ≪ iconv 関数
  • iconv_get_encoding ≫
  • PHP Manual
  • iconv 関数
  • ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

説明

iconv(string $from_encoding, string $to_encoding, string $string): string|false

文字列 string の文字セットを from_encoding から to_encoding に変換します。

パラメータ

from_encoding

string の解釈に使われる文字セット。

to_encoding

変換したいエンコーディング。

文字列 //TRANSLIT を to_encoding に追加すると、翻字機能が有効になります。これは、指定された文字集合で 表せない文字を、見た目の似ている別の文字に置き換える機能です。 文字列 //IGNORE を追加すると、指定された文字集合で 表せない文字は黙って切り捨てられます。 それ以外の場合は E_NOTICE が発生し、この関数は false を返します。

警告

//TRANSLIT が機能したとしたら、 どう動くかはシステムの iconv() の実装 (ICONV_IMPL を参照) に依存します。 実装によっては、//TRANSLIT を無視することが知られています。 よって、to_encoding において無効な文字に対しては、 変換処理は失敗するかもしれません。

string

変換する文字列。

戻り値

変換された文字列を返します。 失敗した場合に false を返します。

例

例1 iconv() の例

<?php
$text = "This is the Euro symbol '?'.";

echo 'Original : ', $text, PHP_EOL;
echo 'TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
echo 'IGNORE : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
echo 'Plain : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

Original : This is the Euro symbol '?'.
TRANSLIT : This is the Euro symbol 'EUR'.
IGNORE   : This is the Euro symbol ''.
Plain    :
Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

注意

注意:

文字エンコーディングと、指定できるオプションは、 インストールされている iconv の実装に依存します。 from_encoding や to_encoding が現在のシステムでサポートされていない場合は、 false を返します。

参考

  • mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • UConverter::transcode() - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する


iconv 拡張モジュールの内部設定変数を取得する

  • ≪ iconv
  • iconv_mime_decode ≫
  • PHP Manual
  • iconv 関数
  • iconv 拡張モジュールの内部設定変数を取得する

iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する

説明

iconv_get_encoding(string $type = "all"): array|string|false

iconv 拡張モジュールの内部設定変数を取得します。

パラメータ

type

オプション type の値は以下のどれかとすることができます。

  • all
  • input_encoding
  • output_encoding
  • internal_encoding

戻り値

成功時に内部設定変数の現在の設定、失敗した場合に false を返します。

type が省略されるか、"all"が指定された場合、 iconv_get_encoding() は上記変数全てを格納した 配列を返します。

例

例1 iconv_get_encoding() の例

<pre>
<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
var_dump(iconv_get_encoding('all'));
?>
</pre>

上の例の出力は以下となります。

Array
(
    [input_encoding] => ISO-8859-1
    [output_encoding] => ISO-8859-1
    [internal_encoding] => UTF-8
)

参考

  • iconv_set_encoding() - 文字エンコーディング変換用の設定を行なう
  • ob_iconv_handler() - 出力バッファハンドラとして文字エンコーディングを変換する


MIME ヘッダフィールドをデコードする

  • ≪ iconv_get_encoding
  • iconv_mime_decode_headers ≫
  • PHP Manual
  • iconv 関数
  • MIME ヘッダフィールドをデコードする

iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — MIME ヘッダフィールドをデコードする

説明

iconv_mime_decode(string $string, int $mode = 0, ?string $encoding = null): string|false

MIME ヘッダフィールドをデコードします。

パラメータ

string

エンコードされたヘッダを表す文字列。

mode

mode は、iconv_mime_decode() が不正な形式の MIME ヘッダフィールドに遭遇した場合の 振る舞いを定義します。以下のビットマスクの組み合わせで指定が可能です。

iconv_mime_decode() で指定できるビットマスク
値 | 定数名 | 説明
1 | ICONV_MIME_DECODE_STRICT | 指定すると、ヘッダは » RFC2047 で定義されている標準に完全準拠する形式でデコードされます。 このオプションはデフォルトでは無効になっています。なぜなら、世の中には おかしなメールソフトが多く存在し、それらは規格に従わずに間違った MIME ヘッダを生成するからです。
2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | 指定すると、iconv_mime_decode_headers() は文法的なエラーを無視し、デコード作業を継続します。

encoding

オプションの encoding パラメータは、結果の 文字セットを指定します。指定されなかった場合、もしくは null の場合は iconv.internal_encoding が用いられます。

戻り値

成功した場合はデコードされた MIME フィールドを、 デコード中にエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 iconv_mime_decode() の例

<?php
// この結果は "Subject: Prufung Prufung" となります。
echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
0, "ISO-8859-1");
?>

参考

  • iconv_mime_decode_headers() - 複数の MIME ヘッダフィールドを一度にデコードする
  • mb_decode_mimeheader() - MIME ヘッダフィールドの文字列をデコードする
  • imap_mime_header_decode() - MIME ヘッダ要素をデコードする
  • imap_base64() - BASE64 でエンコードされたテキストをデコードする
  • imap_qprint() - quoted-printable 文字列を 8 ビット文字列に変換する


複数の MIME ヘッダフィールドを一度にデコードする

  • ≪ iconv_mime_decode
  • iconv_mime_encode ≫
  • PHP Manual
  • iconv 関数
  • 複数の MIME ヘッダフィールドを一度にデコードする

iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — 複数の MIME ヘッダフィールドを一度にデコードする

説明

iconv_mime_decode_headers(string $headers, int $mode = 0, ?string $encoding = null): array|false

複数の MIME ヘッダフィールドを一度にデコードします。

パラメータ

headers

エンコードされたヘッダを表す文字列。

mode

mode は、iconv_mime_decode_headers() が不正な形式の MIME ヘッダフィールドに遭遇した場合の 振る舞いを定義します。以下のビットマスクの組み合わせで指定が可能です。

iconv_mime_decode_headers() で指定できるビットマスク
値 | 定数名 | 説明
1 | ICONV_MIME_DECODE_STRICT | 指定すると、ヘッダは » RFC2047 で定義されている標準に完全準拠する形式でデコードされます。 このオプションはデフォルトでは無効になっています。なぜなら、世の中には おかしなメールソフトが多く存在し、それらは規格に従わずに間違った MIME ヘッダを生成するからです。
2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | 指定すると、iconv_mime_decode_headers() は文法的なエラーを無視し、デコード作業を継続します。

encoding

オプションの encoding パラメータは、結果の 文字セットを指定します。指定されなかった場合、もしくは null の場合は iconv.internal_encoding が用いられます。

戻り値

成功した場合は連想配列を返します。その中身には headers で指定した MIME ヘッダフィールドがすべて含まれています。 デコード中にエラーが発生した場合は false を返します。

連想配列の個々のキーがフィールド名を表し、対応する要素がフィールドの 値を表します。同じ名前のフィールドが複数存在する場合は、 iconv_mime_decode_headers() が自動的に連番つきの 配列をつくり、出現順にその配列に入れられます。 フィールド名は、大文字小文字を区別しない ことに注意して下さい。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 iconv_mime_decode_headers() の例

<?php
$headers_string = <<<EOF
Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
To: example@example.com
Date: Thu, 1 Jan 1970 00:00:00 +0000
Message-Id: <example@example.com>
Received: from localhost (localhost [127.0.0.1]) by localhost
with SMTP id example for <example@example.com>;
Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
(envelope-from example-return-0000-example=example.com@example.com)
Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

EOF;

$headers = iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
print_r($headers);
?>

上の例の出力は以下となります。

Array
(
    [Subject] => Pr?ung Pr?ung
    [To] => example@example.com
    [Date] => Thu, 1 Jan 1970 00:00:00 +0000
    [Message-Id] => <example@example.com>
    [Received] => Array
        (
            [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
            [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
        )

)

参考

  • iconv_mime_decode() - MIME ヘッダフィールドをデコードする
  • mb_decode_mimeheader() - MIME ヘッダフィールドの文字列をデコードする
  • imap_mime_header_decode() - MIME ヘッダ要素をデコードする
  • imap_base64() - BASE64 でエンコードされたテキストをデコードする
  • imap_qprint() - quoted-printable 文字列を 8 ビット文字列に変換する


MIME ヘッダフィールドを作成する

  • ≪ iconv_mime_decode_headers
  • iconv_set_encoding ≫
  • PHP Manual
  • iconv 関数
  • MIME ヘッダフィールドを作成する

iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — MIME ヘッダフィールドを作成する

説明

iconv_mime_encode(string $field_name, string $field_value, array $options = []): string|false

有効な MIME ヘッダフィールドを作成し、返します。 これは以下のような形式になります。

Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile
上の例では "Subject" がフィールド名、"=?ISO-8859-1?..." で始まる部分が フィールドの値となります。

パラメータ

field_name

フィールド名。

field_value

フィールドの値。

options

iconv_mime_encode() の振る舞いを変更するには、 ここで設定項目を含む連想配列を指定します。 iconv_mime_encode() でサポートされている項目は 以下のとおりです。項目名の大文字・小文字は区別されることに注意してください。

iconv_mime_encode() でサポートされる設定項目
項目 | 型 | 説明 | デフォルト値 | 例
scheme | string | フィールドの値のエンコード方法を指定します。"B" か "Q" の どちらかを指定することになるでしょう。"B" は base64 エンコードを、また "Q" は quoted-printable エンコードを表します。 | B | B
input-charset | string | 第 1 パラメータ field_name と第 2 パラメータ field_value の文字セットを指定します。 指定されなかった場合は、iconv_mime_encode() は ini 設定 iconv.internal_encoding であると仮定します。 | iconv.internal_encoding | ISO-8859-1
output-charset | string | MIME ヘッダを作成する文字セットを指定します。 | iconv.internal_encoding | UTF-8
line-length | int | ヘッダ行の長さの最大値を指定します。もし結果がこの値より 長くなった場合は、 » RFC2822 - Internet Message Format に基づいてヘッダを "折りたたんで" 複数行に分割します。 指定されなかった場合は、長さは 76 文字に限定されます。 | 76 | 996
line-break-chars | string | 長いヘッダフィールドに対して "折りたたみ" 処理が行われる場合に 個々の行の後ろに付加される文字列を指定します。 指定されなかった場合は、"\r\n" （CR LF）が用いられます。 このパラメータは、input-charset の値にかかわらず 常に ASCII 文字列として扱われることに注意してください。 | \r\n | \n

戻り値

成功した場合はエンコードした MIME フィールド、 エンコード時にエラーが発生した場合は false を返します。

例

例1 iconv_mime_encode() の例:

<?php
$preferences = array(
"input-charset" => "ISO-8859-1",
"output-charset" => "UTF-8",
"line-length" => 76,
"line-break-chars" => "\n"
);
$preferences["scheme"] = "Q";
// この結果は "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?=" となります。
echo iconv_mime_encode("Subject", "Prufung Prufung", $preferences);

$preferences["scheme"] = "B";
// この結果は "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=" となります。
echo iconv_mime_encode("Subject", "Prufung Prufung", $preferences);
?>

参考

  • imap_binary() - 8 ビット文字列を base64 文字列に変換する
  • mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする
  • imap_8bit() - 8 ビット文字列を quoted-printable 文字列に変換する
  • quoted_printable_encode() - 8 ビット文字列を quoted-printable 文字列に変換する


文字エンコーディング変換用の設定を行なう

  • ≪ iconv_mime_encode
  • iconv_strlen ≫
  • PHP Manual
  • iconv 関数
  • 文字エンコーディング変換用の設定を行なう

iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — 文字エンコーディング変換用の設定を行なう

説明

iconv_set_encoding(string $type, string $encoding): bool

type で指定された内部設定変数の値を、 encoding に変更します。

パラメータ

type

type には以下の値のどれかを指定できます。

  • input_encoding
  • output_encoding
  • internal_encoding

encoding

文字セット。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 iconv_set_encoding() の例

<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
?>

参考

  • iconv_get_encoding() - iconv 拡張モジュールの内部設定変数を取得する
  • ob_iconv_handler() - 出力バッファハンドラとして文字エンコーディングを変換する


文字列の文字数を返す

  • ≪ iconv_set_encoding
  • iconv_strpos ≫
  • PHP Manual
  • iconv 関数
  • 文字列の文字数を返す

iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — 文字列の文字数を返す

説明

iconv_strlen(string $string, ?string $encoding = null): int|false

strlen() とは違い、iconv_strlen() は与えられたバイト列 string 中に現れる文字の数を 指定された文字セットに基づいて数えます。この結果は、必ずしも文字列の バイト数と一致するとは限りません。

パラメータ

string

文字列。

encoding

encoding パラメータが指定されなかった場合、もしくは null の場合、 string のエンコードは iconv.internal_encoding であると判断されます。

戻り値

string の文字数を返します。 処理中にエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • grapheme_strlen() - 書記素単位で文字列の長さを取得する
  • mb_strlen() - 文字列の長さを得る
  • strlen() - 文字列の長さを得る


文字列が最初に現れる場所を見つける

  • ≪ iconv_strlen
  • iconv_strrpos ≫
  • PHP Manual
  • iconv 関数
  • 文字列が最初に現れる場所を見つける

iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — 文字列が最初に現れる場所を見つける

説明

iconv_strpos(
string $haystack,
string $needle,
int $offset = 0,
?string $encoding = null
): int|false

needle が haystack の中で最初に現れる位置を探します。

strpos() の戻り値は needle が見つかった位置の 先頭からのバイト数でしたが、それとは異なり iconv_strpos() の戻り値は needle が見つかった 位置の先頭からの文字数となります。文字数は encoding で指定された文字セットに基づいて 数えられます。

パラメータ

haystack

文字列全体。

needle

検索する文字列。

offset

オプションの offset パラメータは 検索を開始する位置を指定します。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

encoding

encoding パラメータが指定されなかった場合、もしくは null の場合、 string のエンコードは iconv.internal_encoding であると判断されます。

haystack や needle が文字列でない場合、文字列に変換され、文字が並んだ値として適用されます。

戻り値

needle が haystack の中で最初に現れる位置を探します。

もし needle が見つからなかった場合、 iconv_strpos() は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。
7.1.0 | 負の offset をサポートするようになりました。

参考

  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • iconv_strrpos() - 文字列が最後に現れる場所を見つける
  • mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける


文字列が最後に現れる場所を見つける

  • ≪ iconv_strpos
  • iconv_substr ≫
  • PHP Manual
  • iconv 関数
  • 文字列が最後に現れる場所を見つける

iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — 文字列が最後に現れる場所を見つける

説明

iconv_strrpos(string $haystack, string $needle, ?string $encoding = null): int|false

needle が haystack の中で最後に現れる位置を探します。

strrpos() の戻り値は needle が見つかった位置の 先頭からのバイト数でしたが、それとは異なり iconv_strrpos() の戻り値は needle が見つかった 位置の先頭からの文字数となります。 文字数は encoding で指定された文字セットに基づいて数えられます。

パラメータ

haystack

文字列全体。

needle

検索する文字列。

encoding

encoding パラメータが指定されなかった場合、もしくは null の場合、 string のエンコードは iconv.internal_encoding であると判断されます。

haystack や needle が文字列でない場合、文字列に変換され、文字が並んだ値として適用されます。

戻り値

文字列 haystack の中で、 needle が最後に現れた位置を数字で返します。

もし needle が見つからなかった場合、 iconv_strrpos() は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • iconv_strpos() - 文字列が最初に現れる場所を見つける
  • mb_strrpos() - 文字列の中に指定した文字列が最後に現れる位置を見つける


文字列の一部を切り出す

  • ≪ iconv_strrpos
  • ob_iconv_handler ≫
  • PHP Manual
  • iconv 関数
  • 文字列の一部を切り出す

iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — 文字列の一部を切り出す

説明

iconv_substr(
string $string,
int $offset,
?int $length = null,
?string $encoding = null
): string|false

文字列 string の、 offset と length で指定された一部を返します。

パラメータ

string

元の文字列。

offset

offset が負でない場合、 iconv_substr() は string の offset 番目の文字（ゼロから数えて）から切り出します。

offset が負の場合、 iconv_substr() は string の最後から数えて offset 番目の文字から切り出します。

length

length が指定され、かつ正である場合、 返される文字列は offset から数えて最大 length 文字数分となります (string の長さに依存します)。

もし負の length が渡された場合に iconv_substr() が切り出す文字列は、 string の offset 番目の文字からはじまり、文字列の最後から数えて length 文字分戻ったところまでとなります。 offset も負の場合、開始位置は 上で説明した方式で計算されます。

encoding

encoding が指定されなかった場合、もしくは null の場合、文字セットは ini 設定 iconv.internal_encoding で定義された値とみなされます。

offset や length のパラメータは、常に charset で定義された 文字セットにおける文字数と判断されることに注意してください。 一方、substr() の場合はこれらの値を常に バイト数として判断します。

戻り値

文字列 string の、 offset と length で指定された一部を返します。

もし string が offset の文字列長より短い場合は、false が返されます。 string が offset の文字数に等しい場合、 空文字列が返されます。

変更履歴

バージョン | 説明
8.0.0 | length と encoding は、nullable になりました。
7.0.11 | string が offset の文字数に等しい場合、 空文字列が返されます。 これより前のバージョンでは、この場合 false が返されていました。

参考

  • substr() - 文字列の一部分を返す
  • mb_substr() - 文字列の一部を得る
  • mb_strcut() - 文字列の一部を得る


出力バッファハンドラとして文字エンコーディングを変換する

  • ≪ iconv_substr
  • intl ≫
  • PHP Manual
  • iconv 関数
  • 出力バッファハンドラとして文字エンコーディングを変換する

ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する

説明

ob_iconv_handler(string $contents, int $status): string

internal_encoding でエンコードされた文字列を output_encodingに変換します。

internal_encoding および output_encoding は、 iconv_set_encoding() または設定ファイル php.ini で定義されている必要があります。

パラメータ

このハンドラのパラメータについての情報は ob_start() を参照ください。

戻り値

このハンドラの戻り値についての情報は ob_start() を参照ください。

例

例1 ob_iconv_handler() の例

<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
ob_start("ob_iconv_handler"); // 出力バッファリングを開始
?>

参考

  • iconv_get_encoding() - iconv 拡張モジュールの内部設定変数を取得する
  • iconv_set_encoding() - 文字エンコーディング変換用の設定を行なう
  • 出力制御関数 (output control)


国際化関数

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
    • 基本的な使用法
  • Collator — Collator クラス
    • Collator::asort — インデックスの情報を保持しつつ配列を並べ替える
    • Collator::compare — ふたつの Unicode 文字列を比較する
    • Collator::__construct — collator を作成する
    • Collator::create — collator を作成する
    • Collator::getAttribute — 照合用の属性の値を取得する
    • Collator::getErrorCode — collator の直近のエラーコードを取得する
    • Collator::getErrorMessage — collator の直近のエラーコードのテキストを取得する
    • Collator::getLocale — collator のロケール名を取得する
    • Collator::getSortKey — 文字列のソート用のキーを取得する
    • Collator::getStrength — 現在の照合強度を取得する
    • Collator::setAttribute — 照合用の属性を設定する
    • Collator::setStrength — 照合強度を設定する
    • Collator::sort — 指定した collator で配列を並べ替える
    • Collator::sortWithSortKeys — 指定した collator とキーで配列を並べ替える
  • NumberFormatter — NumberFormatter クラス
    • NumberFormatter::create — 数値フォーマッタを作成する
    • NumberFormatter::format — 数値をフォーマットする
    • NumberFormatter::formatCurrency — 通貨の値をフォーマットする
    • NumberFormatter::getAttribute — 属性を取得する
    • NumberFormatter::getErrorCode — フォーマッタの直近のエラーコードを取得する
    • NumberFormatter::getErrorMessage — フォーマッタの直近のエラーメッセージを取得する
    • NumberFormatter::getLocale — フォーマッタのロケールを取得する
    • NumberFormatter::getPattern — フォーマッタのパターンを取得する
    • NumberFormatter::getSymbol — 記号を取得する
    • NumberFormatter::getTextAttribute — テキストの属性を取得する
    • NumberFormatter::parse — 数値をパースする
    • NumberFormatter::parseCurrency — 通貨をパースする
    • NumberFormatter::setAttribute — 属性を設定する
    • NumberFormatter::setPattern — フォーマッタのパターンを設定する
    • NumberFormatter::setSymbol — 記号の値を設定する
    • NumberFormatter::setTextAttribute — テキスト属性を設定する
  • Locale — Locale クラス
    • Locale::acceptFromHttp — 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す
    • Locale::canonicalize — ロケール文字列を正規化する
    • Locale::composeLocale — 正しく並べ替えて区切られたロケール ID を返す
    • Locale::filterMatches — 言語タグフィルタがロケールにマッチするかどうかを調べる
    • Locale::getAllVariants — 入力ロケールの変化系を取得する
    • Locale::getDefault — INTL のグローバル 'default_locale' からデフォルトのロケールを取得する
    • Locale::getDisplayLanguage — 入力ロケールの言語の表示名を、適切に地域化して返す
    • Locale::getDisplayName — 入力ロケールの表示名を、適切に地域化して返す
    • Locale::getDisplayRegion — 入力ロケールの地域の表示名を、適切に地域化して返す
    • Locale::getDisplayScript — 入力ロケールの文字の表示名を、適切に地域化して返す
    • Locale::getDisplayVariant — 入力ロケールの変化形の表示名を、適切に地域化して返す
    • Locale::getKeywords — 入力ロケールのキーワードを取得する
    • Locale::getPrimaryLanguage — 入力ロケールのプライマリ言語を取得する
    • Locale::getRegion — 入力ロケールの地域を取得する
    • Locale::getScript — 入力ロケールの文字を取得する
    • Locale::lookup — その言語にマッチする言語タグの一覧を検索する
    • Locale::parseLocale — ロケール ID のサブタグ要素を連想配列で返す
    • Locale::setDefault — デフォルトの実行時ロケールを設定する
  • Normalizer — Normalizer クラス
    • Normalizer::getRawDecomposition — UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する
    • Normalizer::isNormalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる
    • Normalizer::normalize — 渡された入力を正規化し、正規化後の文字列を返す
  • MessageFormatter — MessageFormatter クラス
    • MessageFormatter::create — 新しいメッセージフォーマッタを作成する
    • MessageFormatter::format — メッセージをフォーマットする
    • MessageFormatter::formatMessage — 手早くメッセージをフォーマットする
    • MessageFormatter::getErrorCode — 直近の操作のエラーコードを取得する
    • MessageFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
    • MessageFormatter::getLocale — フォーマッタを作成した際のロケールを取得する
    • MessageFormatter::getPattern — フォーマッタが使用するパターンを取得する
    • MessageFormatter::parse — パターンを使用して入力文字列をパースする
    • MessageFormatter::parseMessage — 手早く入力文字列をパースする
    • MessageFormatter::setPattern — フォーマッタが使用するパターンを設定する
  • IntlCalendar — IntlCalendar クラス
    • IntlCalendar::add — フィールドに (符号付きの) 一定量の時間を追加する
    • IntlCalendar::after — このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する
    • IntlCalendar::before — このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する
    • IntlCalendar::clear — 単一または全てのフィールドをクリアする
    • IntlCalendar::__construct — インスタンス化を禁止するための private なコンストラクタ
    • IntlCalendar::createInstance — 新しい IntlCalendar を作成する
    • IntlCalendar::equals — ふたつの IntlCalendar オブジェクトの時刻を比較する
    • IntlCalendar::fieldDifference — 指定された時刻と、このオブジェクトの時刻の差を計算する
    • IntlCalendar::fromDateTime — DateTime オブジェクトまたは文字列から、IntlCalendar を作成する
    • IntlCalendar::get — フィールドの値を取得する
    • IntlCalendar::getActualMaximum — オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する
    • IntlCalendar::getActualMinimum — オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する
    • IntlCalendar::getAvailableLocales — データが存在するロケールの配列を取得する
    • IntlCalendar::getDayOfWeekType — 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す
    • IntlCalendar::getErrorCode — オブジェクトに関する直近のエラーコードを取得する
    • IntlCalendar::getErrorMessage — オブジェクトの直近のエラーメッセージを取得する
    • IntlCalendar::getFirstDayOfWeek — カレンダーのロケールに基づいて、週の始めの日を返す
    • IntlCalendar::getGreatestMinimum — 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す
    • IntlCalendar::getKeywordValuesForLocale — ロケールのキーワードの値の集合を返す
    • IntlCalendar::getLeastMaximum — 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す
    • IntlCalendar::getLocale — オブジェクトに関連付けられたロケールを取得する
    • IntlCalendar::getMaximum — フィールドのグローバルな最大値を返す
    • IntlCalendar::getMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を返す
    • IntlCalendar::getMinimum — フィールドのグローバルな最小値を返す
    • IntlCalendar::getNow — 現在時刻を示す数値を取得する
    • IntlCalendar::getRepeatedWallTimeOption — 繰り返される実時間を扱う際の振る舞いを取得する
    • IntlCalendar::getSkippedWallTimeOption — スキップされた実時間を扱う際の振る舞いを取得する
    • IntlCalendar::getTime — このオブジェクトが表す時刻を取得する
    • IntlCalendar::getTimeZone — オブジェクトのタイムゾーンを取得する
    • IntlCalendar::getType — カレンダーのタイプを取得する
    • IntlCalendar::getWeekendTransition — 週末が開始/終了した日からの経過時間を取得する
    • IntlCalendar::inDaylightTime — オブジェクトの時刻が夏時間かを調べる
    • IntlCalendar::isEquivalentTo — 別のカレンダーが、時刻を除いて等しいかを調べる
    • IntlCalendar::isLenient — 日付と時刻の解釈を「緩いモード」で行うかを取得する
    • IntlCalendar::isSet — フィールドが設定されているかを調べる
    • IntlCalendar::isWeekend — ある日付/時刻が週末にあるかを調べる
    • IntlCalendar::roll — 次のフィールドを繰り上げずに、フィールドに値を加算する
    • IntlCalendar::set — 時刻または複数の共通フィールドを一度に設定する
    • IntlCalendar::setDate — 日付のフィールドを設定する
    • IntlCalendar::setDateTime — 日付と時刻のフィールドを設定する
    • IntlCalendar::setFirstDayOfWeek — 週の始まりと見なされる曜日を設定する
    • IntlCalendar::setLenient — 日付/時刻の解釈を「緩いモード」にするかを設定する
    • IntlCalendar::setMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を設定する
    • IntlCalendar::setRepeatedWallTimeOption — 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する
    • IntlCalendar::setSkippedWallTimeOption — 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する
    • IntlCalendar::setTime — エポックからのカレンダーの時刻をミリ秒単位で設定する
    • IntlCalendar::setTimeZone — このカレンダーで使うタイムゾーンを設定する
    • IntlCalendar::toDateTime — IntlCalendar を DateTime オブジェクトに変換する
  • IntlGregorianCalendar — IntlGregorianCalendar クラス
    • IntlGregorianCalendar::__construct — グレゴリオ暦の Calendar クラスを作成する
    • IntlGregorianCalendar::createFromDate — 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する
    • IntlGregorianCalendar::createFromDateTime — 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する
    • IntlGregorianCalendar::getGregorianChange — グレゴリオ暦への切換え日を取得する
    • IntlGregorianCalendar::isLeapYear — 指定された年がうるう年かを判定する
    • IntlGregorianCalendar::setGregorianChange — グレゴリオ暦への切換え日を設定する
  • IntlTimeZone — IntlTimeZone クラス
    • IntlTimeZone::__construct — インスタンス化を禁止するためのprivateなコンストラクタ
    • IntlTimeZone::countEquivalentIDs — 指定した ID を含む等価グループの中にある ID の数を取得する
    • IntlTimeZone::createDefault — このホストのデフォルトタイムゾーンの新しいコピーを作る
    • IntlTimeZone::createEnumeration — 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する
    • IntlTimeZone::createTimeZone — 指定した ID のタイムゾーンオブジェクトを作る
    • IntlTimeZone::createTimeZoneIDEnumeration — 指定されたフィルタ条件を反映した、システムタイムゾーンのイテレータを取得する
    • IntlTimeZone::fromDateTimeZone — DateTimeZone からタイムゾーンオブジェクトを作る
    • IntlTimeZone::getCanonicalID — 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する
    • IntlTimeZone::getDisplayName — このタイムゾーンの、ユーザー向けに表示する名前を取得する
    • IntlTimeZone::getDSTSavings — ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する
    • IntlTimeZone::getEquivalentID — 指定した ID を含む等価グループの ID を取得する
    • IntlTimeZone::getErrorCode — 直近のエラーコードを取得する
    • IntlTimeZone::getErrorMessage — 直近のエラーメッセージを取得する
    • IntlTimeZone::getGMT — GMT (UTC) タイムゾーンを作る
    • IntlTimeZone::getID — タイムゾーン ID を取得する
    • IntlTimeZone::getIDForWindowsID — Windows のタイムゾーンを、システムタイムゾーンに翻訳する
    • IntlTimeZone::getOffset — 指定した時刻の、GMT へのオフセットを取得する
    • IntlTimeZone::getRawOffset — (夏時間を考慮せずに) GMT へのオフセットを取得する
    • IntlTimeZone::getRegion — 指定されたシステムタイムゾーンのIDから、地域コードを取得する
    • IntlTimeZone::getTZDataVersion — ICU が使っているタイムゾーンデータのバージョンを取得する
    • IntlTimeZone::getUnknown — "unknown" なタイムゾーンを取得する
    • IntlTimeZone::getWindowsID — システムタイムゾーンを、Windows のタイムゾーンに翻訳する
    • IntlTimeZone::hasSameRules — このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる
    • IntlTimeZone::toDateTimeZone — DateTimeZone オブジェクトに変換する
    • IntlTimeZone::useDaylightTime — このタイムゾーンが夏時間を採用しているかどうかを調べる
  • IntlDateFormatter — IntlDateFormatter クラス
    • IntlDateFormatter::create — Date Formatter を作成する
    • IntlDateFormatter::format — 日付/時刻 の値を文字列としてフォーマットする
    • IntlDateFormatter::formatObject — オブジェクトの書式を設定する
    • IntlDateFormatter::getCalendar — IntlDateFormatter が使用するカレンダー型を取得する
    • IntlDateFormatter::getDateType — IntlDateFormatter が使用する日付形式を取得する
    • IntlDateFormatter::getErrorCode — 直近の操作のエラーコードを取得する
    • IntlDateFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
    • IntlDateFormatter::getLocale — Formatter が使用するロケールを取得する
    • IntlDateFormatter::getPattern — IntlDateFormatter が使用するパターンを取得する
    • IntlDateFormatter::getTimeType — IntlDateFormatter が使用する時刻形式を取得する
    • IntlDateFormatter::getTimeZoneId — IntlDateFormatter が使用するタイムゾーン ID を取得する
    • IntlDateFormatter::getCalendarObject — カレンダーオブジェクトのコピーを取得する
    • IntlDateFormatter::getTimeZone — タイムゾーンを取得する
    • IntlDateFormatter::isLenient — IntlDateFormatter で使用する寛大さを取得する
    • IntlDateFormatter::localtime — 文字列をパースして、フィールドベースの時刻値にする
    • IntlDateFormatter::parse — 文字列をパースしてタイムスタンプにする
    • IntlDateFormatter::setCalendar — Formatter が使うカレンダー型を設定する
    • IntlDateFormatter::setLenient — パーサの寛大さを設定する
    • IntlDateFormatter::setPattern — IntlDateFormatter が使用するパターンを設定する
    • IntlDateFormatter::setTimeZone — タイムゾーンを設定する
  • ResourceBundle — ResourceBundle クラス
    • ResourceBundle::count — バンドル内の要素数を取得する
    • ResourceBundle::create — リソースバンドルを作成する
    • ResourceBundle::get — バンドルからデータを取得する
    • ResourceBundle::getErrorCode — バンドルの直近のエラーコードを取得する
    • ResourceBundle::getErrorMessage — バンドルの直近のエラーメッセージを取得する
    • ResourceBundle::getLocales — サポートするロケールを取得する
  • Spoofchecker — Spoofchecker クラス
    • Spoofchecker::areConfusable — 指定された文字列が、読み手を混乱させうるかをチェックする
    • Spoofchecker::__construct — コンストラクタ
    • Spoofchecker::isSuspicious — 指定されたテキストに、疑わしい文字が含まれていないかをチェックする
    • Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する
    • Spoofchecker::setChecks — 実行するチェックを設定する
    • Spoofchecker::setRestrictionLevel — 制限レベルを設定する
  • Transliterator — Transliterator クラス
    • Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ
    • Transliterator::create — Transliterator を作成する
    • Transliterator::createFromRules — 規則に基づいた Transliterator を作成する
    • Transliterator::createInverse — 逆方向の Transliterator を作成する
    • Transliterator::getErrorCode — 直近のエラーコードを取得する
    • Transliterator::getErrorMessage — 直近のエラーメッセージを取得する
    • Transliterator::listIDs — Transliterator の ID を取得する
    • Transliterator::transliterate — 文字列を音訳する
  • IntlBreakIterator — IntlBreakIterator クラス
    • IntlBreakIterator::__construct — インスタンス化を禁止するためのprivateなコンストラクタ
    • IntlBreakIterator::createCharacterInstance — 文字シーケンスの組み合わせの境界用にイテレータを作る
    • IntlBreakIterator::createCodePointInstance — コードポイントの境界用にイテレータを作る
    • IntlBreakIterator::createLineInstance — 論理的に可能な改行用にイテレータを作る
    • IntlBreakIterator::createSentenceInstance — 文末用にイテレータを作る
    • IntlBreakIterator::createTitleInstance — タイトル文字の区切り用にイテレータを作る
    • IntlBreakIterator::createWordInstance — 単語の区切り用にイテレータを作る
    • IntlBreakIterator::current — 現在位置のインデックスを取得する
    • IntlBreakIterator::first — テキスト内の最初の文字を場所を取得する
    • IntlBreakIterator::following — 指定したオフセット以降の最初の境界までイテレータを進める
    • IntlBreakIterator::getErrorCode — このオブジェクトの直近のエラーコードを取得する
    • IntlBreakIterator::getErrorMessage — このオブジェクトの直近のエラーメッセージを取得する
    • IntlBreakIterator::getLocale — このオブジェクトに関連づけられたロケールを取得する
    • IntlBreakIterator::getPartsIterator — 境界と境界の間の navigating fragments 用にイテレータを作る
    • IntlBreakIterator::getText — スキャンするテキストを取得する
    • IntlBreakIterator::isBoundary — あるオフセットが境界のオフセットかどうかを調べる
    • IntlBreakIterator::last — イテレータの位置を、最後の文字より後に設定する
    • IntlBreakIterator::next — イテレータを次の境界まで進める
    • IntlBreakIterator::preceding — イテレータの位置を、指定したオフセット以前の最初の境界に設定する
    • IntlBreakIterator::previous — イテレータの位置を、現在位置の直前の境界に設定する
    • IntlBreakIterator::setText — スキャンするテキストを設定する
  • IntlRuleBasedBreakIterator — IntlRuleBasedBreakIterator クラス
    • IntlRuleBasedBreakIterator::__construct — ルールセットから iterator を作成する
    • IntlRuleBasedBreakIterator::getBinaryRules — コンパイル済みのルールを、バイナリで取得する
    • IntlRuleBasedBreakIterator::getRules — このオブジェクトを作るのに使われているルールを取得する
    • IntlRuleBasedBreakIterator::getRuleStatus — 現在の境界位置を決めるルールから、ステータスの最大値を取得する
    • IntlRuleBasedBreakIterator::getRuleStatusVec — 現在の境界位置から定まるルールから、ステータス値を取得する
  • IntlCodePointBreakIterator — IntlCodePointBreakIterator クラス
    • IntlCodePointBreakIterator::getLastCodePoint — イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する
  • IntlDatePatternGenerator — IntlDatePatternGenerator クラス
    • IntlDatePatternGenerator::create — IntlDatePatternGenerator を作成する
    • IntlDatePatternGenerator::getBestPattern — もっとも適合した 日付/時刻 のフォーマットを決定する
  • IntlPartsIterator — IntlPartsIterator クラス
    • IntlPartsIterator::getBreakIterator — この parts iterator の裏付けとなる、IntlBreakIterator を取得する
  • UConverter — UConverter クラス
    • UConverter::__construct — UConverter オブジェクトを作る
    • UConverter::convert — ある文字セットから別の文字セットに文字列を変換する
    • UConverter::fromUCallback — デフォルトの "from" コールバック関数
    • UConverter::getAliases — 指定した名前のエイリアスを取得する
    • UConverter::getAvailable — 利用可能なコンバーター名を取得する
    • UConverter::getDestinationEncoding — 変換先エンコーディングを取得する
    • UConverter::getDestinationType — 変換先のコンバーターの型を取得する
    • UConverter::getErrorCode — 直近のエラーコードを取得する
    • UConverter::getErrorMessage — 直近のエラーメッセージを取得する
    • UConverter::getSourceEncoding — 変換元エンコーディングを取得する
    • UConverter::getSourceType — 変換元のコンバーターの型を取得する
    • UConverter::getStandards — コンバーター名に対応する標準を取得する
    • UConverter::getSubstChars — 置換文字を取得する
    • UConverter::reasonText — コールバックの理由を表す文字列を取得する
    • UConverter::setDestinationEncoding — 変換先エンコーディングを設定する
    • UConverter::setSourceEncoding — 変換元エンコーディングを設定する
    • UConverter::setSubstChars — 置換文字を設定する
    • UConverter::toUCallback — デフォルトの "to" コールバック関数
    • UConverter::transcode — ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
  • Grapheme 関数
    • grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
    • grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
    • grapheme_strlen — 書記素単位で文字列の長さを取得する
    • grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
    • grapheme_substr — 部分文字列を返す
  • IDN 関数
    • idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する
    • idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する
  • IntlChar — IntlChar クラス
    • IntlChar::charAge — コードポイントの "age" を取得する
    • IntlChar::charDigitValue — 10進数の桁の文字を桁の値として取得する
    • IntlChar::charDirection — コードポイントの双方向カテゴリの値を取得する
    • IntlChar::charFromName — 名前で Unicode 文字を探し、コードポイントの値を返す
    • IntlChar::charMirror — コードポイントの "鏡文字" を取得する
    • IntlChar::charName — Unicode 文字の名前を取得する
    • IntlChar::charType — コードポイントの一般カテゴリの値を取得する
    • IntlChar::chr — コードポイント値に対応する、Unicode 文字を返す
    • IntlChar::digit — コードポイントの10進の数値を、指定された基数で返す
    • IntlChar::enumCharNames — 指定された範囲の全てのUnicode文字を走査する
    • IntlChar::enumCharTypes — Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する
    • IntlChar::foldCase — コードポイントに対してケースフォールディングを行う
    • IntlChar::forDigit — 指定された整数と基数を表す文字を取得する
    • IntlChar::getBidiPairedBracket — コードポイントと対になる括弧文字を取得する
    • IntlChar::getBlockCode — コードポイントが含まれる割当ブロックを取得する
    • IntlChar::getCombiningClass — コードポイントの合成クラスを取得する
    • IntlChar::getFC_NFKC_Closure — コードポイントの FC_NFKC_Closure プロパティの値を取得する
    • IntlChar::getIntPropertyMaxValue — Unicode プロパティの最大値を取得する
    • IntlChar::getIntPropertyMinValue — Unicode プロパティの最小値を取得する
    • IntlChar::getIntPropertyValue — コードポイントに対応する、Unicode プロパティの値を取得する
    • IntlChar::getNumericValue — Unicode のコードポイントの数値の値を取得する
    • IntlChar::getPropertyEnum — プロパティの名前に対応する定数値を取得する
    • IntlChar::getPropertyName — プロパティに対応する、Unicode での名前を取得する
    • IntlChar::getPropertyValueEnum — 指定された値の名前に対応する、プロパティの値を取得する
    • IntlChar::getPropertyValueName — プロパティの値に対応する、Unicode の名前を取得する
    • IntlChar::getUnicodeVersion — Unicode のバージョンを取得する
    • IntlChar::hasBinaryProperty — コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
    • IntlChar::isalnum — コードポイントが英数字であるかを調べる
    • IntlChar::isalpha — コードポイントがアルファベットかを調べる
    • IntlChar::isbase — コードポイントが基底文字に含まれるかを調べる
    • IntlChar::isblank — コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる
    • IntlChar::iscntrl — コードポイントが制御文字かどうかを調べる
    • IntlChar::isdefined — コードポイントが定義されているかどうかを調べる
    • IntlChar::isdigit — コードポイントが、数字であるかを調べる
    • IntlChar::isgraph — コードポイントが図形文字であるかを調べる
    • IntlChar::isIDIgnorable — コードポイントが無視できる文字かを調べる
    • IntlChar::isIDPart — コードポイントが識別子として使えるかを調べる
    • IntlChar::isIDStart — コードポイントが識別子の最初の文字として使えるかを調べる
    • IntlChar::isISOControl — コードポイントがISOで定義された制御文字であるかを調べる
    • IntlChar::isJavaIDPart — コードポイントが、Java の識別子として使えるかを調べる
    • IntlChar::isJavaIDStart — コードポイントが Java の識別子の最初の文字として使えるかを調べる
    • IntlChar::isJavaSpaceChar — コードポイントが Java におけるスペース文字であるかを調べる
    • IntlChar::islower — コードポイントが小文字かどうかを調べる
    • IntlChar::isMirrored — コードポイントが Bidi_Mirrored プロパティを持つかを調べる
    • IntlChar::isprint — コードポイントが印字可能な文字かを調べる
    • IntlChar::ispunct — コードポイントが句読点の文字かどうかを調べる
    • IntlChar::isspace — コードポイントが、スペース文字であるかを調べる
    • IntlChar::istitle — コードポイントがタイトルケース文字であるかを調べる
    • IntlChar::isUAlphabetic — コードポイントが、Alphabetic プロパティを持つかを調べる
    • IntlChar::isULowercase — コードポイントが小文字のUnicodeプロパティを持つかを調べる
    • IntlChar::isupper — コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
    • IntlChar::isUUppercase — コードポイントが大文字のUnicodeプロパティを持つかを調べる
    • IntlChar::isUWhiteSpace — コードポイントが、White_Space プロパティを持つかを調べる
    • IntlChar::isWhitespace — コードポイントが、ICU の空白文字であるかを調べる
    • IntlChar::isxdigit — コードポイントが、16進数の文字であるかを調べる
    • IntlChar::ord — 文字に対応する Unicode コードポイントを返す
    • IntlChar::tolower — Unicode 文字を小文字にする
    • IntlChar::totitle — Unicode 文字をタイトルケースにする
    • IntlChar::toupper — Unicode 文字を大文字にする
  • IntlException — intl のエラー用の例外クラス
  • IntlIterator — IntlIterator クラス
    • IntlIterator::current — 現在の要素を取得する
    • IntlIterator::key — 現在のキーを取得する
    • IntlIterator::next — 次の要素に進む
    • IntlIterator::rewind — イテレータを最初の要素に戻す
    • IntlIterator::valid — 現在の位置が有効かを調べる
  • 国際化 関数
    • intl_error_name — 指定したエラーコードに対応する名前を取得する
    • intl_get_error_code — 直近のエラーコードを取得する
    • intl_get_error_message — 直近のエラーの説明を取得する
    • intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる


はじめに

国際化用拡張モジュール (これ以降では Intl と略します) は » ICU ライブラリのラッパーです。 PHP プログラマが、ロケール関連のさまざまな操作を行えるようにします。 フォーマット、音訳、エンコード変換、カレンダーの処理、 » UCA 準拠の照合順序 (collation)、 テキストの区切り、ロケール識別子やタイムゾーンや書記素を用いた操作などが可能です。

ICU の API に従って作成されているので、 C/C++ や Java で ICU を使ったことがあるかたは簡単に PHP の API も使えることでしょう。 また、ICU のドキュメントを参考にすればさまざまな ICU の関数について知ることができます。

Intl はいくつかのモジュールで構成されており、 各モジュールが対応する ICU API を公開しています。

  • Collator: ロケールに応じた適切な並び順を考慮して、文字列の比較を行います。
  • Number Formatter: 各地域固有の書式、あるいは指定した規則に基づいて数値を表示したり、 文字列を数値として解釈したりします。
  • Message Formatter: メッセージ関連のデータ (数値や日付など) をパターンやロケールにあわせて適切にフォーマットしたり、 メッセージをパースしてデータを取り出したりします。 複数形を扱ったり、ロケールごとの数値や通貨や条件などを扱ったりすることもできます。
  • Normalizer: テキストに対して Unicode の正規化を行ったり、 指定した文字列が正規化済みかどうかを調べたりします。
  • Locale: ロケール識別子を扱うための機能を提供します。 たとえばロケール識別子のパースや作成、検索などを行います。
  • Calendar: ロケールにあわせたカレンダーの操作を行うためのクラスを提供します。 指定したロケールのタイムゾーンや週の最初の曜日を取得したり、 サマータイム中であるか否かを調べたりすることもできます。
  • Timezone: » "Olson" database のラッパーを提供します。 世界中のタイムゾーンに関する情報が含まれています。
  • Date formatter: ローカライズした書式や指定したパターン、ルールに基づいて日付と時刻を表示できるようにします。 また、文字列を日付や時刻としてパースすることもできます。

リンク

  • » ICU のドキュメント

  • » ICU ユーザーガイド

  • » Unicode Collation Algorithm


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • intl
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

この拡張モジュールをビルドするには » ICU ライブラリのバージョン 4.0.0 以降をインストールする必要があります。 PHP 7.4.0 以降は、ICU 50.1 以降が必要です。


インストール手順

PHP のコンパイル時に --enable-intl を指定すると、 この拡張モジュールは有効になります。

ICU のインストール場所が標準と異なる場合は、その場所を環境変数 LD_LIBRARY_PATH に指定しましょう。 そうすればリンカがライブラリを見つけてくれるようになります。

$ export LD_LIBRARY_PATH=/opt/icu/lib

PHP と ICU をデフォルトの場所にインストールしている場合は、 configure 時の追加のオプションは不要です。


実行時設定

php.ini の設定により動作が変化します。

Intl 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
intl.default_locale |  | INI_ALL |
intl.error_level | 0 | INI_ALL |
intl.use_exceptions | 0 | INI_ALL | PECL 3.0.0a1 以降で使用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

intl.default_locale string

何も指定しなかった (引数を省略したり NULL を渡したりした) 場合に intl 関数が使うロケール。 これは ICU のロケールであり、システムのロケールではありません。 組み込みの ICU ロケールとそのデータは、 » https://icu4c-demos.unicode.org/icu-bin/locexp で確認できます。

デフォルト値は空文字列で、これは ICU のデフォルトロケールを意味します。 いったん設定したら、ini の設定でこのデフォルト値に戻すことはできません。 このデフォルトに依存することはおすすめしません。その値がサーバーの環境に依存するからです。

intl.error_level int

ICU 関数でエラーが発生したときに生成されるエラーメッセージのタイプ。 これは PHP のエラーレベル、 すなわち E_WARNING などになります。 0 を設定すれば、エラーメッセージを抑制できます。 この設定は、エラーを表す戻り値や intl_get_error_code() が返す値、 そしてエラーコードやエラーメッセージを取得するクラスメソッドなどには影響しません。

デフォルト値は 0 です。

intl.use_exceptions int

true にすると、intl 関数でエラーが発生したときに例外を発生させます。 この例外は、IntlException 型になります。 intl.error_level によるエラーメッセージと組み合わせて使うことになるでしょう。

デフォルト値は false です。


定義済み定数

INTL_ICU_DATA_VERSION (string)
ICU4C のデータバージョン。
INTL_ICU_VERSION (string)
ICUライブラリのバージョン。10進の数字をドットで区切った文字列です。
INTL_MAX_LOCALE_LEN (int)
ロケール名の長さの制限。PHP コード内では 80 文字までに制限されており、 それより長いロケール名は使用できません。
IDNA_DEFAULT (int)
IDN 関数の入力で、アサインされていないコードポイントの処理を拒否し、 入力がドメイン名 ASCII 規則を満たすかどうかをチェックしません。
IDNA_ALLOW_UNASSIGNED (int)
IDN 関数の入力で、アサインされていないコードポイントの処理を許可します。
IDNA_USE_STD3_RULES (int)
IDN 関数の入力がドメイン名 ASCII 規則を満たすかどうかをチェックします。
IDNA_CHECK_BIDI (int)
入力が BiDi の規則を満たすかどうかをチェックします。 IDNA2003 の実装ではこの設定は無視され、常にこのチェックを行います。
IDNA_CHECK_CONTEXTJ (int)
入力が CONTEXTJ の規則を満たすかどうかをチェックします。 IDNA2003 の実装ではこの設定は無視されます。このチェックは IDNA2008 から追加されたものだからです。
IDNA_NONTRANSITIONAL_TO_ASCII (int)
idn_to_ascii() で非移行的処理をするためのオプション。 デフォルトでは移行的処理となります。このオプションは IDNA2003 の実装では無視されます。
IDNA_NONTRANSITIONAL_TO_UNICODE (int)
idn_to_utf8() で非移行的処理をするためのオプション。 デフォルトでは移行的処理となります。このオプションは IDNA2003 の実装では無視されます。
INTL_IDNA_VARIANT_2003 (int)
IDNA 2003 のアルゴリズムを idn_to_utf8() と idn_to_ascii() で使います。これはデフォルトの設定です。 この定数およびデフォルトの使用は、PHP 7.2.0 以降は非推奨です。
INTL_IDNA_VARIANT_UTS46 (int)
UTS #46 アルゴリズムを idn_to_utf8() と idn_to_ascii() で使います。 ICU 4.6 以降で利用可能です。
GRAPHEME_EXTR_COUNT (int)
展開される graphme クラスタのデフォルト数。
GRAPHEME_EXTR_MAXBYTES (int)
返される最大バイト数。
GRAPHEME_EXTR_MAXCHARS (int)
返されるUTF-8文字の最大文字数。

UTS #46 アルゴリズムを idn_to_utf8() と idn_to_ascii() で使うときに、 これらのエラーがビットセットで報告されます。

IDNA_ERROR_EMPTY_LABEL (int)
IDNA_ERROR_LABEL_TOO_LONG (int)
IDNA_ERROR_DOMAIN_NAME_TOO_LONG (int)
IDNA_ERROR_LEADING_HYPHEN (int)
IDNA_ERROR_TRAILING_HYPHEN (int)
IDNA_ERROR_HYPHEN_3_4 (int)
IDNA_ERROR_LEADING_COMBINING_MARK (int)
IDNA_ERROR_DISALLOWED (int)
IDNA_ERROR_PUNYCODE (int)
IDNA_ERROR_LABEL_HAS_DOT (int)
IDNA_ERROR_INVALID_ACE_LABEL (int)
IDNA_ERROR_BIDI (int)
IDNA_ERROR_CONTEXTJ (int)
ULOC_ACTUAL_LOCALE (int)
データが実際に由来するロケール。
ULOC_VALID_LOCALE (int)
ICU によってサポートされている、もっとも特定されたロケール。
U_AMBIGUOUS_ALIAS_WARNING (int)
This converter alias can go to different converter implementations.
U_BAD_VARIABLE_DEFINITION (int)
Missing '$' or duplicate variable name.
U_BRK_ASSIGN_ERROR (int)
Syntax error in RBBI rule assignment statement.
U_BRK_ERROR_LIMIT (int)
This must always be the last value to indicate the limit for Break Iterator failures.
U_BRK_ERROR_START (int)
Start of codes indicating Break Iterator failures.
U_BRK_HEX_DIGITS_EXPECTED (int)
Hex digits expected as part of a escaped char in a rule.
U_BRK_INIT_ERROR (int)
Initialization failure. Probable missing ICU Data.
U_BRK_INTERNAL_ERROR (int)
An internal error (bug) was detected.
U_BRK_MALFORMED_RULE_TAG (int)
The {nnn} tag on a rule is mal formed.
U_BRK_MISMATCHED_PAREN (int)
Mis-matched parentheses in an RBBI rule.
U_BRK_NEW_LINE_IN_QUOTED_STRING (int)
Missing closing quote in an RBBI rule.
U_BRK_RULE_EMPTY_SET (int)
Rule contains an empty Unicode Set.
U_BRK_RULE_SYNTAX (int)
Syntax error in RBBI rule.
U_BRK_SEMICOLON_EXPECTED (int)
Missing ';' at the end of a RBBI rule.
U_BRK_UNCLOSED_SET (int)
UnicodeSet witing an RBBI rule missing a closing ']'.
U_BRK_UNDEFINED_VARIABLE (int)
Use of an undefined $Variable in an RBBI rule.
U_BRK_UNRECOGNIZED_OPTION (int)
Option in RBBI rules not recognized.
U_BRK_VARIABLE_REDFINITION (int)
RBBI rule variable redefined.
U_BUFFER_OVERFLOW_ERROR (int)
A result would not fit in the supplied buffer.
U_CE_NOT_FOUND_ERROR (int)
Currently used only while setting variable top, but can be used generally.
U_COLLATOR_VERSION_MISMATCH (int)
Collator version is not compatible with the base version.
U_DIFFERENT_UCA_VERSION (int)
ucol_open encountered a mismatch between UCA version and collator image version, so the collator was constructed from rules. No impact to further function.
U_ENUM_OUT_OF_SYNC_ERROR (int)
UEnumeration out of sync with underlying collection.
U_ERROR_LIMIT (int)
Alias of U_PLUGIN_ERROR_LIMIT.
U_ERROR_WARNING_LIMIT (int)
This must always be the last warning value to indicate the limit for UErrorCode warnings (last warning code +1).
U_ERROR_WARNING_START (int)
Start of information results (semantically successful).
U_FILE_ACCESS_ERROR (int)
The requested file cannot be found.
U_FMT_PARSE_ERROR_LIMIT (int)
The limit for format library errors.
U_FMT_PARSE_ERROR_START (int)
Start of format library errors.
U_IDNA_ACE_PREFIX_ERROR (int)
U_IDNA_CHECK_BIDI_ERROR (int)
U_IDNA_DOMAIN_NAME_TOO_LONG_ERROR (int)
U_IDNA_ERROR_LIMIT (int)
U_IDNA_ERROR_START (int)
U_IDNA_LABEL_TOO_LONG_ERROR (int)
U_IDNA_PROHIBITED_ERROR (int)
U_IDNA_STD3_ASCII_RULES_ERROR (int)
U_IDNA_UNASSIGNED_ERROR (int)
U_IDNA_VERIFICATION_ERROR (int)
U_IDNA_ZERO_LENGTH_LABEL_ERROR (int)
U_ILLEGAL_ARGUMENT_ERROR (int)
Indicates an incorrect argument value.
U_ILLEGAL_CHAR_FOUND (int)
Character conversion: Illegal input sequence.
U_ILLEGAL_CHAR_IN_SEGMENT (int)
Unused as of ICU 2.4.
U_ILLEGAL_CHARACTER (int)
A special character is outside its allowed context.
U_ILLEGAL_ESCAPE_SEQUENCE (int)
ISO-2022 illlegal escape sequence.
U_ILLEGAL_PAD_POSITION (int)
Pad symbol misplaced in number pattern.
U_INDEX_OUTOFBOUNDS_ERROR (int)
Trying to access the index that is out of bounds.
U_INTERNAL_PROGRAM_ERROR (int)
Indicates a bug in the library code.
U_INTERNAL_TRANSLITERATOR_ERROR (int)
Internal transliterator system error.
U_INVALID_CHAR_FOUND (int)
Character conversion: Unmappable input sequence. In other APIs: Invalid character.
U_INVALID_FORMAT_ERROR (int)
Data format is not what is expected.
U_INVALID_FUNCTION (int)
A '&fn()' rule specifies an unknown transliterator.
U_INVALID_ID (int)
A '::id' rule specifies an unknown transliterator.
U_INVALID_PROPERTY_PATTERN (int)
Unused as of ICU 2.4.
U_INVALID_RBT_SYNTAX (int)
A '::id' rule was passed to the RuleBasedTransliterator parser.
U_INVALID_STATE_ERROR (int)
Requested operation can not be completed with ICU in its current state.
U_INVALID_TABLE_FILE (int)
Conversion table file not found.
U_INVALID_TABLE_FORMAT (int)
Conversion table file found, but corrupted.
U_INVARIANT_CONVERSION_ERROR (int)
Unable to convert a UChar* string to char* with the invariant converter.
U_MALFORMED_EXPONENTIAL_PATTERN (int)
Grouping symbol in exponent pattern.
U_MALFORMED_PRAGMA (int)
A 'use' pragma is invalid.
U_MALFORMED_RULE (int)
Elements of a rule are misplaced.
U_MALFORMED_SET (int)
A UnicodeSet pattern is invalid.
U_MALFORMED_SYMBOL_REFERENCE (int)
Unused as of ICU 2.4.
U_MALFORMED_UNICODE_ESCAPE (int)
A Unicode escape pattern is invalid.
U_MALFORMED_VARIABLE_DEFINITION (int)
A variable definition is invalid.
U_MALFORMED_VARIABLE_REFERENCE (int)
A variable reference is invalid.
U_MEMORY_ALLOCATION_ERROR (int)
Memory allocation error.
U_MESSAGE_PARSE_ERROR (int)
Unable to parse a message (message format).
U_MISMATCHED_SEGMENT_DELIMITERS (int)
Unused as of ICU 2.4.
U_MISPLACED_ANCHOR_START (int)
A start anchor appears at an illegal position.
U_MISPLACED_COMPOUND_FILTER (int)
A compound filter is in an invalid location.
U_MISPLACED_CURSOR_OFFSET (int)
A cursor offset occurs at an illegal position.
U_MISPLACED_QUANTIFIER (int)
A quantifier appears after a segment close delimiter.
U_MISSING_OPERATOR (int)
A rule contains no operator.
U_MISSING_RESOURCE_ERROR (int)
The requested resource cannot be found.
U_MISSING_SEGMENT_CLOSE (int)
Unused as of ICU 2.4.
U_MULTIPLE_ANTE_CONTEXTS (int)
More than one ante context.
U_MULTIPLE_COMPOUND_FILTERS (int)
More than one compound filter.
U_MULTIPLE_CURSORS (int)
More than one cursor.
U_MULTIPLE_DECIMAL_SEPARATORS (int)
More than one decimal separator in number pattern.
U_MULTIPLE_DECIMAL_SEPERATORS (int)
Alias of U_MULTIPLE_DECIMAL_SEPARATORS.
U_MULTIPLE_EXPONENTIAL_SYMBOLS (int)
More than one exponent symbol in number pattern.
U_MULTIPLE_PAD_SPECIFIERS (int)
More than one pad symbol in number pattern.
U_MULTIPLE_PERCENT_SYMBOLS (int)
More than one percent symbol in number pattern.
U_MULTIPLE_PERMILL_SYMBOLS (int)
More than one permill symbol in number pattern.
U_MULTIPLE_POST_CONTEXTS (int)
More than one post context.
U_NO_SPACE_AVAILABLE (int)
No space available for in-buffer expansion for Arabic shaping.
U_NO_WRITE_PERMISSION (int)
Attempt to modify read-only or constant data.
U_PARSE_ERROR (int)
Equivalent to Java ParseException.
U_PARSE_ERROR_LIMIT (int)
The limit for Transliterator errors.
U_PARSE_ERROR_START (int)
Start of Transliterator errors.
U_PATTERN_SYNTAX_ERROR (int)
Syntax error in format pattern.
U_PRIMARY_TOO_LONG_ERROR (int)
User tried to set variable top to a primary that is longer than two bytes.
U_REGEX_BAD_ESCAPE_SEQUENCE (int)
Unrecognized backslash escape sequence in pattern.
U_REGEX_BAD_INTERVAL (int)
Error in {min,max} interval.
U_REGEX_ERROR_LIMIT (int)
This must always be the last value to indicate the limit for regexp errors.
U_REGEX_ERROR_START (int)
Start of codes indicating Regexp failures.
U_REGEX_INTERNAL_ERROR (int)
An internal error (bug) was detected.
U_REGEX_INVALID_BACK_REF (int)
Back-reference to a non-existent capture group.
U_REGEX_INVALID_FLAG (int)
Invalid value for match mode flags.
U_REGEX_INVALID_STATE (int)
RegexMatcher in invalid state for requested operation.
U_REGEX_LOOK_BEHIND_LIMIT (int)
Look-Behind pattern matches must have a bounded maximum length.
U_REGEX_MAX_LT_MIN (int)
In {min,max}, max is less than min.
U_REGEX_MISMATCHED_PAREN (int)
Incorrectly nested parentheses in regexp pattern.
U_REGEX_NUMBER_TOO_BIG (int)
Decimal number is too large.
U_REGEX_PROPERTY_SYNTAX (int)
Incorrect Unicode property.
U_REGEX_RULE_SYNTAX (int)
Syntax error in regexp pattern.
U_REGEX_SET_CONTAINS_STRING (int)
Regexps cannot have UnicodeSets containing strings.
U_REGEX_UNIMPLEMENTED (int)
Use of regexp feature that is not yet implemented.
U_RESOURCE_TYPE_MISMATCH (int)
An operation is requested over a resource that does not support it.
U_RULE_MASK_ERROR (int)
A rule is hidden by an earlier more general rule.
U_SAFECLONE_ALLOCATED_WARNING (int)
A SafeClone operation required allocating memory (informational only).
U_SORT_KEY_TOO_SHORT_WARNING (int)
Number of levels requested in getBound is higher than the number of levels in the sort key.
U_STANDARD_ERROR_LIMIT (int)
This must always be the last value to indicate the limit for standard errors.
U_STATE_OLD_WARNING (int)
ICU has to use compatibility layer to construct the service. Expect performance/memory usage degradation.
U_STATE_TOO_OLD_ERROR (int)
ICU cannot construct a service from this state, as it is no longer supported.
U_STRING_NOT_TERMINATED_WARNING (int)
An output string could not be NUL-terminated because output length==destCapacity.
U_STRINGPREP_CHECK_BIDI_ERROR (int)
Alias of U_IDNA_CHECK_BIDI_ERROR.
U_STRINGPREP_PROHIBITED_ERROR (int)
Alias of U_IDNA_PROHIBITED_ERROR.
U_STRINGPREP_UNASSIGNED_ERROR (int)
Alias of U_IDNA_UNASSIGNED_ERROR.
U_TOO_MANY_ALIASES_ERROR (int)
There are too many aliases in the path to the requested resource. It is very possible that a circular alias definition has occured.
U_TRAILING_BACKSLASH (int)
A dangling backslash.
U_TRUNCATED_CHAR_FOUND (int)
Character conversion: Incomplete input sequence.
U_UNCLOSED_SEGMENT (int)
A closing ')' is missing.
U_UNDEFINED_SEGMENT_REFERENCE (int)
A segment reference does not correspond to a defined segment.
U_UNDEFINED_VARIABLE (int)
A variable reference does not correspond to a defined variable.
U_UNEXPECTED_TOKEN (int)
Syntax error in format pattern.
U_UNMATCHED_BRACES (int)
Braces do not match in message pattern.
U_UNQUOTED_SPECIAL (int)
A special character was not quoted or escaped.
U_UNSUPPORTED_ATTRIBUTE (int)
Unused as of ICU 2.4.
U_UNSUPPORTED_ERROR (int)
Requested operation not supported in current context.
U_UNSUPPORTED_ESCAPE_SEQUENCE (int)
ISO-2022 unsupported escape sequence.
U_UNSUPPORTED_PROPERTY (int)
Unused as of ICU 2.4.
U_UNTERMINATED_QUOTE (int)
A closing single quote is missing.
U_USELESS_COLLATOR_ERROR (int)
Collator is options only and no base is specified.
U_USING_DEFAULT_WARNING (int)
A resource bundle lookup returned a result from the root locale (not an error).
U_USING_FALLBACK_WARNING (int)
A resource bundle lookup returned a fallback result (not an error).
U_VARIABLE_RANGE_EXHAUSTED (int)
Too many stand-ins generated for the given variable range.
U_VARIABLE_RANGE_OVERLAP (int)
The variable range overlaps characters used in rules.
U_ZERO_ERROR (int)
No error, no warning.


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • intl
  • 例

例

目次

  • 基本的な使用法


基本的な使用法

各モジュールには、 手続き型とオブジェクト指向型の二種類の API が存在します。 それぞれの API について、対応するドキュメントで説明します。

注意:

入力文字列は、すべて UTF-8 でエンコードされていなければなりません。 出力文字列も、すべて UTF-8 となります。

例1 手続き型 API の使用例

<?php
$coll = collator_create('en_US');
$result = collator_compare($coll, "string#1", "string#2");
?>

例2 オブジェクト指向型 API の使用例

<?php
$coll = new Collator('en_US');
$al = $coll->getLocale(Locale::ACTUAL_LOCALE);
echo "実際のロケール: $al\n";

$formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
echo $formatter->format(1234567);
?>


Collator クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

はじめに

各ロケール固有の並び順を考慮した文字列の比較機能を提供します。

クラス概要

class Collator {
/* 定数 */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* メソッド */
public __construct(string $locale)
public asort(array &$array, int $flags = Collator::SORT_REGULAR): bool
public compare(string $string1, string $string2): int|false
public static create(string $locale): ?Collator
public getAttribute(int $attribute): int|false
public getErrorCode(): int|false
public getErrorMessage(): string|false
public getLocale(int $type): string|false
public getSortKey(string $string): string|false
public getStrength(): int
public setAttribute(int $attribute, int $value): bool
public setStrength(int $strength): bool
public sort(array &$array, int $flags = Collator::SORT_REGULAR): bool
public sortWithSortKeys(array &$array): bool
}

定義済み定数

Collator::FRENCH_COLLATION

文字列の後に続くさまざまなアクセントによる並べ替えを行います。 この属性は、フランス語などの一部のロケールでは自動的に On となります。 通常は、この属性を明示的に設定する必要はありません。 これを On にすると文字列の比較の効率が落ちますが、 ソートキーの長さは影響を受けません。 使用できる値は次のとおりです。

  • Collator::ON
  • Collator::OFF(デフォルト)
  • Collator::DEFAULT_VALUE

例1 FRENCH_COLLATION のルール

  • F=OFF cote < cote < cote < cote
  • F=ON cote < cote < cote < cote

Collator::ALTERNATE_HANDLING

Alternate 属性は、UCA における、いわゆる "可変文字 (variable characters)"、 つまり空白や句読点、記号の処理方法を制御するものです。 Alternate を NonIgnorable (N) に設定すると、これらの文字の違いを通常の文字の違いと同じように扱います。 Alternate を Shifted (S) に設定すると、これらの文字の違いの重要度を低くします。 Shifted は、Strength を Quaternary (第四段階) に指定して使用することが多くなります。 この場合、文字列の比較において空白や句読点そして記号の違いを考慮するのは それ以外の要素 (文字、アクセント、大文字小文字) がすべて一致する場合のみとなります。 Alternate を Shifted 以外にした場合は、 Strength が 3 のときと 4 のときの違いがなくなります。 詳細な情報やサンプルは、 » UCA の Variable_Weighting を参照ください。 Alternate の値を単なる On や Off にしていない理由は、将来的にさらに別の値が追加される可能性があるからです。 UCA のオプション Blanked を表すには、Strength を 3 そして Alternate を Shifted に設定します。 大半のロケールでは、デフォルトは NonIgnorable です。 Shifted を選択すると、記号類以外が等しい文字列がたくさんあるときに処理速度が低下します。 強度レベルを上げない限り、ソートキーの長さには影響を与えません。

使用できる値は次のとおりです。

  • Collator::NON_IGNORABLE(デフォルト)
  • Collator::SHIFTED
  • Collator::DEFAULT_VALUE

例2 ALTERNATE_HANDLING のルール

  • S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  • S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  • S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA

Collator::CASE_FIRST

Case_First 属性は、 文字列のその他の部分に違いがないときに 大文字と小文字のどちらが前にくるかを指定するものです。 使用できる値は、 Uppercase_First (U) と Lowercase_First (L)、そして標準の Default と Off です。 Off と Lowercase_First は、結果に関していえばほとんど違いはありません。 そのため、普通は Lowercase_First を使うことはありません。 Off あるいは Uppercase_First を使用することになります (X と L の違いを知りたい人は、Collation Customization を調べてください)。 L あるいは U のいずれを指定しても、文字列比較の処理速度には影響を与えません。 しかし、ソートキーの長さには影響を与えます。

使用できる値は次のとおりです。

  • Collator::OFF(デフォルト)
  • Collator::LOWER_FIRST
  • Collator::UPPER_FIRST
  • Collator:DEFAULT

例3 CASE_FIRST のルール

  • C=X or C=L "china" < "China" < "denmark" < "Denmark"
  • C=U "China" < "china" < "Denmark" < "denmark"

Collator::CASE_LEVEL

Case_Level 属性は、アクセントは無視するものの大文字小文字は区別したい場合に使用します。 そんな場合は、Strength を Primary にして Case_Level を On とします。 大半のロケールでは、この設定はデフォルトで Off となっています。 この属性を On にすると、文字列の比較のパフォーマンスやソートキーに多少影響を及ぼします。

使用できる値は次のとおりです。

  • Collator::OFF(デフォルト)
  • Collator::ON
  • Collator::DEFAULT_VALUE

例4 CASE_LEVEL のルール

  • S=1, E=X role = Role = role
  • S=1, E=O role = role < Role

Collator::NORMALIZATION_MODE

Normalization 設定は、比較時にテキストを正規化するか否かを指定します。 この設定を off (多くのロケールにおけるデフォルト設定です) にしても、 一般的な使用法ではほぼ正確に利用できます (詳細は UTN #5 を参照ください)。 問題となるのは、アクセント記号が正規の位置以外に登場する場合などです。 この設定を On にすると、 どんなテキストが与えられたとしても可能な限り結果を保証するようにします。 この属性を On にすると、 文字列比較のパフォーマンスに中程度の影響を及ぼします。 影響の程度は、正規化を要する並びの登場頻度に依存します。 ソートキーの長さには、目立った影響は及ぼしません。 入力テキストが NFD あるいは NFKD 形式で正規化されている場合は、 このオプションを有効にする必要はありません。

使用できる値は次のとおりです。

  • Collator::OFF(デフォルト)
  • Collator::ON
  • Collator::DEFAULT_VALUE

Collator::STRENGTH

ICU Collation Service は、多くの比較レベルをサポートしています ("レベル" という名前ですが、"強度" と呼ばれることもあります)。 これらのカテゴリを用いることで、ICU は、 各地域の規約にあわせた適切な文字列の並べ替えを正確に行えるようになります。 また、各段階を選択して採用することで、 テキスト内の文字列検索をさまざまな条件で行うことも可能になります。 詳細な情報は collator_set_strength() を参照ください。

使用できる値は次のとおりです。

  • Collator::PRIMARY
  • Collator::SECONDARY
  • Collator::TERTIARY(デフォルト)
  • Collator::QUATERNARY
  • Collator::IDENTICAL
  • Collator::DEFAULT_VALUE

Collator::HIRAGANA_QUATERNARY_MODE

JIS x 4061 との互換性を維持するには、さらなるレベルを追加して ひらがなとカタカナを区別する必要があります。 標準規格との互換性を要する場合は、この属性を On にして強度を Quaternary にしなければなりません。 これは、ソートキーの長さにも文字列比較のパフォーマンスにも影響を及ぼします。

使用できる値は次のとおりです。

  • Collator::OFF(デフォルト)
  • Collator::ON
  • Collator::DEFAULT_VALUE

Collator::NUMERIC_COLLATION

on にすると、数値形式の文字列の各桁を数値として使用した照合キーを生成します。 これにより、'100' のほうが '2' より「後」に並ぶようになります。

使用できる値は次のとおりです。

  • Collator::OFF(デフォルト)
  • Collator::ON
  • Collator::DEFAULT_VALUE

Collator::DEFAULT_VALUE
Collator::PRIMARY
Collator::SECONDARY
Collator::TERTIARY
Collator::DEFAULT_STRENGTH
Collator::QUATERNARY
Collator::IDENTICAL
Collator::OFF
Collator::ON
Collator::SHIFTED
Collator::NON_IGNORABLE
Collator::LOWER_FIRST
Collator::UPPER_FIRST
Collator::SORT_REGULAR

Collator::SORT_STRING

Collator::SORT_NUMERIC

目次

  • Collator::asort — インデックスの情報を保持しつつ配列を並べ替える
  • Collator::compare — ふたつの Unicode 文字列を比較する
  • Collator::__construct — collator を作成する
  • Collator::create — collator を作成する
  • Collator::getAttribute — 照合用の属性の値を取得する
  • Collator::getErrorCode — collator の直近のエラーコードを取得する
  • Collator::getErrorMessage — collator の直近のエラーコードのテキストを取得する
  • Collator::getLocale — collator のロケール名を取得する
  • Collator::getSortKey — 文字列のソート用のキーを取得する
  • Collator::getStrength — 現在の照合強度を取得する
  • Collator::setAttribute — 照合用の属性を設定する
  • Collator::setStrength — 照合強度を設定する
  • Collator::sort — 指定した collator で配列を並べ替える
  • Collator::sortWithSortKeys — 指定した collator とキーで配列を並べ替える


インデックスの情報を保持しつつ配列を並べ替える

  • ≪ Collator
  • Collator::compare ≫
  • PHP Manual
  • Collator
  • インデックスの情報を保持しつつ配列を並べ替える

Collator::asort

collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — インデックスの情報を保持しつつ配列を並べ替える

説明

オブジェクト指向型

public Collator::asort(array &$array, int $flags = Collator::SORT_REGULAR): bool

手続き型

collator_asort(Collator $object, array &$array, int $flags = Collator::SORT_REGULAR): bool

この関数は、インデックスと値の関係を保持したうえで配列を並べ替えます。 これを主に使用するのは、実際の並び順も重要となる連想配列です。 配列の要素には、現在のロケールの規則にしたがった並び順が適用されます。

PHP の標準関数 asort() と同等です。

パラメータ

object

Collator オブジェクト。

array

並べ替えたい文字列の配列。

flags

オプションの並べ替え方式。以下のいずれか。

  • Collator::SORT_REGULAR - 通常の比較 (型を変更しない)

  • Collator::SORT_NUMERIC - 数値としての比較

  • Collator::SORT_STRING - 文字列としての比較

デフォルトの flags の値は Collator::SORT_REGULAR です。 flags に無効な値が指定された場合も、このデフォルトを使用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_asort() の例

<?php
$coll = collator_create( 'en_US' );
$arr = array(
'a' => '100',
'b' => '50',
'c' => '7'
);
collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
var_export( $arr );

collator_asort( $coll, $arr, Collator::SORT_STRING );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  'c' => '7',
  'b' => '50',
  'a' => '100',
)array (
  'a' => '100',
  'b' => '50',
  'c' => '7',
)

参考

  • Collator の定数
  • collator_sort() - 指定した collator で配列を並べ替える
  • collator_sort_with_sort_keys() - 指定した collator とキーで配列を並べ替える


ふたつの Unicode 文字列を比較する

  • ≪ Collator::asort
  • Collator::__construct ≫
  • PHP Manual
  • Collator
  • ふたつの Unicode 文字列を比較する

Collator::compare

collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — ふたつの Unicode 文字列を比較する

説明

オブジェクト指向型

public Collator::compare(string $string1, string $string2): int|false

手続き型

collator_compare(Collator $object, string $string1, string $string2): int|false

ふたつの Unicode 文字列を、比較規則にもとづいて比較します。

パラメータ

object

Collator オブジェクト。

string1

最初の文字列。

string2

2 番目の文字列。

戻り値

比較結果を返します。

  • string1 が string2 より 大きい ときは 1

  • string1 と string2 が 等しい ときは 0

  • string1 が string2 より 小さい ときは -1

エラー時には false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 collator_compare() の例

<?php
$s1 = 'Hello';
$s2 = 'hello';

$coll = collator_create( 'en_US' );
$res = collator_compare( $coll, $s1, $s2 );

if ($res === false) {
echo collator_get_error_message( $coll );
} else if( $res > 0 ) {
echo "s1 is greater than s2\n";
} else if( $res < 0 ) {
echo "s1 is less than s2\n";
} else {
echo "s1 is equal to s2\n";
}
?>

上の例の出力は以下となります。

s1 is greater than s2

例2 ダイアクリティカルマークや、大文字小文字の区別を無視して比較する

<?php
$c = new Collator( 'en' );
$c->setStrength( Collator::PRIMARY );
if ( $c->compare( 'Sean', 'Sean' ) == 0 )
{
echo "The same\n";
}

上の例の出力は以下となります。

The same

この例は、collator に基本的な文字のみを考慮するように指示します。 Collator->setStrength() のドキュメントは、照合強度の違いについて説明しています。

参考

  • collator_sort() - 指定した collator で配列を並べ替える


collator を作成する

  • ≪ Collator::compare
  • Collator::create ≫
  • PHP Manual
  • Collator
  • collator を作成する

Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — collator を作成する

説明

public Collator::__construct(string $locale)

新しい Collator のインスタンスを作成します。

パラメータ

locale

照合規則を使用するロケール。特殊な場合として、 空文字列を渡した場合はデフォルトのロケールの照合規則を使用します。 "root" を渡した場合は、 » UCA の規則を使用します。

locale 属性は、 各国・各地域のユーザーの期待通りに並べ替えやマッチングを行うために もっとも重要な属性です。デフォルトの » UCA の並び順で正しく ("正しく" とは、その言語を使用する人の期待通りにということです) 処理できるのは、オランダ語やポルトガル語などの一部の言語だけです。 それ以外の場合は、UCA にロケールを指定して その言語に応じた適切な照合を行えるようにする必要があります。 従って、各ロケールにあわせて正しく設定した collator を使用する必要があります。 ロケールを選択すると、その他の属性の値も適切な物に自動設定されます。 従って、その他の属性については明示的に設定する必要はほとんどありません。 選択したロケールによっては、文字列比較のパフォーマンスやソートキーの長さに違いが出ることがあります。

エラー / 例外

エラー時には "空の" オブジェクトを返します。何が起こったのかを知るには intl_get_error_code() や intl_get_error_message() を使用します。

例

例1 Collator::__construct() の例

<?php
$coll = new Collator('en_CA');
?>

参考

  • Collator::create() - collator を作成する
  • collator_create() - collator を作成する


collator を作成する

  • ≪ Collator::__construct
  • Collator::getAttribute ≫
  • PHP Manual
  • Collator
  • collator を作成する

Collator::create

collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — collator を作成する

説明

オブジェクト指向型

public static Collator::create(string $locale): ?Collator

手続き型

collator_create(string $locale): ?Collator

すでに指定しているオプションを用いて文字列を比較します。

パラメータ

locale

照合規則を使用するロケール。特殊な場合として、 空文字列を渡した場合はデフォルトのロケールの照合規則を使用します。 "root" を渡した場合は » UCA の規則を使用します。

戻り値

新しい Collator オブジェクトのインスタンス、 あるいはエラー時に null を返します。

例

例1 collator_create() の例

<?php
$coll = collator_create( 'en_US' );

if( !isset( $coll ) ) {
printf( "Collator creation failed: %s\n", intl_get_error_message() );
exit( 1 );
}
?>

参考

  • Collator::__construct() - collator を作成する


照合用の属性の値を取得する

  • ≪ Collator::create
  • Collator::getErrorCode ≫
  • PHP Manual
  • Collator
  • 照合用の属性の値を取得する

Collator::getAttribute

collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — 照合用の属性の値を取得する

説明

オブジェクト指向型

public Collator::getAttribute(int $attribute): int|false

手続き型

collator_get_attribute(Collator $object, int $attribute): int|false

collator の属性の値を取得します。

パラメータ

object

Collator オブジェクト。

attribute

値を取得したい属性。

戻り値

属性の値を返します。 失敗した場合に false を返します

例

例1 collator_get_attribute() の例

<?php
$coll = collator_create( 'en_CA' );
$val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
if( $val === false )
{
// エラー処理
}
?>

参考

  • Collator の定数
  • collator_set_attribute() - 照合用の属性を設定する
  • collator_get_strength() - 現在の照合強度を取得する


collator の直近のエラーコードを取得する

  • ≪ Collator::getAttribute
  • Collator::getErrorMessage ≫
  • PHP Manual
  • Collator
  • collator の直近のエラーコードを取得する

Collator::getErrorCode

collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — collator の直近のエラーコードを取得する

説明

オブジェクト指向型

public Collator::getErrorCode(): int|false

手続き型

collator_get_error_code(Collator $object): int|false

パラメータ

object

Collator オブジェクト。

戻り値

直近の Collator API 関数コールが返したエラーコードを返します。 失敗した場合に false を返します

例

例1 collator_get_error_code() の例

<?php
$coll = collator_create( 'en_US' );
if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
handle_error( collator_get_error_code() );
?>

参考

  • collator_get_error_message() - collator の直近のエラーコードのテキストを取得する


collator の直近のエラーコードのテキストを取得する

  • ≪ Collator::getErrorCode
  • Collator::getLocale ≫
  • PHP Manual
  • Collator
  • collator の直近のエラーコードのテキストを取得する

Collator::getErrorMessage

collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — collator の直近のエラーコードのテキストを取得する

説明

オブジェクト指向型

public Collator::getErrorMessage(): string|false

手続き型

collator_get_error_message(Collator $object): string|false

直近のエラーのメッセージを取得します。

パラメータ

object

Collator オブジェクト。

戻り値

直近の Collator API 関数コールで発生したエラーの説明を返します。 失敗した場合に false を返します

例

例1 collator_get_error_message() の例

<?php
$coll = collator_create( 'lt' );
if( collator_compare( $coll, 'y', 'k' ) === false ) {
echo collator_get_error_message( $coll );
}
?>

参考

  • collator_get_error_code() - collator の直近のエラーコードを取得する


collator のロケール名を取得する

  • ≪ Collator::getErrorMessage
  • Collator::getSortKey ≫
  • PHP Manual
  • Collator
  • collator のロケール名を取得する

Collator::getLocale

collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — collator のロケール名を取得する

説明

オブジェクト指向型

public Collator::getLocale(int $type): string|false

手続き型

collator_get_locale(Collator $object, int $type): string|false

collector のロケール名を取得します。

パラメータ

object

Collator オブジェクト。

type

妥当なロケールか実際のロケール (それぞれ Locale::VALID_LOCALE および Locale::ACTUAL_LOCALE)。

戻り値

照合データの実際のロケール名を返します。ルールベースの collator のインスタンスの場合やエラーが発生した場合は false を返します。

例

例1 collator_get_locale() の例

<?php
$coll = collator_create( 'en_US_California' );
$res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
$res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
printf( "Valid locale name: %s\nActual locale name: %s\n",
$res_val, $res_act );
?>

上の例の出力は以下となります。

Requested locale name: en_US_California
Valid locale name: en_US
Actual locale name: en

参考

  • collator_create() - collator を作成する


文字列のソート用のキーを取得する

  • ≪ Collator::getLocale
  • Collator::getStrength ≫
  • PHP Manual
  • Collator
  • 文字列のソート用のキーを取得する

Collator::getSortKey

collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — 文字列のソート用のキーを取得する

説明

オブジェクト指向型

public Collator::getSortKey(string $string): string|false

手続き型

collator_get_sort_key(Collator $object, string $string): string|false

文字列用の照合キーを返します。 照合キーは文字列のかわりに直接比較することができますが、 これは実装依存の動きであり、ICUライブラリのバージョンによって変わる可能性があります。 一般的に、ソート用のキーはデータベース内部か、関数呼び出しコストがとても高い状況でのみ役に立ちます。

パラメータ

object

Collator オブジェクト。

string

キーの生成元となる文字列。

戻り値

文字列の照合キーを返します。失敗した場合に false を返します

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 collator_get_sort_key() の例

<?php
$s1 = 'Hello';

$coll = collator_create('en_US');
$res = collator_get_sort_key($coll, $s1);

echo bin2hex($res);
?>

上の例の出力は、 たとえば以下のようになります。

3832404046010901dc08

参考

  • collator_sort() - 指定した collator で配列を並べ替える
  • collator_sort_with_sort_keys() - 指定した collator とキーで配列を並べ替える


現在の照合強度を取得する

  • ≪ Collator::getSortKey
  • Collator::setAttribute ≫
  • PHP Manual
  • Collator
  • 現在の照合強度を取得する

Collator::getStrength

collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — 現在の照合強度を取得する

説明

オブジェクト指向型

public Collator::getStrength(): int

手続き型

collator_get_strength(Collator $object): int

パラメータ

object

Collator オブジェクト。

戻り値

現在の照合強度を返します。 失敗した場合に false を返します

例

例1 collator_get_strength() の例

<?php
$coll = collator_create( 'en_US' );
$strength = collator_get_strength( $coll );
?>

参考

  • Collator の定数
  • collator_set_strength() - 照合強度を設定する
  • collator_get_attribute() - 照合用の属性の値を取得する


照合用の属性を設定する

  • ≪ Collator::getStrength
  • Collator::setStrength ≫
  • PHP Manual
  • Collator
  • 照合用の属性を設定する

Collator::setAttribute

collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — 照合用の属性を設定する

説明

オブジェクト指向型

public Collator::setAttribute(int $attribute, int $value): bool

手続き型

collator_set_attribute(Collator $object, int $attribute, int $value): bool

パラメータ

object

Collator オブジェクト。

attribute

属性。

value

属性の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_set_attribute() の例

<?php
$coll = collator_create( 'en_CA' );
$val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
if ($val === false) {
// エラー処理
} elseif ($val === Collator::ON) {
// 何かすてきなこと
}
?>

参考

  • Collator の定数
  • collator_get_attribute() - 照合用の属性の値を取得する
  • collator_set_strength() - 照合強度を設定する


照合強度を設定する

  • ≪ Collator::setAttribute
  • Collator::sort ≫
  • PHP Manual
  • Collator
  • 照合強度を設定する

Collator::setStrength

collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — 照合強度を設定する

説明

オブジェクト指向型

public Collator::setStrength(int $strength): bool

手続き型

collator_set_strength(Collator $object, int $strength): bool

» ICU Collation Service は、多くの比較レベルをサポートしています ("レベル" という名前ですが、"強度" と呼ばれることもあります)。 これらのカテゴリを用いることで、ICU は、 各地域の規約にあわせた適切な文字列の並べ替えを正確に行えるようになります。 また、各段階を選択して採用することで、 テキスト内の文字列検索をさまざまな条件で行うことも可能になります。

  1. 第一段階 (Primary Level): 一般に、これは元となる文字自体の違いを表すものとして使用します (たとえば "a" < "b")。これが、いちばん強い違いとなります。 たとえば、辞書などではこれを用いてセクション分けしています。 これは、 level 1 の強度 (level1 strength) ともいいます。

  2. 第二段階 (Secondary Level): 文字のアクセント記号を、第二段階の違いとします (たとえば "as" < "as" < "at")。 言語によっては、その他の文字の違いも第二段階の違いとみなすこともあります。 文字列のどこかで第一段階の違いがある場合、第二段階の違いは無視します。 これは、 level 2 の強度 (level2 strength) ともいいます。

    注意:

    注意: 言語によっては (たとえばデンマーク語)、 アクセント記号は元の文字とは別の文字とみなすものもあります。 しかし、たいていの言語では、 アクセントなしの文字とアクセントつきの文字の違いは第二段階とみなします。

  3. 第三段階 (Tertiary Level): 大文字と小文字の違いを区別するのが第二段階の違いです (たとえば "ao" < "Ao" < "ao")。 さらに、ある文字とその派生形の違い(たとえば "a" and "??") も第三段階と判断します。さらに、カナの大文字と小文字の違い (訳注: たとえば "や" と "ゃ") もこの段階になります。 文字列のどこかで第一段階や第二段階の違いがある場合、 第三段階の違いは無視します。 これは、level 3 の強度 (level3 strength) ともいいます。

  4. 第四段階 (Quaternary Level): レベル 1 から 3 までで句読点を無視する場合 ("句読点の無視" を参照)、 追加の段階を使用して句読点つきの単語となしの単語を区別します (たとえば "ab" < "a-b" < "aB")。 どこかに第一段階や第二段階、第三段階の違いがある場合、 第四段階の違いは無視します。 これは、 level 4 の強度 (level4 strength) ともいいます。 第四段階を使用するのは、句読点を無視する必要がある場合や 日本語のテキスト ("ひらがなの処理" を参照) を処理する場合のみです。

  5. 一致段階 (Identical Level): それ以外のすべてのレベルで等しかった場合に、最後の手段として一致段階を用います。 この段階で比較するのは、NFD 形式の文字列の Unicode コードポイントです。 レベル 1 から 4 までで違いがない場合にのみ比較します。 たとえば、ヘブライ語の朗誦記号 (cantillation mark) は、 この段階でしか識別できません。 この段階は慎重に使うようにしましょう。 ふたつの文字列でコードポイントの値のみが違うなどということは、 めったにないことだからです。 この段階を使用すると、(ソートキーの強度が上がるのと同時に) インクリメンタルな比較やソートキーの生成のパフォーマンスが劇的に低下します。 これは、level 5 の強度 (level5 strength) ともいいます。

たとえば、「アクセントを無視」したり「アクセントと大文字小文字の区別を無視」 したりしてテキストの検索を行いたいこともあります。 ほぼすべての文字は第三段階までで識別できるので、 大半のロケールではデフォルトの指定は第三段階となっています。 しかし、場合によっては第四段階の強度を使用することになります。 これを用いると、空白や句読点や記号など、 他の強度では無視されるような違いも識別するようになります。 文字の識別を非常に厳密に行うには、一致段階の強度を使用します (たとえばこれを使用すると、Mathematical Bold Small A と Mathematical Italic Small A が別の文字とみなされます)。 しかし、第三段階を超える強度を使用すると、 ソートキーが非常に長くなってしまい、 また同じ文字列に対する比較処理も非常に遅くなってしまいます。

パラメータ

object

Collator オブジェクト。

strength

設定する強度。

以下のいずれかです。

  • Collator::PRIMARY

  • Collator::SECONDARY

  • Collator::TERTIARY

  • Collator::QUATERNARY

  • Collator::IDENTICAL

  • Collator::DEFAULT_STRENGTH

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_set_strength() の例

<?php
$arr = array( 'ao', 'Ao', 'ao' );
$coll = collator_create( 'en_US' );

// デフォルトの強度で配列を並べ替えます
collator_sort( $coll, $arr );
var_export( $arr );

// 第一段階の強度で配列を並べ替えます
collator_set_strength( $coll, Collator::PRIMARY );
collator_sort( $coll, $arr );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  0 => 'ao',
  1 => 'Ao',
  2 => 'ao',
)
array (
  0 => 'ao',
  1 => 'Ao',
  2 => 'ao',
)

参考

  • Collator の定数
  • collator_get_strength() - 現在の照合強度を取得する


指定した collator で配列を並べ替える

  • ≪ Collator::setStrength
  • Collator::sortWithSortKeys ≫
  • PHP Manual
  • Collator
  • 指定した collator で配列を並べ替える

Collator::sort

collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — 指定した collator で配列を並べ替える

説明

オブジェクト指向型

public Collator::sort(array &$array, int $flags = Collator::SORT_REGULAR): bool

手続き型

collator_sort(Collator $object, array &$array, int $flags = Collator::SORT_REGULAR): bool

この関数は、現在のロケールの規則にもとづいて配列を並べ替えます。

PHP の標準関数 sort() と同等です。

パラメータ

object

Collator オブジェクト。

array

並べ替えたい文字列の配列。

flags

オプションの並べ替え方式。以下のいずれか。

  • Collator::SORT_REGULAR - 通常の比較 (型を変更しない)

  • Collator::SORT_NUMERIC - 数値としての比較

  • Collator::SORT_STRING - 文字列としての比較

デフォルトの並べ替え方式は Collator::SORT_REGULAR です。flags に無効な値を指定した場合もこの方式を使います。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_sort() の例

<?php
$coll = collator_create( 'en_US' );
$arr = array( 'at', 'as', 'as' );

var_export( $arr );
collator_sort( $coll, $arr );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  0 => 'at',
  1 => 'as',
  2 => 'as',
)array (
  0 => 'as',
  1 => 'as',
  2 => 'at',
)

参考

  • Collator の定数
  • collator_asort() - インデックスの情報を保持しつつ配列を並べ替える
  • collator_sort_with_sort_keys() - 指定した collator とキーで配列を並べ替える


指定した collator とキーで配列を並べ替える

  • ≪ Collator::sort
  • NumberFormatter ≫
  • PHP Manual
  • Collator
  • 指定した collator とキーで配列を並べ替える

Collator::sortWithSortKeys

collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — 指定した collator とキーで配列を並べ替える

説明

オブジェクト指向型

public Collator::sortWithSortKeys(array &$array): bool

手続き型

collator_sort_with_sort_keys(Collator $object, array &$array): bool

collator_sort() と似ていますが、 ucol_getSortKey() が作成した ICU ソートキーを用いることで 大きな配列をより高速に処理できます。

パラメータ

object

Collator オブジェクト。

array

並べ替えたい文字列の配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 collator_sort_with_sort_keys() の例

<?php
$arr = array( 'Kopfe', 'Kypper', 'Kopfe' );
$coll = collator_create( 'sv' );

collator_sort_with_sort_keys( $coll, $arr );
var_export( $arr );
?>

上の例の出力は以下となります。

array (
  0 => 'Kopfe',
  1 => 'Kypper',
  2 => 'Kopfe',
)

参考

  • Collator の定数
  • collator_sort() - 指定した collator で配列を並べ替える
  • collator_asort() - インデックスの情報を保持しつつ配列を並べ替える


NumberFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

はじめに

プログラムで数値を保存したり操作したりする際には、 ロケールに依存しないバイナリ表現を使用します。 数値を表示するときに、ロケールにあわせた文字列形式に変換します。 たとえば 12345.67 という数値の表記はアメリカでは "12,345.67"、 フランスでは "12 345,67"、そしてドイツでは "12.345,67" となります。

NumberFormatter クラスのメソッドを実行すると、 数値や通貨、パーセンテージなどの値をロケールに応じた形式にフォーマットすることができます。 NumberFormatter はロケールを考慮した処理を行うので、 ロケールごとに別の NumberFormatter を用意する必要があります。 NumberFormatter のメソッドは、浮動小数点数値のような数値を ロケールにあわせた文字列に変換します。

通貨の場合は、通貨用の書式を使用してフォーマッタを作成します。 これは、ロケールにあわせて数値を適切な書式にして通貨記号をつけた文字列を返します。 もちろん、NumberFormatter クラスは為替レートの変換などは考慮しません。 指定した通貨にかかわらず、出力される数値は同じものとなります。 つまり、ロケールによって同じ数値が違う額を表すことになるということです。 9988776.65 という数値を指定したときの結果は次のようになります。

  • 9 988 776,65 ? (フランス)
  • 9.988.776,65 ? (ドイツ)
  • $9,988,776.65 (アメリカ)

パーセンテージをフォーマットするには、 パーセンテージ用の書式を指定したフォーマッタを作成します。 これを使用すると、たとえば 0.75 のような小数が 75% と表示されるようになります。

spelled-out numbers のような複雑な書式を設定する場合は、 ルールベースの数値フォーマッタを使用します。

クラス概要

class NumberFormatter {
/* 定数 */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ACCOUNTING;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* メソッド */
public __construct(string $locale, int $style, ?string $pattern = null)
public static create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter
public format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false
public formatCurrency(float $amount, string $currency): string|false
public getAttribute(int $attribute): int|float|false
public getErrorCode(): int
public getErrorMessage(): string
public getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false
public getPattern(): string|false
public getSymbol(int $symbol): string|false
public getTextAttribute(int $attribute): string|false
public parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false
public parseCurrency(string $string, string &$currency, int &$offset = null): float|false
public setAttribute(int $attribute, int|float $value): bool
public setPattern(string $pattern): bool
public setSymbol(int $symbol, string $value): bool
public setTextAttribute(int $attribute, string $value): bool
}

定義済み定数

フォーマッタのタイプ

これらのスタイルは numfmt_create() で使用するもので、フォーマッタの形式を定義します。

NumberFormatter::PATTERN_DECIMAL
パターンで定義する十進形式
NumberFormatter::DECIMAL
十進形式
NumberFormatter::CURRENCY
通貨形式
NumberFormatter::PERCENT
パーセント形式
NumberFormatter::SCIENTIFIC
科学形式
NumberFormatter::SPELLOUT
ルールベースの省略しない形式
NumberFormatter::ORDINAL
ルールベースの序数形式
NumberFormatter::DURATION
ルールベースの連続形式
NumberFormatter::PATTERN_RULEBASED
パターンで定義するルールベースの形式
NumberFormatter::CURRENCY_ACCOUNTING
会計処理のための通貨フォーマット。例: 負の通貨量の場合、-$3.00 ではなく、($3.00) になります。 PHP 7.4.1 と ICU 53 から利用可能です。
NumberFormatter::DEFAULT_STYLE
そのロケールのデフォルトの形式
NumberFormatter::IGNORE
PATTERN_DECIMAL のエイリアス

数値フォーマットの指定子

これらの定数は、数値のパースやフォーマットの方法を定義します。 numfmt_format() や numfmt_parse() の引数として使用します。

NumberFormatter::TYPE_DEFAULT
変数の型に由来する型
NumberFormatter::TYPE_INT32
32 ビット整数値としてフォーマット/パースする
NumberFormatter::TYPE_INT64
64 ビット整数値としてフォーマット/パースする
NumberFormatter::TYPE_DOUBLE
浮動小数点数値としてフォーマット/パースする
NumberFormatter::TYPE_CURRENCY
通貨値としてフォーマット/パースする。PHP 8.3.0 以降は非推奨

数値フォーマットの属性

numfmt_get_attribute() および numfmt_set_attribute() で使用する数値フォーマット属性です。

NumberFormatter::PARSE_INT_ONLY
整数値のみをパースする
NumberFormatter::GROUPING_USED
グループ区切り文字を使用する
NumberFormatter::DECIMAL_ALWAYS_SHOWN
常に小数点を表示する
NumberFormatter::MAX_INTEGER_DIGITS
整数部の最大桁数
NumberFormatter::MIN_INTEGER_DIGITS
整数部の最小桁数
NumberFormatter::INTEGER_DIGITS
整数部の桁数
NumberFormatter::MAX_FRACTION_DIGITS
小数部の最大桁数
NumberFormatter::MIN_FRACTION_DIGITS
小数部の最小桁数
NumberFormatter::FRACTION_DIGITS
小数部の桁数
NumberFormatter::MULTIPLIER
乗数
NumberFormatter::GROUPING_SIZE
グループ化のサイズ
NumberFormatter::ROUNDING_MODE
丸めモード
NumberFormatter::ROUNDING_INCREMENT
切り上げ
NumberFormatter::FORMAT_WIDTH
format() の出力のパディング幅
NumberFormatter::PADDING_POSITION
パディングを行う位置。 使用できる引数の値についてはパディング位置に関する定数を参照ください。
NumberFormatter::SECONDARY_GROUPING_SIZE
第二段階のグループ化のサイズ
NumberFormatter::SIGNIFICANT_DIGITS_USED
有効数字を使用する
NumberFormatter::MIN_SIGNIFICANT_DIGITS
有効数字の最小桁数
NumberFormatter::MAX_SIGNIFICANT_DIGITS
有効数字の最大桁数
NumberFormatter::LENIENT_PARSE
ルールベースのフォーマットで使用する Lenient パースモード

数値フォーマットのテキスト属性

numfmt_get_text_attribute() および numfmt_set_text_attribute() で使用する数値フォーマットテキスト属性です。

NumberFormatter::POSITIVE_PREFIX
正の数のプレフィックス
NumberFormatter::POSITIVE_SUFFIX
正の数のサフィックス
NumberFormatter::NEGATIVE_PREFIX
負の数のプレフィックス
NumberFormatter::NEGATIVE_SUFFIX
負の数のサフィックス
NumberFormatter::PADDING_CHARACTER
余白を埋める際に使用する文字
NumberFormatter::CURRENCY_CODE
ISO 通貨コード
NumberFormatter::DEFAULT_RULESET
デフォルトのルールセット。 ルールベースのフォーマッタでのみ有効です。
NumberFormatter::PUBLIC_RULESETS
パブリックルールセット。 これは、ルールベースのフォーマッタでのみ有効です。 これは読み込み専用の属性です。 パブリックルールセットは文字列として返され、 個々のルールセットは ';' (セミコロン) で区切られています。

シンボルフォーマットの指定子

numfmt_get_symbol() および numfmt_set_symbol() で使用する数値フォーマット記号です。

NumberFormatter::DECIMAL_SEPARATOR_SYMBOL
小数点
NumberFormatter::GROUPING_SEPARATOR_SYMBOL
グループ区切り文字
NumberFormatter::PATTERN_SEPARATOR_SYMBOL
パターン区切り文字
NumberFormatter::PERCENT_SYMBOL
パーセント記号
NumberFormatter::ZERO_DIGIT_SYMBOL
ゼロ
NumberFormatter::DIGIT_SYMBOL
パターン内で数字を表す文字
NumberFormatter::MINUS_SIGN_SYMBOL
マイナス記号
NumberFormatter::PLUS_SIGN_SYMBOL
プラス記号
NumberFormatter::CURRENCY_SYMBOL
通貨記号
NumberFormatter::INTL_CURRENCY_SYMBOL
国際通貨記号
NumberFormatter::MONETARY_SEPARATOR_SYMBOL
金額の区切り文字
NumberFormatter::EXPONENTIAL_SYMBOL
指数記号
NumberFormatter::PERMILL_SYMBOL
パーミル記号
NumberFormatter::PAD_ESCAPE_SYMBOL
パディング文字のエスケープ記号
NumberFormatter::INFINITY_SYMBOL
無限大記号
NumberFormatter::NAN_SYMBOL
非数値記号
NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL
有効数字記号
NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL
金額のグループ区切り文字

丸めモード

numfmt_get_attribute() および
numfmt_set_attribute() で、
NumberFormatter::ROUNDING_MODE
属性に使用する丸めモードの値です。

NumberFormatter::ROUND_CEILING
正の無限大に向けて丸めるモード
NumberFormatter::ROUND_DOWN
ゼロに向けて丸めるモード
NumberFormatter::ROUND_FLOOR
負の無限大に向けて丸めるモード
NumberFormatter::ROUND_HALFDOWN
"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロに向けて丸めます。
NumberFormatter::ROUND_HALFEVEN
"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合は偶数になるように丸めます。
NumberFormatter::ROUND_HALFUP
"一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロから離れる方向に丸めます。
NumberFormatter::ROUND_UP
ゼロから離れる方向に丸めるモード

パディングの指定子

numfmt_get_attribute() および
numfmt_set_attribute() で、
NumberFormatter::PADDING_POSITION
属性に使用するパディング位置の値です。

NumberFormatter::PAD_AFTER_PREFIX
プレフィックスの後にパディング文字を入れる
NumberFormatter::PAD_AFTER_SUFFIX
サフィックスの後にパディング文字を入れる
NumberFormatter::PAD_BEFORE_PREFIX
プレフィックスの前にパディング文字を入れる
NumberFormatter::PAD_BEFORE_SUFFIX
サフィックスの前にパディング文字を入れる

参考

  • » ICU formatting documentation
  • » ICU number formatters
  • » ICU decimal formatters
  • » ICU rule-based number formatters

目次

  • NumberFormatter::create — 数値フォーマッタを作成する
  • NumberFormatter::format — 数値をフォーマットする
  • NumberFormatter::formatCurrency — 通貨の値をフォーマットする
  • NumberFormatter::getAttribute — 属性を取得する
  • NumberFormatter::getErrorCode — フォーマッタの直近のエラーコードを取得する
  • NumberFormatter::getErrorMessage — フォーマッタの直近のエラーメッセージを取得する
  • NumberFormatter::getLocale — フォーマッタのロケールを取得する
  • NumberFormatter::getPattern — フォーマッタのパターンを取得する
  • NumberFormatter::getSymbol — 記号を取得する
  • NumberFormatter::getTextAttribute — テキストの属性を取得する
  • NumberFormatter::parse — 数値をパースする
  • NumberFormatter::parseCurrency — 通貨をパースする
  • NumberFormatter::setAttribute — 属性を設定する
  • NumberFormatter::setPattern — フォーマッタのパターンを設定する
  • NumberFormatter::setSymbol — 記号の値を設定する
  • NumberFormatter::setTextAttribute — テキスト属性を設定する


数値フォーマッタを作成する

  • ≪ NumberFormatter
  • NumberFormatter::format ≫
  • PHP Manual
  • NumberFormatter
  • 数値フォーマッタを作成する

NumberFormatter::create

numfmt_create

NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — 数値フォーマッタを作成する

説明

オブジェクト指向型 (メソッド)

public static NumberFormatter::create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter

手続き型

numfmt_create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter

オブジェクト指向型 (コンストラクタ):

public NumberFormatter::__construct(string $locale, int $style, ?string $pattern = null)

数値フォーマッタを作成します。

パラメータ

locale

数値フォーマットするロケール (ロケール名。たとえば en_CA)。

style

フォーマットの形式。 フォーマット形式 定数のいずれか。 NumberFormatter::PATTERN_DECIMAL あるいは NumberFormatter::PATTERN_RULEBASED を指定した場合は指定したパターンの数値フォーマットをオープンします。 これは、それぞれ » ICU DecimalFormat ドキュメント あるいは » ICU RuleBasedNumberFormat ドキュメント で述べられている構文を満たす必要があります。

pattern

選択した形式がパターンを要求するものである場合のパターン文字列。

戻り値

NumberFormatter オブジェクト、 あるいはエラー時に null を返します。

変更履歴

バージョン | 説明
8.0.0 | pattern は、nullable になりました。

例

例1 numfmt_create() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
$fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
echo numfmt_format($fmt, 1142)."\n";
?>

例2 NumberFormatter::create() の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo $fmt->format(1234567.891234567890000)."\n";
$fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
echo $fmt->format(1142)."\n";
?>

上の例の出力は以下となります。

1.234.567,891
millicentoquarantadue

参考

  • numfmt_format() - 数値をフォーマットする
  • numfmt_parse() - 数値をパースする


数値をフォーマットする

  • ≪ NumberFormatter::create
  • NumberFormatter::formatCurrency ≫
  • PHP Manual
  • NumberFormatter
  • 数値をフォーマットする

NumberFormatter::format

numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — 数値をフォーマットする

説明

オブジェクト指向型

public NumberFormatter::format(int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false

手続き型

numfmt_format(NumberFormatter $formatter, int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false

数値をフォーマット規則にしたがってフォーマットします。

パラメータ

formatter

NumberFormatter オブジェクト。

num

フォーマットする値。int あるいは float で指定します。その他の型は数値に変換されます。

type

使用する フォーマット形式。 NumberFormatter::TYPE_CURRENCY はサポートされていないので注意して下さい。 NumberFormatter::TYPE_CURRENCY を使いたい場合、 代わりに NumberFormatter::formatCurrency() を使いましょう。

戻り値

フォーマットした値を文字列で返します。 エラー時には false を返します。

例

例1 numfmt_format() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_format($fmt))) {
report_error("Formatter error");
}
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
report_error("Formatter error");
}
?>

上の例の出力は以下となります。

1.234.567,891

注意

注意:

このメソッドで実現可能なフォーマットでは、 ICU ライブラリが持つ機能をすべて使えません。 たとえば、短い通貨記号を使ってフォーマットする場合です。

ICU ライブラリが持つ機能をすべて使うには、 msgfmt_format_message() を使います。

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_format_currency() - 通貨の値をフォーマットする
  • numfmt_parse() - 数値をパースする
  • msgfmt_format_message() - 手早くメッセージをフォーマットする


通貨の値をフォーマットする

  • ≪ NumberFormatter::format
  • NumberFormatter::getAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 通貨の値をフォーマットする

NumberFormatter::formatCurrency

numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — 通貨の値をフォーマットする

説明

オブジェクト指向型

public NumberFormatter::formatCurrency(float $amount, string $currency): string|false

手続き型

numfmt_format_currency(NumberFormatter $formatter, float $amount, string $currency): string|false

通貨の値をフォーマット規則にしたがってフォーマットします。

パラメータ

formatter

NumberFormatter オブジェクト。

amount

通貨の値。

currency

使用する通貨を表す、3 文字の ISO 4217 通貨コード。

戻り値

通貨の値をフォーマットした文字列を返します。 失敗した場合に false を返します

例

例1 numfmt_format_currency() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
$fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
$fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
?>

上の例の出力は以下となります。

1.234.567,89 ?
1.234.567,89 RUR
1 234 567,89?
1 234 567,89р.

注意

注意:

このメソッドで実現可能なフォーマットでは、 ICU ライブラリが持つ機能をすべて使えません。 たとえば、短い通貨記号を使ってフォーマットする場合です。

ICU ライブラリが持つ機能をすべて使うには、 msgfmt_format_message() を使います。

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_format() - 数値をフォーマットする
  • numfmt_parse_currency() - 通貨をパースする
  • msgfmt_format_message() - 手早くメッセージをフォーマットする


属性を取得する

  • ≪ NumberFormatter::formatCurrency
  • NumberFormatter::getErrorCode ≫
  • PHP Manual
  • NumberFormatter
  • 属性を取得する

NumberFormatter::getAttribute

numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — 属性を取得する

説明

オブジェクト指向型

public NumberFormatter::getAttribute(int $attribute): int|float|false

手続き型

numfmt_get_attribute(NumberFormatter $formatter, int $attribute): int|float|false

フォーマッタの数値属性を取得します。 数値属性の例としては、フォーマッタが作成する整数部の桁数などがあります。

パラメータ

formatter

NumberFormatter オブジェクト。

attribute

属性指定子。 数値属性 定数のいずれか。

戻り値

成功した場合に属性の値、エラー時に false を返します。

例

例1 numfmt_get_attribute() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Digits: 3
1.234.567,891
Digits: 2
1.234.567,89

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_get_text_attribute() - テキストの属性を取得する
  • numfmt_set_attribute() - 属性を設定する


フォーマッタの直近のエラーコードを取得する

  • ≪ NumberFormatter::getAttribute
  • NumberFormatter::getErrorMessage ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタの直近のエラーコードを取得する

NumberFormatter::getErrorCode

numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — フォーマッタの直近のエラーコードを取得する

説明

オブジェクト指向型

public NumberFormatter::getErrorCode(): int

手続き型

numfmt_get_error_code(NumberFormatter $formatter): int

フォーマッタが直近に実行した関数のエラーコードを取得します。

パラメータ

formatter

NumberFormatter オブジェクト。

戻り値

直近の関数コールのエラーコードを返します。

例

例1 numfmt_get_error_code() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
if(intl_is_failure(numfmt_get_error_code($fmt))) {
report_error("Formatter error");
}
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
if(intl_is_failure($fmt->getErrorCode())) {
report_error("Formatter error");
}
?>

参考

  • numfmt_get_error_message() - フォーマッタの直近のエラーメッセージを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


フォーマッタの直近のエラーメッセージを取得する

  • ≪ NumberFormatter::getErrorCode
  • NumberFormatter::getLocale ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタの直近のエラーメッセージを取得する

NumberFormatter::getErrorMessage

numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — フォーマッタの直近のエラーメッセージを取得する

説明

オブジェクト指向型

public NumberFormatter::getErrorMessage(): string

手続き型

numfmt_get_error_message(NumberFormatter $formatter): string

フォーマッタが直近に実行した関数のエラーメッセージを取得します。

パラメータ

formatter

NumberFormatter オブジェクト。

戻り値

直近の関数コールのエラーメッセージを返します。

例

例1 numfmt_get_error_message() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$data = numfmt_format($fmt, 1234567.891234567890000);
var_dump(numfmt_get_error_message($fmt));
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$fmt->format(1234567.891234567890000);
var_dump(numfmt_get_error_message($fmt));
?>

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


フォーマッタのロケールを取得する

  • ≪ NumberFormatter::getErrorMessage
  • NumberFormatter::getPattern ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタのロケールを取得する

NumberFormatter::getLocale

numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — フォーマッタのロケールを取得する

説明

オブジェクト指向型

public NumberFormatter::getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false

手続き型

numfmt_get_locale(NumberFormatter $formatter, int $type = ULOC_ACTUAL_LOCALE): string|false

フォーマッタのロケール名を取得します。

パラメータ

formatter

NumberFormatter オブジェクト。

type

妥当なロケールあるいは正確なロケールのいずれか ( Locale::VALID_LOCALE, Locale::ACTUAL_LOCALE, respectively) を選択します。デフォルトは実際のロケールです。

戻り値

フォーマッタの作成時に使用したロケールを返します。 失敗した場合は false を返します。

例

例1 numfmt_get_locale() の例

<?php
$req = 'fr_FR_PARIS';
$fmt = numfmt_create( $req, NumberFormatter::DECIMAL);
$res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
$res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
printf( "Requested locale name: %s\nValid locale name: %s\nActual locale name: %s\n",
$req, $res_val, $res_act );
?>

上の例の出力は以下となります。

Requested locale name: fr_FR_PARIS
Valid locale name: fr_FR
Actual locale name: fr

参考

  • numfmt_create() - 数値フォーマッタを作成する
  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する


フォーマッタのパターンを取得する

  • ≪ NumberFormatter::getLocale
  • NumberFormatter::getSymbol ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタのパターンを取得する

NumberFormatter::getPattern

numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — フォーマッタのパターンを取得する

説明

オブジェクト指向型

public NumberFormatter::getPattern(): string|false

手続き型

numfmt_get_pattern(NumberFormatter $formatter): string|false

フォーマッタが使用するパターンを取り出します。

パラメータ

formatter

NumberFormatter オブジェクト。

戻り値

このフォーマッタが使用するパターン文字列、 あるいはエラー発生時に false を返します。

例

例1 numfmt_get_pattern() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_pattern($fmt, "#0.# kg");
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setPattern("#0.# kg");
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Pattern: #,##0.###
1.234.567,891
Pattern: #0.# kg
1234567,9 kg

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_set_pattern() - フォーマッタのパターンを設定する
  • numfmt_create() - 数値フォーマッタを作成する


記号を取得する

  • ≪ NumberFormatter::getPattern
  • NumberFormatter::getTextAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 記号を取得する

NumberFormatter::getSymbol

numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — 記号を取得する

説明

オブジェクト指向型

public NumberFormatter::getSymbol(int $symbol): string|false

手続き型

numfmt_get_symbol(NumberFormatter $formatter, int $symbol): string|false

フォーマッタに関連づけられている記号を取得します。 フォーマッタでは、この記号で数値の中のロケールに依存する文字 (パーセント記号など) を扱います。 この API は、ルールベースのフォーマッタではサポートしていません。

パラメータ

formatter

NumberFormatter オブジェクト。

symbol

記号指定子。 フォーマット記号 定数のいずれか。

戻り値

記号文字列、あるいはエラー時に false を返します。

例

例1 numfmt_get_symbol() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Sep: .
1.234.567,891
Sep: *
1*234*567,891

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_set_symbol() - 記号の値を設定する


テキストの属性を取得する

  • ≪ NumberFormatter::getSymbol
  • NumberFormatter::parse ≫
  • PHP Manual
  • NumberFormatter
  • テキストの属性を取得する

NumberFormatter::getTextAttribute

numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — テキストの属性を取得する

説明

オブジェクト指向型

public NumberFormatter::getTextAttribute(int $attribute): string|false

手続き型

numfmt_get_text_attribute(NumberFormatter $formatter, int $attribute): string|false

フォーマッタに関連づけられているテキスト属性を取得します。 テキスト属性の例としては、正の数字のサフィックスなどがあります。 属性が理解できない場合は、エラー U_UNSUPPORTED_ERROR が発生します。 ルールベースのフォーマッタでは、 NumberFormatter::DEFAULT_RULESET および NumberFormatter::PUBLIC_RULESETS のみが使用できます。

パラメータ

formatter

NumberFormatter オブジェクト。

attribute

属性指定子。 テキスト属性 定数のいずれか。

戻り値

成功した場合に属性の値、あるいはエラー時に false を返します。

例

例1 numfmt_get_text_attribute() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
$fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Prefix: -
-1.234.567,891
Prefix: MINUS
MINUS1.234.567,891

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_get_attribute() - 属性を取得する
  • numfmt_set_text_attribute() - テキスト属性を設定する


数値をパースする

  • ≪ NumberFormatter::getTextAttribute
  • NumberFormatter::parseCurrency ≫
  • PHP Manual
  • NumberFormatter
  • 数値をパースする

NumberFormatter::parse

numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — 数値をパースする

説明

オブジェクト指向型

public NumberFormatter::parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int &$offset = null): int|float|false

手続き型

numfmt_parse(
NumberFormatter $formatter,
string $string,
int $type = NumberFormatter::TYPE_DOUBLE,
int &$offset = null
): int|float|false

現在のフォーマット規則を使用して、文字列を数値にパースします。

パラメータ

formatter

NumberFormatter オブジェクト。

string

数値としてパースする文字列。

type

使用する フォーマット形式。デフォルトでは NumberFormatter::TYPE_DOUBLE を使用します。 NumberFormatter::TYPE_CURRENCY はサポートされていないので注意して下さい。 NumberFormatter::TYPE_CURRENCY を使いたい場合、 代わりに NumberFormatter::parseCurrency() を使いましょう。

offset

文字列中でパースを開始する位置のオフセット。 結果を返す際に、この値はパース終了時のオフセットを保持します。

戻り値

パースした数値、あるいはエラー時に false を返します。

例

例1 numfmt_parse() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
$num = "1.234.567,891";
echo numfmt_parse($fmt, $num)."\n";
echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
$num = "1.234.567,891";
echo $fmt->parse($num)."\n";
echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
?>

上の例の出力は以下となります。

1234567.891
1234567

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_format() - 数値をフォーマットする
  • numfmt_parse_currency() - 通貨をパースする


通貨をパースする

  • ≪ NumberFormatter::parse
  • NumberFormatter::setAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 通貨をパースする

NumberFormatter::parseCurrency

numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — 通貨をパースする

説明

オブジェクト指向型

public NumberFormatter::parseCurrency(string $string, string &$currency, int &$offset = null): float|false

手続き型

numfmt_parse_currency(
NumberFormatter $formatter,
string $string,
string &$currency,
int &$offset = null
): float|false

現在のフォーマッタを使用して、文字列を浮動小数点と通貨にパースします。

パラメータ

formatter

NumberFormatter オブジェクト。

currency

通貨名 (3 文字の ISO 4217 通貨コード) を受け取るパラメータ。

offset

文字列中でパースを開始する位置のオフセット。 結果を返す際に、この値はパース終了時のオフセットを保持します。

戻り値

パースした数値、あるいはエラー時に false を返します。

例

例1 numfmt_parse_currency() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
$num = "1.234.567,89\xc2\xa0$";
echo "We have ".numfmt_parse_currency($fmt, $num, $curr)." in $curr\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
$num = "1.234.567,89\xc2\xa0$";
echo "We have ".$fmt->parseCurrency($num, $curr)." in $curr\n";
?>

上の例の出力は以下となります。

We have 1234567.89 in USD

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_parse() - 数値をパースする
  • numfmt_format_currency() - 通貨の値をフォーマットする


属性を設定する

  • ≪ NumberFormatter::parseCurrency
  • NumberFormatter::setPattern ≫
  • PHP Manual
  • NumberFormatter
  • 属性を設定する

NumberFormatter::setAttribute

numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — 属性を設定する

説明

オブジェクト指向型

public NumberFormatter::setAttribute(int $attribute, int|float $value): bool

手続き型

numfmt_set_attribute(NumberFormatter $formatter, int $attribute, int|float $value): bool

フォーマッタに関連づけられている数値属性を設定します。 数値属性の例としては、フォーマッタが作成する整数部の桁数などがあります。

パラメータ

formatter

NumberFormatter オブジェクト。

attribute

属性指定子。 数値属性 定数のいずれか。

value

属性の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 numfmt_set_attribute() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Digits: 3
1.234.567,891
Digits: 2
1.234.567,89

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_get_attribute() - 属性を取得する
  • numfmt_set_text_attribute() - テキスト属性を設定する


フォーマッタのパターンを設定する

  • ≪ NumberFormatter::setAttribute
  • NumberFormatter::setSymbol ≫
  • PHP Manual
  • NumberFormatter
  • フォーマッタのパターンを設定する

NumberFormatter::setPattern

numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — フォーマッタのパターンを設定する

説明

オブジェクト指向型

public NumberFormatter::setPattern(string $pattern): bool

手続き型

numfmt_set_pattern(NumberFormatter $formatter, string $pattern): bool

フォーマッタが使用するパターンを設定します。 ルールベースのフォーマッタでは使用できません。

パラメータ

formatter

NumberFormatter オブジェクト。

pattern

» ICU DecimalFormat ドキュメント で述べられている構文によるパターン。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 numfmt_set_pattern() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_pattern($fmt, "#0.# kg");
echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setPattern("#0.# kg");
echo "Pattern: ".$fmt->getPattern()."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Pattern: #,##0.###
1.234.567,891
Pattern: #0.# kg
1234567,9 kg

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_create() - 数値フォーマッタを作成する
  • numfmt_get_pattern() - フォーマッタのパターンを取得する


記号の値を設定する

  • ≪ NumberFormatter::setPattern
  • NumberFormatter::setTextAttribute ≫
  • PHP Manual
  • NumberFormatter
  • 記号の値を設定する

NumberFormatter::setSymbol

numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — 記号の値を設定する

説明

オブジェクト指向型

public NumberFormatter::setSymbol(int $symbol, string $value): bool

手続き型

numfmt_set_symbol(NumberFormatter $formatter, int $symbol, string $value): bool

フォーマッタに関連づけられている記号を設定します。 フォーマッタでは、この記号で数値の中のロケールに依存する文字 (パーセント記号など) を扱います。 この API は、ルールベースのフォーマッタではサポートしていません。

パラメータ

formatter

NumberFormatter オブジェクト。

symbol

記号指定子。 フォーマット記号 定数のいずれか。

value

その記号に対応するテキスト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 numfmt_set_symbol() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo numfmt_format($fmt, 1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
$fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
echo $fmt->format(1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Sep: .
1.234.567,891
Sep: *
1*234*567,891

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_get_symbol() - 記号を取得する


テキスト属性を設定する

  • ≪ NumberFormatter::setSymbol
  • Locale ≫
  • PHP Manual
  • NumberFormatter
  • テキスト属性を設定する

NumberFormatter::setTextAttribute

numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — テキスト属性を設定する

説明

オブジェクト指向型

public NumberFormatter::setTextAttribute(int $attribute, string $value): bool

手続き型

numfmt_set_text_attribute(NumberFormatter $formatter, int $attribute, string $value): bool

フォーマッタに関連づけられているテキスト属性を設定します。 テキスト属性の例としては、正の数字のサフィックスなどがあります。 属性が理解できない場合は、エラー U_UNSUPPORTED_ERROR が発生します。 ルールベースのフォーマッタでは、 NumberFormatter::DEFAULT_RULESET および NumberFormatter::PUBLIC_RULESETS のみが使用できます。

パラメータ

formatter

NumberFormatter オブジェクト。

attribute

属性指定子。 テキスト属性 定数のいずれか。

value

属性の値を表すテキスト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 numfmt_set_text_attribute() の例

<?php
$fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
echo numfmt_format($fmt, -1234567.891234567890000)."\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
$fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
echo $fmt->format(-1234567.891234567890000)."\n";
?>

上の例の出力は以下となります。

Prefix: -
-1.234.567,891
Prefix: MINUS
MINUS1.234.567,891

参考

  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
  • numfmt_get_text_attribute() - テキストの属性を取得する
  • numfmt_set_attribute() - 属性を設定する


Locale クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

はじめに

"ロケール" とは、言語や文化等の地域固有の内容を API で取得する際に使用する識別子のことです。PHP で使用しているロケールは、 ICU (そして他の多くの Unix 系 OS や Mac、Java など) が採用している CLDR ロケールと同じです。 ロケールは、RFC 4646 形式の言語タグ (アンダースコアではなくハイフンを使用したもの) を使用します。古くから用いられているアンダースコア形式の識別子も使用できます。 特にことわりがない限り、このクラスの関数では両方の形式の識別子を使用可能です。

識別子の例を以下にあげます。

  • en-US (英語、米国)
  • zh-Hant-TW (中国語、繁体字、台湾 )
  • fr-CA, fr-FR (それぞれ、カナダのフランス語とフランスのフランス語)

Locale クラス (そしてそれに対応する手続き型の関数) を使用して、ロケール識別子に対する操作を行います。 たとえばその識別子が妥当な形式かどうかを調べたりします。 CLDR が UAX #35 で使用している (そして ICU も継承している) 拡張は、ICU で普通に用いることができます。

Locale クラスのインスタンスを作成することはできません。 すべての関数/メソッドは :: を付けて呼び出します。

null や空文字列は "root" ロケールとなります。 この "root" ロケールは、CLDR においては "en_US_POSIX" と同じ意味になります。言語タグ (そして ロケール識別子) は大文字小文字を区別しません。 仕様にあわせて大文字小文字の正規化を行う関数が存在します。

クラス概要

class Locale {
/* 定数 */
public const int ACTUAL_LOCALE;
public const int VALID_LOCALE;
public const null DEFAULT_LOCALE = null;
public const string LANG_TAG;
public const string EXTLANG_TAG;
public const string SCRIPT_TAG;
public const string REGION_TAG;
public const string VARIANT_TAG;
public const string GRANDFATHERED_LANG_TAG;
public const string PRIVATE_TAG;
/* メソッド */
public static acceptFromHttp(string $header): string|false
public static canonicalize(string $locale): ?string
public static composeLocale(array $subtags): string|false
public static filterMatches(string $languageTag, string $locale, bool $canonicalize = false): ?bool
public static getAllVariants(string $locale): ?array
public static getDefault(): string
public static getDisplayLanguage(string $locale, ?string $displayLocale = null): string|false
public static getDisplayName(string $locale, ?string $displayLocale = null): string|false
public static getDisplayRegion(string $locale, ?string $displayLocale = null): string|false
public static getDisplayScript(string $locale, ?string $displayLocale = null): string|false
public static getDisplayVariant(string $locale, ?string $displayLocale = null): string|false
public static getKeywords(string $locale): array|false|null
public static getPrimaryLanguage(string $locale): ?string
public static getRegion(string $locale): ?string
public static getScript(string $locale): ?string
public static lookup(
array $languageTag,
string $locale,
bool $canonicalize = false,
?string $defaultLocale = null
): ?string
public static parseLocale(string $locale): ?array
public static setDefault(string $locale): bool
}

定義済み定数

Locale::DEFAULT_LOCALE
NumberFormatter のようなロケールの影響を受けるさまざまなクラスのメソッドの locale パラメータとして使用します。 この定数は、デフォルトのロケールをメソッドで使用するようにします。

これらの定数は、さまざまなクラスの getLocale メソッドでロケールを選択するために使用します。

Locale::ACTUAL_LOCALE
これは、データが実際にやってくる元のロケールです。
Locale::VALID_LOCALE
これは、ICU がサポートする最も明確なロケールです。

ロケールのサブタグ

これらの定数は、ロケールのパースや合成の方法を定義します。 locale_compose() の引数に渡す配列のキーとして使用し、 また locale_parse() が返す連想配列のキーとしても用いられます。

Locale::LANG_TAG
言語サブタグ
Locale::EXTLANG_TAG
拡張言語サブタグ
Locale::SCRIPT_TAG
文字サブタグ
Locale::REGION_TAG
地域サブタグ
Locale::VARIANT_TAG
変化形サブタグ
Locale::GRANDFATHERED_LANG_TAG
先祖言語 (Grandfathered Language) サブタグ
Locale::PRIVATE_TAG
プライベートサブタグ

参考

  • » RFC 4646 - Tags for Identifying Languages
  • » RFC 4647 - Matching of Language Tags
  • » Unicode CLDR Project:Common Locale Data Repository
  • » IANA Language Subtags Registry
  • » ICU User Guide - Locale
  • » ICU Locale api

目次

  • Locale::acceptFromHttp — 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す
  • Locale::canonicalize — ロケール文字列を正規化する
  • Locale::composeLocale — 正しく並べ替えて区切られたロケール ID を返す
  • Locale::filterMatches — 言語タグフィルタがロケールにマッチするかどうかを調べる
  • Locale::getAllVariants — 入力ロケールの変化系を取得する
  • Locale::getDefault — INTL のグローバル 'default_locale' からデフォルトのロケールを取得する
  • Locale::getDisplayLanguage — 入力ロケールの言語の表示名を、適切に地域化して返す
  • Locale::getDisplayName — 入力ロケールの表示名を、適切に地域化して返す
  • Locale::getDisplayRegion — 入力ロケールの地域の表示名を、適切に地域化して返す
  • Locale::getDisplayScript — 入力ロケールの文字の表示名を、適切に地域化して返す
  • Locale::getDisplayVariant — 入力ロケールの変化形の表示名を、適切に地域化して返す
  • Locale::getKeywords — 入力ロケールのキーワードを取得する
  • Locale::getPrimaryLanguage — 入力ロケールのプライマリ言語を取得する
  • Locale::getRegion — 入力ロケールの地域を取得する
  • Locale::getScript — 入力ロケールの文字を取得する
  • Locale::lookup — その言語にマッチする言語タグの一覧を検索する
  • Locale::parseLocale — ロケール ID のサブタグ要素を連想配列で返す
  • Locale::setDefault — デフォルトの実行時ロケールを設定する


最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す

  • ≪ Locale
  • Locale::canonicalize ≫
  • PHP Manual
  • Locale
  • 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す

Locale::acceptFromHttp

locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す

説明

オブジェクト指向型

public static Locale::acceptFromHttp(string $header): string|false

手続き型

locale_accept_from_http(string $header): string|false

HTTP "Accept-Language" ヘッダが要求する言語リストを満たすロケールを探します。

パラメータ

header

"Accept-Language" ヘッダを含む文字列。RFC 2616 形式。

戻り値

対応するロケール ID を返します。

header の長さが INTL_MAX_LOCALE_LEN を超えた場合、false を返します。

例

例1 locale_accept_from_http() の例

<?php
$locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
echo $locale;
?>

例2 オブジェクト指向の例

<?php
$locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
echo $locale;
?>

上の例の出力は以下となります。

en_US

参考

  • locale_lookup() - その言語にマッチする言語タグの一覧を検索する


ロケール文字列を正規化する

  • ≪ Locale::acceptFromHttp
  • Locale::composeLocale ≫
  • PHP Manual
  • Locale
  • ロケール文字列を正規化する

Locale::canonicalize

locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — ロケール文字列を正規化する

説明

public static Locale::canonicalize(string $locale): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

戻り値

正規化されたロケール文字列を返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。


正しく並べ替えて区切られたロケール ID を返す

  • ≪ Locale::canonicalize
  • Locale::filterMatches ≫
  • PHP Manual
  • Locale
  • 正しく並べ替えて区切られたロケール ID を返す

Locale::composeLocale

locale_compose

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — 正しく並べ替えて区切られたロケール ID を返す

説明

オブジェクト指向型

public static Locale::composeLocale(array $subtags): string|false

手続き型

locale_compose(array $subtags): string|false

正しく並べ替えて区切られたロケール ID を返します。 キーが特定のロケール ID サブタグを表し、 サブタグの値がそのキーに対応する値となります。

パラメータ

subtags

キーと値のペアを含む配列。 キーには特定のロケール ID サブタグを指定し、 そのサブタグの値を関連付けます。

注意:

サブタグ 'variant' と 'private' には最大で 15 の値を指定できますが、 'extlang' には最大で 3 つの値しか指定できません。 たとえば、variant には 0 から 14 までの サフィックスをつけることができ、 配列のキーは variant0, variant1, ..., variant14 となります。 返されるロケール ID において、このサブタグは variant0、 variant1、 variant2、......の順に並びます。

代わりに、'variant'、 'private' および 'extlang' の値は、特定のキー (例 'variant') に対して配列を指定できます。 この場合、サブタグに適用される値の数には制限がありません。

戻り値

対応するロケール識別子を返します。 subtags が空の場合は false を返します。

例

例1 locale_compose() の例

<?php
$arr = array(
'language'=>'en',
'script' =>'Hans',
'region' =>'CN',
'variant2'=>'rozaj',
'variant1'=>'nedis',
'private1'=>'prv1',
'private2'=>'prv2',
);
echo locale_compose($arr);
?>

例2 オブジェクト指向の例

<?php
$arr = array(
'language'=>'en' ,
'script' =>'Hans',
'region' =>'CN',
'variant2'=>'rozaj',
'variant1'=>'nedis',
'private1'=>'prv1',
'private2'=>'prv2',
);
echo Locale::composeLocale($arr);
?>

上の例の出力は以下となります。

Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

例3 サブタグの制限

subtags に、 数字が末尾に付く複数のキーが別々に指定された場合、 サポートされていないキーは黙って無視され (以下の例では、'extlang3')、 結果は末尾の数値の順に並びます。 サブタグの値に配列が指定された場合は、 この制限はなく、結果は与えられた順に並びます。

<?php
$arr = array(
'language' => 'en',
'script' => 'Hans',
'region' => 'CN',
'extlang3' => 'd',
'extlang2' => 'c',
'extlang1' => 'b',
'extlang0' => 'a',
);
echo locale_compose($arr), PHP_EOL;

$arr = array(
'language' => 'en',
'script' => 'Hans',
'region' => 'CN',
'extlang' => ['a', 'b', 'c', 'd'],
);
echo locale_compose($arr), PHP_EOL;
?>

上の例の出力は以下となります。

en_a_b_c_Hans_CN
en_a_b_c_d_Hans_CN

参考

  • locale_parse() - ロケール ID のサブタグ要素を連想配列で返す


言語タグフィルタがロケールにマッチするかどうかを調べる

  • ≪ Locale::composeLocale
  • Locale::getAllVariants ≫
  • PHP Manual
  • Locale
  • 言語タグフィルタがロケールにマッチするかどうかを調べる

Locale::filterMatches

locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — 言語タグフィルタがロケールにマッチするかどうかを調べる

説明

オブジェクト指向型

public static Locale::filterMatches(string $languageTag, string $locale, bool $canonicalize = false): ?bool

手続き型

locale_filter_matches(string $languageTag, string $locale, bool $canonicalize = false): ?bool

languageTag フィルタが locale でマッチするかどうかを RFC 4647 の基本フィルタリングアルゴリズムで調べます。

パラメータ

languageTag

調べたい言語タグ。

locale

調べる対象となる言語の範囲。

canonicalize

true の場合は、引数を正式な形式に変換してからマッチを行います。

戻り値

locale が languageTag にマッチする場合に true、 それ以外の場合に false を返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_filter_matches() の例

<?php
echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
echo '; ';
echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Matches" : "Does not match";
?>

例2 オブジェクト指向の例

<?php
echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
echo '; ';
echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Matches" : "Does not match";
?>

上の例の出力は以下となります。

Does not match; Matches

参考

  • locale_lookup() - その言語にマッチする言語タグの一覧を検索する


入力ロケールの変化系を取得する

  • ≪ Locale::filterMatches
  • Locale::getDefault ≫
  • PHP Manual
  • Locale
  • 入力ロケールの変化系を取得する

Locale::getAllVariants

locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — 入力ロケールの変化系を取得する

説明

オブジェクト指向型

public static Locale::getAllVariants(string $locale): ?array

手続き型

locale_get_all_variants(string $locale): ?array

入力ロケールの変化系を取得します。

パラメータ

locale

変化系を取得したいロケール。

戻り値

そのロケールのすべての variant サブタグを含む配列、あるいは存在しない場合に null を返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_get_all_variants() の例

<?php
$arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
var_export( $arr );
?>

例2 オブジェクト指向の例

<?php
$arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
var_export( $arr );
?>

上の例の出力は以下となります。

array (
    0 => 'NEDIS',
    1 => 'ROJAZ',
    2 => '1901',
)

参考

  • locale_get_primary_language() - 入力ロケールのプライマリ言語を取得する
  • locale_get_script() - 入力ロケールの文字を取得する
  • locale_get_region() - 入力ロケールの地域を取得する


INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

  • ≪ Locale::getAllVariants
  • Locale::getDisplayLanguage ≫
  • PHP Manual
  • Locale
  • INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

Locale::getDefault

locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — INTL のグローバル 'default_locale' からデフォルトのロケールを取得する

説明

オブジェクト指向型

public static Locale::getDefault(): string

手続き型

locale_get_default(): string

デフォルトのロケールの値を取得します。PHP の国際化においては、 この値は php.ini の 'intl.default_locale' の値となります。 この値が存在しない場合は ICU の関数 uloc_getDefault() で取得します。

パラメータ

戻り値

現在の実行時ロケールを返します。

例

例1 locale_get_default() の例

<?php
ini_set('intl.default_locale', 'de-DE');
echo locale_get_default();
echo '; ';
locale_set_default('fr');
echo locale_get_default();
?>

例2 オブジェクト指向の例

<?php
ini_set('intl.default_locale', 'de-DE');
echo Locale::getDefault();
echo '; ';
Locale::setDefault('fr');
echo Locale::getDefault();
?>

上の例の出力は以下となります。

de-DE; fr

参考

  • locale_set_default() - デフォルトの実行時ロケールを設定する


入力ロケールの言語の表示名を、適切に地域化して返す

  • ≪ Locale::getDefault
  • Locale::getDisplayName ≫
  • PHP Manual
  • Locale
  • 入力ロケールの言語の表示名を、適切に地域化して返す

Locale::getDisplayLanguage

locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — 入力ロケールの言語の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayLanguage(string $locale, ?string $displayLocale = null): string|false

手続き型

locale_get_display_language(string $locale, ?string $displayLocale = null): string|false

入力ロケールの言語の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示言語を返したいロケール。

displayLocale

オプションのフォーマットロケール。 言語名の表示に使用します。

戻り値

locale に対応する言語の表示名を、 displayLocale にあわせた形式で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | displayLocale は、nullable になりました。

例

例1 locale_get_display_language() の例

<?php
echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
?>

上の例の出力は以下となります。

Slovenian;
slov\xc3\xa8ne;
Slowenisch

参考

  • locale_get_display_name() - 入力ロケールの表示名を、適切に地域化して返す
  • locale_get_display_script() - 入力ロケールの文字の表示名を、適切に地域化して返す
  • locale_get_display_region() - 入力ロケールの地域の表示名を、適切に地域化して返す
  • locale_get_display_variant() - 入力ロケールの変化形の表示名を、適切に地域化して返す


入力ロケールの表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayLanguage
  • Locale::getDisplayRegion ≫
  • PHP Manual
  • Locale
  • 入力ロケールの表示名を、適切に地域化して返す

Locale::getDisplayName

locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — 入力ロケールの表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayName(string $locale, ?string $displayLocale = null): string|false

手続き型

locale_get_display_name(string $locale, ?string $displayLocale = null): string|false

入力ロケールの表示名を、適切に地域化して返します。 locale が null の場合はデフォルトのロケールを使用します。

説明

オブジェクト指向型

public static Locale::getDisplayName(string $locale, string $in_locale = ?): string

手続き型

locale_get_display_name(string $locale, string $in_locale = ?): string

入力ロケールの表示名を、適切に地域化して返します。 $locale が null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示名を返したいロケール。

displayLocale

オプションのフォーマットロケール。

戻り値

ロケールの表示名を、 displayLocale にあわせた形式で返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | displayLocale は、nullable になりました。

例

例1 locale_get_display_name() の例

<?php
echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
?>

上の例の出力は以下となります。

Slovenian (Latin, Italy, Natisone dialect);
slov\xc3\xa8ne (latin, Italie, dialecte de Natisone;
Slowenisch (Lateinisch, Italien, NEDIS)

参考

  • locale_get_display_language() - 入力ロケールの言語の表示名を、適切に地域化して返す
  • locale_get_display_script() - 入力ロケールの文字の表示名を、適切に地域化して返す
  • locale_get_display_region() - 入力ロケールの地域の表示名を、適切に地域化して返す
  • locale_get_display_variant() - 入力ロケールの変化形の表示名を、適切に地域化して返す


入力ロケールの地域の表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayName
  • Locale::getDisplayScript ≫
  • PHP Manual
  • Locale
  • 入力ロケールの地域の表示名を、適切に地域化して返す

Locale::getDisplayRegion

locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — 入力ロケールの地域の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayRegion(string $locale, ?string $displayLocale = null): string|false

手続き型

locale_get_display_region(string $locale, ?string $displayLocale = null): string|false

入力ロケールの地域の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示地域を返したいロケール。

displayLocale

オプションのフォーマットロケール。 地域名の表示に使用します。

戻り値

locale に対応する地域の表示名を、 displayLocale にあわせた形式で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | displayLocale は、nullable になりました。

例

例1 locale_get_display_region() の例

<?php
echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
?>

上の例の出力は以下となります。

Italy;
Italie;
Italien

参考

  • locale_get_display_name() - 入力ロケールの表示名を、適切に地域化して返す
  • locale_get_display_language() - 入力ロケールの言語の表示名を、適切に地域化して返す
  • locale_get_display_script() - 入力ロケールの文字の表示名を、適切に地域化して返す
  • locale_get_display_variant() - 入力ロケールの変化形の表示名を、適切に地域化して返す


入力ロケールの文字の表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayRegion
  • Locale::getDisplayVariant ≫
  • PHP Manual
  • Locale
  • 入力ロケールの文字の表示名を、適切に地域化して返す

Locale::getDisplayScript

locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — 入力ロケールの文字の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayScript(string $locale, ?string $displayLocale = null): string|false

手続き型

locale_get_display_script(string $locale, ?string $displayLocale = null): string|false

入力ロケールの文字の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示文字を返したいロケール。

displayLocale

オプションのフォーマットロケール。 文字名の表示に使用します。

戻り値

locale に対応する文字の表示名を、 displayLocale にあわせた形式で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | displayLocale は、nullable になりました。

例

例1 locale_get_display_script() の例

<?php
echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
?>

上の例の出力は以下となります。

Latin;
latin;
Lateinisch

参考

  • locale_get_display_name() - 入力ロケールの表示名を、適切に地域化して返す
  • locale_get_display_language() - 入力ロケールの言語の表示名を、適切に地域化して返す
  • locale_get_display_region() - 入力ロケールの地域の表示名を、適切に地域化して返す
  • locale_get_display_variant() - 入力ロケールの変化形の表示名を、適切に地域化して返す


入力ロケールの変化形の表示名を、適切に地域化して返す

  • ≪ Locale::getDisplayScript
  • Locale::getKeywords ≫
  • PHP Manual
  • Locale
  • 入力ロケールの変化形の表示名を、適切に地域化して返す

Locale::getDisplayVariant

locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — 入力ロケールの変化形の表示名を、適切に地域化して返す

説明

オブジェクト指向型

public static Locale::getDisplayVariant(string $locale, ?string $displayLocale = null): string|false

手続き型

locale_get_display_variant(string $locale, ?string $displayLocale = null): string|false

入力ロケールの変化形の表示名を、適切に地域化して返します。 null の場合はデフォルトのロケールを使用します。

パラメータ

locale

表示変化形を返したいロケール。

displayLocale

オプションのフォーマットロケール。 変化形の表示に使用します。

戻り値

locale に対応する変化形の表示名を、 displayLocale にあわせた形式で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | displayLocale は、nullable になりました。

例

例1 locale_get_display_variant() の例

<?php
echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
echo ";\n";
echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
echo ";\n";
echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
?>

上の例の出力は以下となります。

Natisone dialect;
dialecte de Natisone;
NEDIS

参考

  • locale_get_display_name() - 入力ロケールの表示名を、適切に地域化して返す
  • locale_get_display_language() - 入力ロケールの言語の表示名を、適切に地域化して返す
  • locale_get_display_script() - 入力ロケールの文字の表示名を、適切に地域化して返す
  • locale_get_display_region() - 入力ロケールの地域の表示名を、適切に地域化して返す


入力ロケールのキーワードを取得する

  • ≪ Locale::getDisplayVariant
  • Locale::getPrimaryLanguage ≫
  • PHP Manual
  • Locale
  • 入力ロケールのキーワードを取得する

Locale::getKeywords

locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — 入力ロケールのキーワードを取得する

説明

オブジェクト指向型

public static Locale::getKeywords(string $locale): array|false|null

手続き型

locale_get_keywords(string $locale): array|false|null

入力ロケールのキーワードを取得します。

パラメータ

locale

キーワードを取り出したいロケール。

戻り値

このロケールのキーワードと値のペアを連想配列で返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_get_keywords() の例

<?php
$keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
if ($keywords_arr) {
foreach ($keywords_arr as $key => $value) {
echo "$key = $value\n";
}
}
?>

例2 オブジェクト指向の例

<?php
$keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
if ($keywords_arr) {
foreach ($keywords_arr as $key => $value) {
echo "$key = $value\n";
}
}
?>

上の例の出力は以下となります。

collation = PHONEBOOK
currency = EUR

参考

  • locale_get_all_variants() - 入力ロケールの変化系を取得する


入力ロケールのプライマリ言語を取得する

  • ≪ Locale::getKeywords
  • Locale::getRegion ≫
  • PHP Manual
  • Locale
  • 入力ロケールのプライマリ言語を取得する

Locale::getPrimaryLanguage

locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — 入力ロケールのプライマリ言語を取得する

説明

オブジェクト指向型

public static Locale::getPrimaryLanguage(string $locale): ?string

手続き型

locale_get_primary_language(string $locale): ?string

入力ロケールのプライマリ言語を取得します。

パラメータ

locale

プライマリ言語コードを取り出したいロケール。

戻り値

このロケールの言語コードを返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_get_primary_language() の例

<?php
echo locale_get_primary_language('zh-Hant');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getPrimaryLanguage('zh-Hant');
?>

上の例の出力は以下となります。

zh

参考

  • locale_get_script() - 入力ロケールの文字を取得する
  • locale_get_region() - 入力ロケールの地域を取得する
  • locale_get_all_variants() - 入力ロケールの変化系を取得する


入力ロケールの地域を取得する

  • ≪ Locale::getPrimaryLanguage
  • Locale::getScript ≫
  • PHP Manual
  • Locale
  • 入力ロケールの地域を取得する

Locale::getRegion

locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — 入力ロケールの地域を取得する

説明

オブジェクト指向型

public static Locale::getRegion(string $locale): ?string

手続き型

locale_get_region(string $locale): ?string

入力ロケールの地域を取得します。

パラメータ

locale

地域コードを取り出したいロケール。

戻り値

このロケールの地域サブタグを返します。 地域サブタグが存在しない場合は null を返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_get_region() の例

<?php
echo locale_get_region('de-CH-1901');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getRegion('de-CH-1901');
?>

上の例の出力は以下となります。

CH

参考

  • locale_get_primary_language() - 入力ロケールのプライマリ言語を取得する
  • locale_get_script() - 入力ロケールの文字を取得する
  • locale_get_all_variants() - 入力ロケールの変化系を取得する


入力ロケールの文字を取得する

  • ≪ Locale::getRegion
  • Locale::lookup ≫
  • PHP Manual
  • Locale
  • 入力ロケールの文字を取得する

Locale::getScript

locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — 入力ロケールの文字を取得する

説明

オブジェクト指向型

public static Locale::getScript(string $locale): ?string

手続き型

locale_get_script(string $locale): ?string

入力ロケールの文字を取得します。

パラメータ

locale

文字を取り出したいロケール。

戻り値

このロケールの文字サブタグ、あるいは存在しない場合に null を返します。

例

例1 locale_get_script() の例

<?php
echo locale_get_script('sr-Cyrl');
?>

例2 オブジェクト指向の例

<?php
echo Locale::getScript('sr-Cyrl');
?>

上の例の出力は以下となります。

Cyrl

参考

  • locale_get_primary_language() - 入力ロケールのプライマリ言語を取得する
  • locale_get_region() - 入力ロケールの地域を取得する
  • locale_get_all_variants() - 入力ロケールの変化系を取得する


その言語にマッチする言語タグの一覧を検索する

  • ≪ Locale::getScript
  • Locale::parseLocale ≫
  • PHP Manual
  • Locale
  • その言語にマッチする言語タグの一覧を検索する

Locale::lookup

locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — その言語にマッチする言語タグの一覧を検索する

説明

オブジェクト指向型

public static Locale::lookup(
array $languageTag,
string $locale,
bool $canonicalize = false,
?string $defaultLocale = null
): ?string

手続き型

locale_lookup(
array $languageTag,
string $locale,
bool $canonicalize = false,
?string $defaultLocale = null
): ?string

languageTag の中から、 locale で指定した言語の範囲に最もマッチするものを RFC 4647 の検索アルゴリズムで調べます。

パラメータ

languageTag

locale と比較したい言語タグの一覧を含む配列。 最大で 100 件まで指定できます。

locale

調べる対象となる言語の範囲として使用するロケール。

canonicalize

true の場合は、引数を正式な形式に変換してからマッチを行います。

defaultLocale

マッチしなかったときに使用するロケール。

戻り値

最も近い言語タグ、あるいはデフォルトの値を返します。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

変更履歴

バージョン | 説明
7.4.0 | defaultLocale は、nullable になりました。

例

例1 locale_lookup() の例

<?php
$arr = array(
'de-DEVA',
'de-DE-1996',
'de',
'de-De'
);
echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
?>

例2 オブジェクト指向の例

<?php
$arr = array(
'de-DEVA',
'de-DE-1996',
'de',
'de-De'
);
echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
?>

上の例の出力は以下となります。

de_de_1996

参考

  • locale_filter_matches() - 言語タグフィルタがロケールにマッチするかどうかを調べる


ロケール ID のサブタグ要素を連想配列で返す

  • ≪ Locale::lookup
  • Locale::setDefault ≫
  • PHP Manual
  • Locale
  • ロケール ID のサブタグ要素を連想配列で返す

Locale::parseLocale

locale_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — ロケール ID のサブタグ要素を連想配列で返す

説明

オブジェクト指向型

public static Locale::parseLocale(string $locale): ?array

手続き型

locale_parse(string $locale): ?array

ロケール ID のサブタグ要素を連想配列で返します。

パラメータ

locale

サブタグの配列を取り出したいロケール。 注意: サブタグ 'variant' と 'private' には最大で 15 の値を指定できますが、 'extlang' には最大で 3 つの値しか指定できません。

戻り値

連想配列を返します。キーがロケール ID サブタグを表し、 そのサブタグの値が関連付けられています。 この配列の並び順はロケール ID サブタグの順となります。変化形が '-varX-varY-varZ' の場合、返される配列は variant0=>varX , variant1=>varY , variant2=>varZ のようになります。

locale の長さが INTL_MAX_LOCALE_LEN を超えた場合、null を返します。

例

例1 locale_parse() の例

<?php
$arr = locale_parse('sl-Latn-IT-nedis');
if ($arr) {
foreach ($arr as $key => $value) {
echo "$key : $value , ";
}
}
?>

例2 オブジェクト指向の例

<?php
$arr = Locale::parseLocale('sl-Latn-IT-nedis');
if ($arr) {
foreach ($arr as $key => $value) {
echo "$key : $value , ";
}
}
?>

上の例の出力は以下となります。

language : sl , script : Latn , region : IT , variant0 : NEDIS ,

参考

  • locale_compose() - 正しく並べ替えて区切られたロケール ID を返す


デフォルトの実行時ロケールを設定する

  • ≪ Locale::parseLocale
  • Normalizer ≫
  • PHP Manual
  • Locale
  • デフォルトの実行時ロケールを設定する

Locale::setDefault

locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — デフォルトの実行時ロケールを設定する

説明

オブジェクト指向型

public static Locale::setDefault(string $locale): bool

手続き型

locale_set_default(string $locale): bool

デフォルトの実行時ロケールを locale に設定します。 これは INTL のグローバル 'default_locale' のロケール ID となります。UAX #35 拡張も使用可能です。

パラメータ

locale

BCP 47 準拠の言語タグ。

戻り値

常に true を返します。

例

例1 locale_set_default() の例

<?php
locale_set_default('de-DE');
echo locale_get_default();
?>

例2 オブジェクト指向の例

<?php
Locale::setDefault('de-DE');
echo Locale::getDefault();
?>

上の例の出力は以下となります。

de-DE

参考

  • locale_get_default() - INTL のグローバル 'default_locale' からデフォルトのロケールを取得する


Normalizer クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

はじめに

正規化とは、文字や文字列を正式に決められた表現に変換する処理のことです。 これは、検索や並べ替えなどの際に比較をするときに特に重要となります。 ただ、それだけではなく、テキストを保存する際に表記を統一するために用いることもあります。

Unicode Consortium では、 アプリケーション側でのさまざまなニーズにあわせていくつかの正規化方式を定義しています。

  • Normalization Form D (NFD) - Canonical Decomposition
  • Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
  • Normalization Form KD (NFKD) - Compatibility Decomposition
  • Normalization Form KC (NFKC) - Compatibility Decomposition followed by Canonical Composition
これらの方式は、テキストに対する変換 (transformation) のセットとして定義されます。変換 (transformation) は、アルゴリズムとデータファイルの両方で表現します。

クラス概要

class Normalizer {
/* 定数 */
public const int FORM_D;
public const int NFD;
public const int FORM_KD;
public const int NFKD;
public const int FORM_C;
public const int NFC;
public const int FORM_KC;
public const int NFKC;
public const int FORM_KC_CF;
public const int NFKC_CF;
/* メソッド */
public static getRawDecomposition(string $string, int $form = Normalizer::FORM_C): ?string
public static isNormalized(string $string, int $form = Normalizer::FORM_C): bool
public static normalize(string $string, int $form = Normalizer::FORM_C): string|false
}

定義済み定数

以下の定数は、使用する正規化方式を定義するものです。

Normalizer::FORM_C
Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
Normalizer::FORM_D
Normalization Form D (NFD) - Canonical Decomposition
Normalizer::NFD

Normalizer::FORM_KC
Normalization Form KC (NFKC) - Compatibility Decomposition, followed by Canonical Composition
Normalizer::NFKC

Normalizer::FORM_KC_CF

Normalizer::FORM_KD
Normalization Form KD (NFKD) - Compatibility Decomposition
Normalizer::NFKD

Normalizer::NFC

Normalizer::NFKC_CF

参考

  • » Unicode Normalization
  • » Unicode Normalization FAQ
  • » ICU User Guide - Normalization
  • » ICU API Reference - Normalization

変更履歴

バージョン | 説明
8.0.0 | Normalizer::NONE が削除されました。

目次

  • Normalizer::getRawDecomposition — UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する
  • Normalizer::isNormalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる
  • Normalizer::normalize — 渡された入力を正規化し、正規化後の文字列を返す


UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する

  • ≪ Normalizer
  • Normalizer::isNormalized ≫
  • PHP Manual
  • Normalizer
  • UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する

Normalizer::getRawDecomposition

normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する

説明

オブジェクト指向型

public static Normalizer::getRawDecomposition(string $string, int $form = Normalizer::FORM_C): ?string

手続き型

normalizer_get_raw_decomposition(string $string, int $form = Normalizer::FORM_C): ?string

指定された UTF-8 エンコードされているコードポイントから、 Unicode Character Database (UCD) で指定されている Decomposition_Mapping プロパティの値を取得します。

パラメータ

string

入力文字列。 この値は単一の文字で、 UTF-8 エンコードされているコードポイントです。

戻り値

Unicode Character Database (UCD) に存在する場合、 Decomposition_Mapping プロパティの値を含む文字列を返します。

指定された文字に Decomposition_Mapping プロパティの値がない場合は、 null を返します。

例

例1 Normalizer::getRawDecomposition() の例

<?php

$result = "";
$strings = [
"a",
"\u{FFDA}",
"\u{FDFA}",
"",
"aa",
"\xF5",
];

foreach ($strings as $string) {
$decomposition = Normalizer::getRawDecomposition($string);
// $decomposition = normalizer_get_raw_decomposition($string); Procedural way

$error_code = intl_get_error_code();
$error_message = intl_get_error_message();

$string_hex = bin2hex($string);
$result .= "---------------------\n";

if ($decomposition === null) {
$result .= "'$string_hex' has no decomposition mapping\n" ;
} else {
$result .= "'$string_hex' has the decomposition mapping '" . bin2hex($decomposition) . "'\n" ;
}

$result .= "error info: '$error_message' ($error_code)\n";
}

echo $result;
?>

上の例の出力は以下となります。

---------------------
'61' has no decomposition mapping
error info: 'U_ZERO_ERROR' (0)
---------------------
'efbf9a' has the decomposition mapping 'e385a1'
error info: 'U_ZERO_ERROR' (0)
---------------------
'efb7ba' has the decomposition mapping 'd8b5d984d98920d8a7d984d984d98720d8b9d984d98ad98720d988d8b3d984d985'
error info: 'U_ZERO_ERROR' (0)
---------------------
'' has no decomposition mapping
error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
---------------------
'6161' has no decomposition mapping
error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
---------------------
'f5' has no decomposition mapping
error info: 'Code point out of range: U_ILLEGAL_ARGUMENT_ERROR' (1)

参考

  • Normalizer::normalize() - 渡された入力を正規化し、正規化後の文字列を返す
  • Normalizer::isNormalized() - 渡された文字列が、指定した正規化を適用済みかどうかを調べる


渡された文字列が、指定した正規化を適用済みかどうかを調べる

  • ≪ Normalizer::getRawDecomposition
  • Normalizer::normalize ≫
  • PHP Manual
  • Normalizer
  • 渡された文字列が、指定した正規化を適用済みかどうかを調べる

Normalizer::isNormalized

normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる

説明

オブジェクト指向型

public static Normalizer::isNormalized(string $string, int $form = Normalizer::FORM_C): bool

手続き型

normalizer_is_normalized(string $string, int $form = Normalizer::FORM_C): bool

渡された文字列が、指定した正規化を適用済みかどうかを調べます。

パラメータ

string

正規化する入力文字列。

form

正規化方式のいずれか。

戻り値

正規化されている場合に true、正規化されていない場合やエラーが発生した場合に false を返します。

例

例1 normalizer_is_normalized() の例

<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)

$char_orig = 'A' . $char_combining_ring_above;
$char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
echo '; ';
echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
?>

例2 オブジェクト指向の例

<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)

$char_orig = 'A' . $char_combining_ring_above;
$char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
echo '; ';
echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
?>

上の例の出力は以下となります。

not normalized; normalized

参考

  • normalizer_normalize() - 渡された入力を正規化し、正規化後の文字列を返す


渡された入力を正規化し、正規化後の文字列を返す

  • ≪ Normalizer::isNormalized
  • MessageFormatter ≫
  • PHP Manual
  • Normalizer
  • 渡された入力を正規化し、正規化後の文字列を返す

Normalizer::normalize

normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — 渡された入力を正規化し、正規化後の文字列を返す

説明

オブジェクト指向型

public static Normalizer::normalize(string $string, int $form = Normalizer::FORM_C): string|false

手続き型

normalizer_normalize(string $string, int $form = Normalizer::FORM_C): string|false

渡された入力を正規化し、正規化後の文字列を返します。

パラメータ

string

正規化する入力文字列。

form

正規化方式のいずれか。

戻り値

正規化後の文字列、あるいはエラーが発生した場合に false を返します。

例

例1 normalizer_normalize() の例

<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)

$char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
$char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

echo urlencode($char_1);
echo ' ';
echo urlencode($char_2);
?>

例2 オブジェクト指向の例

<?php
$char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
$char_combining_ring_above = "\xCC\x8A"; // 'COMBINING RING ABOVE' (U+030A)

$char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
$char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

echo urlencode($char_1);
echo ' ';
echo urlencode($char_2);
?>

上の例の出力は以下となります。

%C3%85 %C3%85

参考

  • normalizer_is_normalized() - 渡された文字列が、指定した正規化を適用済みかどうかを調べる


MessageFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

はじめに

MessageFormatter は、言語に依存しない連結されたメッセージを作成するための具象クラスです。 このクラスのメソッドを使用して、 エンドユーザー向けのすべてのメッセージを作成します。

MessageFormatter クラスは、プログラムから渡したさまざまな部品 (テキスト、数値、日付など) を組み合わせてメッセージを作成します。 MessageFormatter クラスでは、 プログラム側が部品の順序を気にする必要はありません。 このクラスでは、各部品に対して書式指定を使用し、 リソースバンドル内のひとつの文字列にメッセージをまとめます。 たとえば、 "Finished printing x out of y files..." のようなメッセージがあった場合に MessageFormatter は各翻訳に対して柔軟な表示を行います。

これまでは、エンドユーザー向けのメッセージは文章として作成し、 文字列で処理していました。 これは地域化の際にさまざまな問題を引き起こしていました。 文章の構造や単語の並び順、そして数値の書式などは 各言語によってさまざまに異なっているからです。 言語に依存しない方法でメッセージを作成するには、 メッセージの各部分を分割し、そこにデータへのキーを指定するようにします。 このキーを使用して、MessageFormatter クラスはメッセージの各部分を連結します。 そして地域化して適切な書式にした文字列をエンドユーザー向けに表示します。

MessageFormatter はオブジェクトのセットを受け取ってそれをフォーマットし、 フォーマットした文字列を適切な位置に埋め込みます。 MessageFormatter のフォーマットを選択することで、 数値にあわせて複数形を選択することができます。 一般的には、メッセージのフォーマットはリソースから取得し、 引数は実行時に動的に与えるようになります。

クラス概要

class MessageFormatter {
/* メソッド */
public __construct(string $locale, string $pattern)
public static create(string $locale, string $pattern): ?MessageFormatter
public format(array $values): string|false
public static formatMessage(string $locale, string $pattern, array $values): string|false
public getErrorCode(): int
public getErrorMessage(): string
public getLocale(): string
public getPattern(): string|false
public parse(string $string): array|false
public static parseMessage(string $locale, string $pattern, string $message): array|false
public setPattern(string $pattern): bool
}

参考

  • » ICU formatting documentation
  • » ICU message formatting description
  • » ICU message formatters
  • » ICU choice formatters

目次

  • MessageFormatter::create — 新しいメッセージフォーマッタを作成する
  • MessageFormatter::format — メッセージをフォーマットする
  • MessageFormatter::formatMessage — 手早くメッセージをフォーマットする
  • MessageFormatter::getErrorCode — 直近の操作のエラーコードを取得する
  • MessageFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
  • MessageFormatter::getLocale — フォーマッタを作成した際のロケールを取得する
  • MessageFormatter::getPattern — フォーマッタが使用するパターンを取得する
  • MessageFormatter::parse — パターンを使用して入力文字列をパースする
  • MessageFormatter::parseMessage — 手早く入力文字列をパースする
  • MessageFormatter::setPattern — フォーマッタが使用するパターンを設定する


新しいメッセージフォーマッタを作成する

  • ≪ MessageFormatter
  • MessageFormatter::format ≫
  • PHP Manual
  • MessageFormatter
  • 新しいメッセージフォーマッタを作成する

MessageFormatter::create

MessageFormatter::__construct

msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — 新しいメッセージフォーマッタを作成する

説明

オブジェクト指向型 (メソッド)

public static MessageFormatter::create(string $locale, string $pattern): ?MessageFormatter

オブジェクト指向型 (コンストラクタ):

public MessageFormatter::__construct(string $locale, string $pattern)

手続き型

msgfmt_create(string $locale, string $pattern): ?MessageFormatter

新しい Message Formatter を作成します。

パラメータ

locale

引数のフォーマットに用いるロケール。

pattern

引数を埋め込むパターン文字列。 パターンには、'アポストロフィに優しい' 構文を使用します。 詳細は » Quoting/Escaping を参照ください。

戻り値

フォーマッタオブジェクトを返します。 失敗した場合は null を返します。

エラー / 例外

コンストラクタとして呼ばれた場合、失敗時に IntlException をスローします。

例

例1 msgfmt_create() の例

<?php
$fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
$fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo $fmt->format(array(4560, 123, 4560/123));
$fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo $fmt->format(array(4560, 123, 4560/123));
?>

上の例の出力は以下となります。

4,560 monkeys on 123 trees make 37.073 monkeys per tree
4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum

参考

  • msgfmt_format() - メッセージをフォーマットする
  • msgfmt_parse() - パターンを使用して入力文字列をパースする
  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する


メッセージをフォーマットする

  • ≪ MessageFormatter::create
  • MessageFormatter::formatMessage ≫
  • PHP Manual
  • MessageFormatter
  • メッセージをフォーマットする

MessageFormatter::format

msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — メッセージをフォーマットする

説明

オブジェクト指向型

public MessageFormatter::format(array $values): string|false

手続き型

msgfmt_format(MessageFormatter $formatter, array $values): string|false

ロケールの規則にしたがってデータをフォーマット文字列に埋め込み、 メッセージをフォーマットします。

パラメータ

formatter

メッセージのフォーマッタ。

values

フォーマット文字列に埋め込む引数。

戻り値

フォーマットした文字列を返します。 あるいはエラーが発生した場合は false を返します。

例

例1 msgfmt_format() の例

<?php
$fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
$fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo msgfmt_format($fmt, array(4560, 123, 4560/123));
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
echo $fmt->format(array(4560, 123, 4560/123));
$fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
echo $fmt->format(array(4560, 123, 4560/123));
?>

上の例の出力は以下となります。

4,560 monkeys on 123 trees make 37.073 monkeys per tree
4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_parse() - パターンを使用して入力文字列をパースする
  • msgfmt_format_message() - 手早くメッセージをフォーマットする
  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する


手早くメッセージをフォーマットする

  • ≪ MessageFormatter::format
  • MessageFormatter::getErrorCode ≫
  • PHP Manual
  • MessageFormatter
  • 手早くメッセージをフォーマットする

MessageFormatter::formatMessage

msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — 手早くメッセージをフォーマットする

説明

オブジェクト指向型

public static MessageFormatter::formatMessage(string $locale, string $pattern, array $values): string|false

手続き型

msgfmt_format_message(string $locale, string $pattern, array $values): string|false

明示的にフォーマッタオブジェクトを作成せずに、 手早くメッセージをフォーマットする関数です。 この関数を使用するのは、 一度きりのフォーマット処理であってパラメータや状態を保持する必要がない場合か、 追加のコンテキストを ICU に直接与えることで、出力をカスタマイズしたい場合です。

パラメータ

locale

ロケールに依存する部分をフォーマットする際に使用するロケール。

pattern

使用するパターン文字列。 パターンには、'アポストロフィに優しい' 構文を使用します。 詳細は » Quoting/Escaping を参照ください。

values

フォーマット文字列に埋め込む値の配列。

戻り値

フォーマットしたパターン文字列を返します。 エラーが発生した場合は false を返します。

例

例1 msgfmt_format_message() の例

<?php
echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
echo msgfmt_format_message("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
echo msgfmt_format_message("en",
"There {apple, plural,
=0 {are no apples}
=1 {is one apple...}
other {are # apples!}
}",
['apple' => 0]
), "\n";

例2 オブジェクト指向の例

<?php
echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
echo MessageFormatter::formatMessage("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
echo MessageFormatter::formatMessage("en",
"There {apple, plural,
=0 {are no apples}
=1 {is one apple...}
other {are # apples!}
}",
['apple' => 0]
), "\n";

上の例の出力は以下となります。

4,560 monkeys on 123 trees make 37.073 monkeys per tree
4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum
You finished 3rd!
There are no apples

例3 通常の通貨記号と、短い形式の通貨記号を使ってフォーマットするよう、ICU に指示する

ICU ? 67 が必要です

<?php
echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD}", array(123.45));
echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD unit-width-narrow}", array(123.45));

上の例の出力は以下となります。

123,45 CA$
123,45 $

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_parse() - パターンを使用して入力文字列をパースする
  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する


直近の操作のエラーコードを取得する

  • ≪ MessageFormatter::formatMessage
  • MessageFormatter::getErrorMessage ≫
  • PHP Manual
  • MessageFormatter
  • 直近の操作のエラーコードを取得する

MessageFormatter::getErrorCode

msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — 直近の操作のエラーコードを取得する

説明

オブジェクト指向型

public MessageFormatter::getErrorCode(): int

手続き型

msgfmt_get_error_code(MessageFormatter $formatter): int

直近の操作のエラーコードを取得します。

パラメータ

formatter

メッセージのフォーマッタ。

参考

  • msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


直近の操作のエラーテキストを取得する

  • ≪ MessageFormatter::getErrorCode
  • MessageFormatter::getLocale ≫
  • PHP Manual
  • MessageFormatter
  • 直近の操作のエラーテキストを取得する

MessageFormatter::getErrorMessage

msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — 直近の操作のエラーテキストを取得する

説明

オブジェクト指向型

public MessageFormatter::getErrorMessage(): string

手続き型

msgfmt_get_error_message(MessageFormatter $formatter): string

直近の操作のエラーテキストを取得します。

パラメータ

formatter

メッセージのフォーマッタ。

戻り値

直近のエラーの説明を返します。

例

例1 msgfmt_get_error_message() の例

<?php
$fmt = msgfmt_create("en_US", "{0, number} monkeys on {1, number} trees");
$str = msgfmt_format($fmt, array());
if(!$str) {
echo "ERROR: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
}
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter("en_US", "{0, number} monkeys on {1, number} trees");
$str = $fmt->format(array());
if(!$str) {
echo "ERROR: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
}
?>

上の例の出力は以下となります。

ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

参考

  • msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


フォーマッタを作成した際のロケールを取得する

  • ≪ MessageFormatter::getErrorMessage
  • MessageFormatter::getPattern ≫
  • PHP Manual
  • MessageFormatter
  • フォーマッタを作成した際のロケールを取得する

MessageFormatter::getLocale

msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — フォーマッタを作成した際のロケールを取得する

説明

オブジェクト指向型

public MessageFormatter::getLocale(): string

手続き型

msgfmt_get_locale(MessageFormatter $formatter): string

フォーマッタを作成した際のロケールを取得します。

パラメータ

formatter

フォーマッタリソース。

戻り値

ロケール名を返します。

例

例1 msgfmt_get_locale() の例

<?php
$fmt = msgfmt_create('en_US', "Number {0,number}");
echo msgfmt_get_locale($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter('en_US', "Number {0,number}");
echo $fmt->getLocale();
?>

上の例の出力は以下となります。

en_US

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する


フォーマッタが使用するパターンを取得する

  • ≪ MessageFormatter::getLocale
  • MessageFormatter::parse ≫
  • PHP Manual
  • MessageFormatter
  • フォーマッタが使用するパターンを取得する

MessageFormatter::getPattern

msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — フォーマッタが使用するパターンを取得する

説明

オブジェクト指向型

public MessageFormatter::getPattern(): string|false

手続き型

msgfmt_get_pattern(MessageFormatter $formatter): string|false

フォーマッタが使用するパターンを取得します。

パラメータ

formatter

メッセージのフォーマッタ。

戻り値

このメッセージフォーマッタのパターン文字列を返します。 失敗した場合に false を返します

例

例1 msgfmt_get_pattern() の例

<?php
$fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
echo "Default pattern: '" . $fmt->getPattern() . "'\n";
echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";

$fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
echo "New pattern: '" . $fmt->getPattern() . "'\n";
echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
?>

上の例の出力は以下となります。

Default pattern: '{0,number} monkeys on {1,number} trees'
Formatting result: 123 monkeys on 456 trees
New pattern: '{0,number} trees hosting {1,number} monkeys'
Formatted number: 123 trees hosting 456 monkeys

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_set_pattern() - フォーマッタが使用するパターンを設定する


パターンを使用して入力文字列をパースする

  • ≪ MessageFormatter::getPattern
  • MessageFormatter::parseMessage ≫
  • PHP Manual
  • MessageFormatter
  • パターンを使用して入力文字列をパースする

MessageFormatter::parse

msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — パターンを使用して入力文字列をパースする

説明

オブジェクト指向型

public MessageFormatter::parse(string $string): array|false

手続き型

msgfmt_parse(MessageFormatter $formatter, string $string): array|false

入力文字列をパースし、取り出した項目を配列で返します。

パラメータ

formatter

メッセージのフォーマッタ。

string

パースする文字列。

戻り値

取り出した項目を含む配列を返します。 エラーが発生した場合は false を返します。

例

例1 msgfmt_parse() の例

<?php
$fmt = msgfmt_create('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
$res = msgfmt_parse($fmt, "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($res);

$fmt = msgfmt_create('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
$res = msgfmt_parse($fmt, "4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($res);
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
$res = $fmt->parse("4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($res);

$fmt = new MessageFormatter('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum");
$res = $fmt->parse("4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($res);
?>

上の例の出力は以下となります。

array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)
array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_format() - メッセージをフォーマットする
  • msgfmt_parse_message() - 手早く入力文字列をパースする


手早く入力文字列をパースする

  • ≪ MessageFormatter::parse
  • MessageFormatter::setPattern ≫
  • PHP Manual
  • MessageFormatter
  • 手早く入力文字列をパースする

MessageFormatter::parseMessage

msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — 手早く入力文字列をパースする

説明

オブジェクト指向型

public static MessageFormatter::parseMessage(string $locale, string $pattern, string $message): array|false

手続き型

msgfmt_parse_message(string $locale, string $pattern, string $message): array|false

明示的にフォーマッタオブジェクトを作成せずに、 手早く入力文字列をパースします。 この関数を使用するのは、 一度きりのフォーマット処理であってパラメータや状態を保持する必要がない場合です。

パラメータ

locale

ロケールに依存する部分をパースする際に使用するロケール。

pattern

message のパースに使うパターン。

message

パースする文字列。pattern を満たします。

戻り値

取り出した項目を含む配列を返します。 エラーが発生した場合は false を返します。

例

例1 msgfmt_parse_message() の例

<?php
$fmt = msgfmt_parse_message('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
"4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($fmt);

$fmt = msgfmt_parse_message('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum",
"4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
"4,560 monkeys on 123 trees make 37.073 monkeys per tree");
var_export($fmt);

$fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen auf {1,number,integer} Baumen sind {2,number} Affen pro Baum",
"4.560 Affen auf 123 Baumen sind 37,073 Affen pro Baum");
var_export($fmt);
?>

上の例の出力は以下となります。

array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)
array (
  0 => 4560,
  1 => 123,
  2 => 37.073,
)

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_format_message() - 手早くメッセージをフォーマットする
  • msgfmt_parse() - パターンを使用して入力文字列をパースする


フォーマッタが使用するパターンを設定する

  • ≪ MessageFormatter::parseMessage
  • IntlCalendar ≫
  • PHP Manual
  • MessageFormatter
  • フォーマッタが使用するパターンを設定する

MessageFormatter::setPattern

msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — フォーマッタが使用するパターンを設定する

説明

オブジェクト指向型

public MessageFormatter::setPattern(string $pattern): bool

手続き型

msgfmt_set_pattern(MessageFormatter $formatter, string $pattern): bool

フォーマッタが使用するパターンを設定します。

パラメータ

formatter

メッセージのフォーマッタ。

pattern

このメッセージフォーマッタで使用するパターン文字列。 パターンには、'アポストロフィに優しい' 構文を使用します。 詳細は » Quoting/Escaping を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 msgfmt_set_pattern() の例

<?php
$fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
?>

例2 オブジェクト指向の例

<?php
$fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
echo "Default pattern: '" . $fmt->getPattern() . "'\n";
echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";

$fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
echo "New pattern: '" . $fmt->getPattern() . "'\n";
echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
?>

上の例の出力は以下となります。

Default pattern: '{0,number} monkeys on {1,number} trees'
Formatting result: 123 monkeys on 456 trees
New pattern: '{0,number} trees hosting {1,number} monkeys'
Formatted number: 123 trees hosting 456 monkeys

参考

  • msgfmt_create() - 新しいメッセージフォーマッタを作成する
  • msgfmt_get_pattern() - フォーマッタが使用するパターンを取得する


IntlCalendar クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

はじめに

クラス概要

class IntlCalendar {
/* 定数 */
public const int FIELD_ERA;
public const int FIELD_YEAR;
public const int FIELD_MONTH;
public const int FIELD_WEEK_OF_YEAR;
public const int FIELD_WEEK_OF_MONTH;
public const int FIELD_DATE;
public const int FIELD_DAY_OF_YEAR;
public const int FIELD_DAY_OF_WEEK;
public const int FIELD_DAY_OF_WEEK_IN_MONTH;
public const int FIELD_AM_PM;
public const int FIELD_HOUR;
public const int FIELD_HOUR_OF_DAY;
public const int FIELD_MINUTE;
public const int FIELD_SECOND;
public const int FIELD_MILLISECOND;
public const int FIELD_ZONE_OFFSET;
public const int FIELD_DST_OFFSET;
public const int FIELD_YEAR_WOY;
public const int FIELD_DOW_LOCAL;
public const int FIELD_EXTENDED_YEAR;
public const int FIELD_JULIAN_DAY;
public const int FIELD_MILLISECONDS_IN_DAY;
public const int FIELD_IS_LEAP_MONTH;
public const int FIELD_FIELD_COUNT;
public const int FIELD_DAY_OF_MONTH;
public const int DOW_SUNDAY;
public const int DOW_MONDAY;
public const int DOW_TUESDAY;
public const int DOW_WEDNESDAY;
public const int DOW_THURSDAY;
public const int DOW_FRIDAY;
public const int DOW_SATURDAY;
public const int DOW_TYPE_WEEKDAY;
public const int DOW_TYPE_WEEKEND;
public const int DOW_TYPE_WEEKEND_OFFSET;
public const int DOW_TYPE_WEEKEND_CEASE;
public const int WALLTIME_FIRST;
public const int WALLTIME_LAST;
public const int WALLTIME_NEXT_VALID;
/* メソッド */
private __construct()
public add(int $field, int $value): bool
public after(IntlCalendar $other): bool
public before(IntlCalendar $other): bool
public clear(?int $field = null): true
public static createInstance(IntlTimeZone|DateTimeZone|string|null $timezone = null, ?string $locale = null): ?IntlCalendar
public equals(IntlCalendar $other): bool
public fieldDifference(float $timestamp, int $field): int|false
public static fromDateTime(DateTime|string $datetime, ?string $locale = null): ?IntlCalendar
public get(int $field): int|false
public getActualMaximum(int $field): int|false
public getActualMinimum(int $field): int|false
public static getAvailableLocales(): array
public getDayOfWeekType(int $dayOfWeek): int|false
public getErrorCode(): int|false
public getErrorMessage(): string|false
public getFirstDayOfWeek(): int|false
public getGreatestMinimum(int $field): int|false
public static getKeywordValuesForLocale(string $keyword, string $locale, bool $onlyCommon): IntlIterator|false
public getLeastMaximum(int $field): int|false
public getLocale(int $type): string|false
public getMaximum(int $field): int|false
public getMinimalDaysInFirstWeek(): int|false
public getMinimum(int $field): int|false
public static getNow(): float
public getRepeatedWallTimeOption(): int
public getSkippedWallTimeOption(): int
public getTime(): float|false
public getTimeZone(): IntlTimeZone|false
public getType(): string
public getWeekendTransition(int $dayOfWeek): int|false
public inDaylightTime(): bool
public isEquivalentTo(IntlCalendar $other): bool
public isLenient(): bool
public isSet(int $field): bool
public isWeekend(?float $timestamp = null): bool
public roll(int $field, int|bool $value): bool
public set(int $field, int $value): true
public set(
int $year,
int $month,
int $dayOfMonth = NULL,
int $hour = NULL,
int $minute = NULL,
int $second = NULL
): true
public setDate(int $year, int $month, int $dayOfMonth): void
public setDateTime(
int $year,
int $month,
int $dayOfMonth,
int $hour,
int $minute,
?int $second = null
): void
public setFirstDayOfWeek(int $dayOfWeek): true
public setLenient(bool $lenient): true
public setMinimalDaysInFirstWeek(int $days): true
public setRepeatedWallTimeOption(int $option): true
public setSkippedWallTimeOption(int $option): true
public setTime(float $timestamp): bool
public setTimeZone(IntlTimeZone|DateTimeZone|string|null $timezone): bool
public toDateTime(): DateTime|false
}

定義済み定数

IntlCalendar::FIELD_ERA

カレンダーのフィールドで、時代を表す数値です。たとえば、グレゴリオ暦やユリウス暦の場合は 1 が紀元後そして 0 が紀元前を表します。 また、和暦の場合は 235 が平成を表します。 すべてのカレンダーが複数の時代を持つわけではありません。

IntlCalendar::FIELD_YEAR

カレンダーの、年を表すフィールド。時代が違えば同じ数字になることもあります。 そのカレンダー型が複数の時代を持っている場合は、このフィールドの最小値は通常は 1 になります。

IntlCalendar::FIELD_MONTH

カレンダーの、月を表すフィールド。月番号はゼロからはじまるので、1月が 0、2月が 1、...そして12月が 11 となります。13番目の月あるいはうるう月があるカレンダーの場合は、12 で表します。

IntlCalendar::FIELD_WEEK_OF_YEAR

カレンダーの、年内の週番号を表すフィールド。 これは、何曜日を週の開始日とみなすか、そして週の最小日数は何日かによって決まります。

IntlCalendar::FIELD_WEEK_OF_MONTH

カレンダーの、月内の週番号を表すフィールド。 これは、何曜日を週の開始日とみなすか、そして週の最小日数は何日かによって決まります。

IntlCalendar::FIELD_DATE

カレンダーの、月内の日数を表すフィールド。 IntlCalendar::FIELD_DAY_OF_MONTH と同じで、こちらのほうがよりわかりやすい名前です。

IntlCalendar::FIELD_DAY_OF_YEAR

カレンダーの、年内の日数を表すフィールド。 グレゴリオ暦の場合は、1 から始まって 365 あるいは 366 で終わります。

IntlCalendar::FIELD_DAY_OF_WEEK

カレンダーの、曜日を表すフィールド。 最初の値は 1 (日曜日。 IntlCalendar::DOW_SUNDAY とそれに続く定数を参照ください) で、有効な最後の値は 7 (土曜日) です。

IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH

曜日 (日曜日、月曜日、...) を指定されたときに、このフィールドには当月内でその曜日が何番目に登場するのかを代入します。 つまり、このフィールドの値が 1 で曜日番号が 2 (月曜日) だったとすると、 当月の第一月曜日の日付が設定されます。 最大値は 5 です。

さらに、0 や負の数も使えます。 0 は、ある月の最初の (day of week in month の値が 1 となる) 七日間の直前の七日間を表します。 負の値を指定した場合は、月末から数えます。-1 は、その曜日が当月の最後に登場する日付、 -2 はさらにその一週間前といったようになります。

IntlCalendar::FIELD_WEEK_OF_MONTH や IntlCalendar::FIELD_WEEK_OF_YEAR とは異なり、この値は IntlCalendar::getFirstDayOfWeek() や IntlCalendar::getMinimalDaysInFirstWeek() に依存しません。 第一月曜日は第一月曜日であり、たとえ前月に属する日であってもそれは変わりません。

IntlCalendar::FIELD_AM_PM

カレンダーの、午前 (0) か午後 (1) かを表すフィールド。 深夜 0 時は午前、正午は午後となります。

IntlCalendar::FIELD_HOUR

カレンダーの、時間を表すフィールド。午前か午後かは含みません。 有効な値は 0 から 11 までです。

IntlCalendar::FIELD_HOUR_OF_DAY

カレンダーの、24 時間制の時間を表すフィールド。 有効な値は 0 から 23 までです。

IntlCalendar::FIELD_MINUTE

カレンダーの、分を表すフィールド。

IntlCalendar::FIELD_SECOND

カレンダーの、秒を表すフィールド。

IntlCalendar::FIELD_MILLISECOND

カレンダーの、ミリ秒を表すフィールド。

IntlCalendar::FIELD_ZONE_OFFSET

カレンダーの、タイムゾーンのオフセットをミリ秒で表すフィールド。 夏時間によるオフセットは含みません。

IntlCalendar::FIELD_DST_OFFSET

カレンダーの、夏時間によるオフセットをミリ秒で表すフィールド。 夏時間を採用しているタイムゾーンの場合に使います。

IntlCalendar::FIELD_YEAR_WOY

カレンダーの、week of year 用の年を表すフィールド。

IntlCalendar::FIELD_DOW_LOCAL

カレンダーの、ローカライズした曜日を表すフィールド。 1 から 7 までの値となり、 1 は IntlCalendar::getFirstDayOfWeek() が返す値にマッチする曜日に使います。

IntlCalendar::FIELD_EXTENDED_YEAR

カレンダーの、年番号を表すフィールド。この番号は、時代をまたがって続きます。 グレゴリオ暦の場合、紀元後の年についてはこの値は IntlCalendar::FIELD_YEAR に一致します。 紀元前 y 年の場合は -y + 1 となります。

IntlCalendar::FIELD_JULIAN_DAY

カレンダーの、ユリウス日を表すフィールド。 一般的な慣習とは違って、このユリウス日は現地時間の深夜 0 時に加算されます。 UTC の正午ではありません。 これで、日付を一意に特定します。

IntlCalendar::FIELD_MILLISECONDS_IN_DAY

カレンダーの、 IntlCalendar::FIELD_HOUR_OF_DAY や IntlCalendar::FIELD_MINUTE、 IntlCalendar::FIELD_SECOND、そして IntlCalendar::FIELD_MILLISECOND の情報をまとめたフィールド。 0 から 24 * 3600 * 1000 - 1 までの値となります。この値は、その日の中での経過ミリ秒数ではありません。 というのも、夏時間への移行を挟む場合はこの値は連続した値にならないからです。

IntlCalendar::FIELD_IS_LEAP_MONTH

カレンダーのフィールドで、値が 1 のときはうるう月、 0 の場合はそうでないことを表します。

IntlCalendar::FIELD_FIELD_COUNT

フィールドの総数。

IntlCalendar::FIELD_DAY_OF_MONTH

IntlCalendar::FIELD_DATE のエイリアス。

IntlCalendar::DOW_SUNDAY

日曜日。

IntlCalendar::DOW_MONDAY

月曜日。

IntlCalendar::DOW_TUESDAY

火曜日。

IntlCalendar::DOW_WEDNESDAY

水曜日。

IntlCalendar::DOW_THURSDAY

木曜日。

IntlCalendar::DOW_FRIDAY

金曜日。

IntlCalendar::DOW_SATURDAY

土曜日。

IntlCalendar::DOW_TYPE_WEEKDAY

平日であることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::DOW_TYPE_WEEKEND

週末であることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::DOW_TYPE_WEEKEND_OFFSET

指定した曜日から週末が始まることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::DOW_TYPE_WEEKEND_CEASE

指定した曜日で週末が終わることを示す IntlCalendar::getDayOfWeekType() の出力。

IntlCalendar::WALLTIME_FIRST

スキップした範囲内の実測時間が一時間前の実測時間と同じ瞬間を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。 また、繰り返した範囲内の実測時間がその最初のほうを指すことを示す IntlCalendar::getRepeatedWallTimeOption() の出力。

IntlCalendar::WALLTIME_LAST

スキップした範囲内の実測時間が一時間後の実測時間と同じ瞬間を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。 また、繰り返した範囲内の実測時間がその二番目のほうを指すことを示す IntlCalendar::getRepeatedWallTimeOption() の出力。

IntlCalendar::WALLTIME_NEXT_VALID

スキップした範囲内の実測時間が夏時間への移行 (開始) を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。

目次

  • IntlCalendar::add — フィールドに (符号付きの) 一定量の時間を追加する
  • IntlCalendar::after — このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する
  • IntlCalendar::before — このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する
  • IntlCalendar::clear — 単一または全てのフィールドをクリアする
  • IntlCalendar::__construct — インスタンス化を禁止するための private なコンストラクタ
  • IntlCalendar::createInstance — 新しい IntlCalendar を作成する
  • IntlCalendar::equals — ふたつの IntlCalendar オブジェクトの時刻を比較する
  • IntlCalendar::fieldDifference — 指定された時刻と、このオブジェクトの時刻の差を計算する
  • IntlCalendar::fromDateTime — DateTime オブジェクトまたは文字列から、IntlCalendar を作成する
  • IntlCalendar::get — フィールドの値を取得する
  • IntlCalendar::getActualMaximum — オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する
  • IntlCalendar::getActualMinimum — オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する
  • IntlCalendar::getAvailableLocales — データが存在するロケールの配列を取得する
  • IntlCalendar::getDayOfWeekType — 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す
  • IntlCalendar::getErrorCode — オブジェクトに関する直近のエラーコードを取得する
  • IntlCalendar::getErrorMessage — オブジェクトの直近のエラーメッセージを取得する
  • IntlCalendar::getFirstDayOfWeek — カレンダーのロケールに基づいて、週の始めの日を返す
  • IntlCalendar::getGreatestMinimum — 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す
  • IntlCalendar::getKeywordValuesForLocale — ロケールのキーワードの値の集合を返す
  • IntlCalendar::getLeastMaximum — 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す
  • IntlCalendar::getLocale — オブジェクトに関連付けられたロケールを取得する
  • IntlCalendar::getMaximum — フィールドのグローバルな最大値を返す
  • IntlCalendar::getMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を返す
  • IntlCalendar::getMinimum — フィールドのグローバルな最小値を返す
  • IntlCalendar::getNow — 現在時刻を示す数値を取得する
  • IntlCalendar::getRepeatedWallTimeOption — 繰り返される実時間を扱う際の振る舞いを取得する
  • IntlCalendar::getSkippedWallTimeOption — スキップされた実時間を扱う際の振る舞いを取得する
  • IntlCalendar::getTime — このオブジェクトが表す時刻を取得する
  • IntlCalendar::getTimeZone — オブジェクトのタイムゾーンを取得する
  • IntlCalendar::getType — カレンダーのタイプを取得する
  • IntlCalendar::getWeekendTransition — 週末が開始/終了した日からの経過時間を取得する
  • IntlCalendar::inDaylightTime — オブジェクトの時刻が夏時間かを調べる
  • IntlCalendar::isEquivalentTo — 別のカレンダーが、時刻を除いて等しいかを調べる
  • IntlCalendar::isLenient — 日付と時刻の解釈を「緩いモード」で行うかを取得する
  • IntlCalendar::isSet — フィールドが設定されているかを調べる
  • IntlCalendar::isWeekend — ある日付/時刻が週末にあるかを調べる
  • IntlCalendar::roll — 次のフィールドを繰り上げずに、フィールドに値を加算する
  • IntlCalendar::set — 時刻または複数の共通フィールドを一度に設定する
  • IntlCalendar::setDate — 日付のフィールドを設定する
  • IntlCalendar::setDateTime — 日付と時刻のフィールドを設定する
  • IntlCalendar::setFirstDayOfWeek — 週の始まりと見なされる曜日を設定する
  • IntlCalendar::setLenient — 日付/時刻の解釈を「緩いモード」にするかを設定する
  • IntlCalendar::setMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を設定する
  • IntlCalendar::setRepeatedWallTimeOption — 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する
  • IntlCalendar::setSkippedWallTimeOption — 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する
  • IntlCalendar::setTime — エポックからのカレンダーの時刻をミリ秒単位で設定する
  • IntlCalendar::setTimeZone — このカレンダーで使うタイムゾーンを設定する
  • IntlCalendar::toDateTime — IntlCalendar を DateTime オブジェクトに変換する


フィールドに (符号付きの) 一定量の時間を追加する

  • ≪ IntlCalendar
  • IntlCalendar::after ≫
  • PHP Manual
  • IntlCalendar
  • フィールドに (符号付きの) 一定量の時間を追加する

IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — フィールドに (符号付きの) 一定量の時間を追加する

説明

オブジェクト指向型

public IntlCalendar::add(int $field, int $value): bool

手続き型

intlcal_add(IntlCalendar $calendar, int $field, int $value): bool

フィールドに符号付きの量を追加します。 正の量を追加すると、時間を前に進めることができます。 たとえ、フィールドの数値の値が減るとしても、同じことができます。 (つまり、紀元前の年代を扱っていてもです)

他のフィールドは調整する必要があるかも知れません - たとえば、1月の31日に1ヶ月を足したとします。 そうすると、結果は 2月の28日(または29日) になるでしょう。 IntlCalendar::roll() とは異なり、 値が1周して元に戻る場合、 より重要なフィールドの値が変わる可能性があります。 たとえば、1月31日に1日足すと、1月1日ではなく、 2月1日になります。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

value

現在のフィールドに加算する、符号付きの値。 値が正の場合、 時は前に進みます。負の値の場合、時は過去に遡ります。 前後する単位は、フィールドによって暗黙のうちに決まります。 たとえば、IntlCalendar::FIELD_HOUR_OF_DAY の場合は 1時間単位です。

戻り値

成功時に true を返します。 失敗した場合に false を返します.

例

例1 IntlCalendar::add()

<?php
ini_set('intl.default_locale', 'fr_FR');
ini_set('date.timezone', 'UTC');

$cal = new IntlGregorianCalendar(2012, 0 /* January */, 31);
echo IntlDateFormatter::formatObject($cal), "\n";

$cal->add(IntlCalendar::FIELD_MONTH, 1);
echo IntlDateFormatter::formatObject($cal), "\n";

$cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
echo IntlDateFormatter::formatObject($cal), "\n";

上の例の出力は以下となります。

31 janv. 2012 00:00:00
29 fevr. 2012 00:00:00
1 mars 2012 00:00:00


このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する

  • ≪ IntlCalendar::add
  • IntlCalendar::before ≫
  • PHP Manual
  • IntlCalendar
  • このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する

IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する

説明

オブジェクト指向型

public IntlCalendar::after(IntlCalendar $other): bool

手続き型

intlcal_after(IntlCalendar $calendar, IntlCalendar $other): bool

このオブジェクトの時刻が、 指定されたオブジェクトの時刻より未来かを返します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

other

このカレンダーオブジェクトの時刻が、 最初のオブジェクトの時刻と比較されます。

戻り値

このオブジェクトの現在時刻が、 calendar の時刻より後の場合に true を返します。 そうでない場合、false を返します。

失敗時に false を返します。エラーを検知するには、intl_get_error_code() を使うか、 Intl拡張モジュールが 例外 をスローするように設定して下さい。

例

例1 IntlCalendar::after()

<?php
$cal1 = IntlCalendar::createInstance();
$cal2 = clone $cal1;

var_dump($cal1->after($cal2), //false
$cal2->after($cal1)); //false

$cal1->roll(IntlCalendar::FIELD_MILLISECOND, true);

var_dump($cal1->after($cal2), //true
$cal2->after($cal1)); //false


このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する

  • ≪ IntlCalendar::after
  • IntlCalendar::clear ≫
  • PHP Manual
  • IntlCalendar
  • このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する

IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する

説明

オブジェクト指向型

public IntlCalendar::before(IntlCalendar $other): bool

手続き型

intlcal_before(IntlCalendar $calendar, IntlCalendar $other): bool

このオブジェクトの時刻が、 指定されたオブジェクトの時刻よりより過去かを判定して返します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

other

このカレンダーオブジェクトの時刻が、 最初のオブジェクトの時刻と比較されます。

戻り値

このオブジェクトの現在時刻が、 calendar の時刻より前の場合に true を返します。 そうでない場合、false を返します。

失敗時に false を返します。エラーを検知するには、intl_get_error_code() を使うか、 Intl拡張モジュールが 例外 をスローするように設定して下さい。


単一または全てのフィールドをクリアする

  • ≪ IntlCalendar::before
  • IntlCalendar::__construct ≫
  • PHP Manual
  • IntlCalendar
  • 単一または全てのフィールドをクリアする

IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — 単一または全てのフィールドをクリアする

説明

オブジェクト指向型

public IntlCalendar::clear(?int $field = null): true

手続き型

intlcal_clear(IntlCalendar $calendar, ?int $field = null): true

全てのフィールドか、特定のフィールドをクリアします。 クリアされたフィールドは、未設定とマークされ、 時刻の計算時にフィールドが重複した場合の優先度が低くなるか、 デフォルト値に設定されます。 さらに、値に 0 が設定されると、 与えられたフィールドの優先度が低くなることに加えて、 フィールドへの問い合わせが終わるまで、 内部的に別の値に設定される可能性があります。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 IntlCalendar::clear() の例

<?php
ini_set('intl.default_locale', 'es_ES');
ini_set('date.timezone', 'UTC');

$fields = array(
'FIELD_ERA' => 0,
'FIELD_YEAR' => 1,
'FIELD_MONTH' => 2,
'FIELD_WEEK_OF_YEAR' => 3,
'FIELD_WEEK_OF_MONTH' => 4,
'FIELD_DATE' => 5,
'FIELD_DAY_OF_YEAR' => 6,
'FIELD_DAY_OF_WEEK' => 7,
'FIELD_DAY_OF_WEEK_IN_MONTH' => 8,
'FIELD_AM_PM' => 9,
'FIELD_HOUR' => 10,
'FIELD_HOUR_OF_DAY' => 11,
'FIELD_MINUTE' => 12,
'FIELD_SECOND' => 13,
'FIELD_MILLISECOND' => 14,
'FIELD_ZONE_OFFSET' => 15,
'FIELD_DST_OFFSET' => 16,
'FIELD_YEAR_WOY' => 17,
'FIELD_DOW_LOCAL' => 18,
'FIELD_EXTENDED_YEAR' => 19,
'FIELD_JULIAN_DAY' => 20,
'FIELD_MILLISECONDS_IN_DAY' => 21,
'FIELD_IS_LEAP_MONTH' => 22,
'FIELD_FIELD_COUNT' => 23,
);
function getSetFields(IntlCalendar $cal) {
global $fields;
$ret = array();
foreach ($fields as $name => $value) {
if ($cal->isSet($value)) {
$ret[] = $name;
}
}
return $ret;
}

$cal = new IntlGregorianCalendar(2013, 2 /* March */, 15);
echo "After GregorianCalendar creation\n";
print_r(getSetFields($cal));
echo "\n";

echo IntlDateFormatter::formatObject($cal), "\n";
echo "After the formatter requested the extended year\n";
print_r(getSetFields($cal));
echo "\n";

$cal->clear(IntlCalendar::FIELD_YEAR);
echo "After the year has been cleared, the date stays the same\n";
echo IntlDateFormatter::formatObject($cal), "\n";
echo "because FIELD_EXTENDED_YEAR is still set\n";
print_r(getSetFields($cal));
echo "\n";

var_dump($cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR));
echo "After the extended year has been cleared\n";
print_r(getSetFields($cal));
echo IntlDateFormatter::formatObject($cal), "\n";
echo "\n";

echo "After the fields are recalculated,\n"
. " extended year is set again (to 1970)\n";
print_r(getSetFields($cal));
echo "\n";

$cal->clear();
echo "After calling variant with no arguments\n";
print_r(getSetFields($cal));
echo IntlDateFormatter::formatObject($cal), "\n";

上の例の出力は以下となります。

After GregorianCalendar creation
Array
(
    [0] => FIELD_ERA
    [1] => FIELD_YEAR
    [2] => FIELD_MONTH
    [3] => FIELD_DATE
)

15/03/2013 00:00:00
After the formatter requested the extended year
Array
(
    [0] => FIELD_ERA
    [1] => FIELD_YEAR
    [2] => FIELD_MONTH
    [3] => FIELD_DATE
    [4] => FIELD_EXTENDED_YEAR
)

After the year has been cleared, the date stays the same
15/03/2013 00:00:00
because FIELD_EXTENDED_YEAR is still set
Array
(
    [0] => FIELD_ERA
    [1] => FIELD_MONTH
    [2] => FIELD_DATE
    [3] => FIELD_EXTENDED_YEAR
)

bool(true)
After the extended year has been cleared
Array
(
    [0] => FIELD_ERA
    [1] => FIELD_MONTH
    [2] => FIELD_DATE
)
15/03/1970 00:00:00

After the fields are recalculated,
 extended year is set again (to 1970)
Array
(
    [0] => FIELD_ERA
    [1] => FIELD_MONTH
    [2] => FIELD_DATE
    [3] => FIELD_EXTENDED_YEAR
)

After calling variant with no arguments
Array
(
)
01/01/1970 00:00:00


インスタンス化を禁止するための private なコンストラクタ

  • ≪ IntlCalendar::clear
  • IntlCalendar::createInstance ≫
  • PHP Manual
  • IntlCalendar
  • インスタンス化を禁止するための private なコンストラクタ

IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — インスタンス化を禁止するための private なコンストラクタ

説明

private IntlCalendar::__construct()

new 演算子によるインスタンス化を>拒否するために用意された、 private なコンストラクタです。

IntlCalendar::createInstance() をコールして下さい。

パラメータ

この関数にはパラメータはありません。


新しい IntlCalendar を作成する

  • ≪ IntlCalendar::__construct
  • IntlCalendar::equals ≫
  • PHP Manual
  • IntlCalendar
  • 新しい IntlCalendar を作成する

IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — 新しい IntlCalendar を作成する

説明

オブジェクト指向型

public static IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null $timezone = null, ?string $locale = null): ?IntlCalendar

手続き型

intlcal_create_instance(IntlTimeZone|DateTimeZone|string|null $timezone = null, ?string $locale = null): ?IntlCalendar

指定されたタイムゾーンとロケールを使い、 IntlCalendar を作成します。 このファクトリメソッドは IntlCalendar のサブクラスを返す可能性があります。

作成されたカレンダーオブジェクトは、 システムの時刻を基準とした、作成時点の時刻を表すインスタンスです。 フィールドは IntCalendar::clear() を引数なしでコールすることですべてクリアできます。 IntlGregorianCalendar::__construct() も参照ください。

パラメータ

timezone

使用するタイムゾーン。

  • null。この場合はデフォルトのタイムゾーンを使います。デフォルトは、ini 項目 date.timezone で設定したものか、 date_default_timezone_set() 関数で指定したもの (そして date_default_timezone_get() が返すもの) になります。

  • IntlTimeZone。これを直接使います。

  • DateTimeZone。その識別子を取り出して、ICU タイムゾーンオブジェクトを作ります。 つまり、これは ICU のデータベースに基づくタイムゾーンとなり、PHP のタイムゾーンデータベースに基づくものではありません。

  • 文字列。ICU タイムゾーン識別子として有効なものを指定します。 IntlTimeZone::createTimeZoneIDEnumeration() を参照ください。 "GMT+08:30" などのオフセットも指定できます。

locale

使用するロケール。 null の場合は、 デフォルトのロケール を使います。

戻り値

IntlCalendar のインスタンスを返します。 失敗時に null を返します。

例

例1 IntlCalendar::createInstance()

<?php
ini_set('intl.default_locale', 'es_ES');
ini_set('date.timezone', 'Europe/Madrid');

$cal = IntlCalendar::createInstance();
echo "No arguments\n";
var_dump(get_class($cal),
IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
echo "\n";

echo "Explicit timezone\n";
$cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
var_dump(get_class($cal),
IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
echo "\n";

echo "Explicit locale (with calendar)\n";
$cal = IntlCalendar::createInstance(NULL, 'es_ES@calendar=persian');
var_dump(get_class($cal),
IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));

上の例の出力は以下となります。

No arguments
string(21) "IntlGregorianCalendar"
string(68) "martes 18 de junio de 2013 14:11:02 Hora de verano de Europa Central"

Explicit timezone
string(21) "IntlGregorianCalendar"
string(45) "martes 18 de junio de 2013 12:11:02 GMT+00:00"

Explicit locale (with calendar)
string(12) "IntlCalendar"
string(70) "martes 28 de Khordad de 1392 14:11:02 Hora de verano de Europa Central"

参考

  • IntlGregorianCalendar::__construct() - グレゴリオ暦の Calendar クラスを作成する


ふたつの IntlCalendar オブジェクトの時刻を比較する

  • ≪ IntlCalendar::createInstance
  • IntlCalendar::fieldDifference ≫
  • PHP Manual
  • IntlCalendar
  • ふたつの IntlCalendar オブジェクトの時刻を比較する

IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — ふたつの IntlCalendar オブジェクトの時刻を比較する

説明

オブジェクト指向型

public IntlCalendar::equals(IntlCalendar $other): bool

手続き型

intlcal_equals(IntlCalendar $calendar, IntlCalendar $other): bool

このカレンダーオブジェクトと、 指定されたカレンダーオブジェクトの時刻が同じなら、true を返します。 カレンダーの型とフィールドの状態は、必ずしも同じである必要はありません。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

other

比較対象のカレンダーオブジェクト。

戻り値

このカレンダーオブジェクトと、 渡された IntlCalendar の時刻が同じな場合、 true を返します。 そうでない場合、false を返します。

失敗時に false を返します。エラーを検知するには、intl_get_error_code() を使うか、 Intl拡張モジュールが 例外 をスローするように設定して下さい。

例

例1 IntlCalendar::equals()

<?php
ini_set('date.timezone', 'UTC');

$cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
$cal2 = clone $cal1;

var_dump($cal1->equals($cal2)); //TRUE

//The locale is not included in the comparison
$cal2 = IntlCalendar::createInstance(NULL, 'pt_PT');
$cal2->setTime($cal1->getTime());
var_dump($cal1->equals($cal2)); //TRUE

//And set fields state is not included as well
$cal2->clear(IntlCalendar::FIELD_YEAR);
var_dump($cal1->isSet(IntlCalendar::FIELD_YEAR) ==
$cal2->isSet(IntlCalendar::FIELD_YEAR)); //FALSE
var_dump($cal1->equals($cal2)); //TRUE

//Neither is the calendar type
$cal2 = IntlCalendar::createInstance(NULL, 'es_ES@calendar=islamic');
$cal2->setTime($cal1->getTime());
var_dump($cal1->equals($cal2)); //TRUE

//Only the time is
$cal2 = clone $cal1;
$cal2->setTime($cal1->getTime() + 1.);
var_dump($cal1->equals($cal2)); //FALSE


指定された時刻と、このオブジェクトの時刻の差を計算する

  • ≪ IntlCalendar::equals
  • IntlCalendar::fromDateTime ≫
  • PHP Manual
  • IntlCalendar
  • 指定された時刻と、このオブジェクトの時刻の差を計算する

IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — 指定された時刻と、このオブジェクトの時刻の差を計算する

説明

オブジェクト指向型

public IntlCalendar::fieldDifference(float $timestamp, int $field): int|false

手続き型

intlcal_field_difference(IntlCalendar $calendar, float $timestamp, int $field): int|false

field に設定された量も考慮して、 指定された時刻と、このオブジェクトに設定された時刻の差を返します。

このメソッドは連続して呼び出すものです。 最初は、関心のある重要なフィールドからはじめ、 もっとも関心が薄いフィールドへと続きます。 最終的な副作用として、 このカレンダーの指定されたフィールドの値が、 返される量だけ進みます。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

timestamp

field が表す、比較する時刻の量。 結果を正の値にするには、 この引数で指定する値を、 このメソッドを呼び出すオブジェクトの時刻よりも、 未来に設定しなければいけません。

field

比較される量を表すフィールド。

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

Returns a (signed) difference of time in the unit associated with the specified field失敗した場合に false を返します.

例

例1 IntlCalendar::fieldDifference()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'fr_FR');

$cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
$cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
$time = $cal2->getTime();

echo "Time before: ", IntlDateFormatter::formatObject($cal1), "\n";

printf(
"The difference in time is %d year(s), %d month(s), "
. "%d day(s), %d hour(s) and %d minute(s)\n",
$cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
$cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
$cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
$cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
$cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
);

//now it was advanced to the target time, exception for the seconds,
//for which we did not measure the difference
echo "Time after: ", IntlDateFormatter::formatObject($cal1), "\n";

上の例の出力は以下となります。

Time before: 29 fevr. 2012 09:00:11
The difference in time is 1 year(s), 0 month(s), 1 day(s), 0 hour(s) and 19 minute(s)
Time after: 1 mars 2013 09:19:11


DateTime オブジェクトまたは文字列から、IntlCalendar を作成する

  • ≪ IntlCalendar::fieldDifference
  • IntlCalendar::get ≫
  • PHP Manual
  • IntlCalendar
  • DateTime オブジェクトまたは文字列から、IntlCalendar を作成する

IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — DateTime オブジェクトまたは文字列から、IntlCalendar を作成する

説明

オブジェクト指向型

public static IntlCalendar::fromDateTime(DateTime|string $datetime, ?string $locale = null): ?IntlCalendar

手続き型

intlcal_from_date_time(DateTime|string $datetime, ?string $locale = null): ?IntlCalendar

DateTime オブジェクト または、 DateTime オブジェクトを作成できる文字列から、 IntlCalendar を生成します。

新しいカレンダーオブジェクトは、 指定された DateTime と同じ瞬間 (とても遠い過去または未来の日付の場合、精度が失われることがあります) を表すだけでなく、 同じタイムゾーンも保持します。 (但し、異なるタイムゾーンのデータベースを使った場合、 結果が異なる場合があることにも注意して下さい)

パラメータ

datetime

DateTime オブジェクト または、 DateTime::__construct() に渡すことができる文字列。

戻り値

IntlCalendar オブジェクトを返します。失敗した場合は null を返します。 文字列を渡した場合、 DateTime のコンストラクタから伝播する形で、 例外がスローされる可能性があります。

例

例1 IntlCalendar::fromDateTime()

<?php
ini_set('date.timezone', 'Europe/Lisbon');

//same as IntlCalendar::fromDateTime(new DateTime(...))
$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin');

//Note the timezone is Europe/Berlin, not the default Europe/Lisbon
echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

上の例の出力は以下となります。

2013 Februar 28 00:01:02 Deutschland Zeit


フィールドの値を取得する

  • ≪ IntlCalendar::fromDateTime
  • IntlCalendar::getActualMaximum ≫
  • PHP Manual
  • IntlCalendar
  • フィールドの値を取得する

IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — フィールドの値を取得する

説明

オブジェクト指向型

public IntlCalendar::get(int $field): int|false

手続き型

intlcal_get(IntlCalendar $calendar, int $field): int|false

指定されたフィールドの値を取得します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

指定された時刻フィールドの値を数値で返します。

例

例1 IntlCalendar::get()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'en_US');

$class = new ReflectionClass('IntlCalendar');
$fields = array();
foreach ($class->getConstants() as $name => $val) {
if (strpos($name, 'FIELD_') !== 0 || $val > 22)
continue;
$fields[$val] = $name;
}

$cal = IntlCalendar::createInstance(); // current time
var_dump(IntlDateFormatter::formatObject($cal));
foreach ($fields as $val => $name) {
echo "$val ($name)", "\n ", $cal->get($val), "\n";
}

上の例の出力は以下となります。

string(23) "Jul 1, 2013, 4:44:44 AM"
0 (FIELD_ERA)
    1
1 (FIELD_YEAR)
    2013
2 (FIELD_MONTH)
    6
3 (FIELD_WEEK_OF_YEAR)
    27
4 (FIELD_WEEK_OF_MONTH)
    1
5 (FIELD_DAY_OF_MONTH)
    1
6 (FIELD_DAY_OF_YEAR)
    182
7 (FIELD_DAY_OF_WEEK)
    2
8 (FIELD_DAY_OF_WEEK_IN_MONTH)
    1
9 (FIELD_AM_PM)
    0
10 (FIELD_HOUR)
    4
11 (FIELD_HOUR_OF_DAY)
    4
12 (FIELD_MINUTE)
    44
13 (FIELD_SECOND)
    44
14 (FIELD_MILLISECOND)
    551
15 (FIELD_ZONE_OFFSET)
    0
16 (FIELD_DST_OFFSET)
    3600000
17 (FIELD_YEAR_WOY)
    2013
18 (FIELD_DOW_LOCAL)
    2
19 (FIELD_EXTENDED_YEAR)
    2013
20 (FIELD_JULIAN_DAY)
    2456475
21 (FIELD_MILLISECONDS_IN_DAY)
    17084551
22 (FIELD_IS_LEAP_MONTH)
    0


オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する

  • ≪ IntlCalendar::get
  • IntlCalendar::getActualMinimum ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する

IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する

説明

オブジェクト指向型

public IntlCalendar::getActualMaximum(int $field): int|false

手続き型

intlcal_get_actual_maximum(IntlCalendar $calendar, int $field): int|false

現在時刻に応じた、フィールドに関連する最大値を返します。 正確なセマンティクスはフィールドによって異なりますが、 一般的な場合、 フィールドの値が 関連する最大値のうち、最小のもの に設定されたとすると、 フィールドの値が グローバルな最大値 に達するか、1周まわって元に戻るまでインクリメントされ、 グローバルな最大値の値か、 元に戻る直前の値がそれぞれ返されます。

たとえば、グレゴリオ暦においては、 実際の 月の日付 の最大値は、 現在時刻の年や月に応じて、 28 から 31 までの異なる値をとります。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

指定された field に関連付けられた単位の最大値を表す数値を返します。 失敗した場合に false を返します

例

例1 IntlCalendar::getActualMaximum()

<?php
ini_set('date.timezone', 'Europe/Lisbon');

$cal = IntlCalendar::fromDateTime('2013-02-15');
var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28

$cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29

上の例の出力は以下となります。

int(28)
int(29)

参考

  • IntlCalendar::getMaximum() - フィールドのグローバルな最大値を返す
  • IntlCalendar::getLeastMaximum() - 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す
  • IntlCalendar::getActualMinimum() - オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する


オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する

  • ≪ IntlCalendar::getActualMaximum
  • IntlCalendar::getAvailableLocales ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する

IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する

説明

オブジェクト指向型

public IntlCalendar::getActualMinimum(int $field): int|false

手続き型

intlcal_get_actual_minimum(IntlCalendar $calendar, int $field): int|false

現在時刻に応じた、フィールドに関連する最小値を返します。 正確なセマンティクスはフィールドによって異なりますが、 一般的な場合、 フィールドの値が 関連する最小値のうち、最大のもの に設定されたとすると、 フィールドの値が グローバルな最小値 に達するか、1周まわって元に戻るまでデクリメントされ、 グローバルな最小値の値か、 元に戻る直前の値がそれぞれ返されます。

グレゴリオ暦の場合は、 常に IntlCalendar::getMinimum() と同じ動きをします。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

指定されたフィールドの単位の最小値を表す数値を返します。 失敗した場合に false を返します

参考

  • IntlCalendar::getMinimum() - フィールドのグローバルな最小値を返す
  • IntlCalendar::getGreatestMinimum() - 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す
  • IntlCalendar::getActualMaximum() - オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する


データが存在するロケールの配列を取得する

  • ≪ IntlCalendar::getActualMinimum
  • IntlCalendar::getDayOfWeekType ≫
  • PHP Manual
  • IntlCalendar
  • データが存在するロケールの配列を取得する

IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — データが存在するロケールの配列を取得する

説明

オブジェクト指向型

public static IntlCalendar::getAvailableLocales(): array

手続き型

intlcal_get_available_locales(): array

カレンダーがインストールされているロケールのリストを返します。 ICU 51 以降では、 インストールされている全ての ICU ロケールのリストになります。

パラメータ

この関数にはパラメータはありません。

戻り値

文字列の配列を返します。 ひとつひとつが、ロケールを示します。

例

例1 IntlCalendar::getAvailableLocales()

<?php
print_r(IntlCalendar::getAvailableLocales());

上の例の出力は以下となります。

Array
(
    [0] => af
    [1] => af_NA
    [2] => af_ZA
    [3] => agq
    [4] => agq_CM
    [5] => ak
    [6] => ak_GH
    [7] => am
    [8] => am_ET
    [9] => ar
    [10] => ar_001
    [11] => ar_AE
    [12] => ar_BH
    [13] => ar_DJ
    ... output abbreviated ...
    [595] => zh_Hant_HK
    [596] => zh_Hant_MO
    [597] => zh_Hant_TW
    [598] => zu
    [599] => zu_ZA
)


指定された日が平日か、週末か、ふたつの週の間の移行日かを返す

  • ≪ IntlCalendar::getAvailableLocales
  • IntlCalendar::getErrorCode ≫
  • PHP Manual
  • IntlCalendar
  • 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す

IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す

説明

オブジェクト指向型

public IntlCalendar::getDayOfWeekType(int $dayOfWeek): int|false

手続き型

intlcal_get_day_of_week_type(IntlCalendar $calendar, int $dayOfWeek): int|false

指定された日が平日 (IntlCalendar::DOW_TYPE_WEEKDAY) か、 週末 (IntlCalendar::DOW_TYPE_WEEKEND) か、 週末が始まる日 (IntlCalendar::DOW_TYPE_WEEKEND_OFFSET) か、 週末が終了する日 (IntlCalendar::DOW_TYPE_WEEKEND_CEASE) であるかを返します。

IntlCalendar::DOW_TYPE_WEEKEND_OFFSET または
IntlCalendar::DOW_TYPE_WEEKEND_CEASE を返した場合、
IntlCalendar::getWeekendTransition()
をコールして、週末の期間を取得することができます。

この関数を使うには、ICU 4.4 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

dayOfWeek

以下の定数のうち、いずれかを指定します。
IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY.

戻り値

定数 IntlCalendar::DOW_TYPE_WEEKDAY, IntlCalendar::DOW_TYPE_WEEKEND, IntlCalendar::DOW_TYPE_WEEKEND_OFFSET, IntlCalendar::DOW_TYPE_WEEKEND_CEASE のいずれかを返します。 失敗した場合に false を返します.

例

例1 IntlCalendar::getDayOfWeekType()

<?php
foreach (array('en_US', 'ar_SA') as $locale) {
echo "Locale: ", Locale::getDisplayName($locale, "en_US"), "\n";

$cal = IntlCalendar::createInstance('UTC', $locale);

for ($i = IntlCalendar::DOW_SUNDAY; $i <= IntlCalendar::DOW_SATURDAY; $i++) {
$type = $cal->getDayOfWeekType($i);
$transition = ($type !== IntlCalendar::DOW_TYPE_WEEKDAY)
? $cal->getWeekendTransition($i)
: '';
echo $i, " ", $type, " ", $transition, "\n";
}
echo "\n";
}
?>

上の例の出力は以下となります。

Locale: English (United States)
1 1 86400000
2 0
3 0
4 0
5 0
6 0
7 1 0

Locale: Arabic (Saudi Arabia)
1 0
2 0
3 0
4 0
5 0
6 1 0
7 1 86400000


オブジェクトに関する直近のエラーコードを取得する

  • ≪ IntlCalendar::getDayOfWeekType
  • IntlCalendar::getErrorMessage ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトに関する直近のエラーコードを取得する

IntlCalendar::getErrorCode

intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — オブジェクトに関する直近のエラーコードを取得する

説明

オブジェクト指向型 (method):

public IntlCalendar::getErrorCode(): int|false

手続き型:

intlcal_get_error_code(IntlCalendar $calendar): int|false

このオブジェクトの直近の呼び出し (clone も含みます) に関する ICU エラーコードを返します。 または、(手続き型の場合) calendar に指定された IntlCalendar に関する 直近のエラーコードを返します。 これは、単に警告を示している場合 (負のエラーコード) もあれば、 全くエラーがないことを示す場合 (U_ZERO_ERROR) もあります。 実際にエラーがあったかどうかをチェックする場合、 intl_is_failure() が使えます。

(ICU ライブラリを呼び出す前に) PHP 側で不正な引数を検知した場合は、 この関数で検知できる情報として記録されません。

intl 拡張モジュールの関数をコールした際に発生した直近のエラーは、 以前の引数エラーも含めて、 intl_get_error_code() で取得できます。 この関数はグローバルなエラーコードをリセットしますが、 オブジェクトのエラーコードはリセットしません。

パラメータ

calendar

手続き型のインターフェイスで指定する、カレンダーオブジェクト

戻り値

成功、失敗、または警告を示す ICU エラーコードを返します。 失敗した場合は false を返します。

例

例1 IntlCalendar::getErrorCode() と IntlCalendar::getErrorMessage() の例

<?php
ini_set("intl.error_level", E_WARNING);
ini_set("intl.default_locale", "nl");

$intlcal = new IntlGregorianCalendar(2012, 1, 29);
var_dump(
$intlcal->getErrorCode(),
$intlcal->getErrorMessage()
);
$intlcal->fieldDifference(-1e100, IntlCalendar::FIELD_SECOND);

var_dump(
$intlcal->getErrorCode(),
$intlcal->getErrorMessage()
);

上の例の出力は以下となります。

int(0)
string(12) "U_ZERO_ERROR"

Warning: IntlCalendar::fieldDifference(): intlcal_field_difference: Call to ICU method has failed in /home/glopes/php/ws/example.php on line 10
int(1)
string(81) "intlcal_field_difference: Call to ICU method has failed: U_ILLEGAL_ARGUMENT_ERROR"

参考

  • IntlCalendar::getErrorMessage() - オブジェクトの直近のエラーメッセージを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • intl_error_name() - 指定したエラーコードに対応する名前を取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_get_error_message() - 直近のエラーの説明を取得する


オブジェクトの直近のエラーメッセージを取得する

  • ≪ IntlCalendar::getErrorCode
  • IntlCalendar::getFirstDayOfWeek ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトの直近のエラーメッセージを取得する

IntlCalendar::getErrorMessage

intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — オブジェクトの直近のエラーメッセージを取得する

説明

オブジェクト指向型 (method):

public IntlCalendar::getErrorMessage(): string|false

手続き型:

intlcal_get_error_message(IntlCalendar $calendar): string|false

IntlCalendar::getErrorCode() や intlcal_get_error_code() によって報告されたエラーに関連するエラーメッセージを(もしあれば)返します。 関連するエラーメッセージが存在しない場合、 エラー定数の名前の文字列表現だけを返します。 エラーメッセージが存在する場合、 PHP バインディングの側で設定されたメッセージを含む文字列を返します。

パラメータ

calendar

手続き型のインターフェイスで指定する、カレンダーオブジェクト

戻り値

このオブジェクトにおける関数コールで発生した、 直近のエラーに関連するメッセージを返します。 または、エラーが発生しないことを示す文字列を返します。 失敗した場合は false を返します。

例

例1 IntlCalendar::getErrorMessage()

<?php
$cal = IntlCalendar::createInstance('UTC', 'en_US');
var_dump($cal->getErrorMessage());

$cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
var_dump($cal->getErrorMessage());

上の例の出力は以下となります。

string(12) "U_ZERO_ERROR"
string(82) "intlcal_get_weekend_transition: Error calling ICU method: U_ILLEGAL_ARGUMENT_ERROR"


カレンダーのロケールに基づいて、週の始めの日を返す

  • ≪ IntlCalendar::getErrorMessage
  • IntlCalendar::getGreatestMinimum ≫
  • PHP Manual
  • IntlCalendar
  • カレンダーのロケールに基づいて、週の始めの日を返す

IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — カレンダーのロケールに基づいて、週の始めの日を返す

説明

オブジェクト指向型

public IntlCalendar::getFirstDayOfWeek(): int|false

手続き型

intlcal_get_first_day_of_week(IntlCalendar $calendar): int|false

週の始めにあたる平日を返します。 これはロケールに基づくデフォルト値か、 IntlCalendar::setFirstDayOfWeek() で設定された値です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY
の定数のうち、いずれかを返します。
失敗した場合に false を返します.

例

例1 IntlCalendar::getFirstDayOfWeek()

<?php
ini_set('date.timezone', 'UTC');

$cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
var_dump($cal1->getFirstDayOfWeek()); // Monday
$cal1->set(2013, 1 /* February */, 3); // a Sunday
var_dump($cal1->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 5

$cal2 = IntlCalendar::createInstance(NULL, 'en_US');
var_dump($cal2->getFirstDayOfWeek()); // Sunday
$cal2->set(2013, 1 /* February */, 3); // a Sunday
var_dump($cal2->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 6

上の例の出力は以下となります。

int(2)
int(5)
int(1)
int(6)

参考

  • IntlCalendar::setFirstDayOfWeek() - 週の始まりと見なされる曜日を設定する


指定されたフィールドの、ローカルな最小値のうち、最大の値を返す

  • ≪ IntlCalendar::getFirstDayOfWeek
  • IntlCalendar::getKeywordValuesForLocale ≫
  • PHP Manual
  • IntlCalendar
  • 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す

IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す

説明

オブジェクト指向型

public IntlCalendar::getGreatestMinimum(int $field): int|false

手続き型

intlcal_get_greatest_minimum(IntlCalendar $calendar, int $field): int|false

指定されたフィールドの、ローカルな最小値のうち、最大の値を返します。 これは、 IntlCalendar::getActualMinimum() が返す値に等しいか、より大きい値、もしくは、 IntlCalendar::getMinimum() が返す値に等しいか、より大きい値になるはずです。 これらの3つの関数は、 グレゴリオ暦では同じ値を返します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

フィールドの値を示す整数値を、フィールドの単位で返します。 失敗した場合に false を返します


ロケールのキーワードの値の集合を返す

  • ≪ IntlCalendar::getGreatestMinimum
  • IntlCalendar::getLeastMaximum ≫
  • PHP Manual
  • IntlCalendar
  • ロケールのキーワードの値の集合を返す

IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — ロケールのキーワードの値の集合を返す

説明

オブジェクト指向型

public static IntlCalendar::getKeywordValuesForLocale(string $keyword, string $locale, bool $onlyCommon): IntlIterator|false

手続き型

intlcal_get_keyword_values_for_locale(string $keyword, string $locale, bool $onlyCommon): IntlIterator|false

指定されたロケールのキーに基づいて、 異なる振る舞いに繋がるキーに対応する、値の集合を返します。 現状では、キーワード 'calendar' のみがサポートされています。

この関数を使うには、ICU 4.2 以上が必要です。

パラメータ

keyword

関連する値を問い合わせるロケールのキーワード。 現状、 'calendar' だけがサポートされています。

locale

キーワード/値 のペアを追加するロケール。

onlyCommon

指定されたロケールで、共通に使われている値だけを表示するかどうか。

戻り値

ロケールのキーワードの値の文字列を格納したイテレータを返します。 失敗した場合に false を返します

例

例1 IntlCalendar::getKeyworkValuesForLocale()

<?php
print_r(
iterator_to_array(
IntlCalendar::getKeywordValuesForLocale(
'calendar', 'fa_IR', true)));
print_r(
iterator_to_array(
IntlCalendar::getKeywordValuesForLocale(
'calendar', 'fa_IR', false)));

上の例の出力は以下となります。

Array
(
    [0] => persian
    [1] => gregorian
    [2] => islamic
    [3] => islamic-civil
)
Array
(
    [0] => persian
    [1] => gregorian
    [2] => islamic
    [3] => islamic-civil
    [4] => japanese
    [5] => buddhist
    [6] => roc
    [7] => hebrew
    [8] => chinese
    [9] => indian
    [10] => coptic
    [11] => ethiopic
    [12] => ethiopic-amete-alem
)


指定されたフィールドの、ローカルな最大値のうち、最小の値を返す

  • ≪ IntlCalendar::getKeywordValuesForLocale
  • IntlCalendar::getLocale ≫
  • PHP Manual
  • IntlCalendar
  • 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す

IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す

説明

オブジェクト指向型

public IntlCalendar::getLeastMaximum(int $field): int|false

手続き型

intlcal_get_least_maximum(IntlCalendar $calendar, int $field): int|false

指定されたフィールドの、ローカルな最大値のうち、最小の値を返します。 これは、 IntlCalendar::getActualMaxmimum() が返す値に等しいか、より小さい値、もしくは、 IntlCalendar::getMaximum() が返す値に等しいか、より小さい値になるはずです。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

フィールドの値を示す整数値を、フィールドの単位で返します。 失敗した場合に false を返します

例

例1 Maxima examples

<?php
ini_set('date.timezone', 'UTC');
ini_set('intl.default_locale', 'it_IT');

$cal = new IntlGregorianCalendar(2013, 3 /* April */, 6);
var_dump(
$cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 28
$cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 30
$cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH) // 31
);

上の例の出力は以下となります。

int(28)
int(30)
int(31)

参考

  • IntlCalendar::getActualMaximum() - オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する
  • IntlCalendar::getMaximum() - フィールドのグローバルな最大値を返す
  • IntlCalendar::getGreatestMinimum() - 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す


オブジェクトに関連付けられたロケールを取得する

  • ≪ IntlCalendar::getLeastMaximum
  • IntlCalendar::getMaximum ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトに関連付けられたロケールを取得する

IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — オブジェクトに関連付けられたロケールを取得する

説明

オブジェクト指向型

public IntlCalendar::getLocale(int $type): string|false

手続き型

intlcal_get_locale(IntlCalendar $calendar, int $type): string|false

カレンダーオブジェクトが使っているロケールを返します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

type

実際のロケール (カレンダーデータの元になったロケール。 Locale::ACTUAL_LOCALE) または有効なロケールを取得するかどうか。 つまり、指定されたロケールに対して ICU が比較的サポートしている、 もっとも特殊なロケールです - 詳細は Locale::VALID_LOCALE を参照ください。 ロケールは実際のロケール、有効なロケール、 指定されたロケールの順に並び、 さらにもっとも一般的なものから、もっとも特殊なものへ並びます。

戻り値

ロケールを表す文字列を返します。 失敗した場合に false を返します.

例

例1 IntlCalendar::getLocale()

<?php
$cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
var_dump(
$cal->getLocale(Locale::ACTUAL_LOCALE),
$cal->getLocale(Locale::VALID_LOCALE)
);

上の例の出力は以下となります。

string(2) "en"
string(5) "en_US"


フィールドのグローバルな最大値を返す

  • ≪ IntlCalendar::getLocale
  • IntlCalendar::getMinimalDaysInFirstWeek ≫
  • PHP Manual
  • IntlCalendar
  • フィールドのグローバルな最大値を返す

IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — フィールドのグローバルな最大値を返す

説明

オブジェクト指向型

public IntlCalendar::getMaximum(int $field): int|false

手続き型

intlcal_get_maximum(IntlCalendar $calendar, int $field): int|false

この特定のカレンダーにおける、 フィールドのグローバルな最大値を取得します。 この値は IntlCalendar::getActualMaximum() が返す値に等しいか、より大きい値、 または IntlCalendar::getLeastMaximum() が返す値に等しいか、より大きい値になります。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

フィールドの値を示す整数値を、フィールドの単位で返します。 失敗した場合に false を返します

参考

  • IntlCalendar::getActualMaximum() - オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する
  • IntlCalendar::getLeastMaximum() - 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す
  • IntlCalendar::getMinimum() - フィールドのグローバルな最小値を返す


特定の年や月における、最初の週の日数の最小値を返す

  • ≪ IntlCalendar::getMaximum
  • IntlCalendar::getMinimum ≫
  • PHP Manual
  • IntlCalendar
  • 特定の年や月における、最初の週の日数の最小値を返す

IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を返す

説明

オブジェクト指向型

public IntlCalendar::getMinimalDaysInFirstWeek(): int|false

手続き型

intlcal_get_minimal_days_in_first_week(IntlCalendar $calendar): int|false

特定の年や月が持たなければならない、 最初の週の日数の最小値を返します。 たとえば、グレゴリオ暦においてこの値が1の場合、 その年の最初の週には1月1日が含まれます。 一方で、この値を7にすると、1月1日はその週の曜日が IntlCalendar::getFirstDayOfWeek() が返した曜日と一致する場合のみ、最初の週になります。 そうでない場合、前年の最後の週として扱われます。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

日数を示す数値を返します。 失敗した場合に false を返します

例

例1 IntlCalendar::getMinimalDaysInFirstWeek()

<?php
ini_set('date.timezone', 'UTC');
ini_set('intl.default_locale', 'en_US');

$cal = new IntlGregorianCalendar(2013, 0 /* January */, 2);
var_dump(IntlDateFormatter::formatObject($cal, 'cccc')); // Wednesday

var_dump($cal->getMinimalDaysInFirstWeek(), // 1
$cal->getFirstDayofWeek()); // 1 (Sunday)

// Week 1 of 2013
var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

$cal->setMinimalDaysInFirstWeek(4);
// Still Week 1 of 2013 (1st week has 5 days in the new year)
var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

$cal->setMinimalDaysInFirstWeek(6);
// Week 53 of 2012
var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

上の例の出力は以下となります。

string(9) "Wednesday"
int(1)
int(1)
string(14) "Week 1 of 2013"
string(14) "Week 1 of 2013"
string(15) "Week 53 of 2012"


フィールドのグローバルな最小値を返す

  • ≪ IntlCalendar::getMinimalDaysInFirstWeek
  • IntlCalendar::getNow ≫
  • PHP Manual
  • IntlCalendar
  • フィールドのグローバルな最小値を返す

IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — フィールドのグローバルな最小値を返す

説明

オブジェクト指向型

public IntlCalendar::getMinimum(int $field): int|false

手続き型

intlcal_get_minimum(IntlCalendar $calendar, int $field): int|false

この特定のカレンダーにおける、 フィールドのグローバルな最小値を取得します。 この値は IntlCalendar::getActualMinimum() が返す値に等しいか、より小さい値、 または IntlCalendar::getGreatestMinimum() が返す値に等しいか、より小きい値になります。 グレゴリオ暦のカレンダーでは、 これらは(各フィールドについて)常に同じ値を返します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

フィールドの値を示す整数値を、フィールドの単位で返します。 失敗した場合に false を返します


現在時刻を示す数値を取得する

  • ≪ IntlCalendar::getMinimum
  • IntlCalendar::getRepeatedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • 現在時刻を示す数値を取得する

IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — 現在時刻を示す数値を取得する

説明

オブジェクト指向型

public static IntlCalendar::getNow(): float

手続き型

intlcal_get_now(): float

エポックからの経過時間をミリ秒単位で返します。 この値は、システム時刻から来たものです。

パラメータ

この関数にはパラメータはありません。

戻り値

エポックからの経過時間をミリ秒単位で表した float を返します。 この値にはうるう秒は含まれていません。

例

例1 IntlCalendar::getNow()

<?php
$formatter = IntlDateFormatter::create('es_ES',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'Europe/Madrid');

$val = IntlCalendar::getNow();

var_dump($val);
echo $formatter->format(IntlCalendar::getNow() / 1000.), "\n";

上の例の出力は以下となります。

float(1371425814666)
lunes, 17 de junio de 2013 01:36:54 Hora de verano de Europa central


繰り返される実時間を扱う際の振る舞いを取得する

  • ≪ IntlCalendar::getNow
  • IntlCalendar::getSkippedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • 繰り返される実時間を扱う際の振る舞いを取得する

IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — 繰り返される実時間を扱う際の振る舞いを取得する

説明

オブジェクト指向型

public IntlCalendar::getRepeatedWallTimeOption(): int

手続き型

intlcal_get_repeated_wall_time_option(IntlCalendar $calendar): int

夏時間が終わり、 「時計が巻き戻される時に繰り返される実時間」をどう扱うかの戦略を取得します。 デフォルト値は IntlCalendar::WALLTIME_LAST です。

この関数を使うには、ICU 4.9 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

IntlCalendar::WALLTIME_FIRST または IntlCalendar::WALLTIME_LAST のどちらかを返します。

例

例1 IntlCalendar::getRepeatedWallTimeOption()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'en_US');
ini_set('intl.error_level', E_WARNING);

//On October 27th at 0200, the clock goes back 1 hour and from GMT+01 to GMT+00
$cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30);

var_dump($cal->getRepeatedWalltimeOption()); // 0 WALLTIME_LAST

$formatter = IntlDateFormatter::create(
NULL,
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'UTC'
);
var_dump($formatter->format($cal->getTime() / 1000.));

$cal->setRepeatedWalltimeOption(IntlCalendar::WALLTIME_FIRST);
var_dump($cal->getRepeatedWalltimeOption()); // 1 WALLTIME_FIRST
$cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

var_dump($formatter->format($cal->getTime() / 1000.));

上の例の出力は以下となります。

int(0)
string(42) "Sunday, October 27, 2013 at 1:30:00 AM GMT"
int(1)
string(43) "Sunday, October 27, 2013 at 12:30:00 AM GMT"

参考

  • IntlCalendar::getSkippedWallTimeOption() - スキップされた実時間を扱う際の振る舞いを取得する
  • IntlCalendar::setSkippedWallTimeOption() - 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する
  • IntlCalendar::setRepeatedWallTimeOption() - 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する


スキップされた実時間を扱う際の振る舞いを取得する

  • ≪ IntlCalendar::getRepeatedWallTimeOption
  • IntlCalendar::getTime ≫
  • PHP Manual
  • IntlCalendar
  • スキップされた実時間を扱う際の振る舞いを取得する

IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — スキップされた実時間を扱う際の振る舞いを取得する

説明

オブジェクト指向型

public IntlCalendar::getSkippedWallTimeOption(): int

手続き型

intlcal_get_skipped_wall_time_option(IntlCalendar $calendar): int

夏時間が始まった際に時間を進めた場合に、 スキップされる実時間をどう扱うかの戦略を取得します。 デフォルト値は IntlCalendar::WALLTIME_LAST です。

このオプションを有効にするには、 カレンダーの 緩いモード がONになっている必要があります。 そうでない場合、存在しない時刻を設定しようとしてエラーが発生します。

この関数を使うには、ICU 4.9 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

IntlCalendar::WALLTIME_FIRST,
IntlCalendar::WALLTIME_LAST,
IntlCalendar::WALLTIME_NEXT_VALID
のうちのいずれかを返します。

例

例1 IntlCalendar::getSkippedWallTimeOption()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'en_US');
ini_set('intl.error_level', E_WARNING);

//On March 31st at 0100, the clock goes forward 1 hour and from GMT+00 to GMT+01
$cal = new IntlGregorianCalendar(2013, 2 /* March */, 31, 1, 30);

var_dump(
$cal->isLenient(), // true
$cal->getSkippedWalltimeOption() // 0 WALLTIME_LAST
);

$formatter = IntlDateFormatter::create(
NULL,
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'UTC'
);
var_dump($formatter->format($cal->getTime() / 1000));

$cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
var_dump($cal->getSkippedWalltimeOption()); // 1 WALLTIME_FIRST
$cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

var_dump($formatter->format($cal->getTime() / 1000));

$cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_NEXT_VALID);
var_dump($cal->getSkippedWalltimeOption()); // 2 WALLTIME_NEXT_VALID
$cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

var_dump($formatter->format($cal->getTime() / 1000));

上の例の出力は以下となります。

bool(true)
int(0)
string(40) "Sunday, March 31, 2013 at 1:30:00 AM GMT"
int(1)
string(41) "Sunday, March 31, 2013 at 12:30:00 AM GMT"
int(2)
string(40) "Sunday, March 31, 2013 at 1:00:00 AM GMT"

参考

  • IntlCalendar::getRepeatedWallTimeOption() - 繰り返される実時間を扱う際の振る舞いを取得する
  • IntlCalendar::setSkippedWallTimeOption() - 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する
  • IntlCalendar::setRepeatedWallTimeOption() - 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する


このオブジェクトが表す時刻を取得する

  • ≪ IntlCalendar::getSkippedWallTimeOption
  • IntlCalendar::getTimeZone ≫
  • PHP Manual
  • IntlCalendar
  • このオブジェクトが表す時刻を取得する

IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — このオブジェクトが表す時刻を取得する

説明

オブジェクト指向型

public IntlCalendar::getTime(): float|false

手続き型

intlcal_get_time(IntlCalendar $calendar): float|false

このオブジェクトに関連付けられた時刻を返します。 エポック(1 Jan 1970 00:00:00.000 UTC) からの経過時刻をミリ秒単位で表したものです。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

エポック(1 Jan 1970 00:00:00.000 UTC) からの経過時刻をミリ秒単位で表した値を float で返します。 失敗した場合に false を返します

例

例1 IntlCalendar::getTime()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'en_US');

$cal = new IntlGregorianCalendar(2013, 4 /* May */, 1, 0, 0, 0);
$time = $cal->getTime();
var_dump($time, $time / 1000 == strtotime('2013-05-01 00:00:00')); //true

上の例の出力は以下となります。

float(1367362800000)
bool(true)

参考

  • IntlCalendar::getNow() - 現在時刻を示す数値を取得する


オブジェクトのタイムゾーンを取得する

  • ≪ IntlCalendar::getTime
  • IntlCalendar::getType ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトのタイムゾーンを取得する

IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — オブジェクトのタイムゾーンを取得する

説明

オブジェクト指向型

public IntlCalendar::getTimeZone(): IntlTimeZone|false

手続き型

intlcal_get_time_zone(IntlCalendar $calendar): IntlTimeZone|false

このカレンダーに関連付けられた、 IntlTimeZone オブジェクトを返します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

このオブジェクトで内部的に使われている、 関連した IntlTimeZone を返します。 失敗時に false を返します。

例

例1 IntlCalendar::getTimeZone()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'en_US');

$cal = IntlCalendar::createInstance();
print_r($cal->getTimeZone());

$cal->setTimeZone('UTC');
print_r($cal->getTimeZone());

$cal = IntlCalendar::fromDateTime('2012-01-01 00:00:00 GMT+03:33');
print_r($cal->getTimeZone());

上の例の出力は以下となります。

IntlTimeZone Object
(
    [valid] => 1
    [id] => Europe/Lisbon
    [rawOffset] => 0
    [currentOffset] => 3600000
)
IntlTimeZone Object
(
    [valid] => 1
    [id] => UTC
    [rawOffset] => 0
    [currentOffset] => 0
)
IntlTimeZone Object
(
    [valid] => 1
    [id] => GMT+03:33
    [rawOffset] => 12780000
    [currentOffset] => 12780000
)

参考

  • IntlCalendar::setTimeZone() - このカレンダーで使うタイムゾーンを設定する
  • IntlCalendar::createInstance() - 新しい IntlCalendar を作成する
  • IntlGregorianCalendar::__construct() - グレゴリオ暦の Calendar クラスを作成する


カレンダーのタイプを取得する

  • ≪ IntlCalendar::getTimeZone
  • IntlCalendar::getWeekendTransition ≫
  • PHP Manual
  • IntlCalendar
  • カレンダーのタイプを取得する

IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — カレンダーのタイプを取得する

説明

オブジェクト指向型

public IntlCalendar::getType(): string

手続き型

intlcal_get_type(IntlCalendar $calendar): string

カレンダーのタイプを示す文字列を取得します。 これは、カレンダーのキーワードが 'calendar' のうち、有効な ロケールのキーワードの値 のうちの一つです。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

カレンダーのタイプを示す文字列を返します。 たとえば 'gregorian', 'islamic' のようなものです。

例

例1 IntlCalendar::getType()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'en_US');

$cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
var_dump($cal->getType());

$cal = new IntlGregorianCalendar();
var_dump($cal->getType());

上の例の出力は以下となります。

string(19) "ethiopic-amete-alem"
string(9) "gregorian"


週末が開始/終了した日からの経過時間を取得する

  • ≪ IntlCalendar::getType
  • IntlCalendar::inDaylightTime ≫
  • PHP Manual
  • IntlCalendar
  • 週末が開始/終了した日からの経過時間を取得する

IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — 週末が開始/終了した日からの経過時間を取得する

説明

オブジェクト指向型

public IntlCalendar::getWeekendTransition(int $dayOfWeek): int|false

手続き型

intlcal_get_weekend_transition(IntlCalendar $calendar, int $dayOfWeek): int|false

週末が開始/終了する日からの経過時間をミリ秒単位で返します。

IntlCalendar::getDayOfWeekType() が IntlCalendar::DOW_TYPE_WEEKEND_OFFSET や IntlCalendar::DOW_TYPE_WEEKEND_CEASE を返した曜日にのみ、この関数は使えます。 それ以外の曜日の場合は、エラーになります。

この関数を使うには、ICU 4.4 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

dayOfWeek

IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY
のいずれかを指定します。

戻り値

週末が開始/終了する日からの経過時間をミリ秒単位で返します。 失敗した場合に false を返します.

例

See example on IntlCalendar::getDayOfWeekType().


オブジェクトの時刻が夏時間かを調べる

  • ≪ IntlCalendar::getWeekendTransition
  • IntlCalendar::isEquivalentTo ≫
  • PHP Manual
  • IntlCalendar
  • オブジェクトの時刻が夏時間かを調べる

IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — オブジェクトの時刻が夏時間かを調べる

説明

オブジェクト指向型

public IntlCalendar::inDaylightTime(): bool

手続き型

intlcal_in_daylight_time(IntlCalendar $calendar): bool

このオブジェクトが表す瞬間、 およびタイムゾーンが夏時間の場所であるかを判定します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

このオブジェクトの日付が夏時間の場合に true を返します。 そうでない場合、false を返します。

失敗時に false を返します。エラーを検知するには、intl_get_error_code() を使うか、 Intl拡張モジュールが 例外 をスローするように設定して下さい。

例

例1 IntlCalendar::inDaylightTime()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'pt_PT');

$cal = new IntlGregorianCalendar(2013, 6 /* July */, 1, 4, 56, 31);
var_dump($cal->inDaylightTime()); // true
$cal->set(IntlCalendar::FIELD_MONTH, 11 /* December */);
var_dump($cal->inDaylightTime()); // false

//DST end transition on 2013-10-27 at 0200 (wall time back 1 hour)
$cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30, 0);

var_dump($cal->inDaylightTime()); // false (default WALLTIME_LAST)

$cal->setRepeatedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
$cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1); // force time recalculation
var_dump($cal->inDaylightTime()); // true


別のカレンダーが、時刻を除いて等しいかを調べる

  • ≪ IntlCalendar::inDaylightTime
  • IntlCalendar::isLenient ≫
  • PHP Manual
  • IntlCalendar
  • 別のカレンダーが、時刻を除いて等しいかを調べる

IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — 別のカレンダーが、時刻を除いて等しいかを調べる

説明

オブジェクト指向型

public IntlCalendar::isEquivalentTo(IntlCalendar $other): bool

手続き型

intlcal_is_equivalent_to(IntlCalendar $calendar, IntlCalendar $other): bool

このオブジェクト、および指定されたオブジェクトが、 設定されている時刻以外で等しいかを返します。 振る舞いの変更がオブジェクトの不一致から起きない限り、 ロケールが一致している必要はありません。 比較されるのは、 タイムゾーン や 緩いモード が設定されているかどうか、 実時間設定の 繰り返し、 実時間の設定の 省略、 週の始まりと終了の曜日、 週の間の移行が起こる時刻 があります。 その他、カレンダー特有の設定も比較されます。 たとえば、グレゴリオ暦/ユリウス暦への移行の瞬間などです。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

other

比較するカレンダー

戻り値

引数にエラーがなく、 時刻以外はおそらくカレンダーが等しい場合に true を返します。

例

例1 IntlCalendar::isEquivalentTo()

<?php
$cal1 = IntlCalendar::createInstance('Europe/Lisbon', 'pt_PT');
$cal2 = IntlCalendar::createInstance('Europe/Lisbon', 'es_ES');
$cal2->clear();

var_dump($cal1->isEquivalentTo($cal2)); // true

$cal3 = IntlCalendar::createInstance('Europe/Lisbon', 'en_US');
var_dump($cal1->isEquivalentTo($cal3)); // false
var_dump($cal1->getFirstDayOfWeek(), // 2 (Monday)
$cal3->getFirstDayOfWeek()); // 1 (Sunday)

上の例の出力は以下となります。

bool(true)
bool(false)
int(2)
int(1)

参考

  • IntlCalendar::equals() - ふたつの IntlCalendar オブジェクトの時刻を比較する


日付と時刻の解釈を「緩いモード」で行うかを取得する

  • ≪ IntlCalendar::isEquivalentTo
  • IntlCalendar::isSet ≫
  • PHP Manual
  • IntlCalendar
  • 日付と時刻の解釈を「緩いモード」で行うかを取得する

IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — 日付と時刻の解釈を「緩いモード」で行うかを取得する

説明

オブジェクト指向型

public IntlCalendar::isLenient(): bool

手続き型

intlcal_is_lenient(IntlCalendar $calendar): bool

現在の日付/時刻の解釈が「緩いモード」(デフォルト) で行われているかを返します。 緩いモードの場合、フィールドの範囲外の値によっては、 エラーを発生させることなく受け入れられる場合があります。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

カレンダーが「緩いモード」に設定されているかどうかを bool で返します。

例

例1 IntlCalendar::isLenient()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'pt_PT');
ini_set('intl.use_exceptions', '1');

$cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
var_dump(IntlDateFormatter::formatObject($cal), // 01/07/2013, 00:00:00
$cal->isLenient()); // true

$cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
var_dump(IntlDateFormatter::formatObject($cal)); // 02/08/2013, 00:00:00

$cal->setLenient(false);
var_dump($cal->isLenient()); // false
$cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
var_dump(IntlDateFormatter::formatObject($cal)); // error

上の例の出力は以下となります。

string(20) "01/07/2013, 00:00:00"
bool(true)
string(20) "02/08/2013, 00:00:00"
bool(false)

Fatal error: Uncaught exception 'IntlException' with message 'datefmt_format_object: error obtaining instant from IntlCalendar' in /home/foobar/example.php:16
Stack trace:
#0 /home/foobar/example.php(16): IntlDateFormatter::formatObject(Object(IntlGregorianCalendar))
#1 {main}
  thrown in /home/foobar/example.php on line 16


フィールドが設定されているかを調べる

  • ≪ IntlCalendar::isLenient
  • IntlCalendar::isWeekend ≫
  • PHP Manual
  • IntlCalendar
  • フィールドが設定されているかを調べる

IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — フィールドが設定されているかを調べる

説明

オブジェクト指向型

public IntlCalendar::isSet(int $field): bool

手続き型

intlcal_is_set(IntlCalendar $calendar, int $field): bool

(clear とは逆に) フィールドが設定されているかどうかを判定して返します。 フィールドを設定することは、 フィールドを未設定にし、 日付/時刻を計算する時にデフォルト値を用いることよりも優先度が高いです。 後に設定したフィールドの方が、先に設定したものよりも優先度が高いです。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

戻り値

引数にエラーがない場合、 フィールドが設定されると true を返します。

例

IntlCalendar::clear() の例を参照ください。

参考

  • IntlCalendar::clear() - 単一または全てのフィールドをクリアする
  • IntlCalendar::set() - 時刻または複数の共通フィールドを一度に設定する


ある日付/時刻が週末にあるかを調べる

  • ≪ IntlCalendar::isSet
  • IntlCalendar::roll ≫
  • PHP Manual
  • IntlCalendar
  • ある日付/時刻が週末にあるかを調べる

IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — ある日付/時刻が週末にあるかを調べる

説明

オブジェクト指向型

public IntlCalendar::isWeekend(?float $timestamp = null): bool

手続き型

intlcal_is_weekend(IntlCalendar $calendar, ?float $timestamp = null): bool

オブジェクトの現在時刻、または 指定されたタイムスタンプが、 オブジェクトのカレンダーシステムに照らして、 週末に発生するかを判定して返します。

この関数を使うには、ICU 4.4 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

timestamp

エポックからの経過時刻をミリ秒単位、 かつうるう秒を除いた値を、 オプションのタイムスタンプとして指定します。 null の場合、 オブジェクトの現在時刻を代わりに使います。

戻り値

指定した、またはこのオブジェクトの時刻が週末に入っているかを bool で返します。

失敗時に false を返します。エラーを検知するには、intl_get_error_code() を使うか、 Intl拡張モジュールが 例外 をスローするように設定して下さい。

例

例1 IntlCalendar::isWeekend()

<?php
ini_set('date.timezone', 'Europe/Lisbon');

$cal = new IntlGregorianCalendar(NULL, 'en_US');
$cal->set(2013, 6 /* July */, 7); // a Sunday

var_dump($cal->isWeekend()); // true
var_dump($cal->isWeekend(strtotime('2013-07-01 00:00:00'))); // false, Monday

$cal = new IntlGregorianCalendar(NULL, 'ar_SA');
$cal->set(2013, 6 /* July */, 7); // a Sunday
var_dump($cal->isWeekend()); // false, Sunday not in weekend in this calendar

参考

  • IntlCalendar::getDayOfWeekType() - 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す
  • IntlCalendar::getWeekendTransition() - 週末が開始/終了した日からの経過時間を取得する


次のフィールドを繰り上げずに、フィールドに値を加算する

  • ≪ IntlCalendar::isWeekend
  • IntlCalendar::set ≫
  • PHP Manual
  • IntlCalendar
  • 次のフィールドを繰り上げずに、フィールドに値を加算する

IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — 次のフィールドを繰り上げずに、フィールドに値を加算する

説明

オブジェクト指向型

public IntlCalendar::roll(int $field, int|bool $value): bool

手続き型

intlcal_roll(IntlCalendar $calendar, int $field, int|bool $value): bool

(符号付きの)量をフィールドに加算します。 IntlCalendar::add() との違いは、 フィールドの値がオーバーフローしても、 次のフィールドの値が繰り上がらないことです。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

value

フィールドに加算する(符号付きの)量。 true を指定すると値を増やします (つまり、1 を足します)。 false を指定すると値を減らします (つまり、1 を引きます)。

戻り値

成功時に true を返します。 失敗した場合は false を返します。

例

例1 IntlCalendar::roll()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'pt_PT');

$cal = new IntlGregorianCalendar(2013, 5 /* June */, 30);

$cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
var_dump(IntlDateFormatter::formatObject($cal)); // "01/07/2013, 00:00:00"

$cal->set(2013, 5 /* June */, 30);
$cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true); // roll up, same as rolling +1
var_dump(IntlDateFormatter::formatObject($cal)); // "01/06/2013, 00:00:00"

上の例の出力は以下となります。

string(20) "01/07/2013, 00:00:00"
string(20) "01/06/2013, 00:00:00"

参考

  • IntlCalendar::add() - フィールドに (符号付きの) 一定量の時間を追加する
  • IntlCalendar::set() - 時刻または複数の共通フィールドを一度に設定する


時刻または複数の共通フィールドを一度に設定する

  • ≪ IntlCalendar::roll
  • IntlCalendar::setDate ≫
  • PHP Manual
  • IntlCalendar
  • 時刻または複数の共通フィールドを一度に設定する

IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — 時刻または複数の共通フィールドを一度に設定する

説明

オブジェクト指向型

public IntlCalendar::set(int $field, int $value): true
public IntlCalendar::set(
int $year,
int $month,
int $dayOfMonth = NULL,
int $hour = NULL,
int $minute = NULL,
int $second = NULL
): true

手続き型

intlcal_set(IntlCalendar $cal, int $field, int $value): true
intlcal_set(
IntlCalendar $cal,
int $year,
int $month,
int $dayOfMonth = NULL,
int $hour = NULL,
int $minute = NULL,
int $second = NULL
): bool

特定のフィールドを指定された値に設定するか、 いくつかの共通のフィールドを一度に設定します。 受け入れ可能な値の範囲は、 カレンダーの 緩いモード が有効かどうかに依存します。

衝突したフィールドについては、 あとで設定されたフィールドの優先度が高くなります。

このメソッドは、引数を4つ指定してコールできません。

パラメータ

cal

IntlCalendar クラスのインスタンス。

field

IntlCalendar の日付/時刻 フィールド定数 のいずれか。 0 から IntlCalendar::FIELD_COUNT までの間の整数値です。

value

指定されたフィールドに設定する新しい値。

year

IntlCalendar::FIELD_YEAR に設定する新しい値。

month

IntlCalendar::FIELD_MONTH に設定する新しい値。 月の値は0から始まります。 つまり、1月は0として表され、2月は1、... 12月は11になります。 そして、Undecember(カレンダーそのもの) の場合は、12 になります。

dayOfMonth

IntlCalendar::FIELD_DAY_OF_MONTH に設定する新しい値。

hour

IntlCalendar::FIELD_HOUR_OF_DAY に設定する新しい値。

minute

IntlCalendar::FIELD_MINUTE に設定する新しい値。

second

IntlCalendar::FIELD_SECOND に設定する新しい値。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 IntlCalendar::set()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'pt_PT');

//Calls made later have priority
$cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
$cal->set(IntlCalendar::FIELD_YEAR, 2012);
$cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
var_dump(IntlDateFormatter::formatObject($cal));

$cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
$cal->set(IntlCalendar::FIELD_YEAR, 2012);
$cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
//the time has not been recalculated yet. If we clear the extended year,
//the year set before will be used
$cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR);
var_dump(IntlDateFormatter::formatObject($cal));

上の例の出力は以下となります。

string(20) "01/07/2011, 00:00:00"
string(20) "01/07/2012, 00:00:00"

参考

  • IntlCalendar::get() - フィールドの値を取得する
  • IntlCalendar::add() - フィールドに (符号付きの) 一定量の時間を追加する
  • IntlCalendar::roll() - 次のフィールドを繰り上げずに、フィールドに値を加算する


日付のフィールドを設定する

  • ≪ IntlCalendar::set
  • IntlCalendar::setDateTime ≫
  • PHP Manual
  • IntlCalendar
  • 日付のフィールドを設定する

IntlCalendar::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — 日付のフィールドを設定する

説明

public IntlCalendar::setDate(int $year, int $month, int $dayOfMonth): void

日付のフィールドを、指定した値に設定します。

パラメータ

year

IntlCalendar::FIELD_YEAR の新しい値。

month

IntlCalendar::FIELD_MONTH の新しい値。 月の数値は0から始まります。1月は0、2月は1、のように続き、 12月は11になります。(カレンダーに存在していれば) Undecember が12になります。

dayOfMonth

IntlCalendar::FIELD_DAY_OF_MONTH の新しい値。

戻り値

値を返しません。

例

例1 IntlCalendar::setDate() の例

<?php
$intlCal = IntlCalendar::createInstance('UTC');

$intlCal->setDate(2012, 1, 29);
?>


日付と時刻のフィールドを設定する

  • ≪ IntlCalendar::setDate
  • IntlCalendar::setFirstDayOfWeek ≫
  • PHP Manual
  • IntlCalendar
  • 日付と時刻のフィールドを設定する

IntlCalendar::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — 日付と時刻のフィールドを設定する

説明

public IntlCalendar::setDateTime(
int $year,
int $month,
int $dayOfMonth,
int $hour,
int $minute,
?int $second = null
): void

日付と時刻のフィールドを、指定された値に設定します。

パラメータ

year

IntlCalendar::FIELD_YEAR の新しい値。

month

IntlCalendar::FIELD_MONTH の新しい値。 月の数値は0から始まります。1月は0、2月は1、のように続き、 12月は11になります。(カレンダーに存在していれば) Undecember が12になります。

dayOfMonth

IntlCalendar::FIELD_DAY_OF_MONTH の新しい値。

hour

IntlCalendar::FIELD_HOUR_OF_DAY の新しい値。

minute

IntlCalendar::FIELD_MINUTE の新しい値。

second

IntlCalendar::FIELD_SECOND の新しい値。

戻り値

値を返しません。

例

例1 IntlCalendar::setDateTime() の例

<?php
$intlCal = IntlCalendar::createInstance('UTC');

$intlCal->setDateTime(2012, 1, 29, 23, 58);
?>


週の始まりと見なされる曜日を設定する

  • ≪ IntlCalendar::setDateTime
  • IntlCalendar::setLenient ≫
  • PHP Manual
  • IntlCalendar
  • 週の始まりと見なされる曜日を設定する

IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — 週の始まりと見なされる曜日を設定する

説明

オブジェクト指向型

public IntlCalendar::setFirstDayOfWeek(int $dayOfWeek): true

手続き型

intlcal_set_first_day_of_week(IntlCalendar $calendar, int $dayOfWeek): true

週の始まりとみなされる曜日を定義します。 これは、 IntlCalendar::FIELD_WEEK_OF_YEAR や IntlCalendar::FIELD_YEAR_WOY のような、 週の始まりと終わりの概念に依存したフィールドの振る舞いに影響します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

dayOfWeek

IntlCalendar::DOW_SUNDAY,
IntlCalendar::DOW_MONDAY, ...,
IntlCalendar::DOW_SATURDAY のうちのいずれか。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 IntlCalendar::setFirstDayOfWeek()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'es_ES');

$cal = IntlCalendar::createInstance();
$cal->set(2013, 5 /* June */, 30); // A Sunday

var_dump($cal->getFirstDayOfWeek()); // 2 (Monday)

echo IntlDateFormatter::formatObject($cal, <<<EOD
'local day of week: 'cc'
week of month : 'W'
week of year : 'ww
EOD
), "\n";

$cal->setFirstDayOfWeek(IntlCalendar::DOW_SUNDAY);

echo IntlDateFormatter::formatObject($cal, <<<EOD
'local day of week: 'cc'
week of month : 'W'
week of year : 'ww
EOD
), "\n";

上の例の出力は以下となります。

int(2)
local day of week: 7
week of month    : 4
week of year     : 26
local day of week: 1
week of month    : 5
week of year     : 27


日付/時刻の解釈を「緩いモード」にするかを設定する

  • ≪ IntlCalendar::setFirstDayOfWeek
  • IntlCalendar::setMinimalDaysInFirstWeek ≫
  • PHP Manual
  • IntlCalendar
  • 日付/時刻の解釈を「緩いモード」にするかを設定する

IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — 日付/時刻の解釈を「緩いモード」にするかを設定する

説明

オブジェクト指向型

public IntlCalendar::setLenient(bool $lenient): true

手続き型

intlcal_set_lenient(IntlCalendar $calendar, bool $lenient): true

カレンダーを「緩いモード」にするかを設定します。 緩いモードでは、 範囲外の値はフィールドによっては受け入れられる可能性があります。 振る舞いは IntlCalendar::add() のそれに似ています (つまり、値が元に戻り、重要度が高いフィールドが繰り上がります)。 「緩いモード」がオフの場合、範囲外の値の場合はエラーが発生します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

lenient

「緩いモード」を有効にする場合は true を指定します。 オフにする場合は false を指定します。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

IntlCalendar::isLenient() の例を参照ください。


特定の年や月における、最初の週の日数の最小値を設定する

  • ≪ IntlCalendar::setLenient
  • IntlCalendar::setRepeatedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • 特定の年や月における、最初の週の日数の最小値を設定する

IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を設定する

説明

オブジェクト指向型

public IntlCalendar::setMinimalDaysInFirstWeek(int $days): true

手続き型

intlcal_set_minimal_days_in_first_week(IntlCalendar $calendar, int $days): true

特定の年や月が持たなければならない、 最初の週の日数の最小値を設定します。 たとえば、グレゴリオ暦においてこの値が1の場合、 その年の最初の週には1月1日が含まれます。 一方で、この値を7にすると、1月1日はその週の曜日が IntlCalendar::getFirstDayOfWeek() が返した曜日と一致する場合のみ、最初の週になります。 そうでない場合、前年の最後の週として扱われます。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

days

設定する最小の日数。

戻り値

常に true を返します。

エラー / 例外

days が範囲外の値 (1 より小さいか、7 より大きい) の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | 入力が不正な場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、false を返していました。


負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する

  • ≪ IntlCalendar::setMinimalDaysInFirstWeek
  • IntlCalendar::setSkippedWallTimeOption ≫
  • PHP Manual
  • IntlCalendar
  • 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する

IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する

説明

オブジェクト指向型

public IntlCalendar::setRepeatedWallTimeOption(int $option): true

手続き型

intlcal_set_repeated_wall_time_option(IntlCalendar $calendar, int $option): true

夏時間が終わり、時計を元に戻す際に繰り返される、 実時間をどう扱うかの戦略を設定します。 デフォルト値は IntlCalendar::WALLTIME_LAST (夏時間後に、時間を進めた時を採用する) ですが、 IntlCalendar::WALLTIME_FIRST (夏時間が終わった瞬間の時刻を採用する) も指定できます。

この関数を使うには、ICU 4.9 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

option

IntlCalendar::WALLTIME_FIRST, IntlCalendar::WALLTIME_LAST のいずれかです。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

IntlCalendar::getRepeatedWallTimeOption() の例を参照ください。

参考

  • intlCalendar::getRepeatedWallTimeOption() - 繰り返される実時間を扱う際の振る舞いを取得する
  • intlCalendar::setSkippedWallTimeOption() - 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する
  • intlCalendar::getSkippedWallTimeOption() - スキップされた実時間を扱う際の振る舞いを取得する


正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する

  • ≪ IntlCalendar::setRepeatedWallTimeOption
  • IntlCalendar::setTime ≫
  • PHP Manual
  • IntlCalendar
  • 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する

IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する

説明

オブジェクト指向型

public IntlCalendar::setSkippedWallTimeOption(int $option): true

手続き型

intlcal_set_skipped_wall_time_option(IntlCalendar $calendar, int $option): true

夏時間が始まった際に時間を進めた場合に、 スキップされる実時間をどう扱うかの戦略を設定します。 デフォルト値は IntlCalendar::WALLTIME_LAST (実時間を一時間進めたものと見なす) です。 別の値として、 IntlCalendar::WALLTIME_FIRST (一時間少ない実時間を採用する) および IntlCalendar::WALLTIME_NEXT_VALID (夏時間が始まった瞬間を採用する) があります。

このオプションは、カレンダーが表現する瞬間 (IntlCalendar::getTime() が返す値) にのみ影響します。 フィールドの値は決して上書きされません。

このオプションを有効にするには、 カレンダーの 緩いモード がONになっている必要があります。 そうでない場合、存在しない時刻を設定しようとしてエラーが発生します。

この関数を使うには、ICU 4.9 以降が必要です。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

option

IntlCalendar::WALLTIME_FIRST,
IntlCalendar::WALLTIME_LAST,
IntlCalendar::WALLTIME_NEXT_VALID
のいずれかを指定します。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

IntlCalendar::getSkippedWallTimeOption() の例を参照ください。

参考

  • intlCalendar::getSkippedWallTimeOption() - スキップされた実時間を扱う際の振る舞いを取得する
  • intlCalendar::setRepeatedWallTimeOption() - 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する
  • intlCalendar::getRepeatedWallTimeOption() - 繰り返される実時間を扱う際の振る舞いを取得する


エポックからのカレンダーの時刻をミリ秒単位で設定する

  • ≪ IntlCalendar::setSkippedWallTimeOption
  • IntlCalendar::setTimeZone ≫
  • PHP Manual
  • IntlCalendar
  • エポックからのカレンダーの時刻をミリ秒単位で設定する

IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — エポックからのカレンダーの時刻をミリ秒単位で設定する

説明

オブジェクト指向型

public IntlCalendar::setTime(float $timestamp): bool

手続き型

intlcal_set_time(IntlCalendar $calendar, float $timestamp): bool

このオブジェクトで表される瞬間を設定します。 瞬間とは、エポック(1 Jan 1970 00:00:00.000 UTC) からの経過時刻をミリ秒単位の整数値で表したもので、 うるう秒を無視したものです。 全てのフィールドの値はそれに従って再計算されます。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

timestamp

エポックからその瞬間までの経過時間のうち、 うるう秒を無視したものをミリ秒で表したもの。

戻り値

成功時に true を返します。 失敗時に false を返します。

例

例1 IntlCalendar::setTime()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'fr_FR');

$cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

/* In Europe/Lisbon, on 2013-10-27 at 0200, the clock goes back one hour and
the timezone from UTC+01 to UTC+00 */

$cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

$cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

上の例の出力は以下となります。

samedi 1 juin 2013 12:00:00 heure avancee d'Europe de l'Ouest
dimanche 27 octobre 2013 01:30:00 heure avancee d'Europe de l'Ouest
dimanche 27 octobre 2013 01:30:00 heure normale d'Europe de l'Ouest


このカレンダーで使うタイムゾーンを設定する

  • ≪ IntlCalendar::setTime
  • IntlCalendar::toDateTime ≫
  • PHP Manual
  • IntlCalendar
  • このカレンダーで使うタイムゾーンを設定する

IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — このカレンダーで使うタイムゾーンを設定する

説明

オブジェクト指向型

public IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null $timezone): bool

手続き型

intlcal_set_time_zone(IntlCalendar $calendar, IntlTimeZone|DateTimeZone|string|null $timezone): bool

このカレンダーで使う新しいタイムゾーンを定義します。 このオブジェクトの時刻は、 フィールドの値を保持したまま表現されます。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

timezone

このカレンダーで使う新しいタイムゾーン。 以下のやり方で指定できます:

  • null。この場合はデフォルトのタイムゾーンを使います。デフォルトは、ini 項目 date.timezone で設定したものか、 date_default_timezone_set() 関数で指定したもの (そして date_default_timezone_get() が返すもの) になります。

  • IntlTimeZone。これを直接使います。

  • DateTimeZone。その識別子を取り出して、ICU タイムゾーンオブジェクトを作ります。 つまり、これは ICU のデータベースに基づくタイムゾーンとなり、PHP のタイムゾーンデータベースに基づくものではありません。

  • 文字列。ICU タイムゾーン識別子として有効なものを指定します。 IntlTimeZone::createTimeZoneIDEnumeration() を参照ください。 "GMT+08:30" などのオフセットも指定できます。

戻り値

成功時に true を返します。 失敗時に false を返します。 Returns true on success and false on failure.

例

例1 IntlCalendar::setTimeZone()

<?php
ini_set('date.timezone', 'Europe/Lisbon');
ini_set('intl.default_locale', 'es_ES');

$cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
echo "(instant {$cal->getTime()})\n";

$cal->setTimeZone(IntlTimeZone::getGMT());
echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
echo "(instant {$cal->getTime()})\n";

$cal->setTimeZone('GMT+03:33');
echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
echo "(instant {$cal->getTime()})\n";

上の例の出力は以下となります。

sabado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
(instant 1370084400000)
sabado, 1 de junio de 2013 11:00:00 GMT
(instant 1370084400000)
sabado, 1 de junio de 2013 14:33:00 GMT+03:33
(instant 1370084400000)


IntlCalendar を DateTime オブジェクトに変換する

  • ≪ IntlCalendar::setTimeZone
  • IntlGregorianCalendar ≫
  • PHP Manual
  • IntlCalendar
  • IntlCalendar を DateTime オブジェクトに変換する

IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — IntlCalendar を DateTime オブジェクトに変換する

説明

オブジェクト指向型

public IntlCalendar::toDateTime(): DateTime|false

手続き型

intlcal_to_date_time(IntlCalendar $calendar): DateTime|false

同じ瞬間 (精度は秒単位で、丸めエラーは1秒以下) を表現し、このオブジェクトのタイムゾーン (DateTime のタイムゾーンは、 PHP のタイムゾーンに依存しているのに対し、 IntlCalendar のタイムゾーンは ICU のそれに依存している点が異なります) を持つ DateTime オブジェクトを生成します。

パラメータ

calendar

IntlCalendar クラスのインスタンス。

戻り値

このオブジェクトと同じ (但し、ICU ではなく PHP のデータベースを使った) タイムゾーンと、同じ時刻 (精度はミリ秒ではなく秒単位) を保持した DateTime を返します。 失敗した場合は false を返します。

例

例1 IntlCalendar::toDateTime()

<?php
ini_set('date.timezone', 'UTC');
ini_set('intl.default_locale', 'pt_PT');

$cal = IntlCalendar::createInstance('Europe/Lisbon'); //current time

$dt = $cal->toDateTime();
print_r($dt);

上の例の出力は以下となります。

DateTime Object
(
    [date] => 2013-07-02 00:29:13
    [timezone_type] => 3
    [timezone] => Europe/Lisbon
)

参考

  • IntlCalendar::fromDateTime() - DateTime オブジェクトまたは文字列から、IntlCalendar を作成する
  • IntlCalendar::getTime() - このオブジェクトが表す時刻を取得する
  • IntlCalendar::createInstance() - 新しい IntlCalendar を作成する
  • DateTime::__construct() - 新しい DateTime オブジェクトを返す


IntlGregorianCalendar クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

クラス概要

class IntlGregorianCalendar extends IntlCalendar {
/* 継承した定数 */
public const int IntlCalendar::FIELD_ERA;
public const int IntlCalendar::FIELD_YEAR;
public const int IntlCalendar::FIELD_MONTH;
public const int IntlCalendar::FIELD_WEEK_OF_YEAR;
public const int IntlCalendar::FIELD_WEEK_OF_MONTH;
public const int IntlCalendar::FIELD_DATE;
public const int IntlCalendar::FIELD_DAY_OF_YEAR;
public const int IntlCalendar::FIELD_DAY_OF_WEEK;
public const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH;
public const int IntlCalendar::FIELD_AM_PM;
public const int IntlCalendar::FIELD_HOUR;
public const int IntlCalendar::FIELD_HOUR_OF_DAY;
public const int IntlCalendar::FIELD_MINUTE;
public const int IntlCalendar::FIELD_SECOND;
public const int IntlCalendar::FIELD_MILLISECOND;
public const int IntlCalendar::FIELD_ZONE_OFFSET;
public const int IntlCalendar::FIELD_DST_OFFSET;
public const int IntlCalendar::FIELD_YEAR_WOY;
public const int IntlCalendar::FIELD_DOW_LOCAL;
public const int IntlCalendar::FIELD_EXTENDED_YEAR;
public const int IntlCalendar::FIELD_JULIAN_DAY;
public const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY;
public const int IntlCalendar::FIELD_IS_LEAP_MONTH;
public const int IntlCalendar::FIELD_FIELD_COUNT;
public const int IntlCalendar::FIELD_DAY_OF_MONTH;
public const int IntlCalendar::DOW_SUNDAY;
public const int IntlCalendar::DOW_MONDAY;
public const int IntlCalendar::DOW_TUESDAY;
public const int IntlCalendar::DOW_WEDNESDAY;
public const int IntlCalendar::DOW_THURSDAY;
public const int IntlCalendar::DOW_FRIDAY;
public const int IntlCalendar::DOW_SATURDAY;
public const int IntlCalendar::DOW_TYPE_WEEKDAY;
public const int IntlCalendar::DOW_TYPE_WEEKEND;
public const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET;
public const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE;
public const int IntlCalendar::WALLTIME_FIRST;
public const int IntlCalendar::WALLTIME_LAST;
public const int IntlCalendar::WALLTIME_NEXT_VALID;
/* メソッド */
public __construct(IntlTimeZone $tz = ?, string $locale = ?)
public __construct(int $timeZoneOrYear, int $localeOrMonth, int $dayOfMonth)
public __construct(
int $timeZoneOrYear,
int $localeOrMonth,
int $dayOfMonth,
int $hour,
int $minute,
int $second = ?
)
public static createFromDate(int $year, int $month, int $dayOfMonth): static
public static createFromDateTime(
int $year,
int $month,
int $dayOfMonth,
int $hour,
int $minute,
?int $second = null
): static
public getGregorianChange(): float
public isLeapYear(int $year): bool
public setGregorianChange(float $timestamp): bool
/* 継承したメソッド */
public IntlCalendar::add(int $field, int $value): bool
public IntlCalendar::after(IntlCalendar $other): bool
public IntlCalendar::before(IntlCalendar $other): bool
public IntlCalendar::clear(?int $field = null): true
public static IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null $timezone = null, ?string $locale = null): ?IntlCalendar
public IntlCalendar::equals(IntlCalendar $other): bool
public IntlCalendar::fieldDifference(float $timestamp, int $field): int|false
public static IntlCalendar::fromDateTime(DateTime|string $datetime, ?string $locale = null): ?IntlCalendar
public IntlCalendar::get(int $field): int|false
public IntlCalendar::getActualMaximum(int $field): int|false
public IntlCalendar::getActualMinimum(int $field): int|false
public static IntlCalendar::getAvailableLocales(): array
public IntlCalendar::getDayOfWeekType(int $dayOfWeek): int|false
public IntlCalendar::getErrorCode(): int|false
public IntlCalendar::getErrorMessage(): string|false
public IntlCalendar::getFirstDayOfWeek(): int|false
public IntlCalendar::getGreatestMinimum(int $field): int|false
public static IntlCalendar::getKeywordValuesForLocale(string $keyword, string $locale, bool $onlyCommon): IntlIterator|false
public IntlCalendar::getLeastMaximum(int $field): int|false
public IntlCalendar::getLocale(int $type): string|false
public IntlCalendar::getMaximum(int $field): int|false
public IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public IntlCalendar::getMinimum(int $field): int|false
public static IntlCalendar::getNow(): float
public IntlCalendar::getRepeatedWallTimeOption(): int
public IntlCalendar::getSkippedWallTimeOption(): int
public IntlCalendar::getTime(): float|false
public IntlCalendar::getTimeZone(): IntlTimeZone|false
public IntlCalendar::getType(): string
public IntlCalendar::getWeekendTransition(int $dayOfWeek): int|false
public IntlCalendar::inDaylightTime(): bool
public IntlCalendar::isEquivalentTo(IntlCalendar $other): bool
public IntlCalendar::isLenient(): bool
public IntlCalendar::isSet(int $field): bool
public IntlCalendar::isWeekend(?float $timestamp = null): bool
public IntlCalendar::roll(int $field, int|bool $value): bool
public IntlCalendar::set(int $field, int $value): true
public IntlCalendar::set(
int $year,
int $month,
int $dayOfMonth = NULL,
int $hour = NULL,
int $minute = NULL,
int $second = NULL
): true
public IntlCalendar::setDate(int $year, int $month, int $dayOfMonth): void
public IntlCalendar::setDateTime(
int $year,
int $month,
int $dayOfMonth,
int $hour,
int $minute,
?int $second = null
): void
public IntlCalendar::setFirstDayOfWeek(int $dayOfWeek): true
public IntlCalendar::setLenient(bool $lenient): true
public IntlCalendar::setMinimalDaysInFirstWeek(int $days): true
public IntlCalendar::setRepeatedWallTimeOption(int $option): true
public IntlCalendar::setSkippedWallTimeOption(int $option): true
public IntlCalendar::setTime(float $timestamp): bool
public IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null $timezone): bool
public IntlCalendar::toDateTime(): DateTime|false
}

目次

  • IntlGregorianCalendar::__construct — グレゴリオ暦の Calendar クラスを作成する
  • IntlGregorianCalendar::createFromDate — 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する
  • IntlGregorianCalendar::createFromDateTime — 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する
  • IntlGregorianCalendar::getGregorianChange — グレゴリオ暦への切換え日を取得する
  • IntlGregorianCalendar::isLeapYear — 指定された年がうるう年かを判定する
  • IntlGregorianCalendar::setGregorianChange — グレゴリオ暦への切換え日を設定する


グレゴリオ暦の Calendar クラスを作成する

  • ≪ IntlGregorianCalendar
  • IntlGregorianCalendar::createFromDate ≫
  • PHP Manual
  • IntlGregorianCalendar
  • グレゴリオ暦の Calendar クラスを作成する

IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — グレゴリオ暦の Calendar クラスを作成する

説明

public IntlGregorianCalendar::__construct(IntlTimeZone $tz = ?, string $locale = ?)
public IntlGregorianCalendar::__construct(int $timeZoneOrYear, int $localeOrMonth, int $dayOfMonth)
public IntlGregorianCalendar::__construct(
int $timeZoneOrYear,
int $localeOrMonth,
int $dayOfMonth,
int $hour,
int $minute,
int $second = ?
)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tz

locale

timeZoneOrYear

localeOrMonth

dayOfMonth

hour

minute

second


日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する

  • ≪ IntlGregorianCalendar::__construct
  • IntlGregorianCalendar::createFromDateTime ≫
  • PHP Manual
  • IntlGregorianCalendar
  • 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する

IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する

説明

public static IntlGregorianCalendar::createFromDate(int $year, int $month, int $dayOfMonth): static

日付の情報から、 新しい IntlGregorianCalendar のインスタンスを作成します。

パラメータ

year

IntlGregorianCalendar::FIELD_YEAR の新しい値

month

IntlGregorianCalendar::FIELD_MONTH の新しい値。 月の数値は0から始まります。1月は0、2月は1、のように続き、 12月は11になります。(カレンダーに存在していれば) Undecember が12になります。

dayOfMonth

IntlGregorianCalendar::FIELD_DAY_OF_MONTH の新しい値

戻り値

新しい IntlGregorianCalendar のインスタンスを返します。

例

例1 IntlGregorianCalendar::createFromDate() の例

<?php

$intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
var_dump($intlCalendar);
?>

上の例の出力は、 たとえば以下のようになります。

object(IntlGregorianCalendar)#1 (5) {
  ["valid"]=>
  bool(true)
  ["type"]=>
  string(9) "gregorian"
  ["timeZone"]=>
  array(4) {
    ["valid"]=>
    bool(true)
    ["id"]=>
    string(16) "Europe/Amsterdam"
    ["rawOffset"]=>
    int(3600000)
    ["currentOffset"]=>
    int(3600000)
  }
  ["locale"]=>
  string(11) "en_US_POSIX"
  ["fields"]=>
  array(23) {
    ["era"]=>
    int(1)
    ["year"]=>
    int(2023)
    ["month"]=>
    int(11)
    ["week of year"]=>
    int(51)
    ["week of month"]=>
    int(4)
    ["day of year"]=>
    int(357)
    ["day of month"]=>
    int(23)
    ["day of week"]=>
    int(7)
    ["day of week in month"]=>
    int(4)
    ["AM/PM"]=>
    int(0)
    ["hour"]=>
    int(0)
    ["hour of day"]=>
    int(0)
    ["minute"]=>
    int(0)
    ["second"]=>
    int(0)
    ["millisecond"]=>
    int(0)
    ["zone offset"]=>
    int(3600000)
    ["DST offset"]=>
    int(0)
    ["year for week of year"]=>
    int(2023)
    ["localized day of week"]=>
    int(7)
    ["extended year"]=>
    int(2023)
    ["julian day"]=>
    int(2460302)
    ["milliseconds in day"]=>
    int(0)
    ["is leap month"]=>
    int(0)
  }
}

参考

  • IntlGregorianCalendar::createFromDateTime() - 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する


日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する

  • ≪ IntlGregorianCalendar::createFromDate
  • IntlGregorianCalendar::getGregorianChange ≫
  • PHP Manual
  • IntlGregorianCalendar
  • 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する

IntlGregorianCalendar::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する

説明

public static IntlGregorianCalendar::createFromDateTime(
int $year,
int $month,
int $dayOfMonth,
int $hour,
int $minute,
?int $second = null
): static

日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成します。

パラメータ

year

IntlGregorianCalendar::FIELD_YEAR の新しい値

month

IntlGregorianCalendar::FIELD_MONTH の新しい値。 月の数値は0から始まります。1月は0、2月は1、のように続き、 12月は11になります。(カレンダーに存在していれば) Undecember が12になります。

dayOfMonth

IntlGregorianCalendar::FIELD_DAY_OF_MONTH の新しい値

hour

IntlGregorianCalendar::FIELD_HOUR_OF_DAY の新しい値

minute

IntlGregorianCalendar::FIELD_MINUTE の新しい値

second

IntlGregorianCalendar::FIELD_SECOND の新しい値

戻り値

新しい IntlGregorianCalendar のインスタンスを返します。

例

例1 IntlGregorianCalendar::createFromDateTime() の例

<?php

$intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
var_dump($intlCalendar);
?>

上の例の出力は、 たとえば以下のようになります。

object(IntlGregorianCalendar)#1 (5) {
  ["valid"]=>
  bool(true)
  ["type"]=>
  string(9) "gregorian"
  ["timeZone"]=>
  array(4) {
    ["valid"]=>
    bool(true)
    ["id"]=>
    string(16) "Europe/Amsterdam"
    ["rawOffset"]=>
    int(3600000)
    ["currentOffset"]=>
    int(3600000)
  }
  ["locale"]=>
  string(11) "en_US_POSIX"
  ["fields"]=>
  array(23) {
    ["era"]=>
    int(1)
    ["year"]=>
    int(2023)
    ["month"]=>
    int(11)
    ["week of year"]=>
    int(51)
    ["week of month"]=>
    int(4)
    ["day of year"]=>
    int(357)
    ["day of month"]=>
    int(23)
    ["day of week"]=>
    int(7)
    ["day of week in month"]=>
    int(4)
    ["AM/PM"]=>
    int(1)
    ["hour"]=>
    int(0)
    ["hour of day"]=>
    int(12)
    ["minute"]=>
    int(0)
    ["second"]=>
    int(0)
    ["millisecond"]=>
    int(0)
    ["zone offset"]=>
    int(3600000)
    ["DST offset"]=>
    int(0)
    ["year for week of year"]=>
    int(2023)
    ["localized day of week"]=>
    int(7)
    ["extended year"]=>
    int(2023)
    ["julian day"]=>
    int(2460302)
    ["milliseconds in day"]=>
    int(43200000)
    ["is leap month"]=>
    int(0)
  }
}

参考

  • IntlGregorianCalendar::createFromDate() - 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する


グレゴリオ暦への切換え日を取得する

  • ≪ IntlGregorianCalendar::createFromDateTime
  • IntlGregorianCalendar::isLeapYear ≫
  • PHP Manual
  • IntlGregorianCalendar
  • グレゴリオ暦への切換え日を取得する

IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — グレゴリオ暦への切換え日を取得する

説明

public IntlGregorianCalendar::getGregorianChange(): float

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

切替日を返します。


指定された年がうるう年かを判定する

  • ≪ IntlGregorianCalendar::getGregorianChange
  • IntlGregorianCalendar::setGregorianChange ≫
  • PHP Manual
  • IntlGregorianCalendar
  • 指定された年がうるう年かを判定する

IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — 指定された年がうるう年かを判定する

説明

public IntlGregorianCalendar::isLeapYear(int $year): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

year

戻り値

うるう年の場合、true を返します。 そうでない場合や、失敗した場合は false を返します。


グレゴリオ暦への切換え日を設定する

  • ≪ IntlGregorianCalendar::isLeapYear
  • IntlTimeZone ≫
  • PHP Manual
  • IntlGregorianCalendar
  • グレゴリオ暦への切換え日を設定する

IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — グレゴリオ暦への切換え日を設定する

説明

public IntlGregorianCalendar::setGregorianChange(float $timestamp): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timestamp

戻り値

成功した場合に true を、失敗した場合に false を返します。


IntlTimeZone クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

はじめに

クラス概要

class IntlTimeZone {
/* 定数 */
public const int DISPLAY_SHORT;
public const int DISPLAY_LONG;
public const int DISPLAY_SHORT_GENERIC;
public const int DISPLAY_LONG_GENERIC;
public const int DISPLAY_SHORT_GMT;
public const int DISPLAY_LONG_GMT;
public const int DISPLAY_SHORT_COMMONLY_USED;
public const int DISPLAY_GENERIC_LOCATION;
public const int TYPE_ANY;
public const int TYPE_CANONICAL;
public const int TYPE_CANONICAL_LOCATION;
/* メソッド */
private __construct()
public static countEquivalentIDs(string $timezoneId): int|false
public static createDefault(): IntlTimeZone
public static createEnumeration(IntlTimeZone|string|int|float|null $countryOrRawOffset = null): IntlIterator|false
public static createTimeZone(string $timezoneId): ?IntlTimeZone
public static createTimeZoneIDEnumeration(int $type, ?string $region = null, ?int $rawOffset = null): IntlIterator|false
public static fromDateTimeZone(DateTimeZone $timezone): ?IntlTimeZone
public static getCanonicalID(string $timezoneId, bool &$isSystemId = null): string|false
public getDisplayName(bool $dst = false, int $style = IntlTimeZone::DISPLAY_LONG, ?string $locale = null): string|false
public getDSTSavings(): int
public static getEquivalentID(string $timezoneId, int $offset): string|false
public getErrorCode(): int|false
public getErrorMessage(): string|false
public static getGMT(): IntlTimeZone
public getID(): string|false
public static getIDForWindowsID(string $timezoneId, ?string $region = null): string|false
public getOffset(
float $timestamp,
bool $local,
int &$rawOffset,
int &$dstOffset
): bool
public getRawOffset(): int
public static getRegion(string $timezoneId): string|false
public static getTZDataVersion(): string|false
public static getUnknown(): IntlTimeZone
public static getWindowsID(string $timezoneId): string|false
public hasSameRules(IntlTimeZone $other): bool
public toDateTimeZone(): DateTimeZone|false
public useDaylightTime(): bool
}

定義済み定数

IntlTimeZone::DISPLAY_SHORT

IntlTimeZone::DISPLAY_LONG

IntlTimeZone::DISPLAY_SHORT_GENERIC

IntlTimeZone::DISPLAY_LONG_GENERIC

IntlTimeZone::DISPLAY_SHORT_GMT

IntlTimeZone::DISPLAY_LONG_GMT

IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED

IntlTimeZone::DISPLAY_GENERIC_LOCATION

IntlTimeZone::TYPE_ANY

IntlTimeZone::TYPE_CANONICAL

IntlTimeZone::TYPE_CANONICAL_LOCATION

目次

  • IntlTimeZone::__construct — インスタンス化を禁止するためのprivateなコンストラクタ
  • IntlTimeZone::countEquivalentIDs — 指定した ID を含む等価グループの中にある ID の数を取得する
  • IntlTimeZone::createDefault — このホストのデフォルトタイムゾーンの新しいコピーを作る
  • IntlTimeZone::createEnumeration — 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する
  • IntlTimeZone::createTimeZone — 指定した ID のタイムゾーンオブジェクトを作る
  • IntlTimeZone::createTimeZoneIDEnumeration — 指定されたフィルタ条件を反映した、システムタイムゾーンのイテレータを取得する
  • IntlTimeZone::fromDateTimeZone — DateTimeZone からタイムゾーンオブジェクトを作る
  • IntlTimeZone::getCanonicalID — 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する
  • IntlTimeZone::getDisplayName — このタイムゾーンの、ユーザー向けに表示する名前を取得する
  • IntlTimeZone::getDSTSavings — ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する
  • IntlTimeZone::getEquivalentID — 指定した ID を含む等価グループの ID を取得する
  • IntlTimeZone::getErrorCode — 直近のエラーコードを取得する
  • IntlTimeZone::getErrorMessage — 直近のエラーメッセージを取得する
  • IntlTimeZone::getGMT — GMT (UTC) タイムゾーンを作る
  • IntlTimeZone::getID — タイムゾーン ID を取得する
  • IntlTimeZone::getIDForWindowsID — Windows のタイムゾーンを、システムタイムゾーンに翻訳する
  • IntlTimeZone::getOffset — 指定した時刻の、GMT へのオフセットを取得する
  • IntlTimeZone::getRawOffset — (夏時間を考慮せずに) GMT へのオフセットを取得する
  • IntlTimeZone::getRegion — 指定されたシステムタイムゾーンのIDから、地域コードを取得する
  • IntlTimeZone::getTZDataVersion — ICU が使っているタイムゾーンデータのバージョンを取得する
  • IntlTimeZone::getUnknown — "unknown" なタイムゾーンを取得する
  • IntlTimeZone::getWindowsID — システムタイムゾーンを、Windows のタイムゾーンに翻訳する
  • IntlTimeZone::hasSameRules — このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる
  • IntlTimeZone::toDateTimeZone — DateTimeZone オブジェクトに変換する
  • IntlTimeZone::useDaylightTime — このタイムゾーンが夏時間を採用しているかどうかを調べる


インスタンス化を禁止するためのprivateなコンストラクタ

  • ≪ IntlTimeZone
  • IntlTimeZone::countEquivalentIDs ≫
  • PHP Manual
  • IntlTimeZone
  • インスタンス化を禁止するためのprivateなコンストラクタ

IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — インスタンス化を禁止するためのprivateなコンストラクタ

説明

private IntlTimeZone::__construct()

パラメータ

この関数にはパラメータはありません。


指定した ID を含む等価グループの中にある ID の数を取得する

  • ≪ IntlTimeZone::__construct
  • IntlTimeZone::createDefault ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した ID を含む等価グループの中にある ID の数を取得する

IntlTimeZone::countEquivalentIDs

intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — 指定した ID を含む等価グループの中にある ID の数を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::countEquivalentIDs(string $timezoneId): int|false

手続き型:

intltz_count_equivalent_ids(string $timezoneId): int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

戻り値


このホストのデフォルトタイムゾーンの新しいコピーを作る

  • ≪ IntlTimeZone::countEquivalentIDs
  • IntlTimeZone::createEnumeration ≫
  • PHP Manual
  • IntlTimeZone
  • このホストのデフォルトタイムゾーンの新しいコピーを作る

IntlTimeZone::createDefault

intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — このホストのデフォルトタイムゾーンの新しいコピーを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createDefault(): IntlTimeZone

手続き型:

intltz_create_default(): IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する

  • ≪ IntlTimeZone::createDefault
  • IntlTimeZone::createTimeZone ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する

IntlTimeZone::createEnumeration

intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createEnumeration(IntlTimeZone|string|int|float|null $countryOrRawOffset = null): IntlIterator|false

手続き型:

intltz_create_enumeration(IntlTimeZone|string|int|float|null $countryOrRawOffset = null): IntlIterator|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

countryOrRawOffset

戻り値


指定した ID のタイムゾーンオブジェクトを作る

  • ≪ IntlTimeZone::createEnumeration
  • IntlTimeZone::createTimeZoneIDEnumeration ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した ID のタイムゾーンオブジェクトを作る

IntlTimeZone::createTimeZone

intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — 指定した ID のタイムゾーンオブジェクトを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createTimeZone(string $timezoneId): ?IntlTimeZone

手続き型:

intltz_create_time_zone(string $timezoneId): ?IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

戻り値


指定されたフィルタ条件を反映した、システムタイムゾーンのイテレータを取得する

  • ≪ IntlTimeZone::createTimeZone
  • IntlTimeZone::fromDateTimeZone ≫
  • PHP Manual
  • IntlTimeZone
  • 指定されたフィルタ条件を反映した、システムタイムゾーンのイテレータを取得する

IntlTimeZone::createTimeZoneIDEnumeration

intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — 指定されたフィルタ条件を反映した、システムタイムゾーンのイテレータを取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::createTimeZoneIDEnumeration(int $type, ?string $region = null, ?int $rawOffset = null): IntlIterator|false

手続き型:

intltz_create_time_zone_id_enumeration(int $type, ?string $region = null, ?int $rawOffset = null): IntlIterator|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

type

region

rawOffset

戻り値

IntlIterator を返します。 失敗した場合に false を返します.


DateTimeZone からタイムゾーンオブジェクトを作る

  • ≪ IntlTimeZone::createTimeZoneIDEnumeration
  • IntlTimeZone::getCanonicalID ≫
  • PHP Manual
  • IntlTimeZone
  • DateTimeZone からタイムゾーンオブジェクトを作る

IntlTimeZone::fromDateTimeZone

intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — DateTimeZone からタイムゾーンオブジェクトを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::fromDateTimeZone(DateTimeZone $timezone): ?IntlTimeZone

手続き型:

intltz_from_date_time_zone(DateTimeZone $timezone): ?IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezone

戻り値


指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する

  • ≪ IntlTimeZone::fromDateTimeZone
  • IntlTimeZone::getDisplayName ≫
  • PHP Manual
  • IntlTimeZone
  • 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する

IntlTimeZone::getCanonicalID

intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getCanonicalID(string $timezoneId, bool &$isSystemId = null): string|false

手続き型:

intltz_get_canonical_id(string $timezoneId, bool &$isSystemId = null): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

isSystemId

戻り値


このタイムゾーンの、ユーザー向けに表示する名前を取得する

  • ≪ IntlTimeZone::getCanonicalID
  • IntlTimeZone::getDSTSavings ≫
  • PHP Manual
  • IntlTimeZone
  • このタイムゾーンの、ユーザー向けに表示する名前を取得する

IntlTimeZone::getDisplayName

intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — このタイムゾーンの、ユーザー向けに表示する名前を取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getDisplayName(bool $dst = false, int $style = IntlTimeZone::DISPLAY_LONG, ?string $locale = null): string|false

手続き型:

intltz_get_display_name(
IntlTimeZone $timezone,
bool $dst = false,
int $style = IntlTimeZone::DISPLAY_LONG,
?string $locale = null
): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

dst

style

locale

戻り値


ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する

  • ≪ IntlTimeZone::getDisplayName
  • IntlTimeZone::getEquivalentID ≫
  • PHP Manual
  • IntlTimeZone
  • ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する

IntlTimeZone::getDSTSavings

intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getDSTSavings(): int

手続き型:

intltz_get_dst_savings(IntlTimeZone $timezone): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


指定した ID を含む等価グループの ID を取得する

  • ≪ IntlTimeZone::getDSTSavings
  • IntlTimeZone::getErrorCode ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した ID を含む等価グループの ID を取得する

IntlTimeZone::getEquivalentID

intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — 指定した ID を含む等価グループの ID を取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getEquivalentID(string $timezoneId, int $offset): string|false

手続き型:

intltz_get_equivalent_id(string $timezoneId, int $offset): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

offset

戻り値


直近のエラーコードを取得する

  • ≪ IntlTimeZone::getEquivalentID
  • IntlTimeZone::getErrorMessage ≫
  • PHP Manual
  • IntlTimeZone
  • 直近のエラーコードを取得する

IntlTimeZone::getErrorCode

intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — 直近のエラーコードを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getErrorCode(): int|false

手続き型:

intltz_get_error_code(IntlTimeZone $timezone): int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


直近のエラーメッセージを取得する

  • ≪ IntlTimeZone::getErrorCode
  • IntlTimeZone::getGMT ≫
  • PHP Manual
  • IntlTimeZone
  • 直近のエラーメッセージを取得する

IntlTimeZone::getErrorMessage

intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — 直近のエラーメッセージを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getErrorMessage(): string|false

手続き型:

intltz_get_error_message(IntlTimeZone $timezone): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


GMT (UTC) タイムゾーンを作る

  • ≪ IntlTimeZone::getErrorMessage
  • IntlTimeZone::getID ≫
  • PHP Manual
  • IntlTimeZone
  • GMT (UTC) タイムゾーンを作る

IntlTimeZone::getGMT

intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — GMT (UTC) タイムゾーンを作る

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getGMT(): IntlTimeZone

手続き型:

intltz_get_gmt(): IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


タイムゾーン ID を取得する

  • ≪ IntlTimeZone::getGMT
  • IntlTimeZone::getIDForWindowsID ≫
  • PHP Manual
  • IntlTimeZone
  • タイムゾーン ID を取得する

IntlTimeZone::getID

intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — タイムゾーン ID を取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getID(): string|false

手続き型:

intltz_get_id(IntlTimeZone $timezone): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Windows のタイムゾーンを、システムタイムゾーンに翻訳する

  • ≪ IntlTimeZone::getID
  • IntlTimeZone::getOffset ≫
  • PHP Manual
  • IntlTimeZone
  • Windows のタイムゾーンを、システムタイムゾーンに翻訳する

IntlTimeZone::getIDForWindowsID

intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Windows のタイムゾーンを、システムタイムゾーンに翻訳する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getIDForWindowsID(string $timezoneId, ?string $region = null): string|false

手続き型:

intltz_get_id_for_windows_id(string $timezoneId, ?string $region = null): string|false

Windows のタイムゾーン (例: "Pacific Standard Time") を、システムタイムゾーン (例: "America/Los_Angeles") に翻訳します。

注意: この関数を使うには、ICU version ? 52 が必要です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

region

戻り値

システムタイムゾーンを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | region は、nullable になりました。

参考

  • IntlTimeZone::getWindowsID() - システムタイムゾーンを、Windows のタイムゾーンに翻訳する


指定した時刻の、GMT へのオフセットを取得する

  • ≪ IntlTimeZone::getIDForWindowsID
  • IntlTimeZone::getRawOffset ≫
  • PHP Manual
  • IntlTimeZone
  • 指定した時刻の、GMT へのオフセットを取得する

IntlTimeZone::getOffset

intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — 指定した時刻の、GMT へのオフセットを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getOffset(
float $timestamp,
bool $local,
int &$rawOffset,
int &$dstOffset
): bool

手続き型:

intltz_get_offset(
IntlTimeZone $timezone,
float $timestamp,
bool $local,
int &$rawOffset,
int &$dstOffset
): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timestamp

local

rawOffset

dstOffset

戻り値


(夏時間を考慮せずに) GMT へのオフセットを取得する

  • ≪ IntlTimeZone::getOffset
  • IntlTimeZone::getRegion ≫
  • PHP Manual
  • IntlTimeZone
  • (夏時間を考慮せずに) GMT へのオフセットを取得する

IntlTimeZone::getRawOffset

intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — (夏時間を考慮せずに) GMT へのオフセットを取得する

説明

オブジェクト指向型 (method):

public IntlTimeZone::getRawOffset(): int

手続き型:

intltz_get_raw_offset(IntlTimeZone $timezone): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


指定されたシステムタイムゾーンのIDから、地域コードを取得する

  • ≪ IntlTimeZone::getRawOffset
  • IntlTimeZone::getTZDataVersion ≫
  • PHP Manual
  • IntlTimeZone
  • 指定されたシステムタイムゾーンのIDから、地域コードを取得する

IntlTimeZone::getRegion

intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — 指定されたシステムタイムゾーンのIDから、地域コードを取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getRegion(string $timezoneId): string|false

手続き型:

intltz_get_region(string $timezoneId): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

戻り値

地域コードを返します。 失敗した場合に false を返します.


ICU が使っているタイムゾーンデータのバージョンを取得する

  • ≪ IntlTimeZone::getRegion
  • IntlTimeZone::getUnknown ≫
  • PHP Manual
  • IntlTimeZone
  • ICU が使っているタイムゾーンデータのバージョンを取得する

IntlTimeZone::getTZDataVersion

intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — ICU が使っているタイムゾーンデータのバージョンを取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getTZDataVersion(): string|false

手続き型:

intltz_get_tz_data_version(): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


"unknown" なタイムゾーンを取得する

  • ≪ IntlTimeZone::getTZDataVersion
  • IntlTimeZone::getWindowsID ≫
  • PHP Manual
  • IntlTimeZone
  • "unknown" なタイムゾーンを取得する

IntlTimeZone::getUnknown

intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — "unknown" なタイムゾーンを取得する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getUnknown(): IntlTimeZone

手続き型:

intltz_get_unknown(): IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

IntlTimeZone を返します。 失敗した場合は null を返します。


システムタイムゾーンを、Windows のタイムゾーンに翻訳する

  • ≪ IntlTimeZone::getUnknown
  • IntlTimeZone::hasSameRules ≫
  • PHP Manual
  • IntlTimeZone
  • システムタイムゾーンを、Windows のタイムゾーンに翻訳する

IntlTimeZone::getWindowsID

intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — システムタイムゾーンを、Windows のタイムゾーンに翻訳する

説明

オブジェクト指向型 (method):

public static IntlTimeZone::getWindowsID(string $timezoneId): string|false

手続き型:

intltz_get_windows_id(string $timezoneId): string|false

システムタイムゾーン (例: "America/Los_Angeles") を、 Windows のタイムゾーン (例: "Pacific Standard Time") に翻訳します。

注意: この関数を使うには、ICU version ? 52 が必要です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timezoneId

戻り値

Windows のタイムゾーンを返します。 失敗した場合に false を返します.

参考

  • IntlTimeZone::getIDForWindowsID() - Windows のタイムゾーンを、システムタイムゾーンに翻訳する


このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる

  • ≪ IntlTimeZone::getWindowsID
  • IntlTimeZone::toDateTimeZone ≫
  • PHP Manual
  • IntlTimeZone
  • このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる

IntlTimeZone::hasSameRules

intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる

説明

オブジェクト指向型 (method):

public IntlTimeZone::hasSameRules(IntlTimeZone $other): bool

手続き型:

intltz_has_same_rules(IntlTimeZone $timezone, IntlTimeZone $other): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

other

戻り値


DateTimeZone オブジェクトに変換する

  • ≪ IntlTimeZone::hasSameRules
  • IntlTimeZone::useDaylightTime ≫
  • PHP Manual
  • IntlTimeZone
  • DateTimeZone オブジェクトに変換する

IntlTimeZone::toDateTimeZone

intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — DateTimeZone オブジェクトに変換する

説明

オブジェクト指向型 (method):

public IntlTimeZone::toDateTimeZone(): DateTimeZone|false

手続き型:

intltz_to_date_time_zone(IntlTimeZone $timezone): DateTimeZone|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


このタイムゾーンが夏時間を採用しているかどうかを調べる

  • ≪ IntlTimeZone::toDateTimeZone
  • IntlDateFormatter ≫
  • PHP Manual
  • IntlTimeZone
  • このタイムゾーンが夏時間を採用しているかどうかを調べる

IntlTimeZone::useDaylightTime

intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — このタイムゾーンが夏時間を採用しているかどうかを調べる

説明

オブジェクト指向型 (method):

public IntlTimeZone::useDaylightTime(): bool

手続き型:

intltz_use_daylight_time(IntlTimeZone $timezone): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


IntlDateFormatter クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

はじめに

Date Formatter は、パターン文字列や出来合いのパターンを使用して ロケールに依存する日付のフォーマット/パースを行う具象クラスです。

このクラスは ICU の日付フォーマット機能を表します。 これを使用すると、パターン文字列や出来合いのパターンを使用して 日付を各地域のフォーマットで表示したり、 文字列をパースして PHP の日付として扱ったりすることができます。

クラス概要

class IntlDateFormatter {
/* 定数 */
public const int FULL;
public const int LONG;
public const int MEDIUM;
public const int SHORT;
public const int NONE;
public const int RELATIVE_FULL;
public const int RELATIVE_LONG;
public const int RELATIVE_MEDIUM;
public const int RELATIVE_SHORT;
public const int GREGORIAN;
public const int TRADITIONAL;
/* メソッド */
public __construct(
?string $locale,
int $dateType = IntlDateFormatter::FULL,
int $timeType = IntlDateFormatter::FULL,
IntlTimeZone|DateTimeZone|string|null $timezone = null,
IntlCalendar|int|null $calendar = null,
?string $pattern = null
)
public static create(
?string $locale,
int $dateType = IntlDateFormatter::FULL,
int $timeType = IntlDateFormatter::FULL,
IntlTimeZone|DateTimeZone|string|null $timezone = null,
IntlCalendar|int|null $calendar = null,
?string $pattern = null
): ?IntlDateFormatter
public format(IntlCalendar|DateTimeInterface|array|string|int|float $datetime): string|false
public static formatObject(IntlCalendar|DateTimeInterface $datetime, array|int|string|null $format = null, ?string $locale = null): string|false
public getCalendar(): int|false
public getDateType(): int|false
public getErrorCode(): int
public getErrorMessage(): string
public getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false
public getPattern(): string|false
public getTimeType(): int|false
public getTimeZoneId(): string|false
public getCalendarObject(): IntlCalendar|false|null
public getTimeZone(): IntlTimeZone|false
public isLenient(): bool
public localtime(string $string, int &$offset = null): array|false
public parse(string $string, int &$offset = null): int|float|false
public setCalendar(IntlCalendar|int|null $calendar): bool
public setLenient(bool $lenient): void
public setPattern(string $pattern): bool
public setTimeZone(IntlTimeZone|DateTimeZone|string|null $timezone): bool
}

参考

  • » ICU Date formatter
  • » ICU Date formats

定義済み定数

これらの定数は、DateType や TimeType のコンストラクタでさまざまなフォーマットを指定するために使用します。

IntlDateFormatter::NONE
この要素を含まない
IntlDateFormatter::FULL
完全に指定した形式 (Tuesday, April 12, 1952 AD あるいは 3:30:42pm PST)
IntlDateFormatter::LONG
長い形式 (January 12, 1952 あるいは 3:30:32pm)
IntlDateFormatter::MEDIUM
中間の形式 (Jan 12, 1952)
IntlDateFormatter::SHORT
不可欠なデータのみを扱う最も省略した形式 (12/13/52 あるいは 3:30pm)
IntlDateFormatter::RELATIVE_FULL
IntlDateFormatter::FULL と同じですが、 昨日、今日、明日についてはそれぞれ、 yesterday, today, tomorrow になります。 PHP 8.0.0 以降で、dateType に限って利用可能です。
IntlDateFormatter::RELATIVE_LONG
IntlDateFormatter::LONG と同じですが、 昨日、今日、明日についてはそれぞれ、 yesterday, today, tomorrow になります。 PHP 8.0.0 以降で、dateType に限って利用可能です。
IntlDateFormatter::RELATIVE_MEDIUM
IntlDateFormatter::MEDIUM と同じですが、 昨日、今日、明日についてはそれぞれ、 yesterday, today, tomorrow になります。 PHP 8.0.0 以降で、dateType に限って利用可能です。
IntlDateFormatter::RELATIVE_SHORT
IntlDateFormatter::SHORT と同じですが、 昨日、今日、明日についてはそれぞれ、 yesterday, today, tomorrow になります。 PHP 8.0.0 以降で、dateType に限って利用可能です。

次の整数定数は、暦の種類を指定するものです。 これらの暦は、すべてグレゴリオ暦にもとづくものです。 グレゴリオ暦以外の暦はロケールで指定しなければなりません。 たとえば、 locale="hi@calendar=BUDDHIST" のようになります。

IntlDateFormatter::TRADITIONAL
非グレゴリオ暦
IntlDateFormatter::GREGORIAN
グレゴリオ暦

目次

  • IntlDateFormatter::create — Date Formatter を作成する
  • IntlDateFormatter::format — 日付/時刻 の値を文字列としてフォーマットする
  • IntlDateFormatter::formatObject — オブジェクトの書式を設定する
  • IntlDateFormatter::getCalendar — IntlDateFormatter が使用するカレンダー型を取得する
  • IntlDateFormatter::getDateType — IntlDateFormatter が使用する日付形式を取得する
  • IntlDateFormatter::getErrorCode — 直近の操作のエラーコードを取得する
  • IntlDateFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
  • IntlDateFormatter::getLocale — Formatter が使用するロケールを取得する
  • IntlDateFormatter::getPattern — IntlDateFormatter が使用するパターンを取得する
  • IntlDateFormatter::getTimeType — IntlDateFormatter が使用する時刻形式を取得する
  • IntlDateFormatter::getTimeZoneId — IntlDateFormatter が使用するタイムゾーン ID を取得する
  • IntlDateFormatter::getCalendarObject — カレンダーオブジェクトのコピーを取得する
  • IntlDateFormatter::getTimeZone — タイムゾーンを取得する
  • IntlDateFormatter::isLenient — IntlDateFormatter で使用する寛大さを取得する
  • IntlDateFormatter::localtime — 文字列をパースして、フィールドベースの時刻値にする
  • IntlDateFormatter::parse — 文字列をパースしてタイムスタンプにする
  • IntlDateFormatter::setCalendar — Formatter が使うカレンダー型を設定する
  • IntlDateFormatter::setLenient — パーサの寛大さを設定する
  • IntlDateFormatter::setPattern — IntlDateFormatter が使用するパターンを設定する
  • IntlDateFormatter::setTimeZone — タイムゾーンを設定する


Date Formatter を作成する

  • ≪ IntlDateFormatter
  • IntlDateFormatter::format ≫
  • PHP Manual
  • IntlDateFormatter
  • Date Formatter を作成する

IntlDateFormatter::create

datefmt_create

IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Date Formatter を作成する

説明

オブジェクト指向型

public static IntlDateFormatter::create(
?string $locale,
int $dateType = IntlDateFormatter::FULL,
int $timeType = IntlDateFormatter::FULL,
IntlTimeZone|DateTimeZone|string|null $timezone = null,
IntlCalendar|int|null $calendar = null,
?string $pattern = null
): ?IntlDateFormatter

オブジェクト指向型 (コンストラクタ)

public IntlDateFormatter::__construct(
?string $locale,
int $dateType = IntlDateFormatter::FULL,
int $timeType = IntlDateFormatter::FULL,
IntlTimeZone|DateTimeZone|string|null $timezone = null,
IntlCalendar|int|null $calendar = null,
?string $pattern = null
)

手続き型

datefmt_create(
?string $locale,
int $dateType = IntlDateFormatter::FULL,
int $timeType = IntlDateFormatter::FULL,
IntlTimeZone|DateTimeZone|string|null $timezone = null,
IntlCalendar|int|null $calendar = null,
?string $pattern = null
): ?IntlDateFormatter

Date Formatter を作成します。

パラメータ

locale

フォーマットやパースの際に使用するロケール。null を指定すると、 ini 設定 intl.default_locale の値を使います。

dateType

使用する日付の形式。 IntlDateFormatter の定数 のいずれかです。 デフォルト値は IntlDateFormatter::FULL です。

timeType

使用する時刻の形式。 IntlDateFormatter の定数 のいずれかです。 デフォルト値は IntlDateFormatter::FULL です。

timezone

タイムゾーン ID。デフォルト (そして、null が渡されたときにも使われるもの) は date_default_timezone_get() が返す ID、あるいは calendar パラメータに IntlCalendar オブジェクトが渡されていればそのタイムゾーンを使います。 この ID は、ICU のデータベースにある妥当な識別子である必要があります。あるいは、 オフセットを明示した GMT-05:30 のような形式になります。

IntlTimeZone オブジェクトあるいは DateTimeZone オブジェクトも指定できます。

calendar

フォーマットやパースの際に使用するカレンダー。デフォルトは null で、 これは IntlDateFormatter::GREGORIAN を表します。 IntlDateFormatter のカレンダー定数 あるいは IntlCalendar を指定します。 渡された IntlCalendar は、クローンされます。 IntlDateFormatter によって元のオブジェクトが書き換えられることはありません。 これは、利用するカレンダーの型 (グレゴリオ暦、イスラム暦、ペルシア暦など) の判定に使います。 また、timezone パラメータに null を指定した場合にはタイムゾーンの判定にも使います。

pattern

フォーマットやパースの際に使用するオプションのパターン。 使えるパターンについては » https://unicode-org.github.io/icu/userguide/format_parse/datetime/ を参照ください。

戻り値

作成された IntlDateFormatter を返します。失敗した場合は null を返します。

変更履歴

バージョン | 説明
8.1.0 | dateType と timeType は、オプションになりました。

例

例1 datefmt_create() の例

<?php
$fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles', IntlDateFormatter::GREGORIAN );
echo "First Formatted output is ".datefmt_format( $fmt , 0);
$fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN );
echo "Second Formatted output is ".datefmt_format( $fmt , 0);

$fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN ,"MM/dd/yyyy");
echo "First Formatted output with pattern is ".datefmt_format( $fmt , 0);
$fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN ,"MM/dd/yyyy");
echo "Second Formatted output with pattern is ".datefmt_format( $fmt , 0);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN );
echo "First Formatted output is ".$fmt->format(0);
$fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN );
echo "Second Formatted output is ".$fmt->format(0);

$fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN ,"MM/dd/yyyy");
echo "First Formatted output with pattern is ".$fmt->format(0);
$fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
'America/Los_Angeles',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
echo "Second Formatted output with pattern is ".$fmt->format(0);
?>

例3 無効なロケールを処理する例

<?php
try {
$fmt = new IntlDateFormatter(
'invalid_locale',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'dunno',
IntlDateFormatter::GREGORIAN,
);
} catch (\Error $e) {
// ...
}
?>

上の例の出力は以下となります。

First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
First Formatted output with pattern is 12/31/1969
Second Formatted output with pattern is 12/31/1969

参考

  • datefmt_format() - 日付/時刻 の値を文字列としてフォーマットする
  • datefmt_parse() - 文字列をパースしてタイムスタンプにする
  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する


日付/時刻 の値を文字列としてフォーマットする

  • ≪ IntlDateFormatter::create
  • IntlDateFormatter::formatObject ≫
  • PHP Manual
  • IntlDateFormatter
  • 日付/時刻 の値を文字列としてフォーマットする

IntlDateFormatter::format

datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — 日付/時刻 の値を文字列としてフォーマットする

説明

オブジェクト指向型

public IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float $datetime): string|false

手続き型

datefmt_format(IntlDateFormatter $formatter, IntlCalendar|DateTimeInterface|array|string|int|float $datetime): string|false

時刻の値を文字列としてフォーマットします。

パラメータ

formatter

Date Formatter リソース。

datetime

フォーマットする値。DateTimeInterface オブジェクト、 IntlCalendar オブジェクト、 epoch からの経過秒数を表す数値 (小数になる可能性もある)、 あるいは localtime() が出力する形式の配列となります。

DateTime オブジェクトあるいは IntlCalendar オブジェクトを渡した場合は、 そのタイムゾーンは考慮しません。これらをフォーマットするときに使うのは、 フォーマッターで設定されているタイムゾーンです。 渡したオブジェクトのタイムゾーンを使って欲しい場合は、 IntlDateFormatter::setTimeZone() を呼んでそのオブジェクトのタイムゾーンを設定しておかなければいけません。 あるいは、staticメソッド IntlDateFormatter::formatObject() をかわりに使ってもかまいません。

戻り値

フォーマットされた文字列、あるいはエラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
7.1.5 | datetime パラメータに 一般的な DateTimeInterface オブジェクトのサポートが追加されました。 これより前のバージョンでは、DateTime オブジェクトのみがサポートされていました。
PECL 3.0.0 | IntlCalendar オブジェクトを datetime に渡せるようになりました。

例

例1 datefmt_format() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'First Formatted output is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Second Formatted output is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'First Formatted output with pattern is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo "Second Formatted output with pattern is " . datefmt_format($fmt, 0);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'First Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Second Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'First Formatted output with pattern is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'Second Formatted output with pattern is ' . $fmt->format(0);
?>

上の例の出力は以下となります。

First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
First Formatted output with pattern is 12/31/1969
Second Formatted output with pattern is 12/31/1969

例3 IntlCalendar オブジェクトを使う例

<?php
$tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));
$formatter = IntlDateFormatter::create(
'fr_FR',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
$tz,
IntlDateFormatter::GREGORIAN
);

$cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
$cal->set(IntlCalendar::FIELD_MONTH, 8); //9th month, Ramadan
$cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); //1st day
$cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
$cal->clear(IntlCalendar::FIELD_MINUTE);
$cal->clear(IntlCalendar::FIELD_SECOND);
$cal->clear(IntlCalendar::FIELD_MILLISECOND);

echo "In this islamic year, Ramadan started/will start on:\n\t",
$formatter->format($cal), "\n";

// フォーマッターのタイムゾーンを利用します
$formatter->setTimeZone('Asia/Tokyo');
echo "After changing timezone:\n\t",
$formatter->format($cal), "\n";

上の例の出力は以下となります。

In this islamic year, Ramadan started/will start on:
    mardi 9 juillet 2013 19:00:00 heure avancee d'Europe centrale
After changing timezone:
    mercredi 10 juillet 2013 02:00:00 heure normale du Japon

参考

  • datefmt_create() - Date Formatter を作成する
  • datefmt_parse() - 文字列をパースしてタイムスタンプにする
  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する
  • datefmt_format_object() - オブジェクトの書式を設定する


オブジェクトの書式を設定する

  • ≪ IntlDateFormatter::format
  • IntlDateFormatter::getCalendar ≫
  • PHP Manual
  • IntlDateFormatter
  • オブジェクトの書式を設定する

IntlDateFormatter::formatObject

datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — オブジェクトの書式を設定する

説明

オブジェクト指向型

public static IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface $datetime, array|int|string|null $format = null, ?string $locale = null): string|false

手続き型

datefmt_format_object(IntlCalendar|DateTimeInterface $datetime, array|int|string|null $format = null, ?string $locale = null): string|false

この関数は、IntlCalendar オブジェクトや DateTime オブジェクトをフォーマットします。その際、明示的に IntlDateFormatter オブジェクトを作る必要はありません。

一時的な IntlDateFormatter が作られ、 渡されたオブジェクトのタイムゾーンを受け取ります。PHP に組み込まれているタイムゾーンデータベースは使いません。 そのかわりに、ICU のタイムゾーンデータベースを使います。 したがって、DateTime オブジェクトで使うタイムゾーン ID は ICU のデータベースに存在するものでなければいけません。

パラメータ

datetime

IntlCalendar あるいは DateTime 型のオブジェクト。 このオブジェクトの中のタイムゾーン情報を使います。

format

日付/時刻のフォーマット方法。二つの要素からなる配列 (最初の要素が日付のスタイル、二番目の要素が時刻のスタイル。それぞれ、定数 IntlDateFormatter::NONE、 IntlDateFormatter::SHORT、 IntlDateFormatter::MEDIUM、 IntlDateFormatter::LONG、 IntlDateFormatter::FULL のいずれか)、 これらの定数のいずれかの値を表す int 型 (日付と時刻の両方に使います)、あるいは » ICU のドキュメント にあるフォーマットを表す文字列を指定します。null を渡した場合はデフォルトのスタイルを使います。

locale

利用するロケール。null を渡した場合は デフォルトのロケール を使います。

戻り値

結果を文字列で返します。失敗した場合に false を返します。

例

例1 IntlDateFormatter::formatObject() の例

<?php
/* デフォルトのタイムゾーンは利用せず、オブジェクトのタイムゾーンを取得します */
ini_set('date.timezone', 'UTC');
/* デフォルトのロケールは、この ini 設定から取得します */
ini_set('intl.default_locale', 'fr_FR');

$cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
echo "default:\n\t",
IntlDateFormatter::formatObject($cal),
"\n";

echo "long \$format (full):\n\t",
IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
"\n";

echo "array \$format (none, full):\n\t",
IntlDateFormatter::formatObject($cal, array(
IntlDateFormatter::NONE,
IntlDateFormatter::FULL)),
"\n";

echo "string \$format (d 'of' MMMM y):\n\t",
IntlDateFormatter::formatObject($cal, "d 'of' MMMM y", 'en_US'),
"\n";

echo "with DateTime:\n\t",
IntlDateFormatter::formatObject(
new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
IntlDateFormatter::FULL,
'es_ES'),
"\n";

上の例の出力は以下となります。

default:
    6 juin 2013 17:05:06
long $format (full):
    jeudi 6 juin 2013 17:05:06 heure d'ete irlandaise
array $format (none, full):
    17:05:06 heure d'ete irlandaise
string $format (d 'of' MMMM y):
    6 of June 2013
with DateTime:
    lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central


IntlDateFormatter が使用するカレンダー型を取得する

  • ≪ IntlDateFormatter::formatObject
  • IntlDateFormatter::getDateType ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するカレンダー型を取得する

IntlDateFormatter::getCalendar

datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — IntlDateFormatter が使用するカレンダー型を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getCalendar(): int|false

手続き型

datefmt_get_calendar(IntlDateFormatter $formatter): int|false

パラメータ

formatter

Formatter リソース。

戻り値

Formatter が使用する カレンダー型 を返します。 IntlDateFormatter::TRADITIONAL あるいは IntlDateFormatter::GREGORIAN です。 失敗時に false を返します。

例

例1 datefmt_get_calendar() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . datefmt_get_calendar($fmt);
datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . datefmt_get_calendar($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . $fmt->getCalendar();
$fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . $fmt->getCalendar();

?>

例3 無効なロケールを処理する例

<?php
try {
$fmt = new IntlDateFormatter(
'invalid_locale',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'dunno',
IntlDateFormatter::GREGORIAN,
);
$cal = $fmt->getCalendar();
} catch (\Error $e) {
// ...
}
?>

上の例の出力は以下となります。

calendar of the formatter is : 1
Now calendar of the formatter is : 0

参考

  • datefmt_get_calendar_object() - カレンダーオブジェクトのコピーを取得する
  • datefmt_set_calendar() - Formatter が使うカレンダー型を設定する
  • datefmt_create() - Date Formatter を作成する


IntlDateFormatter が使用する日付形式を取得する

  • ≪ IntlDateFormatter::getCalendar
  • IntlDateFormatter::getErrorCode ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用する日付形式を取得する

IntlDateFormatter::getDateType

datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — IntlDateFormatter が使用する日付形式を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getDateType(): int|false

手続き型

datefmt_get_datetype(IntlDateFormatter $formatter): int|false

Formatter が使用する日付形式を返します。

パラメータ

formatter

Formatter リソース。

戻り値

Formatter の現在の 日付形式 の値を返します。 失敗した場合に false を返します

例

例1 datefmt_get_datetype() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'datetype of the formatter is : ' . datefmt_get_datetype($fmt);
echo 'First Formatted output with datetype is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
'en_US',
IntlDateFormatter::SHORT,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Now datetype of the formatter is : ' . datefmt_get_datetype($fmt);
echo 'Second Formatted output with datetype is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'datetype of the formatter is : ' . $fmt->getDateType();
echo 'First Formatted output is ' . $fmt->format(0);
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::SHORT,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Now datetype of the formatter is : ' . $fmt->getDateType();
echo 'Second Formatted output is ' . $fmt->format(0);

?>

上の例の出力は以下となります。

datetype of the formatter is : 0
First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Now datetype of the formatter is : 2
Second Formatted output is 12/31/69 4:00:00 PM PT

参考

  • datefmt_get_timetype() - IntlDateFormatter が使用する時刻形式を取得する
  • datefmt_create() - Date Formatter を作成する


直近の操作のエラーコードを取得する

  • ≪ IntlDateFormatter::getDateType
  • IntlDateFormatter::getErrorMessage ≫
  • PHP Manual
  • IntlDateFormatter
  • 直近の操作のエラーコードを取得する

IntlDateFormatter::getErrorCode

datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — 直近の操作のエラーコードを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getErrorCode(): int

手続き型

datefmt_get_error_code(IntlDateFormatter $formatter): int

直近のフォーマット操作のエラーコードを返します。

パラメータ

formatter

Formatter リソース。

戻り値

エラーコードを返します。UErrorCode のいずれかの値となります。初期値は U_ZERO_ERROR です。

例

例1 datefmt_get_error_code() の例

<?php

$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
$str = datefmt_format($fmt, 0);

printf(
"ERROR: %s (%d)\n",
datefmt_get_error_message($fmt),
datefmt_get_error_code($fmt)
);
?>

例2 オブジェクト指向の例

<?php

$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
$str = $fmt->format(0);

printf(
"ERROR: %s (%d)\n",
$fmt->getErrorMessage(),
$fmt->getErrorCode()
);
?>

上の例の出力は以下となります。

ERROR: U_ZERO_ERROR (0)

参考

  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


直近の操作のエラーテキストを取得する

  • ≪ IntlDateFormatter::getErrorCode
  • IntlDateFormatter::getLocale ≫
  • PHP Manual
  • IntlDateFormatter
  • 直近の操作のエラーテキストを取得する

IntlDateFormatter::getErrorMessage

datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — 直近の操作のエラーテキストを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getErrorMessage(): string

手続き型

datefmt_get_error_message(IntlDateFormatter $formatter): string

直近の操作のエラーテキストを取得します。

パラメータ

formatter

Formatter リソース。

戻り値

直近のエラーの説明を返します。

例

例1 datefmt_get_error_message() の例

<?php

$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
$str = datefmt_format($fmt, 0);

printf(
"ERROR: %s (%d)\n",
datefmt_get_error_message($fmt),
datefmt_get_error_code($fmt)
);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
$str = $fmt->format(0);

printf(
"ERROR: %s (%d)\n",
$fmt->getErrorMessage(),
$fmt->getErrorCode()
);
?>

上の例の出力は以下となります。

ERROR: U_ZERO_ERROR (0)

参考

  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


Formatter が使用するロケールを取得する

  • ≪ IntlDateFormatter::getErrorMessage
  • IntlDateFormatter::getPattern ≫
  • PHP Manual
  • IntlDateFormatter
  • Formatter が使用するロケールを取得する

IntlDateFormatter::getLocale

datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Formatter が使用するロケールを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false

手続き型

datefmt_get_locale(IntlDateFormatter $formatter, int $type = ULOC_ACTUAL_LOCALE): string|false

Formatter が使用するロケールを取得します。

パラメータ

formatter

Formatter リソース。

type

妥当なロケールか実際のロケール (それぞれ Locale::VALID_LOCALE、 Locale::ACTUAL_LOCALE) のいずれかを選択します。デフォルトは「実際の (actual)」ロケールです。

戻り値

この Formatter のロケールを返します。 失敗した場合に false を返します

例

例1 datefmt_get_locale() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . datefmt_get_locale($fmt);
echo 'First Formatted output is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . datefmt_get_locale($fmt);
echo 'Second Formatted output is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . $fmt->getLocale();
echo 'First Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'locale of the formatter is : ' . $fmt->getLocale();
echo 'Second Formatted output is ' . $fmt->format(0);

?>

上の例の出力は以下となります。

locale of the formatter is : en
First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
locale of the formatter is : de
Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00

参考

  • datefmt_create() - Date Formatter を作成する


IntlDateFormatter が使用するパターンを取得する

  • ≪ IntlDateFormatter::getLocale
  • IntlDateFormatter::getTimeType ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するパターンを取得する

IntlDateFormatter::getPattern

datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — IntlDateFormatter が使用するパターンを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getPattern(): string|false

手続き型

datefmt_get_pattern(IntlDateFormatter $formatter): string|false

Formatter が使用するパターンを取得します。

パラメータ

formatter

Formatter リソース。

戻り値

フォーマット/パース 時に使用するパターン文字列を返します。 失敗した場合に false を返します

例

例1 datefmt_get_pattern() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'pattern of the formatter is : ' . datefmt_get_pattern($fmt);
echo 'First Formatted output with pattern is ' . datefmt_format($fmt, 0);
datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
echo 'Now pattern of the formatter is : ' . datefmt_get_pattern($fmt);
echo 'Second Formatted output with pattern is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'pattern of the formatter is : ' . $fmt->getPattern();
echo 'First Formatted output is ' . $fmt->format(0);
$fmt->setPattern('yyyymmdd hh:mm:ss z');
echo 'Now pattern of the formatter is : ' . $fmt->getPattern();
echo 'Second Formatted output is ' . $fmt->format(0);
?>

上の例の出力は以下となります。

pattern of the formatter is : MM/dd/yyyy
First Formatted output is 12/31/1969
Now pattern of the formatter is : yyyymmdd hh:mm:ss z
Second Formatted output is 19690031 04:00:00 PST

参考

  • datefmt_set_pattern() - IntlDateFormatter が使用するパターンを設定する
  • datefmt_create() - Date Formatter を作成する


IntlDateFormatter が使用する時刻形式を取得する

  • ≪ IntlDateFormatter::getPattern
  • IntlDateFormatter::getTimeZoneId ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用する時刻形式を取得する

IntlDateFormatter::getTimeType

datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — IntlDateFormatter が使用する時刻形式を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getTimeType(): int|false

手続き型

datefmt_get_timetype(IntlDateFormatter $formatter): int|false

Formatter が使用する時刻形式を返します。

パラメータ

formatter

Formatter リソース。

戻り値

Formatter の現在の 日付形式 の値を返します。 失敗した場合に false を返します

例

例1 datefmt_get_timetype() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'timetype of the formatter is : ' . datefmt_get_timetype($fmt);
echo 'First Formatted output with timetype is ' . datefmt_format($fmt, 0);

$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::SHORT,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Now timetype of the formatter is : ' . datefmt_get_timetype($fmt);
echo 'Second Formatted output with timetype is ' . datefmt_format($fmt, 0);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'timetype of the formatter is : ' . $fmt->getTimeType();
echo 'First Formatted output is ' . $fmt->format(0);

$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::SHORT,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Now timetype of the formatter is : ' . $fmt->getTimeType();
echo 'Second Formatted output is ' . $fmt->format(0);

?>

上の例の出力は以下となります。

timetype of the formatter is : 0
First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Now timetype of the formatter is : 3
Second Formatted output is Wednesday, December 31, 1969 4:00 PM

参考

  • datefmt_get_datetype() - IntlDateFormatter が使用する日付形式を取得する
  • datefmt_create() - Date Formatter を作成する


IntlDateFormatter が使用するタイムゾーン ID を取得する

  • ≪ IntlDateFormatter::getTimeType
  • IntlDateFormatter::getCalendarObject ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するタイムゾーン ID を取得する

IntlDateFormatter::getTimeZoneId

datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — IntlDateFormatter が使用するタイムゾーン ID を取得する

説明

オブジェクト指向型

public IntlDateFormatter::getTimeZoneId(): string|false

手続き型

datefmt_get_timezone_id(IntlDateFormatter $formatter): string|false

IntlDateFormatter が使用するタイムゾーン ID を取得します。

パラメータ

formatter

Formatter リソース。

戻り値

この Formatter が使用するタイムゾーンの ID 文字列を返します。 失敗した場合に false を返します

例

例1 datefmt_get_timezone_id() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'timezone_id of the formatter is: ' . datefmt_get_timezone_id($fmt) . "\n";
datefmt_set_timezone($fmt, 'Europe/Madrid');
echo 'Now timezone_id of the formatter is: ' . datefmt_get_timezone_id($fmt);

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'timezone_id of the formatter is: ' . $fmt->getTimezoneId() . "\n";
$fmt->setTimezone('Europe/Madrid');
echo 'Now timezone_id of the formatter is: ' . $fmt->getTimezoneId();

?>

上の例の出力は以下となります。

timezone_id of the formatter is: America/Los_Angeles
Now timezone_id of the formatter is: Europe/Madrid

参考

  • datefmt_set_timezone() - タイムゾーンを設定する
  • datefmt_create() - Date Formatter を作成する


カレンダーオブジェクトのコピーを取得する

  • ≪ IntlDateFormatter::getTimeZoneId
  • IntlDateFormatter::getTimeZone ≫
  • PHP Manual
  • IntlDateFormatter
  • カレンダーオブジェクトのコピーを取得する

IntlDateFormatter::getCalendarObject

datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — カレンダーオブジェクトのコピーを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

手続き型

datefmt_get_calendar_object(IntlDateFormatter $formatter): IntlCalendar|false|null

このフォーマッターが内部的に使うカレンダーオブジェクトのコピーを取得します。 このカレンダーには型 (gregorian、japanese、buddhist、roc、persian、 islamic など) やタイムゾーンが設定されており、フォーマッターが使っている型やタイムゾーンと一致します。 オブジェクトの日付や時刻は指定されていません。

パラメータ

この関数にはパラメータはありません。

戻り値

このフォーマッターが内部的に使うカレンダーオブジェクトのコピーを返します。 何も設定されなかった場合は null を返します。 失敗した場合に false を返します

例

例1 IntlDateFormatter::getCalendarObject() の例

<?php
$formatter = IntlDateFormatter::create(
"fr_FR@calendar=islamic",
NULL,
NULL,
"GMT-01:00",
IntlDateFormatter::TRADITIONAL
);

$cal = $formatter->getCalendarObject();

var_dump(
$cal->getType(),
$cal->getTimeZone(),
$cal->getLocale(Locale::VALID_LOCALE)
);

上の例の出力は以下となります。

string(7) "islamic"
object(IntlTimeZone)#3 (4) {
  ["valid"]=>
  bool(true)
  ["id"]=>
  string(9) "GMT-01:00"
  ["rawOffset"]=>
  int(-3600000)
  ["currentOffset"]=>
  int(-3600000)
}
string(5) "fr_FR"

参考

  • IntlDateFormatter::getCalendar() - IntlDateFormatter が使用するカレンダー型を取得する
  • IntlDateFormatter::setCalendar() - Formatter が使うカレンダー型を設定する
  • IntlCalendar


タイムゾーンを取得する

  • ≪ IntlDateFormatter::getCalendarObject
  • IntlDateFormatter::isLenient ≫
  • PHP Manual
  • IntlDateFormatter
  • タイムゾーンを取得する

IntlDateFormatter::getTimeZone

datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — タイムゾーンを取得する

説明

オブジェクト指向型

public IntlDateFormatter::getTimeZone(): IntlTimeZone|false

手続き型

datefmt_get_timezone(IntlDateFormatter $formatter): IntlTimeZone|false

タイムゾーンを表す IntlTimeZone オブジェクトを返します。 このオブジェクトで日付や時刻をフォーマットするときに、このタイムゾーンを使います。 IntlCalendar や DateTime オブジェクトをこの IntlDateFormatter でフォーマットするときに使うタイムゾーンは、 このメソッドが返すものとなります。フォーマットしようとしているオブジェクトのタイムゾーンではありません。

パラメータ

この関数にはパラメータはありません。

戻り値

IntlTimeZone オブジェクトを返します。 失敗した場合に false を返します。

例

例1 IntlDateFormatter::getTimeZone() の例

<?php

$madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
$lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

var_dump($madrid->getTimezone());
echo $madrid->getTimezone()->getDisplayName(
false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
echo $lisbon->getTimeZone()->getId(), "\n";
// id は ->getTimezoneId() でも取得できます
echo $lisbon->getTimeZoneId(), "\n";

上の例の出力は以下となります。

object(IntlTimeZone)#4 (4) {
  ["valid"]=>
  bool(true)
  ["id"]=>
  string(13) "Europe/Madrid"
  ["rawOffset"]=>
  int(3600000)
  ["currentOffset"]=>
  int(7200000)
}
Spain Time
Europe/Lisbon
Europe/Lisbon

参考

  • IntlDateFormatter::getTimeZoneId() - IntlDateFormatter が使用するタイムゾーン ID を取得する
  • IntlDateFormatter::setTimeZone() - タイムゾーンを設定する
  • IntlTimeZone


IntlDateFormatter で使用する寛大さを取得する

  • ≪ IntlDateFormatter::getTimeZone
  • IntlDateFormatter::localtime ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter で使用する寛大さを取得する

IntlDateFormatter::isLenient

datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — IntlDateFormatter で使用する寛大さを取得する

説明

オブジェクト指向型

public IntlDateFormatter::isLenient(): bool

手続き型

datefmt_is_lenient(IntlDateFormatter $formatter): bool

パターンに正確にマッチしていない入力の処理を、 パーサが厳格に行うのか寛大に行うのかを調べます。

パラメータ

formatter

Formatter リソース。

戻り値

寛大なパーサの場合は true、厳格なパーサの場合は false 返します。 デフォルトのパーサは寛大なパーサです。

例

例1 datefmt_is_lenient() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'dd/mm/yyyy'
);
echo 'lenient of the formatter is : ';
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}
datefmt_set_lenient($fmt,false);
echo 'Now lenient of the formatter is : ';
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\n Trying to do parse('35/13/1971').Result is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
"dd/mm/yyyy"
);
echo "lenient of the formatter is : ";
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0){
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}

$fmt->setLenient(FALSE);
echo 'Now lenient of the formatter is : ';
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}

?>

上の例の出力は以下となります。

lenient of the formatter is : TRUE
Trying to do parse('35/13/1971').
Result is : -2147483
Now lenient of the formatter is : FALSE
Trying to do parse('35/13/1971').
Result is :
Error_msg is : Date parsing failed: U_PARSE_ERROR
Error_code is : 9

参考

  • datefmt_set_lenient() - パーサの寛大さを設定する
  • datefmt_create() - Date Formatter を作成する


文字列をパースして、フィールドベースの時刻値にする

  • ≪ IntlDateFormatter::isLenient
  • IntlDateFormatter::parse ≫
  • PHP Manual
  • IntlDateFormatter
  • 文字列をパースして、フィールドベースの時刻値にする

IntlDateFormatter::localtime

datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — 文字列をパースして、フィールドベースの時刻値にする

説明

オブジェクト指向型

public IntlDateFormatter::localtime(string $string, int &$offset = null): array|false

手続き型

datefmt_localtime(IntlDateFormatter $formatter, string $string, int &$offset = null): array|false

文字列 $value を変換し、フィールドベースの時刻値 (各フィールドを含む配列) にします。$parse_pos からパースを開始し、入力値を可能な限り使用します。

パラメータ

formatter

Formatter リソース。

string

時間に変換する文字列。

offset

$value のパースを開始する位置 (ゼロから数えます)。 $value を処理する前にエラーが発生していない場合は $parse_pos は -1 となります。それ以外の場合はパースが終了した位置となります (そしてエラーが発生します)。 この変数には、パースが失敗した場合にその終了位置が含まれます。 $parse_pos > strlen($value) の場合、パースは即時に失敗します。

戻り値

Localtime 互換の、整数値の配列を返します。 tm_hour フィールド内の、24 時間制の時刻の値を含みます。 失敗した場合に false を返します

例

例1 datefmt_localtime() の例

<?php

$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
$arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 4:00:00 PM PT', 0);
echo 'First parsed output is ';
if ($arr) {
foreach ($arr as $key => $value) {
echo "$key : $value , ";
}
}

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
$arr = $fmt->localtime('Wednesday, December 31, 1969 4:00:00 PM PT', 0);
echo 'First parsed output is ';
if ($arr) {
foreach ($arr as $key => $value) {
echo "$key : $value , ";
}
}

?>

上の例の出力は以下となります。

First parsed output is tm_sec : 0 , tm_min : 0 , tm_hour : 16 , tm_year : 1969 ,
tm_mday : 31 , tm_wday : 4 , tm_yday : 365 , tm_mon : 11 , tm_isdst : 0 ,

参考

  • datefmt_create() - Date Formatter を作成する
  • datefmt_format() - 日付/時刻 の値を文字列としてフォーマットする
  • datefmt_parse() - 文字列をパースしてタイムスタンプにする
  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する


文字列をパースしてタイムスタンプにする

  • ≪ IntlDateFormatter::localtime
  • IntlDateFormatter::setCalendar ≫
  • PHP Manual
  • IntlDateFormatter
  • 文字列をパースしてタイムスタンプにする

IntlDateFormatter::parse

datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — 文字列をパースしてタイムスタンプにする

説明

オブジェクト指向型

public IntlDateFormatter::parse(string $string, int &$offset = null): int|float|false

手続き型

datefmt_parse(IntlDateFormatter $formatter, string $string, int &$offset = null): int|float|false

string を時間に変換します。offset からパースを開始し、 入力値を可能な限り使用します。

パラメータ

formatter

Formatter リソース。

string

時間に変換する文字列。

offset

string のパースを開始する位置 (ゼロから数えます)。 string を処理する前にエラーが発生していない場合は offset は -1 となります。それ以外の場合はパースが終了した位置となります (そしてエラーが発生します)。 この変数には、パースが失敗した場合にその終了位置が含まれます。 offset > strlen($string) の場合、パースは即時に失敗します。

戻り値

タイムスタンプとしてパースされた値を返します。 パースできなかった場合は false を返します。

例

例1 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'First parsed output is ' . $fmt->parse('Wednesday, December 20, 1989 4:00:00 PM PT');
$fmt = new IntlDateFormatter(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
?>

例2 datefmt_parse() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'First parsed output is ' . datefmt_parse($fmt, 'Wednesday, December 20, 1989 4:00:00 PM PT');
$fmt = datefmt_create(
'de-DE',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'Second parsed output is ' . datefmt_parse($fmt, 'Mittwoch, 20. Dezember 1989 16:00 Uhr GMT-08:00');
?>

上の例の出力は以下となります。

First parsed output is 630201600
Second parsed output is 630201600

参考

  • datefmt_create() - Date Formatter を作成する
  • datefmt_format() - 日付/時刻 の値を文字列としてフォーマットする
  • datefmt_localtime() - 文字列をパースして、フィールドベースの時刻値にする
  • datefmt_get_error_code() - 直近の操作のエラーコードを取得する
  • datefmt_get_error_message() - 直近の操作のエラーテキストを取得する


Formatter が使うカレンダー型を設定する

  • ≪ IntlDateFormatter::parse
  • IntlDateFormatter::setLenient ≫
  • PHP Manual
  • IntlDateFormatter
  • Formatter が使うカレンダー型を設定する

IntlDateFormatter::setCalendar

datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Formatter が使うカレンダー型を設定する

説明

オブジェクト指向型

public IntlDateFormatter::setCalendar(IntlCalendar|int|null $calendar): bool

手続き型

datefmt_set_calendar(IntlDateFormatter $formatter, IntlCalendar|int|null $calendar): bool

このフォーマッターが使用するカレンダーあるいはカレンダー型を設定します。

パラメータ

formatter

フォーマッターリソース。

calendar

使用する カレンダー型 (デフォルトは IntlDateFormatter::GREGORIAN で、 null を指定した場合にもこれを使います)、あるいは IntlCalendar オブジェクト。

IntlCalendar オブジェクトが渡された場合は、それをクローンします。 引数として渡したオブジェクトは、何も変更されません。

フォーマッターのタイムゾーンを残すのは IntlCalendar オブジェクトが渡されなかった場合だけで、 このオブジェクトが渡された場合は新しいタイムゾーンを利用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
5.5.0/PECL 3.0.0 | IntlCalendar オブジェクトを渡せるようになりました。

例

例1 datefmt_set_calendar() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . datefmt_get_calendar($fmt);
datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . datefmt_get_calendar($fmt);
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
echo 'calendar of the formatter is : ' . $fmt->getCalendar();
$fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
echo 'Now calendar of the formatter is : ' . $fmt->getCalendar();
?>

上の例の出力は以下となります。

calendar of the formatter is : 1
Now calendar of the formatter is : 0

例3 引数に IntlCalendar を使う例

<?php
$time = strtotime("2013-03-03 00:00:00 UTC");
$formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

echo "before: ", $formatter->format($time), "\n";

/* カレンダーのロケールは使われないことに注目 */
$formatter->setCalendar(IntlCalendar::createInstance(
"America/New_York", "pt_PT@calendar=islamic"));

echo "after: ", $formatter->format($time), "\n";

上の例の出力は以下となります。

before: Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
after:  Saturday, Rabi? II 20, 1434 at 7:00:00 PM Eastern Standard Time

参考

  • datefmt_get_calendar() - IntlDateFormatter が使用するカレンダー型を取得する
  • datefmt_get_calendar_object() - カレンダーオブジェクトのコピーを取得する
  • datefmt_create() - Date Formatter を作成する


パーサの寛大さを設定する

  • ≪ IntlDateFormatter::setCalendar
  • IntlDateFormatter::setPattern ≫
  • PHP Manual
  • IntlDateFormatter
  • パーサの寛大さを設定する

IntlDateFormatter::setLenient

datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — パーサの寛大さを設定する

説明

オブジェクト指向型

public IntlDateFormatter::setLenient(bool $lenient): void

手続き型

datefmt_set_lenient(IntlDateFormatter $formatter, bool $lenient): void

パターンに正確にマッチしていない入力の処理を、 パーサが厳格に行うのか寛大に行うのかを定義します。 寛大なパースを有効にすると、日付や時刻のパターンに不備がある場合でも 可能な限り値を取得しようと試みます。余計な空白があったり 理解不能なトークンがあったり、あるいは値が無効な場合 ("Feburary 30th") は処理できません。

パラメータ

formatter

Formatter リソース。

lenient

パーサを寛大なものにするかどうか。デフォルトは true (寛大) です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 datefmt_set_lenient() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'dd/MM/yyyy'
);
echo 'lenient of the formatter is : ';
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}
datefmt_set_lenient($fmt, false);
echo "\nNow lenient of the formatter is : ";
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
datefmt_parse($fmt, '35/13/1971');
echo "\nTrying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : ".intl_get_error_message();
echo "\nError_code is : ".intl_get_error_code();
}

?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'dd/MM/yyyy'
);
echo 'lenient of the formatter is : ';
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}

$fmt->setLenient(FALSE);
echo "\nNow lenient of the formatter is : ";
if ($fmt->isLenient()) {
echo 'TRUE';
} else {
echo 'FALSE';
}
$fmt->parse('35/13/1971');
echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
if (intl_get_error_code() != 0) {
echo "\nError_msg is : " . intl_get_error_message();
echo "\nError_code is : " . intl_get_error_code();
}

?>

上の例の出力は以下となります。

lenient of the formatter is : TRUE
Trying to do parse('35/13/1971').
Result is : 66038400
Now lenient of the formatter is : FALSE
Trying to do parse('35/13/1971').
Result is :
Error_msg is : Date parsing failed: U_PARSE_ERROR
Error_code is : 9

参考

  • datefmt_is_lenient() - IntlDateFormatter で使用する寛大さを取得する
  • datefmt_create() - Date Formatter を作成する


IntlDateFormatter が使用するパターンを設定する

  • ≪ IntlDateFormatter::setLenient
  • IntlDateFormatter::setTimeZone ≫
  • PHP Manual
  • IntlDateFormatter
  • IntlDateFormatter が使用するパターンを設定する

IntlDateFormatter::setPattern

datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — IntlDateFormatter が使用するパターンを設定する

説明

オブジェクト指向型

public IntlDateFormatter::setPattern(string $pattern): bool

手続き型

datefmt_set_pattern(IntlDateFormatter $formatter, string $pattern): bool

IntlDateFormatter が使用するパターンを取得します。

パラメータ

formatter

Formatter リソース。

pattern

使用するパターン文字列。 使えるパターンについては » https://unicode-org.github.io/icu/userguide/format_parse/datetime/ を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 間違ったフォーマット文字列を指定すると、失敗します。

例

例1 datefmt_set_pattern() の例

<?php
$fmt = datefmt_create(
'en_US',
IntlDateFormatter::FULL,IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'Pattern of the formatter is : ', datefmt_get_pattern($fmt), PHP_EOL;
echo 'First Formatted output with pattern is ', datefmt_format($fmt, 0), PHP_EOL;
datefmt_set_pattern($fmt, 'yyyyMMdd hh:mm:ss z');
echo 'Now pattern of the formatter is : ', datefmt_get_pattern($fmt), PHP_EOL;
echo 'Second Formatted output with pattern is ', datefmt_format($fmt, 0), PHP_EOL;
?>

例2 オブジェクト指向の例

<?php
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,IntlDateFormatter::FULL,
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN,
'MM/dd/yyyy'
);
echo 'Pattern of the formatter is : ', $fmt->getPattern(), PHP_EOL;
echo 'First Formatted output is ', $fmt->format(0), PHP_EOL;
$fmt->setPattern('yyyyMMdd hh:mm:ss z');
echo 'Now pattern of the formatter is : ', $fmt->getPattern(), PHP_EOL;
echo 'Second Formatted output is ', $fmt->format(0), PHP_EOL;
?>

上の例の出力は以下となります。

Pattern of the formatter is : MM/dd/yyyy
First Formatted output is 12/31/1969
Now pattern of the formatter is : yyyyMMdd hh:mm:ss z
Second Formatted output is 19691231 04:00:00 PST

参考

  • datefmt_get_pattern() - IntlDateFormatter が使用するパターンを取得する
  • datefmt_create() - Date Formatter を作成する


タイムゾーンを設定する

  • ≪ IntlDateFormatter::setPattern
  • ResourceBundle ≫
  • PHP Manual
  • IntlDateFormatter
  • タイムゾーンを設定する

IntlDateFormatter::setTimeZone

datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — タイムゾーンを設定する

説明

オブジェクト指向型

public IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null $timezone): bool

手続き型

datefmt_set_timezone(IntlDateFormatter $formatter, IntlTimeZone|DateTimeZone|string|null $timezone): bool

IntlDateFormatter によって使われるタイムゾーンを設定します。

パラメータ

formatter

フォーマッターのリソース

timezone

利用するタイムゾーン。次の形式で指定できます。

  • null。この場合はデフォルトのタイムゾーンを使います。デフォルトは、ini 項目 date.timezone で設定したものか、 date_default_timezone_set() 関数で指定したもの (そして date_default_timezone_get() が返すもの) になります。

  • IntlTimeZone。これを直接使います。

  • DateTimeZone。その識別子を取り出して、ICU タイムゾーンオブジェクトを作ります。 つまり、これは ICU のデータベースに基づくタイムゾーンとなり、PHP のタイムゾーンデータベースに基づくものではありません。

  • 文字列。ICU タイムゾーン識別子として有効なものを指定します。 IntlTimeZone::createTimeZoneIDEnumeration() を参照ください。 "GMT+08:30" などのオフセットも指定できます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | この関数は、true を返すようになりました。 これより前のバージョンでは、null を返していました。

例

例1 IntlDateFormatter::setTimeZone() の例

<?php
ini_set('date.timezone', 'Europe/Amsterdam');

$formatter = IntlDateFormatter::create(NULL, NULL, NULL, "UTC");

$formatter->setTimeZone(NULL);
echo "NULL\n ", $formatter->getTimeZone()->getId(), "\n";

$formatter->setTimeZone(IntlTimeZone::createTimeZone('Europe/Lisbon'));
echo "IntlTimeZone\n ", $formatter->getTimeZone()->getId(), "\n";

$formatter->setTimeZone(new DateTimeZone('Europe/Paris'));
echo "DateTimeZone\n ", $formatter->getTimeZone()->getId(), "\n";

$formatter->setTimeZone('Europe/Rome');
echo "String\n ", $formatter->getTimeZone()->getId(), "\n";

$formatter->setTimeZone('GMT+00:30');
print_r($formatter->getTimeZone());

上の例の出力は以下となります。

NULL
    Europe/Amsterdam
IntlTimeZone
    Europe/Lisbon
DateTimeZone
    Europe/Paris
String
    Europe/Rome
IntlTimeZone Object
(
    [valid] => 1
    [id] => GMT+00:30
    [rawOffset] => 1800000
    [currentOffset] => 1800000
)

参考

  • IntlDateFormatter::getTimeZone() - タイムゾーンを取得する


ResourceBundle クラス

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

はじめに

ローカライズしたソフトウェア製品には、 現在のロケールによって切り替えるデータのセットが必要となることがよくあります。 たとえばメッセージやラベル、書式パターンなどです。 ICU のリソース機能を使うと、リソースセットを定義することができます。 ロケールに基づいてアプリケーションからこれを読み込み、 ロケールにかかわらず統一された方法でアクセスすることができます。

このクラスは ICU のリソースデータファイルへのアクセスを実装しています。 このファイルはバイナリデータの配列で、ICU がローカライズしたデータを保存するために使っています。

ICU リソースバンドルには、シンプルなリソースと複雑なリソースを保持することができます。 複雑なリソースとはコンテナ形式のもので、数値添字あるいは文字列添字 (PHP の配列と同じ) のいずれかの形式になります。シンプルなリソースは 文字列、整数、バイナリデータフィールド、整数の配列 のいずれかの型となります。

ResourceBundle からデータにアクセスするには、 配列を使う方法と foreach を使う方法、そしてクラスメソッドを使う方法があります。 シンプルなリソースの場合は PHP の値、複雑なリソースの場合は ResourceBundle オブジェクトとして取得できます。 リソースはすべて読み込み専用となります。

クラス概要

class ResourceBundle implements IteratorAggregate, Countable {
/* メソッド */
public __construct(?string $locale, ?string $bundle, bool $fallback = true)
public count(): int
public static create(?string $locale, ?string $bundle, bool $fallback = true): ?ResourceBundle
public get(string|int $index, bool $fallback = true): mixed
public getErrorCode(): int
public getErrorMessage(): string
public static getLocales(string $bundle): array|false
}

変更履歴

バージョン | 説明
8.0.0 | ResourceBundle は、 IteratorAggregate を実装しました。 これより前のバージョンでは、 Traversable を代わりに実装していました。
7.4.0 | ResourceBundle は、 Countable を新たに実装しました。

参考

  • » ICU Resource Management
  • » ICU Data

目次

  • ResourceBundle::count — バンドル内の要素数を取得する
  • ResourceBundle::create — リソースバンドルを作成する
  • ResourceBundle::get — バンドルからデータを取得する
  • ResourceBundle::getErrorCode — バンドルの直近のエラーコードを取得する
  • ResourceBundle::getErrorMessage — バンドルの直近のエラーメッセージを取得する
  • ResourceBundle::getLocales — サポートするロケールを取得する


バンドル内の要素数を取得する

  • ≪ ResourceBundle
  • ResourceBundle::create ≫
  • PHP Manual
  • ResourceBundle
  • バンドル内の要素数を取得する

ResourceBundle::count

resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — バンドル内の要素数を取得する

説明

オブジェクト指向型

public ResourceBundle::count(): int

手続き型

resourcebundle_count(ResourceBundle $bundle): int

バンドル内の要素数を取得します。

パラメータ

bundle

ResourceBundle オブジェクト。

戻り値

バンドル内の要素数を返します。

例

例1 resourcebundle_count() の例

<?php
$r = resourcebundle_create( 'es', "/usr/share/data/myapp");
echo resourcebundle_count($r);
?>

例2 オブジェクト指向の例

<?php
$r = new ResourceBundle( 'es', "/usr/share/data/myapp");
echo $r->count();
?>

上の例の出力は以下となります。

42

参考

  • resourcebundle_get() - バンドルからデータを取得する


リソースバンドルを作成する

  • ≪ ResourceBundle::count
  • ResourceBundle::get ≫
  • PHP Manual
  • ResourceBundle
  • リソースバンドルを作成する

ResourceBundle::create

resourcebundle_create

ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — リソースバンドルを作成する

説明

オブジェクト指向型 (メソッド)

public static ResourceBundle::create(?string $locale, ?string $bundle, bool $fallback = true): ?ResourceBundle

手続き型

resourcebundle_create(?string $locale, ?string $bundle, bool $fallback = true): ?ResourceBundle

オブジェクト指向型 (コンストラクタ):

public ResourceBundle::__construct(?string $locale, ?string $bundle, bool $fallback = true)

リソースバンドルを作成します。

パラメータ

locale

リソースバンドルを読み込むロケール (en_CA などのロケール名)。

bundle

データが格納されているディレクトリ、あるいは .dat ファイル名。

fallback

ロケールを完全一致とするか、あるいは代替として親ロケールを使うことを許可するか。

戻り値

ResourceBundle オブジェクト、あるいはエラー時に null を返します。

例

例1 resourcebundle_create() の例

<?php
$r = resourcebundle_create( 'es', "/usr/share/data/myapp");
echo $r['teststring'];
?>

例2 ResourceBundle::create() の例

<?php
$r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
echo $r['teststring'];
?>

上の例の出力は以下となります。

!Hola, mundo!

参考

  • resourcebundle_get() - バンドルからデータを取得する


バンドルからデータを取得する

  • ≪ ResourceBundle::create
  • ResourceBundle::getErrorCode ≫
  • PHP Manual
  • ResourceBundle
  • バンドルからデータを取得する

ResourceBundle::get

resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — バンドルからデータを取得する

説明

オブジェクト指向型

public ResourceBundle::get(string|int $index, bool $fallback = true): mixed

手続き型

resourcebundle_get(ResourceBundle $bundle, string|int $index, bool $fallback = true): mixed

インデックスあるいは文字列キーを指定して、バンドルからデータを取得します。

パラメータ

bundle

ResourceBundle オブジェクト。

index

データのインデックス。文字列あるいは整数値となります。

fallback

ロケールが正確にマッチしなければ、 親のロケールにfallback することを許すかどうか

戻り値

指定したインデックスのデータ、あるいはエラー時に null を返します。 文字列、整数値、バイナリデータ文字列は、それぞれに対応する PHP の型として返します。 整数の配列は PHP の配列として返します。複雑な型は ResourceBundle オブジェクトとして返します。

例

例1 resourcebundle_get() の例

<?php
$r = resourcebundle_create( 'es', "/usr/share/data/myapp");
echo resourcebundle_get($r, 'somestring');
?>

例2 オブジェクト指向の例

<?php
$r = new ResourceBundle( 'es', "/usr/share/data/myapp");
echo $r->get('somestring');
?>

上の例の出力は以下となります。

?Hola, mundo!

参考

  • resourcebundle_count() - バンドル内の要素数を取得する


バンドルの直近のエラーコードを取得する

  • ≪ ResourceBundle::get
  • ResourceBundle::getErrorMessage ≫
  • PHP Manual
  • ResourceBundle
  • バンドルの直近のエラーコードを取得する

ResourceBundle::getErrorCode

resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — バンドルの直近のエラーコードを取得する

説明

オブジェクト指向型

public ResourceBundle::getErrorCode(): int

手続き型

resourcebundle_get_error_code(ResourceBundle $bundle): int

バンドルオブジェクトが最後に実行した関数のエラーコードを取得します。

パラメータ

bundle

ResourceBundle オブジェクト。

戻り値

バンドルオブジェクトの最後の関数コールからのエラーコードを返します。

例

例1 resourcebundle_get_error_code() の例

<?php
$r = resourcebundle_create( 'es', "/usr/share/data/myapp");
echo $r['somestring'];
if(intl_is_failure(resourcebundle_get_error_code($r))) {
report_error("Bundle error");
}
?>

例2 オブジェクト指向の例

<?php
$r = new ResourceBundle( 'es', "/usr/share/data/myapp");
echo $r['somestring'];
if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
report_error("Bundle error");
}
?>

参考

  • resourcebundle_get_error_message() - バンドルの直近のエラーメッセージを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


バンドルの直近のエラーメッセージを取得する

  • ≪ ResourceBundle::getErrorCode
  • ResourceBundle::getLocales ≫
  • PHP Manual
  • ResourceBundle
  • バンドルの直近のエラーメッセージを取得する

ResourceBundle::getErrorMessage

resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — バンドルの直近のエラーメッセージを取得する

説明

オブジェクト指向型

public ResourceBundle::getErrorMessage(): string

手続き型

resourcebundle_get_error_message(ResourceBundle $bundle): string

バンドルオブジェクトが最後に実行した関数のエラーメッセージを取得します。

パラメータ

bundle

ResourceBundle オブジェクト。

戻り値

バンドルオブジェクトの最後の関数コールからのエラーメッセージを返します。

例

例1 resourcebundle_get_error_message() の例

<?php
$r = resourcebundle_create( 'es', "/usr/share/data/myapp");
echo $r['somestring'];
if(intl_is_failure(resourcebundle_get_error_code($r))) {
report_error("Bundle error: ".resourcebundle_get_error_message($r));
}
?>

例2 オブジェクト指向の例

<?php
$r = new ResourceBundle( 'es', "/usr/share/data/myapp");
echo $r['somestring'];
if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
report_error("Bundle error: ".ResourceBundle::getErrorMessage($r));
}
?>

参考

  • resourcebundle_get_error_code() - バンドルの直近のエラーコードを取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる


サポートするロケールを取得する

  • ≪ ResourceBundle::getErrorMessage
  • Spoofchecker ≫
  • PHP Manual
  • ResourceBundle
  • サポートするロケールを取得する

ResourceBundle::getLocales

resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — サポートするロケールを取得する

説明

オブジェクト指向型

public static ResourceBundle::getLocales(string $bundle): array|false

手続き型

resourcebundle_locales(string $bundle): array|false

ResourceBundle 名を指定して、サポートするロケールを取得します。

パラメータ

bundle

ロケールを取得したい ResourceBundle のパス、あるいは 空文字列を指定するとデフォルトのロケール一覧を取得できます。

戻り値

このバンドルがサポートするロケールの一覧を返します。 失敗した場合は false を返します。

例

例1 resourcebundle_locales() の例

<?php
$bundle = "/user/share/data/myapp";
echo join(PHP_EOL, resourcebundle_locales($bundle));
?>

上の例の出力は、 たとえば以下のようになります。

es
root

例2 オブジェクト指向の例

<?php
$bundle = "/usr/share/data/myapp";
$r = new ResourceBundle( 'es', $bundle);
echo join("\n", $r->getLocales($bundle));
?>

上の例の出力は、 たとえば以下のようになります。

es
root

参考

  • resourcebundle_get() - バンドルからデータを取得する


Spoofchecker クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

はじめに

Unicode は非常にたくさんの文字と、 世界中の様々な表記体系を含んでいます。 そのため使い方を誤ると、 文字の類似性を利用して、 プログラムやシステムに対するセキュリティ攻撃が成立する可能性があります。 そのため、このクラスが提供されています。

このクラスのメソッドを使うと、 個別の文字列が、文字の読み手を混乱させようとしている可能性があるかをチェック(spoof detection)できます。 たとえば、キリル文字の 'а' が混じった "pаypаl" のような文字列のようなものをチェックできます。

クラス概要

class Spoofchecker {
/* 定数 */
public const int SINGLE_SCRIPT_CONFUSABLE;
public const int MIXED_SCRIPT_CONFUSABLE;
public const int WHOLE_SCRIPT_CONFUSABLE;
public const int ANY_CASE;
public const int SINGLE_SCRIPT;
public const int INVISIBLE;
public const int CHAR_LIMIT;
public const int ASCII;
public const int HIGHLY_RESTRICTIVE;
public const int MODERATELY_RESTRICTIVE;
public const int MINIMALLY_RESTRICTIVE;
public const int UNRESTRICTIVE;
public const int SINGLE_SCRIPT_RESTRICTIVE;
public const int MIXED_NUMBERS;
public const int HIDDEN_OVERLAY;
/* メソッド */
public __construct()
public areConfusable(string $string1, string $string2, int &$errorCode = null): bool
public isSuspicious(string $string, int &$errorCode = null): bool
public setAllowedLocales(string $locales): void
public setChecks(int $checks): void
public setRestrictionLevel(int $level): void
}

定義済み定数

Spoofchecker::SINGLE_SCRIPT_CONFUSABLE

Spoofchecker::MIXED_SCRIPT_CONFUSABLE

Spoofchecker::WHOLE_SCRIPT_CONFUSABLE

Spoofchecker::ANY_CASE

Spoofchecker::SINGLE_SCRIPT

Spoofchecker::INVISIBLE

Spoofchecker::CHAR_LIMIT

Spoofchecker::ASCII

Spoofchecker::HIGHLY_RESTRICTIVE

Spoofchecker::MODERATELY_RESTRICTIVE

Spoofchecker::MINIMALLY_RESTRICTIVE

Spoofchecker::UNRESTRICTIVE

Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE

Spoofchecker::MIXED_NUMBERS

Spoofchecker::HIDDEN_OVERLAY

変更履歴

バージョン | 説明
7.3.0 | Spoofchecker::setRestrictionLevel() で使うクラス定数、Spoofchecker::ASCII, Spoofchecker::HIGHLY_RESTRICTIVE, Spoofchecker::MODERATELY_RESTRICTIVE, Spoofchecker::MINIMALLY_RESTRICTIVE, Spoofchecker::UNRESTRICTIVE, Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE が追加されました。

目次

  • Spoofchecker::areConfusable — 指定された文字列が、読み手を混乱させうるかをチェックする
  • Spoofchecker::__construct — コンストラクタ
  • Spoofchecker::isSuspicious — 指定されたテキストに、疑わしい文字が含まれていないかをチェックする
  • Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する
  • Spoofchecker::setChecks — 実行するチェックを設定する
  • Spoofchecker::setRestrictionLevel — 制限レベルを設定する


指定された文字列が、読み手を混乱させうるかをチェックする

  • ≪ Spoofchecker
  • Spoofchecker::__construct ≫
  • PHP Manual
  • Spoofchecker
  • 指定された文字列が、読み手を混乱させうるかをチェックする

Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — 指定された文字列が、読み手を混乱させうるかをチェックする

説明

public Spoofchecker::areConfusable(string $string1, string $string2, int &$errorCode = null): bool

ふたつの指定された文字列が、間違いやすいものかをチェックします。

パラメータ

string1

チェックするひとつめの文字列。

string2

チェックするふたつめの文字列。

errorCode

整数のリファレンスを設定します。 エラーがあった場合には、 エラーコード値を含みます。

戻り値

ふたつの指定された文字列が、間違いやすいものであれば true を、 そうでない場合は false を返します。

例

例1 Spoofchecker::areConfusable() の例

<?php
$checker = new Spoofchecker();

$checker->areConfusable('google.com', 'goog1e.com'); // true
// Lower l can be confused with digit one

$checker->areConfusable('google.com', 'g00g1e.com'); // false
// Zero (0) cannot be easily confused with "o" letter


コンストラクタ

  • ≪ Spoofchecker::areConfusable
  • Spoofchecker::isSuspicious ≫
  • PHP Manual
  • Spoofchecker
  • コンストラクタ

Spoofchecker::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Spoofchecker::__construct — コンストラクタ

説明

public Spoofchecker::__construct()

Spoofchecker の新しいインスタンスを作成します。

パラメータ

この関数にはパラメータはありません。


指定されたテキストに、疑わしい文字が含まれていないかをチェックする

  • ≪ Spoofchecker::__construct
  • Spoofchecker::setAllowedLocales ≫
  • PHP Manual
  • Spoofchecker
  • 指定されたテキストに、疑わしい文字が含まれていないかをチェックする

Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — 指定されたテキストに、疑わしい文字が含まれていないかをチェックする

説明

public Spoofchecker::isSuspicious(string $string, int &$errorCode = null): bool

指定された文字列に、見た目は殆ど同じように見えるが、 Unicode 文字的には異なる、疑わしい文字が含まれているかを調べます。

パラメータ

string

調べる文字列

errorCode

整数のリファレンスを設定します。 エラーがあった場合には、 エラーコード値を含みます。

戻り値

疑わしい文字が含まれている場合は true を、 そうでない場合は false を返します。

例

例1 Spoofchecker::isSuspicious() の例

<?php
$checker = new Spoofchecker();

$checker->isSuspicious('google.com'); // FALSE: only ASCII characters

$checker->isSuspicious('Рaypal.com'); // TRUE
// The first letter is from Cyrylic, not a regular latin "P"


チェック時に使うロケールを設定する

  • ≪ Spoofchecker::isSuspicious
  • Spoofchecker::setChecks ≫
  • PHP Manual
  • Spoofchecker
  • チェック時に使うロケールを設定する

Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する

説明

public Spoofchecker::setAllowedLocales(string $locales): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locales

戻り値


実行するチェックを設定する

  • ≪ Spoofchecker::setAllowedLocales
  • Spoofchecker::setRestrictionLevel ≫
  • PHP Manual
  • Spoofchecker
  • 実行するチェックを設定する

Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — 実行するチェックを設定する

説明

public Spoofchecker::setChecks(int $checks): void

SpoofChecker::isSuspicious() で行われるチェックの種類を設定します。

パラメータ

checks

SpoofChecker::isSuspicious()
で行われるチェック。
以下からなるビットマスクの組み合わせです。
Spoofchecker::SINGLE_SCRIPT_CONFUSABLE,
Spoofchecker::MIXED_SCRIPT_CONFUSABLE,
Spoofchecker::WHOLE_SCRIPT_CONFUSABLE,
Spoofchecker::ANY_CASE,
Spoofchecker::SINGLE_SCRIPT,
Spoofchecker::INVISIBLE,
Spoofchecker::CHAR_LIMIT。
ICU 58 以降では、デフォルトで全てのチェックが設定されます。
それより前のバージョンでは、全てのチェックから
Spoofchecker::SINGLE_SCRIPT
が除外されていました。

戻り値

値を返しません。


制限レベルを設定する

  • ≪ Spoofchecker::setChecks
  • Transliterator ≫
  • PHP Manual
  • Spoofchecker
  • 制限レベルを設定する

Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — 制限レベルを設定する

説明

public Spoofchecker::setRestrictionLevel(int $level): void

SpoofChecker::isSuspicious() の制限レベルを設定します。

パラメータ

level

SpoofChecker::isSuspicious() の制限レベル。
以下のうちひとつを指定します:
Spoofchecker::ASCII,
Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE,
Spoofchecker::HIGHLY_RESTRICTIVE,
Spoofchecker::MODERATELY_RESTRICTIVE,
Spoofchecker::MINIMALLY_RESTRICTIVE,
Spoofchecker::UNRESTRICTIVE.
デフォルトは Spoofchecker::HIGHLY_RESTRICTIVE です。

戻り値

値を返しません。


Transliterator クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

はじめに

Transliterator クラスは、文字列の音訳を行います。

クラス概要

class Transliterator {
/* 定数 */
public const int FORWARD;
public const int REVERSE;
/* プロパティ */
public readonly string $id;
/* メソッド */
final private __construct()
public static create(string $id, int $direction = Transliterator::FORWARD): ?Transliterator
public static createFromRules(string $rules, int $direction = Transliterator::FORWARD): ?Transliterator
public createInverse(): ?Transliterator
public getErrorCode(): int|false
public getErrorMessage(): string|false
public static listIDs(): array|false
public transliterate(string $string, int $start = 0, int $end = -1): string|false
}

プロパティ

id

定義済み定数

Transliterator::FORWARD

Transliterator::REVERSE

変更履歴

バージョン | 説明
8.2.0 | プロパティ id は、readonly になりました。

目次

  • Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ
  • Transliterator::create — Transliterator を作成する
  • Transliterator::createFromRules — 規則に基づいた Transliterator を作成する
  • Transliterator::createInverse — 逆方向の Transliterator を作成する
  • Transliterator::getErrorCode — 直近のエラーコードを取得する
  • Transliterator::getErrorMessage — 直近のエラーメッセージを取得する
  • Transliterator::listIDs — Transliterator の ID を取得する
  • Transliterator::transliterate — 文字列を音訳する


インスタンス化を拒否するために private にしたコンストラクタ

  • ≪ Transliterator
  • Transliterator::create ≫
  • PHP Manual
  • Transliterator
  • インスタンス化を拒否するために private にしたコンストラクタ

Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ

説明

final private Transliterator::__construct()

このメソッドをコールしてはいけません。 new 演算子によるインスタンス化を拒否するために用意されたものです。

かわりに、ファクトリーメソッドである Transliterator::create() あるいは Transliterator::createFromRules() を使いましょう。

パラメータ

この関数にはパラメータはありません。

参考

  • Transliterator::create() - Transliterator を作成する
  • Transliterator::createFromRules() - 規則に基づいた Transliterator を作成する


Transliterator を作成する

  • ≪ Transliterator::__construct
  • Transliterator::createFromRules ≫
  • PHP Manual
  • Transliterator
  • Transliterator を作成する

Transliterator::create

transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Transliterator を作成する

説明

オブジェクト指向型

public static Transliterator::create(string $id, int $direction = Transliterator::FORWARD): ?Transliterator

手続き型

transliterator_create(string $id, int $direction = Transliterator::FORWARD): ?Transliterator

ID を指定して Transliterator をオープンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

id

ID を指定します。 全ての登録済みの transliterator ID は、 Transliterator::listIDs() を使って取得できます。

direction

方向。デフォルトは Transliterator::FORWARD です。 Transliterator::REVERSE も指定できます。

戻り値

成功した場合に Transliterator オブジェクト、失敗した場合に null を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::__construct() - インスタンス化を拒否するために private にしたコンストラクタ


規則に基づいた Transliterator を作成する

  • ≪ Transliterator::create
  • Transliterator::createInverse ≫
  • PHP Manual
  • Transliterator
  • 規則に基づいた Transliterator を作成する

Transliterator::createFromRules

transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — 規則に基づいた Transliterator を作成する

説明

オブジェクト指向型

public static Transliterator::createFromRules(string $rules, int $direction = Transliterator::FORWARD): ?Transliterator

手続き型

transliterator_create_from_rules(string $rules, int $direction = Transliterator::FORWARD): ?Transliterator

規則に基づいた Transliterator を作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rules

UTS #35 (LDML) の "Transform Rules Syntax" で定義されている規則です。

direction

方向。デフォルトは Transliterator::FORWARD です。 Transliterator::REVERSE も指定できます。

戻り値

成功した場合に Transliterator オブジェクト、失敗した場合に null を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::create() - Transliterator を作成する


逆方向の Transliterator を作成する

  • ≪ Transliterator::createFromRules
  • Transliterator::getErrorCode ≫
  • PHP Manual
  • Transliterator
  • 逆方向の Transliterator を作成する

Transliterator::createInverse

transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — 逆方向の Transliterator を作成する

説明

オブジェクト指向型

public Transliterator::createInverse(): ?Transliterator

手続き型

transliterator_create_inverse(Transliterator $transliterator): ?Transliterator

逆方向の Transliterator をオープンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に Transliterator オブジェクト、失敗した場合に null を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::create() - Transliterator を作成する


直近のエラーコードを取得する

  • ≪ Transliterator::createInverse
  • Transliterator::getErrorMessage ≫
  • PHP Manual
  • Transliterator
  • 直近のエラーコードを取得する

Transliterator::getErrorCode

transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — 直近のエラーコードを取得する

説明

オブジェクト指向型

public Transliterator::getErrorCode(): int|false

手続き型

transliterator_get_error_code(Transliterator $transliterator): int|false

この Transliterator の直近のエラーコードを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

transliterator

戻り値

成功した場合にエラーコードを返します。 エラーがない場合や失敗した場合は false を返します。

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::listIDs() - Transliterator の ID を取得する


直近のエラーメッセージを取得する

  • ≪ Transliterator::getErrorCode
  • Transliterator::listIDs ≫
  • PHP Manual
  • Transliterator
  • 直近のエラーメッセージを取得する

Transliterator::getErrorMessage

transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — 直近のエラーメッセージを取得する

説明

オブジェクト指向型

public Transliterator::getErrorMessage(): string|false

手続き型

transliterator_get_error_message(Transliterator $transliterator): string|false

この Transliterator の直近のエラーメッセージを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

transliterator

戻り値

成功した場合にエラーメッセージを返します。 エラーがない場合や失敗した場合は false を返します。

参考

  • Transliterator::getErrorCode() - 直近のエラーコードを取得する
  • Transliterator::listIDs() - Transliterator の ID を取得する


Transliterator の ID を取得する

  • ≪ Transliterator::getErrorMessage
  • Transliterator::transliterate ≫
  • PHP Manual
  • Transliterator
  • Transliterator の ID を取得する

Transliterator::listIDs

transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Transliterator の ID を取得する

説明

オブジェクト指向型

public static Transliterator::listIDs(): array|false

手続き型

transliterator_list_ids(): array|false

登録されている Transliterator ID の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合は登録されている Transliterator ID の配列を返します。 失敗した場合に false を返します。

例

例1 登録済みの transliterator ID を取得する

<?php
print_r(Transliterator::listIDs());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => ASCII-Latin
    [1] => Accents-Any
    [2] => Amharic-Latin/BGN
    [3] => Any-Accents
    [4] => Any-Publishing
...
    [650] => Any-ps_Latn/BGN
    [651] => Any-tk/BGN
    [652] => Any-ch_FONIPA
    [653] => Any-cs_FONIPA
    [654] => Any-cy_FONIPA
)

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::transliterate() - 文字列を音訳する


文字列を音訳する

  • ≪ Transliterator::listIDs
  • IntlBreakIterator ≫
  • PHP Manual
  • Transliterator
  • 文字列を音訳する

Transliterator::transliterate

transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — 文字列を音訳する

説明

オブジェクト指向型

public Transliterator::transliterate(string $string, int $start = 0, int $end = -1): string|false

手続き型

transliterator_transliterate(
Transliterator|string $transliterator,
string $string,
int $start = 0,
int $end = -1
): string|false

文字列あるいはその一部をICU の音訳器を使って変換します。

パラメータ

transliterator

手続き型の場合に、Transliterator あるいは Transliterator を作成できる文字列を指定します。

string

変換する文字列。

start

文字列の変換の開始位置を表すインデックス (UTF-16 コード単位) を指定します。指定した位置も、変換範囲に含まれます。 インデックスは 0 から始まります。この位置より前にあるテキストは、そのまま残ります。

end

文字列の変換の終了位置を表すインデックス (UTF-16 コード単位) を指定します。指定した位置は、変換範囲に含まれません。 インデックスは 0 から始まります。この位置も含めてそれ以降にあるテキストは、そのまま残ります。

戻り値

成功した場合に変換後の文字列を返します。 失敗した場合に false を返します。

例

例1 エスケープされた UTF-16 コード単位の変換

<?php
$s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
echo transliterator_transliterate("Hex-Any/Java", $s), "\n";

//now the reverse operation with a supplementary character
$supplChar = html_entity_decode('&#x1D11E;');
echo mb_strlen($supplChar, "UTF-8"), "\n";
$encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
//echoes two encoded UTF-16 code units
echo $encSupplChar, "\n";
//and back
echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

お早うございます
1
\uD834\uDD1E
??

参考

  • Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
  • Transliterator::__construct() - インスタンス化を拒否するために private にしたコンストラクタ


IntlBreakIterator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

"break iterator" は、 テキスト中のどこに境界 (たとえば、単語や文章の境目) が位置するのかに関するメソッドを公開しています。 PHP の IntlBreakIterator は、 全ての break iterator の基底クラスになります。 追加の機能が利用可能な場合は、 intl 拡張モジュールは適切なサブクラスを公開しています。 たとえば、 IntlRuleBasedBreakIterator や IntlCodePointBreakIterator です。

このクラスは、 IteratorAggregate も実装しています。 IntlBreakIterator を走査すると、 テキストに存在する連続する境界を示す、 負でない整数値を返します。 これは、UTF-8 のコード単位(バイト) の数として表現され、 テキストの最初 (これは、位置 0 になります) から取得されます。 イテレータによって返されるキーは、 {0, 1, 2, ...} のように、自然数の順序に並びます。

クラス概要

class IntlBreakIterator implements IteratorAggregate {
/* 定数 */
public const int DONE;
public const int WORD_NONE;
public const int WORD_NONE_LIMIT;
public const int WORD_NUMBER;
public const int WORD_NUMBER_LIMIT;
public const int WORD_LETTER;
public const int WORD_LETTER_LIMIT;
public const int WORD_KANA;
public const int WORD_KANA_LIMIT;
public const int WORD_IDEO;
public const int WORD_IDEO_LIMIT;
public const int LINE_SOFT;
public const int LINE_SOFT_LIMIT;
public const int LINE_HARD;
public const int LINE_HARD_LIMIT;
public const int SENTENCE_TERM;
public const int SENTENCE_TERM_LIMIT;
public const int SENTENCE_SEP;
public const int SENTENCE_SEP_LIMIT;
/* メソッド */
private __construct()
public static createCharacterInstance(?string $locale = null): ?IntlBreakIterator
public static createCodePointInstance(): IntlCodePointBreakIterator
public static createLineInstance(?string $locale = null): ?IntlBreakIterator
public static createSentenceInstance(?string $locale = null): ?IntlBreakIterator
public static createTitleInstance(?string $locale = null): ?IntlBreakIterator
public static createWordInstance(?string $locale = null): ?IntlBreakIterator
public current(): int
public first(): int
public following(int $offset): int
public getErrorCode(): int
public getErrorMessage(): string
public getLocale(int $type): string|false
public getPartsIterator(string $type = IntlPartsIterator::KEY_SEQUENTIAL): IntlPartsIterator
public getText(): ?string
public isBoundary(int $offset): bool
public last(): int
public next(?int $offset = null): int
public preceding(int $offset): int
public previous(): int
public setText(string $text): bool
}

定義済み定数

IntlBreakIterator::DONE

IntlBreakIterator::WORD_NONE

IntlBreakIterator::WORD_NONE_LIMIT

IntlBreakIterator::WORD_NUMBER

IntlBreakIterator::WORD_NUMBER_LIMIT

IntlBreakIterator::WORD_LETTER

IntlBreakIterator::WORD_LETTER_LIMIT

IntlBreakIterator::WORD_KANA

IntlBreakIterator::WORD_KANA_LIMIT

IntlBreakIterator::WORD_IDEO

IntlBreakIterator::WORD_IDEO_LIMIT

IntlBreakIterator::LINE_SOFT

IntlBreakIterator::LINE_SOFT_LIMIT

IntlBreakIterator::LINE_HARD

IntlBreakIterator::LINE_HARD_LIMIT

IntlBreakIterator::SENTENCE_TERM

IntlBreakIterator::SENTENCE_TERM_LIMIT

IntlBreakIterator::SENTENCE_SEP

IntlBreakIterator::SENTENCE_SEP_LIMIT

変更履歴

バージョン | 説明
8.0.0 | IntlBreakIterator は、 IteratorAggregate を実装しました。 これより前のバージョンでは、 Traversable を代わりに実装していました。

目次

  • IntlBreakIterator::__construct — インスタンス化を禁止するためのprivateなコンストラクタ
  • IntlBreakIterator::createCharacterInstance — 文字シーケンスの組み合わせの境界用にイテレータを作る
  • IntlBreakIterator::createCodePointInstance — コードポイントの境界用にイテレータを作る
  • IntlBreakIterator::createLineInstance — 論理的に可能な改行用にイテレータを作る
  • IntlBreakIterator::createSentenceInstance — 文末用にイテレータを作る
  • IntlBreakIterator::createTitleInstance — タイトル文字の区切り用にイテレータを作る
  • IntlBreakIterator::createWordInstance — 単語の区切り用にイテレータを作る
  • IntlBreakIterator::current — 現在位置のインデックスを取得する
  • IntlBreakIterator::first — テキスト内の最初の文字を場所を取得する
  • IntlBreakIterator::following — 指定したオフセット以降の最初の境界までイテレータを進める
  • IntlBreakIterator::getErrorCode — このオブジェクトの直近のエラーコードを取得する
  • IntlBreakIterator::getErrorMessage — このオブジェクトの直近のエラーメッセージを取得する
  • IntlBreakIterator::getLocale — このオブジェクトに関連づけられたロケールを取得する
  • IntlBreakIterator::getPartsIterator — 境界と境界の間の navigating fragments 用にイテレータを作る
  • IntlBreakIterator::getText — スキャンするテキストを取得する
  • IntlBreakIterator::isBoundary — あるオフセットが境界のオフセットかどうかを調べる
  • IntlBreakIterator::last — イテレータの位置を、最後の文字より後に設定する
  • IntlBreakIterator::next — イテレータを次の境界まで進める
  • IntlBreakIterator::preceding — イテレータの位置を、指定したオフセット以前の最初の境界に設定する
  • IntlBreakIterator::previous — イテレータの位置を、現在位置の直前の境界に設定する
  • IntlBreakIterator::setText — スキャンするテキストを設定する


インスタンス化を禁止するためのprivateなコンストラクタ

  • ≪ IntlBreakIterator
  • IntlBreakIterator::createCharacterInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • インスタンス化を禁止するためのprivateなコンストラクタ

IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — インスタンス化を禁止するためのprivateなコンストラクタ

説明

private IntlBreakIterator::__construct()

IntlBreakIterator のインスタンスは、 static なファクトリメソッドのうちの一つを使って生成してください。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • IntlBreakIterator::createCharacterInstance() - 文字シーケンスの組み合わせの境界用にイテレータを作る
  • IntlBreakIterator::createCodePointInstance() - コードポイントの境界用にイテレータを作る
  • IntlBreakIterator::createLineInstance() - 論理的に可能な改行用にイテレータを作る
  • IntlBreakIterator::createSentenceInstance() - 文末用にイテレータを作る
  • IntlBreakIterator::createTitleInstance() - タイトル文字の区切り用にイテレータを作る
  • IntlBreakIterator::createWordInstance() - 単語の区切り用にイテレータを作る


文字シーケンスの組み合わせの境界用にイテレータを作る

  • ≪ IntlBreakIterator::__construct
  • IntlBreakIterator::createCodePointInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • 文字シーケンスの組み合わせの境界用にイテレータを作る

IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — 文字シーケンスの組み合わせの境界用にイテレータを作る

説明

public static IntlBreakIterator::createCharacterInstance(?string $locale = null): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

戻り値


コードポイントの境界用にイテレータを作る

  • ≪ IntlBreakIterator::createCharacterInstance
  • IntlBreakIterator::createLineInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • コードポイントの境界用にイテレータを作る

IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — コードポイントの境界用にイテレータを作る

説明

public static IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


論理的に可能な改行用にイテレータを作る

  • ≪ IntlBreakIterator::createCodePointInstance
  • IntlBreakIterator::createSentenceInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • 論理的に可能な改行用にイテレータを作る

IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — 論理的に可能な改行用にイテレータを作る

説明

public static IntlBreakIterator::createLineInstance(?string $locale = null): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

戻り値


文末用にイテレータを作る

  • ≪ IntlBreakIterator::createLineInstance
  • IntlBreakIterator::createTitleInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • 文末用にイテレータを作る

IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — 文末用にイテレータを作る

説明

public static IntlBreakIterator::createSentenceInstance(?string $locale = null): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

戻り値


タイトル文字の区切り用にイテレータを作る

  • ≪ IntlBreakIterator::createSentenceInstance
  • IntlBreakIterator::createWordInstance ≫
  • PHP Manual
  • IntlBreakIterator
  • タイトル文字の区切り用にイテレータを作る

IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — タイトル文字の区切り用にイテレータを作る

説明

public static IntlBreakIterator::createTitleInstance(?string $locale = null): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

戻り値


単語の区切り用にイテレータを作る

  • ≪ IntlBreakIterator::createTitleInstance
  • IntlBreakIterator::current ≫
  • PHP Manual
  • IntlBreakIterator
  • 単語の区切り用にイテレータを作る

IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — 単語の区切り用にイテレータを作る

説明

public static IntlBreakIterator::createWordInstance(?string $locale = null): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

locale

戻り値


現在位置のインデックスを取得する

  • ≪ IntlBreakIterator::createWordInstance
  • IntlBreakIterator::first ≫
  • PHP Manual
  • IntlBreakIterator
  • 現在位置のインデックスを取得する

IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — 現在位置のインデックスを取得する

説明

public IntlBreakIterator::current(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


テキスト内の最初の文字を場所を取得する

  • ≪ IntlBreakIterator::current
  • IntlBreakIterator::following ≫
  • PHP Manual
  • IntlBreakIterator
  • テキスト内の最初の文字を場所を取得する

IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — テキスト内の最初の文字を場所を取得する

説明

public IntlBreakIterator::first(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


指定したオフセット以降の最初の境界までイテレータを進める

  • ≪ IntlBreakIterator::first
  • IntlBreakIterator::getErrorCode ≫
  • PHP Manual
  • IntlBreakIterator
  • 指定したオフセット以降の最初の境界までイテレータを進める

IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — 指定したオフセット以降の最初の境界までイテレータを進める

説明

public IntlBreakIterator::following(int $offset): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

戻り値


このオブジェクトの直近のエラーコードを取得する

  • ≪ IntlBreakIterator::following
  • IntlBreakIterator::getErrorMessage ≫
  • PHP Manual
  • IntlBreakIterator
  • このオブジェクトの直近のエラーコードを取得する

IntlBreakIterator::getErrorCode

intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — このオブジェクトの直近のエラーコードを取得する

説明

オブジェクト指向型 (method):

public IntlBreakIterator::getErrorCode(): int

手続き型:

intl_get_error_code(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


このオブジェクトの直近のエラーメッセージを取得する

  • ≪ IntlBreakIterator::getErrorCode
  • IntlBreakIterator::getLocale ≫
  • PHP Manual
  • IntlBreakIterator
  • このオブジェクトの直近のエラーメッセージを取得する

IntlBreakIterator::getErrorMessage

intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — このオブジェクトの直近のエラーメッセージを取得する

説明

オブジェクト指向型 (method):

public IntlBreakIterator::getErrorMessage(): string

手続き型:

intl_get_error_message(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


このオブジェクトに関連づけられたロケールを取得する

  • ≪ IntlBreakIterator::getErrorMessage
  • IntlBreakIterator::getPartsIterator ≫
  • PHP Manual
  • IntlBreakIterator
  • このオブジェクトに関連づけられたロケールを取得する

IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — このオブジェクトに関連づけられたロケールを取得する

説明

public IntlBreakIterator::getLocale(int $type): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

type

戻り値


境界と境界の間の navigating fragments 用にイテレータを作る

  • ≪ IntlBreakIterator::getLocale
  • IntlBreakIterator::getText ≫
  • PHP Manual
  • IntlBreakIterator
  • 境界と境界の間の navigating fragments 用にイテレータを作る

IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — 境界と境界の間の navigating fragments 用にイテレータを作る

説明

public IntlBreakIterator::getPartsIterator(string $type = IntlPartsIterator::KEY_SEQUENTIAL): IntlPartsIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

type

オプションのキータイプ。可能な値は以下のとおりです:

  • IntlPartsIterator::KEY_SEQUENTIAL - デフォルト。シーケンシャルに増える整数をキーとして使います
  • IntlPartsIterator::KEY_LEFT - 現在のパートの左側のバイトオフセットをキーとして使います。
  • IntlPartsIterator::KEY_RIGHT - 現在のパートの右側のバイトオフセットをキーとして使います。

戻り値


スキャンするテキストを取得する

  • ≪ IntlBreakIterator::getPartsIterator
  • IntlBreakIterator::isBoundary ≫
  • PHP Manual
  • IntlBreakIterator
  • スキャンするテキストを取得する

IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — スキャンするテキストを取得する

説明

public IntlBreakIterator::getText(): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


あるオフセットが境界のオフセットかどうかを調べる

  • ≪ IntlBreakIterator::getText
  • IntlBreakIterator::last ≫
  • PHP Manual
  • IntlBreakIterator
  • あるオフセットが境界のオフセットかどうかを調べる

IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — あるオフセットが境界のオフセットかどうかを調べる

説明

public IntlBreakIterator::isBoundary(int $offset): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

戻り値


イテレータの位置を、最後の文字より後に設定する

  • ≪ IntlBreakIterator::isBoundary
  • IntlBreakIterator::next ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータの位置を、最後の文字より後に設定する

IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — イテレータの位置を、最後の文字より後に設定する

説明

public IntlBreakIterator::last(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


イテレータを次の境界まで進める

  • ≪ IntlBreakIterator::last
  • IntlBreakIterator::preceding ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータを次の境界まで進める

IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — イテレータを次の境界まで進める

説明

public IntlBreakIterator::next(?int $offset = null): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

戻り値


イテレータの位置を、指定したオフセット以前の最初の境界に設定する

  • ≪ IntlBreakIterator::next
  • IntlBreakIterator::previous ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータの位置を、指定したオフセット以前の最初の境界に設定する

IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — イテレータの位置を、指定したオフセット以前の最初の境界に設定する

説明

public IntlBreakIterator::preceding(int $offset): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

戻り値


イテレータの位置を、現在位置の直前の境界に設定する

  • ≪ IntlBreakIterator::preceding
  • IntlBreakIterator::setText ≫
  • PHP Manual
  • IntlBreakIterator
  • イテレータの位置を、現在位置の直前の境界に設定する

IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — イテレータの位置を、現在位置の直前の境界に設定する

説明

public IntlBreakIterator::previous(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


スキャンするテキストを設定する

  • ≪ IntlBreakIterator::previous
  • IntlRuleBasedBreakIterator ≫
  • PHP Manual
  • IntlBreakIterator
  • スキャンするテキストを設定する

IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — スキャンするテキストを設定する

説明

public IntlBreakIterator::setText(string $text): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | この関数は、失敗時に false を返すようになりました。 これより前のバージョンでは null を返していました。


IntlRuleBasedBreakIterator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

ICU の break iterator をカプセル化した IntlBreakIterator クラスのサブクラスです。 一定のルールを使って振る舞いが定義されています。 これは、殆どの break iterator に共通する機能です。

これらのルールは、 » ICU Boundary Analysis User Guide で説明されています。

クラス概要

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* 継承した定数 */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* メソッド */
public __construct(string $rules, bool $compiled = false)
public getBinaryRules(): string|false
public getRules(): string|false
public getRuleStatus(): int
public getRuleStatusVec(): array|false
/* 継承したメソッド */
public static IntlBreakIterator::createCharacterInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static IntlBreakIterator::createLineInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createSentenceInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createTitleInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createWordInstance(?string $locale = null): ?IntlBreakIterator
public IntlBreakIterator::current(): int
public IntlBreakIterator::first(): int
public IntlBreakIterator::following(int $offset): int
public IntlBreakIterator::getErrorCode(): int
public IntlBreakIterator::getErrorMessage(): string
public IntlBreakIterator::getLocale(int $type): string|false
public IntlBreakIterator::getPartsIterator(string $type = IntlPartsIterator::KEY_SEQUENTIAL): IntlPartsIterator
public IntlBreakIterator::getText(): ?string
public IntlBreakIterator::isBoundary(int $offset): bool
public IntlBreakIterator::last(): int
public IntlBreakIterator::next(?int $offset = null): int
public IntlBreakIterator::preceding(int $offset): int
public IntlBreakIterator::previous(): int
public IntlBreakIterator::setText(string $text): bool
}

目次

  • IntlRuleBasedBreakIterator::__construct — ルールセットから iterator を作成する
  • IntlRuleBasedBreakIterator::getBinaryRules — コンパイル済みのルールを、バイナリで取得する
  • IntlRuleBasedBreakIterator::getRules — このオブジェクトを作るのに使われているルールを取得する
  • IntlRuleBasedBreakIterator::getRuleStatus — 現在の境界位置を決めるルールから、ステータスの最大値を取得する
  • IntlRuleBasedBreakIterator::getRuleStatusVec — 現在の境界位置から定まるルールから、ステータス値を取得する


ルールセットから iterator を作成する

  • ≪ IntlRuleBasedBreakIterator
  • IntlRuleBasedBreakIterator::getBinaryRules ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • ルールセットから iterator を作成する

IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — ルールセットから iterator を作成する

説明

public IntlRuleBasedBreakIterator::__construct(string $rules, bool $compiled = false)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rules

compiled

戻り値


コンパイル済みのルールを、バイナリで取得する

  • ≪ IntlRuleBasedBreakIterator::__construct
  • IntlRuleBasedBreakIterator::getRules ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • コンパイル済みのルールを、バイナリで取得する

IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — コンパイル済みのルールを、バイナリで取得する

説明

public IntlRuleBasedBreakIterator::getBinaryRules(): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


このオブジェクトを作るのに使われているルールを取得する

  • ≪ IntlRuleBasedBreakIterator::getBinaryRules
  • IntlRuleBasedBreakIterator::getRuleStatus ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • このオブジェクトを作るのに使われているルールを取得する

IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — このオブジェクトを作るのに使われているルールを取得する

説明

public IntlRuleBasedBreakIterator::getRules(): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


現在の境界位置を決めるルールから、ステータスの最大値を取得する

  • ≪ IntlRuleBasedBreakIterator::getRules
  • IntlRuleBasedBreakIterator::getRuleStatusVec ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • 現在の境界位置を決めるルールから、ステータスの最大値を取得する

IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — 現在の境界位置を決めるルールから、ステータスの最大値を取得する

説明

public IntlRuleBasedBreakIterator::getRuleStatus(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


現在の境界位置から定まるルールから、ステータス値を取得する

  • ≪ IntlRuleBasedBreakIterator::getRuleStatus
  • IntlCodePointBreakIterator ≫
  • PHP Manual
  • IntlRuleBasedBreakIterator
  • 現在の境界位置から定まるルールから、ステータス値を取得する

IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — 現在の境界位置から定まるルールから、ステータス値を取得する

説明

public IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


IntlCodePointBreakIterator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

この break iterator は、UTF-8 のコードポイント間の境界を認識するものです。

クラス概要

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* 継承した定数 */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* メソッド */
public getLastCodePoint(): int
/* 継承したメソッド */
public static IntlBreakIterator::createCharacterInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static IntlBreakIterator::createLineInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createSentenceInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createTitleInstance(?string $locale = null): ?IntlBreakIterator
public static IntlBreakIterator::createWordInstance(?string $locale = null): ?IntlBreakIterator
public IntlBreakIterator::current(): int
public IntlBreakIterator::first(): int
public IntlBreakIterator::following(int $offset): int
public IntlBreakIterator::getErrorCode(): int
public IntlBreakIterator::getErrorMessage(): string
public IntlBreakIterator::getLocale(int $type): string|false
public IntlBreakIterator::getPartsIterator(string $type = IntlPartsIterator::KEY_SEQUENTIAL): IntlPartsIterator
public IntlBreakIterator::getText(): ?string
public IntlBreakIterator::isBoundary(int $offset): bool
public IntlBreakIterator::last(): int
public IntlBreakIterator::next(?int $offset = null): int
public IntlBreakIterator::preceding(int $offset): int
public IntlBreakIterator::previous(): int
public IntlBreakIterator::setText(string $text): bool
}

目次

  • IntlCodePointBreakIterator::getLastCodePoint — イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する


イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する

  • ≪ IntlCodePointBreakIterator
  • IntlDatePatternGenerator ≫
  • PHP Manual
  • IntlCodePointBreakIterator
  • イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する

IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する

説明

public IntlCodePointBreakIterator::getLastCodePoint(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


IntlDatePatternGenerator クラス

(PHP 8 >= 8.1.0)

はじめに

IntlDateFormatter で使われる、 地域化された 日付/時刻 のフォーマットパターン文字列を生成します。

クラス概要

class IntlDatePatternGenerator {
/* メソッド */
public __construct(?string $locale = null)
public static create(?string $locale = null): ?IntlDatePatternGenerator
public getBestPattern(string $skeleton): string|false
}

目次

  • IntlDatePatternGenerator::create — IntlDatePatternGenerator を作成する
  • IntlDatePatternGenerator::getBestPattern — もっとも適合した 日付/時刻 のフォーマットを決定する


IntlDatePatternGenerator を作成する

  • ≪ IntlDatePatternGenerator
  • IntlDatePatternGenerator::getBestPattern ≫
  • PHP Manual
  • IntlDatePatternGenerator
  • IntlDatePatternGenerator を作成する

IntlDatePatternGenerator::create

IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — IntlDatePatternGenerator を作成する

説明

public static IntlDatePatternGenerator::create(?string $locale = null): ?IntlDatePatternGenerator
public IntlDatePatternGenerator::__construct(?string $locale = null)

IntlDatePatternGenerator のインスタンスを作成します。

パラメータ

locale

ロケールを指定します。 null を渡すと、 intl.default_locale の設定を使います。

戻り値

成功時に IntlDatePatternGenerator のインスタンスを返します。失敗時に null を返します。


もっとも適合した 日付/時刻 のフォーマットを決定する

  • ≪ IntlDatePatternGenerator::create
  • IntlPartsIterator ≫
  • PHP Manual
  • IntlDatePatternGenerator
  • もっとも適合した 日付/時刻 のフォーマットを決定する

IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — もっとも適合した 日付/時刻 のフォーマットを決定する

説明

public IntlDatePatternGenerator::getBestPattern(string $skeleton): string|false

特定のロケールにもっとも合致した 日付/時刻のフォーマットがどれかを決定します。

パラメータ

skeleton

スケルトンを指定します。

戻り値

成功時に DateTimeInterface::format() が受け入れるフォーマットを返します。 失敗した場合に false を返します

例

例1 IntlDatePatternGenerator::getBestPattern() の例

<?php

$skeleton = 'YYYYMMdd';
$today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');

$patternGenerator = new \IntlDatePatternGenerator('de_DE');
$pattern = $patternGenerator->getBestPattern($skeleton);
echo 'de: ', \IntlDateFormatter::formatObject($today, $pattern, 'de_DE'), "\n";

$patternGenerator = new \IntlDatePatternGenerator('en_US');
$pattern = $patternGenerator->getBestPattern($skeleton);
echo 'en: ', \IntlDateFormatter::formatObject($today, $pattern, 'en_US');
?>

上の例の出力は以下となります。

de: 24.04.2021
en: 04/24/2021


IntlPartsIterator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

このクラスのインスタンスは、 IntlBreakIterator から得られます。 break iterator は走査するたびに、 一連の境界の位置を返しますが、 IntlPartsIterator は、ふたつの連続する境界の間で認識されたテキストの断片を提供します。

キーは境界の左側、右側、として表現されるかもしれませんし、 負でない整数値として表現されるだけかもしれません。 IntlBreakIterator::getPartsIterator() も参照ください。

クラス概要

class IntlPartsIterator extends IntlIterator {
/* 定数 */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* メソッド */
public getBreakIterator(): IntlBreakIterator
/* 継承したメソッド */
public IntlIterator::current(): mixed
public IntlIterator::key(): mixed
public IntlIterator::next(): void
public IntlIterator::rewind(): void
public IntlIterator::valid(): bool
}

定義済み定数

IntlPartsIterator::KEY_SEQUENTIAL

IntlPartsIterator::KEY_LEFT

IntlPartsIterator::KEY_RIGHT

目次

  • IntlPartsIterator::getBreakIterator — この parts iterator の裏付けとなる、IntlBreakIterator を取得する


この parts iterator の裏付けとなる、IntlBreakIterator を取得する

  • ≪ IntlPartsIterator
  • UConverter ≫
  • PHP Manual
  • IntlPartsIterator
  • この parts iterator の裏付けとなる、IntlBreakIterator を取得する

IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — この parts iterator の裏付けとなる、IntlBreakIterator を取得する

説明

public IntlPartsIterator::getBreakIterator(): IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


UConverter クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

はじめに

クラス概要

class UConverter {
/* 定数 */
public const int REASON_UNASSIGNED;
public const int REASON_ILLEGAL;
public const int REASON_IRREGULAR;
public const int REASON_RESET;
public const int REASON_CLOSE;
public const int REASON_CLONE;
public const int UNSUPPORTED_CONVERTER;
public const int SBCS;
public const int DBCS;
public const int MBCS;
public const int LATIN_1;
public const int UTF8;
public const int UTF16_BigEndian;
public const int UTF16_LittleEndian;
public const int UTF32_BigEndian;
public const int UTF32_LittleEndian;
public const int EBCDIC_STATEFUL;
public const int ISO_2022;
public const int LMBCS_1;
public const int LMBCS_2;
public const int LMBCS_3;
public const int LMBCS_4;
public const int LMBCS_5;
public const int LMBCS_6;
public const int LMBCS_8;
public const int LMBCS_11;
public const int LMBCS_16;
public const int LMBCS_17;
public const int LMBCS_18;
public const int LMBCS_19;
public const int LMBCS_LAST;
public const int HZ;
public const int SCSU;
public const int ISCII;
public const int US_ASCII;
public const int UTF7;
public const int BOCU1;
public const int UTF16;
public const int UTF32;
public const int CESU8;
public const int IMAP_MAILBOX;
/* メソッド */
public __construct(?string $destination_encoding = null, ?string $source_encoding = null)
public convert(string $str, bool $reverse = false): string|false
public fromUCallback(
int $reason,
array $source,
int $codePoint,
int &$error
): string|int|array|null
public static getAliases(string $name): array|false|null
public static getAvailable(): array
public getDestinationEncoding(): string|false|null
public getDestinationType(): int|false|null
public getErrorCode(): int
public getErrorMessage(): ?string
public getSourceEncoding(): string|false|null
public getSourceType(): int|false|null
public static getStandards(): ?array
public getSubstChars(): string|false|null
public static reasonText(int $reason): string
public setDestinationEncoding(string $encoding): bool
public setSourceEncoding(string $encoding): bool
public setSubstChars(string $chars): bool
public toUCallback(
int $reason,
string $source,
string $codeUnits,
int &$error
): string|int|array|null
public static transcode(
string $str,
string $toEncoding,
string $fromEncoding,
?array $options = null
): string|false
}

定義済み定数

UConverter::REASON_UNASSIGNED

UConverter::REASON_ILLEGAL

UConverter::REASON_IRREGULAR

UConverter::REASON_RESET

UConverter::REASON_CLOSE

UConverter::REASON_CLONE

UConverter::UNSUPPORTED_CONVERTER

UConverter::SBCS

UConverter::DBCS

UConverter::MBCS

UConverter::LATIN_1

UConverter::UTF8

UConverter::UTF16_BigEndian

UConverter::UTF16_LittleEndian

UConverter::UTF32_BigEndian

UConverter::UTF32_LittleEndian

UConverter::EBCDIC_STATEFUL

UConverter::ISO_2022

UConverter::LMBCS_1

UConverter::LMBCS_2

UConverter::LMBCS_3

UConverter::LMBCS_4

UConverter::LMBCS_5

UConverter::LMBCS_6

UConverter::LMBCS_8

UConverter::LMBCS_11

UConverter::LMBCS_16

UConverter::LMBCS_17

UConverter::LMBCS_18

UConverter::LMBCS_19

UConverter::LMBCS_LAST

UConverter::HZ

UConverter::SCSU

UConverter::ISCII

UConverter::US_ASCII

UConverter::UTF7

UConverter::BOCU1

UConverter::UTF16

UConverter::UTF32

UConverter::CESU8

UConverter::IMAP_MAILBOX

目次

  • UConverter::__construct — UConverter オブジェクトを作る
  • UConverter::convert — ある文字セットから別の文字セットに文字列を変換する
  • UConverter::fromUCallback — デフォルトの "from" コールバック関数
  • UConverter::getAliases — 指定した名前のエイリアスを取得する
  • UConverter::getAvailable — 利用可能なコンバーター名を取得する
  • UConverter::getDestinationEncoding — 変換先エンコーディングを取得する
  • UConverter::getDestinationType — 変換先のコンバーターの型を取得する
  • UConverter::getErrorCode — 直近のエラーコードを取得する
  • UConverter::getErrorMessage — 直近のエラーメッセージを取得する
  • UConverter::getSourceEncoding — 変換元エンコーディングを取得する
  • UConverter::getSourceType — 変換元のコンバーターの型を取得する
  • UConverter::getStandards — コンバーター名に対応する標準を取得する
  • UConverter::getSubstChars — 置換文字を取得する
  • UConverter::reasonText — コールバックの理由を表す文字列を取得する
  • UConverter::setDestinationEncoding — 変換先エンコーディングを設定する
  • UConverter::setSourceEncoding — 変換元エンコーディングを設定する
  • UConverter::setSubstChars — 置換文字を設定する
  • UConverter::toUCallback — デフォルトの "to" コールバック関数
  • UConverter::transcode — ある文字エンコーディングから別の文字エンコーディングに文字列を変換する


UConverter オブジェクトを作る

  • ≪ UConverter
  • UConverter::convert ≫
  • PHP Manual
  • UConverter
  • UConverter オブジェクトを作る

UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — UConverter オブジェクトを作る

説明

public UConverter::__construct(?string $destination_encoding = null, ?string $source_encoding = null)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

destination_encoding

source_encoding

戻り値


ある文字セットから別の文字セットに文字列を変換する

  • ≪ UConverter::__construct
  • UConverter::fromUCallback ≫
  • PHP Manual
  • UConverter
  • ある文字セットから別の文字セットに文字列を変換する

UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — ある文字セットから別の文字セットに文字列を変換する

説明

public UConverter::convert(string $str, bool $reverse = false): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

str

reverse

戻り値


デフォルトの "from" コールバック関数

  • ≪ UConverter::convert
  • UConverter::getAliases ≫
  • PHP Manual
  • UConverter
  • デフォルトの "from" コールバック関数

UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — デフォルトの "from" コールバック関数

説明

public UConverter::fromUCallback(
int $reason,
array $source,
int $codePoint,
int &$error
): string|int|array|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reason

source

codePoint

error

戻り値


指定した名前のエイリアスを取得する

  • ≪ UConverter::fromUCallback
  • UConverter::getAvailable ≫
  • PHP Manual
  • UConverter
  • 指定した名前のエイリアスを取得する

UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — 指定した名前のエイリアスを取得する

説明

public static UConverter::getAliases(string $name): array|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


利用可能なコンバーター名を取得する

  • ≪ UConverter::getAliases
  • UConverter::getDestinationEncoding ≫
  • PHP Manual
  • UConverter
  • 利用可能なコンバーター名を取得する

UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — 利用可能なコンバーター名を取得する

説明

public static UConverter::getAvailable(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


変換先エンコーディングを取得する

  • ≪ UConverter::getAvailable
  • UConverter::getDestinationType ≫
  • PHP Manual
  • UConverter
  • 変換先エンコーディングを取得する

UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — 変換先エンコーディングを取得する

説明

public UConverter::getDestinationEncoding(): string|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


変換先のコンバーターの型を取得する

  • ≪ UConverter::getDestinationEncoding
  • UConverter::getErrorCode ≫
  • PHP Manual
  • UConverter
  • 変換先のコンバーターの型を取得する

UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — 変換先のコンバーターの型を取得する

説明

public UConverter::getDestinationType(): int|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


直近のエラーコードを取得する

  • ≪ UConverter::getDestinationType
  • UConverter::getErrorMessage ≫
  • PHP Manual
  • UConverter
  • 直近のエラーコードを取得する

UConverter::getErrorCode

intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — 直近のエラーコードを取得する

説明

public UConverter::getErrorCode(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


直近のエラーメッセージを取得する

  • ≪ UConverter::getErrorCode
  • UConverter::getSourceEncoding ≫
  • PHP Manual
  • UConverter
  • 直近のエラーメッセージを取得する

UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — 直近のエラーメッセージを取得する

説明

public UConverter::getErrorMessage(): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


変換元エンコーディングを取得する

  • ≪ UConverter::getErrorMessage
  • UConverter::getSourceType ≫
  • PHP Manual
  • UConverter
  • 変換元エンコーディングを取得する

UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — 変換元エンコーディングを取得する

説明

public UConverter::getSourceEncoding(): string|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


変換元のコンバーターの型を取得する

  • ≪ UConverter::getSourceEncoding
  • UConverter::getStandards ≫
  • PHP Manual
  • UConverter
  • 変換元のコンバーターの型を取得する

UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — 変換元のコンバーターの型を取得する

説明

public UConverter::getSourceType(): int|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


コンバーター名に対応する標準を取得する

  • ≪ UConverter::getSourceType
  • UConverter::getSubstChars ≫
  • PHP Manual
  • UConverter
  • コンバーター名に対応する標準を取得する

UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — コンバーター名に対応する標準を取得する

説明

public static UConverter::getStandards(): ?array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


置換文字を取得する

  • ≪ UConverter::getStandards
  • UConverter::reasonText ≫
  • PHP Manual
  • UConverter
  • 置換文字を取得する

UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — 置換文字を取得する

説明

public UConverter::getSubstChars(): string|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


コールバックの理由を表す文字列を取得する

  • ≪ UConverter::getSubstChars
  • UConverter::setDestinationEncoding ≫
  • PHP Manual
  • UConverter
  • コールバックの理由を表す文字列を取得する

UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — コールバックの理由を表す文字列を取得する

説明

public static UConverter::reasonText(int $reason): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reason

戻り値


変換先エンコーディングを設定する

  • ≪ UConverter::reasonText
  • UConverter::setSourceEncoding ≫
  • PHP Manual
  • UConverter
  • 変換先エンコーディングを設定する

UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — 変換先エンコーディングを設定する

説明

public UConverter::setDestinationEncoding(string $encoding): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

encoding

戻り値


変換元エンコーディングを設定する

  • ≪ UConverter::setDestinationEncoding
  • UConverter::setSubstChars ≫
  • PHP Manual
  • UConverter
  • 変換元エンコーディングを設定する

UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — 変換元エンコーディングを設定する

説明

public UConverter::setSourceEncoding(string $encoding): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

encoding

戻り値


置換文字を設定する

  • ≪ UConverter::setSourceEncoding
  • UConverter::toUCallback ≫
  • PHP Manual
  • UConverter
  • 置換文字を設定する

UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — 置換文字を設定する

説明

public UConverter::setSubstChars(string $chars): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

chars

戻り値


デフォルトの "to" コールバック関数

  • ≪ UConverter::setSubstChars
  • UConverter::transcode ≫
  • PHP Manual
  • UConverter
  • デフォルトの "to" コールバック関数

UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — デフォルトの "to" コールバック関数

説明

public UConverter::toUCallback(
int $reason,
string $source,
string $codeUnits,
int &$error
): string|int|array|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reason

source

codeUnits

error

戻り値


ある文字エンコーディングから別の文字エンコーディングに文字列を変換する

  • ≪ UConverter::toUCallback
  • Grapheme 関数 ≫
  • PHP Manual
  • UConverter
  • ある文字エンコーディングから別の文字エンコーディングに文字列を変換する

UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — ある文字エンコーディングから別の文字エンコーディングに文字列を変換する

説明

public static UConverter::transcode(
string $str,
string $toEncoding,
string $fromEncoding,
?array $options = null
): string|false

文字列 str の文字エンコーディングを、 fromEncoding から toEncoding に変換します。

パラメータ

str

変換する文字列。

toEncoding

変換したいエンコーディング。

fromEncoding

str の解釈に使われる文字セット。

options

オプションの配列。以下のキーが使えます:

  • 'to_subst' - toEncoding ではエンコードできない str の文字を置き換えるのに使う文字。 これを指定する場合、 変換先のエンコーディングのうちの一文字でなければいけません。

戻り値

変換後の文字列を返します。 失敗した場合に false を返します

例

例1 UTF-8 から UTF-16 に変換し、UTF-8 に戻す例

<?php
$utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoe' in UTF-8
$utf16_string = UConverter::transcode($utf8_string, 'UTF-16BE', 'UTF-8');
echo bin2hex($utf16_string), "\n";
$new_utf8_string = UConverter::transcode($utf16_string, 'UTF-8', 'UTF-16BE');
echo bin2hex($new_utf8_string), "\n";
?>

上の例の出力は以下となります。

005a006f00eb
5a6fc3ab

例2 入力に不正な文字が含まれていた場合

入力文字列に fromEncoding では不正なバイト列が含まれていた場合、 Unicode のコードポイント U+FFFD (置換文字) に置き換えられます。 この置き換えは、toEncoding に変換する前に行われます。

<?php
$invalid_utf8_string = "\xC3"; // incomplete multi-byte UTF-8 sequence
$utf16_string = UConverter::transcode($invalid_utf8_string, 'UTF-16BE', 'UTF-8');
echo bin2hex($utf16_string), "\n";
?>

上の例の出力は以下となります。

fffd

例3 エンコードできない文字

入力文字列に toEncoding で表現できない文字が含まれていた場合、 それらは一文字で置換されます。 置換に使われる文字はエンコーディングに依存しますが、 'to_subst' を使って制御できます。

<?php
$utf8_string = "\xE2\x82\xAC"; // ? (Euro Sign) does not exist in ISO 8859-1
// Default replacement in ISO 8859-1 is "\x1A" (Substitute)
$iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF-8');
echo bin2hex($iso8859_1_string), "\n";
// Specify a replacement of '?' ("\x3F") instead
$iso8859_1_string = UConverter::transcode(
$utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
);
echo bin2hex($iso8859_1_string), "\n";
// Since ISO 8859-1 cannot map U+FFFD, invalid input is also replaced by to_subst
$invalid_utf8_string = "\xC3"; // incomplete multi-byte UTF-8 sequence
$iso8859_1_string = UConverter::transcode(
$invalid_utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
);
echo bin2hex($iso8859_1_string), "\n";
?>

上の例の出力は以下となります。

1a
3f
3f

参考

  • mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


Grapheme 関数

目次

  • grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
  • grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strlen — 書記素単位で文字列の長さを取得する
  • grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_substr — 部分文字列を返す


デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

  • ≪ Grapheme 関数
  • grapheme_stripos ≫
  • PHP Manual
  • Grapheme 関数
  • デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

説明

手続き型

grapheme_extract(
string $haystack,
int $size,
int $type = GRAPHEME_EXTR_COUNT,
int $offset = 0,
int &$next = null
): string|false

デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数です。 テキストは UTF-8 でエンコードされている必要があります。

パラメータ

haystack

検索する文字列。

size

返す項目 (type に基づく) の最大数。

type

size パラメータの単位の形式を指定します。

  • GRAPHEME_EXTR_COUNT (デフォルト) - size は、 抽出するデフォルト書記素クラスタの数です。
  • GRAPHEME_EXTR_MAXBYTES - size は、返すバイト数の最大値です。
  • GRAPHEME_EXTR_MAXCHARS - size は、返す UTF-8 文字数の最大値です。

offset

haystack 内での開始位置をバイト数で指定します。 指定する場合は、0 から haystack のバイト数までの値でなければなりません。 負の値を指定すると、haystack の末尾からバイト数を数えます。 offset が指す位置が UTF-8 文字の先頭バイトでない場合は、 その次の文字の先頭から開始します。

next

次の開始位置への参照が設定されます。 この関数をコールすると、文字列の最後の部分の先頭バイトを指すことになります。

戻り値

オフセット offset から始まり、 指定した size と type を満たす、 デフォルトの書記素クラスタバウンダリで終わる文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

例

例1 grapheme_extract() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));

?>

上の例の出力は以下となります。

o%CC%88

参考

  • grapheme_substr() - 部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_extract
  • grapheme_stristr ≫
  • PHP Manual
  • Grapheme 関数
  • 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_stripos(string $haystack, string $needle, int $offset = 0): int|false

大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの offset パラメータで、haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 負の値を指定した場合は、文字列の末尾からのオフセットとみなします。 offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

戻り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_stripos() は false を返します。

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

例

例1 grapheme_stripos() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
$char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

print grapheme_stripos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

?>

上の例の出力は以下となります。

2

参考

  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

  • ≪ grapheme_stripos
  • grapheme_strlen ≫
  • PHP Manual
  • Grapheme 関数
  • 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

説明

手続き型

grapheme_stristr(string $haystack, string $needle, bool $beforeNeedle = false): string|false

大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所を含めてそれ以降の部分文字列を返します。

パラメータ

haystack

入力文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

beforeNeedle

true の場合、grapheme_stristr() は needle が最初に登場した場所より前の、 haystack の部分文字列を返します (needle は含めません)。

戻り値

haystack の部分文字列、あるいは needle が見つからなかった場合に false を返します。

例

例1 grapheme_stristr() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
$char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_O_diaeresis_nfd));

?>

上の例の出力は以下となります。

o%CC%88a%CC%8A

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


書記素単位で文字列の長さを取得する

  • ≪ grapheme_stristr
  • grapheme_strpos ≫
  • PHP Manual
  • Grapheme 関数
  • 書記素単位で文字列の長さを取得する

grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — 書記素単位で文字列の長さを取得する

説明

手続き型

grapheme_strlen(string $string): int|false|null

書記素単位 (バイト数や文字数ではありません) で文字列の長さを取得します。

パラメータ

string

長さを調べたい文字列。正しい形式の UTF-8 でなければなりません。

戻り値

成功した場合に文字列の長さを返します。 失敗した場合に false を返します

例

例1 grapheme_strlen() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

?>

上の例の出力は以下となります。

6

参考

  • » Unicode Text Segmentation: Grapheme Cluster Boundaries
  • iconv_strlen() - 文字列の文字数を返す
  • mb_strlen() - 文字列の長さを得る
  • strlen() - 文字列の長さを得る


文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_strlen
  • grapheme_strripos ≫
  • PHP Manual
  • Grapheme 関数
  • 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_strpos(string $haystack, string $needle, int $offset = 0): int|false

文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの offset パラメータで、haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。 offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

戻り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_strpos() は false を返します。

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

例

例1 grapheme_strpos() example

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

?>

上の例の出力は以下となります。

2

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_strpos
  • grapheme_strrpos ≫
  • PHP Manual
  • Grapheme 関数
  • 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_strripos(string $haystack, string $needle, int $offset = 0): int|false

大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの offset パラメータで、haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

戻り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_strripos() は false を返します。

例

例1 grapheme_strripos() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
$char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

print grapheme_strripos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

?>

上の例の出力は以下となります。

2

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

  • ≪ grapheme_strripos
  • grapheme_strstr ≫
  • PHP Manual
  • Grapheme 関数
  • 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

説明

手続き型

grapheme_strrpos(string $haystack, string $needle, int $offset = 0): int|false

文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つけます。

パラメータ

haystack

探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

offset

オプションの offset パラメータで、haystack のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 offset の値にかかわらず、返される値は常に haystack の先頭からの位置になります。

戻り値

位置を表す整数値を返します。needle が見つからない場合は grapheme_strrpos() は false を返します。

例

例1 grapheme_strrpos() example

<?php
$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strrpos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);
?>

上の例の出力は以下となります。

2

参考

  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strstr() - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

  • ≪ grapheme_strrpos
  • grapheme_substr ≫
  • PHP Manual
  • Grapheme 関数
  • haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

説明

手続き型

grapheme_strstr(string $haystack, string $needle, bool $beforeNeedle = false): string|false

haystack 文字列の中で needle が最初に登場した場所を含めてそれ以降の部分文字列を返します。

パラメータ

haystack

入力文字列。正しい形式の UTF-8 でなければなりません。

needle

探したい文字列。正しい形式の UTF-8 でなければなりません。

beforeNeedle

true の場合、grapheme_strstr() は needle が最初に登場した場所より前の haystack の部分文字列を返します (needle は含めません)。

戻り値

haystack の部分文字列、あるいは needle が見つからなかった場合に false を返します。

例

例1 grapheme_strstr() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_o_diaeresis_nfd));

?>

上の例の出力は以下となります。

o%CC%88a%CC%8A

参考

  • grapheme_stristr() - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
  • grapheme_stripos() - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strpos() - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strripos() - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • grapheme_strrpos() - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


部分文字列を返す

  • ≪ grapheme_strstr
  • IDN 関数 ≫
  • PHP Manual
  • Grapheme 関数
  • 部分文字列を返す

grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — 部分文字列を返す

説明

手続き型

grapheme_substr(string $string, int $offset, ?int $length = null): string|false

部分文字列を返します。

パラメータ

string

入力文字列。正しい形式の UTF-8 でなければなりません。

offset

デフォルトの書記素単位での開始位置。 offset がゼロ以上である場合は、string の offset 番目の位置から始まる文字列を返します。位置はゼロから数え始めます。 offset が負の場合は、文字列の末尾から数えて offset 番目 (書記素単位) の位置以降の文字列を返します。

length

長さを書記素単位で指定します。 length が正の値の場合は、offset から数えて最大 length 文字までの文字列を返します (文字列全体の長さによって変わります)。 length が負の値の場合は、文字列の末尾から多くの書記素が削除されます (offset が負の場合にはまず開始位置を算出してから行います)。 offset がこの削除された場所以降になる場合は、空文字列を返します。

戻り値

string の部分文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は、offset が文字列境界の範囲外になる場合を一貫した形で扱うようになりました。 これより前のバージョンでは、 場合によっては空文字列ではなく false を返すことがありました。

例

例1 grapheme_substr() の例

<?php

$char_a_ring_nfd = "a\xCC\x8A"; // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print urlencode(grapheme_substr( "ao" . $char_a_ring_nfd . "bc" . $char_o_diaeresis_nfd . "O", 2, -1 ));
?>

上の例の出力は以下となります。

a%CC%8Abco%CC%88

参考

  • grapheme_extract() - デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
  • » Unicode Text Segmentation: Grapheme Cluster Boundaries


IDN 関数

目次

  • idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する
  • idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する


ドメイン名をIDNAのASCII形式に変換する

  • ≪ IDN 関数
  • idn_to_utf8 ≫
  • PHP Manual
  • IDN 関数
  • ドメイン名をIDNAのASCII形式に変換する

idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する

説明

手続き型

idn_to_ascii(
string $domain,
int $flags = IDNA_DEFAULT,
int $variant = INTL_IDNA_VARIANT_UTS46,
array &$idna_info = null
): string|false

Unicode のドメイン名を、IDNAが定めたASCII形式に変換します。

パラメータ

domain

変換するドメイン名。UTF-8 にエンコードされている必要があります。

flags

変換オプション - IDNA_ ではじまる定数 (IDNA_ERROR_* 定数を除く) の組み合わせです。

variant

IDNA 2003 の場合は INTL_IDNA_VARIANT_2003 (PHP 7.2.0 以降は非推奨)、あるいは UTS #46 の場合は INTL_IDNA_VARIANT_UTS46 (ICU 4.6 以降のみ利用可能)。

idna_info

このパラメータを使うのは、variant が INTL_IDNA_VARIANT_UTS46 の場合だけです。 このとき、このパラメータには 'result'、 'isTransitionalDifferent'、そして 'errors' の三つのキーを含む配列が入ります。 'result' にはおそらく不正だと考えられる変換結果、 'isTransitionalDifferent' には UTS #46 の非移行的な機能を使って結果を変更したかどうかをあらわす boolean 値、そして 'errors' はエラー定数 IDNA_ERROR_* のビットセットを表します。

戻り値

IDNA のASCII形式でエンコードされたドメイン名。失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | variant のデフォルト値が INTL_IDNA_VARIANT_UTS46 となり、 その代わりに INTL_IDNA_VARIANT_2003 は非推奨となりました。
7.2.0 | INTL_IDNA_VARIANT_2003 は非推奨です。代わりに INTL_IDNA_VARIANT_UTS46 を使用してください。

例

例1 idn_to_ascii() の例

<?php

echo idn_to_ascii('tast.de');

?>

上の例の出力は以下となります。

xn--tst-qla.de

参考

  • idn_to_utf8() - IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する


IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

  • ≪ idn_to_ascii
  • IntlChar ≫
  • PHP Manual
  • IDN 関数
  • IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

説明

手続き型

idn_to_utf8(
string $domain,
int $flags = IDNA_DEFAULT,
int $variant = INTL_IDNA_VARIANT_UTS46,
array &$idna_info = null
): string|false

IDNAのASCII方式でエンコードされたドメイン名をUTF-8でエンコードされたUnicodeに変換します。

パラメータ

domain

IDNAのASCII方式でエンコードされた、変換対象のドメイン名

flags

変換オプション - IDNA_ ではじまる定数 (IDNA_ERROR_* 定数を除く) の組み合わせです

variant

IDNA 2003 の場合は INTL_IDNA_VARIANT_2003 (PHP 7.2.0 以降は非推奨)、あるいは UTS #46 の場合は INTL_IDNA_VARIANT_UTS46 (ICU 4.6 以降のみ利用可能)。

idna_info

このパラメータを使うのは、variant が INTL_IDNA_VARIANT_UTS46 の場合だけです。 このとき、このパラメータには 'result'、 'isTransitionalDifferent'、そして 'errors' の三つのキーを含む配列が入ります。 'result' にはおそらく不正だと考えられる変換結果、 'isTransitionalDifferent' には UTS #46 の非移行的な機能を使って結果を変更したかどうかをあらわす boolean 値、そして 'errors' はエラー定数 IDNA_ERROR_* のビットセットを表します。

戻り値

Unicodeのドメイン名。UTF-8 にエンコードされています。失敗した場合に false を返します

変更履歴

バージョン | 説明
7.4.0 | variant のデフォルト値が INTL_IDNA_VARIANT_UTS46 となり、 その代わりに INTL_IDNA_VARIANT_2003 は非推奨となりました。
7.2.0 | INTL_IDNA_VARIANT_2003 は非推奨です。代わりに INTL_IDNA_VARIANT_UTS46 を使用してください。

例

例1 idn_to_utf8() の例

<?php

echo idn_to_utf8('xn--tst-qla.de');

?>

上の例の出力は以下となります。

tast.de

参考

  • idn_to_ascii() - ドメイン名をIDNAのASCII形式に変換する


IntlChar クラス

(PHP 7, PHP 8)

はじめに

IntlChar クラスは、 Unicode 文字に関する情報にアクセスするための、 たくさんの便利メソッドを提供しています。

このクラスのメソッドと定数は、 依存している ICU ライブラリで使われている名前や振る舞いにとても近いものです。

クラス概要

class IntlChar {
/* 定数 */
public const string UNICODE_VERSION;
public const int CODEPOINT_MIN;
public const int CODEPOINT_MAX;
public const float NO_NUMERIC_VALUE;
public const int PROPERTY_ALPHABETIC;
public const int PROPERTY_BINARY_START;
public const int PROPERTY_ASCII_HEX_DIGIT;
public const int PROPERTY_BIDI_CONTROL;
public const int PROPERTY_BIDI_MIRRORED;
public const int PROPERTY_DASH;
public const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT;
public const int PROPERTY_DEPRECATED;
public const int PROPERTY_DIACRITIC;
public const int PROPERTY_EXTENDER;
public const int PROPERTY_FULL_COMPOSITION_EXCLUSION;
public const int PROPERTY_GRAPHEME_BASE;
public const int PROPERTY_GRAPHEME_EXTEND;
public const int PROPERTY_GRAPHEME_LINK;
public const int PROPERTY_HEX_DIGIT;
public const int PROPERTY_HYPHEN;
public const int PROPERTY_ID_CONTINUE;
public const int PROPERTY_ID_START;
public const int PROPERTY_IDEOGRAPHIC;
public const int PROPERTY_IDS_BINARY_OPERATOR;
public const int PROPERTY_IDS_TRINARY_OPERATOR;
public const int PROPERTY_JOIN_CONTROL;
public const int PROPERTY_LOGICAL_ORDER_EXCEPTION;
public const int PROPERTY_LOWERCASE;
public const int PROPERTY_MATH;
public const int PROPERTY_NONCHARACTER_CODE_POINT;
public const int PROPERTY_QUOTATION_MARK;
public const int PROPERTY_RADICAL;
public const int PROPERTY_SOFT_DOTTED;
public const int PROPERTY_TERMINAL_PUNCTUATION;
public const int PROPERTY_UNIFIED_IDEOGRAPH;
public const int PROPERTY_UPPERCASE;
public const int PROPERTY_WHITE_SPACE;
public const int PROPERTY_XID_CONTINUE;
public const int PROPERTY_XID_START;
public const int PROPERTY_CASE_SENSITIVE;
public const int PROPERTY_S_TERM;
public const int PROPERTY_VARIATION_SELECTOR;
public const int PROPERTY_NFD_INERT;
public const int PROPERTY_NFKD_INERT;
public const int PROPERTY_NFC_INERT;
public const int PROPERTY_NFKC_INERT;
public const int PROPERTY_SEGMENT_STARTER;
public const int PROPERTY_PATTERN_SYNTAX;
public const int PROPERTY_PATTERN_WHITE_SPACE;
public const int PROPERTY_POSIX_ALNUM;
public const int PROPERTY_POSIX_BLANK;
public const int PROPERTY_POSIX_GRAPH;
public const int PROPERTY_POSIX_PRINT;
public const int PROPERTY_POSIX_XDIGIT;
public const int PROPERTY_CASED;
public const int PROPERTY_CASE_IGNORABLE;
public const int PROPERTY_CHANGES_WHEN_LOWERCASED;
public const int PROPERTY_CHANGES_WHEN_UPPERCASED;
public const int PROPERTY_CHANGES_WHEN_TITLECASED;
public const int PROPERTY_CHANGES_WHEN_CASEFOLDED;
public const int PROPERTY_CHANGES_WHEN_CASEMAPPED;
public const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED;
public const int PROPERTY_BINARY_LIMIT;
public const int PROPERTY_BIDI_CLASS;
public const int PROPERTY_INT_START;
public const int PROPERTY_BLOCK;
public const int PROPERTY_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_DECOMPOSITION_TYPE;
public const int PROPERTY_EAST_ASIAN_WIDTH;
public const int PROPERTY_GENERAL_CATEGORY;
public const int PROPERTY_JOINING_GROUP;
public const int PROPERTY_JOINING_TYPE;
public const int PROPERTY_LINE_BREAK;
public const int PROPERTY_NUMERIC_TYPE;
public const int PROPERTY_SCRIPT;
public const int PROPERTY_HANGUL_SYLLABLE_TYPE;
public const int PROPERTY_NFD_QUICK_CHECK;
public const int PROPERTY_NFKD_QUICK_CHECK;
public const int PROPERTY_NFC_QUICK_CHECK;
public const int PROPERTY_NFKC_QUICK_CHECK;
public const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_GRAPHEME_CLUSTER_BREAK;
public const int PROPERTY_SENTENCE_BREAK;
public const int PROPERTY_WORD_BREAK;
public const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE;
public const int PROPERTY_INT_LIMIT;
public const int PROPERTY_GENERAL_CATEGORY_MASK;
public const int PROPERTY_MASK_START;
public const int PROPERTY_MASK_LIMIT;
public const int PROPERTY_NUMERIC_VALUE;
public const int PROPERTY_DOUBLE_START;
public const int PROPERTY_DOUBLE_LIMIT;
public const int PROPERTY_AGE;
public const int PROPERTY_STRING_START;
public const int PROPERTY_BIDI_MIRRORING_GLYPH;
public const int PROPERTY_CASE_FOLDING;
public const int PROPERTY_ISO_COMMENT;
public const int PROPERTY_LOWERCASE_MAPPING;
public const int PROPERTY_NAME;
public const int PROPERTY_SIMPLE_CASE_FOLDING;
public const int PROPERTY_SIMPLE_LOWERCASE_MAPPING;
public const int PROPERTY_SIMPLE_TITLECASE_MAPPING;
public const int PROPERTY_SIMPLE_UPPERCASE_MAPPING;
public const int PROPERTY_TITLECASE_MAPPING;
public const int PROPERTY_UNICODE_1_NAME;
public const int PROPERTY_UPPERCASE_MAPPING;
public const int PROPERTY_BIDI_PAIRED_BRACKET;
public const int PROPERTY_STRING_LIMIT;
public const int PROPERTY_SCRIPT_EXTENSIONS;
public const int PROPERTY_OTHER_PROPERTY_START;
public const int PROPERTY_OTHER_PROPERTY_LIMIT;
public const int PROPERTY_INVALID_CODE;
public const int CHAR_CATEGORY_UNASSIGNED;
public const int CHAR_CATEGORY_GENERAL_OTHER_TYPES;
public const int CHAR_CATEGORY_UPPERCASE_LETTER;
public const int CHAR_CATEGORY_LOWERCASE_LETTER;
public const int CHAR_CATEGORY_TITLECASE_LETTER;
public const int CHAR_CATEGORY_MODIFIER_LETTER;
public const int CHAR_CATEGORY_OTHER_LETTER;
public const int CHAR_CATEGORY_NON_SPACING_MARK;
public const int CHAR_CATEGORY_ENCLOSING_MARK;
public const int CHAR_CATEGORY_COMBINING_SPACING_MARK;
public const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER;
public const int CHAR_CATEGORY_LETTER_NUMBER;
public const int CHAR_CATEGORY_OTHER_NUMBER;
public const int CHAR_CATEGORY_SPACE_SEPARATOR;
public const int CHAR_CATEGORY_LINE_SEPARATOR;
public const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR;
public const int CHAR_CATEGORY_CONTROL_CHAR;
public const int CHAR_CATEGORY_FORMAT_CHAR;
public const int CHAR_CATEGORY_PRIVATE_USE_CHAR;
public const int CHAR_CATEGORY_SURROGATE;
public const int CHAR_CATEGORY_DASH_PUNCTUATION;
public const int CHAR_CATEGORY_START_PUNCTUATION;
public const int CHAR_CATEGORY_END_PUNCTUATION;
public const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION;
public const int CHAR_CATEGORY_OTHER_PUNCTUATION;
public const int CHAR_CATEGORY_MATH_SYMBOL;
public const int CHAR_CATEGORY_CURRENCY_SYMBOL;
public const int CHAR_CATEGORY_MODIFIER_SYMBOL;
public const int CHAR_CATEGORY_OTHER_SYMBOL;
public const int CHAR_CATEGORY_INITIAL_PUNCTUATION;
public const int CHAR_CATEGORY_FINAL_PUNCTUATION;
public const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR;
public const int CHAR_DIRECTION_ARABIC_NUMBER;
public const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_BLOCK_SEPARATOR;
public const int CHAR_DIRECTION_SEGMENT_SEPARATOR;
public const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL;
public const int CHAR_DIRECTION_OTHER_NEUTRAL;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT;
public const int CHAR_DIRECTION_DIR_NON_SPACING_MARK;
public const int CHAR_DIRECTION_BOUNDARY_NEUTRAL;
public const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE;
public const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT;
public const int BLOCK_CODE_NO_BLOCK;
public const int BLOCK_CODE_BASIC_LATIN;
public const int BLOCK_CODE_LATIN_1_SUPPLEMENT;
public const int BLOCK_CODE_LATIN_EXTENDED_A;
public const int BLOCK_CODE_LATIN_EXTENDED_B;
public const int BLOCK_CODE_IPA_EXTENSIONS;
public const int BLOCK_CODE_SPACING_MODIFIER_LETTERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS;
public const int BLOCK_CODE_GREEK;
public const int BLOCK_CODE_CYRILLIC;
public const int BLOCK_CODE_ARMENIAN;
public const int BLOCK_CODE_HEBREW;
public const int BLOCK_CODE_ARABIC;
public const int BLOCK_CODE_SYRIAC;
public const int BLOCK_CODE_THAANA;
public const int BLOCK_CODE_DEVANAGARI;
public const int BLOCK_CODE_BENGALI;
public const int BLOCK_CODE_GURMUKHI;
public const int BLOCK_CODE_GUJARATI;
public const int BLOCK_CODE_ORIYA;
public const int BLOCK_CODE_TAMIL;
public const int BLOCK_CODE_TELUGU;
public const int BLOCK_CODE_KANNADA;
public const int BLOCK_CODE_MALAYALAM;
public const int BLOCK_CODE_SINHALA;
public const int BLOCK_CODE_THAI;
public const int BLOCK_CODE_LAO;
public const int BLOCK_CODE_TIBETAN;
public const int BLOCK_CODE_MYANMAR;
public const int BLOCK_CODE_GEORGIAN;
public const int BLOCK_CODE_HANGUL_JAMO;
public const int BLOCK_CODE_ETHIOPIC;
public const int BLOCK_CODE_CHEROKEE;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS;
public const int BLOCK_CODE_OGHAM;
public const int BLOCK_CODE_RUNIC;
public const int BLOCK_CODE_KHMER;
public const int BLOCK_CODE_MONGOLIAN;
public const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL;
public const int BLOCK_CODE_GREEK_EXTENDED;
public const int BLOCK_CODE_GENERAL_PUNCTUATION;
public const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS;
public const int BLOCK_CODE_CURRENCY_SYMBOLS;
public const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS;
public const int BLOCK_CODE_LETTERLIKE_SYMBOLS;
public const int BLOCK_CODE_NUMBER_FORMS;
public const int BLOCK_CODE_ARROWS;
public const int BLOCK_CODE_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL;
public const int BLOCK_CODE_CONTROL_PICTURES;
public const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS;
public const int BLOCK_CODE_BOX_DRAWING;
public const int BLOCK_CODE_BLOCK_ELEMENTS;
public const int BLOCK_CODE_GEOMETRIC_SHAPES;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS;
public const int BLOCK_CODE_DINGBATS;
public const int BLOCK_CODE_BRAILLE_PATTERNS;
public const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT;
public const int BLOCK_CODE_KANGXI_RADICALS;
public const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS;
public const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION;
public const int BLOCK_CODE_HIRAGANA;
public const int BLOCK_CODE_KATAKANA;
public const int BLOCK_CODE_BOPOMOFO;
public const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO;
public const int BLOCK_CODE_KANBUN;
public const int BLOCK_CODE_BOPOMOFO_EXTENDED;
public const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS;
public const int BLOCK_CODE_CJK_COMPATIBILITY;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS;
public const int BLOCK_CODE_YI_SYLLABLES;
public const int BLOCK_CODE_YI_RADICALS;
public const int BLOCK_CODE_HANGUL_SYLLABLES;
public const int BLOCK_CODE_HIGH_SURROGATES;
public const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES;
public const int BLOCK_CODE_LOW_SURROGATES;
public const int BLOCK_CODE_PRIVATE_USE_AREA;
public const int BLOCK_CODE_PRIVATE_USE;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS;
public const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A;
public const int BLOCK_CODE_COMBINING_HALF_MARKS;
public const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS;
public const int BLOCK_CODE_SMALL_FORM_VARIANTS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B;
public const int BLOCK_CODE_SPECIALS;
public const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS;
public const int BLOCK_CODE_OLD_ITALIC;
public const int BLOCK_CODE_GOTHIC;
public const int BLOCK_CODE_DESERET;
public const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT;
public const int BLOCK_CODE_TAGS;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENT;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY;
public const int BLOCK_CODE_TAGALOG;
public const int BLOCK_CODE_HANUNOO;
public const int BLOCK_CODE_BUHID;
public const int BLOCK_CODE_TAGBANWA;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B;
public const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_VARIATION_SELECTORS;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B;
public const int BLOCK_CODE_LIMBU;
public const int BLOCK_CODE_TAI_LE;
public const int BLOCK_CODE_KHMER_SYMBOLS;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS;
public const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS;
public const int BLOCK_CODE_LINEAR_B_SYLLABARY;
public const int BLOCK_CODE_LINEAR_B_IDEOGRAMS;
public const int BLOCK_CODE_AEGEAN_NUMBERS;
public const int BLOCK_CODE_UGARITIC;
public const int BLOCK_CODE_SHAVIAN;
public const int BLOCK_CODE_OSMANYA;
public const int BLOCK_CODE_CYPRIOT_SYLLABARY;
public const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS;
public const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT;
public const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION;
public const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS;
public const int BLOCK_CODE_ARABIC_SUPPLEMENT;
public const int BLOCK_CODE_BUGINESE;
public const int BLOCK_CODE_CJK_STROKES;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT;
public const int BLOCK_CODE_COPTIC;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED;
public const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT;
public const int BLOCK_CODE_GEORGIAN_SUPPLEMENT;
public const int BLOCK_CODE_GLAGOLITIC;
public const int BLOCK_CODE_KHAROSHTHI;
public const int BLOCK_CODE_MODIFIER_TONE_LETTERS;
public const int BLOCK_CODE_NEW_TAI_LUE;
public const int BLOCK_CODE_OLD_PERSIAN;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT;
public const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION;
public const int BLOCK_CODE_SYLOTI_NAGRI;
public const int BLOCK_CODE_TIFINAGH;
public const int BLOCK_CODE_VERTICAL_FORMS;
public const int BLOCK_CODE_NKO;
public const int BLOCK_CODE_BALINESE;
public const int BLOCK_CODE_LATIN_EXTENDED_C;
public const int BLOCK_CODE_LATIN_EXTENDED_D;
public const int BLOCK_CODE_PHAGS_PA;
public const int BLOCK_CODE_PHOENICIAN;
public const int BLOCK_CODE_CUNEIFORM;
public const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION;
public const int BLOCK_CODE_COUNTING_ROD_NUMERALS;
public const int BLOCK_CODE_SUNDANESE;
public const int BLOCK_CODE_LEPCHA;
public const int BLOCK_CODE_OL_CHIKI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_A;
public const int BLOCK_CODE_VAI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_B;
public const int BLOCK_CODE_SAURASHTRA;
public const int BLOCK_CODE_KAYAH_LI;
public const int BLOCK_CODE_REJANG;
public const int BLOCK_CODE_CHAM;
public const int BLOCK_CODE_ANCIENT_SYMBOLS;
public const int BLOCK_CODE_PHAISTOS_DISC;
public const int BLOCK_CODE_LYCIAN;
public const int BLOCK_CODE_CARIAN;
public const int BLOCK_CODE_LYDIAN;
public const int BLOCK_CODE_MAHJONG_TILES;
public const int BLOCK_CODE_DOMINO_TILES;
public const int BLOCK_CODE_SAMARITAN;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED;
public const int BLOCK_CODE_TAI_THAM;
public const int BLOCK_CODE_VEDIC_EXTENSIONS;
public const int BLOCK_CODE_LISU;
public const int BLOCK_CODE_BAMUM;
public const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS;
public const int BLOCK_CODE_DEVANAGARI_EXTENDED;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A;
public const int BLOCK_CODE_JAVANESE;
public const int BLOCK_CODE_MYANMAR_EXTENDED_A;
public const int BLOCK_CODE_TAI_VIET;
public const int BLOCK_CODE_MEETEI_MAYEK;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B;
public const int BLOCK_CODE_IMPERIAL_ARAMAIC;
public const int BLOCK_CODE_OLD_SOUTH_ARABIAN;
public const int BLOCK_CODE_AVESTAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI;
public const int BLOCK_CODE_OLD_TURKIC;
public const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS;
public const int BLOCK_CODE_KAITHI;
public const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT;
public const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C;
public const int BLOCK_CODE_MANDAIC;
public const int BLOCK_CODE_BATAK;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED_A;
public const int BLOCK_CODE_BRAHMI;
public const int BLOCK_CODE_BAMUM_SUPPLEMENT;
public const int BLOCK_CODE_KANA_SUPPLEMENT;
public const int BLOCK_CODE_PLAYING_CARDS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS;
public const int BLOCK_CODE_EMOTICONS;
public const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS;
public const int BLOCK_CODE_ALCHEMICAL_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D;
public const int BLOCK_CODE_ARABIC_EXTENDED_A;
public const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS;
public const int BLOCK_CODE_CHAKMA;
public const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS;
public const int BLOCK_CODE_MEROITIC_CURSIVE;
public const int BLOCK_CODE_MEROITIC_HIEROGLYPHS;
public const int BLOCK_CODE_MIAO;
public const int BLOCK_CODE_SHARADA;
public const int BLOCK_CODE_SORA_SOMPENG;
public const int BLOCK_CODE_SUNDANESE_SUPPLEMENT;
public const int BLOCK_CODE_TAKRI;
public const int BLOCK_CODE_BASSA_VAH;
public const int BLOCK_CODE_CAUCASIAN_ALBANIAN;
public const int BLOCK_CODE_COPTIC_EPACT_NUMBERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED;
public const int BLOCK_CODE_DUPLOYAN;
public const int BLOCK_CODE_ELBASAN;
public const int BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED;
public const int BLOCK_CODE_GRANTHA;
public const int BLOCK_CODE_KHOJKI;
public const int BLOCK_CODE_KHUDAWADI;
public const int BLOCK_CODE_LATIN_EXTENDED_E;
public const int BLOCK_CODE_LINEAR_A;
public const int BLOCK_CODE_MAHAJANI;
public const int BLOCK_CODE_MANICHAEAN;
public const int BLOCK_CODE_MENDE_KIKAKUI;
public const int BLOCK_CODE_MODI;
public const int BLOCK_CODE_MRO;
public const int BLOCK_CODE_MYANMAR_EXTENDED_B;
public const int BLOCK_CODE_NABATAEAN;
public const int BLOCK_CODE_OLD_NORTH_ARABIAN;
public const int BLOCK_CODE_OLD_PERMIC;
public const int BLOCK_CODE_ORNAMENTAL_DINGBATS;
public const int BLOCK_CODE_PAHAWH_HMONG;
public const int BLOCK_CODE_PALMYRENE;
public const int BLOCK_CODE_PAU_CIN_HAU;
public const int BLOCK_CODE_PSALTER_PAHLAVI;
public const int BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS;
public const int BLOCK_CODE_SIDDHAM;
public const int BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_C;
public const int BLOCK_CODE_TIRHUTA;
public const int BLOCK_CODE_WARANG_CITI;
public const int BLOCK_CODE_COUNT;
public const int BLOCK_CODE_INVALID_CODE;
public const int BPT_NONE;
public const int BPT_OPEN;
public const int BPT_CLOSE;
public const int BPT_COUNT;
public const int EA_NEUTRAL;
public const int EA_AMBIGUOUS;
public const int EA_HALFWIDTH;
public const int EA_FULLWIDTH;
public const int EA_NARROW;
public const int EA_WIDE;
public const int EA_COUNT;
public const int UNICODE_CHAR_NAME;
public const int UNICODE_10_CHAR_NAME;
public const int EXTENDED_CHAR_NAME;
public const int CHAR_NAME_ALIAS;
public const int CHAR_NAME_CHOICE_COUNT;
public const int SHORT_PROPERTY_NAME;
public const int LONG_PROPERTY_NAME;
public const int PROPERTY_NAME_CHOICE_COUNT;
public const int DT_NONE;
public const int DT_CANONICAL;
public const int DT_COMPAT;
public const int DT_CIRCLE;
public const int DT_FINAL;
public const int DT_FONT;
public const int DT_FRACTION;
public const int DT_INITIAL;
public const int DT_ISOLATED;
public const int DT_MEDIAL;
public const int DT_NARROW;
public const int DT_NOBREAK;
public const int DT_SMALL;
public const int DT_SQUARE;
public const int DT_SUB;
public const int DT_SUPER;
public const int DT_VERTICAL;
public const int DT_WIDE;
public const int DT_COUNT;
public const int JT_NON_JOINING;
public const int JT_JOIN_CAUSING;
public const int JT_DUAL_JOINING;
public const int JT_LEFT_JOINING;
public const int JT_RIGHT_JOINING;
public const int JT_TRANSPARENT;
public const int JT_COUNT;
public const int JG_NO_JOINING_GROUP;
public const int JG_AIN;
public const int JG_ALAPH;
public const int JG_ALEF;
public const int JG_BEH;
public const int JG_BETH;
public const int JG_DAL;
public const int JG_DALATH_RISH;
public const int JG_E;
public const int JG_FEH;
public const int JG_FINAL_SEMKATH;
public const int JG_GAF;
public const int JG_GAMAL;
public const int JG_HAH;
public const int JG_TEH_MARBUTA_GOAL;
public const int JG_HAMZA_ON_HEH_GOAL;
public const int JG_HE;
public const int JG_HEH;
public const int JG_HEH_GOAL;
public const int JG_HETH;
public const int JG_KAF;
public const int JG_KAPH;
public const int JG_KNOTTED_HEH;
public const int JG_LAM;
public const int JG_LAMADH;
public const int JG_MEEM;
public const int JG_MIM;
public const int JG_NOON;
public const int JG_NUN;
public const int JG_PE;
public const int JG_QAF;
public const int JG_QAPH;
public const int JG_REH;
public const int JG_REVERSED_PE;
public const int JG_SAD;
public const int JG_SADHE;
public const int JG_SEEN;
public const int JG_SEMKATH;
public const int JG_SHIN;
public const int JG_SWASH_KAF;
public const int JG_SYRIAC_WAW;
public const int JG_TAH;
public const int JG_TAW;
public const int JG_TEH_MARBUTA;
public const int JG_TETH;
public const int JG_WAW;
public const int JG_YEH;
public const int JG_YEH_BARREE;
public const int JG_YEH_WITH_TAIL;
public const int JG_YUDH;
public const int JG_YUDH_HE;
public const int JG_ZAIN;
public const int JG_FE;
public const int JG_KHAPH;
public const int JG_ZHAIN;
public const int JG_BURUSHASKI_YEH_BARREE;
public const int JG_FARSI_YEH;
public const int JG_NYA;
public const int JG_ROHINGYA_YEH;
public const int JG_MANICHAEAN_ALEPH;
public const int JG_MANICHAEAN_AYIN;
public const int JG_MANICHAEAN_BETH;
public const int JG_MANICHAEAN_DALETH;
public const int JG_MANICHAEAN_DHAMEDH;
public const int JG_MANICHAEAN_FIVE;
public const int JG_MANICHAEAN_GIMEL;
public const int JG_MANICHAEAN_HETH;
public const int JG_MANICHAEAN_HUNDRED;
public const int JG_MANICHAEAN_KAPH;
public const int JG_MANICHAEAN_LAMEDH;
public const int JG_MANICHAEAN_MEM;
public const int JG_MANICHAEAN_NUN;
public const int JG_MANICHAEAN_ONE;
public const int JG_MANICHAEAN_PE;
public const int JG_MANICHAEAN_QOPH;
public const int JG_MANICHAEAN_RESH;
public const int JG_MANICHAEAN_SADHE;
public const int JG_MANICHAEAN_SAMEKH;
public const int JG_MANICHAEAN_TAW;
public const int JG_MANICHAEAN_TEN;
public const int JG_MANICHAEAN_TETH;
public const int JG_MANICHAEAN_THAMEDH;
public const int JG_MANICHAEAN_TWENTY;
public const int JG_MANICHAEAN_WAW;
public const int JG_MANICHAEAN_YODH;
public const int JG_MANICHAEAN_ZAYIN;
public const int JG_STRAIGHT_WAW;
public const int JG_COUNT;
public const int GCB_OTHER;
public const int GCB_CONTROL;
public const int GCB_CR;
public const int GCB_EXTEND;
public const int GCB_L;
public const int GCB_LF;
public const int GCB_LV;
public const int GCB_LVT;
public const int GCB_T;
public const int GCB_V;
public const int GCB_SPACING_MARK;
public const int GCB_PREPEND;
public const int GCB_REGIONAL_INDICATOR;
public const int GCB_COUNT;
public const int WB_OTHER;
public const int WB_ALETTER;
public const int WB_FORMAT;
public const int WB_KATAKANA;
public const int WB_MIDLETTER;
public const int WB_MIDNUM;
public const int WB_NUMERIC;
public const int WB_EXTENDNUMLET;
public const int WB_CR;
public const int WB_EXTEND;
public const int WB_LF;
public const int WB_MIDNUMLET;
public const int WB_NEWLINE;
public const int WB_REGIONAL_INDICATOR;
public const int WB_HEBREW_LETTER;
public const int WB_SINGLE_QUOTE;
public const int WB_DOUBLE_QUOTE;
public const int WB_COUNT;
public const int SB_OTHER;
public const int SB_ATERM;
public const int SB_CLOSE;
public const int SB_FORMAT;
public const int SB_LOWER;
public const int SB_NUMERIC;
public const int SB_OLETTER;
public const int SB_SEP;
public const int SB_SP;
public const int SB_STERM;
public const int SB_UPPER;
public const int SB_CR;
public const int SB_EXTEND;
public const int SB_LF;
public const int SB_SCONTINUE;
public const int SB_COUNT;
public const int LB_UNKNOWN;
public const int LB_AMBIGUOUS;
public const int LB_ALPHABETIC;
public const int LB_BREAK_BOTH;
public const int LB_BREAK_AFTER;
public const int LB_BREAK_BEFORE;
public const int LB_MANDATORY_BREAK;
public const int LB_CONTINGENT_BREAK;
public const int LB_CLOSE_PUNCTUATION;
public const int LB_COMBINING_MARK;
public const int LB_CARRIAGE_RETURN;
public const int LB_EXCLAMATION;
public const int LB_GLUE;
public const int LB_HYPHEN;
public const int LB_IDEOGRAPHIC;
public const int LB_INSEPARABLE;
public const int LB_INSEPERABLE;
public const int LB_INFIX_NUMERIC;
public const int LB_LINE_FEED;
public const int LB_NONSTARTER;
public const int LB_NUMERIC;
public const int LB_OPEN_PUNCTUATION;
public const int LB_POSTFIX_NUMERIC;
public const int LB_PREFIX_NUMERIC;
public const int LB_QUOTATION;
public const int LB_COMPLEX_CONTEXT;
public const int LB_SURROGATE;
public const int LB_SPACE;
public const int LB_BREAK_SYMBOLS;
public const int LB_ZWSPACE;
public const int LB_NEXT_LINE;
public const int LB_WORD_JOINER;
public const int LB_H2;
public const int LB_H3;
public const int LB_JL;
public const int LB_JT;
public const int LB_JV;
public const int LB_CLOSE_PARENTHESIS;
public const int LB_CONDITIONAL_JAPANESE_STARTER;
public const int LB_HEBREW_LETTER;
public const int LB_REGIONAL_INDICATOR;
public const int LB_COUNT;
public const int NT_NONE;
public const int NT_DECIMAL;
public const int NT_DIGIT;
public const int NT_NUMERIC;
public const int NT_COUNT;
public const int HST_NOT_APPLICABLE;
public const int HST_LEADING_JAMO;
public const int HST_VOWEL_JAMO;
public const int HST_TRAILING_JAMO;
public const int HST_LV_SYLLABLE;
public const int HST_LVT_SYLLABLE;
public const int HST_COUNT;
public const int FOLD_CASE_DEFAULT;
public const int FOLD_CASE_EXCLUDE_SPECIAL_I;
/* メソッド */
public static charAge(int|string $codepoint): ?array
public static charDigitValue(int|string $codepoint): ?int
public static charDirection(int|string $codepoint): ?int
public static charFromName(string $name, int $type = IntlChar::UNICODE_CHAR_NAME): ?int
public static charMirror(int|string $codepoint): int|string|null
public static charName(int|string $codepoint, int $type = IntlChar::UNICODE_CHAR_NAME): ?string
public static charType(int|string $codepoint): ?int
public static chr(int|string $codepoint): ?string
public static digit(int|string $codepoint, int $base = 10): int|false|null
public static enumCharNames(
int|string $start,
int|string $end,
callable $callback,
int $type = IntlChar::UNICODE_CHAR_NAME
): bool
public static enumCharTypes(callable $callback): void
public static foldCase(int|string $codepoint, int $options = IntlChar::FOLD_CASE_DEFAULT): int|string|null
public static forDigit(int $digit, int $base = 10): int
public static getBidiPairedBracket(int|string $codepoint): int|string|null
public static getBlockCode(int|string $codepoint): ?int
public static getCombiningClass(int|string $codepoint): ?int
public static getFC_NFKC_Closure(int|string $codepoint): string|false|null
public static getIntPropertyMaxValue(int $property): int
public static getIntPropertyMinValue(int $property): int
public static getIntPropertyValue(int|string $codepoint, int $property): ?int
public static getNumericValue(int|string $codepoint): ?float
public static getPropertyEnum(string $alias): int
public static getPropertyName(int $property, int $type = IntlChar::LONG_PROPERTY_NAME): string|false
public static getPropertyValueEnum(int $property, string $name): int
public static getPropertyValueName(int $property, int $value, int $type = IntlChar::LONG_PROPERTY_NAME): string|false
public static getUnicodeVersion(): array
public static hasBinaryProperty(int|string $codepoint, int $property): ?bool
public static isalnum(int|string $codepoint): ?bool
public static isalpha(int|string $codepoint): ?bool
public static isbase(int|string $codepoint): ?bool
public static isblank(int|string $codepoint): ?bool
public static iscntrl(int|string $codepoint): ?bool
public static isdefined(int|string $codepoint): ?bool
public static isdigit(int|string $codepoint): ?bool
public static isgraph(int|string $codepoint): ?bool
public static isIDIgnorable(int|string $codepoint): ?bool
public static isIDPart(int|string $codepoint): ?bool
public static isIDStart(int|string $codepoint): ?bool
public static isISOControl(int|string $codepoint): ?bool
public static isJavaIDPart(int|string $codepoint): ?bool
public static isJavaIDStart(int|string $codepoint): ?bool
public static isJavaSpaceChar(int|string $codepoint): ?bool
public static islower(int|string $codepoint): ?bool
public static isMirrored(int|string $codepoint): ?bool
public static isprint(int|string $codepoint): ?bool
public static ispunct(int|string $codepoint): ?bool
public static isspace(int|string $codepoint): ?bool
public static istitle(int|string $codepoint): ?bool
public static isUAlphabetic(int|string $codepoint): ?bool
public static isULowercase(int|string $codepoint): ?bool
public static isupper(int|string $codepoint): ?bool
public static isUUppercase(int|string $codepoint): ?bool
public static isUWhiteSpace(int|string $codepoint): ?bool
public static isWhitespace(int|string $codepoint): ?bool
public static isxdigit(int|string $codepoint): ?bool
public static ord(int|string $character): ?int
public static tolower(int|string $codepoint): int|string|null
public static totitle(int|string $codepoint): int|string|null
public static toupper(int|string $codepoint): int|string|null
}

定義済み定数

IntlChar::UNICODE_VERSION

IntlChar::CODEPOINT_MIN

IntlChar::CODEPOINT_MAX

IntlChar::NO_NUMERIC_VALUE

Special value that is returned by IntlChar::getNumericValue() when no numeric value is defined for a code point.

IntlChar::PROPERTY_ALPHABETIC

IntlChar::PROPERTY_BINARY_START

IntlChar::PROPERTY_ASCII_HEX_DIGIT

IntlChar::PROPERTY_BIDI_CONTROL

IntlChar::PROPERTY_BIDI_MIRRORED

IntlChar::PROPERTY_DASH

IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT

IntlChar::PROPERTY_DEPRECATED

IntlChar::PROPERTY_DIACRITIC

IntlChar::PROPERTY_EXTENDER

IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION

IntlChar::PROPERTY_GRAPHEME_BASE

IntlChar::PROPERTY_GRAPHEME_EXTEND

IntlChar::PROPERTY_GRAPHEME_LINK

IntlChar::PROPERTY_HEX_DIGIT

IntlChar::PROPERTY_HYPHEN

IntlChar::PROPERTY_ID_CONTINUE

IntlChar::PROPERTY_ID_START

IntlChar::PROPERTY_IDEOGRAPHIC

IntlChar::PROPERTY_IDS_BINARY_OPERATOR

IntlChar::PROPERTY_IDS_TRINARY_OPERATOR

IntlChar::PROPERTY_JOIN_CONTROL

IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION

IntlChar::PROPERTY_LOWERCASE

IntlChar::PROPERTY_MATH

IntlChar::PROPERTY_NONCHARACTER_CODE_POINT

IntlChar::PROPERTY_QUOTATION_MARK

IntlChar::PROPERTY_RADICAL

IntlChar::PROPERTY_SOFT_DOTTED

IntlChar::PROPERTY_TERMINAL_PUNCTUATION

IntlChar::PROPERTY_UNIFIED_IDEOGRAPH

IntlChar::PROPERTY_UPPERCASE

IntlChar::PROPERTY_WHITE_SPACE

IntlChar::PROPERTY_XID_CONTINUE

IntlChar::PROPERTY_XID_START

IntlChar::PROPERTY_CASE_SENSITIVE

IntlChar::PROPERTY_S_TERM

IntlChar::PROPERTY_VARIATION_SELECTOR

IntlChar::PROPERTY_NFD_INERT

IntlChar::PROPERTY_NFKD_INERT

IntlChar::PROPERTY_NFC_INERT

IntlChar::PROPERTY_NFKC_INERT

IntlChar::PROPERTY_SEGMENT_STARTER

IntlChar::PROPERTY_PATTERN_SYNTAX

IntlChar::PROPERTY_PATTERN_WHITE_SPACE

IntlChar::PROPERTY_POSIX_ALNUM

IntlChar::PROPERTY_POSIX_BLANK

IntlChar::PROPERTY_POSIX_GRAPH

IntlChar::PROPERTY_POSIX_PRINT

IntlChar::PROPERTY_POSIX_XDIGIT

IntlChar::PROPERTY_CASED

IntlChar::PROPERTY_CASE_IGNORABLE

IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED

IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED

IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED

IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED

IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED

IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED

IntlChar::PROPERTY_BINARY_LIMIT

IntlChar::PROPERTY_BIDI_CLASS

IntlChar::PROPERTY_INT_START

IntlChar::PROPERTY_BLOCK

IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS

IntlChar::PROPERTY_DECOMPOSITION_TYPE

IntlChar::PROPERTY_EAST_ASIAN_WIDTH

IntlChar::PROPERTY_GENERAL_CATEGORY

IntlChar::PROPERTY_JOINING_GROUP

IntlChar::PROPERTY_JOINING_TYPE

IntlChar::PROPERTY_LINE_BREAK

IntlChar::PROPERTY_NUMERIC_TYPE

IntlChar::PROPERTY_SCRIPT

IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE

IntlChar::PROPERTY_NFD_QUICK_CHECK

IntlChar::PROPERTY_NFKD_QUICK_CHECK

IntlChar::PROPERTY_NFC_QUICK_CHECK

IntlChar::PROPERTY_NFKC_QUICK_CHECK

IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS

IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS

IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK

IntlChar::PROPERTY_SENTENCE_BREAK

IntlChar::PROPERTY_WORD_BREAK

IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE

IntlChar::PROPERTY_INT_LIMIT

IntlChar::PROPERTY_GENERAL_CATEGORY_MASK

IntlChar::PROPERTY_MASK_START

IntlChar::PROPERTY_MASK_LIMIT

IntlChar::PROPERTY_NUMERIC_VALUE

IntlChar::PROPERTY_DOUBLE_START

IntlChar::PROPERTY_DOUBLE_LIMIT

IntlChar::PROPERTY_AGE

IntlChar::PROPERTY_STRING_START

IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH

IntlChar::PROPERTY_CASE_FOLDING

IntlChar::PROPERTY_ISO_COMMENT

IntlChar::PROPERTY_LOWERCASE_MAPPING

IntlChar::PROPERTY_NAME

IntlChar::PROPERTY_SIMPLE_CASE_FOLDING

IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING

IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING

IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING

IntlChar::PROPERTY_TITLECASE_MAPPING

IntlChar::PROPERTY_UNICODE_1_NAME

IntlChar::PROPERTY_UPPERCASE_MAPPING

IntlChar::PROPERTY_BIDI_PAIRED_BRACKET

IntlChar::PROPERTY_STRING_LIMIT

IntlChar::PROPERTY_SCRIPT_EXTENSIONS

IntlChar::PROPERTY_OTHER_PROPERTY_START

IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT

IntlChar::PROPERTY_INVALID_CODE

IntlChar::CHAR_CATEGORY_UNASSIGNED

IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES

IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER

IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER

IntlChar::CHAR_CATEGORY_TITLECASE_LETTER

IntlChar::CHAR_CATEGORY_MODIFIER_LETTER

IntlChar::CHAR_CATEGORY_OTHER_LETTER

IntlChar::CHAR_CATEGORY_NON_SPACING_MARK

IntlChar::CHAR_CATEGORY_ENCLOSING_MARK

IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK

IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER

IntlChar::CHAR_CATEGORY_LETTER_NUMBER

IntlChar::CHAR_CATEGORY_OTHER_NUMBER

IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR

IntlChar::CHAR_CATEGORY_LINE_SEPARATOR

IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR

IntlChar::CHAR_CATEGORY_CONTROL_CHAR

IntlChar::CHAR_CATEGORY_FORMAT_CHAR

IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR

IntlChar::CHAR_CATEGORY_SURROGATE

IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION

IntlChar::CHAR_CATEGORY_START_PUNCTUATION

IntlChar::CHAR_CATEGORY_END_PUNCTUATION

IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION

IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION

IntlChar::CHAR_CATEGORY_MATH_SYMBOL

IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL

IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL

IntlChar::CHAR_CATEGORY_OTHER_SYMBOL

IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION

IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION

IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT

IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER

IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR

IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR

IntlChar::CHAR_DIRECTION_ARABIC_NUMBER

IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR

IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR

IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR

IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL

IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE

IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT

IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK

IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL

IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE

IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE

IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE

IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE

IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT

IntlChar::BLOCK_CODE_NO_BLOCK

IntlChar::BLOCK_CODE_BASIC_LATIN

IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT

IntlChar::BLOCK_CODE_LATIN_EXTENDED_A

IntlChar::BLOCK_CODE_LATIN_EXTENDED_B

IntlChar::BLOCK_CODE_IPA_EXTENSIONS

IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS

IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS

IntlChar::BLOCK_CODE_GREEK

IntlChar::BLOCK_CODE_CYRILLIC

IntlChar::BLOCK_CODE_ARMENIAN

IntlChar::BLOCK_CODE_HEBREW

IntlChar::BLOCK_CODE_ARABIC

IntlChar::BLOCK_CODE_SYRIAC

IntlChar::BLOCK_CODE_THAANA

IntlChar::BLOCK_CODE_DEVANAGARI

IntlChar::BLOCK_CODE_BENGALI

IntlChar::BLOCK_CODE_GURMUKHI

IntlChar::BLOCK_CODE_GUJARATI

IntlChar::BLOCK_CODE_ORIYA

IntlChar::BLOCK_CODE_TAMIL

IntlChar::BLOCK_CODE_TELUGU

IntlChar::BLOCK_CODE_KANNADA

IntlChar::BLOCK_CODE_MALAYALAM

IntlChar::BLOCK_CODE_SINHALA

IntlChar::BLOCK_CODE_THAI

IntlChar::BLOCK_CODE_LAO

IntlChar::BLOCK_CODE_TIBETAN

IntlChar::BLOCK_CODE_MYANMAR

IntlChar::BLOCK_CODE_GEORGIAN

IntlChar::BLOCK_CODE_HANGUL_JAMO

IntlChar::BLOCK_CODE_ETHIOPIC

IntlChar::BLOCK_CODE_CHEROKEE

IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS

IntlChar::BLOCK_CODE_OGHAM

IntlChar::BLOCK_CODE_RUNIC

IntlChar::BLOCK_CODE_KHMER

IntlChar::BLOCK_CODE_MONGOLIAN

IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL

IntlChar::BLOCK_CODE_GREEK_EXTENDED

IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION

IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS

IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS

IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS

IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS

IntlChar::BLOCK_CODE_NUMBER_FORMS

IntlChar::BLOCK_CODE_ARROWS

IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS

IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL

IntlChar::BLOCK_CODE_CONTROL_PICTURES

IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION

IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS

IntlChar::BLOCK_CODE_BOX_DRAWING

IntlChar::BLOCK_CODE_BLOCK_ELEMENTS

IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES

IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS

IntlChar::BLOCK_CODE_DINGBATS

IntlChar::BLOCK_CODE_BRAILLE_PATTERNS

IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT

IntlChar::BLOCK_CODE_KANGXI_RADICALS

IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS

IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION

IntlChar::BLOCK_CODE_HIRAGANA

IntlChar::BLOCK_CODE_KATAKANA

IntlChar::BLOCK_CODE_BOPOMOFO

IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO

IntlChar::BLOCK_CODE_KANBUN

IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED

IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS

IntlChar::BLOCK_CODE_YI_SYLLABLES

IntlChar::BLOCK_CODE_YI_RADICALS

IntlChar::BLOCK_CODE_HANGUL_SYLLABLES

IntlChar::BLOCK_CODE_HIGH_SURROGATES

IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES

IntlChar::BLOCK_CODE_LOW_SURROGATES

IntlChar::BLOCK_CODE_PRIVATE_USE_AREA

IntlChar::BLOCK_CODE_PRIVATE_USE

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS

IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS

IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A

IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS

IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS

IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B

IntlChar::BLOCK_CODE_SPECIALS

IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS

IntlChar::BLOCK_CODE_OLD_ITALIC

IntlChar::BLOCK_CODE_GOTHIC

IntlChar::BLOCK_CODE_DESERET

IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS

IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS

IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B

IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT

IntlChar::BLOCK_CODE_TAGS

IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT

IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY

IntlChar::BLOCK_CODE_TAGALOG

IntlChar::BLOCK_CODE_HANUNOO

IntlChar::BLOCK_CODE_BUHID

IntlChar::BLOCK_CODE_TAGBANWA

IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A

IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A

IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B

IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B

IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS

IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS

IntlChar::BLOCK_CODE_VARIATION_SELECTORS

IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A

IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B

IntlChar::BLOCK_CODE_LIMBU

IntlChar::BLOCK_CODE_TAI_LE

IntlChar::BLOCK_CODE_KHMER_SYMBOLS

IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS

IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS

IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS

IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY

IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS

IntlChar::BLOCK_CODE_AEGEAN_NUMBERS

IntlChar::BLOCK_CODE_UGARITIC

IntlChar::BLOCK_CODE_SHAVIAN

IntlChar::BLOCK_CODE_OSMANYA

IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY

IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS

IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT

IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION

IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS

IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT

IntlChar::BLOCK_CODE_BUGINESE

IntlChar::BLOCK_CODE_CJK_STROKES

IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT

IntlChar::BLOCK_CODE_COPTIC

IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED

IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT

IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT

IntlChar::BLOCK_CODE_GLAGOLITIC

IntlChar::BLOCK_CODE_KHAROSHTHI

IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS

IntlChar::BLOCK_CODE_NEW_TAI_LUE

IntlChar::BLOCK_CODE_OLD_PERSIAN

IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT

IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION

IntlChar::BLOCK_CODE_SYLOTI_NAGRI

IntlChar::BLOCK_CODE_TIFINAGH

IntlChar::BLOCK_CODE_VERTICAL_FORMS

IntlChar::BLOCK_CODE_NKO

IntlChar::BLOCK_CODE_BALINESE

IntlChar::BLOCK_CODE_LATIN_EXTENDED_C

IntlChar::BLOCK_CODE_LATIN_EXTENDED_D

IntlChar::BLOCK_CODE_PHAGS_PA

IntlChar::BLOCK_CODE_PHOENICIAN

IntlChar::BLOCK_CODE_CUNEIFORM

IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION

IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS

IntlChar::BLOCK_CODE_SUNDANESE

IntlChar::BLOCK_CODE_LEPCHA

IntlChar::BLOCK_CODE_OL_CHIKI

IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A

IntlChar::BLOCK_CODE_VAI

IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B

IntlChar::BLOCK_CODE_SAURASHTRA

IntlChar::BLOCK_CODE_KAYAH_LI

IntlChar::BLOCK_CODE_REJANG

IntlChar::BLOCK_CODE_CHAM

IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS

IntlChar::BLOCK_CODE_PHAISTOS_DISC

IntlChar::BLOCK_CODE_LYCIAN

IntlChar::BLOCK_CODE_CARIAN

IntlChar::BLOCK_CODE_LYDIAN

IntlChar::BLOCK_CODE_MAHJONG_TILES

IntlChar::BLOCK_CODE_DOMINO_TILES

IntlChar::BLOCK_CODE_SAMARITAN

IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED

IntlChar::BLOCK_CODE_TAI_THAM

IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS

IntlChar::BLOCK_CODE_LISU

IntlChar::BLOCK_CODE_BAMUM

IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS

IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED

IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A

IntlChar::BLOCK_CODE_JAVANESE

IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A

IntlChar::BLOCK_CODE_TAI_VIET

IntlChar::BLOCK_CODE_MEETEI_MAYEK

IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B

IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC

IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN

IntlChar::BLOCK_CODE_AVESTAN

IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN

IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI

IntlChar::BLOCK_CODE_OLD_TURKIC

IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS

IntlChar::BLOCK_CODE_KAITHI

IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS

IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT

IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C

IntlChar::BLOCK_CODE_MANDAIC

IntlChar::BLOCK_CODE_BATAK

IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A

IntlChar::BLOCK_CODE_BRAHMI

IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT

IntlChar::BLOCK_CODE_KANA_SUPPLEMENT

IntlChar::BLOCK_CODE_PLAYING_CARDS

IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS

IntlChar::BLOCK_CODE_EMOTICONS

IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS

IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS

IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D

IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A

IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS

IntlChar::BLOCK_CODE_CHAKMA

IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS

IntlChar::BLOCK_CODE_MEROITIC_CURSIVE

IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS

IntlChar::BLOCK_CODE_MIAO

IntlChar::BLOCK_CODE_SHARADA

IntlChar::BLOCK_CODE_SORA_SOMPENG

IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT

IntlChar::BLOCK_CODE_TAKRI

IntlChar::BLOCK_CODE_BASSA_VAH

IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN

IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS

IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED

IntlChar::BLOCK_CODE_DUPLOYAN

IntlChar::BLOCK_CODE_ELBASAN

IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED

IntlChar::BLOCK_CODE_GRANTHA

IntlChar::BLOCK_CODE_KHOJKI

IntlChar::BLOCK_CODE_KHUDAWADI

IntlChar::BLOCK_CODE_LATIN_EXTENDED_E

IntlChar::BLOCK_CODE_LINEAR_A

IntlChar::BLOCK_CODE_MAHAJANI

IntlChar::BLOCK_CODE_MANICHAEAN

IntlChar::BLOCK_CODE_MENDE_KIKAKUI

IntlChar::BLOCK_CODE_MODI

IntlChar::BLOCK_CODE_MRO

IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B

IntlChar::BLOCK_CODE_NABATAEAN

IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN

IntlChar::BLOCK_CODE_OLD_PERMIC

IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS

IntlChar::BLOCK_CODE_PAHAWH_HMONG

IntlChar::BLOCK_CODE_PALMYRENE

IntlChar::BLOCK_CODE_PAU_CIN_HAU

IntlChar::BLOCK_CODE_PSALTER_PAHLAVI

IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS

IntlChar::BLOCK_CODE_SIDDHAM

IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS

IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C

IntlChar::BLOCK_CODE_TIRHUTA

IntlChar::BLOCK_CODE_WARANG_CITI

IntlChar::BLOCK_CODE_COUNT

IntlChar::BLOCK_CODE_INVALID_CODE

IntlChar::BPT_NONE

IntlChar::BPT_OPEN

IntlChar::BPT_CLOSE

IntlChar::BPT_COUNT

IntlChar::EA_NEUTRAL

IntlChar::EA_AMBIGUOUS

IntlChar::EA_HALFWIDTH

IntlChar::EA_FULLWIDTH

IntlChar::EA_NARROW

IntlChar::EA_WIDE

IntlChar::EA_COUNT

IntlChar::UNICODE_CHAR_NAME

IntlChar::UNICODE_10_CHAR_NAME

IntlChar::EXTENDED_CHAR_NAME

IntlChar::CHAR_NAME_ALIAS

IntlChar::CHAR_NAME_CHOICE_COUNT

IntlChar::SHORT_PROPERTY_NAME

IntlChar::LONG_PROPERTY_NAME

IntlChar::PROPERTY_NAME_CHOICE_COUNT

IntlChar::DT_NONE

IntlChar::DT_CANONICAL

IntlChar::DT_COMPAT

IntlChar::DT_CIRCLE

IntlChar::DT_FINAL

IntlChar::DT_FONT

IntlChar::DT_FRACTION

IntlChar::DT_INITIAL

IntlChar::DT_ISOLATED

IntlChar::DT_MEDIAL

IntlChar::DT_NARROW

IntlChar::DT_NOBREAK

IntlChar::DT_SMALL

IntlChar::DT_SQUARE

IntlChar::DT_SUB

IntlChar::DT_SUPER

IntlChar::DT_VERTICAL

IntlChar::DT_WIDE

IntlChar::DT_COUNT

IntlChar::JT_NON_JOINING

IntlChar::JT_JOIN_CAUSING

IntlChar::JT_DUAL_JOINING

IntlChar::JT_LEFT_JOINING

IntlChar::JT_RIGHT_JOINING

IntlChar::JT_TRANSPARENT

IntlChar::JT_COUNT

IntlChar::JG_NO_JOINING_GROUP

IntlChar::JG_AIN

IntlChar::JG_ALAPH

IntlChar::JG_ALEF

IntlChar::JG_BEH

IntlChar::JG_BETH

IntlChar::JG_DAL

IntlChar::JG_DALATH_RISH

IntlChar::JG_E

IntlChar::JG_FEH

IntlChar::JG_FINAL_SEMKATH

IntlChar::JG_GAF

IntlChar::JG_GAMAL

IntlChar::JG_HAH

IntlChar::JG_TEH_MARBUTA_GOAL

IntlChar::JG_HAMZA_ON_HEH_GOAL

IntlChar::JG_HE

IntlChar::JG_HEH

IntlChar::JG_HEH_GOAL

IntlChar::JG_HETH

IntlChar::JG_KAF

IntlChar::JG_KAPH

IntlChar::JG_KNOTTED_HEH

IntlChar::JG_LAM

IntlChar::JG_LAMADH

IntlChar::JG_MEEM

IntlChar::JG_MIM

IntlChar::JG_NOON

IntlChar::JG_NUN

IntlChar::JG_PE

IntlChar::JG_QAF

IntlChar::JG_QAPH

IntlChar::JG_REH

IntlChar::JG_REVERSED_PE

IntlChar::JG_SAD

IntlChar::JG_SADHE

IntlChar::JG_SEEN

IntlChar::JG_SEMKATH

IntlChar::JG_SHIN

IntlChar::JG_SWASH_KAF

IntlChar::JG_SYRIAC_WAW

IntlChar::JG_TAH

IntlChar::JG_TAW

IntlChar::JG_TEH_MARBUTA

IntlChar::JG_TETH

IntlChar::JG_WAW

IntlChar::JG_YEH

IntlChar::JG_YEH_BARREE

IntlChar::JG_YEH_WITH_TAIL

IntlChar::JG_YUDH

IntlChar::JG_YUDH_HE

IntlChar::JG_ZAIN

IntlChar::JG_FE

IntlChar::JG_KHAPH

IntlChar::JG_ZHAIN

IntlChar::JG_BURUSHASKI_YEH_BARREE

IntlChar::JG_FARSI_YEH

IntlChar::JG_NYA

IntlChar::JG_ROHINGYA_YEH

IntlChar::JG_MANICHAEAN_ALEPH

IntlChar::JG_MANICHAEAN_AYIN

IntlChar::JG_MANICHAEAN_BETH

IntlChar::JG_MANICHAEAN_DALETH

IntlChar::JG_MANICHAEAN_DHAMEDH

IntlChar::JG_MANICHAEAN_FIVE

IntlChar::JG_MANICHAEAN_GIMEL

IntlChar::JG_MANICHAEAN_HETH

IntlChar::JG_MANICHAEAN_HUNDRED

IntlChar::JG_MANICHAEAN_KAPH

IntlChar::JG_MANICHAEAN_LAMEDH

IntlChar::JG_MANICHAEAN_MEM

IntlChar::JG_MANICHAEAN_NUN

IntlChar::JG_MANICHAEAN_ONE

IntlChar::JG_MANICHAEAN_PE

IntlChar::JG_MANICHAEAN_QOPH

IntlChar::JG_MANICHAEAN_RESH

IntlChar::JG_MANICHAEAN_SADHE

IntlChar::JG_MANICHAEAN_SAMEKH

IntlChar::JG_MANICHAEAN_TAW

IntlChar::JG_MANICHAEAN_TEN

IntlChar::JG_MANICHAEAN_TETH

IntlChar::JG_MANICHAEAN_THAMEDH

IntlChar::JG_MANICHAEAN_TWENTY

IntlChar::JG_MANICHAEAN_WAW

IntlChar::JG_MANICHAEAN_YODH

IntlChar::JG_MANICHAEAN_ZAYIN

IntlChar::JG_STRAIGHT_WAW

IntlChar::JG_COUNT

IntlChar::GCB_OTHER

IntlChar::GCB_CONTROL

IntlChar::GCB_CR

IntlChar::GCB_EXTEND

IntlChar::GCB_L

IntlChar::GCB_LF

IntlChar::GCB_LV

IntlChar::GCB_LVT

IntlChar::GCB_T

IntlChar::GCB_V

IntlChar::GCB_SPACING_MARK

IntlChar::GCB_PREPEND

IntlChar::GCB_REGIONAL_INDICATOR

IntlChar::GCB_COUNT

IntlChar::WB_OTHER

IntlChar::WB_ALETTER

IntlChar::WB_FORMAT

IntlChar::WB_KATAKANA

IntlChar::WB_MIDLETTER

IntlChar::WB_MIDNUM

IntlChar::WB_NUMERIC

IntlChar::WB_EXTENDNUMLET

IntlChar::WB_CR

IntlChar::WB_EXTEND

IntlChar::WB_LF

IntlChar::WB_MIDNUMLET

IntlChar::WB_NEWLINE

IntlChar::WB_REGIONAL_INDICATOR

IntlChar::WB_HEBREW_LETTER

IntlChar::WB_SINGLE_QUOTE

IntlChar::WB_DOUBLE_QUOTE

IntlChar::WB_COUNT

IntlChar::SB_OTHER

IntlChar::SB_ATERM

IntlChar::SB_CLOSE

IntlChar::SB_FORMAT

IntlChar::SB_LOWER

IntlChar::SB_NUMERIC

IntlChar::SB_OLETTER

IntlChar::SB_SEP

IntlChar::SB_SP

IntlChar::SB_STERM

IntlChar::SB_UPPER

IntlChar::SB_CR

IntlChar::SB_EXTEND

IntlChar::SB_LF

IntlChar::SB_SCONTINUE

IntlChar::SB_COUNT

IntlChar::LB_UNKNOWN

IntlChar::LB_AMBIGUOUS

IntlChar::LB_ALPHABETIC

IntlChar::LB_BREAK_BOTH

IntlChar::LB_BREAK_AFTER

IntlChar::LB_BREAK_BEFORE

IntlChar::LB_MANDATORY_BREAK

IntlChar::LB_CONTINGENT_BREAK

IntlChar::LB_CLOSE_PUNCTUATION

IntlChar::LB_COMBINING_MARK

IntlChar::LB_CARRIAGE_RETURN

IntlChar::LB_EXCLAMATION

IntlChar::LB_GLUE

IntlChar::LB_HYPHEN

IntlChar::LB_IDEOGRAPHIC

IntlChar::LB_INSEPARABLE

IntlChar::LB_INSEPERABLE

IntlChar::LB_INFIX_NUMERIC

IntlChar::LB_LINE_FEED

IntlChar::LB_NONSTARTER

IntlChar::LB_NUMERIC

IntlChar::LB_OPEN_PUNCTUATION

IntlChar::LB_POSTFIX_NUMERIC

IntlChar::LB_PREFIX_NUMERIC

IntlChar::LB_QUOTATION

IntlChar::LB_COMPLEX_CONTEXT

IntlChar::LB_SURROGATE

IntlChar::LB_SPACE

IntlChar::LB_BREAK_SYMBOLS

IntlChar::LB_ZWSPACE

IntlChar::LB_NEXT_LINE

IntlChar::LB_WORD_JOINER

IntlChar::LB_H2

IntlChar::LB_H3

IntlChar::LB_JL

IntlChar::LB_JT

IntlChar::LB_JV

IntlChar::LB_CLOSE_PARENTHESIS

IntlChar::LB_CONDITIONAL_JAPANESE_STARTER

IntlChar::LB_HEBREW_LETTER

IntlChar::LB_REGIONAL_INDICATOR

IntlChar::LB_COUNT

IntlChar::NT_NONE

IntlChar::NT_DECIMAL

IntlChar::NT_DIGIT

IntlChar::NT_NUMERIC

IntlChar::NT_COUNT

IntlChar::HST_NOT_APPLICABLE

IntlChar::HST_LEADING_JAMO

IntlChar::HST_VOWEL_JAMO

IntlChar::HST_TRAILING_JAMO

IntlChar::HST_LV_SYLLABLE

IntlChar::HST_LVT_SYLLABLE

IntlChar::HST_COUNT

IntlChar::FOLD_CASE_DEFAULT

IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I

変更履歴

バージョン | 説明
7.0.6 | The IntlChar::NO_NUMERIC_VALUE constant was added.

目次

  • IntlChar::charAge — コードポイントの "age" を取得する
  • IntlChar::charDigitValue — 10進数の桁の文字を桁の値として取得する
  • IntlChar::charDirection — コードポイントの双方向カテゴリの値を取得する
  • IntlChar::charFromName — 名前で Unicode 文字を探し、コードポイントの値を返す
  • IntlChar::charMirror — コードポイントの "鏡文字" を取得する
  • IntlChar::charName — Unicode 文字の名前を取得する
  • IntlChar::charType — コードポイントの一般カテゴリの値を取得する
  • IntlChar::chr — コードポイント値に対応する、Unicode 文字を返す
  • IntlChar::digit — コードポイントの10進の数値を、指定された基数で返す
  • IntlChar::enumCharNames — 指定された範囲の全てのUnicode文字を走査する
  • IntlChar::enumCharTypes — Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する
  • IntlChar::foldCase — コードポイントに対してケースフォールディングを行う
  • IntlChar::forDigit — 指定された整数と基数を表す文字を取得する
  • IntlChar::getBidiPairedBracket — コードポイントと対になる括弧文字を取得する
  • IntlChar::getBlockCode — コードポイントが含まれる割当ブロックを取得する
  • IntlChar::getCombiningClass — コードポイントの合成クラスを取得する
  • IntlChar::getFC_NFKC_Closure — コードポイントの FC_NFKC_Closure プロパティの値を取得する
  • IntlChar::getIntPropertyMaxValue — Unicode プロパティの最大値を取得する
  • IntlChar::getIntPropertyMinValue — Unicode プロパティの最小値を取得する
  • IntlChar::getIntPropertyValue — コードポイントに対応する、Unicode プロパティの値を取得する
  • IntlChar::getNumericValue — Unicode のコードポイントの数値の値を取得する
  • IntlChar::getPropertyEnum — プロパティの名前に対応する定数値を取得する
  • IntlChar::getPropertyName — プロパティに対応する、Unicode での名前を取得する
  • IntlChar::getPropertyValueEnum — 指定された値の名前に対応する、プロパティの値を取得する
  • IntlChar::getPropertyValueName — プロパティの値に対応する、Unicode の名前を取得する
  • IntlChar::getUnicodeVersion — Unicode のバージョンを取得する
  • IntlChar::hasBinaryProperty — コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::isalnum — コードポイントが英数字であるかを調べる
  • IntlChar::isalpha — コードポイントがアルファベットかを調べる
  • IntlChar::isbase — コードポイントが基底文字に含まれるかを調べる
  • IntlChar::isblank — コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる
  • IntlChar::iscntrl — コードポイントが制御文字かどうかを調べる
  • IntlChar::isdefined — コードポイントが定義されているかどうかを調べる
  • IntlChar::isdigit — コードポイントが、数字であるかを調べる
  • IntlChar::isgraph — コードポイントが図形文字であるかを調べる
  • IntlChar::isIDIgnorable — コードポイントが無視できる文字かを調べる
  • IntlChar::isIDPart — コードポイントが識別子として使えるかを調べる
  • IntlChar::isIDStart — コードポイントが識別子の最初の文字として使えるかを調べる
  • IntlChar::isISOControl — コードポイントがISOで定義された制御文字であるかを調べる
  • IntlChar::isJavaIDPart — コードポイントが、Java の識別子として使えるかを調べる
  • IntlChar::isJavaIDStart — コードポイントが Java の識別子の最初の文字として使えるかを調べる
  • IntlChar::isJavaSpaceChar — コードポイントが Java におけるスペース文字であるかを調べる
  • IntlChar::islower — コードポイントが小文字かどうかを調べる
  • IntlChar::isMirrored — コードポイントが Bidi_Mirrored プロパティを持つかを調べる
  • IntlChar::isprint — コードポイントが印字可能な文字かを調べる
  • IntlChar::ispunct — コードポイントが句読点の文字かどうかを調べる
  • IntlChar::isspace — コードポイントが、スペース文字であるかを調べる
  • IntlChar::istitle — コードポイントがタイトルケース文字であるかを調べる
  • IntlChar::isUAlphabetic — コードポイントが、Alphabetic プロパティを持つかを調べる
  • IntlChar::isULowercase — コードポイントが小文字のUnicodeプロパティを持つかを調べる
  • IntlChar::isupper — コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
  • IntlChar::isUUppercase — コードポイントが大文字のUnicodeプロパティを持つかを調べる
  • IntlChar::isUWhiteSpace — コードポイントが、White_Space プロパティを持つかを調べる
  • IntlChar::isWhitespace — コードポイントが、ICU の空白文字であるかを調べる
  • IntlChar::isxdigit — コードポイントが、16進数の文字であるかを調べる
  • IntlChar::ord — 文字に対応する Unicode コードポイントを返す
  • IntlChar::tolower — Unicode 文字を小文字にする
  • IntlChar::totitle — Unicode 文字をタイトルケースにする
  • IntlChar::toupper — Unicode 文字を大文字にする


コードポイントの "age" を取得する

  • ≪ IntlChar
  • IntlChar::charDigitValue ≫
  • PHP Manual
  • IntlChar
  • コードポイントの "age" を取得する

IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — コードポイントの "age" を取得する

説明

public static IntlChar::charAge(int|string $codepoint): ?array

コードポイントの "age" を取得します。

"age" とは、(内部的な用途や、文字でない用途の場合) コードポイントが最初に設計された Unicode のバージョンです。 または、最初に文字が割り当てられた最初の Unicode のバージョンです。 これは、受け入れられない新しい文字を受け取り、 コードポイントを出力することを避けるために便利です。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

Unicode のバージョン番号を配列として返します。 たとえば、 1.3.31.2 は、 [1, 3, 31, 2] と表現されます。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charage("\u{2603}"));
var_dump(IntlChar::charage("\u{1F576}"));
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  int(1)
  [1]=>
  int(1)
  [2]=>
  int(0)
  [3]=>
  int(0)
}
array(4) {
  [0]=>
  int(7)
  [1]=>
  int(0)
  [2]=>
  int(0)
  [3]=>
  int(0)
}

参考

  • IntlChar::getUnicodeVersion() - Unicode のバージョンを取得する
  • IntlChar::getIntPropertyMinValue() - Unicode プロパティの最小値を取得する
  • IntlChar::getIntPropertyValue() - コードポイントに対応する、Unicode プロパティの値を取得する


10進数の桁の文字を桁の値として取得する

  • ≪ IntlChar::charAge
  • IntlChar::charDirection ≫
  • PHP Manual
  • IntlChar
  • 10進数の桁の文字を桁の値として取得する

IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — 10進数の桁の文字を桁の値として取得する

説明

public static IntlChar::charDigitValue(int|string $codepoint): ?int

10進数の桁の文字を、桁の値として取得します。

対象となる文字は、一般カテゴリ "Nd" (decimal digit numbers) と a Numeric_Type of Decimal に属するものです。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint の10進数の桁の値を返します。 10進数の桁の文字でない場合は、-1 を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charDigitValue("1"));
var_dump(IntlChar::charDigitValue("\u{0662}"));
var_dump(IntlChar::charDigitValue("\u{0E53}"));
?>

上の例の出力は以下となります。

int(1)
int(2)
int(3)

参考

  • IntlChar::getNumericValue() - Unicode のコードポイントの数値の値を取得する


コードポイントの双方向カテゴリの値を取得する

  • ≪ IntlChar::charDigitValue
  • IntlChar::charFromName ≫
  • PHP Manual
  • IntlChar
  • コードポイントの双方向カテゴリの値を取得する

IntlChar::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — コードポイントの双方向カテゴリの値を取得する

説明

public static IntlChar::charDirection(int|string $codepoint): ?int

» Unicode bidirectional algorithm (UAX #9) で使われる、コードポイントの双方向カテゴリの値を返します。

注意:

コードポイントが割り当てられていない値にも、 R や AL の双方向カテゴリを持つものがあります。 これは、右から左に書く言葉で予約されているブロックに含まれているからです。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

双方向カテゴリの値を返します。 下記の定数のうち、ひとつを返します:

  • IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT
  • IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT
  • IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER
  • IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR
  • IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR
  • IntlChar::CHAR_DIRECTION_ARABIC_NUMBER
  • IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR
  • IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR
  • IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR
  • IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL
  • IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL
  • IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING
  • IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE
  • IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC
  • IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING
  • IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE
  • IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT
  • IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK
  • IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL
  • IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE
  • IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE
  • IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE
  • IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE
  • IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT
Returns null on failure.

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charDirection("A") === IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT);
var_dump(IntlChar::charDirection("\u{05E9}") === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
var_dump(IntlChar::charDirection("+") === IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR);
var_dump(IntlChar::charDirection(".") === IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(true)


名前で Unicode 文字を探し、コードポイントの値を返す

  • ≪ IntlChar::charDirection
  • IntlChar::charMirror ≫
  • PHP Manual
  • IntlChar
  • 名前で Unicode 文字を探し、コードポイントの値を返す

IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — 名前で Unicode 文字を探し、コードポイントの値を返す

説明

public static IntlChar::charFromName(string $name, int $type = IntlChar::UNICODE_CHAR_NAME): ?int

名前で Unicode 文字を探し、コードポイントの値を返します。

指定する名前は、完全、かつ正確なマッチが行われます。 名前がコードポイントに対応していない場合は、null を返します。

Unicode 1.0 の名前は、 それ以降の "modern" name と異なる場合のみマッチします。 Unicode の名前は、全て大文字です。 拡張名は小文字ではじまり、その後に大文字の16進の数値が続き、 そしてそれを鉤括弧で囲んだものです。

パラメータ

name

Unicode 文字の完全な名前。

type

検索に使う名前の集合。 以下の定数のうちのいずれかです:

  • IntlChar::UNICODE_CHAR_NAME (デフォルト)
  • IntlChar::UNICODE_10_CHAR_NAME
  • IntlChar::EXTENDED_CHAR_NAME
  • IntlChar::CHAR_NAME_ALIAS
  • IntlChar::CHAR_NAME_CHOICE_COUNT

戻り値

指定された名前に対応するコードポイントの値を(数値で)返します。 コードポイントが存在しない場合は null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charFromName("LATIN CAPITAL LETTER A"));
var_dump(IntlChar::charFromName("SNOWMAN"));
var_dump(IntlChar::charFromName("RECYCLING SYMBOL FOR TYPE-1 PLASTICS"));
var_dump(IntlChar::charFromName("A RANDOM STRING WHICH DOESN'T CORRESPOND TO ANY UNICODE CHARACTER"));
?>

上の例の出力は以下となります。

int(65)
int(9731)
int(9843)
NULL

参考

  • IntlChar::charName() - Unicode 文字の名前を取得する
  • IntlChar::enumCharNames() - 指定された範囲の全てのUnicode文字を走査する


コードポイントの "鏡文字" を取得する

  • ≪ IntlChar::charFromName
  • IntlChar::charName ≫
  • PHP Manual
  • IntlChar
  • コードポイントの "鏡文字" を取得する

IntlChar::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — コードポイントの "鏡文字" を取得する

説明

public static IntlChar::charMirror(int|string $codepoint): int|string|null

指定された文字を、鏡文字 にマップします。

Bidi_Mirrored プロパティを持つ文字ごとに、 実装上、別のUnicode文字 (コードポイント) への "安っぽい" (poor man's) マッピング が必要になることがあります。 これは、特定の文字のデフォルトのグリフが、 指定された文字のデフォルトのグリフに対する鏡文字 (上下はそのままで、左右を反転させた文字) にあたるように対応付けることです。 こうすることで、 文字方向を考慮したり、 グリフを選択する機能がないディスプレイのために、 テキスト変換を行うのに有用です。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

鏡文字(上下はそのままで、左右を反転させた文字) として置き換えられる可能性のある、 別の Unicode コードポイントを返します。 そのようなマッピングが存在しなかったり、 codepoint が Bidi_Mirrored プロパティを持たない場合には、 codepoint そのものを返します。

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charMirror("A"));
var_dump(IntlChar::charMirror("<"));
var_dump(IntlChar::charMirror("("));
?>

上の例の出力は以下となります。

string(1) "A"
string(1) ">"
string(2) ")"

参考

  • IntlChar::isMirrored() - コードポイントが Bidi_Mirrored プロパティを持つかを調べる
  • IntlChar::PROPERTY_BIDI_MIRRORED


Unicode 文字の名前を取得する

  • ≪ IntlChar::charMirror
  • IntlChar::charType ≫
  • PHP Manual
  • IntlChar
  • Unicode 文字の名前を取得する

IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Unicode 文字の名前を取得する

説明

public static IntlChar::charName(int|string $codepoint, int $type = IntlChar::UNICODE_CHAR_NAME): ?string

Unicode 文字の名前を取得します。

type の値によって、返される名前は "modern" name か、 Unicode 1.0 で定義されたもののどちらかになります。 名前には A-Z, 0-9, space, '-' のような "不変な" 文字が含まれています。 Unicode 1.0 の名前は、それが "modern" name と異なっており、 かつ ICU がその名前のデータを持っている時に限り取得できます。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

type

検索に使う名前の集合。 以下の定数のうちのいずれかです:

  • IntlChar::UNICODE_CHAR_NAME (デフォルト)
  • IntlChar::UNICODE_10_CHAR_NAME
  • IntlChar::EXTENDED_CHAR_NAME
  • IntlChar::CHAR_NAME_ALIAS
  • IntlChar::CHAR_NAME_CHOICE_COUNT

戻り値

対応する名前を返します。 その文字に対応する名前がない場合は、空文字列を返します。 コードポイントが存在しない場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charName("."));
var_dump(IntlChar::charName(".", IntlChar::UNICODE_CHAR_NAME));
var_dump(IntlChar::charName("\u{2603}"));
var_dump(IntlChar::charName("\u{0000}"));
?>

上の例の出力は以下となります。

string(9) "FULL STOP"
string(9) "FULL STOP"
string(7) "SNOWMAN"
string(0) ""

参考

  • IntlChar::charFromName() - 名前で Unicode 文字を探し、コードポイントの値を返す
  • IntlChar::enumCharNames() - 指定された範囲の全てのUnicode文字を走査する


コードポイントの一般カテゴリの値を取得する

  • ≪ IntlChar::charName
  • IntlChar::chr ≫
  • PHP Manual
  • IntlChar
  • コードポイントの一般カテゴリの値を取得する

IntlChar::charType

(PHP 7, PHP 8)

IntlChar::charType — コードポイントの一般カテゴリの値を取得する

説明

public static IntlChar::charType(int|string $codepoint): ?int

コードポイントの一般カテゴリの値を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

一般カテゴリタイプの値を返します。 以下の定数のうちのひとつです:

  • IntlChar::CHAR_CATEGORY_UNASSIGNED
  • IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES
  • IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER
  • IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER
  • IntlChar::CHAR_CATEGORY_TITLECASE_LETTER
  • IntlChar::CHAR_CATEGORY_MODIFIER_LETTER
  • IntlChar::CHAR_CATEGORY_OTHER_LETTER
  • IntlChar::CHAR_CATEGORY_NON_SPACING_MARK
  • IntlChar::CHAR_CATEGORY_ENCLOSING_MARK
  • IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK
  • IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER
  • IntlChar::CHAR_CATEGORY_LETTER_NUMBER
  • IntlChar::CHAR_CATEGORY_OTHER_NUMBER
  • IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR
  • IntlChar::CHAR_CATEGORY_LINE_SEPARATOR
  • IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR
  • IntlChar::CHAR_CATEGORY_CONTROL_CHAR
  • IntlChar::CHAR_CATEGORY_FORMAT_CHAR
  • IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR
  • IntlChar::CHAR_CATEGORY_SURROGATE
  • IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_START_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_END_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_MATH_SYMBOL
  • IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL
  • IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL
  • IntlChar::CHAR_CATEGORY_OTHER_SYMBOL
  • IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION
  • IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::charType("A") === IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER);
var_dump(IntlChar::charType(".") === IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION);
var_dump(IntlChar::charType("\t") === IntlChar::CHAR_CATEGORY_CONTROL_CHAR);
var_dump(IntlChar::charType("\u{2603}") === IntlChar::CHAR_CATEGORY_OTHER_SYMBOL);
var_dump(IntlChar::charType("multiple chars") === null);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(true)
bool(true)


コードポイント値に対応する、Unicode 文字を返す

  • ≪ IntlChar::charType
  • IntlChar::digit ≫
  • PHP Manual
  • IntlChar
  • コードポイント値に対応する、Unicode 文字を返す

IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — コードポイント値に対応する、Unicode 文字を返す

説明

public static IntlChar::chr(int|string $codepoint): ?string

指定された Unicode のコードポイント値に対応する、 一文字を含んだ文字列を返します。

このメソッドは、 IntlChar::ord() を補完するものです。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

指定された Unicode のコードポイント値に対応する、 一文字を含んだ文字列を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
$values = ["A", 63, 123, 9731];
foreach ($values as $value) {
var_dump(IntlChar::chr($value));
}
?>

上の例の出力は以下となります。

string(1) "A"
string(1) "?"
string(1) "{"
string(3) "?"

参考

  • IntlChar::ord() - 文字に対応する Unicode コードポイントを返す
  • mb_chr() - Unicode のコードポイントに対応する文字を返す
  • chr() - 数値から、1バイトの文字列を生成する


コードポイントの10進の数値を、指定された基数で返す

  • ≪ IntlChar::chr
  • IntlChar::enumCharNames ≫
  • PHP Manual
  • IntlChar
  • コードポイントの10進の数値を、指定された基数で返す

IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — コードポイントの10進の数値を、指定された基数で返す

説明

public static IntlChar::digit(int|string $codepoint, int $base = 10): int|false|null

指定されたコードポイントの10進の数値を、指定された基数で返します。

基数が 2<=radix<=36 の範囲外であったり、 codepoint の値が指定された基数に対して有効な値でない場合、 false を返します。 次のいずれかが当てはまる場合、 有効な値であると見なされます。

  • 指定された文字が、10進数の値である場合。 これは、general category "Nd" (decimal digit numbers)、かつ Numeric_Type of Decimal である場合です。 この場合、値はその文字の10進の数値になります。
  • 指定された文字が、アルファベットの大文字 'A' から 'Z' までの範囲にある場合。 この場合、値は指定された文字を c とすると、c-'A'+10 になります。
  • 指定された文字が、アルファベットの小文字 'a' から 'z' までの範囲にある場合。 この場合、値は指定された文字を c とすると、c-'a'+10 になります。
  • ASCII の範囲 (0061..007A, 0041..005A) または全角の ASCII の範囲 (FF41..FF5A, FF21..FF3A) にあると認識できるアルファベットの場合。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

base

基数 (デフォルトは 10 です)

戻り値

文字で表現される数値を、指定された基数で返します。 指定された値が基数を超過していたり、 値が存在しない場合は false を返します。 失敗した場合は、null を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::digit("0"));
var_dump(IntlChar::digit("3"));
var_dump(IntlChar::digit("A"));
var_dump(IntlChar::digit("A", 16));
?>

上の例の出力は以下となります。

int(0)
int(3)
bool(false)
int(10)

参考

  • IntlChar::forDigit() - 指定された整数と基数を表す文字を取得する
  • IntlChar::charDigitValue() - 10進数の桁の文字を桁の値として取得する
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる
  • IntlChar::PROPERTY_NUMERIC_TYPE


指定された範囲の全てのUnicode文字を走査する

  • ≪ IntlChar::digit
  • IntlChar::enumCharTypes ≫
  • PHP Manual
  • IntlChar
  • 指定された範囲の全てのUnicode文字を走査する

IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — 指定された範囲の全てのUnicode文字を走査する

説明

public static IntlChar::enumCharNames(
int|string $start,
int|string $end,
callable $callback,
int $type = IntlChar::UNICODE_CHAR_NAME
): bool

最初と最後(但し、最初は含み、最後は含まない) の範囲にある Unicode 文字を全て走査し、 個々の文字について、コードポイントの値と文字の名前を渡してコールバック関数をコールします。

Unicode 1.0 の名前については、modern name と異なるもののみが走査されます。

パラメータ

start

走査を開始する最初のコードポイント。

end

走査する最後のコードポイントよりひとつ先を指定します。

callback

文字の名前それぞれについて、この関数がコールされます。 以下の3つの引数が渡されます:

  • int $codepoint - コードポイントの数値
  • int $nameChoice - 以下に示す type と同じ値
  • string $name - 文字の名前

type

どの種類の名前を走査するかを選びます。以下の定数が使えます:

  • IntlChar::UNICODE_CHAR_NAME (デフォルト)
  • IntlChar::UNICODE_10_CHAR_NAME
  • IntlChar::EXTENDED_CHAR_NAME
  • IntlChar::CHAR_NAME_ALIAS
  • IntlChar::CHAR_NAME_CHOICE_COUNT

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | この関数は、失敗時に false を返すようになりました。 これより前のバージョンでは null を返していました。

例

例1 サンプルの範囲に入るコードポイントを走査する例

<?php
IntlChar::enumCharNames(0x2600, 0x2610, function($codepoint, $nameChoice, $name) {
printf("U+%04x %s\n", $codepoint, $name);
});
?>

上の例の出力は以下となります。

U+2600 BLACK SUN WITH RAYS
U+2601 CLOUD
U+2602 UMBRELLA
U+2603 SNOWMAN
U+2604 COMET
U+2605 BLACK STAR
U+2606 WHITE STAR
U+2607 LIGHTNING
U+2608 THUNDERSTORM
U+2609 SUN
U+260a ASCENDING NODE
U+260b DESCENDING NODE
U+260c CONJUNCTION
U+260d OPPOSITION
U+260e BLACK TELEPHONE
U+260f WHITE TELEPHONE

参考

  • IntlChar::charName() - Unicode 文字の名前を取得する
  • IntlChar::charFromName() - 名前で Unicode 文字を探し、コードポイントの値を返す


Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する

  • ≪ IntlChar::enumCharNames
  • IntlChar::foldCase ≫
  • PHP Manual
  • IntlChar
  • Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する

IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する

説明

public static IntlChar::enumCharTypes(callable $callback): void

Unicode の一般カテゴリの情報を付加した形で、全てのコードポイントを効率的に走査します。 これは、全ての割当済みのコードポイントを走査し、データ構造を作る用途などに役立ちます。

一般カテゴリ("character type") の情報が付いた、コードポイントの連続した範囲それぞれについて、 callback 関数がコールされます。 隣接した範囲は違う type を持ちます。 Unicode 標準は、この type の値の範囲が 0..31 にあることを保証しています。

パラメータ

callback

同じ一般カテゴリを持つ、連続した範囲のコードポイントそれぞれについて、 コールされるコールバック関数です。 3つの引数を渡すことが出来ます:

  • int $start - 範囲の始めにあたるコードポイント
  • int $end - 範囲の最後にあたるコードポイント
  • int $name - カテゴリタイプ (定数 IntlChar::CHAR_CATEGORY_* のうちのひとつ)

戻り値

値を返しません。

例

例1 サンプルのコードポイントの範囲を走査する

<?php
IntlChar::enumCharTypes(function($start, $end, $type) {
printf("U+%04x through U+%04x are in category %d\n", $start, $end, $type);
});
?>

上の例の出力は以下となります。

U+0000 through U+0020 are in category 15
U+0020 through U+0021 are in category 12
U+0021 through U+0024 are in category 23
U+0024 through U+0025 are in category 25
U+0025 through U+0028 are in category 23
U+0028 through U+0029 are in category 20
U+0029 through U+002a are in category 21
U+002a through U+002b are in category 23
U+002b through U+002c are in category 24
U+002c through U+002d are in category 23
U+002d through U+002e are in category 19
U+002e through U+0030 are in category 23
U+0030 through U+003a are in category 9
...


コードポイントに対してケースフォールディングを行う

  • ≪ IntlChar::enumCharTypes
  • IntlChar::forDigit ≫
  • PHP Manual
  • IntlChar
  • コードポイントに対してケースフォールディングを行う

IntlChar::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — コードポイントに対してケースフォールディングを行う

説明

public static IntlChar::foldCase(int|string $codepoint, int $options = IntlChar::FOLD_CASE_DEFAULT): int|string|null

指定された文字を、 ケースフォールディングの仕様に照らして等価な文字にマップします。 そのような文字が存在しない場合は、指定された文字そのものを返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

options

IntlChar::FOLD_CASE_DEFAULT (デフォルト) または IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I

戻り値

指定されたコードポイントに、 Simple_Case_Folding が存在する場合、それを返します。 存在しない場合、指定されたコードポイントそのものを返します。 失敗した場合は、null を返します。


指定された整数と基数を表す文字を取得する

  • ≪ IntlChar::foldCase
  • IntlChar::getBidiPairedBracket ≫
  • PHP Manual
  • IntlChar
  • 指定された整数と基数を表す文字を取得する

IntlChar::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — 指定された整数と基数を表す文字を取得する

説明

public static IntlChar::forDigit(int $digit, int $base = 10): int

指定された整数値と基数を表現する文字を判定します。

基数の値が正しくない場合、 または指定された基数に対して整数値が無効な場合、 null 文字 (U+0000) を返します。

基数は 2 以上 36 以下の場合に有効です。 整数値は、0 <= digit < radix の場合に有効です。

整数値が 10 より小さい場合、 '0' (ASCII の文字「0」) + 指定された整数値の値を返します。 そうでない場合、'a' + 指定された整数値 - 10 の値を返します。

パラメータ

digit

文字に変換する整数値。

base

基数 (デフォルトは 10)

戻り値

指定された整数値と基数を表す、 文字を数値として返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::forDigit(0));
var_dump(IntlChar::forDigit(3));
var_dump(IntlChar::forDigit(3, 10));
var_dump(IntlChar::forDigit(10));
var_dump(IntlChar::forDigit(10, 16));
?>

上の例の出力は以下となります。

int(48)
int(51)
int(51)
int(0)
int(97)

参考

  • IntlChar::digit() - コードポイントの10進の数値を、指定された基数で返す
  • IntlChar::charDigitValue() - 10進数の桁の文字を桁の値として取得する
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる
  • IntlChar::PROPERTY_NUMERIC_TYPE


コードポイントと対になる括弧文字を取得する

  • ≪ IntlChar::forDigit
  • IntlChar::getBlockCode ≫
  • PHP Manual
  • IntlChar
  • コードポイントと対になる括弧文字を取得する

IntlChar::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — コードポイントと対になる括弧文字を取得する

説明

public static IntlChar::getBidiPairedBracket(int|string $codepoint): int|string|null

指定された文字を、それと対になる括弧文字にマップします。

Bidi_Paired_Bracket_Type!=None の場合、 これは IntlChar::charMirror() と同等です。 そうでない場合、codepoint そのものを返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

対になる括弧にあたるコードポイントを返します。 そのような文字がない場合は、 codepoint そのものを返します。 失敗した場合は、null を返します。

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getBidiPairedBracket(91));
var_dump(IntlChar::getBidiPairedBracket('['));
?>

上の例の出力は以下となります。

int(93)
string(1) "]"

参考

  • IntlChar::charMirror() - コードポイントの "鏡文字" を取得する
  • IntlChar::PROPERTY_BIDI_PAIRED_BRACKET
  • IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE


コードポイントが含まれる割当ブロックを取得する

  • ≪ IntlChar::getBidiPairedBracket
  • IntlChar::getCombiningClass ≫
  • PHP Manual
  • IntlChar
  • コードポイントが含まれる割当ブロックを取得する

IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — コードポイントが含まれる割当ブロックを取得する

説明

public static IntlChar::getBlockCode(int|string $codepoint): ?int

コードポイントが含まれる Unicode の割当ブロックを返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint のブロックの値を返します。 返されうる値については 定数 IntlChar::BLOCK_CODE_* を参照ください。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getBlockCode("A") === IntlChar::BLOCK_CODE_BASIC_LATIN);
var_dump(IntlChar::getBlockCode("Φ") === IntlChar::BLOCK_CODE_GREEK);
var_dump(IntlChar::getBlockCode("\u{2603}") === IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)


コードポイントの合成クラスを取得する

  • ≪ IntlChar::getBlockCode
  • IntlChar::getFC_NFKC_Closure ≫
  • PHP Manual
  • IntlChar
  • コードポイントの合成クラスを取得する

IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — コードポイントの合成クラスを取得する

説明

public static IntlChar::getCombiningClass(int|string $codepoint): ?int

指定されたコードポイントの合成クラス (combining class) を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

指定されたコードポイントの合成クラス (combining class) の値を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getCombiningClass("A"));
var_dump(IntlChar::getCombiningClass("\u{0334}"));
var_dump(IntlChar::getCombiningClass("\u{0358}"));
?>

上の例の出力は以下となります。

int(0)
int(1)
int(232)


コードポイントの FC_NFKC_Closure プロパティの値を取得する

  • ≪ IntlChar::getCombiningClass
  • IntlChar::getIntPropertyMaxValue ≫
  • PHP Manual
  • IntlChar
  • コードポイントの FC_NFKC_Closure プロパティの値を取得する

IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — コードポイントの FC_NFKC_Closure プロパティの値を取得する

説明

public static IntlChar::getFC_NFKC_Closure(int|string $codepoint): string|false|null

コードポイントの FC_NFKC_Closure プロパティの値を文字列で取得します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint の FC_NFKC_Closure プロパティの値を文字列で返します。 値が存在しない場合は、空文字列を返します。 失敗した場合は、null または false を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
?>

上の例の出力は以下となります。

string(3) "tel"
string(2) "a"


Unicode プロパティの最大値を取得する

  • ≪ IntlChar::getFC_NFKC_Closure
  • IntlChar::getIntPropertyMinValue ≫
  • PHP Manual
  • IntlChar
  • Unicode プロパティの最大値を取得する

IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Unicode プロパティの最大値を取得する

説明

public static IntlChar::getIntPropertyMaxValue(int $property): int

Unicode プロパティの値 enumerated/integer/binary のうち、最大値を取得します。

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

戻り値

IntlChar::getIntPropertyValue() が返す Unicode プロパティの最大値を返します。 プロパティのセレクタが範囲外の場合は <=0 の値を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_BIDI_CLASS));
var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_SCRIPT));
var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_IDEOGRAPHIC));
var_dump(IntlChar::getIntPropertyMaxValue(999999999)); // Some made-up value
?>

上の例の出力は以下となります。

int(22)
int(166)
int(1)
int(-1)

参考

  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::getIntPropertyMinValue() - Unicode プロパティの最小値を取得する
  • IntlChar::getIntPropertyValue() - コードポイントに対応する、Unicode プロパティの値を取得する
  • IntlChar::getUnicodeVersion() - Unicode のバージョンを取得する


Unicode プロパティの最小値を取得する

  • ≪ IntlChar::getIntPropertyMaxValue
  • IntlChar::getIntPropertyValue ≫
  • PHP Manual
  • IntlChar
  • Unicode プロパティの最小値を取得する

IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Unicode プロパティの最小値を取得する

説明

public static IntlChar::getIntPropertyMinValue(int $property): int

Unicode プロパティの値 enumerated/integer/binary のうち、最小値を取得します。

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

戻り値

IntlChar::getIntPropertyValue() が返す Unicode プロパティの最小値を返します。 プロパティのセレクタが範囲外の場合は 0 を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_BIDI_CLASS));
var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_SCRIPT));
var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_IDEOGRAPHIC));
var_dump(IntlChar::getIntPropertyMinValue(999999999)); // Some made-up value
?>

上の例の出力は以下となります。

int(0)
int(0)
int(0)
int(0)

参考

  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::getIntPropertyMaxValue() - Unicode プロパティの最大値を取得する
  • IntlChar::getIntPropertyValue() - コードポイントに対応する、Unicode プロパティの値を取得する
  • IntlChar::getUnicodeVersion() - Unicode のバージョンを取得する


コードポイントに対応する、Unicode プロパティの値を取得する

  • ≪ IntlChar::getIntPropertyMinValue
  • IntlChar::getNumericValue ≫
  • PHP Manual
  • IntlChar
  • コードポイントに対応する、Unicode プロパティの値を取得する

IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — コードポイントに対応する、Unicode プロパティの値を取得する

説明

public static IntlChar::getIntPropertyValue(int|string $codepoint, int $property): ?int

コードポイントに対応する、 Unicode プロパティを示す整数値か、 列挙値に対応するプロパティの値を取得します。 バイナリとマスクプロパティの値も返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

戻り値

プロパティの値に直接対応する数値か、 列挙型のプロパティの場合は、 列挙型のそれぞれのプロパティの定数に対応する数値を返します。 失敗した場合は、null を返します。

バイナリ Unicode プロパティの場合は、 0 または 1 (false/true に対応) を返します。

マスクプロパティの場合は、ビットマスクの値を返します。

property が範囲外の値だったり、 Unicode がプロパティやコードポイントのデータを全く持っていない場合は、 0 を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getIntPropertyValue("A", IntlChar::PROPERTY_ALPHABETIC) === 1);
var_dump(IntlChar::getIntPropertyValue("[", IntlChar::PROPERTY_BIDI_MIRRORED) === 1);
var_dump(IntlChar::getIntPropertyValue("Φ", IntlChar::PROPERTY_BLOCK) === IntlChar::BLOCK_CODE_GREEK);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)

参考

  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::getIntPropertyMinValue() - Unicode プロパティの最小値を取得する
  • IntlChar::getIntPropertyMaxValue() - Unicode プロパティの最大値を取得する
  • IntlChar::getUnicodeVersion() - Unicode のバージョンを取得する


Unicode のコードポイントの数値の値を取得する

  • ≪ IntlChar::getIntPropertyValue
  • IntlChar::getPropertyEnum ≫
  • PHP Manual
  • IntlChar
  • Unicode のコードポイントの数値の値を取得する

IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Unicode のコードポイントの数値の値を取得する

説明

public static IntlChar::getNumericValue(int|string $codepoint): ?float

Unicode Character Database で定義された コードポイントの数値の値を取得します。

Unicode Character Database の中で 数値の値がない文字については、 IntlChar::NO_NUMERIC_VALUE を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint の数値の値を返します。 値が未定義の場合は IntlChar::NO_NUMERIC_VALUE を返します。 IntlChar::NO_NUMERIC_VALUE は PHP 7.0.6 で追加されました。 これより前のバージョンでは、リテラル値 (float)-123456789 が使われる可能性がありました。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::getNumericValue("4"));
var_dump(IntlChar::getNumericValue("x"));
var_dump(IntlChar::getNumericValue("\u{216C}"));
?>

上の例の出力は以下となります。

float(4)
float(-123456789)
float(50)


プロパティの名前に対応する定数値を取得する

  • ≪ IntlChar::getNumericValue
  • IntlChar::getPropertyName ≫
  • PHP Manual
  • IntlChar
  • プロパティの名前に対応する定数値を取得する

IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — プロパティの名前に対応する定数値を取得する

説明

public static IntlChar::getPropertyEnum(string $alias): int

指定されたプロパティの名前に対応する、プロパティの定数値を返します。 これは、Unicode のデータベースファイル PropertyAliases.txt に存在するものです。 短縮名や長い名前、その他の名前も認識します。

さらに、 この関数はプロパティ IntlChar::PROPERTY_GENERAL_CATEGORY_MASK を仮想の名前 "gcm" / "General_Category_Mask" に対応させています。 これらの名前は、PropertyAliases.txt には存在しません。

この関数は、 IntlChar::getPropertyName() を補完するものです。

パラメータ

alias

マッチさせるプロパティの名前。 PropertyAliases.txt で説明されている "loose matching" を使って比較されます。

戻り値

IntlChar::PROPERTY_ で始まる定数値を返します。 指定した名前が、どのプロパティにもマッチしない場合は IntlChar::PROPERTY_INVALID_CODE を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getPropertyEnum('Bidi_Class') === IntlChar::PROPERTY_BIDI_CLASS);
var_dump(IntlChar::getPropertyEnum('script') === IntlChar::PROPERTY_SCRIPT);
var_dump(IntlChar::getPropertyEnum('IDEOGRAPHIC') === IntlChar::PROPERTY_IDEOGRAPHIC);
var_dump(IntlChar::getPropertyEnum('Some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(true)

参考

  • IntlChar::getPropertyName() - プロパティに対応する、Unicode での名前を取得する


プロパティに対応する、Unicode での名前を取得する

  • ≪ IntlChar::getPropertyEnum
  • IntlChar::getPropertyValueEnum ≫
  • PHP Manual
  • IntlChar
  • プロパティに対応する、Unicode での名前を取得する

IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — プロパティに対応する、Unicode での名前を取得する

説明

public static IntlChar::getPropertyName(int $property, int $type = IntlChar::LONG_PROPERTY_NAME): string|false

指定されたプロパティに対応する、Unicode の名前を返します。 Unicode のデータベースファイル PropertyAliases.txt に存在するものです。

さらに、 この関数はプロパティ IntlChar::PROPERTY_GENERAL_CATEGORY_MASK を仮想の名前 "gcm" / "General_Category_Mask" に対応させています。 これらの名前は、PropertyAliases.txt には存在しません。

この関数は、 IntlChar::getPropertyEnum() を補完するものです。

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

IntlChar::PROPERTY_INVALID_CODE は使ってはいけません。 また、property が範囲外の値の場合 false を返します。

type

どの名前を取得するかを選択します。 範囲外の値が指定された場合、false を返します。

全てのプロパティには長い名前 (long name) が存在します。 殆どのプロパティには短縮名 (short name) が存在しますが、 ないものもあります。 さらに、Unicode はこれら以外の追加の名前も許容しています。つまり、 追加の名前が存在する場合、 IntlChar::LONG_PROPERTY_NAME に追加される形で返されます。

戻り値

名前を返します。 property や type が範囲外の場合は、 false を返します。

指定された type が false を返す場合は、 それより大きな type の値も false を返しますが、 ひとつだけ例外があります。 IntlChar::SHORT_PROPERTY_NAME を指定して false を返す場合は、 IntlChar::LONG_PROPERTY_NAME (と、それより大きな値) は false でない値を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS));
var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::SHORT_PROPERTY_NAME));
var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME));
var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME + 1));
?>

上の例の出力は以下となります。

string(10) "Bidi_Class"
string(2) "bc"
string(10) "Bidi_Class"
bool(false)

参考

  • IntlChar::getPropertyEnum() - プロパティの名前に対応する定数値を取得する


指定された値の名前に対応する、プロパティの値を取得する

  • ≪ IntlChar::getPropertyName
  • IntlChar::getPropertyValueName ≫
  • PHP Manual
  • IntlChar
  • 指定された値の名前に対応する、プロパティの値を取得する

IntlChar::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — 指定された値の名前に対応する、プロパティの値を取得する

説明

public static IntlChar::getPropertyValueEnum(int $property, string $name): int

指定された値の名前に対応する、プロパティの値を整数で返します。 Unicode のデータベースファイル PropertyValueAliases.txt に存在するものです。 短縮名や長い名前、その他の名前も認識します。

注意:

PropertyValueAliases.txt に存在する名前の中には、 IntlChar::PROPERTY_GENERAL_CATEGORY_MASK を指定しないと取得できないものがあります。 IntlChar::PROPERTY_GENERAL_CATEGORY を指定すると取得できません。 以下の文字が該当します:

  • "C" / "Other"
  • "L" / "Letter"
  • "LC" / "Cased_Letter"
  • "M" / "Mark"
  • "N" / "Number"
  • "P" / "Punctuation"
  • "S" / "Symbol"
  • "Z" / "Separator"

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

範囲外の値が指定されたり、 このメソッドが指定された値で動作しなかった場合は、 IntlChar::PROPERTY_INVALID_CODE を返します。

name

マッチさせる値の名前。 PropertyValueAliases.txt で説明されている "loose matching" を使って比較されます。

戻り値

対応する値の整数を返します。 指定した名前が、プロパティのどの値にもマッチしないか、 プロパティそのものが無効な場合は、 IntlChar::PROPERTY_INVALID_CODE を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BLOCK, 'greek') === IntlChar::BLOCK_CODE_GREEK);
var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'RIGHT_TO_LEFT') === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
var_dump(IntlChar::getPropertyValueEnum(123456789, 'RIGHT_TO_LEFT') === IntlChar::PROPERTY_INVALID_CODE);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(true)


プロパティの値に対応する、Unicode の名前を取得する

  • ≪ IntlChar::getPropertyValueEnum
  • IntlChar::getUnicodeVersion ≫
  • PHP Manual
  • IntlChar
  • プロパティの値に対応する、Unicode の名前を取得する

IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — プロパティの値に対応する、Unicode の名前を取得する

説明

public static IntlChar::getPropertyValueName(int $property, int $value, int $type = IntlChar::LONG_PROPERTY_NAME): string|false

指定されたプロパティの値に対応する、Unicode の名前を返します。 Unicode のデータベースファイル PropertyValueAliases.txt に存在するものです。

注意:

PropertyValueAliases.txt に存在する名前の中には、 IntlChar::PROPERTY_GENERAL_CATEGORY_MASK を指定しないと取得できないものがあります。 IntlChar::PROPERTY_GENERAL_CATEGORY を指定すると取得できません。 以下の文字が該当します:

  • "C" / "Other"
  • "L" / "Letter"
  • "LC" / "Cased_Letter"
  • "M" / "Mark"
  • "N" / "Number"
  • "P" / "Punctuation"
  • "S" / "Symbol"
  • "Z" / "Separator"

パラメータ

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

範囲外の値が指定されたり、 このメソッドが指定された値で動作しなかった場合は、 false を返します。

value

プロパティの値を指定します。 範囲外の値が指定された場合、false を返します。

一般的に、有効な値は 0 からある最大値までの値を取りますが、いくつか例外があります:

  • プロパティが IntlChar::PROPERTY_BLOCK の場合、 0 でない値 IntlChar::BLOCK_CODE_BASIC_LATIN から始まります。
  • プロパティが IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS の場合は、連続してしない 0..240 までの値を取ります。

type

どの名前を取得するかを選択します。 範囲外の値の場合、false を返します。

全ての値には長い名前 (long name) が存在します。 殆どの値には短縮名 (short name) が存在しますが、 ないものもあります。 さらに、Unicode はこれら以外の追加の名前も許容しています。つまり、 追加の名前が存在する場合、 IntlChar::LONG_PROPERTY_NAME に追加される形で返されます。

戻り値

名前を返します。 property や type が範囲外の場合は、 false を返します。 失敗した場合は、null を返します。

指定された type が false を返す場合は、 それより大きな type の値も false を返しますが、 ひとつだけ例外があります。 IntlChar::SHORT_PROPERTY_NAME を指定して false を返す場合は、 IntlChar::LONG_PROPERTY_NAME (と、それより大きな値) は false でない値を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK));
var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::SHORT_PROPERTY_NAME));
var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME));
var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME + 1));
?>

上の例の出力は以下となります。

string(16) "Greek_And_Coptic"
string(5) "Greek"
string(16) "Greek_And_Coptic"
bool(false)


Unicode のバージョンを取得する

  • ≪ IntlChar::getPropertyValueName
  • IntlChar::hasBinaryProperty ≫
  • PHP Manual
  • IntlChar
  • Unicode のバージョンを取得する

IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Unicode のバージョンを取得する

説明

public static IntlChar::getUnicodeVersion(): array

Unicode のバージョン情報を取得します。

バージョンの配列には、 ICU が現在使っている Unicode 標準のバージョン情報が入っています。 たとえば、Unicode version 3.1.1 は、 [3, 1, 1, 0] という配列で表現されます。

パラメータ

この関数にはパラメータはありません。

戻り値

Unicode のバージョン番号が入った配列を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::getUnicodeVersion());
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  int(7)
  [1]=>
  int(0)
  [2]=>
  int(0)
  [3]=>
  int(0)
}

参考

  • IntlChar::charAge() - コードポイントの "age" を取得する


コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる

  • ≪ IntlChar::getUnicodeVersion
  • IntlChar::isalnum ≫
  • PHP Manual
  • IntlChar
  • コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる

IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる

説明

public static IntlChar::hasBinaryProperty(int|string $codepoint, int $property): ?bool

コードポイントに対応する、 バイナリ Unicode プロパティがあるかをチェックします。

Unicode、特にバージョン 3.2 では、 UnicodeData.txt に存在するオリジナルのもの以上に、 多くのプロパティを定義しています。

プロパティの API は、 Unicode Character Database (UCD) や Unicode Technical Reports (UTR) で定義されている Unicode プロパティを反映したものを意図しています。 プロパティの詳細については、 » http://www.unicode.org/ucd/ を参照ください。 Unicode プロパティの名前については、 UCD ファイル PropertyAliases.txt を参照ください。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

property

調べたい Unicode プロパティ (定数 IntlChar::PROPERTY_* を参照ください)。

戻り値

codepoint に対応するバイナリ Unicode プロパティに応じて、true または false を返します。 property が範囲外だったり、 Unicode のバージョンやコードポイントが、 バイナリプロパティのデータを全く持っていない場合も、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなプロパティの例

<?php
var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_ALPHABETIC));
var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_CASE_SENSITIVE));
var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_BIDI_MIRRORED));
var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_ALPHABETIC));
var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_CASE_SENSITIVE));
var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_BIDI_MIRRORED));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(false)
bool(false)
bool(true)

参考

  • IntlChar::getIntPropertyValue() - コードポイントに対応する、Unicode プロパティの値を取得する
  • IntlChar::getUnicodeVersion() - Unicode のバージョンを取得する


コードポイントが英数字であるかを調べる

  • ≪ IntlChar::hasBinaryProperty
  • IntlChar::isalpha ≫
  • PHP Manual
  • IntlChar
  • コードポイントが英数字であるかを調べる

IntlChar::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — コードポイントが英数字であるかを調べる

説明

public static IntlChar::isalnum(int|string $codepoint): ?bool

指定されたコードポイントが英数字(文字または数字)かを判定します。 一般カテゴリ "L" (letters) や "Nd" (decimal digit numbers) に属する場合に true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が英数字である場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isalnum("A"));
var_dump(IntlChar::isalnum("1"));
var_dump(IntlChar::isalnum("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

参考

  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる
  • ctype_alnum() - 英数字かどうかを調べる


コードポイントがアルファベットかを調べる

  • ≪ IntlChar::isalnum
  • IntlChar::isbase ≫
  • PHP Manual
  • IntlChar
  • コードポイントがアルファベットかを調べる

IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — コードポイントがアルファベットかを調べる

説明

public static IntlChar::isalpha(int|string $codepoint): ?bool

指定されたコードポイントがアルファベットかを判定します。 つまり、general categories "L" (letters) の場合に true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint がアルファベットの場合、 true を返します。そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isalpha("A"));
var_dump(IntlChar::isalpha("1"));
var_dump(IntlChar::isalpha("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)

参考

  • IntlChar::isalnum() - コードポイントが英数字であるかを調べる
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる
  • ctype_alpha() - 英字かどうかを調べる


コードポイントが基底文字に含まれるかを調べる

  • ≪ IntlChar::isalpha
  • IntlChar::isblank ≫
  • PHP Manual
  • IntlChar
  • コードポイントが基底文字に含まれるかを調べる

IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — コードポイントが基底文字に含まれるかを調べる

説明

public static IntlChar::isbase(int|string $codepoint): ?bool

指定されたコードポイントが基底文字に含まれるかを判定します。 一般カテゴリ "L" (letters), "N" (numbers), "Mc" (spacing combining marks), "Me" (enclosing marks) の場合に、true を返します。

注意:

これは、Unicode の chapter 3.5, conformance clause D13 にある定義とは異なります。 その定義は、 前の文字と視覚的に結合しない (Cn でない) 全ての文字を含み、 かつ control (Cc) や format (Cf) 文字を含まないものです。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が基底文字の場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isbase("A"));
var_dump(IntlChar::isbase("1"));
var_dump(IntlChar::isbase("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

参考

  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる


コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる

  • ≪ IntlChar::isbase
  • IntlChar::iscntrl ≫
  • PHP Manual
  • IntlChar
  • コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる

IntlChar::isblank

(PHP 7, PHP 8)

IntlChar::isblank — コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる

説明

public static IntlChar::isblank(int|string $codepoint): ?bool

指定されたコードポイントが "空白" または "水平方向の空白" 文字であるかを判定します。 これは、単語を視覚的に区切る文字のことです。

定義は、以下のようになります:

  • Unicode の White_Space 文字の場合に、true を返します。 但し、"vertical space controls" は除きます。 "vertical space controls" に該当するのは以下の文字です: U+000A (LF) U+000B (VT) U+000C (FF) U+000D (CR) U+0085 (NEL) U+2028 (LS) U+2029 (PS)
  • U+0009 (TAB) と、一般カテゴリ "Zs" (space separators) を持つ場合に、true を返します。 但し、 Zero Width Space (ZWSP, U+200B) は除きます。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepointが "空白" または "水平方向の空白" 文字である場合、true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isblank("A"));
var_dump(IntlChar::isblank(" "));
var_dump(IntlChar::isblank("\t"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)

参考

  • IntlChar::isspace() - コードポイントが、スペース文字であるかを調べる
  • IntlChar::isJavaSpaceChar() - コードポイントが Java におけるスペース文字であるかを調べる
  • IntlChar::isUWhiteSpace() - コードポイントが、White_Space プロパティを持つかを調べる
  • IntlChar::isWhitespace() - コードポイントが、ICU の空白文字であるかを調べる


コードポイントが制御文字かどうかを調べる

  • ≪ IntlChar::isblank
  • IntlChar::isdefined ≫
  • PHP Manual
  • IntlChar
  • コードポイントが制御文字かどうかを調べる

IntlChar::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — コードポイントが制御文字かどうかを調べる

説明

public static IntlChar::iscntrl(int|string $codepoint): ?bool

指定されたコードポイントが制御文字かを判定します。

制御文字は、以下に挙げるものです:

  • ISO 8-bit control character (U+0000..U+001f and U+007f..U+009f)
  • IntlChar::CHAR_CATEGORY_CONTROL_CHAR (Cc)
  • IntlChar::CHAR_CATEGORY_FORMAT_CHAR (Cf)
  • IntlChar::CHAR_CATEGORY_LINE_SEPARATOR (Zl)
  • IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR (Zp)

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が制御文字の場合に true を返します。 そうでない場合に、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::iscntrl("A"));
var_dump(IntlChar::iscntrl(" "));
var_dump(IntlChar::iscntrl("\n"));
var_dump(IntlChar::iscntrl("\u{200e}"));
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(true)
bool(true)

参考

  • IntlChar::isprint() - コードポイントが印字可能な文字かを調べる
  • IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT
  • ctype_cntrl() - 制御文字かどうかを調べる


コードポイントが定義されているかどうかを調べる

  • ≪ IntlChar::iscntrl
  • IntlChar::isdigit ≫
  • PHP Manual
  • IntlChar
  • コードポイントが定義されているかどうかを調べる

IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — コードポイントが定義されているかどうかを調べる

説明

public static IntlChar::isdefined(int|string $codepoint): ?bool

指定されたコードポイントが "定義されているか" どうかを判定します。 これは、一般的に文字が割り当てられているかを意味します。

"Cn" (other, not assigned) 以外の一般カテゴリの場合に true を返します。

注意:

文字でないコードポイント(例: U+FDD0) は "定義されていません" (Cn だからです) が、 サロゲートコードポイントは "定義されている" (Cs) ことに注意して下さい。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が 定義済みの文字である場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isdefined("A"));
var_dump(IntlChar::isdefined(" "));
var_dump(IntlChar::isdefined("\u{FDD0}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

参考

  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる
  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::isalnum() - コードポイントが英数字であるかを調べる
  • IntlChar::isupper() - コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
  • IntlChar::islower() - コードポイントが小文字かどうかを調べる
  • IntlChar::istitle() - コードポイントがタイトルケース文字であるかを調べる


コードポイントが、数字であるかを調べる

  • ≪ IntlChar::isdefined
  • IntlChar::isgraph ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、数字であるかを調べる

IntlChar::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — コードポイントが、数字であるかを調べる

説明

public static IntlChar::isdigit(int|string $codepoint): ?bool

指定されたコードポイントが、数字であるかを判定します。

戻り値が true になるのは、 general category "Nd" (decimal digit numbers) にある文字です。 これは、Unicode 4 から始まり、 Numeric_Type of Decimal であるかをチェックするのと同じです。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が数字である場合、true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isdigit("A"));
var_dump(IntlChar::isdigit("1"));
var_dump(IntlChar::isdigit("\t"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::isalnum() - コードポイントが英数字であるかを調べる
  • IntlChar::isxdigit() - コードポイントが、16進数の文字であるかを調べる
  • ctype_digit() - 数字かどうかを調べる


コードポイントが図形文字であるかを調べる

  • ≪ IntlChar::isdigit
  • IntlChar::isIDIgnorable ≫
  • PHP Manual
  • IntlChar
  • コードポイントが図形文字であるかを調べる

IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — コードポイントが図形文字であるかを調べる

説明

public static IntlChar::isgraph(int|string $codepoint): ?bool

指定されたコードポイントが図形文字 (印字可能だが、スペースを除く)であるかを判定します。

一般カテゴリ "Cc" (control codes), "Cf" (format controls), "Cs" (surrogates), "Cn" (unassigned), and "Z" (separators) を除く全ての文字について、true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が図形文字の場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isgraph("A"));
var_dump(IntlChar::isgraph("1"));
var_dump(IntlChar::isgraph("\u{2603}"));
var_dump(IntlChar::isgraph("\n"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(false)

参考

  • ctype_graph() - 空白以外の印字可能な文字かどうかを調べる


コードポイントが無視できる文字かを調べる

  • ≪ IntlChar::isgraph
  • IntlChar::isIDPart ≫
  • PHP Manual
  • IntlChar
  • コードポイントが無視できる文字かを調べる

IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — コードポイントが無視できる文字かを調べる

説明

public static IntlChar::isIDIgnorable(int|string $codepoint): ?bool

指定された文字が、 識別子の中で無視できる文字と見なすべきかを判定します。

一般カテゴリ "Cf" (format controls) または、 空白文字でない ISO で定義された制御文字 (U+0000..U+0008, U+000E..U+001B, U+007F..U+009F) の場合に、true を返します。

注意:

Unicode標準 は Cf (format controls) を無視することを推奨している点に注意して下さい。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が、 識別子の中で無視できる場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isIDIgnorable("A"));
var_dump(IntlChar::isIDIgnorable(" "));
var_dump(IntlChar::isIDIgnorable("\u{007F}"));
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(true)

参考

  • IntlChar::isIDStart() - コードポイントが識別子の最初の文字として使えるかを調べる
  • IntlChar::isIDPart() - コードポイントが識別子として使えるかを調べる
  • IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT


コードポイントが識別子として使えるかを調べる

  • ≪ IntlChar::isIDIgnorable
  • IntlChar::isIDStart ≫
  • PHP Manual
  • IntlChar
  • コードポイントが識別子として使えるかを調べる

IntlChar::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — コードポイントが識別子として使えるかを調べる

説明

public static IntlChar::isIDPart(int|string $codepoint): ?bool

指定された文字が識別子として使えるかを判定します。

一般カテゴリ "L" (letters), "Nl" (letter numbers), "Nd" (decimal digits), "Mc", "Mn" (combining marks), "Pc" (connecting punctuation), および u_isIDIgnorable(c) の場合に true　を返します。

注意:

これは、 Unicode の ID_Continue (IntlChar::PROPERTY_ID_CONTINUE) プロパティとほぼ同じですが、 IntlChar::isIDIgnorable() より小さい Cf を無視することを推奨している点は除きます。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が 識別子として使える場合 true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isIDPart("A"));
var_dump(IntlChar::isIDPart("$"));
var_dump(IntlChar::isIDPart("\n"));
var_dump(IntlChar::isIDPart("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)
bool(false)

参考

  • IntlChar::isIDIgnorable() - コードポイントが無視できる文字かを調べる
  • IntlChar::isIDStart() - コードポイントが識別子の最初の文字として使えるかを調べる
  • IntlChar::PROPERTY_ID_CONTINUE


コードポイントが識別子の最初の文字として使えるかを調べる

  • ≪ IntlChar::isIDPart
  • IntlChar::isISOControl ≫
  • PHP Manual
  • IntlChar
  • コードポイントが識別子の最初の文字として使えるかを調べる

IntlChar::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — コードポイントが識別子の最初の文字として使えるかを調べる

説明

public static IntlChar::isIDStart(int|string $codepoint): ?bool

指定されたコードポイントが、 Unicode の仕様 (The Unicode Standard, Version 3.0, chapter 5.16 Identifiers) に照らして識別子の最初の文字として使えるかを判定します。

一般カテゴリ "L" (letters) と "Nl" (letter numbers) に属する文字の場合に、 true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が識別子の最初の文字として使える場合、 true を返します。そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isIDStart("A"));
var_dump(IntlChar::isIDStart("$"));
var_dump(IntlChar::isIDStart("\n"));
var_dump(IntlChar::isIDStart("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)
bool(false)

参考

  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::isIDPart() - コードポイントが識別子として使えるかを調べる
  • IntlChar::PROPERTY_ID_START


コードポイントがISOで定義された制御文字であるかを調べる

  • ≪ IntlChar::isIDStart
  • IntlChar::isJavaIDPart ≫
  • PHP Manual
  • IntlChar
  • コードポイントがISOで定義された制御文字であるかを調べる

IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — コードポイントがISOで定義された制御文字であるかを調べる

説明

public static IntlChar::isISOControl(int|string $codepoint): ?bool

指定されたコードポイントが、 ISOで定義された制御文字であるかを判定します。

U+0000..U+001f または U+007f..U+009f (一般カテゴリ "Cc") の場合に true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint がISOで定義された制御文字の場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isISOControl(" "));
var_dump(IntlChar::isISOControl("\n"));
var_dump(IntlChar::isISOControl("\u{200e}"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

  • IntlChar::iscntrl() - コードポイントが制御文字かどうかを調べる


コードポイントが、Java の識別子として使えるかを調べる

  • ≪ IntlChar::isISOControl
  • IntlChar::isJavaIDStart ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、Java の識別子として使えるかを調べる

IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — コードポイントが、Java の識別子として使えるかを調べる

説明

public static IntlChar::isJavaIDPart(int|string $codepoint): ?bool

指定されたコードポイントが、Java の識別子として使えるかを判定します。

IntlChar::isIDPart() が true を返す場合に加え、 一般カテゴリ "Sc" (currency symbols) に属する文字の場合に true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が、 Java の識別子として使える場合 true を返します。 そうでない場合に、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isJavaIDPart("A"));
var_dump(IntlChar::isJavaIDPart("$"));
var_dump(IntlChar::isJavaIDPart("\n"));
var_dump(IntlChar::isJavaIDPart("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(false)

参考

  • IntlChar::isIDIgnorable() - コードポイントが無視できる文字かを調べる
  • IntlChar::isIDPart() - コードポイントが識別子として使えるかを調べる
  • IntlChar::isJavaIDStart() - コードポイントが Java の識別子の最初の文字として使えるかを調べる
  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる


コードポイントが Java の識別子の最初の文字として使えるかを調べる

  • ≪ IntlChar::isJavaIDPart
  • IntlChar::isJavaSpaceChar ≫
  • PHP Manual
  • IntlChar
  • コードポイントが Java の識別子の最初の文字として使えるかを調べる

IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — コードポイントが Java の識別子の最初の文字として使えるかを調べる

説明

public static IntlChar::isJavaIDStart(int|string $codepoint): ?bool

指定された文字が、 Java の識別子の最初の文字として使えるかを判定します。

IntlChar::isIDStart() が true を返す場合に加えて、 一般カテゴリ "Sc" (currency symbols) と "Pc" (connecting punctuation) に属する文字の場合に true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が、Java の識別子の最初の文字として使える場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isJavaIDStart("A"));
var_dump(IntlChar::isJavaIDStart("$"));
var_dump(IntlChar::isJavaIDStart("\n"));
var_dump(IntlChar::isJavaIDStart("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(false)

参考

  • IntlChar::isIDStart() - コードポイントが識別子の最初の文字として使えるかを調べる
  • IntlChar::isJavaIDPart() - コードポイントが、Java の識別子として使えるかを調べる
  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる


コードポイントが Java におけるスペース文字であるかを調べる

  • ≪ IntlChar::isJavaIDStart
  • IntlChar::islower ≫
  • PHP Manual
  • IntlChar
  • コードポイントが Java におけるスペース文字であるかを調べる

IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — コードポイントが Java におけるスペース文字であるかを調べる

説明

public static IntlChar::isJavaSpaceChar(int|string $codepoint): ?bool

指定されたコードポイントが、 Java におけるスペース文字であるかを判定します。

一般カテゴリ "Z" (separators) に属する文字の場合に true を返します。 これは、制御文字 (例: TAB や Line Feed) を含みません。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が Java におけるスペース文字である場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isJavaSpaceChar("A"));
var_dump(IntlChar::isJavaSpaceChar(" "));
var_dump(IntlChar::isJavaSpaceChar("\n"));
var_dump(IntlChar::isJavaSpaceChar("\t"));
var_dump(IntlChar::isJavaSpaceChar("\u{00A0}"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)
bool(false)
bool(true)

参考

  • IntlChar::isspace() - コードポイントが、スペース文字であるかを調べる
  • IntlChar::isWhitespace() - コードポイントが、ICU の空白文字であるかを調べる
  • IntlChar::isUWhiteSpace() - コードポイントが、White_Space プロパティを持つかを調べる


コードポイントが小文字かどうかを調べる

  • ≪ IntlChar::isJavaSpaceChar
  • IntlChar::isMirrored ≫
  • PHP Manual
  • IntlChar
  • コードポイントが小文字かどうかを調べる

IntlChar::islower

(PHP 7, PHP 8)

IntlChar::islower — コードポイントが小文字かどうかを調べる

説明

public static IntlChar::islower(int|string $codepoint): ?bool

指定されたコードポイントが、一般カテゴリ "Ll" (小文字) に属するかを判定します。

注意:

このメソッドのやり方だと、 小文字ではあるものの、違うカテゴリに属する文字を見逃してしまいます。 それらも含めて小文字かどうかを判定するには、 IntlChar::isULowercase() を使って下さい。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が が 一般カテゴリ "Ll" に属する小文字である場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::islower("A"));
var_dump(IntlChar::islower("a"));
var_dump(IntlChar::islower("Φ"));
var_dump(IntlChar::islower("φ"));
var_dump(IntlChar::islower("1"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)
bool(true)
bool(false)

参考

  • IntlChar::isupper() - コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
  • IntlChar::istitle() - コードポイントがタイトルケース文字であるかを調べる
  • IntlChar::tolower() - Unicode 文字を小文字にする
  • IntlChar::toupper() - Unicode 文字を大文字にする
  • IntlChar::PROPERTY_LOWERCASE
  • ctype_lower() - 小文字かどうかを調べる


コードポイントが Bidi_Mirrored プロパティを持つかを調べる

  • ≪ IntlChar::islower
  • IntlChar::isprint ≫
  • PHP Manual
  • IntlChar
  • コードポイントが Bidi_Mirrored プロパティを持つかを調べる

IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — コードポイントが Bidi_Mirrored プロパティを持つかを調べる

説明

public static IntlChar::isMirrored(int|string $codepoint): ?bool

コードポイントが Bidi_Mirrored プロパティを持つかを判定します。

このプロパティは、右から左に読む場合に使われ、 "左右を反転した" グリフを表示するために必要です。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が Bidi_Mirrored プロパティを持つ場合に true を返します。 そうでない場合に、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isMirrored("A"));
var_dump(IntlChar::isMirrored("<"));
var_dump(IntlChar::isMirrored("("));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)

参考

  • IntlChar::charMirror() - コードポイントの "鏡文字" を取得する
  • IntlChar::PROPERTY_BIDI_MIRRORED


コードポイントが印字可能な文字かを調べる

  • ≪ IntlChar::isMirrored
  • IntlChar::ispunct ≫
  • PHP Manual
  • IntlChar
  • コードポイントが印字可能な文字かを調べる

IntlChar::isprint

(PHP 7, PHP 8)

IntlChar::isprint — コードポイントが印字可能な文字かを調べる

説明

public static IntlChar::isprint(int|string $codepoint): ?bool

指定されたコードポイントが、印字可能な文字かを判定します。

一般カテゴリ "C" (controls) 以外の文字の場合、true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が印字可能な文字の場合、true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isprint("A"));
var_dump(IntlChar::isprint(" "));
var_dump(IntlChar::isprint("\n"));
var_dump(IntlChar::isprint("\u{200e}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(false)

参考

  • IntlChar::iscntrl() - コードポイントが制御文字かどうかを調べる
  • IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT
  • ctype_print() - 印字可能な文字かどうかを調べる


コードポイントが句読点の文字かどうかを調べる

  • ≪ IntlChar::isprint
  • IntlChar::isspace ≫
  • PHP Manual
  • IntlChar
  • コードポイントが句読点の文字かどうかを調べる

IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — コードポイントが句読点の文字かどうかを調べる

説明

public static IntlChar::ispunct(int|string $codepoint): ?bool

指定されたコードポイントが句読点の文字かどうかを判定します。

一般カテゴリ "P" (punctuation) を持つ文字の場合に true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が句読点の文字の場合、 true を返します。そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::ispunct("."));
var_dump(IntlChar::ispunct(","));
var_dump(IntlChar::ispunct("\n"));
var_dump(IntlChar::ispunct("$"));

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(false)

参考

  • ctype_punct() - 空白、英数字以外の出力可能な文字かどうかを調べる


コードポイントが、スペース文字であるかを調べる

  • ≪ IntlChar::ispunct
  • IntlChar::istitle ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、スペース文字であるかを調べる

IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — コードポイントが、スペース文字であるかを調べる

説明

public static IntlChar::isspace(int|string $codepoint): ?bool

指定された文字が、スペース文字かどうかを判定します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint がスペース文字である場合は true を返します。 そうでない場合は、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isspace("A"));
var_dump(IntlChar::isspace(" "));
var_dump(IntlChar::isspace("\n"));
var_dump(IntlChar::isspace("\t"));
var_dump(IntlChar::isspace("\u{00A0}"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)
bool(true)
bool(true)

参考

  • IntlChar::isJavaSpaceChar() - コードポイントが Java におけるスペース文字であるかを調べる
  • IntlChar::isWhitespace() - コードポイントが、ICU の空白文字であるかを調べる
  • IntlChar::isUWhiteSpace() - コードポイントが、White_Space プロパティを持つかを調べる
  • ctype_space() - 空白文字かどうか調べる


コードポイントがタイトルケース文字であるかを調べる

  • ≪ IntlChar::isspace
  • IntlChar::isUAlphabetic ≫
  • PHP Manual
  • IntlChar
  • コードポイントがタイトルケース文字であるかを調べる

IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — コードポイントがタイトルケース文字であるかを調べる

説明

public static IntlChar::istitle(int|string $codepoint): ?bool

コードポイントがタイトルケース文字であるかを判定します。

一般カテゴリ "Lt" (タイトルケース文字) である場合に、 true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint がタイトルケース文字である場合に、 true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
// Latin Capital Letter Dz with Caron U+01C4
var_dump(IntlChar::istitle("?"));
// Latin Capital Letter D with Small Letter Z with Caron U+01C5
var_dump(IntlChar::istitle("?"));
// Latin Small Letter Dz with Caron U+01C6
var_dump(IntlChar::istitle("?"));

// Greek Capital Letter Alpha with Prosgegrammeni U+1FBC
var_dump(IntlChar::istitle("?"));
// Greek Small Letter Alpha with Ypogegrammeni U+1FB3
var_dump(IntlChar::istitle("?"));
// Greek Capital Letter Alpha U+0391
var_dump(IntlChar::istitle("Α"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)
bool(true)
bool(false)
bool(false)

参考

  • IntlChar::isupper() - コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
  • IntlChar::islower() - コードポイントが小文字かどうかを調べる
  • IntlChar::totitle() - Unicode 文字をタイトルケースにする


コードポイントが、Alphabetic プロパティを持つかを調べる

  • ≪ IntlChar::istitle
  • IntlChar::isULowercase ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、Alphabetic プロパティを持つかを調べる

IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — コードポイントが、Alphabetic プロパティを持つかを調べる

説明

public static IntlChar::isUAlphabetic(int|string $codepoint): ?bool

コードポイントが、Alphabetic プロパティを持つかを調べます。

これは、 IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC) と同等です。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が、Alphabetic プロパティを持つ場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isUAlphabetic("A"));
var_dump(IntlChar::isUAlphabetic("1"));
var_dump(IntlChar::isUAlphabetic("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)

参考

  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる
  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::PROPERTY_ALPHABETIC


コードポイントが小文字のUnicodeプロパティを持つかを調べる

  • ≪ IntlChar::isUAlphabetic
  • IntlChar::isupper ≫
  • PHP Manual
  • IntlChar
  • コードポイントが小文字のUnicodeプロパティを持つかを調べる

IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — コードポイントが小文字のUnicodeプロパティを持つかを調べる

説明

public static IntlChar::isULowercase(int|string $codepoint): ?bool

コードポイントが小文字のUnicodeプロパティを持つかを調べます。

これは、 IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE) と同等です。

注意:

これは、IntlChar::islower() とは異なり、 より多くの文字で true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が 小文字のUnicodeプロパティを持つ場合に true を返します。 そうでない場合は、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isULowercase("A"));
var_dump(IntlChar::isULowercase("a"));
var_dump(IntlChar::isULowercase("Φ"));
var_dump(IntlChar::isULowercase("φ"));
var_dump(IntlChar::isULowercase("1"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)
bool(true)
bool(false)

参考

  • IntlChar::islower() - コードポイントが小文字かどうかを調べる
  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::PROPERTY_LOWERCASE


コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する

  • ≪ IntlChar::isULowercase
  • IntlChar::isUUppercase ≫
  • PHP Manual
  • IntlChar
  • コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する

IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する

説明

public static IntlChar::isupper(int|string $codepoint): ?bool

指定されたコードポイントが、 一般カテゴリ "Lu" (大文字) に属するかを判定します。

注意:

このメソッドのやり方だと、 大文字ではあるものの、違うカテゴリに属する文字を見逃してしまいます。 それらも含めて大文字かどうかを判定するには、 IntlChar::isUUppercase() を使って下さい。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が 一般カテゴリ "Lu" に属する大文字である場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isupper("A"));
var_dump(IntlChar::isupper("a"));
var_dump(IntlChar::isupper("Φ"));
var_dump(IntlChar::isupper("φ"));
var_dump(IntlChar::isupper("1"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)
bool(false)
bool(false)

参考

  • IntlChar::islower() - コードポイントが小文字かどうかを調べる
  • IntlChar::istitle() - コードポイントがタイトルケース文字であるかを調べる
  • IntlChar::tolower() - Unicode 文字を小文字にする
  • IntlChar::toupper() - Unicode 文字を大文字にする
  • IntlChar::PROPERTY_UPPERCASE
  • ctype_upper() - 大文字かどうか調べる


コードポイントが大文字のUnicodeプロパティを持つかを調べる

  • ≪ IntlChar::isupper
  • IntlChar::isUWhiteSpace ≫
  • PHP Manual
  • IntlChar
  • コードポイントが大文字のUnicodeプロパティを持つかを調べる

IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — コードポイントが大文字のUnicodeプロパティを持つかを調べる

説明

public static IntlChar::isUUppercase(int|string $codepoint): ?bool

コードポイントが大文字のUnicodeプロパティを持つかを判定します。

これは、 IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE) と同等です。

注意:

これは、IntlChar::isupper() とは異なり、 より多くの文字で true を返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が 大文字のUnicodeプロパティを持つ場合に true を返します。 そうでない場合は、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isUUppercase("A"));
var_dump(IntlChar::isUUppercase("a"));
var_dump(IntlChar::isUUppercase("Φ"));
var_dump(IntlChar::isUUppercase("φ"));
var_dump(IntlChar::isUUppercase("1"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)
bool(false)
bool(false)

参考

  • IntlChar::isupper() - コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::PROPERTY_UPPERCASE


コードポイントが、White_Space プロパティを持つかを調べる

  • ≪ IntlChar::isUUppercase
  • IntlChar::isWhitespace ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、White_Space プロパティを持つかを調べる

IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — コードポイントが、White_Space プロパティを持つかを調べる

説明

public static IntlChar::isUWhiteSpace(int|string $codepoint): ?bool

コードポイントが、White_Space プロパティを持つかを調べます。

これは、 IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE) と同等です。

注意:

これは、 IntlChar::isspace() や IntlChar::isWhitespace() とは異なります。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

コードポイントが、White_Space プロパティを持つ場合に true を返します。 そうでない場合、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isUWhiteSpace("A"));
var_dump(IntlChar::isUWhiteSpace(" "));
var_dump(IntlChar::isUWhiteSpace("\n"));
var_dump(IntlChar::isUWhiteSpace("\t"));
var_dump(IntlChar::isUWhiteSpace("\u{00A0}"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)
bool(true)
bool(true)

参考

  • IntlChar::isspace() - コードポイントが、スペース文字であるかを調べる
  • IntlChar::isWhitespace() - コードポイントが、ICU の空白文字であるかを調べる
  • IntlChar::isJavaSpaceChar() - コードポイントが Java におけるスペース文字であるかを調べる
  • IntlChar::hasBinaryProperty() - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
  • IntlChar::PROPERTY_WHITE_SPACE


コードポイントが、ICU の空白文字であるかを調べる

  • ≪ IntlChar::isUWhiteSpace
  • IntlChar::isxdigit ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、ICU の空白文字であるかを調べる

IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — コードポイントが、ICU の空白文字であるかを調べる

説明

public static IntlChar::isWhitespace(int|string $codepoint): ?bool

コードポイントが、ICU の空白文字であるかを判定します。

以下の条件のうちひとつでも満たす場合のみ、 文字は ICU の空白文字であると見なされます:

  • Unicode の区切り文字 (categories "Z" = "Zs", "Zl", "Zp" の場合) であるが、 同時に ノーブレークスペース (U+00A0 NBSP, U+2007 Figure Space, U+202F Narrow NBSP) でもないこと。
  • U+0009 HORIZONTAL TABULATION の場合
  • U+000A LINE FEED の場合
  • U+000B VERTICAL TABULATION の場合
  • U+000C FORM FEED の場合
  • U+000D CARRIAGE RETURN の場合
  • U+001C FILE SEPARATOR の場合
  • U+001D GROUP SEPARATOR の場合
  • U+001E RECORD SEPARATOR の場合
  • U+001F UNIT SEPARATOR の場合

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が、ICU の空白文字である場合は true を返します。 そうでない場合は、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::iswhitespace("A"));
var_dump(IntlChar::iswhitespace(" "));
var_dump(IntlChar::iswhitespace("\n"));
var_dump(IntlChar::iswhitespace("\t"));
var_dump(IntlChar::iswhitespace("\u{00A0}"));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)
bool(true)
bool(false)

参考

  • IntlChar::isspace() - コードポイントが、スペース文字であるかを調べる
  • IntlChar::isJavaSpaceChar() - コードポイントが Java におけるスペース文字であるかを調べる
  • IntlChar::isUWhiteSpace() - コードポイントが、White_Space プロパティを持つかを調べる


コードポイントが、16進数の文字であるかを調べる

  • ≪ IntlChar::isWhitespace
  • IntlChar::ord ≫
  • PHP Manual
  • IntlChar
  • コードポイントが、16進数の文字であるかを調べる

IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — コードポイントが、16進数の文字であるかを調べる

説明

public static IntlChar::isxdigit(int|string $codepoint): ?bool

指定されたコードポイントが、16進数の文字であるかを判定します。

戻り値が true になるのは、 general category "Nd" (decimal digit numbers) にある文字か、 ASCII と 全角ASCII の a-f および A-F にある文字です。 (つまり、コードポイント 0041..0046, 0061..0066, FF21..FF26, FF41..FF46 に入る文字です)

この関数の動作は、IntlChar::digit($codepoint, 16) >= 0 と同等です。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

codepoint が16進文字である場合は、true を返します。 そうでない場合は、false を返します。 失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::isxdigit("A"));
var_dump(IntlChar::isxdigit("1"));
var_dump(IntlChar::isxdigit("\u{2603}"));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

注意

注意:

16進数の文字のうち、ASCII 文字の範囲に定義を絞るには、以下のようにします:

<?php
$isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
?>

参考

  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる
  • ctype_xdigit() - 16 進数を表す文字かどうかを調べる


文字に対応する Unicode コードポイントを返す

  • ≪ IntlChar::isxdigit
  • IntlChar::tolower ≫
  • PHP Manual
  • IntlChar
  • 文字に対応する Unicode コードポイントを返す

IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — 文字に対応する Unicode コードポイントを返す

説明

public static IntlChar::ord(int|string $character): ?int

指定された文字の Unicode コードポイントを返します。

このメソッドは、IntlChar::chr() を補完するものです。

パラメータ

character

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

Unicode のコードポイントを整数値で返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::ord("A"));
var_dump(IntlChar::ord(" "));
var_dump(IntlChar::ord("\u{2603}"));
?>

上の例の出力は以下となります。

int(65)
int(32)
int(9731)

参考

  • IntlChar::chr() - コードポイント値に対応する、Unicode 文字を返す
  • mb_ord() - 文字の Unicode コードポイントを取得する
  • ord() - 文字列の先頭バイトを、0 から 255 までの値に変換する


Unicode 文字を小文字にする

  • ≪ IntlChar::ord
  • IntlChar::totitle ≫
  • PHP Manual
  • IntlChar
  • Unicode 文字を小文字にする

IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Unicode 文字を小文字にする

説明

public static IntlChar::tolower(int|string $codepoint): int|string|null

指定した文字を、同等の小文字にマップします。 同等の小文字が存在しない場合、指定された文字そのものを返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

存在する場合に、コードポイントの Simple_Lowercase_Mapping の値を返します。 存在しない場合は、コードポイントそのものを返します。 失敗した場合は、null を返します。

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::tolower("A"));
var_dump(IntlChar::tolower("a"));
var_dump(IntlChar::tolower("Φ"));
var_dump(IntlChar::tolower("φ"));
var_dump(IntlChar::tolower("1"));
var_dump(IntlChar::tolower(ord("A")));
var_dump(IntlChar::tolower(ord("a")));
?>

上の例の出力は以下となります。

string(1) "a"
string(1) "a"
string(2) "φ"
string(2) "φ"
string(1) "1"
int(97)
int(97)

参考

  • IntlChar::totitle() - Unicode 文字をタイトルケースにする
  • IntlChar::toupper() - Unicode 文字を大文字にする
  • mb_strtolower() - 文字列を小文字にする


Unicode 文字をタイトルケースにする

  • ≪ IntlChar::tolower
  • IntlChar::toupper ≫
  • PHP Manual
  • IntlChar
  • Unicode 文字をタイトルケースにする

IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Unicode 文字をタイトルケースにする

説明

public static IntlChar::totitle(int|string $codepoint): int|string|null

指定した文字を、同等のタイトルケースにマップします。 同等のタイトルケースが存在しない場合、指定された文字そのものを返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

存在する場合に、コードポイントの Simple_Titlecase_Mapping の値を返します。 存在しない場合は、コードポイントそのものを返します。 失敗した場合は、null を返します。

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::totitle("?"));
var_dump(IntlChar::totitle("?"));
var_dump(IntlChar::totitle("Φ"));
var_dump(IntlChar::totitle("φ"));
var_dump(IntlChar::totitle("1"));
var_dump(IntlChar::totitle("?");
var_dump(IntlChar::totitle(ord("A")));
?>

上の例の出力は以下となります。

string(1) "?"
string(1) "?"
string(2) "Φ"
string(2) "φ"
string(1) "1"
string(1) "?"
int(65)

参考

  • IntlChar::tolower() - Unicode 文字を小文字にする
  • IntlChar::toupper() - Unicode 文字を大文字にする
  • IntlChar::istitle() - コードポイントがタイトルケース文字であるかを調べる
  • mb_convert_case() - 文字列に対してケースフォールディングを行う


Unicode 文字を大文字にする

  • ≪ IntlChar::totitle
  • IntlException ≫
  • PHP Manual
  • IntlChar
  • Unicode 文字を大文字にする

IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Unicode 文字を大文字にする

説明

public static IntlChar::toupper(int|string $codepoint): int|string|null

指定した文字を、同等の大文字にマップします。 同等の大文字が存在しない場合、指定された文字そのものを返します。

パラメータ

codepoint

コードポイントを表す int 型の値 (例: U+2603 SNOWMAN を表す 0x2603)、あるいは UTF-8 文字列としてエンコードされた文字 (例: "\u{2603}")。

戻り値

存在する場合に、コードポイントの Simple_Uppercase_Mapping の値を返します。 存在しない場合は、コードポイントそのものを返します。

戻り値の型は int になります。ただし、コードポイントを UTF-8 文字列で渡した場合は別で、その場合の返り値の型は文字列になります。失敗した場合は、null を返します。

例

例1 さまざまなコードポイントの例

<?php
var_dump(IntlChar::toupper("A"));
var_dump(IntlChar::toupper("a"));
var_dump(IntlChar::toupper("Φ"));
var_dump(IntlChar::toupper("φ"));
var_dump(IntlChar::toupper("1"));
var_dump(IntlChar::toupper(ord("A")));
var_dump(IntlChar::toupper(ord("a")));
?>

上の例の出力は以下となります。

string(1) "A"
string(1) "A"
string(2) "Φ"
string(2) "Φ"
string(1) "1"
int(65)
int(65)

参考

  • IntlChar::tolower() - Unicode 文字を小文字にする
  • IntlChar::totitle() - Unicode 文字をタイトルケースにする
  • mb_strtoupper() - 文字列を大文字にする


intl のエラー用の例外クラス

(PHP 5 > 5.5.0, PHP 7, PHP 8, PECL intl > 3.0.0a1)

はじめに

このクラスは、intl 関数の内部でエラーが発生したときに例外を生成するために使います。 例外が生成されるのは、intl.use_exceptions が有効な場合だけです。

クラス概要

class IntlException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


IntlIterator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

このクラスは、intl 拡張モジュール全体を通じて、 拡張モジュールが提供する他のいかなるオブジェクトでも認識できない イテレータを表現します。 言語構造 foreach によって内部的に使われる独自のイテレータは、 オブジェクトからのみ取得できます。よって、 このクラスのインスタンスは、 この内部オブジェクトが取得できるフックを提供する役割を果たします。 便宜のため、 このクラスは Iterator インターフェイスも実装しています。 これによって、 値の集合をこのインターフェイスのメソッドを使って走査することができます。 これらのメソッドも、 foreach に提供される内部的なイテレータオブジェクトも、 同じ状態 (つまり、イテレータの位置と現在の値) を持っています。

このクラスのサブクラスは、 もっと豊かな機能を提供しています。

クラス概要

class IntlIterator implements Iterator {
/* メソッド */
public current(): mixed
public key(): mixed
public next(): void
public rewind(): void
public valid(): bool
}

目次

  • IntlIterator::current — 現在の要素を取得する
  • IntlIterator::key — 現在のキーを取得する
  • IntlIterator::next — 次の要素に進む
  • IntlIterator::rewind — イテレータを最初の要素に戻す
  • IntlIterator::valid — 現在の位置が有効かを調べる


現在の要素を取得する

  • ≪ IntlIterator
  • IntlIterator::key ≫
  • PHP Manual
  • IntlIterator
  • 現在の要素を取得する

IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — 現在の要素を取得する

説明

public IntlIterator::current(): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


現在のキーを取得する

  • ≪ IntlIterator::current
  • IntlIterator::next ≫
  • PHP Manual
  • IntlIterator
  • 現在のキーを取得する

IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — 現在のキーを取得する

説明

public IntlIterator::key(): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


次の要素に進む

  • ≪ IntlIterator::key
  • IntlIterator::rewind ≫
  • PHP Manual
  • IntlIterator
  • 次の要素に進む

IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — 次の要素に進む

説明

public IntlIterator::next(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


イテレータを最初の要素に戻す

  • ≪ IntlIterator::next
  • IntlIterator::valid ≫
  • PHP Manual
  • IntlIterator
  • イテレータを最初の要素に戻す

IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — イテレータを最初の要素に戻す

説明

public IntlIterator::rewind(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


現在の位置が有効かを調べる

  • ≪ IntlIterator::rewind
  • 国際化 関数 ≫
  • PHP Manual
  • IntlIterator
  • 現在の位置が有効かを調べる

IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — 現在の位置が有効かを調べる

説明

public IntlIterator::valid(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


国際化 関数

目次

  • intl_error_name — 指定したエラーコードに対応する名前を取得する
  • intl_get_error_code — 直近のエラーコードを取得する
  • intl_get_error_message — 直近のエラーの説明を取得する
  • intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる


指定したエラーコードに対応する名前を取得する

  • ≪ 国際化 関数
  • intl_get_error_code ≫
  • PHP Manual
  • 国際化 関数
  • 指定したエラーコードに対応する名前を取得する

intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — 指定したエラーコードに対応する名前を取得する

説明

intl_error_name(int $errorCode): string

ICU のエラーコード名を返します。

パラメータ

errorCode

ICU のエラーコード。

戻り値

エラーコード定数と同じ名前の文字列を返します。

例

例1 intl_error_name() の例

<?php
$coll = collator_create( 'en_RU' );
$err_code = collator_get_error_code( $coll );

printf( "Symbolic name for %d is %s\n.", $err_code, intl_error_name( $err_code ) );
?>

上の例の出力は、 たとえば以下のようになります。

Symbolic name for -128 is U_USING_FALLBACK_WARNING.

参考

  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_get_error_message() - 直近のエラーの説明を取得する


直近のエラーコードを取得する

  • ≪ intl_error_name
  • intl_get_error_message ≫
  • PHP Manual
  • 国際化 関数
  • 直近のエラーコードを取得する

intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — 直近のエラーコードを取得する

説明

intl_get_error_code(): int

staticメソッドを実行した場合など、 エラーコードを取得するオブジェクトが存在しない場合のエラー処理に便利です。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の API 関数のコールが返すエラーコードを返します。

例

例1 intl_get_error_code() の例

<?php
$coll = collator_create( '<bad_param>' );
if( !$coll ) {
handle_error( intl_get_error_code() );
}
?>

参考

  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • intl_error_name() - 指定したエラーコードに対応する名前を取得する
  • intl_get_error_message() - 直近のエラーの説明を取得する
  • collator_get_error_code() - collator の直近のエラーコードを取得する
  • numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する


直近のエラーの説明を取得する

  • ≪ intl_get_error_code
  • intl_is_failure ≫
  • PHP Manual
  • 国際化 関数
  • 直近のエラーの説明を取得する

intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — 直近のエラーの説明を取得する

説明

intl_get_error_message(): string

直近の国際化関数のコールによるエラーメッセージを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の API 関数のコールで発生したエラーの説明を返します。

例

例1 intl_get_error_message() の例

<?php
if( Collator::getAvailableLocales() === false ) {
show_error( intl_get_error_message() );
}
?>

参考

  • intl_error_name() - 指定したエラーコードに対応する名前を取得する
  • intl_get_error_code() - 直近のエラーコードを取得する
  • intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる
  • collator_get_error_message() - collator の直近のエラーコードのテキストを取得する
  • numfmt_get_error_message() - フォーマッタの直近のエラーメッセージを取得する


指定したエラーコードが失敗を表すかどうかを調べる

  • ≪ intl_get_error_message
  • マルチバイト文字列 ≫
  • PHP Manual
  • 国際化 関数
  • 指定したエラーコードが失敗を表すかどうかを調べる

intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる

説明

intl_is_failure(int $errorCode): bool

パラメータ

errorCode

intl_get_error_code() や collator_get_error_code() が返す値。

戻り値

そのコードが何らかの失敗を意味する場合に true、 成功あるいは警告を意味する場合に false を返します。

例

例1 intl_is_failure() example

<?php
function check( $err_code )
{
var_export( intl_is_failure( $err_code ) );
echo "\n";
}

check( U_ZERO_ERROR );
check( U_USING_FALLBACK_WARNING );
check( U_ILLEGAL_ARGUMENT_ERROR );
?>

上の例の出力は、 たとえば以下のようになります。

false
false
true

参考

  • intl_get_error_code() - 直近のエラーコードを取得する
  • collator_get_error_code() - collator の直近のエラーコードを取得する
  • Collator-getErrorCode()


マルチバイト文字列

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • サポートされるエンコーディングの概要
  • 日本語のマルチバイト文字に関する基本事項
  • HTTP 入出力
  • サポートされる文字エンコーディング
  • 関数のオーバーロード機能
  • PHP の文字エンコーディングに関する要件
  • マルチバイト文字列 関数
    • mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる
    • mb_chr — Unicode のコードポイントに対応する文字を返す
    • mb_convert_case — 文字列に対してケースフォールディングを行う
    • mb_convert_encoding — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
    • mb_convert_kana — カナを("全角かな"、"半角かな"等に)変換する
    • mb_convert_variables — 変数の文字コードを変換する
    • mb_decode_mimeheader — MIME ヘッダフィールドの文字列をデコードする
    • mb_decode_numericentity — HTML 数値エンティティを文字にデコードする
    • mb_detect_encoding — 文字エンコーディングを検出する
    • mb_detect_order — 文字エンコーディング検出順序を設定あるいは取得する
    • mb_encode_mimeheader — MIMEヘッダの文字列をエンコードする
    • mb_encode_numericentity — 文字を HTML 数値エンティティにエンコードする
    • mb_encoding_aliases — 既知のエンコーディング・タイプのエイリアスを取得
    • mb_ereg — マルチバイト対応の正規表現マッチ
    • mb_ereg_match — マルチバイト文字列が正規表現に一致するか調べる
    • mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う
    • mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う
    • mb_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる
    • mb_ereg_search_getpos — 次の正規表現検索を開始する位置を取得する
    • mb_ereg_search_getregs — マルチバイト文字列が正規表現に一致する部分があるか調べる
    • mb_ereg_search_init — マルチバイト正規表現検索用の文字列と正規表現を設定する
    • mb_ereg_search_pos — 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す
    • mb_ereg_search_regs — 指定したマルチバイト文字列が正規表現に一致する部分を取得する
    • mb_ereg_search_setpos — 次の正規表現検索を開始する位置を設定する
    • mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ
    • mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う
    • mb_get_info — mbstring の内部設定値を取得する
    • mb_http_input — HTTP 入力文字エンコーディングを検出する
    • mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する
    • mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する
    • mb_language — 現在の言語を設定あるいは取得する
    • mb_list_encodings — サポートするすべてのエンコーディングの配列を返す
    • mb_ord — 文字の Unicode コードポイントを取得する
    • mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数
    • mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する
    • mb_preferred_mime_name — MIME 文字設定を文字列で得る
    • mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
    • mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する
    • mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える
    • mb_send_mail — エンコード変換を行ってメールを送信する
    • mb_split — マルチバイト文字列を正規表現により分割する
    • mb_str_pad — マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める
    • mb_str_split — マルチバイト文字列を受取り、文字の配列を返す
    • mb_strcut — 文字列の一部を得る
    • mb_strimwidth — 指定した幅で文字列を丸める
    • mb_stripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
    • mb_stristr — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
    • mb_strlen — 文字列の長さを得る
    • mb_strpos — 文字列の中に指定した文字列が最初に現れる位置を見つける
    • mb_strrchr — 別の文字列の中で、ある文字が最後に現れる場所を見つける
    • mb_strrichr — 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す
    • mb_strripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す
    • mb_strrpos — 文字列の中に指定した文字列が最後に現れる位置を見つける
    • mb_strstr — 文字列の中で、指定した文字列が最初に現れる位置を見つける
    • mb_strtolower — 文字列を小文字にする
    • mb_strtoupper — 文字列を大文字にする
    • mb_strwidth — 文字列の幅を返す
    • mb_substitute_character — 置換文字を設定あるいは取得する
    • mb_substr — 文字列の一部を得る
    • mb_substr_count — 部分文字列の出現回数を数える


はじめに

全ての文字をシングルバイトで一対一表現可能な言語は数多くありますが、 文字表現に単一バイトによる表現範囲を越えるほど多くの文字を必要とする言語も多くあります (1 バイトは 8 ビットから構成されます。各ビットには、1 あるいは 0 の 2 種類の値しか保持できません。そのため、単一のバイトで表すことのできる値は 256 (2 の 8 乗) 種類までとなります)。 マルチバイト文字のエンコーディング法は、 256 を越える文字を通常のビット単位の符号化システムで表現するために開発されました。

マルチバイトエンコーディングで符号化された文字列を (trim, split, splice などで) 処理する際、こうしたエンコーディングでは二つ以上の連続するバイトが 一つの文字を表す可能性があるため、特別な関数を使用する必要があります。 マルチバイトに対応しない文字列関数を文字列に適用した場合、 マルチバイト文字の先頭バイトまたは終了バイトを検出できずに文字列を壊し、 多くの場合には元の意味を失わせてしまう可能性があります。

mbstring はマルチバイト対応の文字列関数を提供し、 PHP でマルチバイトエンコーディングを処理することを容易にします。 それに加えて、mbstring は、 可能な範囲での文字エンコーディングの変換を処理します。 mbstring は UTF-8 や UCS-2 のような Unicode に基づくエンコーディングや多くのシングルバイトエンコーディングを処理するのに便利です (サポートされる文字エンコーディング に一覧があります)。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • マルチバイト文字列
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

mbstring は拡張モジュールです。つまり、デフォルトでは 有効にならないということです。 configure スクリプトでモジュールを有効にする必要が あります。詳細は、インストールの 節を参照ください。

mbstring モジュールに関係する設定オプションは 以下のとおりです。

  • --enable-mbstring: mbstring 関数を有効にします。このオプションは、 mbstring 関数を利用するために必要です。

    mbstring 拡張モジュールを使用するためには、 libmbflライブラリが必要です。 libmbflは、mbstring 拡張モジュールにバンドルされています。PHP 7.3.0 より前では、 libmbfl がシステムにすでにインストール済みの場合、 --with-libmbfl[=DIR] を指定して インストール済みのライブラリを使用します。

  • --disable-mbregex : マルチバイト対応の正規表現関数を無効にします。

    Oniguruma は、 マルチバイト文字をサポートする正規表現関数のために必要です。 PHP 7.4.0 以降では、libonig ライブラリを検知するのに pkg-config を使うようになりました。 PHP 7.4.0 より前のバージョンでは、 Oniguruma は mbstring にバンドルされていましたが、 既に libonig がシステムにインストール済みの場合、 --with-onig[=DIR] を指定して インストール済みのライブラリを使用することができました。

    --disable-mbregex-backtrack を指定して、マルチバイト正規表現バックトラックチェックを無効にすることができます。


実行時設定

php.ini の設定により動作が変化します。

mbstring 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mbstring.language | "neutral" | INI_ALL |
mbstring.detect_order | NULL | INI_ALL |
mbstring.http_input | "pass" | INI_ALL | 非推奨になりました。
mbstring.http_output | "pass" | INI_ALL | 非推奨になりました。
mbstring.internal_encoding | NULL | INI_ALL | 非推奨になりました。
mbstring.substitute_character | NULL | INI_ALL |
mbstring.func_overload | "0" | INI_SYSTEM | PHP 7.2.0 で非推奨になり、PHP 8.0.0 で削除されました。
mbstring.encoding_translation | "0" | INI_PERDIR |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | INI_ALL |
mbstring.strict_detection | "0" | INI_ALL |
mbstring.regex_retry_limit | "1000000" | INI_ALL | PHP 7.4.0 以降で利用可能です。
mbstring.regex_stack_limit | "100000" | INI_ALL | PHP 7.3.5 以降で利用可能です。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mbstring.language string

mbstring で使用される言語設定(NLS)のデフォルト値。 この設定は mbstring.internal_encoding を定義するため、 php.ini の中で mbstring.internal_encoding は、 mbstring.language の後に置く必要があることに注意してください。

mbstring.encoding_translation bool

入力される HTTP クエリに関して、 文字エンコーディング検出および内部文字エンコーディングへの変換を行う 透過的な文字エンコーディングフィルタを有効にします。

mbstring.internal_encoding string
警告

この非推奨の機能は、きっと 将来 削除 されるでしょう。

内部文字エンコーディングのデフォルト値を定義します。

この値は空のままにしておいて、代わりに default_charset を設定すべきです。

mbstring.http_input string
警告

この非推奨の機能は、きっと 将来 削除 されるでしょう。

HTTP 入力文字エンコーディングのデフォルト値を定義します。

この値は空のままにしておいて、代わりに default_charset を設定すべきです。

mbstring.http_output string
警告

この非推奨の機能は、きっと 将来 削除 されるでしょう。

HTTP 出力文字エンコーディングのデフォルト値を定義します (出力は、内部エンコーディングから HTTP 出力エンコーディングに変換された上で出力されます)。

この値は空のままにしておいて、代わりに default_charset を設定すべきです。

mbstring.detect_order string

文字コード検出のデフォルト値を定義します。 mb_detect_order()も参照ください。

mbstring.substitute_character string

無効な文字を代替する文字を定義します。 サポートされる値は、mb_substitute_character() を参照ください。

mbstring.func_overload string
警告

この機能は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この機能に頼らないことを強く推奨します。

シングルバイト対応の関数を mbstring 関数の対応する関数でオーバーロード (置換)します。詳細は、 関数のオーバーロード を参照ください。

この設定は、php.ini でしか変更できません。

mbstring.http_output_conv_mimetypes string

mbstring.strict_detection bool

厳密なエンコーディング検出を有効にします。 詳しい説明と例は、mb_detect_encoding() を参照ください。

mbstring.regex_retry_limit int

mbregex のマッチングの間に行われる、バックトラッキングの量を制限します。

この設定は、oniguruma >= 6.8.0 と PHP をリンクした場合にのみ利用可能です。

mbstring.regex_stack_limit int

mbstring の正規表現エンジンの、スタックの深さを制限します。

» HTML 4.01 の仕様 によると、Web ブラウザは、 フォームのデータを投稿する際にページで使用される文字エンコーディングと 異なるエンコーディングを使用することができます。 ブラウザで使用される文字エンコーディングを検出するには、 mb_http_input() を参照ください。

一般的に使用されるブラウザでは、 指定したHTML文書の文字エンコーディングをかなり正確に推定することができますが、 header() または設定パラメータ default_charset により、 Content-Type HTTP ヘッダで charset を設定する方がより良いでしょう。

例1 php.ini 設定の例

; デフォルトの言語を設定
mbstring.language        = neutral; デフォルト言語を中立(UTF-8)に設定 (デフォルト)
mbstring.language        = English; デフォルト言語を英語に設定
mbstring.language        = Japanese; デフォルト言語を日本語に設定

;; デフォルトの内部エンコーディングを設定
;; 注意: PHPで動作する文字エンコーディングを使用すること
mbstring.internal_encoding    = UTF-8  ; 内部エンコーディングを UTF-8 に設定

;; HTTP入力エンコーディング変換を有効にする
mbstring.encoding_translation = On

;; デフォルトのHTTP入力文字エンコーディングを設定
;; 注意: スクリプトではhttp_inputの設定は変更できません。
mbstring.http_input           = pass    ; 変換しない。
mbstring.http_input           = auto    ; HTTP 入力を auto に設定
                                ; "auto" は mbstring.language の設定を使って展開されます
mbstring.http_input           = SJIS    ; HTTP入力をSJISに設定
mbstring.http_input           = UTF-8,SJIS,EUC-JP ; 順番を指定

;; デフォルトのHTTP出力文字エンコーディングを設定
mbstring.http_output          = pass    ; 変換しない
mbstring.http_output          = UTF-8   ; HTTP出力エンコーディングを
                                        ;  UTF-8 に指定

;; デフォルトの文字エンコーディング検出順序を設定
mbstring.detect_order         = auto    ; デフォルトの順番を auto に設定
mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; 順番を指定

;; 代替文字のデフォルト値を設定
mbstring.substitute_character = 12307   ; Unicode 値を指定
mbstring.substitute_character = none    ; 文字を出力しない
mbstring.substitute_character = long    ; long の例: U+3000,JIS+7E7E

例2 EUC-JP ユーザー用の php.ini の設定

;; 出力バッファリングを無効にする
output_buffering      = Off

;; HTTP charsetヘッダを設定
default_charset       = EUC-JP

;; デフォルトの言語を日本語にする
mbstring.language = Japanese

;; HTTP 入力変換を有効にする
mbstring.encoding_translation = On

;; HTTP 入力エンコーディング変換を auto に設定
mbstring.http_input   = auto

;; HTTP 出力を EUC-JP に設定
mbstring.http_output  = EUC-JP

;; 内部エンコーディングを EUC-JP に設定
mbstring.internal_encoding = EUC-JP

;; 無効な文字を出力しない
mbstring.substitute_character = none

例3 SJIS ユーザー用の php.iniの 設定

;; 出力のバッファリングを有効に
output_buffering     = On

;; 出力の変換を有効にするために mb_output_handler を設定
output_handler       = mb_output_handler

;; HTTPヘッダ charset を設定
default_charset      = Shift_JIS

;; デフォルトの言語を日本語に設定
mbstring.language = Japanese

;; HTTP 入力変換を有効にする
mbstring.encoding_translation = On

;; HTTP 入力エンコーディング変換を auto に設定
mbstring.http_input  = auto

;; SJIS に変換
mbstring.http_output = SJIS

;; 内部エンコーディングを EUC-JP に設定
mbstring.internal_encoding = EUC-JP

;; 無効な文字を出力しない
mbstring.substitute_character = none


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MB_OVERLOAD_MAIL (int)
PHP 8.0.0 で削除されました。
MB_OVERLOAD_STRING (int)
PHP 8.0.0 で削除されました。
MB_OVERLOAD_REGEX (int)
PHP 8.0.0 で削除されました。
MB_CASE_UPPER (int)
完全な大文字のケースフォールディングを実行します。 この操作で、文字列の長さが変わる可能性があります。 この定数は mb_strtoupper() で使うモードです。
MB_CASE_LOWER (int)
完全な小文字へのケースフォールディングを実行します。 この操作で、文字列の長さが変わる可能性があります。 この定数は mb_strtolower() で使うモードです。
MB_CASE_TITLE (int)
Unicodeプロパティ由来の大文字小文字の区別の有無に基づいて、Title-case 変換を実行します。 これは特に、クォートやアポストロフィーのハンドリングも改善します。 この操作で、文字列の長さが変わる可能性があります。
MB_CASE_FOLD (int)
文字列に存在する大文字小文字の区別を取り除くことで、完全なケースフォールディング変換を実行します。 これは大文字小文字を区別しないマッチングで使います。 この操作で、文字列の長さが変わる可能性があります。 PHP 7.3 から利用可能
MB_CASE_LOWER_SIMPLE (int)
単純な小文字へのケースフォールディング変換を実行します。 この操作で、文字列の長さは変わりません。 PHP 7.3 から利用可能
MB_CASE_UPPER_SIMPLE (int)
単純な大文字へのケースフォールディング変換を実行します。 この操作で、文字列の長さは変わりません。 PHP 7.3 から利用可能
MB_CASE_TITLE_SIMPLE (int)
単純な Title-case 変換を実行します。 この操作で、文字列の長さは変わりません。 PHP 7.3 から利用可能
MB_CASE_FOLD_SIMPLE (int)
文字列に存在する大文字小文字の区別を取り除くことで、単純なケースフォールディング変換を実行します。 これは大文字小文字を区別しない操作で使います。 この操作で文字列の長さは変わりません。 mbstring 拡張モジュールで内部的に大文字小文字を区別しない操作で使われていました。 PHP 7.3 から利用可能。
MB_ONIGURUMA_VERSION (string)
Oniguruma のバージョン。 例: 6.9.4. PHP 7.4 から利用可能。


サポートされるエンコーディングの概要

サポートされるエンコーディングの概要
IANA 文字セット登録名 | 依存する文字集合 | 説明 | 注記
ISO-10646-UCS-4 | ISO 10646 | 31 ビットコード空間を使用するユニバーサル文字セットで、 ISO/IEC 10646 によって UCS-4 として標準化されています。 最新版の Unicode コードマップと連動しています。 | この名前をエンコーディング変換の際に使用すると、 先頭の BOM (バイトオーダーマーク) にもとづいてそれ以降のバイト列のエンディアンを識別します。
ISO-10646-UCS-4 | UCS-4 | 上を参照ください。 | UCS-4 とは対照的に、 文字列が常にビッグエンディアン形式とみなされます。
ISO-10646-UCS-4 | UCS-4 | 上を参照ください。 | UCS-4 とは対照的に、 文字列が常にリトルエンディアン形式とみなされます。
ISO-10646-UCS-2 | UCS-2 | 16 ビットコード空間を使用するユニバーサル文字セットで、 ISO/IEC 10646 によって UCS-2 として標準化されています。 最新版の Unicode コードマップと連動しています。 | この名前をエンコーディング変換の際に使用すると、 先頭の BOM (バイトオーダーマーク) にもとづいてそれ以降のバイト列のエンディアンを識別します。
ISO-10646-UCS-2 | UCS-2 | 上を参照ください。 | UCS-2 とは対照的に、 文字列が常にビッグエンディアン形式とみなされます。
ISO-10646-UCS-2 | UCS-2 | 上を参照ください。 | UCS-2 とは対照的に、 文字列が常にリトルエンディアン形式とみなされます。
UTF-32 | Unicode | 32 ビット幅の Unicode 変換フォーマットで、 そのエンコーディング空間は Unicode のコードセット標準を参照します。 このエンコーディング体系は UCS-4 とは異なります。 なぜなら、Unicode のコード空間は 21 ビットまでに制限されるからです。 | この名前をエンコーディング変換の際に使用すると、 先頭の BOM (バイトオーダーマーク) にもとづいてそれ以降のバイト列のエンディアンを識別します。
UTF-32BE | Unicode | 上を参照ください。 | UTF-32 とは対照的に、 文字列が常にビッグエンディアン形式とみなされます。
UTF-32LE | Unicode | 上を参照ください。 | UTF-32 とは対照的に、 文字列が常にリトルエンディアン形式とみなされます。
UTF-16 | Unicode | 16 ビット幅の Unicode 変換フォーマットです。 注意すべき点は、UTF-16 の仕様が UCS-2 とは異なることです。 なぜなら、Unicode 2.0 より導入されたサロゲート機能により、 UTF-16 は現在 21 ビットコード空間を参照しているからです。 | この名前をエンコーディング変換の際に使用すると、 先頭の BOM (バイトオーダーマーク) にもとづいてそれ以降のバイト列のエンディアンを識別します。
UTF-16BE | Unicode | 上を参照ください。 | UTF-16 とは対照的に、 文字列が常にビッグエンディアン形式とみなされます。
UTF-16LE | Unicode | 上を参照ください。 | UTF-16 とは対照的に、 文字列が常にリトルエンディアン形式とみなされます。
UTF-8 | Unicode / UCS | 8 ビット幅の Unicode 変換フォーマットです。 | none
UTF-7 | Unicode | メールで安全に使用できる Unicode 変換フォーマットです。 » RFC2152 で定義されています。 | none
(none) | Unicode | UTF-7 の変化形です。 » IMAP プロトコル での使用に特化しています。 | none
US-ASCII (推奨される MIME 名) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | American Standard Code for Information Interchange は、一般的に使用される 7 ビットエンコーディングです。 国際標準規格 ISO 646 として標準化されています。 | (none)
EUC-JP (推奨される MIME 名) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | US-ASCII / JIS X0201:1997 (半角カナの部分) / JIS X0208:1990 / JIS X0212:1990 を合成したもの | この名前が Extended UNIX Code Packed Format for Japanese を短縮したものであることからわかるように、 一般的に UNIX 系のプラットフォームで用いられます。 もととなるエンコーディング方式である Extended UNIX Code は、ISO 2022 にもとづいて設計されています。 | EUC-JP が参照している文字セットは IBM932 / CP932 のものとは異なります。 これらはそれぞれ OS/2R および MicrosoftR WindowsR で用いられています。これらのプラットフォームとの間で情報をやり取りする場合は、 代わりに EUCJP-WIN を使用してください。
Shift_JIS (推奨される MIME 名) / MS_Kanji / csShift_JIS | JIS X0201:1997 / JIS X0208:1997 を合成したもの | Shift_JIS が開発されたのは 80 年代初期です。 当時は日本語ワープロが普及していたため、 旧来のエンコーディング方式である JIS X 0201:1976 との互換性を保つために開発されました。 IANA の定義によると、Shift_JIS のコードセットは IBM932 / CP932 とは微妙に異なります。 しかし、"SJIS" / "Shift_JIS" という名前は、 これらのコードセットを表すものとしてしばしば誤用されています。 | CP932 コードマップを使用するには、代わりに SJIS-WIN を使用してください。
(none) | JIS X0201:1997 / JIS X0208:1997 / IBM 拡張文字 / NEC 拡張文字 を合成したもの | この "エンコーディング" は EUC-JP と同じエンコーディング方式を使用しますが、 もととなる文字セットが異なります。 つまり、EUC-JP とは異なる文字に対応するコードポイントがあるということです。 | none
Windows-31J / csWindows31J | JIS X0201:1997 / JIS X0208:1997 / IBM 拡張文字 / NEC 拡張文字 を合成したもの | この "エンコーディング" は Shift_JIS と同じエンコーディング方式を使用しますが、 もととなる文字セットが異なります。 つまり、Shift_JIS とは異なる文字に対応するコードポイントがあるということです。 | (none)
ISO-2022-JP (推奨される MIME 名) / csISO2022JP | US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983 | » RFC1468 | (none)
JIS |  |  |
ISO-8859-1 |  |  |
ISO-8859-2 |  |  |
ISO-8859-3 |  |  |
ISO-8859-4 |  |  |
ISO-8859-5 |  |  |
ISO-8859-6 |  |  |
ISO-8859-7 |  |  |
ISO-8859-8 |  |  |
ISO-8859-9 |  |  |
ISO-8859-10 |  |  |
ISO-8859-13 |  |  |
ISO-8859-14 |  |  |
ISO-8859-15 |  |  |
ISO-8859-16 |  |  |
byte2be |  |  |
byte2le |  |  |
byte4be |  |  |
byte4le |  |  |
BASE64 |  |  |
HTML-ENTITIES |  |  |
7bit |  |  |
8bit |  |  |
EUC-CN |  |  |
CP936 |  |  |
HZ |  |  |
EUC-TW |  |  |
CP950 |  |  |
BIG-5 |  |  |
EUC-KR |  |  |
UHC (CP949) |  |  |
ISO-2022-KR |  |  |
Windows-1251 (CP1251) |  |  |
Windows-1252 (CP1252) |  |  |
CP866 (IBM866) |  |  |
KOI8-R |  |  |
KOI8-U |  |  |


日本語のマルチバイト文字に関する基本事項

日本語の文字は、マルチバイトエンコーディングを使用しないと表せません。 また、プラットフォームや使用目的によって複数の標準エンコーディングが 使い分けられています。さらに悪いことに、 これらの複数の標準エンコーディングはそれぞれ微妙に異なります。 日本語環境で使用しやすいウェブアプリケーションを作成するには、 これらの複雑な問題を考慮した上で 適切な文字エンコーディングを使用しなければなりません。

  • 1 文字は最大 6 バイトになる
  • ほとんどの日本語マルチバイト文字は、シングルバイト文字の 2 倍の幅となります。これらの文字のことを、日本語では "全角 (zen-kaku)" と呼びます。これは、 "full width" という意味です。一方、幅の狭い文字のことは "半角 (han-kaku)" と呼びます。これは、 "half width" という意味です。しかしながら、 文字の見た目は、それを表示する際に使用するタイプフェイスに依存します。
  • いくつかの文字エンコーディングでは、ISO-2022 で定義されたシフト (エスケープ) シーケンスを使用して、特定のコード範囲 (00h から 7fh まで) のコードマップを切り替えます。
  • SMTP/NNTPでは、ISO-2022-JP を使用する必要があり、ヘッダとエンティティは 各 RFC の規定に基づき再度符号化される必要があります。 これらは必須のものではありませんが、多くの一般的なユーザーエージェントは、 他の符号化手法を認識できないため、行っておく方が良いでしょう。
  • » i-mode または » EZweb のような携帯電話サービス用に作成された Web ページは、 Shift_JIS を使用することになります。
  • » i-mode や » EZweb などの携帯電話サービスで使われる絵文字にも対応しています。


HTTP 入出力

HTTP 入出力の文字エンコーディング変換はバイナリデータも変換して しまいます。HTTP 入出力にバイナリデータが使用される場合、ユーザーは、 文字エンコーディング変換を制御する必要があります。

注意:

HTML フォームの enctype が multipart/form-data に設定され、かつ、 php.ini において mbstring.encoding_translation に On が指定されている場合、 POST データの変数とアップロードされたファイルの名前の文字エンコーディングは、 内部文字エンコーディングに変換されます。 ただし、クエリキーに関しては、変換されません。

  • HTTP 入力

    PHP スクリプトで HTTP 入力文字変換を制御する手段はありません。 HTTP 入力文字変換を無効にするには、php.ini で行う必要があります。

    例1 php.ini で HTTP 入力変換を無効にする

    ;; HTTP 入力変換を無効にする
mbstring.http_input = pass
;; HTTP 入力変換を無効にする
mbstring.encoding_translation = Off

    PHP を Apache モジュールで使用する場合、php.ini の設定を httpd.conf により仮想ホスト単位で、または .htaccess によりディレクトリ単位で上書きすることが可能です。 詳細は、設定の節および Apache マニュアルを参照ください。

  • HTTP 出力

    出力の文字エンコーディング変換を有効にする方法は複数あります。 まず php.ini、もうひとつは ob_start() で ob_start のコールバック関数として mb_output_handler() を指定するものです。

例2 php.ini の設定例

;; 全ての PHP ページで出力の文字エンコーディング変換を有効にする

;; 出力バッファリングを有効にする
output_buffering    = On

;; mb_output_handler による出力変換を有効にする
output_handler      = mb_output_handler

例3 スクリプトの例

<?php

// このページでのみ出力の文字エンコーディング変換を有効にする

// HTTP 出力文字エンコーディングをSJISに設定する
mb_http_output('SJIS');

// 出力のバッファリングを開始し、コールバック関数として"mb_output_handler"
// を指定する
ob_start('mb_output_handler');

?>


サポートされる文字エンコーディング

現在、以下の文字エンコーディングが mbstring モジュールによりサポートされています。文字エンコーディングは、 mbstring 関数の encoding パラメータで指定することが可能です。

以下の文字エンコーディングがこの PHP 拡張モジュールでサポートされています。

  • UCS-4*
  • UCS-4BE
  • UCS-4LE*
  • UCS-2
  • UCS-2BE
  • UCS-2LE
  • UTF-32*
  • UTF-32BE*
  • UTF-32LE*
  • UTF-16*
  • UTF-16BE*
  • UTF-16LE*
  • UTF-7
  • UTF7-IMAP
  • UTF-8*
  • ASCII*
  • EUC-JP*
  • SJIS*
  • eucJP-win*
  • SJIS-win*
  • ISO-2022-JP
  • ISO-2022-JP-MS
  • CP932
  • CP51932
  • SJIS-mac (エイリアス: MacJapanese)
  • SJIS-Mobile#DOCOMO (エイリアス: SJIS-DOCOMO)
  • SJIS-Mobile#KDDI (エイリアス: SJIS-KDDI)
  • SJIS-Mobile#SOFTBANK (エイリアス: SJIS-SOFTBANK)
  • UTF-8-Mobile#DOCOMO (エイリアス: UTF-8-DOCOMO)
  • UTF-8-Mobile#KDDI-A
  • UTF-8-Mobile#KDDI-B (エイリアス: UTF-8-KDDI)
  • UTF-8-Mobile#SOFTBANK (エイリアス: UTF-8-SOFTBANK)
  • ISO-2022-JP-MOBILE#KDDI (エイリアス: ISO-2022-JP-KDDI)
  • JIS
  • JIS-ms
  • CP50220
  • CP50220raw
  • CP50221
  • CP50222
  • ISO-8859-1*
  • ISO-8859-2*
  • ISO-8859-3*
  • ISO-8859-4*
  • ISO-8859-5*
  • ISO-8859-6*
  • ISO-8859-7*
  • ISO-8859-8*
  • ISO-8859-9*
  • ISO-8859-10*
  • ISO-8859-13*
  • ISO-8859-14*
  • ISO-8859-15*
  • ISO-8859-16*
  • byte2be
  • byte2le
  • byte4be
  • byte4le
  • BASE64
  • HTML-ENTITIES (別名: HTML)
  • 7bit
  • 8bit
  • EUC-CN*
  • CP936
  • GB18030
  • HZ
  • EUC-TW*
  • CP950
  • BIG-5*
  • EUC-KR*
  • UHC (別名:CP949)
  • ISO-2022-KR
  • Windows-1251 (別名:CP1251)
  • Windows-1252 (別名:CP1252)
  • CP866 (別名:IBM866)
  • KOI8-R*
  • KOI8-U*
  • ArmSCII-8 (別名:ArmSCII8)

* は、正規表現でも使えるエンコーディングであることを表します。

エンコーディング名を指定する php.ini エントリには、 "auto" および "pass" を指定することもできます。 エンコーディング名を指定する mbstring 関数にも、"auto" を指定することができます。

"pass" が指定された場合、 文字エンコーディングの変換は行われません。

"auto" が指定された場合、この文字列は 言語設定 (NLS) ごとに定義されたエンコーディングのリストに変換されます。たとえば、言語設定が Japanese の場合は "ASCII,JIS,UTF-8,EUC-JP,SJIS" です。

mb_detect_order() も参照ください。


関数のオーバーロード機能

警告

この機能は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この機能に頼らないことを強く推奨します。

PHP アプリケーションの多くは、英語等のシングルバイトの言語用に設計されており、 日本語を含むマルチバイト文字列を扱う場合には問題を生じる場合があります。 substr() 等の PHP の文字列関数の多くは、 マルチバイト文字列に対応していません。

mbstring では、 対応するマルチバイト文字対応版の関数で既存の PHP 関数を オーバーロードする機能をサポートします。関数のオーバーロードを行うと、例えば substr() を PHP スクリプトでコールした場合に、 mb_substr() が代わりにコールされるようになります。 これにより、マルチバイト文字に対応しないアプリケーションの移植が容易となります。

関数オーバーロードを使用するには、php.ini の mbstring.func_overload ディレクティブに正の値を指定します。 これは、オーバーロードされる関数の種類を指定するビットマスクの組み合わせとなります。 mail() 関数をオーバーロードするには 1 を指定します。 2 は文字列関数、4 は正規表現関数を表します。つまり、例えば 7 を指定すると、メール関数、文字列関数および正規表現関数が オーバーロードされることになります。オーバーロードされる関数の一覧を以下に示します。

オーバーロードされる関数
mbstring.func_overload の値 | 元の関数 | オーバーロードする関数
1 | mail() | mb_send_mail()
2 | strlen() | mb_strlen()
2 | strpos() | mb_strpos()
2 | strrpos() | mb_strrpos()
2 | substr() | mb_substr()
2 | strtolower() | mb_strtolower()
2 | strtoupper() | mb_strtoupper()
2 | stripos() | mb_stripos()
2 | strripos() | mb_strripos()
2 | strstr() | mb_strstr()
2 | stristr() | mb_stristr()
2 | strrchr() | mb_strrchr()
2 | substr_count() | mb_substr_count()

注意:

ディレクトリ単位の設定でこのオプションを使用することは推奨されません。 これは、実際の運用環境ではまだ安定性が確認されておらず、 予期しない結果をもたらす可能性があるためです。


PHP の文字エンコーディングに関する要件

以下の型のエンコーディングが、PHP で安全に使用することができます。

  • シングルバイトエンコーディングで、

    • 00h から 7fh の範囲の文字に関して、 ASCII 互換 (ISO646 互換) のマッピングを有する。

  • マルチバイトエンコーディングで、

    • 00h から 7fh の範囲の文字では、 ASCII 互換のマッピングを有する。
    • ISO2022 エスケープシーケンスを使用しない。
    • 単一の文字を表す複数バイトのいずれにおいても 00h から 7fh の値を使用しない。

PHP で動作しないと思われる文字エンコーディングの例を以下に示します。

JIS, SJIS, ISO-2022-JP, BIG-5

これらのエンコーディングで書かれた PHP スクリプトは、 特に符号化された文字列がスクリプトで記述子やリテラルに使用される場合には、 動作しない可能性がありますが、入力される HTTP クエリに関して mbstring の透過的なエンコーディングフィルタを 設定することでこれらのエンコーディングをほとんど使用しないようにすることができます。

注意:

SJIS, BIG5, CP936, CP949, GB18030 は、読者がパーサ/コンパイラ、 文字エンコーディングと文字エンコーディングの問題点について精通していない限り 内部エンコーディングとして使用するべきではありません。

注意:

PHP でデータベースに接続する場合、性能を向上させるためにデータベースと PHP の内部エンコーディングについて同じ文字エンコーディングを使用することを推奨します。

PostgreSQL を使用している場合、 バックエンドの文字エンコーディングと異なる文字エンコーディングを使用することが可能です。 詳細については、PostgreSQL のマニュアルを参照ください。


マルチバイト文字列 関数

リファレンス

マルチバイト文字エンコーディングおよびそれに関連する問題は非常に複雑で、 このドキュメントの範囲を超えています。これらの問題に関連するより詳細な情報は、 以下の URL やその他のリソースを参照ください。

  • Unicode について

    » http://www.unicode.org/

  • 日本語/韓国語/中国語文字に関する情報

    » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

目次

  • mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる
  • mb_chr — Unicode のコードポイントに対応する文字を返す
  • mb_convert_case — 文字列に対してケースフォールディングを行う
  • mb_convert_encoding — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • mb_convert_kana — カナを("全角かな"、"半角かな"等に)変換する
  • mb_convert_variables — 変数の文字コードを変換する
  • mb_decode_mimeheader — MIME ヘッダフィールドの文字列をデコードする
  • mb_decode_numericentity — HTML 数値エンティティを文字にデコードする
  • mb_detect_encoding — 文字エンコーディングを検出する
  • mb_detect_order — 文字エンコーディング検出順序を設定あるいは取得する
  • mb_encode_mimeheader — MIMEヘッダの文字列をエンコードする
  • mb_encode_numericentity — 文字を HTML 数値エンティティにエンコードする
  • mb_encoding_aliases — 既知のエンコーディング・タイプのエイリアスを取得
  • mb_ereg — マルチバイト対応の正規表現マッチ
  • mb_ereg_match — マルチバイト文字列が正規表現に一致するか調べる
  • mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う
  • mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う
  • mb_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる
  • mb_ereg_search_getpos — 次の正規表現検索を開始する位置を取得する
  • mb_ereg_search_getregs — マルチバイト文字列が正規表現に一致する部分があるか調べる
  • mb_ereg_search_init — マルチバイト正規表現検索用の文字列と正規表現を設定する
  • mb_ereg_search_pos — 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す
  • mb_ereg_search_regs — 指定したマルチバイト文字列が正規表現に一致する部分を取得する
  • mb_ereg_search_setpos — 次の正規表現検索を開始する位置を設定する
  • mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ
  • mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う
  • mb_get_info — mbstring の内部設定値を取得する
  • mb_http_input — HTTP 入力文字エンコーディングを検出する
  • mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する
  • mb_language — 現在の言語を設定あるいは取得する
  • mb_list_encodings — サポートするすべてのエンコーディングの配列を返す
  • mb_ord — 文字の Unicode コードポイントを取得する
  • mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数
  • mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する
  • mb_preferred_mime_name — MIME 文字設定を文字列で得る
  • mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する
  • mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える
  • mb_send_mail — エンコード変換を行ってメールを送信する
  • mb_split — マルチバイト文字列を正規表現により分割する
  • mb_str_pad — マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める
  • mb_str_split — マルチバイト文字列を受取り、文字の配列を返す
  • mb_strcut — 文字列の一部を得る
  • mb_strimwidth — 指定した幅で文字列を丸める
  • mb_stripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
  • mb_stristr — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
  • mb_strlen — 文字列の長さを得る
  • mb_strpos — 文字列の中に指定した文字列が最初に現れる位置を見つける
  • mb_strrchr — 別の文字列の中で、ある文字が最後に現れる場所を見つける
  • mb_strrichr — 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す
  • mb_strripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す
  • mb_strrpos — 文字列の中に指定した文字列が最後に現れる位置を見つける
  • mb_strstr — 文字列の中で、指定した文字列が最初に現れる位置を見つける
  • mb_strtolower — 文字列を小文字にする
  • mb_strtoupper — 文字列を大文字にする
  • mb_strwidth — 文字列の幅を返す
  • mb_substitute_character — 置換文字を設定あるいは取得する
  • mb_substr — 文字列の一部を得る
  • mb_substr_count — 部分文字列の出現回数を数える


文字列が、指定したエンコーディングで有効なものかどうかを調べる

  • ≪ マルチバイト文字列 関数
  • mb_chr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列が、指定したエンコーディングで有効なものかどうかを調べる

mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる

説明

mb_check_encoding(array|string|null $value = null, ?string $encoding = null): bool

そのバイトストリームが指定したエンコーディングで有効なものかどうかを調べます。 value が配列の場合、全てのキーと値が再帰的に調べられます。 これは、いわゆる「不正なエンコーディングによる攻撃」を防ぐのに役立ちます。

パラメータ

value

調べるバイトストリーム または array。省略した場合は、 リクエスト開始時からのすべての入力が対象となります。

警告

PHP 8.1.0 以降では、このパラメータを省略したり null を渡したりすることは推奨されなくなっています。

encoding

期待するエンコーディング。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数を渡さずにこの関数を呼び出したり、 value に null を渡して呼び出すことは推奨されなくなりました。
8.0.0 | value と encoding は、nullable になりました。
7.2.0 | この関数は、value に配列を受け入れるようになりました。 このバージョンより前では、文字列のみがサポートされていました。


Unicode のコードポイントに対応する文字を返す

  • ≪ mb_check_encoding
  • mb_convert_case ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • Unicode のコードポイントに対応する文字を返す

mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Unicode のコードポイントに対応する文字を返す

説明

mb_chr(int $codepoint, ?string $encoding = null): string|false

Unicode のコードポイントで指定された文字を含む文字列を返します この値は、指定されたエンコーディングでエンコードされます。

この関数は、mb_ord() を補完するものです。

パラメータ

codepoint

Unicode のコードポイント値。 たとえば、 U+1F418 ELEPHANT に対応する 128024。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

これは、指定されたエンコーディングで表現できる場合、 指定された文字を含む文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 さまざまなコードポイントの例

<?php
$values = [65, 63, 0x20AC, 128024];
foreach ($values as $value) {
var_dump(mb_chr($value, 'UTF-8'));
var_dump(mb_chr($value, 'ISO-8859-1'));
}
?>

上の例の出力は以下となります。

string(1) "A"
string(1) "A"
string(1) "?"
string(1) "?"
string(3) "?"
bool(false)
string(4) ""
bool(false)

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_ord() - 文字の Unicode コードポイントを取得する
  • IntlChar::ord() - 文字に対応する Unicode コードポイントを返す
  • chr() - 数値から、1バイトの文字列を生成する


文字列に対してケースフォールディングを行う

  • ≪ mb_chr
  • mb_convert_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列に対してケースフォールディングを行う

mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — 文字列に対してケースフォールディングを行う

説明

mb_convert_case(string $string, int $mode, ?string $encoding = null): string

mode で指定された方法で string に対してケースフォールディングを行います。

パラメータ

string

変換される文字列。

mode

変換モード。以下のうちいずれかひとつです。 MB_CASE_UPPER, MB_CASE_LOWER, MB_CASE_TITLE, MB_CASE_FOLD, MB_CASE_UPPER_SIMPLE, MB_CASE_LOWER_SIMPLE, MB_CASE_TITLE_SIMPLE, MB_CASE_FOLD_SIMPLE

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

mode で指定された方法で string に対してケースフォールディングを行った結果を返します。

変更履歴

バージョン | 説明
7.3.0 | mode に MB_CASE_FOLD, MB_CASE_UPPER_SIMPLE, MB_CASE_LOWER_SIMPLE, MB_CASE_TITLE_SIMPLE, MB_CASE_FOLD_SIMPLE のサポートが追加されました。

例

例1 mb_convert_case() の例

<?php
$str = "mary had a Little lamb and she loved it so";
$str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
$str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
echo $str; // Prints Mary Had A Little Lamb And She Loved It So
?>

例2 非ラテン UTF-8 テキストでの mb_convert_case() の例

<?php
$str = "Τ?χιστη αλ?πηξ βαφ?? ψημ?νη γη, δρασκελ?ζει υπ?ρ νωθρο? κυν??";
$str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
echo $str; // 結果は Τ?ΧΙΣΤΗ ΑΛ?ΠΗΞ ΒΑΦ?Σ ΨΗΜ?ΝΗ ΓΗ, ΔΡΑΣΚΕΛ?ΖΕΙ ΥΠ?Ρ ΝΩΘΡΟ? ΚΥΝ?Σ
$str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
echo $str; // 結果は Τ?χιστη Αλ?πηξ Βαφ?σ Ψημ?νη Γη, Δρασκελ?ζει Υπ?ρ Νωθρο? Κυν?σ
?>

Unicode

標準のケースフォールディング関数である strtolower() や strtoupper() と違い、ケースフォールディングは Unicode 文字属性を基準に行われます。したがって、この関数の挙動は ロケールの設定に影響されず、また、すべてのアルファベット、 例えば A ウムラウト (A) を変換することができます。

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照ください。

参考

  • mb_strtolower() - 文字列を小文字にする
  • mb_strtoupper() - 文字列を大文字にする
  • strtolower() - 文字列を小文字にする
  • strtoupper() - 文字列を大文字にする
  • ucfirst() - 文字列の最初の文字を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする


ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

  • ≪ mb_convert_case
  • mb_convert_kana ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

説明

mb_convert_encoding(array|string $string, string $to_encoding, array|string|null $from_encoding = null): array|string|false

文字列 string の文字エンコーディングを、 from_encoding または現在の内部エンコーディングから to_encoding に変換します。 string が配列の場合、それに含まれる全ての文字列型の値が再帰的に変換されます。

パラメータ

string

変換する string または array

to_encoding

変換したい文字エンコーディング。

from_encoding

string を解釈するのに使われている 現在の文字エンコーディング。 配列またはカンマ区切りの文字列とすることで、 複数のエンコーディングを指定できます。 この場合、正しいエンコーディングを mb_detect_encoding() と同じアルゴリズムで推測します。

from_encoding が省略されたり、 null だった場合は、 mbstring.internal_encoding setting が設定されていた場合、それを使います。 設定されていない場合は、 default_charset setting を使います。

to_encoding や from_encoding に指定できる値は、 サポートされる文字エンコーディングを参照ください。

戻り値

成功時に、変換後の文字列または配列を返します。 失敗した場合に false を返します

エラー / 例外

PHP 8.0.0 以降では、 to_encoding または from_encoding に不正なエンコーディングが渡された場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生していました。

変更履歴

バージョン | 説明
8.2.0 | mb_convert_encoding() は、 以下のテキストでないエンコーディングを返さなくなりました: "Base64", "QPrint", "UUencode", "HTML entities", "7 bit", "8 bit"
8.0.0 | to_encoding に不正なエンコーディングが渡された場合、 ValueError がスローされるようになりました。
8.0.0 | from_encoding に不正なエンコーディングが渡された場合、 ValueError がスローされるようになりました。
8.0.0 | from_encoding は、nullable になりました。
7.2.0 | この関数は、 string に 配列を受け入れるようになりました。 これより前のバージョンでは、文字列のみがサポートされていました。

例

例1 mb_convert_encoding() の例

<?php
/* 内部文字エンコーディングからSJISに変換 */
$str = mb_convert_encoding($str, "SJIS");

/* EUC-JPからUTF-7に変換 */
$str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

/* JIS, eucjp-win, sjis-winの順番で自動検出し、UCS-2LEに変換 */
$str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

/* mbstring.language が "Japanese" の場合 "auto" は、"ASCII,JIS,UTF-8,EUC-JP,SJIS" に展開される */
$str = mb_convert_encoding($str, "EUC-JP", "auto");
?>

参考

  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する
  • UConverter::transcode() - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


カナを("全角かな"、"半角かな"等に)変換する

  • ≪ mb_convert_encoding
  • mb_convert_variables ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • カナを("全角かな"、"半角かな"等に)変換する

mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — カナを("全角かな"、"半角かな"等に)変換する

説明

mb_convert_kana(string $string, string $mode = "KV", ?string $encoding = null): string

文字列 string に関して「半角」-「全角」変換を行います。 この関数は、日本語のみで使用可能です。

パラメータ

string

変換される文字列。

mode

変換オプション。

以下のオプションを組み合わせて指定します。

使用可能な変換オプション
オプション | 意味
r | 「全角」英字を「半角」に変換します。
R | 「半角」英字を「全角」に変換します。
n | 「全角」数字を「半角」に変換します。
N | 「半角」数字を「全角」に変換します。
a | 「全角」英数字を「半角」に変換します。
A | 「半角」英数字を「全角」に変換します （"a", "A" オプションに含まれる文字は、U+0022, U+0027, U+005C, U+007Eを除く U+0021 - U+007E の範囲です）。
s | 「全角」スペースを「半角」に変換します（U+3000 -> U+0020）。
S | 「半角」スペースを「全角」に変換します（U+0020 -> U+3000）。
k | 「全角カタカナ」を「半角カタカナ」に変換します。
K | 「半角カタカナ」を「全角カタカナ」に変換します。
h | 「全角ひらがな」を「半角カタカナ」に変換します。
H | 「半角カタカナ」を「全角ひらがな」に変換します。
c | 「全角カタカナ」を「全角ひらがな」に変換します。
C | 「全角ひらがな」を「全角カタカナ」に変換します。
V | 濁点付きの文字を一文字に変換します。"K", "H" と共に使用します。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

変換後の文字列を返します。

エラー / 例外

異なる mode の組み合わせが無効な場合 (例: "sS") は、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.2.0 | 異なる mode の組み合わせが無効な場合、 ValueError がスローされるようになりました。
8.0.0 | encoding は、nullable になりました。

例

例1 mb_convert_kana() の例

<?php
/* 「仮名」を全て「全角カタカナ」に変換します */
$str = mb_convert_kana($str, "KVC");

/* 「半角カタカナ」を「全角カタカナ」に変換し、「全角」英数字を「半角」
に変換します。 */
$str = mb_convert_kana($str, "KVa");
?>


変数の文字コードを変換する

  • ≪ mb_convert_kana
  • mb_decode_mimeheader ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 変数の文字コードを変換する

mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — 変数の文字コードを変換する

説明

mb_convert_variables(
string $to_encoding,
array|string $from_encoding,
mixed &$var,
mixed &...$vars
): string|false

エンコーディング from_encoding の変数 var と vars をエンコーディング to_encoding に変換します。

mb_convert_variables() は、エンコーディング検出のために Array または Object の文字列を結合します。これは、 エンコーディング検出は短い文字列では失敗する傾向があるためです。このため、 1 つの配列またはオブジェクトで異なるエンコーディングを混ぜることはできません。

パラメータ

to_encoding

文字列の変換後のエンコーディング。

from_encoding

from_encoding には配列またはカンマ区切りの文字列を指定し、 from-coding からエンコーディングの検出を試みます。 from_encoding が省略された場合、detect_order を使用します。

var

var(3番目以降の引数)は、変換する変数への リファレンスです。文字列、配列、オブジェクトを指定することが可能です。 mb_convert_variables() は全てのパラメータが 同じエンコーディングを有することを仮定します。

vars

追加の変数。

戻り値

成功時に変換前の文字エンコーディングを返し、失敗した場合に false を返します。

例

例1 mb_convert_variables() の例

<?php
/* 変数 $post1, $post2 を内部エンコーディングに変換する */
$interenc = mb_internal_encoding();
$inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
?>


MIME ヘッダフィールドの文字列をデコードする

  • ≪ mb_convert_variables
  • mb_decode_numericentity ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • MIME ヘッダフィールドの文字列をデコードする

mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — MIME ヘッダフィールドの文字列をデコードする

説明

mb_decode_mimeheader(string $string): string

エンコードされた MIME ヘッダの文字列 string をデコードします。

パラメータ

string

デコードする文字列。

戻り値

内部文字エンコーディングでデコードされた文字列を返します。

参考

  • mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする


HTML 数値エンティティを文字にデコードする

  • ≪ mb_decode_mimeheader
  • mb_detect_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • HTML 数値エンティティを文字にデコードする

mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — HTML 数値エンティティを文字にデコードする

説明

mb_decode_numericentity(string $string, array $map, ?string $encoding = null): string

文字列 string において指定した文字領域にある数値エンティティを変換し、 変換後の文字列を返します。

パラメータ

string

デコードする文字列。

map

map は変換するコード領域を指定する配列です。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

is_hex

このパラメータは使われていません。

戻り値

変換された文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 map の例

<?php
$convmap = array (
int start_code1, int end_code1, int offset1, int mask1,
int start_code2, int end_code2, int offset2, int mask2,
........
int start_codeN, int end_codeN, int offsetN, int maskN );
// start_codeN および end_codeN に Unicode値を指定
// 値にoffsetNを追加、マスクmaskNを指定してビット毎の'AND'をとり、
// 数値エンティティに値を変換します。
?>

例2 map を使って JavaScript の文字列をエスケープする例

<?php
function escape_javascript_string($str) {
$map = [
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,0,0, // 49
0,0,0,0,0,0,0,0,1,1,
1,1,1,1,1,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,1,1,1,1,1,1,0,0,0, // 99
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1, // 149
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1, // 199
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,1,1, // 249
1,1,1,1,1,1,1, // 255
];
// 文字エンコーディングは UTF-8
$mblen = mb_strlen($str, 'UTF-8');
$utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
for ($i=0, $encoded=''; $i < $mblen; $i++) {
$u = substr($utf32, $i*8, 8);
$v = base_convert($u, 16, 10);
if ($v < 256 && $map[$v]) {
$encoded .= '\\x'.substr($u, 6,2);
} else if ($v == 2028) {
$encoded .= '\\u2028';
} else if ($v == 2029) {
$encoded .= '\\u2029';
} else {
$encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
}
}
return $encoded;
}

// テストデータ
$convmap = [ 0x0, 0xffff, 0, 0xffff ];
$msg = '';
for ($i=0; $i < 1000; $i++) {
// chr() では 128 より大きい UTF-8 データを正しく生成できないので、mb_decode_numericentity() を使います
$msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
}

// var_dump($msg);
var_dump(escape_javascript_string($msg));

参考

  • mb_encode_numericentity() - 文字を HTML 数値エンティティにエンコードする


文字エンコーディングを検出する

  • ≪ mb_decode_numericentity
  • mb_detect_order ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字エンコーディングを検出する

mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — 文字エンコーディングを検出する

説明

mb_detect_encoding(string $string, array|string|null $encodings = null, bool $strict = false): string|false

エンコーディングの候補の一覧から、 文字列 string のもっとも可能性が高い文字エンコーディングを検出します。

追加の情報なしに、 意図した文字エンコーディングを自動で検出する行為は、 全く役に立ちません。 これは、暗号化された文字列を鍵なしにデコードする行為に似ています。 "Content-Type" HTTP ヘッダのような、 データを転送された際に付いてくる情報や、 保存された文字エンコーディングに関する指示を指定することが常に望ましいです。

この関数は、全ての文字列が正しいバイト配列とは限らない マルチバイト文字列を指定するともっとも役に立ちます。 入力となる文字列に誤ったバイトが含まれていた場合、 そのエンコーディングは採用されず、次のものを試します。

パラメータ

string

調べる対象の文字列。

encodings

文字エンコーディングの一覧を試す順番に指定します。 このリストは、文字列の配列または、 カンマ区切りのリストで指定できます。

encodings が省略された場合、 または null の場合、 現在の detect_order ( mbstring.detect_order 設定オプション または mb_detect_order() で設定したもの) を使います。

strict

encodings で指定された 文字エンコーディングのリストの全てに対して、 不正と判定された場合の振る舞いを指定します。 strict が false の場合、 もっとも近いと判定された文字エンコーディングが返されます。 strict を true にした場合、 false が返されます。

strict のデフォルト値は mbstring.strict_detection 設定オプションで指定できます。

戻り値

検出した文字エンコーディングを返します。 指定したエンコーディングの全てに対して、不正と判定された場合は false を返します。

変更履歴

バージョン | 説明
8.2.0 | mb_detect_encoding() は、 以下のテキストでないエンコーディングを返さなくなりました: "Base64", "QPrint", "UUencode", "HTML entities", "7 bit", "8 bit"

例

例1 mb_detect_encoding() の例

<?php
// 現在のdetect_orderで文字エンコーディングを検出
echo mb_detect_encoding($str);

// "auto" は mbstring.language の設定を使って展開されます
echo mb_detect_encoding($str, "auto");

// 文字エンコーディングをカンマ区切りのリストで指定することで、encodings 引数を指定
echo mb_detect_encoding($str, "JIS, eucjp-win, sjis-win");

// encodings 引数を配列で指定
$encodings = [
"ASCII",
"JIS",
"EUC-JP"
];
echo mb_detect_encoding($str, $encodings);
?>

例2 strict パラメーターの効果

<?php
// 'aeou' は ISO-8859-1 でエンコードされています
$str = "\xE1\xE9\xF3\xFA";

// この文字列は、ASCII または UTF-8 的には正しくありませんが、
// UTF-8 がもっとも近いと判定されます
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

// 正しいエンコーディングが見つかった場合、
// strict パラメータを指定しても結果は変わりません
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
?>

上の例の出力は以下となります。

string(5) "UTF-8"
bool(false)
string(10) "ISO-8859-1"
string(10) "ISO-8859-1"

場合によっては、同じバイト配列が、 複数の文字エンコーディング的に正しいかもしれませんが、 どの解釈が意図されたものなのかを知ることは不可能です。 たとえば、 バイト配列 "\xC4\xA2" は、 以下のように解釈できます:

  • "A￠" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS のあとに、U+00A2 CENT SIGN が続いたもの) これらは、ISO-8859-1, ISO-8859-15, Windows-1252 でエンコードされたものと解釈できます。
  • "Ф?" (U+0424 CYRILLIC CAPITAL LETTER EF のあとに、 U+0402 CYRILLIC CAPITAL LETTER DJE が続いたもの) これは、ISO-8859-5 でエンコードされたものと解釈できます。
  • "?" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) これは、UTF-8 でエンコードされたものと解釈できます。

例3 複数のエンコーディングと一致した場合の効果

<?php
$str = "\xC4\xA2";

// 3つ全てのエンコーディングに照らして正しい文字列なので、
// 最初のひとつが返されます。
var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5']));
var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
?>

上の例の出力は以下となります。

string(5) "UTF-8"
string(10) "ISO-8859-1"
string(10) "ISO-8859-5"

参考

  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する


文字エンコーディング検出順序を設定あるいは取得する

  • ≪ mb_detect_encoding
  • mb_encode_mimeheader ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字エンコーディング検出順序を設定あるいは取得する

mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — 文字エンコーディング検出順序を設定あるいは取得する

説明

mb_detect_order(array|string|null $encoding = null): array|bool

自動文字エンコーディング検出の順番を encoding に設定します。

パラメータ

encoding

encoding は、 配列またはカンマ区切りの文字エンコーディングのリストです。サポートされる文字エンコーディングを参照ください。

encoding が省略された場合、または null の場合は、 現在の文字エンコーディング検出順を配列で返します。

この設定は、mb_detect_encoding() および mb_send_mail() に影響します。

mbstring が現在実装しているのは、 以下のエンコーディングを検出するフィルタです。 以下のエンコーディングにおいて無効なバイトシーケンスがあった場合、 エンコーディング検出は失敗します。

UTF-8, UTF-7, ASCII, EUC-JP,SJIS, eucJP-win, SJIS-win, JIS, ISO-2022-JP

ISO-8859-*の場合、mbstring は常に ISO-8859-* として検出します。

UTF-16, UTF-32, UCS2, UCS4 の場合、 エンコーディング検出は常に失敗します。

戻り値

検出順序を設定する場合は、成功した場合に true を返し、失敗したときに false を返します。

検出順序を取得する場合は、エンコーディングの配列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 mb_detect_order() の例

<?php
/* リストで検出順を設定 */
mb_detect_order("eucjp-win,sjis-win,UTF-8");

/* 配列で検出順を設定 */
$ary[] = "ASCII";
$ary[] = "JIS";
$ary[] = "EUC-JP";
mb_detect_order($ary);

/* 現在の検出順を表示 */
echo implode(", ", mb_detect_order());
?>

例2 無意味な順番の例

; 常に ISO-8859-1 として検出されます
detect_order = ISO-8859-1, UTF-8

; ASCII/UTF-7 の値は UTF-8 として有効なため、常に UTF-8 として検出されます
detect_order = UTF-8, ASCII, UTF-7

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_http_input() - HTTP 入力文字エンコーディングを検出する
  • mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_send_mail() - エンコード変換を行ってメールを送信する


MIMEヘッダの文字列をエンコードする

  • ≪ mb_detect_order
  • mb_encode_numericentity ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • MIMEヘッダの文字列をエンコードする

mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — MIMEヘッダの文字列をエンコードする

説明

mb_encode_mimeheader(
string $string,
?string $charset = null,
?string $transfer_encoding = null,
string $newline = "\r\n",
int $indent = 0
): string

MIME ヘッダエンコーディング方式によって文字列 string をエンコードします。

パラメータ

string

エンコードする文字列。 mb_internal_encoding() と同じエンコーディングにしなければいけません。

charset

charset は、string の変換後の文字セット名です。デフォルトは、現在の NLS 設定 (mbstring.language) によって決まります。

transfer_encoding

transfer_encoding は MIME エンコーディングの 方式を指定します。"B" (Base64) または "Q" (Quoted-Printable) のどちらかでなければなりません。 デフォルトは "B" です。

newline

newline は EOL (行末) のマーカで、 mb_encode_mimeheader() が行を折りたたむ (» RFC 用語で、 ある一定より長い行を複数行に分割することを言います。 分割する長さは、現在 74 文字に固定されています) 際に利用します。 デフォルトは "\r\n" (CRLF) です。

indent

最初の行の字下げ (ヘッダで string の前におく文字数)。

戻り値

文字列を ASCII 表現に変換したものを返します。

変更履歴

バージョン | 説明
8.0.0 | charset と transfer_encoding は、 nullable になりました。

例

例1 mb_encode_mimeheader() の例

<?php
$name = "太郎"; // 漢字
$mbox = "kru";
$doma = "gtinn.mon";
$addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
echo $addr;
?>

上の例の出力は以下となります。

"=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

注意

注意:

この関数は、行を分割する際に特別な配慮（単語の区切りなど）を行いません。 このせいで、もとの文字列に予期せぬ空白が入ってしまう可能性があります。

参考

  • mb_decode_mimeheader() - MIME ヘッダフィールドの文字列をデコードする


文字を HTML 数値エンティティにエンコードする

  • ≪ mb_encode_mimeheader
  • mb_encoding_aliases ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字を HTML 数値エンティティにエンコードする

mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — 文字を HTML 数値エンティティにエンコードする

説明

mb_encode_numericentity(
string $string,
array $map,
?string $encoding = null,
bool $hex = false
): string

stringの中で指定した文字コードを 文字コードから HTML 数値エンティティに変換します。

パラメータ

string

エンコードする文字列。

map

map は、変換するコード領域を指定する配列です。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

hex

返されたエンティティのリファレンスが16進記法であるべきかどうか (false の場合、10進記法です)

戻り値

変換後の文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 map の例

<?php
$convmap = array (
int start_code1, int end_code1, int offset1, int mask1,
int start_code2, int end_code2, int offset2, int mask2,
........
int start_codeN, int end_codeN, int offsetN, int maskN );
// start_codeN および end_codeN に Unicode 値を指定
// 値に offsetN を追加、マスク maskN を指定してビット毎の'AND'をとり、
// 数値エンティティに値を変換します。
?>

例2 mb_encode_numericentity() の例

<?php
/* ISO-8859-1 の左面をHTML数値エンティティに変換 */
$convmap = array(0x80, 0xff, 0, 0xff);
$str = mb_encode_numericentity($str, $convmap, "ISO-8859-1");

/* ブロック 95-104 にある SJIS-win コードのユーザー定義領域を
数値エンティティに変換 */
$convmap = array(
0xe000, 0xe03e, 0x1040, 0xffff,
0xe03f, 0xe0bb, 0x1041, 0xffff,
0xe0bc, 0xe0fa, 0x1084, 0xffff,
0xe0fb, 0xe177, 0x1085, 0xffff,
0xe178, 0xe1b6, 0x10c8, 0xffff,
0xe1b7, 0xe233, 0x10c9, 0xffff,
0xe234, 0xe272, 0x110c, 0xffff,
0xe273, 0xe2ef, 0x110d, 0xffff,
0xe2f0, 0xe32e, 0x1150, 0xffff,
0xe32f, 0xe3ab, 0x1151, 0xffff );
$str = mb_encode_numericentity($str, $convmap, "sjis-win");
?>

参考

  • mb_decode_numericentity() - HTML 数値エンティティを文字にデコードする


既知のエンコーディング・タイプのエイリアスを取得

  • ≪ mb_encode_numericentity
  • mb_ereg ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 既知のエンコーディング・タイプのエイリアスを取得

mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — 既知のエンコーディング・タイプのエイリアスを取得

説明

mb_encoding_aliases(string $encoding): array

既知の encoding タイプに関するエイリアスの配列を返します。

パラメータ

encoding

エイリアスに関してチェックするエンコーディングタイプ。

戻り値

数値インデックス付きの、エンコーディング・エイリアスの配列を返します。

エラー / 例外

encoding が未知の値の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | encoding が未知の値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生し、false を返していました。

例

例1 mb_encoding_aliases() 例

<?php
$encoding = 'ASCII';
$known_encodings = mb_list_encodings();

if (in_array($encoding, $known_encodings)) {

$aliases = mb_encoding_aliases($encoding);
print_r($aliases);

} else {

echo "Unknown ($encoding) encoding.\n";

}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => ANSI_X3.4-1968
    [1] => iso-ir-6
    [2] => ANSI_X3.4-1986
    [3] => ISO_646.irv:1991
    [4] => US-ASCII
    [5] => ISO646-US
    [6] => us
    [7] => IBM367
    [8] => cp367
    [9] => csASCII
)

参考

  • mb_list_encodings() - サポートするすべてのエンコーディングの配列を返す


マルチバイト対応の正規表現マッチ

  • ≪ mb_encoding_aliases
  • mb_ereg_match ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト対応の正規表現マッチ

mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — マルチバイト対応の正規表現マッチ

説明

mb_ereg(string $pattern, string $string, array &$matches = null): bool

マルチバイト対応の正規表現マッチを行います。

パラメータ

pattern

検索パターン。

string

検索文字列。

matches

pattern 内のカッコで囲まれた部分文字列にマッチするものが あった場合、第3引数 matches が指定されていると、 配列 matches の要素としてマッチ結果が格納されます。 マッチするものがなかった場合、matches は空の配列となります。

$matches[1] には最初の左括弧で指定された部分文字列が入ります。 $matches[2] には2番目の左括弧で指定された部分文字列が入ります。 以下同様です。 $matches[0] にはマッチした文字列全体のコピーが入ります。

戻り値

string 内に pattern にマッチする文字列があるかを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、成功時に true を返すようになりました。 これより前のバージョンでは、 string 内に pattern にマッチする文字列が存在し、かつ matches が渡された場合、 マッチした文字列のバイト長を返していました。 matches が渡されなかった場合、 あるいはマッチした文字列の長さが 0 だった場合、 この関数は 1 を返していました。
7.1.0 | マッチしなかった場合、mb_ereg() は matches を空の配列とするようになりました。 これより前のバージョンでは matches を変更しませんでした。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_eregi() - マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ


マルチバイト文字列が正規表現に一致するか調べる

  • ≪ mb_ereg
  • mb_ereg_replace ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列が正規表現に一致するか調べる

mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — マルチバイト文字列が正規表現に一致するか調べる

説明

mb_ereg_match(string $pattern, string $string, ?string $options = null): bool

マルチバイト文字列に対する正規表現マッチングを行います。

注意: この関数は、pattern が string の先頭からマッチするかどうかを調べます。

パラメータ

pattern

正規表現パターン。

string

評価する文字列。

options

検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

string が正規表現 pattern に一致する場合にtrue 、 そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | options は、nullable になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg() - マルチバイト対応の正規表現マッチ


マルチバイト文字列に正規表現による置換を行う

  • ≪ mb_ereg_match
  • mb_ereg_replace_callback ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列に正規表現による置換を行う

mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う

説明

mb_ereg_replace(
string $pattern,
string $replacement,
string $string,
?string $options = null
): string|false|null

string から pattern にマッチする文字列を探し、 見つかった文字列を replacement で置換します。

パラメータ

pattern

正規表現パターン。

マルチバイト文字を pattern で使用することができます。

replacement

置換文字列。

string

調べたい文字列。

options
検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

成功した場合に結果の文字列、エラー時に false を返します。 string が現在のエンコーディングに照らして不正な場合は、null を返します。

変更履歴

バージョン | 説明
8.0.0 | options は、nullable になりました。
7.1.0 | この関数は、現在のエンコーディングに照らして string が正しいかをチェックするようになりました。
7.1.0 | e 修飾子が非推奨になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

警告

信頼できない入力に対しては、 絶対に e 修正子を使用してはいけません。 (preg_replace() と同様、) 自動的なエスケープは行いません。 このことを忘れていると、自分の書いたアプリケーションにリモートコード実行の脆弱性を作りこんでしまうことになります。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_eregi_replace() - マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う


マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

  • ≪ mb_ereg_replace
  • mb_ereg_search ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

説明

mb_ereg_replace_callback(
string $pattern,
callable $callback,
string $string,
?string $options = null
): string|false|null

stringから patternにマッチする文字列を検索し、 一致した文字列をcallback関数の出力で置換します。

この関数の動作はmb_ereg_replace()とほぼ同じですが、 replacementパラメータの代わりに callbackを指定するところが異なります。

パラメータ

pattern

正規表現パターン。

patternではマルチバイト文字列を使用可能です。

callback

コールバック関数で、 string文字列で一致した要素を配列で 指定してコールされます。 このコールバック関数は、置換した文字列を返す必要があります。

しばしば、 mb_ereg_replace_callback()の callback関数が必要となるのは一度だけである 場合があります。 この場合、 mb_ereg_replace_callback()をコールする際の コールバックに 匿名関数 を使用することができます。 このようにすることで、 コールに関する全ての情報を一つの場所に集約し、 他のどこでも使用されないコールバック関数の名前を 関数の名前空間にばらまかないですみます。

string

チェックされるstring。

options

検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

成功した際に置換後の文字列、 そうでない場合はエラー時に false を返します。 string が現在のエンコーディングに照らして不正な場合は、null を返します。

変更履歴

バージョン | 説明
8.0.0 | options は、nullable になりました。
7.1.0 | この関数は、現在のエンコーディングに照らして string が正しいかをチェックするようになりました。

例

例1 mb_ereg_replace_callback() の例

<?php
// this text was used in 2002
// we want to get this up to date for 2003
$text = "April fools day is 04/01/2002\n";
$text.= "Last christmas was 12/24/2001\n";
// the callback function
function next_year($matches)
{
// as usual: $matches[0] is the complete match
// $matches[1] the match for the first subpattern
// enclosed in '(...)' and so on
return $matches[1].($matches[2]+1);
}
echo mb_ereg_replace_callback(
"(\d{2}/\d{2}/)(\d{4})",
"next_year",
$text);

?>

上の例の出力は以下となります。

April fools day is 04/01/2003
Last christmas was 12/24/2002

例2 匿名関数を使用したmb_ereg_replace_callback()の例

<?php
// this text was used in 2002
// we want to get this up to date for 2003
$text = "April fools day is 04/01/2002\n";
$text.= "Last christmas was 12/24/2001\n";

echo mb_ereg_replace_callback(
"(\d{2}/\d{2}/)(\d{4})",
function ($matches) {
return $matches[1].($matches[2]+1);
},
$text);
?>

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_replace() - マルチバイト文字列に正規表現による置換を行う
  • 匿名関数


指定したマルチバイト文字列が正規表現に一致するか調べる

  • ≪ mb_ereg_replace_callback
  • mb_ereg_search_getpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定したマルチバイト文字列が正規表現に一致するか調べる

mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる

説明

mb_ereg_search(?string $pattern = null, ?string $options = null): bool

指定したマルチバイト文字列に対するマルチバイト正規表現マッチングを行います。

パラメータ

pattern

検索パターン。

options

検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

mb_ereg_search()は、マルチバイト文字列が正規表現に 一致するかどうか調べ、一致する場合にtrue、それ以外の場合に false を返します。検索対象の文字列は、 mb_ereg_search_init() により設定します。 正規表現 pattern を省略した場合は、 前回のものを再利用します。

変更履歴

バージョン | 説明
8.0.0 | pattern と options は、nullable になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する


次の正規表現検索を開始する位置を取得する

  • ≪ mb_ereg_search
  • mb_ereg_search_getregs ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 次の正規表現検索を開始する位置を取得する

mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — 次の正規表現検索を開始する位置を取得する

説明

mb_ereg_search_getpos(): int

次の正規表現マッチングを開始する位置を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

mb_ereg_search_getpos() は、
mb_ereg_search(),
mb_ereg_search_pos(),
mb_ereg_search_regs() で検索を開始する位置を返します。
位置は、文字列の先頭からのバイト数で表した値です。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_setpos() - 次の正規表現検索を開始する位置を設定する


マルチバイト文字列が正規表現に一致する部分があるか調べる

  • ≪ mb_ereg_search_getpos
  • mb_ereg_search_init ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列が正規表現に一致する部分があるか調べる

mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — マルチバイト文字列が正規表現に一致する部分があるか調べる

説明

mb_ereg_search_getregs(): array|false

直近のマルチバイト正規表現マッチングの結果を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直前の mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs() で一致した部分文字列を含む 配列を返します。一致する部分があった場合には、一致した部分文字列全体が 最初の要素に、最初の括弧でグループ化された部分が 2 番目の要素に、そして 2 番目の括弧でグループ化された部分が 3 番目の要素にといったようになります。 エラー時には false を返します。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する


マルチバイト正規表現検索用の文字列と正規表現を設定する

  • ≪ mb_ereg_search_getregs
  • mb_ereg_search_pos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト正規表現検索用の文字列と正規表現を設定する

mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — マルチバイト正規表現検索用の文字列と正規表現を設定する

説明

mb_ereg_search_init(string $string, ?string $pattern = null, ?string $options = null): bool

mb_ereg_search_init() は、マルチバイト対応の正規
表現検索において検索対象の文字列 string
および正規表現 pattern を設定します。
この設定は、mb_ereg_search(),
mb_ereg_search_pos(),
mb_ereg_search_regs() で使用されます。

パラメータ

string

検索文字列。

pattern

検索パターン。

options

検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | pattern と options は、nullable になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_regs() - 指定したマルチバイト文字列が正規表現に一致する部分を取得する


指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

  • ≪ mb_ereg_search_init
  • mb_ereg_search_regs ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

説明

mb_ereg_search_pos(?string $pattern = null, ?string $options = null): array|false

マルチバイト文字列の中で正規表現に一致した部分の位置と長さを配列で返します。

検索対象の文字列は、mb_ereg_search_init() により設定します。省略した場合は、前回のものが利用されます。

パラメータ

pattern

検索パターン。

options

検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

ふたつの要素からなる配列を返します。最初の要素はオフセットをバイト単位で表したもので、 マッチしたのが検索文字列の先頭から何バイト目かを示します。 二番目の要素はマッチした部分の長さをバイト単位で表したものです。

エラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | pattern と options は、nullable になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する


指定したマルチバイト文字列が正規表現に一致する部分を取得する

  • ≪ mb_ereg_search_pos
  • mb_ereg_search_setpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定したマルチバイト文字列が正規表現に一致する部分を取得する

mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — 指定したマルチバイト文字列が正規表現に一致する部分を取得する

説明

mb_ereg_search_regs(?string $pattern = null, ?string $options = null): array|false

マルチバイト正規表現にマッチした部分を返します。

パラメータ

pattern

検索パターン。

options

検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

mb_ereg_search_regs() は、マルチバイト文字列の 中に正規表現に一致する部分があるかどうか調べ、一致した場合にはそれを 配列で返します。配列の最初の要素には一致した部分文字列全体、2 番目の 要素は最初の括弧でグループ化された部分、3 番目の要素は2番目の括弧で グループ化された部分といったようになります。 エラー時には false を返します。

変更履歴

バージョン | 説明
8.0.0 | pattern と options は、nullable になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する


次の正規表現検索を開始する位置を設定する

  • ≪ mb_ereg_search_regs
  • mb_eregi ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 次の正規表現検索を開始する位置を設定する

mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — 次の正規表現検索を開始する位置を設定する

説明

mb_ereg_search_setpos(int $offset): bool

mb_ereg_search_setpos() は、 mb_ereg_search() で検索を開始する位置を設定します。

パラメータ

offset

設定する位置。負の値を指定すると、文字列の末尾から数えます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | 負の offset をサポートするようになりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_search_init() - マルチバイト正規表現検索用の文字列と正規表現を設定する


マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

  • ≪ mb_ereg_search_setpos
  • mb_eregi_replace ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

説明

mb_eregi(string $pattern, string $string, array &$matches = null): bool

マルチバイトをサポートし、かつ大文字小文字を無視した正規表現マッチを実行します。

パラメータ

pattern

正規表現のパターン

string

検索対象の string

matches

pattern の 括弧で囲まれた部分文字列にマッチする部分が見つかり、 かつ3番目の引数 matches が渡された場合、 マッチした部分が matches 配列に格納されます。 何もマッチしなかった場合、 matches には空の配列が設定されます。

$matches[1] には、最初の左括弧から始まる部分文字列が含まれます。 $matches[2] には、二番目の左括弧から始まる部分文字列が含まれます。 以後同様です。 $matches[0] には、マッチした文字列全体のコピーが含まれます。

戻り値

string 内に pattern にマッチする文字列があるかを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、成功時に true を返すようになりました。 これより前のバージョンでは、 string 内に pattern にマッチする文字列が存在し、かつ matches が渡された場合、 マッチした文字列のバイト長を返していました。 matches が渡されなかった場合、 あるいはマッチした文字列の長さが 0 だった場合、 この関数は 1 を返していました。
7.1.0 | mb_eregi() 関数は、何もマッチしなかった場合に matches に空の配列を設定するようになりました。 これより前のバージョンでは、何もマッチしなかった場合に matches を変更しませんでした。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg() - マルチバイト対応の正規表現マッチ


マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

  • ≪ mb_eregi
  • mb_get_info ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

説明

mb_eregi_replace(
string $pattern,
string $replacement,
string $string,
?string $options = null
): string|false|null

string において、 正規表現 pattern にマッチする文字列を replacement に置換します。

パラメータ

pattern

正規表現パターン。マルチバイト文字を使用できます。 大文字小文字は区別しません。

replacement

置換する文字列。

string

検索対象となる文字列。

options
検索オプション。説明は、mb_regex_set_options() を参照ください。

戻り値

結果の文字列、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | options は、nullable になりました。
7.1.0 | この関数は、現在のエンコーディングに照らして string が正しいかをチェックするようになりました。
7.1.0 | e 修飾子が非推奨になりました。

注意

注意:

内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

警告

信頼できない入力に対しては、 絶対に e 修正子を使用してはいけません。 (preg_replace() と同様、) 自動的なエスケープは行いません。 このことを忘れていると、自分の書いたアプリケーションにリモートコード実行の脆弱性を作りこんでしまうことになります。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg_replace() - マルチバイト文字列に正規表現による置換を行う


mbstring の内部設定値を取得する

  • ≪ mb_eregi_replace
  • mb_http_input ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • mbstring の内部設定値を取得する

mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — mbstring の内部設定値を取得する

説明

mb_get_info(string $type = "all"): array|string|int|false|null

mb_get_info() は、mbstring の内部設定パラメータを返します。

パラメータ

type

type が指定されない場合、または、"all" の場合、 "internal_encoding", "http_input", "http_output", "http_output_conv_mimetypes", "mail_charset", "mail_header_encoding", "mail_body_encoding", "illegal_chars", "encoding_translation", "language", "detect_order", "substitute_character", "strict_detection" の設定値を有する連想配列が返されます。

type に "internal_encoding", "http_input", "http_output", "http_output_conv_mimetypes", "mail_charset", "mail_header_encoding", "mail_body_encoding", "illegal_chars", "encoding_translation", "language", "detect_order", "substitute_character", "strict_detection" が指定された場合、 指定された設定パラメータが返されます。

戻り値

type が指定されていない場合は型情報を含む配列、 それ以外の場合は指定した type の値を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 引数 type の "func_overload" と "func_overload_list" はサポートされなくなりました。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する


HTTP 入力文字エンコーディングを検出する

  • ≪ mb_get_info
  • mb_http_output ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • HTTP 入力文字エンコーディングを検出する

mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — HTTP 入力文字エンコーディングを検出する

説明

mb_http_input(?string $type = null): array|string|false

HTTP 入力文字エンコーディングを検出します。

パラメータ

type

HTTP 入力の型を表す文字列を入力してください。 GET の場合は "G"、POST の場合は "P"、 COOKIE の場合は "C"、文字列の場合は "S"、 リストの場合は "L"、リスト全体（配列を返す） の場合は "I" です。 type が省略された場合、 直近に処理された入力型が返されます。

戻り値

type の文字エンコーディング名を返します。 type が "I" の場合は、 文字エンコーディング名の配列を返します。 mb_http_input() が指定した HTTP 入力の処理を行っていない場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | type は、nullable になりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する


HTTP 出力文字エンコーディングを設定あるいは取得する

  • ≪ mb_http_input
  • mb_internal_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • HTTP 出力文字エンコーディングを設定あるいは取得する

mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する

説明

mb_http_output(?string $encoding = null): string|bool

HTTP 出力文字エンコーディングを設定あるいは取得します。 この関数を実行した後、 出力は内部エンコーディングから encoding に変換されます。

パラメータ

encoding

encoding が設定された場合、 mb_http_output() は HTTP 出力文字エンコーディングを encodingに設定します。

encoding が省略された場合、 mb_http_output() は現在の HTTP 出力文字エンコーディングを返します。

戻り値

encoding が省略された場合、 mb_http_output() は現在の HTTP 出力文字エンコーディングを返します。それ以外の場合、 成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_http_input() - HTTP 入力文字エンコーディングを検出する
  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する


内部文字エンコーディングを設定あるいは取得する

  • ≪ mb_http_output
  • mb_language ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 内部文字エンコーディングを設定あるいは取得する

mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する

説明

mb_internal_encoding(?string $encoding = null): string|bool

内部文字エンコーディングを設定あるいは取得します。

パラメータ

encoding

encoding は、HTTP 入力文字エンコーディング変換、 HTTP 出力文字エンコーディング変換および mbstring モジュールの文字列関数においてデフォルトの文字エンコーディングとして使用されます。 マルチバイト正規表現用のエンコーディングは、ここで扱う内部文字エンコーディングとは別であることに注意してください。

戻り値

encoding が設定された場合、 成功した場合に true を、失敗した場合に false を返します。 このとき、マルチバイト正規表現用のエンコーディングは変更されません。 encoding が省略された場合、 現在の内部文字エンコーディング名を返します。

エラー / 例外

PHP 8.0.0 以降では、 encoding が不正な値の場合に ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生していました。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。
8.0.0 | encoding が不正な値の場合に ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生していました。

例

例1 mb_internal_encoding() の例

<?php
/* 内部文字エンコーディングをUTF-8に設定 */
mb_internal_encoding("UTF-8");

/* 現在の内部文字エンコーディングを表示 */
echo mb_internal_encoding();
?>

参考

  • mb_http_input() - HTTP 入力文字エンコーディングを検出する
  • mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する
  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する
  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する


現在の言語を設定あるいは取得する

  • ≪ mb_internal_encoding
  • mb_list_encodings ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 現在の言語を設定あるいは取得する

mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — 現在の言語を設定あるいは取得する

説明

mb_language(?string $language = null): string|bool

現在の言語を設定あるいは取得します。

パラメータ

language

e-mail メッセージのエンコーディングとして使用します。 有効な言語の一覧は、以下のテーブルで示します。 mb_send_mail() は、e-mail をエンコードする際にこの設定を使用します。

言語 | 文字コード | エンコーディング | エイリアス
German/de | ISO-8859-15 | Quoted-Printable | Deutsch
English/en | ISO-8859-1 | Quoted-Printable
Armenian/hy | ArmSCII-8 | Quoted-Printable
Japanese/ja | ISO-2022-JP | BASE64
Korean/ko | ISO-2022-KR | BASE64
neutral | UTF-8 | BASE64
Russian/ru | KOI8-R | Quoted-Printable
Turkish/tr | ISO-8859-9 | Quoted-Printable
Ukrainian/ua | KOI8-U | Quoted-Printable
uni | UTF-8 | BASE64 | universal
Simplified Chinese/zh-cn | HZ | BASE64
Traditional Chinese/zh-tw | BIG-5 | BASE64

戻り値

language が設定され、 language が有効な場合、trueが返されます。 そうでない場合、falseが返されます。 language が省略された場合、または null の場合、 言語の名前が文字列として返されます。

変更履歴

バージョン | 説明
8.0.0 | language は、nullable になりました。

参考

  • mb_send_mail() - エンコード変換を行ってメールを送信する


サポートするすべてのエンコーディングの配列を返す

  • ≪ mb_language
  • mb_ord ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • サポートするすべてのエンコーディングの配列を返す

mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — サポートするすべてのエンコーディングの配列を返す

説明

mb_list_encodings(): array

サポートするすべてのエンコーディングの配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

数値添字の配列を返します。

エラー / 例外

この関数はエラーを発生させません。

例

例1 mb_list_encodings() の例

<?php

print_r(mb_list_encodings());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => pass
    [1] => auto
    [2] => wchar
    [3] => byte2be
    [4] => byte2le
    [5] => byte4be
    [6] => byte4le
    [7] => BASE64
    [8] => UUENCODE
    [9] => HTML-ENTITIES
    [10] => Quoted-Printable
    [11] => 7bit
    [12] => 8bit
    [13] => UCS-4
    [14] => UCS-4BE
    [15] => UCS-4LE
    [16] => UCS-2
    [17] => UCS-2BE
    [18] => UCS-2LE
    [19] => UTF-32
    [20] => UTF-32BE
    [21] => UTF-32LE
    [22] => UTF-16
    [23] => UTF-16BE
    [24] => UTF-16LE
    [25] => UTF-8
    [26] => UTF-7
    [27] => UTF7-IMAP
    [28] => ASCII
    [29] => EUC-JP
    [30] => SJIS
    [31] => eucJP-win
    [32] => SJIS-win
    [33] => JIS
    [34] => ISO-2022-JP
    [35] => Windows-1252
    [36] => ISO-8859-1
    [37] => ISO-8859-2
    [38] => ISO-8859-3
    [39] => ISO-8859-4
    [40] => ISO-8859-5
    [41] => ISO-8859-6
    [42] => ISO-8859-7
    [43] => ISO-8859-8
    [44] => ISO-8859-9
    [45] => ISO-8859-10
    [46] => ISO-8859-13
    [47] => ISO-8859-14
    [48] => ISO-8859-15
    [49] => EUC-CN
    [50] => CP936
    [51] => HZ
    [52] => EUC-TW
    [53] => BIG-5
    [54] => EUC-KR
    [55] => UHC
    [56] => ISO-2022-KR
    [57] => Windows-1251
    [58] => CP866
    [59] => KOI8-R
)

参考

  • mb_encoding_aliases() - 既知のエンコーディング・タイプのエイリアスを取得


文字の Unicode コードポイントを取得する

  • ≪ mb_list_encodings
  • mb_output_handler ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字の Unicode コードポイントを取得する

mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — 文字の Unicode コードポイントを取得する

説明

mb_ord(string $string, ?string $encoding = null): int|false

指定された文字の Unicode コードポイントを返します。

この関数は mb_chr() を補完するものです。

パラメータ

string

文字列

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

string のはじめの文字に対応する Unicode コードポイントを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 A basic mb_ord() example

<?php
var_dump(mb_ord("A", "UTF-8"));
var_dump(mb_ord("", "UTF-8"));
var_dump(mb_ord("\x80", "ISO-8859-1"));
var_dump(mb_ord("\x80", "Windows-1252"));
?>

上の例の出力は以下となります。

int(65)
int(128024)
int(128)
int(8364)

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_chr() - Unicode のコードポイントに対応する文字を返す
  • IntlChar::ord() - 文字に対応する Unicode コードポイントを返す
  • ord() - 文字列の先頭バイトを、0 から 255 までの値に変換する


出力バッファ内で文字エンコーディングを変換するコールバック関数

  • ≪ mb_ord
  • mb_parse_str ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 出力バッファ内で文字エンコーディングを変換するコールバック関数

mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数

説明

mb_output_handler(string $string, int $status): string

mb_output_handler() は、
ob_start() のコールバック関数です。
mb_output_handler() は、出力バッファの文字を
内部文字エンコーディングから HTTP 出力文字エンコーディングに変換します。

パラメータ

string

出力バッファの中身。

status

出力バッファの状態。

戻り値

変換後の文字列を返します。

例

例1 mb_output_handler() の例

<?php
mb_http_output("UTF-8");
ob_start("mb_output_handler");
?>

注意

注意:

イメージのようなバイナリデータを出力したい場合、 バイナリデータを送信する前に header() により Content-Type: ヘッダ(例：header("Content-Type: image/png"))を 送信する必要があります。Content-Type: ヘッダが送信されると出力文字 コード変換は無効となります。

'Content-Type: text/*' を送信した場合には、テキストが送信されるとみなし、文字コード設定に 基づいて出力文字コード変換を行います。

参考

  • ob_start() - 出力のバッファリングを有効にする


GET/POST/COOKIE データをパースし、グローバル変数を設定する

  • ≪ mb_output_handler
  • mb_preferred_mime_name ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • GET/POST/COOKIE データをパースし、グローバル変数を設定する

mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する

説明

mb_parse_str(string $string, array &$result): bool

GET/POST/COOKIE データをパースし、 グローバル変数を設定します。PHPは、生の POST/COOKIE を提供しないため、 現状では GET データでのみ使用可能です。この関数は、URL エンコードされたデータをパース、エンコーディングを検出、 内部エンコーディングへ変換し、配列result またはグローバル配列に設定します。

パラメータ

string

URL エンコードされたデータ。

result

デコードされ、文字エンコーディング変換された文字列が含まれます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 第二引数はオプションではなくなりました。
7.2.0 | 第二引数なしで mb_parse_str() を呼び出すことは推奨されなくなりました。

参考

  • mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する


MIME 文字設定を文字列で得る

  • ≪ mb_parse_str
  • mb_regex_encoding ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • MIME 文字設定を文字列で得る

mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — MIME 文字設定を文字列で得る

説明

mb_preferred_mime_name(string $encoding): string|false

指定したエンコーディングの MIME charset 文字列を取得します。

パラメータ

encoding

調べるエンコーディング。

戻り値

文字エンコーディング encoding 用の MIME charset 文字列を返します。 指定された encoding に対して、 好ましい charset がない場合は false を返します。

例

例1 mb_preferred_mime_name() の例

<?php
$outputenc = "sjis-win";
mb_http_output($outputenc);
ob_start("mb_output_handler");
header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
?>


現在のマルチバイト正規表現用のエンコーディングを取得または設定する

  • ≪ mb_preferred_mime_name
  • mb_regex_set_options ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 現在のマルチバイト正規表現用のエンコーディングを取得または設定する

mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する

説明

mb_regex_encoding(?string $encoding = null): string|bool

現在のマルチバイト正規表現用のエンコーディングを取得または設定する

パラメータ

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

encoding が設定された場合、成功した場合に TRUE を、失敗した場合に FALSE を返します。 このとき、内部文字エンコーディングは変更されません。 encoding が省略された場合、現在のマルチバイト用の正規表現関数で用いる文字エンコーディング名を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • mb_ereg() - マルチバイト対応の正規表現マッチ


マルチバイト正規表現関数のデフォルトオプションを取得または設定する

  • ≪ mb_regex_encoding
  • mb_scrub ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト正規表現関数のデフォルトオプションを取得または設定する

mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する

説明

mb_regex_set_options(?string $options = null): string

options で表されるオプションを、 マルチバイト対応の正規表現関数のデフォルトに設定します。

パラメータ

options

設定するオプション。文字列で設定し、各文字がオプションを表します。 モードを設定する際には、モード文字は最後に指定しなければなりません。 オプションは複数指定できますが、モードはひとつしか指定できません。

Regex のオプション
オプション | 意味 | 変更履歴
i | 曖昧なマッチをオンにする
x | 拡張パターン形式を有効にする
m | '.' が改行にマッチする
s | '^' -> '\A', '$' -> '\Z'
p | m と s を両方指定するのと同じ
l | 最も長くマッチするものを探す
n | 空のマッチを無視する
e | 結果のコードを eval() する | PHP 7.1.0 で非推奨になり、PHP 8.0.0 で削除されました。

注意:

mb_regex_set_options() に "e" オプションを設定しても、何も起きません。 mb_ereg_replace() や mb_eregi_replace() で指定するようにしてください。

Regex 構文モード(ひとつだけ設定可能です)
モード | 意味
j | Java (Sun java.util.regex)
u | GNU regex
g | grep
c | Emacs
r | Ruby
z | Perl
b | POSIX Basic regex
d | POSIX Extended regex

戻り値

以前設定されていたオプションを返します。 options が省略された場合、または null の場合、 現在設定されているオプションを文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | options が指定され、null でない場合、 以前に 設定されていたオプションが返されるようになりました。 これより前のバージョンでは、 現在 設定されているオプションが返されていました。
8.0.0 | options は、nullable になりました。
8.0.0 | "e" オプションを指定すると、ValueError がスローされるようになりました。
7.1.0 | "e" オプションを指定すると、E_DEPRECATED が発生するようになりました。

参考

  • mb_split() - マルチバイト文字列を正規表現により分割する
  • mb_ereg() - マルチバイト対応の正規表現マッチ
  • mb_eregi() - マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ


文字列に含まれる不正なバイト列を代替文字に置き換える

  • ≪ mb_regex_set_options
  • mb_send_mail ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列に含まれる不正なバイト列を代替文字に置き換える

mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える

説明

mb_scrub(string $string, ?string $encoding = null): string

指定されたエンコーディングに基づいて、文字の変換を行います。 エンコーディングが指定されない場合は、 デフォルトのエンコーディングが使われます。 この関数は、不正なバイトシーケンスを代替文字に置換する効果があります。

パラメータ

string

入力文字列

encoding

string を解釈するエンコーディング。 省略されるか、null でない場合は、 mbstring.internal_encoding setting が設定されている場合、それを使います。 設定されていない場合は、default_charset の設定を使います。

戻り値

不正なバイトシーケンスを置換した文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。


エンコード変換を行ってメールを送信する

  • ≪ mb_scrub
  • mb_split ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • エンコード変換を行ってメールを送信する

mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — エンコード変換を行ってメールを送信する

説明

mb_send_mail(
string $to,
string $subject,
string $message,
array|string $additional_headers = [],
?string $additional_params = null
): bool

email を送信します。ヘッダと本文は mb_language() の設定に基づき変換、エンコードされます。 これは mail() のラッパー関数です。詳細は、 mail() を参照ください。

パラメータ

to

送信先のメールアドレス。 各アドレスをカンマで区切ると、複数の宛先を to に指定できます。 このパラメータは、自動的にはエンコードされません。

subject

メールの件名。

message

メールの本文。

additional_headers（オプション）

メールヘッダの最後に挿入される String または array

通常、これは追加のヘッダ（From、Cc、Bcc）のために用いられます。 複数のヘッダを追加する場合は CRLF（\r\n）で区切ります。 攻撃者が不要なヘッダーを注入しないようにパラメータを検証してください。

array が渡された場合、キーと値はそれぞれ ヘッダーの名前および値です。

注意:

メールを送信する際には、必ず From ヘッダが含まれていなければなりません。 additional_headers パラメータで指定するか、 あるいは php.ini にデフォルト値を指定します。

指定しなかった場合は、以下のようなエラーメッセージが返ります Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing 。 Windows では、From ヘッダを設定すると Return-Path も設定されます。

注意:

メッセージが受信されなかった場合には、LF（\n）のみを使ってみてください。 Unix の MTA の中には、自動的に LF を CRLF に変換してしまう もの (有名なところでは、» qmail など) があります（もし CRLF を利用していた場合、CR が重複してしまいます）。 ただし、これは最後の手段です。というのも、これは » RFC 2822 に違反しているからです。

additional_params

additional_params は、MTA へ渡す コマンドライン引数です。sendmail を利用する際に正しい Return-Path を設定するためなどに利用すると便利です。

このパラメータはコマンドの実行を防止するために内部的に escapeshellcmd() によってエスケープされます。 escapeshellcmd() はコマンドの実行を防止しますが、 別のパラメータを追加することは許してしまいます。セキュリティ上の理由から、 このパラメータは検証されるべきです。

escapeshellcmd() が自動的に適用されるため、 インターネット RFC でメールアドレスとして許可さているいくつかの文字を使用することができません。 これらの文字を使用することが必須であるプログラムでは mail() を使うことはできません。

この方法でエンベロープの sender ヘッダ（-f）を設定する際は、 'X-Warning' ヘッダが付加されないように Web サーバーの実行ユーザーを sendmail 設定に追加しておく必要があるかもしれません。 sendmail を利用している場合、これは /etc/mail/trusted-users で設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | additional_params は、nullable になりました。
7.2.0 | additional_headers パラメータは、 array も受け付けるようになりました。

参考

  • mail() - メールを送信する
  • mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする
  • mb_language() - 現在の言語を設定あるいは取得する


マルチバイト文字列を正規表現により分割する

  • ≪ mb_send_mail
  • mb_str_pad ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列を正規表現により分割する

mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — マルチバイト文字列を正規表現により分割する

説明

mb_split(string $pattern, string $string, int $limit = -1): array|false

マルチバイト文字列 string において、正規表現 pattern により文字列を分割し、 結果を配列として返します。

パラメータ

pattern

正規表現パターン。

string

分割する文字列。

limit
オプションの引数 limit を指定した場合は、 最大 limit 個の要素に分割されます。

戻り値

結果を配列で返します。 失敗した場合に false を返します

注意

注意:

mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

参考

  • mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
  • mb_ereg() - マルチバイト対応の正規表現マッチ


マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める

  • ≪ mb_split
  • mb_str_split ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める

mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める

説明

mb_str_pad(
string $string,
int $length,
string $pad_string = " ",
int $pad_type = STR_PAD_RIGHT,
?string $encoding = null
): string

この関数は文字列 string の左、右または両側を指定した長さで埋めます。 長さは Unicode のコードポイント単位で決まります。 pad_string が指定されていない場合は、 string は空白で埋められ、それ以外の場合は、 pad_string からの文字で制限まで埋められます。

パラメータ

string

入力文字列。

length

length の値が負、 または入力文字列の長さ以下である場合、埋める操作は行われません。 string をそのまま返します。

pad_string

注意:

必要とされる埋める文字数が pad_string の長さで均等に分割できない場合、pad_string は切り捨てられます。

pad_type

オプションの引数 pad_type には、 STR_PAD_RIGHT, STR_PAD_LEFT, STR_PAD_BOTH を指定可能です。 pad_typeが指定されない場合、 STR_PAD_RIGHT を仮定します。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

埋めた後の文字列を返します。

例

例1 mb_str_pad() の例

<?php
var_dump(mb_str_pad('??', 6, '???', STR_PAD_RIGHT)); // string(18) "??????"
var_dump(mb_str_pad('??', 6, '???', STR_PAD_LEFT)); // string(18) "??????"
var_dump(mb_str_pad('??', 6, '???', STR_PAD_BOTH)); // string(18) "??????"

var_dump(mb_str_pad("??", 3, "祝", STR_PAD_LEFT)); // string(10) "祝祝??"
?>


マルチバイト文字列を受取り、文字の配列を返す

  • ≪ mb_str_pad
  • mb_strcut ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • マルチバイト文字列を受取り、文字の配列を返す

mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — マルチバイト文字列を受取り、文字の配列を返す

説明

mb_str_split(string $string, int $length = 1, ?string $encoding = null): array

この関数は文字列の配列を返します。 これは str_split() に 1, 2 または 4バイトの固定長のエンコーディングだけでなく、 可変長のエンコーディングのサポートも追加したものです。 length を指定すると、 文字列は指定された数の(バイトではなく)文字のチャンクに分割されます。 encoding もオプションで指定できますが、 指定するほうが良いでしょう。

パラメータ

string

文字またはチャンクに分割する string

length

これを指定すると、返される配列の個々の要素は一文字ではなく複数の文字になります。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

サポートされているエンコーディングのうち、ひとつを指定した文字列

戻り値

mb_str_split() は、string の配列を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。
8.0.0 | この関数は、失敗時に false を返さなくなりました。

参考

  • str_split() - 文字列を配列に変換する


文字列の一部を得る

  • ≪ mb_str_split
  • mb_strimwidth ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の一部を得る

mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — 文字列の一部を得る

説明

mb_strcut(
string $string,
int $start,
?int $length = null,
?string $encoding = null
): string

mb_strcut() は、ある文字列からの部分文字列の抽出を mb_substr() と同じ方法で行います。ただし、 処理は文字単位ではなくバイト単位で行います。 切り出し位置がたまたまマルチバイト文字の 2 バイト目以降だった場合、 切り出しはその文字の最初のバイトから行われます。この挙動もまた substr() 関数と異なるところです。 substr() の場合は、 マルチバイト文字の 2 バイト目以降であってもその位置から切り出しを行い、 結果的に壊れたバイト列を返すことになります。

パラメータ

string

取り出しの対象となる文字列。

start

start が非負である場合に返される文字列は、 string の start バイト目以降の文字列となります (ゼロから数えます)。 たとえば、文字列 'abcdef' の 0 バイト目は 'a' で、 2 バイト目は 'c' のようになります。

start が負の場合に返される文字列は、 string の後ろから数えて start バイト目以降となります。 負の start の絶対値が文字列の長さよりも大きい場合、 返される文字列は、string の先頭から始まります。

length

バイト単位での長さ。 省略したり NULL を指定したりした場合は、 文字列の最後までの全バイトを取り出します。

length が負の場合、返される文字列は string の後ろから数えて length バイト目で終了します。 しかし、負の length の絶対値が start の位置を超える場合、空の文字列が返されます。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

mb_strcut() は、 start および length パラメータで指定した string の一部を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_substr() - 文字列の一部を得る
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する


指定した幅で文字列を丸める

  • ≪ mb_strcut
  • mb_stripos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 指定した幅で文字列を丸める

mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — 指定した幅で文字列を丸める

説明

mb_strimwidth(
string $string,
int $start,
int $width,
string $trim_marker = "",
?string $encoding = null
): string

文字列 string を指定した幅 width で丸めます。 半角文字は 1 として、 全角文字は 2 として数えます。 東アジアの文字の長さに関する詳細は » http://www.unicode.org/reports/tr11/ を参照ください。

パラメータ

string

丸めたい文字列。

start

開始位置のオフセット。文字列の始めからの文字数 (最初の文字は 0) です。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

width

丸める幅。 負の値を指定すると、文字列の末尾からの幅を数えます。

注意:

負の値を指定することは、PHP 8.3.0 以降では推奨されなくなっています。

trim_marker

丸めた後にその文字列の最後に追加される文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

丸められた文字列を返します。 trim_marker が設定された場合、 width にマッチする最後の文字を trim_marker で置き換えます。

変更履歴

バージョン | 説明
8.3.0 | mb_strimwidth() に負の width を渡すことは、推奨されなくなりました。
8.0.0 | encoding は、nullable になりました。
7.1.0 | 負の start と width をサポートするようになりました。

例

例1 mb_strimwidth() の例

<?php
echo mb_strimwidth("Hello World", 0, 10, "...");
// "Hello W..." と出力します
?>

参考

  • mb_strwidth() - 文字列の幅を返す
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する


大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

  • ≪ mb_strimwidth
  • mb_stristr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

説明

mb_stripos(
string $haystack,
string $needle,
int $offset = 0,
?string $encoding = null
): int|false

mb_stripos() は、 needle が haystack の中で最初に現れる位置を返します。 mb_strpos() とは異なり、 mb_stripos() は大文字小文字を区別しません。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最初に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

offset

haystack の中で、検索を開始する位置。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

戻り値

needle が haystack の中で最初に現れる位置を返します。needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。
7.1.0 | 負の offset をサポートするようになりました。

参考

  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける


大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

  • ≪ mb_stripos
  • mb_strlen ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

説明

mb_stristr(
string $haystack,
string $needle,
bool $before_needle = false,
?string $encoding = null
): string|false

mb_stristr() は、 haystack の中で最初に needle が現れる場所を探し、 haystack の部分文字列を返します。 mb_strstr() とは異なり、 mb_stristr() は大文字小文字を区別しません。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最初に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最初に現れる位置までを返します (needle を含めません)。 false の場合は、needle が最初に現れる位置から haystack の最後までを返します (needle を含めます)。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

戻り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。

参考

  • stristr() - 大文字小文字を区別しない strstr
  • strstr() - 文字列が最初に現れる位置を見つける
  • mb_strstr() - 文字列の中で、指定した文字列が最初に現れる位置を見つける


文字列の長さを得る

  • ≪ mb_stristr
  • mb_strpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の長さを得る

mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — 文字列の長さを得る

説明

mb_strlen(string $string, ?string $encoding = null): int

文字列の長さを取得します。

パラメータ

string

長さを調べたい文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

文字エンコーディング encoding の文字列 string の文字数を返します。 マルチバイト文字の一文字は1個として数えられます。

エラー / 例外

不明な encoding を指定した場合は E_WARNING レベルの警告が生成されます。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • grapheme_strlen() - 書記素単位で文字列の長さを取得する
  • iconv_strlen() - 文字列の文字数を返す
  • strlen() - 文字列の長さを得る


文字列の中に指定した文字列が最初に現れる位置を見つける

  • ≪ mb_strlen
  • mb_strrchr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の中に指定した文字列が最初に現れる位置を見つける

mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — 文字列の中に指定した文字列が最初に現れる位置を見つける

説明

mb_strpos(
string $haystack,
string $needle,
int $offset = 0,
?string $encoding = null
): int|false

ある文字列の中で別の文字列が最初に現れる位置を見つけます。

マルチバイト文字列に正しくマッチするように strpos() を拡張したもので、 最初の 1 文字目の位置が 0 、2 文字目の文字が 1 というようになります。

パラメータ

haystack

調べたい文字列。

needle

haystack の中から探す文字列。 strpos() とは違い、 数値を指定しても文字コードの値と見なされることはありません。

offset

検索オフセット。 指定されない場合は、0 が使用されます。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

文字列 haystack の中で needle が最初に現れる位置を数字で返します。 needle が見付からなかった場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。
7.1.0 | 負の offset をサポートするようになりました。

参考

  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける


別の文字列の中で、ある文字が最後に現れる場所を見つける

  • ≪ mb_strpos
  • mb_strrichr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 別の文字列の中で、ある文字が最後に現れる場所を見つける

mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — 別の文字列の中で、ある文字が最後に現れる場所を見つける

説明

mb_strrchr(
string $haystack,
string $needle,
bool $before_needle = false,
?string $encoding = null
): string|false

mb_strrchr() は、 haystack の中で最後に needle が現れる場所を探し、 haystack の部分文字列を返します。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最後に現れる位置を探す文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最後に現れる位置までを返します。 false の場合は、needle が最後に現れる位置から haystack の最後までを返します。

encoding

使用する文字エンコーディングの名前。 省略した場合は内部文字エンコーディングを使用します。

戻り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。

参考

  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • mb_strstr() - 文字列の中で、指定した文字列が最初に現れる位置を見つける
  • mb_strrichr() - 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す


大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

  • ≪ mb_strrchr
  • mb_strripos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

説明

mb_strrichr(
string $haystack,
string $needle,
bool $before_needle = false,
?string $encoding = null
): string|false

mb_strrichr() は、 haystack の中で最後に needle が現れる場所を探し、 haystack の部分文字列を返します。 mb_strrchr() とは異なり、 mb_strrichr() は大文字小文字を区別しません。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最後に現れる位置を探す文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最後に現れる位置までを返します。 false の場合は、needle が最後に現れる位置から haystack の最後までを返します。

encoding

使用する文字エンコーディングの名前。 省略した場合は内部文字エンコーディングを使用します。

戻り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。

参考

  • mb_stristr() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
  • mb_strrchr() - 別の文字列の中で、ある文字が最後に現れる場所を見つける


大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

  • ≪ mb_strrichr
  • mb_strrpos ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

説明

mb_strripos(
string $haystack,
string $needle,
int $offset = 0,
?string $encoding = null
): int|false

mb_strripos() は、マルチバイト対応の strripos() 操作を、文字数に基づいて行います。 needle の位置を haystack の先頭から順に数えていきます。 最初の文字の位置は 0、二番目の文字の位置は 1 という具合です。 mb_strrpos() とは異なり、 mb_strripos() は大文字小文字を区別しません。

パラメータ

haystack

needle が最後に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

offset

haystack の中で、検索を開始する位置。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

戻り値

needle が haystack の中で最後に現れる位置を返します。needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。

参考

  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • mb_strrpos() - 文字列の中に指定した文字列が最後に現れる位置を見つける


文字列の中に指定した文字列が最後に現れる位置を見つける

  • ≪ mb_strripos
  • mb_strstr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の中に指定した文字列が最後に現れる位置を見つける

mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — 文字列の中に指定した文字列が最後に現れる位置を見つける

説明

mb_strrpos(
string $haystack,
string $needle,
int $offset = 0,
?string $encoding = null
): int|false

mb_strrpos() は、マルチバイト対応の strrpos() 操作を、文字数に基づいて行います。 needle の位置を haystack の先頭から順に数えていきます。 最初の文字の位置は 0、二番目の文字の位置は 1 という具合です。

パラメータ

haystack

needle が最後に登場する場所を調べたい文字列。

needle

haystack の中で見つけたい文字列。

offset
指定すると、文字列中の任意の文字位置から検索を開始することができます。 負の値を指定すると、文字の終端より前の任意の位置で検索を終了します。
encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

文字列 haystack の中で needle が最後に現れる位置を数字で返します。 needle が見付からなかった場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | 3番目の引数に、offset の代わりに encoding を渡すことができる仕様は削除されました。
8.0.0 | encoding は、nullable になりました。

参考

  • mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す


文字列の中で、指定した文字列が最初に現れる位置を見つける

  • ≪ mb_strrpos
  • mb_strtolower ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の中で、指定した文字列が最初に現れる位置を見つける

mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — 文字列の中で、指定した文字列が最初に現れる位置を見つける

説明

mb_strstr(
string $haystack,
string $needle,
bool $before_needle = false,
?string $encoding = null
): string|false

mb_strstr() は、 haystack の中で最初に needle が現れる場所を探し、 haystack の部分文字列を返します。 needle が見つからなかった場合は false を返します。

パラメータ

haystack

needle が最初に現れる位置を見つける文字列。

needle

haystack の中で探す文字列。

before_needle

この関数が haystack のどの部分を返すのかを指定します。 true の場合は、haystack の先頭から needle が最初に現れる位置までを返します (needle を含めません)。 false の場合は、needle が最初に現れる位置から haystack の最後までを返します (needle を含めます)。

encoding

使用する文字エンコーディング名。 省略した場合は内部文字エンコーディングが用いられます。

戻り値

haystack の部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空の文字列も受け入れるようになりました。
8.0.0 | encoding は、nullable になりました。

参考

  • stristr() - 大文字小文字を区別しない strstr
  • strstr() - 文字列が最初に現れる位置を見つける
  • mb_stristr() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す


文字列を小文字にする

  • ≪ mb_strstr
  • mb_strtoupper ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列を小文字にする

mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — 文字列を小文字にする

説明

mb_strtolower(string $string, ?string $encoding = null): string

string のすべてのアルファベットを小文字にして返します。

パラメータ

string

小文字にしたい文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

string のすべてのアルファベットを小文字にしたものを返します。

例

例1 mb_strtolower() の例

<?php
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = mb_strtolower($str);
echo $str; // 結果は mary had a little lamb and she loved it so
?>

例2 非ラテン UTF-8 テキストでの mb_strtolower() の例

<?php
$str = "Τ?χιστη αλ?πηξ βαφ?? ψημ?νη γη, δρασκελ?ζει υπ?ρ νωθρο? κυν??";
$str = mb_strtolower($str, 'UTF-8');
echo $str; // 結果は τ?χιστη αλ?πηξ βαφ?? ψημ?νη γη, δρασκελ?ζει υπ?ρ νωθρο? κυν??
?>

Unicode

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照ください。

strtolower() と違い、アルファベットであるかどうかは Unicode 文字属性をもとに決定されます。したがって、この関数の挙動は ロケールの設定に影響されず、すべてのアルファベット、 例えば A ウムラウト (A) を変換することができます。

参考

  • mb_strtoupper() - 文字列を大文字にする
  • mb_convert_case() - 文字列に対してケースフォールディングを行う
  • strtolower() - 文字列を小文字にする


文字列を大文字にする

  • ≪ mb_strtolower
  • mb_strwidth ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列を大文字にする

mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — 文字列を大文字にする

説明

mb_strtoupper(string $string, ?string $encoding = null): string

string のすべてのアルファベットを大文字にして返します。

パラメータ

string

大文字に変換したい文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

string のすべてのアルファベットを大文字にしたものを返します。

例

例1 mb_strtoupper() の例

<?php
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = mb_strtoupper($str);
echo $str; // 結果は MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
?>

例2 非ラテン UTF-8 テキストでの mb_strtoupper() の例

<?php
$str = "Τ?χιστη αλ?πηξ βαφ?? ψημ?νη γη, δρασκελ?ζει υπ?ρ νωθρο? κυν??";
$str = mb_strtoupper($str, 'UTF-8');
echo $str; // 結果は Τ?ΧΙΣΤΗ ΑΛ?ΠΗΞ ΒΑΦ?Σ ΨΗΜ?ΝΗ ΓΗ, ΔΡΑΣΚΕΛ?ΖΕΙ ΥΠ?Ρ ΝΩΘΡΟ? ΚΥΝ?Σ
?>

Unicode

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照ください。

strtoupper()と違い、アルファベットであるかどうかは Unicode 文字属性をもとに決定されます。したがって、この関数の挙動は ロケールの設定に影響されず、すべてのアルファベット、 例えば A ウムラウト (a) を変換することができます。

参考

  • mb_strtolower() - 文字列を小文字にする
  • mb_convert_case() - 文字列に対してケースフォールディングを行う
  • strtoupper() - 文字列を大文字にする


文字列の幅を返す

  • ≪ mb_strtoupper
  • mb_substitute_character ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の幅を返す

mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — 文字列の幅を返す

説明

mb_strwidth(string $string, ?string $encoding = null): int

文字列 string の幅を返します。 半角文字は 1 として、 全角文字は 2 として数えます。 東アジアの文字の長さに関する詳細は » http://www.unicode.org/reports/tr11/ を参照ください。

全角文字は次のとおりです。 U+1100-U+115F、 U+11A3-U+11A7、 U+11FA-U+11FF、 U+2329-U+232A、 U+2E80-U+2E99、 U+2E9B-U+2EF3、 U+2F00-U+2FD5、 U+2FF0-U+2FFB、 U+3000-U+303E、 U+3041-U+3096、 U+3099-U+30FF、 U+3105-U+312D、 U+3131-U+318E、 U+3190-U+31BA、 U+31C0-U+31E3、 U+31F0-U+321E、 U+3220-U+3247、 U+3250-U+32FE、 U+3300-U+4DBF、 U+4E00-U+A48C、 U+A490-U+A4C6、 U+A960-U+A97C、 U+AC00-U+D7A3、 U+D7B0-U+D7C6、 U+D7CB-U+D7FB、 U+F900-U+FAFF、 U+FE10-U+FE19、 U+FE30-U+FE52、 U+FE54-U+FE66、 U+FE68-U+FE6B、 U+FF01-U+FF60、 U+FFE0-U+FFE6、 U+1B000-U+1B001、 U+1F200-U+1F202、 U+1F210-U+1F23A、 U+1F240-U+1F248、 U+1F250-U+1F251、 U+20000-U+2FFFD、 U+30000-U+3FFFD。 他のすべての文字は半角の文字です。

パラメータ

string

幅を取得したい文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

文字列 string の幅を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 mb_strwidth() example

<?php
var_dump(
mb_strwidth('a'), // LATIN SMALL LETTER A
mb_strwidth("\u{ff41}") // FULLWIDTH LATIN SMALL LETTER A
);
?>

上の例の出力は以下となります。

int(1)
int(2)

参考

  • mb_strimwidth() - 指定した幅で文字列を丸める
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する


置換文字を設定あるいは取得する

  • ≪ mb_strwidth
  • mb_substr ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 置換文字を設定あるいは取得する

mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — 置換文字を設定あるいは取得する

説明

mb_substitute_character(string|int|null $substitute_character = null): string|int|bool

入力文字エンコーディングが無効、 または出力文字エンコーディングに文字コードが存在しない場合の代替文字を指定します。 無効な文字は、"none" (出力しない)、文字列または整数値 (Unicode 文字コード値) に置換することが可能です。

この設定は、mb_convert_encoding()、
mb_convert_variables()、
mb_output_handler()、
mb_scrub()、
および mb_send_mail() に影響します。

パラメータ

substitute_character

Unicode 値の整数または文字列を以下のように指定します。

  • "none": 出力しない
  • "long": 文字コードの値を出力する (例: U+3000、JIS+7E7E)
  • "entity": 文字エンティティを出力する (例: &#x200;)

戻り値

substitute_character が設定された場合、成功時に true、そうでない場合に false を返します。 substitute_character が設定されない場合は、現在の設定を返します。

変更履歴

バージョン | 説明
8.0.0 | substitute_character に空文字列を渡すことはサポートされなくなりました。 代わりに "none" を渡すべきです。
8.0.0 | encoding は、nullable になりました。

例

例1 mb_substitute_character() の例

<?php
/* Unicode U+3013 (ゲタ記号)を設定 */
mb_substitute_character(0x3013);

/* HEX フォーマットを設定 */
mb_substitute_character("long");

/* 現在の設定を表示 */
echo mb_substitute_character();
?>


文字列の一部を得る

  • ≪ mb_substitute_character
  • mb_substr_count ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 文字列の一部を得る

mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — 文字列の一部を得る

説明

mb_substr(
string $string,
int $start,
?int $length = null,
?string $encoding = null
): string

文字数に基づきマルチバイト対応の substr() 処理を行います。位置は、 string の始めから数えられます。 最初の文字の位置は 0、2 番目の文字の位置は 1、といったようになります。

パラメータ

string

部分文字列を取り出したい文字列。

start

start が非負である場合に返される文字列は、 string の start バイト目以降の文字列となります (ゼロから数えます)。 たとえば、文字列 'abcdef' の 0 バイト目は 'a' で、 2 バイト目は 'c' のようになります。

start が負の数の場合に返される文字列は、 string の後ろから数えて start バイト目以降となります。

length

string の中から取り出す最大文字数。 省略したり NULL を渡したりした場合は、 文字列の最後までの全バイトを取り出します。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

mb_substr() は、start および length パラメータで指定した string の一部を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

参考

  • mb_strcut() - 文字列の一部を得る
  • mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する


部分文字列の出現回数を数える

  • ≪ mb_substr
  • Pspell ≫
  • PHP Manual
  • マルチバイト文字列 関数
  • 部分文字列の出現回数を数える

mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — 部分文字列の出現回数を数える

説明

mb_substr_count(string $haystack, string $needle, ?string $encoding = null): int

文字列 haystack の中での部分文字列 needle の出現回数を数えます。

パラメータ

haystack

調べたい文字列。

needle

見つける文字列。

encoding

encoding パラメータには文字エンコーディングを指定します。省略した場合、もしくは null の場合は、 内部文字エンコーディングを使用します。

戻り値

文字列 haystack の中での部分文字列 needle の出現回数を返します。

変更履歴

バージョン | 説明
8.0.0 | encoding は、nullable になりました。

例

例1 mb_substr_count() の例

<?php
echo mb_substr_count("これはてすとです。", "す"); // 2 を出力する
?>

参考

  • mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける
  • mb_substr() - 文字列の一部を得る
  • substr_count() - 副文字列の出現回数を数える


Pspell

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • Pspell 関数
    • pspell_add_to_personal — ユーザーの単語リストに単語を追加する
    • pspell_add_to_session — 現在のセッションの単語リストに単語を追加する
    • pspell_check — 単語をチェックする
    • pspell_clear_session — 現在のセッションをクリアする
    • pspell_config_create — 辞書をオープンする際に使用する設定を作成する
    • pspell_config_data_dir — 言語のデータファイルの場所
    • pspell_config_dict_dir — メイン単語リストの場所
    • pspell_config_ignore — 長さが N 文字未満の単語を無視する
    • pspell_config_mode — 返される提案の数のモードを変更する
    • pspell_config_personal — 個人の単語リストを保持するファイルを設定する
    • pspell_config_repl — 置換候補を保持するファイルを設定する
    • pspell_config_runtogether — 複合語を有効な単語の組み合わせとして考慮する
    • pspell_config_save_repl — 単語リストと共に置換リストを保存するかどうかを定義する
    • pspell_new — 新規辞書をロードする
    • pspell_new_config — 指定した設定に基づき新規辞書をロードする
    • pspell_new_personal — 個人の単語リストを有する新規辞書をロードする
    • pspell_save_wordlist — 個人の単語リストをファイルに保存する
    • pspell_store_replacement — 単語を置換する組を保存する
    • pspell_suggest — 単語のスペルについて修正候補を示す
  • PSpell\Dictionary — PSpell\Dictionary クラス
  • PSpell\Config — PSpell\Config クラス


  • ≪ Pspell
  • インストール/設定 ≫
  • PHP Manual
  • Pspell
  • はじめに

はじめに

これらの関数により、単語のスペルチェックを行い、修正案を提案させる ことが可能となります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Pspell
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

PHP を pspell サポートつきでコンパイルするには、aspellライブラリが 必要です。これは、» http://aspell.net/ で取得可能です。


インストール手順

PHP をコンパイルする際に、オプション --with-pspell[=dir] を追加する 必要があります。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 aspell の bin フォルダにある aspell-15.dll

Win32 サポートは、aspell バージョン 0.50 以降が必要です。


リソース型

PHP 8.1.0 より前のバージョンでは、 この拡張モジュールは2つのリソースを使用していました。 ひとつは辞書のリンクID、ふたつめは pspell 設定のリソースです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PSPELL_FAST (int)
PSPELL_NORMAL (int)
PSPELL_BAD_SPELLERS (int)
PSPELL_RUN_TOGETHER (int)


Pspell 関数

目次

  • pspell_add_to_personal — ユーザーの単語リストに単語を追加する
  • pspell_add_to_session — 現在のセッションの単語リストに単語を追加する
  • pspell_check — 単語をチェックする
  • pspell_clear_session — 現在のセッションをクリアする
  • pspell_config_create — 辞書をオープンする際に使用する設定を作成する
  • pspell_config_data_dir — 言語のデータファイルの場所
  • pspell_config_dict_dir — メイン単語リストの場所
  • pspell_config_ignore — 長さが N 文字未満の単語を無視する
  • pspell_config_mode — 返される提案の数のモードを変更する
  • pspell_config_personal — 個人の単語リストを保持するファイルを設定する
  • pspell_config_repl — 置換候補を保持するファイルを設定する
  • pspell_config_runtogether — 複合語を有効な単語の組み合わせとして考慮する
  • pspell_config_save_repl — 単語リストと共に置換リストを保存するかどうかを定義する
  • pspell_new — 新規辞書をロードする
  • pspell_new_config — 指定した設定に基づき新規辞書をロードする
  • pspell_new_personal — 個人の単語リストを有する新規辞書をロードする
  • pspell_save_wordlist — 個人の単語リストをファイルに保存する
  • pspell_store_replacement — 単語を置換する組を保存する
  • pspell_suggest — 単語のスペルについて修正候補を示す


ユーザーの単語リストに単語を追加する

  • ≪ Pspell 関数
  • pspell_add_to_session ≫
  • PHP Manual
  • Pspell 関数
  • ユーザーの単語リストに単語を追加する

pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — ユーザーの単語リストに単語を追加する

説明

pspell_add_to_personal(PSpell\Dictionary $dictionary, string $word): bool

pspell_add_to_personal() はユーザーの単語リスト
に単語を追加します。ディレクトリをオープンするために
pspell_new_config() を
pspell_config_personal() とともに使用した場合、
pspell_save_wordlist() で単語リストを保存することが可能です。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

word

追加する単語。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_add_to_personal()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
$pspell = pspell_new_config($pspell_config);

pspell_add_to_personal($pspell, "Vlad");
pspell_save_wordlist($pspell);
?>

注意

注意:

この関数は、pspell .11.2 と aspell .32.5 以降でない限り動作しないことに注意してください。


現在のセッションの単語リストに単語を追加する

  • ≪ pspell_add_to_personal
  • pspell_check ≫
  • PHP Manual
  • Pspell 関数
  • 現在のセッションの単語リストに単語を追加する

pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — 現在のセッションの単語リストに単語を追加する

説明

pspell_add_to_session(PSpell\Dictionary $dictionary, string $word): bool

pspell_add_to_session() は、 現在のセッションに関連する単語リストに単語を追加します。この関数は、 pspell_add_to_personal() に似ています。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

word

追加する単語。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


単語をチェックする

  • ≪ pspell_add_to_session
  • pspell_clear_session ≫
  • PHP Manual
  • Pspell 関数
  • 単語をチェックする

pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — 単語をチェックする

説明

pspell_check(PSpell\Dictionary $dictionary, string $word): bool

pspell_check() は単語のスペルをチェックします。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

word

チェックする単語。

戻り値

スペルが正しい場合に true、そうでない場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_check() の例

<?php
$pspell = pspell_new("en");

if (pspell_check($pspell, "testt")) {
echo "This is a valid spelling";
} else {
echo "Sorry, wrong spelling";
}
?>


現在のセッションをクリアする

  • ≪ pspell_check
  • pspell_config_create ≫
  • PHP Manual
  • Pspell 関数
  • 現在のセッションをクリアする

pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — 現在のセッションをクリアする

説明

pspell_clear_session(PSpell\Dictionary $dictionary): bool

pspell_clear_session() は、 現在のセッションをクリアします。現在の単語リストはブランクになり、 例えば pspell_save_wordlist() でこのリストを保存しても何もおきません。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_add_to_personal() の例

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
$pspell = pspell_new_config($pspell_config);

pspell_add_to_personal($pspell, "Vlad");
pspell_clear_session($pspell);
pspell_save_wordlist($pspell); //"Vlad" は保存されません。
?>


辞書をオープンする際に使用する設定を作成する

  • ≪ pspell_clear_session
  • pspell_config_data_dir ≫
  • PHP Manual
  • Pspell 関数
  • 辞書をオープンする際に使用する設定を作成する

pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — 辞書をオープンする際に使用する設定を作成する

説明

pspell_config_create(
string $language,
string $spelling = "",
string $jargon = "",
string $encoding = ""
): PSpell\Config

辞書をオープンする際に使用する設定を作成します。

pspell_config_create() は、
pspell_new() の構文に非常によく似ています。実際、
pspell_new_config() の直後に
pspell_config_create() を使用した場合、全く同じ
結果となります。しかし、新しい設定を作成した後、
pspell_new_config() をコールする前に関数
pspell_config_*() を使用することで
いくつかの進んだ機能が使用できます。

より詳細な情報と例については、pspell Web サイト » http://aspell.net/ のオンラインマニュアルを参照ください。

パラメータ

language

パラメータ language は、2 文字の ISO 639 言語コードと オプションでダッシュまたはアンダースコアの後に 2 文字の ISO 3166 国コードからなる言語コードです。

spelling

パラメータ spelling は、英語のように複数のスペルがある言語に関して スペルの指定を行うものです。指定可能な値は、 'american', 'british', 'canadian'です。

jargon

パラメータ jargon は、同じ language および spelling パラメータを有する 2 つの異なる単語リストを区別するための 追加情報を有しています。

encoding

パラメータ encoding は、単語のエンコーディングとして 予想されるものです。有効な値は、'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32' です。このパラメータはよくテストされていないため、 使用する際には注意してください。

戻り値

PSpell\Config クラスのインスタンスを返します。

変更履歴

バージョン | 説明
8.1.0 | PSpell\Config クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。

例

例1 pspell_config_create()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
$pspell = pspell_new_personal($pspell_config, "en");
?>


言語のデータファイルの場所

  • ≪ pspell_config_create
  • pspell_config_dict_dir ≫
  • PHP Manual
  • Pspell 関数
  • 言語のデータファイルの場所

pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — 言語のデータファイルの場所

説明

pspell_config_data_dir(PSpell\Config $config, string $directory): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


メイン単語リストの場所

  • ≪ pspell_config_data_dir
  • pspell_config_ignore ≫
  • PHP Manual
  • Pspell 関数
  • メイン単語リストの場所

pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — メイン単語リストの場所

説明

pspell_config_dict_dir(PSpell\Config $config, string $directory): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


長さが N 文字未満の単語を無視する

  • ≪ pspell_config_dict_dir
  • pspell_config_mode ≫
  • PHP Manual
  • Pspell 関数
  • 長さが N 文字未満の単語を無視する

pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — 長さが N 文字未満の単語を無視する

説明

pspell_config_ignore(PSpell\Config $config, int $min_length): bool

pspell_config_ignore() は、 pspell_new_config() をコールする前に使用しなければなりません。 この関数は、スペルチェッカに無視させる短い単語の長さを指定します。

パラメータ

config

PSpell\Config クラスのインスタンス。

min_length

min_length 文字より短い単語をスキップします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_config_ignore()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_ignore($pspell_config, 5);
$pspell = pspell_new_config($pspell_config);
pspell_check($pspell, "abcd"); // エラーとはなりません
?>


返される提案の数のモードを変更する

  • ≪ pspell_config_ignore
  • pspell_config_personal ≫
  • PHP Manual
  • Pspell 関数
  • 返される提案の数のモードを変更する

pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — 返される提案の数のモードを変更する

説明

pspell_config_mode(PSpell\Config $config, int $mode): bool

pspell_config_mode() は、
pspell_new_config() のコール前に設定を行う際に使用します。この関数は、
pspell_suggest() により返される修正候補の数を定義します。

パラメータ

config

PSpell\Config クラスのインスタンス。

mode

パラメータ mode は、スペルチェッカの動作モードです。 使用可能なモードを以下に示します。

  • PSPELL_FAST - 高速モード (修正候補の数は最小)
  • PSPELL_NORMAL - 通常モード (修正候補はより多い)
  • PSPELL_BAD_SPELLERS - 低速モード (修正候補は多い)

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_config_mode() の例

<?php
$pspell_config = pspell_config_create("en");
pspell_config_mode($pspell_config, PSPELL_FAST);
$pspell = pspell_new_config($pspell_config);
pspell_check($pspell, "thecat");
?>


個人の単語リストを保持するファイルを設定する

  • ≪ pspell_config_mode
  • pspell_config_repl ≫
  • PHP Manual
  • Pspell 関数
  • 個人の単語リストを保持するファイルを設定する

pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — 個人の単語リストを保持するファイルを設定する

説明

pspell_config_personal(PSpell\Config $config, string $filename): bool

個人の単語リストファイルを設定します。個人の単語リストは、 pspell_new_config()をコールした後にロードされ、 標準的な単語リストに追加されて使用されます。このファイルは、 pspell_save_wordlist() により個人的な単語リスト が保存されるファイルでもあります。

pspell_config_personal() は、 pspell_new_config() をコールする前に設定を行うために使用する必要があります。

パラメータ

config

PSpell\Config クラスのインスタンス。

filename

個人の単語リスト。存在しない場合は作成します。PHP の実行ユーザー (たとえば nobody) が書き込み可能である必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_config_personal()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
$pspell = pspell_new_config($pspell_config);
pspell_check($pspell, "thecat");
?>

注意

注意:

この関数は、 pspell .11.2 および aspell .32.5 以降でない限り動作しないことに注意してください。


置換候補を保持するファイルを設定する

  • ≪ pspell_config_personal
  • pspell_config_runtogether ≫
  • PHP Manual
  • Pspell 関数
  • 置換候補を保持するファイルを設定する

pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — 置換候補を保持するファイルを設定する

説明

pspell_config_repl(PSpell\Config $config, string $filename): bool

置換候補を保持するファイルを設定します。

置換の組は、スペルチェッカの品質を改善します。 単語のスペルミスをした場合、そして、適当な修正候補がリストにあった場合、 pspell_store_replacement() を置換候補を保存するために使用し、置換候補を含む単語リストを保存するために pspell_save_wordlist()を使用することが可能です。

pspell_config_repl() は、 pspell_new_config() をコールする前に設定を行うために使用する必要があります。

パラメータ

config

PSpell\Config クラスのインスタンス。

filename

このファイルは PHP の実行ユーザー (たとえば nobody) が書き込み可能である必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_config_repl()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
$pspell = pspell_new_config($pspell_config);
pspell_check($pspell, "thecat");
?>

注意

注意:

この関数は、pspell .11.2 および aspell .32.5 以降でない限り動作しないことに注意してください。


複合語を有効な単語の組み合わせとして考慮する

  • ≪ pspell_config_repl
  • pspell_config_save_repl ≫
  • PHP Manual
  • Pspell 関数
  • 複合語を有効な単語の組み合わせとして考慮する

pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — 複合語を有効な単語の組み合わせとして考慮する

説明

pspell_config_runtogether(PSpell\Config $config, bool $allow): bool

この関数は、複合語を正しい複合語として処理するかどうかを定義します。 つまり、"thecat" には、二つの単語の間に空白はありませんが、 正しい複合語となります。この設定の変更は、 pspell_check() による戻り値にのみ影響を与えます。 pspell_suggest() は、この場合でも修正候補を返します。

pspell_config_runtogether() は、 pspell_new_config() をコールする前に設定を行うために使用する必要があります。

パラメータ

config

PSpell\Config クラスのインスタンス。

allow

連続した単語を複合語として扱う場合な true、 それ以外の場合は false。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_config_runtogether()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_runtogether($pspell_config, true);
$pspell = pspell_new_config($pspell_config);
pspell_check($pspell, "thecat");
?>


単語リストと共に置換リストを保存するかどうかを定義する

  • ≪ pspell_config_runtogether
  • pspell_new ≫
  • PHP Manual
  • Pspell 関数
  • 単語リストと共に置換リストを保存するかどうかを定義する

pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — 単語リストと共に置換リストを保存するかどうかを定義する

説明

pspell_config_save_repl(PSpell\Config $config, bool $save): bool

pspell_config_save_repl() は、 pspell_save_wordlist() が単語リストと共に置換リストを保存するかどうかを定義します。 通常はこの関数を使用する必要はありません。なぜなら、 pspell_config_repl() を使用した場合は置換の組は pspell_save_wordlist() により保存され、 そうでない場合には置換の組は保存されないためです。

pspell_config_save_repl() は、 pspell_new_config() のコール前に設定を行う際に使用します。

パラメータ

config

PSpell\Config クラスのインスタンス。

save

置換リストを保存する場合に true、それ以外の場合に false。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

注意

注意:

この関数は、pspell .11.2およびaspell .32.5 以降を有していない場合には 動作しないことに注意してください。


新規辞書をロードする

  • ≪ pspell_config_save_repl
  • pspell_new_config ≫
  • PHP Manual
  • Pspell 関数
  • 新規辞書をロードする

pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — 新規辞書をロードする

説明

pspell_new(
string $language,
string $spelling = "",
string $jargon = "",
string $encoding = "",
int $mode = 0
): PSpell\Dictionary|false

pspell_new() は、新規の辞書をロードして PSpell\Dictionary クラスのインスタンスを返します。 このインスタンスは、他の pspell 関数で使用されます。

詳細な情報および例については、pspell の Web サイト :» http://aspell.net/ にあるインラインマニュアルを参照ください。

パラメータ

language

パラメータ language は、2 文字の ISO 639 言語コードと オプションでダッシュまたはアンダースコアの後に 2 文字の ISO 3166 国コードからなる言語コードです。

spelling

パラメータ spelling は、英語のように複数のスペルがある言語に関して スペルの指定を行うものです。指定可能な値は、 'american', 'british', 'canadian'です。

jargon

パラメータ jargon は、同じ language および spelling パラメータを有する 2 つの異なる単語リストを区別するための 追加情報を有しています。

encoding

パラメータ encoding は、単語のエンコーディングとして 予想されるものです。有効な値は、'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32' です。このパラメータはよくテストされていないため、 使用する際には注意してください。

mode

パラメータ mode は、スペルチェッカの動作モードです。 使用可能なモードを以下に示します。

  • PSPELL_FAST - 高速モード (修正候補の数は最小)
  • PSPELL_NORMAL - 通常モード (修正候補はより多い)
  • PSPELL_BAD_SPELLERS - 低速モード (修正候補は多い)
  • PSPELL_RUN_TOGETHER - つながった単語を複合語 （legal compound）として考慮します。この場合、"thecat" には二つの 単語の間に空白はありませんが複合語となります。この設定の変更は pspell_check() から返される結果にのみ影響します。 設定変更後も pspell_suggest() は修正候補を返します。
mode は、これらのさまざまな定数を用いたビットマスクです。 しかし PSPELL_FAST、 PSPELL_NORMAL および PSPELL_BAD_SPELLERS は相反するため、 この中のひとつを選択する必要があります。

戻り値

成功した場合に、 PSpell\Dictionary クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PSpell\Dictionary クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。

例

例1 pspell_new()

<?php
$pspell = pspell_new("en", "", "", "",
(PSPELL_FAST|PSPELL_RUN_TOGETHER));
?>


指定した設定に基づき新規辞書をロードする

  • ≪ pspell_new
  • pspell_new_personal ≫
  • PHP Manual
  • Pspell 関数
  • 指定した設定に基づき新規辞書をロードする

pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — 指定した設定に基づき新規辞書をロードする

説明

pspell_new_config(PSpell\Config $config): PSpell\Dictionary|false

pspell_new_config() は、 pspell_config_create() で作成され、 関数 pspell_config_*() で修正された config を使用して 新規辞書をオープンします。この方法は最も柔軟で、 pspell_new() および pspell_new_personal() で提供された全ての機能を有しています。

パラメータ

config

パラメータ config は、config が作成された際に pspell_config_create() により返されたパラメータです。

戻り値

成功した場合に PSpell\Dictionary クラスのインスタンスを返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 config は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
8.1.0 | PSpell\Dictionary クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。

例

例1 pspell_new_config()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
$pspell = pspell_new_config($pspell_config);
?>


個人の単語リストを有する新規辞書をロードする

  • ≪ pspell_new_config
  • pspell_save_wordlist ≫
  • PHP Manual
  • Pspell 関数
  • 個人の単語リストを有する新規辞書をロードする

pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — 個人の単語リストを有する新規辞書をロードする

説明

pspell_new_personal(
string $filename,
string $language,
string $spelling = "",
string $jargon = "",
string $encoding = "",
int $mode = 0
): PSpell\Dictionary|false

pspell_new_personal() は、個人の単語リストと共に
新規辞書をオープンし、辞書リンクIDを返します。この ID は他の
pspell 関数で使用されます。単語リストは修正可能で、必要に応じて
pspell_save_wordlist() で保存することも可能です。
しかし、置換の組は保存されません。置換の組を保存するには、
pspell_config_create() を用いて設定を作成し、
pspell_config_personal() で個人の単語リストを
設定し、pspell_config_repl() で置換のファイルを
設定し、pspell_new_config() で新規の辞書を
オープンします。

詳細な情報および例については、pspell の Web サイト :» http://aspell.net/ にあるインラインマニュアルを参照ください。

パラメータ

filename

個人リストに追加された単語が保存される場所を指定します。 この場所には '/' で始まる絶対パスのファイル名を指定する必要があります。 そうでない場合は $HOME からの相対パスになりますが、 これは多くのシステムでは、"/root" であり、 おそらく望ましい結果とはならないためです。

language

2 文字の ISO 639 言語コードと オプションでダッシュまたはアンダースコアの後に 2 文字の ISO 3166 国コードからなる言語コードです。

spelling

英語のように複数のスペルがある言語に関して スペルの指定を行うものです。指定可能な値は、 'american', 'british', 'canadian'です。

jargon

同じ language および spelling パラメータを有する 2 つの異なる単語リストを区別するための 追加情報を有しています。

encoding

単語のエンコーディングとして予想されるもの。有効な値は、 utf-8, iso8859-*, koi8-r, viscii, cp1252, machine unsigned 16, machine unsigned 32 です。

mode

スペルチェッカの動作モードです。 使用可能なモードを以下に示します。

  • PSPELL_FAST - 高速モード (修正候補の数は最小)
  • PSPELL_NORMAL - 通常モード (修正候補はより多い)
  • PSPELL_BAD_SPELLERS - 低速モード (修正候補は多い)
  • PSPELL_RUN_TOGETHER - つながった単語を複合語 （legal compound）として考慮します。この場合、"thecat" には二つの 単語の間に空白はありませんが複合語となります。この設定の変更は pspell_check() から返される結果にのみ影響します。 設定変更後も pspell_suggest() は修正候補を返します。
mode は、これらのさまざまな定数を用いたビットマスクです。 しかし PSPELL_FAST、 PSPELL_NORMAL および PSPELL_BAD_SPELLERS は相反するため、 この中のひとつを選択する必要があります。

戻り値

成功した場合に、 PSpell\Dictionary クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | PSpell\Dictionary クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。

例

例1 pspell_new_personal()

<?php
$pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
"en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
?>


個人の単語リストをファイルに保存する

  • ≪ pspell_new_personal
  • pspell_store_replacement ≫
  • PHP Manual
  • Pspell 関数
  • 個人の単語リストをファイルに保存する

pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — 個人の単語リストをファイルに保存する

説明

pspell_save_wordlist(PSpell\Dictionary $dictionary): bool

pspell_save_wordlist() は、 現在のセッションから個人の単語リストを保存します。 ファイルの位置は pspell_config_personal() および(オプションで) pspell_config_repl() で指定されている必要があります。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_add_to_personal()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
$pspell = pspell_new_config($pspell_config);

pspell_add_to_personal($pspell, "Vlad");
pspell_save_wordlist($pspell);
?>

注意

注意:

この関数は、pspell .11.2 および aspell .32.5 以降がない限り動作しないことに注意してください。


単語を置換する組を保存する

  • ≪ pspell_save_wordlist
  • pspell_suggest ≫
  • PHP Manual
  • Pspell 関数
  • 単語を置換する組を保存する

pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — 単語を置換する組を保存する

説明

pspell_store_replacement(PSpell\Dictionary $dictionary, string $misspelled, string $correct): bool

pspell_store_replacement() は、単語の置換候補を 保存します。これにより、この後の pspell_suggest() で置換候補を返すことが可能と なります。この関数の利点を活かすためには、辞書をオープンする際に pspell_new_personal() を使用する必要があります。 置換候補を恒久的に保存するためには pspell_config_personal() を使用する必要があり、 pspell_config_repl() によりカスタム単語リストを 保存するパスを設定し、この後、変更点をディスクへ書き込むために pspell_save_wordlist() を使用する必要があります。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

misspelled

まちがったスペルの単語。

correct

misspelled を修正した単語。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_store_replacement()

<?php
$pspell_config = pspell_config_create("en");
pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
$pspell = pspell_new_config($pspell_config);

pspell_store_replacement($pspell, $misspelled, $correct);
pspell_save_wordlist($pspell);
?>

注意

注意:

この関数は、pspell .11.2 および aspell .32.5 以降でない限り 動作しないことに注意してください。


単語のスペルについて修正候補を示す

  • ≪ pspell_store_replacement
  • PSpell\Dictionary ≫
  • PHP Manual
  • Pspell 関数
  • 単語のスペルについて修正候補を示す

pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — 単語のスペルについて修正候補を示す

説明

pspell_suggest(PSpell\Dictionary $dictionary, string $word): array|false

pspell_suggest() は、 指定した単語について可能性のあるスペルの配列を返します。

パラメータ

dictionary

PSpell\Dictionary クラスのインスタンス。

word

調べたい単語。

戻り値

修正候補の配列を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 dictionary は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 pspell_suggest() の例

<?php
$pspell = pspell_new("en");

if (!pspell_check($pspell, "testt")) {
$suggestions = pspell_suggest($pspell, "testt");

foreach ($suggestions as $suggestion) {
echo "Possible spelling: $suggestion<br />";
}
}
?>


PSpell\Dictionary クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、pspell リソースを置き換える、完全不定形クラスです。

クラス概要

final class PSpell\Dictionary {
}


PSpell\Config クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、pspell 設定 リソースを置き換える、完全不定形クラスです。

クラス概要

final class PSpell\Config {
}


GNU Recode

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Recode 関数
    • recode — recode_string のエイリアス
    • recode_file — コード変換指令に基づきファイルからファイルにコード変換する
    • recode_string — コード変換指令に基づき文字列のコードを変換する


はじめに

このモジュールは、GNU recode ライブラリへのインターフェイスを 有しています。GNU Recode ライブラリは、様々にコード化された 文字や表面的なエンコード法を相互に変換します。 正確に変換できない場合、問題のある文字を削除するか近似を行います。 このライブラリは、約 150 種類の文字セットを認識、生成することが可能で、 ほとんど全ての組み合わせで相互の変換を行うことができます。 » RFC 1345 文字セットの ほとんどがサポートされています。

注意: PHp 7.4.0 以降、この拡張モジュールは PHP 本体にバンドルされなくなり、 » PECL に移動しました。 代わりに、マルチバイト文字列 または iconv 拡張モジュールの利用を検討してください。

注意: この拡張モジュールは Windows 環境では利用できません。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Recode
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

GNU Recode 3.5 以降をシステムにインストールしておく必要があります。 このパッケージは、» http://directory.fsf.org/All_GNU_Packages/recode.html から ダウンロードすることが可能です。

警告

Recode ライブラリのバージョン 3.6 は、ある状況下での文字列の変換時に 変な文字を付加してしまうことがあります。そのため、Recode v3.5 か、あるいは別の選択肢として iconv あるいは mbstring 拡張モジュールを使用するほうが安全です。


インストール手順

PHP 7.4 以降

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/recode.

PHP < 7.4

本モジュールで定義された関数を使用するには、--with-recode[=DIR] オプションを指定して PHP インタプリタをコンパイルする必要があります。

警告

拡張モジュール mysql または imap をロードした 後に recode を拡張モジュールとしてロードした場合に、 PHP のクラッシュおよび起動に関する問題が 発生する可能性があります。これらの拡張モジュールの前に recode を ロードすることにより、問題を解決することができます。 これは、imap で使用されている c-client ライブラリおよび recode の両方が 固有の hash_lookup() 関数を有しており、 mysql と recode が固有の hash_insert 関数を有している ことによる技術的な問題です。

警告

IMAP、recode、 YAZ 拡張モジュールは、組み合わせて使用することはできません。 これは、これらすべてが同一の内部シンボルを使用しているためです。 注意: Yaz 2.0 以降ではこの問題は発生しません。


Recode 関数

目次

  • recode — recode_string のエイリアス
  • recode_file — コード変換指令に基づきファイルからファイルにコード変換する
  • recode_string — コード変換指令に基づき文字列のコードを変換する


recode_string のエイリアス

  • ≪ Recode 関数
  • recode_file ≫
  • PHP Manual
  • Recode 関数
  • recode_string のエイリアス

recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — recode_string() のエイリアス

説明

この関数は次の関数のエイリアスです。 recode_string().


コード変換指令に基づきファイルからファイルにコード変換する

  • ≪ recode
  • recode_string ≫
  • PHP Manual
  • Recode 関数
  • コード変換指令に基づきファイルからファイルにコード変換する

recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — コード変換指令に基づきファイルからファイルにコード変換する

説明

recode_file(string $request, resource $input, resource $output): bool

コード変換指令 request に基づきファイルハンドル input が指すファイルをファイルハンドル output が指すファイルにコード変換します。

パラメータ

request

変換指令の型。

input

入力として使用する ローカルファイルハンドルリソース。

output

出力として使用する ローカルファイルハンドルリソース。

戻り値

応じることができない場合に false、それ以外の場合に true を返します。

例

例1 基本的な recode_file() の例

<?php
$input = fopen('input.txt', 'r');
$output = fopen('output.txt', 'w');
recode_file("us..flat", $input, $output);
?>

注意

この関数は現在リモートファイル(URL)を指すファイルハンドルを処理 できません。ファイルハンドルは共にローカルなファイルを指している 必要があります。

参考

  • fopen() - ファイルまたは URL をオープンする


コード変換指令に基づき文字列のコードを変換する

  • ≪ recode_file
  • 画像処理および作成 ≫
  • PHP Manual
  • Recode 関数
  • コード変換指令に基づき文字列のコードを変換する

recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — コード変換指令に基づき文字列のコードを変換する

説明

recode_string(string $request, string $string): string

コード変換指令 request に基づき文字列 string のコードを変換します。

パラメータ

request

変換指令の型。

string

変換する文字列。

戻り値

変換後の文字列、または変換指令を実行できない場合に false を返します。

例

例1 基本的な recode_string() の例

<?php
echo recode_string("us..flat", "The following character has a diacritical mark: a");
?>

注意

簡単なコード変換指令は、"lat1..iso646-de" のようになります。

参考

  • コード変換指令に関する詳細な手順に関しては、インストールされている GNU Recode のドキュメントも参照ください。
  • mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • UConverter::transcode() - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


画像処理および作成

  • Exif — Exchangeable image information
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Exif 関数
  • GD — 画像処理 (GD)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GD および Image 関数
    • GdImage — GdImage クラス
    • GdFont — GdFont クラス
  • Gmagick
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Gmagick — Gmagick クラス
    • GmagickDraw — GmagickDraw クラス
    • GmagickPixel — GmagickPixel クラス
  • ImageMagick — 画像処理 (ImageMagick)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Imagick — Imagick クラス
    • ImagickDraw — ImagickDraw クラス
    • ImagickPixel — ImagickPixel クラス
    • ImagickPixelIterator — ImagickPixelIterator クラス
    • ImagickKernel — The ImagickKernel class


Exchangeable image information

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Exif 関数
    • exif_imagetype — イメージの型を定義する
    • exif_read_data — 画像ファイルから EXIF ヘッダを読み込む
    • exif_tagname — インデックスに対応するヘッダ名を取得する
    • exif_thumbnail — 画像に埋め込まれたサムネイルを取得する
    • read_exif_data — のエイリアス exif_read_data


はじめに

exif 拡張モジュールを使用すると、画像のメタデータを扱うことが可能と なります。例えば、デジタルカメラで撮影した画像ファイルから 画像のヘッダ情報を読み込むために exif 関数を使用することができます。 こうした情報は、通常 JPEG や TIFF 画像で見つかります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Exif
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

--enable-exif オプションを用いて PHP をコンパイルする必要があります。 EXIF タグでマルチバイトのサポートを有効にするには、 --enable-mbstring を用いてPHPをコンパイルすることで、 mbstring 拡張モジュールを有効にしなければいけません。 exif モジュールを作成するために、追加の ライブラリは一切必要ありません。

Windows のみ: mbstring 拡張モジュールは常に有効でなければなりません。 mbstring 拡張モジュールは、 php.ini で EXIF より前にロードされなければなりません。


インストール手順

exif サポートを有効にするには、PHP の configure 時に --enable-exif を指定します。

Windows ユーザーは、php.ini で php_mbstring.dll および php_exif.dll の両方の DLL を有効にする 必要があります。php_mbstring.dll DLL は、必ず php_exif.dll DLL より 先に 読み込まれていなければなりません。そうなるように php.ini で設定 してください。


実行時設定

php.ini の設定により動作が変化します。

mbstring が有効になっている場合、 Exif 拡張モジュールはユーザーコメントの文字エンコーディングの変換 （Unicode と JIS）を自動的に行います。この処理が行われるのは、 指定した文字セットを使用して最初にコメントをデコードする際です。 その結果は、HTTP 出力用の文字コードにエンコード されます。

Exif 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
exif.encode_unicode | "ISO-8859-15" | INI_ALL |
exif.decode_unicode_motorola | "UCS-2BE" | INI_ALL |
exif.decode_unicode_intel | "UCS-2LE" | INI_ALL |
exif.encode_jis | "" | INI_ALL |
exif.decode_jis_motorola | "JIS" | INI_ALL |
exif.decode_jis_intel | "JIS" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

exif.encode_unicode string

exif.encode_unicode は、UNICODE ユーザーコメント を処理する文字セットを定義します。デフォルトは ISO-8859-15 で、 アジア以外のほとんどの国で動作します。この設定は、空白 あるいは mbstring のサポートするエンコーディングである必要があります。 空白の場合は mbstring の内部エンコーディング設定が使用されます。

exif.decode_unicode_motorola string

exif.decode_unicode_motorola は、画像の バイトオーダーがモトローラ形式（ビッグエンディアン）であった場合に Unicode のユーザーコメントを扱うための内部文字セットを定義します。 この設定は空白にすることはできず、mbstring がサポートしている エンコーディングの中から指定します。デフォルトは UCS-2BE です。

exif.decode_unicode_intel string

exif.decode_unicode_intel は、画像の バイトオーダーがインテル形式（リトルエンディアン）であった場合に Unicode のユーザーコメントを扱うための内部文字セットを定義します。 この設定は空白にすることはできず、mbstring がサポートしている エンコーディングの中から指定します。デフォルトは UCS-2LE です。

exif.encode_jis string

exif.encode_jis は、JIS ユーザーコメントを 処理する文字セットを定義します。デフォルトは空白で、これは mbstring の内部設定を使用させることを意味します。

exif.decode_jis_motorola string

exif.decode_jis_motorola は、画像の バイトオーダーがモトローラ形式（ビッグエンディアン）であった場合に JIS のユーザーコメントを扱うための内部文字セットを定義します。 この設定は空白にすることはできず、mbstring がサポートしている エンコーディングの中から指定します。デフォルトは JIS です。

exif.decode_jis_intel string

exif.decode_jis_intel は、画像の バイトオーダーがインテル形式（リトルエンディアン）であった場合に JIS のユーザーコメントを扱うための内部文字セットを定義します。 この設定は空白にすることはできず、mbstring がサポートしている エンコーディングの中から指定します。デフォルトは JIS です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

EXIF_USE_MBSTRING (int)
mbstring が有効な場合、 この定数は 1 という値です。 それ以外の場合、値は 0 です。

exif_imagetype() は、関連するいくつかの組み込み定数を 一覧表示します。


Exif 関数

目次

  • exif_imagetype — イメージの型を定義する
  • exif_read_data — 画像ファイルから EXIF ヘッダを読み込む
  • exif_tagname — インデックスに対応するヘッダ名を取得する
  • exif_thumbnail — 画像に埋め込まれたサムネイルを取得する
  • read_exif_data — のエイリアス exif_read_data


イメージの型を定義する

  • ≪ Exif 関数
  • exif_read_data ≫
  • PHP Manual
  • Exif 関数
  • イメージの型を定義する

exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — イメージの型を定義する

説明

exif_imagetype(string $filename): int|false

exif_imagetype() を画像の先頭バイトを読み そのサインを調べます。

exif_imagetype() は、他の exif 関数がサポートしていないファイル形式で コールされるの防いだり、$_SERVER['HTTP_ACCEPT'] と組み合わせて閲覧者が画像を見る権限を持っているかどうかを調べたりするために 使用可能です。

パラメータ

filename
調べる画像。

戻り値

正しいサインが見つかった場合は適切な定数、それ以外の場合は false を返します。戻り値は getimagesize() がインデックス 2 に対して返す値と同じですが、exif_imagetype() のほうがずっと早く動作します。

以下の定数が定義されており、exif_imagetype() の戻り値を表しています。

Imagetype 定数
値 | 定数
1 | IMAGETYPE_GIF
2 | IMAGETYPE_JPEG
3 | IMAGETYPE_PNG
4 | IMAGETYPE_SWF
5 | IMAGETYPE_PSD
6 | IMAGETYPE_BMP
7 | IMAGETYPE_TIFF_II (intel byte order)
8 | IMAGETYPE_TIFF_MM (motorola byte order)
9 | IMAGETYPE_JPC
10 | IMAGETYPE_JP2
11 | IMAGETYPE_JPX
12 | IMAGETYPE_JB2
13 | IMAGETYPE_SWC
14 | IMAGETYPE_IFF
15 | IMAGETYPE_WBMP
16 | IMAGETYPE_XBM
17 | IMAGETYPE_ICO
18 | IMAGETYPE_WEBP
19 | IMAGETYPE_AVIF

注意:

画像の形式を判別するために必要なだけのバイト数を読み込めない場合、 exif_imagetype() は E_NOTICE を発行して false を返します。

変更履歴

バージョン | 説明
7.1.0 | WebP をサポートしました
8.1.0 | AVIF をサポートしました。

例

例1 exif_imagetype() の例

<?php
if (exif_imagetype('image.gif') != IMAGETYPE_GIF) {
echo 'The picture is not a gif';
}
?>

参考

  • image_type_to_mime_type() - getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する
  • getimagesize() - 画像の大きさを取得する


画像ファイルから EXIF ヘッダを読み込む

  • ≪ exif_imagetype
  • exif_tagname ≫
  • PHP Manual
  • Exif 関数
  • 画像ファイルから EXIF ヘッダを読み込む

exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — 画像ファイルから EXIF ヘッダを読み込む

説明

exif_read_data(
resource|string $file,
?string $required_sections = null,
bool $as_arrays = false,
bool $read_thumbnail = false
): array|false

exif_read_data() は、 画像ファイルから EXIF ヘッダを読み込みます。この方法で、デジタルカメラが生成したメタデータを 読み込むことが可能です。

EXIF ヘッダは、デジタルカメラが作成した JPEG/TIFF 画像によく含まれています。しかし残念なことに、 そのタグ付けの方法はメーカーによって異なります。 したがって、特定の Exif ヘッダが常に存在すると仮定することはできません。

Height および Width は、getimagesize() と同じ方法で計算されます。 よって、これらの値は決してヘッダの一部として返してはいけません。 また、html は高さ/幅を表すテキスト文字列で、 通常の HTML の中で用いられます。

Exif ヘッダに著作権表示が含まれている場合、それ自身には 2 つの値を 含めることが可能です。Exif 2.10 のこの矛盾した規格に対応するため、 COMPUTED セクションは Copyright.Photographer および Copyright.Editor の両方を返します。 また IFD0 セクションには 2 つのエントリを NULL 文字で区切った バイト配列を含めます。データ型が間違っている場合は最初のエントリのみを かえします（Exif の通常の挙動）。COMPUTED には、元の著作権文字列あるいは カンマで区切られた写真と編集者の著作権表示のどちらかを Copyright エントリに含めることが可能です。

UserComment タグにも Copyright タグと同様の問題があります。ここにも 2 つの値を格納することが可能です。それは使用しているエンコーディングと 値自身の 2 つです。そうなると、IFD セクションにはエンコーディングのみを 含めるか、あるいはバイト配列を格納することになります。COMPUTED セクションは UserCommentEncoding および UserComment を両方格納することができます。UserComment はどちらの 場合でも有効なので、IFD0 セクションではこちらを優先すべきです。

exif_read_data() は、EXIF 仕様（» http://exif.org/Exif2-2.PDF, 20 ページ）に基づいて EXIF データタグの検証も行います。

パラメータ

file

画像ファイルの位置。 ファイルのパス (ストリームラッパーもいつもどおりサポートされています) またはストリームresource。

required_sections

結果の配列を作成するために存在する必要のあるセクションのカンマ区切り リスト。要求されたセクションがひとつも見つからなかった場合の戻り値は false となります。

FILE | FileName, FileSize, FileDateTime, SectionsFound
COMPUTED | html, Width, Height, IsColor, および他の取得可能なもの。Height および Width は getimagesize() と同じ方法で取得した もので、その値はヘッダの一部ではありません。また、html は 通常の HTML 内で使用される height/width の 文字列です。
ANY_TAG | タグを有するすべての情報。例えば IFD0, EXIF, ...
IFD0 | IFD0 のすべてのタグつきデータ。通常の画像ファイルでは、 ここに画像のサイズが含まれます。
THUMBNAIL | 2 番目の IFD がある場合、ファイルにサムネイルが含まれている 可能性があります。埋め込まれたサムネイルに関するすべての タグつき情報はこのセクションに格納されます。
COMMENT | JPEG 画像のコメントヘッダ。
EXIF | EXIF セクションは IFD0 のサブセクションです。ここには 画像に関する詳細な情報が含まれています。これらのエントリの ほとんどはデジタルカメラに関連するものです。

as_arrays

各セクションを配列とするかどうかを指定します。 required_sections の COMPUTED、 THUMBNAIL および COMMENT は常に配列となります。これは、これらのセクションに 含まれる値の名前が他のセクションと衝突する可能性があるからです。

read_thumbnail

true を指定すると、サムネイル本体を読み込みます。それ以外の場合は タグつきデータのみを読み込みます。

戻り値

ヘッダ名がキー・ヘッダの内容が値となる連想配列を返します。 返されるデータがない場合は exif_read_data() は false を返します。

エラー / 例外

サポートされていないタグや、エラーが起きうる条件が指定された場合は、 E_WARNING かつ/または E_NOTICE が発生します。 警告が発生しても、この関数は対応する情報を全て読み取ろうとします。

変更履歴

バージョン | 説明
8.0.0 | required_sections は、nullable になりました。
7.2.0 | file パラメータは ローカルファイルとストリームリソースを両方サポートするようになりました。
7.2.0

以下の EXIF フォーマットのサポートが追加されました:

  • Samsung
  • DJI
  • Panasonic
  • Sony
  • Pentax
  • Minolta
  • Sigma/Foveon
  • AGFA
  • Kyocera
  • Ricoh
  • Epson

例

例1 exif_read_data() の例

<?php
echo "test1.jpg:<br />\n";
$exif = exif_read_data('tests/test1.jpg', 'IFD0');
echo $exif===false ? "No header data found.<br />\n" : "Image contains headers<br />\n";

$exif = exif_read_data('tests/test2.jpg', 0, true);
echo "test2.jpg:<br />\n";
foreach ($exif as $key => $section) {
foreach ($section as $name => $val) {
echo "$key.$name: $val<br />\n";
}
}
?>

最初のコールは失敗します。画像がヘッダ情報を有していないためです。

上の例の出力は、 たとえば以下のようになります。

test1.jpg:
No header data found.
test2.jpg:
FILE.FileName: test2.jpg
FILE.FileDateTime: 1017666176
FILE.FileSize: 1240
FILE.FileType: 2
FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
COMPUTED.html: width="1" height="1"
COMPUTED.Height: 1
COMPUTED.Width: 1
COMPUTED.IsColor: 1
COMPUTED.ByteOrderMotorola: 1
COMPUTED.UserComment: Exif test image.
COMPUTED.UserCommentEncoding: ASCII
COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
COMPUTED.Copyright.Editor: Edited by M.Boerger.
IFD0.Copyright: Photo (c) M.Boerger
IFD0.UserComment: ASCII
THUMBNAIL.JPEGInterchangeFormat: 134
THUMBNAIL.JPEGInterchangeFormatLength: 523
COMMENT.0: Comment #1.
COMMENT.1: Comment #2.
COMMENT.2: Comment #3end
THUMBNAIL.JPEGInterchangeFormat: 134
THUMBNAIL.Thumbnail.Height: 1
THUMBNAIL.Thumbnail.Height: 1

例2 PHP 7.2.0 で利用できるストリームを exif_read_data() で使う例

<?php
// Open a the file, this should be in binary mode
$fp = fopen('/path/to/image.jpg', 'rb');

if (!$fp) {
echo 'Error: Unable to open image for reading';
exit;
}

// Attempt to read the exif headers
$headers = exif_read_data($fp);

if (!$headers) {
echo 'Error: Unable to read exif headers';
exit;
}

// Print the 'COMPUTED' headers
echo 'EXIF Headers:' . PHP_EOL;

foreach ($headers['COMPUTED'] as $header => $value) {
printf(' %s => %s%s', $header, $value, PHP_EOL);
}
?>

上の例の出力は、 たとえば以下のようになります。

EXIF Headers:
 Height => 576
 Width => 1024
 IsColor => 1
 ByteOrderMotorola => 0
 ApertureFNumber => f/5.6
 UserComment =>
 UserCommentEncoding => UNDEFINED
 Copyright => Denis
 Thumbnail.FileType => 2
 Thumbnail.MimeType => image/jpeg

注意

注意:

mbstring が有効な場合、 exif はUnicodeを処理し、 exif.decode_unicode_motorola および exif.decode_unicode_intel で指定された文字コードとして取り出そうとします。 exif 拡張モジュールはエンコーディングを自分自身で探そうとはしないので、 exif_read_data() を呼ぶ前に、 これらの ini ディレクティブのうちのひとつに どのエンコーディングをデコードに使うかを適切に設定するのはユーザーの責任です。

注意:

この関数にストリームを渡すために file を使った場合、 ストリームはシーク可能でなければなりません。 ファイルポインタの位置は、関数から戻った後でも変化しないことに注意してください。

参考

  • exif_thumbnail() - 画像に埋め込まれたサムネイルを取得する
  • getimagesize() - 画像の大きさを取得する
  • サポートするプロトコル/ラッパー


インデックスに対応するヘッダ名を取得する

  • ≪ exif_read_data
  • exif_thumbnail ≫
  • PHP Manual
  • Exif 関数
  • インデックスに対応するヘッダ名を取得する

exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — インデックスに対応するヘッダ名を取得する

説明

exif_tagname(int $index): string|false

パラメータ

index

名前を調べたいタグの ID。

戻り値

ヘッダ名を返します。もし index が EXIF タグ ID として未定義の場合は false を返します。

例

例1 exif_tagname() の例

<?php
echo "256: ".exif_tagname(256).PHP_EOL;
echo "257: ".exif_tagname(257).PHP_EOL;
?>

上の例の出力は以下となります。

256: ImageWidth
257: ImageLength

参考

  • exif_imagetype() - イメージの型を定義する
  • » EXIF 仕様
  • » EXIF タグ


画像に埋め込まれたサムネイルを取得する

  • ≪ exif_tagname
  • read_exif_data ≫
  • PHP Manual
  • Exif 関数
  • 画像に埋め込まれたサムネイルを取得する

exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — 画像に埋め込まれたサムネイルを取得する

説明

exif_thumbnail(
resource|string $file,
int &$width = null,
int &$height = null,
int &$image_type = null
): string|false

exif_thumbnail() は、 画像に埋め込まれたサムネイルを読み込みます。

この関数を使用してサムネイルを出力したい場合は、 header() 関数を使用して mimetype 情報を送信する 必要があります。

exif_thumbnail() が画像を作成することはできないが、 そのサイズだけはわかるという可能性があります。そのような場合、戻り値は false となりますが width および height を設定されています。

パラメータ

file

読み込む画像ファイルの名前。サムネイルが埋め込まれています。 画像ファイルの位置。これはファイルのパスか、ストリーム resource です。

width

返されるサムネイルの幅が格納されます。

height

返されるサムネイルの高さが格納されます。

image_type

返されるサムネイルの画像タイプが格納されます。 TIFF あるいは JPEG のどちらかです。

戻り値

埋め込まれたサムネイルを返します。画像がサムネイルを含まない場合は false を返します。

変更履歴

バージョン | 説明
7.2.0 | file パラメータは ローカルファイルとストリームリソースを両方サポートするようになりました。

例

例1 exif_thumbnail() の例

<?php
$image = exif_thumbnail('/path/to/image.jpg', $width, $height, $type);
if ($image!==false) {
header('Content-type: ' .image_type_to_mime_type($type));
echo $image;
exit;
} else {
// no thumbnail available, handle the error here
echo 'No thumbnail available';
}
?>

注意

注意:

この関数にストリームを渡すために file を使った場合、 ストリームはシーク可能でなければなりません。 ファイルポインタの位置は、関数から戻った後でも変化しないことに注意してください。

参考

  • exif_read_data() - 画像ファイルから EXIF ヘッダを読み込む
  • image_type_to_mime_type() - getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する


のエイリアス exif_read_data

  • ≪ exif_thumbnail
  • GD ≫
  • PHP Manual
  • Exif 関数
  • のエイリアス exif_read_data

read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — のエイリアス exif_read_data()

警告

このエイリアスは PHP 7.2.0 で 非推奨 となり、PHP 8.0.0 で 削除 されました。

説明

この関数は次の関数のエイリアスです。 exif_read_data().

変更履歴

バージョン | 説明
7.2.0 | この関数エイリアスは非推奨になりました。


画像処理 (GD)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • PHP による PNG の生成
    • アルファチャネルを使用した、画像へのすかしの追加
    • imagecopymerge による半透明なすかしの作成
  • GD および Image 関数
    • gd_info — 現在インストールされているGDライブラリに関する情報を取得する
    • getimagesize — 画像の大きさを取得する
    • getimagesizefromstring — 画像の大きさを文字列から取得する
    • image_type_to_extension — 画像形式からファイルの拡張子を取得する
    • image_type_to_mime_type — getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する
    • image2wbmp — 画像をブラウザあるいはファイルに出力する
    • imageaffine — 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す
    • imageaffinematrixconcat — 二つのアフィン変換行列を連結する
    • imageaffinematrixget — アフィン変換行列を取得する
    • imagealphablending — イメージのブレンドモードを設定する
    • imageantialias — アンチエイリアス機能を使用すべきかどうかを判断する
    • imagearc — 部分楕円を描画する
    • imageavif — 画像をブラウザあるいはファイルに出力する
    • imagebmp — ビットマップ画像をブラウザかファイルに出力する
    • imagechar — 水平に文字を描画する
    • imagecharup — 垂直に文字を描画する
    • imagecolorallocate — 画像で使用する色を作成する
    • imagecolorallocatealpha — 画像で使用する色を透過度を指定して作成する
    • imagecolorat — ピクセルの色のインデックスを取得する
    • imagecolorclosest — 指定した色に最も近い色のインデックスを取得する
    • imagecolorclosestalpha — 指定した色+アルファ値に最も近い色のインデックスを取得する
    • imagecolorclosesthwb — 色合い、白、黒を有する色のインデックスを得る
    • imagecolordeallocate — イメージの色リソースを開放する
    • imagecolorexact — 指定した色のインデックスを取得する
    • imagecolorexactalpha — 指定した色+アルファ値のインデックスを取得する
    • imagecolormatch — パレットイメージの色を True カラーイメージに近づける
    • imagecolorresolve — 指定した色または出来るだけ近い色のインデックスを得る
    • imagecolorresolvealpha — 指定した色+アルファ値または最も近い色のインデックスを取得する
    • imagecolorset — 指定したパレットインデックスの色を設定する
    • imagecolorsforindex — カラーインデックスからカラーを取得する
    • imagecolorstotal — 画像パレットの色数を検出する
    • imagecolortransparent — 透明色を定義する
    • imageconvolution — div および offset の係数を使用し、3x3 の畳み込み配列を適用する
    • imagecopy — 画像の一部をコピーする
    • imagecopymerge — イメージの一部をコピー、マージする
    • imagecopymergegray — グレースケールでイメージの一部をコピー、マージする
    • imagecopyresampled — 再サンプリングを行いイメージの一部をコピー、伸縮する
    • imagecopyresized — 画像の一部をコピーしサイズを変更する
    • imagecreate — パレットを使用する新規画像を作成する
    • imagecreatefromavif — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する
    • imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する
    • imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する
    • imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する
    • imagecreatefromtga — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromwbmp — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromwebp — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromxbm — 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromxpm — 新しい画像をファイルあるいは URL から作成する
    • imagecreatetruecolor — TrueColor イメージを新規に作成する
    • imagecrop — 指定した矩形に画像をクロップする
    • imagecropauto — 利用可能なモードを指定して、画像を自動的にクロップする
    • imagedashedline — 破線を描画する
    • imagedestroy — 画像を破棄する
    • imageellipse — 楕円を描画する
    • imagefill — 塗り潰す
    • imagefilledarc — 楕円弧を描画し、塗りつぶす
    • imagefilledellipse — 塗りつぶされた楕円を描画する
    • imagefilledpolygon — 塗りつぶした多角形を描画する
    • imagefilledrectangle — 塗りつぶした矩形を描画する
    • imagefilltoborder — 特定色で塗りつぶす
    • imagefilter — 画像にフィルタを適用する
    • imageflip — 指定したモードで画像を反転させる
    • imagefontheight — フォントの高さを取得する
    • imagefontwidth — フォントの幅を取得する
    • imageftbbox — freetype2 によるフォントを用いたテキストを囲む箱を取得する
    • imagefttext — FreeType 2 によるフォントを用いてイメージにテキストを描画する
    • imagegammacorrect — GD イメージにガンマ補正を適用する
    • imagegd — GD イメージをブラウザまたはファイルに出力する
    • imagegd2 — GD2 イメージをブラウザまたはファイルに出力する
    • imagegetclip — 長方形を切り取り、画像として取得する
    • imagegetinterpolation — 補間方法を取得する
    • imagegif — 画像をブラウザあるいはファイルに出力する
    • imagegrabscreen — 画面全体をキャプチャする
    • imagegrabwindow — ウィンドウをキャプチャする
    • imageinterlace — インターレースを有効もしくは無効にする
    • imageistruecolor — 画像が truecolor かどうか調べる
    • imagejpeg — 画像をブラウザあるいはファイルに出力する
    • imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する
    • imageline — 直線を描画する
    • imageloadfont — 新しいフォントを読み込む
    • imageopenpolygon — オープンポリゴンを描画する
    • imagepalettecopy — あるイメージから他のイメージにパレットをコピーする
    • imagepalettetotruecolor — パレット形式の画像を true color に変換する
    • imagepng — PNG イメージをブラウザまたはファイルに出力する
    • imagepolygon — 多角形を描画する
    • imagerectangle — 矩形を描画する
    • imageresolution — 画像の解像度を取得/設定する
    • imagerotate — 指定された角度で画像を回転する
    • imagesavealpha — 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する
    • imagescale — 幅と高さを指定して、画像の縮尺を変更する
    • imagesetbrush — 線の描画用にブラシイメージを設定する
    • imagesetclip — 切り取る長方形を設定する
    • imagesetinterpolation — 補間方法を設定する
    • imagesetpixel — 点を生成する
    • imagesetstyle — 線描画用のスタイルを設定する
    • imagesetthickness — 線描画用の線幅を設定する
    • imagesettile — 塗りつぶし用のイメージを設定する
    • imagestring — 文字列を水平に描画する
    • imagestringup — 文字列を垂直に描画する
    • imagesx — 画像の幅を取得する
    • imagesy — 画像の高さを取得する
    • imagetruecolortopalette — TrueColor イメージをパレットイメージに変換する
    • imagettfbbox — TypeType フォントを使用したテキストの bounding box を生成する
    • imagettftext — TrueType フォントを使用してテキストを画像に書き込む
    • imagetypes — この PHP がサポートしている画像形式を返す
    • imagewbmp — 画像をブラウザあるいはファイルに出力する
    • imagewebp — WebP 画像をブラウザあるいはファイルに出力する
    • imagexbm — XBM 画像をブラウザあるいはファイルに出力する
    • iptcembed — バイナリ IPTC データを JPEG イメージに埋めこむ
    • iptcparse — バイナリの IPTC ブロックのタグをパースする
    • jpeg2wbmp — JPEG画像をWBMP画像に変換する
    • png2wbmp — PNG画像をWBMP画像に変換する
  • GdImage — GdImage クラス
  • GdFont — GdFont クラス


はじめに

PHPができることは、HTML出力を生成することだけではありません。PHP は、多くの異なるイメージ形式でイメージファイルを作成したり、操作 したりすることもできます。このイメージ形式には、GIF, PNG, JPEG, WBMP および XPM が含まれます。 さらに便利なことに、PHPはイメージストリームを直接ブラウザに出力することができます。 イメージ関数を使用するには、PHP を GD ライブラリとともにコンパイルしなければなりません。 使用したいイメージ形式によっては、GD と PHP 以外に他のライブラリも必要となる可能性があります。

PHPのイメージ関数により JPEG、GIF、 PNG、SWF、 TIFF、JPEG2000イメージの 大きさを知ることができます。

exif 拡張モジュール を使用すると、 JPEG や TIFF 画像のヘッダに保存された情報を扱うことができます。 これにより、デジタルカメラが作成したメタデータを読み込むことができます。 exif 関数は GD ライブラリは必要ありません。

注意: イメージの読み込み、書き込み、修正の機能を拡張するには、 要求の節を呼んでください。 デジタルカメラで撮影した画像のメタデータを読み込むには、 上で説明した exif 拡張モジュール が必要です。

注意: getimagesize() 関数は、GD 拡張モジュールは必要ありません。

警告

バンドルされている GD ライブラリは、メモリを確保するのに Zend メモリマネージャーを使っていますが、 システムにインストールされている GD ライブラリは使っていません。 よって、後者には memory_limit は適用されません。

GD はさまざまなフォーマットに対応しています。 GD がサポートするフォーマットの一覧と、読み書きの対応状況を含めた注意をまとめました。

GD がサポートするフォーマット
フォーマット | 読み込みのサポート | 書き込みのサポート | 注意
JPEG | true | true |
PNG | true | true |
GIF | true | true |
XBM | true | true |
XPM | true | false |
WBMP | true | true |
WebP | true | true |
BMP | true | true | PHP 7.2.0 以降で利用可能です

ほとんどのフォーマットは読み書きの両方に対応していますが、 PHP をコンパイルするときにそのフォーマットのサポートを組み込んでいるとは限りません。 GD でどのフォーマットを使えるようにコンパイルしたのかを調べるには gd_info() 関数を使いましょう。 コンパイル時の設定については、インストール方法のページを参照ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • GD
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

GDライブラリ( » http://www.libgd.org/で取得可能)があれば、画像の作成と操 作を行なうこともできます。

操作できるイメージの形式は、インストールされている GDとこれらのイメージフォーマットにアクセスする ためにGDが必要とするその他のライブラリに依存します。

注意: libgd-2.1.0 以降が必要です。 もしなければ、PHP に附属する GD ライブラリを使います。

注意: GD ライブラリは、zlib >= 1.2.0.4 が必要です。

より多くのイメージ形式を処理するために GD を拡張したいと思うかもしれません。

サポートされるイメージ形式
イメージ形式 | ダウンロードするライブラリ | 注記
gif |  |
avif |  |
jpeg | » http://www.ijg.org/ | (PHP のビルド前に) jpeg ライブラリをビルドする際、configure で --enable-shared オプションを指定する必要があります。 そうしないと、PHP をビルドする際の configure で libjpeg.(a|so) not found というエラーが発生します。
png | » http://www.libpng.org/pub/png/libpng.html |
xpm | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | Xウインドウ環境をインストールしている場合、 このライブラリを既に利用可能と思われます。
webp |  |

別の種類のフォントを処理できるように GD を拡張したいと思うかもしれません。 そうした用途のために、» FreeType 2 ライブラリがサポートされています。


インストール手順

PHPでGDサポートを有効にするには、configure に--with-gd[=DIR]を指定します。ただし、DIRは GDのベースインストールディレクトリです。 PHPにバンドルされている推奨のGDライブラリを使用するには --with-gdを指定します。 GD ライブラリをコンパイルするには、libpng と libjpeg が必要です。 PHP 7.4.0 以降では、--with-gd は --enable-gd (gd 拡張モジュールを有効にするかどうかを指定する) と --with-external-gd (バンドル版の libgd ではなく、外部の libgd を使うように指定する) に変わりました。

Windows の場合、GD DLL php_gd.dll を php.ini に 拡張モジュールとして指定してください。 PHP 8.0.0 より前のバージョンでは、DLL の名前は php_gd2.dll でした。

より多くの画像フォーマットを扱えるようにGDの能力を高めるには、 --with-XXXXのような形のオプションを指定します。

サポートされる画像フォーマット
画像フォーマット | configure オプション
avif | avif をサポートするには --with-avif を指定します。PHP 8.1.0 以降で利用可能です。
jpeg | jpeg をサポートするには --with-jpeg-dir=DIR を指定します。Jpeg 6b、7、そして 8 に対応しています。 PHP 7.4.0 以降では、 --with-jpeg を代わりに使って下さい。
png | PNGをサポートするには--with-png-dir=DIR を指定します。ただし、libpngはzlibライブラリを 必要とするため、--with-zlib-dir[=DIR] もconfigureオプションに追加する必要があります。 PHP 7.4.0 以降、 --with-png-dir と --with-zlib-dir は削除されました。 libpng と zlib は必須になっています。
xpm | XPMをサポートするには--with-xpm-dir=DIR を指定します。必要なライブラリをconfigureが見つけられなかった場合は X11ライブラリのパスを追加してください。 PHP 7.4.0 以降では、 --with-xpm を代わりに使って下さい。
webp | webp をサポートするには --with-webp-dir=DIR を追加してください。 PHP 7.4.0 以降では、 --with-webp を代わりに使って下さい。

注意: libpng と共に PHP をコンパイルする際、GD ライブラリとリンクされる同じバージョンを使用する必要があります。

GDがより多くのフォントを扱えるようにするには --with-XXXXのような形のオプションを指定します。

サポートされるフォントライブラリ
フォントライブラリ | configure オプション
FreeType 2 | FreeType 2 をサポートするには --with-freetype-dir=DIRを指定します。 PHP 7.4.0 以降では、pkg-config に依存しているので、 --with-freetype を代わりに使ってください。
ネイティブ TrueType 文字列関数 | ネイティブな TrueType 文字列関数 をサポートするには --enable-gd-native-ttfを指定します (これは PHP 7.2.0 で削除されました。)


実行時設定

php.ini の設定により動作が変化します。

Image 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
gd.jpeg_ignore_warning | "1" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

gd.jpeg_ignore_warning bool

libjpeg(-turbo) が出す警告（エラーではない）を無視します。

gd.jpeg_ignore_warning の変更履歴
バージョン | 説明
7.1.0 | gd.jpeg_ignore_warning のデフォルト値が 0 から 1 に変わりました。

exif の設定ディレクティブも参照ください。

警告

イメージ関数は非常にメモリを消費します。 バンドルされたバージョンの GD ライブラリを使用している場合、 memory_limit を十分大きな値にしておくようにしましょう。


リソース型

この拡張モジュールでは、以下のリソース型を定義しています。

GD におけるリソース型の一覧
名前 | 説明 | 備考
gd | 画像リソース。imagecreatefrompng() などの関数が利用します。 | PHP 8.0.0 より前
gd font | imageloadfont() が内部的に生成したフォントリソース。 | PHP 8.1.0 より前


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

GD_VERSION (string)
PHP をコンパイルしたときの GD のバージョン
GD_MAJOR_VERSION (int)
PHP をコンパイルしたときの GD のメジャーバージョン
GD_MINOR_VERSION (int)
PHP をコンパイルしたときの GD のマイナーバージョン
GD_RELEASE_VERSION (int)
PHP をコンパイルしたときの GD のリリースバージョン
GD_EXTRA_VERSION (string)
PHP をコンパイルしたときの GD の "追加" バージョン (beta/rc..)
GD_BUNDLED (int)
バンドルされている GD を使用する場合は 1、 それ以外の場合は 0 が設定されます。
IMG_AVIF (int)
imagetypes() の戻り値として用います。 (PHP 8.1.0 以降で利用可能です)
IMG_BMP (int)
imagetypes() の戻り値として用います。
IMG_GIF (int)
imagetypes() の戻り値として用います。
IMG_JPG (int)
imagetypes() の戻り値として用います。
IMG_JPEG (int)
imagetypes() の戻り値として用います。

注意:

この定数の値は IMG_JPG と同じです。

IMG_PNG (int)
imagetypes() の戻り値として用います。
IMG_TGA (int)
imagetypes() の戻り値として用います。 PHP 7.4.0 以降で利用可能
IMG_WBMP (int)
imagetypes() の戻り値として用います。
IMG_XPM (int)
imagetypes() の戻り値として用います。
IMG_WEBP (int)
imagetypes() の戻り値として用います。 (PHP 7.0.10 以降で利用可能です)
IMG_WEBP_LOSSLESS (int)
(PHP 8.1.0 以降で利用可能です)
IMG_COLOR_TILED (int)
imagecolorallocate() や imagecolorallocatealpha() で割り当てた色のかわりに使用できる、特別な色オプション。
IMG_COLOR_STYLED (int)
imagecolorallocate() や imagecolorallocatealpha() で割り当てた色のかわりに使用できる、特別な色オプション。
IMG_COLOR_BRUSHED (int)
imagecolorallocate() や imagecolorallocatealpha() で割り当てた色のかわりに使用できる、特別な色オプション。
IMG_COLOR_STYLEDBRUSHED (int)
imagecolorallocate() や imagecolorallocatealpha() で割り当てた色のかわりに使用できる、特別な色オプション。
IMG_COLOR_TRANSPARENT (int)
imagecolorallocate() や imagecolorallocatealpha() で割り当てた色のかわりに使用できる、特別な色オプション。
IMG_AFFINE_TRANSLATE (int)
アフィン変換の形式を表す定数。imageaffinematrixget() 関数が使用します。
IMG_AFFINE_SCALE (int)
アフィン変換の形式を表す定数。imageaffinematrixget() 関数が使用します。
IMG_AFFINE_ROTATE (int)
アフィン変換の形式を表す定数。imageaffinematrixget() 関数が使用します。
IMG_AFFINE_SHEAR_HORIZONTAL (int)
アフィン変換の形式を表す定数。imageaffinematrixget() 関数が使用します。
IMG_AFFINE_SHEAR_VERTICAL (int)
アフィン変換の形式を表す定数。imageaffinematrixget() 関数が使用します。
IMG_ARC_ROUNDED (int)
スタイル定数。imagefilledarc() 関数が使用します。

注意:

この定数の値は IMG_ARC_PIE と同じです。

IMG_ARC_PIE (int)
スタイル定数。imagefilledarc() 関数が使用します。
IMG_ARC_CHORD (int)
スタイル定数。imagefilledarc() 関数が使用します。
IMG_ARC_NOFILL (int)
スタイル定数。imagefilledarc() 関数が使用します。
IMG_ARC_EDGED (int)
スタイル定数。imagefilledarc() 関数が使用します。
IMG_GD2_RAW (int)
タイプ変数。imagegd2() 関数が使用します。
IMG_GD2_COMPRESSED (int)
タイプ変数。imagegd2() 関数が使用します。
IMG_EFFECT_REPLACE (int)
アルファブレンディング効果。imagelayereffect() 関数で使用します。
IMG_EFFECT_ALPHABLEND (int)
アルファブレンディング効果。imagelayereffect() 関数で使用します。
IMG_EFFECT_NORMAL (int)
アルファブレンディング効果。imagelayereffect() 関数で使用します。
IMG_EFFECT_OVERLAY (int)
アルファブレンディング効果。imagelayereffect() 関数で使用します。
IMG_EFFECT_MULTIPLY (int)
アルファブレンディング効果。imagelayereffect() 関数で使用します。
IMG_FILTER_NEGATE (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_GRAYSCALE (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_BRIGHTNESS (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_CONTRAST (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_COLORIZE (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_EDGEDETECT (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_GAUSSIAN_BLUR (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_SELECTIVE_BLUR (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_EMBOSS (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_MEAN_REMOVAL (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_SMOOTH (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_PIXELATE (int)
特別な GD フィルタ。imagefilter() 関数で使用します。
IMG_FILTER_SCATTER (int)
特別な GD フィルタ。imagefilter() 関数で使用します。 (PHP 7.4.0 以降で使用可能)
IMAGETYPE_GIF (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_JPEG (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_JPEG2000 (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_PNG (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_SWF (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_PSD (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_BMP (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_WBMP (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_XBM (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_TIFF_II (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_TIFF_MM (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_IFF (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_JB2 (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_JPC (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_JP2 (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_JPX (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_SWC (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_ICO (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_WEBP (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。 (PHP 7.1.0 以降で利用可能です)
IMAGETYPE_AVIF (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。 (PHP 8.1.0 以降で利用可能です)
IMAGETYPE_UNKNOWN (int)
画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。
IMAGETYPE_COUNT (int)
画像タイプの定数の数("unknown" タイプも含みます)。 image_type_to_mime_type() と image_type_to_extension() でサポートされています。
PNG_NO_FILTER (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
PNG_FILTER_NONE (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
PNG_FILTER_SUB (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
PNG_FILTER_UP (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
PNG_FILTER_AVG (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
PNG_FILTER_PAETH (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
PNG_ALL_FILTERS (int)
特別な PNG フィルタ。imagepng() 関数で使用します。
IMG_FLIP_VERTICAL (int)
imageflip() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_FLIP_HORIZONTAL (int)
imageflip() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_FLIP_BOTH (int)
imageflip() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BELL (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BESSEL (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BILINEAR_FIXED (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BICUBIC (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BICUBIC_FIXED (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BLACKMAN (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BOX (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_BSPLINE (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_CATMULLROM (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_GAUSSIAN (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_GENERALIZED_CUBIC (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_HERMITE (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_HAMMING (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_HANNING (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_MITCHELL (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_POWER (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_QUADRATIC (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_SINC (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_NEAREST_NEIGHBOUR (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_WEIGHTED4 (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_TRIANGLE (int)
imagesetinterpolation() で使用します。PHP 5.5.0 以降で使用可能です。
IMG_CROP_BLACK (int)
黒い背景を切り抜きます。
IMG_CROP_DEFAULT (int)
IMG_CROP_TRANSPARENT と同じです。 PHP 7.4.0 より前のバージョンでは、 透過色が存在しない場合、バンドルされていた libgd が IMG_CROP_SIDES にフォールバックしていました。
IMG_CROP_SIDES (int)
切り抜く背景を検知しようとする際、 画像の四隅を使います。
IMG_CROP_THRESHOLD (int)
指定された threshold と color を使い、画像を切り抜きます。
IMG_CROP_TRANSPARENT (int)
透明な背景を切り抜きます。
IMG_CROP_WHITE (int)
白い背景を切り抜きます。


例

目次

  • PHP による PNG の生成
  • アルファチャネルを使用した、画像へのすかしの追加
  • imagecopymerge による半透明なすかしの作成


PHP による PNG の生成

例1 PHP による PNG の生成

<?php

header("Content-type: image/png");
$string = $_GET['text'];
$im = imagecreatefrompng("images/button1.png");
$orange = imagecolorallocate($im, 220, 210, 60);
$px = (imagesx($im) - 7.5 * strlen($string)) / 2;
imagestring($im, 3, $px, 9, $string, $orange);
imagepng($im);
imagedestroy($im);

?>
この例のスクリプトは、<img src="button.php?text"> のようなタグが書かれたページからコールされるものです。 上の button.php スクリプトは、この "text" 文字列を引数とし、 基本画像 "images/button1.png" の上にこの文字列を重ねて描いた後、その画像を出力します。 この方法を使うと、ボタンのテキストが変わるたびに新たなボタンを作り直す羽目になることを回避できます。 この方法により、動的に画像ボタンを生成できるのです。


アルファチャネルを使用した、画像へのすかしの追加

例1 アルファチャネルを使用した、画像へのすかしの追加

<?php
// スタンプと、それをすかしとして適用する写真を読み込みます
$stamp = imagecreatefrompng('stamp.png');
$im = imagecreatefromjpeg('photo.jpeg');

// スタンプの余白を設定し、スタンプ画像の幅と高さを取得します
$marge_right = 10;
$marge_bottom = 10;
$sx = imagesx($stamp);
$sy = imagesy($stamp);

// スタンプ画像を写真の上にコピーします。余白の値と
// 写真の幅を元にスタンプの位置を決定します
imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

// 出力し、メモリを開放します
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>
この例は、すかしやスタンプを写真あるいは著作権つき画像に追加するための一般的な方法です。 スタンプ画像内のアルファチャネルのテキストはアンチエイリアス処理されることに注意しましょう。 画像をコピーしてもこれは残り続けます。


imagecopymerge による半透明なすかしの作成

  • ≪ アルファチャネルを使用した、画像へのすかしの追加
  • GD および Image 関数 ≫
  • PHP Manual
  • 例
  • imagecopymerge による半透明なすかしの作成

imagecopymerge() による半透明なすかしの作成

例1 imagecopymerge() による半透明なすかしの作成

<?php
// スタンプと、それをすかしとして適用する写真を読み込みます
$im = imagecreatefromjpeg('photo.jpeg');

// まず、スタンプ画像を GD で作成します
$stamp = imagecreatetruecolor(100, 70);
imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

// スタンプの余白を設定し、スタンプ画像の幅と高さを取得します
$marge_right = 10;
$marge_bottom = 10;
$sx = imagesx($stamp);
$sy = imagesy($stamp);

// スタンプを、50% の不透明度で写真に重ねます
imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

// 画像をファイルに保存し、メモリを開放します
imagepng($im, 'photo_stamp.png');
imagedestroy($im);

?>
この例は、imagecopymerge() を使ってスタンプを元画像にかぶせます。 これを使うと、スタンプの不透明度を設定することができます。 今回の例では 50% の不透明度に設定しています。 この半透明のすかしを用いる方法は、著作権つきの画像を保護するのに便利です。 すかしをとるのは非常に難しく、またもとの画像の見栄えも損ねません。


GD および Image 関数

目次

  • gd_info — 現在インストールされているGDライブラリに関する情報を取得する
  • getimagesize — 画像の大きさを取得する
  • getimagesizefromstring — 画像の大きさを文字列から取得する
  • image_type_to_extension — 画像形式からファイルの拡張子を取得する
  • image_type_to_mime_type — getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する
  • image2wbmp — 画像をブラウザあるいはファイルに出力する
  • imageaffine — 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す
  • imageaffinematrixconcat — 二つのアフィン変換行列を連結する
  • imageaffinematrixget — アフィン変換行列を取得する
  • imagealphablending — イメージのブレンドモードを設定する
  • imageantialias — アンチエイリアス機能を使用すべきかどうかを判断する
  • imagearc — 部分楕円を描画する
  • imageavif — 画像をブラウザあるいはファイルに出力する
  • imagebmp — ビットマップ画像をブラウザかファイルに出力する
  • imagechar — 水平に文字を描画する
  • imagecharup — 垂直に文字を描画する
  • imagecolorallocate — 画像で使用する色を作成する
  • imagecolorallocatealpha — 画像で使用する色を透過度を指定して作成する
  • imagecolorat — ピクセルの色のインデックスを取得する
  • imagecolorclosest — 指定した色に最も近い色のインデックスを取得する
  • imagecolorclosestalpha — 指定した色+アルファ値に最も近い色のインデックスを取得する
  • imagecolorclosesthwb — 色合い、白、黒を有する色のインデックスを得る
  • imagecolordeallocate — イメージの色リソースを開放する
  • imagecolorexact — 指定した色のインデックスを取得する
  • imagecolorexactalpha — 指定した色+アルファ値のインデックスを取得する
  • imagecolormatch — パレットイメージの色を True カラーイメージに近づける
  • imagecolorresolve — 指定した色または出来るだけ近い色のインデックスを得る
  • imagecolorresolvealpha — 指定した色+アルファ値または最も近い色のインデックスを取得する
  • imagecolorset — 指定したパレットインデックスの色を設定する
  • imagecolorsforindex — カラーインデックスからカラーを取得する
  • imagecolorstotal — 画像パレットの色数を検出する
  • imagecolortransparent — 透明色を定義する
  • imageconvolution — div および offset の係数を使用し、3x3 の畳み込み配列を適用する
  • imagecopy — 画像の一部をコピーする
  • imagecopymerge — イメージの一部をコピー、マージする
  • imagecopymergegray — グレースケールでイメージの一部をコピー、マージする
  • imagecopyresampled — 再サンプリングを行いイメージの一部をコピー、伸縮する
  • imagecopyresized — 画像の一部をコピーしサイズを変更する
  • imagecreate — パレットを使用する新規画像を作成する
  • imagecreatefromavif — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する
  • imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する
  • imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する
  • imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する
  • imagecreatefromtga — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromwbmp — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromwebp — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromxbm — 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromxpm — 新しい画像をファイルあるいは URL から作成する
  • imagecreatetruecolor — TrueColor イメージを新規に作成する
  • imagecrop — 指定した矩形に画像をクロップする
  • imagecropauto — 利用可能なモードを指定して、画像を自動的にクロップする
  • imagedashedline — 破線を描画する
  • imagedestroy — 画像を破棄する
  • imageellipse — 楕円を描画する
  • imagefill — 塗り潰す
  • imagefilledarc — 楕円弧を描画し、塗りつぶす
  • imagefilledellipse — 塗りつぶされた楕円を描画する
  • imagefilledpolygon — 塗りつぶした多角形を描画する
  • imagefilledrectangle — 塗りつぶした矩形を描画する
  • imagefilltoborder — 特定色で塗りつぶす
  • imagefilter — 画像にフィルタを適用する
  • imageflip — 指定したモードで画像を反転させる
  • imagefontheight — フォントの高さを取得する
  • imagefontwidth — フォントの幅を取得する
  • imageftbbox — freetype2 によるフォントを用いたテキストを囲む箱を取得する
  • imagefttext — FreeType 2 によるフォントを用いてイメージにテキストを描画する
  • imagegammacorrect — GD イメージにガンマ補正を適用する
  • imagegd — GD イメージをブラウザまたはファイルに出力する
  • imagegd2 — GD2 イメージをブラウザまたはファイルに出力する
  • imagegetclip — 長方形を切り取り、画像として取得する
  • imagegetinterpolation — 補間方法を取得する
  • imagegif — 画像をブラウザあるいはファイルに出力する
  • imagegrabscreen — 画面全体をキャプチャする
  • imagegrabwindow — ウィンドウをキャプチャする
  • imageinterlace — インターレースを有効もしくは無効にする
  • imageistruecolor — 画像が truecolor かどうか調べる
  • imagejpeg — 画像をブラウザあるいはファイルに出力する
  • imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する
  • imageline — 直線を描画する
  • imageloadfont — 新しいフォントを読み込む
  • imageopenpolygon — オープンポリゴンを描画する
  • imagepalettecopy — あるイメージから他のイメージにパレットをコピーする
  • imagepalettetotruecolor — パレット形式の画像を true color に変換する
  • imagepng — PNG イメージをブラウザまたはファイルに出力する
  • imagepolygon — 多角形を描画する
  • imagerectangle — 矩形を描画する
  • imageresolution — 画像の解像度を取得/設定する
  • imagerotate — 指定された角度で画像を回転する
  • imagesavealpha — 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する
  • imagescale — 幅と高さを指定して、画像の縮尺を変更する
  • imagesetbrush — 線の描画用にブラシイメージを設定する
  • imagesetclip — 切り取る長方形を設定する
  • imagesetinterpolation — 補間方法を設定する
  • imagesetpixel — 点を生成する
  • imagesetstyle — 線描画用のスタイルを設定する
  • imagesetthickness — 線描画用の線幅を設定する
  • imagesettile — 塗りつぶし用のイメージを設定する
  • imagestring — 文字列を水平に描画する
  • imagestringup — 文字列を垂直に描画する
  • imagesx — 画像の幅を取得する
  • imagesy — 画像の高さを取得する
  • imagetruecolortopalette — TrueColor イメージをパレットイメージに変換する
  • imagettfbbox — TypeType フォントを使用したテキストの bounding box を生成する
  • imagettftext — TrueType フォントを使用してテキストを画像に書き込む
  • imagetypes — この PHP がサポートしている画像形式を返す
  • imagewbmp — 画像をブラウザあるいはファイルに出力する
  • imagewebp — WebP 画像をブラウザあるいはファイルに出力する
  • imagexbm — XBM 画像をブラウザあるいはファイルに出力する
  • iptcembed — バイナリ IPTC データを JPEG イメージに埋めこむ
  • iptcparse — バイナリの IPTC ブロックのタグをパースする
  • jpeg2wbmp — JPEG画像をWBMP画像に変換する
  • png2wbmp — PNG画像をWBMP画像に変換する


現在インストールされているGDライブラリに関する情報を取得する

  • ≪ GD および Image 関数
  • getimagesize ≫
  • PHP Manual
  • GD および Image 関数
  • 現在インストールされているGDライブラリに関する情報を取得する

gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — 現在インストールされているGDライブラリに関する情報を取得する

説明

gd_info(): array

インストールされている GD ライブラリのバージョンとスペックに関する情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

連想配列を返します。

gd_info() が返す配列の要素
属性 | 意味
GD Version | string。インストールされている libgdのバージョン
FreeType Support | bool value. true の場合FreeTypeサポートはインストールされている
FreeType Linkage | string値。FreeTypeのリンク方法の情報。 'with freetype', 'with TTF library', 'with unknown library'など。 FreeType Supportがtrueにセットされている場合にのみ この要素が定義されます。
T1Lib Support | bool値。 T1Libサポートが含まれている場合にtrue
GIF Read Support | bool値。 GIF画像の読み込み がサポートされている場合にtrue
GIF Create Support | bool値。 GIF画像の生成 がサポートされている場合にtrue
JPEG Support | bool値。 JPEGサポートが含まれている場合にtrue
PNG Support | bool値。 PNGサポートが含まれている場合にtrue
WBMP Support | bool値。 WBMPサポートが含まれている場合にtrue
XBM Support | bool値。 XBMサポートが含まれている場合にtrue
WebP Support | bool 値。 WebP サポートが含まれている場合にtrue
AVIF Support | bool 値。 AVIF サポートが含まれている場合にtrue PHP 8.1.0 以降で利用可能です。

注意:

PHP 5.3.0 より前のバージョンでは、JPEG Support 属性は JPG Support という名前でした。

例

例1 gd_info() の使用法

<?php
var_dump(gd_info());
?>

上の例の出力は、 たとえば以下のようになります。

array(10) {
  ["GD Version"]=>
  string(24) "bundled (2.1.0 compatible)"
  ["FreeType Support"]=>
  bool(false)
  ["T1Lib Support"]=>
  bool(false)
  ["GIF Read Support"]=>
  bool(true)
  ["GIF Create Support"]=>
  bool(false)
  ["JPEG Support"]=>
  bool(false)
  ["PNG Support"]=>
  bool(true)
  ["WBMP Support"]=>
  bool(true)
  ["XBM Support"]=>
  bool(false)
  ["WebP Support"]=>
  bool(false)
  ["AVIF Support"]=>
  bool(false)
}

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagewebp() - WebP 画像をブラウザあるいはファイルに出力する
  • imageavif() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す


画像の大きさを取得する

  • ≪ gd_info
  • getimagesizefromstring ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の大きさを取得する

getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — 画像の大きさを取得する

説明

getimagesize(string $filename, array &$image_info = null): array|false

getimagesize() 関数は、サポートする任意の形式の画像ファイルの大きさを決定し、 ファイルの型と高さ/幅を表す文字列を返します。これらは HTML の IMG タグや HTTP の content type として使用できます。

警告

この関数は、filename が適切な画像ファイルであることを想定しています。 画像以外のファイルを渡してもそれを画像だと判断してしまい、関数の処理は成功するでしょう。 しかし、配列には意味のない値が含まれる場合があります。

getimagesize() を使って、そのファイルが画像であるかどうかを確かめることはできません。 そのようなことをしたい場合は、そのために用意されたソリューション (Fileinfo 拡張モジュールなど) を使いましょう。

getimagesize() は、 image_info パラメータで追加情報を返します。

注意: JPC と JP2 は異なるビット深度のコンポーネントを含むことが可能なことに 注意してください。この場合 "bits" に対する値は、 最も大きい深度になります。また、JP2 ファイルは 複数の JPEG 2000 コードストリームを含む場合があります。この場合、 getimagesize() はファイルのルートから 最初に遭遇するコードストリームに対する値を返します。

注意: アイコンに関する情報は、ビットレートが最大のアイコンから取得します。

注意: GIF 画像はひとつ以上のフレームからなります。 個々のフレームは画像の一部のみを占めます。 getimagesize() が報告する画像のサイズは、 (logical screen descriptor から読み込まれた) 全部のサイズです。

パラメータ

filename

このパラメータは、情報を取得したいファイルの名前を指定します。 ローカルファイルへの参照、あるいは (設定で許可されているなら) ストリームを用いたリモートファイルへの参照を指定できます。

image_info

オプションのパラメータで、 画像ファイルから何らかの拡張情報を引き出すことが可能です。 現在、この変数にはJPGファイルについて 異なった複数のAPPマーカーが連想配列として返されます。いくつかのプログラムは、 これらのAPPマーカーを画像の中の埋込テキストの情報として使用します。 最も一般的な例は、マーカーAPPl3に埋込IPTC » http://www.iptc.org/情報が返されることです。 バイナリ形式のマーカーAPP13を読むことができるよう処理するために iptcparse() 関数を使用することができます。

注意:

image_info は、 JFIF ファイルのみをサポートします。

戻り値

最大 7 つの要素からなる配列を返します。画像の形式によっては、 channels や bits は含まれないことがあります。

0 番目および 1 番目の要素は、それぞれ画像の幅と高さを表します。

注意:

形式によっては、画像を含まないものや複数の画像を含むものがあります。 これらの場合、getimagesize() は画像のサイズを適切に決定することができません。このような場合、 getimagesize() が返す幅と高さはいずれもゼロとなります。

2 番目の要素は IMAGETYPE_XXX constants 定数のひとつで、 画像の形式を表します。

3 番目の要素は IMG タグで直接利用できる文字列 height="yyy" width="xxx" です。

mimeは画像のMIMEタイプに一致します。この情報は 画像とともに正しい HTTP Content-type ヘッダを転送するために使用できます。

例1 getimagesize() および MIME 型

<?php
$size = getimagesize($filename);
$fp = fopen($filename, "rb");
if ($size && $fp) {
header("Content-type: {$size['mime']}");
fpassthru($fp);
exit;
} else {
// エラー
}
?>

channels は RGB 画像の場合に 3、CMYK 画像の場合に 4 です。

bits は個々の色のビット数です。

画像の形式によっては、channels や bits の値の存在は混乱の元です。 たとえば、GIF は常に 1 ピクセルあたり 3 チャンネルを使用しますが、グローバルカラーテーブルを使ったアニメーション GIF のピクセルあたりのビット数を計算することはできません。

失敗した場合には false を返します。

エラー / 例外

もし filename のイメージにアクセスできない場合、 getimagesize() は false を返し、E_WARNING レベルのエラーを発生させます。 読み込み時にエラーが発生した場合は、 getimagesize() は E_NOTICE レベルのエラーを発生させます。

変更履歴

バージョン | 説明
8.2.0 | AVIF 画像の ビット数、チャンネル情報、幅と高さの情報(dimensions) を返すようになりました。 これより前のバージョンでは、幅と高さの情報は 0x0 として報告され、ビット数とチャンネル情報は全く報告されていませんでした。
7.1.0 | WebP に対応しました。

例

例2 getimagesize() の例

<?php
list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
?>

例3 getimagesize (URL)

<?php
$size = getimagesize("http://www.example.com/gifs/logo.gif");

// ファイル名にスペースが含まれる場合は適切にエンコードしてください
$size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

?>

例4 IPTC を返す getimagesize()

<?php
$size = getimagesize("testimg.jpg", $info);
if (isset($info["APP13"])) {
$iptc = iptcparse($info["APP13"]);
var_dump($iptc);
}
?>

注意

注意:

この関数は、GD 画像ライブラリは必要ありません。

参考

  • image_type_to_mime_type() - getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する
  • exif_imagetype() - イメージの型を定義する
  • exif_read_data() - 画像ファイルから EXIF ヘッダを読み込む
  • exif_thumbnail() - 画像に埋め込まれたサムネイルを取得する
  • imagesx() - 画像の幅を取得する
  • imagesy() - 画像の高さを取得する


画像の大きさを文字列から取得する

  • ≪ getimagesize
  • image_type_to_extension ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の大きさを文字列から取得する

getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — 画像の大きさを文字列から取得する

説明

getimagesizefromstring(string $string, array &$image_info = null): array|false

getimagesize() と似ていますが、 getimagesizefromstring() の最初のパラメータはファイル名ではなく文字列となります。

この関数の挙動の詳細については getimagesize() のドキュメントを参照ください。

パラメータ

string

文字列で表した画像データ。

image_info

getimagesize() を参照ください。

戻り値

getimagesize() を参照ください。

例

例1 getimagesizefromstring() の例

<?php
$img = '/path/to/test.png';

// ファイルとして開く
$size_info1 = getimagesize($img);

// あるいは、文字列として開く
$data = file_get_contents($img);
$size_info2 = getimagesizefromstring($data);
?>

参考

  • getimagesize() - 画像の大きさを取得する


画像形式からファイルの拡張子を取得する

  • ≪ getimagesizefromstring
  • image_type_to_mime_type ≫
  • PHP Manual
  • GD および Image 関数
  • 画像形式からファイルの拡張子を取得する

image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — 画像形式からファイルの拡張子を取得する

説明

image_type_to_extension(int $image_type, bool $include_dot = true): string|false

指定した定数 IMAGETYPE_XXX に対応する拡張子を返します。

パラメータ

image_type

IMAGETYPE_XXX 定数のいずれかひとつ。

include_dot

拡張子の前にドットをつけるかどうか。デフォルトは true。

戻り値

指定した型に対応する拡張子を文字列で返します。 失敗した場合に false を返します

例

例1 image_type_to_extension() の例

<?php
// 画像のインスタンスを作成します
$im = imagecreatetruecolor(100, 100);

// 画像を保存します
imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
imagedestroy($im);
?>

注意

注意:

この関数は、GD 画像ライブラリは必要ありません。


getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

  • ≪ image_type_to_extension
  • image2wbmp ≫
  • PHP Manual
  • GD および Image 関数
  • getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する

説明

image_type_to_mime_type(int $image_type): string

image_type_to_mime_type() は IMAGETYPE 定数で指定される Mime-Type を取得します。

パラメータ

image_type

IMAGETYPE_XXX 定数のいずれか。

戻り値

戻り値は次のとおりです。

戻り値の定数
image_type | 戻り値
IMAGETYPE_GIF | image/gif
IMAGETYPE_JPEG | image/jpeg
IMAGETYPE_PNG | image/png
IMAGETYPE_SWF | application/x-shockwave-flash
IMAGETYPE_PSD | image/psd
IMAGETYPE_BMP | image/bmp
IMAGETYPE_TIFF_II (intel byte order) | image/tiff
IMAGETYPE_TIFF_MM (motorola byte order) | image/tiff
IMAGETYPE_JPC | application/octet-stream
IMAGETYPE_JP2 | image/jp2
IMAGETYPE_JPX | application/octet-stream
IMAGETYPE_JB2 | application/octet-stream
IMAGETYPE_SWC | application/x-shockwave-flash
IMAGETYPE_IFF | image/iff
IMAGETYPE_WBMP | image/vnd.wap.wbmp
IMAGETYPE_XBM | image/xbm
IMAGETYPE_ICO | image/vnd.microsoft.icon
IMAGETYPE_WEBP | image/webp
IMAGETYPE_AVIF | image/avif

例

例1 image_type_to_mime_type() の例

<?php
header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
?>

注意

注意:

この関数は、GD 画像ライブラリは必要ありません。

参考

  • getimagesize() - 画像の大きさを取得する
  • exif_imagetype() - イメージの型を定義する
  • exif_read_data() - 画像ファイルから EXIF ヘッダを読み込む
  • exif_thumbnail() - 画像に埋め込まれたサムネイルを取得する


画像をブラウザあるいはファイルに出力する

  • ≪ image_type_to_mime_type
  • imageaffine ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — 画像をブラウザあるいはファイルに出力する

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

image2wbmp(resource $image, string $filename = ?, int $foreground = ?): bool

image2wbmp() は、イメージ im から filename に WBMP ファイルを作成します。

パラメータ

image

imagecreatetruecolor() のような、 画像を生成する関数から返される画像リソース。

filename

保存されるファイルへのパス。指定しなかった場合は、生の画像ストリームが直接出力されます。

foreground

imagecolorallocate() から取得した識別子をこのパラメーターに設定することで、 フォアグラウンドカラーを設定できます。 デフォルトのフォアグラウンドカラーは黒です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 image2wbmp() の例

<?php
$file = 'php.png';
$image = imagecreatefrompng($file);

header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
image2wbmp($image); // ストリームを直接出力します。
imagedestroy($image);
?>

参考

  • imagewbmp() - 画像をブラウザあるいはファイルに出力する


元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

  • ≪ image2wbmp
  • imageaffinematrixconcat ≫
  • PHP Manual
  • GD および Image 関数
  • 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

説明

imageaffine(GdImage $image, array $affine, ?array $clip = null): GdImage|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

affine

0 から 5 までのキーを持つ配列。

clip

キー "x"、"y"、"width" そして "height" を持つ配列。 または null。

戻り値

アフィン変換した画像オブジェクトを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | clip は、nullable になりました。
8.0.0 | 成功時に、この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource が返されていました。


二つのアフィン変換行列を連結する

  • ≪ imageaffine
  • imageaffinematrixget ≫
  • PHP Manual
  • GD および Image 関数
  • 二つのアフィン変換行列を連結する

imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — 二つのアフィン変換行列を連結する

説明

imageaffinematrixconcat(array $matrix1, array $matrix2): array|false

二つのアフィン変換行列を連結したものを返します。 複数の行列を、同じ画像に対して一度に適用したい場合に便利です。

パラメータ

matrix1

アフィン変換行列 (0 から 5 までのキーに float 値を持つ配列)。

matrix2

アフィン変換行列 (0 から 5 までのキーに float 値を持つ配列)。

戻り値

アフィン変換行列 (0 から 5 までのキーに float 値を持つ配列) を返します。失敗した場合に false を返します。

例

例1 imageaffinematrixconcat() の例

<?php
$m1 = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
$m2 = imageaffinematrixget(IMG_AFFINE_SCALE, array('x' => 4, 'y' => 5));
$matrix = imageaffinematrixconcat($m1, $m2);
print_r($matrix);
?>

上の例の出力は以下となります。

Array
(
    [0] => 4
    [1] => 0
    [2] => 0
    [3] => 5
    [4] => 8
    [5] => 15
)

参考

  • imageaffine() - 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す
  • imageaffinematrixget() - アフィン変換行列を取得する


アフィン変換行列を取得する

  • ≪ imageaffinematrixconcat
  • imagealphablending ≫
  • PHP Manual
  • GD および Image 関数
  • アフィン変換行列を取得する

imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — アフィン変換行列を取得する

説明

imageaffinematrixget(int $type, array|float $options): array|false

アフィン変換行列を返します。

パラメータ

type

定数 IMG_AFFINE_* のいずれか。

options

type が IMG_AFFINE_TRANSLATE あるいは IMG_AFFINE_SCALE の場合は、 options は x と y をキーとする配列でなければいけません。 それぞれの値は float にする必要があります。

type が IMG_AFFINE_ROTATE、 IMG_AFFINE_SHEAR_HORIZONTAL、 IMG_AFFINE_SHEAR_VERTICAL のいずれかである場合は、 options はアングルを指定する float 値でなければいけません。

戻り値

0 から 5 までのキーに float 値を持つ配列を返します。失敗した場合に false を返します。

例

例1 imageaffinematrixget() の例

<?php
$matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
print_r($matrix);
?>

上の例の出力は以下となります。

Array
(
    [0] => 1
    [1] => 0
    [2] => 0
    [3] => 1
    [4] => 2
    [5] => 3
)

参考

  • imageaffine() - 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す
  • imageaffinematrixconcat() - 二つのアフィン変換行列を連結する


イメージのブレンドモードを設定する

  • ≪ imageaffinematrixget
  • imageantialias ≫
  • PHP Manual
  • GD および Image 関数
  • イメージのブレンドモードを設定する

imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — イメージのブレンドモードを設定する

説明

imagealphablending(GdImage $image, bool $enable): bool

imagealphablending() によりTrueColorイメージに 二つの異なる描画モードを使用可能となります。ブレンドモードでは、 全ての描画関数に指定される色のalphaチャネル要素として使用され、 例えばimagesetpixel()では背景色の透過割合を定 義します。結果として、gd は描画色に関してその点に存在する色を自動 的にブレンドし、イメージに結果を保存します。結果のピクセルは、透 明になります。ブレンドモードでない場合、描画色は形式的にそのアル ファチャネル情報にコピーされ、出力ピクセルを置換します。ブレンド モードは、パレットイメージを描画している際には使用できません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

enable

ブレンドモードを有効にするかどうか。True Color 画像の場合のデフォルトは true、それ以外の場合のデフォルトは false です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagealphablending() の使用例

<?php
// 画像を作成します
$im = imagecreatetruecolor(100, 100);

// アルファブレンディングをオンにします
imagealphablending($im, true);

// 正方形を描画します
imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

// 出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>


アンチエイリアス機能を使用すべきかどうかを判断する

  • ≪ imagealphablending
  • imagearc ≫
  • PHP Manual
  • GD および Image 関数
  • アンチエイリアス機能を使用すべきかどうかを判断する

imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — アンチエイリアス機能を使用すべきかどうかを判断する

説明

imageantialias(GdImage $image, bool $enable): bool

直線や多角形を高速に描画するためのアンチエイリアス機能を有効にします。 アルファコンポーネントはサポートしていません。ダイレクトブレンド操作を 使用します。truecolor 画像に対してのみ動作します。

thickness および styled はサポートしていません。

背景色が透明な場合にアンチエイリアス機能を使用すると、予期せぬ結果に 終わることがあります。ブレンドメソッドでは、背景色が使用されます。 アルファコンポーネントをサポートしていないため、アルファコンポーネントに 基づいたアンチエイリアス手法は使用できません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

enable

アンチエイリアスを有効にするかどうか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
7.2.0 | imageantialias() が常に使えるようになりました。 これまでのバージョンでは、PHP にバンドルされている GD ライブラリでコンパイルした場合にしか使えませんでした。

例

例1 2 本の直線のうち一方にアンチエイリアスを有効にする

<?php
// アンチエイリアス画像と通常の画像を用意します
$aa = imagecreatetruecolor(400, 100);
$normal = imagecreatetruecolor(200, 100);

// アンチエイリアスを有効にします
imageantialias($aa, true);

// 色を割り当てます
$red = imagecolorallocate($normal, 255, 0, 0);
$red_aa = imagecolorallocate($aa, 255, 0, 0);

// 一方はアンチエイリアスを有効にした状態で 2 本の直線を描画します
imageline($normal, 0, 0, 200, 100, $red);
imageline($aa, 0, 0, 200, 100, $red_aa);

// ふたつの画像を横に並べて出力します (アンチエイリアス: 左、通常: 右)
imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

// 画像を出力します
header('Content-type: image/png');

imagepng($aa);
imagedestroy($aa);
imagedestroy($normal);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 2 本の直線のうち一方にアンチエイリアスを有効にする

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する


部分楕円を描画する

  • ≪ imageantialias
  • imageavif ≫
  • PHP Manual
  • GD および Image 関数
  • 部分楕円を描画する

imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — 部分楕円を描画する

説明

imagearc(
GdImage $image,
int $center_x,
int $center_y,
int $width,
int $height,
int $start_angle,
int $end_angle,
int $color
): bool

imagearc() は、指定した座標を中心とする円弧を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

center_x

中心の x 座標。

center_y

中心の y 座標。

width

円弧の幅。

height

円弧の高さ。

start_angle

始点の角度。

end_angle

終点の角度。 0° は 3 時の位置で、そこから時計回りの方向に円弧が描かれます。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagearc() による円の描画

<?php

// 200*200 の画像を作成します
$img = imagecreatetruecolor(200, 200);

// 色を設定します
$white = imagecolorallocate($img, 255, 255, 255);
$red = imagecolorallocate($img, 255, 0, 0);
$green = imagecolorallocate($img, 0, 255, 0);
$blue = imagecolorallocate($img, 0, 0, 255);

// 頭を描きます
imagearc($img, 100, 100, 200, 200, 0, 360, $white);
// 口を描きます
imagearc($img, 100, 100, 150, 150, 25, 155, $red);
// 左右の目を描きます
imagearc($img, 60, 75, 50, 50, 0, 360, $green);
imagearc($img, 140, 75, 50, 50, 0, 360, $blue);

// 画像をブラウザに出力します
header("Content-type: image/png");
imagepng($img);

// メモリを解放します
imagedestroy($img);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagearc() による円の描画

参考

  • imagefilledarc() - 楕円弧を描画し、塗りつぶす
  • imageellipse() - 楕円を描画する
  • imagefilledellipse() - 塗りつぶされた楕円を描画する


画像をブラウザあるいはファイルに出力する

  • ≪ imagearc
  • imagebmp ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imageavif

(PHP 8 >= 8.1.0)

imageavif — 画像をブラウザあるいはファイルに出力する

説明

imageavif(
GdImage $image,
resource|string|null $file = null,
int $quality = -1,
int $speed = -1
): bool

指定された image から、 AVIF ラスタ画像を出力、または保存します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

quality

quality はオプションで、 0 (画質は最悪、小さなファイル) から 100 (最高画質、大きなファイル) までの値を取ります。 -1 を指定した場合、 デフォルト値 30 を使います。

speed

speed はオプションで、 0 (ゆっくり、小さなファイル) から 10 (速い、大きなファイル) までの値を取ります。 -1 を指定した場合、 デフォルト値 6 を使います。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す


ビットマップ画像をブラウザかファイルに出力する

  • ≪ imageavif
  • imagechar ≫
  • PHP Manual
  • GD および Image 関数
  • ビットマップ画像をブラウザかファイルに出力する

imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — ビットマップ画像をブラウザかファイルに出力する

説明

imagebmp(GdImage $image, resource|string|null $file = null, bool $compressed = true): bool

与えられた image のビットマップ版を保存するか出力します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

注意:

引数 compressed が指定されない場合、 null は不正な値になります。

compressed

ビットマップをランレングス法(RLE)を使って圧縮するかどうか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | compressed の型は、 bool になりました。 これより前のバージョンでは、数値型でした。

例

例1 ビットマップファイルを保存する

<?php
// 空の画像を生成し、いくつかテキストを加えます。
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);

imagestring($im, 1, 5, 5, 'BMP with PHP', $text_color);

// 画像を保存します。
imagebmp($im, 'php.bmp');

// メモリを解放します。
imagedestroy($im);
?>


水平に文字を描画する

  • ≪ imagebmp
  • imagecharup ≫
  • PHP Manual
  • GD および Image 関数
  • 水平に文字を描画する

imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — 水平に文字を描画する

説明

imagechar(
GdImage $image,
GdFont|int $font,
int $x,
int $y,
string $char,
int $color
): bool

imagechar() は、画像 im 上の座標 x,y(左上が 0, 0) に color 色で char の最初の文字を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。

x

始点の x 座標。

y

始点の y 座標。

char

描画する文字。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 font は、GdFont クラスのインスタンスと数値を両方受け入れるようになりました。これより前のバージョンでは、数値のみを受け入れていました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagechar() の例

<?php

$im = imagecreate(100, 100);

$string = 'PHP';

$bg = imagecolorallocate($im, 255, 255, 255);
$black = imagecolorallocate($im, 0, 0, 0);

// 左上の角に黒で "P" を表示します
imagechar($im, 1, 0, 0, $string, $black);

header('Content-type: image/png');
imagepng($im);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagechar()

参考

  • imagecharup() - 垂直に文字を描画する
  • imageloadfont() - 新しいフォントを読み込む


垂直に文字を描画する

  • ≪ imagechar
  • imagecolorallocate ≫
  • PHP Manual
  • GD および Image 関数
  • 垂直に文字を描画する

imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — 垂直に文字を描画する

説明

imagecharup(
GdImage $image,
GdFont|int $font,
int $x,
int $y,
string $char,
int $color
): bool

指定した画像 image の指定した位置に、 文字 char を垂直に描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。

x

始点の x 座標。

y

始点の y 座標。

char

描画する文字。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 font は、GdFont クラスのインスタンスと数値を両方受け入れるようになりました。これより前のバージョンでは、数値のみを受け入れていました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecharup() の例

<?php

$im = imagecreate(100, 100);

$string = 'Note that the first letter is a N';

$bg = imagecolorallocate($im, 255, 255, 255);
$black = imagecolorallocate($im, 0, 0, 0);

// 白地に黒の "Z" を表示します
imagecharup($im, 3, 10, 10, $string, $black);

header('Content-type: image/png');
imagepng($im);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecharup()

参考

  • imagechar() - 水平に文字を描画する
  • imageloadfont() - 新しいフォントを読み込む


画像で使用する色を作成する

  • ≪ imagecharup
  • imagecolorallocatealpha ≫
  • PHP Manual
  • GD および Image 関数
  • 画像で使用する色を作成する

imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — 画像で使用する色を作成する

説明

imagecolorallocate(
GdImage $image,
int $red,
int $green,
int $blue
): int|false

指定した RGB を配色とする色の ID を返します。

imagecolorallocate() は image で表される画像上で使用する各々の色を作成する際にコールする必要があります。

注意:

imagecolorallocate() の最初のコールで パレットをもとにした画像 (imagecreate() を使用して作成した画像) で背景色がセットされます。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

これらの値は 0 から 255 までの整数か、あるいは 0x00 から 0XFF までの 16 進数です。

戻り値

色の ID、あるいは作成に失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecolorallocate() の例

<?php

$im = imagecreate(100, 100);

// 背景色を赤にします
$background = imagecolorallocate($im, 255, 0, 0);

// その他の色を設定します
$white = imagecolorallocate($im, 255, 255, 255);
$black = imagecolorallocate($im, 0, 0, 0);

// 十六進で指定します
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
$black = imagecolorallocate($im, 0x00, 0x00, 0x00);

?>

参考

  • imagecolorallocatealpha() - 画像で使用する色を透過度を指定して作成する
  • imagecolordeallocate() - イメージの色リソースを開放する


画像で使用する色を透過度を指定して作成する

  • ≪ imagecolorallocate
  • imagecolorat ≫
  • PHP Manual
  • GD および Image 関数
  • 画像で使用する色を透過度を指定して作成する

imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — 画像で使用する色を透過度を指定して作成する

説明

imagecolorallocatealpha(
GdImage $image,
int $red,
int $green,
int $blue,
int $alpha
): int|false

imagecolorallocatealpha() は、 透明度を指定するパラメータ alpha が追加されている以外は imagecolorallocate() と等価です。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

パラメータ red、green および blue には、 0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

戻り値

色 ID、あるいは作成に失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecolorallocatealpha() の使用例

<?php
$size = 300;
$image=imagecreatetruecolor($size, $size);

// 白い背景で黒いふちどりにします
$back = imagecolorallocate($image, 255, 255, 255);
$border = imagecolorallocate($image, 0, 0, 0);
imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

$yellow_x = 100;
$yellow_y = 75;
$red_x = 120;
$red_y = 165;
$blue_x = 187;
$blue_y = 125;
$radius = 150;

// alpha 値を指定して色を作成します
$yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
$red = imagecolorallocatealpha($image, 255, 0, 0, 75);
$blue = imagecolorallocatealpha($image, 0, 0, 255, 75);

// 3つの重なる円を描きます
imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

// 正しいヘッダを出力するのを忘れないように!
header('Content-Type: image/png');

// 最後に、結果を出力します
imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecolorallocatealpha 関数の使用例

例2 imagecolorallocatealpha() 関数を使い、典型的なアルファ値を変換する

アルファの値を 0 にすると、通常は完全に透過なピクセルが指定されますし、 アルファチャネルは 8bit です。このようなアルファ値を imagecolorallocatealpha() 関数と互換性がある値に変換するには、 いくつか簡単な計算をすれば十分です:

<?php
$alpha8 = 0; // 完全に透過
var_dump(127 - ($alpha8 >> 1));
$alpha8 = 255; // 完全に不透明
var_dump(127 - ($alpha8 >> 1));
?>

上の例の出力は以下となります。

int(127)
int(0)

参考

  • imagecolorallocate() - 画像で使用する色を作成する
  • imagecolordeallocate() - イメージの色リソースを開放する


ピクセルの色のインデックスを取得する

  • ≪ imagecolorallocatealpha
  • imagecolorclosest ≫
  • PHP Manual
  • GD および Image 関数
  • ピクセルの色のインデックスを取得する

imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — ピクセルの色のインデックスを取得する

説明

imagecolorat(GdImage $image, int $x, int $y): int|false

imageで指定された画像上の 特定位置にあるピクセルの色のインデックスを返します。

画像が True カラーイメージである場合、この関数はそのピクセルの RGB 値を整数で返します。 赤、緑、青のそれぞれの値にアクセスするにはビットシフトとマスキングを利用してください:

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x

点の x 座標。

y

点の y 座標。

戻り値

色のインデックスを返します。失敗した場合に false を返します

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 個々の RGB 値へのアクセス

<?php
$im = imagecreatefrompng("php.png");
$rgb = imagecolorat($im, 10, 15);
$r = ($rgb >> 16) & 0xFF;
$g = ($rgb >> 8) & 0xFF;
$b = $rgb & 0xFF;

var_dump($r, $g, $b);
?>

上の例の出力は、 たとえば以下のようになります。

int(119)
int(123)
int(180)

例2 imagecolorsforindex() による可読形式の RGB 値

<?php
$im = imagecreatefrompng("php.png");
$rgb = imagecolorat($im, 10, 15);

$colors = imagecolorsforindex($im, $rgb);

var_dump($colors);
?>

上の例の出力は、 たとえば以下のようになります。

array(4) {
  ["red"]=>
  int(119)
  ["green"]=>
  int(123)
  ["blue"]=>
  int(180)
  ["alpha"]=>
  int(127)
}

参考

  • imagecolorset() - 指定したパレットインデックスの色を設定する
  • imagecolorsforindex() - カラーインデックスからカラーを取得する
  • imagesetpixel() - 点を生成する


指定した色に最も近い色のインデックスを取得する

  • ≪ imagecolorat
  • imagecolorclosestalpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色に最も近い色のインデックスを取得する

imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — 指定した色に最も近い色のインデックスを取得する

説明

imagecolorclosest(
GdImage $image,
int $red,
int $green,
int $blue
): int

指定した RGB 値に「近い」 画像パレット中の色のインデックスを返します。

指定した色とパレット上の各色の「距離」は、 RGB 値が三次元空間上の点の座標を表すと考えて計算します。

画像をファイルから作成した場合は、画像内で使われている色だけを解決します。パレットにだけ存在する色は解決されません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

戻り値

画像パレット内で、指定した色にいちばん近い色のインデックスを返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 画像内での色セットの検索

<?php
// 画像を作成し、パレット画像に変換します
$im = imagecreatefrompng('figures/imagecolorclosest.png');
imagetruecolortopalette($im, false, 255);

// 探したい色 (RGB)
$colors = array(
array(254, 145, 154),
array(153, 145, 188),
array(153, 90, 145),
array(255, 137, 92)
);

// それぞれを検索し、パレット内でもっとも近い色を見つけます
// 検索番号、検索した RGB、そして見つかった RGB を返します
foreach($colors as $id => $rgb)
{
$result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
$result = imagecolorsforindex($im, $result);
$result = "({$result['red']}, {$result['green']}, {$result['blue']})";

echo "#$id: Search ($rgb[0], $rgb[1], $rgb[2]); Closest match: $result.\n";
}

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

#0: Search (254, 145, 154); Closest match: (252, 150, 148).
#1: Search (153, 145, 188); Closest match: (148, 150, 196).
#2: Search (153, 90, 145); Closest match: (148, 90, 156).
#3: Search (255, 137, 92); Closest match: (252, 150, 92).

参考

  • imagecolorexact() - 指定した色のインデックスを取得する
  • imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する
  • imagecolorclosesthwb() - 色合い、白、黒を有する色のインデックスを得る


指定した色+アルファ値に最も近い色のインデックスを取得する

  • ≪ imagecolorclosest
  • imagecolorclosesthwb ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色+アルファ値に最も近い色のインデックスを取得する

imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — 指定した色+アルファ値に最も近い色のインデックスを取得する

説明

imagecolorclosestalpha(
GdImage $image,
int $red,
int $green,
int $blue,
int $alpha
): int

指定した RGB 値と alpha レベルに 「近い」画像パレット中の色のインデックスを返します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

戻り値

画像パレット内で、指定した色にいちばん近い色のインデックスを返します。

例

例1 画像内での色セットの検索

<?php
// 画像を作成し、パレット画像に変換します
$im = imagecreatefrompng('figures/imagecolorclosest.png');
imagetruecolortopalette($im, false, 255);

// 探したい色 (RGB)
$colors = array(
array(254, 145, 154, 50),
array(153, 145, 188, 127),
array(153, 90, 145, 0),
array(255, 137, 92, 84)
);

// それぞれを検索し、パレット内でもっとも近い色を見つけます
// 検索番号、検索した RGB、そして見つかった RGB を返します
foreach($colors as $id => $rgb)
{
$result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
$result = imagecolorsforindex($im, $result);
$result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

echo "#$id: Search ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Closest match: $result.\n";
}

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

#0: Search (254, 145, 154, 50); Closest match: (252, 150, 148, 0).
#1: Search (153, 145, 188, 127); Closest match: (148, 150, 196, 0).
#2: Search (153, 90, 145, 0); Closest match: (148, 90, 156, 0).
#3: Search (255, 137, 92, 84); Closest match: (252, 150, 92, 0).

参考

  • imagecolorexactalpha() - 指定した色+アルファ値のインデックスを取得する
  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する
  • imagecolorclosesthwb() - 色合い、白、黒を有する色のインデックスを得る


色合い、白、黒を有する色のインデックスを得る

  • ≪ imagecolorclosestalpha
  • imagecolordeallocate ≫
  • PHP Manual
  • GD および Image 関数
  • 色合い、白、黒を有する色のインデックスを得る

imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — 色合い、白、黒を有する色のインデックスを得る

説明

imagecolorclosesthwb(
GdImage $image,
int $red,
int $green,
int $blue
): int

指定した色に最も近い色合い、白、黒を有する色のインデックスを取得します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

戻り値

指定した色に最も近い色合い、白、黒を有する色のインデックスを返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecolorclosesthwb() の使用例

<?php
$im = imagecreatefromgif('php.gif');

echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

HWB: 33

参考

  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する


イメージの色リソースを開放する

  • ≪ imagecolorclosesthwb
  • imagecolorexact ≫
  • PHP Manual
  • GD および Image 関数
  • イメージの色リソースを開放する

imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — イメージの色リソースを開放する

説明

imagecolordeallocate(GdImage $image, int $color): bool

imagecolorallocate() または imagecolorallocatealpha() で確保された色を開放します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

color

色 ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecolordeallocate() の使用法

<?php
$white = imagecolorallocate($im, 255, 255, 255);
imagecolordeallocate($im, $white);
?>

参考

  • imagecolorallocate() - 画像で使用する色を作成する
  • imagecolorallocatealpha() - 画像で使用する色を透過度を指定して作成する


指定した色のインデックスを取得する

  • ≪ imagecolordeallocate
  • imagecolorexactalpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色のインデックスを取得する

imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — 指定した色のインデックスを取得する

説明

imagecolorexact(
GdImage $image,
int $red,
int $green,
int $blue
): int

画像パレット中の特定の色のインデックスを返します。

画像をファイルから作成した場合は、画像内で使われている色だけを解決します。パレットにだけ存在する色は解決されません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

戻り値

指定した色の、パレット内でのインデックスを返します。 画像パレット中に色が存在しない場合は -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 GD ロゴからの色の取得

<?php
// 画像を用意します
$im = imagecreatefrompng('./gdlogo.png');

$colors = Array();
$colors[] = imagecolorexact($im, 255, 0, 0);
$colors[] = imagecolorexact($im, 0, 0, 0);
$colors[] = imagecolorexact($im, 255, 255, 255);
$colors[] = imagecolorexact($im, 100, 255, 52);

print_r($colors);

// メモリから解放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 16711680
    [1] => 0
    [2] => 16777215
    [3] => 6618932
)

参考

  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する


指定した色+アルファ値のインデックスを取得する

  • ≪ imagecolorexact
  • imagecolormatch ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色+アルファ値のインデックスを取得する

imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — 指定した色+アルファ値のインデックスを取得する

説明

imagecolorexactalpha(
GdImage $image,
int $red,
int $green,
int $blue,
int $alpha
): int

イメージのパレットで指定した色+アルファ値のインデックスを返します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

戻り値

イメージのパレットにおける、指定した色+アルファ値のインデックスを返します。 指定した色がイメージのパレットに存在しない場合、-1が返されます。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 GD ロゴからの色の取得

<?php

// 画像を用意します
$im = imagecreatefrompng('./gdlogo.png');

$colors = Array();
$colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
$colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
$colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
$colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

print_r($colors);

// メモリから開放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 16711680
    [1] => 2130706432
    [2] => 939524095
    [3] => 342163252
)

参考

  • imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する


パレットイメージの色を True カラーイメージに近づける

  • ≪ imagecolorexactalpha
  • imagecolorresolve ≫
  • PHP Manual
  • GD および Image 関数
  • パレットイメージの色を True カラーイメージに近づける

imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — パレットイメージの色を True カラーイメージに近づける

説明

imagecolormatch(GdImage $image1, GdImage $image2): bool

パレットイメージの色を True カラーイメージに近づけます。

パラメータ

image1

truecolor イメージオブジェクト

image2

パレットイメージオブジェクト。 image1 と同じ大きさの画像を指します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image1 と image2 は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource が期待されていました。

例

例1 imagecolormatch() の例

<?php
// true color 画像とパレット画像を用意します
$im1 = imagecreatefrompng('./gdlogo.png');
$im2 = imagecreate(imagesx($im1), imagesy($im1));

// いくつかの色を $im2 に追加します
$colors = Array();
$colors[] = imagecolorallocate($im2, 255, 36, 74);
$colors[] = imagecolorallocate($im2, 40, 0, 240);
$colors[] = imagecolorallocate($im2, 82, 100, 255);
$colors[] = imagecolorallocate($im2, 84, 63, 44);

// これらの色を true color 画像にマッチさせます
imagecolormatch($im1, $im2);

// メモリから開放します
imagedestroy($im1);
imagedestroy($im2);
?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する


指定した色または出来るだけ近い色のインデックスを得る

  • ≪ imagecolormatch
  • imagecolorresolvealpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色または出来るだけ近い色のインデックスを得る

imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — 指定した色または出来るだけ近い色のインデックスを得る

説明

imagecolorresolve(
GdImage $image,
int $red,
int $green,
int $blue
): int

この関数は、指定した色に関するインデックスを常に返します。 その色そのものまたは出来るだけ近い色へのインデックスが返されます。

画像をファイルから作成した場合は、画像内で使われている色だけを解決します。パレットにだけ存在する色は解決されません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

戻り値

色インデックスを返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecoloresolve() による画像からの色の取得

<?php
// 画像を読み込みます
$im = imagecreatefromgif('phplogo.gif');

// 最も近い色を画像から取得します
$colors = array();
$colors[] = imagecolorresolve($im, 255, 255, 255);
$colors[] = imagecolorresolve($im, 0, 0, 200);

// 出力します
print_r($colors);

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 89
    [1] => 85
)

参考

  • imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する


指定した色+アルファ値または最も近い色のインデックスを取得する

  • ≪ imagecolorresolve
  • imagecolorset ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した色+アルファ値または最も近い色のインデックスを取得する

imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — 指定した色+アルファ値または最も近い色のインデックスを取得する

説明

imagecolorresolvealpha(
GdImage $image,
int $red,
int $green,
int $blue,
int $alpha
): int

この関数は、指定した色のインデックスを必ず返します。そうでない場合、 正確な色または最も近い別の色のどちらかを返します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

0 から 127 までの値。 0 は完全に不透明な状態。 127 は完全に透明な状態を表します。

色のパラメータは、0 から 255 までの整数値か 0x00 から 0xFF までの十六進値を指定します。

戻り値

色インデックスを返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecoloresolvealpha() による画像からの色の取得

<?php
// 画像を読み込みます
$im = imagecreatefromgif('phplogo.gif');

// 最も近い色を画像から取得します
$colors = array();
$colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
$colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

// 出力します
print_r($colors);

imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 89
    [1] => 85
)

参考

  • imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する


指定したパレットインデックスの色を設定する

  • ≪ imagecolorresolvealpha
  • imagecolorsforindex ≫
  • PHP Manual
  • GD および Image 関数
  • 指定したパレットインデックスの色を設定する

imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — 指定したパレットインデックスの色を設定する

説明

imagecolorset(
GdImage $image,
int $color,
int $red,
int $green,
int $blue,
int $alpha = 0
): ?false

この関数は、パレット上で指定したインデックス index を 指定した色 color に設定します。 実際にぬりつぶしを実行するオーバーヘッドなしに パレット上の色を使用する画像をぬりつぶしたような効果を得る ことができ、便利です。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

color

パレットのインデックス。

red

赤コンポーネントの値。

green

緑コンポーネントの値。

blue

青コンポーネントの値。

alpha

アルファコンポーネントの値。

戻り値

この関数は、成功時に null を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecolorset() の例

<?php
// 300x100 の画像を作成します
$im = imagecreate(300, 100);

// 背景色を赤に設定します
imagecolorallocate($im, 255, 0, 0);

// 背景の色インデックスを取得します
$bg = imagecolorat($im, 0, 0);

// 背景色を青に設定します
imagecolorset($im, $bg, 0, 0, 255);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

参考

  • imagecolorat() - ピクセルの色のインデックスを取得する


カラーインデックスからカラーを取得する

  • ≪ imagecolorset
  • imagecolorstotal ≫
  • PHP Manual
  • GD および Image 関数
  • カラーインデックスからカラーを取得する

imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — カラーインデックスからカラーを取得する

説明

imagecolorsforindex(GdImage $image, int $color): array

指定したインデックスに対する色を取得します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

color

色インデックス。

戻り値

指定したカラーインデックス index に対して適当な値からなる red、green、blue をキーとする連想配列を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | color が範囲外の値の場合に、 imagecolorsforindex() は ValueError をスローするようになりました。 これより前のバージョンでは、 false を返していました。

例

例1 imagecolorsforindex() の例

<?php

// 画像をオープンします
$im = imagecreatefrompng('nexen.png');

// 色を取得します
$start_x = 40;
$start_y = 50;
$color_index = imagecolorat($im, $start_x, $start_y);

// 可読形式にします
$color_tran = imagecolorsforindex($im, $color_index);

// どんな内容でしょう?
print_r($color_tran);

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
   [red] => 226
   [green] => 222
   [blue] => 252
   [alpha] => 0
)

参考

  • imagecolorat() - ピクセルの色のインデックスを取得する
  • imagecolorexact() - 指定した色のインデックスを取得する


画像パレットの色数を検出する

  • ≪ imagecolorsforindex
  • imagecolortransparent ≫
  • PHP Manual
  • GD および Image 関数
  • 画像パレットの色数を検出する

imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — 画像パレットの色数を検出する

説明

imagecolorstotal(GdImage $image): int

指定した画像パレットの色数を返します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

指定した画像パレットの色数を返します。 truecolor 画像の場合は 0 を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagecolorstotal() による画像の色の総数の取得

<?php
// 画像のインスタンスを作成します
$im = imagecreatefromgif('php.gif');

echo '色の総数: ' . imagecolorstotal($im);

// 画像を解放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

色の総数: 128

参考

  • imagecolorat() - ピクセルの色のインデックスを取得する
  • imagecolorsforindex() - カラーインデックスからカラーを取得する
  • imageistruecolor() - 画像が truecolor かどうか調べる


透明色を定義する

  • ≪ imagecolorstotal
  • imageconvolution ≫
  • PHP Manual
  • GD および Image 関数
  • 透明色を定義する

imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — 透明色を定義する

説明

imagecolortransparent(GdImage $image, ?int $color = null): int

指定した画像 image 上の透明色を設定したり、取得したりします。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

color

imagecolorallocate() で作成された色識別子。

戻り値

新しい透明色の ID (指定しなかった場合は現在設定されている ID) を返します。color が null の場合、 かつ現在の透明色も設定されていない場合は -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | color は、nullable になりました。

例

例1 imagecolortransparent() の例

<?php
// 55x30 の画像を作成します
$im = imagecreatetruecolor(55, 30);
$red = imagecolorallocate($im, 255, 0, 0);
$black = imagecolorallocate($im, 0, 0, 0);

// 背景を透明にします
imagecolortransparent($im, $black);

// 赤い矩形を描画します
imagefilledrectangle($im, 4, 4, 50, 25, $red);

// 画像を保存します
imagepng($im, './imagecolortransparent.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecolortransparent()

注意

注意:

透過性は imagecopymerge() かつ True カラーの場合のみコピーされます。imagecopy() もしくはパレットイメージの場合はコピーされません。

注意:

透明色は画像のプロパティであり、色のプロパティではありません。 ある色を透明色と定義したら、画像上で既にその色で着色されてる領域も 透明になります。


div および offset の係数を使用し、3x3 の畳み込み配列を適用する

  • ≪ imagecolortransparent
  • imagecopy ≫
  • PHP Manual
  • GD および Image 関数
  • div および offset の係数を使用し、3x3 の畳み込み配列を適用する

imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — div および offset の係数を使用し、3x3 の畳み込み配列を適用する

説明

imageconvolution(
GdImage $image,
array $matrix,
float $divisor,
float $offset
): bool

画像に畳み込み配列を適用します。 指定した係数とオフセットを使用します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

matrix

3x3 の配列。三つの float 値からなる三つの配列の配列。

divisor

畳み込み結果の除数。正規化で使用します。

offset

色オフセット。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 PHP.net ロゴのエンボス加工

<?php
$image = imagecreatefromgif('http://www.php.net/images/php.gif');

$emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
imageconvolution($image, $emboss, 1, 127);

header('Content-Type: image/png');
imagepng($image, null, 9);
?>

上の例の出力は以下となります。

出力例 : PHP.net ロゴのエンボス加工

例2 ガウス分布のぼかし

<?php
$image = imagecreatetruecolor(180,40);

// テキストを書き、画像にガウス分布のぼかしを適用します
imagestring($image, 5, 10, 8, 'Gaussian Blur Text', 0x00ff00);
$gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
imageconvolution($image, $gaussian, 16, 0);

// 比較用にもう一度テキストを書きます
imagestring($image, 5, 10, 18, 'Gaussian Blur Text', 0x00ff00);

header('Content-Type: image/png');
imagepng($image, null, 9);
?>

上の例の出力は以下となります。

出力例 : ガウス分布のぼかし

参考

  • imagefilter() - 画像にフィルタを適用する


画像の一部をコピーする

  • ≪ imageconvolution
  • imagecopymerge ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の一部をコピーする

imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — 画像の一部をコピーする

説明

imagecopy(
GdImage $dst_image,
GdImage $src_image,
int $dst_x,
int $dst_y,
int $src_x,
int $src_y,
int $src_width,
int $src_height
): bool

src_image の一部、つまり、x,y座標 src_x, src_y を基準として幅 src_width、高さ src_height の領域を dst_image にコピーします。指定された領域は、x,y座標 dst_x,dst_yにコピー されます。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

src_width

コピー元の幅。

src_height

コピー元の高さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dst_image と src_image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource が期待されていました。

例

例1 PHP.net のロゴの切り取り

<?php
// 画像のインスタンスを作成します
$src = imagecreatefromgif('php.gif');
$dest = imagecreatetruecolor(80, 40);

// コピーします
imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

// 出力してメモリから解放します
header('Content-Type: image/gif');
imagegif($dest);

imagedestroy($dest);
imagedestroy($src);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : PHP.net のロゴの切り取り

参考

  • imagecrop() - 指定した矩形に画像をクロップする


イメージの一部をコピー、マージする

  • ≪ imagecopy
  • imagecopymergegray ≫
  • PHP Manual
  • GD および Image 関数
  • イメージの一部をコピー、マージする

imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — イメージの一部をコピー、マージする

説明

imagecopymerge(
GdImage $dst_image,
GdImage $src_image,
int $dst_x,
int $dst_y,
int $src_x,
int $src_y,
int $src_width,
int $src_height,
int $pct
): bool

src_image のsrc_x, src_y で始まる幅 src_width 、 高さ src_heightの領域を x,y座標で指定した dst_image にコピーします。 定義された部分は、x,y座標、dst_x、 dst_yにコピーされます。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

src_width

コピー元の幅。

src_height

コピー元の高さ。

pct

二つの画像は、 0から100の範囲で指定した pctに基づきマージされます。 pct = 0 の時は、何も行われません。 100の場合、この関数の動作は、パレットイメージに対する imagecopy() と同じとなります (アルファコンポーネントを無視する点だけが違います)。 一方 true color 画像については、この関数はアルファ透過度を実装しています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dst_image と src_image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource が期待されていました。

例

例1 2 つの PHP.net ロゴを 75% の透過度でマージ

<?php
// 画像のインスタンスを作成します
$dest = imagecreatefromgif('php.gif');
$src = imagecreatefromgif('php.gif');

// コピー・マージします
imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

// 出力してメモリから解放します
header('Content-Type: image/gif');
imagegif($dest);

imagedestroy($dest);
imagedestroy($src);
?>


グレースケールでイメージの一部をコピー、マージする

  • ≪ imagecopymerge
  • imagecopyresampled ≫
  • PHP Manual
  • GD および Image 関数
  • グレースケールでイメージの一部をコピー、マージする

imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — グレースケールでイメージの一部をコピー、マージする

説明

imagecopymergegray(
GdImage $dst_image,
GdImage $src_image,
int $dst_x,
int $dst_y,
int $src_x,
int $src_y,
int $src_width,
int $src_height,
int $pct
): bool

imagecopymergegray() は、 src_image の X,Y座標 src_x, src_y から 始まる幅 src_width、高さ src_height の領域を dst_image にコピーします。 定義された部分は、x、y座標dst_x、 dst_yにコピーされます。

この関数は imagecopymerge() と同じですが、マー ジをする際に、コピー前にコピー先のピクセルをグレースケールに変換 することにより、コピー先のピクセルをコピー元の色相を維持するとこ ろが異なります。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

src_width

コピー元の幅。

src_height

コピー元の高さ。

pct

src_image が pct にしたがってグレースケールに変換されます。 pct が 0 の場合は完全なグレースケール、 100 の場合は何も変わらない状態となります。 pct = 100 の場合、パレット画像に対してはこの関数は imagecopy() と同じ動作となります (アルファコンポーネントを無視する点だけが違います)。 一方 true color 画像については、この関数はアルファ透過度を実装しています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dst_image と src_image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource を期待していました。

例

例1 imagecopymergegray() の使用法

<?php
// 画像のインスタンスを作成します
$dest = imagecreatefromgif('php.gif');
$src = imagecreatefromgif('php.gif');

// コピー・マージ (Gray = 20%) します
imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

// 出力してメモリから解放します
header('Content-Type: image/gif');
imagegif($dest);

imagedestroy($dest);
imagedestroy($src);
?>


再サンプリングを行いイメージの一部をコピー、伸縮する

  • ≪ imagecopymergegray
  • imagecopyresized ≫
  • PHP Manual
  • GD および Image 関数
  • 再サンプリングを行いイメージの一部をコピー、伸縮する

imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — 再サンプリングを行いイメージの一部をコピー、伸縮する

説明

imagecopyresampled(
GdImage $dst_image,
GdImage $src_image,
int $dst_x,
int $dst_y,
int $src_x,
int $src_y,
int $dst_width,
int $dst_height,
int $src_width,
int $src_height
): bool

imagecopyresampled() は、イメージの矩形の部分 を別のイメージにコピーします。同時にピクセル値を滑らかに補間を行い、 このため、特にサイズを小さくした場合には鮮明さが維持されます。

言い換えると、imagecopyresampled() は src_image の座標 (src_x,src_y) にある 幅 src_width、高さ src_height の矩形領域を受け取って、それを dst_image の座標 (dst_x,dst_y) にある幅 dst_width、 高さ dst_height の矩形領域に配置します。

コピー元とコピー先の座標、幅、高さが異なる場合には、 適当なイメージ伸縮が行われます。座標は、左上を基準とします。 この関数は、同じイメージ内の領域にコピーする場合にも使用可能です (dst_image が src_image と同じ場合) が、領域が重なる場合の結果は予測できません。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

dst_width

コピー先の幅。

dst_height

コピー先の高さ。

src_width

コピー元の幅。

src_height

コピー元の高さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dst_image と src_image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource を期待していました。

例

例1 単純な例

この例は、イメージをオリジナルの半分のサイズに再サンプルします。

<?php
// ファイル
$filename = 'test.jpg';
$percent = 0.5;

// コンテントタイプ
header('Content-Type: image/jpeg');

// 新規サイズを取得します
list($width, $height) = getimagesize($filename);
$new_width = $width * $percent;
$new_height = $height * $percent;

// 再サンプル
$image_p = imagecreatetruecolor($new_width, $new_height);
$image = imagecreatefromjpeg($filename);
imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

// 出力
imagejpeg($image_p, null, 100);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 単純な例

例2 イメージを均等に再サンプルする

この例は最大の幅もしくは高さが 200 ピクセルのイメージを表示します。

<?php
// ファイル
$filename = 'test.jpg';

// 最大の高さ・幅を設定します
$width = 200;
$height = 200;

// コンテントタイプ
header('Content-Type: image/jpeg');

// 新規サイズを取得します
list($width_orig, $height_orig) = getimagesize($filename);

$ratio_orig = $width_orig/$height_orig;

if ($width/$height > $ratio_orig) {
$width = $height*$ratio_orig;
} else {
$height = $width/$ratio_orig;
}

// 再サンプル
$image_p = imagecreatetruecolor($width, $height);
$image = imagecreatefromjpeg($filename);
imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

// 出力
imagejpeg($image_p, null, 100);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : イメージを均等に再サンプルする

注意

注意:

パレットイメージの制限(255+1色)による問題があります。 カラーの再サンプリングやフィルタリングには通常は255色以上の色が 必要となります。再サンプルするピクセルとその色を計算するために ある種の近似計算が使用されます。パレットに新しい色を割り当てよう として失敗すると、(理論的に)最も近い色が選択されます。 それは必ずしも常に可視色とは限りません。そのため、 空白(あるいは不可視な)といった不可思議な結果がもたらされます。 この問題を回避するには、imagecreatetruecolor()で 生成されるようなTrueカラーイメージを目的のイメージとして 使用してください。

参考

  • imagecopyresized() - 画像の一部をコピーしサイズを変更する
  • imagescale() - 幅と高さを指定して、画像の縮尺を変更する
  • imagecrop() - 指定した矩形に画像をクロップする


画像の一部をコピーしサイズを変更する

  • ≪ imagecopyresampled
  • imagecreate ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の一部をコピーしサイズを変更する

imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — 画像の一部をコピーしサイズを変更する

説明

imagecopyresized(
GdImage $dst_image,
GdImage $src_image,
int $dst_x,
int $dst_y,
int $src_x,
int $src_y,
int $dst_width,
int $dst_height,
int $src_width,
int $src_height
): bool

imagecopyresized() は指定した画像の矩形部分を 別の画像へコピーします。dst_image はコピー先の イメージ ID、src_image はコピー元のイメージ ID です。

言い換えると、imagecopyresized() は src_image の座標 (src_x,src_y) にある 幅 src_width、 高さ src_height の矩形領域を受け取って、それを dst_image の座標 (dst_x,dst_y) にある幅 dst_width、 高さ dst_height の矩形領域に配置します。

コピー先とコピー元の座標、幅、高さが異なった場合、画像の一部が 適当に伸縮されます。座標の原点は左上です。(仮に、 dst_image と src_image が 同一であれば)関数は領域のコピーに使うことができますが、領域が 重なったときの結果は予測できません。

パラメータ

dst_image

コピー先の画像リソース。

src_image

コピー元の画像リソース。

dst_x

コピー先の x 座標。

dst_y

コピー先の y 座標。

src_x

コピー元の x 座標。

src_y

コピー元の y 座標。

dst_width

コピー先の幅。

dst_height

コピー先の高さ。

src_width

コピー元の幅。

src_height

コピー元の高さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | dst_image と src_image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource を期待していました。

例

例1 イメージをリサイズする

この例はイメージを半分のサイズで表示します。

<?php
// ファイルと新規サイズ
$filename = 'test.jpg';
$percent = 0.5;

// コンテントタイプ
header('Content-Type: image/jpeg');

// 新規サイズを取得します
list($width, $height) = getimagesize($filename);
$newwidth = $width * $percent;
$newheight = $height * $percent;

// 読み込み
$thumb = imagecreatetruecolor($newwidth, $newheight);
$source = imagecreatefromjpeg($filename);

// リサイズ
imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

// 出力
imagejpeg($thumb);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : イメージをリサイズする

イメージは半分サイズで出力されますが、 imagecopyresampled() を使用するとより良い品質になります。

注意

注意:

パレットイメージの制限(255+1 色)による問題があります。 カラーの再サンプリングやフィルタリングには通常は 255 色以上の色が 必要となります。再サンプルするピクセルとその色を計算するために ある種の近似計算が使用されます。パレットに新しい色を割り当てよう として失敗すると、(理論的に)最も近い色が選択されます。 それは必ずしも常に可視色とは限りません。そのため、 空白(あるいは不可視な)といった不可思議な結果がもたらされます。 この問題を回避するには、imagecreatetruecolor() で 生成されるような True カラーイメージを目的のイメージとして 使用してください。

参考

  • imagecopyresampled() - 再サンプリングを行いイメージの一部をコピー、伸縮する
  • imagescale() - 幅と高さを指定して、画像の縮尺を変更する
  • imagecrop() - 指定した矩形に画像をクロップする


パレットを使用する新規画像を作成する

  • ≪ imagecopyresized
  • imagecreatefromavif ≫
  • PHP Manual
  • GD および Image 関数
  • パレットを使用する新規画像を作成する

imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — パレットを使用する新規画像を作成する

説明

imagecreate(int $width, int $height): GdImage|false

imagecreate() は、 指定した大きさの空の画像を表す画像 ID を返します。

一般に、imagecreate() よりは
imagecreatetruecolor() を使うことを推奨します。
より高品質な画像処理ができるからです。パレット形式の画像を出力したい場合は、
imagepng() や
imagegif() で画像を保存する直前に
imagetruecolortopalette() を呼ばなければいけません。

パラメータ

width

画像の幅。

height

画像の高さ。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 新しい GD 画像ストリームの作成および画像の出力

<?php
header("Content-Type: image/png");
$im = @imagecreate(110, 20)
or die("Cannot Initialize new GD image stream");
$background_color = imagecolorallocate($im, 0, 0, 0);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, "A Simple Text String", $text_color);
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 新しい GD 画像ストリームの作成および画像の出力

参考

  • imagedestroy() - 画像を破棄する
  • imagecreatetruecolor() - TrueColor イメージを新規に作成する


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreate
  • imagecreatefrombmp ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromavif(string $filename): GdImage|false

imagecreatefromavif() は、 指定されたファイルから取得した画像を表す、 画像オブジェクトを返します。

パラメータ

filename

AVIF ラスタ画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromavif
  • imagecreatefromgd ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefrombmp(string $filename): GdImage|false

imagecreatefrombmp() は、指定したファイル名から 得られたイメージを表すイメージ ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

BMP 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource が返されていました。

例

例1 imagecreatefrombmp() を使用した BMP 画像から PNG 画像への変換

<?php
// BMP ファイルを読み込み
$im = imagecreatefrombmp('./example.bmp');

// デフォルト設定で PNG ファイルへ変換
imagepng($im, './example.png');
imagedestroy($im);
?>


GD ファイルまたは URL から新規イメージを生成する

  • ≪ imagecreatefrombmp
  • imagecreatefromgd2 ≫
  • PHP Manual
  • GD および Image 関数
  • GD ファイルまたは URL から新規イメージを生成する

imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する

説明

imagecreatefromgd(string $filename): GdImage|false

GD ファイルまたは URL から新規イメージを生成します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource が返されていました。

例

例1 imagecreatefromgd() の例

<?php
// gd 画像を読み込みます
$im = @imagecreatefromgd('./test.gd');

// 画像が読み込まれているかどうかを調べます
if(!$im)
{
die('gd 画像を読み込めません!');
}

// ここで画像処理をします

// 画像を保存します
imagegd($im, './test_updated.gd');
imagedestroy($im);
?>

注意

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。


GD2 ファイルまたは URL から新規イメージを生成する

  • ≪ imagecreatefromgd
  • imagecreatefromgd2part ≫
  • PHP Manual
  • GD および Image 関数
  • GD2 ファイルまたは URL から新規イメージを生成する

imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する

説明

imagecreatefromgd2(string $filename): GdImage|false

GD2 ファイルまたは URL から新規イメージを生成します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

GD2 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 imagecreatefromgd2() の例

<?php
// gd2 画像を読み込みます
$im = imagecreatefromgd2('./test.gd2');

// 画像にエフェクトを施します。ここでは、
// 画像の打ち消しを行います
if(function_exists('imagefilter'))
{
imagefilter($im, IMG_FILTER_NEGATE);
}

// 画像を保存します
imagegd2($im, './test_updated.gd2');
imagedestroy($im);
?>

注意

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。


GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

  • ≪ imagecreatefromgd2
  • imagecreatefromgif ≫
  • PHP Manual
  • GD および Image 関数
  • GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

説明

imagecreatefromgd2part(
string $filename,
int $x,
int $y,
int $width,
int $height
): GdImage|false

GD2 ファイルまたは URL の指定した部分から新規イメージを生成します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

GD2 画像へのパス。

x

作成元の x 座標。

y

作成元の y 座標。

width

コピー元の幅。

height

コピー元の高さ。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 imagecreatefromgd2part() の例

<?php
// この例では、まず画像のサイズが必要となります
$image = getimagesize('./test.gd2');

// 画像のサイズを取得し、
// 画像のインスタンスを作成します
$im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

// 画像処理をします。
// ここでは、エンボス処理を行っています
if(function_exists('imagefilter'))
{
imagefilter($im, IMG_FILTER_EMBOSS);
}

// 最適化した画像を保存します
imagegd2($im, './test_emboss.gd2');
imagedestroy($im);
?>

注意

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromgd2part
  • imagecreatefromjpeg ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromgif(string $filename): GdImage|false

imagecreatefromgif() は、 指定したファイル名の画像を表す画像 ID を返します。

警告

GIF ファイルをメモリに取り込む際、最初のフレームだけが 画像オブジェクトで返されます。getimagesize() で報告される画像サイズは必ずしも必要ありません。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

GIF 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 GIF の作成時のエラーを処理する例

<?php
function LoadGif($imgname)
{
/* オープンします */
$im = @imagecreatefromgif($imgname);

/* 失敗したかどうかを調べます */
if(!$im)
{
/* 空の画像を作成します */
$im = imagecreatetruecolor (150, 30);
$bgc = imagecolorallocate ($im, 255, 255, 255);
$tc = imagecolorallocate ($im, 0, 0, 0);

imagefilledrectangle ($im, 0, 0, 150, 30, $bgc);

/* エラーメッセージを出力します */
imagestring ($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
}

return $im;
}

header('Content-Type: image/gif');

$img = LoadGif('bogus.image');

imagegif($img);
imagedestroy($img);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : GIF の作成時のエラーを処理する例


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromgif
  • imagecreatefrompng ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromjpeg(string $filename): GdImage|false

imagecreatefromjpeg() は引数 filename から得られる画像を表すイメージIDを返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

JPEG 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 JPEG の作成時のエラーを処理する例

<?php
function LoadJpeg($imgname)
{
/* オープンします */
$im = @imagecreatefromjpeg($imgname);

/* 失敗したかどうかを調べます */
if(!$im)
{
/* 空の画像を作成します */
$im = imagecreatetruecolor(150, 30);
$bgc = imagecolorallocate($im, 255, 255, 255);
$tc = imagecolorallocate($im, 0, 0, 0);

imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

/* エラーメッセージを出力します */
imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
}

return $im;
}

header('Content-Type: image/jpeg');

$img = LoadJpeg('bogus.image');

imagejpeg($img);
imagedestroy($img);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : JPEG の作成時のエラーを処理する例


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromjpeg
  • imagecreatefromstring ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefrompng(string $filename): GdImage|false

imagecreatefrompng()は引数 filename から得られる画像を表す画像 ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

PNG 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 PNG の作成時のエラーを処理する例

<?php
function LoadPNG($imgname)
{
/* オープンします */
$im = @imagecreatefrompng($imgname);

/* 失敗したかどうかを調べます */
if(!$im)
{
/* 空の画像を作成します */
$im = imagecreatetruecolor(150, 30);
$bgc = imagecolorallocate($im, 255, 255, 255);
$tc = imagecolorallocate($im, 0, 0, 0);

imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

/* エラーメッセージを出力します */
imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
}

return $im;
}

header('Content-Type: image/png');

$img = LoadPNG('bogus.image');

imagepng($img);
imagedestroy($img);
?>

上の例の出力は、 たとえば以下のようになります。


文字列の中のイメージストリームから新規イメージを作成する

  • ≪ imagecreatefrompng
  • imagecreatefromtga ≫
  • PHP Manual
  • GD および Image 関数
  • 文字列の中のイメージストリームから新規イメージを作成する

imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する

説明

imagecreatefromstring(string $data): GdImage|false

imagecreatefromstring() は、指定した data から 得られたイメージを表すイメージ ID を返します。もし、PHP が JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP, AVIF をサポートするようビルドされている場合、 イメージの種類は自動的に判別されます。

パラメータ

data

画像データを含む文字列。

戻り値

成功時にはイメージオブジェクトが返されます。 イメージの種類がサポートされていない、データのフォーマットが識別できない、 イメージが壊れておりリロードできないなどの場合は false が返されます。

エラー / 例外

認識できない書式のデータを受け取った場合に、 imagecreatefromstring() は E_WARNING レベルのエラーを発行します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
7.3.0 | WEBP がサポートされました。 (但し、使っている libgd がサポートしている場合に限ります)

例

例1 imagecreatefromstring() の例

<?php
$data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
. 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
. 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
. '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg==';
$data = base64_decode($data);

$im = imagecreatefromstring($data);
if ($im !== false) {
header('Content-Type: image/png');
imagepng($im);
imagedestroy($im);
}
else {
echo 'エラーが発生しました。';
}
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagecreatefromstring()

参考

  • imagecreatefromjpeg() - 新しい画像をファイルあるいは URL から作成する
  • imagecreatefrompng() - 新しい画像をファイルあるいは URL から作成する
  • imagecreatefromgif() - 新しい画像をファイルあるいは URL から作成する
  • imagecreatetruecolor() - TrueColor イメージを新規に作成する


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromstring
  • imagecreatefromwbmp ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromtga(string $filename): GdImage|false

imagecreatefromtga() は 指定されたファイルから、画像オブジェクトを返します。

パラメータ

filename

Truevision TGA 画像ファイルへのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は GdImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromtga
  • imagecreatefromwebp ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromwbmp(string $filename): GdImage|false

imagecreatefromwbmp() は、指定したファイル名から 得られたイメージを表すイメージ ID を返します。

注意: WBMP画像は、Windows bitmp ではなく、ワイヤレスビットマップです。 Windows bitmap は、imagecreatefrombmp() 関数を使って読み込むことができます。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

WBMP 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 WBMP の作成時のエラーを処理する例

<?php
function LoadWBMP($imgname)
{
/* オープンします */
$im = @imagecreatefromwbmp($imgname);

/* 失敗したかどうかを調べます */
if(!$im)
{
/* 空の画像を作成します */
$im = imagecreatetruecolor(150, 30);
$bgc = imagecolorallocate($im, 255, 255, 255);
$tc = imagecolorallocate($im, 0, 0, 0);

imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

/* エラーメッセージを出力します */
imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
}

return $im;
}

header('Content-Type: image/vnd.wap.wbmp');

$img = LoadWBMP('bogus.image');

imagewbmp($img);
imagedestroy($img);
?>


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromwbmp
  • imagecreatefromxbm ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromwebp(string $filename): GdImage|false

imagecreatefromwebp() は、指定したファイル名から得られる画像を表す ID を返します。 アニメーションWebP は読み取れないことに注意して下さい。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

WebP 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 imagecreatefromwebp() を使った、WebP から jpeg への変換

<?php
// WebP ファイルを読み込みます
$im = imagecreatefromwebp('./example.webp');

// 100% のクオリティで jpeg ファイルに変換します
imagejpeg($im, './example.jpeg', 100);
imagedestroy($im);
?>


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromwebp
  • imagecreatefromxpm ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromxbm(string $filename): GdImage|false

imagecreatefromxbm() は、指定した filename から得られたイメージを表すイメージIDを返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

XBM 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 XBM 画像から png 画像への imagecreatefromxbm() を用いた変換

<?php
// xbm ファイルを読み込みます
$xbm = imagecreatefromxbm('./example.xbm');

// それを png ファイルに変換します
imagepng($xbm, './example.png');
imagedestroy($xbm);
?>


新しい画像をファイルあるいは URL から作成する

  • ≪ imagecreatefromxbm
  • imagecreatetruecolor ≫
  • PHP Manual
  • GD および Image 関数
  • 新しい画像をファイルあるいは URL から作成する

imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — 新しい画像をファイルあるいは URL から作成する

説明

imagecreatefromxpm(string $filename): GdImage|false

imagecreatefromxpm() は、指定した filename から得られたイメージを表すイメージ ID を返します。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

パラメータ

filename

XPM 画像へのパス。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 imagecreatefromxpm() による画像インスタンスの作成

<?php
// XPM に対応しているかどうかを調べます
if(!(imagetypes() & IMG_XPM))
{
die('Support for xpm was not found!');
}

// 画像インスタンスを作成します
$xpm = imagecreatefromxpm('./example.xpm');

// ここで画像の操作をします

// PHP は xpm 画像の書き出しをサポートしていないので、
// ここでは、画像を 100% の品質の jpeg ファイルとして保存します
imagejpeg($xpm, './example.jpg', 100);
imagedestroy($xpm);
?>


TrueColor イメージを新規に作成する

  • ≪ imagecreatefromxpm
  • imagecrop ≫
  • PHP Manual
  • GD および Image 関数
  • TrueColor イメージを新規に作成する

imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — TrueColor イメージを新規に作成する

説明

imagecreatetruecolor(int $width, int $height): GdImage|false

imagecreatetruecolor() は、指定した大きさの黒い画像を表す画像オブジェクトを返します。

パラメータ

width

画像の幅。

height

画像の高さ。

戻り値

成功した場合に画像オブジェクト、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 新規 GD イメージストリームの作成およびイメージの出力

<?php
header ('Content-Type: image/png');
$im = @imagecreatetruecolor(120, 20)
or die('Cannot Initialize new GD image stream');
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 新規 GD イメージストリームの作成およびイメージの出力

参考

  • imagedestroy() - 画像を破棄する
  • imagecreate() - パレットを使用する新規画像を作成する


指定した矩形に画像をクロップする

  • ≪ imagecreatetruecolor
  • imagecropauto ≫
  • PHP Manual
  • GD および Image 関数
  • 指定した矩形に画像をクロップする

imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — 指定した矩形に画像をクロップする

説明

imagecrop(GdImage $image, array $rectangle): GdImage|false

画像を指定した矩形範囲にクロップして、クロップ後の画像を返します。 パラメータ image で渡した画像には何も手を加えません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

rectangle

クロップする矩形を配列で指定します。配列のキーには x, y, width, height を指定します。

戻り値

成功した場合にクロップ後の画像オブジェクトを返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 imagecrop() の例

この例は、画像を正方形にクロップする方法を示すものです。

<?php
$im = imagecreatefrompng('example.png');
$size = min(imagesx($im), imagesy($im));
$im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
if ($im2 !== FALSE) {
imagepng($im2, 'example-cropped.png');
imagedestroy($im2);
}
imagedestroy($im);
?>

参考

  • imagecropauto() - 利用可能なモードを指定して、画像を自動的にクロップする


利用可能なモードを指定して、画像を自動的にクロップする

  • ≪ imagecrop
  • imagedashedline ≫
  • PHP Manual
  • GD および Image 関数
  • 利用可能なモードを指定して、画像を自動的にクロップする

imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — 利用可能なモードを指定して、画像を自動的にクロップする

説明

imagecropauto(
GdImage $image,
int $mode = IMG_CROP_DEFAULT,
float $threshold = 0.5,
int $color = -1
): GdImage|false

指定した mode にしたがって、画像を自動的にクロップします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

mode

以下の定数のいずれか。

IMG_CROP_DEFAULT
IMG_CROP_TRANSPARENT と同じです。 PHP 7.4.0 より前のバージョンでは、 PHP にバンドルされた libgd は、 画像に透過色がない場合に IMG_CROP_SIDES にフォールバックしていました。
IMG_CROP_TRANSPARENT
透過色の背景をクロップします。
IMG_CROP_BLACK
黒の背景をクロップします。
IMG_CROP_WHITE
白の背景をクロップします。
IMG_CROP_SIDES
画像の四隅から、クロップする背景色を検出します。
IMG_CROP_THRESHOLD
threshold と color を用いてクロップします。
threshold

画像の色とクロップする色を比較する際に用いる許容誤差を、パーセントで指定します。 色の違いを判断する際には、RGBキューブ内での距離を用います。

IMG_CROP_THRESHOLD モードのときにだけ利用します。

注意: PHP 7.4.0 より前のバージョンでは、 PHP にバンドルされていた libgd はやや異なるアルゴリズムを用いていました。 なので、同じ threshold を渡しても システムの libgd と PHP にバンドルされた libgd とは異なる結果が生成されていました。

color

RGB値あるいはパレットインデックスを指定します。

IMG_CROP_THRESHOLD モードのときにだけ利用します。

戻り値

成功した場合にクロップ後の画像オブジェクトを返します。 失敗した場合に false を返します 画像全体がクロップされてしまった場合にも false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
7.4.0 | PHP にバンドルされた imagecropauto() の振る舞いは、 システムにインストールされる libgd のそれと同じになりました。 つまり、IMG_CROP_DEFAULT が IMG_CROP_SIDES にフォールバックすることはなくなり、 しきい値によるクロップは、 システムにインストールされる libgd のアルゴリズムと同じものを使うようになりました。
7.4.0 | mode パラメータのデフォルト値が IMG_CROP_AUTO に変更されました。 これより前のバージョンでは、デフォルト値は -1 で、IMG_CROP_DEFAULT に対応しています。 しかし、-1 を渡すのは非推奨になりました。

例

例1 自動クロップの適切な処理

戻り値のところで説明したとおり、全部クロップしてしまったときに imagecropauto() が返す値は false となります。 この例では、クロップする部分がある場合にだけ画像オブジェクト $im を自動クロップします。 それ以外の場合は、元の画像をそのまま使います。

<?php
$cropped = imagecropauto($im, IMG_CROP_DEFAULT);
if ($cropped !== false) { // 新しい画像オブジェクトが戻された場合にだけ
imagedestroy($im); // 元の画像を破棄して
$im = $cropped; // クロップ後の画像を $im に代入します
}
?>

参考

  • imagecrop() - 指定した矩形に画像をクロップする


破線を描画する

  • ≪ imagecropauto
  • imagedestroy ≫
  • PHP Manual
  • GD および Image 関数
  • 破線を描画する

imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — 破線を描画する

説明

imagedashedline(
GdImage $image,
int $x1,
int $y1,
int $x2,
int $y2,
int $color
): bool

これは古い関数です。代わりに imagesetstyle() と imageline() の組み合せを使用してください。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x1

左上の x 座標。

y1

左上の y 座標 0。0 は画像の左上の角です。

x2

右下の x 座標。

y2

右下の y 座標。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagedashedline() の例

<?php
// 100x100 の画像を作成します
$im = imagecreatetruecolor(100, 100);
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

// 縦の破線を描画します
imagedashedline($im, 50, 25, 50, 75, $white);

// 画像を保存します
imagepng($im, './dashedline.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagedashedline()

例2 imagedashedline() のもうひとつの使用法

<?php
// 100x100 の画像を作成します
$im = imagecreatetruecolor(100, 100);
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

// 独自のスタイルの作成: 最初の 4 ピクセルを白色、
// 次の 4 ピクセルを透明とし、破線風の効果を作成します
$style = Array(
$white,
$white,
$white,
$white,
IMG_COLOR_TRANSPARENT,
IMG_COLOR_TRANSPARENT,
IMG_COLOR_TRANSPARENT,
IMG_COLOR_TRANSPARENT
);

imagesetstyle($im, $style);

// 破線を描画します
imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

// 画像を保存します
imagepng($im, './imageline.png');
imagedestroy($im);
?>

参考

  • imagesetstyle() - 線描画用のスタイルを設定する
  • imageline() - 直線を描画する


画像を破棄する

  • ≪ imagedashedline
  • imageellipse ≫
  • PHP Manual
  • GD および Image 関数
  • 画像を破棄する

imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — 画像を破棄する

説明

imagedestroy(GdImage $image): bool

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

PHP 8.0.0 より前のバージョンでは、 imagedestroy() は画像 image を保持するメモリを解放していました。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は何も処理を行わなくなりました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 PHP 8.0.0 より前のバージョンでの imagedestroy() の使用例

<?php
// 100 x 100 の画像を作成します
$im = imagecreatetruecolor(100, 100);

// 画像を変更したり保存したりします

// 画像をメモリから開放します
imagedestroy($im);
?>


楕円を描画する

  • ≪ imagedestroy
  • imagefill ≫
  • PHP Manual
  • GD および Image 関数
  • 楕円を描画する

imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — 楕円を描画する

説明

imageellipse(
GdImage $image,
int $center_x,
int $center_y,
int $width,
int $height,
int $color
): bool

指定した座標を中心とする楕円を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

center_x

中心の x 座標。

center_y

中心の y 座標。

width

楕円の幅。

height

楕円の高さ。

color

楕円の色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imageellipse() の例

<?php

// 空の画像を生成します
$image = imagecreatetruecolor(400, 300);

// 背景色を選択します
$bg = imagecolorallocate($image, 0, 0, 0);

// 上で選択した色で背景を塗ります
imagefill($image, 0, 0, $bg);

// 楕円の色を選択します
$col_ellipse = imagecolorallocate($image, 255, 255, 255);

// 楕円を描画します
imageellipse($image, 200, 150, 300, 200, $col_ellipse);

// 画像を出力します
header("Content-type: image/png");
imagepng($image);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imageellipse()

注意

注意:

imageellipse() は imagesetthickness() を無視します。

参考

  • imagefilledellipse() - 塗りつぶされた楕円を描画する
  • imagearc() - 部分楕円を描画する


塗り潰す

  • ≪ imageellipse
  • imagefilledarc ≫
  • PHP Manual
  • GD および Image 関数
  • 塗り潰す

imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — 塗り潰す

説明

imagefill(
GdImage $image,
int $x,
int $y,
int $color
): bool

指定した座標 (左上が 0, 0 です) から、指定した色 color で image を塗りつぶします。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x

開始位置の x 座標。

y

開始位置の y 座標。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagefill() の例

<?php

$im = imagecreatetruecolor(100, 100);

// 背景色を赤に設定します
$red = imagecolorallocate($im, 255, 0, 0);
imagefill($im, 0, 0, $red);

header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefill()

参考

  • imagecolorallocate() - 画像で使用する色を作成する


楕円弧を描画し、塗りつぶす

  • ≪ imagefill
  • imagefilledellipse ≫
  • PHP Manual
  • GD および Image 関数
  • 楕円弧を描画し、塗りつぶす

imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — 楕円弧を描画し、塗りつぶす

説明

imagefilledarc(
GdImage $image,
int $center_x,
int $center_y,
int $width,
int $height,
int $start_angle,
int $end_angle,
int $color,
int $style
): bool

指定した image の指定した座標を中心とする、 楕円弧を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

center_x

中心の x 座標。

center_y

中心の y 座標。

width

弧の幅。

height

弧の高さ。

start_angle

弧の開始角度。

end_angle

弧の終了角度。 0° は三時の方向で、そこから時計回りに数えます。

color

imagecolorallocate() で作成された色識別子。

style

次の選択肢のビット和。

  1. IMG_ARC_PIE
  2. IMG_ARC_CHORD
  3. IMG_ARC_NOFILL
  4. IMG_ARC_EDGED
IMG_ARC_PIE および IMG_ARC_CHORD は相反します。 IMG_ARC_CHORD は、 開始角と終了角を直線で結ぶだけですが、IMG_ARC_PIE は、角を丸めます。IMG_ARC_NOFILL は、弧と弦が縁どられ塗りつぶされないことを指定します。 IMG_ARC_EDGED は、 IMG_ARC_NOFILL と共に指定することにより、 開始角と終端角は中心と結ばれます。これは、(塗りつぶすよりも) 「パイの切れ端」を縁どる良い方法です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 3D 風のパイを作成する

<?php

// 画像を作成します
$image = imagecreatetruecolor(100, 100);

// 色を割り当てます
$white = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
$gray = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
$darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
$navy = imagecolorallocate($image, 0x00, 0x00, 0x80);
$darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
$red = imagecolorallocate($image, 0xFF, 0x00, 0x00);
$darkred = imagecolorallocate($image, 0x90, 0x00, 0x00);

// 3D 効果を作成します
for ($i = 60; $i > 50; $i--) {
imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
}

imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

// 画像を出力します
header('Content-type: image/png');
imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 3D 風のパイを作成する


塗りつぶされた楕円を描画する

  • ≪ imagefilledarc
  • imagefilledpolygon ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶされた楕円を描画する

imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — 塗りつぶされた楕円を描画する

説明

imagefilledellipse(
GdImage $image,
int $center_x,
int $center_y,
int $width,
int $height,
int $color
): bool

指定した image の指定した座標を中心として楕円を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

center_x

中心の x 座標。

center_y

中心の y 座標。

width

楕円の幅。

height

楕円の高さ。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagefilledellipse() の例

<?php

// 空の画像を作成します
$image = imagecreatetruecolor(400, 300);

// 背景色を塗ります
$bg = imagecolorallocate($image, 0, 0, 0);

// 楕円の色を選択します
$col_ellipse = imagecolorallocate($image, 255, 255, 255);

// 白い楕円を描画します
imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

// 画像を出力します
header("Content-type: image/png");
imagepng($image);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilledellipse()

注意

注意:

imagefilledellipse() は imagesetthickness() を無視します。

参考

  • imageellipse() - 楕円を描画する
  • imagefilledarc() - 楕円弧を描画し、塗りつぶす


塗りつぶした多角形を描画する

  • ≪ imagefilledellipse
  • imagefilledrectangle ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶした多角形を描画する

imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — 塗りつぶした多角形を描画する

説明

PHP 8.0.0 以降のシグネチャ(名前付き引数をサポートしていません)

imagefilledpolygon(GdImage $image, array $points, int $color): bool

代替のシグネチャ (PHP 8.1.0 以降 は非推奨)

imagefilledpolygon(
GdImage $image,
array $points,
int $num_points,
int $color
): bool

imagefilledpolygon() は画像 image 上に塗りつぶした多角形を生成します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

points

多角形の頂点の座標 x および y を含む配列。

num_points

頂点の総数。 3 以上である必要があります。

代替のシグネチャ(PHP 8.0.0 以降) でこの引数が省略された場合、 points は偶数でなければいけません。また、 num_points は count($points)/2 であると仮定されます。
color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 num_points は、推奨されなくなりました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagefilledpolygon() の例

<?php
// 多角形の点の配列を準備します
$values = array(
40, 50, // Point 1 (x, y)
20, 240, // Point 2 (x, y)
60, 60, // Point 3 (x, y)
240, 20, // Point 4 (x, y)
50, 40, // Point 5 (x, y)
10, 10 // Point 6 (x, y)
);

// 画像を生成します
$image = imagecreatetruecolor(250, 250);

// 色を割り当てます
$bg = imagecolorallocate($image, 0, 0, 0);
$blue = imagecolorallocate($image, 0, 0, 255);

// 背景を塗りつぶします
imagefilledrectangle($image, 0, 0, 249, 249, $bg);

// 多角形を描画します
imagefilledpolygon($image, $values, 6, $blue);

// 画像を出力します
header('Content-type: image/png');
imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilledpolygon()

参考

  • imagepolygon() - 多角形を描画する


塗りつぶした矩形を描画する

  • ≪ imagefilledpolygon
  • imagefilltoborder ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶした矩形を描画する

imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — 塗りつぶした矩形を描画する

説明

imagefilledrectangle(
GdImage $image,
int $x1,
int $y1,
int $x2,
int $y2,
int $color
): bool

色 color で塗りつぶした矩形を、 指定した image 上に作成します。 開始位置と終了位置を指定します。0, 0 が画像の左上角を表します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x1

開始位置の x 座標。

y1

開始位置の y 座標。

x2

終了位置の x 座標。

y2

終了位置の y 座標。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagefilledrectangle() の例

<?php
// 55x30 の画像を作成します
$im = imagecreatetruecolor(55, 30);
$white = imagecolorallocate($im, 255, 255, 255);

// 白の矩形を描画します
imagefilledrectangle($im, 4, 4, 50, 25, $white);

// 画像を保存します
imagepng($im, './imagefilledrectangle.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilledrectangle()


特定色で塗りつぶす

  • ≪ imagefilledrectangle
  • imagefilter ≫
  • PHP Manual
  • GD および Image 関数
  • 特定色で塗りつぶす

imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — 特定色で塗りつぶす

説明

imagefilltoborder(
GdImage $image,
int $x,
int $y,
int $border_color,
int $color
): bool

imagefilltoborder()は、 border_colorで指定した色を境界色として塗りつぶし を行います。(x,y)が 塗りつぶしの始点(左上が0, 0)で、領域内を color色で塗りつぶします。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x

開始位置の x 座標。

y

開始位置の y 座標。

border_color

境界色。imagecolorallocate() で作成された色識別子。

color

塗りつぶし色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 楕円の塗りつぶし

<?php
// 画像ハンドルを作成し、背景を白に設定します
$im = imagecreatetruecolor(100, 100);
imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

// 黒い線で楕円を描画します
imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

// 枠線と塗りつぶしの色を設定します
$border = imagecolorallocate($im, 0, 0, 0);
$fill = imagecolorallocate($im, 255, 0, 0);

// 選択した部分を塗りつぶします
imagefilltoborder($im, 50, 50, $border, $fill);

// 出力し、メモリを開放します
header('Content-type: image/png');
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 楕円の塗りつぶし

注意

塗りつぶしのアルゴリズムは、 どのピクセルが既に設定されているかについて明示的に記憶しません。 むしろピクセルの色からそれを推測しようとします。 よって、そのピクセルが既に存在していたものか、 新たに設定されたものなのかは区別できません。 これは、画像で既に使われている色で画像を塗りつぶそうとすると、 望ましくない結果が得られることがあるということです。


画像にフィルタを適用する

  • ≪ imagefilltoborder
  • imageflip ≫
  • PHP Manual
  • GD および Image 関数
  • 画像にフィルタを適用する

imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — 画像にフィルタを適用する

説明

imagefilter(GdImage $image, int $filter, array|int|float|bool ...$args): bool

imagefilter() は、指定したフィルタ filter を image に適用します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

filter

filter は、以下のいずれかです。

  • IMG_FILTER_NEGATE: 画像の色を反転させます。
  • IMG_FILTER_GRAYSCALE: REC.601 luma (Y') の計算と同じ係数を使い、 重み付けを赤、緑、青のコンポーネントごとに変えることで、 画像を白黒にします。アルファ値は保持されます。 パレットの制限のため、パレット画像の結果は異なるかもしれません。
  • IMG_FILTER_BRIGHTNESS: 画像の輝度を変更します。 輝度レベルを args で設定します。輝度の範囲は -255 から 255 までです。
  • IMG_FILTER_CONTRAST: 画像のコントラストを 変更します。コントラストのレベルを args で設定します。
  • IMG_FILTER_COLORIZE: IMG_FILTER_GRAYSCALE と似ていますが、 色を指定することが可能です。 args、arg2 および arg3 を使用して red、green、 blue の値を指定します。また arg4 を使用して alpha チャネルの値を指定します。 各値の範囲は 0 から 255 までです。
  • IMG_FILTER_EDGEDETECT: エッジを検出し、 画像のエッジを強調します。
  • IMG_FILTER_EMBOSS: 画像にエンボス処理を行います。
  • IMG_FILTER_GAUSSIAN_BLUR: ガウス分布を 使用して画像をぼかします。
  • IMG_FILTER_SELECTIVE_BLUR: 画像をぼかします。
  • IMG_FILTER_MEAN_REMOVAL: 平均を除去し、 「スケッチ風の」効果を得ます。
  • IMG_FILTER_SMOOTH: 画像を滑らかにします。 滑らかさのレベルを args で指定します。
  • IMG_FILTER_PIXELATE: モザイク効果を画像に適用します。 args でブロックの大きさを、 そして arg2 でモザイク効果のモードを指定します。
  • IMG_FILTER_SCATTER: Scatter 効果を 画像に適用します。args と arg2 を効果の強さを定義するのに使い、 選んだピクセルの色にだけ適用するために 追加で arg3 を使います。

args

  • IMG_FILTER_BRIGHTNESS: 輝度レベル。
  • IMG_FILTER_CONTRAST: コントラストレベル。
  • IMG_FILTER_COLORIZE: 赤コンポーネントの値。
  • IMG_FILTER_SMOOTH: 平滑度レベル。
  • IMG_FILTER_PIXELATE: ピクセル単位のブロックサイズ。
  • IMG_FILTER_SCATTER: 効果を減らすレベル。 この値は、 arg2 で設定する追加レベル以上でなければなりません。

arg2

  • IMG_FILTER_COLORIZE: 緑コンポーネントの値。
  • IMG_FILTER_PIXELATE: 高度なモザイク効果を使用するか否か (デフォルトは false)。
  • IMG_FILTER_SCATTER: 効果の追加レベル

arg3

  • IMG_FILTER_COLORIZE: 青コンポーネントの値。
  • IMG_FILTER_SCATTER: オプション。 効果を適用するインデックスカラーの値の配列。

arg4

  • IMG_FILTER_COLORIZE: アルファチャネル。 0 から 127 までの値で、0 は完全な不透明、127 は完全な透明を表す。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
7.4.0 | Scatter 効果のサポート (IMG_FILTER_SCATTER) が追加されました。

例

例1 imagefilter() グレースケールの例

<?php
$im = imagecreatefrompng('dave.png');

if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
{
echo 'Image converted to grayscale.';

imagepng($im, 'dave.png');
}
else
{
echo 'Conversion to grayscale failed.';
}

imagedestroy($im);
?>

例2 imagefilter() 輝度の例

<?php
$im = imagecreatefrompng('sean.png');

if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
{
echo 'Image brightness changed.';

imagepng($im, 'sean.png');
imagedestroy($im);
}
else
{
echo 'Image brightness change failed.';
}
?>

例3 imagefilter() 単色化の例

<?php
$im = imagecreatefrompng('philip.png');

/* R, G, B, so 0, 255, 0 is green */
if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
{
echo 'Image successfully shaded green.';

imagepng($im, 'philip.png');
imagedestroy($im);
}
else
{
echo 'Green shading failed.';
}
?>

例4 imagefilter() での打ち消しの例

<?php
// Define our negate function so its portable for
// php versions without imagefilter()
function negate($im)
{
if(function_exists('imagefilter'))
{
return imagefilter($im, IMG_FILTER_NEGATE);
}

for($x = 0; $x < imagesx($im); ++$x)
{
for($y = 0; $y < imagesy($im); ++$y)
{
$index = imagecolorat($im, $x, $y);
$rgb = imagecolorsforindex($index);
$color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

imagesetpixel($im, $x, $y, $color);
}
}

return(true);
}

$im = imagecreatefromjpeg('kalle.jpg');

if($im && negate($im))
{
echo 'Image successfully converted to negative colors.';

imagejpeg($im, 'kalle.jpg', 100);
imagedestroy($im);
}
else
{
echo 'Converting to negative colors failed.';
}
?>

例5 imagefilter() でのモザイク処理の例

<?php
// Load the PHP logo, we need to create two instances
// to show the differences
$logo1 = imagecreatefrompng('./php.png');
$logo2 = imagecreatefrompng('./php.png');

// Create the image instance we want to show the
// differences on
$output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

// Apply pixelation to each instance, with a block
// size of 3
imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

// Merge the differences onto the output image
imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);
imagedestroy($logo1);
imagedestroy($logo2);

// Output the differences
header('Content-Type: image/png');
imagepng($output);
imagedestroy($output);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilter() でのモザイク処理

例6 imagefilter() でのScatter効果の例

<?php
// Load the image
$logo = imagecreatefrompng('./php.png');

// Apply a very soft scatter effect to the image
imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

// Output the image with the scatter effect
header('Content-Type: image/png');
imagepng($logo);
imagedestroy($logo);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagefilter() scatter

注意

注意: IMG_FILTER_SCATTER の適用結果は常にランダムです。

参考

  • imageconvolution() - div および offset の係数を使用し、3x3 の畳み込み配列を適用する


指定したモードで画像を反転させる

  • ≪ imagefilter
  • imagefontheight ≫
  • PHP Manual
  • GD および Image 関数
  • 指定したモードで画像を反転させる

imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — 指定したモードで画像を反転させる

説明

imageflip(GdImage $image, int $mode): bool

image を、指定した mode で反転させます。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

mode

反転のモード。定数 IMG_FLIP_* のいずれかを指定します。

定数 | 意味
IMG_FLIP_HORIZONTAL | 水平方向に、左右を反転させます。
IMG_FLIP_VERTICAL | 垂直方向に、上下を反転させます。
IMG_FLIP_BOTH | 水平方向、垂直方向の両方に反転させます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 垂直方向の反転

この例では、定数 IMG_FLIP_VERTICAL を使います。

<?php
// 画像ファイル
$filename = 'phplogo.png';

// コンテントタイプ
header('Content-type: image/png');

// 読み込み
$im = imagecreatefrompng($filename);

// 垂直反転
imageflip($im, IMG_FLIP_VERTICAL);

// 出力
imagejpeg($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

例2 水平方向の反転

この例では、定数 IMG_FLIP_HORIZONTAL を使います。

<?php
// 画像ファイル
$filename = 'phplogo.png';

// コンテントタイプ
header('Content-type: image/png');

// 読み込み
$im = imagecreatefrompng($filename);

// 水平反転
imageflip($im, IMG_FLIP_HORIZONTAL);

// 出力
imagejpeg($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。


フォントの高さを取得する

  • ≪ imageflip
  • imagefontwidth ≫
  • PHP Manual
  • GD および Image 関数
  • フォントの高さを取得する

imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — フォントの高さを取得する

説明

imagefontheight(GdFont|int $font): int

指定されたフォントの文字の高さをピクセル単位で返します。

パラメータ

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。

戻り値

フォントの高さをピクセルで返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 font は、GdFont クラスのインスタンスと数値を両方受け入れるようになりました。これより前のバージョンでは、数値のみを受け入れていました。

例

例1 組み込みフォントでの imagefontheight() の使用法

<?php
echo 'フォントの高さ: ' . imagefontheight(4);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの高さ: 16

例2 imagefontheight() と imageloadfont() を組み合わせた使用法

<?php
// .gdf フォントを読み込みます
$font = imageloadfont('anonymous.gdf');

echo 'フォントの高さ: ' . imagefontheight($font);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの高さ: 43

参考

  • imagefontwidth() - フォントの幅を取得する
  • imageloadfont() - 新しいフォントを読み込む


フォントの幅を取得する

  • ≪ imagefontheight
  • imageftbbox ≫
  • PHP Manual
  • GD および Image 関数
  • フォントの幅を取得する

imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — フォントの幅を取得する

説明

imagefontwidth(GdFont|int $font): int

指定されたフォントの文字の幅をピクセル単位で返します。

パラメータ

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。

戻り値

フォントの幅をピクセルで返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 font は、GdFont クラスのインスタンスと数値を両方受け入れるようになりました。これより前のバージョンでは、数値のみを受け入れていました。

例

例1 組み込みフォントでの imagefontwidth() の使用法

<?php
echo 'フォントの幅: ' . imagefontwidth(4);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの幅: 8

例2 imagefontwidth() と imageloadfont() を組み合わせた使用法

<?php
// .gdf フォントを読み込みます
$font = imageloadfont('anonymous.gdf');

echo 'フォントの幅: ' . imagefontwidth($font);
?>

上の例の出力は、 たとえば以下のようになります。

フォントの幅: 23

参考

  • imagefontheight() - フォントの高さを取得する
  • imageloadfont() - 新しいフォントを読み込む


freetype2 によるフォントを用いたテキストを囲む箱を取得する

  • ≪ imagefontwidth
  • imagefttext ≫
  • PHP Manual
  • GD および Image 関数
  • freetype2 によるフォントを用いたテキストを囲む箱を取得する

imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — freetype2 によるフォントを用いたテキストを囲む箱を取得する

説明

imageftbbox(
float $size,
float $angle,
string $font_filename,
string $string,
array $options = []
): array|false

この関数は FreeType テキスト用のバウンディングボックスをピクセル単位で算出し、 それを返します。

注意:

PHP 8.0.0 より前のバージョンでは、 imageftbbox() は、 imagettfbbox() を拡張したものでした。 追加で options をサポートしていました。 PHP 8.0.0 以降では、 imagettfbbox() は imageftbbox() のエイリアスになっています。

パラメータ

size

ポイント数単位のフォントサイズ。

angle

string を取得する角度。

font_filename

TrueType フォントのファイル名 (URL も可)。 PHP が使用している GD ライブラリのバージョンにも依存しますが、 先頭に '/' がついていないファイル名を渡した場合は ファイル名の末尾に '.ttf' を追加して GD のフォントパスからファイルを探そうとすることもあります。

string

取得したい文字列。

options

options の配列のインデックス
キー | 型 | 意味
linespacing | float | 描画時の行間を定義します

戻り値

imageftbbox() は 8 つの要素からなる配列を返します。 これが、テキストを囲む箱の 4 つの角の座標を表します。

0 | 左下角の X 座標
1 | 左下角の Y 座標
2 | 右下角の X 座標
3 | 右下角の Y 座標
4 | 右上角の X 座標
5 | 右上角の Y 座標
6 | 左上角の X 座標
7 | 左上角の Y 座標

これらの点は、angle の値にかかわらず text からの相対位置になります。 つまり「左上」とは、そのテキストが水平になるように見たときの左上ということです。

失敗した場合には、false を返します。

例

例1 imageftbbox() の例

<?php
// 300x150 の画像を作成します
$im = imagecreatetruecolor(300, 150);
$black = imagecolorallocate($im, 0, 0, 0);
$white = imagecolorallocate($im, 255, 255, 255);

// 背景色を白に設定します
imagefilledrectangle($im, 0, 0, 299, 299, $white);

// フォントファイルへのパス
$font = './arial.ttf';

// まずバウンディングボックスを作成します
$bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

// X 座標および Y 座標
$x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
$y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

imagefttext($im, 10, 0, $x, $y, $black, $font, 'The PHP Documentation Group');

// ブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imagefttext() - FreeType 2 によるフォントを用いてイメージにテキストを描画する
  • imagettfbbox() - TypeType フォントを使用したテキストの bounding box を生成する


FreeType 2 によるフォントを用いてイメージにテキストを描画する

  • ≪ imageftbbox
  • imagegammacorrect ≫
  • PHP Manual
  • GD および Image 関数
  • FreeType 2 によるフォントを用いてイメージにテキストを描画する

imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — FreeType 2 によるフォントを用いてイメージにテキストを描画する

説明

imagefttext(
GdImage $image,
float $size,
float $angle,
int $x,
int $y,
int $color,
string $font_filename,
string $text,
array $options = []
): array|false

注意:

PHP 8.0.0 より前のバージョンでは、 imagefttext() は、 imagettftext() を拡張したものでした。 options を追加でサポートしていました。 PHP 8.0.0 以降では、 imagettftext() は imagefttext() のエイリアスになっています。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

size

使用するフォントのサイズ (ポイント数)。

angle

角度 (度数)。0 度は、左から右に読むテキストを表します。 度数を上げていくと、反時計回りに回転します。たとえば、 90 度の場合は下から上に読むテキストとなります。

x

x と y で表す座標が、最初の文字のベースポイント (その文字の左下の角とほぼ等しい点) となります。 imagestring() の場合は x と y で最初の文字の左上の角を指定しており、 たとえば "左上" は 0, 0 となりますが、この関数では異なります。

y

y 座標。これはフォントのベースラインを指定するものであり、 文字の最下端を指定するものではありません。

color

テキストに使用する色のインデックス。 imagecolorexact() を参照ください。

font_filename

使用する TrueType フォントへのパス。

PHP が使用している GD ライブラリのバージョンにも依存しますが、 font_filename の先頭に / がついていない場合はファイル名の末尾に .ttf を追加して GD のフォントパスからファイルを探そうとすることもあります。

たいていの場合は、スクリプト内で使うフォントの場所は同じディレクトリになるでしょう。 そんな場合は、次のようにすれば読み込み時の問題を回避できます。

<?php
// GD 用の環境変数を設定します
putenv('GDFONTPATH=' . realpath('.'));

// 使用するフォント名を指定します (拡張子 .ttf がないことに注目しましょう)
$font = 'SomeFont';
?>

text

画像に挿入するテキスト。

options

options の配列のインデックス
キー | 型 | 意味
linespacing | float | 描画時の行間を定義します

戻り値

この関数は、長方形の 4 つの角を表す点の配列を返します。 最初が左下の位置で、そこから反時計回りに回ります。

0 | 左下の x 座標
1 | 左下の y 座標
2 | 右下の x 座標
3 | 右下の y 座標
4 | 右上の x 座標
5 | 右上の y 座標
6 | 左上の x 座標
7 | 左上の y 座標

失敗時には、false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagefttext() の例

<?php
// 300x100 の画像を作成します
$im = imagecreatetruecolor(300, 100);
$red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
$black = imagecolorallocate($im, 0x00, 0x00, 0x00);

// 背景を赤にします
imagefilledrectangle($im, 0, 0, 299, 99, $red);

// ttf フォントファイルへのパスを設定します
$font_file = './arial.ttf';

// フォントサイズ 13 で 'PHP Manual' というテキストを描画します
imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imageftbbox() - freetype2 によるフォントを用いたテキストを囲む箱を取得する
  • imagettftext() - TrueType フォントを使用してテキストを画像に書き込む


GD イメージにガンマ補正を適用する

  • ≪ imagefttext
  • imagegd ≫
  • PHP Manual
  • GD および Image 関数
  • GD イメージにガンマ補正を適用する

imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — GD イメージにガンマ補正を適用する

説明

imagegammacorrect(GdImage $image, float $input_gamma, float $output_gamma): bool

指定した GD 画像 image に 入力ガンマ値、出力ガンマ値を指定してガンマ補正を適用します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

input_gamma

入力ガンマ値。

output_gamma

出力ガンマ値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagegammacorrect() の使用法

<?php
// 画像のインスタンスを作成します
$im = imagecreatefromgif('php.gif');

// ガンマ補正を out = 1.537 で行います
imagegammacorrect($im, 1.0, 1.537);

// 出力してメモリから解放します
imagegif($im, './php_gamma_corrected.gif');
imagedestroy($im);
?>


GD イメージをブラウザまたはファイルに出力する

  • ≪ imagegammacorrect
  • imagegd2 ≫
  • PHP Manual
  • GD および Image 関数
  • GD イメージをブラウザまたはファイルに出力する

imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — GD イメージをブラウザまたはファイルに出力する

説明

imagegd(GdImage $image, ?string $file = null): bool

GD イメージを、指定した file に出力します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.3 | file は、nullable になりました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
7.2.0 | imagegd() が truecolor 画像を出力できるようになりました。 これまでのバージョンでは、暗黙のうちにパレット画像に変換されていました。

例

例1 GD 画像の出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, "A Simple Text String", $text_color);

// 画像を出力します
imagegd($im);

// メモリを開放します
imagedestroy($im);
?>

例2 GD 画像の保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, "A Simple Text String", $text_color);

// GD 画像を保存します
// GD 画像のファイル形式は .gd です。 http://www.libgd.org/GdFileFormats を参照ください
imagegd($im, 'simple.gd');

// メモリを開放します
imagedestroy($im);
?>

注意

注意:

通常 GD フォーマットはイメージの一部を高速にロードするために 使用されます。GD フォーマットは GD 互換アプリケーションでのみ使用可能であることに注意してください。

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

参考

  • imagegd2() - GD2 イメージをブラウザまたはファイルに出力する


GD2 イメージをブラウザまたはファイルに出力する

  • ≪ imagegd
  • imagegetclip ≫
  • PHP Manual
  • GD および Image 関数
  • GD2 イメージをブラウザまたはファイルに出力する

imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — GD2 イメージをブラウザまたはファイルに出力する

説明

imagegd2(
GdImage $image,
?string $file = null,
int $chunk_size = 128,
int $mode = IMG_GD2_RAW
): bool

GD2 イメージを、指定した file に出力します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

chunk_size

チャンクの大きさ。

mode

IMG_GD2_RAW あるいは IMG_GD2_COMPRESSED のいずれかです。デフォルトは IMG_GD2_RAW です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.3 | file は、nullable になりました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 GD2 画像の出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, "A Simple Text String", $text_color);

// 画像を出力します
imagegd2($im);

// メモリを開放します
imagedestroy($im);
?>

例2 GD2 画像の保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, "A Simple Text String", $text_color);

// GD2 画像を保存します
// GD2 画像のファイル形式は .gd2 です。 http://www.libgd.org/GdFileFormats を参照ください
imagegd2($im, 'simple.gd2');

// メモリを開放します
imagedestroy($im);
?>

注意

注意:

通常 GD2 フォーマットはイメージの一部を高速にロードするために 使用されます。GD2 フォーマットは GD2 互換アプリケーションでのみ使用可能であることに注意してください。

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

参考

  • imagegd() - GD イメージをブラウザまたはファイルに出力する


長方形を切り取り、画像として取得する

  • ≪ imagegd2
  • imagegetinterpolation ≫
  • PHP Manual
  • GD および Image 関数
  • 長方形を切り取り、画像として取得する

imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — 長方形を切り取り、画像として取得する

説明

imagegetclip(GdImage $image): array

imagegetclip() 関数は、現在切り取っている長方形を取得します。 つまり、ピクセルが存在しない状態でなければ描画されます。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

この関数は、切り取っている長方形の座標を配列で返し、 次のエントリを持ちます:

  • 左上のx座標
  • 左上のx座標
  • 右下のx座標
  • 右下のy座標

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagegetclip() の例

切り取る範囲を設定し、長方形のクリップを取得します。

<?php
$im = imagecreate(100, 100);
imagesetclip($im, 10,10, 89,89);
print_r(imagegetclip($im));

上の例の出力は以下となります。

Array
(
    [0] => 10
    [1] => 10
    [2] => 89
    [3] => 89
)

参考

  • imagesetclip() - 切り取る長方形を設定する


補間方法を取得する

  • ≪ imagegetclip
  • imagegif ≫
  • PHP Manual
  • GD および Image 関数
  • 補間方法を取得する

imagegetinterpolation

(PHP 8)

imagegetinterpolation — 補間方法を取得する

説明

imagegetinterpolation(GdImage $image): int

image に現在設定されている補間方法を取得します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

補間方法を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

参考

  • imagesetinterpolation() - 補間方法を設定する


画像をブラウザあるいはファイルに出力する

  • ≪ imagegetinterpolation
  • imagegrabscreen ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — 画像をブラウザあるいはファイルに出力する

説明

imagegif(GdImage $image, resource|string|null $file = null): bool

imagegif() は画像 image から file に GIF ファイルを作成します。 引数 image は imagecreate() あるいは imagecreatefrom* 関数から返されたものです。

画像フォーマットは、imagecolortransparent() を 用いて画像を透明化しない限り GIF87a となります。 透明化した場合の画像フォーマットは GIF89a となります。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagegif() による画像の出力

<?php
// 新しい画像のインスタンスを作成します
$im = imagecreatetruecolor(100, 100);

// 背景を白にします
imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

// テキスト文字列を画像の上に描画します
imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

// 画像をブラウザに出力します
header('Content-Type: image/gif');

imagegif($im);
imagedestroy($im);
?>

例2 imagegif() による PNG 画像から GIF への変換

<?php

// PNG を読み込みます
$png = imagecreatefrompng('./php.png');

// 画像を GIF 形式で保存します
imagegif($png, './php.gif');

// メモリから開放します
imagedestroy($png);

// 終了です
echo 'Converted PNG image to GIF with success!';
?>

注意

注意:

以下の短いコードにより、利用可能な GD サポートの型を自動検出して 汎用性のある PHP アプリケーションを書くことが可能です。 header ("Content-Type: image/gif"); imagegif ($im); の部分を、より柔軟性のある このコードに置換してください。

<?php
// Create a new image instance
$im = imagecreatetruecolor(100, 100);

// Do some image operations here

// Handle output
if(function_exists('imagegif'))
{
// For GIF
header('Content-Type: image/gif');

imagegif($im);
}
elseif(function_exists('imagejpeg'))
{
// For JPEG
header('Content-Type: image/jpeg');

imagejpeg($im, NULL, 100);
}
elseif(function_exists('imagepng'))
{
// For PNG
header('Content-Type: image/png');

imagepng($im);
}
elseif(function_exists('imagewbmp'))
{
// For WBMP
header('Content-Type: image/vnd.wap.wbmp');

imagewbmp($im);
}
else
{
imagedestroy($im);

die('No image support in this PHP server');
}

// If image support was found for one of these
// formats, then free it from memory
if($im)
{
imagedestroy($im);
}
?>

注意:

種々のイメージ関数のサポートを調べるために 関数 imagetypes() を使用することが可能です。

<?php
if(imagetypes() & IMG_GIF)
{
header('Content-type: image/gif');
imagegif($im);
}
elseif(imagetypes() & IMG_JPG)
{
/* ... etc. */
}
?>

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す


画面全体をキャプチャする

  • ≪ imagegif
  • imagegrabwindow ≫
  • PHP Manual
  • GD および Image 関数
  • 画面全体をキャプチャする

imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — 画面全体をキャプチャする

説明

imagegrabscreen(): GdImage|false

画面全体のスクリーンショットを取得します。

注意:

この関数は Windows 上でのみ使用できます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に画像オブジェクト、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

例

例1 imagegrabscreen() の例

この例は、現在の画面の状態のスクリーンショットを取得してそれを png 画像として保存するものです。

<?php
$im = imagegrabscreen();
imagepng($im, "myscreenshot.png");
imagedestroy($im);
?>

参考

  • imagegrabwindow() - ウィンドウをキャプチャする


ウィンドウをキャプチャする

  • ≪ imagegrabscreen
  • imageinterlace ≫
  • PHP Manual
  • GD および Image 関数
  • ウィンドウをキャプチャする

imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — ウィンドウをキャプチャする

説明

imagegrabwindow(int $handle, bool $client_area = false): GdImage|false

ウィンドウあるいはそのクライアント領域のキャプチャを、 ウィンドウハンドル (COM インスタンスの HWND プロパティ) を指定して取得します。

注意:

この関数は Windows 上でのみ使用できます。

パラメータ

handle

HWND ウィンドウ ID。

client_area

アプリケーションのクライアント領域を含めるかどうか。

戻り値

成功した場合に画像オブジェクト、失敗した場合に false を返します。

エラー / 例外

handle が無効なウィンドウハンドルである場合に E_NOTICE、 Windows API のバージョンが古すぎる場合に E_WARNING が発生します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
8.0.0 | client_area は、 bool を期待するようになりました。 これより前のバージョンでは、数値型を期待していました。

例

例1 imagegrabwindow() の例

ウィンドウ (ここでは IE) のキャプチャを行います。

<?php
$browser = new COM("InternetExplorer.Application");
$handle = $browser->HWND;
$browser->Visible = true;
$im = imagegrabwindow($handle);
$browser->Quit();
imagepng($im, "iesnap.png");
imagedestroy($im);
?>

ウィンドウ (ここでは IE) の中身のキャプチャを行います。

<?php
$browser = new COM("InternetExplorer.Application");
$handle = $browser->HWND;
$browser->Visible = true;
$browser->Navigate("http://www.libgd.org");

/* まだ動作するか？ */
while ($browser->Busy) {
com_message_pump(4000);
}
$im = imagegrabwindow($handle, 0);
$browser->Quit();
imagepng($im, "iesnap.png");
imagedestroy($im);
?>

参考

  • imagegrabscreen() - 画面全体をキャプチャする


インターレースを有効もしくは無効にする

  • ≪ imagegrabwindow
  • imageistruecolor ≫
  • PHP Manual
  • GD および Image 関数
  • インターレースを有効もしくは無効にする

imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — インターレースを有効もしくは無効にする

説明

imageinterlace(GdImage $image, ?bool $enable = null): bool

imageinterlace() は、インターレースビットをon またはoffに切り替えます。

インターレースビットがonでかつその画像が JPEG の場合、 その画像はプログレッシブ JPEG として生成されています。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

interlace

true の場合はインターレース画像となり、 false の場合はインターレースビットを off にします。 null を渡すと、インターレースに関する振る舞いは変更されません。

戻り値

画像のインターレースビットが設定されている場合に true 、 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.5 | imageinterlace() は、 bool を返すようになりました。 これより前のバージョンでは、int を返していました。 (インターレース画像の場合は 0 でない値を、 そうでない場合は 0 を返していました)
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | enable は、 bool の値を期待するようになりました。 これより前のバージョンでは、数値型を期待していました。

例

例1 imageinterlace() によるインターレース処理の有効化

<?php
// 画像のインスタンスを作成します
$im = imagecreatefromgif('php.gif');

// インターレースを有効にします
imageinterlace($im, true);

// 画像を保存します
imagegif($im, './php_interlaced.gif');
imagedestroy($im);
?>


画像が truecolor かどうか調べる

  • ≪ imageinterlace
  • imagejpeg ≫
  • PHP Manual
  • GD および Image 関数
  • 画像が truecolor かどうか調べる

imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — 画像が truecolor かどうか調べる

説明

imageistruecolor(GdImage $image): bool

imageistruecolor() は、 image が truecolor 画像かどうか調べます。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

image が truecolor の場合に true、 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imageistruecolor() による、シンプルな true color 画像の検出

<?php
// $im は画像のインスタンスです

// それが true color 画像か否かを調べます
if(!imageistruecolor($im))
{
// 新しい true color 画像のインスタンスを作成します
$tc = imagecreatetruecolor(imagesx($im), imagesy($im));

// ピクセルをコピーします
imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));
imagedestroy($im);

$im = $tc;
$tc = NULL;

// あるいは imagepalettetotruecolor() を使います
}

// 画像のインスタンスに対する操作を続けます
?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imagepalettetotruecolor() - パレット形式の画像を true color に変換する


画像をブラウザあるいはファイルに出力する

  • ≪ imageistruecolor
  • imagelayereffect ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — 画像をブラウザあるいはファイルに出力する

説明

imagejpeg(GdImage $image, resource|string|null $file = null, int $quality = -1): bool

imagejpeg() は、画像 image から JPEG ファイルを作成します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

quality

quality はオプションであり、0(品質は最低 ですが、ファイルはより小さい)から100(品質は最高ですが、ファイルは 最大)の範囲で指定します。 デフォルト (-1) は、IJG 品質値(75) を使います。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 JPEG 画像のブラウザへの出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// content type ヘッダを、ここでは image/jpeg と設定します
header('Content-Type: image/jpeg');

// 画像を出力します
imagejpeg($im);

// メモリを開放します
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : JPEG 画像の出力

例2 JPEG 画像のファイルへの保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// 画像を 'simpletext.jpg' として保存します
imagejpeg($im, 'simpletext.jpg');

// メモリを開放します
imagedestroy($im);
?>

例3 75% 品質でのブラウザへの画像の出力

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// content type ヘッダを、ここでは image/jpeg と設定します
header('Content-Type: image/jpeg');

// file パラメータを NULL でスキップし、品質を 75% に設定します
imagejpeg($im, NULL, 75);

// メモリを開放します
imagedestroy($im);
?>

注意

注意:

プログレッシブ JPEG を出力したい場合には、 imageinterlace() でインターレースをセットする必要があります。

参考

  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imageinterlace() - インターレースを有効もしくは無効にする
  • imagetypes() - この PHP がサポートしている画像形式を返す


アルファブレンディングフラグを設定し、レイヤ効果を使用する

  • ≪ imagejpeg
  • imageline ≫
  • PHP Manual
  • GD および Image 関数
  • アルファブレンディングフラグを設定し、レイヤ効果を使用する

imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する

説明

imagelayereffect(GdImage $image, int $effect): bool

アルファブレンディングフラグを設定し、レイヤ効果を使用します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

effect

以下の定数のいずれか。

IMG_EFFECT_REPLACE
ピクセルの置換を使用します (imagealphablending() に true を渡すのと同じです)。
IMG_EFFECT_ALPHABLEND
通常のピクセルブレンディングを使用します (imagealphablending() に false を渡すのと同じです)。
IMG_EFFECT_NORMAL
IMG_EFFECT_ALPHABLEND と同じです。
IMG_EFFECT_OVERLAY
オーバーレイを使用すると、背景の黒い部分は黒のまま。 一方背景の白い部分は白のままとなります。 背景のグレーな部分は、前景のピクセルの色となります。
IMG_EFFECT_MULTIPLY
多重効果を使ったオーバーレイを使用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
7.2.0 | IMG_EFFECT_MULTIPLY が追加されました (システムの libgd が 2.1.1 以降であるか、バンドルされている libgd を使う必要があります)。

例

例1 imagelayereffect() の例

<?php
// 画像を準備します
$im = imagecreatetruecolor(100, 100);

// 背景を設定します
imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

// オーバーレイアルファブレンディングフラグを適用します
imagelayereffect($im, IMG_EFFECT_OVERLAY);

// 2 つのグレーの楕円を描画します
imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

// 出力します
header('Content-type: image/png');

imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagelayereffect()


直線を描画する

  • ≪ imagelayereffect
  • imageloadfont ≫
  • PHP Manual
  • GD および Image 関数
  • 直線を描画する

imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — 直線を描画する

説明

imageline(
GdImage $image,
int $x1,
int $y1,
int $x2,
int $y2,
int $color
): bool

指定したふたつの点を結ぶ直線を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x1

最初の点の x 座標。

y1

最初の点の y 座標。

x2

二番目の点の x 座標。

y2

二番目の点の y 座標。

color

直線の色。imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 太い線を描画する

<?php

function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
{
/* この方法は直行する線の場合のみうまく動作します
imagesetthickness($image, $thick);
return imageline($image, $x1, $y1, $x2, $y2, $color);
*/
if ($thick == 1) {
return imageline($image, $x1, $y1, $x2, $y2, $color);
}
$t = $thick / 2 - 0.5;
if ($x1 == $x2 || $y1 == $y2) {
return imagefilledrectangle($image, round(min($x1, $x2) - $t), round(min($y1, $y2) - $t), round(max($x1, $x2) + $t), round(max($y1, $y2) + $t), $color);
}
$k = ($y2 - $y1) / ($x2 - $x1); //y = kx + q
$a = $t / sqrt(1 + pow($k, 2));
$points = array(
round($x1 - (1+$k)*$a), round($y1 + (1-$k)*$a),
round($x1 - (1-$k)*$a), round($y1 - (1+$k)*$a),
round($x2 + (1+$k)*$a), round($y2 - (1-$k)*$a),
round($x2 + (1-$k)*$a), round($y2 + (1+$k)*$a),
);
imagefilledpolygon($image, $points, 4, $color);
return imagepolygon($image, $points, 4, $color);
}

?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imagecolorallocate() - 画像で使用する色を作成する


新しいフォントを読み込む

  • ≪ imageline
  • imageopenpolygon ≫
  • PHP Manual
  • GD および Image 関数
  • 新しいフォントを読み込む

imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — 新しいフォントを読み込む

説明

imageloadfont(string $filename): GdFont|false

imageloadfont() はユーザーが定義したビットマップを読み込み、 その ID を返します。

パラメータ

filename

フォントファイル形式は現在はバイナリで、アーキクチャに依存します。 このため、PHP を実行するマシーンと同一の型の CPU 上でフォントファイルを 生成する必要があります。

フォントファイルのフォーマット
バイト位置 | C 言語のデータ型 | 説明
0-3 バイト目 | int | フォント中の文字の数
4-7 バイト目 | int | フォント中の最初の文字の値(しばしば 空白を表す 32 となります)
8-11 バイト目 | int | 各文字のピクセル幅
12-15 バイト目 | int | 各文字のピクセル高さ
16 バイト目から | char | 文字データの配列、各文字のピクセルにつき1バイトで、 総数は(文字数*幅*高さ)バイトです。

戻り値

GdFont クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | GdFont クラスのインスタンスを返すようになりました。 これより前のバージョンでは、数値を返していました。

例

例1 imageloadfont() の使用例

<?php
// 新しい画像インスタンスを作成します
$im = imagecreatetruecolor(50, 20);
$black = imagecolorallocate($im, 0, 0, 0);
$white = imagecolorallocate($im, 255, 255, 255);

// 背景を白に設定します
imagefilledrectangle($im, 0, 0, 49, 19, $white);

// gd フォントを読み込み 'Hello' を書き込みます
$font = imageloadfont('./04b.gdf');
imagestring($im, $font, 0, 0, 'Hello', $black);

// ブラウザに出力します
header('Content-type: image/png');

imagepng($im);
imagedestroy($im);
?>

参考

  • imagefontwidth() - フォントの幅を取得する
  • imagefontheight() - フォントの高さを取得する


オープンポリゴンを描画する

  • ≪ imageloadfont
  • imagepalettecopy ≫
  • PHP Manual
  • GD および Image 関数
  • オープンポリゴンを描画する

imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — オープンポリゴンを描画する

説明

PHP 8.0.0 以降のシグネチャ (名前付き引数をサポートしていません)

imageopenpolygon(GdImage $image, array $points, int $color): bool

代替のシグネチャ (PHP 8.1.0 以降は非推奨)

imageopenpolygon(
GdImage $image,
array $points,
int $num_points,
int $color
): bool

imageopenpolygon() 関数は、 与えられた image のオープンポリゴンを描画します。 imagepolygon() とは異なり、 始点と終点の間の線は描かれません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

points

ポリゴンの点を含む配列:

points[0] | = x0
points[1] | = y0
points[2] | = x1
points[3] | = y1

num_points

全ての点の数。少なくとも3以上である必要があります。

代替のシグネチャ(PHP 8.0.0 以降) でこの引数が省略された場合、 points は偶数でなければいけません。また、 num_points は count($points)/2 であると仮定されます。
color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 num_points は、推奨されなくなりました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imageopenpolygon() の例

<?php
// 空の画像を生成します。
$image = imagecreatetruecolor(400, 300);

// 色をポリゴンに割り当てます。
$col_poly = imagecolorallocate($image, 255, 255, 255);

// ポリゴンを描画します。
imageopenpolygon($image, array(
0, 0,
100, 200,
300, 200
),
3,
$col_poly);

// 画像をブラウザに出力します。
header('Content-type: image/png');

imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • imagepolygon() - 多角形を描画する


あるイメージから他のイメージにパレットをコピーする

  • ≪ imageopenpolygon
  • imagepalettetotruecolor ≫
  • PHP Manual
  • GD および Image 関数
  • あるイメージから他のイメージにパレットをコピーする

imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — あるイメージから他のイメージにパレットをコピーする

説明

imagepalettecopy(GdImage $dst, GdImage $src): void

imagepalettecopy() は、パレットを src から dst にコピーします。

パラメータ

dst

コピー先の画像オブジェクト

src

コピー元の画像オブジェクト

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | dst と src は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource を期待していました。

例

例1 imagepalettecopy() の例

<?php
// 2 つのパレット画像を作成します
$palette1 = imagecreate(100, 100);
$palette2 = imagecreate(100, 100);

// 最初のパレット画像の背景色を
// 緑に設定します
$green = imagecolorallocate($palette1, 0, 255, 0);

// パレットを画像 1 から画像 2 にコピーします
imagepalettecopy($palette2, $palette1);

// パレットをコピーしたので、
// imagecolorallocate() をもう一度使わなくても
// 画像 1 に割り当てられた緑色を使うことができます
imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

// 画像をブラウザに出力します
header('Content-type: image/png');

imagepng($palette2);
imagedestroy($palette1);
imagedestroy($palette2);
?>


パレット形式の画像を true color に変換する

  • ≪ imagepalettecopy
  • imagepng ≫
  • PHP Manual
  • GD および Image 関数
  • パレット形式の画像を true color に変換する

imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — パレット形式の画像を true color に変換する

説明

imagepalettetotruecolor(GdImage $image): bool

imagecreate() のような関数で作ったパレット形式の画像を、 imagecreatetruecolor() で作るような true color 形式に変換します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

変換に成功した場合や、元画像が既に true color だった場合に true を返します。 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 画像オブジェクトの true color への変換

<?php
// 過去との互換性のための処理
if(!function_exists('imagepalettetotruecolor'))
{
function imagepalettetotruecolor(&$src)
{
if(imageistruecolor($src))
{
return(true);
}

$dst = imagecreatetruecolor(imagesx($src), imagesy($src));

imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));
imagedestroy($src);

$src = $dst;

return(true);
}
}

// ヘルパークロージャ
$typeof = function() use($im)
{
echo 'typeof($im) = ' . (imageistruecolor($im) ? 'true color' : 'palette'), PHP_EOL;
};

// パレット形式の画像を作ります
$im = imagecreate(100, 100);
$typeof();

// true color に変換します
imagepalettetotruecolor($im);
$typeof();

// メモリを解放します
imagedestroy($im);
?>

上の例の出力は以下となります。

typeof($im) = palette
typeof($im) = true color

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imageistruecolor() - 画像が truecolor かどうか調べる


PNG イメージをブラウザまたはファイルに出力する

  • ≪ imagepalettetotruecolor
  • imagepolygon ≫
  • PHP Manual
  • GD および Image 関数
  • PNG イメージをブラウザまたはファイルに出力する

imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — PNG イメージをブラウザまたはファイルに出力する

説明

imagepng(
GdImage $image,
resource|string|null $file = null,
int $quality = -1,
int $filters = -1
): bool

指定した image から、PNG 画像を出力あるいは保存します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

注意:

quality および filters を使用しない場合は、 null を指定することはできません。

quality

圧縮レベル。0 (圧縮しない) から 9 までの値です。 デフォルト (-1) は、zlib の圧縮レベルのデフォルトを使います。 詳細は、» zlib マニュアル をご覧ください。

filters

PNG ファイルの大きさを小さくします。 これはビットマスクフィールドで、定数 PNG_FILTER_XXX の組み合わせを指定します。 PNG_NO_FILTER や PNG_ALL_FILTERS を使用すると、 全フィルタを一括で無効にしたり有効にしたりできます。 デフォルト値 (-1) は、フィルタリングを無効にします。

警告

システムにインストールされた libgd は、filters パラメータを無視します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

<?php
$im = imagecreatefrompng("test.png");

header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

参考

  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagewbmp() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す
  • imagesavealpha() - 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する


多角形を描画する

  • ≪ imagepng
  • imagerectangle ≫
  • PHP Manual
  • GD および Image 関数
  • 多角形を描画する

imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — 多角形を描画する

説明

PHP 8.0.0 以降のシグネチャ(名前付き引数をサポートしていません)

imagepolygon(GdImage $image, array $points, int $color): bool

代替のシグネチャ (PHP 8.1.0 以降は非推奨)

imagepolygon(
GdImage $image,
array $points,
int $num_points,
int $color
): bool

imagepolygon() は、指定した image に多角形を作成します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

points

多角形の頂点からなる PHP の配列で、 次のようになります。

points[0] | = x0
points[1] | = y0
points[2] | = x1
points[3] | = y1

num_points

頂点の総数。最小でも3でなければなりません。

代替のシグネチャ(PHP 8.0.0 以降) でこの引数が省略された場合、 points は偶数でなければいけません。また、 num_points は count($points)/2 であると仮定されます。
color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 num_points は、推奨されなくなりました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagepolygon() の例

<?php
// 空の画像を生成します
$image = imagecreatetruecolor(400, 300);

// 多角形の色を選択します
$col_poly = imagecolorallocate($image, 255, 255, 255);

// 多角形を描画します
imagepolygon($image, array(
0, 0,
100, 200,
300, 200
),
3,
$col_poly);

// 画像を出力します
header('Content-type: image/png');

imagepng($image);
imagedestroy($image);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagepolygon()

参考

  • imagefilledpolygon() - 塗りつぶした多角形を描画する
  • imageopenpolygon() - オープンポリゴンを描画する
  • imagecreate() - パレットを使用する新規画像を作成する
  • imagecreatetruecolor() - TrueColor イメージを新規に作成する


矩形を描画する

  • ≪ imagepolygon
  • imageresolution ≫
  • PHP Manual
  • GD および Image 関数
  • 矩形を描画する

imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — 矩形を描画する

説明

imagerectangle(
GdImage $image,
int $x1,
int $y1,
int $x2,
int $y2,
int $color
): bool

imagerectangle() は、指定した座標から始まる矩形を作成します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x1

左上の x 座標。

y1

左上の y 座標。 0, 0 が画像の左上隅を表します。

x2

右下の x 座標。

y2

右下の y 座標。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 シンプルな imagerectangle() の例

<?php
// 200 x 200 の画像を作成します
$canvas = imagecreatetruecolor(200, 200);

// 色を割り当てます
$pink = imagecolorallocate($canvas, 255, 105, 180);
$white = imagecolorallocate($canvas, 255, 255, 255);
$green = imagecolorallocate($canvas, 132, 135, 28);

// 3 つの矩形をそれぞれの色で描画します
imagerectangle($canvas, 50, 50, 150, 150, $pink);
imagerectangle($canvas, 45, 60, 120, 100, $white);
imagerectangle($canvas, 100, 120, 75, 160, $green);

// 出力してメモリから解放します
header('Content-Type: image/jpeg');

imagejpeg($canvas);
imagedestroy($canvas);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : シンプルな imagerectangle() の例


画像の解像度を取得/設定する

  • ≪ imagerectangle
  • imagerotate ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の解像度を取得/設定する

imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — 画像の解像度を取得/設定する

説明

imageresolution(GdImage $image, ?int $resolution_x = null, ?int $resolution_y = null): array|bool

imageresolution() 関数は、 画像の解像度を DPI(dots per inch) 単位で取得/設定します。 オプションのパラメータが null だった場合は、 現在の解像度を配列で返します。 resolution_x だけが null でない場合、 垂直/水平方向の解像度がこの値に設定されます。 オプションのパラメータが両方指定されると、 垂直/水平方向の解像度がそれぞれ指定された値に設定されます。

この手の情報をサポートしている画像フォーマットを読み書きする場合(現状、PNG と JPEG)に、 解像度情報はメタ情報としてのみ使われます。画像を描画する操作には一切影響しません。 新しい画像の解像度は 96DPI です。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

resolution_x

水平方向の解像度をDPI単位で指定します。

resolution_y

垂直方向の解像度をDPI単位で指定します。

戻り値

getter として使う場合、 水平方向と垂直方向の解像度を成功時には返します。 失敗した場合に false を返します。 setter として使う場合、 成功時には true を返し、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | resolution_x と resolution_y は、nullable になりました。

例

例1 画像の解像度を取得/設定する

<?php
$im = imagecreatetruecolor(100, 100);
imageresolution($im, 200);
print_r(imageresolution($im));
imageresolution($im, 300, 72);
print_r(imageresolution($im));
?>

上の例の出力は以下となります。

Array
(
    [0] => 200
    [1] => 200
)
Array
(
    [0] => 300
    [1] => 72
)


指定された角度で画像を回転する

  • ≪ imageresolution
  • imagesavealpha ≫
  • PHP Manual
  • GD および Image 関数
  • 指定された角度で画像を回転する

imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — 指定された角度で画像を回転する

説明

imagerotate(GdImage $image, float $angle, int $background_color): GdImage|false

画像 image を、 angle で指定された角度だけ回転します。

回転の中心は画像の中心です。 回転後の画像の大きさは、もとの大きさと異なる可能性があります。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

angle

回転角度。これは、画像を反時計回りに回転させるときの度数を表します。

background_color

回転後、カバーされない部分の色。

戻り値

回転させた画像オブジェクトを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | 使われていなかった ignore_transparent が、完全に削除されました。
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | 使われていなかった ignore_transparent は、 bool を期待するようになりました。 これより前のバージョンでは、数値型を期待していました。

例

例1 画像を 180 度回転する

この例は、画像を 180 度 - 上下逆さまに回転します

<?php
// ファイルと回転角
$filename = 'test.jpg';
$degrees = 180;

// コンテントタイプ
header('Content-type: image/jpeg');

// 読み込み
$source = imagecreatefromjpeg($filename);

// 回転
$rotate = imagerotate($source, $degrees, 0);

// 出力
imagejpeg($rotate);

// メモリの解放
imagedestroy($source);
imagedestroy($rotate);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 画像を 180 度回転する

注意

注意:

この関数は、imagesetinterpolation() で設定した補間方式の影響を受けます。

参考

  • imagesetinterpolation() - 補間方法を設定する


画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

  • ≪ imagerotate
  • imagescale ≫
  • PHP Manual
  • GD および Image 関数
  • 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

説明

imagesavealpha(GdImage $image, bool $enable): bool

imagesavealpha() は 画像を保存する際に（単一色の透過設定ではない）完全な アルファチャネル情報を保存するフラグを設定します。 この関数は、完全なアルファチャンネル情報をサポートしている画像フォーマット、 つまり、PNG, WebP, AVIF をサポートしています。

注意: imagesavealpha() は、PNG でのみ意味があります。 なぜなら、完全なアルファチャンネル情報を WebP, AVIF は常に保存するからです。 この振る舞いは将来変更される可能性があるので、依存すべきではありません。 よって、WebP や AVIF 画像であっても imagesavealpha() を意図的にコールすべきです。

アルファチャネルを保存するためには、まずアルファブレンディングを解除する必要があります (imagealphablending($im, false))。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

enable

アルファチャネルを保存するか否か。デフォルトは false です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 基本的な imagesavealpha() の使用法

<?php
// アルファチャネルつきの png 画像を読み込みます
$png = imagecreatefrompng('./alphachannel_example.png');

// アルファブレンディングを無効にします
imagealphablending($png, false);

// 望んだ操作をします

// アルファフラグを設定します
imagesavealpha($png, true);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($png);
imagedestroy($png);
?>

参考

  • imagealphablending() - イメージのブレンドモードを設定する


幅と高さを指定して、画像の縮尺を変更する

  • ≪ imagesavealpha
  • imagesetbrush ≫
  • PHP Manual
  • GD および Image 関数
  • 幅と高さを指定して、画像の縮尺を変更する

imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — 幅と高さを指定して、画像の縮尺を変更する

説明

imagescale(
GdImage $image,
int $width,
int $height = -1,
int $mode = IMG_BILINEAR_FIXED
): GdImage|false

imagescale() は、指定した補間アルゴリズムを使って画像の縮尺を変更します。

注意:

他の画像処理関数と異なり、 imagescale() 関数は渡された image を変更しません。 代わりに 新しい 画像が返されます。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

width

変更後の画像の幅。

height

変更後の画像の高さ。省略したり負の数を指定したりした場合は、元の画像のアスペクト比を維持します。

mode

IMG_NEAREST_NEIGHBOUR、 IMG_BILINEAR_FIXED、 IMG_BICUBIC、 IMG_BICUBIC_FIXED あるいはそれ以外 (2 パスで使います) のいずれか。

注意: IMG_WEIGHTED4 にはまだ対応していません。

戻り値

成功した場合に、縮尺を変更した画像オブジェクトを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

参考

  • imagecopyresized() - 画像の一部をコピーしサイズを変更する
  • imagecopyresampled() - 再サンプリングを行いイメージの一部をコピー、伸縮する


線の描画用にブラシイメージを設定する

  • ≪ imagescale
  • imagesetclip ≫
  • PHP Manual
  • GD および Image 関数
  • 線の描画用にブラシイメージを設定する

imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — 線の描画用にブラシイメージを設定する

説明

imagesetbrush(GdImage $image, GdImage $brush): bool

imagesetbrush() は、特別な色 IMG_COLOR_BRUSHED または IMG_COLOR_STYLEDBRUSHED で描画される際に (imageline() や imagepolygon() のような) 全ての線描画関数で使用されるブラシイメージを設定します。

警告

ブラシの使用が終った際には特別な処理は不要ですが、 ブラシイメージを破棄する(もしくは、PHPに破棄させる)場合には、新たにブラシイメージを設定するまでは、 色 IMG_COLOR_BRUSHED または IMG_COLOR_STYLEDBRUSHED を使用するべきではありません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

brush

画像オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image と brush は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは resource を期待していました。

例

例1 imagesetbrush() の例

<?php
// 小さい php ロゴを読み込みます
$php = imagecreatefrompng('./php.png');

// 100x100 のメイン画像を作成します
$im = imagecreatetruecolor(100, 100);

// 背景を白で塗りつぶします
$white = imagecolorallocate($im, 255, 255, 255);
imagefilledrectangle($im, 0, 0, 299, 99, $white);

// ブラシを設定します
imagesetbrush($im, $php);

// いくつかのブラシを重ねます
imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

// 画像をブラウザに出力します
header('Content-type: image/png');

imagepng($im);
imagedestroy($im);
imagedestroy($php);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetbrush()


切り取る長方形を設定する

  • ≪ imagesetbrush
  • imagesetinterpolation ≫
  • PHP Manual
  • GD および Image 関数
  • 切り取る長方形を設定する

imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — 切り取る長方形を設定する

説明

imagesetclip(
GdImage $image,
int $x1,
int $y1,
int $x2,
int $y2
): bool

imagesetclip() は、切り取る長方形を設定します。 つまり、ピクセルが存在しない状態でなければ描画されます。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x1

左上のx座標

y1

左上のy座標

x2

右下のx座標

y2

右下のy座標

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

参考

  • imagegetclip() - 長方形を切り取り、画像として取得する


補間方法を設定する

  • ≪ imagesetclip
  • imagesetpixel ≫
  • PHP Manual
  • GD および Image 関数
  • 補間方法を設定する

imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — 補間方法を設定する

説明

imagesetinterpolation(GdImage $image, int $method = IMG_BILINEAR_FIXED): bool

補間方法を設定します。これは、imagerotate() など GD のさまざまな関数のレンダリングに影響を及ぼします。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

method

補間方法。次のいずれかで指定します。

  • IMG_BELL: Bell フィルター。
  • IMG_BESSEL: Bessel フィルター。
  • IMG_BICUBIC: 双三次補間。
  • IMG_BICUBIC_FIXED: 双三次補間の固定小数点実装。
  • IMG_BILINEAR_FIXED: 双直線補間の固定小数点実装 (デフォルト (画像作成時も含む))。
  • IMG_BLACKMAN: Blackman ウィンドウ関数。
  • IMG_BOX: Box blur フィルター。
  • IMG_BSPLINE: スプライン補間。
  • IMG_CATMULLROM: 三次元エルミートスプライン補間。
  • IMG_GAUSSIAN: ガウス関数。
  • IMG_GENERALIZED_CUBIC: 汎用三次元スプラインフラクタル補間。
  • IMG_HERMITE: エルミート補間。
  • IMG_HAMMING: ハミングフィルター。
  • IMG_HANNING: ハニングフィルター。
  • IMG_MITCHELL: Mitchell フィルター。
  • IMG_POWER: Power 補間。
  • IMG_QUADRATIC: 逆二次補間。
  • IMG_SINC: Sinc 関数。
  • IMG_NEAREST_NEIGHBOUR: 最近接補間。
  • IMG_WEIGHTED4: 重み付きフィルター。
  • IMG_TRIANGLE: 三角補間。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagesetinterpolation() の例

<?php
// 画像を読み込みます
$im = imagecreate(500, 500);

// デフォルトの補間方法は IMG_BILINEAR_FIXED ですが、これを
// 'Mitchell' フィルターに変更します
imagesetinterpolation($im, IMG_MITCHELL);

// $im の作業を続けます
?>

注意

補間方法を変更すると、これらの関数のレンダリングに影響を及ぼします。

  • imageaffine()
  • imagerotate()

参考

  • imagegetinterpolation() - 補間方法を取得する


点を生成する

  • ≪ imagesetinterpolation
  • imagesetstyle ≫
  • PHP Manual
  • GD および Image 関数
  • 点を生成する

imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — 点を生成する

説明

imagesetpixel(
GdImage $image,
int $x,
int $y,
int $color
): bool

imagesetpixel() は、指定した座標にピクセルを描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

x

x 座標。

y

y 座標。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagesetpixel() の例

A random drawing that ends with a regular picture.

<?php

$x = 200;
$y = 200;

$gd = imagecreatetruecolor($x, $y);

$corners[0] = array('x' => 100, 'y' => 10);
$corners[1] = array('x' => 0, 'y' => 190);
$corners[2] = array('x' => 200, 'y' => 190);

$red = imagecolorallocate($gd, 255, 0, 0);

for ($i = 0; $i < 100000; $i++) {
imagesetpixel($gd, round($x), round($y), $red);
$a = rand(0, 2);
$x = ($x + $corners[$a]['x']) / 2;
$y = ($y + $corners[$a]['y']) / 2;
}

header('Content-Type: image/png');
imagepng($gd);

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetpixel()

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • imagecolorallocate() - 画像で使用する色を作成する
  • imagecolorat() - ピクセルの色のインデックスを取得する


線描画用のスタイルを設定する

  • ≪ imagesetpixel
  • imagesetthickness ≫
  • PHP Manual
  • GD および Image 関数
  • 線描画用のスタイルを設定する

imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — 線描画用のスタイルを設定する

説明

imagesetstyle(GdImage $image, array $style): bool

imagesetstyle() は、特別な IMG_COLOR_STYLED または色を有するイメージの線 IMG_COLOR_STYLEDBRUSHED を描画する際に (imageline() と imagepolygon() のような) 全ての線描画関数で使用されるスタイルを設定します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

style

はピクセルの配列です。定数 IMG_COLOR_TRANSPARENT を使用すると、透明なピクセルを追加できます。 style は空の配列にしてはいけません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

以下の例は、キャンバスの左上から右下隅に破線を描画するスクリプトです。

例1 imagesetstyle() の例

<?php
header("Content-type: image/jpeg");
$im = imagecreatetruecolor(100, 100);
$w = imagecolorallocate($im, 255, 255, 255);
$red = imagecolorallocate($im, 255, 0, 0);

/* 5 ピクセルの赤線と 5 ピクセルの白線の破線を描画します */
$style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
imagesetstyle($im, $style);
imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

/* imagesetstyle を併用した imagesetbrush() を使用して happy face の線を描画します */
$style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
imagesetstyle($im, $style);

$brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
$w2 = imagecolorallocate($brush, 255, 255, 255);
imagecolortransparent($brush, $w2);
imagesetbrush($im, $brush);
imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

imagejpeg($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetstyle()

参考

  • imagesetbrush() - 線の描画用にブラシイメージを設定する
  • imageline() - 直線を描画する


線描画用の線幅を設定する

  • ≪ imagesetstyle
  • imagesettile ≫
  • PHP Manual
  • GD および Image 関数
  • 線描画用の線幅を設定する

imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — 線描画用の線幅を設定する

説明

imagesetthickness(GdImage $image, int $thickness): bool

imagesetthickness() は、長方形、多角形、弧などを描画する際の線幅を thickness ピクセルに設定します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

thickness

ピクセル単位の線幅。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagesetthickness() の例

<?php
// 200x100 の画像を作成します
$im = imagecreatetruecolor(200, 100);
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
$black = imagecolorallocate($im, 0x00, 0x00, 0x00);

// 背景を白に設定します
imagefilledrectangle($im, 0, 0, 299, 99, $white);

// 線幅を 5 に設定します
imagesetthickness($im, 5);

// 矩形を描画します
imagerectangle($im, 14, 14, 185, 85, $black);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesetthickness()


塗りつぶし用のイメージを設定する

  • ≪ imagesetthickness
  • imagestring ≫
  • PHP Manual
  • GD および Image 関数
  • 塗りつぶし用のイメージを設定する

imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — 塗りつぶし用のイメージを設定する

説明

imagesettile(GdImage $image, GdImage $tile): bool

imagesettile() は、特別な色 IMG_COLOR_TILED を指定して塗りつぶされた場合に、 (imagefill() や imagefilledpolygon() のような) 領域塗りつぶし関数で使用されるタイルイメージを設定します。

タイルは、領域を塗りつぶすために繰り返し使用されるイメージです。 全ての GD イメージをタイルとして使用可能で、 imagecolortransparent() でタイルの透過色 ID を設定することにより、 その一部から下の部分が透けて見えるようなタイルを作成することが可能です。

警告

タイルの使用が終った際には、特別な処理は不要ですが、 タイルイメージを破棄する(もしくは、PHPに破棄させる)場合には、 新たにタイルイメージを設定するまでは、色 IMG_COLOR_TILED を使用してはいけません。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

tile

タイルとして使用する画像オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image と tile は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 resource を期待していました。

例

例1 imagesettile() の例

<?php
// 外部の画像を読み込みます
$zend = imagecreatefromgif('./zend.gif');

// 200x200 の画像を作成します
$im = imagecreatetruecolor(200, 200);

// タイルを設定します
imagesettile($im, $zend);

// 画像の繰り返しを設定します
imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

// 画像をブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
imagedestroy($zend);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagesettile()


文字列を水平に描画する

  • ≪ imagesettile
  • imagestringup ≫
  • PHP Manual
  • GD および Image 関数
  • 文字列を水平に描画する

imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — 文字列を水平に描画する

説明

imagestring(
GdImage $image,
GdFont|int $font,
int $x,
int $y,
string $string,
int $color
): bool

指定した座標に文字列 string を描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。

x

左上隅の x 座標。

y

左上隅の y 座標。

string

書き出す文字列。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 font は、GdFont クラスのインスタンスと数値を両方受け入れるようになりました。これより前のバージョンでは、数値のみを受け入れていました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagestring() の例

<?php
// 100*30 の画像を生成します
$im = imagecreate(100, 30);

// 白色の背景と青色のテキスト
$bg = imagecolorallocate($im, 255, 255, 255);
$textcolor = imagecolorallocate($im, 0, 0, 255);

// 左上に文字列を描画します
imagestring($im, 5, 0, 0, "Hello world!", $textcolor);

// 画像を出力します
header("Content-type: image/png");

imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagestring()

参考

  • imagestringup() - 文字列を垂直に描画する
  • imageloadfont() - 新しいフォントを読み込む
  • imagettftext() - TrueType フォントを使用してテキストを画像に書き込む


文字列を垂直に描画する

  • ≪ imagestring
  • imagesx ≫
  • PHP Manual
  • GD および Image 関数
  • 文字列を垂直に描画する

imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — 文字列を垂直に描画する

説明

imagestringup(
GdImage $image,
GdFont|int $font,
int $x,
int $y,
string $string,
int $color
): bool

文字列 string を、指定した座標で垂直に描画します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

font

latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。

x

左下隅の x 座標。

y

左下隅の y 座標。

string

書き出す文字列。

color

imagecolorallocate() で作成された色識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 font は、GdFont クラスのインスタンスと数値を両方受け入れるようになりました。これより前のバージョンでは、数値のみを受け入れていました。
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagestringup() の例

<?php
// 100*100 の画像を作成します
$im = imagecreatetruecolor(100, 100);

// テキストを書き込みます
$textcolor = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
imagestringup($im, 3, 40, 80, 'gd library', $textcolor);

// 画像を保存します
imagepng($im, './stringup.png');
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagestringup()

参考

  • imagestring() - 文字列を水平に描画する
  • imageloadfont() - 新しいフォントを読み込む


画像の幅を取得する

  • ≪ imagestringup
  • imagesy ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の幅を取得する

imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — 画像の幅を取得する

説明

imagesx(GdImage $image): int

指定した画像オブジェクト image の幅を返します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

image の幅を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagesx() の使用法

<?php

// 300*200 の画像を作成します
$img = imagecreatetruecolor(300, 200);

echo imagesx($img); // 300

?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • getimagesize() - 画像の大きさを取得する
  • imagesy() - 画像の高さを取得する


画像の高さを取得する

  • ≪ imagesx
  • imagetruecolortopalette ≫
  • PHP Manual
  • GD および Image 関数
  • 画像の高さを取得する

imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — 画像の高さを取得する

説明

imagesy(GdImage $image): int

指定した画像オブジェクト image の高さを返します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

戻り値

image の高さを返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 imagesy() の使用法

<?php

// 300*200 の画像を作成します
$img = imagecreatetruecolor(300, 200);

echo imagesy($img); // 200

?>

参考

  • imagecreatetruecolor() - TrueColor イメージを新規に作成する
  • getimagesize() - 画像の大きさを取得する
  • imagesx() - 画像の幅を取得する


TrueColor イメージをパレットイメージに変換する

  • ≪ imagesy
  • imagettfbbox ≫
  • PHP Manual
  • GD および Image 関数
  • TrueColor イメージをパレットイメージに変換する

imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — TrueColor イメージをパレットイメージに変換する

説明

imagetruecolortopalette(GdImage $image, bool $dither, int $num_colors): bool

imagetruecolortopalette() は、TrueColorイメー ジをパレットイメージに変換します。この関数のコードは、元々 Independent JPEG Groupライブラリ用に書かれたもので、素晴らしいも のです。このコードは、色をできる限り維持することに加えて、アルファ チャネルに関する情報を出力されるパレットにおいてできるだけ維持す るように修正されています。これは、期待通りにうまくいきません。通 常は、最高の出力品質が保障されるTrueColor出力イメージを単に出力す るのが最良の方法です。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

dither

イメージにディザーをかけることを指定します。 true の場合はディザーが行われます。 出力はぼやけますが、色の近似はより良くなります。

num_colors

パレットに保持される最大の色数を設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 true color 画像からパレット画像への変換

<?php
// 新しい true color 画像を作成します
$im = imagecreatetruecolor(100, 100);

// ディザリングなしの 255 色パレットに変換します
imagetruecolortopalette($im, false, 255);

// 画像を保存します
imagepng($im, './paletteimage.png');
imagedestroy($im);
?>


TypeType フォントを使用したテキストの bounding box を生成する

  • ≪ imagetruecolortopalette
  • imagettftext ≫
  • PHP Manual
  • GD および Image 関数
  • TypeType フォントを使用したテキストの bounding box を生成する

imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — TypeType フォントを使用したテキストの bounding box を生成する

説明

imagettfbbox(
float $size,
float $angle,
string $font_filename,
string $string,
array $options = []
): array|false

この関数は TrueType テキストの bounding box をピクセル単位で計算して 返します。

注意:

PHP 8.0.0 より前のバージョンでは、 imageftbbox() は、 imagettfbbox() を拡張したものでした。 extrainfo を追加でサポートしています。 PHP 8.0.0 以降では、 imagettfbbox() は、 imageftbbox() のエイリアスになっています。

パラメータ

size

ポイント数単位のフォントサイズ。

angle

測定する string の角度(度単位)。

fontfile

使用したい TrueType フォントへのパス。

どの GDライブラリをPHPが使っているかによって、 いつ fontfile パラメータの先頭が / で始まらず、 .ttf がファイル名に付加されるかが違います。 そして、ライブラリは自らが定義したフォントパスに従ってそのファイル名を探そうとします。

GD ライブラリ 2.0.18 より前のバージョンを使っている場合、 セミコロンではなく、space 文字が 異なるフォントファイルの 'pathのセパレータ' として使われていました。 この機能を意図せず使ってしまうと、次のような警告が発生します: Warning: Could not find/open font. この事象の影響を受けてしまうバージョンでは、 唯一の解決策はフォントをスペースを含まないパスに移動させることだけです。

多くの場合、スクリプトが使っているフォントと同じディレクトリにある場合、 次のようなテクニックで問題を軽減できるでしょう。

<?php
// GD の環境変数を設定
putenv('GDFONTPATH=' . realpath('.'));

// 使用されるフォント名 ( .ttf 拡張子の欠落に注意)
$font = 'SomeFont';
?>

注意:

open_basedir は fontfile には適用され ない ことに注意してください。

string

測定する文字列。

戻り値

imagettfbbox() は、テキストの bounding box を 作成するための 4 点を表現する 8 個の要素からなる配列を返します。 エラー時には false を返します。

キー | 内容
0 | 左下角の X 座標
1 | 左下角の Y 座標
2 | 右下角の X 座標
3 | 右下角の Y 座標
4 | 右上角の X 座標
5 | 右上角の Y 座標
6 | 左上角の X 座標
7 | 左上角の Y 座標

各点の位置は、 angle にかかわらず text からの相対位置で表されます。 つまり、"左上"はテキストを水平に見た場合の左上の角を意味します。

変更履歴

バージョン | 説明
8.0.0 | options が追加されました。

例

例1 imagettfbbox() の例

<?php
// 300x150 の画像を作成します
$im = imagecreatetruecolor(300, 150);
$black = imagecolorallocate($im, 0, 0, 0);
$white = imagecolorallocate($im, 255, 255, 255);

// 背景を白に設定します
imagefilledrectangle($im, 0, 0, 299, 299, $white);

// フォントファイルへのパス
$font = './arial.ttf';

// まず最初のテキスト用のバウンディングボックスを作成します
$bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

// X 座標と Y 座標
$x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
$y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

// 書き込みます
imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

// 次に 2 番目のテキスト用のバウンディングボックスを作成します
$bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

// 最初のテキストに続ける座標を設定します
$x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
$y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

// 書き込みます
imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

// ブラウザに出力します
header('Content-Type: image/png');

imagepng($im);
imagedestroy($im);
?>

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imagettftext() - TrueType フォントを使用してテキストを画像に書き込む
  • imageftbbox() - freetype2 によるフォントを用いたテキストを囲む箱を取得する


TrueType フォントを使用してテキストを画像に書き込む

  • ≪ imagettfbbox
  • imagetypes ≫
  • PHP Manual
  • GD および Image 関数
  • TrueType フォントを使用してテキストを画像に書き込む

imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — TrueType フォントを使用してテキストを画像に書き込む

説明

imagettftext(
GdImage $image,
float $size,
float $angle,
int $x,
int $y,
int $color,
string $font_filename,
string $text,
array $options = []
): array|false

指定した text を、 TrueType フォントを使用して画像に書き込みます。

注意:

PHP 8.0.0 より前のバージョンでは、 imagefttext() は、 imagettftext() を拡張したものでした。 extrainfo を追加でサポートしています。 PHP 8.0.0 以降では、 imagettftext() は、 imagefttext() のエイリアスになっています。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

size

ポイント数単位のフォントサイズ。

angle

度で表される角度。0 度は左から右にテキストを読む方向になります。 0 より大きな値は、反時計回りの回転を表現します。例えば、 90 という値は下から上にテキストを読む方向になります。

x

x と y で与えられた座標は、最初の文字のベースポイント (ほぼ文字の左下角) を定義します。 この仕様は、x と y で最初の文字の右上角を定義する imagestring() と異なっています。 例えば、左上は 0, 0 となります。

y

y 座標。これは文字の最下位置ではなく、 フォントペースラインの位置を指定します。

color

カラーインデックス。負の数を使用した場合、 アンチエイリアス機能がオフになります。 imagecolorallocate() を参照ください。

fontfile

使用したい TrueType フォントへのパス。

どの GDライブラリをPHPが使っているかによって、 いつ fontfile パラメータの先頭が / で始まらず、 .ttf がファイル名に付加されるかが違います。 そして、ライブラリは自らが定義したフォントパスに従ってそのファイル名を探そうとします。

GD ライブラリ 2.0.18 より前のバージョンを使っている場合、 セミコロンではなく、space 文字が 異なるフォントファイルの 'pathのセパレータ' として使われていました。 この機能を意図せず使ってしまうと、次のような警告が発生します: Warning: Could not find/open font. この事象の影響を受けてしまうバージョンでは、 唯一の解決策はフォントをスペースを含まないパスに移動させることだけです。

多くの場合、スクリプトが使っているフォントと同じディレクトリにある場合、 次のようなテクニックで問題を軽減できるでしょう。

<?php
// GD の環境変数を設定
putenv('GDFONTPATH=' . realpath('.'));

// 使用されるフォント名 ( .ttf 拡張子の欠落に注意)
$font = 'SomeFont';
?>

注意:

open_basedir は fontfile には適用され ない ことに注意してください。

text

テキスト文字列を UTF-8 エンコーディングで表したもの。

フォント内で 127 文字目以降の文字にアクセスするために、 (&#8364; のような) 十進数文字参照を含めることができます。 (&#xA9; のような) 十六進形式もサポートしています。 UTF-8 エンコーディングされた文字列を直接渡すことができます。

&copy; のような文字エンティティはサポートされません。 html_entity_decode() を使用して、 文字エンティティを UTF-8 文字列にすることを検討してください。

フォントでサポートされていない文字が文字列で使用されている場合、 その文字は白抜きの矩形に置き換えられます。

戻り値

テキストの境界を 構成する 4 点を表す 8 個の要素を有する配列を返します。 返される点は左下、右下、右上、左上の順番となります。 点の座標は、角度によらず text に関する相対座標として表されます。 つまり、"左上"は、text を水平に見た場合の左上の隅を表します。 エラー時には false を返します。

変更履歴

バージョン | 説明
8.0.0 | options が追加されました。

例

例1 imagettftext() の例

この例は、400x30 ピクセルの白地に Arial フォントを用いて、黒字 (グレーの影付き) で "Testing..." と書かれた PNG を作成します。

<?php
// コンテントタイプを設定します
header('Content-Type: image/png');

// 画像を生成します
$im = imagecreatetruecolor(400, 30);

// いくつかの色を生成します
$white = imagecolorallocate($im, 255, 255, 255);
$grey = imagecolorallocate($im, 128, 128, 128);
$black = imagecolorallocate($im, 0, 0, 0);
imagefilledrectangle($im, 0, 0, 399, 29, $white);

// 描画する文字列
$text = 'Testing...';
// フォント自身のパスでパスを置き換えます
$font = 'arial.ttf';

// テキストに影を付けます
imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

// テキストを追加します
imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

// imagepng() を使用して imagejpeg() よりもクリアなテキストにします
imagepng($im);
imagedestroy($im);
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : imagettftext()

注意

注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

参考

  • imagettfbbox() - TypeType フォントを使用したテキストの bounding box を生成する
  • imagefttext() - FreeType 2 によるフォントを用いてイメージにテキストを描画する


この PHP がサポートしている画像形式を返す

  • ≪ imagettftext
  • imagewbmp ≫
  • PHP Manual
  • GD および Image 関数
  • この PHP がサポートしている画像形式を返す

imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — この PHP がサポートしている画像形式を返す

説明

imagetypes(): int

現在使用している PHP がサポートする画像形式を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像形式に対応するビットフィールドで、 PHP に組み込まれている GD がサポートする画像形式を返します。 返されるビットは次のとおりです。 IMG_AVIF | IMG_BMP | IMG_GIF | IMG_JPG | IMG_PNG | IMG_WBMP | IMG_XPM | IMG_WEBP。

変更履歴

バージョン | 説明
8.1.0 | IMG_AVIF が追加されました。
7.2.0 | IMG_BMP が追加されました。
7.0.10 | IMG_WEBP が追加されました。

例

例1 PNG をサポートしているかどうかの確認

<?php
if (imagetypes() & IMG_PNG) {
echo "PNG をサポートしています";
}
?>

参考

  • gd_info() - 現在インストールされているGDライブラリに関する情報を取得する


画像をブラウザあるいはファイルに出力する

  • ≪ imagetypes
  • imagewebp ≫
  • PHP Manual
  • GD および Image 関数
  • 画像をブラウザあるいはファイルに出力する

imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — 画像をブラウザあるいはファイルに出力する

説明

imagewbmp(GdImage $image, resource|string|null $file = null, ?int $foreground_color = null): bool

imagewbmp() は、指定した image を WBMP にして出力あるいは保存します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

foreground_color

このパラメータで、 前景の色を指定できます。imagecolorallocate() で 取得した ID を使用してください。デフォルトの前景色は黒です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | foreground_color は、 nullable になりました。

例

例1 WBMP 画像の出力

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// content type ヘッダを設定します - ここでは image/vnd.wap.wbmp
// ヒント: image_type_to_mime_type() で content-types を取得します
header('Content-Type: image/vnd.wap.wbmp');

// 画像を出力します
imagewbmp($im);

// メモリを開放します
imagedestroy($im);
?>

例2 WBMP 画像の保存

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// 画像を保存します
imagewbmp($im, 'simpletext.wbmp');

// メモリを開放します
imagedestroy($im);
?>

例3 別の前景での画像の出力

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// content type ヘッダを設定します - ここでは image/vnd.wap.wbmp
// ヒント: image_type_to_mime_type() で content-types を取得します
header('Content-Type: image/vnd.wap.wbmp');

// 別の前景色を設定します
$foreground_color = imagecolorallocate($im, 255, 0, 0);

imagewbmp($im, NULL, $foreground_color);

// メモリを開放します
imagedestroy($im);
?>

参考

  • image2wbmp() - 画像をブラウザあるいはファイルに出力する
  • imagepng() - PNG イメージをブラウザまたはファイルに出力する
  • imagegif() - 画像をブラウザあるいはファイルに出力する
  • imagejpeg() - 画像をブラウザあるいはファイルに出力する
  • imagetypes() - この PHP がサポートしている画像形式を返す


WebP 画像をブラウザあるいはファイルに出力する

  • ≪ imagewbmp
  • imagexbm ≫
  • PHP Manual
  • GD および Image 関数
  • WebP 画像をブラウザあるいはファイルに出力する

imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — WebP 画像をブラウザあるいはファイルに出力する

説明

imagewebp(GdImage $image, resource|string|null $file = null, int $quality = -1): bool

指定した image を、WebP 形式で出力あるいは保存します。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

file

ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり null を設定したりした場合は、画像ストリームを直接出力します。

quality

quality には、0 (品質は最低で、 ファイルサイズが小さくなる) から 100 (品質が最高で、ファイルサイズは大きくなる) までの値を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。

例

例1 WebP ファイルの保存

<?php
// 空の画像を作成し、テキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);

imagestring($im, 1, 5, 5, 'WebP with PHP', $text_color);

// 画像を保存します
imagewebp($im, 'php.webp');

// メモリを解放します
imagedestroy($im);
?>


XBM 画像をブラウザあるいはファイルに出力する

  • ≪ imagewebp
  • iptcembed ≫
  • PHP Manual
  • GD および Image 関数
  • XBM 画像をブラウザあるいはファイルに出力する

imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — XBM 画像をブラウザあるいはファイルに出力する

説明

imagexbm(GdImage $image, ?string $filename, ?int $foreground_color = null): bool

imagewbmp() は、指定した image を XBM にして出力あるいは保存します。

注意: imagexbm() はパディングを一切行わないので、 画像の幅は 8 の倍数でなければいけません。 PHP 7.0.9 以降では、この制約がなくなりました。

パラメータ

image

imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

filename

画像の保存先のパスを文字列で指定します。null を設定した場合は、画像ストリームを直接出力します。

filename (拡張子 .xbm を除いた部分) は、XBM の C 識別子としても用いられます。 そのため、現在のロケールで扱える英数字以外の文字は、アンダースコアに置き換えられます。 filename を null にすると、 image を使って C 識別子を作ります。

foreground_color

このパラメータで、 前景の色を指定できます。imagecolorallocate() で 取得した ID を使用してください。デフォルトの前景色は黒です。 その他の色はすべて、背景色として扱われます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

変更履歴

バージョン | 説明
8.0.0 | image は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な gd resource が期待されていました。
8.0.0 | foreground_color は、 nullable になりました。
8.0.0 | 使われていなかった第4引数は削除されました。

例

例1 XBM ファイルの保存

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// 画像を保存します
imagexbm($im, 'simpletext.xbm');

// メモリを開放します
imagedestroy($im);
?>

例2 別の前景色による XBM ファイルの保存

<?php
// 空の画像を作成してテキストを追加します
$im = imagecreatetruecolor(120, 20);
$text_color = imagecolorallocate($im, 233, 14, 91);
imagestring($im, 1, 5, 5, 'A Simple Text String', $text_color);

// 別の前景色を設定します
$foreground_color = imagecolorallocate($im, 255, 0, 0);

// 画像を保存します
imagexbm($im, NULL, $foreground_color);

// メモリを開放します
imagedestroy($im);
?>


バイナリ IPTC データを JPEG イメージに埋めこむ

  • ≪ imagexbm
  • iptcparse ≫
  • PHP Manual
  • GD および Image 関数
  • バイナリ IPTC データを JPEG イメージに埋めこむ

iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — バイナリ IPTC データを JPEG イメージに埋めこむ

説明

iptcembed(string $iptc_data, string $filename, int $spool = 0): string|bool

バイナリ IPTC データを JPEG イメージに埋めこみます。

パラメータ

iptc_data

書き込むデータ。

filename

JPEG 画像へのパス。

spool

Spool フラグ。このフラグが 2 より小さい場合は、JPEG が文字列として返されます。そうでない場合は、JPEG を STDOUT に出力します。

戻り値

成功し、かつ spool が 2 より小さい場合は、JPEG を返します。 失敗した場合に false を返します。spool が 2 以上の場合は、成功した場合に true を返します。 失敗した場合に false を返します。

例

例1 IPTC データの JPEG への埋め込み

<?php

// Thies C. Arntzen による iptc_make_tag() 関数
function iptc_make_tag($rec, $data, $value)
{
$length = strlen($value);
$retval = chr(0x1C) . chr($rec) . chr($data);

if($length < 0x8000)
{
$retval .= chr($length >> 8) . chr($length & 0xFF);
}
else
{
$retval .= chr(0x80) .
chr(0x04) .
chr(($length >> 24) & 0xFF) .
chr(($length >> 16) & 0xFF) .
chr(($length >> 8) & 0xFF) .
chr($length & 0xFF);
}

return $retval . $value;
}

// jpeg ファイルへのパス
$path = './phplogo.jpg';

// IPTC タグを設定します
$iptc = array(
'2#120' => 'Test image',
'2#116' => 'Copyright 2008-2009, The PHP Group'
);

// IPTC タグをバイナリコードに変換します
$data = '';

foreach($iptc as $tag => $string)
{
$tag = substr($tag, 2);
$data .= iptc_make_tag(2, $tag, $string);
}

// IPTC データを埋め込みます
$content = iptcembed($data, $path);

// 新しい画像データをファイルに書き込みます
$fp = fopen($path, "wb");
fwrite($fp, $content);
fclose($fp);
?>

注意

注意:

この関数は、GD 画像ライブラリは必要ありません。


バイナリの IPTC ブロックのタグをパースする

  • ≪ iptcembed
  • jpeg2wbmp ≫
  • PHP Manual
  • GD および Image 関数
  • バイナリの IPTC ブロックのタグをパースする

iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — バイナリの IPTC ブロックのタグをパースする

説明

iptcparse(string $iptc_block): array|false

» IPTC ブロックをパースします。

パラメータ

iptc_block

バイナリ IPTC ブロック。

戻り値

タグマーカーをインデックスとし、その値を保持する配列を返します。 エラー時や IPTC データが見つからなかったときは false を返します。

例

例1 iptcparse() を getimagesize() と組み合わせる使用法

<?php
$size = getimagesize('./test.jpg', $info);
if(isset($info['APP13']))
{
$iptc = iptcparse($info['APP13']);
var_dump($iptc);
}
?>

注意

注意:

この関数は、GD 画像ライブラリは必要ありません。


JPEG画像をWBMP画像に変換する

  • ≪ iptcparse
  • png2wbmp ≫
  • PHP Manual
  • GD および Image 関数
  • JPEG画像をWBMP画像に変換する

jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — JPEG画像をWBMP画像に変換する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

jpeg2wbmp(
string $jpegname,
string $wbmpname,
int $dest_height,
int $dest_width,
int $threshold
): bool

JPEG画像をWBMP画像に変換します。

パラメータ

jpegname

JPEG画像ファイルのパス

wbmpname

出力先のWBMPファイルのパス

dest_height

出力画像の高さ

dest_width

出力画像の幅

threshold

しきい値の値。0から8までの値を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 jpeg2wbmp() の例

<?php
// Path to the target jpeg
$path = './test.jpg';

// Get the image sizes
$image = getimagesize($path);

// Convert image
jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
?>

参考

  • png2wbmp() - PNG画像をWBMP画像に変換する


PNG画像をWBMP画像に変換する

  • ≪ jpeg2wbmp
  • GdImage ≫
  • PHP Manual
  • GD および Image 関数
  • PNG画像をWBMP画像に変換する

png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — PNG画像をWBMP画像に変換する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

png2wbmp(
string $pngname,
string $wbmpname,
int $dest_height,
int $dest_width,
int $threshold
): bool

PNG画像をWBMP画像に変換します。

パラメータ

pngname

PNG画像ファイル

wbmpname

出力先のWBMPファイルのパス

dest_height

出力画像の高さ

dest_width

出力画像の幅

threshold

しきい値の値。0から8までの値を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は true を返します。

例

例1 png2wbmp() の例

<?php
// Path to the target png
$path = './test.png';

// Get the image sizes
$image = getimagesize($path);

// Convert image
png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
?>

参考

  • jpeg2wbmp() - JPEG画像をWBMP画像に変換する


GdImage クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 gd リソースを置き換える完全不透明クラスです。

クラス概要

final class GdImage {
}


GdFont クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、gd font リソースを置き換える、完全不定形クラスです。

クラス概要

final class GdFont {
}


Gmagick

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
  • Gmagick — Gmagick クラス
    • Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する
    • Gmagick::addnoiseimage — ランダムなノイズを画像に追加する
    • Gmagick::annotateimage — 画像にテキストによる注記を加える
    • Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する
    • Gmagick::borderimage — 画像の周りを枠線で囲む
    • Gmagick::charcoalimage — 木炭画をシミュレートする
    • Gmagick::chopimage — 画像の一部を取り除き、切り詰める
    • Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする
    • Gmagick::commentimage — コメントを画像に追加する
    • Gmagick::compositeimage — ある画像を別の画像に合成する
    • Gmagick::__construct — Gmagick のコンストラクタ
    • Gmagick::cropimage — 画像の一部を抽出する
    • Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する
    • Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す
    • Gmagick::cyclecolormapimage — 画像のカラーマップを移動する
    • Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す
    • Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する
    • Gmagick::destroy — Gmagick オブジェクトを破棄する
    • Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする
    • Gmagick::edgeimage — 画像の輪郭を強調する
    • Gmagick::embossimage — グレースケール画像に三次元効果を施して返す
    • Gmagick::enhanceimage — ノイジーな画像の品質を向上させる
    • Gmagick::equalizeimage — 画像ヒストグラムを均等化する
    • Gmagick::flipimage — 垂直方向に反転した画像を作成する
    • Gmagick::flopimage — 水平方向に反転した画像を作成する
    • Gmagick::frameimage — 三次元の枠線をシミュレートする
    • Gmagick::gammaimage — 画像をガンマ補正する
    • Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す
    • Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する
    • Gmagick::getimagebackgroundcolor — 画像の背景色を返す
    • Gmagick::getimageblueprimary — 青が一番強い点を返す
    • Gmagick::getimagebordercolor — 画像の前景色を返す
    • Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す
    • Gmagick::getimagecolors — 指定した色マップインデックスの色を返す
    • Gmagick::getimagecolorspace — 画像の色空間を取得する
    • Gmagick::getimagecompose — 画像の合成演算子を返す
    • Gmagick::getimagedelay — 画像の遅延を取得する
    • Gmagick::getimagedepth — 画像の深度を取得する
    • Gmagick::getimagedispose — 画像の配置方法を取得する
    • Gmagick::getimageextrema — 画像の極値を取得する
    • Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す
    • Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す
    • Gmagick::getimagegamma — 画像のガンマを取得する
    • Gmagick::getimagegreenprimary — 緑が一番強い点を返す
    • Gmagick::getimageheight — 画像の高さを返す
    • Gmagick::getimagehistogram — 画像のヒストグラムを取得する
    • Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する
    • Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する
    • Gmagick::getimageiterations — 画像の反復を取得する
    • Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる
    • Gmagick::getimagemattecolor — 画像のマット色を返す
    • Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す
    • Gmagick::getimageredprimary — 赤が一番強い点を返す
    • Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する
    • Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する
    • Gmagick::getimagescene — 画像のシーンを取得する
    • Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する
    • Gmagick::getimagetype — 画像の型を取得する
    • Gmagick::getimageunits — 画像の解像度の単位を取得する
    • Gmagick::getimagewhitepoint — 色度が白い点を返す
    • Gmagick::getimagewidth — 画像の幅を返す
    • Gmagick::getpackagename — GraphicsMagick パッケージ名を返す
    • Gmagick::getquantumdepth — Gmagick quantum depth を返す
    • Gmagick::getreleasedate — GraphicsMagick のリリース日を返す
    • Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する
    • Gmagick::getsize — Gmagick オブジェクトのサイズを取得する
    • Gmagick::getversion — GraphicsMagick API のバージョンを返す
    • Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる
    • Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる
    • Gmagick::implodeimage — 新しい画像をコピーとして作成する
    • Gmagick::labelimage — ラベルを画像に追加する
    • Gmagick::levelimage — 画像のレベルを調節する
    • Gmagick::magnifyimage — 画像を二倍に比例拡大する
    • Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える
    • Gmagick::medianfilterimage — デジタルフィルタを適用する
    • Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する
    • Gmagick::modulateimage — 明度、彩度、色相を制御する
    • Gmagick::motionblurimage — モーションブラーをシミュレートする
    • Gmagick::newimage — 新しい画像を作成する
    • Gmagick::nextimage — 次の画像に移動する
    • Gmagick::normalizeimage — カラー画像のコントラストを強調する
    • Gmagick::oilpaintimage — 油絵をシミュレートする
    • Gmagick::previousimage — オブジェクト内の前の画像に移動する
    • Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する
    • Gmagick::quantizeimage — 参照画像内の色を解析する
    • Gmagick::quantizeimages — 画像シーケンス内の色を解析する
    • Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す
    • Gmagick::queryfonts — 設定したフォントを返す
    • Gmagick::queryformats — Gmagick がサポートするフォーマットを返す
    • Gmagick::radialblurimage — 画像にラジアルブラーを施す
    • Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする
    • Gmagick::read — ファイルから画像を読み込む
    • Gmagick::readimage — ファイルから画像を読み込む
    • Gmagick::readimageblob — バイナリ文字列から画像を読み込む
    • Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む
    • Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする
    • Gmagick::removeimage — 画像リストから画像を削除する
    • Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す
    • Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする
    • Gmagick::resizeimage — 画像のサイズを変更する
    • Gmagick::rollimage — 画像を補正する
    • Gmagick::rotateimage — 画像を回転する
    • Gmagick::scaleimage — 画像のサイズを変更する
    • Gmagick::separateimagechannel — 画像からチャネルを分離する
    • Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する
    • Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する
    • Gmagick::setimagebackgroundcolor — 画像の背景色を設定する
    • Gmagick::setimageblueprimary — 青が一番強い点を設定する
    • Gmagick::setimagebordercolor — 画像の枠線の色を設定する
    • Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する
    • Gmagick::setimagecolorspace — 画像の色空間を設定する
    • Gmagick::setimagecompose — 画像の合成演算子を設定する
    • Gmagick::setimagedelay — 画像の遅延を設定する
    • Gmagick::setimagedepth — 画像の深度を設定する
    • Gmagick::setimagedispose — 画像の配置方法を設定する
    • Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する
    • Gmagick::setimageformat — 特定の画像のフォーマットを設定する
    • Gmagick::setimagegamma — 画像のガンマを設定する
    • Gmagick::setimagegreenprimary — 緑が一番強い点を設定する
    • Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する
    • Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する
    • Gmagick::setimageiterations — 画像の反復を設定する
    • Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する
    • Gmagick::setimageredprimary — 赤が一番強い点を設定する
    • Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する
    • Gmagick::setimageresolution — 画像の解像度を設定する
    • Gmagick::setimagescene — 画像のシーンを設定する
    • Gmagick::setimagetype — 画像の型を設定する
    • Gmagick::setimageunits — 画像の解像度の単位を設定する
    • Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する
    • Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する
    • Gmagick::setsize — Gmagick オブジェクトのサイズを設定する
    • Gmagick::shearimage — 平行四辺形を作成する
    • Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する
    • Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する
    • Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する
    • Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする
    • Gmagick::thumbnailimage — 画像のサイズを変更する
    • Gmagick::trimimage — 画像の輪郭を削除する
    • Gmagick::write — Gmagick::writeimage のエイリアス
    • Gmagick::writeimage — 画像を指定したファイル名で書き出す
  • GmagickDraw — GmagickDraw クラス
    • GmagickDraw::annotate — 画像の上にテキストを描画する
    • GmagickDraw::arc — 弧を描く
    • GmagickDraw::bezier — ベジエ曲線を描く
    • GmagickDraw::ellipse — 楕円を画像上に描く
    • GmagickDraw::getfillcolor — 塗りつぶし色を返す
    • GmagickDraw::getfillopacity — 描画に使う不透明度を返す
    • GmagickDraw::getfont — フォントを返す
    • GmagickDraw::getfontsize — フォントのポイント数を返す
    • GmagickDraw::getfontstyle — フォントスタイルを返す
    • GmagickDraw::getfontweight — フォントのウェイトを返す
    • GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す
    • GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す
    • GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す
    • GmagickDraw::gettextdecoration — テキストのデコレーションを返す
    • GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す
    • GmagickDraw::line — 直線を描く
    • GmagickDraw::point — 点を描く
    • GmagickDraw::polygon — 多角形を描く
    • GmagickDraw::polyline — ポリラインを描く
    • GmagickDraw::rectangle — 矩形を描く
    • GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する
    • GmagickDraw::roundrectangle — 角が丸い矩形を描く
    • GmagickDraw::scale — 倍率を調整する
    • GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する
    • GmagickDraw::setfillopacity — 不透明度を設定する
    • GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する
    • GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する
    • GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する
    • GmagickDraw::setfontweight — フォントのウェイトを設定する
    • GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する
    • GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する
    • GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する
    • GmagickDraw::settextdecoration — デコレーションを設定する
    • GmagickDraw::settextencoding — テキストのコードセットを設定する
  • GmagickPixel — GmagickPixel クラス
    • GmagickPixel::__construct — GmagickPixel のコンストラクタ
    • GmagickPixel::getcolor — 色を返す
    • GmagickPixel::getcolorcount — この色の色カウントを返す
    • GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する
    • GmagickPixel::setcolor — 色を設定する
    • GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する


はじめに

Gmagick は、GraphicsMagick API を用いて画像の作成や編集を行ったり画像のメタ情報を取得したりするための拡張モジュールです。

GraphicsMagick は、自らを「画像処理におけるスイスアーミーナイフ」と称しています。 88 の主要なフォーマットに対応しており、よく使われる DPX、GIF、JPEG、JPEG-2000、 PNG、PDF、PNM そして TIFF もそれに含まれます。

Gmagick は、メインとなる Gmagick クラスのほかに描画のエフェクトを担当する GmagickDraw クラスと画像の各ピクセル (色、透明度) をあらわす GmagickPixel クラスで構成されています。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Gmagick
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

この拡張モジュールは、GraphicsMagick バージョン 1.4 以降 で最もうまく動作します。 Gmagick は GraphicsMagick 1.2.6 までの旧バージョンでも動作しますが、 旧バージョンでは対応していない機能やフォーマットがあります。 Windows 版の GraphicsMagick は、GraphicsMagick のウェブサイトから取得できます。 ImageMagick と GraphicsMagick の違いについては、こちらの » FAQ を参照ください。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gmagick.

注意: この拡張モジュールの正式な名前は gmagick です。

Windows 用にビルドした Gmagick 拡張モジュールは、 » ここ にあります。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Colortype constants
Gmagick::COLOR_BLACK (int)
Black
Gmagick::COLOR_BLUE (int)
Blue
Gmagick::COLOR_CYAN (int)
Cyan
Gmagick::COLOR_GREEN (int)
Green
Gmagick::COLOR_RED (int)
Red
Gmagick::COLOR_YELLOW (int)
Yellow
Gmagick::COLOR_MAGENTA (int)
Magenta
Gmagick::COLOR_OPACITY (int)
Opacity
Gmagick::COLOR_ALPHA (int)
Alpha
Gmagick::COLOR_FUZZ (int)
Fuzz
Composite Operator Constants
Gmagick::COMPOSITE_DEFAULT (int)
The default composite operator
Gmagick::COMPOSITE_UNDEFINED (int)
Undefined composite operator
Gmagick::COMPOSITE_NO (int)
No composite operator defined
Gmagick::COMPOSITE_ADD (int)
The result of image + image
Gmagick::COMPOSITE_ATOP (int)
The result is the same shape as image, with composite image obscuring image where the image shapes overlap
Gmagick::COMPOSITE_BLEND (int)
Blends the image
Gmagick::COMPOSITE_BUMPMAP (int)
The same as COMPOSITE_MULTIPLY, except the source is converted to grayscale first.
Gmagick::COMPOSITE_CLEAR (int)
Makes the target image transparent
Gmagick::COMPOSITE_COLORBURN (int)
Darkens the destination image to reflect the source image
Gmagick::COMPOSITE_COLORDODGE (int)
Brightens the destination image to reflect the source image
Gmagick::COMPOSITE_COLORIZE (int)
Colorizes the target image using the composite image
Gmagick::COMPOSITE_COPYBLACK (int)
Copies black from the source to target
Gmagick::COMPOSITE_COPYBLUE (int)
Copies blue from the source to target
Gmagick::COMPOSITE_COPY (int)
Copies the source image on the target image
Gmagick::COMPOSITE_COPYCYAN (int)
Copies cyan from the source to target
Gmagick::COMPOSITE_COPYGREEN (int)
Copies green from the source to target
Gmagick::COMPOSITE_COPYMAGENTA (int)
Copies magenta from the source to target
Gmagick::COMPOSITE_COPYOPACITY (int)
Copies opacity from the source to target
Gmagick::COMPOSITE_COPYRED (int)
Copies red from the source to target
Gmagick::COMPOSITE_COPYYELLOW (int)
Copies yellow from the source to target
Gmagick::COMPOSITE_DARKEN (int)
Darkens the target image
Gmagick::COMPOSITE_DSTATOP (int)
The part of the destination lying inside of the source is composited over the source and replaces the destination
Gmagick::COMPOSITE_DST (int)
The target is left untouched
Gmagick::COMPOSITE_DSTIN (int)
The parts inside the source replace the target
Gmagick::COMPOSITE_DSTOUT (int)
The parts outside the source replace the target
Gmagick::COMPOSITE_DSTOVER (int)
Target replaces the source
Gmagick::COMPOSITE_DIFFERENCE (int)
Subtracts the darker of the two constituent colors from the lighter
Gmagick::COMPOSITE_DISPLACE (int)
Shifts target image pixels as defined by the source
Gmagick::COMPOSITE_DISSOLVE (int)
Dissolves the source in to the target
Gmagick::COMPOSITE_EXCLUSION (int)
Produces an effect similar to that of Gmagick::COMPOSITE_DIFFERENCE, but appears as lower contrast
Gmagick::COMPOSITE_HARDLIGHT (int)
Multiplies or screens the colors, dependent on the source color value
Gmagick::COMPOSITE_HUE (int)
Modifies the hue of the target as defined by source
Gmagick::COMPOSITE_IN (int)
Composites source into the target
Gmagick::COMPOSITE_LIGHTEN (int)
Lightens the target as defined by source
Gmagick::COMPOSITE_LUMINIZE (int)
Luminizes the target as defined by source
Gmagick::COMPOSITE_MINUS (int)
Subtracts the source from the target
Gmagick::COMPOSITE_MODULATE (int)
Modulates the target brightness, saturation and hue as defined by source
Gmagick::COMPOSITE_MULTIPLY (int)
Multiplies the target to the source
Gmagick::COMPOSITE_OUT (int)
Composites outer parts of the source on the target
Gmagick::COMPOSITE_OVER (int)
Composites source over the target
Gmagick::COMPOSITE_OVERLAY (int)
Overlays the source on the target
Gmagick::COMPOSITE_PLUS (int)
Adds the source to the target
Gmagick::COMPOSITE_REPLACE (int)
Replaces the target with the source
Gmagick::COMPOSITE_SATURATE (int)
Saturates the target as defined by the source
Gmagick::COMPOSITE_SCREEN (int)
The source and destination are complemented and then multiplied and then replace the destination
Gmagick::COMPOSITE_SOFTLIGHT (int)
Darkens or lightens the colors, dependent on the source
Gmagick::COMPOSITE_SRCATOP (int)
The part of the source lying inside of the destination is composited onto the destination
Gmagick::COMPOSITE_SRC (int)
The source is copied to the destination
Gmagick::COMPOSITE_SRCIN (int)
The part of the source lying inside of the destination replaces the destination
Gmagick::COMPOSITE_SRCOUT (int)
The part of the source lying outside of the destination replaces the destination
Gmagick::COMPOSITE_SRCOVER (int)
The source replaces the destination
Gmagick::COMPOSITE_SUBTRACT (int)
Subtract the colors in the source image from the destination image
Gmagick::COMPOSITE_THRESHOLD (int)
The source is composited on the target as defined by source threshold
Gmagick::COMPOSITE_XOR (int)
The part of the source that lies outside of the destination is combined with the part of the destination that lies outside of the source
Montage Mode constants
Gmagick::MONTAGEMODE_FRAME (int)
Gmagick::MONTAGEMODE_UNFRAME (int)
Gmagick::MONTAGEMODE_CONCATENATE (int)
Style constants
Gmagick::STYLE_NORMAL (int)
Gmagick::STYLE_ITALIC (int)
Gmagick::STYLE_OBLIQUE (int)
Gmagick::STYLE_ANY (int)
Filter constants
Gmagick::FILTER_UNDEFINED (int)
Gmagick::FILTER_POINT (int)
Gmagick::FILTER_BOX (int)
Gmagick::FILTER_TRIANGLE (int)
Gmagick::FILTER_HERMITE (int)
Gmagick::FILTER_HANNING (int)
Gmagick::FILTER_HAMMING (int)
Gmagick::FILTER_BLACKMAN (int)
Gmagick::FILTER_GAUSSIAN (int)
Gmagick::FILTER_QUADRATIC (int)
Gmagick::FILTER_CUBIC (int)
Gmagick::FILTER_CATROM (int)
Gmagick::FILTER_MITCHELL (int)
Gmagick::FILTER_LANCZOS (int)
Gmagick::FILTER_BESSEL (int)
Gmagick::FILTER_SINC (int)
Image type constants
Gmagick::IMGTYPE_UNDEFINED (int)
Gmagick::IMGTYPE_BILEVEL (int)
Gmagick::IMGTYPE_GRAYSCALE (int)
Gmagick::IMGTYPE_GRAYSCALEMATTE (int)
Gmagick::IMGTYPE_PALETTE (int)
Gmagick::IMGTYPE_PALETTEMATTE (int)
Gmagick::IMGTYPE_TRUECOLOR (int)
Gmagick::IMGTYPE_TRUECOLORMATTE (int)
Gmagick::IMGTYPE_COLORSEPARATION (int)
Gmagick::IMGTYPE_COLORSEPARATIONMATTE (int)
Gmagick::IMGTYPE_OPTIMIZE (int)
Resolution constants
Gmagick::RESOLUTION_UNDEFINED (int)
Gmagick::RESOLUTION_PIXELSPERINCH (int)
Gmagick::RESOLUTION_PIXELSPERCENTIMETER (int)
Compression constants
Gmagick::COMPRESSION_UNDEFINED (int)
Gmagick::COMPRESSION_NO (int)
Gmagick::COMPRESSION_BZIP (int)
Gmagick::COMPRESSION_FAX (int)
Gmagick::COMPRESSION_GROUP4 (int)
Gmagick::COMPRESSION_JPEG (int)
Gmagick::COMPRESSION_JPEG2000 (int)
Gmagick::COMPRESSION_LOSSLESSJPEG (int)
Gmagick::COMPRESSION_LZW (int)
Gmagick::COMPRESSION_RLE (int)
Gmagick::COMPRESSION_ZIP (int)
Paint constants
Gmagick::PAINT_POINT (int)
Gmagick::PAINT_REPLACE (int)
Gmagick::PAINT_FLOODFILL (int)
Gmagick::PAINT_FILLTOBORDER (int)
Gmagick::PAINT_RESET (int)
Gravity constants
Gmagick::GRAVITY_NORTHWEST (int)
Gmagick::GRAVITY_NORTH (int)
Gmagick::GRAVITY_NORTHEAST (int)
Gmagick::GRAVITY_WEST (int)
Gmagick::GRAVITY_CENTER (int)
Gmagick::GRAVITY_EAST (int)
Gmagick::GRAVITY_SOUTHWEST (int)
Gmagick::GRAVITY_SOUTH (int)
Gmagick::GRAVITY_SOUTHEAST (int)
Stretch constants
Gmagick::STRETCH_NORMAL (int)
Gmagick::STRETCH_ULTRACONDENSED (int)
Gmagick::STRETCH_CONDENSED (int)
Gmagick::STRETCH_SEMICONDENSED (int)
Gmagick::STRETCH_SEMIEXPANDED (int)
Gmagick::STRETCH_EXPANDED (int)
Gmagick::STRETCH_EXTRAEXPANDED (int)
Gmagick::STRETCH_ULTRAEXPANDED (int)
Gmagick::STRETCH_ANY (int)
Align constants
Gmagick::ALIGN_UNDEFINED (int)
Gmagick::ALIGN_LEFT (int)
Gmagick::ALIGN_CENTER (int)
Gmagick::ALIGN_RIGHT (int)
Decoration constants
Gmagick::DECORATION_NO (int)
Gmagick::DECORATION_UNDERLINE (int)
Gmagick::DECORATION_OVERLINE (int)
Gmagick::DECORATION_LINETROUGH (int)
Noise constants
Gmagick::NOISE_UNIFORM (int)
Gmagick::NOISE_GAUSSIAN (int)
Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN (int)
Gmagick::NOISE_IMPULSE (int)
Gmagick::NOISE_LAPLACIAN (int)
Gmagick::NOISE_POISSON (int)
Channel constants
Gmagick::CHANNEL_UNDEFINED (int)
Gmagick::CHANNEL_RED (int)
Gmagick::CHANNEL_GRAY (int)
Gmagick::CHANNEL_CYAN (int)
Gmagick::CHANNEL_GREEN (int)
Gmagick::CHANNEL_MAGENTA (int)
Gmagick::CHANNEL_BLUE (int)
Gmagick::CHANNEL_YELLOW (int)
Gmagick::CHANNEL_ALPHA (int)
Gmagick::CHANNEL_OPACITY (int)
Gmagick::CHANNEL_MATTE (int)
Gmagick::CHANNEL_BLACK (int)
Gmagick::CHANNEL_INDEX (int)
Gmagick::CHANNEL_ALL (int)
Metric constants
Gmagick::METRIC_UNDEFINED (int)
Gmagick::METRIC_MEANABSOLUTEERROR (int)
Gmagick::METRIC_MEANSQUAREERROR (int)
Gmagick::METRIC_PEAKABSOLUTEERROR (int)
Gmagick::METRIC_PEAKSIGNALTONOISERATIO (int)
Gmagick::METRIC_ROOTMEANSQUAREDERROR (int)
Pixel constants
Gmagick::PIXEL_CHAR (int)
Gmagick::PIXEL_DOUBLE (int)
Gmagick::PIXEL_FLOAT (int)
Gmagick::PIXEL_INTEGER (int)
Gmagick::PIXEL_LONG (int)
Gmagick::PIXEL_QUANTUM (int)
Gmagick::PIXEL_SHORT (int)
Colorspace constants
Gmagick::COLORSPACE_UNDEFINED (int)
Gmagick::COLORSPACE_RGB (int)
Gmagick::COLORSPACE_GRAY (int)
Gmagick::COLORSPACE_TRANSPARENT (int)
Gmagick::COLORSPACE_OHTA (int)
Gmagick::COLORSPACE_LAB (int)
Gmagick::COLORSPACE_XYZ (int)
Gmagick::COLORSPACE_YCBCR (int)
Gmagick::COLORSPACE_YCC (int)
Gmagick::COLORSPACE_YIQ (int)
Gmagick::COLORSPACE_YPBPR (int)
Gmagick::COLORSPACE_YUV (int)
Gmagick::COLORSPACE_CMYK (int)
Gmagick::COLORSPACE_SRGB (int)
Gmagick::COLORSPACE_HSB (int)
Gmagick::COLORSPACE_HSL (int)
Gmagick::COLORSPACE_HWB (int)
Gmagick::COLORSPACE_REC601LUMA (int)
Gmagick::COLORSPACE_REC709LUMA (int)
Gmagick::COLORSPACE_LOG (int)
Virtual Pixel Method constants
Gmagick::VIRTUALPIXELMETHOD_UNDEFINED (int)
Gmagick::VIRTUALPIXELMETHOD_BACKGROUND (int)
Gmagick::VIRTUALPIXELMETHOD_CONSTANT (int)
Gmagick::VIRTUALPIXELMETHOD_EDGE (int)
Gmagick::VIRTUALPIXELMETHOD_MIRROR (int)
Gmagick::VIRTUALPIXELMETHOD_TILE (int)
Gmagick::VIRTUALPIXELMETHOD_TRANSPARENT (int)
Preview constants
Gmagick::PREVIEW_UNDEFINED (int)
Gmagick::PREVIEW_ROTATE (int)
Gmagick::PREVIEW_SHEAR (int)
Gmagick::PREVIEW_ROLL (int)
Gmagick::PREVIEW_HUE (int)
Gmagick::PREVIEW_SATURATION (int)
Gmagick::PREVIEW_BRIGHTNESS (int)
Gmagick::PREVIEW_GAMMA (int)
Gmagick::PREVIEW_SPIFF (int)
Gmagick::PREVIEW_DULL (int)
Gmagick::PREVIEW_GRAYSCALE (int)
Gmagick::PREVIEW_QUANTIZE (int)
Gmagick::PREVIEW_DESPECKLE (int)
Gmagick::PREVIEW_REDUCENOISE (int)
Gmagick::PREVIEW_ADDNOISE (int)
Gmagick::PREVIEW_SHARPEN (int)
Gmagick::PREVIEW_BLUR (int)
Gmagick::PREVIEW_THRESHOLD (int)
Gmagick::PREVIEW_EDGEDETECT (int)
Gmagick::PREVIEW_SPREAD (int)
Gmagick::PREVIEW_SOLARIZE (int)
Gmagick::PREVIEW_SHADE (int)
Gmagick::PREVIEW_RAISE (int)
Gmagick::PREVIEW_SEGMENT (int)
Gmagick::PREVIEW_SWIRL (int)
Gmagick::PREVIEW_IMPLODE (int)
Gmagick::PREVIEW_WAVE (int)
Gmagick::PREVIEW_OILPAINT (int)
Gmagick::PREVIEW_CHARCOALDRAWING (int)
Gmagick::PREVIEW_JPEG (int)
Rendering Intent constants
Gmagick::RENDERINGINTENT_UNDEFINED (int)
Gmagick::RENDERINGINTENT_SATURATION (int)
Gmagick::RENDERINGINTENT_PERCEPTUAL (int)
Gmagick::RENDERINGINTENT_ABSOLUTE (int)
Gmagick::RENDERINGINTENT_RELATIVE (int)
Fillrule constants
Gmagick::FILLRULE_UNDEFINED (int)
Gmagick::FILLRULE_EVENODD (int)
Gmagick::FILLRULE_NONZERO (int)
Pathunit constants
Gmagick::PATHUNITS_UNDEFINED (int)
Gmagick::PATHUNITS_USERSPACE (int)
Gmagick::PATHUNITS_USERSPACEONUSE (int)
Gmagick::PATHUNITS_OBJECTBOUNDINGBOX (int)
Linecap constants
Gmagick::LINECAP_UNDEFINED (int)
Gmagick::LINECAP_BUTT (int)
Gmagick::LINECAP_ROUND (int)
Gmagick::LINECAP_SQUARE (int)
Line Join constants
Gmagick::LINEJOIN_UNDEFINED (int)
Gmagick::LINEJOIN_MITER (int)
Gmagick::LINEJOIN_ROUND (int)
Gmagick::LINEJOIN_BEVEL (int)
Resourcetype constants
Gmagick::RESOURCETYPE_UNDEFINED (int)
Gmagick::RESOURCETYPE_AREA (int)
Gmagick::RESOURCETYPE_DISK (int)
Gmagick::RESOURCETYPE_FILE (int)
Gmagick::RESOURCETYPE_MAP (int)
Gmagick::RESOURCETYPE_MEMORY (int)
Orientation constants
Gmagick::ORIENTATION_UNDEFINED (int)
Gmagick::ORIENTATION_TOPLEFT (int)
Gmagick::ORIENTATION_TOPRIGHT (int)
Gmagick::ORIENTATION_BOTTOMRIGHT (int)
Gmagick::ORIENTATION_BOTTOMLEFT (int)
Gmagick::ORIENTATION_LEFTTOP (int)
Gmagick::ORIENTATION_RIGHTTOP (int)
Gmagick::ORIENTATION_RIGHTBOTTOM (int)
Gmagick::ORIENTATION_LEFTBOTTOM (int)
Interlace constants
Gmagick::INTERLACE_UNDEFINED (int)
Gmagick::INTERLACE_NO (int)
Gmagick::INTERLACE_NONE (int)
Gmagick::INTERLACE_LINE (int)
Gmagick::INTERLACE_PLANE (int)
Gmagick::INTERLACE_PARTITION (int)


例

次の例は、Gmagick での一般的な画像操作の方法を示すものです。

例1 Gmagick の例

<?php
// 新しい Gmagick オブジェクトのインスタンスを作成します
$image = new Gmagick('example.jpg');

// 読み込んだ画像のサムネイルを作成します。どちらかの軸に 0 を指定すると、アスペクト比を維持します
$image->thumbnailimage(100, 0);

// 画像の周りに枠をつけ、油彩風に見えるようにします
// このように、Gmagick ではメソッドの連結に対応していることに注意しましょう
$image->borderimage("yellow", 8, 8)->oilpaintimage(0.3);

// 現在の画像をファイルに書き込みます
$image->write('example_thumbnail.jpg');
?>


Gmagick クラス

(PECL gmagick >= Unknown)

はじめに

クラス概要

class Gmagick {
/* メソッド */
public __construct(string $filename = ?)
public addimage(Gmagick $source): Gmagick
public addnoiseimage(int $noise_type): Gmagick
public annotateimage(
GmagickDraw $GmagickDraw,
float $x,
float $y,
float $angle,
string $text
): Gmagick
public blurimage(float $radius, float $sigma, int $channel = ?): Gmagick
public borderimage(GmagickPixel $color, int $width, int $height): Gmagick
public charcoalimage(float $radius, float $sigma): Gmagick
public chopimage(
int $width,
int $height,
int $x,
int $y
): Gmagick
public clear(): Gmagick
public commentimage(string $comment): Gmagick
public compositeimage(
Gmagick $source,
int $COMPOSE,
int $x,
int $y
): Gmagick
public cropimage(
int $width ,
int $height ,
int $x,
int $y
): Gmagick
public cropthumbnailimage(int $width, int $height): Gmagick
public current(): Gmagick
public cyclecolormapimage(int $displace): Gmagick
public deconstructimages(): Gmagick
public despeckleimage(): Gmagick
public destroy(): bool
public drawimage(GmagickDraw $GmagickDraw): Gmagick
public edgeimage(float $radius): Gmagick
public embossimage(float $radius, float $sigma): Gmagick
public enhanceimage(): Gmagick
public equalizeimage(): Gmagick
public flipimage(): Gmagick
public flopimage(): Gmagick
public frameimage(
GmagickPixel $color,
int $width,
int $height,
int $inner_bevel,
int $outer_bevel
): Gmagick
public gammaimage(float $gamma): Gmagick
public getcopyright(): string
public getfilename(): string
public getimagebackgroundcolor(): GmagickPixel
public getimageblueprimary(): array
public getimagebordercolor(): GmagickPixel
public getimagechanneldepth(int $channel_type): int
public getimagecolors(): int
public getimagecolorspace(): int
public getimagecompose(): int
public getimagedelay(): int
public getimagedepth(): int
public getimagedispose(): int
public getimageextrema(): array
public getimagefilename(): string
public getimageformat(): string
public getimagegamma(): float
public getimagegreenprimary(): array
public getimageheight(): int
public getimagehistogram(): array
public getimageindex(): int
public getimageinterlacescheme(): int
public getimageiterations(): int
public getimagematte(): int
public getimagemattecolor(): GmagickPixel
public getimageprofile(string $name): string
public getimageredprimary(): array
public getimagerenderingintent(): int
public getimageresolution(): array
public getimagescene(): int
public getimagesignature(): string
public getimagetype(): int
public getimageunits(): int
public getimagewhitepoint(): array
public getimagewidth(): int
public getpackagename(): string
public getquantumdepth(): array
public getreleasedate(): string
public getsamplingfactors(): array
public getsize(): array
public getversion(): array
public hasnextimage(): mixed
public haspreviousimage(): mixed
public implodeimage(float $radius): mixed
public labelimage(string $label): mixed
public levelimage(
float $blackPoint,
float $gamma,
float $whitePoint,
int $channel = Gmagick::CHANNEL_DEFAULT
): mixed
public magnifyimage(): mixed
public mapimage(gmagick $gmagick, bool $dither): Gmagick
public medianfilterimage(float $radius): void
public minifyimage(): Gmagick
public modulateimage(float $brightness, float $saturation, float $hue): Gmagick
public motionblurimage(float $radius, float $sigma, float $angle): Gmagick
public newimage(
int $width,
int $height,
string $background,
string $format = ?
): Gmagick
public nextimage(): bool
public normalizeimage(int $channel = ?): Gmagick
public oilpaintimage( float $radius ): Gmagick
public previousimage(): bool
public profileimage(string $name, string $profile): Gmagick
public quantizeimage(
int $numColors,
int $colorspace,
int $treeDepth,
bool $dither,
bool $measureError
): Gmagick
public quantizeimages(
int $numColors,
int $colorspace,
int $treeDepth,
bool $dither,
bool $measureError
): Gmagick
public queryfontmetrics(GmagickDraw $draw, string $text): array
public queryfonts(string $pattern = "*"): array
public queryformats(string $pattern = "*"): array
public radialblurimage(float $angle, int $channel = Gmagick::CHANNEL_DEFAULT): Gmagick
public raiseimage(
int $width,
int $height,
int $x,
int $y,
bool $raise
): Gmagick
public read(string $filename): Gmagick
public readimage(string $filename): Gmagick
public readimageblob(string $imageContents, string $filename = ?): Gmagick
public readimagefile(resource $fp, string $filename = ?): Gmagick
public reducenoiseimage(float $radius): Gmagick
public removeimage(): Gmagick
public removeimageprofile(string $name): string
public resampleimage(
float $xResolution,
float $yResolution,
int $filter,
float $blur
): Gmagick
public resizeimage(
int $width,
int $height,
int $filter,
float $blur,
bool $fit = false
): Gmagick
public rollimage(int $x, int $y): Gmagick
public rotateimage(mixed $color, float $degrees): Gmagick
public scaleimage(int $width, int $height, bool $fit = false): Gmagick
public separateimagechannel(int $channel): Gmagick
setCompressionQuality( int $quality = 75 ): Gmagick
public setfilename(string $filename): Gmagick
public setimagebackgroundcolor(GmagickPixel $color): Gmagick
public setimageblueprimary(float $x, float $y): Gmagick
public setimagebordercolor(GmagickPixel $color): Gmagick
public setimagechanneldepth(int $channel, int $depth): Gmagick
public setimagecolorspace(int $colorspace): Gmagick
public setimagecompose(int $composite): Gmagick
public setimagedelay(int $delay): Gmagick
public setimagedepth(int $depth): Gmagick
public setimagedispose(int $disposeType): Gmagick
public setimagefilename(string $filename): Gmagick
public setimageformat(string $imageFormat): Gmagick
public setimagegamma(float $gamma): Gmagick
public setimagegreenprimary(float $x, float $y): Gmagick
public setimageindex(int $index): Gmagick
public setimageinterlacescheme(int $interlace): Gmagick
public setimageiterations(int $iterations): Gmagick
public setimageprofile(string $name, string $profile): Gmagick
public setimageredprimary(float $x, float $y): Gmagick
public setimagerenderingintent(int $rendering_intent): Gmagick
public setimageresolution(float $xResolution, float $yResolution): Gmagick
public setimagescene(int $scene): Gmagick
public setimagetype(int $imgType): Gmagick
public setimageunits(int $resolution): Gmagick
public setimagewhitepoint(float $x, float $y): Gmagick
public setsamplingfactors(array $factors): Gmagick
public setsize(int $columns, int $rows): Gmagick
public shearimage(mixed $color, float $xShear, float $yShear): Gmagick
public solarizeimage(int $threshold): Gmagick
public spreadimage(float $radius): Gmagick
public stripimage(): Gmagick
public swirlimage(float $degrees): Gmagick
public thumbnailimage(int $width, int $height, bool $fit = false): Gmagick
public trimimage(float $fuzz): Gmagick
public writeimage(string $filename, bool $all_frames = false): Gmagick
}

目次

  • Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する
  • Gmagick::addnoiseimage — ランダムなノイズを画像に追加する
  • Gmagick::annotateimage — 画像にテキストによる注記を加える
  • Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する
  • Gmagick::borderimage — 画像の周りを枠線で囲む
  • Gmagick::charcoalimage — 木炭画をシミュレートする
  • Gmagick::chopimage — 画像の一部を取り除き、切り詰める
  • Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする
  • Gmagick::commentimage — コメントを画像に追加する
  • Gmagick::compositeimage — ある画像を別の画像に合成する
  • Gmagick::__construct — Gmagick のコンストラクタ
  • Gmagick::cropimage — 画像の一部を抽出する
  • Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する
  • Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す
  • Gmagick::cyclecolormapimage — 画像のカラーマップを移動する
  • Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す
  • Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する
  • Gmagick::destroy — Gmagick オブジェクトを破棄する
  • Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする
  • Gmagick::edgeimage — 画像の輪郭を強調する
  • Gmagick::embossimage — グレースケール画像に三次元効果を施して返す
  • Gmagick::enhanceimage — ノイジーな画像の品質を向上させる
  • Gmagick::equalizeimage — 画像ヒストグラムを均等化する
  • Gmagick::flipimage — 垂直方向に反転した画像を作成する
  • Gmagick::flopimage — 水平方向に反転した画像を作成する
  • Gmagick::frameimage — 三次元の枠線をシミュレートする
  • Gmagick::gammaimage — 画像をガンマ補正する
  • Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す
  • Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する
  • Gmagick::getimagebackgroundcolor — 画像の背景色を返す
  • Gmagick::getimageblueprimary — 青が一番強い点を返す
  • Gmagick::getimagebordercolor — 画像の前景色を返す
  • Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す
  • Gmagick::getimagecolors — 指定した色マップインデックスの色を返す
  • Gmagick::getimagecolorspace — 画像の色空間を取得する
  • Gmagick::getimagecompose — 画像の合成演算子を返す
  • Gmagick::getimagedelay — 画像の遅延を取得する
  • Gmagick::getimagedepth — 画像の深度を取得する
  • Gmagick::getimagedispose — 画像の配置方法を取得する
  • Gmagick::getimageextrema — 画像の極値を取得する
  • Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す
  • Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す
  • Gmagick::getimagegamma — 画像のガンマを取得する
  • Gmagick::getimagegreenprimary — 緑が一番強い点を返す
  • Gmagick::getimageheight — 画像の高さを返す
  • Gmagick::getimagehistogram — 画像のヒストグラムを取得する
  • Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する
  • Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する
  • Gmagick::getimageiterations — 画像の反復を取得する
  • Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる
  • Gmagick::getimagemattecolor — 画像のマット色を返す
  • Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す
  • Gmagick::getimageredprimary — 赤が一番強い点を返す
  • Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する
  • Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する
  • Gmagick::getimagescene — 画像のシーンを取得する
  • Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する
  • Gmagick::getimagetype — 画像の型を取得する
  • Gmagick::getimageunits — 画像の解像度の単位を取得する
  • Gmagick::getimagewhitepoint — 色度が白い点を返す
  • Gmagick::getimagewidth — 画像の幅を返す
  • Gmagick::getpackagename — GraphicsMagick パッケージ名を返す
  • Gmagick::getquantumdepth — Gmagick quantum depth を返す
  • Gmagick::getreleasedate — GraphicsMagick のリリース日を返す
  • Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する
  • Gmagick::getsize — Gmagick オブジェクトのサイズを取得する
  • Gmagick::getversion — GraphicsMagick API のバージョンを返す
  • Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる
  • Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる
  • Gmagick::implodeimage — 新しい画像をコピーとして作成する
  • Gmagick::labelimage — ラベルを画像に追加する
  • Gmagick::levelimage — 画像のレベルを調節する
  • Gmagick::magnifyimage — 画像を二倍に比例拡大する
  • Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える
  • Gmagick::medianfilterimage — デジタルフィルタを適用する
  • Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する
  • Gmagick::modulateimage — 明度、彩度、色相を制御する
  • Gmagick::motionblurimage — モーションブラーをシミュレートする
  • Gmagick::newimage — 新しい画像を作成する
  • Gmagick::nextimage — 次の画像に移動する
  • Gmagick::normalizeimage — カラー画像のコントラストを強調する
  • Gmagick::oilpaintimage — 油絵をシミュレートする
  • Gmagick::previousimage — オブジェクト内の前の画像に移動する
  • Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する
  • Gmagick::quantizeimage — 参照画像内の色を解析する
  • Gmagick::quantizeimages — 画像シーケンス内の色を解析する
  • Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す
  • Gmagick::queryfonts — 設定したフォントを返す
  • Gmagick::queryformats — Gmagick がサポートするフォーマットを返す
  • Gmagick::radialblurimage — 画像にラジアルブラーを施す
  • Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする
  • Gmagick::read — ファイルから画像を読み込む
  • Gmagick::readimage — ファイルから画像を読み込む
  • Gmagick::readimageblob — バイナリ文字列から画像を読み込む
  • Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む
  • Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする
  • Gmagick::removeimage — 画像リストから画像を削除する
  • Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す
  • Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする
  • Gmagick::resizeimage — 画像のサイズを変更する
  • Gmagick::rollimage — 画像を補正する
  • Gmagick::rotateimage — 画像を回転する
  • Gmagick::scaleimage — 画像のサイズを変更する
  • Gmagick::separateimagechannel — 画像からチャネルを分離する
  • Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する
  • Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する
  • Gmagick::setimagebackgroundcolor — 画像の背景色を設定する
  • Gmagick::setimageblueprimary — 青が一番強い点を設定する
  • Gmagick::setimagebordercolor — 画像の枠線の色を設定する
  • Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する
  • Gmagick::setimagecolorspace — 画像の色空間を設定する
  • Gmagick::setimagecompose — 画像の合成演算子を設定する
  • Gmagick::setimagedelay — 画像の遅延を設定する
  • Gmagick::setimagedepth — 画像の深度を設定する
  • Gmagick::setimagedispose — 画像の配置方法を設定する
  • Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する
  • Gmagick::setimageformat — 特定の画像のフォーマットを設定する
  • Gmagick::setimagegamma — 画像のガンマを設定する
  • Gmagick::setimagegreenprimary — 緑が一番強い点を設定する
  • Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する
  • Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する
  • Gmagick::setimageiterations — 画像の反復を設定する
  • Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する
  • Gmagick::setimageredprimary — 赤が一番強い点を設定する
  • Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する
  • Gmagick::setimageresolution — 画像の解像度を設定する
  • Gmagick::setimagescene — 画像のシーンを設定する
  • Gmagick::setimagetype — 画像の型を設定する
  • Gmagick::setimageunits — 画像の解像度の単位を設定する
  • Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する
  • Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する
  • Gmagick::setsize — Gmagick オブジェクトのサイズを設定する
  • Gmagick::shearimage — 平行四辺形を作成する
  • Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する
  • Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する
  • Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する
  • Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする
  • Gmagick::thumbnailimage — 画像のサイズを変更する
  • Gmagick::trimimage — 画像の輪郭を削除する
  • Gmagick::write — Gmagick::writeimage のエイリアス
  • Gmagick::writeimage — 画像を指定したファイル名で書き出す


新しい画像を Gmagick オブジェクトの画像リストに追加する

  • ≪ Gmagick
  • Gmagick::addnoiseimage ≫
  • PHP Manual
  • Gmagick
  • 新しい画像を Gmagick オブジェクトの画像リストに追加する

Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する

説明

public Gmagick::addimage(Gmagick $source): Gmagick

新しい画像を、ソースオブジェクトの現在位置から Gmagick オブジェクトに追加します。 この操作の後は、イテレータの位置がリストの末尾に移動します。

パラメータ

source

ソース Gmagick オブジェクト。

戻り値

Gmagick オブジェクトに画像を追加して返します。

エラー / 例外

エラー時に GmagickException をスローします。


ランダムなノイズを画像に追加する

  • ≪ Gmagick::addimage
  • Gmagick::annotateimage ≫
  • PHP Manual
  • Gmagick
  • ランダムなノイズを画像に追加する

Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — ランダムなノイズを画像に追加する

説明

public Gmagick::addnoiseimage(int $noise_type): Gmagick

ランダムなノイズを画像に追加します。

パラメータ

noise_type

ノイズの形式。 ノイズ定数 の一覧を参照ください。

戻り値

Gmagick オブジェクトにノイズを追加して返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像にテキストによる注記を加える

  • ≪ Gmagick::addnoiseimage
  • Gmagick::blurimage ≫
  • PHP Manual
  • Gmagick
  • 画像にテキストによる注記を加える

Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — 画像にテキストによる注記を加える

説明

public Gmagick::annotateimage(
GmagickDraw $GmagickDraw,
float $x,
float $y,
float $angle,
string $text
): Gmagick

テキストによる注記を画像に加えます。

パラメータ

GmagickDraw

テキスト描画設定を含む GmagickDraw オブジェクト。

x

テキストの左端の水平オフセットをあらわすピクセル数。

y

テキストのベースラインの垂直オフセットをあらわすピクセル数。

angle

テキストを書き出す角度。

text

描画するテキスト。

戻り値

Gmagick オブジェクトに注記を加えて返します。

エラー / 例外

エラー時に GmagickException をスローします。


blur (にじみ) フィルタを画像に追加する

  • ≪ Gmagick::annotateimage
  • Gmagick::borderimage ≫
  • PHP Manual
  • Gmagick
  • blur (にじみ) フィルタを画像に追加する

Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する

説明

public Gmagick::blurimage(float $radius, float $sigma, int $channel = ?): Gmagick

blur (にじみ) フィルタを画像に追加します。

パラメータ

radius

にじみの半径。

sigma

標準偏差。

戻り値

にじませた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の周りを枠線で囲む

  • ≪ Gmagick::blurimage
  • Gmagick::charcoalimage ≫
  • PHP Manual
  • Gmagick
  • 画像の周りを枠線で囲む

Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — 画像の周りを枠線で囲む

説明

public Gmagick::borderimage(GmagickPixel $color, int $width, int $height): Gmagick

画像の周りを枠線で囲みます。枠線の色は GmagickPixel オブジェクトあるいは色文字列で指定します。

パラメータ

color

枠線の色を含む GmagickPixel オブジェクトあるいは文字列。

width

枠線の幅。

height

枠線の高さ。

戻り値

枠線を定義した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


木炭画をシミュレートする

  • ≪ Gmagick::borderimage
  • Gmagick::chopimage ≫
  • PHP Manual
  • Gmagick
  • 木炭画をシミュレートする

Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — 木炭画をシミュレートする

説明

public Gmagick::charcoalimage(float $radius, float $sigma): Gmagick

木炭画をシミュレートします。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

戻り値

木炭画をシミュレートした Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の一部を取り除き、切り詰める

  • ≪ Gmagick::charcoalimage
  • Gmagick::clear ≫
  • PHP Manual
  • Gmagick
  • 画像の一部を取り除き、切り詰める

Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — 画像の一部を取り除き、切り詰める

説明

public Gmagick::chopimage(
int $width,
int $height,
int $x,
int $y
): Gmagick

画像の一部を削除し、そこにあった画像をなくします。

パラメータ

width

切り取る範囲の幅。

height

切り取る範囲の高さ。

x

切り取る範囲の X 座標。

y

切り取る範囲の Y 座標。

戻り値

切り取った後の Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

  • ≪ Gmagick::chopimage
  • Gmagick::commentimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

説明

public Gmagick::clear(): Gmagick

Gmagick オブジェクトに関連付けられたすべてのリソースをクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

クリアした Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


コメントを画像に追加する

  • ≪ Gmagick::clear
  • Gmagick::compositeimage ≫
  • PHP Manual
  • Gmagick
  • コメントを画像に追加する

Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — コメントを画像に追加する

説明

public Gmagick::commentimage(string $comment): Gmagick

コメントを画像に追加します。

パラメータ

comment

追加するコメント。

戻り値

コメントを追加した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


ある画像を別の画像に合成する

  • ≪ Gmagick::commentimage
  • Gmagick::__construct ≫
  • PHP Manual
  • Gmagick
  • ある画像を別の画像に合成する

Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — ある画像を別の画像に合成する

説明

public Gmagick::compositeimage(
Gmagick $source,
int $COMPOSE,
int $x,
int $y
): Gmagick

ある画像を、別の画像の指定した位置に合成します。

パラメータ

source

合成する画像を保持する Gmagick オブジェクト。

compose

合成演算子。

x

合成する位置の列オフセット。

y

合成する位置の行オフセット。

戻り値

合成した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick のコンストラクタ

  • ≪ Gmagick::compositeimage
  • Gmagick::cropimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick のコンストラクタ

Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — Gmagick のコンストラクタ

説明

public Gmagick::__construct(string $filename = ?)

Gmagick のコンストラクタです。

パラメータ

filename

読み込みたい画像へのパス、あるいは複数のパスの配列。

エラー / 例外

エラー時に GmagickException をスローします。


画像の一部を抽出する

  • ≪ Gmagick::__construct
  • Gmagick::cropthumbnailimage ≫
  • PHP Manual
  • Gmagick
  • 画像の一部を抽出する

Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — 画像の一部を抽出する

説明

public Gmagick::cropimage(
int $width ,
int $height ,
int $x,
int $y
): Gmagick

画像の一部を抽出します。

パラメータ

width

抽出する幅。

height

抽出する高さ。

x

抽出する領域の左上の X 座標。

y

抽出する領域の左上の Y 座標。

戻り値

抽出した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


切り取ってサムネイルを作成する

  • ≪ Gmagick::cropimage
  • Gmagick::current ≫
  • PHP Manual
  • Gmagick
  • 切り取ってサムネイルを作成する

Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する

説明

public Gmagick::cropthumbnailimage(int $width, int $height): Gmagick

固定サイズのサムネイルを作成します。 まず画像のサイズを拡大あるいは縮小し、指定した範囲を中心から切り取ります。

パラメータ

width

サムネイルの幅。

height

サムネイルの高さ。

戻り値

切り取った Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


現在の Gmagick オブジェクトへの参照を返す

  • ≪ Gmagick::cropthumbnailimage
  • Gmagick::cyclecolormapimage ≫
  • PHP Manual
  • Gmagick
  • 現在の Gmagick オブジェクトへの参照を返す

Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す

説明

public Gmagick::current(): Gmagick

現在の gmagick オブジェクトへの参照を返し、 画像ポインタを正しいシーケンスに設定します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に自分自身を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のカラーマップを移動する

  • ≪ Gmagick::current
  • Gmagick::deconstructimages ≫
  • PHP Manual
  • Gmagick
  • 画像のカラーマップを移動する

Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — 画像のカラーマップを移動する

説明

public Gmagick::cyclecolormapimage(int $displace): Gmagick

位置番号を指定して、画像のカラーマップを移動します。 カラーマップを何度か回転させると、サイケデリックな効果が得られます。

パラメータ

displace

カラーマップを移動させる量。

戻り値

成功した場合に自分自身を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像間の特定のピクセルの差を返す

  • ≪ Gmagick::cyclecolormapimage
  • Gmagick::despeckleimage ≫
  • PHP Manual
  • Gmagick
  • 画像間の特定のピクセルの差を返す

Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す

説明

public Gmagick::deconstructimages(): Gmagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

新しい Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像内のスペックルノイズを軽減する

  • ≪ Gmagick::deconstructimages
  • Gmagick::destroy ≫
  • PHP Manual
  • Gmagick
  • 画像内のスペックルノイズを軽減する

Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する

説明

public Gmagick::despeckleimage(): Gmagick

画像内のスペックルノイズを軽減します。ただし元画像の輪郭は保持します。

パラメータ

この関数にはパラメータはありません。

戻り値

スペックルノイズを軽減した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

例

例1 Gmagick::despeckleimage() の例

<?php
/* ... */
?>

上の例の出力は、 たとえば以下のようになります。

...


Gmagick オブジェクトを破棄する

  • ≪ Gmagick::despeckleimage
  • Gmagick::drawimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトを破棄する

Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Gmagick オブジェクトを破棄する

説明

public Gmagick::destroy(): bool

Gmagick オブジェクトを破棄し、 関連するリソースをすべて解放します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。


現在の画像上の GmagickDraw オブジェクトをレンダリングする

  • ≪ Gmagick::destroy
  • Gmagick::edgeimage ≫
  • PHP Manual
  • Gmagick
  • 現在の画像上の GmagickDraw オブジェクトをレンダリングする

Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする

説明

public Gmagick::drawimage(GmagickDraw $GmagickDraw): Gmagick

現在の画像上の GmagickDraw オブジェクトをレンダリングします。

パラメータ

GmagickDraw

画像をレンダリングする描画操作。

戻り値

描かれた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の輪郭を強調する

  • ≪ Gmagick::drawimage
  • Gmagick::embossimage ≫
  • PHP Manual
  • Gmagick
  • 画像の輪郭を強調する

Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — 画像の輪郭を強調する

説明

public Gmagick::edgeimage(float $radius): Gmagick

指定した半径の畳み込みフィルタを使用して、画像の輪郭を強調します。 radius に 0 を設定すると自動選択となります。

パラメータ

radius

操作の半径。

戻り値

輪郭を強調した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


グレースケール画像に三次元効果を施して返す

  • ≪ Gmagick::edgeimage
  • Gmagick::enhanceimage ≫
  • PHP Manual
  • Gmagick
  • グレースケール画像に三次元効果を施して返す

Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — グレースケール画像に三次元効果を施して返す

説明

public Gmagick::embossimage(float $radius, float $sigma): Gmagick

グレースケール画像に三次元効果を施したものを返します。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

パラメータ

radius

効果の半径。

sigma

効果のシグマ。

戻り値

エンボス処理した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


ノイジーな画像の品質を向上させる

  • ≪ Gmagick::embossimage
  • Gmagick::equalizeimage ≫
  • PHP Manual
  • Gmagick
  • ノイジーな画像の品質を向上させる

Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — ノイジーな画像の品質を向上させる

説明

public Gmagick::enhanceimage(): Gmagick

デジタルフィルタを適用して、ノイジーな画像の品質を向上させます。

パラメータ

この関数にはパラメータはありません。

戻り値

品質を向上させた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像ヒストグラムを均等化する

  • ≪ Gmagick::enhanceimage
  • Gmagick::flipimage ≫
  • PHP Manual
  • Gmagick
  • 画像ヒストグラムを均等化する

Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — 画像ヒストグラムを均等化する

説明

public Gmagick::equalizeimage(): Gmagick

画像ヒストグラムを均等化します。

パラメータ

この関数にはパラメータはありません。

戻り値

均等化した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


垂直方向に反転した画像を作成する

  • ≪ Gmagick::equalizeimage
  • Gmagick::flopimage ≫
  • PHP Manual
  • Gmagick
  • 垂直方向に反転した画像を作成する

Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — 垂直方向に反転した画像を作成する

説明

public Gmagick::flipimage(): Gmagick

中心の x 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

垂直反転した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

参考

  • Gmagick::flopimage() - 水平方向に反転した画像を作成する


水平方向に反転した画像を作成する

  • ≪ Gmagick::flipimage
  • Gmagick::frameimage ≫
  • PHP Manual
  • Gmagick
  • 水平方向に反転した画像を作成する

Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — 水平方向に反転した画像を作成する

説明

public Gmagick::flopimage(): Gmagick

中心の y 軸を基準してピクセルを反転させ、水平方向のミラー画像を作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

垂直反転した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

参考

  • Gmagick::flipimage() - 垂直方向に反転した画像を作成する


三次元の枠線をシミュレートする

  • ≪ Gmagick::flopimage
  • Gmagick::gammaimage ≫
  • PHP Manual
  • Gmagick
  • 三次元の枠線をシミュレートする

Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — 三次元の枠線をシミュレートする

説明

public Gmagick::frameimage(
GmagickPixel $color,
int $width,
int $height,
int $inner_bevel,
int $outer_bevel
): Gmagick

画像の周りに三次元の枠線を追加します。 width と height で、それぞれ縦の枠線と横の枠線の幅を指定します。 inner_bevel および outer_bevel は、 それぞれ枠の内側と外側の影の幅を指定します。

パラメータ

color

マット色を表す GmagickPixel オブジェクトあるいは浮動小数点数。

width

枠の幅。

height

枠の高さ。

inner_bevel

内側の影の幅。

outer_bevel

外側の影の幅。

戻り値

枠線をつけた Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像をガンマ補正する

  • ≪ Gmagick::frameimage
  • Gmagick::getcopyright ≫
  • PHP Manual
  • Gmagick
  • 画像をガンマ補正する

Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — 画像をガンマ補正する

説明

public Gmagick::gammaimage(float $gamma): Gmagick

画像をガンマ補正します。同じ画像でも、 異なるデバイス上で見ると見た目が変わることがあります。 これは、画面上に画像の輝度を表現する方法がことなるためです。 赤、緑、青の各チャネルに個別のガンマレベルを指定するか、 あるいはすべてのチャネルに共通のガンマレベルを指定します。 値の典型的な範囲は、0.8 から 2.3 の間となります。

パラメータ

gamma

ガンマ補正の量。

戻り値

ガンマ補正した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


GraphicsMagick API の著作権情報を文字列で返す

  • ≪ Gmagick::gammaimage
  • Gmagick::getfilename ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick API の著作権情報を文字列で返す

Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す

説明

public Gmagick::getcopyright(): string

GraphicsMagick API の著作権情報を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

GraphicsMagick および Magickwand C API の著作権情報を含む文字列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像シーケンスに関連付けられたファイル名を取得する

  • ≪ Gmagick::getcopyright
  • Gmagick::getimagebackgroundcolor ≫
  • PHP Manual
  • Gmagick
  • 画像シーケンスに関連付けられたファイル名を取得する

Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する

説明

public Gmagick::getfilename(): string

画像シーケンスに関連付けられたファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に文字列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の背景色を返す

  • ≪ Gmagick::getfilename
  • Gmagick::getimageblueprimary ≫
  • PHP Manual
  • Gmagick
  • 画像の背景色を返す

Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — 画像の背景色を返す

説明

public Gmagick::getimagebackgroundcolor(): GmagickPixel

画像の背景色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の背景色を設定した GmagickPixel を返します。

エラー / 例外

エラー時に GmagickException をスローします。


青が一番強い点を返す

  • ≪ Gmagick::getimagebackgroundcolor
  • Gmagick::getimagebordercolor ≫
  • PHP Manual
  • Gmagick
  • 青が一番強い点を返す

Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — 青が一番強い点を返す

説明

public Gmagick::getimageblueprimary(): array

青が一番強い点を返します。

パラメータ

x

青が一番強い点の x 座標。

y

青が一番強い点の y 座標。

戻り値

"x" 座標および "y" 座標を含む配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の前景色を返す

  • ≪ Gmagick::getimageblueprimary
  • Gmagick::getimagechanneldepth ≫
  • PHP Manual
  • Gmagick
  • 画像の前景色を返す

Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — 画像の前景色を返す

説明

public Gmagick::getimagebordercolor(): GmagickPixel

画像の前景色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の前景色を表す GmagickPixel オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


特定の画像チャネルの深度を返す

  • ≪ Gmagick::getimagebordercolor
  • Gmagick::getimagecolors ≫
  • PHP Manual
  • Gmagick
  • 特定の画像チャネルの深度を返す

Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す

説明

public Gmagick::getimagechanneldepth(int $channel_type): int

特定の画像チャネルの深度を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像チャネルの深度を返します。

エラー / 例外

エラー時に GmagickException をスローします。


指定した色マップインデックスの色を返す

  • ≪ Gmagick::getimagechanneldepth
  • Gmagick::getimagecolorspace ≫
  • PHP Manual
  • Gmagick
  • 指定した色マップインデックスの色を返す

Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — 指定した色マップインデックスの色を返す

説明

public Gmagick::getimagecolors(): int

指定した色マップインデックスの色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像内の色の数を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の色空間を取得する

  • ≪ Gmagick::getimagecolors
  • Gmagick::getimagecompose ≫
  • PHP Manual
  • Gmagick
  • 画像の色空間を取得する

Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — 画像の色空間を取得する

説明

public Gmagick::getimagecolorspace(): int

画像の色空間を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

色空間を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の合成演算子を返す

  • ≪ Gmagick::getimagecolorspace
  • Gmagick::getimagedelay ≫
  • PHP Manual
  • Gmagick
  • 画像の合成演算子を返す

Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — 画像の合成演算子を返す

説明

public Gmagick::getimagecompose(): int

画像に関連付けられている合成演算子を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像に関連付けられている合成演算子を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の遅延を取得する

  • ≪ Gmagick::getimagecompose
  • Gmagick::getimagedepth ≫
  • PHP Manual
  • Gmagick
  • 画像の遅延を取得する

Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — 画像の遅延を取得する

説明

public Gmagick::getimagedelay(): int

画像の遅延を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の遅延を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の深度を取得する

  • ≪ Gmagick::getimagedelay
  • Gmagick::getimagedispose ≫
  • PHP Manual
  • Gmagick
  • 画像の深度を取得する

Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — 画像の深度を取得する

説明

public Gmagick::getimagedepth(): int

画像の深度を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の深度を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の配置方法を取得する

  • ≪ Gmagick::getimagedepth
  • Gmagick::getimageextrema ≫
  • PHP Manual
  • Gmagick
  • 画像の配置方法を取得する

Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — 画像の配置方法を取得する

説明

public Gmagick::getimagedispose(): int

画像の配置方法を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の配置方法を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の極値を取得する

  • ≪ Gmagick::getimagedispose
  • Gmagick::getimagefilename ≫
  • PHP Manual
  • Gmagick
  • 画像の極値を取得する

Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — 画像の極値を取得する

説明

public Gmagick::getimageextrema(): array

画像の極値を取得します。 "min" および "max" というキーを持つ連想配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

"min" および "max" というキーを持つ連想配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


シーケンス内の特定の画像のファイル名を返す

  • ≪ Gmagick::getimageextrema
  • Gmagick::getimageformat ≫
  • PHP Manual
  • Gmagick
  • シーケンス内の特定の画像のファイル名を返す

Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す

説明

public Gmagick::getimagefilename(): string

シーケンス内の特定の画像のファイル名を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のファイル名を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


シーケンス内の特定の画像のフォーマットを返す

  • ≪ Gmagick::getimagefilename
  • Gmagick::getimagegamma ≫
  • PHP Manual
  • Gmagick
  • シーケンス内の特定の画像のフォーマットを返す

Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す

説明

public Gmagick::getimageformat(): string

シーケンス内の特定の画像のフォーマットを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合は画像のフォーマットを文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のガンマを取得する

  • ≪ Gmagick::getimageformat
  • Gmagick::getimagegreenprimary ≫
  • PHP Manual
  • Gmagick
  • 画像のガンマを取得する

Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — 画像のガンマを取得する

説明

public Gmagick::getimagegamma(): float

画像のガンマを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にガンマを返します。

エラー / 例外

エラー時に GmagickException をスローします。


緑が一番強い点を返す

  • ≪ Gmagick::getimagegamma
  • Gmagick::getimageheight ≫
  • PHP Manual
  • Gmagick
  • 緑が一番強い点を返す

Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — 緑が一番強い点を返す

説明

public Gmagick::getimagegreenprimary(): array

緑が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に "x" および "y" というキーを持つ配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の高さを返す

  • ≪ Gmagick::getimagegreenprimary
  • Gmagick::getimagehistogram ≫
  • PHP Manual
  • Gmagick
  • 画像の高さを返す

Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — 画像の高さを返す

説明

public Gmagick::getimageheight(): int

画像の高さを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の高さをピクセル数で返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のヒストグラムを取得する

  • ≪ Gmagick::getimageheight
  • Gmagick::getimageindex ≫
  • PHP Manual
  • Gmagick
  • 画像のヒストグラムを取得する

Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — 画像のヒストグラムを取得する

説明

public Gmagick::getimagehistogram(): array

画像のヒストグラムを GmagickPixel オブジェクトの配列で返します。 エラーが起きた場合は GmagickException をスローします。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のヒストグラムを GmagickPixel オブジェクトの配列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


現在アクティブな画像のインデックスを取得する

  • ≪ Gmagick::getimagehistogram
  • Gmagick::getimageinterlacescheme ≫
  • PHP Manual
  • Gmagick
  • 現在アクティブな画像のインデックスを取得する

Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する

説明

public Gmagick::getimageindex(): int

Gmagick オブジェクト内で現在アクティブな画像のインデックスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在アクティブな画像のインデックスを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のインターレース手法を取得する

  • ≪ Gmagick::getimageindex
  • Gmagick::getimageiterations ≫
  • PHP Manual
  • Gmagick
  • 画像のインターレース手法を取得する

Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する

説明

public Gmagick::getimageinterlacescheme(): int

画像のインターレース手法を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に画像のインターレース手法を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の反復を取得する

  • ≪ Gmagick::getimageinterlacescheme
  • Gmagick::getimagematte ≫
  • PHP Manual
  • Gmagick
  • 画像の反復を取得する

Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — 画像の反復を取得する

説明

public Gmagick::getimageiterations(): int

画像の反復を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の反復を表す整数値を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像がマットチャネルを持っているかどうかを調べる

  • ≪ Gmagick::getimageiterations
  • Gmagick::getimagemattecolor ≫
  • PHP Manual
  • Gmagick
  • 画像がマットチャネルを持っているかどうかを調べる

Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる

説明

public Gmagick::getimagematte(): int

画像がマットチャネルを持っている場合に true、 そうでない場合に false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像がマットチャネルを持っている場合に true、 そうでない場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のマット色を返す

  • ≪ Gmagick::getimagematte
  • Gmagick::getimageprofile ≫
  • PHP Manual
  • Gmagick
  • 画像のマット色を返す

Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — 画像のマット色を返す

説明

public Gmagick::getimagemattecolor(): GmagickPixel

成功した場合に GmagickPixel オブジェクトを返します。エラー時に GmagickException をスローします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に GmagickPixel オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


指定した名前の画像プロファイルを返す

  • ≪ Gmagick::getimagemattecolor
  • Gmagick::getimageredprimary ≫
  • PHP Manual
  • Gmagick
  • 指定した名前の画像プロファイルを返す

Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す

説明

public Gmagick::getimageprofile(string $name): string

指定した名前の画像プロファイルを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像プロファイルを含む文字列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


赤が一番強い点を返す

  • ≪ Gmagick::getimageprofile
  • Gmagick::getimagerenderingintent ≫
  • PHP Manual
  • Gmagick
  • 赤が一番強い点を返す

Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — 赤が一番強い点を返す

説明

public Gmagick::getimageredprimary(): array

赤が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

赤が一番強い点を "x" および "y" というキーを持つ配列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のレンダリング方向を取得する

  • ≪ Gmagick::getimageredprimary
  • Gmagick::getimageresolution ≫
  • PHP Manual
  • Gmagick
  • 画像のレンダリング方向を取得する

Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する

説明

public Gmagick::getimagerenderingintent(): int

画像のレンダリング方向を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のレンダリング方向を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の X 方向と Y 方向の解像度を取得する

  • ≪ Gmagick::getimagerenderingintent
  • Gmagick::getimagescene ≫
  • PHP Manual
  • Gmagick
  • 画像の X 方向と Y 方向の解像度を取得する

Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する

説明

public Gmagick::getimageresolution(): array

解像度を配列で取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

解像度を配列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のシーンを取得する

  • ≪ Gmagick::getimageresolution
  • Gmagick::getimagesignature ≫
  • PHP Manual
  • Gmagick
  • 画像のシーンを取得する

Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — 画像のシーンを取得する

説明

public Gmagick::getimagescene(): int

画像のシーンを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のシーンを返します。

エラー / 例外

エラー時に GmagickException をスローします。


SHA-256 メッセージダイジェストを生成する

  • ≪ Gmagick::getimagescene
  • Gmagick::getimagetype ≫
  • PHP Manual
  • Gmagick
  • SHA-256 メッセージダイジェストを生成する

Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する

説明

public Gmagick::getimagesignature(): string

画像ピクセルストリームの SHA-256 メッセージダイジェストを生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

そのファイルの SHA-256 ハッシュを文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の型を取得する

  • ≪ Gmagick::getimagesignature
  • Gmagick::getimageunits ≫
  • PHP Manual
  • Gmagick
  • 画像の型を取得する

Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — 画像の型を取得する

説明

public Gmagick::getimagetype(): int

画像の型を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の型を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の解像度の単位を取得する

  • ≪ Gmagick::getimagetype
  • Gmagick::getimagewhitepoint ≫
  • PHP Manual
  • Gmagick
  • 画像の解像度の単位を取得する

Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — 画像の解像度の単位を取得する

説明

public Gmagick::getimageunits(): int

画像の解像度の単位を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の解像度の単位を返します。


色度が白い点を返す

  • ≪ Gmagick::getimageunits
  • Gmagick::getimagewidth ≫
  • PHP Manual
  • Gmagick
  • 色度が白い点を返す

Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — 色度が白い点を返す

説明

public Gmagick::getimagewhitepoint(): array

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

パラメータ

この関数にはパラメータはありません。

戻り値

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

エラー / 例外

エラー時に GmagickException をスローします。


画像の幅を返す

  • ≪ Gmagick::getimagewhitepoint
  • Gmagick::getpackagename ≫
  • PHP Manual
  • Gmagick
  • 画像の幅を返す

Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — 画像の幅を返す

説明

public Gmagick::getimagewidth(): int

画像の幅を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の幅を返します。

エラー / 例外

エラー時に GmagickException をスローします。


GraphicsMagick パッケージ名を返す

  • ≪ Gmagick::getimagewidth
  • Gmagick::getquantumdepth ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick パッケージ名を返す

Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — GraphicsMagick パッケージ名を返す

説明

public Gmagick::getpackagename(): string

GraphicsMagick パッケージ名を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

GraphicsMagick パッケージ名を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick quantum depth を返す

  • ≪ Gmagick::getpackagename
  • Gmagick::getreleasedate ≫
  • PHP Manual
  • Gmagick
  • Gmagick quantum depth を返す

Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Gmagick quantum depth を返す

説明

public Gmagick::getquantumdepth(): array

Gmagick quantum depth を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Gmagick quantum depth を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


GraphicsMagick のリリース日を返す

  • ≪ Gmagick::getquantumdepth
  • Gmagick::getsamplingfactors ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick のリリース日を返す

Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — GraphicsMagick のリリース日を返す

説明

public Gmagick::getreleasedate(): string

GraphicsMagick のリリース日を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

GraphicsMagick のリリース日を文字列で返します。

エラー / 例外

エラー時に GmagickException をスローします。


水平方向および垂直方向のサンプリング係数を取得する

  • ≪ Gmagick::getreleasedate
  • Gmagick::getsize ≫
  • PHP Manual
  • Gmagick
  • 水平方向および垂直方向のサンプリング係数を取得する

Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する

説明

public Gmagick::getsamplingfactors(): array

水平方向および垂直方向のサンプリング係数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の水平方向および垂直方向のサンプリング係数を含む連想配列を返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick オブジェクトのサイズを取得する

  • ≪ Gmagick::getsamplingfactors
  • Gmagick::getversion ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトのサイズを取得する

Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Gmagick オブジェクトのサイズを取得する

説明

public Gmagick::getsize(): array

Gmagick オブジェクトのサイズを返します。 "columns" および "rows" というキーを持つ連想配列となります。

パラメータ

この関数にはパラメータはありません。

戻り値

Gmagick オブジェクトのサイズを返します。 "columns" および "rows" というキーを持つ連想配列となります。

エラー / 例外

エラー時に GmagickException をスローします。


GraphicsMagick API のバージョンを返す

  • ≪ Gmagick::getsize
  • Gmagick::hasnextimage ≫
  • PHP Manual
  • Gmagick
  • GraphicsMagick API のバージョンを返す

Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — GraphicsMagick API のバージョンを返す

説明

public Gmagick::getversion(): array

GraphicsMagick API のバージョンを文字列と数値で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

GraphicsMagick API のバージョンを文字列と数値で返します。

エラー / 例外

エラー時に GmagickException をスローします。


オブジェクトが次の画像を保持しているかどうかを調べる

  • ≪ Gmagick::getversion
  • Gmagick::haspreviousimage ≫
  • PHP Manual
  • Gmagick
  • オブジェクトが次の画像を保持しているかどうかを調べる

Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる

説明

public Gmagick::hasnextimage(): mixed

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。

エラー / 例外

エラー時に GmagickException をスローします。


オブジェクトが前の画像を保持しているかどうかを調べる

  • ≪ Gmagick::hasnextimage
  • Gmagick::implodeimage ≫
  • PHP Manual
  • Gmagick
  • オブジェクトが前の画像を保持しているかどうかを調べる

Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる

説明

public Gmagick::haspreviousimage(): mixed

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。

エラー / 例外

エラー時に GmagickException をスローします。


新しい画像をコピーとして作成する

  • ≪ Gmagick::haspreviousimage
  • Gmagick::labelimage ≫
  • PHP Manual
  • Gmagick
  • 新しい画像をコピーとして作成する

Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — 新しい画像をコピーとして作成する

説明

public Gmagick::implodeimage(float $radius): mixed

既存の画像をコピーして新しい画像を作成します。 既存の画像のピクセルを、指定したパーセンテージで "内破" します。

パラメータ

radius

内破処理の半径。

戻り値

内破した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


ラベルを画像に追加する

  • ≪ Gmagick::implodeimage
  • Gmagick::levelimage ≫
  • PHP Manual
  • Gmagick
  • ラベルを画像に追加する

Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — ラベルを画像に追加する

説明

public Gmagick::labelimage(string $label): mixed

ラベルを画像に追加します。

パラメータ

label

追加するラベル。

戻り値

ラベルを追加した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のレベルを調節する

  • ≪ Gmagick::labelimage
  • Gmagick::magnifyimage ≫
  • PHP Manual
  • Gmagick
  • 画像のレベルを調節する

Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — 画像のレベルを調節する

説明

public Gmagick::levelimage(
float $blackPoint,
float $gamma,
float $whitePoint,
int $channel = Gmagick::CHANNEL_DEFAULT
): mixed

画像のレベルを調整します。 指定した白と黒の範囲にある色を、利用可能な色の範囲全体に拡大します。 黒の点、中間点、白の点をパラメータで指定します。 黒の点は、画像の中で一番暗い色を表します。 これより暗い色の点はゼロに設定されます。 中間点は、画像に適用するガンマ補正を指定します。 黒の点は、画像の中で一番明るい色を表します。 これより明るい色の点は最大値に設定されます。

パラメータ

blackPoint

画像の黒の点。

gamma

ガンマ値。

whitePoint

画像の白の点。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

画像のレベルを調節した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像を二倍に比例拡大する

  • ≪ Gmagick::levelimage
  • Gmagick::mapimage ≫
  • PHP Manual
  • Gmagick
  • 画像を二倍に比例拡大する

Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — 画像を二倍に比例拡大する

説明

public Gmagick::magnifyimage(): mixed

画像を元のサイズの二倍に比例拡大します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡大した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の色を、参照画像の中の最も近い色に置き換える

  • ≪ Gmagick::magnifyimage
  • Gmagick::medianfilterimage ≫
  • PHP Manual
  • Gmagick
  • 画像の色を、参照画像の中の最も近い色に置き換える

Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える

説明

public Gmagick::mapimage(gmagick $gmagick, bool $dither): Gmagick

画像の色を、参照画像の中の最も近い色に置き換えます。

パラメータ

gmagick

参照する画像。

dither

ゼロ以外の整数値を設定して、マップした画像をディザリングします。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


デジタルフィルタを適用する

  • ≪ Gmagick::mapimage
  • Gmagick::minifyimage ≫
  • PHP Manual
  • Gmagick
  • デジタルフィルタを適用する

Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — デジタルフィルタを適用する

説明

public Gmagick::medianfilterimage(float $radius): void

デジタルフィルタを適用してノイジーな画像の品質を向上させます。 各ピクセルの内容を、radius で定義した近傍ピクセルの中央値で置き換えます。

パラメータ

radius

近傍ピクセルの半径。

戻り値

メジアンフィルタを適用した Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像をその半分のサイズに比例縮小する

  • ≪ Gmagick::medianfilterimage
  • Gmagick::modulateimage ≫
  • PHP Manual
  • Gmagick
  • 画像をその半分のサイズに比例縮小する

Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する

説明

public Gmagick::minifyimage(): Gmagick

画像のサイズを元の半分に比例縮小します。

パラメータ

この関数にはパラメータはありません。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


明度、彩度、色相を制御する

  • ≪ Gmagick::minifyimage
  • Gmagick::motionblurimage ≫
  • PHP Manual
  • Gmagick
  • 明度、彩度、色相を制御する

Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — 明度、彩度、色相を制御する

説明

public Gmagick::modulateimage(float $brightness, float $saturation, float $hue): Gmagick

画像の明度、彩度、色相を制御します。 色相は、現在位置からの絶対回転角のパーセンテージで表します。 たとえば 50 の場合は反時計回りに 90 度の回転を表します。 また 150 の場合は時計回りの 90 度の回転、0 および 200 はともに 180 度の回転を表します。

パラメータ

brightness

画像の明度 (-100 から +100)。

saturation

画像の彩度 (-100 から +100)。

hue

画像の色相 (-100 から +100)。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


モーションブラーをシミュレートする

  • ≪ Gmagick::modulateimage
  • Gmagick::newimage ≫
  • PHP Manual
  • Gmagick
  • モーションブラーをシミュレートする

Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — モーションブラーをシミュレートする

説明

public Gmagick::motionblurimage(float $radius, float $sigma, float $angle): Gmagick

モーションブラーをシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、 Gmagick::motionblurimage() が適切な半径を自動的に設定します。 angle にはぼかしをかける角度を指定します。

パラメータ

radius

ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。

sigma

ガウス演算の標準偏差。ピクセル単位で指定します。

angle

この角度で効果を適用します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


新しい画像を作成する

  • ≪ Gmagick::motionblurimage
  • Gmagick::nextimage ≫
  • PHP Manual
  • Gmagick
  • 新しい画像を作成する

Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — 新しい画像を作成する

説明

public Gmagick::newimage(
int $width,
int $height,
string $background,
string $format = ?
): Gmagick

新しい画像を作成し、背景色を設定します。

パラメータ

width

新しい画像の幅。

height

新しい画像の高さ。

background

この画像で使う背景色 (浮動小数点数)。

format

画像フォーマット。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


次の画像に移動する

  • ≪ Gmagick::newimage
  • Gmagick::normalizeimage ≫
  • PHP Manual
  • Gmagick
  • 次の画像に移動する

Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — 次の画像に移動する

説明

public Gmagick::nextimage(): bool

画像リスト内の次の画像を Gmagick オブジェクトに関連付けます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。


カラー画像のコントラストを強調する

  • ≪ Gmagick::nextimage
  • Gmagick::oilpaintimage ≫
  • PHP Manual
  • Gmagick
  • カラー画像のコントラストを強調する

Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — カラー画像のコントラストを強調する

説明

public Gmagick::normalizeimage(int $channel = ?): Gmagick

カラー画像のコントラストを強調します。 ピクセルの色を、とりうる値の範囲全体に拡張します。

パラメータ

channel

どのチャネルを正規化するか。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


油絵をシミュレートする

  • ≪ Gmagick::normalizeimage
  • Gmagick::previousimage ≫
  • PHP Manual
  • Gmagick
  • 油絵をシミュレートする

Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — 油絵をシミュレートする

説明

public Gmagick::oilpaintimage( float $radius ): Gmagick

油絵風の効果を施すフィルタを適用します。 各ピクセルが、指定した半径内の周囲の中で最もよくあらわれる色に置き換えられます。

パラメータ

radius

近傍円の半径。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


オブジェクト内の前の画像に移動する

  • ≪ Gmagick::oilpaintimage
  • Gmagick::profileimage ≫
  • PHP Manual
  • Gmagick
  • オブジェクト内の前の画像に移動する

Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — オブジェクト内の前の画像に移動する

説明

public Gmagick::previousimage(): bool

画像リスト内の前の画像を Gmagick オブジェクトに関連付けます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のプロファイルを追加あるいは削除する

  • ≪ Gmagick::previousimage
  • Gmagick::quantizeimage ≫
  • PHP Manual
  • Gmagick
  • 画像のプロファイルを追加あるいは削除する

Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する

説明

public Gmagick::profileimage(string $name, string $profile): Gmagick

ICC、IPTC あるいは汎用のプロファイルを画像に追加あるいは削除します。 profile が null の場合は画像からプロファイルを削除し、 それ以外の場合は追加します。 name に *、profile に null を指定すると、画像からすべてのプロパティを削除します。

パラメータ

name

追加あるいは削除するプロファイルの名前。ICC、IPTC、あるいは generic。

profile

プロファイル。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


参照画像内の色を解析する

  • ≪ Gmagick::profileimage
  • Gmagick::quantizeimages ≫
  • PHP Manual
  • Gmagick
  • 参照画像内の色を解析する

Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — 参照画像内の色を解析する

説明

public Gmagick::quantizeimage(
int $numColors,
int $colorspace,
int $treeDepth,
bool $dither,
bool $measureError
): Gmagick

参照画像内の色を解析し、その画像を表すための色を固定の色数で選びます。 そのアルゴリズムの目標は、入力画像と出力画像の色の差を最小限に抑えながらも 処理時間を短くすることです。

パラメータ

numColors

色数。

colorspace

この色空間の中で色数を減らす。通常は RGBColorspace。

treeDepth

通常は、この整数値は 0 か 1 になります。 0 あるいは 1 を指定すると、Quantize に最適なツリーの深さとして Log4(number_colors) を選ばせます。 この深さのツリーは一般に、最小のメモリー消費で最大の計算速度を得られる最良の参照画像表現法になります。 色数が少ないなど、場合によっては Log4(number_colors) 以外の値が必要になることもあります。 色ツリーを完全に広げるには、この値を 8 にします。

dither

ゼロ以外の値を元の画像との間の違いに分配し、 対応する減色アルゴリズムを近傍ピクセルとのヒルベルト曲線に沿ったものにします。

measureError

ゼロ以外の値で、元画像と量子化した画像の違いを計測します。 この違いが、全体の量子化エラーになります。 エラーを判定するために、画像内の全ピクセルを計算し、 RGB 空間において参照画像と量子化語のピクセルの差を合計します。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像シーケンス内の色を解析する

  • ≪ Gmagick::quantizeimage
  • Gmagick::queryfontmetrics ≫
  • PHP Manual
  • Gmagick
  • 画像シーケンス内の色を解析する

Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — 画像シーケンス内の色を解析する

説明

public Gmagick::quantizeimages(
int $numColors,
int $colorspace,
int $treeDepth,
bool $dither,
bool $measureError
): Gmagick

画像シーケンス内の色を解析し、その画像を表すための色を固定の色数で選びます。 そのアルゴリズムの目標は、入力画像と出力画像の色の差を最小限に抑えながらも 処理時間を短くすることです。

パラメータ

numColors

色数。

colorspace

この色空間の中で色数を減らす。通常は RGBColorspace。

treeDepth

通常は、この整数値は 0 か 1 になります。 0 あるいは 1 を指定すると、Quantize に最適なツリーの深さとして Log4(number_colors) を選ばせます。 この深さのツリーは一般に、最小のメモリー消費で最大の計算速度を得られる最良の参照画像表現法になります。 色数が少ないなど、場合によっては Log4(number_colors) 以外の値が必要になることもあります。 色ツリーを完全に広げるには、この値を 8 にします。

dither

ゼロ以外の値を元の画像との間の違いに分配し、 対応する減色アルゴリズムを近傍ピクセルとのヒルベルト曲線に沿ったものにします。

measureError

ゼロ以外の値で、元画像と量子化した画像の違いを計測します。 この違いが、全体の量子化エラーになります。 エラーを判定するために、画像内の全ピクセルを計算し、 RGB 空間において参照画像と量子化語のピクセルの差を合計します。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


フォントメトリクスを表す配列を返す

  • ≪ Gmagick::quantizeimages
  • Gmagick::queryfonts ≫
  • PHP Manual
  • Gmagick
  • フォントメトリクスを表す配列を返す

Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す

説明

public Gmagick::queryfontmetrics(GmagickDraw $draw, string $text): array

MagickQueryFontMetrics() は、フォントメトリクスを表す多次元配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


設定したフォントを返す

  • ≪ Gmagick::queryfontmetrics
  • Gmagick::queryformats ≫
  • PHP Manual
  • Gmagick
  • 設定したフォントを返す

Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — 設定したフォントを返す

説明

public Gmagick::queryfonts(string $pattern = "*"): array

設定したフォントを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick がサポートするフォーマットを返す

  • ≪ Gmagick::queryfonts
  • Gmagick::radialblurimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick がサポートするフォーマットを返す

Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Gmagick がサポートするフォーマットを返す

説明

public Gmagick::queryformats(string $pattern = "*"): array

Gmagick がサポートするフォーマットを返します。

パラメータ

pattern

パターンを含む文字列へのポインタを指定します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像にラジアルブラーを施す

  • ≪ Gmagick::queryformats
  • Gmagick::raiseimage ≫
  • PHP Manual
  • Gmagick
  • 画像にラジアルブラーを施す

Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — 画像にラジアルブラーを施す

説明

public Gmagick::radialblurimage(float $angle, int $channel = Gmagick::CHANNEL_DEFAULT): Gmagick

画像にラジアルブラーを施します。

パラメータ

angle

ラジアルブラーの角度。

channel

関連するチャネル。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


三次元のボタン風の効果をシミュレートする

  • ≪ Gmagick::radialblurimage
  • Gmagick::read ≫
  • PHP Manual
  • Gmagick
  • 三次元のボタン風の効果をシミュレートする

Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする

説明

public Gmagick::raiseimage(
int $width,
int $height,
int $x,
int $y,
bool $raise
): Gmagick

画像の輪郭を明るくしたり暗くしたりすることによって、 三次元のボタン風の効果をシミュレートします。 raise_info のメンバ width および height が、 垂直方向および水平方向の効果の輪郭を定義します。

パラメータ

width

明るくする範囲の幅。

height

明るくする範囲の高さ。

x

X 座標。

y

Y 座標。

raise

ゼロ以外の値を指定すると三次元の引き上げ効果、ゼロの場合は引き下げ効果。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


ファイルから画像を読み込む

  • ≪ Gmagick::raiseimage
  • Gmagick::readimage ≫
  • PHP Manual
  • Gmagick
  • ファイルから画像を読み込む

Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — ファイルから画像を読み込む

説明

public Gmagick::read(string $filename): Gmagick

ファイルから画像を読み込みます。

パラメータ

filename

画像ファイル名。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


ファイルから画像を読み込む

  • ≪ Gmagick::read
  • Gmagick::readimageblob ≫
  • PHP Manual
  • Gmagick
  • ファイルから画像を読み込む

Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — ファイルから画像を読み込む

説明

public Gmagick::readimage(string $filename): Gmagick

ファイルから画像を読み込みます。

パラメータ

filename

画像ファイル名。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


バイナリ文字列から画像を読み込む

  • ≪ Gmagick::readimage
  • Gmagick::readimagefile ≫
  • PHP Manual
  • Gmagick
  • バイナリ文字列から画像を読み込む

Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — バイナリ文字列から画像を読み込む

説明

public Gmagick::readimageblob(string $imageContents, string $filename = ?): Gmagick

バイナリ文字列から画像を読み込みます。

パラメータ

imageContents

画像の内容。

filename

画像ファイル名。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


オープンしているファイルハンドルから画像を読み込む

  • ≪ Gmagick::readimageblob
  • Gmagick::reducenoiseimage ≫
  • PHP Manual
  • Gmagick
  • オープンしているファイルハンドルから画像を読み込む

Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む

説明

public Gmagick::readimagefile(resource $fp, string $filename = ?): Gmagick

オープンしているファイルハンドルから画像を読み込みます。

パラメータ

fp

ファイルディスクリプタ。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の輪郭をなめらかにする

  • ≪ Gmagick::readimagefile
  • Gmagick::removeimage ≫
  • PHP Manual
  • Gmagick
  • 画像の輪郭をなめらかにする

Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする

説明

public Gmagick::reducenoiseimage(float $radius): Gmagick

画像の輪郭をなめらかにします。縁の情報は保持します。 各ピクセルの内容を近傍の一番近い値で置き換えるというアルゴリズムです。 近傍は半径で定義します。radius に 0 を指定すると、 Gmagick::reducenoiseimage() が適切な半径を自動的に設定します。

パラメータ

radius

近傍ピクセルの半径。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像リストから画像を削除する

  • ≪ Gmagick::reducenoiseimage
  • Gmagick::removeimageprofile ≫
  • PHP Manual
  • Gmagick
  • 画像リストから画像を削除する

Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — 画像リストから画像を削除する

説明

public Gmagick::removeimage(): Gmagick

画像リストから画像を削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


指定した名前の画像プロファイルを削除して返す

  • ≪ Gmagick::removeimage
  • Gmagick::resampleimage ≫
  • PHP Manual
  • Gmagick
  • 指定した名前の画像プロファイルを削除して返す

Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す

説明

public Gmagick::removeimageprofile(string $name): string

指定した名前の画像プロファイルを削除して返します。

パラメータ

name

返すプロファイルの名前。ICC、IPTC あるいは generic。

戻り値

指定した名前のプロファイルを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像を指定した解像度にリサンプリングする

  • ≪ Gmagick::removeimageprofile
  • Gmagick::resizeimage ≫
  • PHP Manual
  • Gmagick
  • 画像を指定した解像度にリサンプリングする

Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする

説明

public Gmagick::resampleimage(
float $xResolution,
float $yResolution,
int $filter,
float $blur
): Gmagick

画像を指定した解像度にリサンプリングします。

パラメータ

xResolution

新しい画像の x 方向の解像度。

yResolution

新しい画像の y 方向の解像度。

filter

利用するフィルタ。

blur

blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のサイズを変更する

  • ≪ Gmagick::resampleimage
  • Gmagick::rollimage ≫
  • PHP Manual
  • Gmagick
  • 画像のサイズを変更する

Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — 画像のサイズを変更する

説明

public Gmagick::resizeimage(
int $width,
int $height,
int $filter,
float $blur,
bool $fit = false
): Gmagick

指定した大きさとフィルタで、画像のサイズを変更します。

パラメータ

width

画像の幅。

height

画像の高さ。

filter

利用するフィルタ。

blur

blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像を補正する

  • ≪ Gmagick::resizeimage
  • Gmagick::rotateimage ≫
  • PHP Manual
  • Gmagick
  • 画像を補正する

Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — 画像を補正する

説明

public Gmagick::rollimage(int $x, int $y): Gmagick

x および y を指定して画像を補正します。

パラメータ

x

x オフセット。

y

y オフセット。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像を回転する

  • ≪ Gmagick::rollimage
  • Gmagick::scaleimage ≫
  • PHP Manual
  • Gmagick
  • 画像を回転する

Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — 画像を回転する

説明

public Gmagick::rotateimage(mixed $color, float $degrees): Gmagick

指定した角度だけ画像を回転させます。回転によって生じる空き領域は、 背景色で埋められます。

パラメータ

color

背景色。

degrees

画像を回転させる度数。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のサイズを変更する

  • ≪ Gmagick::rotateimage
  • Gmagick::separateimagechannel ≫
  • PHP Manual
  • Gmagick
  • 画像のサイズを変更する

Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — 画像のサイズを変更する

説明

public Gmagick::scaleimage(int $width, int $height, bool $fit = false): Gmagick

画像のサイズを指定した大きさに変更します。 パラメータに 0 を指定すると、そのパラメータを自動的に計算します。

パラメータ

width

変更後の画像の幅。

height

変更後の画像の高さ。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像からチャネルを分離する

  • ≪ Gmagick::scaleimage
  • Gmagick::setCompressionQuality ≫
  • PHP Manual
  • Gmagick
  • 画像からチャネルを分離する

Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — 画像からチャネルを分離する

説明

public Gmagick::separateimagechannel(int $channel): Gmagick

画像からチャネルを分離し、グレースケール画像を返します。 channel には、画像の各ピクセルの特定の色コンポーネントを指定します。

パラメータ

channel

チャンネル 定数のうちの一つ。 (Gmagick::CHANNEL_*)

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


オブジェクトのデフォルトの圧縮クオリティを設定する

  • ≪ Gmagick::separateimagechannel
  • Gmagick::setfilename ≫
  • PHP Manual
  • Gmagick
  • オブジェクトのデフォルトの圧縮クオリティを設定する

Gmagick::setCompressionQuality

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する

説明

Gmagick::setCompressionQuality( int $quality = 75 ): Gmagick

オブジェクトのデフォルトの圧縮クオリティを設定します。

パラメータ

quality

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。

例

例1 Gmagick::setCompressionQuality()

<?php
$gm = new Gmagick();
$gm->read("magick:rose");
$gm->setCompressionQuality(2);
?>


画像を読み書きする前にファイル名を設定する

  • ≪ Gmagick::setCompressionQuality
  • Gmagick::setimagebackgroundcolor ≫
  • PHP Manual
  • Gmagick
  • 画像を読み書きする前にファイル名を設定する

Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する

説明

public Gmagick::setfilename(string $filename): Gmagick

画像を読み書きする前にファイル名を設定します。

パラメータ

filename

画像ファイル名。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の背景色を設定する

  • ≪ Gmagick::setfilename
  • Gmagick::setimageblueprimary ≫
  • PHP Manual
  • Gmagick
  • 画像の背景色を設定する

Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — 画像の背景色を設定する

説明

public Gmagick::setimagebackgroundcolor(GmagickPixel $color): Gmagick

画像の背景色を設定します。

パラメータ

color

画像の背景色。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


青が一番強い点を設定する

  • ≪ Gmagick::setimagebackgroundcolor
  • Gmagick::setimagebordercolor ≫
  • PHP Manual
  • Gmagick
  • 青が一番強い点を設定する

Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — 青が一番強い点を設定する

説明

public Gmagick::setimageblueprimary(float $x, float $y): Gmagick

青が一番強い点を設定します。

パラメータ

x

青が一番強い点の x 座標。

y

青が一番強い点の y 座標。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の枠線の色を設定する

  • ≪ Gmagick::setimageblueprimary
  • Gmagick::setimagechanneldepth ≫
  • PHP Manual
  • Gmagick
  • 画像の枠線の色を設定する

Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — 画像の枠線の色を設定する

説明

public Gmagick::setimagebordercolor(GmagickPixel $color): Gmagick

画像の枠線の色を設定します。

パラメータ

color

画像の前景色。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


特定の画像チャネルの深度を設定する

  • ≪ Gmagick::setimagebordercolor
  • Gmagick::setimagecolorspace ≫
  • PHP Manual
  • Gmagick
  • 特定の画像チャネルの深度を設定する

Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する

説明

public Gmagick::setimagechanneldepth(int $channel, int $depth): Gmagick

特定の画像チャネルの深度を設定します。

パラメータ

channel

チャンネル 定数のうちの一つ。 (Gmagick::CHANNEL_*)

depth

深度を表すビット数。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の色空間を設定する

  • ≪ Gmagick::setimagechanneldepth
  • Gmagick::setimagecompose ≫
  • PHP Manual
  • Gmagick
  • 画像の色空間を設定する

Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — 画像の色空間を設定する

説明

public Gmagick::setimagecolorspace(int $colorspace): Gmagick

画像の色空間を設定します。

パラメータ

colorspace

色空間 定数のうちの一つ。 (Gmagick::COLORSPACE_*)

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の合成演算子を設定する

  • ≪ Gmagick::setimagecolorspace
  • Gmagick::setimagedelay ≫
  • PHP Manual
  • Gmagick
  • 画像の合成演算子を設定する

Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — 画像の合成演算子を設定する

説明

public Gmagick::setimagecompose(int $composite): Gmagick

画像の合成演算子を設定します。

パラメータ

composite

画像の合成演算子。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の遅延を設定する

  • ≪ Gmagick::setimagecompose
  • Gmagick::setimagedepth ≫
  • PHP Manual
  • Gmagick
  • 画像の遅延を設定する

Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — 画像の遅延を設定する

説明

public Gmagick::setimagedelay(int $delay): Gmagick

画像の遅延を設定します。

パラメータ

delay

画像の遅延を 1/100 秒単位で指定します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の深度を設定する

  • ≪ Gmagick::setimagedelay
  • Gmagick::setimagedispose ≫
  • PHP Manual
  • Gmagick
  • 画像の深度を設定する

Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — 画像の深度を設定する

説明

public Gmagick::setimagedepth(int $depth): Gmagick

画像の深度を設定します。

パラメータ

depth

画像の深度 (ビット)。8、16 あるいは 32。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の配置方法を設定する

  • ≪ Gmagick::setimagedepth
  • Gmagick::setimagefilename ≫
  • PHP Manual
  • Gmagick
  • 画像の配置方法を設定する

Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — 画像の配置方法を設定する

説明

public Gmagick::setimagedispose(int $disposeType): Gmagick

画像の配置方法を設定します。

パラメータ

disposeType

画像の配置方法。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


シーケンス内の特定の画像のファイル名を設定する

  • ≪ Gmagick::setimagedispose
  • Gmagick::setimageformat ≫
  • PHP Manual
  • Gmagick
  • シーケンス内の特定の画像のファイル名を設定する

Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する

説明

public Gmagick::setimagefilename(string $filename): Gmagick

シーケンス内の特定の画像のファイル名を設定します。

パラメータ

filename

画像ファイル名。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


特定の画像のフォーマットを設定する

  • ≪ Gmagick::setimagefilename
  • Gmagick::setimagegamma ≫
  • PHP Manual
  • Gmagick
  • 特定の画像のフォーマットを設定する

Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — 特定の画像のフォーマットを設定する

説明

public Gmagick::setimageformat(string $imageFormat): Gmagick

シーケンス内の特定の画像のフォーマットを設定します。

パラメータ

imageFormat

画像のフォーマット。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のガンマを設定する

  • ≪ Gmagick::setimageformat
  • Gmagick::setimagegreenprimary ≫
  • PHP Manual
  • Gmagick
  • 画像のガンマを設定する

Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — 画像のガンマを設定する

説明

public Gmagick::setimagegamma(float $gamma): Gmagick

画像のガンマを設定します。

パラメータ

gamma

画像のガンマ。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


緑が一番強い点を設定する

  • ≪ Gmagick::setimagegamma
  • Gmagick::setimageindex ≫
  • PHP Manual
  • Gmagick
  • 緑が一番強い点を設定する

Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — 緑が一番強い点を設定する

説明

public Gmagick::setimagegreenprimary(float $x, float $y): Gmagick

緑が一番強い点を設定します。

パラメータ

x

緑が一番強い点の x 座標。

y

緑が一番強い点の y 座標。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

  • ≪ Gmagick::setimagegreenprimary
  • Gmagick::setimageinterlacescheme ≫
  • PHP Manual
  • Gmagick
  • 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

説明

public Gmagick::setimageindex(int $index): Gmagick

画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定します。

パラメータ

index

シーン番号。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のインターレース手法を設定する

  • ≪ Gmagick::setimageindex
  • Gmagick::setimageiterations ≫
  • PHP Manual
  • Gmagick
  • 画像のインターレース手法を設定する

Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する

説明

public Gmagick::setimageinterlacescheme(int $interlace): Gmagick

画像のインターレース手法を設定します。

パラメータ

interlace

インターレース 定数のうちの一つ。 (Gmagick::INTERLACE_*)

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の反復を設定する

  • ≪ Gmagick::setimageinterlacescheme
  • Gmagick::setimageprofile ≫
  • PHP Manual
  • Gmagick
  • 画像の反復を設定する

Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — 画像の反復を設定する

説明

public Gmagick::setimageiterations(int $iterations): Gmagick

画像の反復を設定します。

パラメータ

iterations

画像の遅延を 1/100 秒単位で指定します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

  • ≪ Gmagick::setimageiterations
  • Gmagick::setimageredprimary ≫
  • PHP Manual
  • Gmagick
  • 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

説明

public Gmagick::setimageprofile(string $name, string $profile): Gmagick

指定した名前の画像プロファイルを Gmagick オブジェクトに追加します。 同じ名前のプロファイルが存在する場合は、それを置き換えます。 このメソッドは Gmagick::profileImage() メソッドとは異なり、 CMS カラープロファイルは適用しません。

パラメータ

name

追加あるいは削除するプロファイルの名前。ICC、IPTC あるいは generic。

profile

プロファイル。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


赤が一番強い点を設定する

  • ≪ Gmagick::setimageprofile
  • Gmagick::setimagerenderingintent ≫
  • PHP Manual
  • Gmagick
  • 赤が一番強い点を設定する

Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — 赤が一番強い点を設定する

説明

public Gmagick::setimageredprimary(float $x, float $y): Gmagick

赤が一番強い点を設定します。

パラメータ

x

赤が一番強い点の x 座標。

y

赤が一番強い点の y 座標。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のレンダリング方向を設定する

  • ≪ Gmagick::setimageredprimary
  • Gmagick::setimageresolution ≫
  • PHP Manual
  • Gmagick
  • 画像のレンダリング方向を設定する

Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する

説明

public Gmagick::setimagerenderingintent(int $rendering_intent): Gmagick

画像のレンダリング方向を設定します。

パラメータ

rendering_intent

レンダリング方向 の定数のうちの一つ。 (Gmagick::RENDERINGINTENT_*)

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の解像度を設定する

  • ≪ Gmagick::setimagerenderingintent
  • Gmagick::setimagescene ≫
  • PHP Manual
  • Gmagick
  • 画像の解像度を設定する

Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — 画像の解像度を設定する

説明

public Gmagick::setimageresolution(float $xResolution, float $yResolution): Gmagick

画像の解像度を設定します。

パラメータ

xResolution

x 方向の解像度。

yResolution

y 方向の解像度。

戻り値

成功した場合に Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のシーンを設定する

  • ≪ Gmagick::setimageresolution
  • Gmagick::setimagetype ≫
  • PHP Manual
  • Gmagick
  • 画像のシーンを設定する

Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — 画像のシーンを設定する

説明

public Gmagick::setimagescene(int $scene): Gmagick

画像のシーンを設定します。

パラメータ

scene

画像のシーン番号。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の型を設定する

  • ≪ Gmagick::setimagescene
  • Gmagick::setimageunits ≫
  • PHP Manual
  • Gmagick
  • 画像の型を設定する

Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — 画像の型を設定する

説明

public Gmagick::setimagetype(int $imgType): Gmagick

画像の型を設定します。

パラメータ

imgType

画像の型 の定数のうちのひとつ。 (Gmagick::IMGTYPE_*)

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の解像度の単位を設定する

  • ≪ Gmagick::setimagetype
  • Gmagick::setimagewhitepoint ≫
  • PHP Manual
  • Gmagick
  • 画像の解像度の単位を設定する

Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — 画像の解像度の単位を設定する

説明

public Gmagick::setimageunits(int $resolution): Gmagick

画像の解像度の単位を設定します。

パラメータ

resolution

画像の解像度の単位。Undefinedresolution、PixelsPerInchResolution あるいは PixelsPerCentimeterResolution。 解像度 の定数のうちの一つ。 (Gmagick::RESOLUTION_*)

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の色度が白い点を設定する

  • ≪ Gmagick::setimageunits
  • Gmagick::setsamplingfactors ≫
  • PHP Manual
  • Gmagick
  • 画像の色度が白い点を設定する

Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する

説明

public Gmagick::setimagewhitepoint(float $x, float $y): Gmagick

画像の色度が白い点を設定します。

パラメータ

x

白い点の x 座標。

y

白い点の y 座標。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のサンプリング係数を設定する

  • ≪ Gmagick::setimagewhitepoint
  • Gmagick::setsize ≫
  • PHP Manual
  • Gmagick
  • 画像のサンプリング係数を設定する

Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する

説明

public Gmagick::setsamplingfactors(array $factors): Gmagick

画像のサンプリング係数を設定します。

パラメータ

factors

各色コンポーネントのサンプリング係数を表す float 型の値の配列 (RGB 順)。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick オブジェクトのサイズを設定する

  • ≪ Gmagick::setsamplingfactors
  • Gmagick::shearimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick オブジェクトのサイズを設定する

Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Gmagick オブジェクトのサイズを設定する

説明

public Gmagick::setsize(int $columns, int $rows): Gmagick

Gmagick オブジェクトのサイズを設定します。
Gmagick::COLORSPACE_RGB や
Gmagick::COLORSPACE_GRAY、
Gmagick::COLORSPACE_CMYK
といった生の画像フォーマットを読み込む前に設定します。

パラメータ

columns

ピクセル数で指定する幅。

rows

ピクセル数で指定する高さ。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


平行四辺形を作成する

  • ≪ Gmagick::setsize
  • Gmagick::solarizeimage ≫
  • PHP Manual
  • Gmagick
  • 平行四辺形を作成する

Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — 平行四辺形を作成する

説明

public Gmagick::shearimage(mixed $color, float $xShear, float $yShear): Gmagick

画像を X 軸方向あるいは Y 軸方向に押しつぶし、平行四辺形を作成します。 X 方向に押しつぶすと X 軸方向にスライドし、Y 方向に押しつぶすと Y 軸方向にスライドします。押しつぶす量は、角度で指定します。 X 方向に押しつぶす場合、x_shear は Y 軸からの相対角度となります。 同様に、Y 方向に押しつぶす場合は y_shear が X 軸からの相対角度となります。 変形によってできた空白部分は、背景色で埋められます。

パラメータ

color

背景色。

xShear

x 軸方向に押しつぶす角度。

yShear

y 軸方向に押しつぶす角度。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像にソラリゼーション効果を適用する

  • ≪ Gmagick::shearimage
  • Gmagick::spreadimage ≫
  • PHP Manual
  • Gmagick
  • 画像にソラリゼーション効果を適用する

Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する

説明

public Gmagick::solarizeimage(int $threshold): Gmagick

画像に特殊効果を施し、 印画紙の特定の箇所の露光時間を長くしたような画像になります。 threshold は 0 から QuantumRange までの値で、 ソラリゼーションの効き具合を指定します。

パラメータ

threshold

ソラリゼーションの効き具合を指定します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


ブロック内の各ピクセルをランダムに移動する

  • ≪ Gmagick::solarizeimage
  • Gmagick::stripimage ≫
  • PHP Manual
  • Gmagick
  • ブロック内の各ピクセルをランダムに移動する

Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する

説明

public Gmagick::spreadimage(float $radius): Gmagick

radius パラメータで定義したブロック内の各ピクセルを、 ランダムに移動させます。

パラメータ

radius

この範囲の近くにあるランダムなピクセルを選びます。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像からすべてのプロパティやコメントを除去する

  • ≪ Gmagick::spreadimage
  • Gmagick::swirlimage ≫
  • PHP Manual
  • Gmagick
  • 画像からすべてのプロパティやコメントを除去する

Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する

説明

public Gmagick::stripimage(): Gmagick

画像からすべてのプロパティやコメントを除去します。

パラメータ

この関数にはパラメータはありません。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の中心から、ピクセルを渦巻状にする

  • ≪ Gmagick::stripimage
  • Gmagick::thumbnailimage ≫
  • PHP Manual
  • Gmagick
  • 画像の中心から、ピクセルを渦巻状にする

Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする

説明

public Gmagick::swirlimage(float $degrees): Gmagick

画像の中心から、ピクセルを渦巻状にします。 degrees は個々のピクセルが移動する弧の量を表します。 degrees を 1 から 360 まで変化させると、劇的な効果が得られます。

パラメータ

degrees

渦巻効果の程度。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像のサイズを変更する

  • ≪ Gmagick::swirlimage
  • Gmagick::trimimage ≫
  • PHP Manual
  • Gmagick
  • 画像のサイズを変更する

Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — 画像のサイズを変更する

説明

public Gmagick::thumbnailimage(int $width, int $height, bool $fit = false): Gmagick

画像のサイズを指定したものに変更し、関連付けられたプロパティをすべて削除します。 ウェブ上での表示に適した小さなサムネイル画像を作成します。 三番目のパラメータに true を指定すると、columns や rows にそれぞれの最大値を使用します。両方のパラメータが、 マッチするまであるいは指定したパラメータより小さくなるまで縮小されます。

パラメータ

width

画像の幅。

height

画像の高さ。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


画像の輪郭を削除する

  • ≪ Gmagick::thumbnailimage
  • Gmagick::write ≫
  • PHP Manual
  • Gmagick
  • 画像の輪郭を削除する

Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — 画像の輪郭を削除する

説明

public Gmagick::trimimage(float $fuzz): Gmagick

画像の背景色と同じ色の輪郭を削除します。

パラメータ

fuzz

デフォルトでは、対象の色は特定のピクセルの色とまったく同じでなければなりません。 しかし、ふたつの色が微妙に異なることもよくあります。 画像の fuzz メンバは、どの程度の色を「同じ色」とみなすかを表します。 このパラメータは、量の範囲の変化を表します。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


Gmagick::writeimage のエイリアス

  • ≪ Gmagick::trimimage
  • Gmagick::writeimage ≫
  • PHP Manual
  • Gmagick
  • Gmagick::writeimage のエイリアス

Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Gmagick::writeimage() のエイリアス

説明

このメソッドは次のメソッドのエイリアスです。 Gmagick::writeimage()


画像を指定したファイル名で書き出す

  • ≪ Gmagick::write
  • GmagickDraw ≫
  • PHP Manual
  • Gmagick
  • 画像を指定したファイル名で書き出す

Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — 画像を指定したファイル名で書き出す

説明

public Gmagick::writeimage(string $filename, bool $all_frames = false): Gmagick

画像を指定したファイル名で書き出します。filename が null の場合は、 Gmagick::readimage() あるいは Gmagick::setimagefilename() で設定したファイル名で書き出します。

パラメータ

filename

画像ファイル名。

戻り値

Gmagick オブジェクトを返します。

エラー / 例外

エラー時に GmagickException をスローします。


GmagickDraw クラス

(PECL gmagick >= Unknown)

はじめに

クラス概要

class GmagickDraw {
/* メソッド */
public annotate(float $x, float $y, string $text): GmagickDraw
public arc(
float $sx,
float $sy,
float $ex,
float $ey,
float $sd,
float $ed
): GmagickDraw
public bezier(array $coordinate_array): GmagickDraw
public ellipse(
float $ox,
float $oy,
float $rx,
float $ry,
float $start,
float $end
): GmagickDraw
public getfillcolor(): GmagickPixel
public getfillopacity(): float
public getfont(): mixed
public getfontsize(): float
public getfontstyle(): int
public getfontweight(): int
public getstrokecolor(): GmagickPixel
public getstrokeopacity(): float
public getstrokewidth(): float
public gettextdecoration(): int
public gettextencoding(): mixed
public line(
float $sx,
float $sy,
float $ex,
float $ey
): GmagickDraw
public point(float $x, float $y): GmagickDraw
public polygon(array $coordinates): GmagickDraw
public polyline(array $coordinate_array): GmagickDraw
public rectangle(
float $x1,
float $y1,
float $x2,
float $y2
): GmagickDraw
public rotate(float $degrees): GmagickDraw
public roundrectangle(
float $x1,
float $y1,
float $x2,
float $y2,
float $rx,
float $ry
): GmagickDraw
public scale(float $x, float $y): GmagickDraw
public setfillcolor(mixed $color): GmagickDraw
public setfillopacity(float $fill_opacity): GmagickDraw
public setfont(string $font): GmagickDraw
public setfontsize(float $pointsize): GmagickDraw
public setfontstyle(int $style): GmagickDraw
public setfontweight(int $weight): GmagickDraw
public setstrokecolor(mixed $color): GmagickDraw
public setstrokeopacity(float $stroke_opacity): GmagickDraw
public setstrokewidth(float $width): GmagickDraw
public settextdecoration(int $decoration): GmagickDraw
public settextencoding(string $encoding): GmagickDraw
}

目次

  • GmagickDraw::annotate — 画像の上にテキストを描画する
  • GmagickDraw::arc — 弧を描く
  • GmagickDraw::bezier — ベジエ曲線を描く
  • GmagickDraw::ellipse — 楕円を画像上に描く
  • GmagickDraw::getfillcolor — 塗りつぶし色を返す
  • GmagickDraw::getfillopacity — 描画に使う不透明度を返す
  • GmagickDraw::getfont — フォントを返す
  • GmagickDraw::getfontsize — フォントのポイント数を返す
  • GmagickDraw::getfontstyle — フォントスタイルを返す
  • GmagickDraw::getfontweight — フォントのウェイトを返す
  • GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す
  • GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す
  • GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す
  • GmagickDraw::gettextdecoration — テキストのデコレーションを返す
  • GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す
  • GmagickDraw::line — 直線を描く
  • GmagickDraw::point — 点を描く
  • GmagickDraw::polygon — 多角形を描く
  • GmagickDraw::polyline — ポリラインを描く
  • GmagickDraw::rectangle — 矩形を描く
  • GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する
  • GmagickDraw::roundrectangle — 角が丸い矩形を描く
  • GmagickDraw::scale — 倍率を調整する
  • GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する
  • GmagickDraw::setfillopacity — 不透明度を設定する
  • GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する
  • GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する
  • GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する
  • GmagickDraw::setfontweight — フォントのウェイトを設定する
  • GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する
  • GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する
  • GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する
  • GmagickDraw::settextdecoration — デコレーションを設定する
  • GmagickDraw::settextencoding — テキストのコードセットを設定する


画像の上にテキストを描画する

  • ≪ GmagickDraw
  • GmagickDraw::arc ≫
  • PHP Manual
  • GmagickDraw
  • 画像の上にテキストを描画する

GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — 画像の上にテキストを描画する

説明

public GmagickDraw::annotate(float $x, float $y, string $text): GmagickDraw

画像の上にテキストを描画します。

パラメータ

x

テキストの左端の x 座標。

y

テキストのベースラインの y 座標。

text

描画するテキスト。

戻り値

GmagickDraw オブジェクトを返します。


弧を描く

  • ≪ GmagickDraw::annotate
  • GmagickDraw::bezier ≫
  • PHP Manual
  • GmagickDraw
  • 弧を描く

GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — 弧を描く

説明

public GmagickDraw::arc(
float $sx,
float $sy,
float $ex,
float $ey,
float $sd,
float $ed
): GmagickDraw

指定した矩形内に収まる弧を、画像上に描きます。

パラメータ

sx

矩形の開始位置の x 座標。

sy

矩形の開始位置の y 座標。

ex

矩形の終了位置の x 座標。

ey

矩形の終了位置の y 座標。

sd

開始角度。

ed

終了角度。

戻り値

GmagickDraw オブジェクトを返します。


ベジエ曲線を描く

  • ≪ GmagickDraw::arc
  • GmagickDraw::ellipse ≫
  • PHP Manual
  • GmagickDraw
  • ベジエ曲線を描く

GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — ベジエ曲線を描く

説明

public GmagickDraw::bezier(array $coordinate_array): GmagickDraw

指定した点を通るベジエ曲線を画像上に描きます。

パラメータ

coordinate_array

座標の配列。

戻り値

GmagickDraw オブジェクトを返します。


楕円を画像上に描く

  • ≪ GmagickDraw::bezier
  • GmagickDraw::getfillcolor ≫
  • PHP Manual
  • GmagickDraw
  • 楕円を画像上に描く

GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — 楕円を画像上に描く

説明

public GmagickDraw::ellipse(
float $ox,
float $oy,
float $rx,
float $ry,
float $start,
float $end
): GmagickDraw

楕円を画像上に描きます。

パラメータ

ox

原点の x 座標。

oy

原点の y 座標。

rx

x 方向の半径。

ry

y 方向の半径。

start

開始角度。

end

終了角度。

戻り値

GmagickDraw オブジェクトを返します。


塗りつぶし色を返す

  • ≪ GmagickDraw::ellipse
  • GmagickDraw::getfillopacity ≫
  • PHP Manual
  • GmagickDraw
  • 塗りつぶし色を返す

GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — 塗りつぶし色を返す

説明

public GmagickDraw::getfillcolor(): GmagickPixel

オブジェクトを塗りつぶすときに使う色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトを塗りつぶすときに使う色の GmagickPixel を返します。


描画に使う不透明度を返す

  • ≪ GmagickDraw::getfillcolor
  • GmagickDraw::getfont ≫
  • PHP Manual
  • GmagickDraw
  • 描画に使う不透明度を返す

GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — 描画に使う不透明度を返す

説明

public GmagickDraw::getfillopacity(): float

描画に使う不透明度を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

塗りつぶしの色やテクスチャに使う不透明度を返します。完全に不透明な状態が 1.0 になります。


フォントを返す

  • ≪ GmagickDraw::getfillopacity
  • GmagickDraw::getfontsize ≫
  • PHP Manual
  • GmagickDraw
  • フォントを返す

GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — フォントを返す

説明

public GmagickDraw::getfont(): mixed

テキストのアノテーションで使うフォントを表す文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に文字列を返します。フォントが設定されていない場合は false を返します。


フォントのポイント数を返す

  • ≪ GmagickDraw::getfont
  • GmagickDraw::getfontstyle ≫
  • PHP Manual
  • GmagickDraw
  • フォントのポイント数を返す

GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — フォントのポイント数を返す

説明

public GmagickDraw::getfontsize(): float

テキストのアノテーションで使うフォントのポイント数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の GmagickDraw オブジェクトに関連づけられたフォントのサイズを返します。


フォントスタイルを返す

  • ≪ GmagickDraw::getfontsize
  • GmagickDraw::getfontweight ≫
  • PHP Manual
  • GmagickDraw
  • フォントスタイルを返す

GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — フォントスタイルを返す

説明

public GmagickDraw::getfontstyle(): int

テキストのアノテーションで使うフォントのスタイルを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

GmagickDraw オブジェクトに関連づけられたフォントスタイル定数 (STYLE_) を返します。 スタイルが設定されていない場合は 0 を返します。


フォントのウェイトを返す

  • ≪ GmagickDraw::getfontstyle
  • GmagickDraw::getstrokecolor ≫
  • PHP Manual
  • GmagickDraw
  • フォントのウェイトを返す

GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — フォントのウェイトを返す

説明

public GmagickDraw::getfontweight(): int

テキストのアノテーションで使うフォントのウェイトを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に整数値を返します。ウェイトが設定されていない場合は 0 を返します。


オブジェクトの輪郭の描画に使う色を返す

  • ≪ GmagickDraw::getfontweight
  • GmagickDraw::getstrokeopacity ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う色を返す

GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す

説明

public GmagickDraw::getstrokecolor(): GmagickPixel

オブジェクトの輪郭の描画に使う色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

色を表す GmagickPixel オブジェクトを返します。


オブジェクトの輪郭の不透明度を返す

  • ≪ GmagickDraw::getstrokecolor
  • GmagickDraw::getstrokewidth ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の不透明度を返す

GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す

説明

public GmagickDraw::getstrokeopacity(): float

オブジェクトの輪郭の不透明度を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

不透明度を表す float 型の数値を返します。


オブジェクトの輪郭の描画に使う線の幅を返す

  • ≪ GmagickDraw::getstrokeopacity
  • GmagickDraw::gettextdecoration ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う線の幅を返す

GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す

説明

public GmagickDraw::getstrokewidth(): float

オブジェクトの輪郭の描画に使う線の幅を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

線の幅を表す float 型の値を返します。


テキストのデコレーションを返す

  • ≪ GmagickDraw::getstrokewidth
  • GmagickDraw::gettextencoding ≫
  • PHP Manual
  • GmagickDraw
  • テキストのデコレーションを返す

GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — テキストのデコレーションを返す

説明

public GmagickDraw::gettextdecoration(): int

テキストのアノテーションに適用するデコレーションを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

DECORATION_ 定数のいずれかを返します。デコレーションが設定されていない場合は 0 を返します。


テキストのアノテーションで使うコードセットを返す

  • ≪ GmagickDraw::gettextdecoration
  • GmagickDraw::line ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うコードセットを返す

GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す

説明

public GmagickDraw::gettextencoding(): mixed

テキストのアノテーションで使うコードセットを表す文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

コードセットを表す文字列を返します。 エンコーディングが設定されていない場合は false を返します。


直線を描く

  • ≪ GmagickDraw::gettextencoding
  • GmagickDraw::point ≫
  • PHP Manual
  • GmagickDraw
  • 直線を描く

GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — 直線を描く

説明

public GmagickDraw::line(
float $sx,
float $sy,
float $ex,
float $ey
): GmagickDraw

現在の描画色、不透明度、線幅を使って画像上に直線を描きます。

パラメータ

sx

開始位置の x 座標。

sy

開始位置の y 座標。

ex

終了位置の x 座標。

ey

終了位置の y 座標。

戻り値

GmagickDraw オブジェクトを返します。


点を描く

  • ≪ GmagickDraw::line
  • GmagickDraw::polygon ≫
  • PHP Manual
  • GmagickDraw
  • 点を描く

GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — 点を描く

説明

public GmagickDraw::point(float $x, float $y): GmagickDraw

現在の描画色と太さを使って、指定した座標に点を描きます。

パラメータ

x

点の x 座標。

y

点の y 座標。

戻り値

GmagickDraw オブジェクトを返します。


多角形を描く

  • ≪ GmagickDraw::point
  • GmagickDraw::polyline ≫
  • PHP Manual
  • GmagickDraw
  • 多角形を描く

GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — 多角形を描く

説明

public GmagickDraw::polygon(array $coordinates): GmagickDraw

現在の描画色、線幅、塗りつぶし色、塗りつぶしテクスチャを使って、指定した座標の配列による多角形を描きます。

パラメータ

coordinates

座標の配列。

戻り値

GmagickDraw オブジェクトを返します。


ポリラインを描く

  • ≪ GmagickDraw::polygon
  • GmagickDraw::rectangle ≫
  • PHP Manual
  • GmagickDraw
  • ポリラインを描く

GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — ポリラインを描く

説明

public GmagickDraw::polyline(array $coordinate_array): GmagickDraw

現在の描画色、線幅、塗りつぶし色、塗りつぶしテクスチャを使って、指定した座標の配列によるポリラインを描きます。

パラメータ

coordinate_array

座標の配列。

戻り値

GmagickDraw オブジェクトを返します。


矩形を描く

  • ≪ GmagickDraw::polyline
  • GmagickDraw::rotate ≫
  • PHP Manual
  • GmagickDraw
  • 矩形を描く

GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — 矩形を描く

説明

public GmagickDraw::rectangle(
float $x1,
float $y1,
float $x2,
float $y2
): GmagickDraw

二つの座標を指定して、現在の描画色と線幅そして塗りつぶし設定を使った矩形を描きます。

パラメータ

x1

最初の x 座標。

y1

最初の y 座標。

x2

二番目の x 座標。

y2

二番目の y 座標。

戻り値

GmagickDraw オブジェクトを返します。


指定した回転角を現在の座標空間に適用する

  • ≪ GmagickDraw::rectangle
  • GmagickDraw::roundrectangle ≫
  • PHP Manual
  • GmagickDraw
  • 指定した回転角を現在の座標空間に適用する

GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する

説明

public GmagickDraw::rotate(float $degrees): GmagickDraw

指定した回転角を現在の座標空間に適用します。

パラメータ

degrees

回転角度。

戻り値

GmagickDraw オブジェクトを返します。


角が丸い矩形を描く

  • ≪ GmagickDraw::rotate
  • GmagickDraw::scale ≫
  • PHP Manual
  • GmagickDraw
  • 角が丸い矩形を描く

GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — 角が丸い矩形を描く

説明

public GmagickDraw::roundrectangle(
float $x1,
float $y1,
float $x2,
float $y2,
float $rx,
float $ry
): GmagickDraw

二つの座標そして x 方向と y 方向の角の半径を指定して、現在の描画色と線幅そして塗りつぶし設定を使った過度の丸い矩形を描きます。

パラメータ

x1

最初の x 座標。

y1

最初の y 座標。

x2

二番目の x 座標。

y2

二番目の y 座標。

rx

水平方向の角の半径。

ry

垂直方向の角の半径。

戻り値

GmagickDraw オブジェクトを返します。


倍率を調整する

  • ≪ GmagickDraw::roundrectangle
  • GmagickDraw::setfillcolor ≫
  • PHP Manual
  • GmagickDraw
  • 倍率を調整する

GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — 倍率を調整する

説明

public GmagickDraw::scale(float $x, float $y): GmagickDraw

現在の座標空間に対して水平方向と垂直方向の倍率を調整します。

パラメータ

x

水平方向の倍率。

y

垂直方向の倍率。

戻り値

GmagickDraw オブジェクトを返します。


オブジェクトの塗りつぶしに使う色を設定する

  • ≪ GmagickDraw::scale
  • GmagickDraw::setfillopacity ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの塗りつぶしに使う色を設定する

GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する

説明

public GmagickDraw::setfillcolor(mixed $color): GmagickDraw

オブジェクトの塗りつぶしに使う色を設定します。

パラメータ

color

塗りつぶしに使う色を表す GmagickPixel オブジェクトあるいは文字列。

戻り値

成功した場合に GmagickDraw オブジェクトを返します。


不透明度を設定する

  • ≪ GmagickDraw::setfillcolor
  • GmagickDraw::setfont ≫
  • PHP Manual
  • GmagickDraw
  • 不透明度を設定する

GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — 不透明度を設定する

説明

public GmagickDraw::setfillopacity(float $fill_opacity): GmagickDraw

塗りつぶし色や塗りつぶしテクスチャを使った描画のときに使う不透明度を設定します。 1.0 にすると、完全に不透明になります。

パラメータ

fill_opacity

塗りつぶしの不透明度。

戻り値

GmagickDraw オブジェクトを返します。


テキストのアノテーションで使うフォントの完全な名前を設定する

  • ≪ GmagickDraw::setfillopacity
  • GmagickDraw::setfontsize ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うフォントの完全な名前を設定する

GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する

説明

public GmagickDraw::setfont(string $font): GmagickDraw

テキストのアノテーションで使うフォントの完全な名前を設定します。

パラメータ

font

フォント名。

戻り値

GmagickDraw オブジェクトを返します。


テキストのアノテーションで使うフォントのポイント数を設定する

  • ≪ GmagickDraw::setfont
  • GmagickDraw::setfontstyle ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うフォントのポイント数を設定する

GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する

説明

public GmagickDraw::setfontsize(float $pointsize): GmagickDraw

テキストのアノテーションで使うフォントのポイント数を設定します。

パラメータ

pointsize

テキストのポイント数。

戻り値

GmagickDraw オブジェクトを返します。


テキストのアノテーションで使うフォントのスタイルを設定する

  • ≪ GmagickDraw::setfontsize
  • GmagickDraw::setfontweight ≫
  • PHP Manual
  • GmagickDraw
  • テキストのアノテーションで使うフォントのスタイルを設定する

GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する

説明

public GmagickDraw::setfontstyle(int $style): GmagickDraw

テキストのアノテーションで使うフォントのスタイルを設定します。 AnyStyle はワイルドカードで、「気にしない」という意味になります。

パラメータ

style

フォントスタイル (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)。

戻り値

GmagickDraw オブジェクトを返します。


フォントのウェイトを設定する

  • ≪ GmagickDraw::setfontstyle
  • GmagickDraw::setstrokecolor ≫
  • PHP Manual
  • GmagickDraw
  • フォントのウェイトを設定する

GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — フォントのウェイトを設定する

説明

public GmagickDraw::setfontweight(int $weight): GmagickDraw

テキストのアノテーションで使うフォントのウェイトを設定します。

パラメータ

weight

フォントのウェイト (100-900 の範囲が有効)。

戻り値

GmagickDraw オブジェクトを返します。


オブジェクトの輪郭の描画に使う色を設定する

  • ≪ GmagickDraw::setfontweight
  • GmagickDraw::setstrokeopacity ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う色を設定する

GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する

説明

public GmagickDraw::setstrokecolor(mixed $color): GmagickDraw

オブジェクトの輪郭の描画に使う色を設定します。

パラメータ

color

輪郭の色を表す GmagickPixel オブジェクトあるいは文字列。

戻り値

成功した場合に GmagickDraw オブジェクトを返します。


オブジェクトの輪郭の不透明度を設定する

  • ≪ GmagickDraw::setstrokecolor
  • GmagickDraw::setstrokewidth ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の不透明度を設定する

GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する

説明

public GmagickDraw::setstrokeopacity(float $stroke_opacity): GmagickDraw

オブジェクトの輪郭の不透明度を設定します。

パラメータ

stroke_opacity

不透明度。1.0 が完全な不透明を表します。

戻り値

GmagickDraw オブジェクトを返します。


オブジェクトの輪郭の描画に使う線の幅を設定する

  • ≪ GmagickDraw::setstrokeopacity
  • GmagickDraw::settextdecoration ≫
  • PHP Manual
  • GmagickDraw
  • オブジェクトの輪郭の描画に使う線の幅を設定する

GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する

説明

public GmagickDraw::setstrokewidth(float $width): GmagickDraw

オブジェクトの輪郭の描画に使う線の幅を設定します。

パラメータ

width

線の幅。

戻り値

GmagickDraw オブジェクトを返します。


デコレーションを設定する

  • ≪ GmagickDraw::setstrokewidth
  • GmagickDraw::settextencoding ≫
  • PHP Manual
  • GmagickDraw
  • デコレーションを設定する

GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — デコレーションを設定する

説明

public GmagickDraw::settextdecoration(int $decoration): GmagickDraw

テキストのアノテーションに適用するデコレーションを設定します。

パラメータ

int

テキストのデコレーション。NoDecoration、UnderlineDecoration、OverlineDecoration あるいは LineThroughDecoration のいずれか。

戻り値

GmagickDraw オブジェクトを返します。


テキストのコードセットを設定する

  • ≪ GmagickDraw::settextdecoration
  • GmagickPixel ≫
  • PHP Manual
  • GmagickDraw
  • テキストのコードセットを設定する

GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — テキストのコードセットを設定する

説明

public GmagickDraw::settextencoding(string $encoding): GmagickDraw

テキストのアノテーションで使うコードセットを表す文字列を設定します。 現時点で使える文字エンコーディングは "UTF-8" だけで、 これは Unicode をバイト列として使います。 空文字列を指定すると、テキストのエンコーディングをシステムのデフォルトに合わせます。 Unicode を使ったテキストのアノテーションをするには、Unicode に対応したフォントが必要です。

パラメータ

encoding

テキストのエンコーディングを表す文字列。

戻り値

GmagickDraw オブジェクトを返します。


GmagickPixel クラス

(PECL gmagick >= Unknown)

はじめに

クラス概要

class GmagickPixel {
/* メソッド */
public __construct(string $color = ?)
public getcolor(bool $as_array = false, bool $normalize_array = false): mixed
public getcolorcount(): int
public getcolorvalue(int $color): float
public setcolor(string $color): GmagickPixel
public setcolorvalue(int $color, float $value): GmagickPixel
}

目次

  • GmagickPixel::__construct — GmagickPixel のコンストラクタ
  • GmagickPixel::getcolor — 色を返す
  • GmagickPixel::getcolorcount — この色の色カウントを返す
  • GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する
  • GmagickPixel::setcolor — 色を設定する
  • GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する


GmagickPixel のコンストラクタ

  • ≪ GmagickPixel
  • GmagickPixel::getcolor ≫
  • PHP Manual
  • GmagickPixel
  • GmagickPixel のコンストラクタ

GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — GmagickPixel のコンストラクタ

説明

public GmagickPixel::__construct(string $color = ?)

GmagickPixel オブジェクトを作ります。 色を指定した場合は、オブジェクトを作ってからその色で初期化したものを返します。

パラメータ

color

オプションで指定する色文字列。このオブジェクトの初期値として使います。


色を返す

  • ≪ GmagickPixel::__construct
  • GmagickPixel::getcolorcount ≫
  • PHP Manual
  • GmagickPixel
  • 色を返す

GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — 色を返す

説明

public GmagickPixel::getcolor(bool $as_array = false, bool $normalize_array = false): mixed

GmagickPixel オブジェクトの色を文字列あるいは配列で返します。 透明度が設定されているときは、リストの四番目の値として返します。

パラメータ

as_array

true にすると、戻り値を文字列ではなく配列にします。

normalize_array

true にすると、色の値を正規化します。

戻り値

各チャネルの値を文字列あるいは配列で返します。normalize_array に true を市得治した場合は正規化をします。エラー時には GmagickPixelException をスローします。


この色の色カウントを返す

  • ≪ GmagickPixel::getcolor
  • GmagickPixel::getcolorvalue ≫
  • PHP Manual
  • GmagickPixel
  • この色の色カウントを返す

GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — この色の色カウントを返す

説明

public GmagickPixel::getcolorcount(): int

この色に関連づけられた色カウントを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に色カウントを整数値で返します。 失敗した場合は GmagickPixelException をスローします。


指定した色チャネルの正規化した値を取得する

  • ≪ GmagickPixel::getcolorcount
  • GmagickPixel::setcolor ≫
  • PHP Manual
  • GmagickPixel
  • 指定した色チャネルの正規化した値を取得する

GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する

説明

public GmagickPixel::getcolorvalue(int $color): float

指定した色チャネルの値を取得します。0 から 1 までの間の浮動小数点数値になります。

パラメータ

color

調べたいチャネル。Gmagick チャネル定数で指定します。

戻り値

チャネルの値を、正規化した浮動小数点数値で返します。 エラー時には GmagickPixelException をスローします。


色を設定する

  • ≪ GmagickPixel::getcolorvalue
  • GmagickPixel::setcolorvalue ≫
  • PHP Manual
  • GmagickPixel
  • 色を設定する

GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — 色を設定する

説明

public GmagickPixel::setcolor(string $color): GmagickPixel

GmagickPixel オブジェクトの色を文字列で設定します ("blue"、"#0000ff"、"rgb(0,0,255)"、"cmyk(100,100,100,10)" など)。

パラメータ

color

GmagickPixel オブジェクトを初期化するときに使う色。

戻り値

GmagickPixel オブジェクトを返します。


色チャネルの正規化した値を設定する

  • ≪ GmagickPixel::setcolor
  • ImageMagick ≫
  • PHP Manual
  • GmagickPixel
  • 色チャネルの正規化した値を設定する

GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する

説明

public GmagickPixel::setcolorvalue(int $color, float $value): GmagickPixel

このオブジェクトの指定したチャネルの値を設定します。 これは 0 から 1 までの間の値になります。 この関数を使って GmagickPixel オブジェクトの透明度チャネルを設定できます。

パラメータ

color

Gmagick チャネル定数のいずれか。

value

設定したい値。0 から 1 までの範囲で指定します。

戻り値

GmagickPixel オブジェクトを返します。


画像処理 (ImageMagick)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
    • 基本的な使用法
  • Imagick — Imagick クラス
    • Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する
    • Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する
    • Imagick::adaptiveSharpenImage — 順応して画像をシャープにする
    • Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する
    • Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する
    • Imagick::addNoiseImage — ランダムなノイズを画像に追加する
    • Imagick::affineTransformImage — 画像を変換する
    • Imagick::animateImages — 画像を動かす
    • Imagick::annotateImage — 画像にテキストによる注記を加える
    • Imagick::appendImages — 画像群を追加する
    • Imagick::autoLevelImage — Adjusts the levels of a particular image channel
    • Imagick::averageImages — 画像群を平均化する
    • Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする
    • Imagick::blueShiftImage — Mutes the colors of the image
    • Imagick::blurImage — blur (にじみ) フィルタを画像に追加する
    • Imagick::borderImage — 画像の周りを枠線で囲む
    • Imagick::brightnessContrastImage — Change the brightness and/or contrast of an image
    • Imagick::charcoalImage — 木炭画をシミュレートする
    • Imagick::chopImage — 画像の一部を取り除き、切り詰める
    • Imagick::clampImage — Restricts the color range from 0 to the quantum depth.
    • Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
    • Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る
    • Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present
    • Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る
    • Imagick::clone — Imagick オブジェクトの完全なコピーを作成する
    • Imagick::clutImage — 画像の色を置き換える
    • Imagick::coalesceImages — 複数の画像を合成する
    • Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する
    • Imagick::colorizeImage — 塗りつぶし色と画像を混合する
    • Imagick::colorMatrixImage — Apply color transformation to an image
    • Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる
    • Imagick::commentImage — コメントを画像に追加する
    • Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す
    • Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す
    • Imagick::compareImages — ある画像を再構築された画像と比較する
    • Imagick::compositeImage — ある画像を別の画像に合成する
    • Imagick::__construct — Imagick のコンストラクタ
    • Imagick::contrastImage — 画像のコントラストを変更する
    • Imagick::contrastStretchImage — カラー画像のコントラストを強調する
    • Imagick::convolveImage — 独自の畳み込み関数を画像に適用する
    • Imagick::count — Get the number of images
    • Imagick::cropImage — 画像の一部を抽出する
    • Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する
    • Imagick::current — 現在の Imagick オブジェクトへの参照を返す
    • Imagick::cycleColormapImage — 画像のカラーマップを移動する
    • Imagick::decipherImage — 画像を復号する
    • Imagick::deconstructImages — 画像間の特定のピクセルの差を返す
    • Imagick::deleteImageArtifact — 画像のアーチファクトを削除する
    • Imagick::deleteImageProperty — Deletes an image property
    • Imagick::deskewImage — 傾きを除去する
    • Imagick::despeckleImage — 画像内のスペックルノイズを軽減する
    • Imagick::destroy — Imagick オブジェクトを破棄する
    • Imagick::displayImage — 画像を表示する
    • Imagick::displayImages — 画像あるいは画像シーケンスを表示する
    • Imagick::distortImage — さまざまな方式で画像を歪める
    • Imagick::drawImage — 現在の画像上の ImagickDraw オブジェクトをレンダリングする
    • Imagick::edgeImage — 画像の輪郭を強調する
    • Imagick::embossImage — グレースケール画像に三次元効果を施して返す
    • Imagick::encipherImage — 画像を暗号化する
    • Imagick::enhanceImage — ノイジーな画像の品質を向上させる
    • Imagick::equalizeImage — 画像ヒストグラムを均等化する
    • Imagick::evaluateImage — 式を画像に適用する
    • Imagick::exportImagePixels — 画像の生のピクセルをエクスポートする
    • Imagick::extentImage — 画像のサイズを設定する
    • Imagick::filter — Applies a custom convolution kernel to the image
    • Imagick::flattenImages — 画像シーケンスをマージする
    • Imagick::flipImage — 垂直方向に反転した画像を作成する
    • Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する
    • Imagick::flopImage — 水平方向に反転した画像を作成する
    • Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)
    • Imagick::frameImage — 三次元の枠線をシミュレートする
    • Imagick::functionImage — 画像に関数を適用する
    • Imagick::fxImage — 式を画像の各ピクセルに適用する
    • Imagick::gammaImage — 画像をガンマ補正する
    • Imagick::gaussianBlurImage — 画像をぼかす
    • Imagick::getColorspace — 色空間を取得する
    • Imagick::getCompression — オブジェクトの圧縮形式を取得する
    • Imagick::getCompressionQuality — オブジェクトの圧縮品質を取得する
    • Imagick::getCopyright — ImageMagick API の著作権情報を文字列で返す
    • Imagick::getFilename — 画像シーケンスに関連付けられたファイル名を取得する
    • Imagick::getFont — フォントを取得する
    • Imagick::getFormat — Imagick オブジェクトのフォーマットを取得する
    • Imagick::getGravity — gravity を取得する
    • Imagick::getHomeURL — ImageMagick のホーム URL を返す
    • Imagick::getImage — 新しい Imagick オブジェクトを返す
    • Imagick::getImageAlphaChannel — 画像がアルファチャネルを持つかを調べる
    • Imagick::getImageArtifact — 画像のアーチファクトを取得する
    • Imagick::getImageAttribute — Returns a named attribute
    • Imagick::getImageBackgroundColor — 画像の背景色を返す
    • Imagick::getImageBlob — 画像シーケンスを blob で返す
    • Imagick::getImageBluePrimary — 青が一番強い点を返す
    • Imagick::getImageBorderColor — 画像の前景色を返す
    • Imagick::getImageChannelDepth — 特定の画像チャネルの深度を返す
    • Imagick::getImageChannelDistortion — 画像のチャネルを再構築した画像と比較する
    • Imagick::getImageChannelDistortions — チャネルの歪みを取得する
    • Imagick::getImageChannelExtrema — ひとつあるいは複数の画像チャネルの極値を取得する
    • Imagick::getImageChannelKurtosis — getImageChannelKurtosis
    • Imagick::getImageChannelMean — 平均値と標準偏差を取得する
    • Imagick::getImageChannelRange — チャネルの範囲を取得する
    • Imagick::getImageChannelStatistics — 画像の各チャネルの統計情報を返す
    • Imagick::getImageClipMask — 画像のクリップマスクを取得する
    • Imagick::getImageColormapColor — 指定したインデックスに対応する色マップ上の色を返す
    • Imagick::getImageColors — 画像で使われている色の数を取得する
    • Imagick::getImageColorspace — 画像の色空間を取得する
    • Imagick::getImageCompose — 画像の合成演算子を返す
    • Imagick::getImageCompression — 現在の画像の圧縮形式を取得する
    • Imagick::getImageCompressionQuality — 現在の画像の圧縮品質を取得する
    • Imagick::getImageDelay — 画像の遅延を取得する
    • Imagick::getImageDepth — 画像の深度を取得する
    • Imagick::getImageDispose — 画像の配置方法を取得する
    • Imagick::getImageDistortion — ある画像と再構築した画像を比較する
    • Imagick::getImageExtrema — 画像の極値を取得する
    • Imagick::getImageFilename — シーケンス内の特定の画像のファイル名を返す
    • Imagick::getImageFormat — シーケンス内の特定の画像のフォーマットを返す
    • Imagick::getImageGamma — 画像のガンマを取得する
    • Imagick::getImageGeometry — 幅と高さを連想配列で取得する
    • Imagick::getImageGravity — 画像の gravity を取得する
    • Imagick::getImageGreenPrimary — 緑が一番強い点を返す
    • Imagick::getImageHeight — 画像の高さを返す
    • Imagick::getImageHistogram — 画像のヒストグラムを取得する
    • Imagick::getImageIndex — 現在アクティブな画像のインデックスを取得する
    • Imagick::getImageInterlaceScheme — 画像のインターレース手法を取得する
    • Imagick::getImageInterpolateMethod — 画像の補間方式を返す
    • Imagick::getImageIterations — 画像の反復を取得する
    • Imagick::getImageLength — 画像の長さをバイト数で取得する
    • Imagick::getImageMatte — 画像がマットチャネルを持っているかどうかを返す
    • Imagick::getImageMatteColor — 画像のマット色を返す
    • Imagick::getImageMimeType — Returns the image mime-type
    • Imagick::getImageOrientation — 画像の方向を取得する
    • Imagick::getImagePage — ページのジオメトリを返す
    • Imagick::getImagePixelColor — 指定したピクセルの色を返す
    • Imagick::getImageProfile — 指定した名前の画像プロファイルを返す
    • Imagick::getImageProfiles — 画像プロファイルを返す
    • Imagick::getImageProperties — 画像のプロパティを返す
    • Imagick::getImageProperty — 指定した名前の画像のプロパティを返す
    • Imagick::getImageRedPrimary — 赤が一番強い点を返す
    • Imagick::getImageRegion — 画像の一部を抽出する
    • Imagick::getImageRenderingIntent — 画像のレンダリング方向を取得する
    • Imagick::getImageResolution — 画像の X 方向と Y 方向の解像度を取得する
    • Imagick::getImagesBlob — すべての画像シーケンスを blob で返す
    • Imagick::getImageScene — 画像のシーンを取得する
    • Imagick::getImageSignature — SHA-256 メッセージダイジェストを生成する
    • Imagick::getImageSize — 画像の長さをバイト数で返す
    • Imagick::getImageTicksPerSecond — 画像の ticks-per-second を取得する
    • Imagick::getImageTotalInkDensity — 画像の総インク密度を取得する
    • Imagick::getImageType — 画像の型を取得する
    • Imagick::getImageUnits — 画像の解像度の単位を取得する
    • Imagick::getImageVirtualPixelMethod — 仮想ピクセルメソッドを取得する
    • Imagick::getImageWhitePoint — 色度が白い点を返す
    • Imagick::getImageWidth — 画像の幅を返す
    • Imagick::getInterlaceScheme — オブジェクトのインターレース方式を取得する
    • Imagick::getIteratorIndex — 現在アクティブな画像のインデックスを取得する
    • Imagick::getNumberImages — オブジェクト内の画像の数を返す
    • Imagick::getOption — 指定したキーに対応する値を返す
    • Imagick::getPackageName — ImageMagick パッケージ名を返す
    • Imagick::getPage — ページのジオメトリを返す
    • Imagick::getPixelIterator — MagickPixelIterator を返す
    • Imagick::getPixelRegionIterator — 画像セクションの ImagickPixelIterator を取得する
    • Imagick::getPointSize — ポイントサイズを取得する
    • Imagick::getQuantum — Returns the ImageMagick quantum range
    • Imagick::getQuantumDepth — quantum depth を取得する
    • Imagick::getQuantumRange — Imagick quantum range を返す
    • Imagick::getRegistry — Get a StringRegistry entry
    • Imagick::getReleaseDate — ImageMagick のリリース日を返す
    • Imagick::getResource — 指定したリソースのメモリ使用状況を返す
    • Imagick::getResourceLimit — 指定したリソースの制限を返す
    • Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する
    • Imagick::getSize — Returns the size associated with the Imagick object
    • Imagick::getSizeOffset — サイズのオフセットを返す
    • Imagick::getVersion — ImageMagick API のバージョンを返す
    • Imagick::haldClutImage — 画像内の色を置換する
    • Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる
    • Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる
    • Imagick::identifyFormat — Formats a string with image details
    • Imagick::identifyImage — 画像を識別し、属性を取得する
    • Imagick::implodeImage — 新しい画像をコピーとして作成する
    • Imagick::importImagePixels — 画像のピクセルをインポートする
    • Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)
    • Imagick::labelImage — ラベルを画像に追加する
    • Imagick::levelImage — 画像のレベルを調節する
    • Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる
    • Imagick::liquidRescaleImage — 画像を動かす
    • Imagick::listRegistry — List all the registry settings
    • Imagick::magnifyImage — 画像を 2 倍に比例拡大する
    • Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える
    • Imagick::matteFloodfillImage — 色の透明度を変更する
    • Imagick::medianFilterImage — デジタルフィルタを適用する
    • Imagick::mergeImageLayers — 画像のレイヤーをマージする
    • Imagick::minifyImage — 画像をその半分のサイズに比例縮小する
    • Imagick::modulateImage — 明度、飽和度、色相を制御する
    • Imagick::montageImage — 合成画像を作成する
    • Imagick::morphImages — 複数の画像をモーフィングする
    • Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.
    • Imagick::mosaicImages — 画像からモザイクを作成する
    • Imagick::motionBlurImage — モーションブラーをシミュレートする
    • Imagick::negateImage — 画像の色を打ち消す
    • Imagick::newImage — 新しい画像を作成する
    • Imagick::newPseudoImage — 新しい画像を作成する
    • Imagick::nextImage — 次の画像に移動する
    • Imagick::normalizeImage — カラー画像のコントラストを強調する
    • Imagick::oilPaintImage — 油絵をシミュレートする
    • Imagick::opaquePaintImage — 対象にマッチする任意のピクセルの色を変更する
    • Imagick::optimizeImageLayers — 画像の繰り返し部分を削除して最適化する
    • Imagick::orderedPosterizeImage — 配列ディザリングを行う
    • Imagick::paintFloodfillImage — 色にマッチするピクセルを変更する
    • Imagick::paintOpaqueImage — 色にマッチするピクセルを変更する
    • Imagick::paintTransparentImage — 色にマッチするピクセルを塗りつぶし色に変更する
    • Imagick::pingImage — 画像の基本属性を取得する
    • Imagick::pingImageBlob — 手早く属性を取得する
    • Imagick::pingImageFile — 画像の基本属性を手軽に取得する
    • Imagick::polaroidImage — ポラロイド写真をシミュレートする
    • Imagick::posterizeImage — 指定した色数まで画像を減色する
    • Imagick::previewImages — 画像処理用の適切なパラメータを手早く取得する
    • Imagick::previousImage — オブジェクト内の前の画像に移動する
    • Imagick::profileImage — 画像のプロファイルを追加あるいは削除する
    • Imagick::quantizeImage — 参照画像内の色を解析する
    • Imagick::quantizeImages — 画像シーケンス内の色を解析する
    • Imagick::queryFontMetrics — フォントメトリクスを表す配列を返す
    • Imagick::queryFonts — 設定したフォントを返す
    • Imagick::queryFormats — Imagick がサポートするフォーマットを返す
    • Imagick::radialBlurImage — 画像にラジアルブラーを施す
    • Imagick::raiseImage — 三次元のボタン風の効果をシミュレートする
    • Imagick::randomThresholdImage — コントラストの高い 2 色の画像を作成する
    • Imagick::readImage — ファイルから画像を読み込む
    • Imagick::readImageBlob — バイナリ文字列から画像を読み込む
    • Imagick::readImageFile — オープンしているファイルハンドルから画像を読み込む
    • Imagick::readimages — Reads image from an array of filenames
    • Imagick::recolorImage — 画像の色を変更する
    • Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする
    • Imagick::remapImage — 画像の色を再配置する
    • Imagick::removeImage — 画像リストから画像を削除する
    • Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す
    • Imagick::render — それまでのすべての描画コマンドをレンダリングする
    • Imagick::resampleImage — 画像を指定した解像度にリサンプリングする
    • Imagick::resetImagePage — 画像のページをリセットする
    • Imagick::resizeImage — 画像のサイズを変更する
    • Imagick::rollImage — 画像を補正する
    • Imagick::rotateImage — 画像を回転する
    • Imagick::rotationalBlurImage — Rotational blurs an image
    • Imagick::roundCorners — 画像の角を丸める
    • Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する
    • Imagick::scaleImage — 画像のサイズを変更する
    • Imagick::segmentImage — 画像を分割する
    • Imagick::selectiveBlurImage — Selectively blur an image within a contrast threshold
    • Imagick::separateImageChannel — 画像からチャネルを分離する
    • Imagick::sepiaToneImage — 画像をセピア調にする
    • Imagick::setBackgroundColor — オブジェクトのデフォルト背景色を設定する
    • Imagick::setColorspace — 色空間を設定する
    • Imagick::setCompression — オブジェクトのデフォルトの圧縮方式を設定する
    • Imagick::setCompressionQuality — オブジェクトのデフォルトの圧縮品質を設定する
    • Imagick::setFilename — 画像を読み書きする前にファイル名を設定する
    • Imagick::setFirstIterator — Imagick イテレータを最初の画像に設定する
    • Imagick::setFont — フォントを設定する
    • Imagick::setFormat — Imagick オブジェクトのフォーマットを設定する
    • Imagick::setGravity — gravity を設定する
    • Imagick::setImage — オブジェクト内の画像を置き換える
    • Imagick::setImageAlphaChannel — 画像のアルファチャネルを設定する
    • Imagick::setImageArtifact — 画像のアーチファクトを設定する
    • Imagick::setImageAttribute — Sets an image attribute
    • Imagick::setImageBackgroundColor — 画像の背景色を設定する
    • Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
    • Imagick::setImageBiasQuantum — Sets the image bias
    • Imagick::setImageBluePrimary — 青が一番強い点を設定する
    • Imagick::setImageBorderColor — 画像の前景色を設定する
    • Imagick::setImageChannelDepth — 特定の画像チャネルの深度を設定する
    • Imagick::setImageClipMask — 画像のクリップマスクを設定する
    • Imagick::setImageColormapColor — 指定した色マップインデックスの色を設定する
    • Imagick::setImageColorspace — 画像の色空間を設定する
    • Imagick::setImageCompose — 画像の合成演算子を設定する
    • Imagick::setImageCompression — 画像の圧縮を設定する
    • Imagick::setImageCompressionQuality — 画像の圧縮品質を設定する
    • Imagick::setImageDelay — 画像の遅延を設定する
    • Imagick::setImageDepth — 画像の深度を設定する
    • Imagick::setImageDispose — 画像の配置方法を設定する
    • Imagick::setImageExtent — 画像のサイズを設定する
    • Imagick::setImageFilename — 特定の画像のファイル名を設定する
    • Imagick::setImageFormat — 特定の画像のフォーマットを設定する
    • Imagick::setImageGamma — 画像のガンマを設定する
    • Imagick::setImageGravity — 画像の gravity を設定する
    • Imagick::setImageGreenPrimary — 緑が一番強い点を設定する
    • Imagick::setImageIndex — イテレータの位置を設定する
    • Imagick::setImageInterlaceScheme — 画像のインターレース手法を設定する
    • Imagick::setImageInterpolateMethod — 画像のピクセル補間方式を設定する
    • Imagick::setImageIterations — 画像の反復を設定する
    • Imagick::setImageMatte — 画像のマットチャネルを設定する
    • Imagick::setImageMatteColor — 画像のマット色を設定する
    • Imagick::setImageOpacity — 画像の不透明度を設定する
    • Imagick::setImageOrientation — 画像の方向を設定する
    • Imagick::setImagePage — 画像のページのジオメトリを設定する
    • Imagick::setImageProfile — 指定した名前の画像プロファイルを Imagick オブジェクトに追加する
    • Imagick::setImageProperty — 画像のプロパティを設定する
    • Imagick::setImageRedPrimary — 赤が一番強い点を設定する
    • Imagick::setImageRenderingIntent — 画像のレンダリング方向を設定する
    • Imagick::setImageResolution — 画像の解像度を設定する
    • Imagick::setImageScene — 画像のシーンを設定する
    • Imagick::setImageTicksPerSecond — 画像の ticks-per-second を設定する
    • Imagick::setImageType — 画像の型を設定する
    • Imagick::setImageUnits — 画像の解像度の単位を設定する
    • Imagick::setImageVirtualPixelMethod — 画像の仮想ピクセルメソッドを設定する
    • Imagick::setImageWhitePoint — 画像の色度が白い点を設定する
    • Imagick::setInterlaceScheme — 画像の圧縮を設定する
    • Imagick::setIteratorIndex — イテレータの位置を設定する
    • Imagick::setLastIterator — Imagick イテレータを最後の画像に設定する
    • Imagick::setOption — オプションを設定する
    • Imagick::setPage — Imagick オブジェクトのページジオメトリを設定する
    • Imagick::setPointSize — ポイントサイズを設定する
    • Imagick::setProgressMonitor — Set a callback to be called during processing
    • Imagick::setRegistry — Sets the ImageMagick registry entry named key to value
    • Imagick::setResolution — 画像の解像度を設定する
    • Imagick::setResourceLimit — 特定のリソースの制限を設定する
    • Imagick::setSamplingFactors — 画像のサンプリング係数を設定する
    • Imagick::setSize — Imagick オブジェクトのサイズを設定する
    • Imagick::setSizeOffset — Imagick オブジェクトのサイズのオフセットを設定する
    • Imagick::setType — 画像タイプ属性を設定する
    • Imagick::shadeImage — 3D 効果を作成する
    • Imagick::shadowImage — 画像の影をシミュレートする
    • Imagick::sharpenImage — 画像をシャープにする
    • Imagick::shaveImage — 画像の輪郭からピクセルを刈り取る
    • Imagick::shearImage — 平行四辺形を作成する
    • Imagick::sigmoidalContrastImage — 画像のコントラストを調整する
    • Imagick::sketchImage — 鉛筆画をシミュレートする
    • Imagick::smushImages — Takes all images from the current image pointer to the end of the image list and smushs them
    • Imagick::solarizeImage — 画像にソラリゼーション効果を適用する
    • Imagick::sparseColorImage — 色を補間する
    • Imagick::spliceImage — 無地の画像を作成する
    • Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する
    • Imagick::statisticImage — Modifies image using a statistics function
    • Imagick::steganoImage — デジタル透かしを画像に埋め込む
    • Imagick::stereoImage — ふたつの画像を合成する
    • Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する
    • Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image
    • Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする
    • Imagick::textureImage — テクスチャ画像をタイル状に並べる
    • Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する
    • Imagick::thumbnailImage — 画像のサイズを変更する
    • Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する
    • Imagick::__toString — Returns the image as a string
    • Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド
    • Imagick::transformImageColorspace — Transforms an image to a new colorspace
    • Imagick::transparentPaintImage — ピクセルを透過させる
    • Imagick::transposeImage — 垂直方向に反転させた画像を作成する
    • Imagick::transverseImage — 水平方向に反転させた画像を作成する
    • Imagick::trimImage — 画像の輪郭を削除する
    • Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する
    • Imagick::unsharpMaskImage — 画像をシャープにする
    • Imagick::valid — 現在のアイテムが有効かどうかを調べる
    • Imagick::vignetteImage — ビネットフィルタを画像に追加する
    • Imagick::waveImage — ウェーブフィルタを画像に適用する
    • Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする
    • Imagick::writeImage — 指定した名前で画像を書き込む
    • Imagick::writeImageFile — 画像をファイルハンドルに書き出す
    • Imagick::writeImages — 画像あるいは画像シーケンスを書き込む
    • Imagick::writeImagesFile — フレームをファイルハンドルに書き出す
  • ImagickDraw — ImagickDraw クラス
    • ImagickDraw::affine — 現在のアフィン変換行列を設定する
    • ImagickDraw::annotation — 画像上にテキストを描画する
    • ImagickDraw::arc — 円弧を描画する
    • ImagickDraw::bezier — ベジエ曲線を描画する
    • ImagickDraw::circle — 円を描画する
    • ImagickDraw::clear — ImagickDraw をクリアする
    • ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する
    • ImagickDraw::color — 画像上に色を描画する
    • ImagickDraw::comment — コメントを追加する
    • ImagickDraw::composite — 現在の画像上に別の画像を合成する
    • ImagickDraw::__construct — ImagickDraw コンストラクタ
    • ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する
    • ImagickDraw::ellipse — 画像上に楕円を描画する
    • ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する
    • ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す
    • ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す
    • ImagickDraw::getFillColor — 塗りつぶし色を返す
    • ImagickDraw::getFillOpacity — 描画時の透過度を返す
    • ImagickDraw::getFillRule — 塗りつぶしルールを返す
    • ImagickDraw::getFont — フォントを返す
    • ImagickDraw::getFontFamily — フォントファミリーを返す
    • ImagickDraw::getFontSize — フォントのポイント数を返す
    • ImagickDraw::getFontStretch — Gets the font stretch to use when annotating with text
    • ImagickDraw::getFontStyle — フォントのスタイルを返す
    • ImagickDraw::getFontWeight — フォントの重さを返す
    • ImagickDraw::getGravity — テキストの配置時の gravity を返す
    • ImagickDraw::getStrokeAntialias — 現在の縁取りのアンチエイリアス設定を返す
    • ImagickDraw::getStrokeColor — オブジェクトの縁取りに使用する色を返す
    • ImagickDraw::getStrokeDashArray — パスの描画に使用する破線のパターンを表す配列を返す
    • ImagickDraw::getStrokeDashOffset — 破線パターンにおける破線の開始オフセットを返す
    • ImagickDraw::getStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を返す
    • ImagickDraw::getStrokeLineJoin — パスの角を描画する際に使用する形状を返す
    • ImagickDraw::getStrokeMiterLimit — マイターリミットを返す
    • ImagickDraw::getStrokeOpacity — オブジェクトの枠線の透明度を返す
    • ImagickDraw::getStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を返す
    • ImagickDraw::getTextAlignment — テキストの配置を返す
    • ImagickDraw::getTextAntialias — 現在のテキストのアンチエイリアス設定を返す
    • ImagickDraw::getTextDecoration — テキストの装飾を返す
    • ImagickDraw::getTextEncoding — テキストによる注記の際に使用するコードセットを返す
    • ImagickDraw::getTextInterlineSpacing — Gets the text interword spacing
    • ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing
    • ImagickDraw::getTextKerning — Gets the text kerning
    • ImagickDraw::getTextUnderColor — テキストの背景色を返す
    • ImagickDraw::getVectorGraphics — ベクターグラフィックを含む文字列を返す
    • ImagickDraw::line — 直線を描画する
    • ImagickDraw::matte — 画像の opacity チャネル上に描画する
    • ImagickDraw::pathClose — パス要素を現在のパスに追加する
    • ImagickDraw::pathCurveToAbsolute — 三次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierAbsolute — 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierRelative — 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToRelative — 三次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToSmoothAbsolute — 三次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToSmoothRelative — 三次ベジエ曲線を描画する
    • ImagickDraw::pathEllipticArcAbsolute — 楕円弧を描画する
    • ImagickDraw::pathEllipticArcRelative — 楕円弧を描画する
    • ImagickDraw::pathFinish — 現在のパスを終了する
    • ImagickDraw::pathLineToAbsolute — 直線パスを描画する
    • ImagickDraw::pathLineToHorizontalAbsolute — 水平直線パスを描画する
    • ImagickDraw::pathLineToHorizontalRelative — 水平直線パスを描画する
    • ImagickDraw::pathLineToRelative — 直線パスを描画する
    • ImagickDraw::pathLineToVerticalAbsolute — 垂直直線パスを描画する
    • ImagickDraw::pathLineToVerticalRelative — 垂直直線パスを描画する
    • ImagickDraw::pathMoveToAbsolute — 新しいサブパスを開始する
    • ImagickDraw::pathMoveToRelative — 新しいサブパスを開始する
    • ImagickDraw::pathStart — パス描画リストの開始を宣言する
    • ImagickDraw::point — 点を描画する
    • ImagickDraw::polygon — 多角形を描画する
    • ImagickDraw::polyline — 線分群を描画する
    • ImagickDraw::pop — スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す
    • ImagickDraw::popClipPath — クリップパスの定義を終了する
    • ImagickDraw::popDefs — 定義リストを終了する
    • ImagickDraw::popPattern — パターン定義を終了する
    • ImagickDraw::push — 現在の ImagickDraw をコピーしてスタックに格納する
    • ImagickDraw::pushClipPath — クリップパスの定義を開始する
    • ImagickDraw::pushDefs — 後に続くコマンドが、処理の前に名前つき要素を作成することを示す
    • ImagickDraw::pushPattern — 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す
    • ImagickDraw::rectangle — 矩形を描画する
    • ImagickDraw::render — これまでのすべての描画コマンドを画像上にレンダリングする
    • ImagickDraw::resetVectorGraphics — Resets the vector graphics
    • ImagickDraw::rotate — 指定した回転を現在の座標空間に適用する
    • ImagickDraw::roundRectangle — 角が丸い矩形を描画する
    • ImagickDraw::scale — 倍率を調整する
    • ImagickDraw::setClipPath — 指定した名前のクリッピングパスを画像に関連付ける
    • ImagickDraw::setClipRule — クリッピングパスで使用する多角形塗りつぶしルールを設定する
    • ImagickDraw::setClipUnits — クリップパスの単位の解釈を設定する
    • ImagickDraw::setFillAlpha — 色やテクスチャによる塗りつぶしの際の透過度を設定する
    • ImagickDraw::setFillColor — オブジェクトの塗りつぶしに使用する色を設定する
    • ImagickDraw::setFillOpacity — 色やテクスチャによる塗りつぶしの際の透過度を設定する
    • ImagickDraw::setFillPatternURL — オブジェクトの塗りつぶしパターンとして使用する URL を設定する
    • ImagickDraw::setFillRule — 多角形の描画時に使用する塗りつぶしルールを設定する
    • ImagickDraw::setFont — テキストによる注記を行う際に使用するフォントを設定する
    • ImagickDraw::setFontFamily — テキストによる注記を行う際に使用するフォントファミリーを設定する
    • ImagickDraw::setFontSize — テキストによる注記を行う際に使用するフォントのポイント数を設定する
    • ImagickDraw::setFontStretch — テキストによる注記を行う際に使用するフォントの伸縮を設定する
    • ImagickDraw::setFontStyle — テキストによる注記を行う際に使用するフォントのスタイルを設定する
    • ImagickDraw::setFontWeight — フォントの重さを設定する
    • ImagickDraw::setGravity — テキストの配置時の gravity を設定する
    • ImagickDraw::setResolution — Sets the resolution
    • ImagickDraw::setStrokeAlpha — オブジェクトの枠線の透明度を指定する
    • ImagickDraw::setStrokeAntialias — 縁取りの枠線をアンチエイリアス処理するかどうかを制御する
    • ImagickDraw::setStrokeColor — オブジェクトの縁取りに使用する色を設定する
    • ImagickDraw::setStrokeDashArray — パスの描画に使用する破線のパターンを指定する
    • ImagickDraw::setStrokeDashOffset — 破線パターンにおける破線の開始オフセットを指定する
    • ImagickDraw::setStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を指定する
    • ImagickDraw::setStrokeLineJoin — パスの角を描画する際に使用する形状を指定する
    • ImagickDraw::setStrokeMiterLimit — マイターリミットを指定する
    • ImagickDraw::setStrokeOpacity — オブジェクトの枠線の透明度を指定する
    • ImagickDraw::setStrokePatternURL — オブジェクトの枠線の描画に使用するパターンを設定する
    • ImagickDraw::setStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を設定する
    • ImagickDraw::setTextAlignment — テキストの配置を指定する
    • ImagickDraw::setTextAntialias — テキストをアンチエイリアス処理するかどうかを制御する
    • ImagickDraw::setTextDecoration — 装飾を指定する
    • ImagickDraw::setTextEncoding — テキストのコードセットを指定する
    • ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing
    • ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing
    • ImagickDraw::setTextKerning — Sets the text kerning
    • ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する
    • ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する
    • ImagickDraw::setViewbox — キャンバス全体の大きさを設定する
    • ImagickDraw::skewX — 現在の座標系を水平方向に傾ける
    • ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける
    • ImagickDraw::translate — 現在の座標系に変換を適用する
  • ImagickPixel — ImagickPixel クラス
    • ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する
    • ImagickPixel::__construct — ImagickPixel のコンストラクタ
    • ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する
    • ImagickPixel::getColor — 色を返す
    • ImagickPixel::getColorAsString — 色を文字列で返す
    • ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す
    • ImagickPixel::getColorQuantum — Returns the color of the pixel in an array as Quantum values
    • ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する
    • ImagickPixel::getColorValueQuantum — Gets the quantum value of a color in the ImagickPixel
    • ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
    • ImagickPixel::getIndex — Gets the colormap index of the pixel wand
    • ImagickPixel::isPixelSimilar — Check the distance between this color and another
    • ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance
    • ImagickPixel::isSimilar — この色と別の色の差を調べる
    • ImagickPixel::setColor — 色を設定する
    • ImagickPixel::setColorCount — Sets the color count associated with this color
    • ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する
    • ImagickPixel::setColorValueQuantum — Sets the quantum value of a color element of the ImagickPixel
    • ImagickPixel::setHSL — 正規化した HSL カラーを設定する
    • ImagickPixel::setIndex — Sets the colormap index of the pixel wand
  • ImagickPixelIterator — ImagickPixelIterator クラス
    • ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する
    • ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ
    • ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する
    • ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す
    • ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す
    • ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す
    • ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す
    • ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す
    • ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す
    • ImagickPixelIterator::resetIterator — pixel iterator をリセットする
    • ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する
    • ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する
    • ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する
    • ImagickPixelIterator::syncIterator — pixel iterator を同期する
  • ImagickKernel — The ImagickKernel class
    • ImagickKernel::addKernel — Attach another kernel to a kernel list
    • ImagickKernel::addUnityKernel — Adds a Unity Kernel to the kernel list
    • ImagickKernel::fromBuiltIn — Create a kernel from a builtin in kernel
    • ImagickKernel::fromMatrix — Create a kernel from a 2d matrix of values
    • ImagickKernel::getMatrix — Get the 2d matrix of values used in this kernel
    • ImagickKernel::scale — Scales a kernel list by the given amount
    • ImagickKernel::separate — Separates a linked set of kernels and returns an array of ImagickKernels


はじめに

Imagick は、ImageMagick API を使用して画像の作成や修正を行う ネイティブ PHP 拡張モジュールです。

ImageMagick について

ImageMagick は、ビットマップ画像の作成や修正を行うソフトウェア群です。 さまざまな (100 をこえる) 形式の画像の読み書きや変換に対応しており、 DPX や EXR、GIF、JPEG、JPEG-2000、PDF、PhotoCD、PNG、Postscript、SVG そして TIFF といった形式を扱うことができます。

ImageMagick Studio LLC は、 フリーソフトウェアによる画像処理ソリューションを提供することを目指す非営利組織です。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • ImageMagick
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

Windows 以外のプラットフォームでのインストール要件

ImageMagick >= 6.2.4 が必要です。 Imagick 拡張モジュールが処理できるフォーマットの数は、 インストールされている ImageMagick でサポートしているフォーマットに依存します。 たとえば、Imagemagick で PDF を操作するには ghostscript が必要となります。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/imagick.

注意: この拡張モジュールの正式な名前は imagick です。

Windows 版のビルド済み DLL は、» PECL のサイトからダウンロードできます。 パッケージには extension_dir に置く必要がある拡張モジュールのDLL (php_imagick.dll) が既に含まれています。 PATH が通った場所に置く必要がある ImageMagick の DLL も含まれています。 Imagick 3.6.0 以降では、 組み込みのデフォルト値を置き換えるために使う XML 設定ファイル config も含まれています。 このファイルは %USERPROFILE%/.config/ImageMagick に置くか、環境変数 MAGICK_CONFIGURE_PATH で指定されたパスに置く必要があります。 詳細は » ImageMagick configuration files documentation を参照ください。


実行時設定

php.ini の設定により動作が変化します。

Imagick 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
imagick.locale_fix | false | INI_ALL | Imagick 2.1.0 以降で使用可能
imagick.progress_monitor | false | INI_SYSTEM | Imagick 2.2.2 以降で使用可能
imagick.skip_version_check | false | INI_SYSTEM | Imagick 3.3.0 以降で使用可能
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

imagick.locale_fix bool

小数点に ',' を使うロケールでの描画のバグを修正します。

imagick.progress_monitor bool

画像プログレスモニターを有効にします。

imagick.skip_version_check bool

Imagick を読み込む際には、コンパイル時に使った ImageMagick のバージョン番号と現在インストールされている ImageMagick のバージョン番号をチェックして、 一致しない場合に警告を発します。この ini 設定を有効にすると、一致しない場合の警告を出さないようにできます。

コンパイル時に使ったバージョンと異なる ImageMagick を利用することはお勧めしません。 たまたま動いているように見えるかもしれませんが、不意にクラッシュしたり予期せぬ振る舞いを起こしたりする可能性があります。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

COLOR_* 定数

色タイプ定数です。これらは主に ImagickPixel で使用します。

imagick::COLOR_BLACK (int)
黒
imagick::COLOR_BLUE (int)
青
imagick::COLOR_CYAN (int)
シアン
imagick::COLOR_GREEN (int)
緑
imagick::COLOR_RED (int)
赤
imagick::COLOR_YELLOW (int)
黄色
imagick::COLOR_MAGENTA (int)
マゼンタ
imagick::COLOR_OPACITY (int)
色の透過度
imagick::COLOR_ALPHA (int)
色のアルファ値
imagick::COLOR_FUZZ (int)
ファズ
DISPOSE 定数

配置方式の定数です。

imagick::DISPOSE_UNRECOGNIZED (int)
認識不可能
imagick::DISPOSE_UNDEFINED (int)
未定義
imagick::DISPOSE_NONE (int)
なし
imagick::DISPOSE_BACKGROUND (int)
背景
imagick::DISPOSE_PREVIOUS (int)
前
合成演算子用定数
imagick::COMPOSITE_DEFAULT (int)
デフォルトの合成演算子
imagick::COMPOSITE_UNDEFINED (int)
未定義の合成演算子
imagick::COMPOSITE_NO (int)
合成演算子が定義されていない
imagick::COMPOSITE_ADD (int)
画像と画像を足し合わせます。
imagick::COMPOSITE_ATOP (int)
元の画像と同じ形で、ぼんやりとした画像を重ねます。
imagick::COMPOSITE_BLEND (int)
画像を混ぜ合わせます。
imagick::COMPOSITE_BUMPMAP (int)
COMPOSITE_MULTIPLY と同じですが、まず最初に元画像をグレースケールに変換します。
imagick::COMPOSITE_CLEAR (int)
対象の画像を透明にします。
imagick::COMPOSITE_COLORBURN (int)
対象の画像を暗くして元画像を反映させます。
imagick::COMPOSITE_COLORDODGE (int)
対象の画像を明るくして元画像を反映させます。
imagick::COMPOSITE_COLORIZE (int)
合成する画像を用いて画像をカラー化します。
imagick::COMPOSITE_COPYBLACK (int)
黒を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYBLUE (int)
青を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPY (int)
元画像を対象画像の上にコピーします。
imagick::COMPOSITE_COPYCYAN (int)
シアンを元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYGREEN (int)
緑を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYMAGENTA (int)
マゼンタを元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYOPACITY (int)
透明度を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYRED (int)
赤を元画像から対象画像にコピーします。
imagick::COMPOSITE_COPYYELLOW (int)
黄を元画像から対象画像にコピーします。
imagick::COMPOSITE_DARKEN (int)
対象画像を暗くします。
imagick::COMPOSITE_DSTATOP (int)
対象画像のうち元画像の内部にあるものを元画像と合成し、対象画像を置き換えます。
imagick::COMPOSITE_DST (int)
対象画像をそのままにしておきます。
imagick::COMPOSITE_DSTIN (int)
元画像の内部で対象画像を置き換えます。
imagick::COMPOSITE_DSTOUT (int)
元画像の外部で対象画像を置き換えます。
imagick::COMPOSITE_DSTOVER (int)
対象画像で元画像を置き換えます。
imagick::COMPOSITE_DIFFERENCE (int)
ふたつの色のうち、明るいほうから暗いほうを引きます。
imagick::COMPOSITE_DISPLACE (int)
対象画像のピクセルを、元画像で定義されたようにシフトします。
imagick::COMPOSITE_DISSOLVE (int)
元画像を対象画像の中に分解します。
imagick::COMPOSITE_EXCLUSION (int)
imagick::COMPOSITE_DIFFERENCE と似た効果を施しますが、 コントラストはそれよりやや低くなります。
imagick::COMPOSITE_HARDLIGHT (int)
元の画像の色に応じて、色を掛け合わせます。
imagick::COMPOSITE_HUE (int)
対象画像の色相を、元画像で指定したように変更します。
imagick::COMPOSITE_IN (int)
元画像を対象画像の中に合成します。
imagick::COMPOSITE_LIGHTEN (int)
対象画像の明度を、元画像で指定したように上げます。
imagick::COMPOSITE_LUMINIZE (int)
対象画像を、元画像で指定したようにルミナイズします。
imagick::COMPOSITE_MINUS (int)
元画像を対象画像から引きます。
imagick::COMPOSITE_MODULATE (int)
対象画像の輝度、彩度および色相を、元画像で指定したように調節します。
imagick::COMPOSITE_MULTIPLY (int)
対象画像を元画像に掛け合わせます。
imagick::COMPOSITE_OUT (int)
元画像の外部を対象画像に合成します。
imagick::COMPOSITE_OVER (int)
元画像を対象画像にかぶせます。
imagick::COMPOSITE_OVERLAY (int)
元画像を対象画像にオーバーレイさせます。
imagick::COMPOSITE_PLUS (int)
元画像を対象画像に加えます。
imagick::COMPOSITE_REPLACE (int)
対象画像を元画像で置き換えます。
imagick::COMPOSITE_SATURATE (int)
対象画像を、元画像で指定したようにしみこませます。
imagick::COMPOSITE_SCREEN (int)
The source and destination are complemented and then multiplied and then replace the destination
imagick::COMPOSITE_SOFTLIGHT (int)
元画像の指定に応じて、画像を明るくしたり暗くしたりします。
imagick::COMPOSITE_SRCATOP (int)
元画像のうち対象画像の内側にある部分を、対象画像の上に合成します。
imagick::COMPOSITE_SRC (int)
元画像を対象画像にコピーします。
imagick::COMPOSITE_SRCIN (int)
元画像のうち対象画像の内側にある部分で、対象画像を置き換えます。
imagick::COMPOSITE_SRCOUT (int)
元画像のうち対象画像の外部にある部分で元画像を置き換えます。
imagick::COMPOSITE_SRCOVER (int)
元画像で対象画像を置き換えます。
imagick::COMPOSITE_SUBTRACT (int)
元画像の色を対象画像から引きます。
imagick::COMPOSITE_THRESHOLD (int)
指定した閾値で、元画像を対象画像に合成します。
imagick::COMPOSITE_XOR (int)
元画像のうち対象画像の外側にある部分と、 対象画像のうち元画像の外側にある部分を合成します。
MONTAGEMODE 定数

imagick::MONTAGEMODE_FRAME (int)
imagick::MONTAGEMODE_UNFRAME (int)
imagick::MONTAGEMODE_CONCATENATE (int)
STYLE 定数

imagick::STYLE_NORMAL (int)
imagick::STYLE_ITALIC (int)
imagick::STYLE_OBLIQUE (int)
imagick::STYLE_ANY (int)
FILTER 定数

imagick::FILTER_UNDEFINED (int)
imagick::FILTER_POINT (int)
imagick::FILTER_BOX (int)
imagick::FILTER_TRIANGLE (int)
imagick::FILTER_HERMITE (int)
imagick::FILTER_HANNING (int)
imagick::FILTER_HAMMING (int)
imagick::FILTER_BLACKMAN (int)
imagick::FILTER_GAUSSIAN (int)
imagick::FILTER_QUADRATIC (int)
imagick::FILTER_CUBIC (int)
imagick::FILTER_CATROM (int)
imagick::FILTER_MITCHELL (int)
imagick::FILTER_LANCZOS (int)
imagick::FILTER_BESSEL (int)
imagick::FILTER_SINC (int)
IMGTYPE 定数

imagick::IMGTYPE_UNDEFINED (int)
imagick::IMGTYPE_BILEVEL (int)
imagick::IMGTYPE_GRAYSCALE (int)
imagick::IMGTYPE_GRAYSCALEMATTE (int)
imagick::IMGTYPE_PALETTE (int)
imagick::IMGTYPE_PALETTEMATTE (int)
imagick::IMGTYPE_TRUECOLOR (int)
imagick::IMGTYPE_TRUECOLORMATTE (int)
imagick::IMGTYPE_COLORSEPARATION (int)
imagick::IMGTYPE_COLORSEPARATIONMATTE (int)
imagick::IMGTYPE_OPTIMIZE (int)
RESOLUTION 定数

imagick::RESOLUTION_UNDEFINED (int)
imagick::RESOLUTION_PIXELSPERINCH (int)
imagick::RESOLUTION_PIXELSPERCENTIMETER (int)
COMPRESSION 定数

imagick::COMPRESSION_UNDEFINED (int)
imagick::COMPRESSION_NO (int)
imagick::COMPRESSION_BZIP (int)
imagick::COMPRESSION_FAX (int)
imagick::COMPRESSION_GROUP4 (int)
imagick::COMPRESSION_JPEG (int)
imagick::COMPRESSION_JPEG2000 (int)
imagick::COMPRESSION_LOSSLESSJPEG (int)
imagick::COMPRESSION_LZW (int)
imagick::COMPRESSION_RLE (int)
imagick::COMPRESSION_ZIP (int)
imagick::COMPRESSION_DXT1 (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.0 以降。
imagick::COMPRESSION_DXT3 (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.0 以降。
imagick::COMPRESSION_DXT5 (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.0 以降。
PAINT 定数

imagick::PAINT_POINT (int)
imagick::PAINT_REPLACE (int)
imagick::PAINT_FLOODFILL (int)
imagick::PAINT_FILLTOBORDER (int)
imagick::PAINT_RESET (int)
GRAVITY 定数

imagick::GRAVITY_NORTHWEST (int)
imagick::GRAVITY_NORTH (int)
imagick::GRAVITY_NORTHEAST (int)
imagick::GRAVITY_WEST (int)
imagick::GRAVITY_CENTER (int)
imagick::GRAVITY_EAST (int)
imagick::GRAVITY_SOUTHWEST (int)
imagick::GRAVITY_SOUTH (int)
imagick::GRAVITY_SOUTHEAST (int)
STRETCH 定数

imagick::STRETCH_NORMAL (int)
imagick::STRETCH_ULTRACONDENSED (int)
imagick::STRETCH_CONDENSED (int)
imagick::STRETCH_SEMICONDENSED (int)
imagick::STRETCH_SEMIEXPANDED (int)
imagick::STRETCH_EXPANDED (int)
imagick::STRETCH_EXTRAEXPANDED (int)
imagick::STRETCH_ULTRAEXPANDED (int)
imagick::STRETCH_ANY (int)
ALIGN 定数

imagick::ALIGN_UNDEFINED (int)
imagick::ALIGN_LEFT (int)
imagick::ALIGN_CENTER (int)
imagick::ALIGN_RIGHT (int)
DECORATION 定数

imagick::DECORATION_NO (int)
imagick::DECORATION_UNDERLINE (int)
imagick::DECORATION_OVERLINE (int)
imagick::DECORATION_LINETROUGH (int)
NOISE 定数

imagick::NOISE_UNIFORM (int)
imagick::NOISE_GAUSSIAN (int)
imagick::NOISE_MULTIPLICATIVEGAUSSIAN (int)
imagick::NOISE_IMPULSE (int)
imagick::NOISE_LAPLACIAN (int)
imagick::NOISE_POISSON (int)
imagick::NOISE_RANDOM (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
CHANNEL 定数

imagick::CHANNEL_UNDEFINED (int)
imagick::CHANNEL_RED (int)
imagick::CHANNEL_GRAY (int)
imagick::CHANNEL_CYAN (int)
imagick::CHANNEL_GREEN (int)
imagick::CHANNEL_MAGENTA (int)
imagick::CHANNEL_BLUE (int)
imagick::CHANNEL_YELLOW (int)
imagick::CHANNEL_ALPHA (int)
imagick::CHANNEL_OPACITY (int)
imagick::CHANNEL_MATTE (int)
imagick::CHANNEL_BLACK (int)
imagick::CHANNEL_INDEX (int)
imagick::CHANNEL_ALL (int)
imagick::CHANNEL_DEFAULT (int)
METRIC 定数

imagick::METRIC_UNDEFINED (int)
imagick::METRIC_MEANABSOLUTEERROR (int)
imagick::METRIC_MEANSQUAREERROR (int)
imagick::METRIC_PEAKABSOLUTEERROR (int)
imagick::METRIC_PEAKSIGNALTONOISERATIO (int)
imagick::METRIC_ROOTMEANSQUAREDERROR (int)
PIXEL 定数

imagick::PIXEL_CHAR (int)
imagick::PIXEL_DOUBLE (int)
imagick::PIXEL_FLOAT (int)
imagick::PIXEL_INTEGER (int)
ImageMagick < 7 でのみ利用可能です。
imagick::PIXEL_LONG (int)
imagick::PIXEL_QUANTUM (int)
imagick::PIXEL_SHORT (int)
EVALUATE 定数

imagick::EVALUATE_UNDEFINED (int)
imagick::EVALUATE_ADD (int)
imagick::EVALUATE_AND (int)
imagick::EVALUATE_DIVIDE (int)
imagick::EVALUATE_LEFTSHIFT (int)
imagick::EVALUATE_MAX (int)
imagick::EVALUATE_MIN (int)
imagick::EVALUATE_MULTIPLY (int)
imagick::EVALUATE_OR (int)
imagick::EVALUATE_RIGHTSHIFT (int)
imagick::EVALUATE_SET (int)
imagick::EVALUATE_SUBTRACT (int)
imagick::EVALUATE_XOR (int)
imagick::EVALUATE_POW (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_LOG (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_THRESHOLD (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_THRESHOLDBLACK (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_THRESHOLDWHITE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_GAUSSIANNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_IMPULSENOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_LAPLACIANNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_MULTIPLICATIVENOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_POISSONNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_UNIFORMNOISE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_COSINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_SINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
imagick::EVALUATE_ADDMODULUS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.4 以降。
COLORSPACE 定数

imagick::COLORSPACE_UNDEFINED (int)
imagick::COLORSPACE_RGB (int)
imagick::COLORSPACE_GRAY (int)
imagick::COLORSPACE_TRANSPARENT (int)
imagick::COLORSPACE_OHTA (int)
imagick::COLORSPACE_LAB (int)
imagick::COLORSPACE_XYZ (int)
imagick::COLORSPACE_YCBCR (int)
imagick::COLORSPACE_YCC (int)
imagick::COLORSPACE_YIQ (int)
imagick::COLORSPACE_YPBPR (int)
imagick::COLORSPACE_YUV (int)
imagick::COLORSPACE_CMYK (int)
imagick::COLORSPACE_SRGB (int)
imagick::COLORSPACE_HSB (int)
imagick::COLORSPACE_HSL (int)
imagick::COLORSPACE_HWB (int)
imagick::COLORSPACE_REC601LUMA (int)
imagick::COLORSPACE_REC709LUMA (int)
imagick::COLORSPACE_LOG (int)
imagick::COLORSPACE_CMY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
VIRTUALPIXELMETHOD 定数

imagick::VIRTUALPIXELMETHOD_UNDEFINED (int)
imagick::VIRTUALPIXELMETHOD_BACKGROUND (int)
imagick::VIRTUALPIXELMETHOD_CONSTANT (int)
imagick::VIRTUALPIXELMETHOD_EDGE (int)
imagick::VIRTUALPIXELMETHOD_MIRROR (int)
imagick::VIRTUALPIXELMETHOD_TILE (int)
imagick::VIRTUALPIXELMETHOD_TRANSPARENT (int)
imagick::VIRTUALPIXELMETHOD_MASK (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_BLACK (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_GRAY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_WHITE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.2 以降。
imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.3 以降。
imagick::VIRTUALPIXELMETHOD_VERTICALTILE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.3 以降。
PREVIEW 定数

imagick::PREVIEW_UNDEFINED (int)
imagick::PREVIEW_ROTATE (int)
imagick::PREVIEW_SHEAR (int)
imagick::PREVIEW_ROLL (int)
imagick::PREVIEW_HUE (int)
imagick::PREVIEW_SATURATION (int)
imagick::PREVIEW_BRIGHTNESS (int)
imagick::PREVIEW_GAMMA (int)
imagick::PREVIEW_SPIFF (int)
imagick::PREVIEW_DULL (int)
imagick::PREVIEW_GRAYSCALE (int)
imagick::PREVIEW_QUANTIZE (int)
imagick::PREVIEW_DESPECKLE (int)
imagick::PREVIEW_REDUCENOISE (int)
imagick::PREVIEW_ADDNOISE (int)
imagick::PREVIEW_SHARPEN (int)
imagick::PREVIEW_BLUR (int)
imagick::PREVIEW_THRESHOLD (int)
imagick::PREVIEW_EDGEDETECT (int)
imagick::PREVIEW_SPREAD (int)
imagick::PREVIEW_SOLARIZE (int)
imagick::PREVIEW_SHADE (int)
imagick::PREVIEW_RAISE (int)
imagick::PREVIEW_SEGMENT (int)
imagick::PREVIEW_SWIRL (int)
imagick::PREVIEW_IMPLODE (int)
imagick::PREVIEW_WAVE (int)
imagick::PREVIEW_OILPAINT (int)
imagick::PREVIEW_CHARCOALDRAWING (int)
imagick::PREVIEW_JPEG (int)
RENDERINGINTENT 定数

imagick::RENDERINGINTENT_UNDEFINED (int)
imagick::RENDERINGINTENT_SATURATION (int)
imagick::RENDERINGINTENT_PERCEPTUAL (int)
imagick::RENDERINGINTENT_ABSOLUTE (int)
imagick::RENDERINGINTENT_RELATIVE (int)
INTERLACE 定数

imagick::INTERLACE_UNDEFINED (int)
imagick::INTERLACE_NO (int)
imagick::INTERLACE_LINE (int)
imagick::INTERLACE_PLANE (int)
imagick::INTERLACE_PARTITION (int)
imagick::INTERLACE_GIF (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.4 以降。
imagick::INTERLACE_JPEG (int)
imagick::INTERLACE_PNG (int)
FILLRULE 定数

imagick::FILLRULE_UNDEFINED (int)
imagick::FILLRULE_EVENODD (int)
imagick::FILLRULE_NONZERO (int)
PATHUNITS 定数

imagick::PATHUNITS_UNDEFINED (int)
imagick::PATHUNITS_USERSPACE (int)
imagick::PATHUNITS_USERSPACEONUSE (int)
imagick::PATHUNITS_OBJECTBOUNDINGBOX (int)
LINECAP 定数

imagick::LINECAP_UNDEFINED (int)
imagick::LINECAP_BUTT (int)
imagick::LINECAP_ROUND (int)
imagick::LINECAP_SQUARE (int)
LINEJOIN 定数

imagick::LINEJOIN_UNDEFINED (int)
imagick::LINEJOIN_MITER (int)
imagick::LINEJOIN_ROUND (int)
imagick::LINEJOIN_BEVEL (int)
RESOURCETYPE 定数

imagick::RESOURCETYPE_UNDEFINED (int)
imagick::RESOURCETYPE_AREA (int)
ピクセルキャッシュメモリに配置できる画像の最大サイズ (幅 * 高さ) を設定する
imagick::RESOURCETYPE_DISK (int)
ピクセルキャッシュに使えるディスクスペースの最大値 (バイト) を設定する
imagick::RESOURCETYPE_FILE (int)
オープンするピクセルキャッシュファイルの最大数を設定する
imagick::RESOURCETYPE_MAP (int)
ピクセルキャッシュ用に確保するメモリマップの最大量 (バイト) を設定する
imagick::RESOURCETYPE_MEMORY (int)
ヒープからピクセルキャッシュに割り当てるメモリの最大値 (バイト) を設定する
imagick::RESOURCETYPE_THREAD (int)
並行スレッドの最大数を設定する。 この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.7.8 以降で利用可能。
LAYERMETHOD 定数

imagick::LAYERMETHOD_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COALESCE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COMPAREANY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COMPARECLEAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_COMPAREOVERLAY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_DISPOSE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_OPTIMIZE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_OPTIMIZEPLUS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.2.9 以降。
imagick::LAYERMETHOD_OPTIMIZEIMAGE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_OPTIMIZETRANS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_REMOVEDUPS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_REMOVEZERO (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_COMPOSITE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::LAYERMETHOD_MERGE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.7 以降。
imagick::LAYERMETHOD_FLATTEN (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.7 以降。
imagick::LAYERMETHOD_MOSAIC (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.7 以降。
ORIENTATION 定数

imagick::ORIENTATION_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_TOPLEFT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_TOPRIGHT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_BOTTOMRIGHT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_BOTTOMLEFT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_LEFTTOP (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_RIGHTTOP (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_RIGHTBOTTOM (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
imagick::ORIENTATION_LEFTBOTTOM (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.0 以降。
DISTORTION 定数

imagick::DISTORTION_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_AFFINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_AFFINEPROJECTION (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_ARC (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_BILINEAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_PERSPECTIVE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_PERSPECTIVEPROJECTION (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_SCALEROTATETRANSLATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.6 以降。
imagick::DISTORTION_POLYNOMIAL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_POLAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_DEPOLAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_BARREL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_BARRELINVERSE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_SHEPARDS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DISTORTION_SENTINEL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
ALPHACHANNEL 定数

imagick::ALPHACHANNEL_ACTIVATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_DEACTIVATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_RESET (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_SET (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.8 以降。
imagick::ALPHACHANNEL_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_COPY (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_EXTRACT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_OPAQUE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_SHAPE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_TRANSPARENT (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::ALPHACHANNEL_BACKGROUND (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.5.3 以降。
imagick::ALPHACHANNEL_REMOVE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.7.8 以降。
imagick::ALPHACHANNEL_ASSOCIATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.9.0 以降。
imagick::ALPHACHANNEL_DISSOCIATE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.9.0 以降。
imagick::ALPHACHANNEL_ON (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 7.0.0 以降。
imagick::ALPHACHANNEL_OFF (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 7.0.0 以降。
imagick::ALPHACHANNEL_DISCRETE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 7.0.0 以降。
SPARSECOLORMETHOD 定数

imagick::SPARSECOLORMETHOD_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::SPARSECOLORMETHOD_BARYCENTRIC (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::SPARSECOLORMETHOD_BILINEAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::SPARSECOLORMETHOD_POLYNOMIAL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::SPARSECOLORMETHOD_SPEPARDS (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::SPARSECOLORMETHOD_VORONOI (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
FUNCTION 定数

imagick::FUNCTION_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.9 以降。
imagick::FUNCTION_POLYNOMIAL (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.9 以降。
imagick::FUNCTION_SINUSOID (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.9 以降。
INTERPOLATE 定数

imagick::INTERPOLATE_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_AVERAGE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_BICUBIC (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_BILINEAR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_FILTER (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_INTEGER (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_MESH (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_NEARESTNEIGHBOR (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.2 以降。
imagick::INTERPOLATE_SPLINE (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.3.4 以降。
DITHERMETHOD 定数

imagick::DITHERMETHOD_UNDEFINED (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DITHERMETHOD_NO (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DITHERMETHOD_RIEMERSMA (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。
imagick::DITHERMETHOD_FLOYDSTEINBERG (int)
この定数は、Imagick のコンパイルを次のバージョンの ImageMagick で 行った場合に使用可能です。 6.4.6 以降。


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • ImageMagick
  • 例

例

目次

  • 基本的な使用法


基本的な使用法

Imagick は、PHP による画像の操作を、 とても簡単なオブジェクト指向インターフェイスで行います。 画像のサムネイルを作成する簡単な例をごらんください。

例1 Imagick によるサムネイルの作成

<?php

header('Content-type: image/jpeg');

$image = new Imagick('image.jpg');

// 幅あるいは高さに 0 を指定すると、
// 元の画像のアスペクト比を維持します
$image->thumbnailImage(100, 0);

echo $image;

?>

SPL および Imagick がサポートするその他のオブジェクト指向機能を使用すると、 ディレクトリ内のすべてのファイルのサイズを変更するのも簡単です (デジタルカメラで撮影した巨大な画像ファイル群をウェブ用に変換するような バッチ処理で有用です)。この例では、リサイズ機能を使用しています。 これは、画像のメタデータを残しておきたいからです。

例2 ディレクトリ内のすべての JPG ファイルのサムネイルの作成

<?php

$images = new Imagick(glob('images/*.JPG'));

foreach($images as $image) {

// 0 を指定することで、thumbnailImage にアスペクト比を維持させています
$image->thumbnailImage(1024,0);

}

$images->writeImages();

?>

これは、鏡像を作成する例です。 鏡像を作成するには、まず画像を反転させてその上に階調を重ねます。 そして、もとの画像と反転画像をキャンバスの上で合成します。

例3 画像の鏡像の作成

<?php
/* 画像を読み込みます */
$im = new Imagick("test.png");

/* 画像のサムネイルを作成します */
$im->thumbnailImage(200, null);

/* 画像の枠線を作成します */
$im->borderImage(new ImagickPixel("white"), 5, 5);

/* 画像をコピーし、反転させます */
$reflection = $im->clone();
$reflection->flipImage();

/* 階調を作成します。これを後で鏡像にかぶせます */
$gradient = new Imagick();

/* 階調は、画像と枠線をあわせたものより大きくなければなりません */
$gradient->newPseudoImage($reflection->getImageWidth() + 10, $reflection->getImageHeight() + 10, "gradient:transparent-black");

/* 階調を合成します */
$reflection->compositeImage($gradient, imagick::COMPOSITE_OVER, 0, 0);

/* 不透明度を設定します。ImageMagick 6.2.9 以降が必要です */
$reflection->setImageOpacity( 0.3 );

/* 空のキャンバスを作成します */
$canvas = new Imagick();

/* キャンバスは、どちらの画像よりも大きくなければなりません */
$width = $im->getImageWidth() + 40;
$height = ($im->getImageHeight() * 2) + 30;
$canvas->newImage($width, $height, new ImagickPixel("black"));
$canvas->setImageFormat("png");

/* もとの画像と鏡像をキャンバスに合成します */
$canvas->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
$canvas->compositeImage($reflection, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

/* 画像を出力します */
header("Content-Type: image/png");
echo $canvas;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : 鏡像の作成

この例では、描画時に塗りつぶしパターンを使用する方法を説明します。

例4 グラデーションつきテキスト

<?php

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* 新しい画像を作成して、これを塗りつぶしパターンとして使用します */
$im->newPseudoImage(50, 50, "gradient:red-black");

/* imagickdraw オブジェクトを作成します */
$draw = new ImagickDraw();

/* "gradient" という新しいパターンを開始します */
$draw->pushPattern('gradient', 0, 0, 50, 50);

/* パターン上のグラデーションを合成します */
$draw->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

/* パターンを閉じます */
$draw->popPattern();

/* "gradient" を塗りつぶしパターンとして指定します */
$draw->setFillPatternURL('#gradient');

/* フォントサイズを 52 に設定します */
$draw->setFontSize(52);

/* テキストを追加します */
$draw->annotation(20, 50, "Hello World!");

/* 新しいキャンバスオブジェクトと白い画像を作成します */
$canvas = new Imagick();
$canvas->newImage(350, 70, "white");

/* ImagickDraw をキャンバス上に描画します */
$canvas->drawImage($draw);

/* 幅 1px の黒い枠線で画像の周りを囲みます */
$canvas->borderImage('black', 1, 1);

/* フォーマットを PNG に設定します */
$canvas->setImageFormat('png');

/* 画像を出力します */
header("Content-Type: image/png");
echo $canvas;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : グラデーションつきテキスト

アニメーション GIF 画像を操作します。

例5 GIF 画像の読み込みと全フレームのサイズ変更

<?php

/* 新しい imagick オブジェクトを作成して GIF を読み込みます */
$im = new Imagick("example.gif");

/* 全フレームのサイズを変更します */
foreach ($im as $frame) {
/* 50x50 のフレーム */
$frame->thumbnailImage(50, 50);

/* 仮想キャンバスを正しい大きさに設定します */
$frame->setImagePage(50, 50, 0, 0);
}

/* writeImage ではなく writeImages を使うことに注意しましょう */
$im->writeImages("example_small.gif", true);
?>

楕円形を使ったりカスタムフォントを使ったりします。

例6 PHP ロゴの作成

<?php
/* 幅と高さを、本物の PHP ロゴにあわせて設定します */
$width = 400;
$height = 210;

/* Imagick オブジェクトを透過キャンバスで作ります */
$img = new Imagick();
$img->newImage($width, $height, new ImagickPixel('transparent'));

/* 楕円の描画用に、新しい ImagickDraw のインスタンスを作ります */
$draw = new ImagickDraw();
/* 楕円の塗りつぶし色を紫にします */
$draw->setFillColor('#777bb4');
/* 楕円の大きさを設定します */
$draw->ellipse($width / 2, $height / 2, $width / 2, $height / 2, 0, 360);
/* 楕円をキャンバス上に描画します */
$img->drawImage($draw);

/* 楕円の塗りつぶし色をリセットして黒に戻し、テキストの描画に備えます (ImagickDraw オブジェクトを再利用していることに注目) */
$draw->setFillColor('black');
/* 縁取りの色を白に設定します */
$draw->setStrokeColor('white');
/* 線の太さを設定します */
$draw->setStrokeWidth(2);
/* フォントのカーニングを設定します (負の値は、文字と文字の間隔を狭くすることを意味します) */
$draw->setTextKerning(-8);
/* PHP ロゴで使うフォントとそのサイズを設定します */
$draw->setFont('Handel Gothic.ttf');
$draw->setFontSize(150);
/* テキストを縦横ともに中央寄せにします */
$draw->setGravity(Imagick::GRAVITY_CENTER);

/* "php" という文字を、キャンバス内の Y オフセット -10 の位置 (楕円の中) に描画します */
$img->annotateImage($draw, 0, -10, 0, 'php');
$img->setImageFormat('png');

/* PNG のヘッダーを設定して、画像を出力します */
header('Content-Type: image/png');
echo $img;
?>

上の例の出力は、 たとえば以下のようになります。

出力例: Imagick で作った PHP ロゴ


Imagick クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

class Imagick implements Iterator {
public __construct(mixed $files = ?)
public adaptiveBlurImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool
public adaptiveResizeImage(
int $columns,
int $rows,
bool $bestfit = false,
bool $legacy = false
): bool
public adaptiveSharpenImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool
public adaptiveThresholdImage(int $width, int $height, int $offset): bool
public addImage(Imagick $source): bool
public addNoiseImage(int $noise_type, int $channel = Imagick::CHANNEL_DEFAULT): bool
public affineTransformImage(ImagickDraw $matrix): bool
public animateImages(string $x_server): bool
public annotateImage(
ImagickDraw $draw_settings,
float $x,
float $y,
float $angle,
string $text
): bool
public appendImages(bool $stack): Imagick
public autoLevelImage(int $channel = Imagick::CHANNEL_DEFAULT): bool
public averageImages(): Imagick
public blackThresholdImage(mixed $threshold): bool
public blueShiftImage(float $factor = 1.5): bool
public blurImage(float $radius, float $sigma, int $channel = ?): bool
public borderImage(mixed $bordercolor, int $width, int $height): bool
public brightnessContrastImage(float $brightness, float $contrast, int $channel = Imagick::CHANNEL_DEFAULT): bool
public charcoalImage(float $radius, float $sigma): bool
public chopImage(
int $width,
int $height,
int $x,
int $y
): bool
public clampImage(int $channel = Imagick::CHANNEL_DEFAULT): bool
public clear(): bool
public clipImage(): bool
public clipImagePath(string $pathname, string $inside): void
public clipPathImage(string $pathname, bool $inside): bool
public clone(): Imagick
public clutImage(Imagick $lookup_table, int $channel = Imagick::CHANNEL_DEFAULT): bool
public coalesceImages(): Imagick
public colorFloodfillImage(
mixed $fill,
float $fuzz,
mixed $bordercolor,
int $x,
int $y
): bool
public colorizeImage(mixed $colorize, mixed $opacity, bool $legacy = false): bool
public colorMatrixImage(array $color_matrix = Imagick::CHANNEL_DEFAULT): bool
public combineImages(int $channelType): Imagick
public commentImage(string $comment): bool
public compareImageChannels(Imagick $image, int $channelType, int $metricType): array
public compareImageLayers(int $method): Imagick
public compareImages(Imagick $compare, int $metric): array
public compositeImage(
Imagick $composite_object,
int $composite,
int $x,
int $y,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public contrastImage(bool $sharpen): bool
public contrastStretchImage(float $black_point, float $white_point, int $channel = Imagick::CHANNEL_DEFAULT): bool
public convolveImage(array $kernel, int $channel = Imagick::CHANNEL_DEFAULT): bool
public count(int $mode = 0): int
public cropImage(
int $width,
int $height,
int $x,
int $y
): bool
public cropThumbnailImage(int $width, int $height, bool $legacy = false): bool
public current(): Imagick
public cycleColormapImage(int $displace): bool
public decipherImage(string $passphrase): bool
public deconstructImages(): Imagick
public deleteImageArtifact(string $artifact): bool
public deleteImageProperty(string $name): bool
public deskewImage(float $threshold): bool
public despeckleImage(): bool
public destroy(): bool
public displayImage(string $servername): bool
public displayImages(string $servername): bool
public distortImage(int $method, array $arguments, bool $bestfit): bool
public drawImage(ImagickDraw $draw): bool
public edgeImage(float $radius): bool
public embossImage(float $radius, float $sigma): bool
public encipherImage(string $passphrase): bool
public enhanceImage(): bool
public equalizeImage(): bool
public evaluateImage(int $op, float $constant, int $channel = Imagick::CHANNEL_DEFAULT): bool
public exportImagePixels(
int $x,
int $y,
int $width,
int $height,
string $map,
int $STORAGE
): array
public extentImage(
int $width,
int $height,
int $x,
int $y
): bool
public filter(ImagickKernel $ImagickKernel, int $channel = Imagick::CHANNEL_UNDEFINED): bool
public flattenImages(): Imagick
public flipImage(): bool
public floodFillPaintImage(
mixed $fill,
float $fuzz,
mixed $target,
int $x,
int $y,
bool $invert,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public flopImage(): bool
public forwardFourierTransformimage(bool $magnitude): bool
public frameImage(
mixed $matte_color,
int $width,
int $height,
int $inner_bevel,
int $outer_bevel
): bool
public functionImage(int $function, array $arguments, int $channel = Imagick::CHANNEL_DEFAULT): bool
public fxImage(string $expression, int $channel = Imagick::CHANNEL_DEFAULT): Imagick
public gammaImage(float $gamma, int $channel = Imagick::CHANNEL_DEFAULT): bool
public gaussianBlurImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool
public getColorspace(): int
public getCompression(): int
public getCompressionQuality(): int
public static getCopyright(): string
public getFilename(): string
public getFont(): string
public getFormat(): string
public getGravity(): int
public static getHomeURL(): string
public getImage(): Imagick
public getImageAlphaChannel(): bool
public getImageArtifact(string $artifact): string
public getImageAttribute(string $key): string
public getImageBackgroundColor(): ImagickPixel
public getImageBlob(): string
public getImageBluePrimary(): array
public getImageBorderColor(): ImagickPixel
public getImageChannelDepth(int $channel): int
public getImageChannelDistortion(Imagick $reference, int $channel, int $metric): float
public getImageChannelDistortions(Imagick $reference, int $metric, int $channel = Imagick::CHANNEL_DEFAULT): float
public getImageChannelExtrema(int $channel): array
public getImageChannelKurtosis(int $channel = Imagick::CHANNEL_DEFAULT): array
public getImageChannelMean(int $channel): array
public getImageChannelRange(int $channel): array
public getImageChannelStatistics(): array
public getImageClipMask(): Imagick
public getImageColormapColor(int $index): ImagickPixel
public getImageColors(): int
public getImageColorspace(): int
public getImageCompose(): int
public getImageCompression(): int
public getImageCompressionQuality(): int
public getImageDelay(): int
public getImageDepth(): int
public getImageDispose(): int
public getImageDistortion(MagickWand $reference, int $metric): float
public getImageExtrema(): array
public getImageFilename(): string
public getImageFormat(): string
public getImageGamma(): float
public getImageGeometry(): array
public getImageGravity(): int
public getImageGreenPrimary(): array
public getImageHeight(): int
public getImageHistogram(): array
public getImageIndex(): int
public getImageInterlaceScheme(): int
public getImageInterpolateMethod(): int
public getImageIterations(): int
public getImageLength(): int
public getImageMatte(): bool
public getImageMatteColor(): ImagickPixel
public getImageMimeType(): string
public getImageOrientation(): int
public getImagePage(): array
public getImagePixelColor(int $x, int $y): ImagickPixel
public getImageProfile(string $name): string
public getImageProfiles(string $pattern = "*", bool $include_values = true): array
public getImageProperties(string $pattern = "*", bool $include_values = true): array
public getImageProperty(string $name): string
public getImageRedPrimary(): array
public getImageRegion(
int $width,
int $height,
int $x,
int $y
): Imagick
public getImageRenderingIntent(): int
public getImageResolution(): array
public getImagesBlob(): string
public getImageScene(): int
public getImageSignature(): string
public getImageSize(): int
public getImageTicksPerSecond(): int
public getImageTotalInkDensity(): float
public getImageType(): int
public getImageUnits(): int
public getImageVirtualPixelMethod(): int
public getImageWhitePoint(): array
public getImageWidth(): int
public getInterlaceScheme(): int
public getIteratorIndex(): int
public getNumberImages(): int
public getOption(string $key): string
public static getPackageName(): string
public getPage(): array
public getPixelIterator(): ImagickPixelIterator
public getPixelRegionIterator(
int $x,
int $y,
int $columns,
int $rows
): ImagickPixelIterator
public getPointSize(): float
public static getQuantum(): int
public static getQuantumDepth(): array
public static getQuantumRange(): array
public static getRegistry(string $key): string
public static getReleaseDate(): string
public static getResource(int $type): int
public static getResourceLimit(int $type): int
public getSamplingFactors(): array
public getSize(): array
public getSizeOffset(): int
public static getVersion(): array
public haldClutImage(Imagick $clut, int $channel = Imagick::CHANNEL_DEFAULT): bool
public hasNextImage(): bool
public hasPreviousImage(): bool
public identifyFormat(string $embedText): string|false
public identifyImage(bool $appendRawOutput = false): array
public implodeImage(float $radius): bool
public importImagePixels(
int $x,
int $y,
int $width,
int $height,
string $map,
int $storage,
array $pixels
): bool
public inverseFourierTransformImage(Imagick $complement, bool $magnitude): bool
public labelImage(string $label): bool
public levelImage(
float $blackPoint,
float $gamma,
float $whitePoint,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public linearStretchImage(float $blackPoint, float $whitePoint): bool
public liquidRescaleImage(
int $width,
int $height,
float $delta_x,
float $rigidity
): bool
public static listRegistry(): array
public magnifyImage(): bool
public mapImage(Imagick $map, bool $dither): bool
public matteFloodfillImage(
float $alpha,
float $fuzz,
mixed $bordercolor,
int $x,
int $y
): bool
public medianFilterImage(float $radius): bool
public mergeImageLayers(int $layer_method): Imagick
public minifyImage(): bool
public modulateImage(float $brightness, float $saturation, float $hue): bool
public montageImage(
ImagickDraw $draw,
string $tile_geometry,
string $thumbnail_geometry,
int $mode,
string $frame
): Imagick
public morphImages(int $number_frames): Imagick
public morphology(
int $morphologyMethod,
int $iterations,
ImagickKernel $ImagickKernel,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public mosaicImages(): Imagick
public motionBlurImage(
float $radius,
float $sigma,
float $angle,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public negateImage(bool $gray, int $channel = Imagick::CHANNEL_DEFAULT): bool
public newImage(
int $cols,
int $rows,
mixed $background,
string $format = ?
): bool
public newPseudoImage(int $columns, int $rows, string $pseudoString): bool
public nextImage(): bool
public normalizeImage(int $channel = Imagick::CHANNEL_DEFAULT): bool
public oilPaintImage(float $radius): bool
public opaquePaintImage(
mixed $target,
mixed $fill,
float $fuzz,
bool $invert,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public optimizeImageLayers(): bool
public orderedPosterizeImage(string $threshold_map, int $channel = Imagick::CHANNEL_DEFAULT): bool
public paintFloodfillImage(
mixed $fill,
float $fuzz,
mixed $bordercolor,
int $x,
int $y,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public paintOpaqueImage(
mixed $target,
mixed $fill,
float $fuzz,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public paintTransparentImage(mixed $target, float $alpha, float $fuzz): bool
public pingImage(string $filename): bool
public pingImageBlob(string $image): bool
public pingImageFile(resource $filehandle, string $fileName = ?): bool
public polaroidImage(ImagickDraw $properties, float $angle): bool
public posterizeImage(int $levels, bool $dither): bool
public previewImages(int $preview): bool
public previousImage(): bool
public profileImage(string $name, ?string $profile): bool
public quantizeImage(
int $numberColors,
int $colorspace,
int $treedepth,
bool $dither,
bool $measureError
): bool
public quantizeImages(
int $numberColors,
int $colorspace,
int $treedepth,
bool $dither,
bool $measureError
): bool
public queryFontMetrics(ImagickDraw $properties, string $text, bool $multiline = ?): array
public static queryFonts(string $pattern = "*"): array
public static queryFormats(string $pattern = "*"): array
public radialBlurImage(float $angle, int $channel = Imagick::CHANNEL_DEFAULT): bool
public raiseImage(
int $width,
int $height,
int $x,
int $y,
bool $raise
): bool
public randomThresholdImage(float $low, float $high, int $channel = Imagick::CHANNEL_DEFAULT): bool
public readImage(string $filename): bool
public readImageBlob(string $image, string $filename = ?): bool
public readImageFile(resource $filehandle, string $fileName = null): bool
public readImages(array $filenames): bool
public recolorImage(array $matrix): bool
public reduceNoiseImage(float $radius): bool
public remapImage(Imagick $replacement, int $DITHER): bool
public removeImage(): bool
public removeImageProfile(string $name): string
public render(): bool
public resampleImage(
float $x_resolution,
float $y_resolution,
int $filter,
float $blur
): bool
public resetImagePage(string $page): bool
public resizeImage(
int $columns,
int $rows,
int $filter,
float $blur,
bool $bestfit = false,
bool $legacy = false
): bool
public rollImage(int $x, int $y): bool
public rotateImage(mixed $background, float $degrees): bool
public rotationalBlurImage(float $angle, int $channel = Imagick::CHANNEL_DEFAULT): bool
public roundCorners(
float $x_rounding,
float $y_rounding,
float $stroke_width = 10,
float $displace = 5,
float $size_correction = -6
): bool
public sampleImage(int $columns, int $rows): bool
public scaleImage(
int $columns,
int $rows,
bool $bestfit = false,
bool $legacy = false
): bool
public segmentImage(
int $COLORSPACE,
float $cluster_threshold,
float $smooth_threshold,
bool $verbose = false
): bool
public selectiveBlurImage(
float $radius,
float $sigma,
float $threshold,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public separateImageChannel(int $channel): bool
public sepiaToneImage(float $threshold): bool
public setBackgroundColor(mixed $background): bool
public setColorspace(int $COLORSPACE): bool
public setCompression(int $compression): bool
public setCompressionQuality(int $quality): bool
public setFilename(string $filename): bool
public setFirstIterator(): bool
public setFont(string $font): bool
public setFormat(string $format): bool
public setGravity(int $gravity): bool
public setImage(Imagick $replace): bool
public setImageAlphaChannel(int $mode): bool
public setImageArtifact(string $artifact, string $value): bool
public setImageAttribute(string $key, string $value): bool
public setImageBackgroundColor(mixed $background): bool
public setImageBias(float $bias): bool
public setImageBiasQuantum(float $bias): void
public setImageBluePrimary(float $x, float $y): bool
public setImageBorderColor(mixed $border): bool
public setImageChannelDepth(int $channel, int $depth): bool
public setImageClipMask(Imagick $clip_mask): bool
public setImageColormapColor(int $index, ImagickPixel $color): bool
public setImageColorspace(int $colorspace): bool
public setImageCompose(int $compose): bool
public setImageCompression(int $compression): bool
public setImageCompressionQuality(int $quality): bool
public setImageDelay(int $delay): bool
public setImageDepth(int $depth): bool
public setImageDispose(int $dispose): bool
public setImageExtent(int $columns, int $rows): bool
public setImageFilename(string $filename): bool
public setImageFormat(string $format): bool
public setImageGamma(float $gamma): bool
public setImageGravity(int $gravity): bool
public setImageGreenPrimary(float $x, float $y): bool
public setImageIndex(int $index): bool
public setImageInterlaceScheme(int $interlace_scheme): bool
public setImageInterpolateMethod(int $method): bool
public setImageIterations(int $iterations): bool
public setImageMatte(bool $matte): bool
public setImageMatteColor(mixed $matte): bool
public setImageOpacity(float $opacity): bool
public setImageOrientation(int $orientation): bool
public setImagePage(
int $width,
int $height,
int $x,
int $y
): bool
public setImageProfile(string $name, string $profile): bool
public setImageProperty(string $name, string $value): bool
public setImageRedPrimary(float $x, float $y): bool
public setImageRenderingIntent(int $rendering_intent): bool
public setImageResolution(float $x_resolution, float $y_resolution): bool
public setImageScene(int $scene): bool
public setImageTicksPerSecond(int $ticks_per_second): bool
public setImageType(int $image_type): bool
public setImageUnits(int $units): bool
public setImageVirtualPixelMethod(int $method): bool
public setImageWhitePoint(float $x, float $y): bool
public setInterlaceScheme(int $interlace_scheme): bool
public setIteratorIndex(int $index): bool
public setLastIterator(): bool
public setOption(string $key, string $value): bool
public setPage(
int $width,
int $height,
int $x,
int $y
): bool
public setPointSize(float $point_size): bool
public setProgressMonitor(callable $callback): bool
public static setRegistry(string $key, string $value): bool
public setResolution(float $x_resolution, float $y_resolution): bool
public static setResourceLimit(int $type, int $limit): bool
public setSamplingFactors(array $factors): bool
public setSize(int $columns, int $rows): bool
public setSizeOffset(int $columns, int $rows, int $offset): bool
public setType(int $image_type): bool
public shadeImage(bool $gray, float $azimuth, float $elevation): bool
public shadowImage(
float $opacity,
float $sigma,
int $x,
int $y
): bool
public sharpenImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool
public shaveImage(int $columns, int $rows): bool
public shearImage(mixed $background, float $x_shear, float $y_shear): bool
public sigmoidalContrastImage(
bool $sharpen,
float $alpha,
float $beta,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public sketchImage(float $radius, float $sigma, float $angle): bool
public smushImages(bool $stack, int $offset): Imagick
public solarizeImage(int $threshold): bool
public sparseColorImage(int $SPARSE_METHOD, array $arguments, int $channel = Imagick::CHANNEL_DEFAULT): bool
public spliceImage(
int $width,
int $height,
int $x,
int $y
): bool
public spreadImage(float $radius): bool
public statisticImage(
int $type,
int $width,
int $height,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public steganoImage(Imagick $watermark_wand, int $offset): Imagick
public stereoImage(Imagick $offset_wand): bool
public stripImage(): bool
public subImageMatch(Imagick $Imagick, array &$offset = ?, float &$similarity = ?): Imagick
swirlImage(float $degrees): bool
textureImage(Imagick $texture_wand): Imagick
public thresholdImage(float $threshold, int $channel = Imagick::CHANNEL_DEFAULT): bool
public thumbnailImage(
int $columns,
int $rows,
bool $bestfit = false,
bool $fill = false,
bool $legacy = false
): bool
public tintImage(mixed $tint, mixed $opacity, bool $legacy = false): bool
public __toString(): string
public transformImage(string $crop, string $geometry): Imagick
public transformImageColorspace(int $colorspace): bool
public transparentPaintImage(
mixed $target,
float $alpha,
float $fuzz,
bool $invert
): bool
public transposeImage(): bool
public transverseImage(): bool
public trimImage(float $fuzz): bool
public uniqueImageColors(): bool
public unsharpMaskImage(
float $radius,
float $sigma,
float $amount,
float $threshold,
int $channel = Imagick::CHANNEL_DEFAULT
): bool
public valid(): bool
public vignetteImage(
float $blackPoint,
float $whitePoint,
int $x,
int $y
): bool
public waveImage(float $amplitude, float $length): bool
public whiteThresholdImage(mixed $threshold): bool
public writeImage(string $filename = NULL): bool
public writeImageFile(resource $filehandle, string $format = ?): bool
public writeImages(string $filename, bool $adjoin): bool
public writeImagesFile(resource $filehandle, string $format = ?): bool
}

画像メソッドおよびグローバルメソッド

Imagick クラスには、複数の画像を同時に保持して操作する機能があります。 内部的には、この機能をスタックで実装しています。 現在の画像を保持する内部ポインタが存在します。 Imagick クラスのすべての画像に対する操作を行う関数もありますが、 大半の関数は内部ポインタが指す現在の画像に対してのみ操作を行います。 スタック内の現在の画像に対してのみ影響を及ぼす関数については、 そのメソッド名に Image という単語を含める決まりになっています。

クラスメソッド

あまりにもたくさんのメソッドがあるので、 一般的な用法に絞った簡単な一覧を示します。

目的別のクラスメソッド
画像に対する効果 | Get メソッド | Set メソッド | 画像の読み書き | その他
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
 | Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

目次

  • Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する
  • Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する
  • Imagick::adaptiveSharpenImage — 順応して画像をシャープにする
  • Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する
  • Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する
  • Imagick::addNoiseImage — ランダムなノイズを画像に追加する
  • Imagick::affineTransformImage — 画像を変換する
  • Imagick::animateImages — 画像を動かす
  • Imagick::annotateImage — 画像にテキストによる注記を加える
  • Imagick::appendImages — 画像群を追加する
  • Imagick::autoLevelImage — Adjusts the levels of a particular image channel
  • Imagick::averageImages — 画像群を平均化する
  • Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする
  • Imagick::blueShiftImage — Mutes the colors of the image
  • Imagick::blurImage — blur (にじみ) フィルタを画像に追加する
  • Imagick::borderImage — 画像の周りを枠線で囲む
  • Imagick::brightnessContrastImage — Change the brightness and/or contrast of an image
  • Imagick::charcoalImage — 木炭画をシミュレートする
  • Imagick::chopImage — 画像の一部を取り除き、切り詰める
  • Imagick::clampImage — Restricts the color range from 0 to the quantum depth.
  • Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
  • Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る
  • Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present
  • Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る
  • Imagick::clone — Imagick オブジェクトの完全なコピーを作成する
  • Imagick::clutImage — 画像の色を置き換える
  • Imagick::coalesceImages — 複数の画像を合成する
  • Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する
  • Imagick::colorizeImage — 塗りつぶし色と画像を混合する
  • Imagick::colorMatrixImage — Apply color transformation to an image
  • Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる
  • Imagick::commentImage — コメントを画像に追加する
  • Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す
  • Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す
  • Imagick::compareImages — ある画像を再構築された画像と比較する
  • Imagick::compositeImage — ある画像を別の画像に合成する
  • Imagick::__construct — Imagick のコンストラクタ
  • Imagick::contrastImage — 画像のコントラストを変更する
  • Imagick::contrastStretchImage — カラー画像のコントラストを強調する
  • Imagick::convolveImage — 独自の畳み込み関数を画像に適用する
  • Imagick::count — Get the number of images
  • Imagick::cropImage — 画像の一部を抽出する
  • Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する
  • Imagick::current — 現在の Imagick オブジェクトへの参照を返す
  • Imagick::cycleColormapImage — 画像のカラーマップを移動する
  • Imagick::decipherImage — 画像を復号する
  • Imagick::deconstructImages — 画像間の特定のピクセルの差を返す
  • Imagick::deleteImageArtifact — 画像のアーチファクトを削除する
  • Imagick::deleteImageProperty — Deletes an image property
  • Imagick::deskewImage — 傾きを除去する
  • Imagick::despeckleImage — 画像内のスペックルノイズを軽減する
  • Imagick::destroy — Imagick オブジェクトを破棄する
  • Imagick::displayImage — 画像を表示する
  • Imagick::displayImages — 画像あるいは画像シーケンスを表示する
  • Imagick::distortImage — さまざまな方式で画像を歪める
  • Imagick::drawImage — 現在の画像上の ImagickDraw オブジェクトをレンダリングする
  • Imagick::edgeImage — 画像の輪郭を強調する
  • Imagick::embossImage — グレースケール画像に三次元効果を施して返す
  • Imagick::encipherImage — 画像を暗号化する
  • Imagick::enhanceImage — ノイジーな画像の品質を向上させる
  • Imagick::equalizeImage — 画像ヒストグラムを均等化する
  • Imagick::evaluateImage — 式を画像に適用する
  • Imagick::exportImagePixels — 画像の生のピクセルをエクスポートする
  • Imagick::extentImage — 画像のサイズを設定する
  • Imagick::filter — Applies a custom convolution kernel to the image
  • Imagick::flattenImages — 画像シーケンスをマージする
  • Imagick::flipImage — 垂直方向に反転した画像を作成する
  • Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する
  • Imagick::flopImage — 水平方向に反転した画像を作成する
  • Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)
  • Imagick::frameImage — 三次元の枠線をシミュレートする
  • Imagick::functionImage — 画像に関数を適用する
  • Imagick::fxImage — 式を画像の各ピクセルに適用する
  • Imagick::gammaImage — 画像をガンマ補正する
  • Imagick::gaussianBlurImage — 画像をぼかす
  • Imagick::getColorspace — 色空間を取得する
  • Imagick::getCompression — オブジェクトの圧縮形式を取得する
  • Imagick::getCompressionQuality — オブジェクトの圧縮品質を取得する
  • Imagick::getCopyright — ImageMagick API の著作権情報を文字列で返す
  • Imagick::getFilename — 画像シーケンスに関連付けられたファイル名を取得する
  • Imagick::getFont — フォントを取得する
  • Imagick::getFormat — Imagick オブジェクトのフォーマットを取得する
  • Imagick::getGravity — gravity を取得する
  • Imagick::getHomeURL — ImageMagick のホーム URL を返す
  • Imagick::getImage — 新しい Imagick オブジェクトを返す
  • Imagick::getImageAlphaChannel — 画像がアルファチャネルを持つかを調べる
  • Imagick::getImageArtifact — 画像のアーチファクトを取得する
  • Imagick::getImageAttribute — Returns a named attribute
  • Imagick::getImageBackgroundColor — 画像の背景色を返す
  • Imagick::getImageBlob — 画像シーケンスを blob で返す
  • Imagick::getImageBluePrimary — 青が一番強い点を返す
  • Imagick::getImageBorderColor — 画像の前景色を返す
  • Imagick::getImageChannelDepth — 特定の画像チャネルの深度を返す
  • Imagick::getImageChannelDistortion — 画像のチャネルを再構築した画像と比較する
  • Imagick::getImageChannelDistortions — チャネルの歪みを取得する
  • Imagick::getImageChannelExtrema — ひとつあるいは複数の画像チャネルの極値を取得する
  • Imagick::getImageChannelKurtosis — getImageChannelKurtosis
  • Imagick::getImageChannelMean — 平均値と標準偏差を取得する
  • Imagick::getImageChannelRange — チャネルの範囲を取得する
  • Imagick::getImageChannelStatistics — 画像の各チャネルの統計情報を返す
  • Imagick::getImageClipMask — 画像のクリップマスクを取得する
  • Imagick::getImageColormapColor — 指定したインデックスに対応する色マップ上の色を返す
  • Imagick::getImageColors — 画像で使われている色の数を取得する
  • Imagick::getImageColorspace — 画像の色空間を取得する
  • Imagick::getImageCompose — 画像の合成演算子を返す
  • Imagick::getImageCompression — 現在の画像の圧縮形式を取得する
  • Imagick::getImageCompressionQuality — 現在の画像の圧縮品質を取得する
  • Imagick::getImageDelay — 画像の遅延を取得する
  • Imagick::getImageDepth — 画像の深度を取得する
  • Imagick::getImageDispose — 画像の配置方法を取得する
  • Imagick::getImageDistortion — ある画像と再構築した画像を比較する
  • Imagick::getImageExtrema — 画像の極値を取得する
  • Imagick::getImageFilename — シーケンス内の特定の画像のファイル名を返す
  • Imagick::getImageFormat — シーケンス内の特定の画像のフォーマットを返す
  • Imagick::getImageGamma — 画像のガンマを取得する
  • Imagick::getImageGeometry — 幅と高さを連想配列で取得する
  • Imagick::getImageGravity — 画像の gravity を取得する
  • Imagick::getImageGreenPrimary — 緑が一番強い点を返す
  • Imagick::getImageHeight — 画像の高さを返す
  • Imagick::getImageHistogram — 画像のヒストグラムを取得する
  • Imagick::getImageIndex — 現在アクティブな画像のインデックスを取得する
  • Imagick::getImageInterlaceScheme — 画像のインターレース手法を取得する
  • Imagick::getImageInterpolateMethod — 画像の補間方式を返す
  • Imagick::getImageIterations — 画像の反復を取得する
  • Imagick::getImageLength — 画像の長さをバイト数で取得する
  • Imagick::getImageMatte — 画像がマットチャネルを持っているかどうかを返す
  • Imagick::getImageMatteColor — 画像のマット色を返す
  • Imagick::getImageMimeType — Returns the image mime-type
  • Imagick::getImageOrientation — 画像の方向を取得する
  • Imagick::getImagePage — ページのジオメトリを返す
  • Imagick::getImagePixelColor — 指定したピクセルの色を返す
  • Imagick::getImageProfile — 指定した名前の画像プロファイルを返す
  • Imagick::getImageProfiles — 画像プロファイルを返す
  • Imagick::getImageProperties — 画像のプロパティを返す
  • Imagick::getImageProperty — 指定した名前の画像のプロパティを返す
  • Imagick::getImageRedPrimary — 赤が一番強い点を返す
  • Imagick::getImageRegion — 画像の一部を抽出する
  • Imagick::getImageRenderingIntent — 画像のレンダリング方向を取得する
  • Imagick::getImageResolution — 画像の X 方向と Y 方向の解像度を取得する
  • Imagick::getImagesBlob — すべての画像シーケンスを blob で返す
  • Imagick::getImageScene — 画像のシーンを取得する
  • Imagick::getImageSignature — SHA-256 メッセージダイジェストを生成する
  • Imagick::getImageSize — 画像の長さをバイト数で返す
  • Imagick::getImageTicksPerSecond — 画像の ticks-per-second を取得する
  • Imagick::getImageTotalInkDensity — 画像の総インク密度を取得する
  • Imagick::getImageType — 画像の型を取得する
  • Imagick::getImageUnits — 画像の解像度の単位を取得する
  • Imagick::getImageVirtualPixelMethod — 仮想ピクセルメソッドを取得する
  • Imagick::getImageWhitePoint — 色度が白い点を返す
  • Imagick::getImageWidth — 画像の幅を返す
  • Imagick::getInterlaceScheme — オブジェクトのインターレース方式を取得する
  • Imagick::getIteratorIndex — 現在アクティブな画像のインデックスを取得する
  • Imagick::getNumberImages — オブジェクト内の画像の数を返す
  • Imagick::getOption — 指定したキーに対応する値を返す
  • Imagick::getPackageName — ImageMagick パッケージ名を返す
  • Imagick::getPage — ページのジオメトリを返す
  • Imagick::getPixelIterator — MagickPixelIterator を返す
  • Imagick::getPixelRegionIterator — 画像セクションの ImagickPixelIterator を取得する
  • Imagick::getPointSize — ポイントサイズを取得する
  • Imagick::getQuantum — Returns the ImageMagick quantum range
  • Imagick::getQuantumDepth — quantum depth を取得する
  • Imagick::getQuantumRange — Imagick quantum range を返す
  • Imagick::getRegistry — Get a StringRegistry entry
  • Imagick::getReleaseDate — ImageMagick のリリース日を返す
  • Imagick::getResource — 指定したリソースのメモリ使用状況を返す
  • Imagick::getResourceLimit — 指定したリソースの制限を返す
  • Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する
  • Imagick::getSize — Returns the size associated with the Imagick object
  • Imagick::getSizeOffset — サイズのオフセットを返す
  • Imagick::getVersion — ImageMagick API のバージョンを返す
  • Imagick::haldClutImage — 画像内の色を置換する
  • Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる
  • Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる
  • Imagick::identifyFormat — Formats a string with image details
  • Imagick::identifyImage — 画像を識別し、属性を取得する
  • Imagick::implodeImage — 新しい画像をコピーとして作成する
  • Imagick::importImagePixels — 画像のピクセルをインポートする
  • Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)
  • Imagick::labelImage — ラベルを画像に追加する
  • Imagick::levelImage — 画像のレベルを調節する
  • Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる
  • Imagick::liquidRescaleImage — 画像を動かす
  • Imagick::listRegistry — List all the registry settings
  • Imagick::magnifyImage — 画像を 2 倍に比例拡大する
  • Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える
  • Imagick::matteFloodfillImage — 色の透明度を変更する
  • Imagick::medianFilterImage — デジタルフィルタを適用する
  • Imagick::mergeImageLayers — 画像のレイヤーをマージする
  • Imagick::minifyImage — 画像をその半分のサイズに比例縮小する
  • Imagick::modulateImage — 明度、飽和度、色相を制御する
  • Imagick::montageImage — 合成画像を作成する
  • Imagick::morphImages — 複数の画像をモーフィングする
  • Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.
  • Imagick::mosaicImages — 画像からモザイクを作成する
  • Imagick::motionBlurImage — モーションブラーをシミュレートする
  • Imagick::negateImage — 画像の色を打ち消す
  • Imagick::newImage — 新しい画像を作成する
  • Imagick::newPseudoImage — 新しい画像を作成する
  • Imagick::nextImage — 次の画像に移動する
  • Imagick::normalizeImage — カラー画像のコントラストを強調する
  • Imagick::oilPaintImage — 油絵をシミュレートする
  • Imagick::opaquePaintImage — 対象にマッチする任意のピクセルの色を変更する
  • Imagick::optimizeImageLayers — 画像の繰り返し部分を削除して最適化する
  • Imagick::orderedPosterizeImage — 配列ディザリングを行う
  • Imagick::paintFloodfillImage — 色にマッチするピクセルを変更する
  • Imagick::paintOpaqueImage — 色にマッチするピクセルを変更する
  • Imagick::paintTransparentImage — 色にマッチするピクセルを塗りつぶし色に変更する
  • Imagick::pingImage — 画像の基本属性を取得する
  • Imagick::pingImageBlob — 手早く属性を取得する
  • Imagick::pingImageFile — 画像の基本属性を手軽に取得する
  • Imagick::polaroidImage — ポラロイド写真をシミュレートする
  • Imagick::posterizeImage — 指定した色数まで画像を減色する
  • Imagick::previewImages — 画像処理用の適切なパラメータを手早く取得する
  • Imagick::previousImage — オブジェクト内の前の画像に移動する
  • Imagick::profileImage — 画像のプロファイルを追加あるいは削除する
  • Imagick::quantizeImage — 参照画像内の色を解析する
  • Imagick::quantizeImages — 画像シーケンス内の色を解析する
  • Imagick::queryFontMetrics — フォントメトリクスを表す配列を返す
  • Imagick::queryFonts — 設定したフォントを返す
  • Imagick::queryFormats — Imagick がサポートするフォーマットを返す
  • Imagick::radialBlurImage — 画像にラジアルブラーを施す
  • Imagick::raiseImage — 三次元のボタン風の効果をシミュレートする
  • Imagick::randomThresholdImage — コントラストの高い 2 色の画像を作成する
  • Imagick::readImage — ファイルから画像を読み込む
  • Imagick::readImageBlob — バイナリ文字列から画像を読み込む
  • Imagick::readImageFile — オープンしているファイルハンドルから画像を読み込む
  • Imagick::readimages — Reads image from an array of filenames
  • Imagick::recolorImage — 画像の色を変更する
  • Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする
  • Imagick::remapImage — 画像の色を再配置する
  • Imagick::removeImage — 画像リストから画像を削除する
  • Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す
  • Imagick::render — それまでのすべての描画コマンドをレンダリングする
  • Imagick::resampleImage — 画像を指定した解像度にリサンプリングする
  • Imagick::resetImagePage — 画像のページをリセットする
  • Imagick::resizeImage — 画像のサイズを変更する
  • Imagick::rollImage — 画像を補正する
  • Imagick::rotateImage — 画像を回転する
  • Imagick::rotationalBlurImage — Rotational blurs an image
  • Imagick::roundCorners — 画像の角を丸める
  • Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する
  • Imagick::scaleImage — 画像のサイズを変更する
  • Imagick::segmentImage — 画像を分割する
  • Imagick::selectiveBlurImage — Selectively blur an image within a contrast threshold
  • Imagick::separateImageChannel — 画像からチャネルを分離する
  • Imagick::sepiaToneImage — 画像をセピア調にする
  • Imagick::setBackgroundColor — オブジェクトのデフォルト背景色を設定する
  • Imagick::setColorspace — 色空間を設定する
  • Imagick::setCompression — オブジェクトのデフォルトの圧縮方式を設定する
  • Imagick::setCompressionQuality — オブジェクトのデフォルトの圧縮品質を設定する
  • Imagick::setFilename — 画像を読み書きする前にファイル名を設定する
  • Imagick::setFirstIterator — Imagick イテレータを最初の画像に設定する
  • Imagick::setFont — フォントを設定する
  • Imagick::setFormat — Imagick オブジェクトのフォーマットを設定する
  • Imagick::setGravity — gravity を設定する
  • Imagick::setImage — オブジェクト内の画像を置き換える
  • Imagick::setImageAlphaChannel — 画像のアルファチャネルを設定する
  • Imagick::setImageArtifact — 画像のアーチファクトを設定する
  • Imagick::setImageAttribute — Sets an image attribute
  • Imagick::setImageBackgroundColor — 画像の背景色を設定する
  • Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
  • Imagick::setImageBiasQuantum — Sets the image bias
  • Imagick::setImageBluePrimary — 青が一番強い点を設定する
  • Imagick::setImageBorderColor — 画像の前景色を設定する
  • Imagick::setImageChannelDepth — 特定の画像チャネルの深度を設定する
  • Imagick::setImageClipMask — 画像のクリップマスクを設定する
  • Imagick::setImageColormapColor — 指定した色マップインデックスの色を設定する
  • Imagick::setImageColorspace — 画像の色空間を設定する
  • Imagick::setImageCompose — 画像の合成演算子を設定する
  • Imagick::setImageCompression — 画像の圧縮を設定する
  • Imagick::setImageCompressionQuality — 画像の圧縮品質を設定する
  • Imagick::setImageDelay — 画像の遅延を設定する
  • Imagick::setImageDepth — 画像の深度を設定する
  • Imagick::setImageDispose — 画像の配置方法を設定する
  • Imagick::setImageExtent — 画像のサイズを設定する
  • Imagick::setImageFilename — 特定の画像のファイル名を設定する
  • Imagick::setImageFormat — 特定の画像のフォーマットを設定する
  • Imagick::setImageGamma — 画像のガンマを設定する
  • Imagick::setImageGravity — 画像の gravity を設定する
  • Imagick::setImageGreenPrimary — 緑が一番強い点を設定する
  • Imagick::setImageIndex — イテレータの位置を設定する
  • Imagick::setImageInterlaceScheme — 画像のインターレース手法を設定する
  • Imagick::setImageInterpolateMethod — 画像のピクセル補間方式を設定する
  • Imagick::setImageIterations — 画像の反復を設定する
  • Imagick::setImageMatte — 画像のマットチャネルを設定する
  • Imagick::setImageMatteColor — 画像のマット色を設定する
  • Imagick::setImageOpacity — 画像の不透明度を設定する
  • Imagick::setImageOrientation — 画像の方向を設定する
  • Imagick::setImagePage — 画像のページのジオメトリを設定する
  • Imagick::setImageProfile — 指定した名前の画像プロファイルを Imagick オブジェクトに追加する
  • Imagick::setImageProperty — 画像のプロパティを設定する
  • Imagick::setImageRedPrimary — 赤が一番強い点を設定する
  • Imagick::setImageRenderingIntent — 画像のレンダリング方向を設定する
  • Imagick::setImageResolution — 画像の解像度を設定する
  • Imagick::setImageScene — 画像のシーンを設定する
  • Imagick::setImageTicksPerSecond — 画像の ticks-per-second を設定する
  • Imagick::setImageType — 画像の型を設定する
  • Imagick::setImageUnits — 画像の解像度の単位を設定する
  • Imagick::setImageVirtualPixelMethod — 画像の仮想ピクセルメソッドを設定する
  • Imagick::setImageWhitePoint — 画像の色度が白い点を設定する
  • Imagick::setInterlaceScheme — 画像の圧縮を設定する
  • Imagick::setIteratorIndex — イテレータの位置を設定する
  • Imagick::setLastIterator — Imagick イテレータを最後の画像に設定する
  • Imagick::setOption — オプションを設定する
  • Imagick::setPage — Imagick オブジェクトのページジオメトリを設定する
  • Imagick::setPointSize — ポイントサイズを設定する
  • Imagick::setProgressMonitor — Set a callback to be called during processing
  • Imagick::setRegistry — Sets the ImageMagick registry entry named key to value
  • Imagick::setResolution — 画像の解像度を設定する
  • Imagick::setResourceLimit — 特定のリソースの制限を設定する
  • Imagick::setSamplingFactors — 画像のサンプリング係数を設定する
  • Imagick::setSize — Imagick オブジェクトのサイズを設定する
  • Imagick::setSizeOffset — Imagick オブジェクトのサイズのオフセットを設定する
  • Imagick::setType — 画像タイプ属性を設定する
  • Imagick::shadeImage — 3D 効果を作成する
  • Imagick::shadowImage — 画像の影をシミュレートする
  • Imagick::sharpenImage — 画像をシャープにする
  • Imagick::shaveImage — 画像の輪郭からピクセルを刈り取る
  • Imagick::shearImage — 平行四辺形を作成する
  • Imagick::sigmoidalContrastImage — 画像のコントラストを調整する
  • Imagick::sketchImage — 鉛筆画をシミュレートする
  • Imagick::smushImages — Takes all images from the current image pointer to the end of the image list and smushs them
  • Imagick::solarizeImage — 画像にソラリゼーション効果を適用する
  • Imagick::sparseColorImage — 色を補間する
  • Imagick::spliceImage — 無地の画像を作成する
  • Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する
  • Imagick::statisticImage — Modifies image using a statistics function
  • Imagick::steganoImage — デジタル透かしを画像に埋め込む
  • Imagick::stereoImage — ふたつの画像を合成する
  • Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する
  • Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image
  • Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする
  • Imagick::textureImage — テクスチャ画像をタイル状に並べる
  • Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する
  • Imagick::thumbnailImage — 画像のサイズを変更する
  • Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する
  • Imagick::__toString — Returns the image as a string
  • Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド
  • Imagick::transformImageColorspace — Transforms an image to a new colorspace
  • Imagick::transparentPaintImage — ピクセルを透過させる
  • Imagick::transposeImage — 垂直方向に反転させた画像を作成する
  • Imagick::transverseImage — 水平方向に反転させた画像を作成する
  • Imagick::trimImage — 画像の輪郭を削除する
  • Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する
  • Imagick::unsharpMaskImage — 画像をシャープにする
  • Imagick::valid — 現在のアイテムが有効かどうかを調べる
  • Imagick::vignetteImage — ビネットフィルタを画像に追加する
  • Imagick::waveImage — ウェーブフィルタを画像に適用する
  • Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする
  • Imagick::writeImage — 指定した名前で画像を書き込む
  • Imagick::writeImageFile — 画像をファイルハンドルに書き出す
  • Imagick::writeImages — 画像あるいは画像シーケンスを書き込む
  • Imagick::writeImagesFile — フレームをファイルハンドルに書き出す


adaptive blur (順応性にじみ) フィルタを画像に追加する

  • ≪ Imagick
  • Imagick::adaptiveResizeImage ≫
  • PHP Manual
  • Imagick
  • adaptive blur (順応性にじみ) フィルタを画像に追加する

Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する

説明

public Imagick::adaptiveBlurImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool

adaptive blur (順応性にじみ) フィルタを画像に追加します。 adaptive blur の効果は、画像の端に近づくほど弱くなります。 一方、標準の blur の場合は画像全体に均一に働きます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。 0 を指定すると、半径を自動的に選択します。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::adaptiveBlurImage() の使用法

画像に順応性にじみを適用し、ブラウザに表示します。

<?php

header('Content-type: image/jpeg');

$image = new Imagick('test.jpg');

$image->adaptiveBlurImage(5,3);
echo $image;

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::adaptiveBlurImage() の使用法

参考

  • Imagick::blurImage() - blur (にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す


データに依存する三角測量にもとづいて画像のサイズを変更する

  • ≪ Imagick::adaptiveBlurImage
  • Imagick::adaptiveSharpenImage ≫
  • PHP Manual
  • Imagick
  • データに依存する三角測量にもとづいて画像のサイズを変更する

Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する

説明

public Imagick::adaptiveResizeImage(
int $columns,
int $rows,
bool $bestfit = false,
bool $legacy = false
): bool

データに依存する三角測量にもとづいて画像のサイズを変更します。 色が突然変わる箇所でのにじみを避けます。 たとえば、画像をほんの少しだけ縮小して "ウェブサイズ" にする場合などに便利です。フルサイズの画像のサムネイルを作成する場合などは、 あまりうまくいかないかもしれません。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

変更後の画像のカラム数。

rows

変更後の画像の行数。

bestfit

画像の大きさをバウンディングボックスにあわせるかどうか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | オプションの fit パラメータが追加されました。
PECL imagick 2.1.0 | このメソッドは、比例形式の拡大・縮小をサポートするようになりました。 どちらかのパラメータにゼロを渡すと比例形式の拡大・縮小を行います。

例

例1 Imagick::adaptiveResizeImage() の使用法

画像のサイズをウェブの標準サイズに変更します。 このメソッドは、元のサイズより少しだけ小さくする場合に最適です。 size.

<?php
header('Content-type: image/jpeg');

$image = new Imagick('image.jpg');
$image->adaptiveResizeImage(1024,768);

echo $image;
?>

参考

  • Imagick::chopImage() - 画像の一部を取り除き、切り詰める
  • Imagick::cropImage() - 画像の一部を抽出する
  • Imagick::magnifyImage() - 画像を 2 倍に比例拡大する
  • Imagick::minifyImage() - 画像をその半分のサイズに比例縮小する
  • Imagick::resizeImage() - 画像のサイズを変更する
  • Imagick::scaleImage() - 画像のサイズを変更する
  • Imagick::shaveImage() - 画像の輪郭からピクセルを刈り取る
  • Imagick::thumbnailImage() - 画像のサイズを変更する
  • Imagick::trimImage() - 画像の輪郭を削除する


順応して画像をシャープにする

  • ≪ Imagick::adaptiveResizeImage
  • Imagick::adaptiveThresholdImage ≫
  • PHP Manual
  • Imagick
  • 順応して画像をシャープにする

Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — 順応して画像をシャープにする

説明

public Imagick::adaptiveSharpenImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像をシャープにします。 画像の端の方ほど強くシャープ処理を行い、 端から離れるにつれてシャープ処理の程度を弱くします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。 0 を使用すると自動的に選択します。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::adaptiveSharpenImage() の例

半径 2、シグマ 1 で順応性のシャープ処理を施します。

<?php
try {
$image = new Imagick('image.png');
$image->adaptiveSharpenImage(2,1);
} catch(ImagickException $e) {
echo 'Error: ' , $e->getMessage();
die();
}
header('Content-type: image/png');
echo $image;
?>

参考

  • Imagick::sharpenImage() - 画像をシャープにする


輝度の範囲にもとづいて各ピクセルの閾値を選択する

  • ≪ Imagick::adaptiveSharpenImage
  • Imagick::addImage ≫
  • PHP Manual
  • Imagick
  • 輝度の範囲にもとづいて各ピクセルの閾値を選択する

Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する

説明

public Imagick::adaptiveThresholdImage(int $width, int $height, int $offset): bool

周辺のピクセルの輝度の範囲にもとづいて、 各ピクセルの閾値を選択します。 画像全体の輝度のヒストグラムが特定の頂点を持っていない場合の閾値の設定が可能となります。

パラメータ

width

周辺の幅。

height

周辺の高さ。

offset

平均オフセット。

戻り値

成功した場合に true を返します。

例

例1 Imagick::adaptiveThresholdImage()

<?php
function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
$imagick = new \Imagick(realpath($imagePath));
$adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
$imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


新しい画像を Imagick オブジェクトの画像リストに追加する

  • ≪ Imagick::adaptiveThresholdImage
  • Imagick::addNoiseImage ≫
  • PHP Manual
  • Imagick
  • 新しい画像を Imagick オブジェクトの画像リストに追加する

Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する

説明

public Imagick::addImage(Imagick $source): bool

元オブジェクトの現在の位置にある新しい画像を、 Imagick オブジェクトの画像リストに追加します。 この操作を行うと、イテレータがリストの最後尾に移動します。

パラメータ

source

元の Imagick オブジェクト。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


ランダムなノイズを画像に追加する

  • ≪ Imagick::addImage
  • Imagick::affineTransformImage ≫
  • PHP Manual
  • Imagick
  • ランダムなノイズを画像に追加する

Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — ランダムなノイズを画像に追加する

説明

public Imagick::addNoiseImage(int $noise_type, int $channel = Imagick::CHANNEL_DEFAULT): bool

ランダムなノイズを画像に追加します。

パラメータ

noise_type

ノイズの形式。 ノイズ定数 の一覧を参照ください。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::addNoiseImage()

<?php
function addNoiseImage($noiseType, $imagePath, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->addNoiseImage($noiseType, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を変換する

  • ≪ Imagick::addNoiseImage
  • Imagick::animateImages ≫
  • PHP Manual
  • Imagick
  • 画像を変換する

Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — 画像を変換する

説明

public Imagick::affineTransformImage(ImagickDraw $matrix): bool

アフィン行列の指定にしたがって画像を変換します。

パラメータ

matrix

アフィン行列。

戻り値

成功した場合に true を返します。

例

例1 Imagick::affineTransformImage()

<?php
function affineTransformImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$draw = new \ImagickDraw();

$angle = deg2rad(40);

$affineRotate = array(
"sx" => cos($angle), "sy" => cos($angle),
"rx" => sin($angle), "ry" => -sin($angle),
"tx" => 0, "ty" => 0,
);

$draw->affine($affineRotate);

$imagick->affineTransformImage($draw);

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を動かす

  • ≪ Imagick::affineTransformImage
  • Imagick::annotateImage ≫
  • PHP Manual
  • Imagick
  • 画像を動かす

Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — 画像を動かす

説明

public Imagick::animateImages(string $x_server): bool

このメソッドは、ローカルあるいはリモートの X サーバーで画像を動かします。 このメソッドは Windows では使えません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x_server

X サーバーのアドレス。

戻り値

成功した場合に true を返します。

参考

  • Imagick::displayImage() - 画像を表示する


画像にテキストによる注記を加える

  • ≪ Imagick::animateImages
  • Imagick::appendImages ≫
  • PHP Manual
  • Imagick
  • 画像にテキストによる注記を加える

Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — 画像にテキストによる注記を加える

説明

public Imagick::annotateImage(
ImagickDraw $draw_settings,
float $x,
float $y,
float $angle,
string $text
): bool

テキストによる注記を画像に加えます。

パラメータ

draw_settings

テキスト描画設定を含む ImagickDraw オブジェクト。

x

テキストの左端の水平オフセットをあらわすピクセル数。

y

テキストのベースラインの垂直オフセットをあらわすピクセル数。

angle

テキストを書き出す角度。

text

描画するテキスト。

戻り値

成功した場合に true を返します。

例

例1 Imagick::annotateImage() の使用法

空の画像にテキスト注記を加えます。

<?php
/* オブジェクトを作成します */
$image = new Imagick();
$draw = new ImagickDraw();
$pixel = new ImagickPixel( 'gray' );

/* 画像を作成します */
$image->newImage(800, 75, $pixel);

/* 黒いテキスト */
$draw->setFillColor('black');

/* フォントのプロパティ */
$draw->setFont('Bookman-DemiItalic');
$draw->setFontSize( 30 );

/* テキストの作成 */
$image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

/* 画像形式の設定 */
$image->setImageFormat('png');

/* ヘッダをつけて画像の出力 */
header('Content-type: image/png');
echo $image;

?>

参考

  • ImagickDraw::annotation() - 画像上にテキストを描画する
  • ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する


画像群を追加する

  • ≪ Imagick::annotateImage
  • Imagick::autoLevelImage ≫
  • PHP Manual
  • Imagick
  • 画像群を追加する

Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — 画像群を追加する

説明

public Imagick::appendImages(bool $stack): Imagick

画像群を、ひとつの大きな画像に追加します。

パラメータ

stack

画像を垂直方向に積むかどうか。デフォルト (あるいは false を指定した場合) は、画像を左から右に積みます。stack が true の場合は、画像を上から下に積みます。

戻り値

成功した場合に Imagick インスタンスを返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::appendImages() の例

<?php

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* 赤、緑、そして青の画像を作成します */
$im->newImage(100, 50, "red");
$im->newImage(100, 50, "green");
$im->newImage(100, 50, "blue");

/* それらをひとつの画像に追加します */
$im->resetIterator();
$combined = $im->appendImages(true);

/* 画像を出力します */
$combined->setImageFormat("png");
header("Content-Type: image/png");
echo $combined;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::appendImages()


Adjusts the levels of a particular image channel

  • ≪ Imagick::appendImages
  • Imagick::averageImages ≫
  • PHP Manual
  • Imagick
  • Adjusts the levels of a particular image channel

Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Adjusts the levels of a particular image channel

説明

public Imagick::autoLevelImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

Adjusts the levels of a particular image channel by scaling the minimum and maximum values to the full quantum range.

パラメータ

channel

Which channel should the auto-levelling should be done on.

戻り値

成功した場合に true を返します。

例

例1 Imagick::autoLevelImage()

<?php
function autoLevelImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->autoLevelImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像群を平均化する

  • ≪ Imagick::autoLevelImage
  • Imagick::blackThresholdImage ≫
  • PHP Manual
  • Imagick
  • 画像群を平均化する

Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — 画像群を平均化する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::averageImages(): Imagick

画像群を平均化します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に Imagick インスタンスを返します。

エラー / 例外

エラー時に ImagickException をスローします。


閾値に満たないすべてのピクセルを黒にする

  • ≪ Imagick::averageImages
  • Imagick::blueShiftImage ≫
  • PHP Manual
  • Imagick
  • 閾値に満たないすべてのピクセルを黒にする

Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする

説明

public Imagick::blackThresholdImage(mixed $threshold): bool

Imagick::thresholdImage() と似ていますが、 これは閾値に満たないピクセルをすべて黒にし、その他のピクセルはそのままにします。

パラメータ

threshold

すべて黒にする閾値。

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::blackThresholdImage()

<?php
function blackThresholdImage($imagePath, $thresholdColor) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->blackthresholdimage($thresholdColor);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Mutes the colors of the image

  • ≪ Imagick::blackThresholdImage
  • Imagick::blurImage ≫
  • PHP Manual
  • Imagick
  • Mutes the colors of the image

Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Mutes the colors of the image

説明

public Imagick::blueShiftImage(float $factor = 1.5): bool

Mutes the colors of the image to simulate a scene at nighttime in the moonlight.

パラメータ

factor

戻り値

成功した場合に true を返します。

例

例1 Imagick::blueShiftImage()

<?php
function blueShiftImage($imagePath, $blueShift) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->blueShiftImage($blueShift);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


blur (にじみ) フィルタを画像に追加する

  • ≪ Imagick::blueShiftImage
  • Imagick::borderImage ≫
  • PHP Manual
  • Imagick
  • blur (にじみ) フィルタを画像に追加する

Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — blur (にじみ) フィルタを画像に追加する

説明

public Imagick::blurImage(float $radius, float $sigma, int $channel = ?): bool

blur (にじみ) フィルタを画像に追加します。 オプションの 3 番目のパラメータを指定すると、 特定のチャネルにのみ適用します。

パラメータ

radius

にじみの半径。

sigma

標準偏差。

channel

チャネル 定数。 省略した場合は全チャネルが対象となります。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::blurImage() の使用法

画像をにじませ、ブラウザに表示します。

<?php

header('Content-type: image/jpeg');

$image = new Imagick('test.jpg');

$image->blurImage(5,3);
echo $image;

?>

参考

  • Imagick::adaptiveBlurImage() - adaptive blur (順応性にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す


画像の周りを枠線で囲む

  • ≪ Imagick::blurImage
  • Imagick::brightnessContrastImage ≫
  • PHP Manual
  • Imagick
  • 画像の周りを枠線で囲む

Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — 画像の周りを枠線で囲む

説明

public Imagick::borderImage(mixed $bordercolor, int $width, int $height): bool

画像の周りを枠線で囲みます。枠線の色は ImagickPixel オブジェクトで指定します。

パラメータ

bordercolor

枠線の色を含む ImagickPixel オブジェクトあるいは文字列。

width

枠線の幅。

height

枠線の高さ。

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::borderImage()

<?php
function borderImage($imagePath, $color, $width, $height) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->borderImage($color, $width, $height);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Change the brightness and/or contrast of an image

  • ≪ Imagick::borderImage
  • Imagick::charcoalImage ≫
  • PHP Manual
  • Imagick
  • Change the brightness and/or contrast of an image

Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Change the brightness and/or contrast of an image

説明

public Imagick::brightnessContrastImage(float $brightness, float $contrast, int $channel = Imagick::CHANNEL_DEFAULT): bool

Change the brightness and/or contrast of an image. It converts the brightness and contrast parameters into slope and intercept and calls a polynomical function to apply to the image.

パラメータ

brightness

contrast

channel

戻り値

成功した場合に true を返します。

例

例1 Imagick::brightnessContrastImage()

<?php
function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->brightnessContrastImage($brightness, $contrast, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


木炭画をシミュレートする

  • ≪ Imagick::brightnessContrastImage
  • Imagick::chopImage ≫
  • PHP Manual
  • Imagick
  • 木炭画をシミュレートする

Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — 木炭画をシミュレートする

説明

public Imagick::charcoalImage(float $radius, float $sigma): bool

木炭画をシミュレートします。

パラメータ

radius

ガウス分布の半径。中心を含まないピクセル数。

sigma

ガウス分布の標準偏差 (ピクセル単位)。

戻り値

成功した場合に true を返します。

例

例1 Imagick::charcoalImage()

<?php
function charcoalImage($imagePath, $radius, $sigma) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->charcoalImage($radius, $sigma);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の一部を取り除き、切り詰める

  • ≪ Imagick::charcoalImage
  • Imagick::clampImage ≫
  • PHP Manual
  • Imagick
  • 画像の一部を取り除き、切り詰める

Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — 画像の一部を取り除き、切り詰める

説明

public Imagick::chopImage(
int $width,
int $height,
int $x,
int $y
): bool

画像の一部を削除し、そこにあった画像をなくします。

パラメータ

width

切り取る範囲の幅。

height

切り取る範囲の高さ。

x

切り取る範囲の X 座標。

y

切り取る範囲の Y 座標。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::chopImage() の使用法

Imagick::chopImage の使用例です。

<?php
/* オブジェクトの作成 */
$image = new Imagick();
$pixel = new ImagickPixel( 'gray' );

/* 新しい画像 */
$image->newImage(400, 200, $pixel);

/* 画像の切り取り */
$image->chopImage(200, 200, 0, 0);

/* 画図おフォーマットの指定 */
$image->setImageFormat('png');

/* ヘッダをつけて画像の出力 */
header('Content-type: image/png');
echo $image;

?>

参考

  • Imagick::cropImage() - 画像の一部を抽出する


Restricts the color range from 0 to the quantum depth.

  • ≪ Imagick::chopImage
  • Imagick::clear ≫
  • PHP Manual
  • Imagick
  • Restricts the color range from 0 to the quantum depth.

Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Restricts the color range from 0 to the quantum depth.

説明

public Imagick::clampImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

Restricts the color range from 0 to the quantum depth.

パラメータ

channel

戻り値

成功した場合に true を、失敗した場合に false を返します。


Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

  • ≪ Imagick::clampImage
  • Imagick::clipImage ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

説明

public Imagick::clear(): bool

Imagick オブジェクトに関連付けられたすべてのリソースをクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


8BIM プロファイルの最初のパスにそって切り取る

  • ≪ Imagick::clear
  • Imagick::clipImagePath ≫
  • PHP Manual
  • Imagick
  • 8BIM プロファイルの最初のパスにそって切り取る

Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る

説明

public Imagick::clipImage(): bool

8BIM プロファイルの最初のパスが存在する場合に、それにそって切り取ります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


Clips along the named paths from the 8BIM profile, if present

  • ≪ Imagick::clipImage
  • Imagick::clipPathImage ≫
  • PHP Manual
  • Imagick
  • Clips along the named paths from the 8BIM profile, if present

Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present

説明

public Imagick::clipImagePath(string $pathname, string $inside): void

Clips along the named paths from the 8BIM profile, if present. Later operations take effect inside the path. Id may be a number if preceded with #, to work on a numbered path, e.g., "#1" to use the first path.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

pathname

inside

戻り値


8BIM プロファイルの指定した名前のパスにそって切り取る

  • ≪ Imagick::clipImagePath
  • Imagick::clone ≫
  • PHP Manual
  • Imagick
  • 8BIM プロファイルの指定した名前のパスにそって切り取る

Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る

説明

public Imagick::clipPathImage(string $pathname, bool $inside): bool

8BIM プロファイルの指定した名前のパスが存在する場合に、それにそって切り取ります。 その後の操作はパスの内部に対してのみ有効となります。 番号で指定する場合は、番号の前に # を付加します。つまり "#1" とすると最初のパスを使用します。

パラメータ

pathname

パスの名前。

inside

true の場合は、その後の操作はクリップパスの内側に対して適用されます。 それ以外の場合は、その後の操作はクリップパスの外側に対して適用されます。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


Imagick オブジェクトの完全なコピーを作成する

  • ≪ Imagick::clipPathImage
  • Imagick::clutImage ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトの完全なコピーを作成する

Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Imagick オブジェクトの完全なコピーを作成する

説明

public Imagick::clone(): Imagick

Imagick オブジェクトの完全なコピーを作成します。

警告

この関数は imagick 3.1.0 で 非推奨 となりました。 かわりに clone キーワードを使います。

パラメータ

この関数にはパラメータはありません。

戻り値

Imagick オブジェクトのコピーを返します。

変更履歴

バージョン | 説明
PECL imagick 3.1.0 | このメソッドは非推奨となりました。かわりに clone キーワードを使います。

例

例1 Imagick オブジェクトのクローン

<?php
// imagick 2.x および 3.0 の場合
$newImage = $image->clone();

// 3.1.0 以降の場合
$newImage = clone $image;
?>


画像の色を置き換える

  • ≪ Imagick::clone
  • Imagick::coalesceImages ≫
  • PHP Manual
  • Imagick
  • 画像の色を置き換える

Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — 画像の色を置き換える

説明

public Imagick::clutImage(Imagick $lookup_table, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像の色を、ルックアップテーブルをもとに置き換えます。 オプションの 2 番目のパラメータを指定すると、 特定のチャネルの色を置き換えます。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

lookup_table

色ルックアップテーブルを含む Imagick オブジェクト。

channel

チャネルタイプ 定数。 省略した場合はデフォルトチャネルが対象となります。

戻り値

成功した場合に true を返します。

例

例1 Imagick::clutImage() の使用法

画像の色を、ルックアップテーブルをもとに置き換えます。

<?php
$image = new Imagick('test.jpg');
$clut = new Imagick();
$clut->newImage(1, 1, new ImagickPixel('black'));
$image->clutImage($clut);
$image->writeImage('test_out.jpg');
?>

参考

  • Imagick::adaptiveBlurImage() - adaptive blur (順応性にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す


複数の画像を合成する

  • ≪ Imagick::clutImage
  • Imagick::colorFloodfillImage ≫
  • PHP Manual
  • Imagick
  • 複数の画像を合成する

Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — 複数の画像を合成する

説明

public Imagick::coalesceImages(): Imagick

ページオフセットや処理方法を指定して、複数の画像を合成します。 典型的な使用例としては、たとえば GIF や MIFF、MNG といった画像シーケンスを最初に背景として指定し、 それ以降にさまざまなサイズやオフセットの画像を合成するというものがあります。 戻り値は、新規 Imagick オブジェクトとなります。 シーケンスの各画像のサイズは、最初の画像のサイズと同じになります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に新規 Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。


対象にマッチする任意の点の色の値を変更する

  • ≪ Imagick::coalesceImages
  • Imagick::colorizeImage ≫
  • PHP Manual
  • Imagick
  • 対象にマッチする任意の点の色の値を変更する

Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::colorFloodfillImage(
mixed $fill,
float $fuzz,
mixed $bordercolor,
int $x,
int $y
): bool

対象にマッチする任意の点の色の値を変更します。

パラメータ

fill

塗りつぶし色を表す ImagickPixel オブジェクト。

fuzz

fuzz の量。たとえば fuzz を 10 に設定すると、 赤の輝度が 100 および 102 の点は同じ色とみなされます。

bordercolor

枠線の色を表す ImagickPixel オブジェクト。

x

開始位置の X 座標。

y

開始位置の Y 座標。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータと三番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


塗りつぶし色と画像を混合する

  • ≪ Imagick::colorFloodfillImage
  • Imagick::colorMatrixImage ≫
  • PHP Manual
  • Imagick
  • 塗りつぶし色と画像を混合する

Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — 塗りつぶし色と画像を混合する

説明

public Imagick::colorizeImage(mixed $colorize, mixed $opacity, bool $legacy = false): bool

画像の各ピクセルに、塗りつぶし色を混合します。

パラメータ

colorize

色を表す ImagickPixel オブジェクトあるいは文字列。

opacity

不透明度を表す ImagickPixel オブジェクトあるいは文字列。 1.0 は完全に不透明、0.0 は完全に透明であることを表します。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして、 不透明度を表す浮動小数点数値を 2 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::colorizeImage()

<?php
function colorizeImage($imagePath, $color, $opacity) {
$imagick = new \Imagick(realpath($imagePath));
$opacity = $opacity / 255.0;
$opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
$imagick->colorizeImage($color, $opacityColor);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Apply color transformation to an image

  • ≪ Imagick::colorizeImage
  • Imagick::combineImages ≫
  • PHP Manual
  • Imagick
  • Apply color transformation to an image

Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Apply color transformation to an image

説明

public Imagick::colorMatrixImage(array $color_matrix = Imagick::CHANNEL_DEFAULT): bool

Apply color transformation to an image. The method permits saturation changes, hue rotation, luminance to alpha, and various other effects. Although variable-sized transformation matrices can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 for CMYKA (or RGBA with offsets). The matrix is similar to those used by Adobe Flash except offsets are in column 6 rather than 5 (in support of CMYKA images) and offsets are normalized (divide Flash offset by 255)

パラメータ

color_matrix

戻り値

成功した場合に true を返します。

例

例1 Imagick::colorMatrixImage()

<?php
function colorMatrixImage($imagePath, $colorMatrix) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageOpacity(1);

//A color matrix should look like:
// $colorMatrix = [
// 1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
// 0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
// 0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
// 0.0, 0.0, 0.0, 1.0, 0.0, 0.0,
// 0.0, 0.0, 0.0, 0.0, 1.0, 0.0,
// 0.0, 0.0, 0.0, 0.0, 0.0, 1.0
// ];

$background = new \Imagick();
$background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(), "pattern:checkerboard");

$background->setImageFormat('png');

$imagick->setImageFormat('png');
$imagick->colorMatrixImage($colorMatrix);

$background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

header("Content-Type: image/png");
echo $background->getImageBlob();
}

?>


ひとつあるいは複数の画像をひとつにまとめる

  • ≪ Imagick::colorMatrixImage
  • Imagick::commentImage ≫
  • PHP Manual
  • Imagick
  • ひとつあるいは複数の画像をひとつにまとめる

Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる

説明

public Imagick::combineImages(int $channelType): Imagick

ひとつあるいは複数の画像をひとつにまとめます。 一連の画像の各ピクセルのグレースケール値が、 合成した画像の特定のチャネルの値となります。典型的なパターンでは 画像 1 => Red、画像 2 => Green、画像 3 => Blue などとなります。

パラメータ

channelType

そのチャネルモードで使用可能なチャネル定数のいずれか。 複数のチャネルを適用するには、channeltype 定数をビット演算子でまとめます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


コメントを画像に追加する

  • ≪ Imagick::combineImages
  • Imagick::compareImageChannels ≫
  • PHP Manual
  • Imagick
  • コメントを画像に追加する

Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — コメントを画像に追加する

説明

public Imagick::commentImage(string $comment): bool

コメントを画像に追加します。

パラメータ

comment

追加するコメント。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::commentImage() の使用法

画像にコメントを追加し、そのコメントを取得します。

<?php

/* 新しい Imagick オブジェクトを作成します */
$im = new imagick();

/* 空の画像を作成します */
$im->newImage(100, 100, new ImagickPixel("red"));

/* コメントをその画像に追加します */
$im->commentImage("Hello World!");

/* コメントを表示します */
echo $im->getImageProperty("comment");

?>


ひとつあるいは複数の画像の差を返す

  • ≪ Imagick::commentImage
  • Imagick::compareImageLayers ≫
  • PHP Manual
  • Imagick
  • ひとつあるいは複数の画像の差を返す

Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す

説明

public Imagick::compareImageChannels(Imagick $image, int $channelType, int $metricType): array

ひとつあるいは複数の画像を比較し、差分の画像を返します。

パラメータ

image

比較する画像を含む Imagick オブジェクト。

channelType

そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを指定するには、チャネル型定数をビット演算子で結合します。 チャネル定数 の一覧を参照ください。

metricType

メトリック型定数 のいずれか。

戻り値

new_wand と distortion を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


複数の画像の中で最大の境界範囲を返す

  • ≪ Imagick::compareImageChannels
  • Imagick::compareImages ≫
  • PHP Manual
  • Imagick
  • 複数の画像の中で最大の境界範囲を返す

Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す

説明

public Imagick::compareImageLayers(int $method): Imagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

method

レイヤメソッド定数 のいずれか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::compareImageLayers() の使用法

画像のレイヤを比較します。

<?php
/* 新しい imagick オブジェクトを作成します */
$im = new Imagick("test.gif");

/* 画像のレイヤを最適化します */
$result = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

/* $result を使って作業をします */
?>

参考

  • Imagick::optimizeImageLayers() - 画像の繰り返し部分を削除して最適化する
  • Imagick::writeImages() - 画像あるいは画像シーケンスを書き込む
  • Imagick::writeImage() - 指定した名前で画像を書き込む


ある画像を再構築された画像と比較する

  • ≪ Imagick::compareImageLayers
  • Imagick::compositeImage ≫
  • PHP Manual
  • Imagick
  • ある画像を再構築された画像と比較する

Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — ある画像を再構築された画像と比較する

説明

public Imagick::compareImages(Imagick $compare, int $metric): array

再構築された画像と画像の差異を含む配列を返します。

パラメータ

compare

比較したい画像。

metric

メトリック定数を指定します。この メトリック定数 の一覧を参照ください。

戻り値

再構築された画像と画像の差異を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::compareImages() の使用法

画像を比較し、再構築された画像を表示します。

<?php

$image1 = new imagick("image1.png");
$image2 = new imagick("image2.png");

$result = $image1->compareImages($image2, Imagick::METRIC_MEANSQUAREERROR);
$result[0]->setImageFormat("png");

header("Content-Type: image/png");
echo $result[0];

?>


ある画像を別の画像に合成する

  • ≪ Imagick::compareImages
  • Imagick::__construct ≫
  • PHP Manual
  • Imagick
  • ある画像を別の画像に合成する

Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — ある画像を別の画像に合成する

説明

public Imagick::compositeImage(
Imagick $composite_object,
int $composite,
int $x,
int $y,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

ある画像を、別の画像の指定した位置に合成します。 合成アルゴリズムに指定する引数は、 setImageArtifact の第一パラメータに 'compose:args'、第二パラメータにデータを渡す必要があります。

パラメータ

composite_object

合成する画像を保持する Imagick オブジェクト。

compose

合成演算子。合成演算定数 を参照ください。

x

合成する位置の列オフセット。

y

合成する位置の行オフセット。

channel

そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを指定するには、チャネル型定数をビット演算子で結合します。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::compositeImage() の利用例

二つの画像を 'mathematics' 方式で合成します。

<?php

// これは、以下のコマンドを実行するのと同等の処理です
// convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

$src1 = new \Imagick("./src1.png");
$src2 = new \Imagick("./src2.png");

$src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
$src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
$src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
$src1->writeImage("./output.png");

?>

参考

  • Imagick::setImageArtifact() - 画像のアーチファクトを設定する


Imagick のコンストラクタ

  • ≪ Imagick::compositeImage
  • Imagick::contrastImage ≫
  • PHP Manual
  • Imagick
  • Imagick のコンストラクタ

Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — Imagick のコンストラクタ

説明

public Imagick::__construct(mixed $files = ?)

指定した画像あるいは画像群用に Imagick のインスタンスを作ります。

パラメータ

files

読み込みたい画像へのパス、あるいは複数のパスの配列。 パスのファイル名にはワイルドカードを含めることができ、 また URL を指定することもできます。

エラー / 例外

エラー時に ImagickException をスローします。


画像のコントラストを変更する

  • ≪ Imagick::__construct
  • Imagick::contrastStretchImage ≫
  • PHP Manual
  • Imagick
  • 画像のコントラストを変更する

Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — 画像のコントラストを変更する

説明

public Imagick::contrastImage(bool $sharpen): bool

画像の中の暗めの部分と明るめの部分の輝度の差を強調します。 sharpen に 0 以外を指定すると画像のコントラストを上げ、 0 を指定するとコントラストを下げます。

パラメータ

sharpen

シャープ値。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::contrastImage()

<?php
function contrastImage($imagePath, $contrastType) {
$imagick = new \Imagick(realpath($imagePath));
if ($contrastType != 2) {
$imagick->contrastImage($contrastType);
}

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


カラー画像のコントラストを強調する

  • ≪ Imagick::contrastImage
  • Imagick::convolveImage ≫
  • PHP Manual
  • Imagick
  • カラー画像のコントラストを強調する

Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — カラー画像のコントラストを強調する

説明

public Imagick::contrastStretchImage(float $black_point, float $white_point, int $channel = Imagick::CHANNEL_DEFAULT): bool

とりうる色の範囲全体に色を調整することによって、 カラー画像のコントラストを強調します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

black_point

黒の点。

white_point

白の点。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 デフォルトは Imagick::CHANNEL_ALL です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。


独自の畳み込み関数を画像に適用する

  • ≪ Imagick::contrastStretchImage
  • Imagick::count ≫
  • PHP Manual
  • Imagick
  • 独自の畳み込み関数を画像に適用する

Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — 独自の畳み込み関数を画像に適用する

説明

public Imagick::convolveImage(array $kernel, int $channel = Imagick::CHANNEL_DEFAULT): bool

独自の畳み込み関数を画像に適用します。

パラメータ

kernel

畳み込みの中心。

channel

そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを適用するには、定数をビット演算子で連結します。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::convolveImage()

<?php
function convolveImage($imagePath, $bias, $kernelMatrix) {
$imagick = new \Imagick(realpath($imagePath));
//$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
$imagick->setImageBias($bias * \Imagick::getQuantum());
$imagick->convolveImage($kernelMatrix);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Get the number of images

  • ≪ Imagick::convolveImage
  • Imagick::cropImage ≫
  • PHP Manual
  • Imagick
  • Get the number of images

Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Get the number of images

説明

public Imagick::count(int $mode = 0): int

Returns the number of images.

パラメータ

mode

An unused argument. Currently there is a non-particularly well defined feature in PHP where calling count() on a countable object might (or might not) require this method to accept a parameter. This parameter is here to be conformant with the interface of countable, even though the param is not used.

戻り値

Returns the number of images.


画像の一部を抽出する

  • ≪ Imagick::count
  • Imagick::cropThumbnailImage ≫
  • PHP Manual
  • Imagick
  • 画像の一部を抽出する

Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — 画像の一部を抽出する

説明

public Imagick::cropImage(
int $width,
int $height,
int $x,
int $y
): bool

画像の一部を抽出します。

パラメータ

width

抽出する幅。

height

抽出する高さ。

x

抽出する領域の左上の X 座標。

y

抽出する領域の左上の Y 座標。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::cropImage()

<?php
function cropImage($imagePath, $startX, $startY, $width, $height) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->cropImage($width, $height, $startX, $startY);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


切り取ってサムネイルを作成する

  • ≪ Imagick::cropImage
  • Imagick::current ≫
  • PHP Manual
  • Imagick
  • 切り取ってサムネイルを作成する

Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する

説明

public Imagick::cropThumbnailImage(int $width, int $height, bool $legacy = false): bool

固定サイズのサムネイルを作成します。 まず画像のサイズを拡大あるいは縮小し、指定した範囲を中心から切り取ります。

パラメータ

width

サムネイルの幅。

height

サムネイルの高さ。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


現在の Imagick オブジェクトへの参照を返す

  • ≪ Imagick::cropThumbnailImage
  • Imagick::cycleColormapImage ≫
  • PHP Manual
  • Imagick
  • 現在の Imagick オブジェクトへの参照を返す

Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — 現在の Imagick オブジェクトへの参照を返す

説明

public Imagick::current(): Imagick

現在の imagick オブジェクトへの参照を返し、 画像ポインタを正しいシーケンスに設定します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に自分自身を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のカラーマップを移動する

  • ≪ Imagick::current
  • Imagick::decipherImage ≫
  • PHP Manual
  • Imagick
  • 画像のカラーマップを移動する

Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — 画像のカラーマップを移動する

説明

public Imagick::cycleColormapImage(int $displace): bool

位置番号を指定して、画像のカラーマップを移動します。 カラーマップを何度か回転させると、サイケデリックな効果が得られます。

パラメータ

displace

カラーマップを移動させる量。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像を復号する

  • ≪ Imagick::cycleColormapImage
  • Imagick::deconstructImages ≫
  • PHP Manual
  • Imagick
  • 画像を復号する

Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — 画像を復号する

説明

public Imagick::decipherImage(string $passphrase): bool

暗号化された画像を復号します。画像の暗号化は Imagick::encipherImage() で行わなければなりません。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

passphrase

パスフレーズ。

戻り値

成功した場合に true を返します。

参考

  • Imagick::encipherImage() - 画像を暗号化する


画像間の特定のピクセルの差を返す

  • ≪ Imagick::decipherImage
  • Imagick::deleteImageArtifact ≫
  • PHP Manual
  • Imagick
  • 画像間の特定のピクセルの差を返す

Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — 画像間の特定のピクセルの差を返す

説明

public Imagick::deconstructImages(): Imagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のアーチファクトを削除する

  • ≪ Imagick::deconstructImages
  • Imagick::deleteImageProperty ≫
  • PHP Manual
  • Imagick
  • 画像のアーチファクトを削除する

Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — 画像のアーチファクトを削除する

説明

public Imagick::deleteImageArtifact(string $artifact): bool

画像に関連づけられたアーチファクトを削除します。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

artifact

削除したいアーチファクトの名前。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setImageArtifact() - 画像のアーチファクトを設定する
  • Imagick::getImageArtifact() - 画像のアーチファクトを取得する


Deletes an image property

  • ≪ Imagick::deleteImageArtifact
  • Imagick::deskewImage ≫
  • PHP Manual
  • Imagick
  • Deletes an image property

Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Deletes an image property

説明

public Imagick::deleteImageProperty(string $name): bool

Deletes an image property.

パラメータ

name

The name of the property to delete.

戻り値

成功した場合に true を返します。


傾きを除去する

  • ≪ Imagick::deleteImageProperty
  • Imagick::despeckleImage ≫
  • PHP Manual
  • Imagick
  • 傾きを除去する

Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — 傾きを除去する

説明

public Imagick::deskewImage(float $threshold): bool

このメソッドを使うと、スキャナでの読み込み時にうまく紙を置かなかった場合などの画像の傾きを除去することができます。 このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

threshold

傾き除去の閾値。

戻り値

例

例1 Imagick::deskewImage()

<?php
function deskewImage($threshold) {
$imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
$deskewImagick = clone $imagick;

//This is the only thing required for deskewing.
$deskewImagick->deskewImage($threshold);

//The rest of this example is to make the result obvious - because
//otherwise the result is not obvious.
$trim = 9;

$deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
$imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
$deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
$imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
$newCanvas = new \Imagick();
$newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
$newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
$newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

header("Content-Type: image/jpg");
echo $newCanvas->getImageBlob();
}

?>


画像内のスペックルノイズを軽減する

  • ≪ Imagick::deskewImage
  • Imagick::destroy ≫
  • PHP Manual
  • Imagick
  • 画像内のスペックルノイズを軽減する

Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — 画像内のスペックルノイズを軽減する

説明

public Imagick::despeckleImage(): bool

画像内のスペックルノイズを軽減します。ただし元画像の輪郭は保持します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::despeckleImage()

<?php
function despeckleImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->despeckleImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Imagick オブジェクトを破棄する

  • ≪ Imagick::despeckleImage
  • Imagick::displayImage ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトを破棄する

Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Imagick オブジェクトを破棄する

説明

public Imagick::destroy(): bool

Imagick オブジェクトを破棄し、関連するリソースをすべて開放します。 このメソッドは非推奨です。かわりに Imagick::clear を使いましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


画像を表示する

  • ≪ Imagick::destroy
  • Imagick::displayImages ≫
  • PHP Manual
  • Imagick
  • 画像を表示する

Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — 画像を表示する

説明

public Imagick::displayImage(string $servername): bool

このメソッドは、画像を X サーバーに表示します。

パラメータ

servername

X サーバーの名前。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像あるいは画像シーケンスを表示する

  • ≪ Imagick::displayImage
  • Imagick::distortImage ≫
  • PHP Manual
  • Imagick
  • 画像あるいは画像シーケンスを表示する

Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — 画像あるいは画像シーケンスを表示する

説明

public Imagick::displayImages(string $servername): bool

画像あるいは画像シーケンスを X サーバーに表示します。

パラメータ

servername

X サーバーの名前。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


さまざまな方式で画像を歪める

  • ≪ Imagick::displayImages
  • Imagick::drawImage ≫
  • PHP Manual
  • Imagick
  • さまざまな方式で画像を歪める

Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — さまざまな方式で画像を歪める

説明

public Imagick::distortImage(int $method, array $arguments, bool $bestfit): bool

さまざまな方式で画像を歪めます。 これは、元画像の色を新たな画像の色に対応させることで行います。 新たな画像は、'bestfit' を true に設定しない限りは元画像と同じ大きさになります。

'bestfit' を有効にし、使用する歪め方式がサイズ変更を許可していた場合は、 変換後の画像に合わせて画像のサイズやオフセットが調整されます。 多くの場合、元画像の仮想オフセットも考慮したマッピングが行われます。

このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

method

画像の歪め方式。 歪め定数 を参照ください。

arguments

歪め方式の引数。

bestfit

元画像のサイズを変更する。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::distortImage() の使用法

画像を歪めてブラウザに表示します。

<?php
/* 新しいオブジェクトを作成します */
$im = new Imagick();

/* 新しいチェッカー板パターンを作成します */
$im->newPseudoImage(100, 100, "pattern:checkerboard");

/* 画像フォーマットを png に設定します */
$im->setImageFormat('png');

/* 新しい透明な可視領域を設定します */
$im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

/* マット処理を有効にします */
$im->setImageMatte(true);

/* 歪め用の制御点 */
$controlPoints = array( 10, 10,
10, 5,

10, $im->getImageHeight() - 20,
10, $im->getImageHeight() - 5,

$im->getImageWidth() - 10, 10,
$im->getImageWidth() - 10, 20,

$im->getImageWidth() - 10, $im->getImageHeight() - 10,
$im->getImageWidth() - 10, $im->getImageHeight() - 30);

/* 歪め処理を行います */
$im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

/* 画像を出力します */
header("Content-Type: image/png");
echo $im;
?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::distortImage() の使用法

参考

  • Imagick::blurImage() - blur (にじみ) フィルタを画像に追加する
  • Imagick::motionBlurImage() - モーションブラーをシミュレートする
  • Imagick::radialBlurImage() - 画像にラジアルブラーを施す


現在の画像上の ImagickDraw オブジェクトをレンダリングする

  • ≪ Imagick::distortImage
  • Imagick::edgeImage ≫
  • PHP Manual
  • Imagick
  • 現在の画像上の ImagickDraw オブジェクトをレンダリングする

Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — 現在の画像上の ImagickDraw オブジェクトをレンダリングする

説明

public Imagick::drawImage(ImagickDraw $draw): bool

現在の画像上の ImagickDraw オブジェクトをレンダリングします。

パラメータ

draw

画像をレンダリングする描画操作。

戻り値

成功した場合に true を返します。


画像の輪郭を強調する

  • ≪ Imagick::drawImage
  • Imagick::embossImage ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭を強調する

Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — 画像の輪郭を強調する

説明

public Imagick::edgeImage(float $radius): bool

指定した半径の畳み込みフィルタを使用して、画像の輪郭を強調します。 radius に 0 を設定すると自動選択となります。

パラメータ

radius

操作の半径。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::edgeImage()

<?php
function edgeImage($imagePath, $radius) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->edgeImage($radius);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


グレースケール画像に三次元効果を施して返す

  • ≪ Imagick::edgeImage
  • Imagick::encipherImage ≫
  • PHP Manual
  • Imagick
  • グレースケール画像に三次元効果を施して返す

Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — グレースケール画像に三次元効果を施して返す

説明

public Imagick::embossImage(float $radius, float $sigma): bool

グレースケール画像に三次元効果を施したものを返します。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

パラメータ

radius

効果の半径。

sigma

効果のシグマ。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::embossImage()

<?php
function embossImage($imagePath, $radius, $sigma) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->embossImage($radius, $sigma);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を暗号化する

  • ≪ Imagick::embossImage
  • Imagick::enhanceImage ≫
  • PHP Manual
  • Imagick
  • 画像を暗号化する

Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — 画像を暗号化する

説明

public Imagick::encipherImage(string $passphrase): bool

プレーンなピクセル群を暗号化します。Imagick::decipherImage() で復号するまで、この画像は読めなくなります。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

passphrase

パスフレーズ。

戻り値

成功した場合に true を返します。

参考

  • Imagick::decipherImage() - 画像を復号する


ノイジーな画像の品質を向上させる

  • ≪ Imagick::encipherImage
  • Imagick::equalizeImage ≫
  • PHP Manual
  • Imagick
  • ノイジーな画像の品質を向上させる

Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — ノイジーな画像の品質を向上させる

説明

public Imagick::enhanceImage(): bool

デジタルフィルタを適用して、ノイジーな画像の品質を向上させます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::enhanceImage()

<?php
function enhanceImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->enhanceImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像ヒストグラムを均等化する

  • ≪ Imagick::enhanceImage
  • Imagick::evaluateImage ≫
  • PHP Manual
  • Imagick
  • 画像ヒストグラムを均等化する

Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — 画像ヒストグラムを均等化する

説明

public Imagick::equalizeImage(): bool

画像ヒストグラムを均等化します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::equalizeImage()

<?php
function equalizeImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->equalizeImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


式を画像に適用する

  • ≪ Imagick::equalizeImage
  • Imagick::exportImagePixels ≫
  • PHP Manual
  • Imagick
  • 式を画像に適用する

Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — 式を画像に適用する

説明

public Imagick::evaluateImage(int $op, float $constant, int $channel = Imagick::CHANNEL_DEFAULT): bool

算術演算、関係演算、論理演算などを画像に適用します。 これらの演算子を使用すると、画像の明度を変えたりコントラストを変えたり、 あるいは画像の "ネガ" を作成したりすることができます。

パラメータ

op

評価演算子。

constant

演算子の値。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::evaluateImage() の使用法

evaluateImage を使って画像の不透明度を減らします。

<?php
// 新しいオブジェクトを画像から作成します
$im = new Imagick('example-alpha.png');

// アルファを 50% に減らします
$im->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

// 画像を出力します
header("Content-Type: image/png");
echo $im;
?>


画像の生のピクセルをエクスポートする

  • ≪ Imagick::evaluateImage
  • Imagick::extentImage ≫
  • PHP Manual
  • Imagick
  • 画像の生のピクセルをエクスポートする

Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — 画像の生のピクセルをエクスポートする

説明

public Imagick::exportImagePixels(
int $x,
int $y,
int $width,
int $height,
string $map,
int $STORAGE
): array

画像のピクセルを配列にエクスポートします。map には、エクスポートするピクセルの順序を指定します。 返される配列の大きさは width * height * strlen(map) となります。 このメソッドは、ImageMagick バージョン 6.4.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x

エクスポートする範囲の X 座標。

y

エクスポートする範囲の Y 座標。

width

エクスポートする範囲の幅。

height

エクスポートする範囲の高さ。

map

エクスポートするピクセルの順序。"RGB" など。 map で使える文字は R, G, B, A, O, C, Y, M, K, I および P です。

STORAGE

ピクセル型定数 を参照ください。

戻り値

ピクセルの値を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::exportImagePixels() の使用法

画像のピクセルを配列にエクスポートします。

<?php

/* 新しいオブジェクトを作成します */
$im = new Imagick();

/* 新しい画像を作成します */
$im->newPseudoImage(0, 0, "magick:rose");

/* 画像のピクセルをエクスポートします。 */
$pixels = $im->exportImagePixels(10, 10, 2, 2, "RGB", Imagick::PIXEL_CHAR);

/* 出力します */
var_dump($pixels);
?>

上の例の出力は以下となります。

array(12) {
  [0]=>
  int(72)
  [1]=>
  int(64)
  [2]=>
  int(57)
  [3]=>
  int(69)
  [4]=>
  int(59)
  [5]=>
  int(43)
  [6]=>
  int(124)
  [7]=>
  int(120)
  [8]=>
  int(-96)
  [9]=>
  int(91)
  [10]=>
  int(84)
  [11]=>
  int(111)
}


画像のサイズを設定する

  • ≪ Imagick::exportImagePixels
  • Imagick::filter ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを設定する

Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — 画像のサイズを設定する

説明

public Imagick::extentImage(
int $width,
int $height,
int $x,
int $y
): bool

画像のサイズを設定するための便利なメソッドです。 このメソッドは、画像のサイズおよび新しい領域を開始する x 座標、y 座標を設定することができます。 このメソッドは、ImageMagick バージョン 6.3.1 以降で Imagick をコンパイルした場合に使用可能です。

警告

ImageMagick 6.5.7-8 (1623) より前のバージョンでは、$x は、左にシフトするときが正で右にシフトするときが負でした。 また $y は、上にシフトするときが正で下にシフトするときが負でした。 ImageMagick 6.3.7 (1591) から ImageMagick 6.5.7-8 (1623) までのどこかで、$x と $y の座標が反転しました。 つまり、$x は、左にシフトするときが負で右にシフトするときが正になりました。 また $y も、上にシフトするときが負で下にシフトするときが正になりました。 そして ImageMagick 6.5.7-8 (1623) から ImageMagick 6.6.9-7 (1641) までのどこかで、$x と $y の座標が再び反転して、ImageMagick 6.5.7-8 (1623) より前のバージョンと同じ状態に戻りました。

パラメータ

width

新しい幅。

height

新しい高さ。

x

新しいサイズの X 座標。

y

新しいサイズの Y 座標。

戻り値

成功した場合に true を返します。

参考

  • Imagick::resizeImage() - 画像のサイズを変更する
  • Imagick::thumbnailImage() - 画像のサイズを変更する
  • Imagick::cropImage() - 画像の一部を抽出する


Applies a custom convolution kernel to the image

  • ≪ Imagick::extentImage
  • Imagick::flattenImages ≫
  • PHP Manual
  • Imagick
  • Applies a custom convolution kernel to the image

Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Applies a custom convolution kernel to the image

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::filter(ImagickKernel $ImagickKernel, int $channel = Imagick::CHANNEL_UNDEFINED): bool

Applies a custom convolution kernel to the image.

パラメータ

ImagickKernel

An instance of ImagickKernel that represents either a single kernel or a linked series of kernels.

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::filter()

<?php
function filter($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$matrix = [
[-1, 0, -1],
[0, 5, 0],
[-1, 0, -1],
];

$kernel = \ImagickKernel::fromMatrix($matrix);
$strength = 0.5;
$kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
$kernel->addUnityKernel(1 - $strength);

$imagick->filter($kernel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像シーケンスをマージする

  • ≪ Imagick::filter
  • Imagick::flipImage ≫
  • PHP Manual
  • Imagick
  • 画像シーケンスをマージする

Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — 画像シーケンスをマージする

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::flattenImages(): Imagick

画像シーケンスをマージします。 これは、たとえば Photoshop のレイヤを単一の画像にまとめる場合などに便利です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


垂直方向に反転した画像を作成する

  • ≪ Imagick::flattenImages
  • Imagick::floodFillPaintImage ≫
  • PHP Manual
  • Imagick
  • 垂直方向に反転した画像を作成する

Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — 垂直方向に反転した画像を作成する

説明

public Imagick::flipImage(): bool

中心の x 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::flipImage()

<?php
function flipImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->flipImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::flopimage() - 水平方向に反転した画像を作成する


対象にマッチする任意のピクセルの値を変更する

  • ≪ Imagick::flipImage
  • Imagick::flopImage ≫
  • PHP Manual
  • Imagick
  • 対象にマッチする任意のピクセルの値を変更する

Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する

説明

public Imagick::floodFillPaintImage(
mixed $fill,
float $fuzz,
mixed $target,
int $x,
int $y,
bool $invert,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

対象にマッチするピクセルとその直接の近傍の任意のピクセルの色の値を変更します。 このメソッドは、廃止予定の Imagick::paintFloodFillImage() を置き換えるものです。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

fill

塗りつぶし色を表す ImagickPixel オブジェクトあるいは文字列。

fuzz

あいまいさをあらわす量。たとえば、これを 10 に設定すると、 赤色の値が 100 の色と 102 の色は同じものとみなされます。

target

対象の色を表す ImagickPixel オブジェクトあるいは文字列。

x

開始位置の X 座標。

y

開始位置の Y 座標。

invert

true の場合は、対象の色にマッチしない任意のピクセルをペイントします。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::floodfillPaintImage() の例

<?php

/* 新しい imagick オブジェクトを作ります */
$im = new Imagick();

/* 赤、緑、青の画像を作ります */
$im->newImage(100, 50, "red");
$im->newImage(100, 50, "green");
$im->newImage(100, 50, "blue");

/* 画像をひとつにまとめます */
$im->resetIterator();
$combined = $im->appendImages(true);

/* この時点の画像を比較用に保存します */
$combined->writeImage("floodfillpaint_intermediate.png");

/* 塗りつぶす対象となるピクセル */
$x = 1;
$y = 1;

/* 塗りつぶす色を取得します */
$target = $combined->getImagePixelColor($x, $y);

/* 1,1 の一にあるピクセルと、対象の色にマッチするすべての
近傍ピクセルを塗りつぶします */
$combined->floodfillPaintImage("black", 1, $target, $x, $y, false);

/* 結果を保存します */
$combined->writeImage("floodfillpaint_result.png");
?>

上の例の出力は、 たとえば以下のようになります。


水平方向に反転した画像を作成する

  • ≪ Imagick::floodFillPaintImage
  • Imagick::forwardFourierTransformImage ≫
  • PHP Manual
  • Imagick
  • 水平方向に反転した画像を作成する

Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — 水平方向に反転した画像を作成する

説明

public Imagick::flopImage(): bool

中心の y 軸を基準してピクセルを反転させ、水平方向のミラー画像を作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::flopImage()

<?php
function flopImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->flopImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::flipimage() - 垂直方向に反転した画像を作成する


Implements the discrete Fourier transform (DFT)

  • ≪ Imagick::flopImage
  • Imagick::frameImage ≫
  • PHP Manual
  • Imagick
  • Implements the discrete Fourier transform (DFT)

Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)

説明

public Imagick::forwardFourierTransformimage(bool $magnitude): bool

Implements the discrete Fourier transform (DFT) of the image either as a magnitude / phase or real / imaginary image pair.

パラメータ

magnitude

If true, return as magnitude / phase pair otherwise a real / imaginary image pair.

戻り値

成功した場合に true を返します。

例

例1 Imagick::forwardFourierTransformImage()

<?php
//Utility function for forwardTransformImage
function createMask() {
$draw = new \ImagickDraw();

$draw->setStrokeOpacity(0);
$draw->setStrokeColor('rgb(255, 255, 255)');
$draw->setFillColor('rgb(255, 255, 255)');

//Draw a circle on the y-axis, with it's centre
//at x, y that touches the origin
$draw->circle(250, 250, 220, 250);

$imagick = new \Imagick();
$imagick->newImage(512, 512, "black");
$imagick->drawImage($draw);
$imagick->gaussianBlurImage(20, 20);
$imagick->autoLevelImage();

return $imagick;
}

function forwardFourierTransformImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

$mask = createMask();
$imagick->forwardFourierTransformImage(true);

@$imagick->setimageindex(0);
$magnitude = $imagick->getimage();

@$imagick->setimageindex(1);
$imagickPhase = $imagick->getimage();

if (true) {
$imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
}

if (false) {
$output = clone $imagickPhase;
$output->setimageformat('png');
header("Content-Type: image/png");
echo $output->getImageBlob();
}

$magnitude->inverseFourierTransformImage($imagickPhase, true);

$magnitude->setimageformat('png');
header("Content-Type: image/png");
echo $magnitude->getImageBlob();
}

?>


三次元の枠線をシミュレートする

  • ≪ Imagick::forwardFourierTransformImage
  • Imagick::functionImage ≫
  • PHP Manual
  • Imagick
  • 三次元の枠線をシミュレートする

Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — 三次元の枠線をシミュレートする

説明

public Imagick::frameImage(
mixed $matte_color,
int $width,
int $height,
int $inner_bevel,
int $outer_bevel
): bool

画像の周りに三次元の枠線を追加します。 width と height で、それぞれ縦の枠線と横の枠線の幅を指定します。 inner_bevel および outer_bevel は、 それぞれ枠の内側と外側の影の幅を指定します。

パラメータ

matte_color

マット色を表す ImagickPixel オブジェクトあるいは文字列。

width

枠の幅。

height

枠の高さ。

inner_bevel

内側の影の幅。

outer_bevel

外側の影の幅。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::frameImage()

<?php
function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
$imagick = new \Imagick(realpath($imagePath));

$width = $width + $innerBevel + $outerBevel;
$height = $height + $innerBevel + $outerBevel;

$imagick->frameimage(
$color,
$width,
$height,
$innerBevel,
$outerBevel
);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像に関数を適用する

  • ≪ Imagick::frameImage
  • Imagick::fxImage ≫
  • PHP Manual
  • Imagick
  • 画像に関数を適用する

Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — 画像に関数を適用する

説明

public Imagick::functionImage(int $function, array $arguments, int $channel = Imagick::CHANNEL_DEFAULT): bool

算術演算、関係演算、論理演算などを疑似画像に適用します。

» ImageMagick v6 Examples - Image Transformations — Function, Multi-Argument Evaluate も参照ください。

このメソッドは、ImageMagick バージョン 6.4.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

function

関数定数 の一覧を参照ください。

arguments

この関数に渡す引数の配列。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 シヌソイドの勾配の作成

<?php
$imagick = new Imagick();
$imagick->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(3, -90);
$imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

header("Content-Type: image/png");
$imagick->setImageFormat("png");
echo $imagick->getImageBlob();
?>

上の例の出力は、 たとえば以下のようになります。

例2 多項式 (4x^2 - 4x + 1) からの勾配の作成

<?php
$imagick = new Imagick();
$imagick->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(4, -4, 1);
$imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

header("Content-Type: image/png");
$imagick->setimageformat("png");
echo $imagick->getImageBlob();
?>

上の例の出力は、 たとえば以下のようになります。

例3 多項式 (4x^2 - 4x^2 + 1) をシヌソイドの勾配で変調した、複雑な勾配の作成

<?php
$imagick1 = new Imagick();
$imagick1->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(9, -90);
$imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

$imagick2 = new Imagick();
$imagick2->newPseudoImage(200, 200, 'gradient:black-white');
$arguments = array(0.5, 0);
$imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
$imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

header("Content-Type: image/png");
$imagick1->setImageFormat("png");
echo $imagick1->getImageBlob();
?>

上の例の出力は、 たとえば以下のようになります。


式を画像の各ピクセルに適用する

  • ≪ Imagick::functionImage
  • Imagick::gammaImage ≫
  • PHP Manual
  • Imagick
  • 式を画像の各ピクセルに適用する

Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — 式を画像の各ピクセルに適用する

説明

public Imagick::fxImage(string $expression, int $channel = Imagick::CHANNEL_DEFAULT): Imagick

式を画像の各ピクセルに適用します。 詳細は » The Fx Special Effects Image Operator を参照ください。

パラメータ

expression

式。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::fxImage()

<?php
function fxImage() {
$imagick = new \Imagick();
$imagick->newPseudoImage(200, 200, "xc:white");

$fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
$fxImage = $imagick->fxImage($fx);

header("Content-Type: image/png");
$fxImage->setimageformat('png');
echo $fxImage->getImageBlob();
}

?>


画像をガンマ補正する

  • ≪ Imagick::fxImage
  • Imagick::gaussianBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像をガンマ補正する

Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — 画像をガンマ補正する

説明

public Imagick::gammaImage(float $gamma, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像をガンマ補正します。同じ画像でも、 異なるデバイス上で見ると見た目が変わることがあります。 これは、画面上に画像の輝度を表現する方法がことなるためです。 赤、緑、青の各チャネルに個別のガンマレベルを指定するか、 あるいはすべてのチャネルに共通のガンマレベルを指定します。 値の典型的な範囲は、0.8 から 2.3 の間となります。

パラメータ

gamma

ガンマ補正の量。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::gammaImage()

<?php
function gammaImage($imagePath, $gamma, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->gammaImage($gamma, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像をぼかす

  • ≪ Imagick::gammaImage
  • Imagick::getColorspace ≫
  • PHP Manual
  • Imagick
  • 画像をぼかす

Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — 画像をぼかす

説明

public Imagick::gaussianBlurImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像をぼかします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

パラメータ

radius

ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。

sigma

ガウス演算の標準偏差。ピクセル単位で指定します。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::gaussianBlurImage()

<?php
function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->gaussianBlurImage($radius, $sigma, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


色空間を取得する

  • ≪ Imagick::gaussianBlurImage
  • Imagick::getCompression ≫
  • PHP Manual
  • Imagick
  • 色空間を取得する

Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — 色空間を取得する

説明

public Imagick::getColorspace(): int

グローバル色空間の値を取得します。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

整数値を返します。この値を COLORSPACE 定数 と比較することができます。


オブジェクトの圧縮形式を取得する

  • ≪ Imagick::getColorspace
  • Imagick::getCompressionQuality ≫
  • PHP Manual
  • Imagick
  • オブジェクトの圧縮形式を取得する

Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — オブジェクトの圧縮形式を取得する

説明

public Imagick::getCompression(): int

オブジェクトの圧縮形式を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

圧縮定数を返します。


オブジェクトの圧縮品質を取得する

  • ≪ Imagick::getCompression
  • Imagick::getCopyright ≫
  • PHP Manual
  • Imagick
  • オブジェクトの圧縮品質を取得する

Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — オブジェクトの圧縮品質を取得する

説明

public Imagick::getCompressionQuality(): int

オブジェクトの圧縮品質を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

圧縮品質を表す整数値を返します。


ImageMagick API の著作権情報を文字列で返す

  • ≪ Imagick::getCompressionQuality
  • Imagick::getFilename ≫
  • PHP Manual
  • Imagick
  • ImageMagick API の著作権情報を文字列で返す

Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — ImageMagick API の著作権情報を文字列で返す

説明

public static Imagick::getCopyright(): string

ImageMagick API の著作権情報を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Imagemagick および Magickwand C API の著作権情報を含む文字列を返します。


画像シーケンスに関連付けられたファイル名を取得する

  • ≪ Imagick::getCopyright
  • Imagick::getFont ≫
  • PHP Manual
  • Imagick
  • 画像シーケンスに関連付けられたファイル名を取得する

Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — 画像シーケンスに関連付けられたファイル名を取得する

説明

public Imagick::getFilename(): string

画像シーケンスに関連付けられたファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に文字列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


フォントを取得する

  • ≪ Imagick::getFilename
  • Imagick::getFormat ≫
  • PHP Manual
  • Imagick
  • フォントを取得する

Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — フォントを取得する

説明

public Imagick::getFont(): string

オブジェクトのフォントプロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

フォント名を表す文字列を返します。フォントが設定されていない場合は false を返します。

参考

  • Imagick::setFont() - フォントを設定する
  • ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する
  • ImagickDraw::getFont() - フォントを返す


Imagick オブジェクトのフォーマットを取得する

  • ≪ Imagick::getFont
  • Imagick::getGravity ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのフォーマットを取得する

Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Imagick オブジェクトのフォーマットを取得する

説明

public Imagick::getFormat(): string

Imagick オブジェクトのフォーマットを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像フォーマットを返します。

エラー / 例外

エラー時に ImagickException をスローします。


gravity を取得する

  • ≪ Imagick::getFormat
  • Imagick::getHomeURL ≫
  • PHP Manual
  • Imagick
  • gravity を取得する

Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — gravity を取得する

説明

public Imagick::getGravity(): int

Imagick オブジェクトのグローバル gravity プロパティを取得します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

gravity プロパティを返します。 gravity 定数 の一覧を参照ください。


ImageMagick のホーム URL を返す

  • ≪ Imagick::getGravity
  • Imagick::getImage ≫
  • PHP Manual
  • Imagick
  • ImageMagick のホーム URL を返す

Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — ImageMagick のホーム URL を返す

説明

public static Imagick::getHomeURL(): string

ImageMagick のホーム URL を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

imagemagick のホームページへのリンクを返します。


新しい Imagick オブジェクトを返す

  • ≪ Imagick::getHomeURL
  • Imagick::getImageAlphaChannel ≫
  • PHP Manual
  • Imagick
  • 新しい Imagick オブジェクトを返す

Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — 新しい Imagick オブジェクトを返す

説明

public Imagick::getImage(): Imagick

現在の画像シーケンスを使用した新しい Imagick オブジェクトを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の画像シーケンスを使用した新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像がアルファチャネルを持つかを調べる

  • ≪ Imagick::getImage
  • Imagick::getImageArtifact ≫
  • PHP Manual
  • Imagick
  • 画像がアルファチャネルを持つかを調べる

Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — 画像がアルファチャネルを持つかを調べる

説明

public Imagick::getImageAlphaChannel(): bool

画像がアルファチャネルを持つかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像がアルファチャネル値を持つ場合は true を返します。 持たない場合 つまり、画像が RGBA ではなく RGB の場合。 または CMYKA ではなく、 CMYK である場合には、 false を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
imagick 3.6.0 | bool を返すようになりました。 これより前のバージョンでは、int を返していました。


画像のアーチファクトを取得する

  • ≪ Imagick::getImageAlphaChannel
  • Imagick::getImageAttribute ≫
  • PHP Manual
  • Imagick
  • 画像のアーチファクトを取得する

Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — 画像のアーチファクトを取得する

説明

public Imagick::getImageArtifact(string $artifact): string

画像に関連づけられたアーチファクトを取得します。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

artifact

アーチファクトの名前。

戻り値

成功した場合にアーチファクトの値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setImageArtifact() - 画像のアーチファクトを設定する
  • Imagick::deleteImageArtifact() - 画像のアーチファクトを削除する


Returns a named attribute

  • ≪ Imagick::getImageArtifact
  • Imagick::getImageBackgroundColor ≫
  • PHP Manual
  • Imagick
  • Returns a named attribute

Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Returns a named attribute

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageAttribute(string $key): string

Returns a named attribute.

パラメータ

key

The key of the attribute to get.

戻り値


画像の背景色を返す

  • ≪ Imagick::getImageAttribute
  • Imagick::getImageBlob ≫
  • PHP Manual
  • Imagick
  • 画像の背景色を返す

Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — 画像の背景色を返す

説明

public Imagick::getImageBackgroundColor(): ImagickPixel

画像の背景色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の背景色を設定した ImagickPixel を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像シーケンスを blob で返す

  • ≪ Imagick::getImageBackgroundColor
  • Imagick::getImageBluePrimary ≫
  • PHP Manual
  • Imagick
  • 画像シーケンスを blob で返す

Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — 画像シーケンスを blob で返す

説明

public Imagick::getImageBlob(): string

画像フォーマットを直接記憶します。 これは、画像シーケンスを文字列で返します。 画像のフォーマットによって、返される blob の形式 (GIF, JPEG, PNG, など) が決まります。 別の画像フォーマットを返すには Imagick::SetImageFormat() を使用します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像を含む文字列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


青が一番強い点を返す

  • ≪ Imagick::getImageBlob
  • Imagick::getImageBorderColor ≫
  • PHP Manual
  • Imagick
  • 青が一番強い点を返す

Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — 青が一番強い点を返す

説明

public Imagick::getImageBluePrimary(): array

青が一番強い点を返します。

パラメータ

x

青が一番強い点の x 座標。

y

青が一番強い点の y 座標。

戻り値

"x" 座標および "y" 座標を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の前景色を返す

  • ≪ Imagick::getImageBluePrimary
  • Imagick::getImageChannelDepth ≫
  • PHP Manual
  • Imagick
  • 画像の前景色を返す

Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — 画像の前景色を返す

説明

public Imagick::getImageBorderColor(): ImagickPixel

画像の前景色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


特定の画像チャネルの深度を返す

  • ≪ Imagick::getImageBorderColor
  • Imagick::getImageChannelDistortion ≫
  • PHP Manual
  • Imagick
  • 特定の画像チャネルの深度を返す

Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — 特定の画像チャネルの深度を返す

説明

public Imagick::getImageChannelDepth(int $channel): int

特定の画像チャネルの深度を返します。

パラメータ

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。


画像のチャネルを再構築した画像と比較する

  • ≪ Imagick::getImageChannelDepth
  • Imagick::getImageChannelDistortions ≫
  • PHP Manual
  • Imagick
  • 画像のチャネルを再構築した画像と比較する

Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — 画像のチャネルを再構築した画像と比較する

説明

public Imagick::getImageChannelDistortion(Imagick $reference, int $channel, int $metric): float

ひとつあるいは複数のチャネルの内容を再構築した画像と比較し、 指定した歪み係数を返します。

パラメータ

reference

比較する Imagick オブジェクト。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

metric

メトリック型定数 のいずれか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


チャネルの歪みを取得する

  • ≪ Imagick::getImageChannelDistortion
  • Imagick::getImageChannelExtrema ≫
  • PHP Manual
  • Imagick
  • チャネルの歪みを取得する

Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — チャネルの歪みを取得する

説明

public Imagick::getImageChannelDistortions(Imagick $reference, int $metric, int $channel = Imagick::CHANNEL_DEFAULT): float

ひとつあるいは複数のチャネルの内容を再構築した画像と比較し、 指定した歪み係数を返します。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

reference

比較する画像を含む Imagick オブジェクト。

metric

メトリック型定数 の一覧を参照ください。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

チャネルの歪みを表す float 型の値を返します。

エラー / 例外

エラー時に ImagickException をスローします。


ひとつあるいは複数の画像チャネルの極値を取得する

  • ≪ Imagick::getImageChannelDistortions
  • Imagick::getImageChannelKurtosis ≫
  • PHP Manual
  • Imagick
  • ひとつあるいは複数の画像チャネルの極値を取得する

Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — ひとつあるいは複数の画像チャネルの極値を取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageChannelExtrema(int $channel): array

ひとつあるいは複数の画像チャネルの極値を取得します。 戻り値は連想配列で、"minima" および "maxima" というキーを含みます。

パラメータ

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


getImageChannelKurtosis

  • ≪ Imagick::getImageChannelExtrema
  • Imagick::getImageChannelMean ≫
  • PHP Manual
  • Imagick
  • getImageChannelKurtosis

Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — getImageChannelKurtosis

説明

public Imagick::getImageChannelKurtosis(int $channel = Imagick::CHANNEL_DEFAULT): array

指定したチャネルの尖度と歪度を取得します。このメソッドは、ImageMagick バージョン 6.4.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

kurtosis と skewness を要素に持つ配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


平均値と標準偏差を取得する

  • ≪ Imagick::getImageChannelKurtosis
  • Imagick::getImageChannelRange ≫
  • PHP Manual
  • Imagick
  • 平均値と標準偏差を取得する

Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — 平均値と標準偏差を取得する

説明

public Imagick::getImageChannelMean(int $channel): array

ひとつあるいは複数の画像チャネルの平均値および標準偏差を取得します。

パラメータ

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

"mean" および "standardDeviation" というキーを含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


チャネルの範囲を取得する

  • ≪ Imagick::getImageChannelMean
  • Imagick::getImageChannelStatistics ≫
  • PHP Manual
  • Imagick
  • チャネルの範囲を取得する

Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — チャネルの範囲を取得する

説明

public Imagick::getImageChannelRange(int $channel): array

ひとつあるいは複数のチャネルの範囲を取得します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

チャネルの minima および maxima の値を含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の各チャネルの統計情報を返す

  • ≪ Imagick::getImageChannelRange
  • Imagick::getImageClipMask ≫
  • PHP Manual
  • Imagick
  • 画像の各チャネルの統計情報を返す

Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — 画像の各チャネルの統計情報を返す

説明

public Imagick::getImageChannelStatistics(): array

画像の各チャネルの統計情報を返します。 この情報に含まれるのは、チャネルの深度、最小値と最大値、 平均値、そして標準偏差です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


画像のクリップマスクを取得する

  • ≪ Imagick::getImageChannelStatistics
  • Imagick::getImageColormapColor ≫
  • PHP Manual
  • Imagick
  • 画像のクリップマスクを取得する

Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — 画像のクリップマスクを取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageClipMask(): Imagick

画像のクリップマスクを含む Imagick オブジェクトを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のクリップマスクを含む Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定したインデックスに対応する色マップ上の色を返す

  • ≪ Imagick::getImageClipMask
  • Imagick::getImageColors ≫
  • PHP Manual
  • Imagick
  • 指定したインデックスに対応する色マップ上の色を返す

Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — 指定したインデックスに対応する色マップ上の色を返す

説明

public Imagick::getImageColormapColor(int $index): ImagickPixel

指定したインデックスに対応する色マップ上の色を返します。

パラメータ

index

画像の色マップ内のオフセット。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像で使われている色の数を取得する

  • ≪ Imagick::getImageColormapColor
  • Imagick::getImageColorspace ≫
  • PHP Manual
  • Imagick
  • 画像で使われている色の数を取得する

Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — 画像で使われている色の数を取得する

説明

public Imagick::getImageColors(): int

画像で使われている色の数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像で使われているユニークな色の数を int で返します。


画像の色空間を取得する

  • ≪ Imagick::getImageColors
  • Imagick::getImageCompose ≫
  • PHP Manual
  • Imagick
  • 画像の色空間を取得する

Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — 画像の色空間を取得する

説明

public Imagick::getImageColorspace(): int

画像の色空間を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

COLORSPACE 定数 と比較できる整数を返します。


画像の合成演算子を返す

  • ≪ Imagick::getImageColorspace
  • Imagick::getImageCompression ≫
  • PHP Manual
  • Imagick
  • 画像の合成演算子を返す

Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — 画像の合成演算子を返す

説明

public Imagick::getImageCompose(): int

画像に関連付けられている合成演算子を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


現在の画像の圧縮形式を取得する

  • ≪ Imagick::getImageCompose
  • Imagick::getImageCompressionQuality ≫
  • PHP Manual
  • Imagick
  • 現在の画像の圧縮形式を取得する

Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — 現在の画像の圧縮形式を取得する

説明

public Imagick::getImageCompression(): int

現在の画像の圧縮形式を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

圧縮形式を表す定数を返します。


現在の画像の圧縮品質を取得する

  • ≪ Imagick::getImageCompression
  • Imagick::getImageDelay ≫
  • PHP Manual
  • Imagick
  • 現在の画像の圧縮品質を取得する

Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — 現在の画像の圧縮品質を取得する

説明

public Imagick::getImageCompressionQuality(): int

現在の画像の圧縮品質を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の圧縮品質を表す整数値を返します。


画像の遅延を取得する

  • ≪ Imagick::getImageCompressionQuality
  • Imagick::getImageDepth ≫
  • PHP Manual
  • Imagick
  • 画像の遅延を取得する

Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — 画像の遅延を取得する

説明

public Imagick::getImageDelay(): int

画像の遅延を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の遅延を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の深度を取得する

  • ≪ Imagick::getImageDelay
  • Imagick::getImageDispose ≫
  • PHP Manual
  • Imagick
  • 画像の深度を取得する

Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — 画像の深度を取得する

説明

public Imagick::getImageDepth(): int

画像の深度を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の深度を返します。


画像の配置方法を取得する

  • ≪ Imagick::getImageDepth
  • Imagick::getImageDistortion ≫
  • PHP Manual
  • Imagick
  • 画像の配置方法を取得する

Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — 画像の配置方法を取得する

説明

public Imagick::getImageDispose(): int

画像の配置方法を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に配置方法を返します。

エラー / 例外

エラー時に ImagickException をスローします。


ある画像と再構築した画像を比較する

  • ≪ Imagick::getImageDispose
  • Imagick::getImageExtrema ≫
  • PHP Manual
  • Imagick
  • ある画像と再構築した画像を比較する

Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — ある画像と再構築した画像を比較する

説明

public Imagick::getImageDistortion(MagickWand $reference, int $metric): float

ある画像と再構築した画像を比較し、 指定した歪み係数を返します。

パラメータ

reference

比較する Imagick オブジェクト。

metric

メトリック型定数 のいずれか。

戻り値

その画像で使用する歪み係数 (あるいはその推測値) を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の極値を取得する

  • ≪ Imagick::getImageDistortion
  • Imagick::getImageFilename ≫
  • PHP Manual
  • Imagick
  • 画像の極値を取得する

Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — 画像の極値を取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageExtrema(): array

画像の極値を取得します。 "min" および "max" というキーを持つ連想配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

"min" および "max" というキーを持つ連想配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


シーケンス内の特定の画像のファイル名を返す

  • ≪ Imagick::getImageExtrema
  • Imagick::getImageFormat ≫
  • PHP Manual
  • Imagick
  • シーケンス内の特定の画像のファイル名を返す

Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — シーケンス内の特定の画像のファイル名を返す

説明

public Imagick::getImageFilename(): string

シーケンス内の特定の画像のファイル名を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のファイル名を文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。


シーケンス内の特定の画像のフォーマットを返す

  • ≪ Imagick::getImageFilename
  • Imagick::getImageGamma ≫
  • PHP Manual
  • Imagick
  • シーケンス内の特定の画像のフォーマットを返す

Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — シーケンス内の特定の画像のフォーマットを返す

説明

public Imagick::getImageFormat(): string

シーケンス内の特定の画像のフォーマットを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合は画像のフォーマットを文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のガンマを取得する

  • ≪ Imagick::getImageFormat
  • Imagick::getImageGeometry ≫
  • PHP Manual
  • Imagick
  • 画像のガンマを取得する

Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — 画像のガンマを取得する

説明

public Imagick::getImageGamma(): float

画像のガンマを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にガンマを返します。

エラー / 例外

エラー時に ImagickException をスローします。


幅と高さを連想配列で取得する

  • ≪ Imagick::getImageGamma
  • Imagick::getImageGravity ≫
  • PHP Manual
  • Imagick
  • 幅と高さを連想配列で取得する

Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — 幅と高さを連想配列で取得する

説明

public Imagick::getImageGeometry(): array

幅と高さを連想配列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の幅と高さを表す配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getImageGeometry() を使う

<?php
$imagick = new Imagick();
$imagick->newImage(100, 200, "black");
print_r($imagick->getImageGeometry());
?>

上の例の出力は以下となります。

Array
(
    [width] => 100
    [height] => 200
)


画像の gravity を取得する

  • ≪ Imagick::getImageGeometry
  • Imagick::getImageGreenPrimary ≫
  • PHP Manual
  • Imagick
  • 画像の gravity を取得する

Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — 画像の gravity を取得する

説明

public Imagick::getImageGravity(): int

画像の原罪の current 値を取得します。 Imagick::getGravity() とは異なり、 このメソッドは原罪の画像シーケンスで定義された gravity を返します。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の property プロパティを返します。 gravity 定数 の一覧を参照ください。


緑が一番強い点を返す

  • ≪ Imagick::getImageGravity
  • Imagick::getImageHeight ≫
  • PHP Manual
  • Imagick
  • 緑が一番強い点を返す

Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — 緑が一番強い点を返す

説明

public Imagick::getImageGreenPrimary(): array

緑が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に "x" および "y" というキーを持つ配列を返します。 失敗した場合は ImagickException をスローします。

エラー / 例外

エラー時に ImagickException をスローします。


画像の高さを返す

  • ≪ Imagick::getImageGreenPrimary
  • Imagick::getImageHistogram ≫
  • PHP Manual
  • Imagick
  • 画像の高さを返す

Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — 画像の高さを返す

説明

public Imagick::getImageHeight(): int

画像の高さを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の高さをピクセル数で返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のヒストグラムを取得する

  • ≪ Imagick::getImageHeight
  • Imagick::getImageIndex ≫
  • PHP Manual
  • Imagick
  • 画像のヒストグラムを取得する

Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — 画像のヒストグラムを取得する

説明

public Imagick::getImageHistogram(): array

画像のヒストグラムを ImagickPixel オブジェクトの配列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のヒストグラムを ImagickPixel オブジェクトの配列で返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Generates Imagick::getImageHistogram()

<?php
function getColorStatistics($histogramElements, $colorChannel) {
$colorStatistics = [];

foreach ($histogramElements as $histogramElement) {
$color = $histogramElement->getColorValue($colorChannel);
$color = intval($color * 255);
$count = $histogramElement->getColorCount();

if (array_key_exists($color, $colorStatistics)) {
$colorStatistics[$color] += $count;
}
else {
$colorStatistics[$color] = $count;
}
}

ksort($colorStatistics);

return $colorStatistics;
}

function getImageHistogram($imagePath) {

$backgroundColor = 'black';

$draw = new \ImagickDraw();
$draw->setStrokeWidth(0); //make the lines be as thin as possible

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

$histogramWidth = 256;
$histogramHeight = 100; // the height for each RGB segment

$imagick = new \Imagick(realpath($imagePath));
//Resize the image to be small, otherwise PHP tends to run out of memory
//This might lead to bad results for images that are pathologically 'pixelly'
$imagick->adaptiveResizeImage(200, 200, true);
$histogramElements = $imagick->getImageHistogram();

$histogram = new \Imagick();
$histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
$histogram->setImageFormat('png');

$getMax = function ($carry, $item) {
if ($item > $carry) {
return $item;
}
return $carry;
};

$colorValues = [
'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
];

$max = array_reduce($colorValues['red'] , $getMax, 0);
$max = array_reduce($colorValues['lime'] , $getMax, $max);
$max = array_reduce($colorValues['blue'] , $getMax, $max);

$scale = $histogramHeight / $max;

$count = 0;
foreach ($colorValues as $color => $values) {
$draw->setstrokecolor($color);

$offset = ($count + 1) * $histogramHeight;

foreach ($values as $index => $value) {
$draw->line($index, $offset, $index, $offset - ($value * $scale));
}
$count++;
}

$histogram->drawImage($draw);

header( "Content-Type: image/png" );
echo $histogram;
}

?>


現在アクティブな画像のインデックスを取得する

  • ≪ Imagick::getImageHistogram
  • Imagick::getImageInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • 現在アクティブな画像のインデックスを取得する

Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — 現在アクティブな画像のインデックスを取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageIndex(): int

Imagick オブジェクト内で現在アクティブな画像のインデックスを取得します。 このメソッドは非推奨です。 Imagick::getIteratorIndex() を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

スタック内の画像のインデックスを表す整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のインターレース手法を取得する

  • ≪ Imagick::getImageIndex
  • Imagick::getImageInterpolateMethod ≫
  • PHP Manual
  • Imagick
  • 画像のインターレース手法を取得する

Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — 画像のインターレース手法を取得する

説明

public Imagick::getImageInterlaceScheme(): int

画像のインターレース手法を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に画像のインターレース手法を返します。 エラー時に ImagickException をスローします。


画像の補間方式を返す

  • ≪ Imagick::getImageInterlaceScheme
  • Imagick::getImageIterations ≫
  • PHP Manual
  • Imagick
  • 画像の補間方式を返す

Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — 画像の補間方式を返す

説明

public Imagick::getImageInterpolateMethod(): int

指定した画像の補間方式を返します。 方式は Imagick::INTERPOLATE_* 定数のいずれかで指定します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に補間方式を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の反復を取得する

  • ≪ Imagick::getImageInterpolateMethod
  • Imagick::getImageLength ≫
  • PHP Manual
  • Imagick
  • 画像の反復を取得する

Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — 画像の反復を取得する

説明

public Imagick::getImageIterations(): int

画像の反復を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の反復を表す整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の長さをバイト数で取得する

  • ≪ Imagick::getImageIterations
  • Imagick::getImageMatte ≫
  • PHP Manual
  • Imagick
  • 画像の長さをバイト数で取得する

Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — 画像の長さをバイト数で取得する

説明

public Imagick::getImageLength(): int

画像の長さをバイト数で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の画像のサイズを整数値で返します。

例

例1 Imagick::getImageLength() の使用法

画像の長さをバイト数で取得します。

<?php
$image = new Imagick('test.jpg');
echo $image->getImageLength() . ' bytes';
?>


画像がマットチャネルを持っているかどうかを返す

  • ≪ Imagick::getImageLength
  • Imagick::getImageMatteColor ≫
  • PHP Manual
  • Imagick
  • 画像がマットチャネルを持っているかどうかを返す

Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — 画像がマットチャネルを持っているかどうかを返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageMatte(): bool

画像がマットチャネルを持っている場合に true、 そうでない場合に false を返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


画像のマット色を返す

  • ≪ Imagick::getImageMatte
  • Imagick::getImageMimeType ≫
  • PHP Manual
  • Imagick
  • 画像のマット色を返す

Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — 画像のマット色を返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageMatteColor(): ImagickPixel

画像のマット色を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に ImagickPixel オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。


Returns the image mime-type

  • ≪ Imagick::getImageMatteColor
  • Imagick::getImageOrientation ≫
  • PHP Manual
  • Imagick
  • Returns the image mime-type

Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Returns the image mime-type

説明

public Imagick::getImageMimeType(): string

Returns the image mime-type.

パラメータ

この関数にはパラメータはありません。

戻り値


画像の方向を取得する

  • ≪ Imagick::getImageMimeType
  • Imagick::getImagePage ≫
  • PHP Manual
  • Imagick
  • 画像の方向を取得する

Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — 画像の方向を取得する

説明

public Imagick::getImageOrientation(): int

画像の方向を取得します。戻り値は 方向定数 のいずれかとなります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。


ページのジオメトリを返す

  • ≪ Imagick::getImageOrientation
  • Imagick::getImagePixelColor ≫
  • PHP Manual
  • Imagick
  • ページのジオメトリを返す

Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — ページのジオメトリを返す

説明

public Imagick::getImagePage(): array

画像のページジオメトリを配列で返します。配列のキーは "width"、"height"、"x" および "y" です。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のページジオメトリを配列で返します。配列のキーは "width"、"height"、"x" および "y" です。

エラー / 例外

エラー時に ImagickException をスローします。


指定したピクセルの色を返す

  • ≪ Imagick::getImagePage
  • Imagick::getImageProfile ≫
  • PHP Manual
  • Imagick
  • 指定したピクセルの色を返す

Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — 指定したピクセルの色を返す

説明

public Imagick::getImagePixelColor(int $x, int $y): ImagickPixel

指定したピクセルの色を返します。

パラメータ

x

ピクセルの x 座標。

y

ピクセルの y 座標。

戻り値

指定した座標の色を表す ImagickPixel のインスタンスを返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定した名前の画像プロファイルを返す

  • ≪ Imagick::getImagePixelColor
  • Imagick::getImageProfiles ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像プロファイルを返す

Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — 指定した名前の画像プロファイルを返す

説明

public Imagick::getImageProfile(string $name): string

指定した名前の画像プロファイルを返します。

パラメータ

name

返したいプロファイルの名前。

戻り値

画像プロファイルを含む文字列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像プロファイルを返す

  • ≪ Imagick::getImageProfile
  • Imagick::getImageProperties ≫
  • PHP Manual
  • Imagick
  • 画像プロファイルを返す

Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — 画像プロファイルを返す

説明

public Imagick::getImageProfiles(string $pattern = "*", bool $include_values = true): array

関連付けられているプロファイルのうち、パターンにマッチするものをすべて返します。 二番目の引数を false にすると、プロファイルの名前だけを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

pattern

プロファイル名のパターン。

include_values

プロファイル名のみを返すかどうか。false の場合は、プロファイル名のみを返します。

戻り値

画像のプロファイルあるいはプロファイル名を含む連想配列を返します。


画像のプロパティを返す

  • ≪ Imagick::getImageProfiles
  • Imagick::getImageProperty ≫
  • PHP Manual
  • Imagick
  • 画像のプロパティを返す

Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — 画像のプロパティを返す

説明

public Imagick::getImageProperties(string $pattern = "*", bool $include_values = true): array

関連付けられているプロパティのうち、パターンにマッチするものをすべて返します。 二番目の引数を false にすると、プロパティの名前だけを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

pattern

プロパティ名のパターン。

include_values

プロパティ名のみを返すかどうか。false の場合は、プロファイル名のみを返します。

戻り値

画像のプロパティあるいはプロパティ名を含む連想配列を返します。

例

例1 Imagick::getImageProperties() の使用法

EXIF 情報を抽出します。

<?php

/* オブジェクトを作成します */
$im = new imagick("/path/to/example.jpg");

/* EXIF 情報を取得します */
$exifArray = $im->getImageProperties("exif:*");

/* EXIF のプロパティをループします */
foreach ($exifArray as $name => $property)
{
echo "{$name} => {$property}<br />\n";
}

?>


指定した名前の画像のプロパティを返す

  • ≪ Imagick::getImageProperties
  • Imagick::getImageRedPrimary ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像のプロパティを返す

Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — 指定した名前の画像のプロパティを返す

説明

public Imagick::getImageProperty(string $name): string

指定した名前の画像プロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.2 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

name

プロパティの名前 (たとえば Exif:DateTime)。

戻り値

画像のプロパティを含む文字列を返します。 指定した名前のプロパティが存在しない場合に false を返します。

例

例1 Imagick::getImageProperty() の使用法

画像のプロパティを設定し、そして取得します。

<?php
$image = new Imagick();
$image->newImage(300, 200, "black");

$image->setImageProperty('Exif:Make', 'Imagick');
echo $image->getImageProperty('Exif:Make');
?>

参考

  • Imagick::setImageProperty() - 画像のプロパティを設定する


赤が一番強い点を返す

  • ≪ Imagick::getImageProperty
  • Imagick::getImageRegion ≫
  • PHP Manual
  • Imagick
  • 赤が一番強い点を返す

Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — 赤が一番強い点を返す

説明

public Imagick::getImageRedPrimary(): array

赤が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

赤が一番強い点を "x" および "y" というキーを持つ配列で返します。 エラー時に ImagickException をスローします。

エラー / 例外

エラー時に ImagickException をスローします。


画像の一部を抽出する

  • ≪ Imagick::getImageRedPrimary
  • Imagick::getImageRenderingIntent ≫
  • PHP Manual
  • Imagick
  • 画像の一部を抽出する

Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — 画像の一部を抽出する

説明

public Imagick::getImageRegion(
int $width,
int $height,
int $x,
int $y
): Imagick

画像の一部を抽出し、新しい Imagick オブジェクトとして返します。

パラメータ

width

抽出する範囲の幅。

height

抽出する範囲の高さ。

x

抽出する範囲の左上の X 座標。

y

抽出する範囲の左上の Y 座標。

戻り値

画像の一部を抽出し、新しい wand として返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のレンダリング方向を取得する

  • ≪ Imagick::getImageRegion
  • Imagick::getImageResolution ≫
  • PHP Manual
  • Imagick
  • 画像のレンダリング方向を取得する

Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — 画像のレンダリング方向を取得する

説明

public Imagick::getImageRenderingIntent(): int

画像のレンダリング方向を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の レンダリング方向 を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の X 方向と Y 方向の解像度を取得する

  • ≪ Imagick::getImageRenderingIntent
  • Imagick::getImagesBlob ≫
  • PHP Manual
  • Imagick
  • 画像の X 方向と Y 方向の解像度を取得する

Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — 画像の X 方向と Y 方向の解像度を取得する

説明

public Imagick::getImageResolution(): array

X 方向および Y 方向の解像度を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

解像度を配列で返します。

エラー / 例外

エラー時に ImagickException をスローします。


すべての画像シーケンスを blob で返す

  • ≪ Imagick::getImageResolution
  • Imagick::getImageScene ≫
  • PHP Manual
  • Imagick
  • すべての画像シーケンスを blob で返す

Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — すべての画像シーケンスを blob で返す

説明

public Imagick::getImagesBlob(): string

メモリ上の画像フォーマットを直接操作します。 すべての画像シーケンスを文字列として返します。 画像のフォーマット (GIF, JPEG, PNG など) に応じて返される blob の形式も異なります。 別の画像フォーマットで返すには Imagick::setImageFormat() を使用します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像を文字列で返します。失敗した場合は ImagickException をスローします。


画像のシーンを取得する

  • ≪ Imagick::getImagesBlob
  • Imagick::getImageSignature ≫
  • PHP Manual
  • Imagick
  • 画像のシーンを取得する

Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — 画像のシーンを取得する

説明

public Imagick::getImageScene(): int

画像のシーンを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像のシーンを返します。

エラー / 例外

エラー時に ImagickException をスローします。


SHA-256 メッセージダイジェストを生成する

  • ≪ Imagick::getImageScene
  • Imagick::getImageSize ≫
  • PHP Manual
  • Imagick
  • SHA-256 メッセージダイジェストを生成する

Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — SHA-256 メッセージダイジェストを生成する

説明

public Imagick::getImageSignature(): string

画像ピクセルストリームの SHA-256 メッセージダイジェストを生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

そのファイルの SHA-256 ハッシュを文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の長さをバイト数で返す

  • ≪ Imagick::getImageSignature
  • Imagick::getImageTicksPerSecond ≫
  • PHP Manual
  • Imagick
  • 画像の長さをバイト数で返す

Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — 画像の長さをバイト数で返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::getImageSize(): int

画像の長さをバイト数で返します。 非推奨です。かわりに Imagick::getImageLength() を使いましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の画像のサイズをバイト数で返します。


画像の ticks-per-second を取得する

  • ≪ Imagick::getImageSize
  • Imagick::getImageTotalInkDensity ≫
  • PHP Manual
  • Imagick
  • 画像の ticks-per-second を取得する

Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — 画像の ticks-per-second を取得する

説明

public Imagick::getImageTicksPerSecond(): int

画像の ticks-per-second を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の ticks-per-second を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の総インク密度を取得する

  • ≪ Imagick::getImageTicksPerSecond
  • Imagick::getImageType ≫
  • PHP Manual
  • Imagick
  • 画像の総インク密度を取得する

Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — 画像の総インク密度を取得する

説明

public Imagick::getImageTotalInkDensity(): float

画像の総インク密度を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の総インク密度を返します。 エラー時に ImagickException をスローします。


画像の型を取得する

  • ≪ Imagick::getImageTotalInkDensity
  • Imagick::getImageUnits ≫
  • PHP Manual
  • Imagick
  • 画像の型を取得する

Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — 画像の型を取得する

説明

public Imagick::getImageType(): int

画像の型を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の型を返します。

  • imagick::IMGTYPE_UNDEFINED
  • imagick::IMGTYPE_BILEVEL
  • imagick::IMGTYPE_GRAYSCALE
  • imagick::IMGTYPE_GRAYSCALEMATTE
  • imagick::IMGTYPE_PALETTE
  • imagick::IMGTYPE_PALETTEMATTE
  • imagick::IMGTYPE_TRUECOLOR
  • imagick::IMGTYPE_TRUECOLORMATTE
  • imagick::IMGTYPE_COLORSEPARATION
  • imagick::IMGTYPE_COLORSEPARATIONMATTE
  • imagick::IMGTYPE_OPTIMIZE

エラー / 例外

エラー時に ImagickException をスローします。


画像の解像度の単位を取得する

  • ≪ Imagick::getImageType
  • Imagick::getImageVirtualPixelMethod ≫
  • PHP Manual
  • Imagick
  • 画像の解像度の単位を取得する

Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — 画像の解像度の単位を取得する

説明

public Imagick::getImageUnits(): int

画像の解像度の単位を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の解像度の単位を返します。

エラー / 例外

エラー時に ImagickException をスローします。


仮想ピクセルメソッドを取得する

  • ≪ Imagick::getImageUnits
  • Imagick::getImageWhitePoint ≫
  • PHP Manual
  • Imagick
  • 仮想ピクセルメソッドを取得する

Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — 仮想ピクセルメソッドを取得する

説明

public Imagick::getImageVirtualPixelMethod(): int

指定した画像の仮想ピクセルメソッドを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に仮想ピクセルメソッドを返します。

エラー / 例外

エラー時に ImagickException をスローします。


色度が白い点を返す

  • ≪ Imagick::getImageVirtualPixelMethod
  • Imagick::getImageWidth ≫
  • PHP Manual
  • Imagick
  • 色度が白い点を返す

Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — 色度が白い点を返す

説明

public Imagick::getImageWhitePoint(): array

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

パラメータ

この関数にはパラメータはありません。

戻り値

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

エラー / 例外

エラー時に ImagickException をスローします。


画像の幅を返す

  • ≪ Imagick::getImageWhitePoint
  • Imagick::getInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • 画像の幅を返す

Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — 画像の幅を返す

説明

public Imagick::getImageWidth(): int

画像の幅を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の幅を返します。

エラー / 例外

エラー時に ImagickException をスローします。


オブジェクトのインターレース方式を取得する

  • ≪ Imagick::getImageWidth
  • Imagick::getIteratorIndex ≫
  • PHP Manual
  • Imagick
  • オブジェクトのインターレース方式を取得する

Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — オブジェクトのインターレース方式を取得する

説明

public Imagick::getInterlaceScheme(): int

オブジェクトのインターレース方式を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

インターレース方式 を返します。

エラー / 例外

エラー時に ImagickException をスローします。


現在アクティブな画像のインデックスを取得する

  • ≪ Imagick::getInterlaceScheme
  • Imagick::getNumberImages ≫
  • PHP Manual
  • Imagick
  • 現在アクティブな画像のインデックスを取得する

Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — 現在アクティブな画像のインデックスを取得する

説明

public Imagick::getIteratorIndex(): int

Imagick オブジェクト内で現在アクティブな画像のインデックスを取得します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

スタック内の画像のインデックスを含む整数値を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getIteratorIndex() の使用法

画像を作成し、インデックスの設定と取得を行います。

<?php
$im = new Imagick();
$im->newImage(100, 100, new ImagickPixel("red"));
$im->newImage(100, 100, new ImagickPixel("green"));
$im->newImage(100, 100, new ImagickPixel("blue"));

$im->setIteratorIndex(1);
echo $im->getIteratorIndex();
?>

参考

  • Imagick::setIteratorIndex() - イテレータの位置を設定する
  • Imagick::getImageIndex() - 現在アクティブな画像のインデックスを取得する
  • Imagick::setImageIndex() - イテレータの位置を設定する


オブジェクト内の画像の数を返す

  • ≪ Imagick::getIteratorIndex
  • Imagick::getOption ≫
  • PHP Manual
  • Imagick
  • オブジェクト内の画像の数を返す

Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — オブジェクト内の画像の数を返す

説明

public Imagick::getNumberImages(): int

Imagick オブジェクトに関連付けられている画像の数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Imagick オブジェクトに関連付けられている画像の数を返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定したキーに対応する値を返す

  • ≪ Imagick::getNumberImages
  • Imagick::getPackageName ≫
  • PHP Manual
  • Imagick
  • 指定したキーに対応する値を返す

Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — 指定したキーに対応する値を返す

説明

public Imagick::getOption(string $key): string

オブジェクト内の指定したキーに対応する値を返します。

パラメータ

key

オプションの名前。

戻り値

指定したキーに対応する値を返します。

エラー / 例外

エラー時に ImagickException をスローします。


ImageMagick パッケージ名を返す

  • ≪ Imagick::getOption
  • Imagick::getPage ≫
  • PHP Manual
  • Imagick
  • ImageMagick パッケージ名を返す

Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — ImageMagick パッケージ名を返す

説明

public static Imagick::getPackageName(): string

ImageMagick パッケージ名を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ImageMagick パッケージ名を文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。


ページのジオメトリを返す

  • ≪ Imagick::getPackageName
  • Imagick::getPixelIterator ≫
  • PHP Manual
  • Imagick
  • ページのジオメトリを返す

Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — ページのジオメトリを返す

説明

public Imagick::getPage(): array

Imagick オブジェクトに関連付けられたページのジオメトリを返します。 "width"、"height"、"x" そして "y" というキーを持つ連想配列となります。

パラメータ

この関数にはパラメータはありません。

戻り値

Imagick オブジェクトに関連付けられたページのジオメトリを返します。 "width"、"height"、"x" そして "y" というキーを持つ連想配列となります。 エラー時に ImagickException をスローします。


MagickPixelIterator を返す

  • ≪ Imagick::getPage
  • Imagick::getPixelRegionIterator ≫
  • PHP Manual
  • Imagick
  • MagickPixelIterator を返す

Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — MagickPixelIterator を返す

説明

public Imagick::getPixelIterator(): ImagickPixelIterator

MagickPixelIterator を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に ImagickPixelIterator を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getPixelIterator()

<?php
function getPixelIterator($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imageIterator = $imagick->getPixelIterator();

foreach ($imageIterator as $row => $pixels) { /* Loop through pixel rows */
foreach ($pixels as $column => $pixel) { /* Loop through the pixels in the row (columns) */
/** @var $pixel \ImagickPixel */
if ($column % 2) {
$pixel->setColor("rgba(0, 0, 0, 0)"); /* Paint every second pixel black*/
}
}
$imageIterator->syncIterator(); /* Sync the iterator, this is important to do on each iteration */
}

header("Content-Type: image/jpg");
echo $imagick;
}

?>


画像セクションの ImagickPixelIterator を取得する

  • ≪ Imagick::getPixelIterator
  • Imagick::getPointSize ≫
  • PHP Manual
  • Imagick
  • 画像セクションの ImagickPixelIterator を取得する

Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — 画像セクションの ImagickPixelIterator を取得する

説明

public Imagick::getPixelRegionIterator(
int $x,
int $y,
int $columns,
int $rows
): ImagickPixelIterator

画像セクションの ImagickPixelIterator を取得します。

パラメータ

x

範囲の x 座標。

y

範囲の y 座標。

columns

範囲の幅。

rows

範囲の高さ。

戻り値

画像セクションの ImagickPixelIterator を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::getPixelRegionIterator() の例

画像の左上のピクセルを順にたどり、それを黒に変更します。

<?php
$im = new Imagick(realpath("./testImage.png"));
$areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

foreach ($areaIterator as $rowIterator) {
foreach ($rowIterator as $pixel) {
// すべてのピクセルを黒で塗りつぶします
$pixel->setColor("rgba(0, 0, 0, 0)");
}
$areaIterator->syncIterator();
}
$im->writeImage("./output.png");
?>


ポイントサイズを取得する

  • ≪ Imagick::getPixelRegionIterator
  • Imagick::getQuantum ≫
  • PHP Manual
  • Imagick
  • ポイントサイズを取得する

Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — ポイントサイズを取得する

説明

public Imagick::getPointSize(): float

オブジェクトのポイントサイズプロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

ポイントサイズを表す float 型の値を返します。

参考

  • Imagick::setPointSize() - ポイントサイズを設定する


Returns the ImageMagick quantum range

  • ≪ Imagick::getPointSize
  • Imagick::getQuantumDepth ≫
  • PHP Manual
  • Imagick
  • Returns the ImageMagick quantum range

Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Returns the ImageMagick quantum range

説明

public static Imagick::getQuantum(): int

Returns the ImageMagick quantum range. If HDRI was enabled then the type is a float, if not it is an int.

パラメータ

この関数にはパラメータはありません。

戻り値


quantum depth を取得する

  • ≪ Imagick::getQuantum
  • Imagick::getQuantumRange ≫
  • PHP Manual
  • Imagick
  • quantum depth を取得する

Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — quantum depth を取得する

説明

public static Imagick::getQuantumDepth(): array

Imagick quantum depth を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

"quantumDepthLong" と "quantumDepthString" をキーとして持つ配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


Imagick quantum range を返す

  • ≪ Imagick::getQuantumDepth
  • Imagick::getRegistry ≫
  • PHP Manual
  • Imagick
  • Imagick quantum range を返す

Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Imagick quantum range を返す

説明

public static Imagick::getQuantumRange(): array

Imagick インスタンスの quantum range を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

quantum range を連想配列で返します。 int ("quantumRangeLong") と string ("quantumRangeString") が含まれます。

エラー / 例外

エラー時に ImagickException をスローします。


Get a StringRegistry entry

  • ≪ Imagick::getQuantumRange
  • Imagick::getReleaseDate ≫
  • PHP Manual
  • Imagick
  • Get a StringRegistry entry

Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Get a StringRegistry entry

説明

public static Imagick::getRegistry(string $key): string

Get the StringRegistry entry for the named key or false if not set.

パラメータ

key

The entry to get.

戻り値


ImageMagick のリリース日を返す

  • ≪ Imagick::getRegistry
  • Imagick::getResource ≫
  • PHP Manual
  • Imagick
  • ImageMagick のリリース日を返す

Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — ImageMagick のリリース日を返す

説明

public static Imagick::getReleaseDate(): string

ImageMagick のリリース日を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ImageMagick のリリース日を文字列で返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定したリソースのメモリ使用状況を返す

  • ≪ Imagick::getReleaseDate
  • Imagick::getResourceLimit ≫
  • PHP Manual
  • Imagick
  • 指定したリソースのメモリ使用状況を返す

Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — 指定したリソースのメモリ使用状況を返す

説明

public static Imagick::getResource(int $type): int

指定したリソースのメモリ使用状況をメガバイト単位で返します。

パラメータ

type

リソース型定数 の一覧を参照ください。

戻り値

指定したリソースのメモリ使用状況をメガバイト単位で返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定したリソースの制限を返す

  • ≪ Imagick::getResource
  • Imagick::getSamplingFactors ≫
  • PHP Manual
  • Imagick
  • 指定したリソースの制限を返す

Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — 指定したリソースの制限を返す

説明

public static Imagick::getResourceLimit(int $type): int

指定したリソースの制限を返します。

パラメータ

type

リソース型定数 のうちのひとつ。 単位は制限されるリソースのタイプに依存します。

戻り値

指定したリソースの制限をメガバイト単位で返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setResourceLimit() - 特定のリソースの制限を設定する


水平方向および垂直方向のサンプリング係数を取得する

  • ≪ Imagick::getResourceLimit
  • Imagick::getSize ≫
  • PHP Manual
  • Imagick
  • 水平方向および垂直方向のサンプリング係数を取得する

Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する

説明

public Imagick::getSamplingFactors(): array

水平方向および垂直方向のサンプリング係数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

画像の水平方向および垂直方向のサンプリング係数を含む連想配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。


Returns the size associated with the Imagick object

  • ≪ Imagick::getSamplingFactors
  • Imagick::getSizeOffset ≫
  • PHP Manual
  • Imagick
  • Returns the size associated with the Imagick object

Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Returns the size associated with the Imagick object

説明

public Imagick::getSize(): array

Get the size in pixels associated with the Imagick object, previously set by Imagick::setSize().

注意:

This method just returns the size that was set using Imagick::setSize(). If you want to get the actual width / height of the image, use Imagick::getImageWidth() and Imagick::getImageHeight().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the size associated with the Imagick object as an array with the keys "columns" and "rows".

例

例1 Getting the size of a raw RGB image set at 200x400, after scaling to 400x800 (compared to width / height)

<?php
//Set size first and then load the raw image
$img = new Imagick();
$img->setSize(200, 400);
$img->readImage("image.rgb");

$img->scaleImage(400, 800);

$size = $img->getSize();
print_r($size);

echo $img->getImageWidth()."x".$img->getImageHeight();
?>

上の例の出力は以下となります。

Array
(
    [columns] => 200
    [rows] => 400
)
400x800


サイズのオフセットを返す

  • ≪ Imagick::getSize
  • Imagick::getVersion ≫
  • PHP Manual
  • Imagick
  • サイズのオフセットを返す

Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — サイズのオフセットを返す

説明

public Imagick::getSizeOffset(): int

Imagick オブジェクトのサイズのオフセットを返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

Imagick オブジェクトのサイズのオフセットを返します。

エラー / 例外

エラー時に ImagickException をスローします。


ImageMagick API のバージョンを返す

  • ≪ Imagick::getSizeOffset
  • Imagick::haldClutImage ≫
  • PHP Manual
  • Imagick
  • ImageMagick API のバージョンを返す

Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — ImageMagick API のバージョンを返す

説明

public static Imagick::getVersion(): array

ImageMagick API のバージョンを文字列と数値で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ImageMagick API のバージョンを文字列と数値で返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像内の色を置換する

  • ≪ Imagick::getVersion
  • Imagick::hasNextImage ≫
  • PHP Manual
  • Imagick
  • 画像内の色を置換する

Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — 画像内の色を置換する

説明

public Imagick::haldClutImage(Imagick $clut, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像内の色を、Hald ルックアップテーブルを使って置換します。 Hald 画像を作るには HALD カラーコーダーを使います。

パラメータ

clut

Hald ルックアップ画像を含む Imagick オブジェクト。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::haldClutImage()

<?php
function haldClutImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
$imagickPalette->sepiatoneImage(55);
$imagick->haldClutImage($imagickPalette);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


オブジェクトが次の画像を保持しているかどうかを調べる

  • ≪ Imagick::haldClutImage
  • Imagick::hasPreviousImage ≫
  • PHP Manual
  • Imagick
  • オブジェクトが次の画像を保持しているかどうかを調べる

Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる

説明

public Imagick::hasNextImage(): bool

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。


オブジェクトが前の画像を保持しているかどうかを調べる

  • ≪ Imagick::hasNextImage
  • Imagick::identifyFormat ≫
  • PHP Manual
  • Imagick
  • オブジェクトが前の画像を保持しているかどうかを調べる

Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる

説明

public Imagick::hasPreviousImage(): bool

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば true、していなければ false を返します。


Formats a string with image details

  • ≪ Imagick::hasPreviousImage
  • Imagick::identifyImage ≫
  • PHP Manual
  • Imagick
  • Formats a string with image details

Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Formats a string with image details

説明

public Imagick::identifyFormat(string $embedText): string|false

Replaces any embedded formatting characters with the appropriate image property and returns the interpreted text. See http://www.imagemagick.org/script/escape.php for escape sequences.

パラメータ

embedText

A string containing formatting sequences e.g. "Trim box: %@ number of unique colors: %k".

戻り値

Returns format失敗した場合に false を返します.

例

例1 Imagick::identifyFormat()

<?php
$output = "Output of 'Trim box: %@ number of unique colors: %k' is: <br/>";
$imagick = new \Imagick(realpath("./images/artifact/mask.png"));
$output .= $imagick->identifyFormat("Trim box: %@ number of unique colors: %k");

?>


画像を識別し、属性を取得する

  • ≪ Imagick::identifyFormat
  • Imagick::implodeImage ≫
  • PHP Manual
  • Imagick
  • 画像を識別し、属性を取得する

Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — 画像を識別し、属性を取得する

説明

public Imagick::identifyImage(bool $appendRawOutput = false): array

画像を識別し、属性を返します。属性には画像の幅や高さ、サイズなどが含まれます。

パラメータ

appendRawOutput

true の場合、生の出力が配列に追加されます。

戻り値

画像を識別し、属性を返します。属性には画像の幅や高さ、サイズなどが含まれます。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 結果の書式の例

Array
(
    [imageName] => /some/path/image.jpg
    [format] => JPEG (Joint Photographic Experts Group JFIF format)
    [geometry] => Array
        (
            [width] => 90
            [height] => 90
        )

    [type] => TrueColor
    [colorSpace] => RGB
    [resolution] => Array
        (
            [x] => 300
            [y] => 300
        )

    [units] => PixelsPerInch
    [fileSize] => 1.88672kb
    [compression] => JPEG
    [signature] => 9a6dc8f604f97d0d691c0286176ddf992e188f0bebba98494b2146ee2d7118da
)


新しい画像をコピーとして作成する

  • ≪ Imagick::identifyImage
  • Imagick::importImagePixels ≫
  • PHP Manual
  • Imagick
  • 新しい画像をコピーとして作成する

Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — 新しい画像をコピーとして作成する

説明

public Imagick::implodeImage(float $radius): bool

既存の画像をコピーして新しい画像を作成します。 既存の画像のピクセルを、指定したパーセンテージで "内破" します。

パラメータ

radius

内破処理の半径。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::implodeImage()

<?php
function implodeImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->implodeImage(0.0001);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();

}

?>


画像のピクセルをインポートする

  • ≪ Imagick::implodeImage
  • Imagick::inverseFourierTransformImage ≫
  • PHP Manual
  • Imagick
  • 画像のピクセルをインポートする

Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — 画像のピクセルをインポートする

説明

public Imagick::importImagePixels(
int $x,
int $y,
int $width,
int $height,
string $map,
int $storage,
array $pixels
): bool

配列から画像にピクセルをインポートします。map は、通常は 'RGB' です。このメソッドのパラメータには次の制約があります。配列内のピクセルの量が、 width x height x mapの長さ と一致しなければなりません。 このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

x

画像の x 位置。

y

画像の y 位置。

width

画像の幅。

height

画像の高さ。

map

ピクセルの並び順を表す文字列。たとえば RGB のようになります。以下の文字を任意の順で組み合わせることができます。 R = red, G = green, B = blue, A = alpha (0 is transparent), O = opacity (0 is opaque), C = cyan, Y = yellow, M = magenta, K = black, I = intensity (for grayscale), P = pad.

storage

ピクセルの格納方式。 pixel 定数 の一覧を参照ください。

pixels

ピクセルの配列。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::importImagePixels() の例

<?php

/* ピクセルの配列を生成します。各色について 2000 ピクセルとなります */
$count = 2000 * 3;

$pixels =
array_merge(array_pad(array(), $count, 0),
array_pad(array(), $count, 255),
array_pad(array(), $count, 0),
array_pad(array(), $count, 255),
array_pad(array(), $count, 0));

/* 幅と高さ。ピクセル数を 3 で割った量が面積となります。
3 というのは 'RGB' からきたもので、1 ピクセルあたり 3 つの値があるということです */
$width = $height = pow((count($pixels) / 3), 0.5);

/* 空の画像を作成します */
$im = new Imagick();
$im->newImage($width, $height, 'gray');

/* ピクセルが画像に取り込みます。
width * height * strlen("RGB") が count($pixels) と一致しなければなりません */
$im->importImagePixels(0, 0, $width, $height, "RGB", Imagick::PIXEL_CHAR, $pixels);

/* jpeg 画像として出力します */
$im->setImageFormat('jpg');
header("Content-Type: image/jpg");
echo $im;

?>

上の例の出力は、 たとえば以下のようになります。

出力例 : Imagick::importImagePixels()


Implements the inverse discrete Fourier transform (DFT)

  • ≪ Imagick::importImagePixels
  • Imagick::labelImage ≫
  • PHP Manual
  • Imagick
  • Implements the inverse discrete Fourier transform (DFT)

Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)

説明

public Imagick::inverseFourierTransformImage(Imagick $complement, bool $magnitude): bool

Implements the inverse discrete Fourier transform (DFT) of the image either as a magnitude / phase or real / imaginary image pair.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

complement

The second image to combine with this one to form either the magnitude / phase or real / imaginary image pair.

magnitude

If true, combine as magnitude / phase pair otherwise a real / imaginary image pair.

戻り値

成功した場合に true を返します。


ラベルを画像に追加する

  • ≪ Imagick::inverseFourierTransformImage
  • Imagick::levelImage ≫
  • PHP Manual
  • Imagick
  • ラベルを画像に追加する

Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — ラベルを画像に追加する

説明

public Imagick::labelImage(string $label): bool

ラベルを画像に追加します。

パラメータ

label

追加するラベル。

戻り値

成功した場合に true を返します。


画像のレベルを調節する

  • ≪ Imagick::labelImage
  • Imagick::linearStretchImage ≫
  • PHP Manual
  • Imagick
  • 画像のレベルを調節する

Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — 画像のレベルを調節する

説明

public Imagick::levelImage(
float $blackPoint,
float $gamma,
float $whitePoint,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

画像のレベルを調整します。 指定した白と黒の範囲にある色を、利用可能な色の範囲全体に拡大します。 黒の点、中間点、白の点をパラメータで指定します。 黒の点は、画像の中で一番暗い色を表します。 これより暗い色の点はゼロに設定されます。 中間点は、画像に適用するガンマ補正を指定します。 黒の点は、画像の中で一番明るい色を表します。 これより明るい色の点は最大値に設定されます。

パラメータ

blackPoint

画像の黒の点。

gamma

ガンマ値。

whitePoint

画像の白の点。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::levelImage()

<?php
function levelImage($blackPoint, $gamma, $whitePoint) {
$imagick = new \Imagick();
$imagick->newPseudoimage(500, 500, 'gradient:black-white');

$imagick->setFormat('png');
$quantum = $imagick->getQuantum();
$imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


画像の輝度を引き伸ばして飽和させる

  • ≪ Imagick::levelImage
  • Imagick::liquidRescaleImage ≫
  • PHP Manual
  • Imagick
  • 画像の輝度を引き伸ばして飽和させる

Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる

説明

public Imagick::linearStretchImage(float $blackPoint, float $whitePoint): bool

画像の輝度を引き伸ばして飽和させます。

パラメータ

blackPoint

画像の黒の点。

whitePoint

画像の白の点。

戻り値

成功した場合に true を返します。

例

例1 Imagick::linearStretchImage()

<?php
function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
$imagick = new \Imagick(realpath($imagePath));
$pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
$imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を動かす

  • ≪ Imagick::linearStretchImage
  • Imagick::listRegistry ≫
  • PHP Manual
  • Imagick
  • 画像を動かす

Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — 画像を動かす

説明

public Imagick::liquidRescaleImage(
int $width,
int $height,
float $delta_x,
float $rigidity
): bool

このメソッドは、liquid rescale という方法で画像を拡大・縮小します。 このメソッドは、seam carving という技術を実装したものです。 このメソッドを期待通りに動作させるには、liblqr サポートを含めて ImageMagick をコンパイルしなければなりません。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

width

変更後のサイズの幅。

height

変更後のサイズの高さ。

delta_x

seam が x 軸をどれだけ横切るか。 0 を渡すと seam が直線になります。

rigidity

直線でない seam のバイアスを導入します。このパラメータは通常は 0 です。

戻り値

成功した場合に true を返します。

参考

  • Imagick::resizeImage() - 画像のサイズを変更する


List all the registry settings

  • ≪ Imagick::liquidRescaleImage
  • Imagick::magnifyImage ≫
  • PHP Manual
  • Imagick
  • List all the registry settings

Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — List all the registry settings

説明

public static Imagick::listRegistry(): array

List all the registry settings. Returns an array of all the key/value pairs in the registry

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing the key/values from the registry.


画像を 2 倍に比例拡大する

  • ≪ Imagick::listRegistry
  • Imagick::mapImage ≫
  • PHP Manual
  • Imagick
  • 画像を 2 倍に比例拡大する

Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — 画像を 2 倍に比例拡大する

説明

public Imagick::magnifyImage(): bool

画像を元のサイズの 2 倍に比例拡大します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::magnifyImage()

<?php
function magnifyImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->magnifyImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の色を、参照画像の中の最も近い色に置き換える

  • ≪ Imagick::magnifyImage
  • Imagick::matteFloodfillImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を、参照画像の中の最も近い色に置き換える

Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::mapImage(Imagick $map, bool $dither): bool

パラメータ

map

dither

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


色の透明度を変更する

  • ≪ Imagick::mapImage
  • Imagick::medianFilterImage ≫
  • PHP Manual
  • Imagick
  • 色の透明度を変更する

Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — 色の透明度を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::matteFloodfillImage(
float $alpha,
float $fuzz,
mixed $bordercolor,
int $x,
int $y
): bool

対象となるピクセルとその近傍の透明度を変更します。 FillToBorderMethod を指定した場合は、 画像の描画色に該当しない近傍ピクセルについても透明度を変更します。

パラメータ

alpha

不透明度レベル。1.0 は完全な不透明、0.0 は完全な透明を表します。

fuzz

画像の fuzz 値。 どの程度の色を「同じ色」とみなすかを表します。

bordercolor

輪郭の色を表す ImagickPixel オブジェクトあるいは文字列。

x

操作の開始位置の x 座標。

y

操作の開始位置の y 座標。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を 3 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


デジタルフィルタを適用する

  • ≪ Imagick::matteFloodfillImage
  • Imagick::mergeImageLayers ≫
  • PHP Manual
  • Imagick
  • デジタルフィルタを適用する

Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — デジタルフィルタを適用する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::medianFilterImage(float $radius): bool

デジタルフィルタを適用してノイジーな画像の品質を向上させます。 各ピクセルの内容を、radius で定義した近傍ピクセルの中央値で置き換えます。

パラメータ

radius

近傍ピクセルの半径。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::medianFilterImage()

<?php
function medianFilterImage($radius, $imagePath) {
$imagick = new \Imagick(realpath($imagePath));
@$imagick->medianFilterImage($radius);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像のレイヤーをマージする

  • ≪ Imagick::medianFilterImage
  • Imagick::minifyImage ≫
  • PHP Manual
  • Imagick
  • 画像のレイヤーをマージする

Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — 画像のレイヤーをマージする

説明

public Imagick::mergeImageLayers(int $layer_method): Imagick

画像のレイヤーをひとつにまとめます。このメソッドは、PSD のように複数レイヤーに対応した画像フォーマットを扱うときに便利です。 マージ処理は layer_method で制御します。ここにはレイヤーをマージする方法を定義します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

layer_method

Imagick::LAYERMETHOD_* 定数のいずれか。

戻り値

マージした画像を含む Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::mergeImageLayers()

<?php
function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

$imagick = new \Imagick(realpath($imagePath));

$imagick2 = new \Imagick(realpath($imagePath2));
$imagick->addImage($imagick2);
$imagick->setImageFormat('png');

$result = $imagick->mergeImageLayers($layerMethodType);
header("Content-Type: image/png");
echo $result->getImageBlob();
}

?>

参考

  • Imagick::flattenImages() - 画像シーケンスをマージする


画像をその半分のサイズに比例縮小する

  • ≪ Imagick::mergeImageLayers
  • Imagick::modulateImage ≫
  • PHP Manual
  • Imagick
  • 画像をその半分のサイズに比例縮小する

Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — 画像をその半分のサイズに比例縮小する

説明

public Imagick::minifyImage(): bool

画像のサイズを元の半分に比例縮小します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


明度、飽和度、色相を制御する

  • ≪ Imagick::minifyImage
  • Imagick::montageImage ≫
  • PHP Manual
  • Imagick
  • 明度、飽和度、色相を制御する

Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — 明度、飽和度、色相を制御する

説明

public Imagick::modulateImage(float $brightness, float $saturation, float $hue): bool

画像の明度、飽和度、色相を制御します。 色相は、現在位置からの絶対回転角のパーセンテージで表します。 たとえば 50 の場合は反時計回りに 90 度の回転を表します。 また 150 の場合は時計回りの 90 度の回転、0 および 200 はともに 180 度の回転を表します。

パラメータ

brightness

saturation

hue

戻り値

成功した場合に true を返します。

例

例1 Imagick::modulateImage()

<?php
function modulateImage($imagePath, $hue, $brightness, $saturation) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->modulateImage($brightness, $saturation, $hue);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


合成画像を作成する

  • ≪ Imagick::modulateImage
  • Imagick::morphImages ≫
  • PHP Manual
  • Imagick
  • 合成画像を作成する

Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — 合成画像を作成する

説明

public Imagick::montageImage(
ImagickDraw $draw,
string $tile_geometry,
string $thumbnail_geometry,
int $mode,
string $frame
): Imagick

複数の画像を合成して画像を作成します。 合成画像上で、画像の名前でタイル状に並べられます。 またオプションで各タイルの直下に画像を置くこともできます。

パラメータ

draw

フォント名、サイズ、色をこのオブジェクトから取得します。

tile_geometry

行単位、ページ単位のタイル数 (例 6x4+0+0)。

thumbnail_geometry

各サムネイルの画像サイズと枠線のサイズ (例 120x120+4+3)。

mode

サムネイルのフレームモード。 モンタージュモード定数 を参照ください。

frame

画像を枠線で囲みます (例 15x15+3+3)。 枠の色は、サムネイルのマット色となります。

戻り値

合成画像を生成し、 その情報を Imagick オブジェクトとして返します。


複数の画像をモーフィングする

  • ≪ Imagick::montageImage
  • Imagick::morphology ≫
  • PHP Manual
  • Imagick
  • 複数の画像をモーフィングする

Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — 複数の画像をモーフィングする

説明

public Imagick::morphImages(int $number_frames): Imagick

複数の画像をモーフィングします。 それぞれの画像のピクセルとサイズが線形補間され、 ある画像から次の画像へと変形していきます。

パラメータ

number_frames

生成する中間画像の数。

戻り値

このメソッドは、成功した場合に新しい Imagick オブジェクトを返します。 エラー時に ImagickException をスローします。


Applies a user supplied kernel to the image according to the given morphology method.

  • ≪ Imagick::morphImages
  • Imagick::mosaicImages ≫
  • PHP Manual
  • Imagick
  • Applies a user supplied kernel to the image according to the given morphology method.

Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.

説明

public Imagick::morphology(
int $morphologyMethod,
int $iterations,
ImagickKernel $ImagickKernel,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

Applies a user supplied kernel to the image according to the given morphology method.

パラメータ

morphologyMethod

Which morphology method to use one of the \Imagick::MORPHOLOGY_* constants.

iterations

The number of iteration to apply the morphology function. A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.

ImagickKernel

channel

戻り値

成功した場合に true を返します。

例

例1 Convolve Imagick::morphology()

<?php
$imagick = $this->getCharacter();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
$imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
header("Content-Type: image/png");
echo $imagick->getImageBlob();

?>

例2 Correlate Imagick::morphology()

<?php

// Top-left pixel must be black
// Bottom right pixel must be white
// We don't care about the rest.

$imagick = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
$imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
header("Content-Type: image/png");
echo $imagick->getImageBlob();

?>

例3 Erode Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例4 Erode Intensity Imagick::morphology()

<?php
$canvas = $this->getCharacter();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
$canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例5 Dilate Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例6 Dilate intensity Imagick::morphology()

<?php
$canvas = $this->getCharacter();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
$canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例7 Distance with Chebyshev kernel Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
$canvas->autoLevelImage();
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例8 Distance with Manhattan kernel Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
$canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
$canvas->autoLevelImage();
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例9 Distance with ocatagonal kernel Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
$canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
$canvas->autoLevelImage();
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例10 Distance with Euclidean kernel Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
$canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
$canvas->autoLevelImage();
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例11 Edge Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例12 Open Imagick::morphology()

<?php
// As a result you will see that 'Open' smoothed the outline, by rounding off any sharp points, and remove any parts that is smaller than the shape used. It will also disconnect or 'open' any thin bridges.
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
$canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例13 Open intensity Imagick::morphology()

<?php
// As a result you will see that 'Open' smoothed the outline, by rounding off any sharp points, and remove any parts that is smaller than the shape used. It will also disconnect or 'open' any thin bridges.

$canvas = $this->getCharacter();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
$canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例14 Close Imagick::morphology()

<?php
//The basic use of the 'Close' method is to reduce or remove any 'holes' or 'gaps' about the size of the kernel 'Structure Element'. That is 'close' parts of the background that are about that size.
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
$canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例15 Close Intensity Imagick::morphology()

<?php
//The basic use of the 'Close' method is to reduce or remove any 'holes' or 'gaps' about the size of the kernel 'Structure Element'. That is 'close' parts of the background that are about that size.
$canvas = $this->getCharacter();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
$canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例16 Smooth Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例17 Edge in Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例18 Edge out Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
$canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例19 The 'TopHat' method, or more specifically 'White Top Hat', returns the pixels that were removed by a Opening of the shape, that is the pixels that were removed to round off the points, and the connecting bridged between shapes. Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
$canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例20 The 'BottomHat' method, also known as 'Black TopHat' is the pixels that a Closing of the shape adds to the image. That is the pixels that were used to fill in the 'holes', 'gaps', and 'bridges'. Imagick::morphology()

<?php

$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
$canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例21 Hit and Miss Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
//This finds all the pixels with 3 pixels of the right edge
$matrix = [[1, false, false, 0]];
$kernel = \ImagickKernel::fromMatrix(
$matrix,
[0, 0]
);
$canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例22 Thinning Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
$rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
$leftEdgeKernel->addKernel($rightEdgeKernel);

$canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例23 Thicken Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
$rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
$leftEdgeKernel->addKernel($rightEdgeKernel);

$canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例24 Thick to generate a convex hull Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
$convexKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

// The thicken morphology doesn't handle small gaps. We close them
// with the close morphology.
$canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
$canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
$canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例25 Iterative morphology Imagick::morphology()

<?php
$canvas = $this->getCharacterOutline();
$kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
$canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
$canvas->autoLevelImage();
header("Content-Type: image/png");
echo $canvas->getImageBlob();

?>

例26 Helper function to get an image silhouette Imagick::morphology()

<?php
function getCharacterOutline() {
$imagick = new \Imagick(realpath("./images/character.png"));
$character = new \Imagick();
$character->newPseudoImage(
$imagick->getImageWidth(),
$imagick->getImageHeight(),
"canvas:white"
);
$canvas = new \Imagick();
$canvas->newPseudoImage(
$imagick->getImageWidth(),
$imagick->getImageHeight(),
"canvas:black"
);

$character->compositeimage(
$imagick,
\Imagick::COMPOSITE_COPYOPACITY,
0, 0
);
$canvas->compositeimage(
$character,
\Imagick::COMPOSITE_ATOP,
0, 0
);
$canvas->setFormat('png');

return $canvas;
}
?>


画像からモザイクを作成する

  • ≪ Imagick::morphology
  • Imagick::motionBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像からモザイクを作成する

Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — 画像からモザイクを作成する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::mosaicImages(): Imagick

画像シーケンスをはめ込み合成して単一の画像にします。 シーケンス内の各画像を、画像のページオフセットで指定した位置に合成したものを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


モーションブラーをシミュレートする

  • ≪ Imagick::mosaicImages
  • Imagick::negateImage ≫
  • PHP Manual
  • Imagick
  • モーションブラーをシミュレートする

Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — モーションブラーをシミュレートする

説明

public Imagick::motionBlurImage(
float $radius,
float $sigma,
float $angle,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

モーションブラーをシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、MotionBlurImage() が適切な半径を自動的に設定します。 angle にはぼかしをかける角度を指定します。

パラメータ

radius

ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。

sigma

ガウス演算の標準偏差。ピクセル単位で指定します。

angle

この角度で効果を適用します。

channel

そのチャンネルモードで使用可能な任意のチャンネル定数を指定します。 複数を指定する場合はビット演算子を使用します。 チャンネル定数 の一覧を参照ください。 この引数が有効になるのは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合のみです。

戻り値

成功した場合に true を返します。

例

例1 Imagick::motionBlurImage()

<?php
function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->motionBlurImage($radius, $sigma, $angle, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の色を打ち消す

  • ≪ Imagick::motionBlurImage
  • Imagick::newImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を打ち消す

Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — 画像の色を打ち消す

説明

public Imagick::negateImage(bool $gray, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像の色を打ち消します。グレースケールオプションを指定すると、 画像内のグレースケール値のみを打ち消します。

パラメータ

gray

画像内のグレースケールのみを打ち消すのかどうか。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::negateImage()

<?php
function negateImage($imagePath, $grayOnly, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->negateImage($grayOnly, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


新しい画像を作成する

  • ≪ Imagick::negateImage
  • Imagick::newPseudoImage ≫
  • PHP Manual
  • Imagick
  • 新しい画像を作成する

Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — 新しい画像を作成する

説明

public Imagick::newImage(
int $cols,
int $rows,
mixed $background,
string $format = ?
): bool

新しい画像を作成し、ImagickPixel の値を背景色として関連付けます。

パラメータ

cols

新しい画像のカラム数。

rows

新しい画像の行数。

background

この画像で使用する背景色。

format

画像フォーマット。このパラメータは Imagick バージョン 2.0.1 で追加されました。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を 3 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::newImage() の使用法

新しい画像を作成し、それを表示します。

<?php

$image = new Imagick();
$image->newImage(100, 100, new ImagickPixel('red'));
$image->setImageFormat('png');

header('Content-type: image/png');
echo $image;

?>


新しい画像を作成する

  • ≪ Imagick::newImage
  • Imagick::nextImage ≫
  • PHP Manual
  • Imagick
  • 新しい画像を作成する

Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — 新しい画像を作成する

説明

public Imagick::newPseudoImage(int $columns, int $rows, string $pseudoString): bool

新しい画像を、ImageMagick 疑似フォーマットを使用して作成します。

パラメータ

columns

新しい画像のカラム数。

rows

新しい画像の行数。

pseudoString

疑似画像定義を含む文字列。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::newPseudoImage()

<?php
function newPseudoImage($canvasType) {
$imagick = new \Imagick();
$imagick->newPseudoImage(300, 300, $canvasType);
$imagick->setImageFormat("png");
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

//newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
//newPseudoImage("radial-gradient:red-blue");
newPseudoImage("plasma:fractal");

?>


次の画像に移動する

  • ≪ Imagick::newPseudoImage
  • Imagick::normalizeImage ≫
  • PHP Manual
  • Imagick
  • 次の画像に移動する

Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — 次の画像に移動する

説明

public Imagick::nextImage(): bool

画像リスト内の次の画像を Imagick オブジェクトに関連付けます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


カラー画像のコントラストを強調する

  • ≪ Imagick::nextImage
  • Imagick::oilPaintImage ≫
  • PHP Manual
  • Imagick
  • カラー画像のコントラストを強調する

Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — カラー画像のコントラストを強調する

説明

public Imagick::normalizeImage(int $channel = Imagick::CHANNEL_DEFAULT): bool

カラー画像のコントラストを強調します。 ピクセルの色を、とりうる値の範囲全体に拡張します。

パラメータ

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::normalizeImage()

<?php
function normalizeImage($imagePath, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$original = clone $imagick;
$original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
$imagick->normalizeImage($channel);
$imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


油絵をシミュレートする

  • ≪ Imagick::normalizeImage
  • Imagick::opaquePaintImage ≫
  • PHP Manual
  • Imagick
  • 油絵をシミュレートする

Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — 油絵をシミュレートする

説明

public Imagick::oilPaintImage(float $radius): bool

油絵風の効果を施すフィルタを適用します。 各ピクセルが、指定した半径内の周囲の中で最もよくあらわれる色に置き換えられます。

パラメータ

radius

近傍円の半径。

戻り値

成功した場合に true を返します。

例

例1 Imagick::oilPaintImage()

<?php
function oilPaintImage($imagePath, $radius) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->oilPaintImage($radius);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


対象にマッチする任意のピクセルの色を変更する

  • ≪ Imagick::oilPaintImage
  • Imagick::optimizeImageLayers ≫
  • PHP Manual
  • Imagick
  • 対象にマッチする任意のピクセルの色を変更する

Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — 対象にマッチする任意のピクセルの色を変更する

説明

public Imagick::opaquePaintImage(
mixed $target,
mixed $fill,
float $fuzz,
bool $invert,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

マッチする任意のピクセルの色を、fill で定義した色に変更します。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

target

変更したい色をあらわす ImagickPixel オブジェクトあるいは文字列。

fill

置き換える色。

fuzz

あいまいさをあらわす量。たとえば、これを 10 に設定すると、 赤色の値が 100 の色と 102 の色は同じものとみなされます。

invert

true の場合は、対象の色にマッチしないピクセルを変更します。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。


画像の繰り返し部分を削除して最適化する

  • ≪ Imagick::opaquePaintImage
  • Imagick::orderedPosterizeImage ≫
  • PHP Manual
  • Imagick
  • 画像の繰り返し部分を削除して最適化する

Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — 画像の繰り返し部分を削除して最適化する

説明

public Imagick::optimizeImageLayers(): bool

GIF 形式の画像を、シーケンス内のひとつ前の画像と比較します。 必要最小限の画像で各フレームを置き換え、結果のアニメーションはそのままとなるようにします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::optimizeImageLayers() の使用法

GIF 画像を読み込み、最適化して書き出します。

<?php
/* 新しい imagick オブジェクトを作成します */
$im = new Imagick("test.gif");

/* 画像のレイヤを最適化します */
$im->optimizeImageLayers();

/* 画像を書き戻します */
$im->writeImages("test_optimized.gif", true);
?>

参考

  • Imagick::compareImageLayers() - 複数の画像の中で最大の境界範囲を返す
  • Imagick::writeImages() - 画像あるいは画像シーケンスを書き込む
  • Imagick::writeImage() - 指定した名前で画像を書き込む


配列ディザリングを行う

  • ≪ Imagick::optimizeImageLayers
  • Imagick::paintFloodfillImage ≫
  • PHP Manual
  • Imagick
  • 配列ディザリングを行う

Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — 配列ディザリングを行う

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::orderedPosterizeImage(string $threshold_map, int $channel = Imagick::CHANNEL_DEFAULT): bool

定義済みのディザリング閾値マップにもとづいた、複数の強度レベルによる配列ディザリングを行います。 入力の引数に応じて、各チャネルで異なるレベルを使用することができます。 このメソッドは、ImageMagick バージョン 6.3.1 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

threshold_map

使用するディザリング閾値マップを含む文字列。

channel

チャネルモードに応じたチャネル定数を指定します。 複数のチャネルに適用するには、定数をビット演算子で組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::orderedPosterizeImage()

<?php
function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
$imagick = new \Imagick(realpath($imagePath));

$imagick->orderedPosterizeImage($orderedPosterizeType);
$imagick->setImageFormat('png');

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

//orderedPosterizeImage($imagePath, 'o4x4,3,3');
//orderedPosterizeImage($imagePath, 'o8x8,6,6');
orderedPosterizeImage($imagePath, 'h8x8a');

?>


色にマッチするピクセルを変更する

  • ≪ Imagick::orderedPosterizeImage
  • Imagick::paintOpaqueImage ≫
  • PHP Manual
  • Imagick
  • 色にマッチするピクセルを変更する

Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — 色にマッチするピクセルを変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::paintFloodfillImage(
mixed $fill,
float $fuzz,
mixed $bordercolor,
int $x,
int $y,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

対象にマッチするピクセルとその近傍の色を変更します。 ImageMagick 6.3.8 以降はこのメソッドは非推奨となりました。かわりに Imagick::floodfillPaintImage() を使用します。

パラメータ

fill

塗りつぶし色を表す ImagickPixel オブジェクトあるいは文字列。

fuzz

fuzz の量。たとえば fuzz を 10 にすると、 強度 100 の赤と 102 の赤は同じ色とみなします。

bordercolor

境界色を表す ImagickPixel オブジェクトあるいは文字列。

x

floodfill の開始位置の X 座標。

y

floodfill の開始位置の Y 座標。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。


色にマッチするピクセルを変更する

  • ≪ Imagick::paintFloodfillImage
  • Imagick::paintTransparentImage ≫
  • PHP Manual
  • Imagick
  • 色にマッチするピクセルを変更する

Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — 色にマッチするピクセルを変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::paintOpaqueImage(
mixed $target,
mixed $fill,
float $fuzz,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

色にマッチするピクセルを、塗りつぶし色に変更します。

パラメータ

target

この対象色を変更すると、画像の塗りつぶし色が変わります。 ImagickPixel オブジェクトあるいは文字列で対象色を指定します。

fill

塗りつぶし色を表す ImagickPixel オブジェクトあるいは文字列。

fuzz

画像の fuzz 値。 どの程度の色を「同じ色」とみなすかを表します。

channel

チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初と 2 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


色にマッチするピクセルを塗りつぶし色に変更する

  • ≪ Imagick::paintOpaqueImage
  • Imagick::pingImage ≫
  • PHP Manual
  • Imagick
  • 色にマッチするピクセルを塗りつぶし色に変更する

Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — 色にマッチするピクセルを塗りつぶし色に変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::paintTransparentImage(mixed $target, float $alpha, float $fuzz): bool

塗りつぶし色に指定した色にマッチするピクセルを変更します。

パラメータ

target

この対象色を変更して、画像の不透明度を指定します。

alpha

不透明度レベル。1.0 は完全な不透明、0.0 は完全な透明を表します。

fuzz

画像の fuzz 値。 どの程度の色を「同じ色」とみなすかを表します。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


画像の基本属性を取得する

  • ≪ Imagick::paintTransparentImage
  • Imagick::pingImageBlob ≫
  • PHP Manual
  • Imagick
  • 画像の基本属性を取得する

Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — 画像の基本属性を取得する

説明

public Imagick::pingImage(string $filename): bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。

パラメータ

filename

情報を読み込むファイル名。

戻り値

成功した場合に true を返します。


手早く属性を取得する

  • ≪ Imagick::pingImage
  • Imagick::pingImageFile ≫
  • PHP Manual
  • Imagick
  • 手早く属性を取得する

Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — 手早く属性を取得する

説明

public Imagick::pingImageBlob(string $image): bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

image

画像を含む文字列。

戻り値

成功した場合に true を返します。

例

例1 Imagick::pingImageBlob() の使用法

文字列から画像の情報を読み込みます。

<?php
/* 画像コンテンツを読み込みます */
$image = file_get_contents("test.jpg");

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* 文字列を imagick オブジェクトに渡します */
$im->pingImageBlob($image);

/* 画像の幅と高さを出力します */
echo $im->getImageWidth() . 'x' . $im->getImageHeight();
?>

参考

  • Imagick::pingImage() - 画像の基本属性を取得する
  • Imagick::pingImageFile() - 画像の基本属性を手軽に取得する
  • Imagick::readImage() - ファイルから画像を読み込む
  • Imagick::readImageBlob() - バイナリ文字列から画像を読み込む
  • Imagick::readImageFile() - オープンしているファイルハンドルから画像を読み込む


画像の基本属性を手軽に取得する

  • ≪ Imagick::pingImageBlob
  • Imagick::polaroidImage ≫
  • PHP Manual
  • Imagick
  • 画像の基本属性を手軽に取得する

Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — 画像の基本属性を手軽に取得する

説明

public Imagick::pingImageFile(resource $filehandle, string $fileName = ?): bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

filehandle

開いている画像のファイルハンドル。

fileName

オプションで指定する、この画像のファイル名。

戻り値

成功した場合に true を返します。

例

例1 Imagick::pingImageFile() の使用法

リモートファイルを開きます。

<?php
/* リモートファイルを fopen します */
$fp = fopen("http://example.com/test.jpg");

/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* ハンドルを imagick に渡します */
$im->pingImageFile($fp);
?>

参考

  • Imagick::pingImage() - 画像の基本属性を取得する
  • Imagick::pingImageBlob() - 手早く属性を取得する
  • Imagick::readImage() - ファイルから画像を読み込む
  • Imagick::readImageBlob() - バイナリ文字列から画像を読み込む
  • Imagick::readImageFile() - オープンしているファイルハンドルから画像を読み込む


ポラロイド写真をシミュレートする

  • ≪ Imagick::pingImageFile
  • Imagick::posterizeImage ≫
  • PHP Manual
  • Imagick
  • ポラロイド写真をシミュレートする

Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — ポラロイド写真をシミュレートする

説明

public Imagick::polaroidImage(ImagickDraw $properties, float $angle): bool

ポラロイド写真をシミュレートします。 このメソッドは、ImageMagick バージョン 6.3.2 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

properties

ポラロイドプロパティ。

angle

ポラロイド角度。

戻り値

成功した場合に true を返します。

例

例1 Imagick::polaroidImage() の例

Imagick::polaroidImage() の使用法です。

<?php
/* オブジェクトを作成します */
$image = new Imagick('source.png');

/* 透明度を設定します */
$image->polaroidImage(new ImagickDraw(), 25);

/* 画像を出力します */
header('Content-type: image/png');
echo $image;

?>


指定した色数まで画像を減色する

  • ≪ Imagick::polaroidImage
  • Imagick::previewImages ≫
  • PHP Manual
  • Imagick
  • 指定した色数まで画像を減色する

Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — 指定した色数まで画像を減色する

説明

public Imagick::posterizeImage(int $levels, bool $dither): bool

指定した色数まで画像を減色します。

パラメータ

levels

dither

戻り値

成功した場合に true を返します。

例

例1 Imagick::posterizeImage()

<?php
function posterizeImage($imagePath, $posterizeType, $numberLevels) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->posterizeImage($numberLevels, $posterizeType);
$imagick->setImageFormat('png');
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

?>


画像処理用の適切なパラメータを手早く取得する

  • ≪ Imagick::posterizeImage
  • Imagick::previousImage ≫
  • PHP Manual
  • Imagick
  • 画像処理用の適切なパラメータを手早く取得する

Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — 画像処理用の適切なパラメータを手早く取得する

説明

public Imagick::previewImages(int $preview): bool

指定した画像の 9 枚のサムネイルをタイル状に並べ、 さまざまな強度で画像処理を適用します。 これは、画像処理操作のパラメータの適切な値を手早く知りたい場合に便利です。

パラメータ

preview

プレビュー形式。プレビュー形式の定数 を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


オブジェクト内の前の画像に移動する

  • ≪ Imagick::previewImages
  • Imagick::profileImage ≫
  • PHP Manual
  • Imagick
  • オブジェクト内の前の画像に移動する

Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — オブジェクト内の前の画像に移動する

説明

public Imagick::previousImage(): bool

画像リスト内の前の画像を Imagick オブジェクトに関連付けます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


画像のプロファイルを追加あるいは削除する

  • ≪ Imagick::previousImage
  • Imagick::quantizeImage ≫
  • PHP Manual
  • Imagick
  • 画像のプロファイルを追加あるいは削除する

Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — 画像のプロファイルを追加あるいは削除する

説明

public Imagick::profileImage(string $name, ?string $profile): bool

ICC、IPTC あるいは汎用のプロファイルを画像に追加あるいは削除します。 profile が NULL の場合は画像からプロファイルを削除し、 それ以外の場合は追加します。 name に '*'、profile に NULL を指定すると、画像からすべてのプロパティを削除します。

パラメータ

name

profile

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


参照画像内の色を解析する

  • ≪ Imagick::profileImage
  • Imagick::quantizeImages ≫
  • PHP Manual
  • Imagick
  • 参照画像内の色を解析する

Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — 参照画像内の色を解析する

説明

public Imagick::quantizeImage(
int $numberColors,
int $colorspace,
int $treedepth,
bool $dither,
bool $measureError
): bool

パラメータ

numberColors

colorspace

treedepth

dither

measureError

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::quantizeImage()

<?php
function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
$imagick->setImageFormat('png');
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


画像シーケンス内の色を解析する

  • ≪ Imagick::quantizeImage
  • Imagick::queryFontMetrics ≫
  • PHP Manual
  • Imagick
  • 画像シーケンス内の色を解析する

Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — 画像シーケンス内の色を解析する

説明

public Imagick::quantizeImages(
int $numberColors,
int $colorspace,
int $treedepth,
bool $dither,
bool $measureError
): bool

パラメータ

numberColors

colorspace

treedepth

dither

measureError

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


フォントメトリクスを表す配列を返す

  • ≪ Imagick::quantizeImages
  • Imagick::queryFonts ≫
  • PHP Manual
  • Imagick
  • フォントメトリクスを表す配列を返す

Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — フォントメトリクスを表す配列を返す

説明

public Imagick::queryFontMetrics(ImagickDraw $properties, string $text, bool $multiline = ?): array

フォントメトリクスを表す、多次元配列を返します。

パラメータ

properties

フォントのプロパティを含む ImagickDraw オブジェクト。

text

テキスト。

multiline

マルチラインパラメータ。空にすると自動検出します。

戻り値

フォントメトリクスを表す、多次元配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::queryFontMetrics() の使用法

テキストのメトリクスを取得し、画面上に結果を表示します。

<?php
/* 新しい Imagick オブジェクトを作成します */
$im = new Imagick();

/* ImagickDraw オブジェクトを作成します */
$draw = new ImagickDraw();

/* フォントを設定します */
$draw->setFont('/path/to/font.ttf');

/* フォントメトリクスを出力します。複数行を自動検出します */
var_dump($im->queryFontMetrics($draw, "Hello World!"));
?>


設定したフォントを返す

  • ≪ Imagick::queryFontMetrics
  • Imagick::queryFormats ≫
  • PHP Manual
  • Imagick
  • 設定したフォントを返す

Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — 設定したフォントを返す

説明

public static Imagick::queryFonts(string $pattern = "*"): array

設定したフォントを返します。

パラメータ

pattern

クエリパターン。

戻り値

フォントを含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::queryFonts()

<?php
$output = '';
$output .= "Fonts that match 'Helvetica*' are:<br/>";

$fontList = \Imagick::queryFonts("Helvetica*");

foreach ($fontList as $fontName) {
$output .= '<li>'. $fontName."</li>";
}

return $output;

?>


Imagick がサポートするフォーマットを返す

  • ≪ Imagick::queryFonts
  • Imagick::radialBlurImage ≫
  • PHP Manual
  • Imagick
  • Imagick がサポートするフォーマットを返す

Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Imagick がサポートするフォーマットを返す

説明

public static Imagick::queryFormats(string $pattern = "*"): array

Imagick がサポートするフォーマットを返します。

パラメータ

pattern

戻り値

Imagick がサポートするフォーマットを含む配列を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::queryFormats()

<?php
function render() {
$output = "";
$input = \Imagick::queryformats();
$columns = 6;

$output .= "<table border='2'>";

for ($i=0; $i < count($input); $i += $columns) {
$output .= "<tr>";
for ($c=0; $c<$columns; $c++) {
$output .= "<td>";
if (($i + $c) < count($input)) {
$output .= $input[$i + $c];
}
$output .= "</td>";
}
$output .= "</tr>";
}

$output .= "</table>";

return $output;
}

?>


画像にラジアルブラーを施す

  • ≪ Imagick::queryFormats
  • Imagick::raiseImage ≫
  • PHP Manual
  • Imagick
  • 画像にラジアルブラーを施す

Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — 画像にラジアルブラーを施す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::radialBlurImage(float $angle, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像にラジアルブラーを施します。

パラメータ

angle

channel

戻り値

成功した場合に true を返します。

例

例1 Imagick::radialBlurImage()

<?php
function radialBlurImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
//Blur 3 times with different radii
$imagick->radialBlurImage(3);
$imagick->radialBlurImage(5);
$imagick->radialBlurImage(7);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


三次元のボタン風の効果をシミュレートする

  • ≪ Imagick::radialBlurImage
  • Imagick::randomThresholdImage ≫
  • PHP Manual
  • Imagick
  • 三次元のボタン風の効果をシミュレートする

Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — 三次元のボタン風の効果をシミュレートする

説明

public Imagick::raiseImage(
int $width,
int $height,
int $x,
int $y,
bool $raise
): bool

画像の輪郭を明るくしたり暗くしたりすることによって、 三次元のボタン風の効果をシミュレートします。 raise_info のメンバ width および height が、 垂直方向および水平方向の効果の輪郭を定義します。

パラメータ

width

height

x

y

raise

戻り値

成功した場合に true を返します。

例

例1 Imagick::raiseImage()

<?php
function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
$imagick = new \Imagick(realpath($imagePath));

//x and y do nothing?
$imagick->raiseImage($width, $height, $x, $y, $raise);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


コントラストの高い 2 色の画像を作成する

  • ≪ Imagick::raiseImage
  • Imagick::readImage ≫
  • PHP Manual
  • Imagick
  • コントラストの高い 2 色の画像を作成する

Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — コントラストの高い 2 色の画像を作成する

説明

public Imagick::randomThresholdImage(float $low, float $high, int $channel = Imagick::CHANNEL_DEFAULT): bool

個々のピクセルの輝度を閾値と比較し、その色を変更します。 変換結果は、コントラストの高い 2 色の画像となります。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

low

低い点。

high

高い点。

channel

そのモードに対応した任意のチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数をビット演算子で連結します。 この チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::randomThresholdImage()

<?php
function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
$imagick = new \Imagick(realpath($imagePath));

$imagick->randomThresholdimage(
$lowThreshold * \Imagick::getQuantum(),
$highThreshold * \Imagick::getQuantum(),
$channel
);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


ファイルから画像を読み込む

  • ≪ Imagick::randomThresholdImage
  • Imagick::readImageBlob ≫
  • PHP Manual
  • Imagick
  • ファイルから画像を読み込む

Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — ファイルから画像を読み込む

説明

public Imagick::readImage(string $filename): bool

ファイルから画像を読み込みます。

パラメータ

filename

戻り値

成功した場合に true を返します。


バイナリ文字列から画像を読み込む

  • ≪ Imagick::readImage
  • Imagick::readImageFile ≫
  • PHP Manual
  • Imagick
  • バイナリ文字列から画像を読み込む

Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — バイナリ文字列から画像を読み込む

説明

public Imagick::readImageBlob(string $image, string $filename = ?): bool

バイナリ文字列から画像を読み込みます。

パラメータ

image

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::readImageBlob()

<?php
function readImageBlob() {
$base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
AAAAAElFTkSuQmCC";

$imageBlob = base64_decode($base64);

$imagick = new Imagick();
$imagick->readImageBlob($imageBlob);

header("Content-Type: image/png");
echo $imagick;
}

?>


オープンしているファイルハンドルから画像を読み込む

  • ≪ Imagick::readImageBlob
  • Imagick::readimages ≫
  • PHP Manual
  • Imagick
  • オープンしているファイルハンドルから画像を読み込む

Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — オープンしているファイルハンドルから画像を読み込む

説明

public Imagick::readImageFile(resource $filehandle, string $fileName = null): bool

オープンしているファイルハンドルから画像を読み込みます。

パラメータ

filehandle

fileName

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


Reads image from an array of filenames

  • ≪ Imagick::readImageFile
  • Imagick::recolorImage ≫
  • PHP Manual
  • Imagick
  • Reads image from an array of filenames

Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Reads image from an array of filenames

説明

public Imagick::readImages(array $filenames): bool

Reads image from an array of filenames. All the images are held in a single Imagick object.

パラメータ

filenames

戻り値

成功した場合に true を返します。


画像の色を変更する

  • ≪ Imagick::readimages
  • Imagick::reduceNoiseImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を変更する

Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — 画像の色を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::recolorImage(array $matrix): bool

画像の色を変換します。 このメソッドは可変サイズの行列に対応していますが、通常は RGBA なら 5x5、 CMYK なら 6x6 の行列を使います。最後の行は、正規化した値でなければなりません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

matrix

色の値を含む行列。

戻り値

成功した場合に true を返します。

例

例1 Imagick::recolorImage()

<?php
function recolorImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$remapColor = [ 1, 0, 0,
0, 0, 1,
0, 1, 0,];

//$remapColor = [
// 1.438, -0.122, -0.016, 0, 0, -0.03,
// -0.062, 1.378, -0.016, 0, 0, 0.05,
// -0.062, -0.122, 1.483, 0, 0, -0.02,
//];

@$imagick->recolorImage($remapColor);

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::displayImage() - 画像を表示する


画像の輪郭をなめらかにする

  • ≪ Imagick::recolorImage
  • Imagick::remapImage ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭をなめらかにする

Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::reduceNoiseImage(float $radius): bool

画像の輪郭をなめらかにします。縁の情報は保持します。 各ピクセルの内容を近傍の一番近い値で置き換えるというアルゴリズムです。 近傍は半径で定義します。radius に 0 を指定すると、 Imagick::reduceNoiseImage() が適切な半径を自動的に設定します。

パラメータ

radius

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::reduceNoiseImage()

<?php
function reduceNoiseImage($imagePath, $reduceNoise) {
$imagick = new \Imagick(realpath($imagePath));
@$imagick->reduceNoiseImage($reduceNoise);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の色を再配置する

  • ≪ Imagick::reduceNoiseImage
  • Imagick::removeImage ≫
  • PHP Manual
  • Imagick
  • 画像の色を再配置する

Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — 画像の色を再配置する

説明

public Imagick::remapImage(Imagick $replacement, int $DITHER): bool

画像の色を、replacement で定義したものに置き換えます。 色の変換は、もっとも近い色で行われます。このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

replacement

置き換える色を含む Imagick オブジェクト。

DITHER

ディザメソッド定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像リストから画像を削除する

  • ≪ Imagick::remapImage
  • Imagick::removeImageProfile ≫
  • PHP Manual
  • Imagick
  • 画像リストから画像を削除する

Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — 画像リストから画像を削除する

説明

public Imagick::removeImage(): bool

画像リストから画像を削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定した名前の画像プロファイルを削除してそれを返す

  • ≪ Imagick::removeImage
  • Imagick::render ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像プロファイルを削除してそれを返す

Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す

説明

public Imagick::removeImageProfile(string $name): string

指定した名前の画像プロファイルを削除してそれを返します。

パラメータ

name

戻り値

画像のプロファイル名を返します。

エラー / 例外

エラー時に ImagickException をスローします。


それまでのすべての描画コマンドをレンダリングする

  • ≪ Imagick::removeImageProfile
  • Imagick::resampleImage ≫
  • PHP Manual
  • Imagick
  • それまでのすべての描画コマンドをレンダリングする

Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — それまでのすべての描画コマンドをレンダリングする

説明

public Imagick::render(): bool

それまでのすべての描画コマンドをレンダリングします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


画像を指定した解像度にリサンプリングする

  • ≪ Imagick::render
  • Imagick::resetImagePage ≫
  • PHP Manual
  • Imagick
  • 画像を指定した解像度にリサンプリングする

Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — 画像を指定した解像度にリサンプリングする

説明

public Imagick::resampleImage(
float $x_resolution,
float $y_resolution,
int $filter,
float $blur
): bool

画像を指定した解像度にリサンプリングします。

パラメータ

x_resolution

y_resolution

filter

blur

戻り値

成功した場合に true を返します。

例

例1 Imagick::resampleImage()

<?php
function resampleImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));

$imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像のページをリセットする

  • ≪ Imagick::resampleImage
  • Imagick::resizeImage ≫
  • PHP Manual
  • Imagick
  • 画像のページをリセットする

Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — 画像のページをリセットする

説明

public Imagick::resetImagePage(string $page): bool

ページの定義は文字列で、書式は WxH+x+y となります。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

page

ページ定義。たとえば 7168x5147+0+0 のようになります。

戻り値

成功した場合に true を返します。


画像のサイズを変更する

  • ≪ Imagick::resetImagePage
  • Imagick::rollImage ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを変更する

Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — 画像のサイズを変更する

説明

public Imagick::resizeImage(
int $columns,
int $rows,
int $filter,
float $blur,
bool $bestfit = false,
bool $legacy = false
): bool

指定した大きさと フィルタ で、画像のサイズを変更します。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

画像の幅。

rows

画像の高さ。

filter

フィルタ定数 の一覧を参照ください。

blur

blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

bestfit

オプションの fit パラメータ。

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | オプションのパラメータ fit が追加され、 このメソッドは、比例形式の拡大・縮小をサポートするようになりました。 どちらかのパラメータにゼロを渡すと比例形式の拡大・縮小を行います。

例

例1 Imagick::resizeImage()

<?php
function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
// blur 要素。1 > はぼやけた状態、< 1 はシャープな状態を表します。
$imagick = new \Imagick(realpath($imagePath));

$imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

$cropWidth = $imagick->getImageWidth();
$cropHeight = $imagick->getImageHeight();

if ($cropZoom) {
$newWidth = $cropWidth / 2;
$newHeight = $cropHeight / 2;

$imagick->cropimage(
$newWidth,
$newHeight,
($cropWidth - $newWidth) / 2,
($cropHeight - $newHeight) / 2
);

$imagick->scaleimage(
$imagick->getImageWidth() * 4,
$imagick->getImageHeight() * 4
);
}

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を補正する

  • ≪ Imagick::resizeImage
  • Imagick::rotateImage ≫
  • PHP Manual
  • Imagick
  • 画像を補正する

Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — 画像を補正する

説明

public Imagick::rollImage(int $x, int $y): bool

x および y を指定して画像を補正します。

パラメータ

x

X オフセット。

y

Y オフセット。

戻り値

成功した場合に true を返します。

例

例1 Imagick::rollImage()

<?php
function rollImage($imagePath, $rollX, $rollY) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->rollimage($rollX, $rollY);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を回転する

  • ≪ Imagick::rollImage
  • Imagick::rotationalBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像を回転する

Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — 画像を回転する

説明

public Imagick::rotateImage(mixed $background, float $degrees): bool

指定した角度だけ画像を回転させます。回転によって生じる空き領域は、 背景色で埋められます。

パラメータ

background

背景色。

degrees

画像を回転させる度数。時計回りに数えます。

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::rotateImage()

<?php
function rotateImage($imagePath, $angle, $color) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->rotateimage($color, $angle);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Rotational blurs an image

  • ≪ Imagick::rotateImage
  • Imagick::roundCorners ≫
  • PHP Manual
  • Imagick
  • Rotational blurs an image

Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Rotational blurs an image

説明

public Imagick::rotationalBlurImage(float $angle, int $channel = Imagick::CHANNEL_DEFAULT): bool

Rotational blurs an image.

パラメータ

angle

The angle to apply the blur over.

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::rotationalBlurImage()

<?php
function rotationalBlurImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->rotationalBlurImage(3);
$imagick->rotationalBlurImage(5);
$imagick->rotationalBlurImage(7);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の角を丸める

  • ≪ Imagick::rotationalBlurImage
  • Imagick::sampleImage ≫
  • PHP Manual
  • Imagick
  • 画像の角を丸める

Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — 画像の角を丸める

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::roundCorners(
float $x_rounding,
float $y_rounding,
float $stroke_width = 10,
float $displace = 5,
float $size_correction = -6
): bool

画像の角を丸めます。 最初の 2 つのパラメータで丸める程度を制御し、 のこりの 3 つのパラメータで丸め処理をより細やかにチューニングします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。 このメソッドは、ImageMagick バージョン 7.0.0 以降で Imagick をコンパイルした場合には利用できません。

パラメータ

x_rounding

x 方向の丸め。

y_rounding

y 方向の丸め。

stroke_width

線幅。

displace

image displace

size_correction

サイズ補正。

戻り値

成功した場合に true を返します。

例

例1 Imagick::roundCorners() の使用法

画像の角を丸めます。

<?php

$image = new Imagick();
$image->newPseudoImage(100, 100, "magick:rose");
$image->setImageFormat("png");

$image->roundCorners(5,3);
$image->writeImage("rounded.png");
?>


ピクセルのサンプリングによって画像の倍率を変更する

  • ≪ Imagick::roundCorners
  • Imagick::scaleImage ≫
  • PHP Manual
  • Imagick
  • ピクセルのサンプリングによって画像の倍率を変更する

Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する

説明

public Imagick::sampleImage(int $columns, int $rows): bool

ピクセルのサンプリングによって、指定した大きさに画像の倍率を変更します。 他の拡大・縮小メソッドとは異なり、 このメソッドは変更後の画像に新たな色を追加したりしません。

パラメータ

columns

rows

戻り値

成功した場合に true を返します。


画像のサイズを変更する

  • ≪ Imagick::sampleImage
  • Imagick::segmentImage ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを変更する

Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — 画像のサイズを変更する

説明

public Imagick::scaleImage(
int $columns,
int $rows,
bool $bestfit = false,
bool $legacy = false
): bool

画像のサイズを指定した大きさに変更します。 パラメータに 0 を指定すると、そのパラメータを自動的に計算します。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

rows

bestfit

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | オプションのパラメータ fit が追加され、 このメソッドは、比例形式の拡大・縮小をサポートするようになりました。 どちらかのパラメータにゼロを渡すと比例形式の拡大・縮小を行います。

例

例1 Imagick::scaleImage()

<?php
function scaleImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->scaleImage(150, 150, true);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を分割する

  • ≪ Imagick::scaleImage
  • Imagick::selectiveBlurImage ≫
  • PHP Manual
  • Imagick
  • 画像を分割する

Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — 画像を分割する

説明

public Imagick::segmentImage(
int $COLORSPACE,
float $cluster_threshold,
float $smooth_threshold,
bool $verbose = false
): bool

画像を解析し、似ている部分を特定します。このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

COLORSPACE

COLORSPACE 定数 のいずれか。

cluster_threshold

有効と見なされるために必要な、 hexedra 内の最小ピクセル数を表すパーセンテージ。

smooth_threshold

ヒストグラムからノイズを除去する。

verbose

識別した区分についての詳細情報を出力するか否か。

戻り値

例

例1 Imagick::segmentImage()

<?php
function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

?>


Selectively blur an image within a contrast threshold

  • ≪ Imagick::segmentImage
  • Imagick::separateImageChannel ≫
  • PHP Manual
  • Imagick
  • Selectively blur an image within a contrast threshold

Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Selectively blur an image within a contrast threshold

説明

public Imagick::selectiveBlurImage(
float $radius,
float $sigma,
float $threshold,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

Selectively blur an image within a contrast threshold. It is similar to the unsharpen mask that sharpens everything with contrast above a certain threshold.

パラメータ

radius

sigma

threshold

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

例

例1 Imagick::selectiveBlurImage()

<?php
function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像からチャネルを分離する

  • ≪ Imagick::selectiveBlurImage
  • Imagick::sepiaToneImage ≫
  • PHP Manual
  • Imagick
  • 画像からチャネルを分離する

Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — 画像からチャネルを分離する

説明

public Imagick::separateImageChannel(int $channel): bool

画像からチャネルを分離し、グレースケール画像を返します。 channel には、画像の各ピクセルの特定の色コンポーネントを指定します。

パラメータ

channel

どの「チャネル」を戻すか。RGB 以外の色空間の場合でも、定数 CHANNEL_RED、CHANNEL_GREEN、CHANNEL_BLUE を使って第1、第2、第3チャネルを指定できます。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::separateImageChannel()

<?php
function separateImageChannel($imagePath, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->separateimagechannel($channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

?>


画像をセピア調にする

  • ≪ Imagick::separateImageChannel
  • Imagick::setBackgroundColor ≫
  • PHP Manual
  • Imagick
  • 画像をセピア調にする

Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — 画像をセピア調にする

説明

public Imagick::sepiaToneImage(float $threshold): bool

画像に特殊効果を施し、セピア調の写真のような画像にします。 threshold には 0 から QuantumRange までの値を指定し、 これがセピア調の効き具合を表します。threshold を 80 にすると、 とりあえずはそれなりの効き目になるでしょう。

パラメータ

threshold

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::sepiaToneImage()

<?php
function sepiaToneImage($imagePath, $sepia) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->sepiaToneImage($sepia);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


オブジェクトのデフォルト背景色を設定する

  • ≪ Imagick::sepiaToneImage
  • Imagick::setColorspace ≫
  • PHP Manual
  • Imagick
  • オブジェクトのデフォルト背景色を設定する

Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — オブジェクトのデフォルト背景色を設定する

説明

public Imagick::setBackgroundColor(mixed $background): bool

オブジェクトのデフォルト背景色を設定します。

パラメータ

background

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


色空間を設定する

  • ≪ Imagick::setBackgroundColor
  • Imagick::setCompression ≫
  • PHP Manual
  • Imagick
  • 色空間を設定する

Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — 色空間を設定する

説明

public Imagick::setColorspace(int $COLORSPACE): bool

オブジェクトのグローバル色空間の値を設定します。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

COLORSPACE

COLORSPACE 定数 のひとつ。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


オブジェクトのデフォルトの圧縮方式を設定する

  • ≪ Imagick::setColorspace
  • Imagick::setCompressionQuality ≫
  • PHP Manual
  • Imagick
  • オブジェクトのデフォルトの圧縮方式を設定する

Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — オブジェクトのデフォルトの圧縮方式を設定する

説明

public Imagick::setCompression(int $compression): bool

オブジェクトのデフォルトの圧縮方式を設定します。

パラメータ

compression

圧縮方式。Imagick::COMPRESSION_* 定数を参照ください。

戻り値

成功した場合に true を返します。


オブジェクトのデフォルトの圧縮品質を設定する

  • ≪ Imagick::setCompression
  • Imagick::setFilename ≫
  • PHP Manual
  • Imagick
  • オブジェクトのデフォルトの圧縮品質を設定する

Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — オブジェクトのデフォルトの圧縮品質を設定する

説明

public Imagick::setCompressionQuality(int $quality): bool

オブジェクトのデフォルトの圧縮品質を設定します。

警告

このメソッドは、たとえば Imagick::newPseudoImage などで作った新しい画像に対してだけ使えるものです。 既存の画像に対しては Imagick::setImageCompressionQuality() を使う必要があります。

パラメータ

quality

1 から 100 の間の int 1 = 高圧縮品質。 100 = 低圧縮品質。を表します。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setCompressionQuality()

<?php
function setCompressionQuality($imagePath, $quality) {

$backgroundImagick = new \Imagick(realpath($imagePath));
$imagick = new \Imagick();
$imagick->setCompressionQuality($quality);
$imagick->newPseudoImage(
$backgroundImagick->getImageWidth(),
$backgroundImagick->getImageHeight(),
'canvas:white'
);

$imagick->compositeImage(
$backgroundImagick,
\Imagick::COMPOSITE_ATOP,
0,
0
);

$imagick->setFormat("jpg");
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像を読み書きする前にファイル名を設定する

  • ≪ Imagick::setCompressionQuality
  • Imagick::setFirstIterator ≫
  • PHP Manual
  • Imagick
  • 画像を読み書きする前にファイル名を設定する

Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — 画像を読み書きする前にファイル名を設定する

説明

public Imagick::setFilename(string $filename): bool

画像を読み書きする前にファイル名を設定します。

パラメータ

filename

戻り値

成功した場合に true を返します。


Imagick イテレータを最初の画像に設定する

  • ≪ Imagick::setFilename
  • Imagick::setFont ≫
  • PHP Manual
  • Imagick
  • Imagick イテレータを最初の画像に設定する

Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Imagick イテレータを最初の画像に設定する

説明

public Imagick::setFirstIterator(): bool

Imagick イテレータを最初の画像に設定します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


フォントを設定する

  • ≪ Imagick::setFirstIterator
  • Imagick::setFormat ≫
  • PHP Manual
  • Imagick
  • フォントを設定する

Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — フォントを設定する

説明

public Imagick::setFont(string $font): bool

オブジェクトのフォントプロパティを設定します。 このメソッドは、たとえば caption: pseudo-format のフォントを設定したりする際に使用します。 フォントは、ImageMagick の設定で準備しておくか、あるいは font という名前のファイルが存在しなければなりません。 このメソッドを ImagickDraw::setFont() と混同してはいけません。 こちらは、ある特定の ImagickDraw オブジェクトのフォントを設定するメソッドです。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

font

フォント名あるいはファイル名。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setFont() の例

Imagick::setFont の使用例です。

<?php
/* 新しい imagick オブジェクトを作成します */
$im = new Imagick();

/* オブジェクトのフォントを設定します */
$im->setFont("example.ttf");

/* 新しいキャプションを作成します */
$im->newPseudoImage(100, 100, "caption:Hello");

/* 画像に対してなんらかの操作をします */
?>

参考

  • Imagick::getFont() - フォントを取得する
  • ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する
  • ImagickDraw::getFont() - フォントを返す


Imagick オブジェクトのフォーマットを設定する

  • ≪ Imagick::setFont
  • Imagick::setGravity ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのフォーマットを設定する

Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Imagick オブジェクトのフォーマットを設定する

説明

public Imagick::setFormat(string $format): bool

Imagick オブジェクトのフォーマットを設定します。

パラメータ

format

戻り値

成功した場合に true を返します。


gravity を設定する

  • ≪ Imagick::setFormat
  • Imagick::setImage ≫
  • PHP Manual
  • Imagick
  • gravity を設定する

Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — gravity を設定する

説明

public Imagick::setGravity(int $gravity): bool

Imagick オブジェクトのグローバル gravity プロパティを設定します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

gravity

gravity プロパティ。 gravity 定数 の一覧を参照ください。

戻り値

値を返しません。


オブジェクト内の画像を置き換える

  • ≪ Imagick::setGravity
  • Imagick::setImageAlphaChannel ≫
  • PHP Manual
  • Imagick
  • オブジェクト内の画像を置き換える

Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — オブジェクト内の画像を置き換える

説明

public Imagick::setImage(Imagick $replace): bool

現在の画像シーケンスを、replace で指定したオブジェクトの画像で置き換えます。

パラメータ

replace

置き換える Imagick オブジェクト。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImage() の例

Imagick::setImage() の使用例です。

<?php
/* オブジェクトを作成します */
$image = new Imagick('source.jpg');
$replace = new Imagick('replace.jpg');

/* source.jpg を replace.jpg で置き換えます */
$image->setImage($replace);

/* 画像を出力します */
header('Content-type: image/jpeg');
echo $image;

?>


画像のアルファチャネルを設定する

  • ≪ Imagick::setImage
  • Imagick::setImageArtifact ≫
  • PHP Manual
  • Imagick
  • 画像のアルファチャネルを設定する

Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — 画像のアルファチャネルを設定する

説明

public Imagick::setImageAlphaChannel(int $mode): bool

画像のアルファチャネルを有効あるいは無効にします。mode には Imagick::ALPHACHANNEL_* 定数のいずれかを設定します。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

mode

Imagick::ALPHACHANNEL_* 定数のいずれか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

参考

  • Imagick::setImageMatte() - 画像のマットチャネルを設定する
  • Imagick Alpha Channel 定数


画像のアーチファクトを設定する

  • ≪ Imagick::setImageAlphaChannel
  • Imagick::setImageAttribute ≫
  • PHP Manual
  • Imagick
  • 画像のアーチファクトを設定する

Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — 画像のアーチファクトを設定する

説明

public Imagick::setImageArtifact(string $artifact, string $value): bool

画像にアーチファクトを関連づけます。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

artifact

アーチファクトの名前。

value

アーチファクトの値。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageArtifact()

<?php
function setImageArtifact() {

$src1 = new \Imagick(realpath("./images/artifact/source1.png"));
$src2 = new \Imagick(realpath("./images/artifact/source2.png"));

$src2->setImageVirtualPixelMethod(\Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
$src2->setImageArtifact('compose:args', "1,0,-0.5,0.5");
$src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);

$src1->setImageFormat('png');
header("Content-Type: image/png");
echo $src1->getImagesBlob();
}

?>

参考

  • Imagick::getImageArtifact() - 画像のアーチファクトを取得する
  • Imagick::deleteImageArtifact() - 画像のアーチファクトを削除する


Sets an image attribute

  • ≪ Imagick::setImageArtifact
  • Imagick::setImageBackgroundColor ≫
  • PHP Manual
  • Imagick
  • Sets an image attribute

Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Sets an image attribute

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageAttribute(string $key, string $value): bool

Sets an image attribute.

パラメータ

key

value

戻り値

成功した場合に true を返します。


画像の背景色を設定する

  • ≪ Imagick::setImageAttribute
  • Imagick::setImageBias ≫
  • PHP Manual
  • Imagick
  • 画像の背景色を設定する

Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — 画像の背景色を設定する

説明

public Imagick::setImageBackgroundColor(mixed $background): bool

画像の背景色を設定します。

パラメータ

background

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

  • ≪ Imagick::setImageBackgroundColor
  • Imagick::setImageBiasQuantum ≫
  • PHP Manual
  • Imagick
  • 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageBias(float $bias): bool

画像を折りたたむ任意のメソッド (Imagick::ConvolveImage() など) について画像のバイアスを設定します。

パラメータ

bias

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageBias()

<?php
//requires ImageMagick version 6.9.0-1 to have an effect on convolveImage
function setImageBias($bias) {
$imagick = new \Imagick(realpath("images/stack.jpg"));

$xKernel = array(
-0.70, 0, 0.70,
-0.70, 0, 0.70,
-0.70, 0, 0.70
);

$imagick->setImageBias($bias * \Imagick::getQuantum());
$imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

$imagick->setImageFormat('png');

header('Content-type: image/png');
echo $imagick->getImageBlob();
}

?>


Sets the image bias

  • ≪ Imagick::setImageBias
  • Imagick::setImageBluePrimary ≫
  • PHP Manual
  • Imagick
  • Sets the image bias

Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Sets the image bias

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageBiasQuantum(float $bias): void

Sets the image bias. Bias should be scaled with 0 (no adjustment) to 1 (quantum value).

パラメータ

bias

戻り値


青が一番強い点を設定する

  • ≪ Imagick::setImageBiasQuantum
  • Imagick::setImageBorderColor ≫
  • PHP Manual
  • Imagick
  • 青が一番強い点を設定する

Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — 青が一番強い点を設定する

説明

public Imagick::setImageBluePrimary(float $x, float $y): bool

青が一番強い点を設定します。

パラメータ

x

y

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の前景色を設定する

  • ≪ Imagick::setImageBluePrimary
  • Imagick::setImageChannelDepth ≫
  • PHP Manual
  • Imagick
  • 画像の前景色を設定する

Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — 画像の前景色を設定する

説明

public Imagick::setImageBorderColor(mixed $border): bool

画像の前景色を設定します。

パラメータ

border

前景色。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


特定の画像チャネルの深度を設定する

  • ≪ Imagick::setImageBorderColor
  • Imagick::setImageClipMask ≫
  • PHP Manual
  • Imagick
  • 特定の画像チャネルの深度を設定する

Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — 特定の画像チャネルの深度を設定する

説明

public Imagick::setImageChannelDepth(int $channel, int $depth): bool

特定の画像チャネルの深度を設定します。

パラメータ

channel

depth

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のクリップマスクを設定する

  • ≪ Imagick::setImageChannelDepth
  • Imagick::setImageColormapColor ≫
  • PHP Manual
  • Imagick
  • 画像のクリップマスクを設定する

Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — 画像のクリップマスクを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageClipMask(Imagick $clip_mask): bool

別の Imagick オブジェクトから画像のクリップマスクを設定します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

clip_mask

クリップマスクを含む Imagick オブジェクト。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageClipMask()

<?php
function setImageClipMask($imagePath) {
$imagick = new \Imagick();
$imagick->readImage(realpath($imagePath));

$width = $imagick->getImageWidth();
$height = $imagick->getImageHeight();

$clipMask = new \Imagick();
$clipMask->newPseudoImage(
$width,
$height,
"canvas:transparent"
);

$draw = new \ImagickDraw();
$draw->setFillColor('white');
$draw->circle(
$width / 2,
$height / 2,
($width / 2) + ($width / 4),
$height / 2
);
$clipMask->drawImage($draw);
$imagick->setImageClipMask($clipMask);

$imagick->negateImage(false);
$imagick->setFormat("png");

header("Content-Type: image/png");
echo $imagick->getImagesBlob();

}

?>


指定した色マップインデックスの色を設定する

  • ≪ Imagick::setImageClipMask
  • Imagick::setImageColorspace ≫
  • PHP Manual
  • Imagick
  • 指定した色マップインデックスの色を設定する

Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — 指定した色マップインデックスの色を設定する

説明

public Imagick::setImageColormapColor(int $index, ImagickPixel $color): bool

指定した色マップインデックスの色を設定します。

パラメータ

index

color

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の色空間を設定する

  • ≪ Imagick::setImageColormapColor
  • Imagick::setImageCompose ≫
  • PHP Manual
  • Imagick
  • 画像の色空間を設定する

Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — 画像の色空間を設定する

説明

public Imagick::setImageColorspace(int $colorspace): bool

画像の色空間を設定します。 このメソッドは、新しい画像を作るときに使うものです。 既存の画像の色空間を変更したい場合は、Imagick::transformImageColorspace() を使う必要があります。

パラメータ

colorspace

COLORSPACE 定数のいずれか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の合成演算子を設定する

  • ≪ Imagick::setImageColorspace
  • Imagick::setImageCompression ≫
  • PHP Manual
  • Imagick
  • 画像の合成演算子を設定する

Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — 画像の合成演算子を設定する

説明

public Imagick::setImageCompose(int $compose): bool

画像の合成演算子を設定します。Imagick::montageImage() メソッドを使用して画像のサムネイルを作成する方法を指定する際に便利です。

パラメータ

compose

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の圧縮を設定する

  • ≪ Imagick::setImageCompose
  • Imagick::setImageCompressionQuality ≫
  • PHP Manual
  • Imagick
  • 画像の圧縮を設定する

Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — 画像の圧縮を設定する

説明

public Imagick::setImageCompression(int $compression): bool

画像の圧縮を設定します。

パラメータ

compression

COMPRESSION 定数のいずれか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の圧縮品質を設定する

  • ≪ Imagick::setImageCompression
  • Imagick::setImageDelay ≫
  • PHP Manual
  • Imagick
  • 画像の圧縮品質を設定する

Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — 画像の圧縮品質を設定する

説明

public Imagick::setImageCompressionQuality(int $quality): bool

画像の圧縮品質を設定します。

パラメータ

quality

画像の圧縮品質を表す整数値。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageCompressionQuality()

<?php
function setImageCompressionQuality($imagePath, $quality) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageCompressionQuality($quality);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の遅延を設定する

  • ≪ Imagick::setImageCompressionQuality
  • Imagick::setImageDepth ≫
  • PHP Manual
  • Imagick
  • 画像の遅延を設定する

Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — 画像の遅延を設定する

説明

public Imagick::setImageDelay(int $delay): bool

画像の遅延を設定します。アニメーション画像の場合、この値は、 今のフレームから次のフレームに移動するまでの時間になります。

パラメータ

delay

画像を表示させる時間を 'ticks' で表した値。 アニメーション GIF の場合は 1 秒間に 100 ticks なので、 20 を設定すると 20/100 秒つまり 1/5 秒ということになります。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageDelay() を使ったアニメーション GIF の変更

<?php

// アニメーション GIF を変更し、各フレームの表示時間を 50ms から 0ms に徐々に変えていきます。
// 0ms にすると、たいていのブラウザでは表示をスキップするようになります。
$imagick = new Imagick(realpath("Test.gif"));
$imagick = $imagick->coalesceImages();

$frameCount = 0;

foreach ($imagick as $frame) {
$imagick->setImageDelay((($frameCount % 11) * 5));
$frameCount++;
}

$imagick = $imagick->deconstructImages();

$imagick->writeImages("/path/to/save/output.gif", true);

?>


画像の深度を設定する

  • ≪ Imagick::setImageDelay
  • Imagick::setImageDispose ≫
  • PHP Manual
  • Imagick
  • 画像の深度を設定する

Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — 画像の深度を設定する

説明

public Imagick::setImageDepth(int $depth): bool

画像の深度を設定します。

パラメータ

depth

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の配置方法を設定する

  • ≪ Imagick::setImageDepth
  • Imagick::setImageExtent ≫
  • PHP Manual
  • Imagick
  • 画像の配置方法を設定する

Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — 画像の配置方法を設定する

説明

public Imagick::setImageDispose(int $dispose): bool

画像の配置方法を設定します。

パラメータ

dispose

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のサイズを設定する

  • ≪ Imagick::setImageDispose
  • Imagick::setImageFilename ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを設定する

Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — 画像のサイズを設定する

説明

public Imagick::setImageExtent(int $columns, int $rows): bool

画像のサイズ (つまりカラム数と行数) を設定します。

パラメータ

columns

rows

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


特定の画像のファイル名を設定する

  • ≪ Imagick::setImageExtent
  • Imagick::setImageFormat ≫
  • PHP Manual
  • Imagick
  • 特定の画像のファイル名を設定する

Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — 特定の画像のファイル名を設定する

説明

public Imagick::setImageFilename(string $filename): bool

シーケンス内の特定の画像のファイル名を設定します。

パラメータ

filename

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


特定の画像のフォーマットを設定する

  • ≪ Imagick::setImageFilename
  • Imagick::setImageGamma ≫
  • PHP Manual
  • Imagick
  • 特定の画像のフォーマットを設定する

Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — 特定の画像のフォーマットを設定する

説明

public Imagick::setImageFormat(string $format): bool

シーケンス内の特定の画像のフォーマットを設定します。

パラメータ

format

画像フォーマットを表す文字列。対応するフォーマットは、 インストールされている ImageMagick に依存します。

戻り値

成功した場合に true を返します。


画像のガンマを設定する

  • ≪ Imagick::setImageFormat
  • Imagick::setImageGravity ≫
  • PHP Manual
  • Imagick
  • 画像のガンマを設定する

Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — 画像のガンマを設定する

説明

public Imagick::setImageGamma(float $gamma): bool

画像のガンマを設定します。

パラメータ

gamma

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の gravity を設定する

  • ≪ Imagick::setImageGamma
  • Imagick::setImageGreenPrimary ≫
  • PHP Manual
  • Imagick
  • 画像の gravity を設定する

Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — 画像の gravity を設定する

説明

public Imagick::setImageGravity(int $gravity): bool

原罪の画像の gravity プロパティを設定します。 このメソッドを使うと、単一の画像シーケンスの gravity プロパティを設定することができます。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

gravity

gravity プロパティ。 gravity 定数 の一覧を参照ください。

戻り値

値を返しません。


緑が一番強い点を設定する

  • ≪ Imagick::setImageGravity
  • Imagick::setImageIndex ≫
  • PHP Manual
  • Imagick
  • 緑が一番強い点を設定する

Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — 緑が一番強い点を設定する

説明

public Imagick::setImageGreenPrimary(float $x, float $y): bool

緑が一番強い点を設定します。

パラメータ

x

y

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


イテレータの位置を設定する

  • ≪ Imagick::setImageGreenPrimary
  • Imagick::setImageInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • イテレータの位置を設定する

Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — イテレータの位置を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageIndex(int $index): bool

画像リスト内でのイテレータの位置、index パラメータで指定した場所に設定します。

このメソッドは非推奨です。 Imagick::setIteratorIndex() を参照ください。

パラメータ

index

イテレータを設定する位置。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のインターレース手法を設定する

  • ≪ Imagick::setImageIndex
  • Imagick::setImageInterpolateMethod ≫
  • PHP Manual
  • Imagick
  • 画像のインターレース手法を設定する

Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — 画像のインターレース手法を設定する

説明

public Imagick::setImageInterlaceScheme(int $interlace_scheme): bool

画像の圧縮を設定します。

パラメータ

interlace_scheme

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のピクセル補間方式を設定する

  • ≪ Imagick::setImageInterlaceScheme
  • Imagick::setImageIterations ≫
  • PHP Manual
  • Imagick
  • 画像のピクセル補間方式を設定する

Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — 画像のピクセル補間方式を設定する

説明

public Imagick::setImageInterpolateMethod(int $method): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像のピクセル補間方式を設定します。

パラメータ

method

Imagick::INTERPOLATE_* 定数のいずれか。

戻り値

成功した場合に true を返します。


画像の反復を設定する

  • ≪ Imagick::setImageInterpolateMethod
  • Imagick::setImageMatte ≫
  • PHP Manual
  • Imagick
  • 画像の反復を設定する

Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — 画像の反復を設定する

説明

public Imagick::setImageIterations(int $iterations): bool

アニメーション画像の繰り返し回数を設定します。

パラメータ

iterations

画像をループさせる回数。'0' を指定すると、ずっとループし続けます。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 基本的な Imagick::setImageIterations() の使用例

<?php

$imagick = new Imagick(realpath("Test.gif"));

$imagick = $imagick->coalesceImages();
$imagick->setImageIterations(1);
$imagick = $imagick->deconstructImages();

$imagick->writeImages('/path/to/save/OnceOnly.gif', true);

?>


画像のマットチャネルを設定する

  • ≪ Imagick::setImageIterations
  • Imagick::setImageMatteColor ≫
  • PHP Manual
  • Imagick
  • 画像のマットチャネルを設定する

Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — 画像のマットチャネルを設定する

説明

public Imagick::setImageMatte(bool $matte): bool

画像のマットチャネルを設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

matte

True にするとマットチャネルを有効にし、false の場合は無効にします。

戻り値

成功した場合に true を返します。


画像のマット色を設定する

  • ≪ Imagick::setImageMatte
  • Imagick::setImageOpacity ≫
  • PHP Manual
  • Imagick
  • 画像のマット色を設定する

Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — 画像のマット色を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageMatteColor(mixed $matte): bool

画像のマット色を設定します。

パラメータ

matte

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。


画像の不透明度を設定する

  • ≪ Imagick::setImageMatteColor
  • Imagick::setImageOrientation ≫
  • PHP Manual
  • Imagick
  • 画像の不透明度を設定する

Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — 画像の不透明度を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::setImageOpacity(float $opacity): bool

画像の不透明度を設定します。このメソッドは、ImageMagick バージョン 6.3.1 以降で Imagick をコンパイルした場合に使用可能です。 このメソッドはすべてのチャネルを操作します。つまり、不透明度を 0.5 にすると、 すべての透明な部分が半透明になるということです。すでに透明になっていない範囲に透明度を追加するには、 Imagick::evaluateImage() を使いましょう。

パラメータ

opacity

透明度。1.0 が完全な不透明で、0.0 が完全な透明です。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setImageOpacity() の例

Imagick::setImageOpacity() を使用する例です。

<?php
/* オブジェクトを作成します */
$image = new Imagick('source.png');

/* 透明度を設定します */
$image->setImageOpacity(0.7);

/* 画像を出力します */
header('Content-type: image/png');
echo $image;

?>


画像の方向を設定する

  • ≪ Imagick::setImageOpacity
  • Imagick::setImagePage ≫
  • PHP Manual
  • Imagick
  • 画像の方向を設定する

Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — 画像の方向を設定する

説明

public Imagick::setImageOrientation(int $orientation): bool

画像の方向を設定します。

パラメータ

orientation

方向定数 のいずれか。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setImageOrientation()

<?php
//Doesn't appear to do anything
function setImageOrientation($imagePath, $orientationType) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageOrientation($orientationType);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像のページのジオメトリを設定する

  • ≪ Imagick::setImageOrientation
  • Imagick::setImageProfile ≫
  • PHP Manual
  • Imagick
  • 画像のページのジオメトリを設定する

Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — 画像のページのジオメトリを設定する

説明

public Imagick::setImagePage(
int $width,
int $height,
int $x,
int $y
): bool

画像のページのジオメトリを設定します。

パラメータ

width

height

x

y

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


指定した名前の画像プロファイルを Imagick オブジェクトに追加する

  • ≪ Imagick::setImagePage
  • Imagick::setImageProperty ≫
  • PHP Manual
  • Imagick
  • 指定した名前の画像プロファイルを Imagick オブジェクトに追加する

Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — 指定した名前の画像プロファイルを Imagick オブジェクトに追加する

説明

public Imagick::setImageProfile(string $name, string $profile): bool

指定した名前の画像プロファイルを Imagick オブジェクトに追加します。 同じ名前のプロファイルが存在する場合は、それを置き換えます。 このメソッドは Imagick::ProfileImage() メソッドとは異なり、 CMS カラープロファイルは適用しません。

パラメータ

name

profile

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のプロパティを設定する

  • ≪ Imagick::setImageProfile
  • Imagick::setImageRedPrimary ≫
  • PHP Manual
  • Imagick
  • 画像のプロパティを設定する

Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — 画像のプロパティを設定する

説明

public Imagick::setImageProperty(string $name, string $value): bool

指定した名前のプロパティを画像に設定します。 このメソッドは、ImageMagick バージョン 6.3.2 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

name

value

戻り値

成功した場合に true を返します。

例

例1 Imagick::setImageProperty() の使用法

画像のプロパティを設定し、そして取得します。

<?php
$image = new Imagick();
$image->newImage(300, 200, "black");

$image->setImageProperty('Exif:Make', 'Imagick');
echo $image->getImageProperty('Exif:Make');
?>

参考

  • Imagick::getImageProperty() - 指定した名前の画像のプロパティを返す


赤が一番強い点を設定する

  • ≪ Imagick::setImageProperty
  • Imagick::setImageRenderingIntent ≫
  • PHP Manual
  • Imagick
  • 赤が一番強い点を設定する

Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — 赤が一番強い点を設定する

説明

public Imagick::setImageRedPrimary(float $x, float $y): bool

赤が一番強い点を設定します。

パラメータ

x

y

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像のレンダリング方向を設定する

  • ≪ Imagick::setImageRedPrimary
  • Imagick::setImageResolution ≫
  • PHP Manual
  • Imagick
  • 画像のレンダリング方向を設定する

Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — 画像のレンダリング方向を設定する

説明

public Imagick::setImageRenderingIntent(int $rendering_intent): bool

画像のレンダリング方向を設定します。

パラメータ

rendering_intent

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の解像度を設定する

  • ≪ Imagick::setImageRenderingIntent
  • Imagick::setImageScene ≫
  • PHP Manual
  • Imagick
  • 画像の解像度を設定する

Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — 画像の解像度を設定する

説明

public Imagick::setImageResolution(float $x_resolution, float $y_resolution): bool

画像の解像度を設定します。

パラメータ

x_resolution

y_resolution

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::setImageResolution()

<?php
function setImageResolution($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageResolution(50, 50);

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像のシーンを設定する

  • ≪ Imagick::setImageResolution
  • Imagick::setImageTicksPerSecond ≫
  • PHP Manual
  • Imagick
  • 画像のシーンを設定する

Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — 画像のシーンを設定する

説明

public Imagick::setImageScene(int $scene): bool

画像のシーンを設定します。

パラメータ

scene

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の ticks-per-second を設定する

  • ≪ Imagick::setImageScene
  • Imagick::setImageType ≫
  • PHP Manual
  • Imagick
  • 画像の ticks-per-second を設定する

Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — 画像の ticks-per-second を設定する

説明

public Imagick::setImageTicksPerSecond(int $ticks_per_second): bool

アニメーション画像のフレームを表示する時間を調整します。

注意:

アニメーション GIF の場合、この関数は秒間の 'image ticks' の数は変更しません。常に 100 です。 そのかわりに、'ticks per second' を変更し、フレームを表示する時間を変更したように見せます。

たとえば、各フレームを 20 ticks (1/5 秒) ずつ表示させるようにしているアニメーション GIF に対して、この関数の引数に 50 を渡して呼び出すと、 各フレームの表示時間を 40 ticks (2/5 秒) に変更します。 その結果、元の半分の速さで表示されるようになります。

パラメータ

ticks_per_second

画像を表示させる時間を ticks per second で表した値。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setImageTicksPerSecond() によるアニメーション GIF の変更

<?php

// アニメーション GIF の前半の再生スピードを元の半分に、
// そして後半の再生スピードを元の倍にします。

$imagick = new Imagick(realpath("Test.gif"));
$imagick = $imagick->coalesceImages();

$totalFrames = $imagick->getNumberImages();

$frameCount = 0;

foreach ($imagick as $frame) {
$imagick->setImageTicksPerSecond(50);

if ($frameCount < ($totalFrames / 2)) {
// フレームの表示時間を元の二倍にします
$imagick->setImageTicksPerSecond(50);
} else {
// フレームの表示時間を元の半分にします
$imagick->setImageTicksPerSecond(200);
}

$frameCount++;
}

$imagick = $imagick->deconstructImages();

$imagick->writeImages("/path/to/save/output.gif", true);

?>


画像の型を設定する

  • ≪ Imagick::setImageTicksPerSecond
  • Imagick::setImageUnits ≫
  • PHP Manual
  • Imagick
  • 画像の型を設定する

Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — 画像の型を設定する

説明

public Imagick::setImageType(int $image_type): bool

画像の型を設定します。

パラメータ

image_type

戻り値

成功した場合に true を返します。


画像の解像度の単位を設定する

  • ≪ Imagick::setImageType
  • Imagick::setImageVirtualPixelMethod ≫
  • PHP Manual
  • Imagick
  • 画像の解像度の単位を設定する

Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — 画像の解像度の単位を設定する

説明

public Imagick::setImageUnits(int $units): bool

画像の解像度の単位を設定します。

パラメータ

units

戻り値

成功した場合に true を返します。


画像の仮想ピクセルメソッドを設定する

  • ≪ Imagick::setImageUnits
  • Imagick::setImageWhitePoint ≫
  • PHP Manual
  • Imagick
  • 画像の仮想ピクセルメソッドを設定する

Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — 画像の仮想ピクセルメソッドを設定する

説明

public Imagick::setImageVirtualPixelMethod(int $method): bool

画像の仮想ピクセルメソッドを設定します。

パラメータ

method

戻り値

成功した場合に true を返します。


画像の色度が白い点を設定する

  • ≪ Imagick::setImageVirtualPixelMethod
  • Imagick::setInterlaceScheme ≫
  • PHP Manual
  • Imagick
  • 画像の色度が白い点を設定する

Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — 画像の色度が白い点を設定する

説明

public Imagick::setImageWhitePoint(float $x, float $y): bool

画像の色度が白い点を設定します。

パラメータ

x

y

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像の圧縮を設定する

  • ≪ Imagick::setImageWhitePoint
  • Imagick::setIteratorIndex ≫
  • PHP Manual
  • Imagick
  • 画像の圧縮を設定する

Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — 画像の圧縮を設定する

説明

public Imagick::setInterlaceScheme(int $interlace_scheme): bool

画像の圧縮を設定します。

パラメータ

interlace_scheme

戻り値

成功した場合に true を返します。


イテレータの位置を設定する

  • ≪ Imagick::setInterlaceScheme
  • Imagick::setLastIterator ≫
  • PHP Manual
  • Imagick
  • イテレータの位置を設定する

Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — イテレータの位置を設定する

説明

public Imagick::setIteratorIndex(int $index): bool

イテレータの位置を、画像リスト内の index で指定した位置に設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

index

イテレータを設定する場所。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setIteratorIndex() の使用法

画像を作成し、インデックスを設定して取得します。

<?php
$im = new Imagick();
$im->newImage(100, 100, new ImagickPixel("red"));
$im->newImage(100, 100, new ImagickPixel("green"));
$im->newImage(100, 100, new ImagickPixel("blue"));

$im->setIteratorIndex(1);
echo $im->getIteratorIndex();
?>

参考

  • Imagick::getIteratorIndex() - 現在アクティブな画像のインデックスを取得する
  • Imagick::getImageIndex() - 現在アクティブな画像のインデックスを取得する
  • Imagick::setImageIndex() - イテレータの位置を設定する


Imagick イテレータを最後の画像に設定する

  • ≪ Imagick::setIteratorIndex
  • Imagick::setOption ≫
  • PHP Manual
  • Imagick
  • Imagick イテレータを最後の画像に設定する

Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Imagick イテレータを最後の画像に設定する

説明

public Imagick::setLastIterator(): bool

Imagick イテレータを最後の画像に設定します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


オプションを設定する

  • ≪ Imagick::setLastIterator
  • Imagick::setPage ≫
  • PHP Manual
  • Imagick
  • オプションを設定する

Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — オプションを設定する

説明

public Imagick::setOption(string $key, string $value): bool

ひとつあるいは複数のオプションを設定します。

パラメータ

key

value

戻り値

成功した場合に true を返します。

例

例1 Attempt to reach '$extent' sizeImagick::setOption()

<?php
function renderJPG($extent) {
$imagePath = $this->control->getImagePath();
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageFormat('jpg');
$imagick->setOption('jpeg:extent', $extent);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

例2 Imagick::setOption()

<?php
function renderPNG($imagePath, $format) {

$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageFormat('png');
$imagick->setOption('png:format', $format);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

//Save as 64bit PNG.
renderPNG($imagePath, 'png64');

?>

例3 Imagick::setOption()

<?php
function renderCustomBitDepthPNG() {
$imagePath = $this->control->getImagePath();
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageFormat('png');

$imagick->setOption('png:bit-depth', '16');
$imagick->setOption('png:color-type', 6);
header("Content-Type: image/png");
$crash = true;
if ($crash) {
echo $imagick->getImageBlob();
}
else {
$tempFilename = tempnam('./', 'imagick');
$imagick->writeimage(realpath($tempFilename));
echo file_get_contents($tempFilename);
}
}

?>


Imagick オブジェクトのページジオメトリを設定する

  • ≪ Imagick::setOption
  • Imagick::setPointSize ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのページジオメトリを設定する

Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Imagick オブジェクトのページジオメトリを設定する

説明

public Imagick::setPage(
int $width,
int $height,
int $x,
int $y
): bool

Imagick オブジェクトのページジオメトリを設定します。

パラメータ

width

height

x

y

戻り値

成功した場合に true を返します。


ポイントサイズを設定する

  • ≪ Imagick::setPage
  • Imagick::setProgressMonitor ≫
  • PHP Manual
  • Imagick
  • ポイントサイズを設定する

Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — ポイントサイズを設定する

説明

public Imagick::setPointSize(float $point_size): bool

オブジェクトのポイントサイズプロパティを設定します。このメソッドは、 caption: pseudo-format のフォントサイズを設定するときなどに使います。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

point_size

ポイントサイズ。

戻り値

成功した場合に true を返します。

例

例1 Imagick::setPointSize() の例

Imagick::setPointSize の使用例です。

<?php
/* 新しい imagick オブジェクトを作ります */
$im = new Imagick();

/* オブジェクトのフォントを設定します */
$im->setFont("example.ttf");

/* ポイントサイズを設定します */
$im->setPointSize(12);

/* 新しいキャプションを作ります */
$im->newPseudoImage(100, 100, "caption:Hello");

/* 画像に対して何かの処理をします */
?>

参考

  • Imagick::getPointSize() - ポイントサイズを取得する


Set a callback to be called during processing

  • ≪ Imagick::setPointSize
  • Imagick::setRegistry ≫
  • PHP Manual
  • Imagick
  • Set a callback to be called during processing

Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Set a callback to be called during processing

説明

public Imagick::setProgressMonitor(callable $callback): bool

Set a callback that will be called during the processing of the Imagick image.

パラメータ

callback

The progress function to call. It should return true if image processing should continue, or false if it should be cancelled. The offset parameter indicates the progress and the span parameter indicates the total amount of work needed to be done.

callback ( mixed $offset , mixed $span ): bool
警告

The values passed to the callback function are not consistent. In particular the span parameter can increase during image processing. Because of this calculating the percentage complete of an image operation is not trivial.

戻り値

成功した場合に true を返します。

例

例1 Imagick::setProgressMonitor()

<?php
$abortReason = null;

try {
$imagick = new \Imagick(realpath($this->control->getImagePath()));
$startTime = time();

$callback = function ($offset, $span) use ($startTime, &$abortReason) {
if (((100 * $offset) / $span) > 20) {
$abortReason = "Processing reached 20%";
return false;
}

$nowTime = time();

if ($nowTime - $startTime > 5) {
$abortReason = "Image processing took more than 5 seconds";
return false;
}
if (($offset % 5) == 0) {
echo "Progress: $offset / $span <br/>";
}
return true;
};

$imagick->setProgressMonitor($callback);

$imagick->waveImage(2, 15);

echo "Data len is: ".strlen($imagick->getImageBlob());
}
catch(\ImagickException $e) {
if ($abortReason != null) {
echo "Image processing was aborted: ".$abortReason."<br/>";
}
else {
echo "ImagickException caught: ".$e->getMessage()." Exception type is ".get_class($e);
}
}

?>


Sets the ImageMagick registry entry named key to value

  • ≪ Imagick::setProgressMonitor
  • Imagick::setResolution ≫
  • PHP Manual
  • Imagick
  • Sets the ImageMagick registry entry named key to value

Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Sets the ImageMagick registry entry named key to value

説明

public static Imagick::setRegistry(string $key, string $value): bool

Sets the ImageMagick registry entry named key to value. This is most useful for setting "temporary-path" which controls where ImageMagick creates temporary images e.g. while processing PDFs.

パラメータ

key

value

戻り値

成功した場合に true を返します。


画像の解像度を設定する

  • ≪ Imagick::setRegistry
  • Imagick::setResourceLimit ≫
  • PHP Manual
  • Imagick
  • 画像の解像度を設定する

Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — 画像の解像度を設定する

説明

public Imagick::setResolution(float $x_resolution, float $y_resolution): bool

画像の解像度を設定します。

パラメータ

x_resolution

水平方向の解像度。

y_resolution

垂直方向の解像度。

戻り値

成功した場合に true を返します。

注意

Imagick::setResolution() は、画像の読み込みや作成の前に呼ぶ必要があります。

参考

  • Imagick::setImageResolution() - 画像の解像度を設定する
  • Imagick::getImageResolution() - 画像の X 方向と Y 方向の解像度を取得する


特定のリソースの制限を設定する

  • ≪ Imagick::setResolution
  • Imagick::setSamplingFactors ≫
  • PHP Manual
  • Imagick
  • 特定のリソースの制限を設定する

Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — 特定のリソースの制限を設定する

説明

public static Imagick::setResourceLimit(int $type, int $limit): bool

このメソッドを使って、ImageMagick ライブラリのリソース制限を変更します。

パラメータ

type

リソースタイプ定数 のうちのひとつ。 単位は制限されるリソースのタイプに依存します。

limit

リソースの制限。単位は、制限するリソースの種類によって異なります。

戻り値

成功した場合に true を返します。

参考

  • Imagick::getResourceLimit() - 指定したリソースの制限を返す


画像のサンプリング係数を設定する

  • ≪ Imagick::setResourceLimit
  • Imagick::setSize ≫
  • PHP Manual
  • Imagick
  • 画像のサンプリング係数を設定する

Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — 画像のサンプリング係数を設定する

説明

public Imagick::setSamplingFactors(array $factors): bool

画像のサンプリング係数を設定します。

パラメータ

factors

戻り値

成功した場合に true を返します。

例

例1 Imagick::setSamplingFactors()

<?php
function setSamplingFactors($imagePath) {

$imagePath = "../imagick/images/FineDetail.png";
$imagick = new \Imagick(realpath($imagePath));
$imagick->setImageFormat('jpg');
$imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

$compressed = $imagick->getImageBlob();

$reopen = new \Imagick();
$reopen->readImageBlob($compressed);

$reopen->resizeImage(
$reopen->getImageWidth() * 4,
$reopen->getImageHeight() * 4,
\Imagick::FILTER_POINT,
1
);

header("Content-Type: image/jpg");
echo $reopen->getImageBlob();
}

?>


Imagick オブジェクトのサイズを設定する

  • ≪ Imagick::setSamplingFactors
  • Imagick::setSizeOffset ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのサイズを設定する

Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Imagick オブジェクトのサイズを設定する

説明

public Imagick::setSize(int $columns, int $rows): bool

Imagick オブジェクトのサイズを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。

パラメータ

columns

rows

戻り値

成功した場合に true を返します。


Imagick オブジェクトのサイズのオフセットを設定する

  • ≪ Imagick::setSize
  • Imagick::setType ≫
  • PHP Manual
  • Imagick
  • Imagick オブジェクトのサイズのオフセットを設定する

Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Imagick オブジェクトのサイズのオフセットを設定する

説明

public Imagick::setSizeOffset(int $columns, int $rows, int $offset): bool

Imagick オブジェクトのサイズとオフセットを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

columns

幅 (ピクセル単位)。

rows

高さ (ピクセル単位)。

offset

画像のオフセット。

戻り値

成功した場合に true を返します。


画像タイプ属性を設定する

  • ≪ Imagick::setSizeOffset
  • Imagick::shadeImage ≫
  • PHP Manual
  • Imagick
  • 画像タイプ属性を設定する

Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — 画像タイプ属性を設定する

説明

public Imagick::setType(int $image_type): bool

画像タイプ属性を設定します。

パラメータ

image_type

戻り値

成功した場合に true を返します。


3D 効果を作成する

  • ≪ Imagick::setType
  • Imagick::shadowImage ≫
  • PHP Manual
  • Imagick
  • 3D 効果を作成する

Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — 3D 効果を作成する

説明

public Imagick::shadeImage(bool $gray, float $azimuth, float $elevation): bool

遠くから光をあてているように見せる三次元効果を作成します。 光源の位置は azimuth と elevation で指定します。 azimuth は x 軸方向の角度で、elevation は Z 軸上のピクセル数です。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

gray

ゼロ以外の値で、各ピクセルに影をつけます。

azimuth

光源の方向を定義します。

elevation

光源の方向を定義します。

戻り値

成功した場合に true を返します。

エラー / 例外

失敗した場合に ImagickException をスローします。

例

例1 Imagick::shadeImage()

<?php
function shadeImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->shadeImage(true, 45, 20);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の影をシミュレートする

  • ≪ Imagick::shadeImage
  • Imagick::sharpenImage ≫
  • PHP Manual
  • Imagick
  • 画像の影をシミュレートする

Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — 画像の影をシミュレートする

説明

public Imagick::shadowImage(
float $opacity,
float $sigma,
int $x,
int $y
): bool

画像の影をシミュレートします。

パラメータ

opacity

sigma

x

y

戻り値

成功した場合に true を返します。

例

例1 Imagick::shadowImage()

<?php
function shadowImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->shadowImage(0.4, 10, 50, 5);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像をシャープにする

  • ≪ Imagick::shadowImage
  • Imagick::shaveImage ≫
  • PHP Manual
  • Imagick
  • 画像をシャープにする

Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — 画像をシャープにする

説明

public Imagick::sharpenImage(float $radius, float $sigma, int $channel = Imagick::CHANNEL_DEFAULT): bool

画像をシャープにします。指定した半径と標準偏差 (シグマ) によるガウス演算を施します。適切な結果を得るには、 半径をシグマより大きくする必要があります。半径を 0 に指定すると、適切な半径を Imagick::sharpenImage() が自動的に設定します。

パラメータ

radius

sigma

channel

戻り値

成功した場合に true を返します。

例

例1 Imagick::sharpenImage()

<?php
function sharpenImage($imagePath, $radius, $sigma, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->sharpenimage($radius, $sigma, $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像の輪郭からピクセルを刈り取る

  • ≪ Imagick::sharpenImage
  • Imagick::shearImage ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭からピクセルを刈り取る

Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — 画像の輪郭からピクセルを刈り取る

説明

public Imagick::shaveImage(int $columns, int $rows): bool

画像の輪郭からピクセルを刈り取ります。 新しい画像に必要なメモリを確保し、新しい画像へのポインタを返します。

パラメータ

columns

rows

戻り値

成功した場合に true を返します。

例

例1 Imagick::shaveImage()

<?php
function shaveImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->shaveImage(100, 50);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


平行四辺形を作成する

  • ≪ Imagick::shaveImage
  • Imagick::sigmoidalContrastImage ≫
  • PHP Manual
  • Imagick
  • 平行四辺形を作成する

Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — 平行四辺形を作成する

説明

public Imagick::shearImage(mixed $background, float $x_shear, float $y_shear): bool

画像を X 軸方向あるいは Y 軸方向に押しつぶし、平行四辺形を作成します。 X 方向に押しつぶすと X 軸方向にスライドし、Y 方向に押しつぶすと Y 軸方向にスライドします。押しつぶす量は、角度で指定します。 X 方向に押しつぶす場合、x_shear は Y 軸からの相対角度となります。 同様に、Y 方向に押しつぶす場合は y_shear が X 軸からの相対角度となります。 変形によってできた空白部分は、背景色で埋められます。

パラメータ

background

背景色。

x_shear

x 軸方向に押しつぶす角度。

y_shear

y 軸方向に押しつぶす角度。

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::shearImage()

<?php
function shearImage($imagePath, $color, $shearX, $shearY) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->shearimage($color, $shearX, $shearY);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像のコントラストを調整する

  • ≪ Imagick::shearImage
  • Imagick::sketchImage ≫
  • PHP Manual
  • Imagick
  • 画像のコントラストを調整する

Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — 画像のコントラストを調整する

説明

public Imagick::sigmoidalContrastImage(
bool $sharpen,
float $alpha,
float $beta,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

非線形 S 字コントラストアルゴリズムを用いて画像のコントラストを調整します。 S 字変換関数を使用し、ハイライトや影を飽和させることなく画像のコントラストを強調します。 contrast は、どの程度コントラストを向上させるかを表します (0 は何もしない、3 は一般的な程度、20 は押し出す) mid-point は、結果の画像での中間色の扱いを表します (0 は白、50 はグレー、100 は黒)。sharpen を true にするとコントラストを強め、それ以外にするとコントラストを弱めます。

» ImageMagick v6 Examples - Image Transformations — Sigmoidal Non-linearity Contrast も参照ください。

パラメータ

sharpen

If true increase the contrast, if false decrease the contrast.

alpha

The amount of contrast to apply. 1 is very little, 5 is a significant amount, 20 is extreme.

beta

Where the midpoint of the gradient will be. This value should be in the range 0 to 1 - mutliplied by the quantum value for ImageMagick.

channel

Which color channels the contrast will be applied to.

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::sigmoidalContrastImage() によるグラデーションの作成 (ふたつの画像を、$contrast と $midpoint の定義でブレンドする)

<?php

function generateBlendImage($width, $height, $contrast = 10, $midpoint = 0.5) {
$imagick = new Imagick();
$imagick->newPseudoImage($width, $height, 'gradient:black-white');
$quanta = $imagick->getQuantumRange();
$imagick->sigmoidalContrastImage(true, $contrast, $midpoint * $quanta["quantumRangeLong"]);

return $imagick;
}

?>


鉛筆画をシミュレートする

  • ≪ Imagick::sigmoidalContrastImage
  • Imagick::smushImages ≫
  • PHP Manual
  • Imagick
  • 鉛筆画をシミュレートする

Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — 鉛筆画をシミュレートする

説明

public Imagick::sketchImage(float $radius, float $sigma, float $angle): bool

鉛筆画をシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、 Imagick::sketchImage() が適切な半径を自動的に設定します。 angle で、モーションブラーの角度を指定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

radius

ガウス変換の半径 (ピクセル単位で中心のピクセルは数えない)。

sigma

ガウス変換の標準偏差 (ピクセル単位)。

angle

この角度で効果を適用します。

戻り値

成功した場合に true を返します。

例

例1 Imagick::sketchImage()

<?php
function sketchImage($imagePath, $radius, $sigma, $angle) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->sketchimage($radius, $sigma, $angle);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Takes all images from the current image pointer to the end of the image list and smushs them

  • ≪ Imagick::sketchImage
  • Imagick::solarizeImage ≫
  • PHP Manual
  • Imagick
  • Takes all images from the current image pointer to the end of the image list and smushs them

Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Takes all images from the current image pointer to the end of the image list and smushs them

説明

public Imagick::smushImages(bool $stack, int $offset): Imagick

Takes all images from the current image pointer to the end of the image list and smushs them to each other top-to-bottom if the stack parameter is true, otherwise left-to-right.

パラメータ

stack

offset

戻り値

The new smushed image.

例

例1 Imagick::smushImages()

<?php
function smushImages($imagePath, $imagePath2) {

$imagick = new \Imagick(realpath($imagePath));
$imagick2 = new \Imagick(realpath($imagePath2));

$imagick->addimage($imagick2);
$smushed = $imagick->smushImages(false, 50);
$smushed->setImageFormat('jpg');
header("Content-Type: image/jpg");
echo $smushed->getImageBlob();
}

?>


画像にソラリゼーション効果を適用する

  • ≪ Imagick::smushImages
  • Imagick::sparseColorImage ≫
  • PHP Manual
  • Imagick
  • 画像にソラリゼーション効果を適用する

Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — 画像にソラリゼーション効果を適用する

説明

public Imagick::solarizeImage(int $threshold): bool

画像に特殊効果を施し、 印画紙の特定の箇所の露光時間を長くしたような画像になります。 threshold は 0 から QuantumRange までの値で、 ソラリゼーションの効き具合を指定します。

パラメータ

threshold

戻り値

成功した場合に true を返します。

例

例1 Imagick::solarizeImage()

<?php
function solarizeImage($imagePath, $solarizeThreshold) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


色を補間する

  • ≪ Imagick::solarizeImage
  • Imagick::spliceImage ≫
  • PHP Manual
  • Imagick
  • 色を補間する

Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — 色を補間する

説明

public Imagick::sparseColorImage(int $SPARSE_METHOD, array $arguments, int $channel = Imagick::CHANNEL_DEFAULT): bool

数値を含む配列を引数として受け取り、画像全体にわたって見つかった座標の色を補間します。補間には sparse_method を用います。 このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

SPARSE_METHOD

sparse method 定数 の一覧を参照ください。

arguments

座標を含む配列。配列の書式は array(1,1, 2,45) のようになります。

channel

そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは Imagick::CHANNEL_DEFAULT です。 チャネル定数 の一覧を参照ください。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

<?php
function renderImageBarycentric2() {
$points = [
[0.30, 0.10, 'red'],
[0.10, 0.80, 'blue'],
[0.70, 0.60, 'lime'],
[0.80, 0.20, 'yellow'],
];
$imagick = createGradientImage(
400, 400,
$points,
\Imagick::SPARSECOLORMETHOD_BARYCENTRIC
);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>

例2 SPARSECOLORMETHOD_BILINEAR Imagick::sparseColorImage()

<?php
function renderImageBilinear() {
$points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
$imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>

例3 SPARSECOLORMETHOD_SPEPARDS Imagick::sparseColorImage()

<?php
function renderImageShepards() {
$points = [
[0.30, 0.10, 'red'],
[0.10, 0.80, 'blue'],
[0.70, 0.60, 'lime'],
[0.80, 0.20, 'yellow'],
];
$imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>

例4 SPARSECOLORMETHOD_VORONOI Imagick::sparseColorImage()

<?php
function renderImageVoronoi() {
$points = [
[0.30, 0.10, 'red'],
[0.10, 0.80, 'blue'],
[0.70, 0.60, 'lime'],
[0.80, 0.20, 'yellow'],
];
$imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>

例5 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

<?php
function renderImageBarycentric() {
$points = [
[0, 0, 'skyblue'],
[-1, 1, 'skyblue'],
[1, 1, 'black'],
];
$imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>

例6 createGradientImage is used by other examples. Imagick::sparseColorImage()

<?php
function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

$imagick = new \Imagick();
$imagick->newImage($width, $height, "white");
$imagick->setImageFormat("png");

$barycentricPoints = array();

foreach ($colorPoints as $colorPoint) {

if ($absolute == true) {
$barycentricPoints[] = $colorPoint[0];
$barycentricPoints[] = $colorPoint[1];
}
else {
$barycentricPoints[] = $colorPoint[0] * $width;
$barycentricPoints[] = $colorPoint[1] * $height;
}

if (is_string($colorPoint[2])) {
$imagickPixel = new \ImagickPixel($colorPoint[2]);
}
else if ($colorPoint[2] instanceof \ImagickPixel) {
$imagickPixel = $colorPoint[2];
}
else{
$errorMessage = sprintf(
"Value %s is neither a string nor an ImagickPixel class. Cannot use as a color.",
$colorPoint[2]
);

throw new \InvalidArgumentException(
$errorMessage
);
}

$red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
$green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
$blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
$alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

$barycentricPoints[] = $red;
$barycentricPoints[] = $green;
$barycentricPoints[] = $blue;
$barycentricPoints[] = $alpha;
}

$imagick->sparseColorImage($sparseMethod, $barycentricPoints);

return $imagick;
}

?>


無地の画像を作成する

  • ≪ Imagick::sparseColorImage
  • Imagick::spreadImage ≫
  • PHP Manual
  • Imagick
  • 無地の画像を作成する

Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — 無地の画像を作成する

説明

public Imagick::spliceImage(
int $width,
int $height,
int $x,
int $y
): bool

無地の画像を作成します。

パラメータ

width

height

x

y

戻り値

成功した場合に true を返します。

例

例1 Imagick::spliceImage()

<?php
function spliceImage($imagePath, $startX, $startY, $width, $height) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->spliceImage($width, $height, $startX, $startY);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


ブロック内の各ピクセルをランダムに移動する

  • ≪ Imagick::spliceImage
  • Imagick::statisticImage ≫
  • PHP Manual
  • Imagick
  • ブロック内の各ピクセルをランダムに移動する

Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する

説明

public Imagick::spreadImage(float $radius): bool

radius パラメータで定義したブロック内の各ピクセルを、 ランダムに移動させます。

パラメータ

radius

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::spreadImage()

<?php
function spreadImage($imagePath, $radius) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->spreadImage($radius);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


Modifies image using a statistics function

  • ≪ Imagick::spreadImage
  • Imagick::steganoImage ≫
  • PHP Manual
  • Imagick
  • Modifies image using a statistics function

Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Modifies image using a statistics function

説明

public Imagick::statisticImage(
int $type,
int $width,
int $height,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

Replace each pixel with corresponding statistic from the neighborhood of the specified width and height.

パラメータ

type

width

height

channel

戻り値

成功した場合に true を返します。

例

例1 Imagick::statisticImage()

<?php
function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
$imagick = new \Imagick(realpath($imagePath));

$imagick->statisticImage(
$statisticType,
$width,
$height,
$channel
);

header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

?>


デジタル透かしを画像に埋め込む

  • ≪ Imagick::statisticImage
  • Imagick::stereoImage ≫
  • PHP Manual
  • Imagick
  • デジタル透かしを画像に埋め込む

Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — デジタル透かしを画像に埋め込む

説明

public Imagick::steganoImage(Imagick $watermark_wand, int $offset): Imagick

デジタル透かしを画像に埋め込みます。 あとでこの透かしが見つかれば、その画像の出所を証明することができます。 offset は、透かしの埋め込みを開始する位置を指定します。

パラメータ

watermark_wand

offset

戻り値

成功した場合に true を返します。


ふたつの画像を合成する

  • ≪ Imagick::steganoImage
  • Imagick::stripImage ≫
  • PHP Manual
  • Imagick
  • ふたつの画像を合成する

Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — ふたつの画像を合成する

説明

public Imagick::stereoImage(Imagick $offset_wand): bool

ふたつの画像を合成してひとつの画像にします。 左と右の画像を合成してステレオ効果を生み出します。

パラメータ

offset_wand

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


画像からすべてのプロパティやコメントを除去する

  • ≪ Imagick::stereoImage
  • Imagick::subImageMatch ≫
  • PHP Manual
  • Imagick
  • 画像からすべてのプロパティやコメントを除去する

Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する

説明

public Imagick::stripImage(): bool

画像からすべてのプロパティやコメントを除去します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。


Searches for a subimage in the current image and returns a similarity image

  • ≪ Imagick::stripImage
  • Imagick::swirlImage ≫
  • PHP Manual
  • Imagick
  • Searches for a subimage in the current image and returns a similarity image

Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image

説明

public Imagick::subImageMatch(Imagick $Imagick, array &$offset = ?, float &$similarity = ?): Imagick

Searches for a subimage in the current image and returns a similarity image such that an exact match location is completely white and if none of the pixels match, black, otherwise some gray level in-between. You can also pass in the optional parameters bestMatch and similarity. After calling the function similarity will be set to the 'score' of the similarity between the subimage and the matching position in the larger image, bestMatch will contain an associative array with elements x, y, width, height that describe the matching region.

パラメータ

Imagick

offset

similarity

A new image that displays the amount of similarity at each pixel.

戻り値

例

例1 Imagick::subImageMatch()

<?php
function subImageMatch($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick2 = clone $imagick;
$imagick2->cropimage(40, 40, 250, 110);
$imagick2->vignetteimage(0, 1, 3, 3);

$similarity = null;
$bestMatch = null;
$comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

$comparison->setImageFormat('png');
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


画像の中心から、ピクセルを渦巻状にする

  • ≪ Imagick::subImageMatch
  • Imagick::textureImage ≫
  • PHP Manual
  • Imagick
  • 画像の中心から、ピクセルを渦巻状にする

Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする

説明

Imagick::swirlImage(float $degrees): bool

画像の中心から、ピクセルを渦巻状にします。 degrees は個々のピクセルが移動する弧の量を表します。 degrees を 1 から 360 まで変化させると、劇的な効果が得られます。

パラメータ

degrees

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::swirlImage()

<?php
function swirlImage($imagePath, $swirl) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->swirlImage($swirl);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


テクスチャ画像をタイル状に並べる

  • ≪ Imagick::swirlImage
  • Imagick::thresholdImage ≫
  • PHP Manual
  • Imagick
  • テクスチャ画像をタイル状に並べる

Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — テクスチャ画像をタイル状に並べる

説明

Imagick::textureImage(Imagick $texture_wand): Imagick

テクスチャ画像をタイル状に繰り返し並べます。

パラメータ

texture_wand

テクスチャ画像として使用する Imagick オブジェクト

戻り値

テクスチャ画像を繰り返し適用した新しい Imagick オブジェクトを返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::textureImage()

<?php
function textureImage($imagePath) {
$image = new \Imagick();
$image->newImage(640, 480, new \ImagickPixel('pink'));
$image->setImageFormat("jpg");
$texture = new \Imagick(realpath($imagePath));
$texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
$image = $image->textureImage($texture);
header("Content-Type: image/jpg");
echo $image;
}

?>


閾値にもとづいて個々のピクセルの値を変更する

  • ≪ Imagick::textureImage
  • Imagick::thumbnailImage ≫
  • PHP Manual
  • Imagick
  • 閾値にもとづいて個々のピクセルの値を変更する

Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する

説明

public Imagick::thresholdImage(float $threshold, int $channel = Imagick::CHANNEL_DEFAULT): bool

個々のピクセルの輝度を閾値と比較し、その色を変更します。 変換結果は、コントラストの高い 2 色の画像となります。

パラメータ

threshold

channel

戻り値

成功した場合に true を返します。

例

例1 Imagick::thresholdImage()

<?php
function thresholdimage($imagePath, $threshold, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


画像のサイズを変更する

  • ≪ Imagick::thresholdImage
  • Imagick::tintImage ≫
  • PHP Manual
  • Imagick
  • 画像のサイズを変更する

Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — 画像のサイズを変更する

説明

public Imagick::thumbnailImage(
int $columns,
int $rows,
bool $bestfit = false,
bool $fill = false,
bool $legacy = false
): bool

画像のサイズを指定したものに変更し、関連付けられたプロパティをすべて削除します。 ウェブ上での表示に適した小さなサムネイル画像を作成します。 3 番目のパラメータに true を指定すると、columns や rows にそれぞれの最大値を使用します。両方のパラメータが、 マッチするまであるいは指定したパラメータより小さくなるまで縮小されます。

注意: パラメータ bestfit の挙動は Imagick 3.0.0 で変わりました。 これより前のバージョンでは、200x150 の画像に対して 400x400 を指定した場合は何もせずそのままになっていました。 Imagick 3.0.0 以降では、この画像は 400x300 に拡大されます。これが、 指定したサイズに対して「ベストフィット」する大きさだからです。 bestfit を使う場合は、幅と高さの両方を指定しなければなりません。

パラメータ

columns

画像の幅。

rows

画像の高さ。

bestfit

最大値を強制的に使用するかどうか。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::thumbnailImage()

<?php
function thumbnailImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->setbackgroundcolor('rgb(64, 64, 64)');
$imagick->thumbnailImage(100, 100, true, true);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


色ベクトルを画像の各ピクセルに適用する

  • ≪ Imagick::thumbnailImage
  • Imagick::__toString ≫
  • PHP Manual
  • Imagick
  • 色ベクトルを画像の各ピクセルに適用する

Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する

説明

public Imagick::tintImage(mixed $tint, mixed $opacity, bool $legacy = false): bool

色ベクトルを画像の各ピクセルに適用します。 ベクトルの長さは、黒および白のときに 0、中間色のときに最大となります。 ベクトルの重み関数は f(x)=(1-(4.0*((x-0.5)*(x-0.5)))) です。

パラメータ

tint

opacity

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列を最初のパラメータとして、 不透明度を表す浮動小数点数値を 2 番目のパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::tintImage()

<?php
function tintImage($r, $g, $b, $a) {
$a = $a / 100;

$imagick = new \Imagick();
$imagick->newPseudoImage(400, 400, 'gradient:black-white');

$tint = new \ImagickPixel("rgb($r, $g, $b)");
$opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
$imagick->tintImage($tint, $opacity);
$imagick->setImageFormat('png');
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


Returns the image as a string

  • ≪ Imagick::tintImage
  • Imagick::transformImage ≫
  • PHP Manual
  • Imagick
  • Returns the image as a string

Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Returns the image as a string

説明

public Imagick::__toString(): string

Returns the current image as string. This will only return a single image; it should not be used for Imagick objects that contain multiple images e.g. an animated GIF or PDF with multiple pages.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the string content on success or an empty string on failure.

参考

  • Imagick::getImageBlob() - 画像シーケンスを blob で返す
  • Imagick::getImagesBlob() - すべての画像シーケンスを blob で返す


切り取るサイズと画像のジオメトリを設定する便利なメソッド

  • ≪ Imagick::__toString
  • Imagick::transformImageColorspace ≫
  • PHP Manual
  • Imagick
  • 切り取るサイズと画像のジオメトリを設定する便利なメソッド

Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

説明

public Imagick::transformImage(string $crop, string $geometry): Imagick

切り取るサイズと画像のジオメトリを設定する便利なメソッドです。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

crop

切り取りジオメトリ文字列。 このジオメトリで画像の一部の範囲を指定し、その部分を切り取ります。

geometry

画像ジオメトリ文字列。このジオメトリで最終的な画像のサイズを指定します。

戻り値

変換後の画像を含む Imagick オブジェクトを返します。

例

例1 Imagick::transformImage() の使用

この例は 100x100 の黒い画像を作成します。

<?php
$image = new Imagick();
$image->newImage(300, 200, "black");
$new_image = $image->transformImage("100x100", "100x100");
$new_image->writeImage('test_out.jpg');
?>

参考

  • Imagick::cropImage() - 画像の一部を抽出する
  • Imagick::resizeImage() - 画像のサイズを変更する
  • Imagick::thumbnailImage() - 画像のサイズを変更する


Transforms an image to a new colorspace

  • ≪ Imagick::transformImage
  • Imagick::transparentPaintImage ≫
  • PHP Manual
  • Imagick
  • Transforms an image to a new colorspace

Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Transforms an image to a new colorspace

説明

public Imagick::transformImageColorspace(int $colorspace): bool

Transforms an image to a new colorspace.

パラメータ

colorspace

The colorspace the image should be transformed to, one of the COLORSPACE constants e.g. Imagick::COLORSPACE_CMYK.

戻り値

成功した場合に true を返します。

例

例1 Imagick::transformImageColorspace() example

Transforms an image to a new colorspace, and then extracts a single channel so that the individual channel values can be viewed.

<?php
function transformImageColorspace($imagePath, $colorSpace, $channel) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->transformimagecolorspace($colorSpace);
//channel should be one of the channel constants e.g. \Imagick::CHANNEL_BLUE
$imagick->separateImageChannel($channel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}
?>

参考

  • Imagick::setColorSpace() - 色空間を設定する


ピクセルを透過させる

  • ≪ Imagick::transformImageColorspace
  • Imagick::transposeImage ≫
  • PHP Manual
  • Imagick
  • ピクセルを透過させる

Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — ピクセルを透過させる

説明

public Imagick::transparentPaintImage(
mixed $target,
float $alpha,
float $fuzz,
bool $invert
): bool

対処の色にマッチするピクセルを透過させます。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

target

対象となる色。

alpha

透明度。1.0 は完全な不透明で 0.0 が完全な透明をあらわします。

fuzz

あいまいさをあらわす量。たとえば、これを 10 に設定すると、 赤色の値が 100 の色と 102 の色は同じものとみなされます。

invert

true の場合は、対象の色にマッチしないピクセルを変更します。

戻り値

成功した場合に true を返します。

例

例1 Imagick::transparentPaintImage()

<?php
function transparentPaintImage($color, $alpha, $fuzz) {
$imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

//Need to be in a format that supports transparency
$imagick->setimageformat('png');

$imagick->transparentPaintImage(
$color, $alpha, $fuzz * \Imagick::getQuantum(), false
);

//Not required, but helps tidy up left over pixels
$imagick->despeckleimage();

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


垂直方向に反転させた画像を作成する

  • ≪ Imagick::transparentPaintImage
  • Imagick::transverseImage ≫
  • PHP Manual
  • Imagick
  • 垂直方向に反転させた画像を作成する

Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — 垂直方向に反転させた画像を作成する

説明

public Imagick::transposeImage(): bool

垂直方向に反転させた画像を作成します。 中央の x 軸に対して反転させ、90 度回転させます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

例

例1 Imagick::transposeImage()

<?php
function transposeImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->transposeImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::transverseImage() - 水平方向に反転させた画像を作成する


水平方向に反転させた画像を作成する

  • ≪ Imagick::transposeImage
  • Imagick::trimImage ≫
  • PHP Manual
  • Imagick
  • 水平方向に反転させた画像を作成する

Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — 水平方向に反転させた画像を作成する

説明

public Imagick::transverseImage(): bool

水平方向に反転させた画像を作成します。 中央の y 軸に対して反転させ、270 度回転させます。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

例

例1 Imagick::transverseImage()

<?php
function transverseImage($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->transverseImage();
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::transposeImage() - 垂直方向に反転させた画像を作成する


画像の輪郭を削除する

  • ≪ Imagick::transverseImage
  • Imagick::uniqueImageColors ≫
  • PHP Manual
  • Imagick
  • 画像の輪郭を削除する

Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — 画像の輪郭を削除する

説明

public Imagick::trimImage(float $fuzz): bool

画像の背景色と同じ色の輪郭を削除します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

fuzz

デフォルトでは、対象の色は特定のピクセルの色とまったく同じでなければなりません。 しかし、ふたつの色が微妙に異なることもよくあります。 画像の fuzz メンバは、どの程度の色を「同じ色」とみなすかを表します。 このパラメータは、量の範囲の変化を表します。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::trimImage() の使用法

画像をトリムし、ブラウザに表示します。

<?php
/* オブジェクトを作成し、画像を読み込みます */
$im = new Imagick("image.jpg");

/* 画像をトリムします */
$im->trimImage(0);

/* 画像を出力します */
header("Content-Type: image/" . $im->getImageFormat());
echo $im;
?>

参考

  • Imagick::getQuantumDepth() - quantum depth を取得する
  • Imagick::getQuantumRange() - Imagick quantum range を返す
  • imagecropauto() - 利用可能なモードを指定して、画像を自動的にクロップする


ある 1 色以外のすべての色のピクセルを削除する

  • ≪ Imagick::trimImage
  • Imagick::unsharpMaskImage ≫
  • PHP Manual
  • Imagick
  • ある 1 色以外のすべての色のピクセルを削除する

Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する

説明

public Imagick::uniqueImageColors(): bool

ある 1 色以外のすべての色のピクセルを削除します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。

例

例1 Imagick::uniqueImageColors()

<?php
function uniqueImageColors($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
//Reduce the image to 256 colours nicely.
$imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
$imagick->uniqueImageColors();
$imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


画像をシャープにする

  • ≪ Imagick::uniqueImageColors
  • Imagick::valid ≫
  • PHP Manual
  • Imagick
  • 画像をシャープにする

Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — 画像をシャープにする

説明

public Imagick::unsharpMaskImage(
float $radius,
float $sigma,
float $amount,
float $threshold,
int $channel = Imagick::CHANNEL_DEFAULT
): bool

画像をシャープにします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、 Imagick::UnsharpMaskImage() が適切な半径を自動的に設定します。

パラメータ

radius

sigma

amount

threshold

channel

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 Imagick::unsharpMaskImage()

<?php
function unsharpMaskImage($imagePath, $radius, $sigma, $amount, $unsharpThreshold) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->unsharpMaskImage($radius, $sigma, $amount, $unsharpThreshold);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


現在のアイテムが有効かどうかを調べる

  • ≪ Imagick::unsharpMaskImage
  • Imagick::vignetteImage ≫
  • PHP Manual
  • Imagick
  • 現在のアイテムが有効かどうかを調べる

Imagick::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — 現在のアイテムが有効かどうかを調べる

説明

public Imagick::valid(): bool

現在のアイテムが有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


ビネットフィルタを画像に追加する

  • ≪ Imagick::valid
  • Imagick::waveImage ≫
  • PHP Manual
  • Imagick
  • ビネットフィルタを画像に追加する

Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — ビネットフィルタを画像に追加する

説明

public Imagick::vignetteImage(
float $blackPoint,
float $whitePoint,
int $x,
int $y
): bool

ビネット形式で画像の輪郭をぼかします。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

blackPoint

黒の点。

whitePoint

白の点。

x

楕円の X オフセット。

y

楕円の Y オフセット。

戻り値

成功した場合に true を返します。

例

例1 Imagick::vignetteImage()

<?php
function vignetteImage($imagePath, $blackPoint, $whitePoint, $x, $y) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->vignetteImage($blackPoint, $whitePoint, $x, $y);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::waveImage() - ウェーブフィルタを画像に適用する
  • Imagick::swirlImage() - 画像の中心から、ピクセルを渦巻状にする


ウェーブフィルタを画像に適用する

  • ≪ Imagick::vignetteImage
  • Imagick::whiteThresholdImage ≫
  • PHP Manual
  • Imagick
  • ウェーブフィルタを画像に適用する

Imagick::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — ウェーブフィルタを画像に適用する

説明

public Imagick::waveImage(float $amplitude, float $length): bool

ウェーブフィルタを画像に適用します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

amplitude

波の振幅。

length

波長。

戻り値

成功した場合に true を返します。

エラー / 例外

エラー時に ImagickException をスローします。

例

例1 WaveImage can be quite slow Imagick::waveImage()

<?php
function waveImage($imagePath, $amplitude, $length) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->waveImage($amplitude, $length);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>

参考

  • Imagick::solarizeImage() - 画像にソラリゼーション効果を適用する
  • Imagick::oilpaintImage() - 油絵をシミュレートする
  • Imagick::embossImage() - グレースケール画像に三次元効果を施して返す
  • Imagick::addNoiseImage() - ランダムなノイズを画像に追加する
  • Imagick::swirlImage() - 画像の中心から、ピクセルを渦巻状にする


閾値に満たないすべてのピクセルを白にする

  • ≪ Imagick::waveImage
  • Imagick::writeImage ≫
  • PHP Manual
  • Imagick
  • 閾値に満たないすべてのピクセルを白にする

Imagick::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする

説明

public Imagick::whiteThresholdImage(mixed $threshold): bool

Imagick::thresholdImage() と似ていますが、 これは閾値に満たないピクセルをすべて白にし、その他のピクセルはそのままにします。

パラメータ

threshold

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

例

例1 Imagick::whiteThresholdImage()

<?php
function whiteThresholdImage($imagePath, $color) {
$imagick = new \Imagick(realpath($imagePath));
$imagick->whiteThresholdImage($color);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();
}

?>


指定した名前で画像を書き込む

  • ≪ Imagick::whiteThresholdImage
  • Imagick::writeImageFile ≫
  • PHP Manual
  • Imagick
  • 指定した名前で画像を書き込む

Imagick::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — 指定した名前で画像を書き込む

説明

public Imagick::writeImage(string $filename = NULL): bool

指定した名前で画像を書き込みます。filename パラメータが NULL の場合は、 Imagick::readImage() あるいは Imagick::setImageFilename() で設定した名前で書き込みます。

パラメータ

filename

画像を書き出すファイル名。ファイルの拡張子で画像形式が決まります。 "jpg:test.png" のようにプレフィックスをつけると、拡張子が何であっても特定の形式で保存できます。

戻り値

成功した場合に true を返します。


画像をファイルハンドルに書き出す

  • ≪ Imagick::writeImage
  • Imagick::writeImages ≫
  • PHP Manual
  • Imagick
  • 画像をファイルハンドルに書き出す

Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — 画像をファイルハンドルに書き出す

説明

public Imagick::writeImageFile(resource $filehandle, string $format = ?): bool

開いているファイルハンドルに画像シーケンスを書き出します。 ハンドルは、fopen などで開いておかなければなりません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

filehandle

画像を書き出すファイルハンドル。

format

画像のフォーマット。 指定できる有効なフォーマットのリストは、 ImageMagick のコンパイル時に有効にした機能に依存します。 有効なフォーマットは、 Imagick::queryFormats() を使って実行時にも確認できます。

戻り値

成功した場合に true を返します。

参考

  • Imagick::queryFormats() - Imagick がサポートするフォーマットを返す


画像あるいは画像シーケンスを書き込む

  • ≪ Imagick::writeImageFile
  • Imagick::writeImagesFile ≫
  • PHP Manual
  • Imagick
  • 画像あるいは画像シーケンスを書き込む

Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — 画像あるいは画像シーケンスを書き込む

説明

public Imagick::writeImages(string $filename, bool $adjoin): bool

画像あるいは画像シーケンスを書き込みます。

パラメータ

filename

adjoin

戻り値

成功した場合に true を返します。


フレームをファイルハンドルに書き出す

  • ≪ Imagick::writeImages
  • ImagickDraw ≫
  • PHP Manual
  • Imagick
  • フレームをファイルハンドルに書き出す

Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — フレームをファイルハンドルに書き出す

説明

public Imagick::writeImagesFile(resource $filehandle, string $format = ?): bool

開いているファイルハンドルにすべての画像フレームを書き出します。 このメソッドを使うと、アニメーション gif やその他のマルチフレーム画像を書き出すことができます。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

パラメータ

filehandle

画像を書き出すファイルハンドル。

format

画像のフォーマット。 指定できる有効なフォーマットのリストは、 ImageMagick のコンパイル時に有効にした機能に依存します。 有効なフォーマットは、 Imagick::queryFormats() を使って実行時にも確認できます。

戻り値

成功した場合に true を返します。

参考

  • Imagick::queryFormats() - Imagick がサポートするフォーマットを返す


ImagickDraw クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

class ImagickDraw {
public affine(array $affine): bool
public annotation(float $x, float $y, string $text): bool
public arc(
float $sx,
float $sy,
float $ex,
float $ey,
float $sd,
float $ed
): bool
public bezier(array $coordinates): bool
public circle(
float $ox,
float $oy,
float $px,
float $py
): bool
public clear(): bool
public clone(): ImagickDraw
public color(float $x, float $y, int $paintMethod): bool
public comment(string $comment): bool
public composite(
int $compose,
float $x,
float $y,
float $width,
float $height,
Imagick $compositeWand
): bool
public __construct()
public destroy(): bool
public ellipse(
float $ox,
float $oy,
float $rx,
float $ry,
float $start,
float $end
): bool
public getClipPath(): string
public getClipRule(): int
public getClipUnits(): int
public getFillColor(): ImagickPixel
public getFillOpacity(): float
public getFillRule(): int
public getFont(): string
public getFontFamily(): string
public getFontSize(): float
public getFontStretch(): int
public getFontStyle(): int
public getFontWeight(): int
public getGravity(): int
public getStrokeAntialias(): bool
public getStrokeColor(): ImagickPixel
public getStrokeDashArray(): array
public getStrokeDashOffset(): float
public getStrokeLineCap(): int
public getStrokeLineJoin(): int
public getStrokeMiterLimit(): int
public getStrokeOpacity(): float
public getStrokeWidth(): float
public getTextAlignment(): int
public getTextAntialias(): bool
public getTextDecoration(): int
public getTextEncoding(): string
public getTextInterlineSpacing(): float
public getTextInterwordSpacing(): float
public getTextKerning(): float
public getTextUnderColor(): ImagickPixel
public getVectorGraphics(): string
public line(
float $sx,
float $sy,
float $ex,
float $ey
): bool
public matte(float $x, float $y, int $paintMethod): bool
public pathClose(): bool
public pathCurveToAbsolute(
float $x1,
float $y1,
float $x2,
float $y2,
float $x,
float $y
): bool
public pathCurveToQuadraticBezierAbsolute(
float $x1,
float $y1,
float $x,
float $y
): bool
public pathCurveToQuadraticBezierRelative(
float $x1,
float $y1,
float $x,
float $y
): bool
public pathCurveToQuadraticBezierSmoothAbsolute(float $x, float $y): bool
public pathCurveToQuadraticBezierSmoothRelative(float $x, float $y): bool
public pathCurveToRelative(
float $x1,
float $y1,
float $x2,
float $y2,
float $x,
float $y
): bool
public pathCurveToSmoothAbsolute(
float $x2,
float $y2,
float $x,
float $y
): bool
public pathCurveToSmoothRelative(
float $x2,
float $y2,
float $x,
float $y
): bool
public pathEllipticArcAbsolute(
float $rx,
float $ry,
float $x_axis_rotation,
bool $large_arc_flag,
bool $sweep_flag,
float $x,
float $y
): bool
public pathEllipticArcRelative(
float $rx,
float $ry,
float $x_axis_rotation,
bool $large_arc_flag,
bool $sweep_flag,
float $x,
float $y
): bool
public pathFinish(): bool
public pathLineToAbsolute(float $x, float $y): bool
public pathLineToHorizontalAbsolute(float $x): bool
public pathLineToHorizontalRelative(float $x): bool
public pathLineToRelative(float $x, float $y): bool
public pathLineToVerticalAbsolute(float $y): bool
public pathLineToVerticalRelative(float $y): bool
public pathMoveToAbsolute(float $x, float $y): bool
public pathMoveToRelative(float $x, float $y): bool
public pathStart(): bool
public point(float $x, float $y): bool
public polygon(array $coordinates): bool
public polyline(array $coordinates): bool
public pop(): bool
public popClipPath(): bool
public popDefs(): bool
public popPattern(): bool
public push(): bool
public pushClipPath(string $clip_mask_id): bool
public pushDefs(): bool
public pushPattern(
string $pattern_id,
float $x,
float $y,
float $width,
float $height
): bool
public rectangle(
float $x1,
float $y1,
float $x2,
float $y2
): bool
public render(): bool
public resetVectorGraphics(): bool
public rotate(float $degrees): bool
public roundRectangle(
float $x1,
float $y1,
float $x2,
float $y2,
float $rx,
float $ry
): bool
public scale(float $x, float $y): bool
public setClipPath(string $clip_mask): bool
public setClipRule(int $fill_rule): bool
public setClipUnits(int $clip_units): bool
public setFillAlpha(float $opacity): bool
public setFillColor(ImagickPixel $fill_pixel): bool
public setFillOpacity(float $fillOpacity): bool
public setFillPatternURL(string $fill_url): bool
public setFillRule(int $fill_rule): bool
public setFont(string $font_name): bool
public setFontFamily(string $font_family): bool
public setFontSize(float $pointsize): bool
public setFontStretch(int $fontStretch): bool
public setFontStyle(int $style): bool
public setFontWeight(int $font_weight): bool
public setGravity(int $gravity): bool
public setResolution(float $x_resolution, float $y_resolution): bool
public setStrokeAlpha(float $opacity): bool
public setStrokeAntialias(bool $stroke_antialias): bool
public setStrokeColor(ImagickPixel $stroke_pixel): bool
public setStrokeDashArray(array $dashArray): bool
public setStrokeDashOffset(float $dash_offset): bool
public setStrokeLineCap(int $linecap): bool
public setStrokeLineJoin(int $linejoin): bool
public setStrokeMiterLimit(int $miterlimit): bool
public setStrokeOpacity(float $stroke_opacity): bool
public setStrokePatternURL(string $stroke_url): bool
public setStrokeWidth(float $stroke_width): bool
public setTextAlignment(int $alignment): bool
public setTextAntialias(bool $antiAlias): bool
public setTextDecoration(int $decoration): bool
public setTextEncoding(string $encoding): bool
public setTextInterlineSpacing(float $spacing): bool
public setTextInterwordSpacing(float $spacing): bool
public setTextKerning(float $kerning): bool
public setTextUnderColor(ImagickPixel $under_color): bool
public setVectorGraphics(string $xml): bool
public setViewbox(
int $x1,
int $y1,
int $x2,
int $y2
): bool
public skewX(float $degrees): bool
public skewY(float $degrees): bool
public translate(float $x, float $y): bool
}

目次

  • ImagickDraw::affine — 現在のアフィン変換行列を設定する
  • ImagickDraw::annotation — 画像上にテキストを描画する
  • ImagickDraw::arc — 円弧を描画する
  • ImagickDraw::bezier — ベジエ曲線を描画する
  • ImagickDraw::circle — 円を描画する
  • ImagickDraw::clear — ImagickDraw をクリアする
  • ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する
  • ImagickDraw::color — 画像上に色を描画する
  • ImagickDraw::comment — コメントを追加する
  • ImagickDraw::composite — 現在の画像上に別の画像を合成する
  • ImagickDraw::__construct — ImagickDraw コンストラクタ
  • ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する
  • ImagickDraw::ellipse — 画像上に楕円を描画する
  • ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する
  • ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す
  • ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す
  • ImagickDraw::getFillColor — 塗りつぶし色を返す
  • ImagickDraw::getFillOpacity — 描画時の透過度を返す
  • ImagickDraw::getFillRule — 塗りつぶしルールを返す
  • ImagickDraw::getFont — フォントを返す
  • ImagickDraw::getFontFamily — フォントファミリーを返す
  • ImagickDraw::getFontSize — フォントのポイント数を返す
  • ImagickDraw::getFontStretch — Gets the font stretch to use when annotating with text
  • ImagickDraw::getFontStyle — フォントのスタイルを返す
  • ImagickDraw::getFontWeight — フォントの重さを返す
  • ImagickDraw::getGravity — テキストの配置時の gravity を返す
  • ImagickDraw::getStrokeAntialias — 現在の縁取りのアンチエイリアス設定を返す
  • ImagickDraw::getStrokeColor — オブジェクトの縁取りに使用する色を返す
  • ImagickDraw::getStrokeDashArray — パスの描画に使用する破線のパターンを表す配列を返す
  • ImagickDraw::getStrokeDashOffset — 破線パターンにおける破線の開始オフセットを返す
  • ImagickDraw::getStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を返す
  • ImagickDraw::getStrokeLineJoin — パスの角を描画する際に使用する形状を返す
  • ImagickDraw::getStrokeMiterLimit — マイターリミットを返す
  • ImagickDraw::getStrokeOpacity — オブジェクトの枠線の透明度を返す
  • ImagickDraw::getStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を返す
  • ImagickDraw::getTextAlignment — テキストの配置を返す
  • ImagickDraw::getTextAntialias — 現在のテキストのアンチエイリアス設定を返す
  • ImagickDraw::getTextDecoration — テキストの装飾を返す
  • ImagickDraw::getTextEncoding — テキストによる注記の際に使用するコードセットを返す
  • ImagickDraw::getTextInterlineSpacing — Gets the text interword spacing
  • ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing
  • ImagickDraw::getTextKerning — Gets the text kerning
  • ImagickDraw::getTextUnderColor — テキストの背景色を返す
  • ImagickDraw::getVectorGraphics — ベクターグラフィックを含む文字列を返す
  • ImagickDraw::line — 直線を描画する
  • ImagickDraw::matte — 画像の opacity チャネル上に描画する
  • ImagickDraw::pathClose — パス要素を現在のパスに追加する
  • ImagickDraw::pathCurveToAbsolute — 三次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToQuadraticBezierAbsolute — 二次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToQuadraticBezierRelative — 二次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — 二次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — 二次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToRelative — 三次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToSmoothAbsolute — 三次ベジエ曲線を描画する
  • ImagickDraw::pathCurveToSmoothRelative — 三次ベジエ曲線を描画する
  • ImagickDraw::pathEllipticArcAbsolute — 楕円弧を描画する
  • ImagickDraw::pathEllipticArcRelative — 楕円弧を描画する
  • ImagickDraw::pathFinish — 現在のパスを終了する
  • ImagickDraw::pathLineToAbsolute — 直線パスを描画する
  • ImagickDraw::pathLineToHorizontalAbsolute — 水平直線パスを描画する
  • ImagickDraw::pathLineToHorizontalRelative — 水平直線パスを描画する
  • ImagickDraw::pathLineToRelative — 直線パスを描画する
  • ImagickDraw::pathLineToVerticalAbsolute — 垂直直線パスを描画する
  • ImagickDraw::pathLineToVerticalRelative — 垂直直線パスを描画する
  • ImagickDraw::pathMoveToAbsolute — 新しいサブパスを開始する
  • ImagickDraw::pathMoveToRelative — 新しいサブパスを開始する
  • ImagickDraw::pathStart — パス描画リストの開始を宣言する
  • ImagickDraw::point — 点を描画する
  • ImagickDraw::polygon — 多角形を描画する
  • ImagickDraw::polyline — 線分群を描画する
  • ImagickDraw::pop — スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す
  • ImagickDraw::popClipPath — クリップパスの定義を終了する
  • ImagickDraw::popDefs — 定義リストを終了する
  • ImagickDraw::popPattern — パターン定義を終了する
  • ImagickDraw::push — 現在の ImagickDraw をコピーしてスタックに格納する
  • ImagickDraw::pushClipPath — クリップパスの定義を開始する
  • ImagickDraw::pushDefs — 後に続くコマンドが、処理の前に名前つき要素を作成することを示す
  • ImagickDraw::pushPattern — 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す
  • ImagickDraw::rectangle — 矩形を描画する
  • ImagickDraw::render — これまでのすべての描画コマンドを画像上にレンダリングする
  • ImagickDraw::resetVectorGraphics — Resets the vector graphics
  • ImagickDraw::rotate — 指定した回転を現在の座標空間に適用する
  • ImagickDraw::roundRectangle — 角が丸い矩形を描画する
  • ImagickDraw::scale — 倍率を調整する
  • ImagickDraw::setClipPath — 指定した名前のクリッピングパスを画像に関連付ける
  • ImagickDraw::setClipRule — クリッピングパスで使用する多角形塗りつぶしルールを設定する
  • ImagickDraw::setClipUnits — クリップパスの単位の解釈を設定する
  • ImagickDraw::setFillAlpha — 色やテクスチャによる塗りつぶしの際の透過度を設定する
  • ImagickDraw::setFillColor — オブジェクトの塗りつぶしに使用する色を設定する
  • ImagickDraw::setFillOpacity — 色やテクスチャによる塗りつぶしの際の透過度を設定する
  • ImagickDraw::setFillPatternURL — オブジェクトの塗りつぶしパターンとして使用する URL を設定する
  • ImagickDraw::setFillRule — 多角形の描画時に使用する塗りつぶしルールを設定する
  • ImagickDraw::setFont — テキストによる注記を行う際に使用するフォントを設定する
  • ImagickDraw::setFontFamily — テキストによる注記を行う際に使用するフォントファミリーを設定する
  • ImagickDraw::setFontSize — テキストによる注記を行う際に使用するフォントのポイント数を設定する
  • ImagickDraw::setFontStretch — テキストによる注記を行う際に使用するフォントの伸縮を設定する
  • ImagickDraw::setFontStyle — テキストによる注記を行う際に使用するフォントのスタイルを設定する
  • ImagickDraw::setFontWeight — フォントの重さを設定する
  • ImagickDraw::setGravity — テキストの配置時の gravity を設定する
  • ImagickDraw::setResolution — Sets the resolution
  • ImagickDraw::setStrokeAlpha — オブジェクトの枠線の透明度を指定する
  • ImagickDraw::setStrokeAntialias — 縁取りの枠線をアンチエイリアス処理するかどうかを制御する
  • ImagickDraw::setStrokeColor — オブジェクトの縁取りに使用する色を設定する
  • ImagickDraw::setStrokeDashArray — パスの描画に使用する破線のパターンを指定する
  • ImagickDraw::setStrokeDashOffset — 破線パターンにおける破線の開始オフセットを指定する
  • ImagickDraw::setStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を指定する
  • ImagickDraw::setStrokeLineJoin — パスの角を描画する際に使用する形状を指定する
  • ImagickDraw::setStrokeMiterLimit — マイターリミットを指定する
  • ImagickDraw::setStrokeOpacity — オブジェクトの枠線の透明度を指定する
  • ImagickDraw::setStrokePatternURL — オブジェクトの枠線の描画に使用するパターンを設定する
  • ImagickDraw::setStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を設定する
  • ImagickDraw::setTextAlignment — テキストの配置を指定する
  • ImagickDraw::setTextAntialias — テキストをアンチエイリアス処理するかどうかを制御する
  • ImagickDraw::setTextDecoration — 装飾を指定する
  • ImagickDraw::setTextEncoding — テキストのコードセットを指定する
  • ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing
  • ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing
  • ImagickDraw::setTextKerning — Sets the text kerning
  • ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する
  • ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する
  • ImagickDraw::setViewbox — キャンバス全体の大きさを設定する
  • ImagickDraw::skewX — 現在の座標系を水平方向に傾ける
  • ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける
  • ImagickDraw::translate — 現在の座標系に変換を適用する


現在のアフィン変換行列を設定する

  • ≪ ImagickDraw
  • ImagickDraw::annotation ≫
  • PHP Manual
  • ImagickDraw
  • 現在のアフィン変換行列を設定する

ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — 現在のアフィン変換行列を設定する

説明

public ImagickDraw::affine(array $affine): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のアフィン変換行列を、指定したものに設定します。

パラメータ

affine

アフィン行列のパラメータ。

戻り値

値を返しません。

例

例1 ImagickDraw::affine() の例

<?php
function affine($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeWidth(1);
$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);

$PI = 3.141592653589794;
$angle = 60 * $PI / 360;

//Scale the drawing co-ordinates.
$affineScale = array("sx" => 1.75, "sy" => 1.75, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

//Shear the drawing co-ordinates.
$affineShear = array("sx" => 1, "sy" => 1, "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0);

//Rotate the drawing co-ordinates. The shear affine matrix
//produces incorrectly scaled drawings.
$affineRotate = array("sx" => cos($angle), "sy" => cos($angle), "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0,);

//Translate (offset) the drawing
$affineTranslate = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 30, "ty" => 30);

//The identiy affine matrix
$affineIdentity = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

$examples = [$affineScale, $affineShear, $affineRotate, $affineTranslate, $affineIdentity,];

$count = 0;

foreach ($examples as $example) {
$draw->push();
$draw->translate(($count % 2) * 250, intval($count / 2) * 250);
$draw->translate(100, 100);
$draw->affine($example);
$draw->rectangle(-50, -50, 50, 50);
$draw->pop();
$count++;
}

//Create an image object which the draw commands can be rendered into
$image = new \Imagick();
$image->newImage(500, 750, $backgroundColor);
$image->setImageFormat("png");

//Render the draw commands in the ImagickDraw object
//into the image.
$image->drawImage($draw);

//Send the image to the browser
header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


画像上にテキストを描画する

  • ≪ ImagickDraw::affine
  • ImagickDraw::arc ≫
  • PHP Manual
  • ImagickDraw
  • 画像上にテキストを描画する

ImagickDraw::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — 画像上にテキストを描画する

説明

public ImagickDraw::annotation(float $x, float $y, string $text): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上にテキストを描画します。

パラメータ

x

テキストを描画する x 座標。

y

テキストを描画する y 座標。

text

画像上に描画するテキスト。

戻り値

値を返しません。


円弧を描画する

  • ≪ ImagickDraw::annotation
  • ImagickDraw::bezier ≫
  • PHP Manual
  • ImagickDraw
  • 円弧を描画する

ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — 円弧を描画する

説明

public ImagickDraw::arc(
float $sx,
float $sy,
float $ex,
float $ey,
float $sd,
float $ed
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上の指定した矩形内に円弧を描画します。

パラメータ

sx

矩形の開始位置の x 座標。

sy

矩形の開始位置の y 座標。

ex

矩形の終了位置の x 座標。

ey

矩形の終了位置の y 座標。

sd

開始位置の角度。

ed

終了位置の角度。

戻り値

値を返しません。

例

例1 ImagickDraw::arc() の例

<?php
function arc($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $startAngle, $endAngle) {

//Create a ImagickDraw object to draw into.
$draw = new \ImagickDraw();
$draw->setStrokeWidth(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(2);

$draw->arc($startX, $startY, $endX, $endY, $startAngle, $endAngle);

//Create an image object which the draw commands can be rendered into
$image = new \Imagick();
$image->newImage(IMAGE_WIDTH, IMAGE_HEIGHT, $backgroundColor);
$image->setImageFormat("png");

//Render the draw commands in the ImagickDraw object
//into the image.
$image->drawImage($draw);

//Send the image to the browser
header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


ベジエ曲線を描画する

  • ≪ ImagickDraw::arc
  • ImagickDraw::circle ≫
  • PHP Manual
  • ImagickDraw
  • ベジエ曲線を描画する

ImagickDraw::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — ベジエ曲線を描画する

説明

public ImagickDraw::bezier(array $coordinates): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に点を指定してベジエ曲線を描画します。

パラメータ

coordinates

多次元配列。array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) ) のような形式。

戻り値

値を返しません。

例

例1 ImagickDraw::bezier() の例

<?php
function bezier($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$strokeColor = new \ImagickPixel($strokeColor);
$fillColor = new \ImagickPixel($fillColor);

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);

$smoothPointsSet = [
[
['x' => 10.0 * 5, 'y' => 10.0 * 5],
['x' => 30.0 * 5, 'y' => 90.0 * 5],
['x' => 25.0 * 5, 'y' => 10.0 * 5],
['x' => 50.0 * 5, 'y' => 50.0 * 5],
],
[
['x' => 50.0 * 5, 'y' => 50.0 * 5],
['x' => 75.0 * 5, 'y' => 90.0 * 5],
['x' => 70.0 * 5, 'y' => 10.0 * 5],
['x' => 90.0 * 5, 'y' => 40.0 * 5],
],
];

foreach ($smoothPointsSet as $points) {
$draw->bezier($points);
}

$disjointPoints = [
[
['x' => 10 * 5, 'y' => 10 * 5],
['x' => 30 * 5, 'y' => 90 * 5],
['x' => 25 * 5, 'y' => 10 * 5],
['x' => 50 * 5, 'y' => 50 * 5],
],
[
['x' => 50 * 5, 'y' => 50 * 5],
['x' => 80 * 5, 'y' => 50 * 5],
['x' => 70 * 5, 'y' => 10 * 5],
['x' => 90 * 5, 'y' => 40 * 5],
]
];
$draw->translate(0, 200);

foreach ($disjointPoints as $points) {
$draw->bezier($points);
}

//Create an image object which the draw commands can be rendered into
$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

//Render the draw commands in the ImagickDraw object
//into the image.
$imagick->drawImage($draw);

//Send the image to the browser
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


円を描画する

  • ≪ ImagickDraw::bezier
  • ImagickDraw::clear ≫
  • PHP Manual
  • ImagickDraw
  • 円を描画する

ImagickDraw::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — 円を描画する

説明

public ImagickDraw::circle(
float $ox,
float $oy,
float $px,
float $py
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に円を描画します。

パラメータ

ox

原点の x 座標。

oy

原点の y 座標。

px

周囲の x 座標。

py

周囲の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::circle() の例

<?php
function circle($strokeColor, $fillColor, $backgroundColor, $originX, $originY, $endX, $endY) {

//Create a ImagickDraw object to draw into.
$draw = new \ImagickDraw();

$strokeColor = new \ImagickPixel($strokeColor);
$fillColor = new \ImagickPixel($fillColor);

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->circle($originX, $originY, $endX, $endY);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


ImagickDraw をクリアする

  • ≪ ImagickDraw::circle
  • ImagickDraw::clone ≫
  • PHP Manual
  • ImagickDraw
  • ImagickDraw をクリアする

ImagickDraw::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — ImagickDraw をクリアする

説明

public ImagickDraw::clear(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw オブジェクト上のコマンドをすべてクリアし、 デフォルト設定で初期化します。

戻り値

ImagickDraw オブジェクトを返します。


指定した ImagickDraw オブジェクトの完全なコピーを作成する

  • ≪ ImagickDraw::clear
  • ImagickDraw::color ≫
  • PHP Manual
  • ImagickDraw
  • 指定した ImagickDraw オブジェクトの完全なコピーを作成する

ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する

説明

public ImagickDraw::clone(): ImagickDraw
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した ImagickDraw オブジェクトの完全なコピーを作成します。

戻り値

指定した ImagickDraw オブジェクトの完全なコピーを返します。


画像上に色を描画する

  • ≪ ImagickDraw::clone
  • ImagickDraw::comment ≫
  • PHP Manual
  • ImagickDraw
  • 画像上に色を描画する

ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — 画像上に色を描画する

説明

public ImagickDraw::color(float $x, float $y, int $paintMethod): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の塗りつぶし色を使用して、 指定した開始位置から指定した方法で画像上に色を描画します。

パラメータ

x

描画位置の x 座標。

y

描画位置の y 座標。

paintMethod

PAINT 定数 (imagick::PAINT_*) のいずれか

戻り値

値を返しません。


コメントを追加する

  • ≪ ImagickDraw::color
  • ImagickDraw::composite ≫
  • PHP Manual
  • ImagickDraw
  • コメントを追加する

ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — コメントを追加する

説明

public ImagickDraw::comment(string $comment): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ベクター出力ストリームにコメントを追加します。

パラメータ

comment

ベクター出力ストリームに追加するコメント文字列。

戻り値

値を返しません。


現在の画像上に別の画像を合成する

  • ≪ ImagickDraw::comment
  • ImagickDraw::__construct ≫
  • PHP Manual
  • ImagickDraw
  • 現在の画像上に別の画像を合成する

ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — 現在の画像上に別の画像を合成する

説明

public ImagickDraw::composite(
int $compose,
float $x,
float $y,
float $width,
float $height,
Imagick $compositeWand
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の画像上に別の画像を合成します。 合成演算子、位置、サイズを指定します。

パラメータ

compose

合成演算子 (imagick::COMPOSITE_*) のいずれか

x

左上角の x 座標。

y

左上角の y 座標。

width

合成する画像の幅。

height

合成する画像の高さ。

compositeWand

合成する画像を取得する Imagick オブジェクト。

戻り値

成功した場合に true を返します。

例

例1 ImagickDraw::composite() の例

<?php
function composite($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setFillOpacity(1);
$draw->setStrokeWidth(2);
$draw->setFontSize(72);
$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setStrokeWidth(2);
$draw->setFont("../fonts/CANDY.TTF");
$draw->setFontSize(140);
$draw->rectangle(0, 0, 1000, 300);
$draw->setFillColor('white');
$draw->setfillopacity(1);
$draw->annotation(50, 180, "Lorem Ipsum!");

//Create an image object which the draw commands can be rendered into
$imagick = new \Imagick();
$imagick->newImage(1000, 302, $backgroundColor);
$imagick->setImageFormat("png");

//Render the draw commands in the ImagickDraw object
//into the image.
$imagick->drawImage($draw);

//Send the image to the browser
header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


ImagickDraw コンストラクタ

  • ≪ ImagickDraw::composite
  • ImagickDraw::destroy ≫
  • PHP Manual
  • ImagickDraw
  • ImagickDraw コンストラクタ

ImagickDraw::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — ImagickDraw コンストラクタ

説明

public ImagickDraw::__construct()
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw のコンストラクタです。

戻り値

値を返しません。


関連付けられたすべてのリソースを開放する

  • ≪ ImagickDraw::__construct
  • ImagickDraw::ellipse ≫
  • PHP Manual
  • ImagickDraw
  • 関連付けられたすべてのリソースを開放する

ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する

説明

public ImagickDraw::destroy(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickDraw オブジェクトに関連付けられたすべてのリソースを開放します。

戻り値

値を返しません。


画像上に楕円を描画する

  • ≪ ImagickDraw::destroy
  • ImagickDraw::getClipPath ≫
  • PHP Manual
  • ImagickDraw
  • 画像上に楕円を描画する

ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — 画像上に楕円を描画する

説明

public ImagickDraw::ellipse(
float $ox,
float $oy,
float $rx,
float $ry,
float $start,
float $end
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に楕円を描画します。

パラメータ

ox

oy

rx

ry

start

end

戻り値

値を返しません。

例

例1 ImagickDraw::ellipse() の例

<?php
function ellipse($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->ellipse(125, 70, 100, 50, 0, 360);
$draw->ellipse(350, 70, 100, 50, 0, 315);

$draw->push();
$draw->translate(125, 250);
$draw->rotate(30);
$draw->ellipse(0, 0, 100, 50, 0, 360);
$draw->pop();

$draw->push();
$draw->translate(350, 250);
$draw->rotate(30);
$draw->ellipse(0, 0, 100, 50, 0, 315);
$draw->pop();

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


現在のクリッピングパスの ID を取得する

  • ≪ ImagickDraw::ellipse
  • ImagickDraw::getClipRule ≫
  • PHP Manual
  • ImagickDraw
  • 現在のクリッピングパスの ID を取得する

ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する

説明

public ImagickDraw::getClipPath(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のクリッピングパスの ID を取得します。

戻り値

クリッピングパスの ID を含む文字列、あるいはパスが存在しない場合に false を返します。


現在の多角形塗りつぶしルールを返す

  • ≪ ImagickDraw::getClipPath
  • ImagickDraw::getClipUnits ≫
  • PHP Manual
  • ImagickDraw
  • 現在の多角形塗りつぶしルールを返す

ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す

説明

public ImagickDraw::getClipRule(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリッピングパスで使用されている、現在の多角形塗りつぶしルールを返します。

戻り値

FILLRULE 定数 (imagick::FILLRULE_*) のいずれかを返します。


クリップパスの単位の解釈を返す

  • ≪ ImagickDraw::getClipRule
  • ImagickDraw::getFillColor ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの単位の解釈を返す

ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す

説明

public ImagickDraw::getClipUnits(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの単位の解釈を返します。

戻り値

成功した場合に整数値を返します。


塗りつぶし色を返す

  • ≪ ImagickDraw::getClipUnits
  • ImagickDraw::getFillOpacity ≫
  • PHP Manual
  • ImagickDraw
  • 塗りつぶし色を返す

ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — 塗りつぶし色を返す

説明

public ImagickDraw::getFillColor(): ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

描画オブジェクトで使用する塗りつぶし色を返します。

戻り値

ImagickPixel オブジェクトを返します。


描画時の透過度を返す

  • ≪ ImagickDraw::getFillColor
  • ImagickDraw::getFillRule ≫
  • PHP Manual
  • ImagickDraw
  • 描画時の透過度を返す

ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — 描画時の透過度を返す

説明

public ImagickDraw::getFillOpacity(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を返します。 完全に不透過の場合は 1.0 となります。

戻り値

透過度を返します。


塗りつぶしルールを返す

  • ≪ ImagickDraw::getFillOpacity
  • ImagickDraw::getFont ≫
  • PHP Manual
  • ImagickDraw
  • 塗りつぶしルールを返す

ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — 塗りつぶしルールを返す

説明

public ImagickDraw::getFillRule(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

多角形の描画時に使用する塗りつぶしルールを返します。

戻り値

FILLRULE 定数 (imagick::FILLRULE_*) を返します。


フォントを返す

  • ≪ ImagickDraw::getFillRule
  • ImagickDraw::getFontFamily ≫
  • PHP Manual
  • ImagickDraw
  • フォントを返す

ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — フォントを返す

説明

public ImagickDraw::getFont(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントを文字列で返します。

戻り値

成功した場合に文字列、フォントが設定されていない場合に false を返します。


フォントファミリーを返す

  • ≪ ImagickDraw::getFont
  • ImagickDraw::getFontSize ≫
  • PHP Manual
  • ImagickDraw
  • フォントファミリーを返す

ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — フォントファミリーを返す

説明

public ImagickDraw::getFontFamily(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントファミリーを返します。

戻り値

現在選択されているフォントファミリー、 あるいはフォントファミリーが設定されていない場合に false を返します。


フォントのポイント数を返す

  • ≪ ImagickDraw::getFontFamily
  • ImagickDraw::getFontStretch ≫
  • PHP Manual
  • ImagickDraw
  • フォントのポイント数を返す

ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — フォントのポイント数を返す

説明

public ImagickDraw::getFontSize(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのポイント数を返します。

戻り値

現在の ImagickDraw オブジェクトに関連付けられているフォントのサイズを返します。


Gets the font stretch to use when annotating with text

  • ≪ ImagickDraw::getFontSize
  • ImagickDraw::getFontStyle ≫
  • PHP Manual
  • ImagickDraw
  • Gets the font stretch to use when annotating with text

ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — Gets the font stretch to use when annotating with text

説明

public ImagickDraw::getFontStretch(): int

Gets the font stretch to use when annotating with text. Returns a StretchType.

パラメータ

この関数にはパラメータはありません。

戻り値


フォントのスタイルを返す

  • ≪ ImagickDraw::getFontStretch
  • ImagickDraw::getFontWeight ≫
  • PHP Manual
  • ImagickDraw
  • フォントのスタイルを返す

ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — フォントのスタイルを返す

説明

public ImagickDraw::getFontStyle(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのスタイルを返します。

戻り値

ImagickDraw オブジェクトに関連付けられたフォントの スタイル を表す定数(imagick::STYLE_*)、 あるいはスタイルが設定されていない場合に 0 を返します。


フォントの重さを返す

  • ≪ ImagickDraw::getFontStyle
  • ImagickDraw::getGravity ≫
  • PHP Manual
  • ImagickDraw
  • フォントの重さを返す

ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — フォントの重さを返す

説明

public ImagickDraw::getFontWeight(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの重さを返します。

戻り値

成功した場合に整数値、重さが設定されていない場合に 0 を返します。


テキストの配置時の gravity を返す

  • ≪ ImagickDraw::getFontWeight
  • ImagickDraw::getStrokeAntialias ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置時の gravity を返す

ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — テキストの配置時の gravity を返す

説明

public ImagickDraw::getGravity(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するテキスト配置の gravity を返します。

戻り値

成功時に、GRAVITY 定数 (imagick::GRAVITY_*) を返します。 gravity が設定されていない場合は 0 を返します。


現在の縁取りのアンチエイリアス設定を返す

  • ≪ ImagickDraw::getGravity
  • ImagickDraw::getStrokeColor ≫
  • PHP Manual
  • ImagickDraw
  • 現在の縁取りのアンチエイリアス設定を返す

ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — 現在の縁取りのアンチエイリアス設定を返す

説明

public ImagickDraw::getStrokeAntialias(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の縁取りのアンチエイリアス設定を返します。 縁取りの枠線は、デフォルトでアンチエイリアス処理が行われます。 アンチエイリアスを無効にすると、 縁取りの描画時には縁取り色あるいはキャンバスの色のどちらかが用いられることになります。

戻り値

アンチエイリアスがオンの場合に true、オフの場合に false を返します。


オブジェクトの縁取りに使用する色を返す

  • ≪ ImagickDraw::getStrokeAntialias
  • ImagickDraw::getStrokeDashArray ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの縁取りに使用する色を返す

ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — オブジェクトの縁取りに使用する色を返す

説明

public ImagickDraw::getStrokeColor(): ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの縁取りに使用する色を返します。

パラメータ

stroke_color

戻り値

色を表す ImagickPixel オブジェクトを返します。


パスの描画に使用する破線のパターンを表す配列を返す

  • ≪ ImagickDraw::getStrokeColor
  • ImagickDraw::getStrokeDashOffset ≫
  • PHP Manual
  • ImagickDraw
  • パスの描画に使用する破線のパターンを表す配列を返す

ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — パスの描画に使用する破線のパターンを表す配列を返す

説明

public ImagickDraw::getStrokeDashArray(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パスの描画に使用する破線のパターンを表す配列を返します。

戻り値

成功した場合に配列、設定されていない場合は空の配列を返します。


破線パターンにおける破線の開始オフセットを返す

  • ≪ ImagickDraw::getStrokeDashArray
  • ImagickDraw::getStrokeLineCap ≫
  • PHP Manual
  • ImagickDraw
  • 破線パターンにおける破線の開始オフセットを返す

ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — 破線パターンにおける破線の開始オフセットを返す

説明

public ImagickDraw::getStrokeDashOffset(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

破線パターンにおける破線の開始オフセットを返します。

戻り値

オフセットを表す float 値、あるいは設定されていない場合に 0 を返します。


開かれたサブパスを描画する際に使用する端点の形状を返す

  • ≪ ImagickDraw::getStrokeDashOffset
  • ImagickDraw::getStrokeLineJoin ≫
  • PHP Manual
  • ImagickDraw
  • 開かれたサブパスを描画する際に使用する端点の形状を返す

ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を返す

説明

public ImagickDraw::getStrokeLineCap(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

開かれたサブパスを描画する際に使用する端点の形状を返します。

戻り値

LINECAP 定数 (imagick::LINECAP_*) を返します。 あるいは設定されていない場合に 0 を返します。


パスの角を描画する際に使用する形状を返す

  • ≪ ImagickDraw::getStrokeLineCap
  • ImagickDraw::getStrokeMiterLimit ≫
  • PHP Manual
  • ImagickDraw
  • パスの角を描画する際に使用する形状を返す

ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — パスの角を描画する際に使用する形状を返す

説明

public ImagickDraw::getStrokeLineJoin(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス (あるいはその他のベクター図形) の角を描画する際に使用する形状を返します。

戻り値

LINEJOIN 定数 (imagick::LINEJOIN_*) を返します。 あるいは設定されていない場合に 0 を返します。


マイターリミットを返す

  • ≪ ImagickDraw::getStrokeLineJoin
  • ImagickDraw::getStrokeOpacity ≫
  • PHP Manual
  • ImagickDraw
  • マイターリミットを返す

ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — マイターリミットを返す

説明

public ImagickDraw::getStrokeMiterLimit(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

マイターリミットを返します。 2 本の直線が小さい角度で連結され、かつ連結方法が 'lineJoin' に設定されている場合、 出来上がる線の角の部分が非常に長くなります。'miterLimit' は、miter length (角の長さ) と 'lineWidth' の比率の最大値です。

戻り値

マイターリミットを表す整数値、あるいは マイターリミットが設定されていない場合に 0 を返します。


オブジェクトの枠線の透明度を返す

  • ≪ ImagickDraw::getStrokeMiterLimit
  • ImagickDraw::getStrokeWidth ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の透明度を返す

ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — オブジェクトの枠線の透明度を返す

説明

public ImagickDraw::getStrokeOpacity(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を返します。

戻り値

透明度を表す float 型の値を返します。


オブジェクトの枠線の描画に使用する線の幅を返す

  • ≪ ImagickDraw::getStrokeOpacity
  • ImagickDraw::getTextAlignment ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の描画に使用する線の幅を返す

ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を返す

説明

public ImagickDraw::getStrokeWidth(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用する線の幅を返します。

戻り値

線幅を表す float 型の値を返します。


テキストの配置を返す

  • ≪ ImagickDraw::getStrokeWidth
  • ImagickDraw::getTextAntialias ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置を返す

ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — テキストの配置を返す

説明

public ImagickDraw::getTextAlignment(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際の配置を返します。

戻り値

ALIGN 定数 (imagick::ALIGN_*) を返します。 あるいは設定されていない場合に 0 を返します。


現在のテキストのアンチエイリアス設定を返す

  • ≪ ImagickDraw::getTextAlignment
  • ImagickDraw::getTextDecoration ≫
  • PHP Manual
  • ImagickDraw
  • 現在のテキストのアンチエイリアス設定を返す

ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — 現在のテキストのアンチエイリアス設定を返す

説明

public ImagickDraw::getTextAntialias(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のテキストのアンチエイリアス設定を返します。 これは、テキストのアンチエイリアス処理を行うかどうかを表すものです。 デフォルトでは、テキストのアンチエイリアス処理が行われます。

戻り値

テキストをアンチエイリアス処理する場合に true、 ない場合に false を返します。


テキストの装飾を返す

  • ≪ ImagickDraw::getTextAntialias
  • ImagickDraw::getTextEncoding ≫
  • PHP Manual
  • ImagickDraw
  • テキストの装飾を返す

ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — テキストの装飾を返す

説明

public ImagickDraw::getTextDecoration(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に適用する装飾を返します。

戻り値

DECORATION 定数 (imagick::DECORATION_*) を返します。 あるいは装飾が設定されていない場合に 0 を返します。


テキストによる注記の際に使用するコードセットを返す

  • ≪ ImagickDraw::getTextDecoration
  • ImagickDraw::getTextInterlineSpacing ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記の際に使用するコードセットを返す

ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — テキストによる注記の際に使用するコードセットを返す

説明

public ImagickDraw::getTextEncoding(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するコードセットを表す文字列を返します。

戻り値

コードセットを表す文字列、 あるいはエンコーディングが設定されていない場合に false を返します。


Gets the text interword spacing

  • ≪ ImagickDraw::getTextEncoding
  • ImagickDraw::getTextInterwordSpacing ≫
  • PHP Manual
  • ImagickDraw
  • Gets the text interword spacing

ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — Gets the text interword spacing

説明

public ImagickDraw::getTextInterlineSpacing(): float

Gets the text interword spacing.

パラメータ

この関数にはパラメータはありません。

戻り値


Gets the text interword spacing

  • ≪ ImagickDraw::getTextInterlineSpacing
  • ImagickDraw::getTextKerning ≫
  • PHP Manual
  • ImagickDraw
  • Gets the text interword spacing

ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing

説明

public ImagickDraw::getTextInterwordSpacing(): float

Gets the text interword spacing.

パラメータ

この関数にはパラメータはありません。

戻り値


Gets the text kerning

  • ≪ ImagickDraw::getTextInterwordSpacing
  • ImagickDraw::getTextUnderColor ≫
  • PHP Manual
  • ImagickDraw
  • Gets the text kerning

ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Gets the text kerning

説明

public ImagickDraw::getTextKerning(): float

Gets the text kerning.

パラメータ

この関数にはパラメータはありません。

戻り値


テキストの背景色を返す

  • ≪ ImagickDraw::getTextKerning
  • ImagickDraw::getVectorGraphics ≫
  • PHP Manual
  • ImagickDraw
  • テキストの背景色を返す

ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — テキストの背景色を返す

説明

public ImagickDraw::getTextUnderColor(): ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記の背景に置く矩形の色を返します。

戻り値

色を表す ImagickPixel オブジェクトを返します。


ベクターグラフィックを含む文字列を返す

  • ≪ ImagickDraw::getTextUnderColor
  • ImagickDraw::line ≫
  • PHP Manual
  • ImagickDraw
  • ベクターグラフィックを含む文字列を返す

ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — ベクターグラフィックを含む文字列を返す

説明

public ImagickDraw::getVectorGraphics(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw オブジェクトのインスタンスが作成された後で、 グラフィックメソッドのコールによってできあがったベクターグラフィックを文字列で返します。

戻り値

ベクターグラフィックを文字列で返します。


直線を描画する

  • ≪ ImagickDraw::getVectorGraphics
  • ImagickDraw::matte ≫
  • PHP Manual
  • ImagickDraw
  • 直線を描画する

ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — 直線を描画する

説明

public ImagickDraw::line(
float $sx,
float $sy,
float $ex,
float $ey
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の描画色、透明度そして線幅を使用して画像上に直線を描画します。

パラメータ

sx

開始位置の x 座標。

sy

開始位置の y 座標。

ex

終了位置の x 座標。

ey

終了位置の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::line() の例

<?php
function line($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->line(125, 70, 100, 50);
$draw->line(350, 170, 100, 150);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


画像の opacity チャネル上に描画する

  • ≪ ImagickDraw::line
  • ImagickDraw::pathClose ≫
  • PHP Manual
  • ImagickDraw
  • 画像の opacity チャネル上に描画する

ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — 画像の opacity チャネル上に描画する

説明

public ImagickDraw::matte(float $x, float $y, int $paintMethod): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像の opacity チャネル上に描画し、ピクセルの透過度に影響を与えます。

パラメータ

x

マットの x 座標。

y

マットの y 座標。

paintMethod

PAINT 定数 (imagick::PAINT_*) のうちのいずれか

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ImagickDraw::matte() の例

<?php
function matte($strokeColor, $fillColor, $backgroundColor, $paintType) {
$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->matte(120, 120, $paintType);
$draw->rectangle(100, 100, 300, 200);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


パス要素を現在のパスに追加する

  • ≪ ImagickDraw::matte
  • ImagickDraw::pathCurveToAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • パス要素を現在のパスに追加する

ImagickDraw::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — パス要素を現在のパスに追加する

説明

public ImagickDraw::pathClose(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス要素を現在のパスに追加し、 現在の点から現在のサブパスの直近の開始点 (通常は、直近の moveto の点となります) に直線を引くことで現在のパスを閉じます。

戻り値

値を返しません。


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathClose
  • ImagickDraw::pathCurveToQuadraticBezierAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToAbsolute(
float $x1,
float $y1,
float $x2,
float $y2,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線を描画します。 曲線の開始位置の制御点を (x1,y1)、終了位置の制御点を (x2,y2) とし、それぞれ絶対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

最初の制御点の x 座標。

y1

最初の制御点の y 座標。

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToAbsolute
  • ImagickDraw::pathCurveToQuadraticBezierRelative ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float $x1,
float $y1,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線を描画します。 制御点を (x1,y1) とし、絶対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

制御点の x 座標。

y1

制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::pathCurveToQuadraticBezierAbsolute() の例

<?php
function pathCurveToQuadraticBezierAbsolute($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->pathStart();
$draw->pathMoveToAbsolute(50,250);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is the first two params, and the end point is the last two params.
$draw->pathCurveToQuadraticBezierAbsolute(
150,50,
250,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothAbsolute(
450,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined relative from the current position by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothRelative(
200,-100
);

$draw->pathFinish();

$imagick = new \Imagick();
$imagick->newImage(700, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();

}

?>


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierAbsolute
  • ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierRelative(
float $x1,
float $y1,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線を描画します。 制御点を (x1,y1) とし、相対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

始点の x 座標。

y1

始点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierRelative
  • ImagickDraw::pathCurveToQuadraticBezierSmoothRelative ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線 (絶対座標) を描画します。 制御点の位置は、現在の点と直前のコマンドの制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut あるいは DrawPathCurveToQuadraticBezierSmoothRelative のいずれかでなかった場合は、現在の点を制御点とみなします)。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

この関数を使って、三次ベジエ曲線を描画することはできません。 描画できるのは、二次ベジエ曲線だけです。

パラメータ

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute() の例

<?php
$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor("black");
$draw->setFillColor("blue");

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->pathStart();
$draw->pathMoveToAbsolute(50,250);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is the first two params, and the end point is the last two params.
$draw->pathCurveToQuadraticBezierAbsolute(
150,50,
250,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothAbsolute(
450,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined relative from the current position by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothRelative(
200,-100
);

$draw->pathFinish();

$imagick = new \Imagick();
$imagick->newImage(700, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
?>


二次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute
  • ImagickDraw::pathCurveToRelative ≫
  • PHP Manual
  • ImagickDraw
  • 二次ベジエ曲線を描画する

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — 二次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToQuadraticBezierSmoothRelative(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線 (相対座標) を描画します。 制御点の位置は、現在の点と直前のコマンドの制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut あるいは DrawPathCurveToQuadraticBezierSmoothRelative のいずれかでなかった場合は、現在の点を制御点とみなします)。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

この関数を使って、三次ベジエ曲線を描画することはできません。 描画できるのは、二次ベジエ曲線だけです。

パラメータ

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::pathCurveToQuadraticBezierSmoothRelative() の例

<?php
$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor("black");
$draw->setFillColor("blue");

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->pathStart();
$draw->pathMoveToAbsolute(50,250);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is the first two params, and the end point is the last two params.
$draw->pathCurveToQuadraticBezierAbsolute(
150,50,
250,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothAbsolute(
450,250
);

// This specifies a quadratic bezier curve with the current position as the start
// point, the control point is mirrored from the previous curves control point
// and the end point is defined relative from the current position by the x, y values.
$draw->pathCurveToQuadraticBezierSmoothRelative(
200,-100
);

$draw->pathFinish();

$imagick = new \Imagick();
$imagick->newImage(700, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
?>


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToQuadraticBezierSmoothRelative
  • ImagickDraw::pathCurveToSmoothAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToRelative(
float $x1,
float $y1,
float $x2,
float $y2,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線を描画します。 曲線の開始位置の制御点を (x1,y1)、終了位置の制御点を (x2,y2) とし、それぞれ相対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x1

開始制御点の x 座標。

y1

開始制御点の y 座標。

x2

終了制御点の x 座標。

y2

終了制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToRelative
  • ImagickDraw::pathCurveToSmoothRelative ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToSmoothAbsolute(
float $x2,
float $y2,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線 (絶対座標) を描画します。 最初の制御点の位置は、現在の点と直前のコマンドの 2 番目の制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute あるいは DrawPathCurveToSmoothRelative のいずれかでなかった場合は、現在の点を最初の制御点とみなします)。 2 番目の制御点 (曲線の終了地点の制御点) は (x2,y2) となります。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。


三次ベジエ曲線を描画する

  • ≪ ImagickDraw::pathCurveToSmoothAbsolute
  • ImagickDraw::pathEllipticArcAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 三次ベジエ曲線を描画する

ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — 三次ベジエ曲線を描画する

説明

public ImagickDraw::pathCurveToSmoothRelative(
float $x2,
float $y2,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの三次ベジエ曲線 (相対座標) を描画します。 最初の制御点の位置は、現在の点と直前のコマンドの 2 番目の制御点の位置から推測します (直線のコマンドがなかったり、直前のコマンドが DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute あるいは DrawPathCurveToSmoothRelative のいずれかでなかった場合は、現在の点を最初の制御点とみなします)。 2 番目の制御点 (曲線の終了地点の制御点) は (x2,y2) となります。 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

パラメータ

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x

終点の x 座標。

y

終点の y 座標。

戻り値

値を返しません。


楕円弧を描画する

  • ≪ ImagickDraw::pathCurveToSmoothRelative
  • ImagickDraw::pathEllipticArcRelative ≫
  • PHP Manual
  • ImagickDraw
  • 楕円弧を描画する

ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — 楕円弧を描画する

説明

public ImagickDraw::pathEllipticArcAbsolute(
float $rx,
float $ry,
float $x_axis_rotation,
bool $large_arc_flag,
bool $sweep_flag,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の位置から (x, y) まで、絶対座標を使用して楕円弧を描画します。 楕円の大きさと方向は、2 つの半径 (rx, ry) と xAxisRotation で決まります。xAxisRotation は、楕円全体を座標系に対してどれだけ回転させるかを表すものです。 楕円の中心 (cx, cy) は、その他のパラメータの値から自動的に算出されます。 largeArcFlag および sweepFlag は自動計算を支援するためのもので、 楕円の描画方法を定義します。 large_arc_flag が true の場合は考えうる楕円のうち大きいほうを描画します。 sweep_flag が true の場合は時計回りの回転で楕円を描画します。

パラメータ

rx

x 方向の半径。

ry

y 方向の半径。

x_axis_rotation

x 軸の回転。

large_arc_flag

large arc フラグ。

sweep_flag

sweep フラグ。

x

x 座標。

y

y 座標。

戻り値

値を返しません。


楕円弧を描画する

  • ≪ ImagickDraw::pathEllipticArcAbsolute
  • ImagickDraw::pathFinish ≫
  • PHP Manual
  • ImagickDraw
  • 楕円弧を描画する

ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — 楕円弧を描画する

説明

public ImagickDraw::pathEllipticArcRelative(
float $rx,
float $ry,
float $x_axis_rotation,
bool $large_arc_flag,
bool $sweep_flag,
float $x,
float $y
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の位置から (x, y) まで、相対座標を使用して楕円弧を描画します。 楕円の大きさと方向は、2 つの半径 (rx, ry) と xAxisRotation で決まります。xAxisRotation は、楕円全体を座標系に対してどれだけ回転させるかを表すものです。 楕円の中心 (cx, cy) は、その他のパラメータの値から自動的に算出されます。 largeArcFlag および sweepFlag は自動計算を支援するためのもので、 楕円の描画方法を定義します。 large_arc_flag が true の場合は考えうる楕円のうち大きいほうを描画します。 sweep_flag が true の場合は時計回りの回転で楕円を描画します。

パラメータ

rx

x 方向の半径。

ry

y 方向の半径。

x_axis_rotation

x 軸の回転。

large_arc_flag

large arc フラグ。

sweep_flag

sweep フラグ。

x

x 座標。

y

y 座標。

戻り値

値を返しません。


現在のパスを終了する

  • ≪ ImagickDraw::pathEllipticArcRelative
  • ImagickDraw::pathLineToAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 現在のパスを終了する

ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — 現在のパスを終了する

説明

public ImagickDraw::pathFinish(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のパスを終了します。

戻り値

値を返しません。


直線パスを描画する

  • ≪ ImagickDraw::pathFinish
  • ImagickDraw::pathLineToHorizontalAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 直線パスを描画する

ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — 直線パスを描画する

説明

public ImagickDraw::pathLineToAbsolute(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して直線を描画します。 座標は新しい点に移動します。

パラメータ

x

始点の x 座標。

y

終点の x 座標。

戻り値

値を返しません。


水平直線パスを描画する

  • ≪ ImagickDraw::pathLineToAbsolute
  • ImagickDraw::pathLineToHorizontalRelative ≫
  • PHP Manual
  • ImagickDraw
  • 水平直線パスを描画する

ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — 水平直線パスを描画する

説明

public ImagickDraw::pathLineToHorizontalAbsolute(float $x): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して水平直線を描画します。 座標は新しい点に移動します。

パラメータ

x

x 座標。

戻り値

値を返しません。


水平直線パスを描画する

  • ≪ ImagickDraw::pathLineToHorizontalAbsolute
  • ImagickDraw::pathLineToRelative ≫
  • PHP Manual
  • ImagickDraw
  • 水平直線パスを描画する

ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — 水平直線パスを描画する

説明

public ImagickDraw::pathLineToHorizontalRelative(float $x): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して水平直線を描画します。 座標は新しい点に移動します。

パラメータ

x

x 座標。

戻り値

値を返しません。


直線パスを描画する

  • ≪ ImagickDraw::pathLineToHorizontalRelative
  • ImagickDraw::pathLineToVerticalAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 直線パスを描画する

ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — 直線パスを描画する

説明

public ImagickDraw::pathLineToRelative(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して直線を描画します。 座標は新しい点に移動します。

パラメータ

x

始点の x 座標。

y

始点の y 座標。

戻り値

値を返しません。


垂直直線パスを描画する

  • ≪ ImagickDraw::pathLineToRelative
  • ImagickDraw::pathLineToVerticalRelative ≫
  • PHP Manual
  • ImagickDraw
  • 垂直直線パスを描画する

ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — 垂直直線パスを描画する

説明

public ImagickDraw::pathLineToVerticalAbsolute(float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して垂直直線を描画します。 座標は新しい点に移動します。

パラメータ

y

y 座標。

戻り値

値を返しません。


垂直直線パスを描画する

  • ≪ ImagickDraw::pathLineToVerticalAbsolute
  • ImagickDraw::pathMoveToAbsolute ≫
  • PHP Manual
  • ImagickDraw
  • 垂直直線パスを描画する

ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — 垂直直線パスを描画する

説明

public ImagickDraw::pathLineToVerticalRelative(float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して垂直直線を描画します。 座標は新しい点に移動します。

パラメータ

y

y 座標。

戻り値

値を返しません。


新しいサブパスを開始する

  • ≪ ImagickDraw::pathLineToVerticalRelative
  • ImagickDraw::pathMoveToRelative ≫
  • PHP Manual
  • ImagickDraw
  • 新しいサブパスを開始する

ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — 新しいサブパスを開始する

説明

public ImagickDraw::pathMoveToAbsolute(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

絶対座標で指定した座標から、新しいサブパスを開始します。 現在の点は指定した座標となります。

パラメータ

x

始点の x 座標。

y

始点の y 座標。

戻り値

値を返しません。


新しいサブパスを開始する

  • ≪ ImagickDraw::pathMoveToAbsolute
  • ImagickDraw::pathStart ≫
  • PHP Manual
  • ImagickDraw
  • 新しいサブパスを開始する

ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — 新しいサブパスを開始する

説明

public ImagickDraw::pathMoveToRelative(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

相対座標で指定した座標から、新しいサブパスを開始します。 現在の点は指定した座標となります。

パラメータ

x

始点の x 座標。

y

始点の y 座標。

戻り値

値を返しません。


パス描画リストの開始を宣言する

  • ≪ ImagickDraw::pathMoveToRelative
  • ImagickDraw::point ≫
  • PHP Manual
  • ImagickDraw
  • パス描画リストの開始を宣言する

ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — パス描画リストの開始を宣言する

説明

public ImagickDraw::pathStart(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス描画リストの開始を宣言します。このリストは、対応する DrawPathFinish() コマンドで終了します。 すべての DrawPath コマンドは、このコマンドと DrawPathFinish() コマンドの間にある必要があります。パス描画コマンドは従属コマンドであり、 それ自身だけでは機能しないからです。

戻り値

値を返しません。

例

例1 ImagickDraw::pathStart() の例

<?php
function pathStart($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(72);

$draw->pathStart();
$draw->pathMoveToAbsolute(50, 50);
$draw->pathLineToAbsolute(100, 50);
$draw->pathLineToRelative(0, 50);
$draw->pathLineToHorizontalRelative(-50);
$draw->pathFinish();

$draw->pathStart();
$draw->pathMoveToAbsolute(50, 50);
$draw->pathMoveToRelative(300, 0);
$draw->pathLineToRelative(50, 0);
$draw->pathLineToVerticalRelative(50);
$draw->pathLineToHorizontalAbsolute(350);
$draw->pathclose();
$draw->pathFinish();

$draw->pathStart();
$draw->pathMoveToAbsolute(50, 300);
$draw->pathCurveToAbsolute(50, 300, 100, 200, 300, 300);
$draw->pathLineToVerticalAbsolute(350);
$draw->pathFinish();

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


点を描画する

  • ≪ ImagickDraw::pathStart
  • ImagickDraw::polygon ≫
  • PHP Manual
  • ImagickDraw
  • 点を描画する

ImagickDraw::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — 点を描画する

説明

public ImagickDraw::point(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の描画色と濃度を使用して、 指定した座標に点を描画します。

パラメータ

x

点の x 座標。

y

点の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::point() の例

<?php
function point($fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setFillColor($fillColor);

for ($x = 0; $x < 10000; $x++) {
$draw->point(rand(0, 500), rand(0, 500));
}

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


多角形を描画する

  • ≪ ImagickDraw::point
  • ImagickDraw::polyline ≫
  • PHP Manual
  • ImagickDraw
  • 多角形を描画する

ImagickDraw::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — 多角形を描画する

説明

public ImagickDraw::polygon(array $coordinates): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の線と線幅、そして塗りつぶし色あるいはテクスチャを使用して、 指定した座標配列から多角形を描画します。

パラメータ

coordinates

多次元配列。 array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) ); のような形式となります。

戻り値

成功した場合に true を返します。

例

例1 ImagickDraw::polygon() の例

<?php
function polygon($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setStrokeWidth(4);

$draw->setFillColor($fillColor);

$points = [
['x' => 40 * 5, 'y' => 10 * 5],
['x' => 20 * 5, 'y' => 20 * 5],
['x' => 70 * 5, 'y' => 50 * 5],
['x' => 60 * 5, 'y' => 15 * 5],
];

$draw->polygon($points);

$image = new \Imagick();
$image->newImage(500, 300, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


線分群を描画する

  • ≪ ImagickDraw::polygon
  • ImagickDraw::pop ≫
  • PHP Manual
  • ImagickDraw
  • 線分群を描画する

ImagickDraw::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — 線分群を描画する

説明

public ImagickDraw::polyline(array $coordinates): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の線と線幅、そして塗りつぶし色あるいはテクスチャを使用して、 指定した座標配列から線分群を描画します。

パラメータ

coordinates

x 座標および y 座標の配列。 array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) ) のような形式となります。

戻り値

成功した場合に true を返します。

例

例1 ImagickDraw::polyline() の例

<?php
function polyline($strokeColor, $fillColor, $backgroundColor) {
$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(5);

$points = [
['x' => 40 * 5, 'y' => 10 * 5],
['x' => 20 * 5, 'y' => 20 * 5],
['x' => 70 * 5, 'y' => 50 * 5],
['x' => 60 * 5, 'y' => 15 * 5]
];

$draw->polyline($points);

$image = new \Imagick();
$image->newImage(500, 300, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

  • ≪ ImagickDraw::polyline
  • ImagickDraw::popClipPath ≫
  • PHP Manual
  • ImagickDraw
  • スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

ImagickDraw::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

説明

public ImagickDraw::pop(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返します。 複数の ImagickDraw が存在する可能性もあります。 push された回数より多くの ImagickDraw の pop を試みるとエラーとなります。 また、ImagickDrow が push されたときと同じ方式で pop する必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。


クリップパスの定義を終了する

  • ≪ ImagickDraw::pop
  • ImagickDraw::popDefs ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの定義を終了する

ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — クリップパスの定義を終了する

説明

public ImagickDraw::popClipPath(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの定義を終了します。

戻り値

値を返しません。


定義リストを終了する

  • ≪ ImagickDraw::popClipPath
  • ImagickDraw::popPattern ≫
  • PHP Manual
  • ImagickDraw
  • 定義リストを終了する

ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — 定義リストを終了する

説明

public ImagickDraw::popDefs(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

定義リストを終了します。

戻り値

値を返しません。

例

例1 ImagickDraw::popDefs() の例

<?php
function popDefs($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setstrokeOpacity(1);
$draw->setStrokeWidth(2);
$draw->setFontSize(72);
$draw->pushDefs();
$draw->setStrokeColor('white');
$draw->rectangle(50, 50, 200, 200);
$draw->popDefs();

$draw->rectangle(300, 50, 450, 200);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


パターン定義を終了する

  • ≪ ImagickDraw::popDefs
  • ImagickDraw::push ≫
  • PHP Manual
  • ImagickDraw
  • パターン定義を終了する

ImagickDraw::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — パターン定義を終了する

説明

public ImagickDraw::popPattern(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パターン定義を終了します。

戻り値

成功した場合に true を、失敗した場合に false を返します。


現在の ImagickDraw をコピーしてスタックに格納する

  • ≪ ImagickDraw::popPattern
  • ImagickDraw::pushClipPath ≫
  • PHP Manual
  • ImagickDraw
  • 現在の ImagickDraw をコピーしてスタックに格納する

ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — 現在の ImagickDraw をコピーしてスタックに格納する

説明

public ImagickDraw::push(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の ImagickDraw をコピーして新しい ImagickDraw を作成し、 それを ImagickDraw スタックに格納します。格納した ImagickDraw は ImagickDraw::pop() で取り出すことができます。ImagickDraw は ImagickDraw スタックに保存されます。Pop を行うには、事前に Push が行われている必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ImagickDraw::push() の例

<?php
function push($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillModifiedColor);
$draw->setStrokeWidth(2);
$draw->setFontSize(72);
$draw->push();
$draw->translate(50, 50);
$draw->rectangle(200, 200, 300, 300);
$draw->pop();
$draw->setFillColor($fillColor);
$draw->rectangle(200, 200, 300, 300);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


クリップパスの定義を開始する

  • ≪ ImagickDraw::push
  • ImagickDraw::pushDefs ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの定義を開始する

ImagickDraw::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — クリップパスの定義を開始する

説明

public ImagickDraw::pushClipPath(string $clip_mask_id): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの定義を開始します。 これは、任意の数の描画コマンドで構成され、最後は ImagickDraw::popClipPath() コマンドとなります。

パラメータ

clip_mask_id

クリップマスク ID。

戻り値

値を返しません。


後に続くコマンドが、処理の前に名前つき要素を作成することを示す

  • ≪ ImagickDraw::pushClipPath
  • ImagickDraw::pushPattern ≫
  • PHP Manual
  • ImagickDraw
  • 後に続くコマンドが、処理の前に名前つき要素を作成することを示す

ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — 後に続くコマンドが、処理の前に名前つき要素を作成することを示す

説明

public ImagickDraw::pushDefs(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

後に続く ImagickDraw::popDefs() までのコマンドが、 名前つき要素 (クリップパスやテクスチャなど) を作成することを示します。 これは、効率を考慮して事前に処理されます。

戻り値

値を返しません。


後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

  • ≪ ImagickDraw::pushDefs
  • ImagickDraw::rectangle ≫
  • PHP Manual
  • ImagickDraw
  • 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

説明

public ImagickDraw::pushPattern(
string $pattern_id,
float $x,
float $y,
float $width,
float $height
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

後に続く DrawPopPattern() までのコマンドが、 名前付きパターンを構成することを示します。 パターン空間は、左上の座標と幅、高さで指定します。 そして独自の描画空間となります。 描画される内容は、すべてこのパターン定義を使用します。 名前付きパターンは、線やブラシの定義で使用することができます。

パラメータ

pattern_id

パターン ID。

x

左上の角の x 座標。

y

左上の角の y 座標。

width

パターンの幅。

height

パターンの高さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ImagickDraw::pushPattern() の例

<?php
function pushPattern($strokeColor, $fillColor, $backgroundColor) {
$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(1);
$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(1);

$draw->pushPattern("MyFirstPattern", 0, 0, 50, 50);
for ($x = 0; $x < 50; $x += 10) {
for ($y = 0; $y < 50; $y += 5) {
$positionX = $x + (($y / 5) % 5);
$draw->rectangle($positionX, $y, $positionX + 5, $y + 5);
}
}
$draw->popPattern();

$draw->setFillOpacity(0);
$draw->rectangle(100, 100, 400, 400);
$draw->setFillOpacity(1);

$draw->setFillOpacity(1);

$draw->push();
$draw->setFillPatternURL('#MyFirstPattern');
$draw->setFillColor('yellow');
$draw->rectangle(100, 100, 400, 400);
$draw->pop();

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


矩形を描画する

  • ≪ ImagickDraw::pushPattern
  • ImagickDraw::render ≫
  • PHP Manual
  • ImagickDraw
  • 矩形を描画する

ImagickDraw::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — 矩形を描画する

説明

public ImagickDraw::rectangle(
float $x1,
float $y1,
float $x2,
float $y2
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

2 つの座標を与え、現在の枠線や線幅、塗りつぶしの設定を使用して矩形を描画します。

パラメータ

x1

左上の角の x 座標。

y1

左上の角の y 座標。

x2

右下の角の x 座標。

y2

右下の角の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::rectangle() の例

<?php
function rectangle($strokeColor, $fillColor, $backgroundColor) {
$draw = new \ImagickDraw();
$strokeColor = new \ImagickPixel($strokeColor);
$fillColor = new \ImagickPixel($fillColor);

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);

$draw->rectangle(200, 200, 300, 300);
$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


これまでのすべての描画コマンドを画像上にレンダリングする

  • ≪ ImagickDraw::rectangle
  • ImagickDraw::resetVectorGraphics ≫
  • PHP Manual
  • ImagickDraw
  • これまでのすべての描画コマンドを画像上にレンダリングする

ImagickDraw::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — これまでのすべての描画コマンドを画像上にレンダリングする

説明

public ImagickDraw::render(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

これまでのすべての描画コマンドを画像上にレンダリングします。

戻り値

成功した場合に true を、失敗した場合に false を返します。


Resets the vector graphics

  • ≪ ImagickDraw::render
  • ImagickDraw::rotate ≫
  • PHP Manual
  • ImagickDraw
  • Resets the vector graphics

ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Resets the vector graphics

説明

public ImagickDraw::resetVectorGraphics(): bool

Resets the vector graphics.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を返します。


指定した回転を現在の座標空間に適用する

  • ≪ ImagickDraw::resetVectorGraphics
  • ImagickDraw::roundRectangle ≫
  • PHP Manual
  • ImagickDraw
  • 指定した回転を現在の座標空間に適用する

ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — 指定した回転を現在の座標空間に適用する

説明

public ImagickDraw::rotate(float $degrees): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した回転を現在の座標空間に適用します。

パラメータ

degrees

回転角度。

戻り値

値を返しません。

例

例1 ImagickDraw::rotate() の例

<?php
function rotate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {
$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setStrokeOpacity(1);
$draw->setFillColor($fillColor);
$draw->rectangle(200, 200, 300, 300);
$draw->setFillColor($fillModifiedColor);
$draw->rotate(15);
$draw->rectangle(200, 200, 300, 300);

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


角が丸い矩形を描画する

  • ≪ ImagickDraw::rotate
  • ImagickDraw::scale ≫
  • PHP Manual
  • ImagickDraw
  • 角が丸い矩形を描画する

ImagickDraw::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — 角が丸い矩形を描画する

説明

public ImagickDraw::roundRectangle(
float $x1,
float $y1,
float $x2,
float $y2,
float $rx,
float $ry
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

2 つの座標、そして角の x & y 方向の丸めを与え、 現在の枠線や線幅、塗りつぶしの設定を使用して角が丸い矩形を描画します。

パラメータ

x1

左上の角の x 座標。

y1

左上の角の y 座標。

x2

右下の角の x 座標。

y2

右下の角の y 座標。

rx

x 方向の丸め。

ry

y 方向の丸め。

戻り値

値を返しません。

例

例1 ImagickDraw::roundRectangle() の例

<?php
function roundRectangle($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $roundX, $roundY) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);

$draw->roundRectangle($startX, $startY, $endX, $endY, $roundX, $roundY);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


倍率を調整する

  • ≪ ImagickDraw::roundRectangle
  • ImagickDraw::setClipPath ≫
  • PHP Manual
  • ImagickDraw
  • 倍率を調整する

ImagickDraw::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — 倍率を調整する

説明

public ImagickDraw::scale(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標空間における、 水平方向および垂直方向の拡大率を調整します。

パラメータ

x

水平方向の拡大率。

y

垂直方向の拡大率。

戻り値

値を返しません。

例

例1 ImagickDraw::scale() の例

<?php
function scale($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setStrokeWidth(4);
$draw->setFillColor($fillColor);
$draw->rectangle(200, 200, 300, 300);
$draw->setFillColor($fillModifiedColor);
$draw->scale(1.4, 1.4);
$draw->rectangle(200, 200, 300, 300);

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


指定した名前のクリッピングパスを画像に関連付ける

  • ≪ ImagickDraw::scale
  • ImagickDraw::setClipRule ≫
  • PHP Manual
  • ImagickDraw
  • 指定した名前のクリッピングパスを画像に関連付ける

ImagickDraw::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — 指定した名前のクリッピングパスを画像に関連付ける

説明

public ImagickDraw::setClipPath(string $clip_mask): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した名前のクリッピングパスを画像に関連付けます。 クリッピングパスの範囲内に描画された内容だけが反映されます。

パラメータ

clip_mask

クリッピングパスの名前。

戻り値

値を返しません。

例

例1 ImagickDraw::setClipPath() の例

<?php
function setClipPath($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);

$clipPathName = 'testClipPath';

$draw->pushClipPath($clipPathName);
$draw->rectangle(0, 0, 250, 250);
$draw->popClipPath();
$draw->setClipPath($clipPathName);
$draw->rectangle(100, 100, 400, 400);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


クリッピングパスで使用する多角形塗りつぶしルールを設定する

  • ≪ ImagickDraw::setClipPath
  • ImagickDraw::setClipUnits ≫
  • PHP Manual
  • ImagickDraw
  • クリッピングパスで使用する多角形塗りつぶしルールを設定する

ImagickDraw::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — クリッピングパスで使用する多角形塗りつぶしルールを設定する

説明

public ImagickDraw::setClipRule(int $fill_rule): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリッピングパスで使用する多角形塗りつぶしルールを設定します。

パラメータ

fill_rule

FILLRULE 定数 (imagick::FILLRULE_*) のうちいずれか

戻り値

値を返しません。

例

例1 ImagickDraw::setClipRule() の例

<?php
function setClipRule($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);
//\Imagick::FILLRULE_EVENODD
//\Imagick::FILLRULE_NONZERO

$clipPathName = 'testClipPath';
$draw->pushClipPath($clipPathName);
$draw->setClipRule(\Imagick::FILLRULE_EVENODD);
$draw->rectangle(0, 0, 300, 500);
$draw->rectangle(200, 0, 500, 500);
$draw->popClipPath();
$draw->setClipPath($clipPathName);
$draw->rectangle(200, 200, 300, 300);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


クリップパスの単位の解釈を設定する

  • ≪ ImagickDraw::setClipRule
  • ImagickDraw::setFillAlpha ≫
  • PHP Manual
  • ImagickDraw
  • クリップパスの単位の解釈を設定する

ImagickDraw::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — クリップパスの単位の解釈を設定する

説明

public ImagickDraw::setClipUnits(int $clip_units): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの単位の解釈を設定します。

パラメータ

clip_units

クリップ単位の数。

戻り値

値を返しません。

例

例1 ImagickDraw::setClipUnits() の例

<?php
function setClipUnits($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);
$clipPathName = 'testClipPath';
$draw->setClipUnits(\Imagick::RESOLUTION_PIXELSPERINCH);
$draw->pushClipPath($clipPathName);
$draw->rectangle(0, 0, 250, 250);
$draw->popClipPath();
$draw->setClipPath($clipPathName);

//RESOLUTION_PIXELSPERINCH
//RESOLUTION_PIXELSPERCENTIMETER

$draw->rectangle(200, 200, 300, 300);
$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


色やテクスチャによる塗りつぶしの際の透過度を設定する

  • ≪ ImagickDraw::setClipUnits
  • ImagickDraw::setFillColor ≫
  • PHP Manual
  • ImagickDraw
  • 色やテクスチャによる塗りつぶしの際の透過度を設定する

ImagickDraw::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — 色やテクスチャによる塗りつぶしの際の透過度を設定する

説明

public ImagickDraw::setFillAlpha(float $opacity): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を設定します。 完全に不透明な状態が 1.0 となります。

パラメータ

opacity

塗りつぶしのアルファ値。

戻り値

値を返しません。

例

例1 ImagickDraw::setFillAlpha() の例

<?php
function setFillAlpha($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);
$draw->rectangle(100, 200, 200, 300);
@$draw->setFillAlpha(0.4);
$draw->rectangle(300, 200, 400, 300);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


オブジェクトの塗りつぶしに使用する色を設定する

  • ≪ ImagickDraw::setFillAlpha
  • ImagickDraw::setFillOpacity ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの塗りつぶしに使用する色を設定する

ImagickDraw::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — オブジェクトの塗りつぶしに使用する色を設定する

説明

public ImagickDraw::setFillColor(ImagickPixel $fill_pixel): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの塗りつぶしに使用する色を設定します。

パラメータ

fill_pixel

色を表す ImagickPixel。

戻り値

値を返しません。

例

例1 ImagickDraw::setFillColor()

<?php
function setFillColor($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(1.5);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->rectangle(50, 50, 150, 150);

$draw->setFillColor("rgb(200, 32, 32)");
$draw->rectangle(200, 50, 300, 150);

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


色やテクスチャによる塗りつぶしの際の透過度を設定する

  • ≪ ImagickDraw::setFillColor
  • ImagickDraw::setFillPatternURL ≫
  • PHP Manual
  • ImagickDraw
  • 色やテクスチャによる塗りつぶしの際の透過度を設定する

ImagickDraw::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — 色やテクスチャによる塗りつぶしの際の透過度を設定する

説明

public ImagickDraw::setFillOpacity(float $fillOpacity): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を設定します。 完全に不透明な状態が 1.0 となります。

パラメータ

fillOpacity

塗りつぶしの透明度。

戻り値

値を返しません。

例

例1 ImagickDraw::setFillOpacity()

<?php
function setFillOpacity($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeOpacity(1);
$draw->setStrokeWidth(2);

$draw->rectangle(100, 200, 200, 300);

$draw->setFillOpacity(0.4);
$draw->rectangle(300, 200, 400, 300);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


オブジェクトの塗りつぶしパターンとして使用する URL を設定する

  • ≪ ImagickDraw::setFillOpacity
  • ImagickDraw::setFillRule ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの塗りつぶしパターンとして使用する URL を設定する

ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — オブジェクトの塗りつぶしパターンとして使用する URL を設定する

説明

public ImagickDraw::setFillPatternURL(string $fill_url): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの塗りつぶしパターンとして使用する URL を設定します。 現時点でサポートしているのは、ローカル URL ("#identifier") のみです。 このローカル URL は、DrawPushPattern/DrawPopPattern で塗りつぶしパターンを定義することによって作成されます。

パラメータ

fill_url

塗りつぶしパターンを取得する URL。

戻り値

成功した場合に true を、失敗した場合に false を返します。


多角形の描画時に使用する塗りつぶしルールを設定する

  • ≪ ImagickDraw::setFillPatternURL
  • ImagickDraw::setFont ≫
  • PHP Manual
  • ImagickDraw
  • 多角形の描画時に使用する塗りつぶしルールを設定する

ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — 多角形の描画時に使用する塗りつぶしルールを設定する

説明

public ImagickDraw::setFillRule(int $fill_rule): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

多角形の描画時に使用する塗りつぶしルールを設定します。

パラメータ

fill_rule

FILLRULE 定数 (imagick::FILLRULE_*) のうちのいずれか。

戻り値

値を返しません。

例

例1 ImagickDraw::setFillRule() の例

<?php
function setFillRule($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeWidth(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$fillRules = [\Imagick::FILLRULE_NONZERO, \Imagick::FILLRULE_EVENODD];

$points = 11;
$size = 150;

$draw->translate(175, 160);

for ($x = 0; $x < 2; $x++) {
$draw->setFillRule($fillRules[$x]);
$draw->pathStart();
for ($n = 0; $n < $points * 2; $n++) {

if ($n >= $points) {
$angle = fmod($n * 360 * 4 / $points, 360) * pi() / 180;
}
else {
$angle = fmod($n * 360 * 3 / $points, 360) * pi() / 180;
}

$positionX = $size * sin($angle);
$positionY = $size * cos($angle);

if ($n == 0) {
$draw->pathMoveToAbsolute($positionX, $positionY);
}
else {
$draw->pathLineToAbsolute($positionX, $positionY);
}
}

$draw->pathClose();
$draw->pathFinish();

$draw->translate(325, 0);
}

$image = new \Imagick();
$image->newImage(700, 320, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


テキストによる注記を行う際に使用するフォントを設定する

  • ≪ ImagickDraw::setFillRule
  • ImagickDraw::setFontFamily ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントを設定する

ImagickDraw::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — テキストによる注記を行う際に使用するフォントを設定する

説明

public ImagickDraw::setFont(string $font_name): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントを設定します。

パラメータ

font_name

戻り値

成功した場合に true を返します。

例

例1 ImagickDraw::setFont() の例

<?php
function setFont($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);
$draw->setFontSize(36);

$draw->setFont("../fonts/Arial.ttf");
$draw->annotation(50, 50, "Lorem Ipsum!");

$draw->setFont("../fonts/Consolas.ttf");
$draw->annotation(50, 100, "Lorem Ipsum!");

$draw->setFont("../fonts/CANDY.TTF");
$draw->annotation(50, 150, "Lorem Ipsum!");

$draw->setFont("../fonts/Inconsolata-dz.otf");
$draw->annotation(50, 200, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(500, 300, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストによる注記を行う際に使用するフォントファミリーを設定する

  • ≪ ImagickDraw::setFont
  • ImagickDraw::setFontSize ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントファミリーを設定する

ImagickDraw::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — テキストによる注記を行う際に使用するフォントファミリーを設定する

説明

public ImagickDraw::setFontFamily(string $font_family): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントファミリーを設定します。

パラメータ

font_family

フォントファミリー。

戻り値

成功した場合に true を返します。

例

例1 ImagickDraw::setFontFamily() の例

<?php
function setFontFamily($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();

$strokeColor = new \ImagickPixel($strokeColor);
$fillColor = new \ImagickPixel($fillColor);

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(2);

$draw->setFontSize(48);

$draw->setFontFamily("Times");
$draw->annotation(50, 50, "Lorem Ipsum!");

$draw->setFontFamily("AvantGarde");
$draw->annotation(50, 100, "Lorem Ipsum!");

$draw->setFontFamily("NewCenturySchlbk");
$draw->annotation(50, 150, "Lorem Ipsum!");

$draw->setFontFamily("Palatino");
$draw->annotation(50, 200, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(450, 250, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストによる注記を行う際に使用するフォントのポイント数を設定する

  • ≪ ImagickDraw::setFontFamily
  • ImagickDraw::setFontStretch ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントのポイント数を設定する

ImagickDraw::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — テキストによる注記を行う際に使用するフォントのポイント数を設定する

説明

public ImagickDraw::setFontSize(float $pointsize): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのポイント数を設定します。

パラメータ

pointsize

ポイント数。

戻り値

値を返しません。

例

例1 ImagickDraw::setFontSize() の例

<?php
function setFontSize($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeOpacity(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(2);
$draw->setFont("../fonts/Arial.ttf");

$sizes = [24, 36, 48, 60, 72];

foreach ($sizes as $size) {
$draw->setFontSize($size);
$draw->annotation(50, ($size * $size / 16), "Lorem Ipsum!");
}

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストによる注記を行う際に使用するフォントの伸縮を設定する

  • ≪ ImagickDraw::setFontSize
  • ImagickDraw::setFontStyle ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントの伸縮を設定する

ImagickDraw::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — テキストによる注記を行う際に使用するフォントの伸縮を設定する

説明

public ImagickDraw::setFontStretch(int $fontStretch): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの伸縮を設定します。 AnyStretch は、ワイルドカードの "don't care" オプションとして働きます。

パラメータ

fontStretch

STRETCH 定数 (imagick::STRETCH_*) のうちのいずれか。

戻り値

値を返しません。

例

例1 ImagickDraw::setFontStretch() の例

<?php
function setFontStretch($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(2);
$draw->setFontSize(36);

$fontStretchTypes = [
\Imagick::STRETCH_ULTRACONDENSED,
\Imagick::STRETCH_CONDENSED,
\Imagick::STRETCH_SEMICONDENSED,
\Imagick::STRETCH_SEMIEXPANDED,
\Imagick::STRETCH_EXPANDED,
\Imagick::STRETCH_EXTRAEXPANDED,
\Imagick::STRETCH_ULTRAEXPANDED,
\Imagick::STRETCH_ANY
];

$offset = 0;
foreach ($fontStretchTypes as $fontStretch) {
$draw->setFontStretch($fontStretch);
$draw->annotation(50, 75 + $offset, "Lorem Ipsum!");
$offset += 50;
}

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストによる注記を行う際に使用するフォントのスタイルを設定する

  • ≪ ImagickDraw::setFontStretch
  • ImagickDraw::setFontWeight ≫
  • PHP Manual
  • ImagickDraw
  • テキストによる注記を行う際に使用するフォントのスタイルを設定する

ImagickDraw::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — テキストによる注記を行う際に使用するフォントのスタイルを設定する

説明

public ImagickDraw::setFontStyle(int $style): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのスタイルを設定します。 AnyStyle は、ワイルドカードの "don't care" オプションとして働きます。

パラメータ

style

STYLE 定数 (imagick::STYLE_*) のうちのいずれか。

戻り値

値を返しません。

例

例1 ImagickDraw::setFontStyle() の例

<?php
function setFontStyle($fillColor, $strokeColor, $backgroundColor) {
$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(1);
$draw->setFontSize(36);
$draw->setFontStyle(\Imagick::STYLE_NORMAL);
$draw->annotation(50, 50, "Lorem Ipsum!");

$draw->setFontStyle(\Imagick::STYLE_ITALIC);
$draw->annotation(50, 100, "Lorem Ipsum!");

$draw->setFontStyle(\Imagick::STYLE_OBLIQUE);
$draw->annotation(50, 150, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(350, 300, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


フォントの重さを設定する

  • ≪ ImagickDraw::setFontStyle
  • ImagickDraw::setGravity ≫
  • PHP Manual
  • ImagickDraw
  • フォントの重さを設定する

ImagickDraw::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — フォントの重さを設定する

説明

public ImagickDraw::setFontWeight(int $font_weight): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの重さを設定します。

パラメータ

font_weight

戻り値

例

例1 ImagickDraw::setFontWeight() の例

<?php
function setFontWeight($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(1);

$draw->setFontSize(36);

$draw->setFontWeight(100);
$draw->annotation(50, 50, "Lorem Ipsum!");

$draw->setFontWeight(200);
$draw->annotation(50, 100, "Lorem Ipsum!");

$draw->setFontWeight(400);
$draw->annotation(50, 150, "Lorem Ipsum!");

$draw->setFontWeight(800);
$draw->annotation(50, 200, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストの配置時の gravity を設定する

  • ≪ ImagickDraw::setFontWeight
  • ImagickDraw::setResolution ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置時の gravity を設定する

ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — テキストの配置時の gravity を設定する

説明

public ImagickDraw::setGravity(int $gravity): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するテキスト配置の gravity を設定します。

パラメータ

gravity

GRAVITY 定数 (imagick::GRAVITY_*) のうちのいずれか

戻り値

値を返しません。

例

例1 ImagickDraw::setGravity() の例

<?php
function setGravity($fillColor, $strokeColor, $backgroundColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(1);
$draw->setFontSize(24);

$gravitySettings = array(
\Imagick::GRAVITY_NORTHWEST => 'NorthWest',
\Imagick::GRAVITY_NORTH => 'North',
\Imagick::GRAVITY_NORTHEAST => 'NorthEast',
\Imagick::GRAVITY_WEST => 'West',
\Imagick::GRAVITY_CENTER => 'Centre',
\Imagick::GRAVITY_SOUTHWEST => 'SouthWest',
\Imagick::GRAVITY_SOUTH => 'South',
\Imagick::GRAVITY_SOUTHEAST => 'SouthEast',
\Imagick::GRAVITY_EAST => 'East'
);

$draw->setFont("../fonts/Arial.ttf");

foreach ($gravitySettings as $type => $description) {
$draw->setGravity($type);
$draw->annotation(50, 50, '"' . $description . '"');
}

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


Sets the resolution

  • ≪ ImagickDraw::setGravity
  • ImagickDraw::setStrokeAlpha ≫
  • PHP Manual
  • ImagickDraw
  • Sets the resolution

ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — Sets the resolution

説明

public ImagickDraw::setResolution(float $x_resolution, float $y_resolution): bool

Sets the resolution.

パラメータ

x_resolution

y_resolution

戻り値

成功した場合に true を返します。


オブジェクトの枠線の透明度を指定する

  • ≪ ImagickDraw::setResolution
  • ImagickDraw::setStrokeAntialias ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の透明度を指定する

ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — オブジェクトの枠線の透明度を指定する

説明

public ImagickDraw::setStrokeAlpha(float $opacity): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を指定します。

パラメータ

opacity

透明度。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeAlpha() の例

<?php
function setStrokeAlpha($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(4);
$draw->line(100, 100, 400, 145);
$draw->rectangle(100, 200, 225, 350);
$draw->setStrokeOpacity(0.1);
$draw->line(100, 120, 400, 165);
$draw->rectangle(275, 200, 400, 350);

$image = new \Imagick();
$image->newImage(500, 400, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


縁取りの枠線をアンチエイリアス処理するかどうかを制御する

  • ≪ ImagickDraw::setStrokeAlpha
  • ImagickDraw::setStrokeColor ≫
  • PHP Manual
  • ImagickDraw
  • 縁取りの枠線をアンチエイリアス処理するかどうかを制御する

ImagickDraw::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — 縁取りの枠線をアンチエイリアス処理するかどうかを制御する

説明

public ImagickDraw::setStrokeAntialias(bool $stroke_antialias): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

縁取りの枠線をアンチエイリアス処理するかどうかを制御します。 縁取りの枠線は、デフォルトでアンチエイリアス処理が行われます。 アンチエイリアスを無効にすると、 縁取りの描画時には縁取り色あるいはキャンバスの色のどちらかが用いられることになります。

パラメータ

stroke_antialias

アンチエイリアス設定。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeAntialias() の例

<?php
function setStrokeAntialias($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(1);
$draw->setStrokeAntialias(false);
$draw->line(100, 100, 400, 105);

$draw->line(100, 140, 400, 185);

$draw->setStrokeAntialias(true);
$draw->line(100, 110, 400, 115);
$draw->line(100, 150, 400, 195);

$image = new \Imagick();
$image->newImage(500, 250, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


オブジェクトの縁取りに使用する色を設定する

  • ≪ ImagickDraw::setStrokeAntialias
  • ImagickDraw::setStrokeDashArray ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの縁取りに使用する色を設定する

ImagickDraw::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — オブジェクトの縁取りに使用する色を設定する

説明

public ImagickDraw::setStrokeColor(ImagickPixel $stroke_pixel): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの縁取りに使用する色を設定します。

パラメータ

stroke_pixel

縁取り色。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeColor() の例

<?php
function setStrokeColor($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(5);

$draw->line(100, 100, 400, 145);
$draw->rectangle(100, 200, 225, 350);

$draw->setStrokeOpacity(0.1);
$draw->line(100, 120, 400, 165);
$draw->rectangle(275, 200, 400, 350);

$image = new \Imagick();
$image->newImage(500, 400, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


パスの描画に使用する破線のパターンを指定する

  • ≪ ImagickDraw::setStrokeColor
  • ImagickDraw::setStrokeDashOffset ≫
  • PHP Manual
  • ImagickDraw
  • パスの描画に使用する破線のパターンを指定する

ImagickDraw::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — パスの描画に使用する破線のパターンを指定する

説明

public ImagickDraw::setStrokeDashArray(array $dashArray): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パスの描画に使用する破線のパターンを指定します。 strokeDashArray は数値の配列で、 互い違いに並べる破線と空白の長さをピクセルで表したものです。 If an odd number of values is provided, then the list of values is repeated to yield an even number of values. 既存の配列を削除するには、number_elements にゼロ、そして dash_array に null を渡します。 典型的な strokeDashArray_ 配列のメンバーは 5 3 2 となります。

パラメータ

dashArray

float の配列。

戻り値

成功した場合に true を返します。

例

例1 ImagickDraw::setStrokeDashArray() の例

<?php
function setStrokeDashArray($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(4);

$draw->setStrokeDashArray([10, 10]);
$draw->rectangle(100, 50, 225, 175);

$draw->setStrokeDashArray([20, 5, 20, 5, 5, 5,]);
$draw->rectangle(275, 50, 400, 175);

$draw->setStrokeDashArray([20, 5, 20, 5, 5]);
$draw->rectangle(100, 200, 225, 350);

$draw->setStrokeDashArray([1, 1, 1, 1, 2, 2, 3, 3, 5, 5, 8, 8, 13, 13, 21, 21, 34, 34, 55, 55, 89, 89, 144, 144, 233, 233, 377, 377, 610, 610, 987, 987, 1597, 1597, 2584, 2584, 4181, 4181,]);

$draw->rectangle(275, 200, 400, 350);

$image = new \Imagick();
$image->newImage(500, 400, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


破線パターンにおける破線の開始オフセットを指定する

  • ≪ ImagickDraw::setStrokeDashArray
  • ImagickDraw::setStrokeLineCap ≫
  • PHP Manual
  • ImagickDraw
  • 破線パターンにおける破線の開始オフセットを指定する

ImagickDraw::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — 破線パターンにおける破線の開始オフセットを指定する

説明

public ImagickDraw::setStrokeDashOffset(float $dash_offset): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

破線パターンにおける破線の開始オフセットを指定します。

パラメータ

dash_offset

破線のオフセット。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeDashOffset() の例

<?php
function setStrokeDashOffset($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(4);
$draw->setStrokeDashArray([20, 20]);
$draw->setStrokeDashOffset(0);
$draw->rectangle(100, 50, 225, 175);

//Start the dash effect halfway through the solid portion
$draw->setStrokeDashOffset(10);
$draw->rectangle(275, 50, 400, 175);

//Start the dash effect on the space portion
$draw->setStrokeDashOffset(20);
$draw->rectangle(100, 200, 225, 350);
$draw->setStrokeDashOffset(5);
$draw->rectangle(275, 200, 400, 350);

$image = new \Imagick();
$image->newImage(500, 400, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


開かれたサブパスを描画する際に使用する端点の形状を指定する

  • ≪ ImagickDraw::setStrokeDashOffset
  • ImagickDraw::setStrokeLineJoin ≫
  • PHP Manual
  • ImagickDraw
  • 開かれたサブパスを描画する際に使用する端点の形状を指定する

ImagickDraw::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を指定する

説明

public ImagickDraw::setStrokeLineCap(int $linecap): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

開かれたサブパスを描画する際に使用する端点の形状を指定します。

パラメータ

linecap

LINECAP 定数 (imagick::LINECAP_*) のうちのいずれか

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeLineCap() の例

<?php
function setStrokeLineCap($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(25);

$lineTypes = [\Imagick::LINECAP_BUTT, \Imagick::LINECAP_ROUND, \Imagick::LINECAP_SQUARE,];

$offset = 0;

foreach ($lineTypes as $lineType) {
$draw->setStrokeLineCap($lineType);
$draw->line(50 + $offset, 50, 50 + $offset, 250);
$offset += 50;
}

$imagick = new \Imagick();
$imagick->newImage(300, 300, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


パスの角を描画する際に使用する形状を指定する

  • ≪ ImagickDraw::setStrokeLineCap
  • ImagickDraw::setStrokeMiterLimit ≫
  • PHP Manual
  • ImagickDraw
  • パスの角を描画する際に使用する形状を指定する

ImagickDraw::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — パスの角を描画する際に使用する形状を指定する

説明

public ImagickDraw::setStrokeLineJoin(int $linejoin): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス (あるいはその他のベクター図形) の角を描画する際に使用する形状を指定します。

パラメータ

linejoin

LINEJOIN 定数 (imagick::LINEJOIN_*) のうちのいずれか

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeLineJoin() の例

<?php
function setStrokeLineJoin($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();
$draw->setStrokeWidth(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);

$draw->setStrokeWidth(20);

$offset = 220;

$lineJoinStyle = [
\Imagick::LINEJOIN_MITER,
\Imagick::LINEJOIN_ROUND,
\Imagick::LINEJOIN_BEVEL,
];

for ($x = 0; $x < count($lineJoinStyle); $x++) {
$draw->setStrokeLineJoin($lineJoinStyle[$x]);
$points = [
['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
['x' => 20 * 5, 'y' => 20 * 5 + $x * $offset],
['x' => 70 * 5, 'y' => 50 * 5 + $x * $offset],
['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
];

$draw->polyline($points);
}

$image = new \Imagick();
$image->newImage(500, 700, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


マイターリミットを指定する

  • ≪ ImagickDraw::setStrokeLineJoin
  • ImagickDraw::setStrokeOpacity ≫
  • PHP Manual
  • ImagickDraw
  • マイターリミットを指定する

ImagickDraw::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — マイターリミットを指定する

説明

public ImagickDraw::setStrokeMiterLimit(int $miterlimit): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

マイターリミットを指定します。 2 本の直線が小さい角度で連結され、かつ連結方法が 'lineJoin' に設定されている場合、 出来上がる線の角の部分が非常に長くなります。マイターリミットは、miter length (角の長さ) と 'lineWidth' の比率の最大値です。

パラメータ

miterlimit

マイターリミット。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeMiterLimit() の例

<?php
function setStrokeMiterLimit($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setStrokeOpacity(0.6);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(10);

$yOffset = 100;

$draw->setStrokeLineJoin(\Imagick::LINEJOIN_MITER);

for ($y = 0; $y < 3; $y++) {

$draw->setStrokeMiterLimit(40 * $y);

$points = [
['x' => 22 * 3, 'y' => 15 * 4 + $y * $yOffset],
['x' => 20 * 3, 'y' => 20 * 4 + $y * $yOffset],
['x' => 70 * 5, 'y' => 45 * 4 + $y * $yOffset],
];

$draw->polygon($points);
}

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

$image->setImageType(\Imagick::IMGTYPE_PALETTE);
$image->setImageCompressionQuality(100);
$image->stripImage();

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


オブジェクトの枠線の透明度を指定する

  • ≪ ImagickDraw::setStrokeMiterLimit
  • ImagickDraw::setStrokePatternURL ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の透明度を指定する

ImagickDraw::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — オブジェクトの枠線の透明度を指定する

説明

public ImagickDraw::setStrokeOpacity(float $stroke_opacity): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を指定します。

パラメータ

stroke_opacity

枠線の透明度。1.0 は完全に不透明な状態です。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeOpacity() の例

<?php
function setStrokeOpacity($strokeColor, $fillColor, $backgroundColor) {
$draw = new \ImagickDraw();

$draw->setStrokeWidth(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(10);
$draw->setStrokeOpacity(1);
$draw->line(100, 80, 400, 125);
$draw->rectangle(25, 200, 150, 350);
$draw->setStrokeOpacity(0.5);
$draw->line(100, 100, 400, 145);
$draw->rectangle(200, 200, 325, 350);
$draw->setStrokeOpacity(0.2);
$draw->line(100, 120, 400, 165);
$draw->rectangle(375, 200, 500, 350);

$image = new \Imagick();
$image->newImage(550, 400, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


オブジェクトの枠線の描画に使用するパターンを設定する

  • ≪ ImagickDraw::setStrokeOpacity
  • ImagickDraw::setStrokeWidth ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の描画に使用するパターンを設定する

ImagickDraw::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — オブジェクトの枠線の描画に使用するパターンを設定する

説明

public ImagickDraw::setStrokePatternURL(string $stroke_url): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用するパターンを設定します。

パラメータ

stroke_url

URL。

戻り値

成功した場合に true を返します。


オブジェクトの枠線の描画に使用する線の幅を設定する

  • ≪ ImagickDraw::setStrokePatternURL
  • ImagickDraw::setTextAlignment ≫
  • PHP Manual
  • ImagickDraw
  • オブジェクトの枠線の描画に使用する線の幅を設定する

ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を設定する

説明

public ImagickDraw::setStrokeWidth(float $stroke_width): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用する線の幅を設定します。

パラメータ

stroke_width

線の幅。

戻り値

値を返しません。

例

例1 ImagickDraw::setStrokeWidth() の例

<?php
function setStrokeWidth($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeWidth(1);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->line(100, 100, 400, 145);
$draw->rectangle(100, 200, 225, 350);
$draw->setStrokeWidth(5);
$draw->line(100, 120, 400, 165);
$draw->rectangle(275, 200, 400, 350);

$image = new \Imagick();
$image->newImage(500, 400, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


テキストの配置を指定する

  • ≪ ImagickDraw::setStrokeWidth
  • ImagickDraw::setTextAntialias ≫
  • PHP Manual
  • ImagickDraw
  • テキストの配置を指定する

ImagickDraw::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — テキストの配置を指定する

説明

public ImagickDraw::setTextAlignment(int $alignment): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際の配置を指定します。

パラメータ

alignment

ALIGN 定数 (imagick::ALIGN_*) のうちのいずれか

戻り値

値を返しません。

例

例1 ImagickDraw::setTextAlignment() の例

<?php
function setTextAlignment($strokeColor, $fillColor, $backgroundColor) {
$draw = new \ImagickDraw();
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(1);
$draw->setFontSize(36);

$draw->setTextAlignment(\Imagick::ALIGN_LEFT);
$draw->annotation(250, 75, "Lorem Ipsum!");
$draw->setTextAlignment(\Imagick::ALIGN_CENTER);
$draw->annotation(250, 150, "Lorem Ipsum!");
$draw->setTextAlignment(\Imagick::ALIGN_RIGHT);
$draw->annotation(250, 225, "Lorem Ipsum!");
$draw->line(250, 0, 250, 500);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストをアンチエイリアス処理するかどうかを制御する

  • ≪ ImagickDraw::setTextAlignment
  • ImagickDraw::setTextDecoration ≫
  • PHP Manual
  • ImagickDraw
  • テキストをアンチエイリアス処理するかどうかを制御する

ImagickDraw::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — テキストをアンチエイリアス処理するかどうかを制御する

説明

public ImagickDraw::setTextAntialias(bool $antiAlias): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストをアンチエイリアス処理するかどうかを制御します。 デフォルトではテキストのアンチエイリアス処理を行います。

パラメータ

antiAlias

戻り値

値を返しません。

例

例1 ImagickDraw::setTextAntialias() の例

<?php
function setTextAntialias($fillColor, $backgroundColor) {

$draw = new \ImagickDraw();
$draw->setStrokeColor('none');
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(1);
$draw->setFontSize(32);
$draw->setTextAntialias(false);
$draw->annotation(5, 30, "Lorem Ipsum!");
$draw->setTextAntialias(true);
$draw->annotation(5, 65, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(220, 80, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

//Scale the image so that people can see the aliasing.
$imagick->scaleImage(220 * 6, 80 * 6);
$imagick->cropImage(640, 480, 0, 0);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


装飾を指定する

  • ≪ ImagickDraw::setTextAntialias
  • ImagickDraw::setTextEncoding ≫
  • PHP Manual
  • ImagickDraw
  • 装飾を指定する

ImagickDraw::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — 装飾を指定する

説明

public ImagickDraw::setTextDecoration(int $decoration): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に適用する装飾を指定します。

パラメータ

decoration

DECORATION 定数 (imagick::DECORATION_*) のうちのいずれか。

戻り値

値を返しません。

例

例1 ImagickDraw::setTextDecoration() の例

<?php
function setTextDecoration($strokeColor, $fillColor, $backgroundColor, $textDecoration) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(2);
$draw->setFontSize(72);
$draw->setTextDecoration($textDecoration);
$draw->annotation(50, 75, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(500, 200, $backgroundColor);
$imagick->setImageFormat("png");
$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


テキストのコードセットを指定する

  • ≪ ImagickDraw::setTextDecoration
  • ImagickDraw::setTextInterlineSpacing ≫
  • PHP Manual
  • ImagickDraw
  • テキストのコードセットを指定する

ImagickDraw::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — テキストのコードセットを指定する

説明

public ImagickDraw::setTextEncoding(string $encoding): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するコードセットを指定します。 現時点で指定できるエンコーディングは "UTF-8" のみで、 これはバイトシーケンスを Unicode で表記したものです。 空文字列を指定すると、システムのデフォルトを使用します。 Unicode によるテキストの注記を行うには、 Unicode をサポートしたフォントが必要です。

パラメータ

encoding

エンコーディング名。

戻り値

値を返しません。


Sets the text interline spacing

  • ≪ ImagickDraw::setTextEncoding
  • ImagickDraw::setTextInterwordSpacing ≫
  • PHP Manual
  • ImagickDraw
  • Sets the text interline spacing

ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing

説明

public ImagickDraw::setTextInterlineSpacing(float $spacing): bool

Sets the text interline spacing.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

spacing

戻り値

成功した場合に true を返します。


Sets the text interword spacing

  • ≪ ImagickDraw::setTextInterlineSpacing
  • ImagickDraw::setTextKerning ≫
  • PHP Manual
  • ImagickDraw
  • Sets the text interword spacing

ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing

説明

public ImagickDraw::setTextInterwordSpacing(float $spacing): bool

Sets the text interword spacing.

パラメータ

spacing

戻り値

成功した場合に true を返します。


Sets the text kerning

  • ≪ ImagickDraw::setTextInterwordSpacing
  • ImagickDraw::setTextUnderColor ≫
  • PHP Manual
  • ImagickDraw
  • Sets the text kerning

ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Sets the text kerning

説明

public ImagickDraw::setTextKerning(float $kerning): bool

Sets the text kerning

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

kerning

戻り値

成功した場合に true を返します。


背景の矩形の色を指定する

  • ≪ ImagickDraw::setTextKerning
  • ImagickDraw::setVectorGraphics ≫
  • PHP Manual
  • ImagickDraw
  • 背景の矩形の色を指定する

ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する

説明

public ImagickDraw::setTextUnderColor(ImagickPixel $under_color): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記の背景に置く矩形の色を指定します。

パラメータ

under_color

背景色。

戻り値

値を返しません。

例

例1 ImagickDraw::setTextUnderColor() の例

<?php
function setTextUnderColor($strokeColor, $fillColor, $backgroundColor, $textUnderColor) {
$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(2);
$draw->setFontSize(72);
$draw->annotation(50, 75, "Lorem Ipsum!");
$draw->setTextUnderColor($textUnderColor);
$draw->annotation(50, 175, "Lorem Ipsum!");

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


ベクターグラフィックを設定する

  • ≪ ImagickDraw::setTextUnderColor
  • ImagickDraw::setViewbox ≫
  • PHP Manual
  • ImagickDraw
  • ベクターグラフィックを設定する

ImagickDraw::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する

説明

public ImagickDraw::setVectorGraphics(string $xml): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した ImagickDraw オブジェクトに関連付けるベクターグラフィックを設定します。 このメソッドを ImagickDraw::getVectorGraphics() と組み合わせて使用すると、 ベクターグラフィックの状態を持続させることができます。

パラメータ

xml

ベクターグラフィックを表す xml。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ImagickDraw::setVectorGraphics() の例

<?php
function setVectorGraphics() {
//Setup a draw object with some drawing in it.
$draw = new \ImagickDraw();
$draw->setFillColor("red");
$draw->circle(20, 20, 50, 50);
$draw->setFillColor("blue");
$draw->circle(50, 70, 50, 50);
$draw->rectangle(50, 120, 80, 150);

//Get the drawing as a string
$SVG = $draw->getVectorGraphics();

//$svg is a string, and could be saved anywhere a string can be saved

//Use the saved drawing to generate a new draw object
$draw2 = new \ImagickDraw();
//Apparently the SVG text is missing the root element.
$draw2->setVectorGraphics("<root>".$SVG."</root>");

$imagick = new \Imagick();
$imagick->newImage(200, 200, 'white');
$imagick->setImageFormat("png");

$imagick->drawImage($draw2);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


キャンバス全体の大きさを設定する

  • ≪ ImagickDraw::setVectorGraphics
  • ImagickDraw::skewX ≫
  • PHP Manual
  • ImagickDraw
  • キャンバス全体の大きさを設定する

ImagickDraw::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — キャンバス全体の大きさを設定する

説明

public ImagickDraw::setViewbox(
int $x1,
int $y1,
int $x2,
int $y2
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ベクターデータの描画に使用するキャンバスの大きさを設定します。 通常は、これはキャンバス画像と同じ大きさに設定します。 ベクターデータを SVG や MVG 形式で保存する際に、 これを使用してキャンバス画像の大きさを指定します。 またビューアがベクターデータをレンダリングする際にもこれを使用します。

パラメータ

x1

左の x 座標。

y1

左の y 座標。

x2

右の x 座標。

y2

右の y 座標。

戻り値

値を返しません。

例

例1 ImagickDraw::setViewBox() の例

<?php
function setViewBox($strokeColor, $fillColor, $backgroundColor) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->setStrokeWidth(2);
$draw->setFontSize(72);

/*

Sets the overall canvas size to be recorded with the drawing vector data. Usually this will be specified using the same size as the canvas image. When the vector data is saved to SVG or MVG formats, the viewbox is use to specify the size of the canvas image that a viewer will render the vector data on.

*/

$draw->circle(250, 250, 250, 0);
$draw->setviewbox(0, 0, 200, 200);
$draw->circle(125, 250, 250, 250);
$draw->translate(250, 125);
$draw->circle(0, 0, 125, 0);

$imagick = new \Imagick();
$imagick->newImage(500, 500, $backgroundColor);
$imagick->setImageFormat("png");

$imagick->drawImage($draw);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


現在の座標系を水平方向に傾ける

  • ≪ ImagickDraw::setViewbox
  • ImagickDraw::skewY ≫
  • PHP Manual
  • ImagickDraw
  • 現在の座標系を水平方向に傾ける

ImagickDraw::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — 現在の座標系を水平方向に傾ける

説明

public ImagickDraw::skewX(float $degrees): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標系を水平方向に傾けます。

パラメータ

degrees

傾斜角。

戻り値

値を返しません。

例

例1 ImagickDraw::skewX() の例

<?php
function skewX($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
$startX, $startY, $endX, $endY, $skew) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setStrokeWidth(2);
$draw->setFillColor($fillColor);
$draw->rectangle($startX, $startY, $endX, $endY);
$draw->setFillColor($fillModifiedColor);
$draw->skewX($skew);
$draw->rectangle($startX, $startY, $endX, $endY);

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


現在の座標系を垂直方向に傾ける

  • ≪ ImagickDraw::skewX
  • ImagickDraw::translate ≫
  • PHP Manual
  • ImagickDraw
  • 現在の座標系を垂直方向に傾ける

ImagickDraw::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける

説明

public ImagickDraw::skewY(float $degrees): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標系を垂直方向に傾けます。

パラメータ

degrees

傾斜角。

戻り値

値を返しません。

例

例1 ImagickDraw::skewY() の例

<?php
function skewY($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
$startX, $startY, $endX, $endY, $skew) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setStrokeWidth(2);
$draw->setFillColor($fillColor);
$draw->rectangle($startX, $startY, $endX, $endY);
$draw->setFillColor($fillModifiedColor);
$draw->skewY($skew);
$draw->rectangle($startX, $startY, $endX, $endY);

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");
$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


現在の座標系に変換を適用する

  • ≪ ImagickDraw::skewY
  • ImagickPixel ≫
  • PHP Manual
  • ImagickDraw
  • 現在の座標系に変換を適用する

ImagickDraw::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — 現在の座標系に変換を適用する

説明

public ImagickDraw::translate(float $x, float $y): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の座標系に変換を適用し、座標系の原点を指定した座標に移動します。

パラメータ

x

水平方向の変換。

y

垂直方向の変換。

戻り値

値を返しません。

例

例1 ImagickDraw::translate() の例

<?php
function translate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
$startX, $startY, $endX, $endY, $translateX, $translateY) {

$draw = new \ImagickDraw();

$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->rectangle($startX, $startY, $endX, $endY);

$draw->setFillColor($fillModifiedColor);
$draw->translate($translateX, $translateY);
$draw->rectangle($startX, $startY, $endX, $endY);

$image = new \Imagick();
$image->newImage(500, 500, $backgroundColor);
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


ImagickPixel クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

class ImagickPixel {
public clear(): bool
public __construct(string $color = ?)
public destroy(): bool
public getColor(int $normalized = 0): array
public getColorAsString(): string
public getColorCount(): int
public getColorQuantum(): array
public getColorValue(int $color): float
public getColorValueQuantum(int $color): int|float
public getHSL(): array
public getIndex(): int
public isPixelSimilar(ImagickPixel $color, float $fuzz): bool
public isPixelSimilarQuantum(string $color, string $fuzz = ?): bool
public isSimilar(ImagickPixel $color, float $fuzz): bool
public setColor(string $color): bool
public setcolorcount(int $colorCount): bool
public setColorValue(int $color, float $value): bool
public setColorValueQuantum(int $color, int|float $value): bool
public setHSL(float $hue, float $saturation, float $luminosity): bool
public setIndex(int $index): bool
}

目次

  • ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する
  • ImagickPixel::__construct — ImagickPixel のコンストラクタ
  • ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する
  • ImagickPixel::getColor — 色を返す
  • ImagickPixel::getColorAsString — 色を文字列で返す
  • ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す
  • ImagickPixel::getColorQuantum — Returns the color of the pixel in an array as Quantum values
  • ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する
  • ImagickPixel::getColorValueQuantum — Gets the quantum value of a color in the ImagickPixel
  • ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
  • ImagickPixel::getIndex — Gets the colormap index of the pixel wand
  • ImagickPixel::isPixelSimilar — Check the distance between this color and another
  • ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance
  • ImagickPixel::isSimilar — この色と別の色の差を調べる
  • ImagickPixel::setColor — 色を設定する
  • ImagickPixel::setColorCount — Sets the color count associated with this color
  • ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する
  • ImagickPixel::setColorValueQuantum — Sets the quantum value of a color element of the ImagickPixel
  • ImagickPixel::setHSL — 正規化した HSL カラーを設定する
  • ImagickPixel::setIndex — Sets the colormap index of the pixel wand


このオブジェクトに関連付けられたリソースを消去する

  • ≪ ImagickPixel
  • ImagickPixel::__construct ≫
  • PHP Manual
  • ImagickPixel
  • このオブジェクトに関連付けられたリソースを消去する

ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する

説明

public ImagickPixel::clear(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトをクリアし、初期状態に戻します。 このオブジェクトに関連付けられている色も初期化します。

戻り値

成功した場合に true を返します。


ImagickPixel のコンストラクタ

  • ≪ ImagickPixel::clear
  • ImagickPixel::destroy ≫
  • PHP Manual
  • ImagickPixel
  • ImagickPixel のコンストラクタ

ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — ImagickPixel のコンストラクタ

説明

public ImagickPixel::__construct(string $color = ?)
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトを作成します。color を指定した場合は、 オブジェクトを作成した後で色を初期化してから返します。

パラメータ

color

このオブジェクトの初期化に使用する色を表すオプションの文字列。

戻り値

成功した場合に ImagickPixel オブジェクトを返します。 失敗した場合に ImagickPixelException をスローします。

例

例1 ImagickPixel::construct()

<?php
function construct() {

$columns = 4;

$exampleColors = array(
"rgba(100%, 0%, 0%, 0.5)",
"hsb(33.3333%, 100%, 75%)", // medium green
"hsl(120, 255, 191.25)", //medium green
"graya(50%, 0.5)", // semi-transparent mid gray
"LightCoral", "none", //"cmyk(0.9, 0.48, 0.83, 0.50)",
"#f00", // #rgb
"#ff0000", // #rrggbb
"#ff0000ff", // #rrggbbaa
"#ffff00000000", // #rrrrggggbbbb
"#ffff00000000ffff", // #rrrrggggbbbbaaaa
"rgb(255, 0, 0)", // an integer in the range 0—255 for each component
"rgb(100.0%, 0.0%, 0.0%)", // a float in the range 0—100% for each component
"rgb(255, 0, 0)", // range 0 - 255
"rgba(255, 0, 0, 1.0)", // the same, with an explicit alpha value
"rgb(100%, 0%, 0%)", // range 0.0% - 100.0%
"rgba(100%, 0%, 0%, 1.0)", // the same, with an explicit alpha value
);

$draw = new \ImagickDraw();
$count = 0;
$black = new \ImagickPixel('rgb(0, 0, 0)');

foreach ($exampleColors as $exampleColor) {
$color = new \ImagickPixel($exampleColor);

$draw->setstrokewidth(1.0);
$draw->setStrokeColor($black);
$draw->setFillColor($color);
$offsetX = ($count % $columns) * 50 + 5;
$offsetY = intval($count / $columns) * 50 + 5;
$draw->rectangle(0 + $offsetX, 0 + $offsetY, 40 + $offsetX, 40 + $offsetY);
$count++;
}

$image = new \Imagick();
$image->newImage(350, 350, "blue");
$image->setImageFormat("png");
$image->drawImage($draw);
header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


このオブジェクトに関連付けられているリソースの割り当てを解除する

  • ≪ ImagickPixel::__construct
  • ImagickPixel::getColor ≫
  • PHP Manual
  • ImagickPixel
  • このオブジェクトに関連付けられているリソースの割り当てを解除する

ImagickPixel::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する

説明

public ImagickPixel::destroy(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトが使用しているリソースの割り当てを解除し、 色を初期化します。destroy 関数をコールした後は、このオブジェクトを使用することはできません。

戻り値

成功した場合に true を返します。


色を返す

  • ≪ ImagickPixel::destroy
  • ImagickPixel::getColorAsString ≫
  • PHP Manual
  • ImagickPixel
  • 色を返す

ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — 色を返す

説明

public ImagickPixel::getColor(int $normalized = 0): array

ImagickPixel オブジェクトの色を、配列で返します。透明度が設定されている場合は、 4 つの要素からなる配列となります。

パラメータ

normalized

色を正規化する。 有効な値は 0, 1, 2 です。

normalized で有効な値の一覧
normalized | 説明
0 | RGB の値を 0 から 255 の間の値を取る int として返します (0 と 255 を含みます)。 アルファの値を 0 または 1 の int として返します。
1 | RGBA の値を 0 から 1 の間の値を取る float として返します (0 と 1 を含みます)。
2 | RGBA の値を 0 から 255 の間の値を取る int として返します (0 と 255 を含みます)。

戻り値

各チャネルの値を配列で返します。 エラー時には ImagickPixelException をスローします。

例

例1 基本的な Imagick::getColor() の使用例

<?php

// 定義済みの色 'brown' で ImagickPixel を作ります
$color = new ImagickPixel('brown');

// アルファ値を 25% にします
$color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

$colorInfo = $color->getColor();

echo "Standard values".PHP_EOL;
print_r($colorInfo);

$colorInfo = $color->getColor(1);

echo "Normalized values:".PHP_EOL;
print_r($colorInfo);

?>

上の例の出力は以下となります。

Standard values
Array
(
    [r] => 165
    [g] => 42
    [b] => 42
    [a] => 0
)
Normalized values:
Array
(
    [r] => 0.64705882352941
    [g] => 0.16470588235294
    [b] => 0.16470588235294
    [a] => 0.25000381475547
)


色を文字列で返す

  • ≪ ImagickPixel::getColor
  • ImagickPixel::getColorCount ≫
  • PHP Manual
  • ImagickPixel
  • 色を文字列で返す

ImagickPixel::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — 色を文字列で返す

説明

public ImagickPixel::getColorAsString(): string

ImagickPixel オブジェクトの色を文字列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ImagickPixel オブジェクトの色を文字列で返します。

例

例1 基本的な Imagick::getColorAsString() の使用例

<?php

// 定義済みの色 'brown' で ImagickPixel を作ります
$color = new ImagickPixel('brown');

$color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

$colorInfo = $color->getColorAsString();

print_r($colorInfo);
?>

上の例の出力は以下となります。

rgb(165,42,42)

注意

注意: アルファ値は返さない

この関数が返す文字列には、色のアルファ値は含まれません。


この色に関連付けられている色カウントを返す

  • ≪ ImagickPixel::getColorAsString
  • ImagickPixel::getColorQuantum ≫
  • PHP Manual
  • ImagickPixel
  • この色に関連付けられている色カウントを返す

ImagickPixel::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す

説明

public ImagickPixel::getColorCount(): int

この色に関連付けられている色カウントを返します。

色カウントとは、画像内でこの ImagickPixel と同じ色を持つピクセル数のことです。

ImagickPixel::getColorCount は、Imagick::getImageHistogram() で作った ImagickPixel オブジェクトに対してのみ機能します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に色カウントを返します。失敗した場合に ImagickPixelException をスローします。

例

例1 ImagickPixel getColorCount()

<?php
$imagick = new \Imagick();
$imagick->newPseudoImage(640, 480, "magick:logo");
$histogramElements = $imagick->getImageHistogram();
$lastColor = array_pop($histogramElements);
echo "Last pixel color count is: ".$lastColor->getColorCount();
?>

出力は、次のようになります。

Last pixel color count is: 256244


Returns the color of the pixel in an array as Quantum values

  • ≪ ImagickPixel::getColorCount
  • ImagickPixel::getColorValue ≫
  • PHP Manual
  • ImagickPixel
  • Returns the color of the pixel in an array as Quantum values

ImagickPixel::getColorQuantum

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ImagickPixel::getColorQuantum — Returns the color of the pixel in an array as Quantum values

説明

public ImagickPixel::getColorQuantum(): array

Returns the color of the pixel in an array as Quantum values. If ImageMagick was compiled as HDRI these will be floats, otherwise they will be integers.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array with keys "r", "g", "b", "a".


指定した色チャネルの値を正規化したものを取得する

  • ≪ ImagickPixel::getColorQuantum
  • ImagickPixel::getColorValueQuantum ≫
  • PHP Manual
  • ImagickPixel
  • 指定した色チャネルの値を正規化したものを取得する

ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する

説明

public ImagickPixel::getColorValue(int $color): float

指定した色チャネルの値を取得します。 これは、0 から 1 までの間の浮動小数点数値となります。

パラメータ

color

調べたい色。Imagick の色定数で指定します。 RGB カラー、CMYK カラー、アルファ値、透明度を指定できます (Imagick::COLOR_BLUE や Imagick::COLOR_MAGENTA など)。

戻り値

チャネルの値を正規化した浮動小数点数値を返します。 エラー時には ImagickPixelException をスローします。

例

例1 基本的な Imagick::getColorValue() の使用例

<?php

$color = new ImagickPixel('rgba(90%, 20%, 20%, 0.75)');

echo "Alpha value is ".$color->getColorValue(Imagick::COLOR_ALPHA).PHP_EOL;
echo "".PHP_EOL;
echo "Red value is ".$color->getColorValue(Imagick::COLOR_RED).PHP_EOL;
echo "Green value is ".$color->getColorValue(Imagick::COLOR_GREEN).PHP_EOL;
echo "Blue value is ".$color->getColorValue(Imagick::COLOR_BLUE).PHP_EOL;
echo "".PHP_EOL;
echo "Cyan value is ".$color->getColorValue(Imagick::COLOR_CYAN).PHP_EOL;
echo "Magenta value is ".$color->getColorValue(Imagick::COLOR_MAGENTA).PHP_EOL;
echo "Yellow value is ".$color->getColorValue(Imagick::COLOR_YELLOW).PHP_EOL;
echo "Black value is ".$color->getColorValue(Imagick::COLOR_BLACK).PHP_EOL;

?>

上の例の出力は以下となります。

Alpha value is 0.74999618524453

Red value is 0.90000762951095
Green value is 0.2
Blue value is 0.2

Cyan value is 0.90000762951095
Magenta value is 0.2
Yellow value is 0.2
Black value is 0


Gets the quantum value of a color in the ImagickPixel

  • ≪ ImagickPixel::getColorValue
  • ImagickPixel::getHSL ≫
  • PHP Manual
  • ImagickPixel
  • Gets the quantum value of a color in the ImagickPixel

ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — Gets the quantum value of a color in the ImagickPixel

説明

public ImagickPixel::getColorValueQuantum(int $color): int|float

Gets the quantum value of a color in the ImagickPixel. Return value is a float if ImageMagick was compiled with HDRI, otherwise an integer.

パラメータ

この関数にはパラメータはありません。

戻り値

The quantum value of the color element. Float if ImageMagick was compiled with HDRI, otherwise an int.

例

例1 ImagickPixel::getColorValueQuantum()

<?php
$color = new \ImagickPixel('rgb(128, 5, 255)');
$colorRed = $color->getColorValueQuantum(\Imagick::COLOR_RED);
$colorGreen = $color->getColorValueQuantum(\Imagick::COLOR_GREEN);
$colorBlue = $color->getColorValueQuantum(\Imagick::COLOR_BLUE);
$colorAlpha = $color->getColorValueQuantum(\Imagick::COLOR_ALPHA);

printf(
"Red: %s Green: %s Blue %s Alpha: %s",
$colorRed,
$colorGreen,
$colorBlue,
$colorAlpha
);

?>


ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

  • ≪ ImagickPixel::getColorValueQuantum
  • ImagickPixel::getIndex ≫
  • PHP Manual
  • ImagickPixel
  • ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

ImagickPixel::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

説明

public ImagickPixel::getHSL(): array

ImagickPixel オブジェクトの HSL カラーを正規化したものを返します。 3 つの値は、それぞれ 0.0 から 1.0 までの間の浮動小数点数値となります。

パラメータ

この関数にはパラメータはありません。

戻り値

HSL の値をそれぞれ "hue"、 "saturation"、そして "luminosity" というキーに保持する配列を返します。 失敗した場合に ImagickPixelException をスローします。

例

例1 基本的な Imagick::getHSL() の使用例

<?php

$color = new ImagickPixel('rgb(90%, 10%, 10%)');

$colorInfo = $color->getHSL();

print_r($colorInfo);

?>

上の例の出力は以下となります。

Array
(
    [hue] => 0
    [saturation] => 0.80001220740379
    [luminosity] => 0.50000762951095
)

注意

注意:

ImageMagick ライブラリバージョン 6.2.9 以降で使用可能です。


Gets the colormap index of the pixel wand

  • ≪ ImagickPixel::getHSL
  • ImagickPixel::isPixelSimilar ≫
  • PHP Manual
  • ImagickPixel
  • Gets the colormap index of the pixel wand

ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — Gets the colormap index of the pixel wand

説明

public ImagickPixel::getIndex(): int

Gets the colormap index of the pixel wand.

パラメータ

この関数にはパラメータはありません。

戻り値


Check the distance between this color and another

  • ≪ ImagickPixel::getIndex
  • ImagickPixel::isPixelSimilarQuantum ≫
  • PHP Manual
  • ImagickPixel
  • Check the distance between this color and another

ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Check the distance between this color and another

説明

public ImagickPixel::isPixelSimilar(ImagickPixel $color, float $fuzz): bool

Checks the distance between the color described by this ImagickPixel object and that of the provided object, by plotting their RGB values on the color cube. If the distance between the two points is less than the fuzz value given, the colors are similar. This method replaces ImagickPixel::isSimilar() and correctly normalises the fuzz value to ImageMagick QuantumRange.

パラメータ

color

The ImagickPixel object to compare this object against.

fuzz

The maximum distance within which to consider these colors as similar. The theoretical maximum for this value is the square root of three (1.732).

戻り値

成功した場合に true を返します。


Returns whether two colors differ by less than the specified distance

  • ≪ ImagickPixel::isPixelSimilar
  • ImagickPixel::isSimilar ≫
  • PHP Manual
  • ImagickPixel
  • Returns whether two colors differ by less than the specified distance

ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance

説明

public ImagickPixel::isPixelSimilarQuantum(string $color, string $fuzz = ?): bool

Returns true if the distance between two colors is less than the specified distance. The fuzz value should be in the range 0-QuantumRange. The maximum value represents the longest possible distance in the colorspace. e.g. from RGB(0, 0, 0) to RGB(255, 255, 255) for the RGB colorspace

パラメータ

color

fuzz

戻り値


この色と別の色の差を調べる

  • ≪ ImagickPixel::isPixelSimilarQuantum
  • ImagickPixel::setColor ≫
  • PHP Manual
  • ImagickPixel
  • この色と別の色の差を調べる

ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — この色と別の色の差を調べる

説明

public isSimilar(ImagickPixel $color, float $fuzz): bool
}
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickPixel オブジェクトと別のオブジェクトの色の差を調べます。 これは、両者の RGB 値を色立方体上にプロットすることで行います。 ふたつの色の差が fuzz で指定した値よりも小さければ、 同じ色であるとみなされます。 非推奨です。かわりに ImagickPixel::isPixelSimilar() を使いましょう。

パラメータ

color

このオブジェクトと比較したい ImagickPixel オブジェクト。

fuzz

同じ色であるとみなす最大の誤差。 理論上の最大値は、3 の平方根 (1.732) となります。

戻り値

成功した場合に true を返します。

例

例1 ImagickPixel::isSimilar()

<?php
// The tests below are written with the maximum distance expressed as 255
// so we need to scale them by the square root of 3 - the diagonal length
// of a unit cube.
$root3 = 1.732050807568877;

$tests = array(
['rgb(245, 0, 0)', 'rgb(255, 0, 0)', 9 / $root3, false,],
['rgb(245, 0, 0)', 'rgb(255, 0, 0)', 10 / $root3, true,],
['rgb(0, 0, 0)', 'rgb(7, 7, 0)', 9 / $root3, false,],
['rgb(0, 0, 0)', 'rgb(7, 7, 0)', 10 / $root3, true,],
['rgba(0, 0, 0, 1)', 'rgba(7, 7, 0, 1)', 9 / $root3, false,],
['rgba(0, 0, 0, 1)', 'rgba(7, 7, 0, 1)', 10 / $root3, true,],
['rgb(128, 128, 128)', 'rgb(128, 128, 120)', 7 / $root3, false,],
['rgb(128, 128, 128)', 'rgb(128, 128, 120)', 8 / $root3, true,],
['rgb(0, 0, 0)', 'rgb(255, 255, 255)', 254.9, false,],
['rgb(0, 0, 0)', 'rgb(255, 255, 255)', 255, true,],
['rgb(255, 0, 0)', 'rgb(0, 255, 255)', 254.9, false,],
['rgb(255, 0, 0)', 'rgb(0, 255, 255)', 255, true,],
['black', 'rgba(0, 0, 0)', 0.0, true],
['black', 'rgba(10, 0, 0, 1.0)', 10.0 / $root3, true],);

$output = "<table width='100%' class='infoTable'><thead>
<tr>
<th>
Color 1
</th>
<th>
Color 2
</th>
<th>
Test distance * 255
</th>
<th>
Is within distance
</th>
</tr>
</thead>";

$output .= "<tbody>";

foreach ($tests as $testInfo) {
$color1 = $testInfo[0];
$color2 = $testInfo[1];
$distance = $testInfo[2];
$expectation = $testInfo[3];
$testDistance = ($distance / 255.0);

$color1Pixel = new \ImagickPixel($color1);
$color2Pixel = new \ImagickPixel($color2);

$isSimilar = $color1Pixel->isPixelSimilar($color2Pixel, $testDistance);

if ($isSimilar !== $expectation) {
echo "Test distance failed. Color [$color1] compared to color [$color2] is not within distance $testDistance FAILED.".NL;
}

$layout = "<tr>
<td>%s</td>
<td>%s</td>
<td>%s</td>
<td style='text-align: center;'>%s</td>
</tr>";

$output .= sprintf(
$layout,
$color1,
$color2,
$distance,
$isSimilar ? 'yes' : 'no'
);
}

$output .= "</tbody></table>";

return $output;

?>


色を設定する

  • ≪ ImagickPixel::isSimilar
  • ImagickPixel::setColorCount ≫
  • PHP Manual
  • ImagickPixel
  • 色を設定する

ImagickPixel::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — 色を設定する

説明

public ImagickPixel::setColor(string $color): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickPixel オブジェクトの色を、文字列 (たとえば "blue"、"#0000ff"、"rgb(0,0,255)"、"cmyk(100,100,100,10)" などの形式) で設定します。

パラメータ

color

ImagickPixel オブジェクトを初期化する際に使用する色。

戻り値

色が設定できた場合に true、それ以外の場合に false を返します。

例

例1 ImagickPixel::setColor()

<?php
function setColor() {
$draw = new \ImagickDraw();

$strokeColor = new \ImagickPixel('green');
$fillColor = new \ImagickPixel();
$fillColor->setColor('rgba(100%, 75%, 0%, 1.0)');

$draw->setstrokewidth(3.0);
$draw->setStrokeColor($strokeColor);
$draw->setFillColor($fillColor);
$draw->rectangle(200, 200, 300, 300);

$image = new \Imagick();
$image->newImage(500, 500, "SteelBlue2");
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


Sets the color count associated with this color

  • ≪ ImagickPixel::setColor
  • ImagickPixel::setColorValue ≫
  • PHP Manual
  • ImagickPixel
  • Sets the color count associated with this color

ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — Sets the color count associated with this color

説明

public ImagickPixel::setcolorcount(int $colorCount): bool

Sets the color count associated with this color.

パラメータ

colorCount

戻り値

成功した場合に true を返します。


指定したチャネルの正規化した値を設定する

  • ≪ ImagickPixel::setColorCount
  • ImagickPixel::setColorValueQuantum ≫
  • PHP Manual
  • ImagickPixel
  • 指定したチャネルの正規化した値を設定する

ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する

説明

public ImagickPixel::setColorValue(int $color, float $value): bool

このオブジェクトの、指定したチャネルの値を正規化したものを設定します。 これは 0 から 1 までの値となります。この関数は、 ImagickPixel オブジェクトの透明度を指定する際にも使用します。

パラメータ

color

Imagick 色チャネル定数のいずれか。\Imagick::COLOR_GREEN や \Imagick::COLOR_ALPHA など。

value

そのチャネルに設定する値。0 から 1 までとなります。

戻り値

成功した場合に true を返します。

例

例1 基本的な Imagick::setColorValue() の使用例

<?php

$color = new \ImagickPixel('firebrick');

$color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

print_r($color->getcolor(true));
?>

上の例の出力は以下となります。

Array
(
    [r] => 0.69803921568627
    [g] => 0.13333333333333
    [b] => 0.13333333333333
    [a] => 0.50000762951095
)


Sets the quantum value of a color element of the ImagickPixel

  • ≪ ImagickPixel::setColorValue
  • ImagickPixel::setHSL ≫
  • PHP Manual
  • ImagickPixel
  • Sets the quantum value of a color element of the ImagickPixel

ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — Sets the quantum value of a color element of the ImagickPixel

説明

public ImagickPixel::setColorValueQuantum(int $color, int|float $value): bool

Sets the quantum value of a color element of the ImagickPixel.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

color

Which color element to set e.g. \Imagick::COLOR_GREEN.

value

The quantum value to set the color element to. This should be a float if ImageMagick was compiled with HDRI otherwise an int in the range 0 to Imagick::getQuantum().

戻り値

成功した場合に true を返します。

例

例1 ImagickPixel::setColorValueQuantum()

<?php
function setColorValueQuantum() {
$image = new \Imagick();

$quantumRange = $image->getQuantumRange();

$draw = new \ImagickDraw();
$color = new \ImagickPixel('blue');
$color->setcolorValueQuantum(\Imagick::COLOR_RED, 128 * $quantumRange['quantumRangeLong'] / 256);

$draw->setstrokewidth(1.0);
$draw->setStrokeColor($color);
$draw->setFillColor($color);
$draw->rectangle(200, 200, 300, 300);

$image->newImage(500, 500, "SteelBlue2");
$image->setImageFormat("png");

$image->drawImage($draw);

header("Content-Type: image/png");
echo $image->getImageBlob();
}

?>


正規化した HSL カラーを設定する

  • ≪ ImagickPixel::setColorValueQuantum
  • ImagickPixel::setIndex ≫
  • PHP Manual
  • ImagickPixel
  • 正規化した HSL カラーを設定する

ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — 正規化した HSL カラーを設定する

説明

public ImagickPixel::setHSL(float $hue, float $saturation, float $luminosity): bool

hue (色相)、saturation (彩度) および luminosity (明度) を正規化した値によって ImagickPixel オブジェクトの色を設定します。

パラメータ

hue

色相を正規化した値。これは、色相環上での位置 (0 から 1 まで) を表します。ゼロは赤です。

saturation

彩度を正規化した値。1 が最大です。

luminosity

明度を正規化した値。黒が 0、白が 1 で、 0.5 にすると完全な HS 値が再現されます。

戻り値

成功した場合に true を返します。

例

例1 ImagickPixel::setHSL() による色の変更

<?php

// ほぼ真っ赤な色を作ります
$color = new ImagickPixel('rgb(90%, 10%, 10%)');

// その HSL 値を取得します
$colorInfo = $color->getHSL();

// 色相を 180 度反転させます
$newHue = $colorInfo['hue'] + 0.5;
if ($newHue > 1) {
$newHue = $newHue - 1;
}

// ImagickPixel を新しい色に設定します
$colorInfo = $color->setHSL($newHue, $colorInfo['saturation'], $colorInfo['luminosity']);

// 新しい色が青/緑になることを確かめます
$colorInfo = $color->getcolor();
print_r($colorInfo);

?>

上の例の出力は以下となります。

Array
(
    [r] => 26
    [g] => 230
    [b] => 230
    [a] => 255
)

注意

注意:

ImageMagick ライブラリバージョン 6.2.9 以降で使用可能です。


Sets the colormap index of the pixel wand

  • ≪ ImagickPixel::setHSL
  • ImagickPixelIterator ≫
  • PHP Manual
  • ImagickPixel
  • Sets the colormap index of the pixel wand

ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — Sets the colormap index of the pixel wand

説明

public ImagickPixel::setIndex(int $index): bool

Sets the colormap index of the pixel wand.

パラメータ

index

戻り値

成功した場合に true を返します。


ImagickPixelIterator クラス

(PECL imagick 2, PECL imagick 3)

クラス概要

class ImagickPixelIterator {
public clear(): bool
public __construct(Imagick $wand)
public destroy(): bool
public getCurrentIteratorRow(): array
public getIteratorRow(): int
public getNextIteratorRow(): array
public getPreviousIteratorRow(): array
public newPixelIterator(Imagick $wand): bool
public newPixelRegionIterator(
Imagick $wand,
int $x,
int $y,
int $columns,
int $rows
): bool
public resetIterator(): bool
public setIteratorFirstRow(): bool
public setIteratorLastRow(): bool
public setIteratorRow(int $row): bool
public syncIterator(): bool
}

目次

  • ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する
  • ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ
  • ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する
  • ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す
  • ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す
  • ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す
  • ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す
  • ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す
  • ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す
  • ImagickPixelIterator::resetIterator — pixel iterator をリセットする
  • ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する
  • ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する
  • ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する
  • ImagickPixelIterator::syncIterator — pixel iterator を同期する


PixelIterator に関連付けられたリソースを消去する

  • ≪ ImagickPixelIterator
  • ImagickPixelIterator::__construct ≫
  • PHP Manual
  • ImagickPixelIterator
  • PixelIterator に関連付けられたリソースを消去する

ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する

説明

public ImagickPixelIterator::clear(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

PixelIterator に関連付けられたリソースを消去します。

戻り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::clear()

<?php
function clear($imagePath) {
$imagick = new \Imagick(realpath($imagePath));

$imageIterator = $imagick->getPixelRegionIterator(100, 100, 250, 200);

/* Loop through pixel rows */
foreach ($imageIterator as $pixels) {
/** @var $pixel \ImagickPixel */
/* Loop through the pixels in the row (columns) */
foreach ($pixels as $column => $pixel) {
if ($column % 2) {
/* Paint every second pixel black*/
$pixel->setColor("rgba(0, 0, 0, 0)");
}
}
/* Sync the iterator, this is important to do on each iteration */
$imageIterator->syncIterator();
}

$imageIterator->clear();

header("Content-Type: image/jpg");
echo $imagick;
}

?>


ImagickPixelIterator のコンストラクタ

  • ≪ ImagickPixelIterator::clear
  • ImagickPixelIterator::destroy ≫
  • PHP Manual
  • ImagickPixelIterator
  • ImagickPixelIterator のコンストラクタ

ImagickPixelIterator::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ

説明

public ImagickPixelIterator::__construct(Imagick $wand)
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixelIterator のコンストラクタです。

戻り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::construct()

<?php
function construct($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imageIterator = new \ImagickPixelIterator($imagick);

/* Loop through pixel rows */
foreach ($imageIterator as $pixels) {
/* Loop through the pixels in the row (columns) */
foreach ($pixels as $column => $pixel) {
/** @var $pixel \ImagickPixel */
if ($column % 2) {
/* Paint every second pixel black*/
$pixel->setColor("rgba(0, 0, 0, 0)");
}
}
/* Sync the iterator, this is important to do on each iteration */
$imageIterator->syncIterator();
}

header("Content-Type: image/jpg");
echo $imagick;
}

?>


PixelIterator に関連付けられているリソースの割り当てを解除する

  • ≪ ImagickPixelIterator::__construct
  • ImagickPixelIterator::getCurrentIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • PixelIterator に関連付けられているリソースの割り当てを解除する

ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する

説明

public ImagickPixelIterator::destroy(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

PixelIterator に関連付けられているリソースの割り当てを解除します。

戻り値

成功した場合に true を返します。


ImagickPixel オブジェクトの現在の行を返す

  • ≪ ImagickPixelIterator::destroy
  • ImagickPixelIterator::getIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • ImagickPixel オブジェクトの現在の行を返す

ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す

説明

public ImagickPixelIterator::getCurrentIteratorRow(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の現在の行を、ImagickPixel オブジェクトの配列で返します。

戻り値

ImagickPixel オブジェクトの配列形式で行を返します。これを順次処理することが可能です。


pixel iterator の現在の行を返す

  • ≪ ImagickPixelIterator::getCurrentIteratorRow
  • ImagickPixelIterator::getNextIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator の現在の行を返す

ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す

説明

public ImagickPixelIterator::getIteratorRow(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の現在の行を返します。

戻り値

pixel iterator の現在の行を返します。 エラー時には ImagickPixelIteratorException をスローします。


pixel iterator の次の行を返す

  • ≪ ImagickPixelIterator::getIteratorRow
  • ImagickPixelIterator::getPreviousIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator の次の行を返す

ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す

説明

public ImagickPixelIterator::getNextIteratorRow(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の次の行を、pixel wands の配列として返します。

戻り値

次の行を ImagickPixel オブジェクトの配列で返します。 エラー時には ImagickPixelIteratorException をスローします。

例

例1 ImagickPixelIterator::getNextIteratorRow()

<?php
function getNextIteratorRow($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imageIterator = $imagick->getPixelIterator();

$count = 0;
while ($pixels = $imageIterator->getNextIteratorRow()) {
if (($count % 3) == 0) {
/* Loop through the pixels in the row (columns) */
foreach ($pixels as $column => $pixel) {
/** @var $pixel \ImagickPixel */
if ($column % 2) {
/* Paint every second pixel black*/
$pixel->setColor("rgba(0, 0, 0, 0)");
}
}
/* Sync the iterator, this is important to do on each iteration */
$imageIterator->syncIterator();
}

$count += 1;
}

header("Content-Type: image/jpg");
echo $imagick;
}

?>


前の行を返す

  • ≪ ImagickPixelIterator::getNextIteratorRow
  • ImagickPixelIterator::newPixelIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • 前の行を返す

ImagickPixelIterator::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す

説明

public ImagickPixelIterator::getPreviousIteratorRow(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の前の行を、pixel wands の配列として返します。

戻り値

ImagickPixelIterator の前の行を、ImagickPixelWand オブジェクトの配列として返します。エラー時には ImagickPixelIteratorException をスローします。


新しい pixel iterator を返す

  • ≪ ImagickPixelIterator::getPreviousIteratorRow
  • ImagickPixelIterator::newPixelRegionIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • 新しい pixel iterator を返す

ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す

説明

public ImagickPixelIterator::newPixelIterator(Imagick $wand): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい pixel iterator を返します。

戻り値

成功した場合に true を返します。 ImagickPixelIteratorException をスローします。


新しい pixel iterator を返す

  • ≪ ImagickPixelIterator::newPixelIterator
  • ImagickPixelIterator::resetIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • 新しい pixel iterator を返す

ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す

説明

public ImagickPixelIterator::newPixelRegionIterator(
Imagick $wand,
int $x,
int $y,
int $columns,
int $rows
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい pixel iterator を返します。

パラメータ

wand

x

y

columns

rows

戻り値

成功した場合に新しい ImagickPixelIterator を返します。 失敗した場合は ImagickPixelIteratorException をスローします。


pixel iterator をリセットする

  • ≪ ImagickPixelIterator::newPixelRegionIterator
  • ImagickPixelIterator::setIteratorFirstRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator をリセットする

ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — pixel iterator をリセットする

説明

public ImagickPixelIterator::resetIterator(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator をリセットします。 ImagickPixelIterator::getNextIteratorRow() と組み合わせて使用し、 ピクセルコンテナのすべてのピクセルを順にたどります。

戻り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::resetIterator()

<?php
function resetIterator($imagePath) {

$imagick = new \Imagick(realpath($imagePath));

$imageIterator = $imagick->getPixelIterator();

/* Loop trough pixel rows */
foreach ($imageIterator as $pixels) {
/* Loop through the pixels in the row (columns) */
foreach ($pixels as $column => $pixel) {
/** @var $pixel \ImagickPixel */
if ($column % 2) {

/* Make every second pixel 25% red*/
$pixel->setColorValue(\Imagick::COLOR_RED, 64);
}
}
/* Sync the iterator, this is important to do on each iteration */
$imageIterator->syncIterator();
}

$imageIterator->resetiterator();

/* Loop trough pixel rows */
foreach ($imageIterator as $pixels) {
/* Loop through the pixels in the row (columns) */
foreach ($pixels as $column => $pixel) {
/** @var $pixel \ImagickPixel */
if ($column % 3) {
$pixel->setColorValue(\Imagick::COLOR_BLUE, 64); /* Make every second pixel a little blue*/
//$pixel->setColor("rgba(0, 0, 128, 0)"); /* Paint every second pixel black*/
}
}
$imageIterator->syncIterator(); /* Sync the iterator, this is important to do on each iteration */
}

$imageIterator->clear();

header("Content-Type: image/jpg");
echo $imagick;
}

?>


pixel iterator を最初の行に設定する

  • ≪ ImagickPixelIterator::resetIterator
  • ImagickPixelIterator::setIteratorLastRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator を最初の行に設定する

ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する

説明

public ImagickPixelIterator::setIteratorFirstRow(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を最初の行に設定します。

戻り値

成功した場合に true を返します。


pixel iterator を最後の行に設定する

  • ≪ ImagickPixelIterator::setIteratorFirstRow
  • ImagickPixelIterator::setIteratorRow ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator を最後の行に設定する

ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する

説明

public ImagickPixelIterator::setIteratorLastRow(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を最後の行に設定します。

戻り値

成功した場合に true を返します。


pixel iterator の行を設定する

  • ≪ ImagickPixelIterator::setIteratorLastRow
  • ImagickPixelIterator::syncIterator ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator の行を設定する

ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する

説明

public ImagickPixelIterator::setIteratorRow(int $row): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の行を設定します。

パラメータ

row

戻り値

成功した場合に true を返します。

例

例1 ImagickPixelIterator::setIteratorRow()

<?php
function setIteratorRow($imagePath) {
$imagick = new \Imagick(realpath($imagePath));
$imageIterator = $imagick->getPixelRegionIterator(200, 100, 200, 200);

for ($x = 0; $x < 20; $x++) {
$imageIterator->setIteratorRow($x * 5);
$pixels = $imageIterator->getCurrentIteratorRow();
/* Loop through the pixels in the row (columns) */
foreach ($pixels as $pixel) {
/** @var $pixel \ImagickPixel */
/* Paint every second pixel black*/
$pixel->setColor("rgba(0, 0, 0, 0)");
}

/* Sync the iterator, this is important to do on each iteration */
$imageIterator->syncIterator();
}

header("Content-Type: image/jpg");
echo $imagick;
}

?>


pixel iterator を同期する

  • ≪ ImagickPixelIterator::setIteratorRow
  • ImagickKernel ≫
  • PHP Manual
  • ImagickPixelIterator
  • pixel iterator を同期する

ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — pixel iterator を同期する

説明

public ImagickPixelIterator::syncIterator(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を同期します。

戻り値

成功した場合に true を返します。


The ImagickKernel class

(PECL imagick >= 3.3.0)

はじめに

クラス概要

class ImagickKernel {
/* メソッド */
public addKernel(ImagickKernel $ImagickKernel): void
public addUnityKernel(float $scale): void
public static fromBuiltin(int $kernelType, string $kernelString): ImagickKernel
public static fromMatrix(array $matrix, array $origin = ?): ImagickKernel
public getMatrix(): array
public scale(float $scale, int $normalizeFlag = ?): void
public separate(): array
}

目次

  • ImagickKernel::addKernel — Attach another kernel to a kernel list
  • ImagickKernel::addUnityKernel — Adds a Unity Kernel to the kernel list
  • ImagickKernel::fromBuiltIn — Create a kernel from a builtin in kernel
  • ImagickKernel::fromMatrix — Create a kernel from a 2d matrix of values
  • ImagickKernel::getMatrix — Get the 2d matrix of values used in this kernel
  • ImagickKernel::scale — Scales a kernel list by the given amount
  • ImagickKernel::separate — Separates a linked set of kernels and returns an array of ImagickKernels


Attach another kernel to a kernel list

  • ≪ ImagickKernel
  • ImagickKernel::addUnityKernel ≫
  • PHP Manual
  • ImagickKernel
  • Attach another kernel to a kernel list

ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — Attach another kernel to a kernel list

説明

public ImagickKernel::addKernel(ImagickKernel $ImagickKernel): void

Attach another kernel to this kernel to allow them to both be applied in a single morphology or filter function. Returns the new combined kernel.

パラメータ

ImagickKernel

戻り値

例

例1 ImagickKernel::addKernel()

<?php
function addKernel($imagePath) {
$matrix1 = [
[-1, -1, -1],
[ 0, 0, 0],
[ 1, 1, 1],
];

$matrix2 = [
[-1, 0, 1],
[-1, 0, 1],
[-1, 0, 1],
];

$kernel1 = ImagickKernel::fromMatrix($matrix1);
$kernel2 = ImagickKernel::fromMatrix($matrix2);
$kernel1->addKernel($kernel2);

$imagick = new \Imagick(realpath($imagePath));
$imagick->filter($kernel1);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();

}

?>


Adds a Unity Kernel to the kernel list

  • ≪ ImagickKernel::addKernel
  • ImagickKernel::fromBuiltIn ≫
  • PHP Manual
  • ImagickKernel
  • Adds a Unity Kernel to the kernel list

ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — Adds a Unity Kernel to the kernel list

説明

public ImagickKernel::addUnityKernel(float $scale): void

Adds a given amount of the 'Unity' Convolution Kernel to the given pre-scaled and normalized Kernel. This in effect adds that amount of the original image into the resulting convolution kernel. The resulting effect is to convert the defined kernels into blended soft-blurs, unsharp kernels or into sharpening kernels.

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 ImagickKernel::addUnityKernel()

<?php

function renderKernelTable($matrix) {
$output = "<table class='infoTable'>";

foreach ($matrix as $row) {
$output .= "<tr>";
foreach ($row as $cell) {
$output .= "<td style='text-align:left'>";
if ($cell === false) {
$output .= "false";
}
else {
$output .= round($cell, 3);
}
$output .= "</td>";
}
$output .= "</tr>";
}

$output .= "</table>";

return $output;
}

$matrix = [
[-1, 0, -1],
[ 0, 4, 0],
[-1, 0, -1],
];

$kernel = \ImagickKernel::fromMatrix($matrix);
$kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
$output = "Before adding unity kernel: <br/>";
$output .= renderKernelTable($kernel->getMatrix());
$kernel->addUnityKernel(0.5);
$output .= "After adding unity kernel: <br/>";
$output .= renderKernelTable($kernel->getMatrix());

$kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
$output .= "After renormalizing kernel: <br/>";
$output .= renderKernelTable($kernel->getMatrix());

echo $output;

?>

例2 ImagickKernel::addUnityKernel()

<?php
function addUnityKernel($imagePath) {

$matrix = [
[-1, 0, -1],
[ 0, 4, 0],
[-1, 0, -1],
];

$kernel = ImagickKernel::fromMatrix($matrix);

$kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
$kernel->addUnityKernel(0.5);

$imagick = new \Imagick(realpath($imagePath));
$imagick->filter($kernel);
header("Content-Type: image/jpg");
echo $imagick->getImageBlob();

}

?>


Create a kernel from a builtin in kernel

  • ≪ ImagickKernel::addUnityKernel
  • ImagickKernel::fromMatrix ≫
  • PHP Manual
  • ImagickKernel
  • Create a kernel from a builtin in kernel

ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — Create a kernel from a builtin in kernel

説明

public static ImagickKernel::fromBuiltin(int $kernelType, string $kernelString): ImagickKernel

Create a kernel from a builtin in kernel. See http://www.imagemagick.org/Usage/morphology/#kernel for examples. Currently the 'rotation' symbols are not supported. Example: $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

パラメータ

kerneltype

The type of kernel to build e.g. \Imagick::KERNEL_DIAMOND

kernelString

A string that describes the parameters e.g. "4,2.5"

戻り値

例

例1 ImagickKernel::fromBuiltin()

<?php

function renderKernel(ImagickKernel $imagickKernel) {
$matrix = $imagickKernel->getMatrix();

$imageMargin = 20;

$tileSize = 20;
$tileSpace = 4;
$shadowSigma = 4;
$shadowDropX = 20;
$shadowDropY = 0;

$radius = ($tileSize / 2) * 0.9;

$rows = count($matrix);
$columns = count($matrix[0]);

$imagickDraw = new \ImagickDraw();

$imagickDraw->setFillColor('#afafaf');
$imagickDraw->setStrokeColor('none');

$imagickDraw->translate($imageMargin, $imageMargin);
$imagickDraw->push();

ksort($matrix);

foreach ($matrix as $row) {
ksort($row);
$imagickDraw->push();
foreach ($row as $cell) {
if ($cell !== false) {
$color = intval(255 * $cell);
$colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
$imagickDraw->setFillColor($colorString);
$imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
}
$imagickDraw->translate(($tileSize + $tileSpace), 0);
}
$imagickDraw->pop();
$imagickDraw->translate(0, ($tileSize + $tileSpace));
}

$imagickDraw->pop();

$width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
$height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

$imagickDraw->push();
$imagickDraw->translate($width/2 , $height/2);
$imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
$imagickDraw->setStrokeColor('white');
$imagickDraw->circle(0, 0, $radius - 1, 0);
$imagickDraw->setStrokeColor('black');
$imagickDraw->circle(0, 0, $radius, 0);
$imagickDraw->pop();

$canvasWidth = $width + (2 * $imageMargin);
$canvasHeight = $height + (2 * $imageMargin);

$kernel = new \Imagick();
$kernel->newPseudoImage(
$canvasWidth,
$canvasHeight,
'canvas:none'
);

$kernel->setImageFormat('png');
$kernel->drawImage($imagickDraw);

/* create drop shadow on it's own layer */
$canvas = $kernel->clone();
$canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
$canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

$canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
$canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

/* composite original text_layer onto shadow_layer */
$canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
$canvas->setImageFormat('png');

return $canvas;
}

function createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
$string = '';

if ($kernelFirstTerm != false && strlen(trim($kernelFirstTerm)) != 0) {
$string .= $kernelFirstTerm;

if ($kernelSecondTerm != false && strlen(trim($kernelSecondTerm)) != 0) {
$string .= ','.$kernelSecondTerm;
if ($kernelThirdTerm != false && strlen(trim($kernelThirdTerm)) != 0) {
$string .= ','.$kernelThirdTerm;
}
}
}

$kernel = ImagickKernel::fromBuiltIn(
$kernelType,
$string
);

return $kernel;
}

function fromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
$diamondKernel = createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm);
$imagick = renderKernel($diamondKernel);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

fromBuiltin(\Imagick::KERNEL_DIAMOND, 2, false, false);

?>


Create a kernel from a 2d matrix of values

  • ≪ ImagickKernel::fromBuiltIn
  • ImagickKernel::getMatrix ≫
  • PHP Manual
  • ImagickKernel
  • Create a kernel from a 2d matrix of values

ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — Create a kernel from a 2d matrix of values

説明

public static ImagickKernel::fromMatrix(array $matrix, array $origin = ?): ImagickKernel

Create a kernel from an 2d matrix of values. Each value should either be a float (if the element should be used) or 'false' if the element should be skipped. For matrices that are odd sizes in both dimensions the origin pixel will default to the centre of the kernel. For all other kernel sizes the origin pixel must be specified.

パラメータ

array

A matrix (i.e. 2d array) of values that define the kernel. Each element should be either a float value, or FALSE if that element shouldn't be used by the kernel.

array

Which element of the kernel should be used as the origin pixel. e.g. For a 3x3 matrix specifying the origin as [2, 2] would specify that the bottom right element should be the origin pixel.

戻り値

The generated ImagickKernel.

例

例1 ImagickKernel::fromMatrix()

<?php

function renderKernel(ImagickKernel $imagickKernel) {
$matrix = $imagickKernel->getMatrix();

$imageMargin = 20;

$tileSize = 20;
$tileSpace = 4;
$shadowSigma = 4;
$shadowDropX = 20;
$shadowDropY = 0;

$radius = ($tileSize / 2) * 0.9;

$rows = count($matrix);
$columns = count($matrix[0]);

$imagickDraw = new \ImagickDraw();

$imagickDraw->setFillColor('#afafaf');
$imagickDraw->setStrokeColor('none');

$imagickDraw->translate($imageMargin, $imageMargin);
$imagickDraw->push();

ksort($matrix);

foreach ($matrix as $row) {
ksort($row);
$imagickDraw->push();
foreach ($row as $cell) {
if ($cell !== false) {
$color = intval(255 * $cell);
$colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
$imagickDraw->setFillColor($colorString);
$imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
}
$imagickDraw->translate(($tileSize + $tileSpace), 0);
}
$imagickDraw->pop();
$imagickDraw->translate(0, ($tileSize + $tileSpace));
}

$imagickDraw->pop();

$width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
$height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

$imagickDraw->push();
$imagickDraw->translate($width/2 , $height/2);
$imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
$imagickDraw->setStrokeColor('white');
$imagickDraw->circle(0, 0, $radius - 1, 0);
$imagickDraw->setStrokeColor('black');
$imagickDraw->circle(0, 0, $radius, 0);
$imagickDraw->pop();

$canvasWidth = $width + (2 * $imageMargin);
$canvasHeight = $height + (2 * $imageMargin);

$kernel = new \Imagick();
$kernel->newPseudoImage(
$canvasWidth,
$canvasHeight,
'canvas:none'
);

$kernel->setImageFormat('png');
$kernel->drawImage($imagickDraw);

/* create drop shadow on it's own layer */
$canvas = $kernel->clone();
$canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
$canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

$canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
$canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

/* composite original text_layer onto shadow_layer */
$canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
$canvas->setImageFormat('png');

return $canvas;
}

function createFromMatrix() {
$matrix = [
[0.5, 0, 0.2],
[0, 1, 0],
[0.9, 0, false],
];

$kernel = \ImagickKernel::fromMatrix($matrix);

return $kernel;
}

function fromMatrix() {
$kernel = createFromMatrix();
$imagick = renderKernel($kernel);

header("Content-Type: image/png");
echo $imagick->getImageBlob();
}

?>


Get the 2d matrix of values used in this kernel

  • ≪ ImagickKernel::fromMatrix
  • ImagickKernel::scale ≫
  • PHP Manual
  • ImagickKernel
  • Get the 2d matrix of values used in this kernel

ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — Get the 2d matrix of values used in this kernel

説明

public ImagickKernel::getMatrix(): array

Get the 2d matrix of values used in this kernel. The elements are either float for elements that are used or 'false' if the element should be skipped.

パラメータ

この関数にはパラメータはありません。

戻り値

A matrix (2d array) of the values that represent the kernel.

例

例1 ImagickKernel::getMatrix()

<?php

function renderKernelTable($matrix) {
$output = "<table class='infoTable'>";

foreach ($matrix as $row) {
$output .= "<tr>";
foreach ($row as $cell) {
$output .= "<td style='text-align:left'>";
if ($cell === false) {
$output .= "false";
}
else {
$output .= round($cell, 3);
}
$output .= "</td>";
}
$output .= "</tr>";
}

$output .= "</table>";

return $output;
}

$output = "The built-in kernel name 'ring' with parameters of '2,3.5':<br/>";
$kernel = \ImagickKernel::fromBuiltIn(
\Imagick::KERNEL_RING,
"2,3.5"
);
$matrix = $kernel->getMatrix();
$output .= renderKernelTable($matrix);

echo $output;

?>


Scales a kernel list by the given amount

  • ≪ ImagickKernel::getMatrix
  • ImagickKernel::separate ≫
  • PHP Manual
  • ImagickKernel
  • Scales a kernel list by the given amount

ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — Scales a kernel list by the given amount

説明

public ImagickKernel::scale(float $scale, int $normalizeFlag = ?): void

Scales the given kernel list by the given amount, with or without normalization of the sum of the kernel values (as per given flags). The exact behaviour of this function depends on the normalization type being used please see http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo for details.

パラメータ

scale

normalizeFlag

  • Imagick::NORMALIZE_KERNEL_NONE
  • Imagick::NORMALIZE_KERNEL_VALUE
  • Imagick::NORMALIZE_KERNEL_CORRELATE
  • Imagick::NORMALIZE_KERNEL_PERCENT

戻り値

例

例1 ImagickKernel::scale()

<?php

function renderKernelTable($matrix) {
$output = "<table class='infoTable'>";

foreach ($matrix as $row) {
$output .= "<tr>";
foreach ($row as $cell) {
$output .= "<td style='text-align:left'>";
if ($cell === false) {
$output .= "false";
}
else {
$output .= round($cell, 3);
}
$output .= "</td>";
}
$output .= "</tr>";
}

$output .= "</table>";

return $output;
}

$output = "";

$matrix = [
[-1, 0, -1],
[ 0, 4, 0],
[-1, 0, -1],
];

$kernel = \ImagickKernel::fromMatrix($matrix);
$kernelClone = clone $kernel;

$output .= "Start kernel<br/>";
$output .= renderKernelTable($kernel->getMatrix());

$output .= "Scaling with NORMALIZE_KERNEL_VALUE. The <br/>";
$kernel->scale(2, \Imagick::NORMALIZE_KERNEL_VALUE);
$output .= renderKernelTable($kernel->getMatrix());

$kernel = clone $kernelClone;
$output .= "Scaling by percent<br/>";
$kernel->scale(2, \Imagick::NORMALIZE_KERNEL_PERCENT);
$output .= renderKernelTable($kernel->getMatrix());

$matrix2 = [
[-1, -1, 1],
[ -1, false, 1],
[1, 1, 1],
];

$kernel = \ImagickKernel::fromMatrix($matrix2);
$output .= "Scaling by correlate<br/>";
$kernel->scale(1, \Imagick::NORMALIZE_KERNEL_CORRELATE);
$output .= renderKernelTable($kernel->getMatrix());

return $output;
?>


Separates a linked set of kernels and returns an array of ImagickKernels

  • ≪ ImagickKernel::scale
  • メール関連 ≫
  • PHP Manual
  • ImagickKernel
  • Separates a linked set of kernels and returns an array of ImagickKernels

ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — Separates a linked set of kernels and returns an array of ImagickKernels

説明

public ImagickKernel::separate(): array

Separates a linked set of kernels and returns an array of ImagickKernels.

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 ImagickKernel::separate()

<?php

function renderKernelTable($matrix) {

$output = "<table class='infoTable'>";
foreach ($matrix as $row) {
$output .= "<tr>";
foreach ($row as $cell) {
$output .= "<td style='text-align:left'>";
if ($cell === false) {
$output .= "false";
}
else {
$output .= round($cell, 3);
}
$output .= "</td>";
}
$output .= "</tr>";
}

$output .= "</table>";

return $output;
}

$matrix = [
[-1, 0, -1],
[ 0, 4, 0],
[-1, 0, -1],
];

$kernel = \ImagickKernel::fromMatrix($matrix);
$kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
$diamondKernel = \ImagickKernel::fromBuiltIn(
\Imagick::KERNEL_DIAMOND,
"2"
);

$kernel->addKernel($diamondKernel);

$kernelList = $kernel->separate();

$output = '';
$count = 0;
foreach ($kernelList as $kernel) {
$output .= "<br/>Kernel $count<br/>";
$output .= renderKernelTable($kernel->getMatrix());
$count++;
}

return $output;

?>


メール関連

  • IMAP — IMAP、POP3 および NNTP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • IMAP 関数
    • IMAP\Connection — IMAP\Connection クラス
  • メール
    • はじめに
    • インストール/設定
    • メール 関数
  • Mailparse
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Mailparse 関数


IMAP、POP3 および NNTP

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • IMAP 関数
    • imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する
    • imap_alerts — 発生した IMAP 警告メッセージを返す
    • imap_append — 指定されたメールボックスに文字列メッセージを追加する
    • imap_base64 — BASE64 でエンコードされたテキストをデコードする
    • imap_binary — 8 ビット文字列を base64 文字列に変換する
    • imap_body — メッセージ本文を読む
    • imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む
    • imap_check — 現在のメールボックスをチェックする
    • imap_clearflag_full — メッセージのフラグをクリアする
    • imap_close — IMAP ストリームをクローズする
    • imap_create — imap_createmailbox のエイリアス
    • imap_createmailbox — 新しいメールボックスを作る
    • imap_delete — 現在のメールボックスから削除するメッセージに印を付ける
    • imap_deletemailbox — メールボックスを削除する
    • imap_errors — 発生したすべての IMAP エラーを返す
    • imap_expunge — 削除用にマークされたすべてのメッセージを削除する
    • imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む
    • imap_fetchbody — メッセージ本文中の特定のセクションを取り出す
    • imap_fetchheader — メッセージのヘッダを返す
    • imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します
    • imap_fetchstructure — 特定のメッセージの構造を読み込む
    • imap_fetchtext — imap_body のエイリアス
    • imap_gc — IMAP キャッシュをクリアする
    • imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する
    • imap_get_quotaroot — ユーザー単位のクォータ設定を取得する
    • imap_getacl — 与えられたメールボックスの ACL を取得する
    • imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す
    • imap_getsubscribed — 購読中の全メールボックスの一覧を取得する
    • imap_header — imap_headerinfo のエイリアス
    • imap_headerinfo — メッセージヘッダを読み込む
    • imap_headers — メールボックス内のすべてのメッセージのヘッダを返す
    • imap_is_open — IMAP ストリームがまだ有効かを調べる
    • imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す
    • imap_list — メールボックスのリストを読み込む
    • imap_listmailbox — imap_list のエイリアス
    • imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す
    • imap_listsubscribed — imap_lsub のエイリアス
    • imap_lsub — 購読しているすべてのメールボックスの一覧を得る
    • imap_mail — e-mail メッセージを送信する
    • imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する
    • imap_mail_copy — 指定されたメッセージをメールボックスにコピーする
    • imap_mail_move — 指定されたメッセージをメールボックスに移動する
    • imap_mailboxmsginfo — 現在のメールボックスに関する情報を得る
    • imap_mime_header_decode — MIME ヘッダ要素をデコードする
    • imap_msgno — 指定した UID のメッセージ番号を返す
    • imap_mutf7_to_utf8 — 修正UTF-7文字列をUTF-8にデコードする
    • imap_num_msg — 現在のメールボックスのメッセージ数を取得する
    • imap_num_recent — 現在のメールボックスにある新規メッセージ数を取得する
    • imap_open — メールボックスへの IMAP ストリームをオープンする
    • imap_ping — IMAP ストリームがアクティブかどうかを調べる
    • imap_qprint — quoted-printable 文字列を 8 ビット文字列に変換する
    • imap_rename — imap_renamemailbox のエイリアス
    • imap_renamemailbox — メールボックスの名前を変更する
    • imap_reopen — 新規メールボックスへの IMAP ストリームを再度オープンする
    • imap_rfc822_parse_adrlist — アドレス文字列を解釈します
    • imap_rfc822_parse_headers — 文字列からメールヘッダを解釈する
    • imap_rfc822_write_address — 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す
    • imap_savebody — 指定した本文部をファイルに保存する
    • imap_scan — imap_listscan のエイリアス
    • imap_scanmailbox — imap_listscan のエイリアス
    • imap_search — 指定した検索条件にマッチするメッセージを配列として返す
    • imap_set_quota — 指定したメールボックスにクォータを設定する
    • imap_setacl — 指定したメールボックスの ACL を設定する
    • imap_setflag_full — メッセージにフラグをセットする
    • imap_sort — メッセージヘッダの配列をソートする
    • imap_status — 現在のメールボックス以外のメールボックスのステータス情報を返す
    • imap_subscribe — メールボックスを購読する
    • imap_thread — スレッド化したメッセージのツリーを返す
    • imap_timeout — imap タイムアウトを設定あるいは取得する
    • imap_uid — 指定したメッセージシーケンス番号の UID を返す
    • imap_undelete — 削除マークがついているメッセージのマークをはずす
    • imap_unsubscribe — メールボックスの購読をやめる
    • imap_utf7_decode — 修正版 UTF-7 エンコードされた文字列をデコードする
    • imap_utf7_encode — ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する
    • imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する
    • imap_utf8_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする
  • IMAP\Connection — IMAP\Connection クラス


はじめに

これらの関数は、IMAP プロトコルのほかに NNTP や POP3、 そしてローカルのメールボックスへのアクセスもサポートします。

しかし、IMAP 関数の中には POP プロトコルでは正常に動作しないものがあることに注意しましょう。

警告

IMAP 拡張モジュールはスレッドセーフではありません。 よって、ZTS が有効なPHPで使うべきではありません。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • IMAP
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

この拡張モジュールを使うには、 c-client ライブラリがインストールされている必要があります。 » https://github.com/uw-imap/imap から 最新版を入手し、コンパイルしてください。

IMAP のソースファイルをシステムの include ディレクトリに直接コピー しないことが大切です。そのようなことをすると既存のファイルと衝突を 引き起こす可能性があります。そのかわりにシステムの include ディレクトリの 下に新しいディレクトリ（例： /usr/local/imap-2000b/ 場所や名前は、あなたのシステムの設定や IMAP のバージョンに依存します）を作成し、 この新規ディレクトリの下に lib/、include/ という新しいディレクトリを作成します。IMAP ソースツリーの c-client ディレクトリからすべての *.h ファイルを include/ に、そしてすべての *.c ファイルを lib/ にコピーします。 IMAP をコンパイルすると、c-client.a というファイルが つくられます。これも lib/ ディレクトリにコピーし、 名前を libc-client.a に変更してください。

注意:

c-client ライブラリを SSL や Kerberos のサポートつきでビルド するには、パッケージとともに提供されるドキュメントを参照ください。

注意: Mandrake Linux では、IMAP ライブラリ（libc-client.a） が Kerberos のサポートなしでコンパイルされています。また、SSL 対応バージョン（client-PHP4.a）が別に インストールされます。Kerberos サポートを使用するには、これらの ライブラリを再コンパイルする必要があります。


インストール手順

これらの関数を動作させるには、--with-imap[=DIR] を指定して PHP をコンパイルする必要があります。DIR は c-client インストール時のプレフィックスです。上の例のような場合には --with-imap=/usr/local/imap-2000b を指定します。この場所は、上の指示にしたがってあなたが作成したディレクトリの 場所に依存します。Windows ユーザーは、php.ini で php_imap.dll DLL を有効にします。

注意: c-client の設定によっては、これ以外に --with-imap-ssl=/path/to/openssl/ や --with-kerberos=/path/to/kerberos といったオプションを PHP の configure で指定する必要があります。

警告

IMAP 拡張モジュールはスレッドセーフではありません。 よって、ZTS が有効なPHPで使うべきではありません。

警告

IMAP、recode、 YAZ 拡張モジュールは、組み合わせて使用することはできません。 これは、これらすべてが同一の内部シンボルを使用しているためです。 注意: Yaz 2.0 以降ではこの問題は発生しません。


実行時設定

php.ini の設定により動作が変化します。

IMAP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
imap.enable_insecure_rsh | "0" | INI_SYSTEM | PHP 7.1.25、7.2.13、7.3.0 以降で利用可能です。それより前のバージョンでは、これは暗黙のうちに有効になっていました。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

imap.enable_insecure_rsh bool

このオプションを無効にしていない場合、サーバーとの接続を確立する際に rsh コマンドや ssh コマンドを実行する可能性があります。

警告

rsh コマンドや ssh コマンドにメールボックス名を渡す際に、 PHP や IMAP ライブラリは何もフィルタリングをしません。 信頼できないデータをこの関数に渡すのであれば、このオプションを無効にしておかないと危険です。


リソース型

PHP 8.1.0 より前のバージョンでは、 この拡張モジュールは imap_open() がオープンした IMAP ストリームを表す、 imap リソースを定義していました。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

NIL (int)
PHP 8.1.0 以降は非推奨。
OP_DEBUG (int)
OP_READONLY (int)
メールボックスを読み込み専用で開きます。
OP_ANONYMOUS (int)
ニュースで .newsrc を使用せず、更新も行いません （NNTP のみ）。
OP_SHORTCACHE (int)
OP_SILENT (int)
OP_PROTOTYPE (int)
OP_HALFOPEN (int)
IMAP や NNTP において、接続はオープンするがメールボックスを開きません。
OP_EXPUNGE (int)
OP_SECURE (int)
CL_EXPUNGE (int)
imap_close() のコール時に、メールボックスを 閉じる前に中身を削除します。
FT_UID (int)
パラメータは UID です。
FT_PEEK (int)
まだ設定されていない場合に \Seen フラグを設定しません。
FT_NOT (int)
FT_INTERNAL (int)
返される文字列は内部フォーマットであり、CRLF に正規化しません。
FT_PREFETCHTEXT (int)
ST_UID (int)
シーケンスの引数に、番号ではなく UID を含んでいます。
ST_SILENT (int)
ST_SET (int)
CP_UID (int)
シーケンス番号が UID を含んでいます。
CP_MOVE (int)
imap_mail_copy() でコピーを行った後に 現在のメールボックスからメッセージを削除します。
SE_UID (int)
シーケンス番号のかわりに UID を返します。
SE_FREE (int)
SE_NOPREFETCH (int)
検索されたメッセージを事前にフェッチすることはありません。
SO_FREE (int)
SO_NOSERVER (int)
SA_MESSAGES (int)
SA_RECENT (int)
SA_UNSEEN (int)
SA_UIDNEXT (int)
SA_UIDVALIDITY (int)
SA_ALL (int)
LATT_NOINFERIORS (int)
このメールボックスには「子供」はいません（このメールボックスの配下には メールボックスはありません）。
LATT_NOSELECT (int)
これは単なるコンテナであり、メールボックスではありません。 オープンすることはできません。
LATT_MARKED (int)
このメールボックスはマークされています。UW-IMAPD でのみ使用されます。
LATT_UNMARKED (int)
このメールボックスはマークされていません。UW-IMAPD でのみ使用されます。
LATT_REFERRAL (int)
このコンテナはリモートのメールボックスへの関連を持ちます。
LATT_HASCHILDREN (int)
このメールボックスは、選択可能な子を持ちます。
LATT_HASNOCHILDREN (int)
このメールボックスは、選択可能な子を持ちません。
SORTDATE (int)
imap_sort() のソート条件。 メッセージの日付でソートします。
SORTARRIVAL (int)
imap_sort() のソート条件。 到着日でソートします。
SORTFROM (int)
imap_sort() のソート条件。 メールボックスの最初の From アドレスでソートします。
SORTSUBJECT (int)
imap_sort() のソート条件。 メッセージの表題でソートします。
SORTTO (int)
imap_sort() のソート条件。 メールボックスの最初の To アドレスでソートします。
SORTCC (int)
imap_sort() のソート条件。 メールボックスの最初の Co アドレスでソートします。
SORTSIZE (int)
imap_sort() のソート条件。 メッセージのサイズ（バイト単位）でソートします。
TYPETEXT (int)
最初の body 部の型: unformatted text
TYPEMULTIPART (int)
最初の body 部の型: multiple part
TYPEMESSAGE (int)
最初の body 部の型: encapsulated message
TYPEAPPLICATION (int)
最初の body 部の型: application data
TYPEAUDIO (int)
最初の body 部の型: audio
TYPEIMAGE (int)
最初の body 部の型: static image
TYPEVIDEO (int)
最初の body 部の型: video
TYPEMODEL (int)
最初の body 部の型: model
TYPEOTHER (int)
最初の body 部の型: unknown
ENC7BIT (int)
body 部のエンコーディング: 7 bit SMTP semantic data
ENC8BIT (int)
body 部のエンコーディング: 8 bit SMTP semantic data
ENCBINARY (int)
body 部のエンコーディング: 8 bit binary data
ENCBASE64 (int)
body 部のエンコーディング: base-64 encoded data
ENCQUOTEDPRINTABLE (int)
body 部のエンコーディング: human-readable 8-as-7 bit data
ENCOTHER (int)
body 部のエンコーディング: unknown
IMAP_OPENTIMEOUT (int)
IMAP_READTIMEOUT (int)
IMAP_WRITETIMEOUT (int)
IMAP_CLOSETIMEOUT (int)
IMAP_GC_ELT (int)
ガベージコレクタでメッセージキャッシュ要素を消去します。
IMAP_GC_ENV (int)
ガベージコレクタでエンベロープおよびボディを消去します。
IMAP_GC_TEXTS (int)
ガベージコレクタでテキストを消去します。


IMAP 関数

参考

この文書では、提供される関数に関する全ての話題の詳細について立ち入ることは できません。より詳細な情報については、c-client ライブラリのソースに 付属するドキュメント (docs/internal.txt) および以下の RFC ドキュメントで提供されています。

  • » RFC2821: Simple Mail Transfer Protocol (SMTP).
  • » RFC2822: Standard for ARPA internet text messages.
  • » RFC2060: Internet Message Access Protocol (IMAP) Version 4rev1.
  • » RFC1939: Post Office Protocol Version 3 (POP3).
  • » RFC977: Network News Transfer Protocol (NNTP).
  • » RFC2076: Common Internet Message Headers.
  • » RFC2045 , » RFC2046 , » RFC2047 , » RFC2048 & » RFC2049: Multipurpose Internet Mail Extensions (MIME).
詳しい概観については、David Wood による書籍 » Programming Internet Email や Dianna Mullet と Kevin Mullet による » Managing IMAP でも得ることができます。

目次

  • imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する
  • imap_alerts — 発生した IMAP 警告メッセージを返す
  • imap_append — 指定されたメールボックスに文字列メッセージを追加する
  • imap_base64 — BASE64 でエンコードされたテキストをデコードする
  • imap_binary — 8 ビット文字列を base64 文字列に変換する
  • imap_body — メッセージ本文を読む
  • imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む
  • imap_check — 現在のメールボックスをチェックする
  • imap_clearflag_full — メッセージのフラグをクリアする
  • imap_close — IMAP ストリームをクローズする
  • imap_create — imap_createmailbox のエイリアス
  • imap_createmailbox — 新しいメールボックスを作る
  • imap_delete — 現在のメールボックスから削除するメッセージに印を付ける
  • imap_deletemailbox — メールボックスを削除する
  • imap_errors — 発生したすべての IMAP エラーを返す
  • imap_expunge — 削除用にマークされたすべてのメッセージを削除する
  • imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む
  • imap_fetchbody — メッセージ本文中の特定のセクションを取り出す
  • imap_fetchheader — メッセージのヘッダを返す
  • imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します
  • imap_fetchstructure — 特定のメッセージの構造を読み込む
  • imap_fetchtext — imap_body のエイリアス
  • imap_gc — IMAP キャッシュをクリアする
  • imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する
  • imap_get_quotaroot — ユーザー単位のクォータ設定を取得する
  • imap_getacl — 与えられたメールボックスの ACL を取得する
  • imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す
  • imap_getsubscribed — 購読中の全メールボックスの一覧を取得する
  • imap_header — imap_headerinfo のエイリアス
  • imap_headerinfo — メッセージヘッダを読み込む
  • imap_headers — メールボックス内のすべてのメッセージのヘッダを返す
  • imap_is_open — IMAP ストリームがまだ有効かを調べる
  • imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す
  • imap_list — メールボックスのリストを読み込む
  • imap_listmailbox — imap_list のエイリアス
  • imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す
  • imap_listsubscribed — imap_lsub のエイリアス
  • imap_lsub — 購読しているすべてのメールボックスの一覧を得る
  • imap_mail — e-mail メッセージを送信する
  • imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する
  • imap_mail_copy — 指定されたメッセージをメールボックスにコピーする
  • imap_mail_move — 指定されたメッセージをメールボックスに移動する
  • imap_mailboxmsginfo — 現在のメールボックスに関する情報を得る
  • imap_mime_header_decode — MIME ヘッダ要素をデコードする
  • imap_msgno — 指定した UID のメッセージ番号を返す
  • imap_mutf7_to_utf8 — 修正UTF-7文字列をUTF-8にデコードする
  • imap_num_msg — 現在のメールボックスのメッセージ数を取得する
  • imap_num_recent — 現在のメールボックスにある新規メッセージ数を取得する
  • imap_open — メールボックスへの IMAP ストリームをオープンする
  • imap_ping — IMAP ストリームがアクティブかどうかを調べる
  • imap_qprint — quoted-printable 文字列を 8 ビット文字列に変換する
  • imap_rename — imap_renamemailbox のエイリアス
  • imap_renamemailbox — メールボックスの名前を変更する
  • imap_reopen — 新規メールボックスへの IMAP ストリームを再度オープンする
  • imap_rfc822_parse_adrlist — アドレス文字列を解釈します
  • imap_rfc822_parse_headers — 文字列からメールヘッダを解釈する
  • imap_rfc822_write_address — 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す
  • imap_savebody — 指定した本文部をファイルに保存する
  • imap_scan — imap_listscan のエイリアス
  • imap_scanmailbox — imap_listscan のエイリアス
  • imap_search — 指定した検索条件にマッチするメッセージを配列として返す
  • imap_set_quota — 指定したメールボックスにクォータを設定する
  • imap_setacl — 指定したメールボックスの ACL を設定する
  • imap_setflag_full — メッセージにフラグをセットする
  • imap_sort — メッセージヘッダの配列をソートする
  • imap_status — 現在のメールボックス以外のメールボックスのステータス情報を返す
  • imap_subscribe — メールボックスを購読する
  • imap_thread — スレッド化したメッセージのツリーを返す
  • imap_timeout — imap タイムアウトを設定あるいは取得する
  • imap_uid — 指定したメッセージシーケンス番号の UID を返す
  • imap_undelete — 削除マークがついているメッセージのマークをはずす
  • imap_unsubscribe — メールボックスの購読をやめる
  • imap_utf7_decode — 修正版 UTF-7 エンコードされた文字列をデコードする
  • imap_utf7_encode — ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する
  • imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する
  • imap_utf8_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする


8 ビット文字列を quoted-printable 文字列に変換する

  • ≪ IMAP 関数
  • imap_alerts ≫
  • PHP Manual
  • IMAP 関数
  • 8 ビット文字列を quoted-printable 文字列に変換する

imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する

説明

imap_8bit(string $string): string|false

(» RFC2045, section 6.7 に基づき) 8 ビット文字列を quoted-printable 文字列に変換します。

パラメータ

string

変換する 8 ビット文字列。

戻り値

quoted-printable 文字列を返します。 失敗した場合に false を返します

参考

  • imap_qprint() - quoted-printable 文字列を 8 ビット文字列に変換する


発生した IMAP 警告メッセージを返す

  • ≪ imap_8bit
  • imap_append ≫
  • PHP Manual
  • IMAP 関数
  • 発生した IMAP 警告メッセージを返す

imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — 発生した IMAP 警告メッセージを返す

説明

imap_alerts(): array|false

直近に imap_alerts() をコールして以来、 またはページ処理を開始して以来生成された 全 IMAP 警告メッセージの配列を返します。

imap_alerts() がコールされた場合、 その処理後に警告のスタックはクリアされます。IMAP の仕様では、 これらのメッセージをユーザーに渡すことが規定されています。

パラメータ

この関数にはパラメータはありません。

戻り値

全ての IMAP 警告メッセージの配列、あるいは警告メッセージが発生していない場合は false を返します。

参考

  • imap_errors() - 発生したすべての IMAP エラーを返す


指定されたメールボックスに文字列メッセージを追加する

  • ≪ imap_alerts
  • imap_base64 ≫
  • PHP Manual
  • IMAP 関数
  • 指定されたメールボックスに文字列メッセージを追加する

imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — 指定されたメールボックスに文字列メッセージを追加する

説明

imap_append(
IMAP\Connection $imap,
string $folder,
string $message,
?string $options = null,
?string $internal_date = null
): bool

指定したメールボックス folder に文字列メッセージ message を追加します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

folder

メールボックスの名前。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

message

追加したいメッセージを表す文字列。

Cyrus IMAP サーバーと通信する際には、改行コードとして "\n" のかわりに "\r\n" を使用する必要があります。さもなくば、操作は失敗します。

options

指定した場合は、 options もその folder に書きこまれます。

internal_date

このパラメータが設定されていると、追加したメッセージに INTERNALDATE を設定します。 このパラメータは、rfc2060 の日付時刻値の仕様を満たす文字列でなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | options と internal_date は、nullable になりました。

例

例1 imap_append() の例

<?php
$imap = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

$check = imap_check($imap);
echo "Msg Count before append: ". $check->Nmsgs . "\n";

imap_append($imap, "{imap.example.org}INBOX.Drafts"
, "From: me@example.com\r\n"
. "To: you@example.com\r\n"
. "Subject: test\r\n"
. "\r\n"
. "this is a test message, please ignore\r\n"
);

$check = imap_check($imap);
echo "Msg Count after append : ". $check->Nmsgs . "\n";

imap_close($imap);
?>


BASE64 でエンコードされたテキストをデコードする

  • ≪ imap_append
  • imap_binary ≫
  • PHP Manual
  • IMAP 関数
  • BASE64 でエンコードされたテキストをデコードする

imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — BASE64 でエンコードされたテキストをデコードする

説明

imap_base64(string $string): string|false

BASE64 でエンコードされたテキスト string をデコードします。

パラメータ

string

エンコードされたテキスト。

戻り値

デコードしたメッセージを文字列で返します。 失敗した場合に false を返します

参考

  • imap_binary() - 8 ビット文字列を base64 文字列に変換する
  • base64_encode() - MIME base64 方式でデータをエンコードする
  • base64_decode() - MIME base64 方式によりエンコードされたデータをデコードする
  • » RFC2045, Section 6.8


8 ビット文字列を base64 文字列に変換する

  • ≪ imap_base64
  • imap_body ≫
  • PHP Manual
  • IMAP 関数
  • 8 ビット文字列を base64 文字列に変換する

imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — 8 ビット文字列を base64 文字列に変換する

説明

imap_binary(string $string): string|false

（» RFC2045, Section 6.8 に基づき）8 ビット文字列を base64 文字列に変換します。

パラメータ

string

8 ビット文字列。

戻り値

base64 エンコードされた文字列を返します。 失敗した場合に false を返します

参考

  • imap_base64() - BASE64 でエンコードされたテキストをデコードする


メッセージ本文を読む

  • ≪ imap_binary
  • imap_bodystruct ≫
  • PHP Manual
  • IMAP 関数
  • メッセージ本文を読む

imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — メッセージ本文を読む

説明

imap_body(IMAP\Connection $imap, int $message_num, int $flags = 0): string|false

imap_body() は、現在のメールボックスにある message_num 番目のメッセージの本文を返します。

imap_body() は、メッセージの本文と全く同じ コピーのみを返します。マルチパート MIME エンコードされたメッセージの 一部を展開するには、その構造を解析するために imap_fetch_structure() を使用し、単一の部分要素の コピーを展開する際には、 imap_fetchbody() を使用する必要があります。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

flags

オプションの flags はビットマスクであり、 以下の要素の組み合わせとなります。

  • FT_UID - message_num は UID です
  • FT_PEEK - 既に設定されていない場合、\Seen フラグを設定しない
  • FT_INTERNAL - 内部フォーマットで文字列を返す。 CRLF に正規化しない。

戻り値

指定したメッセージの本文を文字列で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。


指定したメッセージの指定した body セクションの構造を読み込む

  • ≪ imap_body
  • imap_check ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメッセージの指定した body セクションの構造を読み込む

imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む

説明

imap_bodystruct(IMAP\Connection $imap, int $message_num, string $section): stdClass|false

指定したメッセージの指定した body セクションの構造を読み込みます。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

section

読み込む body セクション。

戻り値

オブジェクトの情報を返します。 失敗した場合に false を返します。 オブジェクトの構造やプロパティについての詳細は imap_fetchstructure() を参照ください。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_fetchstructure() - 特定のメッセージの構造を読み込む


現在のメールボックスをチェックする

  • ≪ imap_bodystruct
  • imap_clearflag_full ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスをチェックする

imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — 現在のメールボックスをチェックする

説明

imap_check(IMAP\Connection $imap): stdClass|false

現在のメールボックスに関する情報を調べます。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

以下のプロパティをもつオブジェクトの情報を返します。

  • Date - 現在のシステム時刻を » RFC2822 にしたがってフォーマットしたもの。
  • Driver - メールボックスにアクセスする際に使用するプロトコル: POP3、IMAP、NNTP
  • Mailbox - メールボックスの名前。
  • Nmsgs - メールボックス内のメッセージの数。
  • Recent - メールボックス内の新規メッセージの数。

失敗した場合には false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_check() の例

<?php

$imap = imap_check($imap_stream);
var_dump($imap);

?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)(5) {
  ["Date"]=>
  string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)"
  ["Driver"]=>
  string(4) "imap"
  ["Mailbox"]=>
  string(54)
  "{www.example.com:143/imap/user="foo@example.com"}INBOX"
  ["Nmsgs"]=>
  int(1)
  ["Recent"]=>
  int(0)
}


メッセージのフラグをクリアする

  • ≪ imap_check
  • imap_close ≫
  • PHP Manual
  • IMAP 関数
  • メッセージのフラグをクリアする

imap_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — メッセージのフラグをクリアする

説明

imap_clearflag_full(
IMAP\Connection $imap,
string $sequence,
string $flag,
int $options = 0
): true

この関数は、指定したシーケンス sequence のメッセージのフラグから、指定したフラグ flag を削除します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

sequence

メッセージ番号のシーケンス。 X,Y のようにメッセージを列挙したり、 X:Y のようにしてその間のすべてのメッセージを指定したりできます。

flag

削除可能なフラグは "\\Seen"、 "\\Answered"、"\\Flagged"、"\\Deleted" および "\\Draft" です (» RFC2060 で定義されています)。

options

オプション options はビットマスクであり、 以下の組み合わせとなります。

  • ST_UID - シーケンス引数はシーケンス番号の代わりに UID を含みます。

戻り値

常に true を返します。

エラー / 例外

options が無効な場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | options が無効な値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、false を返していました。

参考

  • imap_setflag_full() - メッセージにフラグをセットする


IMAP ストリームをクローズする

  • ≪ imap_clearflag_full
  • imap_create ≫
  • PHP Manual
  • IMAP 関数
  • IMAP ストリームをクローズする

imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — IMAP ストリームをクローズする

説明

imap_close(IMAP\Connection $imap, int $flags = 0): true

IMAP ストリームをクローズします。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

flags

CL_EXPUNGE を指定した場合、メールボックスを閉じる前に暗黙のうちに 削除マークがついた全てのメッセージを削除します。 imap_expunge() を使用して、同じことを行うこともできます。

戻り値

常に true を返します。

エラー / 例外

flags が無効な場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | flags が無効な値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、false を返していました。

参考

  • imap_open() - メールボックスへの IMAP ストリームをオープンする


imap_createmailbox のエイリアス

  • ≪ imap_close
  • imap_createmailbox ≫
  • PHP Manual
  • IMAP 関数
  • imap_createmailbox のエイリアス

imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — imap_createmailbox() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_createmailbox().


新しいメールボックスを作る

  • ≪ imap_create
  • imap_delete ≫
  • PHP Manual
  • IMAP 関数
  • 新しいメールボックスを作る

imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — 新しいメールボックスを作る

説明

imap_createmailbox(IMAP\Connection $imap, string $mailbox): bool

imap_createmailbox() は mailbox で指定された新しいメールボックスを作成します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。 この名前に国際化文字を含む場合には、 imap_utf7_encode() でエンコードする必要があります。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_createmailbox() example

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$name1 = "phpnewbox";
$name2 = imap_utf7_encode("phpnewbox"); // phpnewb&w7Y-x

$newname = $name1;

echo "Newname will be '$name1'<br />\n";

// ここでは inbox フォルダ内に新しいメールボックス "phptestbox" を
// 作成し、その後でメールボックスの状態を確認し、最後にそれを削除して
// もとの状態に戻します。

if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
$status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
if ($status) {
echo "your new mailbox '$name1' has the following status:<br />\n";
echo "Messages: " . $status->messages . "<br />\n";
echo "Recent: " . $status->recent . "<br />\n";
echo "Unseen: " . $status->unseen . "<br />\n";
echo "UIDnext: " . $status->uidnext . "<br />\n";
echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";

if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
echo "renamed new mailbox from '$name1' to '$name2'<br />\n";
$newname = $name2;
} else {
echo "imap_renamemailbox on new mailbox failed: " . imap_last_error() . "<br />\n";
}
} else {
echo "imap_status on new mailbox failed: " . imap_last_error() . "<br />\n";
}

if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
echo "new mailbox removed to restore initial state<br />\n";
} else {
echo "imap_deletemailbox on new mailbox failed: " . implode("<br />\n", imap_errors()) . "<br />\n";
}

} else {
echo "could not create new mailbox: " . implode("<br />\n", imap_errors()) . "<br />\n";
}

imap_close($mbox);
?>

参考

  • imap_renamemailbox() - メールボックスの名前を変更する
  • imap_deletemailbox() - メールボックスを削除する


現在のメールボックスから削除するメッセージに印を付ける

  • ≪ imap_createmailbox
  • imap_deletemailbox ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスから削除するメッセージに印を付ける

imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — 現在のメールボックスから削除するメッセージに印を付ける

説明

imap_delete(IMAP\Connection $imap, string $message_nums, int $flags = 0): true

message_nums が指すメッセージに 削除予定のマークをします。削除マークを付けられたメッセージは、 imap_expunge() がコールされるか imap_close() に CL_EXPUNGE を付けてコールされるかのどちらかが行われるまでメールボックスに残ったままになります。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_nums

IMAP4 形式のシーケンスフォーマット ("n", "n:m", またはそれらをカンマで区切ったもの) で表現された、ひとつ以上のメッセージを表す文字列。

flags

FT_UID を指定すると、 引数 message_nums を UID として処理することを関数に指示できます。

戻り値

常に true を返します。

エラー / 例外

flags が無効な場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | flags が無効な場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、false を返していました。

例

例1 imap_delete() の例

<?php

$mbox = imap_open("{imap.example.org}INBOX", "username", "password")
or die("接続できません: " . imap_last_error());

$check = imap_mailboxmsginfo($mbox);
echo "Messages before delete: " . $check->Nmsgs . "<br />\n";

imap_delete($mbox, 1);

$check = imap_mailboxmsginfo($mbox);
echo "Messages after delete: " . $check->Nmsgs . "<br />\n";

imap_expunge($mbox);

$check = imap_mailboxmsginfo($mbox);
echo "Messages after expunge: " . $check->Nmsgs . "<br />\n";

imap_close($mbox);
?>

注意

注意:

IMAP メールボックスは、コネクション間で保存可能なメッセージフラグを持っていません。 そのため、削除マークをつけたメッセージが本当に削除されたことを保証するためには、 同一の接続内で imap_expunge() をコールする必要があります。

参考

  • imap_undelete() - 削除マークがついているメッセージのマークをはずす
  • imap_expunge() - 削除用にマークされたすべてのメッセージを削除する
  • imap_close() - IMAP ストリームをクローズする


メールボックスを削除する

  • ≪ imap_delete
  • imap_errors ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスを削除する

imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — メールボックスを削除する

説明

imap_deletemailbox(IMAP\Connection $imap, string $mailbox): bool

指定したメールボックス mailbox を削除します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_createmailbox() - 新しいメールボックスを作る
  • imap_renamemailbox() - メールボックスの名前を変更する
  • mbox の書式については imap_open() - メールボックスへの IMAP ストリームをオープンする


発生したすべての IMAP エラーを返す

  • ≪ imap_deletemailbox
  • imap_expunge ≫
  • PHP Manual
  • IMAP 関数
  • 発生したすべての IMAP エラーを返す

imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — 発生したすべての IMAP エラーを返す

説明

imap_errors(): array|false

ページのリクエストの間かエラースタックがリセットされて以来 生じた全ての IMAP エラー (存在すれば) を返します。

imap_errors() がコールされると、 処理の終了後にエラースタックがクリアされます。

パラメータ

この関数にはパラメータはありません。

戻り値

この関数は、最後に imap_errors() コールを行ってから、またはそのページの処理を開始してから 発生した全ての IMAP エラーメッセージの配列を返します。 エラーメッセージが存在しない場合には false を返します。

参考

  • imap_last_error() - ページリクエスト時に生じた直近の IMAP エラーを返す
  • imap_alerts() - 発生した IMAP 警告メッセージを返す


削除用にマークされたすべてのメッセージを削除する

  • ≪ imap_errors
  • imap_fetch_overview ≫
  • PHP Manual
  • IMAP 関数
  • 削除用にマークされたすべてのメッセージを削除する

imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — 削除用にマークされたすべてのメッセージを削除する

説明

imap_expunge(IMAP\Connection $imap): true

imap_delete()、imap_mail_move()、 あるいは imap_setflag_full() で削除用マークを設定されたすべてのメッセージを削除します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。


指定したメッセージのヘッダ情報の概要を読む

  • ≪ imap_expunge
  • imap_fetchbody ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメッセージのヘッダ情報の概要を読む

imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む

説明

imap_fetch_overview(IMAP\Connection $imap, string $sequence, int $flags = 0): array|false

この関数は、指定された sequence のメールヘッダを取得してその内容の概要を返します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

sequence

メッセージのシーケンスを指定します。 X,Y 形式で列挙したり、 X:Y 形式でその範囲内のすべてのメッセージを取得したりできます。

flags

sequence には、メッセージのインデックスか、もし flags に FT_UID が含まれている場合は UID が含まれます。

戻り値

オブジェクトの配列を返します。各要素が、 それぞれひとつのメッセージのヘッダを表します。 オブジェクトで定義されるのは、存在するプロパティのみです。 以下のプロパティがあります。

  • subject - メッセージの題名(subject)
  • from - 送信者
  • to - 受信者
  • date - 送信日
  • message_id - Message-ID
  • references - このメッセージ ID への参照です
  • in_reply_to - このメッセージ ID への返信です
  • size - サイズ（バイト数）
  • uid - メールボックスにおけるこのメッセージの UID
  • msgno - メールボックスにおけるこのメッセージのシーケンス番号
  • recent - このメッセージには recent フラグが立てられています
  • flagged - フラグが立てられています
  • answered - 返信済みフラグが立てられています
  • deleted - 削除フラグが立てられています
  • seen - 既読フラグが立てられています
  • draft - 草稿フラグが立てられています
  • udate - 受信日時の UNIX タイムスタンプ
この関数は、失敗した時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_fetch_overview() の例

<?php
$mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
or die("接続できません: " . imap_last_error());

$MC = imap_check($mbox);

// INBOX のすべてのメッセージの概要を取得します
$result = imap_fetch_overview($mbox,"1:{$MC->Nmsgs}",0);
foreach ($result as $overview) {
echo "#{$overview->msgno} ({$overview->date}) - From: {$overview->from}
{$overview->subject}\n";
}
imap_close($mbox);
?>

参考

  • imap_fetchheader() - メッセージのヘッダを返す


メッセージ本文中の特定のセクションを取り出す

  • ≪ imap_fetch_overview
  • imap_fetchheader ≫
  • PHP Manual
  • IMAP 関数
  • メッセージ本文中の特定のセクションを取り出す

imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — メッセージ本文中の特定のセクションを取り出す

説明

imap_fetchbody(
IMAP\Connection $imap,
int $message_num,
string $section,
int $flags = 0
): string|false

指定されたメッセージ本文中の特定のセクションを取得します。 本文パートは、この関数ではデコードされません。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

section

パート番号。ピリオドで区切られた整数文字列を指定します。 これは、IMAP4 仕様における本文パートのリストへのインデックスとなります。

flags

ビットマスクであり、以下の組合わせとなります。

  • FT_UID - message_numは UID である
  • FT_PEEK - 既に設定されていない場合、 \Seen フラグを設定しない
  • FT_INTERNAL - 内部フォーマットで文字列を返す。CRLF に正規化しない。

戻り値

指定されたメッセージ本文中の特定のセクションをテキスト文字列で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_savebody() - 指定した本文部をファイルに保存する
  • imap_fetchstructure() - 特定のメッセージの構造を読み込む


メッセージのヘッダを返す

  • ≪ imap_fetchbody
  • imap_fetchmime ≫
  • PHP Manual
  • IMAP 関数
  • メッセージのヘッダを返す

imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — メッセージのヘッダを返す

説明

imap_fetchheader(IMAP\Connection $imap, int $message_num, int $flags = 0): string|false

指定したメッセージについて、フィルタリング されていない完全な » RFC2822 フォーマットのヘッダをテキスト文字列として取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

flags

オプション flags は次のようになります。

  • FT_UID - 引数 message_num は UID です。
  • FT_INTERNAL - 返される文字列は "internal" フォーマットです。CRLF に正規化しません。
  • FT_PREFETCHTEXT - RFC822.TEXT を、 同時に事前に取得しておく必要があります。これは、メッセージテキスト 全体を取得したい場合（例:「ローカルファイルに保存する」操作）に IMAP 接続で余分な RTT を回避します。

戻り値

指定したメッセージのヘッダをテキスト文字列で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_fetch_overview() - 指定したメッセージのヘッダ情報の概要を読む


メッセージの特定のセクションに対する MIME ヘッダを取り出します

  • ≪ imap_fetchheader
  • imap_fetchstructure ≫
  • PHP Manual
  • IMAP 関数
  • メッセージの特定のセクションに対する MIME ヘッダを取り出します

imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します

説明

imap_fetchmime(
IMAP\Connection $imap,
int $message_num,
string $section,
int $flags = 0
): string|false

指定したメッセージの本文の特定のセクションの MIME ヘッダを取り出します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号

section

パート番号。ピリオドで区切られた整数文字列を指定します。 これは、IMAP4 の仕様に従って本文パートのリストにインデックスを付けます。

flags

ビットマスク。以下の組合わせとなります。

  • FT_UID - message_num は UID です
  • FT_PEEK - 既に設定されていない場合、\Seen フラグを設定しません
  • FT_INTERNAL - 返される文字列は内部フォーマットです。 CRLF に正規化しません。

戻り値

指定したメッセージの本文の特定のセクションの MIME ヘッダを文字列として返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す
  • imap_fetchstructure() - 特定のメッセージの構造を読み込む
  • imap_fetchheader() - メッセージのヘッダを返す


特定のメッセージの構造を読み込む

  • ≪ imap_fetchmime
  • imap_fetchtext ≫
  • PHP Manual
  • IMAP 関数
  • 特定のメッセージの構造を読み込む

imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — 特定のメッセージの構造を読み込む

説明

imap_fetchstructure(IMAP\Connection $imap, int $message_num, int $flags = 0): stdClass|false

この関数は、指定したメッセージに関するすべての構造化された情報を取り出します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

flags

オプションのパラメータで、FT_UID のみが指定可能です。 これは、message_num を UID として処理することを関数に指定するためのものです。

戻り値

以下の表に示すプロパティを持つオブジェクトを返します。 失敗した場合に false を返します

imap_fetchstructure() が返すオブジェクト
type | 最初の body 部の型
encoding | body 部を転送する際のエンコード法
ifsubtype | subtype 文字列がある場合に true
subtype | MIME の subtype
ifdescription | description 文字列がある場合に true
description | 内容を記述する文字列
ifid | identification 文字列がある場合に true
id | Identification 文字列
lines | 行数
bytes | バイト数
ifdisposition | disposition 文字列がある場合に true
disposition | Disposition 文字列
ifdparameters | dparameters 配列が存在する場合に true
dparameters | オブジェクトの配列。各オブジェクトは "attribute" および "value" というプロパティを保持し、それぞれ Content-disposition MIME ヘッダの 対応するパラメータを表す。
ifparameters | 配列 parameters が存在する場合に true
parameters | オブジェクトの配列。各オブジェクトは "attribute" および "value" というプロパティを保持する。
parts | オブジェクトの配列であり、その構造はトップレベルオブジェクトと 同じです。それぞれが MIME body 部に対応しています。

最初の body 部の型 (使用するライブラリによって異なるため、定数を使うことを推奨します)
値 | 型 | 定数
0 | text | TYPETEXT
1 | multipart | TYPEMULTIPART
2 | message | TYPEMESSAGE
3 | application | TYPEAPPLICATION
4 | audio | TYPEAUDIO
5 | image | TYPEIMAGE
6 | video | TYPEVIDEO
7 | model | TYPEMODEL
8 | other | TYPEOTHER

転送時のエンコーディング (使用するライブラリによって異なるため、定数を使うことを推奨します)
値 | 型 | 定数
0 | 7bit | ENC7BIT
1 | 8bit | ENC8BIT
2 | Binary | ENCBINARY
3 | Base64 | ENCBASE64
4 | Quoted-Printable | ENCQUOTEDPRINTABLE
5 | other | ENCOTHER

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す
  • imap_bodystruct() - 指定したメッセージの指定した body セクションの構造を読み込む


imap_body のエイリアス

  • ≪ imap_fetchstructure
  • imap_gc ≫
  • PHP Manual
  • IMAP 関数
  • imap_body のエイリアス

imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — imap_body() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_body().


IMAP キャッシュをクリアする

  • ≪ imap_fetchtext
  • imap_get_quota ≫
  • PHP Manual
  • IMAP 関数
  • IMAP キャッシュをクリアする

imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — IMAP キャッシュをクリアする

説明

imap_gc(IMAP\Connection $imap, int $flags): true

指定した型のエントリのキャッシュを破棄します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

flags

破棄したいキャッシュを指定します。以下の定数 IMAP_GC_ELT (メッセージキャッシュ要素)、 IMAP_GC_ENV (エンベロープおよびボディ)、 IMAP_GC_TEXTS (テキスト) の組み合わせとなります。

戻り値

常に true を返します。

エラー / 例外

flags が無効な場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | flags が無効な値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、false を返していました。

例

例1 imap_gc() の例

<?php

$mbox = imap_open("{imap.example.org:143}", "username", "password");

imap_gc($mbox, IMAP_GC_ELT);

?>


クオータレベルの設定、メールボックス毎の使用状況を取得する

  • ≪ imap_gc
  • imap_get_quotaroot ≫
  • PHP Manual
  • IMAP 関数
  • クオータレベルの設定、メールボックス毎の使用状況を取得する

imap_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する

説明

imap_get_quota(IMAP\Connection $imap, string $quota_root): array|false

クオータレベルの設定、メールボックス毎の使用状況を取得します。

この関数の非管理者向けバージョンは、 PHP の imap_get_quotaroot() 関数を参照ください。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

quota_root

quota_root は、通常 user.name という形式にする必要があります。 name は、情報を取得したいメールボックスの名前です。

戻り値

指定したメールボックスの limit と usage をキーとした整数値を配列として返します。 limit の値は、このメールボックスで最大使用可能な大きさを表します。 usage の値は、このメールボックスの現在の使用状況を示します。 失敗した場合に false を返します。

PHP 4.3 では、この関数は » RFC2087 で述べられている機能をより適切に反映するようになっています。 戻り値の配列からは、サポートするリソース （例:メッセージ、あるいはサブフォルダ）数の制限をなくし、 名前つきリソースを独立した配列のキーとして受信するようにしました。 各キーの値は配列となっており、その中に usage と values の値が格納されています。

過去との互換性を保つため、旧来のアクセス方法も使用可能です。 しかし新しい方法に変更することを推奨します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_get_quota() の例

<?php
$mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$quota_value = imap_get_quota($mbox, "user.kalowsky");
if (is_array($quota_value)) {
echo "Usage level is: " . $quota_value['usage'];
echo "Limit level is: " . $quota_value['limit'];
}

imap_close($mbox);
?>

例2 4.3 以降のバージョンでの imap_get_quota() の例

<?php
$mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$quota_values = imap_get_quota($mbox, "user.kalowsky");
if (is_array($quota_values)) {
$storage = $quota_values['STORAGE'];
echo "STORAGE usage level is: " . $storage['usage'];
echo "STORAGE limit level is: " . $storage['limit'];

$message = $quota_values['MESSAGE'];
echo "MESSAGE usage level is: " . $message['usage'];
echo "MESSAGE limit is: " . $message['limit'];

/* ... */
}

imap_close($mbox);
?>

注意

この関数は、現在、c-client2000 以降のライブラリを使用しているユーザーのみ使用可能です。

指定する imap は、 メールの管理者としてオープンしたものである必要があります。 そうでない場合は、この関数は失敗します。

参考

  • imap_open() - メールボックスへの IMAP ストリームをオープンする
  • imap_set_quota() - 指定したメールボックスにクォータを設定する
  • imap_get_quotaroot() - ユーザー単位のクォータ設定を取得する


ユーザー単位のクォータ設定を取得する

  • ≪ imap_get_quota
  • imap_getacl ≫
  • PHP Manual
  • IMAP 関数
  • ユーザー単位のクォータ設定を取得する

imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — ユーザー単位のクォータ設定を取得する

説明

imap_get_quotaroot(IMAP\Connection $imap, string $mailbox): array|false

ユーザー単位のクォータ設定を取得します。 limit の値は、このユーザーがメールボックスで使用可能な総容量を表します。 usage の値は、ユーザーが現在メールボックスで使用している容量を表します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

mailbox はどのメールボックスを調べるかを 指定します（例: INBOX）。

戻り値

指定したユーザーのメールボックスに関連する整数値を配列で返します。 すべての値にはリソース名に基づいたキーがつけられており、 usage および limit 値を保持する配列が関連付けられています。

コールが失敗した場合、およびサーバーからの応答内容をパースできなかった場合には この関数は false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_get_quotaroot() の例

<?php
$mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$quota = imap_get_quotaroot($mbox, "INBOX");
if (is_array($quota)) {
$storage = $quota['STORAGE'];
echo "STORAGE usage level is: " . $storage['usage'];
echo "STORAGE limit level is: " . $storage['limit'];

$message = $quota['MESSAGE'];
echo "MESSAGE usage level is: " . $message['usage'];
echo "MESSAGE limit level is: " . $message['limit'];

/* ... */

}

imap_close($mbox);
?>

注意

この関数は、現在は c-client2000 以降のライブラリを使用しているユーザーのみ利用可能です。

imap は、 調べたいメールボックスを所有するユーザーがオープンしなければなりません。

参考

  • imap_open() - メールボックスへの IMAP ストリームをオープンする
  • imap_set_quota() - 指定したメールボックスにクォータを設定する
  • imap_get_quota() - クオータレベルの設定、メールボックス毎の使用状況を取得する


与えられたメールボックスの ACL を取得する

  • ≪ imap_get_quotaroot
  • imap_getmailboxes ≫
  • PHP Manual
  • IMAP 関数
  • 与えられたメールボックスの ACL を取得する

imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — 与えられたメールボックスの ACL を取得する

説明

imap_getacl(IMAP\Connection $imap, string $mailbox): array|false

指定したメールボックスの ACL を取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

戻り値

"folder" => "acl" 形式の連想配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_getacl() の例

<?php

print_r(imap_getacl($imap, 'user.joecool'));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [asubfolder] => lrswipcda
    [anothersubfolder] => lrswipcda
)

注意

この関数は、現在は c-client2000 以降のライブラリを使用しているユーザーのみ利用可能です。

参考

  • imap_setacl() - 指定したメールボックスの ACL を設定する


メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

  • ≪ imap_getacl
  • imap_getsubscribed ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

説明

imap_getmailboxes(IMAP\Connection $imap, string $reference, string $pattern): array|false

メールボックスの情報を取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

戻り値

メールボックス情報を有するオブジェクトの配列を返します。各オブジェクトには、 メールボックスの完全な名前である name、 このメールボックスの階層の区切りを示す属性 delimiter、 そして attributes が存在します。 attributes はビットマスクであり、 次のものについて調べることができます。

  • LATT_NOINFERIORS - このメールボックスには 「子供」がいないか、またはいないかもしれません（このボックスの中にメールボックスはありません）。 このメールボックスに対して imap_createmailbox() をコールしても動作しません。

  • LATT_NOSELECT - 単なるコンテナであり、 メールボックスではありません - これをオープンすることはできません。

  • LATT_MARKED - このメールボックスにはマークがつけられています。 これは、最後に確認したとき以降に新たなメッセージが到着しているかもしれないということを意味します。 すべての IMAP サーバーがこの機能を提供しているとは限りません。

  • LATT_UNMARKED - このメールボックスにはマークがつけられておらず、 新たなメッセージを含んでいません。 MARKED あるいは UNMARKED が提供されている場合は、 その IMAP サーバーがこのメールボックスに対してマーク機能を提供しているとみなせます。

  • LATT_REFERRAL - このコンテナはリモートメールボックスと関連を持ちます。

  • LATT_HASCHILDREN - このメールボックスは選択可能な子を持ちます。

  • LATT_HASNOCHILDREN - このメールボックスは選択可能な子を持ちません。

この関数は、失敗した時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_getmailboxes() の例

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
if (is_array($list)) {
foreach ($list as $key => $val) {
echo "($key) ";
echo imap_utf7_decode($val->name) . ",";
echo "'" . $val->delimiter . "',";
echo $val->attributes . "<br />\n";
}
} else {
echo "imap_getmailboxes failed: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>

参考

  • imap_getsubscribed() - 購読中の全メールボックスの一覧を取得する


購読中の全メールボックスの一覧を取得する

  • ≪ imap_getmailboxes
  • imap_header ≫
  • PHP Manual
  • IMAP 関数
  • 購読中の全メールボックスの一覧を取得する

imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — 購読中の全メールボックスの一覧を取得する

説明

imap_getsubscribed(IMAP\Connection $imap, string $reference, string $pattern): array|false

購読中のメールボックスの情報を取得します。

imap_getmailboxes() と同じ動作をしますが、 ユーザーが購読しているメールボックスのみを返すという点が異なります。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

reference

reference は、通常は imap_open() で指定したサーバー情報です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

戻り値

メールボックス情報を有するオブジェクトの配列を返します。各オブジェクトには、 メールボックスの完全な名前である name、 このメールボックスの階層の区切りを示す属性 delimiter、 そして attributes が存在します。 attributes はビットマスクであり、 次のものについて調べることができます。

  • LATT_NOINFERIORS - このメールボックスには 「子供」はいません（このボックスの中にメールボックスはありません）。
  • LATT_NOSELECT - 単なるコンテナであり、 メールボックスではありません - これをオープンすることはできません。
  • LATT_MARKED - このメールボックスにはマークが つけられています。UW-IMAPD でのみ使用されます。
  • LATT_UNMARKED - このメールボックスにはマークが つけられていません。UW-IMAPD でのみ使用されます。

  • LATT_REFERRAL - このコンテナはリモートメールボックスと関連を持ちます。

  • LATT_HASCHILDREN - このメールボックスは選択可能な子を持ちます。

  • LATT_HASNOCHILDREN - このメールボックスは選択可能な子を持ちません。

この関数は、失敗した時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。


imap_headerinfo のエイリアス

  • ≪ imap_getsubscribed
  • imap_headerinfo ≫
  • PHP Manual
  • IMAP 関数
  • imap_headerinfo のエイリアス

imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — imap_headerinfo() のエイリアス

警告

このエイリアスは PHP 8.0.0 で 削除 されました。

説明

この関数は次の関数のエイリアスです。 imap_headerinfo().


メッセージヘッダを読み込む

  • ≪ imap_header
  • imap_headers ≫
  • PHP Manual
  • IMAP 関数
  • メッセージヘッダを読み込む

imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — メッセージヘッダを読み込む

説明

imap_headerinfo(
IMAP\Connection $imap,
int $message_num,
int $from_length = 0,
int $subject_length = 0
): stdClass|false

指定したメッセージ番号についての情報を、そのヘッダを読み込んで取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

from_length

fetchfrom プロパティの文字数。 ゼロ以上でなければなりません。

subject_length

fetchsubject プロパティの文字数。 ゼロ以上でなければなりません。

defaulthost

戻り値

エラー時には false、成功時には 以下のプロパティをもつオブジェクトを返します。

  • toaddress - 完全な to: 行。最大 1024 文字。
  • to - To: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • fromaddress - 完全な from: 行。最大 1024 文字。
  • from - From: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • ccaddress - 完全な cc: 行。最大 1024 文字。
  • cc - Cc: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • bccaddress - 完全な bcc: 行。最大 1024 文字。
  • bcc - Bcc: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • reply_toaddress - 完全な Reply-To: 行。最大 1024 文字。
  • reply_to - Reply-To: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • senderaddress - 完全な sender: 行。最大 1024 文字。
  • sender - Sender: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、adl、 mailbox および host
  • return_pathaddress - 完全な Return-Path: 行。最大 1024 文字。
  • return_path - Return-Path: 行から、次のプロパティを含むオブジェクトの配列を返します。 personal、 adl、mailbox および host
  • remail -
  • date - ヘッダにあるメッセージの日付。
  • Date - date と同じ。
  • subject - メッセージの件名。
  • Subject - subject と同じ。
  • in_reply_to -
  • message_id -
  • newsgroups -
  • followup_to -
  • references -
  • Recent - 最近の既読メッセージは R、 最新の未読メッセージは N、 最新でないメッセージは ' '。
  • Unseen - 最新でない未読メッセージは U、 既読、あるいは最新の未読メッセージは ' '。
  • Flagged - フラグがたっている場合は F、 そうでない場合は ' '。
  • Answered - 返信した場合は A、 していない場合は ' '。
  • Deleted - 削除された場合は D、 されていない場合は ' '。
  • Draft - 草稿である場合は X、 そうでない場合は ' '。
  • Msgno - メッセージ番号。
  • MailDate -
  • Size - メッセージのサイズ。
  • udate - メールメッセージの日付を Unix time で表したもの。
  • fetchfrom - from 行を from_length 文字に適合させたもの。
  • fetchsubject - subject 行を subject_length 文字に適合させたもの。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | 未使用だった defaulthost が削除されました。

参考

  • imap_fetch_overview() - 指定したメッセージのヘッダ情報の概要を読む


メールボックス内のすべてのメッセージのヘッダを返す

  • ≪ imap_headerinfo
  • imap_is_open ≫
  • PHP Manual
  • IMAP 関数
  • メールボックス内のすべてのメッセージのヘッダを返す

imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — メールボックス内のすべてのメッセージのヘッダを返す

説明

imap_headers(IMAP\Connection $imap): array|false

メールボックス内のすべてのメッセージのヘッダを返します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

ヘッダ情報でフォーマットされた文字列の配列を返します。1 つの メールメッセージ毎に 1 つの要素が格納されます。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。


IMAP ストリームがまだ有効かを調べる

  • ≪ imap_headers
  • imap_last_error ≫
  • PHP Manual
  • IMAP 関数
  • IMAP ストリームがまだ有効かを調べる

imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — IMAP ストリームがまだ有効かを調べる

説明

imap_is_open(IMAP\Connection $imap): bool

IMAP ストリームがまだ有効かを調べます。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

ストリームがまだ有効な場合は、true を返します。 そうでない場合は、false を返します。

例

例1 imap_is_open() の例

<?php
$mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
imap_is_open($mbox);
// ...
?>


ページリクエスト時に生じた直近の IMAP エラーを返す

  • ≪ imap_is_open
  • imap_list ≫
  • PHP Manual
  • IMAP 関数
  • ページリクエスト時に生じた直近の IMAP エラーを返す

imap_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す

説明

imap_last_error(): string|false

現在のページに生じた直近の IMAP エラーメッセージの全文を返します。 エラースタックは変更されません。 imap_last_error() を続けてコールした際、 コール間に新規エラーが生じていない場合は同じエラーが返されます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のページに生じた直近の IMAP エラーメッセージの全文を返します。 エラーメッセージが存在しない場合は false を返します。

参考

  • imap_errors() - 発生したすべての IMAP エラーを返す


メールボックスのリストを読み込む

  • ≪ imap_last_error
  • imap_listmailbox ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスのリストを読み込む

imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — メールボックスのリストを読み込む

説明

imap_list(IMAP\Connection $imap, string $reference, string $pattern): array|false

メールボックスのリストを読み込みます。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

戻り値

メールボックスの名前を含む配列を返します。 または失敗時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_list() の例

<?php
$mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$list = imap_list($mbox, "{imap.example.org}", "*");
if (is_array($list)) {
foreach ($list as $val) {
echo imap_utf7_decode($val) . "\n";
}
} else {
echo "imap_list が失敗しました: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>

参考

  • imap_getmailboxes() - メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す
  • imap_lsub() - 購読しているすべてのメールボックスの一覧を得る


imap_list のエイリアス

  • ≪ imap_list
  • imap_listscan ≫
  • PHP Manual
  • IMAP 関数
  • imap_list のエイリアス

imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — imap_list() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_list().


指定したテキストにマッチするメールボックスの一覧を返す

  • ≪ imap_listmailbox
  • imap_listsubscribed ≫
  • PHP Manual
  • IMAP 関数
  • 指定したテキストにマッチするメールボックスの一覧を返す

imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す

説明

imap_listscan(
IMAP\Connection $imap,
string $reference,
string $pattern,
string $content
): array|false

content をテキストに持つメールボックスの名前を 配列で返します。

この関数は imap_listmailbox() に似ていますが、 メールボックス内に文字列 content が存在するか どうかを調べる点が違います。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

content

検索する文字列。

戻り値

content をテキストに持つメールボックスの名前を配列で返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_listmailbox() - imap_list のエイリアス
  • imap_search() - 指定した検索条件にマッチするメッセージを配列として返す


imap_lsub のエイリアス

  • ≪ imap_listscan
  • imap_lsub ≫
  • PHP Manual
  • IMAP 関数
  • imap_lsub のエイリアス

imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — imap_lsub() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_lsub().


購読しているすべてのメールボックスの一覧を得る

  • ≪ imap_listsubscribed
  • imap_mail ≫
  • PHP Manual
  • IMAP 関数
  • 購読しているすべてのメールボックスの一覧を得る

imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — 購読しているすべてのメールボックスの一覧を得る

説明

imap_lsub(IMAP\Connection $imap, string $reference, string $pattern): array|false

購読しているすべてのメールボックスの配列を取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

reference

通常、reference は imap_open() で述べられているサーバー定義です。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

pattern

検索を開始するメールボックスの階層を指定します。

pattern の中で使用できる特別な文字として '*' および '%' があります。 '*' は、すべてのメールボックスを意味します。 pattern に '*' を指定すると、 メールボックス階層全体のリストが得られます。 '%' は現在のレベルのみを意味します。 '%' を pattern に指定すると、 トップレベルのメールボックスのみを返します。UW_IMAPD の場合、 '~/mail/%' は ~/mail ディレクトリ内のすべてのメールボックスを返しますが、 そのディレクトリのサブフォルダにあるメールボックスは返しません。

戻り値

購読しているすべてのメールボックスの配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_list() - メールボックスのリストを読み込む
  • imap_getmailboxes() - メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す


e-mail メッセージを送信する

  • ≪ imap_lsub
  • imap_mail_compose ≫
  • PHP Manual
  • IMAP 関数
  • e-mail メッセージを送信する

imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — e-mail メッセージを送信する

説明

imap_mail(
string $to,
string $subject,
string $message,
?string $additional_headers = null,
?string $cc = null,
?string $bcc = null,
?string $return_path = null
): bool

この関数は、Cc および Bcc 受信者の正確な処理を行って email を送信することが可能です。

パラメータ to、cc および bcc は全て文字列で、 » RFC822 アドレスリストとしてパースされます。

パラメータ

to

受信者。

subject

メールの件名。

message

メールの本文。 imap_mail_compose() を参照ください。

additional_headers

メールに設定する追加ヘッダ文字列。

cc

bcc

bcc で指定した受信者は mail を受信しますが、 ヘッダからは除外されます。

return_path

リターンパスを指定するために rpath パラメータを使用してください。この関数は、 複数のユーザー用のメールクライアントとして PHP を使用する際に有用です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | additional_headers, cc, bcc, return_path は、nullable になりました。

参考

  • mail() - メールを送信する
  • imap_mail_compose() - 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する


指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

  • ≪ imap_mail
  • imap_mail_copy ≫
  • PHP Manual
  • IMAP 関数
  • 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

説明

imap_mail_compose(array $envelope, array $bodies): string|false

指定したエンベロープ envelope およびボディセクション bodies に基づいて MIME メッセージを作成します。

パラメータ

envelope

ヘッダフィールドの連想配列。使えるキーは "remail", "return_path", "date", "from", "reply_to", "in_reply_to", "subject", "to", "cc", "bcc"。 "message_id"。 これらの値は、連想配列の値に与えられた文字列でそれぞれのヘッダを設定します。 さらに追加のヘッダを設定する用途として、 "custom_headers" がサポートされています。 ここには、その他のヘッダの連想配列を指定します。例: ["User-Agent: My Mail Client"]

bodies

本文の配列。 配列の最初の要素が、メッセージの中心部分です。 TYPEMULTIPART の場合にだけ、ふたつめ以降の要素が処理されます。 処理された要素は、本文の一部を構成します。

body に指定する配列の構造
キー | 型 | 説明
type | int | MIMEタイプ。 TYPETEXT (デフォルト), TYPEMULTIPART, TYPEMESSAGE, TYPEAPPLICATION, TYPEAUDIO, TYPEIMAGE, TYPEMODEL, TYPEOTHER が指定できます。
encoding | int | Content-Transfer-Encoding の値を指定します。 ENC7BIT (デフォルト), ENC8BIT, ENCBINARY, ENCBASE64, ENCQUOTEDPRINTABLE, ENCOTHER が指定できます。
charset | string | MIMEタイプの charset パラメータの値
type.parameters | array | Content-Type の名前と値を連想配列で指定します。
subtype | string | MIMEサブタイプ。例: TYPEIMAGE の場合は 'jpeg'
id | string | Content-ID の値
description | string | Content-Description の値
disposition.type | string | Content-Disposition の値。例: 'attachment'
disposition | array | Content-Disposition の名前と値を連想配列で指定します。
contents.data | string | ペイロード
lines | int | The size of the payload in lines.
bytes | int | ペイロードのサイズをバイト単位で指定します。
md5 | string | ペイロードのMD5チェックサム

戻り値

MIME メッセージを文字列として返します。 失敗した場合に false を返します

例

例1 imap_mail_compose() の例

<?php

$envelope["from"]= "joe@example.com";
$envelope["to"] = "foo@example.com";
$envelope["cc"] = "bar@example.com";

$part1["type"] = TYPEMULTIPART;
$part1["subtype"] = "mixed";

$filename = "/tmp/imap.c.gz";
$fp = fopen($filename, "r");
$contents = fread($fp, filesize($filename));
fclose($fp);

$part2["type"] = TYPEAPPLICATION;
$part2["encoding"] = ENCBINARY;
$part2["subtype"] = "octet-stream";
$part2["description"] = basename($filename);
$part2["contents.data"] = $contents;

$part3["type"] = TYPETEXT;
$part3["subtype"] = "plain";
$part3["description"] = "description3";
$part3["contents.data"] = "contents.data3\n\n\n\t";

$body[1] = $part1;
$body[2] = $part2;
$body[3] = $part3;

echo nl2br(imap_mail_compose($envelope, $body));

?>


指定されたメッセージをメールボックスにコピーする

  • ≪ imap_mail_compose
  • imap_mail_move ≫
  • PHP Manual
  • IMAP 関数
  • 指定されたメッセージをメールボックスにコピーする

imap_mail_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — 指定されたメッセージをメールボックスにコピーする

説明

imap_mail_copy(
IMAP\Connection $imap,
string $message_nums,
string $mailbox,
int $flags = 0
): bool

message_nums で指定されたメッセージを、 指定したメールボックスにコピーします。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_nums

message_nums は、 (» RFC2060 に記述されたように) ただのメッセージ番号ではなく、範囲を示します。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

flags

flags はビットマスクであり、以下の組み合わせです。

  • CP_UID - UIDS を含む処理の数
  • CP_MOVE - コピー後にメールボックスからメッセージを削除する。 このフラグが設定されていると、この関数は imap_mail_move() と同じ振る舞いをします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_mail_move() - 指定されたメッセージをメールボックスに移動する


指定されたメッセージをメールボックスに移動する

  • ≪ imap_mail_copy
  • imap_mailboxmsginfo ≫
  • PHP Manual
  • IMAP 関数
  • 指定されたメッセージをメールボックスに移動する

imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — 指定されたメッセージをメールボックスに移動する

説明

imap_mail_move(
IMAP\Connection $imap,
string $message_nums,
string $mailbox,
int $flags = 0
): bool

message_nums で指定されたメッセージを、 指定されたメールボックス mbox に移動します。 実際には mailbox にメッセージが コピー され、 オリジナルのメッセージには削除済みのフラグが付く点に注意して下さい。 これは、mailbox にあるメッセージには、 新しい UID が割り当てられるということです。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_nums

message_nums は、 (» RFC2060 に記述されたように) ただのメッセージ番号ではなく、範囲を示します。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

flags

flags はビットマスクであり、ひとつのオプションをとります。

  • CP_UID - UIDS を含む処理の数

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

注意

注意:

imap_mail_move() は元のメールに削除フラグを立てます。 imap_expunge() がコールされたときに確実に削除されるようにするためです。

参考

  • imap_mail_copy() - 指定されたメッセージをメールボックスにコピーする


現在のメールボックスに関する情報を得る

  • ≪ imap_mail_move
  • imap_mime_header_decode ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスに関する情報を得る

imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — 現在のメールボックスに関する情報を得る

説明

imap_mailboxmsginfo(IMAP\Connection $imap): stdClass

サーバーにおける現在のメールボックスのステータスを調べます。この関数は imap_status() に似ていますが、 メールボックス内の全メッセージのサイズを合計します。このため、 実行時間が幾分余計にかかります。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

以下のプロパティを有するオブジェクトを返します。

Mailbox のプロパティ
Date | 最終変更日 (現在の日付時刻)
Driver | ドライバ
Mailbox | メールボックスの名前
Nmsgs | メッセージ数
Recent | 最近のメッセージの数
Unread | 未読のメッセージの数
Deleted | 削除されたメッセージの数
Size | メールボックスのサイズ

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_mailboxmsginfo() example

<?php

$mbox = imap_open("{imap.example.org}INBOX", "username", "password")
or die("接続できません: " . imap_last_error());

$check = imap_mailboxmsginfo($mbox);

if ($check) {
echo "Date: " . $check->Date . "<br />\n" ;
echo "Driver: " . $check->Driver . "<br />\n" ;
echo "Mailbox: " . $check->Mailbox . "<br />\n" ;
echo "Messages: " . $check->Nmsgs . "<br />\n" ;
echo "Recent: " . $check->Recent . "<br />\n" ;
echo "Unread: " . $check->Unread . "<br />\n" ;
echo "Deleted: " . $check->Deleted . "<br />\n" ;
echo "Size: " . $check->Size . "<br />\n" ;
} else {
echo "imap_mailboxmsginfo() に失敗: " . imap_last_error() . "<br />\n";
}

imap_close($mbox);

?>


MIME ヘッダ要素をデコードする

  • ≪ imap_mailboxmsginfo
  • imap_msgno ≫
  • PHP Manual
  • IMAP 関数
  • MIME ヘッダ要素をデコードする

imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — MIME ヘッダ要素をデコードする

説明

imap_mime_header_decode(string $string): array|false

非 ASCII テキストの MIME メッセージヘッダエクステンションをデコードします (» RFC2047 を参照ください)。

パラメータ

string

MIME テキスト。

戻り値

デコードされた要素は、オブジェクトの配列で返されます。 各オブジェクトは、二つのプロパティ charset と text を有しています。

要素がエンコードされていない場合、言い替えるとプレーンな US-ASCII の場合は この要素の charset プロパティは default に設定されます。

この関数は、失敗した時に false を返します。

例

例1 imap_mime_header_decode() の例

<?php
$text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@example.com>";

$elements = imap_mime_header_decode($text);
for ($i=0; $i<count($elements); $i++) {
echo "Charset: {$elements[$i]->charset}\n";
echo "Text: {$elements[$i]->text}\n\n";
}
?>

上の例の出力は以下となります。

Charset: ISO-8859-1
Text: Keld Jorn Simonsen

Charset: default
Text:  <keld@example.com>

上の例には二つの要素があります。最初の要素は ISO-8859-1、 2 番目の要素はプレーンな US-ASCII で事前にエンコードされています。

参考

  • imap_utf8() - MIME エンコードされたテキストを UTF-8 に変換する


指定した UID のメッセージ番号を返す

  • ≪ imap_mime_header_decode
  • imap_mutf7_to_utf8 ≫
  • PHP Manual
  • IMAP 関数
  • 指定した UID のメッセージ番号を返す

imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — 指定した UID のメッセージ番号を返す

説明

imap_msgno(IMAP\Connection $imap, int $message_uid): int

指定した message_uid のメッセージ番号を返します。

この関数は、imap_uid() の逆の動作となります。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_uid

メッセージの UID。

戻り値

指定した message_uid のメッセージ番号を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_uid() - 指定したメッセージシーケンス番号の UID を返す


修正UTF-7文字列をUTF-8にデコードする

  • ≪ imap_msgno
  • imap_num_msg ≫
  • PHP Manual
  • IMAP 関数
  • 修正UTF-7文字列をUTF-8にデコードする

imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — 修正UTF-7文字列をUTF-8にデコードする

説明

imap_mutf7_to_utf8(string $string): string|false

修正UTF-7(RFC 2060, section 5.1.3)文字列を UTF-8 にデコードします。

注意:

この関数は libcclient が utf8_to_mutf7() をエクスポートした場合にのみ利用できます。

パラメータ

string

修正UTF-7 でエンコードされた文字列

戻り値

string を UTF-8 に変換したものを返します。 失敗した場合に false を返します.

参考

  • imap_utf8_to_mutf7() - UTF-8 文字列を修正UTF-7にエンコードする


現在のメールボックスのメッセージ数を取得する

  • ≪ imap_mutf7_to_utf8
  • imap_num_recent ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスのメッセージ数を取得する

imap_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — 現在のメールボックスのメッセージ数を取得する

説明

imap_num_msg(IMAP\Connection $imap): int|false

現在のメールボックスにあるメッセージ数を返します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

現在のメールボックスのメッセージ数を整数として返します。 またはエラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_num_recent() - 現在のメールボックスにある新規メッセージ数を取得する
  • imap_status() - 現在のメールボックス以外のメールボックスのステータス情報を返す


現在のメールボックスにある新規メッセージ数を取得する

  • ≪ imap_num_msg
  • imap_open ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックスにある新規メッセージ数を取得する

imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — 現在のメールボックスにある新規メッセージ数を取得する

説明

imap_num_recent(IMAP\Connection $imap): int

現在のメールボックスにある新しいメッセージの数を返します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

現在のメールボックスにある新しいメッセージの数を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_num_msg() - 現在のメールボックスのメッセージ数を取得する
  • imap_status() - 現在のメールボックス以外のメールボックスのステータス情報を返す


メールボックスへの IMAP ストリームをオープンする

  • ≪ imap_num_recent
  • imap_ping ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスへの IMAP ストリームをオープンする

imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — メールボックスへの IMAP ストリームをオープンする

説明

imap_open(
string $mailbox,
string $user,
string $password,
int $flags = 0,
int $retries = 0,
array $options = []
): IMAP\Connection|false

mailbox への IMAP ストリームをオープンします。

この関数は、POP3 や NNTP サーバーへのストリームをオープンする際にも使用可能です。 しかし、いくつかの関数および機能は IMAP サーバーでしか利用できません。

パラメータ

mailbox

メールボックス名(mailbox)は、サーバー名の部分と使用するサーバーにおける メールボックスへのパスから構成されます。特別な名前 INBOX は、 カレントユーザーの個人メールボックスを意味します。 ASCII 空間で出力可能な文字以外の外国文字を含むメールボックス名は imap_utf7_encode() でエンコードする必要があります。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

サーバー部は '{' および '}' で括られ、サーバー名または IP アドレス、オプションの ':' から始まるポート指定子、('/' で始まる)オプションのプロトコル指定子 から構成されます。

サーバー部は、全ての mailbox パラメータで必須です。

{ で始まる名前はすべてリモート名で、 "{" remote_system_name [":" port] [flags] "}" [mailbox_name] のような形式となります。

  • remote_system_name - Internet ドメイン名 あるいは括弧でかこまれたサーバーの IP アドレス。
  • port - オプションの TCP ポート番号。デフォルトは そのサービスのデフォルトポート。
  • flags - オプションのフラグ。以下の表を参照ください。
  • mailbox_name - リモートメールボックス名。デフォルトは INBOX 。

オプションのフラグ名
フラグ | 説明
/service=service | メールボックスにアクセスするサービス。デフォルトは "imap" 。
/user=user | サーバーへのログイン時のユーザー名。
/authuser=user | リモートの認証ユーザー。指定されていた場合は、このユーザーのパスワードが 認証に使用されます（例: administrator）。
/anonymous | 匿名ユーザーとしてアクセスします。
/debug | プロトコルの通信内容をアプリケーションのデバッグログに記録します。
/secure | ネットワーク越しにプレーンテキストのパスワードを送信しません。
/imap, /imap2, /imap2bis, /imap4, /imap4rev1 | /service=imap と同じです。
/pop3 | /service=pop3 と同じです。
/nntp | /service=nntp と同じです。
/norsh | 事前に認証済みの IMAP セッションを確立する際に、rsh や ssh を使用しません。
/ssl | セッションの暗号化に Secure Socket Layer を使用します。
/validate-cert | TLS/SSL サーバーの証明書を検証します（デフォルトの挙動です）。
/novalidate-cert | TLS/SSL サーバーの証明書を検証しません。サーバーが自己証明の 証明書を使用している際に必要となります。
/tls | セッションの暗号化に start-TLS の使用を強制し、それを サポートしていないサーバーとの接続を拒否します。
/notls | たとえサーバーがそれをサポートしていたとしても、 セッションで start-TLS による暗号化を使用しません。
/readonly | 読み込み専用でのメールボックスのオープンを要求します（IMAP のみ。 NNTP では無視され、SMTP および POP3 ではエラーとなります）。

user

ユーザー名。

password

user のパスワード。

flags

flags はビットマスクであり、以下の組み合わせとなります。

  • OP_READONLY - メールボックスを読み込み専用でオープンします。
  • OP_ANONYMOUS - news に関して .newsrc を使用せず、更新もしません（NNTP のみ）。
  • OP_HALFOPEN - IMAP 及び NNTP 名について、 接続をオープンしますがメールボックスはオープンしません。
  • CL_EXPUNGE - メールボックスを閉じる際に、 自動的にメールボックスを削除します（imap_delete() および imap_expunge() も参照ください）。
  • OP_DEBUG - プロトコルネゴシエーションをデバッグします。
  • OP_SHORTCACHE - 短い（elt-only）キャッシングを行います。
  • OP_SILENT - イベントを受信しません（内部で使用します）。
  • OP_PROTOTYPE - ドライバのプロトタイプを返します。
  • OP_SECURE - セキュアでない認証を行いません。

retries

接続試行の最大数。

options

接続パラメータ。次の (文字列の) キーを使って接続パラメータを設定することができます。

  • DISABLE_AUTHENTICATOR - 認証プロパティを無効にする

戻り値

成功した場合は、 IMAP\Connection クラスのインスタンスを返します。 失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.1.0 | IMAP\Connection のインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。

例

例1 imap_open() のさまざまな使用例

<?php
// ローカルマシンのポート 143 で稼動している IMAP サーバーに接続するには
// 以下のようにします。
$mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

// ローカルマシンのポート 110 で稼動している POP3 サーバーに接続するには、
$mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

// SSL IMAP あるいは POP3 サーバーに接続するには、プロトコル指定のあとに
// /ssl を追加します。
$mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

// 自分でサインした証明書で SSL IMAP あるいは POP3 サーバーに接続するには、
// プロトコル指定のあとに /ssl/novalidate-cert を追加します。
$mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

// ローカルマシンのポート 119 で稼動している NNTP サーバーに接続するには、
$nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");
// リモートサーバーに接続する際は、"localhost" を接続したいサーバーの
// 名前または IP アドレスに置き換えます。
?>

例2 imap_open() の例

<?php
$mbox = imap_open("{imap.example.org:143}", "username", "password");

echo "<h1>Mailboxes</h1>\n";
$folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

if ($folders == false) {
echo "コールが失敗しました<br />\n";
} else {
foreach ($folders as $val) {
echo $val . "<br />\n";
}
}

echo "<h1>INBOX のヘッダ</h1>\n";
$headers = imap_headers($mbox);

if ($headers == false) {
echo "コールが失敗しました<br />\n";
} else {
foreach ($headers as $val) {
echo $val . "<br />\n";
}
}

imap_close($mbox);
?>

参考

  • imap_close() - IMAP ストリームをクローズする


IMAP ストリームがアクティブかどうかを調べる

  • ≪ imap_open
  • imap_qprint ≫
  • PHP Manual
  • IMAP 関数
  • IMAP ストリームがアクティブかどうかを調べる

imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — IMAP ストリームがアクティブかどうかを調べる

説明

imap_ping(IMAP\Connection $imap): bool

imap_ping() はストリームに ping を行い、 まだアクティブであるかどうかを調べます。これにより新しいメールの到着を知ることもあります。 これは、定期的に「メールのチェック」を行い、サーバーとの 「接続を保持し続ける」ためのお勧めの方法です。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

戻り値

ストリームがまだ有効であれば true を、そうでなければ false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_ping() の例

<?php

$imap = imap_open("{imap.example.org}", "mailadmin", "password");

// しばらく休んだ後
if (!imap_ping($imap)) {
// 再接続の処理
}

?>


quoted-printable 文字列を 8 ビット文字列に変換する

  • ≪ imap_ping
  • imap_rename ≫
  • PHP Manual
  • IMAP 関数
  • quoted-printable 文字列を 8 ビット文字列に変換する

imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — quoted-printable 文字列を 8 ビット文字列に変換する

説明

imap_qprint(string $string): string|false

（» RFC2045, section 6.7 に基づき）quoted-printable 文字列を 8 ビット文字列に変換します。

パラメータ

string

quoted-printable 文字列。

戻り値

8 ビット文字列を返します。 失敗した場合に false を返します

参考

  • imap_8bit() - 8 ビット文字列を quoted-printable 文字列に変換する


imap_renamemailbox のエイリアス

  • ≪ imap_qprint
  • imap_renamemailbox ≫
  • PHP Manual
  • IMAP 関数
  • imap_renamemailbox のエイリアス

imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — imap_renamemailbox() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_renamemailbox().


メールボックスの名前を変更する

  • ≪ imap_rename
  • imap_reopen ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスの名前を変更する

imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — メールボックスの名前を変更する

説明

imap_renamemailbox(IMAP\Connection $imap, string $from, string $to): bool

この関数は、古いメールボックスを新しいメールボックスにリネーム します（mbox 名のフォーマットについては imap_open() を参照ください）。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

from

古いメールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

to

新しいメールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_createmailbox() - 新しいメールボックスを作る
  • imap_deletemailbox() - メールボックスを削除する


新規メールボックスへの IMAP ストリームを再度オープンする

  • ≪ imap_renamemailbox
  • imap_rfc822_parse_adrlist ≫
  • PHP Manual
  • IMAP 関数
  • 新規メールボックスへの IMAP ストリームを再度オープンする

imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — 新規メールボックスへの IMAP ストリームを再度オープンする

説明

imap_reopen(
IMAP\Connection $imap,
string $mailbox,
int $flags = 0,
int $retries = 0
): bool

IMAP または NNTP サーバー上の新しい mailbox に対して指定されたストリームを再オープンします。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

flags

flags はビットマスクであり、以下の組み合わせとなります。

  • OP_READONLY - メールボックスを読み込み専用でオープンします。
  • OP_ANONYMOUS - ニュースに関して .newsrc を使用せず、更新もしません（NNTP のみ）。
  • OP_HALFOPEN - IMAP および NNTP 名について、接続をオープンするがメールボックスをオープンしません。
  • OP_EXPUNGE - 何も警告せずにリサイクルストリームを削除します。
  • CL_EXPUNGE - メールボックスを閉じた際に、自動的に メールボックスを削除する（imap_delete() および imap_expunge() も参照ください）。

retries

接続試行の最大数。

戻り値

ストリームを再度オープンした場合に true、 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_reopen() の例

<?php
$mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
// ...
imap_reopen($mbox, "{imap.example.org:143}INBOX.Sent") or die(implode(", ", imap_errors()));
// ..
?>


アドレス文字列を解釈します

  • ≪ imap_reopen
  • imap_rfc822_parse_headers ≫
  • PHP Manual
  • IMAP 関数
  • アドレス文字列を解釈します

imap_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — アドレス文字列を解釈します

説明

imap_rfc822_parse_adrlist(string $string, string $default_hostname): array

» RFC2822 の定義に基づき、アドレス文字列をパースします。

パラメータ

string

アドレスを含む文字列。

default_hostname

デフォルトのホスト名。

戻り値

オブジェクトの配列を返します。オブジェクトのプロパティは以下のとおりです。

  • mailbox - メールボックス名（ユーザー名）。
  • host - ホスト名。
  • personal - 個人名。
  • adl - ドメインソースルート。

例

例1 imap_rfc822_parse_adrlist() の例

<?php

$address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root";
$address_array = imap_rfc822_parse_adrlist($address_string, "example.com");
if (!is_array($address_array) || count($address_array) < 1) {
die("something is wrong\n");
}

foreach ($address_array as $id => $val) {
echo "# $id\n";
echo " mailbox : " . $val->mailbox . "\n";
echo " host : " . $val->host . "\n";
echo " personal: " . $val->personal . "\n";
echo " adl : " . $val->adl . "\n";
}
?>

上の例の出力は以下となります。

# 0
  mailbox : doe
  host    : example.com
  personal: Joe Doe
  adl     :
# 1
  mailbox : postmaster
  host    : example.com
  personal:
  adl     :
# 2
  mailbox : root
  host    : example.com
  personal:
  adl     :

参考

  • imap_rfc822_parse_headers() - 文字列からメールヘッダを解釈する


文字列からメールヘッダを解釈する

  • ≪ imap_rfc822_parse_adrlist
  • imap_rfc822_write_address ≫
  • PHP Manual
  • IMAP 関数
  • 文字列からメールヘッダを解釈する

imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — 文字列からメールヘッダを解釈する

説明

imap_rfc822_parse_headers(string $headers, string $default_hostname = "UNKNOWN"): stdClass

複数のヘッダ要素を含むオブジェクトを取得します。 imap_header() と同じようなものです。

パラメータ

headers

パースされたヘッダデータ。

default_hostname

デフォルトのホスト名。

戻り値

imap_header() が返すオブジェクトと似たものを返します。 フラグおよび他の要素は IMAP サーバーから取得するいう点が異なります。

参考

  • imap_rfc822_parse_adrlist() - アドレス文字列を解釈します


指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

  • ≪ imap_rfc822_parse_headers
  • imap_savebody ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

説明

imap_rfc822_write_address(string $mailbox, string $hostname, string $personal): string|false

指定された情報を » RFC822 の定義に基づき 適切にフォーマットされた電子メールアドレスにして返します。

パラメータ

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

hostname

email のホスト部分。

personal

アカウント所有者の名前。

戻り値

» RFC822 の定義に基づき 適切にフォーマットされた電子メールアドレスを返します。 失敗した場合に false を返します

例

例1 imap_rfc822_write_address() の例

<?php
echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
?>

上の例の出力は以下となります。

Hartmut Holzgraefe <hartmut@example.com>


指定した本文部をファイルに保存する

  • ≪ imap_rfc822_write_address
  • imap_scan ≫
  • PHP Manual
  • IMAP 関数
  • 指定した本文部をファイルに保存する

imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — 指定した本文部をファイルに保存する

説明

imap_savebody(
IMAP\Connection $imap,
resource|string|int $file,
int $message_num,
string $section = "",
int $flags = 0
): bool

指定したメッセージの本文全体、あるいはその一部を保存します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

file

保存先ファイルへのパスを表す文字列、あるいは fopen() が返すファイル記述子。

message_num

メッセージ番号。

section

パート番号。ピリオドで区切られた整数文字列を指定します。 これは、IMAP4 仕様における本文パートのリストへのインデックスとなります。

flags

ビットマスクであり、以下の組合わせとなります。

  • FT_UID - message_numは UID である
  • FT_PEEK - 既に設定されていない場合、 \Seen フラグを設定しない
  • FT_INTERNAL - 内部フォーマットで文字列を返す。CRLF に正規化しない。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す


imap_listscan のエイリアス

  • ≪ imap_savebody
  • imap_scanmailbox ≫
  • PHP Manual
  • IMAP 関数
  • imap_listscan のエイリアス

imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — imap_listscan() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_listscan().


imap_listscan のエイリアス

  • ≪ imap_scan
  • imap_search ≫
  • PHP Manual
  • IMAP 関数
  • imap_listscan のエイリアス

imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — imap_listscan() のエイリアス

説明

この関数は次の関数のエイリアスです。 imap_listscan().


指定した検索条件にマッチするメッセージを配列として返す

  • ≪ imap_scanmailbox
  • imap_set_quota ≫
  • PHP Manual
  • IMAP 関数
  • 指定した検索条件にマッチするメッセージを配列として返す

imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — 指定した検索条件にマッチするメッセージを配列として返す

説明

imap_search(
IMAP\Connection $imap,
string $criteria,
int $flags = SE_FREE,
string $charset = ""
): array|false

この関数は、指定した IMAP ストリームの現在オープンしているメールボックス において検索を行います。

例えば、Mom から送られた全ての未回答のメッセージにマッチさせるには、 "UNANSWERED FROM mom" を使用します。 検索は、大文字小文字が区別されずに行われます。 検索条件のリストは、UW c-client のソースコードからのものであり、 不完全または不正確である可能性があります (» RFC1176 の "tag SEARCH search_criteria" も参照ください)。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

criteria

空白で区切られた文字列で、以下のキーワードが使用可能です。 複数の単語からなるキーワード（例 FROM "joey smith"） は全て引用符で括る必要があります。 結果は、すべての criteria エントリにマッチすることになります。

  • ALL - 他の検索条件にマッチする全メッセージを返す
  • ANSWERED - \\ANSWERED フラグが設定されているメッセージにマッチ
  • BCC "string" - Bcc: フィールドに "string" を有するメッセージにマッチ
  • BEFORE "date" - "date" より前の Date: を有するメッセージにマッチ
  • BODY "string" - メッセージ本体に "string" を有するメッセージにマッチ
  • CC "string" - Cc: フィールドに "string" を有するメッセージにマッチ
  • DELETED - 削除されたメッセージにマッチ
  • FLAGGED - \\FLAGGED フラグ（重要または緊急を表すものとして 使用されることがあります）が設定されているメッセージにマッチ
  • FROM "string" - From: フィールドに "string" を有するメッセージにマッチ
  • KEYWORD "string" - キーワードとして "string" を有するメッセージにマッチ
  • NEW - 新規メッセージにマッチ
  • OLD - 古いメッセージにマッチ
  • ON "date" - Date: が "date" であるメッセージにマッチ
  • RECENT - \\RECENT フラグが設定されているメッセージにマッチ
  • SEEN - 既読の（\\SEEN フラグが設定されている）メッセージにマッチ
  • SINCE "date" - Date: が "date" 以降であるメッセージにマッチ
  • SUBJECT "string" - Subject: に "string" を有するメッセージにマッチ
  • TEXT "string" - テキスト "string" を有するメッセージにマッチ
  • TO "string" - To: に "string" を有するメッセージにマッチ
  • UNANSWERED - 未回答のメッセージにマッチ
  • UNDELETED - 削除されていないメッセージにマッチ
  • UNFLAGGED - フラグが設定されていないメッセージにマッチ
  • UNKEYWORD "string" - キーワード "string" を有さないメッセージにマッチ
  • UNSEEN - 未読のメッセージにマッチ

flags

flags に指定できる値は SE_UID です。これを指定すると、 メッセージ番号ではなく UID を含む配列を返します。

charset

文字列の検索の際に使う MIME 文字セット。

戻り値

メッセージ番号あるいは UID の配列を返します。

検索条件 criteria を処理できなかった場合や 結果が見つからなかった場合は、false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_search() の例

<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);

$some = imap_search($imap, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
$msgnos = imap_search($imap, 'ALL');
$uids = imap_search($imap, 'ALL', SE_UID);

print_r($some);
print_r($msgnos);
print_r($uids);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 4
    [1] => 6
    [2] => 11
)
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
    [5] => 6
)
Array
(
    [0] => 1
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 11
    [5] => 12
)

参考

  • imap_listscan() - 指定したテキストにマッチするメールボックスの一覧を返す


指定したメールボックスにクォータを設定する

  • ≪ imap_search
  • imap_setacl ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメールボックスにクォータを設定する

imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — 指定したメールボックスにクォータを設定する

説明

imap_set_quota(IMAP\Connection $imap, string $quota_root, int $mailbox_size): bool

メールボックス単位でクォータ上限(最大容量)を設定します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

quota_root

クォータを設定するメールボックス。 これは、メールボックスの IMAP 標準フォーマット 'user.name' に基づき指定する必要があります。

mailbox_size

quota_root の最大サイズ (KB 単位)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_set_quota() の例

<?php
$mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
echo "クォータの設定に失敗\n";
return;
}

imap_close($mbox);
?>

注意

この関数は、現在は c-client2000 以降のライブラリのユーザーのみ使用可能です。

メール管理者のアカウントでオープンされている imap が必要です。 他のユーザーでオープンされている場合は、この関数は動作しません。

参考

  • imap_open() - メールボックスへの IMAP ストリームをオープンする
  • imap_get_quota() - クオータレベルの設定、メールボックス毎の使用状況を取得する


指定したメールボックスの ACL を設定する

  • ≪ imap_set_quota
  • imap_setflag_full ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメールボックスの ACL を設定する

imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — 指定したメールボックスの ACL を設定する

説明

imap_setacl(
IMAP\Connection $imap,
string $mailbox,
string $user_id,
string $rights
): bool

指定したメールボックスの ACL を設定します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

user_id

権限を付与するユーザー。

rights

そのユーザーに付与する権限。空文字列を渡すと、acl を削除します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

注意

この関数は、現在 c-client2000 以降のユーザーのみ使用可能です。

参考

  • imap_getacl() - 与えられたメールボックスの ACL を取得する


メッセージにフラグをセットする

  • ≪ imap_setacl
  • imap_sort ≫
  • PHP Manual
  • IMAP 関数
  • メッセージにフラグをセットする

imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — メッセージにフラグをセットする

説明

imap_setflag_full(
IMAP\Connection $imap,
string $sequence,
string $flag,
int $options = 0
): true

この関数は、指定した sequence のメッセージの フラグに指定した flag を設定し、保存します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

sequence

メッセージ番号のシーケンス。 X,Y 形式でメッセージを列挙したり、 X:Y 形式で範囲内のすべてのメッセージを指定したりすることができます。

flag

設定可能なフラグは、(» RFC2060 で定義された) \Seen、 \Answered、\Flagged、 \Deleted および \Draft です。

options

options はビットマスクであり、以下の組み合わせとなります。

  • ST_UID - シーケンス引数はシーケンス番号の代わりに UID を含みます。

戻り値

常に true を返します。

エラー / 例外

options が無効な場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | options が無効な値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、false を返していました。

例

例1 imap_setflag_full() の例

<?php
$mbox = imap_open("{imap.example.org:143}", "username", "password")
or die("接続できません: " . imap_last_error());

$status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

echo gettype($status) . "\n";
echo $status . "\n";

imap_close($mbox);
?>

参考

  • imap_clearflag_full() - メッセージのフラグをクリアする


メッセージヘッダの配列をソートする

  • ≪ imap_setflag_full
  • imap_status ≫
  • PHP Manual
  • IMAP 関数
  • メッセージヘッダの配列をソートする

imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — メッセージヘッダの配列をソートする

説明

imap_sort(
IMAP\Connection $imap,
int $criteria,
bool $reverse,
int $flags = 0,
?string $search_criteria = null,
?string $charset = null
): array|false

指定したパラメータにより取得したメッセージ番号をソートします。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

criteria

criteria は、次のどれかとします (ひとつのみ)。

  • SORTDATE - メッセージの日付
  • SORTARRIVAL - 到着日付
  • SORTFROM - 最初の From アドレスのメールボックス
  • SORTSUBJECT - メッセージ Subject
  • SORTTO - 最初の To アドレスのメールボックス
  • SORTCC - 最初の cc アドレスのメールボックス
  • SORTSIZE - メッセージのサイズ（バイト単位）

reverse

逆順にソートするかどうかを指定します。

flags

flags はビットマスクで、以下の組み合わせとなります。

  • SE_UID - シーケンス番号の代わりに UID を返す
  • SE_NOPREFETCH - 検索したメッセージを事前取得しない

search_criteria

IMAP2 フォーマットの検索条件文字列。詳細は imap_search() を参照ください。

charset

文字列の検索の際に使う MIME 文字セット。

戻り値

指定したパラメータでソートしたメッセージ番号の配列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。
8.0.0 | reverse の型が、int から bool に変更されました。
8.0.0 | search_criteria, charset は、 nullable になりました。


現在のメールボックス以外のメールボックスのステータス情報を返す

  • ≪ imap_sort
  • imap_subscribe ≫
  • PHP Manual
  • IMAP 関数
  • 現在のメールボックス以外のメールボックスのステータス情報を返す

imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — 現在のメールボックス以外のメールボックスのステータス情報を返す

説明

imap_status(IMAP\Connection $imap, string $mailbox, int $flags): stdClass|false

指定したメールボックス mailbox についてのステータス情報を取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

flags

以下のフラグが使用できます。

  • SA_MESSAGES - $status->messages にメールボックスのメッセージ数を設定する
  • SA_RECENT - $status->recent にメールボックスの最近のメッセージ数を設定する
  • SA_UNSEEN - $status->unseen にメールボックスの未読の(新規)メッセージ数を設定する
  • SA_UIDNEXT - $status->uidnext にメールボックスの次の UID を設定する
  • SA_UIDVALIDITY - メールボックスの UID がもはや有効ではない場合に変化する定数を $status->uidvalidity に設定する
  • SA_ALL - 上記のものをすべて設定する

戻り値

この関数は、ステータス情報を含むオブジェクトを返します。 失敗した場合に false を返します。 このオブジェクトには messages、 recent、unseen、 uidnext および uidvalidity というプロパティが含まれます。

flags にも、 上の各定数に対応するビットマスクを設定することができます。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_status() の例

<?php
$mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
or die("接続できません: " . imap_last_error());

$status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
if ($status) {
echo "Messages: " . $status->messages . "<br />\n";
echo "Recent: " . $status->recent . "<br />\n";
echo "Unseen: " . $status->unseen . "<br />\n";
echo "UIDnext: " . $status->uidnext . "<br />\n";
echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";
} else {
echo "imap_status failed: " . imap_last_error() . "\n";
}

imap_close($mbox);
?>


メールボックスを購読する

  • ≪ imap_status
  • imap_thread ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスを購読する

imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — メールボックスを購読する

説明

imap_subscribe(IMAP\Connection $imap, string $mailbox): bool

新規メールボックスを購読します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_unsubscribe() - メールボックスの購読をやめる


スレッド化したメッセージのツリーを返す

  • ≪ imap_subscribe
  • imap_timeout ≫
  • PHP Manual
  • IMAP 関数
  • スレッド化したメッセージのツリーを返す

imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — スレッド化したメッセージのツリーを返す

説明

imap_thread(IMAP\Connection $imap, int $flags = SE_FREE): array|false

スレッド化されたメッセージのツリーを取得します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

flags

戻り値

imap_thread() は、REFERENCES でスレッド化したメッセージのツリーを含む連想配列を返します。 エラー時には false を返します。

現在のメールボックス内のすべてのメッセージが、結果の配列の 3 つの エントリで表されます。

  • $thread["XX.num"] - 現在のメッセージ番号。

  • $thread["XX.next"]

  • $thread["XX.branch"]

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

例

例1 imap_thread() の例

<?php

// ここでは、ニュースグループのスレッドを HTML で出力します。

$nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
$threads = imap_thread($nntp);

foreach ($threads as $key => $val) {
$tree = explode('.', $key);
if ($tree[1] == 'num') {
$header = imap_headerinfo($nntp, $val);
echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
} elseif ($tree[1] == 'branch') {
echo "\t</li>\n</ul>\n";
}
}

imap_close($nntp);

?>


imap タイムアウトを設定あるいは取得する

  • ≪ imap_thread
  • imap_uid ≫
  • PHP Manual
  • IMAP 関数
  • imap タイムアウトを設定あるいは取得する

imap_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — imap タイムアウトを設定あるいは取得する

説明

imap_timeout(int $timeout_type, int $timeout = -1): int|bool

imap タイムアウトを設定あるいは取得します。

パラメータ

timeout_type

IMAP_OPENTIMEOUT、 IMAP_READTIMEOUT、 IMAP_WRITETIMEOUT あるいは IMAP_CLOSETIMEOUT のいずれか。

timeout

タイムアウト秒数。

戻り値

timeout が設定されている場合は、 この関数は成功した場合に true、失敗した場合に false を返します。

timeout が省略されていたり、-1 と評価される値が設定されている場合は、 現在のタイムアウト値 timeout_type を整数で返します。

例

例1 imap_timeout() の例

<?php

echo "現在の読み込みタイムアウト秒数は " . imap_timeout(IMAP_READTIMEOUT) . " です\n";

?>


指定したメッセージシーケンス番号の UID を返す

  • ≪ imap_timeout
  • imap_undelete ≫
  • PHP Manual
  • IMAP 関数
  • 指定したメッセージシーケンス番号の UID を返す

imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — 指定したメッセージシーケンス番号の UID を返す

説明

imap_uid(IMAP\Connection $imap, int $message_num): int|false

この関数は、指定したメッセージシーケンス番号の UID を返します。 メッセージ番号はメールボックスの内容を変更する度に変わる可能性が ありますが、UID はユニークな ID であり時間が経過しても変わりません。

この関数は、imap_msgno() の逆関数です。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_num

メッセージ番号。

戻り値

指定したメッセージの UID を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

注意

注意:

この関数は、POP3 メールボックスではサポートされません。

参考

  • imap_msgno() - 指定した UID のメッセージ番号を返す


削除マークがついているメッセージのマークをはずす

  • ≪ imap_uid
  • imap_unsubscribe ≫
  • PHP Manual
  • IMAP 関数
  • 削除マークがついているメッセージのマークをはずす

imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — 削除マークがついているメッセージのマークをはずす

説明

imap_undelete(IMAP\Connection $imap, string $message_nums, int $flags = 0): true

指定したメッセージについて、 imap_delete() または imap_mail_move() で設定された削除フラグをはずします。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

message_nums

IMAP4 形式のシーケンスフォーマット ("n", "n:m", またはそれらをカンマで区切ったもの) で表現された、ひとつ以上のメッセージを表す文字列。

flags

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_delete() - 現在のメールボックスから削除するメッセージに印を付ける
  • imap_mail_move() - 指定されたメッセージをメールボックスに移動する


メールボックスの購読をやめる

  • ≪ imap_undelete
  • imap_utf7_decode ≫
  • PHP Manual
  • IMAP 関数
  • メールボックスの購読をやめる

imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — メールボックスの購読をやめる

説明

imap_unsubscribe(IMAP\Connection $imap, string $mailbox): bool

指定されたメールボックス mailbox の購読を中止します。

パラメータ

imap

IMAP\Connection クラスのインスタンス。

mailbox

メールボックス名。詳細は imap_open() を参照ください。

警告

信頼できないデータをこのパラメータに渡すのであれば、 imap.enable_insecure_rsh を無効にしておかなければ危険です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 imap は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な imap リソース が期待されていました。

参考

  • imap_subscribe() - メールボックスを購読する


修正版 UTF-7 エンコードされた文字列をデコードする

  • ≪ imap_unsubscribe
  • imap_utf7_encode ≫
  • PHP Manual
  • IMAP 関数
  • 修正版 UTF-7 エンコードされた文字列をデコードする

imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — 修正版 UTF-7 エンコードされた文字列をデコードする

説明

imap_utf7_decode(string $string): string|false

修正版 UTF-7 の string を ISO-8859-1 文字列に デコードします。

この関数は、ある種の非 ASCII 文字を含むメールボックス名をデコードする際に 必要となります。

パラメータ

string

修正版 UTF-7 エンコーディングの文字列。このエンコーディングについては » RFC 2060, section 5.1.3 で定義されています。

戻り値

string と同じ内容の文字を ISO-8859-1 でエンコード した文字列を返します。string に修正版 UTF-7 として 不正な文字が含まれていた場合、あるいは string に ISO-8859-1 文字セットの範囲外の文字が含まれていた場合には false を返します。

参考

  • imap_utf7_encode() - ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する


ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

  • ≪ imap_utf7_decode
  • imap_utf8 ≫
  • PHP Manual
  • IMAP 関数
  • ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

説明

imap_utf7_encode(string $string): string

string を修正版 UTF-7 テキストに変換します。

この関数は、ある種の非 ASCII 文字を含むメールボックス名をエンコード する際に必要となります。

パラメータ

string

ISO-8859-1 文字列。

戻り値

string を修正版 UTF-7 でエンコードした文字列を返します。 このエンコーディングについては » RFC 2060, section 5.1.3 で定義されています。

参考

  • imap_utf7_decode() - 修正版 UTF-7 エンコードされた文字列をデコードする


MIME エンコードされたテキストを UTF-8 に変換する

  • ≪ imap_utf7_encode
  • imap_utf8_to_mutf7 ≫
  • PHP Manual
  • IMAP 関数
  • MIME エンコードされたテキストを UTF-8 に変換する

imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する

説明

imap_utf8(string $mime_encoded_text): string

宣言されている文字セットを libc-client が知っている場合は、 指定した mime_encoded_text を UTF-8 に変換します。 知らない場合は、指定されたテキストはデコードされますが、UTF-8 には変換されません。

パラメータ

mime_encoded_text

MIME エンコードされた文字列。 MIME エンコーディング方法および UTF-8 の仕様については、それぞれ » RFC2047 および » RFC2044 を参照ください。

戻り値

デコードされた文字列。可能な場合は UTF-8 に変換されます。

例

例1 Basic imap_utf8() の使い方

<?php
echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
?>

上の例の出力は、 たとえば以下のようになります。

Johannes SchluI?ter

参考

  • imap_mime_header_decode() - MIME ヘッダ要素をデコードする


UTF-8 文字列を修正UTF-7にエンコードする

  • ≪ imap_utf8
  • IMAP\Connection ≫
  • PHP Manual
  • IMAP 関数
  • UTF-8 文字列を修正UTF-7にエンコードする

imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする

説明

imap_utf8_to_mutf7(string $string): string|false

UTF-8 文字列を、修正UTF-7(RFC 2060, section 5.1.3)にエンコードします。

注意:

この関数は libcclient が utf8_to_mutf7() をエクスポートした場合にのみ利用できます。

パラメータ

string

UTF-8 エンコードされた文字列

戻り値

string を修正UTF-7に変換したものを返します。 失敗した場合に false を返します.

参考

  • imap_mutf7_to_utf8() - 修正UTF-7文字列をUTF-8にデコードする


IMAP\Connection クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、imap リソースを置き換える、 完全不定形クラスです。

クラス概要

final class IMAP\Connection {
}


メール

  • はじめに
  • インストール/設定
    • 要件
    • 実行時設定
  • メール 関数
    • ezmlm_hash — EZMLM で必要なハッシュ値を計算する
    • mail — メールを送信する


  • ≪ メール
  • インストール/設定 ≫
  • PHP Manual
  • メール
  • はじめに

はじめに

mail() 関数によりメールを送信できるようになります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • メール
  • インストール/設定

インストール/設定

目次

  • 要件
  • 実行時設定


要件

メール関数を使用可能にするには、PHP のコンパイル時点でシステム上の sendmail バイナリにアクセスできなければなりません。 qmail や postfix など他のメールプログラムを使用してる場合には、 それらのソフトに付随する適当な sendmail ラッパーを使用するように 気をつけてください。 PHP は sendmail を探す際にまず PATH を見ます。次に /usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib の順で探します。PATH を通して sendmail を使用可能な 状態にしておくことが強く推奨されます。 また、コンパイルされた PHP が sendmail バイナリにアクセスできる権限を 持っていなければなりません。


実行時設定

php.ini の設定により動作が変化します。

Mail 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mail.add_x_header | "0" | INI_PERDIR |
mail.log | NULL | INI_SYSTEM|INI_PERDIR |
mail.force_extra_parameters | NULL | INI_SYSTEM|INI_PERDIR |
SMTP | "localhost" | INI_ALL |
smtp_port | "25" | INI_ALL |
sendmail_from | NULL | INI_ALL |
sendmail_path | "/usr/sbin/sendmail -t -i" | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mail.add_x_header bool

X-PHP-Originating-Script を追加します。 それはスクリプトの UID を含み、その後にファイル名が続きます。

mail.log string

ログファイルへのパス。mail() がコールされるたびにこのファイルに記録します。 ログに含まれる内容は、スクリプトのフルパスと行番号、そして To アドレスとヘッダです。

mail.force_extra_parameters string

指定したパラメータを、sendmail バイナリへの追加パラメータとして強制的に渡します。 これらのパラメータは、常に mail() の第 5 パラメータの値を上書きします。

SMTP string

Windows 環境のみで使用されます: mail() 関数でメールを送信する際に使用する SMTP サーバーのホスト名または IP アドレス。

smtp_port int

Windows 環境のみで使用されます: SMTP 設定で指定したサーバーに接続するポート番号で、 デフォルトは 25 です。

sendmail_from string

SMTP 経由で直接送信されるメールにおいて "From:" に使用するメールアドレスを指定します(Windows環境のみ)。 このディレクティブは、"Return-Path:" ヘッダも設定します。

sendmail_path string

sendmail プログラムを探すパスを指定します。 通常、/usr/sbin/sendmail または /usr/lib/sendmail です。 configure は、このパスを探し、 デフォルト値として設定しますが、 これで上手くいかない場合にはこのオプションで設定する必要があります。

sendmail を使用していないシステムは、 使用するメールシステムが提供する sendmail のラッパー/代替品を、 必要に応じてこのディレクティブに設定する必要があります。例えば、» Qmail ユーザーは、通常 /var/qmail/bin/sendmail または /var/qmail/bin/qmail-inject に設定します。

qmail-inject では、 メールを正しく処理するためのオプション設定は不要です。

このディレクティブは Windows 環境でも動作します。指定された場合は smtp および smtp_port・ sendmail_from の値は無視され、 ここで指定したコマンドが実行されます。


メール 関数

目次

  • ezmlm_hash — EZMLM で必要なハッシュ値を計算する
  • mail — メールを送信する


EZMLM で必要なハッシュ値を計算する

  • ≪ メール 関数
  • mail ≫
  • PHP Manual
  • メール 関数
  • EZMLM で必要なハッシュ値を計算する

ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — EZMLM で必要なハッシュ値を計算する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

ezmlm_hash(string $addr): int

ezmlm_hash() は、EZMLM メイリングリストを MySQL データベースで管理する際に必要なハッシュ値を計算します。

パラメータ

addr

ハッシュ値を計算する email アドレス。

戻り値

addr のハッシュ値を返します。

例

例1 ハッシュ値を計算し、ユーザーを登録する

<?php

$user = "joecool@example.com";
$hash = ezmlm_hash($user);
$query = sprintf("INSERT INTO sample VALUES (%s, '%s')", $hash, $user);
$db->query($query); // PHPLIB dbインターフェイスを使用します

?>


メールを送信する

  • ≪ ezmlm_hash
  • Mailparse ≫
  • PHP Manual
  • メール 関数
  • メールを送信する

mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — メールを送信する

説明

mail(
string $to,
string $subject,
string $message,
array|string $additional_headers = [],
string $additional_params = ""
): bool

メールを送信します。

パラメータ

to

メールの受信者。

» RFC 2822 を満たす書式でなければ なりません。例えば以下のようなものです。

  • user@example.com
  • user@example.com, anotheruser@example.com
  • User
  • User , Another User

subject

送信するメールの表題。

警告

表題は » RFC 2047 を満たすものでなければなりません。

message

送信するメッセージ。

改行コードは CRLF (\r\n) となります。各行の長さは 70 文字を超えては いけません。

警告

（Windows のみ）PHP が SMTP サーバーと直接通信をする際、ピリオドから 始まる行は無視されます。これを防ぐには、行頭のピリオドを ピリオド 2 つに置き換えてください。

<?php
$text = str_replace("\n.", "\n..", $text);
?>

additional_headers（オプション）

メールヘッダの最後に挿入される String または array。

通常、これは追加のヘッダ（From、Cc、Bcc）のために用いられます。 複数のヘッダを追加する場合は CRLF（\r\n）で区切ります。 外部からのデータを用いてヘッダを組み立てる際には、想定外のヘッダが注入されることを防ぐための処理が必要です。

array が渡されると、キーがヘッダの名前となり、 値がそれぞれのヘッダの値になります。

注意:

メールを送信する際には、必ず From ヘッダが含まれていなければなりません。 additional_headers パラメータで指定するか、 あるいは php.ini にデフォルト値を指定します。

指定しなかった場合は、以下のようなエラーメッセージが返ります Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing 。 Windows では、SMTP経由で直接メールを送信する際は、 From ヘッダを設定すると Return-Path も設定されます。

注意:

メッセージが受信されなかった場合には、LF（\n）のみを使ってみてください。 Unix の MTA の中には、自動的に LF を CRLF に変換してしまう もの (有名なところでは、» qmail など) があります（もし CRLF を利用していた場合、CR が重複してしまいます）。 ただし、これは最後の手段です。というのも、これは » RFC 2822 に違反しているからです。

additional_params（オプション）

パラメータ additional_params は、 追加のフラグをコマンドラインオプションとしてメール送信プログラムに渡す際に使用可能です。 メール送信プログラムは、設定オプション sendmail_path により設定されます。例えば、 sendmail を使用する際に -f オプションを使って エンベロープの sender アドレスを設定する際に使用できます。

このパラメータはコマンドの実行を防止するために内部的に escapeshellcmd() によってエスケープされます。 escapeshellcmd() はコマンドの実行を防止しますが、 別のパラメータを追加することは許してしまいます。セキュリティ上の理由から、 シェルコマンドへの望ましくないパラメータの追加を避けるために、 ユーザーはこのパラメータを適切に処理することが推奨されます。

escapeshellcmd() が自動的に適用されるため、 インターネット RFC でメールアドレスとして許可さているいくつかの文字を使用することができません。 mail() はそうした文字を許可しないため、プログラム中でそうした文字の使用が必須である場合、 メール送信の代替手段（フレームワークやライブラリの使用など）が推奨されます。

この方法でエンベロープの sender ヘッダ（-f）を設定する際は、 'X-Warning' ヘッダが付加されないように Web サーバーの実行ユーザーを sendmail 設定に追加しておく必要があるかもしれません。 sendmail を利用している場合、これは /etc/mail/trusted-users で設定します。

戻り値

メール送信が受け入れられた場合に true 、それ以外の場合に false を返します。

メールの配送が受け入れられたかどうかが基準であることに注意しましょう。 メールが実際にあて先に届いたかどうかでは「ありません」。

変更履歴

バージョン | 説明
7.2.0 | additional_headers パラメータは、 array も受け入れるようになりました。

例

例1 メールを送信する

mail() を用いて単純なメールを送信する。

<?php
// 本文
$message = "Line 1\r\nLine 2\r\nLine 3";

// 1 行が 70 文字を超える場合のため、wordwrap() を用いる
$message = wordwrap($message, 70, "\r\n");

// 送信する
mail('caffeinated@example.com', 'My Subject', $message);
?>

例2 追加ヘッダを付加してメールを送信する

基本ヘッダに加え、MUA に From および Reply-To アドレスを通知する。

<?php
$to = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = 'From: webmaster@example.com' . "\r\n" .
'Reply-To: webmaster@example.com' . "\r\n" .
'X-Mailer: PHP/' . phpversion();

mail($to, $subject, $message, $headers);
?>

例3 追加のヘッダを array で指定してメールを送信する

この例は、すぐ上の例と同じメールを送信します。 しかし、追加のヘッダを配列で渡しています (PHP 7.2.0 以降で利用可能)

<?php
$to = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = array(
'From' => 'webmaster@example.com',
'Reply-To' => 'webmaster@example.com',
'X-Mailer' => 'PHP/' . phpversion()
);

mail($to, $subject, $message, $headers);
?>

例4 追加のコマンドラインパラメータを指定してメールを送信する

sendmail_path を用いてメールを送信する際に利用する 追加パラメータとして、additional_params が用いられます。

<?php
mail('nobody@example.com', 'the subject', 'the message', null,
'-fwebmaster@example.com');
?>

例5 HTML メールを送信する

mail() を用いて HTML メールを送信することも可能です。

<?php
// 複数の受信者を指定
$to = 'johny@example.com, sally@example.com'; // カンマに注意

// 表題
$subject = 'Birthday Reminders for August';

// 本文
$message = '
<html>
<head>
<title>Birthday Reminders for August</title>
</head>
<body>
<p>Here are the birthdays upcoming in August!</p>
<table>
<tr>
<th>Person</th><th>Day</th><th>Month</th><th>Year</th>
</tr>
<tr>
<td>Johny</td><td>10th</td><td>August</td><td>1970</td>
</tr>
<tr>
<td>Sally</td><td>17th</td><td>August</td><td>1973</td>
</tr>
</table>
</body>
</html>
';

// HTML メールを送信するには Content-type ヘッダが必須
$headers[] = 'MIME-Version: 1.0';
$headers[] = 'Content-type: text/html; charset=iso-8859-1';

// 追加のヘッダ
$headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
$headers[] = 'From: Birthday Reminder <birthday@example.com>';
$headers[] = 'Cc: birthdayarchive@example.com';
$headers[] = 'Bcc: birthdaycheck@example.com';

// 送信する
mail($to, $subject, $message, implode("\r\n", $headers));
?>

注意:

HTML などの複雑な形式のメールを送信する場合は、PEAR パッケージ » PEAR::Mail_Mime を利用することを推奨します。

注意

注意:

Windows 環境での mail() のSMTP実装は、sendmail の実装とは 多くの点で違います。 第一に、メッセージの生成にローカルのバイナリは使用せず、 ソケットを通じて直接操作するだけです。 これは MTA がネットワークソケットを listen している 必要があるということを意味します（ローカルホスト、リモートマシン どちらでもかまいません）。

第二に、 From: や Cc:・ Bcc:・ Date: のようなカスタムヘッダは MTA ではなく PHP によってパースされます。

そのため、to 引数には "Something <someone@example.com>" 形式の メールアドレスを与えることはできません。 MTA と通信する際に mail コマンドはこれを適切にパースできません。

注意:

mail() 関数は、大量のメールをループ内で送信するには 向いていないことに注意しましょう。この関数は 1 通のメールを送信するたびに SMTP ソケットをいったん閉じて開きなおします。これは非効率的です。

大量のメールを送信する場合は、 » PEAR::Mail および » PEAR::Mail_Queue パッケージを参照ください。

注意:

以下の RFC も有用です。 » RFC 1896、 » RFC 2045、 » RFC 2046、 » RFC 2047、 » RFC 2048、 » RFC 2049 および » RFC 2822

参考

  • mb_send_mail() - エンコード変換を行ってメールを送信する
  • imap_mail() - e-mail メッセージを送信する
  • » PEAR::Mail
  • » PEAR::Mail_Mime


Mailparse

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • Mailparse 関数
    • mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する
    • mailparse_msg_create — mime メールリソースを作成する
    • mailparse_msg_extract_part — メッセージセクションを展開/デコードする
    • mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする
    • mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する
    • mailparse_msg_free — MIME リソースを解放する
    • mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す
    • mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す
    • mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す
    • mailparse_msg_parse — データをパースし、バッファに追加する
    • mailparse_msg_parse_file — ファイルをパースする
    • mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする
    • mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む
    • mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する


はじめに

Mailparse は、電子メールのメッセージをパースして処理するための拡張モジュールです。 » RFC 822 および » RFC 2045 (MIME) に準拠したメッセージを扱うことができます。

Mailparse はストリームベースで動作します。つまり、 処理する際にファイルの内容をメモリにコピーする必要がないということです。 これにより、大きなメッセージを扱う際にリソースを効率的に使用することができます。

注意:

Mailparse には、mbstring 拡張モジュールが必要です。 また、mbstring は mailparse より前に読み込まれていなければなりません。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Mailparse
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定
  • リソース型


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mailparse.

これらの関数を使用するためには、configure 時に --enable-mailparse オプションを指定し、 mailparse のサポートつきで PHP をコンパイルする必要があります。

Windows ユーザーがこれらの関数を利用するには、php.ini の中で php_mailparse.dll を有効にします。 この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

mailparse を使うには、事前に mbstring 拡張モジュールを読み込んでおく必要があります。


実行時設定

php.ini の設定により動作が変化します。

Mailparse 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
mailparse.def_charset | "us-ascii" | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

mailparse.def_charset string

デフォルトの文字セット。


リソース型

Mailparse は、 リソース型 mailparse_mail_structure を定義しています。 これは、mailparse_msg_create() や mailparse_msg_parse_file() から返されるものです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。


Mailparse 関数

目次

  • mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する
  • mailparse_msg_create — mime メールリソースを作成する
  • mailparse_msg_extract_part — メッセージセクションを展開/デコードする
  • mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする
  • mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する
  • mailparse_msg_free — MIME リソースを解放する
  • mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す
  • mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す
  • mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す
  • mailparse_msg_parse — データをパースし、バッファに追加する
  • mailparse_msg_parse_file — ファイルをパースする
  • mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする
  • mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む
  • mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する


最も適したエンコーディングを取得する

  • ≪ Mailparse 関数
  • mailparse_msg_create ≫
  • PHP Manual
  • Mailparse 関数
  • 最も適したエンコーディングを取得する

mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する

説明

mailparse_determine_best_xfer_encoding(resource $fp): string

ファイルポインタから内容を読み込む際に最も適したエンコーディングを調べます。

パラメータ

fp

有効なファイルポインタ。これはシーク可能である必要があります。

戻り値

mbstring モジュールがサポートする文字エンコーディングのいずれかを返します。

例

例1 mailparse_determine_best_xfer_encoding() の例

<?php

$fp = fopen('somemail.eml', 'r');
echo 'Best encoding: ' . mailparse_determine_best_xfer_encoding($fp);

?>

上の例の出力は、 たとえば以下のようになります。

Best encoding: 7bit


mime メールリソースを作成する

  • ≪ mailparse_determine_best_xfer_encoding
  • mailparse_msg_extract_part ≫
  • PHP Manual
  • Mailparse 関数
  • mime メールリソースを作成する

mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — mime メールリソースを作成する

説明

mailparse_msg_create(): resource

MIME メールリソースを作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

メッセージのパースに使用するハンドルを返します。

注意

注意:

この関数が作成したリソースが必要なくなった際は、 メモリリークを避けるため mailparse_msg_free() をコールすることを推奨します。

参考

  • mailparse_msg_free() - MIME リソースを解放する
  • mailparse_msg_parse_file() - ファイルをパースする


メッセージセクションを展開/デコードする

  • ≪ mailparse_msg_create
  • mailparse_msg_extract_part_file ≫
  • PHP Manual
  • Mailparse 関数
  • メッセージセクションを展開/デコードする

mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — メッセージセクションを展開/デコードする

説明

mailparse_msg_extract_part(resource $mimemail, string $msgbody, callable $callbackfunc = ?): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

msgbody

callbackfunc

戻り値

値を返しません。

参考

  • mailparse_msg_extract_part_file() - メッセージセクションを展開/デコードする
  • mailparse_msg_extract_whole_part_file() - ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する


メッセージセクションを展開/デコードする

  • ≪ mailparse_msg_extract_part
  • mailparse_msg_extract_whole_part_file ≫
  • PHP Manual
  • Mailparse 関数
  • メッセージセクションを展開/デコードする

mailparse_msg_extract_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする

説明

mailparse_msg_extract_part_file(resource $mimemail, mixed $filename, callable $callbackfunc = ?): string

指定したファイル名のメッセージセクションを展開/デコードします。

セクションの内容は、transfer encoding に応じて適切にデコードされます。 base64、quoted-printable および uuencode 形式をサポートしています。

パラメータ

mimemail

mailparse_msg_create() で作成した MIME リソース。

filename

ファイル名あるいは有効なストリームリソース。

callbackfunc

展開されたセクションに渡されるコールバック関数、あるいは null を指定すると、この関数は展開したセクションを返します。

省略した場合は標準出力に出力されます。

戻り値

callbackfunc が null でない場合は、 成功時に true を返します。

callbackfunc が null の場合は、 展開したセクションを文字列で返します。

エラー時には false を返します。

参考

  • mailparse_msg_extract_part() - メッセージセクションを展開/デコードする
  • mailparse_msg_extract_whole_part_file() - ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する


ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

  • ≪ mailparse_msg_extract_part_file
  • mailparse_msg_free ≫
  • PHP Manual
  • Mailparse 関数
  • ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

説明

mailparse_msg_extract_whole_part_file(resource $mimemail, string $filename, callable $callbackfunc = ?): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

filename

callbackfunc

戻り値

参考

  • mailparse_msg_extract_part() - メッセージセクションを展開/デコードする
  • mailparse_msg_extract_part_file() - メッセージセクションを展開/デコードする


MIME リソースを解放する

  • ≪ mailparse_msg_extract_whole_part_file
  • mailparse_msg_get_part ≫
  • PHP Manual
  • Mailparse 関数
  • MIME リソースを解放する

mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — MIME リソースを解放する

説明

mailparse_msg_free(resource $mimemail): bool

MIME リソースを解放します。

パラメータ

mimemail

mailparse_msg_create() あるいは mailparse_msg_parse_file() が割り当てた 有効な MIME リソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • mailparse_msg_create() - mime メールリソースを作成する
  • mailparse_msg_parse_file() - ファイルをパースする


MIME メッセージの指定したセクションに関するハンドルを返す

  • ≪ mailparse_msg_free
  • mailparse_msg_get_part_data ≫
  • PHP Manual
  • Mailparse 関数
  • MIME メッセージの指定したセクションに関するハンドルを返す

mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す

説明

mailparse_msg_get_part(resource $mimemail, string $mimesection): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。

mimesection


メッセージに関する情報の連想配列を返す

  • ≪ mailparse_msg_get_part
  • mailparse_msg_get_structure ≫
  • PHP Manual
  • Mailparse 関数
  • メッセージに関する情報の連想配列を返す

mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す

説明

mailparse_msg_get_part_data(resource $mimemail): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。


指定したメッセージ内の MIME セクション名の配列を返す

  • ≪ mailparse_msg_get_part_data
  • mailparse_msg_parse ≫
  • PHP Manual
  • Mailparse 関数
  • 指定したメッセージ内の MIME セクション名の配列を返す

mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す

説明

mailparse_msg_get_structure(resource $mimemail): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

mimemail

有効な MIME リソース。


データをパースし、バッファに追加する

  • ≪ mailparse_msg_get_structure
  • mailparse_msg_parse_file ≫
  • PHP Manual
  • Mailparse 関数
  • データをパースし、バッファに追加する

mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — データをパースし、バッファに追加する

説明

mailparse_msg_parse(resource $mimemail, string $data): bool

データを順にパースし、指定した mime メールリソースに格納します。

この関数により、ファイル全体を読み込んでからパースするのではなく 読み込んだ部分から順に処理していくことができます。

パラメータ

mimemail

有効な MIME リソース。

data

注意:

data の最後のチャンクは、 改行コード(CRLF) で終わることが想定されています。 そうでない場合、最後の行がパースされません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


ファイルをパースする

  • ≪ mailparse_msg_parse
  • mailparse_rfc822_parse_addresses ≫
  • PHP Manual
  • Mailparse 関数
  • ファイルをパースする

mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — ファイルをパースする

説明

mailparse_msg_parse_file(string $filename): resource

ファイルをパースします。 ディスク上にあるメールファイルをパースするための最良の方法です。

パラメータ

filename

メッセージを保持するファイルへのパス。 このファイルがオープンされ、ストリームとしてパーサに流し込まれます。

注意:

filename が保持するメッセージは、 改行コード(CRLF) で終わることが想定されています。 そうでない場合、最後の行がパースされません。

戻り値

構造を表す MIME リソース、あるいはエラー時に false を返します。

注意

注意:

この関数が作成したリソースが必要なくなった際は、 メモリリークを避けるため mailparse_msg_free() をコールすることを推奨します。

参考

  • mailparse_msg_free() - MIME リソースを解放する
  • mailparse_msg_create() - mime メールリソースを作成する


RFC 822 準拠のアドレスをパースする

  • ≪ mailparse_msg_parse_file
  • mailparse_stream_encode ≫
  • PHP Manual
  • Mailparse 関数
  • RFC 822 準拠のアドレスをパースする

mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする

説明

mailparse_rfc822_parse_addresses(string $addresses): array

» RFC 822 準拠の受信者リスト、 たとえば To: ヘッダの内容などをパースします。

パラメータ

addresses

アドレスを含む文字列。たとえば Wez Furlong <wez@example.com>, doe@example.com のようになります。

注意:

この文字列にはヘッダ名を含めてはいけません。

戻り値

各受信者について以下のキーをもつ連想配列の配列を返します。

display | 表示用の受信者名。この部分が設定されていない場合は、 address と同じ値となります。
address | メールアドレス。
is_group | 受信者がニュースグループである場合に true、そうでない場合に false。

例

例1 mailparse_rfc822_parse_addresses() の例

<?php

$to = 'Wez Furlong <wez@example.com>, doe@example.com';
var_dump(mailparse_rfc822_parse_addresses($to));

?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["display"]=>
    string(11) "Wez Furlong"
    ["address"]=>
    string(15) "wez@example.com"
    ["is_group"]=>
    bool(false)
  }
  [1]=>
  array(3) {
    ["display"]=>
    string(15) "doe@example.com"
    ["address"]=>
    string(15) "doe@example.com"
    ["is_group"]=>
    bool(false)
  }
}


ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

  • ≪ mailparse_rfc822_parse_addresses
  • mailparse_uudecode_all ≫
  • PHP Manual
  • Mailparse 関数
  • ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

mailparse_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

説明

mailparse_stream_encode(resource $sourcefp, resource $destfp, string $encoding): bool

ソースファイルポインタからストリームデータを取得し、 encoding を適用して それを出力ファイルポインタに書き込みます。

パラメータ

sourcefp

有効なファイルハンドル。このファイルからのストリームがパーサに流し込まれます。

destfp

エンコードしたデータを書き込むファイルハンドル。

encoding

mbstring モジュールがサポートする文字エンコーディングのいずれか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 mailparse_stream_encode() の例

<?php

// email.eml の中身は: hello, this is some text=hello.
$fp = fopen('email.eml', 'r');

$dest = tmpfile();

mailparse_stream_encode($fp, $dest, "quoted-printable");

rewind($dest);

// ファイルの内容を表示します
fpassthru($dest);

?>

上の例の出力は以下となります。

hello, this is some text=3Dhello.


ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

  • ≪ mailparse_stream_encode
  • 数学 ≫
  • PHP Manual
  • Mailparse 関数
  • ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

説明

mailparse_uudecode_all(resource $fp): array

指定したファイルポインタからのデータを読み込み、 uuencode されたファイルを一時ファイルに展開します。

パラメータ

fp

有効なファイルポインタ。

戻り値

ファイル名の情報を含む連想配列の配列を返します。

filename | 作成された一時ファイルへのパス。
origfilename | もとのファイル名。uuencode されたパートにのみ存在します。
最初の filename エントリがメッセージ本文、次のエントリがデコードされた uuencode ファイルとなります。

例

例1 mailparse_uudecode_all() の例

<?php

$text = <<<EOD
To: fred@example.com

hello, this is some text hello.
blah blah blah.

begin 644 test.txt
/=&AI<R!I<R!A('1E<W0*
`
end

EOD;

$fp = tmpfile();
fwrite($fp, $text);

$data = mailparse_uudecode_all($fp);

echo "BODY\n";
readfile($data[0]["filename"]);
echo "UUE ({$data[1]['origfilename']})\n";
readfile($data[1]["filename"]);

// 後始末をします
unlink($data[0]["filename"]);
unlink($data[1]["filename"]);

?>

上の例の出力は以下となります。

BODY
To: fred@example.com

hello, this is some text hello.
blah blah blah.

UUE (test.txt)
this is a test


数学

  • BC Math — BCMath 任意精度数学関数
    • はじめに
    • インストール/設定
    • BC Math 関数
  • GMP — GNU Multiple Precision
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GMP 関数
    • GMP — GMP クラス
  • Math — 数学関数
    • はじめに
    • 定義済み定数
    • Math 関数
  • Statistics
    • はじめに
    • インストール/設定
    • Statistic 関数
  • Trader — Technical Analysis for Traders
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Trader 関数


BCMath 任意精度数学関数

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • BC Math 関数
    • bcadd — 2つの任意精度の数値を加算する
    • bccomp — 2 つの任意精度数値を比較する
    • bcdiv — 2つの任意精度数値で除算を行う
    • bcmod — 2 つの任意精度数値の剰余を取得する
    • bcmul — 2つの任意精度数値の乗算を行う
    • bcpow — 任意精度数値をべき乗する
    • bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余
    • bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
    • bcsqrt — 任意精度数値の平方根を取得する
    • bcsub — 任意精度数値の減算を行う


はじめに

任意の精度の演算をサポートするために、PHP は 2147483647 (または 0x7FFFFFFF) までの 任意のサイズおよび精度の小数桁をサポートする BCMath を提供します。 十分なメモリがあれば、文字列表現もサポートします。

有効(別名 well-formed) な BCMath数 は、以下の正規表現にマッチする文字列です。 /^[+-]?[0-9]*(\.[0-9]*)?$/.

警告

string であることが期待されている float 型の値を BCMath 関数に渡してしまうと、 PHP が float 型の値を string 型に変換するやり方の影響で、 あなたが望む結果にならない可能性があります。 なぜなら、 string が、ネイピア数を使った表記 (これは BCMath では未サポートです) である可能性があったり、 PHP 8.0.0 以前では 小数点の記号がロケール依存(BCMath は常に小数点(.)を期待しています) であったりするためです。

<?php
$num1 = 0; // (string) 0 => '0'
$num2 = -0.000005; // (string) -0.000005 => '-5.05E-6'
echo bcadd($num1, $num2, 6); // => '0.000000'

setlocale(LC_NUMERIC, 'de_DE'); // 小数点がコンマになるロケール
$num2 = 1.2; // (string) 1.2 => '1,2'
echo bcsub($num1, $num2, 1); // => '0.0'
?>


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • BC Math
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

これらの関数は、PHPが構築オプション --enable-bcmath を付けてコンパイルされている場合にのみ使用できます。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


実行時設定

php.ini の設定により動作が変化します。

BC 数学関数設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
bcmath.scale | "0" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

bcmath.scale int

全ての bcmath 関数に関する 10 進桁数。 bcscale() も参照ください。


BC Math 関数

目次

  • bcadd — 2つの任意精度の数値を加算する
  • bccomp — 2 つの任意精度数値を比較する
  • bcdiv — 2つの任意精度数値で除算を行う
  • bcmod — 2 つの任意精度数値の剰余を取得する
  • bcmul — 2つの任意精度数値の乗算を行う
  • bcpow — 任意精度数値をべき乗する
  • bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余
  • bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
  • bcsqrt — 任意精度数値の平方根を取得する
  • bcsub — 任意精度数値の減算を行う


2つの任意精度の数値を加算する

  • ≪ BC Math 関数
  • bccomp ≫
  • PHP Manual
  • BC Math 関数
  • 2つの任意精度の数値を加算する

bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — 2つの任意精度の数値を加算する

説明

bcadd(string $num1, string $num2, ?int $scale = null): string

num1 を num2 に加算します。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

二つの数の和を文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | scale は nullable になりました。

例

例1 bcadd() の例

<?php

$a = '1.234';
$b = '5';

echo bcadd($a, $b); // 6
echo bcadd($a, $b, 4); // 6.2340

?>

参考

  • bcsub() - 任意精度数値の減算を行う


2 つの任意精度数値を比較する

  • ≪ bcadd
  • bcdiv ≫
  • PHP Manual
  • BC Math 関数
  • 2 つの任意精度数値を比較する

bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — 2 つの任意精度数値を比較する

説明

bccomp(string $num1, string $num2, ?int $scale = null): int

num1 と num2 を比較し、 結果を整数値で返します。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

オプションの scale パラメータで、 小数点以下の桁数を指定します。ここまでを使用して比較を行います。

戻り値

ふたつのオペランドが等しければ 0、 num1 が num2 より大きければ戻り値は 1、小さければ -1 を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

例1 bccomp() の例

<?php

echo bccomp('1', '2') . "\n"; // -1
echo bccomp('1.00001', '1', 3); // 0
echo bccomp('1.00001', '1', 5); // 1

?>


2つの任意精度数値で除算を行う

  • ≪ bccomp
  • bcmod ≫
  • PHP Manual
  • BC Math 関数
  • 2つの任意精度数値で除算を行う

bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — 2つの任意精度数値で除算を行う

説明

bcdiv(string $num1, string $num2, ?int $scale = null): string

num1 を num2 で除算します。

パラメータ

num1

被除数を表す文字列。

num2

割る数を表す文字列。

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

除算結果を文字列で返します。 num2 が 0 の場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

例1 bcdiv() の例

<?php

echo bcdiv('105', '6.55957', 3); // 16.007

?>

参考

  • bcmul() - 2つの任意精度数値の乗算を行う


2 つの任意精度数値の剰余を取得する

  • ≪ bcdiv
  • bcmul ≫
  • PHP Manual
  • BC Math 関数
  • 2 つの任意精度数値の剰余を取得する

bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — 2 つの任意精度数値の剰余を取得する

説明

bcmod(string $num1, string $num2, ?int $scale = null): string

num1 の、 num2 を法とする剰余を取得します。 num2 が 0でなければ、 結果は num1 と同じ符号を持ちます。

パラメータ

num1

被除数を表す文字列。

num2

割る数を表す文字列。

戻り値

剰余を文字列で返します。 num2 が 0 の場合は null を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は nullable になりました。
7.2.0 | num1 と num2 は 整数に切り詰められることがなくなりました。 よって、bcmod() の振る舞いは % 演算子ではなく、 fmod() に従うことになります。
7.2.0 | scale パラメータが追加されました。

例

例1 bcmod() の例

<?php
bcscale(0);
echo bcmod( '5', '3'); // 2
echo bcmod( '5', '-3'); // 2
echo bcmod('-5', '3'); // -2
echo bcmod('-5', '-3'); // -2
?>

例2 bcmod() に小数の値を指定する

<?php
bcscale(1);
echo bcmod('5.7', '1.3'); // 0.5 as of PHP 7.2.0; 0 previously
?>

参考

  • bcdiv() - 2つの任意精度数値で除算を行う


2つの任意精度数値の乗算を行う

  • ≪ bcmod
  • bcpow ≫
  • PHP Manual
  • BC Math 関数
  • 2つの任意精度数値の乗算を行う

bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — 2つの任意精度数値の乗算を行う

説明

bcmul(string $num1, string $num2, ?int $scale = null): string

num1 に num2 を掛けます。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

結果を文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。
7.3.0 | bcmul() 関数が、指定されたスケールの数値を返すようになりました。 これより前のバージョンでは、 返される数値の末尾が 0埋め されることなく、省略される可能性がありました。

例

例1 bcmul() の例

<?php
echo bcmul('1.34747474747', '35', 3); // 47.161
echo bcmul('2', '4'); // 8
?>

注意

注意:

PHP 7.3.0 より前のバージョンでは、 bcmul() は scale 引数で指定したものより少ない桁数を返す可能性がありました。 これは scale で許された精度が不要な場合にだけ起きていました。 たとえば、以下のような場合です:

例2 bcmul() で scale を指定する例

<?php
echo bcmul('5', '2', 2); // prints "10", not "10.00"
?>

参考

  • bcdiv() - 2つの任意精度数値で除算を行う


任意精度数値をべき乗する

  • ≪ bcmul
  • bcpowmod ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値をべき乗する

bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — 任意精度数値をべき乗する

説明

bcpow(string $num, string $exponent, ?int $scale = null): string

num の exponent 乗を求めます。

パラメータ

num

基数を表す文字列。

exponent

指数を表す文字列。 指数が整数でない場合、値は切り捨てられます。 正しい指数の範囲はプラットフォーム依存ですが、 少なくとも -2147483648 から 2147483647 までの範囲を持ちます。

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

結果を文字列で返します。

変更履歴

バージョン | 説明
7.3.0 | bcpow() 関数は、指定されたスケールで値を返すようになりました。 これより前のバージョンでは、後に続く0の桁が省略された数値が返される可能性がありました。

例

例1 bcpow() の例

<?php

echo bcpow('4.2', '3', 2); // 74.08

?>

注意

注意:

PHP 7.3.0 より前のバージョンでは、 bcmul() は scale 引数で指定したものより少ない桁数を返す可能性がありました。 これは scale で許された精度が不要な場合にだけ起きていました。 たとえば、以下のような場合です:

例2 bcpow() で scale を指定する例

<?php
echo bcpow('5', '2', 2); // 結果は "25.00" ではなく "25" となります
?>

参考

  • bcpowmod() - 任意精度数値のべき乗の、指定した数値による剰余
  • bcsqrt() - 任意精度数値の平方根を取得する


任意精度数値のべき乗の、指定した数値による剰余

  • ≪ bcpow
  • bcscale ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値のべき乗の、指定した数値による剰余

bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余

説明

bcpowmod(
string $num,
string $exponent,
string $modulus,
?int $scale = null
): string

modulus で割った余りを求めることを考慮して、 num の exponent 乗を高速に計算します。

パラメータ

num

基数を表す整数の文字列。 (つまり、scale は 0 でなければいけません)

exponent

指数を表す、負でない、整数の文字列。 (つまり、scale は 0 でなければいけません)

modulus

法を表す、整数の文字列。 (つまり、scale は 0 でなければいけません)

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

結果を文字列で返します。modulus が 0 の場合、 または exponent が負の場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。

例

以下の 2 つの文は機能的に同じです。しかし bcpowmod() バージョンのほうが実行時間が早いうえ、 より大きな値の計算が可能です。

<?php
$a = bcpowmod($x, $y, $mod);

$b = bcmod(bcpow($x, $y), $mod);

// $a と $b は同じ値になります

?>

注意

注意:

このメソッドでは剰余計算を行っているので、 正の整数以外を指定すると予期せぬ結果となります。

参考

  • bcpow() - 任意精度数値をべき乗する
  • bcmod() - 2 つの任意精度数値の剰余を取得する


すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

  • ≪ bcpowmod
  • bcsqrt ≫
  • PHP Manual
  • BC Math 関数
  • すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

説明

bcscale(int $scale): int

デフォルトのスケールを設定します。これ以降、 BC 演算関数で明示的にスケールを指定しなかった場合にこの値を使用します。

bcscale(null $scale = null): int

現在のスケールを取得します。

パラメータ

scale

スケール。

戻り値

スケールを設定する場合は、古いスケールを返します。 そうでない場合、現在のスケールを返します。

変更履歴

バージョン | 説明
8.0.0 | scale は、nullable になりました。
7.3.0 | bcscale() は、現在のスケールを取得するために 使えるようになりました。スケールを設定する場合は、古いスケールの値を返します。 これより前のバージョンでは、 scale の指定が強制され、 bcscale() は常に true を返していました。

例

例1 bcscale() の例

<?php

// デフォルトのスケールを 3 とします
bcscale(3);
echo bcdiv('105', '6.55957'); // 16.007

// これは、bcscale() を使用せずにおなじ結果を得ます
echo bcdiv('105', '6.55957', 3); // 16.007

?>


任意精度数値の平方根を取得する

  • ≪ bcscale
  • bcsub ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値の平方根を取得する

bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — 任意精度数値の平方根を取得する

説明

bcsqrt(string $num, ?int $scale = null): string

num の平方根を返します。

パラメータ

num

オペランドを表す、BCMath で有効な数値形式の文字列。

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

平方根を、BCMath で有効な数値形式の文字列で返します。

エラー / 例外

この関数は、以下の場合に ValueError をスローします:

  • num が、BCMath で有効でない数値形式の文字列である場合
  • num が 0 より小さい場合
  • scale が範囲外の値である場合

変更履歴

バージョン | 説明
8.0.0 | num が BCMath で有効でない数値形式の文字列だったり、 0 より小さい場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生していました。
8.0.0 | scale は 0 と 2147483647 の間にあることが必須になりました。 これより前のバージョンでは、負の値は黙って 0 として扱われていました。
8.0.0 | scale は、nullable になりました。

例

例1 bcsqrt() の例

<?php

echo bcsqrt('2', 3); // 1.414

?>

参考

  • bcpow() - 任意精度数値をべき乗する


任意精度数値の減算を行う

  • ≪ bcsqrt
  • GMP ≫
  • PHP Manual
  • BC Math 関数
  • 任意精度数値の減算を行う

bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — 任意精度数値の減算を行う

説明

bcsub(string $left_operand, string $right_operand, int $scale = 0): string

left_operand から right_operand を引きます。

パラメータ

num1

左オペランドを表す文字列。

num2

右オペランドを表す文字列。

scale

このオプションパラメータを使用して、結果の小数点以下の桁数を指定します。省略した場合は、bcscale() 関数でグローバルに設定した桁数をデフォルトとして使用します。それも設定されていない場合は 0 を使用します。

戻り値

減算の結果を文字列で返します。

例

例1 bcsub() の例

<?php

$a = '1.234';
$b = '5';

echo bcsub($a, $b); // -3
echo bcsub($a, $b, 4); // -3.7660

?>

参考

  • bcadd() - 2つの任意精度の数値を加算する


GNU Multiple Precision

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
  • GMP 関数
    • gmp_abs — 絶対値
    • gmp_add — 数値を加算する
    • gmp_and — ビット AND を計算する
    • gmp_binomial — 二項係数を計算する
    • gmp_clrbit — ビットをクリアする
    • gmp_cmp — 数を比較する
    • gmp_com — 1 の補数を計算する
    • gmp_div — gmp_div_q のエイリアス
    • gmp_div_q — 数値を除算する
    • gmp_div_qr — 除算を行い、商と余りを得る
    • gmp_div_r — 除算の余りを計算する
    • gmp_divexact — 正確な除算
    • gmp_export — バイナリ文字列にエクスポートする
    • gmp_fact — 階乗
    • gmp_gcd — 最大公約数を計算する
    • gmp_gcdext — 最大公約数と乗数を計算する
    • gmp_hamdist — ハミング距離
    • gmp_import — バイナリ文字列からインポートする
    • gmp_init — GMP 数を作成する
    • gmp_intval — GMP 数を整数に変換する
    • gmp_invert — 法による逆
    • gmp_jacobi — ヤコビ記号
    • gmp_kronecker — クロネッカーの記号を計算する
    • gmp_lcm — 最小公倍数を計算する
    • gmp_legendre — ルジェンドル記号
    • gmp_mod — モジュロ演算
    • gmp_mul — 数値を乗算する
    • gmp_neg — 符号を反転する
    • gmp_nextprime — 次の素数を見つける
    • gmp_or — ビット OR を計算する
    • gmp_perfect_power — 累乗数かどうかを調べる
    • gmp_perfect_square — 平方数かどうかを調べる
    • gmp_popcount — セットされているビットの数
    • gmp_pow — べき乗を計算する
    • gmp_powm — べき乗とモジュロを計算する
    • gmp_prob_prime — 数が"おそらく素数"であるかどうかを調べる
    • gmp_random — 乱数を生成する
    • gmp_random_bits — 乱数を生成する
    • gmp_random_range — 等確率に選ばれた整数を取得する
    • gmp_random_seed — 乱数シードを設定する
    • gmp_root — n乗根の整数部を返す
    • gmp_rootrem — n乗根の整数部分と小数部分を返す
    • gmp_scan0 — 0 を探す
    • gmp_scan1 — 1 を探す
    • gmp_setbit — ビットを設定する
    • gmp_sign — 数の符号
    • gmp_sqrt — 平方根を計算する
    • gmp_sqrtrem — 余りつきの平方根
    • gmp_strval — GMP 数を文字列に変換する
    • gmp_sub — 数値の減算
    • gmp_testbit — ビットが設定されているかどうかを調べる
    • gmp_xor — ビット XOR を計算する
  • GMP — GMP クラス
    • GMP::__construct — GMP数を作成する
    • GMP::__serialize — GMP オブジェクトをシリアライズする
    • GMP::__unserialize — data 引数をGMP オブジェクトとして復元する


はじめに

以下の関数により、GNU MP ライブラリを使用して 任意長の整数を使用することが可能になります。

注意:

大半の GMP 関数は、GMP 数を引数としてとります。 このマニュアルでは、GMP 数を GMP オブジェクトとしています。 これらの関数の大半は、数値と文字列も 引数として指定可能です。ただし、後者は数値に変換できる場合に限ります。 また、整数引数を使用して処理を行うより高速な関数がある場合には、 指定された引数が整数である場合により低速となる関数の代わりに 使用されます。これは透過的に行われます。 gmp_init() も参照ください。

注意:

PHP 5.6 以降は、 gmp_init() やその他の GMP 関数が返す GMP オブジェクトに対して、 算術演算子や ビット演算子そして 比較演算子 が使えるようになります。

警告

より大きな整数を明示的に指定するには、文字列として指定する必要があります。 さもないと、PHP は値をまず float として解釈するので、 精度が劣化してしまいます。

注意: この拡張モジュールは Windows でも使用可能です。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • GMP
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

» http://gmplib.org/#DOWNLOAD から GMP ライブラリをダウンロード可能です。 このサイトでは、GMP のマニュアルも入手可能です。

これらの関数を使用するには、GMP バージョン 4.2 以降が必要です。 中には、より新しいバージョンの GMP ライブラリを必要とする関数もあります。

Windows では、GMP ではなく MPIR が必要です。


インストール手順

これらの関数を利用可能とするには、オプション --with-gmp を使用することにより GMP サポートを有効にして PHP をコンパイルする必要が あります。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

GMP_ROUND_ZERO (int)
GMP_ROUND_PLUSINF (int)
GMP_ROUND_MINUSINF (int)
GMP_MSW_FIRST (int)
GMP_LSW_FIRST (int)
GMP_LITTLE_ENDIAN (int)
GMP_BIG_ENDIAN (int)
GMP_NATIVE_ENDIAN (int)
GMP_VERSION (string)
GMP ライブラリのバージョン。
GMP_MPIR_VERSION (string)
MPIR ライブラリのバージョン。


例

例1 GMP を使用した階乗関数

<?php
function fact($x)
{
$return = 1;
for ($i=2; $i <= $x; $i++) {
$return = gmp_mul($return, $i);
}
return $return;
}

echo gmp_strval(fact(1000)) . "\n";
?>

この例は、1000 の階乗(非常に大きな数です)を非常に高速に計算します。


GMP 関数

参考

より数学的な関数が、 数学 の節にあります。

目次

  • gmp_abs — 絶対値
  • gmp_add — 数値を加算する
  • gmp_and — ビット AND を計算する
  • gmp_binomial — 二項係数を計算する
  • gmp_clrbit — ビットをクリアする
  • gmp_cmp — 数を比較する
  • gmp_com — 1 の補数を計算する
  • gmp_div — gmp_div_q のエイリアス
  • gmp_div_q — 数値を除算する
  • gmp_div_qr — 除算を行い、商と余りを得る
  • gmp_div_r — 除算の余りを計算する
  • gmp_divexact — 正確な除算
  • gmp_export — バイナリ文字列にエクスポートする
  • gmp_fact — 階乗
  • gmp_gcd — 最大公約数を計算する
  • gmp_gcdext — 最大公約数と乗数を計算する
  • gmp_hamdist — ハミング距離
  • gmp_import — バイナリ文字列からインポートする
  • gmp_init — GMP 数を作成する
  • gmp_intval — GMP 数を整数に変換する
  • gmp_invert — 法による逆
  • gmp_jacobi — ヤコビ記号
  • gmp_kronecker — クロネッカーの記号を計算する
  • gmp_lcm — 最小公倍数を計算する
  • gmp_legendre — ルジェンドル記号
  • gmp_mod — モジュロ演算
  • gmp_mul — 数値を乗算する
  • gmp_neg — 符号を反転する
  • gmp_nextprime — 次の素数を見つける
  • gmp_or — ビット OR を計算する
  • gmp_perfect_power — 累乗数かどうかを調べる
  • gmp_perfect_square — 平方数かどうかを調べる
  • gmp_popcount — セットされているビットの数
  • gmp_pow — べき乗を計算する
  • gmp_powm — べき乗とモジュロを計算する
  • gmp_prob_prime — 数が"おそらく素数"であるかどうかを調べる
  • gmp_random — 乱数を生成する
  • gmp_random_bits — 乱数を生成する
  • gmp_random_range — 等確率に選ばれた整数を取得する
  • gmp_random_seed — 乱数シードを設定する
  • gmp_root — n乗根の整数部を返す
  • gmp_rootrem — n乗根の整数部分と小数部分を返す
  • gmp_scan0 — 0 を探す
  • gmp_scan1 — 1 を探す
  • gmp_setbit — ビットを設定する
  • gmp_sign — 数の符号
  • gmp_sqrt — 平方根を計算する
  • gmp_sqrtrem — 余りつきの平方根
  • gmp_strval — GMP 数を文字列に変換する
  • gmp_sub — 数値の減算
  • gmp_testbit — ビットが設定されているかどうかを調べる
  • gmp_xor — ビット XOR を計算する


絶対値

  • ≪ GMP 関数
  • gmp_add ≫
  • PHP Manual
  • GMP 関数
  • 絶対値

gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — 絶対値

説明

gmp_abs(GMP|int|string $num): GMP

ある数の絶対値を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num の絶対値を GMP 数で返します。

例

例1 gmp_abs() の例

<?php
$abs1 = gmp_abs("274982683358");
$abs2 = gmp_abs("-274982683358");

echo gmp_strval($abs1) . "\n";
echo gmp_strval($abs2) . "\n";
?>

上の例の出力は以下となります。

274982683358
274982683358


数値を加算する

  • ≪ gmp_abs
  • gmp_and ≫
  • PHP Manual
  • GMP 関数
  • 数値を加算する

gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — 数値を加算する

説明

gmp_add(GMP|int|string $num1, GMP|int|string $num2): GMP

2 つの数を加算します。

パラメータ

num1

足される数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

足す数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

加算の結果を GMP 数で返します。

例

例1 gmp_add() の例

<?php
$sum = gmp_add("123456789012345", "76543210987655");
echo gmp_strval($sum) . "\n";
?>

上の例の出力は以下となります。

200000000000000


ビット AND を計算する

  • ≪ gmp_add
  • gmp_binomial ≫
  • PHP Manual
  • GMP 関数
  • ビット AND を計算する

gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — ビット AND を計算する

説明

gmp_and(GMP|int|string $num1, GMP|int|string $num2): GMP

2 つの GMP 数のビット AND を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

ビット AND 演算の結果を GMP 数で返します。

例

例1 gmp_and() の例

<?php
$and1 = gmp_and("0xfffffffff4", "0x4");
$and2 = gmp_and("0xfffffffff4", "0x8");
echo gmp_strval($and1) . "\n";
echo gmp_strval($and2) . "\n";
?>

上の例の出力は以下となります。

4
0


二項係数を計算する

  • ≪ gmp_and
  • gmp_clrbit ≫
  • PHP Manual
  • GMP 関数
  • 二項係数を計算する

gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — 二項係数を計算する

説明

gmp_binomial(GMP|int|string $n, int $k): GMP

二項係数 C(n, k) を計算します。

パラメータ

n

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

k

戻り値

二項係数 C(n, k) を返します。

エラー / 例外

k が負の場合、ValueError がスローされます。 PHP 8.0.0 より前のバージョンでは、E_WARNING レベルの警告が発生していました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。


ビットをクリアする

  • ≪ gmp_binomial
  • gmp_cmp ≫
  • PHP Manual
  • GMP 関数
  • ビットをクリアする

gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — ビットをクリアする

説明

gmp_clrbit(GMP $num, int $index): void

num のビット index をクリア (0 に設定) します。index は 0 から始まります。

パラメータ

num

GMP オブジェクト

index

クリアするビットのインデックス。0 が最下位ビットを表します。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_clrbit() の例

<?php
$a = gmp_init("0xff");
gmp_clrbit($a, 0); // インデックスは 0 から始まり、これは最下位ビットを表します
echo gmp_strval($a) . "\n";
?>

上の例の出力は以下となります。

254

注意

注意:

他の大半の GMP 関数とは異なり、gmp_clrbit() は必ず既存の GMP オブジェクト (例えば gmp_init() を使用して取得したもの) を使用してコールしなければなりません。 リソースは自動的には作成されません。

参考

  • gmp_setbit() - ビットを設定する
  • gmp_testbit() - ビットが設定されているかどうかを調べる


数を比較する

  • ≪ gmp_clrbit
  • gmp_com ≫
  • PHP Manual
  • GMP 関数
  • 数を比較する

gmp_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — 数を比較する

説明

gmp_cmp(GMP|int|string $num1, GMP|int|string $num2): int

ふたつの数を比較します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

a > b の場合に正の値、a = b の場合にゼロ、a < b の場合に負の値を返します。

例

例1 gmp_cmp() の例

<?php
$cmp1 = gmp_cmp("1234", "1000"); // より大きい
$cmp2 = gmp_cmp("1000", "1234"); // より小さい
$cmp3 = gmp_cmp("1234", "1234"); // 等しい

echo "$cmp1 $cmp2 $cmp3\n";
?>

上の例の出力は以下となります。

1 -1 0


1 の補数を計算する

  • ≪ gmp_cmp
  • gmp_div ≫
  • PHP Manual
  • GMP 関数
  • 1 の補数を計算する

gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — 1 の補数を計算する

説明

gmp_com(GMP|int|string $num): GMP

num について、1 の補数を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num についての 1 の補数を GMP 数で返します。

例

例1 gmp_com() の例

<?php
$com = gmp_com("1234");
echo gmp_strval($com) . "\n";
?>

上の例の出力は以下となります。

-1235


gmp_div_q のエイリアス

  • ≪ gmp_com
  • gmp_div_q ≫
  • PHP Manual
  • GMP 関数
  • gmp_div_q のエイリアス

gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — gmp_div_q() のエイリアス

説明

この関数は次の関数のエイリアスです。 gmp_div_q().


数値を除算する

  • ≪ gmp_div
  • gmp_div_qr ≫
  • PHP Manual
  • GMP 関数
  • 数値を除算する

gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — 数値を除算する

説明

gmp_div_q(GMP|int|string $num1, GMP|int|string $num2, int $rounding_mode = GMP_ROUND_ZERO): GMP

num1 を num2 で割り、 結果を整数で返します。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

rounding_mode

結果の丸め方は rounding_mode で指定し、次の値を指定可能です。

  • GMP_ROUND_ZERO: 結果は 0 の方に丸められます。
  • GMP_ROUND_PLUSINF: 結果は、 +infinity の方に丸められます。
  • GMP_ROUND_MINUSINF: 結果は、 -infinity の方に丸められます。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_div_q() の例

<?php
$div1 = gmp_div_q("100", "5");
echo gmp_strval($div1) . "\n";

$div2 = gmp_div_q("1", "3");
echo gmp_strval($div2) . "\n";

$div3 = gmp_div_q("1", "3", GMP_ROUND_PLUSINF);
echo gmp_strval($div3) . "\n";

$div4 = gmp_div_q("-1", "4", GMP_ROUND_PLUSINF);
echo gmp_strval($div4) . "\n";

$div5 = gmp_div_q("-1", "4", GMP_ROUND_MINUSINF);
echo gmp_strval($div5) . "\n";
?>

上の例の出力は以下となります。

20
0
1
0
-1

注意

注意:

この関数は、gmp_div() のようにコールすることも可能です。

参考

  • gmp_div_r() - 除算の余りを計算する
  • gmp_div_qr() - 除算を行い、商と余りを得る


除算を行い、商と余りを得る

  • ≪ gmp_div_q
  • gmp_div_r ≫
  • PHP Manual
  • GMP 関数
  • 除算を行い、商と余りを得る

gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — 除算を行い、商と余りを得る

説明

gmp_div_qr(GMP|int|string $num1, GMP|int|string $num2, int $rounding_mode = GMP_ROUND_ZERO): array

この関数は、num1 を num2 で割ります。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

rounding_mode

引数 rounding_mode の説明については、 gmp_div_q() 関数を参照ください。

戻り値

配列を返します。配列の最初の要素は [n/d] (割算の結果の整数値)、2 番目の要素は (n - [n/d] * d) (割算の余り) です。

例

例1 GMP 数の割算

<?php
$a = gmp_init("0x41682179fbf5");
$res = gmp_div_qr($a, "0xDEFE75");
printf("Result is: q - %s, r - %s",
gmp_strval($res[0]), gmp_strval($res[1]));
?>

参考

  • gmp_div_q() - 数値を除算する
  • gmp_div_r() - 除算の余りを計算する


除算の余りを計算する

  • ≪ gmp_div_qr
  • gmp_divexact ≫
  • PHP Manual
  • GMP 関数
  • 除算の余りを計算する

gmp_div_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — 除算の余りを計算する

説明

gmp_div_r(GMP|int|string $num1, GMP|int|string $num2, int $rounding_mode = GMP_ROUND_ZERO): resource

num1 を num2 で整数として割った際の余りを計算します。余りは、引数 num1 がゼロでない場合に、これと同じ符号を有します。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

rounding_mode

引数 rounding_mode の説明については、関数 gmp_div_q() を参照ください。

戻り値

余りを GMP 数で返します。

例

例1 gmp_div_r() の例

<?php
$div = gmp_div_r("105", "20");
echo gmp_strval($div) . "\n";
?>

上の例の出力は以下となります。

5

参考

  • gmp_div_q() - 数値を除算する
  • gmp_div_qr() - 除算を行い、商と余りを得る


正確な除算

  • ≪ gmp_div_r
  • gmp_export ≫
  • PHP Manual
  • GMP 関数
  • 正確な除算

gmp_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — 正確な除算

説明

gmp_divexact(GMP|int|string $num1, GMP|int|string $num2): GMP

高速な "exact division" アルゴリズムを使用して num1 を num2 で割ります。 この関数は、num1 が num2 で割り切れることがわかっている場合にのみ正確な結果を出力します。

パラメータ

num1

割られる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 を割る数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_divexact() の例

<?php
$div1 = gmp_divexact("10", "2");
echo gmp_strval($div1) . "\n";

$div2 = gmp_divexact("10", "3"); // 間違った結果となります
echo gmp_strval($div2) . "\n";
?>

上の例の出力は以下となります。

5
2863311534


バイナリ文字列にエクスポートする

  • ≪ gmp_divexact
  • gmp_fact ≫
  • PHP Manual
  • GMP 関数
  • バイナリ文字列にエクスポートする

gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — バイナリ文字列にエクスポートする

説明

gmp_export(GMP|int|string $num, int $word_size = 1, int $flags = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): string

GMP数をバイナリ文字列にエクスポートします。

パラメータ

num

エクスポートするGMP数

word_size

デフォルト値は1です。 バイナリデータのチャンクごとのバイト数を指定します。 これはオプションパラメータと組み合わせて主に使います。

flags

デフォルト値は GMP_MSW_FIRST | GMP_NATIVE_ENDIAN です。

戻り値

文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

例

例1 gmp_export() の例

<?php
$number = gmp_init(16705);
echo gmp_export($number) . "\n";
?>

上の例の出力は以下となります。

AA

参考

  • gmp_import() - バイナリ文字列からインポートする


階乗

  • ≪ gmp_export
  • gmp_gcd ≫
  • PHP Manual
  • GMP 関数
  • 階乗

gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — 階乗

説明

gmp_fact(GMP|int|string $num): GMP

num の階乗 (num!) を計算します。

パラメータ

num

階乗を求める数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_fact() の例

<?php
$fact1 = gmp_fact(5); // 5 * 4 * 3 * 2 * 1
echo gmp_strval($fact1) . "\n";

$fact2 = gmp_fact(50); // 50 * 49 * 48, ... etc
echo gmp_strval($fact2) . "\n";
?>

上の例の出力は以下となります。

120
30414093201713378043612608166064768844377641568960512000000000000


最大公約数を計算する

  • ≪ gmp_fact
  • gmp_gcdext ≫
  • PHP Manual
  • GMP 関数
  • 最大公約数を計算する

gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — 最大公約数を計算する

説明

gmp_gcd(GMP|int|string $num1, GMP|int|string $num2): GMP

num1 と num2 の最大公約数を計算します。 引数のどちらかまたは両方が負の場合でも結果は常に正となります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num1 と num2 の両方を割り切ることができる正の数を GMP 数で返します。

例

例1 gmp_gcd() の例

<?php
$gcd = gmp_gcd("12", "21");
echo gmp_strval($gcd) . "\n";
?>

上の例の出力は以下となります。

3

参考

  • gmp_lcm() - 最小公倍数を計算する


最大公約数と乗数を計算する

  • ≪ gmp_gcd
  • gmp_hamdist ≫
  • PHP Manual
  • GMP 関数
  • 最大公約数と乗数を計算する

gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — 最大公約数と乗数を計算する

説明

gmp_gcdext(GMP|int|string $num1, GMP|int|string $num2): array

a*s + b*t = g = gcd(a,b) となるような g, s, t を計算します。ただし、gcd は最大公約数です。g, s, t を要素とする配列を返します。

この関数は、2 変数の線形不定方程式 (linear Diophantine equations) を解く際に使用することが可能です。 この方程式は、a*x + b*y = c のような形式で、 整数のみを解とするものです。 詳細な情報は、» MathWorld の "Diophantine Equation" についてのページを参照ください。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP 数の配列を返します。

例

例1 線形不定方程式を解く

<?php
// 方程式 a*s + b*t = g を解きます。
// a = 12, b = 21, g = gcd(12, 21) = 3 とします。
$a = gmp_init(12);
$b = gmp_init(21);
$g = gmp_gcd($a, $b);
$r = gmp_gcdext($a, $b);

$check_gcd = (gmp_strval($g) == gmp_strval($r['g']));
$eq_res = gmp_add(gmp_mul($a, $r['s']), gmp_mul($b, $r['t']));
$check_res = (gmp_strval($g) == gmp_strval($eq_res));

if ($check_gcd && $check_res) {
$fmt = "Solution: %d*%d + %d*%d = %d\n";
printf($fmt, gmp_strval($a), gmp_strval($r['s']), gmp_strval($b),
gmp_strval($r['t']), gmp_strval($r['g']));
} else {
echo "方程式を解く際にエラーが発生しました\n";
}

// 出力は、解: 12*2 + 21*-1 = 3 のようになります。
?>


ハミング距離

  • ≪ gmp_gcdext
  • gmp_import ≫
  • PHP Manual
  • GMP 関数
  • ハミング距離

gmp_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — ハミング距離

説明

gmp_hamdist(GMP|int|string $num1, GMP|int|string $num2): int

num1 と num2 の間のハミング距離を返します。オペランドは共に非負とする必要があります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の数である必要があります。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の数である必要があります。

戻り値

num1 と num2 のハミング距離を int として返します。

例

例1 gmp_hamdist() の例

<?php
$ham1 = gmp_init("1001010011", 2);
$ham2 = gmp_init("1011111100", 2);
echo gmp_hamdist($ham1, $ham2) . "\n";

/* ハミング距離は、以下と等しくなります */
echo gmp_popcount(gmp_xor($ham1, $ham2)) . "\n";
?>

上の例の出力は以下となります。

6
6

参考

  • gmp_popcount() - セットされているビットの数
  • gmp_xor() - ビット XOR を計算する


バイナリ文字列からインポートする

  • ≪ gmp_hamdist
  • gmp_init ≫
  • PHP Manual
  • GMP 関数
  • バイナリ文字列からインポートする

gmp_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — バイナリ文字列からインポートする

説明

gmp_import(string $data, int $word_size = 1, int $flags = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): GMP

バイナリ文字列から GMP数をインポートします。

パラメータ

data

インポートするバイナリ文字列

word_size

デフォルト値は1です。 バイナリデータのチャンクごとのバイト数を指定します。 これはオプションパラメータと組み合わせて主に使います。

flags

デフォルト値は GMP_MSW_FIRST | GMP_NATIVE_ENDIAN です。

戻り値

GMP 数を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

例

例1 gmp_import() の例

<?php
$number = gmp_import("\0");
echo gmp_strval($number) . "\n";

$number = gmp_import("\0\1\2");
echo gmp_strval($number) . "\n";
?>

上の例の出力は以下となります。

0
258

参考

  • gmp_export() - バイナリ文字列にエクスポートする


GMP 数を作成する

  • ≪ gmp_import
  • gmp_intval ≫
  • PHP Manual
  • GMP 関数
  • GMP 数を作成する

gmp_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — GMP 数を作成する

説明

gmp_init(int|string $num, int $base = 0): GMP

整数または文字列から GMP 数を生成します。

パラメータ

num

整数値あるいは文字列。文字列表現には、 十進数か十六進数、あるいは八進数を使用可能です。

base

基数。

基数には 2 から 62 までの値を指定することができます。 基数を 0 (デフォルト値) にすると、最初の文字に応じて実際の基数を決定します。 最初の二文字が 0x あるいは 0X の場合は十六進数、 最初の2文字が 0b や 0B の場合は二進数、 それ以外の場合で、最初の文字が 0 の場合は八進数、 それ以外の場合は十進数となります。 基数が 36 までの場合、大文字小文字は無視されます。 つまり、大文字と小文字は同じ値を持ちます。 基数が 37 から 62 までの場合、 大文字は通常、10 から 35 を表現し、 小文字は 36 から 61 までを表現します。

戻り値

GMP オブジェクトを返します。

例

例1 GMP 数の作成

<?php
$a = gmp_init(123456);
$b = gmp_init("0xFFFFDEBACDFEDF7200");
?>

注意

注意:

gmp_add() のような GMP 関数において、GMP 数を指定するところに整数または文字列を使用したい場合には、 この関数をコールする必要はありません。この場合、変換が必要な場合には、 gmp_init() と同様の方法で関数の引数は自動的に GMP 数に変換されます。

参考

  • GMP::__construct() - GMP数を作成する


GMP 数を整数に変換する

  • ≪ gmp_init
  • gmp_invert ≫
  • PHP Manual
  • GMP 関数
  • GMP 数を整数に変換する

gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — GMP 数を整数に変換する

説明

gmp_intval(GMP|int|string $num): int

この関数は、GMP 数を PHP ネイティブの整数に変換します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num を整数に変換した結果を返します。

例

例1 gmp_intval() の例

<?php
// 正しい結果を表示します
echo gmp_intval("2147483647") . "\n";

// PHP の整数型の制限をこえているので、正しい結果を表示しません
echo gmp_intval("2147483648") . "\n";

// 正しい結果を表示します
echo gmp_strval("2147483648") . "\n";
?>

上の例の出力は以下となります。

2147483647
2147483647
2147483648

注意

警告

この関数は、数値が実際に PHP の整数型に適合する場合(すなわち、 符号付き long 型)にのみ有用な結果を返します。単に GMP 数を出力したい場合には、gmp_strval() を使用してください。


法による逆

  • ≪ gmp_intval
  • gmp_jacobi ≫
  • PHP Manual
  • GMP 関数
  • 法による逆

gmp_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — 法による逆

説明

gmp_invert(GMP|int|string $num1, GMP|int|string $num2): GMP|false

num2 を法とした num1 の逆を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

成功した場合に GMP 数、逆が存在しない場合に false を返します。

例

例1 gmp_invert() の例

<?php
echo gmp_invert("5", "10"); // 逆は存在しないので何も出力せず、結果は FALSE となります
$invert = gmp_invert("5", "11");
echo gmp_strval($invert) . "\n";
?>

上の例の出力は以下となります。

9


ヤコビ記号

  • ≪ gmp_invert
  • gmp_kronecker ≫
  • PHP Manual
  • GMP 関数
  • ヤコビ記号

gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — ヤコビ記号

説明

gmp_jacobi(GMP|int|string $num1, GMP|int|string $num2): int

num1 および num2 の » ヤコビ記号 を計算します。num2 は正の奇数である必要があります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の奇数でなければなりません。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_jacobi() の例

<?php
echo gmp_jacobi("1", "3") . "\n";
echo gmp_jacobi("2", "3") . "\n";
?>

上の例の出力は以下となります。

1
0

参考

  • gmp_kronecker() - クロネッカーの記号を計算する
  • gmp_legendre() - ルジェンドル記号


クロネッカーの記号を計算する

  • ≪ gmp_jacobi
  • gmp_lcm ≫
  • PHP Manual
  • GMP 関数
  • クロネッカーの記号を計算する

gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — クロネッカーの記号を計算する

説明

gmp_kronecker(GMP|int|string $num1, GMP|int|string $num2): int

この関数は num1 と num2 のクロネッカーの記号を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num1 と num2 のクロネッカーの記号を返します。

参考

  • gmp_jacobi() - ヤコビ記号
  • gmp_legendre() - ルジェンドル記号


最小公倍数を計算する

  • ≪ gmp_kronecker
  • gmp_legendre ≫
  • PHP Manual
  • GMP 関数
  • 最小公倍数を計算する

gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — 最小公倍数を計算する

説明

gmp_lcm(GMP|int|string $num1, GMP|int|string $num2): GMP

この関数は、num1 と num2 の最小公倍数(lcm)を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

参考

  • gmp_gcd() - 最大公約数を計算する


ルジェンドル記号

  • ≪ gmp_lcm
  • gmp_mod ≫
  • PHP Manual
  • GMP 関数
  • ルジェンドル記号

gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — ルジェンドル記号

説明

gmp_legendre(GMP|int|string $num1, GMP|int|string $num2): int

num1 と num2 の » ルジェンドル記号 を計算します。num2 は、正の奇数である必要があります。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

正の奇数でなければなりません。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_legendre() の例

<?php
echo gmp_legendre("1", "3") . "\n";
echo gmp_legendre("2", "3") . "\n";
?>

上の例の出力は以下となります。

1
0

参考

  • gmp_jacobi() - ヤコビ記号
  • gmp_kronecker() - クロネッカーの記号を計算する


モジュロ演算

  • ≪ gmp_legendre
  • gmp_mul ≫
  • PHP Manual
  • GMP 関数
  • モジュロ演算

gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — モジュロ演算

説明

gmp_mod(GMP|int|string $num1, GMP|int|string $num2): GMP

num2 を法とした num1 を計算します。結果は常に非負であり、 num2 の符号は無視されます。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

法として使用する値。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_mod() の例

<?php
$mod = gmp_mod("8", "3");
echo gmp_strval($mod) . "\n";
?>

上の例の出力は以下となります。

2


数値を乗算する

  • ≪ gmp_mod
  • gmp_neg ≫
  • PHP Manual
  • GMP 関数
  • 数値を乗算する

gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — 数値を乗算する

説明

gmp_mul(GMP|int|string $num1, GMP|int|string $num2): GMP

num1 と num2 をかけ、 結果を返します。

パラメータ

num1

num2 を掛けられる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 に掛ける数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_mul() の例

<?php
$mul = gmp_mul("12345678", "2000");
echo gmp_strval($mul) . "\n";
?>

上の例の出力は以下となります。

24691356000


符号を反転する

  • ≪ gmp_mul
  • gmp_nextprime ≫
  • PHP Manual
  • GMP 関数
  • 符号を反転する

gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — 符号を反転する

説明

gmp_neg(GMP|int|string $num): GMP

ある数の符号を反転したものを返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

-num を GMP 数で返します。

例

例1 gmp_neg() の例

<?php
$neg1 = gmp_neg("1");
echo gmp_strval($neg1) . "\n";
$neg2 = gmp_neg("-1");
echo gmp_strval($neg2) . "\n";
?>

上の例の出力は以下となります。

-1
1


次の素数を見つける

  • ≪ gmp_neg
  • gmp_or ≫
  • PHP Manual
  • GMP 関数
  • 次の素数を見つける

gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — 次の素数を見つける

説明

gmp_nextprime(GMP|int|string $num): GMP

次の素数を見つけます。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num より大きい次の素数を GMP 数として返します。

例

例1 gmp_nextprime() の例

<?php
$prime1 = gmp_nextprime(10); // 10 より大きい次の素数
$prime2 = gmp_nextprime(-1000); // -1000 より大きい次の素数

echo gmp_strval($prime1) . "\n";
echo gmp_strval($prime2) . "\n";
?>

上の例の出力は以下となります。

11
2

注意

注意:

この関数は素数を識別するのに確率的アルゴリズムを使用します。 誤って合成数を取得してしまうことは、まずありません。


ビット OR を計算する

  • ≪ gmp_nextprime
  • gmp_perfect_power ≫
  • PHP Manual
  • GMP 関数
  • ビット OR を計算する

gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — ビット OR を計算する

説明

gmp_or(GMP|int|string $num1, GMP|int|string $num2): GMP

2 つの GMP 数のビット OR を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_or() の例

<?php
$or1 = gmp_or("0xfffffff2", "4");
echo gmp_strval($or1, 16) . "\n";
$or2 = gmp_or("0xfffffff2", "2");
echo gmp_strval($or2, 16) . "\n";
?>

上の例の出力は以下となります。

fffffff6
fffffff2


累乗数かどうかを調べる

  • ≪ gmp_or
  • gmp_perfect_square ≫
  • PHP Manual
  • GMP 関数
  • 累乗数かどうかを調べる

gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — 累乗数かどうかを調べる

説明

gmp_perfect_power(GMP|int|string $num): bool

num が累乗数かどうかを調べます。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num が累乗数であった場合は true を返し、 そうでない場合は false を返します。

参考

  • gmp_perfect_square() - 平方数かどうかを調べる


平方数かどうかを調べる

  • ≪ gmp_perfect_power
  • gmp_popcount ≫
  • PHP Manual
  • GMP 関数
  • 平方数かどうかを調べる

gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — 平方数かどうかを調べる

説明

gmp_perfect_square(GMP|int|string $num): bool

その数が平方数であるかどうかを調べます。

パラメータ

num

平方数かどうかを調べたい数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num が平方数の場合に true、その他の場合に false を返します。

例

例1 gmp_perfect_square() の例

<?php
// 3 * 3、平方数です
var_dump(gmp_perfect_square("9"));

// 平方数ではありません
var_dump(gmp_perfect_square("7"));

// 1234567890 * 1234567890、平方数です
var_dump(gmp_perfect_square("1524157875019052100"));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)

参考

  • gmp_perfect_power() - 累乗数かどうかを調べる
  • gmp_sqrt() - 平方根を計算する
  • gmp_sqrtrem() - 余りつきの平方根


セットされているビットの数

  • ≪ gmp_perfect_square
  • gmp_pow ≫
  • PHP Manual
  • GMP 関数
  • セットされているビットの数

gmp_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — セットされているビットの数

説明

gmp_popcount(GMP|int|string $num): int

セットされているビットの数を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

num にセットされているビットの数を返します。

例

例1 gmp_popcount() の例

<?php
$pop1 = gmp_init("10000101", 2); // 1 が 3 つ
echo gmp_popcount($pop1) . "\n";
$pop2 = gmp_init("11111110", 2); // 1 が 7 つ
echo gmp_popcount($pop2) . "\n";
?>

上の例の出力は以下となります。

3
7


べき乗を計算する

  • ≪ gmp_popcount
  • gmp_powm ≫
  • PHP Manual
  • GMP 関数
  • べき乗を計算する

gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — べき乗を計算する

説明

gmp_pow(GMP|int|string $num, int $exponent): GMP

num の exponent 乗を計算します。

パラメータ

num

もととなる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

exponent

正の数で、num を何乗するかを指定します。

戻り値

べき乗の結果を GMP 数で返します。 0^0 は 1 となります。

例

例1 gmp_pow() の例

<?php
$pow1 = gmp_pow("2", 31);
echo gmp_strval($pow1) . "\n";
$pow2 = gmp_pow("0", 0);
echo gmp_strval($pow2) . "\n";
$pow3 = gmp_pow("2", -1); // 負のべき乗を指定したため、警告を発生します
echo gmp_strval($pow3) . "\n";
?>

上の例の出力は以下となります。

2147483648
1


べき乗とモジュロを計算する

  • ≪ gmp_pow
  • gmp_prob_prime ≫
  • PHP Manual
  • GMP 関数
  • べき乗とモジュロを計算する

gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — べき乗とモジュロを計算する

説明

gmp_powm(GMP|int|string $num, GMP|int|string $exponent, GMP|int|string $modulus): GMP

modulus を法として (num の exponent 乗) を計算します。 exponent が負の場合、結果は未定義(undefined) となります。

パラメータ

num

もととなる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

exponent

正の数で、num を何乗するかを指定します。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

modulus

モジュロ。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

結果を GMP 数で返します。

例

例1 gmp_powm() の例

<?php
$pow1 = gmp_powm("2", "31", "2147483649");
echo gmp_strval($pow1) . "\n";
?>

上の例の出力は以下となります。

2147483648


数が"おそらく素数"であるかどうかを調べる

  • ≪ gmp_powm
  • gmp_random ≫
  • PHP Manual
  • GMP 関数
  • 数が"おそらく素数"であるかどうかを調べる

gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — 数が"おそらく素数"であるかどうかを調べる

説明

gmp_prob_prime(GMP|int|string $num, int $repetitions = 10): int

この関数は、Miller-Rabin の確率的テストを使用して、 その数が素数かどうかを調べます。

パラメータ

num

素数かどうかを調べたい数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

repetitions

repetitions の合理的な値は 5 から 10 くらいまで変動します (デフォルトは 10 です)。より大きい値を指定すると、素数でない数を 「おそらく素数である」と誤認識する可能性が小さくなります。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

この関数が 0 を返す場合、num は確実に素数ではありません。 1 を返す場合、num は「おそらく」 素数です。2 を返す場合、num は確実に素数です。

例

例1 gmp_prob_prime() の例

<?php
// 明らかに素数ではありません
echo gmp_prob_prime("6") . "\n";

// おそらく素数です
echo gmp_prob_prime("1111111111111111111") . "\n";

// 明らかに素数です
echo gmp_prob_prime("11") . "\n";
?>

上の例の出力は以下となります。

0
1
2


乱数を生成する

  • ≪ gmp_prob_prime
  • gmp_random_bits ≫
  • PHP Manual
  • GMP 関数
  • 乱数を生成する

gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — 乱数を生成する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

gmp_random(int $limiter = 20): GMP

乱数を生成します。乱数の範囲は 0 と (2 ** n) - 1 の間です。 n は limb * limiter のビット数になります。 limiter が負の場合、負の値が生成されます。

limb は GMP の内部機構です。limb のビット数は固定ではなく、 システムによって変化します。一般的には limb は 16 あるいは 32 ビットですが、それが保証されているわけではありません。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

limiter

リミッタ。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

ランダムな GMP 数を返します。

例

例1 gmp_random() の例

<?php
$rand1 = gmp_random(1); // 0 から 1 * limb のビット数までの間の乱数
$rand2 = gmp_random(2); // 0 から 2 * limb のビット数までの間の乱数

echo gmp_strval($rand1) . "\n";
echo gmp_strval($rand2) . "\n";
?>

上の例の出力は以下となります。

1915834968
8642564075890328087


乱数を生成する

  • ≪ gmp_random
  • gmp_random_range ≫
  • PHP Manual
  • GMP 関数
  • 乱数を生成する

gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — 乱数を生成する

説明

gmp_random_bits(int $bits): GMP

乱数を生成します。値は 0 と 2$bits - 1 の間になります。

bits は0より大きくなければならず、最大値は利用できるメモリの量次第です。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

bits

生成するビット数

戻り値

ランダムなGMP数を返します。

エラー / 例外

bits が 1 より小さい値の場合、 ValueError がスローされます。

例

例1 gmp_random_bits() の例

<?php
$rand1 = gmp_random_bits(3); // random number from 0 to 7
$rand2 = gmp_random_bits(5); // random number from 0 to 31

echo gmp_strval($rand1) . "\n";
echo gmp_strval($rand2) . "\n";
?>

上の例の出力は以下となります。

3
15


等確率に選ばれた整数を取得する

  • ≪ gmp_random_bits
  • gmp_random_seed ≫
  • PHP Manual
  • GMP 関数
  • 等確率に選ばれた整数を取得する

gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — 等確率に選ばれた整数を取得する

説明

gmp_random_range(GMP|int|string $min, GMP|int|string $max): GMP

乱数を生成します。 乱数の範囲は min と max の間です。

min と max は両方負の値を指定できますが、 min は max よりも常に小さくなければいけません。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

min

乱数の最小値を示すGMP数

max

乱数の最大値を示すGMP数

戻り値

閉区間 [min, max] から等確率に選ばれた整数を含む GMP オブジェクトを返します。 min と max も両方、 返される値に含まれる可能性があります。

エラー / 例外

max が min より小さい場合、 ValueError がスローされます。

例

例1 gmp_random_range() の例

<?php
$rand1 = gmp_random_range(0, 100); // random number between 0 and 100
$rand2 = gmp_random_range(-100, -10); // random number between -100 and -10

echo gmp_strval($rand1) . "\n";
echo gmp_strval($rand2) . "\n";
?>

上の例の出力は以下となります。

42
-67


乱数シードを設定する

  • ≪ gmp_random_range
  • gmp_root ≫
  • PHP Manual
  • GMP 関数
  • 乱数シードを設定する

gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — 乱数シードを設定する

説明

gmp_random_seed(GMP|int|string $seed): void

パラメータ

seed

gmp_random(),
gmp_random_bits(),
gmp_random_range() 向けに設定するシード

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

値を返しません。

エラー / 例外

seed が無効な場合は、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | gmp_random_seed() は、 seed が無効な場合に ValueError をスローするようになりました。 これより前のバージョンでは、 E_WARNING が発生し、false を返していました。

例

例1 gmp_random_seed() の例

<?php
// set the seed
gmp_random_seed(100);

var_dump(gmp_strval(gmp_random(1)));

// set the seed to something else
gmp_random_seed(gmp_init(-100));

var_dump(gmp_strval(gmp_random_bits(10)));

// set the seed to something invalid
var_dump(gmp_random_seed('not a number'));

上の例の出力は以下となります。

string(20) "15370156633245019617"
string(3) "683"

Warning: gmp_random_seed(): Unable to convert variable to GMP - string is not an integer in %s on line %d
bool(false)

参考

  • gmp_init() - GMP 数を作成する
  • gmp_random() - 乱数を生成する
  • gmp_random_bits() - 乱数を生成する
  • gmp_random_range() - 等確率に選ばれた整数を取得する


n乗根の整数部を返す

  • ≪ gmp_random_seed
  • gmp_rootrem ≫
  • PHP Manual
  • GMP 関数
  • n乗根の整数部を返す

gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — n乗根の整数部を返す

説明

gmp_root(GMP|int|string $num, int $nth): GMP

num の nth 乗根を計算し、 その整数部を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

nth

num の正のべき乗根

戻り値

結果の整数部をGMP数として返します。


n乗根の整数部分と小数部分を返す

  • ≪ gmp_root
  • gmp_scan0 ≫
  • PHP Manual
  • GMP 関数
  • n乗根の整数部分と小数部分を返す

gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — n乗根の整数部分と小数部分を返す

説明

gmp_rootrem(GMP|int|string $num, int $nth): array

num の nth 乗根を計算し、 整数部分と小数部分を返します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

nth

num の正のn乗根

戻り値

ふたつの要素の配列を返します。 最初の要素はn乗根の整数部分、ふたつめの要素は小数部分です。 両方ともGMP数として表現されます。


0 を探す

  • ≪ gmp_rootrem
  • gmp_scan1 ≫
  • PHP Manual
  • GMP 関数
  • 0 を探す

gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — 0 を探す

説明

gmp_scan0(GMP|int|string $num1, int $start): int

ビット start から最上位ビットの方に、 最初のクリアビットが見付かるまで num1 をスキャンします。

パラメータ

num1

スキャンする数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

start

開始するビット。

戻り値

ビットが見つかった場所のインデックスを整数値で返します。 インデックスは 0 から始まります。

例

例1 gmp_scan0() の例

<?php
// 0 番目から探しはじめ、3 番目の位置に "0" ビットが見つかります
$s1 = gmp_init("10111", 2);
echo gmp_scan0($s1, 0) . "\n";

// 5 番目から探しはじめ、7 番目の位置に "0" ビットが見つかります
$s2 = gmp_init("101110000", 2);
echo gmp_scan0($s2, 5) . "\n";
?>

上の例の出力は以下となります。

3
7


1 を探す

  • ≪ gmp_scan0
  • gmp_setbit ≫
  • PHP Manual
  • GMP 関数
  • 1 を探す

gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — 1 を探す

説明

gmp_scan1(GMP|int|string $num1, int $start): int

ビット start から最上位ビットの方に、 セットされているビットが最初に見付かるまで num1 をスキャンします。

パラメータ

num1

スキャンする数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

start

開始するビット。

戻り値

ビットが見つかった場所のインデックスを整数値で返します。 セットされているビットが存在しない場合には -1 を返します。

例

例1 gmp_scan1() の例

<?php
// 0 番目から探しはじめ、3 番目の位置に "1" ビットが見つかります
$s1 = gmp_init("01000", 2);
echo gmp_scan1($s1, 0) . "\n";

// 5 番目から探しはじめ、9 番目の位置に "1" ビットが見つかります
$s2 = gmp_init("01000001111", 2);
echo gmp_scan1($s2, 5) . "\n";
?>

上の例の出力は以下となります。

3
9


ビットを設定する

  • ≪ gmp_scan1
  • gmp_sign ≫
  • PHP Manual
  • GMP 関数
  • ビットを設定する

gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — ビットを設定する

説明

gmp_setbit(GMP $num, int $index, bool $value = true): void

num のビット index を設定します。

パラメータ

num

GMP オブジェクト

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

index

設定するビットのインデックス。0 は最下位ビットを表します。

value

true にするとそのビットを設定し (値を 1/on にし)、 false にするとそのビットをクリアします (値を 0/off にします)。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_setbit() の例 - インデックス 0

<?php
$a = gmp_init("2"); //
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
gmp_setbit($a, 0); // 0b10 が 0b11 になります
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
?>

上の例の出力は以下となります。

2 -> 0b10
3 -> 0b11

例2 gmp_setbit() の例 - インデックス 1

<?php
$a = gmp_init("0xfd");
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
gmp_setbit($a, 1); // インデックスは 0 から始まります
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
?>

上の例の出力は以下となります。

253 -> 0b11111101
255 -> 0b11111111

例3 gmp_setbit() の例 - ビットのクリア

<?php
$a = gmp_init("0xff");
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
gmp_setbit($a, 0, false); // インデックス 0 のビットをクリアします
echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
?>

上の例の出力は以下となります。

255 -> 0b11111111
254 -> 0b11111110

注意

注意:

他の大半の GMP 関数とは異なり、gmp_setbit() は必ず既存の GMP オブジェクト (例えば gmp_init() を使用して取得したもの) を使用してコールしなければなりません。 リソースは自動的には作成されません。

参考

  • gmp_clrbit() - ビットをクリアする
  • gmp_testbit() - ビットが設定されているかどうかを調べる


数の符号

  • ≪ gmp_setbit
  • gmp_sqrt ≫
  • PHP Manual
  • GMP 関数
  • 数の符号

gmp_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — 数の符号

説明

gmp_sign(GMP|int|string $num): int

数の符号を調べます。

パラメータ

num

GMP オブジェクトまたは int に変換可能な数値形式の文字列。

戻り値

num が正の場合に 1、 num が負の場合に -1、そして num がゼロの場合に 0 を返します。

例

例1 gmp_sign() の例

<?php
// 正
echo gmp_sign("500") . "\n";

// 負
echo gmp_sign("-500") . "\n";

// ゼロ
echo gmp_sign("0") . "\n";
?>

上の例の出力は以下となります。

1
-1
0

参考

  • gmp_abs() - 絶対値
  • abs() - 絶対値


平方根を計算する

  • ≪ gmp_sign
  • gmp_sqrtrem ≫
  • PHP Manual
  • GMP 関数
  • 平方根を計算する

gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — 平方根を計算する

説明

gmp_sqrt(GMP|int|string $num): GMP

num の平方根を計算します。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

平方根の整数部分を GMP 数で返します。

例

例1 gmp_sqrt() の例

<?php
$sqrt1 = gmp_sqrt("9");
$sqrt2 = gmp_sqrt("7");
$sqrt3 = gmp_sqrt("1524157875019052100");

echo gmp_strval($sqrt1) . "\n";
echo gmp_strval($sqrt2) . "\n";
echo gmp_strval($sqrt3) . "\n";
?>

上の例の出力は以下となります。

3
2
1234567890


余りつきの平方根

  • ≪ gmp_sqrt
  • gmp_strval ≫
  • PHP Manual
  • GMP 関数
  • 余りつきの平方根

gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — 余りつきの平方根

説明

gmp_sqrtrem(GMP|int|string $num): array

ある数の平方根を余りつきで計算します。

パラメータ

num

平方根を計算したい数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

最初の要素が num の整数平方根 (gmp_sqrt()も参照ください)、2 番目の要素が余り (すなわち、num と最初の要素の 2 乗の差) であるような配列を返します。

例

例1 gmp_sqrtrem() の例

<?php
list($sqrt1, $sqrt1rem) = gmp_sqrtrem("9");
list($sqrt2, $sqrt2rem) = gmp_sqrtrem("7");
list($sqrt3, $sqrt3rem) = gmp_sqrtrem("1048576");

echo gmp_strval($sqrt1) . ", " . gmp_strval($sqrt1rem) . "\n";
echo gmp_strval($sqrt2) . ", " . gmp_strval($sqrt2rem) . "\n";
echo gmp_strval($sqrt3) . ", " . gmp_strval($sqrt3rem) . "\n";
?>

上の例の出力は以下となります。

3, 0
2, 3
1024, 0


GMP 数を文字列に変換する

  • ≪ gmp_sqrtrem
  • gmp_sub ≫
  • PHP Manual
  • GMP 関数
  • GMP 数を文字列に変換する

gmp_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — GMP 数を文字列に変換する

説明

gmp_strval(GMP|int|string $num, int $base = 10): string

GMP 数を base を基数とする文字列表現に変換します。 デフォルトの基数は 10 です。

パラメータ

num

文字列の変換したい GMP 数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

base

戻り値の基数。デフォルトは 10 です。 基数として使用可能な値は 2 から 62 までおよび -2 から -36 までです。

戻り値

数を文字列で表したものを返します。

例

例1 GMP 数を文字列に変換する

<?php
$a = gmp_init("0x41682179fbf5");
printf("10 進数: %s, 36 進数: %s", gmp_strval($a), gmp_strval($a,36));
?>


数値の減算

  • ≪ gmp_strval
  • gmp_testbit ≫
  • PHP Manual
  • GMP 関数
  • 数値の減算

gmp_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — 数値の減算

説明

gmp_sub(GMP|int|string $num1, GMP|int|string $num2): GMP

num1 から num2 を引いた結果を返します。

パラメータ

num1

引かれる数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

num1 から引く数。

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_sub() の例

<?php
$sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
echo gmp_strval($sub) . "\n";
?>

上の例の出力は以下となります。

281470681743360


ビットが設定されているかどうかを調べる

  • ≪ gmp_sub
  • gmp_xor ≫
  • PHP Manual
  • GMP 関数
  • ビットが設定されているかどうかを調べる

gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — ビットが設定されているかどうかを調べる

説明

gmp_testbit(GMP|int|string $num, int $index): bool

指定したビットが設定されているかどうかを調べます。

パラメータ

num

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

index

調べたいビット。

戻り値

num にビットが設定されている場合に true、 それ以外の場合に false を返します。

エラー / 例外

index に負の数を指定すると E_WARNING が発生し、false を返します。

例

例1 gmp_testbit() の例

<?php
$n = gmp_init("1000000");
var_dump(gmp_testbit($n, 1));
gmp_setbit($n, 1);
var_dump(gmp_testbit($n, 1));
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • gmp_setbit() - ビットを設定する
  • gmp_clrbit() - ビットをクリアする


ビット XOR を計算する

  • ≪ gmp_testbit
  • GMP ≫
  • PHP Manual
  • GMP 関数
  • ビット XOR を計算する

gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — ビット XOR を計算する

説明

gmp_xor(GMP|int|string $num1, GMP|int|string $num2): GMP

2 つの GMP 数のビット排他的論理和 (XOR) を計算します。

パラメータ

num1

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

num2

GMP オブジェクト、整数、あるいは数値に変換可能な数値形式の文字列。

戻り値

GMP オブジェクトを返します。

例

例1 gmp_xor() の例

<?php
$xor1 = gmp_init("1101101110011101", 2);
$xor2 = gmp_init("0110011001011001", 2);

$xor3 = gmp_xor($xor1, $xor2);

echo gmp_strval($xor3, 2) . "\n";
?>

上の例の出力は以下となります。

1011110111000100


GMP クラス

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

はじめに

GMP 数。このオブジェクトは、オーバーロードされた 算術演算子, ビット演算子, 比較演算子 をサポートしています。

注意:

GMP オブジェクトを操作するオブジェクト指向インターフェイスは用意されていません。 手続き型の GMP API を使いましょう。

クラス概要

class GMP {
/* メソッド */
public __construct(int|string $num = 0, int $base = 0)
public __serialize(): array
public __unserialize(array $data): void
}

目次

  • GMP::__construct — GMP数を作成する
  • GMP::__serialize — GMP オブジェクトをシリアライズする
  • GMP::__unserialize — data 引数をGMP オブジェクトとして復元する


GMP数を作成する

  • ≪ GMP
  • GMP::__serialize ≫
  • PHP Manual
  • GMP
  • GMP数を作成する

GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — GMP数を作成する

説明

public GMP::__construct(int|string $num = 0, int $base = 0)

整数または文字列から、GMP数を作成します。

パラメータ

num

整数または文字列。 文字列表現の場合、10進数、8進数、または16進数が指定可能です。

base

基数

基数は、2から62までの値が指定できます。 この値が0(デフォルト値) の場合、 実際の値は先頭に付加されている文字によって決まります。 最初の2文字が 0x や 0X の場合、16進数が仮定されます。最初の2文字が 0b や 0B の場合、2進数が仮定されます。それら以外の場合で、 最初の文字が 0 の場合、8進数が仮定されます。 これら以外の場合、10進数が仮定されます。 基数が36までの場合、大文字小文字は区別されません。 つまり、大文字だろうと小文字だろうと同じ値です。 基数が37から62までの場合、大文字は通常の10から35までの値を表します。 小文字の場合、36から61までの値を表します。

参考

  • gmp_init() - GMP 数を作成する


GMP オブジェクトをシリアライズする

  • ≪ GMP::__construct
  • GMP::__unserialize ≫
  • PHP Manual
  • GMP
  • GMP オブジェクトをシリアライズする

GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — GMP オブジェクトをシリアライズする

説明

public GMP::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


data 引数をGMP オブジェクトとして復元する

  • ≪ GMP::__serialize
  • Math ≫
  • PHP Manual
  • GMP
  • data 引数をGMP オブジェクトとして復元する

GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — data 引数をGMP オブジェクトとして復元する

説明

public GMP::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

アンシリアライズされる値。

戻り値

値を返しません。


数学関数

  • はじめに
  • 定義済み定数
  • Math 関数
    • abs — 絶対値
    • acos — 逆余弦（アークコサイン）
    • acosh — 逆双曲線余弦（アークハイパボリックコサイン）
    • asin — 逆正弦（アークサイン）
    • asinh — 逆双曲線正弦（アークハイパボリックサイン）
    • atan — 逆正接（アークタンジェント）
    • atan2 — 2 変数のアークタンジェント
    • atanh — 逆双曲線正接（アークハイパボリックタンジェント）
    • base_convert — 数値の基数を任意に変換する
    • bindec — 2 進数 を 10 進数に変換する
    • ceil — 端数の切り上げ
    • cos — 余弦（コサイン）
    • cosh — 双曲線余弦（ハイパボリックコサイン）
    • decbin — 10 進数を 2 進数に変換する
    • dechex — 10 進数を 16 進数に変換する
    • decoct — 10 進数を 8 進数に変換する
    • deg2rad — 度単位の数値をラジアン単位に変換する
    • exp — e の累乗を計算する
    • expm1 — 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す
    • fdiv — IEEE 754 に従い、数値の除算を行う
    • floor — 端数の切り捨て
    • fmod — 引数で除算をした際の剰余を返す
    • hexdec — 16 進数を 10 進数に変換する
    • hypot — 直角三角形の斜辺の長さを計算する
    • intdiv — 整数値の除算
    • is_finite — 浮動小数点数の値が、有限の数値であるかどうかを調べる
    • is_infinite — 浮動小数点数の値が、無限大であるかどうかを調べる
    • is_nan — 浮動小数点数の値が、非数かどうかを調べる
    • log — 自然対数
    • log10 — 底が 10 の対数
    • log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
    • max — 最大値を返す
    • min — 最小値を返す
    • octdec — 8 進数を 10 進数に変換する
    • pi — 円周率の値を得る
    • pow — 指数表現
    • rad2deg — ラジアン単位の数値を度単位に変換する
    • round — 浮動小数点数を丸める
    • sin — 正弦（サイン）
    • sinh — 双曲線正弦（ハイパボリックサイン）
    • sqrt — 平方根
    • tan — 正接（タンジェント）
    • tanh — 双曲線正接（ハイパボリックタンジェント）


はじめに

これらの数学関数は、実行するコンピューターの int型および float型の範囲で のみ値を処理します。 より大きな数を処理する必要がある場合には、 任意精度数学関数 や GNU Multiple Precision(GMP) の使用をお勧めします。

参考

  • 算術演算子
  • 任意精度数学関数
  • GNU Multiple Precision(GMP)


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

Math の定数
定数 | 値 | 説明 | 使用可能
M_PI | 3.14159265358979323846 | パイ（円周率） |
M_E | 2.7182818284590452354 | e（自然対数の底） |
M_LOG2E | 1.4426950408889634074 | log_2 e |
M_LOG10E | 0.43429448190325182765 | log_10 e |
M_LN2 | 0.69314718055994530942 | log_e 2 |
M_LN10 | 2.30258509299404568402 | log_e 10 |
M_PI_2 | 1.57079632679489661923 | pi/2 |
M_PI_4 | 0.78539816339744830962 | pi/4 |
M_1_PI | 0.31830988618379067154 | 1/pi |
M_2_PI | 0.63661977236758134308 | 2/pi |
M_SQRTPI | 1.77245385090551602729 | sqrt(pi) |
M_2_SQRTPI | 1.12837916709551257390 | 2/sqrt(pi) |
M_SQRT2 | 1.41421356237309504880 | sqrt(2) |
M_SQRT3 | 1.73205080756887729352 | sqrt(3) |
M_SQRT1_2 | 0.70710678118654752440 | 1/sqrt(2) |
M_LNPI | 1.14472988584940017414 | log_e(pi) |
M_EULER | 0.57721566490153286061 | オイラー定数 |
PHP_ROUND_HALF_UP | 1 | 端数を切り上げる |
PHP_ROUND_HALF_DOWN | 2 | 端数を切り捨てる |
PHP_ROUND_HALF_EVEN | 3 | 端数を偶数に丸める |
PHP_ROUND_HALF_ODD | 4 | 端数を奇数に丸める |
NAN | NAN (float) | 非数値 |
INF | INF (float) | 無限 |


Math 関数

目次

  • abs — 絶対値
  • acos — 逆余弦（アークコサイン）
  • acosh — 逆双曲線余弦（アークハイパボリックコサイン）
  • asin — 逆正弦（アークサイン）
  • asinh — 逆双曲線正弦（アークハイパボリックサイン）
  • atan — 逆正接（アークタンジェント）
  • atan2 — 2 変数のアークタンジェント
  • atanh — 逆双曲線正接（アークハイパボリックタンジェント）
  • base_convert — 数値の基数を任意に変換する
  • bindec — 2 進数 を 10 進数に変換する
  • ceil — 端数の切り上げ
  • cos — 余弦（コサイン）
  • cosh — 双曲線余弦（ハイパボリックコサイン）
  • decbin — 10 進数を 2 進数に変換する
  • dechex — 10 進数を 16 進数に変換する
  • decoct — 10 進数を 8 進数に変換する
  • deg2rad — 度単位の数値をラジアン単位に変換する
  • exp — e の累乗を計算する
  • expm1 — 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す
  • fdiv — IEEE 754 に従い、数値の除算を行う
  • floor — 端数の切り捨て
  • fmod — 引数で除算をした際の剰余を返す
  • hexdec — 16 進数を 10 進数に変換する
  • hypot — 直角三角形の斜辺の長さを計算する
  • intdiv — 整数値の除算
  • is_finite — 浮動小数点数の値が、有限の数値であるかどうかを調べる
  • is_infinite — 浮動小数点数の値が、無限大であるかどうかを調べる
  • is_nan — 浮動小数点数の値が、非数かどうかを調べる
  • log — 自然対数
  • log10 — 底が 10 の対数
  • log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
  • max — 最大値を返す
  • min — 最小値を返す
  • octdec — 8 進数を 10 進数に変換する
  • pi — 円周率の値を得る
  • pow — 指数表現
  • rad2deg — ラジアン単位の数値を度単位に変換する
  • round — 浮動小数点数を丸める
  • sin — 正弦（サイン）
  • sinh — 双曲線正弦（ハイパボリックサイン）
  • sqrt — 平方根
  • tan — 正接（タンジェント）
  • tanh — 双曲線正接（ハイパボリックタンジェント）


絶対値

  • ≪ Math 関数
  • acos ≫
  • PHP Manual
  • Math 関数
  • 絶対値

abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — 絶対値

説明

abs(int|float $num): int|float

num の絶対値を返します。

パラメータ

num

処理する数値。

戻り値

num の絶対値を返します。もし num の型が float であった場合、 戻り値の型も float となります。それ以外の場合は 戻り値の型は int となります（float は、 int の最大値より大きい値をとることがありえるからです）。

変更履歴

バージョン | 説明
8.0.0 | num は、 数値への変換をサポートした内部オブジェクトを受け入れなくなりました。

例

例1 abs() の例

<?php
var_dump(abs(-4.2));
var_dump(abs(5));
var_dump(abs(-5));
?>

上の例の出力は以下となります。

float(4.2)
int(5)
int(5)

参考

  • gmp_abs() - 絶対値
  • gmp_sign() - 数の符号


逆余弦（アークコサイン）

  • ≪ abs
  • acosh ≫
  • PHP Manual
  • Math 関数
  • 逆余弦（アークコサイン）

acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — 逆余弦（アークコサイン）

説明

acos(float $num): float

num のアークコサインをラジアンで返します。 acos() は cos() の逆関数です。 つまり、acos() の定義域にある num の全ての値に対して、$num == cos(acos($num)) が成立します。

パラメータ

num

処理する角度。

戻り値

num のアークコサインをラジアンで返します。

参考

  • cos() - 余弦（コサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
  • asin() - 逆正弦（アークサイン）
  • atan() - 逆正接（アークタンジェント）


逆双曲線余弦（アークハイパボリックコサイン）

  • ≪ acos
  • asin ≫
  • PHP Manual
  • Math 関数
  • 逆双曲線余弦（アークハイパボリックコサイン）

acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — 逆双曲線余弦（アークハイパボリックコサイン）

説明

acosh(float $num): float

num のアークハイパボリックコサインを返します。 つまり、ハイパボリックコサインが num となる値です。

パラメータ

num

処理する値。

戻り値

num のアークハイパボリックコサインを返します。

参考

  • cosh() - 双曲線余弦（ハイパボリックコサイン）
  • acos() - 逆余弦（アークコサイン）
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）


逆正弦（アークサイン）

  • ≪ acosh
  • asinh ≫
  • PHP Manual
  • Math 関数
  • 逆正弦（アークサイン）

asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — 逆正弦（アークサイン）

説明

asin(float $num): float

num のアークサインをラジアンで返します。 asin() は sin() の逆関数です。 つまり、asin() の定義域にある num の全ての値に対して、$num == sin(asin($num)) が成立します。

パラメータ

num

処理する角度。

戻り値

num のアークサインをラジアンで返します。

参考

  • sin() - 正弦（サイン）
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • acos() - 逆余弦（アークコサイン）
  • atan() - 逆正接（アークタンジェント）


逆双曲線正弦（アークハイパボリックサイン）

  • ≪ asin
  • atan ≫
  • PHP Manual
  • Math 関数
  • 逆双曲線正弦（アークハイパボリックサイン）

asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — 逆双曲線正弦（アークハイパボリックサイン）

説明

asinh(float $num): float

num のアークハイパボリックサインを返します。 つまり、ハイパボリックサインが num となる値です。

パラメータ

num

処理する角度。

戻り値

num のアークハイパボリックサインを返します。

参考

  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • asin() - 逆正弦（アークサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）


逆正接（アークタンジェント）

  • ≪ asinh
  • atan2 ≫
  • PHP Manual
  • Math 関数
  • 逆正接（アークタンジェント）

atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — 逆正接（アークタンジェント）

説明

atan(float $num): float

num のアークタンジェントをラジアンで返します。 atan() は tan() の逆関数です。 つまり、atan() の定義域にある num の全ての値に対して、$num == tan(atan($num)) が成立します。

パラメータ

num

処理する引数。

戻り値

num のアークタンジェントをラジアンで返します。

参考

  • tan() - 正接（タンジェント）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）
  • asin() - 逆正弦（アークサイン）
  • acos() - 逆余弦（アークコサイン）


2 変数のアークタンジェント

  • ≪ atan
  • atanh ≫
  • PHP Manual
  • Math 関数
  • 2 変数のアークタンジェント

atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — 2 変数のアークタンジェント

説明

atan2(float $y, float $x): float

この関数は、2 つの変数 x および y のアークタンジェントを計算します。 y / x のアークタンジェントを計算するのに似ていますが、 2 つの引数の符号を用いて結果の象限を定義することが異なっています。

この関数は、結果を -PI から PI の間(両端を含む)のラジアンで返します。

パラメータ

y

被除数。

x

除数。

戻り値

y/x のアークタンジェントをラジアンで返します。

参考

  • atan() - 逆正接（アークタンジェント）


逆双曲線正接（アークハイパボリックタンジェント）

  • ≪ atan2
  • base_convert ≫
  • PHP Manual
  • Math 関数
  • 逆双曲線正接（アークハイパボリックタンジェント）

atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — 逆双曲線正接（アークハイパボリックタンジェント）

説明

atanh(float $num): float

num のアークハイパボリックタンジェントを返します。 つまり、ハイパボリックタンジェントが num となる値です。

パラメータ

num

処理する引数。

戻り値

num のアークハイパボリックタンジェントを返します。

参考

  • tanh() - 双曲線正接（ハイパボリックタンジェント）
  • atan() - 逆正接（アークタンジェント）
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）


数値の基数を任意に変換する

  • ≪ atanh
  • bindec ≫
  • PHP Manual
  • Math 関数
  • 数値の基数を任意に変換する

base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — 数値の基数を任意に変換する

説明

base_convert(string $num, int $from_base, int $to_base): string

num を基数 to_base で表した文字列を返します。 num の基数は、 from_base で指定します。 from_base および to_base は、ともに 2 から 36 までである必要があります。 10 より大きな基数を有する数の各桁は、文字 a-z で表されます。 この場合、a は 10、b は 11、z は 35 を意味します。 num は、大文字小文字を区別せずに扱います。

警告

大きな数値で base_convert() を使用すると、 精度が失われてしまうことがあります。これは、内部で使用している float の性質によるものです。詳細な情報や制限については マニュアルの浮動小数点数 のセクションを参照ください。

パラメータ

num

変換する数値。 num に無効な文字が含まれている場合は、 何もエラーを出さずにただ無視します。 PHP 7.4.0 以降は、無効な文字を与えることは推奨されません。

from_base

変換前の num の基数。

to_base

変換後の num の基数。

戻り値

num を基数 to_base で表した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 base_convert() の例

<?php
$hexadecimal = 'a37334';
echo base_convert($hexadecimal, 16, 2);
?>

上の例の出力は以下となります。

101000110111001100110100

参考

  • intval() - 変数の整数としての値を取得する


2 進数 を 10 進数に変換する

  • ≪ base_convert
  • ceil ≫
  • PHP Manual
  • Math 関数
  • 2 進数 を 10 進数に変換する

bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — 2 進数 を 10 進数に変換する

説明

bindec(string $binary_string): int|float

引数 binary_string により指定された 2 進数と等価な 10 進数を返します。

bindec() は、2 進数を int に変換します。 サイズの問題により、必要に応じて float となることもあります。

bindec() は、すべての binary_string 値を符号なし整数として扱います。 これは、bindec() が最上位ビットを 符号ビットではなく別の桁とみなすからです。

パラメータ

binary_string

変換したい 2 進数文字列。 binary_string に無効な文字を与えても、静かに無視されます。 PHP 7.4.0 以降では、無効な文字を与えることは推奨されません。

警告

このパラメータは文字列でなければなりません。 他のデータ型を使用すると、予期せぬ結果となります。

戻り値

binary_string を 10 進に変換した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 bindec() の例

<?php
echo bindec('110011') . "\n";
echo bindec('000110011') . "\n";

echo bindec('111');
?>

上の例の出力は以下となります。

51
51
7

例2 bindec() が入力を符号なし整数として処理する例

<?php
/*
* The lesson from this example is in the output
* rather than the PHP code itself.
*/

$magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
p($magnitude_lower - 1);
p($magnitude_lower, 'See the rollover? Watch it next time around...');

p(PHP_INT_MAX, 'PHP_INT_MAX');
p(~PHP_INT_MAX, 'interpreted to be one more than PHP_INT_MAX');

if (PHP_INT_SIZE == 4) {
$note = 'interpreted to be the largest unsigned integer';
} else {
$note = 'interpreted to be the largest unsigned integer
(18446744073709551615) but skewed by float precision';
}
p(-1, $note);

function p($input, $note = '') {
echo "input: $input\n";

$format = '%0' . (PHP_INT_SIZE * 8) . 'b';
$bin = sprintf($format, $input);
echo "binary: $bin\n";

ini_set('precision', 20); // For readability on 64 bit boxes.
$dec = bindec($bin);
echo 'bindec(): ' . $dec . "\n";

if ($note) {
echo "NOTE: $note\n";
}

echo "\n";
}
?>

上の例の 32 ビットマシンでの出力は、このようになります。

input:        1073741823
binary:       00111111111111111111111111111111
bindec():     1073741823

input:        1073741824
binary:       01000000000000000000000000000000
bindec():     1073741824
NOTE:         See the rollover?  Watch it next time around...

input:        2147483647
binary:       01111111111111111111111111111111
bindec():     2147483647
NOTE:         PHP_INT_MAX

input:        -2147483648
binary:       10000000000000000000000000000000
bindec():     2147483648
NOTE:         interpreted to be one more than PHP_INT_MAX

input:        -1
binary:       11111111111111111111111111111111
bindec():     4294967295
NOTE:         interpreted to be the largest unsigned integer

上の例の 64 ビットマシンでの出力は、このようになります。

input:        4611686018427387903
binary:       0011111111111111111111111111111111111111111111111111111111111111
bindec():     4611686018427387903

input:        4611686018427387904
binary:       0100000000000000000000000000000000000000000000000000000000000000
bindec():     4611686018427387904
NOTE:         See the rollover?  Watch it next time around...

input:        9223372036854775807
binary:       0111111111111111111111111111111111111111111111111111111111111111
bindec():     9223372036854775807
NOTE:         PHP_INT_MAX

input:        -9223372036854775808
binary:       1000000000000000000000000000000000000000000000000000000000000000
bindec():     9223372036854775808
NOTE:         interpreted to be one more than PHP_INT_MAX

input:        -1
binary:       1111111111111111111111111111111111111111111111111111111111111111
bindec():     18446744073709551616
NOTE:         interpreted to be the largest unsigned integer
              (18446744073709551615) but skewed by float precision

注意

注意:

この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

参考

  • decbin() - 10 進数を 2 進数に変換する
  • octdec() - 8 進数を 10 進数に変換する
  • hexdec() - 16 進数を 10 進数に変換する
  • base_convert() - 数値の基数を任意に変換する


端数の切り上げ

  • ≪ bindec
  • cos ≫
  • PHP Manual
  • Math 関数
  • 端数の切り上げ

ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — 端数の切り上げ

説明

ceil(int|float $num): float

必要に応じて num を切り上げ、 num の次に大きい整数値を返します。

パラメータ

num

丸める値。

戻り値

num の次に大きい整数値を返します。 ceil() の戻り値は float 型と なります。これは、float 値の範囲は通常 int よりも広いためです。

変更履歴

バージョン | 説明
8.0.0 | num は、 数値への変換をサポートした内部オブジェクトを受け入れなくなりました。

例

例1 ceil() の例

<?php
echo ceil(4.3); // 5
echo ceil(9.999); // 10
echo ceil(-3.14); // -3
?>

参考

  • floor() - 端数の切り捨て
  • round() - 浮動小数点数を丸める


余弦（コサイン）

  • ≪ ceil
  • cosh ≫
  • PHP Manual
  • Math 関数
  • 余弦（コサイン）

cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — 余弦（コサイン）

説明

cos(float $num): float

cos() は、num のコサインを 返します。num はラジアンです。

パラメータ

num

ラジアンで表した角度。

戻り値

num のコサインを返します。

例

例1 cos() の例

<?php

echo cos(M_PI); // -1

?>

参考

  • acos() - 逆余弦（アークコサイン）
  • sin() - 正弦（サイン）
  • tan() - 正接（タンジェント）
  • deg2rad() - 度単位の数値をラジアン単位に変換する


双曲線余弦（ハイパボリックコサイン）

  • ≪ cos
  • decbin ≫
  • PHP Manual
  • Math 関数
  • 双曲線余弦（ハイパボリックコサイン）

cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — 双曲線余弦（ハイパボリックコサイン）

説明

cosh(float $num): float

num のハイパボリックコサインを返します。 これは、(exp($num) + exp(-$num))/2 で定義されます。

パラメータ

num

処理する引数。

戻り値

num のハイパボリックコサインを返します。

参考

  • cos() - 余弦（コサイン）
  • acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • tanh() - 双曲線正接（ハイパボリックタンジェント）


10 進数を 2 進数に変換する

  • ≪ cosh
  • dechex ≫
  • PHP Manual
  • Math 関数
  • 10 進数を 2 進数に変換する

decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — 10 進数を 2 進数に変換する

説明

decbin(int $num): string

引数 num を 2 進数表現した文字列を返します。

パラメータ

num

変換したい 10 進数値。

32 ビットマシンでの入力の範囲
正の num | 負の num | 戻り値
0 | 0
1 | 1
2 | 10
... normal progression ...
2147483646 | 1111111111111111111111111111110
2147483647 (符号付き integer の最大値) | 1111111111111111111111111111111 (1 が 31 個)
2147483648 | -2147483648 | 10000000000000000000000000000000
... normal progression ...
4294967294 | -2 | 11111111111111111111111111111110
4294967295 (符号なし integer の最大値) | -1 | 11111111111111111111111111111111 (1 が 32 個)
64 ビットマシンでの入力の範囲
正の num | 負の num | 戻り値
0 | 0
1 | 1
2 | 10
... normal progression ...
9223372036854775806 | 111111111111111111111111111111111111111111111111111111111111110
9223372036854775807 (符号付き integer の最大値) | 111111111111111111111111111111111111111111111111111111111111111 (1 が 63 個)
-9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
... normal progression ...
-2 | 1111111111111111111111111111111111111111111111111111111111111110
-1 | 1111111111111111111111111111111111111111111111111111111111111111 (1 が 64 個)

戻り値

num を 2 進文字列で表した値を返します。

例

例1 decbin() の例

<?php
echo decbin(12) . "\n";
echo decbin(26);
?>

上の例の出力は以下となります。

1100
11010

参考

  • bindec() - 2 進数 を 10 進数に変換する
  • decoct() - 10 進数を 8 進数に変換する
  • dechex() - 10 進数を 16 進数に変換する
  • base_convert() - 数値の基数を任意に変換する
  • printf() - フォーマット済みの文字列を出力する でのフォーマット %b、 %032b あるいは %064b
  • sprintf() - フォーマットされた文字列を返す でのフォーマット %b、 %032b あるいは %064b


10 進数を 16 進数に変換する

  • ≪ decbin
  • decoct ≫
  • PHP Manual
  • Math 関数
  • 10 進数を 16 進数に変換する

dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — 10 進数を 16 進数に変換する

説明

dechex(int $num): string

num で指定した符号なし整数値を 16 進数表現した文字列を返します。

変換できる最大の数字は、32 ビットプラットフォームの場合は PHP_INT_MAX * 2 + 1 (-1) です。これは 10 進数で表すと 4294967295 であり、 dechex() が返す結果は ffffffff になります。

パラメータ

num

変換したい 10 進数値。

PHP の int は符号付き整数ですが、 dechex() ではこれを符号なし整数として扱います。 つまり、負の整数を渡しても、それを符号なし整数として処理します。

戻り値

num を 16 進文字列で表した値を返します。

例

例1 dechex() の例

<?php
echo dechex(10) . "\n";
echo dechex(47);
?>

上の例の出力は以下となります。

a
2f

例2 dechex() での大きな整数の例

<?php
// 以下の出力例は 32 ビットプラットフォームでのものです。
// すべての結果が同じになることに注目しましょう。
echo dechex(-1)."\n";
echo dechex(PHP_INT_MAX * 2 + 1)."\n";
echo dechex(pow(2, 32) - 1)."\n";
?>

上の例の出力は以下となります。

ffffffff
ffffffff
ffffffff

参考

  • hexdec() - 16 進数を 10 進数に変換する
  • decbin() - 10 進数を 2 進数に変換する
  • decoct() - 10 進数を 8 進数に変換する
  • base_convert() - 数値の基数を任意に変換する


10 進数を 8 進数に変換する

  • ≪ dechex
  • deg2rad ≫
  • PHP Manual
  • Math 関数
  • 10 進数を 8 進数に変換する

decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — 10 進数を 8 進数に変換する

説明

decoct(int $num): string

引数 num を 8 進数表現した文字列を返します。 変換出来る最大の数字はプラットフォームによって異なります。 32 ビットプラットフォームでは、通常は十進数の 4294967295 であり、 これは 37777777777 を返します。 64 ビットプラットフォームでは、通常は十進数の 9223372036854775807 であり、これは 777777777777777777777 を返します。

パラメータ

num

変換したい 10 進数値。

戻り値

num を 8 進文字列で表した値を返します。

例

例1 decoct() の例

<?php
echo decoct(15) . "\n";
echo decoct(264);
?>

上の例の出力は以下となります。

17
410

参考

  • octdec() - 8 進数を 10 進数に変換する
  • decbin() - 10 進数を 2 進数に変換する
  • dechex() - 10 進数を 16 進数に変換する
  • base_convert() - 数値の基数を任意に変換する


度単位の数値をラジアン単位に変換する

  • ≪ decoct
  • exp ≫
  • PHP Manual
  • Math 関数
  • 度単位の数値をラジアン単位に変換する

deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — 度単位の数値をラジアン単位に変換する

説明

deg2rad(float $num): float

この関数は、num の単位を度からラジアンに変換します。

パラメータ

num

度で表した角度。

戻り値

num と同等な値をラジアンで表したものを返します。

例

例1 deg2rad() の例

<?php

echo deg2rad(45); // 0.785398163397
var_dump(deg2rad(45) === M_PI_4); // bool(true)

?>

参考

  • rad2deg() - ラジアン単位の数値を度単位に変換する


e の累乗を計算する

  • ≪ deg2rad
  • expm1 ≫
  • PHP Manual
  • Math 関数
  • e の累乗を計算する

exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — e の累乗を計算する

説明

exp(float $num): float

e を num 乗した値を返します。

注意:

'e' は自然対数の底で、およそ 2.718282 です。

パラメータ

num

処理する引数。

戻り値

'e' の num 乗を返します。

例

例1 exp() の例

<?php
echo exp(12) . "\n";
echo exp(5.7);
?>

上の例の出力は以下となります。

1.6275E+005
298.87

参考

  • log() - 自然対数
  • pow() - 指数表現


値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

  • ≪ exp
  • fdiv ≫
  • PHP Manual
  • Math 関数
  • 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

説明

expm1(float $num): float

expm1() は、 exp($num) - 1 の値を返します。 num がゼロに近く、 exp($num) - 1 が引き算時の桁落ちのために 不正確となるような場合でも正確な値が計算できる方法を使用します。

パラメータ

num

処理する引数。

戻り値

e の num 乗から 1 を引いた値を返します。

参考

  • log1p() - 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
  • exp() - e の累乗を計算する


IEEE 754 に従い、数値の除算を行う

  • ≪ expm1
  • floor ≫
  • PHP Manual
  • Math 関数
  • IEEE 754 に従い、数値の除算を行う

fdiv

(PHP 8)

fdiv — IEEE 754 に従い、数値の除算を行う

説明

fdiv(float $num1, float $num2): float

num1 を num2 で割った結果を浮動小数点数の結果として返します。 num2 が 0 の場合、 INF, -INF, NAN のうちのいずれかを返します。

NAN は、 いかなる値とも等しく(==) なりませんし、 いかなる値とも同値(===) にならない点に注意してください。 NAN 同士でも同じです。

パラメータ

num1

被除数(分子)

num2

除数

戻り値

num1/num2 の結果を浮動小数点数として返します。

例

例1 fdiv() を使う

<?php
var_dump(fdiv(5.7, 1.3)); // float(4.384615384615385)
var_dump(fdiv(4, 2)); // float(2)
var_dump(fdiv(1.0, 0.0)); // float(INF)
var_dump(fdiv(-1.0, 0.0)); // float(-INF)
var_dump(fdiv(0.0, 0.0)); // float(NAN)
?>

参考

  • / - 浮動小数点数の除算
  • intdiv() - 整数値の除算 - 整数値の除算
  • fmod() - 引数で除算をした際の剰余を返す - 剰余


端数の切り捨て

  • ≪ fdiv
  • fmod ≫
  • PHP Manual
  • Math 関数
  • 端数の切り捨て

floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — 端数の切り捨て

説明

floor(int|float $num): float

必要に応じて num を丸めることにより、 num をこえない最大の整数の値を (float 型で) 返します。

パラメータ

num

丸める数値。

戻り値

num をこえない最大の整数の値を返します。 floor() の戻り値は float 型のままとなります。

変更履歴

バージョン | 説明
8.0.0 | num は、 数値への変換をサポートした内部オブジェクトを受け入れなくなりました。

例

例1 floor() の例

<?php
echo floor(4.3); // 4
echo floor(9.999); // 9
echo floor(-3.14); // -4
?>

参考

  • ceil() - 端数の切り上げ
  • round() - 浮動小数点数を丸める


引数で除算をした際の剰余を返す

  • ≪ floor
  • hexdec ≫
  • PHP Manual
  • Math 関数
  • 引数で除算をした際の剰余を返す

fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — 引数で除算をした際の剰余を返す

説明

fmod(float $num1, float $num2): float

被除数（num1）を除数（num2） で割った余りを返します。余り（r）は、 整数 i を使用して num1 = i * num2 + r で定義されます。 num2 がゼロ以外の場合はr は num1 と同符号で、絶対値は num2 より小さくなります。

パラメータ

num1

被除数。

num2

除数。

戻り値

num1/num2 の剰余を返します。

例

例1 fmod() の使用法

<?php
$x = 5.7;
$y = 1.3;
$r = fmod($x, $y);
// $r は 0.5 です。なぜなら 4 * 1.3 + 0.5 = 5.7 だからです。
?>

参考

  • / - 浮動小数点数値の除算
  • % - 整数値の剰余
  • intdiv() - 整数値の除算 - 整数値の除算


16 進数を 10 進数に変換する

  • ≪ fmod
  • hypot ≫
  • PHP Manual
  • Math 関数
  • 16 進数を 10 進数に変換する

hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — 16 進数を 10 進数に変換する

説明

hexdec(string $hex_string): int|float

引数 hex_string により指定された 16 進数に 等価な 10 進数を返します。hexdec() は、16 進数を 表す文字列を 10 進数に変換します。

hexdec() は、16 進数以外の文字を一切無視します。 PHP 7.4.0 以降では、無効な文字を与えることは推奨されません。

パラメータ

hex_string

変換したい 16 進文字列。

戻り値

hex_string を 10 進で表した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 hexdec() の例

<?php
var_dump(hexdec("See"));
var_dump(hexdec("ee"));
// 共に "int(238)" を出力

var_dump(hexdec("that")); // "int(10)" を出力
var_dump(hexdec("a0")); // "int(160)" を出力
?>

注意

注意:

この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

参考

  • dechex() - 10 進数を 16 進数に変換する
  • bindec() - 2 進数 を 10 進数に変換する
  • octdec() - 8 進数を 10 進数に変換する
  • base_convert() - 数値の基数を任意に変換する


直角三角形の斜辺の長さを計算する

  • ≪ hexdec
  • intdiv ≫
  • PHP Manual
  • Math 関数
  • 直角三角形の斜辺の長さを計算する

hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — 直角三角形の斜辺の長さを計算する

説明

hypot(float $x, float $y): float

hypot() は、直角をはさむ 2 辺の長さが x および y である 直角三角形の斜辺の長さ、すなわち原点と (x, y) との距離を返します。 これは sqrt($x*$x + $y*$y) と等価です。

パラメータ

x

最初の辺の長さ。

y

二番目の辺の長さ。

戻り値

斜辺の長さを返します。


整数値の除算

  • ≪ hypot
  • is_finite ≫
  • PHP Manual
  • Math 関数
  • 整数値の除算

intdiv

(PHP 7, PHP 8)

intdiv — 整数値の除算

説明

intdiv(int $num1, int $num2): int

num1 を num2 で割った整数商を返します。

パラメータ

num1

割られる数。

num2

num1 を割る数。

戻り値

num1 を num2 で割った整数商。

エラー / 例外

num2 が 0 の場合、DivisionByZeroError 例外がスローされます。num1 が PHP_INT_MIN で num2 が -1 の場合、 ArithmeticError 例外がスローされます。

例

例1 intdiv() の例

<?php
var_dump(intdiv(3, 2));
var_dump(intdiv(-3, 2));
var_dump(intdiv(3, -2));
var_dump(intdiv(-3, -2));
var_dump(intdiv(PHP_INT_MAX, PHP_INT_MAX));
var_dump(intdiv(PHP_INT_MIN, PHP_INT_MIN));
var_dump(intdiv(PHP_INT_MIN, -1));
var_dump(intdiv(1, 0));
?>
int(1)
int(-1)
int(-1)
int(1)
int(1)
int(1)

Fatal error: Uncaught ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer in %s on line 8
Fatal error: Uncaught DivisionByZeroError: Division by zero in %s on line 9

参考

  • / - 浮動小数点数値の除算
  • % - 整数値の剰余
  • fmod() - 引数で除算をした際の剰余を返す - 浮動小数点数値の剰余


浮動小数点数の値が、有限の数値であるかどうかを調べる

  • ≪ intdiv
  • is_infinite ≫
  • PHP Manual
  • Math 関数
  • 浮動小数点数の値が、有限の数値であるかどうかを調べる

is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — 浮動小数点数の値が、有限の数値であるかどうかを調べる

説明

is_finite(float $num): bool

指定した num が有限の浮動小数点数かどうかを返します。

有限の浮動小数点数とは、NAN (is_nan()) でもなく、かつ 無限 (is_infinite()) でもない値です。

パラメータ

num

調べる float の値。

戻り値

num が NAN, INF, -INF のいずれでもない場合、true を返します。そうでない場合、false を返します。

例

例1 is_finite() の例

<?php
$float = 1.2345;
var_dump($float, is_finite($float));

$nan = sqrt(-1);
var_dump($nan, is_finite($nan));

$inf = 1e308 * 2;
var_dump($inf, is_finite($inf));
?>

上の例の出力は以下となります。

float(1.2345)
bool(true)
float(NAN)
bool(false)
float(INF)
bool(false)

参考

  • is_infinite() - 浮動小数点数の値が、無限大であるかどうかを調べる
  • is_nan() - 浮動小数点数の値が、非数かどうかを調べる


浮動小数点数の値が、無限大であるかどうかを調べる

  • ≪ is_finite
  • is_nan ≫
  • PHP Manual
  • Math 関数
  • 浮動小数点数の値が、無限大であるかどうかを調べる

is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — 浮動小数点数の値が、無限大であるかどうかを調べる

説明

is_infinite(float $num): bool

指定した num が、INF か -INF のいずれであるかを返します。

パラメータ

num

調べる float の値。

戻り値

num が INF, -INF のいずれかである場合、true を返します。そうでない場合、false を返します。

例

例1 is_infinite() の例

<?php
$inf = 1e308 * 2;

var_dump($inf, is_infinite($inf));

$negative_inf = -$inf;

var_dump($negative_inf, is_infinite($negative_inf));
?>

上の例の出力は以下となります。

float(INF)
bool(true)
float(-INF)
bool(true)

参考

  • is_finite() - 浮動小数点数の値が、有限の数値であるかどうかを調べる
  • is_nan() - 浮動小数点数の値が、非数かどうかを調べる


浮動小数点数の値が、非数かどうかを調べる

  • ≪ is_infinite
  • log ≫
  • PHP Manual
  • Math 関数
  • 浮動小数点数の値が、非数かどうかを調べる

is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — 浮動小数点数の値が、非数かどうかを調べる

説明

is_nan(float $num): bool

指定された num が、NAN (Not A Number) であるかどうかを返します。

数学的に未定義な演算が行われると、NAN が返されます。 たとえば関数に渡されるパラメータに、範囲外の値が渡されたときが該当します。 平方根(sqrt()) は、正の数値の場合にのみ定義されるので、負の数を渡すと結果は NAN になります。 NAN が返される他の例としては、INF の値を INF で割った場合や、 既に NAN とわかっている値と演算をした場合が挙げられます。

注意:

Not A Number という名前が付いていますが、NAN は float 型の値として正しい値です。

警告

NAN は、NAN と等しい値として比較できません。 浮動小数点数の値が NAN かを判定するには is_nan() を使わなければいけません。 コード $float === NAN は動作しません。

パラメータ

num

調べる float の値。

戻り値

num が NAN の場合、true を返します。そうでない場合、false を返します。

例

例1 is_nan() の例

<?php
$nan = sqrt(-1);

var_dump($nan, is_nan($nan));
?>

上の例の出力は以下となります。

float(NAN)
bool(true)

参考

  • is_finite() - 浮動小数点数の値が、有限の数値であるかどうかを調べる
  • is_infinite() - 浮動小数点数の値が、無限大であるかどうかを調べる


自然対数

  • ≪ is_nan
  • log10 ≫
  • PHP Manual
  • Math 関数
  • 自然対数

log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — 自然対数

説明

log(float $num, float $base = M_E): float

オプションの base パラメータを指定した場合は log() は logbase num を返します。それ以外の場合は log() は num の自然対数を返します。

パラメータ

num

対数を計算する値。

base

オプションで指定する、底 (デフォルトは 'e' で、これは自然対数となります)。

戻り値

base を指定した場合はそれを底とする num の対数、指定しない場合は自然対数を返します。

参考

  • log10() - 底が 10 の対数
  • exp() - e の累乗を計算する
  • pow() - 指数表現
  • error_log() - 定義されたエラー処理ルーチンにエラーメッセージを送信する


底が 10 の対数

  • ≪ log
  • log1p ≫
  • PHP Manual
  • Math 関数
  • 底が 10 の対数

log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — 底が 10 の対数

説明

log10(float $num): float

底を 10 とする num の対数を返します。

パラメータ

num

処理する引数。

戻り値

底を 10 とする num の対数を返します。

参考

  • log() - 自然対数


値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

  • ≪ log10
  • max ≫
  • PHP Manual
  • Math 関数
  • 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

説明

log1p(float $num): float

log1p() は、 log(1 + num) の値を返します。 num がゼロに近い場合でも正確な値が 計算できる方法を使用します。 log() は、このような場合には 精度の問題で log(1) の値を返してしまいます。

パラメータ

num

処理する引数。

戻り値

log(1 + num) を返します。

参考

  • expm1() - 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す
  • log() - 自然対数
  • log10() - 底が 10 の対数


最大値を返す

  • ≪ log1p
  • min ≫
  • PHP Manual
  • Math 関数
  • 最大値を返す

max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — 最大値を返す

説明

max(mixed $value, mixed ...$values): mixed

代替のシグネチャ (名前付き引数をサポートしていません):

max(array $value_array): mixed

パラメータとして配列をひとつだけ渡した場合は、max() は配列の中で最も大きい数値を返します。 ふたつ以上のパラメータを指定した場合は、max() はそれらの中で最も大きいものを返します。

注意:

異なる型の値を比較する際には、 標準の比較ルールに従います。 たとえば、数値形式でない string を int と比較するときには、数値 0 と評価します。 しかし、数値形式でない string どうしを比較するときには、アルファベット順で評価します。 返される値は、何も変換をしていない、元の型の値となります。

警告

異なる型の値を引数として渡す際には注意しましょう。 max() が予期せぬ結果を返す可能性があるからです。

パラメータ

value

任意の 比較可能な 値。

values

任意の 比較可能な 複数の値。

value_array

値を含んだ配列。

戻り値

max() は、パラメータとして渡した値の中で、標準の比較ルールに従って最大になるものを返します。 異なる型で同じ値と評価される複数の値 (0 と 'abc' など) があった場合は、関数に最初に渡されたほうを返します。

エラー / 例外

max() に空の配列を渡すと、 ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | max() は失敗した場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返し、 E_WARNING レベルのエラーが発生していました。
8.0.0 | 文字列と数値の比較方法が変更された ため、 数値と非数値文字列を比較した場合に、引数の順番に応じて異なる値を返さなくなりました。

例

例1 max() の使用例

<?php
echo max(2, 3, 1, 6, 7); // 7
echo max(array(2, 4, 5)); // 5

// -1 と 0 の比較なので、'hello' のほうが大きくなります
echo max('hello', -1); // hello

// 長さが異なる複数の配列を渡すと、いちばん長い配列を返します
$val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)

// 同じ長さの複数の配列を渡すと、max はその要素を左から
// 辞書順に比較します。この例では 2 == 2 ですが 5 > 4 となります
$val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)

// 配列と配列でない値が渡された場合、常に
// 配列が最大と判定されます。
$val = max('string', array(2, 5, 7), 42); // array(2, 5, 7)

// 一方の値が NULL や boolean の場合、それを他の値と比較するときには、
// もう一方の値の型が何であるかにかかわらず、FALSE < TRUE というルールを使います。
// 以下の例では、-10 は TRUE と評価されます。
$val = max(-10, FALSE); // -10

// 一方 0 は FALSE と評価されるので、TRUE よりは小さいとみなされます。
$val = max(0, TRUE); // TRUE
?>

参考

  • min() - 最小値を返す
  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える


最小値を返す

  • ≪ max
  • octdec ≫
  • PHP Manual
  • Math 関数
  • 最小値を返す

min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — 最小値を返す

説明

min(mixed $value, mixed ...$values): mixed

代替のシグネチャ (名前付き引数をサポートしていません):

min(array $value_array): mixed

パラメータとして配列をひとつだけ渡した場合は、 min() は配列の中で最も小さい数値を返します。 ふたつ以上のパラメータを指定した場合は、min() はそれらの中で最も小さいものを返します。

注意:

異なる型の値を比較する際には、 標準の比較ルールに従います。 たとえば、数値形式でない string を int と比較するときには、数値 0 と評価します。 しかし、数値形式でない string どうしを比較するときには、アルファベット順で評価します。 返される値は、何も変換をしていない、元の型の値となります。

警告

異なる型の値を引数として渡す際には注意しましょう。 min() が予期せぬ結果を返す可能性があるからです。

パラメータ

value

任意の 比較可能な 値。

values

任意の 比較可能な 複数の値。

value_array

値を含んだ配列。

戻り値

min() は、パラメータとして渡した値の中で、標準の比較ルールに従って最小になるものを返します。 異なる型で同じ値と評価される複数の値 (0 と 'abc' など) があった場合は、関数に最初に渡されたほうを返します。

エラー / 例外

min() に空の配列を渡すと、 ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | min() は失敗した場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返し、 E_WARNING レベルのエラーが発生していました。
8.0.0 | 文字列と数値の比較方法が変更された ため、 数値と非数値文字列を比較した場合に、引数の順番に応じて異なる値を返さなくなりました。

例

例1 min() の例

<?php
echo min(2, 3, 1, 6, 7); // 1
echo min(array(2, 4, 5)); // 2

// -1 と 0 の比較なので、-1 のほうが小さくなります
echo min('hello', -1); // -1

// 長さが異なる複数の配列を渡すと、いちばん短い配列を返します
$val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)

// 同じ長さの複数の配列を渡すと、max はその要素を左から
// 辞書順に比較します。この例では 2 == 2 ですが 4 < 5 となります
$val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)

// 配列と配列でない値が渡された場合、常に
// 配列が最大と判定されます。
$val = min('string', array(2, 5, 7), 42); // string

// 一方の値が NULL や boolean の場合、それを他の値と比較するときには、
// もう一方の値の型が何であるかにかかわらず、
// FALSE < TRUE / NULL == FALSE というルールを使います。
// 以下の例では、-10 と 10 はどちらも TRUE と評価されます。
$val = min(-10, FALSE, 10); // FALSE
$val = min(-10, NULL, 10); // NULL

// 一方 0 は FALSE と評価されるので、TRUE よりは小さいとみなされます。
$val = min(0, TRUE); // 0
?>

参考

  • max() - 最大値を返す
  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える


8 進数を 10 進数に変換する

  • ≪ min
  • pi ≫
  • PHP Manual
  • Math 関数
  • 8 進数を 10 進数に変換する

octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — 8 進数を 10 進数に変換する

説明

octdec(string $octal_string): int|float

octal_string により指定された 8 進数を 10 進数表現した数値を返します。

パラメータ

octal_string

変換したい 8 進文字列。 octal_string に無効な文字を与えても、静かに無視されます。 PHP 7.4.0 以降では、無効な文字を与えることは推奨されません。

戻り値

octal_string を 8 進で表した値を返します。

変更履歴

バージョン | 説明
7.4.0 | 無効な文字を与えると、非推奨の警告が出るようになりました。 結果は不正な文字がなかったかのように計算されます。

例

例1 octdec() の例

<?php
echo octdec('77') . "\n";
echo octdec(decoct(45));
?>

上の例の出力は以下となります。

63
45

注意

注意:

この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

参考

  • decoct() - 10 進数を 8 進数に変換する
  • bindec() - 2 進数 を 10 進数に変換する
  • hexdec() - 16 進数を 10 進数に変換する
  • base_convert() - 数値の基数を任意に変換する


円周率の値を得る

  • ≪ octdec
  • pow ≫
  • PHP Manual
  • Math 関数
  • 円周率の値を得る

pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — 円周率の値を得る

説明

pi(): float

円周率の近似値を返します。 また、定数 M_PI を使用することで pi() とまったく同じ結果を取得することも可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

円周率の値を不動小数点数で返します。

例

例1 pi() の例

<?php
echo pi(); // 3.1415926535898
echo M_PI; // 3.1415926535898
?>


指数表現

  • ≪ pi
  • rad2deg ≫
  • PHP Manual
  • Math 関数
  • 指数表現

pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — 指数表現

説明

pow(mixed $num, mixed $exponent): int|float|object

num の exponent 乗を返します。

注意:

** 演算子も使えます。

パラメータ

num

使用する基数。

exponent

指数。

戻り値

num の exponent 乗を返します。 両方の引数が非負の整数で、かつ結果が int 型の範囲に収まる場合は、結果を int 型で返します。 それ以外の場合は結果を float 型で返します。

PHP の拡張モジュールは、この演算の振る舞いを上書きし、オブジェクトを返させても構いません。

例

例1 pow() の例

<?php

var_dump(pow(2, 8)); // int(256)
echo pow(-1, 20), PHP_EOL; // 1
echo pow(0, 0), PHP_EOL; // 1
echo pow(10, -1), PHP_EOL; // 0.1
var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)

echo pow(-1, 5.5); // NAN

?>

注意

注意:

この関数はすべての入力を (スカラー値以外でも) 数値に変換します。 その結果、予想外の 結果を引き起こすことがあります。

参考

  • exp() - e の累乗を計算する
  • sqrt() - 平方根
  • bcpow() - 任意精度数値をべき乗する
  • gmp_pow() - べき乗を計算する


ラジアン単位の数値を度単位に変換する

  • ≪ pow
  • round ≫
  • PHP Manual
  • Math 関数
  • ラジアン単位の数値を度単位に変換する

rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — ラジアン単位の数値を度単位に変換する

説明

rad2deg(float $num): float

この関数は、num の単位をラジアンから度に変換します。

パラメータ

num

ラジアン値。

戻り値

num と同等な値を度で表したものを返します。

例

例1 rad2deg() の例

<?php

echo rad2deg(M_PI_4); // 45

?>

参考

  • deg2rad() - 度単位の数値をラジアン単位に変換する


浮動小数点数を丸める

  • ≪ rad2deg
  • sin ≫
  • PHP Manual
  • Math 関数
  • 浮動小数点数を丸める

round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — 浮動小数点数を丸める

説明

round(int|float $num, int $precision = 0, int $mode = PHP_ROUND_HALF_UP): float

num を、指定した precision(小数点以下の桁数)に丸めた値を 返します。precision を負またはゼロ(デフォルト) とすることも可能です。

パラメータ

num

丸める値。

precision

オプションで指定する、丸める桁数。

precision が正の値の場合、 num は 小数点以下、有効桁数 precision 桁に丸められます。

precision が負の場合、 num の 丸め処理は小数点より前の precision 桁に対して行われます。 つまり、一番近い pow(10, -$precision) の倍数に丸められます。 たとえば、precision が -1 の場合、 num は 一番近い10の倍数に、 precision が -2 の場合は 一番近い100の倍数に丸められる、という具合です。

mode

次の定数のいずれかを使って、丸めのモードを指定します。

定数 | 説明
PHP_ROUND_HALF_UP | 端数が5(半分)の場合、 num をゼロから離れる方向に丸めます。 1.5 は 2 に、そして -1.5 は -2 になります。
PHP_ROUND_HALF_DOWN | 端数が5(半分)の場合、 num をゼロに近づく方向に丸めます。 1.5 は 1 に、そして -1.5 は -1 になります。
PHP_ROUND_HALF_EVEN | 端数が5(半分)の場合、 num をもっとも近い偶数に丸めます。 1.5 や 2.5 は 2 になります。
PHP_ROUND_HALF_ODD | 端数が5(半分)の場合、 num をもっとも近い奇数に丸めます。 1.5 は 1 に、そして 2.5 は 3 になります。

戻り値

precision で与えられた精度に丸められた値を float で返します。

変更履歴

バージョン | 説明
8.0.0 | num は、 数値への変換をサポートした内部オブジェクトを受け入れなくなりました。

例

例1 round() の例

<?php
var_dump(round(3.4));
var_dump(round(3.5));
var_dump(round(3.6));
var_dump(round(3.6, 0));
var_dump(round(5.045, 2));
var_dump(round(5.055, 2));
var_dump(round(345, -2));
var_dump(round(345, -3));
var_dump(round(678, -2));
var_dump(round(678, -3));
?>

上の例の出力は以下となります。

float(3)
float(4)
float(4)
float(4)
float(5.05)
float(5.06)
float(300)
float(0)
float(700)
float(1000)

例2 precision が、どうfloatの値に影響するか

<?php
$number = 135.79;

var_dump(round($number, 3));
var_dump(round($number, 2));
var_dump(round($number, 1));
var_dump(round($number, 0));
var_dump(round($number, -1));
var_dump(round($number, -2));
var_dump(round($number, -3));
?>

上の例の出力は以下となります。

float(135.79)
float(135.79)
float(135.8)
float(136)
float(140)
float(100)
float(0)

例3 mode の例

<?php
echo 'Rounding modes with 9.5' . PHP_EOL;
var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

echo PHP_EOL;
echo 'Rounding modes with 8.5' . PHP_EOL;
var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
?>

上の例の出力は以下となります。

Rounding modes with 9.5
float(10)
float(9)
float(10)
float(9)

Rounding modes with 8.5
float(9)
float(8)
float(8)
float(9)

例4 桁数を指定した mode の例

<?php
echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
?>

上の例の出力は以下となります。

Using PHP_ROUND_HALF_UP with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
float(1.5)
float(-1.5)

Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
float(1.5)
float(-1.5)

参考

  • ceil() - 端数の切り上げ
  • floor() - 端数の切り捨て
  • number_format() - 数字を千の位毎にグループ化してフォーマットする


正弦（サイン）

  • ≪ round
  • sinh ≫
  • PHP Manual
  • Math 関数
  • 正弦（サイン）

sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — 正弦（サイン）

説明

sin(float $num): float

sin() は、num のサインを 返します。num はラジアンです。

パラメータ

num

ラジアンで表した値。

戻り値

num のサインを返します。

例

例1 sin() の例

<?php

// 結果の精度は、指定によります。
echo sin(deg2rad(60)); // 0.866025403 ...
echo sin(60); // -0.304810621 ...

?>

参考

  • asin() - 逆正弦（アークサイン）
  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • cos() - 余弦（コサイン）
  • tan() - 正接（タンジェント）
  • deg2rad() - 度単位の数値をラジアン単位に変換する


双曲線正弦（ハイパボリックサイン）

  • ≪ sin
  • sqrt ≫
  • PHP Manual
  • Math 関数
  • 双曲線正弦（ハイパボリックサイン）

sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — 双曲線正弦（ハイパボリックサイン）

説明

sinh(float $num): float

num のハイパボリックサインを返します。 これは、(exp($num) - exp(-$num))/2 で定義されます。

パラメータ

num

処理する引数。

戻り値

num のハイパボリックサインを返します。

参考

  • sin() - 正弦（サイン）
  • asinh() - 逆双曲線正弦（アークハイパボリックサイン）
  • cosh() - 双曲線余弦（ハイパボリックコサイン）
  • tanh() - 双曲線正接（ハイパボリックタンジェント）


平方根

  • ≪ sinh
  • tan ≫
  • PHP Manual
  • Math 関数
  • 平方根

sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — 平方根

説明

sqrt(float $num): float

num の平方根を返します。

パラメータ

num

処理する引数。

戻り値

num の平方根を返します。 負の数を指定した場合は、特別な値 NAN を返します。

例

例1 sqrt() の例

<?php
// 小数点以下の精度は、precision ディレクティブの設定に依存します
echo sqrt(9); // 3
echo sqrt(10); // 3.16227766 ...
?>

参考

  • pow() - 指数表現
  • M_SQRTPI - sqrt(pi)
  • M_2_SQRTPI - 2/sqrt(pi)
  • M_SQRT2 - sqrt(2)
  • M_SQRT3 - sqrt(3)
  • M_SQRT1_2 - 1/sqrt(2)


正接（タンジェント）

  • ≪ sqrt
  • tanh ≫
  • PHP Manual
  • Math 関数
  • 正接（タンジェント）

tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — 正接（タンジェント）

説明

tan(float $num): float

tan() は、num のタンジェントを 返します。num はラジアンです。

パラメータ

num

処理する引数をラジアンで表したもの。

戻り値

num のタンジェントを返します。

例

例1 tan() の例

<?php

echo tan(M_PI_4); // 1

?>

参考

  • atan() - 逆正接（アークタンジェント）
  • atan2() - 2 変数のアークタンジェント
  • sin() - 正弦（サイン）
  • cos() - 余弦（コサイン）
  • tanh() - 双曲線正接（ハイパボリックタンジェント）
  • deg2rad() - 度単位の数値をラジアン単位に変換する


双曲線正接（ハイパボリックタンジェント）

  • ≪ tan
  • Statistics ≫
  • PHP Manual
  • Math 関数
  • 双曲線正接（ハイパボリックタンジェント）

tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — 双曲線正接（ハイパボリックタンジェント）

説明

tanh(float $num): float

num のハイパボリックタンジェントを返します。 これは sinh($num)/cosh($num) で定義されます。

パラメータ

num

処理する引数。

戻り値

num のハイパボリックタンジェントを返します。

参考

  • tan() - 正接（タンジェント）
  • atanh() - 逆双曲線正接（アークハイパボリックタンジェント）
  • sinh() - 双曲線正弦（ハイパボリックサイン）
  • cosh() - 双曲線余弦（ハイパボリックコサイン）


Statistics

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Statistic 関数
    • stats_absolute_deviation — Returns the absolute deviation of an array of values
    • stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others
    • stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others
    • stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others
    • stats_cdf_chisquare — Calculates any one parameter of the chi-square distribution given values for the others
    • stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others
    • stats_cdf_f — Calculates any one parameter of the F distribution given values for the others
    • stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others
    • stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others
    • stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others
    • stats_cdf_negative_binomial — Calculates any one parameter of the negative binomial distribution given values for the others
    • stats_cdf_noncentral_chisquare — Calculates any one parameter of the non-central chi-square distribution given values for the others
    • stats_cdf_noncentral_f — Calculates any one parameter of the non-central F distribution given values for the others
    • stats_cdf_noncentral_t — Calculates any one parameter of the non-central t-distribution give values for the others
    • stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others
    • stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others
    • stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others
    • stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others
    • stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others
    • stats_covariance — Computes the covariance of two data sets
    • stats_dens_beta — Probability density function of the beta distribution
    • stats_dens_cauchy — Probability density function of the Cauchy distribution
    • stats_dens_chisquare — Probability density function of the chi-square distribution
    • stats_dens_exponential — Probability density function of the exponential distribution
    • stats_dens_f — Probability density function of the F distribution
    • stats_dens_gamma — Probability density function of the gamma distribution
    • stats_dens_laplace — Probability density function of the Laplace distribution
    • stats_dens_logistic — Probability density function of the logistic distribution
    • stats_dens_normal — Probability density function of the normal distribution
    • stats_dens_pmf_binomial — Probability mass function of the binomial distribution
    • stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution
    • stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution
    • stats_dens_pmf_poisson — Probability mass function of the Poisson distribution
    • stats_dens_t — Probability density function of the t-distribution
    • stats_dens_uniform — Probability density function of the uniform distribution
    • stats_dens_weibull — Probability density function of the Weibull distribution
    • stats_harmonic_mean — Returns the harmonic mean of an array of values
    • stats_kurtosis — Computes the kurtosis of the data in the array
    • stats_rand_gen_beta — Generates a random deviate from the beta distribution
    • stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution
    • stats_rand_gen_exponential — Generates a random deviate from the exponential distribution
    • stats_rand_gen_f — Generates a random deviate from the F distribution
    • stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)
    • stats_rand_gen_gamma — Generates a random deviate from the gamma distribution
    • stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution
    • stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution
    • stats_rand_gen_int — Generates random integer between 1 and 2147483562
    • stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution
    • stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)
    • stats_rand_gen_noncentral_chisquare — Generates a random deviate from the non-central chi-square distribution
    • stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution
    • stats_rand_gen_noncentral_t — Generates a single random deviate from a non-central t-distribution
    • stats_rand_gen_normal — Generates a single random deviate from a normal distribution
    • stats_rand_gen_t — Generates a single random deviate from a t-distribution
    • stats_rand_get_seeds — Get the seed values of the random number generator
    • stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator
    • stats_rand_ranf — Generates a random floating point number between 0 and 1
    • stats_rand_setall — Set seed values to the random generator
    • stats_skew — Computes the skewness of the data in the array
    • stats_standard_deviation — Returns the standard deviation
    • stats_stat_binomial_coef — Returns a binomial coefficient
    • stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets
    • stats_stat_factorial — Returns the factorial of an integer
    • stats_stat_independent_t — Returns the t-value from the independent two-sample t-test
    • stats_stat_innerproduct — Returns the inner product of two vectors
    • stats_stat_paired_t — Returns the t-value of the dependent t-test for paired samples
    • stats_stat_percentile — Returns the percentile value
    • stats_stat_powersum — Returns the power sum of a vector
    • stats_variance — Returns the variance


はじめに

This is the statistics extension. It contains few dozens of functions useful for statistical computations. It is a wrapper around 2 scientific libraries, namely DCDFLIB (Library of C routines for Cumulative Distributions Functions, Inverses, and Other parameters) by B. Brown & J. Lavato and RANDLIB by Barry Brown, James Lavato & Kathy Russell. Includes CD and PD functions.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Statistics
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

No external libraries are needed. The extension comes bundled with the libraries used.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/stats.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


Statistic 関数

目次

  • stats_absolute_deviation — Returns the absolute deviation of an array of values
  • stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others
  • stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others
  • stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others
  • stats_cdf_chisquare — Calculates any one parameter of the chi-square distribution given values for the others
  • stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others
  • stats_cdf_f — Calculates any one parameter of the F distribution given values for the others
  • stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others
  • stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others
  • stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others
  • stats_cdf_negative_binomial — Calculates any one parameter of the negative binomial distribution given values for the others
  • stats_cdf_noncentral_chisquare — Calculates any one parameter of the non-central chi-square distribution given values for the others
  • stats_cdf_noncentral_f — Calculates any one parameter of the non-central F distribution given values for the others
  • stats_cdf_noncentral_t — Calculates any one parameter of the non-central t-distribution give values for the others
  • stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others
  • stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others
  • stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others
  • stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others
  • stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others
  • stats_covariance — Computes the covariance of two data sets
  • stats_dens_beta — Probability density function of the beta distribution
  • stats_dens_cauchy — Probability density function of the Cauchy distribution
  • stats_dens_chisquare — Probability density function of the chi-square distribution
  • stats_dens_exponential — Probability density function of the exponential distribution
  • stats_dens_f — Probability density function of the F distribution
  • stats_dens_gamma — Probability density function of the gamma distribution
  • stats_dens_laplace — Probability density function of the Laplace distribution
  • stats_dens_logistic — Probability density function of the logistic distribution
  • stats_dens_normal — Probability density function of the normal distribution
  • stats_dens_pmf_binomial — Probability mass function of the binomial distribution
  • stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution
  • stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution
  • stats_dens_pmf_poisson — Probability mass function of the Poisson distribution
  • stats_dens_t — Probability density function of the t-distribution
  • stats_dens_uniform — Probability density function of the uniform distribution
  • stats_dens_weibull — Probability density function of the Weibull distribution
  • stats_harmonic_mean — Returns the harmonic mean of an array of values
  • stats_kurtosis — Computes the kurtosis of the data in the array
  • stats_rand_gen_beta — Generates a random deviate from the beta distribution
  • stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution
  • stats_rand_gen_exponential — Generates a random deviate from the exponential distribution
  • stats_rand_gen_f — Generates a random deviate from the F distribution
  • stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)
  • stats_rand_gen_gamma — Generates a random deviate from the gamma distribution
  • stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution
  • stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution
  • stats_rand_gen_int — Generates random integer between 1 and 2147483562
  • stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution
  • stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)
  • stats_rand_gen_noncentral_chisquare — Generates a random deviate from the non-central chi-square distribution
  • stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution
  • stats_rand_gen_noncentral_t — Generates a single random deviate from a non-central t-distribution
  • stats_rand_gen_normal — Generates a single random deviate from a normal distribution
  • stats_rand_gen_t — Generates a single random deviate from a t-distribution
  • stats_rand_get_seeds — Get the seed values of the random number generator
  • stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator
  • stats_rand_ranf — Generates a random floating point number between 0 and 1
  • stats_rand_setall — Set seed values to the random generator
  • stats_skew — Computes the skewness of the data in the array
  • stats_standard_deviation — Returns the standard deviation
  • stats_stat_binomial_coef — Returns a binomial coefficient
  • stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets
  • stats_stat_factorial — Returns the factorial of an integer
  • stats_stat_independent_t — Returns the t-value from the independent two-sample t-test
  • stats_stat_innerproduct — Returns the inner product of two vectors
  • stats_stat_paired_t — Returns the t-value of the dependent t-test for paired samples
  • stats_stat_percentile — Returns the percentile value
  • stats_stat_powersum — Returns the power sum of a vector
  • stats_variance — Returns the variance


Returns the absolute deviation of an array of values

  • ≪ Statistic 関数
  • stats_cdf_beta ≫
  • PHP Manual
  • Statistic 関数
  • Returns the absolute deviation of an array of values

stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Returns the absolute deviation of an array of values

説明

stats_absolute_deviation(array $a): float

Returns the absolute deviation of the values in a.

パラメータ

a

The input array

戻り値

Returns the absolute deviation of the values in a, or false if a is empty or is not an array.


Calculates any one parameter of the beta distribution given values for the others

  • ≪ stats_absolute_deviation
  • stats_cdf_binomial ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the beta distribution given values for the others

stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others

説明

stats_cdf_beta(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the beta distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, alpha, and beta denotes cumulative distribution function, the value of the random variable, and shape parameters of the beta distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | alpha | beta
2 | x | CDF | alpha | beta
3 | alpha | x | CDF | beta
4 | beta | x | CDF | alpha

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, alpha, or beta, determined by which.


Calculates any one parameter of the binomial distribution given values for the others

  • ≪ stats_cdf_beta
  • stats_cdf_cauchy ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the binomial distribution given values for the others

stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others

説明

stats_cdf_binomial(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the binomial distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, n, and p denotes cumulative distribution function, the number of successes, the number of trials, and the success rate for each trial, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | n | p
2 | x | CDF | n | p
3 | n | x | CDF | p
4 | p | x | CDF | n

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, n, or p, determined by which.


Calculates any one parameter of the Cauchy distribution given values for the others

  • ≪ stats_cdf_binomial
  • stats_cdf_chisquare ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the Cauchy distribution given values for the others

stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others

説明

stats_cdf_cauchy(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Cauchy distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, x0, and gamma denotes cumulative distribution function, the value of the random variable, the location and the scale parameter of the Cauchy distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | x0 | gamma
2 | x | CDF | x0 | gamma
3 | x0 | x | CDF | gamma
4 | gamma | x | CDF | x0

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, x0, or gamma, determined by which.


Calculates any one parameter of the chi-square distribution given values for the others

  • ≪ stats_cdf_cauchy
  • stats_cdf_exponential ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the chi-square distribution given values for the others

stats_cdf_chisquare

(PECL stats >= 1.0.0)

stats_cdf_chisquare — Calculates any one parameter of the chi-square distribution given values for the others

説明

stats_cdf_chisquare(float $par1, float $par2, int $which): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the chi-square distribution. The kind of the return value and parameters (par1 and par2) are determined by which.

The following table lists the return value and parameters by which. CDF, x, and k denotes cumulative distribution function, the value of the random variable, and the degree of freedom of the chi-square distribution, respectively.

Return value and parameters
which | Return value | par1 | par2
1 | CDF | x | k
2 | x | CDF | k
3 | k | x | CDF

パラメータ

par1

The first parameter

par2

The second parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, or k, determined by which.


Calculates any one parameter of the exponential distribution given values for the others

  • ≪ stats_cdf_chisquare
  • stats_cdf_f ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the exponential distribution given values for the others

stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others

説明

stats_cdf_exponential(float $par1, float $par2, int $which): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the exponential distribution. The kind of the return value and parameters (par1 and par2) are determined by which.

The following table lists the return value and parameters by which. CDF, x, and lambda denotes cumulative distribution function, the value of the random variable, and the rate parameter of the exponential distribution, respectively.

Return value and parameters
which | Return value | par1 | par2
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

パラメータ

par1

The first parameter

par2

The second parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, or lambda, determined by which.


Calculates any one parameter of the F distribution given values for the others

  • ≪ stats_cdf_exponential
  • stats_cdf_gamma ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the F distribution given values for the others

stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — Calculates any one parameter of the F distribution given values for the others

説明

stats_cdf_f(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the F distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, d1, and d2 denotes cumulative distribution function, the value of the random variable, and the degree of freedoms of the F distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | d1 | d2
2 | x | CDF | d1 | d2
3 | d1 | x | CDF | d2
4 | d2 | x | CDF | d1

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, d1, or d2, determined by which.


Calculates any one parameter of the gamma distribution given values for the others

  • ≪ stats_cdf_f
  • stats_cdf_laplace ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the gamma distribution given values for the others

stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others

説明

stats_cdf_gamma(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the gamma distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, k, and theta denotes cumulative distribution function, the value of the random variable, and the shape and the scale parameter of the gamma distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | k | theta
2 | x | CDF | k | theta
3 | k | x | CDF | theta
4 | theta | x | CDF | k

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, k, or theta, determined by which.


Calculates any one parameter of the Laplace distribution given values for the others

  • ≪ stats_cdf_gamma
  • stats_cdf_logistic ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the Laplace distribution given values for the others

stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others

説明

stats_cdf_laplace(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Laplace distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, mu, and b denotes cumulative distribution function, the value of the random variable, and the location and the scale parameter of the Laplace distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | mu | b
2 | x | CDF | mu | b
3 | mu | x | CDF | b
4 | b | x | CDF | mu

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, mu, or b, determined by which.


Calculates any one parameter of the logistic distribution given values for the others

  • ≪ stats_cdf_laplace
  • stats_cdf_negative_binomial ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the logistic distribution given values for the others

stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others

説明

stats_cdf_logistic(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the logistic distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, mu, and s denotes cumulative distribution function, the value of the random variable, and the location and the scale parameter of the logistic distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | mu | s
2 | x | CDF | mu | s
3 | mu | x | CDF | s
4 | s | x | CDF | mu

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, mu, or s, determined by which.


Calculates any one parameter of the negative binomial distribution given values for the others

  • ≪ stats_cdf_logistic
  • stats_cdf_noncentral_chisquare ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the negative binomial distribution given values for the others

stats_cdf_negative_binomial

(PECL stats >= 1.0.0)

stats_cdf_negative_binomial — Calculates any one parameter of the negative binomial distribution given values for the others

説明

stats_cdf_negative_binomial(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the negative binomial distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, r, and p denotes cumulative distribution function, the number of failure, the number of success, and the success rate for each trial, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | r | p
2 | x | CDF | r | p
3 | r | x | CDF | p
4 | p | x | CDF | r

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, r, or p, determined by which.


Calculates any one parameter of the non-central chi-square distribution given values for the others

  • ≪ stats_cdf_negative_binomial
  • stats_cdf_noncentral_f ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the non-central chi-square distribution given values for the others

stats_cdf_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_cdf_noncentral_chisquare — Calculates any one parameter of the non-central chi-square distribution given values for the others

説明

stats_cdf_noncentral_chisquare(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the non-central chi-square distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, k, and lambda denotes cumulative distribution function, the value of the random variable, the degree of freedom and the non-centrality parameter of the distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, k, or lambda, determined by which.


Calculates any one parameter of the non-central F distribution given values for the others

  • ≪ stats_cdf_noncentral_chisquare
  • stats_cdf_noncentral_t ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the non-central F distribution given values for the others

stats_cdf_noncentral_f

(PECL stats >= 1.0.0)

stats_cdf_noncentral_f — Calculates any one parameter of the non-central F distribution given values for the others

説明

stats_cdf_noncentral_f(
float $par1,
float $par2,
float $par3,
float $par4,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the non-central F distribution. The kind of the return value and parameters (par1, par2, par3, and par4) are determined by which.

The following table lists the return value and parameters by which. CDF, x, nu1, nu2, and lambda denotes cumulative distribution function, the value of the random variable, the degree of freedoms and the non-centrality parameter of the distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3 | par4
1 | CDF | x | nu1 | nu2 | lambda
2 | x | CDF | nu1 | nu2 | lambda
3 | nu1 | x | CDF | nu2 | lambda
4 | nu2 | x | CDF | nu1 | lambda
5 | lambda | x | CDF | nu1 | nu2

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

par4

The fourth parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, nu1, nu2, or lambda, determined by which.


Calculates any one parameter of the non-central t-distribution give values for the others

  • ≪ stats_cdf_noncentral_f
  • stats_cdf_normal ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the non-central t-distribution give values for the others

stats_cdf_noncentral_t

(PECL stats >= 1.0.0)

stats_cdf_noncentral_t — Calculates any one parameter of the non-central t-distribution give values for the others

説明

stats_cdf_noncentral_t(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the non-central t-distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, nu, and mu denotes cumulative distribution function, the value of the random variable, the degrees of freedom and the non-centrality parameter of the distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | nu | mu
2 | x | CDF | nu | mu
3 | nu | x | CDF | mu
4 | mu | x | CDF | nu

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, nu, or mu, determined by which.


Calculates any one parameter of the normal distribution given values for the others

  • ≪ stats_cdf_noncentral_t
  • stats_cdf_poisson ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the normal distribution given values for the others

stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others

説明

stats_cdf_normal(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the normal distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, mu, and sigma denotes cumulative distribution function, the value of the random variable, the mean and the standard deviation of the normal distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | mu | sigma
2 | x | CDF | mu | sigma
3 | mu | x | CDF | sigma
4 | sigma | x | CDF | mu

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, mu, or sigma, determined by which.


Calculates any one parameter of the Poisson distribution given values for the others

  • ≪ stats_cdf_normal
  • stats_cdf_t ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the Poisson distribution given values for the others

stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others

説明

stats_cdf_poisson(float $par1, float $par2, int $which): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Poisson distribution. The kind of the return value and parameters (par1 and par2) are determined by which.

The following table lists the return value and parameters by which. CDF, x, and lambda denotes cumulative distribution function, the value of the random variable, and the parameter of the Poisson distribution, respectively.

Return value and parameters
which | Return value | par1 | par2
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

パラメータ

par1

The first parameter

par2

The second parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, or lambda, determined by which.


Calculates any one parameter of the t-distribution given values for the others

  • ≪ stats_cdf_poisson
  • stats_cdf_uniform ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the t-distribution given values for the others

stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others

説明

stats_cdf_t(float $par1, float $par2, int $which): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the t-distribution. The kind of the return value and parameters (par1 and par2) are determined by which.

The following table lists the return value and parameters by which. CDF, x, and nu denotes cumulative distribution function, the value of the random variable, and the degrees of freedom of the t-distribution, respectively.

Return value and parameters
which | Return value | par1 | par2
1 | CDF | x | nu
2 | x | CDF | nu
3 | nu | x | CDF

パラメータ

par1

The first parameter

par2

The second parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, or nu, determined by which.


Calculates any one parameter of the uniform distribution given values for the others

  • ≪ stats_cdf_t
  • stats_cdf_weibull ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the uniform distribution given values for the others

stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others

説明

stats_cdf_uniform(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the uniform distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, a, and b denotes cumulative distribution function, the value of the random variable, the lower bound and the higher bound of the uniform distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | a | b
2 | x | CDF | a | b
3 | a | x | CDF | b
4 | b | x | CDF | a

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, a, or b, determined by which.


Calculates any one parameter of the Weibull distribution given values for the others

  • ≪ stats_cdf_uniform
  • stats_covariance ≫
  • PHP Manual
  • Statistic 関数
  • Calculates any one parameter of the Weibull distribution given values for the others

stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others

説明

stats_cdf_weibull(
float $par1,
float $par2,
float $par3,
int $which
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Weibull distribution. The kind of the return value and parameters (par1, par2, and par3) are determined by which.

The following table lists the return value and parameters by which. CDF, x, k, and lambda denotes cumulative distribution function, the value of the random variable, the shape and the scale parameter of the Weibull distribution, respectively.

Return value and parameters
which | Return value | par1 | par2 | par3
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

パラメータ

par1

The first parameter

par2

The second parameter

par3

The third parameter

which

The flag to determine what to be calculated

戻り値

Returns CDF, x, k, or lambda, determined by which.


Computes the covariance of two data sets

  • ≪ stats_cdf_weibull
  • stats_dens_beta ≫
  • PHP Manual
  • Statistic 関数
  • Computes the covariance of two data sets

stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — Computes the covariance of two data sets

説明

stats_covariance(array $a, array $b): float

Returns the covariance of a and b.

パラメータ

a

The first array

b

The second array

戻り値

Returns the covariance of a and b, or false on failure.


Probability density function of the beta distribution

  • ≪ stats_covariance
  • stats_dens_cauchy ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the beta distribution

stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — Probability density function of the beta distribution

説明

stats_dens_beta(float $x, float $a, float $b): float

Returns the probability density at x, where the random variable follows the beta distribution of which the shape parameters are a and b.

パラメータ

x

The value at which the probability density is calculated

a

The shape parameter of the distribution

b

The shape parameter of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the Cauchy distribution

  • ≪ stats_dens_beta
  • stats_dens_chisquare ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the Cauchy distribution

stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — Probability density function of the Cauchy distribution

説明

stats_dens_cauchy(float $x, float $ave, float $stdev): float

Returns the probability density at x, where the random variable follows the Cauchy distribution whose location and scale are ave and stdev, respectively.

パラメータ

x

The value at which the probability density is calculated

ave

The location parameter of the distribution

stdev

The scale parameter of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the chi-square distribution

  • ≪ stats_dens_cauchy
  • stats_dens_exponential ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the chi-square distribution

stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — Probability density function of the chi-square distribution

説明

stats_dens_chisquare(float $x, float $dfr): float

Returns the probability density at x, where the random variable follows the chi-square distribution of which the degree of freedom is dfr.

パラメータ

x

The value at which the probability density is calculated

dfr

The degree of freedom of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the exponential distribution

  • ≪ stats_dens_chisquare
  • stats_dens_f ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the exponential distribution

stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — Probability density function of the exponential distribution

説明

stats_dens_exponential(float $x, float $scale): float

Returns the probability density at x, where the random variable follows the exponential distribution of which the scale is scale.

パラメータ

x

The value at which the probability density is calculated

scale

The scale of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the F distribution

  • ≪ stats_dens_exponential
  • stats_dens_gamma ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the F distribution

stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — Probability density function of the F distribution

説明

stats_dens_f(float $x, float $dfr1, float $dfr2): float

Returns the probability density at x, where the random variable follows the F distribution of which the degree of freedoms are dfr1 and dfr2.

パラメータ

x

The value at which the probability density is calculated

dfr1

The degree of freedom of the distribution

dfr2

The degree of freedom of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the gamma distribution

  • ≪ stats_dens_f
  • stats_dens_laplace ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the gamma distribution

stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — Probability density function of the gamma distribution

説明

stats_dens_gamma(float $x, float $shape, float $scale): float

Returns the probability density at x, where the random variable follows the gamma distribution of which the shape parameter is shape and the scale parameter is scale.

パラメータ

x

The value at which the probability density is calculated

shape

The shape parameter of the distribution

scale

The scale parameter of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the Laplace distribution

  • ≪ stats_dens_gamma
  • stats_dens_logistic ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the Laplace distribution

stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — Probability density function of the Laplace distribution

説明

stats_dens_laplace(float $x, float $ave, float $stdev): float

Returns the probability density at x, where the random variable follows the Laplace distribution of which the location parameter is ave and the scale parameter is stdev.

パラメータ

x

The value at which the probability density is calculated

ave

The location parameter of the distribution

stdev

The shape parameter of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the logistic distribution

  • ≪ stats_dens_laplace
  • stats_dens_normal ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the logistic distribution

stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — Probability density function of the logistic distribution

説明

stats_dens_logistic(float $x, float $ave, float $stdev): float

Returns the probability density at x, where the random variable follows the logistic distribution of which the location parameter is ave and the scale parameter is stdev.

パラメータ

x

The value at which the probability density is calculated

ave

The location parameter of the distribution

stdev

The shape parameter of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the normal distribution

  • ≪ stats_dens_logistic
  • stats_dens_pmf_binomial ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the normal distribution

stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — Probability density function of the normal distribution

説明

stats_dens_normal(float $x, float $ave, float $stdev): float

Returns the probability density at x, where the random variable follows the normal distribution of which the mean is ave and the standard deviation is stdev.

パラメータ

x

The value at which the probability density is calculated

ave

The mean of the distribution

stdev

The standard deviation of the distribution

戻り値

The probability density at x or false for failure.


Probability mass function of the binomial distribution

  • ≪ stats_dens_normal
  • stats_dens_pmf_hypergeometric ≫
  • PHP Manual
  • Statistic 関数
  • Probability mass function of the binomial distribution

stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — Probability mass function of the binomial distribution

説明

stats_dens_pmf_binomial(float $x, float $n, float $pi): float

Returns the probability mass at x, where the random variable follows the binomial distribution of which the number of trials is n and the success rate is pi.

パラメータ

x

The value at which the probability mass is calculated

n

The number of trials of the distribution

pi

The success rate of the distribution

戻り値

The probability mass at x or false for failure.


Probability mass function of the hypergeometric distribution

  • ≪ stats_dens_pmf_binomial
  • stats_dens_pmf_negative_binomial ≫
  • PHP Manual
  • Statistic 関数
  • Probability mass function of the hypergeometric distribution

stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution

説明

stats_dens_pmf_hypergeometric(
float $n1,
float $n2,
float $N1,
float $N2
): float

Returns the probability mass at n1, where the random variable follows the hypergeometric distribution of which the number of failure is n2, the number of success samples is N1, and the number of failure samples is N2.

パラメータ

n1

The number of success, at which the probability mass is calculated

n2

The number of failure of the distribution

N1

The number of success samples of the distribution

N2

The number of failure samples of the distribution

戻り値

The probability mass at n1 or false for failure.


Probability mass function of the negative binomial distribution

  • ≪ stats_dens_pmf_hypergeometric
  • stats_dens_pmf_poisson ≫
  • PHP Manual
  • Statistic 関数
  • Probability mass function of the negative binomial distribution

stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution

説明

stats_dens_pmf_negative_binomial(float $x, float $n, float $pi): float

Returns the probability mass at x, where the random variable follows the negative binomial distribution of which the number of the success is n and the success rate is pi.

パラメータ

x

The value at which the probability mass is calculated

n

The number of the success of the distribution

pi

The success rate of the distribution

戻り値

The probability mass at x or false for failure.


Probability mass function of the Poisson distribution

  • ≪ stats_dens_pmf_negative_binomial
  • stats_dens_t ≫
  • PHP Manual
  • Statistic 関数
  • Probability mass function of the Poisson distribution

stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — Probability mass function of the Poisson distribution

説明

stats_dens_pmf_poisson(float $x, float $lb): float

Returns the probability mass at x, where the random variable follows the Poisson distribution whose parameter is lb.

パラメータ

x

The value at which the probability mass is calculated

lb

The parameter of the Poisson distribution

戻り値

The probability mass at x or false for failure.


Probability density function of the t-distribution

  • ≪ stats_dens_pmf_poisson
  • stats_dens_uniform ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the t-distribution

stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — Probability density function of the t-distribution

説明

stats_dens_t(float $x, float $dfr): float

Returns the probability density at x, where the random variable follows the t-distribution of which the degree of freedom is dfr.

パラメータ

x

The value at which the probability density is calculated

dfr

The degree of freedom of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the uniform distribution

  • ≪ stats_dens_t
  • stats_dens_weibull ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the uniform distribution

stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — Probability density function of the uniform distribution

説明

stats_dens_uniform(float $x, float $a, float $b): float

Returns the probability density at x, where the random variable follows the uniform distribution of which the lower bound is a and the upper bound is b.

パラメータ

x

The value at which the probability density is calculated

a

The lower bound of the distribution

b

The upper bound of the distribution

戻り値

The probability density at x or false for failure.


Probability density function of the Weibull distribution

  • ≪ stats_dens_uniform
  • stats_harmonic_mean ≫
  • PHP Manual
  • Statistic 関数
  • Probability density function of the Weibull distribution

stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — Probability density function of the Weibull distribution

説明

stats_dens_weibull(float $x, float $a, float $b): float

Returns the probability density at x, where the random variable follows the Weibull distribution of which the shape parameter is a and the scale parameter is b.

パラメータ

x

The value at which the probability density is calculated

a

The shape parameter of the distribution

b

The scale parameter of the distribution

戻り値

The probability density at x or false for failure.


Returns the harmonic mean of an array of values

  • ≪ stats_dens_weibull
  • stats_kurtosis ≫
  • PHP Manual
  • Statistic 関数
  • Returns the harmonic mean of an array of values

stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — Returns the harmonic mean of an array of values

説明

stats_harmonic_mean(array $a): number

Returns the harmonic mean of the values in a.

パラメータ

a

The input array

戻り値

Returns the harmonic mean of the values in a, or false if a is empty or is not an array.


Computes the kurtosis of the data in the array

  • ≪ stats_harmonic_mean
  • stats_rand_gen_beta ≫
  • PHP Manual
  • Statistic 関数
  • Computes the kurtosis of the data in the array

stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — Computes the kurtosis of the data in the array

説明

stats_kurtosis(array $a): float

Returns the kurtosis of the values in a.

パラメータ

a

The input array

戻り値

Returns the kurtosis of the values in a, or false if a is empty or is not an array.


Generates a random deviate from the beta distribution

  • ≪ stats_kurtosis
  • stats_rand_gen_chisquare ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the beta distribution

stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — Generates a random deviate from the beta distribution

説明

stats_rand_gen_beta(float $a, float $b): float

Returns a random deviate from the beta distribution with parameters A and B. The density of the beta is x^(a-1) * (1-x)^(b-1) / B(a,b) for 0 < x <. Method R. C. H. Cheng.

パラメータ

a

The shape parameter of the beta distribution

b

The shape parameter of the beta distribution

戻り値

A random deviate


Generates a random deviate from the chi-square distribution

  • ≪ stats_rand_gen_beta
  • stats_rand_gen_exponential ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the chi-square distribution

stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution

説明

stats_rand_gen_chisquare(float $df): float

Returns a random deviate from the chi-square distribution where the degrees of freedom is df.

パラメータ

df

The degrees of freedom

戻り値

A random deviate


Generates a random deviate from the exponential distribution

  • ≪ stats_rand_gen_chisquare
  • stats_rand_gen_f ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the exponential distribution

stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Generates a random deviate from the exponential distribution

説明

stats_rand_gen_exponential(float $av): float

Returns a random deviate from the exponential distribution of which the scale is av.

パラメータ

av

The scale parameter

戻り値

A random deviate


Generates a random deviate from the F distribution

  • ≪ stats_rand_gen_exponential
  • stats_rand_gen_funiform ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the F distribution

stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Generates a random deviate from the F distribution

説明

stats_rand_gen_f(float $dfn, float $dfd): float

Generates a random deviate from the F (variance ratio) distribution with "dfn" degrees of freedom in the numerator and "dfd" degrees of freedom in the denominator. Method : directly generates ratio of chisquare variates.

パラメータ

dfn

The degrees of freedom in the numerator

dfd

The degrees of freedom in the denominator

戻り値

A random deviate


Generates uniform float between low (exclusive) and high (exclusive)

  • ≪ stats_rand_gen_f
  • stats_rand_gen_gamma ≫
  • PHP Manual
  • Statistic 関数
  • Generates uniform float between low (exclusive) and high (exclusive)

stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)

説明

stats_rand_gen_funiform(float $low, float $high): float

Returns a random deviate from the uniform distribution from low to high.

パラメータ

low

The lower bound (inclusive)

high

The upper bound (exclusive)

戻り値

A random deviate


Generates a random deviate from the gamma distribution

  • ≪ stats_rand_gen_funiform
  • stats_rand_gen_ibinomial ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the gamma distribution

stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Generates a random deviate from the gamma distribution

説明

stats_rand_gen_gamma(float $a, float $r): float

Generates a random deviate from the gamma distribution whose density is (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X).

パラメータ

a

location parameter of Gamma distribution (a > 0).

r

shape parameter of Gamma distribution (r > 0).

戻り値

A random deviate


Generates a random deviate from the binomial distribution

  • ≪ stats_rand_gen_gamma
  • stats_rand_gen_ibinomial_negative ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the binomial distribution

stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution

説明

stats_rand_gen_ibinomial(int $n, float $pp): int

Returns a random deviate from the binomial distribution whose number of trials is n and whose probability of an event in each trial is pp.

パラメータ

n

The number of trials

pp

The probability of an event in each trial

戻り値

A random deviate


Generates a random deviate from the negative binomial distribution

  • ≪ stats_rand_gen_ibinomial
  • stats_rand_gen_int ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the negative binomial distribution

stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution

説明

stats_rand_gen_ibinomial_negative(int $n, float $p): int

Returns a random deviate from a negative binomial distribution where the number of success is n and the success rate is p.

パラメータ

n

The number of success

p

The success rate

戻り値

A random deviate, which is the number of failure.


Generates random integer between 1 and 2147483562

  • ≪ stats_rand_gen_ibinomial_negative
  • stats_rand_gen_ipoisson ≫
  • PHP Manual
  • Statistic 関数
  • Generates random integer between 1 and 2147483562

stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — Generates random integer between 1 and 2147483562

説明

stats_rand_gen_int(): int

Returns a random integer between 1 and 2147483562

パラメータ

この関数にはパラメータはありません。

戻り値

A random integer


Generates a single random deviate from a Poisson distribution

  • ≪ stats_rand_gen_int
  • stats_rand_gen_iuniform ≫
  • PHP Manual
  • Statistic 関数
  • Generates a single random deviate from a Poisson distribution

stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution

説明

stats_rand_gen_ipoisson(float $mu): int

Returns a random deviate from the Poisson distribution with parameter mu.

パラメータ

mu

The parameter of the Poisson distribution

戻り値

A random deviate


Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)

  • ≪ stats_rand_gen_ipoisson
  • stats_rand_gen_noncentral_chisquare ≫
  • PHP Manual
  • Statistic 関数
  • Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)

stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)

説明

stats_rand_gen_iuniform(int $low, int $high): int

Returns a random integer from the discrete uniform distribution between low (inclusive) and high (inclusive).

パラメータ

low

The lower bound

high

The upper bound

戻り値

A random integer


Generates a random deviate from the non-central chi-square distribution

  • ≪ stats_rand_gen_iuniform
  • stats_rand_gen_noncentral_f ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the non-central chi-square distribution

stats_rand_gen_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_chisquare — Generates a random deviate from the non-central chi-square distribution

説明

stats_rand_gen_noncentral_chisquare(float $df, float $xnonc): float

Returns a random deviate from the non-central chi-square distribution with degrees of freedom, df, and non-centrality parameter, xnonc.

パラメータ

df

The degrees of freedom

xnonc

The non-centrality parameter

戻り値

A random deviate


Generates a random deviate from the noncentral F distribution

  • ≪ stats_rand_gen_noncentral_chisquare
  • stats_rand_gen_noncentral_t ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random deviate from the noncentral F distribution

stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution

説明

stats_rand_gen_noncentral_f(float $dfn, float $dfd, float $xnonc): float

Returns a random deviate from the non-central F distribution where the degrees of freedoms are dfn (numerator) and dfd (denominator), and the non-centrality parameter is xnonc.

パラメータ

dfn

The degrees of freedom of the numerator

dfd

The degrees of freedom of the denominator

xnonc

The non-centrality parameter

戻り値

A random deviate


Generates a single random deviate from a non-central t-distribution

  • ≪ stats_rand_gen_noncentral_f
  • stats_rand_gen_normal ≫
  • PHP Manual
  • Statistic 関数
  • Generates a single random deviate from a non-central t-distribution

stats_rand_gen_noncentral_t

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_t — Generates a single random deviate from a non-central t-distribution

説明

stats_rand_gen_noncentral_t(float $df, float $xnonc): float

Returns a random deviate from the non-central t-distribution with the degrees of freedom, df, and the non-centrality parameter, xnonc.

パラメータ

df

The degrees of freedom

xnonc

The non-centrality parameter

戻り値

A random deviate


Generates a single random deviate from a normal distribution

  • ≪ stats_rand_gen_noncentral_t
  • stats_rand_gen_t ≫
  • PHP Manual
  • Statistic 関数
  • Generates a single random deviate from a normal distribution

stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — Generates a single random deviate from a normal distribution

説明

stats_rand_gen_normal(float $av, float $sd): float

Returns a random deviate from the normal distribution with mean, av, and standard deviation, sd.

パラメータ

av

The mean of the normal distribution

sd

The standard deviation of the normal distribution

戻り値

A random deviate


Generates a single random deviate from a t-distribution

  • ≪ stats_rand_gen_normal
  • stats_rand_get_seeds ≫
  • PHP Manual
  • Statistic 関数
  • Generates a single random deviate from a t-distribution

stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — Generates a single random deviate from a t-distribution

説明

stats_rand_gen_t(float $df): float

Returns a random deviate from the t-distribution with the degrees of freedom, df.

パラメータ

df

The degrees of freedom

戻り値

A random deviate


Get the seed values of the random number generator

  • ≪ stats_rand_gen_t
  • stats_rand_phrase_to_seeds ≫
  • PHP Manual
  • Statistic 関数
  • Get the seed values of the random number generator

stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — Get the seed values of the random number generator

説明

stats_rand_get_seeds(): array

Returns the current seed values of the random number generator

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of two integers.


Generate two seeds for the RGN random number generator

  • ≪ stats_rand_get_seeds
  • stats_rand_ranf ≫
  • PHP Manual
  • Statistic 関数
  • Generate two seeds for the RGN random number generator

stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator

説明

stats_rand_phrase_to_seeds(string $phrase): array

Generate two seeds for the random number generator from a phrase.

パラメータ

phrase

The input phrase

戻り値

Returns an array of two integers.


Generates a random floating point number between 0 and 1

  • ≪ stats_rand_phrase_to_seeds
  • stats_rand_setall ≫
  • PHP Manual
  • Statistic 関数
  • Generates a random floating point number between 0 and 1

stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — Generates a random floating point number between 0 and 1

説明

stats_rand_ranf(): float

Returns a random floating point number from a uniform distribution between 0 (exclusive) and 1 (exclusive).

パラメータ

この関数にはパラメータはありません。

戻り値

A random floating point number


Set seed values to the random generator

  • ≪ stats_rand_ranf
  • stats_skew ≫
  • PHP Manual
  • Statistic 関数
  • Set seed values to the random generator

stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Set seed values to the random generator

説明

stats_rand_setall(int $iseed1, int $iseed2): void

Set iseed1 and iseed2 as seed values to the random generator used in statistic functions.

パラメータ

iseed1

The value which is used as the random seed

iseed2

The value which is used as the random seed

戻り値

No values are returned.


Computes the skewness of the data in the array

  • ≪ stats_rand_setall
  • stats_standard_deviation ≫
  • PHP Manual
  • Statistic 関数
  • Computes the skewness of the data in the array

stats_skew

(PECL stats >= 1.0.0)

stats_skew — Computes the skewness of the data in the array

説明

stats_skew(array $a): float

Returns the skewness of the values in a.

パラメータ

a

The input array

戻り値

Returns the skewness of the values in a, or false if a is empty or is not an array.


Returns the standard deviation

  • ≪ stats_skew
  • stats_stat_binomial_coef ≫
  • PHP Manual
  • Statistic 関数
  • Returns the standard deviation

stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — Returns the standard deviation

説明

stats_standard_deviation(array $a, bool $sample = false): float

Returns the standard deviation of the values in a.

パラメータ

a

The array of data to find the standard deviation for. Note that all values of the array will be cast to float.

sample

Indicates if a represents a sample of the population; defaults to false.

戻り値

Returns the standard deviation on success; false on failure.

エラー / 例外

Raises an E_WARNING when there are fewer than 2 values in a.


Returns a binomial coefficient

  • ≪ stats_standard_deviation
  • stats_stat_correlation ≫
  • PHP Manual
  • Statistic 関数
  • Returns a binomial coefficient

stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — Returns a binomial coefficient

説明

stats_stat_binomial_coef(int $x, int $n): float

Returns the binomial coefficient of n choose x.

パラメータ

x

The number of chooses from the set

n

The number of elements in the set

戻り値

Returns the binomial coefficient


Returns the Pearson correlation coefficient of two data sets

  • ≪ stats_stat_binomial_coef
  • stats_stat_factorial ≫
  • PHP Manual
  • Statistic 関数
  • Returns the Pearson correlation coefficient of two data sets

stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets

説明

stats_stat_correlation(array $arr1, array $arr2): float

Returns the Pearson correlation coefficient between arr1 and arr2.

パラメータ

arr1

The first array

arr2

The second array

戻り値

Returns the Pearson correlation coefficient between arr1 and arr2, or false on failure.


Returns the factorial of an integer

  • ≪ stats_stat_correlation
  • stats_stat_independent_t ≫
  • PHP Manual
  • Statistic 関数
  • Returns the factorial of an integer

stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — Returns the factorial of an integer

説明

stats_stat_factorial(int $n): float

Returns the factorial of an integer, n.

パラメータ

n

An integer

戻り値

The factorial of n.


Returns the t-value from the independent two-sample t-test

  • ≪ stats_stat_factorial
  • stats_stat_innerproduct ≫
  • PHP Manual
  • Statistic 関数
  • Returns the t-value from the independent two-sample t-test

stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — Returns the t-value from the independent two-sample t-test

説明

stats_stat_independent_t(array $arr1, array $arr2): float

Returns the t-value of the independent two-sample t-test between arr1 and arr2.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

arr1

The first set of values

arr2

The second set of values

戻り値

Returns the t-value, or false if failure.


Returns the inner product of two vectors

  • ≪ stats_stat_independent_t
  • stats_stat_paired_t ≫
  • PHP Manual
  • Statistic 関数
  • Returns the inner product of two vectors

stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — Returns the inner product of two vectors

説明

stats_stat_innerproduct(array $arr1, array $arr2): float

Returns the inner product of arr1 and arr2.

パラメータ

arr1

The first array

arr2

The second array

戻り値

Returns the inner product of arr1 and arr2, or false on failure.


Returns the t-value of the dependent t-test for paired samples

  • ≪ stats_stat_innerproduct
  • stats_stat_percentile ≫
  • PHP Manual
  • Statistic 関数
  • Returns the t-value of the dependent t-test for paired samples

stats_stat_paired_t

(PECL stats >= 1.0.0)

stats_stat_paired_t — Returns the t-value of the dependent t-test for paired samples

説明

stats_stat_paired_t(array $arr1, array $arr2): float

Returns the t-value of the dependent t-test for paired samples arr1 and arr2.

パラメータ

arr1

The first samples

arr2

The second samples

戻り値

Returns the t-value, or false if failure.


Returns the percentile value

  • ≪ stats_stat_paired_t
  • stats_stat_powersum ≫
  • PHP Manual
  • Statistic 関数
  • Returns the percentile value

stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Returns the percentile value

説明

stats_stat_percentile(array $arr, float $perc): float

Returns the perc-th percentile value of the array arr.

パラメータ

arr

The input array

perc

The percentile

戻り値

Returns the percentile values of the input array.


Returns the power sum of a vector

  • ≪ stats_stat_percentile
  • stats_variance ≫
  • PHP Manual
  • Statistic 関数
  • Returns the power sum of a vector

stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — Returns the power sum of a vector

説明

stats_stat_powersum(array $arr, float $power): float

Returns the sum of the power-th power of a vector represented as an array arr.

パラメータ

arr

The input array

power

The power

戻り値

Returns the power sum of the input array.


Returns the variance

  • ≪ stats_stat_powersum
  • Trader ≫
  • PHP Manual
  • Statistic 関数
  • Returns the variance

stats_variance

(PECL stats >= 1.0.0)

stats_variance — Returns the variance

説明

stats_variance(array $a, bool $sample = false): float

Returns the variance of the values in a.

パラメータ

a

The array of data to find the standard deviation for. Note that all values of the array will be cast to float.

sample

Indicates if a represents a sample of the population; defaults to false.

戻り値

Returns the variance on success; false on failure.


Technical Analysis for Traders

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Trader 関数
    • trader_acos — Vector Trigonometric ACos
    • trader_ad — Chaikin A/D Line
    • trader_add — Vector Arithmetic Add
    • trader_adosc — Chaikin A/D Oscillator
    • trader_adx — Average Directional Movement Index
    • trader_adxr — Average Directional Movement Index Rating
    • trader_apo — Absolute Price Oscillator
    • trader_aroon — Aroon
    • trader_aroonosc — Aroon Oscillator
    • trader_asin — Vector Trigonometric ASin
    • trader_atan — Vector Trigonometric ATan
    • trader_atr — Average True Range
    • trader_avgprice — Average Price
    • trader_bbands — Bollinger Bands
    • trader_beta — Beta
    • trader_bop — Balance Of Power
    • trader_cci — Commodity Channel Index
    • trader_cdl2crows — Two Crows
    • trader_cdl3blackcrows — Three Black Crows
    • trader_cdl3inside — Three Inside Up/Down
    • trader_cdl3linestrike — Three-Line Strike
    • trader_cdl3outside — Three Outside Up/Down
    • trader_cdl3starsinsouth — Three Stars In The South
    • trader_cdl3whitesoldiers — Three Advancing White Soldiers
    • trader_cdlabandonedbaby — Abandoned Baby
    • trader_cdladvanceblock — Advance Block
    • trader_cdlbelthold — Belt-hold
    • trader_cdlbreakaway — Breakaway
    • trader_cdlclosingmarubozu — Closing Marubozu
    • trader_cdlconcealbabyswall — Concealing Baby Swallow
    • trader_cdlcounterattack — Counterattack
    • trader_cdldarkcloudcover — Dark Cloud Cover
    • trader_cdldoji — Doji
    • trader_cdldojistar — Doji Star
    • trader_cdldragonflydoji — Dragonfly Doji
    • trader_cdlengulfing — Engulfing Pattern
    • trader_cdleveningdojistar — Evening Doji Star
    • trader_cdleveningstar — Evening Star
    • trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
    • trader_cdlgravestonedoji — Gravestone Doji
    • trader_cdlhammer — Hammer
    • trader_cdlhangingman — Hanging Man
    • trader_cdlharami — Harami Pattern
    • trader_cdlharamicross — Harami Cross Pattern
    • trader_cdlhighwave — High-Wave Candle
    • trader_cdlhikkake — Hikkake Pattern
    • trader_cdlhikkakemod — Modified Hikkake Pattern
    • trader_cdlhomingpigeon — Homing Pigeon
    • trader_cdlidentical3crows — Identical Three Crows
    • trader_cdlinneck — In-Neck Pattern
    • trader_cdlinvertedhammer — Inverted Hammer
    • trader_cdlkicking — Kicking
    • trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu
    • trader_cdlladderbottom — Ladder Bottom
    • trader_cdllongleggeddoji — Long Legged Doji
    • trader_cdllongline — Long Line Candle
    • trader_cdlmarubozu — Marubozu
    • trader_cdlmatchinglow — Matching Low
    • trader_cdlmathold — Mat Hold
    • trader_cdlmorningdojistar — Morning Doji Star
    • trader_cdlmorningstar — Morning Star
    • trader_cdlonneck — On-Neck Pattern
    • trader_cdlpiercing — Piercing Pattern
    • trader_cdlrickshawman — Rickshaw Man
    • trader_cdlrisefall3methods — Rising/Falling Three Methods
    • trader_cdlseparatinglines — Separating Lines
    • trader_cdlshootingstar — Shooting Star
    • trader_cdlshortline — Short Line Candle
    • trader_cdlspinningtop — Spinning Top
    • trader_cdlstalledpattern — Stalled Pattern
    • trader_cdlsticksandwich — Stick Sandwich
    • trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)
    • trader_cdltasukigap — Tasuki Gap
    • trader_cdlthrusting — Thrusting Pattern
    • trader_cdltristar — Tristar Pattern
    • trader_cdlunique3river — Unique 3 River
    • trader_cdlupsidegap2crows — Upside Gap Two Crows
    • trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods
    • trader_ceil — Vector Ceil
    • trader_cmo — Chande Momentum Oscillator
    • trader_correl — Pearson's Correlation Coefficient (r)
    • trader_cos — Vector Trigonometric Cos
    • trader_cosh — Vector Trigonometric Cosh
    • trader_dema — Double Exponential Moving Average
    • trader_div — Vector Arithmetic Div
    • trader_dx — Directional Movement Index
    • trader_ema — Exponential Moving Average
    • trader_errno — Get error code
    • trader_exp — Vector Arithmetic Exp
    • trader_floor — Vector Floor
    • trader_get_compat — Get compatibility mode
    • trader_get_unstable_period — Get unstable period
    • trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period
    • trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase
    • trader_ht_phasor — Hilbert Transform - Phasor Components
    • trader_ht_sine — Hilbert Transform - SineWave
    • trader_ht_trendline — Hilbert Transform - Instantaneous Trendline
    • trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode
    • trader_kama — Kaufman Adaptive Moving Average
    • trader_linearreg — Linear Regression
    • trader_linearreg_angle — Linear Regression Angle
    • trader_linearreg_intercept — Linear Regression Intercept
    • trader_linearreg_slope — Linear Regression Slope
    • trader_ln — Vector Log Natural
    • trader_log10 — Vector Log10
    • trader_ma — Moving average
    • trader_macd — Moving Average Convergence/Divergence
    • trader_macdext — MACD with controllable MA type
    • trader_macdfix — Moving Average Convergence/Divergence Fix 12/26
    • trader_mama — MESA Adaptive Moving Average
    • trader_mavp — Moving average with variable period
    • trader_max — Highest value over a specified period
    • trader_maxindex — Index of highest value over a specified period
    • trader_medprice — Median Price
    • trader_mfi — Money Flow Index
    • trader_midpoint — MidPoint over period
    • trader_midprice — Midpoint Price over period
    • trader_min — Lowest value over a specified period
    • trader_minindex — Index of lowest value over a specified period
    • trader_minmax — Lowest and highest values over a specified period
    • trader_minmaxindex — Indexes of lowest and highest values over a specified period
    • trader_minus_di — Minus Directional Indicator
    • trader_minus_dm — Minus Directional Movement
    • trader_mom — Momentum
    • trader_mult — Vector Arithmetic Mult
    • trader_natr — Normalized Average True Range
    • trader_obv — On Balance Volume
    • trader_plus_di — Plus Directional Indicator
    • trader_plus_dm — Plus Directional Movement
    • trader_ppo — Percentage Price Oscillator
    • trader_roc — Rate of change : ((price/prevPrice)-1)*100
    • trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice
    • trader_rocr — Rate of change ratio: (price/prevPrice)
    • trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100
    • trader_rsi — Relative Strength Index
    • trader_sar — Parabolic SAR
    • trader_sarext — Parabolic SAR - Extended
    • trader_set_compat — Set compatibility mode
    • trader_set_unstable_period — Set unstable period
    • trader_sin — Vector Trigonometric Sin
    • trader_sinh — Vector Trigonometric Sinh
    • trader_sma — Simple Moving Average
    • trader_sqrt — Vector Square Root
    • trader_stddev — Standard Deviation
    • trader_stoch — Stochastic
    • trader_stochf — Stochastic Fast
    • trader_stochrsi — Stochastic Relative Strength Index
    • trader_sub — Vector Arithmetic Subtraction
    • trader_sum — Summation
    • trader_t3 — Triple Exponential Moving Average (T3)
    • trader_tan — Vector Trigonometric Tan
    • trader_tanh — Vector Trigonometric Tanh
    • trader_tema — Triple Exponential Moving Average
    • trader_trange — True Range
    • trader_trima — Triangular Moving Average
    • trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
    • trader_tsf — Time Series Forecast
    • trader_typprice — Typical Price
    • trader_ultosc — Ultimate Oscillator
    • trader_var — Variance
    • trader_wclprice — Weighted Close Price
    • trader_willr — Williams' %R
    • trader_wma — Weighted Moving Average


はじめに

The trader extension is a free open source stock library based on TA-Lib. It's dedicated to trading software developers requiring to perform technical analysis of financial market data. Alongside many indicators like ADX, MACD, RSI, Stochastic, TRIX the candlestick pattern recognition and several vector arithmetic and algebraic functions are present.

Calculations can be done in two modes - TA-Lib and Metastock. Changing it using trader_set_compat() will affect the way some trader functions work.

Some trader functions provide different results depending of the "starting point" of the data being involved. This is often referred as a function having memories. An example of such function is the Exponential Moving Average. It is possible to control the unstable period (the amount of data to strip off) using trader_set_unstable_period() function.

Extended documentation about indicators, formulas and implementations in other programming languages can be found under » tadoc.org.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Trader
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

The trader extension is based on » TA-Lib. TA-Lib is fully integrated into the extension, therefore no external libraries are needed.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/trader.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/trader/.


実行時設定

php.ini の設定により動作が変化します。

Trader 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
trader.real_precision | 3 | INI_ALL | Since trader 0.2.1
trader.real_round_mode | HALF_DOWN | INI_ALL | Since trader 0.3.0

以下に設定ディレクティブに関する 簡単な説明を示します。

trader.real_precision int

All the values in the returned arrays will be rounded to this precision. However the calculations inside TA-Lib happen with unrounded values.

trader.real_round_mode string

Controls the trader real rounding policy. Valid values are HALF_UP, HALF_DOWN, HALF_EVEN and HALF_ODD. The behaviour is identical to the round() function used with the mode argument.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

TRADER_MA_TYPE_SMA (int)
TRADER_MA_TYPE_EMA (int)
TRADER_MA_TYPE_WMA (int)
TRADER_MA_TYPE_DEMA (int)
TRADER_MA_TYPE_TEMA (int)
TRADER_MA_TYPE_TRIMA (int)
TRADER_MA_TYPE_KAMA (int)
TRADER_MA_TYPE_MAMA (int)
TRADER_MA_TYPE_T3 (int)
TRADER_REAL_MIN (float)
TRADER_REAL_MAX (float)
TRADER_FUNC_UNST_ADX (int)
TRADER_FUNC_UNST_ADXR (int)
TRADER_FUNC_UNST_ATR (int)
TRADER_FUNC_UNST_CMO (int)
TRADER_FUNC_UNST_DX (int)
TRADER_FUNC_UNST_EMA (int)
TRADER_FUNC_UNST_HT_DCPERIOD (int)
TRADER_FUNC_UNST_HT_DCPHASE (int)
TRADER_FUNC_UNST_HT_PHASOR (int)
TRADER_FUNC_UNST_HT_SINE (int)
TRADER_FUNC_UNST_HT_TRENDLINE (int)
TRADER_FUNC_UNST_HT_TRENDMODE (int)
TRADER_FUNC_UNST_KAMA (int)
TRADER_FUNC_UNST_MAMA (int)
TRADER_FUNC_UNST_MFI (int)
TRADER_FUNC_UNST_MINUS_DI (int)
TRADER_FUNC_UNST_MINUS_DM (int)
TRADER_FUNC_UNST_NATR (int)
TRADER_FUNC_UNST_PLUS_DI (int)
TRADER_FUNC_UNST_PLUS_DM (int)
TRADER_FUNC_UNST_RSI (int)
TRADER_FUNC_UNST_STOCHRSI (int)
TRADER_FUNC_UNST_T3 (int)
TRADER_FUNC_UNST_ALL (int)
TRADER_FUNC_UNST_NONE (int)
TRADER_COMPATIBILITY_DEFAULT (int)
TRADER_COMPATIBILITY_METASTOCK (int)
TRADER_ERR_SUCCESS (int)
TRADER_ERR_LIB_NOT_INITIALIZE (int)
TRADER_ERR_BAD_PARAM (int)
TRADER_ERR_ALLOC_ERR (int)
TRADER_ERR_GROUP_NOT_FOUND (int)
TRADER_ERR_FUNC_NOT_FOUND (int)
TRADER_ERR_INVALID_HANDLE (int)
TRADER_ERR_INVALID_PARAM_HOLDER (int)
TRADER_ERR_INVALID_PARAM_HOLDER_TYPE (int)
TRADER_ERR_INVALID_PARAM_FUNCTION (int)
TRADER_ERR_INPUT_NOT_ALL_INITIALIZE (int)
TRADER_ERR_OUTPUT_NOT_ALL_INITIALIZE (int)
TRADER_ERR_OUT_OF_RANGE_START_INDEX (int)
TRADER_ERR_OUT_OF_RANGE_END_INDEX (int)
TRADER_ERR_INVALID_LIST_TYPE (int)
TRADER_ERR_BAD_OBJECT (int)
TRADER_ERR_NOT_SUPPORTED (int)
TRADER_ERR_INTERNAL_ERROR (int)
TRADER_ERR_UNKNOWN_ERROR (int)


Trader 関数

目次

  • trader_acos — Vector Trigonometric ACos
  • trader_ad — Chaikin A/D Line
  • trader_add — Vector Arithmetic Add
  • trader_adosc — Chaikin A/D Oscillator
  • trader_adx — Average Directional Movement Index
  • trader_adxr — Average Directional Movement Index Rating
  • trader_apo — Absolute Price Oscillator
  • trader_aroon — Aroon
  • trader_aroonosc — Aroon Oscillator
  • trader_asin — Vector Trigonometric ASin
  • trader_atan — Vector Trigonometric ATan
  • trader_atr — Average True Range
  • trader_avgprice — Average Price
  • trader_bbands — Bollinger Bands
  • trader_beta — Beta
  • trader_bop — Balance Of Power
  • trader_cci — Commodity Channel Index
  • trader_cdl2crows — Two Crows
  • trader_cdl3blackcrows — Three Black Crows
  • trader_cdl3inside — Three Inside Up/Down
  • trader_cdl3linestrike — Three-Line Strike
  • trader_cdl3outside — Three Outside Up/Down
  • trader_cdl3starsinsouth — Three Stars In The South
  • trader_cdl3whitesoldiers — Three Advancing White Soldiers
  • trader_cdlabandonedbaby — Abandoned Baby
  • trader_cdladvanceblock — Advance Block
  • trader_cdlbelthold — Belt-hold
  • trader_cdlbreakaway — Breakaway
  • trader_cdlclosingmarubozu — Closing Marubozu
  • trader_cdlconcealbabyswall — Concealing Baby Swallow
  • trader_cdlcounterattack — Counterattack
  • trader_cdldarkcloudcover — Dark Cloud Cover
  • trader_cdldoji — Doji
  • trader_cdldojistar — Doji Star
  • trader_cdldragonflydoji — Dragonfly Doji
  • trader_cdlengulfing — Engulfing Pattern
  • trader_cdleveningdojistar — Evening Doji Star
  • trader_cdleveningstar — Evening Star
  • trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
  • trader_cdlgravestonedoji — Gravestone Doji
  • trader_cdlhammer — Hammer
  • trader_cdlhangingman — Hanging Man
  • trader_cdlharami — Harami Pattern
  • trader_cdlharamicross — Harami Cross Pattern
  • trader_cdlhighwave — High-Wave Candle
  • trader_cdlhikkake — Hikkake Pattern
  • trader_cdlhikkakemod — Modified Hikkake Pattern
  • trader_cdlhomingpigeon — Homing Pigeon
  • trader_cdlidentical3crows — Identical Three Crows
  • trader_cdlinneck — In-Neck Pattern
  • trader_cdlinvertedhammer — Inverted Hammer
  • trader_cdlkicking — Kicking
  • trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu
  • trader_cdlladderbottom — Ladder Bottom
  • trader_cdllongleggeddoji — Long Legged Doji
  • trader_cdllongline — Long Line Candle
  • trader_cdlmarubozu — Marubozu
  • trader_cdlmatchinglow — Matching Low
  • trader_cdlmathold — Mat Hold
  • trader_cdlmorningdojistar — Morning Doji Star
  • trader_cdlmorningstar — Morning Star
  • trader_cdlonneck — On-Neck Pattern
  • trader_cdlpiercing — Piercing Pattern
  • trader_cdlrickshawman — Rickshaw Man
  • trader_cdlrisefall3methods — Rising/Falling Three Methods
  • trader_cdlseparatinglines — Separating Lines
  • trader_cdlshootingstar — Shooting Star
  • trader_cdlshortline — Short Line Candle
  • trader_cdlspinningtop — Spinning Top
  • trader_cdlstalledpattern — Stalled Pattern
  • trader_cdlsticksandwich — Stick Sandwich
  • trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)
  • trader_cdltasukigap — Tasuki Gap
  • trader_cdlthrusting — Thrusting Pattern
  • trader_cdltristar — Tristar Pattern
  • trader_cdlunique3river — Unique 3 River
  • trader_cdlupsidegap2crows — Upside Gap Two Crows
  • trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods
  • trader_ceil — Vector Ceil
  • trader_cmo — Chande Momentum Oscillator
  • trader_correl — Pearson's Correlation Coefficient (r)
  • trader_cos — Vector Trigonometric Cos
  • trader_cosh — Vector Trigonometric Cosh
  • trader_dema — Double Exponential Moving Average
  • trader_div — Vector Arithmetic Div
  • trader_dx — Directional Movement Index
  • trader_ema — Exponential Moving Average
  • trader_errno — Get error code
  • trader_exp — Vector Arithmetic Exp
  • trader_floor — Vector Floor
  • trader_get_compat — Get compatibility mode
  • trader_get_unstable_period — Get unstable period
  • trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period
  • trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase
  • trader_ht_phasor — Hilbert Transform - Phasor Components
  • trader_ht_sine — Hilbert Transform - SineWave
  • trader_ht_trendline — Hilbert Transform - Instantaneous Trendline
  • trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode
  • trader_kama — Kaufman Adaptive Moving Average
  • trader_linearreg — Linear Regression
  • trader_linearreg_angle — Linear Regression Angle
  • trader_linearreg_intercept — Linear Regression Intercept
  • trader_linearreg_slope — Linear Regression Slope
  • trader_ln — Vector Log Natural
  • trader_log10 — Vector Log10
  • trader_ma — Moving average
  • trader_macd — Moving Average Convergence/Divergence
  • trader_macdext — MACD with controllable MA type
  • trader_macdfix — Moving Average Convergence/Divergence Fix 12/26
  • trader_mama — MESA Adaptive Moving Average
  • trader_mavp — Moving average with variable period
  • trader_max — Highest value over a specified period
  • trader_maxindex — Index of highest value over a specified period
  • trader_medprice — Median Price
  • trader_mfi — Money Flow Index
  • trader_midpoint — MidPoint over period
  • trader_midprice — Midpoint Price over period
  • trader_min — Lowest value over a specified period
  • trader_minindex — Index of lowest value over a specified period
  • trader_minmax — Lowest and highest values over a specified period
  • trader_minmaxindex — Indexes of lowest and highest values over a specified period
  • trader_minus_di — Minus Directional Indicator
  • trader_minus_dm — Minus Directional Movement
  • trader_mom — Momentum
  • trader_mult — Vector Arithmetic Mult
  • trader_natr — Normalized Average True Range
  • trader_obv — On Balance Volume
  • trader_plus_di — Plus Directional Indicator
  • trader_plus_dm — Plus Directional Movement
  • trader_ppo — Percentage Price Oscillator
  • trader_roc — Rate of change : ((price/prevPrice)-1)*100
  • trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice
  • trader_rocr — Rate of change ratio: (price/prevPrice)
  • trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100
  • trader_rsi — Relative Strength Index
  • trader_sar — Parabolic SAR
  • trader_sarext — Parabolic SAR - Extended
  • trader_set_compat — Set compatibility mode
  • trader_set_unstable_period — Set unstable period
  • trader_sin — Vector Trigonometric Sin
  • trader_sinh — Vector Trigonometric Sinh
  • trader_sma — Simple Moving Average
  • trader_sqrt — Vector Square Root
  • trader_stddev — Standard Deviation
  • trader_stoch — Stochastic
  • trader_stochf — Stochastic Fast
  • trader_stochrsi — Stochastic Relative Strength Index
  • trader_sub — Vector Arithmetic Subtraction
  • trader_sum — Summation
  • trader_t3 — Triple Exponential Moving Average (T3)
  • trader_tan — Vector Trigonometric Tan
  • trader_tanh — Vector Trigonometric Tanh
  • trader_tema — Triple Exponential Moving Average
  • trader_trange — True Range
  • trader_trima — Triangular Moving Average
  • trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
  • trader_tsf — Time Series Forecast
  • trader_typprice — Typical Price
  • trader_ultosc — Ultimate Oscillator
  • trader_var — Variance
  • trader_wclprice — Weighted Close Price
  • trader_willr — Williams' %R
  • trader_wma — Weighted Moving Average


Vector Trigonometric ACos

  • ≪ Trader 関数
  • trader_ad ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric ACos

trader_acos

(PECL trader >= 0.2.0)

trader_acos — Vector Trigonometric ACos

説明

trader_acos(array $real): array

Calculates the arc cosine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Chaikin A/D Line

  • ≪ trader_acos
  • trader_add ≫
  • PHP Manual
  • Trader 関数
  • Chaikin A/D Line

trader_ad

(PECL trader >= 0.2.0)

trader_ad — Chaikin A/D Line

説明

trader_ad(
array $high,
array $low,
array $close,
array $volume
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

volume

取引高。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Arithmetic Add

  • ≪ trader_ad
  • trader_adosc ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Add

trader_add

(PECL trader >= 0.2.0)

trader_add — Vector Arithmetic Add

説明

trader_add(array $real0, array $real1): array

Calculates the vector addition of real0 to real1 and returns the resulting vector.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Chaikin A/D Oscillator

  • ≪ trader_add
  • trader_adx ≫
  • PHP Manual
  • Trader 関数
  • Chaikin A/D Oscillator

trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Chaikin A/D Oscillator

説明

trader_adosc(
array $high,
array $low,
array $close,
array $volume,
int $fastPeriod = ?,
int $slowPeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

volume

取引高。実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Average Directional Movement Index

  • ≪ trader_adosc
  • trader_adxr ≫
  • PHP Manual
  • Trader 関数
  • Average Directional Movement Index

trader_adx

(PECL trader >= 0.2.0)

trader_adx — Average Directional Movement Index

説明

trader_adx(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Average Directional Movement Index Rating

  • ≪ trader_adx
  • trader_apo ≫
  • PHP Manual
  • Trader 関数
  • Average Directional Movement Index Rating

trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Average Directional Movement Index Rating

説明

trader_adxr(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Absolute Price Oscillator

  • ≪ trader_adxr
  • trader_aroon ≫
  • PHP Manual
  • Trader 関数
  • Absolute Price Oscillator

trader_apo

(PECL trader >= 0.2.0)

trader_apo — Absolute Price Oscillator

説明

trader_apo(
array $real,
int $fastPeriod = ?,
int $slowPeriod = ?,
int $mAType = ?
): array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Aroon

  • ≪ trader_apo
  • trader_aroonosc ≫
  • PHP Manual
  • Trader 関数
  • Aroon

trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

説明

trader_aroon(array $high, array $low, int $timePeriod = ?): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Aroon Oscillator

  • ≪ trader_aroon
  • trader_asin ≫
  • PHP Manual
  • Trader 関数
  • Aroon Oscillator

trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Aroon Oscillator

説明

trader_aroonosc(array $high, array $low, int $timePeriod = ?): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric ASin

  • ≪ trader_aroonosc
  • trader_atan ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric ASin

trader_asin

(PECL trader >= 0.2.0)

trader_asin — Vector Trigonometric ASin

説明

trader_asin(array $real): array

Calculates the arc sine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric ATan

  • ≪ trader_asin
  • trader_atr ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric ATan

trader_atan

(PECL trader >= 0.2.0)

trader_atan — Vector Trigonometric ATan

説明

trader_atan(array $real): array

Calculates the arc tangent for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Average True Range

  • ≪ trader_atan
  • trader_avgprice ≫
  • PHP Manual
  • Trader 関数
  • Average True Range

trader_atr

(PECL trader >= 0.2.0)

trader_atr — Average True Range

説明

trader_atr(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Average Price

  • ≪ trader_atr
  • trader_bbands ≫
  • PHP Manual
  • Trader 関数
  • Average Price

trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Average Price

説明

trader_avgprice(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Bollinger Bands

  • ≪ trader_avgprice
  • trader_beta ≫
  • PHP Manual
  • Trader 関数
  • Bollinger Bands

trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bollinger Bands

説明

trader_bbands(
array $real,
int $timePeriod = ?,
float $nbDevUp = ?,
float $nbDevDn = ?,
int $mAType = ?
): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

nbDevUp

Deviation multiplier for upper band. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

nbDevDn

Deviation multiplier for lower band. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Beta

  • ≪ trader_bbands
  • trader_bop ≫
  • PHP Manual
  • Trader 関数
  • Beta

trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

説明

trader_beta(array $real0, array $real1, int $timePeriod = ?): array

パラメータ

real0

実数値の配列。

real1

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Balance Of Power

  • ≪ trader_beta
  • trader_cci ≫
  • PHP Manual
  • Trader 関数
  • Balance Of Power

trader_bop

(PECL trader >= 0.2.0)

trader_bop — Balance Of Power

説明

trader_bop(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Commodity Channel Index

  • ≪ trader_bop
  • trader_cdl2crows ≫
  • PHP Manual
  • Trader 関数
  • Commodity Channel Index

trader_cci

(PECL trader >= 0.2.0)

trader_cci — Commodity Channel Index

説明

trader_cci(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Two Crows

  • ≪ trader_cci
  • trader_cdl3blackcrows ≫
  • PHP Manual
  • Trader 関数
  • Two Crows

trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Two Crows

説明

trader_cdl2crows(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Three Black Crows

  • ≪ trader_cdl2crows
  • trader_cdl3inside ≫
  • PHP Manual
  • Trader 関数
  • Three Black Crows

trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Three Black Crows

説明

trader_cdl3blackcrows(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Three Inside Up/Down

  • ≪ trader_cdl3blackcrows
  • trader_cdl3linestrike ≫
  • PHP Manual
  • Trader 関数
  • Three Inside Up/Down

trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Three Inside Up/Down

説明

trader_cdl3inside(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Three-Line Strike

  • ≪ trader_cdl3inside
  • trader_cdl3outside ≫
  • PHP Manual
  • Trader 関数
  • Three-Line Strike

trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Three-Line Strike

説明

trader_cdl3linestrike(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Three Outside Up/Down

  • ≪ trader_cdl3linestrike
  • trader_cdl3starsinsouth ≫
  • PHP Manual
  • Trader 関数
  • Three Outside Up/Down

trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Three Outside Up/Down

説明

trader_cdl3outside(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Three Stars In The South

  • ≪ trader_cdl3outside
  • trader_cdl3whitesoldiers ≫
  • PHP Manual
  • Trader 関数
  • Three Stars In The South

trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Three Stars In The South

説明

trader_cdl3starsinsouth(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Three Advancing White Soldiers

  • ≪ trader_cdl3starsinsouth
  • trader_cdlabandonedbaby ≫
  • PHP Manual
  • Trader 関数
  • Three Advancing White Soldiers

trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Three Advancing White Soldiers

説明

trader_cdl3whitesoldiers(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Abandoned Baby

  • ≪ trader_cdl3whitesoldiers
  • trader_cdladvanceblock ≫
  • PHP Manual
  • Trader 関数
  • Abandoned Baby

trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Abandoned Baby

説明

trader_cdlabandonedbaby(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


Advance Block

  • ≪ trader_cdlabandonedbaby
  • trader_cdlbelthold ≫
  • PHP Manual
  • Trader 関数
  • Advance Block

trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Advance Block

説明

trader_cdladvanceblock(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Belt-hold

  • ≪ trader_cdladvanceblock
  • trader_cdlbreakaway ≫
  • PHP Manual
  • Trader 関数
  • Belt-hold

trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

説明

trader_cdlbelthold(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Breakaway

  • ≪ trader_cdlbelthold
  • trader_cdlclosingmarubozu ≫
  • PHP Manual
  • Trader 関数
  • Breakaway

trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Breakaway

説明

trader_cdlbreakaway(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Closing Marubozu

  • ≪ trader_cdlbreakaway
  • trader_cdlconcealbabyswall ≫
  • PHP Manual
  • Trader 関数
  • Closing Marubozu

trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Closing Marubozu

説明

trader_cdlclosingmarubozu(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Concealing Baby Swallow

  • ≪ trader_cdlclosingmarubozu
  • trader_cdlcounterattack ≫
  • PHP Manual
  • Trader 関数
  • Concealing Baby Swallow

trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Concealing Baby Swallow

説明

trader_cdlconcealbabyswall(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Counterattack

  • ≪ trader_cdlconcealbabyswall
  • trader_cdldarkcloudcover ≫
  • PHP Manual
  • Trader 関数
  • Counterattack

trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Counterattack

説明

trader_cdlcounterattack(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Dark Cloud Cover

  • ≪ trader_cdlcounterattack
  • trader_cdldoji ≫
  • PHP Manual
  • Trader 関数
  • Dark Cloud Cover

trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Dark Cloud Cover

説明

trader_cdldarkcloudcover(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


Doji

  • ≪ trader_cdldarkcloudcover
  • trader_cdldojistar ≫
  • PHP Manual
  • Trader 関数
  • Doji

trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

説明

trader_cdldoji(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Doji Star

  • ≪ trader_cdldoji
  • trader_cdldragonflydoji ≫
  • PHP Manual
  • Trader 関数
  • Doji Star

trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Star

説明

trader_cdldojistar(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Dragonfly Doji

  • ≪ trader_cdldojistar
  • trader_cdlengulfing ≫
  • PHP Manual
  • Trader 関数
  • Dragonfly Doji

trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Dragonfly Doji

説明

trader_cdldragonflydoji(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Engulfing Pattern

  • ≪ trader_cdldragonflydoji
  • trader_cdleveningdojistar ≫
  • PHP Manual
  • Trader 関数
  • Engulfing Pattern

trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Engulfing Pattern

説明

trader_cdlengulfing(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Evening Doji Star

  • ≪ trader_cdlengulfing
  • trader_cdleveningstar ≫
  • PHP Manual
  • Trader 関数
  • Evening Doji Star

trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Evening Doji Star

説明

trader_cdleveningdojistar(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


Evening Star

  • ≪ trader_cdleveningdojistar
  • trader_cdlgapsidesidewhite ≫
  • PHP Manual
  • Trader 関数
  • Evening Star

trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Evening Star

説明

trader_cdleveningstar(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


Up/Down-gap side-by-side white lines

  • ≪ trader_cdleveningstar
  • trader_cdlgravestonedoji ≫
  • PHP Manual
  • Trader 関数
  • Up/Down-gap side-by-side white lines

trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines

説明

trader_cdlgapsidesidewhite(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Gravestone Doji

  • ≪ trader_cdlgapsidesidewhite
  • trader_cdlhammer ≫
  • PHP Manual
  • Trader 関数
  • Gravestone Doji

trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Gravestone Doji

説明

trader_cdlgravestonedoji(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hammer

  • ≪ trader_cdlgravestonedoji
  • trader_cdlhangingman ≫
  • PHP Manual
  • Trader 関数
  • Hammer

trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Hammer

説明

trader_cdlhammer(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hanging Man

  • ≪ trader_cdlhammer
  • trader_cdlharami ≫
  • PHP Manual
  • Trader 関数
  • Hanging Man

trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hanging Man

説明

trader_cdlhangingman(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Harami Pattern

  • ≪ trader_cdlhangingman
  • trader_cdlharamicross ≫
  • PHP Manual
  • Trader 関数
  • Harami Pattern

trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami Pattern

説明

trader_cdlharami(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Harami Cross Pattern

  • ≪ trader_cdlharami
  • trader_cdlhighwave ≫
  • PHP Manual
  • Trader 関数
  • Harami Cross Pattern

trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Harami Cross Pattern

説明

trader_cdlharamicross(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


High-Wave Candle

  • ≪ trader_cdlharamicross
  • trader_cdlhikkake ≫
  • PHP Manual
  • Trader 関数
  • High-Wave Candle

trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — High-Wave Candle

説明

trader_cdlhighwave(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hikkake Pattern

  • ≪ trader_cdlhighwave
  • trader_cdlhikkakemod ≫
  • PHP Manual
  • Trader 関数
  • Hikkake Pattern

trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake Pattern

説明

trader_cdlhikkake(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Modified Hikkake Pattern

  • ≪ trader_cdlhikkake
  • trader_cdlhomingpigeon ≫
  • PHP Manual
  • Trader 関数
  • Modified Hikkake Pattern

trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Modified Hikkake Pattern

説明

trader_cdlhikkakemod(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Homing Pigeon

  • ≪ trader_cdlhikkakemod
  • trader_cdlidentical3crows ≫
  • PHP Manual
  • Trader 関数
  • Homing Pigeon

trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Homing Pigeon

説明

trader_cdlhomingpigeon(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Identical Three Crows

  • ≪ trader_cdlhomingpigeon
  • trader_cdlinneck ≫
  • PHP Manual
  • Trader 関数
  • Identical Three Crows

trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Identical Three Crows

説明

trader_cdlidentical3crows(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


In-Neck Pattern

  • ≪ trader_cdlidentical3crows
  • trader_cdlinvertedhammer ≫
  • PHP Manual
  • Trader 関数
  • In-Neck Pattern

trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck Pattern

説明

trader_cdlinneck(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Inverted Hammer

  • ≪ trader_cdlinneck
  • trader_cdlkicking ≫
  • PHP Manual
  • Trader 関数
  • Inverted Hammer

trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Inverted Hammer

説明

trader_cdlinvertedhammer(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Kicking

  • ≪ trader_cdlinvertedhammer
  • trader_cdlkickingbylength ≫
  • PHP Manual
  • Trader 関数
  • Kicking

trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Kicking

説明

trader_cdlkicking(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Kicking - bull/bear determined by the longer marubozu

  • ≪ trader_cdlkicking
  • trader_cdlladderbottom ≫
  • PHP Manual
  • Trader 関数
  • Kicking - bull/bear determined by the longer marubozu

trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu

説明

trader_cdlkickingbylength(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Ladder Bottom

  • ≪ trader_cdlkickingbylength
  • trader_cdllongleggeddoji ≫
  • PHP Manual
  • Trader 関数
  • Ladder Bottom

trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Ladder Bottom

説明

trader_cdlladderbottom(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Long Legged Doji

  • ≪ trader_cdlladderbottom
  • trader_cdllongline ≫
  • PHP Manual
  • Trader 関数
  • Long Legged Doji

trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Long Legged Doji

説明

trader_cdllongleggeddoji(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Long Line Candle

  • ≪ trader_cdllongleggeddoji
  • trader_cdlmarubozu ≫
  • PHP Manual
  • Trader 関数
  • Long Line Candle

trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Long Line Candle

説明

trader_cdllongline(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Marubozu

  • ≪ trader_cdllongline
  • trader_cdlmatchinglow ≫
  • PHP Manual
  • Trader 関数
  • Marubozu

trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

説明

trader_cdlmarubozu(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Matching Low

  • ≪ trader_cdlmarubozu
  • trader_cdlmathold ≫
  • PHP Manual
  • Trader 関数
  • Matching Low

trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

説明

trader_cdlmatchinglow(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Mat Hold

  • ≪ trader_cdlmatchinglow
  • trader_cdlmorningdojistar ≫
  • PHP Manual
  • Trader 関数
  • Mat Hold

trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

説明

trader_cdlmathold(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


Morning Doji Star

  • ≪ trader_cdlmathold
  • trader_cdlmorningstar ≫
  • PHP Manual
  • Trader 関数
  • Morning Doji Star

trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Morning Doji Star

説明

trader_cdlmorningdojistar(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


Morning Star

  • ≪ trader_cdlmorningdojistar
  • trader_cdlonneck ≫
  • PHP Manual
  • Trader 関数
  • Morning Star

trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Morning Star

説明

trader_cdlmorningstar(
array $open,
array $high,
array $low,
array $close,
float $penetration = ?
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

penetration

Percentage of penetration of a candle within another candle.

戻り値

Returns an array with calculated data or false on failure.


On-Neck Pattern

  • ≪ trader_cdlmorningstar
  • trader_cdlpiercing ≫
  • PHP Manual
  • Trader 関数
  • On-Neck Pattern

trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck Pattern

説明

trader_cdlonneck(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Piercing Pattern

  • ≪ trader_cdlonneck
  • trader_cdlrickshawman ≫
  • PHP Manual
  • Trader 関数
  • Piercing Pattern

trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing Pattern

説明

trader_cdlpiercing(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Rickshaw Man

  • ≪ trader_cdlpiercing
  • trader_cdlrisefall3methods ≫
  • PHP Manual
  • Trader 関数
  • Rickshaw Man

trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Rickshaw Man

説明

trader_cdlrickshawman(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Rising/Falling Three Methods

  • ≪ trader_cdlrickshawman
  • trader_cdlseparatinglines ≫
  • PHP Manual
  • Trader 関数
  • Rising/Falling Three Methods

trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Rising/Falling Three Methods

説明

trader_cdlrisefall3methods(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Separating Lines

  • ≪ trader_cdlrisefall3methods
  • trader_cdlshootingstar ≫
  • PHP Manual
  • Trader 関数
  • Separating Lines

trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Separating Lines

説明

trader_cdlseparatinglines(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Shooting Star

  • ≪ trader_cdlseparatinglines
  • trader_cdlshortline ≫
  • PHP Manual
  • Trader 関数
  • Shooting Star

trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Shooting Star

説明

trader_cdlshootingstar(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Short Line Candle

  • ≪ trader_cdlshootingstar
  • trader_cdlspinningtop ≫
  • PHP Manual
  • Trader 関数
  • Short Line Candle

trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Short Line Candle

説明

trader_cdlshortline(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Spinning Top

  • ≪ trader_cdlshortline
  • trader_cdlstalledpattern ≫
  • PHP Manual
  • Trader 関数
  • Spinning Top

trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Spinning Top

説明

trader_cdlspinningtop(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Stalled Pattern

  • ≪ trader_cdlspinningtop
  • trader_cdlsticksandwich ≫
  • PHP Manual
  • Trader 関数
  • Stalled Pattern

trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Stalled Pattern

説明

trader_cdlstalledpattern(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Stick Sandwich

  • ≪ trader_cdlstalledpattern
  • trader_cdltakuri ≫
  • PHP Manual
  • Trader 関数
  • Stick Sandwich

trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Stick Sandwich

説明

trader_cdlsticksandwich(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Takuri (Dragonfly Doji with very long lower shadow)

  • ≪ trader_cdlsticksandwich
  • trader_cdltasukigap ≫
  • PHP Manual
  • Trader 関数
  • Takuri (Dragonfly Doji with very long lower shadow)

trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)

説明

trader_cdltakuri(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Tasuki Gap

  • ≪ trader_cdltakuri
  • trader_cdlthrusting ≫
  • PHP Manual
  • Trader 関数
  • Tasuki Gap

trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Tasuki Gap

説明

trader_cdltasukigap(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Thrusting Pattern

  • ≪ trader_cdltasukigap
  • trader_cdltristar ≫
  • PHP Manual
  • Trader 関数
  • Thrusting Pattern

trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting Pattern

説明

trader_cdlthrusting(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Tristar Pattern

  • ≪ trader_cdlthrusting
  • trader_cdlunique3river ≫
  • PHP Manual
  • Trader 関数
  • Tristar Pattern

trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tristar Pattern

説明

trader_cdltristar(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Unique 3 River

  • ≪ trader_cdltristar
  • trader_cdlupsidegap2crows ≫
  • PHP Manual
  • Trader 関数
  • Unique 3 River

trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

説明

trader_cdlunique3river(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Upside Gap Two Crows

  • ≪ trader_cdlunique3river
  • trader_cdlxsidegap3methods ≫
  • PHP Manual
  • Trader 関数
  • Upside Gap Two Crows

trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Upside Gap Two Crows

説明

trader_cdlupsidegap2crows(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Upside/Downside Gap Three Methods

  • ≪ trader_cdlupsidegap2crows
  • trader_ceil ≫
  • PHP Manual
  • Trader 関数
  • Upside/Downside Gap Three Methods

trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods

説明

trader_cdlxsidegap3methods(
array $open,
array $high,
array $low,
array $close
): array

パラメータ

open

始値。実数値の配列。

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Ceil

  • ≪ trader_cdlxsidegap3methods
  • trader_cmo ≫
  • PHP Manual
  • Trader 関数
  • Vector Ceil

trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Vector Ceil

説明

trader_ceil(array $real): array

Calculates the next highest integer for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Chande Momentum Oscillator

  • ≪ trader_ceil
  • trader_correl ≫
  • PHP Manual
  • Trader 関数
  • Chande Momentum Oscillator

trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Chande Momentum Oscillator

説明

trader_cmo(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Pearson's Correlation Coefficient (r)

  • ≪ trader_cmo
  • trader_cos ≫
  • PHP Manual
  • Trader 関数
  • Pearson's Correlation Coefficient (r)

trader_correl

(PECL trader >= 0.2.0)

trader_correl — Pearson's Correlation Coefficient (r)

説明

trader_correl(array $real0, array $real1, int $timePeriod = ?): array

パラメータ

real0

実数値の配列。

real1

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric Cos

  • ≪ trader_correl
  • trader_cosh ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Cos

trader_cos

(PECL trader >= 0.2.0)

trader_cos — Vector Trigonometric Cos

説明

trader_cos(array $real): array

Calculates the cosine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric Cosh

  • ≪ trader_cos
  • trader_dema ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Cosh

trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Vector Trigonometric Cosh

説明

trader_cosh(array $real): array

Calculates the hyperbolic cosine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Double Exponential Moving Average

  • ≪ trader_cosh
  • trader_div ≫
  • PHP Manual
  • Trader 関数
  • Double Exponential Moving Average

trader_dema

(PECL trader >= 0.2.0)

trader_dema — Double Exponential Moving Average

説明

trader_dema(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Vector Arithmetic Div

  • ≪ trader_dema
  • trader_dx ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Div

trader_div

(PECL trader >= 0.2.0)

trader_div — Vector Arithmetic Div

説明

trader_div(array $real0, array $real1): array

Divides each value from real0 by the corresponding value from real1 and returns the resulting array.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Directional Movement Index

  • ≪ trader_div
  • trader_ema ≫
  • PHP Manual
  • Trader 関数
  • Directional Movement Index

trader_dx

(PECL trader >= 0.2.0)

trader_dx — Directional Movement Index

説明

trader_dx(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Exponential Moving Average

  • ≪ trader_dx
  • trader_errno ≫
  • PHP Manual
  • Trader 関数
  • Exponential Moving Average

trader_ema

(PECL trader >= 0.2.0)

trader_ema — Exponential Moving Average

説明

trader_ema(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Get error code

  • ≪ trader_ema
  • trader_exp ≫
  • PHP Manual
  • Trader 関数
  • Get error code

trader_errno

(PECL trader >= 0.3.0)

trader_errno — Get error code

説明

trader_errno(): int

Get error code of the last operation.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the error code identified by one of the TRADER_ERR_* constants.


Vector Arithmetic Exp

  • ≪ trader_errno
  • trader_floor ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Exp

trader_exp

(PECL trader >= 0.2.0)

trader_exp — Vector Arithmetic Exp

説明

trader_exp(array $real): array

Calculates e raised to the power of each value in real. Returns an array with the calculated data.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Floor

  • ≪ trader_exp
  • trader_get_compat ≫
  • PHP Manual
  • Trader 関数
  • Vector Floor

trader_floor

(PECL trader >= 0.2.0)

trader_floor — Vector Floor

説明

trader_floor(array $real): array

Calculates the next lowest integer for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Get compatibility mode

  • ≪ trader_floor
  • trader_get_unstable_period ≫
  • PHP Manual
  • Trader 関数
  • Get compatibility mode

trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Get compatibility mode

説明

trader_get_compat(): int

Get compatibility mode which affects the way calculations are done by all the extension functions.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the compatibility mode id which can be identified by TRADER_COMPATIBILITY_* series of constants.


Get unstable period

  • ≪ trader_get_compat
  • trader_ht_dcperiod ≫
  • PHP Manual
  • Trader 関数
  • Get unstable period

trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Get unstable period

説明

trader_get_unstable_period(int $functionId): int

Get unstable period factor for a particular function.

パラメータ

functionId

Function ID the factor to be read for. TRADER_FUNC_UNST_* series of constants should be used.

戻り値

Returns the unstable period factor for the corresponding function.


Hilbert Transform - Dominant Cycle Period

  • ≪ trader_get_unstable_period
  • trader_ht_dcphase ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Dominant Cycle Period

trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period

説明

trader_ht_dcperiod(array $real): array

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hilbert Transform - Dominant Cycle Phase

  • ≪ trader_ht_dcperiod
  • trader_ht_phasor ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Dominant Cycle Phase

trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase

説明

trader_ht_dcphase(array $real): array

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hilbert Transform - Phasor Components

  • ≪ trader_ht_dcphase
  • trader_ht_sine ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Phasor Components

trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Hilbert Transform - Phasor Components

説明

trader_ht_phasor(array $real): array

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hilbert Transform - SineWave

  • ≪ trader_ht_phasor
  • trader_ht_trendline ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - SineWave

trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Hilbert Transform - SineWave

説明

trader_ht_sine(array $real): array

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hilbert Transform - Instantaneous Trendline

  • ≪ trader_ht_sine
  • trader_ht_trendmode ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Instantaneous Trendline

trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Hilbert Transform - Instantaneous Trendline

説明

trader_ht_trendline(array $real): array

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Hilbert Transform - Trend vs Cycle Mode

  • ≪ trader_ht_trendline
  • trader_kama ≫
  • PHP Manual
  • Trader 関数
  • Hilbert Transform - Trend vs Cycle Mode

trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode

説明

trader_ht_trendmode(array $real): array

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Kaufman Adaptive Moving Average

  • ≪ trader_ht_trendmode
  • trader_linearreg ≫
  • PHP Manual
  • Trader 関数
  • Kaufman Adaptive Moving Average

trader_kama

(PECL trader >= 0.2.0)

trader_kama — Kaufman Adaptive Moving Average

説明

trader_kama(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Linear Regression

  • ≪ trader_kama
  • trader_linearreg_angle ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression

trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Linear Regression

説明

trader_linearreg(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Linear Regression Angle

  • ≪ trader_linearreg
  • trader_linearreg_intercept ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression Angle

trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Linear Regression Angle

説明

trader_linearreg_angle(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Linear Regression Intercept

  • ≪ trader_linearreg_angle
  • trader_linearreg_slope ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression Intercept

trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Linear Regression Intercept

説明

trader_linearreg_intercept(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Linear Regression Slope

  • ≪ trader_linearreg_intercept
  • trader_ln ≫
  • PHP Manual
  • Trader 関数
  • Linear Regression Slope

trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Linear Regression Slope

説明

trader_linearreg_slope(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Vector Log Natural

  • ≪ trader_linearreg_slope
  • trader_log10 ≫
  • PHP Manual
  • Trader 関数
  • Vector Log Natural

trader_ln

(PECL trader >= 0.2.0)

trader_ln — Vector Log Natural

説明

trader_ln(array $real): array

Calculates the natural logarithm for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Log10

  • ≪ trader_ln
  • trader_ma ≫
  • PHP Manual
  • Trader 関数
  • Vector Log10

trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Vector Log10

説明

trader_log10(array $real): array

Calculates the base-10 logarithm for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Moving average

  • ≪ trader_log10
  • trader_macd ≫
  • PHP Manual
  • Trader 関数
  • Moving average

trader_ma

(PECL trader >= 0.2.0)

trader_ma — Moving average

説明

trader_ma(array $real, int $timePeriod = ?, int $mAType = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Moving Average Convergence/Divergence

  • ≪ trader_ma
  • trader_macdext ≫
  • PHP Manual
  • Trader 関数
  • Moving Average Convergence/Divergence

trader_macd

(PECL trader >= 0.2.0)

trader_macd — Moving Average Convergence/Divergence

説明

trader_macd(
array $real,
int $fastPeriod = ?,
int $slowPeriod = ?,
int $signalPeriod = ?
): array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

signalPeriod

Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

戻り値

Returns an array with calculated data or false on failure.


MACD with controllable MA type

  • ≪ trader_macd
  • trader_macdfix ≫
  • PHP Manual
  • Trader 関数
  • MACD with controllable MA type

trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD with controllable MA type

説明

trader_macdext(
array $real,
int $fastPeriod = ?,
int $fastMAType = ?,
int $slowPeriod = ?,
int $slowMAType = ?,
int $signalPeriod = ?,
int $signalMAType = ?
): array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

fastMAType

Type of Moving Average for fast MA. TRADER_MA_TYPE_* series of constants should be used.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

slowMAType

Type of Moving Average for slow MA. TRADER_MA_TYPE_* series of constants should be used.

signalPeriod

Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

signalMAType

Type of Moving Average for signal line. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Moving Average Convergence/Divergence Fix 12/26

  • ≪ trader_macdext
  • trader_mama ≫
  • PHP Manual
  • Trader 関数
  • Moving Average Convergence/Divergence Fix 12/26

trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Moving Average Convergence/Divergence Fix 12/26

説明

trader_macdfix(array $real, int $signalPeriod = ?): array

パラメータ

real

実数値の配列。

signalPeriod

Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

戻り値

Returns an array with calculated data or false on failure.


MESA Adaptive Moving Average

  • ≪ trader_macdfix
  • trader_mavp ≫
  • PHP Manual
  • Trader 関数
  • MESA Adaptive Moving Average

trader_mama

(PECL trader >= 0.2.0)

trader_mama — MESA Adaptive Moving Average

説明

trader_mama(array $real, float $fastLimit = ?, float $slowLimit = ?): array

パラメータ

real

実数値の配列。

fastLimit

Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.

slowLimit

Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.

戻り値

Returns an array with calculated data or false on failure.


Moving average with variable period

  • ≪ trader_mama
  • trader_max ≫
  • PHP Manual
  • Trader 関数
  • Moving average with variable period

trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Moving average with variable period

説明

trader_mavp(
array $real,
array $periods,
int $minPeriod = ?,
int $maxPeriod = ?,
int $mAType = ?
): array

パラメータ

real

実数値の配列。

periods

実数値の配列。

minPeriod

Value less than minimum will be changed to Minimum period. Valid range from 2 to 100000

maxPeriod

Value higher than minimum will be changed to Maximum period. Valid range from 2 to 100000

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Highest value over a specified period

  • ≪ trader_mavp
  • trader_maxindex ≫
  • PHP Manual
  • Trader 関数
  • Highest value over a specified period

trader_max

(PECL trader >= 0.2.0)

trader_max — Highest value over a specified period

説明

trader_max(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Index of highest value over a specified period

  • ≪ trader_max
  • trader_medprice ≫
  • PHP Manual
  • Trader 関数
  • Index of highest value over a specified period

trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Index of highest value over a specified period

説明

trader_maxindex(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Median Price

  • ≪ trader_maxindex
  • trader_mfi ≫
  • PHP Manual
  • Trader 関数
  • Median Price

trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Median Price

説明

trader_medprice(array $high, array $low): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Money Flow Index

  • ≪ trader_medprice
  • trader_midpoint ≫
  • PHP Manual
  • Trader 関数
  • Money Flow Index

trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Money Flow Index

説明

trader_mfi(
array $high,
array $low,
array $close,
array $volume,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

volume

取引高。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


MidPoint over period

  • ≪ trader_mfi
  • trader_midprice ≫
  • PHP Manual
  • Trader 関数
  • MidPoint over period

trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — MidPoint over period

説明

trader_midpoint(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Midpoint Price over period

  • ≪ trader_midpoint
  • trader_min ≫
  • PHP Manual
  • Trader 関数
  • Midpoint Price over period

trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Midpoint Price over period

説明

trader_midprice(array $high, array $low, int $timePeriod = ?): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Lowest value over a specified period

  • ≪ trader_midprice
  • trader_minindex ≫
  • PHP Manual
  • Trader 関数
  • Lowest value over a specified period

trader_min

(PECL trader >= 0.2.0)

trader_min — Lowest value over a specified period

説明

trader_min(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Index of lowest value over a specified period

  • ≪ trader_min
  • trader_minmax ≫
  • PHP Manual
  • Trader 関数
  • Index of lowest value over a specified period

trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Index of lowest value over a specified period

説明

trader_minindex(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Lowest and highest values over a specified period

  • ≪ trader_minindex
  • trader_minmaxindex ≫
  • PHP Manual
  • Trader 関数
  • Lowest and highest values over a specified period

trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Lowest and highest values over a specified period

説明

trader_minmax(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Indexes of lowest and highest values over a specified period

  • ≪ trader_minmax
  • trader_minus_di ≫
  • PHP Manual
  • Trader 関数
  • Indexes of lowest and highest values over a specified period

trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Indexes of lowest and highest values over a specified period

説明

trader_minmaxindex(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Minus Directional Indicator

  • ≪ trader_minmaxindex
  • trader_minus_dm ≫
  • PHP Manual
  • Trader 関数
  • Minus Directional Indicator

trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Minus Directional Indicator

説明

trader_minus_di(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Minus Directional Movement

  • ≪ trader_minus_di
  • trader_mom ≫
  • PHP Manual
  • Trader 関数
  • Minus Directional Movement

trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Minus Directional Movement

説明

trader_minus_dm(array $high, array $low, int $timePeriod = ?): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Momentum

  • ≪ trader_minus_dm
  • trader_mult ≫
  • PHP Manual
  • Trader 関数
  • Momentum

trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momentum

説明

trader_mom(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Vector Arithmetic Mult

  • ≪ trader_mom
  • trader_natr ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Mult

trader_mult

(PECL trader >= 0.2.0)

trader_mult — Vector Arithmetic Mult

説明

trader_mult(array $real0, array $real1): array

Calculates the vector dot product of real0 with real1 and returns the resulting vector.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Normalized Average True Range

  • ≪ trader_mult
  • trader_obv ≫
  • PHP Manual
  • Trader 関数
  • Normalized Average True Range

trader_natr

(PECL trader >= 0.2.0)

trader_natr — Normalized Average True Range

説明

trader_natr(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


On Balance Volume

  • ≪ trader_natr
  • trader_plus_di ≫
  • PHP Manual
  • Trader 関数
  • On Balance Volume

trader_obv

(PECL trader >= 0.2.0)

trader_obv — On Balance Volume

説明

trader_obv(array $real, array $volume): array

パラメータ

real

実数値の配列。

volume

取引高。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Plus Directional Indicator

  • ≪ trader_obv
  • trader_plus_dm ≫
  • PHP Manual
  • Trader 関数
  • Plus Directional Indicator

trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Plus Directional Indicator

説明

trader_plus_di(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Plus Directional Movement

  • ≪ trader_plus_di
  • trader_ppo ≫
  • PHP Manual
  • Trader 関数
  • Plus Directional Movement

trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Plus Directional Movement

説明

trader_plus_dm(array $high, array $low, int $timePeriod = ?): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Percentage Price Oscillator

  • ≪ trader_plus_dm
  • trader_roc ≫
  • PHP Manual
  • Trader 関数
  • Percentage Price Oscillator

trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Percentage Price Oscillator

説明

trader_ppo(
array $real,
int $fastPeriod = ?,
int $slowPeriod = ?,
int $mAType = ?
): array

パラメータ

real

実数値の配列。

fastPeriod

Number of period for the fast MA. Valid range from 2 to 100000.

slowPeriod

Number of period for the slow MA. Valid range from 2 to 100000.

mAType

Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Rate of change : ((price/prevPrice)-1)*100

  • ≪ trader_ppo
  • trader_rocp ≫
  • PHP Manual
  • Trader 関数
  • Rate of change : ((price/prevPrice)-1)*100

trader_roc

(PECL trader >= 0.2.0)

trader_roc — Rate of change : ((price/prevPrice)-1)*100

説明

trader_roc(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Rate of change Percentage: (price-prevPrice)/prevPrice

  • ≪ trader_roc
  • trader_rocr ≫
  • PHP Manual
  • Trader 関数
  • Rate of change Percentage: (price-prevPrice)/prevPrice

trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice

説明

trader_rocp(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Rate of change ratio: (price/prevPrice)

  • ≪ trader_rocp
  • trader_rocr100 ≫
  • PHP Manual
  • Trader 関数
  • Rate of change ratio: (price/prevPrice)

trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Rate of change ratio: (price/prevPrice)

説明

trader_rocr(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Rate of change ratio 100 scale: (price/prevPrice)*100

  • ≪ trader_rocr
  • trader_rsi ≫
  • PHP Manual
  • Trader 関数
  • Rate of change ratio 100 scale: (price/prevPrice)*100

trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100

説明

trader_rocr100(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Relative Strength Index

  • ≪ trader_rocr100
  • trader_sar ≫
  • PHP Manual
  • Trader 関数
  • Relative Strength Index

trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Relative Strength Index

説明

trader_rsi(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Parabolic SAR

  • ≪ trader_rsi
  • trader_sarext ≫
  • PHP Manual
  • Trader 関数
  • Parabolic SAR

trader_sar

(PECL trader >= 0.2.0)

trader_sar — Parabolic SAR

説明

trader_sar(
array $high,
array $low,
float $acceleration = ?,
float $maximum = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

acceleration

Acceleration Factor used up to the Maximum value. Valid range from 0 to TRADER_REAL_MAX.

maximum

Acceleration Factor Maximum value. Valid range from 0 to TRADER_REAL_MAX.

戻り値

Returns an array with calculated data or false on failure.


Parabolic SAR - Extended

  • ≪ trader_sar
  • trader_set_compat ≫
  • PHP Manual
  • Trader 関数
  • Parabolic SAR - Extended

trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Parabolic SAR - Extended

説明

trader_sarext(
array $high,
array $low,
float $startValue = ?,
float $offsetOnReverse = ?,
float $accelerationInitLong = ?,
float $accelerationLong = ?,
float $accelerationMaxLong = ?,
float $accelerationInitShort = ?,
float $accelerationShort = ?,
float $accelerationMaxShort = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

startValue

Start value and direction. 0 for Auto, >0 for Long, <0 for Short. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

offsetOnReverse

Percent offset added/removed to initial stop on short/long reversal. Valid range from 0 to TRADER_REAL_MAX.

accelerationInitLong

Acceleration Factor initial value for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationLong

Acceleration Factor for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationMaxLong

Acceleration Factor maximum value for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationInitShort

Acceleration Factor initial value for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationShort

Acceleration Factor for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

accelerationMaxShort

Acceleration Factor maximum value for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

戻り値

Returns an array with calculated data or false on failure.


Set compatibility mode

  • ≪ trader_sarext
  • trader_set_unstable_period ≫
  • PHP Manual
  • Trader 関数
  • Set compatibility mode

trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Set compatibility mode

説明

trader_set_compat(int $compatId): void

Set compatibility mode which will affect the way calculations are done by all the extension functions.

パラメータ

compatId

Compatibility Id. TRADER_COMPATIBILITY_* series of constants should be used.

戻り値

値を返しません。


Set unstable period

  • ≪ trader_set_compat
  • trader_sin ≫
  • PHP Manual
  • Trader 関数
  • Set unstable period

trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Set unstable period

説明

trader_set_unstable_period(int $functionId, int $timePeriod): void

Influences unstable period factor for functions, which are sensible to it. More information about unstable periods can be found on the » TA-Lib API documentation page.

パラメータ

functionId

Function ID the factor should be set for. TRADER_FUNC_UNST_* constant series can be used to affect the corresponding function.

timePeriod

Unstable period value.

戻り値

値を返しません。


Vector Trigonometric Sin

  • ≪ trader_set_unstable_period
  • trader_sinh ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Sin

trader_sin

(PECL trader >= 0.2.0)

trader_sin — Vector Trigonometric Sin

説明

trader_sin(array $real): array

Calculates the sine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric Sinh

  • ≪ trader_sin
  • trader_sma ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Sinh

trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Vector Trigonometric Sinh

説明

trader_sinh(array $real): array

Calculates the hyperbolic sine for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Simple Moving Average

  • ≪ trader_sinh
  • trader_sqrt ≫
  • PHP Manual
  • Trader 関数
  • Simple Moving Average

trader_sma

(PECL trader >= 0.2.0)

trader_sma — Simple Moving Average

説明

trader_sma(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Vector Square Root

  • ≪ trader_sma
  • trader_stddev ≫
  • PHP Manual
  • Trader 関数
  • Vector Square Root

trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Vector Square Root

説明

trader_sqrt(array $real): array

Calculates the square root of each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Standard Deviation

  • ≪ trader_sqrt
  • trader_stoch ≫
  • PHP Manual
  • Trader 関数
  • Standard Deviation

trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Standard Deviation

説明

trader_stddev(array $real, int $timePeriod = ?, float $nbDev = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

nbDev

戻り値

Returns an array with calculated data or false on failure.


Stochastic

  • ≪ trader_stddev
  • trader_stochf ≫
  • PHP Manual
  • Trader 関数
  • Stochastic

trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Stochastic

説明

trader_stoch(
array $high,
array $low,
array $close,
int $fastK_Period = ?,
int $slowK_Period = ?,
int $slowK_MAType = ?,
int $slowD_Period = ?,
int $slowD_MAType = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

fastK_Period

Time period for building the Fast-K line. Valid range from 1 to 100000.

slowK_Period

Smoothing for making the Slow-K line. Valid range from 1 to 100000, usually set to 3.

slowK_MAType

Type of Moving Average for Slow-K. TRADER_MA_TYPE_* series of constants should be used.

slowD_Period

Smoothing for making the Slow-D line. Valid range from 1 to 100000.

slowD_MAType

Type of Moving Average for Slow-D. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Stochastic Fast

  • ≪ trader_stoch
  • trader_stochrsi ≫
  • PHP Manual
  • Trader 関数
  • Stochastic Fast

trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Stochastic Fast

説明

trader_stochf(
array $high,
array $low,
array $close,
int $fastK_Period = ?,
int $fastD_Period = ?,
int $fastD_MAType = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

fastK_Period

Time period for building the Fast-K line. Valid range from 1 to 100000.

fastD_Period

Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.

fastD_MAType

Type of Moving Average for Fast-D. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Stochastic Relative Strength Index

  • ≪ trader_stochf
  • trader_sub ≫
  • PHP Manual
  • Trader 関数
  • Stochastic Relative Strength Index

trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Stochastic Relative Strength Index

説明

trader_stochrsi(
array $real,
int $timePeriod = ?,
int $fastK_Period = ?,
int $fastD_Period = ?,
int $fastD_MAType = ?
): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

fastK_Period

Time period for building the Fast-K line. Valid range from 1 to 100000.

fastD_Period

Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.

fastD_MAType

Type of Moving Average for Fast-D. TRADER_MA_TYPE_* series of constants should be used.

戻り値

Returns an array with calculated data or false on failure.


Vector Arithmetic Subtraction

  • ≪ trader_stochrsi
  • trader_sum ≫
  • PHP Manual
  • Trader 関数
  • Vector Arithmetic Subtraction

trader_sub

(PECL trader >= 0.2.0)

trader_sub — Vector Arithmetic Subtraction

説明

trader_sub(array $real0, array $real1): array

Calculates the vector subtraction of real1 from real0 and returns the resulting vector.

パラメータ

real0

実数値の配列。

real1

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Summation

  • ≪ trader_sub
  • trader_t3 ≫
  • PHP Manual
  • Trader 関数
  • Summation

trader_sum

(PECL trader >= 0.2.0)

trader_sum — Summation

説明

trader_sum(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Triple Exponential Moving Average (T3)

  • ≪ trader_sum
  • trader_tan ≫
  • PHP Manual
  • Trader 関数
  • Triple Exponential Moving Average (T3)

trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Triple Exponential Moving Average (T3)

説明

trader_t3(array $real, int $timePeriod = ?, float $vFactor = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

vFactor

Volume Factor. Valid range from 1 to 0.

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric Tan

  • ≪ trader_t3
  • trader_tanh ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Tan

trader_tan

(PECL trader >= 0.2.0)

trader_tan — Vector Trigonometric Tan

説明

trader_tan(array $real): array

Calculates the tangent for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Vector Trigonometric Tanh

  • ≪ trader_tan
  • trader_tema ≫
  • PHP Manual
  • Trader 関数
  • Vector Trigonometric Tanh

trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Vector Trigonometric Tanh

説明

trader_tanh(array $real): array

Calculates the hyperbolic tangent for each value in real and returns the resulting array.

パラメータ

real

実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Triple Exponential Moving Average

  • ≪ trader_tanh
  • trader_trange ≫
  • PHP Manual
  • Trader 関数
  • Triple Exponential Moving Average

trader_tema

(PECL trader >= 0.2.0)

trader_tema — Triple Exponential Moving Average

説明

trader_tema(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


True Range

  • ≪ trader_tema
  • trader_trima ≫
  • PHP Manual
  • Trader 関数
  • True Range

trader_trange

(PECL trader >= 0.2.0)

trader_trange — True Range

説明

trader_trange(array $high, array $low, array $close): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Triangular Moving Average

  • ≪ trader_trange
  • trader_trix ≫
  • PHP Manual
  • Trader 関数
  • Triangular Moving Average

trader_trima

(PECL trader >= 0.2.0)

trader_trima — Triangular Moving Average

説明

trader_trima(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

  • ≪ trader_trima
  • trader_tsf ≫
  • PHP Manual
  • Trader 関数
  • 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

trader_trix

(PECL trader >= 0.2.0)

trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

説明

trader_trix(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Time Series Forecast

  • ≪ trader_trix
  • trader_typprice ≫
  • PHP Manual
  • Trader 関数
  • Time Series Forecast

trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Time Series Forecast

説明

trader_tsf(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Typical Price

  • ≪ trader_tsf
  • trader_ultosc ≫
  • PHP Manual
  • Trader 関数
  • Typical Price

trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Typical Price

説明

trader_typprice(array $high, array $low, array $close): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Ultimate Oscillator

  • ≪ trader_typprice
  • trader_var ≫
  • PHP Manual
  • Trader 関数
  • Ultimate Oscillator

trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Ultimate Oscillator

説明

trader_ultosc(
array $high,
array $low,
array $close,
int $timePeriod1 = ?,
int $timePeriod2 = ?,
int $timePeriod3 = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod1

Number of bars for 1st period. Valid range from 1 to 100000.

timePeriod2

Number of bars for 2nd period. Valid range from 1 to 100000.

timePeriod3

Number of bars for 3rd period. Valid range from 1 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Variance

  • ≪ trader_ultosc
  • trader_wclprice ≫
  • PHP Manual
  • Trader 関数
  • Variance

trader_var

(PECL trader >= 0.2.0)

trader_var — Variance

説明

trader_var(array $real, int $timePeriod = ?, float $nbDev = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

nbDev

戻り値

Returns an array with calculated data or false on failure.


Weighted Close Price

  • ≪ trader_var
  • trader_willr ≫
  • PHP Manual
  • Trader 関数
  • Weighted Close Price

trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Weighted Close Price

説明

trader_wclprice(array $high, array $low, array $close): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

戻り値

Returns an array with calculated data or false on failure.


Williams' %R

  • ≪ trader_wclprice
  • trader_wma ≫
  • PHP Manual
  • Trader 関数
  • Williams' %R

trader_willr

(PECL trader >= 0.2.0)

trader_willr — Williams' %R

説明

trader_willr(
array $high,
array $low,
array $close,
int $timePeriod = ?
): array

パラメータ

high

高値。実数値の配列。

low

安値。実数値の配列。

close

終値。実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


Weighted Moving Average

  • ≪ trader_willr
  • テキスト以外の MIME 型 ≫
  • PHP Manual
  • Trader 関数
  • Weighted Moving Average

trader_wma

(PECL trader >= 0.2.0)

trader_wma — Weighted Moving Average

説明

trader_wma(array $real, int $timePeriod = ?): array

パラメータ

real

実数値の配列。

timePeriod

Number of period. Valid range from 2 to 100000.

戻り値

Returns an array with calculated data or false on failure.


テキスト以外の MIME 型

  • FDF — Forms Data Format
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • FDF 関数
  • GnuPG — GNU Privacy Guard
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GnuPG 関数
  • wkhtmltox
    • はじめに
    • インストール/設定
    • wkhtmltox\PDF\Converter — wkhtmltox\PDF\Converter クラス
    • wkhtmltox\PDF\Object — The wkhtmltox\PDF\Object class
    • wkhtmltox\Image\Converter — wkhtmltox\Image\Converter クラス
  • PS — PostScript ドキュメントの作成
    • はじめに
    • インストール/設定
    • 定義済み定数
    • PS 関数
  • RpmInfo
    • はじめに
    • インストール/設定
    • 定義済み定数
    • RpmInfo 関数
  • XLSWriter
    • はじめに
    • インストール/設定
    • Vtiful\Kernel\Excel — The Vtiful\Kernel\Excel class
    • Vtiful\Kernel\Format — The Vtiful\Kernel\Format class


Forms Data Format

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
  • FDF 関数
    • fdf_add_doc_javascript — FDF ドキュメントに javascript コードを追加する
    • fdf_add_template — テンプレートを FDF ドキュメントに追加する
    • fdf_close — FDF ドキュメントを閉じる
    • fdf_create — 新規 FDF ドキュメントを作成する
    • fdf_enum_values — 各ドキュメントの値に対してユーザー定義関数をコールする
    • fdf_errno — 直近の fdf 操作に関するエラーコードを返す
    • fdf_error — 直近の fdf エラーコードについての説明を返す
    • fdf_get_ap — フィールドの外観を取得する
    • fdf_get_attachment — FDF に埋め込まれている、アップロードされたファイルを展開する
    • fdf_get_encoding — /Encoding キーの値を取得する
    • fdf_get_file — /F キーの値を得る
    • fdf_get_flags — フィールドのフラグを取得する
    • fdf_get_opt — フィールドのオプション配列から値を取得する
    • fdf_get_status — /STATUS キーの値を得る
    • fdf_get_value — フィールドの値を得る
    • fdf_get_version — FDF API あるいはファイルのバージョンを取得する
    • fdf_header — FDF 固有の出力ヘッダをセットする
    • fdf_next_field_name — 次のフィールド名を得る
    • fdf_open — FDF ドキュメントをオープンする
    • fdf_open_string — 文字列から FDF ドキュメントを読み込む
    • fdf_remove_item — フォームのターゲットフレームを設定する
    • fdf_save — FDF ドキュメントを保存する
    • fdf_save_string — FDF ドキュメントを文字列として返す
    • fdf_set_ap — フィールドの外観を設定する
    • fdf_set_encoding — FDF 文字エンコーディングを設定する
    • fdf_set_file — FDF データを表示する PDF ドキュメントを設定する
    • fdf_set_flags — フィールドのフラグを設定する
    • fdf_set_javascript_action — フィールドの javascript アクションを設定する
    • fdf_set_on_import_javascript — Acrobat が FDF をオープンした際に実行される javascript のコードを追加する
    • fdf_set_opt — フィールドのオプションを設定する
    • fdf_set_status — /STATUS キーの値を設定する
    • fdf_set_submit_form_action — フィールドの投稿フォームアクションを設定する
    • fdf_set_target_frame — フォームの表示対象となるフレームを設定する
    • fdf_set_value — フィールドの値を設定する
    • fdf_set_version — FDF ファイルのバージョン番号を設定する


はじめに

Forms Data Format (FDF)は、PDF ドキュメント内部のフォームを処理する ためのフォーマットです。FDF の詳細および一般的な用途については、 » http://www.adobe.com/devnet/acrobat/fdftoolkit.html にある ドキュメントを参照ください。

FDF の基本的な考えは HTML フォームに似ています。基本的な違いは、 投稿ボタンが押された際にフォームに埋められたデータをサーバーに送信する 方法のフォーマット(これが Form Data Format そのものです)およびフォームの フォーマット自体(これは Portable Document Format、PDF です)です。 FDF データの処理は、fdf 関数が提供する機能の一つです。しかし他にも 機能はあります。既存の PDF フォームを用いてフォーム自体を修正せずに 入力フィールドのデータを入力させることもあるかと思われます。 このような場合、FDF ドキュメント を作成し (fdf_create())、各入力フィールドの値を設定し (fdf_set_value())、PDF フォームとそれを関連付けます (fdf_set_file())。最後にブラウザに MIME 型 application/vnd.fdf で送信する必要があります。 ブラウザの Acrobat Reader プラグイン がこの MIME 型を認識し、 関連する PDF フォームを読み込み、FDF ドキュメントからのデータを 書き込みます。

テキストエディタで FDF ドキュメントの中を見てみると、 FDF という名前のカタログオブジェクトが見つかる はずです。このようなオブジェクトには Fields、 F、Status といった複数の エントリが含まれます。 最も多く使用されるエントりは Fields および F で、Fields は 一連の入力フィールドを指し、F は このデータが属する PDF ドキュメントのファイル名を保持します。 これらのエントリは、FDF ドキュメントの中で /F-Key または /Status-Key として参照されています。fdf_set_file() および fdf_set_status() のような関数により、これらの エントリを修正することが可能です。Fields は、 fdf_set_value()、fdf_set_opt() 等で修整可能です。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • FDF
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

» http://www.adobe.com/devnet/acrobat/fdftoolkit.html から取得可能な FDF toolkit SDKが必要です。 PHP 4.3.0 以降では、少なくとも SDK version 5.0 が必要です。 FDF toolkit library はバイナリ版のみ利用可能で、 Adobe によりサポートされているプラットフォームは Win32、Linux、Solaris、AIX です。


インストール手順

この拡張モジュールは、メンテナンスされておらず開発が止まっています。 しかし、ソースコードは PECL SVN から取得できます。 » https://svn.php.net/viewvc/pecl/fdf.

この拡張モジュールは、PHP にバンドルされていません。

注意: fdftk サポートを指定して PHP を設定した際に問題を発生した場合、 ヘッダファイル fdftk.h および ライブラリ libfdftk.so が正しい場所にあることを 確認してください。configure スクリプトは、FDF SDK 配布ファイルおよび 通常の DIR/include、 DIR/lib といった配置のディレクトリ構造をともに サポートします。このため、配布ファイルを展開したディレクトリにそのまま おいておくか、あるいは /usr/local/include および /usr/local/lib のように使用するプラットフォームに 応じた適当なディレクトリに移動して --with-fdftk=/usr/local を指定して 設定することが可能です。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 fdftk.dll


リソース型

多くの fdf 関数は、最初のパラメータとして fdf リソースが必要です。 fdf リソースは、オープンした fdf ファイルの ハンドルです。fdf リソースは、 fdf_create()、fdf_open()、 fdf_open_string() を用いて取得することが可能です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FDFValue (int)
FDFStatus (int)
FDFFile (int)
FDFID (int)
FDFFf (int)
FDFSetFf (int)
FDFClearFf (int)
FDFFlags (int)
FDFSetF (int)
FDFClrF (int)
FDFAP (int)
FDFAS (int)
FDFAction (int)
FDFAA (int)
FDFAPRef (int)
FDFIF (int)
FDFEnter (int)
FDFExit (int)
FDFDown (int)
FDFUp (int)
FDFFormat (int)
FDFValidate (int)
FDFKeystroke (int)
FDFCalculate (int)
FDFNormalAP (int)
FDFRolloverAP (int)
FDFDownAP (int)


例

以下の例でフォームデータの評価に関して説明します。

例1 FDF ドキュメントの評価

<?php
// 拡張モジュールが提供する入力文字列から fdf をオープンします。
// pdf フォームには volume, date, comment, publisher, preparer
// という名前のテキスト入力フィールドと 2 つのチェックボックス
// show_publisher および show_preparer があるものとします。
$fdf = fdf_open_string($HTTP_FDF_DATA);
$volume = fdf_get_value($fdf, "volume");
echo "volume フィールドの値は '<b>$volume</b>'<br />";

$date = fdf_get_value($fdf, "date");
echo "date フィールドの値は '<b>$date</b>'<br />";

$comment = fdf_get_value($fdf, "comment");
echo "comment フィールドの値は '<b>$comment</b>'<br />";

if (fdf_get_value($fdf, "show_publisher") == "On") {
$publisher = fdf_get_value($fdf, "publisher");
echo "publisher フィールドの値は '<b>$publisher</b>'<br />";
} else
echo "Publisher は非公開です。<br />";

if (fdf_get_value($fdf, "show_preparer") == "On") {
$preparer = fdf_get_value($fdf, "preparer");
echo "preparer フィールドの値は '<b>$preparer</b>'<br />";
} else
echo "Preparer は非公開です。<br />";
fdf_close($fdf);
?>


FDF 関数

目次

  • fdf_add_doc_javascript — FDF ドキュメントに javascript コードを追加する
  • fdf_add_template — テンプレートを FDF ドキュメントに追加する
  • fdf_close — FDF ドキュメントを閉じる
  • fdf_create — 新規 FDF ドキュメントを作成する
  • fdf_enum_values — 各ドキュメントの値に対してユーザー定義関数をコールする
  • fdf_errno — 直近の fdf 操作に関するエラーコードを返す
  • fdf_error — 直近の fdf エラーコードについての説明を返す
  • fdf_get_ap — フィールドの外観を取得する
  • fdf_get_attachment — FDF に埋め込まれている、アップロードされたファイルを展開する
  • fdf_get_encoding — /Encoding キーの値を取得する
  • fdf_get_file — /F キーの値を得る
  • fdf_get_flags — フィールドのフラグを取得する
  • fdf_get_opt — フィールドのオプション配列から値を取得する
  • fdf_get_status — /STATUS キーの値を得る
  • fdf_get_value — フィールドの値を得る
  • fdf_get_version — FDF API あるいはファイルのバージョンを取得する
  • fdf_header — FDF 固有の出力ヘッダをセットする
  • fdf_next_field_name — 次のフィールド名を得る
  • fdf_open — FDF ドキュメントをオープンする
  • fdf_open_string — 文字列から FDF ドキュメントを読み込む
  • fdf_remove_item — フォームのターゲットフレームを設定する
  • fdf_save — FDF ドキュメントを保存する
  • fdf_save_string — FDF ドキュメントを文字列として返す
  • fdf_set_ap — フィールドの外観を設定する
  • fdf_set_encoding — FDF 文字エンコーディングを設定する
  • fdf_set_file — FDF データを表示する PDF ドキュメントを設定する
  • fdf_set_flags — フィールドのフラグを設定する
  • fdf_set_javascript_action — フィールドの javascript アクションを設定する
  • fdf_set_on_import_javascript — Acrobat が FDF をオープンした際に実行される javascript のコードを追加する
  • fdf_set_opt — フィールドのオプションを設定する
  • fdf_set_status — /STATUS キーの値を設定する
  • fdf_set_submit_form_action — フィールドの投稿フォームアクションを設定する
  • fdf_set_target_frame — フォームの表示対象となるフレームを設定する
  • fdf_set_value — フィールドの値を設定する
  • fdf_set_version — FDF ファイルのバージョン番号を設定する


FDF ドキュメントに javascript コードを追加する

  • ≪ FDF 関数
  • fdf_add_template ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントに javascript コードを追加する

fdf_add_doc_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_doc_javascript — FDF ドキュメントに javascript コードを追加する

説明

fdf_add_doc_javascript(resource $fdf_document, string $script_name, string $script_code): bool

スクリプトを FDF に追加します。Acrobat は、FDF が読み込まれた際に それをドキュメントレベルのスクリプトとして追加します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

script_name

スクリプト名。

script_code

スクリプトのコード。コード内での改行は、できるだけ '\r' を使用するようにしてください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 JavaScript コードを FDF に追加する

<?php
$fdf = fdf_create();
fdf_add_doc_javascript($fdf, "PlusOne", "function PlusOne(x)\r{\r return x+1;\r}\r");
fdf_save($fdf);
?>

これは、以下のような FDF を出力します。

%FDF-1.2
%aaIO
1 0 obj
<<
/FDF << /JavaScript << /Doc [ (PlusOne)(function PlusOne\(x\)\r{\r  return x+1;\r}\r)] >> >>
>>
endobj
trailer
<<
/Root 1 0 R

>>
%%EOF


テンプレートを FDF ドキュメントに追加する

  • ≪ fdf_add_doc_javascript
  • fdf_close ≫
  • PHP Manual
  • FDF 関数
  • テンプレートを FDF ドキュメントに追加する

fdf_add_template

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_template — テンプレートを FDF ドキュメントに追加する

説明

fdf_add_template(
resource $fdf_document,
int $newpage,
string $filename,
string $template,
int $rename
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


FDF ドキュメントを閉じる

  • ≪ fdf_add_template
  • fdf_create ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントを閉じる

fdf_close

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_close — FDF ドキュメントを閉じる

説明

fdf_close(resource $fdf_document): void

FDF ドキュメントを閉じます。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

値を返しません。

参考

  • fdf_open() - FDF ドキュメントをオープンする


新規 FDF ドキュメントを作成する

  • ≪ fdf_close
  • fdf_enum_values ≫
  • PHP Manual
  • FDF 関数
  • 新規 FDF ドキュメントを作成する

fdf_create

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_create — 新規 FDF ドキュメントを作成する

説明

fdf_create(): resource

新規 FDF ドキュメントを作成します。

この関数は、PDF ドキュメントの入力フィールドにデータを書きこみたい場合に必要です。

パラメータ

この関数にはパラメータはありません。

戻り値

FDF ドキュメントハンドル、あるいはエラー時に false を返します。

例

例1 PDF ドキュメントを公開する

<?php
$outfdf = fdf_create();
fdf_set_value($outfdf, "volume", $volume, 0);

fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
fdf_save($outfdf, "outtest.fdf");
fdf_close($outfdf);
Header("Content-type: application/vnd.fdf");
$fp = fopen("outtest.fdf", "r");
fpassthru($fp);
unlink("outtest.fdf");
?>

参考

  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_save() - FDF ドキュメントを保存する
  • fdf_open() - FDF ドキュメントをオープンする


各ドキュメントの値に対してユーザー定義関数をコールする

  • ≪ fdf_create
  • fdf_errno ≫
  • PHP Manual
  • FDF 関数
  • 各ドキュメントの値に対してユーザー定義関数をコールする

fdf_enum_values

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_enum_values — 各ドキュメントの値に対してユーザー定義関数をコールする

説明

fdf_enum_values(resource $fdf_document, callable $function, mixed $userdata = ?): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


直近の fdf 操作に関するエラーコードを返す

  • ≪ fdf_enum_values
  • fdf_error ≫
  • PHP Manual
  • FDF 関数
  • 直近の fdf 操作に関するエラーコードを返す

fdf_errno

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_errno — 直近の fdf 操作に関するエラーコードを返す

説明

fdf_errno(): int

直近の FDF 関数コールによって設定されたエラーコードを取得します。

エラーの内容についてのテキストを取得するには fdf_error() を使用します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーコードを表す整数値、あるいはエラーがない場合にゼロを返します。

参考

  • fdf_error() - 直近の fdf エラーコードについての説明を返す


直近の fdf エラーコードについての説明を返す

  • ≪ fdf_errno
  • fdf_get_ap ≫
  • PHP Manual
  • FDF 関数
  • 直近の fdf エラーコードについての説明を返す

fdf_error

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_error — 直近の fdf エラーコードについての説明を返す

説明

fdf_error(int $error_code = -1): string

error_code で指定したエラーコードについての説明テキストを取得します。

パラメータ

error_code

fdf_errno() で取得したエラーコード。 省略した場合は、直近の操作で設定された内部エラーコードを使用します。

戻り値

エラーメッセージを表す文字列、あるいは何も問題がない場合は no error を返します。

参考

  • fdf_errno() - 直近の fdf 操作に関するエラーコードを返す


フィールドの外観を取得する

  • ≪ fdf_error
  • fdf_get_attachment ≫
  • PHP Manual
  • FDF 関数
  • フィールドの外観を取得する

fdf_get_ap

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_ap — フィールドの外観を取得する

説明

fdf_get_ap(
resource $fdf_document,
string $field,
int $face,
string $filename
): bool

field の外観 (つまり /AP キーの値) を取得し、ファイルに保存します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

field

face

FDFNormalAP、FDFRolloverAP および FDFDownAP のいずれか。

filename

ここに外観を保存します。

戻り値

成功した場合に true を、失敗した場合に false を返します。


FDF に埋め込まれている、アップロードされたファイルを展開する

  • ≪ fdf_get_ap
  • fdf_get_encoding ≫
  • PHP Manual
  • FDF 関数
  • FDF に埋め込まれている、アップロードされたファイルを展開する

fdf_get_attachment

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_attachment — FDF に埋め込まれている、アップロードされたファイルを展開する

説明

fdf_get_attachment(resource $fdf_document, string $fieldname, string $savepath): array

「ファイル選択」フィールド fieldname によって アップロードされたファイルを展開し、それを savepath に保存します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

savepath

ファイル名または既存のディレクトリ名を指定し、ディレクトリ名を 指定した場合はその下に元のファイル名で保存されます。 同名のファイルが存在した場合は上書きします。

注意:

savepath にディレクトリを使用してファイルを 保存してその名前を調べる以外には、元のファイル名を知る方法はないと 思われます。

戻り値

返される配列は以下のようなフィールドを保持します。

  • path - ファイルが保存された場所
  • size - 保存されたファイルのバイト数
  • type - (もし FDF 指定されていた場合) FDF の mimetype

例

例1 アップロードされたファイルを保存する

<?php
$fdf = fdf_open_string($HTTP_FDF_DATA);
$data = fdf_get_attachment($fdf, "filename", "/tmpdir");
echo "アップロードされたファイルが $data[path] に保存されました。";
?>


/Encoding キーの値を取得する

  • ≪ fdf_get_attachment
  • fdf_get_file ≫
  • PHP Manual
  • FDF 関数
  • /Encoding キーの値を取得する

fdf_get_encoding

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_encoding — /Encoding キーの値を取得する

説明

fdf_get_encoding(resource $fdf_document): string

/Encoding キーの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

エンコーディングを文字列で返します。 デフォルトの PDFDocEncoding/Unicode スキームを使用している場合は空の文字列を返します。

参考

  • fdf_set_encoding() - FDF 文字エンコーディングを設定する


/F キーの値を得る

  • ≪ fdf_get_encoding
  • fdf_get_flags ≫
  • PHP Manual
  • FDF 関数
  • /F キーの値を得る

fdf_get_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_file — /F キーの値を得る

説明

fdf_get_file(resource $fdf_document): string

/F キーの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

キーの値を文字列を返します。

参考

  • fdf_set_file() - FDF データを表示する PDF ドキュメントを設定する


フィールドのフラグを取得する

  • ≪ fdf_get_file
  • fdf_get_opt ≫
  • PHP Manual
  • FDF 関数
  • フィールドのフラグを取得する

fdf_get_flags

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_flags — フィールドのフラグを取得する

説明

fdf_get_flags(resource $fdf_document, string $fieldname, int $whichflags): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


フィールドのオプション配列から値を取得する

  • ≪ fdf_get_flags
  • fdf_get_status ≫
  • PHP Manual
  • FDF 関数
  • フィールドのオプション配列から値を取得する

fdf_get_opt

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECLv)

fdf_get_opt — フィールドのオプション配列から値を取得する

説明

fdf_get_opt(resource $fdf_document, string $fieldname, int $element = -1): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


/STATUS キーの値を得る

  • ≪ fdf_get_opt
  • fdf_get_value ≫
  • PHP Manual
  • FDF 関数
  • /STATUS キーの値を得る

fdf_get_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_status — /STATUS キーの値を得る

説明

fdf_get_status(resource $fdf_document): string

/STATUS キーの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

キーの値を文字列で返します。

参考

  • fdf_set_status() - /STATUS キーの値を設定する


フィールドの値を得る

  • ≪ fdf_get_status
  • fdf_get_version ≫
  • PHP Manual
  • FDF 関数
  • フィールドの値を得る

fdf_get_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_value — フィールドの値を得る

説明

fdf_get_value(resource $fdf_document, string $fieldname, int $which = -1): mixed

指定したフィールドの値を取得します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールドの名前を表す文字列。

which

このオプションパラメータを渡すことで、配列フィールドの 要素が取得可能です。番号はゼロから始まります。配列以外のフィールドでは、 このオプションは無視されます。

戻り値

フィールドの値を返します。

変更履歴

バージョン | 説明
4.3.0 | 配列のサポート、およびオプションのパラメータ which が追加されました。

参考

  • fdf_set_value() - フィールドの値を設定する


FDF API あるいはファイルのバージョンを取得する

  • ≪ fdf_get_value
  • fdf_header ≫
  • PHP Manual
  • FDF 関数
  • FDF API あるいはファイルのバージョンを取得する

fdf_get_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_version — FDF API あるいはファイルのバージョンを取得する

説明

fdf_get_version(resource $fdf_document = ?): string

指定したドキュメントの FDF バージョン、 あるいはパラメータを指定しなかった場合はツールキット API のバージョンを返します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

バージョンを表す文字列を返します。 現在の FDF ツールキット 5.0 では API のバージョン番号は 5.0 で、 ドキュメントのバージョン番号は 1.2 1.3 あるいは 1.4 です。

参考

  • fdf_set_version() - FDF ファイルのバージョン番号を設定する


FDF 固有の出力ヘッダをセットする

  • ≪ fdf_get_version
  • fdf_next_field_name ≫
  • PHP Manual
  • FDF 関数
  • FDF 固有の出力ヘッダをセットする

fdf_header

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVNf)

fdf_header — FDF 固有の出力ヘッダをセットする

説明

fdf_header(): void

この関数は、簡便に FDF の出力に適当な HTTP ヘッダを付加できるよう 用意されており、Content-type: を application/vnd.fdf に設定します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


次のフィールド名を得る

  • ≪ fdf_header
  • fdf_open ≫
  • PHP Manual
  • FDF 関数
  • 次のフィールド名を得る

fdf_next_field_name

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_next_field_name — 次のフィールド名を得る

説明

fdf_next_field_name(resource $fdf_document, string $fieldname = ?): string

指定したフィールドの後のフィールドの名前を返します。 この名前をその他の関数で使用します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。 省略した場合は最初のフィールドとみなされます。

戻り値

フィールド名を文字列で返します。

例

例1 FDF のすべてのフィールド名を検出する

<?php
$fdf = fdf_open($HTTP_FDF_DATA);
for ($field = fdf_next_field_name($fdf);
$field != "";
$field = fdf_next_field_name($fdf, $field)) {
echo "field: $field\n";
}
?>

参考

  • fdf_get_value() - フィールドの値を得る


FDF ドキュメントをオープンする

  • ≪ fdf_next_field_name
  • fdf_open_string ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントをオープンする

fdf_open

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open — FDF ドキュメントをオープンする

説明

fdf_open(string $filename): resource

フォームデータを含むファイルをオープンします。

fdf_open_string() を用いて、 PDF フォームの POST リクエストを処理することもできます。

パラメータ

filename

FDF ファイルへのパス。このファイルは、PDF フォームから返されたものか、 fdf_create() および fdf_save() で作成したものである必要があります。

戻り値

FDF ドキュメントのハンドル、あるいはエラー時に false を返します。

例

例1 フォームデータへのアクセス

<?php
// FDF データをテンポラリファイルに保存します
$fdffp = fopen("test.fdf", "w");
fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
fclose($fdffp);

// テンポラリファイルをオープンし、データを評価します
$fdf = fdf_open("test.fdf");
/* ... */
fdf_close($fdf);
?>

参考

  • fdf_open_string() - 文字列から FDF ドキュメントを読み込む
  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save() - FDF ドキュメントを保存する


文字列から FDF ドキュメントを読み込む

  • ≪ fdf_open
  • fdf_remove_item ≫
  • PHP Manual
  • FDF 関数
  • 文字列から FDF ドキュメントを読み込む

fdf_open_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open_string — 文字列から FDF ドキュメントを読み込む

説明

fdf_open_string(string $fdf_data): resource

文字列からデータを読み込みます。

fdf_open_string() を $HTTP_FDF_DATA とあわせて使用することで、リモート クライアントからの FDF フォーム入力を処理することが可能です。

パラメータ

fdf_data

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

FDF ドキュメントハンドル、あるいはエラー時に false を返します。

例

例1 フォームデータへのアクセス

<?php
$fdf = fdf_open_string($HTTP_FDF_DATA);
/* ... */
fdf_close($fdf);
?>

参考

  • fdf_open() - FDF ドキュメントをオープンする
  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save_string() - FDF ドキュメントを文字列として返す


フォームのターゲットフレームを設定する

  • ≪ fdf_open_string
  • fdf_save ≫
  • PHP Manual
  • FDF 関数
  • フォームのターゲットフレームを設定する

fdf_remove_item

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_remove_item — フォームのターゲットフレームを設定する

説明

fdf_remove_item(resource $fdf_document, string $fieldname, int $item): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


FDF ドキュメントを保存する

  • ≪ fdf_remove_item
  • fdf_save_string ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントを保存する

fdf_save

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save — FDF ドキュメントを保存する

説明

fdf_save(resource $fdf_document, string $filename = ?): bool

FDF ドキュメントを保存します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

filename

指定した場合は、結果の FDF がここに書き込まれます。 それ以外の場合は、この関数は FDF をデフォルトの PHP 出力ストリームに書き込みます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save_string() - FDF ドキュメントを文字列として返す


FDF ドキュメントを文字列として返す

  • ≪ fdf_save
  • fdf_set_ap ≫
  • PHP Manual
  • FDF 関数
  • FDF ドキュメントを文字列として返す

fdf_save_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save_string — FDF ドキュメントを文字列として返す

説明

fdf_save_string(resource $fdf_document): string

FDF ドキュメントを文字列として返します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

戻り値

ドキュメントを表す文字列、あるいはエラー時に false を返します。

例

例1 FDF の文字列での取得

<?php
$fdf = fdf_create();
fdf_set_value($fdf, "foo", "bar");
$str = fdf_save_string($fdf);
fdf_close($fdf);
echo $str;
?>

上の例の出力は以下となります。

%FDF-1.2
%a??O
1 0 obj
<<
/FDF << /Fields 2 0 R >>
>>
endobj
2 0 obj
[
<< /T (foo)/V (bar)>>
]
endobj
trailer
<<
/Root 1 0 R

>>
%%EOF

参考

  • fdf_open_string() - 文字列から FDF ドキュメントを読み込む
  • fdf_close() - FDF ドキュメントを閉じる
  • fdf_create() - 新規 FDF ドキュメントを作成する
  • fdf_save() - FDF ドキュメントを保存する


フィールドの外観を設定する

  • ≪ fdf_save_string
  • fdf_set_encoding ≫
  • PHP Manual
  • FDF 関数
  • フィールドの外観を設定する

fdf_set_ap

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_ap — フィールドの外観を設定する

説明

fdf_set_ap(
resource $fdf_document,
string $field_name,
int $face,
string $filename,
int $page_number
): bool

フィールドの外観 (すなわち、/AP キーの値) を設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

field_name

face

FDFNormalAP、FDFRolloverAP および FDFDownAP のいずれかが使用可能です。

filename

page_number

戻り値

成功した場合に true を、失敗した場合に false を返します。


FDF 文字エンコーディングを設定する

  • ≪ fdf_set_ap
  • fdf_set_file ≫
  • PHP Manual
  • FDF 関数
  • FDF 文字エンコーディングを設定する

fdf_set_encoding

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_encoding — FDF 文字エンコーディングを設定する

説明

fdf_set_encoding(resource $fdf_document, string $encoding): bool

FDF ドキュメントの文字エンコーディングを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

encoding

エンコーディング名。現在サポートしているのは "Shift-JIS"、"UHC"、 "GBK"、"BigFive" です。

空の文字列を指定すると、エンコーディングをデフォルトの PDFDocEncoding/Unicode スキームに設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。


FDF データを表示する PDF ドキュメントを設定する

  • ≪ fdf_set_encoding
  • fdf_set_flags ≫
  • PHP Manual
  • FDF 関数
  • FDF データを表示する PDF ドキュメントを設定する

fdf_set_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_file — FDF データを表示する PDF ドキュメントを設定する

説明

fdf_set_file(resource $fdf_document, string $url, string $target_frame = ?): bool

フォームの結果を表示する PDF ドキュメントとして、もとのフォームとは別のものを指定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

url

絶対 URL で指定する必要があります。

target_frame

このパラメータを使用して、ドキュメントを表示するフレームを指定します。 このパラメータのデフォルト値を fdf_set_target_frame() で指定することもできます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 FDF データを 2 番目のフォームに渡す

<?php
/* Adobe FDF の content type を設定します */
fdf_header();

/* fdf を開始します */
$fdf = fdf_create();

/* "foo" フィールドに、値 "bar" を設定します */
fdf_set_value($fdf, "foo", "bar");

/* "fdf_form.pdf" を使用して fdf を表示することをクライアントに通知します */
fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

/* fdf を出力します */
fdf_save($fdf);

/* 後始末を行います */
fdf_close($fdf);
?>

参考

  • fdf_get_file() - /F キーの値を得る
  • fdf_set_target_frame() - フォームの表示対象となるフレームを設定する


フィールドのフラグを設定する

  • ≪ fdf_set_file
  • fdf_set_javascript_action ≫
  • PHP Manual
  • FDF 関数
  • フィールドのフラグを設定する

fdf_set_flags

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_flags — フィールドのフラグを設定する

説明

fdf_set_flags(
resource $fdf_document,
string $fieldname,
int $whichFlags,
int $newFlags
): bool

指定したフィールドのフラグを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

whichFlags

newFlags

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_opt() - フィールドのオプションを設定する


フィールドの javascript アクションを設定する

  • ≪ fdf_set_flags
  • fdf_set_on_import_javascript ≫
  • PHP Manual
  • FDF 関数
  • フィールドの javascript アクションを設定する

fdf_set_javascript_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_javascript_action — フィールドの javascript アクションを設定する

説明

fdf_set_javascript_action(
resource $fdf_document,
string $fieldname,
int $trigger,
string $script
): bool

指定したフィールドの javascript アクションを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

trigger

script

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_submit_form_action() - フィールドの投稿フォームアクションを設定する


Acrobat が FDF をオープンした際に実行される javascript のコードを追加する

  • ≪ fdf_set_javascript_action
  • fdf_set_opt ≫
  • PHP Manual
  • FDF 関数
  • Acrobat が FDF をオープンした際に実行される javascript のコードを追加する

fdf_set_on_import_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_on_import_javascript — Acrobat が FDF をオープンした際に実行される javascript のコードを追加する

説明

fdf_set_on_import_javascript(resource $fdf_document, string $script, bool $before_data_import): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

参考

  • fdf_add_doc_javascript() - FDF ドキュメントに javascript コードを追加する
  • fdf_set_javascript_action() - フィールドの javascript アクションを設定する


フィールドのオプションを設定する

  • ≪ fdf_set_on_import_javascript
  • fdf_set_status ≫
  • PHP Manual
  • FDF 関数
  • フィールドのオプションを設定する

fdf_set_opt

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_opt — フィールドのオプションを設定する

説明

fdf_set_opt(
resource $fdf_document,
string $fieldname,
int $element,
string $str1,
string $str2
): bool

指定したフィールドのオプションを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

element

str1

str2

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_flags() - フィールドのフラグを設定する


/STATUS キーの値を設定する

  • ≪ fdf_set_opt
  • fdf_set_submit_form_action ≫
  • PHP Manual
  • FDF 関数
  • /STATUS キーの値を設定する

fdf_set_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_status — /STATUS キーの値を設定する

説明

fdf_set_status(resource $fdf_document, string $status): bool

/STATUS キーの値を設定します。 クライアントが FDF とともにステータスセットを受信すると、その内容を アラートボックスに表示します

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

status

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_get_status() - /STATUS キーの値を得る


フィールドの投稿フォームアクションを設定する

  • ≪ fdf_set_status
  • fdf_set_target_frame ≫
  • PHP Manual
  • FDF 関数
  • フィールドの投稿フォームアクションを設定する

fdf_set_submit_form_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_submit_form_action — フィールドの投稿フォームアクションを設定する

説明

fdf_set_submit_form_action(
resource $fdf_document,
string $fieldname,
int $trigger,
string $script,
int $flags
): bool

指定したフィールドの投稿フォームアクションを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

trigger

script

flags

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_set_javascript_action() - フィールドの javascript アクションを設定する


フォームの表示対象となるフレームを設定する

  • ≪ fdf_set_submit_form_action
  • fdf_set_value ≫
  • PHP Manual
  • FDF 関数
  • フォームの表示対象となるフレームを設定する

fdf_set_target_frame

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_target_frame — フォームの表示対象となるフレームを設定する

説明

fdf_set_target_frame(resource $fdf_document, string $frame_name): bool

fdf_save_file() で定義した PDF の結果を出力する 対象のフレームを設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

frame_name

フレーム名を表す文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_save_file()


フィールドの値を設定する

  • ≪ fdf_set_target_frame
  • fdf_set_version ≫
  • PHP Manual
  • FDF 関数
  • フィールドの値を設定する

fdf_set_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_value — フィールドの値を設定する

説明

fdf_set_value(
resource $fdf_document,
string $fieldname,
mixed $value,
int $isName = ?
): bool

指定したフィールドに値 value を設定します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

fieldname

FDF フィールド名を表す文字列。

value

このパラメータは、配列形式でない限り文字列で保存されます。 配列の場合は、配列のすべての要素が配列として保存されます。

isName

注意:

FDF ツールキットの古いバージョンでは、最後のパラメータは フィールドの値を PDF Name に変換する (= 1) か、PDF String に設定する (= 0) かを定義します。

ツールキットの現在のバージョン 5.0 では、もはやこのパラメータは 使用されません。互換性を確保するためにこのパラメータが オプションとして残されていますが、内部ではこのパラメータは無視されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_get_value() - フィールドの値を得る
  • fdf_remove_item() - フォームのターゲットフレームを設定する


FDF ファイルのバージョン番号を設定する

  • ≪ fdf_set_value
  • GnuPG ≫
  • PHP Manual
  • FDF 関数
  • FDF ファイルのバージョン番号を設定する

fdf_set_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_version — FDF ファイルのバージョン番号を設定する

説明

fdf_set_version(resource $fdf_document, string $version): bool

指定したドキュメントの FDF バージョンを version に設定します。

この拡張モジュールが提供する機能のうちのいくつかは、新しいバージョンの FDF でのみ動作します。

パラメータ

fdf_document

fdf_create()、 fdf_open() あるいは fdf_open_string() が返す FDF ドキュメントハンドル。

version

バージョンを表す文字列。 現在の FDF ツールキット 5.0 では、これは 1.2、 1.3 あるいは 1.4 となります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • fdf_get_version() - FDF API あるいはファイルのバージョンを取得する


GNU Privacy Guard

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
    • テキストへの署名
  • GnuPG 関数
    • gnupg_adddecryptkey — 復号のためのキーを追加する
    • gnupg_addencryptkey — 暗号化のためのキーを追加する
    • gnupg_addsignkey — 署名のためのキーを追加する
    • gnupg_cleardecryptkeys — 事前に復号のために設定されたすべてのキーを削除する
    • gnupg_clearencryptkeys — 事前に暗号化のために設定されたすべてのキーを削除する
    • gnupg_clearsignkeys — 事前に署名のために設定されたすべてのキーを削除する
    • gnupg_decrypt — 指定されたテキストを復号する
    • gnupg_decryptverify — 指定されたテキストを復号し、検証する
    • gnupg_deletekey — キーを削除する
    • gnupg_encrypt — 指定したテキストを暗号化する
    • gnupg_encryptsign — 指定したテキストを暗号化し、署名する
    • gnupg_export — キーをエクスポートする
    • gnupg_getengineinfo — 暗号化エンジンの情報を返す
    • gnupg_geterror — 関数が失敗した場合にエラー文字列を返す
    • gnupg_geterrorinfo — エラー情報を返す
    • gnupg_getprotocol — すべての操作で現在アクティブなプロトコルを返す
    • gnupg_gettrustlist — 信頼済みのアイテムを検索する
    • gnupg_import — キーをインポートする
    • gnupg_init — 接続を初期化する
    • gnupg_keyinfo — 指定したパターンに一致するすべてのキーについての情報を配列で返す
    • gnupg_listsignatures — キーの署名の一覧を返す
    • gnupg_setarmor — armor 形式を切り替える
    • gnupg_seterrormode — エラー報告モードを設定する
    • gnupg_setsignmode — 署名方式を設定する
    • gnupg_sign — 指定したテキストに署名する
    • gnupg_verify — 署名済みテキストを検証する


  • ≪ GnuPG
  • インストール/設定 ≫
  • PHP Manual
  • GnuPG
  • はじめに

はじめに

このモジュールにより、» gnupg を扱うことが可能となります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • GnuPG
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

この拡張モジュールには » gpgme library が必要です。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gnupg.


定義済み定数

GNUPG_SIG_MODE_NORMAL (int)
GNUPG_SIG_MODE_DETACH (int)
GNUPG_SIG_MODE_CLEAR (int)
GNUPG_VALIDITY_UNKNOWN (int)
GNUPG_VALIDITY_UNDEFINED (int)
GNUPG_VALIDITY_NEVER (int)
GNUPG_VALIDITY_MARGINAL (int)
GNUPG_VALIDITY_FULL (int)
GNUPG_VALIDITY_ULTIMATE (int)
GNUPG_PROTOCOL_OpenPGP (int)
GNUPG_PROTOCOL_CMS (int)
GNUPG_SIGSUM_VALID (int)
GNUPG_SIGSUM_GREEN (int)
GNUPG_SIGSUM_RED (int)
GNUPG_SIGSUM_KEY_REVOKED (int)
GNUPG_SIGSUM_KEY_EXPIRED (int)
GNUPG_SIGSUM_KEY_MISSING (int)
GNUPG_SIGSUM_SIG_EXPIRED (int)
GNUPG_SIGSUM_CRL_MISSING (int)
GNUPG_SIGSUM_CRL_TOO_OLD (int)
GNUPG_SIGSUM_BAD_POLICY (int)
GNUPG_SIGSUM_SYS_ERROR (int)
GNUPG_ERROR_WARNING (int)
GNUPG_ERROR_EXCEPTION (int)
GNUPG_ERROR_SILENT (int)


  • ≪ 定義済み定数
  • テキストへの署名 ≫
  • PHP Manual
  • GnuPG
  • 例

例

目次

  • テキストへの署名


テキストへの署名

この例は、指定したテキストに署名をします。

例1 gnupg での署名の例 (手続き型)

<?php
// gnupg を初期化します
$res = gnupg_init();
// 必須ではありません。Clearsign はデフォルト値です
gnupg_setsignmode($res,GNUPG_SIG_MODE_CLEAR);
// 署名のためのキーを、パスフレーズ 'test' で追加します
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
// 署名します
$signed = gnupg_sign($res,"just a test");
echo $signed;
?>

例2 gnupg での署名の例 (オブジェクト指向)

<?php
// 新しいクラス
$gnupg = new gnupg();
// 必須ではありません。Clearsign はデフォルト値です
$gnupg->setsignmode(gnupg::SIG_MODE_CLEAR);
// 署名のためのキーを、パスフレーズ 'test' で追加します
$gnupg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
// 署名します
$signed = $gnupg->sign("just a test");
echo $signed;
?>

例3 keylistiterator

この拡張モジュールでは、キーリングの内容を繰り返し処理することも可能です。

<?php
// 'example' にマッチするキーを抜き出して繰り返し処理をするイテレータを生成します
$iterator = new gnupg_keylistiterator("example");
foreach($iterator as $fingerprint => $userid){
echo $fingerprint." -> ".$userid."\n";
}
?>


GnuPG 関数

注意

この拡張モジュールは、現在のユーザーのキーリングを使用します。キーリングは、 通常は ~./.gnupg/ にあります。別の場所を指定するには、環境変数 GNUPGHOME にキーリングへのパスを格納します。その詳細な方法については putenv を参照ください。

キーを特定する設定項目を必要とする関数も存在します。この設定項目は、何らかの ユニークなキー (ユーザー ID、キー ID、フィンガープリント、...) を参照します。 このドキュメントでは、すべての例でフィンガープリントを使用しています。

注意:

ドキュメントで明示されている関数 (resource を用いるもの) を使う以外に、 gnupg オブジェクトによるオブジェクト指向型の方法を使うこともできます。

目次

  • gnupg_adddecryptkey — 復号のためのキーを追加する
  • gnupg_addencryptkey — 暗号化のためのキーを追加する
  • gnupg_addsignkey — 署名のためのキーを追加する
  • gnupg_cleardecryptkeys — 事前に復号のために設定されたすべてのキーを削除する
  • gnupg_clearencryptkeys — 事前に暗号化のために設定されたすべてのキーを削除する
  • gnupg_clearsignkeys — 事前に署名のために設定されたすべてのキーを削除する
  • gnupg_decrypt — 指定されたテキストを復号する
  • gnupg_decryptverify — 指定されたテキストを復号し、検証する
  • gnupg_deletekey — キーを削除する
  • gnupg_encrypt — 指定したテキストを暗号化する
  • gnupg_encryptsign — 指定したテキストを暗号化し、署名する
  • gnupg_export — キーをエクスポートする
  • gnupg_getengineinfo — 暗号化エンジンの情報を返す
  • gnupg_geterror — 関数が失敗した場合にエラー文字列を返す
  • gnupg_geterrorinfo — エラー情報を返す
  • gnupg_getprotocol — すべての操作で現在アクティブなプロトコルを返す
  • gnupg_gettrustlist — 信頼済みのアイテムを検索する
  • gnupg_import — キーをインポートする
  • gnupg_init — 接続を初期化する
  • gnupg_keyinfo — 指定したパターンに一致するすべてのキーについての情報を配列で返す
  • gnupg_listsignatures — キーの署名の一覧を返す
  • gnupg_setarmor — armor 形式を切り替える
  • gnupg_seterrormode — エラー報告モードを設定する
  • gnupg_setsignmode — 署名方式を設定する
  • gnupg_sign — 指定したテキストに署名する
  • gnupg_verify — 署名済みテキストを検証する


復号のためのキーを追加する

  • ≪ GnuPG 関数
  • gnupg_addencryptkey ≫
  • PHP Manual
  • GnuPG 関数
  • 復号のためのキーを追加する

gnupg_adddecryptkey

(PECL gnupg >= 0.5)

gnupg_adddecryptkey — 復号のためのキーを追加する

説明

gnupg_adddecryptkey(resource $identifier, string $fingerprint, string $passphrase): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

passphrase

パスフレーズ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_adddecryptkey() の例

<?php
$res = gnupg_init();
gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
?>

例2 オブジェクト指向の gnupg_adddecryptkey() の例

<?php
$gpg = new gnupg();
$gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
?>


暗号化のためのキーを追加する

  • ≪ gnupg_adddecryptkey
  • gnupg_addsignkey ≫
  • PHP Manual
  • GnuPG 関数
  • 暗号化のためのキーを追加する

gnupg_addencryptkey

(PECL gnupg >= 0.5)

gnupg_addencryptkey — 暗号化のためのキーを追加する

説明

gnupg_addencryptkey(resource $identifier, string $fingerprint): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_addencryptkey() の例

<?php
$res = gnupg_init();
gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
?>

例2 オブジェクト指向の gnupg_addencryptkey() の例

<?php
$gpg = new gnupg();
$gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
?>


署名のためのキーを追加する

  • ≪ gnupg_addencryptkey
  • gnupg_cleardecryptkeys ≫
  • PHP Manual
  • GnuPG 関数
  • 署名のためのキーを追加する

gnupg_addsignkey

(PECL gnupg >= 0.5)

gnupg_addsignkey — 署名のためのキーを追加する

説明

gnupg_addsignkey(resource $identifier, string $fingerprint, string $passphrase = ?): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

passphrase

パスフレーズ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_addsignkey() の例

<?php
$res = gnupg_init();
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
?>

例2 オブジェクト指向の gnupg_addsignkey() の例

<?php
$gpg = new gnupg();
$gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
?>


事前に復号のために設定されたすべてのキーを削除する

  • ≪ gnupg_addsignkey
  • gnupg_clearencryptkeys ≫
  • PHP Manual
  • GnuPG 関数
  • 事前に復号のために設定されたすべてのキーを削除する

gnupg_cleardecryptkeys

(PECL gnupg >= 0.5)

gnupg_cleardecryptkeys — 事前に復号のために設定されたすべてのキーを削除する

説明

gnupg_cleardecryptkeys(resource $identifier): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_cleardecryptkeys() の例

<?php
$res = gnupg_init();
gnupg_cleardecryptkeys($res);
?>

例2 オブジェクト指向の gnupg_cleardecryptkeys() の例

<?php
$gpg = new gnupg();
$gpg->cleardecryptkeys();
?>


事前に暗号化のために設定されたすべてのキーを削除する

  • ≪ gnupg_cleardecryptkeys
  • gnupg_clearsignkeys ≫
  • PHP Manual
  • GnuPG 関数
  • 事前に暗号化のために設定されたすべてのキーを削除する

gnupg_clearencryptkeys

(PECL gnupg >= 0.5)

gnupg_clearencryptkeys — 事前に暗号化のために設定されたすべてのキーを削除する

説明

gnupg_clearencryptkeys(resource $identifier): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_clearencryptkeys() の例

<?php
$res = gnupg_init();
gnupg_clearencryptkeys($res);
?>

例2 オブジェクト指向の gnupg_clearencryptkeys() の例

<?php
$gpg = new gnupg();
$gpg->clearencryptkeys();
?>


事前に署名のために設定されたすべてのキーを削除する

  • ≪ gnupg_clearencryptkeys
  • gnupg_decrypt ≫
  • PHP Manual
  • GnuPG 関数
  • 事前に署名のために設定されたすべてのキーを削除する

gnupg_clearsignkeys

(PECL gnupg >= 0.5)

gnupg_clearsignkeys — 事前に署名のために設定されたすべてのキーを削除する

説明

gnupg_clearsignkeys(resource $identifier): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_clearsignkeys() の例

<?php
$res = gnupg_init();
gnupg_clearsignkeys($res);
?>

例2 オブジェクト指向の gnupg_clearsignkeys() の例

<?php
$gpg = new gnupg();
$gpg->clearsignkeys();
?>


指定されたテキストを復号する

  • ≪ gnupg_clearsignkeys
  • gnupg_decryptverify ≫
  • PHP Manual
  • GnuPG 関数
  • 指定されたテキストを復号する

gnupg_decrypt

(PECL gnupg >= 0.1)

gnupg_decrypt — 指定されたテキストを復号する

説明

gnupg_decrypt(resource $identifier, string $text): string|false

事前に gnupg_adddecryptkey で設定されたキーを使用し、指定されたテキストを復号します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

text

復号したいテキスト。

戻り値

成功した場合、この関数は復号されたテキストを返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_decrypt() の例

<?php
$res = gnupg_init();
gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$plain = gnupg_decrypt($res,$encrypted_text);
echo $plain;
?>

例2 オブジェクト指向の gnupg_decrypt() の例

<?php
$gpg = new gnupg();
$gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$plain = $gpg->decrypt($encrypted_text);
echo $plain;
?>


指定されたテキストを復号し、検証する

  • ≪ gnupg_decrypt
  • gnupg_deletekey ≫
  • PHP Manual
  • GnuPG 関数
  • 指定されたテキストを復号し、検証する

gnupg_decryptverify

(PECL gnupg >= 0.2)

gnupg_decryptverify — 指定されたテキストを復号し、検証する

説明

gnupg_decryptverify(resource $identifier, string $text, string &$plaintext): array|false

指定したテキストを復号・検証し、署名の情報を返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

text

復号したいテキスト。

plaintext

plaintext には復号したテキストが格納されます。

戻り値

成功した場合、この関数は署名の情報を返し、復号されたテキストを plaintext に保存します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_decryptverify() の例

<?php
$plaintext = "";
$res = gnupg_init();
gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$info = gnupg_decryptverify($res,$text,$plaintext);
print_r($info);
?>

例2 オブジェクト指向の gnupg_decryptverify() の例

<?php
$plaintext = "";
$gpg = new gnupg();
$gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$info = $gpg->decryptverify($text,$plaintext);
print_r($info);
?>


キーを削除する

  • ≪ gnupg_decryptverify
  • gnupg_encrypt ≫
  • PHP Manual
  • GnuPG 関数
  • キーを削除する

gnupg_deletekey

(PECL gnupg >= 0.5)

gnupg_deletekey — キーを削除する

説明

gnupg_deletekey(resource $identifier, string $key, bool $allow_secret): bool

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

key

削除するキー。

allow_secret

秘密鍵も同時に削除するかどうかを指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_deletekey() の例

<?php
$res = gnupg_init();
gnupg_deletekey($res, "8660281B6051D071D94B5B230549F9DC851566DC");
?>

例2 オブジェクト指向の gnupg_deletekey() の例

<?php
$gpg = new gnupg();
$gpg->deletekey("8660281B6051D071D94B5B230549F9DC851566DC");
?>


指定したテキストを暗号化する

  • ≪ gnupg_deletekey
  • gnupg_encryptsign ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したテキストを暗号化する

gnupg_encrypt

(PECL gnupg >= 0.1)

gnupg_encrypt — 指定したテキストを暗号化する

説明

gnupg_encrypt(resource $identifier, string $plaintext): string|false

事前に gnupg_addencryptkey で設定したキーを使用し、指定されたテキストを暗号化します。暗号化された テキストを返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

plaintext

暗号化したいテキスト。

戻り値

成功した場合、この関数は暗号化されたテキストを返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_encrypt() の例

<?php
$res = gnupg_init();
gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
$enc = gnupg_encrypt($res, "just a test");
echo $enc;
?>

例2 オブジェクト指向の gnupg_encrypt() の例

<?php
$gpg = new gnupg();
$gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
$enc = $gpg->encrypt("just a test");
echo $enc;
?>


指定したテキストを暗号化し、署名する

  • ≪ gnupg_encrypt
  • gnupg_export ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したテキストを暗号化し、署名する

gnupg_encryptsign

(PECL gnupg >= 0.2)

gnupg_encryptsign — 指定したテキストを暗号化し、署名する

説明

gnupg_encryptsign(resource $identifier, string $plaintext): string|false

事前に gnupg_addsignkey および gnupg_addencryptkey で設定したキーを使用し、指定した plaintext を暗号化・署名します。暗号化・署名済みのテキストを返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

plaintext

暗号化したいテキスト。

戻り値

成功した場合、この関数は暗号化されて署名されたテキストを返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_encryptsign() の例

<?php
$res = gnupg_init();
gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$enc = gnupg_encryptsign($res, "just a test");
echo $enc;
?>

例2 オブジェクト指向の gnupg_encryptsign() の例

<?php
$gpg = new gnupg();
$gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
$gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$enc = $gpg->encryptsign("just a test");
echo $enc;
?>


キーをエクスポートする

  • ≪ gnupg_encryptsign
  • gnupg_getengineinfo ≫
  • PHP Manual
  • GnuPG 関数
  • キーをエクスポートする

gnupg_export

(PECL gnupg >= 0.1)

gnupg_export — キーをエクスポートする

説明

gnupg_export(resource $identifier, string $fingerprint): string|false

キーの fingerprint をエクスポートします。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

fingerprint

フィンガープリントキー。

戻り値

成功した場合、この関数はキーのデータを返します。 失敗した場合、この関数は false を返します。

例

例1 Procedural gnupg_export() example

<?php
$res = gnupg_init();
$export = gnupg_export($res,"8660281B6051D071D94B5B230549F9DC851566DC");
echo $export;
?>

例2 OO gnupg_export() example

<?php
$gpg = new gnupg();
$export = $gpg->export("8660281B6051D071D94B5B230549F9DC851566DC");
?>


暗号化エンジンの情報を返す

  • ≪ gnupg_export
  • gnupg_geterror ≫
  • PHP Manual
  • GnuPG 関数
  • 暗号化エンジンの情報を返す

gnupg_getengineinfo

(PECL gnupg >= 1.5)

gnupg_getengineinfo — 暗号化エンジンの情報を返す

説明

gnupg_getengineinfo(resource $identifier): array

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

暗号化エンジンの情報を配列で返します。 これは、 protocol, file_name, home_dir からなります。

例

例1 手続き型 gnupg_getengineinfo() の例

<?php
$res = gnupg_init();
print_r(gnupg_getengineinfo($res));
?>

上の例の出力は以下となります。

array(3) {
  ["protocol"]=>
  int(0)
  ["file_name"]=>
  string(12) "/usr/bin/gpg"
  ["home_dir"]=>
  string(0) ""
}

例2 オブジェクト指向 gnupg_getengineinfo() の例

<?php
$gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
print_r($gpg->getengineinfo());
?>

上の例の出力は以下となります。

array(3) {
  ["protocol"]=>
  int(0)
  ["file_name"]=>
  string(13) "/usr/bin/gpg2"
  ["home_dir"]=>
  string(15) "/var/www/.gnupg"
}


関数が失敗した場合にエラー文字列を返す

  • ≪ gnupg_getengineinfo
  • gnupg_geterrorinfo ≫
  • PHP Manual
  • GnuPG 関数
  • 関数が失敗した場合にエラー文字列を返す

gnupg_geterror

(PECL gnupg >= 0.1)

gnupg_geterror — 関数が失敗した場合にエラー文字列を返す

説明

gnupg_geterror(resource $identifier): string|false

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

エラーが発生した場合にエラー文字列、それ以外の場合に false を返します。

例

例1 手続き型の gnupg_geterror() の例

<?php
$res = gnupg_init();
echo gnupg_geterror($res);
?>

例2 オブジェクト指向の gnupg_geterror() の例

<?php
$gpg = new gnupg();
echo $gpg->geterror();
?>


エラー情報を返す

  • ≪ gnupg_geterror
  • gnupg_getprotocol ≫
  • PHP Manual
  • GnuPG 関数
  • エラー情報を返す

gnupg_geterrorinfo

(PECL gnupg >= 1.5)

gnupg_geterrorinfo — エラー情報を返す

説明

gnupg_geterrorinfo(resource $identifier): array

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

エラー情報が含まれる配列を返します。

例

例1 手続き型 gnupg_geterrorinfo() の例

<?php
$res = gnupg_init();
// this is called without any error
print_r(gnupg_geterrorinfo($res));
?>

上の例の出力は以下となります。

array(4) {
  ["generic_message"]=>
  bool(false)
  ["gpgme_code"]=>
  int(0)
  ["gpgme_source"]=>
  string(18) "Unspecified source"
  ["gpgme_message"]=>
  string(7) "Success"
}

例2 オブジェクト指向型 gnupg_geterrorinfo() の例

<?php
$gpg = new gnupg();
// error call
$gpg->decrypt('abc');
// error info should be displayed
print_r($gpg->geterrorinfo());
?>

上の例の出力は以下となります。

array(4) {
  ["generic_message"]=>
  string(14) "decrypt failed"
  ["gpgme_code"]=>
  int(117440570)
  ["gpgme_source"]=>
  string(5) "GPGME"
  ["gpgme_message"]=>
  string(7) "No data"
}


すべての操作で現在アクティブなプロトコルを返す

  • ≪ gnupg_geterrorinfo
  • gnupg_gettrustlist ≫
  • PHP Manual
  • GnuPG 関数
  • すべての操作で現在アクティブなプロトコルを返す

gnupg_getprotocol

(PECL gnupg >= 0.1)

gnupg_getprotocol — すべての操作で現在アクティブなプロトコルを返す

説明

gnupg_getprotocol(resource $identifier): int

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

戻り値

現在アクティブなプロトコルを返します。結果は GNUPG_PROTOCOL_OpenPGP あるいは GNUPG_PROTOCOL_CMS のいずれかとなります。

例

例1 手続き型の gnupg_getprotocol() の例

<?php
$res = gnupg_init();
echo gnupg_getprotocol($res);
?>

例2 オブジェクト指向の gnupg_getprotocol() の例

<?php
$gpg = new gnupg();
echo $gpg->getprotocol();
?>


信頼済みのアイテムを検索する

  • ≪ gnupg_getprotocol
  • gnupg_import ≫
  • PHP Manual
  • GnuPG 関数
  • 信頼済みのアイテムを検索する

gnupg_gettrustlist

(PECL gnupg >= 0.5)

gnupg_gettrustlist — 信頼済みのアイテムを検索する

説明

gnupg_gettrustlist(resource $identifier, string $pattern): ?array

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

pattern

パターンにマッチした、 信頼済みアイテムに絞り込むための式。

戻り値

成功時には、信頼済みアイテムの配列を返します。 失敗した場合は、null を返します。

例

例1 手続き型の gnupg_gettrustlist() の例

<?php
$res = gnupg_init();
$items = gnupg_gettrustlist($res);
print_r($items);
?>

例2 オブジェクト指向の gnupg_gettrustlist() の例

<?php
$gpg = new gnupg();
$items = $gpg->gettrustlist();
print_r($items);
?>


キーをインポートする

  • ≪ gnupg_gettrustlist
  • gnupg_init ≫
  • PHP Manual
  • GnuPG 関数
  • キーをインポートする

gnupg_import

(PECL gnupg >= 0.3)

gnupg_import — キーをインポートする

説明

gnupg_import(resource $identifier, string $keydata): array|false

キー keydata をインポートし、インポート処理に ついての情報を配列で返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

keydata

インポートしたいキーのデータ。

戻り値

成功した場合、この関数はインポート処理の情報を配列で返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_import() の例

<?php
$res = gnupg_init();
$info = gnupg_import($res,$keydata);
print_r($info);
?>

例2 オブジェクト指向の gnupg_import() の例

<?php
$gpg = new gnupg();
$info = $gpg->import($keydata);
print_r($info);
?>


接続を初期化する

  • ≪ gnupg_import
  • gnupg_keyinfo ≫
  • PHP Manual
  • GnuPG 関数
  • 接続を初期化する

gnupg_init

(PECL gnupg >= 0.4)

gnupg_init — 接続を初期化する

説明

gnupg_init(?array $options = null): resource

パラメータ

options

連想配列でなければいけません。 暗号化エンジンのデフォルト設定を変更するために使います。

設定の上書きオプション
キー | 型 | 説明
file_name | string | このプロトコルを実装した、実行可能なプログラムのファイル名。 通常は gpg のパスです。
home_dir | string | 設定ディレクトリのディレクトリ名です。 この値は、同じ目的で使う環境変数 GNUPGHOME も上書きします。

戻り値

GnuPG 接続リソースを返します。これを他の GnuPG 関数で使用します。

変更履歴

バージョン | 説明
1.5.0 | 引数 options が追加されました。

例

例1 デフォルト値を使った、手続き型の gnupg_init() の例

<?php
$res = gnupg_init();
?>

例2 ファイル名とホームディレクトリを上書きした、手続き型の gnupg_init() の例

<?php
$res = gnupg_init(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
?>

例3 デフォルト値を使い、オブジェクト指向型のインターフェイスで gnupg を初期化する例

<?php
$gpg = new gnupg();
?>

例4 ファイル名とホームディレクトリを上書きし、オブジェクト指向型のインターフェイスで gnupg を初期化する例

<?php
$gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
?>


指定したパターンに一致するすべてのキーについての情報を配列で返す

  • ≪ gnupg_init
  • gnupg_listsignatures ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したパターンに一致するすべてのキーについての情報を配列で返す

gnupg_keyinfo

(PECL gnupg >= 0.1)

gnupg_keyinfo — 指定したパターンに一致するすべてのキーについての情報を配列で返す

説明

gnupg_keyinfo(resource $identifier, string $pattern): array|false

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

pattern

キーに対してチェックを行いたいパターン。

戻り値

指定したパターンに一致するすべてのキーについての情報を配列で返します。 エラーが発生した場合は false を返します。

例

例1 手続き型の gnupg_keyinfo() の例

<?php
$res = gnupg_init();
$info = gnupg_keyinfo($res, 'test');
print_r($info);
?>

例2 オブジェクト指向の gnupg_keyinfo() の例

<?php
$gpg = new gnupg();
$info = $gpg->keyinfo("test");
print_r($info);
?>


キーの署名の一覧を返す

  • ≪ gnupg_keyinfo
  • gnupg_setarmor ≫
  • PHP Manual
  • GnuPG 関数
  • キーの署名の一覧を返す

gnupg_listsignatures

(PECL gnupg >= 0.5)

gnupg_listsignatures — キーの署名の一覧を返す

説明

gnupg_listsignatures(resource $identifier, string $keyid): ?array

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

keyid

署名の一覧を得るためのキーID。

戻り値

成功時には、キーの署名の配列を返します。 失敗時には、null を返します。

例

例1 手続き型の gnupg_listsignatures() の例

<?php
$res = gnupg_init();
$signatures = gnupg_listsignatures($res, "8660281B6051D071D94B5B230549F9DC851566DC");
print_r($signatures);
?>

例2 オブジェクト指向の gnupg_listsignatures() の例

<?php
$gpg = new gnupg();
$signatures = $gpg->listsignatures("8660281B6051D071D94B5B230549F9DC851566DC");
print_r($signatures);
?>


armor 形式を切り替える

  • ≪ gnupg_listsignatures
  • gnupg_seterrormode ≫
  • PHP Manual
  • GnuPG 関数
  • armor 形式を切り替える

gnupg_setarmor

(PECL gnupg >= 0.1)

gnupg_setarmor — armor 形式を切り替える

説明

gnupg_setarmor(resource $identifier, int $armor): bool

armor 形式の出力を切り替えます。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

armor

ゼロ以外の整数値をこの関数に渡すと、armor 形式の出力を有効にします (デフォルト)。 0 を渡すと、armor 形式の出力を無効にします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_setarmor() の例

<?php
$res = gnupg_init();
gnupg_setarmor($res,1); // enable armored output;
gnupg_setarmor($res,0); // disable armored output;
?>

例2 オブジェクト指向の gnupg_setarmor() の例

<?php
$gpg = new gnupg();
$gpg->setarmor(1); // enable armored output;
$gpg->setarmor(0); // disable armored output;
?>


エラー報告モードを設定する

  • ≪ gnupg_setarmor
  • gnupg_setsignmode ≫
  • PHP Manual
  • GnuPG 関数
  • エラー報告モードを設定する

gnupg_seterrormode

(PECL gnupg >= 0.6)

gnupg_seterrormode — エラー報告モードを設定する

説明

gnupg_seterrormode(resource $identifier, int $errormode): void

error_reporting のモードを設定します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

errormode

エラー形式。

errormode には、 使用するエラー報告形式を表す定数を指定します。 GNUPG_ERROR_WARNING、 GNUPG_ERROR_EXCEPTION および GNUPG_ERROR_SILENT が使用可能です。 デフォルトでは GNUPG_ERROR_SILENT が使用されます。

戻り値

値を返しません。

例

例1 手続き型の gnupg_seterrormode() の例

<?php
$res = gnupg_init();
gnupg_seterrormode($res,GNUPG_ERROR_WARNING); // エラー時には PHP の警告を発生させます
?>

例2 オブジェクト指向の gnupg_seterrormode() の例

<?php
$gpg = new gnupg();
$gpg->seterrormode(gnupg::ERROR_EXCEPTION); // エラー時には例外をスローします
?>


署名方式を設定する

  • ≪ gnupg_seterrormode
  • gnupg_sign ≫
  • PHP Manual
  • GnuPG 関数
  • 署名方式を設定する

gnupg_setsignmode

(PECL gnupg >= 0.1)

gnupg_setsignmode — 署名方式を設定する

説明

gnupg_setsignmode(resource $identifier, int $signmode): bool

署名方式を設定します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

sigmode

署名の形式。

signmode には、 作成する署名の形式を表す定数を指定します。 GNUPG_SIG_MODE_NORMAL、 GNUPG_SIG_MODE_DETACH および GNUPG_SIG_MODE_CLEAR が使用可能です。 デフォルトでは GNUPG_SIG_MODE_CLEAR が使用されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 手続き型の gnupg_setsignmode() の例

<?php
$res = gnupg_init();
gnupg_setsignmode($res,GNUPG_SIG_MODE_DETACH); // 独立した署名を作成します
?>

例2 オブジェクト指向の gnupg_setsignmode() の例

<?php
$gpg = new gnupg();
$gpg->setsignmode(gnupg::SIG_MODE_DETACH); // 独立した署名を作成します
?>


指定したテキストに署名する

  • ≪ gnupg_setsignmode
  • gnupg_verify ≫
  • PHP Manual
  • GnuPG 関数
  • 指定したテキストに署名する

gnupg_sign

(PECL gnupg >= 0.1)

gnupg_sign — 指定したテキストに署名する

説明

gnupg_sign(resource $identifier, string $plaintext): string|false

事前に gnupg_addsignkey で設定したキーを使用して plaintext に署名し、 gnupg_setsignmode の設定に応じて署名済みテキストあるいは署名を返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

plaintext

署名したい平文テキスト。

戻り値

成功した場合、この関数は署名済みテキストあるいは署名を返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_sign() の例

<?php
$res = gnupg_init();
gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
$signed = gnupg_sign($res, "just a test");
echo $signed;
?>

例2 オブジェクト指向の gnupg_sign() の例

<?php
$gpg = new gnupg();
$gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
$signed = $gpg->sign("just a test");
echo $signed;
?>


署名済みテキストを検証する

  • ≪ gnupg_sign
  • wkhtmltox ≫
  • PHP Manual
  • GnuPG 関数
  • 署名済みテキストを検証する

gnupg_verify

(PECL gnupg >= 0.1)

gnupg_verify — 署名済みテキストを検証する

説明

gnupg_verify(
resource $identifier,
string $signed_text,
string $signature,
string &$plaintext = ?
): array|false

指定した signed_text を検証し、署名についての情報を返します。

パラメータ

identifier

gnupg_init() あるいは gnupg のコールで得られた gnupg ID。

signed_text

The signed text.

signature

署名。clearsign で署名されたテキストを検証するには、 signature に false を設定します。

plaintext

平文テキスト。 このオプションのパラメータを渡すと、 復号されたテキストがそこに保存されます。

戻り値

成功した場合、この関数は署名についての情報を返します。 失敗した場合、この関数は false を返します。

例

例1 手続き型の gnupg_verify() の例

<?php
$plaintext = "";
$res = gnupg_init();
// clearsigned
$info = gnupg_verify($res,$signed_text,false,$plaintext);
print_r($info);
// detached signature
$info = gnupg_verify($res,$signed_text,$signature);
print_r($info);
?>

例2 オブジェクト指向の gnupg_verify() の例

<?php
$plaintext = "";
$gpg = new gnupg();
// clearsigned
$info = $gpg->verify($signed_text,false,$plaintext);
print_r($info);
// detached signature
$info = $gpg->verify($signed_text,$signature);
print_r($info);
?>


wkhtmltox

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • wkhtmltox\PDF\Converter — wkhtmltox\PDF\Converter クラス
    • wkhtmltox\PDF\Converter::add — Add an object for conversion
    • wkhtmltox\PDF\Converter::__construct — Create a new PDF converter
    • wkhtmltox\PDF\Converter::convert — Perform PDF conversion
    • wkhtmltox\PDF\Converter::getVersion — Determine version of Converter
  • wkhtmltox\PDF\Object — The wkhtmltox\PDF\Object class
    • wkhtmltox\PDF\Object::__construct — Create a new PDF Object
  • wkhtmltox\Image\Converter — wkhtmltox\Image\Converter クラス
    • wkhtmltox\Image\Converter::__construct — Create a new Image converter
    • wkhtmltox\Image\Converter::convert — Perform Image conversion
    • wkhtmltox\Image\Converter::getVersion — Determine version of Converter


はじめに

libwkhtmltox は、QtWebKit レンダリングエンジンを使用して、HTML を PDF やさまざまな画像フォーマットにレンダリングするためのオープンソースの LGPLv3 ライブラリです。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • wkhtmltox
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

libwkhtmltox のソースとバイナリリリースは » wkhtmltopdf.org で配布されています。

警告

Windows ユーザーは wkhtmltox.dll を PATH に追加するさらなる手順を実行する必要があります。


インストール手順

この拡張モジュールのソースコードと Windows 用バイナリは » github でホストされています。

ソースコードの取得と拡張モジュールのビルド：

git clone https://github.com/krakjoe/wkhtmltox
cd wkhtmltox
phpize
./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
make
sudo make install

更新の取得と拡張モジュールの再ビルド：

cd wkhtmltox
phpize --clean
git pull origin master
phpize
./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
make
sudo make install


実行時設定

名前 | 説明 | デフォルト | ステージ | 変更履歴
wkhtmltox.graphics | libwkhtmltox にグラフィックの使用を許可する | Off | INI_SYSTEM|INI_PERDIR | >= 0.3.2


wkhtmltox\PDF\Converter クラス

(wkhtmltox >= 0.1.0)

はじめに

一件あるいは一組のHTML入力をPDF出力に変換する

クラス概要

class wkhtmltox\PDF\Converter {
/* コンストラクタ */
public __construct(array $settings = ?)
/* メソッド */
public add(wkhtmltox\PDF\Object $object): void
public convert(): ?string
public getVersion(): string
}

目次

  • wkhtmltox\PDF\Converter::add — Add an object for conversion
  • wkhtmltox\PDF\Converter::__construct — Create a new PDF converter
  • wkhtmltox\PDF\Converter::convert — Perform PDF conversion
  • wkhtmltox\PDF\Converter::getVersion — Determine version of Converter


Add an object for conversion

  • ≪ wkhtmltox\PDF\Converter
  • wkhtmltox\PDF\Converter::__construct ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Add an object for conversion

wkhtmltox\PDF\Converter::add

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::add — Add an object for conversion

説明

public wkhtmltox\PDF\Converter::add(wkhtmltox\PDF\Object $object): void

Adds the given object to conversion

パラメータ

object

The object to add


Create a new PDF converter

  • ≪ wkhtmltox\PDF\Converter::add
  • wkhtmltox\PDF\Converter::convert ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Create a new PDF converter

wkhtmltox\PDF\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::__construct — Create a new PDF converter

説明

public wkhtmltox\PDF\Converter::__construct(array $settings = ?)

Creates a PDF converter, using optional configuration settings

パラメータ

settings

Name | Description | Values | Changelog
size.pageSize | paper size of output document | A4 | >= 0.1.0
size.width | with of the output document | 210mm | >= 0.1.0
size.height | height of the output document | 297mm | >= 0.1.0
orientation orientation of the output document
Landscape
Portrait
>= 0.1.0
colorMode color mode of the output document
Color
Greyscale
>= 0.1.0
resolution | resoluition of the output document | most likely has no effect | >= 0.1.0
dpi | dpi to use while printing | 80 | >= 0.1.0
pageOffset | integer added to page numbers generating headers, footers, and toc | >= 0.1.0
copies | >= 0.1.0
collate | collate copies | boolean | >= 0.1.0
outline | generate PDF outline | boolean | >= 0.1.0
outlineDepth | maximum depth of outline | >= 0.1.0
dumpOutline | path of file to dump outline XML | >= 0.1.0
out | path of output file, if "-" stdout is used | >= 0.1.0
documentTitle | title for the output document | >= 0.1.0
useCompression | enable or disable lossless compression | boolean | >= 0.1.0
margin.top | size of the top margin | 2cm | >= 0.1.0
margin.bottom | size of the bottom margin | 2cm | >= 0.1.0
margin.left | size of the left margin | 2cm | >= 0.1.0
margin.right | size of the right margin | 2cm | >= 0.1.0
imageDPI | maximum DPI for images in the output document | >= 0.1.0
imageQuality | the jpeg compression factor for images in the output document | 94 | >= 0.1.0
load.cookieJar | path of file used to load and store cookies | /tmp/cookies.txt | >= 0.1.0


Perform PDF conversion

  • ≪ wkhtmltox\PDF\Converter::__construct
  • wkhtmltox\PDF\Converter::getVersion ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Perform PDF conversion

wkhtmltox\PDF\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::convert — Perform PDF conversion

説明

public wkhtmltox\PDF\Converter::convert(): ?string

Performs conversion of all previously added Objects

パラメータ

この関数にはパラメータはありません。

戻り値

Where the return value is used, it will be populated with the contents of the conversion buffer


Determine version of Converter

  • ≪ wkhtmltox\PDF\Converter::convert
  • wkhtmltox\PDF\Object ≫
  • PHP Manual
  • wkhtmltox\PDF\Converter
  • Determine version of Converter

wkhtmltox\PDF\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\PDF\Converter::getVersion — Determine version of Converter

説明

public wkhtmltox\PDF\Converter::getVersion(): string

Determines the version of Converter as reported by libwkhtmltox

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a version string


The wkhtmltox\PDF\Object class

(wkhtmltox >= 0.1.0)

はじめに

Represents an HTML document, input to PDF converter

クラス概要

class wkhtmltox\PDF\Object {
/* Constructor */
public __construct(string $buffer, array $settings = ?)
}

目次

  • wkhtmltox\PDF\Object::__construct — Create a new PDF Object


Create a new PDF Object

  • ≪ wkhtmltox\PDF\Object
  • wkhtmltox\Image\Converter ≫
  • PHP Manual
  • wkhtmltox\PDF\Object
  • Create a new PDF Object

wkhtmltox\PDF\Object::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Object::__construct — Create a new PDF Object

説明

public wkhtmltox\PDF\Object::__construct(string $buffer, array $settings = ?)

Creates a new PDF Object from the given buffer and optional configuration settings

パラメータ

buffer

HTML

settings

Name | Description | Values | Changelog
page | URL or path of the HTML to convert | >= 0.1.0
useExternalLinks | set true to convert external links in the input into external PDF links in the output | boolean | >= 0.1.0
useLocalLinks | set true to convert internal links in the input into internal PDF links in the output | boolean | >= 0.1.0
produceForms | set true to turn HTML forms into PDF forms | boolean | >= 0.1.0
replacements | undocumented | >= 0.1.0
includeInOutline | set true to include sections from this object in the outline and toc | boolean | >= 0.1.0
pagesCount | set true to make page count in toc inclusive of the number of pages in this object | boolean | >= 0.1.0
tocXsl | set to style sheet to convert this object into a toc object | >= 0.1.0
toc.useDottedLines | set true to use dotted lines in toc | boolean | >= 0.1.0
toc.captionText | the caption text for toc | >= 0.1.0
toc.forwardLinks | set true to create links from toc to content | boolean | >= 0.1.0
toc.backLinks | set true to create links from content to toc | boolean | >= 0.1.0
toc.indentation | indentation for toc | 2em | >= 0.1.0
toc.fontScale | the factor to scale down the font at every toc level | 0.8 | >= 0.1.0
header.fontSize | font size for use in header | 13 | >= 0.1.0
header.fontName | name of font for use in header | times | >= 0.1.0
header.left | text for left of header | >= 0.1.0
header.center | text for center of header | >= 0.1.0
header.right | text for right of header | >= 0.1.0
header.line | enable or disable horizontal rule under header | boolean | >= 0.1.0
header.spacing | space between header and content | 1.8 | >= 0.1.0
header.htmlUrl | URL or path of HTML to use in header | >= 0.1.0
footer.fontSize | font size for use in footer | 13 | >= 0.1.0
footer.fontName | name of font for use in footer | times | >= 0.1.0
footer.left | text for left of footer | >= 0.1.0
footer.center | text for center of footer | >= 0.1.0
footer.right | text for right of footer | >= 0.1.0
footer.line | enable or disable horizontal rule under footer | boolean | >= 0.1.0
footer.spacing | space between footer and content | 1.8 | >= 0.1.0
footer.htmlUrl | URL or path of HTML to use in footer | >= 0.1.0
load.username | user name to use when loging into a website | bart | >= 0.1.0
load.password | the password to used when logging into a website | elbarto | >= 0.1.0
load.jsdelay | the amount of time in milliseconds to wait after a page is loaded until it is captured | 1200 | >= 0.1.0
load.zoomFactor | how much zoom should be applied to the content | 2.2 | >= 0.1.0
load.customHeaders | custom headers to send when requesting the main web page | >= 0.1.0
load.repertCustomHeaders | set true to send with all requests | boolean | >= 0.1.0
load.cookies | cookie string to send when requesting the main web page | >= 0.1.0
load.post | post string to send when requesting the main web page | >= 0.1.0
load.blockLocalFileAccess | disallow local and piped files to access other local files | boolean | >= 0.1.0
load.stopSlowScript | stop slow running javascript | boolean
load.debugJavascript | allow javascript to raise warnings | boolean | >= 0.1.0
load.loadErrorHandling set error handling strategy
abort | abort the convertion process
skip | do not add the object to the final output
ignore | try to add the object to the final output
>= 0.1.0
load.proxy | >= 0.1.0
web.background | include background image in output | boolean | >= 0.1.0
web.loadImages | include images in output | boolean | >= 0.1.0
web.enableJavascript | enable or disable javascript | boolean | >= 0.1.0
web.enableIntelligentShrinking | enable to attempt to fit more content on page, only applies to PDF output | boolean | >= 0.1.0
web.minimumFontSize | the minimum font size allowed | 9 | >= 0.1.0
web.printMediaType | print content using print media type instead of screen media type | boolean | >= 0.1.0
web.defaultEncoding | content to use where no encoding is specified | utf-8 | >= 0.1.0
web.userStyleSheet | URL or path to a user specified style sheet | /path/to/style.css | >= 0.1.0
web.enablePlugins | enable or disable NS plugins | boolean | >= 0.1.0


wkhtmltox\Image\Converter クラス

(wkhtmltox >= 0.1.0)

はじめに

HTML入力をさまざまな画像形式に変換する

クラス概要

class wkhtmltox\Image\Converter {
/* コンストラクタ */
public __construct(string $buffer = ?, array $settings = ?)
/* メソッド */
public convert(): ?string
public getVersion(): string
}

目次

  • wkhtmltox\Image\Converter::__construct — Create a new Image converter
  • wkhtmltox\Image\Converter::convert — Perform Image conversion
  • wkhtmltox\Image\Converter::getVersion — Determine version of Converter


Create a new Image converter

  • ≪ wkhtmltox\Image\Converter
  • wkhtmltox\Image\Converter::convert ≫
  • PHP Manual
  • wkhtmltox\Image\Converter
  • Create a new Image converter

wkhtmltox\Image\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::__construct — Create a new Image converter

説明

public wkhtmltox\Image\Converter::__construct(string $buffer = ?, array $settings = ?)

Creates an Image converter, optionally taking an input buffer and configuration settings

パラメータ

buffer

HTML

settings

Name | Description | Values | Changelog
in | URL or path of the input file, if "-" stdin is used | /path/to/markup.html | >= 0.1.0
out | path of output file, if "-" stdout is used, by default an internal buffer is used | /path/to/output.png | >= 0.1.0
fmt output format to use
"" default
jpg | output as JPEG
png | output as PNG
bmp | output as bitmap
svg | output as SVG
>= 0.1.0
transparent | when outputting a PNG or SVG, make the white background transparent | boolean | >= 0.1.0
screenWidth | the with of the screen used to render in pixels | 800 | >= 0.1.0
smartWidth | when true, screenWidth is expanded to the content width | boolean | >= 0.1.0
quality | compression factor to use when outputting a JPEG image | 94 | >= 0.1.0
crop.left | left/x coordinate of the window to capture in pixels | 200 | >= 0.1.0
crop.top | top/y coordinate of the window to capture in pixels | 200 | >= 0.1.0
crop.width | width of the window to capture in pixels | 200 | >= 0.1.0
crop.height | height of the window to capture in pixels | 200 | >= 0.1.0
load.cookieJar | path of file used to load and store cookies | /tmp/cookies.txt | >= 0.1.0
load.username | user name to use when loging into a website | bart | >= 0.1.0
load.password | the password to used when logging into a website | elbarto | >= 0.1.0
load.jsdelay | the amount of time in milliseconds to wait after a page is loaded until it is captured | 1200 | >= 0.1.0
load.zoomFactor | how much zoom should be applied to the content | 2.2 | >= 0.1.0
load.customHeaders | custom headers to send when requesting the main web page | >= 0.1.0
load.repertCustomHeaders | set true to send with all requests | boolean | >= 0.1.0
load.cookies | cookie string to send when requesting the main web page | >= 0.1.0
load.post | post string to send when requesting the main web page | >= 0.1.0
load.blockLocalFileAccess | disallow local and piped files to access other local files | boolean | >= 0.1.0
load.stopSlowScript | stop slow running javascript | boolean
load.debugJavascript | allow javascript to raise warnings | boolean | >= 0.1.0
load.loadErrorHandling set error handling strategy
abort | abort the convertion process
skip | do not add the object to the final output
ignore | try to add the object to the final output
>= 0.1.0
load.proxy | >= 0.1.0
web.background | include background image in output | boolean | >= 0.1.0
web.loadImages | include images in output | boolean | >= 0.1.0
web.enableJavascript | enable or disable javascript | boolean | >= 0.1.0
web.enableIntelligentShrinking | enable to attempt to fit more content on page, only applies to PDF output | boolean | >= 0.1.0
web.minimumFontSize | the minimum font size allowed | 9 | >= 0.1.0
web.printMediaType | print content using print media type instead of screen media type | boolean | >= 0.1.0
web.defaultEncoding | content to use where no encoding is specified | utf-8 | >= 0.1.0
web.userStyleSheet | URL or path to a user specified style sheet | /path/to/style.css | >= 0.1.0
web.enablePlugins | enable or disable NS plugins | boolean | >= 0.1.0


Perform Image conversion

  • ≪ wkhtmltox\Image\Converter::__construct
  • wkhtmltox\Image\Converter::getVersion ≫
  • PHP Manual
  • wkhtmltox\Image\Converter
  • Perform Image conversion

wkhtmltox\Image\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::convert — Perform Image conversion

説明

public wkhtmltox\Image\Converter::convert(): ?string

Performs conversion of the input buffer

パラメータ

この関数にはパラメータはありません。

戻り値

Where the return value is used, it will be populated with the contents of the conversion buffer


Determine version of Converter

  • ≪ wkhtmltox\Image\Converter::convert
  • PS ≫
  • PHP Manual
  • wkhtmltox\Image\Converter
  • Determine version of Converter

wkhtmltox\Image\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\Image\Converter::getVersion — Determine version of Converter

説明

public wkhtmltox\Image\Converter::getVersion(): string

Determines the version of Converter as reported by libwkhtmltox

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a version string

警告

This is not yet implemented by libwkhtmltox


PostScript ドキュメントの作成

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • PS 関数
    • ps_add_bookmark — 現在のページにブックマークを追加する
    • ps_add_launchlink — ファイルを実行するためのリンクを追加する
    • ps_add_locallink — 同一ドキュメント内のページへのリンクを追加する
    • ps_add_note — 現在のページに注釈を追加する
    • ps_add_pdflink — 別の PDF ドキュメントのページへのリンクを追加する
    • ps_add_weblink — Web 上の場所へのリンクを追加する
    • ps_arc — 反時計回りに円弧を描く
    • ps_arcn — 時計回りに円弧を描く
    • ps_begin_page — 新しいページを開始する
    • ps_begin_pattern — 新しいパターンを開始する
    • ps_begin_template — 新しいテンプレートを開始する
    • ps_circle — 円を描く
    • ps_clip — 現在のパスを描画範囲として指定する
    • ps_close — PostScript ドキュメントを閉じる
    • ps_close_image — 画像を閉じ、メモリを開放する
    • ps_closepath — パスを閉じる
    • ps_closepath_stroke — パスを閉じ、描画する
    • ps_continue_text — 次の行にテキストを続ける
    • ps_curveto — 曲線を描く
    • ps_delete — PostScript ドキュメントの全リソースを削除する
    • ps_end_page — ページを終了する
    • ps_end_pattern — パターンを終了する
    • ps_end_template — テンプレートを終了する
    • ps_fill — 現在のパスを塗りつぶす
    • ps_fill_stroke — 現在のパスを塗りつぶし、線を引く
    • ps_findfont — フォントを読み込む
    • ps_get_buffer — 生成された PS データを含むバッファの内容を取得する
    • ps_get_parameter — パラメータを取得する
    • ps_get_value — 値を取得する
    • ps_hyphenate — 単語をハイフネーションする
    • ps_include_file — 外部ファイルを生の PostScript コードとして読み込む
    • ps_lineto — 直線を描く
    • ps_makespotcolor — スポット色を作成する
    • ps_moveto — 現在位置を設定する
    • ps_new — 新しい PostScript ドキュメントオブジェクトを作成する
    • ps_open_file — 出力用のファイルを開く
    • ps_open_image — 後で配置するために画像を読み込む
    • ps_open_image_file — ファイルから画像を開く
    • ps_open_memory_image — GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す
    • ps_place_image — 画像をページに配置する
    • ps_rect — 矩形を描く
    • ps_restore — 以前に保存されたコンテキストを復元する
    • ps_rotate — 回転の程度を設定する
    • ps_save — 現在のコンテキストを保存する
    • ps_scale — 縮尺を設定する
    • ps_set_border_color — 注記の枠線の色を設定する
    • ps_set_border_dash — 注記の枠線の、破線の状態を設定する
    • ps_set_border_style — 注記の枠線の形式を設定する
    • ps_set_info — ドキュメントの情報を設定する
    • ps_set_parameter — パラメータを設定する
    • ps_set_text_pos — テキストの出力位置を設定する
    • ps_set_value — 値を設定する
    • ps_setcolor — 色を設定する
    • ps_setdash — 破線の形状を設定する
    • ps_setflat — 平面度を設定する
    • ps_setfont — 以降の出力で用いるフォントを設定する
    • ps_setgray — グレー値を設定する
    • ps_setlinecap — 線端の形状を設定する
    • ps_setlinejoin — 線の連結方法を設定する
    • ps_setlinewidth — 線幅を設定する
    • ps_setmiterlimit — miter limit 値を設定する
    • ps_setoverprintmode — overprint モードを設定する
    • ps_setpolydash — 破線の形状を設定する
    • ps_shading — 以降の出力で用いるシェーディングを作成する
    • ps_shading_pattern — シェーディング用のパターンを作成する
    • ps_shfill — 範囲をシェーディングで塗りつぶす
    • ps_show — テキストを出力する
    • ps_show_boxed — テキストをボックス内に出力する
    • ps_show_xy — 指定された位置にテキストを出力する
    • ps_show_xy2 — テキストを指定した位置に出力する
    • ps_show2 — テキストを現在の位置に出力する
    • ps_string_geometry — 文字列のジオメトリを取得する
    • ps_stringwidth — 文字列の幅を取得する
    • ps_stroke — 現在のパスを描画する
    • ps_symbol — グリフを出力する
    • ps_symbol_name — グリフ名を取得する
    • ps_symbol_width — グリフの幅を取得する
    • ps_translate — 座標変換を設定する


はじめに

このモジュールは、PostScript ドキュメントを作成するためのものです。 PDF 拡張と多くの共通点を持っています。実際のところ API はほぼ同じで、 多くは関数名の最初の pdf_ を ps_ に変えるだけで使えます。 PostScript ドキュメントには直接関係のない機能（ハイパーリンクの追加など） も含まれていますが、これらは PostScript ドキュメントを PDF に変換した場合に有効となります。

この拡張によって作られたドキュメントは、いくつかの点で pdf 拡張に よって作られたドキュメントより優れています。なぜなら pslib のレンダリング関数はカーニングやハイフネーション、そしてリゲチャに対応しており、 よりよい出力が得られるからです。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • PS
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

少なくとも pslib >= 0.1.12 が必要です。 ps ライブラリ（pslib）は、 » http://pslib.sourceforge.net/ にあります。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ps.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


リソース型

この拡張モジュールでは PostScript ドキュメントリソースを定義しています。これは ps_new() が返すものです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下の 2 つの表は、ps 拡張で定義されている定数の一覧です。

線端の形状をあらわす定数
名前 | 意味
ps_LINECAP_BUTT |
ps_LINECAP_ROUND |
ps_LINECAP_SQUARED |
線の連結方法をあらわす定数
名前 | 意味
ps_LINEJOIN_MITER |
ps_LINEJOIN_ROUND |
ps_LINEJOIN_BEVEL |


PS 関数

連絡先

もしこの拡張や pslib についての意見・バグフィックス・機能拡張などがあれば、 私 » steinm@php.net にメールをください。お待ちしています。

目次

  • ps_add_bookmark — 現在のページにブックマークを追加する
  • ps_add_launchlink — ファイルを実行するためのリンクを追加する
  • ps_add_locallink — 同一ドキュメント内のページへのリンクを追加する
  • ps_add_note — 現在のページに注釈を追加する
  • ps_add_pdflink — 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink — Web 上の場所へのリンクを追加する
  • ps_arc — 反時計回りに円弧を描く
  • ps_arcn — 時計回りに円弧を描く
  • ps_begin_page — 新しいページを開始する
  • ps_begin_pattern — 新しいパターンを開始する
  • ps_begin_template — 新しいテンプレートを開始する
  • ps_circle — 円を描く
  • ps_clip — 現在のパスを描画範囲として指定する
  • ps_close — PostScript ドキュメントを閉じる
  • ps_close_image — 画像を閉じ、メモリを開放する
  • ps_closepath — パスを閉じる
  • ps_closepath_stroke — パスを閉じ、描画する
  • ps_continue_text — 次の行にテキストを続ける
  • ps_curveto — 曲線を描く
  • ps_delete — PostScript ドキュメントの全リソースを削除する
  • ps_end_page — ページを終了する
  • ps_end_pattern — パターンを終了する
  • ps_end_template — テンプレートを終了する
  • ps_fill — 現在のパスを塗りつぶす
  • ps_fill_stroke — 現在のパスを塗りつぶし、線を引く
  • ps_findfont — フォントを読み込む
  • ps_get_buffer — 生成された PS データを含むバッファの内容を取得する
  • ps_get_parameter — パラメータを取得する
  • ps_get_value — 値を取得する
  • ps_hyphenate — 単語をハイフネーションする
  • ps_include_file — 外部ファイルを生の PostScript コードとして読み込む
  • ps_lineto — 直線を描く
  • ps_makespotcolor — スポット色を作成する
  • ps_moveto — 現在位置を設定する
  • ps_new — 新しい PostScript ドキュメントオブジェクトを作成する
  • ps_open_file — 出力用のファイルを開く
  • ps_open_image — 後で配置するために画像を読み込む
  • ps_open_image_file — ファイルから画像を開く
  • ps_open_memory_image — GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す
  • ps_place_image — 画像をページに配置する
  • ps_rect — 矩形を描く
  • ps_restore — 以前に保存されたコンテキストを復元する
  • ps_rotate — 回転の程度を設定する
  • ps_save — 現在のコンテキストを保存する
  • ps_scale — 縮尺を設定する
  • ps_set_border_color — 注記の枠線の色を設定する
  • ps_set_border_dash — 注記の枠線の、破線の状態を設定する
  • ps_set_border_style — 注記の枠線の形式を設定する
  • ps_set_info — ドキュメントの情報を設定する
  • ps_set_parameter — パラメータを設定する
  • ps_set_text_pos — テキストの出力位置を設定する
  • ps_set_value — 値を設定する
  • ps_setcolor — 色を設定する
  • ps_setdash — 破線の形状を設定する
  • ps_setflat — 平面度を設定する
  • ps_setfont — 以降の出力で用いるフォントを設定する
  • ps_setgray — グレー値を設定する
  • ps_setlinecap — 線端の形状を設定する
  • ps_setlinejoin — 線の連結方法を設定する
  • ps_setlinewidth — 線幅を設定する
  • ps_setmiterlimit — miter limit 値を設定する
  • ps_setoverprintmode — overprint モードを設定する
  • ps_setpolydash — 破線の形状を設定する
  • ps_shading — 以降の出力で用いるシェーディングを作成する
  • ps_shading_pattern — シェーディング用のパターンを作成する
  • ps_shfill — 範囲をシェーディングで塗りつぶす
  • ps_show — テキストを出力する
  • ps_show_boxed — テキストをボックス内に出力する
  • ps_show_xy — 指定された位置にテキストを出力する
  • ps_show_xy2 — テキストを指定した位置に出力する
  • ps_show2 — テキストを現在の位置に出力する
  • ps_string_geometry — 文字列のジオメトリを取得する
  • ps_stringwidth — 文字列の幅を取得する
  • ps_stroke — 現在のパスを描画する
  • ps_symbol — グリフを出力する
  • ps_symbol_name — グリフ名を取得する
  • ps_symbol_width — グリフの幅を取得する
  • ps_translate — 座標変換を設定する


現在のページにブックマークを追加する

  • ≪ PS 関数
  • ps_add_launchlink ≫
  • PHP Manual
  • PS 関数
  • 現在のページにブックマークを追加する

ps_add_bookmark

(PECL ps >= 1.1.0)

ps_add_bookmark — 現在のページにブックマークを追加する

説明

ps_add_bookmark(
resource $psdoc,
string $text,
int $parent = 0,
int $open = 0
): int

現在のページにブックマークを追加します。たいてい、ブックマークは PDFビューア上でページの左側にツリー形式で表示されます。 ブックマークをクリックすると、該当ページにジャンプします。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

ブックマークの表示に使用するテキスト。

parent

新しいブックマークの親となる、 事前にこの関数で作成されたブックマーク。

open

open がゼロでない場合、ブックマークは PDF ビューア上で開いた形で表示されます。

戻り値

戻り値はブックマークへの参照です。この値は、作成したブックマークを 他のブックマークの親として使用する場合にのみ使われます。 成功した場合には、この値はゼロより大きくなります。 エラーが発生した場合にはゼロを返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する


ファイルを実行するためのリンクを追加する

  • ≪ ps_add_bookmark
  • ps_add_locallink ≫
  • PHP Manual
  • PS 関数
  • ファイルを実行するためのリンクを追加する

ps_add_launchlink

(PECL ps >= 1.1.0)

ps_add_launchlink — ファイルを実行するためのリンクを追加する

説明

ps_add_launchlink(
resource $psdoc,
float $llx,
float $lly,
float $urx,
float $ury,
string $filename
): bool

クリックした際にファイルが実行されるハイパーリンクを、 指定した場所に設定します。ハイパーリンクのリンク元は矩形で表され、 その左下の座標は (llx, lly)、そして右上の座標が (urx, ury) となります。 この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

filename

リンクがクリックされた際に開始するプログラムのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する


同一ドキュメント内のページへのリンクを追加する

  • ≪ ps_add_launchlink
  • ps_add_note ≫
  • PHP Manual
  • PS 関数
  • 同一ドキュメント内のページへのリンクを追加する

ps_add_locallink

(PECL ps >= 1.1.0)

ps_add_locallink — 同一ドキュメント内のページへのリンクを追加する

説明

ps_add_locallink(
resource $psdoc,
float $llx,
float $lly,
float $urx,
float $ury,
int $page,
string $dest
): bool

指定した位置に、同一ドキュメント内のページへのハイパーリンクを設定します。 リンクをクリックすると、そのページに移動します。ドキュメントの最初の ページのページ番号は 1 です。

ハイパーリンクのリンク元は矩形で表され、その左下の座標は (llx, lly)、 そして右上の座標が (urx, ury) となります。この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

page

リンクがクリックされた際に開始するページ。

dest

dest は、ドキュメントがどのように 表示されるかを指定します。とりうる値は fitpage または fitwidth、 fitheight、fitbbox のいずれかです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する


現在のページに注釈を追加する

  • ≪ ps_add_locallink
  • ps_add_pdflink ≫
  • PHP Manual
  • PS 関数
  • 現在のページに注釈を追加する

ps_add_note

(PECL ps >= 1.1.0)

ps_add_note — 現在のページに注釈を追加する

説明

ps_add_note(
resource $psdoc,
float $llx,
float $lly,
float $urx,
float $ury,
string $contents,
string $title,
string $icon,
int $open
): bool

ページの特定の位置に注釈を追加します。注釈は、 テキストが記入された小さな矩形で、ページ上のどこにでも配置できます。 折りたたんで保持することもでき、折りたたまれている場合は、 指定したアイコンをプレースホルダとして使います。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

contents

注釈のテキスト。

title

注釈のヘッダに表示される、タイトル。

icon

注釈が折りたたまれた際に表示されるアイコン。 comment、insert、 note、paragraph、 newparagraph、key あるいは help のいずれかが設定できます。

open

open がゼロでない場合、 PDF ビューア上でドキュメントをオープンすると、 注釈は折りたたまれずに表示されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する
  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する


別の PDF ドキュメントのページへのリンクを追加する

  • ≪ ps_add_note
  • ps_add_weblink ≫
  • PHP Manual
  • PS 関数
  • 別の PDF ドキュメントのページへのリンクを追加する

ps_add_pdflink

(PECL ps >= 1.1.0)

ps_add_pdflink — 別の PDF ドキュメントのページへのリンクを追加する

説明

ps_add_pdflink(
resource $psdoc,
float $llx,
float $lly,
float $urx,
float $ury,
string $filename,
int $page,
string $dest
): bool

指定した位置に、別の PDF ドキュメントへのハイパーリンクを設定します。 リンクをクリックすると、そのドキュメントの指定されたページに移動します。 ドキュメントの最初のページのページ番号は 1 です。

ハイパーリンクのリンク元は矩形で表され、その左下の座標は (llx, lly)、 そして右上の座標が (urx, ury) となります。この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

filename

リンクがクリックされた際に開かれる PDF ドキュメントの名前。

page

対象 PDF ドキュメントのページ番号。

dest

dest は、ドキュメントがどのように 表示されるかを指定します。とりうる値は fitpage または fitwidth、 fitheight、fitbbox のいずれかです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_weblink() - Web 上の場所へのリンクを追加する


Web 上の場所へのリンクを追加する

  • ≪ ps_add_pdflink
  • ps_arc ≫
  • PHP Manual
  • PS 関数
  • Web 上の場所へのリンクを追加する

ps_add_weblink

(PECL ps >= 1.1.0)

ps_add_weblink — Web 上の場所へのリンクを追加する

説明

ps_add_weblink(
resource $psdoc,
float $llx,
float $lly,
float $urx,
float $ury,
string $url
): bool

指定した位置に、Web ページを指すハイパーリンクを設定します。 ハイパーリンクのリンク元は矩形で表され、その左下の座標は (llx, lly)、 そして右上の座標が (urx, ury) となります。 この矩形はデフォルトでは細い青線で表されます。

注釈は、 ドキュメントを印刷したり表示したりするときには表示されません。 しかし、Acrobat Distiller? あるいは Ghostview でドキュメントを pdf に変換すると表示されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

llx

左下角の x 座標。

lly

左下角の y 座標。

urx

右上角の x 座標。

ury

右上角の y 座標。

url

リンクがクリックされた際に開かれるハイパーリンクの URL。 例えば http://www.php.net

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_add_launchlink() - ファイルを実行するためのリンクを追加する
  • ps_add_locallink() - 同一ドキュメント内のページへのリンクを追加する
  • ps_add_pdflink() - 別の PDF ドキュメントのページへのリンクを追加する


反時計回りに円弧を描く

  • ≪ ps_add_weblink
  • ps_arcn ≫
  • PHP Manual
  • PS 関数
  • 反時計回りに円弧を描く

ps_arc

(PECL ps >= 1.1.0)

ps_arc — 反時計回りに円弧を描く

説明

ps_arc(
resource $psdoc,
float $x,
float $y,
float $radius,
float $alpha,
float $beta
): bool

(x, y) を中心とした円の一部を描きます。円弧は alpha で指定された角度からはじまり beta で指定された角度で終わります。反時計回りに描かれます (時計回りに描くには ps_arcn() を使用します)。 また、alpha で指定された角度からはじまって beta で指定された角度で終わるサブパスが、 現在のパスに追加されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

円の中心の x 座標。

y

円の中心の y 座標。

radius

円の半径。

alpha

開始位置の角度を度単位で指定。

beta

終了位置の角度を度単位で指定。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arcn() - 時計回りに円弧を描く


時計回りに円弧を描く

  • ≪ ps_arc
  • ps_begin_page ≫
  • PHP Manual
  • PS 関数
  • 時計回りに円弧を描く

ps_arcn

(PECL ps >= 1.1.0)

ps_arcn — 時計回りに円弧を描く

説明

ps_arcn(
resource $psdoc,
float $x,
float $y,
float $radius,
float $alpha,
float $beta
): bool

(x, y) を中心とした円の一部を描きます。円弧は alpha で指定された角度からはじまり beta で指定された角度で終わります。 時計回りに描かれます (反時計回りに描くには ps_arc() を使用します)。 また、beta で指定された角度からはじまって alpha で指定された角度で終わるサブパスが、カレントパスに追加されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

円の中心の x 座標。

y

円の中心の y 座標。

radius

円の半径。

alpha

開始位置の角度を度単位で指定。

beta

終了位置の角度を度単位で指定。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arc() - 反時計回りに円弧を描く


新しいページを開始する

  • ≪ ps_arcn
  • ps_begin_pattern ≫
  • PHP Manual
  • PS 関数
  • 新しいページを開始する

ps_begin_page

(PECL ps >= 1.1.0)

ps_begin_page — 新しいページを開始する

説明

ps_begin_page(resource $psdoc, float $width, float $height): bool

新しいページを開始します。width や height というパラメータを見ると いかにもページ単位でサイズを変えられるように思えますが、PostScript ではこれは不可能です。最初に ps_begin_page() を呼んだ際に指定されたサイズが、ドキュメント全体に適用されます。 2 回目以降に呼ばれた場合はこのパラメータは意味を持たず、 単に新しいページが作られるだけです。しかし、もしあなたが PostScript ドキュメントを PDF に変換しようと考えているのなら話は別です。 この関数はドキュメントの各ページごとに pdfmark を設定するので、 PDF に変換した後はページごとにサイズを変えることができます。

PostScript はさまざまなページサイズを知らないので、pslib ではドキュメントの各ページに対してバウンディングボックスを設定します。 このサイズは PostScript ビューアによって評価され、 ドキュメントヘッダの BoundingBox より優先されます。 左下角が (0, 0) ではない BoundingBox を設定すると、 予期せぬ結果を引き起こすことがあります。なぜなら、 ページ単位のバウンディングボックスは常に左下角が (0, 0) であり、 これが全体の設定より優先されるからです。

個々のページの情報はカプセル化して保存されています。どういうことかというと、 あるページで設定した情報のほとんどは次のページに引き継がれないということです。

最初の ps_begin_page() 呼び出しまでに一度も ps_findfont() が呼び出されていなかった場合は、 PostScript ドキュメントのヘッダが出力され、 バウンディングボックスが最初のページのサイズに設定されます。 バウンディングボックスの左下角は (0, 0) に設定されます。もしすでに ps_findfont() が呼ばれていた場合は既にヘッダが出力されてしまっており、 ドキュメントに適切なバウンディングボックスが設定されていないことになります。 このようなことを避けるために、ps_findfont() や ps_begin_page() を実行する前にはいつも ps_set_info() を実行し、 BoundingBox や Orientation の値を設定しておくべきです。

注意:

pslib のバージョン 0.2.6 まででは、 ps_set_info() によって事前に設定されていたり ps_findfont() が事前にコールされていない限り、 この関数は常に BoundingBox および Orientation を上書きします。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

ピクセル単位のページの幅 (例: A4 の場合は 596)。

height

ピクセル単位のページの高さ (例: A4 の場合は 842)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_end_page() - ページを終了する
  • ps_findfont() - フォントを読み込む
  • ps_set_info() - ドキュメントの情報を設定する


新しいパターンを開始する

  • ≪ ps_begin_page
  • ps_begin_template ≫
  • PHP Manual
  • PS 関数
  • 新しいパターンを開始する

ps_begin_pattern

(PECL ps >= 1.2.0)

ps_begin_pattern — 新しいパターンを開始する

説明

ps_begin_pattern(
resource $psdoc,
float $width,
float $height,
float $xstep,
float $ystep,
int $painttype
): int|false

新しいパターンを開始します。パターンとは、 領域を塗りつぶすための描画データを含むページのようなものです。 ps_setcolor() をコールする際に pattern に色空間を指定すると、 これは色のように使用されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

ピクセル単位のパターンの幅。

height

ピクセル単位のパターンの高さ。

x-step

パターンを水平方向に並べる際のピクセル単位の間隔。

y-step

パターンを垂直方向に並べる際のピクセル単位の間隔。

painttype

1 あるいは 2 でなければなりません。

戻り値

パターンの ID を返します。失敗した場合に false を返します。

例

例1 パターンの作成および使用

<?php
$ps = ps_new();

if (!ps_open_file($ps, "pattern.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_parameter($ps, "warning", "true");
ps_set_info($ps, "Creator", "pattern.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Pattern example");

$pspattern = ps_begin_pattern($ps, 10.0, 10.0, 10.0, 10.0, 1);
ps_setlinewidth($ps, 0.2);
ps_setcolor($ps, "stroke", "rgb", 0.0, 0.0, 1.0, 0.0);
ps_moveto($ps, 0, 0);
ps_lineto($ps, 7, 7);
ps_stroke($ps);
ps_moveto($ps, 0, 7);
ps_lineto($ps, 7, 0);
ps_stroke($ps);
ps_end_pattern($ps);

ps_begin_page($ps, 596, 842);
ps_setcolor($ps, "both", "pattern", $pspattern, 0.0, 0.0, 0.0);
ps_rect($ps, 50, 400, 200, 200);
ps_fill($ps);
ps_end_page($ps);

ps_close($ps);
ps_delete($ps);
?>

参考

  • ps_end_pattern() - パターンを終了する
  • ps_setcolor() - 色を設定する
  • ps_shading_pattern() - シェーディング用のパターンを作成する


新しいテンプレートを開始する

  • ≪ ps_begin_pattern
  • ps_circle ≫
  • PHP Manual
  • PS 関数
  • 新しいテンプレートを開始する

ps_begin_template

(PECL ps >= 1.2.0)

ps_begin_template — 新しいテンプレートを開始する

説明

ps_begin_template(resource $psdoc, float $width, float $height): int

新しいテンプレートを開始します。テンプレートは、postscript 言語からコールされます。パターンと似ていますが、画像のように使用されます。 テンプレートは、ドキュメント内で何回も使用される描画内容、 例えば会社のロゴなどに対して使用されることが多いでしょう。 テンプレート内では、すべての描画関数が使用されます。 テンプレートは、ps_place_image() によって配置されるまでは描画されません。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

ピクセル単位のテンプレートの幅。

height

ピクセル単位のテンプレートの高さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 テンプレートの作成および使用

<?php
$ps = ps_new();

if (!ps_open_file($ps, "template.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_parameter($ps, "warning", "true");
ps_set_info($ps, "Creator", "template.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Template example");

$pstemplate = ps_begin_template($ps, 30.0, 30.0);
ps_moveto($ps, 0, 0);
ps_lineto($ps, 30, 30);
ps_moveto($ps, 0, 30);
ps_lineto($ps, 30, 0);
ps_stroke($ps);
ps_end_template($ps);

ps_begin_page($ps, 596, 842);
ps_place_image($ps, $pstemplate, 20.0, 20.0, 1.0);
ps_place_image($ps, $pstemplate, 50.0, 30.0, 0.5);
ps_place_image($ps, $pstemplate, 70.0, 70.0, 0.6);
ps_place_image($ps, $pstemplate, 30.0, 50.0, 1.3);
ps_end_page($ps);

ps_close($ps);
ps_delete($ps);
?>

参考

  • ps_end_template() - テンプレートを終了する


円を描く

  • ≪ ps_begin_template
  • ps_clip ≫
  • PHP Manual
  • PS 関数
  • 円を描く

ps_circle

(PECL ps >= 1.1.0)

ps_circle — 円を描く

説明

ps_circle(
resource $psdoc,
float $x,
float $y,
float $radius
): bool

(x, y) を中心とする円を描きます。描画開始位置は (x+radius, y) です。もしパスの外部でこの関数が呼び出された場合、 新しいパスを開始します。パスの内部で呼び出された場合は、 円をサブパスとして追加します。ひとつ前の描画処理の終点が (x+radius, y) でなかった場合、パスに隙間ができることになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

円の中心の x 座標。

y

円の中心の y 座標。

radius

円の半径。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arc() - 反時計回りに円弧を描く
  • ps_arcn() - 時計回りに円弧を描く


現在のパスを描画範囲として指定する

  • ≪ ps_circle
  • ps_close ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを描画範囲として指定する

ps_clip

(PECL ps >= 1.1.0)

ps_clip — 現在のパスを描画範囲として指定する

説明

ps_clip(resource $psdoc): bool

現在のパスを、描画範囲の境界として定義します。 この領域の外に描画された内容は、見えなくなります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_closepath() - パスを閉じる


PostScript ドキュメントを閉じる

  • ≪ ps_clip
  • ps_close_image ≫
  • PHP Manual
  • PS 関数
  • PostScript ドキュメントを閉じる

ps_close

(PECL ps >= 1.1.0)

ps_close — PostScript ドキュメントを閉じる

説明

ps_close(resource $psdoc): bool

PostScript ドキュメントを閉じます。

この関数は、PostScript ドキュメントのトレーラーを書き込みます。 また、ブックマークツリーも書き込みます。ps_close() は、リソースの開放は行いません。これは ps_delete() が行います。

もし事前にコールされていない場合、この関数は ps_delete() からもコールされます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_open_file() - 出力用のファイルを開く
  • ps_delete() - PostScript ドキュメントの全リソースを削除する


画像を閉じ、メモリを開放する

  • ≪ ps_close
  • ps_closepath ≫
  • PHP Manual
  • PS 関数
  • 画像を閉じ、メモリを開放する

ps_close_image

(PECL ps >= 1.1.0)

ps_close_image — 画像を閉じ、メモリを開放する

説明

ps_close_image(resource $psdoc, int $imageid): void|false

画像を閉じ、そのリソースを開放します。 いったん閉じられた後は、画像を使用することはできません。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

imageid

ps_open_image() あるいは ps_open_image_file() が返す、 画像のリソース ID。

戻り値

成功した場合に null を、失敗した場合に false を返します。

参考

  • ps_open_image() - 後で配置するために画像を読み込む
  • ps_open_image_file() - ファイルから画像を開く


パスを閉じる

  • ≪ ps_close_image
  • ps_closepath_stroke ≫
  • PHP Manual
  • PS 関数
  • パスを閉じる

ps_closepath

(PECL ps >= 1.1.0)

ps_closepath — パスを閉じる

説明

ps_closepath(resource $psdoc): bool

パスの終了点と開始点をつなげます。出来上がったパスは、 描画、塗りつぶし、切り取りなどに使用されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_clip() - 現在のパスを描画範囲として指定する
  • ps_closepath_stroke() - パスを閉じ、描画する


パスを閉じ、描画する

  • ≪ ps_closepath
  • ps_continue_text ≫
  • PHP Manual
  • PS 関数
  • パスを閉じ、描画する

ps_closepath_stroke

(PECL ps >= 1.1.0)

ps_closepath_stroke — パスを閉じ、描画する

説明

ps_closepath_stroke(resource $psdoc): bool

パスの終了点を開始点とつなげ、出来上がった線を描画します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_closepath() - パスを閉じる


次の行にテキストを続ける

  • ≪ ps_closepath_stroke
  • ps_curveto ≫
  • PHP Manual
  • PS 関数
  • 次の行にテキストを続ける

ps_continue_text

(PECL ps >= 1.1.0)

ps_continue_text — 次の行にテキストを続ける

説明

ps_continue_text(resource $psdoc, string $text): bool

最終行の次の行からテキストを出力します。行間隔は "leading" の値が用いられます。この値は ps_set_value() を用いて指定する必要があります。 実際のテキストの出力位置は、"textx" と "texty" の値によって決まります。 この値は ps_get_value() を用いて取得することができます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

出力するテキスト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_show() - テキストを出力する
  • ps_show_xy() - 指定された位置にテキストを出力する
  • ps_show_boxed() - テキストをボックス内に出力する


曲線を描く

  • ≪ ps_continue_text
  • ps_delete ≫
  • PHP Manual
  • PS 関数
  • 曲線を描く

ps_curveto

(PECL ps >= 1.1.0)

ps_curveto — 曲線を描く

説明

ps_curveto(
resource $psdoc,
float $x1,
float $y1,
float $x2,
float $y2,
float $x3,
float $y3
): bool

現在のパスに対して、3 つの制御点を指定して 3 次ベジエ曲線を追加します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x1

最初の制御点の x 座標。

y1

最初の制御点の y 座標。

x2

2 番目の制御点の x 座標。

y2

2 番目の制御点の y 座標。

x3

3 番目の制御点の x 座標。

y3

3 番目の制御点の y 座標。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_lineto() - 直線を描く


PostScript ドキュメントの全リソースを削除する

  • ≪ ps_curveto
  • ps_end_page ≫
  • PHP Manual
  • PS 関数
  • PostScript ドキュメントの全リソースを削除する

ps_delete

(PECL ps >= 1.1.0)

ps_delete — PostScript ドキュメントの全リソースを削除する

説明

ps_delete(resource $psdoc): bool

ドキュメントが使用していたメモリを開放します。また、 もし事前に ps_close() でファイルが閉じられていない場合はファイルを閉じます。 どんな場合でも、事前に ps_close() でファイルを閉じておくべきです。なぜなら ps_close() はファイルをただ閉じるだけではなく、トレーラーを出力するからです。 ここには、ドキュメントのページ数やブックマーク階層といった情報が含まれます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_close() - PostScript ドキュメントを閉じる


ページを終了する

  • ≪ ps_delete
  • ps_end_pattern ≫
  • PHP Manual
  • PS 関数
  • ページを終了する

ps_end_page

(PECL ps >= 1.1.0)

ps_end_page — ページを終了する

説明

ps_end_page(resource $psdoc): bool

ps_begin_page() によって開始したページを終了します。 ページを終了しても、現在の描画コンテキストはそのままになります。つまり、 もしページ内部でフォントが読み込まれたのなら、 それを再読み込みしてしなければなりません。 また、行の幅や色などのその他の描画パラメータも再設定する必要があります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_begin_page() - 新しいページを開始する


パターンを終了する

  • ≪ ps_end_page
  • ps_end_template ≫
  • PHP Manual
  • PS 関数
  • パターンを終了する

ps_end_pattern

(PECL ps >= 1.2.0)

ps_end_pattern — パターンを終了する

説明

ps_end_pattern(resource $psdoc): bool

ps_begin_pattern() によって開始したパターンを終了します。 パターンが終了すると、領域の塗りつぶし時にそれを使用できるようになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_begin_pattern() - 新しいパターンを開始する


テンプレートを終了する

  • ≪ ps_end_pattern
  • ps_fill ≫
  • PHP Manual
  • PS 関数
  • テンプレートを終了する

ps_end_template

(PECL ps >= 1.2.0)

ps_end_template — テンプレートを終了する

説明

ps_end_template(resource $psdoc): bool

ps_begin_template() によって開始したテンプレートを終了します。 テンプレートが終了すると、それを画像のように使用できるようになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_begin_template() - 新しいテンプレートを開始する


現在のパスを塗りつぶす

  • ≪ ps_end_template
  • ps_fill_stroke ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを塗りつぶす

ps_fill

(PECL ps >= 1.1.0)

ps_fill — 現在のパスを塗りつぶす

説明

ps_fill(resource $psdoc): bool

ps_lineto() のような描画関数によって事前に作成されたパスを塗りつぶします。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_fill_stroke() - 現在のパスを塗りつぶし、線を引く
  • ps_stroke() - 現在のパスを描画する


現在のパスを塗りつぶし、線を引く

  • ≪ ps_fill
  • ps_findfont ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを塗りつぶし、線を引く

ps_fill_stroke

(PECL ps >= 1.1.0)

ps_fill_stroke — 現在のパスを塗りつぶし、線を引く

説明

ps_fill_stroke(resource $psdoc): bool

ps_lineto() のような描画関数によって事前に作成されたパスを塗りつぶし、描画します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_fill() - 現在のパスを塗りつぶす
  • ps_stroke() - 現在のパスを描画する


フォントを読み込む

  • ≪ ps_fill_stroke
  • ps_get_buffer ≫
  • PHP Manual
  • PS 関数
  • フォントを読み込む

ps_findfont

(PECL ps >= 1.1.0)

ps_findfont — フォントを読み込む

説明

ps_findfont(
resource $psdoc,
string $fontname,
string $encoding,
bool $embed = false
): int

あとで使用するために、フォントを読み込みます。読み込んだフォントを実際に利用するためには、 ps_setfont() で設定しなければなりません。 文字の間隔を計算するため、この関数には adobe フォントメトリックファイルが必要です。 ページの内部で読み込まれたフォントは、 そのページ内でのみ有効となります。ドキュメント全体で使われるフォントは、 最初の ps_begin_page() の実行より前に読み込まれなければなりません。 ページとページの間で ps_findfont() が呼ばれた場合は、それ以降のページでフォントが有効になります。

afm ファイルの名前は、 fontname.afm でなければなりません。 フォントを埋め込む場合は、フォントのアウトラインを含む fontname.pfb が存在しなければなりません。

最初のページを処理する前に ps_findfont() をコール際、 postscript ヘッダが出力されます。ここには、ドキュメント全体に適用される BoundingBox が含まれます。 通常は、BoundingBox を設定するのは最初に ps_begin_page() がコールされたときで、これは ps_findfont() をコールした後になります。 したがって、ps_findfont() のコール時にはまだ BoundingBox が設定されておらず、警告が発生してしまいます。 こうなることを避けるため、ps_findfont() をコールする前に ps_set_parameter() をコールし、BoundingBox を設定しておくべきです。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

fontname

フォントの名前。

encoding

ps_findfont() は、encoding で渡されたファイルを読み込もうと試みます。 エンコーディングファイルは、 dvips(1) で使われるものと同形式です。 そこにはフォントエンコーディングベクタ（現在は利用されていませんが、 存在する必要があります）が含まれており、また afm ファイルから 生成されたリゲチャのリストを拡張するための拡張リゲチャが含まれています。

encoding は null または空文字列とすることも可能で、 その場合はデフォルトエンコーディング（TeXBase1）が用いられます。

encoding が builtin と指定された場合は、 エンコード処理は行われずにフォント固有のエンコーディングがそのまま用いられます。 これは、記号フォントを扱う場合に便利です。

embed

0 より大きい値を設定すると、フォントがドキュメントに埋め込まれます。 これを使用するには、フォントのアウトライン (.pfb ファイル) が必要です。

戻り値

成功した場合にフォントの ID を、失敗した場合にゼロを返します。 ID は正の数値です。

参考

  • ps_begin_page() - 新しいページを開始する
  • ps_setfont() - 以降の出力で用いるフォントを設定する


生成された PS データを含むバッファの内容を取得する

  • ≪ ps_findfont
  • ps_get_parameter ≫
  • PHP Manual
  • PS 関数
  • 生成された PS データを含むバッファの内容を取得する

ps_get_buffer

(PECL ps >= 1.1.0)

ps_get_buffer — 生成された PS データを含むバッファの内容を取得する

説明

ps_get_buffer(resource $psdoc): string

この関数は、まだ実装されていません。常に空の文字列を返します。 メモリ内でのデータ作成が求められる場合に、postscript ファイルを内部バッファに読み込み、バッファの内容をこの関数で取得する、 という実装を計画中です。 現在は、メモリ内で作成されたデータはバッファリングされず直接ブラウザに送られます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

参考

  • ps_open_file() - 出力用のファイルを開く


パラメータを取得する

  • ≪ ps_get_buffer
  • ps_get_value ≫
  • PHP Manual
  • PS 関数
  • パラメータを取得する

ps_get_parameter

(PECL ps >= 1.1.0)

ps_get_parameter — パラメータを取得する

説明

ps_get_parameter(resource $psdoc, string $name, float $modifier = ?): string|false

ps_set_parameter() で直接設定されたか、 あるいは他の関数で間接的に設定されたパラメータの値を取得します。 パラメータは文字列値として定義されます。この関数は、 同じく ps_set_parameter() で設定されたリソースを取得するためには利用できません。

パラメータ name は、以下の値をとります。

fontname

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの名前。

fontencoding

現在アクティブなフォントのエンコーディング。

dottedversion

元になる pslib ライブラリのバージョン。書式は <major>.<minor>.<subminor>

scope

現在の描画スコープ。object, document, null, page, pattern, path, template, prolog, font, glyph。

ligaturedisolvechar

リゲチャを溶かす文字。たとえば、リゲチャ `ff' を含むフォントで `|' がこの文字に指定されていた場合は、 `f|f' はリゲチャ `ff' ではなく 2 つの独立した `f' となります。

imageencoding

画像の符号化に使用するエンコーディング。 hex あるいは 85。 hex エンコーディングは、画像の各バイトを postscript ファイルの 2 バイトであらわします。85 は Ascii85 エンコーディングを表します。

linenumbermode

行番号を段落単位でつける場合は paragraph、 ボックス内でつける場合は box を設定します。

linebreak

テキストを ps_show_boxed() で出力する場合にのみ使用します。 true を設定すると、 改行時にキャリッジリターンが付加されます。

parbreak

テキストを ps_show_boxed() で出力する場合にのみ使用します。 true を設定すると、 キャリッジリターンで新しい段落を開始します。

hyphenation

テキストを ps_show_boxed() で出力する場合にのみ使用します。 true を設定すると、 ハイフネーション辞書が設定されており存在する場合に、 段落のハイフネーション処理が行われます。

hyphendict

ハイフネーションパターンの辞書のファイル名。

戻り値

成功した場合にパラメータの値を、失敗した場合に false を返します。

参考

  • ps_set_parameter() - パラメータを設定する


値を取得する

  • ≪ ps_get_parameter
  • ps_hyphenate ≫
  • PHP Manual
  • PS 関数
  • 値を取得する

ps_get_value

(PECL ps >= 1.1.0)

ps_get_value — 値を取得する

説明

ps_get_value(resource $psdoc, string $name, float $modifier = ?): float

ps_set_value() で設定された値を取得します。 値は浮動小数点数値として定義されます。

パラメータ name には以下の値を設定できます。

fontsize

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの名前。

font

現在アクティブなフォント自身。

imagewidth

パラメータ modifier で渡された ID の画像の幅。

imageheight

パラメータ modifier で渡された ID の画像の高さ。

capheight

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントにおける、 大文字の M の高さ。

ascender

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの ascender (上に突き出している部分の長さ)。

descender

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの descender (下に突き出している部分の長さ)。

italicangle

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの斜体の角度。

underlineposition

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの下線の位置。

underlinethickness

現在アクティブなフォント、 あるいはパラメータ modifier で指定された ID を持つフォントの下線の太さ。

textx

現在のテキスト出力位置の x 座標。

texty

現在のテキスト出力位置の y 座標。

textrendering

現在のテキストのレンダリングモード。

textrise

ベースライン上部の空間。

leading

テキストの行間隔をポイント数で指定。

wordspacing

単語と単語の間の空白の幅を、空白文字の幅を基準として指定。

charspacing

文字と文字の間の空白。0.0 でない場合は、リゲチャは常に分解されます。

hyphenminchars

単語の末尾で、ハイフネーションの対象となる最小文字数。

parindent

各段落の最初の n 行を字下げします。

numindentlines

parindent が 0.0 でない場合に、段落内で字下げする行数。

parskip

段落と段落の間隔。

linenumberspace

行番号を表示するために、各行の先頭に置く空白。

linenumbersep

行番号と行の内容の間隔。

major

pslib のメジャーバージョン番号。

minor

pslib のマイナーバージョン番号。

subminor, revision

pslib の詳細バージョン番号。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

値の名前。

modifier

modifier は、値を取得しようとしている リソースを指定します。たとえばフォントや画像の ID が考えられます。

戻り値

成功した場合にパラメータの値を、失敗した場合に false を返します。

参考

  • ps_set_value() - 値を設定する


単語をハイフネーションする

  • ≪ ps_get_value
  • ps_include_file ≫
  • PHP Manual
  • PS 関数
  • 単語をハイフネーションする

ps_hyphenate

(PECL ps >= 1.1.1)

ps_hyphenate — 単語をハイフネーションする

説明

ps_hyphenate(resource $psdoc, string $text): array|false

渡された単語をハイフネーションします。ps_hyphenate()
は、(ps_set_value() で設定した)
hyphenminchars の値と (ps_set_parameter() で設定した)
hyphendict パラメータの内容を評価します。
hyphendict は、この関数を呼ぶ前に必ず設定しておかなければなりません。

この関数を利用するためには、LC_CTYPE が適切に設定されている必要があります。 PostScript 拡張が初期化される際、環境変数の値が利用されます。 Unix 環境を利用している方は、詳細な情報は locale の man ページを見てください。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

text にはアルファベット以外の文字を 含むべきではありません。ハイフンで分割できる位置が、 整数値の配列として返されます。配列の個々の要素の内容は、 text 内でハイフンを入れられる場所の 次の文字の位置を表します。

戻り値

テキスト内で改行を入れられる位置を表す整数値の配列、 失敗した場合に false を返します。

例

例1 テキストのハイフネーション

<?php
$word = "Koordinatensystem";
$psdoc = ps_new();
ps_set_parameter($psdoc, "hyphendict", "hyph_de.dic");
$hyphens = ps_hyphenate($psdoc, $word);
for($i=0; $i<strlen($word); $i++) {
echo $word[$i];
if(in_array($i, $hyphens))
echo "-";
}
ps_delete($psdoc);
?>

上の例の出力は以下となります。

Ko-ordi-na-ten-sys-tem

参考

  • ps_show_boxed() - テキストをボックス内に出力する
  • locale(1)


外部ファイルを生の PostScript コードとして読み込む

  • ≪ ps_hyphenate
  • ps_lineto ≫
  • PHP Manual
  • PS 関数
  • 外部ファイルを生の PostScript コードとして読み込む

ps_include_file

(PECL ps >= 1.3.4)

ps_include_file — 外部ファイルを生の PostScript コードとして読み込む

説明

ps_include_file(resource $psdoc, string $file): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

file

戻り値

成功した場合に true を、失敗した場合に false を返します。


直線を描く

  • ≪ ps_include_file
  • ps_makespotcolor ≫
  • PHP Manual
  • PS 関数
  • 直線を描く

ps_lineto

(PECL ps >= 1.1.0)

ps_lineto — 直線を描く

説明

ps_lineto(resource $psdoc, float $x, float $y): bool

現在の位置から指定された座標までの直線を現在のパスに追加します。 直線の開始位置を指定するには ps_moveto() を利用します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

直線の終了地点の x 座標。

y

直線の終了地点の y 座標。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 矩形を描画する

<?php
$ps = ps_new();
if (!ps_open_file($ps, "rectangle.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_info($ps, "Creator", "rectangle.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Lineto example");

ps_begin_page($ps, 596, 842);
ps_moveto($ps, 100, 100);
ps_lineto($ps, 100, 200);
ps_lineto($ps, 200, 200);
ps_lineto($ps, 200, 100);
ps_lineto($ps, 100, 100);
ps_stroke($ps);
ps_end_page($ps);

ps_delete($ps);
?>

参考

  • ps_moveto() - 現在位置を設定する


スポット色を作成する

  • ≪ ps_lineto
  • ps_moveto ≫
  • PHP Manual
  • PS 関数
  • スポット色を作成する

ps_makespotcolor

(PECL ps >= 1.1.0)

ps_makespotcolor — スポット色を作成する

説明

ps_makespotcolor(resource $psdoc, string $name, int $reserved = 0): int

現在の塗りつぶし色からスポット色を作成します。塗りつぶし色の色空間は rgb, cmyk または グレースケールのいずれかでなければなりません。 スポット色には任意の名前をつけることができます。 スポット色には、ps_setcolor() を用いてどんな色でも設定できます。 ドキュメントが印刷されずに postscript ビューアで表示される場合にも、 指定した色空間の色が使用されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

スポット色の名前、例えば Pantone 5565。

戻り値

成功した場合にスポット色の ID を、失敗した場合にゼロを返します。

例

例1 スポット色の作成と使用

<?php
$ps = ps_new();
if (!ps_open_file($ps, "spotcolor.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_info($ps, "Creator", "spotcolor.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Spot color example");

ps_begin_page($ps, 596, 842);
ps_setcolor($ps, "fill", "cmyk", 0.37, 0.0, 0.34, 0.34);
$spotcolor = ps_makespotcolor($ps, "PANTONE 5565 C", 0);
ps_setcolor($ps, "fill", "spot", $spotcolor, 0.5, 0.0, 0.0);
ps_moveto($ps, 100, 100);
ps_lineto($ps, 100, 200);
ps_lineto($ps, 200, 200);
ps_lineto($ps, 200, 100);
ps_lineto($ps, 100, 100);
ps_fill($ps);
ps_end_page($ps);

ps_delete($ps);
?>

この例では、深緑 (オリーブ) 色で 50 % の濃度で矩形を塗りつぶすスポット色 "PANTONE 5565 C" を作成します。

参考

  • ps_setcolor() - 色を設定する


現在位置を設定する

  • ≪ ps_makespotcolor
  • ps_new ≫
  • PHP Manual
  • PS 関数
  • 現在位置を設定する

ps_moveto

(PECL ps >= 1.1.0)

ps_moveto — 現在位置を設定する

説明

ps_moveto(resource $psdoc, float $x, float $y): bool

現在位置を新しい座標に指定します。前回のパスが終了してからはじめて ps_moveto() が呼ばれた場合、新しいパスを開始します。 もしすでにパスが開始されているときに呼ばれた場合は、 単に現在位置を設定し、サブパスを開始します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

移動する位置の x 座標。

y

移動する位置の y 座標。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_lineto() - 直線を描く


新しい PostScript ドキュメントオブジェクトを作成する

  • ≪ ps_moveto
  • ps_open_file ≫
  • PHP Manual
  • PS 関数
  • 新しい PostScript ドキュメントオブジェクトを作成する

ps_new

(PECL ps >= 1.1.0)

ps_new — 新しい PostScript ドキュメントオブジェクトを作成する

説明

ps_new(): resource|false

新しいドキュメントのインスタンスを生成します。 ディスク上やメモリ内にファイルを作ることはありません。 ドキュメントのインスタンスがすべてを設定します。 ps_new() の後には、通常は ps_open_file() がコールされます。これにより、 実際に postscript ドキュメントが作成されます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に PostScript ドキュメントのリソースを、 失敗した場合に false を返します。 この戻り値は、その他のすべての関数の最初の引数として渡されます。

参考

  • ps_delete() - PostScript ドキュメントの全リソースを削除する


出力用のファイルを開く

  • ≪ ps_new
  • ps_open_image ≫
  • PHP Manual
  • PS 関数
  • 出力用のファイルを開く

ps_open_file

(PECL ps >= 1.1.0)

ps_open_file — 出力用のファイルを開く

説明

ps_open_file(resource $psdoc, string $filename = ?): bool

ディスク上に新しいファイルを作成し、PostScript ドキュメントをその中に書き込みます。ps_close() が呼ばれると、ファイルは閉じられます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

filename

postscript ファイルの名前。 filename が渡されなかった場合、 ドキュメントはメモリ内に作成され、内容は直接ブラウザに出力されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_close() - PostScript ドキュメントを閉じる


後で配置するために画像を読み込む

  • ≪ ps_open_file
  • ps_open_image_file ≫
  • PHP Manual
  • PS 関数
  • 後で配置するために画像を読み込む

ps_open_image

(PECL ps >= 1.1.0)

ps_open_image — 後で配置するために画像を読み込む

説明

ps_open_image(
resource $psdoc,
string $type,
string $source,
string $data,
int $lenght,
int $width,
int $height,
int $components,
int $bpc,
string $params
): int

すでにメモリ上にある画像を読み込みます。現在は source は評価されず、常に memory と仮定されます。 画像データは、左上から右下に向かってピクセルデータを順に並べたものです。 各ピクセルは、色コンポーネント components で構成されており、このコンポーネントの大きさは bpc ビットです。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

画像の形式。png、 jpeg あるいは eps。

source

使用されません。

data

画像データ。

length

画像データの長さ。

width

画像の幅。

height

画像の高さ。

components

各ピクセルのコンポーネントの数。 1 (グレースケール画像)、 3 (rgb 画像) あるいは 4 (cmyk, rgba 画像)。

bpc

コンポーネント単位のビット数 (ほとんどの場合は 8)

params

戻り値

成功した場合に画像の ID を、失敗した場合にゼロを返します。 ID は、0 より大きい正の数値です。

参考

  • ps_open_image_file() - ファイルから画像を開く
  • ps_place_image() - 画像をページに配置する
  • ps_close_image() - 画像を閉じ、メモリを開放する


ファイルから画像を開く

  • ≪ ps_open_image
  • ps_open_memory_image ≫
  • PHP Manual
  • PS 関数
  • ファイルから画像を開く

ps_open_image_file

(PECL ps >= 1.1.0)

ps_open_image_file — ファイルから画像を開く

説明

ps_open_image_file(
resource $psdoc,
string $type,
string $filename,
string $stringparam = ?,
int $intparam = 0
): int

後で使用するために、画像を読み込みます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

画像の形式。png、 jpeg あるいは eps。

filename

画像データを含むファイルの名前。

stringparam

使用されません。

intparam

使用されません。

戻り値

成功した場合に画像の ID を、失敗した場合にゼロを返します。 ID は、0 より大きい正の数値です。

参考

  • ps_open_image() - 後で配置するために画像を読み込む
  • ps_place_image() - 画像をページに配置する
  • ps_close_image() - 画像を閉じ、メモリを開放する


GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す

  • ≪ ps_open_image_file
  • ps_place_image ≫
  • PHP Manual
  • PS 関数
  • GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す

ps_open_memory_image

(PECL ps >= 1.1.0)

ps_open_memory_image — GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す

説明

ps_open_memory_image(resource $psdoc, int $gd): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

gd


画像をページに配置する

  • ≪ ps_open_memory_image
  • ps_rect ≫
  • PHP Manual
  • PS 関数
  • 画像をページに配置する

ps_place_image

(PECL ps >= 1.1.0)

ps_place_image — 画像をページに配置する

説明

ps_place_image(
resource $psdoc,
int $imageid,
float $x,
float $y,
float $scale
): bool

以前に読み込まれている画像をページに配置します。画像の縮尺は変更できます。 画像を回転させる場合は、事前に ps_rotate() で座標系を回転させておきます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

imageid

ps_open_image() あるいは ps_open_image_file() が返す、 画像のリソース ID。

x

画像の左下角の x 座標。

y

画像の左下角の y 座標。

scale

画像の拡大率。1.0 を指定すると、解像度は 72 dpi となります。 これにより、各ピクセルが 1 ポイントと等しくなるからです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_open_image() - 後で配置するために画像を読み込む
  • ps_open_image_file() - ファイルから画像を開く


矩形を描く

  • ≪ ps_place_image
  • ps_restore ≫
  • PHP Manual
  • PS 関数
  • 矩形を描く

ps_rect

(PECL ps >= 1.1.0)

ps_rect — 矩形を描く

説明

ps_rect(
resource $psdoc,
float $x,
float $y,
float $width,
float $height
): bool

（x, y）を左下の角とする 矩形を描きます。描画は左下の角から始まって同じ位置で終わります。 もしパスの外部でこの関数が呼び出された場合、新しいパスを開始します。 パスの内部で呼び出された場合は、矩形をサブパスとして追加します。一つ前の描画処理が 左下角の位置で終わっていなかった場合は、パスに隙間ができることになります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

矩形の左下角の x 座標。

y

矩形の左下角の y 座標。

width

画像の幅。

height

画像の高さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_arc() - 反時計回りに円弧を描く
  • ps_cirle()
  • ps_lineto() - 直線を描く


以前に保存されたコンテキストを復元する

  • ≪ ps_rect
  • ps_rotate ≫
  • PHP Manual
  • PS 関数
  • 以前に保存されたコンテキストを復元する

ps_restore

(PECL ps >= 1.1.0)

ps_restore — 以前に保存されたコンテキストを復元する

説明

ps_restore(resource $psdoc): bool

以前に保存されている描画コンテキストを復元します。 すべての ps_save() 呼び出しには、対応する ps_restore() の呼び出しが必要です。 座標系変換、線の設定、色の設定などは、すべて ps_save() のコール前の状態に戻ります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_save() - 現在のコンテキストを保存する


回転の程度を設定する

  • ≪ ps_restore
  • ps_save ≫
  • PHP Manual
  • PS 関数
  • 回転の程度を設定する

ps_rotate

(PECL ps >= 1.1.0)

ps_rotate — 回転の程度を設定する

説明

ps_rotate(resource $psdoc, float $rot): bool

座標系の回転を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

rot

回転角度を度単位で指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 座標系の回転

<?php
function rectangle($ps) {
ps_moveto($ps, 0, 0);
ps_lineto($ps, 0, 50);
ps_lineto($ps, 50, 50);
ps_lineto($ps, 50, 0);
ps_lineto($ps, 0, 0);
ps_stroke($ps);
}

$ps = ps_new();
if (!ps_open_file($ps, "rotation.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_info($ps, "Creator", "rotation.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Rotation example");
ps_set_info($ps, "BoundingBox", "0 0 596 842");

$psfont = ps_findfont($ps, "Helvetica", "", 0);

ps_begin_page($ps, 596, 842);
ps_set_text_pos($ps, 100, 100);
ps_save($ps);
ps_translate($ps, 100, 100);
ps_rotate($ps, 45);
rectangle($ps);
ps_restore($ps);
ps_setfont($ps, $psfont, 8.0);
ps_show($ps, "Text without rotation");
ps_end_page($ps);

ps_delete($ps);
?>

上の例では、座標系を回転させることによって、図形 (ここでは単なる矩形) を回転させるという一般的な方法を説明しています。 図形の座標系は (0,0) を起点とみなしているため、 図形がページの端にない場合には座標系の変換も行います。 ps_translate() および ps_rotate() の順番には気をつけてください。 上の例では、変換前の座標系での (100, 100) を基準として矩形を回転させています。 2 つの文の順序を入れ替えると、まったく異なる結果となります。

これ以降のテキストをもとの位置に出力させるには、 ps_save() および ps_restore() を使用して、座標系に関する変更内容をカプセル化します。

参考

  • ps_scale() - 縮尺を設定する
  • ps_translate() - 座標変換を設定する


現在のコンテキストを保存する

  • ≪ ps_rotate
  • ps_scale ≫
  • PHP Manual
  • PS 関数
  • 現在のコンテキストを保存する

ps_save

(PECL ps >= 1.1.0)

ps_save — 現在のコンテキストを保存する

説明

ps_save(resource $psdoc): bool

現在の描画コンテキストを保存します。 そこには色や変換・回転その他の情報が含まれています。保存されたコンテキストは ps_restore() で復元できます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_restore() - 以前に保存されたコンテキストを復元する


縮尺を設定する

  • ≪ ps_save
  • ps_set_border_color ≫
  • PHP Manual
  • PS 関数
  • 縮尺を設定する

ps_scale

(PECL ps >= 1.1.0)

ps_scale — 縮尺を設定する

説明

ps_scale(resource $psdoc, float $x, float $y): bool

座標系の、水平方向・垂直方向の縮尺をそれぞれ設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

水平方向の倍率。

y

垂直方向の倍率。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_rotate() - 回転の程度を設定する
  • ps_translate() - 座標変換を設定する


注記の枠線の色を設定する

  • ≪ ps_scale
  • ps_set_border_dash ≫
  • PHP Manual
  • PS 関数
  • 注記の枠線の色を設定する

ps_set_border_color

(PECL ps >= 1.1.0)

ps_set_border_color — 注記の枠線の色を設定する

説明

ps_set_border_color(
resource $psdoc,
float $red,
float $green,
float $blue
): bool

ps_add_weblink() や ps_add_pdflink() などの関数で追加されたリンクは、 pdf に変換して pdf ビューアで見た際には矩形で囲まれて表示されます。 この矩形は、postscript ドキュメントでは表示されません。 この関数は、矩形の枠線の色を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

red

枠線の色の red 要素。

green

枠線の色の green 要素。

blue

枠線の色の blue 要素。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_set_border_dash() - 注記の枠線の、破線の状態を設定する
  • ps_set_border_style() - 注記の枠線の形式を設定する


注記の枠線の、破線の状態を設定する

  • ≪ ps_set_border_color
  • ps_set_border_style ≫
  • PHP Manual
  • PS 関数
  • 注記の枠線の、破線の状態を設定する

ps_set_border_dash

(PECL ps >= 1.1.0)

ps_set_border_dash — 注記の枠線の、破線の状態を設定する

説明

ps_set_border_dash(resource $psdoc, float $black, float $white): bool

ps_add_weblink() や ps_add_pdflink() などの関数で追加されたリンクは、 pdf に変換して pdf ビューアで見た際には矩形で囲まれて表示されます。 この矩形は、postscript ドキュメントでは表示されません。 この関数は、破線の「線」の部分と「空白」の部分の長さを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

black

破線の長さ。

white

破線と破線の間隔。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_set_border_color() - 注記の枠線の色を設定する
  • ps_set_border_style() - 注記の枠線の形式を設定する


注記の枠線の形式を設定する

  • ≪ ps_set_border_dash
  • ps_set_info ≫
  • PHP Manual
  • PS 関数
  • 注記の枠線の形式を設定する

ps_set_border_style

(PECL ps >= 1.1.0)

ps_set_border_style — 注記の枠線の形式を設定する

説明

ps_set_border_style(resource $psdoc, string $style, float $width): bool

ps_add_weblink() や ps_add_pdflink() などの関数で追加されたリンクは、 pdf に変換して pdf ビューアで見た際には矩形で囲まれて表示されます。 この矩形は、postscript ドキュメントでは表示されません。 この関数は、その線の形式と幅を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

style

style は、 solid（実線） または dashed（破線）のいずれかを設定できます。

width

枠線の幅。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_set_border_color() - 注記の枠線の色を設定する
  • ps_set_border_dash() - 注記の枠線の、破線の状態を設定する


ドキュメントの情報を設定する

  • ≪ ps_set_border_style
  • ps_set_parameter ≫
  • PHP Manual
  • PS 関数
  • ドキュメントの情報を設定する

ps_set_info

(PECL ps >= 1.1.0)

ps_set_info — ドキュメントの情報を設定する

説明

ps_set_info(resource $p, string $key, string $val): bool

ドキュメントの情報フィールドを設定します。この情報は、PostScript ファイルのヘッダにコメントとして表示されます。 ドキュメントが pdf に変換された場合にも、 このフィールドはドキュメントの情報として使用されます。

通常 BoundingBox は最初のページの設定と同じ値を 設定しておきます。 ps_findfont() が事前に呼ばれていなかった場合のみ、この設定が利用されます。そのような場合、 もしこの関数で明示的に設定していなければ BoundingBox は空白のままとなります。

postscript ファイルのヘッダが既に書き込まれている場合には、 この関数は何の意味も持ちません。この関数は、最初のページの前、 あるいは ps_findfont() が最初にコールされる前にコールされる必要があります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

key

設定する情報フィールドの名前。設定できる値は Keywords、Subject、 Title、Creator、 Author、BoundingBox および Orientation です。 このうちのいくつかは、PostScript ビューアに対して意味を持つものであることに注意しましょう。

value

情報フィールドの値。 Orientation フィールドには Portrait あるいは Landscape が設定できます。BoundingBox は 4 つの数値からなる文字列で、最初の 2 つがページの左下角の座標を表します。 残りの 2 つが右上角の座標です。

注意:

pslib のバージョン 0.2.6 まででは、 ps_findfont() が事前にコールされていない限り、 この関数は常に BoundingBox および Orientation を上書きします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_findfont() - フォントを読み込む
  • ps_begin_page() - 新しいページを開始する


パラメータを設定する

  • ≪ ps_set_info
  • ps_set_text_pos ≫
  • PHP Manual
  • PS 関数
  • パラメータを設定する

ps_set_parameter

(PECL ps >= 1.1.0)

ps_set_parameter — パラメータを設定する

説明

ps_set_parameter(resource $psdoc, string $name, string $value): bool

多くの関数で利用されるパラメータを設定します。 パラメータは文字列値として定義されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

使用できる名称については ps_get_parameter() を参照ください。

value

パラメータの値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_get_parameter() - パラメータを取得する
  • ps_set_value() - 値を設定する


テキストの出力位置を設定する

  • ≪ ps_set_parameter
  • ps_set_value ≫
  • PHP Manual
  • PS 関数
  • テキストの出力位置を設定する

ps_set_text_pos

(PECL ps >= 1.1.0)

ps_set_text_pos — テキストの出力位置を設定する

説明

ps_set_text_pos(resource $psdoc, float $x, float $y): bool

テキストを出力する位置を設定します。別の方法として、x と y の値を別々に ps_set_value() で設定することもできます。 この場合の設定項目は、それぞれ textx と texty となります。

テキストを所定の位置に出力したいのなら、テキストの位置を指定してから ps_show() をコールするよりも、 ps_show_xy() を使用するほうが便利です。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

新しいテキスト位置の x 座標。

y

新しいテキスト位置の y 座標。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 指定した位置にテキストを配置する

<?php
$ps = ps_new();
if (!ps_open_file($ps, "text.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_info($ps, "Creator", "rectangle.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Text placement example");

ps_begin_page($ps, 596, 842);
$psfont = ps_findfont($ps, "Helvetica", "", 0);
ps_setfont($ps, $psfont, 8.0);
ps_show_xy($ps, "Some text at (100, 100)", 100, 100);

ps_set_value($ps, "textx", 100);
ps_set_value($ps, "texty", 120);
ps_show($ps, "Some text at (100, 120)");
ps_end_page($ps);

ps_delete($ps);
?>

参考

  • ps_set_value() - 値を設定する
  • ps_show() - テキストを出力する


値を設定する

  • ≪ ps_set_text_pos
  • ps_setcolor ≫
  • PHP Manual
  • PS 関数
  • 値を設定する

ps_set_value

(PECL ps >= 1.1.0)

ps_set_value — 値を設定する

説明

ps_set_value(resource $psdoc, string $name, float $value): bool

多くの関数で利用される値を設定します。 パラメータは浮動小数点数値として定義されます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

name

name は以下のうちのひとつです。

textrendering

テキストをどのように見せるか。

textx

出力テキストの x 座標。

texty

出力テキストの y 座標。

wordspacing

単語の間隔を空白文字に対する比率で設定する。

leading

行間をピクセルで指定する。

value

パラメータの値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_get_value() - 値を取得する
  • ps_set_parameter() - パラメータを設定する


色を設定する

  • ≪ ps_set_value
  • ps_setdash ≫
  • PHP Manual
  • PS 関数
  • 色を設定する

ps_setcolor

(PECL ps >= 1.1.0)

ps_setcolor — 色を設定する

説明

ps_setcolor(
resource $psdoc,
string $type,
string $colorspace,
float $c1,
float $c2,
float $c3,
float $c4
): bool

描画色、塗りつぶし色、あるいはその両方を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

type は both、fill、 あるいは fillstroke のいずれかです。

colorspace

colorspace は gray、 rgb、cmyk、 spot、pattern のいずれかです。 colorspace の値によって、以下のパラメータのうち最初のひとつ・最初の３つ あるいはすべてが利用されます。

c1

colorspace の値によって、red 成分 (rgb の場合)、 cyan 成分 (cmyk の場合)、グレースケール (gray の場合)、 スポット色の ID あるいはパターンの ID のいずれかとなります。

c2

colorspace の値によって、green 成分 (rgb の場合)、 magenta 成分 (cmyk の場合) のいずれかとなります。

c3

colorspace の値によって、blue 成分 (rgb の場合)、 yellow 成分 (cmyk の場合) のいずれかとなります。

c4

colorspace が cmyk の場合にのみ設定され、black 成分の値を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

2 番目のパラメータは、現在は常に評価されるわけではありません。 設定内容にかかわらず、fillstroke が渡されたときのような振る舞いをすることがあります。


破線の形状を設定する

  • ≪ ps_setcolor
  • ps_setflat ≫
  • PHP Manual
  • PS 関数
  • 破線の形状を設定する

ps_setdash

(PECL ps >= 1.1.0)

ps_setdash — 破線の形状を設定する

説明

ps_setdash(resource $psdoc, float $on, float $off): bool

破線の「線」の部分と「空白」の部分の長さを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

on

破線の長さ。

off

破線と破線の間隔の長さ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setpolydash() - 破線の形状を設定する


平面度を設定する

  • ≪ ps_setdash
  • ps_setfont ≫
  • PHP Manual
  • PS 関数
  • 平面度を設定する

ps_setflat

(PECL ps >= 1.1.0)

ps_setflat — 平面度を設定する

説明

ps_setflat(resource $psdoc, float $value): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

value

value は 0.2 から 1 までの間でなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


以降の出力で用いるフォントを設定する

  • ≪ ps_setflat
  • ps_setgray ≫
  • PHP Manual
  • PS 関数
  • 以降の出力で用いるフォントを設定する

ps_setfont

(PECL ps >= 1.1.0)

ps_setfont — 以降の出力で用いるフォントを設定する

説明

ps_setfont(resource $psdoc, int $fontid, float $size): bool

フォントを設定します。このフォントは、事前に ps_findfont() で読み込まれている必要があります。 フォントを設定せずにテキストを出力するとエラーとなります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

fontid

ps_findfont() が返す、フォント ID。

size

フォントのサイズ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_findfont() - フォントを読み込む
  • ps_set_text_pos() - テキストの出力位置を設定する for an example.


グレー値を設定する

  • ≪ ps_setfont
  • ps_setlinecap ≫
  • PHP Manual
  • PS 関数
  • グレー値を設定する

ps_setgray

(PECL ps >= 1.1.0)

ps_setgray — グレー値を設定する

説明

ps_setgray(resource $psdoc, float $gray): bool

以降の描画処理で使われるグレー値を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

gray

値は 0（白）から 1（黒）までの間でなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setcolor() - 色を設定する


線端の形状を設定する

  • ≪ ps_setgray
  • ps_setlinejoin ≫
  • PHP Manual
  • PS 関数
  • 線端の形状を設定する

ps_setlinecap

(PECL ps >= 1.1.0)

ps_setlinecap — 線端の形状を設定する

説明

ps_setlinecap(resource $psdoc, int $type): bool

線端をどのように表示するかを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

線端の形式。 PS_LINECAP_BUTT、 PS_LINECAP_ROUND あるいは PS_LINECAP_SQUARED のいずれか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinejoin() - 線の連結方法を設定する
  • ps_setlinewidth() - 線幅を設定する
  • ps_setmiterlimit() - miter limit 値を設定する


線の連結方法を設定する

  • ≪ ps_setlinecap
  • ps_setlinewidth ≫
  • PHP Manual
  • PS 関数
  • 線の連結方法を設定する

ps_setlinejoin

(PECL ps >= 1.1.0)

ps_setlinejoin — 線の連結方法を設定する

説明

ps_setlinejoin(resource $psdoc, int $type): bool

線がどのように連結されるかを設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

線の連結方式。 PS_LINEJOIN_MITER、 PS_LINEJOIN_ROUND あるいは PS_LINEJOIN_BEVEL のいずれか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinecap() - 線端の形状を設定する
  • ps_setlinewidth() - 線幅を設定する
  • ps_setmiterlimit() - miter limit 値を設定する


線幅を設定する

  • ≪ ps_setlinejoin
  • ps_setmiterlimit ≫
  • PHP Manual
  • PS 関数
  • 線幅を設定する

ps_setlinewidth

(PECL ps >= 1.1.0)

ps_setlinewidth — 線幅を設定する

説明

ps_setlinewidth(resource $psdoc, float $width): bool

以降の描画処理での線幅を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

width

線の幅 (ポイント数)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinecap() - 線端の形状を設定する
  • ps_setlinejoin() - 線の連結方法を設定する
  • ps_setmiterlimit() - miter limit 値を設定する


miter limit 値を設定する

  • ≪ ps_setlinewidth
  • ps_setoverprintmode ≫
  • PHP Manual
  • PS 関数
  • miter limit 値を設定する

ps_setmiterlimit

(PECL ps >= 1.1.0)

ps_setmiterlimit — miter limit 値を設定する

説明

ps_setmiterlimit(resource $psdoc, float $value): bool

2 本の直線が小さい角度で連結され、かつ連結方法が PS_LINEJOIN_MITER に設定されている場合、 出来上がる線の角の部分が非常に長くなります。miter limit は、miter length (角の長さ) と線幅の比率の最大値です。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

value

miter length と線幅の比率の最大値。大きな値 (> 10) を設定すると、2 本の直線が狭い角度で交わる際に、 角の部分が非常に長くなってしまいます。 よくわからない場合はデフォルトのままにしておきましょう。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_setlinecap() - 線端の形状を設定する
  • ps_setlinejoin() - 線の連結方法を設定する
  • ps_setlinewidth() - 線幅を設定する


overprint モードを設定する

  • ≪ ps_setmiterlimit
  • ps_setpolydash ≫
  • PHP Manual
  • PS 関数
  • overprint モードを設定する

ps_setoverprintmode

(PECL ps >= 1.3.0)

ps_setoverprintmode — overprint モードを設定する

説明

ps_setoverprintmode(resource $psdoc, int $mode): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

mode

戻り値

成功した場合に true を、失敗した場合に false を返します。


破線の形状を設定する

  • ≪ ps_setoverprintmode
  • ps_shading ≫
  • PHP Manual
  • PS 関数
  • 破線の形状を設定する

ps_setpolydash

(PECL ps >= 1.1.0)

ps_setpolydash — 破線の形状を設定する

説明

ps_setpolydash(resource $psdoc, float $arr): bool

破線の「線」の部分と「空白」の部分の長さを設定します。 ps_setpolydash() は、 より複雑な破線パターンを設定するために用いられます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

arr

arr は「線」の部分の長さと 「空白」の部分の長さを互い違いにならべたリストです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 破線を描画する

<?php
$ps = ps_new();
if (!ps_open_file($ps, "polydash.ps")) {
print "PostScript ファイルをオープンできません\n";
exit;
}

ps_set_info($ps, "Creator", "polydash.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Poly dash example");

ps_begin_page($ps, 596, 842);
ps_setpolydash($ps, array(10, 5, 2, 5));
ps_moveto($ps, 100, 100);
ps_lineto($ps, 200, 200);
ps_stroke($ps);
ps_end_page($ps);

ps_delete($ps);
?>

この例は、長さ 10 ポイントと 2 ポイントの線を、 5 ポイントの空白でつなげた破線を描画します。

参考

  • ps_setdash() - 破線の形状を設定する


以降の出力で用いるシェーディングを作成する

  • ≪ ps_setpolydash
  • ps_shading_pattern ≫
  • PHP Manual
  • PS 関数
  • 以降の出力で用いるシェーディングを作成する

ps_shading

(PECL ps >= 1.3.0)

ps_shading — 以降の出力で用いるシェーディングを作成する

説明

ps_shading(
resource $psdoc,
string $type,
float $x0,
float $y0,
float $x1,
float $y1,
float $c1,
float $c2,
float $c3,
float $c4,
string $optlist
): int|false

シェーディングを作成します。これは ps_shfill() や ps_shading_pattern() で用いられます。

シェーディングの色には、pattern 以外の任意の色空間が利用できます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

type

シェーディングの種類で、radial (放射状) または axial (直線状) のいずれかです。 シェーディングは現在の塗りつぶし色で始まり、 c1 から c4 までのパラメータで指定される色で終わります (パラメータの意味は ps_setcolor() を参照ください)。

x0, x1, y0, y1

x0, y0, x1, y1 は、 シェーディングの開始位置・終了位置の座標です。 シェーディングの形式が radial の場合は、 それぞれ開始円・終了円の中心となります。

c1, c2, c3, c4

このパラメータの意味は ps_setcolor() を参照ください。

optlist

type が radial の場合、optlist にはパラメータ r0 と r1 が含まれる必要があります。これらはそれぞれ開始位置と終了位置を表す 円の半径です。

戻り値

成功した場合にパターンの ID を、失敗した場合に false を返します。

参考

  • ps_shading_pattern() - シェーディング用のパターンを作成する
  • ps_shfill() - 範囲をシェーディングで塗りつぶす


シェーディング用のパターンを作成する

  • ≪ ps_shading
  • ps_shfill ≫
  • PHP Manual
  • PS 関数
  • シェーディング用のパターンを作成する

ps_shading_pattern

(PECL ps >= 1.3.0)

ps_shading_pattern — シェーディング用のパターンを作成する

説明

ps_shading_pattern(resource $psdoc, int $shadingid, string $optlist): int|false

シェーディング用のパターンを作成します。これは ps_shading() を呼ぶ前に行わなければなりません。 シェーディングパターンは、標準のパターンと同じように用いられます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

shadingid

事前に ps_shading() で作成したシェーディングの ID。

optlist

このパラメータは、現在使用されていません。

戻り値

成功した場合にパターンの ID を、失敗した場合に false を返します。

参考

  • ps_shading() - 以降の出力で用いるシェーディングを作成する
  • ps_shfill() - 範囲をシェーディングで塗りつぶす


範囲をシェーディングで塗りつぶす

  • ≪ ps_shading_pattern
  • ps_show ≫
  • PHP Manual
  • PS 関数
  • 範囲をシェーディングで塗りつぶす

ps_shfill

(PECL ps >= 1.3.0)

ps_shfill — 範囲をシェーディングで塗りつぶす

説明

ps_shfill(resource $psdoc, int $shadingid): bool

範囲をシェーディングで塗りつぶします。シェーディングは事前に ps_shading() で作られている必要があります。 この関数は、ps_shading_pattern() でシェーディングからパターンを作成し、 それを塗りつぶし色として使用するのと同じことを行います。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

shadingid

事前に ps_shading() で作成したシェーディングの ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_shading() - 以降の出力で用いるシェーディングを作成する
  • ps_shading_pattern() - シェーディング用のパターンを作成する


テキストを出力する

  • ≪ ps_shfill
  • ps_show_boxed ≫
  • PHP Manual
  • PS 関数
  • テキストを出力する

ps_show

(PECL ps >= 1.1.0)

ps_show — テキストを出力する

説明

ps_show(resource $psdoc, string $text): bool

現在の位置にテキストを出力します。テキストの位置を設定するには、 関数 ps_set_value() の値 textx および texty に x 座標と y 座標を設定します。 事前に ps_setfont() でフォントが設定されていない場合、この関数はエラーを返します。

ps_show() は、以下のようなパラメータや値
(それぞれ ps_set_parameter() や
ps_set_value() で設定されたもの)
の内容を評価します。

charspacing (value)

連続する 2 つのグリフ間の距離です。値がゼロ以外の場合、リゲチャは 解消されます。ゼロ未満の値を指定することも可能です。

kerning (parameter)

このパラメータを "false" に設定するとカーニングが無効になります。 デフォルトではカーニングが有効になっています。

ligatures (parameter)

このパラメータを "false" に設定するとリゲチャを使用しないようになります。 デフォルトではリゲチャを使用するようになっています。

underline (parameter)

このパラメータを "true" に設定すると下線が引かれます。 デフォルトでは下線が無効になっています。

overline (parameter)

このパラメータを "true" に設定すると上線が引かれます。 デフォルトでは上線が無効になっています。

strikeout (parameter)

このパラメータを "true" に設定すると打ち消し線が引かれます。 デフォルトでは打ち消し線が無効になっています。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

出力するテキスト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_continue_text() - 次の行にテキストを続ける
  • ps_show_xy() - 指定された位置にテキストを出力する
  • ps_setfont() - 以降の出力で用いるフォントを設定する


テキストをボックス内に出力する

  • ≪ ps_show
  • ps_show_xy ≫
  • PHP Manual
  • PS 関数
  • テキストをボックス内に出力する

ps_show_boxed

(PECL ps >= 1.1.0)

ps_show_boxed — テキストをボックス内に出力する

説明

ps_show_boxed(
resource $psdoc,
string $text,
float $left,
float $bottom,
float $width,
float $height,
string $hmode,
string $feature = ?
): int

与えられたボックスの中にテキストを出力します。ボックスの左下の座標が (left, bottom) となります。 必要に応じて改行が挿入されます。連続する空白文字は、ひとつとして扱われ、 タブ文字は空白文字として扱われます。

パラメータ hyphenation が true に設定されており、またパラメータ hyphendict に有効なハイフネーションファイルが設定されている場合に、 テキストのハイフネーションが行われます。 行間隔の設定は、値 leading で行います。 TeX と同様に、段落と段落の間には空行が挿入されます。 値 parindent が 0.0 より大きく設定されている場合、 最初の n 行は字下げされます。n の行数は、値 numindentlines で設定します。 最初の m 段落を字下げしないようにするには、 値 parindentskip に正の数値を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

指定したボックスの中に出力するテキスト。

left

ボックスの左下角の x 座標。

bottom

ボックスの左下角の y 座標。

width

ボックスの幅。

height

ボックスの高さ。

hmode

パラメータ hmode は justify（均等割付）・ fulljustify（完全な均等割付）・ right（右寄せ）・ left（左寄せ）・ center（センタリング）のどれかの値を設定します。 justify と fulljustify の違いは、ボックスの最終行の処理です。 fulljustify モードでは、 段落の最後の行である場合を除いて最終行も均等割付をします。 justify モードでは、最終行は常に左寄せとなります。

feature

用いられるパラメータ

ps_show_boxed() の出力は、パラメータや値
(それぞれ ps_set_parameter() や
ps_set_value() で設定されたもの) で設定できます。
テキスト出力に影響するパラメータや値のうち、以下のものが評価されます。

leading (value)

連続する 2 つの行の間隔です。

linebreak (parameter)

キャリッジリターンを、空白ではなく改行として扱いたい場合は true に設定します。 デフォルトは false です。

parbreak (parameter)

単一行のデータ中のキャリッジリターンを、空白ではなく段落区切りとして 扱いたい場合は true に設定します。 デフォルトは true です。

hyphenation (parameter)

ハイフネーションを有効にする場合は true に設定します。 その際、hyphendict に辞書を設定しておく必要があります。 デフォルトは false です。

hyphendict (parameter)

ハイフネーションパターンの辞書ファイル名です（以下を参照）。

hyphenminchar (value)

ハイフンの前後に最低限必要な文字数です。つまり、少なくともこの値の 2 倍以上の文字数の単語でないとハイフネーションされないということです。 デフォルトは 3 です。値をゼロに設定すると、デフォルトの値が使われます。

parindent (value)

段落の最初の m 行に対する字下げの量をピクセル単位で設定します。 m は、値 numindentlines で設定します。

parskip (value)

段落間の空白の追加量をピクセル単位で設定します。 デフォルトは 0 で、 通常の行間設定をそのまま利用します。

numindentlines (value)

段落の最初の部分で字下げ対象となる行数です。 デフォルトは 1 です。

parindentskip (value)

字下げ処理を行わない段落数を設定します。 デフォルトは 0 です。 この設定が便利に使えるのは、章の始めの段落・2 つのボックスにまたがる テキストなどです。 このような場合には値を 1 に設定します。

linenumbermode (parameter)

行番号のつけ方を設定します。 box を設定するとボックス全体に 番号をつけ、 paragraph を設定するとその中の段落単位で番号をつけます。

linenumberspace (value)

行番号を表示するための、左側のスペースの幅です。行番号は、 このスペースに右詰めで表示されます。 デフォルトは 20 です。

linenumbersep (value)

行番号欄と行本文欄の間の空白です。 デフォルトは 5 です。

ハイフネーション

パラメータ hyphenation が true に設定され、かつ 有効なハイフネーション辞書が設定されている場合に、テキストが ハイフネーションされます。 pslib は独自のハイフネーション辞書を持っておらず、 openoffice または scribus, koffice の辞書のうちひとつを利用します。 これらのソフトウェアがインストールされている環境では、 さまざまな言語の辞書が 以下のディレクトリで見つけられます。

  • /usr/share/apps/koffice/hyphdicts/
  • /usr/lib/scribus/dicts/
  • /usr/lib/openoffice/share/dict/ooo/
現時点では、scribus が最も完璧なハイフネーション辞書を持っているようです。

戻り値

書くことができなかった文字数を返します。

参考

  • ps_continue_text() - 次の行にテキストを続ける


指定された位置にテキストを出力する

  • ≪ ps_show_boxed
  • ps_show_xy2 ≫
  • PHP Manual
  • PS 関数
  • 指定された位置にテキストを出力する

ps_show_xy

(PECL ps >= 1.1.0)

ps_show_xy — 指定された位置にテキストを出力する

説明

ps_show_xy(
resource $psdoc,
string $text,
float $x,
float $y
): bool

指定された位置にテキストを出力します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

出力するテキスト。

x

テキストを囲むボックスの左下角の x 座標。

y

テキストを囲むボックスの左下角の y 座標。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_continue_text() - 次の行にテキストを続ける
  • ps_show() - テキストを出力する


テキストを指定した位置に出力する

  • ≪ ps_show_xy
  • ps_show2 ≫
  • PHP Manual
  • PS 関数
  • テキストを指定した位置に出力する

ps_show_xy2

(PECL ps >= 1.1.0)

ps_show_xy2 — テキストを指定した位置に出力する

説明

ps_show_xy2(
resource $psdoc,
string $text,
int $len,
float $xcoor,
float $ycoor
): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。


テキストを現在の位置に出力する

  • ≪ ps_show_xy2
  • ps_string_geometry ≫
  • PHP Manual
  • PS 関数
  • テキストを現在の位置に出力する

ps_show2

(PECL ps >= 1.1.0)

ps_show2 — テキストを現在の位置に出力する

説明

ps_show2(resource $psdoc, string $text, int $len): bool

テキストを現在の位置に出力します。最大 len 文字までしか出力しません。

パラメータ

psdoc

ps_new() が返す postscript ファイルの ID リソース。

text

出力するテキスト。

len

表示する最大文字数。

戻り値

成功した場合に true を、失敗した場合に false を返します。


文字列のジオメトリを取得する

  • ≪ ps_show2
  • ps_stringwidth ≫
  • PHP Manual
  • PS 関数
  • 文字列のジオメトリを取得する

ps_string_geometry

(PECL ps >= 1.2.0)

ps_string_geometry — 文字列のジオメトリを取得する

説明

ps_string_geometry(
resource $psdoc,
string $text,
int $fontid = 0,
float $size = 0.0
): array

この関数は ps_stringwidth() と似ていますが、 戻り値は、テキストの幅、ascender および descender を含む配列形式になります。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

ジオメトリを計算するテキスト。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

size

フォントのサイズ。指定されていない場合は現在のサイズが使用されます。

戻り値

文字の寸法を格納した配列です。'width' には ps_stringwidth() で返される文字列の幅が入ります。 下に突き出している部分の長さの最大値が 'descender' に、 また上に突き出している部分の長さの最大値が 'ascender' に入ります。

参考

  • ps_continue_text() - 次の行にテキストを続ける
  • ps_stringwidth() - 文字列の幅を取得する


文字列の幅を取得する

  • ≪ ps_string_geometry
  • ps_stroke ≫
  • PHP Manual
  • PS 関数
  • 文字列の幅を取得する

ps_stringwidth

(PECL ps >= 1.1.0)

ps_stringwidth — 文字列の幅を取得する

説明

ps_stringwidth(
resource $psdoc,
string $text,
int $fontid = 0,
float $size = 0.0
): float

指定されたフォントとサイズで出力した場合に、 文字列の幅が何ポイントになるかを計算します。 正確な幅を計算するため、この関数には Adobe のフォントメトリックファイルが必要です。カーニングが有効になっている場合、 それも考慮して計算します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

text

幅を計算するテキスト。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

size

フォントのサイズ。指定されていない場合は現在のサイズが使用されます。

戻り値

文字列の幅をポイント数で返します。

参考

  • ps_string_geometry() - 文字列のジオメトリを取得する


現在のパスを描画する

  • ≪ ps_stringwidth
  • ps_symbol ≫
  • PHP Manual
  • PS 関数
  • 現在のパスを描画する

ps_stroke

(PECL ps >= 1.1.0)

ps_stroke — 現在のパスを描画する

説明

ps_stroke(resource $psdoc): bool

ps_lineto() のような関数で事前に組み立てられたパスを描画します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_closepath_stroke() - パスを閉じ、描画する
  • ps_fill() - 現在のパスを塗りつぶす
  • ps_fill_stroke() - 現在のパスを塗りつぶし、線を引く


グリフを出力する

  • ≪ ps_stroke
  • ps_symbol_name ≫
  • PHP Manual
  • PS 関数
  • グリフを出力する

ps_symbol

(PECL ps >= 1.2.0)

ps_symbol — グリフを出力する

説明

ps_symbol(resource $psdoc, int $ord): bool

現在のフォントのフォントエンコーディングベクタの中で ord 番目の位置にあるグリフを出力します。 フォントエンコーディングは、ps_findfont() でフォントを読み込む際に設定することができます。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

ord

フォントエンコーディングベクタの中でのグリフの位置。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ps_symbol_name() - グリフ名を取得する
  • ps_symbol_width() - グリフの幅を取得する


グリフ名を取得する

  • ≪ ps_symbol
  • ps_symbol_width ≫
  • PHP Manual
  • PS 関数
  • グリフ名を取得する

ps_symbol_name

(PECL ps >= 1.2.0)

ps_symbol_name — グリフ名を取得する

説明

ps_symbol_name(resource $psdoc, int $ord, int $fontid = 0): string

この関数には、有効なグリフ名を取得するために Adobe のフォントメトリックファイルが必要です。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

ord

ord は、フォントエンコーディングベクタ の中でのグリフの位置です。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

戻り値

指定されたフォントのグリフ名を返します。

参考

  • ps_symbol() - グリフを出力する
  • ps_symbol_width() - グリフの幅を取得する


グリフの幅を取得する

  • ≪ ps_symbol_name
  • ps_translate ≫
  • PHP Manual
  • PS 関数
  • グリフの幅を取得する

ps_symbol_width

(PECL ps >= 1.2.0)

ps_symbol_width — グリフの幅を取得する

説明

ps_symbol_width(
resource $psdoc,
int $ord,
int $fontid = 0,
float $size = 0.0
): float

指定されたフォントとサイズで出力した場合に、 グリフの幅が何ポイントになるかを計算します。正確な幅を計算するため、 この関数には Adobe のフォントメトリックファイルが必要です。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

ord

ord は、 フォントエンコーディングベクタの中でのグリフの位置です。

fontid

使用するフォントの ID。フォントが指定されていない場合は、 現在のフォントが使用されます。

size

フォントのサイズ。指定されていない場合は現在のサイズが使用されます。

戻り値

グリフの幅をポイント数で返します。

参考

  • ps_symbol() - グリフを出力する
  • ps_symbol_name() - グリフ名を取得する


座標変換を設定する

  • ≪ ps_symbol_width
  • RpmInfo ≫
  • PHP Manual
  • PS 関数
  • 座標変換を設定する

ps_translate

(PECL ps >= 1.1.0)

ps_translate — 座標変換を設定する

説明

ps_translate(resource $psdoc, float $x, float $y): bool

新しい座標系の原点を設定します。

パラメータ

psdoc

ps_new() が返す、postscript ファイルのリソース ID。

x

変換後の座標系の原点の x 座標。

y

変換後の座標系の原点の y 座標。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 座標系の変換

<?php
function rectangle($ps) {
ps_moveto($ps, 0, 0);
ps_lineto($ps, 0, 50);
ps_lineto($ps, 50, 50);
ps_lineto($ps, 50, 0);
ps_lineto($ps, 0, 0);
ps_stroke($ps);
}

$ps = ps_new();
if (!ps_open_file($ps, "translate.ps")) {
print "Cannot open PostScript file\n";
exit;
}

ps_set_info($ps, "Creator", "translate.php");
ps_set_info($ps, "Author", "Uwe Steinmann");
ps_set_info($ps, "Title", "Translated example");
ps_set_info($ps, "BoundingBox", "0 0 596 842");

$psfont = ps_findfont($ps, "Helvetica", "", 0);

ps_begin_page($ps, 596, 842);
ps_set_text_pos($ps, 100, 100);
ps_translate($ps, 500, 750);
rectangle($ps);
ps_translate($ps, -500, -750);
ps_setfont($ps, $psfont, 8.0);
ps_show($ps, "Text at initial position");
ps_end_page($ps);

ps_begin_page($ps, 596, 842);
ps_set_text_pos($ps, 100, 100);
ps_save($ps);
ps_translate($ps, 500, 750);
rectangle($ps);
ps_restore($ps);
ps_setfont($ps, $psfont, 8.0);
ps_show($ps, "Text at initial position");
ps_end_page($ps);

ps_delete($ps);
?>

上の例は、図形 (ここでは単なる矩形) を、図形自身の座標系を使用したまま ページ内の任意の位置に配置するための 2 種類の方法を示しています。 矩形を描画する前に、座標系の原点を変更しているのがポイントです。 矩形を描画した後は、座標系をもとに戻さなければなりません。

2 ページ目では、少し異なった、よりエレガントな方法を使用しています。 座標系の変換を元に戻すために ps_translate() をもう一度コールするのではなく、 座標系の変更前に描画コンテキストを保存しておいて、 矩形の描画後にそれを復元しています。

参考

  • ps_scale() - 縮尺を設定する
  • ps_rotate() - 回転の程度を設定する


RpmInfo

  • はじめに
  • インストール/設定
    • 要件
    • Installation via PECL
  • 定義済み定数
  • RpmInfo 関数
    • rpmaddtag — Add tag retrieved in query
    • rpmdbinfo — Get information from installed RPM
    • rpmdbsearch — Search RPM packages
    • rpmgetsymlink — Get target of a symlink
    • rpminfo — Get information from a RPM file
    • rpmvercmp — RPM version comparison


はじめに

This extension enables you to retrieve information from RPM files or from the installed RPMs database.

It also provides a rpm stream wrapper to retrieve RPM content (since version 1.0.0 with librpm >= 4.13).


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • RpmInfo
  • インストール/設定

インストール/設定

目次

  • 要件
  • Installation via PECL


  • ≪ インストール/設定
  • Installation via PECL ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

This extension requires » librpm version 4.11.3 or higher.


Installation via PECL

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/rpminfo.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RPMVERSION (string)
System librpm version.
RPMSENSE_ANY (int)
RPMSENSE_LESS (int)
RPMSENSE_GREATER (int)
RPMSENSE_EQUAL (int)
RPMSENSE_POSTTRANS (int)
RPMSENSE_PREREQ (int)
RPMSENSE_PRETRANS (int)
RPMSENSE_INTERP (int)
RPMSENSE_SCRIPT_PRE (int)
RPMSENSE_SCRIPT_POST (int)
RPMSENSE_SCRIPT_PREUN (int)
RPMSENSE_SCRIPT_POSTUN (int)
RPMSENSE_SCRIPT_VERIFY (int)
RPMSENSE_FIND_REQUIRES (int)
RPMSENSE_FIND_PROVIDES (int)
RPMSENSE_TRIGGERIN (int)
RPMSENSE_TRIGGERUN (int)
RPMSENSE_TRIGGERPOSTUN (int)
RPMSENSE_MISSINGOK (int)
RPMSENSE_RPMLIB (int)
RPMSENSE_TRIGGERPREIN (int)
RPMSENSE_KEYRING (int)
RPMSENSE_CONFIG (int)
RPMMIRE_DEFAULT (int)
Search pattern is a regular expression with \., .* and ^...$ added.
RPMMIRE_STRCMP (int)
Search pattern is a string, using strcmp(3).
RPMMIRE_REGEX (int)
Search pattern is a regular expression, using regcomp(3).
RPMMIRE_GLOB (int)
Search pattern is a glob expression, using fnmatch(3).
RPMTAG_ARCH (int)
RPMTAG_ARCHSUFFIX (int)
Requires librpm >= 4.18
RPMTAG_ARCHIVESIZE (int)
RPMTAG_BASENAMES (int)
Name (not path) of files, with database index.
RPMTAG_BUGURL (int)
RPMTAG_BUILDARCHS (int)
RPMTAG_BUILDHOST (int)
RPMTAG_BUILDTIME (int)
RPMTAG_C (int)
RPMTAG_CHANGELOGNAME (int)
RPMTAG_CHANGELOGTEXT (int)
RPMTAG_CHANGELOGTIME (int)
RPMTAG_CLASSDICT (int)
RPMTAG_CONFLICTFLAGS (int)
RPMTAG_CONFLICTNAME (int)
Conflicting dependencies, with database index.
RPMTAG_CONFLICTNEVRS (int)
RPMTAG_CONFLICTS (int)
RPMTAG_CONFLICTVERSION (int)
RPMTAG_COOKIE (int)
RPMTAG_DBINSTANCE (int)
RPMTAG_DEPENDSDICT (int)
RPMTAG_DESCRIPTION (int)
RPMTAG_DIRINDEXES (int)
RPMTAG_DIRNAMES (int)
Directory of files, with database index.
RPMTAG_DISTRIBUTION (int)
RPMTAG_DISTTAG (int)
RPMTAG_DISTURL (int)
RPMTAG_DSAHEADER (int)
RPMTAG_E (int)
RPMTAG_ENCODING (int)
RPMTAG_ENHANCEFLAGS (int)
RPMTAG_ENHANCENAME (int)
Weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_ENHANCENEVRS (int)
RPMTAG_ENHANCES (int)
RPMTAG_ENHANCEVERSION (int)
RPMTAG_EPOCH (int)
RPMTAG_EPOCHNUM (int)
RPMTAG_EVR (int)
RPMTAG_EXCLUDEARCH (int)
RPMTAG_EXCLUDEOS (int)
RPMTAG_EXCLUSIVEARCH (int)
RPMTAG_EXCLUSIVEOS (int)
RPMTAG_FILECAPS (int)
RPMTAG_FILECLASS (int)
RPMTAG_FILECOLORS (int)
RPMTAG_FILECONTEXTS (int)
RPMTAG_FILEDEPENDSN (int)
RPMTAG_FILEDEPENDSX (int)
RPMTAG_FILEDEVICES (int)
RPMTAG_FILEDIGESTALGO (int)
RPMTAG_FILEDIGESTS (int)
RPMTAG_FILEFLAGS (int)
RPMTAG_FILEGROUPNAME (int)
RPMTAG_FILEINODES (int)
RPMTAG_FILELANGS (int)
RPMTAG_FILELINKTOS (int)
RPMTAG_FILEMD5S (int)
RPMTAG_FILEMODES (int)
RPMTAG_FILEMTIMES (int)
RPMTAG_FILENAMES (int)
RPMTAG_FILENLINKS (int)
RPMTAG_FILEPROVIDE (int)
RPMTAG_FILERDEVS (int)
RPMTAG_FILEREQUIRE (int)
RPMTAG_FILESIGNATURELENGTH (int)
RPMTAG_FILESIGNATURES (int)
RPMTAG_FILESIZES (int)
RPMTAG_FILESTATES (int)
RPMTAG_FILETRIGGERCONDS (int)
RPMTAG_FILETRIGGERFLAGS (int)
RPMTAG_FILETRIGGERINDEX (int)
RPMTAG_FILETRIGGERNAME (int)
File trigger name, with database index, requires librpm >= 4.13.
RPMTAG_FILETRIGGERPRIORITIES (int)
RPMTAG_FILETRIGGERSCRIPTFLAGS (int)
RPMTAG_FILETRIGGERSCRIPTPROG (int)
RPMTAG_FILETRIGGERSCRIPTS (int)
RPMTAG_FILETRIGGERTYPE (int)
RPMTAG_FILETRIGGERVERSION (int)
RPMTAG_FILEUSERNAME (int)
RPMTAG_FILEVERIFYFLAGS (int)
RPMTAG_FSCONTEXTS (int)
RPMTAG_GIF (int)
RPMTAG_GROUP (int)
Group of the package, with database index.
RPMTAG_HDRID (int)
RPMTAG_HEADERCOLOR (int)
RPMTAG_HEADERI18NTABLE (int)
RPMTAG_HEADERIMAGE (int)
RPMTAG_HEADERIMMUTABLE (int)
RPMTAG_HEADERREGIONS (int)
RPMTAG_HEADERSIGNATURES (int)
RPMTAG_ICON (int)
RPMTAG_INSTALLCOLOR (int)
RPMTAG_INSTALLTID (int)
Installation transaction ID, with database index.
RPMTAG_INSTALLTIME (int)
RPMTAG_INSTFILENAMES (int)
Path of files, with database index.
RPMTAG_INSTPREFIXES (int)
RPMTAG_LICENSE (int)
RPMTAG_LONGARCHIVESIZE (int)
RPMTAG_LONGFILESIZES (int)
RPMTAG_LONGSIGSIZE (int)
RPMTAG_LONGSIZE (int)
RPMTAG_MODULARITYLABEL (int)
RPMTAG_N (int)
RPMTAG_NAME (int)
Package name, with database index.
RPMTAG_NEVR (int)
RPMTAG_NEVRA (int)
RPMTAG_NOPATCH (int)
RPMTAG_NOSOURCE (int)
RPMTAG_NVR (int)
RPMTAG_NVRA (int)
RPMTAG_O (int)
RPMTAG_OBSOLETEFLAGS (int)
RPMTAG_OBSOLETENAME (int)
Obsoleted packages, with database index.
RPMTAG_OBSOLETENEVRS (int)
RPMTAG_OBSOLETES (int)
RPMTAG_OBSOLETEVERSION (int)
RPMTAG_OLDENHANCES (int)
RPMTAG_OLDENHANCESFLAGS (int)
RPMTAG_OLDENHANCESNAME (int)
RPMTAG_OLDENHANCESVERSION (int)
RPMTAG_OLDFILENAMES (int)
RPMTAG_OLDSUGGESTS (int)
RPMTAG_OLDSUGGESTSFLAGS (int)
RPMTAG_OLDSUGGESTSNAME (int)
RPMTAG_OLDSUGGESTSVERSION (int)
RPMTAG_OPTFLAGS (int)
RPMTAG_ORDERFLAGS (int)
RPMTAG_ORDERNAME (int)
RPMTAG_ORDERVERSION (int)
RPMTAG_ORIGBASENAMES (int)
RPMTAG_ORIGDIRINDEXES (int)
RPMTAG_ORIGDIRNAMES (int)
RPMTAG_ORIGFILENAMES (int)
RPMTAG_OS (int)
RPMTAG_P (int)
RPMTAG_PACKAGER (int)
RPMTAG_PATCH (int)
RPMTAG_PATCHESFLAGS (int)
RPMTAG_PATCHESNAME (int)
RPMTAG_PATCHESVERSION (int)
RPMTAG_PAYLOADCOMPRESSOR (int)
RPMTAG_PAYLOADDIGEST (int)
RPMTAG_PAYLOADDIGESTALT (int)
With librpm >= 4.16.
RPMTAG_PAYLOADDIGESTALGO (int)
RPMTAG_PAYLOADFLAGS (int)
RPMTAG_PAYLOADFORMAT (int)
RPMTAG_PKGID (int)
RPMTAG_PLATFORM (int)
RPMTAG_POLICIES (int)
RPMTAG_POLICYFLAGS (int)
RPMTAG_POLICYNAMES (int)
RPMTAG_POLICYTYPES (int)
RPMTAG_POLICYTYPESINDEXES (int)
RPMTAG_POSTIN (int)
RPMTAG_POSTINFLAGS (int)
RPMTAG_POSTINPROG (int)
RPMTAG_POSTTRANS (int)
RPMTAG_POSTTRANSFLAGS (int)
RPMTAG_POSTTRANSPROG (int)
RPMTAG_POSTUN (int)
RPMTAG_POSTUNFLAGS (int)
RPMTAG_POSTUNPROG (int)
RPMTAG_POSTUNTRANS (int)
Requires librpm >= 4.19
RPMTAG_POSTUNTRANSFLAGS (int)
Requires librpm >= 4.19
RPMTAG_POSTUNTRANSPROG (int)
Requires librpm >= 4.19
RPMTAG_PREFIXES (int)
RPMTAG_PREIN (int)
RPMTAG_PREINFLAGS (int)
RPMTAG_PREINPROG (int)
RPMTAG_PRETRANS (int)
RPMTAG_PRETRANSFLAGS (int)
RPMTAG_PRETRANSPROG (int)
RPMTAG_PREUN (int)
RPMTAG_PREUNFLAGS (int)
RPMTAG_PREUNPROG (int)
RPMTAG_PREUNTRANS (int)
Requires librpm >= 4.19
RPMTAG_PREUNTRANSFLAGS (int)
Requires librpm >= 4.19
RPMTAG_PREUNTRANSPROG (int)
Requires librpm >= 4.19
RPMTAG_PROVIDEFLAGS (int)
RPMTAG_PROVIDENAME (int)
Provided dependencies, with database index.
RPMTAG_PROVIDENEVRS (int)
RPMTAG_PROVIDES (int)
RPMTAG_PROVIDEVERSION (int)
RPMTAG_PUBKEYS (int)
RPMTAG_R (int)
RPMTAG_RECOMMENDFLAGS (int)
RPMTAG_RECOMMENDNAME (int)
Recommended weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_RECOMMENDNEVRS (int)
RPMTAG_RECOMMENDS (int)
RPMTAG_RECOMMENDVERSION (int)
RPMTAG_RECONTEXTS (int)
RPMTAG_RELEASE (int)
RPMTAG_REMOVETID (int)
RPMTAG_REQUIREFLAGS (int)
RPMTAG_REQUIRENAME (int)
Required dependencies, with database index.
RPMTAG_REQUIRENEVRS (int)
RPMTAG_REQUIRES (int)
RPMTAG_REQUIREVERSION (int)
RPMTAG_RPMVERSION (int)
RPMTAG_RSAHEADER (int)
RPMTAG_SHA1HEADER (int)
SHA1 signature, with database index.
RPMTAG_SHA256HEADER (int)
RPMTAG_SIGGPG (int)
RPMTAG_SIGMD5 (int)
MD5 signature, with database index.
RPMTAG_SIGPGP (int)
RPMTAG_SIGSIZE (int)
RPMTAG_SIZE (int)
RPMTAG_SOURCE (int)
RPMTAG_SOURCEPACKAGE (int)
RPMTAG_SOURCEPKGID (int)
RPMTAG_SOURCERPM (int)
RPMTAG_SPEC (int)
Requires librpm >= 4.18
RPMTAG_SUGGESTFLAGS (int)
RPMTAG_SUGGESTNAME (int)
Suggested weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_SUGGESTNEVRS (int)
RPMTAG_SUGGESTS (int)
RPMTAG_SUGGESTVERSION (int)
RPMTAG_SUMMARY (int)
RPMTAG_SUPPLEMENTFLAGS (int)
RPMTAG_SUPPLEMENTNAME (int)
Weak dependencies, with database index, requires librpm >= 4.13.
RPMTAG_SUPPLEMENTNEVRS (int)
RPMTAG_SUPPLEMENTS (int)
RPMTAG_SUPPLEMENTVERSION (int)
RPMTAG_SYSUSERS (int)
Requires librpm >= 4.19
RPMTAG_TRANSFILETRIGGERCONDS (int)
RPMTAG_TRANSFILETRIGGERFLAGS (int)
RPMTAG_TRANSFILETRIGGERINDEX (int)
RPMTAG_TRANSFILETRIGGERNAME (int)
Transaction file trigger name, with database index, requires librpm >= 4.13.
RPMTAG_TRANSFILETRIGGERPRIORITIES (int)
RPMTAG_TRANSFILETRIGGERSCRIPTFLAGS (int)
RPMTAG_TRANSFILETRIGGERSCRIPTPROG (int)
RPMTAG_TRANSFILETRIGGERSCRIPTS (int)
RPMTAG_TRANSFILETRIGGERTYPE (int)
RPMTAG_TRANSFILETRIGGERVERSION (int)
RPMTAG_TRANSLATIONURL (int)
Requires librpm >= 4.18
RPMTAG_TRIGGERCONDS (int)
RPMTAG_TRIGGERFLAGS (int)
RPMTAG_TRIGGERINDEX (int)
RPMTAG_TRIGGERNAME (int)
Trigger name, with database index.
RPMTAG_TRIGGERSCRIPTFLAGS (int)
RPMTAG_TRIGGERSCRIPTPROG (int)
RPMTAG_TRIGGERSCRIPTS (int)
RPMTAG_TRIGGERTYPE (int)
RPMTAG_TRIGGERVERSION (int)
RPMTAG_UPSTREAMRELEASES (int)
Requires librpm >= 4.18
RPMTAG_URL (int)
RPMTAG_V (int)
RPMTAG_VCS (int)
RPMTAG_VENDOR (int)
RPMTAG_VERBOSE (int)
RPMTAG_VERIFYSCRIPT (int)
RPMTAG_VERIFYSCRIPTFLAGS (int)
RPMTAG_VERIFYSCRIPTPROG (int)
RPMTAG_VERITYSIGNATUREALGO (int)
With librpm >= 4.17.
RPMTAG_VERITYSIGNATURES (int)
With librpm >= 4.17.


RpmInfo 関数

目次

  • rpmaddtag — Add tag retrieved in query
  • rpmdbinfo — Get information from installed RPM
  • rpmdbsearch — Search RPM packages
  • rpmgetsymlink — Get target of a symlink
  • rpminfo — Get information from a RPM file
  • rpmvercmp — RPM version comparison


Add tag retrieved in query

  • ≪ RpmInfo 関数
  • rpmdbinfo ≫
  • PHP Manual
  • RpmInfo 関数
  • Add tag retrieved in query

rpmaddtag

(PECL rpminfo >= 0.5.0)

rpmaddtag — Add tag retrieved in query

説明

rpmaddtag(int $tag): bool

Add an additional retrieved tag in subsequent queries.

パラメータ

tag

One of RPMTAG_* constant, see the rpminfo constants page.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • rpminfo() - Get information from a RPM file
  • rpmdbinfo() - Get information from installed RPM
  • rpmdbsearch() - Search RPM packages


Get information from installed RPM

  • ≪ rpmaddtag
  • rpmdbsearch ≫
  • PHP Manual
  • RpmInfo 関数
  • Get information from installed RPM

rpmdbinfo

(PECL rpminfo >= 0.2.0)

rpmdbinfo — Get information from installed RPM

説明

rpmdbinfo(string $nevr, bool $full = false): ?array

Retrieve information about an installed package, from the system RPM database.

パラメータ

nevr

Name with optional epoch, version and release.

full

If true all information headers for the file are retrieved, else only a minimal set.

戻り値

An array of array of information or NULL on error.

例

例1 A rpmdbinfo() example

<?php
rpmaddtag(RPMTAG_INSTALLTIME);
$info = rpmdbinfo("php-pecl-rpminfo");
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [Name] => php-pecl-rpminfo
            [Version] => 0.4.2
            [Release] => 1.fc31
            [Summary] => RPM information
            [Installtime] => 1586244687
            [Arch] => x86_64
        )
)

参考

  • rpmaddtag() - Add tag retrieved in query


Search RPM packages

  • ≪ rpmdbinfo
  • rpmgetsymlink ≫
  • PHP Manual
  • RpmInfo 関数
  • Search RPM packages

rpmdbsearch

(PECL rpminfo >= 0.3.0)

rpmdbsearch — Search RPM packages

説明

rpmdbsearch(
string $pattern,
int $rpmtag = RPMTAG_NAME,
int $rpmmire = -1,
bool $full = false
): ?array

Search packages in the system RPM database.

パラメータ

pattern

Value to search for.

rpmtag

Search criterion, one of RPMTAG_* constant, see the rpminfo constants page.

rpmmire

Pattern type, one of RPMMIRE_* constant, see the rpminfo constants page. When < 0 the criterion must equals the value, and database index is used if possible.

full

If true all information headers for the file are retrieved, else only a minimal set.

戻り値

An array of array of information or NULL on error.

例

例1 Searching for the package owning a file

<?php
$info = rpmdbsearch("/usr/bin/php", RPMTAG_INSTFILENAMES);
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [Name] => php-cli
            [Version] => 7.4.4
            [Release] => 1.fc32
            [Summary] => Command-line interface for PHP
            [Arch] => x86_64
        )

)

参考

  • rpmaddtag() - Add tag retrieved in query


Get target of a symlink

  • ≪ rpmdbsearch
  • rpminfo ≫
  • PHP Manual
  • RpmInfo 関数
  • Get target of a symlink

rpmgetsymlink

(PECL rpminfo >= 1.1.0)

rpmgetsymlink — Get target of a symlink

説明

rpmgetsymlink(string $path, string $name): ?string

Get target of a symlink.

パラメータ

path

Path of the RPM file.

name

Name of the symlink file.

戻り値

A string with target of the symlink, NULL on error, or an empty string if not a symlink.


Get information from a RPM file

  • ≪ rpmgetsymlink
  • rpmvercmp ≫
  • PHP Manual
  • RpmInfo 関数
  • Get information from a RPM file

rpminfo

(PECL rpminfo >= 0.1.0)

rpminfo — Get information from a RPM file

説明

rpminfo(string $path, bool $full = false, string &$error = ?): ?array

Retrieve information about a local file, a RPM package.

パラメータ

path

Path of the RPM file.

full

If true all information headers for the file are retrieved, else only a minimal set.

error

If provided, will receive the possible error message, and will avoid a runtime warning.

戻り値

An array of information or NULL on error.

例

例1 A rpminfo() example

<?php
rpmaddtag(RPMTAG_BUILDTIME);
$info = rpminfo("./php-pecl-rpminfo-0.4.2-1.el8.remi.7.4.x86_64.rpm");
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [Name] => php-pecl-rpminfo
    [Version] => 0.4.2
    [Release] => 1.el8
    [Summary] => RPM information
    [Buildtime] => 1586244821
    [Arch] => x86_64
)

参考

  • rpmaddtag() - Add tag retrieved in query


RPM version comparison

  • ≪ rpminfo
  • XLSWriter ≫
  • PHP Manual
  • RpmInfo 関数
  • RPM version comparison

rpmvercmp

(PECL rpminfo >= 0.1.0)

rpmvercmp — RPM version comparison

説明

rpmvercmp(string $evr1, string $evr2, ?string $operator = null): int|bool

Compare 2 RPM versions.

パラメータ

evr1

First epoch:version-release string

evr2

Second epoch:version-release string

operator

An optional operator. The possible operators are: <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne respectively.

This parameter is case-sensitive, values should be lowercase.

戻り値

Returns < 0 if evr1 is less than evr2, > 0 if evr1 is greater than evr2, and 0 if they are equal.

When using the optional operator argument, the function will return true if the relationship is the one specified by the operator, false otherwise.

変更履歴

バージョン | 説明
0.7.0 | Optional operator was added.


XLSWriter

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • Vtiful\Kernel\Excel — The Vtiful\Kernel\Excel class
    • Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet
    • Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter
    • Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory
    • Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor
    • Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data
    • Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName
    • Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle
    • Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header
    • Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula
    • Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage
    • Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText
    • Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells
    • Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output
    • Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn
    • Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow
  • Vtiful\Kernel\Format — The Vtiful\Kernel\Format class
    • Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align
    • Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold
    • Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic
    • Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline


  • ≪ XLSWriter
  • インストール/設定 ≫
  • PHP Manual
  • XLSWriter
  • はじめに

はじめに

効率的で高速な xlsx ファイル出力拡張モジュールです。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XLSWriter
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

XLSWriter requires PHP 7.0 and above.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xlswriter


リソース型

There is one resource used by the procedural version of the XLSWriter extension: returned by fileName() or \Vtiful\Kernel\Format.


The Vtiful\Kernel\Excel class

(PECL xlswriter >= 1.2.1)

はじめに

Create xlsx files and set cells and output xlsx files

クラス概要

class Vtiful\Kernel\Excel {
/* メソッド */
public __construct(array $config)
public addSheet(string $sheetName)
public autoFilter(string $scope)
public constMemory(string $fileName, string $sheetName = ?)
public data(array $data)
public fileName(string $fileName, string $sheetName = ?)
public getHandle()
public header(array $headerData)
public insertFormula(int $row, int $column, string $formula)
public insertImage(int $row, int $column, string $localImagePath)
public insertText(
int $row,
int $column,
int|float|string $data,
string $format = ?
)
public mergeCells(string $scope, string $data)
public output()
public setColumn(string $range, float $width, resource $format = ?)
public setRow(string $range, float $height, resource $format = ?)
}

目次

  • Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet
  • Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter
  • Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory
  • Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor
  • Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data
  • Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName
  • Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle
  • Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header
  • Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula
  • Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage
  • Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText
  • Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells
  • Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output
  • Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn
  • Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow


Vtiful\Kernel\Excel addSheet

  • ≪ Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel::autoFilter ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel addSheet

Vtiful\Kernel\Excel::addSheet

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet

説明

public Vtiful\Kernel\Excel::addSheet(string $sheetName)

Create a new worksheet in the xlsx file.

パラメータ

sheetName

Worksheet name

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
->header(['name', 'age'])
->data([
['viest', 23],
['wjx', 23]
]);

$file->addSheet('sheet_two')
->header(['name', 'age'])
->data([
['james', 33],
['king', 33]
]);

$file->output();
?>


Vtiful\Kernel\Excel autoFilter

  • ≪ Vtiful\Kernel\Excel::addSheet
  • Vtiful\Kernel\Excel::constMemory ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel autoFilter

Vtiful\Kernel\Excel::autoFilter

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter

説明

public Vtiful\Kernel\Excel::autoFilter(string $scope)

Add autofilter to a worksheet.

パラメータ

scope

Cell start and end coordinate string.

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName('test.xlsx')
->header(['name', 'age'])
->data($data)
->autoFilter('A1:B11') // auto filter
->output();
?>


Vtiful\Kernel\Excel constMemory

  • ≪ Vtiful\Kernel\Excel::autoFilter
  • Vtiful\Kernel\Excel::__construct ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel constMemory

Vtiful\Kernel\Excel::constMemory

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory

説明

public Vtiful\Kernel\Excel::constMemory(string $fileName, string $sheetName = ?)

Write a large file with constant memory usage.

パラメータ

fileName

XLSX file name

sheetName

Worksheet name

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => '/home/viest'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $instance->constMemory('tutorial.xlsx', 'sheet');
?>


Vtiful\Kernel\Excel constructor

  • ≪ Vtiful\Kernel\Excel::constMemory
  • Vtiful\Kernel\Excel::data ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel constructor

Vtiful\Kernel\Excel::__construct

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor

説明

public Vtiful\Kernel\Excel::__construct(array $config)

Vtiful\Kernel\Excel constructor, create a class object.

パラメータ

config

XLSX file export configuration

例

例1 example

<?php
$config = [
'path' => '/home/viest'
];

$excelObject = new \Vtiful\Kernel\Excel($config);
?>


Vtiful\Kernel\Excel data

  • ≪ Vtiful\Kernel\Excel::__construct
  • Vtiful\Kernel\Excel::fileName ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel data

Vtiful\Kernel\Excel::data

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data

説明

public Vtiful\Kernel\Excel::data(array $data)

Write a data in the worksheet.

パラメータ

data

worksheet data

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
->header(['name', 'age'])
->data([
['viest', 23],
['wjx', 23],
]);
?>


Vtiful\Kernel\Excel fileName

  • ≪ Vtiful\Kernel\Excel::data
  • Vtiful\Kernel\Excel::getHandle ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel fileName

Vtiful\Kernel\Excel::fileName

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName

説明

public Vtiful\Kernel\Excel::fileName(string $fileName, string $sheetName = ?)

Create a brand new xlsx file and create a worksheet.

パラメータ

fileName

XLSX file name

sheetName

Worksheet name

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => '/home/viest'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $instance->fileName('tutorial.xlsx', 'sheet');
?>


Vtiful\Kernel\Excel getHandle

  • ≪ Vtiful\Kernel\Excel::fileName
  • Vtiful\Kernel\Excel::header ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel getHandle

Vtiful\Kernel\Excel::getHandle

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle

説明

public Vtiful\Kernel\Excel::getHandle()

Get the xlsx text resource handle.

パラメータ

この関数にはパラメータはありません。

戻り値

Resource

例

例1 example

<?php
$config = [
'path' => './tests'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
->header(['name', 'age']);

$handle = $file->getHandle();
?>


Vtiful\Kernel\Excel header

  • ≪ Vtiful\Kernel\Excel::getHandle
  • Vtiful\Kernel\Excel::insertFormula ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel header

Vtiful\Kernel\Excel::header

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header

説明

public Vtiful\Kernel\Excel::header(array $headerData)

Write a header in the worksheet.

パラメータ

headerData

worksheet header data

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
->header(['name', 'age']);
?>


Vtiful\Kernel\Excel insertFormula

  • ≪ Vtiful\Kernel\Excel::header
  • Vtiful\Kernel\Excel::insertImage ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel insertFormula

Vtiful\Kernel\Excel::insertFormula

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula

説明

public Vtiful\Kernel\Excel::insertFormula(int $row, int $column, string $formula)

Insert calculation formula.

パラメータ

row

cell row

column

cell column

formula

formula string

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName("free.xlsx")
->header(['name', 'money']);

for($index = 1; $index < 10; $index++) {
$file->insertText($index, 0, 'viest');
$file->insertText($index, 1, 10);
}

$file->insertText(12, 0, "Total");
$file->insertFormula(12, 1, '=SUM(B2:B11)'); // insert formula

$file->output();


Vtiful\Kernel\Excel insertImage

  • ≪ Vtiful\Kernel\Excel::insertFormula
  • Vtiful\Kernel\Excel::insertText ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel insertImage

Vtiful\Kernel\Excel::insertImage

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage

説明

public Vtiful\Kernel\Excel::insertImage(int $row, int $column, string $localImagePath)

Insert a local image into the cell.

パラメータ

row

cell row

column

cell column

localImagePath

local image path

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName("free.xlsx");

$file->insertImage(5, 0, '/vagrant/ASW-G-66.jpg');

$file->output();


Vtiful\Kernel\Excel insertText

  • ≪ Vtiful\Kernel\Excel::insertImage
  • Vtiful\Kernel\Excel::mergeCells ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel insertText

Vtiful\Kernel\Excel::insertText

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText

説明

public Vtiful\Kernel\Excel::insertText(
int $row,
int $column,
int|float|string $data,
string $format = ?
)

Write text in a cell.

パラメータ

row

cell row

column

cell column

data

data to be written

format

String format

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$file = $excel->fileName("free.xlsx")
->header(['name', 'money']);

for ($index = 0; $index < 10; $index++) {
$file->insertText($index+1, 0, 'viest');
$file->insertText($index+1, 1, 10000, '#,##0');
}

$textFile->output();


Vtiful\Kernel\Excel mergeCells

  • ≪ Vtiful\Kernel\Excel::insertText
  • Vtiful\Kernel\Excel::output ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel mergeCells

Vtiful\Kernel\Excel::mergeCells

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells

説明

public Vtiful\Kernel\Excel::mergeCells(string $scope, string $data)

Merge Cells.

パラメータ

scope

cell start and end coordinate strings

data

string data

戻り値

Vtiful\Kernel\Excel instance

例

例1 example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);

$excel->fileName("test.xlsx")
->mergeCells('A1:C1', 'Merge cells')
->output();


Vtiful\Kernel\Excel output

  • ≪ Vtiful\Kernel\Excel::mergeCells
  • Vtiful\Kernel\Excel::setColumn ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel output

Vtiful\Kernel\Excel::output

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output

説明

public Vtiful\Kernel\Excel::output()

Output xlsx file to disk.

パラメータ

この関数にはパラメータはありません。

戻り値

XLSX file path;

例

例1 example

<?php
$config = [
'path' => './tests'
];

$fileObject = new \Vtiful\Kernel\Excel($config);

$file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
->header(['name', 'age'])
->data([
['viest', 23],
['wjx', 23],
]);

$path = $file->output();
?>


Vtiful\Kernel\Excel setColumn

  • ≪ Vtiful\Kernel\Excel::output
  • Vtiful\Kernel\Excel::setRow ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel setColumn

Vtiful\Kernel\Excel::setColumn

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn

説明

public Vtiful\Kernel\Excel::setColumn(string $range, float $width, resource $format = ?)

Set the format of the column.

パラメータ

range

cell start and end coordinate strings

width

column width

format

cell format resource

戻り値

Vtiful\Kernel\Excel instance

例

例1 setColumn example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);
$excel->fileName('tutorial01.xlsx');

$format = new \Vtiful\Kernel\Format($excel->getHandle());
$boldStyle = $format->bold()->toResource();

$excel->header(['name', 'age'])
->data([['viest', 21]])
->setColumn('A:A', 200, $boldStyle)
->output();


Vtiful\Kernel\Excel setRow

  • ≪ Vtiful\Kernel\Excel::setColumn
  • Vtiful\Kernel\Format ≫
  • PHP Manual
  • Vtiful\Kernel\Excel
  • Vtiful\Kernel\Excel setRow

Vtiful\Kernel\Excel::setRow

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow

説明

public Vtiful\Kernel\Excel::setRow(string $range, float $height, resource $format = ?)

Set the format of the row.

パラメータ

range

cell start and end coordinate strings

height

row height

format

cell format resource

戻り値

Vtiful\Kernel\Excel instance

例

例1 setRow example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);
$excel->fileName('tutorial01.xlsx');

$format = new \Vtiful\Kernel\Format($excel->getHandle());
$boldStyle = $format->bold()->toResource();

$excel->header(['name', 'age'])
->data([['viest', 21]])
->setRow('A1', 20, $boldStyle)
->output();


The Vtiful\Kernel\Format class

(PECL xlswriter >= 1.2.1)

はじめに

Create a cell format object

クラス概要

class Vtiful\Kernel\Format {
/* 定数 */
const int FORMAT_ALIGN_LEFT = 1;
const int FORMAT_ALIGN_CENTER = 2;
const int FORMAT_ALIGN_RIGHT = 3;
const int FORMAT_ALIGN_FILL = 4;
const int FORMAT_ALIGN_JUSTIFY = 5;
const int FORMAT_ALIGN_CENTER_ACROSS = 6;
const int FORMAT_ALIGN_DISTRIBUTED = 7;
const int FORMAT_ALIGN_VERTICAL_TOP = 8;
const int FORMAT_ALIGN_VERTICAL_BOTTOM = 9;
const int FORMAT_ALIGN_VERTICAL_CENTER = 10;
const int FORMAT_ALIGN_VERTICAL_JUSTIFY = 11;
const int FORMAT_ALIGN_VERTICAL_DISTRIBUTED = 12;
const int UNDERLINE_SINGLE = 1;
const int UNDERLINE_DOUBLE = 2;
const int UNDERLINE_SINGLE_ACCOUNTING = 3;
const int UNDERLINE_DOUBLE_ACCOUNTING = 4;
/* メソッド */
public align(resource $handle, int $style)
public bold(resource $handle)
public italic(resource $handle)
public underline(resource $handle, int $style)
}

定義済み定数

Vtiful\Kernel\Format::FORMAT_ALIGN_LEFT

Vtiful\Kernel\Format::FORMAT_ALIGN_CENTER

Vtiful\Kernel\Format::FORMAT_ALIGN_RIGHT

Vtiful\Kernel\Format::FORMAT_ALIGN_FILL

Vtiful\Kernel\Format::FORMAT_ALIGN_JUSTIFY

Vtiful\Kernel\Format::FORMAT_ALIGN_CENTER_ACROSS

Vtiful\Kernel\Format::FORMAT_ALIGN_DISTRIBUTED

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_TOP

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_BOTTOM

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_CENTER

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_JUSTIFY

Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_DISTRIBUTED

Vtiful\Kernel\Format::UNDERLINE_SINGLE

Vtiful\Kernel\Format::UNDERLINE_DOUBLE

Vtiful\Kernel\Format::UNDERLINE_SINGLE_ACCOUNTING

Vtiful\Kernel\Format::UNDERLINE_DOUBLE_ACCOUNTING

目次

  • Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align
  • Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold
  • Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic
  • Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline


Vtiful\Kernel\Format align

  • ≪ Vtiful\Kernel\Format
  • Vtiful\Kernel\Format::bold ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format align

Vtiful\Kernel\Format::align

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::align — Vtiful\Kernel\Format align

説明

public Vtiful\Kernel\Format::align(resource $handle, int $style)

set cell align

パラメータ

handle

xlsx file handle

style

Vtiful\Kernel\Format constant

戻り値

Resource

例

例1 Align style example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);
$excel->fileName('tutorial01.xlsx');

$format = new \Vtiful\Kernel\Format($excel->getHandle());
$alignStyle = $format->align(\Vtiful\Kernel\Format::FORMAT_ALIGN_LEFT)->toResource();

$excel->header(['name', 'age'])
->data([['viest', 21]])
->setColumn('A:A', 200, $alignStyle)
->output();
?>


Vtiful\Kernel\Format bold

  • ≪ Vtiful\Kernel\Format::align
  • Vtiful\Kernel\Format::italic ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format bold

Vtiful\Kernel\Format::bold

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::bold — Vtiful\Kernel\Format bold

説明

public Vtiful\Kernel\Format::bold(resource $handle)

Vtiful\Kernel\Format bold format

パラメータ

handle

xlsx file handle

戻り値

Resource

例

例1 Bold style example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);
$excel->fileName('tutorial01.xlsx');

$format = new \Vtiful\Kernel\Format($excel->getHandle());
$boldStyle = $format->bold()->toResource();

$excel->header(['name', 'age'])
->data([['viest', 21]])
->setColumn('A:A', 200, $boldStyle)
->output();
?>


Vtiful\Kernel\Format italic

  • ≪ Vtiful\Kernel\Format::bold
  • Vtiful\Kernel\Format::underline ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format italic

Vtiful\Kernel\Format::italic

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::italic — Vtiful\Kernel\Format italic

説明

public Vtiful\Kernel\Format::italic(resource $handle)

Vtiful\Kernel\Format italic format

パラメータ

handle

xlsx file handle

戻り値

Resource

例

例1 Italic style example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);
$excel->fileName('tutorial01.xlsx');

$format = new \Vtiful\Kernel\Format($excel->getHandle());
$italicStyle = $format->italic()->toResource();

$excel->header(['name', 'age'])
->data([['viest', 21]])
->setColumn('A:A', 200, $italicStyle)
->output();
?>


Vtiful\Kernel\Format underline

  • ≪ Vtiful\Kernel\Format::italic
  • プロセス制御 ≫
  • PHP Manual
  • Vtiful\Kernel\Format
  • Vtiful\Kernel\Format underline

Vtiful\Kernel\Format::underline

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Format::underline — Vtiful\Kernel\Format underline

説明

public Vtiful\Kernel\Format::underline(resource $handle, int $style)

Vtiful\Kernel\Format underline format

パラメータ

handle

xlsx file handle

style

Vtiful\Kernel\Format constant

戻り値

Resource

例

例1 Underline style example

<?php
$config = [
'path' => './tests'
];

$excel = new \Vtiful\Kernel\Excel($config);
$excel->fileName('tutorial01.xlsx');

$format = new \Vtiful\Kernel\Format($excel->getHandle());
$underlineStyle = $format->underline(\Vtiful\Kernel\Format::UNDERLINE_SINGLE)->toResource();

$excel->header(['name', 'age'])
->data([['viest', 21]])
->setColumn('A:A', 200, $underlineStyle)
->output();
?>


プロセス制御

  • Eio
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Eio 関数
  • Ev
    • はじめに
    • インストール/設定
    • 例
    • ウォッチャー
    • ウォッチャーのコールバック
    • Periodic ウォッチャーの操作モード
    • Ev — Ev クラス
    • EvCheck — EvCheck クラス
    • EvChild — The EvChild class
    • EvEmbed — EvEmbed クラス
    • EvFork — EvFork クラス
    • EvIdle — The EvIdle class
    • EvIo — The EvIo class
    • EvLoop — The EvLoop class
    • EvPeriodic — The EvPeriodic class
    • EvPrepare — EvPrepare クラス
    • EvSignal — The EvSignal class
    • EvStat — The EvStat class
    • EvTimer — The EvTimer class
    • EvWatcher — The EvWatcher class
  • Expect
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Expect 関数
  • PCNTL — プロセス制御
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PCNTL 関数
  • POSIX
    • はじめに
    • インストール/設定
    • 定義済み定数
    • POSIX 関数
  • プログラムの実行 — システムプログラムの実行
    • はじめに
    • インストール/設定
    • プログラム実行関数
  • parallel
    • はじめに
    • Installation
    • Philosophy
    • Functional API
    • parallel\Runtime — The parallel\Runtime class
    • parallel\Future — The parallel\Future class
    • parallel\Channel — The parallel\Channel class
    • parallel\Events — The parallel\Events class
    • parallel\Events\Input — The parallel\Events\Input class
    • parallel\Events\Event — The parallel\Events\Event class
    • parallel\Events\Event\Type — The parallel\Events\Event\Type class
    • parallel\Sync — The parallel\Sync class
  • pthreads
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Threaded — The Threaded class
    • Thread — Thread クラス
    • Worker — Worker クラス
    • Collectable — The Collectable interface
    • Pool — The Pool class
    • Volatile — The Volatile class
  • セマフォ — セマフォ、共有メモリおよび IPC
    • はじめに
    • インストール/設定
    • 定義済み定数
    • セマフォ関数
    • SysvMessageQueue — SysvMessageQueue クラス
    • SysvSemaphore — SysvSemaphore クラス
    • SysvSharedMemory — SysvSharedMemory クラス
  • 共有メモリ
    • はじめに
    • インストール/設定
    • 例
    • 共有メモリ関数
    • Shmop — Shmop クラス
  • Sync
    • はじめに
    • インストール/設定
    • SyncMutex — The SyncMutex class
    • SyncSemaphore — The SyncSemaphore class
    • SyncEvent — The SyncEvent class
    • SyncReaderWriter — The SyncReaderWriter class
    • SyncSharedMemory — The SyncSharedMemory class


Eio

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
  • Eio 関数
    • eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用
    • eio_cancel — リクエストを取り消す
    • eio_chmod — ファイルやディレクトリのパーミッションを変更する
    • eio_chown — ファイルやディレクトリのオーナーを変更する
    • eio_close — ファイルを閉じる
    • eio_custom — eio_* のようなカスタムリクエストを実行する
    • eio_dup2 — ファイルディスクリプタを複製する
    • eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする
    • eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする
    • eio_fchmod — ファイルのパーミッションを変更する
    • eio_fchown — ファイルのオーナーを変更する
    • eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる
    • eio_fstat — ファイルの状態を取得する
    • eio_fstatvfs — ファイルシステムの状態を取得する
    • eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる
    • eio_ftruncate — ファイルを切り詰める
    • eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する
    • eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する
    • eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す
    • eio_grp — リクエストグループを作る
    • eio_grp_add — リクエストをリクエストグループに追加する
    • eio_grp_cancel — リクエストグループをキャンセルする
    • eio_grp_limit — グループリミットを設定する
    • eio_init — Eio を初期化する
    • eio_link — ファイルのハードリンクを作る
    • eio_lstat — ファイルの状態を取得する
    • eio_mkdir — ディレクトリを作る
    • eio_mknod — 特殊ファイルあるいは一般ファイルを作る
    • eio_nop — 何もせず、ただリクエストのサイクルを回す
    • eio_npending — 終了したけれども処理されなかったリクエストの数を返す
    • eio_nready — 未処理のリクエスト数を返す
    • eio_nreqs — 処理対象のリクエスト数を返す
    • eio_nthreads — 現在利用中のスレッド数を返す
    • eio_open — ファイルを開く
    • eio_poll — 未処理のリクエストがあるかどうかを調べる
    • eio_read — ファイルを、指定したオフセットから読み込む
    • eio_readahead — ファイルを先読みしてページキャッシュに格納する
    • eio_readdir — ディレクトリ全体を読み込む
    • eio_readlink — シンボリックリンクの値を読む
    • eio_realpath — 正規化された絶対パスを取得する
    • eio_rename — ファイル名や場所を変更する
    • eio_rmdir — ディレクトリを削除する
    • eio_seek — fd で指定したファイル内でのオフセットを、offset と whence に従って移動する
    • eio_sendfile — ファイルディスクリプタ間でデータを転送する
    • eio_set_max_idle — アイドルスレッドの最大数を設定する
    • eio_set_max_parallel — 最大の並列スレッド数を設定する
    • eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する
    • eio_set_max_poll_time — 最大のポール時間を設定する
    • eio_set_min_parallel — 最小の並列スレッド数を設定する
    • eio_stat — ファイルの状態を取得する
    • eio_statvfs — ファイルシステムの状態を取得する
    • eio_symlink — シンボリックリンクを作る
    • eio_sync — バッファのキャッシュをディスクに書き込む
    • eio_sync_file_range — ファイルセグメントをディスクに同期する
    • eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ
    • eio_truncate — ファイルを切り詰める
    • eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する
    • eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する
    • eio_write — ファイルに書き込む


はじめに

この拡張モジュールは、非同期 POSIX I/O 機能を提供します。 Marc Lehmann による » libeio C ライブラリを利用します。

注意: この拡張モジュールは Windows 環境では利用できません。

警告

注意すべき点は、個々のリクエストが単一のスレッド内で実行され、 キューに入れた一連のリクエストの実行順は基本的に不定であるということです。 たとえば、次のコード片は間違っています。

例1 間違ったリクエスト

<?php
// $filename のシンボリックリンクを $link に作るリクエスト
eio_symlink($filename, $link);

// $filename を $new_filename に移動するリクエスト
eio_rename($filename, $new_filename);

// リクエストを処理します
eio_event_loop();
?>
この書き方だと、eio_rename() のほうが eio_symlink() よりも先に処理されてしまう可能性があります。 そうならないようにするには、eio_rename() を eio_symlink() のコールバックの中から呼びます。

例2 リクエストコールバックからのリクエストの呼び出し

<?php
function my_symlink_done($filename, $result) {
// $filename を $new_filename に移動するリクエスト
eio_rename($filename, "/path/to/new-name");

// リクエストを処理します
eio_event_loop();
}

// $filename のシンボリックリンクを $link に作るリクエスト
eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_done", $filename);

// リクエストを処理します
eio_event_loop();
?>
あるいは、リクエストグループを作るという手もあります。

例3 リクエストコールバックからのリクエストの呼び出し

<?php
/* これは、グループリクエストが終わってから呼ばれます */
function my_grp_done($data, $result) {
// ...
}

function my_symlink_done($filename, $result) {
// eio_rename リクエストを作り、グループに追加します
$req = eio_rename($filename, "/path/to/new-name");
eio_grp_add($grp, $req);
// もっとリクエストを追加したければ、ここで追加します
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", "my_grp_data");

// eio_symlink リクエストを作り、グループに追加します
// $filename をコールバックに渡します
$req = eio_symlink($filename, $link,
EIO_PRI_DEFAULT, "my_symlink_done", $filename);
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>
グループとは特殊な形式のリクエストのことで、通常の eio リクエストを複数積み上げることができます。 これを使えば、ファイルを開いて読み込んでから閉じるといった 複雑なリクエストを作れます。

バージョン 0.3.0 alpha 以降では、 libeio との通信で内部的に使う変数を eio_get_event_stream() で取得できます。 この変数を使うと、他の拡張モジュールでサポートしている イベントループにバインドできます。 シンプルなイベントループを作って、eio と libevent を一緒に動かしたりできるのです。

例4 eio と libevent を組み合わせる例

<?php
function my_eio_poll($fd, $events, $arg) {
/* libevent の設定があればここに書きます .. */
if (eio_nreqs()) {
eio_poll();
}
/* .. そしてここにも書きます */
}

function my_res_cb($d, $r) {
var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

// このストリームを使って libevent にバインドします
$fd = eio_get_event_stream();

eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
/* その他の eio_* コール ... */

// イベントフラグを設定します
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// イベントベースを設定します
event_base_set($event, $base);

// イベントを有効化します
event_add($event);

// イベントループを開始します
event_base_loop($base);

/* バッファつき libevent インターフェイスでも同様にできます */
?>


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Eio
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

この拡張モジュールには » libeio ライブラリが組み込まれています。libeio を個別にインストールする必要はありません。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/eio

手動でのインストールに関する情報は、パッケージに含まれる INSTALL ファイルを参照ください。


  • ≪ インストール手順
  • 定義済み定数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型

この拡張モジュールでは二種類のリソース型を使います。リクエストとリクエストグループです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

リクエストの優先度

EIO_PRI_MIN (int)
優先度最小
EIO_PRI_DEFAULT (int)
優先度標準
EIO_PRI_MAX (int)
優先度最大

eio_seek() の whence 引数

EIO_SEEK_SET (int)
オフセットをバイト数で指定する (offset)。
EIO_SEEK_CUR (int)
オフセットを現在位置に offset バイト加えた値にする。
EIO_SEEK_END (int)
オフセットをファイルのサイズに offset バイト加えた値にする。

eio_readdir() で使うフラグ

EIO_READDIR_DENTS (int)
eio_readdir() のフラグ。指定すると、コールバックの result 引数が次のキーを持つ配列になります。 'names' - ディレクトリ名の配列／ 'dents' - struct eio_dirent 風の配列で、 それぞれがさらに以下のキーを持ちます ( 'name' - ディレクトリ名／ 'type' - EIO_DT_* 定数のいずれか／ 'inode' - inode 番号。存在しない場合は不定 )
EIO_READDIR_DIRS_FIRST (int)
このフラグを指定すると、ディレクトリをまず最初に返して stat に最適化した順に返します。
EIO_READDIR_STAT_ORDER (int)
このフラグを指定すると、名前を返すときの順序が 各ファイルを stat するのに適した順となります。 指定したディレクトリにあるすべてのファイルを stat() するつもりなら、この順にしておけば最速になります。
EIO_READDIR_FOUND_UNKNOWN (int)
EIO_DT_UNKNOWN (int)
不明なノード型 (ありがち)。さらに stat() が必要です。
EIO_DT_FIFO (int)
FIFO ノード型
EIO_DT_CHR (int)
ノード型
EIO_DT_MPC (int)
多重化キャラクタデバイス (v7+coherent) ノード型
EIO_DT_DIR (int)
ディレクトリノード型
EIO_DT_NAM (int)
Xenix 名前付きファイルノード型
EIO_DT_BLK (int)
ノード型
EIO_DT_MPB (int)
多重化ブロックデバイス (v7+coherent)
EIO_DT_REG (int)
ノード型
EIO_DT_NWK (int)
EIO_DT_CMP (int)
HP-UX ネットワークノード型
EIO_DT_LNK (int)
リンクノード型
EIO_DT_SOCK (int)
ソケットノード型
EIO_DT_DOOR (int)
Solaris door ノード型
EIO_DT_WHT (int)
ノード型
EIO_DT_MAX (int)
ノード型の最大値

eio_open() の flags 引数用のアクセスモード

EIO_O_RDONLY (int)
EIO_O_WRONLY (int)
EIO_O_RDWR (int)
EIO_O_NONBLOCK (int)
EIO_O_APPEND (int)
EIO_O_CREAT (int)
EIO_O_TRUNC (int)
EIO_O_EXCL (int)
EIO_O_FSYNC (int)

eio_open() の mode 引数用のフラグ

EIO_S_IRUSR (int)
EIO_S_IWUSR (int)
EIO_S_IXUSR (int)
EIO_S_IRGRP (int)
EIO_S_IWGRP (int)
EIO_S_IXGRP (int)
EIO_S_IROTH (int)
EIO_S_IWOTH (int)
EIO_S_IXOTH (int)
EIO_S_IFREG (int)
EIO_S_IFCHR (int)
EIO_S_IFBLK (int)
EIO_S_IFIFO (int)
EIO_S_IFSOCK (int)

eio_sync_file_range() のフラグ

EIO_SYNC_FILE_RANGE_WAIT_BEFORE (int)
EIO_SYNC_FILE_RANGE_WRITE (int)
EIO_SYNC_FILE_RANGE_WAIT_AFTER (int)

eio_fallocate() のフラグ

EIO_FALLOC_FL_KEEP_SIZE (int)

注意:

EIO_S_I* 定数の意味は、POSIX での S_I* と同じです。

注意:

EIO_SYNC_FILE_* 定数の意味は、 SYNC_FILE_** と同じです。

注意:

EIO_O_* 定数の意味は、POSIX での O_* と同じです。


例

例1 リクエストの取り消し

<?php
/* eio_nop() が終わったら呼ばれます */
function my_nop_cb($data, $result) {
echo "my_nop ", $data, "\n";
}

// この eio_nop() の呼び出しは取り消されます
$req = eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "1");
var_dump($req);
eio_cancel($req);

// この eio_nop() は処理されます
eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "2");

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
my_nop 2

例2 eio_chmod() の呼び出し

<?php
$temp_filename = dirname(__FILE__) ."/eio-temp-file.tmp";
touch($temp_filename);

/* eio_chmod() が終わったら呼ばれます */
function my_chmod_callback($data, $result) {
global $temp_filename;

if ($result == 0 && !is_readable($temp_filename) && is_writable($temp_filename)) {
echo "eio_chmod_ok";
}

@unlink($temp_filename);
}

eio_chmod($temp_filename, 0200, EIO_PRI_DEFAULT, "my_chmod_callback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_chmod_ok

例3 カスタムリクエストの作成

<?php
/* カスタムコールバック */
function my_custom_callback($data, $result) {
var_dump($data);
var_dump(count($result));
var_dump($result['data_modified']);
var_dump($result['result']);
}

/* カスタムリクエスト */
function my_custom($data) {
var_dump($data);

$result = array(
'result' => 1001,
'data_modified' => "my custom data",
);

return $result;
}

$data = "my_custom_data";
$req = eio_custom("my_custom", EIO_PRI_DEFAULT, "my_custom_callback", $data);
var_dump($req);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
string(14) "my_custom_data"
string(14) "my_custom_data"
int(2)
string(14) "my custom data"
int(1001)

例4 リクエストのグループ化

<?php
/*
* ファイルを開き、読んでから閉じるグループリクエストを作ります
*/

$temp_filename = dirname(__FILE__) ."/eio-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "some data");
fclose($fp);

/* グループリクエストが終了したときに呼ばれます */
function my_grp_done($data, $result) {
global $temp_filename;
var_dump($result == 0);
@unlink($temp_filename);
}

/* eio_open() が終わったら呼ばれます */
function my_grp_file_opened_callback($data, $result) {
global $my_file_fd, $grp;

$my_file_fd = $result;

var_dump($result > 0);

// eio_read() リクエストを作ってグループに追加します
$req = eio_read($my_file_fd, 4, 0, EIO_PRI_DEFAULT, "my_grp_file_read_callback");
eio_grp_add($grp, $req);
}

/* eio_read() が終わったら呼ばれます */
function my_grp_file_read_callback($data, $result) {
global $my_file_fd, $grp;

var_dump($result);

// eio_close() リクエストを作ってグループに追加します
$req = eio_close($my_file_fd);
eio_grp_add($grp, $req);
}

$grp = eio_grp("my_grp_done", "my_grp_data");

// eio_open() リクエストを作ってグループに追加します
$req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);
eio_grp_add($grp, $req);
var_dump($grp);

eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(6) of type (EIO Group Descriptor)
bool(true)
string(4) "some"
bool(true)

例5 eio と libevent 拡張モジュールを組み合わせる

<?php
function my_eio_poll($fd, $events, $arg) {
/* libevent の設定があればここに書きます .. */
if (eio_nreqs()) {
eio_poll();
}
/* .. そしてここにも書きます */
}

function my_nop_cb($d, $r) {
var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

$fd = eio_get_event_stream();
var_dump($fd);

eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_nop_cb", "nop data");
/* その他の eio_* コール ... */

// イベントフラグを設定します
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// イベントベースを設定します
event_base_set($event, $base);

// イベントを有効化します
event_add($event);

// イベントループを開始します
event_base_loop($base);

/* バッファつき libevent インターフェイスでも同様にできます */
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(0)
string(8) "nop data"
int(0)
string(10) "mkdir data"

例6 eio と event 拡張モジュールを組み合わせる

<?php
$base = new EventBase();

// eio ポーリングストリームを取得します
// この変数は、イベントループの実行中ずっと有効でなければいけないことに注意しましょう
$eio_stream = eio_get_event_stream();

// eio ポーリングストリームをイベントループにバインドします
$poll_event = new Event($base, $eio_stream, Event::READ, function () {
if (eio_nreqs()) {
eio_poll();
}
});
$poll_event->add();

// eio ジョブを追加します
eio_nop(EIO_PRI_DEFAULT, function () {
echo "eio_nop\n";
});

// イベントを追加します
$timer = Event::timer($base, function () {
echo "2 seconds elapsed\n";
});
$timer->add(2);

// イベントをディスパッチします
$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

eio_nop
2 seconds elapsed


Eio 関数

目次

  • eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用
  • eio_cancel — リクエストを取り消す
  • eio_chmod — ファイルやディレクトリのパーミッションを変更する
  • eio_chown — ファイルやディレクトリのオーナーを変更する
  • eio_close — ファイルを閉じる
  • eio_custom — eio_* のようなカスタムリクエストを実行する
  • eio_dup2 — ファイルディスクリプタを複製する
  • eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする
  • eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする
  • eio_fchmod — ファイルのパーミッションを変更する
  • eio_fchown — ファイルのオーナーを変更する
  • eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる
  • eio_fstat — ファイルの状態を取得する
  • eio_fstatvfs — ファイルシステムの状態を取得する
  • eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる
  • eio_ftruncate — ファイルを切り詰める
  • eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する
  • eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する
  • eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す
  • eio_grp — リクエストグループを作る
  • eio_grp_add — リクエストをリクエストグループに追加する
  • eio_grp_cancel — リクエストグループをキャンセルする
  • eio_grp_limit — グループリミットを設定する
  • eio_init — Eio を初期化する
  • eio_link — ファイルのハードリンクを作る
  • eio_lstat — ファイルの状態を取得する
  • eio_mkdir — ディレクトリを作る
  • eio_mknod — 特殊ファイルあるいは一般ファイルを作る
  • eio_nop — 何もせず、ただリクエストのサイクルを回す
  • eio_npending — 終了したけれども処理されなかったリクエストの数を返す
  • eio_nready — 未処理のリクエスト数を返す
  • eio_nreqs — 処理対象のリクエスト数を返す
  • eio_nthreads — 現在利用中のスレッド数を返す
  • eio_open — ファイルを開く
  • eio_poll — 未処理のリクエストがあるかどうかを調べる
  • eio_read — ファイルを、指定したオフセットから読み込む
  • eio_readahead — ファイルを先読みしてページキャッシュに格納する
  • eio_readdir — ディレクトリ全体を読み込む
  • eio_readlink — シンボリックリンクの値を読む
  • eio_realpath — 正規化された絶対パスを取得する
  • eio_rename — ファイル名や場所を変更する
  • eio_rmdir — ディレクトリを削除する
  • eio_seek — fd で指定したファイル内でのオフセットを、offset と whence に従って移動する
  • eio_sendfile — ファイルディスクリプタ間でデータを転送する
  • eio_set_max_idle — アイドルスレッドの最大数を設定する
  • eio_set_max_parallel — 最大の並列スレッド数を設定する
  • eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する
  • eio_set_max_poll_time — 最大のポール時間を設定する
  • eio_set_min_parallel — 最小の並列スレッド数を設定する
  • eio_stat — ファイルの状態を取得する
  • eio_statvfs — ファイルシステムの状態を取得する
  • eio_symlink — シンボリックリンクを作る
  • eio_sync — バッファのキャッシュをディスクに書き込む
  • eio_sync_file_range — ファイルセグメントをディスクに同期する
  • eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ
  • eio_truncate — ファイルを切り詰める
  • eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する
  • eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する
  • eio_write — ファイルに書き込む


人為的に負荷を高くする。テストやベンチマークなどで有用

  • ≪ Eio 関数
  • eio_cancel ≫
  • PHP Manual
  • Eio 関数
  • 人為的に負荷を高くする。テストやベンチマークなどで有用

eio_busy

(PECL eio >= 0.0.1dev)

eio_busy — 人為的に負荷を高くする。テストやベンチマークなどで有用

説明

eio_busy(
int $delay,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_busy() は人為的に負荷を高め、実行前に delay 秒待ちます。デバッグやベンチマークに使えるでしょう。

パラメータ

delay

待つ秒数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

すべてのグループリクエストが終わったときに呼ばれるコールバック。

data

callback に渡す任意の引数。

戻り値

eio_busy() は成功した場合にリクエストリソースを返します。 失敗した場合に false を返します

参考

  • eio_nop() - 何もせず、ただリクエストのサイクルを回す


リクエストを取り消す

  • ≪ eio_busy
  • eio_chmod ≫
  • PHP Manual
  • Eio 関数
  • リクエストを取り消す

eio_cancel

(PECL eio >= 0.0.1dev)

eio_cancel — リクエストを取り消す

説明

eio_cancel(resource $req): void

eio_cancel() は、 req で指定したリクエストを取り消します。

パラメータ

req

リクエストリソース。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

値を返しません。

例

例1 eio_cancel() の例

<?php
/* eio_nop() が終わったら呼ばれます */
function my_nop_cb($data, $result) {
echo "my_nop ", $data, "\n";
}

// この eio_nop() の呼び出しは取り消されます
$req = eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "1");
var_dump($req);
eio_cancel($req);

// この eio_nop() は処理されます
eio_nop(EIO_PRI_DEFAULT, "my_nop_cb", "2");

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
my_nop 2

参考

  • eio_grp_cancel() - リクエストグループをキャンセルする


ファイルやディレクトリのパーミッションを変更する

  • ≪ eio_cancel
  • eio_chown ≫
  • PHP Manual
  • Eio 関数
  • ファイルやディレクトリのパーミッションを変更する

eio_chmod

(PECL eio >= 0.0.1dev)

eio_chmod — ファイルやディレクトリのパーミッションを変更する

説明

eio_chmod(
string $path,
int $mode,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_chmod() は、ファイルやディレクトリのパーミッションを変更します。 新しいパーミッションを mode で指定します。

パラメータ

path

対象となるファイルやディレクトリのパス。

警告

相対パスを避けましょう

mode

新しいパーミッション。0644 など。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_chmod() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_chown() - ファイルやディレクトリのオーナーを変更する


ファイルやディレクトリのオーナーを変更する

  • ≪ eio_chmod
  • eio_close ≫
  • PHP Manual
  • Eio 関数
  • ファイルやディレクトリのオーナーを変更する

eio_chown

(PECL eio >= 0.0.1dev)

eio_chown — ファイルやディレクトリのオーナーを変更する

説明

eio_chown(
string $path,
int $uid,
int $gid = -1,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

ファイルやディレクトリのオーナーを変更します。

パラメータ

path

ファイルやディレクトリへのパス。

警告

相対パスを避けましょう

uid

ユーザー ID。-1 にすると無視されます。

gid

グループ ID。-1 にすると無視されます。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_chown() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_chmod() - ファイルやディレクトリのパーミッションを変更する


ファイルを閉じる

  • ≪ eio_chown
  • eio_custom ≫
  • PHP Manual
  • Eio 関数
  • ファイルを閉じる

eio_close

(PECL eio >= 0.0.1dev)

eio_close — ファイルを閉じる

説明

eio_close(
mixed $fd,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_close() は、 fd で指定したファイルを閉じます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_close() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_open() - ファイルを開く


eio_* のようなカスタムリクエストを実行する

  • ≪ eio_close
  • eio_dup2 ≫
  • PHP Manual
  • Eio 関数
  • eio_* のようなカスタムリクエストを実行する

eio_custom

(PECL eio >= 0.0.1dev)

eio_custom — eio_* のようなカスタムリクエストを実行する

説明

eio_custom(
callable $execute,
int $pri,
callable $callback,
mixed $data = NULL
): resource

eio_custom() は、 execute で指定したカスタム関数を実行し、 その他の eio_* と同じように処理します。

パラメータ

execute

次のプロトタイプに沿ったリクエスト関数を指定します。

      mixed execute(mixed data);
callback はイベント完了後のコールバックで、次のプロトタイプに従う必要があります。
      void callback(mixed data, mixed result);
data は、 execute に data 引数経由で渡すデータです。 execute が返す result の値に手を加えません。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_custom() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_custom() の例

<?php
/* カスタムコールバック用のコールバック */
function my_custom_callback($data, $result) {
var_dump($data);
var_dump(count($result));
var_dump($result['data_modified']);
var_dump($result['result']);
}

/* カスタムリクエスト */
function my_custom($data) {
var_dump($data);

$result = array(
'result' => 1001,
'data_modified' => "my custom data",
);

return $result;
}

$data = "my_custom_data";
$req = eio_custom("my_custom", EIO_PRI_DEFAULT, "my_custom_callback", $data);
var_dump($req);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(4) of type (EIO Request Descriptor)
string(14) "my_custom_data"
string(14) "my_custom_data"
int(2)
string(14) "my custom data"
int(1001)


ファイルディスクリプタを複製する

  • ≪ eio_custom
  • eio_event_loop ≫
  • PHP Manual
  • Eio 関数
  • ファイルディスクリプタを複製する

eio_dup2

(PECL eio >= 0.0.1dev)

eio_dup2 — ファイルディスクリプタを複製する

説明

eio_dup2(
mixed $fd,
mixed $fd2,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_dup2() は、ファイルディスクリプタを複製します。

パラメータ

fd

複製元のストリーム、ソケットリソース、あるいはファイルディスクリプタ。

fd2

複製先のストリーム、ソケットリソース、あるいはファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_dup2() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


すべてのリクエストを処理し終えるまで libeio をポールする

  • ≪ eio_dup2
  • eio_fallocate ≫
  • PHP Manual
  • Eio 関数
  • すべてのリクエストを処理し終えるまで libeio をポールする

eio_event_loop

(PECL eio >= 0.0.1dev)

eio_event_loop — すべてのリクエストを処理し終えるまで libeio をポールする

説明

eio_event_loop(): bool

eio_event_loop() は、すべてのリクエストを処理し終えるまで libeio をポールします。

パラメータ

この関数にはパラメータはありません。

戻り値

eio_event_loop() は、成功した場合に true を返します。失敗した場合に false を返します

例

例1 eio_event_loop() の例

<?php
$temp_filename = "eio-temp-file.tmp";
touch($temp_filename);

/* eio_chmod() が終了したときに呼ばれます */
function my_chmod_callback($data, $result) {
global $temp_filename;

if ($result == 0 && !is_readable($temp_filename) && is_writable($temp_filename)) {
echo "eio_chmod_ok";
}

@unlink($temp_filename);
}

eio_chmod($temp_filename, 0200, EIO_PRI_DEFAULT, "my_chmod_callback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_chmod_ok

参考

  • eio_poll() - 未処理のリクエストがあるかどうかを調べる


呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする

  • ≪ eio_event_loop
  • eio_fchmod ≫
  • PHP Manual
  • Eio 関数
  • 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする

eio_fallocate

(PECL eio >= 0.0.1dev)

eio_fallocate — 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする

説明

eio_fallocate(
mixed $fd,
int $mode,
int $offset,
int $length,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_fallocate() 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにします。 ファイルの指定はファイルディスクリプタ fd で行い、 バイト幅の指定は開始位置 offset とそこからの長さ length で行います。

注意: 書き込みモードでのオープンが必須

EIO_O_CREAT を EIO_O_WRONLY あるいは EIO_O_RDWR と論理 OR しなければいけません。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (たとえば eio_open() が返すもの)。

mode

現在サポートするフラグは EIO_FALLOC_FL_KEEP_SIZE (POSIX の定数 FALLOC_FL_KEEP_SIZE と同じ意味) だけです。

offset

バイト幅の開始位置。

length

バイト幅の長さ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_fallocate() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ファイルのパーミッションを変更する

  • ≪ eio_fallocate
  • eio_fchown ≫
  • PHP Manual
  • Eio 関数
  • ファイルのパーミッションを変更する

eio_fchmod

(PECL eio >= 0.0.1dev)

eio_fchmod — ファイルのパーミッションを変更する

説明

eio_fchmod(
mixed $fd,
int $mode,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_fchmod() は、 ファイルディスクリプタ fd で指定したファイルやディレクトリのパーミッションを変更します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

mode

新しいパーミッション。例: 0644

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_fchmod() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_fchown() - ファイルのオーナーを変更する


ファイルのオーナーを変更する

  • ≪ eio_fchmod
  • eio_fdatasync ≫
  • PHP Manual
  • Eio 関数
  • ファイルのオーナーを変更する

eio_fchown

(PECL eio >= 0.0.1dev)

eio_fchown — ファイルのオーナーを変更する

説明

eio_fchown(
mixed $fd,
int $uid,
int $gid = -1,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_fchown() は、 ファイルディスクリプタ fd で指定したファイルやディレクトリのオーナーを変更します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

uid

ユーザー ID。-1 にすると無視されます。

gid

グループ ID。-1 にすると無視されます。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_chmod() は、成功時にリクエストリソースを返します。 失敗した場合に false を返します

参考

  • eio_fchmod() - ファイルのパーミッションを変更する


ファイルのコア内の情報をストレージデバイスに同期させる

  • ≪ eio_fchown
  • eio_fstat ≫
  • PHP Manual
  • Eio 関数
  • ファイルのコア内の情報をストレージデバイスに同期させる

eio_fdatasync

(PECL eio >= 0.0.1dev)

eio_fdatasync — ファイルのコア内の情報をストレージデバイスに同期させる

説明

eio_fdatasync(
mixed $fd,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_fdatasync() は、ファイルのコア内の情報をストレージデバイスに同期させます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_fdatasync() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ファイルの状態を取得する

  • ≪ eio_fdatasync
  • eio_fstatvfs ≫
  • PHP Manual
  • Eio 関数
  • ファイルの状態を取得する

eio_fstat

(PECL eio >= 0.0.1dev)

eio_fstat — ファイルの状態を取得する

説明

eio_fstat(
mixed $fd,
int $pri,
callable $callback,
mixed $data = ?
): resource

eio_fstat() は、 callback の result 引数でファイルの状態を返します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_busy() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_lstat() の例

<?php
// 一時ファイルを作ります
$tmp_filename = dirname(__FILE__) ."/eio-file.tmp";
touch($tmp_filename);

/* eio_fstat() が終わったら呼ばれます */
function my_res_cb($data, $result) {
// 状態を配列で出力します
var_dump($result);

if ($data['fd']) {
// 一時ファイルを閉じます
eio_close($data['fd']);
eio_event_loop();
}
// 一時ファイルを削除します
@unlink($data['file']);
}

/* eio_open() が終わったら呼ばれます */
function my_open_cb($data, $result) {
// コールバック用のデータを用意します
$d = array(
'fd' => $result,
'file'=> $data
);
// 状態を取得します
eio_fstat($result, EIO_PRI_DEFAULT, "my_res_cb", $d);
// リクエストを処理します
eio_event_loop();
}

// 一時ファイルを開きます
eio_open($tmp_filename, EIO_O_RDONLY, NULL, EIO_PRI_DEFAULT,
"my_open_cb", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

array(12) {
 ["st_dev"]=>
  int(2050)
  ["st_ino"]=>
  int(2489159)
  ["st_mode"]=>
  int(33188)
  ["st_nlink"]=>
  int(1)
  ["st_uid"]=>
  int(1000)
  ["st_gid"]=>
  int(100)
  ["st_rdev"]=>
  int(0)
  ["st_blksize"]=>
  int(4096)
  ["st_blocks"]=>
  int(0)
  ["st_atime"]=>
  int(1318239506)
  ["st_mtime"]=>
  int(1318239506)
  ["st_ctime"]=>
  int(1318239506)
}

参考

  • eio_lstat() - ファイルの状態を取得する
  • eio_stat() - ファイルの状態を取得する


ファイルシステムの状態を取得する

  • ≪ eio_fstat
  • eio_fsync ≫
  • PHP Manual
  • Eio 関数
  • ファイルシステムの状態を取得する

eio_fstatvfs

(PECL eio >= 0.0.1dev)

eio_fstatvfs — ファイルシステムの状態を取得する

説明

eio_fstatvfs(
mixed $fd,
int $pri,
callable $callback,
mixed $data = ?
): resource

eio_fstatvfs() は、ファイルシステムの状態を callback の result で返します。

パラメータ

fd

マウントされたファイルシステム内のファイルのディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_fstatvfs() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_statvfs() - ファイルシステムの状態を取得する


メモリ内でのファイルの状態をストレージデバイスに同期させる

  • ≪ eio_fstatvfs
  • eio_ftruncate ≫
  • PHP Manual
  • Eio 関数
  • メモリ内でのファイルの状態をストレージデバイスに同期させる

eio_fsync

(PECL eio >= 0.0.1dev)

eio_fsync — メモリ内でのファイルの状態をストレージデバイスに同期させる

説明

eio_fsync(
mixed $fd,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

メモリ内でのファイルの状態をストレージデバイスに同期させます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_fsync() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_sync() - バッファのキャッシュをディスクに書き込む


ファイルを切り詰める

  • ≪ eio_fsync
  • eio_futime ≫
  • PHP Manual
  • Eio 関数
  • ファイルを切り詰める

eio_ftruncate

(PECL eio >= 0.0.1dev)

eio_ftruncate — ファイルを切り詰める

説明

eio_ftruncate(
mixed $fd,
int $offset = 0,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_ftruncate() は、ファイルディスクリプタ fd で指定したファイルを切り詰めて、ちょうど length バイトにします。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

offset

ファイルの先頭からのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_ftruncate() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_truncate() - ファイルを切り詰める


ファイルの最終アクセス時刻と変更時刻を変更する

  • ≪ eio_ftruncate
  • eio_get_event_stream ≫
  • PHP Manual
  • Eio 関数
  • ファイルの最終アクセス時刻と変更時刻を変更する

eio_futime

(PECL eio >= 0.0.1dev)

eio_futime — ファイルの最終アクセス時刻と変更時刻を変更する

説明

eio_futime(
mixed $fd,
float $atime,
float $mtime,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_futime() は、ファイルの最終アクセス時刻と変更時刻を変更します。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

atime

アクセス時刻。

mtime

変更時刻。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_futime() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_utime() - ファイルの最終アクセス時刻と変更時刻を変更する


内部での libeio との通信に使う変数を表すストリームを取得する

  • ≪ eio_futime
  • eio_get_last_error ≫
  • PHP Manual
  • Eio 関数
  • 内部での libeio との通信に使う変数を表すストリームを取得する

eio_get_event_stream

(PECL eio >= 0.3.1b)

eio_get_event_stream — 内部での libeio との通信に使う変数を表すストリームを取得する

説明

eio_get_event_stream(): mixed

eio_get_event_stream() は、内部での libeio との通信に使う変数を表すストリームを取得します。 他の PECL 拡張モジュール、たとえば libevent にバインドさせたりして使うことができます。

パラメータ

この関数にはパラメータはありません。

戻り値

eio_get_event_stream() は、成功した場合にストリームを返します。それ以外の場合に null を返します。

例

例1 eio を libevent とともに使う

<?php
function my_eio_poll($fd, $events, $arg) {
/* Some libevent regulation might go here .. */
if (eio_nreqs()) {
eio_poll();
}
/* .. and here */
}

function my_res_cb($d, $r) {
var_dump($r); var_dump($d);
}

$base = event_base_new();
$event = event_new();

$fd = eio_get_event_stream();
var_dump($fd);

eio_nop(EIO_PRI_DEFAULT, "my_res_cb", "nop data");
eio_mkdir("/tmp/abc-eio-temp", 0750, EIO_PRI_DEFAULT, "my_res_cb", "mkdir data");
/* some other eio_* calls here ... */

// set event flags
event_set($event, $fd, EV_READ /*| EV_PERSIST*/, "my_eio_poll", array($event, $base));

// set event base
event_base_set($event, $base);

// enable event
event_add($event);

// start event loop
event_base_loop($base);

/* The same will be available via buffered libevent interface */
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(0)
string(8) "nop data"
int(0)
string(10) "mkdir data"


リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す

  • ≪ eio_get_event_stream
  • eio_grp ≫
  • PHP Manual
  • Eio 関数
  • リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す

eio_get_last_error

(PECL eio >= 1.0.0)

eio_get_last_error — リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す

説明

eio_get_last_error(resource $req): string

eio_get_last_error() は、 req に関連づけられた直近のエラーの説明を文字列で返します。

パラメータ

req

リクエストリソース。

戻り値

eio_get_last_error() は、req に関連づけられた直近のエラーの説明を文字列で返します。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


リクエストグループを作る

  • ≪ eio_get_last_error
  • eio_grp_add ≫
  • PHP Manual
  • Eio 関数
  • リクエストグループを作る

eio_grp

(PECL eio >= 0.0.1dev)

eio_grp — リクエストグループを作る

説明

eio_grp(callable $callback, string $data = NULL): resource

eio_grp() は、リクエストグループを作ります。

パラメータ

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_grp() は、成功した場合にリクエストグループリソースを返します。失敗した場合に false を返します

例

例1 eio_grp() の例

<?php
$temp_filename = dirname(__FILE__) ."/eio-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "some data");
fclose($fp);
$my_file_fd = NULL;

/* グループリクエストが終了したときに呼ばれます */
function my_grp_done($data, $result) {
// もしファイルが残っていれば削除します
@unlink($data);
}

/* テンポラリファイルを開いたときに呼ばれます */
function my_grp_file_opened_callback($data, $result) {
global $my_file_fd, $grp;

$my_file_fd = $result;

$req = eio_read($my_file_fd, 4, 0,
EIO_PRI_DEFAULT, "my_grp_file_read_callback");
eio_grp_add($grp, $req);
}

/* ファイルを読み終えたときに呼ばれます */
function my_grp_file_read_callback($data, $result) {
global $my_file_fd, $grp;

var_dump($result);

// ファイルを閉じるリクエストを作ります
$req = eio_close($my_file_fd);

// リクエストをグループに追加します
eio_grp_add($grp, $req);
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", $temp_filename);

// リクエストを作ります
$req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);

// リクエストをグループに追加します
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(4) "some"

参考

  • eio_grp_cancel() - リクエストグループをキャンセルする
  • eio_grp_add() - リクエストをリクエストグループに追加する


リクエストをリクエストグループに追加する

  • ≪ eio_grp
  • eio_grp_cancel ≫
  • PHP Manual
  • Eio 関数
  • リクエストをリクエストグループに追加する

eio_grp_add

(PECL eio >= 0.0.1dev)

eio_grp_add — リクエストをリクエストグループに追加する

説明

eio_grp_add(resource $grp, resource $req): void

eio_grp_add() は、リクエストをリクエストグループに追加します。

パラメータ

grp

eio_grp() が返すリクエストグループリソース。

req

リクエストリソース。

戻り値

値を返しません。

例

例1 リクエストのグループ化

<?php
/*
* ファイルを開き、読んでから閉じるグループリクエストを作ります
*/

// テンポラリファイルを作って何かを書き込みます
$temp_filename = dirname(__FILE__) ."/eio-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "some data");
fclose($fp);

/* グループリクエストが終了したときに呼ばれます */
function my_grp_done($data, $result) {
var_dump($result == 0);
@unlink($data);
}

/* eio_open() が終わったら呼ばれます */
function my_grp_file_opened_callback($data, $result) {
global $grp;

// $result にはファイルディスクリプタが含まれるはずです
var_dump($result > 0);

// eio_read() リクエストを作ってグループに追加します
// ファイルディスクリプタをコールバックに渡します
$req = eio_read($result, 4, 0,
EIO_PRI_DEFAULT, "my_grp_file_read_callback", $result);
eio_grp_add($grp, $req);
}

/* eio_read() が終わったら呼ばれます */
function my_grp_file_read_callback($data, $result) {
global $grp;

// データを読みます
var_dump($result);

// eio_close() リクエストを作ってグループに追加します
// $data にはファイルディスクリプタが含まれるはずです
$req = eio_close($data);
eio_grp_add($grp, $req);
}

// リクエストグループを作ります
$grp = eio_grp("my_grp_done", $temp_filename);
var_dump($grp);

// eio_open() リクエストを作ってグループに追加します
$req = eio_open($temp_filename, EIO_O_RDWR | EIO_O_APPEND , NULL,
EIO_PRI_DEFAULT, "my_grp_file_opened_callback", NULL);
eio_grp_add($grp, $req);

// リクエストを処理します
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

resource(6) of type (EIO Group Descriptor)
bool(true)
string(4) "some"
bool(true)

参考

  • eio_grp() - リクエストグループを作る
  • eio_grp_cancel() - リクエストグループをキャンセルする
  • eio_grp_limit() - グループリミットを設定する


リクエストグループをキャンセルする

  • ≪ eio_grp_add
  • eio_grp_limit ≫
  • PHP Manual
  • Eio 関数
  • リクエストグループをキャンセルする

eio_grp_cancel

(PECL eio >= 0.0.1dev)

eio_grp_cancel — リクエストグループをキャンセルする

説明

eio_grp_cancel(resource $grp): void

eio_grp_cancel() は、 grp で指定したグループリクエストをキャンセルします。

パラメータ

grp

eio_grp() が返すリクエストグループリソース。

戻り値

値を返しません。

参考

  • eio_grp() - リクエストグループを作る
  • eio_grp_add() - リクエストをリクエストグループに追加する


グループリミットを設定する

  • ≪ eio_grp_cancel
  • eio_init ≫
  • PHP Manual
  • Eio 関数
  • グループリミットを設定する

eio_grp_limit

(PECL eio >= 0.0.1dev)

eio_grp_limit — グループリミットを設定する

説明

eio_grp_limit(resource $grp, int $limit): void

リクエストグループ内のリクエスト数を制限します。

パラメータ

grp

リクエストグループリソース。

limit

グループ内のリクエスト数。

戻り値

値を返しません。

参考

  • eio_grp_add() - リクエストをリクエストグループに追加する


Eio を初期化する

  • ≪ eio_grp_limit
  • eio_link ≫
  • PHP Manual
  • Eio 関数
  • Eio を初期化する

eio_init

(PECL eio = 1.0.0)

eio_init — Eio を初期化する

説明

eio_init(): void

eio_init() は、Eio を初期化します。 libeio と Eio 自身が使う内部構造用にメモリを確保します。 Eio 関数を使う前に eio_init() をコールしましょう。 もしコールしなくても、Eio 関数を最初にコールするときに、 内部で自動的にコールされます。

注意:

この関数は、PHP 8 以降に対応した eio 拡張モジュール 3.0.0RC1 で削除されました。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


ファイルのハードリンクを作る

  • ≪ eio_init
  • eio_lstat ≫
  • PHP Manual
  • Eio 関数
  • ファイルのハードリンクを作る

eio_link

(PECL eio >= 0.0.1dev)

eio_link — ファイルのハードリンクを作る

説明

eio_link(
string $path,
string $new_path,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_link() は、path へのハードリンク new_path を作ります。

パラメータ

path

リンク元のパス。

new_path

リンク先のパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

例

例1 eio_link() の例

<?php
$filename = dirname(__FILE__)."/symlink.dat";
touch($filename);
$link = dirname(__FILE__)."/symlink.link";
$hardlink = dirname(__FILE__)."/hardlink.link";

function my_hardlink_cb($data, $result) {
global $link, $filename;
var_dump(file_exists($data) && !is_link($data));
@unlink($data);

eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
}

function my_symlink_cb($data, $result) {
global $link, $filename;
var_dump(file_exists($data) && is_link($data));

if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
@unlink($link);
@unlink($filename);
}
}

function my_readlink_cb($data, $result) {
global $filename, $link;
var_dump($result);

@unlink($link);
@unlink($filename);
}

eio_link($filename, $hardlink, EIO_PRI_DEFAULT, "my_hardlink_cb", $hardlink);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
string(%d) "%ssymlink.dat"

参考

  • eio_symlink() - シンボリックリンクを作る


ファイルの状態を取得する

  • ≪ eio_link
  • eio_mkdir ≫
  • PHP Manual
  • Eio 関数
  • ファイルの状態を取得する

eio_lstat

(PECL eio >= 0.0.1dev)

eio_lstat — ファイルの状態を取得する

説明

eio_lstat(
string $path,
int $pri,
callable $callback,
mixed $data = NULL
): resource

eio_lstat() は、 callback の result 引数でファイルの状態を返します。

パラメータ

path

ファイルへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_lstat() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_lstat() の例

<?php
$tmp_filename = dirname(__FILE__). "/eio-file.tmp";
touch($tmp_filename);

function my_res_cb($data, $result) {
var_dump($data);
var_dump($result);
}

function my_open_cb($data, $result) {
eio_close($result);
eio_event_loop();

@unlink($data);
}

eio_lstat($tmp_filename, EIO_PRI_DEFAULT, "my_res_cb", "eio_lstat");
eio_open($tmp_filename, EIO_O_RDONLY, NULL,
EIO_PRI_DEFAULT, "my_open_cb", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(9) "eio_lstat"
array(12) {
 ["st_dev"]=>
  int(2050)
  ["st_ino"]=>
  int(2099197)
  ["st_mode"]=>
  int(33188)
  ["st_nlink"]=>
  int(1)
  ["st_uid"]=>
  int(1000)
  ["st_gid"]=>
  int(100)
  ["st_rdev"]=>
  int(0)
  ["st_blksize"]=>
  int(4096)
  ["st_blocks"]=>
  int(0)
  ["st_atime"]=>
  int(1318235777)
  ["st_mtime"]=>
  int(1318235777)
  ["st_ctime"]=>
  int(1318235777)
}

参考

  • eio_stat() - ファイルの状態を取得する
  • eio_fstat() - ファイルの状態を取得する


ディレクトリを作る

  • ≪ eio_lstat
  • eio_mknod ≫
  • PHP Manual
  • Eio 関数
  • ディレクトリを作る

eio_mkdir

(PECL eio >= 0.0.1dev)

eio_mkdir — ディレクトリを作る

説明

eio_mkdir(
string $path,
int $mode,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_mkdir() は、 mode で指定したアクセスモードでディレクトリを作ります。

パラメータ

path

新しいディレクトリへのパス。

mode

アクセスモード。例: 0755

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_mkdir() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_mkdir() の例

<?php
$temp_dirname = "eio-temp-dir";

/* eio_mkdir() が終わったら呼ばれます */
function my_mkdir_callback($data, $result) {
if ($result == 0 && is_dir($temp_dirname)
&& !is_readable($temp_dirname)
&& is_writable($temp_dirname)) {
echo "eio_mkdir_ok";
}

// ディレクトリを削除します
if (file_exists($data))
rmdir($temp_dirname);
}

// アクセスモード 0300 でディレクトリを作ります
eio_mkdir($temp_dirname, 0300, EIO_PRI_DEFAULT, "my_mkdir_callback", $temp_dirname);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_mkdir_ok

参考

  • eio_rmdir() - ディレクトリを削除する


特殊ファイルあるいは一般ファイルを作る

  • ≪ eio_mkdir
  • eio_nop ≫
  • PHP Manual
  • Eio 関数
  • 特殊ファイルあるいは一般ファイルを作る

eio_mknod

(PECL eio >= 0.0.1dev)

eio_mknod — 特殊ファイルあるいは一般ファイルを作る

説明

eio_mknod(
string $path,
int $mode,
int $dev,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_mknod() は、一般ファイルや特殊ファイル (こちらのほうが頻繁にあります) を作ります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

path

新しいノード (ファイル) へのパス。

mode

利用するパーミッションと作成するノードの型を指定します。 以下のファイルタイプ定数のひとつと、新しいノードのパーミッション (0640 など) をビット OR で組み合わせたものとなります。 ファイルタイプ定数: EIO_S_IFREG(通常ファイル)、 EIO_S_IFCHR(キャラクタファイル)、 EIO_S_IFBLK(ブロック特殊ファイル)、 EIO_S_IFIFO(FIFO - 名前付きパイプ) および EIO_S_IFSOCK(UNIX ドメインソケット)。 パーミッションの指定には EIO_S_I* 定数も使えます。

dev

ファイルタイプが EIO_S_IFCHR あるいは EIO_S_IFBLK の場合に、 新しく作るデバイスファイルのメジャー番号とマイナー番号を指定します。 それ以外の場合は無視されます。詳細は mknod(2) の man ページを参照ください。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_mknod() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_mknod() の例

<?php
// FIFO 名前付きパイプ
$temp_filename = "/tmp/eio-temp-fifo";

/* eio_mknod() が終わったら呼ばれます */
function my_mknod_callback($data, $result) {
$s = stat($data);
var_dump($s);

if ($result == 0) {
echo "eio_mknod_ok";
}

@unlink($data);
}

eio_mknod($temp_filename, EIO_S_IFIFO, 0,
EIO_PRI_DEFAULT, "my_mknod_callback", $temp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

array(26) {
  [0]=>
  int(17)
  [1]=>
  int(2337608)
  [2]=>
  int(4096)
  [3]=>
  int(1)
  [4]=>
  int(1000)
  [5]=>
  int(100)
  [6]=>
  int(0)
  [7]=>
  int(0)
  [8]=>
  int(1318241261)
  [9]=>
  int(1318241261)
  [10]=>
  int(1318241261)
  [11]=>
  int(4096)
  [12]=>
  int(0)
  ["dev"]=>
  int(17)
  ["ino"]=>
  int(2337608)
  ["mode"]=>
  int(4096)
  ["nlink"]=>
  int(1)
  ["uid"]=>
  int(1000)
  ["gid"]=>
  int(100)
  ["rdev"]=>
  int(0)
  ["size"]=>
  int(0)
  ["atime"]=>
  int(1318241261)
  ["mtime"]=>
  int(1318241261)
  ["ctime"]=>
  int(1318241261)
  ["blksize"]=>
  int(4096)
  ["blocks"]=>
  int(0)
}
eio_mknod_ok

参考

  • eio_open() - ファイルを開く


何もせず、ただリクエストのサイクルを回す

  • ≪ eio_mknod
  • eio_npending ≫
  • PHP Manual
  • Eio 関数
  • 何もせず、ただリクエストのサイクルを回す

eio_nop

(PECL eio >= 0.0.1dev)

eio_nop — 何もせず、ただリクエストのサイクルを回す

説明

eio_nop(int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

eio_nop() は、何もせずただリクエストのサイクルを回します。 デバッグ時に有用です。

パラメータ

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_nop() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_busy() - 人為的に負荷を高くする。テストやベンチマークなどで有用


終了したけれども処理されなかったリクエストの数を返す

  • ≪ eio_nop
  • eio_nready ≫
  • PHP Manual
  • Eio 関数
  • 終了したけれども処理されなかったリクエストの数を返す

eio_npending

(PECL eio >= 0.0.1dev)

eio_npending — 終了したけれども処理されなかったリクエストの数を返す

説明

eio_npending(): int

eio_npending() は、終了したけれども処理されなかったリクエストの数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

eio_npending() は、終了したけれども処理されなかったリクエストの数を返します。

参考

  • eio_nreqs() - 処理対象のリクエスト数を返す
  • eio_nready() - 未処理のリクエスト数を返す
  • eio_nthreads() - 現在利用中のスレッド数を返す


未処理のリクエスト数を返す

  • ≪ eio_npending
  • eio_nreqs ≫
  • PHP Manual
  • Eio 関数
  • 未処理のリクエスト数を返す

eio_nready

(PECL eio >= 0.0.1dev)

eio_nready — 未処理のリクエスト数を返す

説明

eio_nready(): int

パラメータ

この関数にはパラメータはありません。

戻り値

eio_nready() は、未処理のリクエスト数を返します。

参考

  • eio_nreqs() - 処理対象のリクエスト数を返す
  • eio_nready()
  • eio_nthreads() - 現在利用中のスレッド数を返す


処理対象のリクエスト数を返す

  • ≪ eio_nready
  • eio_nthreads ≫
  • PHP Manual
  • Eio 関数
  • 処理対象のリクエスト数を返す

eio_nreqs

(PECL eio >= 0.0.1dev)

eio_nreqs — 処理対象のリクエスト数を返す

説明

eio_nreqs(): int

eio_nreqs() は、 eio_poll() を呼ぶカスタムループの中からコールされます。

パラメータ

この関数にはパラメータはありません。

戻り値

eio_nreqs() は、処理対象のリクエスト数を返します。

例

例1 eio_nreqs() の例

<?php
function res_cb($data, $result) {
var_dump($data);
var_dump($result);
}

eio_nop(EIO_PRI_DEFAULT, "res_cb", "1");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "2");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "3");

while (eio_nreqs()) {
eio_poll();
}
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "1"
int(0)
string(1) "3"
int(0)
string(1) "2"
int(0)

参考

  • eio_poll() - 未処理のリクエストがあるかどうかを調べる
  • eio_nready() - 未処理のリクエスト数を返す


現在利用中のスレッド数を返す

  • ≪ eio_nreqs
  • eio_open ≫
  • PHP Manual
  • Eio 関数
  • 現在利用中のスレッド数を返す

eio_nthreads

(PECL eio >= 0.0.1dev)

eio_nthreads — 現在利用中のスレッド数を返す

説明

eio_nthreads(): int

パラメータ

この関数にはパラメータはありません。

戻り値

eio_nthreads() は、現在利用中のスレッド数を返します。

参考

  • eio_npending() - 終了したけれども処理されなかったリクエストの数を返す
  • eio_nready() - 未処理のリクエスト数を返す
  • eio_nreqs() - 処理対象のリクエスト数を返す
  • eio_set_max_idle() - アイドルスレッドの最大数を設定する
  • eio_set_max_parallel() - 最大の並列スレッド数を設定する
  • eio_set_min_parallel() - 最小の並列スレッド数を設定する


ファイルを開く

  • ≪ eio_nthreads
  • eio_poll ≫
  • PHP Manual
  • Eio 関数
  • ファイルを開く

eio_open

(PECL eio >= 0.0.1dev)

eio_open — ファイルを開く

説明

eio_open(
string $path,
int $flags,
int $mode,
int $pri,
callable $callback,
mixed $data = NULL
): resource

eio_open() は、 path で指定したファイルをアクセスモード mode で開きます。

パラメータ

path

開きたいファイルへのパス。

警告

SAPI の種類によっては (PHP-FPM など)、 フルパスで指定しないと失敗します。

flags

EIO_O_* 定数のいずれか、あるいは複数の組み合わせ。 EIO_O_* 定数の意味は、C のヘッダファイル fnctl.h で定義されている O_* と同じです。デフォルトは EIO_O_RDWR です。

mode

EIO_S_I* 定数のいずれか、あるいは複数の (ビット OR による) 組み合わせ。 この定数の意味は、C のヘッダファイル » sys/stat.h で定義されている S_I* と同じです。 新しくファイルを作るときは必須で、それ以外の場合は無視されます。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_open() は、成功した場合に callback の result 引数でファイルディスクリプタを返します。 それ以外の場合は、result は -1 になります。

例

例1 eio_open() の例

<?php
$temp_filename = "eio-temp-file.tmp";

/* eio_close() が終わったら呼ばれます */
function my_close_cb($data, $result) {
// ゼロが成功を表します
var_dump($result == 0);
@unlink($data);
}

/* eio_open() が終わったら呼ばれます */
function my_file_opened_callback($data, $result) {
// $result にはファイルディスクリプタが含まれるはずです
var_dump($result > 0);

if ($result > 0) {
// ファイルを閉じます
eio_close($result, EIO_PRI_DEFAULT, "my_close_cb", $data);
eio_event_loop();
}
}

// 新しいファイルを読み書きできるように作ります
// オーナー以外は何もできないようにします
eio_open($temp_filename, EIO_O_CREAT | EIO_O_RDWR, EIO_S_IRUSR | EIO_S_IWUSR,
EIO_PRI_DEFAULT, "my_file_opened_callback", $temp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)

参考

  • eio_mknod() - 特殊ファイルあるいは一般ファイルを作る


未処理のリクエストがあるかどうかを調べる

  • ≪ eio_open
  • eio_read ≫
  • PHP Manual
  • Eio 関数
  • 未処理のリクエストがあるかどうかを調べる

eio_poll

(PECL eio >= 0.0.1dev)

eio_poll — 未処理のリクエストがあるかどうかを調べる

説明

eio_poll(): int

eio_poll() を使うと、特別なイベントループを実装できます。 この中で eio_nreqs() を使って、未処理のリクエストの有無を調べます。 unprocessed requests.

注意:

ユーザー空間でのイベントループを実装するときにしか使えません。

パラメータ

この関数にはパラメータはありません。

戻り値

何かのリクエストを実行してそれが非ゼロを返した場合は、その値を返します。 それ以外の場合は 0 を返します。

例

例1 eio_poll() の例

<?php
function res_cb($data, $result) {
var_dump($data);
var_dump($result);
}

eio_nop(EIO_PRI_DEFAULT, "res_cb", "1");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "2");
eio_nop(EIO_PRI_DEFAULT, "res_cb", "3");

while (eio_nreqs()) {
// 何かのプロセス間通信など
eio_poll();
}
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "1"
int(0)
string(1) "3"
int(0)
string(1) "2"
int(0)

参考

  • eio_nreqs() - 処理対象のリクエスト数を返す


ファイルを、指定したオフセットから読み込む

  • ≪ eio_poll
  • eio_readahead ≫
  • PHP Manual
  • Eio 関数
  • ファイルを、指定したオフセットから読み込む

eio_read

(PECL eio >= 0.0.1dev)

eio_read — ファイルを、指定したオフセットから読み込む

説明

eio_read(
mixed $fd,
int $length,
int $offset,
int $pri,
callable $callback,
mixed $data = NULL
): resource

eio_read() は、fd が指すファイルの offset から最大 length バイトまでを読み込みます。 読み込んだデータは callback の result 引数に格納されます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

length

読み込むバイト数の最大値。

offset

ファイル内でのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_read() は、読み込んだデータを callback 関数の result 引数に格納します。

例

例1 eio_read() の例

<?php
// テンポラリファイルを作って何かを書き込みます
$temp_filename = "eio-temp-file.tmp";
$fp = fopen($temp_filename, "w");
fwrite($fp, "1234567890");
fclose($fp);

/* eio_read() が終わったら呼ばれます */
function my_read_cb($data, $result) {
global $temp_filename;

// 読み込んだデータを出力します
var_dump($result);

// ファイルを閉じます
eio_close($data);
eio_event_loop();

// テンポラリファイルを削除します
@unlink($temp_filename);
}

/* eio_open() が終わったら呼ばれます */
function my_file_opened_callback($data, $result) {
// $result にはファイルディスクリプタが含まれるはずです
if ($result > 0) {
// 3 バイト目から 5 バイト読みます
eio_read($result, 5, 2, EIO_PRI_DEFAULT, "my_read_cb", $result);
eio_event_loop();
} else {
// eio_open() が失敗
unlink($data);
}
}

// ファイルを読み書き用に開きます
eio_open($temp_filename, EIO_O_RDWR, NULL,
EIO_PRI_DEFAULT, "my_file_opened_callback", $temp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "34567"

参考

  • eio_open() - ファイルを開く
  • eio_write() - ファイルに書き込む
  • eio_close() - ファイルを閉じる
  • eio_event_loop() - すべてのリクエストを処理し終えるまで libeio をポールする


ファイルを先読みしてページキャッシュに格納する

  • ≪ eio_read
  • eio_readdir ≫
  • PHP Manual
  • Eio 関数
  • ファイルを先読みしてページキャッシュに格納する

eio_readahead

(PECL eio >= 0.0.1dev)

eio_readahead — ファイルを先読みしてページキャッシュに格納する

説明

eio_readahead(
mixed $fd,
int $offset,
int $length,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_readahead() は、ファイルを先読みしてページキャッシュに格納します。 それ以降の読み込みは、ディスク I/O をブロックしなくなります。詳細は READAHEAD(2) の man ページを参照ください。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

offset

読み込みの開始位置。

length

読み込むバイト数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_readahead() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ディレクトリ全体を読み込む

  • ≪ eio_readahead
  • eio_readlink ≫
  • PHP Manual
  • Eio 関数
  • ディレクトリ全体を読み込む

eio_readdir

(PECL eio >= 0.0.1dev)

eio_readdir — ディレクトリ全体を読み込む

説明

eio_readdir(
string $path,
int $flags,
int $pri,
callable $callback,
string $data = NULL
): resource

ディレクトリ全体を (opendir や readdir、 closedir といったシステムコールを使って) 読み込み、 ファイル名あるいは配列 (flags で指定する) を callback 関数の result 引数で返します。

パラメータ

path

ディレクトリのパス。

flags

EIO_READDIR_* 定数の組み合わせ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_readdir() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します。 callback 関数の result に設定される内容は flags によって変わります。

EIO_READDIR_DENTS (int)
eio_readdir() のフラグ。指定すると、コールバックの result 引数が次のキーを持つ配列になります。 'names' - ディレクトリ名の配列／ 'dents' - struct eio_dirent 風の配列で、 それぞれがさらに以下のキーを持ちます ( 'name' - ディレクトリ名／ 'type' - EIO_DT_* 定数のいずれか／ 'inode' - inode 番号。存在しない場合は不定 )
EIO_READDIR_DIRS_FIRST (int)
このフラグを指定すると、ディレクトリをまず最初に返して stat に最適化した順に返します。
EIO_READDIR_STAT_ORDER (int)
このフラグを指定すると、名前を返すときの順序が 各ファイルを stat するのに適した順となります。 指定したディレクトリにあるすべてのファイルを stat() するつもりなら、この順にしておけば最速になります。
EIO_READDIR_FOUND_UNKNOWN (int)

ノード型

EIO_DT_UNKNOWN (int)
不明なノード型 (ありがち)。さらに stat() が必要です。
EIO_DT_FIFO (int)
FIFO ノード型
EIO_DT_CHR (int)
ノード型
EIO_DT_MPC (int)
多重化キャラクタデバイス (v7+coherent) ノード型
EIO_DT_DIR (int)
ディレクトリノード型
EIO_DT_NAM (int)
Xenix 名前付きファイルノード型
EIO_DT_BLK (int)
ノード型
EIO_DT_MPB (int)
多重化ブロックデバイス (v7+coherent)
EIO_DT_REG (int)
ノード型
EIO_DT_NWK (int)
EIO_DT_CMP (int)
HP-UX ネットワークノード型
EIO_DT_LNK (int)
リンクノード型
EIO_DT_SOCK (int)
ソケットノード型
EIO_DT_DOOR (int)
Solaris door ノード型
EIO_DT_WHT (int)
ノード型
EIO_DT_MAX (int)
ノード型の最大値

例

例1 eio_readdir() の例

<?php
/* eio_readdir() が終わったら呼ばれます */
function my_readdir_callback($data, $result) {
echo __FUNCTION__, " called\n";
echo "data: "; var_dump($data);
echo "result: "; var_dump($result);
echo "\n";
}

eio_readdir("/var/spool/news", EIO_READDIR_STAT_ORDER | EIO_READDIR_DIRS_FIRST,
EIO_PRI_DEFAULT, "my_readdir_callback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

my_readdir_callback called
data: NULL
result: array(2) {
 ["names"]=>
  array(7) {
   [0]=>
    string(7) "archive"
    [1]=>
    string(8) "articles"
    [2]=>
    string(8) "incoming"
    [3]=>
    string(7) "innfeed"
    [4]=>
    string(8) "outgoing"
    [5]=>
    string(8) "overview"
    [6]=>
    string(3) "tmp"
  }
 ["dents"]=>
  array(7) {
   [0]=>
    array(3)
    {
     ["name"]=>
      string(7)
      "archive"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393265)
    }
   [1]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "articles"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393266)
    }
   [2]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "incoming"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393267)
    }
   [3]=>
    array(3)
    {
     ["name"]=>
      string(7)
      "innfeed"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393269)
    }
   [4]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "outgoing"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393270)
    }
   [5]=>
    array(3)
    {
     ["name"]=>
      string(8)
      "overview"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393271)
    }
   [6]=>
    array(3)
    {
     ["name"]=>
      string(3)
      "tmp"
      ["type"]=>
      int(4)
      ["inode"]=>
      int(393272)
    }
  }
}


シンボリックリンクの値を読む

  • ≪ eio_readdir
  • eio_realpath ≫
  • PHP Manual
  • Eio 関数
  • シンボリックリンクの値を読む

eio_readlink

(PECL eio >= 0.0.1dev)

eio_readlink — シンボリックリンクの値を読む

説明

eio_readlink(
string $path,
int $pri,
callable $callback,
mixed $data = NULL
): resource

パラメータ

path

シンボリックリンクへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_readlink() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_readlink() の例

<?php
$filename = dirname(__FILE__)."/symlink.dat";
touch($filename);
$link = dirname(__FILE__)."/symlink.link";
$hardlink = dirname(__FILE__)."/hardlink.link";

function my_hardlink_cb($data, $result) {
global $link, $filename;
var_dump(file_exists($data) && !is_link($data));
@unlink($data);

eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
}

function my_symlink_cb($data, $result) {
global $link, $filename;
var_dump(file_exists($data) && is_link($data));

if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
@unlink($link);
@unlink($filename);
}
}

function my_readlink_cb($data, $result) {
global $filename, $link;
var_dump($result);

@unlink($link);
@unlink($filename);
}

eio_link($filename, $hardlink, EIO_PRI_DEFAULT, "my_hardlink_cb", $hardlink);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
string(16) "/tmp/symlink.dat"

参考

  • eio_symlink() - シンボリックリンクを作る


正規化された絶対パスを取得する

  • ≪ eio_readlink
  • eio_rename ≫
  • PHP Manual
  • Eio 関数
  • 正規化された絶対パスを取得する

eio_realpath

(PECL eio >= 0.0.1dev)

eio_realpath — 正規化された絶対パスを取得する

説明

eio_realpath(
string $path,
int $pri,
callable $callback,
string $data = NULL
): resource

eio_realpath() は、正規化された絶対パスを callback 関数の result 引数で返します。

パラメータ

path

短い形式のパス。

pri

callback

data

戻り値

例

例1 eio_realpath() の例

<?php
var_dump(getcwd());

function my_realpath_allback($data, $result) {
var_dump($result);
}

eio_realpath("../", EIO_PRI_DEFAULT, "my_realpath_allback");
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/home/ruslan"
string(5) "/home"


ファイル名や場所を変更する

  • ≪ eio_realpath
  • eio_rmdir ≫
  • PHP Manual
  • Eio 関数
  • ファイル名や場所を変更する

eio_rename

(PECL eio >= 0.0.1dev)

eio_rename — ファイル名や場所を変更する

説明

eio_rename(
string $path,
string $new_path,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_rename() は、ファイル名を変更したり別の場所に移動したりします。

パラメータ

path

元のパス。

new_path

変更後のパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_rename() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_rename() の例

<?php
$filename = dirname(__FILE__)."/eio-temp-file.dat";
touch($filename);
$new_filename = dirname(__FILE__)."/eio-temp-file-new.dat";

function my_rename_cb($data, $result) {
global $filename, $new_filename;

if ($result == 0 && !file_exists($filename) && file_exists($new_filename)) {
@unlink($new_filename);
echo "eio_rename_ok";
} else {
@unlink($filename);
}
}

eio_rename($filename, $new_filename, EIO_PRI_DEFAULT, "my_rename_cb", $filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_rename_ok


ディレクトリを削除する

  • ≪ eio_rename
  • eio_seek ≫
  • PHP Manual
  • Eio 関数
  • ディレクトリを削除する

eio_rmdir

(PECL eio >= 0.0.1dev)

eio_rmdir — ディレクトリを削除する

説明

eio_rmdir(
string $path,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_rmdir() は、ディレクトリを削除します。

パラメータ

path

ディレクトリへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_rmdir() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_rmdir() の例

<?php
$temp_dirname = "eio-temp-dir";
mkdir($temp_dirname);

function my_rmdir_callback($data, $result) {
if ($result == 0 && !file_exists($data)) {
echo "eio_rmdir_ok";
} else if (file_exists($data)) {
rmdir($data);
}
}

eio_rmdir($temp_dirname, EIO_PRI_DEFAULT, "my_rmdir_callback", $temp_dirname);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

eio_rmdir_ok

参考

  • eio_mkdir() - ディレクトリを作る


fd で指定したファイル内でのオフセットを、offset と whence に従って移動する

  • ≪ eio_rmdir
  • eio_sendfile ≫
  • PHP Manual
  • Eio 関数
  • fd で指定したファイル内でのオフセットを、offset と whence に従って移動する

eio_seek

(PECL eio >= 0.5.0b)

eio_seek — fd で指定したファイル内でのオフセットを、offset と whence に従って移動する

説明

eio_seek(
mixed $fd,
int $offset,
int $whence,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_seek() は、fd で指定したファイル内でのオフセットを、offset と whence で指定した位置に移動します。whence の意味は次のとおりです。

  • EIO_SEEK_SET - 戦闘から offset バイトの位置に移動する。
  • EIO_SEEK_CUR - 現在の位置から offset バイト進める。
  • EIO_SEEK_END - ファイルの末尾から offset バイト進める。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ。

offset

読み込みの開始位置。

length

読み込むバイト数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_seek() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ファイルディスクリプタ間でデータを転送する

  • ≪ eio_seek
  • eio_set_max_idle ≫
  • PHP Manual
  • Eio 関数
  • ファイルディスクリプタ間でデータを転送する

eio_sendfile

(PECL eio >= 0.0.1dev)

eio_sendfile — ファイルディスクリプタ間でデータを転送する

説明

eio_sendfile(
mixed $out_fd,
mixed $in_fd,
int $offset,
int $length,
int $pri = ?,
callable $callback = ?,
string $data = ?
): resource

eio_sendfile() は、一方のファイルディスクリプタから もう一方のファイルディスクリプタにデータをコピーします。 詳細は SENDFILE(2) の man ページを参照ください。

パラメータ

out_fd

出力先のストリーム、ソケットリソース、あるいはファイルディスクリプタ。 書き込みモードでのオープンが必須です。

in_fd

入力元のストリーム、ソケットリソース、あるいはファイルディスクリプタ。 読み込みモードでのオープンが必須です。

offset

元ファイル内でのオフセット。

length

コピーするバイト数。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_sendfile() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


アイドルスレッドの最大数を設定する

  • ≪ eio_sendfile
  • eio_set_max_parallel ≫
  • PHP Manual
  • Eio 関数
  • アイドルスレッドの最大数を設定する

eio_set_max_idle

(PECL eio >= 0.0.1dev)

eio_set_max_idle — アイドルスレッドの最大数を設定する

説明

eio_set_max_idle(int $nthreads): void

パラメータ

nthreads

アイドルスレッドの数。

戻り値

値を返しません。

参考

  • eio_nthreads() - 現在利用中のスレッド数を返す
  • eio_set_min_parallel() - 最小の並列スレッド数を設定する
  • eio_set_max_parallel() - 最大の並列スレッド数を設定する


最大の並列スレッド数を設定する

  • ≪ eio_set_max_idle
  • eio_set_max_poll_reqs ≫
  • PHP Manual
  • Eio 関数
  • 最大の並列スレッド数を設定する

eio_set_max_parallel

(PECL eio >= 0.0.1dev)

eio_set_max_parallel — 最大の並列スレッド数を設定する

説明

eio_set_max_parallel(int $nthreads): void

パラメータ

nthreads

並列スレッドの数。

戻り値

値を返しません。

参考

  • eio_nthreads() - 現在利用中のスレッド数を返す
  • eio_set_max_idle() - アイドルスレッドの最大数を設定する
  • eio_set_min_parallel() - 最小の並列スレッド数を設定する


一度のポールで行う最大のリクエスト回数を設定する

  • ≪ eio_set_max_parallel
  • eio_set_max_poll_time ≫
  • PHP Manual
  • Eio 関数
  • 一度のポールで行う最大のリクエスト回数を設定する

eio_set_max_poll_reqs

(PECL eio >= 0.0.1dev)

eio_set_max_poll_reqs — 一度のポールで行う最大のリクエスト回数を設定する

説明

eio_set_max_poll_reqs(int $nreqs): void

パラメータ

nreqs

リクエスト回数。

戻り値

値を返しません。


最大のポール時間を設定する

  • ≪ eio_set_max_poll_reqs
  • eio_set_min_parallel ≫
  • PHP Manual
  • Eio 関数
  • 最大のポール時間を設定する

eio_set_max_poll_time

(PECL eio >= 0.0.1dev)

eio_set_max_poll_time — 最大のポール時間を設定する

説明

eio_set_max_poll_time(float $nseconds): void

ポールの所要時間が nseconds 秒を超えると、処理を止めます。

パラメータ

nseconds

秒数。

戻り値

値を返しません。


最小の並列スレッド数を設定する

  • ≪ eio_set_max_poll_time
  • eio_stat ≫
  • PHP Manual
  • Eio 関数
  • 最小の並列スレッド数を設定する

eio_set_min_parallel

(PECL eio >= 0.0.1dev)

eio_set_min_parallel — 最小の並列スレッド数を設定する

説明

eio_set_min_parallel(string $nthreads): void

パラメータ

nthreads

並列スレッドの数。

戻り値

値を返しません。

参考

  • eio_nthreads() - 現在利用中のスレッド数を返す
  • eio_set_max_idle() - アイドルスレッドの最大数を設定する
  • eio_set_max_parallel() - 最大の並列スレッド数を設定する


ファイルの状態を取得する

  • ≪ eio_set_min_parallel
  • eio_statvfs ≫
  • PHP Manual
  • Eio 関数
  • ファイルの状態を取得する

eio_stat

(PECL eio >= 0.0.1dev)

eio_stat — ファイルの状態を取得する

説明

eio_stat(
string $path,
int $pri,
callable $callback,
mixed $data = NULL
): resource

eio_stat() は、 callback の result 引数でファイルの状態を返します。

パラメータ

path

ファイルへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_stat() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します。 成功した場合は、callback の result 引数に配列が格納されます。

例

例1 eio_stat() の例

<?php
$tmp_filename = "eio-file.tmp";
touch($tmp_filename);

function my_res_cb($data, $result) {
var_dump($data);
var_dump($result);
}

function my_open_cb($data, $result) {
eio_close($result);
eio_event_loop();

@unlink($data);
}

eio_stat($tmp_filename, EIO_PRI_DEFAULT, "my_res_cb", "eio_stat");
eio_open($tmp_filename, EIO_O_RDONLY, NULL,
EIO_PRI_DEFAULT, "my_open_cb", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(8) "eio_stat"
array(12) {
  ["st_dev"]=>
  int(2050)
  ["st_ino"]=>
  int(2489173)
  ["st_mode"]=>
  int(33188)
  ["st_nlink"]=>
  int(1)
  ["st_uid"]=>
  int(1000)
  ["st_gid"]=>
  int(100)
  ["st_rdev"]=>
  int(0)
  ["st_blksize"]=>
  int(4096)
  ["st_blocks"]=>
  int(0)
  ["st_atime"]=>
  int(1318250380)
  ["st_mtime"]=>
  int(1318250380)
  ["st_ctime"]=>
  int(1318250380)
}

参考

  • eio_lstat() - ファイルの状態を取得する
  • eio_fstat() - ファイルの状態を取得する


ファイルシステムの状態を取得する

  • ≪ eio_stat
  • eio_symlink ≫
  • PHP Manual
  • Eio 関数
  • ファイルシステムの状態を取得する

eio_statvfs

(PECL eio >= 0.0.1dev)

eio_statvfs — ファイルシステムの状態を取得する

説明

eio_statvfs(
string $path,
int $pri,
callable $callback,
mixed $data = ?
): resource

eio_statvfs() は、ファイルシステムの状態を callback の result で返します。

パラメータ

path

マウントされたファイルシステム内のファイルのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_statvfs() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します。 成功した場合は、callback の result 引数に配列が格納されます。

例

例1 eio_statvfs() の例

<?php
$tmp_filename = '/tmp/eio-file.tmp';
touch($tmp_filename);

function my_statvfs_callback($data, $result) {
var_dump($data);
var_dump($result);

@unlink($data);
}

eio_statvfs($tmp_filename, EIO_PRI_DEFAULT, "my_statvfs_callback", $tmp_filename);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

string(17) "/tmp/eio-file.tmp"
array(11) {
  ["f_bsize"]=>
  int(4096)
  ["f_frsize"]=>
  int(4096)
  ["f_blocks"]=>
  int(262144)
  ["f_bfree"]=>
  int(262111)
  ["f_bavail"]=>
  int(262111)
  ["f_files"]=>
  int(1540815)
  ["f_ffree"]=>
  int(1540743)
  ["f_favail"]=>
  int(1540743)
  ["f_fsid"]=>
  int(0)
  ["f_flag"]=>
  int(4102)
  ["f_namemax"]=>
  int(255)
}


シンボリックリンクを作る

  • ≪ eio_statvfs
  • eio_sync ≫
  • PHP Manual
  • Eio 関数
  • シンボリックリンクを作る

eio_symlink

(PECL eio >= 0.0.1dev)

eio_symlink — シンボリックリンクを作る

説明

eio_symlink(
string $path,
string $new_path,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_symlink() は、path へのシンボリックリンク new_path を作ります。

パラメータ

path

リンク元のパス。

new_path

リンク先のパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_symlink() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

例

例1 eio_symlink() の例

<?php
$filename = dirname(__FILE__)."/symlink.dat";
touch($filename);
$link = dirname(__FILE__)."/symlink.link";

function my_symlink_cb($data, $result) {
global $link, $filename;
var_dump(file_exists($data) && is_link($data));

if (!eio_readlink($data, EIO_PRI_DEFAULT, "my_readlink_cb", NULL)) {
@unlink($link);
@unlink($filename);
}
}

function my_readlink_cb($data, $result) {
global $filename, $link;
var_dump($result);

@unlink($link);
@unlink($filename);
}

eio_symlink($filename, $link, EIO_PRI_DEFAULT, "my_symlink_cb", $link);
eio_event_loop();
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
string(16) "/tmp/symlink.dat"

参考

  • eio_link() - ファイルのハードリンクを作る


バッファのキャッシュをディスクに書き込む

  • ≪ eio_symlink
  • eio_sync_file_range ≫
  • PHP Manual
  • Eio 関数
  • バッファのキャッシュをディスクに書き込む

eio_sync

(PECL eio >= 0.0.1dev)

eio_sync — バッファのキャッシュをディスクに書き込む

説明

eio_sync(int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

パラメータ

この関数にはパラメータはありません。

戻り値

eio_sync() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ファイルセグメントをディスクに同期する

  • ≪ eio_sync
  • eio_syncfs ≫
  • PHP Manual
  • Eio 関数
  • ファイルセグメントをディスクに同期する

eio_sync_file_range

(PECL eio >= 0.0.1dev)

eio_sync_file_range — ファイルセグメントをディスクに同期する

説明

eio_sync_file_range(
mixed $fd,
int $offset,
int $nbytes,
int $flags,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_sync_file_range() は、ファイルディスクリプタ fd が指すオープン中のファイルをディスクに同期します。

パラメータ

fd

ファイルディスクリプタ。

offset

同期を開始する位置をバイト単位で指定する。

nbytes

同期させる範囲の長さをバイト単位で指定する。 nbytes がゼロの場合は、offset からファイルの末尾までのすべての範囲を同期します。

flags

ビットマスク。以下のいずれかの値を含めます。 EIO_SYNC_FILE_RANGE_WAIT_BEFORE, EIO_SYNC_FILE_RANGE_WRITE, EIO_SYNC_FILE_RANGE_WAIT_AFTER. これらのフラグは、それぞれ対応する SYNC_FILE_RANGE_* と同じ意味です (SYNC_FILE_RANGE(2) の man ページを参照ください)。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_sync_file_range() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


Linux の syncfs システムコールが使えれば、それを呼ぶ

  • ≪ eio_sync_file_range
  • eio_truncate ≫
  • PHP Manual
  • Eio 関数
  • Linux の syncfs システムコールが使えれば、それを呼ぶ

eio_syncfs

(PECL eio >= 0.0.1dev)

eio_syncfs — Linux の syncfs システムコールが使えれば、それを呼ぶ

説明

eio_syncfs(
mixed $fd,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

パラメータ

fd

ファイルディスクリプタ。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_syncfs() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ファイルを切り詰める

  • ≪ eio_syncfs
  • eio_unlink ≫
  • PHP Manual
  • Eio 関数
  • ファイルを切り詰める

eio_truncate

(PECL eio >= 0.0.1dev)

eio_truncate — ファイルを切り詰める

説明

eio_truncate(
string $path,
int $offset = 0,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_truncate() は、path で指定したファイルを切り詰めて、ちょうど length バイトにします。

パラメータ

path

ファイルへのパス。

offset

ファイルの先頭からのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_busy() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_ftruncate() - ファイルを切り詰める


名前を削除し、その名前で参照しているファイルも削除する

  • ≪ eio_truncate
  • eio_utime ≫
  • PHP Manual
  • Eio 関数
  • 名前を削除し、その名前で参照しているファイルも削除する

eio_unlink

(PECL eio >= 0.0.1dev)

eio_unlink — 名前を削除し、その名前で参照しているファイルも削除する

説明

eio_unlink(
string $path,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_unlink() は、その名前をファイルシステムから削除します。

パラメータ

path

ファイルへのパス。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_unlink() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します


ファイルの最終アクセス時刻と変更時刻を変更する

  • ≪ eio_unlink
  • eio_write ≫
  • PHP Manual
  • Eio 関数
  • ファイルの最終アクセス時刻と変更時刻を変更する

eio_utime

(PECL eio >= 0.0.1dev)

eio_utime — ファイルの最終アクセス時刻と変更時刻を変更する

説明

eio_utime(
string $path,
float $atime,
float $mtime,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

パラメータ

path

ファイルへのパス。

atime

アクセス時刻。

mtime

変更時刻。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_utime() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_futime() - ファイルの最終アクセス時刻と変更時刻を変更する


ファイルに書き込む

  • ≪ eio_utime
  • Ev ≫
  • PHP Manual
  • Eio 関数
  • ファイルに書き込む

eio_write

(PECL eio >= 0.0.1dev)

eio_write — ファイルに書き込む

説明

eio_write(
mixed $fd,
string $str,
int $length = 0,
int $offset = 0,
int $pri = EIO_PRI_DEFAULT,
callable $callback = NULL,
mixed $data = NULL
): resource

eio_write() は、str の先頭から offset バイトの位置から、最大で length バイトまで書き込みます。

パラメータ

fd

ストリーム、ソケットリソース、あるいは数値で表したファイルディスクリプタ (eio_open() が返すものなど)。

str

ソース文字列。

length

書き込む最大バイト数。

offset

ファイルの先頭からのオフセット。

pri

リクエストの優先順位。EIO_PRI_DEFAULT、EIO_PRI_MIN、EIO_PRI_MAX あるいは null を指定します。 null を渡した場合、pri は内部的に EIO_PRI_DEFAULT となります。

callback

callback 関数が、リクエスト終了時にコールされます。 この関数のプロトタイプは、

void callback(mixed $data, int $result[, resource $req]);
に一致しなければなりません。
data

は、リクエストに渡すカスタムデータです。

result

にはリクエスト固有の結果が格納されます。基本的には、対応するシステムコールが返すそのままの値となります。

req

はオプションで指定するリクエストリソースです。 eio_get_last_error() のような関数で使えます。

data

callback に渡す任意の引数。

戻り値

eio_write() は、成功した場合にリクエストリソースを返します。失敗した場合に false を返します

参考

  • eio_open() - ファイルを開く


Ev

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
  • ウォッチャー
  • ウォッチャーのコールバック
  • Periodic ウォッチャーの操作モード
  • Ev — Ev クラス
    • Ev::backend — libev が使うバックエンドを表す整数値を返す
    • Ev::depth — 再帰の深さを返す
    • Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す
    • Ev::feedSignal — シグナルイベントを Ev に送る
    • Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る
    • Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す
    • Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す
    • Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する
    • Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
    • Ev::resume — 一時停止していたデフォルトのイベントループを再開させる
    • Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する
    • Ev::sleep — 指定した秒数だけプロセスをブロックする
    • Ev::stop — デフォルトのイベントループを止める
    • Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す
    • Ev::suspend — デフォルトのイベントループを一時停止する
    • Ev::time — epoch から現在時刻までの秒数を返す
    • Ev::verify — 内部の整合性をチェックする (デバッグ用)
  • EvCheck — EvCheck クラス
    • EvCheck::__construct — EvCheck ウォッチャーオブジェクトを作る
    • EvCheck::createStopped — 停止した EvCheck ウォッチャーのインスタンスを作る
  • EvChild — The EvChild class
    • EvChild::__construct — EvChild ウォッチャーオブジェクトを作る
    • EvChild::createStopped — 停止した EvChild ウォッチャーのインスタンスを作る
    • EvChild::set — ウォッチャーを設定する
  • EvEmbed — EvEmbed クラス
    • EvEmbed::__construct — EvEmbed オブジェクトを作る
    • EvEmbed::createStopped — 停止した EvEmbed ウォッチャーのインスタンスを作る
    • EvEmbed::set — ウォッチャーを設定する
    • EvEmbed::sweep — 埋め込んだループに対して単一の非ブロックスイープを行う
  • EvFork — EvFork クラス
    • EvFork::__construct — EvFork ウォッチャーオブジェクトを作る
    • EvFork::createStopped — 停止した EvFork ウォッチャーのインスタンスを作る
  • EvIdle — The EvIdle class
    • EvIdle::__construct — Constructs the EvIdle watcher object
    • EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object
  • EvIo — The EvIo class
    • EvIo::__construct — Constructs EvIo watcher object
    • EvIo::createStopped — Create stopped EvIo watcher object
    • EvIo::set — Configures the watcher
  • EvLoop — The EvLoop class
    • EvLoop::backend — Returns an integer describing the backend used by libev
    • EvLoop::check — Creates EvCheck object associated with the current event loop instance
    • EvLoop::child — Creates EvChild object associated with the current event loop
    • EvLoop::__construct — Constructs the event loop object
    • EvLoop::defaultLoop — Returns or creates the default event loop
    • EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object
    • EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
    • EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
    • EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
    • EvLoop::io — Create EvIo watcher object associated with the current event loop instance
    • EvLoop::loopFork — Must be called after a fork
    • EvLoop::now — Returns the current "event loop time"
    • EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
    • EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
    • EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
    • EvLoop::resume — Resume previously suspended default event loop
    • EvLoop::run — Begin checking for events and calling callbacks for the loop
    • EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
    • EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
    • EvLoop::stop — Stops the event loop
    • EvLoop::suspend — Suspend the loop
    • EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
    • EvLoop::verify — Performs internal consistency checks(for debugging)
  • EvPeriodic — The EvPeriodic class
    • EvPeriodic::again — Simply stops and restarts the periodic watcher again
    • EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
    • EvPeriodic::__construct — Constructs EvPeriodic watcher object
    • EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
    • EvPeriodic::set — Configures the watcher
  • EvPrepare — EvPrepare クラス
    • EvPrepare::__construct — EvPrepare ウォッチャーオブジェクトを作る
    • EvPrepare::createStopped — 停止した EvPrepare ウォッチャーのインスタンスを作る
  • EvSignal — The EvSignal class
    • EvSignal::__construct — Constructs EvSignal watcher object
    • EvSignal::createStopped — Create stopped EvSignal watcher object
    • EvSignal::set — Configures the watcher
  • EvStat — The EvStat class
    • EvStat::attr — Returns the values most recently detected by Ev
    • EvStat::__construct — Constructs EvStat watcher object
    • EvStat::createStopped — Create a stopped EvStat watcher object
    • EvStat::prev — Returns the previous set of values returned by EvStat::attr
    • EvStat::set — Configures the watcher
    • EvStat::stat — Initiates the stat call
  • EvTimer — The EvTimer class
    • EvTimer::again — Restarts the timer watcher
    • EvTimer::__construct — Constructs an EvTimer watcher object
    • EvTimer::createStopped — Creates EvTimer stopped watcher object
    • EvTimer::set — Configures the watcher
  • EvWatcher — The EvWatcher class
    • EvWatcher::clear — Clear watcher pending status
    • EvWatcher::__construct — Abstract constructor of a watcher object
    • EvWatcher::feed — Feeds the given revents set into the event loop
    • EvWatcher::getLoop — Returns the loop responsible for the watcher
    • EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
    • EvWatcher::keepalive — Configures whether to keep the loop from returning
    • EvWatcher::setCallback — Sets new callback for the watcher
    • EvWatcher::start — Starts the watcher
    • EvWatcher::stop — Stops the watcher


はじめに

この拡張モジュールは、 » libev ライブラリへのインターフェイスを提供します。 このライブラリは、C で書かれたハイパフォーマンスで高機能なイベントループです。

注意: この拡張モジュールは Windows 環境では利用できません。

Libev はイベントループです。何か興味のあるイベント (ファイルディスクリプタが読み込み可能になった、あるいはタイムアウトが発生したなど) を登録すると、そのイベントの発生元を管理してプログラムにイベントを提供します。

そのためには、イベントループハンドラを実行して プロセス (あるいはスレッド) を完全に制御する必要があります。 イベントとの通信には、コールバックの仕組みを利用します。

興味のあるイベントを登録するには、イベントウォッチャーを登録します。 そして、ウォッチャーを開始して libev に手渡します。

詳細は » libev のドキュメント を参照ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Ev
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

libev ライブラリはこの拡張モジュールに組み込まれているので、 個別にインストールする必要はありません。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ev .


例

例1 タイマーのサンプル

<?php
// タイマーを作り、2 秒後に起動します
$w1 = new EvTimer(2, 0, function () {
echo "2 seconds elapsed\n";
});

// タイマーを作って 2 秒後に起動させ、その後は
// 手で止めるまで 1 秒おきに繰り返します
$w2 = new EvTimer(2, 1, function ($w) {
echo "is called every second, is launched after 2 seconds\n";
echo "iteration = ", Ev::iteration(), PHP_EOL;

// 5 回繰り返したあとでウォッチャーを止めます
Ev::iteration() == 5 and $w->stop();
// Stop the watcher if further calls cause more than 10 iterations
Ev::iteration() >= 10 and $w->stop();
});

// 停止状態のタイマーを作ります。開始させるまでは非アクティブになります。
$w_stopped = EvTimer::createStopped(10, 5, function($w) {
echo "Callback of a timer created as stopped\n";

// 2 回繰り返したあとでウォッチャーを止めます
Ev::iteration() >= 2 and $w->stop();
});

// Ev::stop() が呼ばれるか、すべてのウォッチャーが止まるまでループします
Ev::run();

// 開始させ、うまく動いているかどうかを確認します
$w_stopped->start();
echo "Run single iteration\n";
Ev::run(Ev::RUN_ONCE);

echo "Restart the second watcher and try to handle the same events, but don't block\n";
$w2->again();
Ev::run(Ev::RUN_NOWAIT);

$w = new EvTimer(10, 0, function() {});
echo "Running a blocking loop\n";
Ev::run();
echo "END\n";
?>

上の例の出力は、 たとえば以下のようになります。

2 seconds elapsed
is called every second, is launched after 2 seconds
iteration = 1
is called every second, is launched after 2 seconds
iteration = 2
is called every second, is launched after 2 seconds
iteration = 3
is called every second, is launched after 2 seconds
iteration = 4
is called every second, is launched after 2 seconds
iteration = 5
Run single iteration
Callback of a timer created as stopped
Restart the second watcher and try to handle the same events, but don't block
Running a blocking loop
is called every second, is launched after 2 seconds
iteration = 8
is called every second, is launched after 2 seconds
iteration = 9
is called every second, is launched after 2 seconds
iteration = 10
END

例2 10.5 秒おきに繰り返すタイマー

<?php
$w = new EvPeriodic(0., 10.5, NULL, function ($w, $revents) {
echo time(), PHP_EOL;
});

Ev::run();
?>

例3 再スケジュールコールバックを使う定期タイマー

<?php
// 10.5 秒おきに繰り返します

function reschedule_cb ($watcher, $now) {
return $now + (10.5. - fmod($now, 10.5));
}

$w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
echo time(), PHP_EOL;
});

Ev::run();
?>

例4 すぐに開始し、10.5 秒おきに繰り返すタイマー

<?php
// すぐに開始し、10.5 秒おきに繰り返します
$w = new EvPeriodic(fmod(Ev::now(), 10.5), 10.5, NULL, function ($w, $revents) {
echo time(), PHP_EOL;
});

Ev::run();
?>

例5 STDIN が読み込み可能になるまで待つ例

<?php
// STDIN が読み込み可能になるまで待ちます
$w = new EvIo(STDIN, Ev::READ, function ($watcher, $revents) {
echo "STDIN is readable\n";
});

Ev::run(Ev::RUN_ONCE);
?>

例6 非同期 I/O を使ったソケットへのアクセス

<?php
/* 非同期 I/O を使ってソケットにアクセスします */

// `sockets' 拡張モジュールは、
// EINPROGRESS や EAGAIN/EWOULDBLOCK などに対して warning を発光します
error_reporting(E_ERROR);

$e_nonblocking = array (/*EAGAIN or EWOULDBLOCK*/11, /*EINPROGRESS*/115);

// WWW サービス用のポートを取得します
$service_port = getservbyname('www', 'tcp');

// 対象ホストの IP アドレスを取得します
$address = gethostbyname('google.co.uk');

// TCP/IP ソケットを作ります
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === FALSE) {
echo "socket_create() failed: reason: "
.socket_strerror(socket_last_error()) . "\n";
}

// O_NONBLOCK フラグを立てます
socket_set_nonblock($socket);

// タイムアウト時に終了させます
$timeout_watcher = new EvTimer(10.0, 0., function () use ($socket) {
socket_close($socket);
Ev::stop(Ev::BREAK_ALL);
});

// ソケットが書き込み可能になったときに HEAD リクエストを作ります
$write_watcher = new EvIo($socket, Ev::WRITE, function ($w)
use ($socket, $timeout_watcher, $e_nonblocking)
{
// タイムアウトのウォッチャーを止めます
$timeout_watcher->stop();
// 書き込みのウォッチャーを止めます
$w->stop();

$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: google.co.uk\r\n";
$in .= "Connection: Close\r\n\r\n";

if (!socket_write($socket, $in, strlen($in))) {
trigger_error("Failed writing $in to socket", E_USER_ERROR);
}

$read_watcher = new EvIo($socket, Ev::READ, function ($w, $re)
use ($socket, $e_nonblocking)
{
// ソケットが読み込み可能になりました。非ブロックモードで 20 バイト recv() します
$ret = socket_recv($socket, $out, 20, MSG_DONTWAIT);

if ($ret) {
echo $out;
} elseif ($ret === 0) {
// すべて読み終えました
$w->stop();
socket_close($socket);
return;
}

// EINPROGRESS、EAGAIN あるいは EWOULDBLOCK を捕捉した場合
if (in_array(socket_last_error(), $e_nonblocking)) {
return;
}

$w->stop();
socket_close($socket);
});

Ev::run();
});

$result = socket_connect($socket, $address, $service_port);

Ev::run();
?>

上の例の出力は、 たとえば以下のようになります。

HTTP/1.1 301 Moved Permanently
Location: http://www.google.co.uk/
Content-Type: text/html; CHARSET=shift-jis
Date: Sun, 23 Dec 2012 16:08:27 GMT
Expires: Tue, 22 Jan 2013 16:08:27 GMT
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
Connection: close

例7 ループの中に別のループを埋め込む例

<?php
/*
* 埋め込み可能なイベントループをデフォルトのイベントループに組み込みます。
* できなかった場合はデフォルトのループを使います。
* デフォルトのループは $loop_hi に、そして埋め込み可能なループは $loop_lo
* に格納されます (埋め込み可能なループが使えなかった場合は $loop_hi
* を使います)。
*
* このサンプルを PHP に移植したものです。
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop_hi = EvLoop::defaultLoop();
$loop_lo = NULL;
$embed = NULL;

/*
* 使えるループを取得できるかどうかを調べます
* (フラグの値が 0 の場合は自動検出を意味します)
*/
$loop_lo = Ev::embeddableBackends() & Ev::recommendedBackends()
? new EvLoop(Ev::embeddableBackends() & Ev::recommendedBackends())
: 0;

if ($loop_lo) {
$embed = new EvEmbed($loop_lo, function () {});
} else {
$loop_lo = $loop_hi;
}
?>

例8 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
$embed = new EvEmbed($loop);
}
}

if (!$socket_loop) {
$socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

例9 SIGTERM の処理

<?php
$w = new EvSignal(SIGTERM, function ($watcher) {
echo "SIGTERM received\n";
$watcher->stop();
});

Ev::run();
?>

例10 /var/log/messages の変更の監視

<?php
// 更新間隔を 10 秒にします
$w = new EvStat("/var/log/messages", 8, function ($w) {
echo "/var/log/messages changed\n";

$attr = $w->attr();

if ($attr['nlink']) {
printf("Current size: %ld\n", $attr['size']);
printf("Current atime: %ld\n", $attr['atime']);
printf("Current mtime: %ld\n", $attr['mtime']);
} else {
fprintf(STDERR, "`messages` file is not there!");
$w->stop();
}
});

Ev::run();
?>

例11 /var/log/messages の変更の監視 (1 秒の遅延を使って、更新を見落とさないようにする)

<?php
$timer = EvTimer::createStopped(0., 1.02, function ($w) {
$w->stop();

$stat = $w->data;

// ファイルへの直近の変更から 1 秒後
printf("Current size: %ld\n", $stat->attr()['size']);
});

$stat = new EvStat("/var/log/messages", 0., function () use ($timer) {
// タイマーウォッチャーをリセットします
$timer->again();
});

$timer->data = $stat;

Ev::run();
?>

例12 ステータスの変更の処理

<?php
$pid = pcntl_fork();

if ($pid == -1) {
fprintf(STDERR, "pcntl_fork failed\n");
} elseif ($pid) {
$w = new EvChild($pid, FALSE, function ($w, $revents) {
$w->stop();

printf("Process %d exited with status %d\n", $w->rpid, $w->rstatus);
});

Ev::run();

// ゾンビ対策
pcntl_wait($status);
} else {
// フォークした子プロセス
exit(2);
}
?>


ウォッチャー

ウォッチャーは、何らかのイベントに関する興味を記録するオブジェクトです。 たとえば次のコードは、 STDIN が読み込み可能になるまで待ちます。

<?php
// STDIN が読み込み可能になるまで待ちます
$w = new EvIo(STDIN, Ev::READ, function ($watcher, $revents) {
echo "STDIN is readable\n";
});
Ev::run(Ev::RUN_ONCE);
?>

すべてのウォッチャーのコンストラクタが、自動的にウォッチャーを開始します。 createStopped メソッドを使う (EvIo::createStopped() など) と、停止状態のウォッチャーを作れます。

ウォッチャーオブジェクトを破棄するときには、自動的にウォッチャーが停止することに注意しましょう。 したがって、コンストラクタやファクトリーメソッドが返すオブジェクトはずっと維持する必要があります。

また、ウォッチャーのプロパティ (set や priority etc.) を変更するすべてのメソッドは、自動的にウォッチャーを停止して アクティブになったら立ち上げなおすことにも注意しましょう。 つまり、未処理のイベントは失われてしまいます。

ウォッチャーのコールバック も参照ください。


ウォッチャーのコールバック

すべてのウォッチャーは、アクティブ (イベントを待ち受け中) あるいは非アクティブ (一時停止) の状態になります。 コールバックを実行できるのは、アクティブなウォッチャーだけです。 すべてのコールバックは、少なくとも二つの引数を付けて呼ばれます。 watcher (ウォッチャー)、そして revents (受け取ったイベントのビットマスク) です。

ウォッチャーのコールバックは、ウォッチャーのコンストラクタ (EvWatcher の派生クラス。 EvCheck::__construct() や EvChild::__construct() など) に渡します。コールバックは、次のプロトタイプにしたがわなければいけません。

callback( object $watcher = NULL , int $revents = NULL ): void

watcher

EvWatcher を継承したクラスのインスタンス。

revents

ウォッチャーが受信したイベント

ウォッチャーの型によって、 revents に関連するビットが割り当てられています。 そのため、複数のウォッチャーに対して同じコールバックを使えます。 イベントのマスクは、イベントの型にちなんだ名前になっています。たとえば EvChild (あるいは EvLoop::child()) は EV::CHILD、 EvPrepare (あるいは EvLoop::prepare()) は Ev::PREPARE、 EvPeriodic (あるいは EvLoop::periodic()) は Ev::PERIODIC などです。ただ I/O のイベントは例外で、これは Ev::READ と Ev::WRITE の両方のビットを設定します。


Periodic ウォッチャーの操作モード

EvPeriodic ウォッチャーは、パラメータ offset、interval および reschedule_cb の設定によってさまざまなモードで動作します。

  1. 絶対時刻のタイマー。 このモードでは、interval = 0 そして reschedule_cb = null となります。 このときは、単純に offset で指定した時刻に実行してその後は繰り返しません。 時刻の飛びがあっても調整はしません。つまり、 January 1st 2014 に実行するように設定した場合は、 システム時刻がこの時刻に達するかこの時刻を過ぎたときに実行されます。

  2. 繰り返しタイマー。 このモードでは、interval > 0 そして reschedule_cb = null となります。ウォッチャーは常に、 offset + N * interval (N は何らかの整数) 経過後にタイムアウトするようにスケジュールされ、 その後繰り返します。時刻の飛びは気にしません。

    これを使うと、システムの時刻に流されないタイマーを作れます。

    <?php
    $hourly     = EvPeriodic(0, 3600, NULL, function () {
    echo     "once per hour\n";
    });
    ?>
    これは、必ずしも 3600 秒おきにイベントが発生することを意味するものではありません。 システムの時刻が一時間経過するごとにコールバックが呼ばれるというものです。

    EvPeriodic は、 time = offset (mod interval) となる次の時刻にコールバックをこのモードで実行しようと試みます。 時刻の飛びは気にしません。

  3. 手動再スケジュールモード。 このモードでは、reschedule_cb が callable になります。

    interval と offset はどちらも無視します。毎回定期ウォッチャーがスケジュールされ、再スケジュールコールバック (reschedule_cb) が呼び出されます。 コールバックの最初の引数がウォッチャー、そして二番目の引数が現在時刻となります。

    このコールバックは、自分自身あるいは他の定期ウォッチャーを停止したり破棄したり してはいけません。また、 イベントループ関数やメソッドも 呼んではいけません。 ウォッチャーを止めるには、1e30 を返した後で停止します。 このタスクには、EvPrepare ウォッチャーが使えます。

    コールバックは、次の実行時刻を返す必要があります。次の実行時刻は、 コールバックに渡された時刻をベースにしたものです (つまり、二番目の引数で受け取った時刻と同じかそれよりも大きな値を返します)。 コールバックが呼ばれるのは、通常はイベントが発生する直前ですが、それ以外の場合にも呼ばれる可能性があります。

    例1 再スケジュールコールバックの利用

    <?php
    // 10.5 秒おきに繰り返します

    function reschedule_cb ($watcher, $now) {
    return     $now + (10.5. - fmod($now, 10.5));
    }

    $w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
    echo     time(), PHP_EOL;
    });

    Ev::run();
    ?>


Ev クラス

(PECL ev >= 0.2.0)

はじめに

Ev は静的クラスで、デフォルトのループへのアクセスや各種共通操作へのアクセスを提供します。

クラス概要

final class Ev {
/* 定数 */
const int FLAG_AUTO = 0;
const int FLAG_NOENV = 16777216;
const int FLAG_FORKCHECK = 33554432;
const int FLAG_NOINOTIFY = 1048576;
const int FLAG_SIGNALFD = 2097152;
const int FLAG_NOSIGMASK = 4194304;
const int RUN_NOWAIT = 1;
const int RUN_ONCE = 2;
const int BREAK_CANCEL = 0;
const int BREAK_ONE = 1;
const int BREAK_ALL = 2;
const int MINPRI = -2;
const int MAXPRI = 2;
const int READ = 1;
const int WRITE = 2;
const int TIMER = 256;
const int PERIODIC = 512;
const int SIGNAL = 1024;
const int CHILD = 2048;
const int STAT = 4096;
const int IDLE = 8192;
const int PREPARE = 16384;
const int CHECK = 32768;
const int EMBED = 65536;
const int CUSTOM = 16777216;
const int ERROR = 2147483648;
const int BACKEND_SELECT = 1;
const int BACKEND_POLL = 2;
const int BACKEND_EPOLL = 4;
const int BACKEND_KQUEUE = 8;
const int BACKEND_DEVPOLL = 16;
const int BACKEND_PORT = 32;
const int BACKEND_ALL = 63;
const int BACKEND_MASK = 65535;
/* メソッド */
final public static backend(): int
final public static depth(): int
final public static embeddableBackends(): int
final public static feedSignal( int $signum ): void
final public static feedSignalEvent( int $signum ): void
final public static iteration(): int
final public static now(): float
final public static nowUpdate(): void
final public static recommendedBackends(): int
final public static resume(): void
final public static run( int $flags = ?): void
final public static sleep( float $seconds ): void
final public static stop( int $how = ?): void
final public static supportedBackends(): int
final public static suspend(): void
final public static time(): float
final public static verify(): void
}

定義済み定数

ループを作るときに渡すフラグ

Ev::FLAG_AUTO

デフォルトのフラグの値。

Ev::FLAG_NOENV

このフラグを使う (あるいは setuid や setgid でプログラムを実行する) と、 libev は環境変数 LIBEV_FLAGS を見ません。 それ以外の場合 (デフォルト) は、 LIBEV_FLAGS が見つかった場合は その内容でフラグを上書きします。パフォーマンステストやバグの調査のときに有用です。

Ev::FLAG_FORKCHECK

libev が繰り返しのたびにフォークをチェックするようにします。毎回手動で EvLoop::fork() を呼ぶことがなくなります。 これを実現するために、ループ内での繰り返しの旅に getpid() を呼んでいます。 そのため、繰り返しの回数が増えるとイベントループがスローダウンするかもしれませんが、 通常は気になるほどではありません。このフラグの設定を上書きしたり、 環境変数 LIBEV_FLAGS で指定したりすることはできません。

Ev::FLAG_NOINOTIFY

このフラグを指定すると、 libev は » ev_stat ウォッチャーに inotify API を使わなくなります。 このフラグは inotify ファイルディスクリプタを節約するのに便利です。 これを使わなければ、ev_stat ウォッチャーを使ったループのたびに inotify ハンドルをひとつずつ消費することになります。

Ev::FLAG_SIGNALFD

このフラグを指定すると、 libev は » ev_signal (および » ev_child ) ウォッチャーに signalfd API を使おうとします。 この API はシグナルを同期的に配送し、高速に処理したり キューに入ったシグナルデータを取得できるようにしたりします。 また、スレッドを使ったときのシグナル処理も、 スレッド内でシグナルが適切にブロックされている限りはシンプルになります。 デフォルトでは signalfd を使いません。

Ev::FLAG_NOSIGMASK

このフラグを指定すると、 libev はシグナルのマスクを変更しないようにします。 具体的には、シグナルが受信されるまではブロックしないようになるということです。

これは、自前のシグナル処理をするときに便利です。 また、特定のスレッドでだけシグナルを処理するという場合にも有用です。

Ev::run() あるいは EvLoop::run() に渡すフラグ

Ev::RUN_NOWAIT

イベントループが新しいイベントを探し、 新しいイベントや未処理のイベントを処理するけれども、 もしイベントが見つからない場合は、最初のループですぐに呼び出し元に制御を戻します。 イベントを待つためにプロセスをブロックしたりはしません。 これは、時間のかかる計算をしているときのポーリングなどに便利です。 プログラムの動きを止めることなく新しいイベントを処理できます。

Ev::RUN_ONCE

イベントループが (必要なら待ち続けてでも) 新しいイベントを探し、 その新しいイベントや未処理のイベントを処理します。 少なくとも一つのイベントがやってくるまで (libev 自身のイベント間隔になるでしょう。 そのため、ユーザー低位のコールバックが呼ばれる保証はありません) プロセスをブロックし ループ処理の終了後に呼び出し元に制御を戻します。

Ev::stop() あるいは EvLoop::stop() に渡すフラグ

Ev::BREAK_CANCEL

ブレーク操作をキャンセルします。

Ev::BREAK_ONE

一番内側の Ev::run() (あるいは EvLoop::run() ) の呼び出しを返します。

Ev::BREAK_ALL

ネストしたすべての Ev::run() (あるいは EvLoop::run() ) の呼び出しを返します。

ウォッチャーの優先度

Ev::MINPRI

最小の優先度。

Ev::MAXPRI

最大の優先度。

受信したイベントのビットマスク

Ev::READ

EvIo ウォッチャーが読み込み可能になったときのファイルディスクリプタ。

Ev::WRITE

EvIo ウォッチャーが書き込み可能になったときのファイルディスクリプタ。

Ev::TIMER

EvTimer ウォッチャーがタイムアウトしました。

Ev::PERIODIC

EvPeriodic ウォッチャーがタイムアウトしました。

Ev::SIGNAL

EvSignal::__construct() のコンストラクタで指定したシグナルを受信しました。

Ev::CHILD

EvChild::__construct() のコンストラクタで指定した pid が、状態の変更を受信しました。

Ev::STAT

EvStat ウォッチャーで指定したパスが、その属性を変更しました。

Ev::IDLE

他のウォッチャーが何もすることがなくなったときに、 EvIdle ウォッチャーが動作します。

Ev::PREPARE

すべての EvPrepare ウォッチャーが、 Ev::run() の開始前に起動しました。つまり、 イベントループがスリープしたり新しいイベントのポーリングをしたりする直前に EvPrepare ウォッチャーが起動するということになります。

Ev::CHECK

すべての EvCheck ウォッチャーが、 Ev::run() が新しいイベントをとりまとめた直後 (ただし受信したイベントのコールバックをキューに入れる前) にキューに入ります。つまり、 イベントループ内で優先度が同じ (あるいはより低い) ウォッチャーより前に EvCheck ウォッチャーが起動するということになります。

Ev::EMBED

EvEmbed で指定した埋め込みイベントループのウォッチャーが注目する必要があります。

Ev::CUSTOM

まだ libev で送信したりそれ以外の使いかたをしたりはしていませんが、 libev ユーザーが (EvWatcher::feed() などで) ウォッチャーに通知するために使えます。

Ev::ERROR

指定されていないエラーが発生し、ウォッチャーが停止しました。 これが発生する原因として考えられるのは、 libev がメモリ不足でウォッチャーをきちんと開始できなかった場合や ファイルディスクリプタが閉じてしまった場合などがあります。 libev は、これらに関してはアプリケーションのバグとみなします。 詳細は » ANATOMY OF A WATCHER を参照ください。

バックエンドのフラグ

Ev::BACKEND_SELECT

select(2) バックエンド

Ev::BACKEND_POLL

poll(2) バックエンド

Ev::BACKEND_EPOLL

Linux 限定の epoll(7) バックエンド。2.6.9 以前のカーネルでもそれ以降のカーネルでも使えます。

Ev::BACKEND_KQUEUE

kqueue バックエンド。大半の BSD システムで利用します。 EvEmbed ウォッチャーを使って、 kqueue バックエンドのループを別のループに埋め込むことができます。 たとえば、 kqueue バックエンドのループを作って、 それをソケットに対してだけ使うこともできます。

Ev::BACKEND_DEVPOLL

Solaris 8 バックエンド。現時点では未実装です。

Ev::BACKEND_PORT

Solaris 10 のイベントポート機構で、規模が大きくなっても対応できます。

Ev::BACKEND_ALL

壊れているものも含めて、すべてのバックエンドを試します。 これを明示的に使うことは推奨しません。ビット演算子を使って、 Ev::BACKEND_ALL & ~ Ev::BACKEND_KQUEUE のようにするか、 Ev::recommendedBackends() を使うか、あるいは何もバックエンドを指定しないようにしましょう。

Ev::BACKEND_MASK

これはバックエンドではなく、 flags の中のすべてのバックエンドビットをマスクするものです。 たとえば、環境変数 LIBEV_FLAGS を変更するときに使います。

注意:

デフォルトのループの場合は、モジュールの初期化時に Ev が (もし使えれば) pthread_atfork を使って » ev_loop_fork の呼び出しを登録します。

注意:

Ev クラスには、 デフォルトのイベントループ にアクセスするメソッドが用意されています (Ev::iteration() や Ev::depth() など)。 カスタムループ (EvLoop::__construct() で作ったもの) の場合、これらの値にアクセスするには EvLoop クラスのプロパティやメソッドを使います。

デフォルトのイベントループ自体のインスタンスを取得するには EvLoop::defaultLoop() メソッドを使います。

目次

  • Ev::backend — libev が使うバックエンドを表す整数値を返す
  • Ev::depth — 再帰の深さを返す
  • Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す
  • Ev::feedSignal — シグナルイベントを Ev に送る
  • Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る
  • Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す
  • Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す
  • Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する
  • Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::resume — 一時停止していたデフォルトのイベントループを再開させる
  • Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する
  • Ev::sleep — 指定した秒数だけプロセスをブロックする
  • Ev::stop — デフォルトのイベントループを止める
  • Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す
  • Ev::suspend — デフォルトのイベントループを一時停止する
  • Ev::time — epoch から現在時刻までの秒数を返す
  • Ev::verify — 内部の整合性をチェックする (デバッグ用)


libev が使うバックエンドを表す整数値を返す

  • ≪ Ev
  • Ev::depth ≫
  • PHP Manual
  • Ev
  • libev が使うバックエンドを表す整数値を返す

Ev::backend

(PECL ev >= 0.2.0)

Ev::backend — libev が使うバックエンドを表す整数値を返す

説明

final public static Ev::backend(): int

libev が使うバックエンドを表す整数値を返します。 バックエンドのフラグ も参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

libev が使うバックエンドを表す整数値 (ビットマスク) を返します。

参考

  • EvEmbed
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す
  • Ev::recommendedBackends() - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::supportedBackends() - 現在の libev の構成でサポートするバックエンド群を返す
  • バックエンドのフラグ


再帰の深さを返す

  • ≪ Ev::backend
  • Ev::embeddableBackends ≫
  • PHP Manual
  • Ev
  • 再帰の深さを返す

Ev::depth

(PECL ev >= 0.2.0)

Ev::depth — 再帰の深さを返す

説明

final public static Ev::depth(): int

Ev::run() に入った回数から Ev::run() を正常終了した回数を引いた結果、 つまり、再帰の深さを返します。 Ev::run() の外部では、この数は 0 になります。 コールバックの中では、この数は 1 になります。ただし、Ev::run() が再帰的に呼び出されている (あるいは別スレッドから呼び出されている) 場合は、もっと大きな数になります。

パラメータ

この関数にはパラメータはありません。

戻り値

ev_depth() は、デフォルトのループの再帰の深さを返します。

参考

  • Ev::iteration() - デフォルトのイベントループが新しいイベントをポーリングした回数を返す


他のイベントループに埋め込めるバックエンド群を返す

  • ≪ Ev::depth
  • Ev::feedSignal ≫
  • PHP Manual
  • Ev
  • 他のイベントループに埋め込めるバックエンド群を返す

Ev::embeddableBackends

(PECL ev >= 0.2.0)

Ev::embeddableBackends — 他のイベントループに埋め込めるバックエンド群を返す

説明

final public static Ev::embeddableBackends(): int

他のイベントループに埋め込めるバックエンド群を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ビットマスクを返します。 バックエンドのフラグ を、ビット OR 演算子で組み合わせたものになります。

例

例1 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
$embed = new EvEmbed($loop);
}
}

if (!$socket_loop) {
$socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

参考

  • EvEmbed
  • Ev::recommendedBackends() - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::supportedBackends() - 現在の libev の構成でサポートするバックエンド群を返す
  • バックエンドのフラグ
  • 例


シグナルイベントを Ev に送る

  • ≪ Ev::embeddableBackends
  • Ev::feedSignalEvent ≫
  • PHP Manual
  • Ev
  • シグナルイベントを Ev に送る

Ev::feedSignal

(PECL ev >= 0.2.0)

Ev::feedSignal — シグナルイベントを Ev に送る

説明

final public static Ev::feedSignal( int $signum ): void

シグナルの受信をシミュレートします。 この関数は、いつでもどんなコンテキストでも安全に呼べます。 シグナルハンドラやランダムスレッドからでもだいじょうぶです。 主に、プロセス内で自前のシグナル処理を行う場合に使います。

Ev::feedSignalEvent() とは違い、どのループがシグナルを登録したのかにかかわらず動作します。

パラメータ

signum

シグナル番号。詳細は signal(7) の man ページを参照ください。 pcntl 拡張モジュールが公開する定数も使えます。

戻り値

値を返しません。

参考

  • Ev::feedSignalEvent() - シグナルイベントの情報をデフォルトループに送る


シグナルイベントの情報をデフォルトループに送る

  • ≪ Ev::feedSignal
  • Ev::iteration ≫
  • PHP Manual
  • Ev
  • シグナルイベントの情報をデフォルトループに送る

Ev::feedSignalEvent

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ev::feedSignalEvent — シグナルイベントの情報をデフォルトループに送る

説明

final public static Ev::feedSignalEvent( int $signum ): void

シグナルイベントをデフォルトループに送ります。 Ev は、signal で指定したシグナルを受け取ったかのように反応します。

パラメータ

signum

シグナル番号。詳細は signal(7) の man ページを参照ください。 pcntl 拡張モジュールが公開する定数も使えます。

戻り値

値を返しません。

参考

  • Ev::feedSignal() - シグナルイベントを Ev に送る


デフォルトのイベントループが新しいイベントをポーリングした回数を返す

  • ≪ Ev::feedSignalEvent
  • Ev::now ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループが新しいイベントをポーリングした回数を返す

Ev::iteration

(PECL ev >= 0.2.0)

Ev::iteration — デフォルトのイベントループが新しいイベントをポーリングした回数を返す

説明

final public static Ev::iteration(): int

デフォルトのイベントループが新しいイベントをポーリングした回数を返します。 生成カウンターとして有用です。

パラメータ

この関数にはパラメータはありません。

戻り値

デフォルトのイベントループのポーリング回数を返します。

参考

  • Ev::depth() - 再帰の深さを返す


デフォルトのイベントループで直近の処理が始まった時刻を返す

  • ≪ Ev::iteration
  • Ev::nowUpdate ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループで直近の処理が始まった時刻を返す

Ev::now

(PECL ev >= 0.2.0)

Ev::now — デフォルトのイベントループで直近の処理が始まった時刻を返す

説明

final public static Ev::now(): float

デフォルトのイベントループで直近の処理が始まった時刻を返します。 これはタイマー (EvTimer および EvPeriodic) が基準にしているもので、 通常は Ev::time() を呼ぶよりも高速になります。

パラメータ

この関数にはパラメータはありません。

戻り値

デフォルトのイベントループで直近の処理が始まった時刻を表す秒数を返します。

参考

  • Ev::nowUpdate() - カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する


カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

  • ≪ Ev::now
  • Ev::recommendedBackends ≫
  • PHP Manual
  • Ev
  • カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

Ev::nowUpdate

(PECL ev >= 0.2.0)

Ev::nowUpdate — カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する

説明

final public static Ev::nowUpdate(): void

カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now() が返す時刻を更新します。これはコストが高い操作で、通常は自動的に Ev::run() の中で実行します。

このメソッドが役立つ場面はほとんどありませんが、 たとえば何かのイベントコールバックがイベントループに入らず長時間処理を続けているときに、 libev が把握する現在時刻を更新するというのがその一つになります。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Ev::now() - デフォルトのイベントループで直近の処理が始まった時刻を返す


現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す

  • ≪ Ev::nowUpdate
  • Ev::resume ≫
  • PHP Manual
  • Ev
  • 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す

Ev::recommendedBackends

(PECL ev >= 0.2.0)

Ev::recommendedBackends — 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す

説明

final public static Ev::recommendedBackends(): int

この libev のバイナリに組み込まれたすべてのバックエンドと、 中でもこのプラットフォーム上でおすすめのバックエンドを返します。 おすすめとは、多くのファイルディスクリプタ形式に対応しているということです。 このバックエンド群は、ev_supported_backends() が返すものより少なくなることがよくあります。たとえば kqueue は大半の BSD システムでうまく動かず、 明示的にリクエストしない限り自動検出できないからです。 このメソッドが返すバックエンドはどれも、明示的に指定しなくても libev で使えます。

パラメータ

この関数にはパラメータはありません。

戻り値

ビットマスクを返します。 バックエンドのフラグ を、ビット OR 演算子で組み合わせたものになります。

例

例1 ループの中に別のループを埋め込む例

<?php
/*
* 埋め込み可能なイベントループをデフォルトのイベントループに組み込みます。
* できなかった場合はデフォルトのループを使います。
* デフォルトのループは $loop_hi に、そして埋め込み可能なループは $loop_lo
* に格納されます (埋め込み可能なループが使えなかった場合は $loop_hi
* を使います)。
*
* このサンプルを PHP に移植したものです。
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop_hi = EvLoop::defaultLoop();
$loop_lo = NULL;
$embed = NULL;

/*
* 使えるループを取得できるかどうかを調べます
* (フラグの値が 0 の場合は自動検出を意味します)
*/
$loop_lo = Ev::embeddableBackends() & Ev::recommendedBackends()
? new EvLoop(Ev::embeddableBackends() & Ev::recommendedBackends())
: 0;

if ($loop_lo) {
$embed = new EvEmbed($loop_lo, function () {});
} else {
$loop_lo = $loop_hi;
}
?>

参考

  • EvEmbed
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す
  • Ev::supportedBackends() - 現在の libev の構成でサポートするバックエンド群を返す
  • バックエンドのフラグ
  • 例


一時停止していたデフォルトのイベントループを再開させる

  • ≪ Ev::recommendedBackends
  • Ev::run ≫
  • PHP Manual
  • Ev
  • 一時停止していたデフォルトのイベントループを再開させる

Ev::resume

(PECL ev >= 0.2.0)

Ev::resume — 一時停止していたデフォルトのイベントループを再開させる

説明

final public static Ev::resume(): void

Ev::suspend() と Ev::resume() が、それぞれループの一時停止と再開に対応します。

すべてのタイマーウォッチャーは、 suspend から resume までの時間だけ遅延します。また、すべての定期ウォッチャーは再スケジュールされます (つまり、一時停止中に発生したイベントは失うことになります)。

Ev::suspend() を呼んだ後は、
そのループ上では Ev::resume() 以外の関数を呼べません。
また、先に Ev::suspend() を呼んでいない状態で
Ev::resume()
は呼べません。

suspend や resume を呼ぶと、 イベントループの時刻を更新するという副作用があります (Ev::nowUpdate() を参照ください)。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Ev::suspend() - デフォルトのイベントループを一時停止する


イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

  • ≪ Ev::resume
  • Ev::sleep ≫
  • PHP Manual
  • Ev
  • イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

Ev::run

(PECL ev >= 0.2.0)

Ev::run — イベントのチェックとデフォルトループのコールバックの呼び出しを開始する

説明

final public static Ev::run( int $flags = ?): void

イベントのチェックとデフォルトループのコールバックの呼び出しを開始します。 コールバックが Ev::stop() メソッドを読んだとき、 あるいは flags がゼロ以外のとき (この場合の戻り値は true) に結果を返します。あるいは、ループを参照するアクティブなウォッチャーがないとき (EvWatcher::keepalive() が true) のときにも結果を返し、このときに返す値は false になります。 戻り値の解釈は、一般的に、 もし true ならまだ作業が残っている となります。

パラメータ

flags

オプションのパラメータで、以下のいずれかになります。

flags に指定できる値の一覧
flags | 説明
0 | 上で述べたデフォルトの挙動。
Ev::RUN_ONCE | 最大 1 件ブロックします (待つけれども繰り返しません)。
Ev::RUN_NOWAIT | まったくブロックしません (イベントを取得して処理しますが、待ちません)。

実行フラグ定数 も参照ください。

戻り値

値を返しません。

参考

  • Ev::stop() - デフォルトのイベントループを止める
  • EvLoop::run() - Begin checking for events and calling callbacks for the loop


指定した秒数だけプロセスをブロックする

  • ≪ Ev::run
  • Ev::stop ≫
  • PHP Manual
  • Ev
  • 指定した秒数だけプロセスをブロックする

Ev::sleep

(PECL ev >= 0.2.0)

Ev::sleep — 指定した秒数だけプロセスをブロックする

説明

final public static Ev::sleep( float $seconds ): void

指定した秒数だけプロセスをブロックします。

パラメータ

seconds

秒数。

戻り値

値を返しません。


デフォルトのイベントループを止める

  • ≪ Ev::sleep
  • Ev::supportedBackends ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループを止める

Ev::stop

(PECL ev >= 0.2.0)

Ev::stop — デフォルトのイベントループを止める

説明

final public static Ev::stop( int $how = ?): void

デフォルトのイベントループを止めます。

パラメータ

how

Ev::BREAK_* 定数 のいずれか。

戻り値

値を返しません。

参考

  • Ev::run() - イベントのチェックとデフォルトループのコールバックの呼び出しを開始する


現在の libev の構成でサポートするバックエンド群を返す

  • ≪ Ev::stop
  • Ev::suspend ≫
  • PHP Manual
  • Ev
  • 現在の libev の構成でサポートするバックエンド群を返す

Ev::supportedBackends

(PECL ev >= 0.2.0)

Ev::supportedBackends — 現在の libev の構成でサポートするバックエンド群を返す

説明

final public static Ev::supportedBackends(): int

現在の libev の構成でサポートするバックエンド群を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ビットマスクを返します。 バックエンドのフラグ を、ビット OR 演算子で組み合わせたものになります。

例

例1 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
$embed = new EvEmbed($loop);
}
}

if (!$socket_loop) {
$socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

参考

  • EvEmbed
  • Ev::recommendedBackends() - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す
  • バックエンドのフラグ
  • 例


デフォルトのイベントループを一時停止する

  • ≪ Ev::supportedBackends
  • Ev::time ≫
  • PHP Manual
  • Ev
  • デフォルトのイベントループを一時停止する

Ev::suspend

(PECL ev >= 0.2.0)

Ev::suspend — デフォルトのイベントループを一時停止する

説明

final public static Ev::suspend(): void

Ev::suspend() と Ev::resume() が、それぞれループの一時停止と再開に対応します。

すべてのタイマーウォッチャーは、 suspend から resume までの時間だけ遅延します。また、すべての定期ウォッチャーは再スケジュールされます (つまり、一時停止中に発生したイベントは失うことになります)。

Ev::suspend() を呼んだ後は、
そのループ上では Ev::resume() 以外の関数を呼べません。
また、先に Ev::suspend() を呼んでいない状態で
Ev::resume()
は呼べません。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Ev::resume() - 一時停止していたデフォルトのイベントループを再開させる


epoch から現在時刻までの秒数を返す

  • ≪ Ev::suspend
  • Ev::verify ≫
  • PHP Manual
  • Ev
  • epoch から現在時刻までの秒数を返す

Ev::time

(PECL ev >= 0.2.0)

Ev::time — epoch から現在時刻までの秒数を返す

説明

final public static Ev::time(): float

epoch から現在時刻までの秒数を返します。 Ev::now() を使うことを検討しましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

epoch から現在時刻までの秒数を返します。

参考

  • Ev::now() - デフォルトのイベントループで直近の処理が始まった時刻を返す


内部の整合性をチェックする (デバッグ用)

  • ≪ Ev::time
  • EvCheck ≫
  • PHP Manual
  • Ev
  • 内部の整合性をチェックする (デバッグ用)

Ev::verify

(PECL ev >= 0.2.0)

Ev::verify — 内部の整合性をチェックする (デバッグ用)

説明

final public static Ev::verify(): void

内部の整合性をチェック (libev のデバッグ用) し、もしデータ構造が壊れている場合はプログラムを終了させます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


EvCheck クラス

(PECL ev >= 0.2.0)

はじめに

EvPrepare ウォッチャーと EvCheck ウォッチャーは、 通常はペアで使います。 EvPrepare ウォッチャーはプロセスをブロックする前に起動し、 EvCheck はブロックした後に起動します。

EvLoop::run() あるいはそれに類するメソッドや関数 (現在のイベントループに入るもの) は、EvPrepare ウォッチャーや EvCheck ウォッチャーからは呼べません。 現在のループ以外のループは問題ありません。 その理由は、これらのウォッチャーの中では再帰をチェックする必要がないからです。 つまり、処理の流れは常に EvPrepare -> ブロック -> EvCheck となるので、これらのウォッチャーは常にペアで呼ばれ、ブロッキング呼び出しの前後を囲むことになります。

主な利用目的は他のイベント機構を libev に統合することで、 少し高度な使いかたになります。変数の変更を追跡したり 自前のウォッチャーを実装したり、net-snmp やコルーチンライブラリを統合したりといった、 さまざまな用途で使えます。 また、何らかのデータをキャッシュしてブロッキングの前にフラッシュするなどの用途で使えることもあります。

EvCheck には最高の優先度 (Ev::MAXPRI) を与えることを推奨します。 これで、ポーリングの後は他のあらゆるウォッチャーよりも先に実行されることが保証されます (EvPrepare ウォッチャーの場合は無鐘鋳です)。

また、EvCheck ウォッチャーはイベントをアクティブにしたり送信したりしてはいけません。 libev では対応してはいますが、 他の EvCheck ウォッチャーが仕事をする前に実行される可能性があります。

クラス概要

class EvCheck extends EvWatcher {
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct( callable $callback , mixed $data = ?, int $priority = ?)
final public static createStopped( string $callback , string $data = ?, string $priority = ?): object
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

目次

  • EvCheck::__construct — EvCheck ウォッチャーオブジェクトを作る
  • EvCheck::createStopped — 停止した EvCheck ウォッチャーのインスタンスを作る


EvCheck ウォッチャーオブジェクトを作る

  • ≪ EvCheck
  • EvCheck::createStopped ≫
  • PHP Manual
  • EvCheck
  • EvCheck ウォッチャーオブジェクトを作る

EvCheck::__construct

(PECL ev >= 0.2.0)

EvCheck::__construct — EvCheck ウォッチャーオブジェクトを作る

説明

public EvCheck::__construct( callable $callback , mixed $data = ?, int $priority = ?)

EvCheck ウォッチャーオブジェクトを作ります。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

参考

  • EvPrepare
  • EvLoop::check() - Creates EvCheck object associated with the current event loop instance


停止した EvCheck ウォッチャーのインスタンスを作る

  • ≪ EvCheck::__construct
  • EvChild ≫
  • PHP Manual
  • EvCheck
  • 停止した EvCheck ウォッチャーのインスタンスを作る

EvCheck::createStopped

(PECL ev >= 0.2.0)

EvCheck::createStopped — 停止した EvCheck ウォッチャーのインスタンスを作る

説明

final public static EvCheck::createStopped( string $callback , string $data = ?, string $priority = ?): object

停止した EvCheck ウォッチャーのインスタンスを作ります。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

戻り値

成功した場合に EvCheck オブジェクトを返します。

参考

  • EvPrepare


The EvChild class

(PECL ev >= 0.2.0)

はじめに

EvChild ウォッチャーは、子プロセスの状態の変更 (たいていは、停止したり終了したりといったもの) に反応してこのプロセスが SIGCHLD を受け取ったときに起動します。 EvChild ウォッチャーは、子をフォークした後 (おそらくはすでに終了した後) でインストールしてもかまいません。 ただし、まだイベントループに入っていないとき (あるいはウォッチャーから引き続いているとき) に限ります。 つまり、フォークした直後に子プロセス用のウォッチャーを登録するのはかまいませんが、 フォークした後でイベントループを何回か処理した後で登録したり、次のコールバックの実行時に登録したりすることはできません。

EvChild ウォッチャーは、 デフォルトループ の中でだけ登録できます。

クラス概要

class EvChild extends EvWatcher {
/* プロパティ */
public $pid;
public $rpid;
public $rstatus;
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct(
int $pid ,
bool $trace ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)
final public static createStopped(
int $pid ,
bool $trace ,
callable $callback ,
mixed $data = ?,
int $priority = ?
): object
public set( int $pid , bool $trace ): void
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

pid

読み込み専用。 このウォッチャーが注目するプロセス ID。0 の場合はあらゆるプロセス ID を表します。

rpid

読み込み専用。 状態の変更を検出するプロセスの ID。

rstatus

読み込み専用。 rpid のプロセス終了ステータス。

目次

  • EvChild::__construct — EvChild ウォッチャーオブジェクトを作る
  • EvChild::createStopped — 停止した EvChild ウォッチャーのインスタンスを作る
  • EvChild::set — ウォッチャーを設定する


EvChild ウォッチャーオブジェクトを作る

  • ≪ EvChild
  • EvChild::createStopped ≫
  • PHP Manual
  • EvChild
  • EvChild ウォッチャーオブジェクトを作る

EvChild::__construct

(PECL ev >= 0.2.0)

EvChild::__construct — EvChild ウォッチャーオブジェクトを作る

説明

public EvChild::__construct(
int $pid ,
bool $trace ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)

EvChild ウォッチャーオブジェクトを作ります。

プロセス ID pid (pid is 0 の場合は任意の PID) の状態の変更を受信したときに、コールバックを呼びます (状態が変わるのは、プロセスが停止したり強制終了させられたり、 trace が true になったり、さらにプロセスを一時停止したり再開したりしたときです)。 言い換えると、あるプロセスが SIGCHLD を受信したときに、 Ev はすべての変更された子プロセスやゾンビ子プロセスの exit/wait 状態を取得してコールバックを呼びます。

EvChild が終了してから child ウォッチャーをインストールしてもかまいませんが、 イベントループが次のイテレーションを始める前でないといけません。 たとえば、最初のプロセスが fork した後で新しい子プロセスが終了するかもしれません。 そのときは、新しい PID の親にだけ EvChild ウォッチャーをインストールできます。

exit/tracing ステータスや pid にアクセスするには、 ウォッチャーオブジェクトのプロパティ rstatus および rpid を使います。

一つの PID に対する PID ウォッチャーの数は無制限で、すべてが呼び出されます。

EvChild::createStopped() メソッドは、新しく作ったウォッチャーを開始させません。

パラメータ

pid

状態の変更を待つプロセスの PID (0 にすると、すべてのプロセスを対象にします)。

trace

false にすると、プロセスが終了したときにだけウォッチャーをアクティブにします。 true の場合は、プロセスが一時停止したり再開したりしたときにもウォッチャーをアクティブにします。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

参考

  • EvLoop::child() - Creates EvChild object associated with the current event loop


停止した EvChild ウォッチャーのインスタンスを作る

  • ≪ EvChild::__construct
  • EvChild::set ≫
  • PHP Manual
  • EvChild
  • 停止した EvChild ウォッチャーのインスタンスを作る

EvChild::createStopped

(PECL ev >= 0.2.0)

EvChild::createStopped — 停止した EvChild ウォッチャーのインスタンスを作る

説明

final public static EvChild::createStopped(
int $pid ,
bool $trace ,
callable $callback ,
mixed $data = ?,
int $priority = ?
): object

EvChild::__construct() と同じですが、ウォッチャーを自動的には開始しません。

パラメータ

pid

EvChild::__construct() と同じ。

trace

EvChild::__construct() と同じ。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

戻り値

参考

  • EvChild::__construct() - EvChild ウォッチャーオブジェクトを作る
  • EvLoop::child() - Creates EvChild object associated with the current event loop


ウォッチャーを設定する

  • ≪ EvChild::createStopped
  • EvEmbed ≫
  • PHP Manual
  • EvChild
  • ウォッチャーを設定する

EvChild::set

(PECL ev >= 0.2.0)

EvChild::set — ウォッチャーを設定する

説明

public EvChild::set( int $pid , bool $trace ): void

パラメータ

pid

EvChild::__construct() と同じ。

trace

EvChild::__construct() と同じ。

戻り値

値を返しません。

参考

  • EvChild::__construct() - EvChild ウォッチャーオブジェクトを作る


EvEmbed クラス

(PECL ev >= 0.2.0)

はじめに

イベントループを別のイベントループに埋め込むために使います。

クラス概要

class EvEmbed extends EvWatcher {
/* プロパティ */
public $embed;
/* メソッド */
public __construct(
object $other ,
callable $callback = ?,
mixed $data = ?,
int $priority = ?
)
final public static createStopped(
object $other ,
callable $callback = ?,
mixed $data = ?,
int $priority = ?
): void
public set( object $other ): void
public sweep(): void
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

is_active

data

is_pending

priority

embed

目次

  • EvEmbed::__construct — EvEmbed オブジェクトを作る
  • EvEmbed::createStopped — 停止した EvEmbed ウォッチャーのインスタンスを作る
  • EvEmbed::set — ウォッチャーを設定する
  • EvEmbed::sweep — 埋め込んだループに対して単一の非ブロックスイープを行う


EvEmbed オブジェクトを作る

  • ≪ EvEmbed
  • EvEmbed::createStopped ≫
  • PHP Manual
  • EvEmbed
  • EvEmbed オブジェクトを作る

EvEmbed::__construct

(PECL ev >= 0.2.0)

EvEmbed::__construct — EvEmbed オブジェクトを作る

説明

public EvEmbed::__construct(
object $other ,
callable $callback = ?,
mixed $data = ?,
int $priority = ?
)

これは高度なウォッチャー型で、あるイベントループを別のイベントループに埋め込むことができます。 現在は、埋め込みループに対応しているのは IO イベントだけです。 他の型のウォッチャーを使うと、処理が遅延したり不正確な動きになったりする可能性があるので、 使ってはいけません。

詳細は、 » libev のドキュメント を参照ください。

このウォッチャーは、BSD システムで kqueue が使えないときにも大量のソケットを処理できるようにするのに便利です。 以下の例を参照ください。

パラメータ

other

EvLoop のインスタンス。 埋め込むループです。これは埋め込み可能なものでなければいけません (Ev::embeddableBackends() を参照ください)。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

例

例1 kqueue バックエンドで作ったループをデフォルトのループに埋め込む例

<?php
/*
* kqueue が使えるかどうかを調べ、ソケットで使う kqueue バックエンドを作ります
* (通常は、どんな kqueue 実装でも動きます)。
* kqueue/socket-only イベントループを loop_socket に格納します
* (EVFLAG_NOENV も使えます)。
*
* この例を流用しました
* http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#Examples_CONTENT-9
*/
$loop = EvLoop::defaultLoop();
$socket_loop = NULL;
$embed = NULL;

if (Ev::supportedBackends() & ~Ev::recommendedBackends() & Ev::BACKEND_KQUEUE) {
if (($socket_loop = new EvLoop(Ev::BACKEND_KQUEUE))) {
$embed = new EvEmbed($loop);
}
}

if (!$socket_loop) {
$socket_loop = $loop;
}

// これで、すべてのソケットに対して $socket_loop を使い、それ以外については $loop を使うようになりました
?>

参考

  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す


停止した EvEmbed ウォッチャーのインスタンスを作る

  • ≪ EvEmbed::__construct
  • EvEmbed::set ≫
  • PHP Manual
  • EvEmbed
  • 停止した EvEmbed ウォッチャーのインスタンスを作る

EvEmbed::createStopped

(PECL ev >= 0.2.0)

EvEmbed::createStopped — 停止した EvEmbed ウォッチャーのインスタンスを作る

説明

final public static EvEmbed::createStopped(
object $other ,
callable $callback = ?,
mixed $data = ?,
int $priority = ?
): void

EvEmbed::__construct() と同じですが、ウォッチャーを自動的には開始しません。

パラメータ

other

EvEmbed::__construct() と同じ。

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

戻り値

成功した場合に、停止した EvEmbed オブジェクトを返します。

参考

  • EvEmbed::__construct() - EvEmbed オブジェクトを作る
  • Ev::embeddableBackends() - 他のイベントループに埋め込めるバックエンド群を返す


ウォッチャーを設定する

  • ≪ EvEmbed::createStopped
  • EvEmbed::sweep ≫
  • PHP Manual
  • EvEmbed
  • ウォッチャーを設定する

EvEmbed::set

(PECL ev >= 0.2.0)

EvEmbed::set — ウォッチャーを設定する

説明

public EvEmbed::set( object $other ): void

ウォッチャーを設定して、 他の イベントループオブジェクトで使えるようにします。

パラメータ

other

EvEmbed::__construct() と同じ。

戻り値

値を返しません。


埋め込んだループに対して単一の非ブロックスイープを行う

  • ≪ EvEmbed::set
  • EvFork ≫
  • PHP Manual
  • EvEmbed
  • 埋め込んだループに対して単一の非ブロックスイープを行う

EvEmbed::sweep

(PECL ev >= 0.2.0)

EvEmbed::sweep — 埋め込んだループに対して単一の非ブロックスイープを行う

説明

public EvEmbed::sweep(): void

埋め込んだループに対して単一の非ブロックスイープを行います。 次のコードとほぼ同じ動きですが、埋め込んだループ用に最適な方法をとります。

<?php
$other->start(Ev::RUN_NOWAIT);
?>

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvWatcher::start() - Starts the watcher


EvFork クラス

(PECL ev >= 0.2.0)

はじめに

Fork ウォッチャーが呼ばれるのは、fork() を検出したときです (通常は、誰かが EvLoop::fork() を呼んで libev に通知します)。 起動するのは、イベントループが次の処理をブロックする前、 そして EvCheck ウォッチャーが呼ばれる前になります。 また、フォークした後の子プロセス内でだけ起動します。 誰かが間違ったプロセスで EvLoop::fork() を呼んだとしても、fork ハンドラが起動してしまうことに注意しましょう。

クラス概要

class EvFork extends EvWatcher {
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct( callable $callback , mixed $data = null , int $priority = 0 )
final public static createStopped( string $callback , string $data = ?, string $priority = ?): object
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

目次

  • EvFork::__construct — EvFork ウォッチャーオブジェクトを作る
  • EvFork::createStopped — 停止した EvFork ウォッチャーのインスタンスを作る


EvFork ウォッチャーオブジェクトを作る

  • ≪ EvFork
  • EvFork::createStopped ≫
  • PHP Manual
  • EvFork
  • EvFork ウォッチャーオブジェクトを作る

EvFork::__construct

(PECL ev >= 0.2.0)

EvFork::__construct — EvFork ウォッチャーオブジェクトを作る

説明

public EvFork::__construct( callable $callback , mixed $data = null , int $priority = 0 )

EvFork ウォッチャーオブジェクトを作り、自動的に開始させます。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

参考

  • EvLoop::fork() - Creates EvFork watcher object associated with the current event loop instance
  • EvCheck


停止した EvFork ウォッチャーのインスタンスを作る

  • ≪ EvFork::__construct
  • EvIdle ≫
  • PHP Manual
  • EvFork
  • 停止した EvFork ウォッチャーのインスタンスを作る

EvFork::createStopped

(PECL ev >= 0.2.0)

EvFork::createStopped — 停止した EvFork ウォッチャーのインスタンスを作る

説明

final public static EvFork::createStopped( string $callback , string $data = ?, string $priority = ?): object

EvFork::__construct() と同じですが、ウォッチャーを自動的には開始しません。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

戻り値

成功した場合に、停止した EvFork オブジェクトを返します。

参考

  • EvFork::__construct() - EvFork ウォッチャーオブジェクトを作る


The EvIdle class

(PECL ev >= 0.2.0)

はじめに

EvIdle watchers trigger events when no other events of the same or higher priority are pending ( EvPrepare , EvCheck and other EvIdle watchers do not count as receiving events ).

Thus, as long as the process is busy handling sockets or timeouts(or even signals) of the same or higher priority it will not be triggered. But when the process is in idle(or only lower-priority watchers are pending), the EvIdle watchers are being called once per event loop iteration - until stopped, that is, or the process receives more events and becomes busy again with higher priority stuff.

Apart from keeping the process non-blocking(which is a useful on its own sometimes), EvIdle watchers are a good place to do "pseudo-background processing" , or delay processing stuff to after the event loop has handled all outstanding events.

The most noticeable effect is that as long as any idle watchers are active, the process will not block when waiting for new events.

クラス概要

class EvIdle extends EvWatcher {
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct( callable $callback , mixed $data = ?, int $priority = ?)
final public static createStopped( string $callback , mixed $data = ?, int $priority = ?): object
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

目次

  • EvIdle::__construct — Constructs the EvIdle watcher object
  • EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object


Constructs the EvIdle watcher object

  • ≪ EvIdle
  • EvIdle::createStopped ≫
  • PHP Manual
  • EvIdle
  • Constructs the EvIdle watcher object

EvIdle::__construct

(PECL ev >= 0.2.0)

EvIdle::__construct — Constructs the EvIdle watcher object

説明

public EvIdle::__construct( callable $callback , mixed $data = ?, int $priority = ?)

Constructs the EvIdle watcher object and starts the watcher automatically.

パラメータ

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

参考

  • EvIdle::createStopped() - Creates instance of a stopped EvIdle watcher object
  • EvLoop::idle() - Creates EvIdle watcher object associated with the current event loop instance


Creates instance of a stopped EvIdle watcher object

  • ≪ EvIdle::__construct
  • EvIo ≫
  • PHP Manual
  • EvIdle
  • Creates instance of a stopped EvIdle watcher object

EvIdle::createStopped

(PECL ev >= 0.2.0)

EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object

説明

final public static EvIdle::createStopped( string $callback , mixed $data = ?, int $priority = ?): object

The same as EvIdle::__construct() , but doesn't start the watcher automatically.

パラメータ

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

戻り値

Returns EvIdle object on success.

参考

  • EvIdle::__construct() - Constructs the EvIdle watcher object
  • EvLoop::idle() - Creates EvIdle watcher object associated with the current event loop instance


The EvIo class

(PECL ev >= 0.2.0)

はじめに

EvIo watchers check whether a file descriptor(or socket, or a stream castable to numeric file descriptor) is readable or writable in each iteration of the event loop, or, more precisely, when reading would not block the process and writing would at least be able to write some data. This behaviour is called level-triggering because events are kept receiving as long as the condition persists. To stop receiving events just stop the watcher.

The number of read and/or write event watchers per fd is unlimited. Setting all file descriptors to non-blocking mode is also usually a good idea(but not required).

Another thing to watch out for is that it is quite easy to receive false readiness notifications, i.e. the callback might be called with Ev::READ but a subsequent read() will actually block because there is no data. It is very easy to get into this situation. Thus it is best to always use non-blocking I/O: An extra read() returning EAGAIN (or similar) is far preferable to a program hanging until some data arrives.

If for some reason it is impossible to run the fd in non-blocking mode, then separately re-test whether a file descriptor is really ready. Some people additionally use SIGALRM and an interval timer, just to be sure thry won't block infinitely.

Always consider using non-blocking mode.

クラス概要

class EvIo extends EvWatcher {
/* プロパティ */
public $fd;
public $events;
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct(
mixed $fd ,
int $events ,
callable $callback ,
mixed $data = ?,
int $priority = ?
)
final public static createStopped(
mixed $fd ,
int $events ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvIo
public set( mixed $fd , int $events ): void
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

fd

events

目次

  • EvIo::__construct — Constructs EvIo watcher object
  • EvIo::createStopped — Create stopped EvIo watcher object
  • EvIo::set — Configures the watcher


Constructs EvIo watcher object

  • ≪ EvIo
  • EvIo::createStopped ≫
  • PHP Manual
  • EvIo
  • Constructs EvIo watcher object

EvIo::__construct

(PECL ev >= 0.2.0)

EvIo::__construct — Constructs EvIo watcher object

説明

public EvIo::__construct(
mixed $fd ,
int $events ,
callable $callback ,
mixed $data = ?,
int $priority = ?
)

Constructs EvIo watcher object and starts the watcher automatically.

パラメータ

fd

Can be a stream opened with fopen() or similar functions, numeric file descriptor, or socket.

events

Ev::READ and/or Ev::WRITE . See the bit masks .

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

参考

  • EvIo::createStopped() - Create stopped EvIo watcher object
  • EvLoop::io() - Create EvIo watcher object associated with the current event loop instance


Create stopped EvIo watcher object

  • ≪ EvIo::__construct
  • EvIo::set ≫
  • PHP Manual
  • EvIo
  • Create stopped EvIo watcher object

EvIo::createStopped

(PECL ev >= 0.2.0)

EvIo::createStopped — Create stopped EvIo watcher object

説明

final public static EvIo::createStopped(
mixed $fd ,
int $events ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvIo

The same as EvIo::__construct() , but doesn't start the watcher automatically.

パラメータ

fd

The same as for EvIo::__construct()

events

The same as for EvIo::__construct()

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

戻り値

Returns EvIo object on success.

参考

  • EvIo::__construct() - Constructs EvIo watcher object
  • EvLoop::io() - Create EvIo watcher object associated with the current event loop instance


Configures the watcher

  • ≪ EvIo::createStopped
  • EvLoop ≫
  • PHP Manual
  • EvIo
  • Configures the watcher

EvIo::set

(PECL ev >= 0.2.0)

EvIo::set — Configures the watcher

説明

public EvIo::set( mixed $fd , int $events ): void

Configures the EvIo watcher

パラメータ

fd

The same as for EvIo::__construct()

events

The same as for EvIo::__construct()

戻り値

値を返しません。


The EvLoop class

(PECL ev >= 0.2.0)

はじめに

Represents an event loop that is always distinct from the default loop . Unlike the default loop , it cannot handle EvChild watchers.

Having threads we have to create a loop per thread, and use the default loop in the parent thread.

The default event loop is initialized automatically by Ev . It is accessible via methods of the Ev class, or via EvLoop::defaultLoop() method.

クラス概要

final class EvLoop {
/* プロパティ */
public $data;
public $backend;
public $is_default_loop;
public $iteration;
public $pending;
public $io_interval;
public $timeout_interval;
public $depth;
/* メソッド */
public __construct(
int $flags = ?,
mixed $data = NULL ,
float $io_interval = 0.0 ,
float $timeout_interval = 0.0
)
public backend(): int
final public check( string $callback , string $data = ?, string $priority = ?): EvCheck
final public child(
string $pid ,
string $trace ,
string $callback ,
string $data = ?,
string $priority = ?
): EvChild
public static defaultLoop(
int $flags = Ev::FLAG_AUTO ,
mixed $data = NULL ,
float $io_interval = 0. ,
float $timeout_interval = 0.
): EvLoop
final public embed(
string $other ,
string $callback = ?,
string $data = ?,
string $priority = ?
): EvEmbed
final public fork( callable $callback , mixed $data = null , int $priority = 0 ): EvFork
final public idle( callable $callback , mixed $data = null , int $priority = 0 ): EvIdle
public invokePending(): void
final public io(
mixed $fd ,
int $events ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvIo
public loopFork(): void
public now(): float
public nowUpdate(): void
final public periodic(
float $offset ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvPeriodic
final public prepare( callable $callback , mixed $data = null , int $priority = 0 ): EvPrepare
public resume(): void
public run( int $flags = 0 ): void
final public signal(
int $signum ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvSignal
final public stat(
string $path ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvStat
public stop( int $how = ?): void
public suspend(): void
final public timer(
float $after ,
float $repeat ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvTimer
public verify(): void
}

プロパティ

data

Custom data attached to loop

backend

Readonly . The backend flags indicating the event backend in use.

is_default_loop

Readonly . true if it is the default event loop.

iteration

The current iteration count of the loop. See Ev::iteration()

pending

The number of pending watchers. 0 indicates that there are no watchers pending.

io_interval

Higher io_interval allows libev to spend more time collecting EvIo events, so more events can be handled per iteration, at the cost of increasing latency. Timeouts (both EvPeriodic and EvTimer ) will not be affected. Setting this to a non-zero value will introduce an additional sleep() call into most loop iterations. The sleep time ensures that libev will not poll for EvIo events more often than once per this interval, on average. Many programs can usually benefit by setting the io_interval to a value near 0.1 , which is often enough for interactive servers(not for games). It usually doesn't make much sense to set it to a lower value than 0.01 , as this approaches the timing granularity of most systems.

See also » FUNCTIONS CONTROLLING EVENT LOOPS .

timeout_interval

Higher timeout_interval allows libev to spend more time collecting timeouts, at the expense of increased latency/jitter/inexactness(the watcher callback will be called later). EvIo watchers will not be affected. Setting this to a non-null value will not introduce any overhead in libev . See also » FUNCTIONS CONTROLLING EVENT LOOPS .

depth

The recursion depth. See Ev::depth() .

目次

  • EvLoop::backend — Returns an integer describing the backend used by libev
  • EvLoop::check — Creates EvCheck object associated with the current event loop instance
  • EvLoop::child — Creates EvChild object associated with the current event loop
  • EvLoop::__construct — Constructs the event loop object
  • EvLoop::defaultLoop — Returns or creates the default event loop
  • EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object
  • EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
  • EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
  • EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
  • EvLoop::io — Create EvIo watcher object associated with the current event loop instance
  • EvLoop::loopFork — Must be called after a fork
  • EvLoop::now — Returns the current "event loop time"
  • EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
  • EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
  • EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
  • EvLoop::resume — Resume previously suspended default event loop
  • EvLoop::run — Begin checking for events and calling callbacks for the loop
  • EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
  • EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
  • EvLoop::stop — Stops the event loop
  • EvLoop::suspend — Suspend the loop
  • EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
  • EvLoop::verify — Performs internal consistency checks(for debugging)


Returns an integer describing the backend used by libev

  • ≪ EvLoop
  • EvLoop::check ≫
  • PHP Manual
  • EvLoop
  • Returns an integer describing the backend used by libev

EvLoop::backend

(PECL ev >= 0.2.0)

EvLoop::backend — Returns an integer describing the backend used by libev

説明

public EvLoop::backend(): int

The same as Ev::backend() , but for the loop instance.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer describing the backend used by libev. See Ev::backend() .

参考

  • Ev::backend() - libev が使うバックエンドを表す整数値を返す


Creates EvCheck object associated with the current event loop instance

  • ≪ EvLoop::backend
  • EvLoop::child ≫
  • PHP Manual
  • EvLoop
  • Creates EvCheck object associated with the current event loop instance

EvLoop::check

(PECL ev >= 0.2.0)

EvLoop::check — Creates EvCheck object associated with the current event loop instance

説明

final public EvLoop::check( string $callback , string $data = ?, string $priority = ?): EvCheck

Creates EvCheck object associated with the current event loop instance.

パラメータ

All parameters have the same meaning as for EvCheck::__construct()

戻り値

Returns EvCheck object on success.

参考

  • EvCheck::__construct() - EvCheck ウォッチャーオブジェクトを作る


Creates EvChild object associated with the current event loop

  • ≪ EvLoop::check
  • EvLoop::__construct ≫
  • PHP Manual
  • EvLoop
  • Creates EvChild object associated with the current event loop

EvLoop::child

(PECL ev >= 0.2.0)

EvLoop::child — Creates EvChild object associated with the current event loop

説明

final public EvLoop::child(
string $pid ,
string $trace ,
string $callback ,
string $data = ?,
string $priority = ?
): EvChild

Creates EvChild object associated with the current event loop.

パラメータ

All parameters have the same meaning as for EvChild::__construct()

戻り値

Returns EvChild object on success.

参考

  • EvChild::__construct() - EvChild ウォッチャーオブジェクトを作る


Constructs the event loop object

  • ≪ EvLoop::child
  • EvLoop::defaultLoop ≫
  • PHP Manual
  • EvLoop
  • Constructs the event loop object

EvLoop::__construct

(PECL ev >= 0.2.0)

EvLoop::__construct — Constructs the event loop object

説明

public EvLoop::__construct(
int $flags = ?,
mixed $data = NULL ,
float $io_interval = 0.0 ,
float $timeout_interval = 0.0
)

Constructs the event loop object.

パラメータ

flags

One of the event loop flags

data

Custom data associated with the loop.

io_interval

See io_interval

timeout_interval

See timeout_interval

参考

  • EvLoop::defaultLoop() - Returns or creates the default event loop


Returns or creates the default event loop

  • ≪ EvLoop::__construct
  • EvLoop::embed ≫
  • PHP Manual
  • EvLoop
  • Returns or creates the default event loop

EvLoop::defaultLoop

(PECL ev >= 0.2.0)

EvLoop::defaultLoop — Returns or creates the default event loop

説明

public static EvLoop::defaultLoop(
int $flags = Ev::FLAG_AUTO ,
mixed $data = NULL ,
float $io_interval = 0. ,
float $timeout_interval = 0.
): EvLoop

If the default event loop is not created, EvLoop::defaultLoop() creates it with the specified parameters. Otherwise, it just returns the object representing previously created instance ignoring all the parameters.

パラメータ

flags

One of the event loop flags

data

Custom data to associate with the loop.

io_collect_interval

See io_interval

timeout_collect_interval

See timeout_interval

戻り値

Returns EvLoop object on success.

参考

  • EvLoop::__construct() - Constructs the event loop object


Creates an instance of EvEmbed watcher associated with the current EvLoop object

  • ≪ EvLoop::defaultLoop
  • EvLoop::fork ≫
  • PHP Manual
  • EvLoop
  • Creates an instance of EvEmbed watcher associated with the current EvLoop object

EvLoop::embed

(PECL ev >= 0.2.0)

EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object

説明

final public EvLoop::embed(
string $other ,
string $callback = ?,
string $data = ?,
string $priority = ?
): EvEmbed

Creates an instance of EvEmbed watcher associated with the current EvLoop object.

パラメータ

All parameters have the same meaning as for EvEmbed::__construct() .

戻り値

Returns EvEmbed object on success.

参考

  • EvEmbed::__construct() - EvEmbed オブジェクトを作る


Creates EvFork watcher object associated with the current event loop instance

  • ≪ EvLoop::embed
  • EvLoop::idle ≫
  • PHP Manual
  • EvLoop
  • Creates EvFork watcher object associated with the current event loop instance

EvLoop::fork

(PECL ev >= 0.2.0)

EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance

説明

final public EvLoop::fork( callable $callback , mixed $data = null , int $priority = 0 ): EvFork

Creates EvFork watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvFork::__construct()

戻り値

Returns EvFork object on success.

参考

  • EvFork::__construct() - EvFork ウォッチャーオブジェクトを作る


Creates EvIdle watcher object associated with the current event loop instance

  • ≪ EvLoop::fork
  • EvLoop::invokePending ≫
  • PHP Manual
  • EvLoop
  • Creates EvIdle watcher object associated with the current event loop instance

EvLoop::idle

(PECL ev >= 0.2.0)

EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance

説明

final public EvLoop::idle( callable $callback , mixed $data = null , int $priority = 0 ): EvIdle

Creates EvIdle watcher object associated with the current event loop instance

パラメータ

All the parameters have the same meaning as for EvIdle::__construct()

戻り値

Returns EvIdle object on success.

参考

  • EvIdle::__construct() - Constructs the EvIdle watcher object


Invoke all pending watchers while resetting their pending state

  • ≪ EvLoop::idle
  • EvLoop::io ≫
  • PHP Manual
  • EvLoop
  • Invoke all pending watchers while resetting their pending state

EvLoop::invokePending

(PECL ev >= 0.2.0)

EvLoop::invokePending — Invoke all pending watchers while resetting their pending state

説明

public EvLoop::invokePending(): void

Invoke all pending watchers while resetting their pending state.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Create EvIo watcher object associated with the current event loop instance

  • ≪ EvLoop::invokePending
  • EvLoop::loopFork ≫
  • PHP Manual
  • EvLoop
  • Create EvIo watcher object associated with the current event loop instance

EvLoop::io

(PECL ev >= 0.2.0)

EvLoop::io — Create EvIo watcher object associated with the current event loop instance

説明

final public EvLoop::io(
mixed $fd ,
int $events ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvIo

Create EvIo watcher object associated with the current event loop instance.

パラメータ

All parameters have the same meaning as for EvIo::__construct()

戻り値

Returns EvIo object on success.

参考

  • EvIo::__construct() - Constructs EvIo watcher object


Must be called after a fork

  • ≪ EvLoop::io
  • EvLoop::now ≫
  • PHP Manual
  • EvLoop
  • Must be called after a fork

EvLoop::loopFork

(PECL ev >= 0.2.0)

EvLoop::loopFork — Must be called after a fork

説明

public EvLoop::loopFork(): void

Must be called after a fork in the child, before entering or continuing the event loop. An alternative is to use Ev::FLAG_FORKCHECK which calls this function automatically, at some performance loss (refer to the » libev documentation ).

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Returns the current "event loop time"

  • ≪ EvLoop::loopFork
  • EvLoop::nowUpdate ≫
  • PHP Manual
  • EvLoop
  • Returns the current "event loop time"

EvLoop::now

(PECL ev >= 0.2.0)

EvLoop::now — Returns the current "event loop time"

説明

public EvLoop::now(): float

Returns the current "event loop time", which is the time the event loop received events and started processing them. This timestamp does not change as long as callbacks are being processed, and this is also the base time used for relative timers. You can treat it as the timestamp of the event occurring(or more correctly, libev finding out about it).

パラメータ

この関数にはパラメータはありません。

戻り値

Returns time of the event loop in (fractional) seconds.

参考

  • Ev::now() - デフォルトのイベントループで直近の処理が始まった時刻を返す


Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

  • ≪ EvLoop::now
  • EvLoop::periodic ≫
  • PHP Manual
  • EvLoop
  • Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

EvLoop::nowUpdate

(PECL ev >= 0.2.0)

EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress

説明

public EvLoop::nowUpdate(): void

Establishes the current time by querying the kernel, updating the time returned by EvLoop::now() in the progress. This is a costly operation and is usually done automatically within EvLoop::run() .

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvLoop::now() - Returns the current "event loop time"
  • Ev::nowUpdate() - カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する


Creates EvPeriodic watcher object associated with the current event loop instance

  • ≪ EvLoop::nowUpdate
  • EvLoop::prepare ≫
  • PHP Manual
  • EvLoop
  • Creates EvPeriodic watcher object associated with the current event loop instance

EvLoop::periodic

(PECL ev >= 0.2.0)

EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance

説明

final public EvLoop::periodic(
float $offset ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvPeriodic

Creates EvPeriodic watcher object associated with the current event loop instance

パラメータ

All parameters have the same maening as for EvPeriodic::__construct()

戻り値

Returns EvPeriodic object on success.

参考

  • EvPeriodic::__construct() - Constructs EvPeriodic watcher object


Creates EvPrepare watcher object associated with the current event loop instance

  • ≪ EvLoop::periodic
  • EvLoop::resume ≫
  • PHP Manual
  • EvLoop
  • Creates EvPrepare watcher object associated with the current event loop instance

EvLoop::prepare

(PECL ev >= 0.2.0)

EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance

説明

final public EvLoop::prepare( callable $callback , mixed $data = null , int $priority = 0 ): EvPrepare

Creates EvPrepare watcher object associated with the current event loop instance

パラメータ

All parameters have the same maening as for EvPrepare()

戻り値

Returns EvPrepare object on success

参考

  • EvPrepare::__construct() - EvPrepare ウォッチャーオブジェクトを作る


Resume previously suspended default event loop

  • ≪ EvLoop::prepare
  • EvLoop::run ≫
  • PHP Manual
  • EvLoop
  • Resume previously suspended default event loop

EvLoop::resume

(PECL ev >= 0.2.0)

EvLoop::resume — Resume previously suspended default event loop

説明

public EvLoop::resume(): void

EvLoop::suspend() and EvLoop::resume() methods suspend and resume a loop correspondingly.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvLoop::suspend() - Suspend the loop
  • Ev::resume() - 一時停止していたデフォルトのイベントループを再開させる


Begin checking for events and calling callbacks for the loop

  • ≪ EvLoop::resume
  • EvLoop::signal ≫
  • PHP Manual
  • EvLoop
  • Begin checking for events and calling callbacks for the loop

EvLoop::run

(PECL ev >= 0.2.0)

EvLoop::run — Begin checking for events and calling callbacks for the loop

説明

public EvLoop::run( int $flags = 0 ): void

Begin checking for events and calling callbacks for the current event loop. Returns when a callback calls Ev::stop() method, or the flags are nonzero(in which case the return value is true) or when there are no active watchers which reference the loop( EvWatcher::keepalive() is true), in which case the return value will be false. The return value can generally be interpreted as if true, there is more work left to do .

パラメータ

flags

Optional parameter flags can be one of the following:

List for possible values of flags
flags | Description
0 | The default behavior described above
Ev::RUN_ONCE | Block at most one(wait, but don't loop)
Ev::RUN_NOWAIT | Don't block at all(fetch/handle events, but don't wait)

See the run flag constants .

戻り値

値を返しません。

参考

  • EvLoop::stop() - Stops the event loop
  • Ev::run() - イベントのチェックとデフォルトループのコールバックの呼び出しを開始する


Creates EvSignal watcher object associated with the current event loop instance

  • ≪ EvLoop::run
  • EvLoop::stat ≫
  • PHP Manual
  • EvLoop
  • Creates EvSignal watcher object associated with the current event loop instance

EvLoop::signal

(PECL ev >= 0.2.0)

EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance

説明

final public EvLoop::signal(
int $signum ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvSignal

Creates EvSignal watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvSignal::__construct()

戻り値

Returns EvSignal object on success

参考

  • EvSignal::__construct() - Constructs EvSignal watcher object


Creates EvStat watcher object associated with the current event loop instance

  • ≪ EvLoop::signal
  • EvLoop::stop ≫
  • PHP Manual
  • EvLoop
  • Creates EvStat watcher object associated with the current event loop instance

EvLoop::stat

(PECL ev >= 0.2.0)

EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance

説明

final public EvLoop::stat(
string $path ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvStat

Creates EvStat watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvSignal::__construct()

戻り値

Returns EvStat object on success

参考

  • EvSignal::__construct() - Constructs EvSignal watcher object


Stops the event loop

  • ≪ EvLoop::stat
  • EvLoop::suspend ≫
  • PHP Manual
  • EvLoop
  • Stops the event loop

EvLoop::stop

(PECL ev >= 0.2.0)

EvLoop::stop — Stops the event loop

説明

public EvLoop::stop( int $how = ?): void

Stops the event loop

パラメータ

how

One of Ev::BREAK_* constants .

戻り値

値を返しません。

参考

  • EvLoop::run() - Begin checking for events and calling callbacks for the loop
  • Ev::stop() - デフォルトのイベントループを止める


Suspend the loop

  • ≪ EvLoop::stop
  • EvLoop::timer ≫
  • PHP Manual
  • EvLoop
  • Suspend the loop

EvLoop::suspend

(PECL ev >= 0.2.0)

EvLoop::suspend — Suspend the loop

説明

public EvLoop::suspend(): void

EvLoop::suspend() and EvLoop::resume() methods suspend and resume a loop correspondingly.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvLoop::resume() - Resume previously suspended default event loop
  • Ev::suspend() - デフォルトのイベントループを一時停止する


Creates EvTimer watcher object associated with the current event loop instance

  • ≪ EvLoop::suspend
  • EvLoop::verify ≫
  • PHP Manual
  • EvLoop
  • Creates EvTimer watcher object associated with the current event loop instance

EvLoop::timer

(PECL ev >= 0.2.0)

EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance

説明

final public EvLoop::timer(
float $after ,
float $repeat ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvTimer

Creates EvTimer watcher object associated with the current event loop instance

パラメータ

All parameters have the same meaning as for EvTimer::__construct()

戻り値

Returns EvTimer object on success

参考

  • EvTimer::__construct() - Constructs an EvTimer watcher object


Performs internal consistency checks(for debugging)

  • ≪ EvLoop::timer
  • EvPeriodic ≫
  • PHP Manual
  • EvLoop
  • Performs internal consistency checks(for debugging)

EvLoop::verify

(PECL ev >= 0.2.0)

EvLoop::verify — Performs internal consistency checks(for debugging)

説明

public EvLoop::verify(): void

Performs internal consistency checks(for debugging libev ) and abort the program if any data structures were found to be corrupted.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Ev::verify() - 内部の整合性をチェックする (デバッグ用)


The EvPeriodic class

(PECL ev >= 0.2.0)

はじめに

Periodic watchers are also timers of a kind, but they are very versatile.

Unlike EvTimer , EvPeriodic watchers are not based on real time(or relative time, the physical time that passes) but on wall clock time(absolute time, calendar or clock). The difference is that wall clock time can run faster or slower than real time, and time jumps are not uncommon(e.g. when adjusting it).

EvPeriodic watcher can be configured to trigger after some specific point in time. For example, if an EvPeriodic watcher is configured to trigger "in 10 seconds" (e.g. EvLoop::now() + 10.0 , i.e. an absolute time, not a delay), and the system clock is reset to January of the previous year , then it will take a year or more to trigger the event (unlike an EvTimer , which would still trigger roughly 10 seconds after starting it as it uses a relative timeout).

As with timers, the callback is guaranteed to be invoked only when the point in time where it is supposed to trigger has passed. If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones with later time-out values (but this is no longer true when a callback calls EvLoop::run() recursively).

クラス概要

class EvPeriodic extends EvWatcher {
/* プロパティ */
public $offset;
public $interval;
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct(
float $offset ,
string $interval ,
callable $reschedule_cb ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)
public again(): void
public at(): float
final public static createStopped(
float $offset ,
float $interval ,
callable $reschedule_cb ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvPeriodic
public set( float $offset , float $interval ): void
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

offset

When repeating, this contains the offset value, otherwise this is the absolute point in time(the offset value passed to EvPeriodic::set() , although libev might modify this value for better numerical stability).

interval

The current interval value. Can be modified any time, but changes only take effect when the periodic timer fires or EvPeriodic::again() is being called.

目次

  • EvPeriodic::again — Simply stops and restarts the periodic watcher again
  • EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
  • EvPeriodic::__construct — Constructs EvPeriodic watcher object
  • EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
  • EvPeriodic::set — Configures the watcher


Simply stops and restarts the periodic watcher again

  • ≪ EvPeriodic
  • EvPeriodic::at ≫
  • PHP Manual
  • EvPeriodic
  • Simply stops and restarts the periodic watcher again

EvPeriodic::again

(PECL ev >= 0.2.0)

EvPeriodic::again — Simply stops and restarts the periodic watcher again

説明

public EvPeriodic::again(): void

Simply stops and restarts the periodic watcher again. This is only useful when attributes are changed.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvTimer::again() - Restarts the timer watcher


Returns the absolute time that this watcher is supposed to trigger next

  • ≪ EvPeriodic::again
  • EvPeriodic::__construct ≫
  • PHP Manual
  • EvPeriodic
  • Returns the absolute time that this watcher is supposed to trigger next

EvPeriodic::at

(PECL ev >= 0.2.0)

EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next

説明

public EvPeriodic::at(): float

When the watcher is active, returns the absolute time that this watcher is supposed to trigger next. This is not the same as the offset argument to EvPeriodic::set() or EvPeriodic::__construct() , but indeed works even in interval mode.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the absolute time this watcher is supposed to trigger next in seconds.


Constructs EvPeriodic watcher object

  • ≪ EvPeriodic::at
  • EvPeriodic::createStopped ≫
  • PHP Manual
  • EvPeriodic
  • Constructs EvPeriodic watcher object

EvPeriodic::__construct

(PECL ev >= 0.2.0)

EvPeriodic::__construct — Constructs EvPeriodic watcher object

説明

public EvPeriodic::__construct(
float $offset ,
string $interval ,
callable $reschedule_cb ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)

Constructs EvPeriodic watcher object and starts it automatically. EvPeriodic::createStopped() method creates stopped periodic watcher.

パラメータ

offset

See Periodic watcher operation modes

interval

See Periodic watcher operation modes

reschedule_cb

Reschedule callback. You can pass null. See Periodic watcher operation modes

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

例

例1 Periodic timer. Use reschedule callback

<?php
// Tick each 10.5 seconds

function reschedule_cb ($watcher, $now) {
return $now + (10.5. - fmod($now, 10.5));
}

$w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
echo time(), PHP_EOL;
});
Ev::run();
?>

例2 Periodic timer. Tick every 10.5 seconds starting at now

<?php
// Tick every 10.5 seconds starting at now
$w = new EvPeriodic(fmod(Ev::now(), 10.5), 10.5, NULL, function ($w, $revents) {
echo time(), PHP_EOL;
});
Ev::run();
?>

例3 Hourly watcher

<?php
$hourly = EvPeriodic(0, 3600, NULL, function () {
echo "once per hour\n";
});
?>

参考

  • Periodic watcher operation modes
  • EvTimer
  • EvPeriodic::createStopped() - Create a stopped EvPeriodic watcher


Create a stopped EvPeriodic watcher

  • ≪ EvPeriodic::__construct
  • EvPeriodic::set ≫
  • PHP Manual
  • EvPeriodic
  • Create a stopped EvPeriodic watcher

EvPeriodic::createStopped

(PECL ev >= 0.2.0)

EvPeriodic::createStopped — Create a stopped EvPeriodic watcher

説明

final public static EvPeriodic::createStopped(
float $offset ,
float $interval ,
callable $reschedule_cb ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvPeriodic

Create EvPeriodic object. Unlike EvPeriodic::__construct() this method doesn't start the watcher automatically.

パラメータ

offset

See Periodic watcher operation modes

interval

See Periodic watcher operation modes

reschedule_cb

Reschedule callback. You can pass null. See Periodic watcher operation modes

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

戻り値

Returns EvPeriodic watcher object on success.

参考

  • EvPeriodic::__construct() - Constructs EvPeriodic watcher object
  • EvTimer::createStopped() - Creates EvTimer stopped watcher object


Configures the watcher

  • ≪ EvPeriodic::createStopped
  • EvPrepare ≫
  • PHP Manual
  • EvPeriodic
  • Configures the watcher

EvPeriodic::set

(PECL ev >= 0.2.0)

EvPeriodic::set — Configures the watcher

説明

public EvPeriodic::set( float $offset , float $interval ): void

(Re-)Configures EvPeriodic watcher

パラメータ

offset

The same meaning as for EvPeriodic::__construct() . See Periodic watcher operation modes

interval

The same meaning as for EvPeriodic::__construct() . See Periodic watcher operation modes

戻り値

値を返しません。


EvPrepare クラス

(PECL ev >= 0.2.0)

はじめに

EvPrepare ウォッチャーと EvCheck ウォッチャーは、 通常はペアで使います。 EvPrepare ウォッチャーはプロセスをブロックする前に起動し、 EvCheck はブロックした後に起動します。

EvLoop::run() あるいはそれに類するメソッドや関数 (現在のイベントループに入るもの) は、EvPrepare ウォッチャーや EvCheck ウォッチャーからは呼べません。 現在のループ以外のループは問題ありません。 その理由は、これらのウォッチャーの中では再帰をチェックする必要がないからです。 つまり、処理の流れは常に EvPrepare -> ブロック -> EvCheck となるので、これらのウォッチャーは常にペアで呼ばれ、ブロッキング呼び出しの前後を囲むことになります。

主な利用目的は他のイベント機構を libev に統合することで、 少し高度な使いかたになります。変数の変更を追跡したり 自前のウォッチャーを実装したり、net-snmp やコルーチンライブラリを統合したりといった、 さまざまな用途で使えます。 また、何らかのデータをキャッシュしてブロッキングの前にフラッシュするなどの用途で使えることもあります。

EvCheck には最高の優先度 (Ev::MAXPRI) を与えることを推奨します。 これで、ポーリングの後は他のあらゆるウォッチャーよりも先に実行されることが保証されます (EvPrepare ウォッチャーの場合は無鐘鋳です)。

また、EvCheck ウォッチャーはイベントをアクティブにしたり送信したりしてはいけません。 libev では対応してはいますが、 他の EvCheck ウォッチャーが仕事をする前に実行される可能性があります。

クラス概要

class EvPrepare extends EvWatcher {
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct( string $callback , string $data = ?, string $priority = ?)
final public static createStopped( callable $callback , mixed $data = null , int $priority = 0 ): EvPrepare
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

目次

  • EvPrepare::__construct — EvPrepare ウォッチャーオブジェクトを作る
  • EvPrepare::createStopped — 停止した EvPrepare ウォッチャーのインスタンスを作る


EvPrepare ウォッチャーオブジェクトを作る

  • ≪ EvPrepare
  • EvPrepare::createStopped ≫
  • PHP Manual
  • EvPrepare
  • EvPrepare ウォッチャーオブジェクトを作る

EvPrepare::__construct

(PECL ev >= 0.2.0)

EvPrepare::__construct — EvPrepare ウォッチャーオブジェクトを作る

説明

public EvPrepare::__construct( string $callback , string $data = ?, string $priority = ?)

EvPrepare ウォッチャーオブジェクトを作り、自動的に開始させます。 停止状態のウォッチャーが必要なときは、 EvPrepare::createStopped() を使いましょう。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

参考

  • EvCheck


停止した EvPrepare ウォッチャーのインスタンスを作る

  • ≪ EvPrepare::__construct
  • EvSignal ≫
  • PHP Manual
  • EvPrepare
  • 停止した EvPrepare ウォッチャーのインスタンスを作る

EvPrepare::createStopped

(PECL ev >= 0.2.0)

EvPrepare::createStopped — 停止した EvPrepare ウォッチャーのインスタンスを作る

説明

final public static EvPrepare::createStopped( callable $callback , mixed $data = null , int $priority = 0 ): EvPrepare

停止した EvPrepare ウォッチャーのインスタンスを作ります。 EvPrepare::__construct() とは違い、 このメソッドはウォッチャーを自動的に開始させません。

パラメータ

callback

ウォッチャーのコールバック を参照ください。

data

このウォッチャーに関連づけるカスタムデータ。

priority

ウォッチャーの優先度。

戻り値

成功した場合に EvPrepare オブジェクトを返します。

参考

  • EvPrepare::__construct() - EvPrepare ウォッチャーオブジェクトを作る
  • EvWatcher::start() - Starts the watcher


The EvSignal class

(PECL ev >= 0.2.0)

はじめに

EvSignal watchers will trigger an event when the process receives a specific signal one or more times. Even though signals are very asynchronous, libev will try its best to deliver signals synchronously, i.e. as part of the normal event processing, like any other event.

There is no limit for the number of watchers for the same signal, but only within the same loop, i.e. one can watch for SIGINT in the default loop and for SIGIO in another loop, but it is not allowed to watch for SIGINT in both the default loop and another loop at the same time. At the moment, SIGCHLD is permanently tied to the default loop.

If possible and supported, libev will install its handlers with SA_RESTART (or equivalent) behaviour enabled, so system calls should not be unduly interrupted. In case of a problem with system calls getting interrupted by signals, all the signals can be blocked in an EvCheck watcher and unblocked in a EvPrepare watcher.

クラス概要

class EvSignal extends EvWatcher {
/* プロパティ */
public $signum;
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct(
int $signum ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)
final public static createStopped(
int $signum ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvSignal
public set( int $signum ): void
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

signum

Signal number. See the constants exported by pcntl extension. See also signal(7) man page.

目次

  • EvSignal::__construct — Constructs EvSignal watcher object
  • EvSignal::createStopped — Create stopped EvSignal watcher object
  • EvSignal::set — Configures the watcher


Constructs EvSignal watcher object

  • ≪ EvSignal
  • EvSignal::createStopped ≫
  • PHP Manual
  • EvSignal
  • Constructs EvSignal watcher object

EvSignal::__construct

(PECL ev >= 0.2.0)

EvSignal::__construct — Constructs EvSignal watcher object

説明

public EvSignal::__construct(
int $signum ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)

Constructs EvSignal watcher object and starts it automatically. For a stopped periodic watcher consider using EvSignal::createStopped() method.

パラメータ

signum

Signal number. See constants exported by pcntl extension. See also signal(7) man page.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

例

例1 Handle SIGTERM signal

<?php
$w = new EvSignal(SIGTERM, function ($watcher) {
echo "SIGTERM received\n";
$watcher->stop();
});

Ev::run();
?>

参考

  • EvSignal::createStopped() - Create stopped EvSignal watcher object


Create stopped EvSignal watcher object

  • ≪ EvSignal::__construct
  • EvSignal::set ≫
  • PHP Manual
  • EvSignal
  • Create stopped EvSignal watcher object

EvSignal::createStopped

(PECL ev >= 0.2.0)

EvSignal::createStopped — Create stopped EvSignal watcher object

説明

final public static EvSignal::createStopped(
int $signum ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvSignal

Create stopped EvSignal watcher object. Unlike EvSignal::__construct() , this method does't start the watcher automatically.

パラメータ

signum

Signal number. See constants exported by pcntl extension. See also signal(7) man page.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

戻り値

Returns EvSignal object on success.

参考

  • EvWatcher::start() - Starts the watcher
  • EvSignal::__construct() - Constructs EvSignal watcher object


Configures the watcher

  • ≪ EvSignal::createStopped
  • EvStat ≫
  • PHP Manual
  • EvSignal
  • Configures the watcher

EvSignal::set

(PECL ev >= 0.2.0)

EvSignal::set — Configures the watcher

説明

public EvSignal::set( int $signum ): void

Configures the watcher.

パラメータ

signum

Signal number. The same as for EvSignal::__construct()

戻り値

値を返しません。


The EvStat class

(PECL ev >= 0.2.0)

はじめに

EvStat monitors a file system path for attribute changes. It calls stat() on that path in regular intervals (or when the OS signals it changed) and sees if it changed compared to the last time, invoking the callback if it did.

The path does not need to exist: changing from "path exists" to "path does not exist" is a status change like any other. The condition "path does not exist" is signified by the 'nlink' item being 0(returned by EvStat::attr() method).

The path must not end in a slash or contain special components such as '.' or .. . The path should be absolute: if it is relative and the working directory changes, then the behaviour is undefined.

Since there is no portable change notification interface available, the portable implementation simply calls stat() regularly on the path to see if it changed somehow. For this case a recommended polling interval can be specified. If one specifies a polling interval of 0.0 (highly recommended) then a suitable, unspecified default value will be used(which could be expected to be around 5 seconds, although this might change dynamically). libev will also impose a minimum interval which is currently around 0.1 , but that's usually overkill.

This watcher type is not meant for massive numbers of EvStat watchers, as even with OS-supported change notifications, this can be resource-intensive.

クラス概要

class EvStat extends EvWatcher {
/* プロパティ */
public $path;
public $interval;
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct(
string $path ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)
public attr(): array
final public static createStopped(
string $path ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): void
public prev(): void
public set( string $path , float $interval ): void
public stat(): bool
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

interval

Readonly . Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

path

Readonly . The path to wait for status changes on.

目次

  • EvStat::attr — Returns the values most recently detected by Ev
  • EvStat::__construct — Constructs EvStat watcher object
  • EvStat::createStopped — Create a stopped EvStat watcher object
  • EvStat::prev — Returns the previous set of values returned by EvStat::attr
  • EvStat::set — Configures the watcher
  • EvStat::stat — Initiates the stat call


Returns the values most recently detected by Ev

  • ≪ EvStat
  • EvStat::__construct ≫
  • PHP Manual
  • EvStat
  • Returns the values most recently detected by Ev

EvStat::attr

(PECL ev >= 0.2.0)

EvStat::attr — Returns the values most recently detected by Ev

説明

public EvStat::attr(): array

Returns array of the values most recently detected by Ev

パラメータ

この関数にはパラメータはありません。

戻り値

Returns array with the values most recently detect by Ev(without actual stat 'ing):

List for item keys of the array returned by EvStat::attr()
Key | Description
'dev' | ID of device containing file
'ino' | inode number
'mode' | protection
'nlink' | number of hard links
'uid' | user ID of owner
'size' | total size, in bytes
'gid' | group ID of owner
'rdev' | device ID (if special file)
'blksize' | blocksize for file system I/O
'blocks' | number of 512B blocks allocated
'atime' | time of last access
'ctime' | time of last status change
'mtime' | time of last modification

See stat(2) man page for details.

例

例1 Monitor changes of /var/log/messages

<?php
// Use 10 second update interval.
$w = new EvStat("/var/log/messages", 8, function ($w) {
echo "/var/log/messages changed\n";

$attr = $w->attr();

if ($attr['nlink']) {
printf("Current size: %ld\n", $attr['size']);
printf("Current atime: %ld\n", $attr['atime']);
printf("Current mtime: %ld\n", $attr['mtime']);
} else {
fprintf(STDERR, "`messages` file is not there!");
$w->stop();
}
});

Ev::run();
?>

参考

  • EvStat::prev() - Returns the previous set of values returned by EvStat::attr
  • EvStat::stat() - Initiates the stat call


Constructs EvStat watcher object

  • ≪ EvStat::attr
  • EvStat::createStopped ≫
  • PHP Manual
  • EvStat
  • Constructs EvStat watcher object

EvStat::__construct

(PECL ev >= 0.2.0)

EvStat::__construct — Constructs EvStat watcher object

説明

public EvStat::__construct(
string $path ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)

Constructs EvStat watcher object and starts the watcher automatically.

パラメータ

path

The path to wait for status changes on.

interval

Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

例

例1 Monitor changes of /var/log/messages

<?php

// Use 10 second update interval.
$w = new EvStat("/var/log/messages", 10, function ($w) {
echo "/var/log/messages changed\n";

$attr = $w->attr();

if ($attr['nlink']) {
printf("Current size: %ld\n", $attr['size']);
printf("Current atime: %ld\n", $attr['atime']);
printf("Current mtime: %ld\n", $attr['mtime']);
} else {
fprintf(STDERR, "`messages` file is not there!");
$w->stop();
}
});

?>


Create a stopped EvStat watcher object

  • ≪ EvStat::__construct
  • EvStat::prev ≫
  • PHP Manual
  • EvStat
  • Create a stopped EvStat watcher object

EvStat::createStopped

(PECL ev >= 0.2.0)

EvStat::createStopped — Create a stopped EvStat watcher object

説明

final public static EvStat::createStopped(
string $path ,
float $interval ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): void

Creates EvStat watcher object, but doesn't start it automatically(unlike EvStat::__construct() ).

パラメータ

path

The path to wait for status changes on.

interval

Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

戻り値

Returns a stopped EvStat watcher object on success.

参考

  • EvStat::__construct() - Constructs EvStat watcher object
  • EvWatcher::start() - Starts the watcher


Returns the previous set of values returned by EvStat::attr

  • ≪ EvStat::createStopped
  • EvStat::set ≫
  • PHP Manual
  • EvStat
  • Returns the previous set of values returned by EvStat::attr

EvStat::prev

(PECL ev >= 0.2.0)

EvStat::prev — Returns the previous set of values returned by EvStat::attr

説明

public EvStat::prev(): void

Just like EvStat::attr() , but returns the previous set of values.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array with the same structure as the array returned by EvStat::attr() . The array contains previously detected values.

参考

  • EvStat::attr() - Returns the values most recently detected by Ev
  • EvStat::stat() - Initiates the stat call


Configures the watcher

  • ≪ EvStat::prev
  • EvStat::stat ≫
  • PHP Manual
  • EvStat
  • Configures the watcher

EvStat::set

(PECL ev >= 0.2.0)

EvStat::set — Configures the watcher

説明

public EvStat::set( string $path , float $interval ): void

Configures the watcher.

パラメータ

path

The path to wait for status changes on.

interval

Hint on how quickly a change is expected to be detected and should normally be specified as 0.0 to let libev choose a suitable value.

戻り値

値を返しません。


Initiates the stat call

  • ≪ EvStat::set
  • EvTimer ≫
  • PHP Manual
  • EvStat
  • Initiates the stat call

EvStat::stat

(PECL ev >= 0.2.0)

EvStat::stat — Initiates the stat call

説明

public EvStat::stat(): bool

Initiates the stat call(updates internal cache). It stats(using lstat ) the path specified in the watcher and sets to the values found.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if path exists. Otherwise false.

参考

  • EvStat::attr() - Returns the values most recently detected by Ev
  • EvStat::prev() - Returns the previous set of values returned by EvStat::attr


The EvTimer class

(PECL ev >= 0.2.0)

はじめに

EvTimer watchers are simple relative timers that generate an event after a given time, and optionally repeating in regular intervals after that.

The timers are based on real time, that is, if one registers an event that times out after an hour and resets the system clock to January last year , it will still time out after(roughly) one hour. "Roughly" because detecting time jumps is hard, and some inaccuracies are unavoidable.

The callback is guaranteed to be invoked only after its timeout has passed (not at, so on systems with very low-resolution clocks this might introduce a small delay). If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones of the same priority with later time-out values (but this is no longer true when a callback calls EvLoop::run() recursively).

The timer itself will do a best-effort at avoiding drift, that is, if a timer is configured to trigger every 10 seconds, then it will normally trigger at exactly 10 second intervals. If, however, the script cannot keep up with the timer because it takes longer than those 10 seconds to do) the timer will not fire more than once per event loop iteration.

クラス概要

class EvTimer extends EvWatcher {
/* プロパティ */
public $repeat;
public $remaining;
/* 継承したプロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
public __construct(
float $after ,
float $repeat ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)
public again(): void
final public static createStopped(
float $after ,
float $repeat ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvTimer
public set( float $after , float $repeat ): void
/* 継承したメソッド */
public EvWatcher::clear(): int
public EvWatcher::feed( int $revents ): void
public EvWatcher::getLoop(): EvLoop
public EvWatcher::invoke( int $revents ): void
public EvWatcher::keepalive( bool $value = ?): bool
public EvWatcher::setCallback( callable $callback ): void
public EvWatcher::start(): void
public EvWatcher::stop(): void
}

プロパティ

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

remaining

Returns the remaining time until a timer fires. If the timer is active, then this time is relative to the current event loop time, otherwise it's the timeout value currently configured.

That is, after instanciating an EvTimer with an after value of 5.0 and repeat value of 7.0 , remaining returns 5.0 . When the timer is started and one second passes, remaining will return 4.0 . When the timer expires and is restarted, it will return roughly 7.0 (likely slightly less as callback invocation takes some time too), and so on.

目次

  • EvTimer::again — Restarts the timer watcher
  • EvTimer::__construct — Constructs an EvTimer watcher object
  • EvTimer::createStopped — Creates EvTimer stopped watcher object
  • EvTimer::set — Configures the watcher


Restarts the timer watcher

  • ≪ EvTimer
  • EvTimer::__construct ≫
  • PHP Manual
  • EvTimer
  • Restarts the timer watcher

EvTimer::again

(PECL ev >= 0.2.0)

EvTimer::again — Restarts the timer watcher

説明

public EvTimer::again(): void

This will act as if the timer timed out and restart it again if it is repeating. The exact semantics are:

  1. if the timer is pending, its pending status is cleared.

  2. if the timer is started but non-repeating, stop it (as if it timed out).

  3. if the timer is repeating, either start it if necessary (with the repeat value), or reset the running timer to the repeat value.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvWatcher::stop() - Stops the watcher


Constructs an EvTimer watcher object

  • ≪ EvTimer::again
  • EvTimer::createStopped ≫
  • PHP Manual
  • EvTimer
  • Constructs an EvTimer watcher object

EvTimer::__construct

(PECL ev >= 0.2.0)

EvTimer::__construct — Constructs an EvTimer watcher object

説明

public EvTimer::__construct(
float $after ,
float $repeat ,
callable $callback ,
mixed $data = null ,
int $priority = 0
)

Constructs an EvTimer watcher object.

パラメータ

after

Configures the timer to trigger after after seconds.

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

例

例1 Simple timers

<?php
// Create and start timer firing after 2 seconds
$w1 = new EvTimer(2, 0, function () {
echo "2 seconds elapsed\n";
});

// Create and launch timer firing after 2 seconds repeating each second
// until we manually stop it
$w2 = new EvTimer(2, 1, function ($w) {
echo "is called every second, is launched after 2 seconds\n";
echo "iteration = ", Ev::iteration(), PHP_EOL;

// Stop the watcher after 5 iterations
Ev::iteration() == 5 and $w->stop();
// Stop the watcher if further calls cause more than 10 iterations
Ev::iteration() >= 10 and $w->stop();
});

// Create stopped timer. It will be inactive until we start it ourselves
$w_stopped = EvTimer::createStopped(10, 5, function($w) {
echo "Callback of a timer created as stopped\n";

// Stop the watcher after 2 iterations
Ev::iteration() >= 2 and $w->stop();
});

// Loop until Ev::stop() is called or all of watchers stop
Ev::run();

// Start and look if it works
$w_stopped->start();
echo "Run single iteration\n";
Ev::run(Ev::RUN_ONCE);

echo "Restart the second watcher and try to handle the same events, but don't block\n";
$w2->again();
Ev::run(Ev::RUN_NOWAIT);

$w = new EvTimer(10, 0, function() {});
echo "Running a blocking loop\n";
Ev::run();
echo "END\n";
?>

上の例の出力は、 たとえば以下のようになります。

2 seconds elapsed
is called every second, is launched after 2 seconds
iteration = 1
is called every second, is launched after 2 seconds
iteration = 2
is called every second, is launched after 2 seconds
iteration = 3
is called every second, is launched after 2 seconds
iteration = 4
is called every second, is launched after 2 seconds
iteration = 5
Run single iteration
Callback of a timer created as stopped
Restart the second watcher and try to handle the same events, but don't block
Running a blocking loop
is called every second, is launched after 2 seconds
iteration = 8
is called every second, is launched after 2 seconds
iteration = 9
is called every second, is launched after 2 seconds
iteration = 10
END

参考

  • EvTimer::createStopped() - Creates EvTimer stopped watcher object
  • EvPeriodic
  • » ev_timer - relative and optionally repeating timeouts
  • » Be smart about timeouts


Creates EvTimer stopped watcher object

  • ≪ EvTimer::__construct
  • EvTimer::set ≫
  • PHP Manual
  • EvTimer
  • Creates EvTimer stopped watcher object

EvTimer::createStopped

(PECL ev >= 0.2.0)

EvTimer::createStopped — Creates EvTimer stopped watcher object

説明

final public static EvTimer::createStopped(
float $after ,
float $repeat ,
callable $callback ,
mixed $data = null ,
int $priority = 0
): EvTimer

Creates EvTimer stopped watcher object. Unlike EvTimer::__construct() , this method doesn't start the watcher automatically.

パラメータ

after

Configures the timer to trigger after after seconds.

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

callback

See Watcher callbacks .

data

Custom data associated with the watcher.

priority

Watcher priority

戻り値

Returns EvTimer watcher object on success.

例

例1 Monotor changes of /var/log/messages. Avoid missing updates by means of one second delay

<?php
$timer = EvTimer::createStopped(0., 1.02, function ($w) {
$w->stop();

$stat = $w->data;

// 1 second after the most recent change of the file
printf("Current size: %ld\n", $stat->attr()['size']);
});

$stat = new EvStat("/var/log/messages", 0., function () use ($timer) {
// Reset timer watcher
$timer->again();
});

$timer->data = $stat;

Ev::run();
?>

参考

  • EvTimer::__construct() - Constructs an EvTimer watcher object
  • EvPeriodic


Configures the watcher

  • ≪ EvTimer::createStopped
  • EvWatcher ≫
  • PHP Manual
  • EvTimer
  • Configures the watcher

EvTimer::set

(PECL ev >= 0.2.0)

EvTimer::set — Configures the watcher

説明

public EvTimer::set( float $after , float $repeat ): void

Configures the watcher

パラメータ

after

Configures the timer to trigger after after seconds.

repeat

If repeat is 0.0 , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

戻り値

値を返しません。


The EvWatcher class

(PECL ev >= 0.2.0)

はじめに

EvWatcher is a base class for all watchers( EvCheck , EvChild etc.). Since EvWatcher 's constructor is abstract , one can't(and don't need to) create EvWatcher objects directly.

クラス概要

abstract class EvWatcher {
/* プロパティ */
public $is_active;
public $data;
public $is_pending;
public $priority;
/* メソッド */
abstract public __construct()
public clear(): int
public feed( int $revents ): void
public getLoop(): EvLoop
public invoke( int $revents ): void
public keepalive( bool $value = ?): bool
public setCallback( callable $callback ): void
public start(): void
public stop(): void
}

プロパティ

is_active

Readonly . true if the watcher is active. false otherwise.

data

User custom data associated with the watcher

is_pending

Readonly .true if the watcher is pending, i.e. it has outstanding events, but its callback has not yet been invoked. false otherwise. As long, as a watcher is pending(but not active), one must not change its priority.

priority

int between Ev::MINPRI and Ev::MAXPRI . Pending watchers with higher priority will be invoked before watchers with lower priority, but priority will not keep watchers from being executed(except for EvIdle watchers). EvIdle watchers provide functionality to suppress invocation when higher priority events are pending.

目次

  • EvWatcher::clear — Clear watcher pending status
  • EvWatcher::__construct — Abstract constructor of a watcher object
  • EvWatcher::feed — Feeds the given revents set into the event loop
  • EvWatcher::getLoop — Returns the loop responsible for the watcher
  • EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
  • EvWatcher::keepalive — Configures whether to keep the loop from returning
  • EvWatcher::setCallback — Sets new callback for the watcher
  • EvWatcher::start — Starts the watcher
  • EvWatcher::stop — Stops the watcher


Clear watcher pending status

  • ≪ EvWatcher
  • EvWatcher::__construct ≫
  • PHP Manual
  • EvWatcher
  • Clear watcher pending status

EvWatcher::clear

(PECL ev >= 0.2.0)

EvWatcher::clear — Clear watcher pending status

説明

public EvWatcher::clear(): int

If the watcher is pending, this method clears its pending status and returns its revents bitset(as if its callback was invoked). If the watcher isn't pending it does nothing and returns 0 .

Sometimes it can be useful to "poll" a watcher instead of waiting for its callback to be invoked, which can be accomplished with this function.

パラメータ

この関数にはパラメータはありません。

戻り値

In case if the watcher is pending, returns revents bitset as if the watcher callback had been invoked. Otherwise returns 0 .


Abstract constructor of a watcher object

  • ≪ EvWatcher::clear
  • EvWatcher::feed ≫
  • PHP Manual
  • EvWatcher
  • Abstract constructor of a watcher object

EvWatcher::__construct

(PECL ev >= 0.2.0)

EvWatcher::__construct — Abstract constructor of a watcher object

説明

abstract public EvWatcher::__construct()

EvWatcher::__construct() is an abstract constructor of a watcher object implemented in the derived classes.

パラメータ

この関数にはパラメータはありません。


Feeds the given revents set into the event loop

  • ≪ EvWatcher::__construct
  • EvWatcher::getLoop ≫
  • PHP Manual
  • EvWatcher
  • Feeds the given revents set into the event loop

EvWatcher::feed

(PECL ev >= 0.2.0)

EvWatcher::feed — Feeds the given revents set into the event loop

説明

public EvWatcher::feed( int $revents ): void

Feeds the given revents set into the event loop, as if the specified event had happened for the watcher.

パラメータ

revents

Bit mask of watcher received events .

戻り値

値を返しません。


Returns the loop responsible for the watcher

  • ≪ EvWatcher::feed
  • EvWatcher::invoke ≫
  • PHP Manual
  • EvWatcher
  • Returns the loop responsible for the watcher

EvWatcher::getLoop

(PECL ev >= 0.2.0)

EvWatcher::getLoop — Returns the loop responsible for the watcher

説明

public EvWatcher::getLoop(): EvLoop

Returns the loop responsible for the watcher

パラメータ

この関数にはパラメータはありません。

戻り値

Returns EvLoop event loop object responsible for the watcher.


Invokes the watcher callback with the given received events bit mask

  • ≪ EvWatcher::getLoop
  • EvWatcher::keepalive ≫
  • PHP Manual
  • EvWatcher
  • Invokes the watcher callback with the given received events bit mask

EvWatcher::invoke

(PECL ev >= 0.2.0)

EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask

説明

public EvWatcher::invoke( int $revents ): void

Invokes the watcher callback with the given received events bit mask.

パラメータ

revents

Bit mask of watcher received events .

戻り値

値を返しません。


Configures whether to keep the loop from returning

  • ≪ EvWatcher::invoke
  • EvWatcher::setCallback ≫
  • PHP Manual
  • EvWatcher
  • Configures whether to keep the loop from returning

EvWatcher::keepalive

(PECL ev >= 0.2.0)

EvWatcher::keepalive — Configures whether to keep the loop from returning

説明

public EvWatcher::keepalive( bool $value = ?): bool

Configures whether to keep the loop from returning. With keepalive value set to false the watcher won't keep Ev::run() / EvLoop::run() from returning even though the watcher is active.

Watchers have keepalive value true by default.

Clearing keepalive status is useful when returning from Ev::run() / EvLoop::run() just because of the watcher is undesirable. It could be a long running UDP socket watcher or so.

パラメータ

value

With keepalive value set to false the watcher won't keep Ev::run() / EvLoop::run() from returning even though the watcher is active.

戻り値

Returns the previous state.

例

例1 Register an I/O watcher for some UDP socket but do not keep the event loop from running just because of that watcher.

<?php
$udp_socket = ...
$udp_watcher = new EvIo($udp_socket, Ev::READ, function () { /* ... */ });
$udp_watcher->keepalive(FALSE);
?>


Sets new callback for the watcher

  • ≪ EvWatcher::keepalive
  • EvWatcher::start ≫
  • PHP Manual
  • EvWatcher
  • Sets new callback for the watcher

EvWatcher::setCallback

(PECL ev >= 0.2.0)

EvWatcher::setCallback — Sets new callback for the watcher

説明

public EvWatcher::setCallback( callable $callback ): void

Sets new callback for the watcher

パラメータ

callback

See Watcher callbacks .

戻り値

値を返しません。


Starts the watcher

  • ≪ EvWatcher::setCallback
  • EvWatcher::stop ≫
  • PHP Manual
  • EvWatcher
  • Starts the watcher

EvWatcher::start

(PECL ev >= 0.2.0)

EvWatcher::start — Starts the watcher

説明

public EvWatcher::start(): void

Marks the watcher as active. Note that only active watchers will receive events.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvWatcher::stop() - Stops the watcher


Stops the watcher

  • ≪ EvWatcher::start
  • Expect ≫
  • PHP Manual
  • EvWatcher
  • Stops the watcher

EvWatcher::stop

(PECL ev >= 0.2.0)

EvWatcher::stop — Stops the watcher

説明

public EvWatcher::stop(): void

Marks the watcher as inactive. Note that only active watchers will receive events.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EvWatcher::start() - Starts the watcher


Expect

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • Expect の使用例
  • Expect 関数
    • expect_expectl — プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける
    • expect_popen — Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする


はじめに

この拡張モジュールは、PTY を経由したプロセス同士の対話機能を提供します。 ファイルシステム関数 で expect:// ラッパー を利用すれば、シンプルでより直感的なインターフェイスが利用できるでしょう。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Expect
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

このモジュールは » expect ライブラリの 関数を使用します。libexpect バージョン >= 5.43.0 が必要です。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/expect.

これらの関数を使用するには、--with-expect[=DIR] オプションを使用して expect サポートつきで PHP をコンパイルする必要があります。

Windows ユーザーは、これらの関数を使用するためには php.ini の中で php_expect.dll を有効にします。 この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


実行時設定

php.ini の設定により動作が変化します。

expect 拡張モジュールを設定するために、 設定ファイル php.ini に 設定項目が用意されています。

Expect 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
expect.timeout | "10" | INI_ALL |
expect.loguser | "1" | INI_ALL |
expect.logfile | "" | INI_ALL |
expect.match_max | "" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

expect.timeout int

データを待ち受ける際のタイムアウト時間です。 expect_expectl() 関数で使用されます。

"-1" を指定すると、タイムアウトを発生させないようにします。

注意:

"0" を指定すると、expect_expectl() 関数は 結果を直ちに返します。

expect.loguser bool

expect が、子プロセスの出力を標準出力に送るかどうかを指定します。 典型的な対話型プログラムは入力した内容を表示するので、これを使用すれば 対話の両方の側を表示することができます。

expect.logfile string

子プロセスの出力内容が書き込まれるファイルの名前。もしファイルが 存在しない場合は新しく作成されます。

注意:

この設置が空欄でなかった場合、 expect.loguser の設定内容に かかわらず出力が書き込まれます。

expect.match_max int

パターン内のアスタリスクとのマッチに使うバッファのデフォルトサイズ (2000 バイト) を変更します。


リソース型

expect_popen() は、オープンした PTY ストリームを返します。これを expect_expectl() で使用します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

EXP_GLOB (int)
パターンが、glob 形式の文字列パターンであることを示します。
EXP_EXACT (int)
パターンが、単なる文字列であることを示します。
EXP_REGEXP (int)
パターンが、正規表現形式の文字列パターンであることを示します。
EXP_EOF (int)
EOF に到達した際に expect_expectl() が返す値です。
EXP_TIMEOUT (int)
expect.timeout で指定した秒数を こえた際に expect_expectl() が返す値です。
EXP_FULLBUFFER (int)
一致するパターンがなかった際に expect_expectl() が返す値です。


  • ≪ 定義済み定数
  • Expect の使用例 ≫
  • PHP Manual
  • Expect
  • 例

例

目次

  • Expect の使用例


Expect の使用例

例1 Expect の使用例

この例ではリモートホストに SSH 経由で接続し、接続先の稼働時間を表示します。

<?php
ini_set("expect.loguser", "Off");

$stream = fopen("expect://ssh root@remotehost uptime", "r");

$cases = array (
array (0 => "password:", 1 => PASSWORD)
);

switch (expect_expectl ($stream, $cases)) {
case PASSWORD:
fwrite ($stream, "password\n");
break;

default:
die ("リモートホストへの接続時にエラーが発生しました!\n");
}

while ($line = fgets($stream)) {
print $line;
}
fclose ($stream);
?>

次の例は、リモートホストに接続して インストールされている OS が 32 ビットか 64 ビットかを確認し、 それぞれのパッケージのアップデートを実行します。

例2 もうひとつの Expect の使用例

<?php
ini_set("expect.timeout", -1);
ini_set("expect.loguser", "Off");

$stream = expect_popen("ssh root@remotehost");

while (true) {
switch (expect_expectl ($stream, array (
array ("password:", PASSWORD), // SSH がパスワードを問い合わせます
array ("yes/no)?", YESNO), // SSH がホストエントリを保存するかどうかを問い合わせます
array ("~$ ", SHELL, EXP_EXACT), // シェルにたどり着きました!
))) {
case PASSWORD:
fwrite ($stream, "secret\n");
break;

case YESNO:
fwrite ($stream, "yes\n");
break;

case SHELL:
fwrite ($stream, "uname -a\n");
while (true) {
switch (expect_expectl ($stream, array (
array ("~$ ", SHELL, EXP_EXACT), // シェルにたどり着きました!
array ("^Linux.*$", UNAME, EXP_REGEXP), // uname -a の出力
), $match)) {
case UNAME:
$uname .= $match[0];
break;

case SHELL:
// アップデートの実行
if (strstr ($uname, "x86_64")) {
fwrite ($stream, "rpm -Uhv http://mirrorsite/somepath/some_64bit.rpm\n");
} else {
fwrite ($stream, "rpm -Uhv http://mirrorsite/somepath/some_32bit.rpm\n");
}
fwrite ($stream, "exit\n");
break 2;

case EXP_TIMEOUT:
case EXP_EOF:
break 2;

default:
die ("エラーが発生しました!\n");
}
}
break 2;

case EXP_TIMEOUT:
case EXP_EOF:
break 2;

default:
die ("エラーが発生しました!\n");
}
}

fclose ($stream);
?>


Expect 関数

目次

  • expect_expectl — プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける
  • expect_popen — Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする


プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける

  • ≪ Expect 関数
  • expect_popen ≫
  • PHP Manual
  • Expect 関数
  • プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける

expect_expectl

(PECL expect >= 0.1.0)

expect_expectl — プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける

説明

expect_expectl(resource $expect, array $cases, array &$match = ?): int

プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続けます。

match を指定すると、検索結果がそこに保存されます。 一致した文字列が match[0] に保存され、 元のパターンの中の (括弧で囲まれた) 部分に一致する文字列が match[1]、match[2]、 と順に、最大 match[9] まで (libexpect の制限です) 保存されます。

パラメータ

expect

事前に expect_popen() でオープンした Expect ストリーム。

cases

expect case の配列。個々の expect case は数値添字の配列で、 以下のような形式となります。

Expect Case の配列
添字 | 値の型 | 説明 | 必須かどうか | デフォルト値
0 | string | ストリームからの出力との比較対象となるパターン。 | yes
1 | mixed | パターンに一致した場合にこの関数が返す値。 | yes
2 | integer | パターンの形式。 EXP_GLOB、 EXP_EXACT あるいは EXP_REGEXP のいずれかひとつです。 | no | EXP_GLOB

戻り値

一致したパターンに関連付けられた値を返します。

この関数の実行に失敗した場合は、 EXP_EOF、 EXP_TIMEOUT あるいは EXP_FULLBUFFER を返します。

変更履歴

バージョン | 説明
PECL expect 0.2.1 | バージョン 0.2.1 より前では、match パラメータに返されるのはマッチした文字列であり、 部分文字列の配列ではありませんでした。

例

例1 expect_expectl() の例

<?php
// ファイルをリモートホストにコピーします
ini_set("expect.timeout", 30);

$stream = fopen("expect://scp user@remotehost:/var/log/messages /home/user/messages.txt", "r");

$cases = array(
// array(パターン, パターンに一致した場合にこの関数が返す値)
array("password:", "asked for password"),
array("yes/no)?", "asked for yes/no")
);

while (true) {
switch (expect_expectl($stream, $cases)) {
case "asked for password":
fwrite($stream, "my password\n");
break;
case "asked for yes/no":
fwrite($stream, "yes\n");
break;
case EXP_TIMEOUT:
case EXP_EOF:
break 2; // switch 文だけではなく while ループも抜けます
default:
die("エラーが発生しました!");
}
}

fclose($stream);
?>
?>

参考

  • expect_popen() - Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする


Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

  • ≪ expect_expectl
  • PCNTL ≫
  • PHP Manual
  • Expect 関数
  • Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

expect_popen

(PECL expect >= 0.1.0)

expect_popen — Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする

説明

expect_popen(string $command): resource

Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームを オープンします。

パラメータ

command

実行するコマンド。

戻り値

プロセスの標準入力・標準出力・標準エラー出力への PTY ストリームを返します。

失敗した場合は、この関数は false を返します。

例

例1 expect_popen() の例

<?php
// PHP.net の CVS リポジトリにログインします
$stream = expect_popen ("cvs -d :pserver:anonymous@cvs.php.net:/repository login");
sleep (3);
fwrite ($stream, "phpfi\n");
fclose ($stream);
?>

参考

  • popen() - プロセスへのファイルポインタをオープンする


プロセス制御

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
  • 例
    • 基本的な使用法
  • PCNTL 関数
    • pcntl_alarm — シグナルを送信するアラームを設定する
    • pcntl_async_signals — 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す
    • pcntl_errno — pcntl_get_last_error のエイリアス
    • pcntl_exec — 現在のプロセス空間で指定したプログラムを実行する
    • pcntl_fork — 現在実行中のプロセスをフォークする
    • pcntl_get_last_error — 直近の pcntl 関数が失敗したときのエラー番号を取得する
    • pcntl_getpriority — プロセスの優先度を取得する
    • pcntl_rfork — プロセスのリソースを管理する
    • pcntl_setpriority — プロセスの優先度を変更する
    • pcntl_signal — シグナルハンドラを設定する
    • pcntl_signal_dispatch — ペンディングシグナル用のハンドラをコールする
    • pcntl_signal_get_handler — 指定されたシグナルの現在のハンドラを取得する
    • pcntl_sigprocmask — ブロックされたシグナルを設定あるいは取得する
    • pcntl_sigtimedwait — タイムアウトつきでシグナルを待つ
    • pcntl_sigwaitinfo — シグナルを待つ
    • pcntl_strerror — 指定した errno に対応するシステムのエラーメッセージを取得する
    • pcntl_unshare — プロセスの実行コンテキストの一部を切り離す
    • pcntl_wait — 待つかフォークした子プロセスのステータスを返す
    • pcntl_waitpid — 待つかフォークした子プロセスのステータスを返す
    • pcntl_wexitstatus — 終了した子プロセスのリターンコードを返す
    • pcntl_wifexited — ステータスコードが正常終了を表しているかどうかを調べる
    • pcntl_wifsignaled — ステータスコードがシグナルによる終了を表しているかどうかを調べる
    • pcntl_wifstopped — 子プロセスが現在停止しているかどうかを調べる
    • pcntl_wstopsig — 子プロセスを停止させたシグナルを返す
    • pcntl_wtermsig — 子プロセスを終了させたシグナルを返す


はじめに

PHP がサポートするプロセス制御関数は、Unix 形式のプロセス生成、 プロセス実行、シグナル処理、プロセス終了機能を実装しています。 プロセス制御は Web サーバー環境で有効にするべきではなく、プロセス 制御関数のどれかが Web サーバー環境で使用された場合には、予期しない結果を 生じる可能性があります。

この文書は、プロセス制御関数の一般的な使用法を説明しようとするものです。 Unix のプロセス制御に関する詳細な情報については、fork(2), waitpid(2) および signal(2) のようなシステムのドキュメントや、 W. Richard Stevens による Advanced Programming in the UNIX Environment (Addison-Wesley) のような優れた参考書を読まれることを推奨します。

現在 PCNTL はシグナルハンドルコールバックの仕組みとして ticks を 使用しており、これは以前の仕組みよりずっと高速です。この変更は "user ticks" を使用するのと同じことです。declare() を使用して、プログラム中でコールバックの発生を許可する場所を指定する 必要があります。これにより、非同期のイベントを処理する際の オーバーヘッドを最小限に抑えることが可能となります。以前は、pcntl を 有効にして PHP をコンパイルすると、pcntl の使用の有無にかかわらず 常にこのオーバーヘッドの被害を被っていたのです。

注意: この拡張モジュールは Windows 環境では利用できません。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • PCNTL
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

PHPがサポートするプロセス制御機能は、デフォルトでは有効となってい ません。プロセス制御機能を有効にするには、 configure のオプションに --enable-pcntl を付け、CGI 版あるいは CLI 版の PHP をコンパイルする必要があります。

注意:

現在、このモジュールは非 Unix 環境(Windows)では動作しません。


定義済み定数

以下のシグナルのリストがプロセス制御関数でサポートされています。 これらのシグナルのデフォルト動作の詳細については、 signal(7) のマニュアルを参照ください。

プロセス制御関連の定数
WNOHANG (int)
WUNTRACED (int)
WCONTINUED (int)
SIG_* 定数
SIG_IGN (int)
SIG_DFL (int)
SIG_ERR (int)
SIGHUP (int)
SIGINFO (int)
SIGINT (int)
SIGQUIT (int)
SIGILL (int)
SIGTRAP (int)
SIGABRT (int)
SIGIOT (int)
SIGBUS (int)
SIGFPE (int)
SIGKILL (int)
SIGUSR1 (int)
SIGSEGV (int)
SIGUSR2 (int)
SIGPIPE (int)
SIGALRM (int)
SIGTERM (int)
SIGSTKFLT (int)
SIGCLD (int)
SIGCHLD (int)
SIGCONT (int)
SIGSTOP (int)
SIGTSTP (int)
SIGTTIN (int)
SIGTTOU (int)
SIGURG (int)
SIGXCPU (int)
SIGXFSZ (int)
SIGVTALRM (int)
SIGPROF (int)
SIGWINCH (int)
SIGPOLL (int)
SIGIO (int)
SIGPWR (int)
SIGSYS (int)
SIGBABY (int)
SIGRTMIN (int)
SIGRTMAX (int)
SIG_BLOCK (int)
SIG_UNBLOCK (int)
SIG_SETMASK (int)
SI_* 定数
SI_USER (int)
SI_NOINFO (int)
SI_KERNEL (int)
SI_QUEUE (int)
SI_TIMER (int)
SI_MSGGQ (int)
SI_ASYNCIO (int)
SI_SIGIO (int)
SI_TKILL (int)
SI_MESGQ (int)
CLD_* 定数
CLD_EXITED (int)
CLD_KILLED (int)
CLD_DUMPED (int)
CLD_TRAPPED (int)
CLD_STOPPED (int)
CLD_CONTINUED (int)
TRAP_* 定数
TRAP_BRKPT (int)
TRAP_TRACE (int)
POLL_* 定数
POLL_IN (int)
POLL_OUT (int)
POLL_MSG (int)
POLL_ERR (int)
POLL_PRI (int)
POLL_HUP (int)
ILL_* 定数
ILL_ILLOPC (int)
ILL_ILLOPN (int)
ILL_ILLADR (int)
ILL_ILLTRP (int)
ILL_PRVOPC (int)
ILL_PRVREG (int)
ILL_COPROC (int)
ILL_BADSTK (int)
FPE_* 定数
FPE_INTDIV (int)
FPE_INTOVF (int)
FPE_FLTDIV (int)
FPE_FLTOVF (int)
FPE_FLTUND (int)
FPE_FLTRES (int)
FPE_FLTINV (int)
FPE_FLTSUB (int)
SEGV_* 定数
SEGV_MAPERR (int)
SEGV_ACCERR (int)
BUS_* 定数
BUS_ADRALN (int)
BUS_ADRERR (int)
BUS_OBJERR (int)
CLONE_* 定数
CLONE_NEWNS (int)
PHP 7.4.0 以降で利用可能。
CLONE_NEWIPC (int)
PHP 7.4.0 以降で利用可能。
CLONE_NEWUTS (int)
PHP 7.4.0 以降で利用可能。
CLONE_NEWNET (int)
PHP 7.4.0 以降で利用可能。
CLONE_NEWPID (int)
PHP 7.4.0 以降で利用可能。
CLONE_NEWUSER (int)
PHP 7.4.0 以降で利用可能。
CLONE_NEWCGROUP (int)
PHP 7.4.0 以降で利用可能。
PRIO_* 定数
PRIO_PGRP (int)
PRIO_USER (int)
PRIO_PROCESS (int)
PRIO_DARWIN_BG (int)
PHP 8.1.0 以降で利用可能。
PRIO_DARWIN_THREAD (int)
PHP 8.1.0 以降で利用可能。
Process Control error constants
定数 | 説明
PCNTL_E2BIG (int) | 引数リストが長すぎます
PCNTL_EACCES (int) | Permission denied
PCNTL_EAGAIN (int) | リソースが一時的に利用できない状態です
PCNTL_ECAPMODE (int) | capability モードで実行された際に許可されない操作を、 プロセスが実行しようとしました
PCNTL_ECHILD (int) | 子プロセスが存在しません
PCNTL_EFAULT (int) | アドレスが不正です
PCNTL_EINTR (int) | 関数呼び出しが中断されました
PCNTL_EINVAL (int) | 引数が不正です
PCNTL_EIO (int) | 入力/出力エラーです
PCNTL_EISDIR (int) | ディレクトリです
PCNTL_ELIBBAD (int) | 壊れた共有メモリにアクセスしようとしています
PCNTL_ELOOP (int) | シンボリックリンクの階層が多すぎます
PCNTL_EMFILE (int) | ファイルをオープンし過ぎです。 RLIMIT_NOFILE リソースリミットを超過することによってよく起こります。 /proc/sys/fs/nr_open で指定したリミットを超過することでも起こりえます。
PCNTL_ENAMETOOLONG (int) | ファイル名が長すぎます
PCNTL_ENFILE (int) | システムで多くのファイルをオープンし過ぎています。 Linux 上では、この原因は /proc/sys/fs/file-max リミットを超えた結果かもしれません。
PCNTL_ENOENT (int) | そのようなファイルやディレクトリはありません。 通常、このエラーは指定されたパス名が存在しないか、 パス名のプレフィックスとなるディレクトリのコンポーネントのひとつが存在しないか、 指定されたパス名が壊れたシンボリックリンクであることが原因で起こります。
PCNTL_ENOEXEC (int) | 実行フォーマットのエラーです
PCNTL_ENOMEM (int) | 空き領域がありません/メモリを割り当てできません
PCNTL_ENOSPC (int) | デバイスに空き領域がありません
PCNTL_ENOTDIR (int) | ディレクトリではありません
PCNTL_EPERM (int) | 操作が許可されていません
PCNTL_ESRCH (int) | そのようなプロセスはありません
PCNTL_ETXTBSY (int) | テキストファイルがビジー状態です
PCNTL_EUSERS (int) | ユーザーが多過ぎます
FORK_* constants
FORK_NOSIGCHLD (int)
FORK_WAITPID (int)
RF* constants
RFCFDG (int)
RFFDG (int)
RFLINUXTHPN (int)
RFNOWAIT (int)
RFPROC (int)
RFTHREAD (int)
RFTSIGZMB (int)


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • PCNTL
  • 例

例

目次

  • 基本的な使用法


基本的な使用法

この例は、シグナルハンドラを有するデーモンプロセスをフォークします。

例1 プロセス制御の例

<?php
declare(ticks=1);

$pid = pcntl_fork();
if ($pid == -1) {
die("fork できません");
} else if ($pid) {
exit(); // 親プロセスの場合
} else {
// 子プロセスの場合
}

// 制御側の端末からデタッチ
if (posix_setsid() == -1) {
die("could not detach from terminal");
}

// シグナルハンドラを設定
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");

// 無限ループでタスク実行
while (1) {

// 何か面白いことをここで行う

}

function sig_handler($signo)
{

switch ($signo) {
case SIGTERM:
// 終了タスクを処理
exit;
break;
case SIGHUP:
// 再起動タスクを処理
break;
default:
// その他の全てのシグナルを処理
}

}

?>


PCNTL 関数

参考

POSIX 関数の節を参照することも 有用でしょう。

目次

  • pcntl_alarm — シグナルを送信するアラームを設定する
  • pcntl_async_signals — 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す
  • pcntl_errno — pcntl_get_last_error のエイリアス
  • pcntl_exec — 現在のプロセス空間で指定したプログラムを実行する
  • pcntl_fork — 現在実行中のプロセスをフォークする
  • pcntl_get_last_error — 直近の pcntl 関数が失敗したときのエラー番号を取得する
  • pcntl_getpriority — プロセスの優先度を取得する
  • pcntl_rfork — プロセスのリソースを管理する
  • pcntl_setpriority — プロセスの優先度を変更する
  • pcntl_signal — シグナルハンドラを設定する
  • pcntl_signal_dispatch — ペンディングシグナル用のハンドラをコールする
  • pcntl_signal_get_handler — 指定されたシグナルの現在のハンドラを取得する
  • pcntl_sigprocmask — ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigtimedwait — タイムアウトつきでシグナルを待つ
  • pcntl_sigwaitinfo — シグナルを待つ
  • pcntl_strerror — 指定した errno に対応するシステムのエラーメッセージを取得する
  • pcntl_unshare — プロセスの実行コンテキストの一部を切り離す
  • pcntl_wait — 待つかフォークした子プロセスのステータスを返す
  • pcntl_waitpid — 待つかフォークした子プロセスのステータスを返す
  • pcntl_wexitstatus — 終了した子プロセスのリターンコードを返す
  • pcntl_wifexited — ステータスコードが正常終了を表しているかどうかを調べる
  • pcntl_wifsignaled — ステータスコードがシグナルによる終了を表しているかどうかを調べる
  • pcntl_wifstopped — 子プロセスが現在停止しているかどうかを調べる
  • pcntl_wstopsig — 子プロセスを停止させたシグナルを返す
  • pcntl_wtermsig — 子プロセスを終了させたシグナルを返す


シグナルを送信するアラームを設定する

  • ≪ PCNTL 関数
  • pcntl_async_signals ≫
  • PHP Manual
  • PCNTL 関数
  • シグナルを送信するアラームを設定する

pcntl_alarm

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pcntl_alarm — シグナルを送信するアラームを設定する

説明

pcntl_alarm(int $seconds): int

プロセスに対して、 指定した秒数後に SIGALRM シグナルを送信するタイマーを作成します。 pcntl_alarm() をコールすると、 それまでに設定されていたアラームはすべて取り消されます。

パラメータ

seconds

待機する秒数。seconds がゼロの場合は、 新しいアラームは作成されません。

戻り値

それまでに予定されていたアラームの予定時刻までの秒数を返します。 事前に予定されていたアラームがなかった場合には 0 を返します。


非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す

  • ≪ pcntl_alarm
  • pcntl_errno ≫
  • PHP Manual
  • PCNTL 関数
  • 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す

pcntl_async_signals

(PHP 7 >= 7.1.0, PHP 8)

pcntl_async_signals — 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す

説明

pcntl_async_signals(?bool $enable = null): bool

enable パラメータが省略された場合、 pcntl_async_signals() は非同期のシグナルハンドリングが有効かどうかを返します。 省略されなかった場合、非同期のシグナルハンドリングを 有効/無効 にします。

パラメータ

enable

非同期のシグナルハンドリングが有効にされるべきかどうか

戻り値

getter として使われた場合(オプションのパラメータが null だった場合)、 この関数は非同期シグナルハンドリングが有効かどうかを返します。 setter として使われた場合(つまり、オプションのパラメータが null でない場合)、 この関数はこの関数を呼び出す 前に 非同期シグナルハンドリングが有効だったかを返します。

変更履歴

バージョン | 説明
8.0.0 | enable は、nullable になりました。

参考

  • declare


pcntl_get_last_error のエイリアス

  • ≪ pcntl_async_signals
  • pcntl_exec ≫
  • PHP Manual
  • PCNTL 関数
  • pcntl_get_last_error のエイリアス

pcntl_errno

(PHP 5 >= 5.3.4, PHP 7, PHP 8)

pcntl_errno — pcntl_get_last_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 pcntl_get_last_error()


現在のプロセス空間で指定したプログラムを実行する

  • ≪ pcntl_errno
  • pcntl_fork ≫
  • PHP Manual
  • PCNTL 関数
  • 現在のプロセス空間で指定したプログラムを実行する

pcntl_exec

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pcntl_exec — 現在のプロセス空間で指定したプログラムを実行する

説明

pcntl_exec(string $path, array $args = [], array $env_vars = []): bool

指定した引数でプログラムを実行します。

パラメータ

path

path は、バイナリ実行ファイルへのパスか、 あるいは有効な実行ファイルを指す shebang (例: #!/usr/local/bin/perl) が一行目に存在するスクリプトへのパスである必要があります。 詳細な情報については、システムの man ページで execve(2) を参照ください。

args

args は、プログラムに渡す引数文字列の配列です。

env_vars

env_vars は、プログラムに渡す環境変数の配列です。 この配列は name => value のような形式で、key が環境変数名・value が その値となります。

戻り値

Returns false.


現在実行中のプロセスをフォークする

  • ≪ pcntl_exec
  • pcntl_get_last_error ≫
  • PHP Manual
  • PCNTL 関数
  • 現在実行中のプロセスをフォークする

pcntl_fork

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_fork — 現在実行中のプロセスをフォークする

説明

pcntl_fork(): int

pcntl_fork() 関数は、親プロセスとその PID および PPID のみが異なる子プロセスを生成します。システム上でのフォークの 動作の具体的な詳細については、実行するシステムの fork(2) の マニュアルを参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時に、子プロセスの PID が親プロセスの実行スレッドに返され、 子プロセスの実行スレッドには 0 が返されます。失敗した場合、親プロセスの コンテキストに -1 が返され、子プロセスは生成されずに、PHP のエラーが 出力されます。

例

例1 pcntl_fork() の例

<?php

$pid = pcntl_fork();
if ($pid == -1) {
die('fork できません');
} else if ($pid) {
// 親プロセスの場合
pcntl_wait($status); // ゾンビプロセスから守る
} else {
// 子プロセスの場合
}

?>

参考

  • pcntl_rfork() - プロセスのリソースを管理する
  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する
  • cli_set_process_title() - プロセスのタイトルを設定する


直近の pcntl 関数が失敗したときのエラー番号を取得する

  • ≪ pcntl_fork
  • pcntl_getpriority ≫
  • PHP Manual
  • PCNTL 関数
  • 直近の pcntl 関数が失敗したときのエラー番号を取得する

pcntl_get_last_error

(PHP 5 >= 5.3.4, PHP 7, PHP 8)

pcntl_get_last_error — 直近の pcntl 関数が失敗したときのエラー番号を取得する

説明

pcntl_get_last_error(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーコードを返します。

参考

  • pcntl_strerror() - 指定した errno に対応するシステムのエラーメッセージを取得する


プロセスの優先度を取得する

  • ≪ pcntl_get_last_error
  • pcntl_rfork ≫
  • PHP Manual
  • PCNTL 関数
  • プロセスの優先度を取得する

pcntl_getpriority

(PHP 5, PHP 7, PHP 8)

pcntl_getpriority — プロセスの優先度を取得する

説明

pcntl_getpriority(?int $process_id = null, int $mode = PRIO_PROCESS): int|false

pcntl_getpriority() は、 process_id の優先度を設定します。システムの型やカーネルの バージョンによって優先度の扱いは違うので、詳細についてはシステムの getpriority(2) の man ページを参照ください。

パラメータ

process_id

null だった場合は、現在のプロセスの プロセスID を使用します。

mode

PRIO_PGRP、PRIO_USER、 PRIO_PROCESS、PRIO_DARWIN_BG、 PRIO_DARWIN_THREAD のいずれか。

戻り値

pcntl_getpriority() はプロセスの優先度を返します。 エラー時には false を返します。数字が小さいほど、優先順位は上となります。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | process_id は、nullable になりました。

参考

  • pcntl_setpriority() - プロセスの優先度を変更する


プロセスのリソースを管理する

  • ≪ pcntl_getpriority
  • pcntl_setpriority ≫
  • PHP Manual
  • PCNTL 関数
  • プロセスのリソースを管理する

pcntl_rfork

(PHP 8 >= 8.1.0)

pcntl_rfork — プロセスのリソースを管理する

説明

pcntl_rfork(int $flags, int $signal = 0): int

プロセスのリソースを管理します。

パラメータ

flags

flags は、 呼び出しているプロセス(親) のリソースを新しいプロセス(子)と共有するか、 デフォルト値で初期化するかを指定します。

flags は、 以下のうちのいくつかを論理ORで指定します:

  • RFPROC: 設定すると、新しいプロセスが作られます。 設定しない場合、変更は現在のプロセスに適用されます。
  • RFNOWAIT: 設定すると、子プロセスは親プロセスから切り離されます。 子プロセスが終了するときには、 親プロセスが収集するステータスが残りません。
  • RFFDG: 設定すると、 呼び出し側のファイルディスクリプタテーブルがコピーされます。 設定しない場合、 ふたつのプロセスが単一のテーブルを共有します。
  • RFCFDG: 設定すると、新しいファイルディスクリプタテーブルを使って 新しいプロセスが開始されます。 RFFDG とは同時に指定できません。
  • RFLINUXTHPN: 設定すると、 子のスレッドが終了時に kernel は SIGCHILD ではなく、 SIGUSR1 を返します。 これは、Linux のcloneが終了時に、 親に状態を知らせる動作を模倣する意図があります。

signal

シグナル番号

戻り値

成功時には、親スレッドの実行時に子プロセスのPIDを返し、 子のスレッド実行時に 0 を返します。 失敗時には、親のコンテキストには -1 を返し、 子プロセスは作られません。そして、PHP のエラーが発生します。

例

例1 pcntl_rfork() の例

<?php

$pid = pcntl_rfork(RFNOWAIT|RFTSIGZMB, SIGUSR1);
if ($pid > 0) {
// This is the parent process.
var_dump($pid);
} else {
// This is the child process.
var_dump($pid);
sleep(2); // as the child does not wait, so we see its "pid"
}
?>

上の例の出力は、 たとえば以下のようになります。

int(77093)
int(0)

注意

注意:

この関数は、BSDシステムでのみ利用可能です。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する
  • cli_set_process_title() - プロセスのタイトルを設定する


プロセスの優先度を変更する

  • ≪ pcntl_rfork
  • pcntl_signal ≫
  • PHP Manual
  • PCNTL 関数
  • プロセスの優先度を変更する

pcntl_setpriority

(PHP 5, PHP 7, PHP 8)

pcntl_setpriority — プロセスの優先度を変更する

説明

pcntl_setpriority(int $priority, ?int $process_id = null, int $mode = PRIO_PROCESS): bool

pcntl_setpriority() は、 process_id の優先度を設定します。

パラメータ

priority

priority は一般的には -20 から 20 までの値です。 デフォルトの優先度は 0 で、数字が小さいほど 優先順位が上となります。システムの型やカーネルの バージョンによって優先度の扱いは違うので、詳細についてはシステムの setpriority(2) の man ページを参照ください。

process_id

null だった場合は、現在のプロセスの プロセスID を使用します。

mode

PRIO_PGRP、PRIO_USER、 PRIO_PROCESS、PRIO_DARWIN_BG、 PRIO_DARWIN_THREAD のいずれか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | process_id は、nullable になりました。

参考

  • pcntl_getpriority() - プロセスの優先度を取得する
  • pcntl_setpriority()


シグナルハンドラを設定する

  • ≪ pcntl_setpriority
  • pcntl_signal_dispatch ≫
  • PHP Manual
  • PCNTL 関数
  • シグナルハンドラを設定する

pcntl_signal

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_signal — シグナルハンドラを設定する

説明

pcntl_signal(int $signal, callable|int $handler, bool $restart_syscalls = true): bool

pcntl_signal() 関数は、signal が指すシグナルに関するハンドラを新たに設定するか、既存のハンドラを置き換えます。

パラメータ

signal

シグナル番号。

handler

シグナルハンドラ。callable を渡すと、それを実行してシグナルを処理します。 あるいは、グローバル定数 SIG_IGN または SIG_DFL を渡すこともできます。それぞれ、シグナルを無視することとデフォルトのシグナルハンドラを復活させることを表します。

callable を渡す場合は、次のシグネチャを実装したものでなければいけません。

handler(int $signo, mixed $siginfo): void
signal
処理するシグナル。
siginfo
OS が siginfo_t 構造体をサポートしている場合、 これはシグナルに依存するシグナル情報の配列になります。

注意:

オブジェクトのメソッドをハンドラとして指定した場合には、 そのハンドラを別のものに変えたりスクリプトが終了したりするまでは オブジェクトのリファレンスカウントが増加したままであることに注意しましょう。

restart_syscalls

再起動のシステムコールに対応するかどうかを設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | PHP 7.1.0 以降、 ハンドラコールバックは特定のシグナルの siginfo を含む 2 番目の引数を受け付けるようになりました。 このデータは、OS が siginfo_t 構造体を持つ場合のみ提供されます。 OS が siginfo_t を実装していない場合は NULL が提供されます。

例

例1 pcntl_signal() の例

<?php
// tick を使用しなければなりません
declare(ticks = 1);

// シグナルハンドラ関数
function sig_handler($signo)
{

switch ($signo) {
case SIGTERM:
// シャットダウンの処理
exit;
break;
case SIGHUP:
// 再起動の処理
break;
case SIGUSR1:
echo "SIGUSR1 を受け取りました...\n";
break;
default:
// それ以外のシグナルの処理
}

}

echo "シグナルハンドラを設定します...\n";

// シグナルハンドラを設定します
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");
pcntl_signal(SIGUSR1, "sig_handler");

// あるいは、オブジェクトも指定できます
// pcntl_signal(SIGUSR1, array($obj, "do_something"));

echo "自分自身に SIGUSR1 シグナルを送信します...\n";

// SIGUSR1 をカレントのプロセス ID に送信します
// posix_* 関数を使うには posix 拡張モジュールが必要です
posix_kill(posix_getpid(), SIGUSR1);

echo "終了\n";

?>

注意

pcntl_signal() は、既存のシグナルハンドラがある場合にはそれを上書きします。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す


ペンディングシグナル用のハンドラをコールする

  • ≪ pcntl_signal
  • pcntl_signal_get_handler ≫
  • PHP Manual
  • PCNTL 関数
  • ペンディングシグナル用のハンドラをコールする

pcntl_signal_dispatch

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_signal_dispatch — ペンディングシグナル用のハンドラをコールする

説明

pcntl_signal_dispatch(): bool

pcntl_signal_dispatch() 関数は、 pcntl_signal() がインストールしたシグナルハンドラを 各ペンディングシグナルに対してコールします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pcntl_signal_dispatch() の例

<?php
echo "Installing signal handler...\n";
pcntl_signal(SIGHUP, function($signo) {
echo "signal handler called\n";
});

echo "Generating signal SIGHUP to self...\n";
posix_kill(posix_getpid(), SIGHUP);

echo "Dispatching...\n";
pcntl_signal_dispatch();

echo "Done\n";

?>

上の例の出力は、 たとえば以下のようになります。

Installing signal handler...
Generating signal SIGHUP to self...
Dispatching...
signal handler called
Done

参考

  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_sigprocmask() - ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigwaitinfo() - シグナルを待つ
  • pcntl_sigtimedwait() - タイムアウトつきでシグナルを待つ


指定されたシグナルの現在のハンドラを取得する

  • ≪ pcntl_signal_dispatch
  • pcntl_sigprocmask ≫
  • PHP Manual
  • PCNTL 関数
  • 指定されたシグナルの現在のハンドラを取得する

pcntl_signal_get_handler

(PHP 7 >= 7.1.0, PHP 8)

pcntl_signal_get_handler — 指定されたシグナルの現在のハンドラを取得する

説明

pcntl_signal_get_handler(int $signal): callable|int

pcntl_signal_get_handler() 関数は、 指定された signal の現在のハンドラを取得します。

パラメータ

signal

シグナル番号

戻り値

この関数は、 SIG_DFL または SIG_IGN が参照する数値を返す可能性があります。 カスタムハンドラを設定している場合は、callable を返します。

変更履歴

バージョン | 説明
7.1.0 | pcntl_signal_get_handler() 関数が追加されました。

例

例1 pcntl_signal_get_handler() の例

<?php
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(0)

function pcntl_test($signo) {}
pcntl_signal(SIGUSR1, 'pcntl_test');
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: string(10) "pcntl_test"

pcntl_signal(SIGUSR1, SIG_DFL);
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(0)

pcntl_signal(SIGUSR1, SIG_IGN);
var_dump(pcntl_signal_get_handler(SIGUSR1)); // Outputs: int(1)
?>

参考

  • pcntl_signal() - シグナルハンドラを設定する


ブロックされたシグナルを設定あるいは取得する

  • ≪ pcntl_signal_get_handler
  • pcntl_sigtimedwait ≫
  • PHP Manual
  • PCNTL 関数
  • ブロックされたシグナルを設定あるいは取得する

pcntl_sigprocmask

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_sigprocmask — ブロックされたシグナルを設定あるいは取得する

説明

pcntl_sigprocmask(int $mode, array $signals, array &$old_signals = null): bool

pcntl_sigprocmask() 関数は、 ブロックされたシグナルを mode パラメータに応じて 追加、削除あるいは設定します。

パラメータ

mode

pcntl_sigprocmask() の挙動を設定します。以下の値が設定できます。

  • SIG_BLOCK: 現在ブロックされているシグナルにシグナルを追加する
  • SIG_UNBLOCK: 現在ブロックされているシグナルからシグナルを削除する
  • SIG_SETMASK: 現在ブロックされているシグナルを、指定したもので置き換える

signals

シグナルのリスト。

old_signals

old_signals パラメータには、 それまでにブロックされていたシグナルのリストが設定されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 pcntl_sigprocmask() の例

<?php
pcntl_sigprocmask(SIG_BLOCK, array(SIGHUP));
$oldset = array();
pcntl_sigprocmask(SIG_UNBLOCK, array(SIGHUP), $oldset);
?>

参考

  • pcntl_sigwaitinfo() - シグナルを待つ
  • pcntl_sigtimedwait() - タイムアウトつきでシグナルを待つ


タイムアウトつきでシグナルを待つ

  • ≪ pcntl_sigprocmask
  • pcntl_sigwaitinfo ≫
  • PHP Manual
  • PCNTL 関数
  • タイムアウトつきでシグナルを待つ

pcntl_sigtimedwait

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_sigtimedwait — タイムアウトつきでシグナルを待つ

説明

pcntl_sigtimedwait(
array $signals,
array &$info = [],
int $seconds = 0,
int $nanoseconds = 0
): int|false

pcntl_sigtimedwait() 関数の挙動は pcntl_sigwaitinfo() とほぼ同じですが、さらに 2 つのパラメータがあります。 seconds および nanoseconds がそれで、 スクリプトが待ち続ける時間の上限をここで設定することができます。

パラメータ

signals

待つシグナルの配列。

info

シグナルについての情報を含む配列が info に設定されます。 pcntl_sigwaitinfo() を参照ください。

seconds

タイムアウトの秒数。

nanoseconds

タイムアウトのナノ秒数。

戻り値

成功した場合に pcntl_sigtimedwait() はシグナル番号を返します。 失敗した場合に false を返します

参考

  • pcntl_sigprocmask() - ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigwaitinfo() - シグナルを待つ


シグナルを待つ

  • ≪ pcntl_sigtimedwait
  • pcntl_strerror ≫
  • PHP Manual
  • PCNTL 関数
  • シグナルを待つ

pcntl_sigwaitinfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

pcntl_sigwaitinfo — シグナルを待つ

説明

pcntl_sigwaitinfo(array $signals, array &$info = []): int|false

pcntl_sigwaitinfo() は、 呼び出し元のスクリプトの実行をいったん停止させ、signals で指定したシグナルを受け取るまで待ちます。もしそのシグナルのいずれかがすでにペンディング状態 (pcntl_sigprocmask() でブロックされているなど) の場合、 pcntl_sigwaitinfo() は即時に結果を返します。

パラメータ

signals

待つシグナルの配列。

info

シグナルについての情報を含む配列が info に設定されます。

次の要素は、すべてのシグナルについて設定されます。

  • signo: シグナル番号
  • errno: エラー番号
  • code: シグナルコード

次の要素は、SIGCHLD シグナルの場合に設定されます。

  • status: 終了値あるいはシグナル
  • utime: 使用したユーザー時間
  • stime: 使用したシステム時間
  • pid: 送信したプロセスの ID
  • uid: 送信したプロセスの実ユーザー ID

次の要素は、SIGILL、 SIGFPE、SIGSEGV および SIGBUS シグナルの場合に設定されます。

  • addr: 問題が発生したメモリ上の場所

次の要素は、SIGPOLL シグナルの場合に設定されます。

  • band: バンドイベント
  • fd: ファイル記述子番号

戻り値

成功した場合にシグナル番号を返します。 失敗した場合に false を返します

例

例1 pcntl_sigwaitinfo() の例

<?php
echo "Blocking SIGHUP signal\n";
pcntl_sigprocmask(SIG_BLOCK, array(SIGHUP));

echo "Sending SIGHUP to self\n";
posix_kill(posix_getpid(), SIGHUP);

echo "Waiting for signals\n";
$info = array();
pcntl_sigwaitinfo(array(SIGHUP), $info);
?>

参考

  • pcntl_sigprocmask() - ブロックされたシグナルを設定あるいは取得する
  • pcntl_sigtimedwait() - タイムアウトつきでシグナルを待つ


指定した errno に対応するシステムのエラーメッセージを取得する

  • ≪ pcntl_sigwaitinfo
  • pcntl_unshare ≫
  • PHP Manual
  • PCNTL 関数
  • 指定した errno に対応するシステムのエラーメッセージを取得する

pcntl_strerror

(PHP 5 >= 5.3.4, PHP 7, PHP 8)

pcntl_strerror — 指定した errno に対応するシステムのエラーメッセージを取得する

説明

pcntl_strerror(int $error_code): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

error_code

戻り値

エラーの説明を返します。

参考

  • pcntl_get_last_error() - 直近の pcntl 関数が失敗したときのエラー番号を取得する


プロセスの実行コンテキストの一部を切り離す

  • ≪ pcntl_strerror
  • pcntl_wait ≫
  • PHP Manual
  • PCNTL 関数
  • プロセスの実行コンテキストの一部を切り離す

pcntl_unshare

(PHP 7 >= 7.4.0, PHP 8)

pcntl_unshare — プロセスの実行コンテキストの一部を切り離す

説明

pcntl_unshare(int $flags): bool

pcntl_unshare() は、 プロセスが他のプロセスと現時点で共有している、 実行コンテキストの一部を切り離せるようにします。 pcntl_unshare() の主な用途は、 プロセスを作らずに、 プロセスが共有している実行コンテキストを制御できるようにすることです。

パラメータ

flags

flags は、 切り離すべき実行コンテキストの一部を指定するためのビットマスクです。 この引数は、以下に示す0個以上の CLONE_* 定数を OR 条件として指定します:

  • CLONE_NEWNS
  • CLONE_NEWIPC
  • CLONE_NEWUTS
  • CLONE_NEWNET
  • CLONE_NEWPID
  • CLONE_NEWUSER
  • CLONE_NEWCGROUP

戻り値

成功した場合、0 を返します。 失敗した場合、-1 を返し、 エラーコードを設定します。 エラーコードは、pcntl_get_last_error() で取得できます。

参考

  • PCNTL 定数
  • pcntl_get_last_error() - 直近の pcntl 関数が失敗したときのエラー番号を取得する


待つかフォークした子プロセスのステータスを返す

  • ≪ pcntl_unshare
  • pcntl_waitpid ≫
  • PHP Manual
  • PCNTL 関数
  • 待つかフォークした子プロセスのステータスを返す

pcntl_wait

(PHP 5, PHP 7, PHP 8)

pcntl_wait — 待つかフォークした子プロセスのステータスを返す

説明

pcntl_wait(int &$status, int $flags = 0, array &$resource_usage = []): int

この関数は、子プロセスが終了する・ カレントのプロセスを終了させるシグナルが送信される・シグナル処理関数を コールするシグナルが送信される のいずれかが発生するまでカレントのプロセスの実行を中断します。 子プロセスが、 コール時に 既に終了している場合("ゾンビ"プロセスと呼ばれます)、この関数は 直ちに処理を返します。子プロセスにより使用される全てのシステム リソースは、解放されます。waitpid のシステムでの動作に関する詳細は、 システムの wait(2) についての man ページを参照ください。

注意:

この関数は、process_id に -1 を指定し、flags を何も設定せずに pcntl_waitpid() をコールするのと等価です。

パラメータ

status

pcntl_wait() は、パラメータ
status の中にステータス情報を保存します。
このステータスは、次の関数を用いて評価可能です。
pcntl_wifexited()、
pcntl_wifstopped()、
pcntl_wifsignaled()、
pcntl_wexitstatus()、
pcntl_wtermsig() および
pcntl_wstopsig() 。

flags

システム上で wait3 が使用可能な場合 (ほとんどの BSD 系システムが 該当します)、オプションのパラメータ flags を使用可能です。このパラメータが指定されない場合、wait はシステムコールに 対して使用されます。wait3 が使用できない場合、flags に値を設定しても何の影響も及ぼしません。 flags の値は、次の 2 つのグローバル定数の ゼロまたはそれ以上の論理和です。

flags のとりうる値
WNOHANG | 子プロセスが終了していない場合に直ちに処理を返します。
WUNTRACED | 停止した子プロセスの場合に処理を返します。 そして、ステータスは報告されません。

戻り値

pcntl_wait() は、終了した子プロセスの プロセス ID を返します。エラーの場合は -1、(wait3 が使用可能なシステムで) WNOHANG が使用され、子プロセスが利用できない場合に 0 を返します。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる
  • pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる
  • pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる
  • pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す
  • pcntl_wtermsig() - 子プロセスを終了させたシグナルを返す
  • pcntl_wstopsig() - 子プロセスを停止させたシグナルを返す
  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す


待つかフォークした子プロセスのステータスを返す

  • ≪ pcntl_wait
  • pcntl_wexitstatus ≫
  • PHP Manual
  • PCNTL 関数
  • 待つかフォークした子プロセスのステータスを返す

pcntl_waitpid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_waitpid — 待つかフォークした子プロセスのステータスを返す

説明

pcntl_waitpid(
int $process_id,
int &$status,
int $flags = 0,
array &$resource_usage = []
): int

引数 process_id で指定した子プロセスが終了する・ 現在のプロセスを終了させるシグナルが送信される・シグナル処理関数を コールするシグナルが送信される のいずれかが発生するまで、現在のプロセスの実行を中断します。

process_id でリクエストされた子プロセスが、 コール時に既に終了している場合("ゾンビ"プロセスと呼ばれます)、 この関数は直ちに処理を返します。 子プロセスにより使用される全てのシステム リソースは、解放されます。waitpid のシステムでの動作に関する詳細は、 システムの waitpid(2) についての man ページを参照ください。

パラメータ

process_id

process_id の値は、次のどれかとなります。

process_id のとりうる値
< -1 | プロセスグループ ID が process_id の絶対値に等しい 子プロセスを待ちます。
-1 | 全ての子プロセスを待ちます。これは、wait 関数の動作と同じです。
0 | プロセスグループ ID がコール側のプロセスと等しい子プロセスを 待ちます。
> 0 | プロセス ID が process_id の値に等しい 子プロセスを待ちます。

注意:

-1 を process_id に指定した際の動きは、 pcntl_wait() の機能と (flags を除いて) 同じです。

status

pcntl_waitpid() は、パラメータ
status の中にステータス情報を保存します。
このステータスは、次の関数を用いて評価可能です。
pcntl_wifexited()、
pcntl_wifstopped()、
pcntl_wifsignaled()、
pcntl_wexitstatus()、
pcntl_wtermsig() および
pcntl_wstopsig() 。

flags

flags の値は、次の 2 つのグローバル定数の ゼロまたはそれ以上の論理和です。

flags のとりうる値
WNOHANG | 子プロセスが終了していない場合に直ちに処理を返します。
WUNTRACED | 停止した子プロセスの場合に処理を返します。そして、ステータス は報告されません。

戻り値

pcntl_waitpid() は、終了した子プロセスの プロセス ID を返します。エラーの場合は -1、WNOHANG が使用され、 子プロセスが利用できない場合に 0 を返します。

参考

  • pcntl_fork() - 現在実行中のプロセスをフォークする
  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる
  • pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる
  • pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる
  • pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す
  • pcntl_wtermsig() - 子プロセスを終了させたシグナルを返す
  • pcntl_wstopsig() - 子プロセスを停止させたシグナルを返す


終了した子プロセスのリターンコードを返す

  • ≪ pcntl_waitpid
  • pcntl_wifexited ≫
  • PHP Manual
  • PCNTL 関数
  • 終了した子プロセスのリターンコードを返す

pcntl_wexitstatus

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wexitstatus — 終了した子プロセスのリターンコードを返す

説明

pcntl_wexitstatus(int $status): int|false

終了した子プロセスのリターンコードを返します。この関数は、 pcntl_wifexited() が true を返す場合のみ 有用です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

戻り値

リターンコードを返します。 この機能を OS がサポートしていない場合、false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_wifexited() - ステータスコードが正常終了を表しているかどうかを調べる


ステータスコードが正常終了を表しているかどうかを調べる

  • ≪ pcntl_wexitstatus
  • pcntl_wifsignaled ≫
  • PHP Manual
  • PCNTL 関数
  • ステータスコードが正常終了を表しているかどうかを調べる

pcntl_wifexited

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wifexited — ステータスコードが正常終了を表しているかどうかを調べる

説明

pcntl_wifexited(int $status): bool

ステータスコードが正常終了を表しているかどうかを調べます。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

戻り値

子プロセスのステータスコードが終了に成功した場合に true、 それ以外の場合に false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_wexitstatus() - 終了した子プロセスのリターンコードを返す


ステータスコードがシグナルによる終了を表しているかどうかを調べる

  • ≪ pcntl_wifexited
  • pcntl_wifstopped ≫
  • PHP Manual
  • PCNTL 関数
  • ステータスコードがシグナルによる終了を表しているかどうかを調べる

pcntl_wifsignaled

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wifsignaled — ステータスコードがシグナルによる終了を表しているかどうかを調べる

説明

pcntl_wifsignaled(int $status): bool

子プロセスが終了した原因が、 シグナルが捕捉されなかったことであるかどうかを調べます。 caught.

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

戻り値

捕捉されなかったシグナルのせいで子プロセスが終了した場合に true、 それ以外の場合に false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する


子プロセスが現在停止しているかどうかを調べる

  • ≪ pcntl_wifsignaled
  • pcntl_wstopsig ≫
  • PHP Manual
  • PCNTL 関数
  • 子プロセスが現在停止しているかどうかを調べる

pcntl_wifstopped

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wifstopped — 子プロセスが現在停止しているかどうかを調べる

説明

pcntl_wifstopped(int $status): bool

リターンを生じた子プロセスが現在停止しているかどうかを調べます。 この関数は、pcntl_waitpid() のコールが オプション WUNTRACED を用いている場合のみ使用可能です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

戻り値

リターンを生じた子プロセスが現在停止している場合に true、 それ以外の場合に false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す


子プロセスを停止させたシグナルを返す

  • ≪ pcntl_wifstopped
  • pcntl_wtermsig ≫
  • PHP Manual
  • PCNTL 関数
  • 子プロセスを停止させたシグナルを返す

pcntl_wstopsig

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wstopsig — 子プロセスを停止させたシグナルを返す

説明

pcntl_wstopsig(int $status): int|false

子プロセスを停止させたシグナル番号を返します。この関数は、 pcntl_wifstopped() が true を返す場合のみ有用です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

戻り値

シグナル番号を返します。 この機能を OS がサポートしていない場合、false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_wifstopped() - 子プロセスが現在停止しているかどうかを調べる


子プロセスを終了させたシグナルを返す

  • ≪ pcntl_wstopsig
  • POSIX ≫
  • PHP Manual
  • PCNTL 関数
  • 子プロセスを終了させたシグナルを返す

pcntl_wtermsig

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

pcntl_wtermsig — 子プロセスを終了させたシグナルを返す

説明

pcntl_wtermsig(int $status): int|false

子プロセスを終了させたシグナル番号を返します。この関数は、 pcntl_wifsignaled() が true を返す場合のみ有用です。

パラメータ

status

パラメータ status は、 pcntl_waitpid() が正常にコールされた際に得られます。

戻り値

シグナル番号を返します。 この機能を OS がサポートしていない場合、false を返します。

参考

  • pcntl_waitpid() - 待つかフォークした子プロセスのステータスを返す
  • pcntl_signal() - シグナルハンドラを設定する
  • pcntl_wifsignaled() - ステータスコードがシグナルによる終了を表しているかどうかを調べる


POSIX

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
    • posix_access 定数
    • posix_mknod 定数
    • posix_setrlimit 定数
    • posix_pathconf の定数
    • posix_sysconf の定数
  • POSIX 関数
    • posix_access — ファイルのアクセス権限を判断する
    • posix_ctermid — 制御する端末のパス名を得る
    • posix_eaccess — ファイルがアクセスできるかを調べる
    • posix_errno — posix_get_last_error のエイリアス
    • posix_fpathconf — 設定可能なリミットの値を返す
    • posix_get_last_error — 直近で失敗した posix 関数が設定したエラー番号を取得する
    • posix_getcwd — 現在のディレクトリのパス名
    • posix_getegid — 現在のプロセスの有効なグループ ID を返す
    • posix_geteuid — 現在のプロセスの有効なユーザー ID を返す
    • posix_getgid — 現在のプロセスの実際のグループ ID を返す
    • posix_getgrgid — 指定したグループ ID を有するグループに関する情報を返す
    • posix_getgrnam — 指定した名前のグループに関する情報を返す
    • posix_getgroups — 現在のプロセスのグループセットを返す
    • posix_getlogin — ログイン名を返す
    • posix_getpgid — ジョブ制御のプロセスグループ ID を得る
    • posix_getpgrp — 現在のプロセスのグループ ID を返す
    • posix_getpid — 現在のプロセス ID を返す
    • posix_getppid — 親プロセスの ID を返す
    • posix_getpwnam — 指定した名前のユーザーに関する情報を返す
    • posix_getpwuid — 指定 ID のユーザーに関する情報を返す
    • posix_getrlimit — システムリソース制限に関する情報を返す
    • posix_getsid — プロセスの現在の sid を得る
    • posix_getuid — 現在のプロセスの実際のユーザー ID を返す
    • posix_initgroups — グループアクセスリストを求める
    • posix_isatty — ファイル記述子が対話型端末であるかどうかを定義する
    • posix_kill — プロセスにシグナルを送信する
    • posix_mkfifo — fifo スペシャルファイル(名前付きパイプ)を作成する
    • posix_mknod — スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)
    • posix_pathconf — 設定可能なリミットの値を返す
    • posix_setegid — 現在のプロセスの実効 GID を設定する
    • posix_seteuid — 現在のプロセスの実効 UID を設定する
    • posix_setgid — 現在のプロセスの GID を設定する
    • posix_setpgid — ジョブ制御のプロセスグループ ID を設定する
    • posix_setrlimit — システムリソース制限を設定
    • posix_setsid — 現在のプロセスをセッションリーダーにする
    • posix_setuid — 現在のプロセスの UID を設定する
    • posix_strerror — 指定したエラー番号に対応するシステムのエラーメッセージを取得する
    • posix_sysconf — システムの実行時情報を返す
    • posix_times — プロセス時間を得る
    • posix_ttyname — 端末のデバイス名を調べる
    • posix_uname — システム名を得る


はじめに

このモジュールは、IEEE 10003.1 (POSIX.1) 標準ドキュメントで 定義された関数へのインターフェイスを有しています。 これらの関数は、他の手段からは利用できません。

警告

posix_getpwnam() のような POSIX 関数は、重要な データを取得することができます。

注意: この拡張モジュールは Windows 環境では利用できません。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • POSIX
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-posix


定義済み定数

目次

  • posix_access 定数
  • posix_mknod 定数
  • posix_setrlimit 定数
  • posix_pathconf の定数
  • posix_sysconf の定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。


posix_access 定数

  • ≪ 定義済み定数
  • posix_mknod 定数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_access 定数

posix_access() 定数

注意:

システムによっては いくつかの定数が使用できない場合があることに注意してください。

POSIX_F_OK (int)
ファイルが存在するかどうかを調べます。
POSIX_R_OK (int)
ファイルが存在し、読み込みが許可されているかどうかを調べます。
POSIX_W_OK (int)
ファイルが存在し、書き込みが許可されているかどうかを調べます。
POSIX_X_OK (int)
ファイルが存在し、実行が許可されているかどうかを調べます。


posix_mknod 定数

  • ≪ posix_access 定数
  • posix_setrlimit 定数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_mknod 定数

posix_mknod() 定数

注意:

システムによっては いくつかの定数が使用できない場合があることに注意してください。

POSIX_S_IFBLK (int)
ブロックスペシャルファイル。
POSIX_S_IFCHR (int)
キャラクタスペシャルファイル。
POSIX_S_IFIFO (int)
FIFO (名前つきパイプ) スペシャルファイル。
POSIX_S_IFREG (int)
通常のファイル。
POSIX_S_IFSOCK (int)
ソケット。


posix_setrlimit 定数

  • ≪ posix_mknod 定数
  • posix_pathconf の定数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_setrlimit 定数

posix_setrlimit() 定数

注意:

システムによっては いくつかの定数が使用できない場合があることに注意してください。

注意:

以下の一覧とともに、特定のオペレーションシステムの setrlimit() のマニュアルページを読みたくなるかもしれません。 なぜなら、POSIX を完全に実装していると主張するオペレーティングシステム間でも、 これらの値をどう解釈するかはばらつきがあるからです。

POSIX_RLIMIT_AS (int)
プロセスのアドレススペースの最大値をバイト単位で指定します。 PHP の memory_limit 設定ディレクティブも参照ください。
POSIX_RLIMIT_CORE (int)
core ファイルの最大サイズ。 0 に設定すると、core ファイルは生成されません。
POSIX_RLIMIT_CPU (int)
プロセスが使えるCPU時間の上限を秒単位で指定します。 プロセスがソフトリミットに達した場合、SIGXCPU シグナルが送られます。 これは pcntl_signal() でキャッチできます。 オペレーティングシステムによっては、 追加の SIGXCPU シグナルをハードリミットに達する まで1秒ごとに送り、ハードリミットに達すると SIGKILL シグナルを送るかもしれません。 See also set_time_limit().
POSIX_RLIMIT_DATA (int)
プロセスのデータセグメントの最大値をバイト単位で指定します。 brk() や sbrk() を呼ぶ拡張モジュールでもない限り、 この設定がPHPの実行に影響を及ぼす可能性は極めて小さいです。
POSIX_RLIMIT_FSIZE (int)
プロセスが作成できるファイルサイズの最大値をバイト単位で指定します。
POSIX_RLIMIT_LOCKS (int)
プロセスが作ることができるロック数の最大数。 これは極めて古い Linux kernel でのみサポートされています。
POSIX_RLIMIT_MEMLOCK (int)
The maximum number of bytes that can be locked into memory. メモリ内にロックできるメモリの最大バイト数。
POSIX_RLIMIT_MSGQUEUE (int)
POSIX メッセージキューのために確保できるバイト数の制限を指定する。 PHP は POSIX メッセージキューをサポートしていないので、 このリミットは POSIX メッセージキューをサポートした拡張モジュールを使っていない限り効果がありません。
POSIX_RLIMIT_NICE (int)
プロセスが 設定できるnice値 の上限を指定します。 リソース制限値として負の数を指定できないため、20 - limit という値が実際に使われます。
POSIX_RLIMIT_NOFILE (int)
このプロセスがオープンできるファイルディスクリプター数の最大値より1大きい値を指定します。
POSIX_RLIMIT_NPROC (int)
プロセスの実ユーザーIDで作成できる最大プロセス数(オペレーティングシステムによってはスレッド数)
POSIX_RLIMIT_RSS (int)
プロセスの resident set の最大値をページ数単位で指定します。
POSIX_RLIMIT_RTPRIO (int)
sched_setscheduler() や sched_setparam() システムコール経由で 設定できる、リアルタイム優先度の最大値
POSIX_RLIMIT_RTTIME (int)
リアルタイムスケジューリングを採用している場合に スケジューリングされるプロセスが、 ブロッキング型のシステムコールを呼び出さずに消費できる CPU時間の最大値をマイクロ秒単位で指定します。
POSIX_RLIMIT_SIGPENDING (int)
プロセスの実ユーザーID に対して、 キューに入れられるシグナルの数の最大値
POSIX_RLIMIT_STACK (int)
プロセススタックの最大サイズをバイト単位で指定します。
POSIX_RLIMIT_INFINITY (int)
リソースリミットが無限であることを示すのに使われます。
POSIX_RLIMIT_KQUEUES (int)
このユーザーID が作成できる kqueues の数の最大値 (FreeBSD)。 PHP 8.1.0 以降で利用可能です。
POSIX_RLIMIT_NPTS (int)
このユーザーID が作成できる擬似端末の数の最大値 (FreeBSD)。 PHP 8.1.0 以降で利用可能です。


posix_pathconf の定数

  • ≪ posix_setrlimit 定数
  • posix_sysconf の定数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_pathconf の定数

posix_pathconf() の定数

POSIX_PC_LINK_MAX (int)
指定されたファイルやディレクトリが持つことができるリンク数の最大値。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_MAX_CANON (int)
端末の正規入力バッファ(キャラクタ特殊ファイルのパス名)の最大バイト数。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_MAX_INPUT (int)
端末の正規入力キュー(キャラクタ特殊ファイルのパス名)の最大バイト数。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_NAME_MAX (int)
パスではなく、ファイル名単体で使える最大文字数。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_PATH_MAX (int)
フルパスの名前に使える最大文字数。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_PIPE_BUF (int)
一回の操作でパイプに書き込める最大バイト数。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_CHOWN_RESTRICTED (int)
chown() が動作できるのに必須の権限。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_NO_TRUNC (int)
ファイル名(またはディレクトリ下のファイル) が POSIX_PC_NAME_MAX より長い場合。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_ALLOC_SIZE_MIN (int)
ファイルの一部が割り当てられるストレージの、バイト単位の最小値。 PHP 8.3.0 以降で利用可能です。
POSIX_PC_ALLOC_SYMLINK_MAX (int)
指定されたファイルやディレクトリが持つことできるシンボリックリンクの最大数。 PHP 8.3.0 以降で利用可能です。


posix_sysconf の定数

  • ≪ posix_pathconf の定数
  • POSIX 関数 ≫
  • PHP Manual
  • 定義済み定数
  • posix_sysconf の定数

posix_sysconf() の定数

POSIX_SC_ARG_MAX (int)
引数(と環境変数)が持つことができるバイト数の最大値。 PHP 8.3.0 以降で利用可能です。
POSIX_SC_PAGESIZE (int)
現在のページのバイト数。 PHP 8.3.0 以降で利用可能です。
POSIX_SC_NPROCESSORS_CONF (int)
システムで設定済みのcpuの数。 PHP 8.3.0 以降で利用可能です。
POSIX_SC_NPROCESSORS_ONLN (int)
システムで現状アクティブなcpuの数。 PHP 8.3.0 以降で利用可能です。


POSIX 関数

参考

プロセス制御関数に関する節も 役に立つでしょう。

目次

  • posix_access — ファイルのアクセス権限を判断する
  • posix_ctermid — 制御する端末のパス名を得る
  • posix_eaccess — ファイルがアクセスできるかを調べる
  • posix_errno — posix_get_last_error のエイリアス
  • posix_fpathconf — 設定可能なリミットの値を返す
  • posix_get_last_error — 直近で失敗した posix 関数が設定したエラー番号を取得する
  • posix_getcwd — 現在のディレクトリのパス名
  • posix_getegid — 現在のプロセスの有効なグループ ID を返す
  • posix_geteuid — 現在のプロセスの有効なユーザー ID を返す
  • posix_getgid — 現在のプロセスの実際のグループ ID を返す
  • posix_getgrgid — 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgrnam — 指定した名前のグループに関する情報を返す
  • posix_getgroups — 現在のプロセスのグループセットを返す
  • posix_getlogin — ログイン名を返す
  • posix_getpgid — ジョブ制御のプロセスグループ ID を得る
  • posix_getpgrp — 現在のプロセスのグループ ID を返す
  • posix_getpid — 現在のプロセス ID を返す
  • posix_getppid — 親プロセスの ID を返す
  • posix_getpwnam — 指定した名前のユーザーに関する情報を返す
  • posix_getpwuid — 指定 ID のユーザーに関する情報を返す
  • posix_getrlimit — システムリソース制限に関する情報を返す
  • posix_getsid — プロセスの現在の sid を得る
  • posix_getuid — 現在のプロセスの実際のユーザー ID を返す
  • posix_initgroups — グループアクセスリストを求める
  • posix_isatty — ファイル記述子が対話型端末であるかどうかを定義する
  • posix_kill — プロセスにシグナルを送信する
  • posix_mkfifo — fifo スペシャルファイル(名前付きパイプ)を作成する
  • posix_mknod — スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)
  • posix_pathconf — 設定可能なリミットの値を返す
  • posix_setegid — 現在のプロセスの実効 GID を設定する
  • posix_seteuid — 現在のプロセスの実効 UID を設定する
  • posix_setgid — 現在のプロセスの GID を設定する
  • posix_setpgid — ジョブ制御のプロセスグループ ID を設定する
  • posix_setrlimit — システムリソース制限を設定
  • posix_setsid — 現在のプロセスをセッションリーダーにする
  • posix_setuid — 現在のプロセスの UID を設定する
  • posix_strerror — 指定したエラー番号に対応するシステムのエラーメッセージを取得する
  • posix_sysconf — システムの実行時情報を返す
  • posix_times — プロセス時間を得る
  • posix_ttyname — 端末のデバイス名を調べる
  • posix_uname — システム名を得る


ファイルのアクセス権限を判断する

  • ≪ POSIX 関数
  • posix_ctermid ≫
  • PHP Manual
  • POSIX 関数
  • ファイルのアクセス権限を判断する

posix_access

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

posix_access — ファイルのアクセス権限を判断する

説明

posix_access(string $filename, int $flags = 0): bool

posix_access() は、ファイルに対するユーザーの アクセス権限を調べます。

パラメータ

filename

調べるファイルの名前。

flags

POSIX_F_OK、POSIX_R_OK、 POSIX_W_OK および POSIX_X_OK のうちのひとつあるいは複数からなるマスク。

POSIX_R_OK、POSIX_W_OK および POSIX_X_OK は、ファイルが存在して読み込み/書き込み/ 実行の権限があるかどうかを調べます。 POSIX_F_OK は単にファイルが存在するかどうか だけを調べます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_access() の例

この例は $file が読み書き可能であるかどうかを調べ、 そうでない場合にエラーメッセージを表示します。

<?php

$file = 'some_file';

if (posix_access($file, POSIX_R_OK | POSIX_W_OK)) {
echo 'このファイルの読み込みと書き込みが可能です!';

} else {
$error = posix_get_last_error();

echo "エラー $error: " . posix_strerror($error);
}

?>

参考

  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する
  • posix_strerror() - 指定したエラー番号に対応するシステムのエラーメッセージを取得する


制御する端末のパス名を得る

  • ≪ posix_access
  • posix_eaccess ≫
  • PHP Manual
  • POSIX 関数
  • 制御する端末のパス名を得る

posix_ctermid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_ctermid — 制御する端末のパス名を得る

説明

posix_ctermid(): string|false

そのプロセスで現在制御している端末のパス名を表す文字列を作成します。 エラーが発生した場合は errno を設定します。この値を調べるには posix_get_last_error() を使用します。

パラメータ

この関数にはパラメータはありません。

戻り値

処理に成功した場合は、現在制御している端末のパス名を表す文字列を返します。 それ以外の場合は false を返し、errno を設定します。 この値を調べるには posix_get_last_error() を使用します。

例

例1 posix_ctermid() の例

この例は、現在の TTY へのパスを表示します。

<?php
echo "I am running from ".posix_ctermid();
?>

参考

  • posix_ttyname() - 端末のデバイス名を調べる
  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する


ファイルがアクセスできるかを調べる

  • ≪ posix_ctermid
  • posix_errno ≫
  • PHP Manual
  • POSIX 関数
  • ファイルがアクセスできるかを調べる

posix_eaccess

(PHP 8 >= 8.3.0)

posix_eaccess — ファイルがアクセスできるかを調べる

説明

posix_eaccess(string $filename, int $flags = 0): bool

posix_eaccess() は、ファイルの実効ユーザーのパーミッションを調べます。

パラメータ

filename

調べるファイル名

flags

POSIX_F_OK, POSIX_R_OK, POSIX_W_OK, POSIX_X_OK のうち、ひとつ以上のビットマスクの組み合わせです。

POSIX_R_OK, POSIX_W_OK, POSIX_X_OK についてはそれぞれ、 ファイルが存在し読み取り可能、ファイルが存在し書き込み可能、 ファイルが存在し実行可能という意味になります。 POSIX_F_OK は、 ファイルが存在するかどうかだけを調べます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | ファイルの実効ユーザー/グループを調べるようになりました。 実ユーザー/グループを調べる posix_access() とは異なります。

例

例1 posix_eaccess() の例

このサンプルは、$file が読み取り可能かつ書き込み可能かを調べます。 そうでない場合、エラーメッセージを出力します。

<?php

$file = 'some_file';

if (posix_eaccess($file, POSIX_R_OK | POSIX_W_OK)) {
echo 'The file is readable and writable!';

} else {
$error = posix_get_last_error();

echo "Error $error: " . posix_strerror($error);
}

?>

参考

  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する
  • posix_strerror() - 指定したエラー番号に対応するシステムのエラーメッセージを取得する
  • posix_access() - ファイルのアクセス権限を判断する


posix_get_last_error のエイリアス

  • ≪ posix_eaccess
  • posix_fpathconf ≫
  • PHP Manual
  • POSIX 関数
  • posix_get_last_error のエイリアス

posix_errno

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

posix_errno — posix_get_last_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 posix_get_last_error().


設定可能なリミットの値を返す

  • ≪ posix_errno
  • posix_get_last_error ≫
  • PHP Manual
  • POSIX 関数
  • 設定可能なリミットの値を返す

posix_fpathconf

(PHP 8 >= 8.3.0)

posix_fpathconf — 設定可能なリミットの値を返す

説明

posix_fpathconf(resource|int $file_descriptor, int $name): int|false

ファイルディスクリプタ resource の name から、 設定可能なリミットの値を返します。

パラメータ

file_descriptor

ファイル記述子。ファイルリソースか、あるいは int で指定します。 int を指定した場合は、システムコールにそのまま渡せるファイル記述子だとみなします。

name

設定可能なリミットの名前。 以下のうちのひとつを指定します。 POSIX_PC_LINK_MAX, POSIX_PC_MAX_CANON POSIX_PC_MAX_INPUT, POSIX_PC_NAME_MAX POSIX_PC_PATH_MAX, POSIX_PC_PIPE_BUF POSIX_PC_CHOWN_RESTRICTED, POSIX_PC_NO_TRUNC POSIX_PC_ALLOC_SIZE_MIN, POSIX_PC_SYMLINK_MAX

戻り値

設定可能なリミットの値、または false を返します。

エラー / 例外

resource が無効な場合、ValueError がスローされます。

例

例1 posix_fpathconf() の例

このサンプルは、カレントディレクトリの最大のパス名の長さをバイト単位で取得します。

<?php
$fd = fopen(__DIR__, "r");
echo posix_fpathconf($fd, POSIX_PC_PATH_MAX);
?>

上の例の出力は以下となります。

4096

参考

  • posix_pathconf() - 設定可能なリミットの値を返す


直近で失敗した posix 関数が設定したエラー番号を取得する

  • ≪ posix_fpathconf
  • posix_getcwd ≫
  • PHP Manual
  • POSIX 関数
  • 直近で失敗した posix 関数が設定したエラー番号を取得する

posix_get_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

posix_get_last_error — 直近で失敗した posix 関数が設定したエラー番号を取得する

説明

posix_get_last_error(): int

直近で失敗した posix 関数が設定したエラー番号を取得します。 エラー番号に対応するエラーメッセージを取得するには posix_strerror() を使用します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近で失敗した posix 関数が設定した errno (エラー番号) を返します。 エラーが発生していない場合は 0 が返されます。

例

例1 posix_get_last_error() の例

この例では、存在しないプロセス ID のプロセスを殺そうとしています。 その結果として発生したエラーの番号を表示します。

<?php
posix_kill(999459,SIGKILL);
echo 'エラーが返されました。エラー番号: '.posix_get_last_error(); //Your error was ___
?>

参考

  • posix_strerror() - 指定したエラー番号に対応するシステムのエラーメッセージを取得する


現在のディレクトリのパス名

  • ≪ posix_get_last_error
  • posix_getegid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のディレクトリのパス名

posix_getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getcwd — 現在のディレクトリのパス名

説明

posix_getcwd(): string|false

スクリプトの現在の実行ディレクトリのパスを、絶対パスで取得します。 エラー時には errno を設定します。この値は posix_get_last_error() で取得することができます。

パラメータ

この関数にはパラメータはありません。

戻り値

絶対パスを表す文字列を返します。 エラー時には false を返し、errno を設定します。この値は posix_get_last_error() で取得することができます。

例

例1 posix_getcwd() の例

この例は、このスクリプトの現在の作業ディレクトリの絶対パスを返します。

<?php
echo '現在の作業ディレクトリは '.posix_getcwd();
?>

注意

注意:

以下のような場合は、この関数は失敗します。

  • 読み込みあるいは検索の権限が取得できない
  • パスが存在しない


現在のプロセスの有効なグループ ID を返す

  • ≪ posix_getcwd
  • posix_geteuid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの有効なグループ ID を返す

posix_getegid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getegid — 現在のプロセスの有効なグループ ID を返す

説明

posix_getegid(): int

現在のプロセスの有効なグループ ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

実効グループ ID を表す整数値を返します。

例

例1 posix_getegid() example

この例は、実効グループ ID を表示し、それを posix_setegid() で変更します。

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setegid(40);
echo '実グループ ID は '.posix_getgid(); //20
echo '実効グループ ID は '.posix_getegid(); //40
?>

注意

posix_getegid() は posix_getgid() と異なります。 実効グループ ID は、コール元のプロセスから posix_setegid() で変更できるからです。

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgid() - 現在のプロセスの実際のグループ ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する


現在のプロセスの有効なユーザー ID を返す

  • ≪ posix_getegid
  • posix_getgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの有効なユーザー ID を返す

posix_geteuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_geteuid — 現在のプロセスの有効なユーザー ID を返す

説明

posix_geteuid(): int

現在のプロセスの有効なユーザー ID を返します。 使用可能なユーザー名に変換する方法に関する情報については、 posix_getpwuid() も参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

ユーザー ID を表す整数値を返します。

例

例1 posix_geteuid() の例

この例は、まず現在のユーザー ID を表示し、 それから posix_seteuid() で実効ユーザー ID を設定します。その後、改めて実ユーザー ID と実効ユーザー ID を表示します。

<?php
echo posix_getuid()."\n"; //10001
echo posix_geteuid()."\n"; //10001
posix_seteuid(10000);
echo posix_getuid()."\n"; //10001
echo posix_geteuid()."\n"; //10000
?>

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • posix_getuid() - 現在のプロセスの実際のユーザー ID を返す
  • posix_setuid() - 現在のプロセスの UID を設定する
  • POSIX man ページ GETEUID(2)


現在のプロセスの実際のグループ ID を返す

  • ≪ posix_geteuid
  • posix_getgrgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実際のグループ ID を返す

posix_getgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgid — 現在のプロセスの実際のグループ ID を返す

説明

posix_getgid(): int

現在のプロセスの実際のグループ ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

実際のグループ ID を表す整数値を返します。

例

例1 posix_getgid() の例

この例では、実グループ ID を表示し、 実効グループ ID を変更した後で再度実グループ ID を表示します。 have changed your effective group id.

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setegid(40);
echo '実グループ ID は '.posix_getgid(); //20
echo '実効グループ ID は '.posix_getegid(); //40
?>

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getegid() - 現在のプロセスの有効なグループ ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する
  • POSIX man ページ GETGID(2)


指定したグループ ID を有するグループに関する情報を返す

  • ≪ posix_getgid
  • posix_getgrnam ≫
  • PHP Manual
  • POSIX 関数
  • 指定したグループ ID を有するグループに関する情報を返す

posix_getgrgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgrgid — 指定したグループ ID を有するグループに関する情報を返す

説明

posix_getgrgid(int $group_id): array|false

指定した ID のグループに関する情報を取得します。

パラメータ

group_id

グループ ID。

戻り値

以下の要素を持つ配列を返します。

グループ情報の配列
要素 | 説明
name | グループ名。これは、16 文字以下の短い文字列からなる 「ハンドル」であり、実際の完全な名前とは異なります。
passwd | グループのパスワードを暗号化したもの。 システムが「シャドー」パスワードを使用している場合は、 ここではアスタリスクが返されます。
gid | グループ ID。この関数をコールする際に指定した group_id と同じものになるので、冗長なデータです。
members | このグループに属する全メンバーを表す文字列の配列。
この関数は、失敗時に false を返します。

例

例1 posix_getgrgid() の使用例

<?php

$groupid = posix_getegid();
$groupinfo = posix_getgrgid($groupid);

print_r($groupinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => toons
    [passwd]  => x
    [members] => Array
        (
            [0] => tom
            [1] => jerry
        )
    [gid]     => 42
)

参考

  • posix_getegid() - 現在のプロセスの有効なグループ ID を返す
  • posix_getgrnam() - 指定した名前のグループに関する情報を返す
  • filegroup() - ファイルのグループを取得する
  • stat() - ファイルに関する情報を取得する
  • POSIX man ページ GETGRNAM(3)


指定した名前のグループに関する情報を返す

  • ≪ posix_getgrgid
  • posix_getgroups ≫
  • PHP Manual
  • POSIX 関数
  • 指定した名前のグループに関する情報を返す

posix_getgrnam

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgrnam — 指定した名前のグループに関する情報を返す

説明

posix_getgrnam(string $name): array|false

指定した名前のグループに関する情報を取得します。

パラメータ

name

グループの名前。

戻り値

成功したときは array を返します。失敗した場合に false を返します。 配列で返される要素は下記のとおりです。

グループ情報の配列
要素 | 説明
name | グループ名。これは、16 文字以下の短い文字列からなる 「ハンドル」であり、実際の完全な名前とは異なります。 グループ ID。この関数をコールする際に指定した name と同じものになるので、冗長なデータです。
passwd | グループのパスワードを暗号化したもの。 システムが「シャドー」パスワードを使用している場合は、 ここではアスタリスクが返されます。
gid | グループ ID を表す数値。
members | このグループに属する全メンバーを表す文字列の配列。

例

例1 posix_getgrnam() の使用例

<?php

$groupinfo = posix_getgrnam("toons");

print_r($groupinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => toons
    [passwd]  => x
    [members] => Array
        (
            [0] => tom
            [1] => jerry
        )
    [gid]     => 42
)

参考

  • posix_getegid() - 現在のプロセスの有効なグループ ID を返す
  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • filegroup() - ファイルのグループを取得する
  • stat() - ファイルに関する情報を取得する
  • POSIX man ページ GETGRNAM(3)


現在のプロセスのグループセットを返す

  • ≪ posix_getgrnam
  • posix_getlogin ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスのグループセットを返す

posix_getgroups

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getgroups — 現在のプロセスのグループセットを返す

説明

posix_getgroups(): array|false

現在のプロセスのグループセットを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のプロセスのグループセットについて、 グループ ID を表す整数値を含む配列を返します。 失敗した場合に false を返します

例

例1 posix_getgroups() の使用例

<?php

$groups = posix_getgroups();

print_r($groups);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 4
    [1] => 20
    [2] => 24
    [3] => 25
    [4] => 29
    [5] => 30
    [6] => 33
    [7] => 44
    [8] => 46
    [9] => 104
    [10] => 109
    [11] => 110
    [12] => 1000
)

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す


ログイン名を返す

  • ≪ posix_getgroups
  • posix_getpgid ≫
  • PHP Manual
  • POSIX 関数
  • ログイン名を返す

posix_getlogin

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getlogin — ログイン名を返す

説明

posix_getlogin(): string|false

現在のプロセスを所有するユーザーのログイン名を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ユーザーのログイン名を文字列で返します。 失敗した場合に false を返します

例

例1 posix_getlogin() の使用例

<?php
echo posix_getlogin(); //apache
?>

参考

  • posix_getpwnam() - 指定した名前のユーザーに関する情報を返す
  • POSIX man ページ GETLOGIN(3)


ジョブ制御のプロセスグループ ID を得る

  • ≪ posix_getlogin
  • posix_getpgrp ≫
  • PHP Manual
  • POSIX 関数
  • ジョブ制御のプロセスグループ ID を得る

posix_getpgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpgid — ジョブ制御のプロセスグループ ID を得る

説明

posix_getpgid(int $process_id): int|false

プロセス process_id のプロセスグループ ID を返します。失敗した場合に false を返します。

パラメータ

process_id

プロセス ID。

戻り値

ID を表す整数値を返します。

例

例1 posix_getpgid() の使用例

<?php
$pid = posix_getppid();
echo posix_getpgid($pid); //35
?>

注意

注意:

この関数は POSIX 関数ではなく、BSD および System V のシステムで共通な関数です。 使用するシステムがこの関数をサポートしていない場合は、 PHP のコンパイル時にこの関数は組み込まれません。 この関数が使用可能かどうかを調べるには、function_exists() を使用します。

参考

  • posix_getppid() - 親プロセスの ID を返す
  • man ページ SETPGID(2)


現在のプロセスのグループ ID を返す

  • ≪ posix_getpgid
  • posix_getpid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスのグループ ID を返す

posix_getpgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpgrp — 現在のプロセスのグループ ID を返す

説明

posix_getpgrp(): int

現在のプロセスのグループ ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ID を表す整数値を返します。

参考

  • プロセスグループの詳細な情報に関しては、POSIX.1 および POSIX システムのマニュアルページ getpgrp(2) を参照ください。


現在のプロセス ID を返す

  • ≪ posix_getpgrp
  • posix_getppid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセス ID を返す

posix_getpid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpid — 現在のプロセス ID を返す

説明

posix_getpid(): int

現在のプロセスのプロセス ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ID を表す整数値を返します。

例

例1 posix_getpid() の使用例

<?php
echo posix_getpid(); //8805
?>

参考

  • posix_kill() - プロセスにシグナルを送信する
  • POSIX man ページ GETPID(2)


親プロセスの ID を返す

  • ≪ posix_getpid
  • posix_getpwnam ≫
  • PHP Manual
  • POSIX 関数
  • 親プロセスの ID を返す

posix_getppid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getppid — 親プロセスの ID を返す

説明

posix_getppid(): int

現在のプロセスの親プロセスの ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ID を表す整数値を返します。

例

例1 posix_getppid() の使用例

<?php
echo posix_getppid(); //8259
?>


指定した名前のユーザーに関する情報を返す

  • ≪ posix_getppid
  • posix_getpwuid ≫
  • PHP Manual
  • POSIX 関数
  • 指定した名前のユーザーに関する情報を返す

posix_getpwnam

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpwnam — 指定した名前のユーザーに関する情報を返す

説明

posix_getpwnam(string $username): array|false

指定したユーザーに関する情報を配列で返します。

パラメータ

username

英数字で表したユーザー名。

戻り値

成功した場合は次の要素を持つ配列、それ以外の場合は false を返します。

ユーザー情報配列
要素 | 説明
name | 要素 name はユーザー名を有しています。これは、通常、 実際の完全な名前ではなく16文字未満のユーザーの"ハンドル名"となります。 この値はこの関数をコールした際に使用したパラメータ usernameと同じとする必要があり、 このため冗長な定義となります。
passwd | 要素passwd には暗号化されたユーザーのパスワードが含まれます。 シャドウパスワードを使用しているシステムでは、アスタリスクが代わりに 返されます。
uid | 数値形式で表したユーザー ID。
gid | ユーザーのグループ ID。 実際のグループ名を調べたりそのグループのメンバーの一覧を 得るには関数 posix_getgrgid() を使用してください。
gecos | GECOS は旧式の項であり、Honeywell バッチ処理プログラムの finger 情報フィールドを参照します。 しかし、このフィールドはまだ生きており、その内容はPOSIXで 規定されています。 このフィールドには、カンマで区切られた ユーザーのフルネーム、オフィスの電話番号、家の電話番号に関する リストが含まれています。多くのシステムでは、ユーザーのフルネーム のみが利用可能です。
dir | この要素には、ユーザーのホームディレクトリへの絶対パスが含まれています。
shell | shell 要素には、ユーザーのデフォルトシェルの実行ファイルへの絶対パスが 含まれています。

例

例1 posix_getpwnam() の使用例

<?php

$userinfo = posix_getpwnam("tom");

print_r($userinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => tom
    [passwd]  => x
    [uid]     => 10000
    [gid]     => 42
    [gecos]   => "tom,,,"
    [dir]     => "/home/tom"
    [shell]   => "/bin/bash"
)

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • POSIX man ページ GETPWNAM(3)


指定 ID のユーザーに関する情報を返す

  • ≪ posix_getpwnam
  • posix_getrlimit ≫
  • PHP Manual
  • POSIX 関数
  • 指定 ID のユーザーに関する情報を返す

posix_getpwuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getpwuid — 指定 ID のユーザーに関する情報を返す

説明

posix_getpwuid(int $user_id): array|false

指定したユーザー ID のユーザーについての情報を配列で返します。

パラメータ

user_id

ユーザー ID。

戻り値

返される連想配列の要素は次のようになります。

ユーザー情報配列
要素 | 説明
name | 要素 name はユーザー名を有しています。これは、通常、 実際の完全な名前ではなく16文字未満のユーザーの"ハンドル名"となります。
passwd | 要素passwd には暗号化されたユーザーのパスワードが含まれます。 シャドウパスワードを使用しているシステムでは、アスタリスクが代わりに 返されます。
uid | ユーザーID。これは、この関数をコールする際に使用するパラメータ user_idと同じとなり、このため冗長になります。
gid | ユーザーのグループID。 実際のグループ名を調べたりそのグループのメンバーの一覧を 得るには関数posix_getgrgid()を使用してください。
gecos | GECOS は旧式の項であり、Honeywell バッチ処理プログラムの finger 情報フィールドを参照します。 しかし、このフィールドはまだ生きており、その内容はPOSIXで 規定されています。 このフィールドには、カンマで区切られた ユーザーのフルネーム、オフィスの電話番号、家の電話番号に関する リストが含まれています。多くのシステムでは、ユーザーのフルネーム のみが利用可能です。
dir | この要素には、ユーザーのホームディレクトリへの絶対パスが含まれています。
shell | shell 要素には、ユーザーのデフォルトシェルの実行ファイルへの絶対パスが 含まれています。
この関数は、失敗時に false を返します。

例

例1 posix_getpwuid() の使用例

<?php

$userinfo = posix_getpwuid(10000);

print_r($userinfo);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [name]    => tom
    [passwd]  => x
    [uid]     => 10000
    [gid]     => 42
    [gecos]   => "tom,,,"
    [dir]     => "/home/tom"
    [shell]   => "/bin/bash"
)

参考

  • posix_getpwnam() - 指定した名前のユーザーに関する情報を返す
  • POSIX man ページ GETPWNAM(3)


システムリソース制限に関する情報を返す

  • ≪ posix_getpwuid
  • posix_getsid ≫
  • PHP Manual
  • POSIX 関数
  • システムリソース制限に関する情報を返す

posix_getrlimit

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getrlimit — システムリソース制限に関する情報を返す

説明

posix_getrlimit(?int $resource = null): array|false

posix_getrlimit() は、 現在のリソースにおけるソフトリミットおよびハードリミットを配列で返します。

各リソースには、それぞれソフトリミットとハードリミットがあります。 ソフトリミットとは、そのリソースに対してカーネルが課す制限値のことです。 ハードリミットとは、ソフトリミットの上限値のことです。 特権を持たないプロセスは、ソフトリミットの値を 0 からハードリミット値の間で設定することが可能です。 また、ハードリミットの値を下げることもできます。

パラメータ

resource

null の場合、全てのリソースリミットを取得します。 null でない場合、指定されたリソースタイプのリミットのみを返します。

戻り値

各リソースに関する制限値を含む連想配列を返します。 個々のリミット値には、ソフトリミットとハードリミットがあります。

返される制限の一覧
制限の名前 | 制限についての説明
core | コアファイルの最大サイズ。0 の場合はコアファイルを作成しません。 コアファイルのサイズがこの値を超えると、 このサイズまで切り詰められます。
totalmem | プロセスのメモリの最大サイズを表すバイト数。
virtualmem | プロセスの仮想メモリの最大サイズを表すバイト数。
data | プロセスのデータセグメントの最大サイズを表すバイト数。
stack | プロセスのスタックの最大サイズを表すバイト数。
rss | RAM 上の仮想ページの最大数。
maxproc | 呼び出し元のプロセスの実ユーザー ID で作成できるプロセスの最大数。
memlock | RAM 内にロックできるメモリの最大バイト数。
cpu | そのプロセスが使用できる CPU 時間。
filesize | そのプロセスが使用できるデータセグメントの最大サイズを表すバイト数。
openfiles | オープンできるファイル記述子の最大値よりひとつ大きい値。
この関数は、失敗時に false を返します。

変更履歴

バージョン | 説明
8.3.0 | オプションの resource が追加されました。

例

例1 posix_getrlimit() の使用例

<?php

$limits = posix_getrlimit();

print_r($limits);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [soft core] => 0
    [hard core] => unlimited
    [soft data] => unlimited
    [hard data] => unlimited
    [soft stack] => 8388608
    [hard stack] => unlimited
    [soft totalmem] => unlimited
    [hard totalmem] => unlimited
    [soft rss] => unlimited
    [hard rss] => unlimited
    [soft maxproc] => unlimited
    [hard maxproc] => unlimited
    [soft memlock] => unlimited
    [hard memlock] => unlimited
    [soft cpu] => unlimited
    [hard cpu] => unlimited
    [soft filesize] => unlimited
    [hard filesize] => unlimited
    [soft openfiles] => 1024
    [hard openfiles] => 1024
)

参考

  • man ページ GETRLIMIT(2)
  • posix_setrlimit() - システムリソース制限を設定


プロセスの現在の sid を得る

  • ≪ posix_getrlimit
  • posix_getuid ≫
  • PHP Manual
  • POSIX 関数
  • プロセスの現在の sid を得る

posix_getsid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getsid — プロセスの現在の sid を得る

説明

posix_getsid(int $process_id): int|false

プロセス process_id のセッション ID を返します。 プロセスのセッション ID とは、セッションリーダーのプロセスグループ ID のことです。

パラメータ

process_id

プロセス ID。0 を指定すると、現在のプロセスとみなされます。 不正な process_id を指定すると、 false が返され、 posix_get_last_error() でチェックできるエラー情報が設定されます。

戻り値

ID を表す整数値を返します。 失敗した場合に false を返します

例

例1 posix_getsid() の使用例

<?php
$pid = posix_getpid();
echo posix_getsid($pid); //8805
?>

参考

  • posix_getpgid() - ジョブ制御のプロセスグループ ID を得る
  • posix_setsid() - 現在のプロセスをセッションリーダーにする
  • POSIX man ページ GETSID(2)


現在のプロセスの実際のユーザー ID を返す

  • ≪ posix_getsid
  • posix_initgroups ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実際のユーザー ID を返す

posix_getuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_getuid — 現在のプロセスの実際のユーザー ID を返す

説明

posix_getuid(): int

現在のプロセスの実際のユーザー ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ID を表す整数値を返します。

例

例1 posix_getuid() の使用例

<?php
echo posix_getuid(); //10000
?>

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • POSIX man ページ GETUID(2)


グループアクセスリストを求める

  • ≪ posix_getuid
  • posix_isatty ≫
  • PHP Manual
  • POSIX 関数
  • グループアクセスリストを求める

posix_initgroups

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

posix_initgroups — グループアクセスリストを求める

説明

posix_initgroups(string $username, int $group_id): bool

指定した名前のユーザーについてのグループアクセスリストを求めます。

パラメータ

username

リストを取得したいユーザー。

group_id

パスワードファイルから取得したグループ番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Unix の initgroups(3) のマニュアル


ファイル記述子が対話型端末であるかどうかを定義する

  • ≪ posix_initgroups
  • posix_kill ≫
  • PHP Manual
  • POSIX 関数
  • ファイル記述子が対話型端末であるかどうかを定義する

posix_isatty

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_isatty — ファイル記述子が対話型端末であるかどうかを定義する

説明

posix_isatty(resource|int $file_descriptor): bool

ファイル記述子 file_descriptor が、 有効な端末デバイスを指しているかどうかを調べます。

パラメータ

file_descriptor

ファイル記述子。ファイルリソースか、あるいは int で指定します。 int を指定した場合は、システムコールにそのまま渡せるファイル記述子だとみなします。

戻り値

file_descriptor がオープンされており、 かつ端末に接続されている場合に true、 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | 通常の PHP の型変換のセマンティクスに従い、 整数を変換した場合に、型のエラーに関する E_WARNING が発生するようになりました。

参考

  • posix_ttyname() - 端末のデバイス名を調べる
  • stream_isatty() - ストリームがターミナル型のデバイスかを調べる


プロセスにシグナルを送信する

  • ≪ posix_isatty
  • posix_mkfifo ≫
  • PHP Manual
  • POSIX 関数
  • プロセスにシグナルを送信する

posix_kill

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_kill — プロセスにシグナルを送信する

説明

posix_kill(int $process_id, int $signal): bool

シグナル signal をプロセス ID process_id のプロセスに送信します。

パラメータ

process_id

プロセス ID。

signal

PCNTL シグナル定数 のいずれか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • POSIX システムの kill(2) マニュアルページも参照ください。 そこには、負のプロセスID、特別プロセスID 0、特別プロセスID -1、 シグナル番号 0 に関する追加情報があります。


fifo スペシャルファイル(名前付きパイプ)を作成する

  • ≪ posix_kill
  • posix_mknod ≫
  • PHP Manual
  • POSIX 関数
  • fifo スペシャルファイル(名前付きパイプ)を作成する

posix_mkfifo

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_mkfifo — fifo スペシャルファイル(名前付きパイプ)を作成する

説明

posix_mkfifo(string $filename, int $permissions): bool

posix_mkfifo() は、 FIFO スペシャルファイルを作成します。 これはファイルシステム内に存在し、プロセス間の双方向通信の末端として 動作します。

パラメータ

filename

FIFO ファイルへのパス。

permissions

2 番目のパラメータ permissions は、8 進表記 (例: 0644)で指定する必要があります。新しく作成される FIFO のパーミッションは、現在の umask() の設定にも依存します。 作成されるファイルのパーミッションは (mode & ~umask) となります。

戻り値

成功した場合に true を、失敗した場合に false を返します。


スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)

  • ≪ posix_mkfifo
  • posix_pathconf ≫
  • PHP Manual
  • POSIX 関数
  • スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)

posix_mknod

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

posix_mknod — スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)

説明

posix_mknod(
string $filename,
int $flags,
int $major = 0,
int $minor = 0
): bool

スペシャルファイルあるいは通常のファイルを作成します。

パラメータ

filename

作成するファイル。

flags

このパラメータは、ファイル型(以下の定数 POSIX_S_IFREG、 POSIX_S_IFCHR、POSIX_S_IFBLK、 POSIX_S_IFIFO あるいは POSIX_S_IFSOCK のうちのひとつ) およびパーミッションの論理和で構成されます。

major

メジャーデバイスカーネル ID (S_IFCHR あるいは S_IFBLK を使用している場合に渡す必要があります)。

minor

マイナーデバイスカーネル ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_mknod() の例

<?php

$file = '/tmp/tmpfile'; // ファイル名
$type = POSIX_S_IFBLK; // ファイル型
$permissions = 0777; // 8 進数
$major = 1;
$minor = 8; // /dev/random

if (!posix_mknod($file, $type | $permissions, $major, $minor)) {
die('Error ' . posix_get_last_error() . ': ' . posix_strerror(posix_get_last_error()));
}

?>

参考

  • posix_mkfifo() - fifo スペシャルファイル(名前付きパイプ)を作成する


設定可能なリミットの値を返す

  • ≪ posix_mknod
  • posix_setegid ≫
  • PHP Manual
  • POSIX 関数
  • 設定可能なリミットの値を返す

posix_pathconf

(PHP 8 >= 8.3.0)

posix_pathconf — 設定可能なリミットの値を返す

説明

posix_pathconf(string $path, int $name): int|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

file の name から、設定可能なリミットの値を返します。

パラメータ

path

リミットを取得したいファイル名

name

設定可能なリミットの名前。 以下のうちの一つを指定します。 POSIX_PC_LINK_MAX, POSIX_PC_MAX_CANON POSIX_PC_MAX_INPUT, POSIX_PC_NAME_MAX POSIX_PC_PATH_MAX, POSIX_PC_PIPE_BUF POSIX_PC_CHOWN_RESTRICTED, POSIX_PC_NO_TRUNC POSIX_PC_ALLOC_SIZE_MIN, POSIX_PC_SYMLINK_MAX

戻り値

設定可能なリミットの値、または false を返します。

エラー / 例外

path が空の場合、 ValueError をスローします。

例

例1 posix_pathconf() の例

このサンプルは、一時ディレクトリのパス名の長さの最大値をバイト単位で返します。

<?php
echo posix_pathconf(sys_get_temp_dir(), POSIX_PC_PATH_MAX);
?>

上の例の出力は以下となります。

4096

参考

  • posix_fpathconf() - 設定可能なリミットの値を返す


現在のプロセスの実効 GID を設定する

  • ≪ posix_pathconf
  • posix_seteuid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実効 GID を設定する

posix_setegid

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

posix_setegid — 現在のプロセスの実効 GID を設定する

説明

posix_setegid(int $group_id): bool

現在のプロセスの実効グループ ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。

パラメータ

group_id

グループ ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_setegid() の例

この例では、まず実効グループ ID を変更してから、それを表示します。

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setegid(40);
echo '実グループ ID は '.posix_getgid(); //20
echo '実効グループ ID は '.posix_getegid(); //40
?>

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgid() - 現在のプロセスの実際のグループ ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する


現在のプロセスの実効 UID を設定する

  • ≪ posix_setegid
  • posix_setgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの実効 UID を設定する

posix_seteuid

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

posix_seteuid — 現在のプロセスの実効 UID を設定する

説明

posix_seteuid(int $user_id): bool

現在のプロセスの実効ユーザー ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。

パラメータ

user_id

ユーザー ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • posix_geteuid() - 現在のプロセスの有効なユーザー ID を返す
  • posix_setgid() - 現在のプロセスの GID を設定する
  • posix_getuid() - 現在のプロセスの実際のユーザー ID を返す


現在のプロセスの GID を設定する

  • ≪ posix_seteuid
  • posix_setpgid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの GID を設定する

posix_setgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setgid — 現在のプロセスの GID を設定する

説明

posix_setgid(int $group_id): bool

現在のプロセスのグループ ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。 posix_setgid() を最初に、 posix_setuid() を最後にコールするのが、 関数コールの正しい順序となります。

注意:

コール元がスーバーユーザーの場合は、実効グループ ID も設定します。

パラメータ

group_id

グループ ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_setgid() の例

この例は、いったん変更した後で実効グループ ID を表示します。

<?php
echo '実グループ ID は '.posix_getgid(); //20
posix_setgid(40);
echo '実グループ ID は '.posix_getgid(); //40
echo '実効グループ ID は '.posix_getegid(); //40
?>

参考

  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す
  • posix_getgid() - 現在のプロセスの実際のグループ ID を返す


ジョブ制御のプロセスグループ ID を設定する

  • ≪ posix_setgid
  • posix_setrlimit ≫
  • PHP Manual
  • POSIX 関数
  • ジョブ制御のプロセスグループ ID を設定する

posix_setpgid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setpgid — ジョブ制御のプロセスグループ ID を設定する

説明

posix_setpgid(int $process_id, int $process_group_id): bool

プロセス process_id をプロセスグループ process_group_id に加えます。

パラメータ

process_id

プロセス ID。

process_group_id

プロセスグループ ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • プロセスグループおよびジョブ制御に関する詳細は、 POSIX.1 および POSIX システムのマニュアルページ setsid(2) を参照ください。


システムリソース制限を設定

  • ≪ posix_setpgid
  • posix_setsid ≫
  • PHP Manual
  • POSIX 関数
  • システムリソース制限を設定

posix_setrlimit

(PHP 7, PHP 8)

posix_setrlimit — システムリソース制限を設定

説明

posix_setrlimit(int $resource, int $soft_limit, int $hard_limit): bool

posix_setrlimit() は、 指定されたシステムリソースに対してソフトリミットおよびハードリミットを設定します。

各リソースには、それぞれソフトリミットとハードリミットがあります。 ソフトリミットとは、そのリソースに対してカーネルが課す制限値のことです。 ハードリミットとは、ソフトリミットの上限値のことです。 特権を持たないプロセスは、ソフトリミットの値を 0 からハードリミット値の間で設定することが可能です。 また、ハードリミットの値を下げることもできます。

パラメータ

resource

設定されるリミットに対応するリソースリミット定数です。

soft_limit

ソフトリミット、単位は、リソース制限が必要とする任意の単位です。または、 POSIX_RLIMIT_INFINITY です。

hard_limit

ハードリミット、単位は、リソース制限が必要とする任意の単位です。または、 POSIX_RLIMIT_INFINITY です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • man ページ SETRLIMIT(2)
  • posix_getrlimit() - システムリソース制限に関する情報を返す


現在のプロセスをセッションリーダーにする

  • ≪ posix_setrlimit
  • posix_setuid ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスをセッションリーダーにする

posix_setsid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setsid — 現在のプロセスをセッションリーダーにする

説明

posix_setsid(): int

現在のプロセスをセッションリーダーにします。

パラメータ

この関数にはパラメータはありません。

戻り値

セッション ID、あるいはエラー時に -1 を返します。

参考

  • プロセスグループおよびジョブ制御に関する詳細は、 POSIX.1 および POSIX システムのマニュアルページ setsid(2) を参照ください。


現在のプロセスの UID を設定する

  • ≪ posix_setsid
  • posix_strerror ≫
  • PHP Manual
  • POSIX 関数
  • 現在のプロセスの UID を設定する

posix_setuid

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_setuid — 現在のプロセスの UID を設定する

説明

posix_setuid(int $user_id): bool

現在のプロセスの実際のユーザー ID を設定します。 この関数は特権関数であり、実行するにはシステム上において適当な権限 (通常は root) が必要です。

パラメータ

user_id

ユーザー ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 posix_setuid() の例

この例は、現在のユーザー ID を表示し、それを別のものに変更します。

<?php
echo posix_getuid()."\n"; //10001
echo posix_geteuid()."\n"; //10001
posix_setuid(10000);
echo posix_getuid()."\n"; //10000
echo posix_geteuid()."\n"; //10000
?>

参考

  • posix_setgid() - 現在のプロセスの GID を設定する
  • posix_seteuid() - 現在のプロセスの実効 UID を設定する
  • posix_getuid() - 現在のプロセスの実際のユーザー ID を返す
  • posix_geteuid() - 現在のプロセスの有効なユーザー ID を返す


指定したエラー番号に対応するシステムのエラーメッセージを取得する

  • ≪ posix_setuid
  • posix_sysconf ≫
  • PHP Manual
  • POSIX 関数
  • 指定したエラー番号に対応するシステムのエラーメッセージを取得する

posix_strerror

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

posix_strerror — 指定したエラー番号に対応するシステムのエラーメッセージを取得する

説明

posix_strerror(int $error_code): string

指定したエラー番号 error_code に対応する POSIX システムエラーメッセージを返します。 error_code を取得するには、 posix_get_last_error() をコールします。

パラメータ

error_code

posix_get_last_error() が返す POSIX エラー番号。0 に設定すると、文字列 "Success" が返されます。

戻り値

エラーメッセージを表す文字列を返します。

例

例1 posix_strerror() の例

この例では、存在しないプロセスを殺そうとしています。 そして、その結果として発生したエラーに対応するメッセージを表示します。

<?php
posix_kill(50,SIGKILL);
echo posix_strerror(posix_get_last_error())."\n";
?>

上の例の出力は、 たとえば以下のようになります。

No such process

参考

  • posix_get_last_error() - 直近で失敗した posix 関数が設定したエラー番号を取得する


システムの実行時情報を返す

  • ≪ posix_strerror
  • posix_times ≫
  • PHP Manual
  • POSIX 関数
  • システムの実行時情報を返す

posix_sysconf

(PHP 8 >= 8.3.0)

posix_sysconf — システムの実行時情報を返す

説明

posix_sysconf(int $conf_id): int

システムの実行時情報を返します。

パラメータ

conf_id

値の識別子を、以下の定数で指定します。 POSIX_SC_ARG_MAX, POSIX_SC_PAGESIZE POSIX_SC_NPROCESSORS_CONF, POSIX_SC_NPROCESSORS_ONLN

戻り値

conf_id に関連する数値の値を返します。

例

例1 posix_sysconf() の例

アクティブなCPUの数を返します。

<?php
echo posix_sysconf(POSIX_SC_NPROCESSORS_ONLN);
?>

上の例の出力は以下となります。

2


プロセス時間を得る

  • ≪ posix_sysconf
  • posix_ttyname ≫
  • PHP Manual
  • POSIX 関数
  • プロセス時間を得る

posix_times

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_times — プロセス時間を得る

説明

posix_times(): array|false

現在の CPU 使用状況についての情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のプロセスの CPU 使用状況に関する情報を表す文字列を連想配列 として返します。連想配列のキーは次のようになります。

  • ticks - リブートからの経過クロック数。
  • utime - 現在のプロセスにより使用されているユーザー時間。
  • stime - 現在のプロセスにより使用されているシステム時間。
  • cutime - 現在のプロセスおよび子プロセスにより使用されているユーザー時間。
  • cstime - 現在のプロセスおよび子プロセスにより使用されているシステム時間。
この関数は、失敗時に false を返します。

例

例1 posix_times() の使用例

<?php

$times = posix_times();

print_r($times);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [ticks] => 25814410
    [utime] => 1
    [stime] => 1
    [cutime] => 0
    [cstime] => 0
)

注意

警告

この関数の返す値は信頼できません。 時間が大きくなると負の値を返すこともあります。


端末のデバイス名を調べる

  • ≪ posix_times
  • posix_uname ≫
  • PHP Manual
  • POSIX 関数
  • 端末のデバイス名を調べる

posix_ttyname

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_ttyname — 端末のデバイス名を調べる

説明

posix_ttyname(resource|int $file_descriptor): string|false

ファイル記述子 file_descriptor 上でオープンしている現在の端末デバイスへの絶対パスを文字列で返します。

パラメータ

file_descriptor

ファイル記述子。ファイルリソースか、あるいは int で指定します。 int を指定した場合は、システムコールにそのまま渡せるファイル記述子だとみなします。

戻り値

成功した場合に file_descriptor の絶対パスを表す文字列、 失敗した場合に false を返します。

エラー / 例外

file_descriptor が無効な整数値の場合、 E_WARNING が発生します。

変更履歴

バージョン | 説明
8.3.0 | 通常の PHP の型変換のセマンティクスに従い、 整数を変換した場合に、型のエラーに関する E_WARNING が発生するようになりました。
8.3.0 | file_descriptor が無効な整数値の場合に、 E_WARNING が発生するようになりました。

参考

  • posix_isatty() - ファイル記述子が対話型端末であるかどうかを定義する
  • stream_isatty() - ストリームがターミナル型のデバイスかを調べる


システム名を得る

  • ≪ posix_ttyname
  • プログラムの実行 ≫
  • PHP Manual
  • POSIX 関数
  • システム名を得る

posix_uname

(PHP 4, PHP 5, PHP 7, PHP 8)

posix_uname — システム名を得る

説明

posix_uname(): array|false

システムについての情報を取得します。

POSIX では、値のフォーマットに関して何の仮定も設けないことを規定しています。 例えば、バージョン番号が 3 桁の数字であることや、 この関数により返されるその他のものに依存してはいけません。

パラメータ

この関数にはパラメータはありません。

戻り値

システムに関する情報を文字列の連想配列として返します。 連想配列のキーは、次のようになります。

  • sysname - オペレーティングシステムの名前 (例 Linux)
  • nodename - システムの名前 (例 valiant)
  • release - オペレーティングシステムのリリース (例 2.2.10)
  • version - オペレーティングシステムのバージョン (例 #4 Tue Jul 20 17:01:36 MEST 1999)
  • machine - システムアーキテクチャ (例 i586)
  • domainname - DNS ドメイン名 (例 example.com)

domainname は、GNU の拡張機能で POSIX.1 には含まれていません。 このため、このフィールドは GNU システム上または GNU libc を使用している場合にのみ使用可能です。

この関数は、失敗時に false を返します。

例

例1 posix_uname() の使用例

<?php
$uname=posix_uname();
print_r($uname);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [sysname] => Linux
    [nodename] => funbox
    [release] => 2.6.20-15-server
    [version] => #2 SMP Sun Apr 15 07:41:34 UTC 2007
    [machine] => i686
)


システムプログラムの実行

  • はじめに
  • インストール/設定
    • リソース型
  • プログラム実行関数
    • escapeshellarg — シェル引数として使用される文字列をエスケープする
    • escapeshellcmd — シェルのメタ文字をエスケープする
    • exec — 外部プログラムを実行する
    • passthru — 外部プログラムを実行し、未整形の出力を表示する
    • proc_close — proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
    • proc_get_status — proc_open で開かれたプロセスに関する情報を取得する
    • proc_nice — 現在のプロセスの優先度を変更する
    • proc_open — コマンドを実行し、入出力用にファイルポインタを開く
    • proc_terminate — proc_open でオープンされたプロセスを強制終了する
    • shell_exec — シェルによりコマンドを実行し、文字列として出力全体を返す
    • system — 外部プログラムを実行し、出力を表示する


はじめに

以下の関数は、システム自体の上でコマンドを実行したり、 こうしたコマンドを安全に実行する手段を提供します。

注意:

これらの関数は、Windows ではすべて cmd.exe 経由でコマンドをコールします。 そのため、これらの関数をコールするユーザーが適切なコマンド実行権限を持っていなければなりません。 唯一の例外は、proc_open() を bypass_shell オプションつきでコールする場合です。


  • ≪ はじめに
  • リソース型 ≫
  • PHP Manual
  • プログラムの実行
  • インストール/設定

インストール/設定

目次

  • リソース型


  • ≪ インストール/設定
  • プログラム実行関数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型

この拡張モジュールが定義するリソースは process リソースで、これは proc_open() が返します。


プログラム実行関数

注意

警告

ロックしてオープンしたファイル (特に、オープンしたセッション) は、プログラムをバックグラウンドで実行する前に閉じておく必要があります。

参考

以下の関数は、 バッククォート演算子 にも関係します。

目次

  • escapeshellarg — シェル引数として使用される文字列をエスケープする
  • escapeshellcmd — シェルのメタ文字をエスケープする
  • exec — 外部プログラムを実行する
  • passthru — 外部プログラムを実行し、未整形の出力を表示する
  • proc_close — proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
  • proc_get_status — proc_open で開かれたプロセスに関する情報を取得する
  • proc_nice — 現在のプロセスの優先度を変更する
  • proc_open — コマンドを実行し、入出力用にファイルポインタを開く
  • proc_terminate — proc_open でオープンされたプロセスを強制終了する
  • shell_exec — シェルによりコマンドを実行し、文字列として出力全体を返す
  • system — 外部プログラムを実行し、出力を表示する


シェル引数として使用される文字列をエスケープする

  • ≪ プログラム実行関数
  • escapeshellcmd ≫
  • PHP Manual
  • プログラム実行関数
  • シェル引数として使用される文字列をエスケープする

escapeshellarg

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

escapeshellarg — シェル引数として使用される文字列をエスケープする

説明

escapeshellarg(string $arg): string

escapeshellarg() は、文字列をシングルクオート で括り、既存のシングルクオートを全てクオート/エスケープします。こ れにより、文字列を直接シェル関数に渡し、単一の安全な引数として処 理することを可能にします。この関数は、ユーザー入力からの入力を シェル関数への引数として渡す際にエスケープするために使用する必要 があります。シェル関数には、exec(), system()そして バッククォート演算子 を含むシェル関数が含まれます。

Windows では、escapeshellarg() は、パーセント記号と感嘆符 (遅延環境変数の展開) とダブルクォートをスペースに置き換えます。 そして、文字列をダブルクォートで囲みます。 さらに、連続するバックスラッシュ(\) は、もうひとつバックスラッシュを追加すればエスケープできます。

パラメータ

arg

エスケープされる引数

戻り値

エスケープされた文字列

例

例1 escapeshellarg() の例

<?php
system('ls '.escapeshellarg($dir));
?>

参考

  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • exec() - 外部プログラムを実行する
  • popen() - プロセスへのファイルポインタをオープンする
  • system() - 外部プログラムを実行し、出力を表示する
  • バッククォート演算子


シェルのメタ文字をエスケープする

  • ≪ escapeshellarg
  • exec ≫
  • PHP Manual
  • プログラム実行関数
  • シェルのメタ文字をエスケープする

escapeshellcmd

(PHP 4, PHP 5, PHP 7, PHP 8)

escapeshellcmd — シェルのメタ文字をエスケープする

説明

escapeshellcmd(string $command): string

escapeshellcmd() は、文字列中においてシェルコマンドを だまして勝手なコマンドを実行する可能性がある文字をエスケープします。 この関数は、ユーザーに入力されたデータを関数 exec() または system() または、 バッククォート演算子 に渡す前に全てエスケープを行う場合に使用するべきです。

&#;`|*?~<>^()[]{}$\、\x0A および \xFF については、その文字の前にバックスラッシュが 追加されます。' および " は、対になっていない場合にのみエスケープされます。 Windows では、 これらの文字に加えて % と ! の前にキャレット (^) が付加されます。

パラメータ

command

エスケープされるコマンド

戻り値

エスケープされた文字列

例

例1 escapeshellcmd() の例

<?php
// 意図的に、任意の数の引数を指定できるようにしています
$command = './configure '.$_POST['configure_options'];

$escaped_command = escapeshellcmd($command);

system($escaped_command);
?>

注意

警告

escapeshellcmd() はコマンド文字列全体に適用しなければなりません。 また、そうしたところで、まだ任意の数の引数を渡すことによる攻撃を許してしまいます。 単一の引数をエスケープするには、かわりに escapeshellarg() を使わねばなりません。

警告

スペースは escapeshellcmd() 関数ではエスケープされません。 たとえば、Windows で問題になりがちな C:\Program Files\ProgramName\program.exe のようなパスが当てはまります。 この問題は以下のようなコードで緩和できます:

<?php
$cmd = preg_replace('`(?<!^) `', '^ ', escapeshellcmd($cmd));

参考

  • escapeshellarg() - シェル引数として使用される文字列をエスケープする
  • exec() - 外部プログラムを実行する
  • popen() - プロセスへのファイルポインタをオープンする
  • system() - 外部プログラムを実行し、出力を表示する
  • バッククォート演算子


外部プログラムを実行する

  • ≪ escapeshellcmd
  • passthru ≫
  • PHP Manual
  • プログラム実行関数
  • 外部プログラムを実行する

exec

(PHP 4, PHP 5, PHP 7, PHP 8)

exec — 外部プログラムを実行する

説明

exec(string $command, array &$output = null, int &$result_code = null): string|false

exec() は指定されたコマンド command を実行します。

パラメータ

command

実行するコマンド

output

引数 output が存在する場合、指定した配列は、 コマンドからの出力の各行で埋められます。 \n のような後に続く空白は、この配列には含まれません。 配列に既に何らかの要素が 含まれる場合は、exec() は配列の最後に追加される ことに注意してください。関数が要素を追加することを望まないのなら、 それが exec() に渡される前に、配列の unset() を呼び出してください。

result_code

引数result_codeが、引数 output と共に存在する場合、実行したコマンドの ステータスがこの変数に書かれます。

戻り値

コマンド結果の最後の行を返します。コマンドを実行し、 一切干渉を受けずに直接コマンドから全てのデータを受けとる必要が あるならば、passthru() 関数を使ってください。

失敗時に false を返します。

実行されたコマンドの出力を取得するには、必ず output パラメータを設定・使用してください。

エラー / 例外

exec() が command を実行できない場合、E_WARNING が発生します。

command が空だったり、null バイトが含まれている場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | command が空だったり、null バイトが含まれている場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、false を返していました。

例

例1 exec() の例

<?php
// ("whoami" コマンドをパスに有するシステム上で)
// 実行中のphp/httpdプロセスを所有するユーザーの名前を出力
$output=null;
$retval=null;
exec('whoami', $output, $retval);
echo "Returned with status $retval and output:\n";
print_r($output);
?>

上の例の出力は、 たとえば以下のようになります。

Returned with status 0 and output:
Array
(
    [0] => cmb
)

注意

警告

ユーザーが入力したデータをこの関数に 渡すことを許可する場合、ユーザーが任意のコマンドを実行できるようシステムを欺くことが できないように escapeshellarg() または escapeshellcmd() を適用する必要があります。

注意:

プログラムがこの関数で始まる場合、 バックグラウンドで処理を続けさせるには、 プログラムの出力をファイルや別の出力ストリームにリダイレクトする必要があります。 そうしないと、プログラムが実行を終えるまで PHP はハングしてしまいます。

注意:

Windowsでは、exec() 関数はコマンドを起動するために最初に cmd.exe を起動します。cmd.exe を起動せずに外部プログラムを起動したい場合は、proc_open() 関数を bypass_shell オプションを指定して使うようにしてください。

参考

  • system() - 外部プログラムを実行し、出力を表示する
  • passthru() - 外部プログラムを実行し、未整形の出力を表示する
  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • pcntl_exec() - 現在のプロセス空間で指定したプログラムを実行する
  • バッククォート演算子


外部プログラムを実行し、未整形の出力を表示する

  • ≪ exec
  • proc_close ≫
  • PHP Manual
  • プログラム実行関数
  • 外部プログラムを実行し、未整形の出力を表示する

passthru

(PHP 4, PHP 5, PHP 7, PHP 8)

passthru — 外部プログラムを実行し、未整形の出力を表示する

説明

passthru(string $command, int &$result_code = null): ?false

passthru()関数はexec()関数と同様、 commandを実行します。 引数 return_code を指定した場合、 Unix コマンドのステータスで置換されます。 この関数は Unix コマンドからの出力がバイナリデータであり、 ブラウザーへ直接返す必要がある場合、exec() もしくはsystem()の代わりに使用する必要があります。 よく使うのは、直接画像ストリームを出力することができる pbmplus ユーティリティの様なものを実行する場合です。content-type を image/gif に設定して、gifを出力するpbmplus プログラムを呼び出すことにより、直接画像を出力する PHP スクリプトを作成 することができます。

パラメータ

command

実行するコマンド

result_code

引数result_codeが存在する場合、 Unix コマンドのステータスがこの変数に書かれます。

戻り値

成功した場合に null を、失敗した場合に false を返します.

エラー / 例外

passthru() が command を実行できない場合、E_WARNING が発生します。

command が空だったり、null バイトが含まれている場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | command が空だったり、null バイトが含まれている場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、false を返していました。

注意

警告

ユーザーが入力したデータをこの関数に 渡すことを許可する場合、ユーザーが任意のコマンドを実行できるようシステムを欺くことが できないように escapeshellarg() または escapeshellcmd() を適用する必要があります。

注意:

プログラムがこの関数で始まる場合、 バックグラウンドで処理を続けさせるには、 プログラムの出力をファイルや別の出力ストリームにリダイレクトする必要があります。 そうしないと、プログラムが実行を終えるまで PHP はハングしてしまいます。

参考

  • exec() - 外部プログラムを実行する
  • system() - 外部プログラムを実行し、出力を表示する
  • popen() - プロセスへのファイルポインタをオープンする
  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • バッククォート演算子


proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す

  • ≪ passthru
  • proc_get_status ≫
  • PHP Manual
  • プログラム実行関数
  • proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す

proc_close

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

proc_close — proc_open() で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す

説明

proc_close(resource $process): int

proc_close() は pclose() と似ていますが、proc_open() で開かれたプロセスに対してのみ機能するという点で異なります。 proc_close() は、プロセスが終了するまで待った後で、 終了コードを返します。もし、そのプロセスに対してパイプが開かれていた場合は、 デッドロックを避けるため、この関数が呼び出された時点でそのパイプは閉じられます - パイプが開いている間、子プロセスは終了できないからです。

パラメータ

process

閉じられる proc_open() リソース

戻り値

実行していたプロセスの終了状態を返します。 エラーが発生した場合は -1 を返します。

注意:

PHP のコンパイル時に --enable-sigchild を指定した場合は、この関数の返り値は未定義となります。


proc_open で開かれたプロセスに関する情報を取得する

  • ≪ proc_close
  • proc_nice ≫
  • PHP Manual
  • プログラム実行関数
  • proc_open で開かれたプロセスに関する情報を取得する

proc_get_status

(PHP 5, PHP 7, PHP 8)

proc_get_status — proc_open() で開かれたプロセスに関する情報を取得する

説明

proc_get_status(resource $process): array

proc_get_status() は、proc_open() で開かれたプロセスに関する情報を取得します。

パラメータ

process

評価される proc_open() リソース

戻り値

集められた情報の 配列 を返します。 返される配列は次のような要素を持ちます:

要素 | 型 | 説明
command | string | proc_open() に指定されたコマンド文字列。
pid | int | プロセス ID
running | bool | もしプロセスがまだ動いている場合は、true 、すでに終了している場合は false。
signaled | bool | 子プロセスが、キャッチされていないシグナルにより終了した場合に true となります。Windows では常に false にセットされます。
stopped | bool | 子プロセスが、シグナルにより停止した時に true となります。 Windows では常に false にセットされます。
exitcode | int | プロセスが返した終了コード (running が false の時のみ意味を持ちます)。 正しい値を返すのは関数を最初にコールした時のみで、次に コールした際には -1 を返します。
termsig | int | プロセスを終了させたシグナルの番号です (signaled が true の時のみ意味を持ちます)。
stopsig | int | プロセスを停止させたシグナルの番号です (stopped が true の時のみ意味を持ちます)。

参考

  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く


現在のプロセスの優先度を変更する

  • ≪ proc_get_status
  • proc_open ≫
  • PHP Manual
  • プログラム実行関数
  • 現在のプロセスの優先度を変更する

proc_nice

(PHP 5, PHP 7, PHP 8)

proc_nice — 現在のプロセスの優先度を変更する

説明

proc_nice(int $priority): bool

proc_nice() は、現在のプロセスの優先度を priority で指定された値に変更します。 priority が正数の場合、 現在のプロセスの優先度をより低くし、priority が負数の場合は優先度が上がります。

proc_nice() は、proc_open() やそれに関連する関数とは関係ありません。

パラメータ

priority

新しい優先度の値。この値はプラットフォームによっては異なるかもしれません。

Unix 上では、-20 のように低い値が高い優先度である一方で、 正の値は低い優先度として扱われます。

Windows では、 priority パラメータは次のような意味があります:

優先度クラス | 取りうる値
優先度高 | priority < -9
通常より高い優先度 | priority < -4
通常の優先度 | priority < 5 & priority > -5
通常より低い優先度 | priority > 5
アイドルな優先度 | priority > 9

戻り値

成功した場合に true を、失敗した場合に false を返します。 ユーザーが優先度を変更する権限を持っていないなど、 エラーが発生した場合は E_WARNING レベルのエラーも発行されます。

変更履歴

バージョン | 説明
7.2.0 | この関数は、Windows で利用できるようになりました。

例

例1 proc_nice() 関数を使い、プロセスの優先度を高に設定する

<?php
// Highest priority
proc_nice(-20);
?>

注意

注意: 可用性

proc_nice() は、使用しているシステムが 'nice' の機能を持っている場合のみ利用可能です。 'nice' は次のシステムに準拠しています: SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3 。

注意: Windows のみ

proc_nice() 関数は、 PHP がたとえスレッドセーフを有効にしてコンパイルされていたとしても、 現在の プロセス の優先度を変更します。

参考

  • pcntl_setpriority() - プロセスの優先度を変更する


コマンドを実行し、入出力用にファイルポインタを開く

  • ≪ proc_nice
  • proc_terminate ≫
  • PHP Manual
  • プログラム実行関数
  • コマンドを実行し、入出力用にファイルポインタを開く

proc_open

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

proc_open — コマンドを実行し、入出力用にファイルポインタを開く

説明

proc_open(
array|string $command,
array $descriptor_spec,
array &$pipes,
?string $cwd = null,
?array $env_vars = null,
?array $options = null
): resource|false

proc_open() は popen() と よく似ていますが、プログラムの実行をさらに細かく制御できる点で違います。

パラメータ

command

実行するコマンドラインを string として渡します。 特殊な文字は適切にエスケープされ、適切にクォートされます。

注意: Windows では、 options の bypass_shell を true に設定しないと、 cmd.exe (実際は%ComSpec%) に command の値を クォートしないまま (つまり、proc_open() に渡されたそのままの値を) /c と一緒に渡してしまいます。 この振る舞いによって、cmd.exe が command からクォートを削除してしまうため、 (詳細は cmd.exe のドキュメントを参照ください) 予期しない、潜在的に危険とさえ言える結果になります。なぜなら、 cmd.exe のエラーメッセージには、 渡された command (の一部) が含まれる可能性があるからです(下の例を見てください)。

PHP 7.4.0 以降、command にはコマンドの引数も含めた array を渡せるようになりました。 この場合、プロセスは直接(シェルを介さずに)オープンされ、PHP が必要な引数のエスケープを全て行います。

注意:

Windows では、array で渡されるコマンドライン引数のエスケープは、 コマンドライン引数の解釈が VCランタイムによって行われるものと互換性があることを前提にして行われます。

descriptor_spec

数値添字の配列で、ディスクリプタ番号をキーとし、PHP がその ディスクリプタをどのように子プロセスに渡すかを表すのが 対応する値となります。 0 が標準入力 (stdin)、1 が標準出力 (stdout) で、 2 が標準エラー出力 (stderr) となります。

各要素は、次のようになります。

  • プロセスに渡すパイプをあらわす配列。 最初の要素はディスクリプタの型で、2 番目の要素がその型に対応するオプションとなります。 使用できる型は pipe (2 番目の要素は、 プロセスにパイプの読み込み側を渡すのなら r、 書き込み側を渡すのなら w) および file (2 番目の要素はファイル名) です。 w 以外に何を指定しても、 r のように扱われるので注意して下さい。
  • 実際のファイルディスクリプタ (オープンしたファイルやソケット、 STDIN など) をあらわすストリームリソース。

ファイルディスクリプタの番号は、特に 0, 1, 2 に限られているわけでは ありません。有効であるどのようなファイルディスクリプタの番号も指定でき、 それは子プロセスに渡されます。これにより、あるスクリプトと、 子プロセスとして起動している別のスクリプトとの間で通信ができます。 特に、これは PGP や GPG、openssl といったプログラムにパスフレーズを より安全な方法で渡したいとき威力を発揮します。 補助的なファイルディスクリプタを介して、そのようなプログラムの 状態を取得するのにも便利です。

pipes

PHP 側で生成されたパイプの終端にあたる ファイルポインタの配列。

cwd

コマンドの初期作業ディレクトリ。 完全パスである必要があります。 デフォルト値 (現在の PHP プロセスの作業ディレクトリ) を使用したい場合は null を指定します。

env_vars

実行するコマンドのための環境変数の配列。 現在の PHP プロセスと同じ環境変数を使用する場合は null を指定します。

options

その他の追加オプションを指定することが可能です。 現在サポートされているオプションは次の通りです。

  • suppress_errors (windows のみ): true にすると、この関数が出力するエラーを抑制します。
  • bypass_shell (windows のみ): true にすると、cmd.exe シェルをバイパスします。
  • blocking_pipes (windows のみ): true に設定すると、パイプを強制的に切断します。
  • create_process_group (Windows のみ): true に設定すると、 子プロセスが CTRL イベントを ハンドルすることを許可します。
  • create_new_console (windows のみ): 新しいプロセスは親の console を継承せず、新しい console を持ちます。

戻り値

プロセスを表すリソースを返します。このリソースは、使用し終えた際に proc_close() を使用して開放する必要があります。 失敗した場合は false を返します。

変更履歴

バージョン | 説明
7.4.4 | options パラメータに オプション create_new_console が追加されました。
7.4.0 | proc_open() 関数は、 command に array を渡せるようになりました。
7.4.0 | options パラメータに オプション create_process_group が追加されました。

例

例1 A proc_open() の例

<?php
$descriptorspec = array(
0 => array("pipe", "r"), // stdin は、子プロセスが読み込むパイプです。
1 => array("pipe", "w"), // stdout は、子プロセスが書き込むパイプです。
2 => array("file", "/tmp/error-output.txt", "a") // はファイルで、そこに書き込みます。
);

$cwd = '/tmp';
$env = array('some_option' => 'aeiou');

$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);

if (is_resource($process)) {
// $pipes はこの時点で次のような形を取っています。
// 0 => 子プロセスの stdin に繋がれた書き込み可能なハンドル
// 1 => 子プロセスの stdout に繋がれた読み込み可能なハンドル
// すべてのエラー出力は /tmp/error-output.txt に書き込みされます。

fwrite($pipes[0], '<?php print_r($_ENV); ?>');
fclose($pipes[0]);

echo stream_get_contents($pipes[1]);
fclose($pipes[1]);

// デッドロックを避けるため、proc_close を呼ぶ前に
// すべてのパイプを閉じることが重要です。
$return_value = proc_close($process);

echo "command returned $return_value\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
command returned 0

例2 proc_open() 関数の癖(Windows限定)

次のプログラムで、ファイル filename.txt にある search というテキストを検索し、結果を出力したいのですが、 実際にはかなり異なる振る舞いをします。

<?php
$descriptorspec = [STDIN, STDOUT, STDOUT];
$cmd = '"findstr" "search" "filename.txt"';
$proc = proc_open($cmd, $descriptorspec, $pipes);
proc_close($proc);
?>

上の例の出力は以下となります。

'findstr" "search" "filename.txt' is not recognized as an internal or external command,
operable program or batch file.

この振る舞いを避けるには、 command を追加のクォートで囲めば通常は十分です:

$cmd = '""findstr" "search" "filename.txt""';

注意

注意:

Windows における互換性: 2 (stderr) よりも大きな番号のディスクリプタは 子プロセスに継承可能なハンドルとして渡されますが、 Windows のアーキテクチャは、ファイルディスクリプタの番号と より低レベルなハンドルを関連付けないので、子プロセスは、 それらのハンドルにアクセスする術を持ちません。stdin, stdout, stderr は期待通り動きます。

注意:

もし単方向(一方向)のパイプを利用したいだけでしたら、 popen() を使うほうがより簡単です。

参考

  • popen() - プロセスへのファイルポインタをオープンする
  • exec() - 外部プログラムを実行する
  • system() - 外部プログラムを実行し、出力を表示する
  • passthru() - 外部プログラムを実行し、未整形の出力を表示する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
  • バッククォート演算子


proc_open でオープンされたプロセスを強制終了する

  • ≪ proc_open
  • shell_exec ≫
  • PHP Manual
  • プログラム実行関数
  • proc_open でオープンされたプロセスを強制終了する

proc_terminate

(PHP 5, PHP 7, PHP 8)

proc_terminate — proc_open でオープンされたプロセスを強制終了する

説明

proc_terminate(resource $process, int $signal = 15): bool

終了させる (proc_open() を用いて生成された) process にシグナルを送信します。 proc_terminate() は即座に返され、 プロセスの終了を待ちません。

proc_terminate() により、プロセスを終了させ、 他のタスクを継続することができます。proc_get_status() 関数を使用して (停止したかどうかを確認するために) プロセスをポーリングすることができます。

パラメータ

process

終了させる proc_open() リソース。

signal

このオプションパラメータは POSIX オペレーティングシステムでのみ有用です。 kill(2) システムコールを使用して、 プロセスに送信するシグナルを指定することができます。 デフォルトは SIGTERM です。

戻り値

実行していたプロセスの終了状態を返します。

参考

  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く
  • proc_close() - proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
  • proc_get_status() - proc_open で開かれたプロセスに関する情報を取得する


シェルによりコマンドを実行し、文字列として出力全体を返す

  • ≪ proc_terminate
  • system ≫
  • PHP Manual
  • プログラム実行関数
  • シェルによりコマンドを実行し、文字列として出力全体を返す

shell_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

shell_exec — シェルによりコマンドを実行し、文字列として出力全体を返す

説明

shell_exec(string $command): string|false|null

この関数は バッククォート演算子 と等価です。

注意:

Windows では、パイプがテキストモードでオープンされるため、 この出力を使ったバイナリの出力が失敗する可能性があります。 このような場合は、popen() の利用を検討してください。

パラメータ

command

実行するコマンド

戻り値

実行されたコマンドからの出力を文字列で返します。 パイプがオープンできなかった場合は false を返します。 エラーが発生したり、コマンドが何も出力しなかった場合は null を返します。

注意:

この関数は、エラーが発生した場合だけでなくプログラムが何も出力しなかった場合にも null を返します。 そのため、実行に失敗したかどうかをこの関数では判断できません。 プログラムの終了コードを調べる必要があるときには exec() を使いましょう。

エラー / 例外

パイプがオープンできなかった場合は E_WARNING レベルの警告が発生します。

例

例1 shell_exec() の例

<?php
$output = shell_exec('ls -lart');
echo "<pre>$output</pre>";
?>

参考

  • exec() - 外部プログラムを実行する
  • escapeshellcmd() - シェルのメタ文字をエスケープする


外部プログラムを実行し、出力を表示する

  • ≪ shell_exec
  • parallel ≫
  • PHP Manual
  • プログラム実行関数
  • 外部プログラムを実行し、出力を表示する

system

(PHP 4, PHP 5, PHP 7, PHP 8)

system — 外部プログラムを実行し、出力を表示する

説明

system(string $command, int &$result_code = null): string|false

system() は、指定した command を実行し、結果を出力する C 言語の system 関数に似ています。

PHP をサーバーモジュールとして実行している場合、 system() のコールにより、各行を出力した後、 Web サーバーの出力バッファが自動的にクリアされます。

コマンドを実行し、何の加工もせずに全てのデータをコマンドから直接 返す必要がある場合、passthru() 関数を使用してください。

パラメータ

command

実行するコマンド。

result_code

引数 result_code が存在する場合、 実行したコマンドの返すステータスがこの変数に書かれます。

戻り値

成功時はコマンド出力の最後の行を返し、失敗時は false を返します。

例

例1 system() の例

<?php
echo '<pre>';

// シェルコマンド "ls" の全ての結果を出力し、出力の最後の
// 行を $last_line に格納します。シェルコマンドの戻り値は
// $retval に格納されます。
$last_line = system('ls', $retval);

// 追加情報を表示します。
echo '
</pre>
<hr />Last line of the output: ' . $last_line . '
<hr />Return value: ' . $retval;
?>

注意

警告

ユーザーが入力したデータをこの関数に 渡すことを許可する場合、ユーザーが任意のコマンドを実行できるようシステムを欺くことが できないように escapeshellarg() または escapeshellcmd() を適用する必要があります。

注意:

プログラムがこの関数で始まる場合、 バックグラウンドで処理を続けさせるには、 プログラムの出力をファイルや別の出力ストリームにリダイレクトする必要があります。 そうしないと、プログラムが実行を終えるまで PHP はハングしてしまいます。

参考

  • exec() - 外部プログラムを実行する
  • passthru() - 外部プログラムを実行し、未整形の出力を表示する
  • popen() - プロセスへのファイルポインタをオープンする
  • escapeshellcmd() - シェルのメタ文字をエスケープする
  • pcntl_exec() - 現在のプロセス空間で指定したプログラムを実行する
  • バッククォート演算子


parallel

  • はじめに
  • Installation
  • Philosophy
  • Functional API
    • parallel\bootstrap — Bootstrapping
    • parallel\run — Execution
  • parallel\Runtime — The parallel\Runtime class
    • parallel\Runtime::__construct — Runtime Construction
    • parallel\Runtime::run — Execution
    • parallel\Runtime::close — Runtime Graceful Join
    • parallel\Runtime::kill — Runtime Join
  • parallel\Future — The parallel\Future class
    • parallel\Future::cancel — Cancellation
    • parallel\Future::cancelled — State Detection
    • parallel\Future::done — State Detection
    • parallel\Future::value — Resolution
  • parallel\Channel — The parallel\Channel class
    • parallel\Channel::__construct — Channel Construction
    • parallel\Channel::make — Access
    • parallel\Channel::open — Access
    • parallel\Channel::recv — Sharing
    • parallel\Channel::send — Sharing
    • parallel\Channel::close — Closing
  • parallel\Events — The parallel\Events class
    • parallel\Events::setBlocking — Behaviour
    • parallel\Events::setTimeout — Behaviour
    • parallel\Events::setInput — Input
    • parallel\Events::addChannel — Targets
    • parallel\Events::addFuture — Targets
    • parallel\Events::remove — Targets
    • parallel\Events::poll — Polling
  • parallel\Events\Input — The parallel\Events\Input class
    • parallel\Events\Input::add — Inputs
    • parallel\Events\Input::clear — Inputs
    • parallel\Events\Input::remove — Inputs
  • parallel\Events\Event — The parallel\Events\Event class
  • parallel\Events\Event\Type — The parallel\Events\Event\Type class
  • parallel\Sync — The parallel\Sync class
    • parallel\Sync::__construct — Construction
    • parallel\Sync::get — Access
    • parallel\Sync::set — Access
    • parallel\Sync::wait — Synchronization
    • parallel\Sync::notify — Synchronization
    • parallel\Sync::__invoke — Synchronization


はじめに

parallel is a parallel concurrency extension for PHP ? 7.2.0. As of parallel 1.2.0, PHP ? 8.0.0 is required.

A brief description of the concepts core to parallel follows, more detailed information may be found within this section of the manual.

Runtime

A parallel\Runtime represents a PHP interpreter thread. A parallel\Runtime is configured with an optional bootstrap file passed to parallel\Runtime::__construct(), this is typically an autoloader, or some other preloading routine: The bootstrap file will be included before any task is executed.

After construction the parallel\Runtime remains available until it is closed, killed, or destroyed by the normal scoping rules of PHP objects. parallel\Runtime::run() allows the programmer to schedule tasks for execution in parallel. A parallel\Runtime has a FIFO schedule, tasks will be executed in the order that they are scheduled.

Functional API

parallel implements a functional, higher level API on top of parallel\Runtime that provides a single function entry point to executing parallel code with automatic scheduling: parallel\run().

Task

A task is simply a Closure intended for parallel execution. The Closure may contain almost any instruction, including nested closures. However, there are some instructions that are prohibited in tasks:

  • yield

  • use by-reference

  • declare class

  • declare named function

注意:

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

注意:

No instructions are prohibited in the files which the task may include.

Future

The parallel\Future is used to access the return value from the task, and exposes an API for cancellation of the task.

Channel

A task may be scheduled with arguments, use lexical scope variables (by-value), and return a value (via a parallel\Future), but these only allow uni-directional communication: They allow the programmer to send data into and retrieve data from a task, but do not allow bi-directional communication between tasks. The parallel\Channel API allows bi-directional communication between tasks, a parallel\Channel is a socket-like link between tasks that the programmer can use to send and receive data.

Events

The parallel\Events API implements a native feel (Traversable) event loop, and parallel\Events::poll() method. It allows the programmer to work with sets of channels and or futures. The programmer simply adds channels and futures to the event loop, optionally setting the input for writes with parallel\Events::setInput(), and enters into a foreach: parallel will read from and write to objects as they become available yielding parallel\Events\Event objects describing the operations that have occurred.

参考

  • Philosophy


Installation

要件

parallel requires a build of PHP with ZTS (Zend Thread Safety) enabled (--enable-zts, or on non-Windows systems prior to PHP 8.0.0, --enable-maintainer-zts)

警告

Zend Thread Safety cannot be enabled post build; it is a build time configuration option.

parallel should build anywhere there is a working Posix Threads header (pthread.h) and ZTS build of PHP, including Windows (using the pthread-w32 project from redhat).

インストール手順

parallel releases are hosted by PECL and the source code by » github, the easiest route to installation is the normal PECL route: » https://pecl.php.net/package/parallel.

Windows users can download prebuilt release binaries from the » PECL website.

警告

Windows users need to take the additional step of adding pthreadVC?.dll (distributed with Windows releases) to their PATH.


Philosophy

This section contains philosophies important to writing parallel code and some details about the internal implementation of parallel.

Do not communicate by sharing memory; instead, share memory by communicating.

This philosophy which is embraced by parallel has its origins in Go, one of the most widely admired if not used platforms for writing parallel code at the moment. Go programmers have to work hard to live up to this ideal: PHP and parallel do all the hard work for the programmer, and by default.

In conventional threading models found in other languages, generally threads are communicating with one another through nothing more than by virtue of the fact that they operate in the same address space. The programmer must deploy mutual exclusion, condition variables, and other low level threading or synchronization primitives in order to ensure proper communication of state and consistency.

When the conventional model is inversed, it means that threads only share memory as a result of communication (a variable is passed over a Channel for example).

When parallel passes a variable from one thread to another by any means - Task arguments, return via Future, and Channels - it is passed by value. In all but the case of unbuffered channels, the variable is also buffered so that it may not change (or be destroyed) before it is used in whichever thread the variable is being passed to. An unbuffered read over a channel is the only instance in which a thread directly reads memory allocated by another thread, it can do so safely because the thread that owns the memory is waiting for the read to complete before it can continue to manipulate it, and the thread that does not own the memory reads by value. When both threads continue, they are no longer sharing memory.

This makes writing and reasoning about parallel code much easier than the conventional model of threading. It means the programmer does not need to consider that threads may be manipulating data concurrently, because that is not possible.

This also makes PHP the perfect platform for implementing a parallel concurrency API based on CSP (message passing over channels), because PHP itself is shared nothing - PHP threads operate in their own virtual address space by default, and so may only share memory by communicating.

Data should have a definitive single owner

When approaching the CSP model for the first time, a programmer versed in the traditional model of threading may find themselves looking for concurrent data structures, because that is what they are used too: they pass around shared objects for manipulation.

When it comes to the CSP model, there is no need for data structures to be shared by many tasks, and indeed, it is simpler if they are not. The data should be owned by a single task, changes to (or operations on) that data structure should be communicated over channels and performed by the owner of the data, the success, failure, or result (state) of the change (or operation) being communicated back.

Once again the share nothing nature of PHP and copy by value nature of parallel helps the programmer to achieve this goal, no data will be shared by accident, only ever as a result of communication.


Functional API

The parallel\Runtime API provides a great degree of control to the power PHP programmer, and those intimately familiar with writing applications that use parallel concurrency.

The functional API provides less control in exchange for the ability to make decisions for the programmer:

  • all executing runtimes are bootstrapped identically

  • scheduling is determined by the API, not the programmer

parallel\run() provides the guarantee that the task will begin to execute in parallel as soon as allowed by hardware and operating system constraints, without needlessly creating runtimes. For most applications the functional API should be preferred.

目次

  • parallel\bootstrap — Bootstrapping
  • parallel\run — Execution


Bootstrapping

  • ≪ Functional API
  • parallel\run ≫
  • PHP Manual
  • Functional API
  • Bootstrapping

parallel\bootstrap

(1.0.0)

parallel\bootstrap — Bootstrapping

説明

parallel\bootstrap(string $file): void

Shall use the provided file to bootstrap all runtimes created for automatic scheduling via parallel\run().

パラメータ

file

Path to the file to bootstrap all runtimes.

戻り値

値を返しません。

エラー / 例外

警告

Shall throw parallel\Runtime\Error\Bootstrap if previously called for this process.

警告

Shall throw parallel\Runtime\Error\Bootstrap if called after parallel\run().

参考

  • parallel\Runtime::run


Execution

  • ≪ parallel\bootstrap
  • parallel\Runtime ≫
  • PHP Manual
  • Functional API
  • Execution

parallel\run

(1.0.0)

parallel\run — Execution

説明

parallel\run(Closure $task): ?Future

Shall schedule task for execution in parallel.

parallel\run(Closure $task, array $argv): ?Future

Shall schedule task for execution in parallel, passing argv at execution time.

Automatic Scheduling

If a \parallel\Runtime internally created and cached by a previous call to parallel\run() is idle, it will be used to execute the task. If no \parallel\Runtime is idle parallel will create and cache a \parallel\Runtime.

注意:

\parallel\Runtime objects created by the programmer are not used for automatic scheduling.

パラメータ

task

A Closure with specific characteristics.

argv

An array of arguments with specific characteristics to be passed to task at execution time.

Task Characteristics

Closures scheduled for parallel execution must not:

  • accept or return by reference
  • accept or return internal objects (see notes)
  • execute a limited set of instructions

Instructions prohibited in Closures intended for parallel execution are:

  • yield
  • use by-reference
  • declare class
  • declare named function

注意:

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

注意:

No instructions are prohibited in the files which the task may include.

Arguments Characteristics

Arguments must not:

  • contain references
  • contain resources
  • contain internal objects (see notes)

注意:

In the case of file stream resources, the resource will be cast to the file descriptor and passed as int where possible, this is unsupported on Windows.

Internal Objects Notes

Internal objects generally use a custom structure which cannot be copied by value safely, PHP currently lacks the mechanics to do this (without serialization) and so only objects that do not use a custom structure may be shared.

Some internal objects do not use a custom structure, for example parallel\Events\Event and so may be shared.

Closures are a special kind of internal object and support being copied by value, and so may be shared.

Channels are central to writing parallel code and support concurrent access and execution by necessity, and so may be shared.

警告

A user class that extends an internal class may use a custom structure as defined by the internal class, in which case they cannot be copied by value safely, and so may not be shared.

戻り値

警告

The return parallel\Future must not be ignored when the task contains a return or throw statement.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if parallel\Runtime was closed.

警告

Shall throw parallel\Runtime\Error\IllegalFunction if task is a closure created from an internal function.

警告

Shall throw parallel\Runtime\Error\IllegalInstruction if task contains illegal instructions.

警告

Shall throw parallel\Runtime\Error\IllegalParameter if task accepts or argv contains illegal variables.

警告

Shall throw parallel\Runtime\Error\IllegalReturn if task returns illegally.

参考

  • parallel\Runtime::run


The parallel\Runtime class

(0.8.0)

Runtime Objects

Each runtime represents a single PHP thread, the thread is created (and bootstrapped) upon construction. The thread then waits for tasks to be scheduled: Scheduled tasks will be executed FIFO and then the thread will resume waiting until more tasks are scheduled, or it's closed, killed, or destroyed by the normal scoping rules of PHP objects.

警告

When a runtime is destroyed by the normal scoping rules of PHP objects, it will first execute all of the tasks that were scheduled, and block while doing so.

Runtime Bootstrapping

When a new runtime is created, it does not share code with the thread (or process) that created it. This means it doesn't have the same classes and functions loaded, nor the same autoloader set. In some cases, a very lightweight runtime is desirable because the tasks that will be scheduled do not need access to the code in the parent thread. In those cases where the tasks do need to access the same code, it is enough to set an autoloader as the bootstrap.

注意:

preloading may be used in conjunction with parallel, in this case preloaded code is available without bootstrapping

クラス概要

final class parallel\Runtime {
/* Create */
public __construct()
public __construct(string $bootstrap)
/* Execute */
public run(Closure $task): ?Future
public run(Closure $task, array $argv): ?Future
/* Join */
public close(): void
public kill(): void
}

目次

  • parallel\Runtime::__construct — Runtime Construction
  • parallel\Runtime::run — Execution
  • parallel\Runtime::close — Runtime Graceful Join
  • parallel\Runtime::kill — Runtime Join


Runtime Construction

  • ≪ parallel\Runtime
  • parallel\Runtime::run ≫
  • PHP Manual
  • parallel\Runtime
  • Runtime Construction

parallel\Runtime::__construct

(0.8.0)

parallel\Runtime::__construct — Runtime Construction

説明

public parallel\Runtime::__construct()

Shall construct a new runtime without bootstrapping.

public parallel\Runtime::__construct(string $bootstrap)

Shall construct a bootstrapped runtime.

パラメータ

bootstrap

The location of a bootstrap file, generally an autoloader.

Exceptions

警告

Shall throw parallel\Runtime\Error if thread could not be created

警告

Shall throw parallel\Runtime\Bootstrap if bootstrapping failed


Execution

  • ≪ parallel\Runtime::__construct
  • parallel\Runtime::close ≫
  • PHP Manual
  • parallel\Runtime
  • Execution

parallel\Runtime::run

(0.8.0)

parallel\Runtime::run — Execution

説明

public parallel\Runtime::run(Closure $task): ?Future

Shall schedule task for execution in parallel.

public parallel\Runtime::run(Closure $task, array $argv): ?Future

Shall schedule task for execution in parallel, passing argv at execution time.

パラメータ

task

A Closure with specific characteristics.

argv

An array of arguments with specific characteristics to be passed to task at execution time.

Task Characteristics

Closures scheduled for parallel execution must not:

  • accept or return by reference
  • accept or return internal objects (see notes)
  • execute a limited set of instructions

Instructions prohibited in Closures intended for parallel execution are:

  • yield
  • use by-reference
  • declare class
  • declare named function

注意:

Nested closures may yield or use by-reference, but must not contain class or named function declarations.

注意:

No instructions are prohibited in the files which the task may include.

Arguments Characteristics

Arguments must not:

  • contain references
  • contain resources
  • contain internal objects (see notes)

注意:

In the case of file stream resources, the resource will be cast to the file descriptor and passed as int where possible, this is unsupported on Windows.

Internal Objects Notes

Internal objects generally use a custom structure which cannot be copied by value safely, PHP currently lacks the mechanics to do this (without serialization) and so only objects that do not use a custom structure may be shared.

Some internal objects do not use a custom structure, for example parallel\Events\Event and so may be shared.

Closures are a special kind of internal object and support being copied by value, and so may be shared.

Channels are central to writing parallel code and support concurrent access and execution by necessity, and so may be shared.

警告

A user class that extends an internal class may use a custom structure as defined by the internal class, in which case they cannot be copied by value safely, and so may not be shared.

戻り値

警告

The return parallel\Future must not be ignored when the task contains a return or throw statement.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if parallel\Runtime was closed.

警告

Shall throw parallel\Runtime\Error\IllegalFunction if task is a closure created from an internal function.

警告

Shall throw parallel\Runtime\Error\IllegalInstruction if task contains illegal instructions.

警告

Shall throw parallel\Runtime\Error\IllegalParameter if task accepts or argv contains illegal variables.

警告

Shall throw parallel\Runtime\Error\IllegalReturn if task returns illegally.


Runtime Graceful Join

  • ≪ parallel\Runtime::run
  • parallel\Runtime::kill ≫
  • PHP Manual
  • parallel\Runtime
  • Runtime Graceful Join

parallel\Runtime::close

(0.8.0)

parallel\Runtime::close — Runtime Graceful Join

説明

public parallel\Runtime::close(): void

Shall request that the runtime shutsdown.

注意:

Tasks scheduled for execution will be executed before the shutdown occurs.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if Runtime was already closed.


Runtime Join

  • ≪ parallel\Runtime::close
  • parallel\Future ≫
  • PHP Manual
  • parallel\Runtime
  • Runtime Join

parallel\Runtime::kill

(0.8.0)

parallel\Runtime::kill — Runtime Join

説明

public parallel\Runtime::kill(): void

Shall attempt to force the runtime to shutdown.

注意:

Tasks scheduled for execution will not be executed, the currently running task shall be interrupted.

警告

Internal function calls in progress cannot be interrupted.

Exceptions

警告

Shall throw parallel\Runtime\Error\Closed if Runtime was closed.


The parallel\Future class

(0.8.0)

Futures

A Future represents the return value or uncaught exception from a task, and exposes an API for cancellation.

例1 Example showing Future as return value

<?php
$runtime = new \parallel\Runtime;
$future = $runtime->run(function(){
return "World";
});
printf("Hello %s\n", $future->value());
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

The behaviour of a future also allows it to be used as a simple synchronization point even where the task does not return a value explicitly.

例2 Example showing Future as synchronization point

<?php
$runtime = new \parallel\Runtime;
$future = $runtime->run(function(){
echo "in child ";
for ($i = 0; $i < 500; $i++) {
if ($i % 10 == 0) {
echo ".";
}
}
echo " leaving child";
});

$future->value();
echo "\nparent continues\n";
?>

上の例の出力は、 たとえば以下のようになります。

in child .................................................. leaving child
parent continues

クラス概要

final class parallel\Future {
/* Resolution */
public value(): mixed
/* State */
public cancelled(): bool
public done(): bool
/* Cancellation */
public cancel(): bool
}

目次

  • parallel\Future::cancel — Cancellation
  • parallel\Future::cancelled — State Detection
  • parallel\Future::done — State Detection
  • parallel\Future::value — Resolution


Cancellation

  • ≪ parallel\Future
  • parallel\Future::cancelled ≫
  • PHP Manual
  • parallel\Future
  • Cancellation

parallel\Future::cancel

(0.9.0)

parallel\Future::cancel — Cancellation

説明

public parallel\Future::cancel(): bool

Shall try to cancel the task

注意:

If task is running, it will be interrupted.

警告

Internal function calls in progress cannot be interrupted.

Exceptions

警告

Shall throw parallel\Future\Error\Killed if parallel\Runtime executing task was killed.

警告

Shall throw parallel\Future\Error\Cancelled if task was already cancelled.


State Detection

  • ≪ parallel\Future::cancel
  • parallel\Future::done ≫
  • PHP Manual
  • parallel\Future
  • State Detection

parallel\Future::cancelled

(0.9.0)

parallel\Future::cancelled — State Detection

説明

public parallel\Future::cancelled(): bool

Shall indicate if the task was cancelled


State Detection

  • ≪ parallel\Future::cancelled
  • parallel\Future::value ≫
  • PHP Manual
  • parallel\Future
  • State Detection

parallel\Future::done

(0.8.0)

parallel\Future::done — State Detection

説明

public parallel\Future::done(): bool

Shall indicate if the task is completed


Resolution

  • ≪ parallel\Future::done
  • parallel\Channel ≫
  • PHP Manual
  • parallel\Future
  • Resolution

parallel\Future::value

(0.8.0)

parallel\Future::value — Resolution

説明

public parallel\Future::value(): mixed

Shall return (and if necessary wait for) return from task

Exceptions

警告

Shall throw parallel\Future\Error if waiting failed (internal error).

警告

Shall throw parallel\Future\Error\Killed if parallel\Runtime executing task was killed.

警告

Shall throw parallel\Future\Error\Cancelled if task was cancelled.

警告

Shall throw parallel\Future\Error\Foreign if task raised an unrecognized uncaught exception.

警告

Shall rethrow Throwable uncaught in task


The parallel\Channel class

(0.9.0)

Unbuffered Channels

An unbuffered channel will block on calls to parallel\Channel::send() until there is a receiver, and block on calls to parallel\Channel::recv() until there is a sender. This means an unbuffered channel is not only a way to share data among tasks but also a simple method of synchronization.

An unbuffered channel is the fastest way to share data among tasks, requiring the least copying.

Buffered Channels

A buffered channel will not block on calls to parallel\Channel::send() until capacity is reached, calls to parallel\Channel::recv() will block until there is data in the buffer.

Closures over Channels

A powerful feature of parallel channels is that they allow the exchange of closures between tasks (and runtimes).

When a closure is sent over a channel the closure is buffered, it doesn't change the buffering of the channel transmitting the closure, but it does effect the static scope inside the closure: The same closure sent to different runtimes, or the same runtime, will not share their static scope.

This means that whenever a closure is executed that was transmitted by a channel, static state will be as it was when the closure was buffered.

Anonymous Channels

The anonymous channel constructor allows the programmer to avoid assigning names to every channel: parallel will generate a unique name for anonymous channels.

クラス概要

final class parallel\Channel {
/* Anonymous Constructor */
public __construct()
public __construct(int $capacity)
/* Access */
public make(string $name): Channel
public make(string $name, int $capacity): Channel
public open(string $name): Channel
/* Sharing */
public recv(): mixed
public send(mixed $value): void
/* Closing */
public close(): void
/* Constant for Infinitely Buffered */
const Infinite;
}

目次

  • parallel\Channel::__construct — Channel Construction
  • parallel\Channel::make — Access
  • parallel\Channel::open — Access
  • parallel\Channel::recv — Sharing
  • parallel\Channel::send — Sharing
  • parallel\Channel::close — Closing


Channel Construction

  • ≪ parallel\Channel
  • parallel\Channel::make ≫
  • PHP Manual
  • parallel\Channel
  • Channel Construction

parallel\Channel::__construct

(1.1.0)

parallel\Channel::__construct — Channel Construction

説明

public parallel\Channel::__construct()

Shall make an anonymous unbuffered channel

public parallel\Channel::__construct(int $capacity)

Shall make an anonymous buffered channel with the given capacity

パラメータ

capacity

May be Channel::Infinite or a positive integer


Access

  • ≪ parallel\Channel::__construct
  • parallel\Channel::open ≫
  • PHP Manual
  • parallel\Channel
  • Access

parallel\Channel::make

(0.9.0)

parallel\Channel::make — Access

説明

public parallel\Channel::make(string $name): Channel

Shall make an unbuffered channel with the given name

public parallel\Channel::make(string $name, int $capacity): Channel

Shall make a buffered channel with the given name and capacity

パラメータ

name

The name of the channel.

capacity

May be Channel::Infinite or a positive integer

Exceptions

警告

Shall throw parallel\Channel\Error\Existence if channel already exists.


Access

  • ≪ parallel\Channel::make
  • parallel\Channel::recv ≫
  • PHP Manual
  • parallel\Channel
  • Access

parallel\Channel::open

(0.9.0)

parallel\Channel::open — Access

説明

public parallel\Channel::open(string $name): Channel

Shall open the channel with the given name

Exceptions

警告

Shall throw parallel\Channel\Error\Existence if channel does not exist.


Sharing

  • ≪ parallel\Channel::open
  • parallel\Channel::send ≫
  • PHP Manual
  • parallel\Channel
  • Sharing

parallel\Channel::recv

(0.9.0)

parallel\Channel::recv — Sharing

説明

public parallel\Channel::recv(): mixed

Shall recv a value from this channel

Exceptions

警告

Shall throw parallel\Channel\Error\Closed if channel is closed.


Sharing

  • ≪ parallel\Channel::recv
  • parallel\Channel::close ≫
  • PHP Manual
  • parallel\Channel
  • Sharing

parallel\Channel::send

(0.9.0)

parallel\Channel::send — Sharing

説明

public parallel\Channel::send(mixed $value): void

Shall send the given value on this channel

Exceptions

警告

Shall throw parallel\Channel\Error\Closed if channel is closed.

警告

Shall throw parallel\Channel\Error\IllegalValue if value is illegal.


Closing

  • ≪ parallel\Channel::send
  • parallel\Events ≫
  • PHP Manual
  • parallel\Channel
  • Closing

parallel\Channel::close

(0.9.0)

parallel\Channel::close — Closing

説明

public parallel\Channel::close(): void

Shall close this channel

Exceptions

警告

Shall throw parallel\Channel\Error\Closed if channel is closed.


The parallel\Events class

(0.9.0)

The Event Loop

The Event loop monitors the state of sets of futures and or channels (targets) in order to perform read (parallel\Future::value(), parallel\Channel::recv()) and write (parallel\Channel::send()) operations as the targets become available and the operations may be performed without blocking the event loop.

クラス概要

final class parallel\Events implements Countable, Traversable {
/* Input */
public setInput(Input $input): void
/* Targets */
public addChannel(parallel\Channel $channel): void
public addFuture(string $name, parallel\Future $future): void
public remove(string $target): void
/* Behaviour */
public setBlocking(bool $blocking): void
public setTimeout(int $timeout): void
/* Polling */
public poll(): ?parallel\Events\Event
}

目次

  • parallel\Events::setBlocking — Behaviour
  • parallel\Events::setTimeout — Behaviour
  • parallel\Events::setInput — Input
  • parallel\Events::addChannel — Targets
  • parallel\Events::addFuture — Targets
  • parallel\Events::remove — Targets
  • parallel\Events::poll — Polling


Behaviour

  • ≪ parallel\Events
  • parallel\Events::setTimeout ≫
  • PHP Manual
  • parallel\Events
  • Behaviour

parallel\Events::setBlocking

(0.9.0)

parallel\Events::setBlocking — Behaviour

説明

By default when events are polled for, blocking will occur (at the PHP level) until the first event can be returned: Setting blocking mode to false will cause poll to return control if the first target polled is not ready.

This differs from setting a timeout of 0 with parallel\Events::setTimeout(), since a timeout of 0, while allowed, will cause an exception to be raised, which may be extremely slow or wasteful if what is really desired is non-blocking behaviour.

A non-blocking loop effects the return value of parallel\Events::poll(), such that it may be null before all events have been processed.

public parallel\Events::setBlocking(bool $blocking): void

Shall set blocking mode

Exceptions

警告

Shall throw parallel\Events\Error if loop has timeout set.


Behaviour

  • ≪ parallel\Events::setBlocking
  • parallel\Events::setInput ≫
  • PHP Manual
  • parallel\Events
  • Behaviour

parallel\Events::setTimeout

(0.9.0)

parallel\Events::setTimeout — Behaviour

説明

By default when events are polled for, blocking will occur (at the PHP level) until the first event can be returned: Setting the timeout causes an exception to be thrown when the timeout is reached.

This differs from setting blocking mode to false with parallel\Events::setBlocking(), which will not cause an exception to be thrown.

public parallel\Events::setTimeout(int $timeout): void

Shall set the timeout in microseconds

Exceptions

警告

Shall throw parallel\Events\Error if loop is non-blocking.


Input

  • ≪ parallel\Events::setTimeout
  • parallel\Events::addChannel ≫
  • PHP Manual
  • parallel\Events
  • Input

parallel\Events::setInput

(0.9.0)

parallel\Events::setInput — Input

説明

public parallel\Events::setInput(Input $input): void

Shall set input for this event loop


Targets

  • ≪ parallel\Events::setInput
  • parallel\Events::addFuture ≫
  • PHP Manual
  • parallel\Events
  • Targets

parallel\Events::addChannel

(0.9.0)

parallel\Events::addChannel — Targets

説明

public parallel\Events::addChannel(parallel\Channel $channel): void

Shall watch for events on the given channel

Exceptions

警告

Shall throw parallel\Events\Error\Existence if channel was already added.


Targets

  • ≪ parallel\Events::addChannel
  • parallel\Events::remove ≫
  • PHP Manual
  • parallel\Events
  • Targets

parallel\Events::addFuture

(0.9.0)

parallel\Events::addFuture — Targets

説明

public parallel\Events::addFuture(string $name, parallel\Future $future): void

Shall watch for events on the given future

Exceptions

警告

Shall throw parallel\Events\Error\Existence if target with the given name was already added.


Targets

  • ≪ parallel\Events::addFuture
  • parallel\Events::poll ≫
  • PHP Manual
  • parallel\Events
  • Targets

parallel\Events::remove

(0.9.0)

parallel\Events::remove — Targets

説明

public parallel\Events::remove(string $target): void

Shall remove the given target

Exceptions

警告

Shall throw parallel\Events\Error\Existence if target with the given name was not found.


Polling

  • ≪ parallel\Events::remove
  • parallel\Events\Input ≫
  • PHP Manual
  • parallel\Events
  • Polling

parallel\Events::poll

(0.9.0)

parallel\Events::poll — Polling

説明

public parallel\Events::poll(): ?parallel\Events\Event

Shall poll for the next event

戻り値

Should there be no targets remaining, null shall be returned

Should this be a non-blocking loop, and blocking would occur, null shall be returned

Otherwise, the parallel\Events\Event returned describes the event.

Exceptions

警告

Shall throw parallel\Events\Error\Timeout if timeout is used and reached.


The parallel\Events\Input class

(0.9.0)

Events Input

An Input object is a container for data that the parallel\Events object will write to parallel\Channel objects as they become available. Multiple event loops may share an Input container - parallel does not verify the contents of the container when it is set as the input for a parallel\Events object.

注意:

When a parallel\Events object performs a write, the target is removed from the input object as if parallel\Events\Input::remove() were called.

クラス概要

final class parallel\Events\Input {
public add(string $target, mixed $value): void
public remove(string $target): void
public clear(): void
}

目次

  • parallel\Events\Input::add — Inputs
  • parallel\Events\Input::clear — Inputs
  • parallel\Events\Input::remove — Inputs


Inputs

  • ≪ parallel\Events\Input
  • parallel\Events\Input::clear ≫
  • PHP Manual
  • parallel\Events\Input
  • Inputs

parallel\Events\Input::add

(0.9.0)

parallel\Events\Input::add — Inputs

説明

public parallel\Events\Input::add(string $target, mixed $value): void

Shall set input for the given target

Exceptions

警告

Shall throw parallel\Events\Input\Error\Existence if input for target already exists.

警告

Shall throw parallel\Events\Input\Error\IllegalValue if value is illegal (object, null).


Inputs

  • ≪ parallel\Events\Input::add
  • parallel\Events\Input::remove ≫
  • PHP Manual
  • parallel\Events\Input
  • Inputs

parallel\Events\Input::clear

(0.9.0)

parallel\Events\Input::clear — Inputs

説明

public parallel\Events\Input::clear(): void

Shall remove input for all targets


Inputs

  • ≪ parallel\Events\Input::clear
  • parallel\Events\Event ≫
  • PHP Manual
  • parallel\Events\Input
  • Inputs

parallel\Events\Input::remove

(0.9.0)

parallel\Events\Input::remove — Inputs

説明

public parallel\Events\Input::remove(string $target): void

Shall remove input for the given target

Exceptions

警告

Shall throw parallel\Events\Input\Error\Existence if input for target does not exist.


The parallel\Events\Event class

(0.9.0)

Event Objects

When an Event is returned, Event::$object shall be removed from the loop that returned it, should the event be a write event the Input for Event::$source shall also be removed.

クラス概要

final class parallel\Events\Event {
/* Shall be one of Event\Type constants */
public int $type;
/* Shall be the source of the event (target name) */
public string $source;
/* Shall be either Future or Channel */
public object $object;
/* Shall be set for Read/Error events */
public $value;
}


The parallel\Events\Event\Type class

(0.9.0)

クラス概要

final class parallel\Events\Event\Type {
/* Event::$object was read into Event::$value */
const Read;
/* Input for Event::$source written to Event::$object */
const Write;
/* Event::$object (Channel) was closed */
const Close;
/* Event::$object (Future) was cancelled */
const Cancel;
/* Runtime executing Event::$object (Future) was killed */
const Kill;
/* Event::$object (Future) raised error */
const Error;
}


The parallel\Sync class

(1.1.0)

Low Level Synchronization

The parallel\Sync class provides access to low level synchronization primitives, mutex, condition variables, and allows the implementation of semaphores.

Synchronization for most applications is much better implemented using channels, however, in some cases authors of low level code may find it useful to be able to access these lower level mechanisms.

クラス概要

final class parallel\Sync {
/* Constructor */
public __construct()
public __construct(scalar $value)
/* Access */
public get(): scalar
public set(scalar $value)
/* Synchronization */
public wait()
public notify(bool $all = ?)
public __invoke(callable $critical)
}

目次

  • parallel\Sync::__construct — Construction
  • parallel\Sync::get — Access
  • parallel\Sync::set — Access
  • parallel\Sync::wait — Synchronization
  • parallel\Sync::notify — Synchronization
  • parallel\Sync::__invoke — Synchronization


Construction

  • ≪ parallel\Sync
  • parallel\Sync::get ≫
  • PHP Manual
  • parallel\Sync
  • Construction

parallel\Sync::__construct

(1.1.0)

parallel\Sync::__construct — Construction

説明

public parallel\Sync::__construct()

Shall construct a new synchronization object with no value

public parallel\Sync::__construct(scalar $value)

Shall construct a new synchronization object containing the given scalar value

Exceptions

警告

Shall throw parallel\Sync\Error\IllegalValue if value is non-scalar.


Access

  • ≪ parallel\Sync::__construct
  • parallel\Sync::set ≫
  • PHP Manual
  • parallel\Sync
  • Access

parallel\Sync::get

(1.1.0)

parallel\Sync::get — Access

説明

public parallel\Sync::get(): scalar

Shall atomically return the synchronization objects value


Access

  • ≪ parallel\Sync::get
  • parallel\Sync::wait ≫
  • PHP Manual
  • parallel\Sync
  • Access

parallel\Sync::set

(1.1.0)

parallel\Sync::set — Access

説明

public parallel\Sync::set(scalar $value)

Shall atomically set the value of the synchronization object

Exceptions

警告

Shall throw parallel\Sync\Error\IllegalValue if value is non-scalar.


Synchronization

  • ≪ parallel\Sync::set
  • parallel\Sync::notify ≫
  • PHP Manual
  • parallel\Sync
  • Synchronization

parallel\Sync::wait

(1.1.0)

parallel\Sync::wait — Synchronization

説明

public parallel\Sync::wait()

Shall wait for notification on this synchronization object


Synchronization

  • ≪ parallel\Sync::wait
  • parallel\Sync::__invoke ≫
  • PHP Manual
  • parallel\Sync
  • Synchronization

parallel\Sync::notify

(1.1.0)

parallel\Sync::notify — Synchronization

説明

public parallel\Sync::notify(bool $all = ?)

Shall notify one (by default) or all threads waiting on the synchronization object


Synchronization

  • ≪ parallel\Sync::notify
  • pthreads ≫
  • PHP Manual
  • parallel\Sync
  • Synchronization

parallel\Sync::__invoke

(1.1.0)

parallel\Sync::__invoke — Synchronization

説明

public parallel\Sync::__invoke(callable $critical)

Shall exclusively enter into the critical code


pthreads

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • Threaded — The Threaded class
    • Threaded::chunk — Manipulation
    • Threaded::count — Manipulation
    • Threaded::extend — Runtime Manipulation
    • Threaded::isRunning — State Detection
    • Threaded::isTerminated — State Detection
    • Threaded::merge — Manipulation
    • Threaded::notify — Synchronization
    • Threaded::notifyOne — Synchronization
    • Threaded::pop — Manipulation
    • Threaded::run — Execution
    • Threaded::shift — Manipulation
    • Threaded::synchronized — Synchronization
    • Threaded::wait — Synchronization
  • Thread — Thread クラス
    • Thread::getCreatorId — 識別
    • Thread::getCurrentThread — Identification
    • Thread::getCurrentThreadId — Identification
    • Thread::getThreadId — 識別
    • Thread::isJoined — 状態を検出する
    • Thread::isStarted — 状態を検出する
    • Thread::join — 同期処理
    • Thread::start — 実行する
  • Worker — Worker クラス
    • Worker::collect — Collect references to completed tasks
    • Worker::getStacked — Gets the remaining stack size
    • Worker::isShutdown — State Detection
    • Worker::shutdown — Shutdown the worker
    • Worker::stack — Stacking work
    • Worker::unstack — Unstacking work
  • Collectable — The Collectable interface
    • Collectable::isGarbage — Determine whether an object has been marked as garbage
  • Pool — The Pool class
    • Pool::collect — Collect references to completed tasks
    • Pool::__construct — Creates a new Pool of Workers
    • Pool::resize — Resize the Pool
    • Pool::shutdown — Shutdown all workers
    • Pool::submit — Submits an object for execution
    • Pool::submitTo — Submits a task to a specific worker for execution
  • Volatile — The Volatile class


はじめに

pthreads はオブジェクト指向の API で、PHP でマルチスレッド処理を行うのに必要なすべてのツールを提供します。 PHP アプリケーションで、Thread や Worker そして Threaded を作ったり読み書きしたり実行したりできるようになります。

警告

この拡張モジュールはメンテナンスされておらず、終了していると考えられます。

ヒント

parallel を代わりに使うことも検討してください。

警告

pthreads 拡張モジュールは、Webサーバー環境では使えません。 よって、PHP でのスレッド処理は CLIベースのアプリケーションに限られています。

警告

ptheads (v3) は PHP 7.2+ で使えます。 これは ZTS モードが 7.0 と 7.1 では安全でないためです。

Threaded クラスが、pthreads が実行できる機能のもとになります。 このクラスは同期のメソッドとプログラマにとって便利なインタフェイスをいくつか公開しています。

Thread クラスと使うと、 それを継承し、run メソッドを実装するだけでスレッドを作れます。 あらゆるメンバにスレッドの参照を使ってあらゆるコンテキストで読み書きができます。 また、あらゆるコンテキストが public と protected なメソッドを実行できます。 run メソッドは、この実装オブジェクトが作られたスレッドとは別の、 Thread::start() が呼ばれたスレッドで実行されます。 スレッドを作ったコンテキストだけが、スレッドの start や join を行えます。

Worker クラスは永続的な状態を保持し、 Thread::start() (またはそれを継承したメソッド) を呼んだ時点から オブジェクトがスコープ外に消えるまで、 あるいは明示的に(Worker::shutdown()経由で) shutdown するまで利用できます。 このオブジェクトを参照する任意のコンテキストから、 タスクを(Worker::stack() 経由で)ワーカーに積むことができ、 これを、Worker が別スレッドで実行します。 Worker の run メソッドは、あらゆるオブジェクトがスタックに積まれる前に実行されます。 そのため、オブジェクトで必要となるリソースの初期化に使えます。

Pool クラスを使って、 Threaded オブジェクトを分散させるワーカークラスのグループを作ることができます。 複数スレッドを扱う際に最も簡単かつ効率的な方法です。

警告

Pool クラスは Threaded クラスを継承していません。 そして、Pool ベースのオブジェクトは通常の PHP オブジェクトです。 よって、そのインスタンスをコンテキスト間で共有してはいけません。

Volatile は pthreads v3 で登場した新しいクラスです。 これは Threaded クラスのプロパティを変更可能にするために使います (なぜなら、これらはデフォルトでは変更できないからです) PHP の配列を Threaded コンテキストに保存する目的でも使えます。

同期はスレッドを扱う際に重要な機能です。 pthreads が作る全てのオブジェクトには (Java プログラマーならおなじみの) Threaded::wait() と Threaded::notify() による同期処理が組み込まれています。 あるオブジェクトの Threaded::wait() を呼ぶと、 別のコンテキストから同じオブジェクトの Threaded::notify() が呼ばれるのを待つようになります。 これを使えば、PHP 内のスレッド化されたオブジェクト (Threaded Object) どうしで強力な同期処理ができるようになります。

警告

マルチスレッドで実行されるあらゆるオブジェクトは Threaded を継承すべきです。

データストレージ: 目安として、シリアライズ可能なデータ型なら何でも、スレッド化されたオブジェクトのメンバーとして使えます。 そのオブジェクトへの参照を持つあらゆるコンテキストから、メンバーの読み書きができます。 すべてのデータ型がシリアライズされるわけではなく、基本型はそのままの形式で格納されます。 それ以外の複雑な型や配列、スレッド化されていないオブジェクトは、シリアライズして格納されます。 これらは、参照を持つ任意のコンテキストから、スレッド化されたオブジェクトへの読み書きができます。 スレッド化されたオブジェクトを例外として、 あるスレッド化されたオブジェクトのメンバーを設定するために使うあらゆる参照は、 そのスレッド化されたオブジェクト内の参照とは区別されます。 同じデータを、いつでもどのコンテキストからでも、 スレッド化されたオブジェクトから直接読み込めます。

static メンバー: 新しいコンテキスト (Thread あるいは Worker) を作るときには、一般的にそれらはコピーされます。 しかし、リソースおよび内部状態を持つオブジェクトは、安全性を考慮して null 化されます。 これを、一種のスレッドローカルストレージとして使えます。 たとえば、データベースサーバーへの接続情報と接続そのものをstatic なメンバーとして持つクラスがあるとします。 コンテキストを開始するときには接続情報だけがコピーされ、接続自体はコピーされません。 新しいコンテキスト上ではそのコンテキストを作ったオブジェクトと同じ方法で接続を立ち上げることができ、 その接続を同じ場所に格納しても元のコンテキストには何も影響を及ぼしません。

警告

print_r や var_dump などのオブジェクトのデバッグ用関数を実行するきには、 再帰の制限が含まれません。

注意:

リソース: PHP のリソースを定義している拡張モジュールは、この手の環境で扱うには不十分です。 pthreads はリソースをコンテキスト間で共有するための対策を用意していますが、 大半のリソース型は安全には扱えません。 コンテキスト間でリソースを共有するときには、いくら注意してもしすぎることはありません。

警告

pthreads を実行する環境下では、安定した環境を提供するためにいくつかの制約と限界があります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • pthreads
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

pthreads を使うには、ビルド時に ZTS (Zend Thread Safety) を有効 (--enable-zts を指定。 PHP 8.0.0 より前のバージョン、かつ Windows 以外のバージョンの場合は、 --enable-maintainer-zts を指定) にする必要があります。

警告

ZTS はビルド時の設定オプションです。ビルドした後で変更することはできません。

pthreads は、Posix スレッドのヘッダファイル (pthread.h) と ZTS 版の PHP があればどこでもビルドできます。 Windows でもビルド可能で、その際には redhat の pthread-w32 プロジェクトを利用します。


インストール手順

pthreads のリリースは PECL でホストされており、ソースコードは » github にあります。 最も簡単なインストール方法は、PECL の » https://pecl.php.net/package/pthreads からのインストールです。

Windows ユーザー用のビルド済みバイナリは、» PECL のウェブサイトからダウンロードできます。

警告

Windows ユーザーはさらに、pthreadVC2.dll (Windows 版のリリースに含まれています) をパスの通った場所に置くという作業も必要です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PTHREADS_INHERIT_ALL (int)
The default options for all Threads, causes pthreads to copy the environment when new Threads are started
PTHREADS_INHERIT_NONE (int)
Do not inherit anything when new Threads are started
PTHREADS_INHERIT_INI (int)
Inherit INI entries when new Threads are started
PTHREADS_INHERIT_CONSTANTS (int)
Inherit user declared constants when new Threads are started
PTHREADS_INHERIT_CLASSES (int)
Inherit user declared classes when new Threads are started
PTHREADS_INHERIT_FUNCTIONS (int)
Inherit user declared functions when new Threads are started
PTHREADS_INHERIT_INCLUDES (int)
Inherit included file information when new Threads are started
PTHREADS_INHERIT_COMMENTS (int)
Inherit all comments when new Threads are started
PTHREADS_ALLOW_HEADERS (int)
Allow new Threads to send headers to standard output (normally prohibited)


The Threaded class

(PECL pthreads >= 2.0.0)

はじめに

Threaded objects form the basis of pthreads ability to execute user code in parallel; they expose synchronization methods and various useful interfaces.

Threaded objects, most importantly, provide implicit safety for the programmer; all operations on the object scope are safe.

クラス概要

class Threaded implements Collectable, Traversable, Countable, ArrayAccess {
/* メソッド */
public chunk(int $size, bool $preserve): array
public count(): int
public extend(string $class): bool
public isRunning(): bool
public isTerminated(): bool
public merge(mixed $from, bool $overwrite = ?): bool
public notify(): bool
public notifyOne(): bool
public pop(): bool
public run(): void
public shift(): mixed
public synchronized(Closure $block, mixed ...$args): mixed
public wait(int $timeout = ?): bool
}

目次

  • Threaded::chunk — Manipulation
  • Threaded::count — Manipulation
  • Threaded::extend — Runtime Manipulation
  • Threaded::isRunning — State Detection
  • Threaded::isTerminated — State Detection
  • Threaded::merge — Manipulation
  • Threaded::notify — Synchronization
  • Threaded::notifyOne — Synchronization
  • Threaded::pop — Manipulation
  • Threaded::run — Execution
  • Threaded::shift — Manipulation
  • Threaded::synchronized — Synchronization
  • Threaded::wait — Synchronization


Manipulation

  • ≪ Threaded
  • Threaded::count ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::chunk

(PECL pthreads >= 2.0.0)

Threaded::chunk — Manipulation

説明

public Threaded::chunk(int $size, bool $preserve): array

Fetches a chunk of the objects property table of the given size, optionally preserving keys

パラメータ

size

The number of items to fetch

preserve

Preserve the keys of members, by default false

戻り値

An array of items from the objects property table

例

例1 Fetch a chunk of the property table

<?php
$safe = new Threaded();

while (count($safe) < 10) {
$safe[] = count($safe);
}

var_dump($safe->chunk(5));
?>

上の例の出力は以下となります。

array(5) {
  [0]=>
  int(0)
  [1]=>
  int(1)
  [2]=>
  int(2)
  [3]=>
  int(3)
  [4]=>
  int(4)
}


Manipulation

  • ≪ Threaded::chunk
  • Threaded::extend ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::count

(PECL pthreads >= 2.0.0)

Threaded::count — Manipulation

説明

public Threaded::count(): int

Returns the number of properties for this object

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Counting the properties of an object

<?php
$safe = new Threaded();

while (count($safe) < 10) {
$safe[] = count($safe);
}

var_dump(count($safe));
?>

上の例の出力は以下となります。

int(10)


Runtime Manipulation

  • ≪ Threaded::count
  • Threaded::isRunning ≫
  • PHP Manual
  • Threaded
  • Runtime Manipulation

Threaded::extend

(PECL pthreads >= 2.0.8)

Threaded::extend — Runtime Manipulation

説明

public Threaded::extend(string $class): bool

Makes thread safe standard class at runtime

パラメータ

class

The class to extend

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Runtime inheritance

<?php
class My {}

Threaded::extend(My::class);

$my = new My();

var_dump($my instanceof Threaded);
?>

上の例の出力は以下となります。

bool(true)


State Detection

  • ≪ Threaded::extend
  • Threaded::isTerminated ≫
  • PHP Manual
  • Threaded
  • State Detection

Threaded::isRunning

(PECL pthreads >= 2.0.0)

Threaded::isRunning — State Detection

説明

public Threaded::isRunning(): bool

Tell if the referenced object is executing

パラメータ

この関数にはパラメータはありません。

戻り値

A boolean indication of state

注意:

A object is considered running while executing the run method

例

例1 Detect the state of the referenced object

<?php
class My extends Thread {
public function run() {
$this->synchronized(function($thread){
if (!$thread->done)
$thread->wait();
}, $this);
}
}
$my = new My();
$my->start();
var_dump($my->isRunning());
$my->synchronized(function($thread){
$thread->done = true;
$thread->notify();
}, $my);
?>

上の例の出力は以下となります。

bool(true)


State Detection

  • ≪ Threaded::isRunning
  • Threaded::merge ≫
  • PHP Manual
  • Threaded
  • State Detection

Threaded::isTerminated

(PECL pthreads >= 2.0.0)

Threaded::isTerminated — State Detection

説明

public Threaded::isTerminated(): bool

Tell if the referenced object was terminated during execution; suffered fatal errors, or threw uncaught exceptions

パラメータ

この関数にはパラメータはありません。

戻り値

A boolean indication of state

例

例1 Detect the state of the referenced object

<?php
class My extends Thread {
public function run() {
i_do_not_exist();
}
}
$my = new My();
$my->start();
$my->join();
var_dump($my->isTerminated());
?>

上の例の出力は以下となります。

bool(true)


Manipulation

  • ≪ Threaded::isTerminated
  • Threaded::notify ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::merge

(PECL pthreads >= 2.0.0)

Threaded::merge — Manipulation

説明

public Threaded::merge(mixed $from, bool $overwrite = ?): bool

Merges data into the current object

パラメータ

from

The data to merge

overwrite

Overwrite existing keys, by default true

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Merging into the property table of a threaded object

<?php
$array = [];

while (count($array) < 10)
$array[] = count($array);

$stdClass = new stdClass();
$stdClass->foo = "foo";
$stdClass->bar = "bar";
$stdClass->baz = "baz";

$safe = new Threaded();
$safe->merge($array);

$safe->foo = "bar";
$safe->merge($stdClass, false);

var_dump($safe);
?>

上の例の出力は以下となります。

object(Threaded)#2 (13) {
  ["0"]=>
  int(0)
  ["1"]=>
  int(1)
  ["2"]=>
  int(2)
  ["3"]=>
  int(3)
  ["4"]=>
  int(4)
  ["5"]=>
  int(5)
  ["6"]=>
  int(6)
  ["7"]=>
  int(7)
  ["8"]=>
  int(8)
  ["9"]=>
  int(9)
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "bar"
  ["baz"]=>
  string(3) "baz"
}


Synchronization

  • ≪ Threaded::merge
  • Threaded::notifyOne ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::notify

(PECL pthreads >= 2.0.0)

Threaded::notify — Synchronization

説明

public Threaded::notify(): bool

Send notification to the referenced object

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Notifications and Waiting

<?php
class My extends Thread {
public function run() {
/** cause this thread to wait **/
$this->synchronized(function($thread){
if (!$thread->done)
$thread->wait();
}, $this);
}
}
$my = new My();
$my->start();
/** send notification to the waiting thread **/
$my->synchronized(function($thread){
$thread->done = true;
$thread->notify();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)


Synchronization

  • ≪ Threaded::notify
  • Threaded::pop ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::notifyOne

(PECL pthreads >= 3.0.0)

Threaded::notifyOne — Synchronization

説明

public Threaded::notifyOne(): bool

Send notification to the referenced object. This unblocks at least one of the blocked threads (as opposed to unblocking all of them, as seen with Threaded::notify()).

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Notifications and Waiting

<?php
class My extends Thread {
public function run() {
/** cause this thread to wait **/
$this->synchronized(function($thread){
if (!$thread->done)
$thread->wait();
}, $this);
}
}
$my = new My();
$my->start();
/** send notification to the waiting thread **/
$my->synchronized(function($thread){
$thread->done = true;
$thread->notifyOne();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)


Manipulation

  • ≪ Threaded::notifyOne
  • Threaded::run ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::pop

(PECL pthreads >= 2.0.0)

Threaded::pop — Manipulation

説明

public Threaded::pop(): bool

Pops an item from the objects property table

パラメータ

この関数にはパラメータはありません。

戻り値

The last item from the objects property table

例

例1 Popping the last item from the property table of a threaded object

<?php
$safe = new Threaded();

while (count($safe) < 10)
$safe[] = count($safe);

var_dump($safe->pop());
?>

上の例の出力は以下となります。

int(9)


Execution

  • ≪ Threaded::pop
  • Threaded::shift ≫
  • PHP Manual
  • Threaded
  • Execution

Threaded::run

(PECL pthreads >= 2.0.0)

Threaded::run — Execution

説明

public Threaded::run(): void

The programmer should always implement the run method for objects that are intended for execution.

パラメータ

この関数にはパラメータはありません。

戻り値

The methods return value, if used, will be ignored


Manipulation

  • ≪ Threaded::run
  • Threaded::synchronized ≫
  • PHP Manual
  • Threaded
  • Manipulation

Threaded::shift

(PECL pthreads >= 2.0.0)

Threaded::shift — Manipulation

説明

public Threaded::shift(): mixed

Shifts an item from the objects property table

パラメータ

この関数にはパラメータはありません。

戻り値

The first item from the objects property table

例

例1 Shifting the first item from the property table of a threaded object

<?php
$safe = new Threaded();

while (count($safe) < 10)
$safe[] = count($safe);

var_dump($safe->shift());
?>

上の例の出力は以下となります。

int(0)


Synchronization

  • ≪ Threaded::shift
  • Threaded::wait ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::synchronized

(PECL pthreads >= 2.0.0)

Threaded::synchronized — Synchronization

説明

public Threaded::synchronized(Closure $block, mixed ...$args): mixed

Executes the block while retaining the referenced objects synchronization lock for the calling context

パラメータ

block

The block of code to execute

args

Variable length list of arguments to use as function arguments to the block

戻り値

The return value from the block

例

例1 Synchronizing

<?php
class My extends Thread {
public function run() {
$this->synchronized(function($thread){
if (!$thread->done)
$thread->wait();
}, $this);
}
}
$my = new My();
$my->start();
$my->synchronized(function($thread){
$thread->done = true;
$thread->notify();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)


Synchronization

  • ≪ Threaded::synchronized
  • Thread ≫
  • PHP Manual
  • Threaded
  • Synchronization

Threaded::wait

(PECL pthreads >= 2.0.0)

Threaded::wait — Synchronization

説明

public Threaded::wait(int $timeout = ?): bool

Will cause the calling context to wait for notification from the referenced object

パラメータ

timeout

An optional timeout in microseconds

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Notifications and Waiting

<?php
class My extends Thread {
public function run() {
/** cause this thread to wait **/
$this->synchronized(function($thread){
if (!$thread->done)
$thread->wait();
}, $this);
}
}
$my = new My();
$my->start();
/** send notification to the waiting thread **/
$my->synchronized(function($thread){
$thread->done = true;
$thread->notify();
}, $my);
var_dump($my->join());
?>

上の例の出力は以下となります。

bool(true)


Thread クラス

(PECL pthreads >= 2.0.0)

はじめに

このオブジェクトの start メソッドが呼ばれると、run メソッドのコードが個別のスレッドで並列処理されます。

run メソッドの実行後は Thread はすぐに終了し、作成元のスレッドに適切な時期に join します。

警告

Thread をいつ join させるのかをエンジンに決めさせていると、予期せぬ振る舞いを引き起こすことがあります。 可能な限り、プログラマーが明示的に指定するようにしましょう。

クラス概要

class Thread extends Threaded implements Countable, Traversable, ArrayAccess {
/* メソッド */
public getCreatorId(): int
public static getCurrentThread(): Thread
public static getCurrentThreadId(): int
public getThreadId(): int
public isJoined(): bool
public isStarted(): bool
public join(): bool
public start(int $options = ?): bool
/* 継承したメソッド */
public Threaded::chunk(int $size, bool $preserve): array
public Threaded::count(): int
public Threaded::extend(string $class): bool
public Threaded::isRunning(): bool
public Threaded::isTerminated(): bool
public Threaded::merge(mixed $from, bool $overwrite = ?): bool
public Threaded::notify(): bool
public Threaded::notifyOne(): bool
public Threaded::pop(): bool
public Threaded::run(): void
public Threaded::shift(): mixed
public Threaded::synchronized(Closure $block, mixed ...$args): mixed
public Threaded::wait(int $timeout = ?): bool
}

目次

  • Thread::getCreatorId — 識別
  • Thread::getCurrentThread — Identification
  • Thread::getCurrentThreadId — Identification
  • Thread::getThreadId — 識別
  • Thread::isJoined — 状態を検出する
  • Thread::isStarted — 状態を検出する
  • Thread::join — 同期処理
  • Thread::start — 実行する


識別

  • ≪ Thread
  • Thread::getCurrentThread ≫
  • PHP Manual
  • Thread
  • 識別

Thread::getCreatorId

(PECL pthreads >= 2.0.0)

Thread::getCreatorId — 識別

説明

public Thread::getCreatorId(): int

このスレッドを作ったスレッドの ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

数値の ID を返します。

例

例1 このスレッドを作ったスレッドあるいはプロセスの ID を返す

<?php
class My extends Thread {
public function run() {
printf("%s created by Thread #%lu\n", __CLASS__, $this->getCreatorId());
}
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

My created by Thread #123456778899


Identification

  • ≪ Thread::getCreatorId
  • Thread::getCurrentThreadId ≫
  • PHP Manual
  • Thread
  • Identification

Thread::getCurrentThread

(PECL pthreads >= 2.0.0)

Thread::getCurrentThread — Identification

説明

public static Thread::getCurrentThread(): Thread

Return a reference to the currently executing Thread

パラメータ

この関数にはパラメータはありません。

戻り値

An object representing the currently executing Thread

例

例1 Return the currently executing Thread

<?php
class My extends Thread {
public function run() {
var_dump(Thread::getCurrentThread());
}
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

object(My)#2 (0) {
}


Identification

  • ≪ Thread::getCurrentThread
  • Thread::getThreadId ≫
  • PHP Manual
  • Thread
  • Identification

Thread::getCurrentThreadId

(PECL pthreads >= 2.0.0)

Thread::getCurrentThreadId — Identification

説明

public static Thread::getCurrentThreadId(): int

Will return the identity of the currently executing Thread

パラメータ

この関数にはパラメータはありません。

戻り値

A numeric identity

例

例1 Return the identity of the currently executing Thread

<?php
class My extends Thread {
public function run() {
printf("%s is Thread #%lu\n", __CLASS__, Thread::getCurrentThreadId());
}
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

My is Thread #123456778899


識別

  • ≪ Thread::getCurrentThreadId
  • Thread::isJoined ≫
  • PHP Manual
  • Thread
  • 識別

Thread::getThreadId

(PECL pthreads >= 2.0.0)

Thread::getThreadId — 識別

説明

public Thread::getThreadId(): int

このスレッドの ID を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

数値の ID を返します。

例

例1 このスレッドの ID を返す

<?php
class My extends Thread {
public function run() {
printf("%s is Thread #%lu\n", __CLASS__, $this->getThreadId());
}
}
$my = new My();
$my->start();
?>

上の例の出力は以下となります。

My is Thread #123456778899


状態を検出する

  • ≪ Thread::getThreadId
  • Thread::isStarted ≫
  • PHP Manual
  • Thread
  • 状態を検出する

Thread::isJoined

(PECL pthreads >= 2.0.0)

Thread::isJoined — 状態を検出する

説明

public Thread::isJoined(): bool

このスレッドが同期されているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 スレッドの状態を検出する

<?php
class My extends Thread {
public function run() {
$this->synchronized(function($thread){
if (!$thread->done)
$thread->wait();
}, $this);
}
}
$my = new My();
$my->start();
var_dump($my->isJoined());
$my->synchronized(function($thread){
$thread->done = true;
$thread->notify();
}, $my);
?>

上の例の出力は以下となります。

bool(false)


状態を検出する

  • ≪ Thread::isJoined
  • Thread::join ≫
  • PHP Manual
  • Thread
  • 状態を検出する

Thread::isStarted

(PECL pthreads >= 2.0.0)

Thread::isStarted — 状態を検出する

説明

public Thread::isStarted(): bool

このスレッドが開始したかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 スレッドが開始したかどうかを検出する

<?php
$worker = new Worker();
$worker->start();
var_dump($worker->isStarted());
?>

上の例の出力は以下となります。

bool(true)


同期処理

  • ≪ Thread::isStarted
  • Thread::start ≫
  • PHP Manual
  • Thread
  • 同期処理

Thread::join

(PECL pthreads >= 2.0.0)

Thread::join — 同期処理

説明

public Thread::join(): bool

呼び出し元のコンテキストが、このスレッドの実行終了を待つようにします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 スレッドとのジョイン

<?php
class My extends Thread {
public function run() {
/* ... */
}
}
$my = new My();
$my->start();
/* ... */
var_dump($my->join());
/* ... */
?>

上の例の出力は以下となります。

bool(true)


実行する

  • ≪ Thread::join
  • Worker ≫
  • PHP Manual
  • Thread
  • 実行する

Thread::start

(PECL pthreads >= 2.0.0)

Thread::start — 実行する

説明

public Thread::start(int $options = ?): bool

新しいスレッドを開始し、実装されている run メソッドを実行します。

パラメータ

options

オプションのマスク。継承に関する定数で、デフォルトは PTHREADS_INHERIT_ALL。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 スレッドの開始

<?php
class My extends Thread {
public function run() {
/** ... **/
}
}
$my = new My();
var_dump($my->start());
?>

上の例の出力は以下となります。

bool(true)


Worker クラス

(PECL pthreads >= 2.0.0)

はじめに

ワーカースレッドには永続コンテキストがあり、たいていの場合はスレッドに対して使えます。

ワーカーを開始させると run メソッドを実行しますが、以下のいずれかの条件を満たすまでスレッドは終了しません。

  • Worker がスコープから外れる (どこからも参照されなくなる)

  • プログラマーが shutdown を呼ぶ

  • スクリプトが終了する

つまり、プログラマーは実行中のコンテキストを再利用できるということです。 オブジェクトを Worker のスタックに置くと、そのオブジェクトの run メソッドを Worker が実行します。

クラス概要

class Worker extends Thread implements Traversable, Countable, ArrayAccess {
/* メソッド */
public collect(Callable $collector = ?): int
public getStacked(): int
public isShutdown(): bool
public shutdown(): bool
public stack(Threaded &$work): int
public unstack(): int
/* 継承したメソッド */
public Thread::getCreatorId(): int
public static Thread::getCurrentThread(): Thread
public static Thread::getCurrentThreadId(): int
public Thread::getThreadId(): int
public Thread::isJoined(): bool
public Thread::isStarted(): bool
public Thread::join(): bool
public Thread::start(int $options = ?): bool
}

目次

  • Worker::collect — Collect references to completed tasks
  • Worker::getStacked — Gets the remaining stack size
  • Worker::isShutdown — State Detection
  • Worker::shutdown — Shutdown the worker
  • Worker::stack — Stacking work
  • Worker::unstack — Unstacking work


Collect references to completed tasks

  • ≪ Worker
  • Worker::getStacked ≫
  • PHP Manual
  • Worker
  • Collect references to completed tasks

Worker::collect

(PECL pthreads >= 3.0.0)

Worker::collect — Collect references to completed tasks

説明

public Worker::collect(Callable $collector = ?): int

Allows the worker to collect references determined to be garbage by the optionally given collector.

パラメータ

collector

A Callable collector that returns a boolean on whether the task can be collected or not. Only in rare cases should a custom collector need to be used.

戻り値

The number of remaining tasks on the worker's stack to be collected.

例

例1 A basic example of Worker::collect()

<?php
$worker = new Worker();

echo "There are currently {$worker->collect()} tasks on the stack to be collected\n";

for ($i = 0; $i < 15; ++$i) {
$worker->stack(new class extends Threaded {});
}

echo "There are {$worker->collect()} tasks remaining on the stack to be collected\n";

$worker->start();

while ($worker->collect()); // blocks until all tasks have finished executing

echo "There are now {$worker->collect()} tasks on the stack to be collected\n";

$worker->shutdown();

上の例の出力は以下となります。

There are currently 0 tasks on the stack to be collected
There are 15 tasks remaining on the stack to be collected
There are now 0 tasks on the stack to be collected


Gets the remaining stack size

  • ≪ Worker::collect
  • Worker::isShutdown ≫
  • PHP Manual
  • Worker
  • Gets the remaining stack size

Worker::getStacked

(PECL pthreads >= 2.0.0)

Worker::getStacked — Gets the remaining stack size

説明

public Worker::getStacked(): int

Returns the number of tasks left on the stack

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of tasks currently waiting to be executed by the worker

例

例1 A basic example of Worker::getStacked

<?php
$worker = new Worker();

for ($i = 0; $i < 5; ++$i) {
$worker->stack(new class extends Threaded {});
}

echo "There are {$worker->getStacked()} stacked tasks\n";

上の例の出力は以下となります。

There are 5 stacked tasks


State Detection

  • ≪ Worker::getStacked
  • Worker::shutdown ≫
  • PHP Manual
  • Worker
  • State Detection

Worker::isShutdown

(PECL pthreads >= 2.0.0)

Worker::isShutdown — State Detection

説明

public Worker::isShutdown(): bool

Whether the worker has been shutdown or not.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns whether the worker has been shutdown or not.

例

例1 Detect the state of a worker

<?php
$worker = new Worker();
$worker->start();

var_dump($worker->isShutdown());

$worker->shutdown();

var_dump($worker->isShutdown());

上の例の出力は以下となります。

bool(false)
bool(true)


Shutdown the worker

  • ≪ Worker::isShutdown
  • Worker::stack ≫
  • PHP Manual
  • Worker
  • Shutdown the worker

Worker::shutdown

(PECL pthreads >= 2.0.0)

Worker::shutdown — Shutdown the worker

説明

public Worker::shutdown(): bool

Shuts down the worker after executing all of the stacked tasks.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Shutdown the referenced worker

<?php
$my = new Worker();
$my->start();
/* stack/execute tasks */
var_dump($my->shutdown());

上の例の出力は以下となります。

bool(true)


Stacking work

  • ≪ Worker::shutdown
  • Worker::unstack ≫
  • PHP Manual
  • Worker
  • Stacking work

Worker::stack

(PECL pthreads >= 2.0.0)

Worker::stack — Stacking work

説明

public Worker::stack(Threaded &$work): int

Appends the new work to the stack of the referenced worker.

パラメータ

work

A Threaded object to be executed by the worker.

戻り値

The new size of the stack.

例

例1 Stacking a task for execution onto a worker

<?php
$worker = new Worker();
$work = new class extends Threaded {};

var_dump($worker->stack($work));

上の例の出力は以下となります。

int(1)


Unstacking work

  • ≪ Worker::stack
  • Collectable ≫
  • PHP Manual
  • Worker
  • Unstacking work

Worker::unstack

(PECL pthreads >= 2.0.0)

Worker::unstack — Unstacking work

説明

public Worker::unstack(): int

Removes the first task (the oldest one) in the stack.

パラメータ

この関数にはパラメータはありません。

戻り値

The new size of the stack.

変更履歴

バージョン | 説明
v3 | The parameter to specify the task to unstack has been removed. Now, only the first task in the stack is removed.

例

例1 Removing objects from the stack of Workers

<?php
$my = new Worker();
$work = new class extends Threaded {};

var_dump($my->stack($work));
var_dump($my->unstack());

上の例の出力は以下となります。

int(1)
int(0)


The Collectable interface

(PECL pthreads >= 2.0.8)

はじめに

Represents a garbage-collectable object.

インターフェイス概要

interface Collectable {
/* メソッド */
public isGarbage(): true
}

目次

  • Collectable::isGarbage — Determine whether an object has been marked as garbage


Determine whether an object has been marked as garbage

  • ≪ Collectable
  • Pool ≫
  • PHP Manual
  • Collectable
  • Determine whether an object has been marked as garbage

Collectable::isGarbage

(PECL pthreads >= 2.0.8)

Collectable::isGarbage — Determine whether an object has been marked as garbage

説明

public Collectable::isGarbage(): true

Can be called in Pool::collect() to determine if this object is garbage.

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • Pool::collect() - Collect references to completed tasks


The Pool class

(PECL pthreads >= 2.0.0)

はじめに

A Pool is a container for, and controller of, an adjustable number of Workers.

Pooling provides a higher level abstraction of the Worker functionality, including the management of references in the way required by pthreads.

クラス概要

class Pool {
/* プロパティ */
protected $size;
protected $class;
protected $workers;
protected $ctor;
protected $last;
/* メソッド */
public __construct(int $size, string $class = ?, array $ctor = ?)
public collect(Callable $collector = ?): int
public resize(int $size): void
public shutdown(): void
public submit(Threaded $task): int
public submitTo(int $worker, Threaded $task): int
}

プロパティ

size

maximum number of Workers this Pool can use

class

the class of the Worker

workers

references to Workers

ctor

the arguments for constructor of new Workers

last

offset in workers of the last Worker used

目次

  • Pool::collect — Collect references to completed tasks
  • Pool::__construct — Creates a new Pool of Workers
  • Pool::resize — Resize the Pool
  • Pool::shutdown — Shutdown all workers
  • Pool::submit — Submits an object for execution
  • Pool::submitTo — Submits a task to a specific worker for execution


Collect references to completed tasks

  • ≪ Pool
  • Pool::__construct ≫
  • PHP Manual
  • Pool
  • Collect references to completed tasks

Pool::collect

(PECL pthreads >= 2.0.0)

Pool::collect — Collect references to completed tasks

説明

public Pool::collect(Callable $collector = ?): int

Allows the pool to collect references determined to be garbage by the optionally given collector.

パラメータ

collector

A Callable collector that returns a boolean on whether the task can be collected or not. Only in rare cases should a custom collector need to be used.

戻り値

The number of remaining tasks in the pool to be collected.

変更履歴

バージョン | 説明
v3 | An integer is now returned, and the collector parameter is now optional.

例

例1 A basic example of Pool::collect()

<?php
$pool = new Pool(4);

for ($i = 0; $i < 15; ++$i) {
$pool->submit(new class extends Threaded {});
}

while ($pool->collect()); // blocks until all tasks have finished executing

$pool->shutdown();


Creates a new Pool of Workers

  • ≪ Pool::collect
  • Pool::resize ≫
  • PHP Manual
  • Pool
  • Creates a new Pool of Workers

Pool::__construct

(PECL pthreads >= 2.0.0)

Pool::__construct — Creates a new Pool of Workers

説明

public Pool::__construct(int $size, string $class = ?, array $ctor = ?)

Construct a new pool of workers. Pools lazily create their threads, which means new threads will only be spawned when they are required to execute tasks.

パラメータ

size

The maximum number of workers for this pool to create

class

The class for new Workers. If no class is given, then it defaults to the Worker class.

ctor

An array of arguments to be passed to new workers' constructors

例

例1 Creating Pools

<?php
class MyWorker extends Worker {

public function __construct(Something $something) {
$this->something = $something;
}

public function run() {
/** ... **/
}
}

$pool = new Pool(8, \MyWorker::class, [new Something()]);

var_dump($pool);
?>

上の例の出力は以下となります。

object(Pool)#1 (6) {
  ["size":protected]=>
  int(8)
  ["class":protected]=>
  string(8) "MyWorker"
  ["workers":protected]=>
  NULL
  ["work":protected]=>
  NULL
  ["ctor":protected]=>
  array(1) {
    [0]=>
    object(Something)#2 (0) {
    }
  }
  ["last":protected]=>
  int(0)
}


Resize the Pool

  • ≪ Pool::__construct
  • Pool::shutdown ≫
  • PHP Manual
  • Pool
  • Resize the Pool

Pool::resize

(PECL pthreads >= 2.0.0)

Pool::resize — Resize the Pool

説明

public Pool::resize(int $size): void

Resize the Pool

パラメータ

size

The maximum number of Workers this Pool can create

戻り値

値を返しません。


Shutdown all workers

  • ≪ Pool::resize
  • Pool::submit ≫
  • PHP Manual
  • Pool
  • Shutdown all workers

Pool::shutdown

(PECL pthreads >= 2.0.0)

Pool::shutdown — Shutdown all workers

説明

public Pool::shutdown(): void

Shuts down all of the workers in the pool. This will block until all submitted tasks have been executed.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Shutting down a pool

<?php
class Task extends Threaded
{
public function run()
{
usleep(500000);
}
}

$pool = new Pool(4);

for ($i = 0; $i < 10; ++$i) {
$pool->submit(new Task());
}

$pool->shutdown(); // blocks until all submitted tasks have finished executing


Submits an object for execution

  • ≪ Pool::shutdown
  • Pool::submitTo ≫
  • PHP Manual
  • Pool
  • Submits an object for execution

Pool::submit

(PECL pthreads >= 2.0.0)

Pool::submit — Submits an object for execution

説明

public Pool::submit(Threaded $task): int

Submit the task to the next Worker in the Pool

パラメータ

task

The task for execution

戻り値

the identifier of the Worker executing the object

例

例1 Submitting Tasks

<?php
class MyWork extends Threaded {

public function run() {
/* ... */
}
}

class MyWorker extends Worker {

public function __construct(Something $something) {
$this->something = $something;
}

public function run() {
/** ... **/
}
}

$pool = new Pool(8, \MyWorker::class, [new Something()]);
$pool->submit(new MyWork());
var_dump($pool);
?>

上の例の出力は以下となります。

object(Pool)#1 (6) {
  ["size":protected]=>
  int(8)
  ["class":protected]=>
  string(8) "MyWorker"
  ["workers":protected]=>
  array(1) {
    [0]=>
    object(MyWorker)#4 (1) {
      ["something"]=>
      object(Something)#5 (0) {
      }
    }
  }
  ["work":protected]=>
  array(1) {
    [0]=>
    object(MyWork)#3 (1) {
      ["worker"]=>
      object(MyWorker)#5 (1) {
        ["something"]=>
        object(Something)#6 (0) {
        }
      }
    }
  }
  ["ctor":protected]=>
  array(1) {
    [0]=>
    object(Something)#2 (0) {
    }
  }
  ["last":protected]=>
  int(1)
}


Submits a task to a specific worker for execution

  • ≪ Pool::submit
  • Volatile ≫
  • PHP Manual
  • Pool
  • Submits a task to a specific worker for execution

Pool::submitTo

(PECL pthreads >= 2.0.0)

Pool::submitTo — Submits a task to a specific worker for execution

説明

public Pool::submitTo(int $worker, Threaded $task): int

Submit a task to the specified worker in the pool. The workers are indexed from 0, and will only exist if the pool has needed to create them (since threads are lazily spawned).

パラメータ

worker

The worker to stack the task onto, indexed from 0.

task

The task for execution.

戻り値

The identifier of the worker that accepted the task.

例

例1 Submitting tasks to a specific worker

<?php
class Task extends Threaded {
public function run() {
var_dump(Thread::getCurrentThreadID());
}
}

$pool = new Pool(2);

$pool->submit(new Task());

for ($i = 0; $i < 5; ++$i) {
$pool->submitTo(0, new Task()); // stack all tasks onto the first worker
}

$pool->submitTo(1, new Task()); // cannot stack the task onto the second worker due to it not existing yet

$pool->shutdown();

上の例の出力は以下となります。

int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)

Fatal error: Uncaught Exception: The selected worker (1) does not exist in %s:%d


The Volatile class

(PECL pthreads >= 3.0.0)

はじめに

The Volatile class is new to pthreads v3. Its introduction is a consequence of the new immutability semantics of Threaded members of Threaded classes. The Volatile class enables for mutability of its Threaded members, and is also used to store PHP arrays in Threaded contexts.

クラス概要

class Volatile extends Threaded implements Collectable, Traversable {
/* 継承したメソッド */
public Threaded::chunk(int $size, bool $preserve): array
public Threaded::count(): int
public Threaded::extend(string $class): bool
public Threaded::isRunning(): bool
public Threaded::isTerminated(): bool
public Threaded::merge(mixed $from, bool $overwrite = ?): bool
public Threaded::notify(): bool
public Threaded::notifyOne(): bool
public Threaded::pop(): bool
public Threaded::run(): void
public Threaded::shift(): mixed
public Threaded::synchronized(Closure $block, mixed ...$args): mixed
public Threaded::wait(int $timeout = ?): bool
}

例

例1 New immutability semantics of Threaded

<?php

class Task extends Threaded
{
public function __construct()
{
$this->data = new Threaded();

// attempt to overwrite a Threaded property of a Threaded class (invalid)
$this->data = new stdClass();
}
}

var_dump((new Task())->data);

上の例の出力は、 たとえば以下のようになります。

RuntimeException: Threaded members previously set to Threaded objects are immutable, cannot overwrite data in %s:%d

例2 Volatile use-case

<?php

class Task extends Volatile
{
public function __construct()
{
$this->data = new Threaded();

// attempt to overwrite a Threaded property of a Volatile class (valid)
$this->data = new stdClass();
}
}

var_dump((new Task())->data);

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#3 (0) {
}


セマフォ、共有メモリおよび IPC

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • セマフォ関数
    • ftok — パス名とプロジェクト ID を、System V IPC キーに変換する
    • msg_get_queue — メッセージキューを作成またはそれにアタッチする
    • msg_queue_exists — メッセージキューが存在するかどうかを調べる
    • msg_receive — メッセージキューからメッセージを受信する
    • msg_remove_queue — メッセージキューを破棄する
    • msg_send — メッセージキューにメッセージを送信する
    • msg_set_queue — メッセージキューデータ構造体の情報を設定する
    • msg_stat_queue — メッセージキューデータ構造体の情報を返す
    • sem_acquire — セマフォを得る
    • sem_get — セマフォ ID を得る
    • sem_release — セマフォを解放する
    • sem_remove — セマフォを削除する
    • shm_attach — 共有メモリセグメントを作成またはオープンする
    • shm_detach — 共有メモリセグメントへの接続を閉じる
    • shm_get_var — 共有メモリから変数を返す
    • shm_has_var — 特定のエントリが存在するかどうかを調べる
    • shm_put_var — 共有メモリの変数を挿入または更新する
    • shm_remove — Unix システムから共有メモリを削除する
    • shm_remove_var — 共有メモリから変数を削除する
  • SysvMessageQueue — SysvMessageQueue クラス
  • SysvSemaphore — SysvSemaphore クラス
  • SysvSharedMemory — SysvSharedMemory クラス


はじめに

これらのモジュールは、System V IPC 関連の関数へのラッパーを提供します。 セマフォ・共有メモリおよびプロセス間通信(IPC)がその中に含まれます。

セマフォは、マシーン上のリソースへの排他的アクセス機能や、 同時にあるリソースを使用することができるプロセスの数を制限するために 使用することができます。

このモジュールは、System V 共有メモリを使用した共有メモリ関数も 提供します。共有メモリは、グローバル変数へのアクセス手段を提供するために 使用することが可能です。別の httpd デーモンおよび (Perl, C, ... のような)他のプログラムさえ、グローバルデータ交換を 提供するこのデータにアクセスすることが可能です。 共有メモリは、同時アクセスに関して安全ではないということを覚えておいて ください。 同期をとるには、セマフォを使用してください。

Unix OS による共有メモリの制限
SHMMAX | 共有メモリの最大サイズ。通常は 131072 バイト
SHMMIN | 共有メモリの最小サイズ。通常は 1 バイト
SHMMNI | 共有メモリセグメントの最大数。通常は 100
SHMSEG | プロセス毎の共有メモリの最大数。通常は 6

メッセージング関数は、他のプロセスと相互にメッセージを送受信する ために使用することができます。 これにより簡単で効率的なプロセス間のデータ交換が可能であり、 Unix ドメインソケットを用いる場合のような設定は不要です。

注意: 共有メモリ関数と ftok() 関数だけが、Windows で利用可能です。 セマフォとメッセージング関数は、Windows ではサポートされていません。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • セマフォ
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定
  • リソース型


インストール手順

この関数はデフォルトでは有効になってはいません。System V セマフォの サポートを有効にするには、オプション --enable-sysvsem を指定して PHP を コンパイルする必要があります。System V 共有メモリのサポートを有効にするには、 オプション --enable-sysvshm を 指定して PHP をコンパイルする必要があります。System V メッセージを有効に するには、オプション --enable-sysvmsg を指定して PHP をコンパイル します。


実行時設定

php.ini の設定により動作が変化します。

セマフォ設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sysvshm.init_mem | 10000 | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

sysvshm.init_mem int

共有メモリセグメントのデフォルトサイズ。


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張モジュールはリソース型を定義していました。 sysvmsg queue (System V メッセージキュー), sysvsem (System V セマフォ), sysvshm (System V 共有メモリ) です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

MSG_IPC_NOWAIT (int)
MSG_EAGAIN (int)
MSG_ENOMSG (int)
MSG_NOERROR (int)
MSG_EXCEPT (int)


セマフォ関数

目次

  • ftok — パス名とプロジェクト ID を、System V IPC キーに変換する
  • msg_get_queue — メッセージキューを作成またはそれにアタッチする
  • msg_queue_exists — メッセージキューが存在するかどうかを調べる
  • msg_receive — メッセージキューからメッセージを受信する
  • msg_remove_queue — メッセージキューを破棄する
  • msg_send — メッセージキューにメッセージを送信する
  • msg_set_queue — メッセージキューデータ構造体の情報を設定する
  • msg_stat_queue — メッセージキューデータ構造体の情報を返す
  • sem_acquire — セマフォを得る
  • sem_get — セマフォ ID を得る
  • sem_release — セマフォを解放する
  • sem_remove — セマフォを削除する
  • shm_attach — 共有メモリセグメントを作成またはオープンする
  • shm_detach — 共有メモリセグメントへの接続を閉じる
  • shm_get_var — 共有メモリから変数を返す
  • shm_has_var — 特定のエントリが存在するかどうかを調べる
  • shm_put_var — 共有メモリの変数を挿入または更新する
  • shm_remove — Unix システムから共有メモリを削除する
  • shm_remove_var — 共有メモリから変数を削除する


パス名とプロジェクト ID を、System V IPC キーに変換する

  • ≪ セマフォ関数
  • msg_get_queue ≫
  • PHP Manual
  • セマフォ関数
  • パス名とプロジェクト ID を、System V IPC キーに変換する

ftok

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftok — パス名とプロジェクト ID を、System V IPC キーに変換する

説明

ftok(string $filename, string $project_id): int

この関数は、filename で表される既存のアクセス可能なファイルおよびプロジェクト ID (project_id) を、shmop_open() やその他の System V IPC キーで使う integer に変換します。

パラメータ

filename

アクセス可能なファイルへのパス。

project_id

プロジェクト ID。一文字からなる文字列でなければなりません。

戻り値

成功した場合には作成されたキーの値を、それ以外の場合には -1 を返します。

参考

  • shmop_open() - 共有メモリブロックを作成またはオープンする
  • sem_get() - セマフォ ID を得る


メッセージキューを作成またはそれにアタッチする

  • ≪ ftok
  • msg_queue_exists ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューを作成またはそれにアタッチする

msg_get_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_get_queue — メッセージキューを作成またはそれにアタッチする

説明

msg_get_queue(int $key, int $permissions = 0666): SysvMessageQueue|false

msg_get_queue() は、指定した key で System V メッセージキューにアクセスするために使用される ID を返します。 最初にコールされた際には、オプションの permissions でメッセージキューを作成します。同じ key で 2 度目に msg_get_queue() がコールされると別の ID が返されますが、どちらの ID も同じメッセージキューを指します。

パラメータ

key

メッセージキューの数値 ID。

permissions

キューのパーミッション。デフォルトは 0666 です。 メッセージキューがすでに存在する場合には、permissions は無視されます。

戻り値

SysvMessageQueue クラスのインスタンスを返します。System V メッセージキューにアクセスします。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合、 この関数は SysvMessageQueue クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_send() - メッセージキューにメッセージを送信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する


メッセージキューが存在するかどうかを調べる

  • ≪ msg_get_queue
  • msg_receive ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューが存在するかどうかを調べる

msg_queue_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

msg_queue_exists — メッセージキューが存在するかどうかを調べる

説明

msg_queue_exists(int $key): bool

key で指定したメッセージキューが存在するかどうかを調べます。

パラメータ

key

キューのキー。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す


メッセージキューからメッセージを受信する

  • ≪ msg_queue_exists
  • msg_remove_queue ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューからメッセージを受信する

msg_receive

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_receive — メッセージキューからメッセージを受信する

説明

msg_receive(
SysvMessageQueue $queue,
int $desired_message_type,
int &$received_message_type,
int $max_message_size,
mixed &$message,
bool $unserialize = true,
int $flags = 0,
int &$error_code = null
): bool

msg_receive() は、指定した queue から指定した desired_message_type の最初のメッセージを受信します。

パラメータ

queue

メッセージキュー

desired_message_type

desired_message_type が 0 の場合、 キューの先頭にあるメッセージが返されます。desiredmsgtype が 0 より大きな値の場合、その型のメッセージのうち一番最初にあるものが返されます。 desired_message_type が 0 より小さな値の場合、 desired_message_type の絶対値と同じかそれより小さい型のメッセージのうち一番最初にあるものが返されます。 条件を満たすメッセージがない場合は、 条件を満たすメッセージがキューに投入されるまで待ち続けます。 パラメータ flags に MSG_IPC_NOWAIT を指定することで、 ブロックモードではなくすることが可能です。

received_message_type

受信したメッセージの型がこのパラメータに保存されます。

max_message_size

読み込むメッセージの最大サイズは mmax_message_size で指定します。もしキューにあるメッセージのサイズがこれより大きい場合、 (以下で説明する flags が設定されていない限り) この関数は失敗します。

message

エラーが発生しなければ、 受信したメッセージは message に保存されます。

unserialize

このパラメータが true に設定されている場合、 メッセージはセッションモジュールと同様の方法でシリアライズされているものとみなされます。 メッセージは元の状態に復元されたうえでスクリプトに返されます。 これにより、配列やオブジェクト構造体のような複雑な形式のデータを他の PHP スクリプトから簡単に受信することが可能となります。 また、もし WDDX シリアライザを使用しているなら、あらゆる WDDX 互換のソースからデータを受け取ることが可能となります。

unserialize が false の場合、 メッセージはバイナリセーフな文字列として返されます。

flags

オプションの flags により、低レベルの msgrcv システムコールにフラグを渡すことが可能です。デフォルト値は 0 ですが、以下の値のうちのいくつかを(値を足すかあるいは論理和ととることで) 指定することが可能です。

msg_receive のフラグの値
MSG_IPC_NOWAIT | desired_message_type を満たすメッセージが存在しない場合に、 待ち続けずにすぐに結果を返します。 関数は失敗し、MSG_ENOMSG に対応する整数値を返します。
MSG_EXCEPT | このフラグを正の desired_message_type と組み合わせて使用すると、この関数は desired_message_type 以外の型をもつ 最初のメッセージを受信するようになります。
MSG_NOERROR | このフラグを設定しておくと、メッセージが max_message_size より大きい場合に そのメッセージを max_message_size までに切り詰め、 エラーを返しません。

error_code

エラーが発生した場合は、オプションの error_code にシステムの errno 値が設定されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

処理が正常に完了すると、メッセージキューデータ構造体は以下のように更新されます。 msg_lrpid には呼び出し元のプロセス ID が 設定され、msg_qnum が 1 減少し、 msg_rtime が現在の時刻に設定されます。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_send() - メッセージキューにメッセージを送信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する


メッセージキューを破棄する

  • ≪ msg_receive
  • msg_send ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューを破棄する

msg_remove_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_remove_queue — メッセージキューを破棄する

説明

msg_remove_queue(SysvMessageQueue $queue): bool

msg_remove_queue() は、queue で指定したメッセージキューを破棄します。この関数を使用するのは、 すべてのプロセスがメッセージキューの使用を終え、 キューが保持するシステムリソースを開放する必要が生じた場合のみです。

パラメータ

queue

メッセージキュー

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_get_queue() - メッセージキューを作成またはそれにアタッチする
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する


メッセージキューにメッセージを送信する

  • ≪ msg_remove_queue
  • msg_set_queue ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューにメッセージを送信する

msg_send

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_send — メッセージキューにメッセージを送信する

説明

msg_send(
SysvMessageQueue $queue,
int $message_type,
string|int|float|bool $message,
bool $serialize = true,
bool $blocking = true,
int &$error_code = null
): bool

msg_send() は、queue で指定したメッセージキューに対して message_type で指定した型 (0 より大きい数値である必要があります) のメッセージ message を送信します。

パラメータ

queue

メッセージキュー

message_type

メッセージのタイプ (0より大きい数値でなければいけません)

message

メッセージの本体

注意:

serialize が false に設定された場合、 この値は string, int, float または bool のいずれかでなければなりません。 それら以外の場合、警告が発生します。

serialize

オプションのパラメータ serialize は、 message を送信する方法を制御します。 serialize のデフォルト値は true で、 この場合 message が送信される前に セッションモジュールと同じ方法でシリアライズされます。 これにより、配列やオブジェクトのような複雑な形式のデータを 他の PHP スクリプトに送信することが可能となります。 また、もし WDDX シリアライザを使用しているなら、あらゆる WDDX 互換クライアントに対して同じことが可能となります。

blocking

メッセージがキューに収まらないほど大きい場合は、他のプロセスが 現在キューにあるメッセージを読み込んでキューの空き容量が確保されるまで スクリプトの実行を待ち続けます。これをブロックモードといいます。 オプションのパラメータ blocking を false に設定することでブロックモードではなくすることが可能で、 この場合、もしキューの空き容量よりも大きなメッセージを送信すると msg_send() はすぐに false を返します。 また、オプションのパラメータ error_code を MSG_EAGAIN に設定すると、 少し時間をおいてメッセージを再度送信しなければならないことが戻り値からわかります。

error_code

この関数の実行が失敗した場合、オプションのエラーコードがシステムの errno 変数の値に設定されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

処理が正常に完了すると、メッセージキューデータ構造体は以下のように更新されます。 msg_lspid には呼び出し元のプロセス ID が 設定され、msg_qnum が 1 増加し、 msg_stime が現在の時刻に設定されます。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する


メッセージキューデータ構造体の情報を設定する

  • ≪ msg_send
  • msg_stat_queue ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューデータ構造体の情報を設定する

msg_set_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_set_queue — メッセージキューデータ構造体の情報を設定する

説明

msg_set_queue(SysvMessageQueue $queue, array $data): bool

msg_set_queue() により、メッセージキューデータ構造体の msg_perm.uid、msg_perm.gid、msg_perm.mode および msg_qbytes フィールドを 変更することが可能です。

データ構造体を変更するには、PHP の実行ユーザーがキューの作成者あるいは (現在の msg_perm.xxx フィールドで指定されている)キューの所有者であるか、 あるいは root 権限を有している必要があります。msg_qbytes の値を システムで定義した制限をこえて設定するには、root 権限が必要です。

パラメータ

queue

メッセージキュー

data

設定したい値を、data 配列に設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_stat_queue() - メッセージキューデータ構造体の情報を返す
  • msg_get_queue() - メッセージキューを作成またはそれにアタッチする


メッセージキューデータ構造体の情報を返す

  • ≪ msg_set_queue
  • sem_acquire ≫
  • PHP Manual
  • セマフォ関数
  • メッセージキューデータ構造体の情報を返す

msg_stat_queue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

msg_stat_queue — メッセージキューデータ構造体の情報を返す

説明

msg_stat_queue(SysvMessageQueue $queue): array|false

msg_stat_queue() は、queue で指定したメッセージキューのメタデータを返します。 これは、例えば受信したメッセージがどのプロセスから送信されたのかを調べる場合などに有用です。

パラメータ

queue

メッセージキュー

戻り値

成功した場合、戻り値は配列で、そのキーと値は以下のような意味をもちます。

msg_stat_queue の配列構造
msg_perm.uid | キューの所有者の uid 。
msg_perm.gid | キューの所有者の gid 。
msg_perm.mode | キューのファイルアクセスモード。
msg_stime | キューに対して最後にメッセージが送信された時刻。
msg_rtime | キューから最後にメッセージを受信した時刻。
msg_ctime | キューが最後に更新された時刻。
msg_qnum | キューにある読み込み待ちのメッセージの数。
msg_qbytes | ひとつのメッセージキューに含められる最大のバイト数。 Linux では、この値の取得や設定を /proc/sys/kernel/msgmnb で行えます。
msg_lspid | 最後にキューに対してメッセージを送信したプロセスの pid 。
msg_lrpid | 最後にキューからメッセージを受信したプロセスの pid 。

失敗時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 queue は、 SysvMessageQueue のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • msg_remove_queue() - メッセージキューを破棄する
  • msg_receive() - メッセージキューからメッセージを受信する
  • msg_get_queue() - メッセージキューを作成またはそれにアタッチする
  • msg_set_queue() - メッセージキューデータ構造体の情報を設定する


セマフォを得る

  • ≪ msg_stat_queue
  • sem_get ≫
  • PHP Manual
  • セマフォ関数
  • セマフォを得る

sem_acquire

(PHP 4, PHP 5, PHP 7, PHP 8)

sem_acquire — セマフォを得る

説明

sem_acquire(SysvSemaphore $semaphore, bool $non_blocking = false): bool

sem_acquire() はデフォルトで、(必要な場合) セマフォが確保できるまでブロックします。 既に確保されているセマフォを得ようとするプロセスは、 セマフォの獲得により max_aquire 値を超える場合、 永久にブロックされます。

リクエスト処理の後、プロセスにより獲得された全てのセマフォのうち、 明示的に開放されていないものが自動的に開放され、警告が表示されます。

パラメータ

semaphore

semaphore はセマフォのリソースで、 sem_get() によって得られます。

non_blocking

セマフォが確保できるまでプロセスを待たせたくない場合に指定します。 true にすると、セマフォをその場で確保できなかった場合に、 この関数は即時に false を返します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 semaphore は、 SysvSemaphore クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • sem_get() - セマフォ ID を得る
  • sem_release() - セマフォを解放する


セマフォ ID を得る

  • ≪ sem_acquire
  • sem_release ≫
  • PHP Manual
  • セマフォ関数
  • セマフォ ID を得る

sem_get

(PHP 4, PHP 5, PHP 7, PHP 8)

sem_get — セマフォ ID を得る

説明

sem_get(
int $key,
int $max_acquire = 1,
int $permissions = 0666,
bool $auto_release = true
): SysvSemaphore|false

sem_get() は、 System V セマフォを指定したキーでアクセスするために使用可能な ID を返します。

同じキーで sem_get() を 2 度コールした場合、 別のセマフォ ID が返されます。 しかし、どちらの ID も同じそのセマフォをアクセスします。

key に 0 を指定すると、 sem_get() が呼び出される度に新しい非公開のセマフォが作られます。

パラメータ

key

max_acquire

同時にセマフォを得ることが可能なプロセス数を max_acquire にセットします。

permissions

セマフォのパーミッション。 実際には、この値はプロセスが現在そのセマフォに付随している 唯一のプロセスであることがわかった場合にのみセットされます。

auto_release

リクエストの終了時に自動的にセマフォを開放するかどうかを指定します。

戻り値

成功した場合に正のセマフォ ID、エラー時には false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した時、 この関数は SysvSemaphore クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。
8.0.0 | auto_release の型が int から bool に変更されました

注意

警告

PHP 以外のところで作られたセマフォに sem_get() でアクセスするときには、 3 つのセマフォのセットとして作ったものでなければいけないことに注意しましょう (たとえば、C の semget() 関数で作るなら、nsems に 3 を指定します)。 そうしないと、PHP からそのセマフォにアクセスできなくなります。

参考

  • sem_acquire() - セマフォを得る
  • sem_release() - セマフォを解放する
  • ftok() - パス名とプロジェクト ID を、System V IPC キーに変換する


セマフォを解放する

  • ≪ sem_get
  • sem_remove ≫
  • PHP Manual
  • セマフォ関数
  • セマフォを解放する

sem_release

(PHP 4, PHP 5, PHP 7, PHP 8)

sem_release — セマフォを解放する

説明

sem_release(SysvSemaphore $semaphore): bool

sem_release() は、そのセマフォが コール元のプロセスにより現在確保されている場合、解放します。 そうでない場合、警告が表示されます。

セマフォを解放した後、再び確保するには、sem_acquire() をコールします。

パラメータ

semaphore

sem_get() が返すセマフォ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 semaphore は、 SysvSemaphore クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • sem_get() - セマフォ ID を得る
  • sem_acquire() - セマフォを得る


セマフォを削除する

  • ≪ sem_release
  • shm_attach ≫
  • PHP Manual
  • セマフォ関数
  • セマフォを削除する

sem_remove

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sem_remove — セマフォを削除する

説明

sem_remove(SysvSemaphore $semaphore): bool

sem_remove() は、指定したセマフォを削除します。

セマフォを削除した後、そのセマフォにはもうアクセスできません。

パラメータ

semaphore

sem_get() が返すセマフォ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 semaphore は、 SysvSemaphore クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • sem_get() - セマフォ ID を得る
  • sem_release() - セマフォを解放する
  • sem_acquire() - セマフォを得る


共有メモリセグメントを作成またはオープンする

  • ≪ sem_remove
  • shm_detach ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリセグメントを作成またはオープンする

shm_attach

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_attach — 共有メモリセグメントを作成またはオープンする

説明

shm_attach(int $key, ?int $size = null, int $permissions = 0666): SysvSharedMemory|false

shm_attach() は ID を返します。 これは、指定されたキー key で System V 共有メモリにアクセスする際に使用することが可能です。 最初のコールの際に、サイズが size、 オプションのパーミッション permissions を指定した共有メモリセグメントを作成します。

同じ key で shm_attach() を 2 回コールした場合は 別の SysvSharedMemory インスタンスが返されますが、 両方のインスタンスは同じ共有メモリをアクセスします。 size および permissions は無視されます。

パラメータ

key

共有メモリセグメント ID を表す数値。

size

メモリのサイズ。省略した場合のデフォルトは php.ini の sysvshm.init_mem、あるいは 10000 バイトとなります。

permissions

オプションのパーミッション設定。デフォルトは 0666 です。

戻り値

成功時には、SysvSharedMemory クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は SysvSharedMemory クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。
8.0.0 | size は、nullable になりました。

参考

  • shm_detach() - 共有メモリセグメントへの接続を閉じる
  • ftok() - パス名とプロジェクト ID を、System V IPC キーに変換する


共有メモリセグメントへの接続を閉じる

  • ≪ shm_attach
  • shm_get_var ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリセグメントへの接続を閉じる

shm_detach

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_detach — 共有メモリセグメントへの接続を閉じる

説明

shm_detach(SysvSharedMemory $shm): bool

shm_detach() は、 shm_attach() で作成され、 指定した shm を有する共有メモリへの接続を閉じます。 共有メモリは、まだ Unix システム上に存在しており、 データはまだ存在するということを覚えておいてください。

パラメータ

shm

shm_attach() が返す共有メモリセグメント。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_attach() - 共有メモリセグメントを作成またはオープンする
  • shm_remove() - Unix システムから共有メモリを削除する
  • shm_remove_var() - 共有メモリから変数を削除する


共有メモリから変数を返す

  • ≪ shm_detach
  • shm_has_var ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリから変数を返す

shm_get_var

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_get_var — 共有メモリから変数を返す

説明

shm_get_var(SysvSharedMemory $shm, int $key): mixed

shm_get_var() は、 shm で指定した共有メモリセグメントから 変数 key を読みこみます。 読み込んだ変数は、まだ共有メモリに存在します。

パラメータ

shm

共有メモリセグメント。shm_attach() から取得します。

key

変数のキー。

戻り値

指定したキーの変数を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_has_var() - 特定のエントリが存在するかどうかを調べる
  • shm_put_var() - 共有メモリの変数を挿入または更新する


特定のエントリが存在するかどうかを調べる

  • ≪ shm_get_var
  • shm_put_var ≫
  • PHP Manual
  • セマフォ関数
  • 特定のエントリが存在するかどうかを調べる

shm_has_var

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

shm_has_var — 特定のエントリが存在するかどうかを調べる

説明

shm_has_var(SysvSharedMemory $shm, int $key): bool

特定のキーが共有メモリセグメント内に存在するかどうかを調べます。

パラメータ

shm

shm_attach() で取得した共有メモリセグメント。

key

変数のキー。

戻り値

エントリが存在する場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_get_var() - 共有メモリから変数を返す
  • shm_put_var() - 共有メモリの変数を挿入または更新する


共有メモリの変数を挿入または更新する

  • ≪ shm_has_var
  • shm_remove ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリの変数を挿入または更新する

shm_put_var

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_put_var — 共有メモリの変数を挿入または更新する

説明

shm_put_var(SysvSharedMemory $shm, int $key, mixed $value): bool

shm_put_var() は、 指定した key を有する 変数 value の挿入または更新を行います。

shm が有効な SysV 共有メモリではない場合や リクエストを処理するために充分な共有メモリが残っていない場合は (E_WARNING レベルの) 警告を発生させます。

パラメータ

shm

shm_attach() が返す共有メモリセグメント。

key

変数のキー。

value

変数。serialize() がサポートするすべての 型を使うことができます。 通常これは、リソース型と一部の内部オブジェクト (シリアライズできないもの) 以外のすべての型を意味します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_get_var() - 共有メモリから変数を返す
  • shm_has_var() - 特定のエントリが存在するかどうかを調べる


Unix システムから共有メモリを削除する

  • ≪ shm_put_var
  • shm_remove_var ≫
  • PHP Manual
  • セマフォ関数
  • Unix システムから共有メモリを削除する

shm_remove

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_remove — Unix システムから共有メモリを削除する

説明

shm_remove(SysvSharedMemory $shm): bool

shm_remove() は、共有メモリ shm を削除します。 全てのデータは破棄されます。

パラメータ

shm

shm_attach() が返す 共有メモリセグメント。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_remove_var() - 共有メモリから変数を削除する


共有メモリから変数を削除する

  • ≪ shm_remove
  • SysvMessageQueue ≫
  • PHP Manual
  • セマフォ関数
  • 共有メモリから変数を削除する

shm_remove_var

(PHP 4, PHP 5, PHP 7, PHP 8)

shm_remove_var — 共有メモリから変数を削除する

説明

shm_remove_var(SysvSharedMemory $shm, int $key): bool

指定したkey を有する変数を共有メモリから削除し、占有するメモリを解放します。

パラメータ

shm

shm_attach() が返す 共有メモリセグメント。

key

変数のキー。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shm は、 SysvSharedMemory クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • shm_remove() - Unix システムから共有メモリを削除する


SysvMessageQueue クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 sysvmsg queue リソースを置き換える、完全不定形クラスです。

クラス概要

final class SysvMessageQueue {
}


SysvSemaphore クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 sysvsem リソースを置き換える、 完全不定形クラスです。

クラス概要

final class SysvSemaphore {
}


SysvSharedMemory クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 sysvshm リソースを置き換える、 完全不定形クラスです。

クラス概要

final class SysvSharedMemory {
}


共有メモリ

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 例
    • 基本的な使用法
  • 共有メモリ関数
    • shmop_close — 共有メモリブロックを閉じる
    • shmop_delete — 共有メモリブロックを削除する
    • shmop_open — 共有メモリブロックを作成またはオープンする
    • shmop_read — 共有メモリブロックからデータを読み取る
    • shmop_size — 共有メモリブロックの大きさを取得する
    • shmop_write — 共有メモリブロックにデータを書き込む
  • Shmop — Shmop クラス


はじめに

shmop は、共有メモリセグメントを PHP から簡単に読み書きまたは作成、 削除することを可能にする一連の関数です。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • 共有メモリ
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

shmop を使用するには、--enable-shmopパラメータを configure に 指定して PHP をコンパイルする必要があります。


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張モジュールは、共有メモリブロックを扱う shmop リソースを定義していました。


  • ≪ リソース型
  • 基本的な使用法 ≫
  • PHP Manual
  • 共有メモリ
  • 例

例

目次

  • 基本的な使用法


基本的な使用法

例1 共有メモリ操作の概要

<?php

// システムID 0xff3を有する 100 バイトの共有メモリブロックを作成する
$shm_id = shmop_open(0xff3, "c", 0644, 100);
if (!$shm_id) {
echo "共有メモリセグメントを作成できませんでした。\n";
}

// 共有メモリのブロック長を得る
$shm_size = shmop_size($shm_id);
echo "SHM ブロックサイズ: ".$shm_size. " が作成されました。\n";

// 共有メモリにテスト用の文字列を書き込んでみる
$shm_bytes_written = shmop_write($shm_id, "my shared memory block", 0);
if ($shm_bytes_written != strlen("my shared memory block")) {
echo "データ全体を書き込めませんでした。\n";
}

// その文字列を再び読み込んでみる
$my_string = shmop_read($shm_id, 0, $shm_size);
if (!$my_string) {
echo "共有メモリブロックから読み込めません。\n";
}
echo "共有メモリ内のデータは次のようになります: ".$my_string."\n";

// ブロックを削除し、共有メモリセグメントを閉じる
if (!shmop_delete($shm_id)) {
echo "共有メモリブロックに削除用のマークを付けることができません。";
}
shmop_close($shm_id);

?>


共有メモリ関数

目次

  • shmop_close — 共有メモリブロックを閉じる
  • shmop_delete — 共有メモリブロックを削除する
  • shmop_open — 共有メモリブロックを作成またはオープンする
  • shmop_read — 共有メモリブロックからデータを読み取る
  • shmop_size — 共有メモリブロックの大きさを取得する
  • shmop_write — 共有メモリブロックにデータを書き込む


共有メモリブロックを閉じる

  • ≪ 共有メモリ関数
  • shmop_delete ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックを閉じる

shmop_close

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_close — 共有メモリブロックを閉じる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

shmop_close(Shmop $shmop): void

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

shmop_close() は、共有メモリブロックを閉じます。

パラメータ

shmop

shmop_open() 関数で作られた共有メモリブロックのリソース。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックを閉じる

<?php
shmop_close($shm_id);
?>

この例は、$shm_id で識別される共有メモリブロックを閉じます。

参考

  • shmop_open() - 共有メモリブロックを作成またはオープンする


共有メモリブロックを削除する

  • ≪ shmop_close
  • shmop_open ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックを削除する

shmop_delete

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_delete — 共有メモリブロックを削除する

説明

shmop_delete(Shmop $shmop): bool

shmop_delete() は、共有メモリブロックを削除ます。

パラメータ

shmop

shmop_open() で作られた共有メモリブロックのリソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックを削除する

<?php
shmop_delete($shm_id);
?>

この例は、$shm_id で識別された共有メモリブロックを削除します。


共有メモリブロックを作成またはオープンする

  • ≪ shmop_delete
  • shmop_read ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックを作成またはオープンする

shmop_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_open — 共有メモリブロックを作成またはオープンする

説明

shmop_open(
int $key,
string $mode,
int $permissions,
int $size
): Shmop|false

shmop_open() は共有メモリブロックを作成または オープンします。

パラメータ

key

共有メモリブロックのシステム ID であり、10 進数または 16 進数で指定することが可能です。

mode

フラグに設定できる内容は、次のとおりです。

  • "a" アクセス用(shmat に SHM_RDONLY を設定する) 既存の共有メモリセグメントを読み込み専用でオープンする必要がある場合に このフラグを使用してください。
  • "c" 作成用(IPC_CREATE を設定する) 新規に共有メモリセグメントが必要な場合にこのフラグを使用してください。 もし同じキーのセグメントがすでに存在する場合、それを読み書きモードで オープンしようと試みます。
  • "w" 読み込み & 書き込みアクセス用 共有メモリセグメントの読み込みや書き込みの必要がある場合にこのフラグを 使用してください。たいていの場合はこのフラグを使用します。
  • "n" 新規メモリセグメントの作成用(IPC_CREATE|IPC_EXCL を設定する) 新規に共有メモリセグメントが必要で、もし同じフラグのセグメントが 存在するときには失敗させたい場合にこのフラグを使用してください。 セキュリティを確保するために、このフラグは有用です。これを使用する ことで、条件の競合による問題を避けることが可能です。

permissions

共有メモリセグメントに設定したい 許可属性で、ファイルに関する許可属性と同様なものです。許可属性は、 例えば 0644 のような 8 進数形式で渡す必要があります。

size

作成したい共有メモリブロックの大きさをバイト数で指定します。

注意:

注意: 既存のメモリセグメントをオープンする場合には、3 番目および 4 番目の引数には 0 を指定する必要があります。

戻り値

成功した場合は、shmop_open() は 作成した共有メモリセグメントにアクセスするために使用する Shmop クラスのインスタンスを返します。 失敗した場合に false を返します。

エラー / 例外

mode が不正な値だったり、 size が 0 以下の値の場合、 ValueError がスローされます。 それ以外の場合で、処理に失敗した場合は E_WARNING が発生します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は Shmop クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。
8.0.0 | mode が不正な値だったり、 size が 0 以下の値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生し、 false を返していました。

例

例1 共有メモリブロックを新規に作成する

<?php
$shm_key = ftok(__FILE__, 't');
$shm_id = shmop_open($shm_key, "c", 0644, 100);
?>

この例は、ftok() が返すシステム ID の共有メモリブロックをオープンします。

参考

  • shmop_close() - 共有メモリブロックを閉じる
  • shmop_delete() - 共有メモリブロックを削除する


共有メモリブロックからデータを読み取る

  • ≪ shmop_open
  • shmop_size ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックからデータを読み取る

shmop_read

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_read — 共有メモリブロックからデータを読み取る

説明

shmop_read(Shmop $shmop, int $offset, int $size): string

shmop_read() は、共有メモリブロックから文字列を読み取ります。

パラメータ

shmop

shmop_open() 関数で作られた、共有メモリブロックの識別子。

offset

読み取りを始めるオフセット。 この値は 0 以上、かつ共有メモリセグメントの実際のサイズ以下でなければいけません。

size

読み取るバイト数。 この値は 0 以上、かつ offset と size の合計値が、共有メモリセグメントの実際のサイズ以下でなければいけません。 0 を指定すると、shmop_size($shmid) - $start バイトを読み取ります。

戻り値

読み取ったデータを返します。 失敗した場合に false を返します

エラー / 例外

offset や size が範囲外の値の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースを期待していました。
8.0.0 | offset や size が範囲外の値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生し、false を返していました。

例

例1 共有メモリブロックを読み取る

<?php
$shm_data = shmop_read($shm_id, 0, 50);
?>

この例は、共有メモリブロックから50バイトを読み取り、 データを $shm_data に格納します。

参考

  • shmop_write() - 共有メモリブロックにデータを書き込む


共有メモリブロックの大きさを取得する

  • ≪ shmop_read
  • shmop_write ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックの大きさを取得する

shmop_size

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_size — 共有メモリブロックの大きさを取得する

説明

shmop_size(Shmop $shmop): int

shmop_size() は、共有メモリブロックのサイズをバイト単位で取得します。

パラメータ

shmop

shmop_open() 関数で作られた、共有メモリブロックの識別子。

戻り値

共有メモリブロックが専有している大きさをバイト単位で返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックのサイズを取得する

<?php
$shm_size = shmop_size($shm_id);
?>

この例は、$shm_id で識別される共有メモリブロックのサイズを $shm_size に代入しています。


共有メモリブロックにデータを書き込む

  • ≪ shmop_size
  • Shmop ≫
  • PHP Manual
  • 共有メモリ関数
  • 共有メモリブロックにデータを書き込む

shmop_write

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

shmop_write — 共有メモリブロックにデータを書き込む

説明

shmop_write(Shmop $shmop, string $data, int $offset): int

shmop_write() は、共有メモリブロックに文字列を書き込みます。

パラメータ

shmop

shmop_open() で作られた共有メモリブロックの識別子。

data

共有メモリブロックに書き込む文字列

offset

共有メモリセグメント内部のどこから、データを書き始めるかを指定します。 この値は 0 以上、かつ共有メモリセグメントの実際のサイズ以下でなければいけません。

戻り値

書き込んだ data のサイズを返します。

エラー / 例外

offset が範囲外の値の場合、 または読み取り専用の共有メモリセグメントに書き込んだ場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | PHP 8.0.0 より前のバージョンでは、 失敗した時に false を返していました。
8.0.0 | 引数 shmop は、 Shmop クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 共有メモリブロックに書き込む

<?php
$shm_bytes_written = shmop_write($shm_id, $my_string, 0);
?>

この例は、$my_string にあるデータを共有メモリブロックに書き込みます。 $shm_bytes_written には、書かれたデータのバイト数が入ります。

参考

  • shmop_read() - 共有メモリブロックからデータを読み取る


Shmop クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 shmop リソースを置き換える完全不透明クラスです。

クラス概要

final class Shmop {
}


Sync

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • SyncMutex — The SyncMutex class
    • SyncMutex::__construct — Constructs a new SyncMutex object
    • SyncMutex::lock — Waits for an exclusive lock
    • SyncMutex::unlock — Unlocks the mutex
  • SyncSemaphore — The SyncSemaphore class
    • SyncSemaphore::__construct — Constructs a new SyncSemaphore object
    • SyncSemaphore::lock — Decreases the count of the semaphore or waits
    • SyncSemaphore::unlock — Increases the count of the semaphore
  • SyncEvent — The SyncEvent class
    • SyncEvent::__construct — Constructs a new SyncEvent object
    • SyncEvent::fire — Fires/sets the event
    • SyncEvent::reset — Resets a manual event
    • SyncEvent::wait — Waits for the event to be fired/set
  • SyncReaderWriter — The SyncReaderWriter class
    • SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object
    • SyncReaderWriter::readlock — Waits for a read lock
    • SyncReaderWriter::readunlock — Releases a read lock
    • SyncReaderWriter::writelock — Waits for an exclusive write lock
    • SyncReaderWriter::writeunlock — Releases a write lock
  • SyncSharedMemory — The SyncSharedMemory class
    • SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object
    • SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory
    • SyncSharedMemory::read — Copy data from named shared memory
    • SyncSharedMemory::size — Returns the size of the named shared memory
    • SyncSharedMemory::write — Copy data to named shared memory


はじめに

The sync extension introduces cross-platform synchonization objects into PHP. Named and unnamed Mutex, Semaphore, Event, Reader-Writer, and named Shared Memory objects provide OS-level synchronization on both POSIX (e.g. Linux) and Windows platforms.

Automatic cleanup of acquired synchronization objects takes place during extension teardown. This means that if PHP prematurely terminates a script (e.g. script execution time is exceeded), objects will not be left in an unknown state. The only exception to this is if PHP itself crashes (e.g. an internal buffer overflow).

Unnamed synchronization objects don't have a lot of use outside of a multithreaded scenario. Unnamed objects are more useful in conjunction with the pthreads PECL extension.

注意:

Named objects require additional care to be used on all systems. If an object is instantiated with a specific set of parameters, it must always be instantiated with those parameters or the object will probably end up in an inconsistent state until the next reboot or a system administrator cleans up the mess.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Sync
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

A system with support for POSIX shared memory (shm_open()) or running Windows.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/sync.


The SyncMutex class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed countable mutex objects.

A mutex is a mutual exclusion object that restricts access to a shared resource (e.g. a file) to a single instance. Countable mutexes acquire the mutex a single time and internally track the number of times the mutex is locked. The mutex is unlocked as soon as it goes out of scope or is unlocked the same number of times that it was locked.

クラス概要

class SyncMutex {
/* メソッド */
public __construct(string $name = ?)
public lock(int $wait = -1): bool
public unlock(bool $all = false): bool
}

目次

  • SyncMutex::__construct — Constructs a new SyncMutex object
  • SyncMutex::lock — Waits for an exclusive lock
  • SyncMutex::unlock — Unlocks the mutex


Constructs a new SyncMutex object

  • ≪ SyncMutex
  • SyncMutex::lock ≫
  • PHP Manual
  • SyncMutex
  • Constructs a new SyncMutex object

SyncMutex::__construct

(PECL sync >= 1.0.0)

SyncMutex::__construct — Constructs a new SyncMutex object

説明

public SyncMutex::__construct(string $name = ?)

Constructs a named or unnamed countable mutex.

パラメータ

name

The name of the mutex if this is a named mutex object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

戻り値

The new SyncMutex object.

エラー / 例外

An exception is thrown if the mutex cannot be created or opened.

例

例1 SyncMutex::__construct() named mutex with lock timeout example

<?php
$mutex = new SyncMutex("UniqueName");

if (!$mutex->lock(3000))
{
echo "Unable to lock mutex.";

exit();
}

/* ... */

$mutex->unlock();
?>

例2 SyncMutex::__construct() unnamed mutex example

<?php
$mutex = new SyncMutex();

$mutex->lock();

/* ... */

$mutex->unlock();
?>

参考

  • SyncMutex::lock() - Waits for an exclusive lock
  • SyncMutex::unlock() - Unlocks the mutex


Waits for an exclusive lock

  • ≪ SyncMutex::__construct
  • SyncMutex::unlock ≫
  • PHP Manual
  • SyncMutex
  • Waits for an exclusive lock

SyncMutex::lock

(PECL sync >= 1.0.0)

SyncMutex::lock — Waits for an exclusive lock

説明

public SyncMutex::lock(int $wait = -1): bool

Obtains an exclusive lock on a SyncMutex object. If the lock is already acquired, then this increments an internal counter.

パラメータ

wait

The number of milliseconds to wait for the exclusive lock. A value of -1 is infinite.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncMutex::lock() example

<?php
$mutex = new SyncMutex("UniqueName");

if (!$mutex->lock(3000))
{
echo "Unable to lock mutex.";

exit();
}

/* ... */

$mutex->unlock();
?>

参考

  • SyncMutex::unlock() - Unlocks the mutex


Unlocks the mutex

  • ≪ SyncMutex::lock
  • SyncSemaphore ≫
  • PHP Manual
  • SyncMutex
  • Unlocks the mutex

SyncMutex::unlock

(PECL sync >= 1.0.0)

SyncMutex::unlock — Unlocks the mutex

説明

public SyncMutex::unlock(bool $all = false): bool

Decreases the internal counter of a SyncMutex object. When the internal counter reaches zero, the actual lock on the object is released.

パラメータ

all

Specifies whether or not to set the internal counter to zero and therefore release the lock.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncMutex::unlock() example

<?php
$mutex = new SyncMutex("UniqueName");

$mutex->lock();

/* ... */

$mutex->unlock();
?>

参考

  • SyncMutex::lock() - Waits for an exclusive lock


The SyncSemaphore class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed semaphore objects.

A semaphore restricts access to a limited resource to a limited number of instances. Semaphores differ from mutexes in that they can allow more than one instance to access a resource at one time while a mutex only allows one instance at a time.

クラス概要

class SyncSemaphore {
/* メソッド */
public __construct(string $name = ?, int $initialval = 1, bool $autounlock = true)
public lock(int $wait = -1): bool
public unlock(int &$prevcount = ?): bool
}

目次

  • SyncSemaphore::__construct — Constructs a new SyncSemaphore object
  • SyncSemaphore::lock — Decreases the count of the semaphore or waits
  • SyncSemaphore::unlock — Increases the count of the semaphore


Constructs a new SyncSemaphore object

  • ≪ SyncSemaphore
  • SyncSemaphore::lock ≫
  • PHP Manual
  • SyncSemaphore
  • Constructs a new SyncSemaphore object

SyncSemaphore::__construct

(PECL sync >= 1.0.0)

SyncSemaphore::__construct — Constructs a new SyncSemaphore object

説明

public SyncSemaphore::__construct(string $name = ?, int $initialval = 1, bool $autounlock = true)

Constructs a named or unnamed semaphore.

パラメータ

name

The name of the semaphore if this is a named semaphore object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

initialval

The initial value of the semaphore. This is the number of locks that may be obtained.

autounlock

Specifies whether or not to automatically unlock the semaphore at the conclusion of the PHP script.

警告

If an object is: A named semaphore with an autounlock of false, the object is locked, and the PHP script concludes before the object is unlocked, then the underlying semaphore will end up in an inconsistent state.

戻り値

The new SyncSemaphore object.

エラー / 例外

An exception is thrown if the semaphore cannot be created or opened.

例

例1 SyncSemaphore::__construct() example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
echo "Unable to lock semaphore.";

exit();
}

/* ... */

$semaphore->unlock();
?>

参考

  • SyncSemaphore::lock() - Decreases the count of the semaphore or waits
  • SyncSemaphore::unlock() - Increases the count of the semaphore


Decreases the count of the semaphore or waits

  • ≪ SyncSemaphore::__construct
  • SyncSemaphore::unlock ≫
  • PHP Manual
  • SyncSemaphore
  • Decreases the count of the semaphore or waits

SyncSemaphore::lock

(PECL sync >= 1.0.0)

SyncSemaphore::lock — Decreases the count of the semaphore or waits

説明

public SyncSemaphore::lock(int $wait = -1): bool

Decreases the count of a SyncSemaphore object or waits until the semaphore becomes non-zero.

パラメータ

wait

The number of milliseconds to wait for the semaphore. A value of -1 is infinite.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncSemaphore::lock() example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
echo "Unable to lock semaphore.";

exit();
}

/* ... */

$semaphore->unlock();
?>

参考

  • SyncSemaphore::unlock() - Increases the count of the semaphore


Increases the count of the semaphore

  • ≪ SyncSemaphore::lock
  • SyncEvent ≫
  • PHP Manual
  • SyncSemaphore
  • Increases the count of the semaphore

SyncSemaphore::unlock

(PECL sync >= 1.0.0)

SyncSemaphore::unlock — Increases the count of the semaphore

説明

public SyncSemaphore::unlock(int &$prevcount = ?): bool

Increases the count of a SyncSemaphore object.

パラメータ

prevcount

Returns the previous count of the semaphore.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncSemaphore::unlock() example

<?php
$semaphore = new SyncSemaphore("LimitedResource_2clients", 2);

if (!$semaphore->lock(3000))
{
echo "Unable to lock semaphore.";

exit();
}

/* ... */

$semaphore->unlock();
?>

参考

  • SyncSemaphore::lock() - Decreases the count of the semaphore or waits


The SyncEvent class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed event objects. Both automatic and manual event objects are supported.

An event object waits, without polling, for the object to be fired/set. One instance waits on the event object while another instance fires/sets the event. Event objects are useful wherever a long-running process would otherwise poll a resource (e.g. checking to see if uploaded data needs to be processed).

クラス概要

class SyncEvent {
/* メソッド */
public __construct(string $name = ?, bool $manual = false, bool $prefire = false)
public fire(): bool
public reset(): bool
public wait(int $wait = -1): bool
}

目次

  • SyncEvent::__construct — Constructs a new SyncEvent object
  • SyncEvent::fire — Fires/sets the event
  • SyncEvent::reset — Resets a manual event
  • SyncEvent::wait — Waits for the event to be fired/set


Constructs a new SyncEvent object

  • ≪ SyncEvent
  • SyncEvent::fire ≫
  • PHP Manual
  • SyncEvent
  • Constructs a new SyncEvent object

SyncEvent::__construct

(PECL sync >= 1.0.0)

SyncEvent::__construct — Constructs a new SyncEvent object

説明

public SyncEvent::__construct(string $name = ?, bool $manual = false, bool $prefire = false)

Constructs a named or unnamed event object.

パラメータ

name

The name of the event if this is a named event object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

manual

Specifies whether or not the event object must be reset manually.

注意:

Manual reset event objects allow all waiting processes through until the object is reset.

prefire

Specifies whether or not to prefire (signal) the event object.

注意:

Only has impact if the calling process/thread is the first to create the object.

戻り値

The new SyncEvent object.

エラー / 例外

An exception is thrown if the event object cannot be created or opened.

例

例1 SyncEvent::__construct() example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

変更履歴

バージョン | 説明
PECL sync 1.1.0 | Added prefire.

参考

  • SyncEvent::fire() - Fires/sets the event
  • SyncEvent::reset() - Resets a manual event
  • SyncEvent::wait() - Waits for the event to be fired/set


Fires/sets the event

  • ≪ SyncEvent::__construct
  • SyncEvent::reset ≫
  • PHP Manual
  • SyncEvent
  • Fires/sets the event

SyncEvent::fire

(PECL sync >= 1.0.0)

SyncEvent::fire — Fires/sets the event

説明

public SyncEvent::fire(): bool

Fires/sets a SyncEvent object. Lets multiple threads through that are waiting if the event object was created with a manual value of true.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncEvent::fire() example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

参考

  • SyncEvent::reset() - Resets a manual event
  • SyncEvent::wait() - Waits for the event to be fired/set


Resets a manual event

  • ≪ SyncEvent::fire
  • SyncEvent::wait ≫
  • PHP Manual
  • SyncEvent
  • Resets a manual event

SyncEvent::reset

(PECL sync >= 1.0.0)

SyncEvent::reset — Resets a manual event

説明

public SyncEvent::reset(): bool

Resets a SyncEvent object that has been fired/set. Only valid for manual event objects.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncEvent::reset() example

<?php
// In a web application:
$event = new SyncEvent("DemoApplication", true);
$event->wait();

// In a cron job:
$event = new SyncEvent("DemoApplication", true);
$event->reset();
/* ... Do some maintenance task(s) ... */
$event->fire();
?>

参考

  • SyncEvent::fire() - Fires/sets the event
  • SyncEvent::reset()
  • SyncEvent::wait() - Waits for the event to be fired/set


Waits for the event to be fired/set

  • ≪ SyncEvent::reset
  • SyncReaderWriter ≫
  • PHP Manual
  • SyncEvent
  • Waits for the event to be fired/set

SyncEvent::wait

(PECL sync >= 1.0.0)

SyncEvent::wait — Waits for the event to be fired/set

説明

public SyncEvent::wait(int $wait = -1): bool

Waits for the SyncEvent object to be fired.

パラメータ

wait

The number of milliseconds to wait for the event to be fired. A value of -1 is infinite.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncEvent::wait() example

<?php
// In a web application:
$event = new SyncEvent("GetAppReport");
$event->fire();

// In a cron job:
$event = new SyncEvent("GetAppReport");
$event->wait();
?>

参考

  • SyncEvent::fire() - Fires/sets the event


The SyncReaderWriter class

(PECL sync >= 1.0.0)

はじめに

A cross-platform, native implementation of named and unnamed reader-writer objects.

A reader-writer object allows many readers or one writer to access a resource. This is an efficient solution for managing resources where access will primarily be read-only but exclusive write access is occasionally necessary.

クラス概要

class SyncReaderWriter {
/* メソッド */
public __construct(string $name = ?, int $autounlock = 1)
public readlock(int $wait = -1): bool
public readunlock(): bool
public writelock(int $wait = -1): bool
public writeunlock(): bool
}

目次

  • SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object
  • SyncReaderWriter::readlock — Waits for a read lock
  • SyncReaderWriter::readunlock — Releases a read lock
  • SyncReaderWriter::writelock — Waits for an exclusive write lock
  • SyncReaderWriter::writeunlock — Releases a write lock


Constructs a new SyncReaderWriter object

  • ≪ SyncReaderWriter
  • SyncReaderWriter::readlock ≫
  • PHP Manual
  • SyncReaderWriter
  • Constructs a new SyncReaderWriter object

SyncReaderWriter::__construct

(PECL sync >= 1.0.0)

SyncReaderWriter::__construct — Constructs a new SyncReaderWriter object

説明

public SyncReaderWriter::__construct(string $name = ?, int $autounlock = 1)

Constructs a named or unnamed reader-writer object.

パラメータ

name

The name of the reader-writer if this is a named reader-writer object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

注意: On Windows, name must not contain backslashes.

autounlock

Specifies whether or not to automatically unlock the reader-writer at the conclusion of the PHP script.

警告

If an object is: A named reader-writer with an autounlock of FALSE, the object is locked for either reading or writing, and the PHP script concludes before the object is unlocked, then the underlying objects will end up in an inconsistent state.

戻り値

The new SyncReaderWriter object.

エラー / 例外

An exception is thrown if the reader-writer cannot be created or opened.

例

例1 SyncReaderWriter::__construct() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();

$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参考

  • SyncReaderWriter::readlock() - Waits for a read lock
  • SyncReaderWriter::readunlock() - Releases a read lock
  • SyncReaderWriter::writelock() - Waits for an exclusive write lock
  • SyncReaderWriter::writeunlock() - Releases a write lock


Waits for a read lock

  • ≪ SyncReaderWriter::__construct
  • SyncReaderWriter::readunlock ≫
  • PHP Manual
  • SyncReaderWriter
  • Waits for a read lock

SyncReaderWriter::readlock

(PECL sync >= 1.0.0)

SyncReaderWriter::readlock — Waits for a read lock

説明

public SyncReaderWriter::readlock(int $wait = -1): bool

Obtains a read lock on a SyncReaderWriter object.

パラメータ

wait

The number of milliseconds to wait for a lock. A value of -1 is infinite.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncReaderWriter::readlock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();
?>

参考

  • SyncReaderWriter::readunlock() - Releases a read lock


Releases a read lock

  • ≪ SyncReaderWriter::readlock
  • SyncReaderWriter::writelock ≫
  • PHP Manual
  • SyncReaderWriter
  • Releases a read lock

SyncReaderWriter::readunlock

(PECL sync >= 1.0.0)

SyncReaderWriter::readunlock — Releases a read lock

説明

public SyncReaderWriter::readunlock(): bool

Releases a read lock on a SyncReaderWriter object.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncReaderWriter::readunlock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->readlock();
/* ... */
$readwrite->readunlock();
?>

参考

  • SyncReaderWriter::readlock() - Waits for a read lock


Waits for an exclusive write lock

  • ≪ SyncReaderWriter::readunlock
  • SyncReaderWriter::writeunlock ≫
  • PHP Manual
  • SyncReaderWriter
  • Waits for an exclusive write lock

SyncReaderWriter::writelock

(PECL sync >= 1.0.0)

SyncReaderWriter::writelock — Waits for an exclusive write lock

説明

public SyncReaderWriter::writelock(int $wait = -1): bool

Obtains an exclusive write lock on a SyncReaderWriter object.

パラメータ

wait

The number of milliseconds to wait for a lock. A value of -1 is infinite.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncReaderWriter::writelock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参考

  • SyncReaderWriter::writeunlock() - Releases a write lock


Releases a write lock

  • ≪ SyncReaderWriter::writelock
  • SyncSharedMemory ≫
  • PHP Manual
  • SyncReaderWriter
  • Releases a write lock

SyncReaderWriter::writeunlock

(PECL sync >= 1.0.0)

SyncReaderWriter::writeunlock — Releases a write lock

説明

public SyncReaderWriter::writeunlock(): bool

Releases a write lock on a SyncReaderWriter object.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncReaderWriter::writeunlock() example

<?php
$readwrite = new SyncReaderWriter("FileCacheLock");
$readwrite->writelock();
/* ... */
$readwrite->writeunlock();
?>

参考

  • SyncReaderWriter::writelock() - Waits for an exclusive write lock


The SyncSharedMemory class

(PECL sync >= 1.1.0)

はじめに

A cross-platform, native, consistent implementation of named shared memory objects.

Shared memory lets two separate processes communicate without the need for complex pipes or sockets. There are several integer-based shared memory implementations for PHP. Named shared memory is an alternative.

Synchronization objects (e.g. SyncMutex) are still required to protect most uses of shared memory.

クラス概要

class SyncSharedMemory {
/* メソッド */
public __construct(string $name, int $size)
public first(): bool
public read(int $start = 0, int $length = ?)
public size(): int
public write(string $string = ?, int $start = 0)
}

目次

  • SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object
  • SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::read — Copy data from named shared memory
  • SyncSharedMemory::size — Returns the size of the named shared memory
  • SyncSharedMemory::write — Copy data to named shared memory


Constructs a new SyncSharedMemory object

  • ≪ SyncSharedMemory
  • SyncSharedMemory::first ≫
  • PHP Manual
  • SyncSharedMemory
  • Constructs a new SyncSharedMemory object

SyncSharedMemory::__construct

(PECL sync >= 1.1.0)

SyncSharedMemory::__construct — Constructs a new SyncSharedMemory object

説明

public SyncSharedMemory::__construct(string $name, int $size)

Constructs a named shared memory object.

パラメータ

name

The name of the shared memory object.

注意:

If the name already exists, it must be able to be opened by the current user that the process is running as or an exception will be thrown with a meaningless error message.

size

The size, in bytes, of shared memory to reserve.

注意:

The amount of memory cannot be resized later. Request sufficient storage up front.

戻り値

The new SyncSharedMemory object.

エラー / 例外

An exception is thrown if the shared memory object cannot be created or opened.

例

例1 SyncSharedMemory::__construct() example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
// Do first time initialization work here.
}

$result = $mem->write(json_encode(array("name" => "my_report.txt")));
?>

参考

  • SyncSharedMemory::first() - Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::size() - Returns the size of the named shared memory
  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read() - Copy data from named shared memory


Check to see if the object is the first instance system-wide of named shared memory

  • ≪ SyncSharedMemory::__construct
  • SyncSharedMemory::read ≫
  • PHP Manual
  • SyncSharedMemory
  • Check to see if the object is the first instance system-wide of named shared memory

SyncSharedMemory::first

(PECL sync >= 1.1.0)

SyncSharedMemory::first — Check to see if the object is the first instance system-wide of named shared memory

説明

public SyncSharedMemory::first(): bool

Retrieves the system-wide first instance status of a SyncSharedMemory object.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SyncSharedMemory::first() example

<?php
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
// Do first time initialization work here.
}

var_dump($mem->first());

$mem2 = new SyncSharedMemory("AppReportName", 1024);

var_dump($mem2->first());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read() - Copy data from named shared memory


Copy data from named shared memory

  • ≪ SyncSharedMemory::first
  • SyncSharedMemory::size ≫
  • PHP Manual
  • SyncSharedMemory
  • Copy data from named shared memory

SyncSharedMemory::read

(PECL sync >= 1.1.0)

SyncSharedMemory::read — Copy data from named shared memory

説明

public SyncSharedMemory::read(int $start = 0, int $length = ?)

Copies data from named shared memory.

パラメータ

start

The start/offset, in bytes, to begin reading.

注意:

If the value is negative, the starting position will begin at the specified number of bytes from the end of the shared memory segment.

length

The number of bytes to read.

注意:

If unspecified, reading will stop at the end of the shared memory segment.

If the value is negative, reading will stop the specified number of bytes from the end of the shared memory segment.

戻り値

A string containing the data read from shared memory.

例

例1 SyncSharedMemory::__construct() example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
// Do first time initialization work here.
}

$result = $mem->write("report.txt");

$result = $mem->read(3, -4);
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "ort"

参考

  • SyncSharedMemory::__construct() - Constructs a new SyncSharedMemory object
  • SyncSharedMemory::first() - Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read()


Returns the size of the named shared memory

  • ≪ SyncSharedMemory::read
  • SyncSharedMemory::write ≫
  • PHP Manual
  • SyncSharedMemory
  • Returns the size of the named shared memory

SyncSharedMemory::size

(PECL sync >= 1.1.0)

SyncSharedMemory::size — Returns the size of the named shared memory

説明

public SyncSharedMemory::size(): int

Retrieves the shared memory size of a SyncSharedMemory object.

パラメータ

この関数にはパラメータはありません。

戻り値

An integer containing the size of the shared memory. This will be the same size that was passed to the constructor.

例

例1 SyncSharedMemory::size() example

<?php
$mem = new SyncSharedMemory("AppReportName", 1024);
var_dump($mem->size());
?>

上の例の出力は、 たとえば以下のようになります。

int(1024)

参考

  • SyncSharedMemory::__construct() - Constructs a new SyncSharedMemory object
  • SyncSharedMemory::write() - Copy data to named shared memory
  • SyncSharedMemory::read() - Copy data from named shared memory


Copy data to named shared memory

  • ≪ SyncSharedMemory::size
  • その他の基本モジュール ≫
  • PHP Manual
  • SyncSharedMemory
  • Copy data to named shared memory

SyncSharedMemory::write

(PECL sync >= 1.1.0)

SyncSharedMemory::write — Copy data to named shared memory

説明

public SyncSharedMemory::write(string $string = ?, int $start = 0)

Copies data to named shared memory.

パラメータ

string

The data to write to shared memory.

注意:

If the size of the data exceeds the size of the shared memory, the number of bytes written returned will be less than the length of the input.

start

The start/offset, in bytes, to begin writing.

注意:

If the value is negative, the starting position will begin at the specified number of bytes from the end of the shared memory segment.

戻り値

An integer containing the number of bytes written to shared memory.

例

例1 SyncSharedMemory::write() example

<?php
// You will probably need to protect shared memory with other synchronization objects.
// Shared memory goes away when the last reference to it disappears.
$mem = new SyncSharedMemory("AppReportName", 1024);
if ($mem->first())
{
// Do first time initialization work here.
}

$result = $mem->write("report.txt");
var_dump($result);

$result = $mem->write("report.txt", -3);
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(3)

参考

  • SyncSharedMemory::__construct() - Constructs a new SyncSharedMemory object
  • SyncSharedMemory::first() - Check to see if the object is the first instance system-wide of named shared memory
  • SyncSharedMemory::write()
  • SyncSharedMemory::read() - Copy data from named shared memory


その他の基本モジュール

  • GeoIP — Geo IP ロケーション
    • はじめに
    • インストール/設定
    • 定義済み定数
    • GeoIP 関数
  • FANN — FANN (Fast Artificial Neural Network)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Fann 関数
    • FANNConnection — The FANNConnection class
  • Igbinary
    • はじめに
    • インストール/設定
    • Igbinary 関数
  • JSON — JavaScript Object Notation
    • はじめに
    • インストール/設定
    • 定義済み定数
    • JsonException — JsonException クラス
    • JsonSerializable — JsonSerializable インターフェイス
    • JSON 関数
  • Simdjson
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Simdjson 関数
    • SimdJsonException — The SimdJsonException class
    • SimdJsonValueError — The SimdJsonValueError class
  • Lua
    • はじめに
    • インストール/設定
    • Lua — Lua クラス
    • LuaClosure — LuaClosure クラス
  • LuaSandbox
    • はじめに
    • インストール/設定
    • Differences from Standard Lua
    • 例
    • LuaSandbox — The LuaSandbox class
    • LuaSandboxFunction — The LuaSandboxFunction class
    • LuaSandboxError — The LuaSandboxError class
    • LuaSandboxErrorError — The LuaSandboxErrorError class
    • LuaSandboxFatalError — The LuaSandboxFatalError class
    • LuaSandboxMemoryError — The LuaSandboxMemoryError class
    • LuaSandboxRuntimeError — The LuaSandboxRuntimeError class
    • LuaSandboxSyntaxError — The LuaSandboxSyntaxError class
    • LuaSandboxTimeoutError — The LuaSandboxTimeoutError class
  • その他 — その他の関数
    • はじめに
    • インストール/設定
    • 定義済み定数
    • その他の関数
    • 変更履歴
  • Random — 乱数生成器および、乱数関連の関数
    • はじめに
    • 定義済み定数
    • 例
    • Random 関数
    • Random\Randomizer — Random\Randomizer クラス
    • Random\Engine — Random\Engine インターフェイス
    • Random\CryptoSafeEngine — Random\CryptoSafeEngine インターフェイス
    • Random\Engine\Secure — Random\Engine\Secure クラス
    • Random\Engine\Mt19937 — Random\Engine\Mt19937 クラス
    • Random\Engine\PcgOneseq128XslRr64 — Random\Engine\PcgOneseq128XslRr64 クラス
    • Random\Engine\Xoshiro256StarStar — Random\Engine\Xoshiro256StarStar クラス
    • Random\RandomError — Random\RandomError クラス
    • Random\BrokenRandomEngineError — Random\BrokenRandomEngineError クラス
    • Random\RandomException — Random\RandomException クラス
  • Seaslog
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Seaslog 関数
    • SeasLog — The SeasLog class
  • SPL — Standard PHP Library (SPL)
    • はじめに
    • 定義済み定数
    • データ構造
    • イテレータ
    • インターフェイス
    • 例外
    • SPL 関数
    • ファイル操作
    • その他のクラスおよびインターフェイス
  • ストリーム
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ストリームフィルタ
    • ストリームコンテキスト
    • ストリームのエラー
    • 例
    • php_user_filter — php_user_filter クラス
    • streamWrapper — streamWrapper クラス
    • ストリーム 関数
  • Swoole
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Swoole 関数
    • Swoole\Async — The Swoole\Async class
    • Swoole\Atomic — The Swoole\Atomic class
    • Swoole\Buffer — The Swoole\Buffer class
    • Swoole\Channel — The Swoole\Channel class
    • Swoole\Client — The Swoole\Client class
    • Swoole\Connection\Iterator — The Swoole\Connection\Iterator class
    • Swoole\Coroutine — The Swoole\Coroutine class
    • Swoole\Event — The Swoole\Event class
    • Swoole\Exception — The Swoole\Exception class
    • Swoole\Http\Client — The Swoole\Http\Client class
    • Swoole\Http\Request — The Swoole\Http\Request class
    • Swoole\Http\Response — The Swoole\Http\Response class
    • Swoole\Http\Server — The Swoole\Http\Server class
    • Swoole\Lock — The Swoole\Lock class
    • Swoole\Mmap — The Swoole\Mmap class
    • Swoole\MySQL — The Swoole\MySQL class
    • Swoole\MySQL\Exception — The Swoole\MySQL\Exception class
    • Swoole\Process — The Swoole\Process class
    • Swoole\Redis\Server — The Swoole\Redis\Server class
    • Swoole\Serialize — The Swoole\Serialize class
    • Swoole\Server — The Swoole\Server class
    • Swoole\Table — The Swoole\Table class
    • Swoole\Timer — The Swoole\Timer class
    • Swoole\WebSocket\Frame — The Swoole\WebSocket\Frame class
    • Swoole\WebSocket\Server — The Swoole\WebSocket\Server class
  • Tidy
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • tidy — tidy クラス
    • tidyNode — tidyNode クラス
    • Tidy 関数
  • Tokenizer
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PhpToken — PhpToken クラス
    • Tokenizer 関数
  • URLs
    • はじめに
    • 定義済み定数
    • URL 関数
  • V8js — V8 JavaScript Engine 統合
    • はじめに
    • インストール/設定
    • 例
    • V8Js — V8Js クラス
    • V8JsException — V8JsException クラス
  • Yaml — YAML によるデータのシリアライズ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • コールバック
    • Yaml 関数
  • Yaf — Yet Another Framework (Yaf)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • アプリケーションの設定
    • Yaf_Application — Yaf_Application クラス
    • Yaf_Bootstrap_Abstract — Yaf_Bootstrap_Abstract クラス
    • Yaf_Dispatcher — Yaf_Dispatcher クラス
    • Yaf_Config_Abstract — Yaf_Config_Abstract クラス
    • Yaf_Config_Ini — Yaf_Config_Ini クラス
    • Yaf_Config_Simple — Yaf_Config_Simple クラス
    • Yaf_Controller_Abstract — Yaf_Controller_Abstract クラス
    • Yaf_Action_Abstract — Yaf_Action_Abstract クラス
    • Yaf_View_Interface — Yaf_View_Interface クラス
    • Yaf_View_Simple — Yaf_View_Simple クラス
    • Yaf_Loader — Yaf_Loader クラス
    • Yaf_Plugin_Abstract — Yaf_Plugin_Abstract クラス
    • Yaf_Registry — Yaf_Registry クラス
    • Yaf_Request_Abstract — Yaf_Request_Abstract クラス
    • Yaf_Request_Http — Yaf_Request_Http クラス
    • Yaf_Request_Simple — Yaf_Request_Simple クラス
    • Yaf_Response_Abstract — Yaf_Response_Abstract クラス
    • Yaf_Route_Interface — Yaf_Route_Interface クラス
    • Yaf_Route_Map — Yaf_Route_Map クラス
    • Yaf_Route_Regex — Yaf_Route_Regex クラス
    • Yaf_Route_Rewrite — Yaf_Route_Rewrite クラス
    • Yaf_Router — Yaf_Router クラス
    • Yaf_Route_Simple — Yaf_Route_Simple クラス
    • Yaf_Route_Static — Yaf_Route_Static クラス
    • Yaf_Route_Supervar — Yaf_Route_Supervar クラス
    • Yaf_Session — Yaf_Session クラス
    • Yaf_Exception — Yaf_Exception クラス
    • Yaf_Exception_TypeError — Yaf_Exception_TypeError クラス
    • Yaf_Exception_StartupError — Yaf_Exception_StartupError クラス
    • Yaf_Exception_DispatchFailed — Yaf_Exception_DispatchFailed クラス
    • Yaf_Exception_RouterFailed — Yaf_Exception_RouterFailed クラス
    • Yaf_Exception_LoadFailed — Yaf_Exception_LoadFailed クラス
    • Yaf_Exception_LoadFailed_Module — Yaf_Exception_LoadFailed_Module クラス
    • Yaf_Exception_LoadFailed_Controller — Yaf_Exception_LoadFailed_Controller クラス
    • Yaf_Exception_LoadFailed_Action — Yaf_Exception_LoadFailed_Action クラス
    • Yaf_Exception_LoadFailed_View — Yaf_Exception_LoadFailed_View クラス
  • Yaconf
    • はじめに
    • インストール/設定
    • Yaconf — The Yaconf class
  • Taint
    • はじめに
    • インストール/設定
    • 詳細
    • Taint 関数
  • Data Structures
    • はじめに
    • インストール/設定
    • 例
    • Ds\Collection — The Collection interface
    • Ds\Hashable — The Hashable interface
    • Ds\Sequence — The Sequence interface
    • Ds\Vector — The Vector class
    • Ds\Deque — The Deque class
    • Ds\Map — The Map class
    • Ds\Pair — The Pair class
    • Ds\Set — The Set class
    • Ds\Stack — The Stack class
    • Ds\Queue — The Queue class
    • Ds\PriorityQueue — The PriorityQueue class
  • var_representation
    • はじめに
    • インストール/設定
    • 定義済み定数
    • var_representation 関数


Geo IP ロケーション

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • GeoIP 関数
    • geoip_asnum_by_name — AS番号(ASN) を取得する
    • geoip_continent_code_by_name — 二文字の大陸コードを取得する
    • geoip_country_code_by_name — 二文字の国コードを取得する
    • geoip_country_code3_by_name — 三文字の国コードを取得する
    • geoip_country_name_by_name — 完全な国名を取得する
    • geoip_database_info — GeoIP データベースの情報を取得する
    • geoip_db_avail — GeoIP データベースが使用可能かどうかを調べる
    • geoip_db_filename — 対応する GeoIP データベースのファイル名を返す
    • geoip_db_get_all_info — すべての GeoIP データベース形式についての詳細情報を返す
    • geoip_domain_by_name — セカンドレベルドメインの名前を取得する
    • geoip_id_by_name — インターネット接続方式を取得する
    • geoip_isp_by_name — インターネットサービスプロバイダ (ISP) 名を取得する
    • geoip_netspeedcell_by_name — インターネットへの接続速度を取得する
    • geoip_org_by_name — 組織名を取得する
    • geoip_record_by_name — GeoIP データベースで見つかった詳細な都市情報を返す
    • geoip_region_by_name — 国コードおよび地域を取得する
    • geoip_region_name_by_code — 国コードと地域コードから地域名を返す
    • geoip_setup_custom_directory — GeoIP データベースのカスタムディレクトリを設定する
    • geoip_time_zone_by_country_and_region — 国コードと地域コードからタイムゾーンを返す


はじめに

GeoIP 拡張モジュールを使用すると、IP アドレスの場所を探すことができます。 市、州、国、経度、緯度そして ISP や接続方式などの情報が GeoIP を用いて取得できます。

警告

この拡張モジュールは、MaxMind の現在の "GeoIP2" データベースをサポートしません。 "GeoIP legacy" データベース・ファイルのみサポートします。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • GeoIP
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

この拡張モジュールを使用するには、GeoIP C ライブラリのバージョン 1.4.0 以降がインストールされていなければなりません。最新のバージョンは » http://www.maxmind.com/app/c から取得できるので、これをコンパイルします。

デフォルトでは、Free GeoIP Country データベースあるいは GeoLite City データベースにしかアクセスできません。 しかし、それ以外のデータベースを使用することも可能です。その場合には » Maxmind から商用ライセンスを購入しなければなりません。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/geoip.


実行時設定

php.ini の設定により動作が変化します。

GeoIP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
geoip.custom_directory | "" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

geoip.custom_directory string

デフォルトは空ですが、 ライブラリ中にコンパイルされているパスとは異なるパスに強制的に変更可能です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

GEOIP_COUNTRY_EDITION (int)
GEOIP_REGION_EDITION_REV0 (int)
GEOIP_CITY_EDITION_REV0 (int)
GEOIP_ORG_EDITION (int)
GEOIP_ISP_EDITION (int)
GEOIP_CITY_EDITION_REV1 (int)
GEOIP_REGION_EDITION_REV1 (int)
GEOIP_PROXY_EDITION (int)
GEOIP_ASNUM_EDITION (int)
GEOIP_NETSPEED_EDITION (int)
GEOIP_DOMAIN_EDITION (int)

以下の定数は、ネット接続のスピードを表します。

GEOIP_UNKNOWN_SPEED (int)
GEOIP_DIALUP_SPEED (int)
GEOIP_CABLEDSL_SPEED (int)
GEOIP_CORPORATE_SPEED (int)


GeoIP 関数

目次

  • geoip_asnum_by_name — AS番号(ASN) を取得する
  • geoip_continent_code_by_name — 二文字の大陸コードを取得する
  • geoip_country_code_by_name — 二文字の国コードを取得する
  • geoip_country_code3_by_name — 三文字の国コードを取得する
  • geoip_country_name_by_name — 完全な国名を取得する
  • geoip_database_info — GeoIP データベースの情報を取得する
  • geoip_db_avail — GeoIP データベースが使用可能かどうかを調べる
  • geoip_db_filename — 対応する GeoIP データベースのファイル名を返す
  • geoip_db_get_all_info — すべての GeoIP データベース形式についての詳細情報を返す
  • geoip_domain_by_name — セカンドレベルドメインの名前を取得する
  • geoip_id_by_name — インターネット接続方式を取得する
  • geoip_isp_by_name — インターネットサービスプロバイダ (ISP) 名を取得する
  • geoip_netspeedcell_by_name — インターネットへの接続速度を取得する
  • geoip_org_by_name — 組織名を取得する
  • geoip_record_by_name — GeoIP データベースで見つかった詳細な都市情報を返す
  • geoip_region_by_name — 国コードおよび地域を取得する
  • geoip_region_name_by_code — 国コードと地域コードから地域名を返す
  • geoip_setup_custom_directory — GeoIP データベースのカスタムディレクトリを設定する
  • geoip_time_zone_by_country_and_region — 国コードと地域コードからタイムゾーンを返す


AS番号(ASN) を取得する

  • ≪ GeoIP 関数
  • geoip_continent_code_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • AS番号(ASN) を取得する

geoip_asnum_by_name

(PECL geoip >= 1.1.0)

geoip_asnum_by_name — AS番号(ASN) を取得する

説明

geoip_asnum_by_name(string $hostname): string

geoip_asnum_by_name() 関数は、 IPアドレスに関連付けられたAS番号(ASN)を返します。

パラメータ

hostname

ホスト名またはIPアドレス

戻り値

成功時にはAS番号を返します。 アドレスがデータベースに見つからなかった場合は false を返します。

例

例1 geoip_asnum_by_name() の例

この例は、www.example.com のAS番号を出力します。

<?php
$asn = geoip_asnum_by_name('www.example.com');

if ($asn) {
echo 'The ASN is: ' . $asn;
}
?>

上の例の出力は以下となります。

The ASN is: AS15133 EdgeCast Networks, Inc


二文字の大陸コードを取得する

  • ≪ geoip_asnum_by_name
  • geoip_country_code_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 二文字の大陸コードを取得する

geoip_continent_code_by_name

(PECL geoip >= 1.0.3)

geoip_continent_code_by_name — 二文字の大陸コードを取得する

説明

geoip_continent_code_by_name(string $hostname): string

geoip_continent_code_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する二文字の大陸コードを返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

戻り値

成功した場合には二文字の大陸コード、 アドレスがデータベースで見つからない場合には false を返します。

大陸コード
コード | 大陸名
AF | アフリカ
AN | 南極
AS | アジア
EU | ヨーロッパ
NA | 北アメリカ
OC | オセアニア
SA | 南アメリカ

例

例1 geoip_continent_code_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$continent = geoip_continent_code_by_name('www.example.com');
if ($continent) {
echo 'This host is located in: ' . $continent;
}
?>

上の例の出力は以下となります。

This host is located in: NA

参考

  • geoip_country_code_by_name() - 二文字の国コードを取得する


二文字の国コードを取得する

  • ≪ geoip_continent_code_by_name
  • geoip_country_code3_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 二文字の国コードを取得する

geoip_country_code_by_name

(PECL geoip >= 0.2.0)

geoip_country_code_by_name — 二文字の国コードを取得する

説明

geoip_country_code_by_name(string $hostname): string

geoip_country_code_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する二文字の国コードを返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

戻り値

成功した場合には二文字の ISO 国コード、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_country_code_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$country = geoip_country_code_by_name('www.example.com');
if ($country) {
echo 'This host is located in: ' . $country;
}
?>

上の例の出力は以下となります。

This host is located in: US

注意

警告

戻り値の完全なリストは » http://www.maxmind.com/en/iso3166 を参照ください。ここには特別なコードも含まれています。

参考

  • geoip_country_code3_by_name() - 三文字の国コードを取得する
  • geoip_country_name_by_name() - 完全な国名を取得する


三文字の国コードを取得する

  • ≪ geoip_country_code_by_name
  • geoip_country_name_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 三文字の国コードを取得する

geoip_country_code3_by_name

(PECL geoip >= 0.2.0)

geoip_country_code3_by_name — 三文字の国コードを取得する

説明

geoip_country_code3_by_name(string $hostname): string

geoip_country_code3_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する三文字の国コードを返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

戻り値

成功した場合には三文字の国コード、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_country_code3_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$country = geoip_country_code3_by_name('www.example.com');
if ($country) {
echo 'This host is located in: ' . $country;
}
?>

上の例の出力は以下となります。

This host is located in: USA

参考

  • geoip_country_code_by_name() - 二文字の国コードを取得する
  • geoip_country_name_by_name() - 完全な国名を取得する


完全な国名を取得する

  • ≪ geoip_country_code3_by_name
  • geoip_database_info ≫
  • PHP Manual
  • GeoIP 関数
  • 完全な国名を取得する

geoip_country_name_by_name

(PECL geoip >= 0.2.0)

geoip_country_name_by_name — 完全な国名を取得する

説明

geoip_country_name_by_name(string $hostname): string

geoip_country_name_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する完全な国名を返します。

パラメータ

hostname

場所を探す対象となるホスト名あるいは IP アドレス。

戻り値

成功した場合には国名、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_country_name_by_name() の例

これは、ホスト example.com がどこにあるのかを表示します。

<?php
$country = geoip_country_name_by_name('www.example.com');
if ($country) {
echo 'This host is located in: ' . $country;
}
?>

上の例の出力は以下となります。

This host is located in: United States

参考

  • geoip_country_code_by_name() - 二文字の国コードを取得する
  • geoip_country_code3_by_name() - 三文字の国コードを取得する


GeoIP データベースの情報を取得する

  • ≪ geoip_country_name_by_name
  • geoip_db_avail ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースの情報を取得する

geoip_database_info

(PECL geoip >= 0.2.0)

geoip_database_info — GeoIP データベースの情報を取得する

説明

geoip_database_info(int $database = GEOIP_COUNTRY_EDITION): string

geoip_database_info() 関数は、 GeoIP データベースのバージョンを返します。 このバージョンはバイナリファイルの内部で定義されています。

この関数を引数なしでコールすると、GeoIP Free Country Edition のバージョンを返します。

パラメータ

database

データベースの型を整数値で指定します。この拡張モジュールで定義されている さまざまな定数 (例: GEOIP_*_EDITION) を使用することができます。

戻り値

対応するデータベースのバージョン、あるいはエラー時に null を返します。

例

例1 geoip_database_info() の例

これは、データベースに関する情報を出力します。

<?php
print geoip_database_info(GEOIP_COUNTRY_EDITION);
?>

上の例の出力は以下となります。

GEO-106FREE 20060801 Build 1 Copyright (c) 2006 MaxMind LLC All Rights Reserved


GeoIP データベースが使用可能かどうかを調べる

  • ≪ geoip_database_info
  • geoip_db_filename ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースが使用可能かどうかを調べる

geoip_db_avail

(PECL geoip >= 1.0.1)

geoip_db_avail — GeoIP データベースが使用可能かどうかを調べる

説明

geoip_db_avail(int $database): bool

geoip_db_avail() 関数は、対応する GeoIP データベースが存在し、ディスク上にオープンできるかどうかを調べます。

これは、そのファイルが適切なデータベース形式かどうかを調べるものではありません。 単にそのファイルが読み込み可能かどうかを調べるだけです。

パラメータ

database

データベースの形式を表す整数値。この拡張モジュールで定義している さまざまな定数 (GEOIP_*_EDITION) を使用することができます。

戻り値

データベースが存在する場合に true、存在しない場合に false、 エラー時に null を返します。

例

例1 geoip_db_avail() の例

これは、現在のデータベースのバージョンを文字列で出力します。

<?php

if (geoip_db_avail(GEOIP_COUNTRY_EDITION))
print geoip_database_info(GEOIP_COUNTRY_EDITION);
?>

上の例の出力は以下となります。

GEO-106FREE 20080801 Build 1 Copyright (c) 2006 MaxMind LLC All Rights Reserved


対応する GeoIP データベースのファイル名を返す

  • ≪ geoip_db_avail
  • geoip_db_get_all_info ≫
  • PHP Manual
  • GeoIP 関数
  • 対応する GeoIP データベースのファイル名を返す

geoip_db_filename

(PECL geoip >= 1.0.1)

geoip_db_filename — 対応する GeoIP データベースのファイル名を返す

説明

geoip_db_filename(int $database): string

geoip_db_filename() 関数は、 対応する GeoIP データベースのファイル名を返します。

これは、そのファイルが存在するかどうかを表すものではありません。 単に、ライブラリがデータベースを探す先を返すだけのものです。

パラメータ

database

データベースの形式を表す整数値。この拡張モジュールで定義している さまざまな定数 (GEOIP_*_EDITION) を使用することができます。

戻り値

対応するデータベースのファイル名、あるいはエラー時に null を返します。

例

例1 geoip_db_filename() の例

これは、対応するデータベースのファイル名を出力します。

<?php

print geoip_db_filename(GEOIP_COUNTRY_EDITION);

?>

上の例の出力は以下となります。

/usr/share/GeoIP/GeoIP.dat


すべての GeoIP データベース形式についての詳細情報を返す

  • ≪ geoip_db_filename
  • geoip_domain_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • すべての GeoIP データベース形式についての詳細情報を返す

geoip_db_get_all_info

(PECL geoip >= 1.0.1)

geoip_db_get_all_info — すべての GeoIP データベース形式についての詳細情報を返す

説明

geoip_db_get_all_info(): array

geoip_db_get_all_info() 関数は、 すべての GeoIP データベース形式についての詳細情報を多次元配列で返します。

この関数は、データベースがインストールされていない場合でも使用可能です。 その場合は、使用できないことが返されます。

返される連想配列のキーは、次のようになります。

  • "available" -- DB が使用可能かどうか (geoip_db_avail() を参照ください)
  • "description" -- データベースについての説明
  • "filename" -- ディスク上でのデータベースのファイル名 (geoip_db_filename() を参照ください)

パラメータ

この関数にはパラメータはありません。

戻り値

連想配列を返します。

例

例1 geoip_db_get_all_info() の例

これは、すべての情報を含む配列を表示します。

<?php
$infos = geoip_db_get_all_info();
if (is_array($infos)) {
var_dump($infos);
}
?>

上の例の出力は以下となります。

array(11) {
  [1]=>
  array(3) {
    ["available"]=>
    bool(true)
    ["description"]=>
    string(21) "GeoIP Country Edition"
    ["filename"]=>
    string(32) "/usr/share/GeoIP/GeoIP.dat"
  }

[ ... ]

  [11]=>
  array(3) {
    ["available"]=>
    bool(false)
    ["description"]=>
    string(25) "GeoIP Domain Name Edition"
    ["filename"]=>
    string(38) "/usr/share/GeoIP/GeoIPDomain.dat"
  }
}

例2 geoip_db_get_all_info() の例

さまざまな定数を使用することで、特定の情報のみを取得することができます。

<?php
$infos = geoip_db_get_all_info();
if ($infos[GEOIP_COUNTRY_EDITION]['available']) {
echo $infos[GEOIP_COUNTRY_EDITION]['description'];
}
?>

上の例の出力は以下となります。

GeoIP Country Edition


セカンドレベルドメインの名前を取得する

  • ≪ geoip_db_get_all_info
  • geoip_id_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • セカンドレベルドメインの名前を取得する

geoip_domain_by_name

(PECL geoip >= 1.1.0)

geoip_domain_by_name — セカンドレベルドメインの名前を取得する

説明

geoip_domain_by_name(string $hostname): string

geoip_domain_by_name() 関数は ホスト名またはIPアドレスに関連付けられた セカンドレベルドメイン名を返します。

この関数は、商用の GeoIP Domain Edition を購入したユーザーだけが利用可能です。 適切にデータベースが配置されていない場合は、警告が発生します。

パラメータ

hostname

ホスト名またはIPアドレス

戻り値

成功時にはドメイン名を返します。 アドレスがデータベースに存在しない場合は false を返します。

例

例1 geoip_domain_by_name() の例

この例は、IPアドレス 61.106.139.1 に関連付けられているドメインを出力します。

<?php
$domain = geoip_domain_by_name('61.106.139.1');

if ($domain) {
echo 'The domain is: '. $domain;
}

?>

上の例の出力は以下となります。

The domain is: von.co.kr


インターネット接続方式を取得する

  • ≪ geoip_domain_by_name
  • geoip_isp_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • インターネット接続方式を取得する

geoip_id_by_name

(PECL geoip >= 0.2.0)

geoip_id_by_name — インターネット接続方式を取得する

説明

geoip_id_by_name(string $hostname): int

geoip_id_by_name() 関数は、 ホスト名あるいは IP アドレスに対応するインターネット接続方式を返します。

戻り値は数値で、以下の定数と比較できます。

  • GEOIP_UNKNOWN_SPEED
  • GEOIP_DIALUP_SPEED
  • GEOIP_CABLEDSL_SPEED
  • GEOIP_CORPORATE_SPEED

パラメータ

hostname

接続方式を探す対象となるホスト名あるいは IP アドレス。

戻り値

接続方式を返します。

例

例1 geoip_id_by_name() の例

これは、ホスト example.com の接続方式を返します。

<?php
$netspeed = geoip_id_by_name('www.example.com');

echo 'The connection type is ';

switch ($netspeed) {
case GEOIP_DIALUP_SPEED:
echo 'dial-up';
break;
case GEOIP_CABLEDSL_SPEED:
echo 'cable or DSL';
break;
case GEOIP_CORPORATE_SPEED:
echo 'corporate';
break;
case GEOIP_UNKNOWN_SPEED:
default:
echo 'unknown';
}
?>

上の例の出力は以下となります。

The connection type is corporate


インターネットサービスプロバイダ (ISP) 名を取得する

  • ≪ geoip_id_by_name
  • geoip_netspeedcell_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • インターネットサービスプロバイダ (ISP) 名を取得する

geoip_isp_by_name

(PECL geoip >= 1.0.2)

geoip_isp_by_name — インターネットサービスプロバイダ (ISP) 名を取得する

説明

geoip_isp_by_name(string $hostname): string

geoip_isp_by_name() 関数は、 IP アドレスに対応するインターネットサービスプロバイダ (ISP) 名を返します。

現在この関数を使用できるのは、商用の GeoIP ISP Edition を購入した人だけです。 適切なデータベースが見つからない場合には警告が発生します。

パラメータ

hostname

ホスト名あるいは IP アドレス。

戻り値

成功した場合には ISP 名、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_isp_by_name() の例

これは、ホスト example.com の ISP 名を表示します。

<?php
$isp = geoip_isp_by_name('www.example.com');
if ($isp) {
echo 'This host IP is from ISP: ' . $isp;
}
?>

上の例の出力は以下となります。

This host IP is from ISP: ICANN c/o Internet Assigned Numbers Authority


インターネットへの接続速度を取得する

  • ≪ geoip_isp_by_name
  • geoip_org_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • インターネットへの接続速度を取得する

geoip_netspeedcell_by_name

(PECL geoip >= 1.1.0)

geoip_netspeedcell_by_name — インターネットへの接続速度を取得する

説明

geoip_netspeedcell_by_name(string $hostname): string

geoip_netspeedcell_by_name() 関数は、 ホスト名またはIPアドレスに対応するインターネットへの接続タイプと接続速度を返します。

この関数は、GeoIP Library 1.4.8 以降でのみ利用可能です。

この関数は、商用の GeoIP NetSpeedCell Edition を購入したユーザーのみが利用可能です。 適切にデータベースが配置されていない場合は、警告が発生します。

この関数の戻り値は文字列です。共通の値は以下の通りです:

  • Cable/DSL
  • Dialup
  • Cellular
  • Corporate

パラメータ

hostname

ホスト名またはIPアドレス

戻り値

成功時には接続スピードを返します。 アドレスがデータベースに存在しない場合は、false を返します。

例

例1 geoip_netspeedcell_by_name() の例

この例は、ホスト example.com の接続速度を出力します。

<?php
$netspeed = geoip_netspeedcell_by_name('www.example.com');

if ($netspeed) {
echo 'The connection type is: '. $netspeed;
}
?>

上の例の出力は以下となります。

The connection type is: Corporate


組織名を取得する

  • ≪ geoip_netspeedcell_by_name
  • geoip_record_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • 組織名を取得する

geoip_org_by_name

(PECL geoip >= 0.2.0)

geoip_org_by_name — 組織名を取得する

説明

geoip_org_by_name(string $hostname): string

geoip_org_by_name() 関数は、 その IP アドレスが割り当てられている組織の名前を返します。

現在この関数を使用できるのは、商用の GeoIP Organization, ISP あるいは AS Edition を購入した人だけです。 適切なデータベースが見つからない場合には警告が発生します。

パラメータ

hostname

ホスト名あるいは IP アドレス。

戻り値

成功した場合には組織名、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_org_by_name() の例

これは、ホスト example.com の IP が誰に割り当てられているかを表示します。

<?php
$org = geoip_org_by_name('www.example.com');
if ($org) {
echo 'This host IP is allocated to: ' . $org;
}
?>

上の例の出力は以下となります。

This host IP is allocated to: ICANN c/o Internet Assigned Numbers Authority


GeoIP データベースで見つかった詳細な都市情報を返す

  • ≪ geoip_org_by_name
  • geoip_region_by_name ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースで見つかった詳細な都市情報を返す

geoip_record_by_name

(PECL geoip >= 0.2.0)

geoip_record_by_name — GeoIP データベースで見つかった詳細な都市情報を返す

説明

geoip_record_by_name(string $hostname): array

geoip_record_by_name() 関数は、 ホスト名あるいは IP アドレスに対応するレコード情報を返します。

この関数は、GeoLite City Edition および商用の GeoIP City Edition のどちらでも使用可能です。 適切なデータベースが見つからない場合には警告が発生します。

返される連想配列には、以下のようなさまざまな名前のキーが含まれます。

  • "continent_code" -- 二文字の大陸コード (バージョン 1.0.4 以降で libgeoip 1.4.3 以降を使用した場合)
  • "country_code" -- 二文字の国コード (geoip_country_code_by_name() を参照ください)
  • "country_code3" -- 三文字の国コード (geoip_country_code3_by_name() を参照ください)
  • "country_name" -- 国名 (geoip_country_name_by_name() を参照ください)
  • "region" -- 地域コード (例: カリフォルニアなら CA)
  • "city" -- 市
  • "postal_code" -- 郵便番号、FSA あるいは Zip コード
  • "latitude" -- 緯度 (符号付き浮動小数点形式(float))
  • "longitude" -- 経度 (符号付浮動小数点形式(float))
  • "dma_code" -- Designated Market Area コード (アメリカおよびカナダのみ)
  • "area_code" -- PSTN エリアコード (例: 212)

パラメータ

hostname

レコードを探す対象となるホスト名あるいは IP アドレス。

戻り値

成功した場合には連想配列、 アドレスがデータベースで見つからない場合には false を返します。

変更履歴

バージョン | 説明
PECL geoip 1.0.4 | continent_code が GeoIP Library 1.4.3 以降でのみ使えるようになりました。
PECL geoip 1.0.3 | country_code3 および country_name が追加されました。

例

例1 geoip_record_by_name() の例

これは、ホスト example.com のレコードを含む連想配列を表示します。

<?php
$record = geoip_record_by_name('www.example.com');
if ($record) {
print_r($record);
}
?>

上の例の出力は以下となります。

Array
(
    [continent_code] => NA
    [country_code] => US
    [country_code3] => USA
    [country_name] => United States
    [region] => CA
    [city] => Marina Del Rey
    [postal_code] =>
    [latitude] => 33.9776992798
    [longitude] => -118.435096741
    [dma_code] => 803
    [area_code] => 310
)


国コードおよび地域を取得する

  • ≪ geoip_record_by_name
  • geoip_region_name_by_code ≫
  • PHP Manual
  • GeoIP 関数
  • 国コードおよび地域を取得する

geoip_region_by_name

(PECL geoip >= 0.2.0)

geoip_region_by_name — 国コードおよび地域を取得する

説明

geoip_region_by_name(string $hostname): array

geoip_region_by_name() 関数は、 ホスト名あるいは IP アドレスに対応する国および地域を返します。

現在この関数を使用できるのは、商用の GeoIP Region Edition を購入した人だけです。 適切なデータベースが見つからない場合には警告が発生します。

返される連想配列には、以下のようなさまざまな名前のキーが含まれます。

  • "country_code" -- 二文字の国コード (geoip_country_code_by_name() を参照ください)
  • "region" -- 地域コード (例: カリフォルニアなら CA)

パラメータ

hostname

地域を探す対象となるホスト名あるいは IP アドレス。

戻り値

成功した場合には連想配列、 アドレスがデータベースで見つからない場合には false を返します。

例

例1 geoip_region_by_name() の例

これは、ホスト example.com の国コードおよび地域を含む配列を表示します。

<?php
$region = geoip_region_by_name('www.example.com');
if ($region) {
print_r($region);
}
?>

上の例の出力は以下となります。

Array
(
    [country_code] => US
    [region] => CA
)


国コードと地域コードから地域名を返す

  • ≪ geoip_region_by_name
  • geoip_setup_custom_directory ≫
  • PHP Manual
  • GeoIP 関数
  • 国コードと地域コードから地域名を返す

geoip_region_name_by_code

(PECL geoip >= 1.0.4)

geoip_region_name_by_code — 国コードと地域コードから地域名を返す

説明

geoip_region_name_by_code(string $country_code, string $region_code): string

geoip_region_name_by_code() 関数は、 国コードと地域コードの組み合わせに対応する地域名を返します。

アメリカの場合、地域コードは各州の名前を二文字で略したものとなります。 カナダの場合、地域コードは Canada Post による二文字の州コードに対応します。

それ以外の場所では、GeoIP は FIPS 10-4 コードを用いて地域を表します。 FIPS 10-4 コードの詳細な一覧は » http://www.maxmind.com/app/fips10_4 で確認できます。

この関数は、GeoIP Library バージョン 1.4.1 以降を使っている場合に使用可能です。 データは直接 GeoIP Library から受け取り、データベースは使用しません。

パラメータ

country_code

二文字の国コード (geoip_country_code_by_name() を参照ください)。

region_code

二文字 (あるいは二桁) の地域コード (geoip_region_by_name() を参照ください)。

戻り値

成功した場合は地域名、国コードと地域コードの組に対応する地域が見つからなかった場合は false を返します。

例

例1 US/Canada の地域コードを使用した geoip_region_name_by_code() の例

これは、国 CA (カナダ)、地域 QC (ケベック) に対応する地域名を表示します。

<?php
$region = geoip_region_name_by_code('CA', 'QC');
if ($region) {
echo 'Region name for CA/QC is: ' . $region;
}
?>

上の例の出力は以下となります。

Region name for CA/QC is: Quebec

例2 FIPS コードを使用した geoip_region_name_by_code() の例

これは、国 JP (日本)、地域 01 に対応する地域名を表示します。

<?php
$region = geoip_region_name_by_code('JP', '01');
if ($region) {
echo 'Region name for JP/01 is: ' . $region;
}
?>

上の例の出力は以下となります。

Region name for JP/01 is: Aichi


GeoIP データベースのカスタムディレクトリを設定する

  • ≪ geoip_region_name_by_code
  • geoip_time_zone_by_country_and_region ≫
  • PHP Manual
  • GeoIP 関数
  • GeoIP データベースのカスタムディレクトリを設定する

geoip_setup_custom_directory

(PECL geoip >= 1.1.0)

geoip_setup_custom_directory — GeoIP データベースのカスタムディレクトリを設定する

説明

geoip_setup_custom_directory(string $path): void

geoip_setup_custom_directory() 関数は、 GeoIPデータベースのデフォルトディレクトリを変更します。 これは geoip.custom_directory を変更することと同等です。

パラメータ

path

ディスク上に置くGeoIP データベースのフルパス。

戻り値

値を返しません。

例

例1 geoip_setup_custom_directory() の例

この例は、GeoIP のデータベースパスを変更します。

<?php

geoip_setup_custom_directory('/some/other/path');

print geoip_db_filename(GEOIP_COUNTRY_EDITION);

?>

上の例の出力は以下となります。

/some/other/path/GeoIP.dat


国コードと地域コードからタイムゾーンを返す

  • ≪ geoip_setup_custom_directory
  • FANN ≫
  • PHP Manual
  • GeoIP 関数
  • 国コードと地域コードからタイムゾーンを返す

geoip_time_zone_by_country_and_region

(PECL geoip >= 1.0.4)

geoip_time_zone_by_country_and_region — 国コードと地域コードからタイムゾーンを返す

説明

geoip_time_zone_by_country_and_region(string $country_code, string $region_code = ?): string

geoip_time_zone_by_country_and_region() 関数は、 国コードと地域コードの組み合わせに対応するタイムゾーンを返します。

アメリカの場合、地域コードは各州の名前を二文字で略したものとなります。 カナダの場合、地域コードは Canada Post による二文字の州コードに対応します。

それ以外の場所では、GeoIP は FIPS 10-4 コードを用いて地域を表します。 FIPS 10-4 コードの詳細な一覧は » http://www.maxmind.com/app/fips10_4 で確認できます。

この関数は、GeoIP Library バージョン 1.4.1 以降を使っている場合に使用可能です。 データは直接 GeoIP Library から受け取り、データベースは使用しません。

パラメータ

country_code

二文字の国コード (geoip_country_code_by_name() を参照ください)。

region_code

二文字 (あるいは二桁) の地域コード (geoip_region_by_name() を参照ください)。

戻り値

成功した場合はタイムゾーン、国コードと地域コードの組に対応するタイムゾーンが見つからなかった場合は false を返します。

例

例1 US/Canada の地域コードを使用した geoip_time_zone_by_country_and_region() の例

これは、国 CA (カナダ)、地域 QC (ケベック) に対応するタイムゾーンを表示します。

<?php
$timezone = geoip_time_zone_by_country_and_region('CA', 'QC');
if ($timezone) {
echo 'Time zone for CA/QC is: ' . $timezone;
}
?>

上の例の出力は以下となります。

Time zone for CA/QC is: America/Montreal

例2 FIPS コードを使用した geoip_time_zone_by_country_and_region() の例

これは、国 JP (日本)、地域 01 に対応するタイムゾーンを表示します。

<?php
$timezone = geoip_time_zone_by_country_and_region('JP', '01');
if ($timezone) {
echo 'Time zone for JP/01 is: ' . $timezone;
}
?>

上の例の出力は以下となります。

Time zone for JP/01 is: Asia/Tokyo


FANN (Fast Artificial Neural Network)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
    • XOR training
  • Fann 関数
    • fann_cascadetrain_on_data — Trains on an entire dataset, for a period of time using the Cascade2 training algorithm
    • fann_cascadetrain_on_file — Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm
    • fann_clear_scaling_params — Clears scaling parameters
    • fann_copy — Creates a copy of a fann structure
    • fann_create_from_file — Constructs a backpropagation neural network from a configuration file
    • fann_create_shortcut — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
    • fann_create_shortcut_array — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
    • fann_create_sparse — Creates a standard backpropagation neural network, which is not fully connected
    • fann_create_sparse_array — Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
    • fann_create_standard — Creates a standard fully connected backpropagation neural network
    • fann_create_standard_array — Creates a standard fully connected backpropagation neural network using an array of layer sizes
    • fann_create_train — Creates an empty training data struct
    • fann_create_train_from_callback — Creates the training data struct from a user supplied function
    • fann_descale_input — Scale data in input vector after get it from ann based on previously calculated parameters
    • fann_descale_output — Scale data in output vector after get it from ann based on previously calculated parameters
    • fann_descale_train — Descale input and output data based on previously calculated parameters
    • fann_destroy — Destroys the entire network and properly freeing all the associated memory
    • fann_destroy_train — Destructs the training data
    • fann_duplicate_train_data — Returns an exact copy of a fann train data
    • fann_get_activation_function — Returns the activation function
    • fann_get_activation_steepness — Returns the activation steepness for supplied neuron and layer number
    • fann_get_bias_array — Get the number of bias in each layer in the network
    • fann_get_bit_fail — The number of fail bits
    • fann_get_bit_fail_limit — Returns the bit fail limit used during training
    • fann_get_cascade_activation_functions — Returns the cascade activation functions
    • fann_get_cascade_activation_functions_count — Returns the number of cascade activation functions
    • fann_get_cascade_activation_steepnesses — Returns the cascade activation steepnesses
    • fann_get_cascade_activation_steepnesses_count — The number of activation steepnesses
    • fann_get_cascade_candidate_change_fraction — Returns the cascade candidate change fraction
    • fann_get_cascade_candidate_limit — Return the candidate limit
    • fann_get_cascade_candidate_stagnation_epochs — Returns the number of cascade candidate stagnation epochs
    • fann_get_cascade_max_cand_epochs — Returns the maximum candidate epochs
    • fann_get_cascade_max_out_epochs — Returns the maximum out epochs
    • fann_get_cascade_min_cand_epochs — Returns the minimum candidate epochs
    • fann_get_cascade_min_out_epochs — Returns the minimum out epochs
    • fann_get_cascade_num_candidate_groups — Returns the number of candidate groups
    • fann_get_cascade_num_candidates — Returns the number of candidates used during training
    • fann_get_cascade_output_change_fraction — Returns the cascade output change fraction
    • fann_get_cascade_output_stagnation_epochs — Returns the number of cascade output stagnation epochs
    • fann_get_cascade_weight_multiplier — Returns the weight multiplier
    • fann_get_connection_array — Get connections in the network
    • fann_get_connection_rate — Get the connection rate used when the network was created
    • fann_get_errno — Returns the last error number
    • fann_get_errstr — Returns the last errstr
    • fann_get_layer_array — Get the number of neurons in each layer in the network
    • fann_get_learning_momentum — Returns the learning momentum
    • fann_get_learning_rate — Returns the learning rate
    • fann_get_MSE — Reads the mean square error from the network
    • fann_get_network_type — Get the type of neural network it was created as
    • fann_get_num_input — Get the number of input neurons
    • fann_get_num_layers — Get the number of layers in the neural network
    • fann_get_num_output — Get the number of output neurons
    • fann_get_quickprop_decay — Returns the decay which is a factor that weights should decrease in each iteration during quickprop training
    • fann_get_quickprop_mu — Returns the mu factor
    • fann_get_rprop_decrease_factor — Returns the increase factor used during RPROP training
    • fann_get_rprop_delta_max — Returns the maximum step-size
    • fann_get_rprop_delta_min — Returns the minimum step-size
    • fann_get_rprop_delta_zero — Returns the initial step-size
    • fann_get_rprop_increase_factor — Returns the increase factor used during RPROP training
    • fann_get_sarprop_step_error_shift — Returns the sarprop step error shift
    • fann_get_sarprop_step_error_threshold_factor — Returns the sarprop step error threshold factor
    • fann_get_sarprop_temperature — Returns the sarprop temperature
    • fann_get_sarprop_weight_decay_shift — Returns the sarprop weight decay shift
    • fann_get_total_connections — Get the total number of connections in the entire network
    • fann_get_total_neurons — Get the total number of neurons in the entire network
    • fann_get_train_error_function — Returns the error function used during training
    • fann_get_train_stop_function — Returns the stop function used during training
    • fann_get_training_algorithm — Returns the training algorithm
    • fann_init_weights — Initialize the weights using Widrow + Nguyen’s algorithm
    • fann_length_train_data — Returns the number of training patterns in the train data
    • fann_merge_train_data — Merges the train data
    • fann_num_input_train_data — Returns the number of inputs in each of the training patterns in the train data
    • fann_num_output_train_data — Returns the number of outputs in each of the training patterns in the train data
    • fann_print_error — Prints the error string
    • fann_randomize_weights — Give each connection a random weight between min_weight and max_weight
    • fann_read_train_from_file — Reads a file that stores training data
    • fann_reset_errno — Resets the last error number
    • fann_reset_errstr — Resets the last error string
    • fann_reset_MSE — Resets the mean square error from the network
    • fann_run — Will run input through the neural network
    • fann_save — Saves the entire network to a configuration file
    • fann_save_train — Save the training structure to a file
    • fann_scale_input — Scale data in input vector before feed it to ann based on previously calculated parameters
    • fann_scale_input_train_data — Scales the inputs in the training data to the specified range
    • fann_scale_output — Scale data in output vector before feed it to ann based on previously calculated parameters
    • fann_scale_output_train_data — Scales the outputs in the training data to the specified range
    • fann_scale_train — Scale input and output data based on previously calculated parameters
    • fann_scale_train_data — Scales the inputs and outputs in the training data to the specified range
    • fann_set_activation_function — Sets the activation function for supplied neuron and layer
    • fann_set_activation_function_hidden — Sets the activation function for all of the hidden layers
    • fann_set_activation_function_layer — Sets the activation function for all the neurons in the supplied layer
    • fann_set_activation_function_output — Sets the activation function for the output layer
    • fann_set_activation_steepness — Sets the activation steepness for supplied neuron and layer number
    • fann_set_activation_steepness_hidden — Sets the steepness of the activation steepness for all neurons in the all hidden layers
    • fann_set_activation_steepness_layer — Sets the activation steepness for all of the neurons in the supplied layer number
    • fann_set_activation_steepness_output — Sets the steepness of the activation steepness in the output layer
    • fann_set_bit_fail_limit — Set the bit fail limit used during training
    • fann_set_callback — Sets the callback function for use during training
    • fann_set_cascade_activation_functions — Sets the array of cascade candidate activation functions
    • fann_set_cascade_activation_steepnesses — Sets the array of cascade candidate activation steepnesses
    • fann_set_cascade_candidate_change_fraction — Sets the cascade candidate change fraction
    • fann_set_cascade_candidate_limit — Sets the candidate limit
    • fann_set_cascade_candidate_stagnation_epochs — Sets the number of cascade candidate stagnation epochs
    • fann_set_cascade_max_cand_epochs — Sets the max candidate epochs
    • fann_set_cascade_max_out_epochs — Sets the maximum out epochs
    • fann_set_cascade_min_cand_epochs — Sets the min candidate epochs
    • fann_set_cascade_min_out_epochs — Sets the minimum out epochs
    • fann_set_cascade_num_candidate_groups — Sets the number of candidate groups
    • fann_set_cascade_output_change_fraction — Sets the cascade output change fraction
    • fann_set_cascade_output_stagnation_epochs — Sets the number of cascade output stagnation epochs
    • fann_set_cascade_weight_multiplier — Sets the weight multiplier
    • fann_set_error_log — Sets where the errors are logged to
    • fann_set_input_scaling_params — Calculate input scaling parameters for future use based on training data
    • fann_set_learning_momentum — Sets the learning momentum
    • fann_set_learning_rate — Sets the learning rate
    • fann_set_output_scaling_params — Calculate output scaling parameters for future use based on training data
    • fann_set_quickprop_decay — Sets the quickprop decay factor
    • fann_set_quickprop_mu — Sets the quickprop mu factor
    • fann_set_rprop_decrease_factor — Sets the decrease factor used during RPROP training
    • fann_set_rprop_delta_max — Sets the maximum step-size
    • fann_set_rprop_delta_min — Sets the minimum step-size
    • fann_set_rprop_delta_zero — Sets the initial step-size
    • fann_set_rprop_increase_factor — Sets the increase factor used during RPROP training
    • fann_set_sarprop_step_error_shift — Sets the sarprop step error shift
    • fann_set_sarprop_step_error_threshold_factor — Sets the sarprop step error threshold factor
    • fann_set_sarprop_temperature — Sets the sarprop temperature
    • fann_set_sarprop_weight_decay_shift — Sets the sarprop weight decay shift
    • fann_set_scaling_params — Calculate input and output scaling parameters for future use based on training data
    • fann_set_train_error_function — Sets the error function used during training
    • fann_set_train_stop_function — Sets the stop function used during training
    • fann_set_training_algorithm — Sets the training algorithm
    • fann_set_weight — Set a connection in the network
    • fann_set_weight_array — Set connections in the network
    • fann_shuffle_train_data — Shuffles training data, randomizing the order
    • fann_subset_train_data — Returns an copy of a subset of the train data
    • fann_test — Test with a set of inputs, and a set of desired outputs
    • fann_test_data — Test a set of training data and calculates the MSE for the training data
    • fann_train — Train one iteration with a set of inputs, and a set of desired outputs
    • fann_train_epoch — Train one epoch with a set of training data
    • fann_train_on_data — Trains on an entire dataset for a period of time
    • fann_train_on_file — Trains on an entire dataset, which is read from file, for a period of time
  • FANNConnection — The FANNConnection class
    • FANNConnection::__construct — The connection constructor
    • FANNConnection::getFromNeuron — Returns the postions of starting neuron
    • FANNConnection::getToNeuron — Returns the postions of terminating neuron
    • FANNConnection::getWeight — Returns the connection weight
    • FANNConnection::setWeight — Sets the connections weight


はじめに

PHP binding for FANN (Fast Artificial Neural Network) Library which implements multilayer artificial neural networks with support for both fully connected and sparsely connected networks. It includes a framework for easy handling of training data sets. It is easy to use, versatile, well documented, and fast.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • FANN
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

PHP >= 5.2.0 and libfann >= 2.1.0


インストール手順

The FANN PHP extension should work on all Linux systems.

  • FANN Library Installation
  • PECL Installation
  • Manual Installation

FANN Library Installation

Before you start installation make sure that libfann is installed on your system. It's part of the main repository in the most Linux distributions (search for fann). You need a development version.

If it is not installed, you need to install it first. Either download it from the » official site or get it from your distro repository. For example on Fedora:

$ sudo yum install fann-devel
or Ubuntu:

$ sudo apt-get install libfann-dev

If the library is re-installed manually, then all old library file should be removed before re-installing otherwise the old library version could be linked.

PECL Installation

This extension is available on PECL. The installation is very simple. Just run:

$ sudo pecl install fann

Manual Installation

For developers and people interested in the latest changes, you can compile the driver from the latest source code on » Github. Go to Github and click the "Download ZIP" button. Then run:

$ unzip php-fann-master.zip
$ cd php-fann-master
$ phpize
$ ./configure
$ make all
$ sudo make install

Make the following changes to php.ini:

  • Make sure the extension_dir variable is pointing to the directory containing fann.so. The build will display where it is installing the PHP driver with output that looks something like:

Installing '/usr/lib/php/extensions/no-debug-non-zts-20060613/fann.so'
    Make sure that it is the same as the PHP extension directory by running:

$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20060613 =>
                   /usr/lib/php/extensions/no-debug-non-zts-20060613
    If it's not, change the extension_dir in php.ini or move fann.so.

  • To load the extension on PHP startup, add a line:

extension=fann.so


  • ≪ インストール手順
  • 定義済み定数 ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Training algorithms
FANN_TRAIN_INCREMENTAL (int)
Standard backpropagation algorithm, where the weights are updated after each training pattern. This means that the weights are updated many times during a single epoch. For this reason some problems, will train very fast with this algorithm, while other more advanced problems will not train very well.
FANN_TRAIN_BATCH (int)
Standard backpropagation algorithm, where the weights are updated after calculating the mean square error for the whole training set. This means that the weights are only updated once during a epoch. For this reason some problems, will train slower with this algorithm. But since the mean square error is calculated more correctly than in incremental training, some problems will reach a better solutions with this algorithm.
FANN_TRAIN_RPROP (int)
A more advanced batch training algorithm which achieves good results for many problems. The RPROP training algorithm is adaptive, and does therefore not use the learning_rate. Some other parameters can however be set to change the way the RPROP algorithm works, but it is only recommended for users with insight in how the RPROP training algorithm works. The RPROP training algorithm is described by [Riedmiller and Braun, 1993], but the actual learning algorithm used here is the iRPROP- training algorithm which is described by [Igel and Husken, 2000] which is an variety of the standard RPROP training algorithm.
FANN_TRAIN_QUICKPROP (int)
A more advanced batch training algorithm which achieves good results for many problems. The quickprop training algorithm uses the learning_rate parameter along with other more advanced parameters, but it is only recommended to change these advanced parameters, for users with insight in how the quickprop training algorithm works. The quickprop training algorithm is described by [Fahlman, 1988].
FANN_TRAIN_SARPROP (int)
Even more advance training algorithm. Only for version 2.2
Activation functions
FANN_LINEAR (int)
Linear activation function.
FANN_THRESHOLD (int)
Threshold activation function.
FANN_THRESHOLD_SYMMETRIC (int)
Threshold activation function.
FANN_SIGMOID (int)
Sigmoid activation function.
FANN_SIGMOID_STEPWISE (int)
Stepwise linear approximation to sigmoid.
FANN_SIGMOID_SYMMETRIC (int)
Symmetric sigmoid activation function, aka. tanh.
FANN_SIGMOID_SYMMETRIC_STEPWISE (int)
Stepwise linear approximation to symmetric sigmoid
FANN_GAUSSIAN (int)
Gaussian activation function.
FANN_GAUSSIAN_SYMMETRIC (int)
Symmetric gaussian activation function.
FANN_GAUSSIAN_STEPWISE (int)
Stepwise gaussian activation function.
FANN_ELLIOT (int)
Fast (sigmoid like) activation function defined by David Elliott.
FANN_ELLIOT_SYMMETRIC (int)
Fast (symmetric sigmoid like) activation function defined by David Elliott.
FANN_LINEAR_PIECE (int)
Bounded linear activation function.
FANN_LINEAR_PIECE_SYMMETRIC (int)
Bounded linear activation function.
FANN_SIN_SYMMETRIC (int)
Periodical sinus activation function.
FANN_COS_SYMMETRIC (int)
Periodical cosinus activation function.
FANN_SIN (int)
Periodical sinus activation function.
FANN_COS (int)
Periodical cosinus activation function.
Error function used during training
FANN_ERRORFUNC_LINEAR (int)
Standard linear error function.
FANN_ERRORFUNC_TANH (int)
Tanh error function; usually better but may require a lower learning rate. This error function aggressively targets outputs that differ much from the desired, while not targeting outputs that only differ slightly. Not recommended for cascade or incremental training.
Stop criteria used during training
FANN_STOPFUNC_MSE (int)
Stop criteria is Mean Square Error (MSE) value.
FANN_STOPFUNC_BIT (int)
Stop criteria is number of bits that fail. The number of bits means the number of output neurons which differs more than the bit fail limit (see fann_get_bit_fail_limit, fann_set_bit_fail_limit). The bits are counted in all of the training data, so this number can be higher than the number of training data.
Definition of network types used by fann_get_network_type()
FANN_NETTYPE_LAYER (int)
Each layer only has connections to the next layer.
FANN_NETTYPE_SHORTCUT (int)
Each layer has connections to all following layers
Errors
FANN_E_NO_ERROR (int)
No error.
FANN_E_CANT_OPEN_CONFIG_R (int)
Unable to open configuration file for reading.
FANN_E_CANT_OPEN_CONFIG_W (int)
Unable to open configuration file for writing.
FANN_E_WRONG_CONFIG_VERSION (int)
Wrong version of configuration file.
FANN_E_CANT_READ_CONFIG (int)
Error reading info from configuration file.
FANN_E_CANT_READ_NEURON (int)
Error reading neuron info from configuration file.
FANN_E_CANT_READ_CONNECTIONS (int)
Error reading connections from configuration file.
FANN_E_WRONG_NUM_CONNECTIONS (int)
Number of connections not equal to the number expected.
FANN_E_CANT_OPEN_TD_W (int)
Unable to open train data file for writing.
FANN_E_CANT_OPEN_TD_R (int)
Unable to open train data file for reading.
FANN_E_CANT_READ_TD (int)
Error reading training data from file.
FANN_E_CANT_ALLOCATE_MEM (int)
Unable to allocate memory.
FANN_E_CANT_TRAIN_ACTIVATION (int)
Unable to train with the selected activation function.
FANN_E_CANT_USE_ACTIVATION (int)
Unable to use the selected activation function.
FANN_E_TRAIN_DATA_MISMATCH (int)
Irreconcilable differences between two struct fann_train_data structures.
FANN_E_CANT_USE_TRAIN_ALG (int)
Unable to use the selected training algorithm.
FANN_E_TRAIN_DATA_SUBSET (int)
Trying to take subset which is not within the training set.
FANN_E_INDEX_OUT_OF_BOUND (int)
Index is out of bound.
FANN_E_SCALE_NOT_PRESENT (int)
Scaling parameters not present.
FANN_E_INPUT_NO_MATCH (int)
The number of input neurons in the ann and data do not match
FANN_E_OUTPUT_NO_MATCH (int)
The number of output neurons in the ann and data do not match.


  • ≪ 定義済み定数
  • XOR training ≫
  • PHP Manual
  • FANN
  • 例

例

目次

  • XOR training


XOR training

This example shows how to train data for XOR function

例1 xor.data file

4 2 1
-1 -1
-1
-1 1
1
1 -1
1
1 1
-1

例2 Simple train

<?php
$num_input = 2;
$num_output = 1;
$num_layers = 3;
$num_neurons_hidden = 3;
$desired_error = 0.001;
$max_epochs = 500000;
$epochs_between_reports = 1000;

$ann = fann_create_standard($num_layers, $num_input, $num_neurons_hidden, $num_output);

if ($ann) {
fann_set_activation_function_hidden($ann, FANN_SIGMOID_SYMMETRIC);
fann_set_activation_function_output($ann, FANN_SIGMOID_SYMMETRIC);

$filename = dirname(__FILE__) . "/xor.data";
if (fann_train_on_file($ann, $filename, $max_epochs, $epochs_between_reports, $desired_error))
fann_save($ann, dirname(__FILE__) . "/xor_float.net");

fann_destroy($ann);
}
?>

This example shows how to read and run data for XOR function

例3 Simple test

<?php
$train_file = (dirname(__FILE__) . "/xor_float.net");
if (!is_file($train_file))
die("The file xor_float.net has not been created! Please run simple_train.php to generate it");

$ann = fann_create_from_file($train_file);
if (!$ann)
die("ANN could not be created");

$input = array(-1, 1);
$calc_out = fann_run($ann, $input);
printf("xor test (%f,%f) -> %f\n", $input[0], $input[1], $calc_out[0]);
fann_destroy($ann);
?>


Fann 関数

目次

  • fann_cascadetrain_on_data — Trains on an entire dataset, for a period of time using the Cascade2 training algorithm
  • fann_cascadetrain_on_file — Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm
  • fann_clear_scaling_params — Clears scaling parameters
  • fann_copy — Creates a copy of a fann structure
  • fann_create_from_file — Constructs a backpropagation neural network from a configuration file
  • fann_create_shortcut — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_shortcut_array — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_sparse — Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_sparse_array — Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
  • fann_create_standard — Creates a standard fully connected backpropagation neural network
  • fann_create_standard_array — Creates a standard fully connected backpropagation neural network using an array of layer sizes
  • fann_create_train — Creates an empty training data struct
  • fann_create_train_from_callback — Creates the training data struct from a user supplied function
  • fann_descale_input — Scale data in input vector after get it from ann based on previously calculated parameters
  • fann_descale_output — Scale data in output vector after get it from ann based on previously calculated parameters
  • fann_descale_train — Descale input and output data based on previously calculated parameters
  • fann_destroy — Destroys the entire network and properly freeing all the associated memory
  • fann_destroy_train — Destructs the training data
  • fann_duplicate_train_data — Returns an exact copy of a fann train data
  • fann_get_activation_function — Returns the activation function
  • fann_get_activation_steepness — Returns the activation steepness for supplied neuron and layer number
  • fann_get_bias_array — Get the number of bias in each layer in the network
  • fann_get_bit_fail — The number of fail bits
  • fann_get_bit_fail_limit — Returns the bit fail limit used during training
  • fann_get_cascade_activation_functions — Returns the cascade activation functions
  • fann_get_cascade_activation_functions_count — Returns the number of cascade activation functions
  • fann_get_cascade_activation_steepnesses — Returns the cascade activation steepnesses
  • fann_get_cascade_activation_steepnesses_count — The number of activation steepnesses
  • fann_get_cascade_candidate_change_fraction — Returns the cascade candidate change fraction
  • fann_get_cascade_candidate_limit — Return the candidate limit
  • fann_get_cascade_candidate_stagnation_epochs — Returns the number of cascade candidate stagnation epochs
  • fann_get_cascade_max_cand_epochs — Returns the maximum candidate epochs
  • fann_get_cascade_max_out_epochs — Returns the maximum out epochs
  • fann_get_cascade_min_cand_epochs — Returns the minimum candidate epochs
  • fann_get_cascade_min_out_epochs — Returns the minimum out epochs
  • fann_get_cascade_num_candidate_groups — Returns the number of candidate groups
  • fann_get_cascade_num_candidates — Returns the number of candidates used during training
  • fann_get_cascade_output_change_fraction — Returns the cascade output change fraction
  • fann_get_cascade_output_stagnation_epochs — Returns the number of cascade output stagnation epochs
  • fann_get_cascade_weight_multiplier — Returns the weight multiplier
  • fann_get_connection_array — Get connections in the network
  • fann_get_connection_rate — Get the connection rate used when the network was created
  • fann_get_errno — Returns the last error number
  • fann_get_errstr — Returns the last errstr
  • fann_get_layer_array — Get the number of neurons in each layer in the network
  • fann_get_learning_momentum — Returns the learning momentum
  • fann_get_learning_rate — Returns the learning rate
  • fann_get_MSE — Reads the mean square error from the network
  • fann_get_network_type — Get the type of neural network it was created as
  • fann_get_num_input — Get the number of input neurons
  • fann_get_num_layers — Get the number of layers in the neural network
  • fann_get_num_output — Get the number of output neurons
  • fann_get_quickprop_decay — Returns the decay which is a factor that weights should decrease in each iteration during quickprop training
  • fann_get_quickprop_mu — Returns the mu factor
  • fann_get_rprop_decrease_factor — Returns the increase factor used during RPROP training
  • fann_get_rprop_delta_max — Returns the maximum step-size
  • fann_get_rprop_delta_min — Returns the minimum step-size
  • fann_get_rprop_delta_zero — Returns the initial step-size
  • fann_get_rprop_increase_factor — Returns the increase factor used during RPROP training
  • fann_get_sarprop_step_error_shift — Returns the sarprop step error shift
  • fann_get_sarprop_step_error_threshold_factor — Returns the sarprop step error threshold factor
  • fann_get_sarprop_temperature — Returns the sarprop temperature
  • fann_get_sarprop_weight_decay_shift — Returns the sarprop weight decay shift
  • fann_get_total_connections — Get the total number of connections in the entire network
  • fann_get_total_neurons — Get the total number of neurons in the entire network
  • fann_get_train_error_function — Returns the error function used during training
  • fann_get_train_stop_function — Returns the stop function used during training
  • fann_get_training_algorithm — Returns the training algorithm
  • fann_init_weights — Initialize the weights using Widrow + Nguyen’s algorithm
  • fann_length_train_data — Returns the number of training patterns in the train data
  • fann_merge_train_data — Merges the train data
  • fann_num_input_train_data — Returns the number of inputs in each of the training patterns in the train data
  • fann_num_output_train_data — Returns the number of outputs in each of the training patterns in the train data
  • fann_print_error — Prints the error string
  • fann_randomize_weights — Give each connection a random weight between min_weight and max_weight
  • fann_read_train_from_file — Reads a file that stores training data
  • fann_reset_errno — Resets the last error number
  • fann_reset_errstr — Resets the last error string
  • fann_reset_MSE — Resets the mean square error from the network
  • fann_run — Will run input through the neural network
  • fann_save — Saves the entire network to a configuration file
  • fann_save_train — Save the training structure to a file
  • fann_scale_input — Scale data in input vector before feed it to ann based on previously calculated parameters
  • fann_scale_input_train_data — Scales the inputs in the training data to the specified range
  • fann_scale_output — Scale data in output vector before feed it to ann based on previously calculated parameters
  • fann_scale_output_train_data — Scales the outputs in the training data to the specified range
  • fann_scale_train — Scale input and output data based on previously calculated parameters
  • fann_scale_train_data — Scales the inputs and outputs in the training data to the specified range
  • fann_set_activation_function — Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_hidden — Sets the activation function for all of the hidden layers
  • fann_set_activation_function_layer — Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_output — Sets the activation function for the output layer
  • fann_set_activation_steepness — Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_hidden — Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_layer — Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_output — Sets the steepness of the activation steepness in the output layer
  • fann_set_bit_fail_limit — Set the bit fail limit used during training
  • fann_set_callback — Sets the callback function for use during training
  • fann_set_cascade_activation_functions — Sets the array of cascade candidate activation functions
  • fann_set_cascade_activation_steepnesses — Sets the array of cascade candidate activation steepnesses
  • fann_set_cascade_candidate_change_fraction — Sets the cascade candidate change fraction
  • fann_set_cascade_candidate_limit — Sets the candidate limit
  • fann_set_cascade_candidate_stagnation_epochs — Sets the number of cascade candidate stagnation epochs
  • fann_set_cascade_max_cand_epochs — Sets the max candidate epochs
  • fann_set_cascade_max_out_epochs — Sets the maximum out epochs
  • fann_set_cascade_min_cand_epochs — Sets the min candidate epochs
  • fann_set_cascade_min_out_epochs — Sets the minimum out epochs
  • fann_set_cascade_num_candidate_groups — Sets the number of candidate groups
  • fann_set_cascade_output_change_fraction — Sets the cascade output change fraction
  • fann_set_cascade_output_stagnation_epochs — Sets the number of cascade output stagnation epochs
  • fann_set_cascade_weight_multiplier — Sets the weight multiplier
  • fann_set_error_log — Sets where the errors are logged to
  • fann_set_input_scaling_params — Calculate input scaling parameters for future use based on training data
  • fann_set_learning_momentum — Sets the learning momentum
  • fann_set_learning_rate — Sets the learning rate
  • fann_set_output_scaling_params — Calculate output scaling parameters for future use based on training data
  • fann_set_quickprop_decay — Sets the quickprop decay factor
  • fann_set_quickprop_mu — Sets the quickprop mu factor
  • fann_set_rprop_decrease_factor — Sets the decrease factor used during RPROP training
  • fann_set_rprop_delta_max — Sets the maximum step-size
  • fann_set_rprop_delta_min — Sets the minimum step-size
  • fann_set_rprop_delta_zero — Sets the initial step-size
  • fann_set_rprop_increase_factor — Sets the increase factor used during RPROP training
  • fann_set_sarprop_step_error_shift — Sets the sarprop step error shift
  • fann_set_sarprop_step_error_threshold_factor — Sets the sarprop step error threshold factor
  • fann_set_sarprop_temperature — Sets the sarprop temperature
  • fann_set_sarprop_weight_decay_shift — Sets the sarprop weight decay shift
  • fann_set_scaling_params — Calculate input and output scaling parameters for future use based on training data
  • fann_set_train_error_function — Sets the error function used during training
  • fann_set_train_stop_function — Sets the stop function used during training
  • fann_set_training_algorithm — Sets the training algorithm
  • fann_set_weight — Set a connection in the network
  • fann_set_weight_array — Set connections in the network
  • fann_shuffle_train_data — Shuffles training data, randomizing the order
  • fann_subset_train_data — Returns an copy of a subset of the train data
  • fann_test — Test with a set of inputs, and a set of desired outputs
  • fann_test_data — Test a set of training data and calculates the MSE for the training data
  • fann_train — Train one iteration with a set of inputs, and a set of desired outputs
  • fann_train_epoch — Train one epoch with a set of training data
  • fann_train_on_data — Trains on an entire dataset for a period of time
  • fann_train_on_file — Trains on an entire dataset, which is read from file, for a period of time


Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

  • ≪ Fann 関数
  • fann_cascadetrain_on_file ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

fann_cascadetrain_on_data

(PECL fann >= 1.0.0)

fann_cascadetrain_on_data — Trains on an entire dataset, for a period of time using the Cascade2 training algorithm

説明

fann_cascadetrain_on_data(
resource $ann,
resource $data,
int $max_neurons,
int $neurons_between_reports,
float $desired_error
): bool

The cascade output change fraction is a number between 0 and 1 determining how large a fraction the fann_get_MSE() value should change within fann_get_cascade_output_stagnation_epochs() during training of the output connections, in order for the training not to stagnate. If the training stagnates, the training of the output connections will be ended and new candidates will be prepared.

This training uses the parameters set using the fann_set_cascade_..., but it also uses another training algorithm as it's internal training algorithm. This algorithm can be set to either FANN_TRAIN_RPROP or FANN_TRAIN_QUICKPROP by fann_set_training_algorithm(), and the parameters set for these training algorithms will also affect the cascade training.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

max_neurons

The maximum number of neurons to be added to neural network.

neurons_between_reports

The number of neurons between printing a status report. A value of zero means no reports should be printed.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on which stop function is chosen by fann_set_train_stop_function()

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_cascadetrain_on_file() - Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm


Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

  • ≪ fann_cascadetrain_on_data
  • fann_clear_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

fann_cascadetrain_on_file

(PECL fann >= 1.0.0)

fann_cascadetrain_on_file — Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm

説明

fann_cascadetrain_on_file(
resource $ann,
string $filename,
int $max_neurons,
int $neurons_between_reports,
float $desired_error
): bool

Does the same as fann_cascadetrain_on_data(), but reads the training data directly from a file.

パラメータ

ann

ニューラルネットワークリソース。

filename

A file containing the data for training.

max_neurons

The maximum number of neurons to be added to neural network

neurons_between_reports

The number of neurons between printing a status report. A value of zero means no reports should be printed.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on which stop function is chosen by fann_set_train_stop_function().

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_cascadetrain_on_data() - Trains on an entire dataset, for a period of time using the Cascade2 training algorithm


Clears scaling parameters

  • ≪ fann_cascadetrain_on_file
  • fann_copy ≫
  • PHP Manual
  • Fann 関数
  • Clears scaling parameters

fann_clear_scaling_params

(PECL fann >= 1.0.0)

fann_clear_scaling_params — Clears scaling parameters

説明

fann_clear_scaling_params(resource $ann): bool

Clears scaling parameters.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。


Creates a copy of a fann structure

  • ≪ fann_clear_scaling_params
  • fann_create_from_file ≫
  • PHP Manual
  • Fann 関数
  • Creates a copy of a fann structure

fann_copy

(PECL fann >= 1.0.0)

fann_copy — Creates a copy of a fann structure

説明

fann_copy(resource $ann): resource

Creates a copy of a fann structure.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Returns a copy of neural network resource on success, or false on error

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_test() - Test with a set of inputs, and a set of desired outputs


Constructs a backpropagation neural network from a configuration file

  • ≪ fann_copy
  • fann_create_shortcut ≫
  • PHP Manual
  • Fann 関数
  • Constructs a backpropagation neural network from a configuration file

fann_create_from_file

(PECL fann >= 1.0.0)

fann_create_from_file — Constructs a backpropagation neural network from a configuration file

説明

fann_create_from_file(string $configuration_file): resource

Constructs a backpropagation neural network from a configuration file, which have been saved by fann_save().

パラメータ

configuration_file

The configuration file path.

戻り値

成功した場合にニューラルネットワークリソース、エラー時に false を返します。

参考

  • fann_save() - Saves the entire network to a configuration file


Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

  • ≪ fann_create_from_file
  • fann_create_shortcut_array ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

fann_create_shortcut

(PECL fann >= 1.0.0)

fann_create_shortcut — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

説明

fann_create_shortcut(
int $num_layers,
int $num_neurons1,
int $num_neurons2,
int ...$num_neuronsN
): resource

Creates a standard backpropagation neural network, which is not fully connected and which also has shortcut connections.

Shortcut connections are connections that skip layers. A fully connected network with shortcut connections, is a network where all neurons are connected to all neurons in later layers. Including direct connections from the input layer to the output layer.

パラメータ

num_layers

The total number of layers including the input and the output layer.

num_neurons1

Number of neurons in the first layer.

num_neurons2

Number of neurons in the second layer.

num_neuronsN

Number of neurons in other layers.

戻り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_shortcut_array() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network


Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

  • ≪ fann_create_shortcut
  • fann_create_sparse ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

fann_create_shortcut_array

(PECL fann >= 1.0.0)

fann_create_shortcut_array — Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections

説明

fann_create_shortcut_array(int $num_layers, array $layers): resource

Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections using an array of layers sizes.

パラメータ

num_layers

The total number of layers including the input and the output layer.

layers

An array of layers sizes.

戻り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network


Creates a standard backpropagation neural network, which is not fully connected

  • ≪ fann_create_shortcut_array
  • fann_create_sparse_array ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network, which is not fully connected

fann_create_sparse

(PECL fann >= 1.0.0)

fann_create_sparse — Creates a standard backpropagation neural network, which is not fully connected

説明

fann_create_sparse(
float $connection_rate,
int $num_layers,
int $num_neurons1,
int $num_neurons2,
int ...$num_neuronsN
): resource

Creates a standard backpropagation neural network, which is not fully connected.

パラメータ

connection_rate

The connection rate controls how many connections there will be in the network. If the connection rate is set to 1, the network will be fully connected, but if it is set to 0.5 only half of the connections will be set. A connection rate of 1 will yield the same result as fann_create_standard().

num_layers

The total number of layers including the input and the output layer.

num_neurons1

Number of neurons in the first layer.

num_neurons2

Number of neurons in the second layer.

num_neuronsN

Number of neurons in other layers.

戻り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_sparse_array() - Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections


Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes

  • ≪ fann_create_sparse
  • fann_create_standard ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes

fann_create_sparse_array

(PECL fann >= 1.0.0)

fann_create_sparse_array — Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes

説明

fann_create_sparse_array(float $connection_rate, int $num_layers, array $layers): resource

Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes.

パラメータ

connection_rate

The connection rate controls how many connections there will be in the network. If the connection rate is set to 1, the network will be fully connected, but if it is set to 0.5 only half of the connections will be set. A connection rate of 1 will yield the same result as fann_create_standard().

num_layers

The total number of layers including the input and the output layer.

layers

An array of layer sizes.

戻り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_standard() - Creates a standard fully connected backpropagation neural network
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections


Creates a standard fully connected backpropagation neural network

  • ≪ fann_create_sparse_array
  • fann_create_standard_array ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard fully connected backpropagation neural network

fann_create_standard

(PECL fann >= 1.0.0)

fann_create_standard — Creates a standard fully connected backpropagation neural network

説明

fann_create_standard(
int $num_layers,
int $num_neurons1,
int $num_neurons2,
int ...$num_neuronsN
): resource

Creates a standard fully connected backpropagation neural network.

There will be a bias neuron in each layer (except the output layer), and this bias neuron will be connected to all neurons in the next layer. When running the network, the bias nodes always emits 1.

To destroy a neural network use the fann_destroy() function.

パラメータ

num_layers

The total number of layers including the input and the output layer.

num_neurons1

Number of neurons in the first layer.

num_neurons2

Number of neurons in the second layer.

num_neuronsN

Number of neurons in other layers.

戻り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_standard_array() - Creates a standard fully connected backpropagation neural network using an array of layer sizes
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections


Creates a standard fully connected backpropagation neural network using an array of layer sizes

  • ≪ fann_create_standard
  • fann_create_train ≫
  • PHP Manual
  • Fann 関数
  • Creates a standard fully connected backpropagation neural network using an array of layer sizes

fann_create_standard_array

(PECL fann >= 1.0.0)

fann_create_standard_array — Creates a standard fully connected backpropagation neural network using an array of layer sizes

説明

fann_create_standard_array(int $num_layers, array $layers): resource

Creates a standard fully connected backpropagation neural network.

There will be a bias neuron in each layer (except the output layer), and this bias neuron will be connected to all neurons in the next layer. When running the network, the bias nodes always emits 1.

To destroy a neural network use the fann_destroy() function.

パラメータ

num_layers

The total number of layers including the input and the output layer.

layers

An array of layer sizes.

戻り値

Returns a neural network resource on success, or false on error.

参考

  • fann_create_standard() - Creates a standard fully connected backpropagation neural network
  • fann_create_sparse() - Creates a standard backpropagation neural network, which is not fully connected
  • fann_create_shortcut() - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections


Creates an empty training data struct

  • ≪ fann_create_standard_array
  • fann_create_train_from_callback ≫
  • PHP Manual
  • Fann 関数
  • Creates an empty training data struct

fann_create_train

(PECL fann >= 1.0.0)

fann_create_train — Creates an empty training data struct

説明

fann_create_train(int $num_data, int $num_input, int $num_output): resource

Creates an empty training data struct.

パラメータ

num_data

The number of training data

num_input

The number of inputs per training data

num_output

The number of ouputs per training data

戻り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_read_train_from_file() - Reads a file that stores training data
  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_destroy_train() - Destructs the training data
  • fann_save_train() - Save the training structure to a file


Creates the training data struct from a user supplied function

  • ≪ fann_create_train
  • fann_descale_input ≫
  • PHP Manual
  • Fann 関数
  • Creates the training data struct from a user supplied function

fann_create_train_from_callback

(PECL fann >= 1.0.0)

fann_create_train_from_callback — Creates the training data struct from a user supplied function

説明

fann_create_train_from_callback(
int $num_data,
int $num_input,
int $num_output,
callable $user_function
): resource

Creates the training data struct from a user supplied function. As the training data are numerable (data 1, data 2...), the user must write a function that receives the number of the training data set (input, output) and returns the set.

パラメータ

num_data

The number of training data

num_input

The number of inputs per training data

num_output

The number of ouputs per training data

user_function

The user supplied function with following parameters:

  • num - The number of the training data set
  • num_input - The number of inputs per training data
  • num_output - The number of ouputs per training data

The function should return an associative array with keys input and output and two array values of input and output.

戻り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

例

例1 fann_create_train_from_callback() example

<?php
function create_train_callback($num_data, $num_input, $num_output) {
return array(
"input" => array_fill(0, $num_input, 1),
"output" => array_fill(0, $num_output, 1),
);
}

$num_data = 3;
$num_input = 2;
$num_output = 1;
$train_data = fann_create_train_from_callback($num_data, $num_input, $num_output, "create_train_callback");
if ($train_data) {
// Do something with $train_data
}
?>

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_read_train_from_file() - Reads a file that stores training data
  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_destroy_train() - Destructs the training data
  • fann_save_train() - Save the training structure to a file


Scale data in input vector after get it from ann based on previously calculated parameters

  • ≪ fann_create_train_from_callback
  • fann_descale_output ≫
  • PHP Manual
  • Fann 関数
  • Scale data in input vector after get it from ann based on previously calculated parameters

fann_descale_input

(PECL fann >= 1.0.0)

fann_descale_input — Scale data in input vector after get it from ann based on previously calculated parameters

説明

fann_descale_input(resource $ann, array $input_vector): bool

Scale data in input vector after get it from ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

input_vector

Input vector that will be descaled

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_input() - Scale data in input vector before feed it to ann based on previously calculated parameters
  • fann_descale_output() - Scale data in output vector after get it from ann based on previously calculated parameters


Scale data in output vector after get it from ann based on previously calculated parameters

  • ≪ fann_descale_input
  • fann_descale_train ≫
  • PHP Manual
  • Fann 関数
  • Scale data in output vector after get it from ann based on previously calculated parameters

fann_descale_output

(PECL fann >= 1.0.0)

fann_descale_output — Scale data in output vector after get it from ann based on previously calculated parameters

説明

fann_descale_output(resource $ann, array $output_vector): bool

Scale data in output vector after get it from ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

output_vector

Output vector that will be descaled

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_output() - Scale data in output vector before feed it to ann based on previously calculated parameters
  • fann_descale_input() - Scale data in input vector after get it from ann based on previously calculated parameters


Descale input and output data based on previously calculated parameters

  • ≪ fann_descale_output
  • fann_destroy ≫
  • PHP Manual
  • Fann 関数
  • Descale input and output data based on previously calculated parameters

fann_descale_train

(PECL fann >= 1.0.0)

fann_descale_train — Descale input and output data based on previously calculated parameters

説明

fann_descale_train(resource $ann, resource $train_data): bool

Descale input and output data based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_train() - Scale input and output data based on previously calculated parameters
  • fann_set_scaling_params() - Calculate input and output scaling parameters for future use based on training data


Destroys the entire network and properly freeing all the associated memory

  • ≪ fann_descale_train
  • fann_destroy_train ≫
  • PHP Manual
  • Fann 関数
  • Destroys the entire network and properly freeing all the associated memory

fann_destroy

(PECL fann >= 1.0.0)

fann_destroy — Destroys the entire network and properly freeing all the associated memory

説明

fann_destroy(resource $ann): bool

Destroys the entire network and properly freeing all the associated memory.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。


Destructs the training data

  • ≪ fann_destroy
  • fann_duplicate_train_data ≫
  • PHP Manual
  • Fann 関数
  • Destructs the training data

fann_destroy_train

(PECL fann >= 1.0.0)

fann_destroy_train — Destructs the training data

説明

fann_destroy_train(resource $train_data): bool

Destructs the training data

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。


Returns an exact copy of a fann train data

  • ≪ fann_destroy_train
  • fann_get_activation_function ≫
  • PHP Manual
  • Fann 関数
  • Returns an exact copy of a fann train data

fann_duplicate_train_data

(PECL fann >= 1.0.0)

fann_duplicate_train_data — Returns an exact copy of a fann train data

説明

fann_duplicate_train_data(resource $data): resource

Returns an exact copy of a fann train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

戻り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。


Returns the activation function

  • ≪ fann_duplicate_train_data
  • fann_get_activation_steepness ≫
  • PHP Manual
  • Fann 関数
  • Returns the activation function

fann_get_activation_function

(PECL fann >= 1.0.0)

fann_get_activation_function — Returns the activation function

説明

fann_get_activation_function(resource $ann, int $layer, int $neuron): int

Get the activation function for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to get activation functions for the neurons in the input layer.

The return value is one of the activation functions constants.

パラメータ

ann

ニューラルネットワークリソース。

layer

Layer number.

neuron

Neuron number.

戻り値

Learning functions constant or -1 if the neuron is not defined in the neural network, or false on error.

参考

  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer


Returns the activation steepness for supplied neuron and layer number

  • ≪ fann_get_activation_function
  • fann_get_bias_array ≫
  • PHP Manual
  • Fann 関数
  • Returns the activation steepness for supplied neuron and layer number

fann_get_activation_steepness

(PECL fann >= 1.0.0)

fann_get_activation_steepness — Returns the activation steepness for supplied neuron and layer number

説明

fann_get_activation_steepness(resource $ann, int $layer, int $neuron): float

Get the activation steepness for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to get activation steepness for the neurons in the input layer.

The steepness of an activation function says something about how fast the activation function goes from the minimum to the maximum. A high value for the activation function will also give a more aggressive training.

When training neural networks where the output values should be at the extremes (usually 0 and 1, depending on the activation function), a steep activation function can be used (e.g. 1.0).

The default activation steepness is 0.5.

パラメータ

ann

ニューラルネットワークリソース。

layer

Layer number

neuron

Neuron number

戻り値

The activation steepness for the neuron or -1 if the neuron is not defined in the neural network, or false on error.

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number


Get the number of bias in each layer in the network

  • ≪ fann_get_activation_steepness
  • fann_get_bit_fail ≫
  • PHP Manual
  • Fann 関数
  • Get the number of bias in each layer in the network

fann_get_bias_array

(PECL fann >= 1.0.0)

fann_get_bias_array — Get the number of bias in each layer in the network

説明

fann_get_bias_array(resource $ann): array

Get the number of bias in each layer in the network.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

An array of numbers of bias in each layer


The number of fail bits

  • ≪ fann_get_bias_array
  • fann_get_bit_fail_limit ≫
  • PHP Manual
  • Fann 関数
  • The number of fail bits

fann_get_bit_fail

(PECL fann >= 1.0.0)

fann_get_bit_fail — The number of fail bits

説明

fann_get_bit_fail(resource $ann): int

The number of fail bits; means the number of output neurons which differ more than the bit fail limit (see fann_get_bit_fail_limit(), fann_set_bit_fail_limit()). The bits are counted in all of the training data, so this number can be higher than the number of training data.

This value is reset by fann_reset_MSE() and updated by all the same functions which also updates the MSE value (e.g. fann_test_data(), fann_train_epoch())

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of bits fail, or false on error.

参考

  • fann_get_MSE() - Reads the mean square error from the network
  • fann_reset_MSE() - Resets the mean square error from the network
  • fann_test_data() - Test a set of training data and calculates the MSE for the training data
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail_limit() - Returns the bit fail limit used during training
  • fann_set_bit_fail_limit() - Set the bit fail limit used during training


Returns the bit fail limit used during training

  • ≪ fann_get_bit_fail
  • fann_get_cascade_activation_functions ≫
  • PHP Manual
  • Fann 関数
  • Returns the bit fail limit used during training

fann_get_bit_fail_limit

(PECL fann >= 1.0.0)

fann_get_bit_fail_limit — Returns the bit fail limit used during training

説明

fann_get_bit_fail_limit(resource $ann): float

Returns the bit fail limit used during training.

The bit fail limit is used during training where the stop function is set to FANN_STOPFUNC_BIT.

The limit is the maximum accepted difference between the desired output and the actual output during training. Each output that diverges more than this limit is counted as an error bit. This difference is divided by two when dealing with symmetric activation functions, so that symmetric and not symmetric activation functions can use the same limit.

The default bit fail limit is 0.35.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The bit fail limit, or false on error.

参考

  • fann_set_bit_fail_limit() - Set the bit fail limit used during training


Returns the cascade activation functions

  • ≪ fann_get_bit_fail_limit
  • fann_get_cascade_activation_functions_count ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade activation functions

fann_get_cascade_activation_functions

(PECL fann >= 1.0.0)

fann_get_cascade_activation_functions — Returns the cascade activation functions

説明

fann_get_cascade_activation_functions(resource $ann): array

The cascade activation functions array is an array of the different activation functions used by the candidates

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

The default activation functions are FANN_SIGMOID, FANN_SIGMOID_SYMMETRIC, FANN_GAUSSIAN, FANN_GAUSSIAN_SYMMETRIC, FANN_ELLIOT, FANN_ELLIOT_SYMMETRIC.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The cascade activation functions, or false on error.

参考

  • fann_get_cascade_activation_functions_count() - Returns the number of cascade activation functions
  • fann_set_cascade_activation_functions() - Sets the array of cascade candidate activation functions


Returns the number of cascade activation functions

  • ≪ fann_get_cascade_activation_functions
  • fann_get_cascade_activation_steepnesses ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of cascade activation functions

fann_get_cascade_activation_functions_count

(PECL fann >= 1.0.0)

fann_get_cascade_activation_functions_count — Returns the number of cascade activation functions

説明

fann_get_cascade_activation_functions_count(resource $ann): int

The number of activation functions in the fann_get_cascade_activation_functions() array.

The default number of activation functions is 6.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of cascade activation functions, or false on error.

参考

  • fann_get_cascade_activation_functions() - Returns the cascade activation functions
  • fann_set_cascade_activation_functions() - Sets the array of cascade candidate activation functions


Returns the cascade activation steepnesses

  • ≪ fann_get_cascade_activation_functions_count
  • fann_get_cascade_activation_steepnesses_count ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade activation steepnesses

fann_get_cascade_activation_steepnesses

(PECL fann >= 1.0.0)

fann_get_cascade_activation_steepnesses — Returns the cascade activation steepnesses

説明

fann_get_cascade_activation_steepnesses(resource $ann): array

The cascade activation steepnesses array is an array of the different activation functions used by the candidates.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

The default activation steepnesses are {0.25, 0.50, 0.75, 1.00}.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The cascade activation steepnesses, or false on error.

参考

  • fann_get_cascade_activation_steepnesses_count() - The number of activation steepnesses
  • fann_set_cascade_activation_steepnesses() - Sets the array of cascade candidate activation steepnesses


The number of activation steepnesses

  • ≪ fann_get_cascade_activation_steepnesses
  • fann_get_cascade_candidate_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • The number of activation steepnesses

fann_get_cascade_activation_steepnesses_count

(PECL fann >= 1.0.0)

fann_get_cascade_activation_steepnesses_count — The number of activation steepnesses

説明

fann_get_cascade_activation_steepnesses_count(resource $ann): int

The number of activation steepnesses in the fann_get_cascade_activation_functions() array.

The default number of activation steepnesses is 4.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of activation steepnesses, or false on error.

参考

  • fann_get_cascade_activation_steepnesses() - Returns the cascade activation steepnesses
  • fann_set_cascade_activation_functions() - Sets the array of cascade candidate activation functions


Returns the cascade candidate change fraction

  • ≪ fann_get_cascade_activation_steepnesses_count
  • fann_get_cascade_candidate_limit ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade candidate change fraction

fann_get_cascade_candidate_change_fraction

(PECL fann >= 1.0.0)

fann_get_cascade_candidate_change_fraction — Returns the cascade candidate change fraction

説明

fann_get_cascade_candidate_change_fraction(resource $ann): float

The cascade candidate change fraction is a number between 0 and 1 determining how large a fraction the fann_get_MSE() value should change within fann_get_cascade_candidate_stagnation_epochs() during training of the candidate neurons, in order for the training not to stagnate. If the training stagnates, the training of the candidate neurons will be ended and the best candidate will be selected.

It means that if the MSE does not change by a fraction of fann_get_cascade_candidate_change_fraction() during a period of fann_get_cascade_candidate_stagnation_epochs(), the training of the candidate neurons is stopped because the training has stagnated.

If the cascade candidate change fraction is low, the candidate neurons will be trained more and if the fraction is high they will be trained less.

The default cascade candidate change fraction is 0.01, which is equalent to a 1% change in MSE.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The cascade candidate change fraction, or false on error.

参考

  • fann_set_cascade_candidate_change_fraction() - Sets the cascade candidate change fraction
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_get_cascade_candidate_stagnation_epochs() - Returns the number of cascade candidate stagnation epochs


Return the candidate limit

  • ≪ fann_get_cascade_candidate_change_fraction
  • fann_get_cascade_candidate_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Return the candidate limit

fann_get_cascade_candidate_limit

(PECL fann >= 1.0.0)

fann_get_cascade_candidate_limit — Return the candidate limit

説明

fann_get_cascade_candidate_limit(resource $ann): float

The candidate limit is a limit for how much the candidate neuron may be trained. The limit is a limit on the proportion between the MSE and candidate score.

Set this to a lower value to avoid overfitting and to a higher if overfitting is not a problem.

The default candidate limit is 1000.0.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The candidate limit, or false on error.

参考

  • fann_set_cascade_candidate_limit() - Sets the candidate limit


Returns the number of cascade candidate stagnation epochs

  • ≪ fann_get_cascade_candidate_limit
  • fann_get_cascade_max_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of cascade candidate stagnation epochs

fann_get_cascade_candidate_stagnation_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_candidate_stagnation_epochs — Returns the number of cascade candidate stagnation epochs

説明

fann_get_cascade_candidate_stagnation_epochs(resource $ann): int

The number of cascade candidate stagnation epochs determines the number of epochs training is allowed to continue without changing the MSE by a fraction of fann_get_cascade_candidate_change_fraction().

See more info about this parameter in fann_get_cascade_candidate_change_fraction().

The default number of cascade candidate stagnation epochs is 12.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of cascade candidate stagnation epochs, or false on error.

参考

  • fann_set_cascade_candidate_stagnation_epochs() - Sets the number of cascade candidate stagnation epochs
  • fann_get_cascade_candidate_change_fraction() - Returns the cascade candidate change fraction


Returns the maximum candidate epochs

  • ≪ fann_get_cascade_candidate_stagnation_epochs
  • fann_get_cascade_max_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the maximum candidate epochs

fann_get_cascade_max_cand_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_max_cand_epochs — Returns the maximum candidate epochs

説明

fann_get_cascade_max_cand_epochs(resource $ann): int

The maximum candidate epochs determines the maximum number of epochs the input connections to the candidates may be trained before adding a new candidate neuron.

The default max candidate epochs is 150.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The maximum candidate epochs, or false on error.

参考

  • fann_set_cascade_max_cand_epochs() - Sets the max candidate epochs


Returns the maximum out epochs

  • ≪ fann_get_cascade_max_cand_epochs
  • fann_get_cascade_min_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the maximum out epochs

fann_get_cascade_max_out_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_max_out_epochs — Returns the maximum out epochs

説明

fann_get_cascade_max_out_epochs(resource $ann): int

The maximum out epochs determines the maximum number of epochs the output connections may be trained after adding a new candidate neuron.

The default max out epochs is 150.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The maximum out epochs, or false on error.

参考

  • fann_set_cascade_max_out_epochs() - Sets the maximum out epochs


Returns the minimum candidate epochs

  • ≪ fann_get_cascade_max_out_epochs
  • fann_get_cascade_min_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the minimum candidate epochs

fann_get_cascade_min_cand_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_min_cand_epochs — Returns the minimum candidate epochs

説明

fann_get_cascade_min_cand_epochs(resource $ann): int

The minimum candidate epochs determines the minimum number of epochs the input connections to the candidates may be trained before adding a new candidate neuron.

The default min candidate epochs is 50.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The minimum candidate epochs, or false on error.

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_cascade_min_cand_epochs() - Sets the min candidate epochs


Returns the minimum out epochs

  • ≪ fann_get_cascade_min_cand_epochs
  • fann_get_cascade_num_candidate_groups ≫
  • PHP Manual
  • Fann 関数
  • Returns the minimum out epochs

fann_get_cascade_min_out_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_min_out_epochs — Returns the minimum out epochs

説明

fann_get_cascade_min_out_epochs(resource $ann): int

The minimum out epochs determines the minimum number of epochs the output connections must be trained after adding a new candidate neuron.

The default min out epochs is 50.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The minimum out epochs, or false on error.

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_cascade_min_out_epochs() - Sets the minimum out epochs


Returns the number of candidate groups

  • ≪ fann_get_cascade_min_out_epochs
  • fann_get_cascade_num_candidates ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of candidate groups

fann_get_cascade_num_candidate_groups

(PECL fann >= 1.0.0)

fann_get_cascade_num_candidate_groups — Returns the number of candidate groups

説明

fann_get_cascade_num_candidate_groups(resource $ann): int

The number of candidate groups is the number of groups of identical candidates which will be used during training.

This number can be used to have more candidates without having to define new parameters for the candidates.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this parameter.

The default number of candidate groups is 2.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of candidate groups, or false on error.

参考

  • fann_set_cascade_num_candidate_groups() - Sets the number of candidate groups


Returns the number of candidates used during training

  • ≪ fann_get_cascade_num_candidate_groups
  • fann_get_cascade_output_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of candidates used during training

fann_get_cascade_num_candidates

(PECL fann >= 1.0.0)

fann_get_cascade_num_candidates — Returns the number of candidates used during training

説明

fann_get_cascade_num_candidates(resource $ann): int

The number of candidates used during training (calculated by multiplying
fann_get_cascade_activation_functions_count(),
fann_get_cascade_activation_steepnesses_count() and
fann_get_cascade_num_candidate_groups()).

The actual candidates is defined by the fann_get_cascade_activation_functions() and fann_get_cascade_activation_steepnesses() arrays. These arrays define the activation functions and activation steepnesses used for the candidate neurons. If there are 2 activation functions in the activation function array and 3 steepnesses in the steepness array, then there will be 2x3=6 different candidates which will be trained. These 6 different candidates can be copied into several candidate groups, where the only difference between these groups is the initial weights. If the number of groups is set to 2, then the number of candidate neurons will be 2x3x2=12. The number of candidate groups is defined by fann_set_cascade_num_candidate_groups().

The default number of candidates is 6x4x2 = 48

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of candidates used during training, or false on error.

参考

  • fann_get_cascade_activation_functions() - Returns the cascade activation functions
  • fann_get_cascade_activation_functions_count() - Returns the number of cascade activation functions
  • fann_get_cascade_activation_steepnesses() - Returns the cascade activation steepnesses
  • fann_get_cascade_activation_steepnesses_count() - The number of activation steepnesses
  • fann_get_cascade_num_candidate_groups() - Returns the number of candidate groups


Returns the cascade output change fraction

  • ≪ fann_get_cascade_num_candidates
  • fann_get_cascade_output_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Returns the cascade output change fraction

fann_get_cascade_output_change_fraction

(PECL fann >= 1.0.0)

fann_get_cascade_output_change_fraction — Returns the cascade output change fraction

説明

fann_get_cascade_output_change_fraction(resource $ann): float

The cascade output change fraction is a number between 0 and 1 determining how large a fraction of the fann_get_MSE() value should change within fann_get_cascade_output_stagnation_epochs() during training of the output connections, in order for the training not to stagnate. If the training stagnates, the training of the output connections will be ended and new candidates will be prepared.

It means that if the MSE does not change by a fraction of fann_get_cascade_output_change_fraction() during a period of fann_get_cascade_output_stagnation_epochs(), the training of the output connections is stopped because the training has stagnated.

If the cascade output change fraction is low, the output connections will be trained more and if the fraction is high, they will be trained less.

The default cascade output change fraction is 0.01, which is equalent to a 1% change in MSE.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The cascade output change fraction, or false on error.

参考

  • fann_set_cascade_output_change_fraction() - Sets the cascade output change fraction
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_get_cascade_output_stagnation_epochs() - Returns the number of cascade output stagnation epochs


Returns the number of cascade output stagnation epochs

  • ≪ fann_get_cascade_output_change_fraction
  • fann_get_cascade_weight_multiplier ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of cascade output stagnation epochs

fann_get_cascade_output_stagnation_epochs

(PECL fann >= 1.0.0)

fann_get_cascade_output_stagnation_epochs — Returns the number of cascade output stagnation epochs

説明

fann_get_cascade_output_stagnation_epochs(resource $ann): int

The number of cascade output stagnation epochs determines the number of epochs training is allowed to continue without changing the MSE by a fraction of fann_get_cascade_output_change_fraction().

See more info about this parameter in fann_get_cascade_output_change_fraction().

The default number of cascade output stagnation epochs is 12.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of cascade output stagnation epochs, or false on error.

参考

  • fann_set_cascade_output_stagnation_epochs() - Sets the number of cascade output stagnation epochs
  • fann_get_cascade_output_change_fraction() - Returns the cascade output change fraction


Returns the weight multiplier

  • ≪ fann_get_cascade_output_stagnation_epochs
  • fann_get_connection_array ≫
  • PHP Manual
  • Fann 関数
  • Returns the weight multiplier

fann_get_cascade_weight_multiplier

(PECL fann >= 1.0.0)

fann_get_cascade_weight_multiplier — Returns the weight multiplier

説明

fann_get_cascade_weight_multiplier(resource $ann): float

The weight multiplier is a parameter which is used to multiply the weights from the candidate neuron before adding the neuron to the neural network. This parameter is usually between 0 and 1, and is used to make the training a bit less aggressive.

The default weight multiplier is 0.4.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The weight multiplier, or false on error.

参考

  • fann_set_cascade_weight_multiplier() - Sets the weight multiplier


Get connections in the network

  • ≪ fann_get_cascade_weight_multiplier
  • fann_get_connection_rate ≫
  • PHP Manual
  • Fann 関数
  • Get connections in the network

fann_get_connection_array

(PECL fann >= 1.0.0)

fann_get_connection_array — Get connections in the network

説明

fann_get_connection_array(resource $ann): array

Get connections in the network.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

An array of connections in the network


Get the connection rate used when the network was created

  • ≪ fann_get_connection_array
  • fann_get_errno ≫
  • PHP Manual
  • Fann 関数
  • Get the connection rate used when the network was created

fann_get_connection_rate

(PECL fann >= 1.0.0)

fann_get_connection_rate — Get the connection rate used when the network was created

説明

fann_get_connection_rate(resource $ann): float

Get the connection rate used when the network was created.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The connection rate used when the network was created, or false on error.


Returns the last error number

  • ≪ fann_get_connection_rate
  • fann_get_errstr ≫
  • PHP Manual
  • Fann 関数
  • Returns the last error number

fann_get_errno

(PECL fann >= 1.0.0)

fann_get_errno — Returns the last error number

説明

fann_get_errno(resource $errdat): int

Returns the last error number.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

戻り値

The error number, or false on error.

参考

  • fann_reset_errno() - Resets the last error number
  • fann_get_errstr() - Returns the last errstr


Returns the last errstr

  • ≪ fann_get_errno
  • fann_get_layer_array ≫
  • PHP Manual
  • Fann 関数
  • Returns the last errstr

fann_get_errstr

(PECL fann >= 1.0.0)

fann_get_errstr — Returns the last errstr

説明

fann_get_errstr(resource $errdat): string

Returns the last errstr.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

戻り値

The last error string, or false on error.

参考

  • fann_reset_errstr() - Resets the last error string
  • fann_get_errno() - Returns the last error number


Get the number of neurons in each layer in the network

  • ≪ fann_get_errstr
  • fann_get_learning_momentum ≫
  • PHP Manual
  • Fann 関数
  • Get the number of neurons in each layer in the network

fann_get_layer_array

(PECL fann >= 1.0.0)

fann_get_layer_array — Get the number of neurons in each layer in the network

説明

fann_get_layer_array(resource $ann): array

Get the number of neurons in each layer in the neural network.

Bias is not included so the layers match the fann_create functions.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

An array of numbers of neurons in each leayer


Returns the learning momentum

  • ≪ fann_get_layer_array
  • fann_get_learning_rate ≫
  • PHP Manual
  • Fann 関数
  • Returns the learning momentum

fann_get_learning_momentum

(PECL fann >= 1.0.0)

fann_get_learning_momentum — Returns the learning momentum

説明

fann_get_learning_momentum(resource $ann): float

The learning momentum can be used to speed up FANN_TRAIN_INCREMENTAL training. A too high momentum will however not benefit training. Setting momentum to 0 will be the same as not using the momentum parameter. The recommended value of this parameter is between 0.0 and 1.0.

The default momentum is 0.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。

The learning momentum, or false on error.

参考

  • fann_set_learning_momentum() - Sets the learning momentum
  • fann_set_training_algorithm() - Sets the training algorithm


Returns the learning rate

  • ≪ fann_get_learning_momentum
  • fann_get_MSE ≫
  • PHP Manual
  • Fann 関数
  • Returns the learning rate

fann_get_learning_rate

(PECL fann >= 1.0.0)

fann_get_learning_rate — Returns the learning rate

説明

fann_get_learning_rate(resource $ann): float

The learning rate is used to determine how aggressive training should be for some of the training algorithms (FANN_TRAIN_INCREMENTAL, FANN_TRAIN_BATCH, FANN_TRAIN_QUICKPROP). Do however note that it is not used in FANN_TRAIN_RPROP.

The default learning rate is 0.7.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The learning rate, or false on error.

参考

  • fann_set_learning_rate() - Sets the learning rate
  • fann_set_training_algorithm() - Sets the training algorithm


Reads the mean square error from the network

  • ≪ fann_get_learning_rate
  • fann_get_network_type ≫
  • PHP Manual
  • Fann 関数
  • Reads the mean square error from the network

fann_get_MSE

(PECL fann >= 1.0.0)

fann_get_MSE — Reads the mean square error from the network

説明

fann_get_MSE(resource $ann): float

Reads the mean square error from the network.

Reads the mean square error from the network. This value is calculated during training or testing and can therefore sometimes be a bit off if the weights have been changed since the last calculation of the value.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The mean square error, or false on error.

参考

  • fann_test_data() - Test a set of training data and calculates the MSE for the training data


Get the type of neural network it was created as

  • ≪ fann_get_MSE
  • fann_get_num_input ≫
  • PHP Manual
  • Fann 関数
  • Get the type of neural network it was created as

fann_get_network_type

(PECL fann >= 1.0.0)

fann_get_network_type — Get the type of neural network it was created as

説明

fann_get_network_type(resource $ann): int

Get the type of neural network it was created as.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Network type constant, or false on error.


Get the number of input neurons

  • ≪ fann_get_network_type
  • fann_get_num_layers ≫
  • PHP Manual
  • Fann 関数
  • Get the number of input neurons

fann_get_num_input

(PECL fann >= 1.0.0)

fann_get_num_input — Get the number of input neurons

説明

fann_get_num_input(resource $ann): int

Get the number of input neurons.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Number of input neurons, or false on error


Get the number of layers in the neural network

  • ≪ fann_get_num_input
  • fann_get_num_output ≫
  • PHP Manual
  • Fann 関数
  • Get the number of layers in the neural network

fann_get_num_layers

(PECL fann >= 1.0.0)

fann_get_num_layers — Get the number of layers in the neural network

説明

fann_get_num_layers(resource $ann): int

Get the number of layers in the neural network.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The number of leayers in the neural network, or false on error.


Get the number of output neurons

  • ≪ fann_get_num_layers
  • fann_get_quickprop_decay ≫
  • PHP Manual
  • Fann 関数
  • Get the number of output neurons

fann_get_num_output

(PECL fann >= 1.0.0)

fann_get_num_output — Get the number of output neurons

説明

fann_get_num_output(resource $ann): int

Get the number of output neurons.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Number of output neurons, or false on error


Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

  • ≪ fann_get_num_output
  • fann_get_quickprop_mu ≫
  • PHP Manual
  • Fann 関数
  • Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

fann_get_quickprop_decay

(PECL fann >= 1.0.0)

fann_get_quickprop_decay — Returns the decay which is a factor that weights should decrease in each iteration during quickprop training

説明

fann_get_quickprop_decay(resource $ann): float

The decay is a small negative valued number which is a factor that the weights should decrease in each iteration during quickprop training. This is used to make sure that the weights do not become too high during training.

The default decay is -0.0001.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The decay, or false on error.

参考

  • fann_set_quickprop_decay() - Sets the quickprop decay factor


Returns the mu factor

  • ≪ fann_get_quickprop_decay
  • fann_get_rprop_decrease_factor ≫
  • PHP Manual
  • Fann 関数
  • Returns the mu factor

fann_get_quickprop_mu

(PECL fann >= 1.0.0)

fann_get_quickprop_mu — Returns the mu factor

説明

fann_get_quickprop_mu(resource $ann): float

The mu factor is used to increase and decrease the step-size during quickprop training. The mu factor should always be above 1, since it would otherwise decrease the step-size when it was suppose to increase it.

The default mu factor is 1.75.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The mu factor, or false on error.

参考

  • fann_set_quickprop_mu() - Sets the quickprop mu factor


Returns the increase factor used during RPROP training

  • ≪ fann_get_quickprop_mu
  • fann_get_rprop_delta_max ≫
  • PHP Manual
  • Fann 関数
  • Returns the increase factor used during RPROP training

fann_get_rprop_decrease_factor

(PECL fann >= 1.0.0)

fann_get_rprop_decrease_factor — Returns the increase factor used during RPROP training

説明

fann_get_rprop_decrease_factor(resource $ann): float

The decrease factor is a value smaller than 1, which is used to decrease the step-size during RPROP training.

The default decrease factor is 0.5.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The decrease factor, or false on error.

参考

  • fann_set_rprop_decrease_factor() - Sets the decrease factor used during RPROP training


Returns the maximum step-size

  • ≪ fann_get_rprop_decrease_factor
  • fann_get_rprop_delta_min ≫
  • PHP Manual
  • Fann 関数
  • Returns the maximum step-size

fann_get_rprop_delta_max

(PECL fann >= 1.0.0)

fann_get_rprop_delta_max — Returns the maximum step-size

説明

fann_get_rprop_delta_max(resource $ann): float

The maximum step-size is a positive number determining how large the maximum step-size may be.

The default delta max is 50.0.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The maximum step-size, or false on error.

参考

  • fann_set_rprop_delta_max() - Sets the maximum step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size


Returns the minimum step-size

  • ≪ fann_get_rprop_delta_max
  • fann_get_rprop_delta_zero ≫
  • PHP Manual
  • Fann 関数
  • Returns the minimum step-size

fann_get_rprop_delta_min

(PECL fann >= 1.0.0)

fann_get_rprop_delta_min — Returns the minimum step-size

説明

fann_get_rprop_delta_min(resource $ann): float

The minimum step-size is a small positive number determining how small the minimum step-size may be.

The default value delta min is 0.0.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The minimum step-size, or false on error.

参考

  • fann_set_rprop_delta_min() - Sets the minimum step-size


Returns the initial step-size

  • ≪ fann_get_rprop_delta_min
  • fann_get_rprop_increase_factor ≫
  • PHP Manual
  • Fann 関数
  • Returns the initial step-size

fann_get_rprop_delta_zero

(PECL fann >= 1.0.0)

fann_get_rprop_delta_zero — Returns the initial step-size

説明

fann_get_rprop_delta_zero(resource $ann): int

The initial step-size is a positive number determining the initial step size.

The default delta zero is 0.1.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The initial step-size, or false on error.

参考

  • fann_set_rprop_delta_zero() - Sets the initial step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size
  • fann_get_rprop_delta_max() - Returns the maximum step-size


Returns the increase factor used during RPROP training

  • ≪ fann_get_rprop_delta_zero
  • fann_get_sarprop_step_error_shift ≫
  • PHP Manual
  • Fann 関数
  • Returns the increase factor used during RPROP training

fann_get_rprop_increase_factor

(PECL fann >= 1.0.0)

fann_get_rprop_increase_factor — Returns the increase factor used during RPROP training

説明

fann_get_rprop_increase_factor(resource $ann): float

The increase factor is a value larger than 1, which is used to increase the step-size during RPROP training.

The default increase factor is 1.2.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The increase factor, or false on error.

参考

  • fann_set_rprop_increase_factor() - Sets the increase factor used during RPROP training


Returns the sarprop step error shift

  • ≪ fann_get_rprop_increase_factor
  • fann_get_sarprop_step_error_threshold_factor ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop step error shift

fann_get_sarprop_step_error_shift

(PECL fann >= 1.0.0)

fann_get_sarprop_step_error_shift — Returns the sarprop step error shift

説明

fann_get_sarprop_step_error_shift(resource $ann): float

Returns the sarprop step error shift.

The default step error shift is 1.385.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The sarprop step error shift , or false on error.

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_step_error_shift() - Sets the sarprop step error shift


Returns the sarprop step error threshold factor

  • ≪ fann_get_sarprop_step_error_shift
  • fann_get_sarprop_temperature ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop step error threshold factor

fann_get_sarprop_step_error_threshold_factor

(PECL fann >= 1.0.0)

fann_get_sarprop_step_error_threshold_factor — Returns the sarprop step error threshold factor

説明

fann_get_sarprop_step_error_threshold_factor(resource $ann): float

The sarprop step error threshold factor.

The default factor is 0.1.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The sarprop step error threshold factor, or false on error.

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_step_error_threshold_factor() - Sets the sarprop step error threshold factor


Returns the sarprop temperature

  • ≪ fann_get_sarprop_step_error_threshold_factor
  • fann_get_sarprop_weight_decay_shift ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop temperature

fann_get_sarprop_temperature

(PECL fann >= 1.0.0)

fann_get_sarprop_temperature — Returns the sarprop temperature

説明

fann_get_sarprop_temperature(resource $ann): float

Returns the sarprop temperature.

The default temperature is 0.015.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The sarprop temperature, or false on error.

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_temperature() - Sets the sarprop temperature


Returns the sarprop weight decay shift

  • ≪ fann_get_sarprop_temperature
  • fann_get_total_connections ≫
  • PHP Manual
  • Fann 関数
  • Returns the sarprop weight decay shift

fann_get_sarprop_weight_decay_shift

(PECL fann >= 1.0.0)

fann_get_sarprop_weight_decay_shift — Returns the sarprop weight decay shift

説明

fann_get_sarprop_weight_decay_shift(resource $ann): float

The sarprop weight decay shift.

The default delta max is -6.644.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The sarprop weight decay shift, or false on error.

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_set_sarprop_weight_decay_shift() - Sets the sarprop weight decay shift


Get the total number of connections in the entire network

  • ≪ fann_get_sarprop_weight_decay_shift
  • fann_get_total_neurons ≫
  • PHP Manual
  • Fann 関数
  • Get the total number of connections in the entire network

fann_get_total_connections

(PECL fann >= 1.0.0)

fann_get_total_connections — Get the total number of connections in the entire network

説明

fann_get_total_connections(resource $ann): int

Get the total number of connections in the entire network.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Total number of connections in the entire network, or false on error


Get the total number of neurons in the entire network

  • ≪ fann_get_total_connections
  • fann_get_train_error_function ≫
  • PHP Manual
  • Fann 関数
  • Get the total number of neurons in the entire network

fann_get_total_neurons

(PECL fann >= 1.0.0)

fann_get_total_neurons — Get the total number of neurons in the entire network

説明

fann_get_total_neurons(resource $ann): int

Get the total number of neurons in the entire network. This number does also include the bias neurons, so a 2-4-2 network has 2+4+2 +2(bias) = 10 neurons.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Total number of neurons in the entire network, or false on error.


Returns the error function used during training

  • ≪ fann_get_total_neurons
  • fann_get_train_stop_function ≫
  • PHP Manual
  • Fann 関数
  • Returns the error function used during training

fann_get_train_error_function

(PECL fann >= 1.0.0)

fann_get_train_error_function — Returns the error function used during training

説明

fann_get_train_error_function(resource $ann): int

Returns the error function used during training.

The error functions are described further in error functions constants.

The default error function is FANN_ERRORFUNC_TANH.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The error function constant, or false on error.

参考

  • fann_set_train_error_function() - Sets the error function used during training


Returns the stop function used during training

  • ≪ fann_get_train_error_function
  • fann_get_training_algorithm ≫
  • PHP Manual
  • Fann 関数
  • Returns the stop function used during training

fann_get_train_stop_function

(PECL fann >= 1.0.0)

fann_get_train_stop_function — Returns the stop function used during training

説明

fann_get_train_stop_function(resource $ann): int

Returns the stop function used during training.

The stop functions are described further in stop functions constants.

The default stop function is FANN_STOPFUNC_MSE.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

The stop function constant, or false on error.

参考

  • fann_set_train_stop_function() - Sets the stop function used during training


Returns the training algorithm

  • ≪ fann_get_train_stop_function
  • fann_init_weights ≫
  • PHP Manual
  • Fann 関数
  • Returns the training algorithm

fann_get_training_algorithm

(PECL fann >= 1.0.0)

fann_get_training_algorithm — Returns the training algorithm

説明

fann_get_training_algorithm(resource $ann): int

Returns the training algorithm. This training algorithm is used by fann_train_on_data() and associated functions.

Note that this algorithm is also used during fann_cascadetrain_on_data(), although only FANN_TRAIN_RPROP and FANN_TRAIN_QUICKPROP is allowed during cascade training.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

Training algorithm constant, or false on error.

参考

  • fann_set_training_algorithm() - Sets the training algorithm


Initialize the weights using Widrow + Nguyen’s algorithm

  • ≪ fann_get_training_algorithm
  • fann_length_train_data ≫
  • PHP Manual
  • Fann 関数
  • Initialize the weights using Widrow + Nguyen’s algorithm

fann_init_weights

(PECL fann >= 1.0.0)

fann_init_weights — Initialize the weights using Widrow + Nguyen's algorithm

説明

fann_init_weights(resource $ann, resource $train_data): bool

Initialize the weights using Widrow + Nguyen's algorithm.

This function behaves similarly to fann_randomize_weights(). It will use the algorithm developed by Derrick Nguyen and Bernard Widrow to set the weights in such a way as to speed up training. This technique is not always successful, and in some cases can be less efficient than a purely random initialization.

The algorithm requires access to the range of the input data (for example largest and smallest input), and therefore accepts a second argument, data, which is the training data that will be used to train the network.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_randomize_weights() - Give each connection a random weight between min_weight and max_weight
  • fann_read_train_from_file() - Reads a file that stores training data


Returns the number of training patterns in the train data

  • ≪ fann_init_weights
  • fann_merge_train_data ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of training patterns in the train data

fann_length_train_data

(PECL fann >= 1.0.0)

fann_length_train_data — Returns the number of training patterns in the train data

説明

fann_length_train_data(resource $data): int

Returns the number of training patterns in the train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

戻り値

Number of elements in the train data resource, or false on error.


Merges the train data

  • ≪ fann_length_train_data
  • fann_num_input_train_data ≫
  • PHP Manual
  • Fann 関数
  • Merges the train data

fann_merge_train_data

(PECL fann >= 1.0.0)

fann_merge_train_data — Merges the train data

説明

fann_merge_train_data(resource $data1, resource $data2): resource

Merges the data from data1 and data2 into a new train data resource.

パラメータ

data1

ニューラルネットワークトレーニングリソース。

data2

ニューラルネットワークトレーニングリソース。

戻り値

New merged train data resource, or false on error.


Returns the number of inputs in each of the training patterns in the train data

  • ≪ fann_merge_train_data
  • fann_num_output_train_data ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of inputs in each of the training patterns in the train data

fann_num_input_train_data

(PECL fann >= 1.0.0)

fann_num_input_train_data — Returns the number of inputs in each of the training patterns in the train data

説明

fann_num_input_train_data(resource $data): int

Returns the number of inputs in each of the training patterns in the train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

戻り値

The number of inputs, or false on error.

参考

  • fann_length_train_data() - Returns the number of training patterns in the train data
  • fann_num_output_train_data() - Returns the number of outputs in each of the training patterns in the train data


Returns the number of outputs in each of the training patterns in the train data

  • ≪ fann_num_input_train_data
  • fann_print_error ≫
  • PHP Manual
  • Fann 関数
  • Returns the number of outputs in each of the training patterns in the train data

fann_num_output_train_data

(PECL fann >= 1.0.0)

fann_num_output_train_data — Returns the number of outputs in each of the training patterns in the train data

説明

fann_num_output_train_data(resource $data): int

Returns the number of outputs in each of the training patterns in the train data resource.

パラメータ

data

ニューラルネットワークトレーニングリソース。

戻り値

The number of outputs, or false on error.

参考

  • fann_length_train_data() - Returns the number of training patterns in the train data
  • fann_num_input_train_data() - Returns the number of inputs in each of the training patterns in the train data


Prints the error string

  • ≪ fann_num_output_train_data
  • fann_randomize_weights ≫
  • PHP Manual
  • Fann 関数
  • Prints the error string

fann_print_error

(PECL fann >= 1.0.0)

fann_print_error — Prints the error string

説明

fann_print_error(resource $errdat): void

Prints the error string.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

戻り値

値を返しません。

参考

  • fann_get_errstr() - Returns the last errstr


Give each connection a random weight between min_weight and max_weight

  • ≪ fann_print_error
  • fann_read_train_from_file ≫
  • PHP Manual
  • Fann 関数
  • Give each connection a random weight between min_weight and max_weight

fann_randomize_weights

(PECL fann >= 1.0.0)

fann_randomize_weights — Give each connection a random weight between min_weight and max_weight

説明

fann_randomize_weights(resource $ann, float $min_weight, float $max_weight): bool

Give each connection a random weight between min_weight and max_weight

From the beginning the weights are random between -0.1 and 0.1.

パラメータ

ann

ニューラルネットワークリソース。

min_weight

Minimum weight value

max_weight

Maximum weight value

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_init_weights() - Initialize the weights using Widrow + Nguyen’s algorithm


Reads a file that stores training data

  • ≪ fann_randomize_weights
  • fann_reset_errno ≫
  • PHP Manual
  • Fann 関数
  • Reads a file that stores training data

fann_read_train_from_file

(PECL fann >= 1.0.0)

fann_read_train_from_file — Reads a file that stores training data

説明

fann_read_train_from_file(string $filename): resource

Reads a file that stores training data.

パラメータ

filename

The input file in the following format:

num_train_data num_input num_output
inputdata separated by space
outputdata separated by space

.
.
.

inputdata separated by space
outputdata separated by space

戻り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

例

例1 fann_read_train_from_file() example

<?php
$train_data = fann_read_train_from_file("xor.data");
if ($train_data) {
// Do something with $train_data for XOR function
}
?>

Contents of xor.data

4 2 1
-1 -1
-1
-1 1
1
1 -1
1
1 1
-1

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_destroy_train() - Destructs the training data
  • fann_save_train() - Save the training structure to a file


Resets the last error number

  • ≪ fann_read_train_from_file
  • fann_reset_errstr ≫
  • PHP Manual
  • Fann 関数
  • Resets the last error number

fann_reset_errno

(PECL fann >= 1.0.0)

fann_reset_errno — Resets the last error number

説明

fann_reset_errno(resource $errdat): void

Resets the last error number.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

戻り値

値を返しません。

参考

  • fann_get_errno() - Returns the last error number
  • fann_reset_errstr() - Resets the last error string


Resets the last error string

  • ≪ fann_reset_errno
  • fann_reset_MSE ≫
  • PHP Manual
  • Fann 関数
  • Resets the last error string

fann_reset_errstr

(PECL fann >= 1.0.0)

fann_reset_errstr — Resets the last error string

説明

fann_reset_errstr(resource $errdat): void

Resets the last error string.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

戻り値

値を返しません。

参考

  • fann_get_errstr() - Returns the last errstr
  • fann_reset_errno() - Resets the last error number


Resets the mean square error from the network

  • ≪ fann_reset_errstr
  • fann_run ≫
  • PHP Manual
  • Fann 関数
  • Resets the mean square error from the network

fann_reset_MSE

(PECL fann >= 1.0.0)

fann_reset_MSE — Resets the mean square error from the network

説明

fann_reset_MSE(string $ann): bool

Resets the mean square error from the network.

This function also resets the number of bits that fail.

パラメータ

ann

ニューラルネットワークリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_MSE() - Reads the mean square error from the network
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_bit_fail_limit() - Returns the bit fail limit used during training


Will run input through the neural network

  • ≪ fann_reset_MSE
  • fann_save ≫
  • PHP Manual
  • Fann 関数
  • Will run input through the neural network

fann_run

(PECL fann >= 1.0.0)

fann_run — Will run input through the neural network

説明

fann_run(resource $ann, array $input): array

Will run input through the neural network, returning an array of outputs, the number of which being equal to the number of neurons in the output layer.

パラメータ

ann

ニューラルネットワークリソース。

input

Array of input values

戻り値

Array of output values, or false on error


Saves the entire network to a configuration file

  • ≪ fann_run
  • fann_save_train ≫
  • PHP Manual
  • Fann 関数
  • Saves the entire network to a configuration file

fann_save

(PECL fann >= 1.0.0)

fann_save — Saves the entire network to a configuration file

説明

fann_save(resource $ann, string $configuration_file): bool

Saves the entire network to a configuration file.

The configuration file contains all information about the neural network and enables fann_create_from_file() to create an exact copy of the neural network and all of the parameters associated with the neural network.

These three parameters (fann_set_callback(), fann_set_error_log(), fann_set_user_data()) are NOT saved to the file because they cannot safely be ported to a different location. Also temporary parameters generated during training like fann_get_MSE() is not saved.

パラメータ

ann

ニューラルネットワークリソース。

configuration_file

The configuration file path.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_create_from_file() - Constructs a backpropagation neural network from a configuration file


Save the training structure to a file

  • ≪ fann_save
  • fann_scale_input ≫
  • PHP Manual
  • Fann 関数
  • Save the training structure to a file

fann_save_train

(PECL fann >= 1.0.0)

fann_save_train — Save the training structure to a file

説明

fann_save_train(resource $data, string $file_name): bool

Save the training data to a file, with the format as specified in fann_read_train_from_file().

パラメータ

data

ニューラルネットワークトレーニングリソース。

file_name

The file name of the file where training data is saved to.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_read_train_from_file() - Reads a file that stores training data


Scale data in input vector before feed it to ann based on previously calculated parameters

  • ≪ fann_save_train
  • fann_scale_input_train_data ≫
  • PHP Manual
  • Fann 関数
  • Scale data in input vector before feed it to ann based on previously calculated parameters

fann_scale_input

(PECL fann >= 1.0.0)

fann_scale_input — Scale data in input vector before feed it to ann based on previously calculated parameters

説明

fann_scale_input(resource $ann, array $input_vector): bool

Scale data in input vector before feed it to ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

input_vector

Input vector that will be scaled

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_descale_input() - Scale data in input vector after get it from ann based on previously calculated parameters
  • fann_scale_output() - Scale data in output vector before feed it to ann based on previously calculated parameters


Scales the inputs in the training data to the specified range

  • ≪ fann_scale_input
  • fann_scale_output ≫
  • PHP Manual
  • Fann 関数
  • Scales the inputs in the training data to the specified range

fann_scale_input_train_data

(PECL fann >= 1.0.0)

fann_scale_input_train_data — Scales the inputs in the training data to the specified range

説明

fann_scale_input_train_data(resource $train_data, float $new_min, float $new_max): bool

Scales the inputs in the training data to the specified range.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

new_min

New minimum after scaling inputs in training data.

new_max

New maximum after scaling inputs in training data.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_output_train_data() - Scales the outputs in the training data to the specified range
  • fann_scale_train_data() - Scales the inputs and outputs in the training data to the specified range


Scale data in output vector before feed it to ann based on previously calculated parameters

  • ≪ fann_scale_input_train_data
  • fann_scale_output_train_data ≫
  • PHP Manual
  • Fann 関数
  • Scale data in output vector before feed it to ann based on previously calculated parameters

fann_scale_output

(PECL fann >= 1.0.0)

fann_scale_output — Scale data in output vector before feed it to ann based on previously calculated parameters

説明

fann_scale_output(resource $ann, array $output_vector): bool

Scale data in output vector before feed it to ann based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

output_vector

Output vector that will be scaled

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_descale_output() - Scale data in output vector after get it from ann based on previously calculated parameters
  • fann_scale_input() - Scale data in input vector before feed it to ann based on previously calculated parameters


Scales the outputs in the training data to the specified range

  • ≪ fann_scale_output
  • fann_scale_train ≫
  • PHP Manual
  • Fann 関数
  • Scales the outputs in the training data to the specified range

fann_scale_output_train_data

(PECL fann >= 1.0.0)

fann_scale_output_train_data — Scales the outputs in the training data to the specified range

説明

fann_scale_output_train_data(resource $train_data, float $new_min, float $new_max): bool

Scales the outputs in the training data to the specified range.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

new_min

New minimum after scaling outputs in training data.

new_max

New maximum after scaling outputs in training data.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_input_train_data() - Scales the inputs in the training data to the specified range
  • fann_scale_train_data() - Scales the inputs and outputs in the training data to the specified range


Scale input and output data based on previously calculated parameters

  • ≪ fann_scale_output_train_data
  • fann_scale_train_data ≫
  • PHP Manual
  • Fann 関数
  • Scale input and output data based on previously calculated parameters

fann_scale_train

(PECL fann >= 1.0.0)

fann_scale_train — Scale input and output data based on previously calculated parameters

説明

fann_scale_train(resource $ann, resource $train_data): bool

Scale input and output data based on previously calculated parameters.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_descale_train() - Descale input and output data based on previously calculated parameters
  • fann_set_scaling_params() - Calculate input and output scaling parameters for future use based on training data


Scales the inputs and outputs in the training data to the specified range

  • ≪ fann_scale_train
  • fann_set_activation_function ≫
  • PHP Manual
  • Fann 関数
  • Scales the inputs and outputs in the training data to the specified range

fann_scale_train_data

(PECL fann >= 1.0.0)

fann_scale_train_data — Scales the inputs and outputs in the training data to the specified range

説明

fann_scale_train_data(resource $train_data, float $new_min, float $new_max): bool

Scales the inputs and outputs in the training data to the specified range.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

new_min

New minimum after scaling inputs and outputs in training data.

new_max

New maximum after scaling inputs and outputs in training data.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_scale_output_train_data() - Scales the outputs in the training data to the specified range
  • fann_scale_input_train_data() - Scales the inputs in the training data to the specified range


Sets the activation function for supplied neuron and layer

  • ≪ fann_scale_train_data
  • fann_set_activation_function_hidden ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for supplied neuron and layer

fann_set_activation_function

(PECL fann >= 1.0.0)

fann_set_activation_function — Sets the activation function for supplied neuron and layer

説明

fann_set_activation_function(
resource $ann,
int $activation_function,
int $layer,
int $neuron
): bool

Set the activation function for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to set activation functions for the neurons in the input layer.

When choosing an activation function it is important to note that the activation functions have different range. FANN_SIGMOID is e.g. in the 0 - 1 range while FANN_SIGMOID_SYMMETRIC is in the -1 - 1 range and FANN_LINEAR is unbound.

The supplied activation_function value must be one of the activation functions constants.

The return value is one of the activation functions constants.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

layer

Layer number.

neuron

Neuron number.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_get_activation_function() - Returns the activation function


Sets the activation function for all of the hidden layers

  • ≪ fann_set_activation_function
  • fann_set_activation_function_layer ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for all of the hidden layers

fann_set_activation_function_hidden

(PECL fann >= 1.0.0)

fann_set_activation_function_hidden — Sets the activation function for all of the hidden layers

説明

fann_set_activation_function_hidden(resource $ann, int $activation_function): bool

Sets the activation function for all of the hidden layers.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number


Sets the activation function for all the neurons in the supplied layer

  • ≪ fann_set_activation_function_hidden
  • fann_set_activation_function_output ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for all the neurons in the supplied layer

fann_set_activation_function_layer

(PECL fann >= 1.0.0)

fann_set_activation_function_layer — Sets the activation function for all the neurons in the supplied layer

説明

fann_set_activation_function_layer(resource $ann, int $activation_function, int $layer): bool

Set the activation function for all the neurons in the layer number layer, counting the input layer as layer 0.

It is not possible to set activation functions for the neurons in the input layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

layer

Layer number.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_function_output() - Sets the activation function for the output layer
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number


Sets the activation function for the output layer

  • ≪ fann_set_activation_function_layer
  • fann_set_activation_steepness ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation function for the output layer

fann_set_activation_function_output

(PECL fann >= 1.0.0)

fann_set_activation_function_output — Sets the activation function for the output layer

説明

fann_set_activation_function_output(resource $ann, int $activation_function): bool

Sets the activation function for the output layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_function

The activation functions constant.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer
  • fann_set_activation_function_layer() - Sets the activation function for all the neurons in the supplied layer
  • fann_set_activation_function_hidden() - Sets the activation function for all of the hidden layers
  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number


Sets the activation steepness for supplied neuron and layer number

  • ≪ fann_set_activation_function_output
  • fann_set_activation_steepness_hidden ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation steepness for supplied neuron and layer number

fann_set_activation_steepness

(PECL fann >= 1.0.0)

fann_set_activation_steepness — Sets the activation steepness for supplied neuron and layer number

説明

fann_set_activation_steepness(
resource $ann,
float $activation_steepness,
int $layer,
int $neuron
): bool

Set the activation steepness for neuron number neuron in layer number layer, counting the input layer as layer 0.

It is not possible to set activation steepness for the neurons in the input layer.

The steepness of an activation function says something about how fast the activation function goes from the minimum to the maximum. A high value for the activation function will also give a more aggressive training.

When training neural networks where the output values should be at the extremes (usually 0 and 1, depending on the activation function), a steep activation function can be used (e.g. 1.0).

The default activation steepness is 0.5.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

layer

Layer number.

neuron

Neuron number.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer


Sets the steepness of the activation steepness for all neurons in the all hidden layers

  • ≪ fann_set_activation_steepness
  • fann_set_activation_steepness_layer ≫
  • PHP Manual
  • Fann 関数
  • Sets the steepness of the activation steepness for all neurons in the all hidden layers

fann_set_activation_steepness_hidden

(PECL fann >= 1.0.0)

fann_set_activation_steepness_hidden — Sets the steepness of the activation steepness for all neurons in the all hidden layers

説明

fann_set_activation_steepness_hidden(resource $ann, float $activation_steepness): bool

Sets the steepness of the activation steepness for all neurons in the all hidden layers.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer


Sets the activation steepness for all of the neurons in the supplied layer number

  • ≪ fann_set_activation_steepness_hidden
  • fann_set_activation_steepness_output ≫
  • PHP Manual
  • Fann 関数
  • Sets the activation steepness for all of the neurons in the supplied layer number

fann_set_activation_steepness_layer

(PECL fann >= 1.0.0)

fann_set_activation_steepness_layer — Sets the activation steepness for all of the neurons in the supplied layer number

説明

fann_set_activation_steepness_layer(resource $ann, float $activation_steepness, int $layer): bool

Set the activation steepness for all of the neurons in layer number layer, counting the input layer as layer 0.

It is not possible to set activation steepness for the neurons in the input layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

layer

Layer number.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_set_activation_steepness_output() - Sets the steepness of the activation steepness in the output layer
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer


Sets the steepness of the activation steepness in the output layer

  • ≪ fann_set_activation_steepness_layer
  • fann_set_bit_fail_limit ≫
  • PHP Manual
  • Fann 関数
  • Sets the steepness of the activation steepness in the output layer

fann_set_activation_steepness_output

(PECL fann >= 1.0.0)

fann_set_activation_steepness_output — Sets the steepness of the activation steepness in the output layer

説明

fann_set_activation_steepness_output(resource $ann, float $activation_steepness): bool

Sets the steepness of the activation steepness in the output layer.

パラメータ

ann

ニューラルネットワークリソース。

activation_steepness

The activation steepness.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_activation_steepness() - Sets the activation steepness for supplied neuron and layer number
  • fann_set_activation_steepness_layer() - Sets the activation steepness for all of the neurons in the supplied layer number
  • fann_set_activation_steepness_hidden() - Sets the steepness of the activation steepness for all neurons in the all hidden layers
  • fann_get_activation_steepness() - Returns the activation steepness for supplied neuron and layer number
  • fann_set_activation_function() - Sets the activation function for supplied neuron and layer


Set the bit fail limit used during training

  • ≪ fann_set_activation_steepness_output
  • fann_set_callback ≫
  • PHP Manual
  • Fann 関数
  • Set the bit fail limit used during training

fann_set_bit_fail_limit

(PECL fann >= 1.0.0)

fann_set_bit_fail_limit — Set the bit fail limit used during training

説明

fann_set_bit_fail_limit(resource $ann, float $bit_fail_limit): bool

Set the bit fail limit used during training.

パラメータ

ann

ニューラルネットワークリソース。

bit_fail_limit

The bit fail limit.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_bit_fail_limit() - Returns the bit fail limit used during training


Sets the callback function for use during training

  • ≪ fann_set_bit_fail_limit
  • fann_set_cascade_activation_functions ≫
  • PHP Manual
  • Fann 関数
  • Sets the callback function for use during training

fann_set_callback

(PECL fann >= 1.0.0)

fann_set_callback — Sets the callback function for use during training

説明

fann_set_callback(resource $ann, callable $callback): bool

Sets the callback function for use during training. It means that it is called from fann_train_on_data() or fann_train_on_file().

パラメータ

ann

ニューラルネットワークリソース。

callback

The supplied callback function takes following parameters:

  • ann - The neural network resource
  • train - The train data resource or null if called from fann_train_on_file()
  • max_epochs - The maximum number of epochs the training should continue
  • epochs_between_reports - The number of epochs between calling this function
  • desired_error - The desired fann_get_MSE() or fann_get_bit_fail(), depending on the stop function chosen by fann_set_train_stop_function()
  • epochs - The current epoch

The callback should return true. If it returns false, the training will terminate.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_on_file() - Trains on an entire dataset, which is read from file, for a period of time


Sets the array of cascade candidate activation functions

  • ≪ fann_set_callback
  • fann_set_cascade_activation_steepnesses ≫
  • PHP Manual
  • Fann 関数
  • Sets the array of cascade candidate activation functions

fann_set_cascade_activation_functions

(PECL fann >= 1.0.0)

fann_set_cascade_activation_functions — Sets the array of cascade candidate activation functions

説明

fann_set_cascade_activation_functions(resource $ann, array $cascade_activation_functions): bool

Sets the array of cascade candidate activation functions.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

パラメータ

ann

ニューラルネットワークリソース。

cascade_activation_functions

The array of cascade candidate activation functions.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_activation_functions_count() - Returns the number of cascade activation functions
  • fann_set_cascade_activation_functions()


Sets the array of cascade candidate activation steepnesses

  • ≪ fann_set_cascade_activation_functions
  • fann_set_cascade_candidate_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Sets the array of cascade candidate activation steepnesses

fann_set_cascade_activation_steepnesses

(PECL fann >= 1.0.0)

fann_set_cascade_activation_steepnesses — Sets the array of cascade candidate activation steepnesses

説明

fann_set_cascade_activation_steepnesses(resource $ann, array $cascade_activation_steepnesses_count): bool

Sets the array of cascade candidate activation steepnesses.

See fann_get_cascade_num_candidates() for a description of which candidate neurons will be generated by this array.

パラメータ

ann

ニューラルネットワークリソース。

cascade_activation_steepnesses_count

The array of cascade candidate activation steepnesses.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_activation_steepnesses() - Returns the cascade activation steepnesses
  • fann_get_cascade_activation_steepnesses_count() - The number of activation steepnesses


Sets the cascade candidate change fraction

  • ≪ fann_set_cascade_activation_steepnesses
  • fann_set_cascade_candidate_limit ≫
  • PHP Manual
  • Fann 関数
  • Sets the cascade candidate change fraction

fann_set_cascade_candidate_change_fraction

(PECL fann >= 1.0.0)

fann_set_cascade_candidate_change_fraction — Sets the cascade candidate change fraction

説明

fann_set_cascade_candidate_change_fraction(resource $ann, float $cascade_candidate_change_fraction): bool

Sets the cascade candidate change fraction.

パラメータ

ann

ニューラルネットワークリソース。

cascade_candidate_change_fraction

The cascade candidate change fraction.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_candidate_change_fraction() - Returns the cascade candidate change fraction


Sets the candidate limit

  • ≪ fann_set_cascade_candidate_change_fraction
  • fann_set_cascade_candidate_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the candidate limit

fann_set_cascade_candidate_limit

(PECL fann >= 1.0.0)

fann_set_cascade_candidate_limit — Sets the candidate limit

説明

fann_set_cascade_candidate_limit(resource $ann, float $cascade_candidate_limit): bool

Sets the candidate limit.

パラメータ

ann

ニューラルネットワークリソース。

cascade_candidate_limit

The candidate limit.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_candidate_limit() - Return the candidate limit


Sets the number of cascade candidate stagnation epochs

  • ≪ fann_set_cascade_candidate_limit
  • fann_set_cascade_max_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the number of cascade candidate stagnation epochs

fann_set_cascade_candidate_stagnation_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_candidate_stagnation_epochs — Sets the number of cascade candidate stagnation epochs

説明

fann_set_cascade_candidate_stagnation_epochs(resource $ann, int $cascade_candidate_stagnation_epochs): bool

Sets the number of cascade candidate stagnation epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_candidate_stagnation_epochs

The number of cascade candidate stagnation epochs.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_candidate_stagnation_epochs() - Returns the number of cascade candidate stagnation epochs


Sets the max candidate epochs

  • ≪ fann_set_cascade_candidate_stagnation_epochs
  • fann_set_cascade_max_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the max candidate epochs

fann_set_cascade_max_cand_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_max_cand_epochs — Sets the max candidate epochs

説明

fann_set_cascade_max_cand_epochs(resource $ann, int $cascade_max_cand_epochs): bool

Sets the max candidate epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_max_cand_epochs

The max candidate epochs.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_max_cand_epochs() - Returns the maximum candidate epochs


Sets the maximum out epochs

  • ≪ fann_set_cascade_max_cand_epochs
  • fann_set_cascade_min_cand_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the maximum out epochs

fann_set_cascade_max_out_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_max_out_epochs — Sets the maximum out epochs

説明

fann_set_cascade_max_out_epochs(resource $ann, int $cascade_max_out_epochs): bool

Sets the maximum out epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_max_out_epochs

The maximum out epochs.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_max_out_epochs() - Returns the maximum out epochs


Sets the min candidate epochs

  • ≪ fann_set_cascade_max_out_epochs
  • fann_set_cascade_min_out_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the min candidate epochs

fann_set_cascade_min_cand_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_min_cand_epochs — Sets the min candidate epochs

説明

fann_set_cascade_min_cand_epochs(resource $ann, int $cascade_min_cand_epochs): bool

Sets the min candidate epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_min_cand_epochs

The minimum candidate epochs.

戻り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_cascade_min_cand_epochs() - Returns the minimum candidate epochs


Sets the minimum out epochs

  • ≪ fann_set_cascade_min_cand_epochs
  • fann_set_cascade_num_candidate_groups ≫
  • PHP Manual
  • Fann 関数
  • Sets the minimum out epochs

fann_set_cascade_min_out_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_min_out_epochs — Sets the minimum out epochs

説明

fann_set_cascade_min_out_epochs(resource $ann, int $cascade_min_out_epochs): bool

Sets the minimum out epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_min_out_epochs

The minimum out epochs.

戻り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_cascade_min_out_epochs() - Returns the minimum out epochs


Sets the number of candidate groups

  • ≪ fann_set_cascade_min_out_epochs
  • fann_set_cascade_output_change_fraction ≫
  • PHP Manual
  • Fann 関数
  • Sets the number of candidate groups

fann_set_cascade_num_candidate_groups

(PECL fann >= 1.0.0)

fann_set_cascade_num_candidate_groups — Sets the number of candidate groups

説明

fann_set_cascade_num_candidate_groups(resource $ann, int $cascade_num_candidate_groups): bool

Sets the number of candidate groups.

パラメータ

ann

ニューラルネットワークリソース。

cascade_num_candidate_groups

The number of candidate groups.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_num_candidate_groups() - Returns the number of candidate groups


Sets the cascade output change fraction

  • ≪ fann_set_cascade_num_candidate_groups
  • fann_set_cascade_output_stagnation_epochs ≫
  • PHP Manual
  • Fann 関数
  • Sets the cascade output change fraction

fann_set_cascade_output_change_fraction

(PECL fann >= 1.0.0)

fann_set_cascade_output_change_fraction — Sets the cascade output change fraction

説明

fann_set_cascade_output_change_fraction(resource $ann, float $cascade_output_change_fraction): bool

Sets the cascade output change fraction.

パラメータ

ann

ニューラルネットワークリソース。

cascade_output_change_fraction

The cascade output change fraction.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_output_change_fraction() - Returns the cascade output change fraction


Sets the number of cascade output stagnation epochs

  • ≪ fann_set_cascade_output_change_fraction
  • fann_set_cascade_weight_multiplier ≫
  • PHP Manual
  • Fann 関数
  • Sets the number of cascade output stagnation epochs

fann_set_cascade_output_stagnation_epochs

(PECL fann >= 1.0.0)

fann_set_cascade_output_stagnation_epochs — Sets the number of cascade output stagnation epochs

説明

fann_set_cascade_output_stagnation_epochs(resource $ann, int $cascade_output_stagnation_epochs): bool

Sets the number of cascade output stagnation epochs.

パラメータ

ann

ニューラルネットワークリソース。

cascade_output_stagnation_epochs

The number of cascade output stagnation epochs.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_output_stagnation_epochs() - Returns the number of cascade output stagnation epochs


Sets the weight multiplier

  • ≪ fann_set_cascade_output_stagnation_epochs
  • fann_set_error_log ≫
  • PHP Manual
  • Fann 関数
  • Sets the weight multiplier

fann_set_cascade_weight_multiplier

(PECL fann >= 1.0.0)

fann_set_cascade_weight_multiplier — Sets the weight multiplier

説明

fann_set_cascade_weight_multiplier(resource $ann, float $cascade_weight_multiplier): bool

Sets the weight multiplier.

パラメータ

ann

ニューラルネットワークリソース。

cascade_weight_multiplier

The weight multiplier.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_cascade_weight_multiplier() - Returns the weight multiplier


Sets where the errors are logged to

  • ≪ fann_set_cascade_weight_multiplier
  • fann_set_input_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Sets where the errors are logged to

fann_set_error_log

(PECL fann >= 1.0.0)

fann_set_error_log — Sets where the errors are logged to

説明

fann_set_error_log(resource $errdat, string $log_file): void

Sets where the errors are logged to.

パラメータ

errdat

ニューラルネットワークリソースあるいはニューラルネットワークトレーニングリソース。

log_file

The log file path.

戻り値

値を返しません。


Calculate input scaling parameters for future use based on training data

  • ≪ fann_set_error_log
  • fann_set_learning_momentum ≫
  • PHP Manual
  • Fann 関数
  • Calculate input scaling parameters for future use based on training data

fann_set_input_scaling_params

(PECL fann >= 1.0.0)

fann_set_input_scaling_params — Calculate input scaling parameters for future use based on training data

説明

fann_set_input_scaling_params(
resource $ann,
resource $train_data,
float $new_input_min,
float $new_input_max
): bool

Calculate input scaling parameters for future use based on training data.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

new_input_min

The desired lower bound in input data after scaling (not strictly followed)

new_input_max

The desired upper bound in input data after scaling (not strictly followed)

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_output_scaling_params() - Calculate output scaling parameters for future use based on training data


Sets the learning momentum

  • ≪ fann_set_input_scaling_params
  • fann_set_learning_rate ≫
  • PHP Manual
  • Fann 関数
  • Sets the learning momentum

fann_set_learning_momentum

(PECL fann >= 1.0.0)

fann_set_learning_momentum — Sets the learning momentum

説明

fann_set_learning_momentum(resource $ann, float $learning_momentum): bool

Sets the learning momentum.

More info available in fann_get_learning_momentum().

パラメータ

ann

ニューラルネットワークリソース。

learning_momentum

The learning momentum.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_learning_momentum() - Returns the learning momentum
  • fann_set_training_algorithm() - Sets the training algorithm


Sets the learning rate

  • ≪ fann_set_learning_momentum
  • fann_set_output_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Sets the learning rate

fann_set_learning_rate

(PECL fann >= 1.0.0)

fann_set_learning_rate — Sets the learning rate

説明

fann_set_learning_rate(resource $ann, float $learning_rate): bool

Sets the learning rate.

More info available in fann_get_learning_rate().

パラメータ

ann

ニューラルネットワークリソース。

learning_rate

The learning rate.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_learning_rate() - Returns the learning rate
  • fann_set_training_algorithm() - Sets the training algorithm


Calculate output scaling parameters for future use based on training data

  • ≪ fann_set_learning_rate
  • fann_set_quickprop_decay ≫
  • PHP Manual
  • Fann 関数
  • Calculate output scaling parameters for future use based on training data

fann_set_output_scaling_params

(PECL fann >= 1.0.0)

fann_set_output_scaling_params — Calculate output scaling parameters for future use based on training data

説明

fann_set_output_scaling_params(
resource $ann,
resource $train_data,
float $new_output_min,
float $new_output_max
): bool

Calculate output scaling parameters for future use based on training data.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

new_output_min

The desired lower bound in output data after scaling (not strictly followed)

new_output_max

The desired upper bound in output data after scaling (not strictly followed)

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_input_scaling_params() - Calculate input scaling parameters for future use based on training data


Sets the quickprop decay factor

  • ≪ fann_set_output_scaling_params
  • fann_set_quickprop_mu ≫
  • PHP Manual
  • Fann 関数
  • Sets the quickprop decay factor

fann_set_quickprop_decay

(PECL fann >= 1.0.0)

fann_set_quickprop_decay — Sets the quickprop decay factor

説明

fann_set_quickprop_decay(resource $ann, float $quickprop_decay): bool

Sets the quickprop decay factor.

パラメータ

ann

ニューラルネットワークリソース。

quickprop_decay

The quickprop decay factor.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_quickprop_decay() - Returns the decay which is a factor that weights should decrease in each iteration during quickprop training


Sets the quickprop mu factor

  • ≪ fann_set_quickprop_decay
  • fann_set_rprop_decrease_factor ≫
  • PHP Manual
  • Fann 関数
  • Sets the quickprop mu factor

fann_set_quickprop_mu

(PECL fann >= 1.0.0)

fann_set_quickprop_mu — Sets the quickprop mu factor

説明

fann_set_quickprop_mu(resource $ann, float $quickprop_mu): bool

Sets the quickprop mu factor.

パラメータ

ann

ニューラルネットワークリソース。

quickprop_mu

The mu factor.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_quickprop_mu() - Returns the mu factor


Sets the decrease factor used during RPROP training

  • ≪ fann_set_quickprop_mu
  • fann_set_rprop_delta_max ≫
  • PHP Manual
  • Fann 関数
  • Sets the decrease factor used during RPROP training

fann_set_rprop_decrease_factor

(PECL fann >= 1.0.0)

fann_set_rprop_decrease_factor — Sets the decrease factor used during RPROP training

説明

fann_set_rprop_decrease_factor(resource $ann, float $rprop_decrease_factor): bool

Sets the decrease factor used during RPROP training.

パラメータ

ann

ニューラルネットワークリソース。

rprop_decrease_factor

The decrease factor.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_decrease_factor() - Returns the increase factor used during RPROP training


Sets the maximum step-size

  • ≪ fann_set_rprop_decrease_factor
  • fann_set_rprop_delta_min ≫
  • PHP Manual
  • Fann 関数
  • Sets the maximum step-size

fann_set_rprop_delta_max

(PECL fann >= 1.0.0)

fann_set_rprop_delta_max — Sets the maximum step-size

説明

fann_set_rprop_delta_max(resource $ann, float $rprop_delta_max): bool

The maximum step-size is a positive number determining how large the maximum step-size may be.

パラメータ

ann

ニューラルネットワークリソース。

rprop_delta_max

The maximum step-size.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_delta_max() - Returns the maximum step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size


Sets the minimum step-size

  • ≪ fann_set_rprop_delta_max
  • fann_set_rprop_delta_zero ≫
  • PHP Manual
  • Fann 関数
  • Sets the minimum step-size

fann_set_rprop_delta_min

(PECL fann >= 1.0.0)

fann_set_rprop_delta_min — Sets the minimum step-size

説明

fann_set_rprop_delta_min(resource $ann, float $rprop_delta_min): bool

The minimum step-size is a small positive number determining how small the minimum step-size may be.

パラメータ

ann

ニューラルネットワークリソース。

rprop_delta_min

The minimum step-size.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_delta_min() - Returns the minimum step-size


Sets the initial step-size

  • ≪ fann_set_rprop_delta_min
  • fann_set_rprop_increase_factor ≫
  • PHP Manual
  • Fann 関数
  • Sets the initial step-size

fann_set_rprop_delta_zero

(PECL fann >= 1.0.0)

fann_set_rprop_delta_zero — Sets the initial step-size

説明

fann_set_rprop_delta_zero(resource $ann, float $rprop_delta_zero): bool

The initial step-size is a positive number determining the initial step size.

パラメータ

ann

ニューラルネットワークリソース。

rprop_delta_zero

The initial step-size.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_delta_zero() - Returns the initial step-size
  • fann_get_rprop_delta_min() - Returns the minimum step-size
  • fann_get_rprop_delta_max() - Returns the maximum step-size


Sets the increase factor used during RPROP training

  • ≪ fann_set_rprop_delta_zero
  • fann_set_sarprop_step_error_shift ≫
  • PHP Manual
  • Fann 関数
  • Sets the increase factor used during RPROP training

fann_set_rprop_increase_factor

(PECL fann >= 1.0.0)

fann_set_rprop_increase_factor — Sets the increase factor used during RPROP training

説明

fann_set_rprop_increase_factor(resource $ann, float $rprop_increase_factor): bool

Sets the increase factor used during RPROP training.

パラメータ

ann

ニューラルネットワークリソース。

rprop_increase_factor

The increase factor.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_rprop_increase_factor() - Returns the increase factor used during RPROP training


Sets the sarprop step error shift

  • ≪ fann_set_rprop_increase_factor
  • fann_set_sarprop_step_error_threshold_factor ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop step error shift

fann_set_sarprop_step_error_shift

(PECL fann >= 1.0.0)

fann_set_sarprop_step_error_shift — Sets the sarprop step error shift

説明

fann_set_sarprop_step_error_shift(resource $ann, float $sarprop_step_error_shift): bool

Sets the sarprop step error shift.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_step_error_shift

The sarprop step error shift.

戻り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_step_error_shift() - Returns the sarprop step error shift


Sets the sarprop step error threshold factor

  • ≪ fann_set_sarprop_step_error_shift
  • fann_set_sarprop_temperature ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop step error threshold factor

fann_set_sarprop_step_error_threshold_factor

(PECL fann >= 1.0.0)

fann_set_sarprop_step_error_threshold_factor — Sets the sarprop step error threshold factor

説明

fann_set_sarprop_step_error_threshold_factor(resource $ann, float $sarprop_step_error_threshold_factor): bool

Sets the sarprop step error threshold factor.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_step_error_threshold_factor

The sarprop step error threshold factor.

戻り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_step_error_threshold_factor() - Returns the sarprop step error threshold factor


Sets the sarprop temperature

  • ≪ fann_set_sarprop_step_error_threshold_factor
  • fann_set_sarprop_weight_decay_shift ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop temperature

fann_set_sarprop_temperature

(PECL fann >= 1.0.0)

fann_set_sarprop_temperature — Sets the sarprop temperature

説明

fann_set_sarprop_temperature(resource $ann, float $sarprop_temperature): bool

Sets the sarprop temperature.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_temperature

The sarprop temperature.

戻り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_temperature() - Returns the sarprop temperature


Sets the sarprop weight decay shift

  • ≪ fann_set_sarprop_temperature
  • fann_set_scaling_params ≫
  • PHP Manual
  • Fann 関数
  • Sets the sarprop weight decay shift

fann_set_sarprop_weight_decay_shift

(PECL fann >= 1.0.0)

fann_set_sarprop_weight_decay_shift — Sets the sarprop weight decay shift

説明

fann_set_sarprop_weight_decay_shift(resource $ann, float $sarprop_weight_decay_shift): bool

Sets the sarprop weight decay shift.

パラメータ

ann

ニューラルネットワークリソース。

sarprop_weight_decay_shift

The sarprop weight decay shift.

戻り値

成功した場合に true、それ以外の場合に false を返します。

注意

注意:

この関数は、fann拡張モジュールが libfann > 2.2 以上でビルドされている場合にだけ利用可能です。

参考

  • fann_get_sarprop_weight_decay_shift() - Returns the sarprop weight decay shift


Calculate input and output scaling parameters for future use based on training data

  • ≪ fann_set_sarprop_weight_decay_shift
  • fann_set_train_error_function ≫
  • PHP Manual
  • Fann 関数
  • Calculate input and output scaling parameters for future use based on training data

fann_set_scaling_params

(PECL fann >= 1.0.0)

fann_set_scaling_params — Calculate input and output scaling parameters for future use based on training data

説明

fann_set_scaling_params(
resource $ann,
resource $train_data,
float $new_input_min,
float $new_input_max,
float $new_output_min,
float $new_output_max
): bool

Calculate input and output scaling parameters for future use based on training data.

パラメータ

ann

ニューラルネットワークリソース。

train_data

ニューラルネットワークトレーニングリソース。

new_input_min

The desired lower bound in input data after scaling (not strictly followed)

new_input_max

The desired upper bound in input data after scaling (not strictly followed)

new_output_min

The desired lower bound in output data after scaling (not strictly followed)

new_output_max

The desired upper bound in output data after scaling (not strictly followed)

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_set_input_scaling_params() - Calculate input scaling parameters for future use based on training data
  • fann_set_output_scaling_params() - Calculate output scaling parameters for future use based on training data


Sets the error function used during training

  • ≪ fann_set_scaling_params
  • fann_set_train_stop_function ≫
  • PHP Manual
  • Fann 関数
  • Sets the error function used during training

fann_set_train_error_function

(PECL fann >= 1.0.0)

fann_set_train_error_function — Sets the error function used during training

説明

fann_set_train_error_function(resource $ann, int $error_function): bool

Sets the error function used during training.

The error functions are described further in error functions constants.

パラメータ

ann

ニューラルネットワークリソース。

error_function

The error function constant

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_train_error_function() - Returns the error function used during training


Sets the stop function used during training

  • ≪ fann_set_train_error_function
  • fann_set_training_algorithm ≫
  • PHP Manual
  • Fann 関数
  • Sets the stop function used during training

fann_set_train_stop_function

(PECL fann >= 1.0.0)

fann_set_train_stop_function — Sets the stop function used during training

説明

fann_set_train_stop_function(resource $ann, int $stop_function): bool

Sets the stop function used during training.

The stop functions are described further in stop functions constants.

パラメータ

ann

ニューラルネットワークリソース。

stop_function

The stop function constant.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_train_stop_function() - Returns the stop function used during training


Sets the training algorithm

  • ≪ fann_set_train_stop_function
  • fann_set_weight ≫
  • PHP Manual
  • Fann 関数
  • Sets the training algorithm

fann_set_training_algorithm

(PECL fann >= 1.0.0)

fann_set_training_algorithm — Sets the training algorithm

説明

fann_set_training_algorithm(resource $ann, int $training_algorithm): bool

Sets the training algorithm.

More info available in fann_get_training_algorithm().

パラメータ

ann

ニューラルネットワークリソース。

training_algorithm

Training algorithm constant

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_get_training_algorithm() - Returns the training algorithm


Set a connection in the network

  • ≪ fann_set_training_algorithm
  • fann_set_weight_array ≫
  • PHP Manual
  • Fann 関数
  • Set a connection in the network

fann_set_weight

(PECL fann >= 1.0.0)

fann_set_weight — Set a connection in the network

説明

fann_set_weight(
resource $ann,
int $from_neuron,
int $to_neuron,
float $weight
): bool

Set a connections in the network.

パラメータ

ann

ニューラルネットワークリソース。

from_neuron

The neuron where the connection starts

to_neuron

The neuron where the connection ends

weight

Connection weight

戻り値

成功した場合に true、それ以外の場合に false を返します。


Set connections in the network

  • ≪ fann_set_weight
  • fann_shuffle_train_data ≫
  • PHP Manual
  • Fann 関数
  • Set connections in the network

fann_set_weight_array

(PECL fann >= 1.0.0)

fann_set_weight_array — Set connections in the network

説明

fann_set_weight_array(resource $ann, array $connections): bool

Set connections in the network.

Only the weights can be changed, connections and weights are ignored if they do not already exist in the network.

パラメータ

ann

ニューラルネットワークリソース。

connections

An array of FANNConnection objects

戻り値

成功した場合に true、それ以外の場合に false を返します。


Shuffles training data, randomizing the order

  • ≪ fann_set_weight_array
  • fann_subset_train_data ≫
  • PHP Manual
  • Fann 関数
  • Shuffles training data, randomizing the order

fann_shuffle_train_data

(PECL fann >= 1.0.0)

fann_shuffle_train_data — Shuffles training data, randomizing the order

説明

fann_shuffle_train_data(resource $train_data): bool

Shuffles training data, randomizing the order. This is recommended for incremental training, while it have no influence during batch training.

パラメータ

train_data

ニューラルネットワークトレーニングリソース。

戻り値

成功した場合に true、それ以外の場合に false を返します。


Returns an copy of a subset of the train data

  • ≪ fann_shuffle_train_data
  • fann_test ≫
  • PHP Manual
  • Fann 関数
  • Returns an copy of a subset of the train data

fann_subset_train_data

(PECL fann >= 1.0.0)

fann_subset_train_data — Returns an copy of a subset of the train data

説明

fann_subset_train_data(resource $data, int $pos, int $length): resource

Returns an copy of a subset of the train data resource, starting at position pos and length elements forward.

The fann_subset_train_data(train_data, 0, fann_length_train_data(train_data)) do the same as fann_duplicate_train_data()

パラメータ

data

ニューラルネットワークトレーニングリソース。

pos

Starting position.

length

The number of copied elements.

戻り値

成功した場合にニューラルネットワークトレーニングリソース、エラー時に false を返します。

参考

  • fann_duplicate_train_data() - Returns an exact copy of a fann train data


Test with a set of inputs, and a set of desired outputs

  • ≪ fann_subset_train_data
  • fann_test_data ≫
  • PHP Manual
  • Fann 関数
  • Test with a set of inputs, and a set of desired outputs

fann_test

(PECL fann >= 1.0.0)

fann_test — Test with a set of inputs, and a set of desired outputs

説明

fann_test(resource $ann, array $input, array $desired_output): array

Test with a set of inputs, and a set of desired outputs. This operation updates the mean square error, but does not change the network in any way.

パラメータ

ann

ニューラルネットワークリソース。

input

An array of inputs. This array must be exactly fann_get_num_input() long.

desired_output

An array of desired outputs. This array must be exactly fann_get_num_output() long.

戻り値

Returns test outputs on success, or false on error.

参考

  • fann_test_data() - Test a set of training data and calculates the MSE for the training data
  • fann_train() - Train one iteration with a set of inputs, and a set of desired outputs
  • fann_get_num_input() - Get the number of input neurons
  • fann_get_num_output() - Get the number of output neurons


Test a set of training data and calculates the MSE for the training data

  • ≪ fann_test
  • fann_train ≫
  • PHP Manual
  • Fann 関数
  • Test a set of training data and calculates the MSE for the training data

fann_test_data

(PECL fann >= 1.0.0)

fann_test_data — Test a set of training data and calculates the MSE for the training data

説明

fann_test_data(resource $ann, resource $data): float

Test a set of training data and calculates the MSE for the training data.

This function updates the MSE and the bit fail values.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

戻り値

The updated MSE, or false on error.

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_training_algorithm() - Sets the training algorithm


Train one iteration with a set of inputs, and a set of desired outputs

  • ≪ fann_test_data
  • fann_train_epoch ≫
  • PHP Manual
  • Fann 関数
  • Train one iteration with a set of inputs, and a set of desired outputs

fann_train

(PECL fann >= 1.0.0)

fann_train — Train one iteration with a set of inputs, and a set of desired outputs

説明

fann_train(resource $ann, array $input, array $desired_output): bool

Train one iteration with a set of inputs, and a set of desired outputs. This training is always incremental training, since only one pattern is presented.

パラメータ

ann

ニューラルネットワークリソース。

input

An array of inputs. This array must be exactly fann_get_num_input() long.

desired_output

An array of desired outputs. This array must be exactly fann_get_num_output() long.

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_num_input() - Get the number of input neurons
  • fann_get_num_output() - Get the number of output neurons


Train one epoch with a set of training data

  • ≪ fann_train
  • fann_train_on_data ≫
  • PHP Manual
  • Fann 関数
  • Train one epoch with a set of training data

fann_train_epoch

(PECL fann >= 1.0.0)

fann_train_epoch — Train one epoch with a set of training data

説明

fann_train_epoch(resource $ann, resource $data): float

Train one epoch with the training data stored in data. One epoch is where all of the training data is considered exactly once.

This function returns the MSE error as it is calculated either before or during the actual training. This is not the actual MSE after the training epoch, but since calculating this will require to go through the entire training set once more. It is more than adequate to use this value during training.

The training algorithm used by this function is chosen by fann_set_training_algorithm() function.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

戻り値

The MSE, or false on error.

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_test_data() - Test a set of training data and calculates the MSE for the training data
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_training_algorithm() - Sets the training algorithm


Trains on an entire dataset for a period of time

  • ≪ fann_train_epoch
  • fann_train_on_file ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset for a period of time

fann_train_on_data

(PECL fann >= 1.0.0)

fann_train_on_data — Trains on an entire dataset for a period of time

説明

fann_train_on_data(
resource $ann,
resource $data,
int $max_epochs,
int $epochs_between_reports,
float $desired_error
): bool

Trains on an entire dataset for a period of time.

This training uses the training algorithm chosen by fann_set_training_algorithm() and the parameters set for these training algorithms.

パラメータ

ann

ニューラルネットワークリソース。

data

ニューラルネットワークトレーニングリソース。

max_epochs

The maximum number of epochs the training should continue

epochs_between_reports

The number of epochs between calling a callback function. A value of zero means that user function is not called.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on the stop function chosen by fann_set_train_stop_function()

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_file() - Trains on an entire dataset, which is read from file, for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_train_stop_function() - Sets the stop function used during training
  • fann_set_training_algorithm() - Sets the training algorithm
  • fann_set_callback() - Sets the callback function for use during training


Trains on an entire dataset, which is read from file, for a period of time

  • ≪ fann_train_on_data
  • FANNConnection ≫
  • PHP Manual
  • Fann 関数
  • Trains on an entire dataset, which is read from file, for a period of time

fann_train_on_file

(PECL fann >= 1.0.0)

fann_train_on_file — Trains on an entire dataset, which is read from file, for a period of time

説明

fann_train_on_file(
resource $ann,
string $filename,
int $max_epochs,
int $epochs_between_reports,
float $desired_error
): bool

Trains on an entire dataset, which is read from file, for a period of time.

This training uses the training algorithm chosen by fann_set_training_algorithm() and the parameters set for these training algorithms.

パラメータ

ann

ニューラルネットワークリソース。

filename

The file containing train data

max_epochs

The maximum number of epochs the training should continue

epochs_between_reports

The number of epochs between calling a user function. A value of zero means that user function is not called.

desired_error

The desired fann_get_MSE() or fann_get_bit_fail(), depending on the stop function chosen by fann_set_train_stop_function()

戻り値

成功した場合に true、それ以外の場合に false を返します。

参考

  • fann_train_on_data() - Trains on an entire dataset for a period of time
  • fann_train_epoch() - Train one epoch with a set of training data
  • fann_get_bit_fail() - The number of fail bits
  • fann_get_MSE() - Reads the mean square error from the network
  • fann_set_train_stop_function() - Sets the stop function used during training
  • fann_set_training_algorithm() - Sets the training algorithm
  • fann_set_callback() - Sets the callback function for use during training


The FANNConnection class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

FANNConnection is used for the neural network connection. The objects of this class are used in fann_get_connection_array() and fann_set_weight_array().

クラス概要

class FANNConnection {
/* プロパティ */
public $from_neuron;
public $to_neuron;
public $weight;
/* メソッド */
public __construct(int $from_neuron, int $to_neuron, float $weight)
public getFromNeuron(): int
public getToNeuron(): int
public getWeight(): void
public setWeight(float $weight): void
}

プロパティ

from_neuron

The neuron where the connection starts.

to_neuron

The neuron where the connection ends.

weight

The weight of the connection.

目次

  • FANNConnection::__construct — The connection constructor
  • FANNConnection::getFromNeuron — Returns the postions of starting neuron
  • FANNConnection::getToNeuron — Returns the postions of terminating neuron
  • FANNConnection::getWeight — Returns the connection weight
  • FANNConnection::setWeight — Sets the connections weight


The connection constructor

  • ≪ FANNConnection
  • FANNConnection::getFromNeuron ≫
  • PHP Manual
  • FANNConnection
  • The connection constructor

FANNConnection::__construct

(PECL fann >= 1.0.0)

FANNConnection::__construct — The connection constructor

説明

public FANNConnection::__construct(int $from_neuron, int $to_neuron, float $weight)

Create new connection and initialize its params. After creating the connection, only weight can be changed.

パラメータ

from_neuron

The position number of starting neuron.

to_neuron

The position number of terminating neuron.

weight

The connection weight value.


Returns the postions of starting neuron

  • ≪ FANNConnection::__construct
  • FANNConnection::getToNeuron ≫
  • PHP Manual
  • FANNConnection
  • Returns the postions of starting neuron

FANNConnection::getFromNeuron

(PECL fann >= 1.0.0)

FANNConnection::getFromNeuron — Returns the postions of starting neuron

説明

public FANNConnection::getFromNeuron(): int

Returns the postions of starting neuron.

パラメータ

この関数にはパラメータはありません。

戻り値

The postions of starting neuron.


Returns the postions of terminating neuron

  • ≪ FANNConnection::getFromNeuron
  • FANNConnection::getWeight ≫
  • PHP Manual
  • FANNConnection
  • Returns the postions of terminating neuron

FANNConnection::getToNeuron

(PECL fann >= 1.0.0)

FANNConnection::getToNeuron — Returns the postions of terminating neuron

説明

public FANNConnection::getToNeuron(): int

Returns the positions of terminating neuron.

パラメータ

この関数にはパラメータはありません。

戻り値

The postions of terminating neuron.


Returns the connection weight

  • ≪ FANNConnection::getToNeuron
  • FANNConnection::setWeight ≫
  • PHP Manual
  • FANNConnection
  • Returns the connection weight

FANNConnection::getWeight

(PECL fann >= 1.0.0)

FANNConnection::getWeight — Returns the connection weight

説明

public FANNConnection::getWeight(): void

Returns the connection weight.

パラメータ

この関数にはパラメータはありません。

戻り値

The connection weight.


Sets the connections weight

  • ≪ FANNConnection::getWeight
  • Igbinary ≫
  • PHP Manual
  • FANNConnection
  • Sets the connections weight

FANNConnection::setWeight

(PECL fann >= 1.0.0)

FANNConnection::setWeight — Sets the connections weight

説明

public FANNConnection::setWeight(float $weight): void

Sets the connection weight.

This method is different than fann_set_weight(). It does not update the weight value in the network. The network value is updated only after calling fann_set_weight_array().

パラメータ

weight

The connection weight.

戻り値

値を返しません。


Igbinary

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • Igbinary 関数
    • igbinary_serialize — コンパクト、かつ保存可能な値のバイナリ表現を生成する
    • igbinary_unserialize — igbinary_serialize によって保存されたバイナリ表現から、PHP の値を復元する


はじめに

Igbinary は、PHP における標準のシリアライザを置き換えるものです。 処理時間や保存容量を消費してしまう PHP の serialize() で採用されているテキスト表現の代替として、 igbinary はデータ構造をコンパクトなバイナリ形式で保存します。 memcached や APCu、 またはそれと類似したメモリベースのストレージを使う場合、 メモリの節約効果は絶大です。 典型的なケースで、必要なストレージ量は 50% 減ります。 正確な割合は、データに依存します。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Igbinary
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/igbinary.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


実行時設定

php.ini の設定により動作が変化します。

Igbinary 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
igbinary.compact_strings | 1 | INI_ALL |
Igbinary の振る舞いに影響する、セッションの設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
session.save_handler | "files" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

igbinary.compact_strings bool

重複する文字列の圧縮を有効にするか、無効にするかを指定します。 デフォルトは On です。

session.save_handler string

この値を igbinary に設定することで、 セッションハンドラに Igbinary を使うことができます。


Igbinary 関数

目次

  • igbinary_serialize — コンパクト、かつ保存可能な値のバイナリ表現を生成する
  • igbinary_unserialize — igbinary_serialize によって保存されたバイナリ表現から、PHP の値を復元する


コンパクト、かつ保存可能な値のバイナリ表現を生成する

  • ≪ Igbinary 関数
  • igbinary_unserialize ≫
  • PHP Manual
  • Igbinary 関数
  • コンパクト、かつ保存可能な値のバイナリ表現を生成する

igbinary_serialize

(PECL igbinary >= 1.1.1)

igbinary_serialize — コンパクト、かつ保存可能な値のバイナリ表現を生成する

説明

igbinary_serialize(mixed $value): string|false

値の保存可能なバイナリ表現を生成します。

これは、値の型と構造を失うことなく、 PHP の値を渡したり、保存したりする際に役立ちます。

シリアライズ済みの PHP の文字列を再度 PHP の値に戻すには、 igbinary_unserialize() が使えます。

パラメータ

value

シリアライズする値。 igbinary_serialize() は、resource 型やいくつかの object 型を除いた、全ての型を扱えます (下記を参照ください)。 自分自身への参照を含む配列であっても、 igbinary_serialize() でシリアライズできます。 シリアライズされる配列やオブジェクトにおける循環参照も保存されます。 それ以外の参照は失われます。

オブジェクトをシリアライズする場合、 igbinary はメンバ関数 __serialize() または __sleep() をシリアライズする前にコールしようとします。 これにより、オブジェクトはシリアライズされる直前に 最終的なクリーンアップ処理などを行えます。 同じように、 igbinary_unserialize() でオブジェクトを復元する際にも、 __unserialize() または __wakeup() メンバ関数がコールされます。

注意:

オブジェクトの private なメンバは、 メンバの名前の前にクラス名が付加されます。 protected なメンバは、 メンバ名の前に '*' が付加されます。 これらの先頭に付けられた値は、 シリアライズ/アンシリアライズ 双方の側で、 null バイトとして扱われます。

戻り値

任意の場所で保存できる value のバイナリストリーム表現を含む、 文字列を返します。

ここで返される値は、バイト値を含みうるバイナリ文字列であり、 そういうものとして扱う必要があります。 たとえば、igbinary_serialize() の出力は、データベースでは一般的に CHAR や TEXT ではなく、 BLOB フィールドに保存する必要があります。

例

例1 igbinary_serialize() の例

<?php
$ser = igbinary_serialize(['test', 'test']);
echo urlencode($ser), "\n";
var_export(igbinary_unserialize($ser));
?>

上の例の出力は以下となります。

%00%00%00%02%14%02%06%00%11%04test%06%01%0E%00
array (
  0 => 'test',
  1 => 'test',
)

注意

注意:

多くの組み込みの PHP オブジェクトは、 シリアライズできないことに注意して下さい。 しかし、Serializable インターフェイスや、 __serialize()/__unserialize()、 マジックメソッド __sleep()/__wakeup() を実装したオブジェクトは、 シリアライズ可能です。 内部クラスがこれらの要件を満たさない場合、 どんなシリアライザであっても信頼できるやり方でシリアライズできません。

上記のルールには、歴史的な例外が存在します。 内部オブジェクトによっては、 それらのインターフェイスやマジックメソッドがなくても、 シリアライズできるものがありました。

参考

  • serialize() - 値の保存可能な表現を生成する
  • igbinary_unserialize() - igbinary_serialize によって保存されたバイナリ表現から、PHP の値を復元する
  • var_export() - 変数の文字列表現を出力または返す
  • json_encode() - 値を JSON 形式にして返す
  • オブジェクトのシリアライズ
  • __sleep()
  • __wakeup()
  • __serialize()
  • __unserialize()


igbinary_serialize によって保存されたバイナリ表現から、PHP の値を復元する

  • ≪ igbinary_serialize
  • JSON ≫
  • PHP Manual
  • Igbinary 関数
  • igbinary_serialize によって保存されたバイナリ表現から、PHP の値を復元する

igbinary_unserialize

(PECL igbinary >= 1.1.1)

igbinary_unserialize — igbinary_serialize() によって保存されたバイナリ表現から、PHP の値を復元する

説明

igbinary_unserialize(string $str): mixed

igbinary_unserialize() は、 igbinary_serialize() によってシリアライズされた単一の値をとり、 それを PHP の変数に戻します。

警告

信頼できないユーザーからの入力をそのまま igbinary_unserialize() に渡してはいけません。 アンシリアライズの時には、 オブジェクトのインスタンス生成やオートローディングなどで コードが実行されることがあり、 悪意のあるユーザーがこれを悪用するかもしれないからです。 シリアル化したデータをユーザーに渡す必要がある場合は、 安全で標準的なデータ交換フォーマットである JSON などを使うようにしましょう。 json_decode() および json_encode() を利用します。

外部で保存されたシリアライズ済みデータを復元する場合、 データの検証に hash_hmac() 関数が使えます。 重要なのは、そのデータを改ざんした者がいないことを保証することです。

警告

igbinary のシリアライズフォーマットでは、 同じ値に対する異なるリファレンスを区別できる方法がありません。 指定された値に対する全ての PHP のリファレンスは、 アンシリアライズされる際に、 同じリファレンスのグループの一部として扱われます。 これは、シリアライズされる際に 異なるリファレンスのグループの一部であったとしても同じです。

パラメータ

str

igbinary_serialize() が生成したシリアライズ済みの値。

もしアンシリアライズする変数がオブジェクトの場合、 オブジェクトが無事再作成された後、igbinary は自動的にメンバ関数 __unserialize() または __wakeup() (存在していれば) をコールしようとします。

注意: unserialize_callback_func ディレクティブ

コールバック関数を設定することが可能です。(不完全な object __PHP_Incomplete_Class を得ることを防ぐため) コールバック関数は、アンシリアライズする際に未定義のクラスをインスタ ンス化する必要がある場合にコールされます。 unserialize_callback_func を定義するためには、 php.ini, ini_set(), .htaccess を使用し てください。未定義のクラスをインスタンス化する度に、コールバック関 数がコールされます。この機能を無効とするには、 単純にこの設定を空にしてください。

戻り値

変換済の値を返します。 値の型は、 bool, int, float, string, array, object, null があり得ます。

渡された文字列が アンシリアライズ できない場合、 false が返されると共に、 E_NOTICE または E_WARNING が発生します。

エラー / 例外

アンシリアライズ を行うハンドラの中で、オブジェクトが Throwable をスローする可能性があります。

注意

警告

エラーが発生したり、 null や false をシリアライズしたものを アンシリアライズ しようとした場合、 null または false を返します。 この特殊ケースについては、 str を igbinary_serialize(null) や igbinary_serialize(false) と比較したり、 発生した E_NOTICE をキャッチすることで扱えます。

参考

  • unserialize() - 保存用表現から PHP の値を生成する
  • json_encode() - 値を JSON 形式にして返す
  • json_decode() - JSON 文字列をデコードする
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • igbinary_serialize() - コンパクト、かつ保存可能な値のバイナリ表現を生成する
  • クラスのオートローディング
  • unserialize_callback_func
  • __wakeup()
  • __serialize()
  • __unserialize()


JavaScript Object Notation

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • JsonException — JsonException クラス
  • JsonSerializable — JsonSerializable インターフェイス
    • JsonSerializable::jsonSerialize — JSON にシリアライズしたいデータを指定する
  • JSON 関数
    • json_decode — JSON 文字列をデコードする
    • json_encode — 値を JSON 形式にして返す
    • json_last_error — 直近に発生したエラーを返す
    • json_last_error_msg — 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
    • json_validate — 文字列が有効なJSONかどうかを調べる


はじめに

この拡張モジュールは、» JavaScript Object Notation (JSON) というデータ交換形式を実装したものです。 PHP には、PHP のためだけに特別に書かれた JSON パーサが同梱されており、 PHPライセンスのもとでライセンスされています。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • JSON
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

PHP コアに含まれるため、 追加のインストール無しで使用できます。


インストール手順

JSON 拡張モジュールは、デフォルトで PHP コアに組み込まれています。

PHP 8.0.0 以降、JSON 拡張モジュールは PHP コアに組み込まれているため、 常に有効になっています。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/json


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

次の定数は、json_last_error() が返したり、 JsonException の code に格納されている エラーの型を表します。

JSON_ERROR_NONE (int)
エラーが発生しませんでした。
JSON_ERROR_DEPTH (int)
スタックの深さが最大に達しました。
JSON_ERROR_STATE_MISMATCH (int)
アンダーフローあるいはモードの不一致が発生しました。
JSON_ERROR_CTRL_CHAR (int)
制御文字エラー。おそらくエンコードが間違っています。
JSON_ERROR_SYNTAX (int)
構文エラー。
JSON_ERROR_UTF8 (int)
正しくエンコードされていないなど、不正な形式の UTF-8 文字。
JSON_ERROR_RECURSION (int)

json_encode() に渡した配列やオブジェクトに再帰参照が含まれており、エンコードできません。 JSON_PARTIAL_OUTPUT_ON_ERROR オプションを指定した場合は、 再帰参照の部分を null にエンコードします。

JSON_ERROR_INF_OR_NAN (int)
json_encode() に渡した値の中に NAN あるいは INF が含まれています。 JSON_PARTIAL_OUTPUT_ON_ERROR オプションを指定した場合は、 これらの特殊な数値を 0 にエンコードします。
JSON_ERROR_UNSUPPORTED_TYPE (int)
json_encode() が対応していない型、たとえば リソース などが渡されました。 JSON_PARTIAL_OUTPUT_ON_ERROR オプションを指定した場合は、 これらを null にエンコードします。
JSON_ERROR_INVALID_PROPERTY_NAME (int)
JSON オブジェクトを PHP オブジェクトにデコードする際、 json_decode() に渡された文字列に、 \u0000 から始まるキーが含まれていました。
JSON_ERROR_UTF16 (int)
json_decode() に渡された JSON 文字列の中に、 単一の、ペアになっていない UTF-16 のサロゲートコードポイントが含まれていました。

次の定数は、 json_decode() のオプションとして 組み合わせて使用します。

JSON_BIGINT_AS_STRING (int)
巨大な整数値を文字列としてデコードします。
JSON_OBJECT_AS_ARRAY (int)
JSON オブジェクトを PHP の配列としてデコードします。 このオプションは json_decode() の第二引数を true に設定して呼び出すことで、自動的に設定できます。

次の定数は、 json_encode() のオプションとして組み合わせて使用します。

JSON_HEX_TAG (int)
すべての < および > をそれぞれ \u003C および \u003E に変換します。
JSON_HEX_AMP (int)
すべての & を \u0026 に変換します。
JSON_HEX_APOS (int)
すべての ' を \u0027 に変換します。
JSON_HEX_QUOT (int)
すべての " を \u0022 に変換します。
JSON_FORCE_OBJECT (int)
非連想配列を使用した場合に、配列ではなくオブジェクトを出力します。 出力を受け取る側がオブジェクトを期待しており、配列が空っぽである場合などに特に便利です。
JSON_NUMERIC_CHECK (int)
数値形式の文字列を数値としてエンコードします。
JSON_PRETTY_PRINT (int)
返される結果の書式を、スペースを使って整えます。
JSON_UNESCAPED_SLASHES (int)
/ をエスケープしません。
JSON_UNESCAPED_UNICODE (int)
マルチバイト Unicode 文字をそのままの形式で扱います (デフォルトでは \uXXXX にエスケープします)。
JSON_PARTIAL_OUTPUT_ON_ERROR (int)
エンコード不可能な値は代替値に置き換え、処理を続行します。
JSON_PRESERVE_ZERO_FRACTION (int)
float 型の値を常に float 値としてエンコードするようにします。
JSON_UNESCAPED_LINE_TERMINATORS (int)
JSON_UNESCAPED_UNICODE が指定されると、 行の終端をエスケープされないままにします。 PHP 7.1 より前のバージョンでは、 この定数がなくてもそういう振る舞いをしていました。 PHP 7.1.0 以降で使用可能です。

次の定数は、 json_decode() および json_encode() のオプションとして組み合わせて使用します。

JSON_INVALID_UTF8_IGNORE (int)
不正な UTF-8 の文字を無視します。 PHP 7.2.0 以降で使用可能です。
JSON_INVALID_UTF8_SUBSTITUTE (int)
不正な UTF-8 の文字を、\0xfffd に変換します。 (Unicode の 'REPLACEMENT CHARACTER') PHP 7.2.0 以降で使用可能です。
JSON_THROW_ON_ERROR (int)
エラーが起きた場合、 json_last_error() や json_last_error_msg() 関数で収集される、 グローバルなエラー状態を設定するかわりに、 JsonException をスローします。 JSON_PARTIAL_OUTPUT_ON_ERROR は JSON_THROW_ON_ERROR よりも優先します。 PHP 7.3.0 以降で使用可能です。
JSON_ERROR_NON_BACKED_ENUM (int)
json_encode() に渡される値のうち、 シリアライズできなかった Backed Enum でない値を含んでいることを示します。 PHP 8.1.0 以降で使用可能です。


JsonException クラス

(PHP 7 >= 7.3.0, PHP 8)

はじめに

JSON_THROW_ON_ERROR オプションが json_encode() や json_decode() に設定されていた場合にスローされる例外です。 code には、エラーのタイプを含みます。 あり得る code の値については、 json_last_error() 関数を参照ください。

クラス概要

class JsonException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


JsonSerializable インターフェイス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

JsonSerializable を実装したオブジェクトは、 json_encode() を呼んで処理されたときの自身の JSON 表現をカスタマイズできます。

インターフェイス概要

interface JsonSerializable {
/* メソッド */
public jsonSerialize(): mixed
}

目次

  • JsonSerializable::jsonSerialize — JSON にシリアライズしたいデータを指定する


JSON にシリアライズしたいデータを指定する

  • ≪ JsonSerializable
  • JSON 関数 ≫
  • PHP Manual
  • JsonSerializable
  • JSON にシリアライズしたいデータを指定する

JsonSerializable::jsonSerialize

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

JsonSerializable::jsonSerialize — JSON にシリアライズしたいデータを指定する

説明

public JsonSerializable::jsonSerialize(): mixed

オブジェクトをシリアライズして、 json_encode() がネイティブにシリアライズできる値にします。

パラメータ

この関数にはパラメータはありません。

戻り値

json_encode() でシリアライズするデータを返します。 resource 型以外の任意の型になります。

例

例1 JsonSerializable::jsonSerialize() で配列を返す例

<?php
class ArrayValue implements JsonSerializable {
private $array;
public function __construct(array $array) {
$this->array = $array;
}

public function jsonSerialize(): mixed {
return $this->array;
}
}

$array = [1, 2, 3];
echo json_encode(new ArrayValue($array), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

[
    1,
    2,
    3
]

例2 JsonSerializable::jsonSerialize() で連想配列を返す例

<?php
class ArrayValue implements JsonSerializable {
private $array;
public function __construct(array $array) {
$this->array = $array;
}

public function jsonSerialize() {
return $this->array;
}
}

$array = ['foo' => 'bar', 'quux' => 'baz'];
echo json_encode(new ArrayValue($array), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

{
    "foo": "bar",
    "quux": "baz"
}

例3 JsonSerializable::jsonSerialize() で整数値を返す例

<?php
class IntegerValue implements JsonSerializable {
private $number;
public function __construct($number) {
$this->number = (int) $number;
}

public function jsonSerialize() {
return $this->number;
}
}

echo json_encode(new IntegerValue(1), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

1

例4 JsonSerializable::jsonSerialize() で文字列を返す例

<?php
class StringValue implements JsonSerializable {
private $string;
public function __construct($string) {
$this->string = (string) $string;
}

public function jsonSerialize() {
return $this->string;
}
}

echo json_encode(new StringValue('Hello!'), JSON_PRETTY_PRINT);
?>

上の例の出力は以下となります。

"Hello!"


JSON 関数

目次

  • json_decode — JSON 文字列をデコードする
  • json_encode — 値を JSON 形式にして返す
  • json_last_error — 直近に発生したエラーを返す
  • json_last_error_msg — 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
  • json_validate — 文字列が有効なJSONかどうかを調べる


JSON 文字列をデコードする

  • ≪ JSON 関数
  • json_encode ≫
  • PHP Manual
  • JSON 関数
  • JSON 文字列をデコードする

json_decode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_decode — JSON 文字列をデコードする

説明

json_decode(
string $json,
?bool $associative = null,
int $depth = 512,
int $flags = 0
): mixed

JSON エンコードされた文字列を受け取り、それを PHP の値に変換します。

パラメータ

json

デコード対象となる json 文字列。

この関数は UTF-8 でエンコードされた文字列でのみ動作します。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。

associative

true の場合、返されるオブジェクトは連想配列形式になります。 false の場合、返されるオブジェクトは object になります。 null の場合、返されるオブジェクトは flags に JSON_OBJECT_AS_ARRAY が設定されているかどうかによって、 連想配列形式か object かが変化します。

depth

デコードするデータのネストの深さの最大値。 この値は 0 より大きく、 2147483647 以下でなければいけません。

flags

JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_OBJECT_AS_ARRAY, JSON_THROW_ON_ERROR. からなるビットマスク。 各定数の意味については JSON 定数のページ に説明があります。

戻り値

json でエンコードされたデータを、適切な PHP の型として返します。 クォートされていない true、false および null はそれぞれ true、false そして null として返されます。 json のデコードに失敗したり エンコードされたデータがネストの最大値を超えているなどの場合、null を返します。

エラー / 例外

depth が範囲外の値の場合、 PHP 8.0.0 以降では ValueError がスローされます。 それより前のバージョンでは、 E_WARNING レベルの警告が発生していました。

変更履歴

バージョン | 説明
7.3.0 | flags パラメータに JSON_THROW_ON_ERROR が追加されました。
7.2.0 | associative は nullable になりました。
7.2.0 | flags パラメータに JSON_INVALID_UTF8_IGNORE および JSON_INVALID_UTF8_SUBSTITUTE が追加されました。
7.1.0 | 空の JSONキー ("") は、 _empty_ というキーではなく、 空のオブジェクトプロパティにエンコードされるようになりました。

例

例1 json_decode() の例

<?php
$json = '{"a":1,"b":2,"c":3,"d":4,"e":5}';

var_dump(json_decode($json));
var_dump(json_decode($json, true));

?>

上の例の出力は以下となります。

object(stdClass)#1 (5) {
    ["a"] => int(1)
    ["b"] => int(2)
    ["c"] => int(3)
    ["d"] => int(4)
    ["e"] => int(5)
}

array(5) {
    ["a"] => int(1)
    ["b"] => int(2)
    ["c"] => int(3)
    ["d"] => int(4)
    ["e"] => int(5)
}

例2 無効なオブジェクトプロパティへのアクセス

オブジェクトの中にある、 PHP の命名規約では使えない文字 (ハイフンなど) を含む要素にアクセスするには、 要素名を波括弧とアポストロフィで囲みます。

<?php

$json = '{"foo-bar": 12345}';

$obj = json_decode($json);
print $obj->{'foo-bar'}; // 12345

?>

例3 json_decode() でのありがちな間違い

<?php

// 以下の文字列は JavaScript としては有効ですが JSON としては無効です

// 名前と値はダブルクォートで囲む必要があります。
// シングルクォートは使えません
$bad_json = "{ 'bar': 'baz' }";
json_decode($bad_json); // null

// 名前をダブルクォートで囲まなければなりません
$bad_json = '{ bar: "baz" }';
json_decode($bad_json); // null

// 最後にカンマをつけてはいけません
$bad_json = '{ bar: "baz", }';
json_decode($bad_json); // null

?>

例4 depth エラー

<?php
// データをエンコードします。ネストの深さは4です (array -> array -> array -> string)
$json = json_encode(
array(
1 => array(
'English' => array(
'One',
'January'
),
'French' => array(
'Une',
'Janvier'
)
)
)
);

// さまざまな深さのエラーを表示します
var_dump(json_decode($json, true, 4));
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;

var_dump(json_decode($json, true, 3));
echo 'Last error: ', json_last_error_msg(), PHP_EOL, PHP_EOL;
?>

上の例の出力は以下となります。

array(1) {
  [1]=>
  array(2) {
    ["English"]=>
    array(2) {
      [0]=>
      string(3) "One"
      [1]=>
      string(7) "January"
    }
    ["French"]=>
    array(2) {
      [0]=>
      string(3) "Une"
      [1]=>
      string(7) "Janvier"
    }
  }
}
Last error: No error

NULL
Last error: Maximum stack depth exceeded

例5 json_decode() で大きな整数値を扱う例

<?php
$json = '{"number": 12345678901234567890}';

var_dump(json_decode($json));
var_dump(json_decode($json, false, 512, JSON_BIGINT_AS_STRING));

?>

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["number"]=>
  float(1.2345678901235E+19)
}
object(stdClass)#1 (1) {
  ["number"]=>
  string(20) "12345678901234567890"
}

注意

注意:

JSON の仕様は JavaScript そのものではなく、JavaScript のサブセットです。

注意:

デコードに失敗した場合は、json_last_error() を使用すればエラーの正確な状態を知ることができます。

参考

  • json_encode() - 値を JSON 形式にして返す
  • json_last_error() - 直近に発生したエラーを返す
  • json_last_error_msg() - 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す


値を JSON 形式にして返す

  • ≪ json_decode
  • json_last_error ≫
  • PHP Manual
  • JSON 関数
  • 値を JSON 形式にして返す

json_encode

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL json >= 1.2.0)

json_encode — 値を JSON 形式にして返す

説明

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

与えられた value を JSON 形式にした文字列を返します。 引数が配列やオブジェクトの場合は、JSON 形式に再帰的に変換されます。

変換される値がオブジェクトの場合、 デフォルトでは public としてアクセス可能なプロパティのみが含まれます。 それ以外のやり方で、値を JSON 形式に変換する方法は、 JsonSerializable を実装することで制御できます。

エンコーディングは、flags の指定によって影響を受けます。 さらに、浮動小数点のエンコーディングは、 serialize_precision の値によっても影響を受けます。

パラメータ

value

エンコードする値。 リソース 型以外の任意の型を指定できます。

すべての文字列データは、UTF-8 エンコードされていなければいけません。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。

flags

JSON_FORCE_OBJECT, JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_INVALID_UTF8_IGNORE, JSON_INVALID_UTF8_SUBSTITUTE, JSON_NUMERIC_CHECK, JSON_PARTIAL_OUTPUT_ON_ERROR, JSON_PRESERVE_ZERO_FRACTION, JSON_PRETTY_PRINT, JSON_UNESCAPED_LINE_TERMINATORS, JSON_UNESCAPED_SLASHES, JSON_UNESCAPED_UNICODE, JSON_THROW_ON_ERROR からなるビットマスク。 各定数の意味については JSON 定数のページ に説明があります。

depth

最大の深さを設定します。正の数でなければいけません。

戻り値

成功した場合に、JSON エンコードされた文字列を返します。 失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | flags パラメータに JSON_THROW_ON_ERROR が追加されました。
7.2.0 | flags パラメータに JSON_INVALID_UTF8_IGNORE と JSON_INVALID_UTF8_SUBSTITUTE が追加されました。
7.1.0 | flags パラメータに JSON_UNESCAPED_LINE_TERMINATORS が追加されました。
7.1.0 | float 値をエンコードする際に、 precision ではなく serialize_precision を使うようになりました。

例

例1 json_encode() の例

<?php
$arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5);

echo json_encode($arr);
?>

上の例の出力は以下となります。

{"a":1,"b":2,"c":3,"d":4,"e":5}

例2 json_encode() で、利用中のいくつかのフラグを表示する例

<?php
$a = array('<foo>',"'bar'",'"baz"','&blong&', "\xc3\xa9");

echo "Normal: ", json_encode($a), "\n";
echo "Tags: ", json_encode($a, JSON_HEX_TAG), "\n";
echo "Apos: ", json_encode($a, JSON_HEX_APOS), "\n";
echo "Quot: ", json_encode($a, JSON_HEX_QUOT), "\n";
echo "Amp: ", json_encode($a, JSON_HEX_AMP), "\n";
echo "Unicode: ", json_encode($a, JSON_UNESCAPED_UNICODE), "\n";
echo "All: ", json_encode($a, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE), "\n\n";

$b = array();

echo "Empty array output as array: ", json_encode($b), "\n";
echo "Empty array output as object: ", json_encode($b, JSON_FORCE_OBJECT), "\n\n";

$c = array(array(1,2,3));

echo "Non-associative array output as array: ", json_encode($c), "\n";
echo "Non-associative array output as object: ", json_encode($c, JSON_FORCE_OBJECT), "\n\n";

$d = array('foo' => 'bar', 'baz' => 'long');

echo "Associative array always output as object: ", json_encode($d), "\n";
echo "Associative array always output as object: ", json_encode($d, JSON_FORCE_OBJECT), "\n\n";
?>

上の例の出力は以下となります。

Normal: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Tags: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Apos: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Quot: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Amp: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Unicode: ["<foo>","'bar'","\"baz\"","&blong&","e"]
All: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","e"]

Empty array output as array: []
Empty array output as object: {}

Non-associative array output as array: [[1,2,3]]
Non-associative array output as object: {"0":{"0":1,"1":2,"2":3}}

Associative array always output as object: {"foo":"bar","baz":"long"}
Associative array always output as object: {"foo":"bar","baz":"long"}

例3 JSON_NUMERIC_CHECK の例

<?php
echo "Strings representing numbers automatically turned into numbers".PHP_EOL;
$numbers = array('+123123', '-123123', '1.2e3', '0.00001');
var_dump(
$numbers,
json_encode($numbers, JSON_NUMERIC_CHECK)
);
echo "Strings containing improperly formatted numbers".PHP_EOL;
$strings = array('+a33123456789', 'a123');
var_dump(
$strings,
json_encode($strings, JSON_NUMERIC_CHECK)
);
?>

上の例の出力は、 たとえば以下のようになります。

Strings representing numbers automatically turned into numbers
array(4) {
  [0]=>
  string(7) "+123123"
  [1]=>
  string(7) "-123123"
  [2]=>
  string(5) "1.2e3"
  [3]=>
  string(7) "0.00001"
}
string(28) "[123123,-123123,1200,1.0e-5]"
Strings containing improperly formatted numbers
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

例4 シーケンシャルな配列とそうでない配列の例

<?php
echo "Sequential array".PHP_EOL;
$sequential = array("foo", "bar", "baz", "blong");
var_dump(
$sequential,
json_encode($sequential)
);

echo PHP_EOL."Non-sequential array".PHP_EOL;
$nonsequential = array(1=>"foo", 2=>"bar", 3=>"baz", 4=>"blong");
var_dump(
$nonsequential,
json_encode($nonsequential)
);

echo PHP_EOL."Sequential array with one key unset".PHP_EOL;
unset($sequential[1]);
var_dump(
$sequential,
json_encode($sequential)
);
?>

上の例の出力は以下となります。

Sequential array
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(27) "["foo","bar","baz","blong"]"

Non-sequential array
array(4) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(3) "baz"
  [4]=>
  string(5) "blong"
}
string(43) "{"1":"foo","2":"bar","3":"baz","4":"blong"}"

Sequential array with one key unset
array(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

例5 JSON_PRESERVE_ZERO_FRACTION の例

<?php
var_dump(json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));
?>

上の例の出力は以下となります。

string(4) "12.0"
string(2) "12"

注意

注意:

エンコードに失敗した場合は、json_last_error() を使ってエラーの内容を調べることができます。

注意:

配列をエンコードする場合、もし配列のキーが 0 からはじまる連続した数値でなければ、 すべてのキーを文字列としてエンコードします。 そして、個々のキー/値のペアを明示的に指定します。

注意:

JSON エンコーダーのリファレンス実装と同様、 string や int、 float そして bool を入力として渡したときに json_encode() が生成する JSON はシンプルな値 (オブジェクトでもないし配列でもないもの) となります。 大半のエンコーダーはこういった値を妥当な JSON として扱いますが、中にはそうでないものもあります。 そのため、現時点ではこの仕様は不明瞭です。

要するに、json_encode() で生成した JSON が、あなたの使おうとしているデコーダーでデコードできるかどうかを常に確認する必要があるということです。

参考

  • JsonSerializable
  • json_decode() - JSON 文字列をデコードする
  • json_last_error() - 直近に発生したエラーを返す
  • json_last_error_msg() - 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
  • serialize() - 値の保存可能な表現を生成する


直近に発生したエラーを返す

  • ≪ json_encode
  • json_last_error_msg ≫
  • PHP Manual
  • JSON 関数
  • 直近に発生したエラーを返す

json_last_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

json_last_error — 直近に発生したエラーを返す

説明

json_last_error(): int

JSON_THROW_ON_ERROR を指定していなかった場合に、 直近の JSON エンコード/デコード処理中に発生したエラー (もし存在すれば) を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

整数値を返します。これは、次の定数のいずれかとなります。

JSON error codes
定数 | 意味 | 使用可能
JSON_ERROR_NONE | エラーは発生しませんでした |
JSON_ERROR_DEPTH | スタックの深さの最大値を超えました |
JSON_ERROR_STATE_MISMATCH | JSON の形式が無効、あるいは壊れています |
JSON_ERROR_CTRL_CHAR | 制御文字エラー。おそらくエンコーディングが違います |
JSON_ERROR_SYNTAX | 構文エラー |
JSON_ERROR_UTF8 | 正しくエンコードされていないなど、不正な形式の UTF-8 文字 |
JSON_ERROR_RECURSION | エンコード対象の値に再帰参照が含まれています |
JSON_ERROR_INF_OR_NAN | エンコード対象の値に NAN あるいは INF が含まれています。 |
JSON_ERROR_UNSUPPORTED_TYPE | エンコード不可能な型の値が渡されました |
JSON_ERROR_INVALID_PROPERTY_NAME | エンコードできないプロパティ名が渡されました |
JSON_ERROR_UTF16 | おそらく正しくエンコードされていない、不正な UTF-16 文字 |

例

例1 json_last_error() の例

<?php
// 正しい json 文字列
$json[] = '{"Organization": "PHP Documentation Team"}';

// 間違った json 文字列で、構文エラーとなります
// ここでは、クォートに " ではなく ' を使用しています
$json[] = "{'Organization': 'PHP Documentation Team'}";

foreach ($json as $string) {
echo 'Decoding: ' . $string;
json_decode($string);

switch (json_last_error()) {
case JSON_ERROR_NONE:
echo ' - No errors';
break;
case JSON_ERROR_DEPTH:
echo ' - Maximum stack depth exceeded';
break;
case JSON_ERROR_STATE_MISMATCH:
echo ' - Underflow or the modes mismatch';
break;
case JSON_ERROR_CTRL_CHAR:
echo ' - Unexpected control character found';
break;
case JSON_ERROR_SYNTAX:
echo ' - Syntax error, malformed JSON';
break;
case JSON_ERROR_UTF8:
echo ' - Malformed UTF-8 characters, possibly incorrectly encoded';
break;
default:
echo ' - Unknown error';
break;
}

echo PHP_EOL;
}
?>

上の例の出力は以下となります。

Decoding: {"Organization": "PHP Documentation Team"} - No errors
Decoding: {'Organization': 'PHP Documentation Team'} - Syntax error, malformed JSON

例2 json_last_error() と json_encode() の組み合わせ

<?php
// 無効な UTF8 シーケンス
$text = "\xB1\x31";

$json = json_encode($text);
$error = json_last_error();

var_dump($json, $error === JSON_ERROR_UTF8);
?>

上の例の出力は以下となります。

string(4) "null"
bool(true)

例3 json_last_error() と JSON_THROW_ON_ERROR の組み合わせ

<?php
// JSON_ERROR_UTF8 が発生する、不正なUTF8シーケンス
json_encode("\xB1\x31");

// 次の文字列は、JSON error が発生しない
json_encode('okay', JSON_THROW_ON_ERROR);

// グローバルなエラー状態は、直前の json_encode() によって変更されない
var_dump(json_last_error() === JSON_ERROR_UTF8);
?>

上の例の出力は以下となります。

bool(true)

参考

  • json_last_error_msg() - 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
  • json_decode() - JSON 文字列をデコードする
  • json_encode() - 値を JSON 形式にして返す


直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す

  • ≪ json_last_error
  • json_validate ≫
  • PHP Manual
  • JSON 関数
  • 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す

json_last_error_msg

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

json_last_error_msg — 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す

説明

json_last_error_msg(): string

呼び出しで JSON_THROW_ON_ERROR を指定しなかった場合、 直近の json_encode() または json_decode() 呼び出しの エラー文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にエラーメッセージ、エラーが発生しなかった場合は "No error"

参考

  • json_last_error() - 直近に発生したエラーを返す


文字列が有効なJSONかどうかを調べる

  • ≪ json_last_error_msg
  • Simdjson ≫
  • PHP Manual
  • JSON 関数
  • 文字列が有効なJSONかどうかを調べる

json_validate

(PHP 8 >= 8.3.0)

json_validate — 文字列が有効なJSONかどうかを調べる

説明

json_validate(string $json, int $depth = 512, int $flags = 0): bool

指定された文字列が、文法的に有効なJSONかどうかを返します。 json_validate() が true を返す場合、 同じ depth と flags を指定して json_decode() を実行してもデコードは成功します。

json_validate() が false を返す場合、
原因は json_last_error() と
json_last_error_msg() を使って取得できます。

デコードされたJSONペイロードを使わない場合、 json_validate() は json_decode() よりもメモリ使用量が少なくなります。 なぜなら、ペイロードを含む配列やオブジェクト構造を組み立てる必要がないからです。

警告

  json_decode() の直前に json_validate() をコールすると、 文字列を不必要に2回パースすることになります。 なぜなら、json_decode() はデコードしている間に暗黙のうちに文字列を検証するからです。

よって json_validate() は、JSON のペイロードをすぐに使わない場合、かつ有効なJSON文字列かどうかを知る必要がある場合にのみ使うべきです。

パラメータ

json

検証する文字列

この関数は、UTF-8 でエンコードされた文字列でのみ動作します。

注意:

PHP の実装は、 » RFC 7159 の JSON のスーパーセットです。

depth

デコードされるネスト構造の深さの最大値。 この値は 0 より大きく、 2147483647 以下でなければいけません。

flags

現状は、JSON_INVALID_UTF8_IGNORE のみを受け入れます。

戻り値

指定された文字列が文法的に有効なJSONの場合、true を返します。 そうでない場合、false を返します。

エラー / 例外

depth が許可された範囲外の値の場合、 ValueError がスローされます。

flags が有効なフラグでない場合、 ValueError がスローされます。

例

例1 json_validate() の例

<?php
var_dump(json_validate('{ "test": { "foo": "bar" } }'));
var_dump(json_validate('{ "": "": "" } }'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • json_decode() - JSON 文字列をデコードする
  • json_last_error() - 直近に発生したエラーを返す
  • json_last_error_msg() - 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す


Simdjson

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
  • Simdjson 関数
    • simdjson_decode — Decodes a JSON string
    • simdjson_is_valid — Check if a JSON string is valid
    • simdjson_key_count — Returns the value at a JSON pointer.
    • simdjson_key_exists — Check if the JSON contains the value referred to by a JSON pointer.
    • simdjson_key_value — Decodes the value of a JSON string located at the requested JSON pointer.
  • SimdJsonException — The SimdJsonException class
  • SimdJsonValueError — The SimdJsonValueError class


はじめに

Provides faster JSON decoding through simdjson bindings for PHP (Single Instruction, Multiple Data)


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Simdjson
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/simdjson.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SIMDJSON_ERR_CAPACITY (int)
This parser can't support a document that big. Thrown when parsing a JSON string that is over 4GiB long.
SIMDJSON_ERR_TAPE_ERROR (int)
The JSON document has an improper structure: missing or superfluous commas, braces, missing keys, etc.
SIMDJSON_ERR_DEPTH_ERROR (int)
The JSON document was too deep (too many nested objects and arrays)
SIMDJSON_ERR_STRING_ERROR (int)
Problem while parsing a string
SIMDJSON_ERR_T_ATOM_ERROR (int)
Problem while parsing an atom starting with the letter 't'
SIMDJSON_ERR_F_ATOM_ERROR (int)
Problem while parsing an atom starting with the letter 'f'
SIMDJSON_ERR_N_ATOM_ERROR (int)
Problem while parsing an atom starting with the letter 'n'
SIMDJSON_ERR_NUMBER_ERROR (int)
Problem while parsing a number
SIMDJSON_ERR_UTF8_ERROR (int)
The input is not valid UTF-8
SIMDJSON_ERR_UNINITIALIZED (int)
The parser used by simdjson is uninitialized. Should not happen.
SIMDJSON_ERR_EMPTY (int)
Empty: no JSON found
SIMDJSON_ERR_UNESCAPED_CHARS (int)
Within strings, some characters must be escaped, we found unescaped characters
SIMDJSON_ERR_UNCLOSED_STRING (int)
A string is opened, but never closed.
SIMDJSON_ERR_UNSUPPORTED_ARCHITECTURE (int)
simdjson does not have an implementation supported by this CPU architecture (perhaps it's a non-SIMD CPU?).
SIMDJSON_ERR_INCORRECT_TYPE (int)
Should not happen.
SIMDJSON_ERR_NUMBER_OUT_OF_RANGE (int)
The JSON number is too large or too small to fit within the requested type. Note that the C simdjson library is a fork and this error is ignored to match php's handling of JSON numbers that are too large or too small.
SIMDJSON_ERR_INDEX_OUT_OF_BOUNDS (int)
Should not happen.
SIMDJSON_ERR_NO_SUCH_FIELD (int)
Should not happen.
SIMDJSON_ERR_IO_ERROR (int)
Should not happen.
SIMDJSON_ERR_INVALID_JSON_POINTER (int)
Invalid JSON pointer syntax in simdjson_key_value() and other functions accepting a JSON pointer $key.
SIMDJSON_ERR_INVALID_URI_FRAGMENT (int)
Invalid URI fragment syntax.
SIMDJSON_ERR_UNEXPECTED_ERROR (int)
Unexpected error, consider reporting this problem as you may have found a bug in the simdjson PECL
SIMDJSON_ERR_PARSER_IN_USE (int)
Should not happen.
SIMDJSON_ERR_OUT_OF_ORDER_ITERATION (int)
Should not happen.
SIMDJSON_ERR_INSUFFICIENT_PADDING (int)
Should not happen.
SIMDJSON_ERR_INCOMPLETE_ARRAY_OR_OBJECT (int)
JSON document ended early in the middle of an object or array.
SIMDJSON_ERR_SCALAR_DOCUMENT_AS_VALUE (int)
Should not happen.
SIMDJSON_ERR_OUT_OF_BOUNDS (int)
Attempted to access location outside of document.
SIMDJSON_ERR_TRAILING_CONTENT (int)
SIMDJSON_ERR_KEY_COUNT_NOT_COUNTABLE (int)
SIMDJSON_ERR_INVALID_PROPERTY (int)
Invalid property name for an stdClass when decoding a value with simdjson_decode() or simdjson_key_value()


Simdjson 関数

目次

  • simdjson_decode — Decodes a JSON string
  • simdjson_is_valid — Check if a JSON string is valid
  • simdjson_key_count — Returns the value at a JSON pointer.
  • simdjson_key_exists — Check if the JSON contains the value referred to by a JSON pointer.
  • simdjson_key_value — Decodes the value of a JSON string located at the requested JSON pointer.


Decodes a JSON string

  • ≪ Simdjson 関数
  • simdjson_is_valid ≫
  • PHP Manual
  • Simdjson 関数
  • Decodes a JSON string

simdjson_decode

(PECL simdjson >= 2.0.0)

simdjson_decode — Decodes a JSON string

説明

simdjson_decode(string $json, bool $associative = false, int $depth = 512): mixed

Takes a JSON encoded string and converts it into a PHP value. This uses a faster Simultaneous Instruction, Multiple Data implementation than json_decode() when it is supported by the computer architecture.

パラメータ

json

The json string being decoded.

This function only works with UTF-8 encoded strings.

This function parses valid inputs which json_decode() can decode, provided that they are less than 4 GiB long.

associative

When true, JSON objects will be returned as associative arrays; when false, JSON objects will be returned as objects.

depth

Maximum nesting depth of the structure being decoded. The value must be greater than 0, and less than or equal to 2147483647. Callers should use reasonably small values, because larger depths require more buffer space and will increase the recursion depth, unlike the current json_decode() implementation.

戻り値

Returns the value encoded in json in appropriate PHP type. Values true, false and null are returned as true, false and null respectively.

エラー / 例外

If json is invalid, a SimdJsonException is thrown as of PECL simdjson 2.1.0, while previously, a RuntimeException was thrown.

If depth is outside the allowed range, a SimdJsonValueError is thrown as of PECL simdjson 3.0.0, while previously, an error of level E_WARNING was raised.

例

例1 simdjson_decode() examples

<?php
$json = '{"a":1,"b":2,"c":3}';

var_dump(simdjson_decode($json));
var_dump(simdjson_decode($json, true));

?>

上の例の出力は以下となります。

object(stdClass)#1 (3) {
  ["a"]=>
  int(1)
  ["b"]=>
  int(2)
  ["c"]=>
  int(3)
}
array(3) {
  ["a"]=>
  int(1)
  ["b"]=>
  int(2)
  ["c"]=>
  int(3)
}

例2 Accessing invalid object properties

Accessing elements within an object that contain characters not permitted under PHP's naming convention (e.g. the hyphen) can be accomplished by encapsulating the element name within braces and the apostrophe.

<?php

$json = '{"foo-bar": 12345}';

$obj = simdjson_decode($json);
print $obj->{'foo-bar'}; // 12345

?>

例3 common mistakes using simdjson_decode()

<?php

// the following strings are valid JavaScript but not valid JSON

// the name and value must be enclosed in double quotes
// single quotes are not valid
$bad_json = "{ 'bar': 'baz' }";
simdjson_decode($bad_json); // Throws SimdJsonException

// the name must be enclosed in double quotes
$bad_json = '{ bar: "baz" }';
simdjson_decode($bad_json); // Throws SimdJsonException

// trailing commas are not allowed
$bad_json = '{ bar: "baz", }';
simdjson_decode($bad_json); // Throws SimdJsonException

?>

例4 depth errors

<?php
// Encode some data with a maximum depth of 4
// (array -> array -> array -> string)
$json = json_encode(
[
1 => [
'English' => [
'One',
'January'
],
'French' => [
'Une',
'Janvier'
]
]
]
);

// Show the errors for different depths.
var_dump(simdjson_decode($json, true, 4));
try {
var_dump(simdjson_decode($json, true, 3));
} catch (SimdJsonException $e) {
echo "Caught: ", $e->getMessage(), "\n";
}
?>

上の例の出力は以下となります。

array(1) {
  [1]=>
  array(2) {
    ["English"]=>
    array(2) {
      [0]=>
      string(3) "One"
      [1]=>
      string(7) "January"
    }
    ["French"]=>
    array(2) {
      [0]=>
      string(3) "Une"
      [1]=>
      string(7) "Janvier"
    }
  }
}
Caught: The JSON document was too deep (too many nested objects and arrays)

例5 simdjson_decode() of large integers

<?php
$json = '{"number": 12345678901234567890}';

var_dump(simdjson_decode($json));

?>

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["number"]=>
  float(1.2345678901235E+19)
}

注意

注意:

The JSON spec is not JavaScript, but a subset of JavaScript.

注意:

In the event of a failure to decode, a SimdJsonException is thrown and SimdJsonException::getCode() and SimdJsonException::getMessage() can be used to determine the exact nature of the error.

参考

  • json_encode() - 値を JSON 形式にして返す
  • json_decode() - JSON 文字列をデコードする


Check if a JSON string is valid

  • ≪ simdjson_decode
  • simdjson_key_count ≫
  • PHP Manual
  • Simdjson 関数
  • Check if a JSON string is valid

simdjson_is_valid

(PECL simdjson >= 2.0.0)

simdjson_is_valid — Check if a JSON string is valid

説明

simdjson_is_valid(string $json = false, int $depth = 512): bool

Takes a JSON encoded string and returns true if it is valid.

パラメータ

json

The json string being validated.

This function only works with UTF-8 encoded strings.

This function validates inputs which json_decode() can decode, provided that they are less than 4 GiB long.

depth

Maximum nesting depth of the structure being validated. The value must be greater than 0, and less than or equal to 2147483647. Callers should use reasonably small values, because larger depths require more buffer space and will increase the recursion depth, unlike the current json_decode() implementation.

戻り値

Returns true if json is a valid JSON string, false otherwise.

エラー / 例外

If json is longer than 4 GiB, a SimdJsonException is thrown as of PECL simdjson 2.1.0, while previously, a RuntimeException was thrown.

If depth is outside the allowed range, a SimdJsonValueError is thrown as of PECL simdjson 3.0.0, while previously, an error of level E_WARNING was raised.

例

例1 simdjson_decode() examples

<?php
$json = '{"a":1,"b":2,"c":3}';
$invalidJson = '{"a":1,"b":2,"c":';

var_dump(simdjson_is_valid($json));
var_dump(simdjson_is_valid($invalidJson));

?>

上の例の出力は以下となります。

bool(true)
bool(false)

例2 depth errors

<?php
// Encode some data with a maximum depth of 4
// (array -> array -> array -> string)
$json = json_encode(
[
1 => [
'English' => [
'One',
'January'
],
'French' => [
'Une',
'Janvier'
]
]
]
);

// Show the errors for different depths.
var_dump(simdjson_is_valid($json, 4));
var_dump(simdjson_is_valid($json, 3));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

注意

注意:

The JSON spec is not JavaScript, but a subset of JavaScript.

注意:

In the event of a failure to decode, a SimdJsonException is thrown and SimdJsonException::getCode() and SimdJsonException::getMessage() can be used to determine the exact nature of the error.

参考

  • json_encode() - 値を JSON 形式にして返す
  • json_decode() - JSON 文字列をデコードする


Returns the value at a JSON pointer.

  • ≪ simdjson_is_valid
  • simdjson_key_exists ≫
  • PHP Manual
  • Simdjson 関数
  • Returns the value at a JSON pointer.

simdjson_key_count

(PECL simdjson >= 2.0.0)

simdjson_key_count — Returns the value at a JSON pointer.

説明

simdjson_key_count(
string $json,
string $key,
int $depth = 512,
bool $throw_if_uncountable = false
): int

Count the number of elements of the object/array found at the requested JSON pointer.

パラメータ

json

The json string being queried.

key

The JSON pointer string.

depth

Maximum nesting depth of the structure being validated. The value must be greater than 0, and less than or equal to 2147483647. Callers should use reasonably small values, because larger depths require more buffer space and will increase the recursion depth, unlike the current json_decode() implementation.

throw_if_uncountable

When true, a SimdJsonException will be thrown instead of returning 0 when the value the JSON pointer points to is neither an object nor an array.

戻り値

Returns an int with the number of elements of the value at the given JSON pointer.


Check if the JSON contains the value referred to by a JSON pointer.

  • ≪ simdjson_key_count
  • simdjson_key_value ≫
  • PHP Manual
  • Simdjson 関数
  • Check if the JSON contains the value referred to by a JSON pointer.

simdjson_key_exists

(PECL simdjson >= 2.0.0)

simdjson_key_exists — Check if the JSON contains the value referred to by a JSON pointer.

説明

simdjson_key_exists(string $json, string $key, int $depth = ?): bool

Count the number of elements of the object/array found at the requested JSON pointer.

パラメータ

json

The json string being queried.

key

The JSON pointer string.

depth

Maximum nesting depth of the structure being validated. The value must be greater than 0, and less than or equal to 2147483647. Callers should use reasonably small values, because larger depths require more buffer space and will increase the recursion depth, unlike the current json_decode() implementation.

throw_if_uncountable

When true, a SimdJsonException will be thrown instead of returning 0 when the value the JSON pointer points to is neither an object nor an array.

戻り値

Returns true if the JSON pointer is valid and refers to a value found within a valid JSON string. Returns false if the JSON is valid but does not contain the JSON pointer.


Decodes the value of a JSON string located at the requested JSON pointer.

  • ≪ simdjson_key_exists
  • SimdJsonException ≫
  • PHP Manual
  • Simdjson 関数
  • Decodes the value of a JSON string located at the requested JSON pointer.

simdjson_key_value

(PECL simdjson >= 2.0.0)

simdjson_key_value — Decodes the value of a JSON string located at the requested JSON pointer.

説明

simdjson_key_value(
string $json,
string $key,
bool $associative = false,
int $depth = 512
): mixed

Decodes and returns the value found at the requested JSON pointer.

パラメータ

json

The json string being queried and decoded.

This function only works with UTF-8 encoded strings.

This function parses valid inputs which json_decode() can decode, provided that they are less than 4 GiB long.

key

The JSON pointer string.

associative

When true, JSON objects will be returned as associative arrays; when false, JSON objects will be returned as objects.

depth

Maximum nesting depth of the structure being decoded. The value must be greater than 0, and less than or equal to 2147483647. Callers should use reasonably small values, because larger depths require more buffer space and will increase the recursion depth, unlike the current json_decode() implementation.

戻り値

Returns the part of the value encoded in json that key refers to in appropriate PHP type. Values true, false and null are returned as true, false and null respectively.

エラー / 例外

If json or key is invalid, or key could not be found within json, a SimdJsonException is thrown as of PECL simdjson 2.1.0, while previously, a RuntimeException was thrown.

If depth is outside the allowed range, a SimdJsonValueError is thrown as of PECL simdjson 3.0.0, while previously, an error of level E_WARNING was raised.

参考

  • json_encode() - 値を JSON 形式にして返す
  • simdjson_decode() - Decodes a JSON string


The SimdJsonException class

(PECL simdjson >= 2.1.0)

はじめに

Exception thrown if simdjson_decode(),
simdjson_key_count(),
simdjson_key_exists(),
or simdjson_key_value().

For possible values see the simdjson error codes constants.

クラス概要

class SimdJsonException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
}


The SimdJsonValueError class

(PECL simdjson >= 3.0.0)

はじめに

A SimdJsonValueError is thrown when the type of an argument to a function from simdjson is correct but the value of it is incorrect. E.g. when the JSON decoding $depth is not positive or the $depth is too large.

クラス概要

class SimdJsonValueError extends ValueError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}

変更履歴

バージョン | 説明
PHP 8.0.0 | SimdJsonValueError extends ValueError now instead of Error.


Lua

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Lua — Lua クラス
    • Lua::assign — PHP 変数を Lua にアサイン
    • Lua::call — Lua 関数を呼び出す
    • Lua::__construct — Lua コンストラクタ
    • Lua::eval — 文字列を Lua コードとして評価
    • Lua::getVersion — getversion 用途
    • Lua::include — Lua スクリプトファイルをパース
    • Lua::registerCallback — PHP 関数を Lua に登録
  • LuaClosure — LuaClosure クラス
    • LuaClosure::__invoke — luaclosure を起動


はじめに

「Lua は、パワフル、高速、軽量かつ組み込み可能なスクリプト言語です。」 この拡張モジュールは、lua インタプリタを組み込み、lua の変数と関数にオブジェクト指向の API を提供します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Lua
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

この拡張モジュールを使うには Lua をインストールする必要があります。 » Lua ホームページ から取得してください。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/lua.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


Lua クラス

(PECL lua >=0.9.0)

はじめに

クラス概要

class Lua {
/* 定数 */
const string LUA_VERSION = Lua 5.1.4;
/* メソッド */
public assign(string $name, string $value): mixed
public call(callable $lua_func, array $args = ?, int $use_self = 0): mixed
public __call(callable $lua_func, array $args = ?, int $use_self = 0): mixed
public __construct(string $lua_script_file = NULL)
public eval(string $statements): mixed
public getVersion(): string
public include(string $file): mixed
public registerCallback(string $name, callable $function): mixed
}

定義済み定数

Lua::LUA_VERSION

目次

  • Lua::assign — PHP 変数を Lua にアサイン
  • Lua::call — Lua 関数を呼び出す
  • Lua::__construct — Lua コンストラクタ
  • Lua::eval — 文字列を Lua コードとして評価
  • Lua::getVersion — getversion 用途
  • Lua::include — Lua スクリプトファイルをパース
  • Lua::registerCallback — PHP 関数を Lua に登録


PHP 変数を Lua にアサイン

  • ≪ Lua
  • Lua::call ≫
  • PHP Manual
  • Lua
  • PHP 変数を Lua にアサイン

Lua::assign

(PECL lua >=0.9.0)

Lua::assign — PHP 変数を Lua にアサイン

説明

public Lua::assign(string $name, string $value): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値

$this、あるいは失敗した場合に null を返します。

例

例1 Lua::assign()の例

<?php
$lua = new Lua();
$lua->assign("php_var", array(1=>1, 2, 3)); //lua table index begin with 1
$lua->eval(<<<CODE
 print(php_var);
CODE
);
?>

上の例の出力は以下となります。

Array
 (
     [1] => 1
     [2] => 2
     [3] => 3
 )


Lua 関数を呼び出す

  • ≪ Lua::assign
  • Lua::__construct ≫
  • PHP Manual
  • Lua
  • Lua 関数を呼び出す

Lua::call

Lua::__call

(PECL lua >=0.9.0)

Lua::call -- Lua::__call — Lua 関数を呼び出す

説明

public Lua::call(callable $lua_func, array $args = ?, int $use_self = 0): mixed
public Lua::__call(callable $lua_func, array $args = ?, int $use_self = 0): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

lua_func

lua での関数名

args

Lua 関数に渡される引数

use_self

self を使うか否か

戻り値

呼び出した関数の結果を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

例

例1 Lua::call()の例

<?php
$lua = new Lua();
$lua->eval(<<<CODE
 function dummy(foo, bar)
print(foo, ",", bar)
end
CODE
);
$lua->call("dummy", array("Lua", "geiliable\n"));
$lua->dummy("Lua", "geiliable"); // __call()
var_dump($lua->call(array("table", "concat"), array(array(1=>1, 2=>2, 3=>3), "-")));
?>

上の例の出力は以下となります。

Lua,geiliable
Lua,geiliable
string(5) "1-2-3"

参考

  • __call()


Lua コンストラクタ

  • ≪ Lua::call
  • Lua::eval ≫
  • PHP Manual
  • Lua
  • Lua コンストラクタ

Lua::__construct

(PECL lua >=0.9.0)

Lua::__construct — Lua コンストラクタ

説明

public Lua::__construct(string $lua_script_file = NULL)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

lua_script_file

戻り値


文字列を Lua コードとして評価

  • ≪ Lua::__construct
  • Lua::getVersion ≫
  • PHP Manual
  • Lua
  • 文字列を Lua コードとして評価

Lua::eval

(PECL lua >=0.9.0)

Lua::eval — 文字列を Lua コードとして評価

説明

public Lua::eval(string $statements): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

statements

戻り値

コードを評価した結果を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

例

例1 Lua::eval()の例

<?php
$lua = new Lua();
$lua->eval(<<<CODE
 print(2);
CODE
);
?>

上の例の出力は以下となります。

2


getversion 用途

  • ≪ Lua::eval
  • Lua::include ≫
  • PHP Manual
  • Lua
  • getversion 用途

Lua::getVersion

(PECL lua >=0.9.0)

Lua::getVersion — getversion 用途

説明

public Lua::getVersion(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

Lua::LUA_VERSION を返します。


Lua スクリプトファイルをパース

  • ≪ Lua::getVersion
  • Lua::registerCallback ≫
  • PHP Manual
  • Lua
  • Lua スクリプトファイルをパース

Lua::include

(PECL lua >=0.9.0)

Lua::include — Lua スクリプトファイルをパース

説明

public Lua::include(string $file): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

file

戻り値

インクルードしたコードの結果を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。


PHP 関数を Lua に登録

  • ≪ Lua::include
  • LuaClosure ≫
  • PHP Manual
  • Lua
  • PHP 関数を Lua に登録

Lua::registerCallback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Lua::registerCallback — PHP 関数を Lua に登録

説明

public Lua::registerCallback(string $name, callable $function): mixed

PHP 関数を Lua に "$name" という関数として登録します。

パラメータ

name

function

有効な PHP 関数コールバック

戻り値

$this を返します。引数が間違っている場合は null、 それ以外のエラーの場合は false を返します。

例

例1 Lua::registerCallback()の例

<?php
$lua = new Lua();
$lua->registerCallback("echo", "var_dump");
$lua->eval(<<<CODE
 echo({1, 2, 3});
CODE
);
?>

上の例の出力は以下となります。

array(3) {
  [1]=>
  float(1)
  [2]=>
  float(2)
  [3]=>
  float(3)
}


LuaClosure クラス

(PECL lua >=0.9.0)

はじめに

LuaClosure は、Lua 関数呼び出しから返されることがありえる LUA_TFUNCTION に対するラッパー・クラスです。

クラス概要

class LuaClosure {
/* メソッド */
public __invoke(mixed ...$args): void
}

目次

  • LuaClosure::__invoke — luaclosure を起動


luaclosure を起動

  • ≪ LuaClosure
  • LuaSandbox ≫
  • PHP Manual
  • LuaClosure
  • luaclosure を起動

LuaClosure::__invoke

(PECL lua >=0.9.0)

LuaClosure::__invoke — luaclosure を起動

説明

public LuaClosure::__invoke(mixed ...$args): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

args

戻り値

例

例1 LuaClosure::__invoke()の例

<?php
$lua = new Lua();
$closure = $lua->eval(<<<CODE
 return (function ()
print("hello world")
end)
CODE
);

$lua->call($closure);
$closure();
?>

上の例の出力は以下となります。

hello worldhello world


LuaSandbox

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Differences from Standard Lua
  • 例
    • Basic usage for LuaSandbox
  • LuaSandbox — The LuaSandbox class
    • LuaSandbox::callFunction — Call a function in a Lua global variable
    • LuaSandbox::disableProfiler — Disable the profiler
    • LuaSandbox::enableProfiler — Enable the profiler.
    • LuaSandbox::getCPUUsage — Fetch the current CPU time usage of the Lua environment
    • LuaSandbox::getMemoryUsage — Fetch the current memory usage of the Lua environment
    • LuaSandbox::getPeakMemoryUsage — Fetch the peak memory usage of the Lua environment
    • LuaSandbox::getProfilerFunctionReport — Fetch profiler data
    • LuaSandbox::getVersionInfo — Return the versions of LuaSandbox and Lua
    • LuaSandbox::loadBinary — Load a precompiled binary chunk into the Lua environment
    • LuaSandbox::loadString — Load Lua code into the Lua environment
    • LuaSandbox::pauseUsageTimer — Pause the CPU usage timer
    • LuaSandbox::registerLibrary — Register a set of PHP functions as a Lua library
    • LuaSandbox::setCPULimit — Set the CPU time limit for the Lua environment
    • LuaSandbox::setMemoryLimit — Set the memory limit for the Lua environment
    • LuaSandbox::unpauseUsageTimer — Unpause the timer paused by LuaSandbox::pauseUsageTimer
    • LuaSandbox::wrapPhpFunction — Wrap a PHP callable in a LuaSandboxFunction
  • LuaSandboxFunction — The LuaSandboxFunction class
    • LuaSandboxFunction::call — Call a Lua function
    • LuaSandboxFunction::__construct — Unused
    • LuaSandboxFunction::dump — Dump the function as a binary blob
  • LuaSandboxError — The LuaSandboxError class
  • LuaSandboxErrorError — The LuaSandboxErrorError class
  • LuaSandboxFatalError — The LuaSandboxFatalError class
  • LuaSandboxMemoryError — The LuaSandboxMemoryError class
  • LuaSandboxRuntimeError — The LuaSandboxRuntimeError class
  • LuaSandboxSyntaxError — The LuaSandboxSyntaxError class
  • LuaSandboxTimeoutError — The LuaSandboxTimeoutError class


はじめに

LuaSandbox is an extension for PHP 7 and PHP 8 to allow safely running untrusted Lua 5.1 code from within PHP.

Differences compared to the Lua extension:

  • LuaSandbox has support for time and memory limits.

  • LuaSandbox provides a default-safe environment for running untrusted code. Stock Lua functions were reviewed for security, and several were patched accordingly.

  • LuaSandbox has a PHP interface which is more complex, precise and powerful, but it is less convenient for developers.

  • LuaSandbox supports only Lua 5.1. It is difficult to change this, because LuaSandbox uses heavily modified Lua standard libraries, and due to the lack of backwards compatibility between major Lua versions. LuaSandbox aims to maximise backwards compatibility with user-supplied scripts.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • LuaSandbox
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

To use this extension, Lua 5.1 will need to be installed, available on the » Lua homepage.

To make full use of the timer features, LuaSandbox should be installed on Linux.

If FreeBSD or Mac OS X is used, only real (wall-clock) time is supported, the functions purporting to return CPU time will actually return wall clock time.

If Windows is used, no timer functions will be supported. The time limits will be inoperable.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/luasandbox.

If the operating system is Debian 10 or later, or Ubuntu 18.04 or later, then LuaSandbox should typically be installed from the package php-luasandbox:

sudo apt-get install php-luasandbox


Differences from Standard Lua

LuaSandbox provides a sandboxed environment which differs in some ways from standard Lua 5.1.

Features that are not available

  • dofile(), loadfile(), and the io package, as they allow direct filesystem access. If needed, filesystem access should be done via PHP callbacks.

  • The package package, including require() and module(), as it depends heavily on direct filesystem access. A pure-Lua rewrite such as that used in the MediaWiki Scribunto extension may be used instead.

  • load() and loadstring(), to allow for static analysis of Lua code.

  • print(), since it outputs to standard output. If needed, output should be done via PHP callbacks.

  • Most of the os package, as it allows manipulation of the process and executing of other processes.

    • os.clock(), os.date(), os.difftime(), and os.time() remain available.

  • Most of the debug package, as it allows manipulation of Lua state and metadata in ways that can break sandboxing.

    • debug.traceback() remains available.

  • string.dump(), as it may expose internal data.

  • collectgarbage(), gcinfo(), and the coroutine package have not been reviewed for security.

Features that have been modified

  • pcall() and xpcall() cannot catch certain errors, particularly timeout errors.

  • tostring() does not include pointer addresses.

  • string.match() has been patched to limit the recursion depth and to periodically check for a timeout.

  • math.random() and math.randomseed() are replaced with versions that don't share state with PHP's rand().

  • The Lua 5.2 __pairs and __ipairs metamethods are supported by pairs() and ipairs().


  • ≪ Differences from Standard Lua
  • Basic usage for LuaSandbox ≫
  • PHP Manual
  • LuaSandbox
  • 例

例

目次

  • Basic usage for LuaSandbox


Basic usage for LuaSandbox

Once you've compiled PHP with LuaSandbox support, you can begin using LuaSandbox to safely run user-provided Lua code.

例1 Execute some Lua code

<?php

$sandbox = new LuaSandbox;
$sandbox->setMemoryLimit( 50 * 1024 * 1024 );
$sandbox->setCPULimit( 10 );

// Register some functions in the Lua environment

function frobnosticate( $v ) {
return [ $v + 42 ];
}

$sandbox->registerLibrary( 'php', [
'frobnosticate' => 'frobnosticate',
'output' => function ( $string ) {
echo "$string\n";
},
'error' => function () {
throw new LuaSandboxRuntimeError( "Something is wrong" );
}
] );

// Execute some Lua code, including callbacks into PHP and into Lua

$luaCode = <<<EOF
php.output( "Hello, world" );

return "Hi", function ( v )
return php.frobnosticate( v + 200 )
end
EOF;

list( $hi, $frob ) = $sandbox->loadString( $luaCode )->call();
assert( $frob->call( 4000 ) === [ 4242 ] );

// PHP-thrown LuaSandboxRuntimeError exceptions can be caught inside Lua

list( $ok, $message ) = $sandbox->loadString( 'return pcall( php.error )' )->call();
assert( !$ok );
assert( $message === 'Something is wrong' );

?>


The LuaSandbox class

(PECL luasandbox >= 1.0.0)

はじめに

The LuaSandbox class creates a Lua environment and allows for execution of Lua code.

クラス概要

class LuaSandbox {
/* 定数 */
const int SAMPLES = 0;
const int SECONDS = 1;
const int PERCENT = 2;
/* メソッド */
public callFunction(string $name, mixed ...$args): array|bool
public disableProfiler(): void
public enableProfiler(float $period = 0.02): bool
public getCPUUsage(): float
public getMemoryUsage(): int
public getPeakMemoryUsage(): int
public getProfilerFunctionReport(int $units = LuaSandbox::SECONDS): array
public static getVersionInfo(): array
public loadBinary(string $code, string $chunkName = ''): LuaSandboxFunction
public loadString(string $code, string $chunkName = ''): LuaSandboxFunction
public pauseUsageTimer(): bool
public registerLibrary(string $libname, array $functions): void
public setCPULimit(float|bool $limit): void
public setMemoryLimit(int $limit): void
public unpauseUsageTimer(): void
public wrapPhpFunction(callable $function): LuaSandboxFunction
}

定義済み定数

LuaSandbox::SAMPLES

Used with LuaSandbox::getProfilerFunctionReport() to return timings in samples.

LuaSandbox::SECONDS

Used with LuaSandbox::getProfilerFunctionReport() to return timings in seconds.

LuaSandbox::PERCENT

Used with LuaSandbox::getProfilerFunctionReport() to return timings in percentages of the total.

目次

  • LuaSandbox::callFunction — Call a function in a Lua global variable
  • LuaSandbox::disableProfiler — Disable the profiler
  • LuaSandbox::enableProfiler — Enable the profiler.
  • LuaSandbox::getCPUUsage — Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::getMemoryUsage — Fetch the current memory usage of the Lua environment
  • LuaSandbox::getPeakMemoryUsage — Fetch the peak memory usage of the Lua environment
  • LuaSandbox::getProfilerFunctionReport — Fetch profiler data
  • LuaSandbox::getVersionInfo — Return the versions of LuaSandbox and Lua
  • LuaSandbox::loadBinary — Load a precompiled binary chunk into the Lua environment
  • LuaSandbox::loadString — Load Lua code into the Lua environment
  • LuaSandbox::pauseUsageTimer — Pause the CPU usage timer
  • LuaSandbox::registerLibrary — Register a set of PHP functions as a Lua library
  • LuaSandbox::setCPULimit — Set the CPU time limit for the Lua environment
  • LuaSandbox::setMemoryLimit — Set the memory limit for the Lua environment
  • LuaSandbox::unpauseUsageTimer — Unpause the timer paused by LuaSandbox::pauseUsageTimer
  • LuaSandbox::wrapPhpFunction — Wrap a PHP callable in a LuaSandboxFunction


Call a function in a Lua global variable

  • ≪ LuaSandbox
  • LuaSandbox::disableProfiler ≫
  • PHP Manual
  • LuaSandbox
  • Call a function in a Lua global variable

LuaSandbox::callFunction

(PECL luasandbox >= 1.0.0)

LuaSandbox::callFunction — Call a function in a Lua global variable

説明

public LuaSandbox::callFunction(string $name, mixed ...$args): array|bool

Calls a function in a Lua global variable.

If the name contains "." characters, the function is located via recursive table accesses, as if the name were a Lua expression.

If the variable does not exist, or is not a function, false will be returned and a warning issued.

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

パラメータ

name

Lua variable name.

args

Arguments to the function.

戻り値

Returns an array of values returned by the Lua function, which may be empty, 失敗した場合に false を返します.

例

例1 Calling a Lua function

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Call Lua's string.match
$captures = $sandbox->callFunction( 'string.match', $string, $pattern );

?>


Disable the profiler

  • ≪ LuaSandbox::callFunction
  • LuaSandbox::enableProfiler ≫
  • PHP Manual
  • LuaSandbox
  • Disable the profiler

LuaSandbox::disableProfiler

(PECL luasandbox >= 1.1.0)

LuaSandbox::disableProfiler — Disable the profiler

説明

public LuaSandbox::disableProfiler(): void

Disables the profiler.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • LuaSandbox::enableProfiler() - Enable the profiler.
  • LuaSandbox::getProfilerFunctionReport() - Fetch profiler data


Enable the profiler.

  • ≪ LuaSandbox::disableProfiler
  • LuaSandbox::getCPUUsage ≫
  • PHP Manual
  • LuaSandbox
  • Enable the profiler.

LuaSandbox::enableProfiler

(PECL luasandbox >= 1.1.0)

LuaSandbox::enableProfiler — Enable the profiler.

説明

public LuaSandbox::enableProfiler(float $period = 0.02): bool

Enables the profiler. Profiling will begin when Lua code is entered.

The profiler periodically samples the Lua environment to record the running function. Testing indicates that at least on Linux, setting a period less than 1ms will lead to a high overrun count but no performance problems.

パラメータ

period

Sampling period in seconds.

戻り値

Returns a boolean indicating whether the profiler is enabled.

参考

  • LuaSandbox::disableProfiler() - Disable the profiler
  • LuaSandbox::getProfilerFunctionReport() - Fetch profiler data


Fetch the current CPU time usage of the Lua environment

  • ≪ LuaSandbox::enableProfiler
  • LuaSandbox::getMemoryUsage ≫
  • PHP Manual
  • LuaSandbox
  • Fetch the current CPU time usage of the Lua environment

LuaSandbox::getCPUUsage

(PECL luasandbox >= 1.0.0)

LuaSandbox::getCPUUsage — Fetch the current CPU time usage of the Lua environment

説明

public LuaSandbox::getCPUUsage(): float

Fetches the current CPU time usage of the Lua environment.

This includes time spent in PHP callbacks.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current CPU time usage in seconds.

注意:

On Windows, this function always returns zero. On operating systems that do not support CLOCK_THREAD_CPUTIME_ID, such as FreeBSD and Mac OS X, this function will return the elapsed wall-clock time, not CPU time.

参考

  • LuaSandbox::getMemoryUsage() - Fetch the current memory usage of the Lua environment
  • LuaSandbox::getPeakMemoryUsage() - Fetch the peak memory usage of the Lua environment
  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment


Fetch the current memory usage of the Lua environment

  • ≪ LuaSandbox::getCPUUsage
  • LuaSandbox::getPeakMemoryUsage ≫
  • PHP Manual
  • LuaSandbox
  • Fetch the current memory usage of the Lua environment

LuaSandbox::getMemoryUsage

(PECL luasandbox >= 1.0.0)

LuaSandbox::getMemoryUsage — Fetch the current memory usage of the Lua environment

説明

public LuaSandbox::getMemoryUsage(): int

Fetches the current memory usage of the Lua environment.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current memory usage in bytes.

参考

  • LuaSandbox::getPeakMemoryUsage() - Fetch the peak memory usage of the Lua environment
  • LuaSandbox::getCPUUsage() - Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::setMemoryLimit() - Set the memory limit for the Lua environment


Fetch the peak memory usage of the Lua environment

  • ≪ LuaSandbox::getMemoryUsage
  • LuaSandbox::getProfilerFunctionReport ≫
  • PHP Manual
  • LuaSandbox
  • Fetch the peak memory usage of the Lua environment

LuaSandbox::getPeakMemoryUsage

(PECL luasandbox >= 1.0.0)

LuaSandbox::getPeakMemoryUsage — Fetch the peak memory usage of the Lua environment

説明

public LuaSandbox::getPeakMemoryUsage(): int

Fetches the peak memory usage of the Lua environment.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the peak memory usage in bytes.

参考

  • LuaSandbox::getMemoryUsage() - Fetch the current memory usage of the Lua environment
  • LuaSandbox::getCPUUsage() - Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::setMemoryLimit() - Set the memory limit for the Lua environment


Fetch profiler data

  • ≪ LuaSandbox::getPeakMemoryUsage
  • LuaSandbox::getVersionInfo ≫
  • PHP Manual
  • LuaSandbox
  • Fetch profiler data

LuaSandbox::getProfilerFunctionReport

(PECL luasandbox >= 1.1.0)

LuaSandbox::getProfilerFunctionReport — Fetch profiler data

説明

public LuaSandbox::getProfilerFunctionReport(int $units = LuaSandbox::SECONDS): array

For a profiling instance previously started by LuaSandbox::enableProfiler(), get a report of the cost of each function.

The measurement unit used for the cost is determined by the $units parameter:

LuaSandbox::SAMPLES

Measure in number of samples.

LuaSandbox::SECONDS

Measure in seconds of CPU time.

LuaSandbox::PERCENT

Measure percentage of CPU time.

パラメータ

units

Measurement unit constant.

戻り値

Returns profiler measurements, sorted in descending order, as an associative array. Keys are the Lua function names (with source file and line defined in angle brackets), values are the measurements as int or float.

注意:

On Windows, this function always returns an empty array. On operating systems that do not support CLOCK_THREAD_CPUTIME_ID, such as FreeBSD and Mac OS X, this function will report the elapsed wall-clock time, not CPU time.

例

例1 Profiling Lua code

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Start the profiler
$sandbox->enableProfiler( 0.01 );

// ... Execute some Lua code here ...

// Fetch the profiler data
$data = $sandbox->getProfilerFunctionReport();

?>


Return the versions of LuaSandbox and Lua

  • ≪ LuaSandbox::getProfilerFunctionReport
  • LuaSandbox::loadBinary ≫
  • PHP Manual
  • LuaSandbox
  • Return the versions of LuaSandbox and Lua

LuaSandbox::getVersionInfo

(PECL luasandbox >= 1.6.0)

LuaSandbox::getVersionInfo — Return the versions of LuaSandbox and Lua

説明

public static LuaSandbox::getVersionInfo(): array

Returns the versions of LuaSandbox and Lua.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array with two keys:

element | type | description
LuaSandbox | string | The version of the LuaSandbox extension.
Lua | string | The library name and version as defined by the LUA_RELEASE macro, for example, "Lua 5.1.5".


Load a precompiled binary chunk into the Lua environment

  • ≪ LuaSandbox::getVersionInfo
  • LuaSandbox::loadString ≫
  • PHP Manual
  • LuaSandbox
  • Load a precompiled binary chunk into the Lua environment

LuaSandbox::loadBinary

(PECL luasandbox >= 1.0.0)

LuaSandbox::loadBinary — Load a precompiled binary chunk into the Lua environment

説明

public LuaSandbox::loadBinary(string $code, string $chunkName = ''): LuaSandboxFunction

Loads data generated by LuaSandboxFunction::dump().

パラメータ

code

Data from LuaSandboxFunction::dump().

chunkName

Name for the loaded function.

戻り値

Returns a LuaSandboxFunction.

参考

  • LuaSandbox::loadString() - Load Lua code into the Lua environment


Load Lua code into the Lua environment

  • ≪ LuaSandbox::loadBinary
  • LuaSandbox::pauseUsageTimer ≫
  • PHP Manual
  • LuaSandbox
  • Load Lua code into the Lua environment

LuaSandbox::loadString

(PECL luasandbox >= 1.0.0)

LuaSandbox::loadString — Load Lua code into the Lua environment

説明

public LuaSandbox::loadString(string $code, string $chunkName = ''): LuaSandboxFunction

Loads Lua code into the Lua environment.

This is the equivalent of standard Lua's loadstring() function.

パラメータ

code

Lua code.

chunkName

Name for the loaded chunk, for use in error traces.

戻り値

Returns a LuaSandboxFunction which, when executed, will execute the passed $code.

例

例1 Loading code into Lua

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Load the code
$function = $sandbox->loadString(
<<<CODE
 return "Hello, world"
CODE
);

// Execute the loaded code
var_dump( $function->call() );

?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(12) "Hello, world"
}

参考

  • LuaSandbox::registerLibrary() - Register a set of PHP functions as a Lua library
  • LuaSandbox::wrapPhpFunction() - Wrap a PHP callable in a LuaSandboxFunction


Pause the CPU usage timer

  • ≪ LuaSandbox::loadString
  • LuaSandbox::registerLibrary ≫
  • PHP Manual
  • LuaSandbox
  • Pause the CPU usage timer

LuaSandbox::pauseUsageTimer

(PECL luasandbox >= 1.4.0)

LuaSandbox::pauseUsageTimer — Pause the CPU usage timer

説明

public LuaSandbox::pauseUsageTimer(): bool

Pauses the CPU usage timer.

This only has effect when called from within a callback from Lua. When execution returns to Lua, the timer will be automatically unpaused. If a new call into Lua is made, the timer will be unpaused for the duration of that call.

If a PHP callback calls into Lua again with timer not paused, and then that Lua function calls into PHP again, the second PHP call will not be able to pause the timer. The logic is that even though the second PHP call would avoid counting the CPU usage against the limit, the first call still counts it.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a bool indicating whether the timer is now paused.

例

例1 Manipulating the usage timer

<?php

// create a new LuaSandbox and set a CPU limit
$sandbox = new LuaSandbox();
$sandbox->setCPULimit( 1 );

function doWait( $t ) {
$end = microtime( true ) + $t;
while ( microtime( true ) < $end ) {
// waste CPU cycles
}
}

// Register a PHP callback
$sandbox->registerLibrary( 'php', [
'test' => function () use ( $sandbox ) {
$sandbox->pauseUsageTimer();
doWait( 5 );

$sandbox->unpauseUsageTimer();
doWait( 0.1 );
},
'test2' => function () use ( $sandbox ) {
$sandbox->pauseUsageTimer();
$sandbox->unpauseUsageTimer();
doWait( 1.1 );
}
] );

echo "This should not time out...\n";
$sandbox->loadString( 'php.test()' )->call();

echo "This should time out.\n";
try {
$sandbox->loadString( 'php.test2()' )->call();
echo "It did not?\n";
} catch ( LuaSandboxTimeoutError $ex ) {
echo "It did! " . $ex->getMessage() . "\n";
}

?>

上の例の出力は以下となります。

This should not time out...
This should time out.
It did! The maximum execution time for this script was exceeded

参考

  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment
  • LuaSandbox::unpauseUsageTimer() - Unpause the timer paused by LuaSandbox::pauseUsageTimer


Register a set of PHP functions as a Lua library

  • ≪ LuaSandbox::pauseUsageTimer
  • LuaSandbox::setCPULimit ≫
  • PHP Manual
  • LuaSandbox
  • Register a set of PHP functions as a Lua library

LuaSandbox::registerLibrary

(PECL luasandbox >= 1.0.0)

LuaSandbox::registerLibrary — Register a set of PHP functions as a Lua library

説明

public LuaSandbox::registerLibrary(string $libname, array $functions): void

Registers a set of PHP functions as a Lua library, so that Lua can call the relevant PHP code.

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

パラメータ

libname

The name of the library. In the Lua state, the global variable of this name will be set to the table of functions. If the table already exists, the new functions will be added to it.

functions

An array, where each key is a function name, and each value is a corresponding PHP callable.

戻り値

値を返しません。

例

例1 Registering PHP functions to call from Lua

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// Register some functions in the Lua environment

function frobnosticate( $v ) {
return [ $v + 42 ];
}

$sandbox->registerLibrary( 'php', [
'frobnosticate' => 'frobnosticate',
'output' => function ( $string ) {
echo "$string\n";
},
'error' => function () {
throw new LuaSandboxRuntimeError( "Something is wrong" );
}
] );

?>

参考

  • LuaSandbox::loadString() - Load Lua code into the Lua environment
  • LuaSandbox::wrapPhpFunction() - Wrap a PHP callable in a LuaSandboxFunction


Set the CPU time limit for the Lua environment

  • ≪ LuaSandbox::registerLibrary
  • LuaSandbox::setMemoryLimit ≫
  • PHP Manual
  • LuaSandbox
  • Set the CPU time limit for the Lua environment

LuaSandbox::setCPULimit

(PECL luasandbox >= 1.0.0)

LuaSandbox::setCPULimit — Set the CPU time limit for the Lua environment

説明

public LuaSandbox::setCPULimit(float|bool $limit): void

Sets the CPU time limit for the Lua environment.

If the total user and system time used by the environment after the call to this method exceeds this limit, a LuaSandboxTimeoutError exception is thrown.

Time used in PHP callbacks is included in the limit.

Setting the time limit from a callback while Lua is running causes the timer to be reset, or started if it was not already running.

注意:

On Windows, the CPU limit will be ignored. On operating systems that do not support CLOCK_THREAD_CPUTIME_ID, such as FreeBSD and Mac OS X, wall-clock time rather than CPU time will be limited.

パラメータ

limit

Limit as a float in seconds, or false for no limit.

戻り値

値を返しません。

例

例1 Calling a Lua function

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// set a time limit
$sandbox->setCPULimit( 2 );

// Run Lua code
$sandbox->loadString( 'while true do end' )->call();

?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error:  Uncaught LuaSandboxTimeoutError: The maximum execution time for this script was exceeded

参考

  • LuaSandbox::getCPUUsage() - Fetch the current CPU time usage of the Lua environment
  • LuaSandbox::setMemoryLimit() - Set the memory limit for the Lua environment


Set the memory limit for the Lua environment

  • ≪ LuaSandbox::setCPULimit
  • LuaSandbox::unpauseUsageTimer ≫
  • PHP Manual
  • LuaSandbox
  • Set the memory limit for the Lua environment

LuaSandbox::setMemoryLimit

(PECL luasandbox >= 1.0.0)

LuaSandbox::setMemoryLimit — Set the memory limit for the Lua environment

説明

public LuaSandbox::setMemoryLimit(int $limit): void

Sets the memory limit for the Lua environment.

If this limit is exceeded, a LuaSandboxMemoryError exception is thrown.

パラメータ

limit

Memory limit in bytes.

戻り値

値を返しません。

例

例1 Calling a Lua function

<?php

// create a new LuaSandbox
$sandbox = new LuaSandbox();

// set a memory limit
$sandbox->setMemoryLimit( 50 * 1024 * 1024 );

// Run Lua code
$sandbox->loadString( 'local x = "x"; while true do x = x .. x; end' )->call();

?>

上の例の出力は、 たとえば以下のようになります。

PHP Fatal error:  Uncaught LuaSandboxMemoryError: not enough memory

参考

  • LuaSandbox::getMemoryUsage() - Fetch the current memory usage of the Lua environment
  • LuaSandbox::getPeakMemoryUsage() - Fetch the peak memory usage of the Lua environment
  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment


Unpause the timer paused by LuaSandbox::pauseUsageTimer

  • ≪ LuaSandbox::setMemoryLimit
  • LuaSandbox::wrapPhpFunction ≫
  • PHP Manual
  • LuaSandbox
  • Unpause the timer paused by LuaSandbox::pauseUsageTimer

LuaSandbox::unpauseUsageTimer

(PECL luasandbox >= 1.4.0)

LuaSandbox::unpauseUsageTimer — Unpause the timer paused by LuaSandbox::pauseUsageTimer()

説明

public LuaSandbox::unpauseUsageTimer(): void

Unpauses the timer paused by LuaSandbox::pauseUsageTimer().

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • LuaSandbox::pauseUsageTimer() - Pause the CPU usage timer
  • LuaSandbox::setCPULimit() - Set the CPU time limit for the Lua environment


Wrap a PHP callable in a LuaSandboxFunction

  • ≪ LuaSandbox::unpauseUsageTimer
  • LuaSandboxFunction ≫
  • PHP Manual
  • LuaSandbox
  • Wrap a PHP callable in a LuaSandboxFunction

LuaSandbox::wrapPhpFunction

(PECL luasandbox >= 1.2.0)

LuaSandbox::wrapPhpFunction — Wrap a PHP callable in a LuaSandboxFunction

説明

public LuaSandbox::wrapPhpFunction(callable $function): LuaSandboxFunction

Wraps a PHP callable in a LuaSandboxFunction, so it can be passed into Lua as an anonymous function.

The function must return either an array of values (which may be empty), or null which is equivalent to returning the empty array.

Exceptions will be raised as errors in Lua, however only LuaSandboxRuntimeError exceptions may be caught inside Lua with pcall() or xpcall().

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

パラメータ

function

Callable to wrap.

戻り値

Returns a LuaSandboxFunction.

参考

  • LuaSandbox::loadString() - Load Lua code into the Lua environment
  • LuaSandbox::registerLibrary() - Register a set of PHP functions as a Lua library


The LuaSandboxFunction class

(PECL luasandbox >= 1.0.0)

はじめに

Represents a Lua function, allowing it to be called from PHP.

A LuaSandboxFunction may be obtained as a return value from Lua, as a parameter
passed to a callback from Lua, or by using
LuaSandbox::wrapPhpFunction(),
LuaSandbox::loadString(), or
LuaSandbox::loadBinary().

クラス概要

class LuaSandboxFunction {
/* メソッド */
public call(string ...$args): array|bool
public dump(): string
}

目次

  • LuaSandboxFunction::call — Call a Lua function
  • LuaSandboxFunction::__construct — Unused
  • LuaSandboxFunction::dump — Dump the function as a binary blob


Call a Lua function

  • ≪ LuaSandboxFunction
  • LuaSandboxFunction::__construct ≫
  • PHP Manual
  • LuaSandboxFunction
  • Call a Lua function

LuaSandboxFunction::call

(PECL luasandbox >= 1.0.0)

LuaSandboxFunction::call — Call a Lua function

説明

public LuaSandboxFunction::call(string ...$args): array|bool

Calls a Lua function.

Errors considered to be the fault of the PHP code will result in the function returning false and E_WARNING being raised, for example, a resource type being used as an argument. Lua errors will result in a LuaSandboxRuntimeError exception being thrown.

PHP and Lua types are converted as follows:

  • PHP null is Lua nil, and vice versa.

  • PHP ints and floats are converted to Lua numbers. Infinity and NAN are supported.

  • Lua numbers without a fractional part between approximately -2**53 and 2**53 are converted to PHP ints, with others being converted to PHP floats.

  • PHP bools are Lua booleans, and vice versa.

  • PHP strings are Lua strings, and vice versa.

  • Lua functions are PHP LuaSandboxFunction objects, and vice versa. General PHP callables are not supported.

  • PHP arrays are converted to Lua tables, and vice versa.

    • Note that Lua typically indexes arrays from 1, while PHP indexes arrays from 0. No adjustment is made for these differing conventions.

    • Self-referential arrays are not supported in either direction.

    • PHP references are dereferenced.

    • Lua __pairs and __ipairs are processed. __index is ignored.

    • When converting from PHP to Lua, integer keys between -2**53 and 2**53 are represented as Lua numbers. All other keys are represented as Lua strings.

    • When converting from Lua to PHP, keys other than strings and numbers will result in an error, as will collisions when converting numbers to strings or vice versa (since PHP considers things like $a[0] and $a["0"] as being equivalent).

  • All other types are unsupported and will raise an error/exception, including general PHP objects and Lua userdata and thread types.

Lua functions inherently return a list of results. So on success, this method returns an array containing all of the values returned by Lua, with int keys starting from zero. Lua may return no results, in which case an empty array is returned.

パラメータ

args

Arguments passed to the function.

戻り値

Returns an array of values returned by the function, which may be empty, 失敗した場合に false を返します.


Unused

  • ≪ LuaSandboxFunction::call
  • LuaSandboxFunction::dump ≫
  • PHP Manual
  • LuaSandboxFunction
  • Unused

LuaSandboxFunction::__construct

(PECL luasandbox >= 1.0.0)

LuaSandboxFunction::__construct — Unused

説明

final private LuaSandboxFunction::__construct()

LuaSandboxFunction are obtained as a return value from Lua,
as a parameter passed to a callback from Lua, or by using
LuaSandbox::wrapPhpFunction(),
LuaSandbox::loadString(), or
LuaSandbox::loadBinary(). They cannot be constructed directly.

パラメータ

この関数にはパラメータはありません。


Dump the function as a binary blob

  • ≪ LuaSandboxFunction::__construct
  • LuaSandboxError ≫
  • PHP Manual
  • LuaSandboxFunction
  • Dump the function as a binary blob

LuaSandboxFunction::dump

(PECL luasandbox >= 1.0.0)

LuaSandboxFunction::dump — Dump the function as a binary blob

説明

public LuaSandboxFunction::dump(): string

Dumps the function as a binary blob.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string that may be passed to LuaSandbox::loadBinary().


The LuaSandboxError class

(PECL luasandbox >= 1.0.0)

はじめに

Base class for LuaSandbox exceptions

クラス概要

class LuaSandboxError extends Exception {
/* 定数 */
const int RUN = 2;
const int SYNTAX = 3;
const int MEM = 4;
const int ERR = 5;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

定義済み定数

LuaSandboxError::RUN

LuaSandboxError::SYNTAX

LuaSandboxError::MEM

LuaSandboxError::ERR


The LuaSandboxErrorError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when Lua encounters an error inside an error handler.

クラス概要

class LuaSandboxErrorError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The LuaSandboxFatalError class

(PECL luasandbox >= 1.0.0)

はじめに

Uncatchable LuaSandbox exceptions.

These may not be caught inside Lua using pcall() or xpcall().

クラス概要

class LuaSandboxFatalError extends LuaSandboxError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The LuaSandboxMemoryError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when Lua cannot allocate memory.

クラス概要

class LuaSandboxMemoryError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

参考

  • LuaSandbox::setMemoryLimit()


The LuaSandboxRuntimeError class

(PECL luasandbox >= 1.0.0)

はじめに

Catchable LuaSandbox runtime exceptions.

These may be caught inside Lua using pcall() or xpcall().

クラス概要

class LuaSandboxRuntimeError extends LuaSandboxError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The LuaSandboxSyntaxError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when Lua code cannot be parsed.

クラス概要

class LuaSandboxSyntaxError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The LuaSandboxTimeoutError class

(PECL luasandbox >= 1.0.0)

はじめに

Exception thrown when the configured CPU time limit is exceeded.

クラス概要

class LuaSandboxTimeoutError extends LuaSandboxFatalError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

参考

  • LuaSandbox::setCPULimit()


その他の関数

  • はじめに
  • インストール/設定
    • 実行時設定
  • 定義済み定数
  • その他の関数
    • connection_aborted — クライアントとの接続が切断されているかどうかを調べる
    • connection_status — 接続ステータスのビットフィールドを返す
    • constant — 定数の値を返す
    • define — 名前を指定して定数を定義する
    • defined — 指定した名前の定数が存在するかどうかを調べる
    • die — exit と同等
    • eval — 文字列を PHP コードとして評価する
    • exit — メッセージを出力し、現在のスクリプトを終了する
    • get_browser — ユーザーのブラウザの機能を取得する
    • __halt_compiler — コンパイラの実行を中止する
    • highlight_file — ファイルの構文ハイライト表示
    • highlight_string — 文字列の構文ハイライト表示
    • hrtime — システムの高精度な時刻を取得する
    • ignore_user_abort — クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
    • pack — データをバイナリ文字列にパックする
    • php_strip_whitespace — コメントと空白文字を取り除いたソースを返す
    • sapi_windows_cp_conv — 文字列のコードページを別のものに変換する
    • sapi_windows_cp_get — 現在のコードページを取得する
    • sapi_windows_cp_is_utf8 — コードページがUTF-8と互換性があるかを返す
    • sapi_windows_cp_set — 現在のプロセスのコードページを設定する
    • sapi_windows_generate_ctrl_event — CTRLイベント を別プロセスに送信する
    • sapi_windows_set_ctrl_handler — CTRLイベント のハンドラを設定したり削除したりする
    • sapi_windows_vt100_support — Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する
    • show_source — highlight_file のエイリアス
    • sleep — 実行を遅延させる
    • sys_getloadavg — システムの平均負荷を取得する
    • time_nanosleep — 秒およびナノ秒単位で実行を遅延する
    • time_sleep_until — 指定した時刻まで実行を遅延する
    • uniqid — 時刻ベースの識別子を生成する
    • unpack — バイナリ文字列からデータを切り出す
    • usleep — マイクロ秒単位で実行を遅延する
  • 変更履歴


  • ≪ その他
  • インストール/設定 ≫
  • PHP Manual
  • その他
  • はじめに

はじめに

他のカテゴリには当てはまらない関数群を、こちらに収録しています。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • その他
  • インストール/設定

インストール/設定

目次

  • 実行時設定


実行時設定

php.ini の設定により動作が変化します。

Misc の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ignore_user_abort | "0" | INI_ALL |
highlight.string | "#DD0000" | INI_ALL |
highlight.comment | "#FF8000" | INI_ALL |
highlight.keyword | "#007700" | INI_ALL |
highlight.default | "#0000BB" | INI_ALL |
highlight.html | "#000000" | INI_ALL |
browscap | NULL | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ignore_user_abort bool

デフォルトは false。true に変更すると、 クライアントが接続を破棄した後もスクリプトは終了しません。

ignore_user_abort() も参照ください。

highlight.bg string
highlight.comment string
highlight.default string
highlight.html string
highlight.keyword string
highlight.string string

構文ハイライト表示モードの色。 <font color="??????"> 形式のものは全て動作します。

browscap string

browser capabilities file (ブラウザ機能ファイル) の 名前 (例: browscap.ini) と場所。 get_browser() も参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

CONNECTION_ABORTED (int)
CONNECTION_NORMAL (int)
CONNECTION_TIMEOUT (int)
__COMPILER_HALT_OFFSET__ (int)


その他の関数

目次

  • connection_aborted — クライアントとの接続が切断されているかどうかを調べる
  • connection_status — 接続ステータスのビットフィールドを返す
  • constant — 定数の値を返す
  • define — 名前を指定して定数を定義する
  • defined — 指定した名前の定数が存在するかどうかを調べる
  • die — exit と同等
  • eval — 文字列を PHP コードとして評価する
  • exit — メッセージを出力し、現在のスクリプトを終了する
  • get_browser — ユーザーのブラウザの機能を取得する
  • __halt_compiler — コンパイラの実行を中止する
  • highlight_file — ファイルの構文ハイライト表示
  • highlight_string — 文字列の構文ハイライト表示
  • hrtime — システムの高精度な時刻を取得する
  • ignore_user_abort — クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
  • pack — データをバイナリ文字列にパックする
  • php_strip_whitespace — コメントと空白文字を取り除いたソースを返す
  • sapi_windows_cp_conv — 文字列のコードページを別のものに変換する
  • sapi_windows_cp_get — 現在のコードページを取得する
  • sapi_windows_cp_is_utf8 — コードページがUTF-8と互換性があるかを返す
  • sapi_windows_cp_set — 現在のプロセスのコードページを設定する
  • sapi_windows_generate_ctrl_event — CTRLイベント を別プロセスに送信する
  • sapi_windows_set_ctrl_handler — CTRLイベント のハンドラを設定したり削除したりする
  • sapi_windows_vt100_support — Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する
  • show_source — highlight_file のエイリアス
  • sleep — 実行を遅延させる
  • sys_getloadavg — システムの平均負荷を取得する
  • time_nanosleep — 秒およびナノ秒単位で実行を遅延する
  • time_sleep_until — 指定した時刻まで実行を遅延する
  • uniqid — 時刻ベースの識別子を生成する
  • unpack — バイナリ文字列からデータを切り出す
  • usleep — マイクロ秒単位で実行を遅延する


クライアントとの接続が切断されているかどうかを調べる

  • ≪ その他の関数
  • connection_status ≫
  • PHP Manual
  • その他の関数
  • クライアントとの接続が切断されているかどうかを調べる

connection_aborted

(PHP 4, PHP 5, PHP 7, PHP 8)

connection_aborted — クライアントとの接続が切断されているかどうかを調べる

説明

connection_aborted(): int

クライアントとの接続が切断されているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クライアントとの接続が切断されている場合に 1、それ以外の場合に 0 を返します。

参考

  • connection_status() - 接続ステータスのビットフィールドを返す
  • ignore_user_abort() - クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
  • PHP における接続処理についての説明は 接続処理


接続ステータスのビットフィールドを返す

  • ≪ connection_aborted
  • constant ≫
  • PHP Manual
  • その他の関数
  • 接続ステータスのビットフィールドを返す

connection_status

(PHP 4, PHP 5, PHP 7, PHP 8)

connection_status — 接続ステータスのビットフィールドを返す

説明

connection_status(): int

接続ステータスのビットフィールドを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

接続ステータスのビットフィールドを返します。これを定数 CONNECTION_* と比較することで、接続の状態を判断できます。

参考

  • connection_aborted() - クライアントとの接続が切断されているかどうかを調べる
  • ignore_user_abort() - クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
  • PHP における接続処理についての説明は 接続処理


定数の値を返す

  • ≪ connection_status
  • define ≫
  • PHP Manual
  • その他の関数
  • 定数の値を返す

constant

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

constant — 定数の値を返す

説明

constant(string $name): mixed

name で指定した定数の値を返します。

constant() はある定数の値を取得する必要があるが、 その名前が不明な場合に有用です。つまり、定数名が変数に保存されているか、 関数から返される場合に有用です。

この関数は クラス定数 や 列挙型のcase に対しても動作します。

パラメータ

name

定数名。

戻り値

定数の値を返します。

エラー / 例外

定数が定義されていない場合は Error がスローされます。 PHP 8.0.0 より前のバージョンでは、 E_WARNING レベルの警告が発生していました。

変更履歴

バージョン | 説明
8.0.0 | 定数が定義されていない場合は、 constant() は Error をスローするようになりました。 これより前のバージョンでは、 E_WARNING レベルの警告が発生し、null を返していました。

例

例1 定数に対して constant() を使う例

<?php

define("MAXSIZE", 100);

echo MAXSIZE;
echo constant("MAXSIZE"); // same thing as the previous line

interface bar {
const test = 'foobar!';
}

class foo {
const test = 'foobar!';
}

$const = 'test';

var_dump(constant('bar::'. $const)); // string(7) "foobar!"
var_dump(constant('foo::'. $const)); // string(7) "foobar!"

?>

例2 列挙型の case に constant() を使う例(PHP 8.1.0 以降)

<?php

enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

$case = 'Hearts';

var_dump(constant('Suit::'. $case)); // enum(Suit::Hearts)

?>

参考

  • define() - 名前を指定して定数を定義する
  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • get_defined_constants() - すべての定数の名前とその値を連想配列として返す
  • 定数の節


名前を指定して定数を定義する

  • ≪ constant
  • defined ≫
  • PHP Manual
  • その他の関数
  • 名前を指定して定数を定義する

define

(PHP 4, PHP 5, PHP 7, PHP 8)

define — 名前を指定して定数を定義する

説明

define(string $constant_name, mixed $value, bool $case_insensitive = false): bool

実行時に、名前を指定して定数を定義します。

パラメータ

constant_name

定数の名前。

注意:

予約語や無効な名前を使っていても、定数を define() できてしまいます。これらの値を取得するには、 constant() 関数を使うこと(だけ)しかできません。 しかしながら、こういったことをするのは推奨されません。

value

定数の値。PHP 5 では、value は スカラー値 (int、 float、string、bool あるいは null) でなければいけません。PHP 7 では配列を使うこともできます。

警告

リソース型の定数を定義することもできますが、 推奨できません。予期せぬ振る舞いをする可能性があります。

case_insensitive

true を指定すると、定数は大文字小文字を区別しないようになります。 デフォルトでは大文字小文字を区別します。つまり CONSTANT と Constant は別の値を表すわけです。

警告

大文字小文字を区別しない定数を定義するのは、 PHP 7.3.0 以降では推奨されなくなりました。 PHP 8.0.0 以降では、false のみを受け入れます。 true を渡すと、警告が発生します。

注意:

大文字小文字を区別しないときは、定数は小文字で格納されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | case_insensitive に true を渡すと、 E_WARNING が発生するようになりました。 false を渡すことはまだ許可されています。
7.3.0 | case_insensitive は非推奨になりました。 8.0.0 で削除される予定です。
7.0.0 | array が使えるようになりました。

例

例1 定数の定義

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // "Hello world." を出力します
echo Constant; // "Constant" を出力し、警告が発生します

define("GREETING", "Hello you.", true);
echo GREETING; // "Hello you." を出力します
echo Greeting; // "Hello you." を出力します

// PHP 7 以降で動作します
define('ANIMALS', array(
'dog',
'cat',
'bird'
));
echo ANIMALS[1]; // "cat" を出力します

?>

例2 予約された名前を定数にする

マジック定数 と同じ名前の定数を定義できる 可能性 を示します。 しかしながら、結果として起きる振る舞いは明らかに混乱を招くため、 こんなことを実際にすることは推奨されません。

<?php
var_dump(defined('__LINE__'));
var_dump(define('__LINE__', 'test'));
var_dump(constant('__LINE__'));
var_dump(__LINE__);
?>

上の例の出力は以下となります。

bool(false)
bool(true)
string(4) "test"
int(5)

参考

  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • constant() - 定数の値を返す
  • 定数の節


指定した名前の定数が存在するかどうかを調べる

  • ≪ define
  • die ≫
  • PHP Manual
  • その他の関数
  • 指定した名前の定数が存在するかどうかを調べる

defined

(PHP 4, PHP 5, PHP 7, PHP 8)

defined — 指定した名前の定数が存在するかどうかを調べる

説明

defined(string $constant_name): bool

constant_name で指定した定数が定義されているかどうかを調べます。

この関数は クラス定数 や 列挙型の case に対しても動作します。

注意:

変数が存在するかどうかを知りたければ、isset() を利用してください。defined() は 定数にしか適用できません。 関数が存在するかどうかを知りたければ、 function_exists() を利用してください。

パラメータ

constant_name

定数名。

戻り値

constant_name で指定した名前の定数が定義されている 場合に true、その他の場合にfalseを返します。

例

例1 定数のチェック

<?php

/* 引用符の使い方に注意してください。これは重要です。この例では
* 文字列 'TEST' が、定数 TEST の名前かどうかを調べています。*/
if (defined('TEST')) {
echo TEST;
}

interface bar {
const test = 'foobar!';
}

class foo {
const test = 'foobar!';
}

var_dump(defined('bar::test')); // bool(true)
var_dump(defined('foo::test')); // bool(true)

?>

例2 列挙型のcase をチェックする(PHP 8.1.0 以降)

<?php

enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

var_dump(defined('Suit::Hearts')); // bool(true)

?>

参考

  • define() - 名前を指定して定数を定義する
  • constant() - 定数の値を返す
  • get_defined_constants() - すべての定数の名前とその値を連想配列として返す
  • function_exists() - 指定した関数が定義されている場合に true を返す
  • 定数の節


exit と同等

  • ≪ defined
  • eval ≫
  • PHP Manual
  • その他の関数
  • exit と同等

die

(PHP 4, PHP 5, PHP 7, PHP 8)

die — exit と同等

説明

この言語構造は、exit() と同等です。


文字列を PHP コードとして評価する

  • ≪ die
  • exit ≫
  • PHP Manual
  • その他の関数
  • 文字列を PHP コードとして評価する

eval

(PHP 4, PHP 5, PHP 7, PHP 8)

eval — 文字列を PHP コードとして評価する

説明

eval(string $code): mixed

指定した code を PHP コードとして評価します。

評価されるコードは、eval() がコールされた行における 変数のスコープ を継承します。コールされた時点で利用可能なあらゆる変数が、 評価されるコード中で読み取ることができますし、変更することもできます。 しかし、定義されている全ての関数やクラスは、グローバル名前空間で定義されます。 言い換えると、コンパイラは評価されるコードを include された別のファイルのようにみなすということです。

警告

eval() は非常に危険な言語構造です。 というのも、任意の PHP コードを実行できてしまうからです。 これを使うことはおすすめしません。 いろいろ検討した結果どうしても使わざるを得なくなった場合は、細心の注意を払って使いましょう。 ユーザーから受け取ったデータをそのまま渡してはいけません。 渡す前に、適切な検証が必要です。

パラメータ

code

有効な PHP コード。これを評価します。

PHP 開始タグを含めてはいけません。つまり、 '<?php echo "Hi!"; ?>' ではなく 'echo "Hi!";' を渡さなければならないということです。 適切に PHP タグを使えば、PHP モードからいったん抜けてもう一度 PHP モードに戻るということも可能です。 たとえば、このようになります。 'echo "PHP モード!"; ?>HTML モード!<?php echo "ふたたび PHP モード!";'

それはさておき、渡すコードは PHP として有効な形式でなければなりません。 つまり、すべての文はセミコロンで終了する必要があるということです。 たとえば 'echo "やあ!"' はパースエラーになりますが、 'echo "やあ!";' は動作します。

return 文は、コードの評価をただちに終了します。

コードの実行は、eval() を呼び出したスコープ内で行われます。
したがって、eval() の中で定義したり変更したりした変数は
eval() を抜けた後でも参照可能です。

戻り値

評価されるコードの中で return が コールされない限り、eval() は null を返します。 return がコールされた場合は、その値を返します。 PHP 7 以降、評価されるコードの中でパースエラーが発生した場合は、 eval() は ParseError 例外をスローします。 PHP 7 より前のバージョンでは、この場合に eval() は false を返していました。 それ以降のコードは通常通り実行されます。 eval() の中でのパースエラーを set_error_handler() で捕捉することはできません。

例

例1 eval() の例 - 簡単なテキストのマージ

<?php
$string = 'cup';
$name = 'coffee';
$str = 'This is a $string with my $name in it.';
echo $str. "\n";
eval("\$str = \"$str\";");
echo $str. "\n";
?>

上の例の出力は以下となります。

This is a $string with my $name in it.
This is a cup with my coffee in it.

注意

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

ヒント

ブラウザに直接結果を出力する すべてのものと同様に、出力制御関数 を使用してこの関数の出力をキャプチャーし、(例えば)文字列 (string)に保存することが可能です。

注意:

評価されるコードの中で致命的なエラーが発生した場合は、 スクリプト全体が終了します。

参考

  • call_user_func() - 最初の引数で指定したコールバック関数をコールする


メッセージを出力し、現在のスクリプトを終了する

  • ≪ eval
  • get_browser ≫
  • PHP Manual
  • その他の関数
  • メッセージを出力し、現在のスクリプトを終了する

exit

(PHP 4, PHP 5, PHP 7, PHP 8)

exit — メッセージを出力し、現在のスクリプトを終了する

説明

exit(string $status = ?): void
exit(int $status): void

スクリプトの実行を終了します。 シャットダウン関数 や オブジェクトのデストラクタ は、exit がコールされた場合にも実行されます。

exit は言語構造です。 status を指定しない場合は括弧なしでコールできます。

パラメータ

status

status が文字列の場合は、この関数は終了直前に status を表示します。

status が int の場合は その値が終了ステータスとして使われ、表示はされません。終了ステータスは 0 から 254 までの値でなければなりません。終了ステータス 255 は PHP に予約されており、使用してはいけません。ステータス 0 は、 プログラムを正常終了させる際に使用します。

戻り値

値を返しません。

例

例1 exit の例

<?php

$filename = '/path/to/data-file';
$file = fopen($filename, 'r')
or exit("ファイル ($filename) をオープンできません");

?>

例2 exit でステータスを指定する例

<?php

// 正常終了
exit;
exit();
exit(0);

// エラーコードつきの終了
exit(1);
exit(0376); // 八進数

?>

例3 シャットダウン関数やデストラクタが実行される例

<?php
class Foo
{
public function __destruct()
{
echo 'Destruct: ' . __METHOD__ . '()' . PHP_EOL;
}
}

function shutdown()
{
echo 'Shutdown: ' . __FUNCTION__ . '()' . PHP_EOL;
}

$foo = new Foo();
register_shutdown_function('shutdown');

exit();
echo 'これは出力されません。';
?>

上の例の出力は以下となります。

Shutdown: shutdown()
 Destruct: Foo::__destruct()

注意

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

注意:

この言語構造は、die() と等価です。

参考

  • register_shutdown_function() - シャットダウン時に実行する関数を登録する


ユーザーのブラウザの機能を取得する

  • ≪ exit
  • __halt_compiler ≫
  • PHP Manual
  • その他の関数
  • ユーザーのブラウザの機能を取得する

get_browser

(PHP 4, PHP 5, PHP 7, PHP 8)

get_browser — ユーザーのブラウザの機能を取得する

説明

get_browser(?string $user_agent = null, bool $return_array = false): object|array|false

ユーザーのブラウザの機能を調べます。これは、browscap.ini ファイルのブラウザ情報を調べることにより行います。

パラメータ

user_agent

処理するユーザーエージェント。デフォルトでは、HTTP の User-Agent ヘッダの内容を使用します。しかし、このパラメータを渡すことでこれを変更する (別のブラウザの情報を取得する) ことが可能です。

このパラメータを処理しないようにするには null 値を渡します。

return_array

true を指定すると、この関数はオブジェクトでなく配列を返します。

戻り値

情報は、オブジェクトあるいは配列形式で返されます。 たとえばブラウザのメジャーバージョン番号、マイナーバージョン番号や ID 文字列といったさまざまなデータが含まれています。また、 フレームや JavaScript、クッキーといった機能についての true/false 値も含んでいます。

cookies の値は、単にそのブラウザがクッキーを扱う機能を 有していることを示すだけであり、ユーザーがクッキーを受け入れる設定に しているかどうかを表すものではありません。それをチェックする唯一の方法は、 いったん setcookie() でクッキーを設定してからリロードし、 その値を調べることです。

情報が取得できなかった場合は、false を返します。 たとえば、php.ini の browscap が設定されていなかった場合などです。

例

例1 ユーザーのブラウザについての全情報の一覧

<?php
echo $_SERVER['HTTP_USER_AGENT'] . "\n\n";

$browser = get_browser(null, true);
print_r($browser);
?>

上の例の出力は、 たとえば以下のようになります。

Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7) Gecko/20040803 Firefox/0.9.3

Array
(
    [browser_name_regex] => ^mozilla/5\.0 (windows; .; windows nt 5\.1; .*rv:.*) gecko/.* firefox/0\.9.*$
    [browser_name_pattern] => Mozilla/5.0 (Windows; ?; Windows NT 5.1; *rv:*) Gecko/* Firefox/0.9*
    [parent] => Firefox 0.9
    [platform] => WinXP
    [browser] => Firefox
    [version] => 0.9
    [majorver] => 0
    [minorver] => 9
    [cssversion] => 2
    [frames] => 1
    [iframes] => 1
    [tables] => 1
    [cookies] => 1
    [backgroundsounds] =>
    [vbscript] =>
    [javascript] => 1
    [javaapplets] => 1
    [activexcontrols] =>
    [cdf] =>
    [aol] =>
    [beta] => 1
    [win16] =>
    [crawler] =>
    [stripper] =>
    [wap] =>
    [netclr] =>
)

注意

注意:

この関数が正常に機能するためには、php.ini の browscap 設定が、システム上の browscap.ini の正確な位置を 指している必要があります。

browscap.ini は PHP にはバンドルされていません。 しかし、ここで最新の » php_browscap.ini を入手することができます。

browscap.ini は多くのブラウザに関する情報をもっていますが、 データベースを最新に保つのはユーザーによる更新に依存しています。 ファイルのフォーマット自体を見ればおおよそのことがわかります。


コンパイラの実行を中止する

  • ≪ get_browser
  • highlight_file ≫
  • PHP Manual
  • その他の関数
  • コンパイラの実行を中止する

__halt_compiler

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

__halt_compiler — コンパイラの実行を中止する

説明

__halt_compiler(): void

コンパイラの実行を中止します。 これは、インストール用ファイルのようなデータを PHP スクリプトに埋め込んでいる場合に便利です。

データの開始位置（バイト値）は、定数 __COMPILER_HALT_OFFSET__ で定義されています。 これはファイル内で __halt_compiler() が使用されている場合にのみ存在します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 __halt_compiler() の例

<?php

// このファイルをオープンします
$fp = fopen(__FILE__, 'r');

// データのある位置までファイルポインタを移動します
fseek($fp, __COMPILER_HALT_OFFSET__);

// それを出力します
var_dump(stream_get_contents($fp));

// ここでスクリプトの実行を終了します
__halt_compiler(); インストールデータ（例: tar, gz, PHP など..）

注意

注意:

__halt_compiler() は、いちばん外側のスコープでのみ使用可能です。


ファイルの構文ハイライト表示

  • ≪ __halt_compiler
  • highlight_string ≫
  • PHP Manual
  • その他の関数
  • ファイルの構文ハイライト表示

highlight_file

(PHP 4, PHP 5, PHP 7, PHP 8)

highlight_file — ファイルの構文ハイライト表示

説明

highlight_file(string $filename, bool $return = false): string|bool

filename の中のコードを構文ハイライト表示して 出力します。色は、PHP 組込の構文ハイライタで定義されているものを使用します。

多くのサーバーでは、拡張子が phps のファイルは 自動的に構文ハイライト表示されるように設定されています。例えば example.phps のようなファイルは、構文ハイライト したソースファイルとして表示されます。これを有効にするには、 httpd.conf に以下のような行を追加します。

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

パラメータ

filename

ハイライト表示する PHP ファイルへのパス。

return

このパラメータを true にすると、この関数はハイライトされたコードを返します。

戻り値

return が true の場合は、 ハイライトされたコードを文字列として返し、表示しません。 それ以外の場合は、成功した場合に true、 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | 結果のHTMLが変更されました。

注意

警告

highlight_file() 関数を使用する場合には、 パスワードやその他潜在的なセキュリティ上の危険を生む類の重要な 情報を不注意で公開してしまわないように注意する必要があります。

注意:

return パラメータを使う場合、この関数は内部的に出力バッファリングを使います。 そのため、ob_start() コールバック関数の中では使えません。

参考

  • highlight_string() - 文字列の構文ハイライト表示
  • ハイライトに関する INI 設定


文字列の構文ハイライト表示

  • ≪ highlight_file
  • hrtime ≫
  • PHP Manual
  • その他の関数
  • 文字列の構文ハイライト表示

highlight_string

(PHP 4, PHP 5, PHP 7, PHP 8)

highlight_string — 文字列の構文ハイライト表示

説明

highlight_string(string $string, bool $return = false): string|bool

PHP 組込みの 構文ハイライタで定義されたカラーを使用して str を構文ハイライト表示したものを、html マークアップで出力あるいは返します。

パラメータ

string

ハイライト表示する PHP コード。開始タグを含む必要があります。

return

このパラメータを true にすると、この関数はハイライトされたコードを返します。

戻り値

return が true の場合は、 ハイライトされたコードを文字列として返し、表示しません。 それ以外の場合は、成功した場合に true、 失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | 結果のHTMLが変更されました。

例

例1 highlight_string() の例

<?php
highlight_string('<?php phpinfo(); ?>');
?>

上の例の出力は以下となります。

<code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php phpinfo</span><span style="color: #007700">(); </span><span style="color: #0000BB">?&gt;</span>
</span>
</code>

上の例の PHP 8.3 での出力は、このようになります。:

<pre><code style="color: #000000"><span style="color: #0000BB">&lt;?php phpinfo</span><span style="color: #007700">(); </span><span style="color: #0000BB">?&gt;</span></code></pre>

注意

注意:

return パラメータを使う場合、この関数は内部的に出力バッファリングを使います。 そのため、ob_start() コールバック関数の中では使えません。

生成される HTML マークアップは、変わる可能性があります。

参考

  • highlight_file() - ファイルの構文ハイライト表示
  • ハイライトに関する INI 設定


システムの高精度な時刻を取得する

  • ≪ highlight_string
  • ignore_user_abort ≫
  • PHP Manual
  • その他の関数
  • システムの高精度な時刻を取得する

hrtime

(PHP 7 >= 7.3.0, PHP 8)

hrtime — システムの高精度な時刻を取得する

説明

hrtime(bool $as_number = false): array|int|float|false

任意のタイミングから計測したシステムの高精度な時刻を取得します。 返されたタイムスタンプは単調であり、調整できません。

パラメータ

as_number

高精度の時刻を array で取得するか、数値で取得するかを指定します。

戻り値

as_number が false の場合は、 [秒, ナノ秒] の形式で数値の配列を返します。 true の場合、ナノ秒を (64ビットプラットフォームの場合) int または float (32ビットプラットフォームの場合) として返します。 失敗した場合は false を返します。

例

例1 hrtime() の使い方

<?php
echo hrtime(true), PHP_EOL;
print_r(hrtime());
?>

上の例の出力は、 たとえば以下のようになります。

10444739687370679
Array
(
    [0] => 10444739
    [1] => 687464812
)

参考

  • High resolution timing 拡張モジュール
  • microtime() - 現在の Unix タイムスタンプをマイクロ秒まで返す


クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する

  • ≪ hrtime
  • pack ≫
  • PHP Manual
  • その他の関数
  • クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する

ignore_user_abort

(PHP 4, PHP 5, PHP 7, PHP 8)

ignore_user_abort — クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する

説明

ignore_user_abort(?bool $enable = null): int

クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定します。

PHP をコマンドラインスクリプトとして実行していて スクリプトを終了させずに tty が消えた場合は、 次に何かを書こうとしたときにスクリプトが終了します。これは enable が true に設定されていても同じです。

パラメータ

enable

この値が指定されるか、null でない場合、この関数は ini 項目 ignore_user_abort に enable の値を設定します。 省略した場合、この関数は前の設定をそのまま返し、何も変更しません。

戻り値

以前の設定を表す integer 値を返します。

変更履歴

バージョン | 説明
8.0.0 | enable は、nullable になりました。

例

例1 ignore_user_abort() の例

<?php
// ユーザーによる中断を無視し、
// スクリプトを永遠に実行させます
ignore_user_abort(true);
set_time_limit(0);

echo 'PHP における接続ハンドリングのテスト';

// 無意味なループを繰り返します。
// きっと誰かが他のページに移動したり
// "中止" ボタンを押したりしてくれるでしょう
while(1)
{
// 接続失敗?
if(connection_status() != CONNECTION_NORMAL)
{
break;
}

// 10 秒間お休み
sleep(10);
}

// ここに到達したということは、while ループ内で
// 'break' が実行されたのでしょう

// ここで、ログを記録したりなどの必要な処理を行います
// これは、ブラウザに依存せずに行えます
?>

注意

PHP は、クライアントに情報を送信しない限り ユーザーが接続を切断したかどうかを検出できません。 単に echo 文を使っただけでは、情報が送信されたかどうかを保証できません。 flush() を参照ください。

参考

  • connection_aborted() - クライアントとの接続が切断されているかどうかを調べる
  • connection_status() - 接続ステータスのビットフィールドを返す
  • PHP における接続処理についての説明は 接続処理


データをバイナリ文字列にパックする

  • ≪ ignore_user_abort
  • php_strip_whitespace ≫
  • PHP Manual
  • その他の関数
  • データをバイナリ文字列にパックする

pack

(PHP 4, PHP 5, PHP 7, PHP 8)

pack — データをバイナリ文字列にパックする

説明

pack(string $format, mixed ...$values): string

指定された引数を format に基づいて バイナリ文字列にパックします。

この関数のアイデアは Perl からのものであり、フォーマット指定用の コードは Perl と同様に動作します。しかし、中には存在しない書式コードもあります。 たとえば Perl の "u" は存在しません。

符号付及び符号無しの区別は関数 unpack() にのみ 影響を与えます。関数 pack() は符号付及び符号無しの フォーマットコードのどちらでも同じ結果となることに注意しましょう。

パラメータ

format

フォーマット文字列は、 フォーマットコードの後にオプションの反復指定用引数が続く形式と なっています。反復指定用引数として整数値、または入力データの最後まで 反復を意味する * のどちらかを指定することができます。 a, A, h, H の場合、 反復数はそのデータ引数が取得する文字の数を指定します。反復数が @ の場合、 次のデータを置く場所の絶対位置を表します。その他の場合、反復数は データ引数が使われる数を指定し、結果のバイナリ文字列にパックされます。

現在、実装されているものを以下に示します。

pack() の書式文字
コード | 説明
a | NUL で埋めた文字列
A | 空白で埋めた文字列
h | 十六進文字列、下位ニブルが先
H | 十六進文字列、上位ニブルが先
c | signed char
C | unsigned char
s | signed short (常に 16 ビット、マシンのバイトオーダー)
S | unsigned short (常に 16 ビット、マシンのバイトオーダー)
n | unsigned short (常に 16 ビット、ビッグエンディアンバイトオーダー)
v | unsigned short (常に 16 ビット、リトルエンディアンバイトオーダー)
i | signed integer (サイズおよびバイトオーダーはマシン依存)
I | unsigned integer (サイズおよびバイトオーダーはマシン依存)
l | signed long (常に 32 ビット、マシンのバイトオーダー)
L | unsigned long (常に 32 ビット、マシンのバイトオーダー)
N | unsigned long (常に 32 ビット、ビッグエンディアンバイトオーダー)
V | unsigned long (常に 32 ビット、リトルエンディアンバイトオーダー)
q | signed long long (常に 64 ビット、マシンのバイトオーダー)
Q | unsigned long long (常に 64 ビット、マシンのバイトオーダー)
J | unsigned long long (常に 64 ビット、ビッグエンディアンバイトオーダー)
P | unsigned long long (常に 64 ビット、リトルエンディアンバイトオーダー)
f | float (サイズおよび表現はマシン依存)
g | float (サイズはマシン依存。 リトルエンディアンバイトオーダー)
G | float (サイズはマシン依存。 ビッグエンディアンバイトオーダー)
d | double (サイズおよび表現はマシン依存)
e | double (サイズはマシン依存。 リトルエンディアンバイトオーダー)
E | double (サイズはマシン依存。 ビッグエンディアンバイトオーダー)
x | NUL バイト
X | 1 バイト戻る
Z | NUL 埋め文字列
@ 絶対位置まで NUL で埋める

values

戻り値

バイナリ文字列を含むデータを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
7.2.0 | float と double 型は、ビッグエンディアンとリトルエンディアンを両方サポートしました。
7.0.15,7.1.1 | "e", "E", "g" および "G" コードが、float と double のバイトオーダーをサポートするために追加されました。

例

例1 pack() の例

<?php
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
?>

この結果のバイナリ文字列の長さは 6 バイト長で、バイト列 0x12, 0x34, 0x78, 0x56, 0x41, 0x42となります。

注意

警告

PHP は、int 型の値を内部的に格納する際に サイズがマシン依存の符号付き値 (C の long 型) を使うことに注意しましょう。int 型の範囲外の数値となる整数リテラルや演算結果は float として保持されます。この float 値を integer としてパックする際には まず最初に integer 型へのキャストを行います。 その結果、できあがるバイトパターンは期待通りにはならないかもしれません。

この問題にもっとも関連するのが、符号なしの数値で int 型で表現できるものをパックする場合です。 int 型のサイズが 32 ビットであるシステムでのキャスト結果は、 (実装で定義されている標準 C の符号なし型から符号付き型への変換に依存しますが) まるで int が符号なし整数であるかのような同一のバイトパターンになることがよくあります。 int 型のサイズが 64 ビットであるシステムでは、 たいていの場合は float の仮数部のサイズが足りず、 値の精度を損なわずに保持することができません。 ネイティブの 64 ビット C int 型を持つシステム (UNIX 系システムのほとんどは持っていません) では、上側の範囲の値で パック書式 I を使うための唯一の方法は、 希望する符号なし値と同じバイト表現になるような負の int 値を作ることになります。

参考

  • unpack() - バイナリ文字列からデータを切り出す


コメントと空白文字を取り除いたソースを返す

  • ≪ pack
  • sapi_windows_cp_conv ≫
  • PHP Manual
  • その他の関数
  • コメントと空白文字を取り除いたソースを返す

php_strip_whitespace

(PHP 5, PHP 7, PHP 8)

php_strip_whitespace — コメントと空白文字を取り除いたソースを返す

説明

php_strip_whitespace(string $filename): string

PHP のソースコード filename からコメントと 空白文字を取り除いたものを返します。これは、スクリプトの中で 実際のコードの量がどれくらいなのかを知るのに役立つでしょう。 これは コマンドライン から php -w を実行するのと同じです。

パラメータ

filename

PHP ファイルへのパス。

戻り値

成功した場合に処理済みのソースコード、失敗した場合に空の文字列を返します。

注意:

この関数は、 short_open_tag ini ディレクティブの値を考慮します。

例

例1 php_strip_whitespace() の例

<?php
// これは PHP のコメントです

/*
* これも PHP のコメントです
*/

echo php_strip_whitespace(__FILE__);
// 改行は空白文字と同じ扱いで、取り除かれます
do_nothing();
?>

上の例の出力は以下となります。

<?php
 echo php_strip_whitespace(__FILE__); do_nothing(); ?>

PHP のコメントが削除されていること、 最初の echo 文の後の改行や空白文字が削除されていることに注目しましょう。


文字列のコードページを別のものに変換する

  • ≪ php_strip_whitespace
  • sapi_windows_cp_get ≫
  • PHP Manual
  • その他の関数
  • 文字列のコードページを別のものに変換する

sapi_windows_cp_conv

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_conv — 文字列のコードページを別のものに変換する

説明

sapi_windows_cp_conv(int|string $in_codepage, int|string $out_codepage, string $subject): ?string

文字列のコードページを別のものに変換します。

パラメータ

in_codepage

subject 文字列のコードページ。 コードページの名前、または識別子を指定します。

out_codepage

subject を文字列が変換されるコードページ。 コードページの名前、または識別子を指定します。

subject

変換する文字列。

戻り値

out_codepage に変換された subject 文字列。 失敗した場合は null を返します。

エラー / 例外

この関数は、不正なコードページが与えられたり、 subject 文字列が in_codepage でなかった場合は、 E_WARNINGレベルの警告を発生させます。

参考

  • sapi_windows_cp_get() - 現在のコードページを取得する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


現在のコードページを取得する

  • ≪ sapi_windows_cp_conv
  • sapi_windows_cp_is_utf8 ≫
  • PHP Manual
  • その他の関数
  • 現在のコードページを取得する

sapi_windows_cp_get

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_get — 現在のコードページを取得する

説明

sapi_windows_cp_get(string $kind = ""): int

現在のコードページを取得します。

パラメータ

kind

取得するオペレーティングシステムのコードページ: 'ansi' または 'oem' それ以外の値は、現在のプロセスのコードページを参照します。

戻り値

コードページの識別子を返します。 kind が 'ansi' の場合、 オペレーティングシステムの、現在の ANSI コードページを返します。 kind が 'oem' の場合、 オペレーティングシステムの、現在の OEM コードページを返します。 それ以外の場合、現在のプロセスのコードページを返します。

参考

  • sapi_windows_cp_set() - 現在のプロセスのコードページを設定する


コードページがUTF-8と互換性があるかを返す

  • ≪ sapi_windows_cp_get
  • sapi_windows_cp_set ≫
  • PHP Manual
  • その他の関数
  • コードページがUTF-8と互換性があるかを返す

sapi_windows_cp_is_utf8

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_is_utf8 — コードページがUTF-8と互換性があるかを返す

説明

sapi_windows_cp_is_utf8(): bool

現在のプロセスのコードページが UTF-8 と互換性があるかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のプロセスのコードページが UTF-8 と互換性があるかを返します。

参考

  • sapi_windows_cp_get() - 現在のコードページを取得する


現在のプロセスのコードページを設定する

  • ≪ sapi_windows_cp_is_utf8
  • sapi_windows_generate_ctrl_event ≫
  • PHP Manual
  • その他の関数
  • 現在のプロセスのコードページを設定する

sapi_windows_cp_set

(PHP 7 >= 7.1.0, PHP 8)

sapi_windows_cp_set — 現在のプロセスのコードページを設定する

説明

sapi_windows_cp_set(int $codepage): bool

現在のプロセスのコードページを設定します。

パラメータ

codepage

コードページの識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • sapi_windows_cp_get() - 現在のコードページを取得する


CTRLイベント を別プロセスに送信する

  • ≪ sapi_windows_cp_set
  • sapi_windows_set_ctrl_handler ≫
  • PHP Manual
  • その他の関数
  • CTRLイベント を別プロセスに送信する

sapi_windows_generate_ctrl_event

(PHP 7 >= 7.4.0, PHP 8)

sapi_windows_generate_ctrl_event — CTRLイベント を別プロセスに送信する

説明

sapi_windows_generate_ctrl_event(int $event, int $pid = 0): bool

同じプロセスグループの別プロセスに CTRLイベント を送信する。

パラメータ

event

送信する CTRL イベント: PHP_WINDOWS_EVENT_CTRL_C または PHP_WINDOWS_EVENT_CTRL_BREAK

pid

イベントを送信するプロセスID。 0 に設定すると、プロセスグループに属する 全てのプロセスにイベントが送信されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sapi_windows_generate_ctrl_event() 関数の基本的な使い方

以下の例は、 CTRL+BREAK イベントを子プロセスに送信する方法を示しています。 この場合、ユーザーが CTRL+BREAK を押すまで、 子プロセスは I'm still alive を1秒ごとに表示します。 CTRL+BREAK は、子プロセスのみを終了させます。

<?php
// CTRL+BREAK イベントを子プロセスに送信する
sapi_windows_set_ctrl_handler('sapi_windows_generate_ctrl_event');

// 1秒ごとに echo する子プロセスを生成
$cmd = ['php', '-r', 'while (true) { echo "I\'m still alive\n"; sleep(1); }'];
$descspec = array(['pipe', 'r'], ['pipe', 'w'], ['pipe', 'w']);
$options = ['create_process_group' => true];
$proc = proc_open($cmd, $descspec, $pipes, null, null, $options);
while (true) {
echo fgets($pipes[1]);
}
?>

参考

  • proc_open() - コマンドを実行し、入出力用にファイルポインタを開く
  • sapi_windows_set_ctrl_handler() - CTRLイベント のハンドラを設定したり削除したりする


CTRLイベント のハンドラを設定したり削除したりする

  • ≪ sapi_windows_generate_ctrl_event
  • sapi_windows_vt100_support ≫
  • PHP Manual
  • その他の関数
  • CTRLイベント のハンドラを設定したり削除したりする

sapi_windows_set_ctrl_handler

(PHP 7 >= 7.4.0, PHP 8)

sapi_windows_set_ctrl_handler — CTRLイベント のハンドラを設定したり削除したりする

説明

sapi_windows_set_ctrl_handler(?callable $handler, bool $add = true): bool

CTRL イベントのハンドラを設定したり削除したりします。 これによって、Windows の CLI プロセスが、 CTRL+C や CTRL+BREAK イベントに割り込んだり、無視したり出来るようになります。 マルチスレッド環境では、この操作はメインスレッドからのみ可能です。

パラメータ

handler

設定したり削除したりするコールバック関数。 設定した場合、この関数は CTRL+C または CTRL+BREAK イベントが発生した場合にいつでも呼び出されます。 関数のシグネチャは次のとおりです:

handler(int $event): void
event
受け取った CTRL イベント; PHP_WINDOWS_EVENT_CTRL_C または PHP_WINDOWS_EVENT_CTRL_BREAK
null を handler に設定すると、 CTRL+Cイベント をプロセスに無視させますが、 CTRL+BREAK イベントは無視しません。

add

true に設定し、ハンドラを設定します。 false の場合、ハンドラは削除されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な sapi_windows_set_ctrl_handler() 関数の使い方

以下の例は、 CTRLイベント にどのように割り込むかを示しています。

<?php
function ctrl_handler(int $event)
{
switch ($event) {
case PHP_WINDOWS_EVENT_CTRL_C:
echo "You have pressed CTRL+C\n";
break;
case PHP_WINDOWS_EVENT_CTRL_BREAK:
echo "You have pressed CTRL+BREAK\n";
break;
}
}

sapi_windows_set_ctrl_handler('ctrl_handler');
while (true); // ハンドラがトリガできるように無限ループにする
?>

参考

  • sapi_windows_generate_ctrl_event() - CTRLイベント を別プロセスに送信する


Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する

  • ≪ sapi_windows_set_ctrl_handler
  • show_source ≫
  • PHP Manual
  • その他の関数
  • Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する

sapi_windows_vt100_support

(PHP 7 >= 7.2.0, PHP 8)

sapi_windows_vt100_support — Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する

説明

sapi_windows_vt100_support(resource $stream, ?bool $enable = null): bool

enable が省略されるか、null の場合、 この関数は stream の VT100 制御コードが有効になっている場合に true を返します。 無効になっている場合 false を返します。

enable が指定され、bool の場合、 この関数は stream の VT100 の機能を 有効/無効 にしようとします。 VT100 の機能が無事有効(または無効)にできた場合、この関数は true を返します。 失敗した場合 false を返します。

起動時に、PHP は STDOUT/STDERR の VT100 の機能を有効にしようとします。これらのストリームがファイルにリダイレクトされると、VT100 の機能は有効にならないかもしれません。

VT100 のサポートが有効な場合、VT100 のターミナルで有効な制御シーケンスが使えます。 これによって、ターミナルの出力を変更できます。Windows では、 これらの制御シーケンスは Console Virtual Terminal Sequence と呼ばれています。

警告

この関数は、Windows 10 API で実装されている ENABLE_VIRTUAL_TERMINAL_PROCESSING フラグを使います。 よって、古いWindowsバージョンでは VT100の機能は有効にならないかもしれません。

パラメータ

stream

この関数で操作するストリーム

enable

bool を指定すると、 (true の場合) VT100の機能が有効になり、 (false の場合) 無効になります。

戻り値

enable が省略されるか、null の場合、 VT100 の機能が有効になっている場合に true を返します。 無効になっている場合 false を返します。

enable に bool を指定すると、 成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | enable は、nullable になりました。

例

例1 sapi_windows_vt100_support() でデフォルトの状態を出力する

デフォルトでは、 STDOUT / STDERR で VT100 の機能が有効になっています。

php -r "var_export(sapi_windows_vt100_support(STDOUT));echo ' ';var_export(sapi_windows_vt100_support(STDERR));"

上の例の出力は、 たとえば以下のようになります。

true true

ストリームがリダイレクトされた場合、 VT100 の機能は有効になりません。

php -r "var_export(sapi_windows_vt100_support(STDOUT));echo ' ';var_export(sapi_windows_vt100_support(STDERR));" 2>NUL

上の例の出力は、 たとえば以下のようになります。

true false

例2 sapi_windows_vt100_support() で状態を変更する

ストリームがリダイレクトされた場合、 STDOUT や STDERR のVT100の機能は有効にできません。

php -r "var_export(sapi_windows_vt100_support(STDOUT, true));echo ' ';var_export(sapi_windows_vt100_support(STDERR, true));" 2>NUL

上の例の出力は、 たとえば以下のようになります。

true false

例3 VT100 のサポートを有効にする例

<?php
$out = fopen('php://stdout','w');
fwrite($out, 'Just forgot a lettr.');
// カーソルを2文字分左に移動
fwrite($out, "\033[2D");
// 空白をひとつ分挿入し、既存のテキストを右に移動させる -> Just forgot a lett r.
fwrite($out, "\033[1@");
fwrite($out, 'e');
?>

上の例の出力は以下となります。

Just forgot a letter.


highlight_file のエイリアス

  • ≪ sapi_windows_vt100_support
  • sleep ≫
  • PHP Manual
  • その他の関数
  • highlight_file のエイリアス

show_source

(PHP 4, PHP 5, PHP 7, PHP 8)

show_source — highlight_file() のエイリアス

説明

この関数は次の関数のエイリアスです。 highlight_file().


実行を遅延させる

  • ≪ show_source
  • sys_getloadavg ≫
  • PHP Manual
  • その他の関数
  • 実行を遅延させる

sleep

(PHP 4, PHP 5, PHP 7, PHP 8)

sleep — 実行を遅延させる

説明

sleep(int $seconds): int

seconds で与えられた秒数分プログラムの実行を遅延させます。

注意:

1秒以下の精度でプログラムの実行を遅延させる用途には、
usleep() を使って下さい。
なぜなら、sleep() は整数値を期待するためです。
たとえば sleep(0.25) は、プログラムの実行を
0 秒停止させてしまいます。

パラメータ

seconds

秒単位の停止時間。 (0 以上の値でなければなりません)

戻り値

成功した場合にゼロを返します。

シグナルで中断した場合、sleep() はゼロ以外の値を返します。 Windows では、この値は常に 192 (Windows API の定数 WAIT_IO_COMPLETION の値) です。 その他のプラットフォームでは、残りの遅延秒数を返します。

エラー / 例外

指定した seconds が負の場合、 この関数は ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | この関数は、負の seconds を指定すると ValueError をスローするようになりました。 これより前のバージョンでは、 E_WARNING が発生し、false を返していました。

例

例1 sleep() の例

<?php

// 現在の時刻
echo date('h:i:s') . "\n";

// 10 秒間遅延させる
sleep(10);

// 再開!
echo date('h:i:s') . "\n";

?>

この例の（10 秒後の）出力は以下のようになります。

05:31:23
05:31:33

参考

  • usleep() - マイクロ秒単位で実行を遅延する
  • time_nanosleep() - 秒およびナノ秒単位で実行を遅延する
  • time_sleep_until() - 指定した時刻まで実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する


システムの平均負荷を取得する

  • ≪ sleep
  • time_nanosleep ≫
  • PHP Manual
  • その他の関数
  • システムの平均負荷を取得する

sys_getloadavg

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

sys_getloadavg — システムの平均負荷を取得する

説明

sys_getloadavg(): array|false

過去 1、5、15 分間のシステムの平均負荷 (システムの実行キューの中のプロセス数) を表す三つの値を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

(過去 1、5、15 分間の) 三つの値を array で返します。 失敗した場合は false を返します。

例

例1 sys_getloadavg() の例

<?php
$load = sys_getloadavg();
if ($load[0] > 0.80) {
header('HTTP/1.1 503 Too busy, try again later');
die('Server too busy. Please try again later.');
}
?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。


秒およびナノ秒単位で実行を遅延する

  • ≪ sys_getloadavg
  • time_sleep_until ≫
  • PHP Manual
  • その他の関数
  • 秒およびナノ秒単位で実行を遅延する

time_nanosleep

(PHP 5, PHP 7, PHP 8)

time_nanosleep — 秒およびナノ秒単位で実行を遅延する

説明

time_nanosleep(int $seconds, int $nanoseconds): array|bool

指定した seconds および nanoseconds の時間だけプログラムの実行を遅延させます。

パラメータ

seconds

非負の整数である必要があります。

nanoseconds

十億よりも小さい非負の整数である必要があります。

注意: Windows では、与えられたナノ秒以上に長くスリープする可能性があります。 動作はハードウェア依存です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

シグナルによって遅延処理が中断された場合、以下の要素からなる連想配列を返します。

  • seconds - 残りの秒数
  • nanoseconds - 残りのナノ秒数

例

例1 time_nanosleep() の例

<?php
// 注意! もし配列が返された場合、これはうまく動作しません
if (time_nanosleep(0, 500000000)) {
echo "0.5 秒遅延しました。\n";
}

// こちらのほうがよいでしょう
if (time_nanosleep(0, 500000000) === true) {
echo "0.5 秒遅延しました。\n";
}

// そしてこれが最良の方法です
$nano = time_nanosleep(2, 100000);

if ($nano === true) {
echo "2 秒と 100 マイクロ秒だけ遅延しました。\n";
} elseif ($nano === false) {
echo "遅延に失敗しました。\n";
} elseif (is_array($nano)) {
$seconds = $nano['seconds'];
$nanoseconds = $nano['nanoseconds'];
echo "シグナルによって中断しました。\n";
echo "残りの秒数は $seconds 秒と $nanoseconds ナノ秒です。";
}
?>

参考

  • sleep() - 実行を遅延させる
  • usleep() - マイクロ秒単位で実行を遅延する
  • time_sleep_until() - 指定した時刻まで実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する


指定した時刻まで実行を遅延する

  • ≪ time_nanosleep
  • uniqid ≫
  • PHP Manual
  • その他の関数
  • 指定した時刻まで実行を遅延する

time_sleep_until

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

time_sleep_until — 指定した時刻まで実行を遅延する

説明

time_sleep_until(float $timestamp): bool

指定した timestamp までスクリプトの実行を遅延させます。

パラメータ

timestamp

スクリプトが再開する時刻。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

過去の timestamp を指定した場合、この関数は E_WARNING を発生させます。

例

例1 time_sleep_until() の例

<?php

// false を返し、警告を発生します
var_dump(time_sleep_until(time()-1));

// 高速なコンピュータ上でのみ動作します。実行を 0.2 秒遅延します。
var_dump(time_sleep_until(microtime(true)+0.2));

?>

注意

注意: すべてのシグナルは、スクリプトが再開した後で送信されます。

参考

  • sleep() - 実行を遅延させる
  • usleep() - マイクロ秒単位で実行を遅延する
  • time_nanosleep() - 秒およびナノ秒単位で実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する


時刻ベースの識別子を生成する

  • ≪ time_sleep_until
  • unpack ≫
  • PHP Manual
  • その他の関数
  • 時刻ベースの識別子を生成する

uniqid

(PHP 4, PHP 5, PHP 7, PHP 8)

uniqid — 時刻ベースの識別子を生成する

説明

uniqid(string $prefix = "", bool $more_entropy = false): string

マイクロ秒単位の現在時刻にもとづいた、識別子を取得します。 prefix が指定された場合は接頭辞が付きますし、 オプションでランダムに生成された値を付加します。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

警告

この関数は、戻り値の一意性を保証するものではありません。 なぜなら、値がマイクロ秒単位の現在時刻をベースとしていますし、 more_entropy を true にしたとしても、 わずかな量のランダムデータが付加されるだけだからです。

パラメータ

prefix

これが有用なのは、たとえば複数ホストで同じマイクロ秒で同時に ID を生成するような場合です。(このような場合は、同一ホストでも NTP によってシステム時刻が巻き戻された場合にも起こりえます)

空の prefix を指定すると、 返される文字列は 13 文字となります。 more_entropy が true の場合は 23 文字となります。

more_entropy

true にすると、uniqid() は 戻り値の最後にさらに別のエントロピーを (線形合同法を使用して) 追加します。これにより、結果が一意になる可能性を高めます。

戻り値

タイムスタンプにもとづいた識別子を文字列で返します。

警告

この関数は戻り値の一意性を完全に保証するものではありません。

例

例1 uniqid() の例

<?php
/* 一意なID、たとえば 4b3403665fea6 */
printf("uniqid(): %s\r\n", uniqid());

/* IDに接頭辞をつけることもできます。これは次のように書くのと
* 同じです
*
* $uniqid = $prefix . uniqid();
* $uniqid = uniqid($prefix);
*/
printf("uniqid('php_'): %s\r\n", uniqid('php_'));

/* more_entropy パラメータも使えます。Cygwin などのシステムで
* 必要となるでしょう。これは、uniqid() が生成する値をたとえば
* 4b340550242239.64159797 のような形式にします。
*/
printf("uniqid('', true): %s\r\n", uniqid('', true));
?>

注意

注意:

Cygwin でこの関数を動作させるには、 more_entropy を true にする必要があります。

参考

  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


バイナリ文字列からデータを切り出す

  • ≪ uniqid
  • usleep ≫
  • PHP Manual
  • その他の関数
  • バイナリ文字列からデータを切り出す

unpack

(PHP 4, PHP 5, PHP 7, PHP 8)

unpack — バイナリ文字列からデータを切り出す

説明

unpack(string $format, string $string, int $offset = 0): array|false

format に基づき、バイナリ文字列から配列に分解します。

分解した結果は連想配列に格納されます。 このようにするには、別のフォーマットコードを使用してそれらを スラッシュ / で区切る必要があります。 引数にリピータが含まれる場合の配列の要素名は、 指定した名前の後に順番に番号がついたものとなります。

Perl の関数に動きを近づけるために、以下の変更が行われています:

  • "a" は最後の NULL バイトを維持します。
  • "A" は最後の ASCII 空白文字 (スペース、タブ、改行、キャリッジリターン、 NULL バイト) をすべて取り除きます。
  • NULL 埋め文字列用に "Z" が追加されました。 これは最後の NULL バイトを取り除きます。

パラメータ

format

書式コードの説明は pack() を参照ください。

string

パックされたデータ。

offset

データ切り出しを開始するオフセット。

戻り値

バイナリ文字列を切り出した要素を含む連想配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
7.2.0 | float および double 型は、 ビッグエンディアンとリトルエンディアンの両方をサポートします。
7.1.0 | オプションの offset が追加されました。

例

例1 unpack() の例

<?php
$binarydata = "\x04\x00\xa0\x00";
$array = unpack("cchars/nint", $binarydata);
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [chars] => 4
    [int] => 160
)

例2 unpack() でのリピータの例

<?php
$binarydata = "\x04\x00\xa0\x00";
$array = unpack("c2chars/nint", $binarydata);
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [chars1] => 4
    [chars2] => 0
    [int] => 40960
)

注意

警告

PHP は内部的に整数を符号付きで保持することに注意しましょう。 大きな値の unsigned long を切り出した場合、PHP の内部で保持された値は、 同じ大きさの符号付き整数となり、符号無しを指定して切出された場合でも 結果は負の数となります。

警告

要素に名前をつけなければ、1 から始まる数値インデックスを用います。 名前をつけない要素が複数ある場合は、データが上書きされてしまうかもしれないことに注意しましょう。 それぞれの要素について、数値インデックスが 1 から割りあてられるからです。

例3 unpack() で名前のないキーを扱う例

<?php
$binarydata = "\x32\x42\x00\xa0";
$array = unpack("c2/n", $binarydata);
var_dump($array);
?>

上の例の出力は以下となります。

array(2) {
  [1]=>
  int(160)
  [2]=>
  int(66)
}

c で指定した最初の値が n で指定した値で上書きされることに注意しましょう。

参考

  • pack() - データをバイナリ文字列にパックする


マイクロ秒単位で実行を遅延する

  • ≪ unpack
  • 変更履歴 ≫
  • PHP Manual
  • その他の関数
  • マイクロ秒単位で実行を遅延する

usleep

(PHP 4, PHP 5, PHP 7, PHP 8)

usleep — マイクロ秒単位で実行を遅延する

説明

usleep(int $microseconds): void

指定したマイクロ秒数だけプログラムの実行を遅延させます。

パラメータ

microseconds

実行を停止するマイクロ秒数。マイクロ秒とは、一秒の百万分の一です。

注意: 1000000 より大きな値を指定すること (つまり、1秒以上スリープさせること) は、 オペレーティングシステムによってはサポートしていないかもしれません。 その場合は、sleep() を代わりに使ってください。

注意: スリープする時間は、わずかに長く (つまり、 microseconds 以上に) なる可能性があります。 これは、システムの動作、 呼び出し処理に時間が掛かること、 およびシステムタイマの精度が原因です。

戻り値

値を返しません。

例

例1 usleep() の例

<?php

// 現在の時刻
echo (new DateTime('now'))->format('H:i:s.v'), "\n";

// 2 ミリ秒待つ
usleep(2000);

// 復帰!
echo (new DateTime('now'))->format('H:i:s.v'), "\n";

// 30 ミリ秒待つ
usleep(30000);

// 再び復帰!
echo (new DateTime('now'))->format('H:i:s.v'), "\n";

?>

上の例の出力は以下となります。

11:13:28.005
11:13:28.007
11:13:28.037

参考

  • sleep() - 実行を遅延させる
  • time_nanosleep() - 秒およびナノ秒単位で実行を遅延する
  • time_sleep_until() - 指定した時刻まで実行を遅延する
  • set_time_limit() - 実行時間の最大値を制限する


変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

Version Function 説明


乱数生成器および、乱数関連の関数

  • はじめに
  • 定義済み定数
  • 例
  • Random 関数
    • getrandmax — 乱数の最大値を取得する
    • lcg_value — 複合線形合同法
    • mt_getrandmax — 乱数値の最大値を表示する
    • mt_rand — メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
    • mt_srand — メルセンヌ・ツイスター乱数生成器にシードを指定する
    • rand — 乱数を生成する
    • random_bytes — 暗号学的にセキュアな、ランダムなバイト列を生成する
    • random_int — 暗号学的にセキュアな方法で、等確率に出る整数を取得する
    • srand — 乱数生成器を初期化する
  • Random\Randomizer — Random\Randomizer クラス
    • Random\Randomizer::__construct — 新しい Randomizer を作成する
    • Random\Randomizer::getBytes — ランダムなバイト列を取得する
    • Random\Randomizer::getBytesFromString — 文字列からランダムにバイト列を取得する
    • Random\Randomizer::getFloat — 等確率に選んだ float の値を取得する
    • Random\Randomizer::getInt — 等確率に選ばれる整数を取得する
    • Random\Randomizer::nextFloat — 半開区間 [0.0, 1.0) から、float の値を取得する
    • Random\Randomizer::nextInt — 正の整数を取得する
    • Random\Randomizer::pickArrayKeys — ランダムに配列のキーを選択する
    • Random\Randomizer::__serialize — Randomizer オブジェクトをシリアライズする
    • Random\Randomizer::shuffleArray — 配列の順列を取得する
    • Random\Randomizer::shuffleBytes — 指定された文字列の、バイト単位の順列を取得する
    • Random\Randomizer::__unserialize — 指定した data を Randomizer オブジェクトに復元する
  • Random\Engine — Random\Engine インターフェイス
    • Random\Engine::generate — ランダムな値を生成する
  • Random\CryptoSafeEngine — Random\CryptoSafeEngine インターフェイス
  • Random\Engine\Secure — Random\Engine\Secure クラス
    • Random\Engine\Secure::generate — 暗号学的にセキュアな、ランダムなバイト列を生成する
  • Random\Engine\Mt19937 — Random\Engine\Mt19937 クラス
    • Random\Engine\Mt19937::__construct — 新しい Mt19937 エンジンを作成する
    • Random\Engine\Mt19937::__debugInfo — エンジンの内部的なステートを返す
    • Random\Engine\Mt19937::generate — 32ビットのランダムな値を生成する
    • Random\Engine\Mt19937::__serialize — Mt19937 オブジェクトをシリアライズする
    • Random\Engine\Mt19937::__unserialize — 指定した data を Mt19937 オブジェクトに復元する
  • Random\Engine\PcgOneseq128XslRr64 — Random\Engine\PcgOneseq128XslRr64 クラス
    • Random\Engine\PcgOneseq128XslRr64::__construct — 128 ビットのステートと XSL RR 変換を使う、新しいPCGエンジンを作成する
    • Random\Engine\PcgOneseq128XslRr64::__debugInfo — エンジンの内部的なステートを返す
    • Random\Engine\PcgOneseq128XslRr64::generate — 64ビットのランダムな値を生成する
    • Random\Engine\PcgOneseq128XslRr64::jump — エンジンの内部状態を、効率的に複数ステップ進める
    • Random\Engine\PcgOneseq128XslRr64::__serialize — PcgOneseq128XslRr64 オブジェクトをシリアライズする
    • Random\Engine\PcgOneseq128XslRr64::__unserialize — 指定した data を PcgOneseq128XslRr64 オブジェクトに復元する
  • Random\Engine\Xoshiro256StarStar — Random\Engine\Xoshiro256StarStar クラス
    • Random\Engine\Xoshiro256StarStar::__construct — 新しい xoshiro256** エンジンを作成する
    • Random\Engine\Xoshiro256StarStar::__debugInfo — エンジンの内部的なステートを返す
    • Random\Engine\Xoshiro256StarStar::generate — 64ビットのランダムな値を生成する
    • Random\Engine\Xoshiro256StarStar::jump — エンジンの内部状態を、効率的に 2^128 ステップ進める
    • Random\Engine\Xoshiro256StarStar::jumpLong — エンジンの内部状態を、効率的に 2^192 ステップ進める
    • Random\Engine\Xoshiro256StarStar::__serialize — Xoshiro256StarStar オブジェクトをシリアライズする
    • Random\Engine\Xoshiro256StarStar::__unserialize — 指定した data を Xoshiro256StarStar オブジェクトに復元する
  • Random\RandomError — Random\RandomError クラス
  • Random\BrokenRandomEngineError — Random\BrokenRandomEngineError クラス
  • Random\RandomException — Random\RandomException クラス


  • ≪ Random
  • 定義済み定数 ≫
  • PHP Manual
  • Random
  • はじめに

はじめに


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

MT_RAND_MT19937 (int)
正しい » Mt19937 (メルセンヌ・ツイスター) の実装をアルゴリズムが使うことを示します。 これは、Random\Engine\Mt19937::__construct() を使って Random\Engine\Mt19937 のインスタンスを作成するか、 mt_srand() を使って グローバルな メルセンヌ・ツイスター のシードを与える際に使います。
MT_RAND_PHP (int)
正しくない メルセンヌ・ツイスター の実装をアルゴリズムが使うことを示します。 これは、Random\Engine\Mt19937::__construct() を使って Random\Engine\Mt19937 のインスタンスを作成するか、 mt_srand() を使って グローバルな メルセンヌ・ツイスター のシードを与える際に使います。 正しくない実装は、PHP 7.1.0 より前のバージョンの mt_srand() と後方互換性を保つために残されています。
警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。


例

例1 Random Example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Random 関数

目次

  • getrandmax — 乱数の最大値を取得する
  • lcg_value — 複合線形合同法
  • mt_getrandmax — 乱数値の最大値を表示する
  • mt_rand — メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • mt_srand — メルセンヌ・ツイスター乱数生成器にシードを指定する
  • rand — 乱数を生成する
  • random_bytes — 暗号学的にセキュアな、ランダムなバイト列を生成する
  • random_int — 暗号学的にセキュアな方法で、等確率に出る整数を取得する
  • srand — 乱数生成器を初期化する


乱数の最大値を取得する

  • ≪ Random 関数
  • lcg_value ≫
  • PHP Manual
  • Random 関数
  • 乱数の最大値を取得する

getrandmax

(PHP 4, PHP 5, PHP 7, PHP 8)

getrandmax — 乱数の最大値を取得する

説明

getrandmax(): int

rand() をコールすることにより得られる最大の値を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

rand() が返す乱数の最大値を返します。

参考

  • rand() - 乱数を生成する
  • srand() - 乱数生成器を初期化する
  • mt_getrandmax() - 乱数値の最大値を表示する


複合線形合同法

  • ≪ getrandmax
  • mt_getrandmax ≫
  • PHP Manual
  • Random 関数
  • 複合線形合同法

lcg_value

(PHP 4, PHP 5, PHP 7, PHP 8)

lcg_value — 複合線形合同法

説明

lcg_value(): float

lcg_value() は、(0, 1)の範囲の疑似乱数を返します。 この関数は、周期が 2^31 - 85 および 2^31 - 249 の 2 つの CG を組み合わせます。 この関数の周期はこれら 2 つの素数の積と等価です。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

警告

乗算や加算(いわゆるアフィン変換)を使って、この関数の戻り値を異なる区間に拡大/縮小すると、結果の値に偏りが出るかもしれません。なぜなら、浮動小数点数は数直線上で均一に分布するわけではないからです。全ての値が浮動小数点数によって正確に表現できるとは限らないので、アフィン変換の結果が求める区間から外れた値になってしまう可能性もあります。

任意の区間内で、ランダムな浮動小数点数の値を生成する場合、 Random\Randomizer::getFloat() を使いましょう。 任意の区間内で、ランダムな整数の値を生成する場合、 Random\Randomizer::getInt() を使いましょう。

パラメータ

この関数にはパラメータはありません。

戻り値

0.0 と 1.0 の範囲の疑似乱数(0.0 と 1.0 を含みます)を、 浮動小数点数で返します。

参考

  • Random\Randomizer::getFloat() - 等確率に選んだ float の値を取得する
  • Random\Randomizer::getInt() - 等確率に選ばれる整数を取得する
  • random_int() - 暗号学的にセキュアな方法で、等確率に出る整数を取得する


乱数値の最大値を表示する

  • ≪ lcg_value
  • mt_rand ≫
  • PHP Manual
  • Random 関数
  • 乱数値の最大値を表示する

mt_getrandmax

(PHP 4, PHP 5, PHP 7, PHP 8)

mt_getrandmax — 乱数値の最大値を表示する

説明

mt_getrandmax(): int

mt_rand() のコールにより返される最大の値を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

mt_rand() を引数なしでコールしたときに取得できる乱数の最大値を返します。 mt_rand() の max に指定する値をこの値以下にしておけば、結果がスケールアップされて無作為性が低下することを避けられます。

参考

  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • mt_srand() - メルセンヌ・ツイスター乱数生成器にシードを指定する
  • getrandmax() - 乱数の最大値を取得する


メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

  • ≪ mt_getrandmax
  • mt_srand ≫
  • PHP Manual
  • Random 関数
  • メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

mt_rand

(PHP 4, PHP 5, PHP 7, PHP 8)

mt_rand — メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する

説明

mt_rand(): int
mt_rand(int $min, int $max): int

古い libc の多くの乱数発生器は、怪しげであるか特性が不明であったりし、 また低速でした。 mt_rand() 関数は、古い rand() の代替品となるものです。 この関数は、その特性が既知の乱数生成器 » メルセンヌ・ツイスター を使用し、 平均的な libc の rand()よりも 4 倍以上高速に乱数を生成します。

オプションの引数 min,max を付けずに コールした場合、mt_rand() は 0 から mt_getrandmax() の間の擬似乱数値を返します。 例えば、5 から 15 まで(端点を含む)の間の乱数値を得たい場合には mt_rand(5, 15) としてください。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

min

オプションで指定する、返される値の最小値 (デフォルトは 0)。

max

オプションで指定する、返される値の最大値 (デフォルトは mt_getrandmax())。

戻り値

min (あるいは 0) から max (あるいは mt_getrandmax()、それぞれ端点を含む) までの間のランダムな整数値を返します。 max が min より小さい場合は false を返します。

変更履歴

バージョン | 説明
7.2.0 | mt_rand() 関数の モジュロバイアスに関するバグが 修正されました。 これは、特定のシードを用いて生成したシーケンスは、64bit マシン上での PHP 7.1 と出力が異なる可能性があることを意味します。
7.1.0 | rand() は、mt_rand() の エイリアスになりました。
7.1.0 | mt_rand() は、固定の、正しいバージョンのメルセンヌツイスタ の アルゴリズム を使うように 更新されました。 古い振る舞いに戻すには、 mt_srand() 関数の第二引数に MT_RAND_PHP を指定して使ってください。

例

例1 mt_rand() の例

<?php
echo mt_rand(), "\n";
echo mt_rand(), "\n";

echo mt_rand(5, 15), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1604716014
1478613278
6

注意

警告

min から max までの幅を mt_getrandmax() の範囲内におさめる必要があります。 つまり、(max - min) <= mt_getrandmax() でなければいけないということです。この範囲をこえてしまうと、 mt_rand() が返す値のランダム性が、 本来あるべき姿よりも低くなってしまいます。

参考

  • mt_srand() - メルセンヌ・ツイスター乱数生成器にシードを指定する
  • mt_getrandmax() - 乱数値の最大値を表示する
  • random_int() - 暗号学的にセキュアな方法で、等確率に出る整数を取得する
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


メルセンヌ・ツイスター乱数生成器にシードを指定する

  • ≪ mt_rand
  • rand ≫
  • PHP Manual
  • Random 関数
  • メルセンヌ・ツイスター乱数生成器にシードを指定する

mt_srand

(PHP 4, PHP 5, PHP 7, PHP 8)

mt_srand — メルセンヌ・ツイスター乱数生成器にシードを指定する

説明

mt_srand(?int $seed = null, int $mode = MT_RAND_MT19937): void

seed により乱数生成器にシードを指定します。 seed を指定しなかった場合は、 ランダムな値を設定します。

注意: srand() または mt_srand() によりランダム数生成器にシードを与える必要はありません。 これは、この処理が自動的に行われるためです。

警告

Mt19937 (メルセンヌ・ツイスター) エンジンは、シードとして32ビットの整数だけを受け入れます。よって、219937-1 もの周期を持つにも関わらず、あり得るランダムなシーケンスの数はたかだか 232 (つまり 4,294,967,296) しかありません。

暗黙、または明示的にランダムなシードに依存する場合、 重複がそれ(4,294,967,296 個)よりも早く発生します。 誕生日のパラドックスによると、80,000 個以下のランダムな値を生成した場合でも、 シードの重複が 50% の確率で発生します。 重複したシードの 10% が、ざっと 30,000 個のランダムな値を生成したあとに発生します。

このため、無視できる確率以上に重複したシーケンスが発生してはいけないアプリケーションでは、Mt19937 は適していません。 再現可能なシードが必須の場合、 Random\Engine\Xoshiro256StarStar と Random\Engine\PcgOneseq128XslRr64 が、ランダムな値が衝突しにくく、より大きなシードをサポートしています。 再現可能なシードが必須でない場合、 Random\Engine\Secure が、暗号学的にセキュアなランダム性を提供します。

パラメータ

seed

seed をシードとした LCG を使って生成された値で 埋められるステート。 32ビットの符号なし整数値として解釈されます。

seed が省略されるか null の場合、 ランダムな符号なし 32ビットの整数が使われます。

mode

以下のいずれかの定数を使用して、使用するアルゴリズムの実装を指定します。

  • MT_RAND_MT19937: 正しいメルセンヌ・ツイスター実装を使います。 PHP 7.1.0 以降で利用可能です。
  • MT_RAND_PHP PHP 7.1.0 より前にデフォルトとして使用されていた、 正しくないメルセンヌ・ツイスター実装を使います。 このモードは、後方互換性を保つ際に使用できます。

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.3.0 | seed は、nullable になりました。
7.1.0 | srand() は、mt_srand() の エイリアスになりました。
7.1.0 | mt_rand() は、正しく修正されたメルセンヌ・ツイスター・アルゴリズムを使用するように 更新されました。 以前のアルゴリズムに戻すには、mt_srand() に MT_RAND_PHP を 第2引数として指定してください。

参考

  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • mt_getrandmax() - 乱数値の最大値を表示する
  • srand() - 乱数生成器を初期化する


乱数を生成する

  • ≪ mt_srand
  • random_bytes ≫
  • PHP Manual
  • Random 関数
  • 乱数を生成する

rand

(PHP 4, PHP 5, PHP 7, PHP 8)

rand — 乱数を生成する

説明

rand(): int
rand(int $min, int $max): int

オプションの引数 min,max を省略してコールした場合、rand() は 0 と getrandmax() の間の擬似乱数(整数)を返します。 例えば、5 から 15 まで（両端を含む）の乱数を得たい場合、 rand(5, 15) とします。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

注意: （Windows のような）いくつかのプラットフォームでは、getrandmax() は 32767 と小さな値となっています。 32767 より広い範囲にしたい場合、 min および max を指定することで、 これより大きな範囲の乱数を生成することができます。 もしくは、 mt_rand() をかわりに使用してみてください。

注意: PHP 7.1.0 以降、rand() は、 mt_rand() と同じ乱数生成器を使います。 下位互換性を保持するために、mt_rand() は false を返すのと対照的に、rand() は max が min よりも小さいことを許します。

パラメータ

min

返す値の最小値 (デフォルトは 0)。

max

返す値の最大値 (デフォルトは getrandmax())。

戻り値

min (あるいは 0) から max (あるいは getrandmax()、それぞれ端点を含む) までの間の疑似乱数値を返します。

変更履歴

バージョン | 説明
7.2.0 | rand() 関数のモジュロバイアスに関するバグが 修正されました。 これは、特定のシードから生成されるシーケンスが 64bit PHP 7.1 のそれとは異なる可能性があるということです。
7.1.0 | rand() は、mt_rand() の エイリアスになりました。

例

例1 rand() の例

<?php
echo rand(), "\n";
echo rand(), "\n";

echo rand(5, 15), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

7771
22264
11

注意

警告

min から max までの幅を mt_getrandmax() の範囲内におさめる必要があります。 つまり、(max - min) <= mt_getrandmax() でなければいけないということです。この範囲をこえてしまうと、 rand() が返す値のランダム性が、 低品質になってしまいます。

参考

  • srand() - 乱数生成器を初期化する
  • getrandmax() - 乱数の最大値を取得する
  • mt_rand() - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
  • random_int() - 暗号学的にセキュアな方法で、等確率に出る整数を取得する
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


暗号学的にセキュアな、ランダムなバイト列を生成する

  • ≪ rand
  • random_int ≫
  • PHP Manual
  • Random 関数
  • 暗号学的にセキュアな、ランダムなバイト列を生成する

random_bytes

(PHP 7, PHP 8)

random_bytes — 暗号学的にセキュアな、ランダムなバイト列を生成する

説明

random_bytes(int $length): string

等確率に選ばれるランダムなバイト列を含む、指定された長さ length の文字列を生成します。

返されるバイト列は完全にランダムに選ばれるため、 結果の文字列は印字できない文字や、 不正な UTF-8 のシーケンスとなる可能性があります。 よって、転送したり表示したりする時にはエンコードが必要かもしれません。

この関数が生成するランダムな値は、すべてのアプリケーションに対して適切です。 たとえば暗号化キーのような、長期間使うシークレットが挙げられます。

この関数が使う不規則性のソースは、優先度順に以下のとおりです:

  • Linux: » getrandom(), /dev/urandom

  • FreeBSD >= 12 (PHP >= 7.3): » getrandom(), /dev/urandom

  • Windows (PHP >= 7.2): » CNG-API

    Windows: » CryptGenRandom

  • macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 CCRandomGenerateBytes がコンパイル時に利用可能な場合): CCRandomGenerateBytes()

    macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), /dev/urandom

  • NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • DragonflyBSD (PHP >= 8.1): » getrandom(), /dev/urandom

  • Solaris (PHP >= 8.1): » getrandom(), /dev/urandom

  • 上記にあてはまらないオペレーティングシステムやPHP のバージョンの場合: /dev/urandom
  • どの不規則性のソースも利用できなかったり、 すべてのソースがランダムな値を生成できなかった場合、 Random\RandomException がスローされます。

注意: この関数は PHP 7.0 で追加されたものですが、PHP 5.2 から 5.6 までのバージョンで使える » ユーザーランドの実装 も公開されています。

パラメータ

length

返すべきランダムな文字列の長さをバイト単位で指定します。 1 以上でなければなりません。

戻り値

暗号学的にセキュアなランダムなバイト列を含んだ文字列を返します。

エラー / 例外

  • 適切な不規則性のソースが見つからない場合は Random\RandomException をスローします。
  • 不正な length が指定されると、 Error がスローされます。

変更履歴

バージョン | 説明
8.2.0 | CSPRNG が失敗した場合に、 Random\RandomException をスローするようになりました。 これより前のバージョンでは、Exception をスローしていました。

例

例1 random_bytes() の例

<?php
$bytes = random_bytes(5);
var_dump(bin2hex($bytes));
?>

上の例の出力は、 たとえば以下のようになります。

string(10) "385e33f741"

参考

  • Random\Randomizer::getBytes() - ランダムなバイト列を取得する
  • random_int() - 暗号学的にセキュアな方法で、等確率に出る整数を取得する
  • bin2hex() - バイナリのデータを16進表現に変換する
  • base64_encode() - MIME base64 方式でデータをエンコードする


暗号学的にセキュアな方法で、等確率に出る整数を取得する

  • ≪ random_bytes
  • srand ≫
  • PHP Manual
  • Random 関数
  • 暗号学的にセキュアな方法で、等確率に出る整数を取得する

random_int

(PHP 7, PHP 8)

random_int — 暗号学的にセキュアな方法で、等確率に出る整数を取得する

説明

random_int(int $min, int $max): int

指定された最小値と最大値の区間から、 等確率に選ばれるランダムな整数を生成します。

この関数が生成するランダムな値は、すべてのアプリケーションに対して適切です。 たとえば暗号化キーのような、長期間使うシークレットが挙げられます。

この関数が使う不規則性のソースは、優先度順に以下のとおりです:

  • Linux: » getrandom(), /dev/urandom

  • FreeBSD >= 12 (PHP >= 7.3): » getrandom(), /dev/urandom

  • Windows (PHP >= 7.2): » CNG-API

    Windows: » CryptGenRandom

  • macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 CCRandomGenerateBytes がコンパイル時に利用可能な場合): CCRandomGenerateBytes()

    macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), /dev/urandom

  • NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • DragonflyBSD (PHP >= 8.1): » getrandom(), /dev/urandom

  • Solaris (PHP >= 8.1): » getrandom(), /dev/urandom

  • 上記にあてはまらないオペレーティングシステムやPHP のバージョンの場合: /dev/urandom
  • どの不規則性のソースも利用できなかったり、 すべてのソースがランダムな値を生成できなかった場合、 Random\RandomException がスローされます。

注意: この関数は PHP 7.0 で追加されたものですが、PHP 5.2 から 5.6 までのバージョンで使える » ユーザーランドの実装 も公開されています。

パラメータ

min

返される最小値。

max

返される最大値。

戻り値

min と max の範囲で、 暗号学的にセキュアな方法で、 閉区間 [min, max] の中から等確率に出るよう選ばれた整数値を返します。 min と max　 も返される値に含みます。

エラー / 例外

  • 適切な不規則性のソースが見つからない場合は Random\RandomException をスローします。
  • max が min より小さい場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.2.0 | CSPRNG が失敗した場合に、 Random\RandomException をスローするようになりました。 これより前のバージョンでは、Exception をスローしていました。

例

例1 random_int() の例

<?php
var_dump(random_int(100, 999));
var_dump(random_int(-1000, 0));
?>

上の例の出力は、 たとえば以下のようになります。

int(248)
int(-898)

参考

  • Random\Randomizer::getInt() - 等確率に選ばれる整数を取得する
  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する


乱数生成器を初期化する

  • ≪ random_int
  • Random\Randomizer ≫
  • PHP Manual
  • Random 関数
  • 乱数生成器を初期化する

srand

(PHP 4, PHP 5, PHP 7, PHP 8)

srand — 乱数生成器を初期化する

説明

srand(?int $seed = null, int $mode = MT_RAND_MT19937): void

シード seed で乱数生成器を初期化します。 seed に 0 を指定した場合はランダムな値が設定されます。

注意: srand() または mt_srand() によりランダム数生成器にシードを与える必要はありません。 これは、この処理が自動的に行われるためです。

警告

Mt19937 (メルセンヌ・ツイスター) エンジンは、シードとして32ビットの整数だけを受け入れます。よって、219937-1 もの周期を持つにも関わらず、あり得るランダムなシーケンスの数はたかだか 232 (つまり 4,294,967,296) しかありません。

暗黙、または明示的にランダムなシードに依存する場合、 重複がそれ(4,294,967,296 個)よりも早く発生します。 誕生日のパラドックスによると、80,000 個以下のランダムな値を生成した場合でも、 シードの重複が 50% の確率で発生します。 重複したシードの 10% が、ざっと 30,000 個のランダムな値を生成したあとに発生します。

このため、無視できる確率以上に重複したシーケンスが発生してはいけないアプリケーションでは、Mt19937 は適していません。 再現可能なシードが必須の場合、 Random\Engine\Xoshiro256StarStar と Random\Engine\PcgOneseq128XslRr64 が、ランダムな値が衝突しにくく、より大きなシードをサポートしています。 再現可能なシードが必須でない場合、 Random\Engine\Secure が、暗号学的にセキュアなランダム性を提供します。

注意: PHP 7.1.0 以降、srand() は、mt_srand() のエイリアスになりました。

パラメータ

seed

seed をシードとした LCG を使って生成された値で 埋められるステート。 32ビットの符号なし整数値として解釈されます。

seed が省略されるか null の場合、 ランダムな符号なし 32ビットの整数が使われます。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.3.0 | seed は、nullable になりました。
7.1.0 | srand() は、 mt_srand() の エイリアスになりました。

参考

  • rand() - 乱数を生成する
  • getrandmax() - 乱数の最大値を取得する
  • mt_srand() - メルセンヌ・ツイスター乱数生成器にシードを指定する


Random\Randomizer クラス

(PHP 8 >= 8.2.0)

はじめに

Random\Engine が提供するランダムな値に対する、高レベルインターフェイスを提供します。

クラス概要

final class Random\Randomizer {
/* プロパティ */
public readonly Random\Engine $engine;
/* メソッド */
public __construct(?Random\Engine $engine = null)
public getBytes(int $length): string
public getBytesFromString(string $string, int $length): string
public getFloat(float $min, float $max, Random\IntervalBoundary $boundary = Random\IntervalBoundary::ClosedOpen): float
public getInt(int $min, int $max): int
public nextFloat(): float
public nextInt(): int
public pickArrayKeys(array $array, int $num): array
public __serialize(): array
public shuffleArray(array $array): array
public shuffleBytes(string $bytes): string
public __unserialize(array $data): void
}

プロパティ

engine

Random\Randomizer のメソッドに与えるランダムな値の、低レベルのソース。

目次

  • Random\Randomizer::__construct — 新しい Randomizer を作成する
  • Random\Randomizer::getBytes — ランダムなバイト列を取得する
  • Random\Randomizer::getBytesFromString — 文字列からランダムにバイト列を取得する
  • Random\Randomizer::getFloat — 等確率に選んだ float の値を取得する
  • Random\Randomizer::getInt — 等確率に選ばれる整数を取得する
  • Random\Randomizer::nextFloat — 半開区間 [0.0, 1.0) から、float の値を取得する
  • Random\Randomizer::nextInt — 正の整数を取得する
  • Random\Randomizer::pickArrayKeys — ランダムに配列のキーを選択する
  • Random\Randomizer::__serialize — Randomizer オブジェクトをシリアライズする
  • Random\Randomizer::shuffleArray — 配列の順列を取得する
  • Random\Randomizer::shuffleBytes — 指定された文字列の、バイト単位の順列を取得する
  • Random\Randomizer::__unserialize — 指定した data を Randomizer オブジェクトに復元する


新しい Randomizer を作成する

  • ≪ Random\Randomizer
  • Random\Randomizer::getBytes ≫
  • PHP Manual
  • Random\Randomizer
  • 新しい Randomizer を作成する

Random\Randomizer::__construct

(PHP 8 >= 8.2.0)

Random\Randomizer::__construct — 新しい Randomizer を作成する

説明

public Random\Randomizer::__construct(?Random\Engine $engine = null)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

engine

ランダムな値を生成するのに使う Random\Engine

engine が省略されるか、null の場合は、 新しい Random\Engine\Secure オブジェクトを使います。

例

例1 Random\Randomizer::__construct() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


ランダムなバイト列を取得する

  • ≪ Random\Randomizer::__construct
  • Random\Randomizer::getBytesFromString ≫
  • PHP Manual
  • Random\Randomizer
  • ランダムなバイト列を取得する

Random\Randomizer::getBytes

(PHP 8 >= 8.2.0)

Random\Randomizer::getBytes — ランダムなバイト列を取得する

説明

public Random\Randomizer::getBytes(int $length): string

等確率に選ばれるランダムなバイト列を含む、指定された長さ length の文字列を生成します。

返されるバイト列は完全にランダムに選ばれるため、 結果の文字列は印字できない文字や、 不正な UTF-8 のシーケンスとなる可能性があります。 よって、転送したり表示したりする時にはエンコードが必要かもしれません。

パラメータ

length

返すべきランダムな文字列の長さをバイト単位で指定します。1 以上でなければなりません。

戻り値

指定された長さの、ランダムなバイト列を含んだ文字列を返します。

エラー / 例外

  • length の値が 1 より小さい場合、 ValueError をスローします。
  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::getBytes() の例

<?php
$r = new \Random\Randomizer();

echo bin2hex($r->getBytes(8)), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

ebdbe93cd56682c2

参考

  • random_bytes() - 暗号学的にセキュアな、ランダムなバイト列を生成する
  • base64_encode() - MIME base64 方式でデータをエンコードする
  • Random\Randomizer::getBytesFromString() - 文字列からランダムにバイト列を取得する


文字列からランダムにバイト列を取得する

  • ≪ Random\Randomizer::getBytes
  • Random\Randomizer::getFloat ≫
  • PHP Manual
  • Random\Randomizer
  • 文字列からランダムにバイト列を取得する

Random\Randomizer::getBytesFromString

(PHP 8 >= 8.3.0)

Random\Randomizer::getBytesFromString — 文字列からランダムにバイト列を取得する

説明

public Random\Randomizer::getBytesFromString(string $string, int $length): string

入力となる string から等確率に選択した、ランダムなバイト列を含む文字列を、 指定された length だけ返します。

特定のバイトが選ばれる確率は、 入力となる string に占める割合に比例します。 それぞれのバイトの頻度が同じ場合、 それぞれのバイトが選ばれる確率は等しくなります。

パラメータ

string

戻り値のために、バイト列が選択される文字列

length

バイト単位で返されるランダムな文字列の長さ。 1 以上でなければいけません。

戻り値

入力された string から取得したランダムなバイト列を、 指定された長さだけ含む文字列を返します。

エラー / 例外

  • string が空の場合、 ValueError がスローされます。
  • length が 1 より小さい場合、 ValueError がスローされます。
  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::getBytesFromString() の例

<?php
$randomizer = new \Random\Randomizer();

printf(
"%s.example.com",
$randomizer->getBytesFromString('abcdefghijklmnopqrstuvwxyz0123456789', 16)
);
?>

上の例の出力は、 たとえば以下のようになります。

3zsw04eiubcf82jd.example.com

例2 2要素認証向けにランダムなコードを生成する

<?php
// The Secure engine is the default, but we make it explicit, because
// multi-factor codes are security sensitive.
$randomizer = new \Random\Randomizer(new \Random\Engine\Secure());

echo implode('-', str_split($randomizer->getBytesFromString('0123456789', 20), 5));
?>

上の例の出力は、 たとえば以下のようになります。

11551-80418-27047-42075

例3 一様分布していない文字列から選択する

<?php
$randomizer = new \Random\Randomizer();

echo $randomizer->getBytesFromString('aaaaabcdef', 20);
?>

上の例の出力は、 たとえば以下のようになります。

fddacbeaaeaaacaaaaca

参考

  • Random\Randomizer::getBytes() - ランダムなバイト列を取得する


等確率に選んだ float の値を取得する

  • ≪ Random\Randomizer::getBytesFromString
  • Random\Randomizer::getInt ≫
  • PHP Manual
  • Random\Randomizer
  • 等確率に選んだ float の値を取得する

Random\Randomizer::getFloat

(PHP 8 >= 8.3.0)

Random\Randomizer::getFloat — 等確率に選んだ float の値を取得する

説明

public Random\Randomizer::getFloat(float $min, float $max, Random\IntervalBoundary $boundary = Random\IntervalBoundary::ClosedOpen): float

指定した区間に一様に分散した浮動小数点数の中から、等確率に選んだ値を返します。

精度が限られているため、 全ての実数が正確に浮動小数点数として表現できるとは限りません。 数値が正確に表現できない場合、値は表現できるもっとも近い値に丸められます。 さらに浮動小数点数の値は、数直線全体に均等に分布しているわけではありません。 浮動小数点数の値は 2進数の指数を使うので、隣り合うふたつの値の距離は、 それぞれの2のべき乗ごとに2倍になります。 つまり: 1.0 と 2.0 の間で表現できる 浮動小数点数 の数は、2.0 と 4.0 の間で表現できる数、4.0 と 8.0 の間で表現できる数、8.0 と 16.0 の間で表現できる数と同じ... といった具合です。

こうした理由から、例えば2つの整数を割るなどして、 要求された区間内の任意の数をランダムサンプリングすると、 分布が偏る可能性があります。 必要な丸めを行うと、 浮動小数点数の値によっては別の値より多くの頻度で返されることがあります。 浮動小数点数の値の密度が変わる2のべき乗周辺の値については、特にそれが当てはまります。

Random\Randomizer::getFloat() は、 指定した区間内で正確に表現でき、 かつ一様に分散した浮動小数点数の可能な限り大きな集合から、 等確率に値を返すアルゴリズムを実装します。 選択可能な浮動小数点数の間の距離 (ステップサイズ) は、 密度が最も小さい浮動小数点数の間の距離、つまり、 絶対値がより大きな区間境界の浮動小数点数の距離に一致します。 これは、区間が2のべき乗を1つ以上横切る場合、 与えられた区間内で表現可能な浮動小数点数の値がすべて返されるとは限らないということです。 ステップは、絶対値の大きい区間境界から始まります。 これは、ステップを正確に表現可能な浮動小数点数と一致させるためです。

閉区間の境界は、常に選択可能な浮動小数点数の集合に含まれます。 よって、区間のサイズがステップサイズの正確な倍数でなく、 かつ絶対値が小さな方の境界が閉じている場合、 その境界とそれにもっとも近い選択可能な浮動小数点数との間の距離は、 ステップサイズよりも小さくなります。

警告

このメソッドが返す float の値を後処理すると、 値の一様な分布を壊す可能性があります。なぜなら、 数学演算に含まれる中間的な浮動小数点数の値は暗黙のうちに丸められているからです。 指定された区間は、できるだけ望ましい区間と一致させるべきですし、 丸め処理はこのメソッドが選択した値をユーザーに表示させる直前に明示的に実行すべきです。

サンプルの浮動小数点表現を使った、アルゴリズムの説明

アルゴリズムがどのように動作するかの例を示すために、 3ビットの仮数を使用する浮動小数点表現を考えてみましょう。 この表現は、連続する2のべき乗の間で、8つの異なる浮動小数点数を表現することができます。 つまり、1.0 と 2.0 の間では 0.125 のすべてのステップサイズを正確に表現でき、 2.0 と 4.0 の間では 0.25 のすべてのステップサイズを正確に表現できるということです。 実際には、PHP の float は 52 ビットの仮数を使用しており、 それぞれの 2 のべき乗の間で 252 個の異なる値を表現することができます。 つまり、以下の数が、1.0 と 4.0 の範囲で正確に表現できるということです。

  • 1.0
  • 1.125
  • 1.25
  • 1.375
  • 1.5
  • 1.625
  • 1.75
  • 1.875
  • 2.0
  • 2.25
  • 2.5
  • 2.75
  • 3.0
  • 3.25
  • 3.5
  • 3.75
  • 4.0

さてここで、$randomizer->getFloat(1.625, 2.5, IntervalBoundary::ClosedOpen) がコールされた場合を考えてみましょう。 つまり、1.625 から始まり、2.5 までのランダムな値 (ただし 2.5 そのものは含みません) を要求するということです。 このメソッドのアルゴリズムは、 まず絶対値の大きい境界(2.5)でのステップサイズを決定します。 今回の境界の場合、ステップサイズは 0.25 です。

ここで、要求された区間のサイズは 0.875 であり、 0.25 の正確な倍数ではないことに注意してください。 もしアルゴリズムが下界 1.625からステップを開始すると、 正確に表現できない 2.125 が現れた時点で、暗黙の丸めが発生します。 そのため、アルゴリズムは上界 2.5 からステップを開始するのです。 選択可能な値は、以下のとおりです:

  • 2.25
  • 2.0
  • 1.75
  • 1.625
2.5 は選択可能な値に含まれません。 なぜなら、要求された区間の上界が開いているからです。 1.625 は選択可能な値に含まれます。 この値は最も近い値 1.75 との距離が 0.125 であり、以前決定したステップサイズ 0.25より小さいのですが、 それにも関わらず、含まれます。 その理由は、要求された区間は下側の境界(1.625)で閉じており、 閉じた境界は常に含まれるからです。

最後に、アルゴリズムは4つの選択可能な値から等確率で値をランダムに選び、それを返します。

2つの整数値を割るやり方ではなぜダメなのか

上の例では、2のべき乗で区切られたそれぞれの区間に、 表現可能な浮動小数点数が8個あります。 ランダムな浮動小数点数を生成するのに、 なぜ2つの整数を割る方法がうまくいかないのかを示すために、 0.0 から 1.0 を含まない右開きの区間に、16個の一様に分散した浮動小数点数があるとしましょう。 そのうち半分は、0.5 から 1.0 までの間で8つの値として正確に表現できますが、 残りの半分は 0.0 から 1.0 までの間でステップサイズが 0.0625 の値です。 これらの値は、0 から 15 の間のランダムな整数を 16 で割ることによって、以下のうちのひとつを簡単に生成することができます:

  • 0.0
  • 0.0625
  • 0.125
  • 0.1875
  • 0.25
  • 0.3125
  • 0.375
  • 0.4375
  • 0.5
  • 0.5625
  • 0.625
  • 0.6875
  • 0.75
  • 0.8125
  • 0.875
  • 0.9375

このランダムな浮動小数点の値は、 1.625 から 2.75 まで (2.75 を含まない) の右開きの区間に、 区間の大きさ(0.875) を掛け合わせ、 最小の 1.625 を足すことで拡大変換できます。 この、いわゆるアフィン変換の結果は、以下のような値になります:

  • 1.625 は、1.625 に丸められます
  • 1.679 は、1.625 に丸められます
  • 1.734 は、1.75 に丸められます
  • 1.789 は、1.75 に丸められます
  • 1.843 は、1.875 に丸められます
  • 1.898 は、1.875 に丸められます
  • 1.953 は、2.0 に丸められます
  • 2.007 は、2.0 に丸められます
  • 2.062 は、2.0 に丸められます
  • 2.117 は、2.0 に丸められます
  • 2.171 は、2.25 に丸められます
  • 2.226 は、2.25 に丸められます
  • 2.281 は、2.25 に丸められます
  • 2.335 は、2.25 に丸められます
  • 2.390 は、2.5 に丸められます
  • 2.445 は、2.5 に丸められます
上界の値 2.5 が、 開区間であるため除外されるべきなのに、返されてしまう点に注意してください。 また、2.0 と 2.25 が、 他の値に比べて2倍の確率で返されることにも注意しましょう。

パラメータ

min

区間の下限

max

区間の上限

boundary

区間の境界を戻り値に含めるかどうかを指定します。

戻り値

min, max, boundary で指定した区間に一様に分散した float の中から、等確率に選んだ値を返します。 min と max が戻り値に含まれるかどうかは、 boundary の値次第です。

エラー / 例外

  • min の値が有限(is_finite())でない場合、 ValueError がスローされます。
  • max の値が有限(is_finite())でない場合、 ValueError がスローされます。
  • 指定された区間に何も値が含まれない場合、 ValueError がスローされます。
  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::getFloat() の例

<?php
$randomizer = new \Random\Randomizer();

// 緯度の粒度は経度の粒度の2倍であることに注意しましょう。
//
// 緯度については、-90 から 90 の値をとります
// 経度については、180 という値は取れますが、-180 は取れません。
// なぜなら、-180 と 180 は同じ経度を指しているからです。
printf(
"Lat: %+.6f Lng: %+.6f",
$randomizer->getFloat(-90, 90, \Random\IntervalBoundary::ClosedClosed),
$randomizer->getFloat(-180, 180, \Random\IntervalBoundary::OpenClosed),
);
?>

上の例の出力は、 たとえば以下のようになります。

Lat: +69.244304 Lng: -53.548951

注意

注意:

このメソッドは、望ましい振る舞いを得るために » Drawing Random Floating-Point Numbers from an Interval. Frederic Goualard, ACM Trans. Model. Comput. Simul., 32:3, 2022 に記されている γ-section アルゴリズムを実装しています。

参考

  • Random\Randomizer::nextFloat() - 半開区間 [0.0, 1.0) から、float の値を取得する
  • Random\Randomizer::getInt() - 等確率に選ばれる整数を取得する


等確率に選ばれる整数を取得する

  • ≪ Random\Randomizer::getFloat
  • Random\Randomizer::nextFloat ≫
  • PHP Manual
  • Random\Randomizer
  • 等確率に選ばれる整数を取得する

Random\Randomizer::getInt

(PHP 8 >= 8.2.0)

Random\Randomizer::getInt — 等確率に選ばれる整数を取得する

説明

public Random\Randomizer::getInt(int $min, int $max): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

min

返される最小値。

max

返される最大値。

戻り値

閉区間 [min, max] の中から、 等確率に出るよう選ばれた整数値を返します。 min と max も返される値に含みます。

エラー / 例外

  • max が min より小さい場合、 ValueError がスローされます。
  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::getInt() の例

<?php
$r = new \Random\Randomizer();

// 範囲内の整数をランダムに出力します
echo $r->getInt(1, 100), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

42

参考

  • random_int() - 暗号学的にセキュアな方法で、等確率に出る整数を取得する
  • Random\Randomizer::getFloat() - 等確率に選んだ float の値を取得する


半開区間 [0.0, 1.0) から、float の値を取得する

  • ≪ Random\Randomizer::getInt
  • Random\Randomizer::nextInt ≫
  • PHP Manual
  • Random\Randomizer
  • 半開区間 [0.0, 1.0) から、float の値を取得する

Random\Randomizer::nextFloat

(PHP 8 >= 8.3.0)

Random\Randomizer::nextFloat — 半開区間 [0.0, 1.0) から、float の値を取得する

説明

public Random\Randomizer::nextFloat(): float

半開区間(左閉右開) に一様に分散した float を等確率に返します。 区間には 0.0 を含み、1.0 までですが、 1.0 そのものは含みません。

返される float の値が、指定された右開の部分区間にある確率は、 部分区間の大きさに比例します。 つまり、返される float が 0.5 より小さい 確率は50%ということです。これは float が 少なくとも 0.5 以上である確率と等しくなります。 同様に、返される float が、区間 0.2 から 0.25 未満までに収まる確率は、ちょうど 5% になります。

この性質を使うと、Random\Randomizer::nextFloat() を活用して返される float が指定された確率 より小さい ことをチェックすることで、 指定された確率でランダムな boolean 値を生成することが可能になります。

注意:

Random\Randomizer::nextFloat() が返す可能性がある float の値の範囲は、 Randomizer::getFloat(0.0, 1.0, IntervalBoundary::ClosedOpen) と同じです。

ですが、内部的な Random\Randomizer::nextFloat() の実装はより効率的です。

警告

乗算や加算(いわゆるアフィン変換)を使って、 この関数の戻り値を異なる区間に拡大/縮小すると、 結果の値に偏りが出るかもしれません。 なぜなら、浮動小数点数は数直線上で均一に分布するわけではないからです。 全ての値が浮動小数点数によって正確に表現できるとは限らないので、 アフィン変換の結果が暗黙の丸め処理によって求める区間から外れた値になってしまう可能性もあります。 アフィン変換の結果生じる問題の 詳細な説明 は、Random\Randomizer::getFloat() のドキュメントに説明があります。

任意の区間内でランダムな float の値を生成するには、 Random\Randomizer::getFloat() を使います。任意の区間内でランダムな整数を生成するには、 Random\Randomizer::getInt() を使います。

パラメータ

この関数にはパラメータはありません。

戻り値

半開区間 [0.0, 1.0) (IntervalBoundary::ClosedOpen) に一様に分散した float を等確率に返します。 返される値には 0.0 を含みますが、 1.0 は含みません。

エラー / 例外

  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::nextFloat() の例

<?php
$r = new \Random\Randomizer();

// 返される bool 値は、指定された確率で true になります
$chance = 0.5;

$bool = $r->nextFloat() < $chance;

echo ($bool ? "You won" : "You lost"), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

You won

例2 アフィン変換を使った間違った拡大演算

<?php
final class MaxEngine implements Random\Engine {
public function generate(): string {
return "\xff";
}
}

$randomizer = new \Random\Randomizer(new MaxEngine);

$min = 3.5;
$max = 4.5;

// 以下は絶対やらないで！:
//
// 以下のコードは nextFloat() が 1を絶対に含まない半開区間からサンプリングしたに
// も関わらず、4.5 を出力します。
printf("Wrong scaling: %.17g", $randomizer->nextFloat() * ($max - $min) + $min);

// 正しくは、以下のようにします:
// $randomizer->getFloat($min, $max, \Random\IntervalBoundary::ClosedOpen);
?>

上の例の出力は以下となります。

Wrong scaling: 4.5

参考

  • Random\Randomizer::getFloat() - 等確率に選んだ float の値を取得する


正の整数を取得する

  • ≪ Random\Randomizer::nextFloat
  • Random\Randomizer::pickArrayKeys ≫
  • PHP Manual
  • Random\Randomizer
  • 正の整数を取得する

Random\Randomizer::nextInt

(PHP 8 >= 8.2.0)

Random\Randomizer::nextInt — 正の整数を取得する

説明

public Random\Randomizer::nextInt(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

Random\Engine::generate() が返したバイト数に応じて、 0 から最大値までの正の整数を返します。 正確な最大値は、2$engine_bytes * 8 - 1 - 1 で計算できます。

エラー / 例外

  • 不整合を避けるため、32ビットの PHP は Random\Engine::generate() の出力サイズが 32ビットを超えた場合、 Random\RandomException をスローします。なぜなら、 選択した整数値を欠けることなく返せないからです。 この振る舞いは、64ビットネイティブのエンジン Random\Engine\PcgOneseq128XslRr64 と Random\Engine\Xoshiro256StarStar に影響します。 4バイト以上のランダムな値を返す、ユーザーが使えるあらゆるエンジンにも影響します。
  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::nextInt() の例

<?php
$r = new \Random\Randomizer();

// "次の" 整数をランダムに出力します
echo $r->nextInt(), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

8041689838856078718


ランダムに配列のキーを選択する

  • ≪ Random\Randomizer::nextInt
  • Random\Randomizer::__serialize ≫
  • PHP Manual
  • Random\Randomizer
  • ランダムに配列のキーを選択する

Random\Randomizer::pickArrayKeys

(PHP 8 >= 8.2.0)

Random\Randomizer::pickArrayKeys — ランダムに配列のキーを選択する

説明

public Random\Randomizer::pickArrayKeys(array $array, int $num): array

指定された array に存在する、 num 個の異なる配列のキーを等確率に選びます。

指定された array の、 個々のキーが返される確率は等しくなります。

警告

配列のキーの選ばれ方は、 指定された array の内部構造に依存します。 ふたつの配列が等しく、かつ Random\Engine の内部的なステートが等しくても、 指定された配列の作られ方によっては返されるキーが異なる可能性があります。

パラメータ

array

キーを選ぶ配列

num

返すべき配列のキーの数。 1 以上かつ、 array の要素数以下である必要があります。

戻り値

array の 異なる num 個のキーを含んだ配列を返します。

返される配列はリスト (array_is_list()) になります。 これは array_keys() が返す配列のサブセットです。

エラー / 例外

  • num の値が 1 より小さかったり、 array の要素数より大きい場合、 ValueError がスローされます。
  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::pickArrayKeys() の例

<?php
$r = new \Random\Randomizer();

$fruits = [ 'red' => '??', 'green' => '??', 'yellow' => '??', 'pink' => '??', 'purple' => '??' ];

// 配列のキーをふたつ、ランダムに取り出します
echo "Keys: ", implode(', ', $r->pickArrayKeys($fruits, 2)), "\n";

// 別の配列のキーを3つ取り出します
echo "Keys: ", implode(', ', $r->pickArrayKeys($fruits, 3)), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Keys: yellow, purple
Keys: red, green, yellow

例2 ランダムに値を取り出す

<?php
$r = new \Random\Randomizer();

$fruits = [ 'red' => '??', 'green' => '??', 'yellow' => '??', 'pink' => '??', 'purple' => '??' ];

$keys = $r->pickArrayKeys($fruits, 2);
// 取り出したキーの値を検索します
$selection = array_map(
static fn ($key) => $fruits[$key],
$keys
);

echo "Values: ", implode(', ', $selection), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Values: ??, ??

参考

  • array_keys() - 配列のキーすべて、あるいはその一部を返す


Randomizer オブジェクトをシリアライズする

  • ≪ Random\Randomizer::pickArrayKeys
  • Random\Randomizer::shuffleArray ≫
  • PHP Manual
  • Random\Randomizer
  • Randomizer オブジェクトをシリアライズする

Random\Randomizer::__serialize

(PHP 8 >= 8.2.0)

Random\Randomizer::__serialize — Randomizer オブジェクトをシリアライズする

説明

public Random\Randomizer::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Randomizer::__serialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


配列の順列を取得する

  • ≪ Random\Randomizer::__serialize
  • Random\Randomizer::shuffleBytes ≫
  • PHP Manual
  • Random\Randomizer
  • 配列の順列を取得する

Random\Randomizer::shuffleArray

(PHP 8 >= 8.2.0)

Random\Randomizer::shuffleArray — 配列の順列を取得する

説明

public Random\Randomizer::shuffleArray(array $array): array

指定された array のあり得る順列から、 等確率に選ばれた順列を返します。

指定された array のあり得る順列それぞれが、返される確率は等しくなります。

パラメータ

array

値をシャッフルする配列

指定された配列は変更されません。

戻り値

array の値の順列を返します。

指定された array のキーは保存されません。 つまり、返される配列はリスト (array_is_list()) になります。

エラー / 例外

  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::shuffleArray() の例

<?php
$r = new \Random\Randomizer();

$fruits = [ 'red' => '??', 'green' => '??', 'yellow' => '??', 'pink' => '??', 'purple' => '??' ];

// 配列をシャッフルします
echo "Salad: ", implode(', ', $r->shuffleArray($fruits)), "\n";

// 再度シャッフルします
echo "Another Salad: ", implode(', ', $r->shuffleArray($fruits)), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Salad: ??, ??, ??, ??, ??
Another Salad: ??, ??, ??, ??, ??


指定された文字列の、バイト単位の順列を取得する

  • ≪ Random\Randomizer::shuffleArray
  • Random\Randomizer::__unserialize ≫
  • PHP Manual
  • Random\Randomizer
  • 指定された文字列の、バイト単位の順列を取得する

Random\Randomizer::shuffleBytes

(PHP 8 >= 8.2.0)

Random\Randomizer::shuffleBytes — 指定された文字列の、バイト単位の順列を取得する

説明

public Random\Randomizer::shuffleBytes(string $bytes): string

指定された bytes のあり得る順列から、 等確率に選ばれた順列を返します。

指定された bytes のあり得る順列それぞれが、返される確率は等しくなります。

パラメータ

bytes

バイト単位でシャッフルする文字列

指定された文字列は変更されません。

戻り値

bytes の、 バイト単位の順列を返します。

エラー / 例外

  • Random\Randomizer::$engine に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

例

例1 Random\Randomizer::shuffleBytes() の例

<?php
$r = new \Random\Randomizer();

// 文字列中のバイト列をシャッフルします
echo "≪", $r->shuffleBytes("PHP is great!"), "≫\n";
?>

上の例の出力は、 たとえば以下のようになります。

≪ ga rHs!PPiet≫

例2 バイト単位でシャッフルするとUnicode文字は壊れる

<?php
$r = new \Random\Randomizer();

$unicode = "??, ??, ??, ??, ??";
$shuffled = $r->shuffleBytes( $unicode );

// バイト単位で ASCII でない文字をシャッフルすると、値が壊れてしまいます。
// その結果、(Unicode 置換文字によって示される)不正なシーケンスが生成されたり、
// 完全に異なる文字が出力に現れたりします。
echo "Original: ", $unicode, "\n";
echo "Shuffled: ≪", $shuffled, "≫\n";
echo "Shuffled Bytes: ", bin2hex($shuffled), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Original: ??, ??, ??, ??, ??
Shuffled: ≪? ??,???????,? ?? ?, ?,??≫
Shuffled Bytes: 87208e912c8d9fa5f0f0f09f8d9f2cf09f208c9d20f02c209f2c8d8d


指定した data を Randomizer オブジェクトに復元する

  • ≪ Random\Randomizer::shuffleBytes
  • Random\Engine ≫
  • PHP Manual
  • Random\Randomizer
  • 指定した data を Randomizer オブジェクトに復元する

Random\Randomizer::__unserialize

(PHP 8 >= 8.2.0)

Random\Randomizer::__unserialize — 指定した data を Randomizer オブジェクトに復元する

説明

public Random\Randomizer::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

戻り値

値を返しません。

例

例1 Random\Randomizer::__unserialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Random\Engine インターフェイス

(PHP 8 >= 8.2.0)

はじめに

Random\Engine は、ランダムな値の低レベルなソースを提供します。 ここから返されたランダムな値は、 高レベルAPIで操作することで消費されます。 Random\Engine インターフェイスを使うと、 ランダムな値を生成するためのアルゴリズムを切り替えることができます。 何故切り替えるのかというと、 それぞれのアルゴリズムは特定のユースケースに応じて、 異なるトレードオフの特性を持つからです。 とても高速に値を生成するものの、 生成するランダムな値の品質は低いアルゴリズムもあれば、 それよりは低速ですが、よりよいランダムな値を生成するアルゴリズムもあります。 さらに、Random\Engine\Secure が提供する、 暗号学的にセキュアな、ランダムな値を生成するものまであります。

PHP は 異なるユースケースに対応した、 複数の Random\Engine を提供します。 とても高速なパフォーマンスを追求したり、 再現可能なシーケンスをアプリケーション側で必須としない限り、 CSPRNG をバックエンドにした Random\Engine\Secure を、 デフォルトとして選択することを推奨します。

インターフェイス概要

interface Random\Engine {
/* メソッド */
public generate(): string
}

目次

  • Random\Engine::generate — ランダムな値を生成する


ランダムな値を生成する

  • ≪ Random\Engine
  • Random\CryptoSafeEngine ≫
  • PHP Manual
  • Random\Engine
  • ランダムな値を生成する

Random\Engine::generate

(PHP 8 >= 8.2.0)

Random\Engine::generate — ランダムな値を生成する

説明

public Random\Engine::generate(): string

ランダムな値を生成し、アルゴリズムの内部的なステートをひとつ進めます。

ランダムな値は、ランダムなバイト列を含んだバイナリ文字列として表現されます。 そう表現することで、アルゴリズムが生成したランダムなビットを、 曖昧さがない形で解釈できるようになります。 これはたとえば、アルゴリズムによって異なる出力サイズを調整する目的があります。

整数の値をネイティブで操作するアルゴリズムは、 たとえば pack() 関数に P フォーマットコードを指定するなどして、リトルエンディアンで整数値を返すべきです。 Random\Randomizer が提供する高レベルインターフェイスは、 数値表現が必要な場合、返されたランダムなバイト列を符号なしのリトルエンディアンとして解釈します。

返された文字列の個々のビットは、 等確率に、かつ独立に選ばれた状態にあることを強く推奨します。 アプリケーションによっては、正しく動作する要件が、 ビットレベルでランダムであることに依存する場合があるからです。 たとえば 線形合同法(LCGs) は、整数の下位ビットについては品質が低いランダムな値を生成するため、 ビットレベルでランダムな状態を必須とするアプリケーションには適していません。

パラメータ

この関数にはパラメータはありません。

戻り値

ランダムなバイト列を含む、空でない文字列を返します。

注意: Random\Randomizer は内部的に、符号なしの64ビット整数を使って動作します。 返される文字列が 64ビット(8バイト)以上のランダムな文字列である場合、 64ビットを超えるバイト列は無視されます。 他のアプリケーションでは、 64ビット以上のデータを一度に処理できるものがあるかもしれません。

エラー / 例外

  • ランダムな値を生成できなかった場合、 Random\RandomException がスローされます。 値を生成している途中でスローされる他の Exception は、 キャッチされて Random\RandomException でラップされます。
  • 返される文字列が空の場合、 Random\Randomizer が Random\BrokenRandomEngineError をスローします。
  • 実装されているアルゴリズムにとても強い偏りがある場合、 Random\Randomizer が Random\BrokenRandomEngineError をスローする場合があります。 これは、偏りがない結果を返すために棄却サンプリングが必要な時に、 無限ループに陥ることを避けるためです。

例

例1 Random\Engine::generate() の例

<?php
/**
* 65536 を法とする LCG(Linear Congruential Generator, 線形合同法)を実装し、
* 61 を掛けて 17 を足し、8ビットの整数を返します。
*
* 注意: このエンジンはデモの用途のみに適した実装です。
* LCG は一般的に、低い品質のランダムな値しか生成しませんし、
* ここで示す実装は、16ビットというとても短い周期しか持っていません。
* これは、殆どの現実の需要を満たしません。
*/
final class LinearCongruentialGenerator implements \Random\Engine
{
private int $state;

public function __construct(?int $seed = null)
{
if ($seed === null) {
$seed = random_int(0, 0xffff);
}

$this->state = $seed & 0xffff;
}

public function generate(): string
{
$this->state = (61 * $this->state + 17) & 0xffff;

return pack('C', $this->state >> 8);
}
}

$r = new \Random\Randomizer(
new LinearCongruentialGenerator(seed: 1)
);

echo "Lucky Number: ", $r->getInt(0, 99), "\n";
?>

上の例の出力は以下となります。

Lucky Number: 4


Random\CryptoSafeEngine インターフェイス

(PHP 8 >= 8.2.0)

はじめに

Random\Engine が、暗号学的にセキュアなランダム値を返すことを示す、マーカーインターフェイスです。

インターフェイス概要

interface Random\CryptoSafeEngine extends Random\Engine {
/* 継承したメソッド */
public Random\Engine::generate(): string
}


Random\Engine\Secure クラス

(PHP 8 >= 8.2.0)

はじめに

オペレーティングシステムの CSPRNG を使い、暗号学的にセキュアな、ランダムな値を生成します。

この Random\Engine が生成するランダムな値は、 暗号化キーのような長期間使うシークレットを含む、すべてのアプリケーションで適切です。

とても高速なパフォーマンスを追求したり、 再現可能なシーケンスをアプリケーション側で必須としない限り、 Random\Engine\Secure エンジンを安全なデフォルトの選択として推奨します。

クラス概要

final class Random\Engine\Secure implements Random\CryptoSafeEngine {
/* メソッド */
public generate(): string
}

目次

  • Random\Engine\Secure::generate — 暗号学的にセキュアな、ランダムなバイト列を生成する


暗号学的にセキュアな、ランダムなバイト列を生成する

  • ≪ Random\Engine\Secure
  • Random\Engine\Mt19937 ≫
  • PHP Manual
  • Random\Engine\Secure
  • 暗号学的にセキュアな、ランダムなバイト列を生成する

Random\Engine\Secure::generate

(PHP 8 >= 8.2.0)

Random\Engine\Secure::generate — 暗号学的にセキュアな、ランダムなバイト列を生成する

説明

public Random\Engine\Secure::generate(): string

暗号学的にセキュアな、ランダムなバイト列を返します。

この関数が使う不規則性のソースは、優先度順に以下のとおりです:

  • Linux: » getrandom(), /dev/urandom

  • FreeBSD >= 12 (PHP >= 7.3): » getrandom(), /dev/urandom

  • Windows (PHP >= 7.2): » CNG-API

    Windows: » CryptGenRandom

  • macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 CCRandomGenerateBytes がコンパイル時に利用可能な場合): CCRandomGenerateBytes()

    macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), /dev/urandom

  • NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom

  • DragonflyBSD (PHP >= 8.1): » getrandom(), /dev/urandom

  • Solaris (PHP >= 8.1): » getrandom(), /dev/urandom

  • 上記にあてはまらないオペレーティングシステムやPHP のバージョンの場合: /dev/urandom
  • どの不規則性のソースも利用できなかったり、 すべてのソースがランダムな値を生成できなかった場合、 Random\RandomException がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

暗号学的にセキュアな、ランダムなバイト列を文字列として返します。 長さは PHP_INT_SIZE です。

エラー / 例外

  • 適切な不規則性のソースが見つからない場合は Random\RandomException をスローします。


Random\Engine\Mt19937 クラス

(PHP 8 >= 8.2.0)

はじめに

» Mt19937 (メルセンヌ・ツイスター) アルゴリズムを実装したクラスです。

クラス概要

final class Random\Engine\Mt19937 implements Random\Engine {
/* メソッド */
public __construct(?int $seed = null, int $mode = MT_RAND_MT19937)
public __debugInfo(): array
public generate(): string
public __serialize(): array
public __unserialize(array $data): void
}

目次

  • Random\Engine\Mt19937::__construct — 新しい Mt19937 エンジンを作成する
  • Random\Engine\Mt19937::__debugInfo — エンジンの内部的なステートを返す
  • Random\Engine\Mt19937::generate — 32ビットのランダムな値を生成する
  • Random\Engine\Mt19937::__serialize — Mt19937 オブジェクトをシリアライズする
  • Random\Engine\Mt19937::__unserialize — 指定した data を Mt19937 オブジェクトに復元する


新しい Mt19937 エンジンを作成する

  • ≪ Random\Engine\Mt19937
  • Random\Engine\Mt19937::__debugInfo ≫
  • PHP Manual
  • Random\Engine\Mt19937
  • 新しい Mt19937 エンジンを作成する

Random\Engine\Mt19937::__construct

(PHP 8 >= 8.2.0)

Random\Engine\Mt19937::__construct — 新しい Mt19937 エンジンを作成する

説明

public Random\Engine\Mt19937::__construct(?int $seed = null, int $mode = MT_RAND_MT19937)

警告

Mt19937 (メルセンヌ・ツイスター) エンジンは、シードとして32ビットの整数だけを受け入れます。よって、219937-1 もの周期を持つにも関わらず、あり得るランダムなシーケンスの数はたかだか 232 (つまり 4,294,967,296) しかありません。

暗黙、または明示的にランダムなシードに依存する場合、 重複がそれ(4,294,967,296 個)よりも早く発生します。 誕生日のパラドックスによると、80,000 個以下のランダムな値を生成した場合でも、 シードの重複が 50% の確率で発生します。 重複したシードの 10% が、ざっと 30,000 個のランダムな値を生成したあとに発生します。

このため、無視できる確率以上に重複したシーケンスが発生してはいけないアプリケーションでは、Mt19937 は適していません。 再現可能なシードが必須の場合、 Random\Engine\Xoshiro256StarStar と Random\Engine\PcgOneseq128XslRr64 が、ランダムな値が衝突しにくく、より大きなシードをサポートしています。 再現可能なシードが必須でない場合、 Random\Engine\Secure が、暗号学的にセキュアなランダム性を提供します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

符号なし32ビットの整数として解釈される seed をシードとし、 線形合同法(LCG) を使って生成された値でステートを埋めます。

seed が省略されるか、null の場合は、 ランダムな符号なし32ビットの整数を使います。

mode

使用するアルゴリズムの実装を指定するために、 以下の定数のうちの一つを指定します:

  • MT_RAND_MT19937: 正しい メルセンヌ・ツイスター の実装です。
  • MT_RAND_PHP: 正しくない メルセンヌ・ツイスター の実装です。 PHP 7.1.0 より前のバージョンの mt_srand() と互換性を保つために残されています。

警告

この機能は PHP 8.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

例

例1 Random\Engine\Mt19937::__construct() の例

<?php
// ランダムな32ビットのシードを使います
$e = new \Random\Engine\Mt19937();

$r = new \Random\Randomizer($e);
?>


エンジンの内部的なステートを返す

  • ≪ Random\Engine\Mt19937::__construct
  • Random\Engine\Mt19937::generate ≫
  • PHP Manual
  • Random\Engine\Mt19937
  • エンジンの内部的なステートを返す

Random\Engine\Mt19937::__debugInfo

(PHP 8 >= 8.2.0)

Random\Engine\Mt19937::__debugInfo — エンジンの内部的なステートを返す

説明

public Random\Engine\Mt19937::__debugInfo(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Engine\Mt19937::__debugInfo() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


32ビットのランダムな値を生成する

  • ≪ Random\Engine\Mt19937::__debugInfo
  • Random\Engine\Mt19937::__serialize ≫
  • PHP Manual
  • Random\Engine\Mt19937
  • 32ビットのランダムな値を生成する

Random\Engine\Mt19937::generate

(PHP 8 >= 8.2.0)

Random\Engine\Mt19937::generate — 32ビットのランダムな値を生成する

説明

public Random\Engine\Mt19937::generate(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

符号なし32ビットの整数値を、リトルエンディアンで表現した文字列を返します。


Mt19937 オブジェクトをシリアライズする

  • ≪ Random\Engine\Mt19937::generate
  • Random\Engine\Mt19937::__unserialize ≫
  • PHP Manual
  • Random\Engine\Mt19937
  • Mt19937 オブジェクトをシリアライズする

Random\Engine\Mt19937::__serialize

(PHP 8 >= 8.2.0)

Random\Engine\Mt19937::__serialize — Mt19937 オブジェクトをシリアライズする

説明

public Random\Engine\Mt19937::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Engine\Mt19937::__serialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


指定した data を Mt19937 オブジェクトに復元する

  • ≪ Random\Engine\Mt19937::__serialize
  • Random\Engine\PcgOneseq128XslRr64 ≫
  • PHP Manual
  • Random\Engine\Mt19937
  • 指定した data を Mt19937 オブジェクトに復元する

Random\Engine\Mt19937::__unserialize

(PHP 8 >= 8.2.0)

Random\Engine\Mt19937::__unserialize — 指定した data を Mt19937 オブジェクトに復元する

説明

public Random\Engine\Mt19937::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

戻り値

値を返しません。

例

例1 Random\Engine\Mt19937::__unserialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Random\Engine\PcgOneseq128XslRr64 クラス

(PHP 8 >= 8.2.0)

はじめに

128 ビットのステートと、XSL-RR 変換を用いて、64 ビットの出力を生成する » Permuted congruential generator (PCG) を実装したクラスです。

クラス概要

final class Random\Engine\PcgOneseq128XslRr64 implements Random\Engine {
/* メソッド */
public __construct(string|int|null $seed = null)
public __debugInfo(): array
public generate(): string
public jump(int $advance): void
public __serialize(): array
public __unserialize(array $data): void
}

目次

  • Random\Engine\PcgOneseq128XslRr64::__construct — 128 ビットのステートと XSL RR 変換を使う、新しいPCGエンジンを作成する
  • Random\Engine\PcgOneseq128XslRr64::__debugInfo — エンジンの内部的なステートを返す
  • Random\Engine\PcgOneseq128XslRr64::generate — 64ビットのランダムな値を生成する
  • Random\Engine\PcgOneseq128XslRr64::jump — エンジンの内部状態を、効率的に複数ステップ進める
  • Random\Engine\PcgOneseq128XslRr64::__serialize — PcgOneseq128XslRr64 オブジェクトをシリアライズする
  • Random\Engine\PcgOneseq128XslRr64::__unserialize — 指定した data を PcgOneseq128XslRr64 オブジェクトに復元する


128 ビットのステートと XSL RR 変換を使う、新しいPCGエンジンを作成する

  • ≪ Random\Engine\PcgOneseq128XslRr64
  • Random\Engine\PcgOneseq128XslRr64::__debugInfo ≫
  • PHP Manual
  • Random\Engine\PcgOneseq128XslRr64
  • 128 ビットのステートと XSL RR 変換を使う、新しいPCGエンジンを作成する

Random\Engine\PcgOneseq128XslRr64::__construct

(PHP 8 >= 8.2.0)

Random\Engine\PcgOneseq128XslRr64::__construct — 128 ビットのステートと XSL RR 変換を使う、新しいPCGエンジンを作成する

説明

public Random\Engine\PcgOneseq128XslRr64::__construct(string|int|null $seed = null)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

128ビット(16バイト) の符号なし整数が、 どのように与えられるかを seed のタイプを使って指定します。

タイプ | 説明
null | ランダムな16バイトのステートを、 CSPRNG を使って生成し、埋めます。
int | 0 に設定することでステートを埋め、エンジンの内部状態をひとつ進めます。 そして、seed を64ビットの符号なし整数と解釈して加算し、 エンジンの内部状態をさらにもうひとつ進めます。
string | 16バイトの文字列を、リトルエンディアン、 かつ符号なし128ビットの整数と解釈してステートを埋めます。

エラー / 例外

  • seedが文字列で、長さが16バイトでなかった場合、 ValueError がスローされます。

例

例1 Random\Engine\PcgOneseq128XslRr64::__construct() の例

<?php
// ランダムな128ビットのシードを使います。
$e = new \Random\Engine\PcgOneseq128XslRr64();

$r = new \Random\Randomizer($e);
?>

例2 文字列からシードを作る

<?php
$string = "My string seed";

// $string を128ビットのシードに変換するために、
// SHA-256 を切り捨てる形で文字列をハッシュ化し、バイナリで出力します。
// 同じ文字列を使うと、同じランダムなシーケンスが生成されます。
$e = new \Random\Engine\PcgOneseq128XslRr64(
substr(hash('sha256', $string, binary: true), 0, 16)
);

echo bin2hex($e->generate()), "\n";
?>

上の例の出力は以下となります。

8333ef59315b16d8


エンジンの内部的なステートを返す

  • ≪ Random\Engine\PcgOneseq128XslRr64::__construct
  • Random\Engine\PcgOneseq128XslRr64::generate ≫
  • PHP Manual
  • Random\Engine\PcgOneseq128XslRr64
  • エンジンの内部的なステートを返す

Random\Engine\PcgOneseq128XslRr64::__debugInfo

(PHP 8 >= 8.2.0)

Random\Engine\PcgOneseq128XslRr64::__debugInfo — エンジンの内部的なステートを返す

説明

public Random\Engine\PcgOneseq128XslRr64::__debugInfo(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Engine\PcgOneseq128XslRr64::__debugInfo() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


64ビットのランダムな値を生成する

  • ≪ Random\Engine\PcgOneseq128XslRr64::__debugInfo
  • Random\Engine\PcgOneseq128XslRr64::jump ≫
  • PHP Manual
  • Random\Engine\PcgOneseq128XslRr64
  • 64ビットのランダムな値を生成する

Random\Engine\PcgOneseq128XslRr64::generate

(PHP 8 >= 8.2.0)

Random\Engine\PcgOneseq128XslRr64::generate — 64ビットのランダムな値を生成する

説明

public Random\Engine\PcgOneseq128XslRr64::generate(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

符号なし64ビットの整数値を、リトルエンディアンで表現した文字列を返します。


エンジンの内部状態を、効率的に複数ステップ進める

  • ≪ Random\Engine\PcgOneseq128XslRr64::generate
  • Random\Engine\PcgOneseq128XslRr64::__serialize ≫
  • PHP Manual
  • Random\Engine\PcgOneseq128XslRr64
  • エンジンの内部状態を、効率的に複数ステップ進める

Random\Engine\PcgOneseq128XslRr64::jump

(PHP 8 >= 8.2.0)

Random\Engine\PcgOneseq128XslRr64::jump — エンジンの内部状態を、効率的に複数ステップ進める

説明

public Random\Engine\PcgOneseq128XslRr64::jump(int $advance): void

Random\Engine\PcgOneseq128XslRr64::generate() が何回も呼ばれたかのように、 アルゴリズムのステートを advance で指定された回数分進めます。

パラメータ

advance

ステートを進める回数。 0 以上でなければなりません。

戻り値

値を返しません。

エラー / 例外

  • advance が 0 より小さい場合、 ValueError がスローされます。

例

例1 Random\Engine\PcgOneseq128XslRr64::jump() の例

<?php
$a = new \Random\Engine\PcgOneseq128XslRr64(0);
$b = clone $a;

for ($i = 0; $i < 1_000; $i++) {
$a->generate();
}
$b->jump(1_000);

echo "A: ", bin2hex($a->generate()), "\n";
echo "B: ", bin2hex($b->generate()), "\n";
?>

上の例の出力は以下となります。

A: e6d0d5813913a424
B: e6d0d5813913a424

例2 Randomizer のメソッドは、複数回エンジンをコールしても構わない

<?php
$a = new \Random\Randomizer(new \Random\Engine\PcgOneseq128XslRr64(42659));
$b = new \Random\Randomizer(clone $a->engine);

$a->getInt(1, 1572864); // generate() を2回呼ぶ
$a->getInt(1, 1572864);

$b->engine->jump(2);

// 最初の ->getInt() のコールは ->generate() を2回呼んでいるので
// ->jump(2) を実行したあとは、エンジンは一致しません。
echo "A: ", bin2hex($a->engine->generate()), "\n";
echo "B: ", bin2hex($b->engine->generate()), "\n";

// ここで、B エンジンは A エンジンと一致します
echo "B: ", bin2hex($b->engine->generate()), "\n";
?>

上の例の出力は以下となります。

A: 1e9f3107d56653d0
B: a156c0086dd79d44
B: 1e9f3107d56653d0


PcgOneseq128XslRr64 オブジェクトをシリアライズする

  • ≪ Random\Engine\PcgOneseq128XslRr64::jump
  • Random\Engine\PcgOneseq128XslRr64::__unserialize ≫
  • PHP Manual
  • Random\Engine\PcgOneseq128XslRr64
  • PcgOneseq128XslRr64 オブジェクトをシリアライズする

Random\Engine\PcgOneseq128XslRr64::__serialize

(PHP 8 >= 8.2.0)

Random\Engine\PcgOneseq128XslRr64::__serialize — PcgOneseq128XslRr64 オブジェクトをシリアライズする

説明

public Random\Engine\PcgOneseq128XslRr64::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Engine\PcgOneseq128XslRr64::__serialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


指定した data を PcgOneseq128XslRr64 オブジェクトに復元する

  • ≪ Random\Engine\PcgOneseq128XslRr64::__serialize
  • Random\Engine\Xoshiro256StarStar ≫
  • PHP Manual
  • Random\Engine\PcgOneseq128XslRr64
  • 指定した data を PcgOneseq128XslRr64 オブジェクトに復元する

Random\Engine\PcgOneseq128XslRr64::__unserialize

(PHP 8 >= 8.2.0)

Random\Engine\PcgOneseq128XslRr64::__unserialize — 指定した data を PcgOneseq128XslRr64 オブジェクトに復元する

説明

public Random\Engine\PcgOneseq128XslRr64::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

戻り値

値を返しません。

例

例1 Random\Engine\PcgOneseq128XslRr64::__unserialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Random\Engine\Xoshiro256StarStar クラス

(PHP 8 >= 8.2.0)

はじめに

» xoshiro256** アルゴリズムを実装したクラスです。

クラス概要

final class Random\Engine\Xoshiro256StarStar implements Random\Engine {
/* メソッド */
public __construct(string|int|null $seed = null)
public __debugInfo(): array
public generate(): string
public jump(): void
public jumpLong(): void
public __serialize(): array
public __unserialize(array $data): void
}

目次

  • Random\Engine\Xoshiro256StarStar::__construct — 新しい xoshiro256** エンジンを作成する
  • Random\Engine\Xoshiro256StarStar::__debugInfo — エンジンの内部的なステートを返す
  • Random\Engine\Xoshiro256StarStar::generate — 64ビットのランダムな値を生成する
  • Random\Engine\Xoshiro256StarStar::jump — エンジンの内部状態を、効率的に 2^128 ステップ進める
  • Random\Engine\Xoshiro256StarStar::jumpLong — エンジンの内部状態を、効率的に 2^192 ステップ進める
  • Random\Engine\Xoshiro256StarStar::__serialize — Xoshiro256StarStar オブジェクトをシリアライズする
  • Random\Engine\Xoshiro256StarStar::__unserialize — 指定した data を Xoshiro256StarStar オブジェクトに復元する


新しい xoshiro256** エンジンを作成する

  • ≪ Random\Engine\Xoshiro256StarStar
  • Random\Engine\Xoshiro256StarStar::__debugInfo ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • 新しい xoshiro256** エンジンを作成する

Random\Engine\Xoshiro256StarStar::__construct

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::__construct — 新しい xoshiro256** エンジンを作成する

説明

public Random\Engine\Xoshiro256StarStar::__construct(string|int|null $seed = null)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

seed

符号なし64ビット整数で構成される 256ビット(32バイト) の内部ステートが、 どのように与えられるかは seed のタイプに依存します。

タイプ | 説明
null | ランダムな32バイトのステートを、 CSPRNG を使って生成し、埋めます。
int | seed を64ビットの符号なし整数と解釈し、 その値を SplitMix64 アルゴリズムに与えて生成した、 4つの連続した値でステートを埋めます。
string | 32バイトの文字列を、4つのリトルエンディアン、 かつ符号なし64ビットの整数と解釈してステートを埋めます。

エラー / 例外

  • seedが文字列で、長さが32バイトでなかった場合、 ValueError がスローされます。
  • seedが文字列で、32 個の NULバイト("\x00") で埋められていた場合、 ValueError がスローされます。

例

例1 Random\Engine\Xoshiro256StarStar::__construct() の例

<?php
// ランダムな256ビットのシードを使います。
$e = new \Random\Engine\Xoshiro256StarStar();

$r = new \Random\Randomizer($e);
?>

例2 文字列からシードを作る

<?php
$string = "My string seed";

// $string を256ビットのシードに変換するために、SHA-256 で文字列をハッシュ化し、
// バイナリで出力します。
// 同じ文字列を使うと、同じランダムなシーケンスが生成されます。
$e = new \Random\Engine\Xoshiro256StarStar(
hash('sha256', $string, binary: true)
);

echo bin2hex($e->generate()), "\n";
?>

上の例の出力は以下となります。

6e013453678388c2


エンジンの内部的なステートを返す

  • ≪ Random\Engine\Xoshiro256StarStar::__construct
  • Random\Engine\Xoshiro256StarStar::generate ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • エンジンの内部的なステートを返す

Random\Engine\Xoshiro256StarStar::__debugInfo

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::__debugInfo — エンジンの内部的なステートを返す

説明

public Random\Engine\Xoshiro256StarStar::__debugInfo(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Engine\Xoshiro256StarStar::__debugInfo() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


64ビットのランダムな値を生成する

  • ≪ Random\Engine\Xoshiro256StarStar::__debugInfo
  • Random\Engine\Xoshiro256StarStar::jump ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • 64ビットのランダムな値を生成する

Random\Engine\Xoshiro256StarStar::generate

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::generate — 64ビットのランダムな値を生成する

説明

public Random\Engine\Xoshiro256StarStar::generate(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

符号なし64ビットの整数値を、リトルエンディアンで表現した文字列を返します。


エンジンの内部状態を、効率的に 2^128 ステップ進める

  • ≪ Random\Engine\Xoshiro256StarStar::generate
  • Random\Engine\Xoshiro256StarStar::jumpLong ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • エンジンの内部状態を、効率的に 2^128 ステップ進める

Random\Engine\Xoshiro256StarStar::jump

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::jump — エンジンの内部状態を、効率的に 2^128 ステップ進める

説明

public Random\Engine\Xoshiro256StarStar::jump(): void

Random\Engine\Xoshiro256StarStar::generate() が 2128 回呼ばれたかのように、 アルゴリズムのステートを 2128 回分進めます。

アルゴリズムの内部状態を進める目的は、 新しい Random\Engine\Xoshiro256StarStar エンジンを、既に存在する Random\Engine\Xoshiro256StarStar から生成するのを容易にするためです。 シードが与えられているエンジンは新しいエンジンの設計図として振る舞い、 clone することができ、 2128 の値を持つ 2128 個分の重ならないシーケンスを作るために、繰り返し内部状態を進めます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Random\Engine\Xoshiro256StarStar::jump() の例

<?php
use Random\Engine\Xoshiro256StarStar;
use Random\Randomizer;

$blueprintRng = new Xoshiro256StarStar(0);

$fibers = [];
for ($i = 0; $i < 8; $i++) {
$fiberRng = clone $blueprintRng;
$blueprintRng->jump();

$fiber = new Fiber(static function () use ($fiberRng, $i): void {
$randomizer = new Randomizer($fiberRng);

while (true) {
Fiber::suspend();

echo "{$i}: ", $randomizer->getInt(0, 100), "\n";
}
});
$fiber->start();

$fibers[] = $fiber;
}

// fiber はランダムな順番で実行されますが、それぞれの fiber
// は毎回同じ値を出力します。なぜなら、それぞれが独自のRNG(乱数生成器)
// のインスタンスを持つからです
$randomizer = new Randomizer();

$fibers = $randomizer->shuffleArray($fibers);
foreach ($fibers as $fiber) {
$fiber->resume();
}

$fibers = $randomizer->shuffleArray($fibers);
foreach ($fibers as $fiber) {
$fiber->resume();
}
?>

上の例の出力は、 たとえば以下のようになります。

4: 89
3: 10
2: 63
1: 75
6: 41
5: 56
0: 16
7: 60
7: 34
6: 58
1: 74
4: 63
3: 3
5: 42
2: 45
0: 86

参考

  • Random\Engine\Xoshiro256StarStar::jumpLong() - エンジンの内部状態を、効率的に 2^192 ステップ進める


エンジンの内部状態を、効率的に 2^192 ステップ進める

  • ≪ Random\Engine\Xoshiro256StarStar::jump
  • Random\Engine\Xoshiro256StarStar::__serialize ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • エンジンの内部状態を、効率的に 2^192 ステップ進める

Random\Engine\Xoshiro256StarStar::jumpLong

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::jumpLong — エンジンの内部状態を、効率的に 2^192 ステップ進める

説明

public Random\Engine\Xoshiro256StarStar::jumpLong(): void

Random\Engine\Xoshiro256StarStar::generate() が 2192 回呼ばれたかのように、 アルゴリズムのステートを 2192 回分進めます。

アルゴリズムの内部状態を大きく進める目的は、 新しい Random\Engine\Xoshiro256StarStar エンジンを、既に存在する Random\Engine\Xoshiro256StarStar から生成するのを容易にするためです。 シードが与えられているエンジンは新しいエンジンの設計図として振る舞い、 clone することができ、 2192 の値を持つ 264 個分の重ならないシーケンスを作るために、繰り返し内部状態を進めます。

このメソッドは、 Random\Engine\Xoshiro256StarStar::jump() と組み合わせることができます。 そうすることで、このメソッドが生成した 264 回数分のシーケンスを、 2128 の値をそれぞれ持つ 264 回分のシーケンスに分割できます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Random\Engine\Xoshiro256StarStar::jumpLong() の例

<?php
$blueprintRng = new \Random\Engine\Xoshiro256StarStar(0);

// 親となるエンジンは、それぞれ 値 2**192 のチャンクを持ちます
$parent1 = clone $blueprintRng;
$blueprintRng->jumpLong();

$parent2 = clone $blueprintRng;
$blueprintRng->jumpLong();

// 子となるエンジンは、親のエンジンが持つ値 2**192 のチャンク
// から取得した、値 2**128 のチャンクをそれぞれ持ちます
$child1a = clone $parent1;
$parent1->jump();
$child1b = clone $parent1;
$parent1->jump();

$child2a = clone $parent2;
$parent2->jump();
$child2b = clone $parent2;
$parent2->jump();

echo "Child 1A: ", bin2hex($child1a->generate()), "\n";
echo "Child 1B: ", bin2hex($child1b->generate()), "\n";
echo "Child 2A: ", bin2hex($child2a->generate()), "\n";
echo "Child 2B: ", bin2hex($child2b->generate()), "\n";
?>

上の例の出力は以下となります。

Child 1A: b4f275cb365fec99
Child 1B: 2cd646c8ed156237
Child 2A: eb3729a722a504e7
Child 2B: d4208dc85bdd6dc3

参考

  • Random\Engine\Xoshiro256StarStar::jump() - エンジンの内部状態を、効率的に 2^128 ステップ進める


Xoshiro256StarStar オブジェクトをシリアライズする

  • ≪ Random\Engine\Xoshiro256StarStar::jumpLong
  • Random\Engine\Xoshiro256StarStar::__unserialize ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • Xoshiro256StarStar オブジェクトをシリアライズする

Random\Engine\Xoshiro256StarStar::__serialize

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::__serialize — Xoshiro256StarStar オブジェクトをシリアライズする

説明

public Random\Engine\Xoshiro256StarStar::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Random\Engine\Xoshiro256StarStar::__serialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


指定した data を Xoshiro256StarStar オブジェクトに復元する

  • ≪ Random\Engine\Xoshiro256StarStar::__serialize
  • Random\RandomError ≫
  • PHP Manual
  • Random\Engine\Xoshiro256StarStar
  • 指定した data を Xoshiro256StarStar オブジェクトに復元する

Random\Engine\Xoshiro256StarStar::__unserialize

(PHP 8 >= 8.2.0)

Random\Engine\Xoshiro256StarStar::__unserialize — 指定した data を Xoshiro256StarStar オブジェクトに復元する

説明

public Random\Engine\Xoshiro256StarStar::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

戻り値

値を返しません。

例

例1 Random\Engine\Xoshiro256StarStar::__unserialize() の例

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Random\RandomError クラス

(PHP 8 >= 8.2.0)

はじめに

ランダムな値を使ったり生成したりする際に発生する、Error の基底クラスです。

クラス概要

class Random\RandomError extends Error {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


Random\BrokenRandomEngineError クラス

(PHP 8 >= 8.2.0)

はじめに

たとえば、生成される値がとても強く偏っているなどの理由で、 使っている Random\Engine が壊れていることを示します。

クラス概要

class Random\BrokenRandomEngineError extends Random\RandomError {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


Random\RandomException クラス

(PHP 8 >= 8.2.0)

はじめに

ランダムな値を使ったり生成したりする際に発生する、Exception の基底クラスです。

クラス概要

class Random\RandomException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


Seaslog

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Seaslog 関数
    • seaslog_get_author — Get SeasLog author.
    • seaslog_get_version — Get SeasLog version.
  • SeasLog — The SeasLog class
    • SeasLog::alert — Record alert log information
    • SeasLog::analyzerCount — Get log count by level, log_path and key_word
    • SeasLog::analyzerDetail — Get log detail by level, log_path, key_word, start, limit, order
    • SeasLog::closeLoggerStream — Manually release stream flow from logger
    • SeasLog::__construct — Description
    • SeasLog::critical — Record critical log information
    • SeasLog::debug — Record debug log information
    • SeasLog::__destruct — Description
    • SeasLog::emergency — Record emergency log information
    • SeasLog::error — Record error log information
    • SeasLog::flushBuffer — Flush logs buffer, dump to appender file, or send to remote api with tcp/udp
    • SeasLog::getBasePath — Get SeasLog base path.
    • SeasLog::getBuffer — Get the logs buffer in memory as array
    • SeasLog::getBufferEnabled — Determin if buffer enabled
    • SeasLog::getDatetimeFormat — Get SeasLog datetime format style
    • SeasLog::getLastLogger — Get SeasLog last logger path
    • SeasLog::getRequestID — Get SeasLog request_id differentiated requests
    • SeasLog::getRequestVariable — Get SeasLog request variable
    • SeasLog::info — Record info log information
    • SeasLog::log — The Common Record Log Function
    • SeasLog::notice — Record notice log information
    • SeasLog::setBasePath — Set SeasLog base path
    • SeasLog::setDatetimeFormat — Set SeasLog datetime format style
    • SeasLog::setLogger — Set SeasLog logger name
    • SeasLog::setRequestID — Set SeasLog request_id differentiated requests
    • SeasLog::setRequestVariable — Manually set SeasLog request variable
    • SeasLog::warning — Record warning log information


はじめに

The Seaslog is an effective,fast,stable log extension for PHP.

The log journal，which is usually the operate record of the system， software and the application record. Through the analysis of the log，it can facilitate users to understand the operation of the system， software and the application situation. If your application log is rich enough, it can also analyze the previous use's operation behavior,type, regional distribution or other more information. The application log also points the multiple levels at the same time, you can easily get the application analysis of health status, timely find problems and quick positioning, and solve the problem, remedy the loss.

The error_log, syslog function which built in PHP is powerful and excellent performance, but due to various defects (error_log have no error level, no fixed format, syslog regardless of module, and mix with system log ), reducing a lot of flexibility , and can't meet the application requirements.

The good news is that there are a number of third-party log class library established to make up for the defects, such as log4php, plog, monolog (of course, there are many applications in the project development of the log class).

So is there a log of libraries meet the following requirements：

  • Modules, classification
  • Simple configuration(preferably without configuration)
  • Clear log format and easy understanding
  • Simple application and well performance
Seaslog just meet these demands.

What is provided at present:

  • In the PHP project, record the log specification and repidly.
  • Configure the default log directory and module
  • Specified log directory and capture current configuration
  • Preliminary analysis of the early warning framework
  • Efficient log buffer and convenient buffer debug
  • Follow the PSR-3 log interface specification
  • Automatically record error information
  • Automatically record abnormal information
  • Support Connect the TCP port, send with RFC5424
  • Support Connect the UDP port, send with RFC5424
  • Support RequestId differentiated requests
  • Support for log template customizations

Read More » SeasLog Document at Github.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Seaslog
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/seaslog


実行時設定

php.ini の設定により動作が変化します。

Seaslog 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
seaslog.appender | 1 | INI_SYSTEM |
seaslog.appender_retry | 0 | INI_ALL |
seaslog.level | 8 | INI_ALL |
seaslog.remote_host | 127.0.0.1 | INI_ALL |
seaslog.remote_port | 514 | INI_ALL |
seaslog.remote_timeout | 1 | INI_SYSTEM |
seaslog.default_basepath | /var/log/www | INI_SYSTEM |
seaslog.default_logger | default | INI_SYSTEM |
seaslog.default_template | %T | %L | %P | %Q | %t | %M | INI_SYSTEM |
seaslog.default_datetime_format | Y-m-d H:i:s | INI_SYSTEM |
seaslog.trace_error | 1 | INI_ALL |
seaslog.trace_exception | 0 | INI_SYSTEM |
seaslog.trace_notice | 0 | INI_ALL |
seaslog.trace_warning | 0 | INI_ALL |
seaslog.use_buffer | 0 | INI_SYSTEM |
seaslog.buffer_size | 0 | INI_ALL |
seaslog.buffer_disabled_in_cli | 0 | INI_SYSTEM |
seaslog.disting_type | 0 | INI_SYSTEM |
seaslog.disting_folder | 1 | INI_SYSTEM |
seaslog.disting_by_hour | 0 | INI_SYSTEM |
seaslog.recall_depth | 0 | INI_ALL |
seaslog.trim_wrap | 0 | INI_ALL |
seaslog.ignore_warning | 1 | INI_ALL |
seaslog.throw_exception | 1 | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

seaslog.appender int

Switch the Record Log Data Store. 1File 2TCP 3UDP (Switch default 1)

SeasLog will send log to tcp://remote_host:remote_port or udp://remote_host:remote_port server, when seaslog.appender configured to 2 (TCP) or 3 (UDP).

When SeasLog send log to TCP/UDP，style follow RFC5424. The {logInfo} affected by seaslog.default_template.

The log style finally formatted such as:
<15>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | DEBUG | 21423 | 599157af4e937 | 1466787583.322 | this is a neeke debug
<14>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | INFO | 21423 | 599157af4e937 | 1466787583.323 | this is a info log
<13>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | NOTICE | 21423 | 599157af4e937 | 1466787583.324 | this is a notice log
seaslog.appender_retry int

Record Log Retry Count. Default 0 (Do Not Retry)

seaslog.buffer_disabled_in_cli int

Disable buffer in cli. 1-Y 0-N(Default)

Switch the configure buffer_disabled_in_cli on. The buffer_disabled_in_cli switch default off. If switch buffer_disabled_in_cli on, and running in cli, seaslog.use_buffer setting will be discarded, Seaslog write to the Data Store IMMEDIATELY.

seaslog.buffer_size int

Configure the buffer_size with 100. The buffer_size default 0, it's meaning don't use buffer. If buffer_size > 0,SeasLog will rewritten down into the Data Store when the prerecorded log in memory count >= this buffer_size,and then refresh the memory poll.

seaslog.default_basepath string

Default Log Base Path. Defult "/var/log/www".

seaslog.default_datetime_format string

The DateTime Style. Default "Y-m-d H:i:s".

seaslog.default_logger string

Default Logger Path. Default "default".

seaslog.disting_by_hour int

Switch use the logger with hour. 1-Y 0-N(Default)

注意:

seaslog.disting_by_hour = 1 Switch use Logger DisTing by hour. It's meaning SeasLog will create the file each one hour.

seaslog.disting_folder int

Switch use the logger with folder. 1-Y(Default) 0-N

注意:

seaslog.disting_folder = 1 Switch use Logger DisTing by folder, it's meaning SeasLog will create the file deistic by folder, and when this configure close SeasLog will create file use underline connect Logger and Time like default_20180211.log.

seaslog.disting_type int

Switch use the logger with type. 1-Y 0-N(Default)

注意:

seaslog.disting_type = 1 Switch use Logger DisTing by type, it's meaning SeasLog will create the file deistic info\warn\error and the other type.

seaslog.ignore_warning int

Switch ignore SeasLog warning. 1-On(Default) 0-Off

注意:

seaslog.ignore_warning = 1 Open a warning to ignore SeasLog itself. When directory permissions or receive server ports are blocked, they are ignored; when closed, a warning is thrown.

seaslog.level int

Record logger level. Default 8 (All of them). 0-EMERGENCY 1-ALERT 2-CRITICAL 3-ERROR 4-WARNING 5-NOTICE 6-INFO 7-DEBUG 8-ALL

注意:

Tips: The configuration item has changed since the 1.7.0 version. Before the 1.7.0 version, the smaller the value, the more logs are taken according to the level: 0-all 1-debug 2-info 3-notice 4-warning 5-error 6-critical 7-alert 8-emergency Before the 1.7.0 version, Default 0 (All of them).

seaslog.recall_depth int

Log function recall depth.Will affected variable LineNo in %F. Default 0

seaslog.remote_host string

If you use Record TCP or UDP, configure this remote ip. Default "127.0.0.1"

seaslog.remote_port int

If you use Record TCP or UDP, configure this remote port. Default 514

seaslog.remote_timeout int

If you use Record TCP or UDP, configure this remote timeout. Default 1 second

seaslog.throw_exception int

Switch throw SeasLog exception. 1-On(Default) 0-Off

注意:

seaslog.throw_exception = 1 Open an exception that throws the SeasLog to throw itself. When the directory authority or the receive server port is blocked, throw an exception; do not throw an exception when closed.

seaslog.trace_error int

Automatic Record final error with default logger. 1-Y(Default) 0-N

seaslog.trace_exception int

Automatic Record exception with default logger. 1-Y 0-N(Default)

seaslog.trace_notice int

Automatic Record notice with default logger. 1-Y 0-N(Default)

seaslog.trace_warning int

Automatic Record warning with default logger. 1-Y 0-N(Default)

seaslog.trim_wrap int

Trim the \n and \r in log message. 1-On 0-Off(Default)

seaslog.use_buffer int

Switch use the log buffer with memory. 1-Y 0-N(Default)

注意:

seaslog.use_buffer = 1 Switch the configure use_buffer on. The use_buffer switch default off. If switch use_buffer on, SeasLog prerecord the log with memory, and them would be rewritten down into the Data Store by request shutdown or php process exit (PHP RSHUTDOWN or PHP MSHUTDOWN).

seaslog.default_template string

Default Log template. Default "%T | %L | %P | %Q | %t | %M".

注意:

The following default variables are provided, which can be used directly in the log template and replaced as a corresponding value when the log is eventually generated.

Default log template is: seaslog.default_template = "%T | %L | %P | %Q | %t | %M", that's mean,default log style is: {dateTime} | {level} | {pid} | {uniqid} | {timeStamp} | {logInfo}

If you custom log template, such as: seaslog.default_template = "[%T]:%L %P %Q %t %M", that's will mean,log style was custom as: [{dateTime}]:{level} {pid} {uniqid} {timeStamp} {logInfo}

Seaslog Default Variable Table
Variable Name | Description
%L | Level.
%M | Message.
%T | DateTime. Such as 2017-08-16 19:15:02, affected by seaslog.default_datetime_format.
%t | Timestamp. Such as 1502882102.862,accurate to milliseconds.
%Q | RequestId. To distinguish a single request, such as not invoking the SeasLog::setRequestId($string) function, the unique value generated by the built-in static char *get_uniqid () function is used when the request is initialized.
%H | HostName.
%P | ProcessId.
%D | Domain:Port. Such as www.cloudwise.com:80; When Cli, Such as cli.
%R | Request URI. Such as /app/user/signin; When Cli it's the index script, Such as CliIndex.php.
%m | Request Method. Such as Get; When Cli it's the command script, Such as /bin/bash.
%I | Client IP; When Cli it's local. Priority value: HTTP_X_REAL_IP > HTTP_X_FORWARDED_FOR > REMOTE_ADDR
%F | FileName:LineNo. Such as UserService.php:118.
%U | MemoryUsage. byte. Call zend_memory_usage.
%u | PeakMemoryUsage. byte. Call zend_memory_peak_usage.
%C | TODO Class::Action. Such as UserService::getUserInfo


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SEASLOG_VERSION (string)
SEASLOG_AUTHOR (string)
SEASLOG_ALL (string)
"ALL"
SEASLOG_DEBUG (string)
"DEBUG" - Detailed debug information.Fine-grained information events.
SEASLOG_INFO (string)
"INFO" - Interesting events.Emphasizes the running process of the application.
SEASLOG_NOTICE (string)
"NOTICE" - Normal but significant events.Information that is more important than the INFO level during execution.
SEASLOG_WARNING (string)
"WARNING" - Exceptional occurrences that are not errors.Potentially aberrant information that needs attention and needs to be repaired.
SEASLOG_ERROR (string)
"ERROR" - Runtime errors that do not require immediate action but should typically.
SEASLOG_CRITICAL (string)
"CRITICAL" - Critical conditions.Need to be repaired immediately, and the program component is unavailable.
SEASLOG_ALERT (string)
"ALERT" - Action must be taken immediately.Immediate attention should be given to relevant personnel for emergency repairs.
SEASLOG_EMERGENCY (string)
"EMERGENCY" - System is unusable.
SEASLOG_DETAIL_ORDER_ASC (int)
1
SEASLOG_DETAIL_ORDER_DESC (int)
2
SEASLOG_APPENDER_FILE (int)
1
SEASLOG_APPENDER_TCP (int)
2
SEASLOG_APPENDER_UDP (int)
3
SEASLOG_CLOSE_LOGGER_STREAM_MOD_ALL (int)
1
SEASLOG_CLOSE_LOGGER_STREAM_MOD_ASSIGN (int)
2
SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT (int)
1
SEASLOG_REQUEST_VARIABLE_REQUEST_URI (int)
2
SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD (int)
3
SEASLOG_REQUEST_VARIABLE_CLIENT_IP (int)
4


例

例1 Get and set base path

<?php
$basePath1 = SeasLog::getBasePath();

SeasLog::setBasePath('/log/base_test');
$basePath2 = SeasLog::getBasePath();

var_dump($basePath1,$basePath2);

?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/var/log/www"
string(14) "/log/base_test"

例2 Get and set logger

<?php
$lastLogger1 = SeasLog::getLastLogger();

SeasLog::setLogger('testModule/app1');
$lastLogger2 = SeasLog::getLastLogger();

var_dump($lastLogger1,$lastLogger2);

?>

上の例の出力は、 たとえば以下のようになります。

string(7) "default"
string(15) "testModule/app1"

例3 Fast write log

<?php
SeasLog::log(SEASLOG_ERROR,'this is a error test by ::log');
SeasLog::debug('this is a {userName} debug',array('{userName}' => 'neeke'));
SeasLog::info('this is a info log');
SeasLog::notice('this is a notice log');
SeasLog::warning('your {website} was down,please {action} it ASAP!',array('{website}' => 'github.com','{action}' => 'rboot'));
SeasLog::error('a error log');
SeasLog::critical('some thing was critical');
SeasLog::alert('yes this is a {messageName}',array('{messageName}' => 'alertMSG'));
SeasLog::emergency('Just now, the house next door was completely burnt out! {note}',array('{note}' => 'it`s a joke'));
?>

As the default, seaslog.default_template = "%T | %L | %P | %Q | %t | %M". That's mean,as the default,log record style is： `{dateTime} | {level} | {pid} | {uniqid} | {timeStamp} | {logInfo}`.

上の例の出力は、 たとえば以下のようになります。

seaslog.appender = 1

2014-07-27 08:53:52 | ERROR | 23625 | 599159975a9ff | 1406422432.786 | this is a error test by log
2014-07-27 08:53:52 | DEBUG | 23625 | 599159975a9ff | 1406422432.786 | this is a neeke debug
2014-07-27 08:53:52 | INFO | 23625 | 599159975a9ff | 1406422432.787 | this is a info log
2014-07-27 08:53:52 | NOTICE | 23625 | 599159975a9ff | 1406422432.787 | this is a notice log
2014-07-27 08:53:52 | WARNING | 23625 | 599159975a9ff | 1406422432.787 | your github.com was down,please rboot it ASAP!
2014-07-27 08:53:52 | ERROR | 23625 | 599159975a9ff | 1406422432.787 | a error log
2014-07-27 08:53:52 | CRITICAL | 23625 | 599159975a9ff | 1406422432.787 | some thing was critical
2014-07-27 08:53:52 | EMERGENCY | 23625 | 599159975a9ff | 1406422432.787 | Just now, the house next door was completely burnt out! it is a joke

上の例の出力は、 たとえば以下のようになります。

seaslog.appender = 2 or seaslog.appender = 3

The log style finally formatted such as:
<15>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | DEBUG | 21423 | 599157af4e937 | 1466787583.322 | this is a neeke debug
<14>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | INFO | 21423 | 599157af4e937 | 1466787583.323 | this is a info log
<13>1 2017-08-27T01:24:59+08:00 vagrant-ubuntu-trusty test/logger[27171]: 2016-06-25 00:59:43 | NOTICE | 21423 | 599157af4e937 | 1466787583.324 | this is a notice log

例4 Fast count some type of log count value

SeasLog get count value of `grep -wc` use system pipe and return to PHP (array or int).

<?php
$countResult1 = SeasLog::analyzerCount();
$countResult2 = SeasLog::analyzerCount(SEASLOG_WARNING);
$countResult3 = SeasLog::analyzerCount(SEASLOG_ERROR,date('Ymd',time()));

var_dump($countResult1,$countResult2,$countResult3);

?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["DEBUG"]=>
  int(3)
  ["INFO"]=>
  int(3)
  ["NOTICE"]=>
  int(3)
  ["WARNING"]=>
  int(3)
  ["ERROR"]=>
  int(6)
  ["CRITICAL"]=>
  int(3)
  ["ALERT"]=>
  int(3)
  ["EMERGENCY"]=>
  int(3)
}
int(7)
int(1)

例5 Acquisit some type of log list

SeasLog get count value of `grep -w` use system pipe and return array to PHP.

<?php
$detailErrorArray = SeasLog::analyzerDetail(SEASLOG_ERROR);
var_dump($detailErrorArray);

var_dump(SeasLog::analyzerDetail(SEASLOG_ERROR,date('Ymd',time())));
?>

上の例の出力は、 たとえば以下のようになります。

array(6) {
  [0] =>
  string(83) "2014-02-24 00:14:02 | ERROR | 8568 | 599157af4e937 | 1393172042.717 | test error 3 "
  [1] =>
  string(83) "2014-02-24 00:14:04 | ERROR | 8594 | 5991576584446 | 1393172044.104 | test error 3 "
  [2] =>
  string(83) "2014-02-24 00:14:04 | ERROR | 8620 | 1502697015147 | 1393172044.862 | test error 3 "
  [3] =>
  string(83) "2014-02-24 00:14:05 | ERROR | 8646 | 599159975a9ff | 1393172045.989 | test error 3 "
  [4] =>
  string(83) "2014-02-24 00:14:07 | ERROR | 8672 | 599159986ec28 | 1393172047.882 | test error 3 "
  [5] =>
  string(83) "2014-02-24 00:14:08 | ERROR | 8698 | 5991599981cec | 1393172048.736 | test error 3 "
}

array(2) {
  [0] =>
  string(83) "2014-02-24 00:14:02 | ERROR | 8568 | 599157af4e937 | 1393172042.717 | test error 3 "
  [1] =>
  string(83) "2014-02-24 00:14:04 | ERROR | 8594 | 5991576584446 | 1393172044.104 | test error 3 "
}


Seaslog 関数

目次

  • seaslog_get_author — Get SeasLog author.
  • seaslog_get_version — Get SeasLog version.


Get SeasLog author.

  • ≪ Seaslog 関数
  • seaslog_get_version ≫
  • PHP Manual
  • Seaslog 関数
  • Get SeasLog author.

seaslog_get_author

(PECL seaslog >=1.0.0)

seaslog_get_author — Get SeasLog author.

説明

seaslog_get_author(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Return SeasLog author as string.

例

例1 seaslog_get_author() example

<?php

var_dump(seaslog_get_author());

?>

上の例の出力は、 たとえば以下のようになります。

string(29) "Chitao.Gao  [ neeke@php.net ]"


Get SeasLog version.

  • ≪ seaslog_get_author
  • SeasLog ≫
  • PHP Manual
  • Seaslog 関数
  • Get SeasLog version.

seaslog_get_version

(PECL seaslog >=1.0.0)

seaslog_get_version — Get SeasLog version.

説明

seaslog_get_version(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Return SeasLog version (SEASLOG_VERSION) as string.

例

例1 seaslog_get_version() example

<?php

var_dump(seaslog_get_version());

?>

上の例の出力は、 たとえば以下のようになります。

string(5) "1.8.4"


The SeasLog class

(PECL seaslog >=1.0.0)

はじめに

クラス概要

class SeasLog {
/* メソッド */
public static alert(string $message, array $content = ?, string $logger = ?): bool
public static analyzerCount(string $level, string $log_path = ?, string $key_word = ?): mixed
public static analyzerDetail(
string $level,
string $log_path = ?,
string $key_word = ?,
int $start = ?,
int $limit = ?,
int $order = ?
): mixed
public static closeLoggerStream(int $model, string $logger): bool
public static critical(string $message, array $content = ?, string $logger = ?): bool
public static debug(string $message, array $content = ?, string $logger = ?): bool
public __destruct()
public static emergency(string $message, array $content = ?, string $logger = ?): bool
public static error(string $message, array $content = ?, string $logger = ?): bool
public static flushBuffer(): bool
public static Seaslog::getBasePath(): string
public static getBuffer(): array
public static getBufferEnabled(): bool
public static getDatetimeFormat(): string
public static getLastLogger(): string
public static getRequestID(): string
public static getRequestVariable(int $key): bool
public static info(string $message, array $content = ?, string $logger = ?): bool
public static log(
string $level,
string $message = ?,
array $content = ?,
string $logger = ?
): bool
public static notice(string $message, array $content = ?, string $logger = ?): bool
public static setBasePath(string $base_path): bool
public static setDatetimeFormat(string $format): bool
public static setLogger(string $logger): bool
public static setRequestID(string $request_id): bool
public static setRequestVariable(int $key, string $value): bool
public static warning(string $message, array $content = ?, string $logger = ?): bool
}

目次

  • SeasLog::alert — Record alert log information
  • SeasLog::analyzerCount — Get log count by level, log_path and key_word
  • SeasLog::analyzerDetail — Get log detail by level, log_path, key_word, start, limit, order
  • SeasLog::closeLoggerStream — Manually release stream flow from logger
  • SeasLog::__construct — Description
  • SeasLog::critical — Record critical log information
  • SeasLog::debug — Record debug log information
  • SeasLog::__destruct — Description
  • SeasLog::emergency — Record emergency log information
  • SeasLog::error — Record error log information
  • SeasLog::flushBuffer — Flush logs buffer, dump to appender file, or send to remote api with tcp/udp
  • SeasLog::getBasePath — Get SeasLog base path.
  • SeasLog::getBuffer — Get the logs buffer in memory as array
  • SeasLog::getBufferEnabled — Determin if buffer enabled
  • SeasLog::getDatetimeFormat — Get SeasLog datetime format style
  • SeasLog::getLastLogger — Get SeasLog last logger path
  • SeasLog::getRequestID — Get SeasLog request_id differentiated requests
  • SeasLog::getRequestVariable — Get SeasLog request variable
  • SeasLog::info — Record info log information
  • SeasLog::log — The Common Record Log Function
  • SeasLog::notice — Record notice log information
  • SeasLog::setBasePath — Set SeasLog base path
  • SeasLog::setDatetimeFormat — Set SeasLog datetime format style
  • SeasLog::setLogger — Set SeasLog logger name
  • SeasLog::setRequestID — Set SeasLog request_id differentiated requests
  • SeasLog::setRequestVariable — Manually set SeasLog request variable
  • SeasLog::warning — Record warning log information


Record alert log information

  • ≪ SeasLog
  • SeasLog::analyzerCount ≫
  • PHP Manual
  • SeasLog
  • Record alert log information

SeasLog::alert

(PECL seaslog >=1.0.0)

SeasLog::alert — Record alert log information

説明

public static SeasLog::alert(string $message, array $content = ?, string $logger = ?): bool

Record alert log information.

注意:

"ALERT" - Action must be taken immediately. Immediate attention should be given to relevant personnel for emergency repairs.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::alert() example

<?php

var_dump(SeasLog::alert('log message'));

//with content
var_dump(SeasLog::alert('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::alert('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | ALERT | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | ALERT | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | ALERT | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


Get log count by level, log_path and key_word

  • ≪ SeasLog::alert
  • SeasLog::analyzerDetail ≫
  • PHP Manual
  • SeasLog
  • Get log count by level, log_path and key_word

SeasLog::analyzerCount

(PECL seaslog >=1.1.6)

SeasLog::analyzerCount — Get log count by level, log_path and key_word

説明

public static SeasLog::analyzerCount(string $level, string $log_path = ?, string $key_word = ?): mixed

`SeasLog` get count value of `grep -ai '{level}' | grep -aic '{key_word}'` use system pipe and return to PHP (array or int).

パラメータ

level

String. The log information level.

log_path

String. The log information path.

key_word

String. The search key word for log information.

戻り値

If `level` is SEASLOG_ALL or Empty, return all levels count as `array`. If `level` is SEASLOG_INFO or the other level, return count as `int`.

例

例1 SeasLog::analyzerCount() example

<?php

$countResult1 = SeasLog::analyzerCount();

//with `level`
$countResult2 = SeasLog::analyzerCount(SEASLOG_DEBUG);

//with `level` and `log_path`
$countResult3 = SeasLog::analyzerCount(SEASLOG_ERROR,date('Ymd',time()));

//with `level` and `key_word`
$countResult4 = SeasLog::analyzerCount(SEASLOG_DEBUG,NULL,'accessToken');

var_dump($countResult1,$countResult2,$countResult3,$countResult4);

?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["DEBUG"]=>
  int(180)
  ["INFO"]=>
  int(214)
  ["NOTICE"]=>
  int(0)
  ["WARNING"]=>
  int(0)
  ["ERROR"]=>
  int(228)
  ["CRITICAL"]=>
  int(244)
  ["ALERT"]=>
  int(1)
  ["EMERGENCY"]=>
  int(0)
}

int(180)

int(228)

int(29)

参考

  • SeasLog::analyzerDetail() - Get log detail by level, log_path, key_word, start, limit, order


Get log detail by level, log_path, key_word, start, limit, order

  • ≪ SeasLog::analyzerCount
  • SeasLog::closeLoggerStream ≫
  • PHP Manual
  • SeasLog
  • Get log detail by level, log_path, key_word, start, limit, order

SeasLog::analyzerDetail

(PECL seaslog >=1.1.6)

SeasLog::analyzerDetail — Get log detail by level, log_path, key_word, start, limit, order

説明

public static SeasLog::analyzerDetail(
string $level,
string $log_path = ?,
string $key_word = ?,
int $start = ?,
int $limit = ?,
int $order = ?
): mixed

`SeasLog` get results of `grep -ai '{level}' | grep -ai '{key_word}' | sed -n '{start},{limit}'p` use system pipe and return array to PHP.

パラメータ

level

String. The log information level.

log_path

String. The log information path.

key_word

String. The search key word for log information.

start

Int. Default is `1`.

limit

Int. Default is `20`.

order

Int. Default is SEASLOG_DETAIL_ORDER_ASC. See also:

  • SEASLOG_DETAIL_ORDER_ASC
  • SEASLOG_DETAIL_ORDER_DESC

戻り値

Return results as array.

注意:

When `start`,`limit` is not NULL and in Windows, SeasLog will threw exception with message 'Param start and limit don't support Windows'.

例

例1 SeasLog::analyzerDetail() example

<?php

$result1 = SeasLog::analyzerDetail(SEASLOG_ERROR);

//with `logger` and `key_word`
$result2 = SeasLog::analyzerDetail(SEASLOG_ERROR,'test/logger/','neeke');

//with `start` and `limit`
$result3 = SeasLog::analyzerDetail(SEASLOG_ERROR,'test/logger/','neeke',1,2);

var_dump($result1,$result2,$result3);
?>

上の例の出力は、 たとえば以下のようになります。

array(20) {
  [0]=>
  string(93) "2018-07-09 12:52:53 | ERROR | 12247 | 5b42ea2580e51 | 1531111973.528 | log message from neeke"
  [1]=>
  string(93) "2018-07-09 12:52:54 | ERROR | 12256 | 5b42ea26d6657 | 1531111974.878 | log message from neeke"
  [2]=>
  string(93) "2018-07-09 12:52:55 | ERROR | 12265 | 5b42ea277b8d4 | 1531111975.506 | log message from neeke"
  [3]=>
  string(104) "2018-07-09 12:52:55 | ERROR | 12274 | 5b42ea27db5dc | 1531111975.898 | log message from the other people"
...
}

array(3) {
  [0]=>
  string(93) "2018-07-09 12:52:53 | ERROR | 12247 | 5b42ea2580e51 | 1531111973.528 | log message from neeke"
  [1]=>
  string(93) "2018-07-09 12:52:54 | ERROR | 12256 | 5b42ea26d6657 | 1531111974.878 | log message from neeke"
  [2]=>
  string(93) "2018-07-09 12:52:55 | ERROR | 12265 | 5b42ea277b8d4 | 1531111975.506 | log message from neeke"
}

array(2) {
  [0]=>
  string(93) "2018-07-09 12:52:53 | ERROR | 12247 | 5b42ea2580e51 | 1531111973.528 | log message from neeke"
  [1]=>
  string(93) "2018-07-09 12:52:54 | ERROR | 12256 | 5b42ea26d6657 | 1531111974.878 | log message from neeke"
}

参考

  • SeasLog::analyzerCount() - Get log count by level, log_path and key_word


Manually release stream flow from logger

  • ≪ SeasLog::analyzerDetail
  • SeasLog::__construct ≫
  • PHP Manual
  • SeasLog
  • Manually release stream flow from logger

SeasLog::closeLoggerStream

(PECL seaslog >=1.8.6)

SeasLog::closeLoggerStream — Manually release stream flow from logger

説明

public static SeasLog::closeLoggerStream(int $model, string $logger): bool

Manually release stream flow from logger. SeasLog caches the stream handle opened by the log logger to save the overhead of creating a stream. The handle will be automatically released at the end of the request. If in CLI mode, the process will also automatically release when it exits. Or you can use the following functions to manually release(manually release function needs to update SeasLog 1.8.6 or updated version).

パラメータ

model

Constant int.

  • SEASLOG_CLOSE_LOGGER_STREAM_MOD_ALL
  • SEASLOG_CLOSE_LOGGER_STREAM_MOD_ASSIGN

logger

The logger name.

戻り値

Return TRUE on released stream flow success, FALSE on failure.

例

例1 SeasLog::closeLoggerStream() example

<?php

var_dump(SeasLog::closeLoggerStream());
var_dump(SeasLog::closeLoggerStream(SEASLOG_CLOSE_LOGGER_STREAM_MOD_ALL));
var_dump(SeasLog::closeLoggerStream(SEASLOG_CLOSE_LOGGER_STREAM_MOD_ASSIGN, 'logger_name'));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)

参考

  • SeasLog::setLogger() - Set SeasLog logger name
  • SeasLog::getLastLogger() - Get SeasLog last logger path


Description

  • ≪ SeasLog::closeLoggerStream
  • SeasLog::critical ≫
  • PHP Manual
  • SeasLog
  • Description

SeasLog::__construct

(PECL seaslog >=1.0.0)

SeasLog::__construct — Description

説明

public SeasLog::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 SeasLog::__construct() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Record critical log information

  • ≪ SeasLog::__construct
  • SeasLog::debug ≫
  • PHP Manual
  • SeasLog
  • Record critical log information

SeasLog::critical

(PECL seaslog >=1.0.0)

SeasLog::critical — Record critical log information

説明

public static SeasLog::critical(string $message, array $content = ?, string $logger = ?): bool

Record critical log information.

注意:

"CRITICAL" - Critical conditions.Need to be repaired immediately, and the program component is unavailable.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::critical() example

<?php

var_dump(SeasLog::critical('log message'));

//with content
var_dump(SeasLog::critical('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::critical('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | CRITICAL | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | CRITICAL | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | CRITICAL | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


Record debug log information

  • ≪ SeasLog::critical
  • SeasLog::__destruct ≫
  • PHP Manual
  • SeasLog
  • Record debug log information

SeasLog::debug

(PECL seaslog >=1.0.0)

SeasLog::debug — Record debug log information

説明

public static SeasLog::debug(string $message, array $content = ?, string $logger = ?): bool

Record debug log information.

注意:

"DEBUG" - Detailed debug information.Fine-grained information events.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::debug() example

<?php

var_dump(SeasLog::debug('log message'));

//with content
var_dump(SeasLog::debug('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::debug('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | DEBUG | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | DEBUG | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | DEBUG | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


Description

  • ≪ SeasLog::debug
  • SeasLog::emergency ≫
  • PHP Manual
  • SeasLog
  • Description

SeasLog::__destruct

(PECL seaslog >=1.0.0)

SeasLog::__destruct — Description

説明

public SeasLog::__destruct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 SeasLog::__destruct() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Record emergency log information

  • ≪ SeasLog::__destruct
  • SeasLog::error ≫
  • PHP Manual
  • SeasLog
  • Record emergency log information

SeasLog::emergency

(PECL seaslog >=1.0.0)

SeasLog::emergency — Record emergency log information

説明

public static SeasLog::emergency(string $message, array $content = ?, string $logger = ?): bool

Record emergency log information.

注意:

"EMERGENCY" - System is unusable.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::emergency() example

<?php

var_dump(SeasLog::emergency('log message'));

//with content
var_dump(SeasLog::emergency('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::emergency('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | EMERGENCY | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | EMERGENCY | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | EMERGENCY | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::log() - The Common Record Log Function


Record error log information

  • ≪ SeasLog::emergency
  • SeasLog::flushBuffer ≫
  • PHP Manual
  • SeasLog
  • Record error log information

SeasLog::error

(PECL seaslog >=1.0.0)

SeasLog::error — Record error log information

説明

public static SeasLog::error(string $message, array $content = ?, string $logger = ?): bool

Record error log information.

注意:

"ERROR" - Runtime errors that do not require immediate action but should typically.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::error() example

<?php

var_dump(SeasLog::error('log message'));

//with content
var_dump(SeasLog::error('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::error('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | ERROR | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | ERROR | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | ERROR | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

  • ≪ SeasLog::error
  • SeasLog::getBasePath ≫
  • PHP Manual
  • SeasLog
  • Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

SeasLog::flushBuffer

(PECL seaslog >=1.0.0)

SeasLog::flushBuffer — Flush logs buffer, dump to appender file, or send to remote api with tcp/udp

説明

public static SeasLog::flushBuffer(): bool

Flush logs buffer by seaslog.appender: dump to file, or send to remote api with tcp/udp.

注意:

See also: seaslog.appender_retry seaslog.remote_host seaslog.remote_port

パラメータ

この関数にはパラメータはありません。

戻り値

Return TRUE on flush buffer success, FALSE on failure.

例

例1 SeasLog::flushBuffer() example

<?php

SeasLog::info('info log');
SeasLog::debug('debug log');
var_dump(SeasLog::getBuffer());
var_dump(SeasLog::flushBuffer());
var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(79) "2018-07-07 10:47:58 | INFO | 71910 | 5b4029ded6009 | 1530931678.877 | info log
"
    [1]=>
    string(81) "2018-07-07 10:47:58 | DEBUG | 71910 | 5b4029ded6009 | 1530931678.877 | debug log
"
  }
}
bool(true)
array(0) {
}

参考

  • seaslog.use_buffer
  • seaslog.buffer_size
  • seaslog.buffer_disabled_in_cli
  • SeasLog::getBufferEnabled() - Determin if buffer enabled
  • SeasLog::getBuffer() - Get the logs buffer in memory as array


Get SeasLog base path.

  • ≪ SeasLog::flushBuffer
  • SeasLog::getBuffer ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog base path.

SeasLog::getBasePath

(PECL seaslog >=1.0.0)

SeasLog::getBasePath — Get SeasLog base path.

説明

public static Seaslog::getBasePath(): string

Use the Function SeasLog::getBasePath() will get the value of seaslog.default_basepath what configured in php.ini(seaslog.ini).

If you use Seaslog::setBasePath(), will change the result.

パラメータ

この関数にはパラメータはありません。

戻り値

Return seaslog.default_basepath as string.

例

例1 SeasLog::getBasePath() example

<?php

var_dump(SeasLog::getBasePath());

?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/var/log/www"


Get the logs buffer in memory as array

  • ≪ SeasLog::getBasePath
  • SeasLog::getBufferEnabled ≫
  • PHP Manual
  • SeasLog
  • Get the logs buffer in memory as array

SeasLog::getBuffer

(PECL seaslog >=1.0.0)

SeasLog::getBuffer — Get the logs buffer in memory as array

説明

public static SeasLog::getBuffer(): array

パラメータ

この関数にはパラメータはありません。

戻り値

Return an array from logs buffer in memory.

例

例1 SeasLog::getBuffer() example

<?php

var_dump(SeasLog::info('info log'));
var_dump(SeasLog::debug('debug log'));
var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(79) "2018-07-07 10:43:32 | INFO | 71785 | 5b4028d4c58d5 | 1530931412.810 | info log
"
    [1]=>
    string(81) "2018-07-07 10:43:32 | DEBUG | 71785 | 5b4028d4c58d5 | 1530931412.810 | debug log
"
  }
}

参考

  • seaslog.use_buffer
  • seaslog.buffer_size
  • seaslog.buffer_disabled_in_cli
  • SeasLog::getBufferEnabled() - Determin if buffer enabled
  • SeasLog::flushBuffer() - Flush logs buffer, dump to appender file, or send to remote api with tcp/udp


Determin if buffer enabled

  • ≪ SeasLog::getBuffer
  • SeasLog::getDatetimeFormat ≫
  • PHP Manual
  • SeasLog
  • Determin if buffer enabled

SeasLog::getBufferEnabled

(PECL seaslog >=1.0.0)

SeasLog::getBufferEnabled — Determin if buffer enabled

説明

public static SeasLog::getBufferEnabled(): bool

Result join seaslog.use_buffer and seaslog.buffer_disabled_in_cli.

パラメータ

この関数にはパラメータはありません。

戻り値

Return TRUE on seaslog.use_buffer is true. If switch seaslog.buffer_disabled_in_cli on, and running in cli, seaslog.use_buffer setting will be discarded, Seaslog write to the Data Store IMMEDIATELY.

例

例1 SeasLog::getBufferEnabled() example

<?php

var_dump(SeasLog::getBufferEnabled());

?>

上の例の出力は、 たとえば以下のようになります。

bool(false)

参考

  • seaslog.use_buffer
  • seaslog.buffer_size
  • seaslog.buffer_disabled_in_cli
  • SeasLog::getBuffer() - Get the logs buffer in memory as array
  • SeasLog::flushBuffer() - Flush logs buffer, dump to appender file, or send to remote api with tcp/udp


Get SeasLog datetime format style

  • ≪ SeasLog::getBufferEnabled
  • SeasLog::getLastLogger ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog datetime format style

SeasLog::getDatetimeFormat

(PECL seaslog >=1.0.0)

SeasLog::getDatetimeFormat — Get SeasLog datetime format style

説明

public static SeasLog::getDatetimeFormat(): string

Get SeasLog datetime format style. Use the Function SeasLog::getDatetimeFormat() will get the value of seaslog.default_datetime_format what configured in php.ini(seaslog.ini).

パラメータ

この関数にはパラメータはありません。

戻り値

Get SeasLog datetime format style of seaslog.default_datetime_format. Use the Function SeasLog::setDatetimeFormat() will change this value.

例

例1 SeasLog::getDatetimeFormat() example

<?php

var_dump(SeasLog::getDateTimeFormat());
var_dump(SeasLog::setDateTimeFormat('Ymd His'));
var_dump(SeasLog::getDateTimeFormat());

?>

上の例の出力は、 たとえば以下のようになります。

string(11) "Y-m-d H:i:s"
bool(true)
string(7) "Ymd His"

参考

  • SeasLog::setDatetimeFormat() - Set SeasLog datetime format style


Get SeasLog last logger path

  • ≪ SeasLog::getDatetimeFormat
  • SeasLog::getRequestID ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog last logger path

SeasLog::getLastLogger

(PECL seaslog >=1.0.0)

SeasLog::getLastLogger — Get SeasLog last logger path

説明

public static SeasLog::getLastLogger(): string

Use the Function SeasLog::getLastLogger() will get the value of seaslog.default_logger what configured in php.ini(seaslog.ini).

パラメータ

この関数にはパラメータはありません。

戻り値

Use the Function SeasLog::setLogger() will change the value of function SeasLog::getLastLogger().

例

例1 SeasLog::getLastLogger() example

<?php

var_dump(SeasLog::getLastLogger());
SeasLog::setLogger('theNewLogger');
var_dump(SeasLog::getLastLogger());
?>

上の例の出力は、 たとえば以下のようになります。

string(7) "default"
string(12) "theNewLogger"

参考

  • SeasLog::setLogger() - Set SeasLog logger name


Get SeasLog request_id differentiated requests

  • ≪ SeasLog::getLastLogger
  • SeasLog::getRequestVariable ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog request_id differentiated requests

SeasLog::getRequestID

(PECL seaslog >=1.0.0)

SeasLog::getRequestID — Get SeasLog request_id differentiated requests

説明

public static SeasLog::getRequestID(): string

To distinguish a single request, such as not invoking the SeasLog::setRequestId() function， the unique value generated by the built-in `static char *get_uniqid ()` function is used when the request is initialized.

パラメータ

この関数にはパラメータはありません。

戻り値

Return string generated by the built-in `static char *get_uniqid ()` function, or setted by SeasLog::setRequestId() function.

例

例1 SeasLog::getRequestID() example

<?php

var_dump(SeasLog::getRequestID());
var_dump(SeasLog::setRequestID('reqeust_id_test_'.time()));
var_dump(SeasLog::getRequestID());

?>

上の例の出力は、 たとえば以下のようになります。

string(13) "5b3f21a209519"
bool(true)
string(26) "reqeust_id_test_1530864034"

参考

  • SeasLog::setRequestID() - Set SeasLog request_id differentiated requests
  • The Variable `%Q` in Seaslog Default Variable Table.


Get SeasLog request variable

  • ≪ SeasLog::getRequestID
  • SeasLog::info ≫
  • PHP Manual
  • SeasLog
  • Get SeasLog request variable

SeasLog::getRequestVariable

(PECL seaslog >=1.9.0)

SeasLog::getRequestVariable — Get SeasLog request variable

説明

public static SeasLog::getRequestVariable(int $key): bool

Get SeasLog request variable.

パラメータ

key

Constant int.

  • SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT
  • SEASLOG_REQUEST_VARIABLE_REQUEST_URI
  • SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD
  • SEASLOG_REQUEST_VARIABLE_CLIENT_IP

戻り値

Return request variable value on set success.

例

例1 SeasLog::getRequestVariable() example

<?php

$sDomainPort = 'domain:port';
$sRequestUri = 'uri';
$sRequestMethod = 'method';
$sClientIp = 'client_ip';

$iErrorKey = 1000;

$oSeasLog = new SeasLog();

var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT, $sDomainPort));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI, $sRequestUri));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD, $sRequestMethod));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP, $sClientIp));

var_dump($oSeasLog->setRequestVariable($iErrorKey,NULL));

var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT) == $sDomainPort);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI) == $sRequestUri);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD) == $sRequestMethod);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP) == $sClientIp);

var_dump($oSeasLog->getRequestVariable($iErrorKey));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)
bool(false)

参考

  • SeasLog::setRequestVariable() - Manually set SeasLog request variable


Record info log information

  • ≪ SeasLog::getRequestVariable
  • SeasLog::log ≫
  • PHP Manual
  • SeasLog
  • Record info log information

SeasLog::info

(PECL seaslog >=1.0.0)

SeasLog::info — Record info log information

説明

public static SeasLog::info(string $message, array $content = ?, string $logger = ?): bool

Record info log information.

注意:

"INFO" - Interesting events.Emphasizes the running process of the application.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::info() example

<?php

var_dump(SeasLog::info('log message'));

//with content
var_dump(SeasLog::info('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::info('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | INFO | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | INFO | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | INFO | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


The Common Record Log Function

  • ≪ SeasLog::info
  • SeasLog::notice ≫
  • PHP Manual
  • SeasLog
  • The Common Record Log Function

SeasLog::log

(PECL seaslog >=1.0.0)

SeasLog::log — The Common Record Log Function

説明

public static SeasLog::log(
string $level,
string $message = ?,
array $content = ?,
string $logger = ?
): bool

The Common Record Log Function.

パラメータ

level

Can use level in:

  • SEASLOG_DEBUG
  • SEASLOG_INFO
  • SEASLOG_NOTICE
  • SEASLOG_WARNING
  • SEASLOG_ERROR
  • SEASLOG_CRITICAL
  • SEASLOG_ALERT
  • SEASLOG_EMERGENCY
Or you can create a new level self-help.

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::log() example

<?php

var_dump(SeasLog::log(SEASLOG_INFO,'info log'));
var_dump(SeasLog::getBuffer());

//create a new level self-help.
var_dump(SeasLog::log('MySelfLevel','info log'));
var_dump(SeasLog::getBuffer());

//with `content`
var_dump(SeasLog::log('MySelfLevel','info log {NAME}',array('NAME' => 'neeke')));
var_dump(SeasLog::getBuffer());

//with `logger`
var_dump(SeasLog::log('MySelfLevel','info log {NAME}',array('NAME' => 'neeke'),'tmp_logger'));
var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(1) {
    [0]=>
    string(79) "2018-07-07 11:12:37 | INFO | 72427 | 5b402fa56a2ea | 1530933157.436 | info log
"
  }
}

bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(1) {
    [0]=>
    string(86) "2018-07-07 11:13:59 | MySelfLevel | 72470 | 5b402ff781c5e | 1530933239.532 | info log
"
  }
}

bool(true)
array(1) {
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:28:12 | MySelfLevel | 72833 | 5b40334ce6a2f | 1530934092.946 | info log neeke
"
  }
}

bool(true)
array(1) {
  ["/var/log/www/default/20180707.log"]=>
  array(1) {
    [0]=>
    string(86) "2018-07-07 11:20:12 | INFO | 72616 | 5b40316c3641e | 1530933612.222 | info log neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information


Record notice log information

  • ≪ SeasLog::log
  • SeasLog::setBasePath ≫
  • PHP Manual
  • SeasLog
  • Record notice log information

SeasLog::notice

(PECL seaslog >=1.0.0)

SeasLog::notice — Record notice log information

説明

public static SeasLog::notice(string $message, array $content = ?, string $logger = ?): bool

Record notice log information.

注意:

"NOTICE" - Normal but significant events.Information that is more important than the INFO level during execution.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::notice() example

<?php

var_dump(SeasLog::notice('log message'));

//with content
var_dump(SeasLog::notice('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::notice('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | NOTICE | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | NOTICE | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | NOTICE | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::warning() - Record warning log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


Set SeasLog base path

  • ≪ SeasLog::notice
  • SeasLog::setDatetimeFormat ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog base path

SeasLog::setBasePath

(PECL seaslog >=1.0.0)

SeasLog::setBasePath — Set SeasLog base path

説明

public static SeasLog::setBasePath(string $base_path): bool

Set SeasLog base path.

パラメータ

base_path

String.

戻り値

Return TRUE on setted base path success, FALSE on failure.

例

例1 SeasLog::setBasePath() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Set SeasLog datetime format style

  • ≪ SeasLog::setBasePath
  • SeasLog::setLogger ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog datetime format style

SeasLog::setDatetimeFormat

(PECL seaslog >=1.0.0)

SeasLog::setDatetimeFormat — Set SeasLog datetime format style

説明

public static SeasLog::setDatetimeFormat(string $format): bool

Set SeasLog datetime format style.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

format

String. Such as `Y-m-d H:i:s` or `Ymd His`. See also first param `format` at date().

戻り値

Return TRUE on setted datetime format success, FALSE on failure.

例

例1 SeasLog::setDatetimeFormat() example

<?php

var_dump(SeasLog::setDateTimeFormat('Ymd His'));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • SeasLog::getDateTimeFormat() - Get SeasLog datetime format style


Set SeasLog logger name

  • ≪ SeasLog::setDatetimeFormat
  • SeasLog::setRequestID ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog logger name

SeasLog::setLogger

(PECL seaslog >=1.0.0)

SeasLog::setLogger — Set SeasLog logger name

説明

public static SeasLog::setLogger(string $logger): bool

Use the Function SeasLog::setLogger() will change the value of function SeasLog::getLastLogger(). Than's mean, SeasLog will record loginfo into the logger directory.

パラメータ

logger

Logger name.

戻り値

Return TRUE on created logger disectory success, FALSE on failure.

例

例1 SeasLog::setLogger() example

<?php

var_dump(SeasLog::setLogger('testModule/testLogger'));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • SeasLog::getLastLogger() - Get SeasLog last logger path
  • SeasLog::closeLoggerStream() - Manually release stream flow from logger


Set SeasLog request_id differentiated requests

  • ≪ SeasLog::setLogger
  • SeasLog::setRequestVariable ≫
  • PHP Manual
  • SeasLog
  • Set SeasLog request_id differentiated requests

SeasLog::setRequestID

(PECL seaslog >=1.0.0)

SeasLog::setRequestID — Set SeasLog request_id differentiated requests

説明

public static SeasLog::setRequestID(string $request_id): bool

To distinguish a single request, such as not invoking the SeasLog::setRequestId() function， the unique value generated by the built-in `static char *get_uniqid ()` function is used when the request is initialized.

パラメータ

request_id

String.

戻り値

Return TRUE on set request_id success, FALSE on failure.

例

例1 SeasLog::setRequestID() example

<?php

var_dump(SeasLog::setRequestID(time() . rand()));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)

参考

  • SeasLog::getRequestID() - Get SeasLog request_id differentiated requests


Manually set SeasLog request variable

  • ≪ SeasLog::setRequestID
  • SeasLog::warning ≫
  • PHP Manual
  • SeasLog
  • Manually set SeasLog request variable

SeasLog::setRequestVariable

(PECL seaslog >=1.9.0)

SeasLog::setRequestVariable — Manually set SeasLog request variable

説明

public static SeasLog::setRequestVariable(int $key, string $value): bool

Manually set SeasLog request variable.

パラメータ

key

Constant int.

  • SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT
  • SEASLOG_REQUEST_VARIABLE_REQUEST_URI
  • SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD
  • SEASLOG_REQUEST_VARIABLE_CLIENT_IP

value

The request variable value.

戻り値

Return TRUE on set success, FALSE on failure.

例

例1 SeasLog::setRequestVariable() example

<?php

$sDomainPort = 'domain:port';
$sRequestUri = 'uri';
$sRequestMethod = 'method';
$sClientIp = 'client_ip';

$iErrorKey = 1000;

$oSeasLog = new SeasLog();

var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT, $sDomainPort));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI, $sRequestUri));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD, $sRequestMethod));
var_dump($oSeasLog->setRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP, $sClientIp));

var_dump($oSeasLog->setRequestVariable($iErrorKey,NULL));

var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_DOMAIN_PORT) == $sDomainPort);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_URI) == $sRequestUri);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_REQUEST_METHOD) == $sRequestMethod);
var_dump($oSeasLog->getRequestVariable(SEASLOG_REQUEST_VARIABLE_CLIENT_IP) == $sClientIp);

var_dump($oSeasLog->getRequestVariable($iErrorKey));

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)
bool(false)

参考

  • SeasLog::getRequestVariable() - Get SeasLog request variable


Record warning log information

  • ≪ SeasLog::setRequestVariable
  • SPL ≫
  • PHP Manual
  • SeasLog
  • Record warning log information

SeasLog::warning

(PECL seaslog >=1.0.0)

SeasLog::warning — Record warning log information

説明

public static SeasLog::warning(string $message, array $content = ?, string $logger = ?): bool

Record warning log information.

注意:

"WARNING" - Exceptional occurrences that are not errors. Potentially aberrant information that needs attention and needs to be repaired.

パラメータ

message

The log message.

content

The `message` contain placeholders which implementors replace with values from content array. Sush as `message` is `log info from {NAME}` and `content` is `array('NAME' => neeke)`, the log information will `log info from neeke`.

logger

The `logger` cased by the third param would be used right this right now, like a temp logger, when the function SeasLog::setLogger() called in pre content. If `logger` NULL or "", SeasLog will use lastest logger setted by SeasLog::setLogger().

戻り値

Return TRUE on record log information success, FALSE on failure.

例

例1 SeasLog::warning() example

<?php

var_dump(SeasLog::warning('log message'));

//with content
var_dump(SeasLog::warning('log message from {NAME}',array('NAME' => 'neeke')));

//with tmp logger
var_dump(SeasLog::warning('log message from {NAME}',array('NAME' => 'neeke'),'tmp_logger'));

var_dump(SeasLog::getBuffer());

?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
array(2) {
  ["/var/log/www/default/20180707.log"]=>
  array(2) {
    [0]=>
    string(81) "2018-07-07 11:45:49 | WARNING | 73263 | 5b40376d1067c | 1530935149.68 | log message
"
    [1]=>
    string(92) "2018-07-07 11:45:49 | WARNING | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
  ["/var/log/www/tmp_logger/20180707.log"]=>
  array(1) {
    [0]=>
    string(92) "2018-07-07 11:45:49 | WARNING | 73263 | 5b40376d1067c | 1530935149.68 | log message from neeke
"
  }
}

参考

  • seaslog.default_template
  • SeasLog::debug() - Record debug log information
  • SeasLog::info() - Record info log information
  • SeasLog::notice() - Record notice log information
  • SeasLog::error() - Record error log information
  • SeasLog::critical() - Record critical log information
  • SeasLog::alert() - Record alert log information
  • SeasLog::emergency() - Record emergency log information
  • SeasLog::log() - The Common Record Log Function


Standard PHP Library (SPL)

  • はじめに
  • 定義済み定数
  • データ構造
    • SplDoublyLinkedList — SplDoublyLinkedList クラス
    • SplStack — SplStack クラス
    • SplQueue — SplQueue クラス
    • SplHeap — SplHeap クラス
    • SplMaxHeap — SplMaxHeap クラス
    • SplMinHeap — SplMinHeap クラス
    • SplPriorityQueue — SplPriorityQueue クラス
    • SplFixedArray — SplFixedArray クラス
    • SplObjectStorage — SplObjectStorage クラス
  • イテレータ
    • AppendIterator — AppendIterator クラス
    • ArrayIterator — ArrayIterator クラス
    • CachingIterator — CachingIterator クラス
    • CallbackFilterIterator — CallbackFilterIterator クラス
    • DirectoryIterator — DirectoryIterator クラス
    • EmptyIterator — EmptyIterator クラス
    • FilesystemIterator — FilesystemIterator クラス
    • FilterIterator — FilterIterator クラス
    • GlobIterator — GlobIterator クラス
    • InfiniteIterator — InfiniteIterator クラス
    • IteratorIterator — IteratorIterator クラス
    • LimitIterator — LimitIterator クラス
    • MultipleIterator — MultipleIterator クラス
    • NoRewindIterator — NoRewindIterator クラス
    • ParentIterator — ParentIterator クラス
    • RecursiveArrayIterator — RecursiveArrayIterator クラス
    • RecursiveCachingIterator — RecursiveCachingIterator クラス
    • RecursiveCallbackFilterIterator — RecursiveCallbackFilterIterator クラス
    • RecursiveDirectoryIterator — RecursiveDirectoryIterator クラス
    • RecursiveFilterIterator — RecursiveFilterIterator クラス
    • RecursiveIteratorIterator — RecursiveIteratorIterator クラス
    • RecursiveRegexIterator — RecursiveRegexIterator クラス
    • RecursiveTreeIterator — RecursiveTreeIterator クラス
    • RegexIterator — RegexIterator クラス
  • インターフェイス
    • Countable — Countable インターフェイス
    • OuterIterator — OuterIterator インターフェイス
    • RecursiveIterator — RecursiveIterator インターフェイス
    • SeekableIterator — SeekableIterator インターフェイス
  • 例外
    • BadFunctionCallException — BadFunctionCallException クラス
    • BadMethodCallException — BadMethodCallException クラス
    • DomainException — DomainException クラス
    • InvalidArgumentException — InvalidArgumentException クラス
    • LengthException — LengthException クラス
    • LogicException — LogicException クラス
    • OutOfBoundsException — OutOfBoundsException クラス
    • OutOfRangeException — OutOfRangeException クラス
    • OverflowException — OverflowException クラス
    • RangeException — RangeException クラス
    • RuntimeException — RuntimeException クラス
    • UnderflowException — UnderflowException クラス
    • UnexpectedValueException — UnexpectedValueException クラス
  • SPL 関数
    • class_implements — 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
    • class_parents — 与えられたクラスの親クラスを返す
    • class_uses — 指定したクラスが使っているトレイトを返す
    • iterator_apply — ユーザー関数をイテレータのすべての要素でコールする
    • iterator_count — イテレータにある要素をカウントする
    • iterator_to_array — イテレータを配列にコピーする
    • spl_autoload — __autoload() のデフォルト実装
    • spl_autoload_call — 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す
    • spl_autoload_extensions — spl_autoload 用のデフォルトの拡張子を登録し、それを返す
    • spl_autoload_functions — すべての登録済み __autoload() 関数を返す
    • spl_autoload_register — 指定した関数を __autoload() の実装として登録する
    • spl_autoload_unregister — 指定した関数の、__autoload() の実装としての登録を解除する
    • spl_classes — 利用可能な SPL クラスを返す
    • spl_object_hash — 指定したオブジェクトのハッシュ ID を返す
    • spl_object_id — 与えられたオブジェクトを扱う数値オブジェクトを返す
  • ファイル操作
    • SplFileInfo — SplFileInfo クラス
    • SplFileObject — SplFileObject クラス
    • SplTempFileObject — SplTempFileObject クラス
  • その他のクラスおよびインターフェイス
    • ArrayObject — ArrayObject クラス
    • SplObserver — SplObserver インターフェイス
    • SplSubject — SplSubject インターフェイス


はじめに

The Standard PHP Library (SPL) は、標準的な問題を解決するためのインターフェイスやクラスを集めたものです。

SPL は、標準データ構造や、オブジェクトを走査するためのイテレータ、インターフェイス、標準の例外、そしてファイルを扱うクラスなどを提供し、 spl_autoload_register() などの関数も提供します。


データ構造

目次

  • SplDoublyLinkedList
  • SplStack
  • SplQueue
  • SplHeap
  • SplMaxHeap
  • SplMinHeap
  • SplPriorityQueue
  • SplFixedArray
  • SplObjectStorage

SPL では、標準的なデータ構造を提供しています。 ここで、それらを実装ごとに分類してまとめます。

双方向リンクリスト

双方向リンクリスト (Doubly Linked List: DLL) は、双方向のノードへのリンクを持つノードのリストです。 イテレータの操作、両隣へのアクセス、ノードの追加や削除のコストは、 データ構造が DLL の場合は O(1) となります。 これは、スタックやキューを実装するのに適しています。

  • SplDoublyLinkedList
    • SplStack
    • SplQueue

ヒープ

ヒープは、ツリー風の構造です。ヒープ特有の性質として、 個々のノードはその子ノードと等しいかそれより大きな値となります。 値の比較は、ヒープ全体の比較メソッドとして実装されているものを使用します。

  • SplHeap
    • SplMaxHeap
    • SplMinHeap
  • SplPriorityQueue

配列

配列は、データを連続的に格納してインデックス経由でアクセスできるようにした構造です。 PHP の配列と混同しないようにしましょう。PHP の配列は、 実際のところは順序つきハッシュテーブルとして実装されています。

  • SplFixedArray

マップ

マップは、キー/値 のペアからなるデータ構造です。 PHP の配列は、整数値/文字列を値と対応させたマップとみなすことができます。 SPL では、オブジェクトとデータを対応させるマップを提供しています。 このマップは、オブジェクトの集合として扱うことができます。

  • SplObjectStorage


SplDoublyLinkedList クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplDoublyLinkedList クラスは、双方向リンクリストの主要な機能を提供します。

クラス概要

class SplDoublyLinkedList implements Iterator, Countable, ArrayAccess, Serializable {
/* 定数 */
public const int IT_MODE_LIFO;
public const int IT_MODE_FIFO;
public const int IT_MODE_DELETE;
public const int IT_MODE_KEEP;
/* メソッド */
public add(int $index, mixed $value): void
public bottom(): mixed
public count(): int
public current(): mixed
public getIteratorMode(): int
public isEmpty(): bool
public key(): int
public next(): void
public offsetExists(int $index): bool
public offsetGet(int $index): mixed
public offsetSet(?int $index, mixed $value): void
public offsetUnset(int $index): void
public pop(): mixed
public prev(): void
public push(mixed $value): void
public rewind(): void
public serialize(): string
public setIteratorMode(int $mode): int
public shift(): mixed
public top(): mixed
public unserialize(string $data): void
public unshift(mixed $value): void
public valid(): bool
}

定義済み定数

イテレーションの方向

SplDoublyLinkedList::IT_MODE_LIFO

スタックのように、LIFO (最後に入れたものを最初に取り出す) の順で走査されます。

SplDoublyLinkedList::IT_MODE_FIFO

キューのように、FIFO(先入れ先出し) の順で走査されます。

イテレーションの振る舞い

SplDoublyLinkedList::IT_MODE_DELETE

走査された要素を削除します。

SplDoublyLinkedList::IT_MODE_KEEP

走査されても要素を削除しません。

目次

  • SplDoublyLinkedList::add — 特定のインデックスに新しい値を 追加/挿入 する
  • SplDoublyLinkedList::bottom — 双方向リンクリストの最初のノードを取得する
  • SplDoublyLinkedList::count — 双方向リンクリストの要素数を数える
  • SplDoublyLinkedList::current — 現在の配列の要素を返す
  • SplDoublyLinkedList::getIteratorMode — 反復処理のモードを返す
  • SplDoublyLinkedList::isEmpty — 双方向リンクリストが空かどうかを調べる
  • SplDoublyLinkedList::key — 現在のノードのインデックスを返す
  • SplDoublyLinkedList::next — 次のエントリに移動する
  • SplDoublyLinkedList::offsetExists — 指定した $index が存在するかどうかを返す
  • SplDoublyLinkedList::offsetGet — 指定した $index の値を返す
  • SplDoublyLinkedList::offsetSet — 指定した $index の値を $value に設定する
  • SplDoublyLinkedList::offsetUnset — 指定した $index の値を削除する
  • SplDoublyLinkedList::pop — 双方向リンクリストの末尾からノードを取り出す
  • SplDoublyLinkedList::prev — 前のエントリに移動する
  • SplDoublyLinkedList::push — 双方向リンクリストの末尾に要素を追加する
  • SplDoublyLinkedList::rewind — イテレータを先頭に巻き戻す
  • SplDoublyLinkedList::serialize — ストレージをシリアライズする
  • SplDoublyLinkedList::setIteratorMode — 反復処理のモードを設定する
  • SplDoublyLinkedList::shift — 双方向リンクリストの先頭からノードを取り出す
  • SplDoublyLinkedList::top — 双方向リンクリストの最後のノードを取得する
  • SplDoublyLinkedList::unserialize — ストレージをアンシリアライズする
  • SplDoublyLinkedList::unshift — 双方向リンクリストの先頭に要素を追加する
  • SplDoublyLinkedList::valid — 双方向リンクリストにまだノードがあるかどうかを調べる


特定のインデックスに新しい値を 追加/挿入 する

  • ≪ SplDoublyLinkedList
  • SplDoublyLinkedList::bottom ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 特定のインデックスに新しい値を 追加/挿入 する

SplDoublyLinkedList::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

SplDoublyLinkedList::add — 特定のインデックスに新しい値を 追加/挿入 する

説明

public SplDoublyLinkedList::add(int $index, mixed $value): void

指定された index に value を挿入し、 以前その位置にあった値(とそれ以後にあるリストの値すべて)をシャッフルします

パラメータ

index

新しい値が挿入されるインデックス

value

index に入る新しい値

戻り値

値を返しません。

エラー / 例外

index が範囲外だったり、 index が数値としてパースできない場合は、 OutOfRangeException がスローされます。


双方向リンクリストの最初のノードを取得する

  • ≪ SplDoublyLinkedList::add
  • SplDoublyLinkedList::count ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの最初のノードを取得する

SplDoublyLinkedList::bottom

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::bottom — 双方向リンクリストの最初のノードを取得する

説明

public SplDoublyLinkedList::bottom(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

最初のノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。


双方向リンクリストの要素数を数える

  • ≪ SplDoublyLinkedList::bottom
  • SplDoublyLinkedList::current ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの要素数を数える

SplDoublyLinkedList::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::count — 双方向リンクリストの要素数を数える

説明

public SplDoublyLinkedList::count(): int

パラメータ

この関数にはパラメータはありません。

戻り値

双方向リンクリストの要素数を返します。


現在の配列の要素を返す

  • ≪ SplDoublyLinkedList::count
  • SplDoublyLinkedList::getIteratorMode ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 現在の配列の要素を返す

SplDoublyLinkedList::current

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::current — 現在の配列の要素を返す

説明

public SplDoublyLinkedList::current(): mixed

双方向リンクリストの現在のノードを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードの値を返します。


反復処理のモードを返す

  • ≪ SplDoublyLinkedList::current
  • SplDoublyLinkedList::isEmpty ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 反復処理のモードを返す

SplDoublyLinkedList::getIteratorMode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::getIteratorMode — 反復処理のモードを返す

説明

public SplDoublyLinkedList::getIteratorMode(): int

パラメータ

この関数にはパラメータはありません。

戻り値

反復処理の際のモードおよびフラグを返します。


双方向リンクリストが空かどうかを調べる

  • ≪ SplDoublyLinkedList::getIteratorMode
  • SplDoublyLinkedList::key ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストが空かどうかを調べる

SplDoublyLinkedList::isEmpty

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::isEmpty — 双方向リンクリストが空かどうかを調べる

説明

public SplDoublyLinkedList::isEmpty(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

双方向リンクリストが空かどうかを返します。


現在のノードのインデックスを返す

  • ≪ SplDoublyLinkedList::isEmpty
  • SplDoublyLinkedList::next ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 現在のノードのインデックスを返す

SplDoublyLinkedList::key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::key — 現在のノードのインデックスを返す

説明

public SplDoublyLinkedList::key(): int

この館数は、現在のノードのインデックスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードのインデックスを返します。


次のエントリに移動する

  • ≪ SplDoublyLinkedList::key
  • SplDoublyLinkedList::offsetExists ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 次のエントリに移動する

SplDoublyLinkedList::next

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::next — 次のエントリに移動する

説明

public SplDoublyLinkedList::next(): void

イテレータを次のノードに移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


指定した $index が存在するかどうかを返す

  • ≪ SplDoublyLinkedList::next
  • SplDoublyLinkedList::offsetGet ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index が存在するかどうかを返す

SplDoublyLinkedList::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::offsetExists — 指定した $index が存在するかどうかを返す

説明

public SplDoublyLinkedList::offsetExists(int $index): bool

パラメータ

index

調べたいインデックス。

戻り値

指定した index が存在する場合に true、 それ以外の場合に false を返します。


指定した $index の値を返す

  • ≪ SplDoublyLinkedList::offsetExists
  • SplDoublyLinkedList::offsetSet ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index の値を返す

SplDoublyLinkedList::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::offsetGet — 指定した $index の値を返す

説明

public SplDoublyLinkedList::offsetGet(int $index): mixed

パラメータ

index

値を取得したいインデックス。

戻り値

指定した index の値を返します。

エラー / 例外

index が範囲外を指すときや index が整数として解釈できないときに OutOfRangeException をスローします。


指定した $index の値を $value に設定する

  • ≪ SplDoublyLinkedList::offsetGet
  • SplDoublyLinkedList::offsetUnset ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index の値を $value に設定する

SplDoublyLinkedList::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::offsetSet — 指定した $index の値を $value に設定する

説明

public SplDoublyLinkedList::offsetSet(?int $index, mixed $value): void

指定した index の値を value に設定します。

パラメータ

index

設定したいインデックス。 null の場合、最後の項目の次の値が追加されます。

value

index の新しい値。

戻り値

値を返しません。

エラー / 例外

index が範囲外を指すときや index が整数として解釈できないときに OutOfRangeException をスローします。


指定した $index の値を削除する

  • ≪ SplDoublyLinkedList::offsetSet
  • SplDoublyLinkedList::pop ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 指定した $index の値を削除する

SplDoublyLinkedList::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::offsetUnset — 指定した $index の値を削除する

説明

public SplDoublyLinkedList::offsetUnset(int $index): void

指定したインデックスの値を削除します。

パラメータ

index

削除したいインデックス。

戻り値

値を返しません。

エラー / 例外

index が範囲外を指すときや index が整数として解釈できないときに OutOfRangeException をスローします。


双方向リンクリストの末尾からノードを取り出す

  • ≪ SplDoublyLinkedList::offsetUnset
  • SplDoublyLinkedList::prev ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの末尾からノードを取り出す

SplDoublyLinkedList::pop

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::pop — 双方向リンクリストの末尾からノードを取り出す

説明

public SplDoublyLinkedList::pop(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

取り出したノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。


前のエントリに移動する

  • ≪ SplDoublyLinkedList::pop
  • SplDoublyLinkedList::push ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 前のエントリに移動する

SplDoublyLinkedList::prev

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::prev — 前のエントリに移動する

説明

public SplDoublyLinkedList::prev(): void

イテレータを前のノードに移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


双方向リンクリストの末尾に要素を追加する

  • ≪ SplDoublyLinkedList::prev
  • SplDoublyLinkedList::rewind ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの末尾に要素を追加する

SplDoublyLinkedList::push

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::push — 双方向リンクリストの末尾に要素を追加する

説明

public SplDoublyLinkedList::push(mixed $value): void

value を双方向リンクリストの末尾に追加します。

パラメータ

value

追加したい値。

戻り値

値を返しません。


イテレータを先頭に巻き戻す

  • ≪ SplDoublyLinkedList::push
  • SplDoublyLinkedList::serialize ≫
  • PHP Manual
  • SplDoublyLinkedList
  • イテレータを先頭に巻き戻す

SplDoublyLinkedList::rewind

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::rewind — イテレータを先頭に巻き戻す

説明

public SplDoublyLinkedList::rewind(): void

イテレータを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


ストレージをシリアライズする

  • ≪ SplDoublyLinkedList::rewind
  • SplDoublyLinkedList::setIteratorMode ≫
  • PHP Manual
  • SplDoublyLinkedList
  • ストレージをシリアライズする

SplDoublyLinkedList::serialize

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SplDoublyLinkedList::serialize — ストレージをシリアライズする

説明

public SplDoublyLinkedList::serialize(): string

ストレージをシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

シリアライズした文字列を返します。

参考

  • SplDoublyLinkedList::unserialize() - ストレージをアンシリアライズする


反復処理のモードを設定する

  • ≪ SplDoublyLinkedList::serialize
  • SplDoublyLinkedList::shift ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 反復処理のモードを設定する

SplDoublyLinkedList::setIteratorMode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::setIteratorMode — 反復処理のモードを設定する

説明

public SplDoublyLinkedList::setIteratorMode(int $mode): int

パラメータ

mode

次の 2 種類の直交するモードを設定できます。

  • 反復処理の方向 (いずれかを選択)
    • SplDoublyLinkedList::IT_MODE_LIFO (スタック方式)
    • SplDoublyLinkedList::IT_MODE_FIFO (キュー方式)
  • イテレータの振る舞い (いずれかを選択)
    • SplDoublyLinkedList::IT_MODE_DELETE (イテレータが要素を削除する)
    • SplDoublyLinkedList::IT_MODE_KEEP (イテレータが要素を順にたどる)

デフォルトのモードは SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLnkedList::IT_MODE_KEEP です。

警告

SplStack と SplQueue においては、反復処理の方向は変更できません。 これらのクラスでは、反復処理の方向は常に SplDoublyLinkedList::IT_MODE_FIFO になります。 この値を変更しようとすると、RuntimeException がスローされます。

戻り値

反復処理に影響する、異なるモードとフラグの値を返します。


双方向リンクリストの先頭からノードを取り出す

  • ≪ SplDoublyLinkedList::setIteratorMode
  • SplDoublyLinkedList::top ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの先頭からノードを取り出す

SplDoublyLinkedList::shift

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::shift — 双方向リンクリストの先頭からノードを取り出す

説明

public SplDoublyLinkedList::shift(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

取り出したノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。


双方向リンクリストの最後のノードを取得する

  • ≪ SplDoublyLinkedList::shift
  • SplDoublyLinkedList::unserialize ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの最後のノードを取得する

SplDoublyLinkedList::top

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::top — 双方向リンクリストの最後のノードを取得する

説明

public SplDoublyLinkedList::top(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

最後のノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。


ストレージをアンシリアライズする

  • ≪ SplDoublyLinkedList::top
  • SplDoublyLinkedList::unshift ≫
  • PHP Manual
  • SplDoublyLinkedList
  • ストレージをアンシリアライズする

SplDoublyLinkedList::unserialize

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SplDoublyLinkedList::unserialize — ストレージをアンシリアライズする

説明

public SplDoublyLinkedList::unserialize(string $data): void

SplDoublyLinkedList::serialize() でシリアライズしたストレージを復元します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

シリアライズした文字列。

戻り値

値を返しません。

参考

  • SplDoublyLinkedList::serialize() - ストレージをシリアライズする


双方向リンクリストの先頭に要素を追加する

  • ≪ SplDoublyLinkedList::unserialize
  • SplDoublyLinkedList::valid ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストの先頭に要素を追加する

SplDoublyLinkedList::unshift

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::unshift — 双方向リンクリストの先頭に要素を追加する

説明

public SplDoublyLinkedList::unshift(mixed $value): void

value を双方向リンクリストの先頭に追加します。

パラメータ

value

追加する値。

戻り値

値を返しません。


双方向リンクリストにまだノードがあるかどうかを調べる

  • ≪ SplDoublyLinkedList::unshift
  • SplStack ≫
  • PHP Manual
  • SplDoublyLinkedList
  • 双方向リンクリストにまだノードがあるかどうかを調べる

SplDoublyLinkedList::valid

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplDoublyLinkedList::valid — 双方向リンクリストにまだノードがあるかどうかを調べる

説明

public SplDoublyLinkedList::valid(): bool

双方向リンクリストにまだノードがあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

双方向リンクリストにまだノードが含まれる場合に true、 そうでない場合に false を返します。


SplStack クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplStack クラスは、スタックの主要な機能を提供します。 双方向リンクリストのイテレータのモードを SplDoublyLinkedList::IT_MODE_LIFO に設定することで実装しています。

クラス概要

class SplStack extends SplDoublyLinkedList {
/* 継承した定数 */
public const int SplDoublyLinkedList::IT_MODE_LIFO;
public const int SplDoublyLinkedList::IT_MODE_FIFO;
public const int SplDoublyLinkedList::IT_MODE_DELETE;
public const int SplDoublyLinkedList::IT_MODE_KEEP;
/* 継承したメソッド */
public SplDoublyLinkedList::add(int $index, mixed $value): void
public SplDoublyLinkedList::bottom(): mixed
public SplDoublyLinkedList::count(): int
public SplDoublyLinkedList::current(): mixed
public SplDoublyLinkedList::getIteratorMode(): int
public SplDoublyLinkedList::isEmpty(): bool
public SplDoublyLinkedList::key(): int
public SplDoublyLinkedList::next(): void
public SplDoublyLinkedList::offsetExists(int $index): bool
public SplDoublyLinkedList::offsetGet(int $index): mixed
public SplDoublyLinkedList::offsetSet(?int $index, mixed $value): void
public SplDoublyLinkedList::offsetUnset(int $index): void
public SplDoublyLinkedList::pop(): mixed
public SplDoublyLinkedList::prev(): void
public SplDoublyLinkedList::push(mixed $value): void
public SplDoublyLinkedList::rewind(): void
public SplDoublyLinkedList::serialize(): string
public SplDoublyLinkedList::setIteratorMode(int $mode): int
public SplDoublyLinkedList::shift(): mixed
public SplDoublyLinkedList::top(): mixed
public SplDoublyLinkedList::unserialize(string $data): void
public SplDoublyLinkedList::unshift(mixed $value): void
public SplDoublyLinkedList::valid(): bool
}

例

例1 SplStack の例

<?php
$q = new SplStack();
$q[] = 1;
$q[] = 2;
$q[] = 3;
foreach ($q as $elem) {
echo $elem."\n";
}
?>

上の例の出力は以下となります。

3
2
1


SplQueue クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplQueue クラスは、キューの主要な機能を提供します。 双方向リンクリストのイテレータのモードを SplDoublyLinkedList::IT_MODE_FIFO に設定することで実装しています。

クラス概要

class SplQueue extends SplDoublyLinkedList {
/* 継承した定数 */
public const int SplDoublyLinkedList::IT_MODE_LIFO;
public const int SplDoublyLinkedList::IT_MODE_FIFO;
public const int SplDoublyLinkedList::IT_MODE_DELETE;
public const int SplDoublyLinkedList::IT_MODE_KEEP;
/* メソッド */
public dequeue(): mixed
public enqueue(mixed $value): void
/* 継承したメソッド */
public SplDoublyLinkedList::add(int $index, mixed $value): void
public SplDoublyLinkedList::bottom(): mixed
public SplDoublyLinkedList::count(): int
public SplDoublyLinkedList::current(): mixed
public SplDoublyLinkedList::getIteratorMode(): int
public SplDoublyLinkedList::isEmpty(): bool
public SplDoublyLinkedList::key(): int
public SplDoublyLinkedList::next(): void
public SplDoublyLinkedList::offsetExists(int $index): bool
public SplDoublyLinkedList::offsetGet(int $index): mixed
public SplDoublyLinkedList::offsetSet(?int $index, mixed $value): void
public SplDoublyLinkedList::offsetUnset(int $index): void
public SplDoublyLinkedList::pop(): mixed
public SplDoublyLinkedList::prev(): void
public SplDoublyLinkedList::push(mixed $value): void
public SplDoublyLinkedList::rewind(): void
public SplDoublyLinkedList::serialize(): string
public SplDoublyLinkedList::setIteratorMode(int $mode): int
public SplDoublyLinkedList::shift(): mixed
public SplDoublyLinkedList::top(): mixed
public SplDoublyLinkedList::unserialize(string $data): void
public SplDoublyLinkedList::unshift(mixed $value): void
public SplDoublyLinkedList::valid(): bool
}

例

例1 SplQueue の例

<?php
$q = new SplQueue();
$q[] = 1;
$q[] = 2;
$q[] = 3;
foreach ($q as $elem) {
echo $elem."\n";
}
?>

上の例の出力は以下となります。

1
2
3

例2 SplQueue を使ってタスクを効率的に処理する

<?php
$q = new SplQueue();
$q->setIteratorMode(SplQueue::IT_MODE_DELETE);
// ... enqueue some tasks on the queue ...
// process them
foreach ($q as $task) {
// ... process $task ...
// add new tasks on the queue
$q[] = $newTask;
// ...
}
?>

目次

  • SplQueue::dequeue — キューからノードを取り出す
  • SplQueue::enqueue — 要素をキューに追加する


キューからノードを取り出す

  • ≪ SplQueue
  • SplQueue::enqueue ≫
  • PHP Manual
  • SplQueue
  • キューからノードを取り出す

SplQueue::dequeue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplQueue::dequeue — キューからノードを取り出す

説明

public SplQueue::dequeue(): mixed

value をキューの先頭から取り出します。

注意:

SplQueue::dequeue() は SplDoublyLinkedList::shift() のエイリアスです。

パラメータ

この関数にはパラメータはありません。

戻り値

キューから取り出したノードの値を返します。


要素をキューに追加する

  • ≪ SplQueue::dequeue
  • SplHeap ≫
  • PHP Manual
  • SplQueue
  • 要素をキューに追加する

SplQueue::enqueue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplQueue::enqueue — 要素をキューに追加する

説明

public SplQueue::enqueue(mixed $value): void

value をキューの末尾に追加します。

注意:

SplQueue::enqueue() は SplDoublyLinkedList::push() のエイリアスです。

パラメータ

value

キューに追加する値。

戻り値

値を返しません。


SplHeap クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplHeap クラスは、ヒープの主要な機能を提供します。

クラス概要

abstract class SplHeap implements Iterator, Countable {
/* メソッド */
protected compare(mixed $value1, mixed $value2): int
public count(): int
public current(): mixed
public extract(): mixed
public insert(mixed $value): true
public isCorrupted(): bool
public isEmpty(): bool
public key(): int
public next(): void
public recoverFromCorruption(): bool
public rewind(): void
public top(): mixed
public valid(): bool
}

目次

  • SplHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く
  • SplHeap::count — ヒープ内の要素数を数える
  • SplHeap::current — イテレータが指す現在のノードを返す
  • SplHeap::extract — ヒープの先頭からノードを取り出す
  • SplHeap::insert — ヒープに要素を挿入する
  • SplHeap::isCorrupted — ヒープが壊れているかを調べる
  • SplHeap::isEmpty — ヒープが空かどうかを調べる
  • SplHeap::key — 現在のノードのインデックスを返す
  • SplHeap::next — 次のノードに移動する
  • SplHeap::recoverFromCorruption — 破壊されたヒープを復旧し、それ以降の操作をできるようにする
  • SplHeap::rewind — イテレータを先頭に巻き戻す (何もしない)
  • SplHeap::top — ヒープの先頭のノードを取り出す
  • SplHeap::valid — ヒープにまだノードがあるかどうかを調べる


要素を比較し、ヒープ内の適切な位置に置く

  • ≪ SplHeap
  • SplHeap::count ≫
  • PHP Manual
  • SplHeap
  • 要素を比較し、ヒープ内の適切な位置に置く

SplHeap::compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

説明

protected SplHeap::compare(mixed $value1, mixed $value2): int

value1 と value2 を比較します。

警告

SplHeap::compare() 内で例外がスローされると、ヒープが壊れてしまいブロックされた状態になることがあります。 SplHeap::recoverFromCorruption() をコールすればブロック状態を解除することができます。 しかし、適切な場所に配置されていない要素が出てくることもあり、 ヒープの性質が失われてしまいます。

パラメータ

value1

比較したい最初のノード。

value2

比較したい 2 番目のノード。

戻り値

比較結果を返します。value1 が value2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の値を持つ複数の要素をヒープ内に保持することはおすすめしません。 そうすると、ヒープ内の相対位置がはっきりしなくなってしまいます。


ヒープ内の要素数を数える

  • ≪ SplHeap::compare
  • SplHeap::current ≫
  • PHP Manual
  • SplHeap
  • ヒープ内の要素数を数える

SplHeap::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::count — ヒープ内の要素数を数える

説明

public SplHeap::count(): int

パラメータ

この関数にはパラメータはありません。

戻り値

ヒープ内の要素数を返します。


イテレータが指す現在のノードを返す

  • ≪ SplHeap::count
  • SplHeap::extract ≫
  • PHP Manual
  • SplHeap
  • イテレータが指す現在のノードを返す

SplHeap::current

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::current — イテレータが指す現在のノードを返す

説明

public SplHeap::current(): mixed

現在のノードを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードの値を返します。


ヒープの先頭からノードを取り出す

  • ≪ SplHeap::current
  • SplHeap::insert ≫
  • PHP Manual
  • SplHeap
  • ヒープの先頭からノードを取り出す

SplHeap::extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::extract — ヒープの先頭からノードを取り出す

説明

public SplHeap::extract(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

取り出したノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。


ヒープに要素を挿入する

  • ≪ SplHeap::extract
  • SplHeap::isCorrupted ≫
  • PHP Manual
  • SplHeap
  • ヒープに要素を挿入する

SplHeap::insert

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::insert — ヒープに要素を挿入する

説明

public SplHeap::insert(mixed $value): true

value をヒープに挿入します。

パラメータ

value

挿入する値。

戻り値

常に true を返します。


ヒープが壊れているかを調べる

  • ≪ SplHeap::insert
  • SplHeap::isEmpty ≫
  • PHP Manual
  • SplHeap
  • ヒープが壊れているかを調べる

SplHeap::isCorrupted

(PHP 7, PHP 8)

SplHeap::isCorrupted — ヒープが壊れているかを調べる

説明

public SplHeap::isCorrupted(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

ヒープが壊れていたら true を、そうでなければ false を返します。


ヒープが空かどうかを調べる

  • ≪ SplHeap::isCorrupted
  • SplHeap::key ≫
  • PHP Manual
  • SplHeap
  • ヒープが空かどうかを調べる

SplHeap::isEmpty

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::isEmpty — ヒープが空かどうかを調べる

説明

public SplHeap::isEmpty(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

ヒープが空かどうかを返します。


現在のノードのインデックスを返す

  • ≪ SplHeap::isEmpty
  • SplHeap::next ≫
  • PHP Manual
  • SplHeap
  • 現在のノードのインデックスを返す

SplHeap::key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::key — 現在のノードのインデックスを返す

説明

public SplHeap::key(): int

この関数は、現在のノードのインデックスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードのインデックスを返します。


次のノードに移動する

  • ≪ SplHeap::key
  • SplHeap::recoverFromCorruption ≫
  • PHP Manual
  • SplHeap
  • 次のノードに移動する

SplHeap::next

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::next — 次のノードに移動する

説明

public SplHeap::next(): void

次のノードに移動します。これは、ヒープの先頭のノードを削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


破壊されたヒープを復旧し、それ以降の操作をできるようにする

  • ≪ SplHeap::next
  • SplHeap::rewind ≫
  • PHP Manual
  • SplHeap
  • 破壊されたヒープを復旧し、それ以降の操作をできるようにする

SplHeap::recoverFromCorruption

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::recoverFromCorruption — 破壊されたヒープを復旧し、それ以降の操作をできるようにする

説明

public SplHeap::recoverFromCorruption(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。


イテレータを先頭に巻き戻す (何もしない)

  • ≪ SplHeap::recoverFromCorruption
  • SplHeap::top ≫
  • PHP Manual
  • SplHeap
  • イテレータを先頭に巻き戻す (何もしない)

SplHeap::rewind

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::rewind — イテレータを先頭に巻き戻す (何もしない)

説明

public SplHeap::rewind(): void

これは、イテレータを先頭に巻き戻します。ヒープの場合は何もしません。 というのもイテレータは仮想的なものであり、 実際はヒープの先頭から動くことがないからです。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


ヒープの先頭のノードを取り出す

  • ≪ SplHeap::rewind
  • SplHeap::valid ≫
  • PHP Manual
  • SplHeap
  • ヒープの先頭のノードを取り出す

SplHeap::top

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::top — ヒープの先頭のノードを取り出す

説明

public SplHeap::top(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

先頭のノードの値を返します。

エラー / 例外

データが空のときは RuntimeException をスローします。


ヒープにまだノードがあるかどうかを調べる

  • ≪ SplHeap::top
  • SplMaxHeap ≫
  • PHP Manual
  • SplHeap
  • ヒープにまだノードがあるかどうかを調べる

SplHeap::valid

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplHeap::valid — ヒープにまだノードがあるかどうかを調べる

説明

public SplHeap::valid(): bool

ヒープにまだノードがあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ヒープにまだノードが含まれる場合に true、 そうでない場合に false を返します。


SplMaxHeap クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplMaxHeap クラスは、ヒープの主要な機能を提供し、最大値を先頭に保ちます。

クラス概要

class SplMaxHeap extends SplHeap {
/* メソッド */
protected compare(mixed $value1, mixed $value2): int
/* 継承したメソッド */
protected SplHeap::compare(mixed $value1, mixed $value2): int
public SplHeap::count(): int
public SplHeap::current(): mixed
public SplHeap::extract(): mixed
public SplHeap::insert(mixed $value): true
public SplHeap::isCorrupted(): bool
public SplHeap::isEmpty(): bool
public SplHeap::key(): int
public SplHeap::next(): void
public SplHeap::recoverFromCorruption(): bool
public SplHeap::rewind(): void
public SplHeap::top(): mixed
public SplHeap::valid(): bool
}

目次

  • SplMaxHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く


要素を比較し、ヒープ内の適切な位置に置く

  • ≪ SplMaxHeap
  • SplMinHeap ≫
  • PHP Manual
  • SplMaxHeap
  • 要素を比較し、ヒープ内の適切な位置に置く

SplMaxHeap::compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplMaxHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

説明

protected SplMaxHeap::compare(mixed $value1, mixed $value2): int

value1 と value2 を比較します。

パラメータ

value1

比較したい最初のノード。

value2

比較したい 2 番目のノード。

戻り値

比較結果を返します。value1 が value2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の値を持つ複数の要素をヒープ内に保持することはおすすめしません。 そうすると、ヒープ内の相対位置がはっきりしなくなってしまいます。


SplMinHeap クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplMinHeap クラスは、ヒープの主要な機能を提供し、最小値を先頭に保ちます。

クラス概要

class SplMinHeap extends SplHeap {
/* メソッド */
protected compare(mixed $value1, mixed $value2): int
/* 継承したメソッド */
protected SplHeap::compare(mixed $value1, mixed $value2): int
public SplHeap::count(): int
public SplHeap::current(): mixed
public SplHeap::extract(): mixed
public SplHeap::insert(mixed $value): true
public SplHeap::isCorrupted(): bool
public SplHeap::isEmpty(): bool
public SplHeap::key(): int
public SplHeap::next(): void
public SplHeap::recoverFromCorruption(): bool
public SplHeap::rewind(): void
public SplHeap::top(): mixed
public SplHeap::valid(): bool
}

目次

  • SplMinHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く


要素を比較し、ヒープ内の適切な位置に置く

  • ≪ SplMinHeap
  • SplPriorityQueue ≫
  • PHP Manual
  • SplMinHeap
  • 要素を比較し、ヒープ内の適切な位置に置く

SplMinHeap::compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplMinHeap::compare — 要素を比較し、ヒープ内の適切な位置に置く

説明

protected SplMinHeap::compare(mixed $value1, mixed $value2): int

value1 と value2 を比較します。

パラメータ

value1

比較したい最初のノード。

value2

比較したい 2 番目のノード。

戻り値

比較結果を返します。value1 が value2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の値を持つ複数の要素をヒープ内に保持することはおすすめしません。 そうすると、ヒープ内の相対位置がはっきりしなくなってしまいます。


SplPriorityQueue クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplPriorityQueue クラスは、優先順位つきキューの主要な機能を提供します。 最大ヒープを使用して実装しています。

注意: 優先度が等しい要素の順番は 未定義 です。 優先度が等しい要素の順序は、挿入された順序と異なるかもしれません。

クラス概要

class SplPriorityQueue implements Iterator, Countable {
/* 定数 */
public const int EXTR_BOTH;
public const int EXTR_PRIORITY;
public const int EXTR_DATA;
/* メソッド */
public compare(mixed $priority1, mixed $priority2): int
public count(): int
public current(): mixed
public extract(): mixed
public getExtractFlags(): int
public insert(mixed $value, mixed $priority): true
public isCorrupted(): bool
public isEmpty(): bool
public key(): int
public next(): void
public recoverFromCorruption(): bool
public rewind(): void
public setExtractFlags(int $flags): int
public top(): mixed
public valid(): bool
}

定義済み定数

SplPriorityQueue::EXTR_BOTH

SplPriorityQueue::EXTR_PRIORITY

SplPriorityQueue::EXTR_DATA

目次

  • SplPriorityQueue::compare — 要素の優先順位を比較し、ヒープ内の適切な位置に置く
  • SplPriorityQueue::count — キュー内の要素数を数える
  • SplPriorityQueue::current — イテレータが指す現在のノードを返す
  • SplPriorityQueue::extract — ヒープの先頭からノードを取り出す
  • SplPriorityQueue::getExtractFlags — 展開する時のフラグを取得する
  • SplPriorityQueue::insert — キューに要素を挿入する
  • SplPriorityQueue::isCorrupted — 優先度付きキューが壊れているかを調べる
  • SplPriorityQueue::isEmpty — キューが空かどうかを調べる
  • SplPriorityQueue::key — 現在のノードのインデックスを返す
  • SplPriorityQueue::next — 次のノードに移動する
  • SplPriorityQueue::recoverFromCorruption — 破壊されたキューを復旧し、それ以降の操作をできるようにする
  • SplPriorityQueue::rewind — イテレータを先頭に巻き戻す (何もしない)
  • SplPriorityQueue::setExtractFlags — 取り出しモードを設定する
  • SplPriorityQueue::top — キューの先頭のノードを取り出す
  • SplPriorityQueue::valid — キューにまだノードがあるかどうかを調べる


要素の優先順位を比較し、ヒープ内の適切な位置に置く

  • ≪ SplPriorityQueue
  • SplPriorityQueue::count ≫
  • PHP Manual
  • SplPriorityQueue
  • 要素の優先順位を比較し、ヒープ内の適切な位置に置く

SplPriorityQueue::compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::compare — 要素の優先順位を比較し、ヒープ内の適切な位置に置く

説明

public SplPriorityQueue::compare(mixed $priority1, mixed $priority2): int

priority1 と priority2 を比較します。

パラメータ

priority1

比較したい最初のノードの優先順位。

priority2

比較したい 2 番目のノードの優先順位。

戻り値

比較結果を返します。priority1 が priority2 より大きい場合は正の整数値、等しい場合は 0、 小さい場合は負の整数値となります。

注意:

同一の優先順位の要素が複数存在する場合は、 キューから取り出す際の順序が不定となります。


キュー内の要素数を数える

  • ≪ SplPriorityQueue::compare
  • SplPriorityQueue::current ≫
  • PHP Manual
  • SplPriorityQueue
  • キュー内の要素数を数える

SplPriorityQueue::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::count — キュー内の要素数を数える

説明

public SplPriorityQueue::count(): int

パラメータ

この関数にはパラメータはありません。

戻り値

キュー内の要素数を返します。


イテレータが指す現在のノードを返す

  • ≪ SplPriorityQueue::count
  • SplPriorityQueue::extract ≫
  • PHP Manual
  • SplPriorityQueue
  • イテレータが指す現在のノードを返す

SplPriorityQueue::current

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::current — イテレータが指す現在のノードを返す

説明

public SplPriorityQueue::current(): mixed

現在のノードを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードの値あるいは優先順位 (あるいはその両方) を、抽出フラグの設定に応じて返します。


ヒープの先頭からノードを取り出す

  • ≪ SplPriorityQueue::current
  • SplPriorityQueue::getExtractFlags ≫
  • PHP Manual
  • SplPriorityQueue
  • ヒープの先頭からノードを取り出す

SplPriorityQueue::extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::extract — ヒープの先頭からノードを取り出す

説明

public SplPriorityQueue::extract(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

取り出したノードの値あるいは優先順位 (あるいはその両方) を、抽出フラグの設定に応じて返します。


展開する時のフラグを取得する

  • ≪ SplPriorityQueue::extract
  • SplPriorityQueue::insert ≫
  • PHP Manual
  • SplPriorityQueue
  • 展開する時のフラグを取得する

SplPriorityQueue::getExtractFlags

(PHP 7, PHP 8)

SplPriorityQueue::getExtractFlags — 展開する時のフラグを取得する

説明

public SplPriorityQueue::getExtractFlags(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

展開時のフラグを返します。


キューに要素を挿入する

  • ≪ SplPriorityQueue::getExtractFlags
  • SplPriorityQueue::isCorrupted ≫
  • PHP Manual
  • SplPriorityQueue
  • キューに要素を挿入する

SplPriorityQueue::insert

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::insert — キューに要素を挿入する

説明

public SplPriorityQueue::insert(mixed $value, mixed $priority): true

value を優先順位 priority でキューに挿入します。

パラメータ

value

挿入する値。

priority

関連づける優先順位。

戻り値

常に true を返します。


優先度付きキューが壊れているかを調べる

  • ≪ SplPriorityQueue::insert
  • SplPriorityQueue::isEmpty ≫
  • PHP Manual
  • SplPriorityQueue
  • 優先度付きキューが壊れているかを調べる

SplPriorityQueue::isCorrupted

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::isCorrupted — 優先度付きキューが壊れているかを調べる

説明

public SplPriorityQueue::isCorrupted(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

優先度付きキューが壊れていたら true を、そうでなければ false を返します。


キューが空かどうかを調べる

  • ≪ SplPriorityQueue::isCorrupted
  • SplPriorityQueue::key ≫
  • PHP Manual
  • SplPriorityQueue
  • キューが空かどうかを調べる

SplPriorityQueue::isEmpty

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::isEmpty — キューが空かどうかを調べる

説明

public SplPriorityQueue::isEmpty(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

キューが空かどうかを返します。


現在のノードのインデックスを返す

  • ≪ SplPriorityQueue::isEmpty
  • SplPriorityQueue::next ≫
  • PHP Manual
  • SplPriorityQueue
  • 現在のノードのインデックスを返す

SplPriorityQueue::key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::key — 現在のノードのインデックスを返す

説明

public SplPriorityQueue::key(): int

この関数は、現在のノードのインデックスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードのインデックスを返します。


次のノードに移動する

  • ≪ SplPriorityQueue::key
  • SplPriorityQueue::recoverFromCorruption ≫
  • PHP Manual
  • SplPriorityQueue
  • 次のノードに移動する

SplPriorityQueue::next

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::next — 次のノードに移動する

説明

public SplPriorityQueue::next(): void

キューから先頭のノードを取り出します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


破壊されたキューを復旧し、それ以降の操作をできるようにする

  • ≪ SplPriorityQueue::next
  • SplPriorityQueue::rewind ≫
  • PHP Manual
  • SplPriorityQueue
  • 破壊されたキューを復旧し、それ以降の操作をできるようにする

SplPriorityQueue::recoverFromCorruption

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::recoverFromCorruption — 破壊されたキューを復旧し、それ以降の操作をできるようにする

説明

public SplPriorityQueue::recoverFromCorruption(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。


イテレータを先頭に巻き戻す (何もしない)

  • ≪ SplPriorityQueue::recoverFromCorruption
  • SplPriorityQueue::setExtractFlags ≫
  • PHP Manual
  • SplPriorityQueue
  • イテレータを先頭に巻き戻す (何もしない)

SplPriorityQueue::rewind

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::rewind — イテレータを先頭に巻き戻す (何もしない)

説明

public SplPriorityQueue::rewind(): void

これは、イテレータを先頭に巻き戻します。ヒープの場合は何もしません。 というのもイテレータは仮想的なものであり、 実際はヒープの先頭から動くことがないからです。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


取り出しモードを設定する

  • ≪ SplPriorityQueue::rewind
  • SplPriorityQueue::top ≫
  • PHP Manual
  • SplPriorityQueue
  • 取り出しモードを設定する

SplPriorityQueue::setExtractFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::setExtractFlags — 取り出しモードを設定する

説明

public SplPriorityQueue::setExtractFlags(int $flags): int

パラメータ

flags

何を取り出すのかを SplPriorityQueue::current()、
SplPriorityQueue::top() および
SplPriorityQueue::extract() で指定します。

  • SplPriorityQueue::EXTR_DATA (0x00000001): データを取り出す
  • SplPriorityQueue::EXTR_PRIORITY (0x00000002): 優先順位を取り出す
  • SplPriorityQueue::EXTR_BOTH (0x00000003): 両方を含む配列を取り出す

デフォルトのモードは SplPriorityQueue::EXTR_DATA です。

戻り値

取り出す際のフラグを返します。


キューの先頭のノードを取り出す

  • ≪ SplPriorityQueue::setExtractFlags
  • SplPriorityQueue::valid ≫
  • PHP Manual
  • SplPriorityQueue
  • キューの先頭のノードを取り出す

SplPriorityQueue::top

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::top — キューの先頭のノードを取り出す

説明

public SplPriorityQueue::top(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

先頭のノードの値あるいは優先順位 (あるいはその両方) を、抽出フラグの設定に応じて返します。


キューにまだノードがあるかどうかを調べる

  • ≪ SplPriorityQueue::top
  • SplFixedArray ≫
  • PHP Manual
  • SplPriorityQueue
  • キューにまだノードがあるかどうかを調べる

SplPriorityQueue::valid

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplPriorityQueue::valid — キューにまだノードがあるかどうかを調べる

説明

public SplPriorityQueue::valid(): bool

キューにまだノードがあるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

キューにまだノードが含まれる場合に true、 そうでない場合に false を返します。


SplFixedArray クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

SplFixedArray クラスは配列の主要な機能を提供します。 SplFixedArray と通常の PHP の配列との主な違いは、 SplFixedArray は手動でリサイズしなければならないことと、 整数値で指定した範囲内の添字しか使用できないところです。 これにより、標準の array よりメモリ消費が少なくて済みます。

クラス概要

class SplFixedArray implements IteratorAggregate, ArrayAccess, Countable, JsonSerializable {
/* メソッド */
public __construct(int $size = 0)
public count(): int
public current(): mixed
public static fromArray(array $array, bool $preserveKeys = true): SplFixedArray
public getIterator(): Iterator
public getSize(): int
public jsonSerialize(): array
public key(): int
public next(): void
public offsetExists(int $index): bool
public offsetGet(int $index): mixed
public offsetSet(int $index, mixed $value): void
public offsetUnset(int $index): void
public rewind(): void
public __serialize(): array
public setSize(int $size): bool
public toArray(): array
public __unserialize(array $data): void
public valid(): bool
public __wakeup(): void
}

変更履歴

バージョン | 説明
8.2.0 | マジックメソッド SplFixedArray::__serialize() と SplFixedArray::__unserialize() が、SplFixedArray に追加されました。
8.1.0 | SplFixedArray は、 JsonSerializable を実装するようになりました。
8.0.0 | SplFixedArray は、 IteratorAggregate を実装するようになりました。 これより前のバージョンでは、 Iterator を実装していました。

例

例1 SplFixedArray の使用例

<?php
// 固定長の配列を初期化します
$array = new SplFixedArray(5);

$array[1] = 2;
$array[4] = "foo";

var_dump($array[0]); // NULL
var_dump($array[1]); // int(2)

var_dump($array["4"]); // string(3) "foo"

// 配列のサイズを 10 に拡大します
$array->setSize(10);

$array[9] = "asdf";

// 配列のサイズを 2 に縮めます
$array->setSize(2);

// 以下は RuntimeException: Index invalid or out of range となります
try {
var_dump($array["non-numeric"]);
} catch(RuntimeException $re) {
echo "RuntimeException: ".$re->getMessage()."\n";
}

try {
var_dump($array[-1]);
} catch(RuntimeException $re) {
echo "RuntimeException: ".$re->getMessage()."\n";
}

try {
var_dump($array[5]);
} catch(RuntimeException $re) {
echo "RuntimeException: ".$re->getMessage()."\n";
}
?>

上の例の出力は以下となります。

NULL
int(2)
string(3) "foo"
RuntimeException: Index invalid or out of range
RuntimeException: Index invalid or out of range
RuntimeException: Index invalid or out of range

目次

  • SplFixedArray::__construct — 新しい固定長配列を作成する
  • SplFixedArray::count — 配列のサイズを返す
  • SplFixedArray::current — 現在の配列の要素を返す
  • SplFixedArray::fromArray — PHP の配列を SplFixedArray インスタンスにインポートする
  • SplFixedArray::getIterator — 配列を走査するためのイテレータを取得する
  • SplFixedArray::getSize — 配列のサイズを取得する
  • SplFixedArray::jsonSerialize — JSON に変換可能な値の表現を返す
  • SplFixedArray::key — 現在の配列の添字を返す
  • SplFixedArray::next — 次のエントリに進む
  • SplFixedArray::offsetExists — 指定した添字が存在するかどうかを返す
  • SplFixedArray::offsetGet — 指定した添字の値を返す
  • SplFixedArray::offsetSet — 指定した添字の新しい値を設定する
  • SplFixedArray::offsetUnset — 指定した添字の値を消去する
  • SplFixedArray::rewind — イテレータを先頭に巻き戻す
  • SplFixedArray::__serialize — SplFixedArray オブジェクトをシリアライズする
  • SplFixedArray::setSize — 配列のサイズを変更する
  • SplFixedArray::toArray — 固定長配列から PHP の配列を返す
  • SplFixedArray::__unserialize — data パラメータを SplFixedArray オブジェクトに復元する
  • SplFixedArray::valid — 配列にまだ要素があるかどうかを調べる
  • SplFixedArray::__wakeup — アンシリアライズ後に配列を再初期化する


新しい固定長配列を作成する

  • ≪ SplFixedArray
  • SplFixedArray::count ≫
  • PHP Manual
  • SplFixedArray
  • 新しい固定長配列を作成する

SplFixedArray::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::__construct — 新しい固定長配列を作成する

説明

public SplFixedArray::__construct(int $size = 0)

新しい固定長配列を作成します。要素の数は size と等しく、値はすべて null となります。

パラメータ

size

固定長配列のサイズ。 0 から PHP_INT_MAX までの数を指定します。

エラー / 例外

size が負の数である場合に ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | size が負の数である場合に ValueError をスローするようになりました。 これより前のバージョンでは、 InvalidArgumentException をスローしていました。

例

例1 SplFixedArray::__construct() の例

<?php
$array = new SplFixedArray(5);

$array[1] = 2;
$array[4] = "foo";

foreach($array as $v) {
var_dump($v);
}
?>

上の例の出力は以下となります。

NULL
int(2)
NULL
NULL
string(3) "foo"


配列のサイズを返す

  • ≪ SplFixedArray::__construct
  • SplFixedArray::current ≫
  • PHP Manual
  • SplFixedArray
  • 配列のサイズを返す

SplFixedArray::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::count — 配列のサイズを返す

説明

public SplFixedArray::count(): int

配列のサイズを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

配列のサイズを返します。

例

例1 SplFixedArray::count() の例

<?php
$array = new SplFixedArray(5);
echo $array->count() . "\n";
echo count($array) . "\n";
?>

上の例の出力は以下となります。

5
5

注意

注意:

このメソッドは、機能的には SplFixedArray::getSize() と同じです。

注意:

要素の数は常に設定されているサイズと等しくなります。すべての要素の値が最初に null で初期化されるからです。

参考

  • SplFixedArray::getSize() - 配列のサイズを取得する


現在の配列の要素を返す

  • ≪ SplFixedArray::count
  • SplFixedArray::fromArray ≫
  • PHP Manual
  • SplFixedArray
  • 現在の配列の要素を返す

SplFixedArray::current

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::current — 現在の配列の要素を返す

説明

public SplFixedArray::current(): mixed

現在の配列の要素を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の値を返します。

エラー / 例外

内部の配列ポインタが無効なインデックスを指していたり、範囲外にあったりする場合に RuntimeException をスローします。


PHP の配列を SplFixedArray インスタンスにインポートする

  • ≪ SplFixedArray::current
  • SplFixedArray::getIterator ≫
  • PHP Manual
  • SplFixedArray
  • PHP の配列を SplFixedArray インスタンスにインポートする

SplFixedArray::fromArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::fromArray — PHP の配列を SplFixedArray インスタンスにインポートする

説明

public static SplFixedArray::fromArray(array $array, bool $preserveKeys = true): SplFixedArray

PHP の配列 array を、新しい SplFixedArray インスタンスにインポートします。

パラメータ

array

インポートする配列。

preserveKeys

元の配列で使っている数値添字を保存しようと試みる。

戻り値

配列の中身を含む SplFixedArray のインスタンスを返します。

例

例1 SplFixedArray::fromArray() の例

<?php
$fa = SplFixedArray::fromArray(array(1 => 1, 0 => 2, 3 => 3));

var_dump($fa);

$fa = SplFixedArray::fromArray(array(1 => 1, 0 => 2, 3 => 3), false);

var_dump($fa);
?>

上の例の出力は以下となります。

object(SplFixedArray)#1 (4) {
  [0]=>
  int(2)
  [1]=>
  int(1)
  [2]=>
  NULL
  [3]=>
  int(3)
}
object(SplFixedArray)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


配列を走査するためのイテレータを取得する

  • ≪ SplFixedArray::fromArray
  • SplFixedArray::getSize ≫
  • PHP Manual
  • SplFixedArray
  • 配列を走査するためのイテレータを取得する

SplFixedArray::getIterator

(PHP 8)

SplFixedArray::getIterator — 配列を走査するためのイテレータを取得する

説明

public SplFixedArray::getIterator(): Iterator

配列を走査するためのイテレータを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

配列を走査するための Iterator を実装した、オブジェクトのインスタンスを返します。


配列のサイズを取得する

  • ≪ SplFixedArray::getIterator
  • SplFixedArray::jsonSerialize ≫
  • PHP Manual
  • SplFixedArray
  • 配列のサイズを取得する

SplFixedArray::getSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::getSize — 配列のサイズを取得する

説明

public SplFixedArray::getSize(): int

配列のサイズを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

配列のサイズを int で返します。

例

例1 SplFixedArray::getSize() の例

<?php
$array = new SplFixedArray(5);
echo $array->getSize()."\n";
$array->setSize(10);
echo $array->getSize()."\n";
?>

上の例の出力は以下となります。

5
10

注意

注意:

このメソッドは、機能的には SplFixedArray::count() と同じです。

参考

  • SplFixedArray::count() - 配列のサイズを返す


JSON に変換可能な値の表現を返す

  • ≪ SplFixedArray::getSize
  • SplFixedArray::key ≫
  • PHP Manual
  • SplFixedArray
  • JSON に変換可能な値の表現を返す

SplFixedArray::jsonSerialize

(PHP 8 >= 8.1.0)

SplFixedArray::jsonSerialize — JSON に変換可能な値の表現を返す

説明

public SplFixedArray::jsonSerialize(): array

json_encode() でネイティブにシリアライズ可能な値に、 配列をシリアライズします。

パラメータ

この関数にはパラメータはありません。

戻り値

json_encode() でシリアライズ可能な配列データを返します。 これは リソース 以外のあらゆる型の値になります。


現在の配列の添字を返す

  • ≪ SplFixedArray::jsonSerialize
  • SplFixedArray::next ≫
  • PHP Manual
  • SplFixedArray
  • 現在の配列の添字を返す

SplFixedArray::key

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::key — 現在の配列の添字を返す

説明

public SplFixedArray::key(): int

現在の配列の添字を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の配列の添字を返します。


次のエントリに進む

  • ≪ SplFixedArray::key
  • SplFixedArray::offsetExists ≫
  • PHP Manual
  • SplFixedArray
  • 次のエントリに進む

SplFixedArray::next

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::next — 次のエントリに進む

説明

public SplFixedArray::next(): void

イテレータを、次の配列の要素に進めます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


指定した添字が存在するかどうかを返す

  • ≪ SplFixedArray::next
  • SplFixedArray::offsetGet ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字が存在するかどうかを返す

SplFixedArray::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::offsetExists — 指定した添字が存在するかどうかを返す

説明

public SplFixedArray::offsetExists(int $index): bool

index で指定した添字が存在するかどうかを返します。

パラメータ

index

調べたい添字。

戻り値

指定した添字が存在する場合に true、それ以外の場合に false を返します。


指定した添字の値を返す

  • ≪ SplFixedArray::offsetExists
  • SplFixedArray::offsetSet ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字の値を返す

SplFixedArray::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::offsetGet — 指定した添字の値を返す

説明

public SplFixedArray::offsetGet(int $index): mixed

index で指定した添字の値を返します。

パラメータ

index

値を取得したい添字。

戻り値

index で指定した添字の値を返します。

エラー / 例外

index が配列で定義されているサイズの範囲外の場合や index を数値として解釈できない場合に RuntimeException をスローします。


指定した添字の新しい値を設定する

  • ≪ SplFixedArray::offsetGet
  • SplFixedArray::offsetUnset ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字の新しい値を設定する

SplFixedArray::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::offsetSet — 指定した添字の新しい値を設定する

説明

public SplFixedArray::offsetSet(int $index, mixed $value): void

index で指定した添字の値を value に設定します。

パラメータ

index

設定したい添字。

value

index の新しい値。

戻り値

値を返しません。

エラー / 例外

index が配列で定義されているサイズの範囲外の場合や index を数値として解釈できない場合に RuntimeException をスローします。


指定した添字の値を消去する

  • ≪ SplFixedArray::offsetSet
  • SplFixedArray::rewind ≫
  • PHP Manual
  • SplFixedArray
  • 指定した添字の値を消去する

SplFixedArray::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::offsetUnset — 指定した添字の値を消去する

説明

public SplFixedArray::offsetUnset(int $index): void

指定した添字の値を消去します。

パラメータ

index

消去したい添字。

戻り値

値を返しません。

エラー / 例外

index が配列で定義されているサイズの範囲外の場合や index を数値として解釈できない場合に RuntimeException をスローします。


イテレータを先頭に巻き戻す

  • ≪ SplFixedArray::offsetUnset
  • SplFixedArray::__serialize ≫
  • PHP Manual
  • SplFixedArray
  • イテレータを先頭に巻き戻す

SplFixedArray::rewind

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::rewind — イテレータを先頭に巻き戻す

説明

public SplFixedArray::rewind(): void

イテレータを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


SplFixedArray オブジェクトをシリアライズする

  • ≪ SplFixedArray::rewind
  • SplFixedArray::setSize ≫
  • PHP Manual
  • SplFixedArray
  • SplFixedArray オブジェクトをシリアライズする

SplFixedArray::__serialize

(PHP 8 >= 8.2.0)

SplFixedArray::__serialize — SplFixedArray オブジェクトをシリアライズする

説明

public SplFixedArray::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


配列のサイズを変更する

  • ≪ SplFixedArray::__serialize
  • SplFixedArray::toArray ≫
  • PHP Manual
  • SplFixedArray
  • 配列のサイズを変更する

SplFixedArray::setSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::setSize — 配列のサイズを変更する

説明

public SplFixedArray::setSize(int $size): bool

配列のサイズを、新しい値 size に変更します。 size が現在の配列のサイズより小さい場合は、 入りきらなかったそれ以降の値は破棄されます。 size が現在の配列のサイズより大きい場合は、 増えた要素の値は null となります。

パラメータ

size

新しい配列のサイズ。 0 から PHP_INT_MAX までの数を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

size が負の数である場合に InvalidArgumentException をスローします。

size を数値として解釈できない場合に E_WARNING が発生します。

例

例1 SplFixedArray::setSize() の例

<?php
$array = new SplFixedArray(5);
echo $array->getSize()."\n";
$array->setSize(10);
echo $array->getSize()."\n";
?>

上の例の出力は以下となります。

5
10


固定長配列から PHP の配列を返す

  • ≪ SplFixedArray::setSize
  • SplFixedArray::__unserialize ≫
  • PHP Manual
  • SplFixedArray
  • 固定長配列から PHP の配列を返す

SplFixedArray::toArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplFixedArray::toArray — 固定長配列から PHP の配列を返す

説明

public SplFixedArray::toArray(): array

固定長配列から PHP の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

固定長配列と同じ内容の PHP の配列を返します。

例

例1 SplFixedArray::toArray() の例

<?php
$fa = new SplFixedArray(3);
$fa[0] = 0;
$fa[2] = 2;
var_dump($fa->toArray());
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(0)
  [1]=>
  NULL
  [2]=>
  int(2)
}


data パラメータを SplFixedArray オブジェクトに復元する

  • ≪ SplFixedArray::toArray
  • SplFixedArray::valid ≫
  • PHP Manual
  • SplFixedArray
  • data パラメータを SplFixedArray オブジェクトに復元する

SplFixedArray::__unserialize

(PHP 8 >= 8.2.0)

SplFixedArray::__unserialize — data パラメータを SplFixedArray オブジェクトに復元する

説明

public SplFixedArray::__unserialize(array $data): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

アンシリアライズする値

戻り値

値を返しません。


配列にまだ要素があるかどうかを調べる

  • ≪ SplFixedArray::__unserialize
  • SplFixedArray::__wakeup ≫
  • PHP Manual
  • SplFixedArray
  • 配列にまだ要素があるかどうかを調べる

SplFixedArray::valid

(PHP 5 >= 5.3.0, PHP 7)

SplFixedArray::valid — 配列にまだ要素があるかどうかを調べる

説明

public SplFixedArray::valid(): bool

配列にまだ要素があるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

配列にまだ要素がある場合に true、それ以外の場合に false を返します。


アンシリアライズ後に配列を再初期化する

  • ≪ SplFixedArray::valid
  • SplObjectStorage ≫
  • PHP Manual
  • SplFixedArray
  • アンシリアライズ後に配列を再初期化する

SplFixedArray::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

SplFixedArray::__wakeup — アンシリアライズ後に配列を再初期化する

説明

public SplFixedArray::__wakeup(): void

アンシリアライズ後に配列を再初期化します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


SplObjectStorage クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

SplObjectStorage クラスは、オブジェクトをデータに対応させたり、 データを渡さずオブジェクトセットとして使用したりします。 これらはどちらも、オブジェクトを一意に特定したい場合に便利です。

クラス概要

class SplObjectStorage implements Countable, Iterator, Serializable, ArrayAccess {
/* メソッド */
public addAll(SplObjectStorage $storage): int
public attach(object $object, mixed $info = null): void
public contains(object $object): bool
public count(int $mode = COUNT_NORMAL): int
public current(): object
public detach(object $object): void
public getHash(object $object): string
public getInfo(): mixed
public key(): int
public next(): void
public offsetExists(object $object): bool
public offsetGet(object $object): mixed
public offsetSet(object $object, mixed $info = null): void
public offsetUnset(object $object): void
public removeAll(SplObjectStorage $storage): int
public removeAllExcept(SplObjectStorage $storage): int
public rewind(): void
public serialize(): string
public setInfo(mixed $info): void
public unserialize(string $data): void
public valid(): bool
}

例

例1 SplObjectStorage をセットとして使用

<?php
// オブジェクトセット
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;
$o3 = new stdClass;

$s->attach($o1);
$s->attach($o2);

var_dump($s->contains($o1));
var_dump($s->contains($o2));
var_dump($s->contains($o3));

$s->detach($o2);

var_dump($s->contains($o1));
var_dump($s->contains($o2));
var_dump($s->contains($o3));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(false)
bool(false)

例2 SplObjectStorage をマップとして使用

<?php
// オブジェクトとデータを対応させます
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;
$o3 = new stdClass;

$s[$o1] = "data for object 1";
$s[$o2] = array(1,2,3);

if (isset($s[$o2])) {
var_dump($s[$o2]);
}
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

目次

  • SplObjectStorage::addAll — 別のストレージからすべてのオブジェクトを追加する
  • SplObjectStorage::attach — オブジェクトをストレージに追加する
  • SplObjectStorage::contains — ストレージに特定のオブジェクトが含まれるかどうかを調べる
  • SplObjectStorage::count — ストレージ内のオブジェクトの数を返す
  • SplObjectStorage::current — 現在のストレージの要素を返す
  • SplObjectStorage::detach — オブジェクトをストレージから取り除く
  • SplObjectStorage::getHash — 中に含むオブジェクトの一意な識別子を算出する
  • SplObjectStorage::getInfo — イテレータの現在のエントリに関連づけられたデータを返す
  • SplObjectStorage::key — イテレータの現在位置を返す
  • SplObjectStorage::next — 次のエントリに移動する
  • SplObjectStorage::offsetExists — オブジェクトがストレージ内に存在するかどうかを調べる
  • SplObjectStorage::offsetGet — オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetSet — ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetUnset — ストレージからオブジェクトを取り除く
  • SplObjectStorage::removeAll — 別のストレージに含まれているオブジェクトを現在のストレージから取り除く
  • SplObjectStorage::removeAllExcept — 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く
  • SplObjectStorage::rewind — イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::serialize — ストレージをシリアライズする
  • SplObjectStorage::setInfo — イテレータの現在のエントリに関連づけるデータを設定する
  • SplObjectStorage::unserialize — ストレージの文字列表現をアンシリアライズする
  • SplObjectStorage::valid — イテレータの現在のエントリが有効かどうかを返す


別のストレージからすべてのオブジェクトを追加する

  • ≪ SplObjectStorage
  • SplObjectStorage::attach ≫
  • PHP Manual
  • SplObjectStorage
  • 別のストレージからすべてのオブジェクトを追加する

SplObjectStorage::addAll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::addAll — 別のストレージからすべてのオブジェクトを追加する

説明

public SplObjectStorage::addAll(SplObjectStorage $storage): int

別のストレージにあるすべてのオブジェクトとデータのペアを、 現在のストレージに追加します。

パラメータ

storage

インポートしたいストレージ。

戻り値

ストレージにあるオブジェクトの数を返します。

例

例1 SplObjectStorage::addAll() の例

<?php
$o = new stdClass;
$a = new SplObjectStorage();
$a[$o] = "hello";

$b = new SplObjectStorage();
$b->addAll($a);
echo $b[$o]."\n";
?>

上の例の出力は、 たとえば以下のようになります。

hello

参考

  • SplObjectStorage::removeAll() - 別のストレージに含まれているオブジェクトを現在のストレージから取り除く


オブジェクトをストレージに追加する

  • ≪ SplObjectStorage::addAll
  • SplObjectStorage::contains ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトをストレージに追加する

SplObjectStorage::attach

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::attach — オブジェクトをストレージに追加する

説明

public SplObjectStorage::attach(object $object, mixed $info = null): void

オブジェクトをストレージに追加し、 オプションでそれを何らかのデータに関連づけます。

パラメータ

object

追加したいオブジェクト。

info

object に関連づけるデータ。

戻り値

値を返しません。

例

例1 SplObjectStorage::attach() の例

<?php
$o1 = new stdClass;
$o2 = new stdClass;
$s = new SplObjectStorage();
$s->attach($o1); // $s[$o1] = NULL; と同等
$s->attach($o2, "hello"); // $s[$o2] = "hello"; と同等

var_dump($s[$o1]);
var_dump($s[$o2]);

?>

上の例の出力は、 たとえば以下のようになります。

NULL
string(5) "hello"

参考

  • SplObjectStorage::detach() - オブジェクトをストレージから取り除く
  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける


ストレージに特定のオブジェクトが含まれるかどうかを調べる

  • ≪ SplObjectStorage::attach
  • SplObjectStorage::count ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージに特定のオブジェクトが含まれるかどうかを調べる

SplObjectStorage::contains

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::contains — ストレージに特定のオブジェクトが含まれるかどうかを調べる

説明

public SplObjectStorage::contains(object $object): bool

指定したオブジェクトがストレージに含まれるかどうかを調べます。

パラメータ

object

探したいオブジェクト。

戻り値

object がストレージに存在する場合に true、それ以外の場合に false を返します。

例

例1 SplObjectStorage::contains() の例

<?php
$o1 = new stdClass;
$o2 = new stdClass;

$s = new SplObjectStorage();

$s[$o1] = "hello";
var_dump($s->contains($o1));
var_dump($s->contains($o2));
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる


ストレージ内のオブジェクトの数を返す

  • ≪ SplObjectStorage::contains
  • SplObjectStorage::current ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージ内のオブジェクトの数を返す

SplObjectStorage::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::count — ストレージ内のオブジェクトの数を返す

説明

public SplObjectStorage::count(int $mode = COUNT_NORMAL): int

ストレージ内のオブジェクトの数を数えます。

パラメータ

mode

オプションの mode 引数が COUNT_RECURSIVE (または 1) に設定された場合、 SplObjectStorage::count() は再帰的にストレージを操作して数えます。

戻り値

ストレージ内のオブジェクトの数を返します。

例

例1 SplObjectStorage::count() の例

<?php
$s = new SplObjectStorage();
$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1);
$s->attach($o2);
$s->attach($o1);
var_dump($s->count());
var_dump(count($s));
?>

上の例の出力は、 たとえば以下のようになります。

int(2)
int(2)

参考

  • SplObjectStorage::attach() - オブジェクトをストレージに追加する
  • SplObjectStorage::detach() - オブジェクトをストレージから取り除く


現在のストレージの要素を返す

  • ≪ SplObjectStorage::count
  • SplObjectStorage::detach ≫
  • PHP Manual
  • SplObjectStorage
  • 現在のストレージの要素を返す

SplObjectStorage::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::current — 現在のストレージの要素を返す

説明

public SplObjectStorage::current(): object

現在のストレージの要素を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のイテレータの位置にあるオブジェクトを返します。

変更履歴

バージョン | 説明
8.1.0 | SplObjectStorage::current() は、 現在の位置が不正な場合、 Error をスローするようになりました。 これより前のバージョンでは、 false を返していました。

例

例1 SplObjectStorage::current() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
$index = $s->key();
$object = $s->current(); // current($s) と同等
$data = $s->getInfo();

var_dump($object);
var_dump($data);
$s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (0) {
}
string(2) "d1"
object(stdClass)#3 (0) {
}
string(2) "d2"

参考

  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::key() - イテレータの現在位置を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す
  • SplObjectStorage::getInfo() - イテレータの現在のエントリに関連づけられたデータを返す


オブジェクトをストレージから取り除く

  • ≪ SplObjectStorage::current
  • SplObjectStorage::getHash ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトをストレージから取り除く

SplObjectStorage::detach

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::detach — オブジェクトをストレージから取り除く

説明

public SplObjectStorage::detach(object $object): void

オブジェクトをストレージから取り除きます。

パラメータ

object

取り除きたいオブジェクト。

戻り値

値を返しません。

例

例1 SplObjectStorage::detach() の例

<?php
$o = new stdClass;
$s = new SplObjectStorage();
$s->attach($o);
var_dump(count($s));
$s->detach($o);
var_dump(count($s));
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(0)

参考

  • SplObjectStorage::attach() - オブジェクトをストレージに追加する
  • SplObjectStorage::removeAll() - 別のストレージに含まれているオブジェクトを現在のストレージから取り除く


中に含むオブジェクトの一意な識別子を算出する

  • ≪ SplObjectStorage::detach
  • SplObjectStorage::getInfo ≫
  • PHP Manual
  • SplObjectStorage
  • 中に含むオブジェクトの一意な識別子を算出する

SplObjectStorage::getHash

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SplObjectStorage::getHash — 中に含むオブジェクトの一意な識別子を算出する

説明

public SplObjectStorage::getHash(object $object): string

このメソッドは、SplObjectStorage オブジェクトに追加されたオブジェクトの識別子を算出します。

SplObjectStorage の実装では、 spl_object_hash() と同じ値を返します。

ストレージオブジェクトには、同じ識別子のオブジェクトを複数格納することはできません。 それを利用して、セット (一意な値のコレクション) を実装するのにも使えます。 オブジェクトが一意であるという性質は、この関数の返す値が一意であるということで実現できます。

パラメータ

object

識別子を算出したいオブジェクト。

戻り値

算出した識別子を文字列で返します。

エラー / 例外

返された値が文字列でない場合に RuntimeException をスローします。

例

例1 SplObjectStorage::getHash() の例

<?php
class OneSpecimenPerClassStorage extends SplObjectStorage {
public function getHash($o) {
return get_class($o);
}
}
class A {}

$s = new OneSpecimenPerClassStorage;
$o1 = new stdClass;
$o2 = new stdClass;
$o3 = new A;

$s[$o1] = 1;
// $o2 は $o1 に等しいとみなされ、値が置き換えられます
$s[$o2] = 2;
$s[$o3] = 3;

// これらは先ほどのオブジェクトと等しいとみなされ、
// さきほど格納した値にアクセスできるようになります
$p1 = new stdClass;
$p2 = new A;
echo $s[$p1], "\n";
echo $s[$p2], "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2
3

参考

  • spl_object_hash() - 指定したオブジェクトのハッシュ ID を返す


イテレータの現在のエントリに関連づけられたデータを返す

  • ≪ SplObjectStorage::getHash
  • SplObjectStorage::key ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在のエントリに関連づけられたデータを返す

SplObjectStorage::getInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::getInfo — イテレータの現在のエントリに関連づけられたデータを返す

説明

public SplObjectStorage::getInfo(): mixed

イテレータの現在の位置が指すオブジェクトに関連づけられたデータあるいは情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータの現在の位置に関連づけられたデータを返します。

例

例1 SplObjectStorage::getInfo() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
$index = $s->key();
$object = $s->current(); // current($s) と同等
$data = $s->getInfo();

var_dump($object);
var_dump($data);
$s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#2 (0) {
}
string(2) "d1"
object(stdClass)#3 (0) {
}
string(2) "d2"

参考

  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::key() - イテレータの現在位置を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す
  • SplObjectStorage::setInfo() - イテレータの現在のエントリに関連づけるデータを設定する


イテレータの現在位置を返す

  • ≪ SplObjectStorage::getInfo
  • SplObjectStorage::next ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在位置を返す

SplObjectStorage::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::key — イテレータの現在位置を返す

説明

public SplObjectStorage::key(): int

イテレータの現在位置を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータの現在位置に対応するインデックスを返します。

例

例1 SplObjectStorage::key() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
$index = $s->key();
$object = $s->current(); // current($s) と同等

var_dump($index);
var_dump($object);
$s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
object(stdClass)#2 (0) {
}
int(1)
object(stdClass)#3 (0) {
}

参考

  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す


次のエントリに移動する

  • ≪ SplObjectStorage::key
  • SplObjectStorage::offsetExists ≫
  • PHP Manual
  • SplObjectStorage
  • 次のエントリに移動する

SplObjectStorage::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::next — 次のエントリに移動する

説明

public SplObjectStorage::next(): void

イテレータを、ストレージ内の次のオブジェクトに移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 SplObjectStorage::next() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
$index = $s->key();
$object = $s->current(); // current($s) と同等

var_dump($index);
var_dump($object);
$s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
object(stdClass)#2 (0) {
}
int(1)
object(stdClass)#3 (0) {
}

参考

  • SPLObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す


オブジェクトがストレージ内に存在するかどうかを調べる

  • ≪ SplObjectStorage::next
  • SplObjectStorage::offsetGet ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトがストレージ内に存在するかどうかを調べる

SplObjectStorage::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::offsetExists — オブジェクトがストレージ内に存在するかどうかを調べる

説明

public SplObjectStorage::offsetExists(object $object): bool

オブジェクトがストレージ内に存在するかどうかを調べます。

注意:

SplObjectStorage::offsetExists() は、SplObjectStorage::contains() のエイリアスです。

パラメータ

object

探したいオブジェクト。

戻り値

object がストレージ内に存在する場合に true、 それ以外の場合に false を返します。

例

例1 SplObjectStorage::offsetExists() の例

<?php
$s = new SplObjectStorage;
$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1);

var_dump($s->offsetExists($o1)); // isset($s[$o1]) と同等
var_dump($s->offsetExists($o2)); // isset($s[$o2]) と同等
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetGet() - オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetUnset() - ストレージからオブジェクトを取り除く


オブジェクトに関連づけられたデータを返す

  • ≪ SplObjectStorage::offsetExists
  • SplObjectStorage::offsetSet ≫
  • PHP Manual
  • SplObjectStorage
  • オブジェクトに関連づけられたデータを返す

SplObjectStorage::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::offsetGet — オブジェクトに関連づけられたデータを返す

説明

public SplObjectStorage::offsetGet(object $object): mixed

ストレージ内のオブジェクトに関連づけられたデータを返します。

パラメータ

object

探したいオブジェクト。

戻り値

ストレージ内のオブジェクトに関連づけられたデータを返します。

エラー / 例外

object が見つからないときに UnexpectedValueException をスローします。

例

例1 SplObjectStorage::offsetGet() の例

<?php
$s = new SplObjectStorage;

$o1 = new stdClass;
$o2 = new stdClass;

$s[$o1] = "hello";
$s->attach($o2);

var_dump($s->offsetGet($o1)); // $s[$o1] と同等
var_dump($s->offsetGet($o2)); // $s[$o2] と同等
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "hello"
NULL

参考

  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる
  • SplObjectStorage::offsetUnset() - ストレージからオブジェクトを取り除く


ストレージ内のオブジェクトにデータを関連づける

  • ≪ SplObjectStorage::offsetGet
  • SplObjectStorage::offsetUnset ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージ内のオブジェクトにデータを関連づける

SplObjectStorage::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::offsetSet — ストレージ内のオブジェクトにデータを関連づける

説明

public SplObjectStorage::offsetSet(object $object, mixed $info = null): void

ストレージ内のオブジェクトにデータを関連づけます。

注意:

SplObjectStorage::offsetSet() は、 SplObjectStorage::attach() のエイリアスです。

パラメータ

object

データを関連づけたいオブジェクト。

info

object に関連づけるデータ。

戻り値

値を返しません。

例

例1 SplObjectStorage::offsetSet() の例

<?php
$s = new SplObjectStorage;

$o1 = new stdClass;

$s->offsetSet($o1, "hello"); // $s[$o1] = "hello"; と同等

var_dump($s[$o1]);
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "hello"

参考

  • SplObjectStorage::attach() - オブジェクトをストレージに追加する
  • SplObjectStorage::offsetGet() - オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる
  • SplObjectStorage::offsetUnset() - ストレージからオブジェクトを取り除く


ストレージからオブジェクトを取り除く

  • ≪ SplObjectStorage::offsetSet
  • SplObjectStorage::removeAll ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージからオブジェクトを取り除く

SplObjectStorage::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::offsetUnset — ストレージからオブジェクトを取り除く

説明

public SplObjectStorage::offsetUnset(object $object): void

ストレージからオブジェクトを取り除きます。

注意:

SplObjectStorage::offsetUnset() は、 SplObjectStorage::detach() のエイリアスです。

パラメータ

object

取り除きたいオブジェクト。

戻り値

値を返しません。

例

例1 SplObjectStorage::offsetUnset() の例

<?php
$o = new stdClass;
$s = new SplObjectStorage();
$s->attach($o);
var_dump(count($s));
$s->offsetUnset($o); // unset($s[$o]) と同等
var_dump(count($s));
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(0)

参考

  • SplObjectStorage::offsetGet() - オブジェクトに関連づけられたデータを返す
  • SplObjectStorage::offsetSet() - ストレージ内のオブジェクトにデータを関連づける
  • SplObjectStorage::offsetExists() - オブジェクトがストレージ内に存在するかどうかを調べる


別のストレージに含まれているオブジェクトを現在のストレージから取り除く

  • ≪ SplObjectStorage::offsetUnset
  • SplObjectStorage::removeAllExcept ≫
  • PHP Manual
  • SplObjectStorage
  • 別のストレージに含まれているオブジェクトを現在のストレージから取り除く

SplObjectStorage::removeAll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::removeAll — 別のストレージに含まれているオブジェクトを現在のストレージから取り除く

説明

public SplObjectStorage::removeAll(SplObjectStorage $storage): int

別のストレージに含まれているオブジェクトを現在のストレージから取り除きます。

パラメータ

storage

取り除きたい要素を含むストレージ。

戻り値

取り除かれた後に残ったオブジェクトの数を返します。

例

例1 SplObjectStorage::removeAll() の例

<?php
$o1 = new stdClass;
$o2 = new stdClass;
$a = new SplObjectStorage();
$a[$o1] = "foo";

$b = new SplObjectStorage();
$b[$o1] = "bar";
$b[$o2] = "gee";

var_dump(count($b));
$b->removeAll($a);
var_dump(count($b));
?>

上の例の出力は、 たとえば以下のようになります。

int(2)
int(1)

参考

  • SplObjectStorage::addAll() - 別のストレージからすべてのオブジェクトを追加する


別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く

  • ≪ SplObjectStorage::removeAll
  • SplObjectStorage::rewind ≫
  • PHP Manual
  • SplObjectStorage
  • 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く

SplObjectStorage::removeAllExcept

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SplObjectStorage::removeAllExcept — 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く

説明

public SplObjectStorage::removeAllExcept(SplObjectStorage $storage): int

別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除きます。

パラメータ

storage

現在のストレージに残しておきたい要素を含むストレージ。

戻り値

取り除かれた後に残ったオブジェクトの数を返します。

例

例1 SplObjectStorage::removeAllExcept() の例

<?php
$a = (object) 'a';
$b = (object) 'b';
$c = (object) 'c';

$foo = new SplObjectStorage;
$foo->attach($a);
$foo->attach($b);

$bar = new SplObjectStorage;
$bar->attach($b);
$bar->attach($c);

$foo->removeAllExcept($bar);
var_dump($foo->contains($a));
var_dump($foo->contains($b));
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


イテレータをストレージの最初の要素に巻き戻す

  • ≪ SplObjectStorage::removeAllExcept
  • SplObjectStorage::serialize ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータをストレージの最初の要素に巻き戻す

SplObjectStorage::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::rewind — イテレータをストレージの最初の要素に巻き戻す

説明

public SplObjectStorage::rewind(): void

イテレータをストレージの最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 SplObjectStorage::rewind() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
$index = $s->key();
$object = $s->current(); // current($s) と同等
$data = $s->getInfo();

var_dump($object);
var_dump($data);
$s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(0)

参考

  • SplObjectStorage::next() - 次のエントリに移動する


ストレージをシリアライズする

  • ≪ SplObjectStorage::rewind
  • SplObjectStorage::setInfo ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージをシリアライズする

SplObjectStorage::serialize

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

SplObjectStorage::serialize — ストレージをシリアライズする

説明

public SplObjectStorage::serialize(): string

ストレージの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ストレージの文字列表現を返します。

例

例1 SplObjectStorage::serialize() の例

<?php
$s = new SplObjectStorage;
$o = new stdClass;
$s[$o] = "data";

echo $s->serialize()."\n";
?>

上の例の出力は、 たとえば以下のようになります。

x:i:1;O:8:"stdClass":0:{},s:4:"data";;m:a:0:{}

参考

  • SplObjectStorage::unserialize() - ストレージの文字列表現をアンシリアライズする


イテレータの現在のエントリに関連づけるデータを設定する

  • ≪ SplObjectStorage::serialize
  • SplObjectStorage::unserialize ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在のエントリに関連づけるデータを設定する

SplObjectStorage::setInfo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SplObjectStorage::setInfo — イテレータの現在のエントリに関連づけるデータを設定する

説明

public SplObjectStorage::setInfo(mixed $info): void

イテレータが現在指しているオブジェクトにデータあるいは情報を関連づけます。

パラメータ

info

現在のイテレータのエントリに関連づけるデータ。

戻り値

値を返しません。

例

例1 SplObjectStorage::setInfo() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
$s->setInfo("new");
$s->next();
}
var_dump($s[$o1]);
var_dump($s[$o2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "new"
string(3) "new"

参考

  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::rewind() - イテレータをストレージの最初の要素に巻き戻す
  • SplObjectStorage::key() - イテレータの現在位置を返す
  • SplObjectStorage::next() - 次のエントリに移動する
  • SplObjectStorage::valid() - イテレータの現在のエントリが有効かどうかを返す
  • SplObjectStorage::getInfo() - イテレータの現在のエントリに関連づけられたデータを返す


ストレージの文字列表現をアンシリアライズする

  • ≪ SplObjectStorage::setInfo
  • SplObjectStorage::valid ≫
  • PHP Manual
  • SplObjectStorage
  • ストレージの文字列表現をアンシリアライズする

SplObjectStorage::unserialize

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

SplObjectStorage::unserialize — ストレージの文字列表現をアンシリアライズする

説明

public SplObjectStorage::unserialize(string $data): void

ストレージのエントリをアンシリアライズし、現在のストレージに追加します。

パラメータ

data

ストレージをシリアライズしたもの。

戻り値

値を返しません。

例

例1 SplObjectStorage::unserialize() の例

<?php
$s1 = new SplObjectStorage;
$s2 = new SplObjectStorage;
$o = new stdClass;
$s1[$o] = "data";

$s2->unserialize($s1->serialize());

var_dump(count($s2));
?>

上の例の出力は、 たとえば以下のようになります。

int(1)

参考

  • SplObjectStorage::serialize() - ストレージをシリアライズする


イテレータの現在のエントリが有効かどうかを返す

  • ≪ SplObjectStorage::unserialize
  • イテレータ ≫
  • PHP Manual
  • SplObjectStorage
  • イテレータの現在のエントリが有効かどうかを返す

SplObjectStorage::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObjectStorage::valid — イテレータの現在のエントリが有効かどうかを返す

説明

public SplObjectStorage::valid(): bool

イテレータの現在のエントリが有効かどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータのエントリが有効な場合に true、それ以外の場合に false を返します。

例

例1 SplObjectStorage::valid() の例

<?php
$s = new SplObjectStorage();

$o1 = new stdClass;
$o2 = new stdClass;

$s->attach($o1, "d1");
$s->attach($o2, "d2");

$s->rewind();
while($s->valid()) {
echo $s->key()."\n";
$s->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

0
1

参考

  • SplObjectStorage::current() - 現在のストレージの要素を返す
  • SplObjectStorage::getInfo() - イテレータの現在のエントリに関連づけられたデータを返す


イテレータ

目次

  • AppendIterator
  • ArrayIterator
  • CachingIterator
  • CallbackFilterIterator
  • DirectoryIterator
  • EmptyIterator
  • FilesystemIterator
  • FilterIterator
  • GlobIterator
  • InfiniteIterator
  • IteratorIterator
  • LimitIterator
  • MultipleIterator
  • NoRewindIterator
  • ParentIterator
  • RecursiveArrayIterator
  • RecursiveCachingIterator
  • RecursiveCallbackFilterIterator
  • RecursiveDirectoryIterator
  • RecursiveFilterIterator
  • RecursiveIteratorIterator
  • RecursiveRegexIterator
  • RecursiveTreeIterator
  • RegexIterator

SPL にはイテレータが用意されており、オブジェクトを反復処理することができます。

SPL イテレータクラスツリー

  • ArrayIterator
    • RecursiveArrayIterator
  • EmptyIterator
  • IteratorIterator
    • AppendIterator
    • CachingIterator
      • RecursiveCachingIterator
    • FilterIterator
      • CallbackFilterIterator
        • RecursiveCallbackFilterIterator
      • RecursiveFilterIterator
        • ParentIterator
      • RegexIterator
        • RecursiveRegexIterator
    • InfiniteIterator
    • LimitIterator
    • NoRewindIterator
  • MultipleIterator
  • RecursiveIteratorIterator
    • RecursiveTreeIterator
  • DirectoryIterator (extends SplFileInfo)
    • FilesystemIterator
      • GlobIterator
      • RecursiveDirectoryIterator


AppendIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

複数のイテレータをひとつひとつ処理するイテレータです。

クラス概要

class AppendIterator extends IteratorIterator {
/* メソッド */
public __construct()
public append(Iterator $iterator): void
public current(): mixed
public getArrayIterator(): ArrayIterator
public getIteratorIndex(): ?int
public key(): scalar
public next(): void
public rewind(): void
public valid(): bool
/* 継承したメソッド */
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • AppendIterator::append — イテレータを追加する
  • AppendIterator::__construct — AppendIterator を作成する
  • AppendIterator::current — 現在の値を取得する
  • AppendIterator::getArrayIterator — ArrayIterator を取得する
  • AppendIterator::getIteratorIndex — イテレータのインデックスを取得する
  • AppendIterator::key — 現在のキーを取得する
  • AppendIterator::next — 次の要素に移動する
  • AppendIterator::rewind — イテレータを巻き戻す
  • AppendIterator::valid — 現在の要素が有効かどうかを調べる


イテレータを追加する

  • ≪ AppendIterator
  • AppendIterator::__construct ≫
  • PHP Manual
  • AppendIterator
  • イテレータを追加する

AppendIterator::append

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::append — イテレータを追加する

説明

public AppendIterator::append(Iterator $iterator): void

イテレータを追加します。

パラメータ

iterator

追加するイテレータ。

戻り値

値を返しません。

例

例1 AppendIterator::append() の例

<?php
$array_a = new ArrayIterator(array('a', 'b', 'c'));
$array_b = new ArrayIterator(array('d', 'e', 'f'));

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

foreach ($iterator as $current) {
echo $current;
}
?>

上の例の出力は以下となります。

abcdef

参考

  • AppendIterator::__construct() - AppendIterator を作成する


AppendIterator を作成する

  • ≪ AppendIterator::append
  • AppendIterator::current ≫
  • PHP Manual
  • AppendIterator
  • AppendIterator を作成する

AppendIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::__construct — AppendIterator を作成する

説明

public AppendIterator::__construct()

AppendIterator を作成します。

パラメータ

この関数にはパラメータはありません。

例

例1 AppendIterator の foreach での使用例

<?php
$pizzas = new ArrayIterator(array('Margarita', 'Siciliana', 'Hawaii'));
$toppings = new ArrayIterator(array('Cheese', 'Anchovies', 'Olives', 'Pineapple', 'Ham'));

$appendIterator = new AppendIterator;
$appendIterator->append($pizzas);
$appendIterator->append($toppings);

foreach ($appendIterator as $key => $item) {
echo $key . ' => ' . $item . PHP_EOL;
}
?>

上の例の出力は以下となります。

0 => Margarita
1 => Siciliana
2 => Hawaii
0 => Cheese
1 => Anchovies
2 => Olives
3 => Pineapple
4 => Ham

例2 AppendIterator API による AppendIterator の処理

<?php
$pizzas = new ArrayIterator(array('Margarita', 'Siciliana', 'Hawaii'));
$toppings = new ArrayIterator(array('Cheese', 'Anchovies', 'Olives', 'Pineapple', 'Ham'));

$appendIterator = new AppendIterator;
$appendIterator->append($pizzas);
$appendIterator->append($toppings);

while ($appendIterator->valid()) {
printf(
'%s => %s => %s%s',
$appendIterator->getIteratorIndex(),
$appendIterator->key(),
$appendIterator->current(),
PHP_EOL
);
$appendIterator->next();
}
?>

上の例の出力は以下となります。

0 => 0 => Margarita
0 => 1 => Siciliana
0 => 2 => Hawaii
1 => 0 => Cheese
1 => 1 => Anchovies
1 => 2 => Olives
1 => 3 => Pineapple
1 => 4 => Ham

注意

警告

iterator_to_array() を使って AppendIterator の値を配列にコピーするときは、 オプションの引数 use_key に false を指定しなければなりません。 use_key を false にしなければ、 内部イテレータに同名のキーが含まれていると 返される配列が上書きされてしまいます。 このときに元のキーの値を取得する方法はありません。

参考

  • AppendIterator::append() - イテレータを追加する


現在の値を取得する

  • ≪ AppendIterator::__construct
  • AppendIterator::getArrayIterator ≫
  • PHP Manual
  • AppendIterator
  • 現在の値を取得する

AppendIterator::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::current — 現在の値を取得する

説明

public AppendIterator::current(): mixed

現在の値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

有効な状態の場合は現在の値、それ以外の場合は null を返します。

参考

  • Iterator::current() - 現在の要素を返す
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::valid() - 現在の要素が有効かどうかを調べる
  • AppendIterator::next() - 次の要素に移動する
  • AppendIterator::rewind() - イテレータを巻き戻す


ArrayIterator を取得する

  • ≪ AppendIterator::current
  • AppendIterator::getIteratorIndex ≫
  • PHP Manual
  • AppendIterator
  • ArrayIterator を取得する

AppendIterator::getArrayIterator

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

AppendIterator::getArrayIterator — ArrayIterator を取得する

説明

public AppendIterator::getArrayIterator(): ArrayIterator

このメソッドは ArrayIterator を取得します。ここに、 AppendIterator::append() で追加したイテレータを格納します。

パラメータ

この関数にはパラメータはありません。

戻り値

追加したイテレータを含む ArrayIterator を返します。

参考

  • AppendIterator::getInnerIterator()


イテレータのインデックスを取得する

  • ≪ AppendIterator::getArrayIterator
  • AppendIterator::key ≫
  • PHP Manual
  • AppendIterator
  • イテレータのインデックスを取得する

AppendIterator::getIteratorIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

AppendIterator::getIteratorIndex — イテレータのインデックスを取得する

説明

public AppendIterator::getIteratorIndex(): ?int

現在の内部イテレータのインデックスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

存在していれば、 現在の内部イテレータのインデックス (最初はゼロ) を整数値で返します。 存在しない場合、null を返します。

例

例1 AppendIterator.getIteratorIndex() の基本的な例

<?php
$array_a = new ArrayIterator(array('a' => 'aardwolf', 'b' => 'bear', 'c' => 'capybara'));
$array_b = new ArrayIterator(array('apple', 'orange', 'lemon'));

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

foreach ($iterator as $key => $current) {
echo $iterator->getIteratorIndex() . ' ' . $key . ' ' . $current . PHP_EOL;
}
?>

上の例の出力は以下となります。

0  a aardwolf
0  b bear
0  c capybara
1  0 apple
1  1 orange
1  2 lemon

参考

  • AppendIterator::getInnerIterator()
  • AppendIterator::getArrayIterator() - ArrayIterator を取得する


現在のキーを取得する

  • ≪ AppendIterator::getIteratorIndex
  • AppendIterator::next ≫
  • PHP Manual
  • AppendIterator
  • 現在のキーを取得する

AppendIterator::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::key — 現在のキーを取得する

説明

public AppendIterator::key(): scalar

現在のキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

有効な状態の場合は現在のキー、それ以外の場合は null を返します。

例

例1 AppendIterator::key() の基本的な例

<?php
$array_a = new ArrayIterator(array('a' => 'aardwolf', 'b' => 'bear', 'c' => 'capybara'));
$array_b = new ArrayIterator(array('apple', 'orange', 'lemon'));

$iterator = new AppendIterator;
$iterator->append($array_a);
$iterator->append($array_b);

// Manual iteration
$iterator->rewind();
while ($iterator->valid()) {
echo $iterator->key() . ' ' . $iterator->current() . PHP_EOL;
$iterator->next();
}

echo PHP_EOL;

// With foreach
foreach ($iterator as $key => $current) {
echo $key . ' ' . $current . PHP_EOL;
}
?>

上の例の出力は以下となります。

a aardwolf
b bear
c capybara
0 apple
1 orange
2 lemon

a aardwolf
b bear
c capybara
0 apple
1 orange
2 lemon

参考

  • AppendIterator::current() - 現在の値を取得する


次の要素に移動する

  • ≪ AppendIterator::key
  • AppendIterator::rewind ≫
  • PHP Manual
  • AppendIterator
  • 次の要素に移動する

AppendIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::next — 次の要素に移動する

説明

public AppendIterator::next(): void

次の要素に移動します。もし別のイテレータに移動する場合は、そのイテレータを巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Iterator::next() - 次の要素に進む
  • AppendIterator::current() - 現在の値を取得する
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::valid() - 現在の要素が有効かどうかを調べる
  • AppendIterator::rewind() - イテレータを巻き戻す


イテレータを巻き戻す

  • ≪ AppendIterator::next
  • AppendIterator::valid ≫
  • PHP Manual
  • AppendIterator
  • イテレータを巻き戻す

AppendIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::rewind — イテレータを巻き戻す

説明

public AppendIterator::rewind(): void

最初の内部イテレータの最初の要素まで巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Iterator::rewind() - イテレータの最初の要素に巻き戻す
  • AppendIterator::current() - 現在の値を取得する
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::next() - 次の要素に移動する
  • AppendIterator::valid() - 現在の要素が有効かどうかを調べる


現在の要素が有効かどうかを調べる

  • ≪ AppendIterator::rewind
  • ArrayIterator ≫
  • PHP Manual
  • AppendIterator
  • 現在の要素が有効かどうかを調べる

AppendIterator::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

AppendIterator::valid — 現在の要素が有効かどうかを調べる

説明

public AppendIterator::valid(): bool

現在の要素が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のイテレーションが有効な場合に true、それ以外の場合に false を返します。

参考

  • AppendIterator::current() - 現在の値を取得する
  • AppendIterator::key() - 現在のキーを取得する
  • AppendIterator::next() - 次の要素に移動する
  • AppendIterator::rewind() - イテレータを巻き戻す


ArrayIterator クラス

(PHP 5, PHP 7, PHP 8)

はじめに

このイテレータは、配列やオブジェクトを反復処理する際に 値やキーを修正したり、要素を削除することができます。

同じ配列を何度も反復処理したい場合は、 ArrayObject のインスタンスとそれを参照する ArrayIterator のインスタンスを作成し、 foreach を使用するか getIterator() メソッドを手動でコールします。

クラス概要

class ArrayIterator implements SeekableIterator, ArrayAccess, Serializable, Countable {
/* 定数 */
public const int STD_PROP_LIST;
public const int ARRAY_AS_PROPS;
/* メソッド */
public __construct(array|object $array = [], int $flags = 0)
public append(mixed $value): void
public asort(int $flags = SORT_REGULAR): true
public count(): int
public current(): mixed
public getArrayCopy(): array
public getFlags(): int
public key(): string|int|null
public ksort(int $flags = SORT_REGULAR): true
public natcasesort(): true
public natsort(): true
public next(): void
public offsetExists(mixed $key): bool
public offsetGet(mixed $key): mixed
public offsetSet(mixed $key, mixed $value): void
public offsetUnset(mixed $key): void
public rewind(): void
public seek(int $offset): void
public serialize(): string
public setFlags(int $flags): void
public uasort(callable $callback): true
public uksort(callable $callback): true
public unserialize(string $data): void
public valid(): bool
}

定義済み定数

ArrayIterator のフラグ

ArrayIterator::STD_PROP_LIST

オブジェクトのプロパティが、 リストとして(var_dump, foreach などから)アクセスされたときの通常の機能を持つ

ArrayIterator::ARRAY_AS_PROPS

エントリがプロパティとしてアクセスできる(読み書きともに)

目次

  • ArrayIterator::append — 要素を追加する
  • ArrayIterator::asort — 値で配列をソートする
  • ArrayIterator::__construct — ArrayIterator を作成する
  • ArrayIterator::count — 要素を数える
  • ArrayIterator::current — 現在の配列エントリを返す
  • ArrayIterator::getArrayCopy — 配列のコピーを取得する
  • ArrayIterator::getFlags — 振る舞いのフラグを取得する
  • ArrayIterator::key — 現在の配列キーを返す
  • ArrayIterator::ksort — キーで配列をソートする
  • ArrayIterator::natcasesort — 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort — 自然順で配列をソートする
  • ArrayIterator::next — 次のエントリに移動する
  • ArrayIterator::offsetExists — オフセットが存在するかどうかを調べる
  • ArrayIterator::offsetGet — オフセットの値を取得する
  • ArrayIterator::offsetSet — オフセットの値を設定する
  • ArrayIterator::offsetUnset — オフセットの値を削除する
  • ArrayIterator::rewind — 配列を最初に巻き戻す
  • ArrayIterator::seek — 位置を移動する
  • ArrayIterator::serialize — シリアライズする
  • ArrayIterator::setFlags — 振る舞いのフラグを設定する
  • ArrayIterator::uasort — ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • ArrayIterator::uksort — ユーザー定義の比較関数を使い、キーでソートする
  • ArrayIterator::unserialize — アンシリアライズする
  • ArrayIterator::valid — 配列がまだエントリを持っているかどうかチェックする


要素を追加する

  • ≪ ArrayIterator
  • ArrayIterator::asort ≫
  • PHP Manual
  • ArrayIterator
  • 要素を追加する

ArrayIterator::append

(PHP 5, PHP 7, PHP 8)

ArrayIterator::append — 要素を追加する

説明

public ArrayIterator::append(mixed $value): void

値を最後の要素として追加します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

value

追加する値。

戻り値

値を返しません。

注意

注意:

このメソッドは、ArrayIterator がオブジェクトを参照している場合はコールできません。

参考

  • ArrayIterator::next() - 次のエントリに移動する


値で配列をソートする

  • ≪ ArrayIterator::append
  • ArrayIterator::__construct ≫
  • PHP Manual
  • ArrayIterator
  • 値で配列をソートする

ArrayIterator::asort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayIterator::asort — 値で配列をソートする

説明

public ArrayIterator::asort(int $flags = SORT_REGULAR): true

値で配列をソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする
  • ArrayIterator::uasort() - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • ArrayIterator::uksort() - ユーザー定義の比較関数を使い、キーでソートする
  • asort() - 連想キーと要素との関係を維持しつつ配列を昇順にソートする


ArrayIterator を作成する

  • ≪ ArrayIterator::asort
  • ArrayIterator::count ≫
  • PHP Manual
  • ArrayIterator
  • ArrayIterator を作成する

ArrayIterator::__construct

(PHP 5, PHP 7, PHP 8)

ArrayIterator::__construct — ArrayIterator を作成する

説明

public ArrayIterator::__construct(array|object $array = [], int $flags = 0)

ArrayIterator オブジェクトを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

array

反復処理をする配列あるいはオブジェクト。

flags

ArrayIterator オブジェクトの振る舞いを制御するフラグ。 ArrayIterator::setFlags() を参照ください。

参考

  • ArrayIterator::getArrayCopy() - 配列のコピーを取得する


要素を数える

  • ≪ ArrayIterator::__construct
  • ArrayIterator::current ≫
  • PHP Manual
  • ArrayIterator
  • 要素を数える

ArrayIterator::count

(PHP 5, PHP 7, PHP 8)

ArrayIterator::count — 要素を数える

説明

public ArrayIterator::count(): int

配列の要素の数、あるいはオブジェクトの public プロパティの数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

連想配列の場合は要素の数、オブジェクトの場合は public プロパティの数を返します。

参考

  • ArrayIterator::getFlags() - 振る舞いのフラグを取得する


現在の配列エントリを返す

  • ≪ ArrayIterator::count
  • ArrayIterator::getArrayCopy ≫
  • PHP Manual
  • ArrayIterator
  • 現在の配列エントリを返す

ArrayIterator::current

(PHP 5, PHP 7, PHP 8)

ArrayIterator::current — 現在の配列エントリを返す

説明

public ArrayIterator::current(): mixed

現在の配列エントリを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の配列エントリを返します。

例

例1 ArrayIterator::current() の例

<?php
$array = array('1' => 'one',
'2' => 'two',
'3' => 'three');

$arrayobject = new ArrayObject($array);

for($iterator = $arrayobject->getIterator();
$iterator->valid();
$iterator->next()) {

echo $iterator->key() . ' => ' . $iterator->current() . "\n";
}
?>

上の例の出力は以下となります。

1 => one
2 => two
3 => three


配列のコピーを取得する

  • ≪ ArrayIterator::current
  • ArrayIterator::getFlags ≫
  • PHP Manual
  • ArrayIterator
  • 配列のコピーを取得する

ArrayIterator::getArrayCopy

(PHP 5, PHP 7, PHP 8)

ArrayIterator::getArrayCopy — 配列のコピーを取得する

説明

public ArrayIterator::getArrayCopy(): array

配列のコピーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

配列のコピーを返します。 ArrayIterator がオブジェクトを参照している場合は public プロパティの配列を返します。

参考

  • ArrayIterator::valid() - 配列がまだエントリを持っているかどうかチェックする


振る舞いのフラグを取得する

  • ≪ ArrayIterator::getArrayCopy
  • ArrayIterator::key ≫
  • PHP Manual
  • ArrayIterator
  • 振る舞いのフラグを取得する

ArrayIterator::getFlags

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayIterator::getFlags — 振る舞いのフラグを取得する

説明

public ArrayIterator::getFlags(): int

ArrayIterator の振る舞いを示すフラグを取得します。 利用可能なフラグについては、 ArrayIterator::setFlags を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のフラグを返します。

参考

  • ArrayIterator::setFlags() - 振る舞いのフラグを設定する
  • ArrayIterator::valid() - 配列がまだエントリを持っているかどうかチェックする


現在の配列キーを返す

  • ≪ ArrayIterator::getFlags
  • ArrayIterator::ksort ≫
  • PHP Manual
  • ArrayIterator
  • 現在の配列キーを返す

ArrayIterator::key

(PHP 5, PHP 7, PHP 8)

ArrayIterator::key — 現在の配列キーを返す

説明

public ArrayIterator::key(): string|int|null

この関数は、現在の配列キーを返します

パラメータ

この関数にはパラメータはありません。

戻り値

この関数は、現在の配列キーを返します

例

例1 ArrayIterator::key() の例

<?php
$array = array('key' => 'value');

$arrayobject = new ArrayObject($array);
$iterator = $arrayobject->getIterator();

echo $iterator->key(); //key
?>


キーで配列をソートする

  • ≪ ArrayIterator::key
  • ArrayIterator::natcasesort ≫
  • PHP Manual
  • ArrayIterator
  • キーで配列をソートする

ArrayIterator::ksort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayIterator::ksort — キーで配列をソートする

説明

public ArrayIterator::ksort(int $flags = SORT_REGULAR): true

キーで配列をソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする
  • ArrayIterator::uasort() - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • ArrayIterator::uksort() - ユーザー定義の比較関数を使い、キーでソートする
  • ksort() - 配列をキーで昇順にソートする


大文字小文字を区別せずに自然順で配列をソートする

  • ≪ ArrayIterator::ksort
  • ArrayIterator::natsort ≫
  • PHP Manual
  • ArrayIterator
  • 大文字小文字を区別せずに自然順で配列をソートする

ArrayIterator::natcasesort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayIterator::natcasesort — 大文字小文字を区別せずに自然順で配列をソートする

説明

public ArrayIterator::natcasesort(): true

大文字小文字を区別しない "自然順" アルゴリズムを使って、値でエントリをソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする
  • ArrayIterator::uasort() - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • ArrayIterator::uksort() - ユーザー定義の比較関数を使い、キーでソートする
  • natcasesort() - 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする


自然順で配列をソートする

  • ≪ ArrayIterator::natcasesort
  • ArrayIterator::next ≫
  • PHP Manual
  • ArrayIterator
  • 自然順で配列をソートする

ArrayIterator::natsort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayIterator::natsort — 自然順で配列をソートする

説明

public ArrayIterator::natsort(): true

"自然順" アルゴリズムを使って、値でエントリをソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::uasort() - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • ArrayIterator::uksort() - ユーザー定義の比較関数を使い、キーでソートする
  • natsort() - "自然順"アルゴリズムで配列をソートする


次のエントリに移動する

  • ≪ ArrayIterator::natsort
  • ArrayIterator::offsetExists ≫
  • PHP Manual
  • ArrayIterator
  • 次のエントリに移動する

ArrayIterator::next

(PHP 5, PHP 7, PHP 8)

ArrayIterator::next — 次のエントリに移動する

説明

public ArrayIterator::next(): void

この関数は次のエントリにイテレータを移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 ArrayIterator::next() の例

<?php
$arrayobject = new ArrayObject();

$arrayobject[] = 'zero';
$arrayobject[] = 'one';

$iterator = $arrayobject->getIterator();

while($iterator->valid()) {
echo $iterator->key() . ' => ' . $iterator->current() . "\n";

$iterator->next();
}
?>

上の例の出力は以下となります。

0 => zero
1 => one


オフセットが存在するかどうかを調べる

  • ≪ ArrayIterator::next
  • ArrayIterator::offsetGet ≫
  • PHP Manual
  • ArrayIterator
  • オフセットが存在するかどうかを調べる

ArrayIterator::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayIterator::offsetExists — オフセットが存在するかどうかを調べる

説明

public ArrayIterator::offsetExists(mixed $key): bool

オフセットが存在するかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

調べたいオフセット。

戻り値

オフセットが存在する場合に true、それ以外の場合に false を返します。

参考

  • ArrayIterator::valid() - 配列がまだエントリを持っているかどうかチェックする


オフセットの値を取得する

  • ≪ ArrayIterator::offsetExists
  • ArrayIterator::offsetSet ≫
  • PHP Manual
  • ArrayIterator
  • オフセットの値を取得する

ArrayIterator::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayIterator::offsetGet — オフセットの値を取得する

説明

public ArrayIterator::offsetGet(mixed $key): mixed

指定したオフセットの値を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

値を取得したいオフセット。

戻り値

オフセット key の値を返します。

参考

  • ArrayIterator::offsetSet() - オフセットの値を設定する
  • ArrayIterator::offsetUnset() - オフセットの値を削除する


オフセットの値を設定する

  • ≪ ArrayIterator::offsetGet
  • ArrayIterator::offsetUnset ≫
  • PHP Manual
  • ArrayIterator
  • オフセットの値を設定する

ArrayIterator::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayIterator::offsetSet — オフセットの値を設定する

説明

public ArrayIterator::offsetSet(mixed $key, mixed $value): void

指定したオフセットの値を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

設定したいインデックス。

value

インデックスに格納する新しい値。

戻り値

値を返しません。

参考

  • ArrayIterator::offsetGet() - オフセットの値を取得する
  • ArrayIterator::offsetUnset() - オフセットの値を削除する


オフセットの値を削除する

  • ≪ ArrayIterator::offsetSet
  • ArrayIterator::rewind ≫
  • PHP Manual
  • ArrayIterator
  • オフセットの値を削除する

ArrayIterator::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayIterator::offsetUnset — オフセットの値を削除する

説明

public ArrayIterator::offsetUnset(mixed $key): void

オフセットの値を削除します。

反復処理を実行中の場合、かつ現在の処理のインデックスを削除するために ArrayIterator::offsetUnset() を使った場合、 反復処理の位置は次のインデックスに移動します。 反復処理の位置が foreach ループの最後であってもインデックスは移動するため、 foreach ループの内部で ArrayIterator::offsetUnset() を使うと、 複数のインデックスがスキップされるかもしれません。

パラメータ

key

削除したいオフセット。

戻り値

値を返しません。

参考

  • ArrayIterator::offsetGet() - オフセットの値を取得する
  • ArrayIterator::offsetSet() - オフセットの値を設定する


配列を最初に巻き戻す

  • ≪ ArrayIterator::offsetUnset
  • ArrayIterator::seek ≫
  • PHP Manual
  • ArrayIterator
  • 配列を最初に巻き戻す

ArrayIterator::rewind

(PHP 5, PHP 7, PHP 8)

ArrayIterator::rewind — 配列を最初に巻き戻す

説明

public ArrayIterator::rewind(): void

イテレータを最初に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 ArrayIterator::rewind() の例

<?php
$arrayobject = new ArrayObject();

$arrayobject[] = 'zero';
$arrayobject[] = 'one';
$arrayobject[] = 'two';

$iterator = $arrayobject->getIterator();

$iterator->next();
echo $iterator->key(); //1

$iterator->rewind(); //最初に巻き戻す
echo $iterator->key(); //0
?>


位置を移動する

  • ≪ ArrayIterator::rewind
  • ArrayIterator::serialize ≫
  • PHP Manual
  • ArrayIterator
  • 位置を移動する

ArrayIterator::seek

(PHP 5, PHP 7, PHP 8)

ArrayIterator::seek — 位置を移動する

説明

public ArrayIterator::seek(int $offset): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

offset

移動する位置。

戻り値

値を返しません。


シリアライズする

  • ≪ ArrayIterator::seek
  • ArrayIterator::setFlags ≫
  • PHP Manual
  • ArrayIterator
  • シリアライズする

ArrayIterator::serialize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ArrayIterator::serialize — シリアライズする

説明

public ArrayIterator::serialize(): string

シリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

シリアライズした ArrayIterator を返します。

参考

  • ArrayIterator::unserialize() - アンシリアライズする


振る舞いのフラグを設定する

  • ≪ ArrayIterator::serialize
  • ArrayIterator::uasort ≫
  • PHP Manual
  • ArrayIterator
  • 振る舞いのフラグを設定する

ArrayIterator::setFlags

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayIterator::setFlags — 振る舞いのフラグを設定する

説明

public ArrayIterator::setFlags(int $flags): void

振る舞いのフラグを設定します。

パラメータ

flags

新しい ArrayIterator の振る舞い。 以下のいずれかの値のビットマスクか、名前付き定数を設定します。 将来のバージョンとの互換性を保証するため、 名前付き定数を使うことを強く推奨します。

利用可能なフラグは以下のとおりです。 これらのフラグの実際の意味は、 定義済みの定数 で説明しています。

ArrayIterator の振る舞いを表すフラグ
値 | 定数
1 | ArrayIterator::STD_PROP_LIST
2 | ArrayIterator::ARRAY_AS_PROPS

戻り値

値を返しません。

参考

  • ArrayIterator::getFlags() - 振る舞いのフラグを取得する


ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する

  • ≪ ArrayIterator::setFlags
  • ArrayIterator::uksort ≫
  • PHP Manual
  • ArrayIterator
  • ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する

ArrayIterator::uasort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayIterator::uasort — ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する

説明

public ArrayIterator::uasort(callable $callback): true

この関数は、ユーザー定義の比較関数を使って 関連している値とインデックスの関係を管理する方法で、要素をソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする
  • ArrayIterator::uksort() - ユーザー定義の比較関数を使い、キーでソートする
  • uasort() - ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する


ユーザー定義の比較関数を使い、キーでソートする

  • ≪ ArrayIterator::uasort
  • ArrayIterator::unserialize ≫
  • PHP Manual
  • ArrayIterator
  • ユーザー定義の比較関数を使い、キーでソートする

ArrayIterator::uksort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayIterator::uksort — ユーザー定義の比較関数を使い、キーでソートする

説明

public ArrayIterator::uksort(callable $callback): true

ユーザー定義の比較関数を使って、キーでエントリをソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

参考

  • ArrayIterator::asort() - 値で配列をソートする
  • ArrayIterator::ksort() - キーで配列をソートする
  • ArrayIterator::natcasesort() - 大文字小文字を区別せずに自然順で配列をソートする
  • ArrayIterator::natsort() - 自然順で配列をソートする
  • ArrayIterator::uasort() - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
  • uksort() - ユーザー定義の比較関数を用いて、キーで配列をソートする


アンシリアライズする

  • ≪ ArrayIterator::uksort
  • ArrayIterator::valid ≫
  • PHP Manual
  • ArrayIterator
  • アンシリアライズする

ArrayIterator::unserialize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ArrayIterator::unserialize — アンシリアライズする

説明

public ArrayIterator::unserialize(string $data): void

アンシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

シリアライズした ArrayIterator オブジェクト。

戻り値

値を返しません。

参考

  • ArrayIterator::serialize() - シリアライズする


配列がまだエントリを持っているかどうかチェックする

  • ≪ ArrayIterator::unserialize
  • CachingIterator ≫
  • PHP Manual
  • ArrayIterator
  • 配列がまだエントリを持っているかどうかチェックする

ArrayIterator::valid

(PHP 5, PHP 7, PHP 8)

ArrayIterator::valid — 配列がまだエントリを持っているかどうかチェックする

説明

public ArrayIterator::valid(): bool

配列がまだエントリを持っているかどうかチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータが有効な場合に true、それ以外の場合に false を返します。

例

例1 ArrayIterator::valid() の例

<?php
$array = array('1' => 'one');

$arrayobject = new ArrayObject($array);
$iterator = $arrayobject->getIterator();

var_dump($iterator->valid()); //bool(true)

$iterator->next(); // 次のアイテムに進める

//配列要素が 1 つしかないので bool(false)
var_dump($iterator->valid());
?>


CachingIterator クラス

(PHP 5, PHP 7, PHP 8)

はじめに

このオブジェクトは、別のイテレータからキャッシュされた反復処理をサポートします。

クラス概要

class CachingIterator extends IteratorIterator implements ArrayAccess, Countable, Stringable {
/* 定数 */
public const int CALL_TOSTRING;
public const int CATCH_GET_CHILD;
public const int TOSTRING_USE_KEY;
public const int TOSTRING_USE_CURRENT;
public const int TOSTRING_USE_INNER;
public const int FULL_CACHE;
/* メソッド */
public __construct(Iterator $iterator, int $flags = CachingIterator::CALL_TOSTRING)
public count(): int
public current(): mixed
public getCache(): array
public getFlags(): int
public hasNext(): bool
public key(): scalar
public next(): void
public offsetExists(string $key): bool
public offsetGet(string $key): mixed
public offsetSet(string $key, mixed $value): void
public offsetUnset(string $key): void
public rewind(): void
public setFlags(int $flags): void
public __toString(): string
public valid(): bool
/* 継承したメソッド */
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

定義済み定数

CachingIterator::CALL_TOSTRING

それぞれの要素を文字列に変換します

CachingIterator::CATCH_GET_CHILD

子要素にアクセスする際、例外をスローしません

CachingIterator::TOSTRING_USE_KEY

文字列に変換する際に key を使います。

CachingIterator::TOSTRING_USE_CURRENT

文字列に変換する際に current を使います。

CachingIterator::TOSTRING_USE_INNER

文字列に変換する際に inner を使います。

CachingIterator::FULL_CACHE

読み込んだデータを全てキャッシュします。

変更履歴

バージョン | 説明
8.0.0 | CachingIterator は、 Stringable を新たに実装しました。

目次

  • CachingIterator::__construct — 新しい CachingIterator オブジェクトを作成する
  • CachingIterator::count — イテレータ内の要素の数
  • CachingIterator::current — 現在の要素を返す
  • CachingIterator::getCache — キャッシュの内容を取得する
  • CachingIterator::getFlags — 使用しているフラグを取得する
  • CachingIterator::hasNext — 内部イテレータが有効な次の要素を持つかどうかをチェックする
  • CachingIterator::key — 現在の要素のキーを返す
  • CachingIterator::next — イテレータを前方に移動する
  • CachingIterator::offsetExists — The offsetExists purpose
  • CachingIterator::offsetGet — The offsetGet purpose
  • CachingIterator::offsetSet — The offsetSet purpose
  • CachingIterator::offsetUnset — The offsetUnset purpose
  • CachingIterator::rewind — イテレータを巻き戻す
  • CachingIterator::setFlags — The setFlags purpose
  • CachingIterator::__toString — 現在の要素の文字列表現を返す
  • CachingIterator::valid — 現在の要素が有効かどうかをチェックする


新しい CachingIterator オブジェクトを作成する

  • ≪ CachingIterator
  • CachingIterator::count ≫
  • PHP Manual
  • CachingIterator
  • 新しい CachingIterator オブジェクトを作成する

CachingIterator::__construct

(PHP 5, PHP 7, PHP 8)

CachingIterator::__construct — 新しい CachingIterator オブジェクトを作成する

説明

public CachingIterator::__construct(Iterator $iterator, int $flags = CachingIterator::CALL_TOSTRING)
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

キャッシュしたいイテレータ。

flags

フラグのビットマスク。


イテレータ内の要素の数

  • ≪ CachingIterator::__construct
  • CachingIterator::current ≫
  • PHP Manual
  • CachingIterator
  • イテレータ内の要素の数

CachingIterator::count

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

CachingIterator::count — イテレータ内の要素の数

説明

public CachingIterator::count(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータ内の要素の数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

イテレータ内の要素の数を返します。


現在の要素を返す

  • ≪ CachingIterator::count
  • CachingIterator::getCache ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素を返す

CachingIterator::current

(PHP 5, PHP 7, PHP 8)

CachingIterator::current — 現在の要素を返す

説明

public CachingIterator::current(): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータの現在の要素を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Mixed

参考

  • Iterator::current() - 現在の要素を返す


キャッシュの内容を取得する

  • ≪ CachingIterator::current
  • CachingIterator::getFlags ≫
  • PHP Manual
  • CachingIterator
  • キャッシュの内容を取得する

CachingIterator::getCache

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::getCache — キャッシュの内容を取得する

説明

public CachingIterator::getCache(): array

キャッシュの内容を取得します。

注意:

CachingIterator::FULL_CACHE フラグを使う必要があります。

パラメータ

この関数にはパラメータはありません。

戻り値

キャッシュの内容を含む配列を返します。

エラー / 例外

CachingIterator::FULL_CACHE フラグを使っていない場合に BadMethodCallException をスローします。

例

例1 CachingIterator::getCache() の例

<?php
$iterator = new ArrayIterator(array(1, 2, 3));
$cache = new CachingIterator($iterator, CachingIterator::FULL_CACHE);

$cache->next();
$cache->next();
var_dump($cache->getCache());

$cache->next();
var_dump($cache->getCache());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


使用しているフラグを取得する

  • ≪ CachingIterator::getCache
  • CachingIterator::hasNext ≫
  • PHP Manual
  • CachingIterator
  • 使用しているフラグを取得する

CachingIterator::getFlags

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::getFlags — 使用しているフラグを取得する

説明

public CachingIterator::getFlags(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

CachingIterator インスタンスが使用するフラグのビットマスクを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Description...


内部イテレータが有効な次の要素を持つかどうかをチェックする

  • ≪ CachingIterator::getFlags
  • CachingIterator::key ≫
  • PHP Manual
  • CachingIterator
  • 内部イテレータが有効な次の要素を持つかどうかをチェックする

CachingIterator::hasNext

(PHP 5, PHP 7, PHP 8)

CachingIterator::hasNext — 内部イテレータが有効な次の要素を持つかどうかをチェックする

説明

public CachingIterator::hasNext(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


現在の要素のキーを返す

  • ≪ CachingIterator::hasNext
  • CachingIterator::next ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素のキーを返す

CachingIterator::key

(PHP 5, PHP 7, PHP 8)

CachingIterator::key — 現在の要素のキーを返す

説明

public CachingIterator::key(): scalar
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

このメソッドは、現在の要素のキーを返します。

パラメータ

この関数にはパラメータはありません。


イテレータを前方に移動する

  • ≪ CachingIterator::key
  • CachingIterator::offsetExists ≫
  • PHP Manual
  • CachingIterator
  • イテレータを前方に移動する

CachingIterator::next

(PHP 5, PHP 7, PHP 8)

CachingIterator::next — イテレータを前方に移動する

説明

public CachingIterator::next(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを前方に移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


The offsetExists purpose

  • ≪ CachingIterator::next
  • CachingIterator::offsetGet ≫
  • PHP Manual
  • CachingIterator
  • The offsetExists purpose

CachingIterator::offsetExists

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::offsetExists — The offsetExists purpose

説明

public CachingIterator::offsetExists(string $key): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

調べたいインデックス。

戻り値

そのオフセットがさすエントリが存在する場合に true、そうでない場合に false を返します。


The offsetGet purpose

  • ≪ CachingIterator::offsetExists
  • CachingIterator::offsetSet ≫
  • PHP Manual
  • CachingIterator
  • The offsetGet purpose

CachingIterator::offsetGet

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::offsetGet — The offsetGet purpose

説明

public CachingIterator::offsetGet(string $key): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

Description...

戻り値

Description...


The offsetSet purpose

  • ≪ CachingIterator::offsetGet
  • CachingIterator::offsetUnset ≫
  • PHP Manual
  • CachingIterator
  • The offsetSet purpose

CachingIterator::offsetSet

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::offsetSet — The offsetSet purpose

説明

public CachingIterator::offsetSet(string $key, mixed $value): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

設定したい要素のインデックス。

value

key の新しい値。

戻り値

値を返しません。


The offsetUnset purpose

  • ≪ CachingIterator::offsetSet
  • CachingIterator::rewind ≫
  • PHP Manual
  • CachingIterator
  • The offsetUnset purpose

CachingIterator::offsetUnset

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::offsetUnset — The offsetUnset purpose

説明

public CachingIterator::offsetUnset(string $key): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

key

設定を解除したい要素のインデックス。

戻り値

値を返しません。


イテレータを巻き戻す

  • ≪ CachingIterator::offsetUnset
  • CachingIterator::setFlags ≫
  • PHP Manual
  • CachingIterator
  • イテレータを巻き戻す

CachingIterator::rewind

(PHP 5, PHP 7, PHP 8)

CachingIterator::rewind — イテレータを巻き戻す

説明

public CachingIterator::rewind(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


The setFlags purpose

  • ≪ CachingIterator::rewind
  • CachingIterator::__toString ≫
  • PHP Manual
  • CachingIterator
  • The setFlags purpose

CachingIterator::setFlags

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

CachingIterator::setFlags — The setFlags purpose

説明

public CachingIterator::setFlags(int $flags): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

CachingIterator オブジェクトのフラグを設定します。

パラメータ

flags

設定したいフラグのビットマスク。

戻り値

値を返しません。


現在の要素の文字列表現を返す

  • ≪ CachingIterator::setFlags
  • CachingIterator::valid ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素の文字列表現を返す

CachingIterator::__toString

(PHP 5, PHP 7, PHP 8)

CachingIterator::__toString — 現在の要素の文字列表現を返す

説明

public CachingIterator::__toString(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素の文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の文字列表現を返します。


現在の要素が有効かどうかをチェックする

  • ≪ CachingIterator::__toString
  • CallbackFilterIterator ≫
  • PHP Manual
  • CachingIterator
  • 現在の要素が有効かどうかをチェックする

CachingIterator::valid

(PHP 5, PHP 7, PHP 8)

CachingIterator::valid — 現在の要素が有効かどうかをチェックする

説明

public CachingIterator::valid(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素が有効かどうかをチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


CallbackFilterIterator クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

クラス概要

class CallbackFilterIterator extends FilterIterator {
/* メソッド */
public __construct(Iterator $iterator, callable $callback)
public accept(): bool
/* 継承したメソッド */
public FilterIterator::accept(): bool
public FilterIterator::current(): mixed
public FilterIterator::key(): mixed
public FilterIterator::next(): void
public FilterIterator::rewind(): void
public FilterIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

例

コールバックは、三つの引数を受け付けなければなりません。 それぞれ、現在のアイテム、現在のキー、そしてイテレータを表します。

例1 利用可能なコールバック引数

<?php

/**
* CallbackFilterIterator 用のコールバック
*
* @param $current 現在のアイテムの値
* @param $key 現在のアイテムのキー
* @param $iterator フィルタリングするイテレータ
* @return boolean 現在のアイテムを受け付ける場合は TRUE、それ以外の場合は FALSE
*/
function my_callback($current, $key, $iterator) {
// ここにフィルタリングのコードを書きます
}

?>

任意の callable を使うことができます。 関数名を含む文字列、メソッドを表す配列、あるいは無名関数などです。

例2 コールバックの基本例

<?php

$dir = new FilesystemIterator(__DIR__);

// 大きなファイル ( > 100MB) をフィルタします
function is_large_file($current) {
return $current->isFile() && $current->getSize() > 104857600;
}
$large_files = new CallbackFilterIterator($dir, 'is_large_file');

// ディレクトリをフィルタします
$files = new CallbackFilterIterator($dir, function ($current, $key, $iterator) {
return $current->isDir() && ! $iterator->isDot();
});

?>

目次

  • CallbackFilterIterator::accept — 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す
  • CallbackFilterIterator::__construct — フィルタリングしたイテレータを別のイテレータから作成する


現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

  • ≪ CallbackFilterIterator
  • CallbackFilterIterator::__construct ≫
  • PHP Manual
  • CallbackFilterIterator
  • 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

CallbackFilterIterator::accept

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

CallbackFilterIterator::accept — 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す

説明

public CallbackFilterIterator::accept(): bool

このメソッドは、現在の値とキーそして内部イテレータを使ってコールバックをコールします。

コールバックは、現在のアイテムを受け付ける場合に true、 拒否する場合に false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のアイテムを受け付ける場合に true、それ以外の場合に false を返します。

参考

  • CallbackFilterIterator の例
  • CallbackFilterIterator::__construct() - フィルタリングしたイテレータを別のイテレータから作成する


フィルタリングしたイテレータを別のイテレータから作成する

  • ≪ CallbackFilterIterator::accept
  • DirectoryIterator ≫
  • PHP Manual
  • CallbackFilterIterator
  • フィルタリングしたイテレータを別のイテレータから作成する

CallbackFilterIterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

CallbackFilterIterator::__construct — フィルタリングしたイテレータを別のイテレータから作成する

説明

public CallbackFilterIterator::__construct(Iterator $iterator, callable $callback)

callback でフィルタリングしたイテレータを作って、 どのアイテムを受け付けてどれを拒否するかを決めます。

パラメータ

iterator

フィルタリングするイテレータ。

callback

コールバック。現在のアイテムを受け付ける場合に true、 拒否する場合に false を返します。 例 を参照ください。

任意の callable 値を指定できます。

参考

  • CallbackFilterIterator の例
  • CallbackFilterIterator::accept() - 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す


DirectoryIterator クラス

(PHP 5, PHP 7, PHP 8)

はじめに

DirectoryIterator クラスは、 ファイルシステムのディレクトリを閲覧するためのシンプルなインターフェイスです。

クラス概要

class DirectoryIterator extends SplFileInfo implements SeekableIterator {
/* メソッド */
public __construct(string $directory)
public current(): mixed
public getBasename(string $suffix = ""): string
public getExtension(): string
public getFilename(): string
public isDot(): bool
public key(): mixed
public next(): void
public rewind(): void
public seek(int $offset): void
public __toString(): string
public valid(): bool
/* 継承したメソッド */
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • DirectoryIterator::__construct — パスから新規ディレクトリイテレータを生成する
  • DirectoryIterator::current — 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::getBasename — 現在の DirectoryIterator のアイテムのベース名を取得する
  • DirectoryIterator::getExtension — ファイルの拡張子を取得する
  • DirectoryIterator::getFilename — 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::isDot — 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
  • DirectoryIterator::key — 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next — 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind — DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::seek — DirectoryIterator のアイテムを移動する
  • DirectoryIterator::__toString — ファイル名を文字列として取得する
  • DirectoryIterator::valid — 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする


パスから新規ディレクトリイテレータを生成する

  • ≪ DirectoryIterator
  • DirectoryIterator::current ≫
  • PHP Manual
  • DirectoryIterator
  • パスから新規ディレクトリイテレータを生成する

DirectoryIterator::__construct

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::__construct — パスから新規ディレクトリイテレータを生成する

説明

public DirectoryIterator::__construct(string $directory)

パスから新規ディレクトリイテレータを生成します。

パラメータ

directory

処理したいディレクトリのパス。

エラー / 例外

directory が存在しない場合に UnexpectedValueException をスローします。

directory が空文字列の場合に ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | directory が空の場合に、ValueError をスローするようになりました。 これより前のバージョンでは、 RuntimeException をスローしていました。

例

例1 DirectoryIterator::__construct() の例

この例は、スクリプト自身がいるディレクトリの中身を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
if (!$fileinfo->isDot()) {
var_dump($fileinfo->getFilename());
}
}
?>

参考

  • SplFileInfo
  • Iterator


現在の DirectoryIterator アイテムを返す

  • ≪ DirectoryIterator::__construct
  • DirectoryIterator::getBasename ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムを返す

DirectoryIterator::current

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::current — 現在の DirectoryIterator アイテムを返す

説明

public DirectoryIterator::current(): mixed

現在の DirectoryIterator アイテムを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の DirectoryIterator アイテムを返します。

例

例1 DirectoryIterator::current() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$iterator = new DirectoryIterator(__DIR__);
while($iterator->valid()) {
$file = $iterator->current();
echo $iterator->key() . " => " . $file->getFilename() . "\n";
$iterator->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

0 => .
1 => ..
2 => apple.jpg
3 => banana.jpg
4 => index.php
5 => pear.jpg

参考

  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::current() - 現在の要素を返す


現在の DirectoryIterator のアイテムのベース名を取得する

  • ≪ DirectoryIterator::current
  • DirectoryIterator::getExtension ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator のアイテムのベース名を取得する

DirectoryIterator::getBasename

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

DirectoryIterator::getBasename — 現在の DirectoryIterator のアイテムのベース名を取得する

説明

public DirectoryIterator::getBasename(string $suffix = ""): string

現在の DirectoryIterator のアイテムのベース名を取得します。

パラメータ

suffix

ベース名が suffix で終わる場合は、これがカットされます。

戻り値

現在の DirectoryIterator のアイテムのベース名を返します。

例

例1 DirectoryIterator::getBasename() の例

この例は、スクリプトがあるディレクトリ内のファイルについて 完全なベース名と最後の .jpg を取り除いたベース名を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
if ($fileinfo->isFile()) {
echo $fileinfo->getBasename() . "\n";
echo $fileinfo->getBasename('.jpg') . "\n";
}
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
apple
banana.jpg
banana
index.php
index.php
pear.jpg
pear

参考

  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getPath()
  • DirectoryIterator::getPathname()
  • basename() - パスの最後にある名前の部分を返す
  • pathinfo() - ファイルパスに関する情報を返す


ファイルの拡張子を取得する

  • ≪ DirectoryIterator::getBasename
  • DirectoryIterator::getFilename ≫
  • PHP Manual
  • DirectoryIterator
  • ファイルの拡張子を取得する

DirectoryIterator::getExtension

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

DirectoryIterator::getExtension — ファイルの拡張子を取得する

説明

public DirectoryIterator::getExtension(): string

ファイルの拡張子を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルの拡張子を文字列で返します。もし拡張しがない場合は空文字列を返します。

例

例1 DirectoryIterator::getExtension() の例

<?php

$directory = new DirectoryIterator(__DIR__);
foreach ($directory as $fileinfo) {
if ($fileinfo->isFile()) {
echo $fileinfo->getExtension() . "\n";
}
}

?>

上の例の出力は、 たとえば以下のようになります。

php
txt
jpg
gz

注意

注意:

このメソッドを使わずに拡張子を取得するには pathinfo() 関数を使います。

<?php
$extension = pathinfo($fileinfo->getFilename(), PATHINFO_EXTENSION);
?>

参考

  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getBasename() - 現在の DirectoryIterator のアイテムのベース名を取得する
  • pathinfo() - ファイルパスに関する情報を返す


現在の DirectoryIterator アイテムのファイル名を返す

  • ≪ DirectoryIterator::getExtension
  • DirectoryIterator::isDot ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのファイル名を返す

DirectoryIterator::getFilename

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::getFilename — 現在の DirectoryIterator アイテムのファイル名を返す

説明

public DirectoryIterator::getFilename(): string

現在の DirectoryIterator アイテムのファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の DirectoryIterator アイテムのファイル名を返します。

例

例1 DirectoryIterator::getFilename() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
echo $fileinfo->getFilename() . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apple.jpg
banana.jpg
index.php
pear.jpg

参考

  • DirectoryIterator::getBasename() - 現在の DirectoryIterator のアイテムのベース名を取得する
  • DirectoryIterator::getPath()
  • DirectoryIterator::getPathname()
  • pathinfo() - ファイルパスに関する情報を返す


現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる

  • ≪ DirectoryIterator::getFilename
  • DirectoryIterator::key ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる

DirectoryIterator::isDot

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::isDot — 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる

説明

public DirectoryIterator::isDot(): bool

現在の DirectoryIterator アイテムがディレクトリであり、かつ . あるいは .. のどちらかであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

エントリが . あるいは .. である場合に true、そうでない場合に false を返します。

例

例1 DirectoryIterator::isDot() の例

この例は、すべてのファイルを出力しますが . と .. は無視します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
foreach ($iterator as $fileinfo) {
if (!$fileinfo->isDot()) {
echo $fileinfo->getFilename() . "\n";
}
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php
pears.jpg

参考

  • DirectoryIterator::getType()
  • DirectoryIterator::isDir()
  • DirectoryIterator::isFile()
  • DirectoryIterator::isLink()


現在の DirectoryIterator アイテムのキーを返す

  • ≪ DirectoryIterator::isDot
  • DirectoryIterator::next ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator アイテムのキーを返す

DirectoryIterator::key

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::key — 現在の DirectoryIterator アイテムのキーを返す

説明

public DirectoryIterator::key(): mixed

現在の DirectoryIterator アイテムのキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の DirectoryIterator アイテムのキーを数値で返します。

変更履歴

バージョン | 説明
8.1.0 | イテレーターが初期化されていない場合、 Error がスローされるようになりました。 これより前のバージョンでは、false を返していました。

例

例1 DirectoryIterator::key() の例

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
if (!$fileinfo->isDot()) {
echo $fileinfo->key() . " => " . $fileinfo->getFilename() . "\n";
}
}
?>

上の例の出力は、 たとえば以下のようになります。

0 => apple.jpg
1 => banana.jpg
2 => index.php
3 => pear.jpg

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::key() - 現在の要素のキーを返す


次の DirectoryIterator アイテムに移動する

  • ≪ DirectoryIterator::key
  • DirectoryIterator::rewind ≫
  • PHP Manual
  • DirectoryIterator
  • 次の DirectoryIterator アイテムに移動する

DirectoryIterator::next

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::next — 次の DirectoryIterator アイテムに移動する

説明

public DirectoryIterator::next(): void

次の DirectoryIterator アイテムに移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 DirectoryIterator::next() の例

ディレクトリ内の一覧を while ループで表示します。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
while($iterator->valid()) {
echo $iterator->getFilename() . "\n";
$iterator->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apple.jpg
banana.jpg
index.php
pear.jpg

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::next() - 次の要素に進む


DirectoryIterator を最初に巻き戻す

  • ≪ DirectoryIterator::next
  • DirectoryIterator::seek ≫
  • PHP Manual
  • DirectoryIterator
  • DirectoryIterator を最初に巻き戻す

DirectoryIterator::rewind

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::rewind — DirectoryIterator を最初に巻き戻す

説明

public DirectoryIterator::rewind(): void

DirectoryIterator を最初に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 DirectoryIterator::rewind() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));

$iterator->next();
echo $iterator->key(); //1

$iterator->rewind(); // 最初に巻き戻します
echo $iterator->key(); //0
?>

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::valid() - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
  • Iterator::rewind() - イテレータの最初の要素に巻き戻す


DirectoryIterator のアイテムを移動する

  • ≪ DirectoryIterator::rewind
  • DirectoryIterator::__toString ≫
  • PHP Manual
  • DirectoryIterator
  • DirectoryIterator のアイテムを移動する

DirectoryIterator::seek

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DirectoryIterator::seek — DirectoryIterator のアイテムを移動する

説明

public DirectoryIterator::seek(int $offset): void

DirectoryIterator の指定した位置に移動します。

パラメータ

offset

異動先を表す、ゼロから始まる位置。

戻り値

値を返しません。

例

例1 DirectoryIterator::seek() の例

スクリプトを含むディレクトリの四番目のアイテムに移動します。 最初の二つは、通常は . と .. です。

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));
$iterator->seek(3);
if ($iterator->valid()) {
echo $iterator->getFilename();
} else {
echo 'No file at position 3';
}
?>

参考

  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • SeekableIterator::seek() - 位置を移動する


ファイル名を文字列として取得する

  • ≪ DirectoryIterator::seek
  • DirectoryIterator::valid ≫
  • PHP Manual
  • DirectoryIterator
  • ファイル名を文字列として取得する

DirectoryIterator::__toString

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::__toString — ファイル名を文字列として取得する

説明

public DirectoryIterator::__toString(): string

現在の DirectoryIterator のアイテムのファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の DirectoryIterator のアイテムのファイル名を返します。

例

例1 DirectoryIterator::__toString() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$dir = new DirectoryIterator(dirname(__FILE__));
foreach ($dir as $fileinfo) {
echo $fileinfo;
}
?>

上の例の出力は、 たとえば以下のようになります。

.
..
apple.jpg
banana.jpg
index.php
pear.jpg

参考

  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • __toString() マジックメソッド


現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

  • ≪ DirectoryIterator::__toString
  • EmptyIterator ≫
  • PHP Manual
  • DirectoryIterator
  • 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

DirectoryIterator::valid

(PHP 5, PHP 7, PHP 8)

DirectoryIterator::valid — 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする

説明

public DirectoryIterator::valid(): bool

現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

有効な位置である場合は true、それ以外の場合は false を返します。

例

例1 DirectoryIterator::valid() の例

<?php
$iterator = new DirectoryIterator(dirname(__FILE__));

// イテレータの最後の位置までループします
while($iterator->valid()) {
$iterator->next();
}

$iterator->valid(); // FALSE
$iterator->rewind();
$iterator->valid(); // TRUE

?>

参考

  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する
  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す
  • Iterator::valid() - 現在位置が有効かどうかを調べる


EmptyIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

空のイテレータ用の EmptyIterator クラスです。

クラス概要

class EmptyIterator implements Iterator {
/* メソッド */
public current(): never
public key(): never
public next(): void
public rewind(): void
public valid(): false
}

目次

  • EmptyIterator::current — current() メソッド
  • EmptyIterator::key — key() メソッド
  • EmptyIterator::next — next() メソッド
  • EmptyIterator::rewind — rewind() メソッド
  • EmptyIterator::valid — 現在の要素が有効かどうかを調べる


current() メソッド

  • ≪ EmptyIterator
  • EmptyIterator::key ≫
  • PHP Manual
  • EmptyIterator
  • current() メソッド

EmptyIterator::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

EmptyIterator::current — current() メソッド

説明

public EmptyIterator::current(): never

このメソッドをコールしてはいけません。アクセスされると例外をスローします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

エラー / 例外

コールされると Exception をスローします。

戻り値

値を返しません。


key() メソッド

  • ≪ EmptyIterator::current
  • EmptyIterator::next ≫
  • PHP Manual
  • EmptyIterator
  • key() メソッド

EmptyIterator::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

EmptyIterator::key — key() メソッド

説明

public EmptyIterator::key(): never

このメソッドをコールしてはいけません。アクセスされると例外をスローします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

エラー / 例外

コールされると Exception をスローします。

戻り値

値を返しません。


next() メソッド

  • ≪ EmptyIterator::key
  • EmptyIterator::rewind ≫
  • PHP Manual
  • EmptyIterator
  • next() メソッド

EmptyIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

EmptyIterator::next — next() メソッド

説明

public EmptyIterator::next(): void

何もしません。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


rewind() メソッド

  • ≪ EmptyIterator::next
  • EmptyIterator::valid ≫
  • PHP Manual
  • EmptyIterator
  • rewind() メソッド

EmptyIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

EmptyIterator::rewind — rewind() メソッド

説明

public EmptyIterator::rewind(): void

何もしません。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


現在の要素が有効かどうかを調べる

  • ≪ EmptyIterator::rewind
  • FilesystemIterator ≫
  • PHP Manual
  • EmptyIterator
  • 現在の要素が有効かどうかを調べる

EmptyIterator::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

EmptyIterator::valid — 現在の要素が有効かどうかを調べる

説明

public EmptyIterator::valid(): false

現在の要素が有効かどうかを調べます。

注意:

EmptyIterator は常に空なので、 有効な値を持ちません。返り値は常に false です。

パラメータ

この関数にはパラメータはありません。

戻り値

false


FilesystemIterator クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

Filesystem イテレータです。

クラス概要

class FilesystemIterator extends DirectoryIterator {
/* 定数 */
public const int CURRENT_MODE_MASK;
public const int CURRENT_AS_PATHNAME;
public const int CURRENT_AS_FILEINFO;
public const int CURRENT_AS_SELF;
public const int KEY_MODE_MASK;
public const int KEY_AS_PATHNAME;
public const int FOLLOW_SYMLINKS;
public const int KEY_AS_FILENAME;
public const int NEW_CURRENT_AND_KEY;
public const int OTHER_MODE_MASK;
public const int SKIP_DOTS;
public const int UNIX_PATHS;
/* メソッド */
public __construct(string $directory, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS)
public current(): string|SplFileInfo|FilesystemIterator
public getFlags(): int
public key(): string
public next(): void
public rewind(): void
public setFlags(int $flags): void
/* 継承したメソッド */
public DirectoryIterator::current(): mixed
public DirectoryIterator::getBasename(string $suffix = ""): string
public DirectoryIterator::getExtension(): string
public DirectoryIterator::getFilename(): string
public DirectoryIterator::isDot(): bool
public DirectoryIterator::key(): mixed
public DirectoryIterator::next(): void
public DirectoryIterator::rewind(): void
public DirectoryIterator::seek(int $offset): void
public DirectoryIterator::__toString(): string
public DirectoryIterator::valid(): bool
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

定義済み定数

FilesystemIterator::CURRENT_AS_PATHNAME

FilesystemIterator::current() がパス名を返すようにします。

FilesystemIterator::CURRENT_AS_FILEINFO

FilesystemIterator::current() が SplFileInfo のインスタンスを返すようにします。

FilesystemIterator::CURRENT_AS_SELF

FilesystemIterator::current() が $this (FilesystemIterator) を返すようにします。

FilesystemIterator::CURRENT_MODE_MASK

FilesystemIterator::current() をマスクします。

FilesystemIterator::KEY_AS_PATHNAME

FilesystemIterator::key() がパス名を返すようにします。

FilesystemIterator::KEY_AS_FILENAME

FilesystemIterator::key() がファイル名を返すようにします。

FilesystemIterator::FOLLOW_SYMLINKS

RecursiveDirectoryIterator::hasChildren() がシンボリックリンクのリンク先をたどるようにします。

FilesystemIterator::KEY_MODE_MASK

FilesystemIterator::key() をマスクします。

FilesystemIterator::NEW_CURRENT_AND_KEY

FilesystemIterator::KEY_AS_FILENAME | FilesystemIterator::CURRENT_AS_FILEINFO と同じ。

FilesystemIterator::OTHER_MODE_MASK

FilesystemIterator::getFlags() と FilesystemIterator::setFlags() で使うマスク

FilesystemIterator::SKIP_DOTS

ドットファイル (. および ..) をスキップします。

FilesystemIterator::UNIX_PATHS

システムのデフォルトにかかわらず、Unix スタイルのスラッシュでパスをあらわすようにします。 コンストラクタから渡された path は変更されないことに注意しましょう。

目次

  • FilesystemIterator::__construct — 新しい filesystem イテレータを作成する
  • FilesystemIterator::current — 現在のファイル
  • FilesystemIterator::getFlags — 処理フラグを取得する
  • FilesystemIterator::key — 現在のファイルのキーを取得する
  • FilesystemIterator::next — 次のファイルに移動する
  • FilesystemIterator::rewind — 先頭に巻き戻す
  • FilesystemIterator::setFlags — 処理フラグを設定する


新しい filesystem イテレータを作成する

  • ≪ FilesystemIterator
  • FilesystemIterator::current ≫
  • PHP Manual
  • FilesystemIterator
  • 新しい filesystem イテレータを作成する

FilesystemIterator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::__construct — 新しい filesystem イテレータを作成する

説明

public FilesystemIterator::__construct(string $directory, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS)

新しい filesystem イテレータを directory から作成します。

パラメータ

directory

反復処理したいファイルシステム上のアイテムへのパス。

flags

フラグを指定すると、いくつかのメソッドの振る舞いを変更することができます。 フラグの一覧は FilesystemIterator の定義済み定数 を参照ください。これは、あとで FilesystemIterator::setFlags() で設定することもできます。

エラー / 例外

directory が存在しない場合に、 UnexpectedValueException をスローします。

directory が空文字列の場合に、 ValueError をスローします。

変更履歴

バージョン | 説明
8.2.0 | PHP 8.2.0 より前のバージョンでは、 FilesystemIterator::SKIP_DOTS は常に設定され、削除できませんでした。
8.0.0 | directory が空文字列の場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、 RuntimeException をスローしていました。

例

例1 FilesystemIterator::__construct() の例

<?php
$it = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::CURRENT_AS_FILEINFO);
foreach ($it as $fileinfo) {
echo $fileinfo->getFilename() . "\n";
}
?>

上の例の PHP 8.2 での出力は、たとえば以下のようになります。:

.
..
apples.jpg
banana.jpg
example.php

PHP 8.2.0 より前のバージョンでは、上の例の出力は以下のようになります:

apples.jpg
banana.jpg
example.php

参考

  • FilesystemIterator::setFlags() - 処理フラグを設定する
  • DirectoryIterator::__construct() - パスから新規ディレクトリイテレータを生成する


現在のファイル

  • ≪ FilesystemIterator::__construct
  • FilesystemIterator::getFlags ≫
  • PHP Manual
  • FilesystemIterator
  • 現在のファイル

FilesystemIterator::current

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::current — 現在のファイル

説明

public FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator

現在の要素のファイル情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

設定されているフラグに応じ、ファイル名、ファイル情報あるいは $this を返します。 FilesystemIterator の定数 を参照ください。

例

例1 FilesystemIterator::current() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$iterator = new FilesystemIterator(__DIR__, FilesystemIterator::CURRENT_AS_PATHNAME);
foreach ($iterator as $fileinfo) {
echo $iterator->current() . "\n";
}
?>

上の例の PHP 8.2 での出力は、たとえば以下のようになります。:

/www/examples/.
/www/examples/..
/www/examples/apple.jpg
/www/examples/banana.jpg
/www/examples/example.php

参考

  • FilesystemIterator 定数
  • DirectoryIterator::current() - 現在の DirectoryIterator アイテムを返す
  • DirectoryIterator::getFileName() - 現在の DirectoryIterator アイテムのファイル名を返す


処理フラグを取得する

  • ≪ FilesystemIterator::current
  • FilesystemIterator::key ≫
  • PHP Manual
  • FilesystemIterator
  • 処理フラグを取得する

FilesystemIterator::getFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::getFlags — 処理フラグを取得する

説明

public FilesystemIterator::getFlags(): int

FilesystemIterator::__construct() あるいは FilesystemIterator::setFlags() で設定した処理フラグを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

設定されているフラグの値を返します。

参考

  • FilesystemIterator::__construct() - 新しい filesystem イテレータを作成する
  • FilesystemIterator::setFlags() - 処理フラグを設定する


現在のファイルのキーを取得する

  • ≪ FilesystemIterator::getFlags
  • FilesystemIterator::next ≫
  • PHP Manual
  • FilesystemIterator
  • 現在のファイルのキーを取得する

FilesystemIterator::key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::key — 現在のファイルのキーを取得する

説明

public FilesystemIterator::key(): string

パラメータ

この関数にはパラメータはありません。

戻り値

設定されているフラグに応じてパス名あるいはファイル名を返します。 FilesystemIterator の定数 も参照ください。

例

例1 FilesystemIterator::key() の例

この例は、スクリプトを含むディレクトリの中身を一覧表示します。

<?php
$iterator = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::KEY_AS_FILENAME);
foreach ($iterator as $fileinfo) {
echo $iterator->key() . "\n";
}
?>

上の例の PHP 8.2 での出力は、たとえば以下のようになります。:

.
..
apple.jpg
banana.jpg
example.php

参考

  • FilesystemIterator 定数
  • DirectoryIterator::key() - 現在の DirectoryIterator アイテムのキーを返す
  • DirectoryIterator::getFilename() - 現在の DirectoryIterator アイテムのファイル名を返す
  • DirectoryIterator::getPathname()


次のファイルに移動する

  • ≪ FilesystemIterator::key
  • FilesystemIterator::rewind ≫
  • PHP Manual
  • FilesystemIterator
  • 次のファイルに移動する

FilesystemIterator::next

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::next — 次のファイルに移動する

説明

public FilesystemIterator::next(): void

次のファイルに移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 FilesystemIterator::next() の例

ディレクトリの中身を while ループで一覧表示します。

<?php
$iterator = new FilesystemIterator(dirname(__FILE__));
while($iterator->valid()) {
echo $iterator->getFilename() . "\n";
$iterator->next();
}
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
example.php

参考

  • DirectoryIterator::next() - 次の DirectoryIterator アイテムに移動する


先頭に巻き戻す

  • ≪ FilesystemIterator::next
  • FilesystemIterator::setFlags ≫
  • PHP Manual
  • FilesystemIterator
  • 先頭に巻き戻す

FilesystemIterator::rewind

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::rewind — 先頭に巻き戻す

説明

public FilesystemIterator::rewind(): void

ディレクトリを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 FilesystemIterator::rewind() の例

<?php
$iterator = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::KEY_AS_FILENAME);

echo $iterator->key() . "\n";

$iterator->next();
echo $iterator->key() . "\n";

$iterator->rewind();
echo $iterator->key() . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

apple.jpg
banana.jpg
apple.jpg

参考

  • DirectoryIterator::rewind() - DirectoryIterator を最初に巻き戻す


処理フラグを設定する

  • ≪ FilesystemIterator::rewind
  • FilterIterator ≫
  • PHP Manual
  • FilesystemIterator
  • 処理フラグを設定する

FilesystemIterator::setFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

FilesystemIterator::setFlags — 処理フラグを設定する

説明

public FilesystemIterator::setFlags(int $flags): void

処理フラグを設定します。

パラメータ

flags

設定する処理フラグ。 FilesystemIterator の定数 も参照ください。

戻り値

値を返しません。

例

例1 FilesystemIterator::key() の例

この例は、フラグ FilesystemIterator::KEY_AS_PATHNAME と FilesystemIterator::KEY_AS_FILENAME の違いを示します。

<?php
$iterator = new FilesystemIterator(dirname(__FILE__), FilesystemIterator::KEY_AS_PATHNAME);
echo "Key as Pathname:\n";
foreach ($iterator as $key => $fileinfo) {
echo $key . "\n";
}

$iterator->setFlags(FilesystemIterator::KEY_AS_FILENAME);
echo "\nKey as Filename:\n";
foreach ($iterator as $key => $fileinfo) {
echo $key . "\n";
}
?>

上の例の PHP 8.2 での出力は、たとえば以下のようになります。:

Key as Pathname:
/www/examples/.
/www/examples/..
/www/examples/apple.jpg
/www/examples/banana.jpg
/www/examples/example.php

Key as Filename:
.
..
apple.jpg
banana.jpg
example.php

参考

  • FilesystemIterator::__construct() - 新しい filesystem イテレータを作成する
  • FilesystemIterator::getFlags() - 処理フラグを取得する


FilterIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

この抽象イテレータは、望まざる値をフィルタリングします。 独自のイテレータフィルタを実装するには、このクラスを継承しなければなりません。 また、サブクラスでは FilterIterator::accept() を実装する必要があります。

クラス概要

abstract class FilterIterator extends IteratorIterator {
/* メソッド */
public __construct(Iterator $iterator)
public accept(): bool
public current(): mixed
public key(): mixed
public next(): void
public rewind(): void
public valid(): bool
/* 継承したメソッド */
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • FilterIterator::accept — イテレータの現在の要素がフィルタを満たすかどうかを調べる
  • FilterIterator::__construct — filterIterator を作成する
  • FilterIterator::current — 現在の要素の値を取得する
  • FilterIterator::key — 現在のキーを取得する
  • FilterIterator::next — イテレータを前に移動する
  • FilterIterator::rewind — イテレータを巻き戻す
  • FilterIterator::valid — 現在の要素が有効かどうかをチェックする


イテレータの現在の要素がフィルタを満たすかどうかを調べる

  • ≪ FilterIterator
  • FilterIterator::__construct ≫
  • PHP Manual
  • FilterIterator
  • イテレータの現在の要素がフィルタを満たすかどうかを調べる

FilterIterator::accept

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::accept — イテレータの現在の要素がフィルタを満たすかどうかを調べる

説明

public FilterIterator::accept(): bool

イテレータの現在の要素がこのフィルタを通過するかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素が通過する場合に true、それ以外の場合に false を返します。

例

例1 FilterIterator::accept() の例

<?php
// このイテレータは、10 文字未満の値をすべてフィルタリングします
class LengthFilterIterator extends FilterIterator {

public function accept() {
// 長さが 10 文字以上の文字列のみを許可します
return strlen(parent::current()) >= 10;
}

}

$arrayIterator = new ArrayIterator(array('test1', 'more than 10 characters'));
$lengthFilter = new LengthFilterIterator($arrayIterator);

foreach ($lengthFilter as $value) {
echo $value . "\n";
}
?>

上の例の出力は以下となります。

more than 10 characters


filterIterator を作成する

  • ≪ FilterIterator::accept
  • FilterIterator::current ≫
  • PHP Manual
  • FilterIterator
  • filterIterator を作成する

FilterIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::__construct — filterIterator を作成する

説明

public FilterIterator::__construct(Iterator $iterator)

新しい FilterIterator を作成します。 これは、イテレータとそれに適用するフィルタで構成されています。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

フィルタリングの対象となるイテレータ。

参考

  • LimitIterator::__construct() - LimitIterator を作成する


現在の要素の値を取得する

  • ≪ FilterIterator::__construct
  • FilterIterator::key ≫
  • PHP Manual
  • FilterIterator
  • 現在の要素の値を取得する

FilterIterator::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::current — 現在の要素の値を取得する

説明

public FilterIterator::current(): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素の値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の値を返します。

参考

  • FilterIterator::key() - 現在のキーを取得する
  • FilterIterator::next() - イテレータを前に移動する


現在のキーを取得する

  • ≪ FilterIterator::current
  • FilterIterator::next ≫
  • PHP Manual
  • FilterIterator
  • 現在のキーを取得する

FilterIterator::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::key — 現在のキーを取得する

説明

public FilterIterator::key(): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のキーを返します。

参考

  • FilterIterator::next() - イテレータを前に移動する
  • FilterIterator::current() - 現在の要素の値を取得する


イテレータを前に移動する

  • ≪ FilterIterator::key
  • FilterIterator::rewind ≫
  • PHP Manual
  • FilterIterator
  • イテレータを前に移動する

FilterIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::next — イテレータを前に移動する

説明

public FilterIterator::next(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを前方に移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • FilterIterator::current() - 現在の要素の値を取得する
  • FilterIterator::key() - 現在のキーを取得する


イテレータを巻き戻す

  • ≪ FilterIterator::next
  • FilterIterator::valid ≫
  • PHP Manual
  • FilterIterator
  • イテレータを巻き戻す

FilterIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::rewind — イテレータを巻き戻す

説明

public FilterIterator::rewind(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

イテレータを巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • FilterIterator::current() - 現在の要素の値を取得する
  • FilterIterator::key() - 現在のキーを取得する
  • FilterIterator::next() - イテレータを前に移動する


現在の要素が有効かどうかをチェックする

  • ≪ FilterIterator::rewind
  • GlobIterator ≫
  • PHP Manual
  • FilterIterator
  • 現在の要素が有効かどうかをチェックする

FilterIterator::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

FilterIterator::valid — 現在の要素が有効かどうかをチェックする

説明

public FilterIterator::valid(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の要素が有効かどうかをチェックします。

注意:

この関数の標準的な実装は、 内部のイテレータが最初の有効な要素に進むまで、 まず false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素が有効である場合に true、そうでない場合に false を返します。


GlobIterator クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

ファイルシステムで、glob() と同じ形式の反復処理を行います。

クラス概要

class GlobIterator extends FilesystemIterator implements Countable {
/* 継承した定数 */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* メソッド */
public __construct(string $pattern, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO)
public count(): int
/* 継承したメソッド */
public FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public FilesystemIterator::getFlags(): int
public FilesystemIterator::key(): string
public FilesystemIterator::next(): void
public FilesystemIterator::rewind(): void
public FilesystemIterator::setFlags(int $flags): void
public DirectoryIterator::current(): mixed
public DirectoryIterator::getBasename(string $suffix = ""): string
public DirectoryIterator::getExtension(): string
public DirectoryIterator::getFilename(): string
public DirectoryIterator::isDot(): bool
public DirectoryIterator::key(): mixed
public DirectoryIterator::next(): void
public DirectoryIterator::rewind(): void
public DirectoryIterator::seek(int $offset): void
public DirectoryIterator::__toString(): string
public DirectoryIterator::valid(): bool
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • GlobIterator::__construct — glob を使うディレクトリを作成する
  • GlobIterator::count — ディレクトリやファイルの数を取得する


glob を使うディレクトリを作成する

  • ≪ GlobIterator
  • GlobIterator::count ≫
  • PHP Manual
  • GlobIterator
  • glob を使うディレクトリを作成する

GlobIterator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

GlobIterator::__construct — glob を使うディレクトリを作成する

説明

public GlobIterator::__construct(string $pattern, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO)

glob 式から新しいディレクトリイテレータを作成します。

パラメータ

pattern

glob() 関数に渡すパターン

flags

オプションのフラグ。 FilesystemIterator 定数のビットマスクとなります。

エラー / 例外

directory が存在しない場合に UnexpectedValueException をスローします。

directory が空文字列の場合に ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | directory が空文字列の場合に ValueError をスローするようになりました。 これより前のバージョンでは、 RuntimeException をスローしていました。

例

例1 GlobIterator の例

<?php
$iterator = new GlobIterator('*.dll', FilesystemIterator::KEY_AS_FILENAME);

if (!$iterator->count()) {
echo 'No matches';
} else {
$n = 0;

printf("Matched %d item(s)\r\n", $iterator->count());

foreach ($iterator as $item) {
printf("[%d] %s\r\n", ++$n, $iterator->key());
}
}
?>

上の例の出力は、 たとえば以下のようになります。

Matched 2 item(s)
[1] php5ts.dll
[2] php_gd2.dll

参考

  • DirectoryIterator::__construct() - パスから新規ディレクトリイテレータを生成する
  • GlobIterator::count() - ディレクトリやファイルの数を取得する
  • glob() - パターンにマッチするパス名を探す


ディレクトリやファイルの数を取得する

  • ≪ GlobIterator::__construct
  • InfiniteIterator ≫
  • PHP Manual
  • GlobIterator
  • ディレクトリやファイルの数を取得する

GlobIterator::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

GlobIterator::count — ディレクトリやファイルの数を取得する

説明

public GlobIterator::count(): int

glob 式から見つかったディレクトリやファイルの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

返されたディレクトリやファイルの数を int で返します。

例

例1 GlobIterator::count() の例

<?php
$iterator = new GlobIterator('*.xml');

printf("Matched %d item(s)\r\n", $iterator->count());
?>

上の例の出力は、 たとえば以下のようになります。

Matched 8 item(s)

参考

  • GlobIterator::__construct() - glob を使うディレクトリを作成する
  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える
  • glob() - パターンにマッチするパス名を探す


InfiniteIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

InfiniteIterator は、 他のイテレータを受け取って無限に反復させます。 最後までたどり着いたときに手動で巻き戻す必要はありません。

クラス概要

class InfiniteIterator extends IteratorIterator {
/* メソッド */
public __construct(Iterator $iterator)
public next(): void
/* 継承したメソッド */
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • InfiniteIterator::__construct — InfiniteIterator を作成する
  • InfiniteIterator::next — 内部イテレータを次に移動するか、巻き戻す


InfiniteIterator を作成する

  • ≪ InfiniteIterator
  • InfiniteIterator::next ≫
  • PHP Manual
  • InfiniteIterator
  • InfiniteIterator を作成する

InfiniteIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

InfiniteIterator::__construct — InfiniteIterator を作成する

説明

public InfiniteIterator::__construct(Iterator $iterator)

イテレータから InfiniteIterator を作成します。

パラメータ

iterator

無限に処理し続けるイテレータ。

例

例1 InfiniteIterator::__construct() の例

<?php
$arrayit = new ArrayIterator(array('cat','dog'));
$infinite = new InfiniteIterator($arrayit);
$limit = new LimitIterator($infinite, 0, 7);
foreach($limit as $value)
{
echo "$value\n";
}
?>

上の例の出力は以下となります。

cat
dog
cat
dog
cat
dog
cat

参考

  • InfiniteIterator::next() - 内部イテレータを次に移動するか、巻き戻す


内部イテレータを次に移動するか、巻き戻す

  • ≪ InfiniteIterator::__construct
  • IteratorIterator ≫
  • PHP Manual
  • InfiniteIterator
  • 内部イテレータを次に移動するか、巻き戻す

InfiniteIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

InfiniteIterator::next — 内部イテレータを次に移動するか、巻き戻す

説明

public InfiniteIterator::next(): void

次の要素があるときは、イテレータを次の要素に移動します。 要素がないときは、内部イテレータを開始位置に巻き戻します。

注意:

内部イテレータが空の場合は InfiniteIterator も停止します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • InfiniteIterator::__construct() - InfiniteIterator を作成する


IteratorIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

このイテレータラッパーを使うと、 Traversable なものなら何でもイテレータに変換することができます。 注意すべきなのは、Iterator を実装していない大半のクラスにはそれなりの理由 (Iterator の機能群を完全には提供できないなど) があるということです。 もしそうならば、誤使用を防ぐような方法を提供すべきです、 でなければ、例外や致命的なエラーが起こり得ます。

クラス概要

class IteratorIterator implements OuterIterator {
/* メソッド */
public __construct(Traversable $iterator, ?string $class = null)
public current(): mixed
public getInnerIterator(): ?Iterator
public key(): mixed
public next(): void
public rewind(): void
public valid(): bool
}

注意

注意:

このクラスは、内部のイテレータのメソッドへのアクセスを許可するために、マジックメソッド __call を利用します。

目次

  • IteratorIterator::__construct — traversable な何かからイテレータを作成する
  • IteratorIterator::current — 現在の値を取得する
  • IteratorIterator::getInnerIterator — 内部イテレータを取得する
  • IteratorIterator::key — 現在の要素のキーを取得する
  • IteratorIterator::next — 次の要素に移動する
  • IteratorIterator::rewind — 最初の要素に巻き戻す
  • IteratorIterator::valid — 現在の要素が有効かどうかを調べる


traversable な何かからイテレータを作成する

  • ≪ IteratorIterator
  • IteratorIterator::current ≫
  • PHP Manual
  • IteratorIterator
  • traversable な何かからイテレータを作成する

IteratorIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::__construct — traversable な何かからイテレータを作成する

説明

public IteratorIterator::__construct(Traversable $iterator, ?string $class = null)

traversable な何かからイテレータを作成します。

パラメータ

iterator

traversable なイテレータ。

class

内側のイテレータのために使うクラス名。 これを使うと、与えられたイテレータをラップするために異なるイテレータクラスを指定できます。 デフォルトでは、IteratorIterator を使います。

参考

  • Traversable


現在の値を取得する

  • ≪ IteratorIterator::__construct
  • IteratorIterator::getInnerIterator ≫
  • PHP Manual
  • IteratorIterator
  • 現在の値を取得する

IteratorIterator::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::current — 現在の値を取得する

説明

public IteratorIterator::current(): mixed

現在の要素の値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の値を返します。

参考

  • IteratorIterator::key() - 現在の要素のキーを取得する


内部イテレータを取得する

  • ≪ IteratorIterator::current
  • IteratorIterator::key ≫
  • PHP Manual
  • IteratorIterator
  • 内部イテレータを取得する

IteratorIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::getInnerIterator — 内部イテレータを取得する

説明

public IteratorIterator::getInnerIterator(): ?Iterator

内部イテレータを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

IteratorIterator::__construct() に渡した内部イテレータを返します。 内部イテレータが存在しない場合は、null を返します。

参考

  • Iterator
  • OuterIterator


現在の要素のキーを取得する

  • ≪ IteratorIterator::getInnerIterator
  • IteratorIterator::next ≫
  • PHP Manual
  • IteratorIterator
  • 現在の要素のキーを取得する

IteratorIterator::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::key — 現在の要素のキーを取得する

説明

public IteratorIterator::key(): mixed

現在の要素のキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素のキーを返します。

参考

  • IteratorIterator::current() - 現在の値を取得する


次の要素に移動する

  • ≪ IteratorIterator::key
  • IteratorIterator::rewind ≫
  • PHP Manual
  • IteratorIterator
  • 次の要素に移動する

IteratorIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::next — 次の要素に移動する

説明

public IteratorIterator::next(): void

次の要素に移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • IteratorIterator::rewind() - 最初の要素に巻き戻す
  • IteratorIterator::valid() - 現在の要素が有効かどうかを調べる


最初の要素に巻き戻す

  • ≪ IteratorIterator::next
  • IteratorIterator::valid ≫
  • PHP Manual
  • IteratorIterator
  • 最初の要素に巻き戻す

IteratorIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::rewind — 最初の要素に巻き戻す

説明

public IteratorIterator::rewind(): void

最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • IteratorIterator::next() - 次の要素に移動する
  • IteratorIterator::valid() - 現在の要素が有効かどうかを調べる


現在の要素が有効かどうかを調べる

  • ≪ IteratorIterator::rewind
  • LimitIterator ≫
  • PHP Manual
  • IteratorIterator
  • 現在の要素が有効かどうかを調べる

IteratorIterator::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

IteratorIterator::valid — 現在の要素が有効かどうかを調べる

説明

public IteratorIterator::valid(): bool

現在の要素が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素が有効な場合に true、それ以外の場合に false を返します。

参考

  • iterator_count() - イテレータにある要素をカウントする
  • IteratorIterator::current() - 現在の値を取得する


LimitIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

LimitIterator クラスは、ある Iterator 上の限られたサブセットに対する反復処理を行います。

クラス概要

class LimitIterator extends IteratorIterator {
/* メソッド */
public __construct(Iterator $iterator, int $offset = 0, int $limit = -1)
public current(): mixed
public getPosition(): int
public key(): mixed
public next(): void
public rewind(): void
public seek(int $offset): int
public valid(): bool
/* 継承したメソッド */
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

例

例1 LimitIterator の使用例

<?php

// 限定した処理を行うイテレータを作成します
$fruits = new ArrayIterator(array(
'apple',
'banana',
'cherry',
'damson',
'elderberry'
));

// 最初の三つの果物だけをループ対象とします
foreach (new LimitIterator($fruits, 0, 3) as $fruit) {
var_dump($fruit);
}

echo "\n";

// 三番目の果物から最後までをループ対象とします
// 注意: オフセットは 0 から始まり、0 は apple です
foreach (new LimitIterator($fruits, 2) as $fruit) {
var_dump($fruit);
}

?>

上の例の出力は以下となります。

string(5) "apple"
string(6) "banana"
string(6) "cherry"

string(6) "cherry"
string(6) "damson"
string(10) "elderberry"

目次

  • LimitIterator::__construct — LimitIterator を作成する
  • LimitIterator::current — 現在の要素を取得する
  • LimitIterator::getPosition — 現在の位置を返す
  • LimitIterator::key — 現在のキーを取得する
  • LimitIterator::next — イテレータを前に移動する
  • LimitIterator::rewind — イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek — 与えられた位置に移動する
  • LimitIterator::valid — 現在の要素が有効かどうかをチェックする


LimitIterator を作成する

  • ≪ LimitIterator
  • LimitIterator::current ≫
  • PHP Manual
  • LimitIterator
  • LimitIterator を作成する

LimitIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::__construct — LimitIterator を作成する

説明

public LimitIterator::__construct(Iterator $iterator, int $offset = 0, int $limit = -1)

開始位置 offset と最大数 limit を指定したイテレータ iterator から 新しい LimitIterator を作成します。

パラメータ

iterator

制限したいイテレータ。

offset

オプションの開始位置。

limit

オプションの要素数。

エラー / 例外

offset が 0 未満、 あるいは limit が -1 未満の場合に ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | offset が 0 未満の場合に、ValueError をスローするようになりました。 これより前のバージョンでは、 RuntimeException をスローしていました。
8.0.0 | limit が -1 未満の場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、 RuntimeException をスローしていました。

例

例1 LimitIterator::__construct() の例

<?php
$ait = new ArrayIterator(array('a', 'b', 'c', 'd', 'e'));
$lit = new LimitIterator($ait, 1, 3);
foreach ($lit as $value) {
echo $value . "\n";
}
?>

上の例の出力は以下となります。

b
c
d

参考

  • LimitIterator の例


現在の要素を取得する

  • ≪ LimitIterator::__construct
  • LimitIterator::getPosition ≫
  • PHP Manual
  • LimitIterator
  • 現在の要素を取得する

LimitIterator::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::current — 現在の要素を取得する

説明

public LimitIterator::current(): mixed

内部イテレータの現在の要素を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素、あるいは現在の要素がない場合は null を返します。

参考

  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする


現在の位置を返す

  • ≪ LimitIterator::current
  • LimitIterator::key ≫
  • PHP Manual
  • LimitIterator
  • 現在の位置を返す

LimitIterator::getPosition

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::getPosition — 現在の位置を返す

説明

public LimitIterator::getPosition(): int

内部 Iterator の、ゼロから数えた現在位置を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の位置を返します。

例

例1 LimitIterator::getPosition() の例

<?php
$fruits = array(
'a' => 'apple',
'b' => 'banana',
'c' => 'cherry',
'd' => 'damson',
'e' => 'elderberry'
);
$array_it = new ArrayIterator($fruits);
$limit_it = new LimitIterator($array_it, 2, 3);
foreach ($limit_it as $item) {
echo $limit_it->getPosition() . ' ' . $item . "\n";
}
?>

上の例の出力は以下となります。

2 cherry
3 damson
4 elderberry

参考

  • FilterIterator::key() - 現在のキーを取得する


現在のキーを取得する

  • ≪ LimitIterator::getPosition
  • LimitIterator::next ≫
  • PHP Manual
  • LimitIterator
  • 現在のキーを取得する

LimitIterator::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::key — 現在のキーを取得する

説明

public LimitIterator::key(): mixed

内部イテレータの現在の要素のキーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素のキーを返します。

参考

  • LimitIterator::getPosition() - 現在の位置を返す
  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする


イテレータを前に移動する

  • ≪ LimitIterator::key
  • LimitIterator::rewind ≫
  • PHP Manual
  • LimitIterator
  • イテレータを前に移動する

LimitIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::next — イテレータを前に移動する

説明

public LimitIterator::next(): void

イテレータを前に移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする


イテレータを指定した開始オフセットに巻き戻す

  • ≪ LimitIterator::next
  • LimitIterator::seek ≫
  • PHP Manual
  • LimitIterator
  • イテレータを指定した開始オフセットに巻き戻す

LimitIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::rewind — イテレータを指定した開始オフセットに巻き戻す

説明

public LimitIterator::rewind(): void

イテレータを、LimitIterator::__construct() で指定した開始オフセットに巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::seek() - 与えられた位置に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする


与えられた位置に移動する

  • ≪ LimitIterator::rewind
  • LimitIterator::valid ≫
  • PHP Manual
  • LimitIterator
  • 与えられた位置に移動する

LimitIterator::seek

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::seek — 与えられた位置に移動する

説明

public LimitIterator::seek(int $offset): int

イテレータを、offset で指定したオフセットに移動します。

パラメータ

offset

移動したい位置。

戻り値

移動後のオフセット位置を返します。

エラー / 例外

LimitIterator::__construct() で指定した範囲外の位置を指定した場合は OutOfBoundsException をスローします。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::valid() - 現在の要素が有効かどうかをチェックする


現在の要素が有効かどうかをチェックする

  • ≪ LimitIterator::seek
  • MultipleIterator ≫
  • PHP Manual
  • LimitIterator
  • 現在の要素が有効かどうかをチェックする

LimitIterator::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

LimitIterator::valid — 現在の要素が有効かどうかをチェックする

説明

public LimitIterator::valid(): bool

現在の要素が有効かどうかをチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • LimitIterator::current() - 現在の要素を取得する
  • LimitIterator::key() - 現在のキーを取得する
  • LimitIterator::rewind() - イテレータを指定した開始オフセットに巻き戻す
  • LimitIterator::next() - イテレータを前に移動する
  • LimitIterator::seek() - 与えられた位置に移動する


MultipleIterator クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

アタッチしたすべてのイテレータを順に処理するイテレータです。

クラス概要

class MultipleIterator implements Iterator {
/* 定数 */
public const int MIT_NEED_ANY;
public const int MIT_NEED_ALL;
public const int MIT_KEYS_NUMERIC;
public const int MIT_KEYS_ASSOC;
/* メソッド */
public __construct(int $flags = MultipleIterator::MIT_NEED_ALL | MultipleIterator::MIT_KEYS_NUMERIC)
public attachIterator(Iterator $iterator, string|int|null $info = null): void
public containsIterator(Iterator $iterator): bool
public countIterators(): int
public current(): array
public detachIterator(Iterator $iterator): void
public getFlags(): int
public key(): array
public next(): void
public rewind(): void
public setFlags(int $flags): void
public valid(): bool
}

定義済み定数

MultipleIterator::MIT_NEED_ANY

すべてのサブイテレータが処理可能である必要はありません。

MultipleIterator::MIT_NEED_ALL

すべてのサブイテレータが正しく反復処理できることを要求します。

MultipleIterator::MIT_KEYS_NUMERIC

キーは、サブイテレータの位置から作成されます。

MultipleIterator::MIT_KEYS_ASSOC

キーは、サブイテレータに関連付けられた情報から作成されます。

目次

  • MultipleIterator::attachIterator — イテレータの情報をアタッチする
  • MultipleIterator::__construct — 新しい MultipleIterator を作成する
  • MultipleIterator::containsIterator — イテレータがアタッチされているかどうかを調べる
  • MultipleIterator::countIterators — アタッチされているイテレータインスタンスの数を取得する
  • MultipleIterator::current — 登録されているイテレータインスタンスを取得する
  • MultipleIterator::detachIterator — イテレータをデタッチする
  • MultipleIterator::getFlags — フラグの情報を取得する
  • MultipleIterator::key — 登録されているイテレータインスタンスを取得する
  • MultipleIterator::next — アタッチしているすべてのイテレータインスタンスを次に移動させる
  • MultipleIterator::rewind — アタッチしているすべてのイテレータインスタンスを巻き戻す
  • MultipleIterator::setFlags — フラグを設定する
  • MultipleIterator::valid — サブイテレータの有効性を調べる


イテレータの情報をアタッチする

  • ≪ MultipleIterator
  • MultipleIterator::__construct ≫
  • PHP Manual
  • MultipleIterator
  • イテレータの情報をアタッチする

MultipleIterator::attachIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::attachIterator — イテレータの情報をアタッチする

説明

public MultipleIterator::attachIterator(Iterator $iterator, string|int|null $info = null): void

イテレータの情報をアタッチします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

アタッチする新しいイテレータ。

info

イテレータに関連する情報。 int、string あるいは null でなければなりません。

戻り値

エラー / 例外

iterator が無効な場合、 あるいは info がすでに関連づけられた情報である場合に IllegalValueException をスローします。

参考

  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する


新しい MultipleIterator を作成する

  • ≪ MultipleIterator::attachIterator
  • MultipleIterator::containsIterator ≫
  • PHP Manual
  • MultipleIterator
  • 新しい MultipleIterator を作成する

MultipleIterator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::__construct — 新しい MultipleIterator を作成する

説明

public MultipleIterator::__construct(int $flags = MultipleIterator::MIT_NEED_ALL | MultipleIterator::MIT_KEYS_NUMERIC)

新しい MultipleIterator を作成します。

パラメータ

flags

設定するフラグ。 フラグ定数 を参照ください。

  • MultipleIterator::MIT_NEED_ALL あるいは MultipleIterator::MIT_NEED_ANY
  • MultipleIterator::MIT_KEYS_NUMERIC あるいは MultipleIterator::MIT_KEYS_ASSOC

デフォルトは MultipleIterator::MIT_NEED_ALL|MultipleIterator::MIT_KEYS_NUMERIC です。

例

例1 MultipleIterator の反復処理

<?php
$people = new ArrayIterator(array('John', 'Jane', 'Jack', 'Judy'));
$roles = new ArrayIterator(array('Developer', 'Scrum Master', 'Project Owner'));

$team = new MultipleIterator($flags);
$team->attachIterator($people, 'person');
$team->attachIterator($roles, 'role');

foreach ($team as $member) {
print_r($member);
}
?>

$flags = MIT_NEED_ALL|MIT_KEYS_NUMERIC の場合の出力

Array
(
    [0] => John
    [1] => Developer
)
Array
(
    [0] => Jane
    [1] => Scrum Master
)
Array
(
    [0] => Jack
    [1] => Project Owner
)

$flags = MIT_NEED_ANY|MIT_KEYS_NUMERIC の場合の出力

Array
(
    [0] => John
    [1] => Developer
)
Array
(
    [0] => Jane
    [1] => Scrum Master
)
Array
(
    [0] => Jack
    [1] => Project Owner
)
Array
(
    [0] => Judy
    [1] =>
)

$flags = MIT_NEED_ALL|MIT_KEYS_ASSOC の場合の出力

Array
(
    [person] => John
    [role] => Developer
)
Array
(
    [person] => Jane
    [role] => Scrum Master
)
Array
(
    [person] => Jack
    [role] => Project Owner
)

$flags = MIT_NEED_ANY|MIT_KEYS_ASSOC の場合の出力

Array
(
    [person] => John
    [role] => Developer
)
Array
(
    [person] => Jane
    [role] => Scrum Master
)
Array
(
    [person] => Jack
    [role] => Project Owner
)
Array
(
    [person] => Judy
    [role] =>
)

参考

  • フラグ定数
  • MultipleIterator::valid() - サブイテレータの有効性を調べる


イテレータがアタッチされているかどうかを調べる

  • ≪ MultipleIterator::__construct
  • MultipleIterator::countIterators ≫
  • PHP Manual
  • MultipleIterator
  • イテレータがアタッチされているかどうかを調べる

MultipleIterator::containsIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::containsIterator — イテレータがアタッチされているかどうかを調べる

説明

public MultipleIterator::containsIterator(Iterator $iterator): bool

イテレータがアタッチされているかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

調べたいイタレータ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • MultipleIterator::valid() - サブイテレータの有効性を調べる


アタッチされているイテレータインスタンスの数を取得する

  • ≪ MultipleIterator::containsIterator
  • MultipleIterator::current ≫
  • PHP Manual
  • MultipleIterator
  • アタッチされているイテレータインスタンスの数を取得する

MultipleIterator::countIterators

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::countIterators — アタッチされているイテレータインスタンスの数を取得する

説明

public MultipleIterator::countIterators(): int

アタッチされているイテレータインスタンスの数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

アタッチされているイテレータインスタンスの数を (int で) 返します

参考

  • MultipleIterator::containsIterator() - イテレータがアタッチされているかどうかを調べる


登録されているイテレータインスタンスを取得する

  • ≪ MultipleIterator::countIterators
  • MultipleIterator::detachIterator ≫
  • PHP Manual
  • MultipleIterator
  • 登録されているイテレータインスタンスを取得する

MultipleIterator::current

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::current — 登録されているイテレータインスタンスを取得する

説明

public MultipleIterator::current(): array

登録されているイテレータインスタンスの current() の結果を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

アタッチされている各イテレータの現在の値を含む配列を返します。

エラー / 例外

イテレーターが無効な場合(PHP 8.1.0 以降) には、 RuntimeException が発生します。 モード MIT_NEED_ALL が設定されているときに、 アタッチされているイテレータの中にひとつでも無効なものがあった場合も、 RuntimeException が発生します。また、 キーが null で MIT_KEYS_ASSOC が設定されている場合には IllegalValueException が発生します。

変更履歴

バージョン | 説明
8.1.0 | MultipleIterator::current() が無効なイテレータを使って呼び出された場合に、 RuntimeException をスローするようになりました。 これより前のバージョンでは、false を返していました。

参考

  • MultipleIterator::valid() - サブイテレータの有効性を調べる


イテレータをデタッチする

  • ≪ MultipleIterator::current
  • MultipleIterator::getFlags ≫
  • PHP Manual
  • MultipleIterator
  • イテレータをデタッチする

MultipleIterator::detachIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::detachIterator — イテレータをデタッチする

説明

public MultipleIterator::detachIterator(Iterator $iterator): void

イテレータをデタッチします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

デタッチするイテレータ。

戻り値

値を返しません。

参考

  • MultipleIterator::attachIterator() - イテレータの情報をアタッチする


フラグの情報を取得する

  • ≪ MultipleIterator::detachIterator
  • MultipleIterator::key ≫
  • PHP Manual
  • MultipleIterator
  • フラグの情報を取得する

MultipleIterator::getFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::getFlags — フラグの情報を取得する

説明

public MultipleIterator::getFlags(): int

フラグについての情報を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

フラグについての情報を int で返します。

参考

  • フラグ定数
  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する
  • MultipleIterator::setFlags() - フラグを設定する


登録されているイテレータインスタンスを取得する

  • ≪ MultipleIterator::getFlags
  • MultipleIterator::next ≫
  • PHP Manual
  • MultipleIterator
  • 登録されているイテレータインスタンスを取得する

MultipleIterator::key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::key — 登録されているイテレータインスタンスを取得する

説明

public MultipleIterator::key(): array

登録されているイテレータインスタンスの key() の結果を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

登録されているイテレータインスタンスの配列を返します。

エラー / 例外

イテレータが無効な場合には、RuntimeException をスローします (PHP 8.1.0 以降)。 また、モード MIT_NEED_ALL が設定されているときに、 アタッチされているイテレータの中にひとつでも無効なものがあった場合にも RuntimeException が発生します。

このメソッドを foreach から呼ぶと、 警告 "Illegal type returned" が発生します。

変更履歴

バージョン | 説明
8.1.0 | MultipleIterator::key() が無効なイテレータを使って呼び出された場合に、 RuntimeException をスローするようになりました。 これより前のバージョンでは、false を返していました。

参考

  • MultipleIterator::current() - 登録されているイテレータインスタンスを取得する


アタッチしているすべてのイテレータインスタンスを次に移動させる

  • ≪ MultipleIterator::key
  • MultipleIterator::rewind ≫
  • PHP Manual
  • MultipleIterator
  • アタッチしているすべてのイテレータインスタンスを次に移動させる

MultipleIterator::next

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::next — アタッチしているすべてのイテレータインスタンスを次に移動させる

説明

public MultipleIterator::next(): void

アタッチしているすべてのイテレータインスタンスを次に移動させます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • MultipleIterator::rewind() - アタッチしているすべてのイテレータインスタンスを巻き戻す


アタッチしているすべてのイテレータインスタンスを巻き戻す

  • ≪ MultipleIterator::next
  • MultipleIterator::setFlags ≫
  • PHP Manual
  • MultipleIterator
  • アタッチしているすべてのイテレータインスタンスを巻き戻す

MultipleIterator::rewind

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::rewind — アタッチしているすべてのイテレータインスタンスを巻き戻す

説明

public MultipleIterator::rewind(): void

アタッチしているすべてのイテレータインスタンスを巻き戻します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • MultipleIterator::next() - アタッチしているすべてのイテレータインスタンスを次に移動させる


フラグを設定する

  • ≪ MultipleIterator::rewind
  • MultipleIterator::valid ≫
  • PHP Manual
  • MultipleIterator
  • フラグを設定する

MultipleIterator::setFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::setFlags — フラグを設定する

説明

public MultipleIterator::setFlags(int $flags): void

フラグを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flags

設定するフラグ。 フラグ定数 を参照ください。

戻り値

値を返しません。

参考

  • フラグ定数
  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する
  • MultipleIterator::getFlags() - フラグの情報を取得する


サブイテレータの有効性を調べる

  • ≪ MultipleIterator::setFlags
  • NoRewindIterator ≫
  • PHP Manual
  • MultipleIterator
  • サブイテレータの有効性を調べる

MultipleIterator::valid

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

MultipleIterator::valid — サブイテレータの有効性を調べる

説明

public MultipleIterator::valid(): bool

サブイテレータの有効性を調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

サブイテレータのひとつあるいはすべて (フラグによって異なります) が有効な場合に true、 それ以外の場合に false を返します。

参考

  • MultipleIterator::__construct() - 新しい MultipleIterator を作成する


NoRewindIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

このイテレータは巻き戻しの操作を無視します。 これにより、一部のみを走査する 複数の foreach ループでイテレータを処理することが可能になります。

クラス概要

class NoRewindIterator extends IteratorIterator {
/* メソッド */
public __construct(Iterator $iterator)
public current(): mixed
public key(): mixed
public next(): void
public rewind(): void
public valid(): bool
/* 継承したメソッド */
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • NoRewindIterator::__construct — NoRewindIterator を作成する
  • NoRewindIterator::current — 現在の値を取得する
  • NoRewindIterator::key — 現在のキーを取得する
  • NoRewindIterator::next — 次の要素に移動する
  • NoRewindIterator::rewind — 内部イテレータの巻き戻し操作を阻止する
  • NoRewindIterator::valid — イテレータの有効性を検証する


NoRewindIterator を作成する

  • ≪ NoRewindIterator
  • NoRewindIterator::current ≫
  • PHP Manual
  • NoRewindIterator
  • NoRewindIterator を作成する

NoRewindIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

NoRewindIterator::__construct — NoRewindIterator を作成する

説明

public NoRewindIterator::__construct(Iterator $iterator)

NoRewindIterator を作成します。

パラメータ

iterator

使用するイテレータ。

例

例1 NoRewindIterator::__construct() の例

二番目のループは何も出力しません。 このイテレータは一度しか使えず、巻き戻しされないからです。

<?php
$fruit = array('apple', 'banana', 'cranberry');

$arr = new ArrayObject($fruit);
$it = new NoRewindIterator($arr->getIterator());

echo "Fruit A:\n";
foreach( $it as $item ) {
echo $item . "\n";
}

echo "Fruit B:\n";
foreach( $it as $item ) {
echo $item . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Fruit A:
apple
banana
cranberry
Fruit B:

参考

  • NoRewindIterator::valid() - イテレータの有効性を検証する


現在の値を取得する

  • ≪ NoRewindIterator::__construct
  • NoRewindIterator::key ≫
  • PHP Manual
  • NoRewindIterator
  • 現在の値を取得する

NoRewindIterator::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

NoRewindIterator::current — 現在の値を取得する

説明

public NoRewindIterator::current(): mixed

現在の値を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の値を返します。

参考

  • NoRewindIterator::key() - 現在のキーを取得する


現在のキーを取得する

  • ≪ NoRewindIterator::current
  • NoRewindIterator::next ≫
  • PHP Manual
  • NoRewindIterator
  • 現在のキーを取得する

NoRewindIterator::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

NoRewindIterator::key — 現在のキーを取得する

説明

public NoRewindIterator::key(): mixed

現在のキーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のキーを返します。

参考

  • NoRewindIterator::next() - 次の要素に移動する


次の要素に移動する

  • ≪ NoRewindIterator::key
  • NoRewindIterator::rewind ≫
  • PHP Manual
  • NoRewindIterator
  • 次の要素に移動する

NoRewindIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

NoRewindIterator::next — 次の要素に移動する

説明

public NoRewindIterator::next(): void

次の要素に移動します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • NoRewindIterator::rewind() - 内部イテレータの巻き戻し操作を阻止する


内部イテレータの巻き戻し操作を阻止する

  • ≪ NoRewindIterator::next
  • NoRewindIterator::valid ≫
  • PHP Manual
  • NoRewindIterator
  • 内部イテレータの巻き戻し操作を阻止する

NoRewindIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

NoRewindIterator::rewind — 内部イテレータの巻き戻し操作を阻止する

説明

public NoRewindIterator::rewind(): void

内部イテレータの巻き戻し操作を阻止します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 NoRewindIterator::rewind() の例

この例は、NoRewindIterator オブジェクトで rewind をコールしても何も起こらないことを示します。

<?php
$fruits = array("lemon", "orange", "apple", "pear");

$noRewindIterator = new NoRewindIterator(new ArrayIterator($fruits));

echo $noRewindIterator->current() . "\n";
$noRewindIterator->next();
// イテレータを巻き戻します (何も起こりません)
$noRewindIterator->rewind();
echo $noRewindIterator->current() . "\n";
?>

上の例の出力は以下となります。

lemon
orange


イテレータの有効性を検証する

  • ≪ NoRewindIterator::rewind
  • ParentIterator ≫
  • PHP Manual
  • NoRewindIterator
  • イテレータの有効性を検証する

NoRewindIterator::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

NoRewindIterator::valid — イテレータの有効性を検証する

説明

public NoRewindIterator::valid(): bool

イテレータが有効かどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • NoRewindIterator::getInnerIterator()


ParentIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

これは FilterIterator を継承したクラスで、 RecursiveIteratorIterator を使った再帰的な反復処理をできるようにします。 ただし、子を持つ要素しか表示しません。

クラス概要

class ParentIterator extends RecursiveFilterIterator {
/* メソッド */
public __construct(RecursiveIterator $iterator)
public accept(): bool
public getChildren(): ParentIterator
public hasChildren(): bool
public next(): void
public rewind(): void
/* 継承したメソッド */
public RecursiveFilterIterator::getChildren(): ?RecursiveFilterIterator
public RecursiveFilterIterator::hasChildren(): bool
public FilterIterator::accept(): bool
public FilterIterator::current(): mixed
public FilterIterator::key(): mixed
public FilterIterator::next(): void
public FilterIterator::rewind(): void
public FilterIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • ParentIterator::accept — 受け入れ可能かどうかを調べる
  • ParentIterator::__construct — ParentIterator を作成する
  • ParentIterator::getChildren — ParentIterator に含まれる内部イテレータの子を返す
  • ParentIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかをチェックする
  • ParentIterator::next — イテレータを前に移動する
  • ParentIterator::rewind — イテレータを巻き戻す


受け入れ可能かどうかを調べる

  • ≪ ParentIterator
  • ParentIterator::__construct ≫
  • PHP Manual
  • ParentIterator
  • 受け入れ可能かどうかを調べる

ParentIterator::accept

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ParentIterator::accept — 受け入れ可能かどうかを調べる

説明

public ParentIterator::accept(): bool

現在の要素が子を持っているかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

受け入れ可能な場合に true、それ以外の場合に false を返します。

参考

  • ParentIterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかをチェックする
  • FilterIterator::accept() - イテレータの現在の要素がフィルタを満たすかどうかを調べる


ParentIterator を作成する

  • ≪ ParentIterator::accept
  • ParentIterator::getChildren ≫
  • PHP Manual
  • ParentIterator
  • ParentIterator を作成する

ParentIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ParentIterator::__construct — ParentIterator を作成する

説明

public ParentIterator::__construct(RecursiveIterator $iterator)

イテレータ上に ParentIterator を作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

作成する元となるイテレータ。


ParentIterator に含まれる内部イテレータの子を返す

  • ≪ ParentIterator::__construct
  • ParentIterator::hasChildren ≫
  • PHP Manual
  • ParentIterator
  • ParentIterator に含まれる内部イテレータの子を返す

ParentIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ParentIterator::getChildren — ParentIterator に含まれる内部イテレータの子を返す

説明

public ParentIterator::getChildren(): ParentIterator

ParentIterator に含まれる内部イテレータの子を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトを返します。


内部イテレータの現在の要素が子を持つかどうかをチェックする

  • ≪ ParentIterator::getChildren
  • ParentIterator::next ≫
  • PHP Manual
  • ParentIterator
  • 内部イテレータの現在の要素が子を持つかどうかをチェックする

ParentIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ParentIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかをチェックする

説明

public ParentIterator::hasChildren(): bool

内部イテレータの現在の要素が子を持つかどうかをチェックします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


イテレータを前に移動する

  • ≪ ParentIterator::hasChildren
  • ParentIterator::rewind ≫
  • PHP Manual
  • ParentIterator
  • イテレータを前に移動する

ParentIterator::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ParentIterator::next — イテレータを前に移動する

説明

public ParentIterator::next(): void

イテレータを前に移動します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


イテレータを巻き戻す

  • ≪ ParentIterator::next
  • RecursiveArrayIterator ≫
  • PHP Manual
  • ParentIterator
  • イテレータを巻き戻す

ParentIterator::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ParentIterator::rewind — イテレータを巻き戻す

説明

public ParentIterator::rewind(): void

イテレータを巻き戻します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


RecursiveArrayIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

このイテレータは、ArrayIterator と同じように配列やオブジェクトを反復処理しつつ、 そのキーや値を消去したり書き換えたりすることができます。 さらに、現在のイテレータのエントリを反復処理することも可能です。

クラス概要

class RecursiveArrayIterator extends ArrayIterator implements RecursiveIterator {
/* 継承した定数 */
public const int ArrayIterator::STD_PROP_LIST;
public const int ArrayIterator::ARRAY_AS_PROPS;
/* 定数 */
public const int CHILD_ARRAYS_ONLY;
/* メソッド */
public getChildren(): ?RecursiveArrayIterator
public hasChildren(): bool
/* 継承したメソッド */
public ArrayIterator::__construct(array|object $array = [], int $flags = 0)
public ArrayIterator::append(mixed $value): void
public ArrayIterator::asort(int $flags = SORT_REGULAR): true
public ArrayIterator::count(): int
public ArrayIterator::current(): mixed
public ArrayIterator::getArrayCopy(): array
public ArrayIterator::getFlags(): int
public ArrayIterator::key(): string|int|null
public ArrayIterator::ksort(int $flags = SORT_REGULAR): true
public ArrayIterator::natcasesort(): true
public ArrayIterator::natsort(): true
public ArrayIterator::next(): void
public ArrayIterator::offsetExists(mixed $key): bool
public ArrayIterator::offsetGet(mixed $key): mixed
public ArrayIterator::offsetSet(mixed $key, mixed $value): void
public ArrayIterator::offsetUnset(mixed $key): void
public ArrayIterator::rewind(): void
public ArrayIterator::seek(int $offset): void
public ArrayIterator::serialize(): string
public ArrayIterator::setFlags(int $flags): void
public ArrayIterator::uasort(callable $callback): true
public ArrayIterator::uksort(callable $callback): true
public ArrayIterator::unserialize(string $data): void
public ArrayIterator::valid(): bool
}

定義済み定数

RecursiveArrayIterator フラグ

RecursiveArrayIterator::CHILD_ARRAYS_ONLY

(オブジェクトではなく)配列のみが、再帰的な走査が可能な子を持つと見なす

目次

  • RecursiveArrayIterator::getChildren — 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す
  • RecursiveArrayIterator::hasChildren — 現在のエントリが配列あるいはオブジェクトであるかどうかを返す


現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

  • ≪ RecursiveArrayIterator
  • RecursiveArrayIterator::hasChildren ≫
  • PHP Manual
  • RecursiveArrayIterator
  • 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

RecursiveArrayIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveArrayIterator::getChildren — 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す

説明

public RecursiveArrayIterator::getChildren(): ?RecursiveArrayIterator

現在のエントリのイテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のエントリが配列あるいはオブジェクトである場合に、 そのイテレータを返します。 失敗時に null を返します。

エラー / 例外

現在のエントリが配列やオブジェクトではない場合に InvalidArgumentException をスローします。

例

例1 RecursiveArrayIterator::getChildren() の例

<?php
$fruits = array("a" => "lemon", "b" => "orange", array("a" => "apple", "p" => "pear"));

$iterator = new RecursiveArrayIterator($fruits);

while ($iterator->valid()) {

if ($iterator->hasChildren()) {
// すべての子を表示します
foreach ($iterator->getChildren() as $key => $value) {
echo $key . ' : ' . $value . "\n";
}
} else {
echo "No children.\n";
}

$iterator->next();
}
?>

上の例の出力は以下となります。

No children.
No children.
a : apple
p : pear

参考

  • RecursiveArrayIterator::hasChildren() - 現在のエントリが配列あるいはオブジェクトであるかどうかを返す


現在のエントリが配列あるいはオブジェクトであるかどうかを返す

  • ≪ RecursiveArrayIterator::getChildren
  • RecursiveCachingIterator ≫
  • PHP Manual
  • RecursiveArrayIterator
  • 現在のエントリが配列あるいはオブジェクトであるかどうかを返す

RecursiveArrayIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveArrayIterator::hasChildren — 現在のエントリが配列あるいはオブジェクトであるかどうかを返す

説明

public RecursiveArrayIterator::hasChildren(): bool

現在のエントリが配列あるいはオブジェクトであるかどうか、つまり RecursiveArrayIterator::getChildren() でイテレータを取得できるかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のエントリが配列あるいはオブジェクトである場合に true、 それ以外の場合に false を返します。

例

例1 RecursiveArrayIterator::hasChildren() の例

<?php
$fruits = array("a" => "lemon", "b" => "orange", array("a" => "apple", "p" => "pear"));

$iterator = new RecursiveArrayIterator($fruits);

while ($iterator->valid()) {

// 子を持つかどうかを調べます
if ($iterator->hasChildren()) {
// すべての子を表示します
foreach ($iterator->getChildren() as $key => $value) {
echo $key . ' : ' . $value . "\n";
}
} else {
echo "No children.\n";
}

$iterator->next();
}
?>

上の例の出力は以下となります。

No children.
No children.
a : apple
p : pear

参考

  • RecursiveArrayIterator::getChildren() - 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す


RecursiveCachingIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

...

クラス概要

class RecursiveCachingIterator extends CachingIterator implements RecursiveIterator {
/* 継承した定数 */
public const int CachingIterator::CALL_TOSTRING;
public const int CachingIterator::CATCH_GET_CHILD;
public const int CachingIterator::TOSTRING_USE_KEY;
public const int CachingIterator::TOSTRING_USE_CURRENT;
public const int CachingIterator::TOSTRING_USE_INNER;
public const int CachingIterator::FULL_CACHE;
/* メソッド */
public __construct(Iterator $iterator, int $flags = RecursiveCachingIterator::CALL_TOSTRING)
public getChildren(): ?RecursiveCachingIterator
public hasChildren(): bool
/* 継承したメソッド */
public CachingIterator::count(): int
public CachingIterator::current(): mixed
public CachingIterator::getCache(): array
public CachingIterator::getFlags(): int
public CachingIterator::hasNext(): bool
public CachingIterator::key(): scalar
public CachingIterator::next(): void
public CachingIterator::offsetExists(string $key): bool
public CachingIterator::offsetGet(string $key): mixed
public CachingIterator::offsetSet(string $key, mixed $value): void
public CachingIterator::offsetUnset(string $key): void
public CachingIterator::rewind(): void
public CachingIterator::setFlags(int $flags): void
public CachingIterator::__toString(): string
public CachingIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • RecursiveCachingIterator::__construct — コンストラクタ
  • RecursiveCachingIterator::getChildren — 内部イテレータの子を RecursiveCachingIterator として返す
  • RecursiveCachingIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかチェックする


コンストラクタ

  • ≪ RecursiveCachingIterator
  • RecursiveCachingIterator::getChildren ≫
  • PHP Manual
  • RecursiveCachingIterator
  • コンストラクタ

RecursiveCachingIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveCachingIterator::__construct — コンストラクタ

説明

public RecursiveCachingIterator::__construct(Iterator $iterator, int $flags = RecursiveCachingIterator::CALL_TOSTRING)

iterator で渡されたイテレータをもとにして新しい RecursiveCachingIterator を作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

使用するイテレータ。

flags

フラグ。CALL_TOSTRING は RecursiveCachingIterator::__toString() をすべての要素に対してコールします (デフォルト)。 CATCH_GET_CHILD は 子を取得しようとしたときに発生する例外を捕捉します。

参考

  • CachingIterator::__construct() - 新しい CachingIterator オブジェクトを作成する


内部イテレータの子を RecursiveCachingIterator として返す

  • ≪ RecursiveCachingIterator::__construct
  • RecursiveCachingIterator::hasChildren ≫
  • PHP Manual
  • RecursiveCachingIterator
  • 内部イテレータの子を RecursiveCachingIterator として返す

RecursiveCachingIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveCachingIterator::getChildren — 内部イテレータの子を RecursiveCachingIterator として返す

説明

public RecursiveCachingIterator::getChildren(): ?RecursiveCachingIterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

内部イテレータの子を RecursiveCachingIterator として返します。 子が存在しない場合、null を返します。


内部イテレータの現在の要素が子を持つかどうかチェックする

  • ≪ RecursiveCachingIterator::getChildren
  • RecursiveCallbackFilterIterator ≫
  • PHP Manual
  • RecursiveCachingIterator
  • 内部イテレータの現在の要素が子を持つかどうかチェックする

RecursiveCachingIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveCachingIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかチェックする

説明

public RecursiveCachingIterator::hasChildren(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

内部イテレータが子を持つ場合に true、そうでない場合に false を返します。


RecursiveCallbackFilterIterator クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

クラス概要

class RecursiveCallbackFilterIterator extends CallbackFilterIterator implements RecursiveIterator {
/* メソッド */
public __construct(RecursiveIterator $iterator, callable $callback)
public getChildren(): RecursiveCallbackFilterIterator
public hasChildren(): bool
/* 継承したメソッド */
public CallbackFilterIterator::accept(): bool
public FilterIterator::accept(): bool
public FilterIterator::current(): mixed
public FilterIterator::key(): mixed
public FilterIterator::next(): void
public FilterIterator::rewind(): void
public FilterIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

例

コールバックは、三つの引数を受け付けなければなりません。 それぞれ、現在のアイテム、現在のキー、そしてイテレータを表します。

例1 利用可能なコールバック引数

<?php

/**
* RecursiveCallbackFilterIterator 用のコールバック
*
* @param $current 現在のアイテムの値
* @param $key 現在のアイテムのキー
* @param $iterator フィルタリングするイテレータ
* @return boolean 現在のアイテムを受け付ける場合は TRUE、それ以外の場合は FALSE
*/
function my_callback($current, $key, $iterator) {
// ここにフィルタリングのコードを書きます
}

?>

再帰イテレータのフィルタリングにはふたつの条件があります。 まず最初は再帰を許可するかどうかです。コールバック関数は、 現在のイテレータのアイテムが子を持つときに true を返さなければなりません。 二番目の条件が通常のフィルタリング条件で、 次の例におけるファイルサイズや拡張子のチェックがこれにあたります。

例2 再帰コールバックの基本例

<?php

$dir = new RecursiveDirectoryIterator(__DIR__);

// 大きなファイル ( > 100MB) をフィルタします
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
// 再帰を許可します
if ($iterator->hasChildren()) {
return TRUE;
}
// 巨大なファイルのチェックをします
if ($current->isFile() && $current->getSize() > 104857600) {
return TRUE;
}
return FALSE;
});

foreach (new RecursiveIteratorIterator($files) as $file) {
echo $file->getPathname() . PHP_EOL;
}

?>

目次

  • RecursiveCallbackFilterIterator::__construct — RecursiveIterator から RecursiveCallbackFilterIterator を作成する
  • RecursiveCallbackFilterIterator::getChildren — RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveCallbackFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる


RecursiveIterator から RecursiveCallbackFilterIterator を作成する

  • ≪ RecursiveCallbackFilterIterator
  • RecursiveCallbackFilterIterator::getChildren ≫
  • PHP Manual
  • RecursiveCallbackFilterIterator
  • RecursiveIterator から RecursiveCallbackFilterIterator を作成する

RecursiveCallbackFilterIterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

RecursiveCallbackFilterIterator::__construct — RecursiveIterator から RecursiveCallbackFilterIterator を作成する

説明

public RecursiveCallbackFilterIterator::__construct(RecursiveIterator $iterator, callable $callback)

callback でフィルタリングした RecursiveIterator を作って、 どのアイテムを受け付けてどれを拒否するかを決めます。

パラメータ

iterator

フィルタリングする再帰イテレータ。

callback

コールバック。現在のアイテムを受け付ける場合に true、 拒否する場合に false を返します。 例 を参照ください。

任意の callable 値を指定できます。

参考

  • RecursiveCallbackFilterIterator の例
  • RecursiveCallbackFilterIterator::getChildren() - RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveCallbackFilteriterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる


RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

  • ≪ RecursiveCallbackFilterIterator::__construct
  • RecursiveCallbackFilterIterator::hasChildren ≫
  • PHP Manual
  • RecursiveCallbackFilterIterator
  • RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

RecursiveCallbackFilterIterator::getChildren

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

RecursiveCallbackFilterIterator::getChildren — RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す

説明

public RecursiveCallbackFilterIterator::getChildren(): RecursiveCallbackFilterIterator

内部イテレータのフィルタリングした子を取得します。

RecursiveCallbackFilterIterator::hasChildren() を使って、取得できる子があるかどうかを調べなければなりません。

パラメータ

この関数にはパラメータはありません。

戻り値

子を含む RecursiveCallbackFilterIterator を返します。

参考

  • RecursiveCallbackFilterIterator の例
  • RecursiveCallbackFilterIterator::__construct() - RecursiveIterator から RecursiveCallbackFilterIterator を作成する
  • RecursiveCallbackFilteriterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる


内部イテレータの現在の要素が子を持つかどうかを調べる

  • ≪ RecursiveCallbackFilterIterator::getChildren
  • RecursiveDirectoryIterator ≫
  • PHP Manual
  • RecursiveCallbackFilterIterator
  • 内部イテレータの現在の要素が子を持つかどうかを調べる

RecursiveCallbackFilterIterator::hasChildren

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

RecursiveCallbackFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる

説明

public RecursiveCallbackFilterIterator::hasChildren(): bool

現在の要素が子を持つときに true、それ以外の場合に false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素が子を持つときに true、それ以外の場合に false を返します。

例

例1 RecursiveCallbackFilterIterator::hasChildren() の基本的な使用例

<?php

$dir = new RecursiveDirectoryIterator(__DIR__);

// 再帰的に XML ファイルを処理します
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
// ディレクトリの再帰処理を許可します
if ($iterator->hasChildren()) {
return TRUE;
}
// XML ファイルかどうかを調べます
if (!strcasecmp($current->getExtension(), 'xml')) {
return TRUE;
}
return FALSE;
});

?>

参考

  • RecursiveCallbackFilterIterator の例
  • RecursiveCallbackFilterIterator::__construct() - RecursiveIterator から RecursiveCallbackFilterIterator を作成する
  • RecursiveCallbackFilteriterator::getChildren() - RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す


RecursiveDirectoryIterator クラス

(PHP 5, PHP 7, PHP 8)

はじめに

RecursiveDirectoryIterator は、 ファイルシステムのディレクトリを再帰的に反復処理するためのインターフェイスです。

クラス概要

class RecursiveDirectoryIterator extends FilesystemIterator implements RecursiveIterator {
/* 継承した定数 */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* メソッド */
public __construct(string $directory, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO)
public getChildren(): RecursiveDirectoryIterator
public getSubPath(): string
public getSubPathname(): string
public hasChildren(bool $allowLinks = false): bool
public key(): string
public next(): void
public rewind(): void
/* 継承したメソッド */
public FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public FilesystemIterator::getFlags(): int
public FilesystemIterator::key(): string
public FilesystemIterator::next(): void
public FilesystemIterator::rewind(): void
public FilesystemIterator::setFlags(int $flags): void
public DirectoryIterator::current(): mixed
public DirectoryIterator::getBasename(string $suffix = ""): string
public DirectoryIterator::getExtension(): string
public DirectoryIterator::getFilename(): string
public DirectoryIterator::isDot(): bool
public DirectoryIterator::key(): mixed
public DirectoryIterator::next(): void
public DirectoryIterator::rewind(): void
public DirectoryIterator::seek(int $offset): void
public DirectoryIterator::__toString(): string
public DirectoryIterator::valid(): bool
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • RecursiveDirectoryIterator::__construct — RecursiveDirectoryIterator を作成する
  • RecursiveDirectoryIterator::getChildren — ディレクトリであれば、現在のエントリに対するイテレータを返す
  • RecursiveDirectoryIterator::getSubPath — サブパスを取得する
  • RecursiveDirectoryIterator::getSubPathname — サブパスと名前を取得する
  • RecursiveDirectoryIterator::hasChildren — 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す
  • RecursiveDirectoryIterator::key — 現在のディレクトリエントリのパスとファイル名を返す
  • RecursiveDirectoryIterator::next — 次のエントリに移動する
  • RecursiveDirectoryIterator::rewind — ディレクトリを最初に巻き戻す


RecursiveDirectoryIterator を作成する

  • ≪ RecursiveDirectoryIterator
  • RecursiveDirectoryIterator::getChildren ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • RecursiveDirectoryIterator を作成する

RecursiveDirectoryIterator::__construct

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

RecursiveDirectoryIterator::__construct — RecursiveDirectoryIterator を作成する

説明

public RecursiveDirectoryIterator::__construct(string $directory, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO)

指定したパス directory の RecursiveDirectoryIterator() を作成します。

パラメータ

directory

反復処理の対象となるディレクトリのパス。

flags

フラグを指定して、いくつかのメソッドの振る舞いを変更することができます。 フラグの一覧は FilesystemIterator の定義済み定数 にあります。フラグは、あとから FilesystemIterator::setFlags() で設定することもできます。

エラー / 例外

directory が存在しない場合に、 UnexpectedValueException をスローします。

directory が空文字列の場合に、 ValueError をスローします。

変更履歴

バージョン | 説明
8.0.0 | directory が空文字列の場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、 RuntimeException をスローしていました。

例

例1 RecursiveDirectoryIterator の例

<?php

$directory = '/tmp';

$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory));

$it->rewind();
while($it->valid()) {

if (!$it->isDot()) {
echo 'SubPathName: ' . $it->getSubPathName() . "\n";
echo 'SubPath: ' . $it->getSubPath() . "\n";
echo 'Key: ' . $it->key() . "\n\n";
}

$it->next();
}

?>

上の例の出力は、 たとえば以下のようになります。

SubPathName: fruit/apple.xml
SubPath:     fruit
Key:         /tmp/fruit/apple.xml

SubPathName: stuff.xml
SubPath:
Key:         /tmp/stuff.xml

SubPathName: veggies/carrot.xml
SubPath:     veggies
Key:         /tmp/veggies/carrot.xml

参考

  • FilesystemIterator::__construct() - 新しい filesystem イテレータを作成する
  • RecursiveIteratorIterator::__construct() - RecursiveIteratorIterator を作成する
  • FilesystemIterator の定義済み定数


ディレクトリであれば、現在のエントリに対するイテレータを返す

  • ≪ RecursiveDirectoryIterator::__construct
  • RecursiveDirectoryIterator::getSubPath ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • ディレクトリであれば、現在のエントリに対するイテレータを返す

RecursiveDirectoryIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveDirectoryIterator::getChildren — ディレクトリであれば、現在のエントリに対するイテレータを返す

説明

public RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイル名、ファイル情報、あるいは $this のどれかを、 設定されているフラグによって返します。 FilesystemIterator の定数 も参照ください。


サブパスを取得する

  • ≪ RecursiveDirectoryIterator::getChildren
  • RecursiveDirectoryIterator::getSubPathname ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • サブパスを取得する

RecursiveDirectoryIterator::getSubPath

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveDirectoryIterator::getSubPath — サブパスを取得する

説明

public RecursiveDirectoryIterator::getSubPath(): string

コンストラクタで渡されたディレクトリのサブパスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

サブパス(サブディレクトリ) を返します。

例

例1 getSubPath() の例

$directory = '/tmp';

$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory));

foreach ($it as $file) {
echo 'SubPathName: ' . $it->getSubPathName() . "\n";
echo 'SubPath: ' . $it->getSubPath() . "\n\n";
}

上の例の出力は、 たとえば以下のようになります。

SubPathName: fruit/apple.xml
     SubPath:     fruit

     SubPathName: stuff.xml
     SubPath:

     SubPathName: veggies/carrot.xml
     SubPath:     veggies

参考

  • RecursiveDirectoryIterator::getSubPathName() - サブパスと名前を取得する
  • RecursiveDirectoryIterator::key() - 現在のディレクトリエントリのパスとファイル名を返す


サブパスと名前を取得する

  • ≪ RecursiveDirectoryIterator::getSubPath
  • RecursiveDirectoryIterator::hasChildren ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • サブパスと名前を取得する

RecursiveDirectoryIterator::getSubPathname

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveDirectoryIterator::getSubPathname — サブパスと名前を取得する

説明

public RecursiveDirectoryIterator::getSubPathname(): string

サブパスとファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

サブパス (サブディレクトリ) とファイル名を返します。

例

例1 getSubPathname() の例

$directory = '/tmp';

$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory));

foreach ($it as $file) {
echo 'SubPathName: ' . $it->getSubPathname() . "\n";
echo 'SubPath: ' . $it->getSubPath() . "\n\n";
}

上の例の出力は、 たとえば以下のようになります。

SubPathName: fruit/apple.xml
     SubPath:     fruit

     SubPathName: stuff.xml
     SubPath:

     SubPathName: veggies/carrot.xml
     SubPath:     veggies

参考

  • RecursiveDirectoryIterator::getSubPath() - サブパスを取得する
  • RecursiveDirectoryIterator::key() - 現在のディレクトリエントリのパスとファイル名を返す


現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す

  • ≪ RecursiveDirectoryIterator::getSubPathname
  • RecursiveDirectoryIterator::key ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す

RecursiveDirectoryIterator::hasChildren

(PHP 5, PHP 7, PHP 8)

RecursiveDirectoryIterator::hasChildren — 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す

説明

public RecursiveDirectoryIterator::hasChildren(bool $allowLinks = false): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

allowLinks

戻り値

現在のエントリが ('.' や '..' 以外の) ディレクトリであるかどうかを返します。


現在のディレクトリエントリのパスとファイル名を返す

  • ≪ RecursiveDirectoryIterator::hasChildren
  • RecursiveDirectoryIterator::next ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • 現在のディレクトリエントリのパスとファイル名を返す

RecursiveDirectoryIterator::key

(PHP 5, PHP 7, PHP 8)

RecursiveDirectoryIterator::key — 現在のディレクトリエントリのパスとファイル名を返す

説明

public RecursiveDirectoryIterator::key(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のディレクトリエントリのパスとファイル名を返します。


次のエントリに移動する

  • ≪ RecursiveDirectoryIterator::key
  • RecursiveDirectoryIterator::rewind ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • 次のエントリに移動する

RecursiveDirectoryIterator::next

(PHP 5, PHP 7, PHP 8)

RecursiveDirectoryIterator::next — 次のエントリに移動する

説明

public RecursiveDirectoryIterator::next(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


ディレクトリを最初に巻き戻す

  • ≪ RecursiveDirectoryIterator::next
  • RecursiveFilterIterator ≫
  • PHP Manual
  • RecursiveDirectoryIterator
  • ディレクトリを最初に巻き戻す

RecursiveDirectoryIterator::rewind

(PHP 5, PHP 7, PHP 8)

RecursiveDirectoryIterator::rewind — ディレクトリを最初に巻き戻す

説明

public RecursiveDirectoryIterator::rewind(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


RecursiveFilterIterator クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

この抽象イテレータは、不要な値を RecursiveIterator から取り除きます。 このクラスを継承して、独自のフィルタを実装することができます。 RecursiveFilterIterator::accept() は、サブクラスで必ず実装しなければなりません。

クラス概要

abstract class RecursiveFilterIterator extends FilterIterator implements RecursiveIterator {
/* メソッド */
public __construct(RecursiveIterator $iterator)
public getChildren(): ?RecursiveFilterIterator
public hasChildren(): bool
/* 継承したメソッド */
public FilterIterator::accept(): bool
public FilterIterator::current(): mixed
public FilterIterator::key(): mixed
public FilterIterator::next(): void
public FilterIterator::rewind(): void
public FilterIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • RecursiveFilterIterator::__construct — RecursiveIterator から RecursiveFilterIterator を作成する
  • RecursiveFilterIterator::getChildren — RecursiveFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる


RecursiveIterator から RecursiveFilterIterator を作成する

  • ≪ RecursiveFilterIterator
  • RecursiveFilterIterator::getChildren ≫
  • PHP Manual
  • RecursiveFilterIterator
  • RecursiveIterator から RecursiveFilterIterator を作成する

RecursiveFilterIterator::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveFilterIterator::__construct — RecursiveIterator から RecursiveFilterIterator を作成する

説明

public RecursiveFilterIterator::__construct(RecursiveIterator $iterator)

RecursiveIterator から RecursiveFilterIterator を作成します。

パラメータ

iterator

フィルタリングする RecursiveIterator。

例

例1 RecursiveFilterIterator() の基本例

<?php
class TestsOnlyFilter extends RecursiveFilterIterator {
public function accept() {
// 現在のアイテムが再帰可能であるか、値が
// "test" で始まる場合にのみ許可します
return $this->hasChildren() || (strpos($this->current(), "test") !== FALSE);
}
}

$array = array("test1", array("taste2", "test3", "test4"), "test5");
$iterator = new RecursiveArrayIterator($array);
$filter = new TestsOnlyFilter($iterator);

foreach(new RecursiveIteratorIterator($filter) as $key => $value)
{
echo $value . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

test1
test3
test4
test5

例2 RecursiveFilterIterator() の例

<?php
class StartsWithFilter extends RecursiveFilterIterator {

protected $word;

public function __construct(RecursiveIterator $rit, $word) {
$this->word = $word;
parent::__construct($rit);
}

public function accept() {
return $this->hasChildren() OR strpos($this->current(), $this->word) === 0;
}

public function getChildren() {
return new self($this->getInnerIterator()->getChildren(), $this->word);
}
}

$array = array("test1", array("taste2", "test3", "test4"), "test5");
$iterator = new RecursiveArrayIterator($array);
$filter = new StartsWithFilter($iterator, "test");

foreach(new RecursiveIteratorIterator($filter) as $key => $value)
{
echo $value . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

test1
test3
test4
test5

参考

  • RecursiveFilterIterator::getChildren() - RecursiveFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveFilterIterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる
  • FilterIterator::accept() - イテレータの現在の要素がフィルタを満たすかどうかを調べる


RecursiveFilterIterator に含まれる内部イテレータの子を返す

  • ≪ RecursiveFilterIterator::__construct
  • RecursiveFilterIterator::hasChildren ≫
  • PHP Manual
  • RecursiveFilterIterator
  • RecursiveFilterIterator に含まれる内部イテレータの子を返す

RecursiveFilterIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveFilterIterator::getChildren — RecursiveFilterIterator に含まれる内部イテレータの子を返す

説明

public RecursiveFilterIterator::getChildren(): ?RecursiveFilterIterator

RecursiveFilterIterator に含まれる内部イテレータの子を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

RecursiveFilterIterator に含まれる内部イテレータの子を返します。

参考

  • RecursiveFilterIterator::hasChildren() - 内部イテレータの現在の要素が子を持つかどうかを調べる
  • RecursiveIterator::getChildren() - 現在のエントリのイテレータを返す


内部イテレータの現在の要素が子を持つかどうかを調べる

  • ≪ RecursiveFilterIterator::getChildren
  • RecursiveIteratorIterator ≫
  • PHP Manual
  • RecursiveFilterIterator
  • 内部イテレータの現在の要素が子を持つかどうかを調べる

RecursiveFilterIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveFilterIterator::hasChildren — 内部イテレータの現在の要素が子を持つかどうかを調べる

説明

public RecursiveFilterIterator::hasChildren(): bool

内部イテレータの現在の要素が子を持つかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

内部イテレータが子を持つ場合に true、それ以外の場合に false を返します。

参考

  • RecursiveFilterIterator::getChildren() - RecursiveFilterIterator に含まれる内部イテレータの子を返す
  • RecursiveIterator::hasChildren() - 現在のエントリのイテレータを作れるかどうかを返す


RecursiveIteratorIterator クラス

(PHP 5, PHP 7, PHP 8)

はじめに

再帰的なイテレータの反復処理に使用します。

クラス概要

class RecursiveIteratorIterator implements OuterIterator {
/* 定数 */
public const int LEAVES_ONLY;
public const int SELF_FIRST;
public const int CHILD_FIRST;
public const int CATCH_GET_CHILD;
/* メソッド */
public __construct(Traversable $iterator, int $mode = RecursiveIteratorIterator::LEAVES_ONLY, int $flags = 0)
public beginChildren(): void
public beginIteration(): void
public callGetChildren(): ?RecursiveIterator
public callHasChildren(): bool
public current(): mixed
public endChildren(): void
public endIteration(): void
public getDepth(): int
public getInnerIterator(): RecursiveIterator
public getMaxDepth(): int|false
public getSubIterator(?int $level = null): ?RecursiveIterator
public key(): mixed
public next(): void
public nextElement(): void
public rewind(): void
public setMaxDepth(int $maxDepth = -1): void
public valid(): bool
}

定義済み定数

RecursiveIteratorIterator::LEAVES_ONLY

RecursiveIteratorIterator::SELF_FIRST

RecursiveIteratorIterator::CHILD_FIRST

RecursiveIteratorIterator::CATCH_GET_CHILD

目次

  • RecursiveIteratorIterator::beginChildren — 子を開始する
  • RecursiveIteratorIterator::beginIteration — 反復処理を開始する
  • RecursiveIteratorIterator::callGetChildren — 子を取得する
  • RecursiveIteratorIterator::callHasChildren — 子を持つかどうかを調べる
  • RecursiveIteratorIterator::__construct — RecursiveIteratorIterator を作成する
  • RecursiveIteratorIterator::current — 現在の要素の値にアクセスする
  • RecursiveIteratorIterator::endChildren — 子を終了する
  • RecursiveIteratorIterator::endIteration — 反復処理を終了する
  • RecursiveIteratorIterator::getDepth — 再帰的なイテレーションにおける現在の深さを取得する
  • RecursiveIteratorIterator::getInnerIterator — 内部イテレータを取得する
  • RecursiveIteratorIterator::getMaxDepth — 最大の深さを取得する
  • RecursiveIteratorIterator::getSubIterator — 現在の有効なサブイテレータを取得する
  • RecursiveIteratorIterator::key — 現在のキーにアクセスする
  • RecursiveIteratorIterator::next — 次の要素に移動する
  • RecursiveIteratorIterator::nextElement — 次の要素
  • RecursiveIteratorIterator::rewind — トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す
  • RecursiveIteratorIterator::setMaxDepth — 最大の深さを設定する
  • RecursiveIteratorIterator::valid — 現在の位置が有効かどうかをチェックする


子を開始する

  • ≪ RecursiveIteratorIterator
  • RecursiveIteratorIterator::beginIteration ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を開始する

RecursiveIteratorIterator::beginChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::beginChildren — 子を開始する

説明

public RecursiveIteratorIterator::beginChildren(): void

RecursiveIteratorIterator::getChildren() と、それに関連する RecursiveIteratorIterator::rewind() をコールした後でコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


反復処理を開始する

  • ≪ RecursiveIteratorIterator::beginChildren
  • RecursiveIteratorIterator::callGetChildren ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 反復処理を開始する

RecursiveIteratorIterator::beginIteration

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::beginIteration — 反復処理を開始する

説明

public RecursiveIteratorIterator::beginIteration(): void

反復処理が始まるとき (最初に RecursiveIteratorIterator::rewind() がコールされた後) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


子を取得する

  • ≪ RecursiveIteratorIterator::beginIteration
  • RecursiveIteratorIterator::callHasChildren ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を取得する

RecursiveIteratorIterator::callGetChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::callGetChildren — 子を取得する

説明

public RecursiveIteratorIterator::callGetChildren(): ?RecursiveIterator

現在の要素の子を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時に RecursiveIterator() を返します。 失敗時に null を返します。


子を持つかどうかを調べる

  • ≪ RecursiveIteratorIterator::callGetChildren
  • RecursiveIteratorIterator::__construct ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を持つかどうかを調べる

RecursiveIteratorIterator::callHasChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::callHasChildren — 子を持つかどうかを調べる

説明

public RecursiveIteratorIterator::callHasChildren(): bool

各要素に対して、子を持っているかどうかを調べるためにコールします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

要素に子があるかどうかを返します。


RecursiveIteratorIterator を作成する

  • ≪ RecursiveIteratorIterator::callHasChildren
  • RecursiveIteratorIterator::current ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • RecursiveIteratorIterator を作成する

RecursiveIteratorIterator::__construct

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

RecursiveIteratorIterator::__construct — RecursiveIteratorIterator を作成する

説明

public RecursiveIteratorIterator::__construct(Traversable $iterator, int $mode = RecursiveIteratorIterator::LEAVES_ONLY, int $flags = 0)

RecursiveIterator から RecursiveIteratorIterator を作成します。

パラメータ

iterator

作成する元となるイテレータ。 RecursiveIterator あるいは IteratorAggregate。

mode

オプションのモード。これらの値が指定できます。

  • RecursiveIteratorIterator::LEAVES_ONLY - デフォルト。イテレーションで葉ノードだけを取り上げます。
  • RecursiveIteratorIterator::SELF_FIRST - イテレーションで葉と親を (親から先に) 取り上げます。
  • RecursiveIteratorIterator::CHILD_FIRST - イテレーションで葉と親を (葉から先に) 取り上げます。

flags

オプションのフラグ。指定できる値は RecursiveIteratorIterator::CATCH_GET_CHILD で、RecursiveIteratorIterator::getChildren() のコール時にスローされた例外を無視します。

例

例1 RecursiveIteratorIterator の反復処理

<?php
$array = array(
array(
array(
array(
'leaf-0-0-0-0',
'leaf-0-0-0-1'
),
'leaf-0-0-0'
),
array(
array(
'leaf-0-1-0-0',
'leaf-0-1-0-1'
),
'leaf-0-1-0'
),
'leaf-0-0'
)
);

$iterator = new RecursiveIteratorIterator(
new RecursiveArrayIterator($array),
$mode
);
foreach ($iterator as $key => $leaf) {
echo "$key => $leaf", PHP_EOL;
}
?>

$mode = RecursiveIteratorIterator::LEAVES_ONLY の場合の出力

0 => leaf-0-0-0-0
1 => leaf-0-0-0-1
0 => leaf-0-0-0
0 => leaf-0-1-0-0
1 => leaf-0-1-0-1
0 => leaf-0-1-0
0 => leaf-0-0

$mode = RecursiveIteratorIterator::SELF_FIRST の場合の出力

0 => Array
0 => Array
0 => Array
0 => leaf-0-0-0-0
1 => leaf-0-0-0-1
1 => leaf-0-0-0
1 => Array
0 => Array
0 => leaf-0-1-0-0
1 => leaf-0-1-0-1
1 => leaf-0-1-0
2 => leaf-0-0

$mode = RecursiveIteratorIterator::CHILD_FIRST の場合の出力

0 => leaf-0-0-0-0
1 => leaf-0-0-0-1
0 => Array
1 => leaf-0-0-0
0 => Array
0 => leaf-0-1-0-0
1 => leaf-0-1-0-1
0 => Array
1 => leaf-0-1-0
1 => Array
2 => leaf-0-0
0 => Array


現在の要素の値にアクセスする

  • ≪ RecursiveIteratorIterator::__construct
  • RecursiveIteratorIterator::endChildren ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在の要素の値にアクセスする

RecursiveIteratorIterator::current

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::current — 現在の要素の値にアクセスする

説明

public RecursiveIteratorIterator::current(): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の値を返します。


子を終了する

  • ≪ RecursiveIteratorIterator::current
  • RecursiveIteratorIterator::endIteration ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 子を終了する

RecursiveIteratorIterator::endChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::endChildren — 子を終了する

説明

public RecursiveIteratorIterator::endChildren(): void

そのレベルの再帰処理が終了したときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


反復処理を終了する

  • ≪ RecursiveIteratorIterator::endChildren
  • RecursiveIteratorIterator::getDepth ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 反復処理を終了する

RecursiveIteratorIterator::endIteration

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::endIteration — 反復処理を終了する

説明

public RecursiveIteratorIterator::endIteration(): void

反復処理が終了したとき (RecursiveIteratorIterator::valid() が最初に false を返したとき) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


再帰的なイテレーションにおける現在の深さを取得する

  • ≪ RecursiveIteratorIterator::endIteration
  • RecursiveIteratorIterator::getInnerIterator ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 再帰的なイテレーションにおける現在の深さを取得する

RecursiveIteratorIterator::getDepth

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::getDepth — 再帰的なイテレーションにおける現在の深さを取得する

説明

public RecursiveIteratorIterator::getDepth(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

再帰的なイテレーションにおける現在の深さを返します。


内部イテレータを取得する

  • ≪ RecursiveIteratorIterator::getDepth
  • RecursiveIteratorIterator::getMaxDepth ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 内部イテレータを取得する

RecursiveIteratorIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::getInnerIterator — 内部イテレータを取得する

説明

public RecursiveIteratorIterator::getInnerIterator(): RecursiveIterator

現在アクティブなサブイテレータを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在アクティブなサブイテレータを返します。


最大の深さを取得する

  • ≪ RecursiveIteratorIterator::getInnerIterator
  • RecursiveIteratorIterator::getSubIterator ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 最大の深さを取得する

RecursiveIteratorIterator::getMaxDepth

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::getMaxDepth — 最大の深さを取得する

説明

public RecursiveIteratorIterator::getMaxDepth(): int|false

許可される最大の深さを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

許可される最大の深さ、あるいは無制限の場合に false を返します。

参考

  • RecursiveIteratorIterator::setMaxDepth() - 最大の深さを設定する


現在の有効なサブイテレータを取得する

  • ≪ RecursiveIteratorIterator::getMaxDepth
  • RecursiveIteratorIterator::key ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在の有効なサブイテレータを取得する

RecursiveIteratorIterator::getSubIterator

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::getSubIterator — 現在の有効なサブイテレータを取得する

説明

public RecursiveIteratorIterator::getSubIterator(?int $level = null): ?RecursiveIterator
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

level

戻り値

成功時に、現在の有効なサブイテレータを返します。 失敗時に null を返します。

変更履歴

バージョン | 説明
8.0.0 | level は、nullable になりました。


現在のキーにアクセスする

  • ≪ RecursiveIteratorIterator::getSubIterator
  • RecursiveIteratorIterator::next ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在のキーにアクセスする

RecursiveIteratorIterator::key

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::key — 現在のキーにアクセスする

説明

public RecursiveIteratorIterator::key(): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のキーを返します。


次の要素に移動する

  • ≪ RecursiveIteratorIterator::key
  • RecursiveIteratorIterator::nextElement ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 次の要素に移動する

RecursiveIteratorIterator::next

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::next — 次の要素に移動する

説明

public RecursiveIteratorIterator::next(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


次の要素

  • ≪ RecursiveIteratorIterator::next
  • RecursiveIteratorIterator::rewind ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 次の要素

RecursiveIteratorIterator::nextElement

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::nextElement — 次の要素

説明

public RecursiveIteratorIterator::nextElement(): void

次の要素が利用可能となったときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す

  • ≪ RecursiveIteratorIterator::nextElement
  • RecursiveIteratorIterator::setMaxDepth ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す

RecursiveIteratorIterator::rewind

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::rewind — トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す

説明

public RecursiveIteratorIterator::rewind(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


最大の深さを設定する

  • ≪ RecursiveIteratorIterator::rewind
  • RecursiveIteratorIterator::valid ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 最大の深さを設定する

RecursiveIteratorIterator::setMaxDepth

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIteratorIterator::setMaxDepth — 最大の深さを設定する

説明

public RecursiveIteratorIterator::setMaxDepth(int $maxDepth = -1): void

許可される最大の深さを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

maxDepth

許可される最大の深さ。-1 を指定すると無制限にできます。

戻り値

値を返しません。

エラー / 例外

maxDepth が -1 より小さい場合に例外が発生します。


現在の位置が有効かどうかをチェックする

  • ≪ RecursiveIteratorIterator::setMaxDepth
  • RecursiveRegexIterator ≫
  • PHP Manual
  • RecursiveIteratorIterator
  • 現在の位置が有効かどうかをチェックする

RecursiveIteratorIterator::valid

(PHP 5, PHP 7, PHP 8)

RecursiveIteratorIterator::valid — 現在の位置が有効かどうかをチェックする

説明

public RecursiveIteratorIterator::valid(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の位置が有効な場合に true、そうでない場合に false を返します。


RecursiveRegexIterator クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

この再帰イテレータは、別の再帰イテレータを正規表現でフィルタリングすることができます。

クラス概要

class RecursiveRegexIterator extends RegexIterator implements RecursiveIterator {
/* 継承した定数 */
public const int RegexIterator::USE_KEY;
public const int RegexIterator::INVERT_MATCH;
public const int RegexIterator::MATCH;
public const int RegexIterator::GET_MATCH;
public const int RegexIterator::ALL_MATCHES;
public const int RegexIterator::SPLIT;
public const int RegexIterator::REPLACE;
/* 継承したプロパティ */
public ?string $replacement = null;
/* メソッド */
public __construct(
RecursiveIterator $iterator,
string $pattern,
int $mode = RecursiveRegexIterator::MATCH,
int $flags = 0,
int $pregFlags = 0
)
public getChildren(): RecursiveRegexIterator
public hasChildren(): bool
/* 継承したメソッド */
public RegexIterator::accept(): bool
public RegexIterator::getFlags(): int
public RegexIterator::getMode(): int
public RegexIterator::getPregFlags(): int
public RegexIterator::getRegex(): string
public RegexIterator::setFlags(int $flags): void
public RegexIterator::setMode(int $mode): void
public RegexIterator::setPregFlags(int $pregFlags): void
public FilterIterator::accept(): bool
public FilterIterator::current(): mixed
public FilterIterator::key(): mixed
public FilterIterator::next(): void
public FilterIterator::rewind(): void
public FilterIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

目次

  • RecursiveRegexIterator::__construct — 新しい RecursiveRegexIterator を作成する
  • RecursiveRegexIterator::getChildren — 現在のエントリのイテレータを返す
  • RecursiveRegexIterator::hasChildren — 現在のエントリのイテレータが取得可能かどうかを返す


新しい RecursiveRegexIterator を作成する

  • ≪ RecursiveRegexIterator
  • RecursiveRegexIterator::getChildren ≫
  • PHP Manual
  • RecursiveRegexIterator
  • 新しい RecursiveRegexIterator を作成する

RecursiveRegexIterator::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RecursiveRegexIterator::__construct — 新しい RecursiveRegexIterator を作成する

説明

public RecursiveRegexIterator::__construct(
RecursiveIterator $iterator,
string $pattern,
int $mode = RecursiveRegexIterator::MATCH,
int $flags = 0,
int $pregFlags = 0
)

新しい正規表現イテレータを作成します。

パラメータ

iterator

この正規表現フィルタを適用するイテレータ。

pattern

マッチさせる正規表現。

mode

操作モード。モードの一覧は RegexIterator::setMode() を参照ください。

flags

特殊なフラグ。フラグの一覧は RegexIterator::setFlags() を参照ください。

pregFlags

正規表現フラグ。これらのフラグは操作モードに依存します。

RegexIterator preg_flags
操作モード | 使用可能なフラグ
RecursiveRegexIterator::ALL_MATCHES | preg_match_all() を参照ください。
RecursiveRegexIterator::GET_MATCH | preg_match() を参照ください。
RecursiveRegexIterator::MATCH | preg_match() を参照ください。
RecursiveRegexIterator::REPLACE | なし。
RecursiveRegexIterator::SPLIT | preg_split() を参照ください。

例

例1 RecursiveRegexIterator::__construct() の例

'test' で始まるすべての文字列を取り出す新しい RegexIterator を作成します。

<?php
$rArrayIterator = new RecursiveArrayIterator(array('test1', array('tet3', 'test4', 'test5')));
$rRegexIterator = new RecursiveRegexIterator($rArrayIterator, '/^test/',
RecursiveRegexIterator::ALL_MATCHES);

foreach ($rRegexIterator as $key1 => $value1) {

if ($rRegexIterator->hasChildren()) {

// すべての子を表示します
echo "Children: ";
foreach ($rRegexIterator->getChildren() as $key => $value) {
echo $value . " ";
}
echo "\n";
} else {
echo "No children\n";
}

}
?>

上の例の出力は、 たとえば以下のようになります。

No children
Children: test4 test5

参考

  • preg_match() - 正規表現によるマッチングを行う
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する


現在のエントリのイテレータを返す

  • ≪ RecursiveRegexIterator::__construct
  • RecursiveRegexIterator::hasChildren ≫
  • PHP Manual
  • RecursiveRegexIterator
  • 現在のエントリのイテレータを返す

RecursiveRegexIterator::getChildren

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RecursiveRegexIterator::getChildren — 現在のエントリのイテレータを返す

説明

public RecursiveRegexIterator::getChildren(): RecursiveRegexIterator

現在のエントリのイテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

内部イテレータで反復処理が可能な場合に、現在のエントリのイテレータを返します。

エラー / 例外

現在のエントリが内部イテレータによる反復処理が可能なものでない場合に InvalidArgumentException をスローします。

例

例1 RecursiveRegexIterator::getChildren() の例

<?php
$rArrayIterator = new RecursiveArrayIterator(array('test1', array('tet3', 'test4', 'test5')));
$rRegexIterator = new RecursiveRegexIterator($rArrayIterator, '/^test/',
RecursiveRegexIterator::ALL_MATCHES);

foreach ($rRegexIterator as $key1 => $value1) {

if ($rRegexIterator->hasChildren()) {

// すべての子を表示します
echo "Children: ";
foreach ($rRegexIterator->getChildren() as $key => $value) {
echo $value . " ";
}
echo "\n";
} else {
echo "No children\n";
}

}
?>

上の例の出力は以下となります。

No children
Children: test4 test5

参考

  • RecursiveRegexIterator::hasChildren() - 現在のエントリのイテレータが取得可能かどうかを返す


現在のエントリのイテレータが取得可能かどうかを返す

  • ≪ RecursiveRegexIterator::getChildren
  • RecursiveTreeIterator ≫
  • PHP Manual
  • RecursiveRegexIterator
  • 現在のエントリのイテレータが取得可能かどうかを返す

RecursiveRegexIterator::hasChildren

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RecursiveRegexIterator::hasChildren — 現在のエントリのイテレータが取得可能かどうかを返す

説明

public RecursiveRegexIterator::hasChildren(): bool

現在のエントリのイテレータが取得可能かどうかを返すこのイテレータは RecursiveRegexIterator::getChildren() で取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のエントリのイテレータが取得可能な場合に true、それ以外の場合に false を返します。

例

例1 RecursiveRegexIterator::hasChildren() の例

<?php
$rArrayIterator = new RecursiveArrayIterator(array('test1', array('tet3', 'test4', 'test5')));
$rRegexIterator = new RecursiveRegexIterator($rArrayIterator, '/^test/',
RecursiveRegexIterator::ALL_MATCHES);

foreach ($rRegexIterator as $value) {
var_dump($rRegexIterator->hasChildren());
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • RecursiveRegexIterator::getChildren() - 現在のエントリのイテレータを返す


RecursiveTreeIterator クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

はじめに

RecursiveIterator を反復処理し、ASCII グラフィックツリーを生成します。

クラス概要

class RecursiveTreeIterator extends RecursiveIteratorIterator {
/* 継承した定数 */
public const int RecursiveIteratorIterator::LEAVES_ONLY;
public const int RecursiveIteratorIterator::SELF_FIRST;
public const int RecursiveIteratorIterator::CHILD_FIRST;
public const int RecursiveIteratorIterator::CATCH_GET_CHILD;
/* 定数 */
public const int BYPASS_CURRENT;
public const int BYPASS_KEY;
public const int PREFIX_LEFT;
public const int PREFIX_MID_HAS_NEXT = 1;
public const int PREFIX_MID_LAST = 2;
public const int PREFIX_END_HAS_NEXT = 3;
public const int PREFIX_END_LAST = 4;
public const int PREFIX_RIGHT = 5;
/* メソッド */
public __construct(
RecursiveIterator|IteratorAggregate $iterator,
int $flags = RecursiveTreeIterator::BYPASS_KEY,
int $cachingIteratorFlags = CachingIterator::CATCH_GET_CHILD,
int $mode = RecursiveTreeIterator::SELF_FIRST
)
public beginChildren(): void
public beginIteration(): RecursiveIterator
public callGetChildren(): RecursiveIterator
public callHasChildren(): bool
public current(): mixed
public endChildren(): void
public endIteration(): void
public getEntry(): string
public getPostfix(): string
public getPrefix(): string
public key(): mixed
public next(): void
public nextElement(): void
public rewind(): void
public setPostfix(string $postfix): void
public setPrefixPart(int $part, string $value): void
public valid(): bool
/* 継承したメソッド */
public RecursiveIteratorIterator::beginChildren(): void
public RecursiveIteratorIterator::beginIteration(): void
public RecursiveIteratorIterator::callGetChildren(): ?RecursiveIterator
public RecursiveIteratorIterator::callHasChildren(): bool
public RecursiveIteratorIterator::current(): mixed
public RecursiveIteratorIterator::endChildren(): void
public RecursiveIteratorIterator::endIteration(): void
public RecursiveIteratorIterator::getDepth(): int
public RecursiveIteratorIterator::getInnerIterator(): RecursiveIterator
public RecursiveIteratorIterator::getMaxDepth(): int|false
public RecursiveIteratorIterator::getSubIterator(?int $level = null): ?RecursiveIterator
public RecursiveIteratorIterator::key(): mixed
public RecursiveIteratorIterator::next(): void
public RecursiveIteratorIterator::nextElement(): void
public RecursiveIteratorIterator::rewind(): void
public RecursiveIteratorIterator::setMaxDepth(int $maxDepth = -1): void
public RecursiveIteratorIterator::valid(): bool
}

定義済み定数

RecursiveTreeIterator::BYPASS_CURRENT

RecursiveTreeIterator::BYPASS_KEY

RecursiveTreeIterator::PREFIX_LEFT

RecursiveTreeIterator::PREFIX_MID_HAS_NEXT

RecursiveTreeIterator::PREFIX_MID_LAST

RecursiveTreeIterator::PREFIX_END_HAS_NEXT

RecursiveTreeIterator::PREFIX_END_LAST

RecursiveTreeIterator::PREFIX_RIGHT

目次

  • RecursiveTreeIterator::beginChildren — 子を開始する
  • RecursiveTreeIterator::beginIteration — 反復処理を開始する
  • RecursiveTreeIterator::callGetChildren — 子を取得する
  • RecursiveTreeIterator::callHasChildren — 子を持っているかどうかを調べる
  • RecursiveTreeIterator::__construct — RecursiveTreeIterator を作成する
  • RecursiveTreeIterator::current — 現在の要素を取得する
  • RecursiveTreeIterator::endChildren — 子を終了する
  • RecursiveTreeIterator::endIteration — 反復処理を終了する
  • RecursiveTreeIterator::getEntry — 現在のエントリを取得する
  • RecursiveTreeIterator::getPostfix — 接尾辞を取得する
  • RecursiveTreeIterator::getPrefix — 接頭辞を取得する
  • RecursiveTreeIterator::key — 現在の要素のキーを取得する
  • RecursiveTreeIterator::next — 次の要素に移動する
  • RecursiveTreeIterator::nextElement — 次の要素
  • RecursiveTreeIterator::rewind — イテレータを巻き戻す
  • RecursiveTreeIterator::setPostfix — postfix を設定する
  • RecursiveTreeIterator::setPrefixPart — 接頭辞の部分を設定する
  • RecursiveTreeIterator::valid — 有効性を調べる


子を開始する

  • ≪ RecursiveTreeIterator
  • RecursiveTreeIterator::beginIteration ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を開始する

RecursiveTreeIterator::beginChildren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::beginChildren — 子を開始する

説明

public RecursiveTreeIterator::beginChildren(): void

一段下がるときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


反復処理を開始する

  • ≪ RecursiveTreeIterator::beginChildren
  • RecursiveTreeIterator::callGetChildren ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 反復処理を開始する

RecursiveTreeIterator::beginIteration

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::beginIteration — 反復処理を開始する

説明

public RecursiveTreeIterator::beginIteration(): RecursiveIterator

反復処理を開始するとき (最初に RecursiveTreeIterator::rewind() がコールされた後) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

RecursiveIterator を返します。


子を取得する

  • ≪ RecursiveTreeIterator::beginIteration
  • RecursiveTreeIterator::callHasChildren ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を取得する

RecursiveTreeIterator::callGetChildren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::callGetChildren — 子を取得する

説明

public RecursiveTreeIterator::callGetChildren(): RecursiveIterator

現在の要素の子を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

RecursiveIterator を返します。


子を持っているかどうかを調べる

  • ≪ RecursiveTreeIterator::callGetChildren
  • RecursiveTreeIterator::__construct ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を持っているかどうかを調べる

RecursiveTreeIterator::callHasChildren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::callHasChildren — 子を持っているかどうかを調べる

説明

public RecursiveTreeIterator::callHasChildren(): bool

各要素が子を持っているかどうかを調べるときにコールします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

子がある場合に true、それ以外の場合に false を返します。


RecursiveTreeIterator を作成する

  • ≪ RecursiveTreeIterator::callHasChildren
  • RecursiveTreeIterator::current ≫
  • PHP Manual
  • RecursiveTreeIterator
  • RecursiveTreeIterator を作成する

RecursiveTreeIterator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::__construct — RecursiveTreeIterator を作成する

説明

public RecursiveTreeIterator::__construct(
RecursiveIterator|IteratorAggregate $iterator,
int $flags = RecursiveTreeIterator::BYPASS_KEY,
int $cachingIteratorFlags = CachingIterator::CATCH_GET_CHILD,
int $mode = RecursiveTreeIterator::SELF_FIRST
)

新しい RecursiveTreeIterator を、指定した再帰イテレータから作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

iterator

RecursiveIterator あるいは IteratorAggregate。

flags

フラグを指定して一部のメソッドの振る舞いを変更することができます。 フラグの一覧は RecursiveTreeIterator の定義済み定数 にあります。

caching_it_flags

内部的に使う RecursiveCachingIterator の振る舞いを変更するフラグ。

mode

内部的に使う RecursiveIteratorIterator の振る舞いを変更するフラグ。


現在の要素を取得する

  • ≪ RecursiveTreeIterator::__construct
  • RecursiveTreeIterator::endChildren ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 現在の要素を取得する

RecursiveTreeIterator::current

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::current — 現在の要素を取得する

説明

public RecursiveTreeIterator::current(): mixed

接頭辞と接尾辞をつけた現在の要素を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

接頭辞と接尾辞をつけた現在の要素を返します。


子を終了する

  • ≪ RecursiveTreeIterator::current
  • RecursiveTreeIterator::endIteration ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 子を終了する

RecursiveTreeIterator::endChildren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::endChildren — 子を終了する

説明

public RecursiveTreeIterator::endChildren(): void

一段下の再帰処理が終了したときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


反復処理を終了する

  • ≪ RecursiveTreeIterator::endChildren
  • RecursiveTreeIterator::getEntry ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 反復処理を終了する

RecursiveTreeIterator::endIteration

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::endIteration — 反復処理を終了する

説明

public RecursiveTreeIterator::endIteration(): void

反復処理が終了したとき (RecursiveTreeIterator::valid() が最初に false を返したとき) にコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


現在のエントリを取得する

  • ≪ RecursiveTreeIterator::endIteration
  • RecursiveTreeIterator::getPostfix ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 現在のエントリを取得する

RecursiveTreeIterator::getEntry

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::getEntry — 現在のエントリを取得する

説明

public RecursiveTreeIterator::getEntry(): string

現在の要素から作ったツリーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素から作ったツリーを返します。


接尾辞を取得する

  • ≪ RecursiveTreeIterator::getEntry
  • RecursiveTreeIterator::getPrefix ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 接尾辞を取得する

RecursiveTreeIterator::getPostfix

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::getPostfix — 接尾辞を取得する

説明

public RecursiveTreeIterator::getPostfix(): string

現在の要素の後に置く文字列を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の後に置く文字列を返します。


接頭辞を取得する

  • ≪ RecursiveTreeIterator::getPostfix
  • RecursiveTreeIterator::key ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 接頭辞を取得する

RecursiveTreeIterator::getPrefix

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::getPrefix — 接頭辞を取得する

説明

public RecursiveTreeIterator::getPrefix(): string

現在の要素の前に置く文字列を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の前に置く文字列を返します。


現在の要素のキーを取得する

  • ≪ RecursiveTreeIterator::getPrefix
  • RecursiveTreeIterator::next ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 現在の要素のキーを取得する

RecursiveTreeIterator::key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::key — 現在の要素のキーを取得する

説明

public RecursiveTreeIterator::key(): mixed

接頭辞と接尾辞をつけた現在のキーを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

接頭辞と接尾辞をつけた現在のキーを返します。


次の要素に移動する

  • ≪ RecursiveTreeIterator::key
  • RecursiveTreeIterator::nextElement ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 次の要素に移動する

RecursiveTreeIterator::next

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::next — 次の要素に移動する

説明

public RecursiveTreeIterator::next(): void

次の要素に移動します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


次の要素

  • ≪ RecursiveTreeIterator::next
  • RecursiveTreeIterator::rewind ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 次の要素

RecursiveTreeIterator::nextElement

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::nextElement — 次の要素

説明

public RecursiveTreeIterator::nextElement(): void

次の要素が利用可能となったときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


イテレータを巻き戻す

  • ≪ RecursiveTreeIterator::nextElement
  • RecursiveTreeIterator::setPostfix ≫
  • PHP Manual
  • RecursiveTreeIterator
  • イテレータを巻き戻す

RecursiveTreeIterator::rewind

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::rewind — イテレータを巻き戻す

説明

public RecursiveTreeIterator::rewind(): void

トップレベルの内部イテレータの最初の要素にイテレータを巻き戻します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


postfix を設定する

  • ≪ RecursiveTreeIterator::rewind
  • RecursiveTreeIterator::setPrefixPart ≫
  • PHP Manual
  • RecursiveTreeIterator
  • postfix を設定する

RecursiveTreeIterator::setPostfix

(PHP 5 >= 5.5.3, PHP 7, PHP 8)

RecursiveTreeIterator::setPostfix — postfix を設定する

説明

public RecursiveTreeIterator::setPostfix(string $postfix): void

RecursiveTreeIterator::getPostfix() で使われる postfix を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

postfix

戻り値

値を返しません。


接頭辞の部分を設定する

  • ≪ RecursiveTreeIterator::setPostfix
  • RecursiveTreeIterator::valid ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 接頭辞の部分を設定する

RecursiveTreeIterator::setPrefixPart

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::setPrefixPart — 接頭辞の部分を設定する

説明

public RecursiveTreeIterator::setPrefixPart(int $part, string $value): void

グラフィックツリーで使う接頭辞を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

part

RecursiveTreeIterator::PREFIX_* 定数のいずれか。

value

part で指定した接頭辞に代入する値。

戻り値

値を返しません。


有効性を調べる

  • ≪ RecursiveTreeIterator::setPrefixPart
  • RegexIterator ≫
  • PHP Manual
  • RecursiveTreeIterator
  • 有効性を調べる

RecursiveTreeIterator::valid

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

RecursiveTreeIterator::valid — 有効性を調べる

説明

public RecursiveTreeIterator::valid(): bool

現在位置が有効かどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

現在位置が有効な場合に true、それ以外の場合に false を返します。


RegexIterator クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

このイテレータを使うと、別のイテレータを正規表現でフィルタリングすることができます。

クラス概要

class RegexIterator extends FilterIterator {
/* 定数 */
public const int USE_KEY;
public const int INVERT_MATCH;
public const int MATCH;
public const int GET_MATCH;
public const int ALL_MATCHES;
public const int SPLIT;
public const int REPLACE;
/* プロパティ */
public ?string $replacement = null;
/* メソッド */
public __construct(
Iterator $iterator,
string $pattern,
int $mode = RegexIterator::MATCH,
int $flags = 0,
int $pregFlags = 0
)
public accept(): bool
public getFlags(): int
public getMode(): int
public getPregFlags(): int
public getRegex(): string
public setFlags(int $flags): void
public setMode(int $mode): void
public setPregFlags(int $pregFlags): void
/* 継承したメソッド */
public FilterIterator::accept(): bool
public FilterIterator::current(): mixed
public FilterIterator::key(): mixed
public FilterIterator::next(): void
public FilterIterator::rewind(): void
public FilterIterator::valid(): bool
public IteratorIterator::current(): mixed
public IteratorIterator::getInnerIterator(): ?Iterator
public IteratorIterator::key(): mixed
public IteratorIterator::next(): void
public IteratorIterator::rewind(): void
public IteratorIterator::valid(): bool
}

定義済み定数

RegexIterator の操作モード

RegexIterator::ALL_MATCHES

現在のエントリにマッチするものをすべて返します (preg_match_all() を参照ください)。

RegexIterator::GET_MATCH

現在のエントリに最初にマッチしたものを返します (preg_match() を参照ください)。

RegexIterator::MATCH

現在のエントリに対するマッチ (フィルタ) のみを行います (preg_match() を参照ください)。

RegexIterator::REPLACE

現在のエントリを置換します (preg_replace() を参照ください。まだ完全には実装されていません)。

RegexIterator::SPLIT

現在のエントリで分割した値を返します (preg_split() を参照ください)。

RegexIterator のフラグ

RegexIterator::USE_KEY

特別なフラグ: エントリの値ではなく、キーにマッチさせます。

RegexIterator::INVERT_MATCH

RegexIterator::accept() の戻り値を反転させます。

プロパティ

replacement

目次

  • RegexIterator::accept — 受け入れ状況を取得する
  • RegexIterator::__construct — 新しい RegexIterator を作成する
  • RegexIterator::getFlags — フラグを取得する
  • RegexIterator::getMode — 操作モードを返す
  • RegexIterator::getPregFlags — 正規表現フラグを返す
  • RegexIterator::getRegex — 現在の正規表現を返す
  • RegexIterator::setFlags — フラグを設定する
  • RegexIterator::setMode — 操作モードを設定する
  • RegexIterator::setPregFlags — 正規表現フラグを設定する


受け入れ状況を取得する

  • ≪ RegexIterator
  • RegexIterator::__construct ≫
  • PHP Manual
  • RegexIterator
  • 受け入れ状況を取得する

RegexIterator::accept

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::accept — 受け入れ状況を取得する

説明

public RegexIterator::accept(): bool

(string) RegexIterator::current()
(RegexIterator::USE_KEY
フラグが設定されている場合は RegexIterator::key())
を正規表現でマッチさせます。

パラメータ

この関数にはパラメータはありません。

戻り値

マッチした場合に true、それ以外の場合に false を返します。

例

例1 RegexIterator::accept() の例

この例は、正規表現にマッチするアイテムのみを許可するものです。

<?php
$names = new ArrayIterator(array('Ann', 'Bob', 'Charlie', 'David'));
$filter = new RegexIterator($names, '/^[B-D]/');
foreach ($filter as $name) {
echo $name . PHP_EOL;
}
?>

上の例の出力は以下となります。

Bob
Charlie
David

参考

  • RegexIterator 定数
  • RegexIterator::setFlags() - フラグを設定する


新しい RegexIterator を作成する

  • ≪ RegexIterator::accept
  • RegexIterator::getFlags ≫
  • PHP Manual
  • RegexIterator
  • 新しい RegexIterator を作成する

RegexIterator::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::__construct — 新しい RegexIterator を作成する

説明

public RegexIterator::__construct(
Iterator $iterator,
string $pattern,
int $mode = RegexIterator::MATCH,
int $flags = 0,
int $pregFlags = 0
)

新しい RegexIterator を作成します。これは、正規表現を使って Iterator をフィルタリングします。

パラメータ

iterator

この正規表現フィルタを適用するイテレータ。

pattern

マッチさせる正規表現。

mode

操作モード。モードの一覧は RegexIterator::setMode() を参照ください。

flags

特殊なフラグ。フラグの一覧は RegexIterator::setFlags() を参照ください。

pregFlags

正規表現フラグ。これらのフラグは操作モードに依存します。

RegexIterator preg_flags
操作モード | 使用可能なフラグ
RegexIterator::ALL_MATCHES | preg_match_all() を参照ください。
RegexIterator::GET_MATCH | preg_match() を参照ください。
RegexIterator::MATCH | preg_match() を参照ください。
RegexIterator::REPLACE | なし。
RegexIterator::SPLIT | preg_split() を参照ください。

エラー / 例外

引数 pattern が無効な場合に InvalidArgumentException をスローします。

例

例1 RegexIterator::__construct() の例

'test' で始まるすべての文字列を取り出す新しい RegexIterator を作成します。

<?php
$arrayIterator = new ArrayIterator(array('test 1', 'another test', 'test 123'));
$regexIterator = new RegexIterator($arrayIterator, '/^test/');

foreach ($regexIterator as $value) {
echo $value . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

test 1
test 123

参考

  • preg_match() - 正規表現によるマッチングを行う
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する


フラグを取得する

  • ≪ RegexIterator::__construct
  • RegexIterator::getMode ≫
  • PHP Manual
  • RegexIterator
  • フラグを取得する

RegexIterator::getFlags

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::getFlags — フラグを取得する

説明

public RegexIterator::getFlags(): int

フラグを返します。使用可能なフラグの一覧は RegexIterator::setFlags() を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

設定されているフラグを返します。

例

例1 RegexIterator::getFlags() の例

<?php

$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^test/');
$regexIterator->setFlags(RegexIterator::USE_KEY);

if ($regexIterator->getFlags() & RegexIterator::USE_KEY) {
echo 'Filtering based on the array keys.';
} else {
echo 'Filtering based on the array values.';
}
?>

上の例の出力は以下となります。

Filtering based on the array keys.

参考

  • RegexIterator::setFlags() - フラグを設定する


操作モードを返す

  • ≪ RegexIterator::getFlags
  • RegexIterator::getPregFlags ≫
  • PHP Manual
  • RegexIterator
  • 操作モードを返す

RegexIterator::getMode

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::getMode — 操作モードを返す

説明

public RegexIterator::getMode(): int

操作モードを返します。操作モードの一覧は RegexIterator::setMode() を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

操作モードを返します。

例

例1 RegexIterator::getMode() の例

<?php

$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^[a-z]+/', RegexIterator::GET_MATCH);

$mode = $regexIterator->getMode();
if ($mode & RegexIterator::GET_MATCH) {
echo 'Getting the match for each item.';
} elseif ($mode & RegexIterator::ALL_MATCHES) {
echo 'Getting all matches for each item.';
} elseif ($mode & RegexIterator::MATCH) {
echo 'Getting each item if it matches.';
} elseif ($mode & RegexIterator::SPLIT) {
echo 'Getting split pieces of each.';
}
?>

上の例の出力は以下となります。

Getting the match for each item.

参考

  • RegexIterator::setMode() - 操作モードを設定する


正規表現フラグを返す

  • ≪ RegexIterator::getMode
  • RegexIterator::getRegex ≫
  • PHP Manual
  • RegexIterator
  • 正規表現フラグを返す

RegexIterator::getPregFlags

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::getPregFlags — 正規表現フラグを返す

説明

public RegexIterator::getPregFlags(): int

正規表現フラグを返します。使用可能なフラグの一覧は RegexIterator::__construct() を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

正規表現フラグのビットマスクを返します。

例

例1 RegexIterator::getPregFlags() の例

<?php

$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/\s/', RegexIterator::SPLIT);
$regexIterator->setPregFlags(PREG_SPLIT_NO_EMPTY | PREG_SPLIT_OFFSET_CAPTURE);

if ($regexIterator->getPregFlags() & PREG_SPLIT_NO_EMPTY) {
echo 'Ignoring empty pieces';
} else {
echo 'Not ignoring empty pieces';
}

?>

上の例の出力は以下となります。

Ignoring empty pieces

参考

  • RegexIterator::setPregFlags() - 正規表現フラグを設定する


現在の正規表現を返す

  • ≪ RegexIterator::getPregFlags
  • RegexIterator::setFlags ≫
  • PHP Manual
  • RegexIterator
  • 現在の正規表現を返す

RegexIterator::getRegex

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

RegexIterator::getRegex — 現在の正規表現を返す

説明

public RegexIterator::getRegex(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


フラグを設定する

  • ≪ RegexIterator::getRegex
  • RegexIterator::setMode ≫
  • PHP Manual
  • RegexIterator
  • フラグを設定する

RegexIterator::setFlags

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::setFlags — フラグを設定する

説明

public RegexIterator::setFlags(int $flags): void

フラグを設定します。

パラメータ

flags

設定するフラグ。クラス定数のビットマスクで指定します。

利用できるフラグは次のとおりです。これらのフラグの実際の意味については 定義済みの定数 で説明します。

RegexIterator のフラグ
値 | 定数
1 | RegexIterator::USE_KEY

戻り値

値を返しません。

例

例1 RegexIterator::setFlags() の例

新しい RegexIterator を作成します。これは、キーが 'test' ではじまるすべてのエントリを取り出します。

<?php
$test = array ('str1' => 'test 1', 'teststr2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^test/');
$regexIterator->setFlags(RegexIterator::USE_KEY);

foreach ($regexIterator as $key => $value) {
echo $key . ' => ' . $value . "\n";
}
?>

上の例の出力は以下となります。

teststr2 => another test

参考

  • RegexIterator::getFlags() - フラグを取得する


操作モードを設定する

  • ≪ RegexIterator::setFlags
  • RegexIterator::setPregFlags ≫
  • PHP Manual
  • RegexIterator
  • 操作モードを設定する

RegexIterator::setMode

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::setMode — 操作モードを設定する

説明

public RegexIterator::setMode(int $mode): void

操作モードを設定します。

パラメータ

mode

操作モード。

操作モードは次のとおりです。これらのモードの実際の意味については 定義済みの定数 で説明します。

RegexIterator のモード
値 | 定数
0 | RegexIterator::MATCH
1 | RegexIterator::GET_MATCH
2 | RegexIterator::ALL_MATCHES
3 | RegexIterator::SPLIT
4 | RegexIterator::REPLACE

戻り値

値を返しません。

例

例1 RegexIterator::setMode() の例

<?php
$test = array ('str1' => 'test 1', 'test str2' => 'another test', 'str3' => 'test 123');

$arrayIterator = new ArrayIterator($test);
// 'test ' で始まってその後に 1 桁以上の数字が続くものだけを取り出します
$regexIterator = new RegexIterator($arrayIterator, '/^test (\d+)/');
// 操作モードは、実際の値をマッチした部分で置き換えます
$regexIterator->setMode(RegexIterator::GET_MATCH);

foreach ($regexIterator as $key => $value) {
// print out the matched number(s)
echo $key . ' => ' . $value[1] . PHP_EOL;
}
?>

上の例の出力は、 たとえば以下のようになります。

str1 => 1
str3 => 123

参考

  • RegexIterator::getMode() - 操作モードを返す


正規表現フラグを設定する

  • ≪ RegexIterator::setMode
  • インターフェイス ≫
  • PHP Manual
  • RegexIterator
  • 正規表現フラグを設定する

RegexIterator::setPregFlags

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

RegexIterator::setPregFlags — 正規表現フラグを設定する

説明

public RegexIterator::setPregFlags(int $pregFlags): void

正規表現フラグを設定します。

パラメータ

pregFlags

正規表現フラグ。利用できるフラグの概要は RegexIterator::__construct() を参照ください。

戻り値

値を返しません。

例

例1 RegexIterator::setPregFlags() の例

新しい RegexIterator を作成します。これは、 配列のキーが 'test' で始まるすべてのエントリを取り出します。

<?php
$test = array ('test 1', 'another test', 'test 123');

$arrayIterator = new ArrayIterator($test);
$regexIterator = new RegexIterator($arrayIterator, '/^test/', RegexIterator::GET_MATCH);

$regexIterator->setPregFlags(PREG_OFFSET_CAPTURE);

foreach ($regexIterator as $key => $value) {
var_dump($value);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(4) "test"
    [1]=>
    int(0)
  }
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(4) "test"
    [1]=>
    int(0)
  }
}

参考

  • RegexIterator::getPregFlags() - 正規表現フラグを返す


インターフェイス

目次

  • Countable
  • OuterIterator
  • RecursiveIterator
  • SeekableIterator

SPL にはインターフェイスが用意されています。

定義済みのインターフェイスとクラス も参照ください。

インターフェイス一覧

  • Countable
  • OuterIterator
  • RecursiveIterator
  • SeekableIterator
  • SplObserver
  • SplSubject


Countable インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

Countable を実装したクラスは、 count() 関数で使用することができます。

インターフェイス概要

interface Countable {
/* メソッド */
public count(): int
}

目次

  • Countable::count — オブジェクトの要素数を数える


オブジェクトの要素数を数える

  • ≪ Countable
  • OuterIterator ≫
  • PHP Manual
  • Countable
  • オブジェクトの要素数を数える

Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — オブジェクトの要素数を数える

説明

public Countable::count(): int

このメソッドは、Countable を実装したオブジェクトで count() 関数を使用した際に実行されます。

パラメータ

この関数にはパラメータはありません。

戻り値

要素数を int 型で返します。

注意:

戻り値は int 型にキャストされます。

例

例1 Countable::count() の例

<?php
class myCounter implements Countable {
private $count = 0;
public function count() {
return ++$this->count;
}
}

$counter = new myCounter;

for($i=0; $i<10; ++$i) {
echo "I have been count()ed " . count($counter) . " times\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

I have been count()ed 1 times
I have been count()ed 2 times
I have been count()ed 3 times
I have been count()ed 4 times
I have been count()ed 5 times
I have been count()ed 6 times
I have been count()ed 7 times
I have been count()ed 8 times
I have been count()ed 9 times
I have been count()ed 10 times


OuterIterator インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

OuterIterator を実装したクラスは、 イテレータ群の反復処理に使うことができます。

インターフェイス概要

interface OuterIterator extends Iterator {
/* メソッド */
public getInnerIterator(): ?Iterator
/* 継承したメソッド */
public Iterator::current(): mixed
public Iterator::key(): mixed
public Iterator::next(): void
public Iterator::rewind(): void
public Iterator::valid(): bool
}

目次

  • OuterIterator::getInnerIterator — 現在のエントリの内部イテレータを返す


現在のエントリの内部イテレータを返す

  • ≪ OuterIterator
  • RecursiveIterator ≫
  • PHP Manual
  • OuterIterator
  • 現在のエントリの内部イテレータを返す

OuterIterator::getInnerIterator

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

OuterIterator::getInnerIterator — 現在のエントリの内部イテレータを返す

説明

public OuterIterator::getInnerIterator(): ?Iterator

現在のイテレータエントリの内部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のエントリの内部イテレータが存在する場合、それを返します。 存在しない場合、null を返します。


RecursiveIterator インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

RecursiveIterator を実装したクラスは、 イテレータ群を再帰的に反復処理するときに使うことができます。

インターフェイス概要

interface RecursiveIterator extends Iterator {
/* メソッド */
public getChildren(): ?RecursiveIterator
public hasChildren(): bool
/* 継承したメソッド */
public Iterator::current(): mixed
public Iterator::key(): mixed
public Iterator::next(): void
public Iterator::rewind(): void
public Iterator::valid(): bool
}

目次

  • RecursiveIterator::getChildren — 現在のエントリのイテレータを返す
  • RecursiveIterator::hasChildren — 現在のエントリのイテレータを作れるかどうかを返す


現在のエントリのイテレータを返す

  • ≪ RecursiveIterator
  • RecursiveIterator::hasChildren ≫
  • PHP Manual
  • RecursiveIterator
  • 現在のエントリのイテレータを返す

RecursiveIterator::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIterator::getChildren — 現在のエントリのイテレータを返す

説明

public RecursiveIterator::getChildren(): ?RecursiveIterator

現在のエントリのイテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のエントリのイテレータが存在した場合、それを返します。 存在しない場合、null を返します。

参考

  • RecursiveIterator::hasChildren() - 現在のエントリのイテレータを作れるかどうかを返す


現在のエントリのイテレータを作れるかどうかを返す

  • ≪ RecursiveIterator::getChildren
  • SeekableIterator ≫
  • PHP Manual
  • RecursiveIterator
  • 現在のエントリのイテレータを作れるかどうかを返す

RecursiveIterator::hasChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

RecursiveIterator::hasChildren — 現在のエントリのイテレータを作れるかどうかを返す

説明

public RecursiveIterator::hasChildren(): bool

現在のエントリのイテレータを作れるかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のエントリが反復処理可能な場合に true、それ以外の場合に false を返します。

参考

  • RecursiveIterator::getChildren() - 現在のエントリのイテレータを返す


SeekableIterator インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

Seekable イテレータです。

インターフェイス概要

interface SeekableIterator extends Iterator {
/* メソッド */
public seek(int $offset): void
/* 継承したメソッド */
public Iterator::current(): mixed
public Iterator::key(): mixed
public Iterator::next(): void
public Iterator::rewind(): void
public Iterator::valid(): bool
}

例

例1 基本的な使用法

この例では、SeekableIterator を作成して位置を移動し、無効な位置を扱います。

<?php
class MySeekableIterator implements SeekableIterator {

private $position;

private $array = array(
"first element",
"second element",
"third element",
"fourth element"
);

/* SeekableIterator インターフェイスで必要なメソッド群 */

public function seek($position) {
if (!isset($this->array[$position])) {
throw new OutOfBoundsException("invalid seek position ($position)");
}

$this->position = $position;
}

/* Iterator インターフェイスで必要なメソッド群 */

public function rewind() {
$this->position = 0;
}

public function current() {
return $this->array[$this->position];
}

public function key() {
return $this->position;
}

public function next() {
++$this->position;
}

public function valid() {
return isset($this->array[$this->position]);
}
}

try {

$it = new MySeekableIterator;
echo $it->current(), "\n";

$it->seek(2);
echo $it->current(), "\n";

$it->seek(1);
echo $it->current(), "\n";

$it->seek(10);

} catch (OutOfBoundsException $e) {
echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

first element
third element
second element
invalid seek position (10)

目次

  • SeekableIterator::seek — 位置を移動する


位置を移動する

  • ≪ SeekableIterator
  • 例外 ≫
  • PHP Manual
  • SeekableIterator
  • 位置を移動する

SeekableIterator::seek

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SeekableIterator::seek — 位置を移動する

説明

public SeekableIterator::seek(int $offset): void

イテレータ内の指定した位置に移動します。

パラメータ

offset

移動先の位置。

戻り値

値を返しません。

エラー / 例外

offset に移動できない場合、 OutOfBoundsException をスローするよう実装しなければなりません。

例

例1 SeekableIterator::seek() の例

イテレータの 3 番目の位置に移動します (ArrayIterator は SeekableIterator を実装しています)。

<?php
$array = array("apple", "banana", "cherry", "damson", "elderberry");
$iterator = new ArrayIterator($array);
$iterator->seek(3);
echo $iterator->current();
?>

上の例の出力は、 たとえば以下のようになります。

damson

参考

  • SeekableIterator
  • Iterator


例外

目次

  • BadFunctionCallException
  • BadMethodCallException
  • DomainException
  • InvalidArgumentException
  • LengthException
  • LogicException
  • OutOfBoundsException
  • OutOfRangeException
  • OverflowException
  • RangeException
  • RuntimeException
  • UnderflowException
  • UnexpectedValueException

SPL には標準の例外が用意されています。

定義済みの例外 も参照ください。

SPL 例外クラスツリー

  • LogicException (extends Exception)
    • BadFunctionCallException
      • BadMethodCallException
    • DomainException
    • InvalidArgumentException
    • LengthException
    • OutOfRangeException
  • RuntimeException (extends Exception)
    • OutOfBoundsException
    • OverflowException
    • RangeException
    • UnderflowException
    • UnexpectedValueException


BadFunctionCallException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

未定義の関数をコールバックが参照したり、引数を指定しなかったりした場合にスローされる例外です。

クラス概要

class BadFunctionCallException extends LogicException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


BadMethodCallException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

未定義のメソッドをコールバックが参照したり、引数を指定しなかったりした場合にスローされる例外です。

クラス概要

class BadMethodCallException extends BadFunctionCallException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


DomainException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

定義したデータドメインに値が従わないときにスローされる例外です。

クラス概要

class DomainException extends LogicException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


InvalidArgumentException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

引数の型が期待する型と一致しなかった場合にスローされる例外です。

クラス概要

class InvalidArgumentException extends LogicException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


LengthException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

長さが無効な場合にスローされる例外です。

クラス概要

class LengthException extends LogicException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


LogicException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

プログラムのロジック内でのエラーを表す例外です。 この類の例外が出た場合は、自分が書いたコードを修正すべきです。

クラス概要

class LogicException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


OutOfBoundsException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

値が有効なキーでなかった場合にスローされる例外です。 これは、コンパイル時には検出できないエラーです。

クラス概要

class OutOfBoundsException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


OutOfRangeException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

無効なインデックスを要求した場合にスローされる例外です。 これは、コンパイル時に検出しなければなりません。

クラス概要

class OutOfRangeException extends LogicException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


OverflowException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

いっぱいになっているコンテナに要素を追加した場合にスローされる例外です。

クラス概要

class OverflowException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


RangeException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

プログラムの実行時に範囲エラーが発生したことを示すときにスローされる例外です。 通常は、アンダーフローやオーバーフロー以外の計算エラーが発生したことを意味します。 これは、実行時版の DomainException です。

クラス概要

class RangeException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


RuntimeException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

実行時にだけ発生するようなエラーの際にスローされます。

クラス概要

class RuntimeException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


UnderflowException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

空のコンテナ上で無効な操作 (要素の削除など) を試みたときにスローされる例外です。

クラス概要

class UnderflowException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


UnexpectedValueException クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

いくつかの値のセットに一致しない値であった際にスローされる例外です。 これが発生する例としては、ある関数が別の関数をコールしていて、 その関数の戻り値が特定の型や値である (そして計算やバッファ関連のエラーがない) ことを想定している場合があります。

クラス概要

class UnexpectedValueException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


SPL 関数

目次

  • class_implements — 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
  • class_parents — 与えられたクラスの親クラスを返す
  • class_uses — 指定したクラスが使っているトレイトを返す
  • iterator_apply — ユーザー関数をイテレータのすべての要素でコールする
  • iterator_count — イテレータにある要素をカウントする
  • iterator_to_array — イテレータを配列にコピーする
  • spl_autoload — __autoload() のデフォルト実装
  • spl_autoload_call — 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す
  • spl_autoload_extensions — spl_autoload 用のデフォルトの拡張子を登録し、それを返す
  • spl_autoload_functions — すべての登録済み __autoload() 関数を返す
  • spl_autoload_register — 指定した関数を __autoload() の実装として登録する
  • spl_autoload_unregister — 指定した関数の、__autoload() の実装としての登録を解除する
  • spl_classes — 利用可能な SPL クラスを返す
  • spl_object_hash — 指定したオブジェクトのハッシュ ID を返す
  • spl_object_id — 与えられたオブジェクトを扱う数値オブジェクトを返す


与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

  • ≪ SPL 関数
  • class_parents ≫
  • PHP Manual
  • SPL 関数
  • 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

class_implements

(PHP 5, PHP 7, PHP 8)

class_implements — 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す

説明

class_implements(object|string $object_or_class, bool $autoload = true): array|false

この関数は、与えられたクラス object_or_class とその親が実装しているインターフェイスを配列で返します。

パラメータ

object_or_class

オブジェクト (クラスのインスタンス) もしくは文字列 (クラス名あるいはインターフェイス名) を指定します。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

成功した場合に配列、 指定されたクラスが存在しない場合に false を返します。

例

例1 class_implements() の例

<?php

interface foo { }
class bar implements foo {}

print_r(class_implements(new bar));

// パラメータを文字列として指定しても良い
print_r(class_implements('bar'));

spl_autoload_register();

// 'not_loaded' クラスをロードするためにオートローディングを使用する
print_r(class_implements('not_loaded', true));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [foo] => foo
)
Array
(
    [foo] => foo
)
Array
(
    [interface_of_not_loaded] => interface_of_not_loaded
)

注意

注意: オブジェクトが、インターフェイスを実装しているかどうかを調べるには、 instanceof か、is_a() 関数を代わりに使うべきです。

参考

  • class_parents() - 与えられたクラスの親クラスを返す
  • get_declared_interfaces() - 宣言されている全てのインターフェイスの配列を返す
  • is_a() - オブジェクトが指定された型のものか、部分型であるかを調べる
  • instanceof


与えられたクラスの親クラスを返す

  • ≪ class_implements
  • class_uses ≫
  • PHP Manual
  • SPL 関数
  • 与えられたクラスの親クラスを返す

class_parents

(PHP 5, PHP 7, PHP 8)

class_parents — 与えられたクラスの親クラスを返す

説明

class_parents(object|string $object_or_class, bool $autoload = true): array|false

この関数は、与えられたクラス object_or_class の親クラス名を 配列で返します。

パラメータ

object_or_class

オブジェクトもしくはクラスの文字列を指定します。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

成功した場合に配列、 指定されたクラスが存在しない場合に false を返します。

例

例1 class_parents() の例

<?php

class foo { }
class bar extends foo {}

print_r(class_parents(new bar));

// パラメータを文字列として指定しても良い
print_r(class_parents('bar'));

spl_autoload_register();

// 'not_loaded' クラスをロードするためにオートローディングを使用する
print_r(class_parents('not_loaded', true));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [foo] => foo
)
Array
(
    [foo] => foo
)
Array
(
    [parent_of_not_loaded] => parent_of_not_loaded
)

注意

注意: オブジェクトが、クラスを継承しているかどうかを調べるには、 instanceof か、is_a() 関数を代わりに使うべきです。

参考

  • class_implements() - 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
  • is_a() - オブジェクトが指定された型のものか、部分型であるかを調べる
  • instanceof


指定したクラスが使っているトレイトを返す

  • ≪ class_parents
  • iterator_apply ≫
  • PHP Manual
  • SPL 関数
  • 指定したクラスが使っているトレイトを返す

class_uses

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

class_uses — 指定したクラスが使っているトレイトを返す

説明

class_uses(object|string $object_or_class, bool $autoload = true): array|false

この関数は、指定した object_or_class が使っているトレイトの名前を配列で返します。 しかし、親クラスで使っているトレイトは含まれません。

パラメータ

object_or_class

オブジェクト (クラスのインスタンス) あるいは文字列 (クラス名)。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

成功した場合に配列、 指定されたクラスが存在しない場合に false を返します。

例

例1 class_uses() の例

<?php

trait foo { }
class bar {
use foo;
}

print_r(class_uses(new bar));

print_r(class_uses('bar'));

spl_autoload_register();

// オートローディングを使い、'not_loaded' クラスを読み込みます
print_r(class_uses('not_loaded', true));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [foo] => foo
)
Array
(
    [foo] => foo
)
Array
(
    [trait_of_not_loaded] => trait_of_not_loaded
)

参考

  • class_parents() - 与えられたクラスの親クラスを返す
  • get_declared_traits() - 宣言されているすべてのトレイトの配列を返す


ユーザー関数をイテレータのすべての要素でコールする

  • ≪ class_uses
  • iterator_count ≫
  • PHP Manual
  • SPL 関数
  • ユーザー関数をイテレータのすべての要素でコールする

iterator_apply

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

iterator_apply — ユーザー関数をイテレータのすべての要素でコールする

説明

iterator_apply(Traversable $iterator, callable $callback, ?array $args = null): int

イテレータ内のすべての要素に対して関数をコールします。

パラメータ

iterator

順次処理したいイテレータオブジェクト

callback

すべての要素に対してコールしたいコールバック関数。 この関数は args のみを受け取ります。 デフォルトでは引数を渡されません。 たとえば count($args) === 3 の場合、 コールバック関数は3変数関数です。

注意: iterator での処理を続けるために、 この関数は true を返さなければなりません。

args

コールバック関数に渡す引数。 引数の array。 args の個々の要素が コールバック callback に別々の引数として渡されます。

戻り値

イテレータの要素数を返します。

例

例1 iterator_apply() の例

<?php
function print_caps(Iterator $iterator) {
echo strtoupper($iterator->current()) . "\n";
return TRUE;
}

$it = new ArrayIterator(array("Apples", "Bananas", "Cherries"));
iterator_apply($it, "print_caps", array($it));
?>

上の例の出力は以下となります。

APPLES
BANANAS
CHERRIES

参考

  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する


イテレータにある要素をカウントする

  • ≪ iterator_apply
  • iterator_to_array ≫
  • PHP Manual
  • SPL 関数
  • イテレータにある要素をカウントする

iterator_count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

iterator_count — イテレータにある要素をカウントする

説明

iterator_count(Traversable|array $iterator): int

イテレータにある要素をカウントします。 iterator_count() は、 iterator の現在位置がそのまま保たれることを保障しません。

パラメータ

iterator

カウントしたいイテレータ。

戻り値

iterator の要素数を返します。

変更履歴

バージョン | 説明
8.2.0 | iterator の型が Traversable から、 Traversable|array に拡大されました。

例

例1 iterator_count() の例

<?php
$iterator = new ArrayIterator(array('recipe'=>'pancakes', 'egg', 'milk', 'flour'));
var_dump(iterator_count($iterator));
?>

上の例の出力は以下となります。

int(4)

例2 iterator_count() で位置を変更する例

<?php
$iterator = new ArrayIterator(['one', 'two', 'three']);
var_dump($iterator->current());
var_dump(iterator_count($iterator));
var_dump($iterator->current());
?>

上の例の出力は以下となります。

string(3) "one"
int(3)
NULL

例3 foreach ループ内での iterator_count()

<?php
$iterator = new ArrayIterator(['one', 'two', 'three']);
foreach ($iterator as $key => $value) {
echo "$key: $value (", iterator_count($iterator), ")\n";
}?>

上の例の出力は以下となります。

0: one (3)


イテレータを配列にコピーする

  • ≪ iterator_count
  • spl_autoload ≫
  • PHP Manual
  • SPL 関数
  • イテレータを配列にコピーする

iterator_to_array

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

iterator_to_array — イテレータを配列にコピーする

説明

iterator_to_array(Traversable|array $iterator, bool $preserve_keys = true): array

イテレータの要素を配列にコピーします。

パラメータ

iterator

コピーしたいイテレータ。

preserve_keys

イテレータの要素のキーをインデックスとして使用するかどうか。

キーが array あるいは object の場合は、警告が発生します。 キーが null の場合は空文字列に変換し、キーが float の場合は int 型になるよう切り詰めます。 キーが resource の場合は警告を発し、リソース ID に変換します。 また、キーが bool の場合は整数値に変換します。

注意:

このパラメータを省略したり true を指定したりした場合は、 重複するキーは上書きされます。そのキーに対して最後にあらわれた値が array で返されることになります。 このパラメータを false にすると、重複があってもすべての値を返します。

戻り値

iterator の要素を含む配列を返します。

変更履歴

バージョン | 説明
8.2.0 | iterator の型が Traversable から、 Traversable|array に拡大されました。

例

例1 iterator_to_array() の例

<?php
$iterator = new ArrayIterator(array('recipe'=>'pancakes', 'egg', 'milk', 'flour'));
var_dump(iterator_to_array($iterator, true));
var_dump(iterator_to_array($iterator, false));
?>

上の例の出力は以下となります。

array(4) {
  ["recipe"]=>
  string(8) "pancakes"
  [0]=>
  string(3) "egg"
  [1]=>
  string(4) "milk"
  [2]=>
  string(5) "flour"
}
array(4) {
  [0]=>
  string(8) "pancakes"
  [1]=>
  string(3) "egg"
  [2]=>
  string(4) "milk"
  [3]=>
  string(5) "flour"
}


__autoload() のデフォルト実装

  • ≪ iterator_to_array
  • spl_autoload_call ≫
  • PHP Manual
  • SPL 関数
  • __autoload() のデフォルト実装

spl_autoload

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload — __autoload() のデフォルト実装

説明

spl_autoload(string $class, ?string $file_extensions = null): void

この関数は、__autoload() のデフォルト実装として使用されることを意図しています。 ほかに何も指定されておらず、spl_autoload_register() がパラメータなしでコールされた場合には、 その後の __autoload() のコール時には spl_autoload() が使用されます。

パラメータ

class

インスタンスを作成するクラス名 (および名前空間名)。

file_extensions

デフォルトでは、クラス名を小文字にして .inc および .php を拡張子につけたファイル名のファイルが存在するかどうかを すべての include_path から探します。

戻り値

値を返しません。

エラー / 例外

クラスが見つからず、かつそれ以外にオートローダーが登録されていない場合に LogicException をスローします。

変更履歴

バージョン | 説明
8.0.0 | file_extensions は、nullable になりました。


要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す

  • ≪ spl_autoload
  • spl_autoload_extensions ≫
  • PHP Manual
  • SPL 関数
  • 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す

spl_autoload_call

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload_call — 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す

説明

spl_autoload_call(string $class): void

この関数は、登録済みの __autoload 関数を使用して クラスあるいはインターフェイスを手動で探すために使用することができます。

パラメータ

class

探したいクラス名。

戻り値

値を返しません。


spl_autoload 用のデフォルトの拡張子を登録し、それを返す

  • ≪ spl_autoload_call
  • spl_autoload_functions ≫
  • PHP Manual
  • SPL 関数
  • spl_autoload 用のデフォルトの拡張子を登録し、それを返す

spl_autoload_extensions

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload_extensions — spl_autoload 用のデフォルトの拡張子を登録し、それを返す

説明

spl_autoload_extensions(?string $file_extensions = null): string

この関数は、__autoload() 用の代替関数である spl_autoload() が使用するファイル拡張子を変更したり調べたりします。

注意: ファイルの拡張子の間にスペースを入れるべきではありません。

パラメータ

file_extensions

null を指定した場合、現在の拡張子一覧をカンマ区切りで返します。 ファイル拡張子を変更するには、 新しい拡張子一覧をカンマ区切り文字列で表したものを引数に指定して、 この関数を実行します。

戻り値

spl_autoload() のデフォルト拡張子の一覧をカンマ区切り形式で返します。

変更履歴

バージョン | 説明
8.0.0 | file_extensions は、nullable になりました。

例

例1 spl_autoload_extensions() の例

<?php
spl_autoload_extensions(".php,.inc");
?>


すべての登録済み __autoload() 関数を返す

  • ≪ spl_autoload_extensions
  • spl_autoload_register ≫
  • PHP Manual
  • SPL 関数
  • すべての登録済み __autoload() 関数を返す

spl_autoload_functions

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload_functions — すべての登録済み __autoload() 関数を返す

説明

spl_autoload_functions(): array

すべての登録済み __autoload() 関数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

関数が何も登録されていなかったり、 autoload キューが有効になっていない場合は、 空の配列が返されます。

変更履歴

バージョン | 説明
8.0.0 | 戻り値は常に配列になりました。 これより前のバージョンでは、 autoload キューが有効になっていない場合に false を返していました。


指定した関数を __autoload() の実装として登録する

  • ≪ spl_autoload_functions
  • spl_autoload_unregister ≫
  • PHP Manual
  • SPL 関数
  • 指定した関数を __autoload() の実装として登録する

spl_autoload_register

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload_register — 指定した関数を __autoload() の実装として登録する

説明

spl_autoload_register(?callable $callback = null, bool $throw = true, bool $prepend = false): bool

指定した関数を、spl が提供する __autoload キューに登録します。 キューがまだアクティブになっていない場合は、まずアクティブにします。

もしあなたのコード中に __autoload() 関数が存在するのなら、
それを明示的に __autoload キューに登録しなければなりません。
なぜなら、spl_autoload_register() は、
spl_autoload() あるいは spl_autoload_call() によって
__autoload() 関数のエンジンキャッシュを効率的に置き換えるからです。

複数の autoload 関数が必要となる場合でも spl_autoload_register() は対応できます。この関数は autoload 関数のキューを作成し、 定義された順にそれを実行していきます。一方 __autoload() は、一度しか定義できません。

パラメータ

callback

登録したい autoload 関数。 null を指定した場合、デフォルト実装である spl_autoload() が登録されます。

callback(string $class): void

class には、完全修飾子を示す、先頭のバックスラッシュが付くことはありません。

throw

このパラメータは、 spl_autoload_register() が callback を登録できなかったときに例外をスローするかどうかを指定します。

警告

このパラメータは、PHP 8.0.0 以降は無視されます。 かつ、false を設定すると警告が発生します。 spl_autoload_register() は、 引数が不正な場合常に TypeError をスローするようになっています。

prepend

true の場合、spl_autoload_register() はキューの最後に追加するのではなく先頭に追加します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | callback は、nullable になりました。

例

例1 spl_autoload_register() を __autoload() 関数の代わりに使う例

<?php

// function __autoload($class) {
// include 'classes/' . $class . '.class.php';
// }

function my_autoloader($class) {
include 'classes/' . $class . '.class.php';
}

spl_autoload_register('my_autoloader');

// あるいは、無名関数も使えます
spl_autoload_register(function ($class) {
include 'classes/' . $class . '.class.php';
});

?>

例2 spl_autoload_register() でクラスをロードしない例

<?php

namespace Foobar;

class Foo {
static public function test($class) {
print '[['. $class .']]';
}
}

spl_autoload_register(__NAMESPACE__ .'\Foo::test');

new InexistentClass;

?>

上の例の出力は、 たとえば以下のようになります。

[[Foobar\InexistentClass]]
Fatal error: Class 'Foobar\InexistentClass' not found in ...

例3 識別子には先頭のバックスラッシュが付かない

<?php

spl_autoload_register(static function ($class) {
var_dump($class);
});

class_exists('RelativeName');
class_exists('RelativeName\\WithNamespace');
class_exists('\\AbsoluteName');
class_exists('\\AbsoluteName\\WithNamespace');

?>

上の例の出力は以下となります。

string(12) "RelativeName"
string(26) "RelativeName\WithNamespace"
string(12) "AbsoluteName"
string(26) "AbsoluteName\WithNamespace"

参考

  • __autoload() - 未定義のクラスのロードを試みる


指定した関数の、__autoload() の実装としての登録を解除する

  • ≪ spl_autoload_register
  • spl_classes ≫
  • PHP Manual
  • SPL 関数
  • 指定した関数の、__autoload() の実装としての登録を解除する

spl_autoload_unregister

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload_unregister — 指定した関数の、__autoload() の実装としての登録を解除する

説明

spl_autoload_unregister(callable $callback): bool

spl が提供する __autoload キューから、関数を削除します。 キューがアクティブであり、かつこの関数の削除後にキューが空になった場合は キューが非アクティブ化されます。

この関数の結果として autoload キューが非アクティブになったとした場合に、 既存の __autoload 関数が再アクティブ化されることはありません。

パラメータ

callback

登録を解除したい autoload 関数。

戻り値

成功した場合に true を、失敗した場合に false を返します。


利用可能な SPL クラスを返す

  • ≪ spl_autoload_unregister
  • spl_object_hash ≫
  • PHP Manual
  • SPL 関数
  • 利用可能な SPL クラスを返す

spl_classes

(PHP 5, PHP 7, PHP 8)

spl_classes — 利用可能な SPL クラスを返す

説明

spl_classes(): array

この関数は現在利用可能な SPL クラスを配列で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在利用可能な SPL クラスを配列で返します。

例

例1 spl_classes() の例

<?php

print_r(spl_classes());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [ArrayObject] => ArrayObject
    [ArrayIterator] => ArrayIterator
    [CachingIterator] => CachingIterator
    [RecursiveCachingIterator] => RecursiveCachingIterator
    [DirectoryIterator] => DirectoryIterator
    [FilterIterator] => FilterIterator
    [LimitIterator] => LimitIterator
    [ParentIterator] => ParentIterator
    [RecursiveDirectoryIterator] => RecursiveDirectoryIterator
    [RecursiveIterator] => RecursiveIterator
    [RecursiveIteratorIterator] => RecursiveIteratorIterator
    [SeekableIterator] => SeekableIterator
    [SimpleXMLIterator] => SimpleXMLIterator
)


指定したオブジェクトのハッシュ ID を返す

  • ≪ spl_classes
  • spl_object_id ≫
  • PHP Manual
  • SPL 関数
  • 指定したオブジェクトのハッシュ ID を返す

spl_object_hash

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

spl_object_hash — 指定したオブジェクトのハッシュ ID を返す

説明

spl_object_hash(object $object): string

この関数は、オブジェクトの一意な識別子を返します。この ID は、 オブジェクトを保存する際のハッシュのキーとして使えます。 また、オブジェクトが破棄されるまでは、オブジェクトを識別するための値としても使えます。 オブジェクトが破棄されると、そのハッシュが他のオブジェクトで再利用されてしまうことがあります。 この振る舞いは、spl_object_id() に似ています。

パラメータ

object

何らかのオブジェクト。

戻り値

現在存在する各オブジェクトに固有で、同一オブジェクトに対しては常に同じ値となる文字列を返します。

例

例1 spl_object_hash() の例

<?php
$id = spl_object_hash($object);
$storage[$id] = $object;
?>

注意

注意:

オブジェクトが破壊されるとき、そのハッシュが他のオブジェクトで再利用されてしまうことがあります。

注意:

オブジェクトの ハッシュID は、=== や !== を使って比較すべきです。なぜなら、この関数が返すハッシュID が 数値形式の文字列 になる可能性があるからです。 たとえば以下のような値がありえます: 0000000000000e600000000000000000

参考

  • spl_object_id() - 与えられたオブジェクトを扱う数値オブジェクトを返す


与えられたオブジェクトを扱う数値オブジェクトを返す

  • ≪ spl_object_hash
  • ファイル操作 ≫
  • PHP Manual
  • SPL 関数
  • 与えられたオブジェクトを扱う数値オブジェクトを返す

spl_object_id

(PHP 7 >= 7.2.0, PHP 8)

spl_object_id — 与えられたオブジェクトを扱う数値オブジェクトを返す

説明

spl_object_id(object $object): int

この関数は、オブジェクトのユニークな識別子を返します。 このオブジェクトidはオブジェクトが生きている間ユニークです。 オブジェクトがいったん破棄されると、そのidは他のオブジェクトによって再利用されます。 この振る舞いは、spl_object_hash() と似ています。

パラメータ

object

任意のオブジェクト

戻り値

現在存在しているそれぞれのオブジェクトの間でユニークで、 かつそれぞれのオブジェクト毎に常に同じ数値の識別子を返します。

例

例1 spl_object_id() の例

<?php
$id = spl_object_id($object);
$storage[$id] = $object;
?>

注意

注意:

オブジェクトが破棄されると、そのidは他のオブジェクトによって再利用されるかもしれません。


ファイル操作

目次

  • SplFileInfo
  • SplFileObject
  • SplTempFileObject

SPL にはファイルを扱うためのクラスが用意されています。


SplFileInfo クラス

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

はじめに

SplFileInfo クラスは、各ファイルの情報を取得するための上位レベルのオブジェクト指向インターフェイスです。

クラス概要

class SplFileInfo implements Stringable {
/* メソッド */
public __construct(string $filename)
public getATime(): int|false
public getBasename(string $suffix = ""): string
public getCTime(): int|false
public getExtension(): string
public getFileInfo(?string $class = null): SplFileInfo
public getFilename(): string
public getGroup(): int|false
public getInode(): int|false
public getLinkTarget(): string|false
public getMTime(): int|false
public getOwner(): int|false
public getPath(): string
public getPathInfo(?string $class = null): ?SplFileInfo
public getPathname(): string
public getPerms(): int|false
public getRealPath(): string|false
public getSize(): int|false
public getType(): string|false
public isDir(): bool
public isExecutable(): bool
public isFile(): bool
public isLink(): bool
public isReadable(): bool
public isWritable(): bool
public openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public setFileClass(string $class = SplFileObject::class): void
public setInfoClass(string $class = SplFileInfo::class): void
public __toString(): string
}

変更履歴

バージョン | 説明
8.0.0 | SplFileInfo は、新たに Stringable を実装しました。

目次

  • SplFileInfo::__construct — 新しい SplFileInfo オブジェクトを作成する
  • SplFileInfo::getATime — ファイルの最終アクセス時刻を取得する
  • SplFileInfo::getBasename — ファイルのベース名を取得する
  • SplFileInfo::getCTime — inode 変更時刻を取得する
  • SplFileInfo::getExtension — ファイルの拡張子を取得する
  • SplFileInfo::getFileInfo — ファイルの SplFileInfo オブジェクトを取得する
  • SplFileInfo::getFilename — ファイル名を取得する
  • SplFileInfo::getGroup — ファイルのグループを取得する
  • SplFileInfo::getInode — ファイルの inode を取得する
  • SplFileInfo::getLinkTarget — リンク先を取得する
  • SplFileInfo::getMTime — 最終変更時刻を取得する
  • SplFileInfo::getOwner — ファイルの所有者を取得する
  • SplFileInfo::getPath — ファイル名を除いたパスを取得する
  • SplFileInfo::getPathInfo — パスの SplFileInfo オブジェクトを取得する
  • SplFileInfo::getPathname — ファイルへのパスを取得する
  • SplFileInfo::getPerms — ファイルのパーミッションを取得する
  • SplFileInfo::getRealPath — ファイルへの絶対パスを取得する
  • SplFileInfo::getSize — ファイルサイズを取得する
  • SplFileInfo::getType — ファイルタイプを取得する
  • SplFileInfo::isDir — ファイルがディレクトリかどうかを調べる
  • SplFileInfo::isExecutable — ファイルが実行可能かどうかを調べる
  • SplFileInfo::isFile — オブジェクトの参照先が通常のファイルであるかどうかを調べる
  • SplFileInfo::isLink — ファイルがリンクであるかどうかを調べる
  • SplFileInfo::isReadable — ファイルが読み込み可能か調べる
  • SplFileInfo::isWritable — エントリが書き込み可能であるかどうかを調べる
  • SplFileInfo::openFile — ファイルの SplFileObject オブジェクトを取得する
  • SplFileInfo::setFileClass — SplFileInfo::openFile で使用するクラスを設定する
  • SplFileInfo::setInfoClass — SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する
  • SplFileInfo::__toString — ファイルへのパスを文字列で返す


新しい SplFileInfo オブジェクトを作成する

  • ≪ SplFileInfo
  • SplFileInfo::getATime ≫
  • PHP Manual
  • SplFileInfo
  • 新しい SplFileInfo オブジェクトを作成する

SplFileInfo::__construct

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::__construct — 新しい SplFileInfo オブジェクトを作成する

説明

public SplFileInfo::__construct(string $filename)

file_name で指定したファイル用の新しい SplFileInfo オブジェクトを作成します。 ファイルが存在する必要はなく、また読み込み可能である必要もありません。

パラメータ

filename

ファイルへのパス。

例

例1 SplFileInfo::__construct() の例

<?php
$info = new SplFileInfo('example.php');
if ($info->isFile()) {
echo $info->getRealPath();
}
?>


ファイルの最終アクセス時刻を取得する

  • ≪ SplFileInfo::__construct
  • SplFileInfo::getBasename ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの最終アクセス時刻を取得する

SplFileInfo::getATime

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getATime — ファイルの最終アクセス時刻を取得する

説明

public SplFileInfo::getATime(): int|false

ファイルの最終アクセス時刻を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時に、ファイルに最後にアクセスがあった時刻を返します。 失敗時に false を返します。

エラー / 例外

エラー時に RunTimeException をスローします。

例

例1 SplFileInfo::getATime() の例

<?php
$info = new SplFileInfo('example.jpg');
echo 'Last accessed at ' . date('g:i a', $info->getATime());
?>

上の例の出力は、 たとえば以下のようになります。

Last accessed at 1:49 pm

参考

  • fileatime() - ファイルの最終アクセス時刻を取得する
  • SplFileInfo::getCTime() - inode 変更時刻を取得する
  • SplFileInfo::getMTime() - 最終変更時刻を取得する


ファイルのベース名を取得する

  • ≪ SplFileInfo::getATime
  • SplFileInfo::getCTime ≫
  • PHP Manual
  • SplFileInfo
  • ファイルのベース名を取得する

SplFileInfo::getBasename

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

SplFileInfo::getBasename — ファイルのベース名を取得する

説明

public SplFileInfo::getBasename(string $suffix = ""): string

このメソッドは、ファイルやディレクトリそしてリンクからパス情報を除いたベース名を返します。

警告

SplFileInfo::getBasename() は、ロケールを認識します。 よって、マルチバイト文字が含まれたパスのベース名を正しく返させるためには、 そのパスと一致するロケールを setlocale() 関数で設定しなければなりません。

パラメータ

suffix

返されるベース名から取り除きたい、オプションのサフィックス。

戻り値

パス情報を含まないベース名を返します。

例

例1 SplFileInfo::getBasename() の例

<?php
$info = new SplFileInfo('file.txt');
var_dump($info->getBasename());

$info = new SplFileInfo('/path/to/file.txt');
var_dump($info->getBasename());

$info = new SplFileInfo('/path/to/file.txt');
var_dump($info->getBasename('.txt'));
?>

上の例の出力は、 たとえば以下のようになります。

string(8) "file.txt"
string(8) "file.txt"
string(4) "file"

参考

  • SplFileInfo::getFilename() - ファイル名を取得する


inode 変更時刻を取得する

  • ≪ SplFileInfo::getBasename
  • SplFileInfo::getExtension ≫
  • PHP Manual
  • SplFileInfo
  • inode 変更時刻を取得する

SplFileInfo::getCTime

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getCTime — inode 変更時刻を取得する

説明

public SplFileInfo::getCTime(): int|false

ファイルの inode が変更された時刻を返します。返される時刻は Unix タイムスタンプ形式です。

パラメータ

この関数にはパラメータはありません。

戻り値

最終変更時刻を Unix タイムスタンプで返します。 失敗時に false を返します。

エラー / 例外

エラー時に RunTimeException をスローします。

例

例1 SplFileInfo::getCTime() の例

<?php
$info = new SplFileInfo('example.jpg');
echo 'Last changed at ' . date('g:i a', $info->getCTime());
?>

上の例の出力は、 たとえば以下のようになります。

Last changed at 1:49 pm

参考

  • filectime() - ファイルの inode 変更時刻を取得する
  • SplFileInfo::getATime() - ファイルの最終アクセス時刻を取得する
  • SplFileInfo::getMTime() - 最終変更時刻を取得する


ファイルの拡張子を取得する

  • ≪ SplFileInfo::getCTime
  • SplFileInfo::getFileInfo ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの拡張子を取得する

SplFileInfo::getExtension

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SplFileInfo::getExtension — ファイルの拡張子を取得する

説明

public SplFileInfo::getExtension(): string

ファイルの拡張子を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルの拡張子を含む文字列を返します。 拡張子がないときは、空文字列を返します。

例

例1 SplFileInfo::getExtension() の例

<?php

$info = new SplFileInfo('foo.txt');
var_dump($info->getExtension());

$info = new SplFileInfo('photo.jpg');
var_dump($info->getExtension());

$info = new SplFileInfo('something.tar.gz');
var_dump($info->getExtension());

?>

上の例の出力は以下となります。

string(3) "txt"
string(3) "jpg"
string(2) "gz"

注意

注意:

拡張子を取得する別の方法には、 pathinfo() 関数があります。

<?php
$extension = pathinfo($info->getFilename(), PATHINFO_EXTENSION);
?>

参考

  • SplFileInfo::getFilename() - ファイル名を取得する
  • SplFileInfo::getBasename() - ファイルのベース名を取得する
  • pathinfo() - ファイルパスに関する情報を返す


ファイルの SplFileInfo オブジェクトを取得する

  • ≪ SplFileInfo::getExtension
  • SplFileInfo::getFilename ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの SplFileInfo オブジェクトを取得する

SplFileInfo::getFileInfo

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getFileInfo — ファイルの SplFileInfo オブジェクトを取得する

説明

public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo

このメソッドは、参照先のファイルの SplFileInfo オブジェクトを取得します。

パラメータ

class

使用したい SplFileInfo 派生クラスの名前。

戻り値

そのファイル用に作成した SplFileInfo オブジェクトを返します。

変更履歴

バージョン | 説明
8.0.0 | class は、nullable になりました。

参考

  • SplFileInfo::setInfoClass() - SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する


ファイル名を取得する

  • ≪ SplFileInfo::getFileInfo
  • SplFileInfo::getGroup ≫
  • PHP Manual
  • SplFileInfo
  • ファイル名を取得する

SplFileInfo::getFilename

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getFilename — ファイル名を取得する

説明

public SplFileInfo::getFilename(): string

パス情報を一切含まないファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイル名を返します。

例

例1 SplFileInfo::getFilename() の例

<?php
$info = new SplFileInfo('foo.txt');
var_dump($info->getFilename());

$info = new SplFileInfo('/path/to/foo.txt');
var_dump($info->getFilename());

$info = new SplFileInfo('http://www.php.net/');
var_dump($info->getFilename());

$info = new SplFileInfo('http://www.php.net/svn.php');
var_dump($info->getFilename());
?>

上の例の出力は、 たとえば以下のようになります。

string(7) "foo.txt"
string(7) "foo.txt"
string(0) ""
string(7) "svn.php"

参考

  • SplFileInfo::getBasename() - ファイルのベース名を取得する


ファイルのグループを取得する

  • ≪ SplFileInfo::getFilename
  • SplFileInfo::getInode ≫
  • PHP Manual
  • SplFileInfo
  • ファイルのグループを取得する

SplFileInfo::getGroup

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getGroup — ファイルのグループを取得する

説明

public SplFileInfo::getGroup(): int|false

ファイルのグループを取得します。グループ ID を数値形式で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時に、グループ ID を数値形式で返します。 失敗時に false を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getGroup() の例

<?php
$info = new SplFileInfo('example.jpg');
echo info->getFilename() . ' belongs to group id ' . $info->getGroup() . "\n";
print_r(posix_getgrgid($info->getGroup()));
?>

上の例の出力は、 たとえば以下のようになります。

example.jpg belongs to group id 42
Array
(
    [name] => toons
    [passwd] => x
    [members] => Array
        (
            [0] => tom
            [1] => jerry
        )
    [gid] => 42
)

参考

  • filegroup() - ファイルのグループを取得する
  • posix_getgrgid() - 指定したグループ ID を有するグループに関する情報を返す


ファイルの inode を取得する

  • ≪ SplFileInfo::getGroup
  • SplFileInfo::getLinkTarget ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの inode を取得する

SplFileInfo::getInode

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getInode — ファイルの inode を取得する

説明

public SplFileInfo::getInode(): int|false

ファイルシステムオブジェクトの inode 番号を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルシステムオブジェクトの inode 番号を返します。 失敗時に false を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

参考

  • fileinode() - ファイルの inode を取得する


リンク先を取得する

  • ≪ SplFileInfo::getInode
  • SplFileInfo::getMTime ≫
  • PHP Manual
  • SplFileInfo
  • リンク先を取得する

SplFileInfo::getLinkTarget

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

SplFileInfo::getLinkTarget — リンク先を取得する

説明

public SplFileInfo::getLinkTarget(): string|false

ファイルシステムのリンク先を取得します。

注意:

リンク先は、ファイルシステム上の実際のパスではないかもしれません。 SplFileInfo::getRealPath() を使用して、ファイルシステム上の実際のパスを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルシステムのリンク先を返します。 失敗時に false を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getLinkTarget() の例

<?php
$info = new SplFileInfo('/Users/bbieber/workspace');
if ($info->isLink()) {
var_dump($info->getLinkTarget());
var_dump($info->getRealPath());
}
?>

上の例の出力は、 たとえば以下のようになります。

string(19) "Documents/workspace"
string(34) "/Users/bbieber/Documents/workspace"

参考

  • SplFileInfo::isLink() - ファイルがリンクであるかどうかを調べる
  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する


最終変更時刻を取得する

  • ≪ SplFileInfo::getLinkTarget
  • SplFileInfo::getOwner ≫
  • PHP Manual
  • SplFileInfo
  • 最終変更時刻を取得する

SplFileInfo::getMTime

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getMTime — 最終変更時刻を取得する

説明

public SplFileInfo::getMTime(): int|false

ファイルの中身が変更された時刻を返します。返される時刻は Unix タイムスタンプ形式となります。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルの最終変更時刻を Unix タイムスタンプで返します。 失敗時に false を返します。

例

例1 SplFileInfo::getMTime() の例

<?php
$info = new SplFileInfo('example.jpg');
echo 'Last modified at ' . date('g:i a', $info->getMTime());
?>

上の例の出力は、 たとえば以下のようになります。

Last modified at 1:49 pm

参考

  • filemtime() - ファイルの更新時刻を取得する
  • SplFileInfo::getATime() - ファイルの最終アクセス時刻を取得する
  • SplFileInfo::getCTime() - inode 変更時刻を取得する


ファイルの所有者を取得する

  • ≪ SplFileInfo::getMTime
  • SplFileInfo::getPath ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの所有者を取得する

SplFileInfo::getOwner

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getOwner — ファイルの所有者を取得する

説明

public SplFileInfo::getOwner(): int|false

ファイルの所有者を取得します。オーナー ID は数値形式で返されます。

パラメータ

この関数にはパラメータはありません。

戻り値

オーナー ID を数値形式で返します。 失敗時に false を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getOwner() の例

<?php
$info = new SplFileInfo('example.jpg');
echo info->getFilename() . ' belongs to owner id ' . $info->getOwner() . "\n";
print_r(posix_getpwuid($info->getOwner()));
?>

上の例の出力は、 たとえば以下のようになります。

example.jpg belongs to user id 501
Array
(
    [name] => tom
    [passwd] => x
    [uid] => 501
    [gid] => 42
    [gecos] => Tom Cat
    [dir] => /home/tom
    [shell] => /bin/bash
)

参考

  • posix_getpwuid() - 指定 ID のユーザーに関する情報を返す
  • SplFileInfo::getGroup() - ファイルのグループを取得する


ファイル名を除いたパスを取得する

  • ≪ SplFileInfo::getOwner
  • SplFileInfo::getPathInfo ≫
  • PHP Manual
  • SplFileInfo
  • ファイル名を除いたパスを取得する

SplFileInfo::getPath

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getPath — ファイル名を除いたパスを取得する

説明

public SplFileInfo::getPath(): string

ファイルへのパスを返します。ファイル名や最後のスラッシュは取り除きます。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルへのパスを返します。

例

例1 SplFileInfo::getPath() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
var_dump($info->getPath());

$info = new SplFileInfo('/usr/');
var_dump($info->getPath());?>

上の例の出力は、 たとえば以下のようになります。

string(8) "/usr/bin"
string(4) "/usr"

参考

  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する
  • SplFileInfo::getFilename() - ファイル名を取得する
  • SplFileInfo::getPathInfo() - パスの SplFileInfo オブジェクトを取得する


パスの SplFileInfo オブジェクトを取得する

  • ≪ SplFileInfo::getPath
  • SplFileInfo::getPathname ≫
  • PHP Manual
  • SplFileInfo
  • パスの SplFileInfo オブジェクトを取得する

SplFileInfo::getPathInfo

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getPathInfo — パスの SplFileInfo オブジェクトを取得する

説明

public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo

現在のファイルの親を表す SplFileInfo オブジェクトを取得します。

パラメータ

class

使用したい SplFileInfo 派生クラスの名前。 SplFileInfo 自体を使う場合は null を指定します。

戻り値

ファイルの親のパスの SplFileInfo オブジェクトを返します。 失敗時に null を返します。

変更履歴

バージョン | 説明
8.0.0 | class は、nullable になりました。

例

例1 SplFileInfo::getPathInfo() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
$parent_info = $info->getPathInfo();
var_dump($parent_info->getRealPath());
?>

上の例の出力は、 たとえば以下のようになります。

string(8) "/usr/bin"

参考

  • SplFileInfo::setInfoClass() - SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する


ファイルへのパスを取得する

  • ≪ SplFileInfo::getPathInfo
  • SplFileInfo::getPerms ≫
  • PHP Manual
  • SplFileInfo
  • ファイルへのパスを取得する

SplFileInfo::getPathname

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getPathname — ファイルへのパスを取得する

説明

public SplFileInfo::getPathname(): string

ファイルへのパスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルへのパスを返します。

例

例1 SplFileInfo::getPathname() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
var_dump($info->getPathname());
?>

上の例の出力は、 たとえば以下のようになります。

string(12) "/usr/bin/php"

参考

  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する


ファイルのパーミッションを取得する

  • ≪ SplFileInfo::getPathname
  • SplFileInfo::getRealPath ≫
  • PHP Manual
  • SplFileInfo
  • ファイルのパーミッションを取得する

SplFileInfo::getPerms

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getPerms — ファイルのパーミッションを取得する

説明

public SplFileInfo::getPerms(): int|false

ファイルのパーミッションを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルのパーミッションを返します。 失敗時に false を返します。

例

例1 SplFileInfo::getPerms() の例

<?php
$info = new SplFileInfo('/tmp');
echo substr(sprintf('%o', $info->getPerms()), -4);

$info = new SplFileInfo(__FILE__);
echo substr(sprintf('%o', $info->getPerms()), -4);
?>

上の例の出力は、 たとえば以下のようになります。

1777
0644


ファイルへの絶対パスを取得する

  • ≪ SplFileInfo::getPerms
  • SplFileInfo::getSize ≫
  • PHP Manual
  • SplFileInfo
  • ファイルへの絶対パスを取得する

SplFileInfo::getRealPath

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

SplFileInfo::getRealPath — ファイルへの絶対パスを取得する

説明

public SplFileInfo::getRealPath(): string|false

このメソッドは、すべてのシンボリックリンクを展開して相対参照を解決し、 ファイルへの実際のパスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルへのパスを返します。ファイルが存在しない場合は false を返します。

例

例1 SplFileInfo::getRealPath() の例

<?php
$info = new SplFileInfo('/..//./../../'.__FILE__);
var_dump($info->getRealPath());

$info = new SplFileInfo('/tmp');
var_dump($info->getRealPath());

$info = new SplFileInfo('/I/Do/Not/Exist');
var_dump($info->getRealPath());

$info = new SplFileInfo('php://output');
var_dump($info->getRealPath());

$info = new SplFileInfo("");
var_dump($info->getRealPath());
?>

上の例の出力は、 たとえば以下のようになります。

string(28) "/private/tmp/phptempfile.php"
string(12) "/private/tmp"
bool(false)
bool(false)
string(12) "/private/tmp"

参考

  • SplFileInfo::isLink() - ファイルがリンクであるかどうかを調べる
  • realpath() - 正規化された絶対パス名を返す


ファイルサイズを取得する

  • ≪ SplFileInfo::getRealPath
  • SplFileInfo::getType ≫
  • PHP Manual
  • SplFileInfo
  • ファイルサイズを取得する

SplFileInfo::getSize

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getSize — ファイルサイズを取得する

説明

public SplFileInfo::getSize(): int|false

参照するファイルのファイルサイズをバイト数で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルサイズをバイト数で返します。 失敗時に false を返します。

エラー / 例外

ファイルが存在しなかった場合やエラーが発生した場合に RuntimeException をスローします。

例

例1 SplFileInfo::getSize() の例

<?php
$info = new SplFileInfo('example.jpg');
echo $fileinfo->getFilename() . " " . $fileinfo->getSize();
?>

上の例の出力は、 たとえば以下のようになります。

example.jpg 15385

参考

  • filesize() - ファイルのサイズを取得する


ファイルタイプを取得する

  • ≪ SplFileInfo::getSize
  • SplFileInfo::isDir ≫
  • PHP Manual
  • SplFileInfo
  • ファイルタイプを取得する

SplFileInfo::getType

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::getType — ファイルタイプを取得する

説明

public SplFileInfo::getType(): string|false

参照するファイルの型を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

このエントリの型を文字列で返します。 file, link, dir, block, fifo, char, socket, unknown のいずれかとなります。 失敗時に false を返します。

エラー / 例外

エラー時に RuntimeException をスローします。

例

例1 SplFileInfo::getType() の例

<?php

$info = new SplFileInfo(__FILE__);
echo $info->getType().PHP_EOL;

$info = new SplFileInfo(dirname(__FILE__));
echo $info->getType();

?>

上の例の出力は、 たとえば以下のようになります。

file
dir


ファイルがディレクトリかどうかを調べる

  • ≪ SplFileInfo::getType
  • SplFileInfo::isExecutable ≫
  • PHP Manual
  • SplFileInfo
  • ファイルがディレクトリかどうかを調べる

SplFileInfo::isDir

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::isDir — ファイルがディレクトリかどうかを調べる

説明

public SplFileInfo::isDir(): bool

このメソッドを使用して、ファイルがディレクトリかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ディレクトリである場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isDir() の例

<?php
$d = new SplFileInfo(dirname(__FILE__));
var_dump($d->isDir());

$d = new SplFileInfo(__FILE__);
var_dump($d->isDir());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)


ファイルが実行可能かどうかを調べる

  • ≪ SplFileInfo::isDir
  • SplFileInfo::isFile ≫
  • PHP Manual
  • SplFileInfo
  • ファイルが実行可能かどうかを調べる

SplFileInfo::isExecutable

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::isExecutable — ファイルが実行可能かどうかを調べる

説明

public SplFileInfo::isExecutable(): bool

ファイルが実行可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

実行可能である場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isExecutable() の例

<?php
$info = new SplFileInfo('/usr/bin/php');
var_dump($info->isExecutable());

$info = new SplFileInfo('/usr/bin');
var_dump($info->isExecutable());

$info = new SplFileInfo('foo');
var_dump($info->isExecutable());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)


オブジェクトの参照先が通常のファイルであるかどうかを調べる

  • ≪ SplFileInfo::isExecutable
  • SplFileInfo::isLink ≫
  • PHP Manual
  • SplFileInfo
  • オブジェクトの参照先が通常のファイルであるかどうかを調べる

SplFileInfo::isFile

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::isFile — オブジェクトの参照先が通常のファイルであるかどうかを調べる

説明

public SplFileInfo::isFile(): bool

この SplFileInfo オブジェクトが参照するファイルが存在し、通常のファイルであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルが存在してかつ (リンクではない) 通常のファイルである場合に true、 そうでない場合に false を返します。

例

例1 SplFileInfo::isFile() の例

<?php
$info = new SplFileInfo(__FILE__);
var_dump($info->isFile());

$info = new SplFileInfo(dirname(__FILE__));
var_dump($info->isFile());
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)


ファイルがリンクであるかどうかを調べる

  • ≪ SplFileInfo::isFile
  • SplFileInfo::isReadable ≫
  • PHP Manual
  • SplFileInfo
  • ファイルがリンクであるかどうかを調べる

SplFileInfo::isLink

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::isLink — ファイルがリンクであるかどうかを調べる

説明

public SplFileInfo::isLink(): bool

このメソッドを使用して、SplFileInfo オブジェクトが参照するファイルがリンクであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルがリンクである場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isLink() の例

<?php
$info = new SplFileInfo('/path/to/symlink');
if ($info->isLink()) {
echo 'The real path is '.$info->getRealPath();
}
?>

参考

  • SplFileInfo::getRealPath() - ファイルへの絶対パスを取得する


ファイルが読み込み可能か調べる

  • ≪ SplFileInfo::isLink
  • SplFileInfo::isWritable ≫
  • PHP Manual
  • SplFileInfo
  • ファイルが読み込み可能か調べる

SplFileInfo::isReadable

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::isReadable — ファイルが読み込み可能か調べる

説明

public SplFileInfo::isReadable(): bool

ファイルが読み込み可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

読み込み可能である場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isReadable() の例

<?php
$info = new SplFileInfo('readable.jpg');
if ($info->isReadable()) {
echo $info->getFilename() . ' is readable';
}
?>

上の例の出力は、 たとえば以下のようになります。

readable.jpg is readable


エントリが書き込み可能であるかどうかを調べる

  • ≪ SplFileInfo::isReadable
  • SplFileInfo::openFile ≫
  • PHP Manual
  • SplFileInfo
  • エントリが書き込み可能であるかどうかを調べる

SplFileInfo::isWritable

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::isWritable — エントリが書き込み可能であるかどうかを調べる

説明

public SplFileInfo::isWritable(): bool

現在のエントリが書き込み可能かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

書き込み可能な場合に true、そうでない場合に false を返します。

例

例1 SplFileInfo::isWriteable() の例

<?php
$info = new SplFileInfo('locked.jpg');
if (!$info->isWriteable()) {
echo $info->getFilename() . ' is not writeable';
}
?>

上の例の出力は、 たとえば以下のようになります。

locked.jpg is not writeable


ファイルの SplFileObject オブジェクトを取得する

  • ≪ SplFileInfo::isWritable
  • SplFileInfo::setFileClass ≫
  • PHP Manual
  • SplFileInfo
  • ファイルの SplFileObject オブジェクトを取得する

SplFileInfo::openFile

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::openFile — ファイルの SplFileObject オブジェクトを取得する

説明

public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject

ファイルの SplFileObject オブジェクトを作成します。 これが便利なのは、SplFileObject にはファイルを操作するためのさまざまなメソッドが追加されているからです。 SplFileInfo には、 たとえばファイルが書き込み可能かどうかなどといった情報を取得するだけの機能しかありません。

パラメータ

mode

ファイルを開く際のモード。使用できるモードについての説明は fopen() のドキュメントを参照ください。 デフォルトは読み込み専用となります。

useIncludePath

true に設定すると、このファイル名を include_path の中からも探します。

context

コンテキスト についての説明は、 マニュアルの コンテキスト の節を参照ください。

戻り値

オープンしたファイルを SplFileObject オブジェクトで返します。

エラー / 例外

ファイルをオープンできない (アクセス権限が適切でないなど) 場合に RuntimeException が発生します。

変更履歴

バージョン | 説明
8.0.0 | context は、nullable になりました。

例

例1 SplFileInfo::openFile() の例

<?php
$fileinfo = new SplFileInfo('/tmp/foo.txt');

if ($fileinfo->isWritable()) {

$fileobj = $fileinfo->openFile('a');

$fileobj->fwrite("appended this sample text");
}
?>

参考

  • SplFileObject
  • stream_context_create() - ストリームコンテキストを作成する
  • fopen() - ファイルまたは URL をオープンする


SplFileInfo::openFile で使用するクラスを設定する

  • ≪ SplFileInfo::openFile
  • SplFileInfo::setInfoClass ≫
  • PHP Manual
  • SplFileInfo
  • SplFileInfo::openFile で使用するクラスを設定する

SplFileInfo::setFileClass

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::setFileClass — SplFileInfo::openFile() で使用するクラスを設定する

説明

public SplFileInfo::setFileClass(string $class = SplFileObject::class): void

SplFileInfo::openFile() が呼ばれたときに使用する、カスタムクラスを設定します。 このメソッドに渡すクラス名は、SplFileObject あるいはその派生クラスのものでなければいけません。

パラメータ

class

SplFileInfo::openFile() がコールされた際に使用するクラス名。

戻り値

値を返しません。

例

例1 SplFileInfo::setFileClass() の例

<?php
// SplFileObject を継承したクラスを作成します
class MyFoo extends SplFileObject {}

$info = new SplFileInfo(__FILE__);
// 使用するクラスを設定します
$info->setFileClass('MyFoo');
var_dump($info->openFile());
?>

上の例の出力は、 たとえば以下のようになります。

object(MyFoo)#2 (0) { }

参考

  • SplFileInfo::openFile() - ファイルの SplFileObject オブジェクトを取得する


SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する

  • ≪ SplFileInfo::setFileClass
  • SplFileInfo::__toString ≫
  • PHP Manual
  • SplFileInfo
  • SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する

SplFileInfo::setInfoClass

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::setInfoClass — SplFileInfo::getFileInfo() および SplFileInfo::getPathInfo() で使用するクラスを設定する

説明

public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void

このメソッドで、 SplFileInfo::getFileInfo() および SplFileInfo::getPathInfo() がコールされた際に使用するカスタムクラスを設定します。 このメソッドに渡すクラス名は、SplFileInfo あるいはその派生クラスのものでなければいけません。

パラメータ

class

SplFileInfo::getFileInfo() および SplFileInfo::getPathInfo() がコールされた際に使用するクラス名。

戻り値

値を返しません。

例

例1 SplFileInfo::setFileClass() の例

<?php
// SplFileInfo を継承したクラスを定義します
class MyFoo extends SplFileInfo {}

$info = new SplFileInfo('foo');
// 使用するクラス名を設定します
$info->setInfoClass('MyFoo');
var_dump($info->getFileInfo());
?>

上の例の出力は、 たとえば以下のようになります。

object(MyFoo)#2 (0) { }

参考

  • SplFileInfo::getFileInfo() - ファイルの SplFileInfo オブジェクトを取得する


ファイルへのパスを文字列で返す

  • ≪ SplFileInfo::setInfoClass
  • SplFileObject ≫
  • PHP Manual
  • SplFileInfo
  • ファイルへのパスを文字列で返す

SplFileInfo::__toString

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileInfo::__toString — ファイルへのパスを文字列で返す

説明

public SplFileInfo::__toString(): string

このメソッドは、参照するファイルのファイル名を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルへのパスを返します。

例

例1 SplFileInfo::__toString() の例

<?php
$info = new SplFileInfo('foo');
var_dump($info->__toString());
echo $info.PHP_EOL;

$info = new SplFileInfo('/usr/bin/php');
var_dump($info->__toString());
echo $info.PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "foo"
foo
string(12) "/usr/bin/php"
/usr/bin/php


SplFileObject クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

SplFileObject クラスはファイルのためのオブジェクト指向のインターフェイスを提供します。

クラス概要

class SplFileObject extends SplFileInfo implements RecursiveIterator, SeekableIterator {
/* 定数 */
public const int DROP_NEW_LINE;
public const int READ_AHEAD;
public const int SKIP_EMPTY;
public const int READ_CSV;
/* メソッド */
public __construct(
string $filename,
string $mode = "r",
bool $useIncludePath = false,
?resource $context = null
)
public current(): string|array|false
public eof(): bool
public fflush(): bool
public fgetc(): string|false
public fgetcsv(string $separator = ",", string $enclosure = "\"", string $escape = "\\"): array|false
public fgets(): string
public fgetss(string $allowable_tags = ?): string
public flock(int $operation, int &$wouldBlock = null): bool
public fpassthru(): int
public fputcsv(
array $fields,
string $separator = ",",
string $enclosure = "\"",
string $escape = "\\",
string $eol = "\n"
): int|false
public fread(int $length): string|false
public fscanf(string $format, mixed &...$vars): array|int|null
public fseek(int $offset, int $whence = SEEK_SET): int
public fstat(): array
public ftell(): int|false
public ftruncate(int $size): bool
public fwrite(string $data, int $length = 0): int|false
public getChildren(): null
public getCsvControl(): array
public getFlags(): int
public getMaxLineLen(): int
public hasChildren(): false
public key(): int
public next(): void
public rewind(): void
public seek(int $line): void
public setCsvControl(string $separator = ",", string $enclosure = "\"", string $escape = "\\"): void
public setFlags(int $flags): void
public setMaxLineLen(int $maxLength): void
public __toString(): string
public valid(): bool
/* 継承したメソッド */
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

定義済み定数

SplFileObject::DROP_NEW_LINE

行末の改行を読み飛ばします。

SplFileObject::READ_AHEAD

先読み/巻き戻しで読み出します。

SplFileObject::SKIP_EMPTY

ファイルの空行を読み飛ばします。期待通りに動作させるには、READ_AHEAD フラグを有効にしないといけません。

SplFileObject::READ_CSV

CSV 列として行を読み込みます。

目次

  • SplFileObject::__construct — 新しいファイルオブジェクトを作成する
  • SplFileObject::current — ファイルの現在の行を取得する
  • SplFileObject::eof — ファイルの終端に到達しているか調べる
  • SplFileObject::fflush — 出力をファイルにフラッシュする
  • SplFileObject::fgetc — ファイルから文字を取り出す
  • SplFileObject::fgetcsv — ファイルから行を取り出し CSV フィールドとして処理する
  • SplFileObject::fgets — ファイルから 1 行取り出す
  • SplFileObject::fgetss — ファイルから 1 行取り出し HTML タグを取り除く
  • SplFileObject::flock — 簡易なファイルロックを行う
  • SplFileObject::fpassthru — ファイルポインタに残っているデータをすべて出力する
  • SplFileObject::fputcsv — フィールドの配列を CSV の行として書き出す
  • SplFileObject::fread — ファイルから読み取る
  • SplFileObject::fscanf — フォーマットに従ってファイルからの入力をパースする
  • SplFileObject::fseek — ファイルポインタを移動させる
  • SplFileObject::fstat — ファイルの情報を得る
  • SplFileObject::ftell — ファイルポインタの現在位置を返す
  • SplFileObject::ftruncate — ファイルを指定した長さに丸める
  • SplFileObject::fwrite — ファイルに書き込む
  • SplFileObject::getChildren — 用途はなし
  • SplFileObject::getCsvControl — CSV の区切り、囲み文字、エスケープ文字を取得する
  • SplFileObject::getCurrentLine — SplFileObject::fgets のエイリアス
  • SplFileObject::getFlags — SplFileObject のフラグを取得する
  • SplFileObject::getMaxLineLen — 行の最大バイト数を取得する
  • SplFileObject::hasChildren — SplFileObject は子を持ちません
  • SplFileObject::key — 行番号を取得する
  • SplFileObject::next — 次の行を読み出す
  • SplFileObject::rewind — ファイルポインタを先頭に巻き戻す
  • SplFileObject::seek — ファイルポインタを指定行に移動させる
  • SplFileObject::setCsvControl — CSV の区切り文字、囲み文字、エスケープ文字をセットする
  • SplFileObject::setFlags — SplFileObject のフラグをセットする
  • SplFileObject::setMaxLineLen — 読み込む行の最大バイト数をセットする
  • SplFileObject::__toString — 現在の行を文字列として取得する
  • SplFileObject::valid — ファイル終端でないかチェックする


新しいファイルオブジェクトを作成する

  • ≪ SplFileObject
  • SplFileObject::current ≫
  • PHP Manual
  • SplFileObject
  • 新しいファイルオブジェクトを作成する

SplFileObject::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::__construct — 新しいファイルオブジェクトを作成する

説明

public SplFileObject::__construct(
string $filename,
string $mode = "r",
bool $useIncludePath = false,
?resource $context = null
)

新しいファイルオブジェクトを作成します。

パラメータ

filename

読み込むファイル。

ヒント

fopen wrappers が有効の場合、この関数のファイル名として URL を使用することができます。ファイル名の指定方法に関する詳細は fopen() を参照ください。 サポートするプロトコル/ラッパー には、さまざまなラッパーの機能やその使用法、 提供される定義済み変数などの情報がまとめられています。

mode

ファイルをオープンするときのモード。許可されるモードのリストは fopen() を参照。

useIncludePath

filename を探すのに include_path を探索するかどうか。

context

stream_context_create() で作られる有効なコンテキストリソース。

エラー / 例外

filename がオープンできない場合、RuntimeException がスローされます。

filename がディレクトリの場合、LogicException がスローされます。

例

例1 SplFileObject::__construct() の例

この例は現在のファイルをオープンし 1 行ごとに内容を反復処理します。

<?php
$file = new SplFileObject(__FILE__);
foreach ($file as $line_num => $line) {
echo "Line $line_num is $line";
}
?>

上の例の出力は、 たとえば以下のようになります。

Line 0 is <?php
Line 1 is $file = new SplFileObject(__FILE__);
Line 2 is foreach ($file as $line_num => $line) {
Line 3 is     echo "Line $line_num is $line";
Line 4 is }
Line 5 is ?>

参考

  • SplFileInfo::openFile() - ファイルの SplFileObject オブジェクトを取得する
  • fopen() - ファイルまたは URL をオープンする


ファイルの現在の行を取得する

  • ≪ SplFileObject::__construct
  • SplFileObject::eof ≫
  • PHP Manual
  • SplFileObject
  • ファイルの現在の行を取得する

SplFileObject::current

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::current — ファイルの現在の行を取得する

説明

public SplFileObject::current(): string|array|false

ファイルの現在の行を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルの現在の行を取得します。SplFileObject::READ_CSV フラグがセットされている場合、このメソッドは CSV データとして処理された現在の行を格納している配列を返します。 ファイルの終端に達した場合、false を返します。

例

例1 SplFileObject::current() の例

<?php
$file = new SplFileObject(__FILE__);
foreach ($file as $k => $line) {
echo ($file->key() + 1) . ': ' . $file->current();
}
?>

上の例の出力は、 たとえば以下のようになります。

1: <?php
2: $file = new SplFileObject(__FILE__);
3: foreach ($file as $line) {
4:     echo ($file->key() + 1) . ': ' . $file->current();
5: }
6: ?>

参考

  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする


ファイルの終端に到達しているか調べる

  • ≪ SplFileObject::current
  • SplFileObject::fflush ≫
  • PHP Manual
  • SplFileObject
  • ファイルの終端に到達しているか調べる

SplFileObject::eof

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::eof — ファイルの終端に到達しているか調べる

説明

public SplFileObject::eof(): bool

ファイルの終端に到達しているか調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルが終端であれば true、そうでなければ false を返します。

例

例1 SplFileObject::eof() の例

<?php
$file = new SplFileObject("fruits.txt");
while ( ! $file->eof()) {
echo $file->fgets();
}
?>

上の例の出力は、 たとえば以下のようになります。

apple
banana
cherry
date
elderberry

参考

  • SplFileObject::valid() - ファイル終端でないかチェックする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる


出力をファイルにフラッシュする

  • ≪ SplFileObject::eof
  • SplFileObject::fgetc ≫
  • PHP Manual
  • SplFileObject
  • 出力をファイルにフラッシュする

SplFileObject::fflush

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fflush — 出力をファイルにフラッシュする

説明

public SplFileObject::fflush(): bool

バッファリングされたすべての出力をファイルに強制的に書き込みます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SplFileObject::fflush() の例

<?php
$file = new SplFileObject('misc.txt', 'r+');
$file->rewind();
$file->fwrite("Foo");
$file->fflush();
$file->ftruncate($file->ftell());
?>

参考

  • SplFileObject::fwrite() - ファイルに書き込む


ファイルから文字を取り出す

  • ≪ SplFileObject::fflush
  • SplFileObject::fgetcsv ≫
  • PHP Manual
  • SplFileObject
  • ファイルから文字を取り出す

SplFileObject::fgetc

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fgetc — ファイルから文字を取り出す

説明

public SplFileObject::fgetc(): string|false

ファイルから 1 文字取り出す。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルから読み込まれた 1 文字を含む文字列もしくは終端の場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 SplFileObject::fgetc() の例

<?php
$file = new SplFileObject('file.txt');
while (false !== ($char = $file->fgetc())) {
echo "$char\n";
}
?>

参考

  • SplFileObject::fgets() - ファイルから 1 行取り出す


ファイルから行を取り出し CSV フィールドとして処理する

  • ≪ SplFileObject::fgetc
  • SplFileObject::fgets ≫
  • PHP Manual
  • SplFileObject
  • ファイルから行を取り出し CSV フィールドとして処理する

SplFileObject::fgetcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fgetcsv — ファイルから行を取り出し CSV フィールドとして処理する

説明

public SplFileObject::fgetcsv(string $separator = ",", string $enclosure = "\"", string $escape = "\\"): array|false

CSV フォーマットのファイルから行を取り出し読み込まれたフィールドを含む配列を返します。

注意:

この関数は、ロケール設定を考慮します。 LC_CTYPE がたとえば en_US.UTF-8 だった場合、 ファイルの1バイトのエンコーディングは、この関数では間違った読まれ方をする可能性があります。

パラメータ

separator

フィールドの区切り文字 (シングルバイト文字 1 文字のみ)。 デフォルトはカンマもしくは SplFileObject::setCsvControl() を使ってセットされた値です。

enclosure

フィールド囲み文字 (シングルバイト文字 1 文字のみ)。 デフォルトはダブルクォートもしくは SplFileObject::setCsvControl() を使ってセットされた値です。

escape

エスケープ文字 (シングルバイト文字 最大で1文字)。 デフォルトはバックスラッシュ (\) もしくは SplFileObject::setCsvControl() を使ってセットされた値です。 空文字列("")の場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

注意: enclosure の文字は、フィールド内で2回出力される ことでエスケープされます。しかし、 escape 文字はその代替として使えます。 デフォルトのパラメータの値 "" と \" は同じ意味を持ちます。 enclosure の文字を escape 文字でエスケープすることには、 特別な意味はありません。それ自身をエスケープする意味ですらありません。

戻り値

読み込まれたフィールドを含む数値添字配列もしくはエラーのときは false を返します。

注意:

CSV ファイルの空白行は SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE を使わない限り単独の null フィールドで構成される配列として返され、この場合空白行は読み飛ばされます。

変更履歴

バージョン | 説明
7.4.0 | escape パラメータは空文字列を受け入れるようになりました。 この場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

例

例1 SplFileObject::fgetcsv() の例

<?php
$file = new SplFileObject("data.csv");
while (!$file->eof()) {
var_dump($file->fgetcsv());
}
?>

例2 SplFileObject::READ_CSV の例

<?php
$file = new SplFileObject("animals.csv");
$file->setFlags(SplFileObject::READ_CSV);
foreach ($file as $row) {
list($animal, $class, $legs) = $row;
printf("A %s is a %s with %d legs\n", $animal, $class, $legs);
}
?>

animals.csv の内容

crocodile,reptile,4
dolphin,mammal,0
duck,bird,2
koala,mammal,4
salmon,fish,0

上の例の出力は、 たとえば以下のようになります。

A crocodile is a reptile with 4 legs
A dolphin is a mammal with 0 legs
A duck is a bird with 2 legs
A koala is a mammal with 4 legs
A salmon is a fish with 0 legs

参考

  • SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
  • SplFileObject::setFlags() - SplFileObject のフラグをセットする
  • SplFileObject::READ_CSV
  • SplFileObject::current() - ファイルの現在の行を取得する


ファイルから 1 行取り出す

  • ≪ SplFileObject::fgetcsv
  • SplFileObject::fgetss ≫
  • PHP Manual
  • SplFileObject
  • ファイルから 1 行取り出す

SplFileObject::fgets

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fgets — ファイルから 1 行取り出す

説明

public SplFileObject::fgets(): string

ファイルから 1 行取り出します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルから次の行を含む文字列を返します。

エラー / 例外

ファイルが読み込みできない場合 RuntimeException がスローされます。

例

例1 SplFileObject::fgets() の例

この例では file.txt の内容が 1 行ごとに出力されます。

<?php
$file = new SplFileObject("file.txt");
while (!$file->eof()) {
echo $file->fgets();
}
?>

参考

  • fgets() - ファイルポインタから 1 行取得する
  • SplFileObject::fgetss() - ファイルから 1 行取り出し HTML タグを取り除く
  • SplFileObject::fgetc() - ファイルから文字を取り出す
  • SplFileObject::current() - ファイルの現在の行を取得する


ファイルから 1 行取り出し HTML タグを取り除く

  • ≪ SplFileObject::fgets
  • SplFileObject::flock ≫
  • PHP Manual
  • SplFileObject
  • ファイルから 1 行取り出し HTML タグを取り除く

SplFileObject::fgetss

(PHP 5 >= 5.1.0, PHP 7)

SplFileObject::fgetss — ファイルから 1 行取り出し HTML タグを取り除く

警告

この関数は PHP 7.3.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public SplFileObject::fgetss(string $allowable_tags = ?): string

SplFileObject::fgetss() 読み込むテキストから HTML と PHP タグを取り除こうとすること以外、SplFileObject::fgets() と同じです。 この関数は、ある呼び出しから別の呼び出しの間のパースの状態を保持します。 したがって、これは SplFileObject::fgets() の戻り値に対して strip_tags() 関数を呼び出すのと同じではありません。

パラメータ

allowable_tags

オプションのパラメータで、取り除きたくないタグを指定します。

戻り値

HTML と PHP コードが取り除かれたファイルの次の行を含む文字列、もしくは false を返します。

例

例1 SplFileObject::fgetss() の例

<?php
$str = <<<EOD
<html><body>
<p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
</body></html>
Text outside of the HTML block.
EOD;
file_put_contents("sample.php", $str);

$file = new SplFileObject("sample.php");
while (!$file->eof()) {
echo $file->fgetss();
}
?>

上の例の出力は、 たとえば以下のようになります。

Welcome! Today is the  of .

Text outside of the HTML block.

参考

  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • SplFileObject::fgets() - ファイルから 1 行取り出す
  • SplFileObject::fgetc() - ファイルから文字を取り出す
  • SplFileObject::current() - ファイルの現在の行を取得する
  • The string.strip_tags filter


簡易なファイルロックを行う

  • ≪ SplFileObject::fgetss
  • SplFileObject::fpassthru ≫
  • PHP Manual
  • SplFileObject
  • 簡易なファイルロックを行う

SplFileObject::flock

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::flock — 簡易なファイルロックを行う

説明

public SplFileObject::flock(int $operation, int &$wouldBlock = null): bool

flock() と同じ簡易な方法でファイルをロックもしくはロック解除する。

パラメータ

operation

operation は次のいずれかです:

  • 共有ロック (読み手) にするには LOCK_SH。
  • 排他ロック (書き手) にするには LOCK_EX。
  • (共有もしくは排他) ロックを解除するには LOCK_UN。

ロックを試みている間に flock() がブロックすべきでない場合は、上の操作のいずれかに LOCK_NB をビットマスクとして追加できます。

wouldBlock

ロックがブロックされる場合 (errno が EWOULDBLOCK である)、true にセットします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SplFileObject::flock() の例

<?php
$file = new SplFileObject("/tmp/lock.txt", "w");
if ($file->flock(LOCK_EX)) { // 排他ロックを行う
$file->ftruncate(0); // ファイルを丸める
$file->fwrite("ここで何かを書き出します\n");
$file->flock(LOCK_UN); // ロックを解除する
} else {
echo "ロックを取得できませんでした！";
}
?>

参考

  • flock() - 汎用のファイルロックを行う


ファイルポインタに残っているデータをすべて出力する

  • ≪ SplFileObject::flock
  • SplFileObject::fputcsv ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタに残っているデータをすべて出力する

SplFileObject::fpassthru

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fpassthru — ファイルポインタに残っているデータをすべて出力する

説明

public SplFileObject::fpassthru(): int

与えられたファイルポインタの現在位置から終端までを読み込み結果を出力バッファに書き出します。

既にデータをファイルに書き込んでいる場合、ファイルポインタをファイルの始めにリセットするために SplFileObject::rewind() を呼び出すことが必要になる場合があります。

パラメータ

この関数にはパラメータはありません。

戻り値

handle から読み込まれ出力を通して渡された文字数を返します。

例

例1 SplFileObject::fpassthru() の例

<?php

// ファイルをバイナリモードでオープンする
$file = new SplFileObject("./img/ok.png", "rb");

// 正しいヘッダを送出する
header("Content-Type: image/png");
header("Content-Length: " . $file->getSize());

// 画像をダンプしてスクリプトを終了させる
$file->fpassthru();
exit;

?>

参考

  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する


フィールドの配列を CSV の行として書き出す

  • ≪ SplFileObject::fpassthru
  • SplFileObject::fread ≫
  • PHP Manual
  • SplFileObject
  • フィールドの配列を CSV の行として書き出す

SplFileObject::fputcsv

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SplFileObject::fputcsv — フィールドの配列を CSV の行として書き出す

説明

public SplFileObject::fputcsv(
array $fields,
string $separator = ",",
string $enclosure = "\"",
string $escape = "\\",
string $eol = "\n"
): int|false

fields の配列を、CSV の行としてファイルに書き出します。

パラメータ

fields

値の配列。

separator

オプションで指定する、フィールドの区切り文字 (シングルバイト文字 一文字のみ)。

enclosure

オプションで指定する。フィールドの囲み文字 (シングルバイト文字 一文字のみ)。

escape

オプションの escape は、エスケープ文字 (シングルバイト文字 最大で一文字) を指定します。 空文字列 ("") を与えると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構を無効にします。

eol

eol は、 カスタムの行末シーケンスを設定するオプションの引数です。

注意:

enclosure がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。 ただし、その直前に escape がある場合は別です。

戻り値

書き出した文字列の長さを返します。失敗した場合に false を返します。

separator や enclosure が一文字でない場合は false を返し、何もファイルに書き出しません。

エラー / 例外

separator や enclosure が一文字でない場合は E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.1.0 | オプションの引数 eol が追加されました。
7.4.0 | escape パラメータは空文字列を受け入れるようになりました。 この場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

例

例1 SplFileObject::fputcsv() の例

<?php

$list = array (
array('aaa', 'bbb', 'ccc', 'dddd'),
array('123', '456', '789'),
array('"aaa"', '"bbb"')
);

$file = new SplFileObject('file.csv', 'w');

foreach ($list as $fields) {
$file->fputcsv($fields);
}

?>

上の例は、次の内容をファイル file.csv に書き出します。

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

参考

  • fputcsv() - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
  • SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する


ファイルから読み取る

  • ≪ SplFileObject::fputcsv
  • SplFileObject::fscanf ≫
  • PHP Manual
  • SplFileObject
  • ファイルから読み取る

SplFileObject::fread

(PHP 5 >= 5.5.11, PHP 7, PHP 8)

SplFileObject::fread — ファイルから読み取る

説明

public SplFileObject::fread(int $length): string|false

ファイルから与えられたバイト数だけ読み取ります。

パラメータ

length

読み取るバイト数

戻り値

ファイルから読み取った文字列を返します。 失敗した場合に false を返します

例

例1 SplFileObject::fread() の例

<?php
// Get contents of a file into a string
$filename = "/usr/local/something.txt";
$file = new SplFileObject($filename, "r");
$contents = $file->fread($file->getSize());
?>

注意

注意:

SplFileObject::fread() は、 ファイルポインタの現在の位置から読み取ることに注意してください。 ポインタの現在の位置を知るには SplFileObject::ftell() を使い、 ポインタの位置を巻き戻すには、 SplFileObject::rewind() (または SplFileObject::fseek()) を使ってください。

参考

  • fread() - バイナリセーフなファイルの読み込み


フォーマットに従ってファイルからの入力をパースする

  • ≪ SplFileObject::fread
  • SplFileObject::fseek ≫
  • PHP Manual
  • SplFileObject
  • フォーマットに従ってファイルからの入力をパースする

SplFileObject::fscanf

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fscanf — フォーマットに従ってファイルからの入力をパースする

説明

public SplFileObject::fscanf(string $format, mixed &...$vars): array|int|null

ファイルから 1 行読み込み、format に従って解釈します。

format 文字列のホワイトスペースはファイルからの行のホワイトスペースとマッチします。このことが意味するのはフォーマット文字列のタブ (\t) でさえも入力ストリームの 1 つのスペース文字とマッチしてしまうということです。

パラメータ

format

string を解釈するフォーマット。 sprintf() のドキュメントにある説明と比べて、以下の違いがあります。

  • ロケールに対応していません。
  • F、g、G および b はサポートしていません。
  • D は十進数値を表します。
  • i は基数検出つきの整数値を表します。
  • n は処理する文字数を表します。
  • s は、空白文字を読み取ると停止することを示します。
  • argnum$ の代わりに * を指定すると、 この変換仕様に従った値の代入を抑制します。

vars

オプションの割り当て値。

戻り値

このメソッドに渡される引数がひとつしかない場合、処理される値は配列として返されます。そうでなければ、オプションパラメータが渡される場合、メソッドは割り当て値の個数を返します。オプションパラメータは参照渡しでなければなりません。

例

例1 SplFileObject::fscanf() の例

<?php
$file = new SplFileObject("misc.txt");
while ($userinfo = $file->fscanf("%s %s %s")) {
list ($name, $profession, $countrycode) = $userinfo;
// $name $profession $countrycode で何かを行う
}
?>

users.txt の内容

javier   argonaut    pe
hiroshi  sculptor    jp
robert   slacker     us
luigi    florist     it

参考

  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す


ファイルポインタを移動させる

  • ≪ SplFileObject::fscanf
  • SplFileObject::fstat ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタを移動させる

SplFileObject::fseek

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fseek — ファイルポインタを移動させる

説明

public SplFileObject::fseek(int $offset, int $whence = SEEK_SET): int

offset を whence で指定される位置に追加することで、ファイルの始めからバイト単位でファイルポイントを移動させます。

パラメータ

offset

オフセットです。負の値はポインタを戻すために使うことができます。これは SEEK_END が whence の値として使われるときに便利です。

whence

whence の値は次のようなものになります:

  • SEEK_SET - offset バイトに等しい位置にセットします。
  • SEEK_CUR - 現在の位置に offset を加えた位置にセットします。
  • SEEK_END - 終端に offset を加えた位置にセットします。

whence が指定されない場合、SEEK_SET が前提になります。

戻り値

探索が成功した場合は 0、そうでなければ -1 が返されます。終端より先の位置を探索してもエラーにならないことにご注意してください。

例

例1 SplFileObject::fseek() の例

<?php
$file = new SplFileObject("somefile.txt");

// 最初の行を読み込む
$data = $file->fgets();

// ファイルの最初に戻る
// $file->rewind(); と同じ
$file->fseek(0);
?>

参考

  • fseek() - ファイルポインタを移動する


ファイルの情報を得る

  • ≪ SplFileObject::fseek
  • SplFileObject::ftell ≫
  • PHP Manual
  • SplFileObject
  • ファイルの情報を得る

SplFileObject::fstat

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fstat — ファイルの情報を得る

説明

public SplFileObject::fstat(): array

ファイルの統計情報を集めます。fstat() とまったく同じように振る舞います。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルの統計情報の配列を返します; 配列フォーマットの詳細は stat() のマニュアルページを参照ください。

例

例1 SplFileObject::fstat() の例

<?php
$file = new SplFileObject("/etc/passwd");
$stat = $file->fstat();

// 連想配列の部分だけ表示する
print_r(array_slice($stat, 13));

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [dev] => 771
    [ino] => 488704
    [mode] => 33188
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 1114
    [atime] => 1061067181
    [mtime] => 1056136526
    [ctime] => 1056136526
    [blksize] => 4096
    [blocks] => 8
)

参考

  • fstat() - オープンしたファイルポインタからファイルに関する情報を取得する
  • stat() - ファイルに関する情報を取得する


ファイルポインタの現在位置を返す

  • ≪ SplFileObject::fstat
  • SplFileObject::ftruncate ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタの現在位置を返す

SplFileObject::ftell

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::ftell — ファイルポインタの現在位置を返す

説明

public SplFileObject::ftell(): int|false

ファイルストリームにおいて現在のオフセットを表すファイルポインタの現在位置を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイルポインタの位置を整数として、もしくはエラーのときは false を返します。

例

例1 SplFileObject::ftell() の例

<?php
$file = new SplFileObject("/etc/passwd");

// 最初の行を読み込む
$data = $file->fgets();

// どこにいるのか？
echo $file->ftell();
?>

参考

  • ftell() - ファイルの読み書き用ポインタの現在位置を返す


ファイルを指定した長さに丸める

  • ≪ SplFileObject::ftell
  • SplFileObject::fwrite ≫
  • PHP Manual
  • SplFileObject
  • ファイルを指定した長さに丸める

SplFileObject::ftruncate

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::ftruncate — ファイルを指定した長さに丸める

説明

public SplFileObject::ftruncate(int $size): bool

ファイルを size バイトに丸めます。

パラメータ

size

丸めるサイズ。

注意:

size がファイルのサイズより大きい場合、ファイルは null バイトで拡大されます。

size がファイルのサイズより小さい場合、余分なデータは失われます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SplFileObject::ftruncate() の例

<?php
// "Hello World!" が格納されるファイルを作成する
$file = new SplFileObject("/tmp/ftruncate", "w+");
$file->fwrite("Hello World!");

// 5 バイトに丸める
$file->ftruncate(5);

// 巻き戻してデータを読み出す
$file->rewind();
echo $file->fgets();
?>

上の例の出力は、 たとえば以下のようになります。

Hello

参考

  • ftruncate() - ファイルを指定した長さに丸める


ファイルに書き込む

  • ≪ SplFileObject::ftruncate
  • SplFileObject::getChildren ≫
  • PHP Manual
  • SplFileObject
  • ファイルに書き込む

SplFileObject::fwrite

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::fwrite — ファイルに書き込む

説明

public SplFileObject::fwrite(string $data, int $length = 0): int|false

Writes the contents of data to the file

パラメータ

data

ファイルに書き込まれる文字列。

length

length 引数が渡される場合、length バイト分だけ書き込まれた後もしくは data の終端に達するのどちらか早い方の後で書き込みが停止します。

戻り値

書き込まれるバイト数、もしくはエラーの場合 false を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は、失敗した時に0ではなく false を返すようになりました。

例

例1 SplFileObject::fwrite() の例

<?php
$file = new SplFileObject("fwrite.txt", "w");
$written = $file->fwrite("12345");
echo "$written バイトをファイルに書き込みました";
?>

上の例の出力は、 たとえば以下のようになります。

Wrote 5 bytes to file

参考

  • fwrite() - バイナリセーフなファイル書き込み処理


用途はなし

  • ≪ SplFileObject::fwrite
  • SplFileObject::getCsvControl ≫
  • PHP Manual
  • SplFileObject
  • 用途はなし

SplFileObject::getChildren

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::getChildren — 用途はなし

説明

public SplFileObject::getChildren(): null

SplFileObject は子を持たないのでこのメソッドは null を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

null を返します。

参考

  • RecursiveIterator::getChildren() - 現在のエントリのイテレータを返す


CSV の区切り、囲み文字、エスケープ文字を取得する

  • ≪ SplFileObject::getChildren
  • SplFileObject::getCurrentLine ≫
  • PHP Manual
  • SplFileObject
  • CSV の区切り、囲み文字、エスケープ文字を取得する

SplFileObject::getCsvControl

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

SplFileObject::getCsvControl — CSV の区切り、囲み文字、エスケープ文字を取得する

説明

public SplFileObject::getCsvControl(): array

CSV フィールドを処理するのに使われる区切りと囲み文字とエスケープ文字を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

区切りと囲み文字とエスケープ文字を含む数字添字配列を返します。

変更履歴

バージョン | 説明
7.4.0 | エスケープ文字は空文字列でも問題なくなりました。
7.0.10 | 戻り値の配列にエスケープ文字が追加されました。

例

例1 SplFileObject::getCsvControl() の例

<?php
$file = new SplFileObject("data.txt");
print_r($file->getCsvControl());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => ,
    [1] => "
    [2] => \
)

参考

  • SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
  • SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する


SplFileObject::fgets のエイリアス

  • ≪ SplFileObject::getCsvControl
  • SplFileObject::getFlags ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject::fgets のエイリアス

SplFileObject::getCurrentLine

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileObject::getCurrentLine — SplFileObject::fgets() のエイリアス

説明

このメソッドは次のメソッドのエイリアスです。 SplFileObject::fgets()


SplFileObject のフラグを取得する

  • ≪ SplFileObject::getCurrentLine
  • SplFileObject::getMaxLineLen ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject のフラグを取得する

SplFileObject::getFlags

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::getFlags — SplFileObject のフラグを取得する

説明

public SplFileObject::getFlags(): int

SplFileObject のインスタンス用のフラグセットを int 形式で取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

フラグを表す int を返します。

例

例1 SplFileObject::getFlags() の例

<?php
$file = new SplFileObject(__FILE__, "r");

if ($file->getFlags() & SplFileObject::SKIP_EMPTY) {
echo "空行を読み飛ばします\n";
} else {
echo "空行を読み飛ばしません\n";
}

$file->setFlags(SplFileObject::SKIP_EMPTY);

if ($file->getFlags() & SplFileObject::SKIP_EMPTY) {
echo "空行を読み飛ばします\n";
} else {
echo "空行を読み飛ばしません\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

空行を読み飛ばしません
空行を読み飛ばします

参考

  • SplFileObject::setFlags() - SplFileObject のフラグをセットする


行の最大バイト数を取得する

  • ≪ SplFileObject::getFlags
  • SplFileObject::hasChildren ≫
  • PHP Manual
  • SplFileObject
  • 行の最大バイト数を取得する

SplFileObject::getMaxLineLen

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::getMaxLineLen — 行の最大バイト数を取得する

説明

public SplFileObject::getMaxLineLen(): int

SplFileObject::setMaxLineLen() によってセットされる行の最大バイト数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

SplFileObject::setMaxLineLen() でセットされる場合は行の最大バイト数を返します。デフォルトは 0 です。

例

例1 SplFileObject::getMaxLineLen() の例

<?php
$file = new SplFileObject("file.txt");
var_dump($file->getMaxLineLen());

$file->setMaxLineLen(20);
var_dump($file->getMaxLineLen());
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
int(20)

参考

  • SplFileObject::setMaxLineLen() - 読み込む行の最大バイト数をセットする


SplFileObject は子を持ちません

  • ≪ SplFileObject::getMaxLineLen
  • SplFileObject::key ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject は子を持ちません

SplFileObject::hasChildren

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplFileObject::hasChildren — SplFileObject は子を持ちません

説明

public SplFileObject::hasChildren(): false

SplFileObject は子を持たないのでこのメソッドは常に false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

false を返します。

参考

  • RecursiveIterator::hasChildren() - 現在のエントリのイテレータを作れるかどうかを返す


行番号を取得する

  • ≪ SplFileObject::hasChildren
  • SplFileObject::next ≫
  • PHP Manual
  • SplFileObject
  • 行番号を取得する

SplFileObject::key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::key — 行番号を取得する

説明

public SplFileObject::key(): int

現在の行番号を取得します。

注意:

固定長のファイルを読み込むのに SplFileObject::setMaxLineLen() が使われている場合 この数はファイルの実際の行番号を反映しない可能性があります。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の行番号を返します。

例

例1 SplFileObject::key() の例

<?php
$file = new SplFileObject("lipsum.txt");
foreach ($file as $line) {
echo $file->key() . ". " . $line;
}
?>

上の例の出力は、 たとえば以下のようになります。

0. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
1. Duis nec sapien felis, ac sodales nisl.
2. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

例2 SplFileObject::setMaxLineLen() による SplFileObject::key() の例

<?php
$file = new SplFileObject("lipsum.txt");
$file->setMaxLineLen(20);
foreach ($file as $line) {
echo $file->key() . ". " . $line . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

0. Lorem ipsum dolor s
1. it amet, consectetu
2. r adipiscing elit.
3.

4. Duis nec sapien fel
5. is, ac sodales nisl
6. .

7. Lorem ipsum dolor s
8. it amet, consectetu
9. r adipiscing elit.

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする


次の行を読み出す

  • ≪ SplFileObject::key
  • SplFileObject::rewind ≫
  • PHP Manual
  • SplFileObject
  • 次の行を読み出す

SplFileObject::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::next — 次の行を読み出す

説明

public SplFileObject::next(): void

ファイルの次の行に進みます。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 SplFileObject::next() の例

<?php
// 行単位でファイルを読み込む
$file = new SplFileObject("misc.txt");
while (!$file->eof()) {
echo $file->current();
$file->next();
}
?>

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする


ファイルポインタを先頭に巻き戻す

  • ≪ SplFileObject::next
  • SplFileObject::seek ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタを先頭に巻き戻す

SplFileObject::rewind

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::rewind — ファイルポインタを先頭に巻き戻す

説明

public SplFileObject::rewind(): void

ファイルポインタを先頭に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

巻き戻しができない場合 RuntimeException がスローされます。

例

例1 SplFileObject::rewind() の例

<?php
$file = new SplFileObject("misc.txt");

// ファイル全体をループする
foreach ($file as $line) { }

// 最初の行に巻き戻す
$file->rewind();

// 最初の行を出力する
echo $file->current();
?>

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::valid() - ファイル終端でないかチェックする


ファイルポインタを指定行に移動させる

  • ≪ SplFileObject::rewind
  • SplFileObject::setCsvControl ≫
  • PHP Manual
  • SplFileObject
  • ファイルポインタを指定行に移動させる

SplFileObject::seek

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::seek — ファイルポインタを指定行に移動させる

説明

public SplFileObject::seek(int $line): void

ファイルポインタを指定行に移動させます。

パラメータ

line

ゼロを起点とした移動させる行数。

戻り値

値を返しません。

エラー / 例外

line が負の値の場合、LogicException がスローされます。

例

例1 SplFileObject::seek() の例

この例はポジション 2 で見つかるスクリプトの第 3 行目を出力します。

<?php
$file = new SplFileObject(__FILE__);
$file->seek(2);
echo $file->current();
?>

上の例の出力は、 たとえば以下のようになります。

$file->seek(2);

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す
  • SplFileObject::valid() - ファイル終端でないかチェックする


CSV の区切り文字、囲み文字、エスケープ文字をセットする

  • ≪ SplFileObject::seek
  • SplFileObject::setFlags ≫
  • PHP Manual
  • SplFileObject
  • CSV の区切り文字、囲み文字、エスケープ文字をセットする

SplFileObject::setCsvControl

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

SplFileObject::setCsvControl — CSV の区切り文字、囲み文字、エスケープ文字をセットする

説明

public SplFileObject::setCsvControl(string $separator = ",", string $enclosure = "\"", string $escape = "\\"): void

CSV フィールド処理用の区切り文字と囲み文字とエスケープ文字をセットします。

パラメータ

separator

フィールドの区切り文字 (シングルバイト文字 1 文字のみ)。

enclosure

フィールドの囲み文字 (シングルバイト文字 1 文字のみ)。

escape

フィールドのエスケープ文字 (シングルバイト文字 最大で1文字)。 空文字列("")を指定すると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

戻り値

値を返しません。

変更履歴

バージョン | 説明
7.4.0 | escape パラメータは空文字列を受け入れるようになりました。 この場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

例

例1 SplFileObject::setCsvControl() の例

<?php
$file = new SplFileObject("data.csv");
$file->setFlags(SplFileObject::READ_CSV);
$file->setCsvControl('|');
foreach ($file as $row) {
list ($fruit, $quantity) = $row;
// Do something with values
}
?>

data.csv の内容

<?php
apples|20
bananas|14
cherries|87
?>

参考

  • SplFileObject::getCsvControl() - CSV の区切り、囲み文字、エスケープ文字を取得する
  • SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する


SplFileObject のフラグをセットする

  • ≪ SplFileObject::setCsvControl
  • SplFileObject::setMaxLineLen ≫
  • PHP Manual
  • SplFileObject
  • SplFileObject のフラグをセットする

SplFileObject::setFlags

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::setFlags — SplFileObject のフラグをセットする

説明

public SplFileObject::setFlags(int $flags): void

SplFileObject によって使われるフラグをセットします。

パラメータ

flags

セットするフラグのビットマスク。 利用可能なフラグは SplFileObject の定数 を参照ください。

戻り値

値を返しません。

例

例1 SplFileObject::setFlags() の例

<?php
$file = new SplFileObject("data.csv");
$file->setFlags(SplFileObject::READ_CSV);
foreach ($file as $fields) {
var_dump($fields);
}
?>

参考

  • SplFileObject::getFlags() - SplFileObject のフラグを取得する


読み込む行の最大バイト数をセットする

  • ≪ SplFileObject::setFlags
  • SplFileObject::__toString ≫
  • PHP Manual
  • SplFileObject
  • 読み込む行の最大バイト数をセットする

SplFileObject::setMaxLineLen

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::setMaxLineLen — 読み込む行の最大バイト数をセットする

説明

public SplFileObject::setMaxLineLen(int $maxLength): void

読み込む行の最大バイト数をセットします。

パラメータ

maxLength

行の最大バイト数。

戻り値

値を返しません。

エラー / 例外

maxLength がゼロより小さい場合に DomainException をスローします。

例

例1 SplFileObject::setMaxLineLen() の例

<?php
$file = new SplFileObject("lipsum.txt");
$file->setMaxLineLen(20);
foreach ($file as $line) {
echo $line . "\n";
}
?>

lipsum.txt の内容

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Duis nec sapien felis, ac sodales nisl.
Nulla vitae magna vitae purus aliquet consequat.

上の例の出力は、 たとえば以下のようになります。

Lorem ipsum dolor s
it amet, consectetu
r adipiscing elit.

Duis nec sapien fel
is, ac sodales nisl
.

Nulla vitae magna v
itae purus aliquet
consequat.

参考

  • SplFileObject::getMaxLineLen() - 行の最大バイト数を取得する


現在の行を文字列として取得する

  • ≪ SplFileObject::setMaxLineLen
  • SplFileObject::valid ≫
  • PHP Manual
  • SplFileObject
  • 現在の行を文字列として取得する

SplFileObject::__toString

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::__toString — 現在の行を文字列として取得する

説明

public SplFileObject::__toString(): string

このメソッドは、現在の行を文字列として取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の行を文字列で返します。

変更履歴

バージョン | 説明
8.1.14, 8.2.1 | SplFileObject::fgets() のエイリアスから、 SplFileObject::current() の実装に変わりました。 この実装は、 SplFileObject::READ_CSV フラグを設定すると、 CSV の文字列を返します。
7.2.19, 7.3.6 | SplFileObject::current() のエイリアスから、 SplFileObject::fgets() のエイリアスに変わりました。


ファイル終端でないかチェックする

  • ≪ SplFileObject::__toString
  • SplTempFileObject ≫
  • PHP Manual
  • SplFileObject
  • ファイル終端でないかチェックする

SplFileObject::valid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplFileObject::valid — ファイル終端でないかチェックする

説明

public SplFileObject::valid(): bool

ファイル終端に到達したかチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

ファイル終端に到達していなければ true、そうでなければ false を返します。

例

例1 SplFileObject::valid() の例

<?php
// Loop over a file, line by line
$file = new SplFileObject("file.txt");
while ($file->valid()) {
echo $file->fgets();
}
?>

参考

  • SplFileObject::current() - ファイルの現在の行を取得する
  • SplFileObject::key() - 行番号を取得する
  • SplFileObject::seek() - ファイルポインタを指定行に移動させる
  • SplFileObject::next() - 次の行を読み出す
  • SplFileObject::rewind() - ファイルポインタを先頭に巻き戻す


SplTempFileObject クラス

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

はじめに

SplTempFileObject クラスは、一時ファイルへのオブジェクト指向インターフェイスを提供します。

クラス概要

class SplTempFileObject extends SplFileObject {
/* 継承した定数 */
public const int SplFileObject::DROP_NEW_LINE;
public const int SplFileObject::READ_AHEAD;
public const int SplFileObject::SKIP_EMPTY;
public const int SplFileObject::READ_CSV;
/* メソッド */
public __construct(int $maxMemory = 2 * 1024 * 1024)
/* 継承したメソッド */
public SplFileObject::current(): string|array|false
public SplFileObject::eof(): bool
public SplFileObject::fflush(): bool
public SplFileObject::fgetc(): string|false
public SplFileObject::fgetcsv(string $separator = ",", string $enclosure = "\"", string $escape = "\\"): array|false
public SplFileObject::fgets(): string
public SplFileObject::fgetss(string $allowable_tags = ?): string
public SplFileObject::flock(int $operation, int &$wouldBlock = null): bool
public SplFileObject::fpassthru(): int
public SplFileObject::fputcsv(
array $fields,
string $separator = ",",
string $enclosure = "\"",
string $escape = "\\",
string $eol = "\n"
): int|false
public SplFileObject::fread(int $length): string|false
public SplFileObject::fscanf(string $format, mixed &...$vars): array|int|null
public SplFileObject::fseek(int $offset, int $whence = SEEK_SET): int
public SplFileObject::fstat(): array
public SplFileObject::ftell(): int|false
public SplFileObject::ftruncate(int $size): bool
public SplFileObject::fwrite(string $data, int $length = 0): int|false
public SplFileObject::getChildren(): null
public SplFileObject::getCsvControl(): array
public SplFileObject::getFlags(): int
public SplFileObject::getMaxLineLen(): int
public SplFileObject::hasChildren(): false
public SplFileObject::key(): int
public SplFileObject::next(): void
public SplFileObject::rewind(): void
public SplFileObject::seek(int $line): void
public SplFileObject::setCsvControl(string $separator = ",", string $enclosure = "\"", string $escape = "\\"): void
public SplFileObject::setFlags(int $flags): void
public SplFileObject::setMaxLineLen(int $maxLength): void
public SplFileObject::__toString(): string
public SplFileObject::valid(): bool
public SplFileInfo::getATime(): int|false
public SplFileInfo::getBasename(string $suffix = ""): string
public SplFileInfo::getCTime(): int|false
public SplFileInfo::getExtension(): string
public SplFileInfo::getFileInfo(?string $class = null): SplFileInfo
public SplFileInfo::getFilename(): string
public SplFileInfo::getGroup(): int|false
public SplFileInfo::getInode(): int|false
public SplFileInfo::getLinkTarget(): string|false
public SplFileInfo::getMTime(): int|false
public SplFileInfo::getOwner(): int|false
public SplFileInfo::getPath(): string
public SplFileInfo::getPathInfo(?string $class = null): ?SplFileInfo
public SplFileInfo::getPathname(): string
public SplFileInfo::getPerms(): int|false
public SplFileInfo::getRealPath(): string|false
public SplFileInfo::getSize(): int|false
public SplFileInfo::getType(): string|false
public SplFileInfo::isDir(): bool
public SplFileInfo::isExecutable(): bool
public SplFileInfo::isFile(): bool
public SplFileInfo::isLink(): bool
public SplFileInfo::isReadable(): bool
public SplFileInfo::isWritable(): bool
public SplFileInfo::openFile(string $mode = "r", bool $useIncludePath = false, ?resource $context = null): SplFileObject
public SplFileInfo::setFileClass(string $class = SplFileObject::class): void
public SplFileInfo::setInfoClass(string $class = SplFileInfo::class): void
public SplFileInfo::__toString(): string
}

目次

  • SplTempFileObject::__construct — 新しい一時ファイルオブジェクトを作成する


新しい一時ファイルオブジェクトを作成する

  • ≪ SplTempFileObject
  • その他のクラスおよびインターフェイス ≫
  • PHP Manual
  • SplTempFileObject
  • 新しい一時ファイルオブジェクトを作成する

SplTempFileObject::__construct

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SplTempFileObject::__construct — 新しい一時ファイルオブジェクトを作成する

説明

public SplTempFileObject::__construct(int $maxMemory = 2 * 1024 * 1024)

新しい一時ファイルオブジェクトを作成します。

パラメータ

maxMemory

一時ファイルに使うメモリの最大量(バイト単位、デフォルトは 2 MB)。 一時ファイルがこのサイズを越える場合、ファイルはシステムの一時ディレクトリに移動させられます。

maxMemory が負の値である場合、 メモリだけが使われます。maxMemory がゼロの場合、メモリは使われません。

エラー / 例外

エラーが起きる場合 RuntimeException がスローされます。

例

例1 SplTempFileObject() の例

この例では読み書きできるメモリで一時ファイルが書き込まれます。

<?php
$temp = new SplTempFileObject();
$temp->fwrite("これは最初の行で\n");
$temp->fwrite("そしてこれは 2 番目の行です。\n");
echo "一時ファイルに " . $temp->ftell() . " バイトが書き込まれました。\n\n";

// 先頭に巻き戻し、書かれた内容を読み取る
$temp->rewind();
foreach ($temp as $line) {
echo $line;
}
?>

上の例の出力は、 たとえば以下のようになります。

一時ファイルに 47 バイト書き込まれました。

これは最初の行で
そしてこれは 2 番目の行です。

参考

  • SplFileObject
  • PHP 入出力ストリーム (php://temp および php://memory について)


その他のクラスおよびインターフェイス

目次

  • ArrayObject
  • SplObserver
  • SplSubject

他の SPL カテゴリにあてはまらないクラスおよびインターフェイス群です。


ArrayObject クラス

(PHP 5, PHP 7, PHP 8)

はじめに

このクラスは、オブジェクトを配列として動作させます。

クラス概要

class ArrayObject implements IteratorAggregate, ArrayAccess, Serializable, Countable {
/* 定数 */
public const int STD_PROP_LIST;
public const int ARRAY_AS_PROPS;
/* メソッド */
public __construct(array|object $array = [], int $flags = 0, string $iteratorClass = ArrayIterator::class)
public append(mixed $value): void
public asort(int $flags = SORT_REGULAR): true
public count(): int
public exchangeArray(array|object $array): array
public getArrayCopy(): array
public getFlags(): int
public getIterator(): Iterator
public getIteratorClass(): string
public ksort(int $flags = SORT_REGULAR): true
public natcasesort(): true
public natsort(): true
public offsetExists(mixed $key): bool
public offsetGet(mixed $key): mixed
public offsetSet(mixed $key, mixed $value): void
public offsetUnset(mixed $key): void
public serialize(): string
public setFlags(int $flags): void
public setIteratorClass(string $iteratorClass): void
public uasort(callable $callback): true
public uksort(callable $callback): true
public unserialize(string $data): void
}

定義済み定数

ArrayObject の定数

ArrayObject::STD_PROP_LIST

オブジェクトのプロパティは (var_dump(), foreach などで) 配列としてアクセスしたときと同じ機能を持ちます

ArrayObject::ARRAY_AS_PROPS

オブジェクトのエントリはプロパティとしてアクセスできます(読み書き可)。 ArrayObject クラスはオブジェクトにアクセスするのに独自のロジックを使います。よって、動的なプロパティを読み書きしようとしても警告やエラーは発生しません。

目次

  • ArrayObject::append — 値を追加する
  • ArrayObject::asort — 値でエントリをソートする
  • ArrayObject::__construct — 新規配列オブジェクトを生成する
  • ArrayObject::count — ArrayObject の public プロパティの数を取得する
  • ArrayObject::exchangeArray — 配列を別の配列と交換する
  • ArrayObject::getArrayCopy — ArrayObject のコピーを作成する
  • ArrayObject::getFlags — 振る舞いのフラグを取得する
  • ArrayObject::getIterator — ArrayObject インスタンスから新規イテレータを生成する
  • ArrayObject::getIteratorClass — ArrayObject のイテレータクラス名を取得する
  • ArrayObject::ksort — キーでエントリをソートする
  • ArrayObject::natcasesort — 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natsort — "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::offsetExists — 要求されたインデックスが存在するかどうかを返す
  • ArrayObject::offsetGet — 指定したインデックスの値を返す
  • ArrayObject::offsetSet — 指定したインデックスに新しい値をセットする
  • ArrayObject::offsetUnset — 指定したインデックスの値を解除する
  • ArrayObject::serialize — ArrayObject をシリアライズする
  • ArrayObject::setFlags — 処理フラグを設定する
  • ArrayObject::setIteratorClass — ArrayObject のイテレータクラス名を設定する
  • ArrayObject::uasort — ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort — ユーザー定義の比較関数を使って、キーでエントリをソートする
  • ArrayObject::unserialize — ArrayObject をアンシリアライズする


値を追加する

  • ≪ ArrayObject
  • ArrayObject::asort ≫
  • PHP Manual
  • ArrayObject
  • 値を追加する

ArrayObject::append

(PHP 5, PHP 7, PHP 8)

ArrayObject::append — 値を追加する

説明

public ArrayObject::append(mixed $value): void

新しい値を最後の要素として追加します。

注意:

このメソッドは、ArrayObject をオブジェクトから作成した場合にはコールできません。 かわりに ArrayObject::offsetSet() を使用します。

パラメータ

value

追加する値。

戻り値

値を返しません。

例

例1 ArrayObject::append() の例

<?php
$arrayobj = new ArrayObject(array('first','second','third'));
$arrayobj->append('fourth');
$arrayobj->append(array('five', 'six'));
var_dump($arrayobj);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (5) {
  [0]=>
  string(5) "first"
  [1]=>
  string(6) "second"
  [2]=>
  string(5) "third"
  [3]=>
  string(6) "fourth"
  [4]=>
  array(2) {
    [0]=>
    string(4) "five"
    [1]=>
    string(3) "six"
  }
}

参考

  • ArrayObject::offsetSet() - 指定したインデックスに新しい値をセットする


値でエントリをソートする

  • ≪ ArrayObject::append
  • ArrayObject::__construct ≫
  • PHP Manual
  • ArrayObject
  • 値でエントリをソートする

ArrayObject::asort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayObject::asort — 値でエントリをソートする

説明

public ArrayObject::asort(int $flags = SORT_REGULAR): true

エントリを昇順にソートします。 キーとそれに対応する値の関連は保持されたままとなります。

これは主に、連想配列など実際の要素の並びが重要となる場合のソートで使います。

パラメータ

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 ArrayObject::asort() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
$fruitArrayObject = new ArrayObject($fruits);
$fruitArrayObject->asort();

foreach ($fruitArrayObject as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

c = apple
b = banana
d = lemon
a = orange

フルーツがアルファベット順で並べ替えられ、 各エントリに対応するキーもそれにあわせて並べ替えられます。

参考

  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする
  • asort() - 連想キーと要素との関係を維持しつつ配列を昇順にソートする


新規配列オブジェクトを生成する

  • ≪ ArrayObject::asort
  • ArrayObject::count ≫
  • PHP Manual
  • ArrayObject
  • 新規配列オブジェクトを生成する

ArrayObject::__construct

(PHP 5, PHP 7, PHP 8)

ArrayObject::__construct — 新規配列オブジェクトを生成する

説明

public ArrayObject::__construct(array|object $array = [], int $flags = 0, string $iteratorClass = ArrayIterator::class)

新規配列オブジェクトを生成します。

パラメータ

array

array には、 配列あるいはオブジェクトを指定することができます。

flags

ArrayObject オブジェクトの振る舞いを制御するフラグ。 ArrayObject::setFlags() を参照ください。

iteratorClass

ArrayObject オブジェクトの反復処理に使用するクラスを指定します。 ここで指定するクラスは、 ArrayIterator を実装していなければなりません。

例

例1 ArrayObject::__construct() の例

<?php
$array = array('1' => 'one',
'2' => 'two',
'3' => 'three');

$arrayobject = new ArrayObject($array);

var_dump($arrayobject);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (3) {
  [1]=>
  string(3) "one"
  [2]=>
  string(3) "two"
  [3]=>
  string(5) "three"
}

参考

  • ArrayObject::setflags() - 処理フラグを設定する


ArrayObject の public プロパティの数を取得する

  • ≪ ArrayObject::__construct
  • ArrayObject::exchangeArray ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject の public プロパティの数を取得する

ArrayObject::count

(PHP 5, PHP 7, PHP 8)

ArrayObject::count — ArrayObject の public プロパティの数を取得する

説明

public ArrayObject::count(): int

ArrayObject の public プロパティの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ArrayObject の public プロパティの数を返します。

注意:

ArrayObject を配列から作成した場合は、すべてのプロパティが public となります。

例

例1 ArrayObject::count() の例

<?php
class Example {
public $public = 'prop:public';
private $prv = 'prop:private';
protected $prt = 'prop:protected';
}

$arrayobj = new ArrayObject(new Example());
var_dump($arrayobj->count());

$arrayobj = new ArrayObject(array('first','second','third'));
var_dump($arrayobj->count());
?>

上の例の出力は以下となります。

int(1)
int(3)


配列を別の配列と交換する

  • ≪ ArrayObject::count
  • ArrayObject::getArrayCopy ≫
  • PHP Manual
  • ArrayObject
  • 配列を別の配列と交換する

ArrayObject::exchangeArray

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayObject::exchangeArray — 配列を別の配列と交換する

説明

public ArrayObject::exchangeArray(array|object $array): array

現在の配列を、別の配列あるいはオブジェクトと交換します。

パラメータ

array

現在の配列と交換する配列あるいはオブジェクト。

戻り値

元の配列を返します。

例

例1 ArrayObject::exchangeArray() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);
// ヨーロッパの都市の配列
$locations = array('Amsterdam', 'Paris', 'London');

$fruitsArrayObject = new ArrayObject($fruits);

// フルーツを都市と交換します
$old = $fruitsArrayObject->exchangeArray($locations);
print_r($old);
print_r($fruitsArrayObject);

?>

上の例の出力は以下となります。

Array
(
    [lemons] => 1
    [oranges] => 4
    [bananas] => 5
    [apples] => 10
)
ArrayObject Object
(
    [0] => Amsterdam
    [1] => Paris
    [2] => London
)


ArrayObject のコピーを作成する

  • ≪ ArrayObject::exchangeArray
  • ArrayObject::getFlags ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject のコピーを作成する

ArrayObject::getArrayCopy

(PHP 5, PHP 7, PHP 8)

ArrayObject::getArrayCopy — ArrayObject のコピーを作成する

説明

public ArrayObject::getArrayCopy(): array

ArrayObject を配列にエクスポートします。

パラメータ

この関数にはパラメータはありません。

戻り値

配列のコピーを返します。ArrayObject がオブジェクトを参照している場合は、 オブジェクトのプロパティの配列を返します。

例

例1 ArrayObject::getArrayCopy() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);
$fruitsArrayObject['pears'] = 4;

// 配列のコピーを作成します
$copy = $fruitsArrayObject->getArrayCopy();
print_r($copy);

?>

上の例の出力は以下となります。

Array
(
    [lemons] => 1
    [oranges] => 4
    [bananas] => 5
    [apples] => 10
    [pears] => 4
)


振る舞いのフラグを取得する

  • ≪ ArrayObject::getArrayCopy
  • ArrayObject::getIterator ≫
  • PHP Manual
  • ArrayObject
  • 振る舞いのフラグを取得する

ArrayObject::getFlags

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayObject::getFlags — 振る舞いのフラグを取得する

説明

public ArrayObject::getFlags(): int

ArrayObject の振る舞いのフラグを取得します。 利用可能なフラグの一覧は、 ArrayObject::setFlags メソッドを参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

ArrayObject の振る舞いのフラグを返します。

例

例1 ArrayObject::getFlags() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// 現在のフラグを取得します
$flags = $fruitsArrayObject->getFlags();
var_dump($flags);

// 新しいフラグを設定します
$fruitsArrayObject->setFlags(ArrayObject::ARRAY_AS_PROPS);

// 新しいフラグを取得します
$flags = $fruitsArrayObject->getFlags();
var_dump($flags);
?>

上の例の出力は以下となります。

int(0)
int(2)

参考

  • ArrayObject::setFlags() - 処理フラグを設定する


ArrayObject インスタンスから新規イテレータを生成する

  • ≪ ArrayObject::getFlags
  • ArrayObject::getIteratorClass ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject インスタンスから新規イテレータを生成する

ArrayObject::getIterator

(PHP 5, PHP 7, PHP 8)

ArrayObject::getIterator — ArrayObject インスタンスから新規イテレータを生成する

説明

public ArrayObject::getIterator(): Iterator

新しいイテレータを ArrayObject インスタンスから作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

ArrayObject からイテレータを返します。

例

例1 ArrayObject::getIterator() の例

<?php
$array = array('1' => 'one',
'2' => 'two',
'3' => 'three');

$arrayobject = new ArrayObject($array);

$iterator = $arrayobject->getIterator();

while($iterator->valid()) {
echo $iterator->key() . ' => ' . $iterator->current() . "\n";

$iterator->next();
}
?>

上の例の出力は以下となります。

1 => one
2 => two
3 => three


ArrayObject のイテレータクラス名を取得する

  • ≪ ArrayObject::getIterator
  • ArrayObject::ksort ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject のイテレータクラス名を取得する

ArrayObject::getIteratorClass

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayObject::getIteratorClass — ArrayObject のイテレータクラス名を取得する

説明

public ArrayObject::getIteratorClass(): string

配列イテレータのクラス名を取得します。これは ArrayObject::getIterator() で使います。

パラメータ

この関数にはパラメータはありません。

戻り値

このオブジェクトの反復処理に使うイテレータのクラス名を返します。

例

例1 ArrayObject::getIteratorClass() の例

<?php
// 独自のイテレータ (ArrayIterator を継承したもの)
class MyArrayIterator extends ArrayIterator {
// 独自の実装
}

// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// 現在のクラス名を取得します
$className = $fruitsArrayObject->getIteratorClass();
var_dump($className);

// 新しいクラス名を設定します
$fruitsArrayObject->setIteratorClass('MyArrayIterator');

// 新しいイテレータクラス名を取得します
$className = $fruitsArrayObject->getIteratorClass();
var_dump($className);
?>

上の例の出力は以下となります。

string(13) "ArrayIterator"
string(15) "MyArrayIterator"

参考

  • ArrayObject::setIteratorClass メソッド


キーでエントリをソートする

  • ≪ ArrayObject::getIteratorClass
  • ArrayObject::natcasesort ≫
  • PHP Manual
  • ArrayObject
  • キーでエントリをソートする

ArrayObject::ksort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayObject::ksort — キーでエントリをソートする

説明

public ArrayObject::ksort(int $flags = SORT_REGULAR): true

キーでエントリをソートし、キーと値の関係は保持します。 主に連想配列で有用です。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 ArrayObject::ksort() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
$fruitArrayObject = new ArrayObject($fruits);
$fruitArrayObject->ksort();

foreach ($fruitArrayObject as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

a = orange
b = banana
c = apple
d = lemon

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする
  • ksort() - 配列をキーで昇順にソートする


大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする

  • ≪ ArrayObject::ksort
  • ArrayObject::natsort ≫
  • PHP Manual
  • ArrayObject
  • 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする

ArrayObject::natcasesort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayObject::natcasesort — 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする

説明

public ArrayObject::natcasesort(): true

このメソッドは、大文字小文字を区別しない ArrayObject::natsort です。

このメソッドは、英数字からなる文字列を人間が並び替えるのと同じようなアルゴリズムでソートし、 キーと値の対応は保持します。このようなソートのことを "自然順" と呼びます。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 ArrayObject::natcasesort() の例

<?php
$array = array('IMG0.png', 'img12.png', 'img10.png', 'img2.png', 'img1.png', 'IMG3.png');

$arr1 = new ArrayObject($array);
$arr2 = clone $arr1;

$arr1->asort();
echo "Standard sorting\n";
print_r($arr1);

$arr2->natcasesort();
echo "\nNatural order sorting (case-insensitive)\n";
print_r($arr2);
?>

上の例の出力は以下となります。

Standard sorting
ArrayObject Object
(
    [0] => IMG0.png
    [5] => IMG3.png
    [4] => img1.png
    [2] => img10.png
    [1] => img12.png
    [3] => img2.png
)

Natural order sorting (case-insensitive)
ArrayObject Object
(
    [0] => IMG0.png
    [4] => img1.png
    [3] => img2.png
    [5] => IMG3.png
    [2] => img10.png
    [1] => img12.png
)

より詳細な情報は、Martin Pool の » Natural Order String Comparison を参照ください。

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする
  • natcasesort() - 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする


"自然順" アルゴリズムでエントリをソートする

  • ≪ ArrayObject::natcasesort
  • ArrayObject::offsetExists ≫
  • PHP Manual
  • ArrayObject
  • "自然順" アルゴリズムでエントリをソートする

ArrayObject::natsort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayObject::natsort — "自然順" アルゴリズムでエントリをソートする

説明

public ArrayObject::natsort(): true

このメソッドは、英数字からなる文字列を人間が並び替えるのと同じようなアルゴリズムでソートし、 キーと値の対応は保持します。このようなソートのことを "自然順" と呼びます。 このアルゴリズムと、コンピュータの通常の文字列ソートアルゴリズム (ArrayObject::asort で使われているもの) の違いは、以下のサンプルを参照ください。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 ArrayObject::natsort() の例

<?php
$array = array("img12.png", "img10.png", "img2.png", "img1.png");

$arr1 = new ArrayObject($array);
$arr2 = clone $arr1;

$arr1->asort();
echo "Standard sorting\n";
print_r($arr1);

$arr2->natsort();
echo "\nNatural order sorting\n";
print_r($arr2);
?>

上の例の出力は以下となります。

Standard sorting
ArrayObject Object
(
    [3] => img1.png
    [1] => img10.png
    [0] => img12.png
    [2] => img2.png
)

Natural order sorting
ArrayObject Object
(
    [3] => img1.png
    [2] => img2.png
    [1] => img10.png
    [0] => img12.png
)

より詳細な情報は、Martin Pool の » Natural Order String Comparison を参照ください。

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする
  • natsort() - "自然順"アルゴリズムで配列をソートする


要求されたインデックスが存在するかどうかを返す

  • ≪ ArrayObject::natsort
  • ArrayObject::offsetGet ≫
  • PHP Manual
  • ArrayObject
  • 要求されたインデックスが存在するかどうかを返す

ArrayObject::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayObject::offsetExists — 要求されたインデックスが存在するかどうかを返す

説明

public ArrayObject::offsetExists(mixed $key): bool

パラメータ

key

調べたいインデックス。

戻り値

指定したインデックスが存在する場合に true、それ以外の場合に false を返します。

例

例1 ArrayObject::offsetExists() の例

<?php
$arrayobj = new ArrayObject(array('zero', 'one', 'example'=>'e.g.'));
var_dump($arrayobj->offsetExists(1));
var_dump($arrayobj->offsetExists('example'));
var_dump($arrayobj->offsetExists('notfound'));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)


指定したインデックスの値を返す

  • ≪ ArrayObject::offsetExists
  • ArrayObject::offsetSet ≫
  • PHP Manual
  • ArrayObject
  • 指定したインデックスの値を返す

ArrayObject::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayObject::offsetGet — 指定したインデックスの値を返す

説明

public ArrayObject::offsetGet(mixed $key): mixed

パラメータ

key

値のインデックス。

戻り値

指定したインデックスの値、あるいは null を返します。

エラー / 例外

指定したインデックスが存在しない場合に E_NOTICE が発生します。

例

例1 ArrayObject::offsetGet() の例

<?php
$arrayobj = new ArrayObject(array('zero', 7, 'example'=>'e.g.'));
var_dump($arrayobj->offsetGet(1));
var_dump($arrayobj->offsetGet('example'));
var_dump($arrayobj->offsetExists('notfound'));
?>

上の例の出力は以下となります。

int(7)
string(4) "e.g."
bool(false)


指定したインデックスに新しい値をセットする

  • ≪ ArrayObject::offsetGet
  • ArrayObject::offsetUnset ≫
  • PHP Manual
  • ArrayObject
  • 指定したインデックスに新しい値をセットする

ArrayObject::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayObject::offsetSet — 指定したインデックスに新しい値をセットする

説明

public ArrayObject::offsetSet(mixed $key, mixed $value): void

指定したインデックスに新しい値を設定します。

パラメータ

key

設定したいインデックス。

value

key の新しい値。

戻り値

値を返しません。

例

例1 ArrayObject::offsetSet() の例

<?php
class Example {
public $property = 'prop:public';
}
$arrayobj = new ArrayObject(new Example());
$arrayobj->offsetSet(4, 'four');
$arrayobj->offsetSet('group', array('g1', 'g2'));
var_dump($arrayobj);

$arrayobj = new ArrayObject(array('zero','one'));
$arrayobj->offsetSet(null, 'last');
var_dump($arrayobj);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (3) {
  ["property"]=>
  string(11) "prop:public"
  [4]=>
  string(4) "four"
  ["group"]=>
  array(2) {
    [0]=>
    string(2) "g1"
    [1]=>
    string(2) "g2"
  }
}
object(ArrayObject)#3 (3) {
  [0]=>
  string(4) "zero"
  [1]=>
  string(3) "one"
  [2]=>
  string(4) "last"
}

参考

  • ArrayObject::append() - 値を追加する


指定したインデックスの値を解除する

  • ≪ ArrayObject::offsetSet
  • ArrayObject::serialize ≫
  • PHP Manual
  • ArrayObject
  • 指定したインデックスの値を解除する

ArrayObject::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayObject::offsetUnset — 指定したインデックスの値を解除する

説明

public ArrayObject::offsetUnset(mixed $key): void

指定したインデックスの値を解除します。

パラメータ

key

解除したいインデックス。

戻り値

値を返しません。

例

例1 ArrayObject::offsetUnset() の例

<?php
$arrayobj = new ArrayObject(array(0=>'zero',2=>'two'));
$arrayobj->offsetUnset(2);
var_dump($arrayobj);
?>

上の例の出力は以下となります。

object(ArrayObject)#1 (1) {
  [0]=>
  string(4) "zero"
}


ArrayObject をシリアライズする

  • ≪ ArrayObject::offsetUnset
  • ArrayObject::setFlags ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject をシリアライズする

ArrayObject::serialize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ArrayObject::serialize — ArrayObject をシリアライズする

説明

public ArrayObject::serialize(): string

ArrayObject をシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

ArrayObject をシリアライズしたものを返します。

例

例1 ArrayObject::serialize() の例

<?php
$o = new ArrayObject();

$s1 = serialize($o);
$s2 = $o->serialize();

var_dump($s1);
var_dump($s2);
?>

上の例の出力は以下となります。

string(45) "C:11:"ArrayObject":21:{x:i:0;a:0:{};m:a:0:{}}"
string(21) "x:i:0;a:0:{};m:a:0:{}"

参考

  • ArrayObject::unserialize() - ArrayObject をアンシリアライズする
  • serialize() - 値の保存可能な表現を生成する
  • オブジェクトのシリアライズ


処理フラグを設定する

  • ≪ ArrayObject::serialize
  • ArrayObject::setIteratorClass ≫
  • PHP Manual
  • ArrayObject
  • 処理フラグを設定する

ArrayObject::setFlags

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayObject::setFlags — 処理フラグを設定する

説明

public ArrayObject::setFlags(int $flags): void

ArrayObject の振る舞いを変更するフラグを設定します。

パラメータ

flags

新たな ArrayObject の振る舞い。 ビットマスクか、定数名で指定します。 将来のバージョンとの互換性のため、定数名での指定を強く推奨します。

利用可能なフラグの一覧を以下に示します。 これらのフラグの実際の意味については 定義済みの定数 を参照ください。

ArrayObject のフラグ
値 | 定数
1 | ArrayObject::STD_PROP_LIST
2 | ArrayObject::ARRAY_AS_PROPS

戻り値

値を返しません。

例

例1 ArrayObject::setFlags() の例

<?php
// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// 配列のキーをプロパティとして使用してみます
var_dump($fruitsArrayObject->lemons);
// フラグを設定して、配列のキーを ArrayObject のプロパティとして使えるようにします
$fruitsArrayObject->setFlags(ArrayObject::ARRAY_AS_PROPS);
// 改めて挑戦します
var_dump($fruitsArrayObject->lemons);
?>

上の例の出力は以下となります。

NULL
int(1)


ArrayObject のイテレータクラス名を設定する

  • ≪ ArrayObject::setFlags
  • ArrayObject::uasort ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject のイテレータクラス名を設定する

ArrayObject::setIteratorClass

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ArrayObject::setIteratorClass — ArrayObject のイテレータクラス名を設定する

説明

public ArrayObject::setIteratorClass(string $iteratorClass): void

配列イテレータのクラス名を設定します。これは ArrayObject::getIterator() で使います。

パラメータ

iteratorClass

このオブジェクトの反復処理に使う配列イテレータのクラス名。

戻り値

値を返しません。

例

例1 ArrayObject::setIteratorClass() の例

<?php
// 独自のイテレータ (ArrayIterator を継承したもの)
class MyArrayIterator extends ArrayIterator {
// 独自の実装
}

// フルーツの配列
$fruits = array("lemons" => 1, "oranges" => 4, "bananas" => 5, "apples" => 10);

$fruitsArrayObject = new ArrayObject($fruits);

// イテレータのクラス名を新しく設定します
$fruitsArrayObject->setIteratorClass('MyArrayIterator');
print_r($fruitsArrayObject->getIterator());

?>

上の例の出力は以下となります。

MyArrayIterator Object
(
    [lemons] => 1
    [oranges] => 4
    [bananas] => 5
    [apples] => 10
)


ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

  • ≪ ArrayObject::setIteratorClass
  • ArrayObject::uksort ≫
  • PHP Manual
  • ArrayObject
  • ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

ArrayObject::uasort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayObject::uasort — ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する

説明

public ArrayObject::uasort(callable $callback): true

この関数はエントリをソートします。キーとそれに対応する値の関連は保持されたままとなります。 ソートにはユーザー定義の比較関数を利用します。

これは主に、連想配列など実際の要素の並びが重要となる場合のソートで使います。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 ArrayObject::uasort() の例

<?php
// 比較関数
function cmp($a, $b) {
if ($a == $b) {
return 0;
}
return ($a < $b) ? -1 : 1;
}

// ソートしたい配列
$array = array('a' => 4, 'b' => 8, 'c' => -1, 'd' => -9, 'e' => 2, 'f' => 5, 'g' => 3, 'h' => -4);
$arrayObject = new ArrayObject($array);
print_r($arrayObject);

// ソートと、その結果の表示
$arrayObject->uasort('cmp');
print_r($arrayObject);
?>

上の例の出力は以下となります。

Array
(
    [a] => 4
    [b] => 8
    [c] => -1
    [d] => -9
    [e] => 2
    [f] => 5
    [g] => 3
    [h] => -4
)
Array
(
    [d] => -9
    [h] => -4
    [c] => -1
    [e] => 2
    [g] => 3
    [a] => 4
    [f] => 5
    [b] => 8
)

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uksort() - ユーザー定義の比較関数を使って、キーでエントリをソートする
  • uasort() - ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する


ユーザー定義の比較関数を使って、キーでエントリをソートする

  • ≪ ArrayObject::uasort
  • ArrayObject::unserialize ≫
  • PHP Manual
  • ArrayObject
  • ユーザー定義の比較関数を使って、キーでエントリをソートする

ArrayObject::uksort

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ArrayObject::uksort — ユーザー定義の比較関数を使って、キーでエントリをソートする

説明

public ArrayObject::uksort(callable $callback): true

この関数は、ユーザー定義の比較関数を使ってキーでエントリをソートします。 キーとそれに対応する値の関連は保持されたままとなります。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

パラメータ

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 ArrayObject::uksort() の例

<?php
function cmp($a, $b) {
$a = preg_replace('@^(a|an|the) @', '', $a);
$b = preg_replace('@^(a|an|the) @', '', $b);
return strcasecmp($a, $b);
}

$array = array("John" => 1, "the Earth" => 2, "an apple" => 3, "a banana" => 4);
$arrayObject = new ArrayObject($array);
$arrayObject->uksort('cmp');

foreach ($arrayObject as $key => $value) {
echo "$key: $value\n";
}
?>

上の例の出力は以下となります。

an apple: 3
a banana: 4
the Earth: 2
John: 1

参考

  • ArrayObject::asort() - 値でエントリをソートする
  • ArrayObject::ksort() - キーでエントリをソートする
  • ArrayObject::natsort() - "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::natcasesort() - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
  • ArrayObject::uasort() - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
  • uksort() - ユーザー定義の比較関数を用いて、キーで配列をソートする


ArrayObject をアンシリアライズする

  • ≪ ArrayObject::uksort
  • SplObserver ≫
  • PHP Manual
  • ArrayObject
  • ArrayObject をアンシリアライズする

ArrayObject::unserialize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ArrayObject::unserialize — ArrayObject をアンシリアライズする

説明

public ArrayObject::unserialize(string $data): void

シリアライズした ArrayObject をアンシリアライズします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

シリアライズした ArrayObject。

戻り値

値を返しません。

参考

  • ArrayIterator::serialize() - シリアライズする
  • unserialize() - 保存用表現から PHP の値を生成する
  • オブジェクトのシリアライズ


SplObserver インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

SplObserver インターフェイスを SplSubject とともに使うと、Observer パターンを実装することができます。

インターフェイス概要

interface SplObserver {
/* メソッド */
public update(SplSubject $subject): void
}

目次

  • SplObserver::update — subject の更新を受信する


subject の更新を受信する

  • ≪ SplObserver
  • SplSubject ≫
  • PHP Manual
  • SplObserver
  • subject の更新を受信する

SplObserver::update

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplObserver::update — subject の更新を受信する

説明

public SplObserver::update(SplSubject $subject): void

このメソッドは、オブザーバがアタッチされている任意の SplSubject が SplSubject::notify() をコールしたときにコールされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

subject

observer に更新を通知する SplSubject。

戻り値

値を返しません。


SplSubject インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

SplSubject インターフェイスを SplObserver とともに使うと、Observer パターンを実装することができます。

インターフェイス概要

interface SplSubject {
/* メソッド */
public attach(SplObserver $observer): void
public detach(SplObserver $observer): void
public notify(): void
}

目次

  • SplSubject::attach — SplObserver をアタッチする
  • SplSubject::detach — observer をデタッチする
  • SplSubject::notify — observer に通知する


SplObserver をアタッチする

  • ≪ SplSubject
  • SplSubject::detach ≫
  • PHP Manual
  • SplSubject
  • SplObserver をアタッチする

SplSubject::attach

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplSubject::attach — SplObserver をアタッチする

説明

public SplSubject::attach(SplObserver $observer): void

SplObserver にアタッチし、更新を通知できるようにします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

observer

アタッチする SplObserver。

戻り値

値を返しません。


observer をデタッチする

  • ≪ SplSubject::attach
  • SplSubject::notify ≫
  • PHP Manual
  • SplSubject
  • observer をデタッチする

SplSubject::detach

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplSubject::detach — observer をデタッチする

説明

public SplSubject::detach(SplObserver $observer): void

observer をデタッチし、更新を通知しないようにします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

observer

デタッチする SplObserver。

戻り値

値を返しません。


observer に通知する

  • ≪ SplSubject::detach
  • ストリーム ≫
  • PHP Manual
  • SplSubject
  • observer に通知する

SplSubject::notify

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SplSubject::notify — observer に通知する

説明

public SplSubject::notify(): void

アタッチされたすべての observer に通知します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


ストリーム

  • はじめに
  • インストール/設定
    • ストリームのクラス
  • 定義済み定数
  • ストリームフィルタ
  • ストリームコンテキスト
  • ストリームのエラー
  • 例
    • ストリームラッパーとして登録するクラスの例
  • php_user_filter — php_user_filter クラス
    • php_user_filter::filter — フィルタを適用するときにコールされる
    • php_user_filter::onClose — フィルタを閉じるときにコールされる
    • php_user_filter::onCreate — フィルタを作成するときにコールされる
  • streamWrapper — streamWrapper クラス
    • streamWrapper::__construct — 新しいストリームラッパーを作成する
    • streamWrapper::__destruct — 既存のストリームラッパーを破棄する
    • streamWrapper::dir_closedir — ディレクトリハンドルを閉じる
    • streamWrapper::dir_opendir — ディレクトリハンドルをオープンする
    • streamWrapper::dir_readdir — ディレクトリハンドルからエントリを読み込む
    • streamWrapper::dir_rewinddir — ディレクトリハンドルを巻き戻す
    • streamWrapper::mkdir — ディレクトリを作成する
    • streamWrapper::rename — ファイルあるいはディレクトリの名前を変える
    • streamWrapper::rmdir — ディレクトリを削除する
    • streamWrapper::stream_cast — 元となるリソースを取得する
    • streamWrapper::stream_close — リソースを閉じる
    • streamWrapper::stream_eof — ファイルポインタが終端にあるかどうかを調べる
    • streamWrapper::stream_flush — 出力をフラッシュする
    • streamWrapper::stream_lock — ファイルのアドバイザリ・ロック
    • streamWrapper::stream_metadata — ストリームメタデータを変更する
    • streamWrapper::stream_open — ファイルあるいは URL をオープンする
    • streamWrapper::stream_read — ストリームから読み込む
    • streamWrapper::stream_seek — ストリーム内の特定の場所に移動する
    • streamWrapper::stream_set_option — ストリームのオプションを変更する
    • streamWrapper::stream_stat — ファイルリソースについての情報を取得する
    • streamWrapper::stream_tell — ストリームの現在位置を取得する
    • streamWrapper::stream_truncate — ストリームを丸める
    • streamWrapper::stream_write — ストリームに書き込む
    • streamWrapper::unlink — ファイルを削除する
    • streamWrapper::url_stat — ファイルについての情報を取得する
  • ストリーム 関数
    • stream_bucket_append — bucket を brigade に追加する
    • stream_bucket_make_writeable — 操作する brigade から bucket オブジェクトを返す
    • stream_bucket_new — 現在のストリームで使用する新しい bucket を作成する
    • stream_bucket_prepend — bucket を brigade の先頭に追加する
    • stream_context_create — ストリームコンテキストを作成する
    • stream_context_get_default — デフォルトのストリームコンテキストを取得する
    • stream_context_get_options — ストリーム / ラッパー / コンテキストに設定されているオプションを取得する
    • stream_context_get_params — コンテキストのパラメータを取得する
    • stream_context_set_default — デフォルトのストリームコンテキストを設定する
    • stream_context_set_option — ストリーム / ラッパー / コンテキストのオプションを設定する
    • stream_context_set_options — 指定されたコンテキストのオプションを設定する
    • stream_context_set_params — ストリーム / ラッパー / コンテキストのパラメータを設定する
    • stream_copy_to_stream — データをあるストリームから別のストリームにコピーする
    • stream_filter_append — ストリームにフィルタを付加する
    • stream_filter_prepend — フィルタをストリームに付加する
    • stream_filter_register — ユーザー定義のストリームフィルタを登録する
    • stream_filter_remove — ストリームからフィルタを取り除く
    • stream_get_contents — 残りのストリームを文字列に読み込む
    • stream_get_filters — 登録されているフィルタのリストを取得する
    • stream_get_line — 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む
    • stream_get_meta_data — ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する
    • stream_get_transports — 登録されたソケットのトランスポートの一覧を取得する
    • stream_get_wrappers — 登録されているストリームのラッパーのリストを取得する
    • stream_is_local — ローカルストリームかどうかを調べる
    • stream_isatty — ストリームがターミナル型のデバイスかを調べる
    • stream_notification_callback — notification コンテキストパラメータ用のコールバック関数
    • stream_register_wrapper — stream_wrapper_register のエイリアス
    • stream_resolve_include_path — インクルードパスに対してファイル名を解決する
    • stream_select — select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
    • stream_set_blocking — ストリームのブロックモードを有効にする / 解除する
    • stream_set_chunk_size — ストリームのチャンクサイズを設定する
    • stream_set_read_buffer — 指定したストリームのファイル読み込みバッファリングを有効にする
    • stream_set_timeout — ストリームにタイムアウトを設定する
    • stream_set_write_buffer — 指定されたストリームのファイル書き込みバッファリングを有効にする
    • stream_socket_accept — stream_socket_server で作られたソケットの接続を受け入れる
    • stream_socket_client — インターネットドメインまたは Unix ドメインのソケット接続を開く
    • stream_socket_enable_crypto — 接続済みのソケットについて暗号化の on/off を切り替える
    • stream_socket_get_name — ローカルまたはリモートのソケットの名前を取得する
    • stream_socket_pair — 接続された、区別できないソケットストリームの組を作成する
    • stream_socket_recvfrom — 接続されているかどうかにかかわらず、ソケットからのデータを受信する
    • stream_socket_sendto — 接続されているかどうかにかかわらず、ソケットにデータを送信する
    • stream_socket_server — インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
    • stream_socket_shutdown — 全二重接続を終了する
    • stream_supports_lock — ストリームがロックをサポートしているかどうかを調べる
    • stream_wrapper_register — PHP のクラスとして実装された URL ラッパーを登録する
    • stream_wrapper_restore — 事前に登録を解除された組み込みラッパーを復元する
    • stream_wrapper_unregister — URL ラッパーの登録を解除する


はじめに

ストリームは、 ファイル、ネットワーク、データ圧縮などに関する、 共通した一連の関数群と利用法を持つ操作の一般化の手法です。 もっとも単純な定義では、ストリーム というのは、ストリーミング可能な動作を体現する resource オブジェクトといえます。つまり、ストリームには線的に読み出したり、 あるいは書き込んだりすることが可能で、かつ、 ストリーム上の任意の場所に fseek() できる場合もあります。

ラッパー というのは、ストリームにおいてどのように特定の プロトコル/エンコーディングを扱うかを扱うかを指示する付加的なコード です。たとえば、http ラッパーは、どのようにして URL を、リモートサーバーのファイルに対する HTTP/1.0 リクエストに転換するかを知っています。PHP には、デフォルトで組み込まれているラッパーが多数存在しますが (サポートするプロトコル/ラッパー を参照ください)、 それに加え、カスタムラッパーをstream_wrapper_register() を利用して PHP スクリプトの内部から、あるいはストリーム API を用いて、 直接拡張モジュールの内部から追加できます。 あらゆる種類のラッパーが PHP に追加できるので、 特にラッパーでできることの限界はありません。 現在登録されているラッパーの種類を知るには、 stream_get_wrappers() を使います。

リソースは次のような形でストリームとして参照されます: scheme://target

  • scheme(string) - 使用されるラッパーの名称です。例として、 file, http, https, ftp, ftps, compress.zlib, compress.bz2, php などが含まれます。 PHP 組み込みのラッパーについては、サポートするプロトコル/ラッパー を参照ください。もしラッパーが指定されていない場合は、使用している関数の デフォルトが利用されます(通常は file://)。
  • target - 使用するラッパーによって解釈が異なります。 ファイルシステムに関連したストリームの場合、 一般的にこのパラメータは対象となるファイルの ファイル名とパスを表します。 ネットワークに関連したストリームの場合、一般的に このパラメータはホスト名と、(多くの場合付加されるはずの) パス名です。 PHP 組み込みのラッパーに、どのようにターゲットが解釈されるかは、 サポートするプロトコル/ラッパー を参照ください。


  • ≪ はじめに
  • ストリームのクラス ≫
  • PHP Manual
  • ストリーム
  • インストール/設定

インストール/設定

目次

  • ストリームのクラス


ストリームのクラス

ユーザー定義のラッパーは、stream_wrapper_register() で、同関数の説明ページに記載されたクラス定義を使うことで、 登録することができます。

ユーザー定義のフィルタ用に、ベースとなる抽象クラスとして php_user_filter クラスがあらかじめ定義されています。 ユーザー定義のフィルタの実装に関する詳細は、 stream_filter_register() を参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

定数 | 説明
STREAM_FILTER_READ | stream_filter_append() または stream_filter_prepend() と共に使われます。 指定されたフィルタが 読み込みのときのみ 適用されることを示します。
STREAM_FILTER_WRITE | stream_filter_append() または stream_filter_prepend() と共に使われます。 指定されたフィルタが 書き込みのときのみ 適用されることを示します。
STREAM_FILTER_ALL | この定数は右の値と等価です: STREAM_FILTER_READ | STREAM_FILTER_WRITE
PSFS_PASS_ON | 返値: ユーザー空間のフィルタが バケットを $out に返したことを 示します。
PSFS_FEED_ME | 返値: ユーザー空間のフィルタが $out にバケットを返さなかったことを 示します。(つまり、変換されたデータを返す用意ができていないという ことです。)
PSFS_ERR_FATAL * | 返値: ユーザー空間のフィルタにおいて、 復旧不可能なエラーが発生したことを示します。 (つまり、不正なデータを受け取ったということです。)
PSFS_FLAG_NORMAL | 通常の読み書き。
PSFS_FLAG_FLUSH_INC | インクリメンタルなフラッシュ。
PSFS_FLAG_FLUSH_CLOSE | 最後に閉じる前にフラッシュ。
STREAM_USE_PATH | フラグ: stream が include_path を使ったかどうかを示します。
STREAM_REPORT_ERRORS | フラグ: ストリームを開く際に、 ユーザー空間にある wrapper の側で、 trigger_error() を使ってエラーを発生させるかどうかを 示します。もし、このフラグがセットされていない場合は、 ユーザーの側でエラーをスローしてはいけません。
STREAM_CLIENT_ASYNC_CONNECT | 非同期的にソケットを開きます。このオプションは、 STREAM_CLIENT_CONNECT フラグとともに使用する 必要があります。 stream_socket_client() と共に使われます。
STREAM_CLIENT_CONNECT | クライアントソケット接続を開きます。クライアントソケットは 常にこのフラグを含んでいる必要があります。 stream_socket_client() と共に使われます。
STREAM_CLIENT_PERSISTENT | stream_socket_client()を使って 開かれたソケットが、セッションをまたいでも保持されるよう 指示します。
STREAM_SERVER_BIND | stream_socket_server() で開かれたソケットが 特定のターゲットに関連付けられることを示します。 サーバーソケットには常にこのフラグが与えられているはずです。
STREAM_SERVER_LISTEN | stream_socket_server() で開かれ、 STREAM_SERVER_BIND によってターゲットに 関連付けられたストリームに、ソケットに対して接続待ちを開始するよう 指示します。 接続指向の転送（TCP のような）はこのフラグを使用する必要があります。 それ以外の場合はサーバーソケットが有効になりません。 このフラグを非接続指向の転送（UDP のような）に使用するとエラーになります。
STREAM_NOTIFY_RESOLVE | 該当するストリームにおいて、リクエストされたリモートのドメイン名の 解決に成功したか、失敗したことを示します。 このとき、何が起こっているかについては、 severity を参照ください。
STREAM_NOTIFY_CONNECT | 外部のリソースへの接続が確立されたことを示します。
STREAM_NOTIFY_AUTH_REQUIRED | 指定されたリソースにアクセスするためには、さらに認証情報が必要です。 通常に、STREAM_NOTIFY_SEVERITY_ERR の severity (深刻度) と共に通知されます。
STREAM_NOTIFY_MIME_TYPE_IS | リソースの mime タイプ が確認されました。 どのタイプと判定されたかについては、message を見てください。
STREAM_NOTIFY_FILE_SIZE_IS | 確認されたリソースのサイズを表します。
STREAM_NOTIFY_REDIRECTED | 外部リソースへのアクセスは、別の場所にリダイレクトされました。 詳細を知るには、message を調べてみてください。
STREAM_NOTIFY_PROGRESS | ストリームにおける転送の進捗が、 bytes_transferred または、場合によっては bytes_max に現れていることを示します。
STREAM_NOTIFY_COMPLETED | これ以上ストリームにデータがないことを示します。
STREAM_NOTIFY_FAILURE | ストリームにおいて一般的なエラーが発生したことを示します。 エラーの詳細については、 message と message_code を調べてみてください。
STREAM_NOTIFY_AUTH_RESULT | 認証が完了した(成功または失敗した)ことを示します。
STREAM_NOTIFY_SEVERITY_INFO | 正常な状態における、エラーでない通知があることを示します。
STREAM_NOTIFY_SEVERITY_WARN | 致命的でないエラーが発生したことを示します。処理は継続されます。
STREAM_NOTIFY_SEVERITY_ERR | 致命的なエラーが発生したことを示します。処理は中断されます。
STREAM_IPPROTO_ICMP + | ICMP ソケットを提供します。
STREAM_IPPROTO_IP + | IP ソケットを提供します。
STREAM_IPPROTO_RAW + | RAW ソケットを提供します。
STREAM_IPPROTO_TCP + | TCP ソケットを提供します。
STREAM_IPPROTO_UDP + | UDP ソケットを提供します。
STREAM_PF_INET + | Internet Protocol バージョン 4（IPv4）です。
STREAM_PF_INET6 + | Internet Protocol バージョン 6（IPv6）です。
STREAM_PF_UNIX + | Unix システムの内部プロトコルです。
STREAM_SOCK_DGRAM + | データグラムを提供します。これはコネクションレスのメッセージ （例: UDP）です。
STREAM_SOCK_RAW + | raw ソケットを提供します。これは内部のネットワークプロトコルや インターフェイスへのアクセス機能を提供します。通常、この形式の ソケットは root ユーザーが使用します。
STREAM_SOCK_RDM + | RDM（Reliably-delivered messages）ソケットを提供します。
STREAM_SOCK_SEQPACKET + | シーケンシャルパケットストリームソケットを提供します。
STREAM_SOCK_STREAM + | 帯域外データを転送するための、シーケンシャルで双方向の バイトストリーム（例: TCP）を提供します。
STREAM_SHUT_RD | stream_socket_shutdown() で使用し、 それ以降の受信を無効にします。
STREAM_SHUT_WR | stream_socket_shutdown() で使用し、 それ以降の送信を無効にします。
STREAM_SHUT_RDWR | stream_socket_shutdown() で使用し、 それ以降の送受信を無効にします。
STREAM_CAST_FOR_SELECT | stream_select() が stream_cast() をコールしている場合のストリームのキャスト。
STREAM_CAST_AS_STREAM | stream_cast() が他からコールされた (上記参照) 場合のストリームのキャスト。
STREAM_META_TOUCH | stream_metadata() と組み合わせて使い、touch() のコールを指定します。
STREAM_META_OWNER | stream_metadata() と組み合わせて使い、chown() のコールを指定します。
STREAM_META_OWNER_NAME | stream_metadata() と組み合わせて使い、chown() のコールを指定します。
STREAM_META_GROUP | stream_metadata() と組み合わせて使い、chgrp() のコールを指定します。
STREAM_META_GROUP_NAME | stream_metadata() と組み合わせて使い、chgrp() のコールを指定します。
STREAM_META_ACCESS | stream_metadata() と組み合わせて使い、chmod() のコールを指定します。
STREAM_BUFFER_NONE | バッファリングを行いません。
STREAM_BUFFER_LINE | 行単位のバッファリングを行います。
STREAM_BUFFER_FULL | 全てをバッファリングします。
STREAM_CRYPTO_METHOD_ANY_CLIENT | あらゆる TLS または SSL バージョンのクライアントストリーム
STREAM_CRYPTO_METHOD_SSLv2_CLIENT | SSL 2.0 のクライアントストリーム
STREAM_CRYPTO_METHOD_SSLv3_CLIENT | SSL 3 のクライアントストリーム
STREAM_CRYPTO_METHOD_SSLv23_CLIENT | TLS 1.0, 1.1, 1.2 のクライアントストリーム
STREAM_CRYPTO_METHOD_TLS_CLIENT | あらゆる TLS バージョンのクライアントストリーム
STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT | TLS 1.0 のクライアントストリーム
STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT | TLS 1.1 のクライアントストリーム
STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT | TLS 1.2 のクライアントストリーム
STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT | TLS 1.3 のクライアントストリーム
STREAM_CRYPTO_METHOD_ANY_SERVER | あらゆる TLS または SSL バージョンのサーバストリーム
STREAM_CRYPTO_METHOD_SSLv2_SERVER | SSL 2 のサーバストリーム
STREAM_CRYPTO_METHOD_SSLv3_SERVER | SSL 3 のサーバストリーム
STREAM_CRYPTO_METHOD_SSLv23_SERVER | TLS 1.0, 1.1, 1.2 のサーバストリーム
STREAM_CRYPTO_METHOD_TLS_SERVER | あらゆる TLS バージョンのサーバストリーム
STREAM_CRYPTO_METHOD_TLSv1_0_SERVER | TLS 1.0 のサーバストリーム
STREAM_CRYPTO_METHOD_TLSv1_1_SERVER | TLS 1.1 のサーバストリーム
STREAM_CRYPTO_METHOD_TLSv1_2_SERVER | TLS 1.2 のサーバストリーム
STREAM_CRYPTO_METHOD_TLSv1_3_SERVER | TLS 1.3 のサーバストリーム
STREAM_CRYPTO_PROTO_SSLv3 | のエイリアス STREAM_CRYPTO_METHOD_SSLv3_SERVER.
STREAM_CRYPTO_PROTO_TLSv1_0 | のエイリアス STREAM_CRYPTO_METHOD_TLSv1_0_SERVER.
STREAM_CRYPTO_PROTO_TLSv1_1 | のエイリアス STREAM_CRYPTO_METHOD_TLSv1_1_SERVER.
STREAM_CRYPTO_PROTO_TLSv1_2 | のエイリアス STREAM_CRYPTO_METHOD_TLSv1_2_SERVER.
STREAM_CRYPTO_PROTO_TLSv1_3 | のエイリアス STREAM_CRYPTO_METHOD_TLSv1_3_SERVER.
STREAM_IGNORE_URL | プラグインラッパーを使わない
STREAM_MUST_SEEK | ストリームがシークできることを示します。 これは、ストリームのコピーが生成されている可能性があります。
STREAM_MKDIR_RECURSIVE | mkdir() や rmdir() のオプションパラメータの再帰フラグ
STREAM_IS_URL | このストリームがURLであることを示します
STREAM_URL_STAT_LINK | リンクそのものに関する情報のみを返し、 リンクが指すリソースに関する情報は返しません。
STREAM_URL_STAT_QUIET | ラッパーはエラーを発生させるべきではありません
STREAM_PEEK | ソケットからデータを取得しますが、 バッファを消費しません。 後に fread() や stream_socket_recvfrom() をコールしても同じデータが見えます。
STREAM_OOB | OOB (out-of-band) データを処理します
STREAM_OPTION_BLOCKING | ストリーム上のブロッキング/ノンブロッキングモードを設定します
STREAM_OPTION_READ_TIMEOUT | ストリーム上の読み取りファイルバッファリングを設定します
STREAM_OPTION_WRITE_BUFFER | ストリーム上の書き込みファイルバッファリングを設定します
STREAM_OPTION_READ_BUFFER | ストリーム上の読み取りファイルバッファリングを設定します

注意: + がつけられている定数は stream_socket_pair() とともに使用することが想定されています。 これらの定数の中にはあなたのシステムでは使用できないものがあるかもしれない ことに注意してください。

注意: STREAM_META_* 定数は stream_metadata() とともに使用することが想定されています。


ストリームフィルタ

フィルタ は、ストリームから読み込まれたり、 あるいは、ストリームから書き込まれたするデータに対して何らかの操作を行う、 最終段階にあるコードです。 PHP スクリプトの内部で、 stream_filter_register() を使って、 あるいは拡張モジュールの内部で、カスタムフィルタを作成することができます。 現在登録されているフィルタの一覧を取得するには、 stream_get_filters() をお使いください。


ストリームコンテキスト

コンテキスト は、ストリームの挙動を変えたり、 拡張したりすることのできる パラメータ と ラッパー固有の オプション の集合です。 コンテキスト は、 stream_context_create() を使って生成しますが、 これは、ほとんどのファイルシステム関連のストリーム生成関数に 渡すことができます (例えば fopen(), file(), file_get_contents() など)。

オプション は、 stream_context_create() の呼び出し時に指定しますが、 後で stream_context_set_option() を使って 指定することもできます。 ラッパー固有の オプション については、 コンテキストオプションとパラメータ を参照ください。

さらに、stream_context_set_params() を使うことで、 パラメータ を、コンテキスト に対し指定することができます。


ストリームのエラー

ファイルやソケット関連の関数で処理に失敗するのと同じように、 ストリームにおける操作も様々な予測できる理由で失敗することがあります (例: リモートホストに接続できない、ファイルが見つからない、等)。 また、ストリーム関連の関数呼び出しは、 スクリプトの実行されるシステムにおいて、 利用しようとしているストリームが登録されていないことから失敗することも あります。どのタイプのストリームがインストールされた PHP でサポートされているかは、 stream_get_wrappers() の返す配列の内容を参照 してください。なお、他の PHP の内部関数と同様、 E_WARNING メッセージがエラー時に出力され、 エラーの原因を報告します。


例

目次

  • ストリームラッパーとして登録するクラスの例

例1 file_get_contents() を使って さまざまな場所からデータを取得する

<?php
/* /home/bar にあるローカルファイルを読み出す */
$localfile = file_get_contents("/home/bar/foo.txt");

/* 上と同一だが、明示的に FILE スキームを指定している */
$localfile = file_get_contents("file:///home/bar/foo.txt");

/* HTTP を利用し、www.example.com にあるリモートのファイルを読み出す */
$httpfile = file_get_contents("http://www.example.com/foo.txt");

/* HTTPS を利用し、www.example.com にあるリモートのファイルを読み出す */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");

/* FTP を利用し、ftp.example.com にあるリモートのファイルを読み出す */
$ftpfile = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");

/* FTPS を利用し、ftp.example.com にあるリモートのファイルを読み出す */
$ftpsfile = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?>

例2 https のサーバーに対して POST リクエストを行う

<?php
/* https://secure.example.com/form_action.php に対して POST リクエストを送信
* ダミー値を持つ "foo" と "bar" というフォーム要素が含まれます。
*/

$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");

$data = "foo=" . urlencode("Fooの値") . "&bar=" . urlencode("Barの値");

fwrite($sock, "POST /form_action.php HTTP/1.0\r\n");
fwrite($sock, "Host: secure.example.com\r\n");
fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fwrite($sock, "Content-length: " . strlen($data) . "\r\n");
fwrite($sock, "Accept: */*\r\n");
fwrite($sock, "\r\n");
fwrite($sock, $data);

$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";

echo "\n";

$body = "";
while (!feof($sock))
$body .= fgets($sock, 4096);

fclose($sock);
?>

例3 データを圧縮ファイルに書き込む

<?php
/* 任意の文字列を含む圧縮ファイルを作成
* ファイルは、compress.zlib ストリームを使っても、または単に
* コマンドラインで 'gzip -d foo-bar.txt.gz' を使っても読み出せます。
*/
$fp = fopen("compress.zlib://foo-bar.txt.gz", "wb");
if (!$fp) die("ファイルが作成できません。");

fwrite($fp, "これはテストです。\n");

fclose($fp);
?>


ストリームラッパーとして登録するクラスの例

以下のサンプルは、var:// プロトコルハンドラを実装し、 指定した名前のグローバル変数の読み書きを fread() のような標準のファイルシステム関数でできるようにしています。 以下で実装した var:// プロトコルでは、URL "var://foo" で $GLOBALS["foo"] への読み書きを行います。

例1 グローバル変数の読み書き用のストリーム

<?php

class VariableStream {
var $position;
var $varname;

function stream_open($path, $mode, $options, &$opened_path)
{
$url = parse_url($path);
$this->varname = $url["host"];
$this->position = 0;

return true;
}

function stream_read($count)
{
$ret = substr($GLOBALS[$this->varname], $this->position, $count);
$this->position += strlen($ret);
return $ret;
}

function stream_write($data)
{
$left = substr($GLOBALS[$this->varname], 0, $this->position);
$right = substr($GLOBALS[$this->varname], $this->position + strlen($data));
$GLOBALS[$this->varname] = $left . $data . $right;
$this->position += strlen($data);
return strlen($data);
}

function stream_tell()
{
return $this->position;
}

function stream_eof()
{
return $this->position >= strlen($GLOBALS[$this->varname]);
}

function stream_seek($offset, $whence)
{
switch ($whence) {
case SEEK_SET:
if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) {
$this->position = $offset;
return true;
} else {
return false;
}
break;

case SEEK_CUR:
if ($offset >= 0) {
$this->position += $offset;
return true;
} else {
return false;
}
break;

case SEEK_END:
if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {
$this->position = strlen($GLOBALS[$this->varname]) + $offset;
return true;
} else {
return false;
}
break;

default:
return false;
}
}

function stream_metadata($path, $option, $var)
{
if($option == STREAM_META_TOUCH) {
$url = parse_url($path);
$varname = $url["host"];
if(!isset($GLOBALS[$varname])) {
$GLOBALS[$varname] = '';
}
return true;
}
return false;
}
}

stream_wrapper_register("var", "VariableStream")
or die("Failed to register protocol");

$myvar = "";

$fp = fopen("var://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
echo fgets($fp);
}
fclose($fp);
var_dump($myvar);

?>

上の例の出力は以下となります。

line1
line2
line3
string(18) "line1
line2
line3
"


php_user_filter クラス

(PHP 5, PHP 7, PHP 8)

はじめに

このクラスの子クラスを stream_filter_register() に渡します。 子クラスの __construct メソッドは呼び出されないので注意して下さい: 初期化については、php_user_filter::onCreate() を変わりに使うべきです。

クラス概要

class php_user_filter {
/* プロパティ */
public string $filtername = "";
public mixed $params = "";
public ?resource $stream = null;
/* メソッド */
public filter(
resource $in,
resource $out,
int &$consumed,
bool $closing
): int
public onClose(): void
public onCreate(): bool
}

プロパティ

filtername

stream_filter_append() で登録するフィルタの名前。

params

stream

目次

  • php_user_filter::filter — フィルタを適用するときにコールされる
  • php_user_filter::onClose — フィルタを閉じるときにコールされる
  • php_user_filter::onCreate — フィルタを作成するときにコールされる


フィルタを適用するときにコールされる

  • ≪ php_user_filter
  • php_user_filter::onClose ≫
  • PHP Manual
  • php_user_filter
  • フィルタを適用するときにコールされる

php_user_filter::filter

(PHP 5, PHP 7, PHP 8)

php_user_filter::filter — フィルタを適用するときにコールされる

説明

public php_user_filter::filter(
resource $in,
resource $out,
int &$consumed,
bool $closing
): int

このメソッドがコールされるのは、アタッチしたストリームとの間で (fread() や fwrite() による) データの読み書きを行ったときです。

パラメータ

in

in は バケット群 を指すリソースで、 この中には一つあるいは複数の バケット オブジェクトが含まれています。 このオブジェクトに、フィルタ対象のデータが含まれます。

out

out はもう一つの バケット群 を指すリソースで、 変更した内容をここに保存します。

consumed

consumed は常に参照渡しとする必要があります。 フィルタで読み込んだり変更したりしたデータの長さをここで加算します。 大半の場合、各 $bucket 上で $bucket->datalen をコールするたびに consumed を増やすことになります。

closing

ストリームが終了処理の最中である場合 (つまり、フィルタチェインの最後の処理を行っている場合) に、closing パラメータが true となります。

戻り値

filter() メソッドは、処理を終えたときに次のいずれかの値を返す必要があります。

戻り値 | 意味
PSFS_PASS_ON | フィルタの処理が成功し、データが out バケット群 に保存されました。
PSFS_FEED_ME | フィルタの処理は成功しましたが、返すデータはありません。 ストリームあるいは一つ前のフィルタから、さらにデータが必要です。
PSFS_ERR_FATAL (デフォルト) | フィルタで対処不能なエラーが発生し、処理を続行できません。


フィルタを閉じるときにコールされる

  • ≪ php_user_filter::filter
  • php_user_filter::onCreate ≫
  • PHP Manual
  • php_user_filter
  • フィルタを閉じるときにコールされる

php_user_filter::onClose

(PHP 5, PHP 7, PHP 8)

php_user_filter::onClose — フィルタを閉じるときにコールされる

説明

public php_user_filter::onClose(): void

このメソッドがコールされるのはフィルタを終了する (通常は、同時にストリームも終了する) ときで、flush メソッドよりも 後で 実行されます。 onCreate() で何らかのリソースを確保したり初期化したりしていた場合は、ここで破棄することになります。

パラメータ

この関数にはパラメータはありません。

戻り値

戻り値は無視されます。


フィルタを作成するときにコールされる

  • ≪ php_user_filter::onClose
  • streamWrapper ≫
  • PHP Manual
  • php_user_filter
  • フィルタを作成するときにコールされる

php_user_filter::onCreate

(PHP 5, PHP 7, PHP 8)

php_user_filter::onCreate — フィルタを作成するときにコールされる

説明

public php_user_filter::onCreate(): bool

このメソッドがコールされるのは、フィルタクラスのオブジェクトのインスタンスを生成するときです。 他のリソース (バッファなど) を確保したり初期化したりする場合は、このメソッドで行います。

フィルタのインスタンスを作成して yourfilter->onCreate() をコールすると、 以下の表に示すさまざまなプロパティが使えるようになります。

プロパティ | 内容
FilterClass->filtername | フィルタのインスタンスを作成するときの名前を表す文字列。 フィルタを登録するときには、複数の名前を使ったりワイルドカードを使ったりできます。 このプロパティを使って、どの名前が用いられたのかを判断します。
FilterClass->params | stream_filter_append() あるいは stream_filter_prepend() に渡された params パラメータの内容。
FilterClass->stream | フィルタの対象となるストリームリソース。 closing パラメータが false の状態で filter() がコールされている間だけ存在します。

パラメータ

この関数にはパラメータはありません。

戻り値

このメソッドを実装は、成功した場合に true そして失敗した場合に false を返す必要があります。


streamWrapper クラス

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

はじめに

独自のプロトコルハンドラやストリームを実装し、 (fopen() や fread() などの) 他のファイルシステム関数で使用できるようにします。

注意:

これは、実際のクラスではありません。 クラスがどのようにプロトコルを定義すべきかを示す、単なるプロトタイプです。

注意:

ここに示す方法以外でメソッドを実装した場合の挙動は未定義となります。

このクラスのインスタンスは、 関連付けられているプロトコルへのストリーム関数からのアクセスがあった時点で初期化されます。

クラス概要

class streamWrapper {
/* プロパティ */
public resource $context;
/* メソッド */
public __construct()
public dir_closedir(): bool
public dir_opendir(string $path, int $options): bool
public dir_readdir(): string
public dir_rewinddir(): bool
public mkdir(string $path, int $mode, int $options): bool
public rename(string $path_from, string $path_to): bool
public rmdir(string $path, int $options): bool
public stream_cast(int $cast_as): resource
public stream_close(): void
public stream_eof(): bool
public stream_flush(): bool
public stream_lock(int $operation): bool
public stream_metadata(string $path, int $option, mixed $value): bool
public stream_open(
string $path,
string $mode,
int $options,
?string &$opened_path
): bool
public stream_read(int $count): string|false
public stream_seek(int $offset, int $whence = SEEK_SET): bool
public stream_set_option(int $option, int $arg1, int $arg2): bool
public stream_stat(): array|false
public stream_tell(): int
public stream_truncate(int $new_size): bool
public stream_write(string $data): int
public unlink(string $path): bool
public url_stat(string $path, int $flags): array|false
public __destruct()
}

プロパティ

resource context

現在のコンテキスト、 あるいは呼び出し元からコンテキストが渡されていない場合は null。

stream_context_get_options() を用いてコンテキストをパースします。

注意:

このプロパティは必ず public とし、 PHP が実際のコンテキストリソースを設定できるようにしなければなりません。

参考

  • ストリームラッパーとして登録するクラスの例
  • stream_wrapper_register()
  • stream_wrapper_unregister()
  • stream_wrapper_restore()

目次

  • streamWrapper::__construct — 新しいストリームラッパーを作成する
  • streamWrapper::__destruct — 既存のストリームラッパーを破棄する
  • streamWrapper::dir_closedir — ディレクトリハンドルを閉じる
  • streamWrapper::dir_opendir — ディレクトリハンドルをオープンする
  • streamWrapper::dir_readdir — ディレクトリハンドルからエントリを読み込む
  • streamWrapper::dir_rewinddir — ディレクトリハンドルを巻き戻す
  • streamWrapper::mkdir — ディレクトリを作成する
  • streamWrapper::rename — ファイルあるいはディレクトリの名前を変える
  • streamWrapper::rmdir — ディレクトリを削除する
  • streamWrapper::stream_cast — 元となるリソースを取得する
  • streamWrapper::stream_close — リソースを閉じる
  • streamWrapper::stream_eof — ファイルポインタが終端にあるかどうかを調べる
  • streamWrapper::stream_flush — 出力をフラッシュする
  • streamWrapper::stream_lock — ファイルのアドバイザリ・ロック
  • streamWrapper::stream_metadata — ストリームメタデータを変更する
  • streamWrapper::stream_open — ファイルあるいは URL をオープンする
  • streamWrapper::stream_read — ストリームから読み込む
  • streamWrapper::stream_seek — ストリーム内の特定の場所に移動する
  • streamWrapper::stream_set_option — ストリームのオプションを変更する
  • streamWrapper::stream_stat — ファイルリソースについての情報を取得する
  • streamWrapper::stream_tell — ストリームの現在位置を取得する
  • streamWrapper::stream_truncate — ストリームを丸める
  • streamWrapper::stream_write — ストリームに書き込む
  • streamWrapper::unlink — ファイルを削除する
  • streamWrapper::url_stat — ファイルについての情報を取得する


新しいストリームラッパーを作成する

  • ≪ streamWrapper
  • streamWrapper::__destruct ≫
  • PHP Manual
  • streamWrapper
  • 新しいストリームラッパーを作成する

streamWrapper::__construct

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::__construct — 新しいストリームラッパーを作成する

説明

public streamWrapper::__construct()

ストリームラッパーをオープンしたときに、 streamWrapper::stream_open() の直前にコールされます。

パラメータ

この関数にはパラメータはありません。


既存のストリームラッパーを破棄する

  • ≪ streamWrapper::__construct
  • streamWrapper::dir_closedir ≫
  • PHP Manual
  • streamWrapper
  • 既存のストリームラッパーを破棄する

streamWrapper::__destruct

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::__destruct — 既存のストリームラッパーを破棄する

説明

public streamWrapper::__destruct()

ストリームラッパーを閉じるときに、 streamWrapper::stream_flush() の直前に呼び出されます。

パラメータ

この関数にはパラメータはありません。


ディレクトリハンドルを閉じる

  • ≪ streamWrapper::__destruct
  • streamWrapper::dir_opendir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルを閉じる

streamWrapper::dir_closedir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_closedir — ディレクトリハンドルを閉じる

説明

public streamWrapper::dir_closedir(): bool

このメソッドは closedir() に対応してコールされます。

ディレクトリストリームをオープンして使用している際にロックしたり割り当てたりしたリソースは、 すべて開放しなければなりません。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • closedir() - ディレクトリハンドルをクローズする
  • streamWrapper::dir_opendir() - ディレクトリハンドルをオープンする


ディレクトリハンドルをオープンする

  • ≪ streamWrapper::dir_closedir
  • streamWrapper::dir_readdir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルをオープンする

streamWrapper::dir_opendir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_opendir — ディレクトリハンドルをオープンする

説明

public streamWrapper::dir_opendir(string $path, int $options): bool

このメソッドは、opendir() に対応してコールされます。

パラメータ

path

opendir() に渡す URL を指定します。

注意:

parse_url() でこの URL が壊れることがあります。

options

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • opendir() - ディレクトリハンドルをオープンする
  • streamWrapper::dir_closedir() - ディレクトリハンドルを閉じる
  • parse_url() - URL を解釈し、その構成要素を返す


ディレクトリハンドルからエントリを読み込む

  • ≪ streamWrapper::dir_opendir
  • streamWrapper::dir_rewinddir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルからエントリを読み込む

streamWrapper::dir_readdir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_readdir — ディレクトリハンドルからエントリを読み込む

説明

public streamWrapper::dir_readdir(): string

このメソッドは、readdir() に対応してコールされます。

パラメータ

この関数にはパラメータはありません。

戻り値

次のファイル名をあらわす文字列、あるいは次のファイルがない場合に false を返します。

注意:

戻り値は文字列にキャストされます。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

例

例1 tar アーカイブのファイル一覧

<?php
class streamWrapper {
protected $fp;

public function dir_opendir($path, $options) {
$url = parse_url($path);

$path = $url["host"] . $url["path"];

if (!is_readable($path)) {
trigger_error("$path isn't readable for me", E_USER_NOTICE);
return false;
}
if (!is_file($path)) {
trigger_error("$path isn't a file", E_USER_NOTICE);
return false;
}

$this->fp = fopen($path, "rb");
return true;
}

public function dir_readdir() {
// Extract the header for this entry
$header = fread($this->fp, 512);
$data = unpack("a100filename/a8mode/a8uid/a8gid/a12size/a12mtime/a8checksum/a1filetype/a100link/a100linkedfile", $header);

// Trim the filename and filesize
$filename = trim($data["filename"]);

// No filename? We are the end of the archive
if (!$filename) {
return false;
}

$octal_bytes = trim($data["size"]);
// Filesize is defined in octects
$bytes = octdec($octal_bytes);

// tar rounds up filesizes up to multiple of 512 bytes (zero filled)
$rest = $bytes % 512;
if ($rest > 0) {
$bytes += 512 - $rest;
}

// Seek over the file
fseek($this->fp, $bytes, SEEK_CUR);

return $filename;
}

public function dir_closedir() {
return fclose($this->fp);
}

public function dir_rewinddir() {
return fseek($this->fp, 0, SEEK_SET);
}
}

stream_wrapper_register("tar", "streamWrapper");
$handle = opendir("tar://example.tar");
while (false !== ($file = readdir($handle))) {
var_dump($file);
}

echo "Rewinding..\n";
rewind($handle);
var_dump(readdir($handle));

closedir($handle);
?>

上の例の出力は、 たとえば以下のようになります。

string(13) "construct.xml"
string(16) "dir-closedir.xml"
string(15) "dir-opendir.xml"
string(15) "dir-readdir.xml"
string(17) "dir-rewinddir.xml"
string(9) "mkdir.xml"
string(10) "rename.xml"
string(9) "rmdir.xml"
string(15) "stream-cast.xml"
string(16) "stream-close.xml"
string(14) "stream-eof.xml"
string(16) "stream-flush.xml"
string(15) "stream-lock.xml"
string(15) "stream-open.xml"
string(15) "stream-read.xml"
string(15) "stream-seek.xml"
string(21) "stream-set-option.xml"
string(15) "stream-stat.xml"
string(15) "stream-tell.xml"
string(16) "stream-write.xml"
string(10) "unlink.xml"
string(12) "url-stat.xml"
Rewinding..
string(13) "construct.xml"

参考

  • readdir() - ディレクトリハンドルからエントリを読み込む


ディレクトリハンドルを巻き戻す

  • ≪ streamWrapper::dir_readdir
  • streamWrapper::mkdir ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリハンドルを巻き戻す

streamWrapper::dir_rewinddir

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::dir_rewinddir — ディレクトリハンドルを巻き戻す

説明

public streamWrapper::dir_rewinddir(): bool

このメソッドは、rewinddir() に対応してコールされます。

streamWrapper::dir_readdir() が生成する出力をリセットしなければなりません。
つまり、次に streamWrapper::dir_readdir()
をコールすると、streamWrapper::dir_opendir()
が返す場所にある最初のエントリを返すようにしなければいけないということです。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • rewinddir() - ディレクトリハンドルを元に戻す
  • streamWrapper::dir_readdir() - ディレクトリハンドルからエントリを読み込む


ディレクトリを作成する

  • ≪ streamWrapper::dir_rewinddir
  • streamWrapper::rename ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリを作成する

streamWrapper::mkdir

(PHP 5, PHP 7, PHP 8)

streamWrapper::mkdir — ディレクトリを作成する

説明

public streamWrapper::mkdir(string $path, int $mode, int $options): bool

このメソッドは、mkdir() に対応してコールされます。

注意:

適切なエラーメッセージを返すためには、 ラッパーがディレクトリの作成に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path

作成したいディレクトリ。

mode

mkdir() に渡す値。

options

STREAM_MKDIR_RECURSIVE などの値のビットマスク。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • mkdir() - ディレクトリを作る
  • streamwrapper::rmdir() - ディレクトリを削除する


ファイルあるいはディレクトリの名前を変える

  • ≪ streamWrapper::mkdir
  • streamWrapper::rmdir ≫
  • PHP Manual
  • streamWrapper
  • ファイルあるいはディレクトリの名前を変える

streamWrapper::rename

(PHP 5, PHP 7, PHP 8)

streamWrapper::rename — ファイルあるいはディレクトリの名前を変える

説明

public streamWrapper::rename(string $path_from, string $path_to): bool

このメソッドは、rename() に対応してコールされます。

path_from を path_to に変更します。

注意:

適切なエラーメッセージを返すためには、 ラッパーがファイル名の変更に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path_from

現在のファイルの URL。

path_to

path_from の変更後の URL。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • rename() - ファイルをリネームする


ディレクトリを削除する

  • ≪ streamWrapper::rename
  • streamWrapper::stream_cast ≫
  • PHP Manual
  • streamWrapper
  • ディレクトリを削除する

streamWrapper::rmdir

(PHP 5, PHP 7, PHP 8)

streamWrapper::rmdir — ディレクトリを削除する

説明

public streamWrapper::rmdir(string $path, int $options): bool

このメソッドは、rmdir() に対応してコールされます。

注意:

適切なエラーメッセージを返すためには、 ラッパーがディレクトリの削除に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path

削除したいディレクトリの URL。

options

STREAM_MKDIR_RECURSIVE などの値のビットマスク。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • rmdir() - ディレクトリを削除する
  • streamwrapper::mkdir() - ディレクトリを作成する
  • streamwrapper::unlink() - ファイルを削除する


元となるリソースを取得する

  • ≪ streamWrapper::rmdir
  • streamWrapper::stream_close ≫
  • PHP Manual
  • streamWrapper
  • 元となるリソースを取得する

streamWrapper::stream_cast

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

streamWrapper::stream_cast — 元となるリソースを取得する

説明

public streamWrapper::stream_cast(int $cast_as): resource

このメソッドは、stream_select() に対応してコールされます。

パラメータ

cast_as

stream_select() が stream_cast() をコールした場合は STREAM_CAST_FOR_SELECT、 stream_cast() がそれ以外の用途でコールされた場合は STREAM_CAST_AS_STREAM。

戻り値

ラッパーが使用しているストリームリソース、あるいは false を返します。

参考

  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う


リソースを閉じる

  • ≪ streamWrapper::stream_cast
  • streamWrapper::stream_eof ≫
  • PHP Manual
  • streamWrapper
  • リソースを閉じる

streamWrapper::stream_close

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_close — リソースを閉じる

説明

public streamWrapper::stream_close(): void

このメソッドは、fclose() に対応してコールされます。

ラッパーがロックしたり割り当てたりしたリソースは、すべて開放しなければなりません。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • fclose() - オープンされたファイルポインタをクローズする
  • streamWrapper::dir_closedir() - ディレクトリハンドルを閉じる


ファイルポインタが終端にあるかどうかを調べる

  • ≪ streamWrapper::stream_close
  • streamWrapper::stream_flush ≫
  • PHP Manual
  • streamWrapper
  • ファイルポインタが終端にあるかどうかを調べる

streamWrapper::stream_eof

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_eof — ファイルポインタが終端にあるかどうかを調べる

説明

public streamWrapper::stream_eof(): bool

このメソッドは、feof() に対応してコールされます。

パラメータ

この関数にはパラメータはありません。

戻り値

読み込み/書き込み位置がストリームの末尾にあってもうそれ以上読み込むデータがない場合に true、 それ以外の場合に false を返します。

注意

警告

ファイル全体を (file_get_contents() などで)
読み込む場合、PHP はループ内で
streamWrapper::stream_read() をコールしてから
streamWrapper::stream_eof() をコールします。
しかし、streamWrapper::stream_read()
が空でない文字列を返す限りは
streamWrapper::stream_eof()
の戻り値を無視します。

参考

  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる


出力をフラッシュする

  • ≪ streamWrapper::stream_eof
  • streamWrapper::stream_lock ≫
  • PHP Manual
  • streamWrapper
  • 出力をフラッシュする

streamWrapper::stream_flush

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_flush — 出力をフラッシュする

説明

public streamWrapper::stream_flush(): bool

このメソッドがコールされるのは、fflush() への対応をする場合やストリームを閉じる場合です。 フラッシュしていないデータが残っていれば、それを書き出します。

データをストリームにキャッシュした状態でまだストレージに格納していないのなら、 ここで格納しなければなりません。

パラメータ

この関数にはパラメータはありません。

戻り値

キャッシュデータが正常に格納できた (あるいは格納するデータがなかった) 場合に true、データを格納できなかった場合に false を返します。

注意

注意:

実装されていない場合の戻り値は false です。

参考

  • fflush() - 出力をファイルにフラッシュする


ファイルのアドバイザリ・ロック

  • ≪ streamWrapper::stream_flush
  • streamWrapper::stream_metadata ≫
  • PHP Manual
  • streamWrapper
  • ファイルのアドバイザリ・ロック

streamWrapper::stream_lock

(PHP 5, PHP 7, PHP 8)

streamWrapper::stream_lock — ファイルのアドバイザリ・ロック

説明

public streamWrapper::stream_lock(int $operation): bool

このメソッドは、flock() に対応してコールされます。また file_put_contents() (flags が LOCK_EX を含む場合)、 stream_set_blocking() がコールされたときやストリームを閉じるとき (LOCK_UN) にもコールされます。

パラメータ

operation

operation は以下のいずれかとなります。

  • LOCK_SH 共有ロック (読み込み) を確保します。
  • LOCK_EX 排他ロック (書き込み) を確保します。
  • LOCK_UN ロック (共有あるいは排他) を開放します。
  • LOCK_NB flock() によるロック中にブロックしない (Windows ではサポートしていません)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに失敗した場合 (実装されていないなど) は E_WARNING を発行します。

参考

  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • flock() - 汎用のファイルロックを行う


ストリームメタデータを変更する

  • ≪ streamWrapper::stream_lock
  • streamWrapper::stream_open ≫
  • PHP Manual
  • streamWrapper
  • ストリームメタデータを変更する

streamWrapper::stream_metadata

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

streamWrapper::stream_metadata — ストリームメタデータを変更する

説明

public streamWrapper::stream_metadata(string $path, int $option, mixed $value): bool

ストリームのメタデータを設定します。ストリーム URL 上で次のいずれかの関数がコールされたときに呼び出されます。

  • touch()
  • chmod()
  • chown()
  • chgrp()
システムによっては、これらの動作の中に利用できないものがある可能性もあります。

パラメータ

path

メタデータを設定するファイルパスあるいは URL。URL の場合は、:// 区切りの形式でなければならないことに注意しましょう。 それ以外の形式の URL には対応していません。

option

次のいずれかです。

  • STREAM_META_TOUCH (touch() に反応してコールされる)
  • STREAM_META_OWNER_NAME (chown() に反応して文字列引数つきでコールされる)
  • STREAM_META_OWNER (chown() に反応してコールされる)
  • STREAM_META_GROUP_NAME (chgrp() に反応してコールされる)
  • STREAM_META_GROUP (chgrp() に反応してコールされる)
  • STREAM_META_ACCESS (chmod() に反応してコールされる)

value

option の値が

  • STREAM_META_TOUCH の場合は、touch() 関数の二つの引数を含む配列。
  • STREAM_META_OWNER_NAME あるいは PHP_STREAM_META_GROUP_NAME の場合は、オーナーの名前を表す文字列。
  • STREAM_META_OWNER あるいは PHP_STREAM_META_GROUP の場合は、オーナーを表す整数値。
  • STREAM_META_ACCESS の場合は、chmod() への引数となる整数値。

戻り値

成功した場合に true を、失敗した場合に false を返します。 option が実装されていない場合は false を返さなければなりません。

参考

  • touch() - ファイルの最終アクセス時刻および最終更新日をセットする
  • chmod() - ファイルのモードを変更する
  • chown() - ファイルの所有者を変更する
  • chgrp() - ファイルのグループを変更する


ファイルあるいは URL をオープンする

  • ≪ streamWrapper::stream_metadata
  • streamWrapper::stream_read ≫
  • PHP Manual
  • streamWrapper
  • ファイルあるいは URL をオープンする

streamWrapper::stream_open

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_open — ファイルあるいは URL をオープンする

説明

public streamWrapper::stream_open(
string $path,
string $mode,
int $options,
?string &$opened_path
): bool

このメソッドは、ラッパーが初期化された (たとえば fopen() や file_get_contents()) 直後にコールされます。

パラメータ

path

元の関数に渡す URL を指定します。

注意:

parse_url() でこの URL が壊れることがあります。 :// で区切った URL のみをサポートしていることに注意しましょう。 : や :/ も技術的な面では妥当な URL ですが、サポートしていません。

mode

ファイルをオープンする際のモード。詳細は fopen() を参照ください。

注意:

指定した path に対して mode が有効かどうかの確認を忘れないようにしましょう。

options

ストリーム API が設定する追加のフラグ。次の値を OR で連結して指定します。

フラグ | 説明
STREAM_USE_PATH | path が相対パスの場合は、 include_path を用いてリソースを探します。
STREAM_REPORT_ERRORS | このフラグが設定されている場合、 ストリームのオープン時のエラーを trigger_error() で報告しなければなりません。フラグが設定されていない場合は、 エラーを一切報告してはいけません。

opened_path

path のオープンに成功し、 STREAM_USE_PATH が options に設定されていた場合、 opened_path には実際にオープンしたファイル/リソース のフルパスを設定しなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • fopen() - ファイルまたは URL をオープンする
  • parse_url() - URL を解釈し、その構成要素を返す


ストリームから読み込む

  • ≪ streamWrapper::stream_open
  • streamWrapper::stream_seek ≫
  • PHP Manual
  • streamWrapper
  • ストリームから読み込む

streamWrapper::stream_read

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_read — ストリームから読み込む

説明

public streamWrapper::stream_read(int $count): string|false

このメソッドは、fread() および fgets() に対応してコールされます。

注意:

ストリームの読み込み/書き込み位置 (読み込みに成功したバイト数ぶん) の更新を忘れないようにしましょう。

パラメータ

count

現在位置から何バイトぶんのデータを返すか。

戻り値

count バイト未満のデータしか存在しない場合は、 返せる限りのデータを返します。もうデータがない場合は、空文字列を返します。 読み込みが失敗した場合は、false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意:

戻り値が count より長い場合は E_WARNING エラーが発生し、余分なデータは失われます。

注意

注意:

streamWrapper::stream_eof() は、 streamWrapper::stream_read() がコールされた後に直接コールされ、 EOF に達したかどうかを調べます。実装されていない場合は EOF だとみなされます。

警告

ファイル全体を (file_get_contents() などで)
読み込む場合、PHP はループ内で
streamWrapper::stream_read() をコールしてから
streamWrapper::stream_eof() をコールします。
しかし、streamWrapper::stream_read()
が空でない文字列を返す限りは
streamWrapper::stream_eof()
の戻り値を無視します。

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fgets() - ファイルポインタから 1 行取得する


ストリーム内の特定の場所に移動する

  • ≪ streamWrapper::stream_read
  • streamWrapper::stream_set_option ≫
  • PHP Manual
  • streamWrapper
  • ストリーム内の特定の場所に移動する

streamWrapper::stream_seek

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_seek — ストリーム内の特定の場所に移動する

説明

public streamWrapper::stream_seek(int $offset, int $whence = SEEK_SET): bool

このメソッドは、fseek() に対応してコールされます。

ストリームの読み込み/書き込み位置を、 offset と whence に応じて更新しなければなりません。

パラメータ

offset

移動するストリームオフセット。

whence

使用可能な値

  • SEEK_SET - offset バイト目の位置に移動する。
  • SEEK_CUR - 現在位置から offset バイトぶん進める。
  • SEEK_END - ファイルの終端から offset バイトぶん進める。

注意: 現在の実装は、 whence の値を SEEK_CUR に設定することはありません。 そのようなシークは、 内部的に SEEK_SET と同じ動きに変換されます。

戻り値

位置を更新した場合に true、それ以外の場合に false を返します。

注意

注意:

実装されていないの戻り値は false とみなされます。

注意:

成功した場合、
streamWrapper::stream_seek() をコールした直後に
streamWrapper::stream_tell() がコールされます。
streamWrapper::stream_tell() が失敗すると、
呼び出し元関数への戻り値は false に設定されます。

注意:

ストリーム上でシーク操作をしたときに、必ずこの関数がコールされるとは限りません。 PHP のストリームはバッファ付きの読み込みがデフォルトで有効になっている (stream_set_read_buffer() も参照ください) ので、シーク操作が単なるバッファポインタの移動だけで済む場合があります。

参考

  • fseek() - ファイルポインタを移動する


ストリームのオプションを変更する

  • ≪ streamWrapper::stream_seek
  • streamWrapper::stream_stat ≫
  • PHP Manual
  • streamWrapper
  • ストリームのオプションを変更する

streamWrapper::stream_set_option

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

streamWrapper::stream_set_option — ストリームのオプションを変更する

説明

public streamWrapper::stream_set_option(int $option, int $arg1, int $arg2): bool

このメソッドは、ストリームのオプションを設定する際にコールされます。

パラメータ

option

以下のいずれか。

  • STREAM_OPTION_BLOCKING (このメソッドは、stream_set_blocking() に対応してコールされます)
  • STREAM_OPTION_READ_TIMEOUT (このメソッドは、stream_set_timeout() に対応してコールされます)
  • STREAM_OPTION_READ_BUFFER (このメソッドは、stream_set_read_buffer() に対応してコールされます)
  • STREAM_OPTION_WRITE_BUFFER (このメソッドは、stream_set_write_buffer() に対応してコールされます)

arg1

option の値に応じて、以下の内容となります。

  • STREAM_OPTION_BLOCKING: 要求されたブロックモード (1 はブロックモード、0 は非ブロックモード)。
  • STREAM_OPTION_READ_TIMEOUT: タイムアウト秒数。
  • STREAM_OPTION_READ_BUFFER: バッファモード (STREAM_BUFFER_NONE あるいは STREAM_BUFFER_FULL).
  • STREAM_OPTION_WRITE_BUFFER: バッファモード (STREAM_BUFFER_NONE あるいは STREAM_BUFFER_FULL)。

arg2

option の値に応じて、以下の内容となります。

  • STREAM_OPTION_BLOCKING: このオプションは設定されません。
  • STREAM_OPTION_READ_TIMEOUT: タイムアウトマイクロ秒数。
  • STREAM_OPTION_READ_BUFFER: 要求されたバッファサイズ。
  • STREAM_OPTION_WRITE_BUFFER: 要求されたバッファサイズ。

戻り値

成功した場合に true を、失敗した場合に false を返します。 option が実装されていない場合は false を返さなければなりません。

参考

  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • stream_set_write_buffer() - 指定されたストリームのファイル書き込みバッファリングを有効にする


ファイルリソースについての情報を取得する

  • ≪ streamWrapper::stream_set_option
  • streamWrapper::stream_tell ≫
  • PHP Manual
  • streamWrapper
  • ファイルリソースについての情報を取得する

streamWrapper::stream_stat

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_stat — ファイルリソースについての情報を取得する

説明

public streamWrapper::stream_stat(): array|false

このメソッドは、fstat() に対応してコールされます。

パラメータ

この関数にはパラメータはありません。

戻り値

stat() を参照ください。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

参考

  • stat() - ファイルに関する情報を取得する
  • streamwrapper::url_stat() - ファイルについての情報を取得する


ストリームの現在位置を取得する

  • ≪ streamWrapper::stream_stat
  • streamWrapper::stream_truncate ≫
  • PHP Manual
  • streamWrapper
  • ストリームの現在位置を取得する

streamWrapper::stream_tell

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_tell — ストリームの現在位置を取得する

説明

public streamWrapper::stream_tell(): int

このメソッドは、fseek() に対応してコールされ、現在の位置を決定します。

パラメータ

この関数にはパラメータはありません。

戻り値

ストリームの現在位置を返します。

参考

  • streamWrapper::stream_tell()


ストリームを丸める

  • ≪ streamWrapper::stream_tell
  • streamWrapper::stream_write ≫
  • PHP Manual
  • streamWrapper
  • ストリームを丸める

streamWrapper::stream_truncate

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

streamWrapper::stream_truncate — ストリームを丸める

説明

public streamWrapper::stream_truncate(int $new_size): bool

ftruncate() などによる丸めの際にコールされます。

パラメータ

new_size

新しいサイズ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ftruncate() - ファイルを指定した長さに丸める


ストリームに書き込む

  • ≪ streamWrapper::stream_truncate
  • streamWrapper::unlink ≫
  • PHP Manual
  • streamWrapper
  • ストリームに書き込む

streamWrapper::stream_write

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::stream_write — ストリームに書き込む

説明

public streamWrapper::stream_write(string $data): int

このメソッドは、fwrite() に対応してコールされます。

注意:

正常にストリームに書き込めたバイト数ぶんだけ、 ストリームの現在位置を更新することを忘れないようにしましょう。

パラメータ

data

元となるシステムに書き込まれるデータ。

注意:

元となるシステム上にすべてを書き込むだけの余地がない場合は、 可能な限りのデータを格納します。

戻り値

正常に格納できたバイト数、あるいは何も格納できなかった場合は 0 を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意:

戻り値が data の長さより大きい場合は、 E_WARNING が発行されて戻り値がその長さまで切り詰められます。

参考

  • fwrite() - バイナリセーフなファイル書き込み処理


ファイルを削除する

  • ≪ streamWrapper::stream_write
  • streamWrapper::url_stat ≫
  • PHP Manual
  • streamWrapper
  • ファイルを削除する

streamWrapper::unlink

(PHP 5, PHP 7, PHP 8)

streamWrapper::unlink — ファイルを削除する

説明

public streamWrapper::unlink(string $path): bool

このメソッドは、unlink() に対応してコールされます。

注意:

適切なエラーメッセージを返すためには、 ラッパーがファイルの削除に対応していない場合にはこのメソッドを定義しては いけません。

パラメータ

path

削除したいファイルの URL。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • unlink() - ファイルを削除する
  • streamWrapper::rmdir() - ディレクトリを削除する


ファイルについての情報を取得する

  • ≪ streamWrapper::unlink
  • ストリーム 関数 ≫
  • PHP Manual
  • streamWrapper
  • ファイルについての情報を取得する

streamWrapper::url_stat

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

streamWrapper::url_stat — ファイルについての情報を取得する

説明

public streamWrapper::url_stat(string $path, int $flags): array|false

このメソッドは、すべての stat() 関連の関数に対応してコールされます。

  • copy()
  • fileperms()
  • fileinode()
  • filesize()
  • fileowner()
  • filegroup()
  • fileatime()
  • filemtime()
  • filectime()
  • filetype()
  • is_writable()
  • is_readable()
  • is_executable()
  • is_file()
  • is_dir()
  • is_link()
  • file_exists()
  • lstat()
  • stat()
  • SplFileInfo::getPerms()
  • SplFileInfo::getInode()
  • SplFileInfo::getSize()
  • SplFileInfo::getOwner()
  • SplFileInfo::getGroup()
  • SplFileInfo::getATime()
  • SplFileInfo::getMTime()
  • SplFileInfo::getCTime()
  • SplFileInfo::getType()
  • SplFileInfo::isWritable()
  • SplFileInfo::isReadable()
  • SplFileInfo::isExecutable()
  • SplFileInfo::isFile()
  • SplFileInfo::isDir()
  • SplFileInfo::isLink()
  • RecursiveDirectoryIterator::hasChildren()

パラメータ

path

情報を取得したいファイルの URL。 URL の区切り文字は :// でなければならないことに注意しましょう。 それ以外の形式の URL はサポートしていません。

flags

ストリーム API が設定する追加のフラグ。以下の値の OR で組み合わせて使用します。

Flag | Description
STREAM_URL_STAT_LINK | 他のリソースへのリンクを行うことができるリソース (たとえば HTTP Location: による転送やファイルシステムのシンボリックリンク)。 このフラグを指定すると、リンク先のリソースの情報ではなくリンクそのものの情報のみを返します。 このフラグは、lstat()、 is_link() あるいは filetype() に対応して設定されます。
STREAM_URL_STAT_QUIET | このフラグが設定されると、ラッパーが一切エラーを発生しなくなります。 フラグが設定されていない場合、 パス情報の取得中に発生したエラーは trigger_error() を用いて通知します。

戻り値

stat() が返すのと同じ要素を持つ配列を返さなければなりません。 未知の値、あるいは取得できない値については適切な値 (通常は 0) を設定します。 stat() 関数で説明されている mode には特別な注意を払ってください。 失敗した場合は、false を返します。

エラー / 例外

このメソッドのコールに (未実装などの理由で) 失敗した場合、 E_WARNING を発行します。

注意

注意:

有効なコンテキストがコール元関数に渡された場合に streamWrapper::$context プロパティが更新されます。

参考

  • stat() - ファイルに関する情報を取得する
  • streamwrapper::stream_stat() - ファイルリソースについての情報を取得する


ストリーム 関数

目次

  • stream_bucket_append — bucket を brigade に追加する
  • stream_bucket_make_writeable — 操作する brigade から bucket オブジェクトを返す
  • stream_bucket_new — 現在のストリームで使用する新しい bucket を作成する
  • stream_bucket_prepend — bucket を brigade の先頭に追加する
  • stream_context_create — ストリームコンテキストを作成する
  • stream_context_get_default — デフォルトのストリームコンテキストを取得する
  • stream_context_get_options — ストリーム / ラッパー / コンテキストに設定されているオプションを取得する
  • stream_context_get_params — コンテキストのパラメータを取得する
  • stream_context_set_default — デフォルトのストリームコンテキストを設定する
  • stream_context_set_option — ストリーム / ラッパー / コンテキストのオプションを設定する
  • stream_context_set_options — 指定されたコンテキストのオプションを設定する
  • stream_context_set_params — ストリーム / ラッパー / コンテキストのパラメータを設定する
  • stream_copy_to_stream — データをあるストリームから別のストリームにコピーする
  • stream_filter_append — ストリームにフィルタを付加する
  • stream_filter_prepend — フィルタをストリームに付加する
  • stream_filter_register — ユーザー定義のストリームフィルタを登録する
  • stream_filter_remove — ストリームからフィルタを取り除く
  • stream_get_contents — 残りのストリームを文字列に読み込む
  • stream_get_filters — 登録されているフィルタのリストを取得する
  • stream_get_line — 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む
  • stream_get_meta_data — ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する
  • stream_get_transports — 登録されたソケットのトランスポートの一覧を取得する
  • stream_get_wrappers — 登録されているストリームのラッパーのリストを取得する
  • stream_is_local — ローカルストリームかどうかを調べる
  • stream_isatty — ストリームがターミナル型のデバイスかを調べる
  • stream_notification_callback — notification コンテキストパラメータ用のコールバック関数
  • stream_register_wrapper — stream_wrapper_register のエイリアス
  • stream_resolve_include_path — インクルードパスに対してファイル名を解決する
  • stream_select — select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
  • stream_set_blocking — ストリームのブロックモードを有効にする / 解除する
  • stream_set_chunk_size — ストリームのチャンクサイズを設定する
  • stream_set_read_buffer — 指定したストリームのファイル読み込みバッファリングを有効にする
  • stream_set_timeout — ストリームにタイムアウトを設定する
  • stream_set_write_buffer — 指定されたストリームのファイル書き込みバッファリングを有効にする
  • stream_socket_accept — stream_socket_server で作られたソケットの接続を受け入れる
  • stream_socket_client — インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_socket_enable_crypto — 接続済みのソケットについて暗号化の on/off を切り替える
  • stream_socket_get_name — ローカルまたはリモートのソケットの名前を取得する
  • stream_socket_pair — 接続された、区別できないソケットストリームの組を作成する
  • stream_socket_recvfrom — 接続されているかどうかにかかわらず、ソケットからのデータを受信する
  • stream_socket_sendto — 接続されているかどうかにかかわらず、ソケットにデータを送信する
  • stream_socket_server — インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
  • stream_socket_shutdown — 全二重接続を終了する
  • stream_supports_lock — ストリームがロックをサポートしているかどうかを調べる
  • stream_wrapper_register — PHP のクラスとして実装された URL ラッパーを登録する
  • stream_wrapper_restore — 事前に登録を解除された組み込みラッパーを復元する
  • stream_wrapper_unregister — URL ラッパーの登録を解除する


bucket を brigade に追加する

  • ≪ ストリーム 関数
  • stream_bucket_make_writeable ≫
  • PHP Manual
  • ストリーム 関数
  • bucket を brigade に追加する

stream_bucket_append

(PHP 5, PHP 7, PHP 8)

stream_bucket_append — bucket を brigade に追加する

説明

stream_bucket_append(resource $brigade, object $bucket): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


操作する brigade から bucket オブジェクトを返す

  • ≪ stream_bucket_append
  • stream_bucket_new ≫
  • PHP Manual
  • ストリーム 関数
  • 操作する brigade から bucket オブジェクトを返す

stream_bucket_make_writeable

(PHP 5, PHP 7, PHP 8)

stream_bucket_make_writeable — 操作する brigade から bucket オブジェクトを返す

説明

stream_bucket_make_writeable(resource $brigade): ?object

brigade に含まれる内容にアクセスしたり、 操作したりする場合には、常にこの関数がコールされます。 通常は、php_user_filter::filter() からコールされます。

パラメータ

brigade

bucket オブジェクトを返す brigade。

戻り値

以下に示すプロパティを持つ bucket オブジェクトを返すか、 null を返します。

data (string)

data bucket bucket に含まれる現在の文字列。

datalen (integer)

datalen bucket bucket に含まれる文字列の長さ。

参考

  • stream_bucket_append() - bucket を brigade に追加する
  • stream_bucket_prepend() - bucket を brigade の先頭に追加する


現在のストリームで使用する新しい bucket を作成する

  • ≪ stream_bucket_make_writeable
  • stream_bucket_prepend ≫
  • PHP Manual
  • ストリーム 関数
  • 現在のストリームで使用する新しい bucket を作成する

stream_bucket_new

(PHP 5, PHP 7, PHP 8)

stream_bucket_new — 現在のストリームで使用する新しい bucket を作成する

説明

stream_bucket_new(resource $stream, string $buffer): object
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


bucket を brigade の先頭に追加する

  • ≪ stream_bucket_new
  • stream_context_create ≫
  • PHP Manual
  • ストリーム 関数
  • bucket を brigade の先頭に追加する

stream_bucket_prepend

(PHP 5, PHP 7, PHP 8)

stream_bucket_prepend — bucket を brigade の先頭に追加する

説明

stream_bucket_prepend(resource $brigade, object $bucket): void

この関数を呼ぶと、bucket brigade の先頭に bucket を追加できます。一般に、 php_user_filter::filter() から呼ばれます。

パラメータ

brigade

brigade は bucket brigade を指すリソースで、ここにはひとつあるいは複数の bucket オブジェクトが含まれます。

bucket

bucket オブジェクト。

戻り値

値を返しません。

例

例1 stream_bucket_prepend() の例

<?php

class foo extends php_user_filter {
protected $calls = 0;
public function filter($in, $out, &$consumed, $closing) {
while ($bucket = stream_bucket_make_writeable($in)) {
$consumed += $bucket->datalen;
if ($this->calls++ == 2) {
// This bucket will appear again before any other bucket.
stream_bucket_prepend($in, $bucket);
}
}
return PSFS_FEED_ME;
}
}
stream_filter_register('test', 'foo');
print file_get_contents('php://filter/read=test/resource=foo');
?>


ストリームコンテキストを作成する

  • ≪ stream_bucket_prepend
  • stream_context_get_default ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームコンテキストを作成する

stream_context_create

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_create — ストリームコンテキストを作成する

説明

stream_context_create(?array $options = null, ?array $params = null): resource

options に、 指定されたオプションが予め設定されたストリームコンテキストを作成し、 それを返します。

パラメータ

options

次のような形式の連想配列からなる連想配列 $arr['wrapper']['option'] = $value または null でなくてはなりません。 使用可能はラッパーやオプションの一覧は コンテキストオプション を参照ください。

デフォルトは null です。

params

$arr['parameter'] = $value 形式の連想配列、または null でなくてはなりません。 標準のストリームパラメータについては コンテキストパラメータ を参照ください。

戻り値

ストリームコンテキストリソースを返します。

変更履歴

バージョン | 説明
8.0.0 | options と params は、nullable になりました。

例

例1 stream_context_create() の使用

<?php
$opts = [
'http' => [
'method' => "GET",
// Use newline \n to separate multiple headers
'header' => "Accept-language: en\nCookie: foo=bar",
]
];

$context = stream_context_create($opts);

/* 上のヘッダと共に http リクエストを www.example.com に対して
送出します */
$fp = fopen('http://www.example.com', 'r', false, $context);
fpassthru($fp);
fclose($fp);
?>

参考

  • stream_context_set_option() - ストリーム / ラッパー / コンテキストのオプションを設定する
  • サポートするラッパーのリスト (サポートするプロトコル/ラッパー)
  • コンテキストオプション (コンテキストオプションとパラメータ)


デフォルトのストリームコンテキストを取得する

  • ≪ stream_context_create
  • stream_context_get_options ≫
  • PHP Manual
  • ストリーム 関数
  • デフォルトのストリームコンテキストを取得する

stream_context_get_default

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_context_get_default — デフォルトのストリームコンテキストを取得する

説明

stream_context_get_default(?array $options = null): resource

（fopen()、file_get_contents() のような） ファイル操作関数がコンテキストパラメータなしでコールされた場合に使用される デフォルトのストリームコンテキストを返します。デフォルトコンテキストに 関するオプションは、stream_context_create() と同じ 構文で任意に指定することが可能です。

パラメータ

options
options は、 $arr['wrapper']['option'] = $value のような形式の、連想配列の連想配列、 または null である必要があります。

戻り値

ストリームコンテキストリソースを返します。

変更履歴

バージョン | 説明
8.0.0 | options は、nullable になりました。

例

例1 stream_context_get_default() の使用

<?php
$default_opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar",
'proxy'=>"tcp://10.54.1.39:8000"
)
);

$alternate_opts = array(
'http'=>array(
'method'=>"POST",
'header'=>"Content-type: application/x-www-form-urlencoded\r\n" .
"Content-length: " . strlen("baz=bomb"),
'content'=>"baz=bomb"
)
);

$default = stream_context_get_default($default_opts);
$alternate = stream_context_create($alternate_opts);

/* www.example.com に対する通常の GET リクエストを、プロキシサーバー 10.54.1.39
* に対して送信します。コンテキストオプション $default_opts を使用します。
*/
readfile('http://www.example.com');

/* POST リクエストを、直接 www.example.com に送信します。
* コンテキストオプション $alternate_opts を使用します。
*/
readfile('http://www.example.com', false, $alternate);

?>

参考

  • stream_context_create() - ストリームコンテキストを作成する
  • stream_context_set_default() - デフォルトのストリームコンテキストを設定する
  • サポートするラッパーとコンテキストオプションの一覧 (サポートするプロトコル/ラッパー).


ストリーム / ラッパー / コンテキストに設定されているオプションを取得する

  • ≪ stream_context_get_default
  • stream_context_get_params ≫
  • PHP Manual
  • ストリーム 関数
  • ストリーム / ラッパー / コンテキストに設定されているオプションを取得する

stream_context_get_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_get_options — ストリーム / ラッパー / コンテキストに設定されているオプションを取得する

説明

stream_context_get_options(resource $stream_or_context): array

指定されたストリームまたはコンテキストに設定されたオプションを配列として返します。

パラメータ

stream_or_context

オプションを取得したいストリームあるいはコンテキスト。

戻り値

オプションを連想配列で返します。

例

例1 stream_context_get_options() の例

<?php
$params = array("method" => "POST");

stream_context_set_default(array("http" => $params));

var_dump(stream_context_get_options(stream_context_get_default()));

?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["http"]=>
  array(1) {
    ["method"]=>
    string(4) "POST"
  }
}


コンテキストのパラメータを取得する

  • ≪ stream_context_get_options
  • stream_context_set_default ≫
  • PHP Manual
  • ストリーム 関数
  • コンテキストのパラメータを取得する

stream_context_get_params

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

stream_context_get_params — コンテキストのパラメータを取得する

説明

stream_context_get_params(resource $context): array

パラメータおよびオプションの情報を、ストリームあるいはコンテキストから取得します。

パラメータ

context

ストリームリソースあるいは コンテキストリソース。

戻り値

すべてのコンテキストオプションおよびパラメータを含む連想配列を返します。

例

例1 stream_context_get_params() の例

基本的な使用例です。

<?php
$ctx = stream_context_create();
$params = array("notification" => "stream_notification_callback");
stream_context_set_params($ctx, $params);

var_dump(stream_context_get_params($ctx));
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["notification"]=>
  string(28) "stream_notification_callback"
  ["options"]=>
  array(0) {
  }
}

参考

  • stream_context_set_option() - ストリーム / ラッパー / コンテキストのオプションを設定する
  • stream_context_set_params() - ストリーム / ラッパー / コンテキストのパラメータを設定する


デフォルトのストリームコンテキストを設定する

  • ≪ stream_context_get_params
  • stream_context_set_option ≫
  • PHP Manual
  • ストリーム 関数
  • デフォルトのストリームコンテキストを設定する

stream_context_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

stream_context_set_default — デフォルトのストリームコンテキストを設定する

説明

stream_context_set_default(array $options): resource

(fopen()、file_get_contents() のような) ファイル操作関数がコンテキストパラメータなしでコールされた場合に使用される デフォルトのストリームコンテキストを設定します。 stream_context_create() と同じ構文が使用できます。

パラメータ

options

デフォルトコンテキストに設定するオプション。

注意:

options は、 $arr['wrapper']['option'] = $value のような形式の、連想配列の連想配列である必要があります。

戻り値

デフォルトのストリームコンテキストを返します。

例

例1 stream_context_set_default() の例

<?php
$default_opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar",
'proxy'=>"tcp://10.54.1.39:8000"
)
);

$default = stream_context_set_default($default_opts);

/* www.example.com に対する通常の GET リクエストを、プロキシサーバー 10.54.1.39
* に対して送信します。コンテキストオプション $default_opts を使用します。
*/
readfile('http://www.example.com');
?>

参考

  • stream_context_create() - ストリームコンテキストを作成する
  • stream_context_get_default() - デフォルトのストリームコンテキストを取得する
  • サポートするラッパーとコンテキストオプションの一覧 (サポートするプロトコル/ラッパー).


ストリーム / ラッパー / コンテキストのオプションを設定する

  • ≪ stream_context_set_default
  • stream_context_set_options ≫
  • PHP Manual
  • ストリーム 関数
  • ストリーム / ラッパー / コンテキストのオプションを設定する

stream_context_set_option

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_set_option — ストリーム / ラッパー / コンテキストのオプションを設定する

説明

stream_context_set_option(
resource $stream_or_context,
string $wrapper,
string $option,
mixed $value
): bool
stream_context_set_option(resource $stream_or_context, array $options): bool

指定されたストリームまたはコンテキストのオプションを設定します。 value の内容が wrapper に対する option として設定されます。

パラメータ

stream_or_context

オプションを適用したいストリームあるいはコンテキストリソース。

wrapper

ラッパーの名前(プロトコルによって異なります)。 ストリームオプションの一覧は コンテキストオプションおよびパラメータを参照ください。

option

オプションの名前

value

オプションの値

options

stream_or_context に設定するオプション。

注意:

options は、 $arr['wrapper']['option'] = $value のような形式の、連想配列の連想配列である必要があります。

ストリームオプションの一覧は コンテキストオプションおよびパラメータを参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。


指定されたコンテキストのオプションを設定する

  • ≪ stream_context_set_option
  • stream_context_set_params ≫
  • PHP Manual
  • ストリーム 関数
  • 指定されたコンテキストのオプションを設定する

stream_context_set_options

(PHP 8 >= 8.3.0)

stream_context_set_options — 指定されたコンテキストのオプションを設定する

説明

stream_context_set_options(resource $context, array $options): true

指定されたコンテキストのオプションを設定します。

パラメータ

context

オプションを適用するストリーム、またはコンテキストリソース。

options

context に設定するオプション。

注意:

options は、 $array['wrapper']['option'] = $value のフォーマットからなる連想配列でなければいけません。

ストリームオプションの一覧は コンテキストオプションとパラメータ を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_context_set_options() の例

<?php

$context = stream_context_create();

$options = [
'http' => [
'protocol_version' => 1.1,
'user_agent' => 'PHPT Agent',
],
];

stream_context_set_options($context, $options);
var_dump(stream_context_get_options($context));
?>

上の例の出力は以下となります。

array(1) {
  ["http"]=>
  array(2) {
    ["protocol_version"]=>
    float(1.1)
    ["user_agent"]=>
    string(10) "PHPT Agent"
  }
}

参考

  • stream_context_set_option() - ストリーム / ラッパー / コンテキストのオプションを設定する


ストリーム / ラッパー / コンテキストのパラメータを設定する

  • ≪ stream_context_set_options
  • stream_copy_to_stream ≫
  • PHP Manual
  • ストリーム 関数
  • ストリーム / ラッパー / コンテキストのパラメータを設定する

stream_context_set_params

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_context_set_params — ストリーム / ラッパー / コンテキストのパラメータを設定する

説明

stream_context_set_params(resource $context, array $params): true

指定したコンテキストのパラメータを設定します。

パラメータ

context

パラメータを適用したいストリームあるいはコンテキスト。

params

$params['paramname'] = "paramvalue"; という形式で設定される、連想配列のパラメータ。

サポートされているパラメータ
パラメータ | 目的
notification | ストリームから何らかの通知があった時に呼ばれる、ユーザー定義のコールバック関数を指定します。 http:// および ftp:// ストリームラッパーでのみサポートされます。
options | コンテキストオプションおよびパラメータ を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • stream_notification_callback() - notification コンテキストパラメータ用のコールバック関数


データをあるストリームから別のストリームにコピーする

  • ≪ stream_context_set_params
  • stream_filter_append ≫
  • PHP Manual
  • ストリーム 関数
  • データをあるストリームから別のストリームにコピーする

stream_copy_to_stream

(PHP 5, PHP 7, PHP 8)

stream_copy_to_stream — データをあるストリームから別のストリームにコピーする

説明

stream_copy_to_stream(
resource $from,
resource $to,
?int $length = null,
int $offset = 0
): int|false

現在の位置（あるいはもし指定されていれば offset の位置）から最大 length バイトのデータを from から to にコピーします。もし length が null の 場合は、from にある残りすべてのデータが コピーされます。

パラメータ

from

コピー元のストリーム。

to

コピー先のストリーム。

length

コピーする最大バイト数。 デフォルトでは、残りの全てのデータがコピーされます。

offset

コピーを開始する位置。

戻り値

コピーされたバイト数を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 stream_copy_to_stream() の例

<?php
$src = fopen('http://www.example.com', 'r');
$dest1 = fopen('first1k.txt', 'w');
$dest2 = fopen('remainder.txt', 'w');

echo stream_copy_to_stream($src, $dest1, 1024) . " バイトが first1k.txt にコピーされました\n";
echo stream_copy_to_stream($src, $dest2) . " バイトが remainder.txt にコピーされました\n";

?>

参考

  • copy() - ファイルをコピーする


ストリームにフィルタを付加する

  • ≪ stream_copy_to_stream
  • stream_filter_prepend ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームにフィルタを付加する

stream_filter_append

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_filter_append — ストリームにフィルタを付加する

説明

stream_filter_append(
resource $stream,
string $filtername,
int $read_write = ?,
mixed $params = ?
): resource

filtername で指定されたフィルタを、 stream に付加されているフィルタのリストに加えます。

パラメータ

stream

対象となるストリーム。

filtername

フィルタ名。

read_write

デフォルトでは、 stream_filter_append() は ストリームが読み込み用に開かれている場合は (つまり、オープンモードが r あるいは + を伴う場合は)、 フィルタを リードフィルタチェイン に追加し、 ストリームが書き出し用に開かれている場合は(つまり、オープンモードが w か aか、あるいは+ を伴う場合は)、 ライトフィルターチェィンにも追加します。 STREAM_FILTER_READ・ STREAM_FILTER_WRITE・ STREAM_FILTER_ALL を read_writeパラメータに渡すことで、この挙動を変えることができます。

params

このフィルタは、指定された params と共に、 リストの末尾に追加され、ストリームに対する操作の中で最後に呼び出されます。 フィルタをリストの先頭に加えたいときは、stream_filter_prepend() を使ってください。

戻り値

成功した場合にリソース、失敗した場合に false を返します。 このリソースは、stream_filter_remove() をコールする際にこのフィルタインスタンスを参照するために使用可能です。

false が返されるのは、stream がリソースではない場合や filtername が見つからない場合です。

例

例1 フィルタの適用される場所を制御する

<?php
/* ファイルを読み書き用に開く */
$fp = fopen('test.txt', 'w+');

/* ROT13 フィルタをライトフィルタチェインに付加する。
* リードフィルタチェインには付加しない。*/
stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE);

/* 単純な文字列をファイルに書き出す。
* この文字列には、出口で ROT13 変換が適用される。
*/
fwrite($fp, "This is a test\n");

/* ファイルの最初に戻る */
rewind($fp);

/* 書き出した内容を読み戻す。
* もし、フィルタがリードフィルタチェインにも
* 付加されていれば、再び読み出し時に ROT13 が適用され、
* テキストは元の状態に戻るはず。 */
fpassthru($fp);

fclose($fp);

/* 期待される出力
---------------

Guvf vf n grfg

*/
?>

注意

注意: カスタム(ユーザー)フィルタを使うには
カスタムフィルタを filtername に指定するためには、 まず stream_filter_register() 関数でそれを登録しておく 必要があります。

注意: ストリームデータは（ローカルおよびリモートの）リソースからチャンク単位で 読み込まれ、内部バッファに保持されます。新しいフィルタがストリームに 追加されると、内部バッファのデータがその時点でフィルタリングされます。 これは stream_filter_prepend() の挙動とは違います。

注意: フィルタが読み込み用および書き込み用に追加されると、フィルタのインスタンスが 2 つ作成されます。両方のフィルタリソースを取得するには、 STREAM_FILTER_READ と STREAM_FILTER_WRITE で stream_filter_append() を 2 回コールしなければなりません。

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_filter_prepend() - フィルタをストリームに付加する
  • stream_get_filters() - 登録されているフィルタのリストを取得する


フィルタをストリームに付加する

  • ≪ stream_filter_append
  • stream_filter_register ≫
  • PHP Manual
  • ストリーム 関数
  • フィルタをストリームに付加する

stream_filter_prepend

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_filter_prepend — フィルタをストリームに付加する

説明

stream_filter_prepend(
resource $stream,
string $filtername,
int $read_write = ?,
mixed $params = ?
): resource

filtername で指定されたフィルタを、 stream に付加されているフィルタのリストに加えます。

パラメータ

stream

対象となるストリーム。

filtername

フィルタ名。

read_write

デフォルトでは、 stream_filter_prepend() は ストリームが読み込み用に開かれている場合は (つまり、オープンモードが r あるいは + を伴う場合は)、 フィルタを リードフィルタチェイン に追加し、 ストリームが書き出し用に開かれている場合は(つまり、オープンモードが w か aか、あるいは+ を伴う場合は)、 ライトフィルターチェィンにも追加します。 STREAM_FILTER_READ・ STREAM_FILTER_WRITE・ STREAM_FILTER_ALL を read_writeパラメータに渡すことで、この挙動を変えることができます。 このパラメータを使った例については、 stream_filter_append() を参照ください。

params

このフィルタは、指定された params と共に、 リストの先頭に追加され、ストリームに対する操作の中で最初に呼び出されます。 フィルタをリストの末尾に加えたいときは、stream_filter_append() を使ってください。

戻り値

成功した場合にリソース、失敗した場合に false を返します。 このリソースは、stream_filter_remove() をコールする際にこのフィルタインスタンスを参照するために使用可能です。

false が返されるのは、stream がリソースではない場合や filtername が見つからない場合です。

注意

注意: カスタム(ユーザー)フィルタを使うには
カスタムフィルタを filtername に指定するためには、 まず stream_filter_register() 関数でそれを登録しておく 必要があります。

注意: ストリームデータは（ローカルおよびリモートの）リソースからチャンク単位で 読み込まれ、内部バッファに保持されます。新しいフィルタがストリームに 追加されても、内部バッファにあるデータのうち既に他のフィルタの処理が 終わっているものは新しいフィルタでは処理されません。 これは stream_filter_apppend() の挙動とは違います。

注意: フィルタが読み込み用および書き込み用に追加されると、フィルタのインスタンスが 2 つ作成されます。両方のフィルタリソースを取得するには、 STREAM_FILTER_READ と STREAM_FILTER_WRITE で stream_filter_prepend() を 2 回コールしなければなりません。

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_filter_append() - ストリームにフィルタを付加する


ユーザー定義のストリームフィルタを登録する

  • ≪ stream_filter_prepend
  • stream_filter_remove ≫
  • PHP Manual
  • ストリーム 関数
  • ユーザー定義のストリームフィルタを登録する

stream_filter_register

(PHP 5, PHP 7, PHP 8)

stream_filter_register — ユーザー定義のストリームフィルタを登録する

説明

stream_filter_register(string $filter_name, string $class): bool

stream_filter_register() は、fopen() や fread() などのファイルシステムの関数で利用可能な 登録されているどの種類のストリームとも一緒に使うことのできる カスタムフィルタを登録します。

パラメータ

filter_name

登録するフィルタ名。

class

フィルタを実装するには、まず、php_user_filter を継承したクラスのメンバ関数を実装しなくてはなりません。 PHP は、書き込みまたは読み出し操作を カスタムフィルタの付加されたストリームに対して行う際に、まず データをそのフィルタに(そして、付加されている他のすべてのフィルタにも) 渡し、指示どおりストリームのデータが変更されるようにします。 メソッドの実装は、php_user_filter の説明の通りにしなければなりません。 さもないと、定義されていない動作をします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

stream_filter_register() は、 指定された filter_name がすでに定義されている場合、 false を返します。

例

例1 foo-bar.txt ストリームの文字を大文字化するフィルタ

下記の例は、読み込まれたり書き出されたりするデータに含まれるすべての英文字を 大文字化する strtoupper ストリームを実装し、foo-bar.txt ストリームに適用するものです。

<?php

/* フィルタクラスを定義する */
class strtoupper_filter extends php_user_filter {
function filter($in, $out, &$consumed, $closing)
{
while ($bucket = stream_bucket_make_writeable($in)) {
$bucket->data = strtoupper($bucket->data);
$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}

/* PHP にフィルタを登録する */
stream_filter_register("strtoupper", "strtoupper_filter")
or die("Failed to register filter");

$fp = fopen("foo-bar.txt", "w");

/* フィルタを開いたストリームに付加する */
stream_filter_append($fp, "strtoupper");

fwrite($fp, "Line1\n");
fwrite($fp, "Word - 2\n");
fwrite($fp, "Easy As 123\n");

fclose($fp);

/* ファイルを読み出し出力する
*/
readfile("foo-bar.txt");

?>

上の例の出力は以下となります。

LINE1
WORD - 2
EASY AS 123

例2 複数のフィルタ名に対応する一般的なフィルタクラスを登録する

<?php

/* フィルタクラスを定義する */
class string_filter extends php_user_filter {
var $mode;

function filter($in, $out, &$consumed, $closing)
{
while ($bucket = stream_bucket_make_writeable($in)) {
if ($this->mode == 1) {
$bucket->data = strtoupper($bucket->data);
} elseif ($this->mode == 0) {
$bucket->data = strtolower($bucket->data);
}

$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}

function onCreate()
{
if ($this->filtername == 'str.toupper') {
$this->mode = 1;
} elseif ($this->filtername == 'str.tolower') {
$this->mode = 0;
} else {
/* その他の str.* フィルタが問い合わせられた場合は
失敗を報告し、PHP が検索を続けられるようにする */
return false;
}

return true;
}
}

/* PHP にフィルタを登録する */
stream_filter_register("str.*", "string_filter")
or die("Failed to register filter");

$fp = fopen("foo-bar.txt", "w");

/* フィルタを開いたストリームに付加する
ここで str.tolower をバインドすることも可能 */
stream_filter_append($fp, "str.toupper");

fwrite($fp, "Line1\n");
fwrite($fp, "Word - 2\n");
fwrite($fp, "Easy As 123\n");

fclose($fp);

/* ファイルを読み出し出力する
*/
readfile("foo-bar.txt");
?>

上の例の出力は以下となります。

LINE1
WORD - 2
EASY AS 123

参考

  • stream_wrapper_register() - PHP のクラスとして実装された URL ラッパーを登録する
  • stream_filter_append() - ストリームにフィルタを付加する
  • stream_filter_prepend() - フィルタをストリームに付加する


ストリームからフィルタを取り除く

  • ≪ stream_filter_register
  • stream_get_contents ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームからフィルタを取り除く

stream_filter_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_filter_remove — ストリームからフィルタを取り除く

説明

stream_filter_remove(resource $stream_filter): bool

事前に stream_filter_prepend() あるいは stream_filter_append() でストリームに追加した フィルタを削除します。フィルタの内部バッファに残っているデータは 削除前にフラッシュされ、次のフィルタに渡されます。

パラメータ

stream_filter

削除するストリームフィルタ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ストリームの再フィルタリングを動的に行う

<?php
/* テストファイルを読み込み/書き込みモードでオープンします */
$fp = fopen("test.txt", "rw");

$rot13_filter = stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE);
fwrite($fp, "This is ");
stream_filter_remove($rot13_filter);
fwrite($fp, "a test\n");

rewind($fp);
fpassthru($fp);
fclose($fp);

?>

上の例の出力は以下となります。

Guvf vf a test

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_filter_append() - ストリームにフィルタを付加する
  • stream_filter_prepend() - フィルタをストリームに付加する


残りのストリームを文字列に読み込む

  • ≪ stream_filter_remove
  • stream_get_filters ≫
  • PHP Manual
  • ストリーム 関数
  • 残りのストリームを文字列に読み込む

stream_get_contents

(PHP 5, PHP 7, PHP 8)

stream_get_contents — 残りのストリームを文字列に読み込む

説明

stream_get_contents(resource $stream, ?int $length = null, int $offset = -1): string|false

file_get_contents() と似ていますが、 stream_get_contents() は既にオープンしている ストリームリソースに対して操作を行います。そして、指定した offset から始まる最大 length バイトのデータを取得して文字列に 保存します。

パラメータ

stream (resource)

ストリームリソース（例: fopen() の返す値）。

length (int)

読み込む最大バイト数。デフォルトは null （バッファの残りのデータをすべて読み込む）。

offset (int)

読み込みを開始する前に移動する位置。負の数を指定した場合は移動が発生せず、 現在位置から読み込みを開始します。

戻り値

文字列を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 stream_get_contents() の例

<?php

if ($stream = fopen('http://www.example.com', 'r')) {
// オフセット 10 から開始して、残りのすべてのページを表示します
echo stream_get_contents($stream, -1, 10);

fclose($stream);
}

if ($stream = fopen('http://www.example.net', 'r')) {
// 最初の 5 バイトを表示します
echo stream_get_contents($stream, 5);

fclose($stream);
}

?>

注意

注意: この関数はバイナリデータに対応しています。

注意:

length の値に null 以外を指定した場合、 この関数はすぐにその指定したサイズの内部バッファを確保します。 たとえ、実際に扱うコンテンツが十分小さかったとしても同じです。

参考

  • fgets() - ファイルポインタから 1 行取得する
  • fread() - バイナリセーフなファイルの読み込み
  • fpassthru() - ファイルポインタ上に残っているすべてのデータを出力する


登録されているフィルタのリストを取得する

  • ≪ stream_get_contents
  • stream_get_line ≫
  • PHP Manual
  • ストリーム 関数
  • 登録されているフィルタのリストを取得する

stream_get_filters

(PHP 5, PHP 7, PHP 8)

stream_get_filters — 登録されているフィルタのリストを取得する

説明

stream_get_filters(): array

実行中のシステムに登録されているフィルタの一覧を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

使用可能なすべてのストリームフィルタの名前を含む配列を返します。

例

例1 stream_get_filters() を使用する

<?php
$streamlist = stream_get_filters();
print_r($streamlist);
?>

上の例の出力は、 たとえば以下のようになります。

Array (
  [0] => string.rot13
  [1] => string.toupper
  [2] => string.tolower
  [3] => string.base64
  [4] => string.quoted-printable
)

参考

  • stream_filter_register() - ユーザー定義のストリームフィルタを登録する
  • stream_get_wrappers() - 登録されているストリームのラッパーのリストを取得する


指定されたデリミタの位置までのデータを一行分としてストリームから読み込む

  • ≪ stream_get_filters
  • stream_get_meta_data ≫
  • PHP Manual
  • ストリーム 関数
  • 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む

stream_get_line

(PHP 5, PHP 7, PHP 8)

stream_get_line — 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む

説明

stream_get_line(resource $stream, int $length, string $ending = ""): string|false

指定したハンドルから一行取得します。

読み込みは、length バイト読まれたか、 ending で指定された空でない文字列がストリームに見つかったか (この文字列は返値に 含まれません)、あるいは EOF に達したとき、のうち一番最初に遭遇したところで停止します。

この関数は fgets() とほとんど同一ですが、 \n や \r 、\r\n といった一般的な文字列以外を行末を示すデリミタ として指定できる点で、またデリミタ自体を返値に 含まない 点で異なります。

パラメータ

stream

有効なファイルハンドル。

length

ハンドルから読み込む最大バイト数。 負の値はサポートされていません。 ゼロ(0) を指定すると、 ソケットのデフォルトのチャンクサイズ つまり、8192 を使います。

ending

オプションのデリミタ文字列。

戻り値

最大 length バイトの、 stream で指定されたファイルから読み込んだデータを返します。 失敗した場合に false を返します

参考

  • fread() - バイナリセーフなファイルの読み込み
  • fgets() - ファイルポインタから 1 行取得する
  • fgetc() - ファイルポインタから1文字取り出す


ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

  • ≪ stream_get_line
  • stream_get_transports ≫
  • PHP Manual
  • ストリーム 関数
  • ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

stream_get_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_get_meta_data — ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する

説明

stream_get_meta_data(resource $stream): array

既存の stream に関する情報を返します。

パラメータ

stream

ストリームは fopen()、fsockopen()、pfsockopen()、stream_socket_client() で作成されたいずれのものも指定できます。

戻り値

結果の配列は次のような項目を含みます。

  • timed_out (bool) - 最後に fread() または fgets() でデータを待っている時にタイムアウトした場合 true を返します。

  • blocked (bool) - ストリームがブロック I/O モードの場合に true となります。 stream_set_blocking() を参照ください。

  • eof (bool) - ストリームが EOF に 達した時 true となります。 ストリームがソケットベースの場合、このメンバーは、 たとえ unread_bytes が 0 でなくても true になる場合があることに注意してください。 まだデータがあるかどうかを調べるには、このパラメータではなく、 feof() を使ってください。

  • unread_bytes (int) - PHP の 内部バッファにあるデータのバイト数。

    注意: スクリプト中でこの値を使用してはいけません。

  • stream_type (string) - ストリームの下層にある実装を表すラベル

  • wrapper_type (string) - ストリームを覆うプロトコルラッパーを表すラベル。 ラッパーについては サポートするプロトコル/ラッパー を参照ください。

  • wrapper_data (mixed) - ストリームに付随しているラッパーの固有のデータ。 ラッパーとその固有の情報については、サポートするプロトコル/ラッパー を参照ください。

  • mode (string) - このストリームに要求される アクセスモード（fopen() リファレンスの表 1 を参照ください）。

  • seekable (bool) - 現在のストリーム内で 移動が可能かどうか。

  • uri (string) - このストリームに関連付けられた URI / ファイル名。

  • crypto (array) - このストリームに関連付けられた TLS 接続のメタデータ (注意: リソースのストリームが TLS を使っている場合にのみ含まれます)

例

例1 fopen() を使い、http 経由で stream_get_meta_data() を使う例

<?php
$url = 'http://www.example.com/';

if (!$fp = fopen($url, 'r')) {
trigger_error("Unable to open URL ($url)", E_USER_ERROR);
}

$meta = stream_get_meta_data($fp);

var_dump($meta);

fclose($fp);
?>

上の例の出力は、 たとえば以下のようになります。

array(10) {
  'timed_out' =>
  bool(false)
  'blocked' =>
  bool(true)
  'eof' =>
  bool(false)
  'wrapper_data' =>
  array(13) {
    [0] =>
    string(15) "HTTP/1.1 200 OK"
    [1] =>
    string(11) "Age: 244629"
    [2] =>
    string(29) "Cache-Control: max-age=604800"
    [3] =>
    string(38) "Content-Type: text/html; CHARSET=shift-jis"
    [4] =>
    string(35) "Date: Sat, 20 Nov 2021 18:17:57 GMT"
    [5] =>
    string(24) "Etag: "3147526947+ident""
    [6] =>
    string(38) "Expires: Sat, 27 Nov 2021 18:17:57 GMT"
    [7] =>
    string(44) "Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT"
    [8] =>
    string(22) "Server: ECS (chb/0286)"
    [9] =>
    string(21) "Vary: Accept-Encoding"
    [10] =>
    string(12) "X-Cache: HIT"
    [11] =>
    string(20) "Content-Length: 1256"
    [12] =>
    string(17) "Connection: close"
  }
  'wrapper_type' =>
  string(4) "http"
  'stream_type' =>
  string(14) "tcp_socket/ssl"
  'mode' =>
  string(1) "r"
  'unread_bytes' =>
  int(1256)
  'seekable' =>
  bool(false)
  'uri' =>
  string(23) "http://www.example.com/"
}

例2 stream_socket_client() を使い、https 経由で stream_get_meta_data() を使う例

<?php
$streamContext = stream_context_create(
[
'ssl' => [
'capture_peer_cert' => true,
'capture_peer_cert_chain' => true,
'disable_compression' => true,
],
]
);

$client = stream_socket_client(
'ssl://www.example.com:443',
$errorNumber,
$errorDescription,
40,
STREAM_CLIENT_CONNECT,
$streamContext
);

$meta = stream_get_meta_data($client);

var_dump($meta);
?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  'crypto' =>
  array(4) {
    'protocol' =>
    string(7) "TLSv1.3"
    'cipher_name' =>
    string(22) "TLS_AES_256_GCM_SHA384"
    'cipher_bits' =>
    int(256)
    'cipher_version' =>
    string(7) "TLSv1.3"
  }
  'timed_out' =>
  bool(false)
  'blocked' =>
  bool(true)
  'eof' =>
  bool(false)
  'stream_type' =>
  string(14) "tcp_socket/ssl"
  'mode' =>
  string(2) "r+"
  'unread_bytes' =>
  int(0)
  'seekable' =>
  bool(false)
}

注意

注意:

この関数は、Socket 拡張モジュール で作成したソケットでは動作しません。

参考

  • get_headers() - HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
  • $http_response_header


登録されたソケットのトランスポートの一覧を取得する

  • ≪ stream_get_meta_data
  • stream_get_wrappers ≫
  • PHP Manual
  • ストリーム 関数
  • 登録されたソケットのトランスポートの一覧を取得する

stream_get_transports

(PHP 5, PHP 7, PHP 8)

stream_get_transports — 登録されたソケットのトランスポートの一覧を取得する

説明

stream_get_transports(): array

スクリプトを走らせているシステムにおいて利用可能なソケットのトランスポートのリストを配列として返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ソケットのトランスポート名の配列を返します。

例

例1 stream_get_transports() を使った例

<?php
$xportlist = stream_get_transports();
print_r($xportlist);
?>

上の例の出力は、 たとえば以下のようになります。

Array (
  [0] => tcp
  [1] => udp
  [2] => unix
  [3] => udg
)

参考

  • stream_get_filters() - 登録されているフィルタのリストを取得する
  • stream_get_wrappers() - 登録されているストリームのラッパーのリストを取得する


登録されているストリームのラッパーのリストを取得する

  • ≪ stream_get_transports
  • stream_is_local ≫
  • PHP Manual
  • ストリーム 関数
  • 登録されているストリームのラッパーのリストを取得する

stream_get_wrappers

(PHP 5, PHP 7, PHP 8)

stream_get_wrappers — 登録されているストリームのラッパーのリストを取得する

説明

stream_get_wrappers(): array

実行中のシステムで使用可能な、登録済みのストリームの一覧を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

スクリプトを走らせているシステム上で使うことのできるすべてのストリーム ラッパーの名前を配列の形で返します。

例

例1 stream_get_wrappers() の例

<?php
print_r(stream_get_wrappers());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => php
    [1] => file
    [2] => http
    [3] => ftp
    [4] => compress.bzip2
    [5] => compress.zlib
)

例2 ストリームラッパーのが存在するかどうかを調べる

<?php
// bzip2 ストリームラッパーが存在するかどうかを調べます
if (in_array('compress.bzip2', stream_get_wrappers())) {
echo 'compress.bzip2:// サポートが有効です。';
} else {
echo 'compress.bzip2:// サポートは有効ではありません。';
}
?>

参考

  • stream_wrapper_register() - PHP のクラスとして実装された URL ラッパーを登録する


ローカルストリームかどうかを調べる

  • ≪ stream_get_wrappers
  • stream_isatty ≫
  • PHP Manual
  • ストリーム 関数
  • ローカルストリームかどうかを調べる

stream_is_local

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

stream_is_local — ローカルストリームかどうかを調べる

説明

stream_is_local(resource|string $stream): bool

ストリームあるいは URL が、ローカルのものであるかどうかを調べます。

パラメータ

stream

調べたいストリームリソースあるいは URL。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_is_local() の例

基本的な使用例です。

<?php
var_dump(stream_is_local("http://example.com"));
var_dump(stream_is_local("/etc"));
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


ストリームがターミナル型のデバイスかを調べる

  • ≪ stream_is_local
  • stream_notification_callback ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームがターミナル型のデバイスかを調べる

stream_isatty

(PHP 7 >= 7.2.0, PHP 8)

stream_isatty — ストリームがターミナル型のデバイスかを調べる

説明

stream_isatty(resource $stream): bool

stream が、有効なターミナル型のデバイスを参照しているかを調べます。 この関数は、posix_isatty() よりも移植性に優れたバージョンです。 なぜなら、この関数は Windows でも動作するからです。

パラメータ

stream

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_isatty() の例

このコマンドは、標準出力 / 標準エラー出力 がファイルにリダイレクトされているかどうかを調べるのに使えます。

php -r "var_export(stream_isatty(STDERR));"

上の例の出力は、 たとえば以下のようになります。

true
php -r "var_export(stream_isatty(STDERR));" 2>output.txt

上の例の出力は、 たとえば以下のようになります。

false


notification コンテキストパラメータ用のコールバック関数

  • ≪ stream_isatty
  • stream_register_wrapper ≫
  • PHP Manual
  • ストリーム 関数
  • notification コンテキストパラメータ用のコールバック関数

stream_notification_callback

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

stream_notification_callback — notification コンテキストパラメータ用のコールバック関数

説明

stream_notification_callback(
int $notification_code,
int $severity,
?string $message,
int $message_code,
int $bytes_transferred,
int $bytes_max
): void

イベント発生時にコールされる callable 関数です。 notification context parameter が使用します。

注意:

これは実際の関数では ありません。 コールバック関数がどうあるべきかというプロトタイプだけを示すものです。

パラメータ

notification_code

STREAM_NOTIFY_* 通知定数のひとつ。

severity

STREAM_NOTIFY_SEVERITY_* 通知定数のひとつ。

message

イベントについて説明するメッセージが存在する場合に渡されます。

message_code

イベントについて説明するコードが存在する場合に渡されます。

この値の意味は、使用するラッパーによって異なります。

bytes_transferred

利用可能な場合は bytes_transferred の値が格納されます。

bytes_max

利用可能な場合は bytes_max の値が格納されます。

戻り値

値を返しません。

例

例1 stream_notification_callback() の例

<?php
function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {

switch($notification_code) {
case STREAM_NOTIFY_RESOLVE:
case STREAM_NOTIFY_AUTH_REQUIRED:
case STREAM_NOTIFY_COMPLETED:
case STREAM_NOTIFY_FAILURE:
case STREAM_NOTIFY_AUTH_RESULT:
var_dump($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max);
/* 無視 */
break;

case STREAM_NOTIFY_REDIRECTED:
echo "Being redirected to: ", $message;
break;

case STREAM_NOTIFY_CONNECT:
echo "Connected...";
break;

case STREAM_NOTIFY_FILE_SIZE_IS:
echo "Got the filesize: ", $bytes_max;
break;

case STREAM_NOTIFY_MIME_TYPE_IS:
echo "Found the mime-type: ", $message;
break;

case STREAM_NOTIFY_PROGRESS:
echo "Made some progress, downloaded ", $bytes_transferred, " so far";
break;
}
echo "\n";
}

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));

file_get_contents("http://php.net/contact", false, $ctx);
?>

上の例の出力は、 たとえば以下のようになります。

Connected...
Found the mime-type: text/html; CHARSET=shift-jis
Being redirected to: http://no.php.net/contact
Connected...
Got the filesize: 0
Found the mime-type: text/html; CHARSET=shift-jis
Being redirected to: http://no.php.net/contact.php
Connected...
Got the filesize: 4589
Found the mime-type: text/html;CHARSET=shift-jis
Made some progress, downloaded 0 so far
Made some progress, downloaded 0 so far
Made some progress, downloaded 0 so far
Made some progress, downloaded 1440 so far
Made some progress, downloaded 2880 so far
Made some progress, downloaded 4320 so far
Made some progress, downloaded 5760 so far
Made some progress, downloaded 6381 so far
Made some progress, downloaded 7002 so far

例2 コマンドラインのダウンロードツール用のシンプルなプログレスバー

<?php
function usage($argv) {
echo "Usage:\n";
printf("\tphp %s <http://example.com/file> <localfile>\n", $argv[0]);
exit(1);
}

function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {
static $filesize = null;

switch($notification_code) {
case STREAM_NOTIFY_RESOLVE:
case STREAM_NOTIFY_AUTH_REQUIRED:
case STREAM_NOTIFY_COMPLETED:
case STREAM_NOTIFY_FAILURE:
case STREAM_NOTIFY_AUTH_RESULT:
/* 無視 */
break;

case STREAM_NOTIFY_REDIRECTED:
echo "Being redirected to: ", $message, "\n";
break;

case STREAM_NOTIFY_CONNECT:
echo "Connected...\n";
break;

case STREAM_NOTIFY_FILE_SIZE_IS:
$filesize = $bytes_max;
echo "Filesize: ", $filesize, "\n";
break;

case STREAM_NOTIFY_MIME_TYPE_IS:
echo "Mime-type: ", $message, "\n";
break;

case STREAM_NOTIFY_PROGRESS:
if ($bytes_transferred > 0) {
if (!isset($filesize)) {
printf("\rUnknown filesize.. %2d kb done..", $bytes_transferred/1024);
} else {
$length = (int)(($bytes_transferred/$filesize)*100);
printf("\r[%-100s] %d%% (%2d/%2d kb)", str_repeat("=", $length). ">", $length, ($bytes_transferred/1024), $filesize/1024);
}
}
break;
}
}

isset($argv[1], $argv[2]) or usage($argv);

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));

$fp = fopen($argv[1], "r", false, $ctx);
if (is_resource($fp) && file_put_contents($argv[2], $fp)) {
echo "\nDone!\n";
exit(0);
}

$err = error_get_last();
echo "\nErrrrrorr..\n", $err["message"], "\n";
exit(1);
?>

上の例を php -n fetch.php http://no2.php.net/get/php-5-LATEST.tar.bz2/from/this/mirror php-latest.tar.bz2 のように実行すると、次のような出力となります。

Connected...
Mime-type: text/html; CHARSET=shift-jis
Being redirected to: http://no2.php.net/distributions/php-5.2.5.tar.bz2
Connected...
Filesize: 7773024
Mime-type: application/octet-stream
[========================================>                                                           ] 40% (3076/7590 kb)

参考

  • コンテキストパラメータ


stream_wrapper_register のエイリアス

  • ≪ stream_notification_callback
  • stream_resolve_include_path ≫
  • PHP Manual
  • ストリーム 関数
  • stream_wrapper_register のエイリアス

stream_register_wrapper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_register_wrapper — stream_wrapper_register() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_wrapper_register().


インクルードパスに対してファイル名を解決する

  • ≪ stream_register_wrapper
  • stream_select ≫
  • PHP Manual
  • ストリーム 関数
  • インクルードパスに対してファイル名を解決する

stream_resolve_include_path

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

stream_resolve_include_path — インクルードパスに対してファイル名を解決する

説明

stream_resolve_include_path(string $filename): string|false

インクルードパスに対して filename を解決します。 fopen()/include と同じルールに従います。

パラメータ

filename

解決するファイル名。

戻り値

解決したファイル名を含む文字列を返します。失敗した場合に false を返します。

例

例1 stream_resolve_include_path() の例

基本的な使いかたです。

<?php
var_dump(stream_resolve_include_path("test.php"));
?>

上の例の出力は、 たとえば以下のようになります。

string(22) "/var/www/html/test.php"


select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う

  • ≪ stream_resolve_include_path
  • stream_set_blocking ≫
  • PHP Manual
  • ストリーム 関数
  • select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う

stream_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_select — select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う

説明

stream_select(
?array &$read,
?array &$write,
?array &$except,
?int $seconds,
?int $microseconds = null
): int|false

stream_select() はストリームの配列を受け取ると、 それらの状態が変化するまで待ちます。機能としては、ストリームに対して 働くという点以外では socket_select() と同一です。

パラメータ

read

read 配列に列挙されたストリームに対しては、 何らかのデータがそのストリーム内で読み出せる状態にあるかどうか 監視が行われます (より正確にいえば、ブロックしないで読み出せる状態かどうか - 特にストリームが EOF に達したかどうか、です。このとき、 fread() は長さ 0 の文字列を返します)。

write

write 配列に列挙されたストリームに対しては、 ブロックしないで書き込みができるかどうかの監視が行われます。

except

except 配列に列挙されたストリームに対しては、 重大な例外（"帯域外の"）データが発生したかどうかの監視が行われます。

注意:

stream_select() の終了時には、 どのストリームの状態が実際に変化したのかが分かるよう、 配列 read、write および except に変更が加えられます。 但し、配列のキーは保存されます。

seconds

seconds と microseconds は、一体となって、timeout パラメータを表現します。 seconds は秒数を指定し、一方 microseconds はマイクロ秒数を指定します。 timeout は、stream_select() の実行から戻るまでの時間の上限です。 seconds および microseconds の両方に 0 を指定すると stream_select() はデータを待たずに一瞬で戻ります。 これは現在のストリームの状態を示します。

seconds が null (タイムアウトなし) の場合、 stream_select() はブロックしつづけ、調べている ストリームのひとつでイベントが発生する（あるいはシグナルがシステム コールを中断する）まで終了しません。

警告

タイムアウト値に 0 を指定すると、ストリームの 状態を即時に取得することが可能です。しかし、ループ内でタイムアウト 0 を指定するのは良い考えではありません。 そうすると大量の CPU 時間を消費してしまいます。

タイムアウト値を数秒にするとかなりましになります。しかし、どうしても 他のコードを同時に実行させながらチェックをする必要がある場合には、 少なくとも 200000 マイクロ秒以上のタイムアウトを 設定するようにしましょう。これであなたのスクリプトの CPU 使用量を 抑えることができます。

タイムアウト値は、あくまでも経過時間の最大値であることを覚えておきましょう。 stream_select() は、指定したストリームが使用可能に なるとすぐに結果を返します。

microseconds

seconds の説明を参照ください。

戻り値

成功した場合 stream_select() は、変更された 配列に何個のストリームリソースが格納されたかを示す数を返します。 もしタイムアウトの時間内に何も規定された事象が起こらなかった場合は 0 になることもあります。エラーの際は false を返し、警告を発生させます （システムコールが別のシグナルによって中断された場合などに起こりえます）。

変更履歴

バージョン | 説明
8.1.0 | microseconds は、nullable になりました。

例

例1 stream_select() の例

この例では、$stream1 あるいは $stream2 のどちらかに読み込めるデータが 到達したかどうかを調べます。 タイムアウトが 0 なので、すぐに結果を返します。

<?php
/* read 配列を用意 */
$read = array($stream1, $stream2);
$write = NULL;
$except = NULL;
if (false === ($num_changed_streams = stream_select($read, $write, $except, 0))) {
/* エラー処理 */
} elseif ($num_changed_streams > 0) {
/* 少なくとも 1 つのストリームに何らかの事象が起こりました。*/
}
?>

注意

注意:

現在の Zend Engine の実装上の制約により、null のような定数を この関数の参照渡しが行われるパラメータに直接指定することはできません。 代わりに一時的な変数を指定するか、一番左の変数が一時的な変数になるような 式を指定してください:

<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>

注意:

エラーかどうかをチェックするには === を使ってください。 stream_select() は 0 を返すことがあるため、その場合 false と == 演算子で比較すると true と評価されてしまうからです:

<?php
$e = NULL;
if (false === stream_select($r, $w, $e, 0)) {
echo "stream_select() に失敗しました\n";
}
?>

注意:

配列に返されたストリームに対して読み込みまたは書き込み操作を行う際に、 必ずしもあなたの希望しただけデータが読まれたり書かれたりはしないことに 注意してください。たった 1 バイトしか読み出せない場合も、書き込めない 場合もあるのです。

注意:

ストリームの中には、(zlib などのように) この関数で select できないものもあります。

注意: Windows の互換性

Windows では、proc_open() が返すファイル記述子に 対して stream_select() を使用すると 失敗して false を返すことがあります。

あらゆる 入力イベントが利用可能になるとすぐに、 コンソールからの STDIN の状態も変化しますが、 ストリームからの読み出しはブロックされたままかもしれません。

参考

  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する


ストリームのブロックモードを有効にする / 解除する

  • ≪ stream_select
  • stream_set_chunk_size ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームのブロックモードを有効にする / 解除する

stream_set_blocking

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_set_blocking — ストリームのブロックモードを有効にする / 解除する

説明

stream_set_blocking(resource $stream, bool $enable): bool

stream のモードをブロックあるいは非ブロックに設定します。

この関数は、非ブロックモードをサポートするすべてのストリーム (現在は、通常のファイルストリームとソケットストリームのみ) において利用可能です。

パラメータ

stream

ストリーム。

enable

enable が false の時、ストリームは 非ブロックモードに切り替えられ、true の場合は、 ブロックモードに切り替えられます。このモードの違いは、 fgets() や fread() といった、ストリームからデータを読む関数に影響します。 非ブロックモードにおいては fgets() を呼び出すと どんな場合でもただちに呼び出し元に戻りますが、ブロックモードの場合では、 ストリームがデータを読み出せる状態になるまで待ちつづけます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意:

Windowsでは、これはローカルファイルには影響しません。 ローカルファイルのノンブロッキングI/Oは、Windowsではサポートされていません。

参考

  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う


ストリームのチャンクサイズを設定する

  • ≪ stream_set_blocking
  • stream_set_read_buffer ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームのチャンクサイズを設定する

stream_set_chunk_size

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

stream_set_chunk_size — ストリームのチャンクサイズを設定する

説明

stream_set_chunk_size(resource $stream, int $size): int

ストリームのチャンクサイズを設定します。

パラメータ

stream

対象のストリーム。

size

設定したいチャンクサイズ。

戻り値

成功した場合に、変更前の設定値を返します。

エラー / 例外

size が 1 より小さいか、あるいは PHP_INT_MAX より大きい場合には ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | size が 1 より小さいか、あるいは PHP_INT_MAX より大きい場合には ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、false を返していました。


指定したストリームのファイル読み込みバッファリングを有効にする

  • ≪ stream_set_chunk_size
  • stream_set_timeout ≫
  • PHP Manual
  • ストリーム 関数
  • 指定したストリームのファイル読み込みバッファリングを有効にする

stream_set_read_buffer

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

stream_set_read_buffer — 指定したストリームのファイル読み込みバッファリングを有効にする

説明

stream_set_read_buffer(resource $stream, int $size): int

読み込みバッファを設定します。stream_set_write_buffer() と似ていますが、読み込み操作を対象としています。

パラメータ

stream

ファイルポインタ。

size

バッファのバイト数。 size が 0 であれば、読み込み操作はバッファされなくなります。 これにより、fread() による読み込み操作が完了するまでは 他のプロセスが同じ入力ストリームから読み込み操作をできないことが保証されます。

戻り値

成功時に 0 を、要求通りに設定できなかった場合はそれ以外の値を返します。

参考

  • stream_set_write_buffer() - 指定されたストリームのファイル書き込みバッファリングを有効にする


ストリームにタイムアウトを設定する

  • ≪ stream_set_read_buffer
  • stream_set_write_buffer ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームにタイムアウトを設定する

stream_set_timeout

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_set_timeout — ストリームにタイムアウトを設定する

説明

stream_set_timeout(resource $stream, int $seconds, int $microseconds = 0): bool

stream にタイムアウトの値を設定します。 この値は、seconds と microseconds の和で表されます。

ストリームがタイムアウトとなった場合は、 stream_get_meta_data() が返す配列のキー 'timed_out' の値が true に設定されます。エラーや警告が発生していなくても同様になります。

パラメータ

stream

対象となるストリーム。

seconds

設定したいタイムアウトの秒数部分。

microseconds

設定したいタイムアウトのマイクロ秒数部分。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_set_timeout() の例

<?php
$fp = fsockopen("www.example.com", 80);
if (!$fp) {
echo "開けません\n";
} else {

fwrite($fp, "GET / HTTP/1.0\r\n\r\n");
stream_set_timeout($fp, 2);
$res = fread($fp, 2000);

$info = stream_get_meta_data($fp);
fclose($fp);

if ($info['timed_out']) {
echo 'Connection timed out!';
} else {
echo $res;
}

}
?>

注意

注意:

この関数では、stream_socket_recvfrom() のような 高度な操作はできません。そのかわりに、timeout パラメータを指定して stream_select() を使用してください。

この関数は、以前は set_socket_timeout() 、その後は socket_set_timeout() と呼ばれたこともありましたが、 これらの利用は推奨されません。

参考

  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • fopen() - ファイルまたは URL をオープンする


指定されたストリームのファイル書き込みバッファリングを有効にする

  • ≪ stream_set_timeout
  • stream_socket_accept ≫
  • PHP Manual
  • ストリーム 関数
  • 指定されたストリームのファイル書き込みバッファリングを有効にする

stream_set_write_buffer

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

stream_set_write_buffer — 指定されたストリームのファイル書き込みバッファリングを有効にする

説明

stream_set_write_buffer(resource $stream, int $size): int

stream で指定されたファイルポインタに size で表されたバイト数分だけ出力バッファを設定します。

パラメータ

stream

ファイルポインタ。

size

バッファのバイト数。 size が 0 であれば、書き込み操作はバッファされなくなります。 これにより、fwrite() による書き込み操作が、他の プロセスが同じ出力ストリームに対して何らかの書き込み操作を行う前に 完了することが保証されます。

戻り値

成功時に 0 を、要求通りに設定できなかった場合はそれ以外の値を返します。

例

例1 stream_set_write_buffer() の例

次の例は、バッファされていないストリームを stream_set_write_buffer() によって作成する方法を示したものです。

<?php
$fp = fopen($file, "w");
if ($fp) {
if (stream_set_write_buffer($fp, 0) !== 0) {
// バッファリングの変更に失敗しました
}
fwrite($fp, $output);
fclose($fp);
}
?>

参考

  • fopen() - ファイルまたは URL をオープンする
  • fwrite() - バイナリセーフなファイル書き込み処理


stream_socket_server で作られたソケットの接続を受け入れる

  • ≪ stream_set_write_buffer
  • stream_socket_client ≫
  • PHP Manual
  • ストリーム 関数
  • stream_socket_server で作られたソケットの接続を受け入れる

stream_socket_accept

(PHP 5, PHP 7, PHP 8)

stream_socket_accept — stream_socket_server() で作られたソケットの接続を受け入れる

説明

stream_socket_accept(resource $socket, ?float $timeout = null, string &$peer_name = null): resource|false

以前に stream_socket_server() によって作られたソケットの接続を受け入れます。

パラメータ

socket

接続元からの接続を受け付けるサーバーソケット。

timeout

デフォルトのソケット接続待ちタイムアウトを上書きします。 時間は秒単位で指定します。 デフォルトでは、 default_socket_timeout の値が使われます。

peer_name

接続元のクライアントの名前 (アドレス) が含まれていて、 選択したトランスポートで有効であった場合に、それを設定します。

注意:

後で stream_socket_get_name() を使用して指定することもできます。

戻り値

受け付けたソケット接続へのストリームを返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | timeout は、nullable になりました。

注意

警告

この関数は UDP サーバーソケットとともに使用すべきではありません。 代わりに stream_socket_recvfrom() および stream_socket_sendto() を使用します。

参考

  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
  • stream_socket_get_name() - ローカルまたはリモートのソケットの名前を取得する
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • cURL 関数


インターネットドメインまたは Unix ドメインのソケット接続を開く

  • ≪ stream_socket_accept
  • stream_socket_enable_crypto ≫
  • PHP Manual
  • ストリーム 関数
  • インターネットドメインまたは Unix ドメインのソケット接続を開く

stream_socket_client

(PHP 5, PHP 7, PHP 8)

stream_socket_client — インターネットドメインまたは Unix ドメインのソケット接続を開く

説明

stream_socket_client(
string $address,
int &$error_code = null,
string &$error_message = null,
?float $timeout = null,
int $flags = STREAM_CLIENT_CONNECT,
?resource $context = null
): resource|false

address で指定された接続先との、 ストリームまたはデータグラム接続を確立します。 作成されるソケットのタイプは、[トランスポート]://[ターゲット] という形式の URL フォーマットによって指定された トランスポートによって決定されます。 TCP や UDP といったインターネットドメインのソケット (AF_INET) には、address パラメータの ターゲット の部分は、ホスト名または IP アドレスと、 それに続くコロンで区切られたポート番号から構成されていなければなりません。 Unix ドメインのソケットの場合は、ターゲット の部分は、ファイルシステムにおけるソケットのファイルを指定しなくては いけません。

注意:

ストリームはデフォルトではブロックモードで開かれますが、 stream_set_blocking() を使うことで非ブロックモードに 変更することができます。

パラメータ

address

接続するソケットのアドレス。

error_code

接続に失敗した場合にシステムレベルのエラー番号が設定されます。

error_message

接続に失敗した場合にシステムレベルのエラーメッセージが設定されます。

timeout

connect() システムコールがタイムアウトとなるまでの秒数。 デフォルトでは、 default_socket_timeout の値を使います。

注意: このパラメータが適用されるのは、非同期通信を試みていない場合のみです。

注意:

ソケット上のデータの読み書きに関してタイムアウトを設定する必要がある場合は、 stream_set_timeout() を使ってください。 stream_socket_client() に渡される timeout は、ソケットの接続時にのみ適用されます。

flags

接続設定フラグの任意の組み合わせを指定できるビットフィールドです。 現在、接続設定フラグとして選択できる値は、 STREAM_CLIENT_CONNECT（デフォルト）、 STREAM_CLIENT_ASYNC_CONNECT と STREAM_CLIENT_PERSISTENT のみです。

context

stream_context_create() で作成した有効なコンテキストリソース。

戻り値

成功した場合に、
fgets(), fgetss(),
fwrite(), fclose(),
feof() といった、ファイル関数と共に使うことのできるストリームリソースを返します。

エラー / 例外

失敗した場合は、error_code と error_message に システムレベルの connect() 関数の実行時に発生したシステムレベルのエラーを表す値を返します。 もし、error_code に返された値が 0 で、かつ、 この関数が false を返した時は、 connect() システムコールの前に何らかのエラーが 発生したことを示しています。これは、多くの場合、ソケットの初期化 に失敗したことで起こります。error_code と error_message パラメータは常に参照渡しされることに 留意してください。

変更履歴

バージョン | 説明
8.0.0 | timeout と context は、nullable になりました。

例

例1 stream_socket_client() の例

<?php
$fp = stream_socket_client("tcp://www.example.com:80", $errno, $errstr, 30);
if (!$fp) {
echo "$errstr ($errno)<br />\n";
} else {
fwrite($fp, "GET / HTTP/1.0\r\nHost: www.example.com\r\nAccept: */*\r\n\r\n");
while (!feof($fp)) {
echo fgets($fp, 1024);
}
fclose($fp);
}
?>

例2 UDP 接続の使用

ローカルホスト上で動いている UDP サービスの "daytime" (ポート 13) で日時の情報を取得します。

<?php
$fp = stream_socket_client("udp://127.0.0.1:13", $errno, $errstr);
if (!$fp) {
echo "ERROR: $errno - $errstr<br />\n";
} else {
fwrite($fp, "\n");
echo fread($fp, 26);
fclose($fp);
}
?>

注意

警告

UDP ソケットは、リモートホストに到達できなくても エラーを発生せず、開いているかような状態になることがありす。 このエラーは、実際にソケットに対して、読み込みや書き込み動作を 行ってみないと判断できません。原因としては、UDP が非接続型の プロトコルであることが挙げられます。つまり、実際にデータを 送受信する段階になるまで、OS の側では接続を確立しようとしないという ことです。

注意: 数値で IPv6 アドレスを指定するときは、 (例 fe80::1) アドレスを角カッコでくくらなくてはなりません。たとえば、 tcp://[fe80::1]:80.

注意:

環境により、Unix ドメインや接続タイムアウトが利用できない場合があります。 有効なトランスポートのリストは、stream_get_transports() で取得できます。組み込むのポートの一覧については、 サポートされるソケットトランスポートのリスト を参照ください。

参考

  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • cURL 関数


接続済みのソケットについて暗号化の on/off を切り替える

  • ≪ stream_socket_client
  • stream_socket_get_name ≫
  • PHP Manual
  • ストリーム 関数
  • 接続済みのソケットについて暗号化の on/off を切り替える

stream_socket_enable_crypto

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_socket_enable_crypto — 接続済みのソケットについて暗号化の on/off を切り替える

説明

stream_socket_enable_crypto(
resource $stream,
bool $enable,
?int $crypto_method = null,
?resource $session_stream = null
): int|bool

ストリームの暗号化を有効あるいは無効にします。

暗号化設定が確立されると、それ以降は enable パラメータに true あるいは false を指定することで暗号化の on/off を動的に切り替えられます。

パラメータ

stream

ストリームリソース。

enable

ストリームの暗号化を有効にするか無効にするか。

crypto_method

ストリームの暗号化の設定。以下の方法が使用できます。

  • STREAM_CRYPTO_METHOD_SSLv2_CLIENT
  • STREAM_CRYPTO_METHOD_SSLv3_CLIENT
  • STREAM_CRYPTO_METHOD_SSLv23_CLIENT
  • STREAM_CRYPTO_METHOD_ANY_CLIENT
  • STREAM_CRYPTO_METHOD_TLS_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT (PHP 7.4.0 以降)
  • STREAM_CRYPTO_METHOD_SSLv2_SERVER
  • STREAM_CRYPTO_METHOD_SSLv3_SERVER
  • STREAM_CRYPTO_METHOD_SSLv23_SERVER
  • STREAM_CRYPTO_METHOD_ANY_SERVER
  • STREAM_CRYPTO_METHOD_TLS_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_0_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_1_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_2_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_3_SERVER (PHP 7.4.0 以降)

省略した場合は、ストリームの SSL コンテキストのオプション crypto_method を利用します。

session_stream

ストリームで session_stream からの設定を送信します。

戻り値

成功した場合に true、ネゴシエーションに失敗した場合に false、 十分なデータがないために再試行が必要な場合（非ブロックモード時のみ） に 0 を返します。

変更履歴

バージョン | 説明
8.0.0 | session_stream は、nullable になりました。

例

例1 stream_socket_enable_crypto() の例

<?php
$fp = stream_socket_client("tcp://myproto.example.com:31337", $errno, $errstr, 30);
if (!$fp) {
die("接続できません: $errstr ($errno)");
}

/* ログイン時の暗号化を有効にします */
stream_socket_enable_crypto($fp, true, STREAM_CRYPTO_METHOD_SSLv23_CLIENT);
fwrite($fp, "USER god\r\n");
fwrite($fp, "PASS secret\r\n");

/* それ以外では暗号化を無効にします */
stream_socket_enable_crypto($fp, false);

while ($motd = fgets($fp)) {
echo $motd;
}

fclose($fp);
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • OpenSSL 関数
    •

  • サポートされるソケットトランスポートのリスト
    •


ローカルまたはリモートのソケットの名前を取得する

  • ≪ stream_socket_enable_crypto
  • stream_socket_pair ≫
  • PHP Manual
  • ストリーム 関数
  • ローカルまたはリモートのソケットの名前を取得する

stream_socket_get_name

(PHP 5, PHP 7, PHP 8)

stream_socket_get_name — ローカルまたはリモートのソケットの名前を取得する

説明

stream_socket_get_name(resource $socket, bool $remote): string|false

指定したソケット接続のローカルまたはリモートでの名前を返します。

パラメータ

socket

名前を取得したいソケット。

remote

true に設定するとリモートでのソケットの名前を返し、 false に設定するとローカルでのソケットの名前を返します。

戻り値

ソケットの名前を返します。 失敗した場合に false を返します

参考

  • stream_socket_accept() - stream_socket_server で作られたソケットの接続を受け入れる


接続された、区別できないソケットストリームの組を作成する

  • ≪ stream_socket_get_name
  • stream_socket_recvfrom ≫
  • PHP Manual
  • ストリーム 関数
  • 接続された、区別できないソケットストリームの組を作成する

stream_socket_pair

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_socket_pair — 接続された、区別できないソケットストリームの組を作成する

説明

stream_socket_pair(int $domain, int $type, int $protocol): array|false

stream_socket_pair() は、互いに接続されており区別できない ソケットストリームの組を作成します。この関数は、一般に IPC （Inter-Process Communication: プロセス間通信）で使用します。

パラメータ

domain

使用するプロトコルファミリー。STREAM_PF_INET、 STREAM_PF_INET6 あるいは STREAM_PF_UNIX

type

使用する接続の型。 STREAM_SOCK_DGRAM、 STREAM_SOCK_RAW、 STREAM_SOCK_RDM、 STREAM_SOCK_SEQPACKET あるいは STREAM_SOCK_STREAM

protocol

使用するプロトコル。STREAM_IPPROTO_ICMP、 STREAM_IPPROTO_IP、 STREAM_IPPROTO_RAW、 STREAM_IPPROTO_TCP あるいは STREAM_IPPROTO_UDP

注意: 各定数についての詳細な情報は ストリーム定数の一覧 を参照ください。

戻り値

成功した場合に 2 つのソケットリソースの配列、失敗した場合に false を返します。

例

例1 stream_socket_pair() の例

この例では、プロセス間通信に stream_socket_pair() を使用する基本的な方法を示します。

<?php

$sockets = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
$pid = pcntl_fork();

if ($pid == -1) {
die('フォークできません');

} else if ($pid) {
/* 親プロセス */
fclose($sockets[0]);

fwrite($sockets[1], "子プロセスの PID: $pid\n");
echo fgets($sockets[1]);

fclose($sockets[1]);

} else {
/* 子プロセス */
fclose($sockets[1]);

fwrite($sockets[0], "子プロセスからのメッセージ\n");
echo fgets($sockets[0]);

fclose($sockets[0]);
}

?>

上の例の出力は、 たとえば以下のようになります。

子プロセスの PID: 1378
子プロセスからのメッセージ


接続されているかどうかにかかわらず、ソケットからのデータを受信する

  • ≪ stream_socket_pair
  • stream_socket_sendto ≫
  • PHP Manual
  • ストリーム 関数
  • 接続されているかどうかにかかわらず、ソケットからのデータを受信する

stream_socket_recvfrom

(PHP 5, PHP 7, PHP 8)

stream_socket_recvfrom — 接続されているかどうかにかかわらず、ソケットからのデータを受信する

説明

stream_socket_recvfrom(
resource $socket,
int $length,
int $flags = 0,
?string &$address = null
): string|false

stream_socket_recvfrom() は、 リモートソケットから最大 length バイトのデータを 受け取ります。

パラメータ

socket

リモートソケット。

length

socket から受信するバイト数。

flags

flags は以下の値の組み合わせです。

flags でとりうる値
STREAM_OOB | OOB (out-of-band) データを処理します。
STREAM_PEEK | ソケットからデータを取得しますが、バッファを消費しません。 fread() あるいは stream_socket_recvfrom() を続けてコールした 際には、同じデータが読み込まれます。

address

address が指定された場合、 そこにはリモートソケットのアドレスが保存されます。

戻り値

読み込んだデータを文字列で返します。 失敗した場合に false を返します

例

例1 stream_socket_recvfrom() の例

<?php
/* localhost のポート 1234 へのサーバーソケットをオープンします */
$server = stream_socket_server('tcp://127.0.0.1:1234');

/* 接続を受け付けます */
$socket = stream_socket_accept($server);

/* OOB データのパケットを取得します（1500 は典型的な MTU のサイズです） */
echo "Received Out-Of-Band: '" . stream_socket_recvfrom($socket, 1500, STREAM_OOB) . "'\n";

/* 通常の帯域内のデータを読み込みますが、バッファを消費しません */
echo "Data: '" . stream_socket_recvfrom($socket, 1500, STREAM_PEEK) . "'\n";

/* 同じパケットをもう一度読み込みます。今度はバッファからそれを削除します */
echo "Data: '" . stream_socket_recvfrom($socket, 1500) . "'\n";

/* ソケットを閉じます */
fclose($socket);
fclose($server);
?>

注意

注意:

受信したメッセージが length パラメータより 長かった場合、ソケットの型によっては（例えば UDP など）超過分の バイトデータが捨てられてしまう可能性があります。

注意:

バッファベースのストリーム関数 (fread() あるいは
stream_get_line() など) をコールした後に
ソケットベースのストリームで stream_socket_recvfrom()
をコールすると、ストリームバッファを経由せず、データをソケットから
直接読み込みます。

参考

  • stream_socket_sendto() - 接続されているかどうかにかかわらず、ソケットにデータを送信する
  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する


接続されているかどうかにかかわらず、ソケットにデータを送信する

  • ≪ stream_socket_recvfrom
  • stream_socket_server ≫
  • PHP Manual
  • ストリーム 関数
  • 接続されているかどうかにかかわらず、ソケットにデータを送信する

stream_socket_sendto

(PHP 5, PHP 7, PHP 8)

stream_socket_sendto — 接続されているかどうかにかかわらず、ソケットにデータを送信する

説明

stream_socket_sendto(
resource $socket,
string $data,
int $flags = 0,
string $address = ""
): int|false

data で指定したデータを socket で指定したソケットに送信します。

パラメータ

socket

data を送信するソケット。

data

送りたいデータ。

flags

flags は以下の値の組み合わせです。

flags でとりうる値
STREAM_OOB OOB (out-of-band) データを処理します。

address

address で別のアドレスが指定されていない限り、 ソケットストリームが作成された際のアドレスを使用します。

指定する場合は、ドットで 4 つに区切った形式 (あるいは IPv6 形式) でなければなりません。

戻り値

結果コードを整数値で返します。 失敗した場合に false を返します

例

例1 stream_socket_sendto() の例

<?php
/* localhost のポート 1234 へのソケットをオープンします */
$socket = stream_socket_client('tcp://127.0.0.1:1234');

/* 普通のデータを普通のチャネルで送信します */
fwrite($socket, "Normal data transmit.");

/* 帯域外のデータを送信します */
stream_socket_sendto($socket, "Out of Band data.", STREAM_OOB);

/* ソケットを閉じます */
fclose($socket);
?>

参考

  • stream_socket_recvfrom() - 接続されているかどうかにかかわらず、ソケットからのデータを受信する
  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する


インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

  • ≪ stream_socket_sendto
  • stream_socket_shutdown ≫
  • PHP Manual
  • ストリーム 関数
  • インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

stream_socket_server

(PHP 5, PHP 7, PHP 8)

stream_socket_server — インターネットドメインまたは Unix ドメインのサーバーソケットを作成する

説明

stream_socket_server(
string $address,
int &$error_code = null,
string &$error_message = null,
int $flags = STREAM_SERVER_BIND | STREAM_SERVER_LISTEN,
?resource $context = null
): resource|false

address で指定された接続ポイントに、 ストリームまたはデータグラムソケットによる接続を作成します。

この関数は、ソケットのみを作成します。接続待ちの状態に入るには、 stream_socket_accept() 関数を使います。

パラメータ

address

作成されるソケットのタイプは、[トランスポート]://[ターゲット] という形式の URL フォーマットによって指定された トランスポートによって決定されます:

TCP や UDP といったインターネットドメインのソケット (AF_INET) には、remote_socket パラメータの ターゲット の部分は、ホスト名または IP アドレスと、 それに続くコロンで区切られたポート番号から構成されていなければなりません。 Unix ドメインのソケットの場合は、ターゲット の部分は、ファイルシステムにおけるソケットのファイルを指定しなくては いけません。

システムの種類によって、Unix ドメインのソケットが利用できない場合があります。 利用できるトランスポートの種類は、stream_get_transports() によって知ることができます。 組み込みのトランスポートのリストは、サポートされるソケットトランスポートのリスト を参照ください。

error_code

オプションの error_code と error_message パラメータが存在するときは、そこにシステムレベルの socket()、bind() および listen() のコールにおいて発生した 実際のシステムレベルのエラーを返します。 もし、error_code に返された値が 0 で、かつ false が返された場合、bind() コールを行う前にエラーが発生したことを示しており、これは多くの場合 ソケットの初期化に失敗したことを示しています。 error_code と error_message パラメータは常に参照渡しとなることに留意してください。

error_message

error_code の説明を参照ください。

flags

ソケット作成フラグの任意の組み合わせを指定できるビットフィールドです。

注意:

UDP ソケットに対しては、STREAM_SERVER_BIND を flags パラメータとして使用する必要があります。

context

戻り値

作成したストリーム、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | context は、nullable になりました。

例

例1 TCP サーバーソケットの使用

<?php
$socket = stream_socket_server("tcp://0.0.0.0:8000", $errno, $errstr);
if (!$socket) {
echo "$errstr ($errno)<br />\n";
} else {
while ($conn = stream_socket_accept($socket)) {
fwrite($conn, 'The local time is ' . date('n/j/Y g:i a') . "\n");
fclose($conn);
}
fclose($socket);
}
?>

下記の例は、PHP のスクリプトが、どうやって stream_socket_client() で示したような、 問い合わせに応答するタイムサーバーとして機能するかを示したものです。

注意: 1024 番よりも小さいポート番号のサーバーソケットを作成する場合、 多くのシステムでは root 権限が必要となります。

例2 UDP サーバーソケットを利用する

<?php
$socket = stream_socket_server("udp://127.0.0.1:1113", $errno, $errstr, STREAM_SERVER_BIND);
if (!$socket) {
die("$errstr ($errno)");
}

do {
$pkt = stream_socket_recvfrom($socket, 1, 0, $peer);
echo "$peer\n";
stream_socket_sendto($socket, date("D M j H:i:s Y\r\n"), 0, $peer);
} while ($pkt !== false);

?>

注意

注意: 数値で IPv6 アドレスを指定するときは、 (例 fe80::1) アドレスを角カッコでくくらなくてはなりません。たとえば、 tcp://[fe80::1]:80.

参考

  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • Curl 拡張モジュール


全二重接続を終了する

  • ≪ stream_socket_server
  • stream_supports_lock ≫
  • PHP Manual
  • ストリーム 関数
  • 全二重接続を終了する

stream_socket_shutdown

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

stream_socket_shutdown — 全二重接続を終了する

説明

stream_socket_shutdown(resource $stream, int $mode): bool

全二重接続を (一時的あるいはそうでなく) 終了します。

注意:

関連するバッファの内容は、空になるかもしれないしならないかもしれません。

パラメータ

stream

オープンしているストリーム (たとえば stream_socket_client() でオープンしたものなど)。

mode

以下の定数のいずれか。STREAM_SHUT_RD (それ以降の受信を無効にする)、STREAM_SHUT_WR (それ以降の送信を無効にする) あるいは STREAM_SHUT_RDWR (それ以降の送受信を無効にする)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 stream_socket_shutdown() の例

<?php

$server = stream_socket_server('tcp://127.0.0.1:1337');
$client = stream_socket_client('tcp://127.0.0.1:1337');

var_dump(fputs($client, "hello"));

stream_socket_shutdown($client, STREAM_SHUT_WR);
var_dump(fputs($client, "hello")); // ここでは動作しません

?>

上の例の出力は、 たとえば以下のようになります。

int(5)

Notice: fputs(): send of 5 bytes failed with errno=32 Broken pipe in test.php on line 9
int(0)

参考

  • fclose() - オープンされたファイルポインタをクローズする


ストリームがロックをサポートしているかどうかを調べる

  • ≪ stream_socket_shutdown
  • stream_wrapper_register ≫
  • PHP Manual
  • ストリーム 関数
  • ストリームがロックをサポートしているかどうかを調べる

stream_supports_lock

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

stream_supports_lock — ストリームがロックをサポートしているかどうかを調べる

説明

stream_supports_lock(resource $stream): bool

flock() によるロックをそのストリームがサポートしているかどうかを調べます。

パラメータ

stream

調べたいストリーム。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • flock() - 汎用のファイルロックを行う


PHP のクラスとして実装された URL ラッパーを登録する

  • ≪ stream_supports_lock
  • stream_wrapper_restore ≫
  • PHP Manual
  • ストリーム 関数
  • PHP のクラスとして実装された URL ラッパーを登録する

stream_wrapper_register

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

stream_wrapper_register — PHP のクラスとして実装された URL ラッパーを登録する

説明

stream_wrapper_register(string $protocol, string $class, int $flags = 0): bool

自分で作ったプロトコルハンドラとストリームを実装し、それを fopen() や fread() といったファイルシステムの関数と利用することを可能にします。

パラメータ

protocol

登録したいラッパー名。 有効なプロトコル名には、 アルファベットと数値、ドット(.)、 プラス文字(+)、 ハイフン(-) のみが含まれています。

class

protocol を実装したクラス名。

flags

protocol が URL プロトコルである場合は STREAM_IS_URL を設定しなければなりません。 デフォルトは 0 で、ローカルストリームを意味します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

stream_wrapper_register() は、 protocol というハンドラが既にある場合、 false を返します。

例

例1 ストリームラッパーの登録方法

<?php
$existed = in_array("var", stream_get_wrappers());
if ($existed) {
stream_wrapper_unregister("var");
}
stream_wrapper_register("var", "VariableStream");
$myvar = "";

$fp = fopen("var://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
echo fgets($fp);
}
fclose($fp);
var_dump($myvar);

if ($existed) {
stream_wrapper_restore("var");
}

?>

上の例の出力は以下となります。

line1
line2
line3
string(18) "line1
line2
line3
"

参考

  • streamWrapper プロトタイプクラス
  • ストリームラッパーとして登録するクラスの例
  • stream_wrapper_unregister() - URL ラッパーの登録を解除する
  • stream_wrapper_restore() - 事前に登録を解除された組み込みラッパーを復元する
  • stream_get_wrappers() - 登録されているストリームのラッパーのリストを取得する


事前に登録を解除された組み込みラッパーを復元する

  • ≪ stream_wrapper_register
  • stream_wrapper_unregister ≫
  • PHP Manual
  • ストリーム 関数
  • 事前に登録を解除された組み込みラッパーを復元する

stream_wrapper_restore

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_wrapper_restore — 事前に登録を解除された組み込みラッパーを復元する

説明

stream_wrapper_restore(string $protocol): bool

stream_wrapper_unregister() で事前に登録を解除した 組み込みラッパーを復元します。

パラメータ

protocol

戻り値

成功した場合に true を、失敗した場合に false を返します。


URL ラッパーの登録を解除する

  • ≪ stream_wrapper_restore
  • Swoole ≫
  • PHP Manual
  • ストリーム 関数
  • URL ラッパーの登録を解除する

stream_wrapper_unregister

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

stream_wrapper_unregister — URL ラッパーの登録を解除する

説明

stream_wrapper_unregister(string $protocol): bool

すでに定義されているストリームラッパーを無効にします。ラッパーが無効になった後は、 stream_wrapper_register() を使用してユーザー定義の ラッパーで上書きしたり stream_wrapper_restore() で再度使用可能にしたりすることが可能となります。

パラメータ

protocol

戻り値

成功した場合に true を、失敗した場合に false を返します。


Swoole

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • Swoole 関数
    • swoole_async_dns_lookup — Async and non-blocking hostname to IP lookup
    • swoole_async_read — Read file stream asynchronously
    • swoole_async_readfile — Read a file asynchronously
    • swoole_async_set — Update the async I/O options
    • swoole_async_write — Write data to a file stream asynchronously
    • swoole_async_writefile — Write data to a file asynchronously
    • swoole_clear_error — Clear errors in the socket or on the last error code
    • swoole_client_select — Get the file description which are ready to read/write or error
    • swoole_cpu_num — Get the number of CPU
    • swoole_errno — Get the error code of the latest system call
    • swoole_error_log — Output error messages to the log
    • swoole_event_add — Add new callback functions of a socket into the EventLoop
    • swoole_event_defer — Add callback function to the next event loop
    • swoole_event_del — Remove all event callback functions of a socket
    • swoole_event_exit — Exit the eventloop, only available at the client side
    • swoole_event_set — Update the event callback functions of a socket
    • swoole_event_wait — Start the event loop
    • swoole_event_write — Write data to a socket
    • swoole_get_local_ip — Get the IPv4 IP addresses of each NIC on the machine
    • swoole_last_error — Get the lastest error message
    • swoole_load_module — Load a swoole extension
    • swoole_select — Select the file descriptions which are ready to read/write or error in the eventloop
    • swoole_set_process_name — Set the process name
    • swoole_strerror — Convert the Errno into error messages
    • swoole_timer_after — Trigger a one time callback function in the future
    • swoole_timer_exists — Check if a timer callback function is existed
    • swoole_timer_tick — Trigger a timer tick callback function by time interval
    • swoole_version — Get the version of Swoole
  • Swoole\Async — The Swoole\Async class
    • Swoole\Async::dnsLookup — Async and non-blocking hostname to IP lookup.
    • Swoole\Async::read — Read file stream asynchronously.
    • Swoole\Async::readFile — Read a file asynchronously.
    • Swoole\Async::set — Update the async I/O options.
    • Swoole\Async::write — Write data to a file stream asynchronously.
    • Swoole\Async::writeFile — Description
  • Swoole\Atomic — The Swoole\Atomic class
    • Swoole\Atomic::add — Add a number to the value to the atomic object.
    • Swoole\Atomic::cmpset — Compare and set the value of the atomic object.
    • Swoole\Atomic::__construct — Construct a swoole atomic object.
    • Swoole\Atomic::get — Get the current value of the atomic object.
    • Swoole\Atomic::set — Set a new value to the atomic object.
    • Swoole\Atomic::sub — Subtract a number to the value of the atomic object.
  • Swoole\Buffer — The Swoole\Buffer class
    • Swoole\Buffer::append — Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.
    • Swoole\Buffer::clear — Reset the memory buffer.
    • Swoole\Buffer::__construct — Fixed size memory blocks allocation.
    • Swoole\Buffer::__destruct — Destruct the Swoole memory buffer.
    • Swoole\Buffer::expand — Expand the size of memory buffer.
    • Swoole\Buffer::read — Read data from the memory buffer based on offset and length.
    • Swoole\Buffer::recycle — Release the memory to OS which is not used by the memory buffer.
    • Swoole\Buffer::substr — Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.
    • Swoole\Buffer::__toString — Get the string value of the memory buffer.
    • Swoole\Buffer::write — Write data to the memory buffer. The memory allocated for the buffer will not be changed.
  • Swoole\Channel — The Swoole\Channel class
    • Swoole\Channel::__construct — Construct a Swoole Channel
    • Swoole\Channel::__destruct — Destruct a Swoole channel.
    • Swoole\Channel::pop — Read and pop data from swoole channel.
    • Swoole\Channel::push — Write and push data into Swoole channel.
    • Swoole\Channel::stats — Get stats of swoole channel.
  • Swoole\Client — The Swoole\Client class
    • Swoole\Client::close — Close the connection established.
    • Swoole\Client::connect — Connect to the remote TCP or UDP port.
    • Swoole\Client::__construct — Create Swoole sync or async TCP/UDP client, with or without SSL.
    • Swoole\Client::__destruct — Destruct the Swoole client.
    • Swoole\Client::getpeername — Get the remote socket name of the connection.
    • Swoole\Client::getsockname — Get the local socket name of the connection.
    • Swoole\Client::isConnected — Check if the connection is established.
    • Swoole\Client::on — Add callback functions triggered by events.
    • Swoole\Client::pause — Pause receiving data.
    • Swoole\Client::pipe — Redirect the data to another file descriptor.
    • Swoole\Client::recv — Receive data from the remote socket.
    • Swoole\Client::resume — Resume receiving data.
    • Swoole\Client::send — Send data to the remote TCP socket.
    • Swoole\Client::sendfile — Send file to the remote TCP socket.
    • Swoole\Client::sendto — Send data to the remote UDP address.
    • Swoole\Client::set — Set the Swoole client parameters before the connection is established.
    • Swoole\Client::sleep — Remove the TCP client from system event loop.
    • Swoole\Client::wakeup — Add the TCP client back into the system event loop.
  • Swoole\Connection\Iterator — The Swoole\Connection\Iterator class
    • Swoole\Connection\Iterator::count — Count connections.
    • Swoole\Connection\Iterator::current — Return current connection entry.
    • Swoole\Connection\Iterator::key — Return key of the current connection.
    • Swoole\Connection\Iterator::next — Move to the next connection.
    • Swoole\Connection\Iterator::offsetExists — Check if offet exists.
    • Swoole\Connection\Iterator::offsetGet — Offset to retrieve.
    • Swoole\Connection\Iterator::offsetSet — Assign a Connection to the specified offset.
    • Swoole\Connection\Iterator::offsetUnset — Unset an offset.
    • Swoole\Connection\Iterator::rewind — Rewinds iterator
    • Swoole\Connection\Iterator::valid — Check if current position is valid.
  • Swoole\Coroutine — The Swoole\Coroutine class
    • Swoole\Coroutine::call_user_func — Call a callback given by the first parameter
    • Swoole\Coroutine::call_user_func_array — Call a callback with an array of parameters
    • Swoole\Coroutine::cli_wait — Description
    • Swoole\Coroutine::create — Description
    • Swoole\Coroutine\Client::close — Description
    • Swoole\Coroutine\Client::connect — Description
    • Swoole\Coroutine\Client::__construct — Description
    • Swoole\Coroutine\Client::__destruct — Description
    • Swoole\Coroutine\Client::getpeername — Description
    • Swoole\Coroutine\Client::getsockname — Description
    • Swoole\Coroutine\Client::isConnected — Description
    • Swoole\Coroutine\Client::recv — Description
    • Swoole\Coroutine\Client::send — Description
    • Swoole\Coroutine\Client::sendfile — Description
    • Swoole\Coroutine\Client::sendto — Description
    • Swoole\Coroutine\Client::set — Description
    • Swoole\Coroutine\Http\Client::addFile — Description
    • Swoole\Coroutine\Http\Client::close — Description
    • Swoole\Coroutine\Http\Client::__construct — Description
    • Swoole\Coroutine\Http\Client::__destruct — Description
    • Swoole\Coroutine\Http\Client::execute — Description
    • Swoole\Coroutine\Http\Client::get — Description
    • Swoole\Coroutine\Http\Client::getDefer — Description
    • Swoole\Coroutine\Http\Client::isConnected — Description
    • Swoole\Coroutine\Http\Client::post — Description
    • Swoole\Coroutine\Http\Client::recv — Description
    • Swoole\Coroutine\Http\Client::set — Description
    • Swoole\Coroutine\Http\Client::setCookies — Description
    • Swoole\Coroutine\Http\Client::setData — Description
    • Swoole\Coroutine\Http\Client::setDefer — Description
    • Swoole\Coroutine\Http\Client::setHeaders — Description
    • Swoole\Coroutine\Http\Client::setMethod — Description
    • Swoole\Coroutine\MySQL::close — Description
    • Swoole\Coroutine\MySQL::connect — Description
    • Swoole\Coroutine\MySQL::__construct — Description
    • Swoole\Coroutine\MySQL::__destruct — Description
    • Swoole\Coroutine\MySQL::getDefer — Description
    • Swoole\Coroutine\MySQL::query — Description
    • Swoole\Coroutine\MySQL::recv — Description
    • Swoole\Coroutine\MySQL::setDefer — Description
    • Swoole\Coroutine::getuid — Description
    • Swoole\Coroutine::resume — Description
    • Swoole\Coroutine::suspend — Description
  • Swoole\Event — The Swoole\Event class
    • Swoole\Event::add — Add new callback functions of a socket into the EventLoop.
    • Swoole\Event::defer — Add a callback function to the next event loop.
    • Swoole\Event::del — Remove all event callback functions of a socket.
    • Swoole\Event::exit — Exit the eventloop, only available at client side.
    • Swoole\Event::set — Update the event callback functions of a socket.
    • Swoole\Event::wait — Description
    • Swoole\Event::write — Write data to the socket.
  • Swoole\Exception — The Swoole\Exception class
  • Swoole\Http\Client — The Swoole\Http\Client class
    • Swoole\Http\Client::addFile — Add a file to the post form.
    • Swoole\Http\Client::close — Close the http connection.
    • Swoole\Http\Client::__construct — Construct the async HTTP client.
    • Swoole\Http\Client::__destruct — Destruct the HTTP client.
    • Swoole\Http\Client::download — Download a file from the remote server.
    • Swoole\Http\Client::execute — Send the HTTP request after setting the parameters.
    • Swoole\Http\Client::get — Send GET http request to the remote server.
    • Swoole\Http\Client::isConnected — Check if the HTTP connection is connected.
    • Swoole\Http\Client::on — Register callback function by event name.
    • Swoole\Http\Client::post — Send POST http request to the remote server.
    • Swoole\Http\Client::push — Push data to websocket client.
    • Swoole\Http\Client::set — Update the HTTP client parameters.
    • Swoole\Http\Client::setCookies — Set the http request cookies.
    • Swoole\Http\Client::setData — Set the HTTP request body data.
    • Swoole\Http\Client::setHeaders — Set the HTTP request headers.
    • Swoole\Http\Client::setMethod — Set the HTTP request method.
    • Swoole\Http\Client::upgrade — Upgrade to websocket protocol.
  • Swoole\Http\Request — The Swoole\Http\Request class
    • Swoole\Http\Request::__destruct — Destruct the HTTP request.
    • Swoole\Http\Request::rawcontent — Get the raw HTTP POST body.
  • Swoole\Http\Response — The Swoole\Http\Response class
    • Swoole\Http\Response::cookie — Set the cookies of the HTTP response.
    • Swoole\Http\Response::__destruct — Destruct the HTTP response.
    • Swoole\Http\Response::end — Send data for the HTTP request and finish the response.
    • Swoole\Http\Response::gzip — Enable the gzip of response content.
    • Swoole\Http\Response::header — Set the HTTP response headers.
    • Swoole\Http\Response::initHeader — Init the HTTP response header.
    • Swoole\Http\Response::rawcookie — Set the raw cookies to the HTTP response.
    • Swoole\Http\Response::sendfile — Send file through the HTTP response.
    • Swoole\Http\Response::status — Set the status code of the HTTP response.
    • Swoole\Http\Response::write — Append HTTP body content to the HTTP response.
  • Swoole\Http\Server — The Swoole\Http\Server class
    • Swoole\Http\Server::on — Bind callback function to HTTP server by event name.
    • Swoole\Http\Server::start — Start the swoole http server.
  • Swoole\Lock — The Swoole\Lock class
    • Swoole\Lock::__construct — Construct a memory lock.
    • Swoole\Lock::__destruct — Destory a Swoole memory lock.
    • Swoole\Lock::lock — Try to acquire the lock. It will block if the lock is not available.
    • Swoole\Lock::lock_read — Lock a read-write lock for reading.
    • Swoole\Lock::trylock — Try to acquire the lock and return straight away even the lock is not available.
    • Swoole\Lock::trylock_read — Try to lock a read-write lock for reading and return straight away even the lock is not available.
    • Swoole\Lock::unlock — Release the lock.
  • Swoole\Mmap — The Swoole\Mmap class
    • Swoole\Mmap::open — Map a file into memory and return the stream resource which can be used by PHP stream operations.
  • Swoole\MySQL — The Swoole\MySQL class
    • Swoole\MySQL::close — Close the async MySQL connection.
    • Swoole\MySQL::connect — Connect to the remote MySQL server.
    • Swoole\MySQL::__construct — Construct an async MySQL client.
    • Swoole\MySQL::__destruct — Destory the async MySQL client.
    • Swoole\MySQL::getBuffer — Description
    • Swoole\MySQL::on — Register callback function based on event name.
    • Swoole\MySQL::query — Run the SQL query.
  • Swoole\MySQL\Exception — The Swoole\MySQL\Exception class
  • Swoole\Process — The Swoole\Process class
    • Swoole\Process::alarm — High precision timer which triggers signal with fixed interval.
    • Swoole\Process::close — Close the pipe to the child process.
    • Swoole\Process::__construct — Construct a process.
    • Swoole\Process::daemon — Change the process to be a daemon process.
    • Swoole\Process::__destruct — Destroy the process.
    • Swoole\Process::exec — Execute system commands.
    • Swoole\Process::exit — Stop the child processes.
    • Swoole\Process::freeQueue — Destroy the message queue created by swoole_process::useQueue.
    • Swoole\Process::kill — Send signal to the child process.
    • Swoole\Process::name — Set name of the process.
    • Swoole\Process::pop — Read and pop data from the message queue.
    • Swoole\Process::push — Write and push data into the message queue.
    • Swoole\Process::read — Read data sending to the process.
    • Swoole\Process::signal — Send signal to the child processes.
    • Swoole\Process::start — Start the process.
    • Swoole\Process::statQueue — Get the stats of the message queue used as the communication method between processes.
    • Swoole\Process::useQueue — Create a message queue as the communication method between the parent process and child processes.
    • Swoole\Process::wait — Wait for the events of child processes.
    • Swoole\Process::write — Write data into the pipe and communicate with the parent process or child processes.
  • Swoole\Redis\Server — The Swoole\Redis\Server class
    • Swoole\Redis\Server::format — Description
    • Swoole\Redis\Server::setHandler — Description
    • Swoole\Redis\Server::start — Description
  • Swoole\Serialize — The Swoole\Serialize class
    • Swoole\Serialize::pack — Serialize the data.
    • Swoole\Serialize::unpack — Unserialize the data.
  • Swoole\Server — The Swoole\Server class
    • Swoole\Server::addlistener — Add a new listener to the server.
    • Swoole\Server::addProcess — Add a user defined swoole_process to the server.
    • Swoole\Server::after — Trigger a callback function after a period of time.
    • Swoole\Server::bind — Bind the connection to a user defined user ID.
    • Swoole\Server::clearTimer — Stop and destroy a timer.
    • Swoole\Server::close — Close a connection to the client.
    • Swoole\Server::confirm — Check status of the connection.
    • Swoole\Server::connection_info — Get the connection info by file description.
    • Swoole\Server::connection_list — Get all of the established connections.
    • Swoole\Server::__construct — Construct a Swoole server.
    • Swoole\Server::defer — Delay execution of the callback function at the end of current EventLoop.
    • Swoole\Server\Port::__construct — Construct a server port
    • Swoole\Server\Port::__destruct — Destory server port
    • Swoole\Server\Port::on — Register callback functions by event.
    • Swoole\Server\Port::set — Set protocol of the server port.
    • Swoole\Server::exist — Check if the connection is existed.
    • Swoole\Server::finish — Used in task process for sending result to the worker process when the task is finished.
    • Swoole\Server::getClientInfo — Get the connection info by file description.
    • Swoole\Server::getClientList — Get all of the established connections.
    • Swoole\Server::getLastError — Get the error code of the most recent error.
    • Swoole\Server::heartbeat — Check all the connections on the server.
    • Swoole\Server::listen — Listen on the given IP and port, socket type.
    • Swoole\Server::on — Register a callback function by event name.
    • Swoole\Server::pause — Stop receiving data from the connection.
    • Swoole\Server::protect — Set the connection to be protected mode.
    • Swoole\Server::reload — Restart all the worker process.
    • Swoole\Server::resume — Start receving data from the connection.
    • Swoole\Server::send — Send data to the client.
    • Swoole\Server::sendfile — Send file to the connection.
    • Swoole\Server::sendMessage — Send message to worker processes by ID.
    • Swoole\Server::sendto — Send data to the remote UDP address.
    • Swoole\Server::sendwait — Send data to the remote socket in the blocking way.
    • Swoole\Server::set — Set the runtime settings of the swoole server.
    • Swoole\Server::shutdown — Shutdown the master server process, this function can be called in worker processes.
    • Swoole\Server::start — Start the Swoole server.
    • Swoole\Server::stats — Get the stats of the Swoole server.
    • Swoole\Server::stop — Stop the Swoole server.
    • Swoole\Server::task — Send data to the task worker processes.
    • Swoole\Server::taskwait — Send data to the task worker processes in blocking way.
    • Swoole\Server::taskWaitMulti — Execute multiple tasks concurrently.
    • Swoole\Server::tick — Repeats a given function at every given time-interval.
  • Swoole\Table — The Swoole\Table class
    • Swoole\Table::column — Set the data type and size of the columns.
    • Swoole\Table::__construct — Construct a Swoole memory table with fixed size.
    • Swoole\Table::count — Count the rows in the table, or count all the elements in the table if $mode = 1.
    • Swoole\Table::create — Create the swoole memory table.
    • Swoole\Table::current — Get the current row.
    • Swoole\Table::decr — Decrement the value in the Swoole table by $row_key and $column_key.
    • Swoole\Table::del — Delete a row in the Swoole table by $row_key.
    • Swoole\Table::destroy — Destroy the Swoole table.
    • Swoole\Table::exist — Check if a row is existed by $row_key.
    • Swoole\Table::get — Get the value in the Swoole table by $row_key and $column_key.
    • Swoole\Table::incr — Increment the value by $row_key and $column_key.
    • Swoole\Table::key — Get the key of current row.
    • Swoole\Table::next — Iterator the next row.
    • Swoole\Table::rewind — Rewind the iterator.
    • Swoole\Table::set — Update a row of the table by $row_key.
    • Swoole\Table::valid — Check if the current row is valid.
  • Swoole\Timer — The Swoole\Timer class
    • Swoole\Timer::after — Trigger a callback function after a period of time.
    • Swoole\Timer::clear — Delete a timer by timer ID.
    • Swoole\Timer::exists — Check if a timer is existed.
    • Swoole\Timer::tick — Repeats a given function at every given time-interval.
  • Swoole\WebSocket\Frame — The Swoole\WebSocket\Frame class
  • Swoole\WebSocket\Server — The Swoole\WebSocket\Server class
    • Swoole\WebSocket\Server::exist — Check if the file descriptor exists.
    • Swoole\WebSocket\Server::on — Register event callback function
    • Swoole\WebSocket\Server::pack — Get a pack of binary data to send in a single frame.
    • Swoole\WebSocket\Server::push — Push data to the remote client.
    • Swoole\WebSocket\Server::unpack — Unpack the binary data received from the client.


はじめに

Swoole is a high-performance networking framework using an event-driven, asynchronous, non-blocking I/O model. It can be used to develop high-performance, scalable, concurrent TCP, UDP, Unix socket, HTTP, Websocket services. To get started, please check the » Swoole Docs.

注意: この拡張モジュールは Windows 環境では利用できません。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Swoole
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

Use --with-swoole[=DIR] when compiling PHP.

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/swoole


実行時設定

php.ini の設定により動作が変化します。

Swoole 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
swoole.aio_thread_num | 2 | INI_ALL |
swoole.display_errors | On | INI_ALL |
swoole.fast_serialize | Off | INI_ALL |
swoole.unixsock_buffer_size | 8388608 | INI_ALL |
swoole.use_namespace | On | INI_SYSTEM |
swoole.enable_coroutine | On | INI_ALL | Available as of swoole 4.0.0
swoole.use_shortname | On | INI_ALL | Available as of swoole 4.0.0
swoole.enable_preemptive_scheduler | Off | INI_ALL | Available as of swoole 4.4.0
swoole.enable_library | On | INI_ALL | Available as of swoole 4.0.0

以下に設定ディレクティブに関する 簡単な説明を示します。

swoole.aio_thread_num int

POSIX asynchronous I/O thread number

swoole.display_errors string

This determines whether Swoole errors should be printed to the screen.

swoole.fast_serialize string

Whether to enable Swoole fast_serialize.

swoole.unixsock_buffer_size int

Buffer size of Unix socket.

swoole.use_namespace string

Whether to use PHP namespaces

swoole.enable_coroutine string

Whether to enable coroutine

swoole.use_shortname string

Whether to enable short aliases

swoole.enable_preemptive_scheduler string

Whether to enable preemptive scheduler

swoole.enable_library string

Whether to enable library


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SWOOLE_BASE (int)
SWOOLE_THREAD (int)
SWOOLE_PROCESS (int)
SWOOLE_IPC_UNSOCK (int)
SWOOLE_IPC_MSGQUEUE (int)
SWOOLE_IPC_PREEMPTIVE (int)
SWOOLE_SOCK_TCP (int)
SWOOLE_SOCK_TCP6 (int)
SWOOLE_SOCK_UDP (int)
SWOOLE_SOCK_UDP6 (int)
SWOOLE_SOCK_UNIX_DGRAM (int)
SWOOLE_SOCK_UNIX_STREAM (int)
SWOOLE_TCP (int)
SWOOLE_TCP6 (int)
SWOOLE_UDP (int)
SWOOLE_UDP6 (int)
SWOOLE_UNIX_DGRAM (int)
SWOOLE_UNIX_STREAM (int)
SWOOLE_SOCK_SYNC (int)
SWOOLE_SOCK_ASYNC (int)
SWOOLE_SYNC (int)
SWOOLE_ASYNC (int)
SWOOLE_KEEP (int)
SWOOLE_EVENT_READ (int)
SWOOLE_EVENT_WRITE (int)
SWOOLE_VERSION (string)
SWOOLE_AIO_BASE (int)
SWOOLE_AIO_LINUX (int)
SWOOLE_FILELOCK (int)
SWOOLE_MUTEX (int)
SWOOLE_SEM (int)
SWOOLE_RWLOCK (int)
WEBSOCKET_OPCODE_TEXT (int)
WEBSOCKET_OPCODE_BINARY (int)
WEBSOCKET_OPCODE_PING (int)
WEBSOCKET_STATUS_CONNECTION (int)
WEBSOCKET_STATUS_HANDSHAKE (int)
WEBSOCKET_STATUS_FRAME (int)
WEBSOCKET_STATUS_ACTIVE (int)
SWOOLE_FAST_PACK (int)
SWOOLE_LOG_DEBUG (int)
Debug log. Available as of swoole 2.1.2.
SWOOLE_LOG_TRACE (int)
Trace log. Available as of swoole 2.1.2.
SWOOLE_LOG_INFO (int)
Info log. Available as of swoole 2.1.2.
SWOOLE_LOG_NOTICE (int)
Notice log. Available as of swoole 2.1.2.
SWOOLE_LOG_WARNING (int)
Warning log. Available as of swoole 2.1.2.
SWOOLE_LOG_ERROR (int)
Error log. Available as of swoole 2.1.2.
SWOOLE_LOG_NONE (int)
None log. Available as of swoole 4.3.2.


Swoole 関数

目次

  • swoole_async_dns_lookup — Async and non-blocking hostname to IP lookup
  • swoole_async_read — Read file stream asynchronously
  • swoole_async_readfile — Read a file asynchronously
  • swoole_async_set — Update the async I/O options
  • swoole_async_write — Write data to a file stream asynchronously
  • swoole_async_writefile — Write data to a file asynchronously
  • swoole_clear_error — Clear errors in the socket or on the last error code
  • swoole_client_select — Get the file description which are ready to read/write or error
  • swoole_cpu_num — Get the number of CPU
  • swoole_errno — Get the error code of the latest system call
  • swoole_error_log — Output error messages to the log
  • swoole_event_add — Add new callback functions of a socket into the EventLoop
  • swoole_event_defer — Add callback function to the next event loop
  • swoole_event_del — Remove all event callback functions of a socket
  • swoole_event_exit — Exit the eventloop, only available at the client side
  • swoole_event_set — Update the event callback functions of a socket
  • swoole_event_wait — Start the event loop
  • swoole_event_write — Write data to a socket
  • swoole_get_local_ip — Get the IPv4 IP addresses of each NIC on the machine
  • swoole_last_error — Get the lastest error message
  • swoole_load_module — Load a swoole extension
  • swoole_select — Select the file descriptions which are ready to read/write or error in the eventloop
  • swoole_set_process_name — Set the process name
  • swoole_strerror — Convert the Errno into error messages
  • swoole_timer_after — Trigger a one time callback function in the future
  • swoole_timer_exists — Check if a timer callback function is existed
  • swoole_timer_tick — Trigger a timer tick callback function by time interval
  • swoole_version — Get the version of Swoole


Async and non-blocking hostname to IP lookup

  • ≪ Swoole 関数
  • swoole_async_read ≫
  • PHP Manual
  • Swoole 関数
  • Async and non-blocking hostname to IP lookup

swoole_async_dns_lookup

(PECL swoole >= 1.9.0)

swoole_async_dns_lookup — Async and non-blocking hostname to IP lookup

説明

swoole_async_dns_lookup(string $hostname, callable $callback): bool

パラメータ

hostname

The host name.

callback
callback(string $hostname, string $ip): mixed
hostname

The host name.

IP

The IP address.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Read file stream asynchronously

  • ≪ swoole_async_dns_lookup
  • swoole_async_readfile ≫
  • PHP Manual
  • Swoole 関数
  • Read file stream asynchronously

swoole_async_read

(PECL swoole >= 1.9.0)

swoole_async_read — Read file stream asynchronously

説明

swoole_async_read(
string $filename,
callable $callback,
int $chunk_size = 65536,
int $offset = 0
): bool

パラメータ

filename

The filename of the file being read.

callback
callback(string $filename, string $content): mixed
filename

The name of the file.

content

The content readed from the file stream.

chunk_size

The chunk length.

offset

The offset.

戻り値

Whether the read is succeed.


Read a file asynchronously

  • ≪ swoole_async_read
  • swoole_async_set ≫
  • PHP Manual
  • Swoole 関数
  • Read a file asynchronously

swoole_async_readfile

(PECL swoole >= 1.9.0)

swoole_async_readfile — Read a file asynchronously

説明

swoole_async_readfile(string $filename, callable $callback): bool

パラメータ

filename

The filename of the file being read.

callback
callback(string $filename, string $content): mixed
filename

The name of the file.

content

The content read from the file.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Update the async I/O options

  • ≪ swoole_async_readfile
  • swoole_async_write ≫
  • PHP Manual
  • Swoole 関数
  • Update the async I/O options

swoole_async_set

(PECL swoole >= 1.9.0)

swoole_async_set — Update the async I/O options

説明

swoole_async_set(array $settings): void

パラメータ

settings

戻り値

値を返しません。


Write data to a file stream asynchronously

  • ≪ swoole_async_set
  • swoole_async_writefile ≫
  • PHP Manual
  • Swoole 関数
  • Write data to a file stream asynchronously

swoole_async_write

(PECL swoole >= 1.9.0)

swoole_async_write — Write data to a file stream asynchronously

説明

swoole_async_write(
string $filename,
string $content,
int $offset = ?,
callable $callback = ?
): bool

パラメータ

filename

The filename being written.

content

The content writing to the file.

offset

The offset.

callback

戻り値

成功した場合に true を、失敗した場合に false を返します。


Write data to a file asynchronously

  • ≪ swoole_async_write
  • swoole_clear_error ≫
  • PHP Manual
  • Swoole 関数
  • Write data to a file asynchronously

swoole_async_writefile

(PECL swoole >= 1.9.0)

swoole_async_writefile — Write data to a file asynchronously

説明

swoole_async_writefile(
string $filename,
string $content,
callable $callback = ?,
int $flags = 0
): bool

パラメータ

filename

The filename being written.

content

The content writing to the file.

callback

flags

戻り値

成功した場合に true を、失敗した場合に false を返します。


Clear errors in the socket or on the last error code

  • ≪ swoole_async_writefile
  • swoole_client_select ≫
  • PHP Manual
  • Swoole 関数
  • Clear errors in the socket or on the last error code

swoole_clear_error

(PECL swoole >= 4.6.0)

swoole_clear_error — Clear errors in the socket or on the last error code

説明

swoole_clear_error(): void

Clear errors in the socket or on the last error code.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Get the file description which are ready to read/write or error

  • ≪ swoole_clear_error
  • swoole_cpu_num ≫
  • PHP Manual
  • Swoole 関数
  • Get the file description which are ready to read/write or error

swoole_client_select

(PECL swoole >= 1.9.0)

swoole_client_select — Get the file description which are ready to read/write or error

説明

swoole_client_select(
array &$read_array,
array &$write_array,
array &$error_array,
float $timeout = 0.5
): int

パラメータ

read_array

write_array

error_array

timeout

戻り値


Get the number of CPU

  • ≪ swoole_client_select
  • swoole_errno ≫
  • PHP Manual
  • Swoole 関数
  • Get the number of CPU

swoole_cpu_num

(PECL swoole >= 1.9.0)

swoole_cpu_num — Get the number of CPU

説明

swoole_cpu_num(): int

パラメータ

この関数にはパラメータはありません。

戻り値

The number of CPU.


Get the error code of the latest system call

  • ≪ swoole_cpu_num
  • swoole_error_log ≫
  • PHP Manual
  • Swoole 関数
  • Get the error code of the latest system call

swoole_errno

(PECL swoole >= 1.9.0)

swoole_errno — Get the error code of the latest system call

説明

swoole_errno(): int

パラメータ

この関数にはパラメータはありません。

戻り値


Output error messages to the log

  • ≪ swoole_errno
  • swoole_event_add ≫
  • PHP Manual
  • Swoole 関数
  • Output error messages to the log

swoole_error_log

(PECL swoole >= 4.5.8)

swoole_error_log — Output error messages to the log

説明

swoole_error_log(int $level, string $msg): void

Output error messages to the log.

パラメータ

level

Log Level, constants can be used: SWOOLE_LOG_DEBUG, SWOOLE_LOG_TRACE, SWOOLE_LOG_INFO, SWOOLE_LOG_NOTICE, SWOOLE_LOG_WARNING, SWOOLE_LOG_ERROR, SWOOLE_LOG_NONE

msg

Message content to be written to the log.

戻り値

値を返しません。


Add new callback functions of a socket into the EventLoop

  • ≪ swoole_error_log
  • swoole_event_defer ≫
  • PHP Manual
  • Swoole 関数
  • Add new callback functions of a socket into the EventLoop

swoole_event_add

(PECL swoole >= 1.9.0)

swoole_event_add — Add new callback functions of a socket into the EventLoop

説明

swoole_event_add(
int $fd,
callable $read_callback = ?,
callable $write_callback = ?,
int $events = 0
): int

パラメータ

fd

read_callback

write_callback

events

戻り値


Add callback function to the next event loop

  • ≪ swoole_event_add
  • swoole_event_del ≫
  • PHP Manual
  • Swoole 関数
  • Add callback function to the next event loop

swoole_event_defer

(PECL swoole >= 1.9.0)

swoole_event_defer — Add callback function to the next event loop

説明

swoole_event_defer(callable $callback): bool

パラメータ

callback

戻り値

成功した場合に true を、失敗した場合に false を返します。


Remove all event callback functions of a socket

  • ≪ swoole_event_defer
  • swoole_event_exit ≫
  • PHP Manual
  • Swoole 関数
  • Remove all event callback functions of a socket

swoole_event_del

(PECL swoole >= 1.9.0)

swoole_event_del — Remove all event callback functions of a socket

説明

swoole_event_del(int $fd): bool

パラメータ

fd

戻り値

成功した場合に true を、失敗した場合に false を返します。


Exit the eventloop, only available at the client side

  • ≪ swoole_event_del
  • swoole_event_set ≫
  • PHP Manual
  • Swoole 関数
  • Exit the eventloop, only available at the client side

swoole_event_exit

(PECL swoole >= 1.9.0)

swoole_event_exit — Exit the eventloop, only available at the client side

説明

swoole_event_exit(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Update the event callback functions of a socket

  • ≪ swoole_event_exit
  • swoole_event_wait ≫
  • PHP Manual
  • Swoole 関数
  • Update the event callback functions of a socket

swoole_event_set

(PECL swoole >= 1.9.0)

swoole_event_set — Update the event callback functions of a socket

説明

swoole_event_set(
int $fd,
callable $read_callback = ?,
callable $write_callback = ?,
int $events = 0
): bool

パラメータ

fd

read_callback

write_callback

events

戻り値


Start the event loop

  • ≪ swoole_event_set
  • swoole_event_write ≫
  • PHP Manual
  • Swoole 関数
  • Start the event loop

swoole_event_wait

(PECL swoole >= 1.9.0)

swoole_event_wait — Start the event loop

説明

swoole_event_wait(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Write data to a socket

  • ≪ swoole_event_wait
  • swoole_get_local_ip ≫
  • PHP Manual
  • Swoole 関数
  • Write data to a socket

swoole_event_write

(PECL swoole >= 1.9.0)

swoole_event_write — Write data to a socket

説明

swoole_event_write(int $fd, string $data): bool

パラメータ

fd

data

戻り値

成功した場合に true を、失敗した場合に false を返します。


Get the IPv4 IP addresses of each NIC on the machine

  • ≪ swoole_event_write
  • swoole_last_error ≫
  • PHP Manual
  • Swoole 関数
  • Get the IPv4 IP addresses of each NIC on the machine

swoole_get_local_ip

(PECL swoole >= 1.9.0)

swoole_get_local_ip — Get the IPv4 IP addresses of each NIC on the machine

説明

swoole_get_local_ip(): array

パラメータ

この関数にはパラメータはありません。

戻り値


Get the lastest error message

  • ≪ swoole_get_local_ip
  • swoole_load_module ≫
  • PHP Manual
  • Swoole 関数
  • Get the lastest error message

swoole_last_error

(PECL swoole >= 1.9.0)

swoole_last_error — Get the lastest error message

説明

swoole_last_error(): int

パラメータ

この関数にはパラメータはありません。

戻り値


Load a swoole extension

  • ≪ swoole_last_error
  • swoole_select ≫
  • PHP Manual
  • Swoole 関数
  • Load a swoole extension

swoole_load_module

(PECL swoole >= 1.9.0)

swoole_load_module — Load a swoole extension

説明

swoole_load_module(string $filename): mixed

パラメータ

この関数にはパラメータはありません。

戻り値


Select the file descriptions which are ready to read/write or error in the eventloop

  • ≪ swoole_load_module
  • swoole_set_process_name ≫
  • PHP Manual
  • Swoole 関数
  • Select the file descriptions which are ready to read/write or error in the eventloop

swoole_select

(PECL swoole >= 1.9.0)

swoole_select — Select the file descriptions which are ready to read/write or error in the eventloop

説明

swoole_select(
array &$read_array,
array &$write_array,
array &$error_array,
float $timeout = ?
): int

パラメータ

read_array

write_array

error_array

timeout

戻り値


Set the process name

  • ≪ swoole_select
  • swoole_strerror ≫
  • PHP Manual
  • Swoole 関数
  • Set the process name

swoole_set_process_name

(PECL swoole >= 1.9.0)

swoole_set_process_name — Set the process name

説明

swoole_set_process_name(string $process_name, int $size = 128): void

パラメータ

process_name

戻り値


Convert the Errno into error messages

  • ≪ swoole_set_process_name
  • swoole_timer_after ≫
  • PHP Manual
  • Swoole 関数
  • Convert the Errno into error messages

swoole_strerror

(PECL swoole >= 1.9.0)

swoole_strerror — Convert the Errno into error messages

説明

swoole_strerror(int $errno, int $error_type = 0): string

パラメータ

errno

戻り値


Trigger a one time callback function in the future

  • ≪ swoole_strerror
  • swoole_timer_exists ≫
  • PHP Manual
  • Swoole 関数
  • Trigger a one time callback function in the future

swoole_timer_after

(PECL swoole >= 1.9.0)

swoole_timer_after — Trigger a one time callback function in the future

説明

swoole_timer_after(int $ms, callable $callback, mixed $param = ?): int

パラメータ

ms

callback

param

戻り値


Check if a timer callback function is existed

  • ≪ swoole_timer_after
  • swoole_timer_tick ≫
  • PHP Manual
  • Swoole 関数
  • Check if a timer callback function is existed

swoole_timer_exists

(PECL swoole >= 1.9.0)

swoole_timer_exists — Check if a timer callback function is existed

説明

swoole_timer_exists(int $timer_id): bool

パラメータ

timer_id

戻り値


Trigger a timer tick callback function by time interval

  • ≪ swoole_timer_exists
  • swoole_version ≫
  • PHP Manual
  • Swoole 関数
  • Trigger a timer tick callback function by time interval

swoole_timer_tick

(PECL swoole >= 1.9.0)

swoole_timer_tick — Trigger a timer tick callback function by time interval

説明

swoole_timer_tick(int $ms, callable $callback, mixed $param = ?): int

パラメータ

ms

callback

戻り値


Get the version of Swoole

  • ≪ swoole_timer_tick
  • Swoole\Async ≫
  • PHP Manual
  • Swoole 関数
  • Get the version of Swoole

swoole_version

(PECL swoole >= 1.9.0)

swoole_version — Get the version of Swoole

説明

swoole_version(): string

パラメータ

この関数にはパラメータはありません。

戻り値

The version of Swoole.


The Swoole\Async class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Async {
/* メソッド */
public static dnsLookup(string $hostname, callable $callback): void
public static read(
string $filename,
callable $callback,
int $chunk_size = ?,
int $offset = ?
): bool
public static readFile(string $filename, callable $callback): void
public static set(array $settings): void
public static write(
string $filename,
string $content,
int $offset = ?,
callable $callback = ?
): void
public static writeFile(
string $filename,
string $content,
callable $callback = ?,
string $flags = ?
): void
}

目次

  • Swoole\Async::dnsLookup — Async and non-blocking hostname to IP lookup.
  • Swoole\Async::read — Read file stream asynchronously.
  • Swoole\Async::readFile — Read a file asynchronously.
  • Swoole\Async::set — Update the async I/O options.
  • Swoole\Async::write — Write data to a file stream asynchronously.
  • Swoole\Async::writeFile — Description


Async and non-blocking hostname to IP lookup.

  • ≪ Swoole\Async
  • Swoole\Async::read ≫
  • PHP Manual
  • Swoole\Async
  • Async and non-blocking hostname to IP lookup.

Swoole\Async::dnsLookup

(PECL swoole >= 1.9.0)

Swoole\Async::dnsLookup — Async and non-blocking hostname to IP lookup.

説明

public static Swoole\Async::dnsLookup(string $hostname, callable $callback): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

hostname

The host name.

callback
callback(string $hostname, string $ip): mixed
hostname

The host name.

IP

The IP address.


Read file stream asynchronously.

  • ≪ Swoole\Async::dnsLookup
  • Swoole\Async::readFile ≫
  • PHP Manual
  • Swoole\Async
  • Read file stream asynchronously.

Swoole\Async::read

(PECL swoole >= 1.9.0)

Swoole\Async::read — Read file stream asynchronously.

説明

public static Swoole\Async::read(
string $filename,
callable $callback,
int $chunk_size = ?,
int $offset = ?
): bool

パラメータ

filename

The name of the file.

callback
callback(string $filename, string $content): mixed
filename

The name of the file.

content

The content readed from the file stream.

chunk_size

The chunk length.

offset

The offset.

戻り値

Whether the read is succeed.


Read a file asynchronously.

  • ≪ Swoole\Async::read
  • Swoole\Async::set ≫
  • PHP Manual
  • Swoole\Async
  • Read a file asynchronously.

Swoole\Async::readFile

(PECL swoole >= 1.9.0)

Swoole\Async::readFile — Read a file asynchronously.

説明

public static Swoole\Async::readFile(string $filename, callable $callback): void

パラメータ

filename

The filename of the file being read.

callback
callback(string $filename, string $content): mixed
filename

The name of the file.

content

The content readed from the file.


Update the async I/O options.

  • ≪ Swoole\Async::readFile
  • Swoole\Async::write ≫
  • PHP Manual
  • Swoole\Async
  • Update the async I/O options.

Swoole\Async::set

(PECL swoole >= 1.9.0)

Swoole\Async::set — Update the async I/O options.

説明

public static Swoole\Async::set(array $settings): void

パラメータ

settings


Write data to a file stream asynchronously.

  • ≪ Swoole\Async::set
  • Swoole\Async::writeFile ≫
  • PHP Manual
  • Swoole\Async
  • Write data to a file stream asynchronously.

Swoole\Async::write

(PECL swoole >= 1.9.0)

Swoole\Async::write — Write data to a file stream asynchronously.

説明

public static Swoole\Async::write(
string $filename,
string $content,
int $offset = ?,
callable $callback = ?
): void

パラメータ

filename

The filename being written.

content

The content writing to the file.

offset

The offset.

callback


Description

  • ≪ Swoole\Async::write
  • Swoole\Atomic ≫
  • PHP Manual
  • Swoole\Async
  • Description

Swoole\Async::writeFile

(PECL swoole >= 1.9.0)

Swoole\Async::writeFile — Description

説明

public static Swoole\Async::writeFile(
string $filename,
string $content,
callable $callback = ?,
string $flags = ?
): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

The filename being written.

content

The content writing to the file.

callback

flags


The Swoole\Atomic class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Atomic {
/* メソッド */
public add(int $add_value = ?): int
public cmpset(int $cmp_value, int $new_value): int
public get(): int
public set(int $value): int
public sub(int $sub_value = ?): int
}

目次

  • Swoole\Atomic::add — Add a number to the value to the atomic object.
  • Swoole\Atomic::cmpset — Compare and set the value of the atomic object.
  • Swoole\Atomic::__construct — Construct a swoole atomic object.
  • Swoole\Atomic::get — Get the current value of the atomic object.
  • Swoole\Atomic::set — Set a new value to the atomic object.
  • Swoole\Atomic::sub — Subtract a number to the value of the atomic object.


Add a number to the value to the atomic object.

  • ≪ Swoole\Atomic
  • Swoole\Atomic::cmpset ≫
  • PHP Manual
  • Swoole\Atomic
  • Add a number to the value to the atomic object.

Swoole\Atomic::add

(PECL swoole >= 1.9.0)

Swoole\Atomic::add — Add a number to the value to the atomic object.

説明

public Swoole\Atomic::add(int $add_value = ?): int

Add a number to the value to the atomic object.

パラメータ

add_value

The value which will be added to the current value.

戻り値

The new value of the atomic object.


Compare and set the value of the atomic object.

  • ≪ Swoole\Atomic::add
  • Swoole\Atomic::__construct ≫
  • PHP Manual
  • Swoole\Atomic
  • Compare and set the value of the atomic object.

Swoole\Atomic::cmpset

(PECL swoole >= 1.9.0)

Swoole\Atomic::cmpset — Compare and set the value of the atomic object.

説明

public Swoole\Atomic::cmpset(int $cmp_value, int $new_value): int

パラメータ

cmp_value

The value to compare with the current value of the atomic object.

new_value

The value to set to the atomic object if the cmp_value is the same as the current value of the atomic object.

戻り値

The new value of the atomic object.


Construct a swoole atomic object.

  • ≪ Swoole\Atomic::cmpset
  • Swoole\Atomic::get ≫
  • PHP Manual
  • Swoole\Atomic
  • Construct a swoole atomic object.

Swoole\Atomic::__construct

(PECL swoole >= 1.9.0)

Swoole\Atomic::__construct — Construct a swoole atomic object.

説明

public Swoole\Atomic::__construct(int $value = ?)

Swoole atomic object is a integer variable allows any processor to atomically test and modify. It is implemented based on CPU atomic instructions. The Swoole atomic variables have to defined before swoole_server->start.

Compare-and-swap (CAS) is an atomic instruction used in multithreading to achieve synchronization. It compares the content of a memory location with a given value and, only if they are the same, modifies the content of that memory location to a new given value.

パラメータ

value

The value of the atomic object.


Get the current value of the atomic object.

  • ≪ Swoole\Atomic::__construct
  • Swoole\Atomic::set ≫
  • PHP Manual
  • Swoole\Atomic
  • Get the current value of the atomic object.

Swoole\Atomic::get

(PECL swoole >= 1.9.0)

Swoole\Atomic::get — Get the current value of the atomic object.

説明

public Swoole\Atomic::get(): int

Get the current value of the atomic object.

パラメータ

この関数にはパラメータはありません。

戻り値

The current value of the atomic object.


Set a new value to the atomic object.

  • ≪ Swoole\Atomic::get
  • Swoole\Atomic::sub ≫
  • PHP Manual
  • Swoole\Atomic
  • Set a new value to the atomic object.

Swoole\Atomic::set

(PECL swoole >= 1.9.0)

Swoole\Atomic::set — Set a new value to the atomic object.

説明

public Swoole\Atomic::set(int $value): int

Set a new value to the atomic object.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

value

The value to set to the atomic object.

戻り値

The current value of the atomic object.


Subtract a number to the value of the atomic object.

  • ≪ Swoole\Atomic::set
  • Swoole\Buffer ≫
  • PHP Manual
  • Swoole\Atomic
  • Subtract a number to the value of the atomic object.

Swoole\Atomic::sub

(PECL swoole >= 1.9.0)

Swoole\Atomic::sub — Subtract a number to the value of the atomic object.

説明

public Swoole\Atomic::sub(int $sub_value = ?): int

Subtract a number to the value of the atomic object.

パラメータ

sub_value

The value which will be subtracted to the current value.

戻り値

The current value of the atomic object.


The Swoole\Buffer class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Buffer {
/* メソッド */
public append(string $data): int
public clear(): void
public __destruct(): void
public expand(int $size): int
public read(int $offset, int $length): string
public recycle(): void
public substr(int $offset, int $length = ?, bool $remove = ?): string
public __toString(): string
public write(int $offset, string $data): void
}

目次

  • Swoole\Buffer::append — Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.
  • Swoole\Buffer::clear — Reset the memory buffer.
  • Swoole\Buffer::__construct — Fixed size memory blocks allocation.
  • Swoole\Buffer::__destruct — Destruct the Swoole memory buffer.
  • Swoole\Buffer::expand — Expand the size of memory buffer.
  • Swoole\Buffer::read — Read data from the memory buffer based on offset and length.
  • Swoole\Buffer::recycle — Release the memory to OS which is not used by the memory buffer.
  • Swoole\Buffer::substr — Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.
  • Swoole\Buffer::__toString — Get the string value of the memory buffer.
  • Swoole\Buffer::write — Write data to the memory buffer. The memory allocated for the buffer will not be changed.


Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.

  • ≪ Swoole\Buffer
  • Swoole\Buffer::clear ≫
  • PHP Manual
  • Swoole\Buffer
  • Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.

Swoole\Buffer::append

(PECL swoole >= 1.9.0)

Swoole\Buffer::append — Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.

説明

public Swoole\Buffer::append(string $data): int

パラメータ

data

The string or binary data to append at the end of the memory buffer.

戻り値

The new size of the memory buffer.


Reset the memory buffer.

  • ≪ Swoole\Buffer::append
  • Swoole\Buffer::__construct ≫
  • PHP Manual
  • Swoole\Buffer
  • Reset the memory buffer.

Swoole\Buffer::clear

(PECL swoole >= 1.9.0)

Swoole\Buffer::clear — Reset the memory buffer.

説明

public Swoole\Buffer::clear(): void

パラメータ

この関数にはパラメータはありません。


Fixed size memory blocks allocation.

  • ≪ Swoole\Buffer::clear
  • Swoole\Buffer::__destruct ≫
  • PHP Manual
  • Swoole\Buffer
  • Fixed size memory blocks allocation.

Swoole\Buffer::__construct

(PECL swoole >= 1.9.0)

Swoole\Buffer::__construct — Fixed size memory blocks allocation.

説明

public Swoole\Buffer::__construct(int $size = ?)

パラメータ

size

The size of the memory to allocate.


Destruct the Swoole memory buffer.

  • ≪ Swoole\Buffer::__construct
  • Swoole\Buffer::expand ≫
  • PHP Manual
  • Swoole\Buffer
  • Destruct the Swoole memory buffer.

Swoole\Buffer::__destruct

(PECL swoole >= 1.9.0)

Swoole\Buffer::__destruct — Destruct the Swoole memory buffer.

説明

public Swoole\Buffer::__destruct(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。


Expand the size of memory buffer.

  • ≪ Swoole\Buffer::__destruct
  • Swoole\Buffer::read ≫
  • PHP Manual
  • Swoole\Buffer
  • Expand the size of memory buffer.

Swoole\Buffer::expand

(PECL swoole >= 1.9.0)

Swoole\Buffer::expand — Expand the size of memory buffer.

説明

public Swoole\Buffer::expand(int $size): int

パラメータ

size

The new size of the memory buffer.

戻り値

The new size of the memory buffer.


Read data from the memory buffer based on offset and length.

  • ≪ Swoole\Buffer::expand
  • Swoole\Buffer::recycle ≫
  • PHP Manual
  • Swoole\Buffer
  • Read data from the memory buffer based on offset and length.

Swoole\Buffer::read

(PECL swoole >= 1.9.0)

Swoole\Buffer::read — Read data from the memory buffer based on offset and length.

説明

public Swoole\Buffer::read(int $offset, int $length): string

パラメータ

offset

The offset.

length

The length.

戻り値

The data readed from the memory buffer.


Release the memory to OS which is not used by the memory buffer.

  • ≪ Swoole\Buffer::read
  • Swoole\Buffer::substr ≫
  • PHP Manual
  • Swoole\Buffer
  • Release the memory to OS which is not used by the memory buffer.

Swoole\Buffer::recycle

(PECL swoole >= 1.9.0)

Swoole\Buffer::recycle — Release the memory to OS which is not used by the memory buffer.

説明

public Swoole\Buffer::recycle(): void

パラメータ

この関数にはパラメータはありません。


Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.

  • ≪ Swoole\Buffer::recycle
  • Swoole\Buffer::__toString ≫
  • PHP Manual
  • Swoole\Buffer
  • Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.

Swoole\Buffer::substr

(PECL swoole >= 1.9.0)

Swoole\Buffer::substr — Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.

説明

public Swoole\Buffer::substr(int $offset, int $length = ?, bool $remove = ?): string

If $remove is set to be true and $offset is set to be 0, the data will be removed from the buffer. The memory for storing the data will be released when the buffer object is deconstructed.

パラメータ

offset

The offset.

length

The length.

remove

Whether to remove the data from the memory buffer.

戻り値

The data or string readed from the memory buffer.


Get the string value of the memory buffer.

  • ≪ Swoole\Buffer::substr
  • Swoole\Buffer::write ≫
  • PHP Manual
  • Swoole\Buffer
  • Get the string value of the memory buffer.

Swoole\Buffer::__toString

(PECL swoole >= 1.9.0)

Swoole\Buffer::__toString — Get the string value of the memory buffer.

説明

public Swoole\Buffer::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値

The string value of the memory buffer.


Write data to the memory buffer. The memory allocated for the buffer will not be changed.

  • ≪ Swoole\Buffer::__toString
  • Swoole\Channel ≫
  • PHP Manual
  • Swoole\Buffer
  • Write data to the memory buffer. The memory allocated for the buffer will not be changed.

Swoole\Buffer::write

(PECL swoole >= 1.9.0)

Swoole\Buffer::write — Write data to the memory buffer. The memory allocated for the buffer will not be changed.

説明

public Swoole\Buffer::write(int $offset, string $data): void

パラメータ

offset

The offset.

data

The data to write to the memory buffer.

戻り値


The Swoole\Channel class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Channel {
/* メソッド */
public __destruct(): void
public pop(): mixed
public push(string $data): bool
public stats(): array
}

目次

  • Swoole\Channel::__construct — Construct a Swoole Channel
  • Swoole\Channel::__destruct — Destruct a Swoole channel.
  • Swoole\Channel::pop — Read and pop data from swoole channel.
  • Swoole\Channel::push — Write and push data into Swoole channel.
  • Swoole\Channel::stats — Get stats of swoole channel.


Construct a Swoole Channel

  • ≪ Swoole\Channel
  • Swoole\Channel::__destruct ≫
  • PHP Manual
  • Swoole\Channel
  • Construct a Swoole Channel

Swoole\Channel::__construct

(PECL swoole >= 1.9.0)

Swoole\Channel::__construct — Construct a Swoole Channel

説明

public Swoole\Channel::__construct(string $size)

Swoole channel is memory data structure works like Chan in Golang, implemented based on shared memory and mutex locks. It can be used as high performance message queue in memory. Construct a swoole channel with a fixed size. The minimum size of a swoole channel is 64KB. Exceptions will be thrown if there is not enough memory.

パラメータ

size

The size of the Swoole channel.


Destruct a Swoole channel.

  • ≪ Swoole\Channel::__construct
  • Swoole\Channel::pop ≫
  • PHP Manual
  • Swoole\Channel
  • Destruct a Swoole channel.

Swoole\Channel::__destruct

(PECL swoole >= 1.9.0)

Swoole\Channel::__destruct — Destruct a Swoole channel.

説明

public Swoole\Channel::__destruct(): void

パラメータ

この関数にはパラメータはありません。


Read and pop data from swoole channel.

  • ≪ Swoole\Channel::__destruct
  • Swoole\Channel::push ≫
  • PHP Manual
  • Swoole\Channel
  • Read and pop data from swoole channel.

Swoole\Channel::pop

(PECL swoole >= 1.9.0)

Swoole\Channel::pop — Read and pop data from swoole channel.

説明

public Swoole\Channel::pop(): mixed

パラメータ

この関数にはパラメータはありません。

戻り値

If the channel is empty, the function will return false, or return the unserialized data.


Write and push data into Swoole channel.

  • ≪ Swoole\Channel::pop
  • Swoole\Channel::stats ≫
  • PHP Manual
  • Swoole\Channel
  • Write and push data into Swoole channel.

Swoole\Channel::push

(PECL swoole >= 1.9.0)

Swoole\Channel::push — Write and push data into Swoole channel.

説明

public Swoole\Channel::push(string $data): bool

Data can be any non-empty PHP variable, the variable will be serialized if it is not string type.

If size of the data is more than 8KB, swoole channel will use temp files storage.

The function will return true if the write operation is succeeded, or return false if there is not enough space.

パラメータ

data

The data to push into the Swoole channel.

戻り値

Wheter the data is pushed into he Swoole channel.


Get stats of swoole channel.

  • ≪ Swoole\Channel::push
  • Swoole\Client ≫
  • PHP Manual
  • Swoole\Channel
  • Get stats of swoole channel.

Swoole\Channel::stats

(PECL swoole >= 1.9.0)

Swoole\Channel::stats — Get stats of swoole channel.

説明

public Swoole\Channel::stats(): array

Get the numbers of queued elements and total size of the memory used by the queue.

パラメータ

この関数にはパラメータはありません。

戻り値

The stats of the Swoole channel.


The Swoole\Client class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Client {
/* 定数 */
const int MSG_OOB = 1;
const int MSG_PEEK = 2;
const int MSG_DONTWAIT = 128;
const int MSG_WAITALL = 64;
/* プロパティ */
public $errCode;
public $sock;
public $reuse;
public $reuseCount;
/* メソッド */
public close(bool $force = ?): bool
public connect(
string $host,
int $port = ?,
int $timeout = ?,
int $flag = ?
): bool
public __destruct(): void
public getpeername(): array
public getsockname(): array
public isConnected(): bool
public on(string $event, callable $callback): void
public pause(): void
public pipe(string $socket): void
public recv(string $size = ?, string $flag = ?): void
public resume(): void
public send(string $data, string $flag = ?): int
public sendfile(string $filename, int $offset = ?): bool
public sendto(string $ip, int $port, string $data): bool
public set(array $settings): void
public sleep(): void
public wakeup(): void
}

プロパティ

errCode

sock

reuse

reuseCount

定義済み定数

Swoole\Client::MSG_OOB

Swoole\Client::MSG_PEEK

Swoole\Client::MSG_DONTWAIT

Swoole\Client::MSG_WAITALL

目次

  • Swoole\Client::close — Close the connection established.
  • Swoole\Client::connect — Connect to the remote TCP or UDP port.
  • Swoole\Client::__construct — Create Swoole sync or async TCP/UDP client, with or without SSL.
  • Swoole\Client::__destruct — Destruct the Swoole client.
  • Swoole\Client::getpeername — Get the remote socket name of the connection.
  • Swoole\Client::getsockname — Get the local socket name of the connection.
  • Swoole\Client::isConnected — Check if the connection is established.
  • Swoole\Client::on — Add callback functions triggered by events.
  • Swoole\Client::pause — Pause receiving data.
  • Swoole\Client::pipe — Redirect the data to another file descriptor.
  • Swoole\Client::recv — Receive data from the remote socket.
  • Swoole\Client::resume — Resume receiving data.
  • Swoole\Client::send — Send data to the remote TCP socket.
  • Swoole\Client::sendfile — Send file to the remote TCP socket.
  • Swoole\Client::sendto — Send data to the remote UDP address.
  • Swoole\Client::set — Set the Swoole client parameters before the connection is established.
  • Swoole\Client::sleep — Remove the TCP client from system event loop.
  • Swoole\Client::wakeup — Add the TCP client back into the system event loop.


Close the connection established.

  • ≪ Swoole\Client
  • Swoole\Client::connect ≫
  • PHP Manual
  • Swoole\Client
  • Close the connection established.

Swoole\Client::close

(PECL swoole >= 1.9.0)

Swoole\Client::close — Close the connection established.

説明

public Swoole\Client::close(bool $force = ?): bool

パラメータ

force

Whether force to close the connection.

戻り値

Whether the connection is closed.


Connect to the remote TCP or UDP port.

  • ≪ Swoole\Client::close
  • Swoole\Client::__construct ≫
  • PHP Manual
  • Swoole\Client
  • Connect to the remote TCP or UDP port.

Swoole\Client::connect

(PECL swoole >= 1.9.0)

Swoole\Client::connect — Connect to the remote TCP or UDP port.

説明

public Swoole\Client::connect(
string $host,
int $port = ?,
int $timeout = ?,
int $flag = ?
): bool

パラメータ

host

The host name of the remote address.

port

The port number of the remote address.

timeout

The timeout(second) of connect/send/recv, the dafault value is 0.1s

flag

If the type of client is UDP, the $flag means if to enable the configuration udp_connect. If the configuration udp_connect is enabled, the client will only receive the data from specified ip:port. If the type of client is TCP and the $flag is set to 1, it must use swoole_client_select to check the connection status before send/recv.

戻り値

Whether the connection is established.


Create Swoole sync or async TCP/UDP client, with or without SSL.

  • ≪ Swoole\Client::connect
  • Swoole\Client::__destruct ≫
  • PHP Manual
  • Swoole\Client
  • Create Swoole sync or async TCP/UDP client, with or without SSL.

Swoole\Client::__construct

(PECL swoole >= 1.9.0)

Swoole\Client::__construct — Create Swoole sync or async TCP/UDP client, with or without SSL.

説明

public Swoole\Client::__construct(int $sock_type, int $is_async = ?)

パラメータ

sock_type

The type of socket: SWOOLE_TCP, SWOOLE_UDP, SWOOLE_ASYNC, SWOOLE_SSL, SWOOLE_KEEP.

is_async

Synchronous or asynchronous client.


Destruct the Swoole client.

  • ≪ Swoole\Client::__construct
  • Swoole\Client::getpeername ≫
  • PHP Manual
  • Swoole\Client
  • Destruct the Swoole client.

Swoole\Client::__destruct

(PECL swoole >= 1.9.0)

Swoole\Client::__destruct — Destruct the Swoole client.

説明

public Swoole\Client::__destruct(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。


Get the remote socket name of the connection.

  • ≪ Swoole\Client::__destruct
  • Swoole\Client::getsockname ≫
  • PHP Manual
  • Swoole\Client
  • Get the remote socket name of the connection.

Swoole\Client::getpeername

(PECL swoole >= 1.9.0)

Swoole\Client::getpeername — Get the remote socket name of the connection.

説明

public Swoole\Client::getpeername(): array

パラメータ

この関数にはパラメータはありません。

戻り値

The host and port of the remote socket.


Get the local socket name of the connection.

  • ≪ Swoole\Client::getpeername
  • Swoole\Client::isConnected ≫
  • PHP Manual
  • Swoole\Client
  • Get the local socket name of the connection.

Swoole\Client::getsockname

(PECL swoole >= 1.9.0)

Swoole\Client::getsockname — Get the local socket name of the connection.

説明

public Swoole\Client::getsockname(): array

パラメータ

この関数にはパラメータはありません。

戻り値

The host and port of the local socket.


Check if the connection is established.

  • ≪ Swoole\Client::getsockname
  • Swoole\Client::on ≫
  • PHP Manual
  • Swoole\Client
  • Check if the connection is established.

Swoole\Client::isConnected

(PECL swoole >= 1.9.0)

Swoole\Client::isConnected — Check if the connection is established.

説明

public Swoole\Client::isConnected(): bool

This method returns the connection status of application layer.

パラメータ

この関数にはパラメータはありません。

戻り値

Whether the connection is established.


Add callback functions triggered by events.

  • ≪ Swoole\Client::isConnected
  • Swoole\Client::pause ≫
  • PHP Manual
  • Swoole\Client
  • Add callback functions triggered by events.

Swoole\Client::on

(PECL swoole >= 1.9.0)

Swoole\Client::on — Add callback functions triggered by events.

説明

public Swoole\Client::on(string $event, callable $callback): void

パラメータ

event

callback


Pause receiving data.

  • ≪ Swoole\Client::on
  • Swoole\Client::pipe ≫
  • PHP Manual
  • Swoole\Client
  • Pause receiving data.

Swoole\Client::pause

(PECL swoole >= 1.9.0)

Swoole\Client::pause — Pause receiving data.

説明

public Swoole\Client::pause(): void

パラメータ

この関数にはパラメータはありません。


Redirect the data to another file descriptor.

  • ≪ Swoole\Client::pause
  • Swoole\Client::recv ≫
  • PHP Manual
  • Swoole\Client
  • Redirect the data to another file descriptor.

Swoole\Client::pipe

(PECL swoole >= 1.9.0)

Swoole\Client::pipe — Redirect the data to another file descriptor.

説明

public Swoole\Client::pipe(string $socket): void

パラメータ

socket


Receive data from the remote socket.

  • ≪ Swoole\Client::pipe
  • Swoole\Client::resume ≫
  • PHP Manual
  • Swoole\Client
  • Receive data from the remote socket.

Swoole\Client::recv

(PECL swoole >= 1.9.0)

Swoole\Client::recv — Receive data from the remote socket.

説明

public Swoole\Client::recv(string $size = ?, string $flag = ?): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

size

flag

戻り値


Resume receiving data.

  • ≪ Swoole\Client::recv
  • Swoole\Client::send ≫
  • PHP Manual
  • Swoole\Client
  • Resume receiving data.

Swoole\Client::resume

(PECL swoole >= 1.9.0)

Swoole\Client::resume — Resume receiving data.

説明

public Swoole\Client::resume(): void

パラメータ

この関数にはパラメータはありません。


Send data to the remote TCP socket.

  • ≪ Swoole\Client::resume
  • Swoole\Client::sendfile ≫
  • PHP Manual
  • Swoole\Client
  • Send data to the remote TCP socket.

Swoole\Client::send

(PECL swoole >= 1.9.0)

Swoole\Client::send — Send data to the remote TCP socket.

説明

public Swoole\Client::send(string $data, string $flag = ?): int

パラメータ

data

The data to send which can be string or binary

flag

戻り値

If the client sends data successfully, it returns the length of data sent. Or it returns false and sets $swoole_client->errCode. For sync client, there is no limit for the data to send. For async client, The limit for the data to send is socket_buffer_size.


Send file to the remote TCP socket.

  • ≪ Swoole\Client::send
  • Swoole\Client::sendto ≫
  • PHP Manual
  • Swoole\Client
  • Send file to the remote TCP socket.

Swoole\Client::sendfile

(PECL swoole >= 1.9.0)

Swoole\Client::sendfile — Send file to the remote TCP socket.

説明

public Swoole\Client::sendfile(string $filename, int $offset = ?): bool

This is a wrapper of the Linux sendfile system call.

パラメータ

filename

File path of the file to send.

offset

Offset of the file to send

戻り値


Send data to the remote UDP address.

  • ≪ Swoole\Client::sendfile
  • Swoole\Client::set ≫
  • PHP Manual
  • Swoole\Client
  • Send data to the remote UDP address.

Swoole\Client::sendto

(PECL swoole >= 1.9.0)

Swoole\Client::sendto — Send data to the remote UDP address.

説明

public Swoole\Client::sendto(string $ip, int $port, string $data): bool

The swoole client should be type of SWOOLE_SOCK_UDP or SWOOLE_SOCK_UDP6.

パラメータ

ip

The IP address of remote host, IPv4 or IPv6.

port

The port number of remote host.

data

The data to send which should be less-than 64K.

戻り値


Set the Swoole client parameters before the connection is established.

  • ≪ Swoole\Client::sendto
  • Swoole\Client::sleep ≫
  • PHP Manual
  • Swoole\Client
  • Set the Swoole client parameters before the connection is established.

Swoole\Client::set

(PECL swoole >= 1.9.0)

Swoole\Client::set — Set the Swoole client parameters before the connection is established.

説明

public Swoole\Client::set(array $settings): void

パラメータ

settings

戻り値


Remove the TCP client from system event loop.

  • ≪ Swoole\Client::set
  • Swoole\Client::wakeup ≫
  • PHP Manual
  • Swoole\Client
  • Remove the TCP client from system event loop.

Swoole\Client::sleep

(PECL swoole >= 1.9.0)

Swoole\Client::sleep — Remove the TCP client from system event loop.

説明

public Swoole\Client::sleep(): void

Remove the TCP client from system event loop.

パラメータ

この関数にはパラメータはありません。

戻り値


Add the TCP client back into the system event loop.

  • ≪ Swoole\Client::sleep
  • Swoole\Connection\Iterator ≫
  • PHP Manual
  • Swoole\Client
  • Add the TCP client back into the system event loop.

Swoole\Client::wakeup

(PECL swoole >= 1.9.0)

Swoole\Client::wakeup — Add the TCP client back into the system event loop.

説明

public Swoole\Client::wakeup(): void

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Connection\Iterator class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Connection\Iterator implements Iterator, Countable, ArrayAccess {
/* メソッド */
public count(): int
public current(): Connection
public key(): int
public next(): Connection
public offsetExists(int $index): bool
public offsetGet(string $index): Connection
public offsetSet(int $offset, mixed $connection): void
public offsetUnset(int $offset): void
public rewind(): void
public valid(): bool
}

目次

  • Swoole\Connection\Iterator::count — Count connections.
  • Swoole\Connection\Iterator::current — Return current connection entry.
  • Swoole\Connection\Iterator::key — Return key of the current connection.
  • Swoole\Connection\Iterator::next — Move to the next connection.
  • Swoole\Connection\Iterator::offsetExists — Check if offet exists.
  • Swoole\Connection\Iterator::offsetGet — Offset to retrieve.
  • Swoole\Connection\Iterator::offsetSet — Assign a Connection to the specified offset.
  • Swoole\Connection\Iterator::offsetUnset — Unset an offset.
  • Swoole\Connection\Iterator::rewind — Rewinds iterator
  • Swoole\Connection\Iterator::valid — Check if current position is valid.


Count connections.

  • ≪ Swoole\Connection\Iterator
  • Swoole\Connection\Iterator::current ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Count connections.

Swoole\Connection\Iterator::count

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::count — Count connections.

説明

public Swoole\Connection\Iterator::count(): int

Gets the number of connections.

パラメータ

この関数にはパラメータはありません。

戻り値

The number of connections.


Return current connection entry.

  • ≪ Swoole\Connection\Iterator::count
  • Swoole\Connection\Iterator::key ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Return current connection entry.

Swoole\Connection\Iterator::current

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::current — Return current connection entry.

説明

public Swoole\Connection\Iterator::current(): Connection

Get current connection entry.

パラメータ

この関数にはパラメータはありません。

戻り値

The current connection entry.


Return key of the current connection.

  • ≪ Swoole\Connection\Iterator::current
  • Swoole\Connection\Iterator::next ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Return key of the current connection.

Swoole\Connection\Iterator::key

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::key — Return key of the current connection.

説明

public Swoole\Connection\Iterator::key(): int

This function returns key of the current connection.

パラメータ

この関数にはパラメータはありません。

戻り値

Key of the current connection.


Move to the next connection.

  • ≪ Swoole\Connection\Iterator::key
  • Swoole\Connection\Iterator::offsetExists ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Move to the next connection.

Swoole\Connection\Iterator::next

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::next — Move to the next connection.

説明

public Swoole\Connection\Iterator::next(): Connection

The iterator to the next connection.

パラメータ

この関数にはパラメータはありません。

戻り値


Check if offet exists.

  • ≪ Swoole\Connection\Iterator::next
  • Swoole\Connection\Iterator::offsetGet ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Check if offet exists.

Swoole\Connection\Iterator::offsetExists

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetExists — Check if offet exists.

説明

public Swoole\Connection\Iterator::offsetExists(int $index): bool

Check if offset exists.

パラメータ

index

The offset being checked.

戻り値

Returns TRUE if the offset exists, otherwise FALSE.


Offset to retrieve.

  • ≪ Swoole\Connection\Iterator::offsetExists
  • Swoole\Connection\Iterator::offsetSet ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Offset to retrieve.

Swoole\Connection\Iterator::offsetGet

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetGet — Offset to retrieve.

説明

public Swoole\Connection\Iterator::offsetGet(string $index): Connection

Return the connection at specified offset.

パラメータ

index

The offset to retrieve.

戻り値


Assign a Connection to the specified offset.

  • ≪ Swoole\Connection\Iterator::offsetGet
  • Swoole\Connection\Iterator::offsetUnset ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Assign a Connection to the specified offset.

Swoole\Connection\Iterator::offsetSet

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetSet — Assign a Connection to the specified offset.

説明

public Swoole\Connection\Iterator::offsetSet(int $offset, mixed $connection): void

Assign a Connection to the specified offset.

パラメータ

offset

The offset to assign the Connection to.

connection

The connection to set.

戻り値


Unset an offset.

  • ≪ Swoole\Connection\Iterator::offsetSet
  • Swoole\Connection\Iterator::rewind ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Unset an offset.

Swoole\Connection\Iterator::offsetUnset

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::offsetUnset — Unset an offset.

説明

public Swoole\Connection\Iterator::offsetUnset(int $offset): void

Unsets an offset.

パラメータ

offset

The offset to unset.

戻り値


Rewinds iterator

  • ≪ Swoole\Connection\Iterator::offsetUnset
  • Swoole\Connection\Iterator::valid ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Rewinds iterator

Swoole\Connection\Iterator::rewind

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::rewind — Rewinds iterator

説明

public Swoole\Connection\Iterator::rewind(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Check if current position is valid.

  • ≪ Swoole\Connection\Iterator::rewind
  • Swoole\Coroutine ≫
  • PHP Manual
  • Swoole\Connection\Iterator
  • Check if current position is valid.

Swoole\Connection\Iterator::valid

(PECL swoole >= 1.9.0)

Swoole\Connection\Iterator::valid — Check if current position is valid.

説明

public Swoole\Connection\Iterator::valid(): bool

Checks if the current position is valid.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns TRUE if the current iterator position is valid, otherwise FALSE.


The Swoole\Coroutine class

(PECL swoole >= 2.0.0)

はじめに

クラス概要

class Swoole\Coroutine {
/* メソッド */
public static call_user_func(callable $callback, mixed ...$args): mixed
public static call_user_func_array(callable $callback, array $param_array): mixed
public static cli_wait(): ReturnType
public static create(): ReturnType
public Swoole\Coroutine\Client::close(): ReturnType
public Swoole\Coroutine\Client::connect(): ReturnType
public Swoole\Coroutine\Client::__destruct(): ReturnType
public Swoole\Coroutine\Client::getpeername(): ReturnType
public Swoole\Coroutine\Client::getsockname(): ReturnType
public Swoole\Coroutine\Client::isConnected(): ReturnType
public Swoole\Coroutine\Client::recv(): ReturnType
public Swoole\Coroutine\Client::send(): ReturnType
public Swoole\Coroutine\Client::sendfile(): ReturnType
public Swoole\Coroutine\Client::sendto(): ReturnType
public Swoole\Coroutine\Client::set(): ReturnType
public Swoole\Coroutine\Http\Client::addFile(): ReturnType
public Swoole\Coroutine\Http\Client::close(): ReturnType
public Swoole\Coroutine\Http\Client::__destruct(): ReturnType
public Swoole\Coroutine\Http\Client::execute(): ReturnType
public Swoole\Coroutine\Http\Client::get(): ReturnType
public Swoole\Coroutine\Http\Client::getDefer(): ReturnType
public Swoole\Coroutine\Http\Client::isConnected(): ReturnType
public Swoole\Coroutine\Http\Client::post(): ReturnType
public Swoole\Coroutine\Http\Client::recv(): ReturnType
public Swoole\Coroutine\Http\Client::set(): ReturnType
public Swoole\Coroutine\Http\Client::setCookies(): ReturnType
public Swoole\Coroutine\Http\Client::setData(): ReturnType
public Swoole\Coroutine\Http\Client::setDefer(): ReturnType
public Swoole\Coroutine\Http\Client::setHeaders(): ReturnType
public Swoole\Coroutine\Http\Client::setMethod(): ReturnType
public Swoole\Coroutine\MySQL::close(): ReturnType
public Swoole\Coroutine\MySQL::connect(): ReturnType
public Swoole\Coroutine\MySQL::__destruct(): ReturnType
public Swoole\Coroutine\MySQL::getDefer(): ReturnType
public Swoole\Coroutine\MySQL::query(): ReturnType
public Swoole\Coroutine\MySQL::recv(): ReturnType
public Swoole\Coroutine\MySQL::setDefer(): ReturnType
public static getuid(): ReturnType
public static resume(): ReturnType
public static suspend(): ReturnType
}

目次

  • Swoole\Coroutine::call_user_func — Call a callback given by the first parameter
  • Swoole\Coroutine::call_user_func_array — Call a callback with an array of parameters
  • Swoole\Coroutine::cli_wait — Description
  • Swoole\Coroutine::create — Description
  • Swoole\Coroutine\Client::close — Description
  • Swoole\Coroutine\Client::connect — Description
  • Swoole\Coroutine\Client::__construct — Description
  • Swoole\Coroutine\Client::__destruct — Description
  • Swoole\Coroutine\Client::getpeername — Description
  • Swoole\Coroutine\Client::getsockname — Description
  • Swoole\Coroutine\Client::isConnected — Description
  • Swoole\Coroutine\Client::recv — Description
  • Swoole\Coroutine\Client::send — Description
  • Swoole\Coroutine\Client::sendfile — Description
  • Swoole\Coroutine\Client::sendto — Description
  • Swoole\Coroutine\Client::set — Description
  • Swoole\Coroutine\Http\Client::addFile — Description
  • Swoole\Coroutine\Http\Client::close — Description
  • Swoole\Coroutine\Http\Client::__construct — Description
  • Swoole\Coroutine\Http\Client::__destruct — Description
  • Swoole\Coroutine\Http\Client::execute — Description
  • Swoole\Coroutine\Http\Client::get — Description
  • Swoole\Coroutine\Http\Client::getDefer — Description
  • Swoole\Coroutine\Http\Client::isConnected — Description
  • Swoole\Coroutine\Http\Client::post — Description
  • Swoole\Coroutine\Http\Client::recv — Description
  • Swoole\Coroutine\Http\Client::set — Description
  • Swoole\Coroutine\Http\Client::setCookies — Description
  • Swoole\Coroutine\Http\Client::setData — Description
  • Swoole\Coroutine\Http\Client::setDefer — Description
  • Swoole\Coroutine\Http\Client::setHeaders — Description
  • Swoole\Coroutine\Http\Client::setMethod — Description
  • Swoole\Coroutine\MySQL::close — Description
  • Swoole\Coroutine\MySQL::connect — Description
  • Swoole\Coroutine\MySQL::__construct — Description
  • Swoole\Coroutine\MySQL::__destruct — Description
  • Swoole\Coroutine\MySQL::getDefer — Description
  • Swoole\Coroutine\MySQL::query — Description
  • Swoole\Coroutine\MySQL::recv — Description
  • Swoole\Coroutine\MySQL::setDefer — Description
  • Swoole\Coroutine::getuid — Description
  • Swoole\Coroutine::resume — Description
  • Swoole\Coroutine::suspend — Description


Call a callback given by the first parameter

  • ≪ Swoole\Coroutine
  • Swoole\Coroutine::call_user_func_array ≫
  • PHP Manual
  • Swoole\Coroutine
  • Call a callback given by the first parameter

Swoole\Coroutine::call_user_func

(PECL swoole >= 2.0.0)

Swoole\Coroutine::call_user_func — Call a callback given by the first parameter

説明

public static Swoole\Coroutine::call_user_func(callable $callback, mixed ...$args): mixed

Calls the callback given by the first parameter and passes the remaining parameters as arguments.

パラメータ

callback

The callable to be called.

args

Zero or more parameters to be passed to the callback.

戻り値


Call a callback with an array of parameters

  • ≪ Swoole\Coroutine::call_user_func
  • Swoole\Coroutine::cli_wait ≫
  • PHP Manual
  • Swoole\Coroutine
  • Call a callback with an array of parameters

Swoole\Coroutine::call_user_func_array

(PECL swoole >= 2.0.0)

Swoole\Coroutine::call_user_func_array — Call a callback with an array of parameters

説明

public static Swoole\Coroutine::call_user_func_array(callable $callback, array $param_array): mixed

Calls the callback given by the first parameter with the parameters in param_array.

パラメータ

callback

The callable to be called.

param_array

Zero or more parameters in the array to be passed to the callback.

戻り値


Description

  • ≪ Swoole\Coroutine::call_user_func_array
  • Swoole\Coroutine::create ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::cli_wait

(PECL swoole >= 2.0.0)

Swoole\Coroutine::cli_wait — Description

説明

public static Swoole\Coroutine::cli_wait(): ReturnType

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine::cli_wait
  • Swoole\Coroutine\Client::close ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::create

(PECL swoole >= 2.0.0)

Swoole\Coroutine::create — Description

説明

public static Swoole\Coroutine::create(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine::create
  • Swoole\Coroutine\Client::connect ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::close

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::close — Description

説明

public Swoole\Coroutine\Client::close(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::close
  • Swoole\Coroutine\Client::__construct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::connect

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::connect — Description

説明

public Swoole\Coroutine\Client::connect(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::connect
  • Swoole\Coroutine\Client::__destruct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::__construct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::__construct — Description

説明

public Swoole\Coroutine\Client::__construct()

パラメータ

この関数にはパラメータはありません。


Description

  • ≪ Swoole\Coroutine\Client::__construct
  • Swoole\Coroutine\Client::getpeername ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::__destruct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::__destruct — Description

説明

public Swoole\Coroutine\Client::__destruct(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::__destruct
  • Swoole\Coroutine\Client::getsockname ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::getpeername

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::getpeername — Description

説明

public Swoole\Coroutine\Client::getpeername(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::getpeername
  • Swoole\Coroutine\Client::isConnected ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::getsockname

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::getsockname — Description

説明

public Swoole\Coroutine\Client::getsockname(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::getsockname
  • Swoole\Coroutine\Client::recv ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::isConnected

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::isConnected — Description

説明

public Swoole\Coroutine\Client::isConnected(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::isConnected
  • Swoole\Coroutine\Client::send ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::recv

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::recv — Description

説明

public Swoole\Coroutine\Client::recv(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::recv
  • Swoole\Coroutine\Client::sendfile ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::send

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::send — Description

説明

public Swoole\Coroutine\Client::send(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::send
  • Swoole\Coroutine\Client::sendto ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::sendfile

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::sendfile — Description

説明

public Swoole\Coroutine\Client::sendfile(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::sendfile
  • Swoole\Coroutine\Client::set ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::sendto

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::sendto — Description

説明

public Swoole\Coroutine\Client::sendto(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::sendto
  • Swoole\Coroutine\Http\Client::addFile ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Client::set

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Client::set — Description

説明

public Swoole\Coroutine\Client::set(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Client::set
  • Swoole\Coroutine\Http\Client::close ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::addFile

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::addFile — Description

説明

public Swoole\Coroutine\Http\Client::addFile(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::addFile
  • Swoole\Coroutine\Http\Client::__construct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::close

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::close — Description

説明

public Swoole\Coroutine\Http\Client::close(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::close
  • Swoole\Coroutine\Http\Client::__destruct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::__construct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::__construct — Description

説明

public Swoole\Coroutine\Http\Client::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。


Description

  • ≪ Swoole\Coroutine\Http\Client::__construct
  • Swoole\Coroutine\Http\Client::execute ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::__destruct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::__destruct — Description

説明

public Swoole\Coroutine\Http\Client::__destruct(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::__destruct
  • Swoole\Coroutine\Http\Client::get ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::execute

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::execute — Description

説明

public Swoole\Coroutine\Http\Client::execute(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::execute
  • Swoole\Coroutine\Http\Client::getDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::get

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::get — Description

説明

public Swoole\Coroutine\Http\Client::get(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::get
  • Swoole\Coroutine\Http\Client::isConnected ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::getDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::getDefer — Description

説明

public Swoole\Coroutine\Http\Client::getDefer(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::getDefer
  • Swoole\Coroutine\Http\Client::post ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::isConnected

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::isConnected — Description

説明

public Swoole\Coroutine\Http\Client::isConnected(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::isConnected
  • Swoole\Coroutine\Http\Client::recv ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::post

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::post — Description

説明

public Swoole\Coroutine\Http\Client::post(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::post
  • Swoole\Coroutine\Http\Client::set ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::recv

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::recv — Description

説明

public Swoole\Coroutine\Http\Client::recv(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::recv
  • Swoole\Coroutine\Http\Client::setCookies ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::set

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::set — Description

説明

public Swoole\Coroutine\Http\Client::set(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::set
  • Swoole\Coroutine\Http\Client::setData ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setCookies

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setCookies — Description

説明

public Swoole\Coroutine\Http\Client::setCookies(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::setCookies
  • Swoole\Coroutine\Http\Client::setDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setData

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setData — Description

説明

public Swoole\Coroutine\Http\Client::setData(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::setData
  • Swoole\Coroutine\Http\Client::setHeaders ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setDefer — Description

説明

public Swoole\Coroutine\Http\Client::setDefer(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::setDefer
  • Swoole\Coroutine\Http\Client::setMethod ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setHeaders

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setHeaders — Description

説明

public Swoole\Coroutine\Http\Client::setHeaders(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::setHeaders
  • Swoole\Coroutine\MySQL::close ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\Http\Client::setMethod

(PECL swoole >= 2.0.0)

Swoole\Coroutine\Http\Client::setMethod — Description

説明

public Swoole\Coroutine\Http\Client::setMethod(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\Http\Client::setMethod
  • Swoole\Coroutine\MySQL::connect ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::close

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::close — Description

説明

public Swoole\Coroutine\MySQL::close(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::close
  • Swoole\Coroutine\MySQL::__construct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::connect

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::connect — Description

説明

public Swoole\Coroutine\MySQL::connect(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::connect
  • Swoole\Coroutine\MySQL::__destruct ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::__construct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::__construct — Description

説明

public Swoole\Coroutine\MySQL::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。


Description

  • ≪ Swoole\Coroutine\MySQL::__construct
  • Swoole\Coroutine\MySQL::getDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::__destruct

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::__destruct — Description

説明

public Swoole\Coroutine\MySQL::__destruct(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::__destruct
  • Swoole\Coroutine\MySQL::query ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::getDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::getDefer — Description

説明

public Swoole\Coroutine\MySQL::getDefer(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::getDefer
  • Swoole\Coroutine\MySQL::recv ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::query

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::query — Description

説明

public Swoole\Coroutine\MySQL::query(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::query
  • Swoole\Coroutine\MySQL::setDefer ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::recv

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::recv — Description

説明

public Swoole\Coroutine\MySQL::recv(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::recv
  • Swoole\Coroutine::getuid ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine\MySQL::setDefer

(PECL swoole >= 2.0.0)

Swoole\Coroutine\MySQL::setDefer — Description

説明

public Swoole\Coroutine\MySQL::setDefer(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine\MySQL::setDefer
  • Swoole\Coroutine::resume ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::getuid

(PECL swoole >= 2.0.0)

Swoole\Coroutine::getuid — Description

説明

public static Swoole\Coroutine::getuid(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine::getuid
  • Swoole\Coroutine::suspend ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::resume

(PECL swoole >= 2.0.0)

Swoole\Coroutine::resume — Description

説明

public static Swoole\Coroutine::resume(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\Coroutine::resume
  • Swoole\Event ≫
  • PHP Manual
  • Swoole\Coroutine
  • Description

Swoole\Coroutine::suspend

(PECL swoole >= 2.0.0)

Swoole\Coroutine::suspend — Description

説明

public static Swoole\Coroutine::suspend(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Event class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Event {
/* メソッド */
public static add(
int $fd,
callable $read_callback,
callable $write_callback = ?,
string $events = ?
): bool
public static defer(mixed $callback): void
public static del(string $fd): bool
public static exit(): void
public static set(
int $fd,
string $read_callback = ?,
string $write_callback = ?,
string $events = ?
): bool
public static wait(): void
public static write(string $fd, string $data): void
}

目次

  • Swoole\Event::add — Add new callback functions of a socket into the EventLoop.
  • Swoole\Event::defer — Add a callback function to the next event loop.
  • Swoole\Event::del — Remove all event callback functions of a socket.
  • Swoole\Event::exit — Exit the eventloop, only available at client side.
  • Swoole\Event::set — Update the event callback functions of a socket.
  • Swoole\Event::wait — Description
  • Swoole\Event::write — Write data to the socket.


Add new callback functions of a socket into the EventLoop.

  • ≪ Swoole\Event
  • Swoole\Event::defer ≫
  • PHP Manual
  • Swoole\Event
  • Add new callback functions of a socket into the EventLoop.

Swoole\Event::add

(PECL swoole >= 1.9.0)

Swoole\Event::add — Add new callback functions of a socket into the EventLoop.

説明

public static Swoole\Event::add(
int $fd,
callable $read_callback,
callable $write_callback = ?,
string $events = ?
): bool

パラメータ

fd

read_callback

write_callback

events

戻り値


Add a callback function to the next event loop.

  • ≪ Swoole\Event::add
  • Swoole\Event::del ≫
  • PHP Manual
  • Swoole\Event
  • Add a callback function to the next event loop.

Swoole\Event::defer

(PECL swoole >= 1.9.0)

Swoole\Event::defer — Add a callback function to the next event loop.

説明

public static Swoole\Event::defer(mixed $callback): void

パラメータ

callback

戻り値


Remove all event callback functions of a socket.

  • ≪ Swoole\Event::defer
  • Swoole\Event::exit ≫
  • PHP Manual
  • Swoole\Event
  • Remove all event callback functions of a socket.

Swoole\Event::del

(PECL swoole >= 1.9.0)

Swoole\Event::del — Remove all event callback functions of a socket.

説明

public static Swoole\Event::del(string $fd): bool

パラメータ

fd

戻り値


Exit the eventloop, only available at client side.

  • ≪ Swoole\Event::del
  • Swoole\Event::set ≫
  • PHP Manual
  • Swoole\Event
  • Exit the eventloop, only available at client side.

Swoole\Event::exit

(PECL swoole >= 1.9.0)

Swoole\Event::exit — Exit the eventloop, only available at client side.

説明

public static Swoole\Event::exit(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Update the event callback functions of a socket.

  • ≪ Swoole\Event::exit
  • Swoole\Event::wait ≫
  • PHP Manual
  • Swoole\Event
  • Update the event callback functions of a socket.

Swoole\Event::set

(PECL swoole >= 1.9.0)

Swoole\Event::set — Update the event callback functions of a socket.

説明

public static Swoole\Event::set(
int $fd,
string $read_callback = ?,
string $write_callback = ?,
string $events = ?
): bool

パラメータ

fd

read_callback

write_callback

events

戻り値


Description

  • ≪ Swoole\Event::set
  • Swoole\Event::write ≫
  • PHP Manual
  • Swoole\Event
  • Description

Swoole\Event::wait

(PECL swoole >= 1.9.0)

Swoole\Event::wait — Description

説明

public static Swoole\Event::wait(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Write data to the socket.

  • ≪ Swoole\Event::wait
  • Swoole\Exception ≫
  • PHP Manual
  • Swoole\Event
  • Write data to the socket.

Swoole\Event::write

(PECL swoole >= 1.9.0)

Swoole\Event::write — Write data to the socket.

説明

public static Swoole\Event::write(string $fd, string $data): void

パラメータ

fd

data

戻り値


The Swoole\Exception class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Exception extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
}


The Swoole\Http\Client class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Http\Client {
/* プロパティ */
public $errCode;
public $sock;
/* メソッド */
public addFile(
string $path,
string $name,
string $type = ?,
string $filename = ?,
string $offset = ?
): void
public close(): void
public __destruct(): void
public download(
string $path,
string $file,
callable $callback,
int $offset = ?
): void
public execute(string $path, string $callback): void
public get(string $path, callable $callback): void
public isConnected(): bool
public on(string $event_name, callable $callback): void
public post(string $path, string $data, callable $callback): void
public push(string $data, string $opcode = ?, string $finish = ?): void
public set(array $settings): void
public setCookies(array $cookies): void
public setData(string $data): ReturnType
public setHeaders(array $headers): void
public setMethod(string $method): void
public upgrade(string $path, string $callback): void
}

プロパティ

errCode

sock

目次

  • Swoole\Http\Client::addFile — Add a file to the post form.
  • Swoole\Http\Client::close — Close the http connection.
  • Swoole\Http\Client::__construct — Construct the async HTTP client.
  • Swoole\Http\Client::__destruct — Destruct the HTTP client.
  • Swoole\Http\Client::download — Download a file from the remote server.
  • Swoole\Http\Client::execute — Send the HTTP request after setting the parameters.
  • Swoole\Http\Client::get — Send GET http request to the remote server.
  • Swoole\Http\Client::isConnected — Check if the HTTP connection is connected.
  • Swoole\Http\Client::on — Register callback function by event name.
  • Swoole\Http\Client::post — Send POST http request to the remote server.
  • Swoole\Http\Client::push — Push data to websocket client.
  • Swoole\Http\Client::set — Update the HTTP client parameters.
  • Swoole\Http\Client::setCookies — Set the http request cookies.
  • Swoole\Http\Client::setData — Set the HTTP request body data.
  • Swoole\Http\Client::setHeaders — Set the HTTP request headers.
  • Swoole\Http\Client::setMethod — Set the HTTP request method.
  • Swoole\Http\Client::upgrade — Upgrade to websocket protocol.


Add a file to the post form.

  • ≪ Swoole\Http\Client
  • Swoole\Http\Client::close ≫
  • PHP Manual
  • Swoole\Http\Client
  • Add a file to the post form.

Swoole\Http\Client::addFile

(PECL swoole >= 1.9.0)

Swoole\Http\Client::addFile — Add a file to the post form.

説明

public Swoole\Http\Client::addFile(
string $path,
string $name,
string $type = ?,
string $filename = ?,
string $offset = ?
): void

パラメータ

path

name

type

filename

offset

戻り値


Close the http connection.

  • ≪ Swoole\Http\Client::addFile
  • Swoole\Http\Client::__construct ≫
  • PHP Manual
  • Swoole\Http\Client
  • Close the http connection.

Swoole\Http\Client::close

(PECL swoole >= 1.9.0)

Swoole\Http\Client::close — Close the http connection.

説明

public Swoole\Http\Client::close(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Construct the async HTTP client.

  • ≪ Swoole\Http\Client::close
  • Swoole\Http\Client::__destruct ≫
  • PHP Manual
  • Swoole\Http\Client
  • Construct the async HTTP client.

Swoole\Http\Client::__construct

(PECL swoole >= 1.9.0)

Swoole\Http\Client::__construct — Construct the async HTTP client.

説明

public Swoole\Http\Client::__construct(string $host, string $port = ?, bool $ssl = ?)

パラメータ

host

The hostname of the remote host.

port

The port number of the remote host.

ssl

Whether to enable SSL.


Destruct the HTTP client.

  • ≪ Swoole\Http\Client::__construct
  • Swoole\Http\Client::download ≫
  • PHP Manual
  • Swoole\Http\Client
  • Destruct the HTTP client.

Swoole\Http\Client::__destruct

(PECL swoole >= 1.9.0)

Swoole\Http\Client::__destruct — Destruct the HTTP client.

説明

public Swoole\Http\Client::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Download a file from the remote server.

  • ≪ Swoole\Http\Client::__destruct
  • Swoole\Http\Client::execute ≫
  • PHP Manual
  • Swoole\Http\Client
  • Download a file from the remote server.

Swoole\Http\Client::download

(PECL swoole >= 1.9.0)

Swoole\Http\Client::download — Download a file from the remote server.

説明

public Swoole\Http\Client::download(
string $path,
string $file,
callable $callback,
int $offset = ?
): void

パラメータ

path

file

callback

offset

戻り値


Send the HTTP request after setting the parameters.

  • ≪ Swoole\Http\Client::download
  • Swoole\Http\Client::get ≫
  • PHP Manual
  • Swoole\Http\Client
  • Send the HTTP request after setting the parameters.

Swoole\Http\Client::execute

(PECL swoole >= 1.9.0)

Swoole\Http\Client::execute — Send the HTTP request after setting the parameters.

説明

public Swoole\Http\Client::execute(string $path, string $callback): void

パラメータ

path

callback

戻り値


Send GET http request to the remote server.

  • ≪ Swoole\Http\Client::execute
  • Swoole\Http\Client::isConnected ≫
  • PHP Manual
  • Swoole\Http\Client
  • Send GET http request to the remote server.

Swoole\Http\Client::get

(PECL swoole >= 1.9.0)

Swoole\Http\Client::get — Send GET http request to the remote server.

説明

public Swoole\Http\Client::get(string $path, callable $callback): void

パラメータ

path

callback

戻り値


Check if the HTTP connection is connected.

  • ≪ Swoole\Http\Client::get
  • Swoole\Http\Client::on ≫
  • PHP Manual
  • Swoole\Http\Client
  • Check if the HTTP connection is connected.

Swoole\Http\Client::isConnected

(PECL swoole >= 1.9.0)

Swoole\Http\Client::isConnected — Check if the HTTP connection is connected.

説明

public Swoole\Http\Client::isConnected(): bool

パラメータ

この関数にはパラメータはありません。

戻り値


Register callback function by event name.

  • ≪ Swoole\Http\Client::isConnected
  • Swoole\Http\Client::post ≫
  • PHP Manual
  • Swoole\Http\Client
  • Register callback function by event name.

Swoole\Http\Client::on

(PECL swoole >= 1.9.0)

Swoole\Http\Client::on — Register callback function by event name.

説明

public Swoole\Http\Client::on(string $event_name, callable $callback): void

パラメータ

event_name

callback

戻り値


Send POST http request to the remote server.

  • ≪ Swoole\Http\Client::on
  • Swoole\Http\Client::push ≫
  • PHP Manual
  • Swoole\Http\Client
  • Send POST http request to the remote server.

Swoole\Http\Client::post

(PECL swoole >= 1.9.0)

Swoole\Http\Client::post — Send POST http request to the remote server.

説明

public Swoole\Http\Client::post(string $path, string $data, callable $callback): void

パラメータ

path

data

callback

戻り値


Push data to websocket client.

  • ≪ Swoole\Http\Client::post
  • Swoole\Http\Client::set ≫
  • PHP Manual
  • Swoole\Http\Client
  • Push data to websocket client.

Swoole\Http\Client::push

(PECL swoole >= 1.9.0)

Swoole\Http\Client::push — Push data to websocket client.

説明

public Swoole\Http\Client::push(string $data, string $opcode = ?, string $finish = ?): void

パラメータ

data

opcode

finish

戻り値


Update the HTTP client parameters.

  • ≪ Swoole\Http\Client::push
  • Swoole\Http\Client::setCookies ≫
  • PHP Manual
  • Swoole\Http\Client
  • Update the HTTP client parameters.

Swoole\Http\Client::set

(PECL swoole >= 1.9.0)

Swoole\Http\Client::set — Update the HTTP client parameters.

説明

public Swoole\Http\Client::set(array $settings): void

パラメータ

settings

戻り値


Set the http request cookies.

  • ≪ Swoole\Http\Client::set
  • Swoole\Http\Client::setData ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the http request cookies.

Swoole\Http\Client::setCookies

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setCookies — Set the http request cookies.

説明

public Swoole\Http\Client::setCookies(array $cookies): void

パラメータ

cookies

戻り値


Set the HTTP request body data.

  • ≪ Swoole\Http\Client::setCookies
  • Swoole\Http\Client::setHeaders ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the HTTP request body data.

Swoole\Http\Client::setData

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setData — Set the HTTP request body data.

説明

public Swoole\Http\Client::setData(string $data): ReturnType

The HTTP method will be changed to be POST.

パラメータ

data

戻り値


Set the HTTP request headers.

  • ≪ Swoole\Http\Client::setData
  • Swoole\Http\Client::setMethod ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the HTTP request headers.

Swoole\Http\Client::setHeaders

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setHeaders — Set the HTTP request headers.

説明

public Swoole\Http\Client::setHeaders(array $headers): void

パラメータ

headers

戻り値


Set the HTTP request method.

  • ≪ Swoole\Http\Client::setHeaders
  • Swoole\Http\Client::upgrade ≫
  • PHP Manual
  • Swoole\Http\Client
  • Set the HTTP request method.

Swoole\Http\Client::setMethod

(PECL swoole >= 1.9.0)

Swoole\Http\Client::setMethod — Set the HTTP request method.

説明

public Swoole\Http\Client::setMethod(string $method): void

パラメータ

method

戻り値


Upgrade to websocket protocol.

  • ≪ Swoole\Http\Client::setMethod
  • Swoole\Http\Request ≫
  • PHP Manual
  • Swoole\Http\Client
  • Upgrade to websocket protocol.

Swoole\Http\Client::upgrade

(PECL swoole >= 1.9.0)

Swoole\Http\Client::upgrade — Upgrade to websocket protocol.

説明

public Swoole\Http\Client::upgrade(string $path, string $callback): void

パラメータ

path

callback

戻り値


The Swoole\Http\Request class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Http\Request {
/* メソッド */
public __destruct(): void
public rawcontent(): string
}

目次

  • Swoole\Http\Request::__destruct — Destruct the HTTP request.
  • Swoole\Http\Request::rawcontent — Get the raw HTTP POST body.


Destruct the HTTP request.

  • ≪ Swoole\Http\Request
  • Swoole\Http\Request::rawcontent ≫
  • PHP Manual
  • Swoole\Http\Request
  • Destruct the HTTP request.

Swoole\Http\Request::__destruct

(PECL swoole >= 1.9.0)

Swoole\Http\Request::__destruct — Destruct the HTTP request.

説明

public Swoole\Http\Request::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Get the raw HTTP POST body.

  • ≪ Swoole\Http\Request::__destruct
  • Swoole\Http\Response ≫
  • PHP Manual
  • Swoole\Http\Request
  • Get the raw HTTP POST body.

Swoole\Http\Request::rawcontent

(PECL swoole >= 1.9.0)

Swoole\Http\Request::rawcontent — Get the raw HTTP POST body.

説明

public Swoole\Http\Request::rawcontent(): string

This method is used for the POST data which isn't in the form of `application/x-www-form-urlencoded`.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Http\Response class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Http\Response {
/* メソッド */
public cookie(
string $name,
string $value = ?,
string $expires = ?,
string $path = ?,
string $domain = ?,
string $secure = ?,
string $httponly = ?
): string
public __destruct(): void
public end(string $content = ?): void
public gzip(string $compress_level = ?): ReturnType
public header(string $key, string $value, string $ucwords = ?): void
public initHeader(): ReturnType
public rawcookie(
string $name,
string $value = ?,
string $expires = ?,
string $path = ?,
string $domain = ?,
string $secure = ?,
string $httponly = ?
): ReturnType
public sendfile(string $filename, int $offset = ?): ReturnType
public status(string $http_code): ReturnType
public write(string $content): void
}

目次

  • Swoole\Http\Response::cookie — Set the cookies of the HTTP response.
  • Swoole\Http\Response::__destruct — Destruct the HTTP response.
  • Swoole\Http\Response::end — Send data for the HTTP request and finish the response.
  • Swoole\Http\Response::gzip — Enable the gzip of response content.
  • Swoole\Http\Response::header — Set the HTTP response headers.
  • Swoole\Http\Response::initHeader — Init the HTTP response header.
  • Swoole\Http\Response::rawcookie — Set the raw cookies to the HTTP response.
  • Swoole\Http\Response::sendfile — Send file through the HTTP response.
  • Swoole\Http\Response::status — Set the status code of the HTTP response.
  • Swoole\Http\Response::write — Append HTTP body content to the HTTP response.


Set the cookies of the HTTP response.

  • ≪ Swoole\Http\Response
  • Swoole\Http\Response::__destruct ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the cookies of the HTTP response.

Swoole\Http\Response::cookie

(PECL swoole >= 1.9.0)

Swoole\Http\Response::cookie — Set the cookies of the HTTP response.

説明

public Swoole\Http\Response::cookie(
string $name,
string $value = ?,
string $expires = ?,
string $path = ?,
string $domain = ?,
string $secure = ?,
string $httponly = ?
): string

パラメータ

name

value

expires

path

domain

secure

httponly

戻り値


Destruct the HTTP response.

  • ≪ Swoole\Http\Response::cookie
  • Swoole\Http\Response::end ≫
  • PHP Manual
  • Swoole\Http\Response
  • Destruct the HTTP response.

Swoole\Http\Response::__destruct

(PECL swoole >= 1.9.0)

Swoole\Http\Response::__destruct — Destruct the HTTP response.

説明

public Swoole\Http\Response::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Send data for the HTTP request and finish the response.

  • ≪ Swoole\Http\Response::__destruct
  • Swoole\Http\Response::gzip ≫
  • PHP Manual
  • Swoole\Http\Response
  • Send data for the HTTP request and finish the response.

Swoole\Http\Response::end

(PECL swoole >= 1.9.0)

Swoole\Http\Response::end — Send data for the HTTP request and finish the response.

説明

public Swoole\Http\Response::end(string $content = ?): void

パラメータ

content

戻り値


Enable the gzip of response content.

  • ≪ Swoole\Http\Response::end
  • Swoole\Http\Response::header ≫
  • PHP Manual
  • Swoole\Http\Response
  • Enable the gzip of response content.

Swoole\Http\Response::gzip

(PECL swoole >= 1.9.0)

Swoole\Http\Response::gzip — Enable the gzip of response content.

説明

public Swoole\Http\Response::gzip(string $compress_level = ?): ReturnType

The header about Content-Encoding will be added automatically.

パラメータ

compress_level

戻り値


Set the HTTP response headers.

  • ≪ Swoole\Http\Response::gzip
  • Swoole\Http\Response::initHeader ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the HTTP response headers.

Swoole\Http\Response::header

(PECL swoole >= 1.9.0)

Swoole\Http\Response::header — Set the HTTP response headers.

説明

public Swoole\Http\Response::header(string $key, string $value, string $ucwords = ?): void

パラメータ

key

value

ucwords

戻り値


Init the HTTP response header.

  • ≪ Swoole\Http\Response::header
  • Swoole\Http\Response::rawcookie ≫
  • PHP Manual
  • Swoole\Http\Response
  • Init the HTTP response header.

Swoole\Http\Response::initHeader

(PECL swoole >= 1.9.0)

Swoole\Http\Response::initHeader — Init the HTTP response header.

説明

public Swoole\Http\Response::initHeader(): ReturnType

Init the HTTP response header.

パラメータ

この関数にはパラメータはありません。

戻り値


Set the raw cookies to the HTTP response.

  • ≪ Swoole\Http\Response::initHeader
  • Swoole\Http\Response::sendfile ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the raw cookies to the HTTP response.

Swoole\Http\Response::rawcookie

(PECL swoole >= 1.9.0)

Swoole\Http\Response::rawcookie — Set the raw cookies to the HTTP response.

説明

public Swoole\Http\Response::rawcookie(
string $name,
string $value = ?,
string $expires = ?,
string $path = ?,
string $domain = ?,
string $secure = ?,
string $httponly = ?
): ReturnType

パラメータ

name

value

expires

path

domain

secure

httponly

戻り値


Send file through the HTTP response.

  • ≪ Swoole\Http\Response::rawcookie
  • Swoole\Http\Response::status ≫
  • PHP Manual
  • Swoole\Http\Response
  • Send file through the HTTP response.

Swoole\Http\Response::sendfile

(PECL swoole >= 1.9.0)

Swoole\Http\Response::sendfile — Send file through the HTTP response.

説明

public Swoole\Http\Response::sendfile(string $filename, int $offset = ?): ReturnType

Send file through the HTTP response.

パラメータ

filename

offset

戻り値


Set the status code of the HTTP response.

  • ≪ Swoole\Http\Response::sendfile
  • Swoole\Http\Response::write ≫
  • PHP Manual
  • Swoole\Http\Response
  • Set the status code of the HTTP response.

Swoole\Http\Response::status

(PECL swoole >= 1.9.0)

Swoole\Http\Response::status — Set the status code of the HTTP response.

説明

public Swoole\Http\Response::status(string $http_code): ReturnType

Set the status code of the HTTP response.

パラメータ

http_code

戻り値


Append HTTP body content to the HTTP response.

  • ≪ Swoole\Http\Response::status
  • Swoole\Http\Server ≫
  • PHP Manual
  • Swoole\Http\Response
  • Append HTTP body content to the HTTP response.

Swoole\Http\Response::write

(PECL swoole >= 1.9.0)

Swoole\Http\Response::write — Append HTTP body content to the HTTP response.

説明

public Swoole\Http\Response::write(string $content): void

Append HTTP body content to the HTTP response.

パラメータ

content

戻り値


The Swoole\Http\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Http\Server extends Swoole\Server {
/* メソッド */
public on(string $event_name, callable $callback): void
public start(): void
/* 継承したメソッド */
public Swoole\Server::addlistener(string $host, int $port, string $socket_type): void
public Swoole\Server::addProcess(swoole_process $process): bool
public Swoole\Server::after(int $after_time_ms, callable $callback, string $param = ?): ReturnType
public Swoole\Server::bind(int $fd, int $uid): bool
public Swoole\Server::clearTimer(int $timer_id): void
swoole_timer_clear(int $timer_id): void
public Swoole\Server::close(int $fd, bool $reset = ?): bool
public Swoole\Server::confirm(int $fd): bool
public Swoole\Server::connection_info(int $fd, int $reactor_id = ?): array
public Swoole\Server::connection_list(int $start_fd, int $pagesize = ?): array
public Swoole\Server::defer(callable $callback): void
public Swoole\Server\Port::__destruct(): void
public Swoole\Server\Port::on(string $event_name, callable $callback): ReturnType
public Swoole\Server\Port::set(array $settings): void
public Swoole\Server::exist(int $fd): bool
public Swoole\Server::finish(string $data): void
public Swoole\Server::getClientInfo(int $fd, int $reactor_id = ?, bool $ignore_error = ?): array
public Swoole\Server::getClientList(int $start_fd, int $pagesize = ?): array
public Swoole\Server::getLastError(): int
public Swoole\Server::heartbeat(bool $if_close_connection): mixed
public Swoole\Server::listen(string $host, int $port, string $socket_type): bool
public Swoole\Server::on(string $event_name, callable $callback): void
public Swoole\Server::pause(int $fd): void
public Swoole\Server::protect(int $fd, bool $is_protected = ?): void
public Swoole\Server::reload(): bool
public Swoole\Server::resume(int $fd): void
public Swoole\Server::send(int $fd, string $data, int $reactor_id = ?): bool
public Swoole\Server::sendfile(int $fd, string $filename, int $offset = ?): bool
public Swoole\Server::sendMessage(int $worker_id, string $data): bool
public Swoole\Server::sendto(
string $ip,
int $port,
string $data,
string $server_socket = ?
): bool
public Swoole\Server::sendwait(int $fd, string $data): bool
public Swoole\Server::set(array $settings): ReturnType
public Swoole\Server::shutdown(): void
public Swoole\Server::start(): void
public Swoole\Server::stats(): array
public Swoole\Server::stop(int $worker_id = ?): bool
public Swoole\Server::task(string $data, int $dst_worker_id = ?, callable $callback = ?): mixed
public Swoole\Server::taskwait(string $data, float $timeout = ?, int $worker_id = ?): void
public Swoole\Server::taskWaitMulti(array $tasks, float $timeout_ms = ?): void
public Swoole\Server::tick(int $interval_ms, callable $callback): void
}

目次

  • Swoole\Http\Server::on — Bind callback function to HTTP server by event name.
  • Swoole\Http\Server::start — Start the swoole http server.


Bind callback function to HTTP server by event name.

  • ≪ Swoole\Http\Server
  • Swoole\Http\Server::start ≫
  • PHP Manual
  • Swoole\Http\Server
  • Bind callback function to HTTP server by event name.

Swoole\Http\Server::on

(PECL swoole >= 1.9.0)

Swoole\Http\Server::on — Bind callback function to HTTP server by event name.

説明

public Swoole\Http\Server::on(string $event_name, callable $callback): void

Bind callback function to HTTP server by event name.

パラメータ

event_name

callback

戻り値


Start the swoole http server.

  • ≪ Swoole\Http\Server::on
  • Swoole\Lock ≫
  • PHP Manual
  • Swoole\Http\Server
  • Start the swoole http server.

Swoole\Http\Server::start

(PECL swoole >= 1.9.0)

Swoole\Http\Server::start — Start the swoole http server.

説明

public Swoole\Http\Server::start(): void

Start the swoole http server.

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Lock class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Lock {
/* メソッド */
public __destruct(): void
public lock(): void
public lock_read(): void
public trylock(): void
public trylock_read(): void
public unlock(): void
}

目次

  • Swoole\Lock::__construct — Construct a memory lock.
  • Swoole\Lock::__destruct — Destory a Swoole memory lock.
  • Swoole\Lock::lock — Try to acquire the lock. It will block if the lock is not available.
  • Swoole\Lock::lock_read — Lock a read-write lock for reading.
  • Swoole\Lock::trylock — Try to acquire the lock and return straight away even the lock is not available.
  • Swoole\Lock::trylock_read — Try to lock a read-write lock for reading and return straight away even the lock is not available.
  • Swoole\Lock::unlock — Release the lock.


Construct a memory lock.

  • ≪ Swoole\Lock
  • Swoole\Lock::__destruct ≫
  • PHP Manual
  • Swoole\Lock
  • Construct a memory lock.

Swoole\Lock::__construct

(PECL swoole >= 1.9.0)

Swoole\Lock::__construct — Construct a memory lock.

説明

public Swoole\Lock::__construct(string $type = ?, string $file_lock_location = ?)

Swoole lock is used for data synchronization between multiple theads or processes.

パラメータ

type

file_lock_location


Destory a Swoole memory lock.

  • ≪ Swoole\Lock::__construct
  • Swoole\Lock::lock ≫
  • PHP Manual
  • Swoole\Lock
  • Destory a Swoole memory lock.

Swoole\Lock::__destruct

(PECL swoole >= 1.9.0)

Swoole\Lock::__destruct — Destory a Swoole memory lock.

説明

public Swoole\Lock::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Try to acquire the lock. It will block if the lock is not available.

  • ≪ Swoole\Lock::__destruct
  • Swoole\Lock::lock_read ≫
  • PHP Manual
  • Swoole\Lock
  • Try to acquire the lock. It will block if the lock is not available.

Swoole\Lock::lock

(PECL swoole >= 1.9.0)

Swoole\Lock::lock — Try to acquire the lock. It will block if the lock is not available.

説明

public Swoole\Lock::lock(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Lock a read-write lock for reading.

  • ≪ Swoole\Lock::lock
  • Swoole\Lock::trylock ≫
  • PHP Manual
  • Swoole\Lock
  • Lock a read-write lock for reading.

Swoole\Lock::lock_read

(PECL swoole >= 1.9.0)

Swoole\Lock::lock_read — Lock a read-write lock for reading.

説明

public Swoole\Lock::lock_read(): void

Lock a read-write lock for reading.

パラメータ

この関数にはパラメータはありません。

戻り値


Try to acquire the lock and return straight away even the lock is not available.

  • ≪ Swoole\Lock::lock_read
  • Swoole\Lock::trylock_read ≫
  • PHP Manual
  • Swoole\Lock
  • Try to acquire the lock and return straight away even the lock is not available.

Swoole\Lock::trylock

(PECL swoole >= 1.9.0)

Swoole\Lock::trylock — Try to acquire the lock and return straight away even the lock is not available.

説明

public Swoole\Lock::trylock(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Try to lock a read-write lock for reading and return straight away even the lock is not available.

  • ≪ Swoole\Lock::trylock
  • Swoole\Lock::unlock ≫
  • PHP Manual
  • Swoole\Lock
  • Try to lock a read-write lock for reading and return straight away even the lock is not available.

Swoole\Lock::trylock_read

(PECL swoole >= 1.9.0)

Swoole\Lock::trylock_read — Try to lock a read-write lock for reading and return straight away even the lock is not available.

説明

public Swoole\Lock::trylock_read(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Release the lock.

  • ≪ Swoole\Lock::trylock_read
  • Swoole\Mmap ≫
  • PHP Manual
  • Swoole\Lock
  • Release the lock.

Swoole\Lock::unlock

(PECL swoole >= 1.9.0)

Swoole\Lock::unlock — Release the lock.

説明

public Swoole\Lock::unlock(): void

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Mmap class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Mmap {
/* メソッド */
public static open(string $filename, string $size = ?, string $offset = ?): ReturnType
}

目次

  • Swoole\Mmap::open — Map a file into memory and return the stream resource which can be used by PHP stream operations.


Map a file into memory and return the stream resource which can be used by PHP stream operations.

  • ≪ Swoole\Mmap
  • Swoole\MySQL ≫
  • PHP Manual
  • Swoole\Mmap
  • Map a file into memory and return the stream resource which can be used by PHP stream operations.

Swoole\Mmap::open

(PECL swoole >= 1.9.0)

Swoole\Mmap::open — Map a file into memory and return the stream resource which can be used by PHP stream operations.

説明

public static Swoole\Mmap::open(string $filename, string $size = ?, string $offset = ?): ReturnType

パラメータ

filename

size

offset

戻り値


The Swoole\MySQL class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\MySQL {
/* メソッド */
public close(): void
public connect(array $server_config, callable $callback): void
public __destruct(): void
public getBuffer(): ReturnType
public on(string $event_name, callable $callback): void
public query(string $sql, callable $callback): ReturnType
}

目次

  • Swoole\MySQL::close — Close the async MySQL connection.
  • Swoole\MySQL::connect — Connect to the remote MySQL server.
  • Swoole\MySQL::__construct — Construct an async MySQL client.
  • Swoole\MySQL::__destruct — Destory the async MySQL client.
  • Swoole\MySQL::getBuffer — Description
  • Swoole\MySQL::on — Register callback function based on event name.
  • Swoole\MySQL::query — Run the SQL query.


Close the async MySQL connection.

  • ≪ Swoole\MySQL
  • Swoole\MySQL::connect ≫
  • PHP Manual
  • Swoole\MySQL
  • Close the async MySQL connection.

Swoole\MySQL::close

(PECL swoole >= 1.9.0)

Swoole\MySQL::close — Close the async MySQL connection.

説明

public Swoole\MySQL::close(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Connect to the remote MySQL server.

  • ≪ Swoole\MySQL::close
  • Swoole\MySQL::__construct ≫
  • PHP Manual
  • Swoole\MySQL
  • Connect to the remote MySQL server.

Swoole\MySQL::connect

(PECL swoole >= 1.9.0)

Swoole\MySQL::connect — Connect to the remote MySQL server.

説明

public Swoole\MySQL::connect(array $server_config, callable $callback): void

Connect to the remote MySQL server.

パラメータ

server_config

callback

戻り値


Construct an async MySQL client.

  • ≪ Swoole\MySQL::connect
  • Swoole\MySQL::__destruct ≫
  • PHP Manual
  • Swoole\MySQL
  • Construct an async MySQL client.

Swoole\MySQL::__construct

(PECL swoole >= 1.9.0)

Swoole\MySQL::__construct — Construct an async MySQL client.

説明

public Swoole\MySQL::__construct()

Construct an async MySQL client.

パラメータ

この関数にはパラメータはありません。


Destory the async MySQL client.

  • ≪ Swoole\MySQL::__construct
  • Swoole\MySQL::getBuffer ≫
  • PHP Manual
  • Swoole\MySQL
  • Destory the async MySQL client.

Swoole\MySQL::__destruct

(PECL swoole >= 1.9.0)

Swoole\MySQL::__destruct — Destory the async MySQL client.

説明

public Swoole\MySQL::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Description

  • ≪ Swoole\MySQL::__destruct
  • Swoole\MySQL::on ≫
  • PHP Manual
  • Swoole\MySQL
  • Description

Swoole\MySQL::getBuffer

(PECL swoole >= 1.9.0)

Swoole\MySQL::getBuffer — Description

説明

public Swoole\MySQL::getBuffer(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Register callback function based on event name.

  • ≪ Swoole\MySQL::getBuffer
  • Swoole\MySQL::query ≫
  • PHP Manual
  • Swoole\MySQL
  • Register callback function based on event name.

Swoole\MySQL::on

(PECL swoole >= 1.9.0)

Swoole\MySQL::on — Register callback function based on event name.

説明

public Swoole\MySQL::on(string $event_name, callable $callback): void

Register callback function based on event name, current only 'close' event is supported.

パラメータ

event_name

callback

戻り値


Run the SQL query.

  • ≪ Swoole\MySQL::on
  • Swoole\MySQL\Exception ≫
  • PHP Manual
  • Swoole\MySQL
  • Run the SQL query.

Swoole\MySQL::query

(PECL swoole >= 1.9.0)

Swoole\MySQL::query — Run the SQL query.

説明

public Swoole\MySQL::query(string $sql, callable $callback): ReturnType

パラメータ

sql

callback

戻り値


The Swoole\MySQL\Exception class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\MySQL\Exception extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
}


The Swoole\Process class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Process {
/* 定数 */
const int IPC_NOWAIT = 256;
/* メソッド */
public static alarm(int $interval_usec): void
public close(): void
public static daemon(bool $nochdir = ?, bool $noclose = ?): void
public __destruct(): void
public exec(string $exec_file, string $args): ReturnType
public exit(string $exit_code = ?): void
public freeQueue(): void
public static kill(int $pid, int $signal_no = ?): bool
public name(string $process_name): bool
public pop(int $maxsize = ?): mixed
public push(string $data): bool
public read(int $maxsize = ?): string
public static signal(string $signal_no, callable $callback): void
public start(): void
public statQueue(): array
public useQueue(int $key, int $mode = ?): bool
public static wait(bool $blocking = ?): array
public write(string $data): int
}

定義済み定数

Swoole\Process::IPC_NOWAIT

目次

  • Swoole\Process::alarm — High precision timer which triggers signal with fixed interval.
  • Swoole\Process::close — Close the pipe to the child process.
  • Swoole\Process::__construct — Construct a process.
  • Swoole\Process::daemon — Change the process to be a daemon process.
  • Swoole\Process::__destruct — Destroy the process.
  • Swoole\Process::exec — Execute system commands.
  • Swoole\Process::exit — Stop the child processes.
  • Swoole\Process::freeQueue — Destroy the message queue created by swoole_process::useQueue.
  • Swoole\Process::kill — Send signal to the child process.
  • Swoole\Process::name — Set name of the process.
  • Swoole\Process::pop — Read and pop data from the message queue.
  • Swoole\Process::push — Write and push data into the message queue.
  • Swoole\Process::read — Read data sending to the process.
  • Swoole\Process::signal — Send signal to the child processes.
  • Swoole\Process::start — Start the process.
  • Swoole\Process::statQueue — Get the stats of the message queue used as the communication method between processes.
  • Swoole\Process::useQueue — Create a message queue as the communication method between the parent process and child processes.
  • Swoole\Process::wait — Wait for the events of child processes.
  • Swoole\Process::write — Write data into the pipe and communicate with the parent process or child processes.


High precision timer which triggers signal with fixed interval.

  • ≪ Swoole\Process
  • Swoole\Process::close ≫
  • PHP Manual
  • Swoole\Process
  • High precision timer which triggers signal with fixed interval.

Swoole\Process::alarm

(PECL swoole >= 1.9.0)

Swoole\Process::alarm — High precision timer which triggers signal with fixed interval.

説明

public static Swoole\Process::alarm(int $interval_usec): void

パラメータ

interval_usec

戻り値


Close the pipe to the child process.

  • ≪ Swoole\Process::alarm
  • Swoole\Process::__construct ≫
  • PHP Manual
  • Swoole\Process
  • Close the pipe to the child process.

Swoole\Process::close

(PECL swoole >= 1.9.0)

Swoole\Process::close — Close the pipe to the child process.

説明

public Swoole\Process::close(): void

Close the pipe to the child process.

パラメータ

この関数にはパラメータはありません。

戻り値


Construct a process.

  • ≪ Swoole\Process::close
  • Swoole\Process::daemon ≫
  • PHP Manual
  • Swoole\Process
  • Construct a process.

Swoole\Process::__construct

(PECL swoole >= 1.9.0)

Swoole\Process::__construct — Construct a process.

説明

public Swoole\Process::__construct(callable $callback, bool $redirect_stdin_and_stdout = ?, int $pipe_type = ?)

パラメータ

callback

redirect_stdin_and_stdout

pipe_type


Change the process to be a daemon process.

  • ≪ Swoole\Process::__construct
  • Swoole\Process::__destruct ≫
  • PHP Manual
  • Swoole\Process
  • Change the process to be a daemon process.

Swoole\Process::daemon

(PECL swoole >= 1.9.0)

Swoole\Process::daemon — Change the process to be a daemon process.

説明

public static Swoole\Process::daemon(bool $nochdir = ?, bool $noclose = ?): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

nochdir

noclose

戻り値


Destroy the process.

  • ≪ Swoole\Process::daemon
  • Swoole\Process::exec ≫
  • PHP Manual
  • Swoole\Process
  • Destroy the process.

Swoole\Process::__destruct

(PECL swoole >= 1.9.0)

Swoole\Process::__destruct — Destroy the process.

説明

public Swoole\Process::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Execute system commands.

  • ≪ Swoole\Process::__destruct
  • Swoole\Process::exit ≫
  • PHP Manual
  • Swoole\Process
  • Execute system commands.

Swoole\Process::exec

(PECL swoole >= 1.9.0)

Swoole\Process::exec — Execute system commands.

説明

public Swoole\Process::exec(string $exec_file, string $args): ReturnType

The process will be replaced to be the system command process, but the pipe to the parent process will be kept.

パラメータ

exec_file

args

戻り値


Stop the child processes.

  • ≪ Swoole\Process::exec
  • Swoole\Process::freeQueue ≫
  • PHP Manual
  • Swoole\Process
  • Stop the child processes.

Swoole\Process::exit

(PECL swoole >= 1.9.0)

Swoole\Process::exit — Stop the child processes.

説明

public Swoole\Process::exit(string $exit_code = ?): void

パラメータ

exit_code

戻り値


Destroy the message queue created by swoole_process::useQueue.

  • ≪ Swoole\Process::exit
  • Swoole\Process::kill ≫
  • PHP Manual
  • Swoole\Process
  • Destroy the message queue created by swoole_process::useQueue.

Swoole\Process::freeQueue

(PECL swoole >= 1.9.0)

Swoole\Process::freeQueue — Destroy the message queue created by swoole_process::useQueue.

説明

public Swoole\Process::freeQueue(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Send signal to the child process.

  • ≪ Swoole\Process::freeQueue
  • Swoole\Process::name ≫
  • PHP Manual
  • Swoole\Process
  • Send signal to the child process.

Swoole\Process::kill

(PECL swoole >= 1.9.0)

Swoole\Process::kill — Send signal to the child process.

説明

public static Swoole\Process::kill(int $pid, int $signal_no = ?): bool

Send signal to the child process.

パラメータ

pid

Process pid

signal_no

Signal to be sent

戻り値

成功した場合に true を、失敗した場合に false を返します。


Set name of the process.

  • ≪ Swoole\Process::kill
  • Swoole\Process::pop ≫
  • PHP Manual
  • Swoole\Process
  • Set name of the process.

Swoole\Process::name

(PECL swoole >= 1.9.0)

Swoole\Process::name — Set name of the process.

説明

public Swoole\Process::name(string $process_name): bool

パラメータ

process_name

Set name of the process.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Read and pop data from the message queue.

  • ≪ Swoole\Process::name
  • Swoole\Process::push ≫
  • PHP Manual
  • Swoole\Process
  • Read and pop data from the message queue.

Swoole\Process::pop

(PECL swoole >= 1.9.0)

Swoole\Process::pop — Read and pop data from the message queue.

説明

public Swoole\Process::pop(int $maxsize = ?): mixed

パラメータ

maxsize

戻り値


Write and push data into the message queue.

  • ≪ Swoole\Process::pop
  • Swoole\Process::read ≫
  • PHP Manual
  • Swoole\Process
  • Write and push data into the message queue.

Swoole\Process::push

(PECL swoole >= 1.9.0)

Swoole\Process::push — Write and push data into the message queue.

説明

public Swoole\Process::push(string $data): bool

パラメータ

data

戻り値


Read data sending to the process.

  • ≪ Swoole\Process::push
  • Swoole\Process::signal ≫
  • PHP Manual
  • Swoole\Process
  • Read data sending to the process.

Swoole\Process::read

(PECL swoole >= 1.9.0)

Swoole\Process::read — Read data sending to the process.

説明

public Swoole\Process::read(int $maxsize = ?): string

パラメータ

maxsize

戻り値


Send signal to the child processes.

  • ≪ Swoole\Process::read
  • Swoole\Process::start ≫
  • PHP Manual
  • Swoole\Process
  • Send signal to the child processes.

Swoole\Process::signal

(PECL swoole >= 1.9.0)

Swoole\Process::signal — Send signal to the child processes.

説明

public static Swoole\Process::signal(string $signal_no, callable $callback): void

パラメータ

signal_no

callback

戻り値

If signal sent successfully, it returns TRUE, otherwise it returns FALSE.


Start the process.

  • ≪ Swoole\Process::signal
  • Swoole\Process::statQueue ≫
  • PHP Manual
  • Swoole\Process
  • Start the process.

Swoole\Process::start

(PECL swoole >= 1.9.0)

Swoole\Process::start — Start the process.

説明

public Swoole\Process::start(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Get the stats of the message queue used as the communication method between processes.

  • ≪ Swoole\Process::start
  • Swoole\Process::useQueue ≫
  • PHP Manual
  • Swoole\Process
  • Get the stats of the message queue used as the communication method between processes.

Swoole\Process::statQueue

(PECL swoole >= 1.9.0)

Swoole\Process::statQueue — Get the stats of the message queue used as the communication method between processes.

説明

public Swoole\Process::statQueue(): array

パラメータ

この関数にはパラメータはありません。

戻り値

The array of status of the message queue.


Create a message queue as the communication method between the parent process and child processes.

  • ≪ Swoole\Process::statQueue
  • Swoole\Process::wait ≫
  • PHP Manual
  • Swoole\Process
  • Create a message queue as the communication method between the parent process and child processes.

Swoole\Process::useQueue

(PECL swoole >= 1.9.0)

Swoole\Process::useQueue — Create a message queue as the communication method between the parent process and child processes.

説明

public Swoole\Process::useQueue(int $key, int $mode = ?): bool

パラメータ

key

mode

戻り値


Wait for the events of child processes.

  • ≪ Swoole\Process::useQueue
  • Swoole\Process::write ≫
  • PHP Manual
  • Swoole\Process
  • Wait for the events of child processes.

Swoole\Process::wait

(PECL swoole >= 1.9.0)

Swoole\Process::wait — Wait for the events of child processes.

説明

public static Swoole\Process::wait(bool $blocking = ?): array

パラメータ

blocking

戻り値


Write data into the pipe and communicate with the parent process or child processes.

  • ≪ Swoole\Process::wait
  • Swoole\Redis\Server ≫
  • PHP Manual
  • Swoole\Process
  • Write data into the pipe and communicate with the parent process or child processes.

Swoole\Process::write

(PECL swoole >= 1.9.0)

Swoole\Process::write — Write data into the pipe and communicate with the parent process or child processes.

説明

public Swoole\Process::write(string $data): int

パラメータ

data

戻り値


The Swoole\Redis\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Redis\Server extends Swoole\Server {
/* 定数 */
const int NIL = 1;
const int ERROR = 0;
const int STATUS = 2;
const int INT = 3;
const int STRING = 4;
const int SET = 5;
const int MAP = 6;
/* メソッド */
public static format(string $type, string $value = ?): ReturnType
public setHandler(
string $command,
string $callback,
string $number_of_string_param = ?,
string $type_of_array_param = ?
): ReturnType
public start(): ReturnType
/* 継承したメソッド */
public Swoole\Server::addlistener(string $host, int $port, string $socket_type): void
public Swoole\Server::addProcess(swoole_process $process): bool
public Swoole\Server::after(int $after_time_ms, callable $callback, string $param = ?): ReturnType
public Swoole\Server::bind(int $fd, int $uid): bool
public Swoole\Server::clearTimer(int $timer_id): void
swoole_timer_clear(int $timer_id): void
public Swoole\Server::close(int $fd, bool $reset = ?): bool
public Swoole\Server::confirm(int $fd): bool
public Swoole\Server::connection_info(int $fd, int $reactor_id = ?): array
public Swoole\Server::connection_list(int $start_fd, int $pagesize = ?): array
public Swoole\Server::defer(callable $callback): void
public Swoole\Server\Port::__destruct(): void
public Swoole\Server\Port::on(string $event_name, callable $callback): ReturnType
public Swoole\Server\Port::set(array $settings): void
public Swoole\Server::exist(int $fd): bool
public Swoole\Server::finish(string $data): void
public Swoole\Server::getClientInfo(int $fd, int $reactor_id = ?, bool $ignore_error = ?): array
public Swoole\Server::getClientList(int $start_fd, int $pagesize = ?): array
public Swoole\Server::getLastError(): int
public Swoole\Server::heartbeat(bool $if_close_connection): mixed
public Swoole\Server::listen(string $host, int $port, string $socket_type): bool
public Swoole\Server::on(string $event_name, callable $callback): void
public Swoole\Server::pause(int $fd): void
public Swoole\Server::protect(int $fd, bool $is_protected = ?): void
public Swoole\Server::reload(): bool
public Swoole\Server::resume(int $fd): void
public Swoole\Server::send(int $fd, string $data, int $reactor_id = ?): bool
public Swoole\Server::sendfile(int $fd, string $filename, int $offset = ?): bool
public Swoole\Server::sendMessage(int $worker_id, string $data): bool
public Swoole\Server::sendto(
string $ip,
int $port,
string $data,
string $server_socket = ?
): bool
public Swoole\Server::sendwait(int $fd, string $data): bool
public Swoole\Server::set(array $settings): ReturnType
public Swoole\Server::shutdown(): void
public Swoole\Server::start(): void
public Swoole\Server::stats(): array
public Swoole\Server::stop(int $worker_id = ?): bool
public Swoole\Server::task(string $data, int $dst_worker_id = ?, callable $callback = ?): mixed
public Swoole\Server::taskwait(string $data, float $timeout = ?, int $worker_id = ?): void
public Swoole\Server::taskWaitMulti(array $tasks, float $timeout_ms = ?): void
public Swoole\Server::tick(int $interval_ms, callable $callback): void
}

定義済み定数

Swoole\Redis\Server::NIL

Swoole\Redis\Server::ERROR

Swoole\Redis\Server::STATUS

Swoole\Redis\Server::INT

Swoole\Redis\Server::STRING

Swoole\Redis\Server::SET

Swoole\Redis\Server::MAP

目次

  • Swoole\Redis\Server::format — Description
  • Swoole\Redis\Server::setHandler — Description
  • Swoole\Redis\Server::start — Description


Description

  • ≪ Swoole\Redis\Server
  • Swoole\Redis\Server::setHandler ≫
  • PHP Manual
  • Swoole\Redis\Server
  • Description

Swoole\Redis\Server::format

(PECL swoole >= 1.9.0)

Swoole\Redis\Server::format — Description

説明

public static Swoole\Redis\Server::format(string $type, string $value = ?): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

type

value

戻り値


Description

  • ≪ Swoole\Redis\Server::format
  • Swoole\Redis\Server::start ≫
  • PHP Manual
  • Swoole\Redis\Server
  • Description

Swoole\Redis\Server::setHandler

(PECL swoole >= 1.9.0)

Swoole\Redis\Server::setHandler — Description

説明

public Swoole\Redis\Server::setHandler(
string $command,
string $callback,
string $number_of_string_param = ?,
string $type_of_array_param = ?
): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

command

callback

number_of_string_param

type_of_array_param

戻り値


Description

  • ≪ Swoole\Redis\Server::setHandler
  • Swoole\Serialize ≫
  • PHP Manual
  • Swoole\Redis\Server
  • Description

Swoole\Redis\Server::start

(PECL swoole >= 1.9.0)

Swoole\Redis\Server::start — Description

説明

public Swoole\Redis\Server::start(): ReturnType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Serialize class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Serialize {
/* メソッド */
public static pack(string $data, int $is_fast = ?): ReturnType
public static unpack(string $data, string $args = ?): ReturnType
}

目次

  • Swoole\Serialize::pack — Serialize the data.
  • Swoole\Serialize::unpack — Unserialize the data.


Serialize the data.

  • ≪ Swoole\Serialize
  • Swoole\Serialize::unpack ≫
  • PHP Manual
  • Swoole\Serialize
  • Serialize the data.

Swoole\Serialize::pack

(PECL swoole >= 1.9.0)

Swoole\Serialize::pack — Serialize the data.

説明

public static Swoole\Serialize::pack(string $data, int $is_fast = ?): ReturnType

Swoole provides a fast and high performance serialization module.

パラメータ

data

is_fast

戻り値


Unserialize the data.

  • ≪ Swoole\Serialize::pack
  • Swoole\Server ≫
  • PHP Manual
  • Swoole\Serialize
  • Unserialize the data.

Swoole\Serialize::unpack

(PECL swoole >= 1.9.0)

Swoole\Serialize::unpack — Unserialize the data.

説明

public static Swoole\Serialize::unpack(string $data, string $args = ?): ReturnType

Unserialize the data.

パラメータ

string

args

戻り値


The Swoole\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Server {
/* メソッド */
public addlistener(string $host, int $port, string $socket_type): void
public addProcess(swoole_process $process): bool
public after(int $after_time_ms, callable $callback, string $param = ?): ReturnType
public bind(int $fd, int $uid): bool
public clearTimer(int $timer_id): void
swoole_timer_clear(int $timer_id): void
public close(int $fd, bool $reset = ?): bool
public confirm(int $fd): bool
public connection_info(int $fd, int $reactor_id = ?): array
public connection_list(int $start_fd, int $pagesize = ?): array
public defer(callable $callback): void
public Swoole\Server\Port::__destruct(): void
public Swoole\Server\Port::on(string $event_name, callable $callback): ReturnType
public Swoole\Server\Port::set(array $settings): void
public exist(int $fd): bool
public finish(string $data): void
public getClientInfo(int $fd, int $reactor_id = ?, bool $ignore_error = ?): array
public getClientList(int $start_fd, int $pagesize = ?): array
public getLastError(): int
public heartbeat(bool $if_close_connection): mixed
public listen(string $host, int $port, string $socket_type): bool
public on(string $event_name, callable $callback): void
public pause(int $fd): void
public protect(int $fd, bool $is_protected = ?): void
public reload(): bool
public resume(int $fd): void
public send(int $fd, string $data, int $reactor_id = ?): bool
public sendfile(int $fd, string $filename, int $offset = ?): bool
public sendMessage(int $worker_id, string $data): bool
public sendto(
string $ip,
int $port,
string $data,
string $server_socket = ?
): bool
public sendwait(int $fd, string $data): bool
public set(array $settings): ReturnType
public shutdown(): void
public start(): void
public stats(): array
public stop(int $worker_id = ?): bool
public task(string $data, int $dst_worker_id = ?, callable $callback = ?): mixed
public taskwait(string $data, float $timeout = ?, int $worker_id = ?): void
public taskWaitMulti(array $tasks, float $timeout_ms = ?): void
public tick(int $interval_ms, callable $callback): void
}

目次

  • Swoole\Server::addlistener — Add a new listener to the server.
  • Swoole\Server::addProcess — Add a user defined swoole_process to the server.
  • Swoole\Server::after — Trigger a callback function after a period of time.
  • Swoole\Server::bind — Bind the connection to a user defined user ID.
  • Swoole\Server::clearTimer — Stop and destroy a timer.
  • Swoole\Server::close — Close a connection to the client.
  • Swoole\Server::confirm — Check status of the connection.
  • Swoole\Server::connection_info — Get the connection info by file description.
  • Swoole\Server::connection_list — Get all of the established connections.
  • Swoole\Server::__construct — Construct a Swoole server.
  • Swoole\Server::defer — Delay execution of the callback function at the end of current EventLoop.
  • Swoole\Server\Port::__construct — Construct a server port
  • Swoole\Server\Port::__destruct — Destory server port
  • Swoole\Server\Port::on — Register callback functions by event.
  • Swoole\Server\Port::set — Set protocol of the server port.
  • Swoole\Server::exist — Check if the connection is existed.
  • Swoole\Server::finish — Used in task process for sending result to the worker process when the task is finished.
  • Swoole\Server::getClientInfo — Get the connection info by file description.
  • Swoole\Server::getClientList — Get all of the established connections.
  • Swoole\Server::getLastError — Get the error code of the most recent error.
  • Swoole\Server::heartbeat — Check all the connections on the server.
  • Swoole\Server::listen — Listen on the given IP and port, socket type.
  • Swoole\Server::on — Register a callback function by event name.
  • Swoole\Server::pause — Stop receiving data from the connection.
  • Swoole\Server::protect — Set the connection to be protected mode.
  • Swoole\Server::reload — Restart all the worker process.
  • Swoole\Server::resume — Start receving data from the connection.
  • Swoole\Server::send — Send data to the client.
  • Swoole\Server::sendfile — Send file to the connection.
  • Swoole\Server::sendMessage — Send message to worker processes by ID.
  • Swoole\Server::sendto — Send data to the remote UDP address.
  • Swoole\Server::sendwait — Send data to the remote socket in the blocking way.
  • Swoole\Server::set — Set the runtime settings of the swoole server.
  • Swoole\Server::shutdown — Shutdown the master server process, this function can be called in worker processes.
  • Swoole\Server::start — Start the Swoole server.
  • Swoole\Server::stats — Get the stats of the Swoole server.
  • Swoole\Server::stop — Stop the Swoole server.
  • Swoole\Server::task — Send data to the task worker processes.
  • Swoole\Server::taskwait — Send data to the task worker processes in blocking way.
  • Swoole\Server::taskWaitMulti — Execute multiple tasks concurrently.
  • Swoole\Server::tick — Repeats a given function at every given time-interval.


Add a new listener to the server.

  • ≪ Swoole\Server
  • Swoole\Server::addProcess ≫
  • PHP Manual
  • Swoole\Server
  • Add a new listener to the server.

Swoole\Server::addlistener

(PECL swoole >= 1.9.0)

Swoole\Server::addlistener — Add a new listener to the server.

説明

public Swoole\Server::addlistener(string $host, int $port, string $socket_type): void

パラメータ

host

port

socket_type

戻り値


Add a user defined swoole_process to the server.

  • ≪ Swoole\Server::addlistener
  • Swoole\Server::after ≫
  • PHP Manual
  • Swoole\Server
  • Add a user defined swoole_process to the server.

Swoole\Server::addProcess

(PECL swoole >= 1.9.0)

Swoole\Server::addProcess — Add a user defined swoole_process to the server.

説明

public Swoole\Server::addProcess(swoole_process $process): bool

パラメータ

process

戻り値


Trigger a callback function after a period of time.

  • ≪ Swoole\Server::addProcess
  • Swoole\Server::bind ≫
  • PHP Manual
  • Swoole\Server
  • Trigger a callback function after a period of time.

Swoole\Server::after

(PECL swoole >= 1.9.0)

Swoole\Server::after — Trigger a callback function after a period of time.

説明

public Swoole\Server::after(int $after_time_ms, callable $callback, string $param = ?): ReturnType

パラメータ

after_time_ms

callback

param

戻り値


Bind the connection to a user defined user ID.

  • ≪ Swoole\Server::after
  • Swoole\Server::clearTimer ≫
  • PHP Manual
  • Swoole\Server
  • Bind the connection to a user defined user ID.

Swoole\Server::bind

(PECL swoole >= 1.9.0)

Swoole\Server::bind — Bind the connection to a user defined user ID.

説明

public Swoole\Server::bind(int $fd, int $uid): bool

パラメータ

fd

uid

戻り値


Stop and destroy a timer.

  • ≪ Swoole\Server::bind
  • Swoole\Server::close ≫
  • PHP Manual
  • Swoole\Server
  • Stop and destroy a timer.

Swoole\Server::clearTimer

swoole_timer_clear

(PECL swoole >= 1.9.0)

Swoole\Server::clearTimer -- swoole_timer_clear — Stop and destroy a timer.

説明

オブジェクト指向型 (method):

public Swoole\Server::clearTimer(int $timer_id): void

手続き型:

swoole_timer_clear(int $timer_id): void

Stop and destroy a timer

パラメータ

timer_id

戻り値


Close a connection to the client.

  • ≪ Swoole\Server::clearTimer
  • Swoole\Server::confirm ≫
  • PHP Manual
  • Swoole\Server
  • Close a connection to the client.

Swoole\Server::close

(PECL swoole >= 1.9.0)

Swoole\Server::close — Close a connection to the client.

説明

public Swoole\Server::close(int $fd, bool $reset = ?): bool

パラメータ

fd

reset

戻り値


Check status of the connection.

  • ≪ Swoole\Server::close
  • Swoole\Server::connection_info ≫
  • PHP Manual
  • Swoole\Server
  • Check status of the connection.

Swoole\Server::confirm

(PECL swoole >= 1.9.0)

Swoole\Server::confirm — Check status of the connection.

説明

public Swoole\Server::confirm(int $fd): bool

パラメータ

fd

戻り値


Get the connection info by file description.

  • ≪ Swoole\Server::confirm
  • Swoole\Server::connection_list ≫
  • PHP Manual
  • Swoole\Server
  • Get the connection info by file description.

Swoole\Server::connection_info

(PECL swoole >= 1.9.0)

Swoole\Server::connection_info — Get the connection info by file description.

説明

public Swoole\Server::connection_info(int $fd, int $reactor_id = ?): array

パラメータ

fd

reactor_id

戻り値


Get all of the established connections.

  • ≪ Swoole\Server::connection_info
  • Swoole\Server::__construct ≫
  • PHP Manual
  • Swoole\Server
  • Get all of the established connections.

Swoole\Server::connection_list

(PECL swoole >= 1.9.0)

Swoole\Server::connection_list — Get all of the established connections.

説明

public Swoole\Server::connection_list(int $start_fd, int $pagesize = ?): array

パラメータ

start_fd

pagesize

戻り値


Construct a Swoole server.

  • ≪ Swoole\Server::connection_list
  • Swoole\Server::defer ≫
  • PHP Manual
  • Swoole\Server
  • Construct a Swoole server.

Swoole\Server::__construct

(PECL swoole >= 1.9.0)

Swoole\Server::__construct — Construct a Swoole server.

説明

public Swoole\Server::__construct(
string $host,
int $port = ?,
integr $mode = ?,
int $sock_type = ?
)

パラメータ

host

port

mode

sock_type


Delay execution of the callback function at the end of current EventLoop.

  • ≪ Swoole\Server::__construct
  • Swoole\Server\Port::__construct ≫
  • PHP Manual
  • Swoole\Server
  • Delay execution of the callback function at the end of current EventLoop.

Swoole\Server::defer

(PECL swoole >= 1.9.0)

Swoole\Server::defer — Delay execution of the callback function at the end of current EventLoop.

説明

public Swoole\Server::defer(callable $callback): void

パラメータ

callback

戻り値


Construct a server port

  • ≪ Swoole\Server::defer
  • Swoole\Server\Port::__destruct ≫
  • PHP Manual
  • Swoole\Server
  • Construct a server port

Swoole\Server\Port::__construct

(PECL swoole >= 1.9.0)

Swoole\Server\Port::__construct — Construct a server port

説明

private Swoole\Server\Port::__construct()

パラメータ

この関数にはパラメータはありません。


Destory server port

  • ≪ Swoole\Server\Port::__construct
  • Swoole\Server\Port::on ≫
  • PHP Manual
  • Swoole\Server
  • Destory server port

Swoole\Server\Port::__destruct

(PECL swoole >= 1.9.0)

Swoole\Server\Port::__destruct — Destory server port

説明

public Swoole\Server\Port::__destruct(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Register callback functions by event.

  • ≪ Swoole\Server\Port::__destruct
  • Swoole\Server\Port::set ≫
  • PHP Manual
  • Swoole\Server
  • Register callback functions by event.

Swoole\Server\Port::on

(PECL swoole >= 1.9.0)

Swoole\Server\Port::on — Register callback functions by event.

説明

public Swoole\Server\Port::on(string $event_name, callable $callback): ReturnType

パラメータ

event_name

callback

戻り値


Set protocol of the server port.

  • ≪ Swoole\Server\Port::on
  • Swoole\Server::exist ≫
  • PHP Manual
  • Swoole\Server
  • Set protocol of the server port.

Swoole\Server\Port::set

(PECL swoole >= 1.9.0)

Swoole\Server\Port::set — Set protocol of the server port.

説明

public Swoole\Server\Port::set(array $settings): void

パラメータ

settings

戻り値


Check if the connection is existed.

  • ≪ Swoole\Server\Port::set
  • Swoole\Server::finish ≫
  • PHP Manual
  • Swoole\Server
  • Check if the connection is existed.

Swoole\Server::exist

(PECL swoole >= 1.9.0)

Swoole\Server::exist — Check if the connection is existed.

説明

public Swoole\Server::exist(int $fd): bool

パラメータ

fd

戻り値


Used in task process for sending result to the worker process when the task is finished.

  • ≪ Swoole\Server::exist
  • Swoole\Server::getClientInfo ≫
  • PHP Manual
  • Swoole\Server
  • Used in task process for sending result to the worker process when the task is finished.

Swoole\Server::finish

(PECL swoole >= 1.9.0)

Swoole\Server::finish — Used in task process for sending result to the worker process when the task is finished.

説明

public Swoole\Server::finish(string $data): void

パラメータ

data

戻り値


Get the connection info by file description.

  • ≪ Swoole\Server::finish
  • Swoole\Server::getClientList ≫
  • PHP Manual
  • Swoole\Server
  • Get the connection info by file description.

Swoole\Server::getClientInfo

(PECL swoole >= 1.9.0)

Swoole\Server::getClientInfo — Get the connection info by file description.

説明

public Swoole\Server::getClientInfo(int $fd, int $reactor_id = ?, bool $ignore_error = ?): array

パラメータ

fd

File descriptors.

reactor_id

The Reactor thread ID where the connection is made.

ignore_error

Whether to ignore errors, if set to true, connection information will be returned even if the connection is closed.

戻り値

Returns information about the client connection.


Get all of the established connections.

  • ≪ Swoole\Server::getClientInfo
  • Swoole\Server::getLastError ≫
  • PHP Manual
  • Swoole\Server
  • Get all of the established connections.

Swoole\Server::getClientList

(PECL swoole >= 1.9.0)

Swoole\Server::getClientList — Get all of the established connections.

説明

public Swoole\Server::getClientList(int $start_fd, int $pagesize = ?): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

start_fd

pagesize

戻り値


Get the error code of the most recent error.

  • ≪ Swoole\Server::getClientList
  • Swoole\Server::heartbeat ≫
  • PHP Manual
  • Swoole\Server
  • Get the error code of the most recent error.

Swoole\Server::getLastError

(PECL swoole >= 1.9.0)

Swoole\Server::getLastError — Get the error code of the most recent error.

説明

public Swoole\Server::getLastError(): int

パラメータ

この関数にはパラメータはありません。

戻り値


Check all the connections on the server.

  • ≪ Swoole\Server::getLastError
  • Swoole\Server::listen ≫
  • PHP Manual
  • Swoole\Server
  • Check all the connections on the server.

Swoole\Server::heartbeat

(PECL swoole >= 1.9.0)

Swoole\Server::heartbeat — Check all the connections on the server.

説明

public Swoole\Server::heartbeat(bool $if_close_connection): mixed

パラメータ

if_close_connection

戻り値


Listen on the given IP and port, socket type.

  • ≪ Swoole\Server::heartbeat
  • Swoole\Server::on ≫
  • PHP Manual
  • Swoole\Server
  • Listen on the given IP and port, socket type.

Swoole\Server::listen

(PECL swoole >= 1.9.0)

Swoole\Server::listen — Listen on the given IP and port, socket type.

説明

public Swoole\Server::listen(string $host, int $port, string $socket_type): bool

パラメータ

host

port

socket_type

戻り値


Register a callback function by event name.

  • ≪ Swoole\Server::listen
  • Swoole\Server::pause ≫
  • PHP Manual
  • Swoole\Server
  • Register a callback function by event name.

Swoole\Server::on

(PECL swoole >= 1.9.0)

Swoole\Server::on — Register a callback function by event name.

説明

public Swoole\Server::on(string $event_name, callable $callback): void

パラメータ

event_name

callback

戻り値


Stop receiving data from the connection.

  • ≪ Swoole\Server::on
  • Swoole\Server::protect ≫
  • PHP Manual
  • Swoole\Server
  • Stop receiving data from the connection.

Swoole\Server::pause

(PECL swoole >= 1.9.0)

Swoole\Server::pause — Stop receiving data from the connection.

説明

public Swoole\Server::pause(int $fd): void

パラメータ

fd

戻り値


Set the connection to be protected mode.

  • ≪ Swoole\Server::pause
  • Swoole\Server::reload ≫
  • PHP Manual
  • Swoole\Server
  • Set the connection to be protected mode.

Swoole\Server::protect

(PECL swoole >= 1.9.0)

Swoole\Server::protect — Set the connection to be protected mode.

説明

public Swoole\Server::protect(int $fd, bool $is_protected = ?): void

パラメータ

fd

is_protected

戻り値


Restart all the worker process.

  • ≪ Swoole\Server::protect
  • Swoole\Server::resume ≫
  • PHP Manual
  • Swoole\Server
  • Restart all the worker process.

Swoole\Server::reload

(PECL swoole >= 1.9.0)

Swoole\Server::reload — Restart all the worker process.

説明

public Swoole\Server::reload(): bool

パラメータ

この関数にはパラメータはありません。

戻り値


Start receving data from the connection.

  • ≪ Swoole\Server::reload
  • Swoole\Server::send ≫
  • PHP Manual
  • Swoole\Server
  • Start receving data from the connection.

Swoole\Server::resume

(PECL swoole >= 1.9.0)

Swoole\Server::resume — Start receving data from the connection.

説明

public Swoole\Server::resume(int $fd): void

パラメータ

fd

戻り値


Send data to the client.

  • ≪ Swoole\Server::resume
  • Swoole\Server::sendfile ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the client.

Swoole\Server::send

(PECL swoole >= 1.9.0)

Swoole\Server::send — Send data to the client.

説明

public Swoole\Server::send(int $fd, string $data, int $reactor_id = ?): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

data

reactor_id

戻り値


Send file to the connection.

  • ≪ Swoole\Server::send
  • Swoole\Server::sendMessage ≫
  • PHP Manual
  • Swoole\Server
  • Send file to the connection.

Swoole\Server::sendfile

(PECL swoole >= 1.9.0)

Swoole\Server::sendfile — Send file to the connection.

説明

public Swoole\Server::sendfile(int $fd, string $filename, int $offset = ?): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

filename

offset

戻り値


Send message to worker processes by ID.

  • ≪ Swoole\Server::sendfile
  • Swoole\Server::sendto ≫
  • PHP Manual
  • Swoole\Server
  • Send message to worker processes by ID.

Swoole\Server::sendMessage

(PECL swoole >= 1.9.0)

Swoole\Server::sendMessage — Send message to worker processes by ID.

説明

public Swoole\Server::sendMessage(int $worker_id, string $data): bool

パラメータ

dst_worker_id

data

戻り値


Send data to the remote UDP address.

  • ≪ Swoole\Server::sendMessage
  • Swoole\Server::sendwait ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the remote UDP address.

Swoole\Server::sendto

(PECL swoole >= 1.9.0)

Swoole\Server::sendto — Send data to the remote UDP address.

説明

public Swoole\Server::sendto(
string $ip,
int $port,
string $data,
string $server_socket = ?
): bool

パラメータ

ip

port

data

server_socket

戻り値


Send data to the remote socket in the blocking way.

  • ≪ Swoole\Server::sendto
  • Swoole\Server::set ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the remote socket in the blocking way.

Swoole\Server::sendwait

(PECL swoole >= 1.9.0)

Swoole\Server::sendwait — Send data to the remote socket in the blocking way.

説明

public Swoole\Server::sendwait(int $fd, string $data): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

data

戻り値


Set the runtime settings of the swoole server.

  • ≪ Swoole\Server::sendwait
  • Swoole\Server::shutdown ≫
  • PHP Manual
  • Swoole\Server
  • Set the runtime settings of the swoole server.

Swoole\Server::set

(PECL swoole >= 1.9.0)

Swoole\Server::set — Set the runtime settings of the swoole server.

説明

public Swoole\Server::set(array $settings): ReturnType

Set the runtime settings of the swoole server. The settings can be accessed by $server->setting when the swoole server has started.

パラメータ

settings

戻り値


Shutdown the master server process, this function can be called in worker processes.

  • ≪ Swoole\Server::set
  • Swoole\Server::start ≫
  • PHP Manual
  • Swoole\Server
  • Shutdown the master server process, this function can be called in worker processes.

Swoole\Server::shutdown

(PECL swoole >= 1.9.0)

Swoole\Server::shutdown — Shutdown the master server process, this function can be called in worker processes.

説明

public Swoole\Server::shutdown(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Start the Swoole server.

  • ≪ Swoole\Server::shutdown
  • Swoole\Server::stats ≫
  • PHP Manual
  • Swoole\Server
  • Start the Swoole server.

Swoole\Server::start

(PECL swoole >= 1.9.0)

Swoole\Server::start — Start the Swoole server.

説明

public Swoole\Server::start(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Get the stats of the Swoole server.

  • ≪ Swoole\Server::start
  • Swoole\Server::stop ≫
  • PHP Manual
  • Swoole\Server
  • Get the stats of the Swoole server.

Swoole\Server::stats

(PECL swoole >= 1.9.0)

Swoole\Server::stats — Get the stats of the Swoole server.

説明

public Swoole\Server::stats(): array

パラメータ

この関数にはパラメータはありません。

戻り値


Stop the Swoole server.

  • ≪ Swoole\Server::stats
  • Swoole\Server::task ≫
  • PHP Manual
  • Swoole\Server
  • Stop the Swoole server.

Swoole\Server::stop

(PECL swoole >= 1.9.0)

Swoole\Server::stop — Stop the Swoole server.

説明

public Swoole\Server::stop(int $worker_id = ?): bool

パラメータ

worker_id

戻り値


Send data to the task worker processes.

  • ≪ Swoole\Server::stop
  • Swoole\Server::taskwait ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the task worker processes.

Swoole\Server::task

(PECL swoole >= 1.9.0)

Swoole\Server::task — Send data to the task worker processes.

説明

public Swoole\Server::task(string $data, int $dst_worker_id = ?, callable $callback = ?): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

dst_worker_id

callback

戻り値


Send data to the task worker processes in blocking way.

  • ≪ Swoole\Server::task
  • Swoole\Server::taskWaitMulti ≫
  • PHP Manual
  • Swoole\Server
  • Send data to the task worker processes in blocking way.

Swoole\Server::taskwait

(PECL swoole >= 1.9.0)

Swoole\Server::taskwait — Send data to the task worker processes in blocking way.

説明

public Swoole\Server::taskwait(string $data, float $timeout = ?, int $worker_id = ?): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

data

timeout

worker_id

戻り値


Execute multiple tasks concurrently.

  • ≪ Swoole\Server::taskwait
  • Swoole\Server::tick ≫
  • PHP Manual
  • Swoole\Server
  • Execute multiple tasks concurrently.

Swoole\Server::taskWaitMulti

(PECL swoole >= 1.9.0)

Swoole\Server::taskWaitMulti — Execute multiple tasks concurrently.

説明

public Swoole\Server::taskWaitMulti(array $tasks, float $timeout_ms = ?): void

パラメータ

tasks

timeout_ms

戻り値


Repeats a given function at every given time-interval.

  • ≪ Swoole\Server::taskWaitMulti
  • Swoole\Table ≫
  • PHP Manual
  • Swoole\Server
  • Repeats a given function at every given time-interval.

Swoole\Server::tick

(PECL swoole >= 1.9.0)

Swoole\Server::tick — Repeats a given function at every given time-interval.

説明

public Swoole\Server::tick(int $interval_ms, callable $callback): void

パラメータ

interval_ms

callback

戻り値


The Swoole\Table class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Table implements Iterator, Countable {
/* 定数 */
const int TYPE_INT = 1;
const int TYPE_STRING = 7;
const int TYPE_FLOAT = 6;
/* メソッド */
public column(string $name, string $type, int $size = ?): ReturnType
public count(): int
public create(): void
public current(): array
public decr(string $key, string $column, int $decrby = ?): ReturnType
public del(string $key): void
public destroy(): void
public exist(string $key): bool
public get(string $row_key, string $column_key): int
public incr(string $key, string $column, int $incrby = ?): void
public key(): string
public next(): ReturnType
public rewind(): void
public set(string $key, array $value): void
public valid(): bool
}

定義済み定数

Swoole\Table::TYPE_INT

Swoole\Table::TYPE_STRING

Swoole\Table::TYPE_FLOAT

目次

  • Swoole\Table::column — Set the data type and size of the columns.
  • Swoole\Table::__construct — Construct a Swoole memory table with fixed size.
  • Swoole\Table::count — Count the rows in the table, or count all the elements in the table if $mode = 1.
  • Swoole\Table::create — Create the swoole memory table.
  • Swoole\Table::current — Get the current row.
  • Swoole\Table::decr — Decrement the value in the Swoole table by $row_key and $column_key.
  • Swoole\Table::del — Delete a row in the Swoole table by $row_key.
  • Swoole\Table::destroy — Destroy the Swoole table.
  • Swoole\Table::exist — Check if a row is existed by $row_key.
  • Swoole\Table::get — Get the value in the Swoole table by $row_key and $column_key.
  • Swoole\Table::incr — Increment the value by $row_key and $column_key.
  • Swoole\Table::key — Get the key of current row.
  • Swoole\Table::next — Iterator the next row.
  • Swoole\Table::rewind — Rewind the iterator.
  • Swoole\Table::set — Update a row of the table by $row_key.
  • Swoole\Table::valid — Check if the current row is valid.


Set the data type and size of the columns.

  • ≪ Swoole\Table
  • Swoole\Table::__construct ≫
  • PHP Manual
  • Swoole\Table
  • Set the data type and size of the columns.

Swoole\Table::column

(PECL swoole >= 1.9.0)

Swoole\Table::column — Set the data type and size of the columns.

説明

public Swoole\Table::column(string $name, string $type, int $size = ?): ReturnType

パラメータ

name

type

size

戻り値


Construct a Swoole memory table with fixed size.

  • ≪ Swoole\Table::column
  • Swoole\Table::count ≫
  • PHP Manual
  • Swoole\Table
  • Construct a Swoole memory table with fixed size.

Swoole\Table::__construct

(PECL swoole >= 1.9.0)

Swoole\Table::__construct — Construct a Swoole memory table with fixed size.

説明

public Swoole\Table::__construct(int $table_size)

パラメータ

table_size


Count the rows in the table, or count all the elements in the table if $mode = 1.

  • ≪ Swoole\Table::__construct
  • Swoole\Table::create ≫
  • PHP Manual
  • Swoole\Table
  • Count the rows in the table, or count all the elements in the table if $mode = 1.

Swoole\Table::count

(PECL swoole >= 1.9.0)

Swoole\Table::count — Count the rows in the table, or count all the elements in the table if $mode = 1.

説明

public Swoole\Table::count(): int

パラメータ

この関数にはパラメータはありません。

戻り値


Create the swoole memory table.

  • ≪ Swoole\Table::count
  • Swoole\Table::current ≫
  • PHP Manual
  • Swoole\Table
  • Create the swoole memory table.

Swoole\Table::create

(PECL swoole >= 1.9.0)

Swoole\Table::create — Create the swoole memory table.

説明

public Swoole\Table::create(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Get the current row.

  • ≪ Swoole\Table::create
  • Swoole\Table::decr ≫
  • PHP Manual
  • Swoole\Table
  • Get the current row.

Swoole\Table::current

(PECL swoole >= 1.9.0)

Swoole\Table::current — Get the current row.

説明

public Swoole\Table::current(): array

パラメータ

この関数にはパラメータはありません。

戻り値


Decrement the value in the Swoole table by $row_key and $column_key.

  • ≪ Swoole\Table::current
  • Swoole\Table::del ≫
  • PHP Manual
  • Swoole\Table
  • Decrement the value in the Swoole table by $row_key and $column_key.

Swoole\Table::decr

(PECL swoole >= 1.9.0)

Swoole\Table::decr — Decrement the value in the Swoole table by $row_key and $column_key.

説明

public Swoole\Table::decr(string $key, string $column, int $decrby = ?): ReturnType

パラメータ

key

column

decrby

戻り値


Delete a row in the Swoole table by $row_key.

  • ≪ Swoole\Table::decr
  • Swoole\Table::destroy ≫
  • PHP Manual
  • Swoole\Table
  • Delete a row in the Swoole table by $row_key.

Swoole\Table::del

(PECL swoole >= 1.9.0)

Swoole\Table::del — Delete a row in the Swoole table by $row_key.

説明

public Swoole\Table::del(string $key): void

パラメータ

key

戻り値


Destroy the Swoole table.

  • ≪ Swoole\Table::del
  • Swoole\Table::exist ≫
  • PHP Manual
  • Swoole\Table
  • Destroy the Swoole table.

Swoole\Table::destroy

(PECL swoole >= 1.9.0)

Swoole\Table::destroy — Destroy the Swoole table.

説明

public Swoole\Table::destroy(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Check if a row is existed by $row_key.

  • ≪ Swoole\Table::destroy
  • Swoole\Table::get ≫
  • PHP Manual
  • Swoole\Table
  • Check if a row is existed by $row_key.

Swoole\Table::exist

(PECL swoole >= 1.9.0)

Swoole\Table::exist — Check if a row is existed by $row_key.

説明

public Swoole\Table::exist(string $key): bool

パラメータ

key

戻り値


Get the value in the Swoole table by $row_key and $column_key.

  • ≪ Swoole\Table::exist
  • Swoole\Table::incr ≫
  • PHP Manual
  • Swoole\Table
  • Get the value in the Swoole table by $row_key and $column_key.

Swoole\Table::get

(PECL swoole >= 1.9.0)

Swoole\Table::get — Get the value in the Swoole table by $row_key and $column_key.

説明

public Swoole\Table::get(string $row_key, string $column_key): int

パラメータ

row_key

column_key

戻り値


Increment the value by $row_key and $column_key.

  • ≪ Swoole\Table::get
  • Swoole\Table::key ≫
  • PHP Manual
  • Swoole\Table
  • Increment the value by $row_key and $column_key.

Swoole\Table::incr

(PECL swoole >= 1.9.0)

Swoole\Table::incr — Increment the value by $row_key and $column_key.

説明

public Swoole\Table::incr(string $key, string $column, int $incrby = ?): void

パラメータ

key

column

incrby

戻り値


Get the key of current row.

  • ≪ Swoole\Table::incr
  • Swoole\Table::next ≫
  • PHP Manual
  • Swoole\Table
  • Get the key of current row.

Swoole\Table::key

(PECL swoole >= 1.9.0)

Swoole\Table::key — Get the key of current row.

説明

public Swoole\Table::key(): string

パラメータ

この関数にはパラメータはありません。

戻り値


Iterator the next row.

  • ≪ Swoole\Table::key
  • Swoole\Table::rewind ≫
  • PHP Manual
  • Swoole\Table
  • Iterator the next row.

Swoole\Table::next

(PECL swoole >= 1.9.0)

Swoole\Table::next — Iterator the next row.

説明

public Swoole\Table::next(): ReturnType

パラメータ

この関数にはパラメータはありません。

戻り値


Rewind the iterator.

  • ≪ Swoole\Table::next
  • Swoole\Table::set ≫
  • PHP Manual
  • Swoole\Table
  • Rewind the iterator.

Swoole\Table::rewind

(PECL swoole >= 1.9.0)

Swoole\Table::rewind — Rewind the iterator.

説明

public Swoole\Table::rewind(): void

パラメータ

この関数にはパラメータはありません。

戻り値


Update a row of the table by $row_key.

  • ≪ Swoole\Table::rewind
  • Swoole\Table::valid ≫
  • PHP Manual
  • Swoole\Table
  • Update a row of the table by $row_key.

Swoole\Table::set

(PECL swoole >= 1.9.0)

Swoole\Table::set — Update a row of the table by $row_key.

説明

public Swoole\Table::set(string $key, array $value): void

パラメータ

key

value

戻り値


Check if the current row is valid.

  • ≪ Swoole\Table::set
  • Swoole\Timer ≫
  • PHP Manual
  • Swoole\Table
  • Check if the current row is valid.

Swoole\Table::valid

(PECL swoole >= 1.9.0)

Swoole\Table::valid — Check if the current row is valid.

説明

public Swoole\Table::valid(): bool

パラメータ

この関数にはパラメータはありません。

戻り値


The Swoole\Timer class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\Timer {
/* メソッド */
public static after(int $after_time_ms, callable $callback): void
public static clear(int $timer_id): void
public static exists(int $timer_id): bool
public static tick(int $interval_ms, callable $callback, string $param = ?): void
}

目次

  • Swoole\Timer::after — Trigger a callback function after a period of time.
  • Swoole\Timer::clear — Delete a timer by timer ID.
  • Swoole\Timer::exists — Check if a timer is existed.
  • Swoole\Timer::tick — Repeats a given function at every given time-interval.


Trigger a callback function after a period of time.

  • ≪ Swoole\Timer
  • Swoole\Timer::clear ≫
  • PHP Manual
  • Swoole\Timer
  • Trigger a callback function after a period of time.

Swoole\Timer::after

(PECL swoole >= 1.9.0)

Swoole\Timer::after — Trigger a callback function after a period of time.

説明

public static Swoole\Timer::after(int $after_time_ms, callable $callback): void

Trigger a callback function after a period of time.

パラメータ

after_time_ms

callback

戻り値


Delete a timer by timer ID.

  • ≪ Swoole\Timer::after
  • Swoole\Timer::exists ≫
  • PHP Manual
  • Swoole\Timer
  • Delete a timer by timer ID.

Swoole\Timer::clear

(PECL swoole >= 1.9.0)

Swoole\Timer::clear — Delete a timer by timer ID.

説明

public static Swoole\Timer::clear(int $timer_id): void

Delete a timer by timer ID.

パラメータ

timer_id

戻り値


Check if a timer is existed.

  • ≪ Swoole\Timer::clear
  • Swoole\Timer::tick ≫
  • PHP Manual
  • Swoole\Timer
  • Check if a timer is existed.

Swoole\Timer::exists

(PECL swoole >= 1.9.0)

Swoole\Timer::exists — Check if a timer is existed.

説明

public static Swoole\Timer::exists(int $timer_id): bool

Check if a timer is existed.

パラメータ

timer_id

戻り値


Repeats a given function at every given time-interval.

  • ≪ Swoole\Timer::exists
  • Swoole\WebSocket\Frame ≫
  • PHP Manual
  • Swoole\Timer
  • Repeats a given function at every given time-interval.

Swoole\Timer::tick

(PECL swoole >= 1.9.0)

Swoole\Timer::tick — Repeats a given function at every given time-interval.

説明

public static Swoole\Timer::tick(int $interval_ms, callable $callback, string $param = ?): void

パラメータ

interval_ms

callback

param

戻り値


  • ≪ Swoole\Timer::tick
  • Swoole\WebSocket\Server ≫
  • PHP Manual
  • Swoole
  • The Swoole\WebSocket\Frame class

The Swoole\WebSocket\Frame class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\WebSocket\Frame {
/* メソッド */
}


The Swoole\WebSocket\Server class

(PECL swoole >= 1.9.0)

はじめに

クラス概要

class Swoole\WebSocket\Server extends Swoole\Http\Server {
/* メソッド */
public exist(int $fd): bool
public on(string $event_name, callable $callback): ReturnType
public static pack(
string $data,
string $opcode = ?,
string $finish = ?,
string $mask = ?
): binary
public push(
string $fd,
string $data,
string $opcode = ?,
string $finish = ?
): void
public static unpack(binary $data): string
/* 継承したメソッド */
public Swoole\Http\Server::on(string $event_name, callable $callback): void
public Swoole\Http\Server::start(): void
}

目次

  • Swoole\WebSocket\Server::exist — Check if the file descriptor exists.
  • Swoole\WebSocket\Server::on — Register event callback function
  • Swoole\WebSocket\Server::pack — Get a pack of binary data to send in a single frame.
  • Swoole\WebSocket\Server::push — Push data to the remote client.
  • Swoole\WebSocket\Server::unpack — Unpack the binary data received from the client.


Check if the file descriptor exists.

  • ≪ Swoole\WebSocket\Server
  • Swoole\WebSocket\Server::on ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Check if the file descriptor exists.

Swoole\WebSocket\Server::exist

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::exist — Check if the file descriptor exists.

説明

public Swoole\WebSocket\Server::exist(int $fd): bool

パラメータ

fd

戻り値


Register event callback function

  • ≪ Swoole\WebSocket\Server::exist
  • Swoole\WebSocket\Server::pack ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Register event callback function

Swoole\WebSocket\Server::on

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::on — Register event callback function

説明

public Swoole\WebSocket\Server::on(string $event_name, callable $callback): ReturnType

Register event callback function

パラメータ

event_name

callback

戻り値


Get a pack of binary data to send in a single frame.

  • ≪ Swoole\WebSocket\Server::on
  • Swoole\WebSocket\Server::push ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Get a pack of binary data to send in a single frame.

Swoole\WebSocket\Server::pack

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::pack — Get a pack of binary data to send in a single frame.

説明

public static Swoole\WebSocket\Server::pack(
string $data,
string $opcode = ?,
string $finish = ?,
string $mask = ?
): binary

パラメータ

data

opcode

finish

mask

戻り値


Push data to the remote client.

  • ≪ Swoole\WebSocket\Server::pack
  • Swoole\WebSocket\Server::unpack ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Push data to the remote client.

Swoole\WebSocket\Server::push

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::push — Push data to the remote client.

説明

public Swoole\WebSocket\Server::push(
string $fd,
string $data,
string $opcode = ?,
string $finish = ?
): void

パラメータ

fd

data

opcode

finish

戻り値


Unpack the binary data received from the client.

  • ≪ Swoole\WebSocket\Server::push
  • Tidy ≫
  • PHP Manual
  • Swoole\WebSocket\Server
  • Unpack the binary data received from the client.

Swoole\WebSocket\Server::unpack

(PECL swoole >= 1.9.0)

Swoole\WebSocket\Server::unpack — Unpack the binary data received from the client.

説明

public static Swoole\WebSocket\Server::unpack(binary $data): string

パラメータ

data

戻り値


Tidy

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
    • Tidy の例
  • tidy — tidy クラス
    • tidy::body — Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
    • tidy::cleanRepair — パースされたマークアップに設定に基く誤りの修正を行う
    • tidy::__construct — 新しい tidy オブジェクトを作成する
    • tidy::diagnose — パース、修正されたマークアップの診断を行う
    • tidy::$errorBuffer — 指定したドキュメントのパースで発生した警告とエラーを返す
    • tidy::getConfig — 現在の Tidy の設定を取得する
    • tidy::getHtmlVer — 指定したドキュメントで検出された HTML バージョンを取得する
    • tidy::getOpt — Tidy ドキュメントについて指定した設定オプションの値を返す
    • tidy::getOptDoc — 与えられたオプション名に対するドキュメントを返す
    • tidy::getRelease — Tidy ライブラリのリリース日 (バージョン) を取得する
    • tidy::getStatus — 指定したドキュメントのステータスを取得する
    • tidy::head — Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
    • tidy::html — Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す
    • tidy::isXhtml — ドキュメントが XHTML ドキュメントかどうかを示す
    • tidy::isXml — ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す
    • tidy::parseFile — ファイルまたは URI にあるマークアップをパースする
    • tidy::parseString — 文字列にストアされたドキュメントをパースする
    • tidy::repairFile — ファイルを修正し、それを文字列として返す
    • tidy::repairString — 別途提供される設定ファイルを使用して文字列を修正する
    • tidy::root — Tidy パースツリーのルートを表す tidyNode を返す
  • tidyNode — tidyNode クラス
    • tidyNode::__construct — private なコンストラクタのため、直接インスタンス化できません
    • tidyNode::getParent — カレントノードの親ノードを返す
    • tidyNode::hasChildren — ノードが子を持つかどうかを調べる
    • tidyNode::hasSiblings — このノードが兄弟ノードを持つかどうかを調べる
    • tidyNode::isAsp — このノードが ASP かどうかを調べる
    • tidyNode::isComment — このノードがコメントを表すものかどうかを調べる
    • tidyNode::isHtml — このノードが HTML要素 であるかどうかを調べる
    • tidyNode::isJste — このノードが JSTE であるかどうかを調べる
    • tidyNode::isPhp — このノードが PHP であるかどうかを調べる
    • tidyNode::isText — このノードが (マークアップでない) テキストであるかどうかを調べる
  • Tidy 関数
    • ob_tidyhandler — バッファを修正するための ob_start コールバック関数
    • tidy_access_count — 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
    • tidy_config_count — 指定したドキュメントについて発生した Tidy 設定エラーの数を返す
    • tidy_error_count — 指定したドキュメントについて発生した Tidy エラーの数を返す
    • tidy_get_output — パースされた Tidy マークアップを表す文字列を返す
    • tidy_warning_count — 指定したドキュメントについて発生した Tidy 警告の数を返す


はじめに

Tidy は、「Tidy HTML clean and repair utility」のバインディングです。 オブジェクト指向のモデルを使って、HTML, XHTML, XML文書の誤りを直すだけでなく、 操作することやドキュメントツリーを走査することもできます。 文書は、PHP や ASP のような組み込みスクリプト言語が入ったものも対象です。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Tidy
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

Tidyを使用するには、libtidyがインストールされている必要があります。 libtidyは、» tidyのホームページ で入手可能です。 PHP 7.1.0 以降は、HTML5 を認識する後継 » libtidy5 もかわりに使えます。 PHP 7.3.0 以降は、別のオプションとして » libtidyp も使えます。


インストール手順

この拡張モジュールは PHP にバンドルされており、configure オプション --with-tidy を指定すればインストールすることができます。


実行時設定

php.ini の設定により動作が変化します。

Tidy の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
tidy.default_config | "" | INI_SYSTEM |
tidy.clean_output | "0" | INI_USER |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

tidy.default_config string

tidy 設定ファイルへのデフォルトパス

tidy.clean_output bool

Tidy による出力の修正のオン/オフを切り替える

警告

もし動的な画像のような HTML ではないコンテンツを生成する場合、 tidy.clean_output をオンにしないでください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

それぞれの TIDY_TAG_XXX は HTML タグに相当します。 例えば、 TIDY_TAG_A は "<a href="XX">link</a>" タグに相当します。

以下の定数が定義されています。

tidy タグ定数
定数 | 備考
TIDY_TAG_UNKNOWN |
TIDY_TAG_A |
TIDY_TAG_ABBR |
TIDY_TAG_ACRONYM |
TIDY_TAG_ADDRESS |
TIDY_TAG_ALIGN |
TIDY_TAG_APPLET |
TIDY_TAG_AREA |
TIDY_TAG_ARTICLE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_ASIDE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_AUDIO | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_B |
TIDY_TAG_BASE |
TIDY_TAG_BASEFONT |
TIDY_TAG_BDI | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_BDO |
TIDY_TAG_BGSOUND |
TIDY_TAG_BIG |
TIDY_TAG_BLINK |
TIDY_TAG_BLOCKQUOTE |
TIDY_TAG_BODY |
TIDY_TAG_BR |
TIDY_TAG_BUTTON |
TIDY_TAG_CANVAS | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_CAPTION |
TIDY_TAG_CENTER |
TIDY_TAG_CITE |
TIDY_TAG_CODE |
TIDY_TAG_COL |
TIDY_TAG_COLGROUP |
TIDY_TAG_COMMAND | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_COMMENT |
TIDY_TAG_DATALIST | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_DD |
TIDY_TAG_DEL |
TIDY_TAG_DETAILS | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_DFN |
TIDY_TAG_DIALOG | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_DIR |
TIDY_TAG_DIV |
TIDY_TAG_DL |
TIDY_TAG_DT |
TIDY_TAG_EM |
TIDY_TAG_EMBED |
TIDY_TAG_FIELDSET |
TIDY_TAG_FIGCAPTION | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_FIGURE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_FONT |
TIDY_TAG_FOOTER | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_FORM |
TIDY_TAG_FRAME |
TIDY_TAG_FRAMESET |
TIDY_TAG_H1 |
TIDY_TAG_H2 |
TIDY_TAG_H3 |
TIDY_TAG_H4 |
TIDY_TAG_H5 |
TIDY_TAG_H6 |
TIDY_TAG_HEAD |
TIDY_TAG_HEADER | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_HGROUP | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_HR |
TIDY_TAG_HTML |
TIDY_TAG_I |
TIDY_TAG_IFRAME |
TIDY_TAG_ILAYER |
TIDY_TAG_IMG |
TIDY_TAG_INPUT |
TIDY_TAG_INS |
TIDY_TAG_ISINDEX |
TIDY_TAG_KBD |
TIDY_TAG_KEYGEN |
TIDY_TAG_LABEL |
TIDY_TAG_LAYER |
TIDY_TAG_LEGEND |
TIDY_TAG_LI |
TIDY_TAG_LINK |
TIDY_TAG_LISTING |
TIDY_TAG_MAIN | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_MAP |
TIDY_TAG_MARK | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_MARQUEE |
TIDY_TAG_MENU |
TIDY_TAG_MENUITEM | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_META |
TIDY_TAG_METER | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_MULTICOL |
TIDY_TAG_NAV | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_NOBR |
TIDY_TAG_NOEMBED |
TIDY_TAG_NOFRAMES |
TIDY_TAG_NOLAYER |
TIDY_TAG_NOSAVE |
TIDY_TAG_NOSCRIPT |
TIDY_TAG_OBJECT |
TIDY_TAG_OL |
TIDY_TAG_OPTGROUP |
TIDY_TAG_OPTION |
TIDY_TAG_OUTPUT | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_P |
TIDY_TAG_PARAM |
TIDY_TAG_PLAINTEXT |
TIDY_TAG_PRE |
TIDY_TAG_PROGRESS | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_Q |
TIDY_TAG_RB |
TIDY_TAG_RBC |
TIDY_TAG_RP |
TIDY_TAG_RT |
TIDY_TAG_RTC |
TIDY_TAG_RUBY |
TIDY_TAG_S |
TIDY_TAG_SAMP |
TIDY_TAG_SCRIPT |
TIDY_TAG_SECTION | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_SELECT |
TIDY_TAG_SERVER |
TIDY_TAG_SERVLET |
TIDY_TAG_SMALL |
TIDY_TAG_SOURCE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_SPACER |
TIDY_TAG_SPAN |
TIDY_TAG_STRIKE |
TIDY_TAG_STRONG |
TIDY_TAG_STYLE |
TIDY_TAG_SUB |
TIDY_TAG_SUMMARY | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_SUP |
TIDY_TAG_TABLE |
TIDY_TAG_TBODY |
TIDY_TAG_TD |
TIDY_TAG_TEMPLATE | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_TEXTAREA |
TIDY_TAG_TFOOT |
TIDY_TAG_TH |
TIDY_TAG_THEAD |
TIDY_TAG_TIME | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_TITLE |
TIDY_TAG_TR |
TIDY_TAG_TRACK | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_TT |
TIDY_TAG_U |
TIDY_TAG_UL |
TIDY_TAG_VAR |
TIDY_TAG_VIDEO | libtidy 5.0.0 で追加されました。PHP 7.4.0 以降で利用可能です
TIDY_TAG_WBR |
TIDY_TAG_XMP |

tidy ノード型定数
定数 | 説明
TIDY_NODETYPE_ROOT | ルートノード
TIDY_NODETYPE_DOCTYPE | 文章型
TIDY_NODETYPE_COMMENT | HTML コメント
TIDY_NODETYPE_PROCINS | 処理命令
TIDY_NODETYPE_TEXT | テキスト
TIDY_NODETYPE_START | 開始タグ
TIDY_NODETYPE_END | 終了タグ
TIDY_NODETYPE_STARTEND | 空タグ
TIDY_NODETYPE_CDATA | CDATA
TIDY_NODETYPE_SECTION | XML セクション
TIDY_NODETYPE_ASP | ASP コード
TIDY_NODETYPE_JSTE | JSTE コード
TIDY_NODETYPE_PHP | PHP コード
TIDY_NODETYPE_XMLDECL | XML 宣言


  • ≪ 定義済み定数
  • Tidy の例 ≫
  • PHP Manual
  • Tidy
  • 例

例

目次

  • Tidy の例


Tidy の例

このシンプルな例は、Tidy の基本的な使い方を示しています。

例1 Tidy の基本的な使用法

<?php
ob_start();
?>
<html>a html document</html>
<?php
$html = ob_get_clean();

// 設定
$config = array(
'indent' => true,
'output-xhtml' => true,
'wrap' => 200);

// Tidy
$tidy = new tidy;
$tidy->parseString($html, $config, 'utf8');
$tidy->cleanRepair();

// 出力
echo $tidy;
?>


tidy クラス

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

はじめに

HTML ファイル中の HTML ノードで、tidy が検出したものです。

クラス概要

class tidy {
/* プロパティ */
public ?string $errorBuffer = null;
public ?string $value = null;
/* メソッド */
public __construct(
?string $filename = null,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
)
public body(): ?tidyNode
public cleanRepair(): bool
public diagnose(): bool
public getConfig(): array
public getHtmlVer(): int
public getOpt(string $option): string|int|bool
public getOptDoc(string $option): string|false
public getRelease(): string
public getStatus(): int
public head(): ?tidyNode
public html(): ?tidyNode
public isXhtml(): bool
public isXml(): bool
public parseFile(
string $filename,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
): bool
public parseString(string $string, array|string|null $config = null, ?string $encoding = null): bool
public static repairFile(
string $filename,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
): string|false
public static repairString(string $string, array|string|null $config = null, ?string $encoding = null): string|false
public root(): ?tidyNode
}

プロパティ

value

ノードをHTMLで表現したもの。ノードを囲むタグを含みます。

目次

  • tidy::body — Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
  • tidy::cleanRepair — パースされたマークアップに設定に基く誤りの修正を行う
  • tidy::__construct — 新しい tidy オブジェクトを作成する
  • tidy::diagnose — パース、修正されたマークアップの診断を行う
  • tidy::$errorBuffer — 指定したドキュメントのパースで発生した警告とエラーを返す
  • tidy::getConfig — 現在の Tidy の設定を取得する
  • tidy::getHtmlVer — 指定したドキュメントで検出された HTML バージョンを取得する
  • tidy::getOpt — Tidy ドキュメントについて指定した設定オプションの値を返す
  • tidy::getOptDoc — 与えられたオプション名に対するドキュメントを返す
  • tidy::getRelease — Tidy ライブラリのリリース日 (バージョン) を取得する
  • tidy::getStatus — 指定したドキュメントのステータスを取得する
  • tidy::head — Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
  • tidy::html — Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す
  • tidy::isXhtml — ドキュメントが XHTML ドキュメントかどうかを示す
  • tidy::isXml — ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す
  • tidy::parseFile — ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString — 文字列にストアされたドキュメントをパースする
  • tidy::repairFile — ファイルを修正し、それを文字列として返す
  • tidy::repairString — 別途提供される設定ファイルを使用して文字列を修正する
  • tidy::root — Tidy パースツリーのルートを表す tidyNode を返す


Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す

  • ≪ tidy
  • tidy::cleanRepair ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す

tidy::body

tidy_get_body

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0)

tidy::body -- tidy_get_body — Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す

説明

オブジェクト指向型

public tidy::body(): ?tidyNode

手続き型

tidy_get_body(tidy $tidy): ?tidyNode

Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返します。

例

例1 tidy::getBody() の例

<?php
$html = '
<html>
<head>
<title>test</title>
</head>
<body>
<p>paragraph</p>
</body>
</html>';

$tidy = tidy_parse_string($html);

$body = $tidy->Body();
echo $body->value;
?>

上の例の出力は以下となります。

<body>
<p>paragraph</p>
</body>

参考

  • tidy::head() - Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
  • tidy::html() - Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す


パースされたマークアップに設定に基く誤りの修正を行う

  • ≪ tidy::body
  • tidy::__construct ≫
  • PHP Manual
  • tidy
  • パースされたマークアップに設定に基く誤りの修正を行う

tidy::cleanRepair

tidy_clean_repair

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::cleanRepair -- tidy_clean_repair — パースされたマークアップに設定に基く誤りの修正を行う

説明

オブジェクト指向型

public tidy::cleanRepair(): bool

手続き型

tidy_clean_repair(tidy $tidy): bool

この関数は、与えられた Tidy オブジェクト tidy を修正します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 tidy::cleanrepair() の例

<?php
$html = '<p>test</I>';

$tidy = tidy_parse_string($html);
$tidy->cleanRepair();

echo $tidy;
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title></title>
</head>
<body>
<p>test</p>
</body>
</html>

参考

  • tidy::repairFile() - ファイルを修正し、それを文字列として返す
  • tidy::repairString() - 別途提供される設定ファイルを使用して文字列を修正する


新しい tidy オブジェクトを作成する

  • ≪ tidy::cleanRepair
  • tidy::diagnose ≫
  • PHP Manual
  • tidy
  • 新しい tidy オブジェクトを作成する

tidy::__construct

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::__construct — 新しい tidy オブジェクトを作成する

説明

public tidy::__construct(
?string $filename = null,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
)

新しい tidy オブジェクトを作成します。

パラメータ

filename

もし filename パラメータが与えられた場合、 この関数はファイルを読み込み、tidy_parse_file() のように実行してファイルに基づいたオブジェクトを初期化します。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

useIncludePath

include_path からファイルを探します。

変更履歴

バージョン | 説明
8.0.0 | filename, config, encoding, useIncludePath は、nullable になりました。

例

例1 tidy::__construct() の例

<?php

$html = <<< HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head><title>title</title></head>
<body>
<p>paragraph <bt />
text</p>
</body></html>

HTML;

$tidy = new tidy();
$tidy->ParseString($html);

$tidy->cleanRepair();

if ($tidy->errorBuffer) {
echo "The following errors were detected:\n";
echo $tidy->errorBuffer;
}

?>

上の例の出力は以下となります。

The following errors were detected:
line 8 column 14 - Error: <bt> is not recognized!
line 8 column 14 - Warning: discarding unexpected <bt>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString() - 文字列にストアされたドキュメントをパースする


パース、修正されたマークアップの診断を行う

  • ≪ tidy::__construct
  • tidy::$errorBuffer ≫
  • PHP Manual
  • tidy
  • パース、修正されたマークアップの診断を行う

tidy::diagnose

tidy_diagnose

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::diagnose -- tidy_diagnose — パース、修正されたマークアップの診断を行う

説明

オブジェクト指向型

public tidy::diagnose(): bool

手続き型

tidy_diagnose(tidy $tidy): bool

与えられた Tidy オブジェクト tidy に対して診断テストを実行し、 エラーバッファにドキュメントについての情報を追加します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 tidy::diagnose() の例

<?php

$html = <<< HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<p>paragraph</p>
HTML;

$tidy = tidy_parse_string($html);
$tidy->cleanRepair();

// 2 つの出力の違いに注意
echo $tidy->errorBuffer . "\n";

$tidy->diagnose();
echo $tidy->errorBuffer;

?>

上の例の出力は以下となります。

line 4 column 1 - Warning: <p> isn't allowed in <head> elements
line 4 column 1 - Warning: inserting missing 'title' element
line 4 column 1 - Warning: <p> isn't allowed in <head> elements
line 4 column 1 - Warning: inserting missing 'title' element
Info: Doctype given is "-//W3C//DTD XHTML 1.0 Strict//EN"
Info: Document content looks like XHTML 1.0 Strict
2 warnings, 0 errors were found!

参考

  • tidy::errorBuffer()


指定したドキュメントのパースで発生した警告とエラーを返す

  • ≪ tidy::diagnose
  • tidy::getConfig ≫
  • PHP Manual
  • tidy
  • 指定したドキュメントのパースで発生した警告とエラーを返す

tidy::$errorBuffer

tidy_get_error_buffer

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::$errorBuffer -- tidy_get_error_buffer — 指定したドキュメントのパースで発生した警告とエラーを返す

説明

オブジェクト指向型 (プロパティ):

public ?string $tidy->errorBuffer;

手続き型:

tidy_get_error_buffer(tidy $tidy): string|false

指定したドキュメントのパースで発生した警告とエラーを返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

エラーバッファを文字列で返します。 バッファが空の場合は false を返します。

例

例1 tidy_get_error_buffer() の例

<?php
$html = '<p>paragraph</p>';

$tidy = tidy_parse_string($html);

echo tidy_get_error_buffer($tidy);
/* オブジェクト指向の場合 */
echo $tidy->errorBuffer;
?>

上の例の出力は以下となります。

line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 1 column 1 - Warning: inserting missing 'title' element

参考

  • tidy_access_count() - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
  • tidy_error_count() - 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_warning_count() - 指定したドキュメントについて発生した Tidy 警告の数を返す


現在の Tidy の設定を取得する

  • ≪ tidy::$errorBuffer
  • tidy::getHtmlVer ≫
  • PHP Manual
  • tidy
  • 現在の Tidy の設定を取得する

tidy::getConfig

tidy_get_config

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.7.0)

tidy::getConfig -- tidy_get_config — 現在の Tidy の設定を取得する

説明

オブジェクト指向型

public tidy::getConfig(): array

手続き型

tidy_get_config(tidy $tidy): array

与えられた Tidy オブジェクト tidy で使用されている設定オプションを配列で返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

設定オプションの配列を返します。

それぞれのオプションの説明については、» http://api.html-tidy.org/#quick-reference を参照ください。

例

例1 tidy::getConfig() の例

<?php
$html = '<p>test</p>';
$config = array('indent' => TRUE,
'output-xhtml' => TRUE,
'wrap' => 200);

$tidy = tidy_parse_string($html, $config);

print_r($tidy->getConfig());
?>

上の例の出力は以下となります。

Array
(
    [indent-spaces] => 2
    [wrap] => 200
    [tab-size] => 8
    [char-encoding] => 1
    [input-encoding] => 3
    [output-encoding] => 1
    [newline] => 1
    [doctype-mode] => 1
    [doctype] =>
    [repeated-attributes] => 1
    [alt-text] =>
    [slide-style] =>
    [error-file] =>
    [output-file] =>
    [write-back] =>
    [markup] => 1
    [show-warnings] => 1
    [quiet] =>
    [indent] => 1
    [hide-endtags] =>
    [input-xml] =>
    [output-xml] => 1
    [output-xhtml] => 1
    [output-html] =>
    [add-xml-decl] =>
    [uppercase-tags] =>
    [uppercase-attributes] =>
    [bare] =>
    [clean] =>
    [logical-emphasis] =>
    [drop-proprietary-attributes] =>
    [drop-font-tags] =>
    [drop-empty-paras] => 1
    [fix-bad-comments] => 1
    [break-before-br] =>
    [split] =>
    [numeric-entities] =>
    [quote-marks] =>
    [quote-nbsp] => 1
    [quote-ampersand] => 1
    [wrap-attributes] =>
    [wrap-script-literals] =>
    [wrap-sections] => 1
    [wrap-asp] => 1
    [wrap-jste] => 1
    [wrap-php] => 1
    [fix-backslash] => 1
    [indent-attributes] =>
    [assume-xml-procins] =>
    [add-xml-space] =>
    [enclose-text] =>
    [enclose-block-text] =>
    [keep-time] =>
    [word-2000] =>
    [tidy-mark] =>
    [gnu-emacs] =>
    [gnu-emacs-file] =>
    [literal-attributes] =>
    [show-body-only] =>
    [fix-uri] => 1
    [lower-literals] => 1
    [hide-comments] =>
    [indent-cdata] =>
    [force-output] => 1
    [show-errors] => 6
    [ascii-chars] => 1
    [join-classes] =>
    [join-styles] => 1
    [escape-cdata] =>
    [language] =>
    [ncr] => 1
    [output-bom] => 2
    [replace-color] =>
    [css-prefix] =>
    [new-inline-tags] =>
    [new-blocklevel-tags] =>
    [new-empty-tags] =>
    [new-pre-tags] =>
    [accessibility-check] => 0
    [vertical-space] =>
    [punctuation-wrap] =>
    [merge-divs] => 1
)

参考

  • tidy_reset_config()
  • tidy_save_config()


指定したドキュメントで検出された HTML バージョンを取得する

  • ≪ tidy::getConfig
  • tidy::getOpt ≫
  • PHP Manual
  • tidy
  • 指定したドキュメントで検出された HTML バージョンを取得する

tidy::getHtmlVer

tidy_get_html_ver

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getHtmlVer -- tidy_get_html_ver — 指定したドキュメントで検出された HTML バージョンを取得する

説明

オブジェクト指向型

public tidy::getHtmlVer(): int

手続き型

tidy_get_html_ver(tidy $tidy): int

指定した Tidy オブジェクト tidy で検出された HTML バージョンを返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

出された HTML バージョンを返します。

警告

この関数は Tidylib 自体でまだ実装されていません。そのため常に 0 を返します。


Tidy ドキュメントについて指定した設定オプションの値を返す

  • ≪ tidy::getHtmlVer
  • tidy::getOptDoc ≫
  • PHP Manual
  • tidy
  • Tidy ドキュメントについて指定した設定オプションの値を返す

tidy::getOpt

tidy_getopt

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getOpt -- tidy_getopt — Tidy ドキュメントについて指定した設定オプションの値を返す

説明

オブジェクト指向型

public tidy::getOpt(string $option): string|int|bool

手続き型

tidy_getopt(tidy $tidy, string $option): string|int|bool

Tidy オブジェクト tidy について指定した設定オプション option の値を返します。

パラメータ

tidy

Tidy オブジェクト。

option

それぞれの設定オプションと型の一覧は、» http://api.html-tidy.org/#quick-reference にあります。

戻り値

指定した設定オプション option の値を返します。 返される型は、設定オプションの型に依存します。

例

例1 tidy_getopt() の例

<?php

$html ='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Title</title></head>
<body>

<p><img src="img.png"></p>

</body></html>';

$config = array('accessibility-check' => 3,
'alt-text' => 'some text');

$tidy = new tidy();
$tidy->parseString($html, $config);

var_dump($tidy->getOpt('accessibility-check')); //integer
var_dump($tidy->getOpt('lower-literals')); //boolean
var_dump($tidy->getOpt('alt-text')); //string

?>

上の例の出力は以下となります。

int(3)
bool(true)
string(9) "some text"


与えられたオプション名に対するドキュメントを返す

  • ≪ tidy::getOpt
  • tidy::getRelease ≫
  • PHP Manual
  • tidy
  • 与えられたオプション名に対するドキュメントを返す

tidy::getOptDoc

tidy_get_opt_doc

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

tidy::getOptDoc -- tidy_get_opt_doc — 与えられたオプション名に対するドキュメントを返す

説明

オブジェクト指向型

public tidy::getOptDoc(string $option): string|false

手続き型

tidy_get_opt_doc(tidy $tidy, string $option): string|false

tidy_get_opt_doc() は、 与えられたオプション名に対するドキュメントを返します。

注意:

この関数を有効にするには、少なくとも2005年4月25日以降の libtidy が必要です。

パラメータ

tidy

Tidy オブジェクト。

option

オプション名。

戻り値

オプションが存在し、かつドキュメントが利用可能であれば、文字列を返します。 その他の場合は false を返します。

例

例1 すべてのオプションについてのドキュメントとデフォルト値をプリントする

<?php

$tidy = new tidy;
$config = $tidy->getConfig();

ksort($config);

foreach ($config as $opt => $val) {

if (!$doc = $tidy->getOptDoc($opt))
$doc = 'no documentation available!';

$val = ($tidy->getOpt($opt) === true) ? 'true' : $val;
$val = ($tidy->getOpt($opt) === false) ? 'false' : $val;

echo "<p><b>$opt</b> (default: '$val')<br />".
"$doc</p><hr />\n";
}

?>

参考

  • tidy::getconfig() - 現在の Tidy の設定を取得する
  • tidy::getopt() - Tidy ドキュメントについて指定した設定オプションの値を返す


Tidy ライブラリのリリース日 (バージョン) を取得する

  • ≪ tidy::getOptDoc
  • tidy::getStatus ≫
  • PHP Manual
  • tidy
  • Tidy ライブラリのリリース日 (バージョン) を取得する

tidy::getRelease

tidy_get_release

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getRelease -- tidy_get_release — Tidy ライブラリのリリース日 (バージョン) を取得する

説明

オブジェクト指向型

public tidy::getRelease(): string

手続き型

tidy_get_release(): string

Tidy ライブラリのリリース日を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Tidy ライブラリのリリース日を文字列で返します。 'unknown' が返される可能性もあります。


指定したドキュメントのステータスを取得する

  • ≪ tidy::getRelease
  • tidy::head ≫
  • PHP Manual
  • tidy
  • 指定したドキュメントのステータスを取得する

tidy::getStatus

tidy_get_status

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::getStatus -- tidy_get_status — 指定したドキュメントのステータスを取得する

説明

オブジェクト指向型

public tidy::getStatus(): int

手続き型

tidy_get_status(tidy $tidy): int

指定した Tidy オブジェクト tidy のステータスを返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

エラー/警告が発生しなかった場合は 0、 警告やアクセイシビリティエラーの場合は 1、 エラーの場合は 2 を返します。

例

例1 tidy::getStatus() の例

<?php
$html = '<p>paragraph</i>';
$tidy = new tidy();
$tidy->parseString($html);

$tidy2 = new tidy();
$html2 = '<bogus>test</bogus>';
$tidy2->parseString($html2);

echo $tidy->getStatus(); //1

echo $tidy2->getStatus(); //2
?>


Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

  • ≪ tidy::getStatus
  • tidy::html ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

tidy::head

tidy_get_head

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0.0)

tidy::head -- tidy_get_head — Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す

説明

オブジェクト指向型

public tidy::head(): ?tidyNode

手続き型

tidy_get_head(tidy $tidy): ?tidyNode

Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

tidyNode オブジェクトを返します。

例

例1 tidy::head() の例

<?php
$html = '
<html>
<head>
<title>test</title>
</head>
<body>
<p>paragraph</p>
</body>
</html>';

$tidy = tidy_parse_string($html);

$head = $tidy->head();
echo $head->value;
?>

上の例の出力は以下となります。

<head>
<title>test</title>
</head>

参考

  • tidy::body() - Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
  • tidy::html() - Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す


Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

  • ≪ tidy::head
  • tidy::isXhtml ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

tidy::html

tidy_get_html

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0.0)

tidy::html -- tidy_get_html — Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す

説明

オブジェクト指向型

public tidy::html(): ?tidyNode

手続き型

tidy_get_html(tidy $tidy): ?tidyNode

この関数は Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

tidyNode オブジェクトを返します。

例

例1 tidy::html() の例

<?php
$html = '
<html>
<head>
<title>test</title>
</head>
<body>
<p>paragraph</p>
</body>
</html>';

$tidy = tidy_parse_string($html);

$html = $tidy->html();
echo $html->value;
?>

上の例の出力は以下となります。

<html>
<head>
<title>test</title>
</head>
<body>
<p>paragraph</p>
</body>
</html>

参考

  • tidy::body() - Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
  • tidy::head() - Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す


ドキュメントが XHTML ドキュメントかどうかを示す

  • ≪ tidy::html
  • tidy::isXml ≫
  • PHP Manual
  • tidy
  • ドキュメントが XHTML ドキュメントかどうかを示す

tidy::isXhtml

tidy_is_xhtml

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::isXhtml -- tidy_is_xhtml — ドキュメントが XHTML ドキュメントかどうかを示す

説明

オブジェクト指向型

public tidy::isXhtml(): bool

手続き型

tidy_is_xhtml(tidy $tidy): bool

ドキュメントが XHTML ドキュメントであるかどうかを調べます。

パラメータ

tidy

Tidy オブジェクト。

戻り値

指定した Tidy オブジェクト tidy が XHTML ドキュメントの場合、この関数は true を返します。 その他の場合は false を返します。

警告

この関数はまだ Tidylib 自身に実装されていません。 なので、常に false を返します。


ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す

  • ≪ tidy::isXhtml
  • tidy::parseFile ≫
  • PHP Manual
  • tidy
  • ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す

tidy::isXml

tidy_is_xml

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::isXml -- tidy_is_xml — ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す

説明

オブジェクト指向型

public tidy::isXml(): bool

手続き型

tidy_is_xml(tidy $tidy): bool

ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを調べます。

パラメータ

tidy

Tidy オブジェクト。

戻り値

指定した Tidy オブジェクト tidy が一般的な XML ドキュメント (非 HTML/XHTML) の場合、 この関数は true を返します。 その他の場合は false を返します。

警告

この関数はまだ Tidylib 自身に実装されていません。 なので、常に false を返します。


ファイルまたは URI にあるマークアップをパースする

  • ≪ tidy::isXml
  • tidy::parseString ≫
  • PHP Manual
  • tidy
  • ファイルまたは URI にあるマークアップをパースする

tidy::parseFile

tidy_parse_file

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::parseFile -- tidy_parse_file — ファイルまたは URI にあるマークアップをパースする

説明

オブジェクト指向型

public tidy::parseFile(
string $filename,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
): bool

手続き型

tidy_parse_file(
string $filename,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
): tidy|false

与えられたファイルをパースします。

パラメータ

filename

もし filename パラメータが与えられた場合、 この関数はファイルを読み込み、tidy_parse_file() のように実行してファイルに基づいたオブジェクトを初期化します。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

useIncludePath

include_path からファイルを探します。

戻り値

tidy::parseFile() は成功時に true を返します。 tidy_parse_file() は、成功時に新しい tidy インスタンスを返します。 これらのメソッド、関数は、ともに失敗時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | config と encoding は、 nullable になりました。

例

例1 tidy::parseFile() の例

<?php
$tidy = new tidy();
$tidy->parseFile('file.html');

$tidy->cleanRepair();

if(!empty($tidy->errorBuffer)) {
echo "The following errors or warnings occurred:\n";
echo $tidy->errorBuffer;
}
?>

参考

  • tidy::parsestring() - 文字列にストアされたドキュメントをパースする
  • tidy::repairfile() - ファイルを修正し、それを文字列として返す
  • tidy::repairstring() - 別途提供される設定ファイルを使用して文字列を修正する


文字列にストアされたドキュメントをパースする

  • ≪ tidy::parseFile
  • tidy::repairFile ≫
  • PHP Manual
  • tidy
  • 文字列にストアされたドキュメントをパースする

tidy::parseString

tidy_parse_string

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy::parseString -- tidy_parse_string — 文字列にストアされたドキュメントをパースする

説明

オブジェクト指向型

public tidy::parseString(string $string, array|string|null $config = null, ?string $encoding = null): bool

手続き型

tidy_parse_string(string $string, array|string|null $config = null, ?string $encoding = null): tidy|false

文字列にストアされたドキュメントをパースします。

パラメータ

string

パースするデータ。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

戻り値

新しい tidy インスタンスを返します。 tidy_parse_string() は、成功時に新しい tidy インスタンスを返します。 これらのメソッド、関数は、失敗時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | config と encoding は、nullable になりました。

例

例1 tidy::parseString() の例

<?php
ob_start();
?>

<html>
<head>
<title>test</title>
</head>
<body>
<p>error<br>another line</i>
</body>
</html>

<?php

$buffer = ob_get_clean();
$config = array('indent' => TRUE,
'output-xhtml' => TRUE,
'wrap' => 200);

$tidy = tidy_parse_string($buffer, $config, 'UTF8');

$tidy->cleanRepair();
echo $tidy;
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>
      test
    </title>
  </head>
  <body>
    <p>
      error<br />
      another line
    </p>
  </body>
</html>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::repairFile() - ファイルを修正し、それを文字列として返す
  • tidy::repairString() - 別途提供される設定ファイルを使用して文字列を修正する


ファイルを修正し、それを文字列として返す

  • ≪ tidy::parseString
  • tidy::repairString ≫
  • PHP Manual
  • tidy
  • ファイルを修正し、それを文字列として返す

tidy::repairFile

tidy_repair_file

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.7.0)

tidy::repairFile -- tidy_repair_file — ファイルを修正し、それを文字列として返す

説明

オブジェクト指向型

public static tidy::repairFile(
string $filename,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
): string|false

手続き型

tidy_repair_file(
string $filename,
array|string|null $config = null,
?string $encoding = null,
bool $useIncludePath = false
): string|false

与えられたファイルを修正し、それを文字列として返します。

パラメータ

filename

修正するファイル。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は http://tidy.sourceforge.net/docs/quickref.html を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

useIncludePath

include_path からファイルを探します。

戻り値

修正した内容を文字列で返します。

例

例1 tidy::repairFile() の例

<?php
$file = 'file.html';

$tidy = new tidy();
$repaired = $tidy->repairfile($file);
rename($file, $file . '.bak');

file_put_contents($file, $repaired);
?>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString() - 文字列にストアされたドキュメントをパースする
  • tidy::repairString() - 別途提供される設定ファイルを使用して文字列を修正する


別途提供される設定ファイルを使用して文字列を修正する

  • ≪ tidy::repairFile
  • tidy::root ≫
  • PHP Manual
  • tidy
  • 別途提供される設定ファイルを使用して文字列を修正する

tidy::repairString

tidy_repair_string

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.7.0)

tidy::repairString -- tidy_repair_string — 別途提供される設定ファイルを使用して文字列を修正する

説明

オブジェクト指向型

public static tidy::repairString(string $string, array|string|null $config = null, ?string $encoding = null): string|false

手続き型

tidy_repair_string(string $string, array|string|null $config = null, ?string $encoding = null): string|false

与えられた文字列を修正します。

パラメータ

string

修正するデータ。

config

config には配列あるいは文字列を渡します。 文字列を渡した場合は設定ファイルの名前、 それ以外の場合は設定そのものとして解釈されます。

オプションについての説明は » http://api.html-tidy.org/#quick-reference を参照ください。

encoding

encoding は入出力ドキュメントのエンコーディングを設定します。 指定できるエンコーディング名は ascii、latin0、latin1、 raw、utf8、iso2022、 mac、win1252、ibm858、 utf16、utf16le、utf16be、 big5 および shiftjis です。

戻り値

修正した文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | tidy::repairString() は、staticメソッドになりました。
8.0.0 | config と encoding は、 nullable になりました。
8.0.0 | この関数は、 useIncludePath を引数として受け入れなくなりました。

例

例1 tidy::repairString() の例

<?php
ob_start();
?>

<html>
<head>
<title>test</title>
</head>
<body>
<p>error</i>
</body>
</html>

<?php

$buffer = ob_get_clean();
$tidy = new tidy();
$clean = $tidy->repairString($buffer);

echo $clean;
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>test</title>
</head>
<body>
<p>error</p>
</body>
</html>

参考

  • tidy::parseFile() - ファイルまたは URI にあるマークアップをパースする
  • tidy::parseString() - 文字列にストアされたドキュメントをパースする
  • tidy::repairFile() - ファイルを修正し、それを文字列として返す


Tidy パースツリーのルートを表す tidyNode を返す

  • ≪ tidy::repairString
  • tidyNode ≫
  • PHP Manual
  • tidy
  • Tidy パースツリーのルートを表す tidyNode を返す

tidy::root

tidy_get_root

(PHP 5, PHP 7, PHP 8, PECL tidy 0.5.2-1.0.0)

tidy::root -- tidy_get_root — Tidy パースツリーのルートを表す tidyNode を返す

説明

オブジェクト指向型

public tidy::root(): ?tidyNode

手続き型

tidy_get_root(tidy $tidy): ?tidyNode

Tidy パースツリーのルートを表す tidyNode を返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

tidyNode オブジェクトを返します。

例

例1 tidy::root() の例

<?php

$html = <<< HTML
<html><body>

<p>paragraph</p>
<br/>

</body></html>
HTML;

$tidy = tidy_parse_string($html);
dump_nodes($tidy->root(), 1);

function dump_nodes($node, $indent) {

if($node->hasChildren()) {
foreach($node->child as $child) {
echo str_repeat('.', $indent*2) . ($child->name ? $child->name : '"'.$child->value.'"'). "\n";

dump_nodes($child, $indent+1);
}
}
}
?>

上の例の出力は以下となります。

..html
....head
......title
....body
......p
........"paragraph"
......br


tidyNode クラス

(PHP 5, PHP 7, PHP 8)

はじめに

HTML ファイル中の HTML ノードで、tidy が検出したものです。

クラス概要

final class tidyNode {
/* プロパティ */
public readonly string $value;
public readonly string $name;
public readonly int $type;
public readonly int $line;
public readonly int $column;
public readonly bool $proprietary;
public readonly ?int $id;
public readonly ?array $attribute;
public readonly ?array $child;
/* メソッド */
private __construct()
public getParent(): ?tidyNode
public hasChildren(): bool
public hasSiblings(): bool
public isAsp(): bool
public isComment(): bool
public isHtml(): bool
public isJste(): bool
public isPhp(): bool
public isText(): bool
}

プロパティ

value

まわりのタグも含む、ノードの HTML 表現

name

HTML ノードの名前

type

ノードの型 (tidy ノード型定数 のうちのひとつ。たとえば TIDY_NODETYPE_PHP)

line

ファイル内でそのタグが存在する行番号

column

ファイル内でそのタグが存在するカラム番号

proprietary

そのノードが独自タグであるかどうかを表す

id

ノードの ID (tag 定数のうちのひとつで、たとえば TIDY_TAG_FRAME)

attribute

現在のノードの属性名 (キー) を表す文字列の配列

child

現在のノードの子を表す tidyNode の配列

目次

  • tidyNode::__construct — private なコンストラクタのため、直接インスタンス化できません
  • tidyNode::getParent — カレントノードの親ノードを返す
  • tidyNode::hasChildren — ノードが子を持つかどうかを調べる
  • tidyNode::hasSiblings — このノードが兄弟ノードを持つかどうかを調べる
  • tidyNode::isAsp — このノードが ASP かどうかを調べる
  • tidyNode::isComment — このノードがコメントを表すものかどうかを調べる
  • tidyNode::isHtml — このノードが HTML要素 であるかどうかを調べる
  • tidyNode::isJste — このノードが JSTE であるかどうかを調べる
  • tidyNode::isPhp — このノードが PHP であるかどうかを調べる
  • tidyNode::isText — このノードが (マークアップでない) テキストであるかどうかを調べる


private なコンストラクタのため、直接インスタンス化できません

  • ≪ tidyNode
  • tidyNode::getParent ≫
  • PHP Manual
  • tidyNode
  • private なコンストラクタのため、直接インスタンス化できません

tidyNode::__construct

(PHP 5, PHP 7, PHP 8)

tidyNode::__construct — private なコンストラクタのため、直接インスタンス化できません

説明

private tidyNode::__construct()

パラメータ

この関数にはパラメータはありません。


カレントノードの親ノードを返す

  • ≪ tidyNode::__construct
  • tidyNode::hasChildren ≫
  • PHP Manual
  • tidyNode
  • カレントノードの親ノードを返す

tidyNode::getParent

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

tidyNode::getParent — カレントノードの親ノードを返す

説明

public tidyNode::getParent(): ?tidyNode

カレントノードの親ノードを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

そのノードが親を持っている場合に tidyNode、 それ以外の場合に null を返します。

例

例1 tidyNode::getParent() の例

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>
Hello World
</body>
</html>

HTML;

$tidy = tidy_parse_string($html);
$num = 0;

$node = $tidy->html()->child[0]->child[0];

var_dump($node->getParent()->name);
?>

上の例の出力は以下となります。

string(4) "head"


ノードが子を持つかどうかを調べる

  • ≪ tidyNode::getParent
  • tidyNode::hasSiblings ≫
  • PHP Manual
  • tidyNode
  • ノードが子を持つかどうかを調べる

tidyNode::hasChildren

(PHP 5, PHP 7, PHP 8)

tidyNode::hasChildren — ノードが子を持つかどうかを調べる

説明

public tidyNode::hasChildren(): bool

ノードが子を持つかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードが子を持つ場合に true、それ以外の場合に false を返します。

例

例1 tidyNode::hasChildren() の例

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

// the head tag
var_dump($tidy->html()->child[0]->hasChildren());

// the php inside the head tag
var_dump($tidy->html()->child[0]->child[0]->hasChildren());

?>

上の例の出力は以下となります。

bool(true)
bool(false)


このノードが兄弟ノードを持つかどうかを調べる

  • ≪ tidyNode::hasChildren
  • tidyNode::isAsp ≫
  • PHP Manual
  • tidyNode
  • このノードが兄弟ノードを持つかどうかを調べる

tidyNode::hasSiblings

(PHP 5, PHP 7, PHP 8)

tidyNode::hasSiblings — このノードが兄弟ノードを持つかどうかを調べる

説明

public tidyNode::hasSiblings(): bool

ノードが兄弟ノードを持つかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

兄弟ノードを持つ場合に true、それ以外の場合に false を返します。

例

例1 tidyNode::hasSiblings() の例

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

// the html tag
var_dump($tidy->html()->hasSiblings());

// the head tag
var_dump($tidy->html()->child[0]->hasSiblings());

?>

上の例の出力は以下となります。

bool(false)
bool(true)


このノードが ASP かどうかを調べる

  • ≪ tidyNode::hasSiblings
  • tidyNode::isComment ≫
  • PHP Manual
  • tidyNode
  • このノードが ASP かどうかを調べる

tidyNode::isAsp

(PHP 5, PHP 7, PHP 8)

tidyNode::isAsp — このノードが ASP かどうかを調べる

説明

public tidyNode::isAsp(): bool

現在のノードが ASP かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードが ASP の場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからの ASP コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

// check if the current node is of requested type
if($node->isAsp()) {
echo "\n\n# asp node #" . ++$GLOBALS['num'] . "\n";
echo $node->value;
}

// check if the current node has childrens
if($node->hasChildren()) {
foreach($node->child as $child) {
get_nodes($child);
}
}
}

?>

上の例の出力は以下となります。

# asp node #1
<%
  /* ASP code */
  response.write("Hello World!")
%>


このノードがコメントを表すものかどうかを調べる

  • ≪ tidyNode::isAsp
  • tidyNode::isHtml ≫
  • PHP Manual
  • tidyNode
  • このノードがコメントを表すものかどうかを調べる

tidyNode::isComment

(PHP 5, PHP 7, PHP 8)

tidyNode::isComment — このノードがコメントを表すものかどうかを調べる

説明

public tidyNode::isComment(): bool

このノードがコメントであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

このノードがコメントである場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからのコメントの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

// check if the current node is of requested type
if($node->isComment()) {
echo "\n\n# comment node #" . ++$GLOBALS['num'] . "\n";
echo $node->value;
}

// check if the current node has childrens
if($node->hasChildren()) {
foreach($node->child as $child) {
get_nodes($child);
}
}
}

?>

上の例の出力は以下となります。

# comment node #1
<!-- Comments -->


このノードが HTML要素 であるかどうかを調べる

  • ≪ tidyNode::isComment
  • tidyNode::isJste ≫
  • PHP Manual
  • tidyNode
  • このノードが HTML要素 であるかどうかを調べる

tidyNode::isHtml

(PHP 5, PHP 7, PHP 8)

tidyNode::isHtml — このノードが HTML要素 であるかどうかを調べる

説明

public tidyNode::isHtml(): bool

このノードが ルート要素 以外の HTML要素 であるかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードが ルート要素 以外の HTML要素 である場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
7.3.24, 7.4.12 | 適切な振る舞いをするように修正されました。 これより前のバージョンでは、ほとんど全てのノードをHTML要素だと報告していました。

例

例1 HTML ドキュメントからの HTML コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {
// check if the current node is of requested type
if($node->isHtml()) {
echo "\n\n# html node #" . ++$GLOBALS['num'] . "\n";
echo $node->value;
}

// check if the current node has childrens
if($node->hasChildren()) {
foreach($node->child as $child) {
get_nodes($child);
}
}
}

?>

上の例の出力は以下となります。

# html node #1
<html>
<head>
<?php echo '<title>title</title>'; ?><#
  /* JSTE code */
  alert('Hello World');
#>
<title></title>
</head>
<body>
<?php
  // PHP code
  echo 'hello world!';
?><%
  /* ASP code */
  response.write("Hello World!")
%><!-- Comments -->
Hello WorldOutside HTML
</body>
</html>

# html node #2
<head>
<?php echo '<title>title</title>'; ?><#
  /* JSTE code */
  alert('Hello World');
#>
<title></title>
</head>

# html node #3
<title></title>

# html node #4
<body>
<?php
  // PHP code
  echo 'hello world!';
?><%
  /* ASP code */
  response.write("Hello World!")
%><!-- Comments -->
Hello WorldOutside HTML
</body>


このノードが JSTE であるかどうかを調べる

  • ≪ tidyNode::isHtml
  • tidyNode::isPhp ≫
  • PHP Manual
  • tidyNode
  • このノードが JSTE であるかどうかを調べる

tidyNode::isJste

(PHP 5, PHP 7, PHP 8)

tidyNode::isJste — このノードが JSTE であるかどうかを調べる

説明

public tidyNode::isJste(): bool

このノードが JSTE であるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードが JSTE である場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからの JSTE コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

// check if the current node is of requested type
if($node->isJste()) {
echo "\n\n# jste node #" . ++$GLOBALS['num'] . "\n";
echo $node->value;
}

// check if the current node has childrens
if($node->hasChildren()) {
foreach($node->child as $child) {
get_nodes($child);
}
}
}

?>

上の例の出力は以下となります。

# jste node #1
<#
  /* JSTE code */
  alert('Hello World');
#>


このノードが PHP であるかどうかを調べる

  • ≪ tidyNode::isJste
  • tidyNode::isText ≫
  • PHP Manual
  • tidyNode
  • このノードが PHP であるかどうかを調べる

tidyNode::isPhp

(PHP 5, PHP 7, PHP 8)

tidyNode::isPhp — このノードが PHP であるかどうかを調べる

説明

public tidyNode::isPhp(): bool

このノードが PHP であるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードが PHP コードである場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからの PHP コードの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

// check if the current node is of requested type
if($node->isPhp()) {
echo "\n\n# php node #" . ++$GLOBALS['num'] . "\n";
echo $node->value;
}

// check if the current node has childrens
if($node->hasChildren()) {
foreach($node->child as $child) {
get_nodes($child);
}
}
}

?>

上の例の出力は以下となります。

# php node #1
<?php echo '<title>title</title>'; ?>

# php node #2
<?php
  // PHP code
  echo 'hello world!';
?>


このノードが (マークアップでない) テキストであるかどうかを調べる

  • ≪ tidyNode::isPhp
  • Tidy 関数 ≫
  • PHP Manual
  • tidyNode
  • このノードが (マークアップでない) テキストであるかどうかを調べる

tidyNode::isText

(PHP 5, PHP 7, PHP 8)

tidyNode::isText — このノードが (マークアップでない) テキストであるかどうかを調べる

説明

public tidyNode::isText(): bool

このノードが (マークアップされていない) テキストであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードがテキストを著す場合に true、それ以外の場合に false を返します。

例

例1 HTML ドキュメントからのテキストの抽出

<?php

$html = <<< HTML
<html><head>
<?php echo '<title>title</title>'; ?>
<#
/* JSTE code */
alert('Hello World');
#>
</head>
<body>

<?php
// PHP code
echo 'hello world!';
?>

<%
/* ASP code */
response.write("Hello World!")
%>

<!-- Comments -->
Hello World
</body></html>
Outside HTML
HTML;

$tidy = tidy_parse_string($html);
$num = 0;

get_nodes($tidy->html());

function get_nodes($node) {

// check if the current node is of requested type
if($node->isText()) {
echo "\n\n# text node #" . ++$GLOBALS['num'] . "\n";
echo $node->value;
}

// check if the current node has childrens
if($node->hasChildren()) {
foreach($node->child as $child) {
get_nodes($child);
}
}
}

?>

上の例の出力は以下となります。

# text node #1
Hello World

# text node #2
Outside HTML


Tidy 関数

目次

  • ob_tidyhandler — バッファを修正するための ob_start コールバック関数
  • tidy_access_count — 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
  • tidy_config_count — 指定したドキュメントについて発生した Tidy 設定エラーの数を返す
  • tidy_error_count — 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_get_output — パースされた Tidy マークアップを表す文字列を返す
  • tidy_warning_count — 指定したドキュメントについて発生した Tidy 警告の数を返す


バッファを修正するための ob_start コールバック関数

  • ≪ Tidy 関数
  • tidy_access_count ≫
  • PHP Manual
  • Tidy 関数
  • バッファを修正するための ob_start コールバック関数

ob_tidyhandler

(PHP 5, PHP 7, PHP 8)

ob_tidyhandler — バッファを修正するための ob_start コールバック関数

説明

ob_tidyhandler(string $input, int $mode = ?): string

バッファを修正するための ob_start() コールバック関数です。

パラメータ

input

バッファ。

mode

バッファのモード。

戻り値

修正したバッファを返します。

例

例1 ob_tidyhandler() の例

<?php
ob_start('ob_tidyhandler');

echo '<p>test</i>';
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title></title>
</head>
<body>
<p>test</p>
</body>
</html>

参考

  • ob_start() - 出力のバッファリングを有効にする


指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

  • ≪ ob_tidyhandler
  • tidy_config_count ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

tidy_access_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_access_count — 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す

説明

tidy_access_count(tidy $tidy): int

tidy_access_count() は、 指定したドキュメントについて発生した Tidy アクセシビリティ警告の数を返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

警告の数を返します。

例

例1 tidy_access_count() の例

<?php

$html ='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Title</title></head>
<body>

<p><img src="img.png"></p>

</body></html>';

// アクセシビリティチェックのレベルを選択する: 1, 2 あるいは 3
$config = array('accessibility-check' => 3);

$tidy = new tidy();
$tidy->parseString($html, $config);
$tidy->cleanRepair();

/* これをコールすることを忘れないように! */
$tidy->diagnose();

echo tidy_access_count($tidy); //5

?>

注意

注意:

TidyLib の設計のため、tidy_access_count() の前に tidy_diagnose() をコールしなければなりません。 さもないと、常に 0 が返されます。 また、accessibility-check オプションを有効にしなければなりません。

参考

  • tidy_error_count() - 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_warning_count() - 指定したドキュメントについて発生した Tidy 警告の数を返す


指定したドキュメントについて発生した Tidy 設定エラーの数を返す

  • ≪ tidy_access_count
  • tidy_error_count ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生した Tidy 設定エラーの数を返す

tidy_config_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_config_count — 指定したドキュメントについて発生した Tidy 設定エラーの数を返す

説明

tidy_config_count(tidy $tidy): int

指定した Tidy オブジェクト tidy の設定時に発生した Tidy エラーの数を返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

エラーの数を返します。

例

例1 tidy_config_count() の例

<?php
$html = '<p>test</I>';

$config = array('doctype' => 'bogus');

$tidy = tidy_parse_string($html, $config);

/* 'bogus' は有効な文章型でないので、1 を出力する */
echo tidy_config_count($tidy);
?>


指定したドキュメントについて発生した Tidy エラーの数を返す

  • ≪ tidy_config_count
  • tidy_get_output ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生した Tidy エラーの数を返す

tidy_error_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_error_count — 指定したドキュメントについて発生した Tidy エラーの数を返す

説明

tidy_error_count(tidy $tidy): int

指定したドキュメントについて発生した Tidy エラーの数を返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

エラーの数を返します。

例

例1 tidy_error_count() の例

<?php
$html = '<p>test</i>
<bogustag>bogus</bogustag>';

$tidy = tidy_parse_string($html);

echo tidy_error_count($tidy) . "\n"; //1

echo $tidy->errorBuffer;
?>

上の例の出力は以下となります。

1
line 1 column 1 - Warning: missing <!DOCTYPE> declaration
line 1 column 8 - Warning: discarding unexpected </i>
line 2 column 1 - Error: <bogustag> is not recognized!
line 2 column 1 - Warning: discarding unexpected <bogustag>
line 2 column 16 - Warning: discarding unexpected </bogustag>
line 1 column 1 - Warning: inserting missing 'title' element

参考

  • tidy_access_count() - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
  • tidy_warning_count() - 指定したドキュメントについて発生した Tidy 警告の数を返す


パースされた Tidy マークアップを表す文字列を返す

  • ≪ tidy_error_count
  • tidy_warning_count ≫
  • PHP Manual
  • Tidy 関数
  • パースされた Tidy マークアップを表す文字列を返す

tidy_get_output

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_get_output — パースされた Tidy マークアップを表す文字列を返す

説明

tidy_get_output(tidy $tidy): string

修正された HTML を文字列で返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

修正された HTML を文字列で返します。

例

例1 tidy_get_output() の例

<?php

$html = '<p>paragraph</i>';
$tidy = tidy_parse_string($html);

$tidy->cleanRepair();

echo tidy_get_output($tidy);
?>

上の例の出力は以下となります。

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title></title>
</head>
<body>
<p>paragraph</p>
</body>
</html>


指定したドキュメントについて発生した Tidy 警告の数を返す

  • ≪ tidy_get_output
  • Tokenizer ≫
  • PHP Manual
  • Tidy 関数
  • 指定したドキュメントについて発生した Tidy 警告の数を返す

tidy_warning_count

(PHP 5, PHP 7, PHP 8, PECL tidy >= 0.5.2)

tidy_warning_count — 指定したドキュメントについて発生した Tidy 警告の数を返す

説明

tidy_warning_count(tidy $tidy): int

指定したドキュメントについて発生した Tidy 警告の数を返します。

パラメータ

tidy

Tidy オブジェクト。

戻り値

警告の数を返します。

例

例1 tidy_warning_count() の例

<?php
$html = '<p>test</i>
<bogustag>bogus</bogustag>';

$tidy = tidy_parse_string($html);

echo tidy_error_count($tidy) . "\n"; //1
echo tidy_warning_count($tidy) . "\n"; //5
?>

参考

  • tidy_error_count() - 指定したドキュメントについて発生した Tidy エラーの数を返す
  • tidy_access_count() - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す


Tokenizer

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
  • 例
  • PhpToken — PhpToken クラス
    • PhpToken::__construct — 新しい PhpToken オブジェクトを返す
    • PhpToken::getTokenName — トークンの名前を返す
    • PhpToken::is — 指定された種類のトークンかを調べる
    • PhpToken::isIgnorable — トークンがPHPパーサから無視されるかを調べる
    • PhpToken::__toString — トークンの文字列表現を返す
    • PhpToken::tokenize — ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
  • Tokenizer 関数
    • token_get_all — 指定したソースを PHP トークンに分割する
    • token_name — 指定した PHP トークンのシンボル名を取得する


はじめに

tokenizer 関数は、Zend Engine に組み込まれた PHP tokenizer へのインターフェイスを提供します。以下の関数により、 字句解析レベルの言語処理を行うことなく、 PHP ソースを解析/修正するツールを作成することが可能となります。

トークンに関する付録も参照ください。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Tokenizer
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-tokenizer

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


定義済み定数

この拡張モジュールを組み込んで PHP をコンパイルするか、あるいは実行時に 動的にモジュールを読み込むと、パーサトークンの一覧 に挙げられている トークンが定数として定義されます。

定数 | 説明
TOKEN_PARSE (int) | 特定の文脈で、予約語を使う能力を認識します。


例

以下に tokenizer を用いた簡単な PHP スクリプトの例を示します。この例は、 PHP ファイルを読み込み、ソースから全てのコメントを削除し、コードのみを 出力するものです。

例1 tokenizer によるコメントの削除

<?php
$source = file_get_contents('example.php');
$tokens = token_get_all($source);

foreach ($tokens as $token) {
if (is_string($token)) {
// 簡単な1文字毎のトークン
echo $token;
} else {
// トークン配列
list($id, $text) = $token;

switch ($id) {
case T_COMMENT:
case T_DOC_COMMENT:
// コメントの場合は何もしない
break;

default:
// それ以外の場合 -> "そのまま"出力
echo $text;
break;
}
}
}
?>


PhpToken クラス

(PHP 8)

はじめに

このクラスは、token_get_all() 関数の代替です。 token_get_all() 関数は、トークンを示す一文字、 またはトークンのIDの配列、トークンのテキスト、行番号からなる配列を返します。 PhpToken::tokenize() は、 全てのトークンを PhpToken オブジェクトに正規化します。 これによって、トークンの操作を行うコードのメモリ使用量が少なくなり、 コードが読みやすくなります。

クラス概要

class PhpToken implements Stringable {
/* プロパティ */
public int $id;
public string $text;
public int $line;
public int $pos;
/* メソッド */
final public __construct(
int $id,
string $text,
int $line = -1,
int $pos = -1
)
public getTokenName(): ?string
public is(int|string|array $kind): bool
public isIgnorable(): bool
public __toString(): string
public static tokenize(string $code, int $flags = 0): array
}

プロパティ

id

T_* 定数のうちのひとつ。 または、 一文字のトークンを表す ASCII コードポイント。

text

トークンの内容を示すテキスト

line

トークンが始まる行番号(1から始まります)

pos

トークン化された文字列内での(バイト単位の)開始位置(0から始まります)

目次

  • PhpToken::__construct — 新しい PhpToken オブジェクトを返す
  • PhpToken::getTokenName — トークンの名前を返す
  • PhpToken::is — 指定された種類のトークンかを調べる
  • PhpToken::isIgnorable — トークンがPHPパーサから無視されるかを調べる
  • PhpToken::__toString — トークンの文字列表現を返す
  • PhpToken::tokenize — ソースコードを PhpToken オブジェクトで表現されたトークンに分割する


新しい PhpToken オブジェクトを返す

  • ≪ PhpToken
  • PhpToken::getTokenName ≫
  • PHP Manual
  • PhpToken
  • 新しい PhpToken オブジェクトを返す

PhpToken::__construct

(PHP 8)

PhpToken::__construct — 新しい PhpToken オブジェクトを返す

説明

final public PhpToken::__construct(
int $id,
string $text,
int $line = -1,
int $pos = -1
)

新しい PhpToken オブジェクトを返します。

パラメータ

id

T_* 定数(パーサトークンの一覧 を参照) のうちのひとつ。 または、 一文字のトークンを表す ASCII コードポイント。

text

トークンの内容を示すテキスト

line

トークンが始まる行番号(1から始まります)

pos

トークン化された文字列内での(バイト単位の)開始位置(0から始まります)

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する


トークンの名前を返す

  • ≪ PhpToken::__construct
  • PhpToken::is ≫
  • PHP Manual
  • PhpToken
  • トークンの名前を返す

PhpToken::getTokenName

(PHP 8)

PhpToken::getTokenName — トークンの名前を返す

説明

public PhpToken::getTokenName(): ?string

トークンの名前を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

一文字のトークンを示す ASCII 文字。 または、既知のトークンの名前を示す T_* 定数(パーサトークンの一覧 を参照)。 不明なトークンの場合は null を返します。

例

例1 PhpToken::getTokenName() の例

<?php
// 既知のトークンの場合
$token = new PhpToken(T_ECHO, 'echo');
var_dump($token->getTokenName()); // -> string(6) "T_ECHO"

// 一文字のトークンの場合
$token = new PhpToken(ord(';'), ';');
var_dump($token->getTokenName()); // -> string(1) ";"

// 不明なトークンの場合
$token = new PhpToken(10000 , "\0");
var_dump($token->getTokenName()); // -> NULL

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
  • token_name() - 指定した PHP トークンのシンボル名を取得する


指定された種類のトークンかを調べる

  • ≪ PhpToken::getTokenName
  • PhpToken::isIgnorable ≫
  • PHP Manual
  • PhpToken
  • 指定された種類のトークンかを調べる

PhpToken::is

(PHP 8)

PhpToken::is — 指定された種類のトークンかを調べる

説明

public PhpToken::is(int|string|array $kind): bool

トークンが指定された kind であるかを判定します。

パラメータ

kind

トークンのID、またはテキスト表現に一致するスカラー値、または配列

戻り値

トークンが指定された種類かを boolean で返します。

例

例1 PhpToken::is() の例

<?php
$token = new PhpToken(T_ECHO, 'echo');
var_dump($token->is(T_ECHO)); // -> bool(true)
var_dump($token->is('echo')); // -> bool(true)
var_dump($token->is(T_FOREACH)); // -> bool(false)
var_dump($token->is('foreach')); // -> bool(false)

例2 この関数に配列を渡す例

<?php
function isClassType(PhpToken $token): bool {
return $token->is([T_CLASS, T_INTERFACE, T_TRAIT]);
}

$interface = new PhpToken(T_INTERFACE, 'interface');
var_dump(isClassType($interface)); // -> bool(true)

$function = new PhpToken(T_FUNCTION, 'function');
var_dump(isClassType($function)); // -> bool(false)

参考

  • token_name() - 指定した PHP トークンのシンボル名を取得する


トークンがPHPパーサから無視されるかを調べる

  • ≪ PhpToken::is
  • PhpToken::__toString ≫
  • PHP Manual
  • PhpToken
  • トークンがPHPパーサから無視されるかを調べる

PhpToken::isIgnorable

(PHP 8)

PhpToken::isIgnorable — トークンがPHPパーサから無視されるかを調べる

説明

public PhpToken::isIgnorable(): bool

トークンがPHPパーサから無視されるかを判定します。

パラメータ

この関数にはパラメータはありません。

戻り値

A boolean value whether the token would be ignored by the PHP parser (such as whitespace or comments).

例

例1 PhpToken::isIgnorable() example

<?php
$echo = new PhpToken(T_ECHO, 'echo');
var_dump($echo->isIgnorable()); // -> bool(false)

$space = new PhpToken(T_WHITESPACE, ' ');
var_dump($space->isIgnorable()); // -> bool(true)

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する


トークンの文字列表現を返す

  • ≪ PhpToken::isIgnorable
  • PhpToken::tokenize ≫
  • PHP Manual
  • PhpToken
  • トークンの文字列表現を返す

PhpToken::__toString

(PHP 8)

PhpToken::__toString — トークンの文字列表現を返す

説明

public PhpToken::__toString(): string

トークンの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

トークンの文字列表現を返します。

例

例1 PhpToken::__toString() の例

<?php
$token = new PhpToken(T_ECHO, 'echo');
echo $token;

上の例の出力は以下となります。

echo

参考

  • token_name() - 指定した PHP トークンのシンボル名を取得する


ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

  • ≪ PhpToken::__toString
  • Tokenizer 関数 ≫
  • PHP Manual
  • PhpToken
  • ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

PhpToken::tokenize

(PHP 8)

PhpToken::tokenize — ソースコードを PhpToken オブジェクトで表現されたトークンに分割する

説明

public static PhpToken::tokenize(string $code, int $flags = 0): array

与えられた code を表現する PhpToken オブジェクトの配列を返します。

パラメータ

code

パースする PHP のコード。

flags

有効なフラグ:

  • TOKEN_PARSE - 特定のコンテクストで予約語を認識します。

戻り値

PhpToken、またはそのサブクラスで表現される、PHPトークンの配列を返します。 このメソッドの戻り値は、PhpToken をシームレスに拡張できるように、 static[] 型になっています。

例

例1 PhpToken::tokenize() の例

<?php
$tokens = PhpToken::tokenize('<?php echo; ?>');

foreach ($tokens as $token) {
echo "Line {$token->line}: {$token->getTokenName()} ('{$token->text}')", PHP_EOL;
}

上の例の出力は以下となります。

Line 1: T_OPEN_TAG ('<?php ')
Line 1: T_ECHO ('echo')
Line 1: ; (';')
Line 1: T_WHITESPACE (' ')
Line 1: T_CLOSE_TAG ('?>')

例2 Extending PhpToken

<?php

class MyPhpToken extends PhpToken {
public function getUpperText() {
return strtoupper($this->text);
}
}

$tokens = MyPhpToken::tokenize('<?php echo; ?>');
echo "'{$tokens[0]->getUpperText()}'";

上の例の出力は以下となります。

'<?PHP '

参考

  • token_get_all() - 指定したソースを PHP トークンに分割する


Tokenizer 関数

目次

  • token_get_all — 指定したソースを PHP トークンに分割する
  • token_name — 指定した PHP トークンのシンボル名を取得する


指定したソースを PHP トークンに分割する

  • ≪ Tokenizer 関数
  • token_name ≫
  • PHP Manual
  • Tokenizer 関数
  • 指定したソースを PHP トークンに分割する

token_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

token_get_all — 指定したソースを PHP トークンに分割する

説明

token_get_all(string $code, int $flags = 0): array

token_get_all() は指定した文字列 code をパースし、Zend engine の 字句解析スキャナにより PHP 言語のトークンに分割します。

パーサトークンの一覧を得るには、パーサトークンの一覧 を参照するか、 あるいは token_name() でトークン値を文字列表現に 変換します。

パラメータ

code

パースする PHP ソース。

flags

以下のフラグが使えます。

  • TOKEN_PARSE - 特定のコンテキストで予約語を使った場合に、それを認識する。

戻り値

トークン ID の配列を返します。配列の各要素には、一文字単位の文字列 (例: ;、.、 >、! など...)、 またはトークンのインデックスを 0 番目の要素、トークンの文字列表現を 1 番目の要素、 行番号を 2 番目の要素とする配列が含まれます。

例

例1 token_get_all() の例

<?php
$tokens = token_get_all('<?php echo; ?>');

foreach ($tokens as $token) {
if (is_array($token)) {
echo "Line {$token[2]}: ", token_name($token[0]), " ('{$token[1]}')", PHP_EOL;
}
}
?>

上の例の出力は、 たとえば以下のようになります。

Line 1: T_OPEN_TAG ('<?php ')
Line 1: T_ECHO ('echo')
Line 1: T_WHITESPACE (' ')
Line 1: T_CLOSE_TAG ('?>')

例2 token_get_all() の間違った使いかた

<?php
$tokens = token_get_all('/* comment */');

foreach ($tokens as $token) {
if (is_array($token)) {
echo "Line {$token[2]}: ", token_name($token[0]), " ('{$token[1]}')", PHP_EOL;
}
}
?>

上の例の出力は、 たとえば以下のようになります。

Line 1: T_INLINE_HTML ('/* comment */')
先ほどの例では、文字列が T_COMMENT ではなく T_INLINE_HTML とパースされていたことに注意しましょう。 これは、指定した "code" の中に開始タグが含まれていないからです。 通常のファイルで、コメントを PHP タグの外部に書いた場合にも同じようになります。

例3 予約語を使ったクラスでの token_get_all() の例

<?php

$source = <<<'code'
<?php

class A
{
const PUBLIC = 1;
}
code;

$tokens = token_get_all($source, TOKEN_PARSE);

foreach ($tokens as $token) {
if (is_array($token)) {
echo token_name($token[0]) , PHP_EOL;
}
}
?>

上の例の出力は、 たとえば以下のようになります。

T_OPEN_TAG
T_WHITESPACE
T_CLASS
T_WHITESPACE
T_STRING
T_CONST
T_WHITESPACE
T_STRING
T_LNUMBER
TOKEN_PARSE フラグを指定しなければ、最後から二番目のトークン (T_STRING) が T_PUBLIC と解釈されてしまいます。

参考

  • PhpToken::tokenize() - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
  • token_name() - 指定した PHP トークンのシンボル名を取得する


指定した PHP トークンのシンボル名を取得する

  • ≪ token_get_all
  • URLs ≫
  • PHP Manual
  • Tokenizer 関数
  • 指定した PHP トークンのシンボル名を取得する

token_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

token_name — 指定した PHP トークンのシンボル名を取得する

説明

token_name(int $id): string

token_name()は、PHP id 値のシンボル名を返します。

パラメータ

id

トークンの値。

戻り値

id に対応するシンボル名を返します。

例

例1 token_name() の例

<?php
// 260は T_EVAL トークンのトークン値
echo token_name(260); // -> "T_EVAL"

// 自身の名前にマップするトークン定数
echo token_name(T_FUNCTION); // -> "T_FUNCTION"
?>

参考

  • パーサトークンの一覧
  • PhpToken::getTokenName() - トークンの名前を返す


URLs

  • はじめに
  • 定義済み定数
  • URL 関数
    • base64_decode — MIME base64 方式によりエンコードされたデータをデコードする
    • base64_encode — MIME base64 方式でデータをエンコードする
    • get_headers — HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
    • get_meta_tags — ファイル上のすべてのメタタグ情報を配列に展開する
    • http_build_query — URL エンコードされたクエリ文字列を生成する
    • parse_url — URL を解釈し、その構成要素を返す
    • rawurldecode — URL エンコードされた文字列をデコードする
    • rawurlencode — RFC 3986 に基づき URL エンコードを行う
    • urldecode — URL エンコードされた文字列をデコードする
    • urlencode — 文字列を URL エンコードする


  • ≪ URLs
  • 定義済み定数 ≫
  • PHP Manual
  • URLs
  • はじめに

はじめに

URL文字列を処理(エンコード、デコード、パース)します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下の定数は parse_url() で使用するものです。

PHP_URL_SCHEME (int)
PHP_URL_HOST (int)
パースした URL のホスト名を出力します。
PHP_URL_PORT (int)
パースした URL のポート番号を出力します。
PHP_URL_USER (int)
パースした URL のユーザー名を出力します。
PHP_URL_PASS (int)
パースした URL のパスワードを出力します。
PHP_URL_PATH (int)
パースした URL のパスを出力します。
PHP_URL_QUERY (int)
パースした URL のクエリ文字列を出力します。
PHP_URL_FRAGMENT (int)
パースした URL のフラグメント (# 以降の文字列) を出力します。

以下の定数は、 http_build_query() で利用するものです。

PHP_QUERY_RFC1738 (int)
» RFC 1738 と application/x-www-form-urlencoded メディアタイプに基づくエンコーディングを行います。 つまり、スペースはプラス記号 (+) にエンコードされます。
PHP_QUERY_RFC3986 (int)
» RFC 3986 に基づくエンコーディングを行います。 スペースはパーセントエンコードされて、%20 となります。


URL 関数

目次

  • base64_decode — MIME base64 方式によりエンコードされたデータをデコードする
  • base64_encode — MIME base64 方式でデータをエンコードする
  • get_headers — HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
  • get_meta_tags — ファイル上のすべてのメタタグ情報を配列に展開する
  • http_build_query — URL エンコードされたクエリ文字列を生成する
  • parse_url — URL を解釈し、その構成要素を返す
  • rawurldecode — URL エンコードされた文字列をデコードする
  • rawurlencode — RFC 3986 に基づき URL エンコードを行う
  • urldecode — URL エンコードされた文字列をデコードする
  • urlencode — 文字列を URL エンコードする


MIME base64 方式によりエンコードされたデータをデコードする

  • ≪ URL 関数
  • base64_encode ≫
  • PHP Manual
  • URL 関数
  • MIME base64 方式によりエンコードされたデータをデコードする

base64_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

base64_decode — MIME base64 方式によりエンコードされたデータをデコードする

説明

base64_decode(string $string, bool $strict = false): string|false

base64 でエンコードされた string をデコードします。

パラメータ

string

デコードされるデータ。

strict

strict パラメータを true に指定すると、 base64_decode() 関数は、 入力に base64 アルファベットの範囲外の文字が含まれる場合に false を返します。 それ以外の場合は、base64 アルファベットの範囲外の文字を破棄したうえでデコードされます。

戻り値

デコードされたデータを返します。失敗した場合に false を返します。 戻り値はバイナリになることもあります。

例

例1 base64_decode() の例

<?php
$str = 'VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==';
echo base64_decode($str);
?>

上の例の出力は以下となります。

This is an encoded string

参考

  • base64_encode() - MIME base64 方式でデータをエンコードする
  • » RFC 2045 6.8 節


MIME base64 方式でデータをエンコードする

  • ≪ base64_decode
  • get_headers ≫
  • PHP Manual
  • URL 関数
  • MIME base64 方式でデータをエンコードする

base64_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

base64_encode — MIME base64 方式でデータをエンコードする

説明

base64_encode(string $string): string

指定した string を base64 でエンコードします。

このエンコードは、メールの本体のように 8 ビットクリーンではないトランスポート層を通じても、 バイナリデータが生き残れるように設計されています。

Base64 でエンコードされたデータは、エンコード前のデータにくらべて 33% 余計に容量が必要です。

パラメータ

string

エンコードするデータ。

戻り値

エンコードされたデータを文字列で返します。

例

例1 base64_encode() の例

<?php
$str = 'This is an encoded string';
echo base64_encode($str);
?>

上の例の出力は以下となります。

VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==

参考

  • base64_decode() - MIME base64 方式によりエンコードされたデータをデコードする
  • chunk_split() - 文字列をより小さな部分に分割する
  • convert_uuencode() - 文字列を uuencode する
  • » RFC 2045 6.8 節


HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する

  • ≪ base64_encode
  • get_meta_tags ≫
  • PHP Manual
  • URL 関数
  • HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する

get_headers

(PHP 5, PHP 7, PHP 8)

get_headers — HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する

説明

get_headers(string $url, bool $associative = false, ?resource $context = null): array|false

get_headers() は、HTTP リクエストに対するレスポンス内で サーバーによって送出されたヘッダの配列を返します。

パラメータ

url

対象となる URL。

associative

オプションの associative パラメータが ゼロ以外にセットされた場合、get_headers() はレスポンスをパースし、配列のキーをセットします。

context

stream_context_create() 関数で作られた 有効なコンテキストリソース。 null を渡すと、デフォルトのコンテキストを使います。

戻り値

数値添字配列あるいは連想配列でヘッダを返します。 失敗した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | associative の型が、 int から bool に変更されました。
7.1.0 | context パラメーターが追加されました。

例

例1 get_headers() の例

<?php
$url = 'http://www.example.com';

print_r(get_headers($url));

print_r(get_headers($url, true));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => HTTP/1.1 200 OK
    [1] => Date: Sat, 29 May 2004 12:28:13 GMT
    [2] => Server: Apache/1.3.27 (Unix)  (Red-Hat/Linux)
    [3] => Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT
    [4] => ETag: "3f80f-1b6-3e1cb03b"
    [5] => Accept-Ranges: bytes
    [6] => Content-Length: 438
    [7] => Connection: close
    [8] => Content-Type: text/html
)

Array
(
    [0] => HTTP/1.1 200 OK
    [Date] => Sat, 29 May 2004 12:28:14 GMT
    [Server] => Apache/1.3.27 (Unix)  (Red-Hat/Linux)
    [Last-Modified] => Wed, 08 Jan 2003 23:11:55 GMT
    [ETag] => "3f80f-1b6-3e1cb03b"
    [Accept-Ranges] => bytes
    [Content-Length] => 438
    [Connection] => close
    [Content-Type] => text/html
)

例2 get_headers() で HEAD を使う例

<?php
// デフォルトでは、get_headers は GET リクエストを使ってヘッダを取得します。
// HEAD リクエストでヘッダを取得したい場合は、ストリームコンテキストを使います。
$context = stream_context_create(
[
'http' => array(
'method' => 'HEAD'
)
]
);
$headers = get_headers('http://example.com', false, $context);
?>

参考

  • apache_request_headers() - すべての HTTP リクエストヘッダを取得する


ファイル上のすべてのメタタグ情報を配列に展開する

  • ≪ get_headers
  • http_build_query ≫
  • PHP Manual
  • URL 関数
  • ファイル上のすべてのメタタグ情報を配列に展開する

get_meta_tags

(PHP 4, PHP 5, PHP 7, PHP 8)

get_meta_tags — ファイル上のすべてのメタタグ情報を配列に展開する

説明

get_meta_tags(string $filename, bool $use_include_path = false): array|false

filename 内の各行をパースし <meta> タグ内の情報を配列として返します。 </head> でパースを終了します。

パラメータ

filename

HTML ファイルへのパスを表す文字列。 ローカルファイルのほか URL も指定できます。

例1 get_meta_tags() が何をパースするのか

<meta name="author" content="name">
<meta name="keywords" content="php documentation">
<meta name="DESCRIPTION" content="a php manual">
<meta name="geo.position" content="49.33;-86.59">
</head> <!-- ここでパースを終了します -->

use_include_path

use_include_path を true に指定すると、 include_path ディレクティブの内容にしたがってファイルを探します。 これはローカルファイルにのみ有効で、URL の場合は使用できません。

戻り値

パースされたメタタグを含む配列を返します。

name 属性の値が配列のキーとなります。content 属性の値が配列の要素となります。 標準の配列関数を利用することでこれらの値に簡単にアクセスすることができます。 name 属性で特別な文字が使われている場合は '_' で代用されます。 それ以外は小文字に変換されます。もしも同じ名前のメタタグがある場合には 最後のもののみが返されます。

失敗時に false を返します。

例

例2 get_meta_tags() が何を返すのか

<?php
// 上のタグは www.example.com 上のものだと仮定します
$tags = get_meta_tags('http://www.example.com/');

// すべてのキーが小文字であり、. (ピリオド) が _ に
// 置換されていることに注目してください。
echo $tags['author']; // name
echo $tags['keywords']; // php documentation
echo $tags['description']; // a php manual
echo $tags['geo_position']; // 49.33;-86.59
?>

注意

注意:

name 属性がついているメタタグのみがパースの対象となります。 クォートは不要です。

参考

  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • urlencode() - 文字列を URL エンコードする


URL エンコードされたクエリ文字列を生成する

  • ≪ get_meta_tags
  • parse_url ≫
  • PHP Manual
  • URL 関数
  • URL エンコードされたクエリ文字列を生成する

http_build_query

(PHP 5, PHP 7, PHP 8)

http_build_query — URL エンコードされたクエリ文字列を生成する

説明

http_build_query(
array|object $data,
string $numeric_prefix = "",
?string $arg_separator = null,
int $encoding_type = PHP_QUERY_RFC1738
): string

与えられた連想配列 (もしくは添字配列) から URL エンコードされたクエリ文字列を生成します。

パラメータ

data

プロパティを含む配列もしくはオブジェクト。

data が配列の場合の形式は、 単純な一次元構造か あるいは配列の配列 (言い換えると、他の配列を含む配列) となります。

data がオブジェクトの場合、 public プロパティだけが結果に含められます。

numeric_prefix

情報源となる配列 (query_data で指定した配列) に数値インデックスが使われていて、しかも numeric_prefix が指定された場合、数値のインデックスを持つ要素に関してのみインデックスの前に numeric_prefix で指定した値が付加されます。

これは、後で PHP や他の CGI アプリケーションによってデータがデコードされる際、 正当な変数名になるよう考慮したものです。

arg_separator

引数のセパレータ。指定されていなかったり、null だった場合は、 arg_separator.output が区分のためのセパレータとして使用されます。

encoding_type

デフォルトは PHP_QUERY_RFC1738 です。

encoding_type が PHP_QUERY_RFC1738 の場合は » RFC 1738 に従ってエンコードされ、メディアタイプは application/x-www-form-urlencoded となります。 つまり、スペースはプラス記号 (+) にエンコードされるということです。

encoding_type が PHP_QUERY_RFC3986 の場合は » RFC 3986 に従ってエンコードされ、 スペースはパーセント形式 (%20) となります。

戻り値

URL エンコードされた文字列を返します。

例

例1 http_build_query() の簡単な使用法

<?php
$data = array(
'foo' => 'bar',
'baz' => 'boom',
'cow' => 'milk',
'null' => null,
'php' => 'hypertext processor'
);

echo http_build_query($data) . "\n";
echo http_build_query($data, '', '&amp;');

?>

上の例の出力は以下となります。

foo=bar&baz=boom&cow=milk&php=hypertext+processor
foo=bar&amp;baz=boom&amp;cow=milk&amp;php=hypertext+processor

例2 数値インデックス要素の場合での http_build_query()

<?php
$data = array('foo', 'bar', 'baz', null, 'boom', 'cow' => 'milk', 'php' => 'hypertext processor');

echo http_build_query($data) . "\n";
echo http_build_query($data, 'myvar_');
?>

上の例の出力は以下となります。

0=foo&1=bar&2=baz&4=boom&cow=milk&php=hypertext+processor
myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_4=boom&cow=milk&php=hypertext+processor

例3 複雑な配列の場合での http_build_query()

<?php
$data = array(
'user' => array(
'name' => 'Bob Smith',
'age' => 47,
'sex' => 'M',
'dob' => '5/12/1956'
),
'pastimes' => array('golf', 'opera', 'poker', 'rap'),
'children' => array(
'bobby' => array('age'=>12, 'sex'=>'M'),
'sally' => array('age'=>8, 'sex'=>'F')
),
'CEO'
);

echo http_build_query($data, 'flags_');
?>

上の例は以下を出力します: (可読性のため適宜折り返しています)

user%5Bname%5D=Bob+Smith&user%5Bage%5D=47&user%5Bsex%5D=M&
user%5Bdob%5D=5%2F12%2F1956&pastimes%5B0%5D=golf&pastimes%5B1%5D=opera&
pastimes%5B2%5D=poker&pastimes%5B3%5D=rap&children%5Bbobby%5D%5Bage%5D=12&
children%5Bbobby%5D%5Bsex%5D=M&children%5Bsally%5D%5Bage%5D=8&
children%5Bsally%5D%5Bsex%5D=F&flags_0=CEO

注意:

基底の配列内の数値インデックス要素 "CEO" のみ、 接頭辞を受け取ります。pastimes 以下にある他の数値インデックスは、 正当な変数名にするための文字列の接頭辞を要求しません。

例4 オブジェクトの場合の http_build_query() の使用

<?php
class parentClass {
public $pub = 'publicParent';
protected $prot = 'protectedParent';
private $priv = 'privateParent';
public $pub_bar = null;
protected $prot_bar = null;
private $priv_bar = null;

public function __construct(){
$this->pub_bar = new childClass();
$this->prot_bar = new childClass();
$this->priv_bar = new childClass();
}
}

class childClass {
public $pub = 'publicChild';
protected $prot = 'protectedChild';
private $priv = 'privateChild';
}

$parent = new parentClass();

echo http_build_query($parent);
?>

上の例の出力は以下となります。

pub=publicParent&pub_bar%5Bpub%5D=publicChild

参考

  • parse_str() - 文字列を処理し、変数に代入する
  • parse_url() - URL を解釈し、その構成要素を返す
  • urlencode() - 文字列を URL エンコードする
  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する


URL を解釈し、その構成要素を返す

  • ≪ http_build_query
  • rawurldecode ≫
  • PHP Manual
  • URL 関数
  • URL を解釈し、その構成要素を返す

parse_url

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_url — URL を解釈し、その構成要素を返す

説明

parse_url(string $url, int $component = -1): int|string|array|null|false

この関数は、URL の様々な構成要素のうち特定できるものに関して 連想配列にして返します。 連想配列に含まれる要素の値は、URLデコード されません。

この関数は、指定された URL が有効かどうかを調べるためのもの ではなく、単に URL を以下で示す 要素に分解するだけのものです。不完全、かつ不正な URL であっても受け入れますし、 そのような場合でも parse_url() は可能な限り 正しく解析しようとします。

パラメータ

url

パースする URL。

component

PHP_URL_SCHEME、 PHP_URL_HOST、PHP_URL_PORT、 PHP_URL_USER、PHP_URL_PASS、 PHP_URL_PATH、PHP_URL_QUERY あるいは PHP_URL_FRAGMENT のうちのいずれかを指定し、 特定の URL コンポーネントのみを文字列 (PHP_URL_PORT を指定した場合だけは整数値) で取得するようにします。

戻り値

完全におかしな形式の URL については、parse_url() は false を返します。

component を省略した場合は、連想配列を返します。 連想配列の中には少なくともひとつの要素が含まれます。 この配列に含まれる可能性のある要素は次のとおりです。

  • scheme - 例: http
  • host
  • port
  • user
  • pass
  • path
  • query - クエスチョンマーク ? 以降
  • fragment - ハッシュマーク # 以降

component が指定されている場合、 parse_url() は配列ではなく文字列 (PHP_URL_PORT の場合は整数値) を返します。 要求したコンポーネントが指定した URL の中にない場合は null を返します。 PHP 8.0.0 以降では、 parse_url() は、query と fragment について、 存在しないことと値が空であることを以下のように区別します:

http://example.com/foo → query = null, fragment = null
http://example.com/foo? → query = "",   fragment = null
http://example.com/foo# → query = null, fragment = ""
http://example.com/foo?# → query = "",   fragment = ""

8.0.0 より前のバージョンでは、上記の場合は query も fragment も共に null になっていました。

URL の各要素(コンポーネント) に含まれる制御文字 (ctype_cntrl() も参照ください) は、 アンダースコア (_) に置き換えられる点に注意して下さい。

変更履歴

バージョン | 説明
8.0.0 | parse_url() は、query と fragment について、 存在しないことと値が空であることを区別するようになりました。

例

例1 parse_url() の例

<?php
$url = 'http://username:password@hostname:9090/path?arg=value#anchor';

var_dump(parse_url($url));
var_dump(parse_url($url, PHP_URL_SCHEME));
var_dump(parse_url($url, PHP_URL_USER));
var_dump(parse_url($url, PHP_URL_PASS));
var_dump(parse_url($url, PHP_URL_HOST));
var_dump(parse_url($url, PHP_URL_PORT));
var_dump(parse_url($url, PHP_URL_PATH));
var_dump(parse_url($url, PHP_URL_QUERY));
var_dump(parse_url($url, PHP_URL_FRAGMENT));
?>

上の例の出力は以下となります。

array(8) {
  ["scheme"]=>
  string(4) "http"
  ["host"]=>
  string(8) "hostname"
  ["port"]=>
  int(9090)
  ["user"]=>
  string(8) "username"
  ["pass"]=>
  string(8) "password"
  ["path"]=>
  string(5) "/path"
  ["query"]=>
  string(9) "arg=value"
  ["fragment"]=>
  string(6) "anchor"
}
string(4) "http"
string(8) "username"
string(8) "password"
string(8) "hostname"
int(9090)
string(5) "/path"
string(9) "arg=value"
string(6) "anchor"

例2 parse_url() でスキームを省略した例

<?php
$url = '//www.example.com/path?googleguy=googley';

// 5.4.7 より前のバージョンでは、パスを "//www.example.com/path" のように表示していました
var_dump(parse_url($url));
?>

上の例の出力は以下となります。

array(3) {
  ["host"]=>
  string(15) "www.example.com"
  ["path"]=>
  string(5) "/path"
  ["query"]=>
  string(17) "googleguy=googley"
}

注意

警告

この関数は相対 URL、 または不正な URL に対しては正しい結果を返さないかもしれません。 また、この関数の返す結果は、 HTTP クライアントの一般的な挙動とも異なるかもしれません。 信頼できない入力から得られる URL をパースする必要がある場合、 たとえば filter_var() 関数を FILTER_VALIDATE_URL と一緒に使うなどして、 追加の検証を行うことが必須です。

注意:

parse_url() は URL をパースするための関数であり、 URI をパースするものではありません。しかし、PHP の後方互換性を満たすため、 例外として file:// スキームについては 3 重スラッシュ(file:///...) が認められています。他のスキームにおいては、これは無効な形式となります。

参考

  • pathinfo() - ファイルパスに関する情報を返す
  • parse_str() - 文字列を処理し、変数に代入する
  • http_build_query() - URL エンコードされたクエリ文字列を生成する
  • dirname() - 親ディレクトリのパスを返す
  • basename() - パスの最後にある名前の部分を返す
  • » RFC 3986


URL エンコードされた文字列をデコードする

  • ≪ parse_url
  • rawurlencode ≫
  • PHP Manual
  • URL 関数
  • URL エンコードされた文字列をデコードする

rawurldecode

(PHP 4, PHP 5, PHP 7, PHP 8)

rawurldecode — URL エンコードされた文字列をデコードする

説明

rawurldecode(string $string): string

文字列の中にパーセント記号 (%) に続いて 2 つの 16 進数があるような表現形式を、文字定数に置き換えて返します。

パラメータ

string

デコードする URL。

戻り値

デコードされた URL を文字列で返します。

例

例1 rawurldecode() の例

<?php

echo rawurldecode('foo%20bar%40baz'); // foo bar@baz

?>

注意

注意:

rawurldecode() は、プラス記号 ('+') をスペースに変換しません。urldecode() は変換します。

参考

  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • urldecode() - URL エンコードされた文字列をデコードする
  • urlencode() - 文字列を URL エンコードする
  • » RFC 3986


RFC 3986 に基づき URL エンコードを行う

  • ≪ rawurldecode
  • urldecode ≫
  • PHP Manual
  • URL 関数
  • RFC 3986 に基づき URL エンコードを行う

rawurlencode

(PHP 4, PHP 5, PHP 7, PHP 8)

rawurlencode — RFC 3986 に基づき URL エンコードを行う

説明

rawurlencode(string $string): string

指定した文字列を » RFC 3986 にもとづいてエンコードします。

パラメータ

string

エンコードする URL。

戻り値

-_.~ を除くすべての非アルファベット文字をパーセント 記号 (%)に続いて 2 つの 16 進数がある表現形式に 置き換えた文字列を返します。これは、文字定数が特殊な URL デリミタと して解釈されたり、URL デリミタが(いくつかの電子メールシステムのような) 転送メディアにより文字変換されて失われてしまったりすることが ないように、» RFC 3986 で定められたエンコーディング方法です。

例

例1 FTP URL へのパスワードの埋め込み

<?php
echo '<a href="ftp://user:', rawurlencode('foo @+%/'),
'@ftp.example.com/x.txt">';
?>

上の例の出力は以下となります。

<a href="ftp://user:foo%20%40%2B%25%2F@ftp.example.com/x.txt">

あるいは、URL の PATH_INFO 中の情報を渡した場合は、

例2 rawurlencode() の例 2

<?php
echo '<a href="http://example.com/department_list_script/',
rawurlencode('sales and marketing/Miami'), '">';
?>

上の例の出力は以下となります。

<a href="http://example.com/department_list_script/sales%20and%20marketing%2FMiami">

参考

  • rawurldecode() - URL エンコードされた文字列をデコードする
  • urldecode() - URL エンコードされた文字列をデコードする
  • urlencode() - 文字列を URL エンコードする
  • » RFC 3986


URL エンコードされた文字列をデコードする

  • ≪ rawurlencode
  • urlencode ≫
  • PHP Manual
  • URL 関数
  • URL エンコードされた文字列をデコードする

urldecode

(PHP 4, PHP 5, PHP 7, PHP 8)

urldecode — URL エンコードされた文字列をデコードする

説明

urldecode(string $string): string

与えられた文字列中のあらゆるエンコード文字 %## をデコードします。 プラス記号 ('+') は、スペース文字にデコードします。

パラメータ

string

デコードする文字列。

戻り値

デコードした文字列を返します。

例

例1 urldecode() の例

<?php
$query = "my=apples&are=green+and+red";

foreach (explode('&', $query) as $chunk) {
$param = explode("=", $chunk);

if ($param) {
printf("Value for parameter \"%s\" is \"%s\"<br/>\n", urldecode($param[0]), urldecode($param[1]));
}
}
?>

注意

警告

スーパーグローバル $_GET および $_REQUEST の内容はすでにデコード済みのものです。 $_GET や $_REQUEST の要素に対して urldecode() を使用すると、予期せぬ危険な結果となります。

参考

  • urlencode() - 文字列を URL エンコードする
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • rawurldecode() - URL エンコードされた文字列をデコードする
  • » RFC 3986


文字列を URL エンコードする

  • ≪ urldecode
  • V8js ≫
  • PHP Manual
  • URL 関数
  • 文字列を URL エンコードする

urlencode

(PHP 4, PHP 5, PHP 7, PHP 8)

urlencode — 文字列を URL エンコードする

説明

urlencode(string $string): string

この関数は、URL の問い合わせ部分に使用する文字列のエンコードや 次のページへ変数を渡す際に便利です。

パラメータ

string

エンコードする文字列。

戻り値

-_. を除くすべての非英数文字が % 記号 (%)に続く二桁の16進数で置き換えられ、 空白は + 記号(+)にエンコードされます。 同様の方法で、WWW のフォームからポストされたデータはエンコードされ、 application/x-www-form-urlencoded メディア型も同様です。歴史的な理由により、この関数は » RFC 3986 エンコード( rawurlencode() を参照ください) とは異なり、 空白を + 記号にエンコードします。

例

例1 urlencode() の例

<?php
$userinput = 'Data123!@-_ +';
echo "UserInput: $userinput\n";
echo '<a href="mycgi?foo=', urlencode($userinput), '">';
?>

上の例の出力は以下となります。

UserInput: Data123!@-_ +
<a href="mycgi?foo=Data123%21%40-_+%2B">

例2 urlencode() および htmlentities() の例

<?php
$foo = 'Data123!@-_ +';
$bar = "Not the same content as $foo";
echo "foo: $foo\n";
echo "bar: $bar\n";
$query_string = 'foo=' . urlencode($foo) . '&bar=' . urlencode($bar);
echo '<a href="mycgi?' . htmlentities($query_string) . '">';
?>

上の例の出力は以下となります。

foo: Data123!@-_ +
bar: Not the same content as Data123!@-_ +
<a href="mycgi?foo=Data123%21%40-_+%2B&amp;bar=Not+the+same+content+as+Data123%21%40-_+%2B">

注意

注意:

HTML エンティティにマッチする変数については注意が必要です。 &amp、&copy、&pound のようなものがブラウザから送信された 場合、エンティティの実体がその変数名の代わりに使用されます。 これは明らかな問題点であり、W3C が何年も指摘し続けてきたことです。 リファレンスは、» http://www.w3.org/TR/html4/appendix/notes.html#h-B.2.2 にあります。

PHP では、 .ini ディレクティブの arg_separator により引数のセパレータを W3C が推奨するセミコロンに変更することが可能です。残念なことに、多くの ユーザーエージントはこのセミコロン区切り形式でデータを送信しません。 よりポータブルな方法としては、セパレータに & の代わりに &amp; を使用するというものがあります。この場合、PHP の arg_separator を変更する必要はありません。セパレータを & のままにし、htmlentities() あるいは htmlspecialchars() で URL をエンコードしてください。

参考

  • urldecode() - URL エンコードされた文字列をデコードする
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • rawurldecode() - URL エンコードされた文字列をデコードする
  • » RFC 3986


V8 JavaScript Engine 統合

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 例
  • V8Js — V8Js クラス
    • V8Js::__construct — 新しい V8Js オブジェクトを作成する
    • V8Js::executeString — 文字列を JavaScript のコードとして実行する
    • V8Js::getExtensions — 登録された拡張の配列を返す
    • V8Js::getPendingException — キャッチされなかった JavaScript 例外の中で未処理のものを返す
    • V8Js::registerExtension — V8Js で使う JavaScript の拡張を登録する
  • V8JsException — V8JsException クラス
    • V8JsException::getJsFileName — getJsFileName
    • V8JsException::getJsLineNumber — getJsLineNumber
    • V8JsException::getJsSourceLine — getJsSourceLine
    • V8JsException::getJsTrace — getJsTrace


  • ≪ V8js
  • インストール/設定 ≫
  • PHP Manual
  • V8js
  • はじめに

はじめに

この拡張モジュールは、» V8 JavaScript Engine を PHP に組み込みます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • V8js
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

PHP と V8 のライブラリとヘッダを、 適切なパスにインストールしておかなければなりません。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/v8js


実行時設定

php.ini の設定により動作が変化します。

V8js 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
v8js.max_disposed_contexts | 25 | INI_ALL |
v8js.flags |  | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

v8js.max_disposed_contexts int

V8 にコンテキストのガベージコレクションをさせるまでの制限を設定します。

v8js.flags string

V8 のコマンドラインフラグを設定します。利用できるフラグの一覧は、 コマンドラインで次のように --help を設定すれば取得できます。

$ php -r 'ini_set("v8js.flags", "--help"); new V8Js;' | less

注意:

実行時にこれらのフラグを有効にするには、V8Js オブジェクトのインスタンスを作成する前に ini_set() をコールしなければなりません!


例

基本的な使用例

例1 基本的な JavaScript の実行

<?php

$v8 = new V8Js();

/* basic.js */
$JS = <<< EOT
len = print('Hello' + ' ' + 'World!' + "\\n");
len;
EOT;

try {
var_dump($v8->executeString($JS, 'basic.js'));
} catch (V8JsException $e) {
var_dump($e);
}

?>

上の例の出力は以下となります。

Hello World!
int(13)


V8Js クラス

(PECL v8js >= 0.1.0)

はじめに

これは V8Js 拡張モジュールのコアクラスです。 このクラスのインスタンスはそれぞれ個別のコンテキストを持ち、 その中ですべての JavaScript をコンパイルして実行します。

詳細は V8Js::__construct() を参照ください。

クラス概要

class V8Js {
/* 定数 */
const string V8_VERSION;
const int FLAG_NONE = 1;
const int FLAG_FORCE_ARRAY = 2;
/* メソッド */
public __construct(
string $object_name = "PHP",
array $variables = array(),
array $extensions = array(),
bool $report_uncaught_exceptions = true
)
public executeString(string $script, string $identifier = "V8Js::executeString()", int $flags = V8Js::FLAG_NONE): mixed
public static getExtensions(): array
public getPendingException(): V8JsException
public static registerExtension(
string $extension_name,
string $script,
array $dependencies = array(),
bool $auto_enable = false
): bool
}

定義済み定数

V8Js::V8_VERSION

V8 JavaScript Engine のバージョン。

V8Js::FLAG_NONE

何もフラグが立っていません。

V8Js::FLAG_FORCE_ARRAY

すべての JS オブジェクトを PHP の連想配列にします。

目次

  • V8Js::__construct — 新しい V8Js オブジェクトを作成する
  • V8Js::executeString — 文字列を JavaScript のコードとして実行する
  • V8Js::getExtensions — 登録された拡張の配列を返す
  • V8Js::getPendingException — キャッチされなかった JavaScript 例外の中で未処理のものを返す
  • V8Js::registerExtension — V8Js で使う JavaScript の拡張を登録する


新しい V8Js オブジェクトを作成する

  • ≪ V8Js
  • V8Js::executeString ≫
  • PHP Manual
  • V8Js
  • 新しい V8Js オブジェクトを作成する

V8Js::__construct

(PECL v8js >= 0.1.0)

V8Js::__construct — 新しい V8Js オブジェクトを作成する

説明

public V8Js::__construct(
string $object_name = "PHP",
array $variables = array(),
array $extensions = array(),
bool $report_uncaught_exceptions = true
)

新しい V8Js オブジェクトを作成します。

パラメータ

object_name

JavaScript に渡すオブジェクトの名前。

variables

JavaScript の中で使う PHP の変数のマップ。 array("js で使うときの名前" => "php の変数名") 形式の連想配列でなければなりません。デフォルトは空の配列です。

extensions

V8Js::registerExtension() で登録した拡張の一覧。 作成した V8Js オブジェクトの JavaScript コンテキストで利用可能なものでなければなりません。

注意:

自動的に有効にするように登録した拡張については、この配列で指定する必要はありません。 また、ある登録が別の拡張に依存している場合も、依存している拡張は省略できます。デフォルトは空の配列です。

report_uncaught_exceptions

キャッチできなかった JavaScript の例外をその場ですぐに報告するかどうかを制御します。 デフォルトは true です。false にしたときは、キャッチできなかった例外へのアクセスには V8Js::getPendingException() を使います。


文字列を JavaScript のコードとして実行する

  • ≪ V8Js::__construct
  • V8Js::getExtensions ≫
  • PHP Manual
  • V8Js
  • 文字列を JavaScript のコードとして実行する

V8Js::executeString

(PECL v8js >= 0.1.0)

V8Js::executeString — 文字列を JavaScript のコードとして実行する

説明

public V8Js::executeString(string $script, string $identifier = "V8Js::executeString()", int $flags = V8Js::FLAG_NONE): mixed

script で渡した文字列を JavaScript のコードとしてコンパイルし、実行します。

パラメータ

script

実行したいコード文字列。

identifier

実行するコードの識別子となる文字列。デバッグ時に使います。

flags

実行フラグ。 V8Js::FLAG_* 定数のいずれかでなければならず、デフォルトは V8Js::FLAG_NONE です。

  • V8Js::FLAG_NONE: 何もフラグが立っていません。

  • V8Js::FLAG_FORCE_ARRAY: PHP に渡されるすべての JS オブジェクトを連想配列にします。

戻り値

JavaScript のコード内で最後に生成された変数の値を PHP の変数の型に変換して返します。


登録された拡張の配列を返す

  • ≪ V8Js::executeString
  • V8Js::getPendingException ≫
  • PHP Manual
  • V8Js
  • 登録された拡張の配列を返す

V8Js::getExtensions

(PECL v8js >= 0.1.0)

V8Js::getExtensions — 登録された拡張の配列を返す

説明

public static V8Js::getExtensions(): array

この関数は、V8Js::registerExtension() で登録された JavaScript 拡張の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

登録された拡張の配列を返します。何も登録されていない場合は空の配列を返します。


キャッチされなかった JavaScript 例外の中で未処理のものを返す

  • ≪ V8Js::getExtensions
  • V8Js::registerExtension ≫
  • PHP Manual
  • V8Js
  • キャッチされなかった JavaScript 例外の中で未処理のものを返す

V8Js::getPendingException

(PECL v8js >= 0.1.0)

V8Js::getPendingException — キャッチされなかった JavaScript 例外の中で未処理のものを返す

説明

public V8Js::getPendingException(): V8JsException

V8Js::executeString() をコールしたときに発生した JavaScript の例外の中で未処理のものを V8JsException で返します。

パラメータ

この関数にはパラメータはありません。

戻り値

V8JsException あるいは null を返します。


V8Js で使う JavaScript の拡張を登録する

  • ≪ V8Js::getPendingException
  • V8JsException ≫
  • PHP Manual
  • V8Js
  • V8Js で使う JavaScript の拡張を登録する

V8Js::registerExtension

(PECL v8js >= 0.1.0)

V8Js::registerExtension — V8Js で使う JavaScript の拡張を登録する

説明

public static V8Js::registerExtension(
string $extension_name,
string $script,
array $dependencies = array(),
bool $auto_enable = false
): bool

渡された JavaScript script を V8Js コンテキストで利用する拡張として登録します。

パラメータ

extension_name

登録する拡張の名前。

script

登録する JavaScript コード。

dependencies

登録する拡張が依存している他の拡張の名前の配列。この拡張が読み込まれたときに、 これらの拡張も自動的に有効になります。

注意:

拡張を使う V8Js を作成する前に、 その拡張自身と依存する拡張群をすべて登録しておかなければなりません。

auto_enable

true にすると、この拡張がすべての V8Js コンテキストで自動的に有効となります。

戻り値

拡張の登録に成功した場合に true、それ以外の場合に false を返します。


V8JsException クラス

(PECL v8js >= 0.1.0)

はじめに

クラス概要

class V8JsException extends Exception {
/* プロパティ */
protected $JsFileName;
protected $JsLineNumber;
protected $JsSourceLine;
protected $JsTrace;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
final public getJsFileName(): string
final public getJsLineNumber(): int
final public getJsSourceLine(): string
final public getJsTrace(): string
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

JsFileName

JsLineNumber

JsSourceLine

JsTrace

目次

  • V8JsException::getJsFileName — getJsFileName
  • V8JsException::getJsLineNumber — getJsLineNumber
  • V8JsException::getJsSourceLine — getJsSourceLine
  • V8JsException::getJsTrace — getJsTrace


getJsFileName

  • ≪ V8JsException
  • V8JsException::getJsLineNumber ≫
  • PHP Manual
  • V8JsException
  • getJsFileName

V8JsException::getJsFileName

(PECL v8js >= 0.1.0)

V8JsException::getJsFileName — getJsFileName

説明

final public V8JsException::getJsFileName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


getJsLineNumber

  • ≪ V8JsException::getJsFileName
  • V8JsException::getJsSourceLine ≫
  • PHP Manual
  • V8JsException
  • getJsLineNumber

V8JsException::getJsLineNumber

(PECL v8js >= 0.1.0)

V8JsException::getJsLineNumber — getJsLineNumber

説明

final public V8JsException::getJsLineNumber(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


getJsSourceLine

  • ≪ V8JsException::getJsLineNumber
  • V8JsException::getJsTrace ≫
  • PHP Manual
  • V8JsException
  • getJsSourceLine

V8JsException::getJsSourceLine

(PECL v8js >= 0.1.0)

V8JsException::getJsSourceLine — getJsSourceLine

説明

final public V8JsException::getJsSourceLine(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


getJsTrace

  • ≪ V8JsException::getJsSourceLine
  • Yaml ≫
  • PHP Manual
  • V8JsException
  • getJsTrace

V8JsException::getJsTrace

(PECL v8js >= 0.1.0)

V8JsException::getJsTrace — getJsTrace

説明

final public V8JsException::getJsTrace(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


YAML によるデータのシリアライズ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
  • コールバック
    • パースコールバック
    • 発行コールバック
  • Yaml 関数
    • yaml_emit — YAML 形式にした値を返す
    • yaml_emit_file — YAML 形式にした値をファイルに送る
    • yaml_parse — YAML ストリームをパースする
    • yaml_parse_file — ファイルからの YAML ストリームをパースする
    • yaml_parse_url — URL からの YAML ストリームをパースする


はじめに

この拡張モジュールは、データの標準的なシリアライズ方式である » YAML Ain't Markup Language (YAML) を実装したものです。 YAML のパースと出力には » LibYAML ライブラリ を用います。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Yaml
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

この拡張モジュールを使うには、» LibYAML C ライブラリ のバージョン 0.1.0 以降をインストールしなければなりません。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaml


実行時設定

php.ini の設定により動作が変化します。

Yaml 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yaml.decode_binary | 0 | INI_ALL |
yaml.decode_php | 0 | INI_ALL | 1.2.0 で追加されました。2.0.0 より前のデフォルトは 1 でした
yaml.decode_timestamp | 0 | INI_ALL |
yaml.output_canonical | 0 | INI_ALL |
yaml.output_indent | 2 | INI_ALL |
yaml.output_width | 80 | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

yaml.decode_binary bool

デフォルトではオフです。オンにすると、明示的にタグ "tag:yaml.org,2002:binary" がつけられた base64 バイナリエンコード形式のエンティティをデコードします。

yaml.decode_php bool

デフォルトではオフです。 しかし、明示的に "!php/object" タグを指定した phpオブジェクトをアンシリアライズさせたい場合には、オンにできます。

yaml.decode_timestamp int

YAML ドキュメントストリームにおける暗黙的なスカラー、 および明示的に "tag:yaml.org,2002:timestamp" がつけられたスカラーの デコードを制御します。デフォルト設定は 0 で、これはなにもデコードしません。 1 を設定すると、strtotime() を使って timestamp 値を Unix タイムスタンプに変換します。 2 を設定すると、date_create() を使って timestamp 値を DateTime オブジェクトに変換します。

yaml.output_canonical bool

デフォルトではオフです。オンにすると、標準形式の出力となります。

yaml.output_indent int

セクションの字下げに使うスペースの数。 1 から 10 までの間の値でなければなりません。

yaml.output_width int

行の長さの推奨値。-1 は、無制限を意味します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

yaml_parse() のコールバックメソッドで使う、 スカラーエンティティの形式
YAML_ANY_SCALAR_STYLE (int)
YAML_PLAIN_SCALAR_STYLE (int)
YAML_SINGLE_QUOTED_SCALAR_STYLE (int)
YAML_DOUBLE_QUOTED_SCALAR_STYLE (int)
YAML_LITERAL_SCALAR_STYLE (int)
YAML_FOLDED_SCALAR_STYLE (int)
yaml_parse() のコールバックメソッドで使う、 共通タグ
YAML_NULL_TAG (string)
"tag:yaml.org,2002:null"
YAML_BOOL_TAG (string)
"tag:yaml.org,2002:bool"
YAML_STR_TAG (string)
"tag:yaml.org,2002:str"
YAML_INT_TAG (string)
"tag:yaml.org,2002:int"
YAML_FLOAT_TAG (string)
"tag:yaml.org,2002:float"
YAML_TIMESTAMP_TAG (string)
"tag:yaml.org,2002:timestamp"
YAML_SEQ_TAG (string)
"tag:yaml.org,2002:seq"
YAML_MAP_TAG (string)
"tag:yaml.org,2002:map"
YAML_PHP_TAG (string)
"!php/object"
yaml_emit() 用のエンコード方式
YAML_ANY_ENCODING (int)
エミッターにエンコードを判断させます。
YAML_UTF8_ENCODING (int)
UTF8 としてエンコードします。
YAML_UTF16LE_ENCODING (int)
UTF16LE としてエンコードします。
YAML_UTF16BE_ENCODING (int)
UTF16BE としてエンコードします。
yaml_emit() 用の改行形式
YAML_ANY_BREAK (int)
エミッターに改行文字を判断させます。
YAML_CR_BREAK (int)
改行文字に \r を使います (Mac 形式)。
YAML_LN_BREAK (int)
改行文字に \n を使います (Unix 形式)。
YAML_CRLN_BREAK (int)
改行文字に \r\n を使います (DOS 形式)。


例

例1 Yaml の例

<?php
$addr = array(
"given" => "Chris",
"family"=> "Dumars",
"address"=> array(
"lines"=> "458 Walkman Dr.
Suite #292",
"city"=> "Royal Oak",
"state"=> "MI",
"postal"=> 48046,
),
);
$invoice = array (
"invoice"=> 34843,
"date"=> "2001-01-23",
"bill-to"=> $addr,
"ship-to"=> $addr,
"product"=> array(
array(
"sku"=> "BL394D",
"quantity"=> 4,
"description"=> "Basketball",
"price"=> 450,
),
array(
"sku"=> "BL4438H",
"quantity"=> 1,
"description"=> "Super Hoop",
"price"=> 2392,
),
),
"tax"=> 251.42,
"total"=> 4443.52,
"comments"=> "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.",
);

// 請求書を YAML 形式で出力します
$yaml = yaml_emit($invoice);
var_dump($yaml);

// YAML から PHP の変数に書き戻します
$parsed = yaml_parse($yaml);

// このやりとりの結果、同じ結果が得られていることを確認します
var_dump($parsed == $invoice);
?>

上の例の出力は、 たとえば以下のようになります。

string(631) "---
invoice: 34843
date: "2001-01-23"
bill-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
"
bool(true)


  • ≪ 例
  • パースコールバック ≫
  • PHP Manual
  • Yaml
  • コールバック

コールバック

目次

  • パースコールバック
  • 発行コールバック


パースコールバック

パースコールバック (callable) は、 yaml_parse() や yaml_parse_file() そして yaml_parse_url() 関数が、登録済みの YAML タグに遭遇したときに起動します。 コールバックに渡されるのは、タグ付けされたエンティティの値とタグ、そしてスカラーエンティティの形式を表すフラグです。 このコールバックが返すデータを使って、YAML パーサがこのエンティティを発行することになります。

例1 パースコールバックの例

<?php
/**
* yaml タグのパース用コールバック。
* @param mixed $value yamlファイルからのデータ
* @param string $tag コールバックを起動したタグ
* @param int $flags スカラーエンティティの形式 (YAML_*_SCALAR_STYLE を参照)
* @return mixed YAML パーサが発行するための値
*/
function tag_callback ($value, $tag, $flags) {
var_dump(func_get_args()); // デバッグ用
return "Hello {$value}";
}

$yaml = <<<YAML
greeting: !example/hello World
YAML;

$result = yaml_parse($yaml, 0, $ndocs, array(
'!example/hello' => 'tag_callback',
));

var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(5) "World"
  [1]=>
  string(14) "!example/hello"
  [2]=>
  int(1)
}
array(1) {
  ["greeting"]=>
  string(11) "Hello World"
}


発行コールバック

発行コールバックが起動するのは、登録済みのクラスのインスタンスが yaml_emit() や yaml_emit_file() から呼び出されたときです。 コールバックに渡されるのは、発行対象のオブジェクトです。 このコールバックは、二つの要素 "tag" および "data" を持つ配列を返す必要があります。 "tag" の値は文字列で、出力時の YAML タグとして用いられます。 "data" の値は YAML 形式にエンコードされ、 解析対象のオブジェクトの代わりに発行されます。

例1 Emit callback example

<?php
class EmitExample {
public $data; // データは pecl/yaml で使える形式となります

public function __construct ($d) {
$this->data = $d;
}

/**
* Yaml 発行コールバック関数。yaml_emit からクラス名で参照される
*
* 二つの要素を持つ配列を返す。
* - 'tag': このシリアライズ用のカスタムタグ
* - 'data': yaml に変換する値 (array, string, bool, number)
*
* @param object $obj 発行するオブジェクト
* @return array 発行するタグおよび代理データ
*/
public static function yamlEmit (EmitExample $obj) {
return array(
'tag' => '!example/emit',
'data' => $obj->data,
);
}
}

$emit_callbacks = array(
'EmitExample' => array('EmitExample', 'yamlEmit')
);

$t = new EmitExample(array('a','b','c'));
$yaml = yaml_emit(
array(
'example' => $t,
),
YAML_ANY_ENCODING,
YAML_ANY_BREAK,
$emit_callbacks
);
var_dump($yaml);
?>

上の例の出力は、 たとえば以下のようになります。

string(43) "---
example: !example/emit
- a
- b
- c
...
"


Yaml 関数

目次

  • yaml_emit — YAML 形式にした値を返す
  • yaml_emit_file — YAML 形式にした値をファイルに送る
  • yaml_parse — YAML ストリームをパースする
  • yaml_parse_file — ファイルからの YAML ストリームをパースする
  • yaml_parse_url — URL からの YAML ストリームをパースする


YAML 形式にした値を返す

  • ≪ Yaml 関数
  • yaml_emit_file ≫
  • PHP Manual
  • Yaml 関数
  • YAML 形式にした値を返す

yaml_emit

(PECL yaml >= 0.5.0)

yaml_emit — YAML 形式にした値を返す

説明

yaml_emit(
mixed $data,
int $encoding = YAML_ANY_ENCODING,
int $linebreak = YAML_ANY_BREAK,
array $callbacks = null
): string

data で渡したデータを YAML 形式にして返します。

パラメータ

data

エンコードしたいデータ。リソース型以外の任意の型が使えます。

encoding

出力時の文字エンコーディング。 YAML_ANY_ENCODING、 YAML_UTF8_ENCODING、 YAML_UTF16LE_ENCODING、 YAML_UTF16BE_ENCODING のいずれか。

linebreak

出力時の改行形式。 YAML_ANY_BREAK、 YAML_CR_BREAK、 YAML_LN_BREAK、 YAML_CRLN_BREAK のいずれか。

callbacks

YAML ノードの発行用のコンテンツハンドラ。 クラス名 => callable 形式の連想配列となります。 詳細は発行コールバック を参照ください。

戻り値

成功した場合に YAML 形式の文字列を返します。

変更履歴

バージョン | 説明
PECL yaml 1.1.0 | callbacks パラメータが追加されました。

例

例1 yaml_emit() の例

<?php
$addr = array(
"given" => "Chris",
"family"=> "Dumars",
"address"=> array(
"lines"=> "458 Walkman Dr.
Suite #292",
"city"=> "Royal Oak",
"state"=> "MI",
"postal"=> 48046,
),
);
$invoice = array (
"invoice"=> 34843,
"date"=> 980208000,
"bill-to"=> $addr,
"ship-to"=> $addr,
"product"=> array(
array(
"sku"=> "BL394D",
"quantity"=> 4,
"description"=> "Basketball",
"price"=> 450,
),
array(
"sku"=> "BL4438H",
"quantity"=> 1,
"description"=> "Super Hoop",
"price"=> 2392,
),
),
"tax"=> 251.42,
"total"=> 4443.52,
"comments"=> "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.",
);
var_dump(yaml_emit($invoice));
?>

上の例の出力は、 たとえば以下のようになります。

string(628) "---
invoice: 34843
date: 980208000
bill-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
"

参考

  • yaml_emit_file() - YAML 形式にした値をファイルに送る
  • yaml_parse() - YAML ストリームをパースする


YAML 形式にした値をファイルに送る

  • ≪ yaml_emit
  • yaml_parse ≫
  • PHP Manual
  • Yaml 関数
  • YAML 形式にした値をファイルに送る

yaml_emit_file

(PECL yaml >= 0.5.0)

yaml_emit_file — YAML 形式にした値をファイルに送る

説明

yaml_emit_file(
string $filename,
mixed $data,
int $encoding = YAML_ANY_ENCODING,
int $linebreak = YAML_ANY_BREAK,
array $callbacks = null
): bool

data で渡したデータを YAML 形式にして filename に書き込みます。

パラメータ

filename

ファイルへのパス。

data

エンコードしたいデータ。リソース型以外の任意の型が使えます。

encoding

出力時の文字エンコーディング。 YAML_ANY_ENCODING、 YAML_UTF8_ENCODING、 YAML_UTF16LE_ENCODING、 YAML_UTF16BE_ENCODING のいずれか。

linebreak

出力時の改行形式。 YAML_ANY_BREAK、 YAML_CR_BREAK、 YAML_LN_BREAK、 YAML_CRLN_BREAK のいずれか。

callbacks

YAML ノードの発行用のコンテンツハンドラ。 クラス名 => callable 形式の連想配列となります。 詳細は発行コールバック を参照ください。

戻り値

成功した場合に true を返します。

変更履歴

バージョン | 説明
PECL yaml 1.1.0 | callbacks パラメータが追加されました。

参考

  • yaml_emit() - YAML 形式にした値を返す
  • yaml_parse() - YAML ストリームをパースする


YAML ストリームをパースする

  • ≪ yaml_emit_file
  • yaml_parse_file ≫
  • PHP Manual
  • Yaml 関数
  • YAML ストリームをパースする

yaml_parse

(PECL yaml >= 0.4.0)

yaml_parse — YAML ストリームをパースする

説明

yaml_parse(
string $input,
int $pos = 0,
int &$ndocs = ?,
array $callbacks = null
): mixed

YAML ドキュメントストリーム全体あるいはその一部を、PHP の変数に変換します。

パラメータ

input

YAML ドキュメントストリームとしてパースする文字列。

pos

ストリームから取り出すドキュメント (-1 はすべてのドキュメント、0 は最初のドキュメント、...)。

ndocs

ndocs を渡すと、 ストリーム内で見つかったドキュメントの数がそこに格納されます。

callbacks

YAML ノードのコンテンツハンドラ。 YAML タグ => callable 形式の連想配列となります。 詳細はパースコールバック を参照ください。

戻り値

適切な PHP の型に変換した結果を返します。 失敗した場合に false を返します。 pos が -1 の場合は配列を返します。 配列の各要素が、ストリーム内で見つかった個々のドキュメントとなります。

例

例1 yaml_parse() の例

<?php
$yaml = <<<EOD
---
invoice: 34843
date: "2001-01-23"
bill-to: &id001
given: Chris
family: Dumars
address:
lines: |-
458 Walkman Dr.
Suite #292
city: Royal Oak
state: MI
postal: 48046
ship-to: *id001
product:
- sku: BL394D
quantity: 4
description: Basketball
price: 450
- sku: BL4438H
quantity: 1
description: Super Hoop
price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
EOD;

$parsed = yaml_parse($yaml);
var_dump($parsed);
?>

上の例の出力は、 たとえば以下のようになります。

array(8) {
  ["invoice"]=>
  int(34843)
  ["date"]=>
  string(10) "2001-01-23"
  ["bill-to"]=>
  &array(3) {
    ["given"]=>
    string(5) "Chris"
    ["family"]=>
    string(6) "Dumars"
    ["address"]=>
    array(4) {
      ["lines"]=>
      string(34) "458 Walkman Dr.
        Suite #292"
      ["city"]=>
      string(9) "Royal Oak"
      ["state"]=>
      string(2) "MI"
      ["postal"]=>
      int(48046)
    }
  }
  ["ship-to"]=>
  &array(3) {
    ["given"]=>
    string(5) "Chris"
    ["family"]=>
    string(6) "Dumars"
    ["address"]=>
    array(4) {
      ["lines"]=>
      string(34) "458 Walkman Dr.
        Suite #292"
      ["city"]=>
      string(9) "Royal Oak"
      ["state"]=>
      string(2) "MI"
      ["postal"]=>
      int(48046)
    }
  }
  ["product"]=>
  array(2) {
    [0]=>
    array(4) {
      ["sku"]=>
      string(6) "BL394D"
      ["quantity"]=>
      int(4)
      ["description"]=>
      string(10) "Basketball"
      ["price"]=>
      int(450)
    }
    [1]=>
    array(4) {
      ["sku"]=>
      string(7) "BL4438H"
      ["quantity"]=>
      int(1)
      ["description"]=>
      string(10) "Super Hoop"
      ["price"]=>
      int(2392)
    }
  }
  ["tax"]=>
  float(251.42)
  ["total"]=>
  float(4443.52)
  ["comments"]=>
  string(68) "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338."
}

注意

警告

!php/object タグを使ったノードの unserialize() を有効にしている場合に、 ユーザーからの信頼できない入力を yaml_parse() で処理するのは危険です。 この挙動を無効にするには、ini 設定の yaml.decode_php を利用します。

参考

  • yaml_parse_file() - ファイルからの YAML ストリームをパースする
  • yaml_parse_url() - URL からの YAML ストリームをパースする
  • yaml_emit() - YAML 形式にした値を返す


ファイルからの YAML ストリームをパースする

  • ≪ yaml_parse
  • yaml_parse_url ≫
  • PHP Manual
  • Yaml 関数
  • ファイルからの YAML ストリームをパースする

yaml_parse_file

(PECL yaml >= 0.4.0)

yaml_parse_file — ファイルからの YAML ストリームをパースする

説明

yaml_parse_file(
string $filename,
int $pos = 0,
int &$ndocs = ?,
array $callbacks = null
): mixed

指定したファイルから読み込んだ YAML ドキュメントストリーム全体あるいはその一部を、PHP の変数に変換します。

パラメータ

filename

ファイルへのパス。

pos

ストリームから取り出すドキュメント (-1 はすべてのドキュメント、0 は最初のドキュメント、...)。

ndocs

ndocs を渡すと、 ストリーム内で見つかったドキュメントの数がそこに格納されます。

callbacks

YAML ノードのコンテンツハンドラ。 YAML タグ => callable 形式の連想配列となります。 詳細はパースコールバック を参照ください。

戻り値

filename にある情報を、 適切な PHP の型に変換した結果を返します。 失敗した場合に false を返します。 pos が -1 の場合は配列を返します。 配列の各要素が、ストリーム内で見つかった個々のドキュメントとなります。

注意

警告

!php/object タグを使ったノードの unserialize() を有効にしている場合に、 ユーザーからの信頼できない入力を yaml_parse_file() で処理するのは危険です。 この挙動を無効にするには、ini 設定の yaml.decode_php を利用します。

参考

  • yaml_parse() - YAML ストリームをパースする
  • yaml_parse_url() - URL からの YAML ストリームをパースする
  • yaml_emit() - YAML 形式にした値を返す


URL からの YAML ストリームをパースする

  • ≪ yaml_parse_file
  • Yaf ≫
  • PHP Manual
  • Yaml 関数
  • URL からの YAML ストリームをパースする

yaml_parse_url

(PECL yaml >= 0.4.0)

yaml_parse_url — URL からの YAML ストリームをパースする

説明

yaml_parse_url(
string $url,
int $pos = 0,
int &$ndocs = ?,
array $callbacks = null
): mixed

指定した URL から読み込んだ YAML ドキュメントストリーム全体あるいはその一部を、PHP の変数に変換します。

パラメータ

url

url は "scheme://..." 形式でなければなりません。 PHP は、このスキームを見てプロトコルハンドラ (ラッパー) を探します。 対応するラッパーが登録されていない場合は notice を発し、 そのまま通常のファイルとみなして処理を続けます。

pos

ストリームから取り出すドキュメント (-1 はすべてのドキュメント、0 は最初のドキュメント、...)。

ndocs

ndocs を渡すと、 ストリーム内で見つかったドキュメントの数がそこに格納されます。

callbacks

YAML ノードのコンテンツハンドラ。 YAML タグ => callable 形式の連想配列となります。 詳細はパースコールバック を参照ください。

戻り値

適切な PHP の型に変換した結果を返します。 失敗した場合に false を返します。 pos が -1 の場合は配列を返します。 配列の各要素が、ストリーム内で見つかった個々のドキュメントとなります。

注意

警告

!php/object タグを使ったノードの unserialize() を有効にしている場合に、 ユーザーからの信頼できない入力を yaml_parse_url() で処理するのは危険です。 この挙動を無効にするには、ini 設定の yaml.decode_php を利用します。

参考

  • yaml_parse() - YAML ストリームをパースする
  • yaml_parse_file() - ファイルからの YAML ストリームをパースする
  • yaml_emit() - YAML 形式にした値を返す


Yet Another Framework (Yaf)

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
  • アプリケーションの設定
  • Yaf_Application — Yaf_Application クラス
    • Yaf_Application::app — アプリケーションのインスタンスを取得する
    • Yaf_Application::bootstrap — ブートストラップをコールする
    • Yaf_Application::clearLastError — 直近のエラー情報を消す
    • Yaf_Application::__construct — Yaf_Application のコンストラクタ
    • Yaf_Application::__destruct — デストラクタ
    • Yaf_Application::environ — 環境を取得する
    • Yaf_Application::execute — コールバックを実行する
    • Yaf_Application::getAppDirectory — アプリケーションディレクトリを取得する
    • Yaf_Application::getConfig — 設定情報を取得する
    • Yaf_Application::getDispatcher — Yaf_Dispatcher のインスタンスを取得する
    • Yaf_Application::getLastErrorMsg — 直近で発生したエラーのメッセージを取得する
    • Yaf_Application::getLastErrorNo — 直近で発生したエラーのコードを取得する
    • Yaf_Application::getModules — 定義済みのモジュール名を取得する
    • Yaf_Application::run — Yaf_Application を開始する
    • Yaf_Application::setAppDirectory — アプリケーションディレクトリを変更する
  • Yaf_Bootstrap_Abstract — Yaf_Bootstrap_Abstract クラス
  • Yaf_Dispatcher — Yaf_Dispatcher クラス
    • Yaf_Dispatcher::autoRender — 自動レンダリングのオン/オフを切り替える
    • Yaf_Dispatcher::catchException — 例外のキャッチのオン/オフを切り替える
    • Yaf_Dispatcher::__construct — Yaf_Dispatcher のコンストラクタ
    • Yaf_Dispatcher::disableView — ビューのレンダリングを無効にする
    • Yaf_Dispatcher::dispatch — リクエストをディスパッチする
    • Yaf_Dispatcher::enableView — ビューのレンダリングを有効にする
    • Yaf_Dispatcher::flushInstantly — その場でのフラッシュのオン/オフを切り替える
    • Yaf_Dispatcher::getApplication — アプリケーションを取得する
    • Yaf_Dispatcher::getDefaultAction — Retrive the default action name
    • Yaf_Dispatcher::getDefaultController — Retrive the default controller name
    • Yaf_Dispatcher::getDefaultModule — Retrive the default module name
    • Yaf_Dispatcher::getInstance — ディスパッチャのインスタンスを取得する
    • Yaf_Dispatcher::getRequest — リクエストのインスタンスを取得する
    • Yaf_Dispatcher::getRouter — ルーターのインスタンスを取得する
    • Yaf_Dispatcher::initView — ビューを初期化して返す
    • Yaf_Dispatcher::registerPlugin — プラグインを登録する
    • Yaf_Dispatcher::returnResponse — The returnResponse purpose
    • Yaf_Dispatcher::setDefaultAction — デフォルトのアクション名を変更する
    • Yaf_Dispatcher::setDefaultController — デフォルトのコントローラ名を変更する
    • Yaf_Dispatcher::setDefaultModule — デフォルトのモジュール名を変更する
    • Yaf_Dispatcher::setErrorHandler — エラーハンドラを設定する
    • Yaf_Dispatcher::setRequest — The setRequest purpose
    • Yaf_Dispatcher::setView — カスタムビューエンジンを設定する
    • Yaf_Dispatcher::throwException — 例外のスローのオン/オフを切り替える
  • Yaf_Config_Abstract — Yaf_Config_Abstract クラス
    • Yaf_Config_Abstract::get — ゲッター
    • Yaf_Config_Abstract::readonly — 設定項目が読み込み専用かどうかを調べる
    • Yaf_Config_Abstract::set — セッター
    • Yaf_Config_Abstract::toArray — 配列に変換する
  • Yaf_Config_Ini — Yaf_Config_Ini クラス
    • Yaf_Config_Ini::__construct — Yaf_Config_Ini のコンストラクタ
    • Yaf_Config_Ini::count — Yaf_Config.ini の全ての要素を数える
    • Yaf_Config_Ini::current — 現在の値を取得する
    • Yaf_Config_Ini::__get — 要素を取得する
    • Yaf_Config_Ini::__isset — キーが存在するかを判定する
    • Yaf_Config_Ini::key — 現在の要素のキーを取得する
    • Yaf_Config_Ini::next — 内部ポインタを進める
    • Yaf_Config_Ini::offsetExists — The offsetExists purpose
    • Yaf_Config_Ini::offsetGet — The offsetGet purpose
    • Yaf_Config_Ini::offsetSet — The offsetSet purpose
    • Yaf_Config_Ini::offsetUnset — The offsetUnset purpose
    • Yaf_Config_Ini::readonly — The readonly purpose
    • Yaf_Config_Ini::rewind — The rewind purpose
    • Yaf_Config_Ini::__set — The __set purpose
    • Yaf_Config_Ini::toArray — PHP の配列として構成を返す
    • Yaf_Config_Ini::valid — The valid purpose
  • Yaf_Config_Simple — Yaf_Config_Simple クラス
    • Yaf_Config_Simple::__construct — コンストラクタ
    • Yaf_Config_Simple::count — The count purpose
    • Yaf_Config_Simple::current — The current purpose
    • Yaf_Config_Simple::__get — The __get purpose
    • Yaf_Config_Simple::__isset — The __isset purpose
    • Yaf_Config_Simple::key — The key purpose
    • Yaf_Config_Simple::next — The next purpose
    • Yaf_Config_Simple::offsetExists — The offsetExists purpose
    • Yaf_Config_Simple::offsetGet — The offsetGet purpose
    • Yaf_Config_Simple::offsetSet — The offsetSet purpose
    • Yaf_Config_Simple::offsetUnset — The offsetUnset purpose
    • Yaf_Config_Simple::readonly — The readonly purpose
    • Yaf_Config_Simple::rewind — The rewind purpose
    • Yaf_Config_Simple::__set — The __set purpose
    • Yaf_Config_Simple::toArray — PHP の配列を返す
    • Yaf_Config_Simple::valid — The valid purpose
  • Yaf_Controller_Abstract — Yaf_Controller_Abstract クラス
    • Yaf_Controller_Abstract::__construct — Yaf_Controller_Abstract のコンストラクタ
    • Yaf_Controller_Abstract::display — The display purpose
    • Yaf_Controller_Abstract::forward — 別のアクションに転送する
    • Yaf_Controller_Abstract::getInvokeArg — The getInvokeArg purpose
    • Yaf_Controller_Abstract::getInvokeArgs — The getInvokeArgs purpose
    • Yaf_Controller_Abstract::getModuleName — モジュール名を取得する
    • Yaf_Controller_Abstract::getName — Get self name
    • Yaf_Controller_Abstract::getRequest — 現在のリクエストオブジェクトを取得する
    • Yaf_Controller_Abstract::getResponse — 現在のレスポンスオブジェクトを取得する
    • Yaf_Controller_Abstract::getView — ビューエンジンを取得する
    • Yaf_Controller_Abstract::getViewpath — getViewpath の目的を書く
    • Yaf_Controller_Abstract::init — コントローラを初期化する
    • Yaf_Controller_Abstract::initView — The initView purpose
    • Yaf_Controller_Abstract::redirect — URL にリダイレクトする
    • Yaf_Controller_Abstract::render — ビューテンプレートをレンダリングする
    • Yaf_Controller_Abstract::setViewpath — The setViewpath purpose
  • Yaf_Action_Abstract — Yaf_Action_Abstract クラス
    • Yaf_Action_Abstract::execute — アクションのエントリポイント
    • Yaf_Action_Abstract::getController — コントローラオブジェクトを取得する
    • Yaf_Action_Abstract::getControllerName — Get controller name
  • Yaf_View_Interface — Yaf_View_Interface クラス
    • Yaf_View_Interface::assign — 値をビューエンジンに代入する
    • Yaf_View_Interface::display — テンプレートをレンダリングして出力する
    • Yaf_View_Interface::getScriptPath — The getScriptPath purpose
    • Yaf_View_Interface::render — テンプレートをレンダリングする
    • Yaf_View_Interface::setScriptPath — The setScriptPath purpose
  • Yaf_View_Simple — Yaf_View_Simple クラス
    • Yaf_View_Simple::assign — 値を代入する
    • Yaf_View_Simple::assignRef — The assignRef purpose
    • Yaf_View_Simple::clear — 代入した値をクリアする
    • Yaf_View_Simple::__construct — Yaf_View_Simple のコンストラクタ
    • Yaf_View_Simple::display — レンダリングして表示する
    • Yaf_View_Simple::eval — テンプレートをレンダリングする
    • Yaf_View_Simple::__get — Retrieve assigned variable
    • Yaf_View_Simple::getScriptPath — テンプレートのディレクトリを取得する
    • Yaf_View_Simple::__isset — The __isset purpose
    • Yaf_View_Simple::render — テンプレートをレンダリングする
    • Yaf_View_Simple::__set — 値をエンジンに設定する
    • Yaf_View_Simple::setScriptPath — テンプレートのディレクトリを設定する
  • Yaf_Loader — Yaf_Loader クラス
    • Yaf_Loader::autoload — The autoload purpose
    • Yaf_Loader::clearLocalNamespace — The clearLocalNamespace purpose
    • Yaf_Loader::__construct — The __construct purpose
    • Yaf_Loader::getInstance — The getInstance purpose
    • Yaf_Loader::getLibraryPath — ライブラリパスを取得する
    • Yaf_Loader::getLocalNamespace — The getLocalNamespace purpose
    • Yaf_Loader::getNamespacePath — Retieve path of a registered namespace
    • Yaf_Loader::getLocalNamespace — Retrive all register namespaces info
    • Yaf_Loader::import — The import purpose
    • Yaf_Loader::isLocalName — The isLocalName purpose
    • Yaf_Loader::registerLocalNamespace — ローカルクラスプレフィックスを登録する
    • Yaf_Loader::registerNamespace — Register namespace with searching path
    • Yaf_Loader::setLibraryPath — ライブラリパスを変更する
  • Yaf_Plugin_Abstract — Yaf_Plugin_Abstract クラス
    • Yaf_Plugin_Abstract::dispatchLoopShutdown — The dispatchLoopShutdown purpose
    • Yaf_Plugin_Abstract::dispatchLoopStartup — ディスパッチループの前にフックする
    • Yaf_Plugin_Abstract::postDispatch — The postDispatch purpose
    • Yaf_Plugin_Abstract::preDispatch — The preDispatch purpose
    • Yaf_Plugin_Abstract::preResponse — The preResponse purpose
    • Yaf_Plugin_Abstract::routerShutdown — The routerShutdown purpose
    • Yaf_Plugin_Abstract::routerStartup — RouterStartup フック
  • Yaf_Registry — Yaf_Registry クラス
    • Yaf_Registry::__construct — Yaf_Registry はシングルトンを実装する
    • Yaf_Registry::del — アイテムをレジストリから削除する
    • Yaf_Registry::get — アイテムをレジストリから取得する
    • Yaf_Registry::has — アイテムが存在するかどうかを調べる
    • Yaf_Registry::set — アイテムをレジストリに追加する
  • Yaf_Request_Abstract — Yaf_Request_Abstract クラス
    • Yaf_Request_Abstract::clearParams — Remove all params
    • Yaf_Request_Abstract::getActionName — The getActionName purpose
    • Yaf_Request_Abstract::getBaseUri — The getBaseUri purpose
    • Yaf_Request_Abstract::getControllerName — The getControllerName purpose
    • Yaf_Request_Abstract::getEnv — ENV 変数を取得する
    • Yaf_Request_Abstract::getException — The getException purpose
    • Yaf_Request_Abstract::getLanguage — クライアントの好きな言語を取得する
    • Yaf_Request_Abstract::getMethod — リクエストメソッドを取得する
    • Yaf_Request_Abstract::getModuleName — The getModuleName purpose
    • Yaf_Request_Abstract::getParam — 呼び出しパラメータを取得する
    • Yaf_Request_Abstract::getParams — 全ての呼び出しパラメータを取得する
    • Yaf_Request_Abstract::getRequestUri — The getRequestUri purpose
    • Yaf_Request_Abstract::getServer — SERVER 変数を取得する
    • Yaf_Request_Abstract::isCli — CLIリクエストかを判定する
    • Yaf_Request_Abstract::isDispatched — リクエストがディスパッチ済みかを判定する
    • Yaf_Request_Abstract::isGet — GETリクエストかどうかを判定する
    • Yaf_Request_Abstract::isHead — HEADリクエストかどうかを判定する
    • Yaf_Request_Abstract::isOptions — OPTIONS リクエストかどうかを判定する
    • Yaf_Request_Abstract::isPost — POST リクエストかどうかを判定する
    • Yaf_Request_Abstract::isPut — PUTリクエストかどうかを判定する
    • Yaf_Request_Abstract::isRouted — リクエストがルーティング済みかを判定する
    • Yaf_Request_Abstract::isXmlHttpRequest — AJAXリクエストかどうかを判定する
    • Yaf_Request_Abstract::setActionName — アクション名を設定する
    • Yaf_Request_Abstract::setBaseUri — ベース URI を設定する
    • Yaf_Request_Abstract::setControllerName — コントローラー名を設定する
    • Yaf_Request_Abstract::setDispatched — The setDispatched purpose
    • Yaf_Request_Abstract::setModuleName — モジュール名を設定する
    • Yaf_Request_Abstract::setParam — 呼び出しパラメータをリクエストに設定する
    • Yaf_Request_Abstract::setRequestUri — The setRequestUri purpose
    • Yaf_Request_Abstract::setRouted — The setRouted purpose
  • Yaf_Request_Http — Yaf_Request_Http クラス
    • Yaf_Request_Http::__construct — Yaf_Request_Http のコンストラクタ
    • Yaf_Request_Http::get — クライアントからの変数を取得する
    • Yaf_Request_Http::getCookie — Cookie 変数を取得する
    • Yaf_Request_Http::getFiles — The getFiles purpose
    • Yaf_Request_Http::getPost — POST 変数を取得する
    • Yaf_Request_Http::getQuery — クエリパラメータを取得する
    • Yaf_Request_Http::getRaw — 生のリクエストボディを取得する
    • Yaf_Request_Http::getRequest — The getRequest purpose
    • Yaf_Request_Http::isXmlHttpRequest — リクエストが Ajax リクエストかどうかを判断する
  • Yaf_Request_Simple — Yaf_Request_Simple クラス
    • Yaf_Request_Simple::__construct — Yaf_Request_Simple のコンストラクタ
    • Yaf_Request_Simple::get — The get purpose
    • Yaf_Request_Simple::getCookie — The getCookie purpose
    • Yaf_Request_Simple::getFiles — The getFiles purpose
    • Yaf_Request_Simple::getPost — The getPost purpose
    • Yaf_Request_Simple::getQuery — The getQuery purpose
    • Yaf_Request_Simple::getRequest — The getRequest purpose
    • Yaf_Request_Simple::isXmlHttpRequest — リクエストが AJAX 経由のリクエストかどうかを判定する
  • Yaf_Response_Abstract — Yaf_Response_Abstract クラス
    • Yaf_Response_Abstract::appendBody — レスポンス本文に追記する
    • Yaf_Response_Abstract::clearBody — 既存のすべてのレスポンス本文を破棄します
    • Yaf_Response_Abstract::clearHeaders — すべてのヘッダをクリアする
    • Yaf_Response_Abstract::__construct — The __construct purpose
    • Yaf_Response_Abstract::__destruct — The __destruct purpose
    • Yaf_Response_Abstract::getBody — コンテンツを取得する
    • Yaf_Response_Abstract::getHeader — getHeader の目的
    • Yaf_Response_Abstract::prependBody — The prependBody purpose
    • Yaf_Response_Abstract::response — レスポンスを送信する
    • Yaf_Response_Abstract::setAllHeaders — The setAllHeaders purpose
    • Yaf_Response_Abstract::setBody — コンテンツをレスポンスに設定する
    • Yaf_Response_Abstract::setHeader — レスポンスヘッダを設定する
    • Yaf_Response_Abstract::setRedirect — The setRedirect purpose
    • Yaf_Response_Abstract::__toString — すべてのレスポンスボディを文字列として取得する
  • Yaf_Route_Interface — Yaf_Route_Interface クラス
    • Yaf_Route_Interface::assemble — リクエストを組み立てる
    • Yaf_Route_Interface::route — リクエストをルーティングする
  • Yaf_Route_Map — Yaf_Route_Map クラス
    • Yaf_Route_Map::assemble — URLを組み立てる
    • Yaf_Route_Map::__construct — The __construct purpose
    • Yaf_Route_Map::route — route の目的
  • Yaf_Route_Regex — Yaf_Route_Regex クラス
    • Yaf_Route_Regex::assemble — URL を組み立てる
    • Yaf_Route_Regex::__construct — Yaf_Route_Regex のコンストラクタ
    • Yaf_Route_Regex::route — The route purpose
  • Yaf_Route_Rewrite — Yaf_Route_Rewrite クラス
    • Yaf_Route_Rewrite::assemble — URLを組み立てる
    • Yaf_Route_Rewrite::__construct — Yaf_Route_Rewrite のコンストラクタ
    • Yaf_Route_Rewrite::route — The route purpose
  • Yaf_Router — Yaf_Router クラス
    • Yaf_Router::addConfig — 設定で定義したルートをルーターに追加する
    • Yaf_Router::addRoute — 新しいルートをルーターに追加する
    • Yaf_Router::__construct — Yaf_Router のコンストラクタ
    • Yaf_Router::getCurrentRoute — 使われているルート名を取得する
    • Yaf_Router::getRoute — 名前を指定してルートを取得する
    • Yaf_Router::getRoutes — 登録済みのルートを取得する
    • Yaf_Router::route — The route purpose
  • Yaf_Route_Simple — Yaf_Route_Simple クラス
    • Yaf_Route_Simple::assemble — URLを組み立てる
    • Yaf_Route_Simple::__construct — Yaf_Route_Simple のコンストラクタ
    • Yaf_Route_Simple::route — リクエストをルーティングする
  • Yaf_Route_Static — Yaf_Route_Static クラス
    • Yaf_Route_Static::assemble — URL を組み立てる
    • Yaf_Route_Static::match — The match purpose
    • Yaf_Route_Static::route — リクエストをルーティングする
  • Yaf_Route_Supervar — Yaf_Route_Supervar クラス
    • Yaf_Route_Supervar::assemble — URL を組み立てる
    • Yaf_Route_Supervar::__construct — The __construct purpose
    • Yaf_Route_Supervar::route — The route purpose
  • Yaf_Session — Yaf_Session クラス
    • Yaf_Session::__construct — Yaf_Session のコンストラクタ
    • Yaf_Session::count — The count purpose
    • Yaf_Session::current — The current purpose
    • Yaf_Session::del — The del purpose
    • Yaf_Session::__get — The __get purpose
    • Yaf_Session::getInstance — The getInstance purpose
    • Yaf_Session::has — The has purpose
    • Yaf_Session::__isset — The __isset purpose
    • Yaf_Session::key — The key purpose
    • Yaf_Session::next — The next purpose
    • Yaf_Session::offsetExists — The offsetExists purpose
    • Yaf_Session::offsetGet — The offsetGet purpose
    • Yaf_Session::offsetSet — The offsetSet purpose
    • Yaf_Session::offsetUnset — The offsetUnset purpose
    • Yaf_Session::rewind — The rewind purpose
    • Yaf_Session::__set — The __set purpose
    • Yaf_Session::start — The start purpose
    • Yaf_Session::__unset — The __unset purpose
    • Yaf_Session::valid — The valid purpose
  • Yaf_Exception — Yaf_Exception クラス
    • Yaf_Exception::__construct — コンストラクタ
    • Yaf_Exception::getPrevious — The getPrevious purpose
  • Yaf_Exception_TypeError — Yaf_Exception_TypeError クラス
  • Yaf_Exception_StartupError — Yaf_Exception_StartupError クラス
  • Yaf_Exception_DispatchFailed — Yaf_Exception_DispatchFailed クラス
  • Yaf_Exception_RouterFailed — Yaf_Exception_RouterFailed クラス
  • Yaf_Exception_LoadFailed — Yaf_Exception_LoadFailed クラス
  • Yaf_Exception_LoadFailed_Module — Yaf_Exception_LoadFailed_Module クラス
  • Yaf_Exception_LoadFailed_Controller — Yaf_Exception_LoadFailed_Controller クラス
  • Yaf_Exception_LoadFailed_Action — Yaf_Exception_LoadFailed_Action クラス
  • Yaf_Exception_LoadFailed_View — Yaf_Exception_LoadFailed_View クラス


はじめに

Yet Another Framework(Yaf) 拡張モジュールは PHP のフレームワークで、ウェブアプリケーションの開発に使います。

ちょっとした Yaf のベンチマークが » Yaf Performance にあります。

手っ取り早く使い始めるには、チュートリアルを参照ください。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Yaf
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaf.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


実行時設定

php.ini の設定により動作が変化します。

Yaf 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yaf.library |  | INI_ALL |
yaf.action_prefer | 0 | INI_ALL |
yaf.lowcase_path | 0 | INI_ALL |
yaf.use_spl_autoload | 0 | INI_ALL |
yaf.forward_limit | 5 | INI_ALL |
yaf.name_suffix | 1 | INI_ALL |
yaf.name_separator |  | INI_ALL |
yaf.cache_config | 0 | INI_SYSTEM |
yaf.environ | product | INI_SYSTEM |
yaf.use_namespace | 0 | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

yaf.library string

グローバルライブラリパス。Yaf_loader は グローバルライブラリをこのディレクトリから探します。

yaf.action_prefer int

PATH_INFO の要素がひとつだけだった場合に、 それをコントローラとみなすかアクションとみなすか。

この設定を On にすると、アクション名とみなします。

yaf.lowcase_path int

クラスのオートロード時に、すべてのパスを小文字にするかどうか。

yaf.use_spl_autoload int

この値を On にすると、Yaf_Loader がクラスを見つけられなかったときに false を返し、 その他のオートロード関数を呼べるようにします。

この値を Off にすると、Yaf_Loader がクラスを見つけられなかったときに true を返し、 クラスのオートロードをそこで失敗させます。

注意:

Yaf がローダーを登録するのは Yaf_Application のインスタンスを作るときです。 なので、その前に登録されたオートローダーが呼ばれるのは Yaf_Loader::autoload() より前になります。

この値が Off (デフォルト) の場合、 Yaf_Loader::autoload() は常に true を返します。

yaf.forward_limit int

最大の転送回数で、デフォルトは 5。 つまり、最大で 5 件まで転送スタックに積めるということです。

これは、 Yaf_Controller_Abstract::forward() の再帰を防ぐための保護です。

yaf.name_suffix int

これを On にすると、Yaf_Loader はクラスのサフィックスを見て MVC クラスかどうかを判断します。

これが Off の場合は、Yaf_Loader はクラス名のプレフィックスを見ます。

yaf.name_separator string

空の値以外を指定すると、Yaf_Loader はクラスのサフィックスを この文字列で判断します。

たとえば、この値を "_" にすると、Yaf_Loader は Index_Controller をコントローラクラスとみなし、IndexController は通常のクラスとみなします。

yaf.cache_config int

これを On にしているときに ini ファイルを Yaf_Application() のパラメータに使うと、ini ファイルのコンパイル結果を PHP プロセスにキャッシュします。

注意:

Yaf は ini ファイルの最終更新時刻を調べ、 前回のコンパイル以降に変更があった場合は読みなおします。

警告

Yaf は ini ファイルのパスをキャッシュエントリのキーとして使います。 そのため、ini ファイルは絶対パスで指定しておきましょう。 そうしないと、もし複数のアプリケーションが 同じ相対パスに ini ファイルを持っていたときに、衝突が発生します。

yaf.environ string

デフォルト値は "product" で、Yaf が ini ファイルのどのセクションを読み込むのかを指定します。

つまり、もしこの値が "product" なら、Yaf は ini ファイルの "product" セクションを読んで Yaf_Application の最終設定をします。ini ファイルは Yaf_Application への最初の引数で指定します。

yaf.use_namespace int

この値を On にすると、 Yaf のすべてのクラスが名前空間形式になります。

たとえば

Yaf_Route_Rewrite => \Yaf\Route\Rewrite
Yaf_Request_Http  => \Yaf\Request\Http
のようになります。ただ、 Yaf_Controller_Abstract のような例外もあります。最後の部分が PHP の予約語と同じなので、 クラス名として使うことができません。そんなクラスの場合は、次のようになります。
Yaf_Controller_Abstract => \Yaf\Controller_Abstract
Yaf_Route_Static => \Yaf\Route_Static


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

YAF_VERSION (string)
YAF_ENVIRON (string)
YAF_ERR_STARTUP_FAILED (int)
YAF_ERR_ROUTE_FAILED (int)
YAF_ERR_DISPATCH_FAILED (int)
YAF_ERR_AUTOLOAD_FAILED (int)
YAF_ERR_NOTFOUND_MODULE (int)
YAF_ERR_NOTFOUND_CONTROLLER (int)
YAF_ERR_NOTFOUND_ACTION (int)
YAF_ERR_NOTFOUND_VIEW (int)
YAF_ERR_CALL_FAILED (int)
YAF_ERR_TYPE_ERROR (int)


例

例1 標準的なアプリケーションのディレクトリ構造

- index.php
- .htaccess
+ conf
  |- application.ini // アプリケーションの設定
- application/
  - Bootstrap.php
  + controllers
     - Index.php // デフォルトのコントローラ
  + views
     |+ index
        - index.phtml // デフォルトアクション用のビューテンプレート
  + modules
  - library
  - models
  - plugins

例2 エントリ

トップディレクトリの index.php が、アプリケーションの唯一の入り口です。 index.php へのすべてのリクエストをリダイレクトしなければいけません (Apache+mod_php なら .htaccess を使えます)。

<?php
define("APPLICATION_PATH", dirname(__FILE__));

$app = new Yaf_Application(APPLICATION_PATH . "/conf/application.ini");
$app->bootstrap() // Bootstrap.php で定義した bootstrap メソッドを呼びます
->run();
?>

例3 リライトルール

#for apache (.htaccess)
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule .* index.php

#for nginx
server {
  listen ****;
  server_name  domain.com;
  root   document_root;
  index  index.php index.html index.htm;

  if (!-e $request_filename) {
    rewrite ^/(.*)  /index.php$1 last;
  }
}

#for lighttpd
$HTTP["host"] =~ "(www.)?domain.com$" {
  url.rewrite = (
     "^/(.+)/?$"  => "/index.php/$1",
  )
}

例4 アプリケーションの設定

[yaf]
; APPLICATION_PATH は index.php で定義した定数
application.directory=APPLICATION_PATH "/application/"

; product セクションは yaf セクションを継承する
[product:yaf]
foo=bar

例5 デフォルトのコントローラ

<?php
class IndexController extends Yaf_Controller_Abstract {
/* デフォルトアクション */
public function indexAction() {
$this->_view->word = "hello world";
// あるいは
// $this->getView()->word = "hello world";
}
}
?>

例6 デフォルトのビューテンプレート

<html>
<head>
<title>Hello World</title>
</head>
<body>
<?php echo $word;?>
 </body>
</html>

例7 アプリケーションの実行

上の例の出力は、 たとえば以下のようになります。

<html>
 <head>
   <title>Hello World</title>
 </head>
 <body>
   hello world
 </body>
</html>

注意:

このサンプルは Yaf のコードジェネレータで生成できます。コードジェネレータは yaf@github にあります。


アプリケーションの設定

設定内容を記した配列か、あるいは ini ファイルへのパス (Yaf_Config_Ini を参照ください) を Yaf_Application::__construct() に渡さなければいけません。

Yaf は、アプリケーションの設定とユーザーの設定を自動的にマージします。 アプリケーションの設定には、プレフィックスとして "yaf." あるいは "application." がつきます。"yaf." と "application." の両方が存在する場合は、"application." を使います。

例1 PHP の配列の例

<?php
$configs = array(
"application" => array(
"directory" => dirname(__FILE__),
"dispatcher" => array(
"catchException" => 0,
),
"view" => array(
"ext" => "phtml",
),
),
);
$app = new Yaf_Application($configs);
?>

例2 ini ファイルの例

[yaf]
yaf.directory = APPLICATION_PATH "/appliation"
yaf.dispatcher.catchException = 0

[product : yaf]
; user configuration list here

Yaf アプリケーション設定
名前 | デフォルト | 変更履歴
application.directory |  |
application.ext | "php" |
application.view.ext | "phtml" |
application.modules | "index" |
application.library | application.directory . "/library" |
application.library.directory | application.directory . "/library" |
application.library.namespace | "" |
application.bootstrap | application.directory . "/Bootstrap" . application.ext |
application.baseUri | "" |
application.dispatcher.defaultRoute |  |
application.dispatcher.throwException | 1 |
application.dispatcher.catchException | 0 |
application.dispatcher.defaultModule | "index" |
application.dispatcher.defaultController | "index" |
application.dispatcher.defaultAction | "index" |
application.system |  |

以下に設定ディレクティブに関する 簡単な説明を示します。

application.directory string

アプリケーションのディレクトリ。このフォルダの中に "controllers"、"views"、"models"、"plugins" といったフォルダを配置します。

注意:

この項目は、デフォルト値を持たない唯一の項目です。 つまり、必ず手動で指定しなければいけません。

application.ext string

PHP スクリプトファイルの拡張子。クラスのオートロード (Yaf_Loader) で利用します。

application.view.ext string

ビューテンプレートスクリプトのファイル拡張子。

application.modules string

登録済みモジュールのカンマ区切りのリスト。特に、 ルーティングで PATH_INFO に三つ以上のセグメントがあるときに使います。

Yaf は、最初のセグメントがモジュール名なのかそうでないのかを知る手段が必要です。

application.library string

ローカルライブラリディレクトリ。Yaf_Loader および yaf.library を参照ください。

注意:

Yaf 2.1.6 以降では、この項目に配列を指定できるようになりました。 配列を指定した場合、ライブラリパスには application.library.directory の値を使います。

application.library.directory string

application.library のエイリアス。 Yaf 2.1.6 で導入されました。

application.library.namespace string

カンマ区切りで表した、ローカルライブラリ名前空間のプレフィックス。

Yaf 2.1.6 で導入されました。

application.bootstrap string

ブートストラップクラスのスクリプトへの絶対パス。

application.baseUri string

ルーティング時に、決まったプレフィックスをリクエスト URI から取り除くために使います。 例として、リクエスト URI が "/prefix/controller/action" だった場合を考えましょう。 application.baseUri を "/prefix" にしておくと、 ルーティング時に "/controller/action" だけが PATH_INFO とみなされるようになります。

ふつうは、この値を設定する必要はありません。

application.dispatcher.throwException bool

これを On にすると、エラーが発生したときに Yaf が例外をスローするようになります。 Yaf_Dispatcher::throwException() も参照ください。

application.dispatcher.catchException bool

これを On にすると、Yaf が例外をキャッチできなかったときに Error コントローラの Error アクションに転送するようになります。 Yaf_Dispatcher::catchException() も参照ください。

application.dispatcher.defaultRoute string

デフォルトのルート。指定しなかった場合は、デフォルトとして Static ルートを使います。 Yaf_Router::addRoute() も参照ください。

application.dispatcher.defaultModule string

デフォルトのモジュール名。 Yaf_Dispatcher::setDefaultModule() も参照ください。

application.dispatcher.defaultController string

デフォルトのコントローラ名。 Yaf_Dispatcher::setDefaultController() も参照ください。

application.dispatcher.defaultAction string

デフォルトのアクション名。 Yaf_Dispatcher::setDefaultAction() も参照ください。

application.system string

yaf の実行時の設定を、application.ini で application.system.lowcase_path のように設定します。

注意:

この方法で設定できるのは INI_ALL の項目だけです。


Yaf_Application クラス

(Yaf >=1.0.0)

はじめに

Yaf_Application はアプリケーションのブートストラップ機能を提供します。 再利用可能なリソース、共有できるモジュールベースのブートストラップクラス、 そして依存関係のチェックなどです。

注意:

Yaf_Application はシングルトンパターンを実装しており、 シリアライズやアンシリアライズはできません。これは、 PHPUnit を使って Yaf 用のテストケースを書こうとしたときに問題の原因となります。

PHPUnit の @backupGlobals アノテーションを使えば グローバル変数のバックアップやりストア操作を制御できるので、 この問題に対応できます。

クラス概要

final class Yaf_Application {
/* プロパティ */
protected $config;
protected $dispatcher;
protected static $_app;
protected $_modules;
protected $_running;
protected $_environ;
/* メソッド */
public __construct(mixed $config, string $envrion = ?)
public static app(): mixed
public bootstrap(Yaf_Bootstrap_Abstract $bootstrap = ?): void
public clearLastError(): Yaf_Application
public environ(): void
public execute(callable $entry, string ...$args): void
public getAppDirectory(): Yaf_Application
public getConfig(): Yaf_Config_Abstract
public getDispatcher(): Yaf_Dispatcher
public getLastErrorMsg(): string
public getLastErrorNo(): int
public getModules(): array
public run(): void
public setAppDirectory(string $directory): Yaf_Application
public __destruct()
}

プロパティ

config

dispatcher

_app

_modules

_running

_environ

目次

  • Yaf_Application::app — アプリケーションのインスタンスを取得する
  • Yaf_Application::bootstrap — ブートストラップをコールする
  • Yaf_Application::clearLastError — 直近のエラー情報を消す
  • Yaf_Application::__construct — Yaf_Application のコンストラクタ
  • Yaf_Application::__destruct — デストラクタ
  • Yaf_Application::environ — 環境を取得する
  • Yaf_Application::execute — コールバックを実行する
  • Yaf_Application::getAppDirectory — アプリケーションディレクトリを取得する
  • Yaf_Application::getConfig — 設定情報を取得する
  • Yaf_Application::getDispatcher — Yaf_Dispatcher のインスタンスを取得する
  • Yaf_Application::getLastErrorMsg — 直近で発生したエラーのメッセージを取得する
  • Yaf_Application::getLastErrorNo — 直近で発生したエラーのコードを取得する
  • Yaf_Application::getModules — 定義済みのモジュール名を取得する
  • Yaf_Application::run — Yaf_Application を開始する
  • Yaf_Application::setAppDirectory — アプリケーションディレクトリを変更する


アプリケーションのインスタンスを取得する

  • ≪ Yaf_Application
  • Yaf_Application::bootstrap ≫
  • PHP Manual
  • Yaf_Application
  • アプリケーションのインスタンスを取得する

Yaf_Application::app

(Yaf >=1.0.0)

Yaf_Application::app — アプリケーションのインスタンスを取得する

説明

public static Yaf_Application::app(): mixed

Yaf_Application のインスタンスを取得します。 別の方法として、 Yaf_Dispatcher::getApplication() も使えます。

パラメータ

この関数にはパラメータはありません。

戻り値

Yaf_Application のインスタンスを返します。まだ Yaf_Application を初期化していない場合は null を返します。

参考

  • Yaf_Dispatcher::getApplication() - アプリケーションを取得する


ブートストラップをコールする

  • ≪ Yaf_Application::app
  • Yaf_Application::clearLastError ≫
  • PHP Manual
  • Yaf_Application
  • ブートストラップをコールする

Yaf_Application::bootstrap

(Yaf >=1.0.0)

Yaf_Application::bootstrap — ブートストラップをコールする

説明

public Yaf_Application::bootstrap(Yaf_Bootstrap_Abstract $bootstrap = ?): void

ブートストラップを実行します。"_init" で始まる名前のすべてのメソッドを その定義順に実行します。bootstrap パラメータを省略した場合は、 application.directory からブートストラップを探します。

パラメータ

bootstrap

Yaf_Bootstrap_Abstract のインスタンス。

戻り値

Yaf_Application のインスタンスを返します。

例

例1 Bootstrap() の例

<?php
/**
* This file should be under the APPLICATION_PATH . "/application/"(which was defined in the config passed to Yaf_Application).
* and named Bootstrap.php, so the Yaf_Application can find it
*/
class Bootstrap extends Yaf_Bootstrap_Abstract {
function _initConfig(Yaf_Dispatcher $dispatcher) {
echo "1st called\n";
}

function _initPlugin($dispatcher) {
echo "2nd called\n";
}
}
?>

例2 Yaf_Application::bootstrap() の例

<?php

defined('APPLICATION_PATH') // APPLICATION_PATH will be used in the ini config file
|| define('APPLICATION_PATH', __DIR__);

$application = new Yaf_Application(APPLICATION_PATH.'/conf/application.ini');
$application->bootstrap();
?>

上の例の出力は、 たとえば以下のようになります。

1st called
2nd called

参考

  • Yaf_Bootstrap_Abstract


直近のエラー情報を消す

  • ≪ Yaf_Application::bootstrap
  • Yaf_Application::__construct ≫
  • PHP Manual
  • Yaf_Application
  • 直近のエラー情報を消す

Yaf_Application::clearLastError

(Yaf >=2.1.2)

Yaf_Application::clearLastError — 直近のエラー情報を消す

説明

public Yaf_Application::clearLastError(): Yaf_Application

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Application::clearLastError() の例

<?php
function error_handler($errno, $errstr, $errfile, $errline) {
Yaf_Application::app()->clearLastError();
var_dump(Yaf_Application::app()->getLastErrorNo());
}

$config = array(
"application" => array(
"directory" => "/tmp/notexists",
"dispatcher" => array(
"throwException" => 0, // エラーが発生したときに、例外ではなくエラーとして扱います
),
),
);

$app = new Yaf_Application($config);
$app->getDispatcher()->setErrorHandler("error_handler", E_RECOVERABLE_ERROR);
$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

int(0)


Yaf_Application のコンストラクタ

  • ≪ Yaf_Application::clearLastError
  • Yaf_Application::__destruct ≫
  • PHP Manual
  • Yaf_Application
  • Yaf_Application のコンストラクタ

Yaf_Application::__construct

(Yaf >=1.0.0)

Yaf_Application::__construct — Yaf_Application のコンストラクタ

説明

public Yaf_Application::__construct(mixed $config, string $envrion = ?)

Yaf_Application のインスタンスを作成します。

パラメータ

config

ini ファイルへのパス、あるいは設定の配列。

ini ファイルを指定する場合は、 yaf.environ で定義した名前のセクションが必要です。 デフォルトは "product" です。

注意:

ini ファイルをアプリケーションの設定コンテナとして使うのなら、 yaf.cache_config でパフォーマンスを改善できます。 performance.

設定項目とそのデフォルト値の一覧を示します。

例1 ini ファイルの例

[product]
;this one should alway be defined, and have no default value
application.directory=APPLICATION_PATH

;following configs have default value, you may no need to define them
application.library = APPLICATION_PATH . "/library"
application.dispatcher.throwException=1
application.dispatcher.catchException=1

application.baseUri=""

;the php script ext name
ap.ext=php

;the view template ext name
ap.view.ext=phtml

ap.dispatcher.defaultModule=Index
ap.dispatcher.defaultController=Index
ap.dispatcher.defaultAction=index

;defined modules
ap.modules=Index

envrion

最終的な設定として、どのセクションを読み込むか。

戻り値

例

例2 Yaf_Application::__construct() の例

<?php
defined('APPLICATION_PATH') // APPLICATION_PATH が ini ファイルで設定されていれば使います
|| define('APPLICATION_PATH', __DIR__));

$application = new Yaf_Application(APPLICATION_PATH.'/conf/application.ini');
$application->bootstrap()->run();
?>

上の例の出力は、 たとえば以下のようになります。

例3 Yaf_Application::__construct() の例

<?php
$config = array(
    "application" => array(
        "directory" => realpath(dirname(__FILE__)) . "/application",
    ),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
$application->bootstrap()->run();
?>

上の例の出力は、
たとえば以下のようになります。

参考

  • Yaf_Config_Ini
    •


デストラクタ

  • ≪ Yaf_Application::__construct
  • Yaf_Application::environ ≫
  • PHP Manual
  • Yaf_Application
  • デストラクタ

Yaf_Application::__destruct

(Yaf >=1.0.0)

Yaf_Application::__destruct — デストラクタ

説明

public Yaf_Application::__destruct()

パラメータ

この関数にはパラメータはありません。

戻り値


環境を取得する

  • ≪ Yaf_Application::__destruct
  • Yaf_Application::execute ≫
  • PHP Manual
  • Yaf_Application
  • 環境を取得する

Yaf_Application::environ

(Yaf >=1.0.0)

Yaf_Application::environ — 環境を取得する

説明

public Yaf_Application::environ(): void

環境を取得します。これは yaf.environ で定義されており、デフォルト値は "product" です。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Application::environ() の例

<?php
$config = array(
"application" => array(
"directory" => realpath(dirname(__FILE__)) . "/application",
),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->environ());
?>

上の例の出力は、 たとえば以下のようになります。

product


コールバックを実行する

  • ≪ Yaf_Application::environ
  • Yaf_Application::getAppDirectory ≫
  • PHP Manual
  • Yaf_Application
  • コールバックを実行する

Yaf_Application::execute

(Yaf >=1.0.0)

Yaf_Application::execute — コールバックを実行する

説明

public Yaf_Application::execute(callable $entry, string ...$args): void

このメソッドは一般的に、Yaf_Application を crontab で実行させるときに使います。 crontab では、オートローダーやブートストラップの仕組みも使えます。

パラメータ

entry

有効なコールバック。

args

コールバックに渡すパラメータ。

戻り値

例

例1 Yaf_Application::execute() の例

<?php
function main($argc, $argv) {
}

$config = array(
"application" => array(
"directory" => realpath(dirname(__FILE__)) . "/application",
),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
$application->execute("main", $argc, $argv);
?>

上の例の出力は、 たとえば以下のようになります。


アプリケーションディレクトリを取得する

  • ≪ Yaf_Application::execute
  • Yaf_Application::getConfig ≫
  • PHP Manual
  • Yaf_Application
  • アプリケーションディレクトリを取得する

Yaf_Application::getAppDirectory

(Yaf >=2.1.4)

Yaf_Application::getAppDirectory — アプリケーションディレクトリを取得する

説明

public Yaf_Application::getAppDirectory(): Yaf_Application

パラメータ

directory

戻り値


設定情報を取得する

  • ≪ Yaf_Application::getAppDirectory
  • Yaf_Application::getDispatcher ≫
  • PHP Manual
  • Yaf_Application
  • 設定情報を取得する

Yaf_Application::getConfig

(Yaf >=1.0.0)

Yaf_Application::getConfig — 設定情報を取得する

説明

public Yaf_Application::getConfig(): Yaf_Config_Abstract

パラメータ

この関数にはパラメータはありません。

戻り値

Yaf_Config_Abstract のインスタンスを返します。

例

例1 Yaf_Application::getConfig() の例

<?php
$config = array(
"application" => array(
"directory" => realpath(dirname(__FILE__)) . "/application",
),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->getConfig());
?>

上の例の出力は、 たとえば以下のようになります。

Yaf_Config_Simple Object
(
    [_config:protected] => Array
        (
            [application] => Array
                (
                    [directory] => /home/laruence/local/www/htdocs/application
                )

        )

    [_readonly:protected] => 1
)


Yaf_Dispatcher のインスタンスを取得する

  • ≪ Yaf_Application::getConfig
  • Yaf_Application::getLastErrorMsg ≫
  • PHP Manual
  • Yaf_Application
  • Yaf_Dispatcher のインスタンスを取得する

Yaf_Application::getDispatcher

(Yaf >=1.0.0)

Yaf_Application::getDispatcher — Yaf_Dispatcher のインスタンスを取得する

説明

public Yaf_Application::getDispatcher(): Yaf_Dispatcher

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Application::getDispatcher() の例

<?php
$config = array(
"application" => array(
"directory" => realpath(dirname(__FILE__)) . "/application",
),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->getDispatcher());
?>

上の例の出力は、 たとえば以下のようになります。

Yaf_Dispatcher Object
(
    [_router:protected] => Yaf_Router Object
        (
            [_routes:protected] => Array
                (
                    [_default] => Yaf_Route_Static Object
                        (
                        )

                )

            [_current:protected] =>
        )

    [_view:protected] =>
    [_request:protected] => Yaf_Request_Http Object
        (
            [module] =>
            [controller] =>
            [action] =>
            [method] => Cli
            [params:protected] => Array
                (
                )

            [language:protected] =>
            [_exception:protected] =>
            [_base_uri:protected] =>
            [uri:protected] =>
            [dispatched:protected] =>
            [routed:protected] =>
        )

    [_plugins:protected] => Array
        (
        )

    [_auto_render:protected] => 1
    [_return_response:protected] =>
    [_instantly_flush:protected] =>
    [_default_module:protected] => Index
    [_default_controller:protected] => Index
    [_default_action:protected] => index
    [_response] => Yaf_Response_Cli Object
        (
            [_header:protected] => Array
                (
                )

            [_body:protected] =>
            [_sendheader:protected] =>
        )

)


直近で発生したエラーのメッセージを取得する

  • ≪ Yaf_Application::getDispatcher
  • Yaf_Application::getLastErrorNo ≫
  • PHP Manual
  • Yaf_Application
  • 直近で発生したエラーのメッセージを取得する

Yaf_Application::getLastErrorMsg

(Yaf >=2.1.2)

Yaf_Application::getLastErrorMsg — 直近で発生したエラーのメッセージを取得する

説明

public Yaf_Application::getLastErrorMsg(): string

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Application::getLastErrorMsg() の例

<?php
function error_handler($errno, $errstr, $errfile, $errline) {
var_dump(Yaf_Application::app()->getLastErrorMsg());
}

$config = array(
"application" => array(
"directory" => "/tmp/notexists",
"dispatcher" => array(
"throwException" => 0, // エラーが発生したときに、例外をスローするのではなくエラーにします
),
),
);

$app = new Yaf_Application($config);
$app->getDispatcher()->setErrorHandler("error_handler", E_RECOVERABLE_ERROR);
$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

string(69) "Could not find controller script /tmp/notexists/controllers/Index.php"


直近で発生したエラーのコードを取得する

  • ≪ Yaf_Application::getLastErrorMsg
  • Yaf_Application::getModules ≫
  • PHP Manual
  • Yaf_Application
  • 直近で発生したエラーのコードを取得する

Yaf_Application::getLastErrorNo

(Yaf >=2.1.2)

Yaf_Application::getLastErrorNo — 直近で発生したエラーのコードを取得する

説明

public Yaf_Application::getLastErrorNo(): int

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Application::getLastErrorNo() の例

<?php
function error_handler($errno, $errstr, $errfile, $errline) {
var_dump(Yaf_Application::app()->getLastErrorNo());
var_dump(Yaf_Application::app()->getLastErrorNo() == YAF_ERR_NOTFOUND_CONTROLLER);
}

$config = array(
"application" => array(
"directory" => "/tmp/notexists",
"dispatcher" => array(
"throwException" => 0, // エラーが発生したときに、例外をスローするのではなくエラーにします
),
),
);

$app = new Yaf_Application($config);
$app->getDispatcher()->setErrorHandler("error_handler", E_RECOVERABLE_ERROR);
$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

int(516)
bool(true)


定義済みのモジュール名を取得する

  • ≪ Yaf_Application::getLastErrorNo
  • Yaf_Application::run ≫
  • PHP Manual
  • Yaf_Application
  • 定義済みのモジュール名を取得する

Yaf_Application::getModules

(Yaf >=1.0.0)

Yaf_Application::getModules — 定義済みのモジュール名を取得する

説明

public Yaf_Application::getModules(): array

設定で定義したモジュールのリストを取得します。 何も定義していない場合は "Index" だけになります。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Application::getModules() の例

<?php
$config = array(
"application" => array(
"directory" => realpath(dirname(__FILE__)) . "/application",
),
);

/** Yaf_Application */
$application = new Yaf_Application($config);
print_r($application->getModules());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Index
)


Yaf_Application を開始する

  • ≪ Yaf_Application::getModules
  • Yaf_Application::setAppDirectory ≫
  • PHP Manual
  • Yaf_Application
  • Yaf_Application を開始する

Yaf_Application::run

(Yaf >=1.0.0)

Yaf_Application::run — Yaf_Application を開始する

説明

public Yaf_Application::run(): void

Yaf_Application を実行します。つまり、Yaf_Application がリクエストを受け取ってルーティングし、コントローラのアクションにディスパッチして レスポンスをレンダリングできるようにします。最終的に、レスポンスをクライアントに返します。

パラメータ

この関数にはパラメータはありません。

戻り値


アプリケーションディレクトリを変更する

  • ≪ Yaf_Application::run
  • Yaf_Bootstrap_Abstract ≫
  • PHP Manual
  • Yaf_Application
  • アプリケーションディレクトリを変更する

Yaf_Application::setAppDirectory

(Yaf >=2.1.4)

Yaf_Application::setAppDirectory — アプリケーションディレクトリを変更する

説明

public Yaf_Application::setAppDirectory(string $directory): Yaf_Application

パラメータ

directory

戻り値


Yaf_Bootstrap_Abstract クラス

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

ブートストラップとは、アプリケーションを実行する前の初期設定に使う仕組みのことです。

ユーザーが自前のブートストラップクラスを定義するには、 Yaf_Bootstrap_Abstract を継承します。

ブートストラップクラスで定義したメソッドの中で "_init" で始まるものがすべて、定義した順に Yaf_Application::bootstrap() から呼ばれます。

例

例1 ブートストラップの例

<?php
/* ブートストラップクラスは ./application/Bootstrap.php で定義しないといけません */
class Bootstrap extends Yaf_Bootstrap_Abstract {
public function _initConfig(Yaf_Dispatcher $dispatcher) {
var_dump(__METHOD__);
}
public function _initPlugin(Yaf_Dispatcher $dispatcher) {
var_dump(__METHOD__);
}
}

$config = array(
"application" => array(
"directory" => dirname(__FILE__) . "/application/",
),
);

$app = new Yaf_Application($config);
$app->bootstrap();
?>

上の例の出力は、 たとえば以下のようになります。

string(22) "Bootstrap::_initConfig"
string(22) "Bootstrap::_initPlugin"

クラス概要

abstract class Yaf_Bootstrap_Abstract {
/* プロパティ */
/* メソッド */
}


Yaf_Dispatcher クラス

(Yaf >=1.0.0)

はじめに

Yaf_Dispatcher の役割は、 リクエスト環境の初期化、やってきたリクエストのルーティング、 そして見つかったアクションへのディスパッチです。 あらゆるレスポンスを取りまとめ、処理が完了した後でそれを返します。

Yaf_Dispatcher はシングルトンパターンを実装しています。 つまり、同時に複数のインスタンスは作れないということです。 そのため、このクラスをレジストリとして使い、 ディスパッチ中に他のオブジェクトから参照させることもできます。

クラス概要

final class Yaf_Dispatcher {
/* プロパティ */
protected $_router;
protected $_view;
protected $_request;
protected $_plugins;
protected static $_instance;
protected $_auto_render;
protected $_return_response;
protected $_instantly_flush;
protected $_default_module;
protected $_default_controller;
protected $_default_action;
/* メソッド */
public __construct()
public autoRender(bool $flag = ?): Yaf_Dispatcher
public catchException(bool $flag = ?): Yaf_Dispatcher
public disableView(): bool
public dispatch(Yaf_Request_Abstract $request): Yaf_Response_Abstract
public enableView(): Yaf_Dispatcher
public flushInstantly(bool $flag = ?): Yaf_Dispatcher
public getApplication(): Yaf_Application
public getDefaultAction(): string
public getDefaultController(): string
public getDefaultModule(): string
public static getInstance(): Yaf_Dispatcher
public getRequest(): Yaf_Request_Abstract
public getRouter(): Yaf_Router
public initView(string $templates_dir, array $options = ?): Yaf_View_Interface
public registerPlugin(Yaf_Plugin_Abstract $plugin): Yaf_Dispatcher
public returnResponse(bool $flag): Yaf_Dispatcher
public setDefaultAction(string $action): Yaf_Dispatcher
public setDefaultController(string $controller): Yaf_Dispatcher
public setDefaultModule(string $module): Yaf_Dispatcher
public setErrorHandler(call $callback, int $error_types): Yaf_Dispatcher
public setRequest(Yaf_Request_Abstract $request): Yaf_Dispatcher
public setView(Yaf_View_Interface $view): Yaf_Dispatcher
public throwException(bool $flag = ?): Yaf_Dispatcher
}

プロパティ

_router

_view

_request

_plugins

_instance

_auto_render

_return_response

_instantly_flush

_default_module

_default_controller

_default_action

目次

  • Yaf_Dispatcher::autoRender — 自動レンダリングのオン/オフを切り替える
  • Yaf_Dispatcher::catchException — 例外のキャッチのオン/オフを切り替える
  • Yaf_Dispatcher::__construct — Yaf_Dispatcher のコンストラクタ
  • Yaf_Dispatcher::disableView — ビューのレンダリングを無効にする
  • Yaf_Dispatcher::dispatch — リクエストをディスパッチする
  • Yaf_Dispatcher::enableView — ビューのレンダリングを有効にする
  • Yaf_Dispatcher::flushInstantly — その場でのフラッシュのオン/オフを切り替える
  • Yaf_Dispatcher::getApplication — アプリケーションを取得する
  • Yaf_Dispatcher::getDefaultAction — Retrive the default action name
  • Yaf_Dispatcher::getDefaultController — Retrive the default controller name
  • Yaf_Dispatcher::getDefaultModule — Retrive the default module name
  • Yaf_Dispatcher::getInstance — ディスパッチャのインスタンスを取得する
  • Yaf_Dispatcher::getRequest — リクエストのインスタンスを取得する
  • Yaf_Dispatcher::getRouter — ルーターのインスタンスを取得する
  • Yaf_Dispatcher::initView — ビューを初期化して返す
  • Yaf_Dispatcher::registerPlugin — プラグインを登録する
  • Yaf_Dispatcher::returnResponse — The returnResponse purpose
  • Yaf_Dispatcher::setDefaultAction — デフォルトのアクション名を変更する
  • Yaf_Dispatcher::setDefaultController — デフォルトのコントローラ名を変更する
  • Yaf_Dispatcher::setDefaultModule — デフォルトのモジュール名を変更する
  • Yaf_Dispatcher::setErrorHandler — エラーハンドラを設定する
  • Yaf_Dispatcher::setRequest — The setRequest purpose
  • Yaf_Dispatcher::setView — カスタムビューエンジンを設定する
  • Yaf_Dispatcher::throwException — 例外のスローのオン/オフを切り替える


自動レンダリングのオン/オフを切り替える

  • ≪ Yaf_Dispatcher
  • Yaf_Dispatcher::catchException ≫
  • PHP Manual
  • Yaf_Dispatcher
  • 自動レンダリングのオン/オフを切り替える

Yaf_Dispatcher::autoRender

(Yaf >=1.0.0)

Yaf_Dispatcher::autoRender — 自動レンダリングのオン/オフを切り替える

説明

public Yaf_Dispatcher::autoRender(bool $flag = ?): Yaf_Dispatcher

Yaf_Dispatcher は リクエストをディスパッチした後で自動的にレンダリングします。 これを無効にするには、 flag を true としてこのメソッドを実行します。

注意:

アクションで false を返せば、そのアクションでの自動レンダリングを回避できます。

パラメータ

flag

bool

注意:

2.2.0 以降は、このパラメータを省略した場合に現在の状態を返すようになりました。

戻り値

例

例1 Yaf_Dispatcher::autoRender() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
/* init メソッドは、コントローラを初期化したときに呼ばれます */
public function init() {
if ($this->getRequest()->isXmlHttpRequest()) {
// ajax リクエストの場合はレンダリングせず、
// json 文字列を出力します
Yaf_Dispatcher::getInstance()->autoRender(FALSE);
}
}

}
?>

上の例の出力は、 たとえば以下のようになります。


例外のキャッチのオン/オフを切り替える

  • ≪ Yaf_Dispatcher::autoRender
  • Yaf_Dispatcher::__construct ≫
  • PHP Manual
  • Yaf_Dispatcher
  • 例外のキャッチのオン/オフを切り替える

Yaf_Dispatcher::catchException

(Yaf >=1.0.0)

Yaf_Dispatcher::catchException — 例外のキャッチのオン/オフを切り替える

説明

public Yaf_Dispatcher::catchException(bool $flag = ?): Yaf_Dispatcher

application.dispatcher.throwException が On (あるいは Yaf_Dispatcher::throwException(TRUE)() で有効にした) 場合、Yaf でエラーが発生したときに例外をスローします。

そのとき、Yaf_Dispatcher::catchException() を有効にする (あるいは application.dispatcher.catchException で有効にする) と、 もし ErrorController::error を定義していれば キャッチしなかった例外はすべて ErrorController::error に送られます。

パラメータ

flag

bool

戻り値

例

例1 Yaf_Dispatcher::catchException() の例

/* 次のような ErrorController を定義しているものとします */
<?php
class ErrorController extends Yaf_Controller_Abstract {
/**
* Yaf_Request_Abstract::getException を呼んで
* 未処理の例外を取得します
*/
public function errorAction($exception) {
/* エラーが発生した */
switch ($exception->getCode()) {
case YAF_ERR_NOTFOUND_MODULE:
case YAF_ERR_NOTFOUND_CONTROLLER:
case YAF_ERR_NOTFOUND_ACTION:
case YAF_ERR_NOTFOUND_VIEW:
echo 404, ":", $exception->getMessage();
break;
default :
$message = $exception->getMessage();
echo 0, ":", $exception->getMessage();
break;
}
}
}
?>

上の例の出力は、 たとえば以下のようになります。

/* now if some error occur, assuming access a non-exists controller(or you can throw a exception yourself): */
404:Could not find controller script **/application/controllers/No-exists-controller.php

参考

  • Yaf_Dispatcher::throwException() - 例外のスローのオン/オフを切り替える
  • Yaf_Dispatcher::setErrorHandler() - エラーハンドラを設定する


Yaf_Dispatcher のコンストラクタ

  • ≪ Yaf_Dispatcher::catchException
  • Yaf_Dispatcher::disableView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Yaf_Dispatcher のコンストラクタ

Yaf_Dispatcher::__construct

(Yaf >=1.0.0)

Yaf_Dispatcher::__construct — Yaf_Dispatcher のコンストラクタ

説明

public Yaf_Dispatcher::__construct()

パラメータ

この関数にはパラメータはありません。

戻り値


ビューのレンダリングを無効にする

  • ≪ Yaf_Dispatcher::__construct
  • Yaf_Dispatcher::dispatch ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ビューのレンダリングを無効にする

Yaf_Dispatcher::disableView

(Yaf >=1.0.0)

Yaf_Dispatcher::disableView — ビューのレンダリングを無効にする

説明

public Yaf_Dispatcher::disableView(): bool

ビューエンジンを無効にします。ユーザーが自分自身で出力しているようなアプリケーションで利用します。

注意:

アクションで false を返せば、そのアクションでの自動レンダリングを回避できます。

パラメータ

この関数にはパラメータはありません。

戻り値


リクエストをディスパッチする

  • ≪ Yaf_Dispatcher::disableView
  • Yaf_Dispatcher::enableView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • リクエストをディスパッチする

Yaf_Dispatcher::dispatch

(Yaf >=1.0.0)

Yaf_Dispatcher::dispatch — リクエストをディスパッチする

説明

public Yaf_Dispatcher::dispatch(Yaf_Request_Abstract $request): Yaf_Response_Abstract

このメソッドが、 Yaf_Dispatcher の主要な作業をします。 リクエストオブジェクトを受け取ります。

ディスパッチ処理には、次の三段階があります。

  • ルーティング
  • ディスパッチ
  • レスポンス
ローディングが発生するのは一度だけで、 Yaf_Dispatcher::dispatch() が呼ばれたときの リクエストオブジェクトの値を使って行います。 ディスパッチはループ内で発生します。ひとつのリクエストで 複数のアクションをディスパッチすることもあれば、 コントローラやプラグイン (Yaf_Plugin_Abstract を参照ください) がリクエストオブジェクトをリセットしてアクションを追加することもあります。 すべてが終わると Yaf_Dispatcher がレスポンスを返します。

パラメータ

request

戻り値


ビューのレンダリングを有効にする

  • ≪ Yaf_Dispatcher::dispatch
  • Yaf_Dispatcher::flushInstantly ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ビューのレンダリングを有効にする

Yaf_Dispatcher::enableView

(Yaf >=1.0.0)

Yaf_Dispatcher::enableView — ビューのレンダリングを有効にする

説明

public Yaf_Dispatcher::enableView(): Yaf_Dispatcher

パラメータ

この関数にはパラメータはありません。

戻り値


その場でのフラッシュのオン/オフを切り替える

  • ≪ Yaf_Dispatcher::enableView
  • Yaf_Dispatcher::getApplication ≫
  • PHP Manual
  • Yaf_Dispatcher
  • その場でのフラッシュのオン/オフを切り替える

Yaf_Dispatcher::flushInstantly

(Yaf >=1.0.0)

Yaf_Dispatcher::flushInstantly — その場でのフラッシュのオン/オフを切り替える

説明

public Yaf_Dispatcher::flushInstantly(bool $flag = ?): Yaf_Dispatcher

パラメータ

flag

bool

注意:

2.2.0 以降は、このパラメータを省略した場合に現在の状態を返すようになりました。

戻り値


アプリケーションを取得する

  • ≪ Yaf_Dispatcher::flushInstantly
  • Yaf_Dispatcher::getDefaultAction ≫
  • PHP Manual
  • Yaf_Dispatcher
  • アプリケーションを取得する

Yaf_Dispatcher::getApplication

(Yaf >=1.0.0)

Yaf_Dispatcher::getApplication — アプリケーションを取得する

説明

public Yaf_Dispatcher::getApplication(): Yaf_Application

Yaf_Application のインスタンスを取得します。 Yaf_Application::app() と同じです。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Application::app() - アプリケーションのインスタンスを取得する


Retrive the default action name

  • ≪ Yaf_Dispatcher::getApplication
  • Yaf_Dispatcher::getDefaultController ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Retrive the default action name

Yaf_Dispatcher::getDefaultAction

(Yaf >=3.2.0)

Yaf_Dispatcher::getDefaultAction — Retrive the default action name

説明

public Yaf_Dispatcher::getDefaultAction(): string

get the default action name

パラメータ

この関数にはパラメータはありません。

戻り値

string, default action name, default is "index"


Retrive the default controller name

  • ≪ Yaf_Dispatcher::getDefaultAction
  • Yaf_Dispatcher::getDefaultModule ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Retrive the default controller name

Yaf_Dispatcher::getDefaultController

(Yaf >=3.2.0)

Yaf_Dispatcher::getDefaultController — Retrive the default controller name

説明

public Yaf_Dispatcher::getDefaultController(): string

get the default controller name

パラメータ

この関数にはパラメータはありません。

戻り値

string, default controller name, default is "Index"


Retrive the default module name

  • ≪ Yaf_Dispatcher::getDefaultController
  • Yaf_Dispatcher::getInstance ≫
  • PHP Manual
  • Yaf_Dispatcher
  • Retrive the default module name

Yaf_Dispatcher::getDefaultModule

(Yaf >=3.2.0)

Yaf_Dispatcher::getDefaultModule — Retrive the default module name

説明

public Yaf_Dispatcher::getDefaultModule(): string

get the default module name

パラメータ

この関数にはパラメータはありません。

戻り値

string, module name, default is "Index"


ディスパッチャのインスタンスを取得する

  • ≪ Yaf_Dispatcher::getDefaultModule
  • Yaf_Dispatcher::getRequest ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ディスパッチャのインスタンスを取得する

Yaf_Dispatcher::getInstance

(Yaf >=1.0.0)

Yaf_Dispatcher::getInstance — ディスパッチャのインスタンスを取得する

説明

public static Yaf_Dispatcher::getInstance(): Yaf_Dispatcher

パラメータ

この関数にはパラメータはありません。

戻り値


リクエストのインスタンスを取得する

  • ≪ Yaf_Dispatcher::getInstance
  • Yaf_Dispatcher::getRouter ≫
  • PHP Manual
  • Yaf_Dispatcher
  • リクエストのインスタンスを取得する

Yaf_Dispatcher::getRequest

(Yaf >=1.0.0)

Yaf_Dispatcher::getRequest — リクエストのインスタンスを取得する

説明

public Yaf_Dispatcher::getRequest(): Yaf_Request_Abstract

パラメータ

この関数にはパラメータはありません。

戻り値


ルーターのインスタンスを取得する

  • ≪ Yaf_Dispatcher::getRequest
  • Yaf_Dispatcher::initView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ルーターのインスタンスを取得する

Yaf_Dispatcher::getRouter

(Yaf >=1.0.0)

Yaf_Dispatcher::getRouter — ルーターのインスタンスを取得する

説明

public Yaf_Dispatcher::getRouter(): Yaf_Router

パラメータ

この関数にはパラメータはありません。

戻り値


ビューを初期化して返す

  • ≪ Yaf_Dispatcher::getRouter
  • Yaf_Dispatcher::registerPlugin ≫
  • PHP Manual
  • Yaf_Dispatcher
  • ビューを初期化して返す

Yaf_Dispatcher::initView

(Yaf >=1.0.0)

Yaf_Dispatcher::initView — ビューを初期化して返す

説明

public Yaf_Dispatcher::initView(string $templates_dir, array $options = ?): Yaf_View_Interface

パラメータ

templates_dir

options

戻り値


プラグインを登録する

  • ≪ Yaf_Dispatcher::initView
  • Yaf_Dispatcher::returnResponse ≫
  • PHP Manual
  • Yaf_Dispatcher
  • プラグインを登録する

Yaf_Dispatcher::registerPlugin

(Yaf >=1.0.0)

Yaf_Dispatcher::registerPlugin — プラグインを登録する

説明

public Yaf_Dispatcher::registerPlugin(Yaf_Plugin_Abstract $plugin): Yaf_Dispatcher

プラグイン (Yaf_Plugin_Abstract を参照) を登録します。ふつうは、プラグインの登録はブートストラップ (Yaf_Bootstrap_Abstract を参照) で行います。

パラメータ

plugin

戻り値

例

例1 Yaf_Dispatcher::registerPlugin() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract {
public function _initPlugin(Yaf_Dispatcher $dispatcher) {
/**
* Yaf assumes plugin scripts under [application.directory] . "/plugins"
* for this case, it will be:
* [application.directory] . "/plugins/" . "User" . [application.ext]
*/
$user = new UserPlugin();
$dispatcher->registerPlugin($user);
}
}
?>

参考

  • Yaf_Plugin_Abstract
  • Yaf_Bootstrap_Abstract


The returnResponse purpose

  • ≪ Yaf_Dispatcher::registerPlugin
  • Yaf_Dispatcher::setDefaultAction ≫
  • PHP Manual
  • Yaf_Dispatcher
  • The returnResponse purpose

Yaf_Dispatcher::returnResponse

(Yaf >=1.0.0)

Yaf_Dispatcher::returnResponse — The returnResponse purpose

説明

public Yaf_Dispatcher::returnResponse(bool $flag): Yaf_Dispatcher

パラメータ

flag

戻り値


デフォルトのアクション名を変更する

  • ≪ Yaf_Dispatcher::returnResponse
  • Yaf_Dispatcher::setDefaultController ≫
  • PHP Manual
  • Yaf_Dispatcher
  • デフォルトのアクション名を変更する

Yaf_Dispatcher::setDefaultAction

(Yaf >=1.0.0)

Yaf_Dispatcher::setDefaultAction — デフォルトのアクション名を変更する

説明

public Yaf_Dispatcher::setDefaultAction(string $action): Yaf_Dispatcher

パラメータ

action

戻り値


デフォルトのコントローラ名を変更する

  • ≪ Yaf_Dispatcher::setDefaultAction
  • Yaf_Dispatcher::setDefaultModule ≫
  • PHP Manual
  • Yaf_Dispatcher
  • デフォルトのコントローラ名を変更する

Yaf_Dispatcher::setDefaultController

(Yaf >=1.0.0)

Yaf_Dispatcher::setDefaultController — デフォルトのコントローラ名を変更する

説明

public Yaf_Dispatcher::setDefaultController(string $controller): Yaf_Dispatcher

パラメータ

controller

戻り値


デフォルトのモジュール名を変更する

  • ≪ Yaf_Dispatcher::setDefaultController
  • Yaf_Dispatcher::setErrorHandler ≫
  • PHP Manual
  • Yaf_Dispatcher
  • デフォルトのモジュール名を変更する

Yaf_Dispatcher::setDefaultModule

(Yaf >=1.0.0)

Yaf_Dispatcher::setDefaultModule — デフォルトのモジュール名を変更する

説明

public Yaf_Dispatcher::setDefaultModule(string $module): Yaf_Dispatcher

パラメータ

module

戻り値


エラーハンドラを設定する

  • ≪ Yaf_Dispatcher::setDefaultModule
  • Yaf_Dispatcher::setRequest ≫
  • PHP Manual
  • Yaf_Dispatcher
  • エラーハンドラを設定する

Yaf_Dispatcher::setErrorHandler

(Yaf >=1.0.0)

Yaf_Dispatcher::setErrorHandler — エラーハンドラを設定する

説明

public Yaf_Dispatcher::setErrorHandler(call $callback, int $error_types): Yaf_Dispatcher

Yaf のエラーハンドラを設定します。application.dispatcher.throwException がオフの場合は、予期せぬエラーが発生した場合に Yaf はキャッチ可能なエラーを発生させます。

従って、このエラーハンドラが呼ばれる一方でエラーも発生します。

パラメータ

callback

コールバック。

error_types

戻り値

参考

  • Yaf_Dispatcher::throwException() - 例外のスローのオン/オフを切り替える
  • Yaf_Application::getLastErrorNo() - 直近で発生したエラーのコードを取得する
  • Yaf_Application::getLastErrorMsg() - 直近で発生したエラーのメッセージを取得する


The setRequest purpose

  • ≪ Yaf_Dispatcher::setErrorHandler
  • Yaf_Dispatcher::setView ≫
  • PHP Manual
  • Yaf_Dispatcher
  • The setRequest purpose

Yaf_Dispatcher::setRequest

(Yaf >=1.0.0)

Yaf_Dispatcher::setRequest — The setRequest purpose

説明

public Yaf_Dispatcher::setRequest(Yaf_Request_Abstract $request): Yaf_Dispatcher

パラメータ

plugin

戻り値


カスタムビューエンジンを設定する

  • ≪ Yaf_Dispatcher::setRequest
  • Yaf_Dispatcher::throwException ≫
  • PHP Manual
  • Yaf_Dispatcher
  • カスタムビューエンジンを設定する

Yaf_Dispatcher::setView

(Yaf >=1.0.0)

Yaf_Dispatcher::setView — カスタムビューエンジンを設定する

説明

public Yaf_Dispatcher::setView(Yaf_View_Interface $view): Yaf_Dispatcher

このメソッドは、Yaf_View_Simple ではなくカスタムビューエンジンを使いたいときに利用します。

パラメータ

view

Yaf_View_Interface のインスタンス。

戻り値

例

例1 カスタムビューエンジンの例

<?php
require "/path/to/smarty/Smarty.class.php";

class Smarty_Adapter implements Yaf_View_Interface
{
/**
* Smarty オブジェクト
* @var Smarty
*/
public $_smarty;

/**
* コンストラクタ
*
* @param string $tmplPath
* @param array $extraParams
* @return void
*/
public function __construct($tmplPath = null, $extraParams = array()) {
$this->_smarty = new Smarty;

if (null !== $tmplPath) {
$this->setScriptPath($tmplPath);
}

foreach ($extraParams as $key => $value) {
$this->_smarty->$key = $value;
}
}

/**
* テンプレートへのパスを設定する
*
* @param string $path パスに設定するディレクトリ
* @return void
*/
public function setScriptPath($path)
{
if (is_readable($path)) {
$this->_smarty->template_dir = $path;
return;
}

throw new Exception('Invalid path provided');
}

/**
* 変数をテンプレートに代入する
*
* @param string $key 変数名
* @param mixed $val 変数の値
* @return void
*/
public function __set($key, $val)
{
$this->_smarty->assign($key, $val);
}

/**
* empty() と isset() による確認をできるようにする
*
* @param string $key
* @return boolean
*/
public function __isset($key)
{
return (null !== $this->_smarty->get_template_vars($key));
}

/**
* オブジェクトのプロパティを unset() できるようにする
*
* @param string $key
* @return void
*/
public function __unset($key)
{
$this->_smarty->clear_assign($key);
}

/**
* 変数をテンプレートに代入する
*
* 指定したキーに値を代入したり、
* key => value ペアの配列で一括代入したりできるようにします。
*
* @see __set()
* @param string|array $spec 代入方法に合わせて、キー あるいは key => value ペアの配列)
* @param mixed $value (オプション) 変数名を指定した場合に、ここで値を指定する
* @return void
*/
public function assign($spec, $value = null) {
if (is_array($spec)) {
$this->_smarty->assign($spec);
return;
}

$this->_smarty->assign($spec, $value);
}

/**
* 代入済みのすべての変数をクリアする
*
* {@link assign()} あるいはプロパティのオーバーロード
* ({@link __get()}/{@link __set()}) で Yaf_View に代入したすべての変数をクリアします
*
* @return void
*/
public function clearVars() {
$this->_smarty->clear_all_assign();
}

/**
* テンプレートを処理して出力を返す
*
* @param string $name 処理するテンプレート
* @return string 出力
*/
public function render($name, $value = NULL) {
return $this->_smarty->fetch($name);
}

public function display($name, $value = NULL) {
echo $this->_smarty->fetch($name);
}

}
?>

例2 Yaf_Dispatcher::setView() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract {

/**
* smarty 用の設定をしておきます
*
* smarty.left_delimiter = "{{"
* smarty.right_delimiter = "}}"
* smarty.template_dir = APPLICATION_PATH "/views/scripts/"
* smarty.compile_dir = APPLICATION_PATH "/views/templates_c/"
* smarty.cache_dir = APPLICATION_PATH "/views/templates_d/"
*
*/
public function _initConfig() {
$config = Yaf_Application::app()->getConfig();
Yaf_Registry::set("config", $config);
}

public function _initLocalName() {
/** Smarty_Adapter クラスをローカルライブラリディレクトリに配置します */
Yaf_Loader::getInstance()->registerLocalNamespace('Smarty');
}

public function _initSmarty(Yaf_Dispatcher $dispatcher) {
$smarty = new Smarty_Adapter(null, Yaf_Registry::get("config")->get("smarty"));
$dispatcher->setView($smarty);
/* これで、Smarty ビューエンジンが Yaf のデフォルトビューエンジンになりました */
}
}
?>

参考

  • Yaf_View_Interface
  • Yaf_View_Simple


例外のスローのオン/オフを切り替える

  • ≪ Yaf_Dispatcher::setView
  • Yaf_Config_Abstract ≫
  • PHP Manual
  • Yaf_Dispatcher
  • 例外のスローのオン/オフを切り替える

Yaf_Dispatcher::throwException

(Yaf >=1.0.0)

Yaf_Dispatcher::throwException — 例外のスローのオン/オフを切り替える

説明

public Yaf_Dispatcher::throwException(bool $flag = ?): Yaf_Dispatcher

予期せぬエラーが発生した場合に例外をスローするかどうかを切り替えます。 オンにすると、Yaf はキャッチ可能なエラーを発生させるのではなく例外をスローするようになります。

application.dispatcher.throwException を使って同じ設定をすることもできます。

パラメータ

flag

bool

戻り値

例

例1 Yaf_Dispatcher::throwexception() の例

<?php

$config = array(
'application' => array(
'directory' => dirname(__FILE__),
),
);
$app = new Yaf_Application($config);

$app->getDispatcher()->throwException(true);

try {
$app->run();
} catch (Yaf_Exception $e) {
var_dump($e->getMessage());
}
?>

上の例の出力は、 たとえば以下のようになります。

string(59) "Could not find controller script /tmp/controllers/Index.php"

例2 Yaf_Dispatcher::throwexception() の例

<?php

$config = array(
'application' => array(
'directory' => dirname(__FILE__),
),
);
$app = new Yaf_Application($config);

$app->getDispatcher()->throwException(false);

$app->run();
?>

上の例の出力は、 たとえば以下のようになります。

PHP Catchable fatal error:  Yaf_Application::run(): Could not find controller script /tmp/controllers/Index.php in /tmp/1.php on line 12

参考

  • Yaf_Dispatcher::catchException() - 例外のキャッチのオン/オフを切り替える
  • Yaf_Exception


Yaf_Config_Abstract クラス

(Yaf >=1.0.0)

はじめに

クラス概要

abstract class Yaf_Config_Abstract {
/* プロパティ */
protected $_config;
protected $_readonly;
/* メソッド */
abstract public get(string $name, mixed $value): mixed
abstract public readonly(): bool
abstract public set(): Yaf_Config_Abstract
abstract public toArray(): array
}

プロパティ

_config

_readonly

目次

  • Yaf_Config_Abstract::get — ゲッター
  • Yaf_Config_Abstract::readonly — 設定項目が読み込み専用かどうかを調べる
  • Yaf_Config_Abstract::set — セッター
  • Yaf_Config_Abstract::toArray — 配列に変換する


ゲッター

  • ≪ Yaf_Config_Abstract
  • Yaf_Config_Abstract::readonly ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • ゲッター

Yaf_Config_Abstract::get

(Yaf >=1.0.0)

Yaf_Config_Abstract::get — ゲッター

説明

abstract public Yaf_Config_Abstract::get(string $name, mixed $value): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


設定項目が読み込み専用かどうかを調べる

  • ≪ Yaf_Config_Abstract::get
  • Yaf_Config_Abstract::set ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • 設定項目が読み込み専用かどうかを調べる

Yaf_Config_Abstract::readonly

(Yaf >=1.0.0)

Yaf_Config_Abstract::readonly — 設定項目が読み込み専用かどうかを調べる

説明

abstract public Yaf_Config_Abstract::readonly(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


セッター

  • ≪ Yaf_Config_Abstract::readonly
  • Yaf_Config_Abstract::toArray ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • セッター

Yaf_Config_Abstract::set

(Yaf >=1.0.0)

Yaf_Config_Abstract::set — セッター

説明

abstract public Yaf_Config_Abstract::set(): Yaf_Config_Abstract

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


配列に変換する

  • ≪ Yaf_Config_Abstract::set
  • Yaf_Config_Ini ≫
  • PHP Manual
  • Yaf_Config_Abstract
  • 配列に変換する

Yaf_Config_Abstract::toArray

(Yaf >=1.0.0)

Yaf_Config_Abstract::toArray — 配列に変換する

説明

abstract public Yaf_Config_Abstract::toArray(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Config_Ini クラス

(Yaf >=1.0.0)

はじめに

Yaf_Config_Ini を使うと、設定データをおなじみの INI 形式で保存でき、アプリケーションからもオブジェクトのプロパティとして読めるようになります。 INI フォーマットを拡張して、設定データを階層構造で扱えるようにしたり 設定セクション間での継承を設定できるようにしたりしています。 設定データの階層は、キーをピリオド(".")で区切って表します。 セクションの継承を表すには、セクション名の後にコロン(":") を続け、その後に継承元のセクション名を指定します。

注意:

Yaf_Config_Ini は、PHP の関数 parse_ini_file() を利用します。 この関数のドキュメントも読んで、その振る舞いを知っておきましょう。 特殊な値、たとえば "true"、"false"、"yes"、"no"、そして "null" の扱いも、parse_ini_file() に従います。

クラス概要

class Yaf_Config_Ini extends Yaf_Config_Abstract implements Iterator, ArrayAccess, Countable {
/* プロパティ */
/* メソッド */
public __construct(string $config_file, string $section = ?)
public count(): void
public current(): void
public __get(string $name = ?): void
public __isset(string $name): void
public key(): void
public next(): void
public offsetExists(string $name): void
public offsetGet(string $name): void
public offsetSet(string $name, string $value): void
public offsetUnset(string $name): void
public readonly(): void
public rewind(): void
public __set(string $name, mixed $value): void
public toArray(): array
public valid(): void
/* 継承したメソッド */
abstract public Yaf_Config_Abstract::get(string $name, mixed $value): mixed
abstract public Yaf_Config_Abstract::readonly(): bool
abstract public Yaf_Config_Abstract::set(): Yaf_Config_Abstract
abstract public Yaf_Config_Abstract::toArray(): array
}

プロパティ

_config

_readonly

例

例1 Yaf_Config_Ini() の例

この例は、Yaf_Config_Ini で INI ファイルから設定データを読む方法を示すものです。 この例では、運用環境とステージング環境の設定データを用意しています。 ステージング環境の設定は運用環境とほぼ同じなので、 staging セクションは production セクションを継承しています。 今回の場合はどちらがどちらを継承してもあまり変わらないので 逆に production セクションが staging セクションを継承するようにもできます。 しかし、もっと複雑な設定になるとそうはいかないでしょう。 次のような設定データが /path/to/config.ini に格納されているものとします。

; Production site configuration data
[production]
webhost                  = www.example.com
database.adapter         = pdo_mysql
database.params.host     = db.example.com
database.params.username = dbuser
database.params.password = secret
database.params.dbname   = dbname

; Staging site configuration data inherits from production and
; overrides values as necessary
[staging : production]
database.params.host     = dev.example.com
database.params.username = devuser
database.params.password = devsecret
<?php
$config = new Yaf_Config_Ini('/path/to/config.ini', 'staging');

var_dump($config->database->params->host);
var_dump($config->database->params->dbname);
var_dump($config->get("database.params.username"));
?>

上の例の出力は、 たとえば以下のようになります。

string(15) "dev.example.com"
string(6) "dbname"
string(7) "devuser

目次

  • Yaf_Config_Ini::__construct — Yaf_Config_Ini のコンストラクタ
  • Yaf_Config_Ini::count — Yaf_Config.ini の全ての要素を数える
  • Yaf_Config_Ini::current — 現在の値を取得する
  • Yaf_Config_Ini::__get — 要素を取得する
  • Yaf_Config_Ini::__isset — キーが存在するかを判定する
  • Yaf_Config_Ini::key — 現在の要素のキーを取得する
  • Yaf_Config_Ini::next — 内部ポインタを進める
  • Yaf_Config_Ini::offsetExists — The offsetExists purpose
  • Yaf_Config_Ini::offsetGet — The offsetGet purpose
  • Yaf_Config_Ini::offsetSet — The offsetSet purpose
  • Yaf_Config_Ini::offsetUnset — The offsetUnset purpose
  • Yaf_Config_Ini::readonly — The readonly purpose
  • Yaf_Config_Ini::rewind — The rewind purpose
  • Yaf_Config_Ini::__set — The __set purpose
  • Yaf_Config_Ini::toArray — PHP の配列として構成を返す
  • Yaf_Config_Ini::valid — The valid purpose


Yaf_Config_Ini のコンストラクタ

  • ≪ Yaf_Config_Ini
  • Yaf_Config_Ini::count ≫
  • PHP Manual
  • Yaf_Config_Ini
  • Yaf_Config_Ini のコンストラクタ

Yaf_Config_Ini::__construct

(Yaf >=1.0.0)

Yaf_Config_Ini::__construct — Yaf_Config_Ini のコンストラクタ

説明

public Yaf_Config_Ini::__construct(string $config_file, string $section = ?)

Yaf_Config_Ini のコンストラクタです。

パラメータ

config_file

INI ファイルへのパス。

section

INI ファイルの中でパースしたいセクション。

戻り値


Yaf_Config.ini の全ての要素を数える

  • ≪ Yaf_Config_Ini::__construct
  • Yaf_Config_Ini::current ≫
  • PHP Manual
  • Yaf_Config_Ini
  • Yaf_Config.ini の全ての要素を数える

Yaf_Config_Ini::count

(Yaf >=1.0.0)

Yaf_Config_Ini::count — Yaf_Config.ini の全ての要素を数える

説明

public Yaf_Config_Ini::count(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


現在の値を取得する

  • ≪ Yaf_Config_Ini::count
  • Yaf_Config_Ini::__get ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 現在の値を取得する

Yaf_Config_Ini::current

(Yaf >=1.0.0)

Yaf_Config_Ini::current — 現在の値を取得する

説明

public Yaf_Config_Ini::current(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


要素を取得する

  • ≪ Yaf_Config_Ini::current
  • Yaf_Config_Ini::__isset ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 要素を取得する

Yaf_Config_Ini::__get

(Yaf >=1.0.0)

Yaf_Config_Ini::__get — 要素を取得する

説明

public Yaf_Config_Ini::__get(string $name = ?): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


キーが存在するかを判定する

  • ≪ Yaf_Config_Ini::__get
  • Yaf_Config_Ini::key ≫
  • PHP Manual
  • Yaf_Config_Ini
  • キーが存在するかを判定する

Yaf_Config_Ini::__isset

(Yaf >=1.0.0)

Yaf_Config_Ini::__isset — キーが存在するかを判定する

説明

public Yaf_Config_Ini::__isset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


現在の要素のキーを取得する

  • ≪ Yaf_Config_Ini::__isset
  • Yaf_Config_Ini::next ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 現在の要素のキーを取得する

Yaf_Config_Ini::key

(Yaf >=1.0.0)

Yaf_Config_Ini::key — 現在の要素のキーを取得する

説明

public Yaf_Config_Ini::key(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


内部ポインタを進める

  • ≪ Yaf_Config_Ini::key
  • Yaf_Config_Ini::offsetExists ≫
  • PHP Manual
  • Yaf_Config_Ini
  • 内部ポインタを進める

Yaf_Config_Ini::next

(Yaf >=1.0.0)

Yaf_Config_Ini::next — 内部ポインタを進める

説明

public Yaf_Config_Ini::next(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The offsetExists purpose

  • ≪ Yaf_Config_Ini::next
  • Yaf_Config_Ini::offsetGet ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetExists purpose

Yaf_Config_Ini::offsetExists

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetExists — The offsetExists purpose

説明

public Yaf_Config_Ini::offsetExists(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The offsetGet purpose

  • ≪ Yaf_Config_Ini::offsetExists
  • Yaf_Config_Ini::offsetSet ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetGet purpose

Yaf_Config_Ini::offsetGet

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetGet — The offsetGet purpose

説明

public Yaf_Config_Ini::offsetGet(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The offsetSet purpose

  • ≪ Yaf_Config_Ini::offsetGet
  • Yaf_Config_Ini::offsetUnset ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetSet purpose

Yaf_Config_Ini::offsetSet

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetSet — The offsetSet purpose

説明

public Yaf_Config_Ini::offsetSet(string $name, string $value): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


The offsetUnset purpose

  • ≪ Yaf_Config_Ini::offsetSet
  • Yaf_Config_Ini::readonly ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The offsetUnset purpose

Yaf_Config_Ini::offsetUnset

(Yaf >=1.0.0)

Yaf_Config_Ini::offsetUnset — The offsetUnset purpose

説明

public Yaf_Config_Ini::offsetUnset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The readonly purpose

  • ≪ Yaf_Config_Ini::offsetUnset
  • Yaf_Config_Ini::rewind ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The readonly purpose

Yaf_Config_Ini::readonly

(Yaf >=1.0.0)

Yaf_Config_Ini::readonly — The readonly purpose

説明

public Yaf_Config_Ini::readonly(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The rewind purpose

  • ≪ Yaf_Config_Ini::readonly
  • Yaf_Config_Ini::__set ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The rewind purpose

Yaf_Config_Ini::rewind

(Yaf >=1.0.0)

Yaf_Config_Ini::rewind — The rewind purpose

説明

public Yaf_Config_Ini::rewind(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __set purpose

  • ≪ Yaf_Config_Ini::rewind
  • Yaf_Config_Ini::toArray ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The __set purpose

Yaf_Config_Ini::__set

(Yaf >=1.0.0)

Yaf_Config_Ini::__set — The __set purpose

説明

public Yaf_Config_Ini::__set(string $name, mixed $value): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


PHP の配列として構成を返す

  • ≪ Yaf_Config_Ini::__set
  • Yaf_Config_Ini::valid ≫
  • PHP Manual
  • Yaf_Config_Ini
  • PHP の配列として構成を返す

Yaf_Config_Ini::toArray

(Yaf >=1.0.0)

Yaf_Config_Ini::toArray — PHP の配列として構成を返す

説明

public Yaf_Config_Ini::toArray(): array

Yaf_Config_Ini から PHP の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値


The valid purpose

  • ≪ Yaf_Config_Ini::toArray
  • Yaf_Config_Simple ≫
  • PHP Manual
  • Yaf_Config_Ini
  • The valid purpose

Yaf_Config_Ini::valid

(Yaf >=1.0.0)

Yaf_Config_Ini::valid — The valid purpose

説明

public Yaf_Config_Ini::valid(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Config_Simple クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Config_Simple extends Yaf_Config_Abstract implements Iterator, ArrayAccess, Countable {
/* プロパティ */
protected $_readonly;
/* メソッド */
public __construct(array $configs, bool $readonly = false)
public count(): void
public current(): void
public __get(string $name = ?): void
public __isset(string $name): void
public key(): void
public next(): void
public offsetExists(string $name): void
public offsetGet(string $name): void
public offsetSet(string $name, string $value): void
public offsetUnset(string $name): void
public readonly(): void
public rewind(): void
public __set(string $name, string $value): void
public toArray(): array
public valid(): void
/* 継承したメソッド */
abstract public Yaf_Config_Abstract::get(string $name, mixed $value): mixed
abstract public Yaf_Config_Abstract::readonly(): bool
abstract public Yaf_Config_Abstract::set(): Yaf_Config_Abstract
abstract public Yaf_Config_Abstract::toArray(): array
}

プロパティ

_config

_readonly

目次

  • Yaf_Config_Simple::__construct — コンストラクタ
  • Yaf_Config_Simple::count — The count purpose
  • Yaf_Config_Simple::current — The current purpose
  • Yaf_Config_Simple::__get — The __get purpose
  • Yaf_Config_Simple::__isset — The __isset purpose
  • Yaf_Config_Simple::key — The key purpose
  • Yaf_Config_Simple::next — The next purpose
  • Yaf_Config_Simple::offsetExists — The offsetExists purpose
  • Yaf_Config_Simple::offsetGet — The offsetGet purpose
  • Yaf_Config_Simple::offsetSet — The offsetSet purpose
  • Yaf_Config_Simple::offsetUnset — The offsetUnset purpose
  • Yaf_Config_Simple::readonly — The readonly purpose
  • Yaf_Config_Simple::rewind — The rewind purpose
  • Yaf_Config_Simple::__set — The __set purpose
  • Yaf_Config_Simple::toArray — PHP の配列を返す
  • Yaf_Config_Simple::valid — The valid purpose


コンストラクタ

  • ≪ Yaf_Config_Simple
  • Yaf_Config_Simple::count ≫
  • PHP Manual
  • Yaf_Config_Simple
  • コンストラクタ

Yaf_Config_Simple::__construct

(Yaf >=1.0.0)

Yaf_Config_Simple::__construct — コンストラクタ

説明

public Yaf_Config_Simple::__construct(array $configs, bool $readonly = false)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

configs

readonly

戻り値


The count purpose

  • ≪ Yaf_Config_Simple::__construct
  • Yaf_Config_Simple::current ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The count purpose

Yaf_Config_Simple::count

(Yaf >=1.0.0)

Yaf_Config_Simple::count — The count purpose

説明

public Yaf_Config_Simple::count(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The current purpose

  • ≪ Yaf_Config_Simple::count
  • Yaf_Config_Simple::__get ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The current purpose

Yaf_Config_Simple::current

(Yaf >=1.0.0)

Yaf_Config_Simple::current — The current purpose

説明

public Yaf_Config_Simple::current(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __get purpose

  • ≪ Yaf_Config_Simple::current
  • Yaf_Config_Simple::__isset ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The __get purpose

Yaf_Config_Simple::__get

(Yaf >=1.0.0)

Yaf_Config_Simple::__get — The __get purpose

説明

public Yaf_Config_Simple::__get(string $name = ?): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The __isset purpose

  • ≪ Yaf_Config_Simple::__get
  • Yaf_Config_Simple::key ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The __isset purpose

Yaf_Config_Simple::__isset

(Yaf >=1.0.0)

Yaf_Config_Simple::__isset — The __isset purpose

説明

public Yaf_Config_Simple::__isset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The key purpose

  • ≪ Yaf_Config_Simple::__isset
  • Yaf_Config_Simple::next ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The key purpose

Yaf_Config_Simple::key

(Yaf >=1.0.0)

Yaf_Config_Simple::key — The key purpose

説明

public Yaf_Config_Simple::key(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The next purpose

  • ≪ Yaf_Config_Simple::key
  • Yaf_Config_Simple::offsetExists ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The next purpose

Yaf_Config_Simple::next

(Yaf >=1.0.0)

Yaf_Config_Simple::next — The next purpose

説明

public Yaf_Config_Simple::next(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The offsetExists purpose

  • ≪ Yaf_Config_Simple::next
  • Yaf_Config_Simple::offsetGet ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetExists purpose

Yaf_Config_Simple::offsetExists

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetExists — The offsetExists purpose

説明

public Yaf_Config_Simple::offsetExists(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The offsetGet purpose

  • ≪ Yaf_Config_Simple::offsetExists
  • Yaf_Config_Simple::offsetSet ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetGet purpose

Yaf_Config_Simple::offsetGet

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetGet — The offsetGet purpose

説明

public Yaf_Config_Simple::offsetGet(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The offsetSet purpose

  • ≪ Yaf_Config_Simple::offsetGet
  • Yaf_Config_Simple::offsetUnset ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetSet purpose

Yaf_Config_Simple::offsetSet

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetSet — The offsetSet purpose

説明

public Yaf_Config_Simple::offsetSet(string $name, string $value): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


The offsetUnset purpose

  • ≪ Yaf_Config_Simple::offsetSet
  • Yaf_Config_Simple::readonly ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The offsetUnset purpose

Yaf_Config_Simple::offsetUnset

(Yaf >=1.0.0)

Yaf_Config_Simple::offsetUnset — The offsetUnset purpose

説明

public Yaf_Config_Simple::offsetUnset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The readonly purpose

  • ≪ Yaf_Config_Simple::offsetUnset
  • Yaf_Config_Simple::rewind ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The readonly purpose

Yaf_Config_Simple::readonly

(Yaf >=1.0.0)

Yaf_Config_Simple::readonly — The readonly purpose

説明

public Yaf_Config_Simple::readonly(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The rewind purpose

  • ≪ Yaf_Config_Simple::readonly
  • Yaf_Config_Simple::__set ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The rewind purpose

Yaf_Config_Simple::rewind

(Yaf >=1.0.0)

Yaf_Config_Simple::rewind — The rewind purpose

説明

public Yaf_Config_Simple::rewind(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __set purpose

  • ≪ Yaf_Config_Simple::rewind
  • Yaf_Config_Simple::toArray ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The __set purpose

Yaf_Config_Simple::__set

(Yaf >=1.0.0)

Yaf_Config_Simple::__set — The __set purpose

説明

public Yaf_Config_Simple::__set(string $name, string $value): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


PHP の配列を返す

  • ≪ Yaf_Config_Simple::__set
  • Yaf_Config_Simple::valid ≫
  • PHP Manual
  • Yaf_Config_Simple
  • PHP の配列を返す

Yaf_Config_Simple::toArray

(Yaf >=1.0.0)

Yaf_Config_Simple::toArray — PHP の配列を返す

説明

public Yaf_Config_Simple::toArray(): array

Yaf_Config_Simple から PHP の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値


The valid purpose

  • ≪ Yaf_Config_Simple::toArray
  • Yaf_Controller_Abstract ≫
  • PHP Manual
  • Yaf_Config_Simple
  • The valid purpose

Yaf_Config_Simple::valid

(Yaf >=1.0.0)

Yaf_Config_Simple::valid — The valid purpose

説明

public Yaf_Config_Simple::valid(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Controller_Abstract クラス

(Yaf >=1.0.0)

はじめに

Yaf_Controller_Abstract は Yaf システムの中心となるクラスです。 MVC は Model-View-Controller の略で、 アプリケーションのロジックと表示のロジックを切り離すためのデザインパターンです。

すべてのカスタムコントローラは Yaf_Controller_Abstract を継承する必要があります。

カスタムコントローラでは __construct を定義できません。そのため、 Yaf_Controller_Abstract ではマジックメソッド Yaf_Controller_Abstract::init() を用意しています。

カスタムコントローラで init() メソッドを定義すると、 コントローラのインスタンスを作成するときにそれが呼ばれます。

アクションには引数を持たせることができます。 リクエストが来たときに、もしリクエストのパラメータ (Yaf_Request_Abstract::getParam() を参照ください) に同名の変数があれば、Yaf はアクションのメソッド (Yaf_Action_Abstract::execute() を参照ください) にそれを渡します。

注意:

これらの引数は何もフィルタリングせずそのまま取り込まれるので、 実際に使う前には注意しないといけません。

クラス概要

abstract class Yaf_Controller_Abstract {
/* プロパティ */
public $actions;
protected $_module;
protected $_name;
protected $_request;
protected $_response;
protected $_invoke_args;
protected $_view;
/* メソッド */
final private __construct()
protected display(string $tpl, array $parameters = ?): bool
public forward(string $action, array $paramters = ?): bool
public getInvokeArg(string $name): void
public getInvokeArgs(): void
public getModuleName(): string
public getName(): string
public getRequest(): Yaf_Request_Abstract
public getResponse(): Yaf_Response_Abstract
public getView(): Yaf_View_Interface
public getViewpath(): string
public init(): void
public initView(array $options = ?): void
public redirect(string $url): bool
protected render(string $tpl, array $parameters = ?): string
public setViewpath(string $view_directory): void
}

プロパティ

actions

アクションメソッドを個別の PHP スクリプトとして定義することもできます。 そのときには、このプロパティと Yaf_Action_Abstract を利用します。

例1 別ファイルでのアクションの定義

<?php
class IndexController extends Yaf_Controller_Abstract {
protected $actions = array(
/** now dummyAction is defined in a separate file */
"dummy" => "actions/Dummy_action.php",
);

/* action method may have arguments */
public function indexAction($name, $id) {
/* $name and $id are unsafe raw data */
assert($name == $this->getRequest()->getParam("name"));
assert($id == $this->_request->getParam("id"));
}
}
?>

例2 Dummy_action.php

<?php
class DummyAction extends Yaf_Action_Abstract {
/* an action class shall define this method as the entry point */
public function execute() {
}
}
?>

_module

モジュール名

_name

コントローラ名

_request

現在のリクエストオブジェクト

_response

現在のレスポンスオブジェクト

_invoke_args

_view

ビューエンジンオブジェクト

目次

  • Yaf_Controller_Abstract::__construct — Yaf_Controller_Abstract のコンストラクタ
  • Yaf_Controller_Abstract::display — The display purpose
  • Yaf_Controller_Abstract::forward — 別のアクションに転送する
  • Yaf_Controller_Abstract::getInvokeArg — The getInvokeArg purpose
  • Yaf_Controller_Abstract::getInvokeArgs — The getInvokeArgs purpose
  • Yaf_Controller_Abstract::getModuleName — モジュール名を取得する
  • Yaf_Controller_Abstract::getName — Get self name
  • Yaf_Controller_Abstract::getRequest — 現在のリクエストオブジェクトを取得する
  • Yaf_Controller_Abstract::getResponse — 現在のレスポンスオブジェクトを取得する
  • Yaf_Controller_Abstract::getView — ビューエンジンを取得する
  • Yaf_Controller_Abstract::getViewpath — getViewpath の目的を書く
  • Yaf_Controller_Abstract::init — コントローラを初期化する
  • Yaf_Controller_Abstract::initView — The initView purpose
  • Yaf_Controller_Abstract::redirect — URL にリダイレクトする
  • Yaf_Controller_Abstract::render — ビューテンプレートをレンダリングする
  • Yaf_Controller_Abstract::setViewpath — The setViewpath purpose


Yaf_Controller_Abstract のコンストラクタ

  • ≪ Yaf_Controller_Abstract
  • Yaf_Controller_Abstract::display ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • Yaf_Controller_Abstract のコンストラクタ

Yaf_Controller_Abstract::__construct

(Yaf >=1.0.0)

Yaf_Controller_Abstract::__construct — Yaf_Controller_Abstract のコンストラクタ

説明

final private Yaf_Controller_Abstract::__construct()

Yaf_Controller_Abstract::__construct() は final メソッドなので、 オーバーライドできません。 Yaf_Controller_Abstract::init() を参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Controller_Abstract::init() - コントローラを初期化する


The display purpose

  • ≪ Yaf_Controller_Abstract::__construct
  • Yaf_Controller_Abstract::forward ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The display purpose

Yaf_Controller_Abstract::display

(Yaf >=1.0.0)

Yaf_Controller_Abstract::display — The display purpose

説明

protected Yaf_Controller_Abstract::display(string $tpl, array $parameters = ?): bool

パラメータ

tpl

parameters

戻り値


別のアクションに転送する

  • ≪ Yaf_Controller_Abstract::display
  • Yaf_Controller_Abstract::getInvokeArg ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • 別のアクションに転送する

Yaf_Controller_Abstract::forward

(Yaf >=1.0.0)

Yaf_Controller_Abstract::forward — 別のアクションに転送する

説明

public Yaf_Controller_Abstract::forward(string $action, array $paramters = ?): bool
public Yaf_Controller_Abstract::forward(string $controller, string $action, array $paramters = ?): bool
public Yaf_Controller_Abstract::forward(
string $module,
string $controller,
string $action,
array $paramters = ?
): bool

現在の実行プロセスを別のアクションに転送します。

注意:

このメソッドは、その場ですぐに次のアクションに切り替えるわけではなく、 現在の実行フローが終わってから次のアクションに転送します。

パラメータ

module

移動先のモジュール名。NULL を渡した場合はデフォルトのモジュール名と見なします。

controller

移動先のコントローラ名。

action

移動先のアクション名。

paramters

呼び出しの引数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Yaf_Controller_Abstract::forward() の例

<?php
class IndexController extends Yaf_Controller_Abstract
{
public function indexAction(){
$logined = $_SESSION["login"];
if (!$logined) {
$this->forward("login", array("from" => "Index")); // login アクションに転送します
return FALSE; // これが重要です。ここで現在の作業フローが終了し、
// Yaf に対して自動レンダリングをしないよう指示します。
}

// 別の処理
}

public function loginAction() {
echo "login, redirected from ", $this->_request->getParam("from") , " action";
}
}
?>

上の例の出力は、 たとえば以下のようになります。

login, redirected from Index action

参考

  • Yaf_Request_Abstrace::getParam()


The getInvokeArg purpose

  • ≪ Yaf_Controller_Abstract::forward
  • Yaf_Controller_Abstract::getInvokeArgs ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The getInvokeArg purpose

Yaf_Controller_Abstract::getInvokeArg

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getInvokeArg — The getInvokeArg purpose

説明

public Yaf_Controller_Abstract::getInvokeArg(string $name): void

パラメータ

name

戻り値


The getInvokeArgs purpose

  • ≪ Yaf_Controller_Abstract::getInvokeArg
  • Yaf_Controller_Abstract::getModuleName ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The getInvokeArgs purpose

Yaf_Controller_Abstract::getInvokeArgs

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getInvokeArgs — The getInvokeArgs purpose

説明

public Yaf_Controller_Abstract::getInvokeArgs(): void

パラメータ

この関数にはパラメータはありません。

戻り値


モジュール名を取得する

  • ≪ Yaf_Controller_Abstract::getInvokeArgs
  • Yaf_Controller_Abstract::getName ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • モジュール名を取得する

Yaf_Controller_Abstract::getModuleName

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getModuleName — モジュール名を取得する

説明

public Yaf_Controller_Abstract::getModuleName(): string

コントローラのモジュール名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値


Get self name

  • ≪ Yaf_Controller_Abstract::getModuleName
  • Yaf_Controller_Abstract::getRequest ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • Get self name

Yaf_Controller_Abstract::getName

(Yaf >=3.2.0)

Yaf_Controller_Abstract::getName — Get self name

説明

public Yaf_Controller_Abstract::getName(): string

get the controller's name

パラメータ

この関数にはパラメータはありません。

戻り値

string, controller name


現在のリクエストオブジェクトを取得する

  • ≪ Yaf_Controller_Abstract::getName
  • Yaf_Controller_Abstract::getResponse ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • 現在のリクエストオブジェクトを取得する

Yaf_Controller_Abstract::getRequest

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getRequest — 現在のリクエストオブジェクトを取得する

説明

public Yaf_Controller_Abstract::getRequest(): Yaf_Request_Abstract

現在のリクエストオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Yaf_Request_Abstract instance


現在のレスポンスオブジェクトを取得する

  • ≪ Yaf_Controller_Abstract::getRequest
  • Yaf_Controller_Abstract::getView ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • 現在のレスポンスオブジェクトを取得する

Yaf_Controller_Abstract::getResponse

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getResponse — 現在のレスポンスオブジェクトを取得する

説明

public Yaf_Controller_Abstract::getResponse(): Yaf_Response_Abstract

現在のレスポンスオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Yaf_Response_Abstract instance


ビューエンジンを取得する

  • ≪ Yaf_Controller_Abstract::getResponse
  • Yaf_Controller_Abstract::getViewpath ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • ビューエンジンを取得する

Yaf_Controller_Abstract::getView

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getView — ビューエンジンを取得する

説明

public Yaf_Controller_Abstract::getView(): Yaf_View_Interface

ビューエンジンを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値


getViewpath の目的を書く

  • ≪ Yaf_Controller_Abstract::getView
  • Yaf_Controller_Abstract::init ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • getViewpath の目的を書く

Yaf_Controller_Abstract::getViewpath

(Yaf >=1.0.0)

Yaf_Controller_Abstract::getViewpath — getViewpath の目的を書く

説明

public Yaf_Controller_Abstract::getViewpath(): string

パラメータ

この関数にはパラメータはありません。

戻り値


コントローラを初期化する

  • ≪ Yaf_Controller_Abstract::getViewpath
  • Yaf_Controller_Abstract::initView ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • コントローラを初期化する

Yaf_Controller_Abstract::init

(Yaf >=1.0.0)

Yaf_Controller_Abstract::init — コントローラを初期化する

説明

public Yaf_Controller_Abstract::init(): void

Yaf_Controller_Abstract::__construct() は final メソッドなので、 オーバーライドできません。しかし、かわりに Yaf_Controller_Abstract::init() を定義できます。 これは、コントローラオブジェクトのインスタンスができた直後に呼ばれます。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Controller_Abstract::__construct() - Yaf_Controller_Abstract のコンストラクタ


The initView purpose

  • ≪ Yaf_Controller_Abstract::init
  • Yaf_Controller_Abstract::redirect ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The initView purpose

Yaf_Controller_Abstract::initView

(Yaf >=1.0.0)

Yaf_Controller_Abstract::initView — The initView purpose

説明

public Yaf_Controller_Abstract::initView(array $options = ?): void

パラメータ

options

戻り値


URL にリダイレクトする

  • ≪ Yaf_Controller_Abstract::initView
  • Yaf_Controller_Abstract::render ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • URL にリダイレクトする

Yaf_Controller_Abstract::redirect

(Yaf >=1.0.0)

Yaf_Controller_Abstract::redirect — URL にリダイレクトする

説明

public Yaf_Controller_Abstract::redirect(string $url): bool

302 ヘッダを送出して、URL にリダイレクトします。

パラメータ

url

場所を表す URL。

戻り値

bool


ビューテンプレートをレンダリングする

  • ≪ Yaf_Controller_Abstract::redirect
  • Yaf_Controller_Abstract::setViewpath ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • ビューテンプレートをレンダリングする

Yaf_Controller_Abstract::render

(Yaf >=1.0.0)

Yaf_Controller_Abstract::render — ビューテンプレートをレンダリングする

説明

protected Yaf_Controller_Abstract::render(string $tpl, array $parameters = ?): string

パラメータ

tpl

parameters

戻り値


The setViewpath purpose

  • ≪ Yaf_Controller_Abstract::render
  • Yaf_Action_Abstract ≫
  • PHP Manual
  • Yaf_Controller_Abstract
  • The setViewpath purpose

Yaf_Controller_Abstract::setViewpath

(Yaf >=1.0.0)

Yaf_Controller_Abstract::setViewpath — The setViewpath purpose

説明

public Yaf_Controller_Abstract::setViewpath(string $view_directory): void

パラメータ

view_directory

戻り値


Yaf_Action_Abstract クラス

(Yaf >=1.0.0)

はじめに

アクションは、Yaf の個別のファイルで定義します (Yaf_Controller_Abstract を参照ください)。 アクションメソッドには Yaf_Action_Abstract クラスも使えます。

Yaf から呼び出すためのエントリポイントが必要なので、 抽象メソッド Yaf_Action_Abstract::execute() をアクションクラスで実装する必要があります。

クラス概要

class Yaf_Action_Abstract extends Yaf_Controller_Abstract {
/* プロパティ */
protected $_controller;
/* メソッド */
abstract publicexecute(mixed ...$args): mixed
publicgetController(): Yaf_Controller_Abstract
public getControllerName(): string
/* 継承したメソッド */
protected Yaf_Controller_Abstract::display(string $tpl, array $parameters = ?): bool
public Yaf_Controller_Abstract::forward(string $action, array $paramters = ?): bool
public Yaf_Controller_Abstract::getInvokeArg(string $name): void
public Yaf_Controller_Abstract::getInvokeArgs(): void
public Yaf_Controller_Abstract::getModuleName(): string
public Yaf_Controller_Abstract::getName(): string
public Yaf_Controller_Abstract::getRequest(): Yaf_Request_Abstract
public Yaf_Controller_Abstract::getResponse(): Yaf_Response_Abstract
public Yaf_Controller_Abstract::getView(): Yaf_View_Interface
public Yaf_Controller_Abstract::getViewpath(): string
public Yaf_Controller_Abstract::init(): void
public Yaf_Controller_Abstract::initView(array $options = ?): void
public Yaf_Controller_Abstract::redirect(string $url): bool
protected Yaf_Controller_Abstract::render(string $tpl, array $parameters = ?): string
public Yaf_Controller_Abstract::setViewpath(string $view_directory): void
}

プロパティ

_module

_name

_request

_response

_invoke_args

_view

_controller

目次

  • Yaf_Action_Abstract::execute — アクションのエントリポイント
  • Yaf_Action_Abstract::getController — コントローラオブジェクトを取得する
  • Yaf_Action_Abstract::getControllerName — Get controller name


アクションのエントリポイント

  • ≪ Yaf_Action_Abstract
  • Yaf_Action_Abstract::getController ≫
  • PHP Manual
  • Yaf_Action_Abstract
  • アクションのエントリポイント

Yaf_Action_Abstract::execute

(Yaf >=1.0.0)

Yaf_Action_Abstract::execute — アクションのエントリポイント

説明

abstract publicYaf_Action_Abstract::execute(mixed ...$args): mixed

このメソッドは、アクションで常に定義しないといけません。これがアクションのエントリポイントになります。 Yaf_Action_Abstract::execute() は引数をとることもあります。

注意:

リクエストから取得した値は安全ではありません。 使う前にフィルタリングが必要です。

パラメータ

args

戻り値

例

例1 Yaf_Action_Abstract::execute() の例

<?php
/**
* A controller example
*/
class ProductController extends Yaf_Controller_Abstract {
protected $actions = array(
"index" => "actions/Index.php",
);
}
?>

例2 Yaf_Action_Abstract::execute() の例

<?php
/**
* ListAction
*/
class ListAction extends Yaf_Action_Abstract {
public function execute ($name, $id) {
assert($name == $this->getRequest()->getParam("name"));
assert($id == $this->getRequest()->getParam("id"));
}
}
?>

上の例の出力は、 たとえば以下のようになります。

/**
 * Yaf_Route_Static を使っているものとします。
 * http://yourdomain/product/list/name/yaf/id/22
 * にアクセスした結果は次のとおり。
 */
 bool(true)
 bool(true)

参考


コントローラオブジェクトを取得する

  • ≪ Yaf_Action_Abstract::execute
  • Yaf_Action_Abstract::getControllerName ≫
  • PHP Manual
  • Yaf_Action_Abstract
  • コントローラオブジェクトを取得する

Yaf_Action_Abstract::getController

(Yaf >=1.0.0)

Yaf_Action_Abstract::getController — コントローラオブジェクトを取得する

説明

publicYaf_Action_Abstract::getController(): Yaf_Controller_Abstract

現在のコントローラオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

Yaf_Controller_Abstract のインスタンスを返します。


Get controller name

  • ≪ Yaf_Action_Abstract::getController
  • Yaf_View_Interface ≫
  • PHP Manual
  • Yaf_Action_Abstract
  • Get controller name

Yaf_Action_Abstract::getControllerName

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Yaf_Action_Abstract::getControllerName — Get controller name

説明

public Yaf_Action_Abstract::getControllerName(): string

get the controller's name

パラメータ

この関数にはパラメータはありません。

戻り値

string, controller name


Yaf_View_Interface クラス

(Yaf >=1.0.0)

はじめに

Yaf では、組み込みのビューエンジン Yaf_View_Simple のかわりにカスタムビューを自作できるようになっています。 その実例は、 Yaf_Dispatcher::setView() を参照ください。

クラス概要

class Yaf_View_Interface {
/* メソッド */
abstract public assign(string $name, string $value = ?): bool
abstract public display(string $tpl, array $tpl_vars = ?): bool
abstract public getScriptPath(): void
abstract public render(string $tpl, array $tpl_vars = ?): string
abstract public setScriptPath(string $template_dir): void
}

目次

  • Yaf_View_Interface::assign — 値をビューエンジンに代入する
  • Yaf_View_Interface::display — テンプレートをレンダリングして出力する
  • Yaf_View_Interface::getScriptPath — The getScriptPath purpose
  • Yaf_View_Interface::render — テンプレートをレンダリングする
  • Yaf_View_Interface::setScriptPath — The setScriptPath purpose


値をビューエンジンに代入する

  • ≪ Yaf_View_Interface
  • Yaf_View_Interface::display ≫
  • PHP Manual
  • Yaf_View_Interface
  • 値をビューエンジンに代入する

Yaf_View_Interface::assign

(Yaf >=1.0.0)

Yaf_View_Interface::assign — 値をビューエンジンに代入する

説明

abstract public Yaf_View_Interface::assign(string $name, string $value = ?): bool

値をビューエンジンに代入します。これで、テンプレートから名前を指定してその値にアクセスできるようになります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


テンプレートをレンダリングして出力する

  • ≪ Yaf_View_Interface::assign
  • Yaf_View_Interface::getScriptPath ≫
  • PHP Manual
  • Yaf_View_Interface
  • テンプレートをレンダリングして出力する

Yaf_View_Interface::display

(Yaf >=1.0.0)

Yaf_View_Interface::display — テンプレートをレンダリングして出力する

説明

abstract public Yaf_View_Interface::display(string $tpl, array $tpl_vars = ?): bool

テンプレートをレンダリングし、結果をすぐに出力します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tpl

tpl_vars

戻り値


The getScriptPath purpose

  • ≪ Yaf_View_Interface::display
  • Yaf_View_Interface::render ≫
  • PHP Manual
  • Yaf_View_Interface
  • The getScriptPath purpose

Yaf_View_Interface::getScriptPath

(Yaf >=1.0.0)

Yaf_View_Interface::getScriptPath — The getScriptPath purpose

説明

abstract public Yaf_View_Interface::getScriptPath(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


テンプレートをレンダリングする

  • ≪ Yaf_View_Interface::getScriptPath
  • Yaf_View_Interface::setScriptPath ≫
  • PHP Manual
  • Yaf_View_Interface
  • テンプレートをレンダリングする

Yaf_View_Interface::render

(Yaf >=1.0.0)

Yaf_View_Interface::render — テンプレートをレンダリングする

説明

abstract public Yaf_View_Interface::render(string $tpl, array $tpl_vars = ?): string

テンプレートをレンダリングし、結果を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tpl

tpl_vars

戻り値


The setScriptPath purpose

  • ≪ Yaf_View_Interface::render
  • Yaf_View_Simple ≫
  • PHP Manual
  • Yaf_View_Interface
  • The setScriptPath purpose

Yaf_View_Interface::setScriptPath

(Yaf >=1.0.0)

Yaf_View_Interface::setScriptPath — The setScriptPath purpose

説明

abstract public Yaf_View_Interface::setScriptPath(string $template_dir): void

テンプレートのベースディレクトリを設定します。これは通常、 Yaf_Dispatcher から呼ばれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

template_dir

テンプレートディレクトリへの絶対パス。デフォルトは application.directory . "/views" です。

戻り値


Yaf_View_Simple クラス

(Yaf >=1.0.0)

はじめに

Yaf_View_Simple は Yaf の組み込みテンプレートエンジンです。 シンプルながらも高速なテンプレートエンジンで、PHP スクリプトテンプレートだけに対応しています。

クラス概要

class Yaf_View_Simple implements Yaf_View_Interface {
/* プロパティ */
protected $_tpl_vars;
protected $_tpl_dir;
/* メソッド */
final public __construct(string $template_dir, array $options = ?)
public assign(string $name, mixed $value = ?): bool
public assignRef(string $name, mixed &$value): bool
public clear(string $name = ?): bool
public display(string $tpl, array $tpl_vars = ?): bool
public eval(string $tpl_content, array $tpl_vars = ?): string
public __get(string $name = ?): void
public getScriptPath(): string
public __isset(string $name): void
public render(string $tpl, array $tpl_vars = ?): string
public __set(string $name, mixed $value): void
public setScriptPath(string $template_dir): bool
}

プロパティ

_tpl_vars

_tpl_dir

目次

  • Yaf_View_Simple::assign — 値を代入する
  • Yaf_View_Simple::assignRef — The assignRef purpose
  • Yaf_View_Simple::clear — 代入した値をクリアする
  • Yaf_View_Simple::__construct — Yaf_View_Simple のコンストラクタ
  • Yaf_View_Simple::display — レンダリングして表示する
  • Yaf_View_Simple::eval — テンプレートをレンダリングする
  • Yaf_View_Simple::__get — Retrieve assigned variable
  • Yaf_View_Simple::getScriptPath — テンプレートのディレクトリを取得する
  • Yaf_View_Simple::__isset — The __isset purpose
  • Yaf_View_Simple::render — テンプレートをレンダリングする
  • Yaf_View_Simple::__set — 値をエンジンに設定する
  • Yaf_View_Simple::setScriptPath — テンプレートのディレクトリを設定する


値を代入する

  • ≪ Yaf_View_Simple
  • Yaf_View_Simple::assignRef ≫
  • PHP Manual
  • Yaf_View_Simple
  • 値を代入する

Yaf_View_Simple::assign

(Yaf >=1.0.0)

Yaf_View_Simple::assign — 値を代入する

説明

public Yaf_View_Simple::assign(string $name, mixed $value = ?): bool

変数をビューエンジンに代入します。

パラメータ

name

文字列あるいは配列。

文字列の場合は、次の引数 $value が必須となります。

value

代入する値。

戻り値

例

例1 Yaf_View_Simple::assign() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
public function indexAction() {
$this->getView()->assign("foo", "bar");
$this->_view->assign( array( "key" => "value", "name" => "value"));
}
}
?>

例2 テンプレートの例

<html>
<head>
<title><?php echo $foo; ?></title>
</head>
<body>
<?php
foreach ($this->_tpl_vars as $name => $value) {
echo $$name; // or echo $this->_tpl_vars[$name];
}
?>
</body>
</html>

参考

  • Yaf_View_Simple::assignRef() - The assignRef purpose
  • Yaf_View_Interface::clear()
  • Yaf_View_Simple::__set() - 値をエンジンに設定する


The assignRef purpose

  • ≪ Yaf_View_Simple::assign
  • Yaf_View_Simple::clear ≫
  • PHP Manual
  • Yaf_View_Simple
  • The assignRef purpose

Yaf_View_Simple::assignRef

(Yaf >=1.0.0)

Yaf_View_Simple::assignRef — The assignRef purpose

説明

public Yaf_View_Simple::assignRef(string $name, mixed &$value): bool

Yaf_View_Simple::assign() とは異なり、 このメソッドは参照で値をエンジンに代入します。

パラメータ

name

テンプレート内でのアクセスに使う名前。

value

代入する値。

戻り値

例

例1 Yaf_View_Simple::assignRef() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
public function indexAction() {
$value = "bar";
$this->getView()->assign("foo", $value);

/* Yaf 2.1.4 より前のバージョンにはバグがあり、
* この出力が "bar" になっていました
*/
$dummy = $this->getView()->render("index/index.phtml");
echo $value;

// 自動レンダリングを無効にします
Yaf_Dispatcher::getInstance()->autoRender(FALSE);
}
}
?>

例2 テンプレートの例

<html>
<head>
<title><?php echo $foo; $foo = "changed"; ?></title>
</head>
<body>
</body>
</html>

上の例の出力は、 たとえば以下のようになります。

/* index コントローラにアクセスしたときの結果 */
changed

参考

  • Yaf_View_Simple::assign() - 値を代入する
  • Yaf_View_Simple::__set() - 値をエンジンに設定する


代入した値をクリアする

  • ≪ Yaf_View_Simple::assignRef
  • Yaf_View_Simple::__construct ≫
  • PHP Manual
  • Yaf_View_Simple
  • 代入した値をクリアする

Yaf_View_Simple::clear

(Yaf >=2.2.0)

Yaf_View_Simple::clear — 代入した値をクリアする

説明

public Yaf_View_Simple::clear(string $name = ?): bool

代入した値をクリアします。

パラメータ

name

代入した変数名。

空の場合は、すべての変数をクリアします。

戻り値

例

例1 Yaf_View_Simple::clear() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
public function indexAction() {
$this->getView()->clear("foo")->clear("bar"); // "foo" と "bar" をクリアします。
$this->_view->clear(); // 全ての変数をクリアします
}
}
?>

参考

  • Yaf_View_Simple::assignRef() - The assignRef purpose
  • Yaf_View_Interface::assign() - 値をビューエンジンに代入する
  • Yaf_View_Simple::__set() - 値をエンジンに設定する


Yaf_View_Simple のコンストラクタ

  • ≪ Yaf_View_Simple::clear
  • Yaf_View_Simple::display ≫
  • PHP Manual
  • Yaf_View_Simple
  • Yaf_View_Simple のコンストラクタ

Yaf_View_Simple::__construct

(Yaf >=1.0.0)

Yaf_View_Simple::__construct — Yaf_View_Simple のコンストラクタ

説明

final public Yaf_View_Simple::__construct(string $template_dir, array $options = ?)

パラメータ

template_dir

テンプレートのベースディレクトリ。デフォルトは APPLICATOIN . "/views" です。

options

エンジンのオプション。Yaf 2.1.13 からは、短いタグ
      "<?=$var?>" を ("short_open_tag" の値にかかわらず)
      テンプレートで使えるようになりました。
      オプション "short_tag" をオフにすると、テンプレートで短いタグを使わないようにできます。

例

例1 Yaf_View_Simple::__constructor() の例

<?php
define ("TEMPLATE_DIRECTORY", APPLICATOIN_PATH . '/views');
$view = new Yaf_View_Simple(TEMPLATE_DIRECTORY, array(
'short_tag' => false // テンプレートで短いタグを使わせないようにします
));
?>


レンダリングして表示する

  • ≪ Yaf_View_Simple::__construct
  • Yaf_View_Simple::eval ≫
  • PHP Manual
  • Yaf_View_Simple
  • レンダリングして表示する

Yaf_View_Simple::display

(Yaf >=1.0.0)

Yaf_View_Simple::display — レンダリングして表示する

説明

public Yaf_View_Simple::display(string $tpl, array $tpl_vars = ?): bool

テンプレートをレンダリングして、結果をすぐに返します。

パラメータ

tpl

tpl_vars

戻り値


テンプレートをレンダリングする

  • ≪ Yaf_View_Simple::display
  • Yaf_View_Simple::__get ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートをレンダリングする

Yaf_View_Simple::eval

(Yaf >=2.2.0)

Yaf_View_Simple::eval — テンプレートをレンダリングする

説明

public Yaf_View_Simple::eval(string $tpl_content, array $tpl_vars = ?): string

文字列のテンプレートをレンダリングして結果を返します。

パラメータ

tpl_content

文字列のテンプレート。

tpl_vars

戻り値


Retrieve assigned variable

  • ≪ Yaf_View_Simple::eval
  • Yaf_View_Simple::getScriptPath ≫
  • PHP Manual
  • Yaf_View_Simple
  • Retrieve assigned variable

Yaf_View_Simple::__get

(Yaf >=1.0.0)

Yaf_View_Simple::__get — Retrieve assigned variable

説明

public Yaf_View_Simple::__get(string $name = ?): void

代入した変数を取得します。

注意:

2.1.11 からは、パラメータを空にできます。

パラメータ

name

代入した変数名。

空にすると、すべての変数を返します。

戻り値


テンプレートのディレクトリを取得する

  • ≪ Yaf_View_Simple::__get
  • Yaf_View_Simple::__isset ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートのディレクトリを取得する

Yaf_View_Simple::getScriptPath

(Yaf >=1.0.0)

Yaf_View_Simple::getScriptPath — テンプレートのディレクトリを取得する

説明

public Yaf_View_Simple::getScriptPath(): string

パラメータ

この関数にはパラメータはありません。

戻り値


The __isset purpose

  • ≪ Yaf_View_Simple::getScriptPath
  • Yaf_View_Simple::render ≫
  • PHP Manual
  • Yaf_View_Simple
  • The __isset purpose

Yaf_View_Simple::__isset

(Yaf >=1.0.0)

Yaf_View_Simple::__isset — The __isset purpose

説明

public Yaf_View_Simple::__isset(string $name): void

パラメータ

name

戻り値


テンプレートをレンダリングする

  • ≪ Yaf_View_Simple::__isset
  • Yaf_View_Simple::__set ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートをレンダリングする

Yaf_View_Simple::render

(Yaf >=1.0.0)

Yaf_View_Simple::render — テンプレートをレンダリングする

説明

public Yaf_View_Simple::render(string $tpl, array $tpl_vars = ?): string

テンプレートをレンダリングして、結果を返します。

パラメータ

tpl

tpl_vars

戻り値


値をエンジンに設定する

  • ≪ Yaf_View_Simple::render
  • Yaf_View_Simple::setScriptPath ≫
  • PHP Manual
  • Yaf_View_Simple
  • 値をエンジンに設定する

Yaf_View_Simple::__set

(Yaf >=1.0.0)

Yaf_View_Simple::__set — 値をエンジンに設定する

説明

public Yaf_View_Simple::__set(string $name, mixed $value): void

Yaf_View_Simple::assign() をもっと簡単にするもうひとつの方法です。

パラメータ

name

変数名。

value

変数の値。

戻り値

例

例1 Yaf_View_Simple::__set() の例

<?php
class IndexController extends Yaf_Controller_Abstract {
public function indexAction() {
$this->getView()->foo = "bar"; // assign("foo", "bar"); と同じ意味
}
}
?>

参考

  • Yaf_View_Simple::assignRef() - The assignRef purpose
  • Yaf_View_Interface::assign() - 値をビューエンジンに代入する


テンプレートのディレクトリを設定する

  • ≪ Yaf_View_Simple::__set
  • Yaf_Loader ≫
  • PHP Manual
  • Yaf_View_Simple
  • テンプレートのディレクトリを設定する

Yaf_View_Simple::setScriptPath

(Yaf >=1.0.0)

Yaf_View_Simple::setScriptPath — テンプレートのディレクトリを設定する

説明

public Yaf_View_Simple::setScriptPath(string $template_dir): bool

パラメータ

template_dir

戻り値


Yaf_Loader クラス

(Yaf >=1.0.0)

はじめに

Yaf_Loader は、 Yaf 用に包括的なオートローディング機能を導入します。

最初に Yaf_Application のインスタンスを取得するときに、 Yaf_Loader はシングルトンのインスタンスを作って それを spl_autoload に登録します。このインスタンスを取得するには Yaf_Loader::getInstance() を使います。

Yaf_Loader は、クラスのロードを一度だけ試みます。 失敗した場合の挙動は yaf.use_spl_auload によって変わります。もしこの設定が On なら Yaf_Loader::autoload() は false を返し、 他のオートロード関数でやり直せるようになります。この設定が Off (デフォルト) の場合は Yaf_Loader::autoload() が true を返します。 そして、より重要なのは、このときに警告メッセージが出ることです (このメッセージを見れば、なぜロードできなかったのかがわかります)。

注意:

yaf.use_spl_autoload はできるだけ Off のままにしておきましょう。 ただし、何かのライブラリが自前のオートロード機構を持っていて、 それを置き換えるのが不可能だという場合は別です。

デフォルトでは、Yaf_Loader はすべてのライブラリ (クラスを定義したスクリプト) が グローバル ライブラリディレクトリ に格納されているものとみなします。このディレクトリは、 php.ini (yaf.library) で指定します。

Yaf_Loader がクラス (ライブラリ) を探すときに ローカルクラスディレクトリ (application.ini で定義するもので、デフォルトは application.directory . "/library") も検索対象とさせたい場合は、クラスのプレフィックスを Yaf_Loader::registerLocalNameSpace() で登録する必要があります。

いくつか例を示します (APPLICATION_PATH は application.directory であるものとします)。

例1 設定の例

// php.ini で、これを設定しているものとします
yaf.library = "/global_dir"

// application.ini で、これを設定しているものとします
application.library = APPLICATION_PATH "/library"
また、次のローカル名前空間を登録しているものとします。

例2 localnamespace の登録

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
public function _initLoader($dispatcher) {
Yaf_Loader::getInstance()->registerLocalNameSpace(array("Foo", "Bar"));
}
?>
オートロードの例です。

例3 クラスのロード

class Foo_Bar_Test =>
  // APPLICATION_PATH/library/Foo/Bar/Test.php

class GLO_Name  =>
  // /global_dir/Glo/Name.php

class BarNon_Test
  // /global_dir/Barnon/Test.php

例4 名前空間つきのクラスのロード

class \Foo\Bar\Dummy =>
   // APPLICATION_PATH/library/Foo/Bar/Dummy.php

class \FooBar\Bar\Dummy =>
   // /global_dir/FooBar/Bar/Dummy.php

すべてのフォルダの先頭が大文字になっているのが気になる場合は、php.ini で yaf.lowcase_path = On とすれば小文字にすることもできます。

Yaf_Loader は MVC クラスを読み込むようにも作られています。 次のような規約に従います。

例5 MVC クラスのロード

Controller Classes =>
// APPLICATION_PATH/controllers/

Model Classes =>
// APPLICATION_PATH/models/

Plugin Classes =>
// APPLICATION_PATH/plugins/
クラスのサフィックス (デフォルト設定の場合。プレフィックスを使うには yaf.name_suffix の値を変更します) で、MVC クラスであるかそうでないかを判断します。

例6 MVC クラスかどうかの区別

Controller Classes =>
    // ***Controller

Model Classes =>
    // ***Model

Plugin Classes =>
    // ***Plugin
例を示します。

例7 MVC のロード

class IndexController
    // APPLICATION_PATH/controllers/Index.php

class DataModel =>
   // APPLICATION_PATH/models/Data.php

class DummyPlugin =>
  // APPLICATION_PATH/plugins/Dummy.php

class A_B_TestModel =>
  // APPLICATION_PATH/models/A/B/Test.php

注意:

2.1.18 からは、Yaf はユーザースクリプト側からのコントローラのオートロードに対応しました (つまり、ユーザーが書いた PHP スクリプトからオートロードを実行できるということです。 ブートストラップやプラグインから、コントローラのstaticプロパティにアクセスできます)。 しかし、オートローダーがコントローラクラスを探す場所は、デフォルトのモジュールフォルダつまり "APPLICATION_PATH/controllers/" だけになります。

また、ディレクトリは yaf.lowcase_path の影響を受けます。

クラス概要

class Yaf_Loader {
/* プロパティ */
protected $_local_ns;
protected $_library;
protected $_global_library;
static $_instance;
/* メソッド */
private __construct()
public autoload(): void
public clearLocalNamespace(): void
public static getInstance(): void
public getLibraryPath(bool $is_global = false): Yaf_Loader
public getLocalNamespace(): void
public getNamespacePath(string $namespaces): string
public getNamespaces(): array
public static import(): void
public isLocalName(): void
public registerLocalNamespace(mixed $prefix): void
public registerNamespace(string|array $namespaces, string $path = ?): bool
public setLibraryPath(string $directory, bool $is_global = false): Yaf_Loader
}

プロパティ

_local_ns

_library

デフォルトでは、この値は application.directory . "/library" となります。この値を変更するには、application.ini (application.library) で設定するか、あるいは Yaf_Loader::setLibraryPath() をコールします。

_global_library

_instance

目次

  • Yaf_Loader::autoload — The autoload purpose
  • Yaf_Loader::clearLocalNamespace — The clearLocalNamespace purpose
  • Yaf_Loader::__construct — The __construct purpose
  • Yaf_Loader::getInstance — The getInstance purpose
  • Yaf_Loader::getLibraryPath — ライブラリパスを取得する
  • Yaf_Loader::getLocalNamespace — The getLocalNamespace purpose
  • Yaf_Loader::getNamespacePath — Retieve path of a registered namespace
  • Yaf_Loader::getLocalNamespace — Retrive all register namespaces info
  • Yaf_Loader::import — The import purpose
  • Yaf_Loader::isLocalName — The isLocalName purpose
  • Yaf_Loader::registerLocalNamespace — ローカルクラスプレフィックスを登録する
  • Yaf_Loader::registerNamespace — Register namespace with searching path
  • Yaf_Loader::setLibraryPath — ライブラリパスを変更する


The autoload purpose

  • ≪ Yaf_Loader
  • Yaf_Loader::clearLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • The autoload purpose

Yaf_Loader::autoload

(Yaf >=1.0.0)

Yaf_Loader::autoload — The autoload purpose

説明

public Yaf_Loader::autoload(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The clearLocalNamespace purpose

  • ≪ Yaf_Loader::autoload
  • Yaf_Loader::__construct ≫
  • PHP Manual
  • Yaf_Loader
  • The clearLocalNamespace purpose

Yaf_Loader::clearLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::clearLocalNamespace — The clearLocalNamespace purpose

説明

public Yaf_Loader::clearLocalNamespace(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __construct purpose

  • ≪ Yaf_Loader::clearLocalNamespace
  • Yaf_Loader::getInstance ≫
  • PHP Manual
  • Yaf_Loader
  • The __construct purpose

Yaf_Loader::__construct

(Yaf >=1.0.0)

Yaf_Loader::__construct — The __construct purpose

説明

private Yaf_Loader::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getInstance purpose

  • ≪ Yaf_Loader::__construct
  • Yaf_Loader::getLibraryPath ≫
  • PHP Manual
  • Yaf_Loader
  • The getInstance purpose

Yaf_Loader::getInstance

(Yaf >=1.0.0)

Yaf_Loader::getInstance — The getInstance purpose

説明

public static Yaf_Loader::getInstance(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


ライブラリパスを取得する

  • ≪ Yaf_Loader::getInstance
  • Yaf_Loader::getLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • ライブラリパスを取得する

Yaf_Loader::getLibraryPath

(Yaf >=2.1.4)

Yaf_Loader::getLibraryPath — ライブラリパスを取得する

説明

public Yaf_Loader::getLibraryPath(bool $is_global = false): Yaf_Loader

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getLocalNamespace purpose

  • ≪ Yaf_Loader::getLibraryPath
  • Yaf_Loader::getNamespacePath ≫
  • PHP Manual
  • Yaf_Loader
  • The getLocalNamespace purpose

Yaf_Loader::getLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::getLocalNamespace — The getLocalNamespace purpose

説明

public Yaf_Loader::getLocalNamespace(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Retieve path of a registered namespace

  • ≪ Yaf_Loader::getLocalNamespace
  • Yaf_Loader::getLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • Retieve path of a registered namespace

Yaf_Loader::getNamespacePath

(Yaf >=3.2.0)

Yaf_Loader::getNamespacePath — Retieve path of a registered namespace

説明

public Yaf_Loader::getNamespacePath(string $namespaces): string

retrieve path of a registered namespace

パラメータ

namespace

a string of namespace.

戻り値

string path, if the namespace is not registered, then null default library will be returned

例

例1 Yaf_Loader::registerNamespace()example

<?php
$loader = Yaf_Loader::getInstance("/var/application/lib");
$loader->registerNamespace("\Vendor\PHP", "/var/lib/php");

$loader->getNamespacePath("\Vendor\PHP"); // '/var/lib/php'
$loader->getNamespacePath("\Vendor\JSP"); // '/var/application/lib'

?>


Retrive all register namespaces info

  • ≪ Yaf_Loader::getNamespacePath
  • Yaf_Loader::import ≫
  • PHP Manual
  • Yaf_Loader
  • Retrive all register namespaces info

Yaf_Loader::getLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::getLocalNamespace — Retrive all register namespaces info

説明

public Yaf_Loader::getNamespaces(): array

get registered namespaces info

パラメータ

この関数にはパラメータはありません。

戻り値

array


The import purpose

  • ≪ Yaf_Loader::getLocalNamespace
  • Yaf_Loader::isLocalName ≫
  • PHP Manual
  • Yaf_Loader
  • The import purpose

Yaf_Loader::import

(Yaf >=1.0.0)

Yaf_Loader::import — The import purpose

説明

public static Yaf_Loader::import(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The isLocalName purpose

  • ≪ Yaf_Loader::import
  • Yaf_Loader::registerLocalNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • The isLocalName purpose

Yaf_Loader::isLocalName

(Yaf >=1.0.0)

Yaf_Loader::isLocalName — The isLocalName purpose

説明

public Yaf_Loader::isLocalName(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


ローカルクラスプレフィックスを登録する

  • ≪ Yaf_Loader::isLocalName
  • Yaf_Loader::registerNamespace ≫
  • PHP Manual
  • Yaf_Loader
  • ローカルクラスプレフィックスを登録する

Yaf_Loader::registerLocalNamespace

(Yaf >=1.0.0)

Yaf_Loader::registerLocalNamespace — ローカルクラスプレフィックスを登録する

説明

public Yaf_Loader::registerLocalNamespace(mixed $prefix): void

ローカルクラスプレフィックスを登録します。 Yaf_Loader がクラスを探すときには、二つのライブラリディレクトリを探します。 一方は application.ini の application.library.directory(in で設定したもので、これをローカルライブラリディレクトリと呼びます。 もう一方は php.ini の yaf.library で設定したもので、これをグローバルライブラリディレクトリと呼びます。 同一サーバー内のいろんなアプリケーションで共有できるからです。

オートロード時に、Yaf_Loader がどちらのライブラリディレクトリを探すのかを判断します。 その際には、存在しないクラス名のプレフィックスを判断材料にします。 プレフィックスの名前が localnamespace として登録されていれば ローカルライブラリディレクトリから探し、そうでなければグローバルライブラリディレクトリから探します。

注意:

yaf.library が設定されていない場合、グローバルライブラリディレクトリは ローカルライブラリディレクトリと同じ場所であるとみなします。 その場合、オートロード時にはすべてローカルライブラリディレクトリを探します。 Yaf アプリケーションを強くするには、 自分のクラスはローカルクラスとして登録するようにしましょう。

パラメータ

prefix

クラス名のプレフィックスを表す文字列あるいは配列。 ローカルライブラリパスにある、このプレフィックスを含むすべてのクラスが読み込まれます。

戻り値

bool

例

例1 Yaf_Loader::registerLocalNamespace() の例

<?php
$loader = Yaf_Loader::getInstance('/local/library/', '/global/library');
$loader->registerLocalNamespace("Baidu");
$loader->registerLocalNamespace(array("Sina", "Weibo"));

$loader->autoload("Baidu_Name"); // search in '/local/library/'
$loader->autoload("Sina"); // search '/local/library/'
$loader->autoload("Global_Name");// search in '/global/library/'
$loader->autoload("Foo_Bar"); // search in '/global/library/'

?>


Register namespace with searching path

  • ≪ Yaf_Loader::registerLocalNamespace
  • Yaf_Loader::setLibraryPath ≫
  • PHP Manual
  • Yaf_Loader
  • Register namespace with searching path

Yaf_Loader::registerNamespace

(Yaf >=3.2.0)

Yaf_Loader::registerNamespace — Register namespace with searching path

説明

public Yaf_Loader::registerNamespace(string|array $namespaces, string $path = ?): bool

Register a namespace with searching path, Yaf_Loader searchs classes under this namespace in path, the one is also could be configureded via application.library.directory.namespace(in application.ini);

注意:

Yaf still think underline as folder separator.

パラメータ

namespace

a string of namespace, or a array of namespaces with paths.

path

a string of path, it is better to use abosolute path here for performance

戻り値

bool

例

例1 Yaf_Loader::registerNamespace()example

<?php
$loader = Yaf_Loader::getInstance();
$loader->registerNamespace("\Vendor\PHP", "/var/lib/php");
$loader->registerNamespace(array(
"\Vendor\ASP" => "/var/lib/asp",
"\Vendor\JSP" => "/usr/lib/vendor/",
));

$loader->autoload("\Vendor\PHP\Dummy"); //load '/var/lib/php/Dummy.php'
$loader->autoload("\Vendor\PHP\Foo_Bar"); //load '/var/lib/php/Foo/Bar.php'
$loader->autoload("\Vendor\JSP\Dummy"); //load '/usr/lib/vendor/Dummy.php'

?>


ライブラリパスを変更する

  • ≪ Yaf_Loader::registerNamespace
  • Yaf_Plugin_Abstract ≫
  • PHP Manual
  • Yaf_Loader
  • ライブラリパスを変更する

Yaf_Loader::setLibraryPath

(Yaf >=2.1.4)

Yaf_Loader::setLibraryPath — ライブラリパスを変更する

説明

public Yaf_Loader::setLibraryPath(string $directory, bool $is_global = false): Yaf_Loader

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Plugin_Abstract クラス

(Yaf >=1.0.0)

はじめに

プラグインを使えば、フレームワークの拡張やカスタマイズを簡単に行えます。

プラグインは、クラスとして定義します。 実際のクラスの定義はコンポーネントによって異なります。 このインターフェイスを実装する必要があるかもしれませんが、 プラグイン自体がクラスであるという事実は変わりません。

プラグインを Yaf にロードするには Yaf_Dispatcher::registerPlugin() を使います。登録を済ませれば、このインターフェイスに従って実装した すべてのメソッドが適切な場面で呼ばれます。

例

例1 プラグインの例

<?php
/* bootstrap class should be defined under ./application/Bootstrap.php */
class Bootstrap extends Yaf_Bootstrap_Abstract {
public function _initPlugin(Yaf_Dispatcher $dispatcher) {
/* register a plugin */
$dispatcher->registerPlugin(new TestPlugin());
}
}

/* plugin class should be placed under ./application/plugins/ */
class TestPlugin extends Yaf_Plugin_Abstract {
public function routerStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
/* before router
in this hook, user can do some url rewrite */
var_dump("routerStartup");
}
public function routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
/* router complete
in this hook, user can do login check */
var_dump("routerShutdown");
}
public function dispatchLoopStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
var_dump("dispatchLoopStartup");
}
public function preDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
var_dump("preDispatch");
}
public function postDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
var_dump("postDispatch");
}
public function dispatchLoopShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
/* final hook
in this hook user can do logging or implement layout */
var_dump("dispatchLoopShutdown");
}
}

Class IndexController extends Yaf_Controller_Abstract {
public function indexAction() {
return FALSE; //prevent rendering
}
}

$config = array(
"application" => array(
"directory" => dirname(__FILE__) . "/application/",
),
);

$app = new Yaf_Application($config);
$app->bootstrap()->run();
?>

上の例の出力は、 たとえば以下のようになります。

string(13) "routerStartup"
string(14) "routerShutdown"
string(19) "dispatchLoopStartup"
string(11) "preDispatch"
string(12) "postDispatch"
string(20) "dispatchLoopShutdown"

クラス概要

class Yaf_Plugin_Abstract {
/* メソッド */
public dispatchLoopShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
public dispatchLoopStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
public postDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
public preDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
public preResponse(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
public routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
public routerStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void
}

目次

  • Yaf_Plugin_Abstract::dispatchLoopShutdown — The dispatchLoopShutdown purpose
  • Yaf_Plugin_Abstract::dispatchLoopStartup — ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::postDispatch — The postDispatch purpose
  • Yaf_Plugin_Abstract::preDispatch — The preDispatch purpose
  • Yaf_Plugin_Abstract::preResponse — The preResponse purpose
  • Yaf_Plugin_Abstract::routerShutdown — The routerShutdown purpose
  • Yaf_Plugin_Abstract::routerStartup — RouterStartup フック


The dispatchLoopShutdown purpose

  • ≪ Yaf_Plugin_Abstract
  • Yaf_Plugin_Abstract::dispatchLoopStartup ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The dispatchLoopShutdown purpose

Yaf_Plugin_Abstract::dispatchLoopShutdown

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::dispatchLoopShutdown — The dispatchLoopShutdown purpose

説明

public Yaf_Plugin_Abstract::dispatchLoopShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

これは、Yaf プラグインのフックシステム内での最後のフックです。 このメソッドを実装したカスタムプラグインは、 ディスパッチループが終了したときに呼ばれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

戻り値

参考

  • Yaf_Plugin_Abstract::routerStartup() - RouterStartup フック
  • Yaf_Plugin_Abstract::routerShutdown() - The routerShutdown purpose
  • Yaf_Plugin_Abstract::dispatchLoopStartup() - ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::preDispatch() - The preDispatch purpose
  • Yaf_Plugin_Abstract::postDispatch() - The postDispatch purpose


ディスパッチループの前にフックする

  • ≪ Yaf_Plugin_Abstract::dispatchLoopShutdown
  • Yaf_Plugin_Abstract::postDispatch ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • ディスパッチループの前にフックする

Yaf_Plugin_Abstract::dispatchLoopStartup

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::dispatchLoopStartup — ディスパッチループの前にフックする

説明

public Yaf_Plugin_Abstract::dispatchLoopStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

パラメータ

request

response

戻り値


The postDispatch purpose

  • ≪ Yaf_Plugin_Abstract::dispatchLoopStartup
  • Yaf_Plugin_Abstract::preDispatch ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The postDispatch purpose

Yaf_Plugin_Abstract::postDispatch

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::postDispatch — The postDispatch purpose

説明

public Yaf_Plugin_Abstract::postDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

戻り値


The preDispatch purpose

  • ≪ Yaf_Plugin_Abstract::postDispatch
  • Yaf_Plugin_Abstract::preResponse ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The preDispatch purpose

Yaf_Plugin_Abstract::preDispatch

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::preDispatch — The preDispatch purpose

説明

public Yaf_Plugin_Abstract::preDispatch(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

戻り値


The preResponse purpose

  • ≪ Yaf_Plugin_Abstract::preDispatch
  • Yaf_Plugin_Abstract::routerShutdown ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The preResponse purpose

Yaf_Plugin_Abstract::preResponse

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::preResponse — The preResponse purpose

説明

public Yaf_Plugin_Abstract::preResponse(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

戻り値


The routerShutdown purpose

  • ≪ Yaf_Plugin_Abstract::preResponse
  • Yaf_Plugin_Abstract::routerStartup ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • The routerShutdown purpose

Yaf_Plugin_Abstract::routerShutdown

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::routerShutdown — The routerShutdown purpose

説明

public Yaf_Plugin_Abstract::routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

このフックが動くのは、ルーティングが終了したときです。 このフックは、ログインのチェックなどでよく使います。

パラメータ

request

response

戻り値

例

例1 Yaf_Plugin_Abstract::routerShutdown() の例

<?php
class UserInitPlugin extends Yaf_Plugin_Abstract {

public function routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
$controller = $request->getControllerName();

/**
* Use access controller is unecessary for APIs
*/
if (in_array(strtolower($controller), array(
'api',
))) {
return TRUE;
}

if (Yaf_Session::getInstance()->has("login")) {
return TRUE;
}

/* Use access check failed, need to login */
$response->setRedirect("http://yourdomain.com/login/");
return FALSE;
}
}
?>

参考

  • Yaf_Plugin_Abstract::routerStartup() - RouterStartup フック
  • Yaf_Plugin_Abstract::dispatchLoopStartup() - ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::preDispatch() - The preDispatch purpose
  • Yaf_Plugin_Abstract::postDispatch() - The postDispatch purpose
  • Yaf_Plugin_Abstract::dispatchLoopShutdown() - The dispatchLoopShutdown purpose


RouterStartup フック

  • ≪ Yaf_Plugin_Abstract::routerShutdown
  • Yaf_Registry ≫
  • PHP Manual
  • Yaf_Plugin_Abstract
  • RouterStartup フック

Yaf_Plugin_Abstract::routerStartup

(Yaf >=1.0.0)

Yaf_Plugin_Abstract::routerStartup — RouterStartup フック

説明

public Yaf_Plugin_Abstract::routerStartup(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response): void

これは、Yaf プラグインのフックシステム内での最初のフックです。 このメソッドを実装したカスタムプラグインは、 ルーティングを始める前に呼ばれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

response

戻り値

参考

  • Yaf_Plugin_Abstract::routerShutdown() - The routerShutdown purpose
  • Yaf_Plugin_Abstract::dispatchLoopStartup() - ディスパッチループの前にフックする
  • Yaf_Plugin_Abstract::preDispatch() - The preDispatch purpose
  • Yaf_Plugin_Abstract::postDispatch() - The postDispatch purpose
  • Yaf_Plugin_Abstract::dispatchLoopShutdown() - The dispatchLoopShutdown purpose


Yaf_Registry クラス

(Yaf >=1.0.0)

はじめに

Yaf_Registry のすべてのメソッドはstaticメソッドとして宣言されており、 どこからでもアクセスできます。これを使えば、コードのどこからでも必要に応じて 任意のデータを保存したり取得したりすることができます。

クラス概要

class Yaf_Registry {
/* プロパティ */
static $_instance;
protected $_entries;
/* メソッド */
private __construct()
public static del(string $name): void
public static get(string $name): mixed
public static has(string $name): bool
public static set(string $name, string $value): bool
}

プロパティ

_instance

_entries

目次

  • Yaf_Registry::__construct — Yaf_Registry はシングルトンを実装する
  • Yaf_Registry::del — アイテムをレジストリから削除する
  • Yaf_Registry::get — アイテムをレジストリから取得する
  • Yaf_Registry::has — アイテムが存在するかどうかを調べる
  • Yaf_Registry::set — アイテムをレジストリに追加する


Yaf_Registry はシングルトンを実装する

  • ≪ Yaf_Registry
  • Yaf_Registry::del ≫
  • PHP Manual
  • Yaf_Registry
  • Yaf_Registry はシングルトンを実装する

Yaf_Registry::__construct

(Yaf >=1.0.0)

Yaf_Registry::__construct — Yaf_Registry はシングルトンを実装する

説明

private Yaf_Registry::__construct()

パラメータ

この関数にはパラメータはありません。

戻り値


アイテムをレジストリから削除する

  • ≪ Yaf_Registry::__construct
  • Yaf_Registry::get ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムをレジストリから削除する

Yaf_Registry::del

(Yaf >=1.0.0)

Yaf_Registry::del — アイテムをレジストリから削除する

説明

public static Yaf_Registry::del(string $name): void

アイテムをレジストリから削除します。

パラメータ

name

戻り値


アイテムをレジストリから取得する

  • ≪ Yaf_Registry::del
  • Yaf_Registry::has ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムをレジストリから取得する

Yaf_Registry::get

(Yaf >=1.0.0)

Yaf_Registry::get — アイテムをレジストリから取得する

説明

public static Yaf_Registry::get(string $name): mixed

アイテムをレジストリから取得します。

パラメータ

name

戻り値


アイテムが存在するかどうかを調べる

  • ≪ Yaf_Registry::get
  • Yaf_Registry::set ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムが存在するかどうかを調べる

Yaf_Registry::has

(Yaf >=1.0.0)

Yaf_Registry::has — アイテムが存在するかどうかを調べる

説明

public static Yaf_Registry::has(string $name): bool

アイテムが存在するかどうかを調べます。

パラメータ

name

戻り値


アイテムをレジストリに追加する

  • ≪ Yaf_Registry::has
  • Yaf_Request_Abstract ≫
  • PHP Manual
  • Yaf_Registry
  • アイテムをレジストリに追加する

Yaf_Registry::set

(Yaf >=1.0.0)

Yaf_Registry::set — アイテムをレジストリに追加する

説明

public static Yaf_Registry::set(string $name, string $value): bool

アイテムをレジストリに追加します。

パラメータ

name

value

戻り値


Yaf_Request_Abstract クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Request_Abstract {
/* 定数 */
const string SCHEME_HTTP = http;
const string SCHEME_HTTPS = https;
/* プロパティ */
public $module;
public $controller;
public $action;
public $method;
protected $params;
protected $language;
protected $_exception;
protected $_base_uri;
protected $uri;
protected $dispatched;
protected $routed;
/* メソッド */
public clearParams(): bool
public getActionName(): void
public getBaseUri(): void
public getControllerName(): void
public getEnv(string $name, string $default = ?): void
public getException(): void
public getLanguage(): void
public getMethod(): string
public getModuleName(): void
public getParam(string $name, string $default = ?): mixed
public getParams(): array
public getRequestUri(): void
public getServer(string $name, string $default = ?): void
public isCli(): bool
public isDispatched(): bool
public isGet(): bool
public isHead(): bool
public isOptions(): bool
public isPost(): bool
public isPut(): bool
public isRouted(): bool
public isXmlHttpRequest(): bool
public setActionName(string $action, bool $format_name = true): void
public setBaseUri(string $uir): bool
public setControllerName(string $controller, bool $format_name = true): void
public setDispatched(): void
public setModuleName(string $module, bool $format_name = true): void
public setParam(string $name, string $value = ?): bool
public setRequestUri(string $uir): void
public setRouted(string $flag = ?): void
}

プロパティ

module

controller

action

method

params

language

_exception

_base_uri

uri

dispatched

routed

定義済み定数

Yaf_Request_Abstract::SCHEME_HTTP

Yaf_Request_Abstract::SCHEME_HTTPS

目次

  • Yaf_Request_Abstract::clearParams — Remove all params
  • Yaf_Request_Abstract::getActionName — The getActionName purpose
  • Yaf_Request_Abstract::getBaseUri — The getBaseUri purpose
  • Yaf_Request_Abstract::getControllerName — The getControllerName purpose
  • Yaf_Request_Abstract::getEnv — ENV 変数を取得する
  • Yaf_Request_Abstract::getException — The getException purpose
  • Yaf_Request_Abstract::getLanguage — クライアントの好きな言語を取得する
  • Yaf_Request_Abstract::getMethod — リクエストメソッドを取得する
  • Yaf_Request_Abstract::getModuleName — The getModuleName purpose
  • Yaf_Request_Abstract::getParam — 呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getParams — 全ての呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getRequestUri — The getRequestUri purpose
  • Yaf_Request_Abstract::getServer — SERVER 変数を取得する
  • Yaf_Request_Abstract::isCli — CLIリクエストかを判定する
  • Yaf_Request_Abstract::isDispatched — リクエストがディスパッチ済みかを判定する
  • Yaf_Request_Abstract::isGet — GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isHead — HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions — OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPost — POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut — PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isRouted — リクエストがルーティング済みかを判定する
  • Yaf_Request_Abstract::isXmlHttpRequest — AJAXリクエストかどうかを判定する
  • Yaf_Request_Abstract::setActionName — アクション名を設定する
  • Yaf_Request_Abstract::setBaseUri — ベース URI を設定する
  • Yaf_Request_Abstract::setControllerName — コントローラー名を設定する
  • Yaf_Request_Abstract::setDispatched — The setDispatched purpose
  • Yaf_Request_Abstract::setModuleName — モジュール名を設定する
  • Yaf_Request_Abstract::setParam — 呼び出しパラメータをリクエストに設定する
  • Yaf_Request_Abstract::setRequestUri — The setRequestUri purpose
  • Yaf_Request_Abstract::setRouted — The setRouted purpose


Remove all params

  • ≪ Yaf_Request_Abstract
  • Yaf_Request_Abstract::getActionName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • Remove all params

Yaf_Request_Abstract::clearParams

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Yaf_Request_Abstract::clearParams — Remove all params

説明

public Yaf_Request_Abstract::clearParams(): bool

Remove all params set by router, or Yaf_Request_Abstract::setParam()

パラメータ

この関数にはパラメータはありません。

戻り値

bool

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


The getActionName purpose

  • ≪ Yaf_Request_Abstract::clearParams
  • Yaf_Request_Abstract::getBaseUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getActionName purpose

Yaf_Request_Abstract::getActionName

(Yaf >=1.0.0)

Yaf_Request_Abstract::getActionName — The getActionName purpose

説明

public Yaf_Request_Abstract::getActionName(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getBaseUri purpose

  • ≪ Yaf_Request_Abstract::getActionName
  • Yaf_Request_Abstract::getControllerName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getBaseUri purpose

Yaf_Request_Abstract::getBaseUri

(Yaf >=1.0.0)

Yaf_Request_Abstract::getBaseUri — The getBaseUri purpose

説明

public Yaf_Request_Abstract::getBaseUri(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getControllerName purpose

  • ≪ Yaf_Request_Abstract::getBaseUri
  • Yaf_Request_Abstract::getEnv ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getControllerName purpose

Yaf_Request_Abstract::getControllerName

(Yaf >=1.0.0)

Yaf_Request_Abstract::getControllerName — The getControllerName purpose

説明

public Yaf_Request_Abstract::getControllerName(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


ENV 変数を取得する

  • ≪ Yaf_Request_Abstract::getControllerName
  • Yaf_Request_Abstract::getException ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • ENV 変数を取得する

Yaf_Request_Abstract::getEnv

(Yaf >=1.0.0)

Yaf_Request_Abstract::getEnv — ENV 変数を取得する

説明

public Yaf_Request_Abstract::getEnv(string $name, string $default = ?): void

ENV 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

戻り値

ストリングを返します

参考

  • Yaf_Request_Abstract::getServer
  • Yaf_Request_Abstract::getParam


The getException purpose

  • ≪ Yaf_Request_Abstract::getEnv
  • Yaf_Request_Abstract::getLanguage ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getException purpose

Yaf_Request_Abstract::getException

(Yaf >=1.0.0)

Yaf_Request_Abstract::getException — The getException purpose

説明

public Yaf_Request_Abstract::getException(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


クライアントの好きな言語を取得する

  • ≪ Yaf_Request_Abstract::getException
  • Yaf_Request_Abstract::getMethod ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • クライアントの好きな言語を取得する

Yaf_Request_Abstract::getLanguage

(Yaf >=1.0.0)

Yaf_Request_Abstract::getLanguage — クライアントの好きな言語を取得する

説明

public Yaf_Request_Abstract::getLanguage(): void

パラメータ

この関数にはパラメータはありません。

戻り値

文字列を返します。


リクエストメソッドを取得する

  • ≪ Yaf_Request_Abstract::getLanguage
  • Yaf_Request_Abstract::getModuleName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • リクエストメソッドを取得する

Yaf_Request_Abstract::getMethod

(Yaf >=1.0.0)

Yaf_Request_Abstract::getMethod — リクエストメソッドを取得する

説明

public Yaf_Request_Abstract::getMethod(): string

パラメータ

この関数にはパラメータはありません。

戻り値

"POST", "GET" などのような文字列を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


The getModuleName purpose

  • ≪ Yaf_Request_Abstract::getMethod
  • Yaf_Request_Abstract::getParam ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getModuleName purpose

Yaf_Request_Abstract::getModuleName

(Yaf >=1.0.0)

Yaf_Request_Abstract::getModuleName — The getModuleName purpose

説明

public Yaf_Request_Abstract::getModuleName(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


呼び出しパラメータを取得する

  • ≪ Yaf_Request_Abstract::getModuleName
  • Yaf_Request_Abstract::getParams ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • 呼び出しパラメータを取得する

Yaf_Request_Abstract::getParam

(Yaf >=1.0.0)

Yaf_Request_Abstract::getParam — 呼び出しパラメータを取得する

説明

public Yaf_Request_Abstract::getParam(string $name, string $default = ?): mixed

パラメータ

name

default

戻り値

参考

  • Yaf_Request_Abstract::setParam() - 呼び出しパラメータをリクエストに設定する


全ての呼び出しパラメータを取得する

  • ≪ Yaf_Request_Abstract::getParam
  • Yaf_Request_Abstract::getRequestUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • 全ての呼び出しパラメータを取得する

Yaf_Request_Abstract::getParams

(Yaf >=1.0.0)

Yaf_Request_Abstract::getParams — 全ての呼び出しパラメータを取得する

説明

public Yaf_Request_Abstract::getParams(): array

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Request_Abstract::setParam() - 呼び出しパラメータをリクエストに設定する


The getRequestUri purpose

  • ≪ Yaf_Request_Abstract::getParams
  • Yaf_Request_Abstract::getServer ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The getRequestUri purpose

Yaf_Request_Abstract::getRequestUri

(Yaf >=1.0.0)

Yaf_Request_Abstract::getRequestUri — The getRequestUri purpose

説明

public Yaf_Request_Abstract::getRequestUri(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


SERVER 変数を取得する

  • ≪ Yaf_Request_Abstract::getRequestUri
  • Yaf_Request_Abstract::isCli ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • SERVER 変数を取得する

Yaf_Request_Abstract::getServer

(Yaf >=1.0.0)

Yaf_Request_Abstract::getServer — SERVER 変数を取得する

説明

public Yaf_Request_Abstract::getServer(string $name, string $default = ?): void

SERVER 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

戻り値

参考

  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getEnv() - ENV 変数を取得する


CLIリクエストかを判定する

  • ≪ Yaf_Request_Abstract::getServer
  • Yaf_Request_Abstract::isDispatched ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • CLIリクエストかを判定する

Yaf_Request_Abstract::isCli

(Yaf >=1.0.0)

Yaf_Request_Abstract::isCli — CLIリクエストかを判定する

説明

public Yaf_Request_Abstract::isCli(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


リクエストがディスパッチ済みかを判定する

  • ≪ Yaf_Request_Abstract::isCli
  • Yaf_Request_Abstract::isGet ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • リクエストがディスパッチ済みかを判定する

Yaf_Request_Abstract::isDispatched

(Yaf >=1.0.0)

Yaf_Request_Abstract::isDispatched — リクエストがディスパッチ済みかを判定する

説明

public Yaf_Request_Abstract::isDispatched(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Dispatcher::dispatch() - リクエストをディスパッチする


GETリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isDispatched
  • Yaf_Request_Abstract::isHead ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • GETリクエストかどうかを判定する

Yaf_Request_Abstract::isGet

(Yaf >=1.0.0)

Yaf_Request_Abstract::isGet — GETリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isGet(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


HEADリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isGet
  • Yaf_Request_Abstract::isOptions ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • HEADリクエストかどうかを判定する

Yaf_Request_Abstract::isHead

(Yaf >=1.0.0)

Yaf_Request_Abstract::isHead — HEADリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isHead(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


OPTIONS リクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isHead
  • Yaf_Request_Abstract::isPost ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • OPTIONS リクエストかどうかを判定する

Yaf_Request_Abstract::isOptions

(Yaf >=1.0.0)

Yaf_Request_Abstract::isOptions — OPTIONS リクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isOptions(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。


POST リクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isOptions
  • Yaf_Request_Abstract::isPut ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • POST リクエストかどうかを判定する

Yaf_Request_Abstract::isPost

(Yaf >=1.0.0)

Yaf_Request_Abstract::isPost — POST リクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isPost(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


PUTリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isPost
  • Yaf_Request_Abstract::isRouted ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • PUTリクエストかどうかを判定する

Yaf_Request_Abstract::isPut

(Yaf >=1.0.0)

Yaf_Request_Abstract::isPut — PUTリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isPut(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する


リクエストがルーティング済みかを判定する

  • ≪ Yaf_Request_Abstract::isPut
  • Yaf_Request_Abstract::isXmlHttpRequest ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • リクエストがルーティング済みかを判定する

Yaf_Request_Abstract::isRouted

(Yaf >=1.0.0)

Yaf_Request_Abstract::isRouted — リクエストがルーティング済みかを判定する

説明

public Yaf_Request_Abstract::isRouted(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。


AJAXリクエストかどうかを判定する

  • ≪ Yaf_Request_Abstract::isRouted
  • Yaf_Request_Abstract::setActionName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • AJAXリクエストかどうかを判定する

Yaf_Request_Abstract::isXmlHttpRequest

(Yaf >=1.0.0)

Yaf_Request_Abstract::isXmlHttpRequest — AJAXリクエストかどうかを判定する

説明

public Yaf_Request_Abstract::isXmlHttpRequest(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

boolean を返します。

参考

  • Yaf_Request_Abstract::isHead() - HEADリクエストかどうかを判定する
  • Yaf_Request_Abstract::isCli() - CLIリクエストかを判定する
  • Yaf_Request_Abstract::isPost() - POST リクエストかどうかを判定する
  • Yaf_Request_Abstract::isPut() - PUTリクエストかどうかを判定する
  • Yaf_Request_Abstract::isOptions() - OPTIONS リクエストかどうかを判定する
  • Yaf_Request_Abstract::isGet() - GETリクエストかどうかを判定する


アクション名を設定する

  • ≪ Yaf_Request_Abstract::isXmlHttpRequest
  • Yaf_Request_Abstract::setBaseUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • アクション名を設定する

Yaf_Request_Abstract::setActionName

(Yaf >=1.0.0)

Yaf_Request_Abstract::setActionName — アクション名を設定する

説明

public Yaf_Request_Abstract::setActionName(string $action, bool $format_name = true): void

アクション名をリクエストに設定します。 このメソッドは通常、ルーティング結果のコントローラー名を設定するカスタムルータで使います。

パラメータ

action

アクション名を表すstring。 "index" や "foo_Bar" のように、小文字で表記すべきです。

format_name

Yaf 3.2.0 で追加されました。 デフォルトでは、Yaf は名前を小文字に変換しますが、 このパラメータを false に設定すると、指定された値そのままをリクエストに使います。

戻り値


ベース URI を設定する

  • ≪ Yaf_Request_Abstract::setActionName
  • Yaf_Request_Abstract::setControllerName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • ベース URI を設定する

Yaf_Request_Abstract::setBaseUri

(Yaf >=1.0.0)

Yaf_Request_Abstract::setBaseUri — ベース URI を設定する

説明

public Yaf_Request_Abstract::setBaseUri(string $uir): bool

ベース URI を設定します。ベース URI はルーティング時に使います。 ルーティングの際にはリクエスト URI を使ってリクエストを振り分けますが、 そのときに、ベース URI を使ってリクエスト URI の先頭部分を読み飛ばします。 たとえば、リクエスト URI が a/b/c でベース URI が "a/b" の場合、"/c" の部分だけを使ってルーティングします。

注意:

普通はこれを設定する必要はありません。Yaf が自動的に判断します。

パラメータ

uir

ベース URI。

戻り値

bool


コントローラー名を設定する

  • ≪ Yaf_Request_Abstract::setBaseUri
  • Yaf_Request_Abstract::setDispatched ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • コントローラー名を設定する

Yaf_Request_Abstract::setControllerName

(Yaf >=1.0.0)

Yaf_Request_Abstract::setControllerName — コントローラー名を設定する

説明

public Yaf_Request_Abstract::setControllerName(string $controller, bool $format_name = true): void

コントローラー名をリクエストに設定します。 このメソッドは通常、ルーティング結果のコントローラー名を設定するカスタムルータで使います。

パラメータ

controller

コントローラー名を表す string。 "Index" や "Foo_Bar" のように、キャメルケースで表記すべきです。

format_name

Yaf 3.2.0 で追加されました。 デフォルトでは、Yaf は名前をキャメルケースでフォーマットしますが、 このパラメータを false に設定すると、指定された値そのままをリクエストに使います。

戻り値


The setDispatched purpose

  • ≪ Yaf_Request_Abstract::setControllerName
  • Yaf_Request_Abstract::setModuleName ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The setDispatched purpose

Yaf_Request_Abstract::setDispatched

(Yaf >=1.0.0)

Yaf_Request_Abstract::setDispatched — The setDispatched purpose

説明

public Yaf_Request_Abstract::setDispatched(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


モジュール名を設定する

  • ≪ Yaf_Request_Abstract::setDispatched
  • Yaf_Request_Abstract::setParam ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • モジュール名を設定する

Yaf_Request_Abstract::setModuleName

(Yaf >=1.0.0)

Yaf_Request_Abstract::setModuleName — モジュール名を設定する

説明

public Yaf_Request_Abstract::setModuleName(string $module, bool $format_name = true): void

リクエストするモジュール名を設定します。 このメソッドは通常、ルーティング結果のモジュール名を設定するカスタムルータで使います。

パラメータ

module

モジュール名を表すstring。 "Index" や "Foo_Bar" のように、キャメルケースで表記すべきです。

format_name

Yaf 3.2.0 で追加されました。 デフォルトでは、Yaf は名前をキャメルケースでフォーマットしますが、 このパラメータを false に設定すると、指定された値そのままをリクエストに使います。

戻り値


呼び出しパラメータをリクエストに設定する

  • ≪ Yaf_Request_Abstract::setModuleName
  • Yaf_Request_Abstract::setRequestUri ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • 呼び出しパラメータをリクエストに設定する

Yaf_Request_Abstract::setParam

(Yaf >=1.0.0)

Yaf_Request_Abstract::setParam — 呼び出しパラメータをリクエストに設定する

説明

public Yaf_Request_Abstract::setParam(string $name, string $value = ?): bool

パラメータをリクエストに設定します。 設定した値は、Yaf_Request_Abstract::getParam() で取得できます

パラメータ

name

value

戻り値

参考

  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する
  • Yaf_Request_Abstract::getParams() - 全ての呼び出しパラメータを取得する


The setRequestUri purpose

  • ≪ Yaf_Request_Abstract::setParam
  • Yaf_Request_Abstract::setRouted ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The setRequestUri purpose

Yaf_Request_Abstract::setRequestUri

(Yaf >=2.1.0)

Yaf_Request_Abstract::setRequestUri — The setRequestUri purpose

説明

public Yaf_Request_Abstract::setRequestUri(string $uir): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

uir

戻り値


The setRouted purpose

  • ≪ Yaf_Request_Abstract::setRequestUri
  • Yaf_Request_Http ≫
  • PHP Manual
  • Yaf_Request_Abstract
  • The setRouted purpose

Yaf_Request_Abstract::setRouted

(Yaf >=1.0.0)

Yaf_Request_Abstract::setRouted — The setRouted purpose

説明

public Yaf_Request_Abstract::setRouted(string $flag = ?): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flag

戻り値


Yaf_Request_Http クラス

(Yaf >=1.0.0)

はじめに

クライアントからのあらゆるリクエストは、 Yaf_Request_Http として初期化されます。 URI のクエリ文字列や POST パラメータなどの情報は、このクラスのメソッド経由で取得できます。

注意:

セキュリティの観点から、Yaf では $_GET/$_POST が読み込み専用となっています。つまり、 これらのグローバル変数の値を書き換えたとしても、 Yaf_Request_Http::getQuery() や Yaf_Request_Http::getPost() からはそれを取得できないということです。

しかし、ユニットテストの際などに、どうしても書き換えが必要になることもあります。 Yaf のビルド時に --enable-yaf-debug を指定すると、ユーザーがスクリプトで設定した値も Yaf で読み込めるようになります。

その際に、Yaf は E_STRICT レベルの警告 「Strict Standards: you are running yaf in debug mode」を発します。

クラス概要

class Yaf_Request_Http extends Yaf_Request_Abstract {
/* プロパティ */
/* メソッド */
public __construct(string $request_uri = ?, string $base_uri = ?)
public get(string $name, string $default = ?): mixed
public getCookie(string $name, string $default = ?): mixed
public getFiles(): void
public getPost(string $name, string $default = ?): mixed
public getQuery(string $name, string $default = ?): mixed
public getRaw(): mixed
public getRequest(): void
public isXmlHttpRequest(): bool
/* 継承したメソッド */
public Yaf_Request_Abstract::clearParams(): bool
public Yaf_Request_Abstract::getActionName(): void
public Yaf_Request_Abstract::getBaseUri(): void
public Yaf_Request_Abstract::getControllerName(): void
public Yaf_Request_Abstract::getEnv(string $name, string $default = ?): void
public Yaf_Request_Abstract::getException(): void
public Yaf_Request_Abstract::getLanguage(): void
public Yaf_Request_Abstract::getMethod(): string
public Yaf_Request_Abstract::getModuleName(): void
public Yaf_Request_Abstract::getParam(string $name, string $default = ?): mixed
public Yaf_Request_Abstract::getParams(): array
public Yaf_Request_Abstract::getRequestUri(): void
public Yaf_Request_Abstract::getServer(string $name, string $default = ?): void
public Yaf_Request_Abstract::isCli(): bool
public Yaf_Request_Abstract::isDispatched(): bool
public Yaf_Request_Abstract::isGet(): bool
public Yaf_Request_Abstract::isHead(): bool
public Yaf_Request_Abstract::isOptions(): bool
public Yaf_Request_Abstract::isPost(): bool
public Yaf_Request_Abstract::isPut(): bool
public Yaf_Request_Abstract::isRouted(): bool
public Yaf_Request_Abstract::isXmlHttpRequest(): bool
public Yaf_Request_Abstract::setActionName(string $action, bool $format_name = true): void
public Yaf_Request_Abstract::setBaseUri(string $uir): bool
public Yaf_Request_Abstract::setControllerName(string $controller, bool $format_name = true): void
public Yaf_Request_Abstract::setDispatched(): void
public Yaf_Request_Abstract::setModuleName(string $module, bool $format_name = true): void
public Yaf_Request_Abstract::setParam(string $name, string $value = ?): bool
public Yaf_Request_Abstract::setRequestUri(string $uir): void
public Yaf_Request_Abstract::setRouted(string $flag = ?): void
}

プロパティ

module

controller

action

method

params

language

_exception

_base_uri

uri

dispatched

routed

目次

  • Yaf_Request_Http::__construct — Yaf_Request_Http のコンストラクタ
  • Yaf_Request_Http::get — クライアントからの変数を取得する
  • Yaf_Request_Http::getCookie — Cookie 変数を取得する
  • Yaf_Request_Http::getFiles — The getFiles purpose
  • Yaf_Request_Http::getPost — POST 変数を取得する
  • Yaf_Request_Http::getQuery — クエリパラメータを取得する
  • Yaf_Request_Http::getRaw — 生のリクエストボディを取得する
  • Yaf_Request_Http::getRequest — The getRequest purpose
  • Yaf_Request_Http::isXmlHttpRequest — リクエストが Ajax リクエストかどうかを判断する


Yaf_Request_Http のコンストラクタ

  • ≪ Yaf_Request_Http
  • Yaf_Request_Http::get ≫
  • PHP Manual
  • Yaf_Request_Http
  • Yaf_Request_Http のコンストラクタ

Yaf_Request_Http::__construct

(Yaf >=1.0.0)

Yaf_Request_Http::__construct — Yaf_Request_Http のコンストラクタ

説明

public Yaf_Request_Http::__construct(string $request_uri = ?, string $base_uri = ?)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


クライアントからの変数を取得する

  • ≪ Yaf_Request_Http::__construct
  • Yaf_Request_Http::getCookie ≫
  • PHP Manual
  • Yaf_Request_Http
  • クライアントからの変数を取得する

Yaf_Request_Http::get

(Yaf >=1.0.0)

Yaf_Request_Http::get — クライアントからの変数を取得する

説明

public Yaf_Request_Http::get(string $name, string $default = ?): mixed

クライアントからの変数を取得します。このメソッドは、まずリクエストのパラメータから name を探し、見つからない場合は POST、GET、Cookie、Server を調べます。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

戻り値

参考

  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する


Cookie 変数を取得する

  • ≪ Yaf_Request_Http::get
  • Yaf_Request_Http::getFiles ≫
  • PHP Manual
  • Yaf_Request_Http
  • Cookie 変数を取得する

Yaf_Request_Http::getCookie

(Yaf >=1.0.0)

Yaf_Request_Http::getCookie — Cookie 変数を取得する

説明

public Yaf_Request_Http::getCookie(string $name, string $default = ?): mixed

Cookie 変数を取得します。

パラメータ

name

クッキー名。

default

このパラメータを指定すると、クッキーが見つからない場合にこの値を返すようになります。

戻り値

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する


The getFiles purpose

  • ≪ Yaf_Request_Http::getCookie
  • Yaf_Request_Http::getPost ≫
  • PHP Manual
  • Yaf_Request_Http
  • The getFiles purpose

Yaf_Request_Http::getFiles

(Yaf >=1.0.0)

Yaf_Request_Http::getFiles — The getFiles purpose

説明

public Yaf_Request_Http::getFiles(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


POST 変数を取得する

  • ≪ Yaf_Request_Http::getFiles
  • Yaf_Request_Http::getQuery ≫
  • PHP Manual
  • Yaf_Request_Http
  • POST 変数を取得する

Yaf_Request_Http::getPost

(Yaf >=1.0.0)

Yaf_Request_Http::getPost — POST 変数を取得する

説明

public Yaf_Request_Http::getPost(string $name, string $default = ?): mixed

POST 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

戻り値

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する


クエリパラメータを取得する

  • ≪ Yaf_Request_Http::getPost
  • Yaf_Request_Http::getRaw ≫
  • PHP Manual
  • Yaf_Request_Http
  • クエリパラメータを取得する

Yaf_Request_Http::getQuery

(Yaf >=1.0.0)

Yaf_Request_Http::getQuery — クエリパラメータを取得する

説明

public Yaf_Request_Http::getQuery(string $name, string $default = ?): mixed

GET 変数を取得します。

パラメータ

name

変数名。

default

このパラメータを指定すると、変数が見つからない場合にこの値を返すようになります。

戻り値

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getRaw() - 生のリクエストボディを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する


生のリクエストボディを取得する

  • ≪ Yaf_Request_Http::getQuery
  • Yaf_Request_Http::getRequest ≫
  • PHP Manual
  • Yaf_Request_Http
  • 生のリクエストボディを取得する

Yaf_Request_Http::getRaw

(Yaf >=3.0.7)

Yaf_Request_Http::getRaw — 生のリクエストボディを取得する

説明

public Yaf_Request_Http::getRaw(): mixed

生のリクエストボディを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に文字列を、失敗した場合に FALSE を返します。

参考

  • Yaf_Request_Http::get() - クライアントからの変数を取得する
  • Yaf_Request_Http::getPost() - POST 変数を取得する
  • Yaf_Request_Http::getCookie() - Cookie 変数を取得する
  • Yaf_Request_Http::getQuery() - クエリパラメータを取得する
  • Yaf_Request_Abstract::getServer() - SERVER 変数を取得する
  • Yaf_Request_Abstract::getParam() - 呼び出しパラメータを取得する


The getRequest purpose

  • ≪ Yaf_Request_Http::getRaw
  • Yaf_Request_Http::isXmlHttpRequest ≫
  • PHP Manual
  • Yaf_Request_Http
  • The getRequest purpose

Yaf_Request_Http::getRequest

(Yaf >=1.0.0)

Yaf_Request_Http::getRequest — The getRequest purpose

説明

public Yaf_Request_Http::getRequest(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


リクエストが Ajax リクエストかどうかを判断する

  • ≪ Yaf_Request_Http::getRequest
  • Yaf_Request_Simple ≫
  • PHP Manual
  • Yaf_Request_Http
  • リクエストが Ajax リクエストかどうかを判断する

Yaf_Request_Http::isXmlHttpRequest

(Yaf >=1.0.0)

Yaf_Request_Http::isXmlHttpRequest — リクエストが Ajax リクエストかどうかを判断する

説明

public Yaf_Request_Http::isXmlHttpRequest(): bool

そのリクエストが Ajax リクエストであるかどうかを調べます。

注意:

このメソッドはリクエストヘッダーの HTTP_X_REQUESTED_WITH を見て判断しますが、 JavaScript ライブラリの中には、Ajax リクエストの際にこのヘッダーをセットしないものがあります。

パラメータ

この関数にはパラメータはありません。

戻り値

boolean


Yaf_Request_Simple クラス

(Yaf >=1.0.0)

はじめに

Yaf_Request_Simple は、 テスト用に使うためのクラスです。 つまり、特定のリクエストを CLI モードでシミュレートしたりするときに使います。

クラス概要

class Yaf_Request_Simple extends Yaf_Request_Abstract {
/* 定数 */
const string SCHEME_HTTP = http;
const string SCHEME_HTTPS = https;
/* プロパティ */
/* メソッド */
public __construct(
string $method = ?,
string $module = ?,
string $controller = ?,
string $action = ?,
array $params = ?
)
public get(): void
public getCookie(): void
public getFiles(): void
public getPost(): void
public getQuery(): void
public getRequest(): void
public isXmlHttpRequest(): void
/* 継承したメソッド */
public Yaf_Request_Abstract::clearParams(): bool
public Yaf_Request_Abstract::getActionName(): void
public Yaf_Request_Abstract::getBaseUri(): void
public Yaf_Request_Abstract::getControllerName(): void
public Yaf_Request_Abstract::getEnv(string $name, string $default = ?): void
public Yaf_Request_Abstract::getException(): void
public Yaf_Request_Abstract::getLanguage(): void
public Yaf_Request_Abstract::getMethod(): string
public Yaf_Request_Abstract::getModuleName(): void
public Yaf_Request_Abstract::getParam(string $name, string $default = ?): mixed
public Yaf_Request_Abstract::getParams(): array
public Yaf_Request_Abstract::getRequestUri(): void
public Yaf_Request_Abstract::getServer(string $name, string $default = ?): void
public Yaf_Request_Abstract::isCli(): bool
public Yaf_Request_Abstract::isDispatched(): bool
public Yaf_Request_Abstract::isGet(): bool
public Yaf_Request_Abstract::isHead(): bool
public Yaf_Request_Abstract::isOptions(): bool
public Yaf_Request_Abstract::isPost(): bool
public Yaf_Request_Abstract::isPut(): bool
public Yaf_Request_Abstract::isRouted(): bool
public Yaf_Request_Abstract::isXmlHttpRequest(): bool
public Yaf_Request_Abstract::setActionName(string $action, bool $format_name = true): void
public Yaf_Request_Abstract::setBaseUri(string $uir): bool
public Yaf_Request_Abstract::setControllerName(string $controller, bool $format_name = true): void
public Yaf_Request_Abstract::setDispatched(): void
public Yaf_Request_Abstract::setModuleName(string $module, bool $format_name = true): void
public Yaf_Request_Abstract::setParam(string $name, string $value = ?): bool
public Yaf_Request_Abstract::setRequestUri(string $uir): void
public Yaf_Request_Abstract::setRouted(string $flag = ?): void
}

プロパティ

module

controller

action

method

params

language

_exception

_base_uri

uri

dispatched

routed

定義済み定数

Yaf_Request_Simple::SCHEME_HTTP

Yaf_Request_Simple::SCHEME_HTTPS

目次

  • Yaf_Request_Simple::__construct — Yaf_Request_Simple のコンストラクタ
  • Yaf_Request_Simple::get — The get purpose
  • Yaf_Request_Simple::getCookie — The getCookie purpose
  • Yaf_Request_Simple::getFiles — The getFiles purpose
  • Yaf_Request_Simple::getPost — The getPost purpose
  • Yaf_Request_Simple::getQuery — The getQuery purpose
  • Yaf_Request_Simple::getRequest — The getRequest purpose
  • Yaf_Request_Simple::isXmlHttpRequest — リクエストが AJAX 経由のリクエストかどうかを判定する


Yaf_Request_Simple のコンストラクタ

  • ≪ Yaf_Request_Simple
  • Yaf_Request_Simple::get ≫
  • PHP Manual
  • Yaf_Request_Simple
  • Yaf_Request_Simple のコンストラクタ

Yaf_Request_Simple::__construct

(Yaf >=1.0.0)

Yaf_Request_Simple::__construct — Yaf_Request_Simple のコンストラクタ

説明

public Yaf_Request_Simple::__construct(
string $method = ?,
string $module = ?,
string $controller = ?,
string $action = ?,
array $params = ?
)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The get purpose

  • ≪ Yaf_Request_Simple::__construct
  • Yaf_Request_Simple::getCookie ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The get purpose

Yaf_Request_Simple::get

(Yaf >=1.0.0)

Yaf_Request_Simple::get — The get purpose

説明

public Yaf_Request_Simple::get(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getCookie purpose

  • ≪ Yaf_Request_Simple::get
  • Yaf_Request_Simple::getFiles ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getCookie purpose

Yaf_Request_Simple::getCookie

(Yaf >=1.0.0)

Yaf_Request_Simple::getCookie — The getCookie purpose

説明

public Yaf_Request_Simple::getCookie(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getFiles purpose

  • ≪ Yaf_Request_Simple::getCookie
  • Yaf_Request_Simple::getPost ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getFiles purpose

Yaf_Request_Simple::getFiles

(Yaf >=1.0.0)

Yaf_Request_Simple::getFiles — The getFiles purpose

説明

public Yaf_Request_Simple::getFiles(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getPost purpose

  • ≪ Yaf_Request_Simple::getFiles
  • Yaf_Request_Simple::getQuery ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getPost purpose

Yaf_Request_Simple::getPost

(Yaf >=1.0.0)

Yaf_Request_Simple::getPost — The getPost purpose

説明

public Yaf_Request_Simple::getPost(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getQuery purpose

  • ≪ Yaf_Request_Simple::getPost
  • Yaf_Request_Simple::getRequest ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getQuery purpose

Yaf_Request_Simple::getQuery

(Yaf >=1.0.0)

Yaf_Request_Simple::getQuery — The getQuery purpose

説明

public Yaf_Request_Simple::getQuery(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getRequest purpose

  • ≪ Yaf_Request_Simple::getQuery
  • Yaf_Request_Simple::isXmlHttpRequest ≫
  • PHP Manual
  • Yaf_Request_Simple
  • The getRequest purpose

Yaf_Request_Simple::getRequest

(Yaf >=1.0.0)

Yaf_Request_Simple::getRequest — The getRequest purpose

説明

public Yaf_Request_Simple::getRequest(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


リクエストが AJAX 経由のリクエストかどうかを判定する

  • ≪ Yaf_Request_Simple::getRequest
  • Yaf_Response_Abstract ≫
  • PHP Manual
  • Yaf_Request_Simple
  • リクエストが AJAX 経由のリクエストかどうかを判定する

Yaf_Request_Simple::isXmlHttpRequest

(Yaf >=1.0.0)

Yaf_Request_Simple::isXmlHttpRequest — リクエストが AJAX 経由のリクエストかどうかを判定する

説明

public Yaf_Request_Simple::isXmlHttpRequest(): void

パラメータ

この関数にはパラメータはありません。

戻り値

常に false を返します。

参考

  • Yaf_Request_Abstract::isXmlHTTPRequest() - AJAXリクエストかどうかを判定する
  • Yaf_Request_Http::isXmlHTTPRequest() - リクエストが Ajax リクエストかどうかを判断する


Yaf_Response_Abstract クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Response_Abstract {
/* 定数 */
const string DEFAULT_BODY = "content";
/* プロパティ */
protected $_header;
protected $_body;
protected $_sendheader;
/* メソッド */
public __construct()
public appendBody(string $content, string $key = ?): bool
public clearBody(string $key = ?): bool
public clearHeaders(): void
public getBody(string $key = ?): mixed
public getHeader(): void
public prependBody(string $content, string $key = ?): bool
public response(): void
protected setAllHeaders(): void
public setBody(string $content, string $key = ?): bool
public setHeader(string $name, string $value, bool $replace = ?): bool
public setRedirect(string $url): bool
private __toString(): string
public __destruct()
}

プロパティ

_header

_body

_sendheader

目次

  • Yaf_Response_Abstract::appendBody — レスポンス本文に追記する
  • Yaf_Response_Abstract::clearBody — 既存のすべてのレスポンス本文を破棄します
  • Yaf_Response_Abstract::clearHeaders — すべてのヘッダをクリアする
  • Yaf_Response_Abstract::__construct — The __construct purpose
  • Yaf_Response_Abstract::__destruct — The __destruct purpose
  • Yaf_Response_Abstract::getBody — コンテンツを取得する
  • Yaf_Response_Abstract::getHeader — getHeader の目的
  • Yaf_Response_Abstract::prependBody — The prependBody purpose
  • Yaf_Response_Abstract::response — レスポンスを送信する
  • Yaf_Response_Abstract::setAllHeaders — The setAllHeaders purpose
  • Yaf_Response_Abstract::setBody — コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::setHeader — レスポンスヘッダを設定する
  • Yaf_Response_Abstract::setRedirect — The setRedirect purpose
  • Yaf_Response_Abstract::__toString — すべてのレスポンスボディを文字列として取得する


レスポンス本文に追記する

  • ≪ Yaf_Response_Abstract
  • Yaf_Response_Abstract::clearBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • レスポンス本文に追記する

Yaf_Response_Abstract::appendBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::appendBody — レスポンス本文に追記する

説明

public Yaf_Response_Abstract::appendBody(string $content, string $key = ?): bool

既存のコンテンツブロックの後にコンテンツを追加します。

パラメータ

body

コンテンツ文字列。

key

コンテンツのキー。キーを指定しない場合は、 Yaf_Response_Abstract::DEFAULT_BODY を使います。

注意:

このパラメータは 2.2.0 で導入されました。

戻り値

bool

例

例1 Yaf_Response_Abstract::appendBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->prependBody(" World");

echo $response;
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

参考

  • Yaf_Config_Ini
  • Yaf_Response_Abstract::getBody() - コンテンツを取得する
  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します


既存のすべてのレスポンス本文を破棄します

  • ≪ Yaf_Response_Abstract::appendBody
  • Yaf_Response_Abstract::clearHeaders ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • 既存のすべてのレスポンス本文を破棄します

Yaf_Response_Abstract::clearBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::clearBody — 既存のすべてのレスポンス本文を破棄します

説明

public Yaf_Response_Abstract::clearBody(string $key = ?): bool

既存のコンテンツを消去します。

パラメータ

key

コンテンツのキー。キーを指定しない場合は、すべてのコンテンツを消去します。

注意:

このパラメータは 2.2.0 で導入されました。

戻り値

参考

  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::getBody() - コンテンツを取得する


すべてのヘッダをクリアする

  • ≪ Yaf_Response_Abstract::clearBody
  • Yaf_Response_Abstract::__construct ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • すべてのヘッダをクリアする

Yaf_Response_Abstract::clearHeaders

(Yaf >=1.0.0)

Yaf_Response_Abstract::clearHeaders — すべてのヘッダをクリアする

説明

public Yaf_Response_Abstract::clearHeaders(): void

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Response_Abstract::getHeader() - getHeader の目的
  • Yaf_Response_Abstract::setHeader() - レスポンスヘッダを設定する


The __construct purpose

  • ≪ Yaf_Response_Abstract::clearHeaders
  • Yaf_Response_Abstract::__destruct ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The __construct purpose

Yaf_Response_Abstract::__construct

(Yaf >=1.0.0)

Yaf_Response_Abstract::__construct — The __construct purpose

説明

public Yaf_Response_Abstract::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __destruct purpose

  • ≪ Yaf_Response_Abstract::__construct
  • Yaf_Response_Abstract::getBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The __destruct purpose

Yaf_Response_Abstract::__destruct

(Yaf >=1.0.0)

Yaf_Response_Abstract::__destruct — The __destruct purpose

説明

public Yaf_Response_Abstract::__destruct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


コンテンツを取得する

  • ≪ Yaf_Response_Abstract::__destruct
  • Yaf_Response_Abstract::getHeader ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • コンテンツを取得する

Yaf_Response_Abstract::getBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::getBody — コンテンツを取得する

説明

public Yaf_Response_Abstract::getBody(string $key = ?): mixed

コンテンツを取得します。

パラメータ

key

コンテンツのキー。キーを指定しない場合は、Yaf_Response_Abstract::DEFAULT_BODY を使います。null を渡すと、すべてのコンテンツを配列で返します。 as a array

注意:

このパラメータは 2.2.0 で導入されました。

戻り値

例

例1 Yaf_Response_Abstract::getBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->setBody(" World", "footer");

var_dump($response->getBody()); // デフォルト
var_dump($response->getBody(Yaf_Response_Abstract::DEFAULT_BODY)); // 上の行と同じ
var_dump($response->getBody("footer"));
var_dump($response->getBody(NULL)); // すべてを取得
?>

上の例の出力は、 たとえば以下のようになります。

string(5) "Hello"
string(5) "Hello"
string(6) " World"
array(2) {
  ["content"]=>
  string(5) "Hello"
  ["footer"]=>
  string(6) " World"
}

参考

  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します


getHeader の目的

  • ≪ Yaf_Response_Abstract::getBody
  • Yaf_Response_Abstract::prependBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • getHeader の目的

Yaf_Response_Abstract::getHeader

(Yaf >=1.0.0)

Yaf_Response_Abstract::getHeader — getHeader の目的

説明

public Yaf_Response_Abstract::getHeader(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Response_Abstract::setHeader() - レスポンスヘッダを設定する
  • Yaf_Response_Abstract::cleanHeaders()


The prependBody purpose

  • ≪ Yaf_Response_Abstract::getHeader
  • Yaf_Response_Abstract::response ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The prependBody purpose

Yaf_Response_Abstract::prependBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::prependBody — The prependBody purpose

説明

public Yaf_Response_Abstract::prependBody(string $content, string $key = ?): bool

既存のコンテンツブロックの前にコンテンツを追加します。

パラメータ

body

コンテンツ文字列。

key

コンテンツのキー。キーを指定しない場合は、 Yaf_Response_Abstract::DEFAULT_BODY を使います。

注意:

このパラメータは 2.2.0 で導入されました。

戻り値

bool

例

例1 Yaf_Response_Abstract::prependBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("World")->prependBody("Hello ");

echo $response;
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

参考

  • Yaf_Response_Abstract::getBody() - コンテンツを取得する
  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します


レスポンスを送信する

  • ≪ Yaf_Response_Abstract::prependBody
  • Yaf_Response_Abstract::setAllHeaders ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • レスポンスを送信する

Yaf_Response_Abstract::response

(Yaf >=1.0.0)

Yaf_Response_Abstract::response — レスポンスを送信する

説明

public Yaf_Response_Abstract::response(): void

レスポンスを送信します。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Response_Abstract::response() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->setBody(" World", "footer");

$response->response();
?>

上の例の出力は、 たとえば以下のようになります。

Hello World

参考

  • Yaf_Response_Abstract::setBody() - コンテンツをレスポンスに設定する
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します


The setAllHeaders purpose

  • ≪ Yaf_Response_Abstract::response
  • Yaf_Response_Abstract::setBody ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The setAllHeaders purpose

Yaf_Response_Abstract::setAllHeaders

(Yaf >=1.0.0)

Yaf_Response_Abstract::setAllHeaders — The setAllHeaders purpose

説明

protected Yaf_Response_Abstract::setAllHeaders(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


コンテンツをレスポンスに設定する

  • ≪ Yaf_Response_Abstract::setAllHeaders
  • Yaf_Response_Abstract::setHeader ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • コンテンツをレスポンスに設定する

Yaf_Response_Abstract::setBody

(Yaf >=1.0.0)

Yaf_Response_Abstract::setBody — コンテンツをレスポンスに設定する

説明

public Yaf_Response_Abstract::setBody(string $content, string $key = ?): bool

コンテンツをレスポンスに設定します。

パラメータ

body

コンテンツ文字列。

key

コンテンツのキー。キーを指定しない場合は、 Yaf_Response_Abstract::DEFAULT_BODY を使います。

注意:

このパラメータは 2.2.0 で導入されました。

戻り値

例

例1 Yaf_Response_Abstract::setBody() の例

<?php
$response = new Yaf_Response_Http();

$response->setBody("Hello")->setBody(" World", "footer");

print_r($response);
echo $response;
?>

上の例の出力は、 たとえば以下のようになります。

Yaf_Response_Http Object
(
    [_header:protected] => Array
        (
        )

    [_body:protected] => Array
        (
            [content] => Hello
            [footer] =>  World
        )

    [_sendheader:protected] => 1
    [_response_code:protected] => 200
)
Hello World

参考

  • Yaf_Response_Abstract::getBody() - コンテンツを取得する
  • Yaf_Response_Abstract::appendBody() - レスポンス本文に追記する
  • Yaf_Response_Abstract::prependBody() - The prependBody purpose
  • Yaf_Response_Abstract::clearBody() - 既存のすべてのレスポンス本文を破棄します


レスポンスヘッダを設定する

  • ≪ Yaf_Response_Abstract::setBody
  • Yaf_Response_Abstract::setRedirect ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • レスポンスヘッダを設定する

Yaf_Response_Abstract::setHeader

(Yaf >=1.0.0)

Yaf_Response_Abstract::setHeader — レスポンスヘッダを設定する

説明

public Yaf_Response_Abstract::setHeader(string $name, string $value, bool $replace = ?): bool

HTTPヘッダを送信するのに使います。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Response_Abstract::getHeader() - getHeader の目的
  • Yaf_Response_Abstract::cleanHeaders()


The setRedirect purpose

  • ≪ Yaf_Response_Abstract::setHeader
  • Yaf_Response_Abstract::__toString ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • The setRedirect purpose

Yaf_Response_Abstract::setRedirect

(Yaf >=1.0.0)

Yaf_Response_Abstract::setRedirect — The setRedirect purpose

説明

public Yaf_Response_Abstract::setRedirect(string $url): bool

パラメータ

url

リダイレクト先のアドレス。

戻り値


すべてのレスポンスボディを文字列として取得する

  • ≪ Yaf_Response_Abstract::setRedirect
  • Yaf_Route_Interface ≫
  • PHP Manual
  • Yaf_Response_Abstract
  • すべてのレスポンスボディを文字列として取得する

Yaf_Response_Abstract::__toString

(Yaf >=1.0.0)

Yaf_Response_Abstract::__toString — すべてのレスポンスボディを文字列として取得する

説明

private Yaf_Response_Abstract::__toString(): string

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Route_Interface クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Interface を使うと、開発者がカスタムルートを定義できるようになります。

クラス概要

class Yaf_Route_Interface {
/* メソッド */
abstract public assemble(array $info, array $query = ?): string
abstract public route(Yaf_Request_Abstract $request): bool
}

目次

  • Yaf_Route_Interface::assemble — リクエストを組み立てる
  • Yaf_Route_Interface::route — リクエストをルーティングする


リクエストを組み立てる

  • ≪ Yaf_Route_Interface
  • Yaf_Route_Interface::route ≫
  • PHP Manual
  • Yaf_Route_Interface
  • リクエストを組み立てる

Yaf_Route_Interface::assemble

(Yaf >=2.3.0)

Yaf_Route_Interface::assemble — リクエストを組み立てる

説明

abstract public Yaf_Route_Interface::assemble(array $info, array $query = ?): string

このメソッドは引数 info に対応するURLを返します。 そして、引数 query によってURLにクエリストリングを追加します。

Route は自分のルーティングのルールに基づいてこのメソッドを実装すべきですし、 逆の処理も行うべきです。

パラメータ

info

query

戻り値


リクエストをルーティングする

  • ≪ Yaf_Route_Interface::assemble
  • Yaf_Route_Map ≫
  • PHP Manual
  • Yaf_Route_Interface
  • リクエストをルーティングする

Yaf_Route_Interface::route

(Yaf >=1.0.0)

Yaf_Route_Interface::route — リクエストをルーティングする

説明

abstract public Yaf_Route_Interface::route(Yaf_Request_Abstract $request): bool

Yaf_Route_Interface::route() は、ルーターを自作するときに唯一実装する必要のあるメソッドです。

注意:

2.3.0 以降では、実装すべきメソッドがひとつ増えました。 Yaf_Route_Interface::assemble() を参照ください。

このメソッドが true を返せば、そこでルーティングが終わります。それ以外の場合は Yaf_Router はルートスタックの次のルーターにリクエストを転送します。

このメソッドは、
Yaf_Request_Abstract::setControllerName()、
Yaf_Request_Abstract::setActionName() および
Yaf_Request_Abstract::setModuleName() を使って
ルーティング結果を request に設定します。

リクエストをルーティングしたことを示すため、このメソッドは最後に Yaf_Request_Abstract::setRouted() を呼ぶ必要があります。

パラメータ

request

Yaf_Request_Abstract のインスタンスを返します。

戻り値


Yaf_Route_Map クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Map は標準で組み込まれているルートです。 単純に URI エンドポイント (URI の中で、ベース URL の後に続く部分。 Yaf_Request_Abstract::setBaseUri() を参照ください) をコントローラ名やアクション名に変換します (どちらになるかは Yaf_Route_Map::__construct() に渡すパラメータで決まります)。 その規則は次のとおりです。 A => controller A. A/B/C => controller A_B_C. A/B/C/D/E => controller A_B_C_D_E.

Yaf_Route_Map::__construct() の二番目のパラメータを指定すると、 URI の中でデリミタより前の部分だけを使ってルーティングを行います。 デリミタ以降の部分は、ルーティングリクエストのパラメータとして使います (Yaf_Route_Map::__construct() のサンプルを参照ください)。

クラス概要

class Yaf_Route_Map implements Yaf_Route_Interface {
/* プロパティ */
protected $_ctl_router;
protected $_delimiter;
/* メソッド */
public __construct(string $controller_prefer = false, string $delimiter = "")
public assemble(array $info, array $query = ?): string
public route(Yaf_Request_Abstract $request): bool
}

プロパティ

_ctl_router

_delimiter

目次

  • Yaf_Route_Map::assemble — URLを組み立てる
  • Yaf_Route_Map::__construct — The __construct purpose
  • Yaf_Route_Map::route — route の目的


URLを組み立てる

  • ≪ Yaf_Route_Map
  • Yaf_Route_Map::__construct ≫
  • PHP Manual
  • Yaf_Route_Map
  • URLを組み立てる

Yaf_Route_Map::assemble

(Yaf >=2.3.0)

Yaf_Route_Map::assemble — URLを組み立てる

説明

public Yaf_Route_Map::assemble(array $info, array $query = ?): string

URLを組み立てます。

パラメータ

info

query

戻り値

成功時に文字列を、 失敗時に null を返します。

エラー / 例外

Yaf_Exception_TypeError をスローする可能性があります。

例

例1 Yaf_Route_Map::assemble() の例

<?php

$router = new Yaf_Router();

$route = new Yaf_Route_Map();

$router->addRoute("map", $route);

var_dump($router->getRoute('map')->assemble(
array(
':c' => 'foo_bar'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2'
)
)
);

$route = new Yaf_Route_Map(true, '_');
$router->addRoute("map", $route);

var_dump($router->getRoute('map')->assemble(
array(
':a' => 'foo_bar'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2'
)
)
);

上の例の出力は、 たとえば以下のようになります。

string(%d) "/foo/bar?tkey1=tval1&tkey2=tval2"
string(%d) "/foo/bar/_/tkey1/tval1/tkey2/tval2"


The __construct purpose

  • ≪ Yaf_Route_Map::assemble
  • Yaf_Route_Map::route ≫
  • PHP Manual
  • Yaf_Route_Map
  • The __construct purpose

Yaf_Route_Map::__construct

(Yaf >=1.0.0)

Yaf_Route_Map::__construct — The __construct purpose

説明

public Yaf_Route_Map::__construct(string $controller_prefer = false, string $delimiter = "")

パラメータ

controller_prefer

結果をコントローラとみなすかアクションとみなすか。

delimiter

戻り値

例

例1 Yaf_Route_Map() の例

<?php
/**
* Add a map route to Yaf_Router route stack
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
new Yaf_Route_Map());
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/product/foo/bar
 * の場合はこのような結果になります
 */
array(
  "controller" => "product_foo_bar",
)

例2 Yaf_Route_Map() の例

<?php
/**
* Add a map route to Yaf_Router route stack
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
new Yaf_Route_Map(true, "_"));
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/user/list/_/foo/22
 * の場合はこのような結果になります
 */
array(
    "action" => "user_list",
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "foo"   => 22,
)

例3 Yaf_Route_Map() の例

<?php
/**
* Add a map route to Yaf_Router route stack by calling addconfig
*/
$config = array(
"name" => array(
"type" => "map", //Yaf_Route_Map route
"controllerPrefer" => FALSE,
"delimiter" => "#!",
),
);
Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
new Yaf_Config_Simple($config));
?>

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Rewrite


route の目的

  • ≪ Yaf_Route_Map::__construct
  • Yaf_Route_Regex ≫
  • PHP Manual
  • Yaf_Route_Map
  • route の目的

Yaf_Route_Map::route

(Yaf >=1.0.0)

Yaf_Route_Map::route — route の目的

説明

public Yaf_Route_Map::route(Yaf_Request_Abstract $request): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

戻り値


Yaf_Route_Regex クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Regex は、 Yaf の組み込みのルートのなかでも一番柔軟性の高いものです。

クラス概要

class Yaf_Route_Regex extends Yaf_Route_Interface implements Yaf_Route_Interface {
/* プロパティ */
protected $_route;
protected $_default;
protected $_maps;
protected $_verify;
/* メソッド */
public __construct(
string $match,
array $route,
array $map = ?,
array $verify = ?,
string $reverse = ?
)
public assemble(array $info, array $query = ?): ?string
public route(Yaf_Request_Abstract $request): bool
/* 継承したメソッド */
abstract public Yaf_Route_Interface::assemble(array $info, array $query = ?): string
abstract public Yaf_Route_Interface::route(Yaf_Request_Abstract $request): bool
}

プロパティ

_route

_default

_maps

_verify

目次

  • Yaf_Route_Regex::assemble — URL を組み立てる
  • Yaf_Route_Regex::__construct — Yaf_Route_Regex のコンストラクタ
  • Yaf_Route_Regex::route — The route purpose


URL を組み立てる

  • ≪ Yaf_Route_Regex
  • Yaf_Route_Regex::__construct ≫
  • PHP Manual
  • Yaf_Route_Regex
  • URL を組み立てる

Yaf_Route_Regex::assemble

(Yaf >=2.3.0)

Yaf_Route_Regex::assemble — URL を組み立てる

説明

public Yaf_Route_Regex::assemble(array $info, array $query = ?): ?string

URL を組み立てます。

パラメータ

info

query

戻り値

成功時に文字列を返します。 失敗時に null を返します。

例

例1 Yaf_Route_Regex::assemble() の例

<?php

$router = new Yaf_Router();

$route = new Yaf_Route_Regex(
"#^/product/([^/]+)/([^/])+#",
array(
'controller' => "product", //route to product controller,
),
array(),
array(),
'/:m/:c/:a'
);

$router->addRoute("regex", $route);

var_dump($router->getRoute('regex')->assemble(
array(
':m' => 'module',
':c' => 'controller',
':a' => 'action'
),
array(
'tkey1' => 'tval1',
'tkey2' =>
'tval2'
)
)
);

上の例の出力は、 たとえば以下のようになります。

string(49) "/module/controller/action?tkey1=tval1&tkey2=tval2"


Yaf_Route_Regex のコンストラクタ

  • ≪ Yaf_Route_Regex::assemble
  • Yaf_Route_Regex::route ≫
  • PHP Manual
  • Yaf_Route_Regex
  • Yaf_Route_Regex のコンストラクタ

Yaf_Route_Regex::__construct

(Yaf >=1.0.0)

Yaf_Route_Regex::__construct — Yaf_Route_Regex のコンストラクタ

説明

public Yaf_Route_Regex::__construct(
string $match,
array $route,
array $map = ?,
array $verify = ?,
string $reverse = ?
)

パラメータ

match

正規表現のパターン。リクエストの URI とマッチさせます。 もしマッチしなければ Yaf_Route_Regex は false を返します。

route

リクエスト URI がパターンにマッチしたときに、 Yaf_Route_Regex はこれを使ってルーティング先を判断します。

この配列で指定するモジュール、コントローラ、アクションはすべて任意指定で、 値を省略したときにはデフォルト設定を利用します。

map

マッチした結果に代入する名前の配列。

verify

reverse

URL を組み立てるときに使う文字列。 Yaf_Route_Regex::assemble() を参照ください。

注意:

このパラメータは 2.3.0 で導入されました。

戻り値

例

例1 Yaf_Route_Regex() の例

<?php
/**
* Add a regex route to Yaf_Router route stack
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
new Yaf_Route_Regex(
"#^/product/([^/]+)/([^/])+#", //match request uri leading "/product"
array(
'controller' => "product", //route to product controller,
),
array(
1 => "name", // now you can call $request->getParam("name")
2 => "id", // to get the first captrue in the match pattern.
)
)
);
?>

例2 Yaf_Route_Regex() (2.3.0 以降) の例

<?php
/**
* Use match result as MVC name
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
new Yaf_Route_Regex(
"#^/product/([^/]+)/([^/])+#i", //match request uri leading "/product"
array(
'controller' => ":name", // route to :name, which is $1 in the match result as controller name
),
array(
1 => "name", // now you can call $request->getParam("name")
2 => "id", // to get the first captrue in the match pattern.
)
)
);
?>

例3 Yaf_Route_Regex と名前付きキャプチャグループ (2.3.0 以降) の例()example

<?php
/**
* Use match result as MVC name
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
new Yaf_Route_Regex(
"#^/product/(?<name>[^/]+)/([^/])+#i", //match request uri leading "/product"
array(
'controller' => ":name", // route to :name,
// which is named capture group 'name' in the match result as controller name
),
array(
2 => "id", // to get the first captrue in the match pattern.
)
)
);
?>

例4 Yaf_Route_Regex() の例

<?php
/**
* Add a regex route to Yaf_Router route stack by calling addconfig
*/
$config = array(
"name" => array(
"type" => "regex", //Yaf_Route_Regex route
"match" => "#(.*)#", //match arbitrary request uri
"route" => array(
'controller' => "product", //route to product controller,
'action' => "dummy", //route to dummy action
),
"map" => array(
1 => "uri", // now you can call $request->getParam("uri")
),
),
);
Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
new Yaf_Config_Simple($config));
?>

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Rewrite
  • Yaf_Route_Map


The route purpose

  • ≪ Yaf_Route_Regex::__construct
  • Yaf_Route_Rewrite ≫
  • PHP Manual
  • Yaf_Route_Regex
  • The route purpose

Yaf_Route_Regex::route

(Yaf >=1.0.0)

Yaf_Route_Regex::route — The route purpose

説明

public Yaf_Route_Regex::route(Yaf_Request_Abstract $request): bool

リクエストをルーティングします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

戻り値

Yaf_Route_Regex::_construct() の引数で指定したパターンにリクエスト URI がマッチした場合に true、 それ以外の場合に false を返します。


Yaf_Route_Rewrite クラス

(Yaf >=1.0.0)

はじめに

使いかたについては、 Yaf_Route_Rewrite::__construct() のサンプルを参照ください。

クラス概要

class Yaf_Route_Rewrite extends Yaf_Route_Interface implements Yaf_Route_Interface {
/* プロパティ */
protected $_route;
protected $_default;
protected $_verify;
/* メソッド */
public __construct(string $match, array $route, array $verify = ?)
public assemble(array $info, array $query = ?): string
public route(Yaf_Request_Abstract $request): bool
/* 継承したメソッド */
abstract public Yaf_Route_Interface::assemble(array $info, array $query = ?): string
abstract public Yaf_Route_Interface::route(Yaf_Request_Abstract $request): bool
}

プロパティ

_route

_default

_verify

目次

  • Yaf_Route_Rewrite::assemble — URLを組み立てる
  • Yaf_Route_Rewrite::__construct — Yaf_Route_Rewrite のコンストラクタ
  • Yaf_Route_Rewrite::route — The route purpose


URLを組み立てる

  • ≪ Yaf_Route_Rewrite
  • Yaf_Route_Rewrite::__construct ≫
  • PHP Manual
  • Yaf_Route_Rewrite
  • URLを組み立てる

Yaf_Route_Rewrite::assemble

(Yaf >=2.3.0)

Yaf_Route_Rewrite::assemble — URLを組み立てる

説明

public Yaf_Route_Rewrite::assemble(array $info, array $query = ?): string

URLを組み立てます。

パラメータ

info

query

戻り値

文字列を返します。

例

例1 Yaf_Route_Rewrite::assemble() の例

router = new Yaf_Router();

$route = new Yaf_Route_Rewrite(
"/product/:name/:id/*",
array(
'controller' => "product",
),
array()
);

$router->addRoute("rewrite", $route);

var_dump($router->getRoute('rewrite')->assemble(
array(
':name' => 'foo',
':id' => 'bar',
':tmpkey1' => 'tmpval1'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2'
)
)
);

上の例の出力は、 たとえば以下のようになります。

string(57) "/product/foo/bar/tmpkey1/tmpval1/?tkey1=tval1&tkey2=tval2"


Yaf_Route_Rewrite のコンストラクタ

  • ≪ Yaf_Route_Rewrite::assemble
  • Yaf_Route_Rewrite::route ≫
  • PHP Manual
  • Yaf_Route_Rewrite
  • Yaf_Route_Rewrite のコンストラクタ

Yaf_Route_Rewrite::__construct

(Yaf >=1.0.0)

Yaf_Route_Rewrite::__construct — Yaf_Route_Rewrite のコンストラクタ

説明

public Yaf_Route_Rewrite::__construct(string $match, array $route, array $verify = ?)

パラメータ

match

リクエストの URI とマッチさせるパターン。 もしマッチしなければ Yaf_Route_Rewrite は false を返します。

:name 形式を使って、マッチしたセグメントに名前を付けることができます。 また、* で残りの URL セグメントにマッチさせられます。

route

リクエスト URI がパターンにマッチしたときに、 Yaf_Route_Rewrite はこれを使ってルーティング先のモジュール、コントローラ、アクションを判断します。

この配列で指定するモジュール、コントローラ、アクションはすべて任意指定で、 値を省略したときにはデフォルト設定を利用します。

verify

戻り値

例

例1 Yaf_Route_Rewrite() の例

<?php
/**
* Add a rewrite route to Yaf_Router route stack
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute("name",
new Yaf_Route_rewrite(
"/product/:name/:id/*", //match request uri leading "/product"
array(
'controller' => "product", //route to product controller,
),
)
);
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/product/foo/22/foo/bar
 * の場合はこのような結果になります
 */
array(
  "controller" => "product",
  "module"     => "index", //(default)
  "action"     => "index", //(default)
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "name" => "foo",
  "id"   => 22,
  "foo"  => bar
)

例2 Yaf_Route_Rewrite() の例

<?php
/**
* Add a rewrite route to Yaf_Router route stack by calling addconfig
*/
$config = array(
"name" => array(
"type" => "rewrite", //Yaf_Route_Rewrite route
"match" => "/user-list/:id", //match only /user/list/?/
"route" => array(
'controller' => "user", //route to user controller,
'action' => "list", //route to list action
),
),
);
Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
new Yaf_Config_Simple($config));
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/user-list/22
 * の場合はこのような結果になります
 */
array(
  "controller" => "user",
  "action"     => "list",
  "module"     => "index", //(default)
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "id"   => 22,
)

例3 Yaf_Route_Rewrite() (2.3.0 以降) の例

<?php
/**
* Add a rewrite route use match result as m/c/a name
*/
$config = array(
"name" => array(
"type" => "rewrite",
"match" => "/user-list/:a/:id", //match only /user-list/*
"route" => array(
'controller' => "user", //route to user controller,
'action' => ":a", //route to :a action
),
),
);
Yaf_Dispatcher::getInstance()->getRouter()->addConfig(
new Yaf_Config_Simple($config));
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/user-list/list/22
 * の場合はこのような結果になります
 */
array(
  "controller" => "user",
  "action"     => "list",
  "module"     => "index", //(default)
)

/**
 * リクエストパラメータは、このようになります
 */
array(
  "id"   => 22,
)

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Map


The route purpose

  • ≪ Yaf_Route_Rewrite::__construct
  • Yaf_Router ≫
  • PHP Manual
  • Yaf_Route_Rewrite
  • The route purpose

Yaf_Route_Rewrite::route

(Yaf >=1.0.0)

Yaf_Route_Rewrite::route — The route purpose

説明

public Yaf_Route_Rewrite::route(Yaf_Request_Abstract $request): bool

パラメータ

request

戻り値


Yaf_Router クラス

(Yaf >=1.0.0)

はじめに

Yaf_Router は、フレームワークの標準のルーターです。 ルーティングとは、URI エンドポイント (URI の中で、ベース URL の後に続く部分。 Yaf_Request_Abstract::setBaseUri() を参照ください) を受け取ってそこからパラメータを抽出し、 リクエストを受け取るモジュールやコントローラそしてアクションを判断する処理のことです。 モジュール、コントローラ、アクション、そしてその他のパラメータは Yaf_Request_Abstract オブジェクトにまとめられ、 そして Yaf_Dispatcher で処理します。 ルーティングが行われるのは一度だけで、リクエストを最初に受け取ってから 最初のコントローラにディスパッチする前に行われます。 Yaf_Router は、mod_rewrite 風の機能を PHP を使って実現できるような設計になっています。 Ruby on Rails のルーティング方式を参考にしており、 ウェブサーバーの URL リライト機能に関する事前知識は不要です。 Apache の場合は、次のような mod_rewrite ルールを書けば使えます。

例1 Apache 用のリライトルール

RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php
あるいは、次のようにもできます (こちらのほうを推奨します)。

例2 Apache 用のリライトルール

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
Lighttpd の場合は、次のようなリライトルールを指定します。

例3 Lighttpd 用のリライトルール

url.rewrite-once = (
  ".*\?(.*)$" => "/index.php?$1",
  ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
  "" => "/index.php"
)
Nginx の場合は、次のようなリライトルールを指定します。

例4 Nginx 用のリライトルール

server {
  listen ****;
  server_name  yourdomain.com;
  root   document_root;
  index  index.php index.html;

  if (!-e $request_filename) {
    rewrite ^/(.*)  /index.php/$1 last;
  }
}

デフォルトのルート

Yaf_Router には設定済みのデフォルトルート Yaf_Route_Static が用意されており、これは controller/action 形式の URI にマッチします。 さらに、モジュール名を最初のパス要素として指定できます。この場合の URI は module/controller/action 形式になります。 また、追加のパラメータを URI に追記できるようになっています。つまり controller/action/var1/value1/var2/value2 といった形式です。

注意:

モジュール名は設定ファイルで定義しておく必要があります。 たとえば application.module="Index,Foo,Bar" とすると、 index、foo、bar だけがモジュール名とみなされます。 設定をしなかった場合は、モジュール名とみなされるのは "Index" だけです。

ルートのマッチングの例を示します。

例5 Yaf_Route_Static のデフォルトルート

// このように設定しているものとします
$conf = array(
   "application" => array(
      "modules" => "Index,Blog",
   ),
);

コントローラのみ
http://example/news
    controller == news
アクションのみ (php.ini で yaf.action_prefer=1 とした場合)
    action  == news

モジュール名として無効な場合はコントローラ名とみなします
http://example/foo
    controller == foo

モジュール + コントローラ
http://example/blog/archive
    module     == blog
    controller == archive

モジュール + コントローラ + アクション
http://example/blog/archive/list
    module     == blog
    controller == archive
    action     == list

モジュール + コントローラ + アクション + パラメータ
http://example/blog/archive/list/sort/alpha/date/desc
    module     == blog
    controller == archive
    action     == list
    sort       == alpha
    date       == desc

クラス概要

class Yaf_Router {
/* プロパティ */
protected $_routes;
protected $_current;
/* メソッド */
public __construct()
public addConfig(Yaf_Config_Abstract $config): bool
public addRoute(string $name, Yaf_Route_Abstract $route): bool
public getCurrentRoute(): string
public getRoute(string $name): Yaf_Route_Interface
public getRoutes(): mixed
public route(Yaf_Request_Abstract $request): bool
}

プロパティ

_routes

登録されたルートスタック。

_current

ルーティングを終えた後に、 今回のリクエストで使ったルートの名前がここに入ります。 この名前を取得するには Yaf_Router::getCurrentRoute() を使います。

目次

  • Yaf_Router::addConfig — 設定で定義したルートをルーターに追加する
  • Yaf_Router::addRoute — 新しいルートをルーターに追加する
  • Yaf_Router::__construct — Yaf_Router のコンストラクタ
  • Yaf_Router::getCurrentRoute — 使われているルート名を取得する
  • Yaf_Router::getRoute — 名前を指定してルートを取得する
  • Yaf_Router::getRoutes — 登録済みのルートを取得する
  • Yaf_Router::route — The route purpose


設定で定義したルートをルーターに追加する

  • ≪ Yaf_Router
  • Yaf_Router::addRoute ≫
  • PHP Manual
  • Yaf_Router
  • 設定で定義したルートをルーターに追加する

Yaf_Router::addConfig

(Yaf >=1.0.0)

Yaf_Router::addConfig — 設定で定義したルートをルーターに追加する

説明

public Yaf_Router::addConfig(Yaf_Config_Abstract $config): bool

設定で定義したルートを Yaf_Router のスタックに追加します。

パラメータ

この関数にはパラメータはありません。

戻り値

Yaf_Config_Abstract のインスタンスを返します。 ここには有効なルート設定が含まれています。

例

例1 application.ini() の例

;the order is very important, the prior one will be called first

;a rewrite route match request /product/*/*
routes.route_name.type="rewrite"
routes.route_name.match="/product/:name/:value"
routes.route_name.route.controller=product
routes.route_name.route.action=info

;a regex route match request /list/*/*
routes.route_name1.type="regex"
routes.route_name1.match="#^list/([^/]*)/([^/]*)#"
routes.route_name1.route.controller=Index
routes.route_name1.route.action=action
routes.route_name1.map.1=name
routes.route_name1.map.2=value

;a simple route match /**?c=controller&a=action&m=module
routes.route_name2.type="simple"
routes.route_name2.controller=c
routes.route_name2.module=m
routes.route_name2.action=a

;a simple router match /**?r=PATH_INFO
routes.route_name3.type="supervar"
routes.route_name3.varname=r

;a map route match any request to controller
routes.route_name4.type="map"
routes.route_name4.controllerPrefer=TRUE
routes.route_namer.delimiter="#!"

例2 Yaf_Dispatcher::autoConfig() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
public function _initConfig() {
$config = Yaf_Application::app()->getConfig();
Yaf_Registry::set("config", $config);
}

public function _initRoute(Yaf_Dispatcher $dispatcher) {
$router = $dispatcher->getRouter();
/**
* we can add some pre-defined routes in application.ini
*/
$router->addConfig(Yaf_Registry::get("config")->routes);
}
?>

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Rewrite
  • Yaf_Route_Map


新しいルートをルーターに追加する

  • ≪ Yaf_Router::addConfig
  • Yaf_Router::__construct ≫
  • PHP Manual
  • Yaf_Router
  • 新しいルートをルーターに追加する

Yaf_Router::addRoute

(Yaf >=1.0.0)

Yaf_Router::addRoute — 新しいルートをルーターに追加する

説明

public Yaf_Router::addRoute(string $name, Yaf_Route_Abstract $route): bool

Yaf_Router はデフォルトのルートとして Yaf_Route_Static を使います。ルーターのルートスタックにそれ以外のルートを追加するときに、このメソッドを使います。

ルートスタックに後から追加したルートのほうが先に呼ばれます。 どれかひとつのルーターが true を返せば、そこでルーティングが終わります。それ以外の場合は 次のルーターを呼びます。

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yaf_Dispatcher::autoRender() の例

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
public function _initConfig() {
$config = Yaf_Application::app()->getConfig();
Yaf_Registry::set("config", $config);
}

public function _initRoute(Yaf_Dispatcher $dispatcher) {
$router = $dispatcher->getRouter();
/**
* we can add some pre-defined routes in application.ini
*/
$router->addConfig(Yaf_Registry::get("config")->routes);
/**
* add a Rewrite route, then for a request uri:
* http://example.com/product/list/22/foo
* will be matched by this route, and result:
*
* [module] =>
* [controller] => product
* [action] => info
* [method] => GET
* [params:protected] => Array
* (
* [id] => 22
* [name] => foo
* )
*
*/
$route = new Yaf_Route_Rewrite(
"/product/list/:id/:name",
array(
"controller" => "product",
"action" => "info",
)
);

$router->addRoute('dummy', $route);
}
}
?>

参考

  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Supervar
  • Yaf_Route_Simple
  • Yaf_Route_Regex
  • Yaf_Route_Rewrite
  • Yaf_Route_Map


Yaf_Router のコンストラクタ

  • ≪ Yaf_Router::addRoute
  • Yaf_Router::getCurrentRoute ≫
  • PHP Manual
  • Yaf_Router
  • Yaf_Router のコンストラクタ

Yaf_Router::__construct

(Yaf >=1.0.0)

Yaf_Router::__construct — Yaf_Router のコンストラクタ

説明

public Yaf_Router::__construct()

パラメータ

この関数にはパラメータはありません。

戻り値


使われているルート名を取得する

  • ≪ Yaf_Router::__construct
  • Yaf_Router::getRoute ≫
  • PHP Manual
  • Yaf_Router
  • 使われているルート名を取得する

Yaf_Router::getCurrentRoute

(Yaf >=1.0.0)

Yaf_Router::getCurrentRoute — 使われているルート名を取得する

説明

public Yaf_Router::getCurrentRoute(): string

ルーティングプロセスで使われているルート名を取得します。

注意:

このメソッドはルーティングが終わってから呼ぶ必要があります。 終わる前に呼ぶと、常に null を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ルート名を文字列で返します。

例

例1 ブートストラップでのルートの登録

<?php
class Bootstrap extends Yaf_Bootstrap_Abstract{
public function _initConfig() {
$config = Yaf_Application::app()->getConfig();
Yaf_Registry::set("config", $config);
}

public function _initRoute(Yaf_Dispatcher $dispatcher) {
$router = $dispatcher->getRouter();
$rewrite_route = new Yaf_Route_Rewrite(
"/product/list/:page",
array(
"controller" => "product",
"action" => "list",
)
);

$regex_route = new Yaf_Route_Rewrite(
"#^/product/info/(\d+)",
array(
"controller" => "product",
"action" => "info",
)
);

$router->addRoute('rewrite', $rewrite_route)->addRoute('regex', $regex_route);
}

/**
* register plugin
*/
public function __initPlugins(Yaf_Dispatcher $dispatcher) {
$dispatcher->registerPlugin(new DummyPlugin());
}
}
?>

例2 プラグイン Dummy.php (application.directory/plugins 配下)

<?php
class DummyPlugin extends Yaf_Plugin_Abstract {
public function routerShutdown(Yaf_Request_Abstract $request, Yaf_Response_Abstract $response) {
var_dump(Yaf_Dispatcher::getInstance()->getRouter()->getCurrentRoute());
}
}
?>

上の例の出力は、 たとえば以下のようになります。

/* http://yourdomain.com/product/list/1
 * の場合の DummyPlugin の出力
 */
string(7) "rewrite"

/* http://yourdomain.com/product/info/34
 * の場合の DummyPlugin の出力
 */
string(5) "regex"

/* その他のリクエスト URI
 * の場合の DummyPlugin の出力
 */
string(8) "_default"

参考

  • Yaf_Bootstrap_Abstract
  • Yaf_Plugin_Abstract
  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する


名前を指定してルートを取得する

  • ≪ Yaf_Router::getCurrentRoute
  • Yaf_Router::getRoutes ≫
  • PHP Manual
  • Yaf_Router
  • 名前を指定してルートを取得する

Yaf_Router::getRoute

(Yaf >=1.0.0)

Yaf_Router::getRoute — 名前を指定してルートを取得する

説明

public Yaf_Router::getRoute(string $name): Yaf_Route_Interface

名前を指定してルートを取得します。 Yaf_Router::getCurrentRoute() も参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Yaf_Bootstrap_Abstract
  • Yaf_Plugin_Abstract
  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::getCurrentRoute() - 使われているルート名を取得する


登録済みのルートを取得する

  • ≪ Yaf_Router::getRoute
  • Yaf_Router::route ≫
  • PHP Manual
  • Yaf_Router
  • 登録済みのルートを取得する

Yaf_Router::getRoutes

(Yaf >=1.0.0)

Yaf_Router::getRoutes — 登録済みのルートを取得する

説明

public Yaf_Router::getRoutes(): mixed

登録済みのルートを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値


The route purpose

  • ≪ Yaf_Router::getRoutes
  • Yaf_Route_Simple ≫
  • PHP Manual
  • Yaf_Router
  • The route purpose

Yaf_Router::route

(Yaf >=1.0.0)

Yaf_Router::route — The route purpose

説明

public Yaf_Router::route(Yaf_Request_Abstract $request): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Route_Simple クラス

(Yaf >=1.0.0)

はじめに

Yaf_Route_Simple は、クエリ文字列を見てルート情報を取得します。

Yaf_Route_Simple に対して必要な設定は、 $_GET のどのキーがモジュールでどのキーがコントローラ、 そしてどのキーがアクションなのかを指定することです。

Yaf_Route_Simple::route() は常に true を返します。 そこで、Yaf_Route_Simple はルートスタックの先頭に置く必要があります。 そうしないと、他のルートは決して呼ばれなくなります。

クラス概要

class Yaf_Route_Simple implements Yaf_Route_Interface {
/* プロパティ */
protected $controller;
protected $module;
protected $action;
/* メソッド */
public __construct(string $module_name, string $controller_name, string $action_name)
public assemble(array $info, array $query = ?): string
public route(Yaf_Request_Abstract $request): bool
}

プロパティ

controller

module

action

目次

  • Yaf_Route_Simple::assemble — URLを組み立てる
  • Yaf_Route_Simple::__construct — Yaf_Route_Simple のコンストラクタ
  • Yaf_Route_Simple::route — リクエストをルーティングする


URLを組み立てる

  • ≪ Yaf_Route_Simple
  • Yaf_Route_Simple::__construct ≫
  • PHP Manual
  • Yaf_Route_Simple
  • URLを組み立てる

Yaf_Route_Simple::assemble

(Yaf >=2.3.0)

Yaf_Route_Simple::assemble — URLを組み立てる

説明

public Yaf_Route_Simple::assemble(array $info, array $query = ?): string

URLを組み立てます。

パラメータ

info

query

戻り値

文字列を返します。

エラー / 例外

info に キー ':c' または ':a' が設定されていなかった場合、 Yaf_Exception_TypeError をスローします。

例

例1 Yaf_Route_Simple::assemble() の例

<?php

$router = new Yaf_Router();

$route = new Yaf_Route_Simple('m', 'c', 'a');

$router->addRoute("simple", $route);

var_dump($router->getRoute('simple')->assemble(
array(
':a' => 'yafaction',
'tkey' => 'tval',
':c' => 'yafcontroller',
':m' => 'yafmodule'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2'
)
));

上の例の出力は、 たとえば以下のようになります。

string(64) "?m=yafmodule&c=yafcontroller&a=yafaction&tkey1=tval1&tkey2=tval2"


Yaf_Route_Simple のコンストラクタ

  • ≪ Yaf_Route_Simple::assemble
  • Yaf_Route_Simple::route ≫
  • PHP Manual
  • Yaf_Route_Simple
  • Yaf_Route_Simple のコンストラクタ

Yaf_Route_Simple::__construct

(Yaf >=1.0.0)

Yaf_Route_Simple::__construct — Yaf_Route_Simple のコンストラクタ

説明

public Yaf_Route_Simple::__construct(string $module_name, string $controller_name, string $action_name)

Yaf_Route_Simple は、クエリストリングからルーティング情報を取得します。 そして、このコンストラクタのパラメータは $_GET の中にあるルーティング情報を検索するキーとして使われます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

module_name

モジュール情報のキー名

controller_name

コントローラー情報のキー名

action_name

アクション情報のキー名

戻り値

常に true を返します。

例

例1 Yaf_Route_Simple::route() の例

<?php
$route = new Yaf_Route_Simple("m", "controller", "act");
Yaf_Router::getInstance()->addRoute("simple", $route);
?>

例2 Yaf_Route_Simple::route()example

Request: http://yourdomain.com/path/?controller=a&act=b
=> module = default(index), controller = a, action = b

Request: http://yourdomain.com/path
=> module = default(index), controller = default(index), action = default(index)

参考

  • Yaf_Route_Supervar::route() - The route purpose
  • Yaf_Route_Static::route() - リクエストをルーティングする
  • Yaf_Route_Regex::route() - The route purpose
  • Yaf_Route_Rewrite::route() - The route purpose
  • Yaf_Route_Map::route() - route の目的


リクエストをルーティングする

  • ≪ Yaf_Route_Simple::__construct
  • Yaf_Route_Static ≫
  • PHP Manual
  • Yaf_Route_Simple
  • リクエストをルーティングする

Yaf_Route_Simple::route

(Yaf >=1.0.0)

Yaf_Route_Simple::route — リクエストをルーティングする

説明

public Yaf_Route_Simple::route(Yaf_Request_Abstract $request): bool

see Yaf_Route_Simple::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

戻り値

常に true を返します。

参考

  • Yaf_Route_Supervar::route() - The route purpose
  • Yaf_Route_Static::route() - リクエストをルーティングする
  • Yaf_Route_Regex::route() - The route purpose
  • Yaf_Route_Rewrite::route() - The route purpose
  • Yaf_Route_Map::route() - route の目的


Yaf_Route_Static クラス

(Yaf >=1.0.0)

はじめに

デフォルトでは、Yaf_Router が持っているルートは Yaf_Route_Static だけです。

Yaf_Route_Static は、 要件の 80% を満たせるように作られています。

Yaf_Route_Static のインスタンスを作る必要はありません。 また、Yaf_Router のルートスタックに追加する必要もありません。 というのもこのクラスは常に Yaf_Router のルートスタックに含まれており、最後に呼ばれるようになっているからです。

クラス概要

class Yaf_Route_Static implements Yaf_Router {
/* メソッド */
public assemble(array $info, array $query = ?): string
public match(string $uri): void
public route(Yaf_Request_Abstract $request): bool
}

目次

  • Yaf_Route_Static::assemble — URL を組み立てる
  • Yaf_Route_Static::match — The match purpose
  • Yaf_Route_Static::route — リクエストをルーティングする


URL を組み立てる

  • ≪ Yaf_Route_Static
  • Yaf_Route_Static::match ≫
  • PHP Manual
  • Yaf_Route_Static
  • URL を組み立てる

Yaf_Route_Static::assemble

(Yaf >=2.3.0)

Yaf_Route_Static::assemble — URL を組み立てる

説明

public Yaf_Route_Static::assemble(array $info, array $query = ?): string

URL を組み立てます。

パラメータ

info

query

戻り値

文字列を返します。

エラー / 例外

info に キー ':c' と ':a' が設定されていなかった場合、 Yaf_Exception_TypeError をスローします。

例

例1 Yaf_Route_Static::assemble() の例

<?php

$router = new Yaf_Router();

$route = new Yaf_Route_Static();

$router->addRoute("static", $route);

var_dump($router->getRoute('static')->assemble(
array(
':a' => 'yafaction',
'tkey' => 'tval',
':c' => 'yafcontroller',
':m' => 'yafmodule'
),
)
);

var_dump($router->getRoute('static')->assemble(
array(
':a' => 'yafaction',
'tkey' => 'tval',
':c' => 'yafcontroller',
':m' => 'yafmodule'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2'
)
)
);

上の例の出力は、 たとえば以下のようになります。

string(%d) "/yafmodule/yafcontroller/yafaction"
string(%d) "/yafmodule/yafcontroller/yafaction?tkey1=tval1&tkey2=tval2"


The match purpose

  • ≪ Yaf_Route_Static::assemble
  • Yaf_Route_Static::route ≫
  • PHP Manual
  • Yaf_Route_Static
  • The match purpose

Yaf_Route_Static::match

(Yaf >=1.0.0)

Yaf_Route_Static::match — The match purpose

説明

public Yaf_Route_Static::match(string $uri): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

uri

戻り値


リクエストをルーティングする

  • ≪ Yaf_Route_Static::match
  • Yaf_Route_Supervar ≫
  • PHP Manual
  • Yaf_Route_Static
  • リクエストをルーティングする

Yaf_Route_Static::route

(Yaf >=1.0.0)

Yaf_Route_Static::route — リクエストをルーティングする

説明

public Yaf_Route_Static::route(Yaf_Request_Abstract $request): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

戻り値

常に true を返します。

例

例1 Yaf_Route_Static::route() の例

// assuming there is only one module defined:Index
Request: http://yourdomain.com/a/b
=> module = index, controller=a, action=b

//assuming ap.action_prefer = On
Request: http://yourdomain.com/b
=> module = default(index), controller = default(index), action = b

//assuming ap.action_prefer = Off
Request: http://yourdomain.com/b
=> module = default(index), controller = b, action = default(index)

Request: http://yourdomain.com/a/b/foo/bar/test/a/id/4
=> module = default(index), controller = a, action = b, request parameters: foo = bar, test = a, id = 4

参考

  • Yaf_Route_Supervar::route() - The route purpose
  • Yaf_Route_Simple::route() - リクエストをルーティングする
  • Yaf_Route_Regex::route() - The route purpose
  • Yaf_Route_Rewrite::route() - The route purpose
  • Yaf_Route_Map::route() - route の目的


Yaf_Route_Supervar クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Route_Supervar implements Yaf_Route_Interface {
/* プロパティ */
protected $_var_name;
/* メソッド */
public __construct(string $supervar_name)
public assemble(array $info, array $query = ?): string
public route(Yaf_Request_Abstract $request): bool
}

プロパティ

_var_name

目次

  • Yaf_Route_Supervar::assemble — URL を組み立てる
  • Yaf_Route_Supervar::__construct — The __construct purpose
  • Yaf_Route_Supervar::route — The route purpose


URL を組み立てる

  • ≪ Yaf_Route_Supervar
  • Yaf_Route_Supervar::__construct ≫
  • PHP Manual
  • Yaf_Route_Supervar
  • URL を組み立てる

Yaf_Route_Supervar::assemble

(Yaf >=2.3.0)

Yaf_Route_Supervar::assemble — URL を組み立てる

説明

public Yaf_Route_Supervar::assemble(array $info, array $query = ?): string

URL を組み立てます

パラメータ

info

query

戻り値

文字列を返します。

エラー / 例外

info に キー ':c' と ':a' が設定されていなかった場合、 Yaf_Exception_TypeError をスローします。

例

例1 Yaf_Route_Supervar::assemble() の例

<?php

$router = new Yaf_Router();

$route = new Yaf_Route_Supervar('r');

$router->addRoute("supervar", $route);

var_dump($router->getRoute('supervar')->assemble(
array(
':a' => 'yafaction',
'tkey' => 'tval',
':c' => 'yafcontroller',
':m' => 'yafmodule'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2'
)
));

try {
var_dump($router->getRoute('supervar')->assemble(
array(
':a' => 'yafaction',
'tkey' => 'tval',
':m' => 'yafmodule'
),
array(
'tkey1' => 'tval1',
'tkey2' => 'tval2',
1 => array(),
)
));
} catch (Exception $e) {
var_dump($e->getMessage());
}

上の例の出力は、 たとえば以下のようになります。

string(%d) "?r=/yafmodule/yafcontroller/yafaction&tkey1=tval1&tkey2=tval2"
string(%d) "You need to specify the controller by ':c'"


The __construct purpose

  • ≪ Yaf_Route_Supervar::assemble
  • Yaf_Route_Supervar::route ≫
  • PHP Manual
  • Yaf_Route_Supervar
  • The __construct purpose

Yaf_Route_Supervar::__construct

(Yaf >=1.0.0)

Yaf_Route_Supervar::__construct — The __construct purpose

説明

public Yaf_Route_Supervar::__construct(string $supervar_name)

Yaf_Route_Supervar は Yaf_Route_Static と似ています。違うところは、 Yaf_Route_Supervar がクエリ文字列からパス情報を探すところです。 パラメータ supervar_name がキーとなります。

パラメータ

supervar_name

キーの名前。

戻り値

例

例1 Yaf_Route_Supervar() の例

<?php
/**
* Add a supervar route to Yaf_Router route stack
*/
Yaf_Dispatcher::getInstance()->getRouter()->addRoute(
"name",
new Yaf_Route_Supervar("r")
);
?>

上の例の出力は、 たとえば以下のようになります。

/** http://yourdomain.com/xx/oo/?r=/ctr/act/var/value
  * の場合はこのような結果になります
  */
  array (
    "module"   => index(default),
    "controller" => ctr,
    "action"     => act,
    "params"     => array(
          "var" => value,
     )
  )

参考

  • Yaf_Router::addRoute() - 新しいルートをルーターに追加する
  • Yaf_Router::addConfig() - 設定で定義したルートをルーターに追加する
  • Yaf_Route_Static
  • Yaf_Route_Regex
  • Yaf_Route_Simple
  • Yaf_Route_Rewrite
  • Yaf_Route_Map


The route purpose

  • ≪ Yaf_Route_Supervar::__construct
  • Yaf_Session ≫
  • PHP Manual
  • Yaf_Route_Supervar
  • The route purpose

Yaf_Route_Supervar::route

(Yaf >=1.0.0)

Yaf_Route_Supervar::route — The route purpose

説明

public Yaf_Route_Supervar::route(Yaf_Request_Abstract $request): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

request

戻り値

Yaf_Route_Supervar::__construct() で指定したキーが $_GET に存在すれば true、存在しなければ false を返します。


Yaf_Session クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Session implements Iterator, ArrayAccess, Countable {
/* プロパティ */
protected static $_instance;
protected $_session;
protected $_started;
/* メソッド */
private __construct()
public count(): void
public current(): void
public del(string $name): void
public __get(string $name): void
public static getInstance(): void
public has(string $name): void
public __isset(string $name): void
public key(): void
public next(): void
public offsetExists(string $name): void
public offsetGet(string $name): void
public offsetSet(string $name, string $value): void
public offsetUnset(string $name): void
public rewind(): void
public __set(string $name, string $value): void
public start(): void
public __unset(string $name): void
public valid(): void
}

プロパティ

_instance

_session

_started

目次

  • Yaf_Session::__construct — Yaf_Session のコンストラクタ
  • Yaf_Session::count — The count purpose
  • Yaf_Session::current — The current purpose
  • Yaf_Session::del — The del purpose
  • Yaf_Session::__get — The __get purpose
  • Yaf_Session::getInstance — The getInstance purpose
  • Yaf_Session::has — The has purpose
  • Yaf_Session::__isset — The __isset purpose
  • Yaf_Session::key — The key purpose
  • Yaf_Session::next — The next purpose
  • Yaf_Session::offsetExists — The offsetExists purpose
  • Yaf_Session::offsetGet — The offsetGet purpose
  • Yaf_Session::offsetSet — The offsetSet purpose
  • Yaf_Session::offsetUnset — The offsetUnset purpose
  • Yaf_Session::rewind — The rewind purpose
  • Yaf_Session::__set — The __set purpose
  • Yaf_Session::start — The start purpose
  • Yaf_Session::__unset — The __unset purpose
  • Yaf_Session::valid — The valid purpose


Yaf_Session のコンストラクタ

  • ≪ Yaf_Session
  • Yaf_Session::count ≫
  • PHP Manual
  • Yaf_Session
  • Yaf_Session のコンストラクタ

Yaf_Session::__construct

(Yaf >=1.0.0)

Yaf_Session::__construct — Yaf_Session のコンストラクタ

説明

private Yaf_Session::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The count purpose

  • ≪ Yaf_Session::__construct
  • Yaf_Session::current ≫
  • PHP Manual
  • Yaf_Session
  • The count purpose

Yaf_Session::count

(Yaf >=1.0.0)

Yaf_Session::count — The count purpose

説明

public Yaf_Session::count(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The current purpose

  • ≪ Yaf_Session::count
  • Yaf_Session::del ≫
  • PHP Manual
  • Yaf_Session
  • The current purpose

Yaf_Session::current

(Yaf >=1.0.0)

Yaf_Session::current — The current purpose

説明

public Yaf_Session::current(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The del purpose

  • ≪ Yaf_Session::current
  • Yaf_Session::__get ≫
  • PHP Manual
  • Yaf_Session
  • The del purpose

Yaf_Session::del

(Yaf >=1.0.0)

Yaf_Session::del — The del purpose

説明

public Yaf_Session::del(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The __get purpose

  • ≪ Yaf_Session::del
  • Yaf_Session::getInstance ≫
  • PHP Manual
  • Yaf_Session
  • The __get purpose

Yaf_Session::__get

(Yaf >=1.0.0)

Yaf_Session::__get — The __get purpose

説明

public Yaf_Session::__get(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The getInstance purpose

  • ≪ Yaf_Session::__get
  • Yaf_Session::has ≫
  • PHP Manual
  • Yaf_Session
  • The getInstance purpose

Yaf_Session::getInstance

(Yaf >=1.0.0)

Yaf_Session::getInstance — The getInstance purpose

説明

public static Yaf_Session::getInstance(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The has purpose

  • ≪ Yaf_Session::getInstance
  • Yaf_Session::__isset ≫
  • PHP Manual
  • Yaf_Session
  • The has purpose

Yaf_Session::has

(Yaf >=1.0.0)

Yaf_Session::has — The has purpose

説明

public Yaf_Session::has(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The __isset purpose

  • ≪ Yaf_Session::has
  • Yaf_Session::key ≫
  • PHP Manual
  • Yaf_Session
  • The __isset purpose

Yaf_Session::__isset

(Yaf >=1.0.0)

Yaf_Session::__isset — The __isset purpose

説明

public Yaf_Session::__isset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The key purpose

  • ≪ Yaf_Session::__isset
  • Yaf_Session::next ≫
  • PHP Manual
  • Yaf_Session
  • The key purpose

Yaf_Session::key

(Yaf >=1.0.0)

Yaf_Session::key — The key purpose

説明

public Yaf_Session::key(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The next purpose

  • ≪ Yaf_Session::key
  • Yaf_Session::offsetExists ≫
  • PHP Manual
  • Yaf_Session
  • The next purpose

Yaf_Session::next

(Yaf >=1.0.0)

Yaf_Session::next — The next purpose

説明

public Yaf_Session::next(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The offsetExists purpose

  • ≪ Yaf_Session::next
  • Yaf_Session::offsetGet ≫
  • PHP Manual
  • Yaf_Session
  • The offsetExists purpose

Yaf_Session::offsetExists

(Yaf >=1.0.0)

Yaf_Session::offsetExists — The offsetExists purpose

説明

public Yaf_Session::offsetExists(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The offsetGet purpose

  • ≪ Yaf_Session::offsetExists
  • Yaf_Session::offsetSet ≫
  • PHP Manual
  • Yaf_Session
  • The offsetGet purpose

Yaf_Session::offsetGet

(Yaf >=1.0.0)

Yaf_Session::offsetGet — The offsetGet purpose

説明

public Yaf_Session::offsetGet(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The offsetSet purpose

  • ≪ Yaf_Session::offsetGet
  • Yaf_Session::offsetUnset ≫
  • PHP Manual
  • Yaf_Session
  • The offsetSet purpose

Yaf_Session::offsetSet

(Yaf >=1.0.0)

Yaf_Session::offsetSet — The offsetSet purpose

説明

public Yaf_Session::offsetSet(string $name, string $value): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


The offsetUnset purpose

  • ≪ Yaf_Session::offsetSet
  • Yaf_Session::rewind ≫
  • PHP Manual
  • Yaf_Session
  • The offsetUnset purpose

Yaf_Session::offsetUnset

(Yaf >=1.0.0)

Yaf_Session::offsetUnset — The offsetUnset purpose

説明

public Yaf_Session::offsetUnset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The rewind purpose

  • ≪ Yaf_Session::offsetUnset
  • Yaf_Session::__set ≫
  • PHP Manual
  • Yaf_Session
  • The rewind purpose

Yaf_Session::rewind

(Yaf >=1.0.0)

Yaf_Session::rewind — The rewind purpose

説明

public Yaf_Session::rewind(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __set purpose

  • ≪ Yaf_Session::rewind
  • Yaf_Session::start ≫
  • PHP Manual
  • Yaf_Session
  • The __set purpose

Yaf_Session::__set

(Yaf >=1.0.0)

Yaf_Session::__set — The __set purpose

説明

public Yaf_Session::__set(string $name, string $value): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

value

戻り値


The start purpose

  • ≪ Yaf_Session::__set
  • Yaf_Session::__unset ≫
  • PHP Manual
  • Yaf_Session
  • The start purpose

Yaf_Session::start

(Yaf >=1.0.0)

Yaf_Session::start — The start purpose

説明

public Yaf_Session::start(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The __unset purpose

  • ≪ Yaf_Session::start
  • Yaf_Session::valid ≫
  • PHP Manual
  • Yaf_Session
  • The __unset purpose

Yaf_Session::__unset

(Yaf >=1.0.0)

Yaf_Session::__unset — The __unset purpose

説明

public Yaf_Session::__unset(string $name): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

戻り値


The valid purpose

  • ≪ Yaf_Session::__unset
  • Yaf_Exception ≫
  • PHP Manual
  • Yaf_Session
  • The valid purpose

Yaf_Session::valid

(Yaf >=1.0.0)

Yaf_Session::valid — The valid purpose

説明

public Yaf_Session::valid(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Exception クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public __construct()
public getPrevious(): void
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

目次

  • Yaf_Exception::__construct — コンストラクタ
  • Yaf_Exception::getPrevious — The getPrevious purpose


コンストラクタ

  • ≪ Yaf_Exception
  • Yaf_Exception::getPrevious ≫
  • PHP Manual
  • Yaf_Exception
  • コンストラクタ

Yaf_Exception::__construct

(Yaf >=1.0.0)

Yaf_Exception::__construct — コンストラクタ

説明

public Yaf_Exception::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The getPrevious purpose

  • ≪ Yaf_Exception::__construct
  • Yaf_Exception_TypeError ≫
  • PHP Manual
  • Yaf_Exception
  • The getPrevious purpose

Yaf_Exception::getPrevious

(Yaf >=1.0.0)

Yaf_Exception::getPrevious — The getPrevious purpose

説明

public Yaf_Exception::getPrevious(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Yaf_Exception_TypeError クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_TypeError extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_StartupError クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_StartupError extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_DispatchFailed クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_DispatchFailed extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_RouterFailed クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_RouterFailed extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_LoadFailed クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_LoadFailed extends Yaf_Exception {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_LoadFailed_Module クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_LoadFailed_Module extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_LoadFailed_Controller クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_LoadFailed_Controller extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_LoadFailed_Action クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_LoadFailed_Action extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaf_Exception_LoadFailed_View クラス

(Yaf >=1.0.0)

はじめに

クラス概要

class Yaf_Exception_LoadFailed_View extends Yaf_Exception_LoadFailed {
/* プロパティ */
/* メソッド */
/* 継承したメソッド */
public Yaf_Exception::getPrevious(): void
}


Yaconf

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • Yaconf — The Yaconf class
    • Yaconf::get — Retrieve a item
    • Yaconf::has — Determine if a item exists


はじめに

Yet Another Configurations Container (Yaconf) は、設定コンテナです。 これは INI ファイルをパースし、 PHP の実行が始まるタイミングで結果を格納します。 この結果は、PHP のライフサイクル全体で利用できます。

Yaconf は、全ての設定をインターン化された文字列か、 変更不能な配列として格納します。 つまり、これらの設定はリファレンスカウントの対象にならないため、 Yaconf から設定を取得する際にコピーが発生せず、とても高速です。

Yaconf は、INI ファイル内でセクションやセクションの継承をサポートしています。 PHP が non-ZTS としてビルドされている場合、 Yaconf は INI ファイルが変更された後に、自動的に設定をリロードする機能をサポートしています。

Yaconf を動かすには、PHP 7.0 以降が必要です。

例1 INI ファイルの例

;simple key val
key=val
;hash
hash.a=val
;array
arr.0=val
;or
arr[]=val
;use PHP constants
version=PHP_VERSION
;use environment
env=${PATH}

例2 INI セクションの例

[SectionA]
key=val
hash.a=val

;SectionB inherits SectionA
[SectionB:SectionA]
;override configuration key in SectionA
key=new_val


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Yaconf
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

Yaconf は PHP 7.0 以降が必要です。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaconf.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


実行時設定

php.ini の設定により動作が変化します。

Yaconf 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yaconf.check_delay | 300 | INI_SYSTEM |
yaconf.directory | /tmp/conf/ | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

yaconf.check_delay int

In which interval Yaconf will detect ini file's change(by directory's mtime), if it is set to zero, you have to restart php to reloading configurations.

yaconf.directory string

Path to directory which all INI configuration files are placed in.


  • ≪ 実行時設定
  • Yaconf ≫
  • PHP Manual
  • インストール/設定
  • リソース型

リソース型


The Yaconf class

(PECL yaconf >= 1.0.0)

はじめに

Yaconf is a configurations container, it parses INIT files, stores the result in PHP when PHP is started, the result lives with the whole PHP lifecycle.

クラス概要

class Yaconf {
/* メソッド */
public static get(string $name, mixed $default_value = NULL): mixed
public static has(string $name): bool
}

目次

  • Yaconf::get — Retrieve a item
  • Yaconf::has — Determine if a item exists


Retrieve a item

  • ≪ Yaconf
  • Yaconf::has ≫
  • PHP Manual
  • Yaconf
  • Retrieve a item

Yaconf::get

(PECL yaconf >= 1.0.0)

Yaconf::get — Retrieve a item

説明

public static Yaconf::get(string $name, mixed $default_value = NULL): mixed

パラメータ

name

Configuration key, the key looks like "filename.key", or "filename.sectionName,key".

default_value

if the key doesn't exists, Yaconf::get will return this as result.

戻り値

Returns configuration result(string or array) if the key exists, return default_value if not.

例

例1 INI()example

;filenmame foo.ini, placed in directory which is yaconf.directoy
[SectionA]
;key value pair
key=val
;hash[a]=val
hash.a=val
;arr[0]=val
arr.0=val
;or
arr[]=val

;SectionB inherits SectionA
[SectionB:SectionA]
;override configuration key in SectionA
key=new_val

上の例の出力は、 たとえば以下のようになります。

php7 -r 'var_dump(Yaconf::get("foo.SectionA.key"));'
//string(3) "val"

php7 -r 'var_dump(Yaconf::get("foo.SectionB.key"));'
//string(7) "new_val"

php7 -r 'var_dump(Yaconf::get("foo")["SectionA"]["hash"]);'
//array(1)


Determine if a item exists

  • ≪ Yaconf::get
  • Taint ≫
  • PHP Manual
  • Yaconf
  • Determine if a item exists

Yaconf::has

(PECL yaconf >= 1.0.0)

Yaconf::has — Determine if a item exists

説明

public static Yaconf::has(string $name): bool

パラメータ

name

戻り値


Taint

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 詳細
    • 汚染された文字列の汚染マークを広げる関数や文
    • 汚染された文字列をチェックする関数や文
    • 文字列の汚染を除去する関数
  • Taint 関数
    • is_tainted — 文字列が汚染されているかどうかを調べる
    • taint — 文字列を汚染させる
    • untaint — 文字列の汚染を除去する


はじめに

taint は、XSS コード (汚染された文字列) を検出するための拡張モジュールです。 SQL インジェクションやシェルコマンドインジェクションなどの脆弱性を検出するためにも使えます。

taint を有効にすると、汚染された文字列 ($_GET や $_POST、$_COOKIE に由来するもの) を何かの関数に渡そうとしたときに警告を出すようになります。

例1 taint() の例

<?php
$a = trim($_GET['a']);

$file_name = '/tmp' . $a;
$output = "Welcome, {$a} !!!";
$var = "output";
$sql = "Select * from " . $a;
$sql .= "ooxx";

echo $output;

print $$var;

include $file_name;

mysql_query($sql);
?>

上の例の出力は、 たとえば以下のようになります。

Warning: main() [function.echo]: Attempt to echo a string that might be tainted

Warning: main() [function.echo]: Attempt to print a string that might be tainted

Warning: include() [function.include]: File path contains data that might be tainted

Warning: mysql_query() [function.mysql-query]: SQL statement contains data that might be tainted


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Taint
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

外部ライブラリは必要ありません。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/taint.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


実行時設定

php.ini の設定により動作が変化します。

Taint 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
taint.enable | 0 | INI_SYSTEM |
taint.error_level | E_WARNING | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

taint.enable int

taint を有効にするかどうか。

taint.error_level int

汚染された文字列を見つけたときに taint が報告するエラーの形式。


詳細

目次

  • 汚染された文字列の汚染マークを広げる関数や文
  • 汚染された文字列をチェックする関数や文
  • 文字列の汚染を除去する関数


汚染された文字列の汚染マークを広げる関数や文

関数 / 文 | 対応するようになったバージョン
= (代入) | 0.1.0
. (連結) | 0.1.0
"{$var}" (変数の置換) | 0.1.0
.= (連結代入) | 0.1.0
strval | 0.3.0
explode/split | 0.3.0
implode/join | 0.3.0
sprintf | 0.3.0
vsprintf | 0.3.0
trim | 0.4.0
rtrim | 0.4.0
ltrim | 0.4.0
strstr | 0.5.0
str_pad | 0.5.0
str_replace | 0.5.0
substr | 0.5.0
strtolower | 0.5.0
strtoupper | 0.5.0


汚染された文字列をチェックする関数や文

関数 / 文 | 対応するようになったバージョン
基本構文
eval | 0.1.0
include/include_once | 0.1.0
require/require_once | 0.1.0
出力関数
echo | 0.1.0
print | 0.1.0
printf | 0.1.0
file_put_contents | 0.1.0
ファイルシステム関数
fopen | 0.2.0
opendir | 0.2.0
basename | 0.2.0
dirname | 0.2.0
file | 0.2.0
pathinfo | 0.2.0
データベース関連関数
mysql_query | 0.2.0
mysqli_query/MySQLi::query | 0.2.0
sqlite_query/SqliteDataBase::query | 0.3.0
sqlite_single_query/SqliteDataBase::singleQuery | 0.3.0
oci_parse | 0.3.0
PDO::query | 0.3.0
PDO::prepare | 0.3.0
SQLite3::query | 2.0.1
SQLite3::prepare | 2.0.1
コマンドライン関連関数
system | 0.1.0
exec | 0.1.0
proc_open | 0.1.0
passthru | 0.1.0
shell_exec | 0.3.0


文字列の汚染を除去する関数

関数 | 対応するようになったバージョン
addslashes | 0.1.0
addcslashes | 0.1.0
htmlspecialchars | 0.1.0
htmlentities | 0.1.0
escapeshellcmd | 0.1.0
mysql_escape_string | 0.1.0
mysql_real_escape_string | 0.1.0
mysqli_escape_string/MySQLi::escape_string | 0.1.0
mysqli_real_escape_string/MySQLi::real_escape_string | 0.1.0
sqlite_escape_string/SqliteDataBase::escapeString | 0.3.0
PDO::quote | 0.3.0


Taint 関数

目次

  • is_tainted — 文字列が汚染されているかどうかを調べる
  • taint — 文字列を汚染させる
  • untaint — 文字列の汚染を除去する


文字列が汚染されているかどうかを調べる

  • ≪ Taint 関数
  • taint ≫
  • PHP Manual
  • Taint 関数
  • 文字列が汚染されているかどうかを調べる

is_tainted

(PECL taint >=0.1.0)

is_tainted — 文字列が汚染されているかどうかを調べる

説明

is_tainted(string $string): bool

文字列が汚染されているかどうかを調べます。

パラメータ

string

戻り値

文字列が汚染されている場合に TRUE、それ以外の場合に FALSE を返します。


文字列を汚染させる

  • ≪ is_tainted
  • untaint ≫
  • PHP Manual
  • Taint 関数
  • 文字列を汚染させる

taint

(PECL taint >=0.1.0)

taint — 文字列を汚染させる

説明

taint(string &$string, string ...$strings): bool

文字列を汚染させます。この関数は、テスト用としてのみ使うものです。

パラメータ

string

strings

戻り値

変換に成功したときに TURE を返します。 taint 拡張モジュールが有効になっていない場合は常に TRUE を返します。


文字列の汚染を除去する

  • ≪ taint
  • Data Structures ≫
  • PHP Manual
  • Taint 関数
  • 文字列の汚染を除去する

untaint

(PECL taint >=0.1.0)

untaint — 文字列の汚染を除去する

説明

untaint(string &$string, string ...$strings): bool

文字列の汚染を除去します。

パラメータ

string

strings

戻り値


Data Structures

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
  • Ds\Collection — The Collection interface
    • Ds\Collection::clear — Removes all values
    • Ds\Collection::copy — Returns a shallow copy of the collection
    • Ds\Collection::isEmpty — Returns whether the collection is empty
    • Ds\Collection::toArray — Converts the collection to an array
  • Ds\Hashable — The Hashable interface
    • Ds\Hashable::equals — Determines whether an object is equal to the current instance
    • Ds\Hashable::hash — Returns a scalar value to be used as a hash value
  • Ds\Sequence — The Sequence interface
    • Ds\Sequence::allocate — Allocates enough memory for a required capacity
    • Ds\Sequence::apply — Updates all values by applying a callback function to each value
    • Ds\Sequence::capacity — Returns the current capacity
    • Ds\Sequence::contains — Determines if the sequence contains given values
    • Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include
    • Ds\Sequence::find — Attempts to find a value's index
    • Ds\Sequence::first — Returns the first value in the sequence
    • Ds\Sequence::get — Returns the value at a given index
    • Ds\Sequence::insert — Inserts values at a given index
    • Ds\Sequence::join — Joins all values together as a string
    • Ds\Sequence::last — Returns the last value
    • Ds\Sequence::map — Returns the result of applying a callback to each value
    • Ds\Sequence::merge — Returns the result of adding all given values to the sequence
    • Ds\Sequence::pop — Removes and returns the last value
    • Ds\Sequence::push — Adds values to the end of the sequence
    • Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function
    • Ds\Sequence::remove — Removes and returns a value by index
    • Ds\Sequence::reverse — Reverses the sequence in-place
    • Ds\Sequence::reversed — Returns a reversed copy
    • Ds\Sequence::rotate — Rotates the sequence by a given number of rotations
    • Ds\Sequence::set — Updates a value at a given index
    • Ds\Sequence::shift — Removes and returns the first value
    • Ds\Sequence::slice — Returns a sub-sequence of a given range
    • Ds\Sequence::sort — Sorts the sequence in-place
    • Ds\Sequence::sorted — Returns a sorted copy
    • Ds\Sequence::sum — Returns the sum of all values in the sequence
    • Ds\Sequence::unshift — Adds values to the front of the sequence
  • Ds\Vector — The Vector class
    • Ds\Vector::allocate — Allocates enough memory for a required capacity
    • Ds\Vector::apply — Updates all values by applying a callback function to each value
    • Ds\Vector::capacity — Returns the current capacity
    • Ds\Vector::clear — Removes all values
    • Ds\Vector::__construct — Creates a new instance
    • Ds\Vector::contains — Determines if the vector contains given values
    • Ds\Vector::copy — Returns a shallow copy of the vector
    • Ds\Vector::count — Returns the number of values in the collection
    • Ds\Vector::filter — Creates a new vector using a callable to determine which values to include
    • Ds\Vector::find — Attempts to find a value's index
    • Ds\Vector::first — Returns the first value in the vector
    • Ds\Vector::get — Returns the value at a given index
    • Ds\Vector::insert — Inserts values at a given index
    • Ds\Vector::isEmpty — Returns whether the vector is empty
    • Ds\Vector::join — Joins all values together as a string
    • Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Vector::last — Returns the last value
    • Ds\Vector::map — Returns the result of applying a callback to each value
    • Ds\Vector::merge — Returns the result of adding all given values to the vector
    • Ds\Vector::pop — Removes and returns the last value
    • Ds\Vector::push — Adds values to the end of the vector
    • Ds\Vector::reduce — Reduces the vector to a single value using a callback function
    • Ds\Vector::remove — Removes and returns a value by index
    • Ds\Vector::reverse — Reverses the vector in-place
    • Ds\Vector::reversed — Returns a reversed copy
    • Ds\Vector::rotate — Rotates the vector by a given number of rotations
    • Ds\Vector::set — Updates a value at a given index
    • Ds\Vector::shift — Removes and returns the first value
    • Ds\Vector::slice — Returns a sub-vector of a given range
    • Ds\Vector::sort — Sorts the vector in-place
    • Ds\Vector::sorted — Returns a sorted copy
    • Ds\Vector::sum — Returns the sum of all values in the vector
    • Ds\Vector::toArray — Converts the vector to an array
    • Ds\Vector::unshift — Adds values to the front of the vector
  • Ds\Deque — The Deque class
    • Ds\Deque::allocate — Allocates enough memory for a required capacity
    • Ds\Deque::apply — Updates all values by applying a callback function to each value
    • Ds\Deque::capacity — Returns the current capacity
    • Ds\Deque::clear — Removes all values from the deque
    • Ds\Deque::__construct — Creates a new instance
    • Ds\Deque::contains — Determines if the deque contains given values
    • Ds\Deque::copy — Returns a shallow copy of the deque
    • Ds\Deque::count — Returns the number of values in the collection
    • Ds\Deque::filter — Creates a new deque using a callable to determine which values to include
    • Ds\Deque::find — Attempts to find a value's index
    • Ds\Deque::first — Returns the first value in the deque
    • Ds\Deque::get — Returns the value at a given index
    • Ds\Deque::insert — Inserts values at a given index
    • Ds\Deque::isEmpty — Returns whether the deque is empty
    • Ds\Deque::join — Joins all values together as a string
    • Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Deque::last — Returns the last value
    • Ds\Deque::map — Returns the result of applying a callback to each value
    • Ds\Deque::merge — Returns the result of adding all given values to the deque
    • Ds\Deque::pop — Removes and returns the last value
    • Ds\Deque::push — Adds values to the end of the deque
    • Ds\Deque::reduce — Reduces the deque to a single value using a callback function
    • Ds\Deque::remove — Removes and returns a value by index
    • Ds\Deque::reverse — Reverses the deque in-place
    • Ds\Deque::reversed — Returns a reversed copy
    • Ds\Deque::rotate — Rotates the deque by a given number of rotations
    • Ds\Deque::set — Updates a value at a given index
    • Ds\Deque::shift — Removes and returns the first value
    • Ds\Deque::slice — Returns a sub-deque of a given range
    • Ds\Deque::sort — Sorts the deque in-place
    • Ds\Deque::sorted — Returns a sorted copy
    • Ds\Deque::sum — Returns the sum of all values in the deque
    • Ds\Deque::toArray — Converts the deque to an array
    • Ds\Deque::unshift — Adds values to the front of the deque
  • Ds\Map — The Map class
    • Ds\Map::allocate — Allocates enough memory for a required capacity
    • Ds\Map::apply — Updates all values by applying a callback function to each value
    • Ds\Map::capacity — Returns the current capacity
    • Ds\Map::clear — Removes all values
    • Ds\Map::__construct — Creates a new instance
    • Ds\Map::copy — Returns a shallow copy of the map
    • Ds\Map::count — Returns the number of values in the map
    • Ds\Map::diff — Creates a new map using keys that aren't in another map
    • Ds\Map::filter — Creates a new map using a callable to determine which pairs to include
    • Ds\Map::first — Returns the first pair in the map
    • Ds\Map::get — Returns the value for a given key
    • Ds\Map::hasKey — Determines whether the map contains a given key
    • Ds\Map::hasValue — Determines whether the map contains a given value
    • Ds\Map::intersect — Creates a new map by intersecting keys with another map
    • Ds\Map::isEmpty — Returns whether the map is empty
    • Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Map::keys — Returns a set of the map's keys
    • Ds\Map::ksort — Sorts the map in-place by key
    • Ds\Map::ksorted — Returns a copy, sorted by key
    • Ds\Map::last — Returns the last pair of the map
    • Ds\Map::map — Returns the result of applying a callback to each value
    • Ds\Map::merge — Returns the result of adding all given associations
    • Ds\Map::pairs — Returns a sequence containing all the pairs of the map
    • Ds\Map::put — Associates a key with a value
    • Ds\Map::putAll — Associates all key-value pairs of a traversable object or array
    • Ds\Map::reduce — Reduces the map to a single value using a callback function
    • Ds\Map::remove — Removes and returns a value by key
    • Ds\Map::reverse — Reverses the map in-place
    • Ds\Map::reversed — Returns a reversed copy
    • Ds\Map::skip — Returns the pair at a given positional index
    • Ds\Map::slice — Returns a subset of the map defined by a starting index and length
    • Ds\Map::sort — Sorts the map in-place by value
    • Ds\Map::sorted — Returns a copy, sorted by value
    • Ds\Map::sum — Returns the sum of all values in the map
    • Ds\Map::toArray — Converts the map to an array
    • Ds\Map::union — Creates a new map using values from the current instance and another map
    • Ds\Map::values — Returns a sequence of the map's values
    • Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both
  • Ds\Pair — The Pair class
    • Ds\Pair::clear — Removes all values
    • Ds\Pair::__construct — Creates a new instance
    • Ds\Pair::copy — Returns a shallow copy of the pair
    • Ds\Pair::isEmpty — Returns whether the pair is empty
    • Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Pair::toArray — Converts the pair to an array
  • Ds\Set — The Set class
    • Ds\Set::add — Adds values to the set
    • Ds\Set::allocate — Allocates enough memory for a required capacity
    • Ds\Set::capacity — Returns the current capacity
    • Ds\Set::clear — Removes all values
    • Ds\Set::__construct — Creates a new instance
    • Ds\Set::contains — Determines if the set contains all values
    • Ds\Set::copy — Returns a shallow copy of the set
    • Ds\Set::count — Returns the number of values in the set
    • Ds\Set::diff — Creates a new set using values that aren't in another set
    • Ds\Set::filter — Creates a new set using a callable to determine which values to include
    • Ds\Set::first — Returns the first value in the set
    • Ds\Set::get — Returns the value at a given index
    • Ds\Set::intersect — Creates a new set by intersecting values with another set
    • Ds\Set::isEmpty — Returns whether the set is empty
    • Ds\Set::join — Joins all values together as a string
    • Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Set::last — Returns the last value in the set
    • Ds\Set::merge — Returns the result of adding all given values to the set
    • Ds\Set::reduce — Reduces the set to a single value using a callback function
    • Ds\Set::remove — Removes all given values from the set
    • Ds\Set::reverse — Reverses the set in-place
    • Ds\Set::reversed — Returns a reversed copy
    • Ds\Set::slice — Returns a sub-set of a given range
    • Ds\Set::sort — Sorts the set in-place
    • Ds\Set::sorted — Returns a sorted copy
    • Ds\Set::sum — Returns the sum of all values in the set
    • Ds\Set::toArray — Converts the set to an array
    • Ds\Set::union — Creates a new set using values from the current instance and another set
    • Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both
  • Ds\Stack — The Stack class
    • Ds\Stack::allocate — Allocates enough memory for a required capacity
    • Ds\Stack::capacity — Returns the current capacity
    • Ds\Stack::clear — Removes all values
    • Ds\Stack::__construct — Creates a new instance
    • Ds\Stack::copy — Returns a shallow copy of the stack
    • Ds\Stack::count — Returns the number of values in the stack
    • Ds\Stack::isEmpty — Returns whether the stack is empty
    • Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Stack::peek — Returns the value at the top of the stack
    • Ds\Stack::pop — Removes and returns the value at the top of the stack
    • Ds\Stack::push — Pushes values onto the stack
    • Ds\Stack::toArray — Converts the stack to an array
  • Ds\Queue — The Queue class
    • Ds\Queue::allocate — Allocates enough memory for a required capacity
    • Ds\Queue::capacity — Returns the current capacity
    • Ds\Queue::clear — Removes all values
    • Ds\Queue::__construct — Creates a new instance
    • Ds\Queue::copy — Returns a shallow copy of the queue
    • Ds\Queue::count — Returns the number of values in the queue
    • Ds\Queue::isEmpty — Returns whether the queue is empty
    • Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\Queue::peek — Returns the value at the front of the queue
    • Ds\Queue::pop — Removes and returns the value at the front of the queue
    • Ds\Queue::push — Pushes values into the queue
    • Ds\Queue::toArray — Converts the queue to an array
  • Ds\PriorityQueue — The PriorityQueue class
    • Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity
    • Ds\PriorityQueue::capacity — Returns the current capacity
    • Ds\PriorityQueue::clear — Removes all values
    • Ds\PriorityQueue::__construct — Creates a new instance
    • Ds\PriorityQueue::copy — Returns a shallow copy of the queue
    • Ds\PriorityQueue::count — Returns the number of values in the queue
    • Ds\PriorityQueue::isEmpty — Returns whether the queue is empty
    • Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON
    • Ds\PriorityQueue::peek — Returns the value at the front of the queue
    • Ds\PriorityQueue::pop — Removes and returns the value with the highest priority
    • Ds\PriorityQueue::push — Pushes values into the queue
    • Ds\PriorityQueue::toArray — Converts the queue to an array


はじめに

Efficient data structures for PHP 7, provided as an alternative to the array.

See » this blog post for benchmarks, discussion and frequently asked questions.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Data Structures
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

PHP 7 is required by both the extension and the compatibility polyfill.


インストール手順

The easiest way to install the extension is via » PECL

pecl install ds

You can also build directly from source:

# Dependencies you might need to install
# sudo apt-get install git build-essential php7.0-dev

git clone https://github.com/php-ds/extension "php-ds"
cd php-ds

# Build and install the extension
phpize
./configure
make
make install

# Clean up the build files
make clean
phpize --clean

If you're on Windows, you can » download a compiled .dll on PECL

注意:

If you're using Composer, it's highly recommended that you include » php-ds/php-ds in your project so that your code is still functional in an environment where the extension is not installed. The extension will take priority if installed.


例

例1 Vector

<?php

$vector = new \Ds\Vector();

$vector->push('a');
$vector->push('b', 'c');

$vector[] = 'd';

print_r($vector);

?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
)

例2 Map

<?php

$map = new \Ds\Map();

$map->put('a', 1);
$map->put('b', 2);

$map['c'] = 3;

print_r($map);

?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)


The Collection interface

(PECL ds >= 1.0.0)

はじめに

Collection is the base interface which covers functionality common to all the data structures in this library. It guarantees that all structures are traversable, countable, and can be converted to json using json_encode().

インターフェイス概要

interface Ds\Collection extends Countable, IteratorAggregate, JsonSerializable {
/* メソッド */
public clear(): void
public copy(): Ds\Collection
public isEmpty(): bool
public toArray(): array
/* 継承したメソッド */
public Countable::count(): int
public IteratorAggregate::getIterator(): Traversable
public JsonSerializable::jsonSerialize(): mixed
}

変更履歴

バージョン | 説明
PECL ds 1.4.0 | Collection implements IteratorAggregate now instead of just Traversable. (This change came to the polyfill in 1.4.1.)

目次

  • Ds\Collection::clear — Removes all values
  • Ds\Collection::copy — Returns a shallow copy of the collection
  • Ds\Collection::isEmpty — Returns whether the collection is empty
  • Ds\Collection::toArray — Converts the collection to an array


Removes all values

  • ≪ Ds\Collection
  • Ds\Collection::copy ≫
  • PHP Manual
  • Ds\Collection
  • Removes all values

Ds\Collection::clear

(PECL ds >= 1.0.0)

Ds\Collection::clear — Removes all values

説明

public Ds\Collection::clear(): void

Removes all values from the collection.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Collection::clear() example

<?php
$collection = new \Ds\Vector([1, 2, 3]);
print_r($collection);

$collection->clear();
print_r($collection);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
)


Returns a shallow copy of the collection

  • ≪ Ds\Collection::clear
  • Ds\Collection::isEmpty ≫
  • PHP Manual
  • Ds\Collection
  • Returns a shallow copy of the collection

Ds\Collection::copy

(PECL ds >= 1.0.0)

Ds\Collection::copy — Returns a shallow copy of the collection

説明

public Ds\Collection::copy(): Ds\Collection

Returns a shallow copy of the collection.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the collection.

例

例1 Ds\Collection::copy() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = $a->copy();

$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)


Returns whether the collection is empty

  • ≪ Ds\Collection::copy
  • Ds\Collection::toArray ≫
  • PHP Manual
  • Ds\Collection
  • Returns whether the collection is empty

Ds\Collection::isEmpty

(PECL ds >= 1.0.0)

Ds\Collection::isEmpty — Returns whether the collection is empty

説明

public Ds\Collection::isEmpty(): bool

Returns whether the collection is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the collection is empty, false otherwise.

例

例1 Ds\Collection::isEmpty() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = new \Ds\Vector();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Converts the collection to an array

  • ≪ Ds\Collection::isEmpty
  • Ds\Hashable ≫
  • PHP Manual
  • Ds\Collection
  • Converts the collection to an array

Ds\Collection::toArray

(PECL ds >= 1.0.0)

Ds\Collection::toArray — Converts the collection to an array

説明

public Ds\Collection::toArray(): array

Converts the collection to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the collection.

例

例1 Ds\Collection::toArray() example

<?php
$collection = new \Ds\Vector([1, 2, 3]);

var_dump($collection->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


The Hashable interface

(PECL ds >= 1.0.0)

はじめに

Hashable is an interface which allows objects to be used as keys. It's an alternative to spl_object_hash(), which determines an object's hash based on its handle: this means that two objects that are considered equal by an implicit definition would not treated as equal because they are not the same instance.

hash() is used to return a scalar value to be used as the object's hash value, which determines where it goes in the hash table. While this value does not have to be unique, objects which are equal must have the same hash value.

equals() is used to determine if two objects are equal. It's guaranteed that the comparing object will be an instance of the same class as the subject.

インターフェイス概要

interface Ds\Hashable {
/* メソッド */
abstract public equals(object $obj): bool
abstract public hash(): mixed
}

目次

  • Ds\Hashable::equals — Determines whether an object is equal to the current instance
  • Ds\Hashable::hash — Returns a scalar value to be used as a hash value


Determines whether an object is equal to the current instance

  • ≪ Ds\Hashable
  • Ds\Hashable::hash ≫
  • PHP Manual
  • Ds\Hashable
  • Determines whether an object is equal to the current instance

Ds\Hashable::equals

(PECL ds >= 1.0.0)

Ds\Hashable::equals — Determines whether an object is equal to the current instance

説明

abstract public Ds\Hashable::equals(object $obj): bool

Determines whether another object is equal to the current instance.

This method allows objects to be used as keys in structures such as Ds\Map and Ds\Set, or any other lookup structure that honors this interface.

注意:

It's guaranteed that obj is an instance of the same class.

警告

It's important that objects which are equal also have the same hash value. See Ds\Hashable::hash().

パラメータ

obj

The object to compare the current instance to, which is always an instance of the same class.

戻り値

true if equal, false otherwise.


Returns a scalar value to be used as a hash value

  • ≪ Ds\Hashable::equals
  • Ds\Sequence ≫
  • PHP Manual
  • Ds\Hashable
  • Returns a scalar value to be used as a hash value

Ds\Hashable::hash

(PECL ds >= 1.0.0)

Ds\Hashable::hash — Returns a scalar value to be used as a hash value

説明

abstract public Ds\Hashable::hash(): mixed

Returns a scalar value to be used as the hash value of the objects.

While the hash value does not define equality, all objects that are equal according to Ds\Hashable::equals() must have the same hash value. Hash values of equal objects don't have to be unique, for example you could just return true for all objects and nothing would break - the only implication would be that hash tables then turn into linked lists because all your objects will be hashed to the same bucket. It's therefore very important that you pick a good hash value, such as an ID or email address.

This method allows objects to be used as keys in structures such as Ds\Map and Ds\Set, or any other lookup structure that honors this interface.

警告

Do not pick a value that might change within the object, such as a public property. Hash table lookups would fail because the hash has changed.

警告

All objects that are equal must have the same hash value.

パラメータ

この関数にはパラメータはありません。

戻り値

A scalar value to be used as this object's hash value.

例

例1 Ds\Hashable::hash() example

<?php
class HashableObject implements \Ds\Hashable
{
private $name;
private $email;

public function __construct($name, $email)
{
$this->name = $name;
$this->email = $email;
}

/**
* Should return the same value for all equal objects, but doesn't have to
* be unique. This value will not be used to determine equality.
*/
public function hash()
{
return $this->email;
}

/**
* This determines equality, usually during a hash table lookup to determine
* if the bucket's key matches the lookup key. The hash has to be equal if
* the objects are equal, otherwise this determination wouldn't be reached.
*/
public function equals($obj): bool
{
return $this->name === $obj->name
&& $this->email === $obj->email;
}
}
?>


The Sequence interface

(PECL ds >= 1.0.0)

はじめに

A Sequence describes the behaviour of values arranged in a single, linear dimension. Some languages refer to this as a "List". It's similar to an array that uses incremental integer keys, with the exception of a few characteristics:

  • Values will always be indexed as [0, 1, 2, ..., size - 1].
  • Only allowed to access values by index in the range [0, size - 1].

Use cases:

  • Wherever you would use an array as a list (not concerned with keys).
  • A more efficient alternative to SplDoublyLinkedList and SplFixedArray.

インターフェイス概要

interface Ds\Sequence extends Ds\Collection, ArrayAccess {
/* メソッド */
abstract public allocate(int $capacity): void
abstract public apply(callable $callback): void
abstract public capacity(): int
abstract public contains(mixed ...$values): bool
abstract public filter(callable $callback = ?): Ds\Sequence
abstract public find(mixed $value): mixed
abstract public first(): mixed
abstract public get(int $index): mixed
abstract public insert(int $index, mixed ...$values): void
abstract public join(string $glue = ?): string
abstract public last(): mixed
abstract public map(callable $callback): Ds\Sequence
abstract public merge(mixed $values): Ds\Sequence
abstract public pop(): mixed
abstract public push(mixed ...$values): void
abstract public reduce(callable $callback, mixed $initial = ?): mixed
abstract public remove(int $index): mixed
abstract public reverse(): void
abstract public reversed(): Ds\Sequence
abstract public rotate(int $rotations): void
abstract public set(int $index, mixed $value): void
abstract public shift(): mixed
abstract public slice(int $index, int $length = ?): Ds\Sequence
abstract public sort(callable $comparator = ?): void
abstract public sorted(callable $comparator = ?): Ds\Sequence
abstract public sum(): int|float
abstract public unshift(mixed $values = ?): void
/* 継承したメソッド */
public Ds\Collection::clear(): void
public Ds\Collection::copy(): Ds\Collection
public Ds\Collection::isEmpty(): bool
public Ds\Collection::toArray(): array
public Countable::count(): int
public IteratorAggregate::getIterator(): Traversable
public JsonSerializable::jsonSerialize(): mixed
public ArrayAccess::offsetExists(mixed $offset): bool
public ArrayAccess::offsetGet(mixed $offset): mixed
public ArrayAccess::offsetSet(mixed $offset, mixed $value): void
public ArrayAccess::offsetUnset(mixed $offset): void
}

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The interface now extends ArrayAccess.

目次

  • Ds\Sequence::allocate — Allocates enough memory for a required capacity
  • Ds\Sequence::apply — Updates all values by applying a callback function to each value
  • Ds\Sequence::capacity — Returns the current capacity
  • Ds\Sequence::contains — Determines if the sequence contains given values
  • Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include
  • Ds\Sequence::find — Attempts to find a value's index
  • Ds\Sequence::first — Returns the first value in the sequence
  • Ds\Sequence::get — Returns the value at a given index
  • Ds\Sequence::insert — Inserts values at a given index
  • Ds\Sequence::join — Joins all values together as a string
  • Ds\Sequence::last — Returns the last value
  • Ds\Sequence::map — Returns the result of applying a callback to each value
  • Ds\Sequence::merge — Returns the result of adding all given values to the sequence
  • Ds\Sequence::pop — Removes and returns the last value
  • Ds\Sequence::push — Adds values to the end of the sequence
  • Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function
  • Ds\Sequence::remove — Removes and returns a value by index
  • Ds\Sequence::reverse — Reverses the sequence in-place
  • Ds\Sequence::reversed — Returns a reversed copy
  • Ds\Sequence::rotate — Rotates the sequence by a given number of rotations
  • Ds\Sequence::set — Updates a value at a given index
  • Ds\Sequence::shift — Removes and returns the first value
  • Ds\Sequence::slice — Returns a sub-sequence of a given range
  • Ds\Sequence::sort — Sorts the sequence in-place
  • Ds\Sequence::sorted — Returns a sorted copy
  • Ds\Sequence::sum — Returns the sum of all values in the sequence
  • Ds\Sequence::unshift — Adds values to the front of the sequence


Allocates enough memory for a required capacity

  • ≪ Ds\Sequence
  • Ds\Sequence::apply ≫
  • PHP Manual
  • Ds\Sequence
  • Allocates enough memory for a required capacity

Ds\Sequence::allocate

(PECL ds >= 1.0.0)

Ds\Sequence::allocate — Allocates enough memory for a required capacity

説明

abstract public Ds\Sequence::allocate(int $capacity): void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

戻り値

値を返しません。

例

例1 Ds\Sequence::allocate() example

<?php
$sequence = new \Ds\Vector();
var_dump($sequence->capacity());

$vector->allocate(100);
var_dump($sequence->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(100)


Updates all values by applying a callback function to each value

  • ≪ Ds\Sequence::allocate
  • Ds\Sequence::capacity ≫
  • PHP Manual
  • Ds\Sequence
  • Updates all values by applying a callback function to each value

Ds\Sequence::apply

(PECL ds >= 1.0.0)

Ds\Sequence::apply — Updates all values by applying a callback function to each value

説明

abstract public Ds\Sequence::apply(callable $callback): void

Updates all values by applying a callback function to each value in the sequence.

パラメータ

callback

callback(mixed $value): mixed

A callable to apply to each value in the sequence.

The callback should return what the value should be replaced by.

戻り値

値を返しません。

例

例1 Ds\Sequence::apply() example

<?php
$sequence = new \Ds\Sequence([1, 2, 3]);
$sequence->apply(function($value) { return $value * 2; });

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)


Returns the current capacity

  • ≪ Ds\Sequence::apply
  • Ds\Sequence::contains ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the current capacity

Ds\Sequence::capacity

(PECL ds >= 1.0.0)

Ds\Sequence::capacity — Returns the current capacity

説明

abstract public Ds\Sequence::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\Sequence::capacity() example

<?php
$sequence = new \Ds\Vector();
var_dump($sequence->capacity());

$sequence->push(...range(1, 50));
var_dump($sequence->capacity());

$sequence[] = "a";
var_dump($sequence->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(50)
int(75)


Determines if the sequence contains given values

  • ≪ Ds\Sequence::capacity
  • Ds\Sequence::filter ≫
  • PHP Manual
  • Ds\Sequence
  • Determines if the sequence contains given values

Ds\Sequence::contains

(PECL ds >= 1.0.0)

Ds\Sequence::contains — Determines if the sequence contains given values

説明

abstract public Ds\Sequence::contains(mixed ...$values): bool

Determines if the sequence contains all values.

パラメータ

values

Values to check.

戻り値

false if any of the provided values are not in the sequence, true otherwise.

例

例1 Ds\Sequence::contains() example

<?php
$sequence = new \Ds\Vector(['a', 'b', 'c', 1, 2, 3]);

var_dump($sequence->contains('a')); // true
var_dump($sequence->contains('a', 'b')); // true
var_dump($sequence->contains('c', 'd')); // false

var_dump($sequence->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($sequence->contains(1)); // true
var_dump($sequence->contains('1')); // false

var_dump($sequece->contains(...[])); // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)


Creates a new sequence using a callable to determine which values to include

  • ≪ Ds\Sequence::contains
  • Ds\Sequence::find ≫
  • PHP Manual
  • Ds\Sequence
  • Creates a new sequence using a callable to determine which values to include

Ds\Sequence::filter

(PECL ds >= 1.0.0)

Ds\Sequence::filter — Creates a new sequence using a callable to determine which values to include

説明

abstract public Ds\Sequence::filter(callable $callback = ?): Ds\Sequence

Creates a new sequence using a callable to determine which values to include.

パラメータ

callback

callback(mixed $value): bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

戻り値

A new sequence containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Sequence::filter() example using callback function

<?php
$sequence = new \Ds\Vector([1, 2, 3, 4, 5]);

var_dump($sequence->filter(function($value) {
return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Sequence::filter() example without a callback function

<?php
$sequence = new \Ds\Vector([0, 1, 'a', true, false]);

var_dump($sequence->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}


Attempts to find a value's index

  • ≪ Ds\Sequence::filter
  • Ds\Sequence::first ≫
  • PHP Manual
  • Ds\Sequence
  • Attempts to find a value's index

Ds\Sequence::find

(PECL ds >= 1.0.0)

Ds\Sequence::find — Attempts to find a value's index

説明

abstract public Ds\Sequence::find(mixed $value): mixed

Returns the index of the value, or false if not found.

パラメータ

value

The value to find.

戻り値

The index of the value, or false if not found.

注意:

Values will be compared by value and by type.

例

例1 Ds\Sequence::find() example

<?php
$sequence = new \Ds\Vector(["a", 1, true]);

var_dump($sequence->find("a")); // 0
var_dump($sequence->find("b")); // false
var_dump($sequence->find("1")); // false
var_dump($sequence->find(1)); // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
bool(false)
bool(false)
int(1)


Returns the first value in the sequence

  • ≪ Ds\Sequence::find
  • Ds\Sequence::get ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the first value in the sequence

Ds\Sequence::first

(PECL ds >= 1.0.0)

Ds\Sequence::first — Returns the first value in the sequence

説明

abstract public Ds\Sequence::first(): mixed

Returns the first value in the sequence.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value in the sequence.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::first() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)


Returns the value at a given index

  • ≪ Ds\Sequence::first
  • Ds\Sequence::insert ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the value at a given index

Ds\Sequence::get

(PECL ds >= 1.0.0)

Ds\Sequence::get — Returns the value at a given index

説明

abstract public Ds\Sequence::get(int $index): mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

戻り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::get() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->get(0));
var_dump($sequence->get(1));
var_dump($sequence->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Sequence::get() example using array syntax

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence[0]);
var_dump($sequence[1]);
var_dump($sequence[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Inserts values at a given index

  • ≪ Ds\Sequence::get
  • Ds\Sequence::join ≫
  • PHP Manual
  • Ds\Sequence
  • Inserts values at a given index

Ds\Sequence::insert

(PECL ds >= 1.0.0)

Ds\Sequence::insert — Inserts values at a given index

説明

abstract public Ds\Sequence::insert(int $index, mixed ...$values): void

Inserts values into the sequence at a given index.

パラメータ

index

The index at which to insert. 0 <= index <= count

注意:

You can insert at the index equal to the number of values.

values

The value or values to insert.

戻り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::insert() example

<?php
$sequence = new \Ds\Vector();

$sequence->insert(0, "e"); // [e]
$sequence->insert(1, "f"); // [e, f]
$sequence->insert(2, "g"); // [e, f, g]
$sequence->insert(0, "a", "b"); // [a, b, e, f, g]
$sequence->insert(2, ...["c", "d"]); // [a, b, c, d, e, f, g]

var_dump($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}


Joins all values together as a string

  • ≪ Ds\Sequence::insert
  • Ds\Sequence::last ≫
  • PHP Manual
  • Ds\Sequence
  • Joins all values together as a string

Ds\Sequence::join

(PECL ds >= 1.0.0)

Ds\Sequence::join — Joins all values together as a string

説明

abstract public Ds\Sequence::join(string $glue = ?): string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

戻り値

All values of the sequence joined together as a string.

例

例1 Ds\Sequence::join() example using a separator string

<?php
$sequence = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($sequence->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Sequence::join() example without a separator string

<?php
$sequence = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($sequence->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"


Returns the last value

  • ≪ Ds\Sequence::join
  • Ds\Sequence::map ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the last value

Ds\Sequence::last

(PECL ds >= 1.0.0)

Ds\Sequence::last — Returns the last value

説明

abstract public Ds\Sequence::last(): mixed

Returns the last value in the sequence.

パラメータ

この関数にはパラメータはありません。

戻り値

The last value in the sequence.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::last() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)


Returns the result of applying a callback to each value

  • ≪ Ds\Sequence::last
  • Ds\Sequence::merge ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the result of applying a callback to each value

Ds\Sequence::map

(PECL ds >= 1.0.0)

Ds\Sequence::map — Returns the result of applying a callback to each value

説明

abstract public Ds\Sequence::map(callable $callback): Ds\Sequence

Returns the result of applying a callback function to each value in the sequence.

パラメータ

callback

callback(mixed $value): mixed

A callable to apply to each value in the sequence.

The callable should return what the new value will be in the new sequence.

戻り値

The result of applying a callback to each value in the sequence.

注意:

The values of the current instance won't be affected.

例

例1 Ds\Sequence::map() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

print_r($sequence->map(function($value) { return $value * 2; }));
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)


Returns the result of adding all given values to the sequence

  • ≪ Ds\Sequence::map
  • Ds\Sequence::pop ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the result of adding all given values to the sequence

Ds\Sequence::merge

(PECL ds >= 1.0.0)

Ds\Sequence::merge — Returns the result of adding all given values to the sequence

説明

abstract public Ds\Sequence::merge(mixed $values): Ds\Sequence

Returns the result of adding all given values to the sequence.

パラメータ

values

A traversable object or an array.

戻り値

The result of adding all given values to the sequence, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Sequence::merge() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->merge([4, 5, 6]));
var_dump($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Removes and returns the last value

  • ≪ Ds\Sequence::merge
  • Ds\Sequence::push ≫
  • PHP Manual
  • Ds\Sequence
  • Removes and returns the last value

Ds\Sequence::pop

(PECL ds >= 1.0.0)

Ds\Sequence::pop — Removes and returns the last value

説明

abstract public Ds\Sequence::pop(): mixed

Removes and returns the last value.

パラメータ

この関数にはパラメータはありません。

戻り値

The removed last value.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::pop() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->pop());
var_dump($sequence->pop());
var_dump($sequence->pop());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(2)
int(1)


Adds values to the end of the sequence

  • ≪ Ds\Sequence::pop
  • Ds\Sequence::reduce ≫
  • PHP Manual
  • Ds\Sequence
  • Adds values to the end of the sequence

Ds\Sequence::push

(PECL ds >= 1.0.0)

Ds\Sequence::push — Adds values to the end of the sequence

説明

abstract public Ds\Sequence::push(mixed ...$values): void

Adds values to the end of the sequence.

パラメータ

values

The values to add.

戻り値

値を返しません。

例

例1 Ds\Sequence::push() example

<?php
$sequence = new \Ds\Vector();

$sequence->push("a");
$sequence->push("b");
$sequence->push("c", "d");
$sequence->push(...["e", "f"]);

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)


Reduces the sequence to a single value using a callback function

  • ≪ Ds\Sequence::push
  • Ds\Sequence::remove ≫
  • PHP Manual
  • Ds\Sequence
  • Reduces the sequence to a single value using a callback function

Ds\Sequence::reduce

(PECL ds >= 1.0.0)

Ds\Sequence::reduce — Reduces the sequence to a single value using a callback function

説明

abstract public Ds\Sequence::reduce(callable $callback, mixed $initial = ?): mixed

Reduces the sequence to a single value using a callback function.

パラメータ

callback
callback(mixed $carry, mixed $value): mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

戻り値

The return value of the final callback.

例

例1 Ds\Sequence::reduce() with initial value example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

$callback = function($carry, $value) {
return $carry * $value;
};

var_dump($sequence->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 = 5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Sequence::reduce() without an initial value example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

var_dump($sequence->reduce(function($carry, $value) {
return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 = 6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)


Removes and returns a value by index

  • ≪ Ds\Sequence::reduce
  • Ds\Sequence::reverse ≫
  • PHP Manual
  • Ds\Sequence
  • Removes and returns a value by index

Ds\Sequence::remove

(PECL ds >= 1.0.0)

Ds\Sequence::remove — Removes and returns a value by index

説明

abstract public Ds\Sequence::remove(int $index): mixed

Removes and returns a value by index.

パラメータ

index

The index of the value to remove.

戻り値

The value that was removed.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::remove() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->remove(1));
var_dump($sequence->remove(0));
var_dump($sequence->remove(0));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "a"
string(1) "c"


Reverses the sequence in-place

  • ≪ Ds\Sequence::remove
  • Ds\Sequence::reversed ≫
  • PHP Manual
  • Ds\Sequence
  • Reverses the sequence in-place

Ds\Sequence::reverse

(PECL ds >= 1.0.0)

Ds\Sequence::reverse — Reverses the sequence in-place

説明

abstract public Ds\Sequence::reverse(): void

Reverses the sequence in-place.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Sequence::reverse() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);
$sequence->reverse();

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)


Returns a reversed copy

  • ≪ Ds\Sequence::reverse
  • Ds\Sequence::rotate ≫
  • PHP Manual
  • Ds\Sequence
  • Returns a reversed copy

Ds\Sequence::reversed

(PECL ds >= 1.0.0)

Ds\Sequence::reversed — Returns a reversed copy

説明

abstract public Ds\Sequence::reversed(): Ds\Sequence

Returns a reversed copy of the sequence.

パラメータ

この関数にはパラメータはありません。

戻り値

A reversed copy of the sequence.

注意:

The current instance is not affected.

例

例1 Ds\Sequence::reversed() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

print_r($sequence->reversed());
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
)


Rotates the sequence by a given number of rotations

  • ≪ Ds\Sequence::reversed
  • Ds\Sequence::set ≫
  • PHP Manual
  • Ds\Sequence
  • Rotates the sequence by a given number of rotations

Ds\Sequence::rotate

(PECL ds >= 1.0.0)

Ds\Sequence::rotate — Rotates the sequence by a given number of rotations

説明

abstract public Ds\Sequence::rotate(int $rotations): void

Rotates the sequence by a given number of rotations, which is equivalent to successively calling $sequence->push($sequence->shift()) if the number of rotations is positive, or $sequence->unshift($sequence->pop()) if negative.

パラメータ

rotations

The number of times the sequence should be rotated.

戻り値

値を返しません。. The sequence of the current instance will be rotated.

例

例1 Ds\Sequence::rotate() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c", "d"]);

$sequence->rotate(1); // "a" is shifted, then pushed.
print_r($sequence);

$sequence->rotate(2); // "b" and "c" are both shifted, the pushed.
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Vector Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)


Updates a value at a given index

  • ≪ Ds\Sequence::rotate
  • Ds\Sequence::shift ≫
  • PHP Manual
  • Ds\Sequence
  • Updates a value at a given index

Ds\Sequence::set

(PECL ds >= 1.0.0)

Ds\Sequence::set — Updates a value at a given index

説明

abstract public Ds\Sequence::set(int $index, mixed $value): void

Updates a value at a given index.

パラメータ

index

The index of the value to update.

value

The new value.

戻り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Sequence::set() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

$sequence->set(1, "_");
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

例2 Ds\Sequence::set() example using array syntax

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

$sequence[1] = "_";
print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)


Removes and returns the first value

  • ≪ Ds\Sequence::set
  • Ds\Sequence::slice ≫
  • PHP Manual
  • Ds\Sequence
  • Removes and returns the first value

Ds\Sequence::shift

(PECL ds >= 1.0.0)

Ds\Sequence::shift — Removes and returns the first value

説明

abstract public Ds\Sequence::shift(): mixed

Removes and returns the first value.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value, which was removed.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Sequence::shift() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c"]);

var_dump($sequence->shift());
var_dump($sequence->shift());
var_dump($sequence->shift());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Returns a sub-sequence of a given range

  • ≪ Ds\Sequence::shift
  • Ds\Sequence::sort ≫
  • PHP Manual
  • Ds\Sequence
  • Returns a sub-sequence of a given range

Ds\Sequence::slice

(PECL ds >= 1.0.0)

Ds\Sequence::slice — Returns a sub-sequence of a given range

説明

abstract public Ds\Sequence::slice(int $index, int $length = ?): Ds\Sequence

Creates a sub-sequence of a given range.

パラメータ

index

The index at which the sub-sequence starts.

If positive, the sequence will start at that index in the sequence. If negative, the sequence will start that far from the end.

length

If a length is given and is positive, the resulting sequence will have up to that many values in it. If the length results in an overflow, only values up to the end of the sequence will be included. If a length is given and is negative, the sequence will stop that many values from the end. If a length is not provided, the resulting sequence will contain all values between the index and the end of the sequence.

戻り値

A sub-sequence of the given range.

例

例1 Ds\Sequence::slice() example

<?php
$sequence = new \Ds\Vector(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($sequence->slice(2));

// Slice from 1, for a length of 3
print_r($sequence->slice(1, 3));

// Slice from 1 onwards
print_r($sequence->slice(1));

// Slice from 2 from the end onwards
print_r($sequence->slice(-2));

// Slice from 1 to 1 from the end
print_r($sequence->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Vector Object
(
    [0] => d
    [1] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)


Sorts the sequence in-place

  • ≪ Ds\Sequence::slice
  • Ds\Sequence::sorted ≫
  • PHP Manual
  • Ds\Sequence
  • Sorts the sequence in-place

Ds\Sequence::sort

(PECL ds >= 1.0.0)

Ds\Sequence::sort — Sorts the sequence in-place

説明

abstract public Ds\Sequence::sort(callable $comparator = ?): void

Sorts the sequence in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

値を返しません。

例

例1 Ds\Sequence::sort() example

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);
$sequence->sort();

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Sequence::sort() example using a comparator

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

$sequence->sort(function($a, $b) {
return $b <=> $a;
});

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns a sorted copy

  • ≪ Ds\Sequence::sort
  • Ds\Sequence::sum ≫
  • PHP Manual
  • Ds\Sequence
  • Returns a sorted copy

Ds\Sequence::sorted

(PECL ds >= 1.0.0)

Ds\Sequence::sorted — Returns a sorted copy

説明

abstract public Ds\Sequence::sorted(callable $comparator = ?): Ds\Sequence

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

Returns a sorted copy of the sequence.

例

例1 Ds\Sequence::sorted() example

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

print_r($sequence->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Sequence::sorted() example using a comparator

<?php
$sequence = new \Ds\Vector([4, 5, 1, 3, 2]);

$sorted = $sequence->sorted(function($a, $b) {
return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns the sum of all values in the sequence

  • ≪ Ds\Sequence::sorted
  • Ds\Sequence::unshift ≫
  • PHP Manual
  • Ds\Sequence
  • Returns the sum of all values in the sequence

Ds\Sequence::sum

(PECL ds >= 1.0.0)

Ds\Sequence::sum — Returns the sum of all values in the sequence

説明

abstract public Ds\Sequence::sum(): int|float

Returns the sum of all values in the sequence.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

戻り値

The sum of all the values in the sequence as either a float or int depending on the values in the sequence.

例

例1 Ds\Sequence::sum() integer example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);
var_dump($sequence->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Sequence::sum() float example

<?php
$sequence = new \Ds\Vector([1, 2.5, 3]);
var_dump($sequence->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)


Adds values to the front of the sequence

  • ≪ Ds\Sequence::sum
  • Ds\Vector ≫
  • PHP Manual
  • Ds\Sequence
  • Adds values to the front of the sequence

Ds\Sequence::unshift

(PECL ds >= 1.0.0)

Ds\Sequence::unshift — Adds values to the front of the sequence

説明

abstract public Ds\Sequence::unshift(mixed $values = ?): void

Adds values to the front of the sequence, moving all the current values forward to make room for the new values.

パラメータ

values

The values to add to the front of the sequence.

注意:

Multiple values will be added in the same order that they are passed.

戻り値

値を返しません。

例

例1 Ds\Sequence::unshift() example

<?php
$sequence = new \Ds\Vector([1, 2, 3]);

$sequence->unshift("a");
$sequence->unshift("b", "c");

print_r($sequence);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)


The Vector class

(PECL ds >= 1.0.0)

はじめに

A Vector is a sequence of values in a contiguous buffer that grows and shrinks automatically. It's the most efficient sequential structure because a value's index is a direct mapping to its index in the buffer, and the growth factor isn't bound to a specific multiple or exponent.

Strengths

  • Supports array syntax (square brackets).
  • Uses less overall memory than an array for the same number of values.
  • Automatically frees allocated memory when its size drops low enough.
  • Capacity does not have to be a power of 2.
  • get(),
set(),
push(),
pop() are all O(1).

Weaknesses

  • shift(),
unshift(),
insert() and
remove() are all O(n).

クラス概要

class Ds\Vector implements Ds\Sequence, ArrayAccess {
/* 定数 */
const int MIN_CAPACITY = 10;
/* メソッド */
public allocate(int $capacity): void
public apply(callable $callback): void
public capacity(): int
public clear(): void
public contains(mixed ...$values): bool
public copy(): Ds\Vector
public filter(callable $callback = ?): Ds\Vector
public find(mixed $value): mixed
public first(): mixed
public get(int $index): mixed
public insert(int $index, mixed ...$values): void
public isEmpty(): bool
public join(string $glue = ?): string
public last(): mixed
public map(callable $callback): Ds\Vector
public merge(mixed $values): Ds\Vector
public pop(): mixed
public push(mixed ...$values): void
public reduce(callable $callback, mixed $initial = ?): mixed
public remove(int $index): mixed
public reverse(): void
public reversed(): Ds\Vector
public rotate(int $rotations): void
public set(int $index, mixed $value): void
public shift(): mixed
public slice(int $index, int $length = ?): Ds\Vector
public sort(callable $comparator = ?): void
public sorted(callable $comparator = ?): Ds\Vector
public sum(): int|float
public toArray(): array
public unshift(mixed $values = ?): void
}

定義済み定数

Ds\Vector::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Vector::allocate — Allocates enough memory for a required capacity
  • Ds\Vector::apply — Updates all values by applying a callback function to each value
  • Ds\Vector::capacity — Returns the current capacity
  • Ds\Vector::clear — Removes all values
  • Ds\Vector::__construct — Creates a new instance
  • Ds\Vector::contains — Determines if the vector contains given values
  • Ds\Vector::copy — Returns a shallow copy of the vector
  • Ds\Vector::count — Returns the number of values in the collection
  • Ds\Vector::filter — Creates a new vector using a callable to determine which values to include
  • Ds\Vector::find — Attempts to find a value's index
  • Ds\Vector::first — Returns the first value in the vector
  • Ds\Vector::get — Returns the value at a given index
  • Ds\Vector::insert — Inserts values at a given index
  • Ds\Vector::isEmpty — Returns whether the vector is empty
  • Ds\Vector::join — Joins all values together as a string
  • Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Vector::last — Returns the last value
  • Ds\Vector::map — Returns the result of applying a callback to each value
  • Ds\Vector::merge — Returns the result of adding all given values to the vector
  • Ds\Vector::pop — Removes and returns the last value
  • Ds\Vector::push — Adds values to the end of the vector
  • Ds\Vector::reduce — Reduces the vector to a single value using a callback function
  • Ds\Vector::remove — Removes and returns a value by index
  • Ds\Vector::reverse — Reverses the vector in-place
  • Ds\Vector::reversed — Returns a reversed copy
  • Ds\Vector::rotate — Rotates the vector by a given number of rotations
  • Ds\Vector::set — Updates a value at a given index
  • Ds\Vector::shift — Removes and returns the first value
  • Ds\Vector::slice — Returns a sub-vector of a given range
  • Ds\Vector::sort — Sorts the vector in-place
  • Ds\Vector::sorted — Returns a sorted copy
  • Ds\Vector::sum — Returns the sum of all values in the vector
  • Ds\Vector::toArray — Converts the vector to an array
  • Ds\Vector::unshift — Adds values to the front of the vector


Allocates enough memory for a required capacity

  • ≪ Ds\Vector
  • Ds\Vector::apply ≫
  • PHP Manual
  • Ds\Vector
  • Allocates enough memory for a required capacity

Ds\Vector::allocate

(PECL ds >= 1.0.0)

Ds\Vector::allocate — Allocates enough memory for a required capacity

説明

public Ds\Vector::allocate(int $capacity): void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

戻り値

値を返しません。

例

例1 Ds\Vector::allocate() example

<?php
$vector = new \Ds\Vector();
var_dump($vector->capacity());

$vector->allocate(100);
var_dump($vector->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(100)


Updates all values by applying a callback function to each value

  • ≪ Ds\Vector::allocate
  • Ds\Vector::capacity ≫
  • PHP Manual
  • Ds\Vector
  • Updates all values by applying a callback function to each value

Ds\Vector::apply

(PECL ds >= 1.0.0)

Ds\Vector::apply — Updates all values by applying a callback function to each value

説明

public Ds\Vector::apply(callable $callback): void

Updates all values by applying a callback function to each value in the vector.

パラメータ

callback

callback(mixed $value): mixed

A callable to apply to each value in the vector.

The callback should return what the value should be replaced by.

戻り値

値を返しません。

例

例1 Ds\Vector::apply() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
$vector->apply(function($value) { return $value * 2; });

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)


Returns the current capacity

  • ≪ Ds\Vector::apply
  • Ds\Vector::clear ≫
  • PHP Manual
  • Ds\Vector
  • Returns the current capacity

Ds\Vector::capacity

(PECL ds >= 1.0.0)

Ds\Vector::capacity — Returns the current capacity

説明

public Ds\Vector::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\Vector::capacity() example

<?php
$vector = new \Ds\Vector();
var_dump($vector->capacity());

$vector->push(...range(1, 50));
var_dump($vector->capacity());

$vector[] = "a";
var_dump($vector->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(10)
int(50)
int(75)


Removes all values

  • ≪ Ds\Vector::capacity
  • Ds\Vector::__construct ≫
  • PHP Manual
  • Ds\Vector
  • Removes all values

Ds\Vector::clear

(PECL ds >= 1.0.0)

Ds\Vector::clear — Removes all values

説明

public Ds\Vector::clear(): void

Removes all values from the vector.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Vector::clear() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
print_r($vector);

$vector->clear();
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
)


Creates a new instance

  • ≪ Ds\Vector::clear
  • Ds\Vector::contains ≫
  • PHP Manual
  • Ds\Vector
  • Creates a new instance

Ds\Vector::__construct

(PECL ds >= 1.0.0)

Ds\Vector::__construct — Creates a new instance

説明

public Ds\Vector::__construct(mixed $values = ?)

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Vector::__construct() example

<?php
$vector = new \Ds\Vector();
var_dump($vector);

$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (0) {
}
object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Determines if the vector contains given values

  • ≪ Ds\Vector::__construct
  • Ds\Vector::copy ≫
  • PHP Manual
  • Ds\Vector
  • Determines if the vector contains given values

Ds\Vector::contains

(PECL ds >= 1.0.0)

Ds\Vector::contains — Determines if the vector contains given values

説明

public Ds\Vector::contains(mixed ...$values): bool

Determines if the vector contains all values.

パラメータ

values

Values to check.

戻り値

false if any of the provided values are not in the vector, true otherwise.

例

例1 Ds\Vector::contains() example

<?php
$vector = new \Ds\Vector(['a', 'b', 'c', 1, 2, 3]);

var_dump($vector->contains('a')); // true
var_dump($vector->contains('a', 'b')); // true
var_dump($vector->contains('c', 'd')); // false

var_dump($vector->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($vector->contains(1)); // true
var_dump($vector->contains('1')); // false

var_dump($sequece->contains(...[])); // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)


Returns a shallow copy of the vector

  • ≪ Ds\Vector::contains
  • Ds\Vector::count ≫
  • PHP Manual
  • Ds\Vector
  • Returns a shallow copy of the vector

Ds\Vector::copy

(PECL ds >= 1.0.0)

Ds\Vector::copy — Returns a shallow copy of the vector

説明

public Ds\Vector::copy(): Ds\Vector

Returns a shallow copy of the vector.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the vector.

例

例1 Ds\Vector::copy() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)


Returns the number of values in the collection

  • ≪ Ds\Vector::copy
  • Ds\Vector::filter ≫
  • PHP Manual
  • Ds\Vector
  • Returns the number of values in the collection

Ds\Vector::count

(PECL ds >= 1.0.0)

Ds\Vector::count — Returns the number of values in the collection

説明

See Countable::count()


Creates a new vector using a callable to determine which values to include

  • ≪ Ds\Vector::count
  • Ds\Vector::find ≫
  • PHP Manual
  • Ds\Vector
  • Creates a new vector using a callable to determine which values to include

Ds\Vector::filter

(PECL ds >= 1.0.0)

Ds\Vector::filter — Creates a new vector using a callable to determine which values to include

説明

public Ds\Vector::filter(callable $callback = ?): Ds\Vector

Creates a new vector using a callable to determine which values to include.

パラメータ

callback

callback(mixed $value): bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

戻り値

A new vector containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Vector::filter() example using callback function

<?php
$vector = new \Ds\Vector([1, 2, 3, 4, 5]);

var_dump($vector->filter(function($value) {
return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Vector::filter() example without a callback function

<?php
$vector = new \Ds\Vector([0, 1, 'a', true, false]);

var_dump($vector->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}


Attempts to find a value's index

  • ≪ Ds\Vector::filter
  • Ds\Vector::first ≫
  • PHP Manual
  • Ds\Vector
  • Attempts to find a value's index

Ds\Vector::find

(PECL ds >= 1.0.0)

Ds\Vector::find — Attempts to find a value's index

説明

public Ds\Vector::find(mixed $value): mixed

Returns the index of the value, or false if not found.

パラメータ

value

The value to find.

戻り値

The index of the value, or false if not found.

注意:

Values will be compared by value and by type.

例

例1 Ds\Vector::find() example

<?php
$vector = new \Ds\Vector(["a", 1, true]);

var_dump($vector->find("a")); // 0
var_dump($vector->find("b")); // false
var_dump($vector->find("1")); // false
var_dump($vector->find(1)); // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
bool(false)
bool(false)
int(1)


Returns the first value in the vector

  • ≪ Ds\Vector::find
  • Ds\Vector::get ≫
  • PHP Manual
  • Ds\Vector
  • Returns the first value in the vector

Ds\Vector::first

(PECL ds >= 1.0.0)

Ds\Vector::first — Returns the first value in the vector

説明

public Ds\Vector::first(): mixed

Returns the first value in the vector.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value in the vector.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::first() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)


Returns the value at a given index

  • ≪ Ds\Vector::first
  • Ds\Vector::insert ≫
  • PHP Manual
  • Ds\Vector
  • Returns the value at a given index

Ds\Vector::get

(PECL ds >= 1.0.0)

Ds\Vector::get — Returns the value at a given index

説明

public Ds\Vector::get(int $index): mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

戻り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::get() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->get(0));
var_dump($vector->get(1));
var_dump($vector->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Vector::get() example using array syntax

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector[0]);
var_dump($vector[1]);
var_dump($vector[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Inserts values at a given index

  • ≪ Ds\Vector::get
  • Ds\Vector::isEmpty ≫
  • PHP Manual
  • Ds\Vector
  • Inserts values at a given index

Ds\Vector::insert

(PECL ds >= 1.0.0)

Ds\Vector::insert — Inserts values at a given index

説明

public Ds\Vector::insert(int $index, mixed ...$values): void

Inserts values into the vector at a given index.

パラメータ

index

The index at which to insert. 0 <= index <= count

注意:

You can insert at the index equal to the number of values.

values

The value or values to insert.

戻り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::insert() example

<?php
$vector = new \Ds\Vector();

$vector->insert(0, "e"); // [e]
$vector->insert(1, "f"); // [e, f]
$vector->insert(2, "g"); // [e, f, g]
$vector->insert(0, "a", "b"); // [a, b, e, f, g]
$vector->insert(2, ...["c", "d"]); // [a, b, c, d, e, f, g]

var_dump($vector);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}


Returns whether the vector is empty

  • ≪ Ds\Vector::insert
  • Ds\Vector::join ≫
  • PHP Manual
  • Ds\Vector
  • Returns whether the vector is empty

Ds\Vector::isEmpty

(PECL ds >= 1.0.0)

Ds\Vector::isEmpty — Returns whether the vector is empty

説明

public Ds\Vector::isEmpty(): bool

Returns whether the vector is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the vector is empty, false otherwise.

例

例1 Ds\Vector::isEmpty() example

<?php
$a = new \Ds\Vector([1, 2, 3]);
$b = new \Ds\Vector();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Joins all values together as a string

  • ≪ Ds\Vector::isEmpty
  • Ds\Vector::jsonSerialize ≫
  • PHP Manual
  • Ds\Vector
  • Joins all values together as a string

Ds\Vector::join

(PECL ds >= 1.0.0)

Ds\Vector::join — Joins all values together as a string

説明

public Ds\Vector::join(string $glue = ?): string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

戻り値

All values of the vector joined together as a string.

例

例1 Ds\Vector::join() example using a separator string

<?php
$vector = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($vector->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Vector::join() example without a separator string

<?php
$vector = new \Ds\Vector(["a", "b", "c", 1, 2, 3]);

var_dump($vector->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"


Returns a representation that can be converted to JSON

  • ≪ Ds\Vector::join
  • Ds\Vector::last ≫
  • PHP Manual
  • Ds\Vector
  • Returns a representation that can be converted to JSON

Ds\Vector::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Vector::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns the last value

  • ≪ Ds\Vector::jsonSerialize
  • Ds\Vector::map ≫
  • PHP Manual
  • Ds\Vector
  • Returns the last value

Ds\Vector::last

(PECL ds >= 1.0.0)

Ds\Vector::last — Returns the last value

説明

public Ds\Vector::last(): mixed

Returns the last value in the vector.

パラメータ

この関数にはパラメータはありません。

戻り値

The last value in the vector.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::last() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)


Returns the result of applying a callback to each value

  • ≪ Ds\Vector::last
  • Ds\Vector::merge ≫
  • PHP Manual
  • Ds\Vector
  • Returns the result of applying a callback to each value

Ds\Vector::map

(PECL ds >= 1.0.0)

Ds\Vector::map — Returns the result of applying a callback to each value

説明

public Ds\Vector::map(callable $callback): Ds\Vector

Returns the result of applying a callback function to each value in the vector.

パラメータ

callback

callback(mixed $value): mixed

A callable to apply to each value in the vector.

The callable should return what the new value will be in the new vector.

戻り値

The result of applying a callback to each value in the vector.

注意:

The values of the current instance won't be affected.

例

例1 Ds\Vector::map() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

print_r($vector->map(function($value) { return $value * 2; }));
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)


Returns the result of adding all given values to the vector

  • ≪ Ds\Vector::map
  • Ds\Vector::pop ≫
  • PHP Manual
  • Ds\Vector
  • Returns the result of adding all given values to the vector

Ds\Vector::merge

(PECL ds >= 1.0.0)

Ds\Vector::merge — Returns the result of adding all given values to the vector

説明

public Ds\Vector::merge(mixed $values): Ds\Vector

Returns the result of adding all given values to the vector.

パラメータ

values

A traversable object or an array.

戻り値

The result of adding all given values to the vector, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Vector::merge() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->merge([4, 5, 6]));
var_dump($vector);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Vector)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Removes and returns the last value

  • ≪ Ds\Vector::merge
  • Ds\Vector::push ≫
  • PHP Manual
  • Ds\Vector
  • Removes and returns the last value

Ds\Vector::pop

(PECL ds >= 1.0.0)

Ds\Vector::pop — Removes and returns the last value

説明

public Ds\Vector::pop(): mixed

Removes and returns the last value.

パラメータ

この関数にはパラメータはありません。

戻り値

The removed last value.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::pop() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->pop());
var_dump($vector->pop());
var_dump($vector->pop());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(2)
int(1)


Adds values to the end of the vector

  • ≪ Ds\Vector::pop
  • Ds\Vector::reduce ≫
  • PHP Manual
  • Ds\Vector
  • Adds values to the end of the vector

Ds\Vector::push

(PECL ds >= 1.0.0)

Ds\Vector::push — Adds values to the end of the vector

説明

public Ds\Vector::push(mixed ...$values): void

Adds values to the end of the vector.

パラメータ

values

The values to add.

戻り値

値を返しません。

例

例1 Ds\Vector::push() example

<?php
$vector = new \Ds\Vector();

$vector->push("a");
$vector->push("b");
$vector->push("c", "d");
$vector->push(...["e", "f"]);

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)


Reduces the vector to a single value using a callback function

  • ≪ Ds\Vector::push
  • Ds\Vector::remove ≫
  • PHP Manual
  • Ds\Vector
  • Reduces the vector to a single value using a callback function

Ds\Vector::reduce

(PECL ds >= 1.0.0)

Ds\Vector::reduce — Reduces the vector to a single value using a callback function

説明

public Ds\Vector::reduce(callable $callback, mixed $initial = ?): mixed

Reduces the vector to a single value using a callback function.

パラメータ

callback
callback(mixed $carry, mixed $value): mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

戻り値

The return value of the final callback.

例

例1 Ds\Vector::reduce() with initial value example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

$callback = function($carry, $value) {
return $carry * $value;
};

var_dump($vector->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 = 5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Vector::reduce() without an initial value example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->reduce(function($carry, $value) {
return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 = 6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)


Removes and returns a value by index

  • ≪ Ds\Vector::reduce
  • Ds\Vector::reverse ≫
  • PHP Manual
  • Ds\Vector
  • Removes and returns a value by index

Ds\Vector::remove

(PECL ds >= 1.0.0)

Ds\Vector::remove — Removes and returns a value by index

説明

public Ds\Vector::remove(int $index): mixed

Removes and returns a value by index.

パラメータ

index

The index of the value to remove.

戻り値

The value that was removed.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::remove() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->remove(1));
var_dump($vector->remove(0));
var_dump($vector->remove(0));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "a"
string(1) "c"


Reverses the vector in-place

  • ≪ Ds\Vector::remove
  • Ds\Vector::reversed ≫
  • PHP Manual
  • Ds\Vector
  • Reverses the vector in-place

Ds\Vector::reverse

(PECL ds >= 1.0.0)

Ds\Vector::reverse — Reverses the vector in-place

説明

public Ds\Vector::reverse(): void

Reverses the vector in-place.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Vector::reverse() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);
$vector->reverse();

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)


Returns a reversed copy

  • ≪ Ds\Vector::reverse
  • Ds\Vector::rotate ≫
  • PHP Manual
  • Ds\Vector
  • Returns a reversed copy

Ds\Vector::reversed

(PECL ds >= 1.0.0)

Ds\Vector::reversed — Returns a reversed copy

説明

public Ds\Vector::reversed(): Ds\Vector

Returns a reversed copy of the vector.

パラメータ

この関数にはパラメータはありません。

戻り値

A reversed copy of the vector.

注意:

The current instance is not affected.

例

例1 Ds\Vector::reversed() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

print_r($vector->reversed());
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Vector Object
(
    [0] => a
    [1] => b
    [2] => c
)


Rotates the vector by a given number of rotations

  • ≪ Ds\Vector::reversed
  • Ds\Vector::set ≫
  • PHP Manual
  • Ds\Vector
  • Rotates the vector by a given number of rotations

Ds\Vector::rotate

(PECL ds >= 1.0.0)

Ds\Vector::rotate — Rotates the vector by a given number of rotations

説明

public Ds\Vector::rotate(int $rotations): void

Rotates the vector by a given number of rotations, which is equivalent to successively calling $vector->push($vector->shift()) if the number of rotations is positive, or $vector->unshift($vector->pop()) if negative.

パラメータ

rotations

The number of times the vector should be rotated.

戻り値

値を返しません。. The vector of the current instance will be rotated.

例

例1 Ds\Vector::rotate() example

<?php
$vector = new \Ds\Vector(["a", "b", "c", "d"]);

$vector->rotate(1); // "a" is shifted, then pushed.
print_r($vector);

$vector->rotate(2); // "b" and "c" are both shifted, the pushed.
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Vector Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)


Updates a value at a given index

  • ≪ Ds\Vector::rotate
  • Ds\Vector::shift ≫
  • PHP Manual
  • Ds\Vector
  • Updates a value at a given index

Ds\Vector::set

(PECL ds >= 1.0.0)

Ds\Vector::set — Updates a value at a given index

説明

public Ds\Vector::set(int $index, mixed $value): void

Updates a value at a given index.

パラメータ

index

The index of the value to update.

value

The new value.

戻り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Vector::set() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

$vector->set(1, "_");
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)

例2 Ds\Vector::set() example using array syntax

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

$vector[1] = "_";
print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => a
    [1] => _
    [2] => c
)


Removes and returns the first value

  • ≪ Ds\Vector::set
  • Ds\Vector::slice ≫
  • PHP Manual
  • Ds\Vector
  • Removes and returns the first value

Ds\Vector::shift

(PECL ds >= 1.0.0)

Ds\Vector::shift — Removes and returns the first value

説明

public Ds\Vector::shift(): mixed

Removes and returns the first value.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value, which was removed.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Vector::shift() example

<?php
$vector = new \Ds\Vector(["a", "b", "c"]);

var_dump($vector->shift());
var_dump($vector->shift());
var_dump($vector->shift());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Returns a sub-vector of a given range

  • ≪ Ds\Vector::shift
  • Ds\Vector::sort ≫
  • PHP Manual
  • Ds\Vector
  • Returns a sub-vector of a given range

Ds\Vector::slice

(PECL ds >= 1.0.0)

Ds\Vector::slice — Returns a sub-vector of a given range

説明

public Ds\Vector::slice(int $index, int $length = ?): Ds\Vector

Creates a sub-vector of a given range.

パラメータ

index

The index at which the sub-vector starts.

If positive, the vector will start at that index in the vector. If negative, the vector will start that far from the end.

length

If a length is given and is positive, the resulting vector will have up to that many values in it. If the length results in an overflow, only values up to the end of the vector will be included. If a length is given and is negative, the vector will stop that many values from the end. If a length is not provided, the resulting vector will contain all values between the index and the end of the vector.

戻り値

A sub-vector of the given range.

例

例1 Ds\Vector::slice() example

<?php
$vector = new \Ds\Vector(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($vector->slice(2));

// Slice from 1, for a length of 3
print_r($vector->slice(1, 3));

// Slice from 1 onwards
print_r($vector->slice(1));

// Slice from 2 from the end onwards
print_r($vector->slice(-2));

// Slice from 1 to 1 from the end
print_r($vector->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Vector Object
(
    [0] => d
    [1] => e
)
Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => d
)


Sorts the vector in-place

  • ≪ Ds\Vector::slice
  • Ds\Vector::sorted ≫
  • PHP Manual
  • Ds\Vector
  • Sorts the vector in-place

Ds\Vector::sort

(PECL ds >= 1.0.0)

Ds\Vector::sort — Sorts the vector in-place

説明

public Ds\Vector::sort(callable $comparator = ?): void

Sorts the vector in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

値を返しません。

例

例1 Ds\Vector::sort() example

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);
$vector->sort();

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Vector::sort() example using a comparator

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

$vector->sort(function($a, $b) {
return $b <=> $a;
});

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns a sorted copy

  • ≪ Ds\Vector::sort
  • Ds\Vector::sum ≫
  • PHP Manual
  • Ds\Vector
  • Returns a sorted copy

Ds\Vector::sorted

(PECL ds >= 1.0.0)

Ds\Vector::sorted — Returns a sorted copy

説明

public Ds\Vector::sorted(callable $comparator = ?): Ds\Vector

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

Returns a sorted copy of the vector.

例

例1 Ds\Vector::sorted() example

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

print_r($vector->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Vector::sorted() example using a comparator

<?php
$vector = new \Ds\Vector([4, 5, 1, 3, 2]);

$sorted = $vector->sorted(function($a, $b) {
return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns the sum of all values in the vector

  • ≪ Ds\Vector::sorted
  • Ds\Vector::toArray ≫
  • PHP Manual
  • Ds\Vector
  • Returns the sum of all values in the vector

Ds\Vector::sum

(PECL ds >= 1.0.0)

Ds\Vector::sum — Returns the sum of all values in the vector

説明

public Ds\Vector::sum(): int|float

Returns the sum of all values in the vector.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

戻り値

The sum of all the values in the vector as either a float or int depending on the values in the vector.

例

例1 Ds\Vector::sum() integer example

<?php
$vector = new \Ds\Vector([1, 2, 3]);
var_dump($vector->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Vector::sum() float example

<?php
$vector = new \Ds\Vector([1, 2.5, 3]);
var_dump($vector->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)


Converts the vector to an array

  • ≪ Ds\Vector::sum
  • Ds\Vector::unshift ≫
  • PHP Manual
  • Ds\Vector
  • Converts the vector to an array

Ds\Vector::toArray

(PECL ds >= 1.0.0)

Ds\Vector::toArray — Converts the vector to an array

説明

public Ds\Vector::toArray(): array

Converts the vector to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the vector.

例

例1 Ds\Vector::toArray() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

var_dump($vector->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Adds values to the front of the vector

  • ≪ Ds\Vector::toArray
  • Ds\Deque ≫
  • PHP Manual
  • Ds\Vector
  • Adds values to the front of the vector

Ds\Vector::unshift

(PECL ds >= 1.0.0)

Ds\Vector::unshift — Adds values to the front of the vector

説明

public Ds\Vector::unshift(mixed $values = ?): void

Adds values to the front of the vector, moving all the current values forward to make room for the new values.

パラメータ

values

The values to add to the front of the vector.

注意:

Multiple values will be added in the same order that they are passed.

戻り値

値を返しません。

例

例1 Ds\Vector::unshift() example

<?php
$vector = new \Ds\Vector([1, 2, 3]);

$vector->unshift("a");
$vector->unshift("b", "c");

print_r($vector);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Vector Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)


The Deque class

(PECL ds >= 1.0.0)

はじめに

A Deque (pronounced "deck") is a sequence of values in a contiguous buffer that grows and shrinks automatically. The name is a common abbreviation of "double-ended queue" and is used internally by Ds\Queue.

Two pointers are used to keep track of a head and a tail. The pointers can "wrap around" the end of the buffer, which avoids the need to move other values around to make room. This makes shift and unshift very fast?—? something a Ds\Vector can't compete with.

Accessing a value by index requires a translation between the index and its corresponding position in the buffer: ((head + position) % capacity).

Strengths

  • Supports array syntax (square brackets).
  • Uses less overall memory than an array for the same number of values.
  • Automatically frees allocated memory when its size drops low enough.
  • get(),
set(),
push(),
pop(),
shift(), and
unshift() are all O(1).

Weaknesses

  • Capacity must be a power of 2.
  • insert() and remove() are O(n).

クラス概要

class Ds\Deque implements Ds\Sequence, ArrayAccess {
/* 定数 */
const int MIN_CAPACITY = 8;
/* メソッド */
public allocate(int $capacity): void
public apply(callable $callback): void
public capacity(): int
public clear(): void
public contains(mixed ...$values): bool
public copy(): Ds\Deque
public filter(callable $callback = ?): Ds\Deque
public find(mixed $value): mixed
public first(): mixed
public get(int $index): mixed
public insert(int $index, mixed ...$values): void
public isEmpty(): bool
public join(string $glue = ?): string
public last(): mixed
public map(callable $callback): Ds\Deque
public merge(mixed $values): Ds\Deque
public pop(): mixed
public push(mixed ...$values): void
public reduce(callable $callback, mixed $initial = ?): mixed
public remove(int $index): mixed
public reverse(): void
public reversed(): Ds\Deque
public rotate(int $rotations): void
public set(int $index, mixed $value): void
public shift(): mixed
public slice(int $index, int $length = ?): Ds\Deque
public sort(callable $comparator = ?): void
public sorted(callable $comparator = ?): Ds\Deque
public sum(): int|float
public toArray(): array
public unshift(mixed $values = ?): void
}

定義済み定数

Ds\Deque::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Deque::allocate — Allocates enough memory for a required capacity
  • Ds\Deque::apply — Updates all values by applying a callback function to each value
  • Ds\Deque::capacity — Returns the current capacity
  • Ds\Deque::clear — Removes all values from the deque
  • Ds\Deque::__construct — Creates a new instance
  • Ds\Deque::contains — Determines if the deque contains given values
  • Ds\Deque::copy — Returns a shallow copy of the deque
  • Ds\Deque::count — Returns the number of values in the collection
  • Ds\Deque::filter — Creates a new deque using a callable to determine which values to include
  • Ds\Deque::find — Attempts to find a value's index
  • Ds\Deque::first — Returns the first value in the deque
  • Ds\Deque::get — Returns the value at a given index
  • Ds\Deque::insert — Inserts values at a given index
  • Ds\Deque::isEmpty — Returns whether the deque is empty
  • Ds\Deque::join — Joins all values together as a string
  • Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Deque::last — Returns the last value
  • Ds\Deque::map — Returns the result of applying a callback to each value
  • Ds\Deque::merge — Returns the result of adding all given values to the deque
  • Ds\Deque::pop — Removes and returns the last value
  • Ds\Deque::push — Adds values to the end of the deque
  • Ds\Deque::reduce — Reduces the deque to a single value using a callback function
  • Ds\Deque::remove — Removes and returns a value by index
  • Ds\Deque::reverse — Reverses the deque in-place
  • Ds\Deque::reversed — Returns a reversed copy
  • Ds\Deque::rotate — Rotates the deque by a given number of rotations
  • Ds\Deque::set — Updates a value at a given index
  • Ds\Deque::shift — Removes and returns the first value
  • Ds\Deque::slice — Returns a sub-deque of a given range
  • Ds\Deque::sort — Sorts the deque in-place
  • Ds\Deque::sorted — Returns a sorted copy
  • Ds\Deque::sum — Returns the sum of all values in the deque
  • Ds\Deque::toArray — Converts the deque to an array
  • Ds\Deque::unshift — Adds values to the front of the deque


Allocates enough memory for a required capacity

  • ≪ Ds\Deque
  • Ds\Deque::apply ≫
  • PHP Manual
  • Ds\Deque
  • Allocates enough memory for a required capacity

Ds\Deque::allocate

(PECL ds >= 1.0.0)

Ds\Deque::allocate — Allocates enough memory for a required capacity

説明

public Ds\Deque::allocate(int $capacity): void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

戻り値

値を返しません。

例

例1 Ds\Deque::allocate() example

<?php
$deque = new \Ds\Deque();
var_dump($deque->capacity());

$deque->allocate(100);
var_dump($deque->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(128)


Updates all values by applying a callback function to each value

  • ≪ Ds\Deque::allocate
  • Ds\Deque::capacity ≫
  • PHP Manual
  • Ds\Deque
  • Updates all values by applying a callback function to each value

Ds\Deque::apply

(PECL ds >= 1.0.0)

Ds\Deque::apply — Updates all values by applying a callback function to each value

説明

public Ds\Deque::apply(callable $callback): void

Updates all values by applying a callback function to each value in the deque.

パラメータ

callback

callback(mixed $value): mixed

A callable to apply to each value in the deque.

The callback should return what the value should be replaced by.

戻り値

値を返しません。

例

例1 Ds\Deque::apply() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
$deque->apply(function($value) { return $value * 2; });

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)


Returns the current capacity

  • ≪ Ds\Deque::apply
  • Ds\Deque::clear ≫
  • PHP Manual
  • Ds\Deque
  • Returns the current capacity

Ds\Deque::capacity

(PECL ds >= 1.0.0)

Ds\Deque::capacity — Returns the current capacity

説明

public Ds\Deque::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\Deque::capacity() example

<?php
$deque = new \Ds\Deque();
var_dump($deque->capacity());

$deque->push(...range(1, 50));
var_dump($deque->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(64)


Removes all values from the deque

  • ≪ Ds\Deque::capacity
  • Ds\Deque::__construct ≫
  • PHP Manual
  • Ds\Deque
  • Removes all values from the deque

Ds\Deque::clear

(PECL ds >= 1.0.0)

Ds\Deque::clear — Removes all values from the deque

説明

public Ds\Deque::clear(): void

Removes all values from the deque.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Deque::clear() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
print_r($deque);

$deque->clear();
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Deque Object
(
)


Creates a new instance

  • ≪ Ds\Deque::clear
  • Ds\Deque::contains ≫
  • PHP Manual
  • Ds\Deque
  • Creates a new instance

Ds\Deque::__construct

(PECL ds >= 1.0.0)

Ds\Deque::__construct — Creates a new instance

説明

public Ds\Deque::__construct(mixed $values = ?)

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Deque::__construct() example

<?php
$deque = new \Ds\Deque();
var_dump($deque);

$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#2 (0) {
}
object(Ds\Deque)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Determines if the deque contains given values

  • ≪ Ds\Deque::__construct
  • Ds\Deque::copy ≫
  • PHP Manual
  • Ds\Deque
  • Determines if the deque contains given values

Ds\Deque::contains

(PECL ds >= 1.0.0)

Ds\Deque::contains — Determines if the deque contains given values

説明

public Ds\Deque::contains(mixed ...$values): bool

Determines if the deque contains all values.

パラメータ

values

Values to check.

戻り値

false if any of the provided values are not in the deque, true otherwise.

例

例1 Ds\Deque::contains() example

<?php
$deque = new \Ds\Deque(['a', 'b', 'c', 1, 2, 3]);

var_dump($deque->contains('a')); // true
var_dump($deque->contains('a', 'b')); // true
var_dump($deque->contains('c', 'd')); // false

var_dump($deque->contains(...['c', 'b', 'a'])); // true

// Always strict
var_dump($deque->contains(1)); // true
var_dump($deque->contains('1')); // false

var_dump($sequece->contains(...[])); // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(false)
bool(true)
bool(true)
bool(false)
bool(true)


Returns a shallow copy of the deque

  • ≪ Ds\Deque::contains
  • Ds\Deque::count ≫
  • PHP Manual
  • Ds\Deque
  • Returns a shallow copy of the deque

Ds\Deque::copy

(PECL ds >= 1.0.0)

Ds\Deque::copy — Returns a shallow copy of the deque

説明

public Ds\Deque::copy(): Ds\Deque

Returns a shallow copy of the deque.

パラメータ

この関数にはパラメータはありません。

戻り値

A shallow copy of the deque.

例

例1 Ds\Deque::copy() example

<?php
$a = new \Ds\Deque([1, 2, 3]);
$b = $a->copy();

$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)


Returns the number of values in the collection

  • ≪ Ds\Deque::copy
  • Ds\Deque::filter ≫
  • PHP Manual
  • Ds\Deque
  • Returns the number of values in the collection

Ds\Deque::count

(PECL ds >= 1.0.0)

Ds\Deque::count — Returns the number of values in the collection

説明

See Countable::count()


Creates a new deque using a callable to determine which values to include

  • ≪ Ds\Deque::count
  • Ds\Deque::find ≫
  • PHP Manual
  • Ds\Deque
  • Creates a new deque using a callable to determine which values to include

Ds\Deque::filter

(PECL ds >= 1.0.0)

Ds\Deque::filter — Creates a new deque using a callable to determine which values to include

説明

public Ds\Deque::filter(callable $callback = ?): Ds\Deque

Creates a new deque using a callable to determine which values to include.

パラメータ

callback

callback(mixed $value): bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

戻り値

A new deque containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Deque::filter() example using callback function

<?php
$deque = new \Ds\Deque([1, 2, 3, 4, 5]);

var_dump($deque->filter(function($value) {
return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Deque::filter() example without a callback function

<?php
$deque = new \Ds\Deque([0, 1, 'a', true, false]);

var_dump($deque->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}


Attempts to find a value's index

  • ≪ Ds\Deque::filter
  • Ds\Deque::first ≫
  • PHP Manual
  • Ds\Deque
  • Attempts to find a value's index

Ds\Deque::find

(PECL ds >= 1.0.0)

Ds\Deque::find — Attempts to find a value's index

説明

public Ds\Deque::find(mixed $value): mixed

Returns the index of the value, or false if not found.

パラメータ

value

The value to find.

戻り値

The index of the value, or false if not found.

注意:

Values will be compared by value and by type.

例

例1 Ds\Deque::find() example

<?php
$deque = new \Ds\Deque(["a", 1, true]);

var_dump($deque->find("a")); // 0
var_dump($deque->find("b")); // false
var_dump($deque->find("1")); // false
var_dump($deque->find(1)); // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(0)
bool(false)
bool(false)
int(1)


Returns the first value in the deque

  • ≪ Ds\Deque::find
  • Ds\Deque::get ≫
  • PHP Manual
  • Ds\Deque
  • Returns the first value in the deque

Ds\Deque::first

(PECL ds >= 1.0.0)

Ds\Deque::first — Returns the first value in the deque

説明

public Ds\Deque::first(): mixed

Returns the first value in the deque.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value in the deque.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::first() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)


Returns the value at a given index

  • ≪ Ds\Deque::first
  • Ds\Deque::insert ≫
  • PHP Manual
  • Ds\Deque
  • Returns the value at a given index

Ds\Deque::get

(PECL ds >= 1.0.0)

Ds\Deque::get — Returns the value at a given index

説明

public Ds\Deque::get(int $index): mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

戻り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::get() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->get(0));
var_dump($deque->get(1));
var_dump($deque->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Deque::get() example using array syntax

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque[0]);
var_dump($deque[1]);
var_dump($deque[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Inserts values at a given index

  • ≪ Ds\Deque::get
  • Ds\Deque::isEmpty ≫
  • PHP Manual
  • Ds\Deque
  • Inserts values at a given index

Ds\Deque::insert

(PECL ds >= 1.0.0)

Ds\Deque::insert — Inserts values at a given index

説明

public Ds\Deque::insert(int $index, mixed ...$values): void

Inserts values into the deque at a given index.

パラメータ

index

The index at which to insert. 0 <= index <= count

注意:

You can insert at the index equal to the number of values.

values

The value or values to insert.

戻り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::insert() example

<?php
$deque = new \Ds\Deque();

$deque->insert(0, "e"); // [e]
$deque->insert(1, "f"); // [e, f]
$deque->insert(2, "g"); // [e, f, g]
$deque->insert(0, "a", "b"); // [a, b, e, f, g]
$deque->insert(2, ...["c", "d"]); // [a, b, c, d, e, f, g]

var_dump($deque);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#1 (7) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
  [3]=>
  string(1) "d"
  [4]=>
  string(1) "e"
  [5]=>
  string(1) "f"
  [6]=>
  string(1) "g"
}


Returns whether the deque is empty

  • ≪ Ds\Deque::insert
  • Ds\Deque::join ≫
  • PHP Manual
  • Ds\Deque
  • Returns whether the deque is empty

Ds\Deque::isEmpty

(PECL ds >= 1.0.0)

Ds\Deque::isEmpty — Returns whether the deque is empty

説明

public Ds\Deque::isEmpty(): bool

Returns whether the deque is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the deque is empty, false otherwise.

例

例1 Ds\Deque::isEmpty() example

<?php
$a = new \Ds\Deque([1, 2, 3]);
$b = new \Ds\Deque();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Joins all values together as a string

  • ≪ Ds\Deque::isEmpty
  • Ds\Deque::jsonSerialize ≫
  • PHP Manual
  • Ds\Deque
  • Joins all values together as a string

Ds\Deque::join

(PECL ds >= 1.0.0)

Ds\Deque::join — Joins all values together as a string

説明

public Ds\Deque::join(string $glue = ?): string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

戻り値

All values of the deque joined together as a string.

例

例1 Ds\Deque::join() example using a separator string

<?php
$deque = new \Ds\Deque(["a", "b", "c", 1, 2, 3]);

var_dump($deque->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Deque::join() example without a separator string

<?php
$deque = new \Ds\Deque(["a", "b", "c", 1, 2, 3]);

var_dump($deque->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"


Returns a representation that can be converted to JSON

  • ≪ Ds\Deque::join
  • Ds\Deque::last ≫
  • PHP Manual
  • Ds\Deque
  • Returns a representation that can be converted to JSON

Ds\Deque::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Deque::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns the last value

  • ≪ Ds\Deque::jsonSerialize
  • Ds\Deque::map ≫
  • PHP Manual
  • Ds\Deque
  • Returns the last value

Ds\Deque::last

(PECL ds >= 1.0.0)

Ds\Deque::last — Returns the last value

説明

public Ds\Deque::last(): mixed

Returns the last value in the deque.

パラメータ

この関数にはパラメータはありません。

戻り値

The last value in the deque.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::last() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)


Returns the result of applying a callback to each value

  • ≪ Ds\Deque::last
  • Ds\Deque::merge ≫
  • PHP Manual
  • Ds\Deque
  • Returns the result of applying a callback to each value

Ds\Deque::map

(PECL ds >= 1.0.0)

Ds\Deque::map — Returns the result of applying a callback to each value

説明

public Ds\Deque::map(callable $callback): Ds\Deque

Returns the result of applying a callback function to each value in the deque.

パラメータ

callback

callback(mixed $value): mixed

A callable to apply to each value in the deque.

The callable should return what the new value will be in the new deque.

戻り値

The result of applying a callback to each value in the deque.

注意:

The values of the current instance won't be affected.

例

例1 Ds\Deque::map() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

print_r($deque->map(function($value) { return $value * 2; }));
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 2
    [1] => 4
    [2] => 6
)
Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)


Returns the result of adding all given values to the deque

  • ≪ Ds\Deque::map
  • Ds\Deque::pop ≫
  • PHP Manual
  • Ds\Deque
  • Returns the result of adding all given values to the deque

Ds\Deque::merge

(PECL ds >= 1.0.0)

Ds\Deque::merge — Returns the result of adding all given values to the deque

説明

public Ds\Deque::merge(mixed $values): Ds\Deque

Returns the result of adding all given values to the deque.

パラメータ

values

A traversable object or an array.

戻り値

The result of adding all given values to the deque, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Deque::merge() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->merge([4, 5, 6]));
var_dump($deque);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Deque)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
  [5]=>
  int(6)
}
object(Ds\Deque)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Removes and returns the last value

  • ≪ Ds\Deque::merge
  • Ds\Deque::push ≫
  • PHP Manual
  • Ds\Deque
  • Removes and returns the last value

Ds\Deque::pop

(PECL ds >= 1.0.0)

Ds\Deque::pop — Removes and returns the last value

説明

public Ds\Deque::pop(): mixed

Removes and returns the last value.

パラメータ

この関数にはパラメータはありません。

戻り値

The removed last value.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::pop() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->pop());
var_dump($deque->pop());
var_dump($deque->pop());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(2)
int(1)


Adds values to the end of the deque

  • ≪ Ds\Deque::pop
  • Ds\Deque::reduce ≫
  • PHP Manual
  • Ds\Deque
  • Adds values to the end of the deque

Ds\Deque::push

(PECL ds >= 1.0.0)

Ds\Deque::push — Adds values to the end of the deque

説明

public Ds\Deque::push(mixed ...$values): void

Adds values to the end of the deque.

パラメータ

values

The values to add.

戻り値

値を返しません。

例

例1 Ds\Deque::push() example

<?php
$deque = new \Ds\Deque();

$deque->push("a");
$deque->push("b");
$deque->push("c", "d");
$deque->push(...["e", "f"]);

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)


Reduces the deque to a single value using a callback function

  • ≪ Ds\Deque::push
  • Ds\Deque::remove ≫
  • PHP Manual
  • Ds\Deque
  • Reduces the deque to a single value using a callback function

Ds\Deque::reduce

(PECL ds >= 1.0.0)

Ds\Deque::reduce — Reduces the deque to a single value using a callback function

説明

public Ds\Deque::reduce(callable $callback, mixed $initial = ?): mixed

Reduces the deque to a single value using a callback function.

パラメータ

callback
callback(mixed $carry, mixed $value): mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

戻り値

The return value of the final callback.

例

例1 Ds\Deque::reduce() with initial value example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

$callback = function($carry, $value) {
return $carry * $value;
};

var_dump($deque->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 = 5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Deque::reduce() without an initial value example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->reduce(function($carry, $value) {
return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 = 6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)


Removes and returns a value by index

  • ≪ Ds\Deque::reduce
  • Ds\Deque::reverse ≫
  • PHP Manual
  • Ds\Deque
  • Removes and returns a value by index

Ds\Deque::remove

(PECL ds >= 1.0.0)

Ds\Deque::remove — Removes and returns a value by index

説明

public Ds\Deque::remove(int $index): mixed

Removes and returns a value by index.

パラメータ

index

The index of the value to remove.

戻り値

The value that was removed.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::remove() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->remove(1));
var_dump($deque->remove(0));
var_dump($deque->remove(0));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "a"
string(1) "c"


Reverses the deque in-place

  • ≪ Ds\Deque::remove
  • Ds\Deque::reversed ≫
  • PHP Manual
  • Ds\Deque
  • Reverses the deque in-place

Ds\Deque::reverse

(PECL ds >= 1.0.0)

Ds\Deque::reverse — Reverses the deque in-place

説明

public Ds\Deque::reverse(): void

Reverses the deque in-place.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Deque::reverse() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);
$deque->reverse();

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => c
    [1] => b
    [2] => a
)


Returns a reversed copy

  • ≪ Ds\Deque::reverse
  • Ds\Deque::rotate ≫
  • PHP Manual
  • Ds\Deque
  • Returns a reversed copy

Ds\Deque::reversed

(PECL ds >= 1.0.0)

Ds\Deque::reversed — Returns a reversed copy

説明

public Ds\Deque::reversed(): Ds\Deque

Returns a reversed copy of the deque.

パラメータ

この関数にはパラメータはありません。

戻り値

A reversed copy of the deque.

注意:

The current instance is not affected.

例

例1 Ds\Deque::reversed() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

print_r($deque->reversed());
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Deque Object
(
    [0] => a
    [1] => b
    [2] => c
)


Rotates the deque by a given number of rotations

  • ≪ Ds\Deque::reversed
  • Ds\Deque::set ≫
  • PHP Manual
  • Ds\Deque
  • Rotates the deque by a given number of rotations

Ds\Deque::rotate

(PECL ds >= 1.0.0)

Ds\Deque::rotate — Rotates the deque by a given number of rotations

説明

public Ds\Deque::rotate(int $rotations): void

Rotates the deque by a given number of rotations, which is equivalent to successively calling $deque->push($deque->shift()) if the number of rotations is positive, or $deque->unshift($deque->pop()) if negative.

パラメータ

rotations

The number of times the deque should be rotated.

戻り値

値を返しません。. The deque of the current instance will be rotated.

例

例1 Ds\Deque::rotate() example

<?php
$deque = new \Ds\Deque(["a", "b", "c", "d"]);

$deque->rotate(1); // "a" is shifted, then pushed.
print_r($deque);

$deque->rotate(2); // "b" and "c" are both shifted, the pushed.
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => b
    [1] => c
    [2] => d
    [3] => a
)
Ds\Deque Object
(
    [0] => d
    [1] => a
    [2] => b
    [3] => c
)


Updates a value at a given index

  • ≪ Ds\Deque::rotate
  • Ds\Deque::shift ≫
  • PHP Manual
  • Ds\Deque
  • Updates a value at a given index

Ds\Deque::set

(PECL ds >= 1.0.0)

Ds\Deque::set — Updates a value at a given index

説明

public Ds\Deque::set(int $index, mixed $value): void

Updates a value at a given index.

パラメータ

index

The index of the value to update.

value

The new value.

戻り値

値を返しません。

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Deque::set() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

$deque->set(1, "_");
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => a
    [1] => _
    [2] => c
)

例2 Ds\Deque::set() example using array syntax

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

$deque[1] = "_";
print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => a
    [1] => _
    [2] => c
)


Removes and returns the first value

  • ≪ Ds\Deque::set
  • Ds\Deque::slice ≫
  • PHP Manual
  • Ds\Deque
  • Removes and returns the first value

Ds\Deque::shift

(PECL ds >= 1.0.0)

Ds\Deque::shift — Removes and returns the first value

説明

public Ds\Deque::shift(): mixed

Removes and returns the first value.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value, which was removed.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Deque::shift() example

<?php
$deque = new \Ds\Deque(["a", "b", "c"]);

var_dump($deque->shift());
var_dump($deque->shift());
var_dump($deque->shift());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Returns a sub-deque of a given range

  • ≪ Ds\Deque::shift
  • Ds\Deque::sort ≫
  • PHP Manual
  • Ds\Deque
  • Returns a sub-deque of a given range

Ds\Deque::slice

(PECL ds >= 1.0.0)

Ds\Deque::slice — Returns a sub-deque of a given range

説明

public Ds\Deque::slice(int $index, int $length = ?): Ds\Deque

Creates a sub-deque of a given range.

パラメータ

index

The index at which the sub-deque starts.

If positive, the deque will start at that index in the deque. If negative, the deque will start that far from the end.

length

If a length is given and is positive, the resulting deque will have up to that many values in it. If the length results in an overflow, only values up to the end of the deque will be included. If a length is given and is negative, the deque will stop that many values from the end. If a length is not provided, the resulting deque will contain all values between the index and the end of the deque.

戻り値

A sub-deque of the given range.

例

例1 Ds\Deque::slice() example

<?php
$deque = new \Ds\Deque(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($deque->slice(2));

// Slice from 1, for a length of 3
print_r($deque->slice(1, 3));

// Slice from 1 onwards
print_r($deque->slice(1));

// Slice from 2 from the end onwards
print_r($deque->slice(-2));

// Slice from 1 to 1 from the end
print_r($deque->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Deque Object
(
    [0] => d
    [1] => e
)
Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => d
)


Sorts the deque in-place

  • ≪ Ds\Deque::slice
  • Ds\Deque::sorted ≫
  • PHP Manual
  • Ds\Deque
  • Sorts the deque in-place

Ds\Deque::sort

(PECL ds >= 1.0.0)

Ds\Deque::sort — Sorts the deque in-place

説明

public Ds\Deque::sort(callable $comparator = ?): void

Sorts the deque in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

値を返しません。

例

例1 Ds\Deque::sort() example

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);
$deque->sort();

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Deque::sort() example using a comparator

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

$deque->sort(function($a, $b) {
return $b <=> $a;
});

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns a sorted copy

  • ≪ Ds\Deque::sort
  • Ds\Deque::sum ≫
  • PHP Manual
  • Ds\Deque
  • Returns a sorted copy

Ds\Deque::sorted

(PECL ds >= 1.0.0)

Ds\Deque::sorted — Returns a sorted copy

説明

public Ds\Deque::sorted(callable $comparator = ?): Ds\Deque

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

Returns a sorted copy of the deque.

例

例1 Ds\Deque::sorted() example

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

print_r($deque->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Deque::sorted() example using a comparator

<?php
$deque = new \Ds\Deque([4, 5, 1, 3, 2]);

$sorted = $deque->sorted(function($a, $b) {
return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns the sum of all values in the deque

  • ≪ Ds\Deque::sorted
  • Ds\Deque::toArray ≫
  • PHP Manual
  • Ds\Deque
  • Returns the sum of all values in the deque

Ds\Deque::sum

(PECL ds >= 1.0.0)

Ds\Deque::sum — Returns the sum of all values in the deque

説明

public Ds\Deque::sum(): int|float

Returns the sum of all values in the deque.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

戻り値

The sum of all the values in the deque as either a float or int depending on the values in the deque.

例

例1 Ds\Deque::sum() integer example

<?php
$deque = new \Ds\Deque([1, 2, 3]);
var_dump($deque->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Deque::sum() float example

<?php
$deque = new \Ds\Deque([1, 2.5, 3]);
var_dump($deque->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)


Converts the deque to an array

  • ≪ Ds\Deque::sum
  • Ds\Deque::unshift ≫
  • PHP Manual
  • Ds\Deque
  • Converts the deque to an array

Ds\Deque::toArray

(PECL ds >= 1.0.0)

Ds\Deque::toArray — Converts the deque to an array

説明

public Ds\Deque::toArray(): array

Converts the deque to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the deque.

例

例1 Ds\Deque::toArray() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

var_dump($deque->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Adds values to the front of the deque

  • ≪ Ds\Deque::toArray
  • Ds\Map ≫
  • PHP Manual
  • Ds\Deque
  • Adds values to the front of the deque

Ds\Deque::unshift

(PECL ds >= 1.0.0)

Ds\Deque::unshift — Adds values to the front of the deque

説明

public Ds\Deque::unshift(mixed $values = ?): void

Adds values to the front of the deque, moving all the current values forward to make room for the new values.

パラメータ

values

The values to add to the front of the deque.

注意:

Multiple values will be added in the same order that they are passed.

戻り値

値を返しません。

例

例1 Ds\Deque::unshift() example

<?php
$deque = new \Ds\Deque([1, 2, 3]);

$deque->unshift("a");
$deque->unshift("b", "c");

print_r($deque);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Deque Object
(
    [0] => b
    [1] => c
    [2] => a
    [3] => 1
    [4] => 2
    [5] => 3
)


The Map class

(PECL ds >= 1.0.0)

はじめに

A Map is a sequential collection of key-value pairs, almost identical to an array used in a similar context. Keys can be any type, but must be unique. Values are replaced if added to the map using the same key.

Strengths

  • Keys and values can be any type, including objects.
  • Supports array syntax (square brackets).
  • Insertion order is preserved.
  • Performance and memory efficiency is very similar to an array.
  • Automatically frees allocated memory when its size drops low enough.

Weaknesses

  • Can't be converted to an array when objects are used as keys.

クラス概要

class Ds\Map implements Ds\Collection, ArrayAccess {
/* 定数 */
const int MIN_CAPACITY = 16;
/* メソッド */
public allocate(int $capacity): void
public apply(callable $callback): void
public capacity(): int
public clear(): void
public copy(): Ds\Map
public diff(Ds\Map $map): Ds\Map
public filter(callable $callback = ?): Ds\Map
public first(): Ds\Pair
public get(mixed $key, mixed $default = ?): mixed
public hasKey(mixed $key): bool
public hasValue(mixed $value): bool
public intersect(Ds\Map $map): Ds\Map
public isEmpty(): bool
public keys(): Ds\Set
public ksort(callable $comparator = ?): void
public ksorted(callable $comparator = ?): Ds\Map
public last(): Ds\Pair
public map(callable $callback): Ds\Map
public merge(mixed $values): Ds\Map
public pairs(): Ds\Sequence
public put(mixed $key, mixed $value): void
public putAll(mixed $pairs): void
public reduce(callable $callback, mixed $initial = ?): mixed
public remove(mixed $key, mixed $default = ?): mixed
public reverse(): void
public reversed(): Ds\Map
public skip(int $position): Ds\Pair
public slice(int $index, int $length = ?): Ds\Map
public sort(callable $comparator = ?): void
public sorted(callable $comparator = ?): Ds\Map
public sum(): int|float
public toArray(): array
public union(Ds\Map $map): Ds\Map
public values(): Ds\Sequence
public xor(Ds\Map $map): Ds\Map
}

定義済み定数

Ds\Map::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Map::allocate — Allocates enough memory for a required capacity
  • Ds\Map::apply — Updates all values by applying a callback function to each value
  • Ds\Map::capacity — Returns the current capacity
  • Ds\Map::clear — Removes all values
  • Ds\Map::__construct — Creates a new instance
  • Ds\Map::copy — Returns a shallow copy of the map
  • Ds\Map::count — Returns the number of values in the map
  • Ds\Map::diff — Creates a new map using keys that aren't in another map
  • Ds\Map::filter — Creates a new map using a callable to determine which pairs to include
  • Ds\Map::first — Returns the first pair in the map
  • Ds\Map::get — Returns the value for a given key
  • Ds\Map::hasKey — Determines whether the map contains a given key
  • Ds\Map::hasValue — Determines whether the map contains a given value
  • Ds\Map::intersect — Creates a new map by intersecting keys with another map
  • Ds\Map::isEmpty — Returns whether the map is empty
  • Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Map::keys — Returns a set of the map's keys
  • Ds\Map::ksort — Sorts the map in-place by key
  • Ds\Map::ksorted — Returns a copy, sorted by key
  • Ds\Map::last — Returns the last pair of the map
  • Ds\Map::map — Returns the result of applying a callback to each value
  • Ds\Map::merge — Returns the result of adding all given associations
  • Ds\Map::pairs — Returns a sequence containing all the pairs of the map
  • Ds\Map::put — Associates a key with a value
  • Ds\Map::putAll — Associates all key-value pairs of a traversable object or array
  • Ds\Map::reduce — Reduces the map to a single value using a callback function
  • Ds\Map::remove — Removes and returns a value by key
  • Ds\Map::reverse — Reverses the map in-place
  • Ds\Map::reversed — Returns a reversed copy
  • Ds\Map::skip — Returns the pair at a given positional index
  • Ds\Map::slice — Returns a subset of the map defined by a starting index and length
  • Ds\Map::sort — Sorts the map in-place by value
  • Ds\Map::sorted — Returns a copy, sorted by value
  • Ds\Map::sum — Returns the sum of all values in the map
  • Ds\Map::toArray — Converts the map to an array
  • Ds\Map::union — Creates a new map using values from the current instance and another map
  • Ds\Map::values — Returns a sequence of the map's values
  • Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both


Allocates enough memory for a required capacity

  • ≪ Ds\Map
  • Ds\Map::apply ≫
  • PHP Manual
  • Ds\Map
  • Allocates enough memory for a required capacity

Ds\Map::allocate

(PECL ds >= 1.0.0)

Ds\Map::allocate — Allocates enough memory for a required capacity

説明

public Ds\Map::allocate(int $capacity): void

Allocates enough memory for a required capacity.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

戻り値

値を返しません。

例

例1 Ds\Map::allocate() example

<?php
$map = new \Ds\Map();
var_dump($map->capacity());

$map->allocate(100);
var_dump($map->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)
int(128)


Updates all values by applying a callback function to each value

  • ≪ Ds\Map::allocate
  • Ds\Map::capacity ≫
  • PHP Manual
  • Ds\Map
  • Updates all values by applying a callback function to each value

Ds\Map::apply

(PECL ds >= 1.0.0)

Ds\Map::apply — Updates all values by applying a callback function to each value

説明

public Ds\Map::apply(callable $callback): void

Updates all values by applying a callback function to each value in the map.

パラメータ

callback

callback(mixed $key, mixed $value): mixed

A callable to apply to each value in the map.

The callback should return what the value should be replaced by.

戻り値

値を返しません。

例

例1 Ds\Map::apply() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$map->apply(function($key, $value) { return $value * 2; });

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 4
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 6
        )

)


Returns the current capacity

  • ≪ Ds\Map::apply
  • Ds\Map::clear ≫
  • PHP Manual
  • Ds\Map
  • Returns the current capacity

Ds\Map::capacity

(PECL ds >= 1.0.0)

Ds\Map::capacity — Returns the current capacity

説明

public Ds\Map::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\Map::capacity() example

<?php
$map = new \Ds\Map();
var_dump($map->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)


Removes all values

  • ≪ Ds\Map::capacity
  • Ds\Map::__construct ≫
  • PHP Manual
  • Ds\Map
  • Removes all values

Ds\Map::clear

(PECL ds >= 1.0.0)

Ds\Map::clear — Removes all values

説明

public Ds\Map::clear(): void

Removes all values from the map.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Map::clear() example

<?php
$map = new \Ds\Map([
"a" => 1,
"b" => 2,
"c" => 3,
]);
print_r($map);

$map->clear();
print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)
Ds\Map Object
(
)


Creates a new instance

  • ≪ Ds\Map::clear
  • Ds\Map::copy ≫
  • PHP Manual
  • Ds\Map
  • Creates a new instance

Ds\Map::__construct

(PECL ds >= 1.0.0)

Ds\Map::__construct — Creates a new instance

説明

public Ds\Map::__construct(mixed ...$values)

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Map::__construct() example

<?php
$map = new \Ds\Map();
var_dump($map);

$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#1 (0) {
}
object(Ds\Map)#2 (3) {
  [0]=>
  object(Ds\Pair)#1 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
  [1]=>
  object(Ds\Pair)#3 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [2]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}


Returns a shallow copy of the map

  • ≪ Ds\Map::__construct
  • Ds\Map::count ≫
  • PHP Manual
  • Ds\Map
  • Returns a shallow copy of the map

Ds\Map::copy

(PECL ds >= 1.0.0)

Ds\Map::copy — Returns a shallow copy of the map

説明

public Ds\Map::copy(): Ds\Map

Returns a shallow copy of the map.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the map.

例

例1 Ds\Map::copy() example

<?php
$map = new \Ds\Map([
"a" => 1,
"b" => 2,
"c" => 3,
]);

print_r($map->copy());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)


Returns the number of values in the map

  • ≪ Ds\Map::copy
  • Ds\Map::diff ≫
  • PHP Manual
  • Ds\Map
  • Returns the number of values in the map

Ds\Map::count

(PECL ds >= 1.0.0)

Ds\Map::count — Returns the number of values in the map

説明

See Countable::count()


Creates a new map using keys that aren't in another map

  • ≪ Ds\Map::count
  • Ds\Map::filter ≫
  • PHP Manual
  • Ds\Map
  • Creates a new map using keys that aren't in another map

Ds\Map::diff

(PECL ds >= 1.0.0)

Ds\Map::diff — Creates a new map using keys that aren't in another map

説明

public Ds\Map::diff(Ds\Map $map): Ds\Map

Returns the result of removing all keys from the current instance that are present in a given map.

A \ B = {x ∈ A | x ? B}

パラメータ

map

The map containing the keys to exclude in the resulting map.

戻り値

The result of removing all keys from the current instance that are present in a given map.

参考

  • » Complement on Wikipedia

例

例1 Ds\Map::diff() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

var_dump($a->diff($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#3 (1) {
  [0]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
}


Creates a new map using a callable to determine which pairs to include

  • ≪ Ds\Map::diff
  • Ds\Map::first ≫
  • PHP Manual
  • Ds\Map
  • Creates a new map using a callable to determine which pairs to include

Ds\Map::filter

(PECL ds >= 1.0.0)

Ds\Map::filter — Creates a new map using a callable to determine which pairs to include

説明

public Ds\Map::filter(callable $callback = ?): Ds\Map

Creates a new map using a callable to determine which pairs to include.

パラメータ

callback

callback(mixed $key, mixed $value): bool

Optional callable which returns true if the pair should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

戻り値

A new map containing all the pairs for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Map::filter() example using callback function

<?php
$map = new \Ds\Map(["a", "b", "c", "d", "e"]);

var_dump($map->filter(function($key, $value) {
return $key % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#3 (3) {
  [0]=>
  object(Ds\Pair)#2 (2) {
    ["key"]=>
    int(0)
    ["value"]=>
    string(1) "a"
  }
  [1]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    int(2)
    ["value"]=>
    string(1) "c"
  }
  [2]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    int(4)
    ["value"]=>
    string(1) "e"
  }
}

例2 Ds\Map::filter() example without a callback function

<?php
$map = new \Ds\Map(["a" => 0, "b" => 1, "c" => true, "d" => false]);

var_dump($map->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}


Returns the first pair in the map

  • ≪ Ds\Map::filter
  • Ds\Map::get ≫
  • PHP Manual
  • Ds\Map
  • Returns the first pair in the map

Ds\Map::first

(PECL ds >= 1.0.0)

Ds\Map::first — Returns the first pair in the map

説明

public Ds\Map::first(): Ds\Pair

Returns the first pair in the map.

パラメータ

この関数にはパラメータはありません。

戻り値

The first pair in the map.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Map::first() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->first());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "a"
  ["value"]=>
  int(1)
}


Returns the value for a given key

  • ≪ Ds\Map::first
  • Ds\Map::hasKey ≫
  • PHP Manual
  • Ds\Map
  • Returns the value for a given key

Ds\Map::get

(PECL ds >= 1.0.0)

Ds\Map::get — Returns the value for a given key

説明

public Ds\Map::get(mixed $key, mixed $default = ?): mixed

Returns the value for a given key, or an optional default value if the key could not be found.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

注意:

You can also use array syntax to access values by key, eg. $map["key"].

警告

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

パラメータ

key

The key to look up.

default

The optional default value, returned if the key could not be found.

戻り値

The value mapped to the given key, or the default value if provided and the key could not be found in the map.

エラー / 例外

OutOfBoundsException if the key could not be found and a default value was not provided.

例

例1 Ds\Map::get() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->get("a")); // 1
var_dump($map->get("d", 10)); // 10 (default used)
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(10)

例2 Ds\Map::get() example using array syntax

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map["a"]); // 1
?>

上の例の出力は、 たとえば以下のようになります。

int(1)


Determines whether the map contains a given key

  • ≪ Ds\Map::get
  • Ds\Map::hasValue ≫
  • PHP Manual
  • Ds\Map
  • Determines whether the map contains a given key

Ds\Map::hasKey

(PECL ds >= 1.0.0)

Ds\Map::hasKey — Determines whether the map contains a given key

説明

public Ds\Map::hasKey(mixed $key): bool

Determines whether the map contains a given key.

パラメータ

key

The key to look for.

戻り値

Returns true if the key could found, false otherwise.

例

例1 Ds\Map::hasKey() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->hasKey("a")); // true
var_dump($map->hasKey("e")); // false
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)


Determines whether the map contains a given value

  • ≪ Ds\Map::hasKey
  • Ds\Map::intersect ≫
  • PHP Manual
  • Ds\Map
  • Determines whether the map contains a given value

Ds\Map::hasValue

(PECL ds >= 1.0.0)

Ds\Map::hasValue — Determines whether the map contains a given value

説明

public Ds\Map::hasValue(mixed $value): bool

Determines whether the map contains a given value.

パラメータ

value

The value to look for.

戻り値

Returns true if the value could found, false otherwise.

例

例1 Ds\Map::hasValue() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->hasValue(1)); // true
var_dump($map->hasValue(4)); // false
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)


Creates a new map by intersecting keys with another map

  • ≪ Ds\Map::hasValue
  • Ds\Map::isEmpty ≫
  • PHP Manual
  • Ds\Map
  • Creates a new map by intersecting keys with another map

Ds\Map::intersect

(PECL ds >= 1.0.0)

Ds\Map::intersect — Creates a new map by intersecting keys with another map

説明

public Ds\Map::intersect(Ds\Map $map): Ds\Map

Creates a new map containing the pairs of the current instance whose keys are also present in the given map. In other words, returns a copy of the current instance with all keys removed that are not also in the other map.

A ∩ B = {x : x ∈ A ∧ x ∈ B}

注意:

Values from the current instance will be kept.

パラメータ

map

The other map, containing the keys to intersect with.

戻り値

The key intersection of the current instance and another map.

参考

  • » Intersection on Wikipedia

例

例1 Ds\Map::intersect() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

var_dump($a->intersect($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#3 (2) {
  [0]=>
  object(Ds\Pair)#4 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [1]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}


Returns whether the map is empty

  • ≪ Ds\Map::intersect
  • Ds\Map::jsonSerialize ≫
  • PHP Manual
  • Ds\Map
  • Returns whether the map is empty

Ds\Map::isEmpty

(PECL ds >= 1.0.0)

Ds\Map::isEmpty — Returns whether the map is empty

説明

public Ds\Map::isEmpty(): bool

Returns whether the map is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the map is empty, false otherwise.

例

例1 Ds\Map::isEmpty() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Returns a representation that can be converted to JSON

  • ≪ Ds\Map::isEmpty
  • Ds\Map::keys ≫
  • PHP Manual
  • Ds\Map
  • Returns a representation that can be converted to JSON

Ds\Map::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Map::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns a set of the map's keys

  • ≪ Ds\Map::jsonSerialize
  • Ds\Map::ksort ≫
  • PHP Manual
  • Ds\Map
  • Returns a set of the map's keys

Ds\Map::keys

(PECL ds >= 1.0.0)

Ds\Map::keys — Returns a set of the map's keys

説明

public Ds\Map::keys(): Ds\Set

Returns a set containing all the keys of the map, in the same order.

パラメータ

この関数にはパラメータはありません。

戻り値

A Ds\Set containing all the keys of the map.

例

例1 Ds\Map::keys() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->keys());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#2 (3) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [2]=>
  string(1) "c"
}


Sorts the map in-place by key

  • ≪ Ds\Map::keys
  • Ds\Map::ksorted ≫
  • PHP Manual
  • Ds\Map
  • Sorts the map in-place by key

Ds\Map::ksort

(PECL ds >= 1.0.0)

Ds\Map::ksort — Sorts the map in-place by key

説明

public Ds\Map::ksort(callable $comparator = ?): void

Sorts the map in-place by key, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

値を返しません。

例

例1 Ds\Map::ksort() example

<?php
$map = new \Ds\Map(["b" => 2, "c" => 3, "a" => 1]);
$map->ksort();

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

例2 Ds\Map::ksort() example using a comparator

<?php
$map = new \Ds\Map([1 => "x", 2 => "y", 0 => "z"]);

// Reverse
$map->ksort(function($a, $b) {
return $b <=> $a;
});

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 2
            [value] => y
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => x
        )

    [2] => Ds\Pair Object
        (
            [key] => 0
            [value] => z
        )

)


Returns a copy, sorted by key

  • ≪ Ds\Map::ksort
  • Ds\Map::last ≫
  • PHP Manual
  • Ds\Map
  • Returns a copy, sorted by key

Ds\Map::ksorted

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Map::ksorted — Returns a copy, sorted by key

説明

public Ds\Map::ksorted(callable $comparator = ?): Ds\Map

Returns a copy sorted by key, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

Returns a copy of the map, sorted by key.

例

例1 Ds\Map::ksorted() example

<?php
$map = new \Ds\Map(["b" => 2, "c" => 3, "a" => 1]);

print_r($map->ksorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

例2 Ds\Map::ksorted() example using a comparator

<?php
$map = new \Ds\Map([1 => "x", 2 => "y", 0 => "z"]);

// Reverse
$sorted = $map->ksorted(function($a, $b) {
return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => 2
            [value] => y
        )

    [1] => Ds\Pair Object
        (
            [key] => 1
            [value] => x
        )

    [2] => Ds\Pair Object
        (
            [key] => 0
            [value] => z
        )

)


Returns the last pair of the map

  • ≪ Ds\Map::ksorted
  • Ds\Map::map ≫
  • PHP Manual
  • Ds\Map
  • Returns the last pair of the map

Ds\Map::last

(PECL ds >= 1.0.0)

Ds\Map::last — Returns the last pair of the map

説明

public Ds\Map::last(): Ds\Pair

Returns the last pair of the map.

パラメータ

この関数にはパラメータはありません。

戻り値

The last pair of the map.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Map::last() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->last());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "c"
  ["value"]=>
  int(3)
}


Returns the result of applying a callback to each value

  • ≪ Ds\Map::last
  • Ds\Map::merge ≫
  • PHP Manual
  • Ds\Map
  • Returns the result of applying a callback to each value

Ds\Map::map

(PECL ds >= 1.0.0)

Ds\Map::map — Returns the result of applying a callback to each value

説明

public Ds\Map::map(callable $callback): Ds\Map

Returns the result of applying a callback function to each value of the map.

パラメータ

callback

callback(mixed $key, mixed $value): mixed

A callable to apply to each value in the map.

The callable should return what the key will be mapped to in the resulting map.

戻り値

The result of applying a callback to each value in the map.

注意:

The keys and values of the current instance won't be affected.

例

例1 Ds\Map::map() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->map(function($key, $value) { return $value * 2; }));
print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 4
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 6
        )

)
Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)


Returns the result of adding all given associations

  • ≪ Ds\Map::map
  • Ds\Map::pairs ≫
  • PHP Manual
  • Ds\Map
  • Returns the result of adding all given associations

Ds\Map::merge

(PECL ds >= 1.0.0)

Ds\Map::merge — Returns the result of adding all given associations

説明

public Ds\Map::merge(mixed $values): Ds\Map

Returns the result of associating all keys of a given traversable object or array with their corresponding values, combined with the current instance.

注意:

Values of the current instance will be overwritten by those provided where keys are equal.

パラメータ

values

A traversable object or an array.

戻り値

The result of associating all keys of a given traversable object or array with their corresponding values, combined with the current instance.

注意:

The current instance won't be affected.

例

例1 Ds\Map::merge() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->merge(["a" => 10, "e" => 50]));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 10
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [3] => Ds\Pair Object
        (
            [key] => e
            [value] => 50
        )

)


Returns a sequence containing all the pairs of the map

  • ≪ Ds\Map::merge
  • Ds\Map::put ≫
  • PHP Manual
  • Ds\Map
  • Returns a sequence containing all the pairs of the map

Ds\Map::pairs

(PECL ds >= 1.0.0)

Ds\Map::pairs — Returns a sequence containing all the pairs of the map

説明

public Ds\Map::pairs(): Ds\Sequence

Returns a Ds\Sequence containing all the pairs of the map.

パラメータ

この関数にはパラメータはありません。

戻り値

Ds\Sequence containing all the pairs of the map.

例

例1 Ds\Map::pairs() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->pairs());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#8 (3) {
  [0]=>
  object(Ds\Pair)#5 (2) {
    ["key"]=>
    string(1) "a"
    ["value"]=>
    int(1)
  }
  [1]=>
  object(Ds\Pair)#6 (2) {
    ["key"]=>
    string(1) "b"
    ["value"]=>
    int(2)
  }
  [2]=>
  object(Ds\Pair)#7 (2) {
    ["key"]=>
    string(1) "c"
    ["value"]=>
    int(3)
  }
}
p


Associates a key with a value

  • ≪ Ds\Map::pairs
  • Ds\Map::putAll ≫
  • PHP Manual
  • Ds\Map
  • Associates a key with a value

Ds\Map::put

(PECL ds >= 1.0.0)

Ds\Map::put — Associates a key with a value

説明

public Ds\Map::put(mixed $key, mixed $value): void

Associates a key with a value, overwriting a previous association if one exists.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

注意:

You can also use array syntax to associate values by key, eg. $map["key"] = $value.

警告

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

パラメータ

key

The key to associate the value with.

value

The value to be associated with the key.

戻り値

値を返しません。

例

例1 Ds\Map::put() example

<?php
$map = new \Ds\Map();

$map->put("a", 1);
$map->put("b", 2);
$map->put("c", 3);

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)

例2 Ds\Map::put() example using objects as keys

<?php
class HashableObject implements \Ds\Hashable
{
/**
* An arbitrary value to use as the hash value. Does not define equality.
*/
private $value;

public function __construct($value)
{
$this->value = $value;
}

public function hash()
{
return $this->value;
}

public function equals($obj): bool
{
return $this->value === $obj->value;
}
}

$map = new \Ds\Map();

$obj = new \ArrayIterator([]);

// Using the same instance multiple times will overwrite the previous value.
$map->put($obj, 1);
$map->put($obj, 2);

// Using multiple instances of the same object will create new associations.
$map->put(new \stdClass(), 3);
$map->put(new \stdClass(), 4);

// Using multiple instances of equal hashable objects will overwrite previous values.
$map->put(new \HashableObject(1), 5);
$map->put(new \HashableObject(1), 6);
$map->put(new \HashableObject(2), 7);
$map->put(new \HashableObject(2), 8);

var_dump($map);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Map)#1 (5) {
  [0]=>
  object(Ds\Pair)#7 (2) {
    ["key"]=>
    object(ArrayIterator)#2 (1) {
      ["storage":"ArrayIterator":private]=>
      array(0) {
      }
    }
    ["value"]=>
    int(2)
  }
  [1]=>
  object(Ds\Pair)#8 (2) {
    ["key"]=>
    object(stdClass)#3 (0) {
    }
    ["value"]=>
    int(3)
  }
  [2]=>
  object(Ds\Pair)#9 (2) {
    ["key"]=>
    object(stdClass)#4 (0) {
    }
    ["value"]=>
    int(4)
  }
  [3]=>
  object(Ds\Pair)#10 (2) {
    ["key"]=>
    object(HashableObject)#5 (1) {
      ["value":"HashableObject":private]=>
      int(1)
    }
    ["value"]=>
    int(6)
  }
  [4]=>
  object(Ds\Pair)#11 (2) {
    ["key"]=>
    object(HashableObject)#6 (1) {
      ["value":"HashableObject":private]=>
      int(2)
    }
    ["value"]=>
    int(8)
  }
}


Associates all key-value pairs of a traversable object or array

  • ≪ Ds\Map::put
  • Ds\Map::reduce ≫
  • PHP Manual
  • Ds\Map
  • Associates all key-value pairs of a traversable object or array

Ds\Map::putAll

(PECL ds >= 1.0.2)

Ds\Map::putAll — Associates all key-value pairs of a traversable object or array

説明

public Ds\Map::putAll(mixed $pairs): void

Associates all key-value pairs of a traversable object or array.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

パラメータ

pairs

traversable object or array.

戻り値

値を返しません。

例

例1 Ds\Map::putAll() example

<?php
$map = new \Ds\Map();

$map->putAll([
"a" => 1,
"b" => 2,
"c" => 3,
]);

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

)


Reduces the map to a single value using a callback function

  • ≪ Ds\Map::putAll
  • Ds\Map::remove ≫
  • PHP Manual
  • Ds\Map
  • Reduces the map to a single value using a callback function

Ds\Map::reduce

(PECL ds >= 1.0.0)

Ds\Map::reduce — Reduces the map to a single value using a callback function

説明

public Ds\Map::reduce(callable $callback, mixed $initial = ?): mixed

Reduces the map to a single value using a callback function.

パラメータ

callback
callback(mixed $carry, mixed $key, mixed $value): mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

key

The key of the current iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

戻り値

The return value of the final callback.

例

例1 Ds\Map::reduce() with initial value example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

$callback = function($carry, $key, $value) {
return $carry * $value;
};

var_dump($map->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 = 5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Map::reduce() without an initial value example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->reduce(function($carry, $key, $value) {
return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 = 6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)


Removes and returns a value by key

  • ≪ Ds\Map::reduce
  • Ds\Map::reverse ≫
  • PHP Manual
  • Ds\Map
  • Removes and returns a value by key

Ds\Map::remove

(PECL ds >= 1.0.0)

Ds\Map::remove — Removes and returns a value by key

説明

public Ds\Map::remove(mixed $key, mixed $default = ?): mixed

Removes and returns a value by key, or return an optional default value if the key could not be found.

注意:

Keys of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

注意:

You can also use array syntax to access values by key, eg. $map["key"].

警告

Be careful when using array syntax. Scalar keys will be coerced to integers by the engine. For example, $map["1"] will attempt to access int(1), while $map->get("1") will correctly look up the string key.

See Arrays.

パラメータ

key

The key to remove.

default

The optional default value, returned if the key could not be found.

戻り値

The value that was removed, or the default value if provided and the key could not be found in the map.

エラー / 例外

OutOfBoundsException if the key could not be found and a default value was not provided.

例

例1 Ds\Map::remove() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->remove("a")); // 1
var_dump($map->remove("e", 10)); // 10 (default used)
?>

上の例の出力は、 たとえば以下のようになります。

int(1)
int(10)


Reverses the map in-place

  • ≪ Ds\Map::remove
  • Ds\Map::reversed ≫
  • PHP Manual
  • Ds\Map
  • Reverses the map in-place

Ds\Map::reverse

(PECL ds >= 1.0.0)

Ds\Map::reverse — Reverses the map in-place

説明

public Ds\Map::reverse(): void

Reverses the map in-place.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Map::reverse() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$map->reverse();

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

)


Returns a reversed copy

  • ≪ Ds\Map::reverse
  • Ds\Map::skip ≫
  • PHP Manual
  • Ds\Map
  • Returns a reversed copy

Ds\Map::reversed

(PECL ds >= 1.0.0)

Ds\Map::reversed — Returns a reversed copy

説明

public Ds\Map::reversed(): Ds\Map

Returns a reversed copy of the map.

パラメータ

この関数にはパラメータはありません。

戻り値

A reversed copy of the map.

注意:

The current instance is not affected.

例

例1 Ds\Map::reversed() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

print_r($map->reversed());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

)


Returns the pair at a given positional index

  • ≪ Ds\Map::reversed
  • Ds\Map::slice ≫
  • PHP Manual
  • Ds\Map
  • Returns the pair at a given positional index

Ds\Map::skip

(PECL ds >= 1.0.0)

Ds\Map::skip — Returns the pair at a given positional index

説明

public Ds\Map::skip(int $position): Ds\Pair

Returns the pair at a given zero-based position.

パラメータ

position

The zero-based positional index to return.

戻り値

Returns the Ds\Pair at the given position.

エラー / 例外

OutOfRangeException if the position is not valid.

例

例1 Ds\Map::skip() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);

var_dump($map->skip(1));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Pair)#2 (2) {
  ["key"]=>
  string(1) "b"
  ["value"]=>
  int(2)
}


Returns a subset of the map defined by a starting index and length

  • ≪ Ds\Map::skip
  • Ds\Map::sort ≫
  • PHP Manual
  • Ds\Map
  • Returns a subset of the map defined by a starting index and length

Ds\Map::slice

(PECL ds >= 1.0.0)

Ds\Map::slice — Returns a subset of the map defined by a starting index and length

説明

public Ds\Map::slice(int $index, int $length = ?): Ds\Map

Returns a subset of the map defined by a starting index and length.

パラメータ

index

The index at which the range starts.

If positive, the range will start at that index in the map. If negative, the range will start that far from the end.

length

If a length is given and is positive, the resulting map will have up to that many pairs in it. If a length is given and is negative, the range will stop that many pairs from the end. If the length results in an overflow, only pairs up to the end of the map will be included. If a length is not provided, the resulting map will contain all pairs between the index and the end of the map.

戻り値

A subset of the map defined by a starting index and length.

例

例1 Ds\Map::slice() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3, "d" => 4, "e" => 5]);

// Slice from 2 onwards
print_r($map->slice(2)->toArray());

// Slice from 1, for a length of 3
print_r($map->slice(1, 3)->toArray());

// Slice from 1 onwards
print_r($map->slice(1)->toArray());

// Slice from 2 from the end onwards
print_r($map->slice(-2)->toArray());

// Slice from 1 to 1 from the end
print_r($map->slice(1, -1)->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [c] => 3
    [d] => 4
    [e] => 5
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
    [e] => 5
)
Array
(
    [d] => 4
    [e] => 5
)
Array
(
    [b] => 2
    [c] => 3
    [d] => 4
)


Sorts the map in-place by value

  • ≪ Ds\Map::slice
  • Ds\Map::sorted ≫
  • PHP Manual
  • Ds\Map
  • Sorts the map in-place by value

Ds\Map::sort

(PECL ds >= 1.0.0)

Ds\Map::sort — Sorts the map in-place by value

説明

public Ds\Map::sort(callable $comparator = ?): void

Sorts the map in-place by value, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

値を返しません。

例

例1 Ds\Map::sort() example

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);
$map->sort();

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

)

例2 Ds\Map::sort() example using a comparator

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

$map->sort(function($a, $b) {
return $b <=> $a;
});

print_r($map);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

)


Returns a copy, sorted by value

  • ≪ Ds\Map::sort
  • Ds\Map::sum ≫
  • PHP Manual
  • Ds\Map
  • Returns a copy, sorted by value

Ds\Map::sorted

(PECL ds >= 1.0.0)

Ds\Map::sorted — Returns a copy, sorted by value

説明

public Ds\Map::sorted(callable $comparator = ?): Ds\Map

Returns a copy, sorted by value using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

Returns a copy of the map, sorted by value.

例

例1 Ds\Map::sort() example

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

print_r($map->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

)

例2 Ds\Map::sort() example using a comparator

<?php
$map = new \Ds\Map(["a" => 2, "b" => 3, "c" => 1]);

// Reverse
$sorted = $map->sorted(function($a, $b) {
return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [1] => Ds\Pair Object
        (
            [key] => a
            [value] => 2
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 1
        )

)


Returns the sum of all values in the map

  • ≪ Ds\Map::sorted
  • Ds\Map::toArray ≫
  • PHP Manual
  • Ds\Map
  • Returns the sum of all values in the map

Ds\Map::sum

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Map::sum — Returns the sum of all values in the map

説明

public Ds\Map::sum(): int|float

Returns the sum of all values in the map.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

戻り値

The sum of all the values in the map as either a float or int depending on the values in the map.

例

例1 Ds\Map::sum() integer example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Map::sum() float example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2.5, "c" => 3]);
var_dump($map->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)


Converts the map to an array

  • ≪ Ds\Map::sum
  • Ds\Map::union ≫
  • PHP Manual
  • Ds\Map
  • Converts the map to an array

Ds\Map::toArray

(PECL ds >= 1.0.0)

Ds\Map::toArray — Converts the map to an array

説明

public Ds\Map::toArray(): array

Converts the map to an array.

警告

Maps where non-scalar keys are can't be converted to an array.

警告

An array will treat all numeric keys as integers, eg. "1" and 1 as keys in the map will only result in 1 being included in the array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the map.

例

例1 Ds\Map::toArray() example

<?php
$map = new \Ds\Map([
"a" => 1,
"b" => 2,
"c" => 3,
]);

var_dump($map->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["a"]=>
  int(1)
  ["b"]=>
  int(2)
  ["c"]=>
  int(3)
}


Creates a new map using values from the current instance and another map

  • ≪ Ds\Map::toArray
  • Ds\Map::values ≫
  • PHP Manual
  • Ds\Map
  • Creates a new map using values from the current instance and another map

Ds\Map::union

(PECL ds >= 1.0.0)

Ds\Map::union — Creates a new map using values from the current instance and another map

説明

public Ds\Map::union(Ds\Map $map): Ds\Map

Creates a new map that contains the pairs of the current instance as well as the pairs of another map.

A ∪ B = {x: x ∈ A ∨ x ∈ B}

注意:

Values of the current instance will be overwritten by those provided where keys are equal.

パラメータ

map

The other map, to combine with the current instance.

戻り値

A new map containing all the pairs of the current instance as well as another map.

参考

  • » Union on Wikipedia

例

例1 Ds\Map::union() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 3, "c" => 4, "d" => 5]);

print_r($a->union($b));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => b
            [value] => 3
        )

    [2] => Ds\Pair Object
        (
            [key] => c
            [value] => 4
        )

    [3] => Ds\Pair Object
        (
            [key] => d
            [value] => 5
        )

)


Returns a sequence of the map's values

  • ≪ Ds\Map::union
  • Ds\Map::xor ≫
  • PHP Manual
  • Ds\Map
  • Returns a sequence of the map's values

Ds\Map::values

(PECL ds >= 1.0.0)

Ds\Map::values — Returns a sequence of the map's values

説明

public Ds\Map::values(): Ds\Sequence

Returns a sequence containing all the values of the map, in the same order.

パラメータ

この関数にはパラメータはありません。

戻り値

A Ds\Sequence containing all the values of the map.

例

例1 Ds\Map::values() example

<?php
$map = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
var_dump($map->values());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Vector)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Creates a new map using keys of either the current instance or of another map, but not of both

  • ≪ Ds\Map::values
  • Ds\Pair ≫
  • PHP Manual
  • Ds\Map
  • Creates a new map using keys of either the current instance or of another map, but not of both

Ds\Map::xor

(PECL ds >= 1.0.0)

Ds\Map::xor — Creates a new map using keys of either the current instance or of another map, but not of both

説明

public Ds\Map::xor(Ds\Map $map): Ds\Map

Creates a new map containing keys of the current instance as well as another map, but not of both.

A ? B = {x : x ∈ (A \ B) ∪ (B \ A)}

パラメータ

map

The other map.

戻り値

A new map containing keys in the current instance as well as another map, but not in both.

参考

  • » Symmetric Difference on Wikipedia

例

例1 Ds\Map::xor() example

<?php
$a = new \Ds\Map(["a" => 1, "b" => 2, "c" => 3]);
$b = new \Ds\Map(["b" => 4, "c" => 5, "d" => 6]);

print_r($a->xor($b));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Map Object
(
    [0] => Ds\Pair Object
        (
            [key] => a
            [value] => 1
        )

    [1] => Ds\Pair Object
        (
            [key] => d
            [value] => 6
        )

)


The Pair class

(PECL ds >= 1.0.0)

はじめに

A pair is used by Ds\Map to pair keys with values.

クラス概要

class Ds\Pair implements JsonSerializable {
/* メソッド */
public __construct(mixed $key = ?, mixed $value = ?)
public clear(): void
public copy(): Ds\Pair
public isEmpty(): bool
public toArray(): array
}

目次

  • Ds\Pair::clear — Removes all values
  • Ds\Pair::__construct — Creates a new instance
  • Ds\Pair::copy — Returns a shallow copy of the pair
  • Ds\Pair::isEmpty — Returns whether the pair is empty
  • Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Pair::toArray — Converts the pair to an array


Removes all values

  • ≪ Ds\Pair
  • Ds\Pair::__construct ≫
  • PHP Manual
  • Ds\Pair
  • Removes all values

Ds\Pair::clear

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Pair::clear — Removes all values

説明

public Ds\Pair::clear(): void

Removes all values from the pair.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Pair::clear() example

<?php
$pair = new \Ds\Pair("a", 1);
print_r($pair);

$pair->clear();
print_r($pair);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Pair Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Pair Object
(
)


Creates a new instance

  • ≪ Ds\Pair::clear
  • Ds\Pair::copy ≫
  • PHP Manual
  • Ds\Pair
  • Creates a new instance

Ds\Pair::__construct

(PECL ds >= 1.0.0)

Ds\Pair::__construct — Creates a new instance

説明

public Ds\Pair::__construct(mixed $key = ?, mixed $value = ?)

Creates a new instance using a given key and value.

パラメータ

key

The key.

value

The value.


Returns a shallow copy of the pair

  • ≪ Ds\Pair::__construct
  • Ds\Pair::isEmpty ≫
  • PHP Manual
  • Ds\Pair
  • Returns a shallow copy of the pair

Ds\Pair::copy

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Pair::copy — Returns a shallow copy of the pair

説明

public Ds\Pair::copy(): Ds\Pair

Returns a shallow copy of the pair.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the pair.

例

例1 Ds\Pair::copy() example

<?php
$a = new \Ds\Pair("a", 1);
$b = $a->copy();

$a->key = "x";

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Pair Object
(
    [key] => x
    [value] => 1
)
Ds\Pair Object
(
    [key] => a
    [value] => 1
)


Returns whether the pair is empty

  • ≪ Ds\Pair::copy
  • Ds\Pair::jsonSerialize ≫
  • PHP Manual
  • Ds\Pair
  • Returns whether the pair is empty

Ds\Pair::isEmpty

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

Ds\Pair::isEmpty — Returns whether the pair is empty

説明

public Ds\Pair::isEmpty(): bool

Returns whether the pair is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the pair is empty, false otherwise.

例

例1 Ds\Pair::isEmpty() example

<?php
$a = new \Ds\Pair("a", 1);
$b = new \Ds\Pair();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Returns a representation that can be converted to JSON

  • ≪ Ds\Pair::isEmpty
  • Ds\Pair::toArray ≫
  • PHP Manual
  • Ds\Pair
  • Returns a representation that can be converted to JSON

Ds\Pair::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Pair::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Converts the pair to an array

  • ≪ Ds\Pair::jsonSerialize
  • Ds\Set ≫
  • PHP Manual
  • Ds\Pair
  • Converts the pair to an array

Ds\Pair::toArray

(PECL ds >= 1.0.0)

Ds\Pair::toArray — Converts the pair to an array

説明

public Ds\Pair::toArray(): array

Converts the pair to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the pair.

例

例1 Ds\Pair::toArray() example

<?php
$pair = new \Ds\Pair("a", 1);

var_dump($pair->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["key"]=>
  string(1) "a"
  ["value"]=>
  int(1)
}


The Set class

(PECL ds >= 1.0.0)

はじめに

A Set is a sequence of unique values. This implementation uses the same hash table as Ds\Map, where values are used as keys and the mapped value is ignored.

Strengths

  • Values can be any type, including objects.
  • Supports array syntax (square brackets).
  • Insertion order is preserved.
  • Automatically frees allocated memory when its size drops low enough.
  • add(),
remove() and
contains() are all O(1).

Weaknesses

  • Doesn't support
                push(),
                pop(),
                insert(),
                shift(), or
                unshift().
  • get() is O(n) if there are deleted values in the buffer before the accessed index, O(1) otherwise.

クラス概要

class Ds\Set implements Ds\Collection, ArrayAccess {
/* 定数 */
const int MIN_CAPACITY = 16;
/* メソッド */
public add(mixed ...$values): void
public allocate(int $capacity): void
public capacity(): int
public clear(): void
public contains(mixed ...$values): bool
public copy(): Ds\Set
public diff(Ds\Set $set): Ds\Set
public filter(callable $callback = ?): Ds\Set
public first(): mixed
public get(int $index): mixed
public intersect(Ds\Set $set): Ds\Set
public isEmpty(): bool
public join(string $glue = ?): string
public last(): mixed
public merge(mixed $values): Ds\Set
public reduce(callable $callback, mixed $initial = ?): mixed
public remove(mixed ...$values): void
public reverse(): void
public reversed(): Ds\Set
public slice(int $index, int $length = ?): Ds\Set
public sort(callable $comparator = ?): void
public sorted(callable $comparator = ?): Ds\Set
public sum(): int|float
public toArray(): array
public union(Ds\Set $set): Ds\Set
public xor(Ds\Set $set): Ds\Set
}

定義済み定数

Ds\Set::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Set::add — Adds values to the set
  • Ds\Set::allocate — Allocates enough memory for a required capacity
  • Ds\Set::capacity — Returns the current capacity
  • Ds\Set::clear — Removes all values
  • Ds\Set::__construct — Creates a new instance
  • Ds\Set::contains — Determines if the set contains all values
  • Ds\Set::copy — Returns a shallow copy of the set
  • Ds\Set::count — Returns the number of values in the set
  • Ds\Set::diff — Creates a new set using values that aren't in another set
  • Ds\Set::filter — Creates a new set using a callable to determine which values to include
  • Ds\Set::first — Returns the first value in the set
  • Ds\Set::get — Returns the value at a given index
  • Ds\Set::intersect — Creates a new set by intersecting values with another set
  • Ds\Set::isEmpty — Returns whether the set is empty
  • Ds\Set::join — Joins all values together as a string
  • Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Set::last — Returns the last value in the set
  • Ds\Set::merge — Returns the result of adding all given values to the set
  • Ds\Set::reduce — Reduces the set to a single value using a callback function
  • Ds\Set::remove — Removes all given values from the set
  • Ds\Set::reverse — Reverses the set in-place
  • Ds\Set::reversed — Returns a reversed copy
  • Ds\Set::slice — Returns a sub-set of a given range
  • Ds\Set::sort — Sorts the set in-place
  • Ds\Set::sorted — Returns a sorted copy
  • Ds\Set::sum — Returns the sum of all values in the set
  • Ds\Set::toArray — Converts the set to an array
  • Ds\Set::union — Creates a new set using values from the current instance and another set
  • Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both


Adds values to the set

  • ≪ Ds\Set
  • Ds\Set::allocate ≫
  • PHP Manual
  • Ds\Set
  • Adds values to the set

Ds\Set::add

(PECL ds >= 1.0.0)

Ds\Set::add — Adds values to the set

説明

public Ds\Set::add(mixed ...$values): void

Adds all given values to the set that haven't already been added.

注意:

Values of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

警告

All comparisons are strict (type and value).

パラメータ

values

Values to add to the set.

戻り値

値を返しません。

例

例1 Ds\Set::add() example using integers

<?php
$set = new \Ds\Set();

$set->add(1);
$set->add(1);
$set->add(2);
$set->add(3);

// Strict comparison would not treat these the same as int(1)
$set->add("1");
$set->add(true);

var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (5) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  string(1) "1"
  [4]=>
  bool(true)
}

例2 Ds\Set::add() example using objects

<?php
class HashableObject implements \Ds\Hashable
{
/**
* An arbitrary value to use as the hash value. Does not define equality.
*/
private $value;

public function __construct($value)
{
$this->value = $value;
}

public function hash()
{
return $this->value;
}

public function equals($obj): bool
{
return $this->value === $obj->value;
}
}

$set = new \Ds\Set();

$obj = new \ArrayIterator([]);

// Adding the same instance multiple times will only add the first.
$set->add($obj);
$set->add($obj);

// Adding multiple instances of the same object will add them all.
$set->add(new \stdClass());
$set->add(new \stdClass());

// Adding multiple instances of equal hashable objects will only add the first.
$set->add(new \HashableObject(1));
$set->add(new \HashableObject(1));
$set->add(new \HashableObject(2));
$set->add(new \HashableObject(2));

var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (5) {
  [0]=>
  object(ArrayIterator)#2 (1) {
    ["storage":"ArrayIterator":private]=>
    array(0) {
    }
  }
  [1]=>
  object(stdClass)#3 (0) {
  }
  [2]=>
  object(stdClass)#4 (0) {
  }
  [3]=>
  object(HashableObject)#5 (1) {
    ["value":"HashableObject":private]=>
    int(1)
  }
  [4]=>
  object(HashableObject)#6 (1) {
    ["value":"HashableObject":private]=>
    int(2)
  }
}


Allocates enough memory for a required capacity

  • ≪ Ds\Set::add
  • Ds\Set::capacity ≫
  • PHP Manual
  • Ds\Set
  • Allocates enough memory for a required capacity

Ds\Set::allocate

(PECL ds >= 1.0.0)

Ds\Set::allocate — Allocates enough memory for a required capacity

説明

public Ds\Set::allocate(int $capacity): void

Allocates enough memory for a required capacity.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

戻り値

値を返しません。

例

例1 Ds\Set::allocate() example

<?php
$set = new \Ds\Set();
var_dump($set->capacity());

$set->allocate(100);
var_dump($set->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)
int(128)


Returns the current capacity

  • ≪ Ds\Set::allocate
  • Ds\Set::clear ≫
  • PHP Manual
  • Ds\Set
  • Returns the current capacity

Ds\Set::capacity

(PECL ds >= 1.0.0)

Ds\Set::capacity — Returns the current capacity

説明

public Ds\Set::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\Set::capacity() example

<?php
$set = new \Ds\Set();
var_dump($set->capacity());

$set->add(...range(1, 50));
var_dump($set->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(16)
int(64)


Removes all values

  • ≪ Ds\Set::capacity
  • Ds\Set::__construct ≫
  • PHP Manual
  • Ds\Set
  • Removes all values

Ds\Set::clear

(PECL ds >= 1.0.0)

Ds\Set::clear — Removes all values

説明

public Ds\Set::clear(): void

Removes all values from the set.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Set::clear() example

<?php
$set = new \Ds\Set([1, 2, 3]);
print_r($set);

$set->clear();
print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Set Object
(
)


Creates a new instance

  • ≪ Ds\Set::clear
  • Ds\Set::contains ≫
  • PHP Manual
  • Ds\Set
  • Creates a new instance

Ds\Set::__construct

(PECL ds >= 1.0.0)

Ds\Set::__construct — Creates a new instance

説明

public Ds\Set::__construct(mixed $values = [])

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Set::__construct() example

<?php
$set = new \Ds\Set();
var_dump($set);

$set = new \Ds\Set([1, 2, 3]);
var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (0) {
}
object(Ds\Set)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Determines if the set contains all values

  • ≪ Ds\Set::__construct
  • Ds\Set::copy ≫
  • PHP Manual
  • Ds\Set
  • Determines if the set contains all values

Ds\Set::contains

(PECL ds >= 1.0.0)

Ds\Set::contains — Determines if the set contains all values

説明

public Ds\Set::contains(mixed ...$values): bool

Determines if the set contains all values.

注意:

Values of type object are supported. If an object implements Ds\Hashable, equality will be determined by the object's equals function. If an object does not implement Ds\Hashable, objects must be references to the same instance to be considered equal.

警告

All comparisons are strict (type and value).

パラメータ

values

Values to check.

戻り値

false if any of the provided values are not in the set, true otherwise.

例

例1 Ds\Set::contains() example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->contains(1)); // true
var_dump($set->contains(1, 2)); // true
var_dump($set->contains(...[1, 2])); // true

var_dump($set->contains("1")); // false
var_dump($set->contains(...[1, 2, 3, 4])); // false

var_dump($set->contains(...[])); // true
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(false)
bool(false)
bool(true)


Returns a shallow copy of the set

  • ≪ Ds\Set::contains
  • Ds\Set::count ≫
  • PHP Manual
  • Ds\Set
  • Returns a shallow copy of the set

Ds\Set::copy

(PECL ds >= 1.0.0)

Ds\Set::copy — Returns a shallow copy of the set

説明

public Ds\Set::copy(): Ds\Set

Returns a shallow copy of the set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the set.

例

例1 Ds\Set::copy() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->add(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)


Returns the number of values in the set

  • ≪ Ds\Set::copy
  • Ds\Set::diff ≫
  • PHP Manual
  • Ds\Set
  • Returns the number of values in the set

Ds\Set::count

(PECL ds >= 1.0.0)

Ds\Set::count — Returns the number of values in the set

説明

See Countable::count()


Creates a new set using values that aren't in another set

  • ≪ Ds\Set::count
  • Ds\Set::filter ≫
  • PHP Manual
  • Ds\Set
  • Creates a new set using values that aren't in another set

Ds\Set::diff

(PECL ds >= 1.0.0)

Ds\Set::diff — Creates a new set using values that aren't in another set

説明

public Ds\Set::diff(Ds\Set $set): Ds\Set

Creates a new set using values that aren't in another set.

A \ B = {x ∈ A | x ? B}

パラメータ

set

Set containing the values to exclude.

戻り値

A new set containing all values that were not in the other set.

参考

  • » Complement on Wikipedia

例

例1 Ds\Set::diff() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->diff($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}


Creates a new set using a callable to determine which values to include

  • ≪ Ds\Set::diff
  • Ds\Set::first ≫
  • PHP Manual
  • Ds\Set
  • Creates a new set using a callable to determine which values to include

Ds\Set::filter

(PECL ds >= 1.0.0)

Ds\Set::filter — Creates a new set using a callable to determine which values to include

説明

public Ds\Set::filter(callable $callback = ?): Ds\Set

Creates a new set using a callable to determine which values to include.

パラメータ

callback

callback(mixed $value): bool

Optional callable which returns true if the value should be included, false otherwise.

If a callback is not provided, only values which are true (see converting to boolean) will be included.

戻り値

A new set containing all the values for which either the callback returned true, or all values that convert to true if a callback was not provided.

例

例1 Ds\Set::filter() example using callback function

<?php
$set = new \Ds\Set([1, 2, 3, 4, 5]);

var_dump($set->filter(function($value) {
return $value % 2 == 0;
}));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (2) {
  [0]=>
  int(2)
  [1]=>
  int(4)
}

例2 Ds\Set::filter() example without a callback function

<?php
$set = new \Ds\Set([0, 1, 'a', true, false]);

var_dump($set->filter());
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  string(1) "a"
  [2]=>
  bool(true)
}


Returns the first value in the set

  • ≪ Ds\Set::filter
  • Ds\Set::get ≫
  • PHP Manual
  • Ds\Set
  • Returns the first value in the set

Ds\Set::first

(PECL ds >= 1.0.0)

Ds\Set::first — Returns the first value in the set

説明

public Ds\Set::first(): mixed

Returns the first value in the set.

パラメータ

この関数にはパラメータはありません。

戻り値

The first value in the set.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Set::first() example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->first());
?>

上の例の出力は、 たとえば以下のようになります。

int(1)


Returns the value at a given index

  • ≪ Ds\Set::first
  • Ds\Set::intersect ≫
  • PHP Manual
  • Ds\Set
  • Returns the value at a given index

Ds\Set::get

(PECL ds >= 1.0.0)

Ds\Set::get — Returns the value at a given index

説明

public Ds\Set::get(int $index): mixed

Returns the value at a given index.

パラメータ

index

The index to access, starting at 0.

戻り値

The value at the requested index.

エラー / 例外

OutOfRangeException if the index is not valid.

例

例1 Ds\Set::get() example

<?php
$set = new \Ds\Set(["a", "b", "c"]);

var_dump($set->get(0));
var_dump($set->get(1));
var_dump($set->get(2));
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"

例2 Ds\Set::get() example using array syntax

<?php
$set = new \Ds\Set(["a", "b", "c"]);

var_dump($set[0]);
var_dump($set[1]);
var_dump($set[2]);
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Creates a new set by intersecting values with another set

  • ≪ Ds\Set::get
  • Ds\Set::isEmpty ≫
  • PHP Manual
  • Ds\Set
  • Creates a new set by intersecting values with another set

Ds\Set::intersect

(PECL ds >= 1.0.0)

Ds\Set::intersect — Creates a new set by intersecting values with another set

説明

public Ds\Set::intersect(Ds\Set $set): Ds\Set

Creates a new set using values common to both the current instance and another set. In other words, returns a copy of the current instance with all values removed that are not in the other set.

A ∩ B = {x : x ∈ A ∧ x ∈ B}

パラメータ

set

The other set.

戻り値

The intersection of the current instance and another set.

参考

  • » Intersection on Wikipedia

例

例1 Ds\Set::intersect() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->intersect($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (1) {
  [0]=>
  int(3)
}


Returns whether the set is empty

  • ≪ Ds\Set::intersect
  • Ds\Set::join ≫
  • PHP Manual
  • Ds\Set
  • Returns whether the set is empty

Ds\Set::isEmpty

(PECL ds >= 1.0.0)

Ds\Set::isEmpty — Returns whether the set is empty

説明

public Ds\Set::isEmpty(): bool

Returns whether the set is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the set is empty, false otherwise.

例

例1 Ds\Set::isEmpty() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Joins all values together as a string

  • ≪ Ds\Set::isEmpty
  • Ds\Set::jsonSerialize ≫
  • PHP Manual
  • Ds\Set
  • Joins all values together as a string

Ds\Set::join

(PECL ds >= 1.0.0)

Ds\Set::join — Joins all values together as a string

説明

public Ds\Set::join(string $glue = ?): string

Joins all values together as a string using an optional separator between each value.

パラメータ

glue

An optional string to separate each value.

戻り値

All values of the set joined together as a string.

例

例1 Ds\Set::join() example using a separator string

<?php
$set = new \Ds\Set(["a", "b", "c", 1, 2, 3]);

var_dump($set->join("|"));
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "a|b|c|1|2|3"

例2 Ds\Set::join() example without a separator string

<?php
$set = new \Ds\Set(["a", "b", "c", 1, 2, 3]);

var_dump($set->join());
?>

上の例の出力は、 たとえば以下のようになります。

string(11) "abc123"


Returns a representation that can be converted to JSON

  • ≪ Ds\Set::join
  • Ds\Set::last ≫
  • PHP Manual
  • Ds\Set
  • Returns a representation that can be converted to JSON

Ds\Set::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Set::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns the last value in the set

  • ≪ Ds\Set::jsonSerialize
  • Ds\Set::merge ≫
  • PHP Manual
  • Ds\Set
  • Returns the last value in the set

Ds\Set::last

(PECL ds >= 1.0.0)

Ds\Set::last — Returns the last value in the set

説明

public Ds\Set::last(): mixed

Returns the last value in the set.

パラメータ

この関数にはパラメータはありません。

戻り値

The last value in the set.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Set::last() example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->last());
?>

上の例の出力は、 たとえば以下のようになります。

int(3)


Returns the result of adding all given values to the set

  • ≪ Ds\Set::last
  • Ds\Set::reduce ≫
  • PHP Manual
  • Ds\Set
  • Returns the result of adding all given values to the set

Ds\Set::merge

(PECL ds >= 1.0.3)

Ds\Set::merge — Returns the result of adding all given values to the set

説明

public Ds\Set::merge(mixed $values): Ds\Set

Returns the result of adding all given values to the set.

パラメータ

values

A traversable object or an array.

戻り値

The result of adding all given values to the set, effectively the same as adding the values to a copy, then returning that copy.

注意:

The current instance won't be affected.

例

例1 Ds\Set::merge() example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->merge([3, 4, 5]));
var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#2 (6) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
}
object(Ds\Set)#1 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Reduces the set to a single value using a callback function

  • ≪ Ds\Set::merge
  • Ds\Set::remove ≫
  • PHP Manual
  • Ds\Set
  • Reduces the set to a single value using a callback function

Ds\Set::reduce

(PECL ds >= 1.0.0)

Ds\Set::reduce — Reduces the set to a single value using a callback function

説明

public Ds\Set::reduce(callable $callback, mixed $initial = ?): mixed

Reduces the set to a single value using a callback function.

パラメータ

callback
callback(mixed $carry, mixed $value): mixed
carry

The return value of the previous callback, or initial if it's the first iteration.

value

The value of the current iteration.

initial

The initial value of the carry value. Can be null.

戻り値

The return value of the final callback.

例

例1 Ds\Set::reduce() with initial value example

<?php
$set = new \Ds\Set([1, 2, 3]);

$callback = function($carry, $value) {
return $carry * $value;
};

var_dump($set->reduce($callback, 5));

// Iterations:
//
// $carry = $initial = 5
//
// $carry = $carry * 1 = 5
// $carry = $carry * 2 = 10
// $carry = $carry * 3 = 30
?>

上の例の出力は、 たとえば以下のようになります。

int(30)

例2 Ds\Set::reduce() without an initial value example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->reduce(function($carry, $value) {
return $carry + $value + 5;
}));

// Iterations:
//
// $carry = $initial = null
//
// $carry = $carry + 1 + 5 = 6
// $carry = $carry + 2 + 5 = 13
// $carry = $carry + 3 + 5 = 21
?>

上の例の出力は、 たとえば以下のようになります。

int(21)


Removes all given values from the set

  • ≪ Ds\Set::reduce
  • Ds\Set::reverse ≫
  • PHP Manual
  • Ds\Set
  • Removes all given values from the set

Ds\Set::remove

(PECL ds >= 1.0.0)

Ds\Set::remove — Removes all given values from the set

説明

public Ds\Set::remove(mixed ...$values): void

Removes all given values from the set, ignoring any that are not in the set.

パラメータ

values

The values to remove.

戻り値

値を返しません。

例

例1 Ds\Set::remove() example

<?php
$set = new \Ds\Set([1, 2, 3, 4, 5]);

$set->remove(1); // Remove 1
$set->remove(1, 2); // Can't find 1, but remove 2
$set->remove(...[3, 4]); // Remove 3 and 4

var_dump($set);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#1 (1) {
  [0]=>
  int(5)
}


Reverses the set in-place

  • ≪ Ds\Set::remove
  • Ds\Set::reversed ≫
  • PHP Manual
  • Ds\Set
  • Reverses the set in-place

Ds\Set::reverse

(PECL ds >= 1.0.0)

Ds\Set::reverse — Reverses the set in-place

説明

public Ds\Set::reverse(): void

Reverses the set in-place.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Set::reverse() example

<?php
$set = new \Ds\Set(["a", "b", "c"]);
$set->reverse();

print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => c
    [1] => b
    [2] => a
)


Returns a reversed copy

  • ≪ Ds\Set::reverse
  • Ds\Set::slice ≫
  • PHP Manual
  • Ds\Set
  • Returns a reversed copy

Ds\Set::reversed

(PECL ds >= 1.0.0)

Ds\Set::reversed — Returns a reversed copy

説明

public Ds\Set::reversed(): Ds\Set

Returns a reversed copy of the set.

パラメータ

この関数にはパラメータはありません。

戻り値

A reversed copy of the set.

注意:

The current instance is not affected.

例

例1 Ds\Set::reversed() example

<?php
$set = new \Ds\Set(["a", "b", "c"]);

print_r($set->reversed());
print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => c
    [1] => b
    [2] => a
)
Ds\Set Object
(
    [0] => a
    [1] => b
    [2] => c
)


Returns a sub-set of a given range

  • ≪ Ds\Set::reversed
  • Ds\Set::sort ≫
  • PHP Manual
  • Ds\Set
  • Returns a sub-set of a given range

Ds\Set::slice

(PECL ds >= 1.0.0)

Ds\Set::slice — Returns a sub-set of a given range

説明

public Ds\Set::slice(int $index, int $length = ?): Ds\Set

Creates a sub-set of a given range.

パラメータ

index

The index at which the sub-set starts.

If positive, the set will start at that index in the set. If negative, the set will start that far from the end.

length

If a length is given and is positive, the resulting set will have up to that many values in it. If the length results in an overflow, only values up to the end of the set will be included. If a length is given and is negative, the set will stop that many values from the end. If a length is not provided, the resulting set will contain all values between the index and the end of the set.

戻り値

A sub-set of the given range.

例

例1 Ds\Set::slice() example

<?php
$set = new \Ds\Set(["a", "b", "c", "d", "e"]);

// Slice from 2 onwards
print_r($set->slice(2));

// Slice from 1, for a length of 3
print_r($set->slice(1, 3));

// Slice from 1 onwards
print_r($set->slice(1));

// Slice from 2 from the end onwards
print_r($set->slice(-2));

// Slice from 1 to 1 from the end
print_r($set->slice(1, -1));
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => c
    [1] => d
    [2] => e
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
    [3] => e
)
Ds\Set Object
(
    [0] => d
    [1] => e
)
Ds\Set Object
(
    [0] => b
    [1] => c
    [2] => d
)


Sorts the set in-place

  • ≪ Ds\Set::slice
  • Ds\Set::sorted ≫
  • PHP Manual
  • Ds\Set
  • Sorts the set in-place

Ds\Set::sort

(PECL ds >= 1.0.0)

Ds\Set::sort — Sorts the set in-place

説明

public Ds\Set::sort(callable $comparator = ?): void

Sorts the set in-place, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

値を返しません。

例

例1 Ds\Set::sort() example

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);
$set->sort();

print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Set::sort() example using a comparator

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

$set->sort(function($a, $b) {
return $b <=> $a;
});

print_r($set);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns a sorted copy

  • ≪ Ds\Set::sort
  • Ds\Set::sum ≫
  • PHP Manual
  • Ds\Set
  • Returns a sorted copy

Ds\Set::sorted

(PECL ds >= 1.0.0)

Ds\Set::sorted — Returns a sorted copy

説明

public Ds\Set::sorted(callable $comparator = ?): Ds\Set

Returns a sorted copy, using an optional comparator function.

パラメータ

comparator

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

Returns a sorted copy of the set.

例

例1 Ds\Set::sorted() example

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

print_r($set->sorted());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)

例2 Ds\Set::sorted() example using a comparator

<?php
$set = new \Ds\Set([4, 5, 1, 3, 2]);

$sorted = $set->sorted(function($a, $b) {
return $b <=> $a;
});

print_r($sorted);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Set Object
(
    [0] => 5
    [1] => 4
    [2] => 3
    [3] => 2
    [4] => 1
)


Returns the sum of all values in the set

  • ≪ Ds\Set::sorted
  • Ds\Set::toArray ≫
  • PHP Manual
  • Ds\Set
  • Returns the sum of all values in the set

Ds\Set::sum

(PECL ds >= 1.0.0)

Ds\Set::sum — Returns the sum of all values in the set

説明

public Ds\Set::sum(): int|float

Returns the sum of all values in the set.

注意:

Arrays and objects are considered equal to zero when calculating the sum.

パラメータ

この関数にはパラメータはありません。

戻り値

The sum of all the values in the set as either a float or int depending on the values in the set.

例

例1 Ds\Set::sum() integer example

<?php
$set = new \Ds\Set([1, 2, 3]);
var_dump($set->sum());
?>

上の例の出力は、 たとえば以下のようになります。

int(6)

例2 Ds\Set::sum() float example

<?php
$set = new \Ds\Set([1, 2.5, 3]);
var_dump($set->sum());
?>

上の例の出力は、 たとえば以下のようになります。

float(6.5)


Converts the set to an array

  • ≪ Ds\Set::sum
  • Ds\Set::union ≫
  • PHP Manual
  • Ds\Set
  • Converts the set to an array

Ds\Set::toArray

(PECL ds >= 1.0.0)

Ds\Set::toArray — Converts the set to an array

説明

public Ds\Set::toArray(): array

Converts the set to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the set.

例

例1 Ds\Set::toArray() example

<?php
$set = new \Ds\Set([1, 2, 3]);

var_dump($set->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Creates a new set using values from the current instance and another set

  • ≪ Ds\Set::toArray
  • Ds\Set::xor ≫
  • PHP Manual
  • Ds\Set
  • Creates a new set using values from the current instance and another set

Ds\Set::union

(PECL ds >= 1.0.0)

Ds\Set::union — Creates a new set using values from the current instance and another set

説明

public Ds\Set::union(Ds\Set $set): Ds\Set

Creates a new set that contains the values of the current instance as well as the values of another set.

A ∪ B = {x: x ∈ A ∨ x ∈ B}

パラメータ

set

The other set, to combine with the current instance.

戻り値

A new set containing all the values of the current instance as well as another set.

参考

  • » Union on Wikipedia

例

例1 Ds\Set::union() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->union($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (5) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
  [3]=>
  int(4)
  [4]=>
  int(5)
}


Creates a new set using values in either the current instance or in another set, but not in both

  • ≪ Ds\Set::union
  • Ds\Stack ≫
  • PHP Manual
  • Ds\Set
  • Creates a new set using values in either the current instance or in another set, but not in both

Ds\Set::xor

(PECL ds >= 1.0.0)

Ds\Set::xor — Creates a new set using values in either the current instance or in another set, but not in both

説明

public Ds\Set::xor(Ds\Set $set): Ds\Set

Creates a new set containing values in the current instance as well as another set, but not in both.

A ? B = {x : x ∈ (A \ B) ∪ (B \ A)}

パラメータ

set

The other set.

戻り値

A new set containing values in the current instance as well as another set, but not in both.

参考

  • » Symmetric Difference on Wikipedia

例

例1 Ds\Set::xor() example

<?php
$a = new \Ds\Set([1, 2, 3]);
$b = new \Ds\Set([3, 4, 5]);

var_dump($a->xor($b));
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Set)#3 (4) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(4)
  [3]=>
  int(5)
}


The Stack class

(PECL ds >= 1.0.0)

はじめに

A Stack is a "last in, first out" or "LIFO" collection that only allows access to the value at the top of the structure and iterates in that order, destructively.

Uses a Ds\Vector internally.

クラス概要

class Ds\Stack implements Ds\Collection, ArrayAccess {
/* メソッド */
public allocate(int $capacity): void
public capacity(): int
public clear(): void
public copy(): Ds\Stack
public isEmpty(): bool
public peek(): mixed
public pop(): mixed
public push(mixed ...$values): void
public toArray(): array
}

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Stack::allocate — Allocates enough memory for a required capacity
  • Ds\Stack::capacity — Returns the current capacity
  • Ds\Stack::clear — Removes all values
  • Ds\Stack::__construct — Creates a new instance
  • Ds\Stack::copy — Returns a shallow copy of the stack
  • Ds\Stack::count — Returns the number of values in the stack
  • Ds\Stack::isEmpty — Returns whether the stack is empty
  • Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Stack::peek — Returns the value at the top of the stack
  • Ds\Stack::pop — Removes and returns the value at the top of the stack
  • Ds\Stack::push — Pushes values onto the stack
  • Ds\Stack::toArray — Converts the stack to an array


Allocates enough memory for a required capacity

  • ≪ Ds\Stack
  • Ds\Stack::capacity ≫
  • PHP Manual
  • Ds\Stack
  • Allocates enough memory for a required capacity

Ds\Stack::allocate

(PECL ds >= 1.0.0)

Ds\Stack::allocate — Allocates enough memory for a required capacity

説明

public Ds\Stack::allocate(int $capacity): void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

戻り値

値を返しません。


Returns the current capacity

  • ≪ Ds\Stack::allocate
  • Ds\Stack::clear ≫
  • PHP Manual
  • Ds\Stack
  • Returns the current capacity

Ds\Stack::capacity

(PECL ds >= 1.0.0)

Ds\Stack::capacity — Returns the current capacity

説明

public Ds\Stack::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.


Removes all values

  • ≪ Ds\Stack::capacity
  • Ds\Stack::__construct ≫
  • PHP Manual
  • Ds\Stack
  • Removes all values

Ds\Stack::clear

(PECL ds >= 1.0.0)

Ds\Stack::clear — Removes all values

説明

public Ds\Stack::clear(): void

Removes all values from the stack.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Stack::clear() example

<?php
$stack = new \Ds\Stack([1, 2, 3]);
print_r($stack);

$stack->clear();
print_r($stack);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)
Ds\Stack Object
(
)


Creates a new instance

  • ≪ Ds\Stack::clear
  • Ds\Stack::copy ≫
  • PHP Manual
  • Ds\Stack
  • Creates a new instance

Ds\Stack::__construct

(PECL ds >= 1.0.0)

Ds\Stack::__construct — Creates a new instance

説明

public Ds\Stack::__construct(mixed $values = ?)

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Stack::__construct() example

<?php
$stack = new \Ds\Stack();
print_r($stack);

$stack = new \Ds\Stack([1, 2, 3]);
print_r($stack);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
)
Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)


Returns a shallow copy of the stack

  • ≪ Ds\Stack::__construct
  • Ds\Stack::count ≫
  • PHP Manual
  • Ds\Stack
  • Returns a shallow copy of the stack

Ds\Stack::copy

(PECL ds >= 1.0.0)

Ds\Stack::copy — Returns a shallow copy of the stack

説明

public Ds\Stack::copy(): Ds\Stack

Returns a shallow copy of the stack.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the stack.

例

例1 Ds\Stack::copy() example

<?php
$a = new \Ds\Stack([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
    [0] => 3
    [1] => 2
    [2] => 1
)
Ds\Stack Object
(
    [0] => 4
    [1] => 3
    [2] => 2
    [3] => 1
)


Returns the number of values in the stack

  • ≪ Ds\Stack::copy
  • Ds\Stack::isEmpty ≫
  • PHP Manual
  • Ds\Stack
  • Returns the number of values in the stack

Ds\Stack::count

(PECL ds >= 1.0.0)

Ds\Stack::count — Returns the number of values in the stack

説明

See Countable::count()


Returns whether the stack is empty

  • ≪ Ds\Stack::count
  • Ds\Stack::jsonSerialize ≫
  • PHP Manual
  • Ds\Stack
  • Returns whether the stack is empty

Ds\Stack::isEmpty

(PECL ds >= 1.0.0)

Ds\Stack::isEmpty — Returns whether the stack is empty

説明

public Ds\Stack::isEmpty(): bool

Returns whether the stack is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the stack is empty, false otherwise.

例

例1 Ds\Stack::isEmpty() example

<?php
$a = new \Ds\Stack([1, 2, 3]);
$b = new \Ds\Stack();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Returns a representation that can be converted to JSON

  • ≪ Ds\Stack::isEmpty
  • Ds\Stack::peek ≫
  • PHP Manual
  • Ds\Stack
  • Returns a representation that can be converted to JSON

Ds\Stack::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Stack::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns the value at the top of the stack

  • ≪ Ds\Stack::jsonSerialize
  • Ds\Stack::pop ≫
  • PHP Manual
  • Ds\Stack
  • Returns the value at the top of the stack

Ds\Stack::peek

(PECL ds >= 1.0.0)

Ds\Stack::peek — Returns the value at the top of the stack

説明

public Ds\Stack::peek(): mixed

Returns the value at the top of the stack, but does not remove it.

パラメータ

この関数にはパラメータはありません。

戻り値

The value at the top of the stack.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Stack::peek() example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c");

var_dump($stack->peek());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "c"


Removes and returns the value at the top of the stack

  • ≪ Ds\Stack::peek
  • Ds\Stack::push ≫
  • PHP Manual
  • Ds\Stack
  • Removes and returns the value at the top of the stack

Ds\Stack::pop

(PECL ds >= 1.0.0)

Ds\Stack::pop — Removes and returns the value at the top of the stack

説明

public Ds\Stack::pop(): mixed

Removes and returns the value at the top of the stack.

パラメータ

この関数にはパラメータはありません。

戻り値

The removed value which was at the top of the stack.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Stack::pop() example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c");

var_dump($stack->pop());
var_dump($stack->pop());
var_dump($stack->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "c"
string(1) "b"
string(1) "a"


Pushes values onto the stack

  • ≪ Ds\Stack::pop
  • Ds\Stack::toArray ≫
  • PHP Manual
  • Ds\Stack
  • Pushes values onto the stack

Ds\Stack::push

(PECL ds >= 1.0.0)

Ds\Stack::push — Pushes values onto the stack

説明

public Ds\Stack::push(mixed ...$values): void

Pushes values onto the stack.

パラメータ

values

The values to push onto the stack.

戻り値

値を返しません。

例

例1 Ds\Stack::push() example

<?php
$stack = new \Ds\Stack();

$stack->push("a");
$stack->push("b");
$stack->push("c", "d");
$stack->push(...["e", "f"]);

print_r($stack);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Stack Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)


Converts the stack to an array

  • ≪ Ds\Stack::push
  • Ds\Queue ≫
  • PHP Manual
  • Ds\Stack
  • Converts the stack to an array

Ds\Stack::toArray

(PECL ds >= 1.0.0)

Ds\Stack::toArray — Converts the stack to an array

説明

public Ds\Stack::toArray(): array

Converts the stack to an array.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the stack.

例

例1 Ds\Stack::toArray() example

<?php
$stack = new \Ds\Stack([1, 2, 3]);

var_dump($stack->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(3)
  [1]=>
  int(2)
  [2]=>
  int(1)
}


The Queue class

(PECL ds >= 1.0.0)

はじめに

A Queue is a "first in, first out" or "FIFO" collection that only allows access to the value at the front of the queue and iterates in that order, destructively.

クラス概要

class Ds\Queue implements Ds\Collection, ArrayAccess {
/* 定数 */
const int MIN_CAPACITY = 8;
/* メソッド */
public allocate(int $capacity): void
public capacity(): int
public clear(): void
public copy(): Ds\Queue
public isEmpty(): bool
public peek(): mixed
public pop(): mixed
public push(mixed ...$values): void
public toArray(): array
}

定義済み定数

Ds\Queue::MIN_CAPACITY

変更履歴

バージョン | 説明
PECL ds 1.3.0 | The class now implements ArrayAccess.

目次

  • Ds\Queue::allocate — Allocates enough memory for a required capacity
  • Ds\Queue::capacity — Returns the current capacity
  • Ds\Queue::clear — Removes all values
  • Ds\Queue::__construct — Creates a new instance
  • Ds\Queue::copy — Returns a shallow copy of the queue
  • Ds\Queue::count — Returns the number of values in the queue
  • Ds\Queue::isEmpty — Returns whether the queue is empty
  • Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\Queue::peek — Returns the value at the front of the queue
  • Ds\Queue::pop — Removes and returns the value at the front of the queue
  • Ds\Queue::push — Pushes values into the queue
  • Ds\Queue::toArray — Converts the queue to an array


Allocates enough memory for a required capacity

  • ≪ Ds\Queue
  • Ds\Queue::capacity ≫
  • PHP Manual
  • Ds\Queue
  • Allocates enough memory for a required capacity

Ds\Queue::allocate

(PECL ds >= 1.0.0)

Ds\Queue::allocate — Allocates enough memory for a required capacity

説明

public Ds\Queue::allocate(int $capacity): void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

注意:

Capacity will always be rounded up to the nearest power of 2.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

戻り値

値を返しません。

例

例1 Ds\Queue::allocate() example

<?php
$queue = new \Ds\Queue();
var_dump($queue->capacity());

$queue->allocate(100);
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(128)


Returns the current capacity

  • ≪ Ds\Queue::allocate
  • Ds\Queue::clear ≫
  • PHP Manual
  • Ds\Queue
  • Returns the current capacity

Ds\Queue::capacity

(PECL ds >= 1.0.0)

Ds\Queue::capacity — Returns the current capacity

説明

public Ds\Queue::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\Queue::capacity() example

<?php
$queue = new \Ds\Queue();
var_dump($queue->capacity());

$queue->push(...range(1, 50));
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(64)


Removes all values

  • ≪ Ds\Queue::capacity
  • Ds\Queue::__construct ≫
  • PHP Manual
  • Ds\Queue
  • Removes all values

Ds\Queue::clear

(PECL ds >= 1.0.0)

Ds\Queue::clear — Removes all values

説明

public Ds\Queue::clear(): void

Removes all values from the queue.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\Queue::clear() example

<?php
$queue = new \Ds\Queue([1, 2, 3]);
print_r($queue);

$queue->clear();
print_r($queue);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Queue Object
(
)


Creates a new instance

  • ≪ Ds\Queue::clear
  • Ds\Queue::copy ≫
  • PHP Manual
  • Ds\Queue
  • Creates a new instance

Ds\Queue::__construct

(PECL ds >= 1.0.0)

Ds\Queue::__construct — Creates a new instance

説明

public Ds\Queue::__construct(mixed $values = ?)

Creates a new instance, using either a traversable object or an array for the initial values.

パラメータ

values

A traversable object or an array to use for the initial values.

例

例1 Ds\Queue::__construct() example

<?php
$queue = new \Ds\Queue();
var_dump($queue);

$queue = new \Ds\Queue([1, 2, 3]);
var_dump($queue);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\Queue)#2 (0) {
}
object(Ds\Queue)#2 (3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


Returns a shallow copy of the queue

  • ≪ Ds\Queue::__construct
  • Ds\Queue::count ≫
  • PHP Manual
  • Ds\Queue
  • Returns a shallow copy of the queue

Ds\Queue::copy

(PECL ds >= 1.0.0)

Ds\Queue::copy — Returns a shallow copy of the queue

説明

public Ds\Queue::copy(): Ds\Queue

Returns a shallow copy of the queue.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the queue.

例

例1 Ds\Queue::copy() example

<?php
$a = new \Ds\Queue([1, 2, 3]);
$b = $a->copy();

// Updating the copy doesn't affect the original
$b->push(4);

print_r($a);
print_r($b);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
)
Ds\Queue Object
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
)


Returns the number of values in the queue

  • ≪ Ds\Queue::copy
  • Ds\Queue::isEmpty ≫
  • PHP Manual
  • Ds\Queue
  • Returns the number of values in the queue

Ds\Queue::count

(PECL ds >= 1.0.0)

Ds\Queue::count — Returns the number of values in the queue

説明

See Countable::count()


Returns whether the queue is empty

  • ≪ Ds\Queue::count
  • Ds\Queue::jsonSerialize ≫
  • PHP Manual
  • Ds\Queue
  • Returns whether the queue is empty

Ds\Queue::isEmpty

(PECL ds >= 1.0.0)

Ds\Queue::isEmpty — Returns whether the queue is empty

説明

public Ds\Queue::isEmpty(): bool

Returns whether the queue is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the queue is empty, false otherwise.

例

例1 Ds\Queue::isEmpty() example

<?php
$a = new \Ds\Queue([1, 2, 3]);
$b = new \Ds\Queue();

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Returns a representation that can be converted to JSON

  • ≪ Ds\Queue::isEmpty
  • Ds\Queue::peek ≫
  • PHP Manual
  • Ds\Queue
  • Returns a representation that can be converted to JSON

Ds\Queue::jsonSerialize

(PECL ds >= 1.0.0)

Ds\Queue::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns the value at the front of the queue

  • ≪ Ds\Queue::jsonSerialize
  • Ds\Queue::pop ≫
  • PHP Manual
  • Ds\Queue
  • Returns the value at the front of the queue

Ds\Queue::peek

(PECL ds >= 1.0.0)

Ds\Queue::peek — Returns the value at the front of the queue

説明

public Ds\Queue::peek(): mixed

Returns the value at the front of the queue, but does not remove it.

パラメータ

この関数にはパラメータはありません。

戻り値

The value at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Queue::peek() example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c");

var_dump($queue->peek());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"


Removes and returns the value at the front of the queue

  • ≪ Ds\Queue::peek
  • Ds\Queue::push ≫
  • PHP Manual
  • Ds\Queue
  • Removes and returns the value at the front of the queue

Ds\Queue::pop

(PECL ds >= 1.0.0)

Ds\Queue::pop — Removes and returns the value at the front of the queue

説明

public Ds\Queue::pop(): mixed

Removes and returns the value at the front of the queue.

パラメータ

この関数にはパラメータはありません。

戻り値

The removed value which was at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\Queue::pop() example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c");

var_dump($queue->pop());
var_dump($queue->pop());
var_dump($queue->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Pushes values into the queue

  • ≪ Ds\Queue::pop
  • Ds\Queue::toArray ≫
  • PHP Manual
  • Ds\Queue
  • Pushes values into the queue

Ds\Queue::push

(PECL ds >= 1.0.0)

Ds\Queue::push — Pushes values into the queue

説明

public Ds\Queue::push(mixed ...$values): void

Pushes values into the queue.

パラメータ

values

The values to push into the queue.

戻り値

値を返しません。

例

例1 Ds\Queue::push() example

<?php
$queue = new \Ds\Queue();

$queue->push("a");
$queue->push("b");
$queue->push("c", "d");
$queue->push(...["e", "f"]);

print_r($queue);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\Queue Object
(
    [0] => a
    [1] => b
    [2] => c
    [3] => d
    [4] => e
    [5] => f
)


Converts the queue to an array

  • ≪ Ds\Queue::push
  • Ds\PriorityQueue ≫
  • PHP Manual
  • Ds\Queue
  • Converts the queue to an array

Ds\Queue::toArray

(PECL ds >= 1.0.0)

Ds\Queue::toArray — Converts the queue to an array

説明

public Ds\Queue::toArray(): array

Converts the queue to an array.

注意:

Casting to an array is not supported yet.

注意:

This method is not destructive.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the queue.

例

例1 Ds\Queue::toArray() example

<?php
$queue = new \Ds\Queue([1, 2, 3]);

var_dump($queue->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}


The PriorityQueue class

(PECL ds >= 1.0.0)

はじめに

A PriorityQueue is very similar to a Queue. Values are pushed into the queue with an assigned priority, and the value with the highest priority will always be at the front of the queue.

Implemented using a max heap.

注意:

"First in, first out" ordering is preserved for values with the same priority.

注意:

Iterating over a PriorityQueue is destructive, equivalent to successive pop operations until the queue is empty.

クラス概要

class Ds\PriorityQueue implements Ds\Collection {
/* 定数 */
const int MIN_CAPACITY = 8;
/* メソッド */
public allocate(int $capacity): void
public capacity(): int
public clear(): void
public copy(): Ds\PriorityQueue
public isEmpty(): bool
public peek(): mixed
public pop(): mixed
public push(mixed $value, int $priority): void
public toArray(): array
}

定義済み定数

Ds\PriorityQueue::MIN_CAPACITY

目次

  • Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity
  • Ds\PriorityQueue::capacity — Returns the current capacity
  • Ds\PriorityQueue::clear — Removes all values
  • Ds\PriorityQueue::__construct — Creates a new instance
  • Ds\PriorityQueue::copy — Returns a shallow copy of the queue
  • Ds\PriorityQueue::count — Returns the number of values in the queue
  • Ds\PriorityQueue::isEmpty — Returns whether the queue is empty
  • Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON
  • Ds\PriorityQueue::peek — Returns the value at the front of the queue
  • Ds\PriorityQueue::pop — Removes and returns the value with the highest priority
  • Ds\PriorityQueue::push — Pushes values into the queue
  • Ds\PriorityQueue::toArray — Converts the queue to an array


Allocates enough memory for a required capacity

  • ≪ Ds\PriorityQueue
  • Ds\PriorityQueue::capacity ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Allocates enough memory for a required capacity

Ds\PriorityQueue::allocate

(PECL ds >= 1.0.0)

Ds\PriorityQueue::allocate — Allocates enough memory for a required capacity

説明

public Ds\PriorityQueue::allocate(int $capacity): void

Ensures that enough memory is allocated for a required capacity. This removes the need to reallocate the internal as values are added.

パラメータ

capacity

The number of values for which capacity should be allocated.

注意:

Capacity will stay the same if this value is less than or equal to the current capacity.

注意:

Capacity will always be rounded up to the nearest power of 2.

戻り値

値を返しません。

例

例1 Ds\PriorityQueue::allocate() example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue->capacity());

$queue->allocate(100);
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)
int(128)


Returns the current capacity

  • ≪ Ds\PriorityQueue::allocate
  • Ds\PriorityQueue::clear ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Returns the current capacity

Ds\PriorityQueue::capacity

(PECL ds >= 1.0.0)

Ds\PriorityQueue::capacity — Returns the current capacity

説明

public Ds\PriorityQueue::capacity(): int

Returns the current capacity.

パラメータ

この関数にはパラメータはありません。

戻り値

The current capacity.

例

例1 Ds\PriorityQueue::capacity() example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue->capacity());
?>

上の例の出力は、 たとえば以下のようになります。

int(8)


Removes all values

  • ≪ Ds\PriorityQueue::capacity
  • Ds\PriorityQueue::__construct ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Removes all values

Ds\PriorityQueue::clear

(PECL ds >= 1.0.0)

Ds\PriorityQueue::clear — Removes all values

説明

public Ds\PriorityQueue::clear(): void

Removes all values from the queue.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Ds\PriorityQueue::clear() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a", 5);
$queue->push("b", 15);
$queue->push("c", 10);

$queue->clear();
print_r($queue);
?>

上の例の出力は、 たとえば以下のようになります。

Ds\PriorityQueue Object
(
)


Creates a new instance

  • ≪ Ds\PriorityQueue::clear
  • Ds\PriorityQueue::copy ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Creates a new instance

Ds\PriorityQueue::__construct

(PECL ds >= 1.0.0)

Ds\PriorityQueue::__construct — Creates a new instance

説明

public Ds\PriorityQueue::__construct()

Creates a new instance.

例

例1 Ds\PriorityQueue::__construct() example

<?php
$queue = new \Ds\PriorityQueue();
var_dump($queue);
?>

上の例の出力は、 たとえば以下のようになります。

object(Ds\PriorityQueue)#1 (0) {
}


Returns a shallow copy of the queue

  • ≪ Ds\PriorityQueue::__construct
  • Ds\PriorityQueue::count ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Returns a shallow copy of the queue

Ds\PriorityQueue::copy

(PECL ds >= 1.0.0)

Ds\PriorityQueue::copy — Returns a shallow copy of the queue

説明

public Ds\PriorityQueue::copy(): Ds\PriorityQueue

Returns a shallow copy of the queue.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a shallow copy of the queue.

例

例1 Ds\PriorityQueue::copy() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a", 5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->copy());
?>

上の例の出力は、 たとえば以下のようになります。

Ds\PriorityQueue Object
(
    [0] => b
    [1] => c
    [2] => a
)


Returns the number of values in the queue

  • ≪ Ds\PriorityQueue::copy
  • Ds\PriorityQueue::isEmpty ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Returns the number of values in the queue

Ds\PriorityQueue::count

(PECL ds >= 1.0.0)

Ds\PriorityQueue::count — Returns the number of values in the queue

説明

See Countable::count()


Returns whether the queue is empty

  • ≪ Ds\PriorityQueue::count
  • Ds\PriorityQueue::jsonSerialize ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Returns whether the queue is empty

Ds\PriorityQueue::isEmpty

(PECL ds >= 1.0.0)

Ds\PriorityQueue::isEmpty — Returns whether the queue is empty

説明

public Ds\PriorityQueue::isEmpty(): bool

Returns whether the queue is empty.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the queue is empty, false otherwise.

例

例1 Ds\PriorityQueue::isEmpty() example

<?php
$a = new \Ds\PriorityQueue();
$b = new \Ds\PriorityQueue();

$a->push("a", 5);
$a->push("b", 15);
$a->push("c", 10);

var_dump($a->isEmpty());
var_dump($b->isEmpty());
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)


Returns a representation that can be converted to JSON

  • ≪ Ds\PriorityQueue::isEmpty
  • Ds\PriorityQueue::peek ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Returns a representation that can be converted to JSON

Ds\PriorityQueue::jsonSerialize

(PECL ds >= 1.0.0)

Ds\PriorityQueue::jsonSerialize — Returns a representation that can be converted to JSON

説明

See JsonSerializable::jsonSerialize()

注意:

You should never need to call this directly.


Returns the value at the front of the queue

  • ≪ Ds\PriorityQueue::jsonSerialize
  • Ds\PriorityQueue::pop ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Returns the value at the front of the queue

Ds\PriorityQueue::peek

(PECL ds >= 1.0.0)

Ds\PriorityQueue::peek — Returns the value at the front of the queue

説明

public Ds\PriorityQueue::peek(): mixed

Returns the value at the front of the queue, but does not remove it.

パラメータ

この関数にはパラメータはありません。

戻り値

The value at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\PriorityQueue::peek() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a", 5);
$queue->push("b", 15);
$queue->push("c", 10);

var_dump($queue->peek());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"


Removes and returns the value with the highest priority

  • ≪ Ds\PriorityQueue::peek
  • Ds\PriorityQueue::push ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Removes and returns the value with the highest priority

Ds\PriorityQueue::pop

(PECL ds >= 1.0.0)

Ds\PriorityQueue::pop — Removes and returns the value with the highest priority

説明

public Ds\PriorityQueue::pop(): mixed

Removes and returns the value at the front of the queue, ie. the value with the highest priority.

注意:

Values with equal priority fall back to FIFO (first in first out).

パラメータ

この関数にはパラメータはありません。

戻り値

The removed value which was at the front of the queue.

エラー / 例外

UnderflowException if empty.

例

例1 Ds\PriorityQueue::pop() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a", 5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->pop());
print_r($queue->pop());
print_r($queue->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "a"
string(1) "b"
string(1) "c"


Pushes values into the queue

  • ≪ Ds\PriorityQueue::pop
  • Ds\PriorityQueue::toArray ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Pushes values into the queue

Ds\PriorityQueue::push

(PECL ds >= 1.0.0)

Ds\PriorityQueue::push — Pushes values into the queue

説明

public Ds\PriorityQueue::push(mixed $value, int $priority): void

Pushes a value with a given priority into the queue.

パラメータ

value

The value to push into the queue.

priority

The priority associated with the value.

戻り値

値を返しません。

例

例1 Ds\PriorityQueue::push() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a", 5);
$queue->push("b", 15);
$queue->push("c", 10);

print_r($queue->pop());
print_r($queue->pop());
print_r($queue->pop());
?>

上の例の出力は、 たとえば以下のようになります。

string(1) "b"
string(1) "c"
string(1) "a"


Converts the queue to an array

  • ≪ Ds\PriorityQueue::push
  • var_representation ≫
  • PHP Manual
  • Ds\PriorityQueue
  • Converts the queue to an array

Ds\PriorityQueue::toArray

(PECL ds >= 1.0.0)

Ds\PriorityQueue::toArray — Converts the queue to an array

説明

public Ds\PriorityQueue::toArray(): array

Converts the queue to an array.

注意:

This method is not destructive.

注意:

Casting to an array is not supported yet.

パラメータ

この関数にはパラメータはありません。

戻り値

An array containing all the values in the same order as the queue.

例

例1 Ds\PriorityQueue::toArray() example

<?php
$queue = new \Ds\PriorityQueue();

$queue->push("a", 5);
$queue->push("b", 15);
$queue->push("c", 10);

var_dump($queue->toArray());
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(1) "b"
  [1]=>
  string(1) "c"
  [2]=>
  string(1) "a"
}


var_representation

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
  • var_representation 関数
    • var_representation — Returns a short, readable, parsable string representation of a variable


はじめに

The var_representation extension provides a compact alternative to var_export() that properly escapes control characters.


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • var_representation
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/var_representation.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

VAR_REPRESENTATION_SINGLE_LINE (int)
var_representation() flag indicating that newlines should not be used for whitespace in variable representations.
VAR_REPRESENTATION_UNESCAPED (int)
var_representation() flag indicating that strings should be encoded as single quoted strings with unescaped control characters.


var_representation 関数

目次

  • var_representation — Returns a short, readable, parsable string representation of a variable


Returns a short, readable, parsable string representation of a variable

  • ≪ var_representation 関数
  • その他のサービス ≫
  • PHP Manual
  • var_representation 関数
  • Returns a short, readable, parsable string representation of a variable

var_representation

(PECL var_representation >= 0.1.0)

var_representation — Returns a short, readable, parsable string representation of a variable

説明

var_representation(mixed $value, int $flags = 0): string

var_representation() (from the var_representation PECL) returns a string with structured information about the given variable. It is similar to var_export() with differences in indentation, string escaping, and array representations.

パラメータ

value

The variable to generate a representation of.

flags

Bitmask consisting of VAR_REPRESENTATION_SINGLE_LINE, VAR_REPRESENTATION_UNESCAPED. The behaviour of these constants is described on the var_representation constants page.

戻り値

Returns the variable representation.

例

例1 var_representation() Examples

<?php
$a = [1, 2, ['key' => 'value']];
echo var_representation($a), "\n";
echo var_representation($a, VAR_REPRESENTATION_SINGLE_LINE), "\n";
?>

上の例の出力は以下となります。

[
  1,
  2,
  [
    'key' => 'value',
  ],
]
[1, 2, ['key' => 'value']]

例2 Escaping control characters

<?php
echo var_representation("Content-Length: 123\r\n");

上の例の出力は以下となります。

"Content-Length: 123\r\n"

例3 Exporting stdClass

<?php
$person = new stdClass;
$person->name = 'ElePHPant ElePHPantsdotter';
$person->website = 'https://php.net/elephpant.php';

echo var_representation($person);

上の例の出力は以下となります。

(object) [
  'name' => 'ElePHPant ElePHPantsdotter',
  'website' => 'https://php.net/elephpant.php',
]

例4 Exporting classes

<?php
class A { public $var; }
$a = new A;
$a->var = 5;
echo var_representation($a);
?>

上の例の出力は以下となります。

\A::__set_state([
  'var' => 5,
])

例5 Using __set_state()

<?php
class A
{
public $var1;
public $var2;

public static function __set_state($an_array)
{
$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_representation($a) . ';'); // $b = \A::__set_state([
// 'var1' => 5,
// 'var2' => 'foo',
// ]);
var_dump($b);
?>

上の例の出力は以下となります。

object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

参考

  • var_export() - 変数の文字列表現を出力または返す


その他のサービス

  • cURL — Client URL Library
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • cURL 関数
    • CurlHandle — CurlHandle クラス
    • CurlMultiHandle — CurlMultiHandle クラス
    • CurlShareHandle — CurlShareHandle クラス
    • CURLFile — CURLFile クラス
    • CURLStringFile — CURLStringFile クラス
  • Event
    • はじめに
    • インストール/設定
    • 例
    • Event flags
    • About event persistence
    • Event callbacks
    • Constructing signal events
    • Event — The Event class
    • EventBase — The EventBase class
    • EventBuffer — The EventBuffer class
    • EventBufferEvent — The EventBufferEvent class
    • About buffer event callbacks
    • EventConfig — The EventConfig class
    • EventDnsBase — The EventDnsBase class
    • EventHttp — The EventHttp class
    • EventHttpConnection — The EventHttpConnection class
    • EventHttpRequest — The EventHttpRequest class
    • EventListener — The EventListener class
    • EventSslContext — The EventSslContext class
    • EventUtil — The EventUtil class
    • EventException — The EventException class
  • FTP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • FTP 関数
    • FTP\Connection — FTP\Connection クラス
  • Gearman
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • GearmanClient — The GearmanClient class
    • GearmanJob — The GearmanJob class
    • GearmanTask — The GearmanTask class
    • GearmanWorker — The GearmanWorker class
    • GearmanException — The GearmanException class
  • LDAP — Lightweight Directory Access Protocol
    • はじめに
    • インストール/設定
    • 定義済み定数
    • PHP LDAP コールの使用法
    • LDAP コントロール
    • 例
    • LDAP 関数
    • LDAP\Connection — LDAP\Connection クラス
    • LDAP\Result — LDAP\Result クラス
    • LDAP\ResultEntry — LDAP\ResultEntry クラス
  • Memcache
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Memcache — Memcache クラス
    • Memcache 関数
  • Memcached
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 有効期限
    • コールバック
    • セッションのサポート
    • Memcached — Memcached クラス
    • MemcachedException — MemcachedException クラス
  • mqseries
    • はじめに
    • インストール/設定
    • 定義済み定数
    • mqseries 関数
  • ネットワーク
    • はじめに
    • インストール/設定
    • 定義済み定数
    • ネットワーク 関数
  • RRD — RRDtool
    • はじめに
    • インストール/設定
    • 例
    • RRD 関数
    • RRDCreator — RRDCreator クラス
    • RRDGraph — RRDGraph クラス
    • RRDUpdater — RRDUpdater クラス
  • ScoutAPM
    • はじめに
    • インストール/設定
    • Scoutapm 関数
  • SNMP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SNMP 関数
    • SNMP — SNMP クラス
    • SNMPException — SNMPException クラス
  • ソケット
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • ソケットのエラー
    • ソケット 関数
    • Socket — Socket クラス
    • AddressInfo — AddressInfo クラス
  • SSH2 — Secure Shell2
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SSH2 関数
  • Stomp — Stomp Client
    • はじめに
    • インストール/設定
    • 例
    • Stomp 関数
    • Stomp — The Stomp class
    • StompFrame — The StompFrame class
    • StompException — The StompException class
  • SVM — サポートベクターマシン
    • はじめに
    • インストール/設定
    • 例
    • SVM — The SVM class
    • SVMModel — SVMModel クラス
  • SVN — Subversion
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SVN 関数
  • TCP — TCP ラッパー
    • はじめに
    • インストール/設定
    • TCP 関数
  • Varnish
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • VarnishAdmin — VarnishAdmin クラス
    • VarnishStat — VarnishStat クラス
    • VarnishLog — VarnishLog クラス
  • YAZ
    • はじめに
    • インストール/設定
    • 例
    • YAZ 関数
  • 0MQ messaging — ZMQ
    • はじめに
    • インストール/設定
    • ZMQ — The ZMQ class
    • ZMQContext — The ZMQContext class
    • ZMQSocket — The ZMQSocket class
    • ZMQPoll — The ZMQPoll class
    • ZMQDevice — The ZMQDevice class
  • ZooKeeper
    • はじめに
    • インストール/設定
    • ZooKeeper 関数
    • Zookeeper — The Zookeeper class
    • ZookeeperConfig — The ZookeeperConfig class
    • ZookeeperException — The ZookeeperException class
    • ZookeeperAuthenticationException — The ZookeeperAuthenticationException class
    • ZookeeperConnectionException — The ZookeeperConnectionException class
    • ZookeeperMarshallingException — The ZookeeperMarshallingException class
    • ZookeeperNoNodeException — The ZookeeperNoNodeException class
    • ZookeeperOperationTimeoutException — The ZookeeperOperationTimeoutException class
    • ZookeeperSessionException — The ZookeeperSessionException class


Client URL Library

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な curl の使用法
  • cURL 関数
    • curl_close — cURL セッションを閉じる
    • curl_copy_handle — cURL ハンドルを、その設定も含めてコピーする
    • curl_errno — 直近のエラー番号を返す
    • curl_error — 現在のセッションに関する直近のエラー文字列を返す
    • curl_escape — 指定した文字列を URL エンコードする
    • curl_exec — cURL セッションを実行する
    • curl_getinfo — 指定した伝送に関する情報を得る
    • curl_init — cURL セッションを初期化する
    • curl_multi_add_handle — cURL マルチハンドルに、通常の cURL ハンドルを追加する
    • curl_multi_close — cURL ハンドルのセットを閉じる
    • curl_multi_errno — 直近のマルチハンドルに対するエラー番号を返す
    • curl_multi_exec — 現在の cURL ハンドルから、サブ接続を実行する
    • curl_multi_getcontent — CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す
    • curl_multi_info_read — 現在の転送についての情報を表示する
    • curl_multi_init — 新規 cURL マルチハンドルを返す
    • curl_multi_remove_handle — cURL ハンドルのセットからマルチハンドルを削除する
    • curl_multi_select — curl_multi 接続のアクティビティを待つ
    • curl_multi_setopt — cURL マルチハンドル用のオプションを設定する
    • curl_multi_strerror — エラーの内容を表す文字列を返す
    • curl_pause — 接続の中断と再開をする
    • curl_reset — libcurl セッションハンドルのすべてのオプションをリセットする
    • curl_setopt — cURL 転送用オプションを設定する
    • curl_setopt_array — CURL 転送用の複数のオプションを設定する
    • curl_share_close — cURL 共有ハンドルを閉じる
    • curl_share_errno — 直近の共有ハンドルに対するエラー番号を返す
    • curl_share_init — curl 共有ハンドルを初期化する
    • curl_share_setopt — cURL 共有ハンドルのオプションを設定する
    • curl_share_strerror — 与えられたエラーコードを説明する文字列を返す
    • curl_strerror — エラーコードの説明を返す
    • curl_unescape — URL エンコードされた文字列をデコードする
    • curl_upkeep — 接続を維持するためのチェックを行う
    • curl_version — cURL のバージョンを返す
  • CurlHandle — CurlHandle クラス
  • CurlMultiHandle — CurlMultiHandle クラス
  • CurlShareHandle — CurlShareHandle クラス
  • CURLFile — CURLFile クラス
    • CURLFile::__construct — CURLFile オブジェクトを作る
    • CURLFile::getFilename — ファイル名を取得する
    • CURLFile::getMimeType — MIME タイプを取得する
    • CURLFile::getPostFilename — POST 用のファイル名を取得する
    • CURLFile::setMimeType — MIME タイプを設定する
    • CURLFile::setPostFilename — POST 用のファイル名を設定する
  • CURLStringFile — CURLStringFile クラス
    • CURLStringFile::__construct — CURLStringFile オブジェクトを作る


はじめに

PHP は、Daniel Stenbergにより開発されたライブラリlibcurl をサポートします。 このライブラリにより、多くの異なったプロトコルで様々なサーバーと接続し、 通信することが可能になります。libcurl は現在 http, https, ftp, gopher, telnet, dict, file, ldap プロトコルをサポートしてします。libcurl は HTTPS 認証、HTTP POST、HTTP PUT、FTP アップロード(これはPHPのftp拡張モジュールでも実行可能です)、 HTTPフォームによるアップロード、プロキシ、クッキー、 ユーザー名+パスワードによる認証もサポートします。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • cURL
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

PHP の cURL 関数を使用するためには、» libcurl パッケージをインストールしておく必要があります。 libcurl 7.10.5 以降が必要です。 PHP 7.3.0 以降では、7.15.5 以降が必要です。 PHP 8.0.0 以降では、7.29.0 以降が必要です。


インストール手順

PHP の cURL サポート機能を使用するには、--with-curl[=DIR] を付けて PHP をコンパイル しておく必要があります。ただし、DIR は、ディレクトリ lib および include を有するディレクトリの場所となります。 ディレクトリ include には、curl という名前のフォルダがある 必要があり、そのフォルダにはファイル easy.h および curl.h がある必要が あります。libcurl.a という名前のファイルがディレクトリ lib にある必要があります。

注意: Win32 ユーザーへの注意
このモジュールを Windows 環境で使用可能とするには、 libeay32.dll および ssleay32.dll、 もしくは OpenSSL 1.1 以降では libcrypto-*.dll および libssl-*.dll が PATH の通った場所に存在する必要があります。 また、libssh2.dll も PATH の通った場所になければなりません。 cURL のサイトにある libcurl.dll は不要です。


実行時設定

php.ini の設定により動作が変化します。

cURL 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
curl.cainfo | NULL | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

curl.cainfo string

CURLOPT_CAINFO オプションのデフォルト値。 絶対パスで指定する必要があります。


リソース型

PHP 8.0.0 より前のバージョンでは、 この拡張モジュールは3つのリソース型を定義していました。 cURL ハンドル、cURL マルチハンドル、cURL 共有ハンドルの3つです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Descriptions and uses for these constants are described within the curl_setopt(), curl_multi_setopt() and curl_getinfo() documentation.

CURLFTP_CREATE_DIR (int)
Available as of PHP 7.0.7 and cURL 7.19.3
CURLFTP_CREATE_DIR_NONE (int)
Available as of PHP 7.0.7 and cURL 7.19.3
CURLFTP_CREATE_DIR_RETRY (int)
Available as of PHP 7.0.7 and cURL 7.19.3
CURLFTPSSL_TRY (int)
CURLFTPSSL_ALL (int)
CURLFTPSSL_CONTROL (int)
CURLFTPSSL_NONE (int)
CURLFTPMETHOD_DEFAULT (int)
Available as of PHP 8.2.0 and cURL 7.15.3.
CURLALTSVC_H1 (int)
Available as of PHP 8.2.0 and cURL 7.64.1.
CURLALTSVC_H2 (int)
Available as of PHP 8.2.0 and cURL 7.64.1.
CURLALTSVC_H3 (int)
Available as of PHP 8.2.0 and cURL 7.64.1.
CURLALTSVC_READONLYFILE (int)
Available as of PHP 8.2.0 and cURL 7.64.1.
CURL_SSLVERSION_DEFAULT (int)
CURL_SSLVERSION_TLSv1 (int)
CURL_SSLVERSION_SSLv2 (int)
CURL_SSLVERSION_SSLv3 (int)
CURL_SSLVERSION_TLSv1_0 (int)
CURL_SSLVERSION_TLSv1_1 (int)
CURL_SSLVERSION_TLSv1_2 (int)
CURL_SSLVERSION_TLSv1_3 (int)
Available as of PHP 7.3.0 and cURL 7.52.0
CURLHSTS_ENABLE (int)
Available as of PHP 8.2.0 and cURL 7.74.0
CURLHSTS_READONLYFILE (int)
Available as of PHP 8.2.0 and cURL 7.74.0
CURLAUTH_BASIC (int)
CURLAUTH_DIGEST (int)
CURLAUTH_GSSNEGOTIATE (int)
CURLAUTH_NEGOTIATE (int)
Available as of PHP 7.0.7 and cURL 7.38.0.
CURLAUTH_NTLM (int)
CURLAUTH_NTLM_WB (int)
Available as of PHP 7.0.7 and cURL 7.22.0
CURLAUTH_ANY (int)
CURLAUTH_ANYSAFE (int)
CURLAUTH_AWS_SIGV4 (int)
Available as of PHP 8.2.0 and cURL 7.75.0.
CURLPX_BAD_ADDRESS_TYPE (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_BAD_VERSION (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_CLOSED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_GSSAPI (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_GSSAPI_PERMSG (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_GSSAPI_PROTECTION (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_IDENTD_DIFFER (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_IDENTD (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_LONG_HOSTNAME (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_LONG_PASSWD (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_LONG_USER (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_NO_AUTH (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_OK (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_RECV_ADDRESS (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_RECV_AUTH (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_RECV_CONNECT (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_RECV_REQACK (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_COMMAND_NOT_SUPPORTED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_CONNECTION_REFUSED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_GENERAL_SERVER_FAILURE (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_HOST_UNREACHABLE (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_NETWORK_UNREACHABLE (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_NOT_ALLOWED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_TTL_EXPIRED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REPLY_UNASSIGNED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_REQUEST_FAILED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_RESOLVE_HOST (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_SEND_AUTH (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_SEND_CONNECT (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_SEND_REQUEST (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_UNKNOWN_FAIL (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_UNKNOWN_MODE (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURLPX_USER_REJECTED (int)
Available as of PHP 8.2.0 and cURL 7.73.0
CURL_PUSH_OK (int)
Available as of PHP 7.1.0 and cURL 7.44.0
CURL_PUSH_DENY (int)
Available as of PHP 7.1.0 and cURL 7.44.0
CURL_REDIR_POST_301 (int)
Available as of PHP 7.0.7 and cURL 7.18.2
CURL_REDIR_POST_302 (int)
Available as of PHP 7.0.7 and cURL 7.18.2
CURL_REDIR_POST_303 (int)
Available as of PHP 7.0.7 and cURL 7.25.1
CURL_REDIR_POST_ALL (int)
Available as of PHP 7.0.7 and cURL 7.18.2
CURL_TIMECOND_NONE (int)
CURL_TIMECOND_IFMODSINCE (int)
CURL_TIMECOND_IFUNMODSINCE (int)
CURL_TIMECOND_LASTMOD (int)
CURL_VERSION_ALTSVC (int)
Available as of PHP 7.3.6 and cURL 7.64.1
CURL_VERSION_ASYNCHDNS (int)
Asynchronous DNS resolves. Available as of PHP 7.3.0 and cURL 7.10.7
CURL_VERSION_BROTLI (int)
Available as of PHP 7.3.0 and cURL 7.57.0
CURL_VERSION_CONV (int)
Character conversions supported. Available as of PHP 7.3.0 and cURL 7.15.4
CURL_VERSION_CURLDEBUG (int)
Debug memory tracking supported. Available as of PHP 7.3.6 and cURL 7.19.6
CURL_VERSION_DEBUG (int)
Built with debug capabilities. Available as of PHP 7.3.0 and cURL 7.10.6
CURL_VERSION_GSASL (int)
Available as of PHP 8.2.0 and cURL 7.76.0
CURL_VERSION_GSSAPI (int)
Built against a GSS-API library. Available as of PHP 7.3.0 and cURL 7.38.0
CURL_VERSION_GSSNEGOTIATE (int)
Negotiate auth is supported. Available as of PHP 7.3.0 and cURL 7.10.6 (deprecated as of 7.38.0)
CURL_VERSION_HSTS (int)
Available as of PHP 8.2.0 and cURL 7.74.0
CURL_VERSION_IDN (int)
Internationized Domain Names are supported. Available as of PHP 7.3.0 and cURL 7.12.0
CURL_VERSION_MULTI_SSL (int)
Available as of PHP 7.3.0 and cURL 7.56.0
CURL_VERSION_NTLM (int)
NTLM auth is supported. Available as of PHP 7.3.0 and cURL 7.10.6
CURL_VERSION_NTLM_WB (int)
NTLM delegation to winbind helper is supported. Available as of PHP 7.3.0 and cURL 7.22.0
CURL_VERSION_IPV6 (int)
IPv6-enabled.
CURL_VERSION_KERBEROS4 (int)
Kerberos V4 auth is supported.
CURL_VERSION_KERBEROS5 (int)
Kerberos V5 auth is supported. Available as of PHP 7.0.7 and cURL 7.40.0
CURL_VERSION_HTTP2 (int)
HTTP2 support built-in. Available as of cURL 7.33.0
CURL_VERSION_HTTP3 (int)
Available as of PHP 8.2.0 and cURL 7.66.0
CURL_VERSION_LARGEFILE (int)
Supports files larger than 2GB. Available as of cURL 7.33.0
CURL_VERSION_PSL (int)
Mozilla's Public Suffix List, used for cookie domain verification. Available as of PHP 7.3.6 and cURL 7.47.0
CURL_VERSION_SPNEGO (int)
SPNEGO auth is supported. Available as of PHP 7.3.0 and cURL 7.10.8
CURL_VERSION_SSPI (int)
Built against Windows SSPI. Available as of PHP 7.3.0 and cURL 7.13.2
CURL_VERSION_SSL (int)
SSL options are present.
CURL_VERSION_TLSAUTH_SRP (int)
TLS-SRP auth is supported. Available as of PHP 7.3.0 and cURL 7.21.4
CURL_VERSION_UNICODE (int)
Available as of PHP 8.2.0 and cURL 7.72.0
CURL_VERSION_UNIX_SOCKETS (int)
Unix domain sockets support. Available as of PHP 7.0.7 and cURL 7.40.0
CURL_VERSION_ZSTD (int)
Available as of PHP 8.2.0 and cURL 7.72.0
CURL_VERSION_LIBZ (int)
libz features are present.
CURLVERSION_NOW (int)
CURLFTPAUTH_DEFAULT (int)
CURLFTPAUTH_SSL (int)
CURLFTPAUTH_TLS (int)
CURLPROXY_HTTP (int)
Available as of cURL 7.10.
CURLPROXY_HTTP_1_0 (int)
Available as of PHP 7.0.7 and cURL 7.19.3
CURLPROXY_SOCKS4 (int)
Available as of cURL 7.10.
CURLPROXY_SOCKS5 (int)
Available as of cURL 7.10.
CURL_NETRC_OPTIONAL (int)
CURL_NETRC_IGNORED (int)
CURL_NETRC_REQUIRED (int)
CURL_HTTP_VERSION_NONE (int)
CURL_HTTP_VERSION_1_0 (int)
CURL_HTTP_VERSION_1_1 (int)
CURL_HTTP_VERSION_2 (int)
Available as of PHP 7.0.7 and cURL 7.43.0
CURL_HTTP_VERSION_2_0 (int)
Available as of cURL 7.33.0
CURL_HTTP_VERSION_2TLS (int)
Available as of PHP 7.0.7 and cURL 7.47.0
CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE (int)
Available as of PHP 7.0.7 and cURL 7.49.0
CURLMSG_DONE (int)
CURLSSLOPT_ALLOW_BEAST (int)
Available as of cURL 7.25.0
CURLSSLOPT_NO_REVOKE (int)
Available as of PHP 7.0.7 and cURL 7.44.0
CURLSSLOPT_AUTO_CLIENT_CERT (int)
Available as of PHP 8.2.0 and cURL 7.77.0
CURLSSLOPT_NATIVE_CA (int)
Available as of PHP 8.2.0 and cURL 7.71.0
CURLSSLOPT_NO_PARTIALCHAIN (int)
Available as of PHP 8.2.0 and cURL 7.68.0
CURLSSLOPT_REVOKE_BEST_EFFORT (int)
Available as of PHP 8.2.0 and cURL 7.70.0
CURLSSH_AUTH_AGENT (int)
Available as of PHP 7.0.7 and cURL 7.28.0
CURLSSH_AUTH_ANY (int)
CURLSSH_AUTH_DEFAULT (int)
CURLSSH_AUTH_HOST (int)
CURLSSH_AUTH_KEYBOARD (int)
CURLSSH_AUTH_NONE (int)
CURLSSH_AUTH_PASSWORD (int)
CURLSSH_AUTH_PUBLICKEY (int)
CURLPIPE_NOTHING (int)
Available as of cURL 7.43.0.
CURLPIPE_HTTP1 (int)
Available as of cURL 7.43.0.
CURLPIPE_MULTIPLEX (int)
Available as of cURL 7.43.0.
CURLPROXY_SOCKS4A (int)
Available as of cURL 7.18.0.
CURLPROXY_SOCKS5_HOSTNAME (int)
Available as of cURL 7.18.0.
CURLHEADER_SEPARATE (int)
Available as of PHP 7.0.7 and cURL 7.37.0.
CURLHEADER_UNIFIED (int)
Available as of PHP 7.0.7 and cURL 7.37.0.
CURLAUTH_GSSAPI (int)
Available as of PHP 7.3.0 and cURL 7.54.1
CURL_MAX_READ_SIZE (int)
Available as of PHP 7.3.0 and cURL 7.53.0
CURLPROXY_HTTPS (int)
Available as of PHP 7.3.0 and cURL 7.52.0
CURL_SSLVERSION_MAX_DEFAULT (int)
Available as of PHP 7.3.0 and cURL 7.54.0
CURL_SSLVERSION_MAX_NONE (int)
Available as of PHP 7.3.0 and cURL 7.54.0
CURL_SSLVERSION_MAX_TLSv1_0 (int)
Available as of PHP 7.3.0 and cURL 7.54.0
CURL_SSLVERSION_MAX_TLSv1_1 (int)
Available as of PHP 7.3.0 and cURL 7.54.0
CURL_SSLVERSION_MAX_TLSv1_2 (int)
Available as of PHP 7.3.0 and cURL 7.54.0
CURL_SSLVERSION_MAX_TLSv1_3 (int)
Available as of PHP 7.3.0 and cURL 7.54.0
CURL_VERSION_HTTPS_PROXY (int)
Available as of PHP 7.3.0 and cURL 7.52.0
CURLAUTH_BEARER (int)
Available as of PHP 7.3.0 and cURL 7.61.0.
CURLSSH_AUTH_GSSAPI (int)
Available as of PHP 7.3.0 and cURL 7.58.0
CURLMIMEOPT_FORMESCAPE (int)
Available as of PHP 8.3.0 and cURL 7.81.0
CURLWS_RAW_MODE (int)
Available as of PHP 8.3.0 and cURL 7.86.0
CURLKHMATCH_OK (int)
Available as of PHP 8.3.0 and cURL 7.19.6
CURLKHMATCH_MISMATCH (int)
Available as of PHP 8.3.0 and cURL 7.19.6
CURLKHMATCH_MISSING (int)
Available as of PHP 8.3.0 and cURL 7.19.6
CURLKHMATCH_LAST (int)
Available as of PHP 8.3.0 and cURL 7.19.6
curl-setopt()
定数 説明
CURLOPT_ABSTRACT_UNIX_SOCKET (int)

Enables the use of an abstract Unix domain socket instead of establishing a TCP connection to a host and sets the path to the given string. This option shares the same semantics as CURLOPT_UNIX_SOCKET_PATH. These two options share the same storage and therefore only one of them can be set per handle. Available as of PHP 7.3.0 and cURL 7.53.0

CURLOPT_ALTSVC (int)

Pass the filename for cURL to use as the Alt-Svc cache file to read existing cache contents from and possibly also write it back to a after a transfer, unless CURLALTSVC_READONLYFILE is set via CURLOPT_ALTSVC_CTRL. Available as of PHP 8.2.0 and cURL 7.64.1.

CURLOPT_ALTSVC_CTRL (int)

Populate the bitmask with the correct set of features to instruct cURL how to handle Alt-Svc for the transfers using this handle. cURL only accepts Alt-Svc headers over HTTPS. It will also only complete a request to an alternative origin if that origin is properly hosted over HTTPS. Setting any bit will enable the alt-svc engine. The options are: CURLALTSVC_H1, CURLALTSVC_H2, CURLALTSVC_H3, and CURLALTSVC_READONLYFILE. Available as of PHP 8.2.0 and cURL 7.64.1.

CURLOPT_AUTOREFERER (int)

true to automatically set the Referer: field in requests where it follows a Location: redirect.

CURLOPT_AWS_SIGV4 (int)

Provides AWS V4 signature authentication on HTTP(S) header. This option overrides any other authentication types that have been set in CURLOPT_HTTPAUTH. This method cannot be combined with other authentication types. Available as of PHP 8.2.0 and cURL 7.75.0

CURLOPT_BINARYTRANSFER (int)

CURLOPT_BUFFERSIZE (int)

The size of the buffer to use for each read. There is no guarantee this request will be fulfilled, however. Available as of cURL 7.10.

CURLOPT_CAINFO (int)

The name of a file holding one or more certificates to verify the peer with. This only makes sense when used in combination with CURLOPT_SSL_VERIFYPEER. Might require an absolute path.

CURLOPT_CAINFO_BLOB (int)

The name of a PEM file holding one or more certificates to verify the peer with. This option overrides CURLOPT_CAINFO. Available as of PHP 8.2.0 and cURL 7.77.0

CURLOPT_CAPATH (int)

A directory that holds multiple CA certificates. Use this option alongside CURLOPT_SSL_VERIFYPEER.

CURLOPT_CA_CACHE_TIMEOUT (int)

Available as of PHP 8.3.0 and cURL 7.87.0

CURLOPT_CERTINFO (int)

true to output SSL certification information to STDERR on secure transfers. Added in cURL 7.19.1. Requires CURLOPT_VERBOSE to be on to have an effect.

CURLOPT_CONNECTTIMEOUT (int)

The number of seconds to wait while trying to connect. Use 0 to wait indefinitely.

CURLOPT_CONNECTTIMEOUT_MS (int)

The number of milliseconds to wait while trying to connect. Use 0 to wait indefinitely. If libcurl is built to use the standard system name resolver, that portion of the connect will still use full-second resolution for timeouts with a minimum timeout allowed of one second. Available as of cURL 7.16.2.

CURLOPT_CONNECT_ONLY (int)

true tells the library to perform all the required proxy authentication and connection setup, but no data transfer. This option is implemented for HTTP, SMTP and POP3. Available as of cURL 7.15.2.

CURLOPT_CONNECT_TO (int)

Connect to a specific host and port instead of the URL's host and port. Accepts an array of strings with the format HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT. Available as of PHP 7.0.7 and cURL 7.49.0

CURLOPT_COOKIE (int)

The contents of the "Cookie: " header to be used in the HTTP request. Note that multiple cookies are separated with a semicolon followed by a space (e.g., "fruit=apple; colour=red")

CURLOPT_COOKIEFILE (int)

The name of the file containing the cookie data. The cookie file can be in Netscape format, or just plain HTTP-style headers dumped into a file. If the name is an empty string, no cookies are loaded, but cookie handling is still enabled.

CURLOPT_COOKIEJAR (int)

The name of a file to save all internal cookies to when the handle's destructor is called.

警告

As of PHP 8.0.0, curl_close() is a no-op and does not destroy the handle. If cookies need to be written prior to the handle being automatically destroyed, call unset() on the handle.

CURLOPT_COOKIELIST (int)

A cookie string (i.e. a single line in Netscape/Mozilla format, or a regular HTTP-style Set-Cookie header) adds that single cookie to the internal cookie store. "ALL" erases all cookies held in memory. "SESS" erases all session cookies held in memory. "FLUSH" writes all known cookies to the file specified by CURLOPT_COOKIEJAR. "RELOAD" loads all cookies from the files specified by CURLOPT_COOKIEFILE. Available as of cURL 7.14.1

CURLOPT_COOKIESESSION (int)

true to mark this as a new cookie "session". It will force libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session. By default, libcurl always stores and loads all cookies, independent if they are session cookies or not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only.

CURLOPT_CRLF (int)

true to convert Unix newlines to CRLF newlines on transfers.

CURLOPT_CUSTOMREQUEST (int)

A custom request method to use instead of "GET" or "HEAD" when doing a HTTP request. This is useful for doing "DELETE" or other, more obscure HTTP requests. Valid values are things like "GET", "POST", "CONNECT" and so on; i.e. Do not enter a whole HTTP request line here. For instance, entering "GET /index.html HTTP/1.0\r\n\r\n" would be incorrect.

注意:

Don't do this without making sure the server supports the custom request method first.

CURLOPT_DEFAULT_PROTOCOL (int)

The default protocol to use if the URL is missing a scheme name. Available as of PHP 7.0.7 and cURL 7.45.0

CURLOPT_DISALLOW_USERNAME_IN_URL (int)

true to not allow URLs that include a username. Usernames are allowed by default (0). Available as of PHP 7.3.0 and cURL 7.61.0

CURLOPT_DNS_CACHE_TIMEOUT (int)

The number of seconds to keep DNS entries in memory. This option is set to 120 (2 minutes) by default.

CURLOPT_DNS_INTERFACE (int)

Set the name of the network interface that the DNS resolver should bind to. This must be an interface name (not an address). Available as of PHP 7.0.7 and cURL 7.33.0

CURLOPT_DNS_LOCAL_IP4 (int)

Set the local IPv4 address that the resolver should bind to. The argument should contain a single numerical IPv4 address as a string. Available as of PHP 7.0.7 and cURL 7.33.0

CURLOPT_DNS_LOCAL_IP6 (int)

Set the local IPv6 address that the resolver should bind to. The argument should contain a single numerical IPv6 address as a string. Available as of PHP 7.0.7 and cURL 7.33.0

CURLOPT_DNS_SHUFFLE_ADDRESSES (int)

true to shuffle the order of all returned addresses so that they will be used in a random order, when a name is resolved and more than one IP address is returned. This may cause IPv4 to be used before IPv6 or vice versa. Available as of PHP 7.3.0 and cURL 7.60.0

CURLOPT_DNS_USE_GLOBAL_CACHE (int)

true to use a global DNS cache. This option is not thread-safe. It is conditionally enabled by default if PHP is built for non-threaded use (CLI, FCGI, Apache2-Prefork, etc.).

CURLOPT_DOH_SSL_VERIFYHOST (int)

Verify the DNS-over-HTTPS server's SSL certificate name fields against the host name. Available as of PHP 8.2.0 and cURL 7.76.0.

CURLOPT_DOH_SSL_VERIFYPEER (int)

Verify the authenticity of the DNS-over-HTTPS server's SSL certificate. Available as of PHP 8.2.0 and cURL 7.76.0.

CURLOPT_DOH_SSL_VERIFYSTATUS (int)

Tell cURL to verify the status of the DNS-over-HTTPS server certificate using the "Certificate Status Request" TLS extension (OCSP stapling). Available as of PHP 8.2.0 and cURL 7.76.0.

CURLOPT_DOH_URL (int)

Provides the DNS-over-HTTPS URL. Available as of PHP 8.1.0 and cURL 7.62.0.

CURLOPT_EGDSOCKET (int)

Like CURLOPT_RANDOM_FILE, except a filename to an Entropy Gathering Daemon socket.

CURLOPT_ENCODING (int)

The contents of the "Accept-Encoding: " header. This enables decoding of the response. Supported encodings are "identity", "deflate", and "gzip". If an empty string, "", is set, a header containing all supported encoding types is sent. Available as of cURL 7.10.

CURLOPT_EXPECT_100_TIMEOUT_MS (int)

The timeout for Expect: 100-continue responses in milliseconds. Defaults to 1000 milliseconds. Available as of PHP 7.0.7 and cURL 7.36.0

CURLOPT_FAILONERROR (int)

true to fail verbosely if the HTTP code returned is greater than or equal to 400. The default behavior is to return the page normally, ignoring the code.

CURLOPT_FILE (int)

The file that the transfer should be written to. The default is STDOUT (the browser window).

CURLOPT_FILETIME (int)

true to attempt to retrieve the modification date of the remote document. This value can be retrieved using the CURLINFO_FILETIME option with curl_getinfo().

CURLOPT_FOLLOWLOCATION (int)

true to follow any "Location: " header that the server sends as part of the HTTP header. See also CURLOPT_MAXREDIRS. This constant is not available when open_basedir is enabled.

CURLOPT_FORBID_REUSE (int)

true to force the connection to explicitly close when it has finished processing, and not be pooled for reuse.

CURLOPT_FRESH_CONNECT (int)

true to force the use of a new connection instead of a cached one.

CURLOPT_FTPAPPEND (int)

true to append to the remote file instead of overwriting it.

CURLOPT_FTPASCII (int)

An alias of CURLOPT_TRANSFERTEXT. Use that instead.

CURLOPT_FTPLISTONLY (int)

true to only list the names of an FTP directory.

CURLOPT_FTPPORT (int)

The value which will be used to get the IP address to use for the FTP "PORT" instruction. The "PORT" instruction tells the remote server to connect to our specified IP address. The string may be a plain IP address, a hostname, a network interface name (under Unix), or just a plain '-' to use the systems default IP address.

CURLOPT_FTPSSLAUTH (int)

The FTP authentication method (when is activated): CURLFTPAUTH_SSL (try SSL first), CURLFTPAUTH_TLS (try TLS first), or CURLFTPAUTH_DEFAULT (let cURL decide). Available as of cURL 7.12.2.

CURLOPT_FTP_CREATE_MISSING_DIRS (int)

true to create missing directories when an FTP operation encounters a path that currently doesn't exist.

CURLOPT_FTP_FILEMETHOD (int)

Tell curl which method to use to reach a file on a FTP(S) server. Possible values are CURLFTPMETHOD_DEFAULT, CURLFTPMETHOD_MULTICWD, CURLFTPMETHOD_NOCWD, and CURLFTPMETHOD_SINGLECWD. Available as of cURL 7.15.1.

CURLOPT_FTP_SSL (int)

CURLOPT_FTP_USE_EPRT (int)

true to use EPRT (and LPRT) when doing active FTP downloads. Use false to disable EPRT and LPRT and use PORT only.

CURLOPT_FTP_USE_EPSV (int)

true to first try an EPSV command for FTP transfers before reverting back to PASV. Set to false to disable EPSV.

CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS (int)

Head start for ipv6 for the happy eyeballs algorithm. Happy eyeballs attempts to connect to both IPv4 and IPv6 addresses for dual-stack hosts, preferring IPv6 first for timeout milliseconds. Defaults to CURL_HET_DEFAULT, which is currently 200 milliseconds. Available as of PHP 7.3.0 and cURL 7.59.0

CURLOPT_HAPROXYPROTOCOL (int)

true to send an HAProxy PROXY protocol v1 header at the start of the connection. The default action is not to send this header. Available as of PHP 7.3.0 and cURL 7.60.0

CURLOPT_HEADER (int)

true to include the header in the output.

CURLOPT_HEADERFUNCTION (int)

A callback accepting two parameters. The first is the cURL resource, the second is a string with the header data to be written. The header data must be written by this callback. Return the number of bytes written.

CURLOPT_HEADEROPT (int)

Possible values are CURLHEADER_UNIFIED or CURLHEADER_SEPARATE. Defaults to CURLHEADER_SEPARATE as of cURL 7.42.1, and CURLHEADER_UNIFIED before. Available as of PHP 7.0.7 and cURL 7.37.0

CURLOPT_HSTS (int)

HSTS (HTTP Strict Transport Security) cache file name. Available as of PHP 8.2.0 and cURL 7.74.0

CURLOPT_HSTS_CTRL (int)

Controls HSTS (HTTP Strict Transport Security) behavior. Populate the bitmask with the correct set of features to instruct cURL how to handle HSTS for the transfers using this handle. CURLHSTS_ENABLE enables the in-memory HSTS cache. If the HSTS cache file is defined, set CURLHSTS_READONLYFILE to make the file read-only. Available as of PHP 8.2.0 and cURL 7.74.0

CURLOPT_HTTP09_ALLOWED (int)

Whether to allow HTTP/0.9 responses. Defaults to false as of libcurl 7.66.0; formerly it defaulted to true. Available as of PHP 7.3.15 and 7.4.3, respectively, and cURL 7.64.0

CURLOPT_HTTP200ALIASES (int)

An array of HTTP 200 responses that will be treated as valid responses and not as errors. Available as of cURL 7.10.3.

CURLOPT_HTTPAUTH (int)

The HTTP authentication method(s) to use. The options are: CURLAUTH_BASIC, CURLAUTH_DIGEST, CURLAUTH_GSSNEGOTIATE, CURLAUTH_NTLM, CURLAUTH_AWS_SIGV4, CURLAUTH_ANY, and CURLAUTH_ANYSAFE. The bitwise | (or) operator can be used to combine more than one method. If this is done, cURL will poll the server to see what methods it supports and pick the best one. CURLAUTH_ANY sets all bits. cURL will automatically select the one it finds most secure. CURLAUTH_ANYSAFE sets all bits except CURLAUTH_BASIC. cURL will automatically select the one it finds most secure.

CURLOPT_HTTPGET (int)

true to reset the HTTP request method to GET. Since GET is the default, this is only necessary if the request method has been changed.

CURLOPT_HTTPHEADER (int)

An array of HTTP header fields to set, in the format array('Content-type: text/plain', 'Content-length: 100')

CURLOPT_HTTPPROXYTUNNEL (int)

true to tunnel through a given HTTP proxy.

CURLOPT_HTTP_CONTENT_DECODING (int)

false to get the raw HTTP response body. Available as of cURL 7.16.2.

CURLOPT_HTTP_VERSION (int)

CURL_HTTP_VERSION_NONE (default, lets CURL decide which version to use), CURL_HTTP_VERSION_1_0 (forces HTTP/1.0), CURL_HTTP_VERSION_1_1 (forces HTTP/1.1), CURL_HTTP_VERSION_2_0 (attempts HTTP 2), CURL_HTTP_VERSION_2 (alias of CURL_HTTP_VERSION_2_0), CURL_HTTP_VERSION_2TLS (attempts HTTP 2 over TLS (HTTPS) only) or CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE (issues non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade).

CURLOPT_INFILE (int)

The file that the transfer should be read from when uploading.

CURLOPT_INFILESIZE (int)

The expected size, in bytes, of the file when uploading a file to a remote site. Note that using this option will not stop libcurl from sending more data, as exactly what is sent depends on CURLOPT_READFUNCTION.

CURLOPT_INTERFACE (int)

The name of the outgoing network interface to use. This can be an interface name, an IP address or a host name.

CURLOPT_IPRESOLVE (int)

Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that resolve addresses using more than one version of IP, possible values are CURL_IPRESOLVE_WHATEVER, CURL_IPRESOLVE_V4, CURL_IPRESOLVE_V6, by default CURL_IPRESOLVE_WHATEVER. Available as of cURL 7.10.8.

CURLOPT_ISSUERCERT_BLOB (int)

Issuer SSL certificate from memory blob. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_KEEP_SENDING_ON_ERROR (int)

true to keep sending the request body if the HTTP code returned is equal to or larger than 300. The default action would be to stop sending and close the stream or connection. Suitable for manual NTLM authentication. Most applications do not need this option. Available as of PHP 7.3.0 and cURL 7.51.0

CURLOPT_KEYPASSWD (int)

The password required to use the CURLOPT_SSLKEY or CURLOPT_SSH_PRIVATE_KEYFILE private key. Available as of cURL 7.16.1.

CURLOPT_KRB4LEVEL (int)

The KRB4 (Kerberos 4) security level. Any of the following values (in order from least to most powerful) are valid: "clear", "safe", "confidential", "private".. If the string does not match one of these, "private" is used. Setting this option to null will disable KRB4 security. Currently KRB4 security only works with FTP transactions.

CURLOPT_LOGIN_OPTIONS (int)

Can be used to set protocol specific login options, such as the preferred authentication mechanism via "AUTH=NTLM" or "AUTH=*", and should be used in conjunction with the CURLOPT_USERNAME option. Available as of PHP 7.0.7 and cURL 7.34.0

CURLOPT_LOW_SPEED_LIMIT (int)

The transfer speed, in bytes per second, that the transfer should be below during the count of CURLOPT_LOW_SPEED_TIME seconds before PHP considers the transfer too slow and aborts.

CURLOPT_LOW_SPEED_TIME (int)

The number of seconds the transfer speed should be below CURLOPT_LOW_SPEED_LIMIT before PHP considers the transfer too slow and aborts.

CURLOPT_MAIL_RCPT_ALLLOWFAILS (int)

Available as of PHP 8.2.0 and cURL 7.69.0

CURLOPT_MAXAGE_CONN (int)

The maximum idle time allowed for an existing connection to be considered for reuse. Default maximum age is set to 118 seconds. Available as of PHP 8.2.0 and cURL 7.65.0

CURLOPT_MAXCONNECTS (int)

The maximum amount of persistent connections that are allowed. When the limit is reached, the oldest one in the cache is closed to prevent increasing the number of open connections.

CURLOPT_MAXFILESIZE_LARGE (int)

The maximum file size in bytes allowed to download. If the file requested is found larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. Available as of PHP 8.2.0 and cURL 7.11.0

CURLOPT_MAXLIFETIME_CONN (int)

The maximum time in seconds, since the creation of the connection, that is allowed for an existing connection to have for it to be considered for reuse. If a connection is found in the cache that is older than this value, it will instead be closed once any in-progress transfers are complete. Default is 0 seconds, meaning the option is disabled and all connections are eligible for reuse. Available as of PHP 8.2.0 and cURL 7.80.0

CURLOPT_MAXREDIRS (int)

The maximum amount of HTTP redirections to follow. Use this option alongside CURLOPT_FOLLOWLOCATION. Default value of 20 is set to prevent infinite redirects. Setting to -1 allows inifinite redirects, and 0 refuses all redirects.

CURLOPT_MAX_RECV_SPEED_LARGE (int)

If a download exceeds this speed (counted in bytes per second) on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value. Defaults to unlimited speed. Available as of cURL 7.15.5

CURLOPT_MAX_SEND_SPEED_LARGE (int)

If an upload exceeds this speed (counted in bytes per second) on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value. Defaults to unlimited speed. Available as of cURL 7.15.5

CURLOPT_MIME_OPTIONS (int)

Available as of PHP 8.3.0 and cURL 7.81.0

CURLOPT_MUTE (int)

true to be completely silent with regards to the cURL functions. Removed as of cURL 7.15.5; use CURLOPT_RETURNTRANSFER instead.

CURLOPT_NETRC (int)

true to scan the ~/.netrc file to find a username and password for the remote site that a connection is being established with.

CURLOPT_NOBODY (int)

true to exclude the body from the output. Request method is then set to HEAD. Changing this to false does not change it to GET.

CURLOPT_NOPROGRESS (int)

true to disable the progress meter for cURL transfers.

注意:

PHP automatically sets this option to true, this should only be changed for debugging purposes.

CURLOPT_NOSIGNAL (int)

true to ignore any cURL function that causes a signal to be sent to the PHP process. This is turned on by default in multi-threaded SAPIs so timeout options can still be used. Available as of cURL 7.10.

CURLOPT_PASSWDFUNCTION (int)

A callback accepting three parameters. The first is the cURL resource, the second is a string containing a password prompt, and the third is the maximum password length. Return the string containing the password. Removed as of PHP 7.3.0.

CURLOPT_PASSWORD (int)

The password to use in authentication. Available as of cURL 7.19.1.

CURLOPT_PATH_AS_IS (int)

true to not handle dot dot sequences. Available as of PHP 7.0.7 and cURL 7.42.0

CURLOPT_PINNEDPUBLICKEY (int)

Set the pinned public key. The string can be the file name of your pinned public key. The file format expected is "PEM" or "DER". The string can also be any number of base64 encoded sha256 hashes preceded by "sha256//" and separated by ";". Available as of PHP 7.0.7 and cURL 7.39.0

CURLOPT_PIPEWAIT (int)

true to wait for pipelining/multiplexing. Available as of PHP 7.0.7 and cURL 7.43.0

CURLOPT_PORT (int)

An alternative port number to connect to.

CURLOPT_POST (int)

true to do a regular HTTP POST. This POST is the normal application/x-www-form-urlencoded kind, most commonly used by HTML forms.

CURLOPT_POSTFIELDS (int)

The full data to post in a HTTP "POST" operation. This parameter can either be passed as a urlencoded string like 'para1=val1&para2=val2&...' or as an array with the field name as key and field data as value. If value is an array, the Content-Type header will be set to multipart/form-data. Files can be sent using CURLFile or CURLStringFile, in which case value must be an array.

CURLOPT_POSTQUOTE (int)

An array of FTP commands to execute on the server after the FTP request has been performed.

CURLOPT_POSTREDIR (int)

A bitmask of 1 (301 Moved Permanently), 2 (302 Found) and 4 (303 See Other) if the HTTP POST method should be maintained when CURLOPT_FOLLOWLOCATION is set and a specific type of redirect occurs. Available as of cURL 7.19.1.

CURLOPT_PRE_PROXY (int)

Set a string holding the host name or dotted numerical IP address to be used as the preproxy that curl connects to before it connects to the HTTP(S) proxy specified in the CURLOPT_PROXY option for the upcoming request. The preproxy can only be a SOCKS proxy and it should be prefixed with [scheme]:// to specify which kind of socks is used. A numerical IPv6 address must be written within [brackets]. Setting the preproxy to an empty string explicitly disables the use of a preproxy. To specify port number in this string, append :[port] to the end of the host name. The proxy's port number may optionally be specified with the separate option CURLOPT_PROXYPORT. Defaults to using port 1080 for proxies if a port is not specified. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PRIVATE (int)

Any data that should be associated with this cURL handle. This data can subsequently be retrieved with the CURLINFO_PRIVATE option of curl_getinfo(). cURL does nothing with this data. When using a cURL multi handle, this private data is typically a unique key to identify a standard cURL handle. Available as of cURL 7.10.3.

CURLOPT_PROGRESSFUNCTION (int)

A callback accepting five parameters. The first is the cURL resource, the second is the total number of bytes expected to be downloaded in this transfer, the third is the number of bytes downloaded so far, the fourth is the total number of bytes expected to be uploaded in this transfer, and the fifth is the number of bytes uploaded so far.

注意:

The callback is only called when the CURLOPT_NOPROGRESS option is set to false.

Return a non-zero value to abort the transfer. In which case, the transfer will set a CURLE_ABORTED_BY_CALLBACK error.

CURLOPT_PROTOCOLS (int)

Bitmask of CURLPROTO_* values. If used, this bitmask limits what protocols libcurl may use in the transfer. This allows you to have a libcurl built to support a wide range of protocols but still limit specific transfers to only be allowed to use a subset of them. By default libcurl will accept all protocols it supports. See also CURLOPT_REDIR_PROTOCOLS. Valid protocol options are: CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_FTP, CURLPROTO_FTPS, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_TELNET, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_TFTP, CURLPROTO_MQTT, CURLPROTO_ALL Available as of cURL 7.19.4.

CURLOPT_PROTOCOLS_STR (int)

Available as of PHP 8.3.0 and cURL 7.85.0

CURLOPT_PROXY (int)

The HTTP proxy to tunnel requests through.

CURLOPT_PROXYAUTH (int)

The HTTP authentication method(s) to use for the proxy connection. Use the same bitmasks as described in CURLOPT_HTTPAUTH. For proxy authentication, only CURLAUTH_BASIC and CURLAUTH_NTLM are currently supported. Available as of cURL 7.10.7.

CURLOPT_PROXYHEADER (int)

An array of custom HTTP headers to pass to proxies. Available as of PHP 7.0.7 and cURL 7.37.0

CURLOPT_PROXYPORT (int)

The port number of the proxy to connect to. This port number can also be set in CURLOPT_PROXY.

CURLOPT_PROXYTYPE (int)

Either CURLPROXY_HTTP (default), CURLPROXY_SOCKS4, CURLPROXY_SOCKS5, CURLPROXY_SOCKS4A or CURLPROXY_SOCKS5_HOSTNAME. Available as of cURL 7.10.

CURLOPT_PROXYUSERPWD (int)

A username and password formatted as "[username]:[password]" to use for the connection to the proxy.

CURLOPT_PROXY_CAINFO (int)

The path to proxy Certificate Authority (CA) bundle. Set the path as a string naming a file holding one or more certificates to verify the HTTPS proxy with. This option is for connecting to an HTTPS proxy, not an HTTPS server. Defaults set to the system path where libcurl's cacert bundle is assumed to be stored. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_CAINFO_BLOB (int)

The name of a PEM file holding one or more certificates to verify the HTTPS proxy with. This option is for connecting to an HTTPS proxy, not an HTTPS server. Defaults set to the system path where libcurl's cacert bundle is assumed to be stored. Available as of PHP 8.2.0 and cURL 7.77.0

CURLOPT_PROXY_CAPATH (int)

The directory holding multiple CA certificates to verify the HTTPS proxy with. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_CRLFILE (int)

Set the file name with the concatenation of CRL (Certificate Revocation List) in PEM format to use in the certificate validation that occurs during the SSL exchange. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_ISSUERCERT (int)

Proxy issuer SSL certificate filename. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_PROXY_ISSUERCERT_BLOB (int)

Proxy issuer SSL certificate from memory blob. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_PROXY_KEYPASSWD (int)

Set the string be used as the password required to use the CURLOPT_PROXY_SSLKEY private key. You never needed a passphrase to load a certificate but you need one to load your private key. This option is for connecting to an HTTPS proxy, not an HTTPS server. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_PINNEDPUBLICKEY (int)

Set the pinned public key for HTTPS proxy. The string can be the file name of your pinned public key. The file format expected is "PEM" or "DER". The string can also be any number of base64 encoded sha256 hashes preceded by "sha256//" and separated by ";". Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SERVICE_NAME (int)

The proxy authentication service name. Available as of PHP 7.0.7, cURL 7.43.0 (for HTTP proxies) and cURL 7.49.0 (for SOCKS5 proxies).

CURLOPT_PROXY_SSLCERT (int)

The file name of your client certificate used to connect to the HTTPS proxy. The default format is "P12" on Secure Transport and "PEM" on other engines, and can be changed with CURLOPT_PROXY_SSLCERTTYPE. With NSS or Secure Transport, this can also be the nickname of the certificate you wish to authenticate with as it is named in the security database. If you want to use a file from the current directory, please precede it with "./" prefix, in order to avoid confusion with a nickname. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSLCERTTYPE (int)

The format of your client certificate used when connecting to an HTTPS proxy. Supported formats are "PEM" and "DER", except with Secure Transport. OpenSSL (versions 0.9.3 and later) and Secure Transport (on iOS 5 or later, or OS X 10.7 or later) also support "P12" for PKCS#12-encoded files. Defaults to "PEM". Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSLCERT_BLOB (int)

SSL proxy client certificate from memory blob. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_PROXY_SSLKEY (int)

The file name of your private key used for connecting to the HTTPS proxy. The default format is "PEM" and can be changed with CURLOPT_PROXY_SSLKEYTYPE. (iOS and Mac OS X only) This option is ignored if curl was built against Secure Transport. Available if built TLS enabled. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSLKEYTYPE (int)

The format of your private key. Supported formats are "PEM", "DER" and "ENG". Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSLKEY_BLOB (int)

Private key for proxy cert from memory blob. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_PROXY_SSLVERSION (int)

One of CURL_SSLVERSION_DEFAULT, CURL_SSLVERSION_TLSv1, CURL_SSLVERSION_TLSv1_0, CURL_SSLVERSION_TLSv1_1, CURL_SSLVERSION_TLSv1_2, CURL_SSLVERSION_TLSv1_3, CURL_SSLVERSION_MAX_DEFAULT, CURL_SSLVERSION_MAX_TLSv1_0, CURL_SSLVERSION_MAX_TLSv1_1, CURL_SSLVERSION_MAX_TLSv1_2, CURL_SSLVERSION_MAX_TLSv1_3, CURL_SSLVERSION_SSLv3 .

警告

It is better to not set this option and leave the default CURL_SSLVERSION_DEFAULT which will attempt to figure out the remote SSL protocol version.

Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSL_CIPHER_LIST (int)

The list of ciphers to use for the connection to the HTTPS proxy. The list must be syntactically correct, it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, !, - and + can be used as operators. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSL_OPTIONS (int)

Set proxy SSL behavior options, which is a bitmask of the following constants: CURLSSLOPT_ALLOW_BEAST, CURLSSLOPT_NO_REVOKE, CURLSSLOPT_NO_PARTIALCHAIN Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSL_VERIFYHOST (int)

Set to 2 to verify in the HTTPS proxy's certificate name fields against the proxy name. When set to 0 the connection succeeds regardless of the names used in the certificate. Use that ability with caution! 1 treated as a debug option in curl 7.28.0 and earlier. From curl 7.28.1 to 7.65.3 CURLE_BAD_FUNCTION_ARGUMENT is returned. From curl 7.66.0 onwards 1 and 2 is treated as the same value. In production environments the value of this option should be kept at 2 (default value). Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_SSL_VERIFYPEER (int)

false to stop cURL from verifying the peer's certificate. Alternate certificates to verify against can be specified with the CURLOPT_CAINFO option or a certificate directory can be specified with the CURLOPT_CAPATH option. When set to false, the peer certificate verification succeeds regardless. true by default. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_TLS13_CIPHERS (int)

The list of cipher suites to use for the TLS 1.3 connection to a proxy. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. This option is currently used only when curl is built to use OpenSSL 1.1.1 or later. If you are using a different SSL backend you can try setting TLS 1.3 cipher suites by using the CURLOPT_PROXY_SSL_CIPHER_LIST option. Available when built with OpenSSL >= 1.1.1. Available as of PHP 7.3.0 and cURL 7.61.0

CURLOPT_PROXY_TLSAUTH_PASSWORD (int)

The password to use for the TLS authentication method specified with the CURLOPT_PROXY_TLSAUTH_TYPE option. Requires that the CURLOPT_PROXY_TLSAUTH_USERNAME option to also be set. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_TLSAUTH_TYPE (int)

The method of the TLS authentication used for the HTTPS connection. Supported method is "SRP".

注意:

Secure Remote Password (SRP) authentication for TLS provides mutual authentication if both sides have a shared secret. To use TLS-SRP, you must also set the CURLOPT_PROXY_TLSAUTH_USERNAME and CURLOPT_PROXY_TLSAUTH_PASSWORD options.

Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PROXY_TLSAUTH_USERNAME (int)

The username to use for the HTTPS proxy TLS authentication method specified with the CURLOPT_PROXY_TLSAUTH_TYPE option. Requires that the CURLOPT_PROXY_TLSAUTH_PASSWORD option to also be set. Available as of PHP 7.3.0 and cURL 7.52.0

CURLOPT_PUT (int)

true to HTTP PUT a file. The file to PUT must be set with CURLOPT_INFILE and CURLOPT_INFILESIZE.

CURLOPT_QUICK_EXIT (int)

Available as of PHP 8.3.0 and cURL 7.87.0

CURLOPT_QUOTE (int)

An array of FTP commands to execute on the server prior to the FTP request.

CURLOPT_RANDOM_FILE (int)

A filename to be used to seed the random number generator for SSL.

CURLOPT_RANGE (int)

Range(s) of data to retrieve in the format "X-Y" where X or Y are optional. HTTP transfers also support several intervals, separated with commas in the format "X-Y,N-M".

CURLOPT_READFUNCTION (int)

A callback accepting three parameters. The first is the cURL resource, the second is a stream resource provided to cURL through the option CURLOPT_INFILE, and the third is the maximum amount of data to be read. The callback must return a string with a length equal or smaller than the amount of data requested, typically by reading it from the passed stream resource. It should return an empty string to signal EOF.

CURLOPT_REDIR_PROTOCOLS (int)

Bitmask of CURLPROTO_* values. If used, this bitmask limits what protocols libcurl may use in a transfer that it follows to in a redirect when CURLOPT_FOLLOWLOCATION is enabled. This allows you to limit specific transfers to only be allowed to use a subset of protocols in redirections. By default libcurl will allow all protocols except for FILE and SCP. This is a difference compared to pre-7.19.4 versions which unconditionally would follow to all protocols supported. See also CURLOPT_PROTOCOLS for protocol constant values. Available as of cURL 7.19.4.

CURLOPT_REDIR_PROTOCOLS_STR (int)

Available as of PHP 8.3.0 and cURL 7.85.0.

CURLOPT_REFERER (int)

The contents of the "Referer: " header to be used in a HTTP request.

CURLOPT_REQUEST_TARGET (int)

Available as of PHP 7.3.0 and cURL 7.55.0.

CURLOPT_RESOLVE (int)

Provide a custom address for a specific host and port pair. An array of hostname, port, and IP address strings, each element separated by a colon. In the format: array("example.com:80:127.0.0.1") Available as of cURL 7.21.3.

CURLOPT_RESUME_FROM (int)

The offset, in bytes, to resume a transfer from.

CURLOPT_RETURNTRANSFER (int)

true to return the transfer as a string of the return value of curl_exec() instead of outputting it directly.

CURLOPT_SAFE_UPLOAD (int)

Always true, what disables support for the @ prefix for uploading files in CURLOPT_POSTFIELDS, which means that values starting with @ can be safely passed as fields. CURLFile may be used for uploads instead.

CURLOPT_SASL_AUTHZID (int)

The authorization identity (authzid) for the transfer. Only applicable to the PLAIN SASL authentication mechanism where it is optional. When not specified, only the authentication identity (authcid) as specified by the username will be sent to the server, along with the password. The server will derive the authzid from the authcid when not provided, which it will then use internally. Available as of PHP 8.2.0 and cURL 7.66.0

CURLOPT_SASL_IR (int)

true to enable sending the initial response in the first packet. Available as of PHP 7.0.7 and cURL 7.31.0

CURLOPT_SERVICE_NAME (int)

The authentication service name. Available as of PHP 7.0.7 and cURL 7.43.0

CURLOPT_SHARE (int)

A result of curl_share_init(). Makes the cURL handle to use the data from the shared handle.

CURLOPT_SOCKS5_AUTH (int)

The SOCKS5 authentication method(s) to use. The options are: CURLAUTH_BASIC, CURLAUTH_GSSAPI, CURLAUTH_NONE. The bitwise | (or) operator can be used to combine more than one method. If this is done, cURL will poll the server to see what methods it supports and pick the best one. CURLAUTH_BASIC allows username/password authentication. CURLAUTH_GSSAPI allows GSS-API authentication. CURLAUTH_NONE allows no authentication. Defaults to CURLAUTH_BASIC|CURLAUTH_GSSAPI. Set the actual username and password with the CURLOPT_PROXYUSERPWD option. Available as of PHP 7.3.0 and cURL 7.55.0

CURLOPT_SSH_AUTH_TYPES (int)

A bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Set to CURLSSH_AUTH_ANY to let libcurl pick one. Available as of cURL 7.16.1.

CURLOPT_SSH_COMPRESSION (int)

true to enable built-in SSH compression. This is a request, not an order; the server may or may not do it. Available as of PHP 7.3.0 and cURL 7.56.0

CURLOPT_SSH_HOSTKEYFUNCTION (int)

Available as of PHP 8.3.0 and cURL 7.84.0

CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (int)

A string containing 32 hexadecimal digits. The string should be the MD5 checksum of the remote host's public key, and libcurl will reject the connection to the host unless the md5sums match. This option is only for SCP and SFTP transfers. Available as of cURL 7.17.1.

CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (int)

Base64-encoded SHA256 hash of the remote host's public key. The transfer will fail if the given hash does not match the hash the remote host provides. Available as of PHP 8.2.0 and cURL 7.80.0

CURLOPT_SSH_PRIVATE_KEYFILE (int)

The file name for your private key. If not used, libcurl defaults to $HOME/.ssh/id_dsa if the HOME environment variable is set, and just "id_dsa" in the current directory if HOME is not set. If the file is password-protected, set the password with CURLOPT_KEYPASSWD. Available as of cURL 7.16.1.

CURLOPT_SSH_PUBLIC_KEYFILE (int)

The file name for your public key. If not used, libcurl defaults to $HOME/.ssh/id_dsa.pub if the HOME environment variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. Available as of cURL 7.16.1.

CURLOPT_SSLCERT (int)

The name of a file containing a PEM formatted certificate.

CURLOPT_SSLCERTPASSWD (int)

The password required to use the CURLOPT_SSLCERT certificate.

CURLOPT_SSLCERTTYPE (int)

The format of the certificate. Supported formats are "PEM" (default), "DER", and "ENG". As of OpenSSL 0.9.3, "P12" (for PKCS#12-encoded files) is also supported. Available as of cURL 7.9.3.

CURLOPT_SSLCERT_BLOB (int)

SSL client certificate from memory blob. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_SSLENGINE (int)

The identifier for the crypto engine of the private SSL key specified in CURLOPT_SSLKEY.

CURLOPT_SSLENGINE_DEFAULT (int)

The identifier for the crypto engine used for asymmetric crypto operations.

CURLOPT_SSLKEY (int)

The name of a file containing a private SSL key.

CURLOPT_SSLKEYPASSWD (int)

The secret password needed to use the private SSL key specified in CURLOPT_SSLKEY.

注意:

Since this option contains a sensitive password, remember to keep the PHP script it is contained within safe.

CURLOPT_SSLKEYTYPE (int)

The key type of the private SSL key specified in CURLOPT_SSLKEY. Supported key types are "PEM" (default), "DER", and "ENG".

CURLOPT_SSLKEY_BLOB (int)

Private key for client cert from memory blob. Available as of PHP 8.1.0 and cURL 7.71.0.

CURLOPT_SSLVERSION (int)

One of CURL_SSLVERSION_DEFAULT, CURL_SSLVERSION_TLSv1, CURL_SSLVERSION_SSLv2, CURL_SSLVERSION_SSLv3, CURL_SSLVERSION_TLSv1_0, CURL_SSLVERSION_TLSv1_1, CURL_SSLVERSION_TLSv1_2, CURL_SSLVERSION_TLSv1_3 . The maximum TLS version can be set by using one of the CURL_SSLVERSION_MAX_* constants. It is also possible to bitwise OR one of the CURL_SSLVERSION_* constants with one of the CURL_SSLVERSION_MAX_*. CURL_SSLVERSION_MAX_DEFAULT (the maximum version supported by the library), CURL_SSLVERSION_MAX_TLSv1_0, CURL_SSLVERSION_MAX_TLSv1_1, CURL_SSLVERSION_MAX_TLSv1_2, CURL_SSLVERSION_MAX_TLSv1_3 .

警告

It is better to not set this option and leave the defaults. As setting this to CURL_SSLVERSION_SSLv2 or CURL_SSLVERSION_SSLv3 is very dangerous, given the known vulnerabilities in SSLv2 and SSLv3.

CURLOPT_SSL_CIPHER_LIST (int)

A list of ciphers to use for SSL. For example, RC4-SHA and TLSv1 are valid cipher lists.

CURLOPT_SSL_EC_CURVES (int)

A colon delimited list of elliptic curve algorithms. For example, X25519:P-521 is a valid list of two elliptic curves. This option defines the client's key exchange algorithms in the SSL handshake, if the SSL backend cURL is built to use supports it. Available as of PHP 8.2.0 and cURL 7.73.0

CURLOPT_SSL_ENABLE_ALPN (int)

false to disable ALPN in the SSL handshake (if the SSL backend libcurl is built to use supports it), which can be used to negotiate http2. Available as of PHP 7.0.7 and cURL 7.36.0

CURLOPT_SSL_ENABLE_NPN (int)

false to disable NPN in the SSL handshake (if the SSL backend libcurl is built to use supports it), which can be used to negotiate http2. Available as of PHP 7.0.7 and cURL 7.36.0

CURLOPT_SSL_FALSESTART (int)

true to enable TLS false start. Available as of PHP 7.0.7 and cURL 7.42.0

CURLOPT_SSL_OPTIONS (int)

Set SSL behavior options, which is a bitmask of the following constants: CURLSSLOPT_ALLOW_BEAST, CURLSSLOPT_NO_REVOKE, CURLSSLOPT_AUTO_CLIENT_CERT, CURLSSLOPT_NATIVE_CA, CURLSSLOPT_NO_PARTIALCHAIN, CURLSSLOPT_REVOKE_BEST_EFFORT Available as of PHP 7.0.7. and cURL 7.25.0

CURLOPT_SSL_VERIFYHOST (int)

2 to verify that a Common Name field or a Subject Alternate Name field in the SSL peer certificate matches the provided hostname. 0 to not check the names. 1 should not be used. In production environments the value of this option should be kept at 2 (default value). Support for value 1 removed in cURL 7.28.1.

CURLOPT_SSL_VERIFYPEER (int)

false to stop cURL from verifying the peer's certificate. Alternate certificates to verify against can be specified with the CURLOPT_CAINFO option or a certificate directory can be specified with the CURLOPT_CAPATH option. true by default as of cURL 7.10. Default bundle installed as of cURL 7.10.

CURLOPT_SSL_VERIFYSTATUS (int)

true to verify the certificate's status. Available as of PHP 7.0.7 and cURL 7.41.0

CURLOPT_STDERR (int)

An alternative location to output errors to instead of STDERR.

CURLOPT_STREAM_WEIGHT (int)

Set the numerical stream weight (a number between 1 and 256). Available as of PHP 7.0.7 and cURL 7.46.0

CURLOPT_SUPPRESS_CONNECT_HEADERS (int)

true to suppress proxy CONNECT response headers from the user callback functions CURLOPT_HEADERFUNCTION and CURLOPT_WRITEFUNCTION, when CURLOPT_HTTPPROXYTUNNEL is used and a CONNECT request is made. Available as of PHP 7.3.0 and cURL 7.54.0

CURLOPT_TCP_FASTOPEN (int)

true to enable TCP Fast Open. Available as of PHP 7.0.7 and cURL 7.49.0

CURLOPT_TCP_KEEPALIVE (int)

If set to 1, TCP keepalive probes will be sent. The delay and frequency of these probes can be controlled by the CURLOPT_TCP_KEEPIDLE and CURLOPT_TCP_KEEPINTVL options, provided the operating system supports them. If set to 0 (default) keepalive probes are disabled. Available as of cURL 7.25.0

CURLOPT_TCP_KEEPIDLE (int)

Sets the delay, in seconds, that the operating system will wait while the connection is idle before sending keepalive probes, if CURLOPT_TCP_KEEPALIVE is enabled. Not all operating systems support this option. The default is 60. Available as of cURL 7.25.0

CURLOPT_TCP_KEEPINTVL (int)

Sets the interval, in seconds, that the operating system will wait between sending keepalive probes, if CURLOPT_TCP_KEEPALIVE is enabled. Not all operating systems support this option. The default is 60. Available as of cURL 7.25.0

CURLOPT_TCP_NODELAY (int)

true to disable TCP's Nagle algorithm, which tries to minimize the number of small packets on the network. Available as of cURL 7.11.2.

CURLOPT_TFTP_NO_OPTIONS (int)

true to not send TFTP options requests. Available as of PHP 7.0.7 and cURL 7.48.0

CURLOPT_TIMECONDITION (int)

How CURLOPT_TIMEVALUE is treated. Use CURL_TIMECOND_IFMODSINCE to return the page only if it has been modified since the time specified in CURLOPT_TIMEVALUE. If it hasn't been modified, a "304 Not Modified" header will be returned assuming CURLOPT_HEADER is true. Use CURL_TIMECOND_IFUNMODSINCE for the reverse effect. Use CURL_TIMECOND_NONE to ignore CURLOPT_TIMEVALUE and always return the page. CURL_TIMECOND_NONE is the default. Before cURL 7.46.0 the default was CURL_TIMECOND_IFMODSINCE.

CURLOPT_TIMEOUT (int)

The maximum number of seconds to allow cURL functions to execute.

CURLOPT_TIMEOUT_MS (int)

The maximum number of milliseconds to allow cURL functions to execute. If libcurl is built to use the standard system name resolver, that portion of the connect will still use full-second resolution for timeouts with a minimum timeout allowed of one second. Available as of cURL 7.16.2.

CURLOPT_TIMEVALUE (int)

The time in seconds since January 1st, 1970. The time will be used by CURLOPT_TIMECONDITION.

CURLOPT_TIMEVALUE_LARGE (int)

The time in seconds since January 1st, 1970. The time will be used by CURLOPT_TIMECONDITION. Defaults to zero. The difference between this option and CURLOPT_TIMEVALUE is the type of the argument. On systems where 'long' is only 32 bit wide, this option has to be used to set dates beyond the year 2038. Available as of PHP 7.3.0 and cURL 7.59.0

CURLOPT_TLS13_CIPHERS (int)

The list of cipher suites to use for the TLS 1.3 connection. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. This option is currently used only when curl is built to use OpenSSL 1.1.1 or later. If you are using a different SSL backend you can try setting TLS 1.3 cipher suites by using the CURLOPT_SSL_CIPHER_LIST option. Available when built with OpenSSL >= 1.1.1. Available as of PHP 7.3.0 and cURL 7.61.0

CURLOPT_TRANSFERTEXT (int)

true to use ASCII mode for FTP transfers. For LDAP, it retrieves data in plain text instead of HTML. On Windows systems, it will not set STDOUT to binary mode.

CURLOPT_UNIX_SOCKET_PATH (int)

Enables the use of Unix domain sockets as connection endpoint and sets the path to the given string. Available as of PHP 7.0.7 and cURL 7.40.0

CURLOPT_UNRESTRICTED_AUTH (int)

true to keep sending the username and password when following locations (using CURLOPT_FOLLOWLOCATION), even when the hostname has changed.

CURLOPT_UPKEEP_INTERVAL_MS (int)

Some protocols have "connection upkeep" mechanisms. These mechanisms usually send some traffic on existing connections in order to keep them alive. This option defines the connection upkeep interval. Currently, the only protocol with a connection upkeep mechanism is HTTP/2. When the connection upkeep interval is exceeded, an HTTP/2 PING frame is sent on the connection. Default is 60 seconds. Available as of PHP 8.2.0 and cURL 7.62.0

CURLOPT_UPLOAD (int)

true to prepare for an upload.

CURLOPT_UPLOAD_BUFFERSIZE (int)

Preferred buffer size in bytes for the cURL upload buffer. The upload buffer size by default is 64 kilobytes. The maximum buffer size allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is 16 kilobytes. Available as of PHP 8.2.0 and cURL 7.62.0

CURLOPT_URL (int)

The URL to fetch. This can also be set when initializing a session with curl_init().

CURLOPT_USERAGENT (int)

The contents of the "User-Agent: " header to be used in a HTTP request.

CURLOPT_USERNAME (int)

The user name to use in authentication. Available as of cURL 7.19.1

CURLOPT_USERPWD (int)

A username and password formatted as "[username]:[password]" to use for the connection.

CURLOPT_VERBOSE (int)

true to output verbose information. Writes output to STDERR, or the file specified using CURLOPT_STDERR.

CURLOPT_WRITEFUNCTION (int)

A callback accepting two parameters. The first is the cURL resource, and the second is a string with the data to be written. The data must be saved by this callback. It must return the exact number of bytes written or the transfer will be aborted with an error.

CURLOPT_WRITEHEADER (int)

The file that the header part of the transfer is written to.

CURLOPT_WS_OPTIONS (int)

Available as of PHP 8.3.0 and cURL 7.86.0

CURLOPT_XFERINFOFUNCTION (int)

A callback accepting two parameters. Has a similar purpose as CURLOPT_PROGRESSFUNCTION but is more modern and the preferred option from cURL. Available as of PHP 8.2.0 and cURL 7.32.0.

CURLOPT_XOAUTH2_BEARER (int)

Specifies the OAuth 2.0 access token. Available as of PHP 7.0.7 and cURL 7.33.0

curl_share_setopt()
定数 | 説明
CURL_LOCK_DATA_CONNECT (int) | 接続キャッシュを共有/非共有にします。 PHP 7.3.0 および cURL 7.10.0 以降で使用可能です。
CURL_LOCK_DATA_COOKIE (int) | Shares/unshares cookie data.
CURL_LOCK_DATA_DNS (int) | Shares/unshares DNS cache. Note that when you use cURL multi handles, all handles added to the same multi handle will share DNS cache by default.
CURL_LOCK_DATA_PSL (int) | Public Suffix List を共有/非共有にします。 PHP 7.3.0 および cURL 7.61.0 以降で使用可能です。
CURL_LOCK_DATA_SSL_SESSION (int) | Shares/unshares SSL session IDs, reducing the time spent on the SSL handshake when reconnecting to the same server. Note that SSL session IDs are reused within the same handle by default.
CURLSHOPT_NONE (int) |
CURLSHOPT_SHARE (int) | Specifies a type of data that should be shared.
CURLSHOPT_UNSHARE (int) | Specifies a type of data that will be no longer shared.
curl_getinfo()
定数 | 説明
CURLINFO_APPCONNECT_TIME (int) | Time in seconds it took from the start until the SSL/SSH connect/handshake to the remote host was completed
CURLINFO_APPCONNECT_TIME_T (int) | Time, in microseconds, it took from the start until the SSL/SSH connect/handshake to the remote host was completed. Available as of PHP 7.3.0 and cURL 7.61.0
CURLINFO_CAINFO (int) | Default built-in CA certificate path. Available as of PHP 8.3.0 and cURL 7.84.0
CURLINFO_CAPATH (int) | Default built-in CA path string. Available as of PHP 8.3.0 and cURL 7.84.0
CURLINFO_CERTINFO (int) | TLS certificate chain
CURLINFO_CONDITION_UNMET (int) | Info on unmet time conditional
CURLINFO_CONNECT_TIME (int) | Time in seconds it took to establish the connection
CURLINFO_CONNECT_TIME_T (int) | Total time taken, in microseconds, from the start until the connection to the remote host (or proxy) was completed. Available as of PHP 7.3.0 and cURL 7.61.0
CURLINFO_CONTENT_LENGTH_DOWNLOAD (int) | Content length of download, read from Content-Length: field
CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (int) | The content-length of the download. This is the value read from the Content-Length: field. -1 if the size isn't known. Available as of PHP 7.3.0 and cURL 7.55.0
CURLINFO_CONTENT_LENGTH_UPLOAD (int) | Specified size of upload
CURLINFO_CONTENT_LENGTH_UPLOAD_T (int) | The specified size of the upload. -1 if the size isn't known. Available as of PHP 7.3.0 and cURL 7.55.0
CURLINFO_CONTENT_TYPE (int) | Content-Type of the requested document. NULL indicates server did not send valid Content-Type header
CURLINFO_COOKIELIST (int) | All known cookies
CURLINFO_EFFECTIVE_METHOD (int) | Get the last used HTTP method.
CURLINFO_EFFECTIVE_URL (int) | Last effective URL
CURLINFO_FILETIME (int) | Remote time of the retrieved document, with the CURLOPT_FILETIME enabled; if -1 is returned the time of the document is unknown
CURLINFO_FILETIME_T (int) | Remote time of the retrieved document (as Unix timestamp), an alternative to CURLINFO_FILETIME to allow systems with 32 bit long variables to extract dates outside of the 32bit timestamp range. Available as of PHP 7.3.0 and cURL 7.59.0
CURLINFO_FTP_ENTRY_PATH (int) | Entry path in FTP server
CURLINFO_HEADER_OUT (int) | The request string sent. For this to work, add the CURLINFO_HEADER_OUT option to the handle by calling curl_setopt()
CURLINFO_HEADER_SIZE (int) | Total size of all headers received
CURLINFO_HTTPAUTH_AVAIL (int) | Bitmask indicating the authentication method(s) available according to the previous response
CURLINFO_HTTP_CODE (int) | The last response code. As of cURL 7.10.8, this is a legacy alias of CURLINFO_RESPONSE_CODE.
CURLINFO_HTTP_CONNECTCODE (int) | The CONNECT response code
CURLINFO_HTTP_VERSION (int) | The version used in the last HTTP connection. The return value will be one of the defined CURL_HTTP_VERSION_* constants or 0 if the version can't be determined. Available as of PHP 7.3.0 and cURL 7.50.0
CURLINFO_LASTONE (int) | The last enum value in the underlying CURLINFO enum in libcurl.
CURLINFO_LOCAL_IP (int) | Local (source) IP address of the most recent connection
CURLINFO_LOCAL_PORT (int) | Local (source) port of the most recent connection
CURLINFO_NAMELOOKUP_TIME (int) | Time in seconds until name resolving was complete
CURLINFO_NAMELOOKUP_TIME_T (int) | Time in microseconds from the start until the name resolving was completed. Available as of PHP 7.3.0 and cURL 7.61.0
CURLINFO_NUM_CONNECTS (int) | Number of connections curl had to create to achieve the previous transfer
CURLINFO_OS_ERRNO (int) | Errno from a connect failure. The number is OS and system specific.
CURLINFO_PRETRANSFER_TIME (int) | Time in seconds from start until just before file transfer begins
CURLINFO_PRETRANSFER_TIME_T (int) | Time taken from the start until the file transfer is just about to begin, in microseconds. Available as of PHP 7.3.0 and cURL 7.61.0
CURLINFO_PRIMARY_IP (int) | IP address of the most recent connection
CURLINFO_PRIMARY_PORT (int) | Destination port of the most recent connection
CURLINFO_PRIVATE (int) | Private data associated with this cURL handle, previously set with the CURLOPT_PRIVATE option of curl_setopt()
CURLINFO_PROTOCOL (int) | The protocol used in the last HTTP connection. The returned value will be exactly one of the CURLPROTO_* values. Available as of PHP 7.3.0 and cURL 7.52.0
CURLINFO_PROXYAUTH_AVAIL (int) | Bitmask indicating the proxy authentication method(s) available according to the previous response
CURLINFO_PROXY_ERROR (int) | The detailed (SOCKS) proxy error code when the most recent transfer returned a CURLE_PROXY error. The returned value will be exactly one of the CURLPX_* values. The error code will be CURLPX_OK if no response code was available. Available as of PHP 8.2.0 and cURL 7.73.0
CURLINFO_PROXY_SSL_VERIFYRESULT (int) | The result of the certificate verification that was requested (using the CURLOPT_PROXY_SSL_VERIFYPEER option). Only used for HTTPS proxies. Available as of PHP 7.3.0 and cURL 7.52.0
CURLINFO_REDIRECT_COUNT (int) | Number of redirects, with the CURLOPT_FOLLOWLOCATION option enabled
CURLINFO_REDIRECT_TIME (int) | Time in seconds of all redirection steps before final transaction was started, with the CURLOPT_FOLLOWLOCATION option enabled
CURLINFO_REDIRECT_TIME_T (int) | Total time, in microseconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. Available as of PHP 7.3.0 and cURL 7.61.0
CURLINFO_REDIRECT_URL (int) | With the CURLOPT_FOLLOWLOCATION option disabled: redirect URL found in the last transaction, that should be requested manually next. With the CURLOPT_FOLLOWLOCATION option enabled: this is empty. The redirect URL in this case is available in CURLINFO_EFFECTIVE_URL
CURLINFO_REFERER (int) | The Referer header. Available as of PHP 8.2.0 and cURL 7.76.0
CURLINFO_REQUEST_SIZE (int) | Total size of issued requests, currently only for HTTP requests
CURLINFO_RESPONSE_CODE (int) | The last response code. Available as of cURL 7.10.8
CURLINFO_RETRY_AFTER (int) | The information from the Retry-After header, or zero if there was no valid header. Available as of PHP 8.2.0 and cURL 7.66.0
CURLINFO_RTSP_CLIENT_CSEQ (int) | Next RTSP client CSeq
CURLINFO_RTSP_CSEQ_RECV (int) | Recently received CSeq
CURLINFO_RTSP_SERVER_CSEQ (int) | Next RTSP server CSeq
CURLINFO_RTSP_SESSION_ID (int) | RTSP session ID
CURLINFO_SCHEME (int) | The URL scheme used for the most recent connection. Available as of PHP 7.3.0 and cURL 7.52.0
CURLINFO_SIZE_DOWNLOAD (int) | Total number of bytes downloaded
CURLINFO_SIZE_DOWNLOAD_T (int) | Total number of bytes that were downloaded. The number is only for the latest transfer and will be reset again for each new transfer. Available as of PHP 7.3.0 and cURL 7.50.0
CURLINFO_SIZE_UPLOAD (int) | Total number of bytes uploaded
CURLINFO_SIZE_UPLOAD_T (int) | Total number of bytes that were uploaded. Available as of PHP 7.3.0 and cURL 7.50.0
CURLINFO_SPEED_DOWNLOAD (int) | Average download speed
CURLINFO_SPEED_DOWNLOAD_T (int) | The average download speed in bytes/second that curl measured for the complete download. Available as of PHP 7.3.0 and cURL 7.50.0
CURLINFO_SPEED_UPLOAD (int) | Average upload speed
CURLINFO_SPEED_UPLOAD_T (int) | The average upload speed in bytes/second that curl measured for the complete upload. Available as of PHP 7.3.0 and cURL 7.50.0
CURLINFO_SSL_ENGINES (int) | OpenSSL crypto-engines supported
CURLINFO_SSL_VERIFYRESULT (int) | Result of SSL certification verification requested by setting CURLOPT_SSL_VERIFYPEER
CURLINFO_STARTTRANSFER_TIME (int) | Time in seconds until the first byte is about to be transferred
CURLINFO_STARTTRANSFER_TIME_T (int) | Time, in microseconds, it took from the start until the first byte is received. Available as of PHP 7.3.0 and cURL 7.61.0
CURLINFO_TOTAL_TIME (int) | Total transaction time in seconds for last transfer
CURLINFO_TOTAL_TIME_T (int) | Total time in microseconds for the previous transfer, including name resolving, TCP connect etc. Available as of PHP 7.3.0 and cURL 7.61.0
curl_multi_setopt()
定数 | 説明
CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (int) | Specifies the chunk length threshold for pipelining in bytes. Available as of PHP 7.0.7 and cURL 7.30.0
CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (int) | Specifies the size threshold for pipelining penalty in bytes. Available as of PHP 7.0.7 and cURL 7.30.0
CURLMOPT_MAXCONNECTS (int) | Specifies the maximum amount of simultaneously open connections that libcurl may cache. By default the size will be enlarged to fit four times the number of handles added via curl_multi_add_handle(). When the cache is full, curl closes the oldest one in the cache to prevent the number of open connections from increasing. Available as of cURL 7.16.3.
CURLMOPT_MAX_CONCURRENT_STREAMS (int) | Specifies the maximum number of concurrent streams for connections that cURL should support on connections using HTTP/2. Valid values range from 1 to 2147483647 (2^31 - 1). The value passed here would be honored based on other system resources properties. Default is 100. Available as of PHP 8.2.0 and cURL 7.67.0.
CURLMOPT_MAX_HOST_CONNECTIONS (int) | Specifies the maximum number of connections to a single host. Available as of PHP 7.0.7 and cURL 7.30.0
CURLMOPT_MAX_PIPELINE_LENGTH (int) | Specifies the maximum number of requests in a pipeline. Available as of PHP 7.0.7 and cURL 7.30.0
CURLMOPT_MAX_TOTAL_CONNECTIONS (int) | Specifies the maximum number of simultaneously open connections. Available as of PHP 7.0.7 and cURL 7.30.0
CURLMOPT_PIPELINING (int) | Pass 1 to enable or 0 to disable. Enabling pipelining on a multi handle will make it attempt to perform HTTP Pipelining as far as possible for transfers using this handle. This means that adding a second request that can use an already existing connection will "pipe" the second request on the same connection. As of cURL 7.43.0, the value is a bitmask, and passing 2 will try to multiplex the new transfer over an existing HTTP/2 connection. Passing 3 instructs cURL to ask for pipelining and multiplexing independently of each other. As of cURL 7.62.0, setting the pipelining bit has no effect. Instead of integer literals, the CURLPIPE_* constants can also be used. Available as of cURL 7.16.0.
CURLMOPT_PUSHFUNCTION (int)

Pass a callable that will be registered to handle server pushes and should have the following signature:

pushfunction(resource $parent_ch, resource $pushed_ch, array $headers): int
parent_ch
The parent cURL handle (the request the client made).
pushed_ch
A new cURL handle for the pushed request.
headers
The push promise headers.
The push function is supposed to return either CURL_PUSH_OK if it can handle the push, or CURL_PUSH_DENY to reject it. Available as of PHP 7.1.0 and cURL 7.44.0

cURL protocol constants
定数 | 説明
CURLPROTO_ALL (int) |
CURLPROTO_DICT (int) |
CURLPROTO_FILE (int) |
CURLPROTO_FTP (int) |
CURLPROTO_FTPS (int) |
CURLPROTO_GOPHER (int) |
CURLPROTO_HTTP (int) |
CURLPROTO_HTTPS (int) |
CURLPROTO_IMAP (int) |
CURLPROTO_IMAPS (int) |
CURLPROTO_LDAP (int) |
CURLPROTO_LDAPS (int) |
CURLPROTO_MQTT (int) | Available as of PHP 8.2.0 and cURL 7.71.0.
CURLPROTO_POP3 (int) |
CURLPROTO_POP3S (int) |
CURLPROTO_RTMP (int) |
CURLPROTO_RTMPE (int) |
CURLPROTO_RTMPS (int) |
CURLPROTO_RTMPT (int) |
CURLPROTO_RTMPTE (int) |
CURLPROTO_RTMPTS (int) |
CURLPROTO_RTSP (int) |
CURLPROTO_SCP (int) |
CURLPROTO_SFTP (int) |
CURLPROTO_SMB (int) | Available as of PHP 7.0.7 and cURL 7.40.0.
CURLPROTO_SMBS (int) | Available as of PHP 7.0.7 and cURL 7.40.0.
CURLPROTO_SMTP (int) |
CURLPROTO_SMTPS (int) |
CURLPROTO_TELNET (int) |
CURLPROTO_TFTP (int) |
cURL error constants
定数 | 説明
CURLE_ABORTED_BY_CALLBACK (int) | Aborted by callback. A callback returned "abort" to libcurl.
CURLE_BAD_CALLING_ORDER (int) |
CURLE_BAD_CONTENT_ENCODING (int) | Unrecognized transfer encoding.
CURLE_BAD_DOWNLOAD_RESUME (int) | The download could not be resumed because the specified offset was out of the file boundary.
CURLE_BAD_FUNCTION_ARGUMENT (int) | A function was called with a bad parameter.
CURLE_BAD_PASSWORD_ENTERED (int) |
CURLE_COULDNT_CONNECT (int) | Failed to connect to host or proxy.
CURLE_COULDNT_RESOLVE_HOST (int) | Could not resolve host. The given remote host was not resolved.
CURLE_COULDNT_RESOLVE_PROXY (int) | Could not resolve proxy. The given proxy host could not be resolved.
CURLE_FAILED_INIT (int) | Early initialization code failed. This is likely to be an internal error or problem, or a resource problem where something fundamental could not get done at init time.
CURLE_FILESIZE_EXCEEDED (int) | Maximum file size exceeded.
CURLE_FILE_COULDNT_READ_FILE (int) | A file given with FILE:// could not be opened. Most likely because the file path does not identify an existing file or due to the lack of appropriate file permissions.
CURLE_FTP_ACCESS_DENIED (int) |
CURLE_FTP_BAD_DOWNLOAD_RESUME (int) |
CURLE_FTP_CANT_GET_HOST (int) | An internal failure to lookup the host used for the new connection.
CURLE_FTP_CANT_RECONNECT (int) |
CURLE_FTP_COULDNT_GET_SIZE (int) |
CURLE_FTP_COULDNT_RETR_FILE (int) | This was either a unexpected reply to a 'RETR' command or a zero byte transfer complete.
CURLE_FTP_COULDNT_SET_ASCII (int) |
CURLE_FTP_COULDNT_SET_BINARY (int) |
CURLE_FTP_COULDNT_STOR_FILE (int) |
CURLE_FTP_COULDNT_USE_REST (int) | The FTP REST command returned error. This should never happen if the server is sane.
CURLE_FTP_PARTIAL_FILE (int) |
CURLE_FTP_PORT_FAILED (int) | The FTP PORT command returned error. This mostly happens when a good enough address has not been specified for libcurl to use. See CURLOPT_FTPPORT.
CURLE_FTP_QUOTE_ERROR (int) |
CURLE_FTP_SSL_FAILED (int) |
CURLE_FTP_USER_PASSWORD_INCORRECT (int) |
CURLE_FTP_WEIRD_227_FORMAT (int) | FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back.
CURLE_FTP_WEIRD_PASS_REPLY (int) | After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned.
CURLE_FTP_WEIRD_PASV_REPLY (int) | libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed.
CURLE_FTP_WEIRD_SERVER_REPLY (int) | The server sent data libcurl could not parse. This error code is known as CURLE_WEIRD_SERVER_REPLY as of cURL 7.51.0.
CURLE_FTP_WEIRD_USER_REPLY (int) |
CURLE_FTP_WRITE_ERROR (int) |
CURLE_FUNCTION_NOT_FOUND (int) | Function not found. A required zlib function was not found.
CURLE_GOT_NOTHING (int) | Nothing was returned from the server, and under the circumstances, getting nothing is considered an error.
CURLE_HTTP_NOT_FOUND (int) |
CURLE_HTTP_PORT_FAILED (int) |
CURLE_HTTP_POST_ERROR (int) | This is an odd error that mainly occurs due to internal confusion.
CURLE_HTTP_RANGE_ERROR (int) |
CURLE_HTTP_RETURNED_ERROR (int) | This is returned if CURLOPT_FAILONERROR is set true and the HTTP server returns an error code that is greater than or equal to 400.
CURLE_LDAP_CANNOT_BIND (int) | LDAP cannot bind. LDAP bind operation failed.
CURLE_LDAP_INVALID_URL (int) |
CURLE_LDAP_SEARCH_FAILED (int) | LDAP search failed.
CURLE_LIBRARY_NOT_FOUND (int) |
CURLE_MALFORMAT_USER (int) |
CURLE_OBSOLETE (int) |
CURLE_OK (int) | All fine. Proceed as usual.
CURLE_OPERATION_TIMEDOUT (int) | Operation timeout. The specified time-out period was reached according to the conditions.
CURLE_OPERATION_TIMEOUTED (int) |
CURLE_OUT_OF_MEMORY (int) | A memory allocation request failed.
CURLE_PARTIAL_FILE (int) | A file transfer was shorter or larger than expected. This happens when the server first reports an expected transfer size, and then delivers data that does not match the previously given size.
CURLE_PROXY (int) | Proxy handshake error. CURLINFO_PROXY_ERROR provides extra details on the specific problem. Available as of PHP 8.2.0 and cURL 7.73.0
CURLE_READ_ERROR (int) | There was a problem reading a local file or an error returned by the read callback.
CURLE_RECV_ERROR (int) | Failure with receiving network data.
CURLE_SEND_ERROR (int) | Failed sending network data.
CURLE_SHARE_IN_USE (int) |
CURLE_SSH (int) | An unspecified error occurred during the SSH session. Available as of cURL 7.16.1.
CURLE_SSL_CACERT (int) |
CURLE_SSL_CACERT_BADFILE (int) | Problem with reading the SSL CA cert.
CURLE_SSL_CERTPROBLEM (int) | Problem with the local client certificate.
CURLE_SSL_CIPHER (int) | Could not use specified cipher.
CURLE_SSL_CONNECT_ERROR (int) | A problem occurred somewhere in the SSL/TLS handshake. Reading the message in the error buffer provides more details on the problem. Could be certificates (file formats, paths, permissions), passwords, and others.
CURLE_SSL_ENGINE_NOTFOUND (int) | The specified crypto engine was not found.
CURLE_SSL_ENGINE_SETFAILED (int) | Failed setting the selected SSL crypto engine as default.
CURLE_SSL_PEER_CERTIFICATE (int) |
CURLE_SSL_PINNEDPUBKEYNOTMATCH (int) | Failed to match the pinned key specified with CURLOPT_PINNEDPUBLICKEY.
CURLE_TELNET_OPTION_SYNTAX (int) |
CURLE_TOO_MANY_REDIRECTS (int) | Too many redirects. When following redirects, libcurl hit the maximum amount. The limit can be set with CURLOPT_MAXREDIRS.
CURLE_UNKNOWN_TELNET_OPTION (int) |
CURLE_UNSUPPORTED_PROTOCOL (int) | The URL passed to libcurl used a protocol that libcurl does not support. The issue might be a compile-time option that was not used, a misspelled protocol string or just a protocol libcurl has no code for.
CURLE_URL_MALFORMAT (int) | The URL was not properly formatted.
CURLE_URL_MALFORMAT_USER (int) |
CURLE_WEIRD_SERVER_REPLY (int) | The server sent data libcurl could not parse. This error code was known as CURLE_FTP_WEIRD_SERVER_REPLY before cURL 7.51.0. Available as of PHP 7.3.0 and cURL 7.51.0
CURLE_WRITE_ERROR (int) | An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback.
curl_multi_* status constants
定数 | 説明
CURLM_ADDED_ALREADY (int) | An easy handle already added to a multi handle was attempted to get added a second time. Available as of cURL 7.32.1
CURLM_BAD_EASY_HANDLE (int) | An easy handle was not good/valid. It could mean that it is not an easy handle at all, or possibly that the handle already is in use by this or another multi handle.
CURLM_BAD_HANDLE (int) | The passed-in handle is not a valid multi handle.
CURLM_CALL_MULTI_PERFORM (int) | As of cURL 7.20.0, this constant is not used. Before cURL 7.20.0, this status could be returned by curl_multi_exec() when curl_multi_select() or a similar function was called before it returned any other constant.
CURLM_INTERNAL_ERROR (int) | Internal libcurl error.
CURLM_OK (int) | No errors.
CURLM_OUT_OF_MEMORY (int) | Ran out of memory while processing multi handles.
curl_pause()
定数 | 説明
CURLPAUSE_ALL (int) | Pause sending and receiving data. Available as of cURL 7.18.0.
CURLPAUSE_CONT (int) | Unpause sending and receiving data. Available as of cURL 7.18.0.
CURLPAUSE_RECV (int) | Pause receiving data. Available as of cURL 7.18.0.
CURLPAUSE_RECV_CONT (int) | Unpause receiving data. Available as of cURL 7.18.0.
CURLPAUSE_SEND (int) | Pause sending data. Available as of cURL 7.18.0.
CURLPAUSE_SEND_CONT (int) | Unpause sending data. Available as of cURL 7.18.0.


  • ≪ 定義済み定数
  • 基本的な curl の使用法 ≫
  • PHP Manual
  • cURL
  • 例

例

目次

  • 基本的な curl の使用法


基本的な curl の使用法

PHP を cURL サポート機能付きでコンパイルすると、 curl 関数を使用可能となります。cURL 関数の基本的な使用法は、 curl_init()により cURL セッションを初期化、 curl_setopt() により転送時のオプションを設定、 続いてcurl_exec() により転送を実行し、 curl_close() によりセッションを終了するというものになります。 cURL 関数を使用して example.com ホームページをファイルに取得する例を示します。

例1 PHP の cURL モジュールを使用して example.com のホームページを取得する

<?php

$ch = curl_init("http://www.example.com/");
$fp = fopen("example_homepage.txt", "w");

curl_setopt($ch, CURLOPT_FILE, $fp);
curl_setopt($ch, CURLOPT_HEADER, 0);

curl_exec($ch);
if(curl_error($ch)) {
fwrite($fp, curl_error($ch));
}
curl_close($ch);
fclose($fp);
?>


cURL 関数

目次

  • curl_close — cURL セッションを閉じる
  • curl_copy_handle — cURL ハンドルを、その設定も含めてコピーする
  • curl_errno — 直近のエラー番号を返す
  • curl_error — 現在のセッションに関する直近のエラー文字列を返す
  • curl_escape — 指定した文字列を URL エンコードする
  • curl_exec — cURL セッションを実行する
  • curl_getinfo — 指定した伝送に関する情報を得る
  • curl_init — cURL セッションを初期化する
  • curl_multi_add_handle — cURL マルチハンドルに、通常の cURL ハンドルを追加する
  • curl_multi_close — cURL ハンドルのセットを閉じる
  • curl_multi_errno — 直近のマルチハンドルに対するエラー番号を返す
  • curl_multi_exec — 現在の cURL ハンドルから、サブ接続を実行する
  • curl_multi_getcontent — CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す
  • curl_multi_info_read — 現在の転送についての情報を表示する
  • curl_multi_init — 新規 cURL マルチハンドルを返す
  • curl_multi_remove_handle — cURL ハンドルのセットからマルチハンドルを削除する
  • curl_multi_select — curl_multi 接続のアクティビティを待つ
  • curl_multi_setopt — cURL マルチハンドル用のオプションを設定する
  • curl_multi_strerror — エラーの内容を表す文字列を返す
  • curl_pause — 接続の中断と再開をする
  • curl_reset — libcurl セッションハンドルのすべてのオプションをリセットする
  • curl_setopt — cURL 転送用オプションを設定する
  • curl_setopt_array — CURL 転送用の複数のオプションを設定する
  • curl_share_close — cURL 共有ハンドルを閉じる
  • curl_share_errno — 直近の共有ハンドルに対するエラー番号を返す
  • curl_share_init — curl 共有ハンドルを初期化する
  • curl_share_setopt — cURL 共有ハンドルのオプションを設定する
  • curl_share_strerror — 与えられたエラーコードを説明する文字列を返す
  • curl_strerror — エラーコードの説明を返す
  • curl_unescape — URL エンコードされた文字列をデコードする
  • curl_upkeep — 接続を維持するためのチェックを行う
  • curl_version — cURL のバージョンを返す


cURL セッションを閉じる

  • ≪ cURL 関数
  • curl_copy_handle ≫
  • PHP Manual
  • cURL 関数
  • cURL セッションを閉じる

curl_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_close — cURL セッションを閉じる

説明

curl_close(CurlHandle $handle): void

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

cURL セッションを閉じ、全てのリソースを開放します。 cURL ハンドル handle も削除されます。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 新しい cURL セッションの初期化とウェブページの取得

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL とその他のオプションを設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// URL を取得し、それをブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを解放します
curl_close($ch);
?>

参考

  • curl_init() - cURL セッションを初期化する
  • curl_multi_close() - cURL ハンドルのセットを閉じる


cURL ハンドルを、その設定も含めてコピーする

  • ≪ curl_close
  • curl_errno ≫
  • PHP Manual
  • cURL 関数
  • cURL ハンドルを、その設定も含めてコピーする

curl_copy_handle

(PHP 5, PHP 7, PHP 8)

curl_copy_handle — cURL ハンドルを、その設定も含めてコピーする

説明

curl_copy_handle(CurlHandle $handle): CurlHandle|false

cURL ハンドルをコピーし、同じ設定を保持します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

新しい cURL ハンドルを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | 成功時に、この関数は CurlHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource が返されていました。

例

例1 cURL ハンドルのコピー

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL その他のオプションを適切に設定します
curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/');
curl_setopt($ch, CURLOPT_HEADER, 0);

// ハンドルをコピーします
$ch2 = curl_copy_handle($ch);

// URL (http://www.example.com/) を取得し、ブラウザに渡します
curl_exec($ch2);

// cURL リソースを閉じ、システムリソースを開放します
curl_close($ch2);
curl_close($ch);
?>


直近のエラー番号を返す

  • ≪ curl_copy_handle
  • curl_error ≫
  • PHP Manual
  • cURL 関数
  • 直近のエラー番号を返す

curl_errno

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

curl_errno — 直近のエラー番号を返す

説明

curl_errno(CurlHandle $handle): int

直近の cURL 処理に関するエラー番号を返します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

エラー番号を返します。エラーが発生しない場合、 0 (ゼロ) を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_errno() の例

<?php
// 存在しない場所への curl ハンドルを作成します
$ch = curl_init('http://404.php.net/');

// 実行します
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);

// エラーが発生したかどうかを確認します
if(curl_errno($ch))
{
echo 'Curl error: ' . curl_error($ch);
}

// ハンドルを閉じます
curl_close($ch);
?>

参考

  • curl_error() - 現在のセッションに関する直近のエラー文字列を返す
  • » Curl エラーコード


現在のセッションに関する直近のエラー文字列を返す

  • ≪ curl_errno
  • curl_escape ≫
  • PHP Manual
  • cURL 関数
  • 現在のセッションに関する直近のエラー文字列を返す

curl_error

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

curl_error — 現在のセッションに関する直近のエラー文字列を返す

説明

curl_error(CurlHandle $handle): string

直近の cURL 操作に関するエラーメッセージをクリアテキストで返します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

エラーメッセージ、あるいはエラーが発生しなかった場合は '' (空文字) を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_error() の例

<?php
// 存在しない場所への curl ハンドルを作成します
$ch = curl_init('http://404.php.net/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

if(curl_exec($ch) === false)
{
echo 'Curl error: ' . curl_error($ch);
}
else
{
echo 'Operation completed without any errors';
}

// ハンドルを閉じます
curl_close($ch);
?>

参考

  • curl_errno() - 直近のエラー番号を返す
  • » Curl エラーコード


指定した文字列を URL エンコードする

  • ≪ curl_error
  • curl_exec ≫
  • PHP Manual
  • cURL 関数
  • 指定した文字列を URL エンコードする

curl_escape

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_escape — 指定した文字列を URL エンコードする

説明

curl_escape(CurlHandle $handle, string $string): string|false

この関数は、指定した文字列を » RFC 3986 に従って URL エンコードします。

パラメータ

handle

curl_init() が返す cURL ハンドル。

string

エンコードする文字列。

戻り値

エスケープした文字列を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_escape() の例

<?php
// curl ハンドルを作成します
$ch = curl_init();

// GET パラメータ用の文字列をエスケープします
$location = curl_escape($ch, 'Hofbrauhaus / Munchen');
// その結果: Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen

// エスケープした文字列を使って URL を組み立てます
$url = "http://example.com/add_location.php?location={$location}";
// その結果: http://example.com/add_location.php?location=Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen

// HTTP リクエストを送信し、ハンドルを閉じます
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
curl_close($ch);
?>

参考

  • curl_unescape() - URL エンコードされた文字列をデコードする
  • urlencode() - 文字列を URL エンコードする
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • » RFC 3986


cURL セッションを実行する

  • ≪ curl_escape
  • curl_getinfo ≫
  • PHP Manual
  • cURL 関数
  • cURL セッションを実行する

curl_exec

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_exec — cURL セッションを実行する

説明

curl_exec(CurlHandle $handle): string|bool

指定した cURL セッションを実行します。

この関数は、cURL セッションを初期化し、 オプションを全て設定した後にコールする必要があります。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。 しかし、オプション CURLOPT_RETURNTRANSFER が設定されていると、 成功した場合に取得結果、失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

注意:

(404 Not found のような) エラーを示すレスポンスステータスコード は、 失敗とはみなされないことに注意してください。 curl_getinfo() 関数が、そうしたチェックを行うのに使えます。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 ウェブページの取得

<?php
// 新規 cURL リソースを作成します
$ch = curl_init();

// URL や他の適当なオプションを設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// URL を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを解放します
curl_close($ch);
?>

参考

  • curl_multi_exec() - 現在の cURL ハンドルから、サブ接続を実行する


指定した伝送に関する情報を得る

  • ≪ curl_exec
  • curl_init ≫
  • PHP Manual
  • cURL 関数
  • 指定した伝送に関する情報を得る

curl_getinfo

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

curl_getinfo — 指定した伝送に関する情報を得る

説明

curl_getinfo(CurlHandle $handle, ?int $option = null): mixed

直近の転送に関する情報を取得します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

option

これは、以下のいずれかの定数となります。

Option | 説明
CURLINFO_CAINFO | デフォルトの組み込みCA証明書のパス
CURLINFO_CAPATH | デフォルトの組み込みCAのパスの文字列
CURLINFO_EFFECTIVE_URL | 直近の有効な URL
CURLINFO_HTTP_CODE | 最後に受け取った HTTP コード。cURL 7.10.8 以降では　CURLINFO_RESPONSE_CODE　の別名になりました。
CURLINFO_FILETIME | ドキュメントを取得するのにかかった時間。 CURLOPT_FILETIME が有効な状態で用いる。 取得できなかった場合は -1
CURLINFO_TOTAL_TIME | 直近の伝送にかかった秒数
CURLINFO_NAMELOOKUP_TIME | 名前解決が完了するまでにかかった秒数
CURLINFO_CONNECT_TIME | 接続を確立するまでにかかった秒数
CURLINFO_PRETRANSFER_TIME | 開始からファイル伝送がはじまるまでにかかった秒数
CURLINFO_STARTTRANSFER_TIME | 最初のバイトの伝送がはじまるまでの秒数
CURLINFO_REDIRECT_COUNT | リダイレクト処理の回数 (CURLOPT_FOLLOWLOCATION オプションが有効な場合)
CURLINFO_REDIRECT_TIME | 伝送が始まるまでのリダイレクト処理の秒数 (CURLOPT_FOLLOWLOCATION オプションが有効な場合)
CURLINFO_REDIRECT_URL | CURLOPT_FOLLOWLOCATION オプションが無効な場合: 直近のトランザクションで見つかったリダイレクト先 URL。これを、次に手動でリクエストしなければいけません。 CURLOPT_FOLLOWLOCATION オプションが有効な場合: これは空になります。 この場合のリダイレクト先 URL は、CURLINFO_EFFECTIVE_URL となります。
CURLINFO_PRIMARY_IP | 直近の接続の IP アドレス
CURLINFO_PRIMARY_PORT | 直近の接続の接続先ポート
CURLINFO_LOCAL_IP | 直近の接続の接続元 IP アドレス
CURLINFO_LOCAL_PORT | 直近の接続の接続元ポート
CURLINFO_SIZE_UPLOAD | アップロードされたバイト数
CURLINFO_SIZE_DOWNLOAD | ダウンロードされたバイト数
CURLINFO_SPEED_DOWNLOAD | 平均のダウンロード速度
CURLINFO_SPEED_UPLOAD | 平均のアップロード速度
CURLINFO_HEADER_SIZE | 受信したヘッダのサイズ
CURLINFO_HEADER_OUT | 送信したリクエスト文字列。 これを動作させるには、curl_setopt() をコールする際に CURLINFO_HEADER_OUT オプションを使うようにしておく必要があります。
CURLINFO_REFERER | リファラヘッダ
CURLINFO_REQUEST_SIZE | 発行されたリクエストのサイズ。現在は HTTP リクエストの場合のみ
CURLINFO_RETRY_AFTER | Retry-After: ヘッダから得られる情報。有効なヘッダがない場合はゼロ。
CURLINFO_SSL_VERIFYRESULT | CURLOPT_SSL_VERIFYPEER を設定した際に要求される SSL 証明書の認証結果
CURLINFO_CONTENT_LENGTH_DOWNLOAD | ダウンロードされるサイズ。 Content-Length: フィールドの内容を取得する
CURLINFO_CONTENT_LENGTH_UPLOAD | アップロードされるサイズ。
CURLINFO_PROXY_ERROR | 直近の転送が CURLE_PROXY を返したときの (SOCKS) プロキシの詳細なエラーコード。 返される値は、 CURLPX_* のうちのひとつです。 レスポンスコードが利用できない場合、 エラーコードは CURLPX_OK になります。
CURLINFO_CONTENT_TYPE | 要求されたドキュメントの Content-Type: ヘッダ。 NULL の場合は、サーバーが適切な Content-Type: ヘッダを返さなかったことを示す。
CURLINFO_PRIVATE | この cURL ハンドルに関連づけられたプライベートデータ。 事前に curl_setopt() の CURLOPT_PRIVATE オプションで設定したもの。
CURLINFO_RESPONSE_CODE | 直近のレスポンスコード。
CURLINFO_HTTP_CONNECTCODE | CONNECT のレスポンスコード。
CURLINFO_HTTPAUTH_AVAIL | 直前のレスポンスから判断する、利用可能な認証方式のビットマスク。
CURLINFO_PROXYAUTH_AVAIL | 直前のレスポンスから判断する、プロキシ認証方式のビットマスク。
CURLINFO_OS_ERRNO | 接続に失敗したときのエラー番号。OS やシステムによって異なります。
CURLINFO_NUM_CONNECTS | curl が直前の転送を実行するために要した接続数。
CURLINFO_SSL_ENGINES | サポートする OpenSSL 暗号エンジン。
CURLINFO_COOKIELIST | すべての既知のクッキー。
CURLINFO_FTP_ENTRY_PATH | FTP サーバーのエントリパス。
CURLINFO_APPCONNECT_TIME | リモートホストとの SSL/SSH 接続／ハンドシェイク が完了するまでに要した秒数。
CURLINFO_CERTINFO | TLS 証明書チェイン。
CURLINFO_CONDITION_UNMET | 時間の条件が満たされなかったことに関する情報。
CURLINFO_RTSP_CLIENT_CSEQ | 次の RTSP クライアントの CSeq。
CURLINFO_RTSP_CSEQ_RECV | 直前に受け取った CSeq。
CURLINFO_RTSP_SERVER_CSEQ | 次の RTSP サーバーの CSeq。
CURLINFO_RTSP_SESSION_ID | RTSP セッション ID。
CURLINFO_CONTENT_LENGTH_DOWNLOAD_T | ダウンロードの content-length の値。これは Content-Length: フィールドから読み取った値です。-1 はサイズが不明であることを示します。
CURLINFO_CONTENT_LENGTH_UPLOAD_T | 指定されたアップロードのサイズ。-1 はサイズが不明であることを示します。
CURLINFO_HTTP_VERSION | 直近のHTTP接続で使われたバージョン。返される値は、CURL_HTTP_VERSION_* で定義されたうちのひとつです。バージョンが特定できない場合は、0 が返されます。
CURLINFO_PROTOCOL | 直近のHTTP接続で使われたプロトコル。返される値は、CURLPROTO_* で定義されたうちのひとつです。
CURLINFO_PROXY_SSL_VERIFYRESULT | (CURLOPT_PROXY_SSL_VERIFYPEER オプションを使って) リクエストされた証明書の検証結果です。 HTTPS プロキシを使った場合にのみ有効です。
CURLINFO_SCHEME | 直近の接続で使われたURLスキーム
CURLINFO_SIZE_DOWNLOAD_T | ダウンロードした合計のバイト数。この数値は直近の転送のみの値です。新しい転送が行われるたびにリセットされます。
CURLINFO_SIZE_UPLOAD_T | アップロードされた合計サイズ(バイト単位)
CURLINFO_SPEED_DOWNLOAD_T | ダウンロードが完了した際にcurlが計測した、平均ダウンロード速度(バイト/毎秒)
CURLINFO_SPEED_UPLOAD_T | アップロードが完了した際にcurlが計測した、平均アップロード速度(バイト/毎秒)
CURLINFO_APPCONNECT_TIME_T | リモートホストと SSL/SSH の接続/ハンドシェイクを開始してから完了するまでにかかった時間 (マイクロ秒)
CURLINFO_CONNECT_TIME_T | リモートホスト(またはプロキシ) と接続を開始して、完了するまでにかかった合計時間(マイクロ秒)
CURLINFO_FILETIME_T | 文書を取得したリモートの時間(Unixタイムスタンプ)。これは CURLINFO_FILETIME の代替であり、32ビットのタイムスタンプの範囲から外れた日付を32ビットのシステムで変数に展開することができます。
CURLINFO_NAMELOOKUP_TIME_T | 名前解決が完了するまでにかかった時間(マイクロ秒)
CURLINFO_PRETRANSFER_TIME_T | ファイルの転送が始まるまでにかかった時間(マイクロ秒)
CURLINFO_REDIRECT_TIME_T | リダイレクトのステップ全てにかかった合計時間(マイクロ秒)。これには、名前解決や接続、事前の転送や最後のトランザクションが開始されるまでの転送処理を含みます。
CURLINFO_STARTTRANSFER_TIME_T | 最初のバイトを受信するまでにかかった時間(マイクロ秒)
CURLINFO_TOTAL_TIME_T | 名前解決, TCP 接続などを含む、以前の転送にかかった合計時間(マイクロ秒)

戻り値

option を指定した場合は、その値を返します。 それ以外の場合は、以下の要素をもつ連想配列を返します (それぞれの要素が option に対応します)。 失敗した場合は false を返します。

  • "url"
  • "content_type"
  • "http_code"
  • "header_size"
  • "request_size"
  • "filetime"
  • "ssl_verify_result"
  • "redirect_count"
  • "total_time"
  • "namelookup_time"
  • "connect_time"
  • "pretransfer_time"
  • "size_upload"
  • "size_download"
  • "speed_download"
  • "speed_upload"
  • "download_content_length"
  • "upload_content_length"
  • "starttransfer_time"
  • "redirect_time"
  • "certinfo"
  • "primary_ip"
  • "primary_port"
  • "local_ip"
  • "local_port"
  • "redirect_url"
  • "request_header" (これが設定されるのは、事前に curl_setopt() をコールしたときに CURLINFO_HEADER_OUT を設定した場合のみです)
プライベートデータはこの連想配列には含まれず、CURLINFO_PRIVATE オプションで個別に取得しなければいけないことに注意しましょう。

変更履歴

バージョン | 説明
8.3.0 | CURLINFO_CAINFO と CURLINFO_CAPATH が追加されました。
8.2.0 | CURLINFO_PROXY_ERROR, CURLINFO_REFERER, CURLINFO_RETRY_AFTER が追加されました。
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | option は nullable になりました。 これより前のバージョンでは、デフォルト値は 0 でした。
7.3.0 | CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, CURLINFO_CONTENT_LENGTH_UPLOAD_T, CURLINFO_HTTP_VERSION, CURLINFO_PROTOCOL, CURLINFO_PROXY_SSL_VERIFYRESULT, CURLINFO_SCHEME, CURLINFO_SIZE_DOWNLOAD_T, CURLINFO_SIZE_UPLOAD_T, CURLINFO_SPEED_DOWNLOAD_T, CURLINFO_SPEED_UPLOAD_T, CURLINFO_APPCONNECT_TIME_T, CURLINFO_CONNECT_TIME_T, CURLINFO_FILETIME_T, CURLINFO_NAMELOOKUP_TIME_T, CURLINFO_PRETRANSFER_TIME_T, CURLINFO_REDIRECT_TIME_T, CURLINFO_STARTTRANSFER_TIME_T, CURLINFO_TOTAL_TIME_T が追加されました。

例

例1 curl_getinfo() の例

<?php
// cURL ハンドルを作成します
$ch = curl_init('http://www.example.com/');

// 実行します
curl_exec($ch);

// エラーが発生したかどうかを確認します
if (!curl_errno($ch)) {
$info = curl_getinfo($ch);
echo 'Took ', $info['total_time'], ' seconds to send a request to ', $info['url'], "\n";
}

// ハンドルを閉じます
curl_close($ch);
?>

例2 curl_getinfo() で option パラメータを使う例

<?php
// cURL ハンドルを作成します
$ch = curl_init('http://www.example.com/');

// 実行します
curl_exec($ch);

// HTTP ステータスコードを調べます
if (!curl_errno($ch)) {
switch ($http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE)) {
case 200: # OK
break;
default:
echo 'Unexpected HTTP code: ', $http_code, "\n";
}
}

// ハンドルを閉じます
curl_close($ch);
?>

注意

注意:

この関数で収集した情報を、ハンドルを再利用するとそのまま保持されます。 つまり、この関数で内部的に統計情報を上書きしない限りは以前の情報が返されるということです。


cURL セッションを初期化する

  • ≪ curl_getinfo
  • curl_multi_add_handle ≫
  • PHP Manual
  • cURL 関数
  • cURL セッションを初期化する

curl_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_init — cURL セッションを初期化する

説明

curl_init(?string $url = null): CurlHandle|false

新規セッションを初期化し、cURL ハンドルを返します。このハンドルは、関数 curl_setopt(), curl_exec(), curl_close() で使用します。

パラメータ

url

urlを指定した場合、オプション CURLOPT_URL がそのパラメータの値に設定されます。関数 curl_setopt() により、 この値をマニュアルで設定することも可能です。

注意:

open_basedir が設定されている場合、cURL で file プロトコルは使えなくなります。

戻り値

成功した場合に cURL ハンドル、エラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は CurlHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.0.0 | url は、nullable になりました。

例

例1 新しい cURL セッションを初期化し、ウェブページを取得する

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL や他の適当なオプションを設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// URL を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを解放します
curl_close($ch);
?>

参考

  • curl_close() - cURL セッションを閉じる
  • curl_multi_init() - 新規 cURL マルチハンドルを返す


cURL マルチハンドルに、通常の cURL ハンドルを追加する

  • ≪ curl_init
  • curl_multi_close ≫
  • PHP Manual
  • cURL 関数
  • cURL マルチハンドルに、通常の cURL ハンドルを追加する

curl_multi_add_handle

(PHP 5, PHP 7, PHP 8)

curl_multi_add_handle — cURL マルチハンドルに、通常の cURL ハンドルを追加する

説明

curl_multi_add_handle(CurlMultiHandle $multi_handle, CurlHandle $handle): int

handle ハンドルを、マルチハンドル multi_handle に追加します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

handle

curl_init() が返す cURL ハンドル。

戻り値

成功した場合に 0、あるいはエラーコード CURLM_XXX のいずれかを返します。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_add_handle() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
$status = curl_multi_exec($mh, $active);
if ($active) {
curl_multi_select($mh);
}
} while ($active && $status == CURLM_OK);

// すべてのハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);
?>

参考

  • curl_multi_remove_handle() - cURL ハンドルのセットからマルチハンドルを削除する
  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_init() - cURL セッションを初期化する


cURL ハンドルのセットを閉じる

  • ≪ curl_multi_add_handle
  • curl_multi_errno ≫
  • PHP Manual
  • cURL 関数
  • cURL ハンドルのセットを閉じる

curl_multi_close

(PHP 5, PHP 7, PHP 8)

curl_multi_close — cURL ハンドルのセットを閉じる

説明

curl_multi_close(CurlMultiHandle $multi_handle): void

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

cURL ハンドルのセットを閉じます。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_close() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
$status = curl_multi_exec($mh, $active);
if ($active) {
curl_multi_select($mh);
}
} while ($active && $status == CURLM_OK);

// ハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_close($ch1);
curl_multi_remove_handle($mh, $ch2);
curl_close($ch2);
curl_multi_close($mh);

?>

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_close() - cURL セッションを閉じる


直近のマルチハンドルに対するエラー番号を返す

  • ≪ curl_multi_close
  • curl_multi_exec ≫
  • PHP Manual
  • cURL 関数
  • 直近のマルチハンドルに対するエラー番号を返す

curl_multi_errno

(PHP 7 >= 7.1.0, PHP 8)

curl_multi_errno — 直近のマルチハンドルに対するエラー番号を返す

説明

curl_multi_errno(CurlMultiHandle $multi_handle): int

直近のマルチハンドルに対するエラー番号を含んだ数値を返します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

戻り値

直近のマルチハンドルに対するエラー番号を含んだ数値を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_errno() - 直近のエラー番号を返す


現在の cURL ハンドルから、サブ接続を実行する

  • ≪ curl_multi_errno
  • curl_multi_getcontent ≫
  • PHP Manual
  • cURL 関数
  • 現在の cURL ハンドルから、サブ接続を実行する

curl_multi_exec

(PHP 5, PHP 7, PHP 8)

curl_multi_exec — 現在の cURL ハンドルから、サブ接続を実行する

説明

curl_multi_exec(CurlMultiHandle $multi_handle, int &$still_running): int

スタック内の各ハンドルを処理します。 このメソッドは、ハンドルがデータの読み書きを要するかどうかにかかわらずコール可能です。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

still_running

処理が実行中かどうかを表すフラグへの参照。

戻り値

cURL 定義済み定数 で定義された cURL コードを返します。

注意:

これは、マルチスタック全体に関するエラーのみを返します。この関数が CURLM_OK を返したとしても、各転送で個別にエラーが発生している可能性があります。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_exec() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
$status = curl_multi_exec($mh, $active);
if ($active) {
// Wait a short time for more activity
curl_multi_select($mh);
}
} while ($active && $status == CURLM_OK);

// ハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_multi_select() - curl_multi 接続のアクティビティを待つ
  • curl_exec() - cURL セッションを実行する


CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す

  • ≪ curl_multi_exec
  • curl_multi_info_read ≫
  • PHP Manual
  • cURL 関数
  • CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す

curl_multi_getcontent

(PHP 5, PHP 7, PHP 8)

curl_multi_getcontent — CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す

説明

curl_multi_getcontent(CurlHandle $handle): ?string

CURLOPT_RETURNTRANSFER に何らかのハンドルが設定されている場合に、 この関数はその cURL ハンドルの内容を文字列形式で返します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

CURLOPT_RETURNTRANSFER が設定されている場合に、 cURL ハンドルの内容を返します。 CURLOPT_RETURNTRANSFER が設定されていない場合は、 null を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す


現在の転送についての情報を表示する

  • ≪ curl_multi_getcontent
  • curl_multi_init ≫
  • PHP Manual
  • cURL 関数
  • 現在の転送についての情報を表示する

curl_multi_info_read

(PHP 5, PHP 7, PHP 8)

curl_multi_info_read — 現在の転送についての情報を表示する

説明

curl_multi_info_read(CurlMultiHandle $multi_handle, int &$queued_messages = null): array|false

マルチハンドルに対して、個別の転送にメッセージ/情報が残っているかどうかを問い合わせます。 メッセージには、転送時のエラーコードや転送が完了したという情報が残っている可能性があります。

この関数を繰り返しコールすると、毎回新しい結果を返します。false が返されると、その時点でもう取得する結果がないことを意味します。 queued_messages がさす値は、 この関数をコールした後に残っているメッセージの数となります。

警告

返されたリソースがさすデータは、 curl_multi_remove_handle() をコールした後には残りません。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

queued_messages

まだキューの中に残っているメッセージの数。

戻り値

成功した場合にメッセージの連想配列、失敗した場合に false を返します。

配列の内容
キー | 値
msg | 定数 CURLMSG_DONE。その他の戻り値は現在は存在しません。
result | 定数 CURLE_* のいずれか。すべて OK なら CURLE_OK が返ります。
handle | curl が扱うハンドルの型を表すリソース。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_multi_info_read() の例

<?php

$urls = array(
"http://www.cnn.com/",
"http://www.bbc.co.uk/",
"http://www.yahoo.com/"
);

$mh = curl_multi_init();

foreach ($urls as $i => $url) {
$conn[$i] = curl_init($url);
curl_setopt($conn[$i], CURLOPT_RETURNTRANSFER, 1);
curl_multi_add_handle($mh, $conn[$i]);
}

do {
$status = curl_multi_exec($mh, $active);
if ($active) {
curl_multi_select($mh);
}
while (false !== ($info = curl_multi_info_read($mh))) {
var_dump($info);
}
} while ($active && $status == CURLM_OK);

foreach ($urls as $i => $url) {
$res[$i] = curl_multi_getcontent($conn[$i]);
curl_close($conn[$i]);
}

var_dump(curl_multi_info_read($mh));

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(5) of type (curl)
}
array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(7) of type (curl)
}
array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(6) of type (curl)
}
bool(false)

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す


新規 cURL マルチハンドルを返す

  • ≪ curl_multi_info_read
  • curl_multi_remove_handle ≫
  • PHP Manual
  • cURL 関数
  • 新規 cURL マルチハンドルを返す

curl_multi_init

(PHP 5, PHP 7, PHP 8)

curl_multi_init — 新規 cURL マルチハンドルを返す

説明

curl_multi_init(): CurlMultiHandle

複数の cURL ハンドルを非同期で実行できるようにします。

パラメータ

この関数にはパラメータはありません。

戻り値

cURL マルチハンドルを返します。

変更履歴

バージョン | 説明
8.0.0 | 成功時に、この関数は CurlMultiHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

例

例1 curl_multi_init() の例

この例は、ふたつの cURL ハンドルを作成し、それをマルチハンドルに追加して非同期で実行します。

<?php
// cURL リソースを作成します
$ch1 = curl_init();
$ch2 = curl_init();

// URL およびその他適切なオプションを設定します。
curl_setopt($ch1, CURLOPT_URL, "http://lxr.php.net/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// マルチ cURL ハンドルを作成します
$mh = curl_multi_init();

// ふたつのハンドルを追加します
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

// ハンドルを実行します
do {
$status = curl_multi_exec($mh, $active);
if ($active) {
curl_multi_select($mh);
}
} while ($active && $status == CURLM_OK);

// ハンドルを閉じます
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参考

  • curl_init() - cURL セッションを初期化する
  • curl_multi_close() - cURL ハンドルのセットを閉じる


cURL ハンドルのセットからマルチハンドルを削除する

  • ≪ curl_multi_init
  • curl_multi_select ≫
  • PHP Manual
  • cURL 関数
  • cURL ハンドルのセットからマルチハンドルを削除する

curl_multi_remove_handle

(PHP 5, PHP 7, PHP 8)

curl_multi_remove_handle — cURL ハンドルのセットからマルチハンドルを削除する

説明

curl_multi_remove_handle(CurlMultiHandle $multi_handle, CurlHandle $handle): int

指定した handle を、multi_handle から削除します。 handle が削除されてからも、このハンドルで curl_exec() を実行できます。 使用中の handle を削除する際には、 そのハンドルにかかわる進行中の転送をきちんと停止します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

handle

curl_init() が返す cURL ハンドル。

戻り値

成功した場合に 0、失敗した場合にエラーコード CURLM_XXX のいずれかを返します。 codes.

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_init() - cURL セッションを初期化する
  • curl_multi_init() - 新規 cURL マルチハンドルを返す
  • curl_multi_add_handle() - cURL マルチハンドルに、通常の cURL ハンドルを追加する


curl_multi 接続のアクティビティを待つ

  • ≪ curl_multi_remove_handle
  • curl_multi_setopt ≫
  • PHP Manual
  • cURL 関数
  • curl_multi 接続のアクティビティを待つ

curl_multi_select

(PHP 5, PHP 7, PHP 8)

curl_multi_select — curl_multi 接続のアクティビティを待つ

説明

curl_multi_select(CurlMultiHandle $multi_handle, float $timeout = 1.0): int

curl_multi 接続に関するアクティビティがあるまでブロックします。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

timeout

レスポンスを待つ秒数。

戻り値

成功した場合は、記述子セットに含まれる記述子の数を返します。 どの記述子上にもアクティビティがなかった場合は、結果が 0 になることもあります。 select に失敗した場合は -1 を返し、それ以外の失敗時は (select システムコールから) タイムアウトします。

変更履歴

バージョン | 説明
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_multi_init() - 新規 cURL マルチハンドルを返す


cURL マルチハンドル用のオプションを設定する

  • ≪ curl_multi_select
  • curl_multi_strerror ≫
  • PHP Manual
  • cURL 関数
  • cURL マルチハンドル用のオプションを設定する

curl_multi_setopt

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_multi_setopt — cURL マルチハンドル用のオプションを設定する

説明

curl_multi_setopt(CurlMultiHandle $multi_handle, int $option, mixed $value): bool

指定された cURL マルチハンドル用のオプションを設定します。

パラメータ

multi_handle

curl_multi_init() が返す cURL マルチハンドル。

option

CURLMOPT_* 定数のいずれか。

value

option に設定する値。

value には int 型の値を指定しなければいけません。 option パラメータの値によって、それぞれ次のようになります。

オプション | value の設定値
CURLMOPT_PIPELINING | 1 を渡せば有効に、そして 0 を渡せば無効になります。 マルチハンドルでのパイプライン化を有効にすると、このハンドルによる転送で、 可能な限り HTTP パイプライン化を試みます。 つまり、二番目のリクエストを追加したときに既存の接続が使える場合は、 既存の接続に「パイプ」でつなぎます。 cURL 7.43.0 以降では、この値はビットマスクですが、 2 を渡すと、既存の HTTP/2 接続上での新しい転送で、 可能な限り多重化を試みます。 3 を渡すと、パイプライン化と多重化を互いに独立して行うよう cURL に指示します。 cURL 7.62.0 以降は、パイプライン化のbitを設定しても効果はありません。
CURLMOPT_MAXCONNECTS | 同時に開く接続の最大数を指定します。これを libcurl がキャッシュします。 デフォルトのサイズは、 curl_multi_add_handle() で追加したハンドル数の四倍に収まるように拡大されます。 キャッシュがいっぱいになると、キャッシュ内で一番古い接続を閉じ、 開いている接続の数が増えないようにします。
CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE | パイプライン化のチャンク長の閾値をバイト単位で指定します。
CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE | パイプライン化のペナルティの閾値をバイト単位で指定します。
CURLMOPT_MAX_CONCURRENT_STREAMS | HTTPS/2 を使う場合に、cURL がサポートすべき並列接続ストリームの最大数。 有効な値は 1 から 2147483647 (2^31 - 1) までです。 ここで渡す値は、他のシステムリソースのプロパティに基づいてできるだけ尊重されます。 デフォルトは 100 です。
CURLMOPT_MAX_HOST_CONNECTIONS | 単一のホストへの最大接続数を指定します。
CURLMOPT_MAX_PIPELINE_LENGTH | 単一のパイプライン内での最大リクエスト数を指定します。
CURLMOPT_MAX_TOTAL_CONNECTIONS | 同時にオープンする接続の最大数を指定します。
CURLMOPT_PUSHFUNCTION

サーバープッシュを扱うために登録される callable を渡し、以下のようなシグネチャをとります:

pushfunction(resource $parent_ch, resource $pushed_ch, array $headers): int
parent_ch

親となる cURL ハンドル(クライアントが作成したリクエストの)

pushed_ch

プッシュされたリクエストのための、新しい cURL ハンドル

headers

The push promise headers. プッシュのためのプロミスヘッダ

プッシュ関数自体は、プッシュをハンドルできる場合は CURL_PUSH_OK を返し、 拒否する場合は、CURL_PUSH_DENY を返すことが想定されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.2.0 | CURLMOPT_MAX_CONCURRENT_STREAMS が追加されました。
8.0.0 | multi_handle は CurlMultiHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
7.1.0 | CURLMOPT_PUSHFUNCTION が追加されました。
7.0.7 | CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE、 CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE、 CURLMOPT_MAX_HOST_CONNECTIONS、 CURLMOPT_MAX_PIPELINE_LENGTH、 CURLMOPT_MAX_TOTAL_CONNECTIONS が追加されました。


エラーの内容を表す文字列を返す

  • ≪ curl_multi_setopt
  • curl_pause ≫
  • PHP Manual
  • cURL 関数
  • エラーの内容を表す文字列を返す

curl_multi_strerror

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_multi_strerror — エラーの内容を表す文字列を返す

説明

curl_multi_strerror(int $error_code): ?string

指定した CURLM エラーコードに対応するエラーメッセージの文字列を返します。

パラメータ

error_code

» CURLM エラーコード 定数のいずれか。

戻り値

有効なエラーコードを指定した場合は、それに対応する文字列を返します。それ以外の場合は null を返します。

例

例1 curl_multi_strerror() の例

<?php
// cURL ハンドルを作ります
$ch1 = curl_init("http://example.com/");
$ch2 = curl_init("http://php.net/");

// cURL マルチハンドルを作ります
$mh = curl_multi_init();

// マルチハンドルにハンドルを追加します
curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);

// マルチハンドルを実行します
do {
$status = curl_multi_exec($mh, $active);
if ($active) {
curl_multi_select($mh);
}
} while ($active && $status === CURLM_OK);

// エラーをチェックします
if ($status != CURLM_OK) {
// エラーメッセージを表示します
echo "ERROR!\n " . curl_multi_strerror($status);
}

?>

参考

  • curl_strerror() - エラーコードの説明を返す
  • » cURL エラーコード


接続の中断と再開をする

  • ≪ curl_multi_strerror
  • curl_reset ≫
  • PHP Manual
  • cURL 関数
  • 接続の中断と再開をする

curl_pause

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_pause — 接続の中断と再開をする

説明

curl_pause(CurlHandle $handle, int $flags): int

cURL の接続セッションを中断、または再開します。 接続セッションは、転送中であれば、読み取り書き込みどちらの方向であっても curl_setopt() で登録したコールバックからこの関数をコールすることで中断できます。

パラメータ

handle

curl_init() が返す cURL ハンドル。

flags

定数 CURLPAUSE_* のいずれか。

戻り値

エラーコードを返します (エラーがない場合は CURLE_OK を返します)。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。


libcurl セッションハンドルのすべてのオプションをリセットする

  • ≪ curl_pause
  • curl_setopt ≫
  • PHP Manual
  • cURL 関数
  • libcurl セッションハンドルのすべてのオプションをリセットする

curl_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_reset — libcurl セッションハンドルのすべてのオプションをリセットする

説明

curl_reset(CurlHandle $handle): void

指定した cURL ハンドルに設定されているすべてのオプションを初期化してデフォルト値に戻します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_reset() の例

<?php
// curl ハンドルを作ります
$ch = curl_init();

// CURLOPT_USERAGENT オプションを設定します
curl_setopt($ch, CURLOPT_USERAGENT, "My test user-agent");

// これまでに設定されたすべてのオプションを初期化します
curl_reset($ch);

// HTTP リクエストを送信します
curl_setopt($ch, CURLOPT_URL, 'http://example.com/');
curl_exec($ch); // 事前に設定した user-agent は送信されません。curl_reset で初期化されたからです

// ハンドルを閉じます
curl_close($ch);
?>

注意

注意:

curl_reset() は、curl_init() のパラメータで指定した URL も初期化します。

参考

  • curl_setopt() - cURL 転送用オプションを設定する


cURL 転送用オプションを設定する

  • ≪ curl_reset
  • curl_setopt_array ≫
  • PHP Manual
  • cURL 関数
  • cURL 転送用オプションを設定する

curl_setopt

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_setopt — cURL 転送用オプションを設定する

説明

curl_setopt(CurlHandle $handle, int $option, mixed $value): bool

指定した cURL セッションハンドルのオプションを設定します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

option

設定したい CURLOPT_XXX オプション。

value

option に設定する値。

value には、 option の以下の値に関して bool 値を指定する必要があります。

オプション | value への設定値 | 注記
CURLOPT_AUTOREFERER | true を設定すると、Location: によるリダイレクトを たどる際には自動的に Referer: フィールドをリクエストに 追加します。
CURLOPT_COOKIESESSION | true を設定すると、クッキーの "セッション" を新しく開始します。 以前のセッションで読み込まれていた "セッションクッキー" は無視するよう、 libcurl に指示します。デフォルトでは、それがセッションクッキーであるか どうかにかかわらず libcurl はすべてのクッキーを読み込んで保存します。 セッションクッキーとは、有効期限が指定されておらず "セッション" の間のみ 有効であるクッキーのことです。
CURLOPT_CERTINFO | true を設定すると、セキュアな転送時に SSL 証明書の情報を STDERR に出力します。 | cURL 7.19.1 で追加されました。 これを使うには、CURLOPT_VERBOSE を on にしておかなければなりません。
CURLOPT_CONNECT_ONLY | true を設定すると、プロキシの認証や接続の確立などをすべて行いますが、データは転送しません。 このオプションは、HTTP や SMTP そして POP3 用に実装されています。 | cURL 7.15.2 で追加されました。
CURLOPT_CRLF | true を設定すると、転送時に Unix 形式の改行を CRLF 形式に変換します。
CURLOPT_DISALLOW_USERNAME_IN_URL | ユーザー名をURLに含めてはいけない場合に true にします。 デフォルトは 0 で、ユーザー名は許可されています。 | cURL 7.61.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_DNS_SHUFFLE_ADDRESSES | 名前が解決され、ひとつ以上のIPアドレスが返された際、 ランダムな順番でそれらを利用するために、 返されたアドレスの順番をシャッフルする場合に true にします。 これによって、IPv6 アドレスの前に IPv4 アドレスが使われるなどの事象が起こるかもしれません。 | cURL 7.60.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_HAPROXYPROTOCOL | HAProxy Proxy プロトコル v1 ヘッダを接続の開始時に送信する場合に true にします。 デフォルトではこのヘッダは送信されません。 | cURL 7.60.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_SSH_COMPRESSION | ビルトインの SSH 圧縮を有効にする場合に true にします。 これはリクエストであり、命令ではありません。 つまり、圧縮されるかどうかはサーバー次第です。 | cURL 7.56.0 で追加されました。 PHP 7.3.0 以降で利用可能です。
CURLOPT_DNS_USE_GLOBAL_CACHE | true を設定すると、グローバル DNS キャッシュを利用します。 このオプションはスレッドセーフではありません。 また、PHP がスレッドセーフでない用途でビルドされている場合 (CLI, FCGI, Apache2-Prefork など) には、デフォルトで有効になっています。
CURLOPT_FAILONERROR | true を設定すると、HTTP で 400 以上のコードが返ってきた際に 処理失敗と判断します。デフォルトでは、コードの値を無視して ページの内容を取得します。
CURLOPT_SSL_FALSESTART | true にすると、TLS false start を有効にします。 | cURL 7.42.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_FILETIME | true を設定すると、ドキュメントの更新日時を取得しようと試みます。 この値を取得するには、curl_getinfo() で CURLINFO_FILETIME オプションを用います。
CURLOPT_FOLLOWLOCATION | true を設定すると、サーバーが HTTP ヘッダの一部として送ってくる "Location: " ヘッダの内容をたどります。 CURLOPT_MAXREDIRS も参照ください。
CURLOPT_FORBID_REUSE | true を設定すると、処理が終了した際に明示的に接続を切断します。 接続を再利用しません。
CURLOPT_FRESH_CONNECT | true を設定すると、キャッシュされている接続を利用せずに 新しい接続を確立します。
CURLOPT_FTP_USE_EPRT | true を設定すると、FTP のダウンロードに EPRT（および LPRT） を利用します。false の場合は EPRT・LPRT を無効にして PORT を利用します。
CURLOPT_FTP_USE_EPSV | true を設定すると、FTP 転送の際にまず EPSV コマンドの利用を 試みます。失敗した場合は PASV を利用します。false を設定すると、 EPSV を無効にします。
CURLOPT_FTP_CREATE_MISSING_DIRS | true を設定すると、FTP の操作中にパスが存在しなかったときに ディレクトリを作成します。
CURLOPT_FTPAPPEND | true を設定すると、リモートファイルを上書きせずに追記します。
CURLOPT_TCP_NODELAY | true にすると、TCP の Nagle アルゴリズムを解除します。解除すると、小さなパケットがネットワーク上を流れる回数をできるだけ減らそうと試みます。 | libcurl 7.11.2 以降と組み合わせてコンパイルしたときに利用可能です。
CURLOPT_FTPASCII | CURLOPT_TRANSFERTEXT のエイリアスです。
CURLOPT_FTPLISTONLY | true を設定すると、FTP でディレクトリ名のみ表示します。
CURLOPT_HEADER | true を設定すると、ヘッダの内容も出力します。
CURLINFO_HEADER_OUT | true を設定すると、リクエスト文字列を追跡します。 | プレフィックスが CURLINFO_ となっているのは意図的なものです。
CURLOPT_HTTP09_ALLOWED | HTTP/0.9 形式のレスポンスを許可するかどうか。libcurl 7.66.0 以降のデフォルトは false です。 それより前のバージョンのデフォルトは true でした。 | PHP 7.3.15 と 7.4.3 以降 および cURL >= 7.64.0 をビルドした場合に使用可能です。
CURLOPT_HTTPGET | true を設定すると、HTTP のリクエスト形式を GET に戻します。 GET はデフォルト設定なので、リクエスト形式が変更されている 場合にのみ必要となります。
CURLOPT_HTTPPROXYTUNNEL | true にすると、指定された HTTP プロキシを介してトンネルします。
CURLOPT_HTTP_CONTENT_DECODING | false を設定すると、生の HTTP レスポンスボディを取得します。 | libcurl >= 7.16.2 とビルドした場合に利用可能です。
CURLOPT_KEEP_SENDING_ON_ERROR | 返されたHTTPコードが300以上であっても、リクエストボディを送信し続ける場合は true にします。 デフォルトのアクションはリクエストボディの送信を止め、 ストリームまたは接続を閉じます。 手動でNTLM認証を行う場合に、このオプションは適切です。 ほとんどのアプリケーションは、このオプションは不要です。 | PHP 7.3.0 以降で、libcurl >= 7.51.0 とビルドした場合に利用可能です。
CURLOPT_MUTE | true を設定すると、cURL 関数に関連する出力を完全に抑えます。 | cURL 7.15.5 で削除されました (かわりに CURLOPT_RETURNTRANSFER が使えます)
CURLOPT_NETRC | true を設定すると、リモートサイトと接続を確立する際に用いる ユーザー名やパスワードを、~/.netrc から取得します。
CURLOPT_NOBODY | true を設定すると、出力から本文を削除します。 リクエストメソッドは HEAD となります。これを false に変更してもリクエストメソッドは GET には変わりません。
CURLOPT_NOPROGRESS true を設定すると、cURL 転送の進捗状況表示を無効にします。

注意:

PHP は、このオプションを自動的に true に設定します。 これを変更するのは、デバッグ時のみにすべきです。

CURLOPT_NOSIGNAL | true を設定すると、cURL 関数が PHP プロセスに送信するシグナルを 無視します。マルチスレッド SAPI ではデフォルトで on となっており、 そのためタイムアウトオプションもまだ利用されています。 | cURL 7.10 で追加されました。
CURLOPT_PATH_AS_IS | true にすると、ドットの連続を処理しません。 | cURL 7.42.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_PIPEWAIT | true にすると、パイプライン化/多重化を待ちます。 | cURL 7.42.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_POST | true を設定すると、HTTP POST を行います。POST は、 application/x-www-form-urlencoded 形式で 行われます。これは一般的な HTML のフォームと同じ形式です。
CURLOPT_PUT | true を設定すると、HTTP PUT を行います。PUT するファイルは CURLOPT_INFILE および CURLOPT_INFILESIZE で指定されている必要があります。
CURLOPT_RETURNTRANSFER | true を設定すると、curl_exec() の戻り値を 文字列で返します。通常はデータを直接出力します。
CURLOPT_SASL_IR | true にすると、最初のパケット内の最初のレスポンスの送信を有効にします。 | cURL 7.31.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_SSL_ENABLE_ALPN | false にすると、SSL ハンドシェイクの際の ALPN を無効にします (SSL バックエンドの libcurl がそれに対応するビルドである場合)。 これは、http2 ネゴシエーションに使えます。 | cURL 7.36.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_SSL_ENABLE_NPN | false にすると、SSL ハンドシェイクの際の NPN を無効にします (SSL バックエンドの libcurl がそれに対応するビルドである場合)。 これは、http2 ネゴシエーションに使えます。 | cURL 7.36.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_SSL_VERIFYPEER | false を設定すると、cURL はサーバー証明書の検証を行いません。 別の証明書を CURLOPT_CAINFO オプションで 指定するか、CURLOPT_CAPATH オプションで 証明ディレクトリを指定します。 | cURL 7.10 以降、デフォルト値は true です。また、 cURL 7.10 以降、デフォルトでインストールされています。
CURLOPT_SSL_VERIFYSTATUS | true にすると、証明書のステータスを検証します。 | cURL 7.41.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_PROXY_SSL_VERIFYPEER | false を設定すると、cURL がピアの証明書の検証を行わなくなります。 別の証明書を検証するには、CURLOPT_CAINFO オプションで指定するか、 CURLOPT_CAPATH を使って証明書のディレクトリを指定するやり方が使えます。 false を指定すると、ピアの証明書の検証はオプションに関係なく成功します。 | true がデフォルトです。 PHP 7.3.0 以降で、libcurl >= 7.52.0 とビルドした場合に利用可能です。
CURLOPT_SAFE_UPLOAD | この値は常に true になります。 CURLOPT_POSTFIELDS を使ってファイルをアップロードする際に、 プレフィックス @ のサポートを無効にします。 これは、@ で始まる値を安全にフィールドに渡せるということです。 CURLFile も代わりに使えます。
CURLOPT_SUPPRESS_CONNECT_HEADERS | true を設定すると、 CURLOPT_HTTPPROXYTUNNEL を使って CONNECT リクエストが生成された場合に、 ユーザーのコールバック関数 CURLOPT_HEADERFUNCTION および CURLOPT_WRITEFUNCTION では proxy CONNECT のレスポンスヘッダを抑制します。 | cURL 7.54.0 で追加されました。PHP 7.3.0 以降で使用可能です。
CURLOPT_TCP_FASTOPEN | true にすると、TCP Fast Open を有効にします。 | cURL 7.49.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_TFTP_NO_OPTIONS | true にすると、TFTP オプションリクエストを送信しません。 | cURL 7.48.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_TRANSFERTEXT | true を設定すると、FTP 転送を ASCII モードで行います。 LDAP の場合は、データを HTML ではなくプレーンテキストで取得します。 Windows システムでは STDOUT に対してバイナリモードを設定しないでください。
CURLOPT_UNRESTRICTED_AUTH | true を設定すると、（CURLOPT_FOLLOWLOCATION を利用して）場所をたどっていく際にユーザー名とパスワードを送信し続けます。 これは、たとえホスト名が変わっても続けられます。
CURLOPT_UPLOAD | true を設定すると、アップロードの準備をします。
CURLOPT_VERBOSE | true を設定すると、詳細な情報を出力します。情報は STDERR か、または CURLOPT_STDERR で指定したファイルに出力されます。

value には、 option の以下の値に関して 整数値を指定する必要があります。

オプション | value への設定値 | 注記
CURLOPT_BUFFERSIZE | 1 回の読み込みに用いるバッファのサイズ。しかしながら、必ず このバッファいっぱいまで読み込まれることを保証するものではありません。 | cURL 7.10 で追加されました。
CURLOPT_CONNECTTIMEOUT | 接続の試行を待ち続ける秒数。0 は永遠に待ち続けることを意味します。
CURLOPT_CONNECTTIMEOUT_MS | 接続の試行を待ち続けるミリ秒数。0 は永遠に待ち続けることを意味します。 システムの標準の名前解決を使うように libcurl をビルドしている場合は、 接続のタイムアウトは秒単位の精度となり、最小のタイムアウトは 1 秒となります。 | cURL 7.16.2 で追加されました。
CURLOPT_DNS_CACHE_TIMEOUT | DNS エントリをメモリ内に保持し続ける秒数。デフォルトでは 120（2 分）に設定されています。
CURLOPT_EXPECT_100_TIMEOUT_MS | Expect: 100-continue のレスポンスを待つタイムアウト。 ミリ秒で指定します。 デフォルトは1000ミリ秒です。 | cURL 7.36.0 で追加されました。PHP 7.0.7 以降で使用可能です。
CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS | Happy Eyeballs アルゴリズムで IPv6 接続を優先して開始します。 Happy Eyeballs アルゴリズムは、 デュアルスタックホストのために IPv4 と IPv6アドレス両方に接続を試みますが、 IPv6 を優先して扱い、そのタイムアウトをミリ秒単位で指定します。 デフォルトは CURL_HET_DEFAULT であり、現状は200ミリ秒です。 | cURL 7.59.0 で追加されました。PHP 7.3.0 以降で使用可能です。
CURLOPT_FTPSSLAUTH | （使用可能な場合の）FTP 認証方法。 CURLFTPAUTH_SSL（まず SSL を試す）、 CURLFTPAUTH_TLS（まず TLS を試す）あるいは CURLFTPAUTH_DEFAULT（cURL が決める）のいずれかです。 | cURL 7.12.2 で追加されました。
CURLOPT_HEADEROPT

ヘッダをどう扱うかを指定します。 次の定数のうち、一つを指定できます:

CURLHEADER_UNIFIED
CURLOPT_HTTPHEADER で指定されたヘッダが、 サーバーとプロキシ双方のリクエストに対して使われます。 このオプションが有効な場合、 CURLOPT_PROXYHEADER は効果がありません。
CURLHEADER_SEPARATE
CURLOPT_HTTPHEADER で指定されたヘッダは、 プロキシには送られず、サーバーにのみ送られます。 プロキシに送るヘッダは、 CURLOPT_PROXYHEADER を設定しなければなりません。 CONNECT でないリクエストがプロキシに送信された場合、 libcurl はサーバーとプロキシ両方にヘッダを送信することに注意してください。 CONNECT リクエストを送信する場合、 libcurl は CURLOPT_PROXYHEADER をプロキシのみに送り、 CURLOPT_HTTPHEADER をサーバーにのみ送信します。

cURL 7.42.1 以降は CURLHEADER_SEPARATE がデフォルトで、 それより前では、 CURLHEADER_UNIFIED がデフォルトでした。 		cURL 7.37.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_HTTP_VERSION | CURL_HTTP_VERSION_NONE (デフォルト。 使用するバージョンを決めるのは cURL にまかせる)、 CURL_HTTP_VERSION_1_0 (HTTP/1.0 を使用する)、 あるいは CURL_HTTP_VERSION_1_1 (HTTP/1.1 を使用する) CURL_HTTP_VERSION_2_0 (HTTP 2 の使用を試みる), CURL_HTTP_VERSION_2 (CURL_HTTP_VERSION_2_0 のエイリアス), CURL_HTTP_VERSION_2TLS (TLS (https) の場合のみ HTTP 2 の使用を試みる) または CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE (HTTP 1.1 へのアップグレードを行わず、HTTP/2 を使って TLS でないリクエストを発行する) のいずれかです。
CURLOPT_HTTPAUTH

使用する HTTP 認証方法。以下の中から選びます。 CURLAUTH_BASIC、 CURLAUTH_DIGEST、 CURLAUTH_GSSNEGOTIATE、 CURLAUTH_NTLM、 CURLAUTH_AWS_SIGV4、 CURLAUTH_ANY および CURLAUTH_ANYSAFE。

2 つ以上の方法を組み合わせるには、ビット演算子 |（or） を使用します。このような場合、cURL はサーバーがサポートしている方法を 問い合わせたうえで最適な方法を選択します。

CURLAUTH_ANY は、全てのビットを設定します。 この場合 cURL は、もっともセキュアなものを自動で選択します。

CURLAUTH_ANYSAFE は、 CURLAUTH_BASIC 以外の全てのビットを設定します。 この場合 cURL は、もっともセキュアなものを自動で選択します。

CURLOPT_INFILESIZE | ファイルをリモートサイトにアップロードする際のファイルサイズ。 このオプションを指定しても、libcurl がそれ以上のデータを送信するのは止められないことに注意しましょう。 実際に何が送信されるのかは CURLOPT_READFUNCTION に依存します。
CURLOPT_LOW_SPEED_LIMIT | 1 秒あたりのバイト数で、転送速度がこれより遅い期間が CURLOPT_LOW_SPEED_TIME 秒以上続いた場合に PHP は転送を終了します。
CURLOPT_LOW_SPEED_TIME | 転送速度が CURLOPT_LOW_SPEED_LIMIT より遅い期間がどれだけ続いた場合に転送を異常終了させるかを、 秒単位で指定します。
CURLOPT_MAIL_RCPT_ALLLOWFAILS | 送信先によっては、RCPT TO コマンドが失敗することを許可します。 | 複数の送信先にデータを送る場合、 デフォルトで cURL は RCPT TO コマンドが送信先のうちひとつでも失敗すると、SMTP の通信を中止します。 このオプションは cURL にエラーを無視し、 有効な送信先の処理は続行するように指示します。 すべての送信先の RCPT TO コマンドが失敗した場合にこのフラグが設定されていた場合は、cURL は SMTP の通信を中止し、最後に実行された RCPT TO コマンドから受け取ったエラーを返します。
CURLOPT_MAXAGE_CONN | 既存の接続を再利用して良いとみなす、アイドル時間の最大値。 デフォルトは 118 秒に設定されています。
CURLOPT_MAXFILESIZE_LARGE | ダウンロードできるファイルの最大サイズをバイト単位で設定します。 この値より大きなファイルがリクエストされた場合、 通信は開始されず、CURLE_FILESIZE_EXCEEDED が返されます。 ダウンロードが始まる前にファイルサイズが常にわかっているわけではないので、ファイルの転送量が指定された最大サイズよりも結局大きかった場合は、このオプションは意味がありません。
CURLOPT_MAXLIFETIME_CONN | 接続が作成されてから、 既存の接続を再利用してもよいと見なすまでの時間の最大値。 秒単位で指定します。 接続がキャッシュに存在し、この値より古いことがわかった場合、 転送中の通信が完了した場合に接続は一度クローズされます。 デフォルトは0です。つまり、 このオプションは無効になっており、 あらゆる接続が再利用の対象になります。
CURLOPT_MAXCONNECTS | 許可される持続的接続の最大数。もしこの値に達した場合、 オープンされている接続数が増えるのを避けるため、 キャッシュされている接続のうち一番古いものを閉じます。
CURLOPT_MAXREDIRS | HTTP のリダイレクト先を追いかける最大値。 CURLOPT_FOLLOWLOCATION とあわせて使用します。 リダイレクトループを避けるため、 デフォルト値として 20 が設定されています。 -1 を設定すると、リダイレクトループを許可します。 0 を指定すると、全てのリダイレクトを拒否します。
CURLOPT_PORT | 接続先のポート番号。
CURLOPT_POSTREDIR | CURLOPT_FOLLOWLOCATION が設定されているときに、 どの形式のリダイレクトの場合に HTTP POST メソッドを維持するのかを、 1 (301 Moved Permanently)、2 (302 Found)、4 (303 See Other) のビットマスクで指定します。 | cURL 7.19.1 で追加されました。
CURLOPT_PROTOCOLS

CURLPROTO_* の値のビットマスク。使用すると、 転送時に libcurl がどのプロトコルを使用するのかに制約を加えます。 さまざまなプロトコルに対応するよう libcurl をビルドしていた場合でも、 これによって特定の転送プロトコルのみを使用するように制限することができます。 デフォルトでは、libcurl がサポートしているすべてのプロトコルの使用を許可します。 CURLOPT_REDIR_PROTOCOLS も参照ください。

使用できるプロトコルオプションは次のとおりです。 CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_FTP, CURLPROTO_FTPS, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_TELNET, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_TFTP, CURLPROTO_MQTT, CURLPROTO_ALL

cURL 7.19.4 で追加されました。
CURLOPT_PROXYAUTH | プロキシ接続に使用する HTTP 認証の方法。 CURLOPT_HTTPAUTH で説明したのと同じオプションを 指定可能です。プロキシ認証でサポートされているのは、今のところ CURLAUTH_BASIC および CURLAUTH_NTLM のみです。 | cURL 7.10.7 で追加されました。
CURLOPT_PROXYPORT | プロキシ接続のポート番号。このポート番号は、 CURLOPT_PROXY で指定することも可能です。
CURLOPT_PROXYTYPE | CURLPROXY_HTTP（デフォルト）、 CURLPROXY_SOCKS4、 CURLPROXY_SOCKS5、 CURLPROXY_SOCKS4A あるいは CURLPROXY_SOCKS5_HOSTNAME。 | cURL 7.10 で追加されました。
CURLOPT_REDIR_PROTOCOLS | CURLPROTO_* の値のビットマスク。使用すると、 CURLOPT_FOLLOWLOCATION が有効な場合のリダイレクト時の転送に libcurl がどのプロトコルを使用するのかに制約を加えます。これによって、 リダイレクト時に特定の転送プロトコルのみを使用するように制限することができます。 デフォルトでは、libcurl がサポートしているすべてのプロトコルのうち FILE と SCP 以外のすべての使用を許可します。この挙動は 7.19.4 より前のバージョンとは異なります。7.19.4 より前のバージョンでは、 サポートするすべてのプロトコルを無条件に許可していました。 プロトコル定数の値は CURLOPT_PROTOCOLS を参照ください。 | cURL 7.19.4 で追加されました。
CURLOPT_RESUME_FROM | 転送を途中から再開する場合のバイトオフセット。
CURLOPT_SOCKS5_AUTH

利用する SOCKS5 認証方法。以下が指定できます: CURLAUTH_BASIC, CURLAUTH_GSSAPI, CURLAUTH_NONE

一つ以上の認証方法を組み合わせるために ビット演算子 | (or) が使えます。 これを使うと、cURL がどの方法をサポートしているかをポーリングし、もっとも良いものを選択します。

CURLAUTH_BASIC を指定すると、ユーザー名/パスワード による認証ができます。

CURLAUTH_GSSAPI を指定すると、GSS-API 認証ができます。

CURLAUTH_NONE を指定すると、認証は行われません。

デフォルトは CURLAUTH_BASIC|CURLAUTH_GSSAPI です。 実際のユーザー名とパスワードは CURLOPT_PROXYUSERPWD オプションを使って設定してください。

PHP 7.3.0 以降 および curl >= 7.55.0 で利用可能です。
CURLOPT_SSL_OPTIONS

SSL 関連の振る舞いのオプションを設定します。 以下に示す定数のビットマスクの組み合わせです:

CURLSSLOPT_ALLOW_BEAST
SSL3 や TLS1.0 プロトコルのセキュリティ上の欠陥を回避するあらゆる手段を使わない。
CURLSSLOPT_NO_REVOKE
証明書の失効チェックを行うSSLバックエンドについて、それを無効にする。
CURLSSLOPT_AUTO_CLIENT_CERT
クライアント証明書を認証のために自動で配置し、 サーバーからリクエストがあったときは利用します。 このオプションは Schannel (native Windows SSL library) でのみサポートされています。
CURLSSLOPT_NATIVE_CA
オペレーティングシステムのネイティブなCAストアを、 証明書の検証に用います。これは OpenSSL を Windows でビルドしたときにのみ使えます。

注意: このオプションは実験的なものであり、振る舞いが変更される可能性があります。

CURLSSLOPT_NO_PARTIALCHAIN
"部分的な" 証明書チェインを許可しません。 この点以外は、cURL のデフォルトの振る舞いをします。 このオプションは、OpenSSL でのみサポートされています。 証明書チェインがルート証明書ではなく、 中間証明書で終わっていた場合は、証明書の検証が失敗します。
CURLSSLOPT_REVOKE_BEST_EFFORT
配布ポイントがオフラインであったり、存在しない場合に、証明書の失効チェックを無視します。 このオプションは Schannel (native Windows SSL library) でのみサポートされています。

注意: CURLSSLOPT_NO_REVOKE と組み合わせて使った場合、後に設定した方が優先されます。

cURL 7.25.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_SSL_VERIFYHOST | 2 は、SSL ピア証明書の Subject Alternate Name フィールド、 または Common Name フィールドの値が、指定されたホスト名にマッチするかを調べます。 0 は、名前をチェックしません。 1 は、使うべきではありません。 本番環境では、このオプションの値は常に 2 (デフォルト値) にしておかなければなりません。 | 値 1 は、cURL 7.28.1 以降では使えなくなりました。
CURLOPT_SSLVERSION

以下のうちの、いずれかの値です。 CURL_SSLVERSION_DEFAULT, CURL_SSLVERSION_TLSv1, CURL_SSLVERSION_SSLv2, CURL_SSLVERSION_SSLv3, CURL_SSLVERSION_TLSv1_0, CURL_SSLVERSION_TLSv1_1, CURL_SSLVERSION_TLSv1_2, CURL_SSLVERSION_TLSv1_3

TLSバージョンの最大値は、定数 CURL_SSLVERSION_MAX_* で設定できます。

定数 CURL_SSLVERSION_MAX_* のうちのひとつと、 定数 CURL_SSLVERSION_* のうちのひとつを OR で設定することもできます。 CURL_SSLVERSION_MAX_DEFAULT (the maximum version supported by the library), CURL_SSLVERSION_MAX_TLSv1_0, CURL_SSLVERSION_MAX_TLSv1_1, CURL_SSLVERSION_MAX_TLSv1_2, CURL_SSLVERSION_MAX_TLSv1_3

警告

この値は何も設定せず、デフォルトに任せるのが最適です。 CURL_SSLVERSION_SSLv2 や CURL_SSLVERSION_SSLv3 を設定すると、 SSLv2 および SSLv3 の既知の脆弱性の影響を受けるため、非常に危険です。

CURLOPT_PROXY_SSL_OPTIONS

HTTPSプロキシの振る舞いを設定するオプションです。 これは以下の定数のうち、任意のものを組み合わせたビットマスクです:

CURLSSLOPT_ALLOW_BEAST
SSL3 と TLS1.0 プロトコルに存在する脆弱性を回避するための回避策を使いません。
CURLSSLOPT_NO_REVOKE
SSLバックエンドの証明書の失効チェックを無効にします。 但し、そうした振る舞いが存在した場合に限ります(curl >= 7.44.0)
CURLSSLOPT_NO_PARTIALCHAIN
"部分的な"証明書チェインを許可しません。 デフォルトでは許可されています(curl >= 7.68.0)

PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSL_VERIFYHOST | HTTPSプロキシの証明書の名前フィールドをプロキシ名と突き合わせて検証する場合 2 を設定します。 0 を設定すると、証明書でどのような名前が使われていようと、接続は成功します。 注意して使用してください! 1 は curl 7.28.0 以前ではデバッグオプションとして扱われていました。 curl 7.28.1 から 7.65.3 までは CURLE_BAD_FUNCTION_ARGUMENT が返されていました。 curl 7.66.0 以降では 1 と 2 は同じ値として扱われます。 本番環境では、このオプションの値は (デフォルトの) 2 であるべきです。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLVERSION

以下のうちのひとつが指定できます CURL_SSLVERSION_DEFAULT, CURL_SSLVERSION_TLSv1, CURL_SSLVERSION_TLSv1_0, CURL_SSLVERSION_TLSv1_1, CURL_SSLVERSION_TLSv1_2, CURL_SSLVERSION_TLSv1_3, CURL_SSLVERSION_MAX_DEFAULT, CURL_SSLVERSION_MAX_TLSv1_0, CURL_SSLVERSION_MAX_TLSv1_1, CURL_SSLVERSION_MAX_TLSv1_2, CURL_SSLVERSION_MAX_TLSv1_3, CURL_SSLVERSION_SSLv3

警告

最も良い選択は、このオプションを設定せず、 デフォルトの CURL_SSLVERSION_DEFAULT を使うことです。 このオプションは、リモートのSSLプロトコルのバージョンを見つけようとします。

PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_STREAM_WEIGHT | ストリームの重みを数値で設定します(1 から 256 までの数値) | cURL 7.46.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_TCP_KEEPALIVE | この値を 1 に設定すると、TCP keepalive のプローブが送信されます。 これらのプローブを送信する頻度と遅延時間は オペレーティングシステムがサポートしていれば CURLOPT_TCP_KEEPIDLE と CURLOPT_TCP_KEEPINTVL で制御可能です。 0 に設定すると(デフォルト)、keepalive のプローブは送信されません。 | cURL 7.25.0 で追加されました。
CURLOPT_TCP_KEEPIDLE | CURLOPT_TCP_KEEPALIVE が有効になっている場合に、 keepalive のプローブを送信する前に、接続をアイドルなままにしてオペレーティングシステムを待たせる 遅延時間を秒単位で設定します。 全てのオペレーティングシステムがこのオプションをサポートしているわけではありません。 デフォルトは 60 です。 | cURL 7.25.0 で追加されました。
CURLOPT_TCP_KEEPINTVL | CURLOPT_TCP_KEEPALIVE が有効になっている場合に、 keepalive のプローブを送信する前に、オペレーティングシステムが待つ間隔を秒単位で設定します。 全てのオペレーティングシステムがこのオプションをサポートしているわけではありません。 デフォルトは 60 です。 | cURL 7.25.0 で追加されました。
CURLOPT_TIMECONDITION | CURLOPT_TIMEVALUE の扱いを決定します。 CURLOPT_TIMEVALUE で指定した時刻以降に 変更されたページのみを返す場合は CURL_TIMECOND_IFMODSINCE を使用します。 CURLOPT_HEADER が true だと仮定すると、 ページが変更されていない場合は "304 Not Modified" ヘッダが返されます。 CURL_TIMECOND_IFUNMODSINCE は反対の意味です。 | cURL 7.46.0 より前のバージョンでは、 CURL_TIMECOND_IFMODSINCE がデフォルトでした。
CURLOPT_TIMEOUT | cURL 関数の実行にかけられる時間の最大値。
CURLOPT_TIMEOUT_MS | cURL 関数の実行にかけられる最大のミリ秒数。 システムの標準の名前解決を使うように libcurl をビルドしている場合は、 接続のタイムアウトは秒単位の精度となり、最小のタイムアウトは 1 秒となります。 | cURL 7.16.2 で追加されました。
CURLOPT_TIMEVALUE | 1970 年 1 月 1 日からの経過秒数。この値は CURLOPT_TIMECONDITION で使用されます。
CURLOPT_TIMEVALUE_LARGE | 1970年1月1日からの経過時刻を秒単位で示します。 この値は CURLOPT_TIMECONDITION によって使われます。 デフォルトは0です。 このオプションと CURLOPT_TIMEVALUE の違いは引数の型です。 'long' が 32ビット長しかないシステムでは、 2038年以降の日付を設定するためにこのオプションを使わなければいけません。 | cURL 7.59.0 で追加されました。PHP 7.3.0 以降で使用可能です。
CURLOPT_UPKEEP_INTERVAL_MS | プロトコルによっては、 "connection upkeep" (接続を維持する) 仕組みを備えているものがあります。 通常、この仕組みは接続を維持するため、既存の接続に対して少量のトラフィックを送信します。 このオプションは、接続を維持するためのトラフィックを送信する間隔を指定します。 こうした接続を維持する仕組みは、現状 HTTP/2 の接続でのみ利用できます。 この接続を維持するための間隔を超えた場合、HTTP/2 PING フレームが送信されます。デフォルトは 60 秒です。
CURLOPT_UPLOAD_BUFFERSIZE | cURL のアップロードバッファの好ましいサイズを、 バイト単位で指定します。 アップロードのバッファサイズは、デフォルトでは 64キロバイトです。 バッファサイズの最大値は、2メガバイトになっています。 バッファサイズの最小値は、16キロバイトになっています。
CURLOPT_MAX_RECV_SPEED_LARGE | ダウンロード速度 (単位は「バイト/秒」) の転送中累加平均がこの値を超えると、 転送を一時停止して、平均速度がこのパラメータの値以下に落ちるまで待ちます。 デフォルトは無制限です。 | cURL 7.15.5 で追加されました。
CURLOPT_MAX_SEND_SPEED_LARGE | アップロード速度 (単位は「バイト/秒」) の転送中累加平均がこの値を超えると、 転送を一時停止して、平均速度がこのパラメータの値以下に落ちるまで待ちます。 デフォルトは無制限です。 | cURL 7.15.5 で追加されました。
CURLOPT_SSH_AUTH_TYPES | CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD のビットマスク。 CURLSSH_AUTH_ANY にすると libcurl がいずれかひとつを選択します。 | cURL 7.16.1 で追加されました。
CURLOPT_IPRESOLVE | ホスト名の解決にどの形式の IP アドレスを使うのかを、アプリケーションが選べるようにします。 複数のバージョンの IP アドレスで解決できるホスト名のときに使うもので、指定できる値は CURL_IPRESOLVE_WHATEVER、 CURL_IPRESOLVE_V4 そして CURL_IPRESOLVE_V6 です。 デフォルトは CURL_IPRESOLVE_WHATEVER です。 | cURL 7.10.8 で追加されました。
CURLOPT_FTP_FILEMETHOD | FTP(S) サーバー上のファイルに到達するために使う方法を curl に伝えます。利用可能な値は CURLFTPMETHOD_DEFAULT、 CURLFTPMETHOD_MULTICWD、 CURLFTPMETHOD_NOCWD および CURLFTPMETHOD_SINGLECWD です。 | cURL 7.15.1 で追加されました。

value は、 option パラメータの 以下の値に関して文字列である必要があります。

オプション | value への設定値 | 注記
CURLOPT_ABSTRACT_UNIX_SOCKET | ホストにTCP接続する代わりに、抽象化されたUnixドメインソケットの使用を有効にし、 パスを指定された string に設定します。 このオプションは CURLOPT_UNIX_SOCKET_PATH と同じセマンティクスを共有しています。 これらのふたつのオプションは同じストレージを共有するので、 ハンドルごとにそれらのうちのひとつだけを設定できます。 | cURL 7.53.0 で追加されました。PHP 7.3.0 以降で利用可能です。
CURLOPT_ALTSVC | Alt-Svc キャッシュとして使うファイル名を cURL に指定します。 これは既存のキャッシュコンテンツを読み取る目的で使います。 また、通信が完了した後に書き込む可能性があります。 書き込むのは、CURLALTSVC_READONLYFILE が CURLOPT_ALTSVC_CTRL 経由で設定されていない場合に限ります。
CURLOPT_ALTSVC_CTRL | このハンドルを使って転送する際に、Alt-Svc をどう扱うかを cURL に指示するために、有効な機能をまとめてビットマスクで指定します。 cURL は Alt-Svc ヘッダを HTTPS の場合にのみ受け入れます。 origin が HTTPS で適切にホストされている場合にのみ、cURL は別のオリジンへのリクエストも完了できます。 以下のいずれかのビットを設定すると、Alt-Svc エンジンは有効になります。 オプションは以下のとおりです: CURLALTSVC_H1, CURLALTSVC_H2, CURLALTSVC_H3 および CURLALTSVC_READONLYFILE
CURLOPT_AWS_SIGV4

AWS V4 signature authentication を、HTTP(S) ヘッダで指定します。

このオプションは、CURLOPT_HTTPAUTH で設定されている他のあらゆる認証タイプを上書きします。 このメソッドは、他の認証タイプと組み合わせることができません。

CURLOPT_CAINFO | 接続先を検証するための証明書を保持するファイル名。 これは CURLOPT_SSL_VERIFYPEER を使用する場合に のみ意味を持ちます。 | 絶対パスで指定しなければならないでしょう。
CURLOPT_CAINFO_BLOB | 接続先を検証するための、ひとつ以上の証明書保持するPEMファイルの名前。 このオプションは、CURLOPT_CAINFO を上書きします。 | PHP 8.2.0 と、cURL 7.77.0 以降で利用可能です。
CURLOPT_CAPATH | 複数の証明書ファイルを保持するディレクトリ。このオプションは CURLOPT_SSL_VERIFYPEER とともに使用します。
CURLOPT_COOKIE | HTTP リクエストにおける "Cookie: " ヘッダの内容。 クッキーが複数ある場合は、セミコロンとスペースで区切られる (例 "fruit=apple; colour=red") ことに注意しましょう。
CURLOPT_COOKIEFILE | クッキーのデータを保持するファイルの名前。クッキーファイルは、 Netscape フォーマットあるいは HTTP ヘッダを単純にファイルにダンプしたものが使用可能です。 名前が空文字列の場合はクッキーを読み込みませんが、クッキーの処理は有効なままです。
CURLOPT_COOKIEJAR ハンドルのデストラクタがコールされた際に、 すべての内部クッキーを保存するファイルの名前。
警告

PHP 8.0.0 以降では、curl_close() をコールしても何もしなくなり、ハンドルを破棄しなくなりました。 ハンドルが自動で破棄される前にクッキーを書き込みたい場合、 ハンドルに対して unset() をコールします。

CURLOPT_COOKIELIST | 内部的な Cookie ストアに追加するCookie文字列(つまり、NetScape/Mozilla フォーマット または HTTP形式の Set-Cookieヘッダ)。 "ALL" の場合、メモリに保持している全てのクッキーを削除します。 "SESS" の場合、メモリに保持している全てのセッションクッキーを削除します。 "FLUSH" の場合、CURLOPT_COOKIEJAR で指定されたファイルに全ての既知の Cooie を書き込みます。 "RELOAD" の場合、CURLOPT_COOKIEFILE で指定されたファイルから全てのクッキーを読み込みます。 | cURL 7.14.1 以降で利用可能です。
CURLOPT_CUSTOMREQUEST HTTP リクエストで "GET" あるいは "HEAD" 以外に 使用するカスタムメソッド。これが有用なのは、"DELETE" やその他のあまり知られていない HTTP リクエストを実行する場合です。 使用可能な値は "GET"、 "POST"、"CONNECT" などです。 HTTP リクエストの内容をすべて指定するわけではありません。つまり、 "GET /index.html HTTP/1.0\r\n\r\n" のような 記述は間違いだということです。

注意:

使用しようとしているメソッドをサーバーがサポートしていることを 確かめるまで、これを使用しないでください。

CURLOPT_DEFAULT_PROTOCOL

URL にスキーム名がなかった場合のデフォルトのプロトコル

cURL 7.45.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_DNS_INTERFACE

DNS リゾルバがバインドするべきネットワークインターフェイス名を設定します。 これは、(アドレスではなく)インターフェイス名でなければなりません。

cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_DNS_LOCAL_IP4

リゾルバがバインドするべきローカルの IPv4 アドレスを設定します。 この値は、数値の IPv4 アドレスを文字列で含めるべきです。

cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_DNS_LOCAL_IP6

リゾルバがバインドするべきローカルの IPv6 アドレスを設定します。 この値は、数値の IPv6 アドレスを文字列で含めるべきです。

cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_EGDSOCKET | CURLOPT_RANDOM_FILE と似ていますが、 Entropy Gathering Daemon ソケットを使用してファイル名を生成する点が 違います。
CURLOPT_ENCODING | "Accept-Encoding: " ヘッダの内容。 これにより、応答のデコードを可能にします。サポートされる エンコーディングは "identity"、 "deflate" および "gzip" です。もし空文字列 "" が指定された場合、 サポートされるエンコーディングをすべて含むヘッダが送信されます。 | cURL 7.10 で追加されました。
CURLOPT_FTPPORT | FTP で "PORT" を使用するための IP アドレスを取得する際に使用される値。 "PORT" は、リモートサーバーに対してこちらが指定した IP アドレスに 接続するよう指示します。この値に設定できる内容は IP アドレス、ホスト名、 ネットワークインターフェイス名（Unix）、あるいは単に '-' を指定する ことでシステムのデフォルト IP アドレスを指定します。
CURLOPT_HSTS

HSTS (HTTP Strict Transport Security) が用いるキャッシュファイル名

CURLOPT_HSTS_CTRL

HSTS (HTTP Strict Transport Security) の振る舞いを制御します。 このハンドルを使って転送する際に、HSTS をどう扱うかを cURL に指示するために、有効な機能をまとめてビットマスクで指定します。 CURLHSTS_ENABLE を使うと、インメモリのキャッシュが有効になります。 HSTS のキャッシュファイルが指定されると、 CURLHSTS_READONLYFILE を使うことで、ファイルを読み取り専用にできます。

CURLOPT_INTERFACE | 使用するネットワークインターフェイスの名前。 インターフェイス名、IP アドレスあるいはホスト名が指定可能です。
CURLOPT_KEYPASSWD | CURLOPT_SSLKEY あるいは CURLOPT_SSH_PRIVATE_KEYFILE 秘密鍵を使うときに必須となるパスワード。 | cURL 7.16.1 で追加されました。
CURLOPT_KRB4LEVEL | KRB4（Kerberos 4）セキュリティレベル。以下の値のいずれか （セキュリティの低い順です）が指定可能です。 "clear"、 "safe"、 "confidential"、 "private"。 文字列がこれらのどれでもなかった場合は、 "private" が使用されます。このオプションを null にすると KRB4 セキュリティを無効にします。現時点では、KRB4 セキュリティは FTP 転送にのみ使用可能です。
CURLOPT_LOGIN_OPTIONS | プロトコル特有のログインオプションを設定するために使えます。 たとえば好ましい認証メカニズムが "AUTH=NTLM" とか "AUTH=*" の場合で、 CURLOPT_USERNAME オプションと組み合わせて使うべき場合です。 | cURL 7.34.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_PINNEDPUBLICKEY | ピン止めされた公開鍵を設定します。 ピン止めされた公開鍵のファイル名ファイル名を文字列として指定できます。 期待されているファイルフォーマットは "PEM" または "DER" 形式です。 文字列は、 base64 エンコードされた sha256 ハッシュで、 "sha256//" が先頭に付いたものです。これを任意の数だけ指定でき、 ";" で区切られます。 | cURL 7.39.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_POSTFIELDS | HTTP "POST" で送信するすべてのデータ。 このパラメータは 'para1=val1&para2=val2&...' のように url エンコードされた文字列形式で渡すこともできますし、 フィールド名をキー、データを値とする配列で渡すこともできます。 value が配列の場合、 Content-Type ヘッダには multipart/form-data を設定します。 ファイルは CURLFile または CURLStringFile を使って送信することが出来ます。 この場合、value は配列でなければなりません。
CURLOPT_PRIVATE | この cURL ハンドルに関連づけるデータ。ここで関連づけたデータは、 curl_getinfo() の CURLINFO_PRIVATE オプションで取得できます。 cURL はデータを一切加工しません。 cURL マルチハンドルを使う場合は一般的に、この値が cURL ハンドルを特定する一意なキーとなります。 | cURL 7.10.3 で追加されました。
CURLOPT_PRE_PROXY | CURLOPT_PROXY で指定された HTTP(S) プロキシにcurlが接続する前に、 事前に接続する preproxy を設定します。 この値には、ホスト名またはドットで区切られた数値のIPアドレスを設定します。 preproxy は SOCKS プロキシだけがなることができ、 どの socks を使うかを指定するために [scheme]:// を先頭に付けます。 数値の IPv6 アドレスは 角括弧 "[]" 内に書かなければいけません。 preproxy にから文字列を設定すると、明示的に preproxy を無効にできます。 この文字列にポート番号を設定するには、 ホスト名の最後に :[port] を追加します。 プロキシのポート番号は別のオプション CURLOPT_PROXYPORT で指定しても構いません。ポート番号を指定しない場合は、 デフォルトでは 1080 を使います。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY | リクエストを経由させる HTTP プロキシ。
CURLOPT_PROXY_SERVICE_NAME | プロキシ認証サービス名 | HTTP プロキシについては、cURL 7.43.0 で追加されました。 SOCKS5 プロキシについては、cURL 7.49.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_PROXY_CAINFO | プロキシの Certificate Authority (CA) バンドルのパスを指定します。 HTTPS プロキシを検証するための証明書をひとつ以上持つ、ファイルの名前を文字列で設定します。 このオプションは HTTPS プロキシに接続するためのものであって、 HTTPS サーバーに接続するためのものではありません。 デフォルトは、libcurl が cacert バンドルを保存していると想定しているシステムパスに設定されています。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_CAINFO_BLOB | HTTPS プロキシを検証するための証明書をひとつ以上持つ、PEMファイルの名前を設定します。 このオプションは HTTPS プロキシに接続するためのものであって、 HTTPS サーバーに接続するためのものではありません。 デフォルトは、libcurl が cacert バンドルを保存していると想定しているシステムパスに設定されています。 | PHP 8.2.0 以降および、cURL >= 7.77.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_CAPATH | HTTPSプロキシを検証するための複数のCA証明書が置かれたディレクトリ。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_CRLFILE | PEMフォーマットの CRL (Certificate Revocation List, 証明書失効リスト) を連結したファイル名を設定します。 これはSSL通信の際に行われる証明書の検証に使います。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_KEYPASSWD | CURLOPT_PROXY_SSLKEY で設定する秘密鍵で使う、 必須のパスワードを設定します。 証明書を読み込むのにパスフレーズは不要ですが、 秘密鍵を読み込むにはパスフレーズが必要です。 このオプションはHTTPSプロキシに接続するために必要です。 HTTPSサーバーに接続するためのものではありません。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_PINNEDPUBLICKEY | HTTPSプロキシ向けの pinned public key を設定します。 pinned public key のファイル名を文字列で設定できます。 ファイルフォーマットは "PEM" または "DER" です。 base64 エンコードされた sha256 ハッシュ を任意の数だけ "sha256//" の後に続けることもできます。このハッシュは ";" で区切ります。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLCERT | HTTPSプロキシに接続する時に使うクライアント証明書のフォーマット。 デフォルトは Secure Transport の場合 "P12" で、 それ以外のエンジンでは "PEM" ですが、 CURLOPT_PROXY_SSLCERTTYPE でも変更できます。 NSS や Secure transport では、 セキュリティデータベースで名付けられた証明書のニックネームも設定できます。 現在のディレクトリにあるファイルを使いたい場合は、 ニックネームとの混乱を避けるため "./" をプレフィックスとして付けてください。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLCERTTYPE | HTTPSプロキシに接続する時に使うクライアント証明書のフォーマット。 サポートされているのは "PEM" と "DER" ですが、 Secure Transport はこれらをサポートしていません。 OpenSSL (0.9.3 以降) と Secure Transport (iOS 5 以降, または OS X 10.7 以降) では PKCS#12-encoded ファイル向けに "P12" もサポートしています。デフォルトは "PEM" です。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSL_CIPHER_LIST | HTTPSプロキシと接続を確立するために使う暗号スイートの一覧。 この一覧はひとつ以上の暗号スイートの文字列がコロンで区切られており、 構文的に正しくなければなりません。 コンマやスペースも区切り文字としては有効ですが、通常はコロンが使われます。 !, - および + が演算子として使えます。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLS13_CIPHERS | TLS 1.3 接続をプロキシと確立するために使う暗号スイートの一覧。 この一覧はひとつ以上の暗号スイートの文字列がコロンで区切られており、 構文的に正しくなければなりません。 現状、このオプションはcurlが OpenSSL 1.1.1 以降とビルドされた時にだけ使われています。 OpenSSL 以外のSSLバックエンドを使っている場合は、 CURLOPT_PROXY_SSL_CIPHER_LIST オプションを使って TLS 1.3 の暗号スイートを設定できます。 | PHP 7.3.0 以降 および cURL >= 7.61.0 と OpenSSL >= 1.1.1 をビルドした場合に使用可能です。
CURLOPT_PROXY_SSLKEY | HTTPSプロキシに接続するのに使う秘密鍵のファイル名。 デフォルトのフォーマットは "PEM" で、 そのフォーマットは CURLOPT_PROXY_SSLKEYTYPE で変更できます。 (iOS と Mac OS X のみ) Secure Transport を使って curl がビルドされている場合、 このオプションは無視されます。 | PHP 7.3.0 以降 および cURL >= 7.61.0 をビルドした場合、 かつ TLS が有効な場合にのみ使用可能です。
CURLOPT_PROXY_SSLKEYTYPE | 秘密鍵のフォーマット。"PEM", "DER" および "ENG" がサポートされています。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLSAUTH_PASSWORD | CURLOPT_PROXY_TLSAUTH_TYPE オプションで指定したTLS認証メソッド で使うパスワード。 CURLOPT_PROXY_TLSAUTH_USERNAME オプションも設定する必要があります。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLSAUTH_TYPE HTTPS接続で使うTLS認証メソッド。 "SRP" がサポートされています。

注意:

TLS の Secure Remote Password (SRP) 認証は、 ローカルとリモートの双方が共通のシークレットを持っている場合に、 お互いを認証する方法を提供します。 TLS-SRP を使うためには、 CURLOPT_PROXY_TLSAUTH_USERNAME と CURLOPT_PROXY_TLSAUTH_PASSWORD オプションも設定する必要があります。

PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXY_TLSAUTH_USERNAME | CURLOPT_PROXY_TLSAUTH_TYPE オプションで指定された HTTPSプロキシのTLS認証メソッドで使うユーザー名。 CURLOPT_PROXY_TLSAUTH_PASSWORD オプションも設定する必要があります。 | PHP 7.3.0 以降 および cURL >= 7.52.0 をビルドした場合に使用可能です。
CURLOPT_PROXYUSERPWD | プロキシに接続するためのユーザー名とパスワード。 "[username]:[password]" 形式で指定します。
CURLOPT_RANDOM_FILE | 使用するファイル名を、SSL の乱数生成器を使用して作成します。
CURLOPT_RANGE | 取得するデータの範囲を "X-Y" 形式で指定します。X あるいは Y は省略可能です。 HTTP 転送では、いくつかの範囲をカンマで区切った "X-Y,N-M" のような形式もサポートしています。
CURLOPT_REFERER | HTTP リクエストで使用される "Referer: " ヘッダの内容。
CURLOPT_SASL_AUTHZID | 通信に用いる authorization identity (authzid) を指定します。 PLAIN SASL 認証メカニズムの場合にのみ適用できますが、これはオプションです。 指定されない場合は、 ユーザー名のみを指定した authentication identity(authcid) のみを、パスワードと一緒にサーバーに送信します。 サーバーは authzid が指定されない場合、authcid から authzid を導出し、内部的に用います。
CURLOPT_SERVICE_NAME | 認証サービス名 | cURL 7.43.0 で追加されました。PHP 7.0.7 以降で利用可能です。
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 | 32 桁の十六進文字列。この文字列は、リモートホストの公開鍵の MD5 チェックサムでなければなりません。 md5sum がマッチしない限り、libcurl はホストとの接続を拒否します。 このオプションは、SCP および SFTP でのみ有効です。 | cURL 7.17.1 で追加されました。
CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 | リモートホストの公開鍵を、Base64 エンコードされた SHA256 ハッシュ形式で指定します。 指定されたハッシュがリモートホストが提供するそれと一致しない場合、 通信は失敗します。
CURLOPT_SSH_PUBLIC_KEYFILE | 公開鍵のファイル名。指定しなかった場合、libcurl はデフォルトの場所を探します。デフォルトは、 環境変数 HOME が設定されていれば $HOME/.ssh/id_dsa.pub、設定されていなければ カレントディレクトリの "id_dsa.pub" です。 | cURL 7.16.1 で追加されました。
CURLOPT_SSH_PRIVATE_KEYFILE | 秘密鍵のファイル名。指定しなかった場合、libcurl はデフォルトの場所を探します。デフォルトは、 環境変数 HOME が設定されていれば $HOME/.ssh/id_dsa、設定されていなければ カレントディレクトリの "id_dsa" です。 ファイルがパスワードで保護されている場合は、パスワードを CURLOPT_KEYPASSWD に設定します。 | cURL 7.16.1 で追加されました。
CURLOPT_SSL_CIPHER_LIST | SSL で使用する暗号のリスト。例えば RC4-SHA および TLSv1 が 使用可能です。
CURLOPT_SSL_EC_CURVES | 楕円曲線暗号のアルゴリズムの一覧を、コロンで区切って指定します。 たとえば、X25519:P-521 は、 有効な楕円曲線暗号の一覧です。 このオプションは、 cURL のSSLバックエンドがそのサポートを用いるようにビルドされている場合に、 SSL ハンドシェイクで使われるクライアントの鍵交換アルゴリズムを定義します。
CURLOPT_SSLCERT | PEM フォーマットの証明書を含むファイルの名前。
CURLOPT_SSLCERTPASSWD | CURLOPT_SSLCERT 証明書を使用する際に必要なパスワード。
CURLOPT_SSLCERTTYPE | 証明書の形式。サポートされるフォーマットは "PEM"（デフォルト）、"DER" および "ENG" です。 OpenSSL 0.9.3 以降では、 "P12" (PKCS#12 でエンコードされたファイル) もサポートしています。 | cURL 7.9.3 で追加されました。
CURLOPT_SSLENGINE | CURLOPT_SSLKEY で指定した SSL 秘密鍵の 暗号化エンジンの ID 。
CURLOPT_SSLENGINE_DEFAULT | 非対称暗号化で使用する暗号化エンジンの ID 。
CURLOPT_SSLKEY | SSL 秘密鍵を含むファイルの名前。
CURLOPT_SSLKEYPASSWD CURLOPT_SSLKEY で指定した SSL 秘密鍵を 使用するために必要なパスワード。

注意:

このオプションには重要なパスワードが含まれます。PHP スクリプトを 安全な状態におくことを忘れないでください。

CURLOPT_SSLKEYTYPE | CURLOPT_SSLKEY で指定した SSL 秘密鍵の 形式。サポートされる型は以下のとおりです。 "PEM"（デフォルト）、"DER" および "ENG" 。
CURLOPT_TLS13_CIPHERS | TLS 1.3 接続を確立するために使う暗号スイートの一覧。 この一覧はひとつ以上の暗号スイートの文字列がコロンで区切られており、 構文的に正しくなければなりません。 このオプションは現状、OpenSSL 1.1.1 以降でcurlがビルドされている場合にだけ使われています。 他のSSLバックエンドを使っている場合、 CURLOPT_SSL_CIPHER_LIST を使うと TLS 1.3 の暗号スイートを設定できます。 | PHP 7.3.0 以降 および cURL >= 7.61.0 と OpenSSL >= 1.1.1 をビルドした場合に使用可能です。
CURLOPT_UNIX_SOCKET_PATH | 接続のエンドポイントとして Unixドメインソケットの利用を有効にし、 ドメインソケットのパスを与えられた string として設定します。 | cURL 7.40.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_URL | 取得する URL 。curl_init() でセッションを 初期化する際に指定することも可能です。
CURLOPT_USERAGENT | HTTP リクエストで使用される "User-Agent: " ヘッダの内容。
CURLOPT_USERNAME | 認証に使うユーザー名 | cURL 7.19.1 で追加されました。
CURLOPT_PASSWORD | 認証に使うパスワード | cURL 7.19.1 で追加されました。
CURLOPT_USERPWD | 接続に使用するユーザー名とパスワード。 "[username]:[password]" 形式で指定します。
CURLOPT_XOAUTH2_BEARER | OAuth 2.0 のアクセストークンを指定します。 | cURL 7.33.0 で追加されました。PHP 7.0.7 以降で利用可能です。

value には、 option の以下の値に関して 配列を指定する必要があります。

オプション | value への設定値 | 注記
CURLOPT_CONNECT_TO | URL で指定されたホストとポートのかわりに接続する、 特定のホストとポート。 HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT というフォーマット文字列の配列を受け入れます。 | cURL 7.49.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_HTTP200ALIASES | エラーではなく正常な応答として扱われる、HTTP 200 レスポンスの配列。 | cURL 7.10.3 で追加されました。
CURLOPT_HTTPHEADER | 設定する HTTP ヘッダフィールドの配列。 array('Content-type: text/plain', 'Content-length: 100') 形式。
CURLOPT_POSTQUOTE | FTP リクエストの実行後に、サーバー上で実行する FTP コマンドの配列。
CURLOPT_PROXYHEADER | プロキシに渡すカスタムHTTPヘッダの配列 | cURL 7.37.0 で追加されました。 PHP 7.0.7 以降で利用可能です。
CURLOPT_QUOTE | FTP リクエストの前にサーバー上で実行する FTP コマンドの配列。
CURLOPT_RESOLVE | 特定のホストとポートのペアのための、カスタムアドレスを指定します。 ホスト名、ポート、そして IP アドレスの文字列の配列です。 それぞれの要素はコロンで区切る必要があります。 以下のようなフォーマットになります: array("example.com:80:127.0.0.1") | cURL 7.21.3 で追加されました。

value はストリームリソース（例えば fopen() が作成するもの）であり、以下の option パラメータに設定します。

オプション | value に設定する内容
CURLOPT_FILE | 転送内容が書き込まれるファイル。デフォルトは STDOUT （ブラウザウィンドウ）。
CURLOPT_INFILE | アップロード時に転送内容を読み込むファイル。
CURLOPT_STDERR | STDERR の代わりにエラーを出力する場所。
CURLOPT_WRITEHEADER | 転送のヘッダ部分が書き込まれるファイル。

value には、 option の以下の値に関して 有効な関数あるいはクロージャの名前を指定する必要があります。

オプション | value への設定値 | 備考
CURLOPT_HEADERFUNCTION | 二つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目は書き込む ヘッダデータの文字列です。このコールバック関数を使用するにあたり、 ヘッダデータを書き込む処理を実装するのはあなたの役目となります。 書き込んだデータのバイト数を返します。
CURLOPT_PASSWDFUNCTION | 三つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目はパスワード プロンプトの文字列、そして 3 番目はパスワードの最大長です。 入力されたパスワードを文字列で返します。 | PHP 7.3.0 で削除されました。
CURLOPT_PROGRESSFUNCTION

五つのパラメータをとるコールバック。 最初のパラメータは cURL 利ソールで、2 番目はこの転送でダウンロードしようとしている総バイト数、 3 番目はこれまでにダウンロードしたバイト数、4 番目はこの転送でアップロードしようとしている総バイト数、 そして 5 番目はこれまでにアップロードしたバイト数です。

注意:

このコールバックが呼ばれるのは、CURLOPT_NOPROGRESS が false の場合だけです。

ゼロ以外の値を返すと、転送を強制終了できます。このとき、この転送にはエラー CURLE_ABORTED_BY_CALLBACK が設定されます。

CURLOPT_READFUNCTION | 三つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目は CURLOPT_INFILE で cURL に渡したストリームリソース、 そして最後が読み込むデータの最大量です。 コールバックは、要求したデータ量以下の長さの文字列を返さなければなりません。 一般的には、渡されたストリームリソースから読み込んだデータを返します。 EOF を伝えるには空文字列を返さなければなりません。
CURLOPT_WRITEFUNCTION | 二つのパラメータをとるコールバック。 最初のパラメータは CURL リソースで、2 番目は書き込む データの文字列です。データの保存には、 このコールバック関数を使わなければなりません。 書き込んだデータの正確なバイト数を返す必要があります。 返さなければ、エラーで転送が異常終了します。
CURLOPT_XFERINFOFUNCTION | 二つのパラメータをとるコールバック。 CURLOPT_PROGRESSFUNCTION と目的は似ていますが、 cURL の観点からはこちらの方がモダンで、好ましいオプションです。 | cURL 7.32.0 で追加されました。 PHP 8.2.0 以降で利用可能です。

その他の値

オプション | value への設定値
CURLOPT_SHARE | curl_share_init() の結果。 この cURL ハンドルに、共有ハンドルからのデータを使わせるようにします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
7.3.15, 7.4.3 | CURLOPT_HTTP09_ALLOWED が追加されました。
7.3.0 | CURLOPT_ABSTRACT_UNIX_SOCKET, CURLOPT_KEEP_SENDING_ON_ERROR, CURLOPT_PRE_PROXY, CURLOPT_PROXY_CAINFO, CURLOPT_PROXY_CAPATH, CURLOPT_PROXY_CRLFILE, CURLOPT_PROXY_KEYPASSWD, CURLOPT_PROXY_PINNEDPUBLICKEY, CURLOPT_PROXY_SSLCERT, CURLOPT_PROXY_SSLCERTTYPE, CURLOPT_PROXY_SSL_CIPHER_LIST, CURLOPT_PROXY_SSLKEY, CURLOPT_PROXY_SSLKEYTYPE, CURLOPT_PROXY_SSL_OPTIONS, CURLOPT_PROXY_SSL_VERIFYHOST, CURLOPT_PROXY_SSL_VERIFYPEER, CURLOPT_PROXY_SSLVERSION, CURLOPT_PROXY_TLSAUTH_PASSWORD, CURLOPT_PROXY_TLSAUTH_TYPE, CURLOPT_PROXY_TLSAUTH_USERNAME, CURLOPT_SOCKS5_AUTH, CURLOPT_SUPPRESS_CONNECT_HEADERS, CURLOPT_DISALLOW_USERNAME_IN_URL, CURLOPT_DNS_SHUFFLE_ADDRESSES, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, CURLOPT_HAPROXYPROTOCOL, CURLOPT_PROXY_TLS13_CIPHERS, CURLOPT_SSH_COMPRESSION, CURLOPT_TIMEVALUE_LARGE および CURLOPT_TLS13_CIPHERS が追加されました。
7.0.7 | CURL_HTTP_VERSION_2, CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE, CURL_HTTP_VERSION_2TLS, CURL_REDIR_POST_301, CURL_REDIR_POST_302, CURL_REDIR_POST_303, CURL_REDIR_POST_ALL, CURL_VERSION_KERBEROS5, CURL_VERSION_PSL, CURL_VERSION_UNIX_SOCKETS, CURLAUTH_NEGOTIATE, CURLAUTH_NTLM_WB, CURLFTP_CREATE_DIR, CURLFTP_CREATE_DIR_NONE, CURLFTP_CREATE_DIR_RETRY, CURLHEADER_SEPARATE, CURLHEADER_UNIFIED, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, CURLMOPT_MAX_HOST_CONNECTIONS, CURLMOPT_MAX_PIPELINE_LENGTH, CURLMOPT_MAX_TOTAL_CONNECTIONS, CURLOPT_CONNECT_TO, CURLOPT_DEFAULT_PROTOCOL, CURLOPT_DNS_INTERFACE, CURLOPT_DNS_LOCAL_IP4, CURLOPT_DNS_LOCAL_IP6, CURLOPT_EXPECT_100_TIMEOUT_MS, CURLOPT_HEADEROPT, CURLOPT_LOGIN_OPTIONS, CURLOPT_PATH_AS_IS, CURLOPT_PINNEDPUBLICKEY, CURLOPT_PIPEWAIT, CURLOPT_PROXY_SERVICE_NAME, CURLOPT_PROXYHEADER, CURLOPT_SASL_IR, CURLOPT_SERVICE_NAME, CURLOPT_SSL_ENABLE_ALPN, CURLOPT_SSL_ENABLE_NPN, CURLOPT_SSL_FALSESTART, CURLOPT_SSL_VERIFYSTATUS, CURLOPT_STREAM_WEIGHT, CURLOPT_TCP_FASTOPEN, CURLOPT_TFTP_NO_OPTIONS, CURLOPT_UNIX_SOCKET_PATH, CURLOPT_XOAUTH2_BEARER, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROXY_HTTP_1_0, CURLSSH_AUTH_AGENT, CURLSSLOPT_NO_REVOKE が追加されました。

例

例1 新規に cURL セッションを初期化、ウェブページを取得する

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL その他のオプションを適切に設定します
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, false);

// URL の内容を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを開放します
curl_close($ch);
?>

注意

注意:

配列を CURLOPT_POSTFIELDS に渡すと、データを multipart/form-data でエンコードします。 一方 URL エンコードされた文字列を渡すと、データを application/x-www-form-urlencoded でエンコードします。

参考

  • curl_setopt_array() - CURL 転送用の複数のオプションを設定する
  • CURLFile
  • CURLStringFile


CURL 転送用の複数のオプションを設定する

  • ≪ curl_setopt
  • curl_share_close ≫
  • PHP Manual
  • cURL 関数
  • CURL 転送用の複数のオプションを設定する

curl_setopt_array

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

curl_setopt_array — CURL 転送用の複数のオプションを設定する

説明

curl_setopt_array(CurlHandle $handle, array $options): bool

cURL セッション用の複数のオプションを設定します。 この関数が便利なのは大量の cURL オプションを設定する場合で、 何度も繰り返して curl_setopt() をコールせずにすみます。

パラメータ

handle

curl_init() が返す cURL ハンドル。

options

設定するオプションとその値を指定した配列。キーとして使用できるのは、 有効な curl_setopt() 定数か、 その定数に対応する整数値だけです。

戻り値

すべてのオプションがうまく設定できた場合に true を返します。 うまく設定できないオプションがあった時点で即時に false が返され、options 配列に含まれるそれ以降のオプションは無視されます。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 新規に CURL セッションを初期化、ウェブページを取得する

<?php
// 新しい cURL リソースを作成します
$ch = curl_init();

// URL その他のオプションを適切に設定します
$options = array(CURLOPT_URL => 'http://www.example.com/',
CURLOPT_HEADER => false
);

curl_setopt_array($ch, $options);

// URL の内容を取得し、ブラウザに渡します
curl_exec($ch);

// cURL リソースを閉じ、システムリソースを開放します
curl_close($ch);
?>

注意

注意:

curl_setopt() と同様、配列を CURLOPT_POST に渡すとデータを multipart/form-data でエンコードします。 一方 URL エンコードされた文字列を渡すと、データを application/x-www-form-urlencoded でエンコードします。

参考

  • curl_setopt() - cURL 転送用オプションを設定する


cURL 共有ハンドルを閉じる

  • ≪ curl_setopt_array
  • curl_share_errno ≫
  • PHP Manual
  • cURL 関数
  • cURL 共有ハンドルを閉じる

curl_share_close

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_share_close — cURL 共有ハンドルを閉じる

説明

curl_share_close(CurlShareHandle $share_handle): void

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

cURL 共有ハンドルを閉じ、すべてのリソースを解放します。

パラメータ

share_handle

curl_share_init() が返す cURL 共有ハンドル

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | share_handle は CurlShareHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_share_setopt() の例

この例は、cURL 共有ハンドルを作って二つの cURL ハンドルを追加し、 それぞれを実行してクッキーのデータを共有します。

<?php
// cURL 共有ハンドルを作り、クッキーのデータを共有させます
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 最初の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 最初の cURL ハンドルを実行します
curl_exec($ch1);

// 二番目の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 二番目の cURL ハンドルを実行します
// $ch1 ハンドルのすべてのクッキーを、$ch2 ハンドルと共有します
curl_exec($ch2);

// cURL 共有ハンドルを閉じます
curl_share_close($sh);

// cURL ハンドルを閉じます
curl_close($ch1);
curl_close($ch2);
?>

参考

  • curl_share_init() - curl 共有ハンドルを初期化する


直近の共有ハンドルに対するエラー番号を返す

  • ≪ curl_share_close
  • curl_share_init ≫
  • PHP Manual
  • cURL 関数
  • 直近の共有ハンドルに対するエラー番号を返す

curl_share_errno

(PHP 7 >= 7.1.0, PHP 8)

curl_share_errno — 直近の共有ハンドルに対するエラー番号を返す

説明

curl_share_errno(CurlShareHandle $share_handle): int

直近の共有ハンドルに対するエラー番号を含んだ数値を返します。

パラメータ

share_handle

curl_share_init() が返す cURL 共有ハンドル

戻り値

直近の共有ハンドルに対するエラー番号を含んだ数値を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | share_handle は CurlShareHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

参考

  • curl_errno() - 直近のエラー番号を返す


curl 共有ハンドルを初期化する

  • ≪ curl_share_errno
  • curl_share_setopt ≫
  • PHP Manual
  • cURL 関数
  • curl 共有ハンドルを初期化する

curl_share_init

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_share_init — curl 共有ハンドルを初期化する

説明

curl_share_init(): CurlShareHandle

複数の cURL ハンドルで、データを共有できるようにします。

パラメータ

この関数にはパラメータはありません。

戻り値

cURL の共有ハンドルを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、CurlShareHandle クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

例

例1 curl_share_init() の例

この例は、cURL 共有ハンドルを作って二つの cURL ハンドルを追加し、 それぞれを実行してクッキーのデータを共有します。

<?php
// cURL 共有ハンドルを作り、クッキーのデータを共有させます
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 最初の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 最初の cURL ハンドルを実行します
curl_exec($ch1);

// 二番目の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 二番目の cURL ハンドルを実行します
// $ch1 ハンドルのすべてのクッキーを、$ch2 ハンドルと共有します
curl_exec($ch2);

// cURL 共有ハンドルを閉じます
curl_share_close($sh);

// cURL ハンドルを閉じます
curl_close($ch1);
curl_close($ch2);
?>

参考

  • curl_share_setopt() - cURL 共有ハンドルのオプションを設定する
  • curl_share_close() - cURL 共有ハンドルを閉じる


cURL 共有ハンドルのオプションを設定する

  • ≪ curl_share_init
  • curl_share_strerror ≫
  • PHP Manual
  • cURL 関数
  • cURL 共有ハンドルのオプションを設定する

curl_share_setopt

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_share_setopt — cURL 共有ハンドルのオプションを設定する

説明

curl_share_setopt(CurlShareHandle $share_handle, int $option, mixed $value): bool

指定した cURL 共有ハンドルに、オプションを設定します。

パラメータ

share_handle

curl_share_init() が返す cURL 共有ハンドル

option

オプション | 説明
CURLSHOPT_SHARE | 共有させるデータの種類を指定します。
CURLSHOPT_UNSHARE | 共有させないデータの種類を指定します。

value

値 | 説明
CURL_LOCK_DATA_COOKIE | クッキーのデータを共有する。
CURL_LOCK_DATA_DNS | DNS キャッシュを共有する。cURL マルチハンドルを使うときには、 同じマルチハンドルに追加されたすべてのハンドルがデフォルトで DNS キャッシュを共有することに注意しましょう。
CURL_LOCK_DATA_SSL_SESSION | SSL セッション ID を共有し、同一サーバーへの再接続時の SSL ハンドシェイクの所要時間を削減する。 同じハンドル内では、デフォルトで SSL セッション ID が再利用されることに注意しましょう。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | share_handle は CurlShareHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_share_setopt() の例

この例は、cURL 共有ハンドルを作って二つの cURL ハンドルを追加し、 それぞれを実行してクッキーのデータを共有します。

<?php
// cURL 共有ハンドルを作り、クッキーのデータを共有させます
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 最初の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 最初の cURL ハンドルを実行します
curl_exec($ch1);

// 二番目の cURL ハンドルを作り、共有ハンドルを割り当てます
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 二番目の cURL ハンドルを実行します
// $ch1 ハンドルのすべてのクッキーを、$ch2 ハンドルと共有します
curl_exec($ch2);

// cURL 共有ハンドルを閉じます
curl_share_close($sh);

// cURL ハンドルを閉じます
curl_close($ch1);
curl_close($ch2);
?>


与えられたエラーコードを説明する文字列を返す

  • ≪ curl_share_setopt
  • curl_strerror ≫
  • PHP Manual
  • cURL 関数
  • 与えられたエラーコードを説明する文字列を返す

curl_share_strerror

(PHP 7 >= 7.1.0, PHP 8)

curl_share_strerror — 与えられたエラーコードを説明する文字列を返す

説明

curl_share_strerror(int $error_code): ?string

与えられたエラーコードを説明する、テキストのエラーメッセージを返します。

パラメータ

error_code

» cURL エラーコード のうちのひとつ。

戻り値

エラーの説明を返します。 不正なエラーコードの場合は、null を返します。

参考

  • curl_share_errno() - 直近の共有ハンドルに対するエラー番号を返す
  • curl_strerror() - エラーコードの説明を返す


エラーコードの説明を返す

  • ≪ curl_share_strerror
  • curl_unescape ≫
  • PHP Manual
  • cURL 関数
  • エラーコードの説明を返す

curl_strerror

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_strerror — エラーコードの説明を返す

説明

curl_strerror(int $error_code): ?string

指定したエラーコードに対応するエラーメッセージを返します。

パラメータ

error_code

» cURL エラーコード 定数のいずれか。

戻り値

エラーの説明を返します。無効なエラーコードを指定した場合は null を返します。

例

例1 curl_errno() の例

<?php
// URL をスペルミスした状態で curl ハンドルを作ります
$ch = curl_init("htp://example.com/");

// リクエストを送信します
curl_exec($ch);

// エラーをチェックし、エラーメッセージを表示します
if($errno = curl_errno($ch)) {
$error_message = curl_strerror($errno);
echo "cURL error ({$errno}):\n {$error_message}";
}

// ハンドルを閉じます
curl_close($ch);
?>

上の例の出力は以下となります。

cURL error (1):
 Unsupported protocol

参考

  • curl_errno() - 直近のエラー番号を返す
  • curl_error() - 現在のセッションに関する直近のエラー文字列を返す
  • » Curl エラーコード


URL エンコードされた文字列をデコードする

  • ≪ curl_strerror
  • curl_upkeep ≫
  • PHP Manual
  • cURL 関数
  • URL エンコードされた文字列をデコードする

curl_unescape

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

curl_unescape — URL エンコードされた文字列をデコードする

説明

curl_unescape(CurlHandle $handle, string $string): string|false

この関数は、URL エンコードされた文字列をデコードします。

パラメータ

handle

curl_init() が返す cURL ハンドル。

string

デコード対象の文字列。

戻り値

デコードした文字列を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | handle は CurlHandle クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

例

例1 curl_escape() の例

<?php
// curl ハンドルを作ります
$ch = curl_init('http://example.com/redirect.php');

// HTTP リクエストを送信し、リダイレクトにしたがいます
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_exec($ch);

// 直近の実効 URL を取得します
$effective_url = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);
// "http://example.com/show_location.php?loc=M%C3%BCnchen"

// URL をデコードします
$effective_url_decoded = curl_unescape($ch, $effective_url);
// "http://example.com/show_location.php?loc=Munchen"

// ハンドルを閉じます
curl_close($ch);
?>

注意

注意:

curl_unescape() は、プラス記号 (+) をスペースに変換しません。 urldecode() は、この変換をします。

参考

  • curl_escape() - 指定した文字列を URL エンコードする
  • urlencode() - 文字列を URL エンコードする
  • urldecode() - URL エンコードされた文字列をデコードする
  • rawurlencode() - RFC 3986 に基づき URL エンコードを行う
  • rawurldecode() - URL エンコードされた文字列をデコードする


接続を維持するためのチェックを行う

  • ≪ curl_unescape
  • curl_version ≫
  • PHP Manual
  • cURL 関数
  • 接続を維持するためのチェックを行う

curl_upkeep

(PHP 8 >= 8.2.0)

curl_upkeep — 接続を維持するためのチェックを行う

説明

curl_upkeep(CurlHandle $handle): bool

この関数は、libcurl >= 7.62.0 でビルドした場合に利用可能です。

プロトコルによっては、"接続を維持する" 仕組みを備えているものがあります。 通常、この仕組みは接続を維持するため、既存の接続に対して少量のトラフィックを送信します。 たとえばこうすることで、熱心なファイアウォールが接続を閉じることを防ぐことができます。

こうした接続を維持する仕組みは、現状 HTTP/2 の接続でのみ利用できます。 通常、少量のトラフィックが接続を維持するために送信されます。 HTTP/2 プロトコルは、HTTP/2 PING フレームを送信することで、接続を維持します。

パラメータ

handle

curl_init() が返す cURL ハンドル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 curl_upkeep() の例

<?php
$url = "https://example.com";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTP_VERSION,CURL_HTTP_VERSION_2_0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_UPKEEP_INTERVAL_MS, 200);
if (curl_exec($ch)) {
usleep(300);
var_dump(curl_upkeep($ch));
}
curl_close($ch);
?>

参考

  • curl_init() - cURL セッションを初期化する


cURL のバージョンを返す

  • ≪ curl_upkeep
  • CurlHandle ≫
  • PHP Manual
  • cURL 関数
  • cURL のバージョンを返す

curl_version

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

curl_version — cURL のバージョンを返す

説明

curl_version(): array|false

cURL のバージョンについての情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

以下の要素からなる連想配列を返します。

キー | 値の説明
version_number | cURL の 24 ビットのバージョン番号
version | cURL バージョン番号を表す文字列
ssl_version_number | OpenSSL の 24 ビットのバージョン番号
ssl_version | OpenSSL バージョン番号を表す文字列
libz_version | zlib バージョンを表す文字列
host | cURL をビルドしたホストについての情報
age |
features | 定数 CURL_VERSION_XXX のビットマスク
protocols | cURL がサポートするプロトコル名の配列

変更履歴

バージョン | 説明
8.0.0 | オプションの引数 age が削除されました。
7.4.0 | オプションの引数 age は推奨されなくなりました。 値を渡すことができますが、無視されます。

例

例1 curl_version() の例

この例では、cURL でどの機能が使えるのかを調べるために curl_version() の返すビットマスク 'features' を使用します。

<?php
// curl のバージョン配列を取得します
$version = curl_version();

// ビットフィールドを使用して、
// curl の機能を調べます
$bitfields = Array(
'CURL_VERSION_IPV6',
'CURL_VERSION_KERBEROS4',
'CURL_VERSION_SSL',
'CURL_VERSION_LIBZ'
);

foreach($bitfields as $feature)
{
echo $feature . ($version['features'] & constant($feature) ? ' matches' : ' does not match');
echo PHP_EOL;
}
?>


CurlHandle クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 curl リソースを置き換える完全不透明クラスです。

クラス概要

final class CurlHandle {
}


CurlMultiHandle クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 curl_multi リソースを置き換える完全不透明クラスです。

クラス概要

final class CurlMultiHandle {
}


CurlShareHandle クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 curl_share リソースを置き換える完全不透明クラスです。

クラス概要

final class CurlShareHandle {
}


CURLFile クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

はじめに

CURLOPT_POSTFIELDS でファイルのアップロードをするには、このクラスか、CURLStringFile を使わなければいけません。

CURLFile のインスタンスをアンシリアライズすることはできません。 PHP 7.4.0 以降では、そもそもシリアライズ自体も禁止されています。

クラス概要

class CURLFile {
/* プロパティ */
public string $name = "";
public string $mime = "";
public string $postname = "";
/* メソッド */
public __construct(string $filename, ?string $mime_type = null, ?string $posted_filename = null)
public getFilename(): string
public getMimeType(): string
public getPostFilename(): string
public setMimeType(string $mime_type): void
public setPostFilename(string $posted_filename): void
}

プロパティ

name

アップロードするファイルの名前。

mime

ファイルの MIME タイプ (デフォルトは application/octet-stream)。

postname

アップロードするデータの中のファイルの名前 (デフォルトは name プロパティ)。

参考

  • curl_setopt()
  • CURLStringFile

目次

  • CURLFile::__construct — CURLFile オブジェクトを作る
  • CURLFile::getFilename — ファイル名を取得する
  • CURLFile::getMimeType — MIME タイプを取得する
  • CURLFile::getPostFilename — POST 用のファイル名を取得する
  • CURLFile::setMimeType — MIME タイプを設定する
  • CURLFile::setPostFilename — POST 用のファイル名を設定する


CURLFile オブジェクトを作る

  • ≪ CURLFile
  • CURLFile::getFilename ≫
  • PHP Manual
  • CURLFile
  • CURLFile オブジェクトを作る

CURLFile::__construct

curl_file_create

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::__construct -- curl_file_create — CURLFile オブジェクトを作る

説明

オブジェクト指向型

public CURLFile::__construct(string $filename, ?string $mime_type = null, ?string $posted_filename = null)

手続き型

curl_file_create(string $filename, ?string $mime_type = null, ?string $posted_filename = null): CURLFile

CURLFile オブジェクトを作ります。これは、CURLOPT_POSTFIELDS でファイルをアップロードするときに使います。

パラメータ

filename

アップロードするファイルへのパス。

mime_type

ファイルの Mimetype。

posted_filename

アップロードデータの中で使うファイルの名前。

戻り値

CURLFile オブジェクトを返します。

変更履歴

バージョン | 説明
8.0.0 | mime_type と posted_filename は nullable になりました。 これより前のバージョンでは、デフォルト値が 0 でした。

例

例1 CURLFile::__construct() の例

オブジェクト指向型

<?php
/* http://example.com/upload.php:
<?php var_dump($_FILES); ?>
*/

// cURL ハンドルを作ります
$ch = curl_init('http://example.com/upload.php');

// CURLFile オブジェクトを作ります
$cfile = new CURLFile('cats.jpg','image/jpeg','test_name');

// POST データを設定します
$data = array('test_file' => $cfile);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

// このハンドルを実行します
curl_exec($ch);
?>

手続き型

<?php
/* http://example.com/upload.php:
<?php var_dump($_FILES); ?>
*/

// cURL ハンドルを作ります
$ch = curl_init('http://example.com/upload.php');

// CURLFile オブジェクトを作ります
$cfile = curl_file_create('cats.jpg','image/jpeg','test_name');

// POST データを設定します
$data = array('test_file' => $cfile);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

// このハンドルを実行します
curl_exec($ch);
?>

上の例の出力は以下となります。

array(1) {
  ["test_file"]=>
  array(5) {
    ["name"]=>
    string(9) "test_name"
    ["type"]=>
    string(10) "image/jpeg"
    ["tmp_name"]=>
    string(14) "/tmp/phpPC9Kbx"
    ["error"]=>
    int(0)
    ["size"]=>
    int(46334)
  }
}

例2 CURLFile::__construct() で、複数のファイルをアップロードする例

オブジェクト指向型

<?php
$request = curl_init('http://www.example.com/upload.php');
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_SAFE_UPLOAD, true);
curl_setopt($request, CURLOPT_POSTFIELDS, [
'blob[0]' => new CURLFile(realpath('first-file.jpg'), 'image/jpeg'),
'blob[1]' => new CURLFile(realpath('second-file.txt'), 'text/plain'),
'blob[2]' => new CURLFile(realpath('third-file.exe'), 'application/octet-stream'),
]);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);

echo curl_exec($request);

var_dump(curl_getinfo($request));

curl_close($request);

手続き型

<?php
// procedural
$request = curl_init('http://www.example.com/upload.php');
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_SAFE_UPLOAD, true);
curl_setopt($request, CURLOPT_POSTFIELDS, [
'blob[0]' => curl_file_create(realpath('first-file.jpg'), 'image/jpeg'),
'blob[1]' => curl_file_create(realpath('second-file.txt'), 'text/plain'),
'blob[2]' => curl_file_create(realpath('third-file.exe'), 'application/octet-stream'),
]);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);

echo curl_exec($request);

var_dump(curl_getinfo($request));

curl_close($request);

上の例の出力は以下となります。

array(26) {
  ["url"]=>
  string(31) "http://www.example.com/upload.php"
  ["content_type"]=>
  string(24) "text/html; CHARSET=shift-jis"
  ["http_code"]=>
  int(200)
  ["header_size"]=>
  int(198)
  ["request_size"]=>
  int(196)
  ["filetime"]=>
  int(-1)
  ["ssl_verify_result"]=>
  int(0)
  ["redirect_count"]=>
  int(0)
  ["total_time"]=>
  float(0.060062)
  ["namelookup_time"]=>
  float(0.028575)
  ["connect_time"]=>
  float(0.029011)
  ["pretransfer_time"]=>
  float(0.029121)
  ["size_upload"]=>
  float(3230730)
  ["size_download"]=>
  float(811)
  ["speed_download"]=>
  float(13516)
  ["speed_upload"]=>
  float(53845500)
  ["download_content_length"]=>
  float(811)
  ["upload_content_length"]=>
  float(3230730)
  ["starttransfer_time"]=>
  float(0.030355)
  ["redirect_time"]=>
  float(0)
  ["redirect_url"]=>
  string(0) ""
  ["primary_ip"]=>
  string(13) "0.0.0.0"
  ["certinfo"]=>
  array(0) {
  }
  ["primary_port"]=>
  int(80)
  ["local_ip"]=>
  string(12) "0.0.0.0"
  ["local_port"]=>
  int(34856)
}

参考

  • curl_setopt() - cURL 転送用オプションを設定する


ファイル名を取得する

  • ≪ CURLFile::__construct
  • CURLFile::getMimeType ≫
  • PHP Manual
  • CURLFile
  • ファイル名を取得する

CURLFile::getFilename

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::getFilename — ファイル名を取得する

説明

public CURLFile::getFilename(): string

パラメータ

この関数にはパラメータはありません。

戻り値

ファイル名を返します。


MIME タイプを取得する

  • ≪ CURLFile::getFilename
  • CURLFile::getPostFilename ≫
  • PHP Manual
  • CURLFile
  • MIME タイプを取得する

CURLFile::getMimeType

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::getMimeType — MIME タイプを取得する

説明

public CURLFile::getMimeType(): string

パラメータ

この関数にはパラメータはありません。

戻り値

MIME タイプを返します。


POST 用のファイル名を取得する

  • ≪ CURLFile::getMimeType
  • CURLFile::setMimeType ≫
  • PHP Manual
  • CURLFile
  • POST 用のファイル名を取得する

CURLFile::getPostFilename

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::getPostFilename — POST 用のファイル名を取得する

説明

public CURLFile::getPostFilename(): string

パラメータ

この関数にはパラメータはありません。

戻り値

POST 用のファイル名を返します。


MIME タイプを設定する

  • ≪ CURLFile::getPostFilename
  • CURLFile::setPostFilename ≫
  • PHP Manual
  • CURLFile
  • MIME タイプを設定する

CURLFile::setMimeType

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::setMimeType — MIME タイプを設定する

説明

public CURLFile::setMimeType(string $mime_type): void

パラメータ

mime_type

POST データで用いる MIME タイプ。

戻り値

値を返しません。


POST 用のファイル名を設定する

  • ≪ CURLFile::setMimeType
  • CURLStringFile ≫
  • PHP Manual
  • CURLFile
  • POST 用のファイル名を設定する

CURLFile::setPostFilename

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

CURLFile::setPostFilename — POST 用のファイル名を設定する

説明

public CURLFile::setPostFilename(string $posted_filename): void

パラメータ

posted_filename

POST データで用いるファイル名。

戻り値

値を返しません。


CURLStringFile クラス

(PHP 8 >= 8.1.0)

はじめに

CURLStringFile を使うと、 ファイルのアップロードを変数を使って直接行うことができます。 このクラスは CURLFile に似ていますが、ファイル名ではなく、 ファイルの中身を使って動作する点が異なります。 CURLOPT_POSTFIELDS でファイルのアップロードをするには、このクラスか、CURLFile を使わなければいけません。

クラス概要

class CURLStringFile {
/* プロパティ */
public string $data;
public string $postname;
public string $mime;
/* メソッド */
public __construct(string $data, string $postname, string $mime = "application/octet-stream")
}

プロパティ

data

アップロードするデータ

postname

アップロードするデータの中のファイルの名前

mime

ファイルの MIME タイプ(デフォルトは application/octet-stream)

参考

  • curl_setopt()
  • CURLFile

目次

  • CURLStringFile::__construct — CURLStringFile オブジェクトを作る


CURLStringFile オブジェクトを作る

  • ≪ CURLStringFile
  • Event ≫
  • PHP Manual
  • CURLStringFile
  • CURLStringFile オブジェクトを作る

CURLStringFile::__construct

(PHP 8 >= 8.1.0)

CURLStringFile::__construct — CURLStringFile オブジェクトを作る

説明

public CURLStringFile::__construct(string $data, string $postname, string $mime = "application/octet-stream")

CURLStringFile オブジェクトを作ります。 これは、CURLOPT_POSTFIELDS でファイルをアップロードするときに使います。

パラメータ

data

アップロードするデータ。

postname

アップロードするデータの中のファイルの名前。

mime

ファイルの MIME タイプ(デフォルトは application/octet-stream)

例

例1 CURLStringFile::__construct() の例

<?php
/* http://example.com/upload.php:
<?php
var_dump($_FILES);
var_dump(file_get_contents($_FILES['test_string']['tmp_name']));
?>
*/

// cURL ハンドルを作ります
$ch = curl_init('http://example.com/upload.php');

// CURLStringFile オブジェクトを作ります
$cstringfile = new CURLStringFile('test upload contents','test.txt','text/plain');

// POST データを設定します
$data = array('test_string' => $cstringfile);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

// このハンドルを実行します
curl_exec($ch);
?>

上の例の出力は以下となります。

array(1) {
  ["test_string"]=>
  array(5) {
    ["name"]=>
    string(8) "test.txt"
    ["type"]=>
    string(10) "text/plain"
    ["tmp_name"]=>
    string(14) "/tmp/phpTtaoCz"
    ["error"]=>
    int(0)
    ["size"]=>
    int(20)
  }
}
string(20) "test upload contents"

参考

  • curl_setopt() - cURL 転送用オプションを設定する


Event

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
  • Event flags
  • About event persistence
  • Event callbacks
  • Constructing signal events
  • Event — The Event class
    • Event::add — Makes event pending
    • Event::addSignal — のエイリアス Event::add
    • Event::addTimer — のエイリアス Event::add
    • Event::__construct — Constructs Event object
    • Event::del — Makes event non-pending
    • Event::delSignal — のエイリアス Event::del
    • Event::delTimer — のエイリアス Event::del
    • Event::free — Make event non-pending and free resources allocated for this event
    • Event::getSupportedMethods — Returns array with of the names of the methods supported in this version of Libevent
    • Event::pending — Detects whether event is pending or scheduled
    • Event::set — Re-configures event
    • Event::setPriority — Set event priority
    • Event::setTimer — Re-configures timer event
    • Event::signal — Constructs signal event object
    • Event::timer — Constructs timer event object
  • EventBase — The EventBase class
    • EventBase::__construct — Constructs EventBase object
    • EventBase::dispatch — Dispatch pending events
    • EventBase::exit — Stop dispatching events
    • EventBase::free — Free resources allocated for this event base
    • EventBase::getFeatures — Returns bitmask of features supported
    • EventBase::getMethod — Returns event method in use
    • EventBase::getTimeOfDayCached — Returns the current event base time
    • EventBase::gotExit — Checks if the event loop was told to exit
    • EventBase::gotStop — Checks if the event loop was told to exit
    • EventBase::loop — Dispatch pending events
    • EventBase::priorityInit — Sets number of priorities per event base
    • EventBase::reInit — Re-initialize event base(after a fork)
    • EventBase::stop — Tells event_base to stop dispatching events
  • EventBuffer — The EventBuffer class
    • EventBuffer::add — Append data to the end of an event buffer
    • EventBuffer::addBuffer — Move all data from a buffer provided to the current instance of EventBuffer
    • EventBuffer::appendFrom — Moves the specified number of bytes from a source buffer to the end of the current buffer
    • EventBuffer::__construct — Constructs EventBuffer object
    • EventBuffer::copyout — Copies out specified number of bytes from the front of the buffer
    • EventBuffer::drain — Removes specified number of bytes from the front of the buffer without copying it anywhere
    • EventBuffer::enableLocking — 説明
    • EventBuffer::expand — Reserves space in buffer
    • EventBuffer::freeze — Prevent calls that modify an event buffer from succeeding
    • EventBuffer::lock — Acquires a lock on buffer
    • EventBuffer::prepend — Prepend data to the front of the buffer
    • EventBuffer::prependBuffer — Moves all data from source buffer to the front of current buffer
    • EventBuffer::pullup — Linearizes data within buffer and returns it's contents as a string
    • EventBuffer::read — Read data from an evbuffer and drain the bytes read
    • EventBuffer::readFrom — Read data from a file onto the end of the buffer
    • EventBuffer::readLine — Extracts a line from the front of the buffer
    • EventBuffer::search — Scans the buffer for an occurrence of a string
    • EventBuffer::searchEol — Scans the buffer for an occurrence of an end of line
    • EventBuffer::substr — Substracts a portion of the buffer data
    • EventBuffer::unfreeze — Re-enable calls that modify an event buffer
    • EventBuffer::unlock — Releases lock acquired by EventBuffer::lock
    • EventBuffer::write — Write contents of the buffer to a file or socket
  • EventBufferEvent — The EventBufferEvent class
    • EventBufferEvent::close — Closes file descriptor associated with the current buffer event
    • EventBufferEvent::connect — Connect buffer event's file descriptor to given address or UNIX socket
    • EventBufferEvent::connectHost — Connects to a hostname with optionally asyncronous DNS resolving
    • EventBufferEvent::__construct — Constructs EventBufferEvent object
    • EventBufferEvent::createPair — Creates two buffer events connected to each other
    • EventBufferEvent::disable — Disable events read, write, or both on a buffer event
    • EventBufferEvent::enable — Enable events read, write, or both on a buffer event
    • EventBufferEvent::free — Free a buffer event
    • EventBufferEvent::getDnsErrorString — Returns string describing the last failed DNS lookup attempt
    • EventBufferEvent::getEnabled — Returns bitmask of events currently enabled on the buffer event
    • EventBufferEvent::getInput — Returns underlying input buffer associated with current buffer event
    • EventBufferEvent::getOutput — Returns underlying output buffer associated with current buffer event
    • EventBufferEvent::read — Read buffer's data
    • EventBufferEvent::readBuffer — Drains the entire contents of the input buffer and places them into buf
    • EventBufferEvent::setCallbacks — Assigns read, write and event(status) callbacks
    • EventBufferEvent::setPriority — Assign a priority to a bufferevent
    • EventBufferEvent::setTimeouts — Set the read and write timeout for a buffer event
    • EventBufferEvent::setWatermark — Adjusts read and/or write watermarks
    • EventBufferEvent::sslError — Returns most recent OpenSSL error reported on the buffer event
    • EventBufferEvent::sslFilter — Create a new SSL buffer event to send its data over another buffer event
    • EventBufferEvent::sslGetCipherInfo — Returns a textual description of the cipher
    • EventBufferEvent::sslGetCipherName — Returns the current cipher name of the SSL connection
    • EventBufferEvent::sslGetCipherVersion — Returns version of cipher used by current SSL connection
    • EventBufferEvent::sslGetProtocol — Returns the name of the protocol used for current SSL connection
    • EventBufferEvent::sslRenegotiate — Tells a bufferevent to begin SSL renegotiation
    • EventBufferEvent::sslSocket — Creates a new SSL buffer event to send its data over an SSL on a socket
    • EventBufferEvent::write — Adds data to a buffer event's output buffer
    • EventBufferEvent::writeBuffer — Adds contents of the entire buffer to a buffer event's output buffer
  • About buffer event callbacks
  • EventConfig — The EventConfig class
    • EventConfig::avoidMethod — Tells libevent to avoid specific event method
    • EventConfig::__construct — Constructs EventConfig object
    • EventConfig::requireFeatures — Enters a required event method feature that the application demands
    • EventConfig::setFlags — Sets one or more flags to configure the eventual EventBase will be initialized
    • EventConfig::setMaxDispatchInterval — Prevents priority inversion
  • EventDnsBase — The EventDnsBase class
    • EventDnsBase::addNameserverIp — Adds a nameserver to the DNS base
    • EventDnsBase::addSearch — Adds a domain to the list of search domains
    • EventDnsBase::clearSearch — Removes all current search suffixes
    • EventDnsBase::__construct — Constructs EventDnsBase object
    • EventDnsBase::countNameservers — Gets the number of configured nameservers
    • EventDnsBase::loadHosts — Loads a hosts file (in the same format as /etc/hosts) from hosts file
    • EventDnsBase::parseResolvConf — Scans the resolv.conf-formatted file
    • EventDnsBase::setOption — Set the value of a configuration option
    • EventDnsBase::setSearchNdots — Set the 'ndots' parameter for searches
  • EventHttp — The EventHttp class
    • EventHttp::accept — Makes an HTTP server accept connections on the specified socket stream or resource
    • EventHttp::addServerAlias — Adds a server alias to the HTTP server object
    • EventHttp::bind — Binds an HTTP server on the specified address and port
    • EventHttp::__construct — Constructs EventHttp object (the HTTP server)
    • EventHttp::removeServerAlias — Removes server alias
    • EventHttp::setAllowedMethods — Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks
    • EventHttp::setCallback — Sets a callback for specified URI
    • EventHttp::setDefaultCallback — Sets default callback to handle requests that are not caught by specific callbacks
    • EventHttp::setMaxBodySize — Sets maximum request body size
    • EventHttp::setMaxHeadersSize — Sets maximum HTTP header size
    • EventHttp::setTimeout — Sets the timeout for an HTTP request
  • EventHttpConnection — The EventHttpConnection class
    • EventHttpConnection::__construct — Constructs EventHttpConnection object
    • EventHttpConnection::getBase — Returns event base associated with the connection
    • EventHttpConnection::getPeer — Gets the remote address and port associated with the connection
    • EventHttpConnection::makeRequest — Makes an HTTP request over the specified connection
    • EventHttpConnection::setCloseCallback — Set callback for connection close
    • EventHttpConnection::setLocalAddress — Sets the IP address from which HTTP connections are made
    • EventHttpConnection::setLocalPort — Sets the local port from which connections are made
    • EventHttpConnection::setMaxBodySize — Sets maximum body size for the connection
    • EventHttpConnection::setMaxHeadersSize — Sets maximum header size
    • EventHttpConnection::setRetries — Sets the retry limit for the connection
    • EventHttpConnection::setTimeout — Sets the timeout for the connection
  • EventHttpRequest — The EventHttpRequest class
    • EventHttpRequest::addHeader — Adds an HTTP header to the headers of the request
    • EventHttpRequest::cancel — Cancels a pending HTTP request
    • EventHttpRequest::clearHeaders — Removes all output headers from the header list of the request
    • EventHttpRequest::closeConnection — Closes associated HTTP connection
    • EventHttpRequest::__construct — Constructs EventHttpRequest object
    • EventHttpRequest::findHeader — Finds the value belonging a header
    • EventHttpRequest::free — Frees the object and removes associated events
    • EventHttpRequest::getBufferEvent — Returns EventBufferEvent object
    • EventHttpRequest::getCommand — Returns the request command(method)
    • EventHttpRequest::getConnection — Returns EventHttpConnection object
    • EventHttpRequest::getHost — Returns the request host
    • EventHttpRequest::getInputBuffer — Returns the input buffer
    • EventHttpRequest::getInputHeaders — Returns associative array of the input headers
    • EventHttpRequest::getOutputBuffer — Returns the output buffer of the request
    • EventHttpRequest::getOutputHeaders — Returns associative array of the output headers
    • EventHttpRequest::getResponseCode — Returns the response code
    • EventHttpRequest::getUri — Returns the request URI
    • EventHttpRequest::removeHeader — Removes an HTTP header from the headers of the request
    • EventHttpRequest::sendError — Send an HTML error message to the client
    • EventHttpRequest::sendReply — Send an HTML reply to the client
    • EventHttpRequest::sendReplyChunk — Send another data chunk as part of an ongoing chunked reply
    • EventHttpRequest::sendReplyEnd — Complete a chunked reply, freeing the request as appropriate
    • EventHttpRequest::sendReplyStart — Initiate a chunked reply
  • EventListener — The EventListener class
    • EventListener::__construct — Creates new connection listener associated with an event base
    • EventListener::disable — Disables an event connect listener object
    • EventListener::enable — Enables an event connect listener object
    • EventListener::getBase — Returns event base associated with the event listener
    • EventListener::getSocketName — Retreives the current address to which the listener's socket is bound
    • EventListener::setCallback — The setCallback purpose
    • EventListener::setErrorCallback — Set event listener's error callback
  • EventSslContext — The EventSslContext class
    • EventSslContext::__construct — Constructs an OpenSSL context for use with Event classes
  • EventUtil — The EventUtil class
    • EventUtil::__construct — The abstract constructor
    • EventUtil::getLastSocketErrno — Returns the most recent socket error number
    • EventUtil::getLastSocketError — Returns the most recent socket error
    • EventUtil::getSocketFd — Returns numeric file descriptor of a socket, or stream
    • EventUtil::getSocketName — Retreives the current address to which the socket is bound
    • EventUtil::setSocketOption — Sets socket options
    • EventUtil::sslRandPoll — Generates entropy by means of OpenSSL's RAND_poll()
  • EventException — The EventException class


はじめに

This is an extension to efficiently schedule I/O, time and signal based events using the best I/O notification mechanism available for specific platform. This is a port of libevent to the PHP infrastructure.

注意:

Note, Windows support introduced in event-1.9.0 .

Version 1.0.0 introduces new object-oriented API (breaking backwards compatibility), and support of libevent 2+ including HTTP, DNS, OpenSSL and the event listener.

注意:

Note, event-1.0.0 and greater is not compatible with previous versions.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Event
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

This extension requires » libevent library. Most modern distributions provide packages for libevent.

OpenSSL features require » OpenSSL library.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/event .


例

例1 Simple HTTP client

<?php
// Read callback
function readcb($bev, $base) {
//$input = $bev->input; //$bev->getInput();

//$pos = $input->search("TTP");
$pos = $bev->input->search("TTP");

while (($n = $bev->input->remove($buf, 1024)) > 0) {
echo $buf;
}
}

// Event callback
function eventcb($bev, $events, $base) {
if ($events & EventBufferEvent::CONNECTED) {
echo "Connected.\n";
} elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
if ($events & EventBufferEvent::ERROR) {
echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
}

echo "Closing\n";
$base->exit();
exit("Done\n");
}
}

if ($argc != 3) {
echo <<<EOS
Trivial HTTP 0.x client
Syntax: php {$argv[0]} [hostname] [resource]
Example: php {$argv[0]} www.google.com /

EOS;
exit();
}

$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // We'll use async DNS resolving
if (!$dns_base) {
exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
"readcb", /* writecb */ NULL, "eventcb"
);
if (!$bev) {
exit("Failed creating bufferevent socket\n");
}

//$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

$output = $bev->output; //$bev->getOutput();
if (!$output->add(
"GET {$argv[2]} HTTP/1.0\r\n".
"Host: {$argv[1]}\r\n".
"Connection: Close\r\n\r\n"
)) {
exit("Failed adding request to output buffer\n");
}

if (!$bev->connectHost($dns_base, $argv[1], 80, EventUtil::AF_UNSPEC)) {
exit("Can't connect to host {$argv[1]}\n");
}

$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Connected.
HTTP/1.1 301 Moved Permanently
Date: Fri, 01 Mar 2013 18:47:48 GMT
Location: http://www.google.co.uk/
Content-Type: text/html; CHARSET=shift-jis
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
Age: 133438
Expires: Sat, 30 Mar 2013 05:39:28 GMT
Connection: close

<HTML><HEAD><meta http-equiv="content-type" content="text/html;CHARSET=shift-jis">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.co.uk/">here</A>.
</BODY></HTML>
Closing
Done

例2 HTTP client using asynchronous DNS resolver

<?php
/*
* 1. Connect to 127.0.0.1 at port 80
* by means of EventBufferEvent::connect().
*
* 2. Request /index.cphp via HTTP/1.0
* using the output buffer.
*
* 3. Asyncronously read the response and print it to stdout.
*/

// Read callback
function readcb($bev, $base) {
$input = $bev->getInput();

while (($n = $input->remove($buf, 1024)) > 0) {
echo $buf;
}
}

// Event callback
function eventcb($bev, $events, $base) {
if ($events & EventBufferEvent::CONNECTED) {
echo "Connected.\n";
} elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
if ($events & EventBufferEvent::ERROR) {
echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
}

echo "Closing\n";
$base->exit();
exit("Done\n");
}
}

$base = new EventBase();

echo "step 1\n";
$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS);
if (!$bev) {
exit("Failed creating bufferevent socket\n");
}

echo "step 2\n";
$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

echo "step 3\n";
// Send request
$output = $bev->getOutput();
if (!$output->add(
"GET /index.cphp HTTP/1.0\r\n".
"Connection: Close\r\n\r\n"
)) {
exit("Failed adding request to output buffer\n");
}

/* Connect to the host syncronously.
We know the IP, and don't need to resolve DNS. */
if (!$bev->connect("127.0.0.1:80")) {
exit("Can't connect to host\n");
}

// Dispatch pending events
$base->dispatch();
?>

例3 Echo server

<?php
/*
* Simple echo server based on libevent's connection listener.
*
* Usage:
* 1) In one terminal window run:
*
* $ php listener.php 9881
*
* 2) In another terminal window open up connection, e.g.:
*
* $ nc 127.0.0.1 9881
*
* 3) start typing. The server should repeat the input.
*/

class MyListenerConnection {
private $bev, $base;

public function __destruct() {
$this->bev->free();
}

public function __construct($base, $fd) {
$this->base = $base;

$this->bev = new EventBufferEvent($base, $fd, EventBufferEvent::OPT_CLOSE_ON_FREE);

$this->bev->setCallbacks(array($this, "echoReadCallback"), NULL,
array($this, "echoEventCallback"), NULL);

if (!$this->bev->enable(Event::READ)) {
echo "Failed to enable READ\n";
return;
}
}

public function echoReadCallback($bev, $ctx) {
// Copy all the data from the input buffer to the output buffer

// Variant #1
$bev->output->addBuffer($bev->input);

/* Variant #2 */
/*
$input = $bev->getInput();
$output = $bev->getOutput();
$output->addBuffer($input);
*/
}

public function echoEventCallback($bev, $events, $ctx) {
if ($events & EventBufferEvent::ERROR) {
echo "Error from bufferevent\n";
}

if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
//$bev->free();
$this->__destruct();
}
}
}

class MyListener {
public $base,
$listener,
$socket;
private $conn = array();

public function __destruct() {
foreach ($this->conn as &$c) $c = NULL;
}

public function __construct($port) {
$this->base = new EventBase();
if (!$this->base) {
echo "Couldn't open event base";
exit(1);
}

// Variant #1
/*
$this->socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if (!socket_bind($this->socket, '0.0.0.0', $port)) {
echo "Unable to bind socket\n";
exit(1);
}
$this->listener = new EventListener($this->base,
array($this, "acceptConnCallback"), $this->base,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
-1, $this->socket);
*/

// Variant #2
$this->listener = new EventListener($this->base,
array($this, "acceptConnCallback"), $this->base,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE, -1,
"0.0.0.0:$port");

if (!$this->listener) {
echo "Couldn't create listener";
exit(1);
}

$this->listener->setErrorCallback(array($this, "accept_error_cb"));
}

public function dispatch() {
$this->base->dispatch();
}

// This callback is invoked when there is data to read on $bev
public function acceptConnCallback($listener, $fd, $address, $ctx) {
// We got a new connection! Set up a bufferevent for it. */
$base = $this->base;
$this->conn[] = new MyListenerConnection($base, $fd);
}

public function accept_error_cb($listener, $ctx) {
$base = $this->base;

fprintf(STDERR, "Got an error %d (%s) on the listener. "
."Shutting down.\n",
EventUtil::getLastSocketErrno(),
EventUtil::getLastSocketError());

$base->exit(NULL);
}
}

$port = 9808;

if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}

$l = new MyListener($port);
$l->dispatch();
?>

例4 SSL echo server

<?php
/*
* SSL echo server
*
* To test:
* 1) Run:
* $ php examples/ssl-echo-server/server.php 9998
*
* 2) in another terminal window run:
* $ socat - SSL:127.0.0.1:9998,verify=1,cafile=examples/ssl-echo-server/cert.pem
*/

class MySslEchoServer {
public $port,
$base,
$bev,
$listener,
$ctx;

function __construct ($port, $host = "127.0.0.1") {
$this->port = $port;
$this->ctx = $this->init_ssl();
if (!$this->ctx) {
exit("Failed creating SSL context\n");
}

$this->base = new EventBase();
if (!$this->base) {
exit("Couldn't open event base\n");
}

$this->listener = new EventListener($this->base,
array($this, "ssl_accept_cb"), $this->ctx,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
-1, "$host:$port");
if (!$this->listener) {
exit("Couldn't create listener\n");
}

$this->listener->setErrorCallback(array($this, "accept_error_cb"));
}
function dispatch() {
$this->base->dispatch();
}

// This callback is invoked when there is data to read on $bev.
function ssl_read_cb($bev, $ctx) {
$in = $bev->input; //$bev->getInput();

printf("Received %zu bytes\n", $in->length);
printf("----- data ----\n");
printf("%ld:\t%s\n", (int) $in->length, $in->pullup(-1));

$bev->writeBuffer($in);
}

// This callback is invoked when some even occurs on the event listener,
// e.g. connection closed, or an error occurred
function ssl_event_cb($bev, $events, $ctx) {
if ($events & EventBufferEvent::ERROR) {
// Fetch errors from the SSL error stack
while ($err = $bev->sslError()) {
fprintf(STDERR, "Bufferevent error %s.\n", $err);
}
}

if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
$bev->free();
}
}

// This callback is invoked when a client accepts new connection
function ssl_accept_cb($listener, $fd, $address, $ctx) {
// We got a new connection! Set up a bufferevent for it.
$this->bev = EventBufferEvent::sslSocket($this->base, $fd, $this->ctx,
EventBufferEvent::SSL_ACCEPTING, EventBufferEvent::OPT_CLOSE_ON_FREE);

if (!$this->bev) {
echo "Failed creating ssl buffer\n";
$this->base->exit(NULL);
exit(1);
}

$this->bev->enable(Event::READ);
$this->bev->setCallbacks(array($this, "ssl_read_cb"), NULL,
array($this, "ssl_event_cb"), NULL);
}

// This callback is invoked when we failed to setup new connection for a client
function accept_error_cb($listener, $ctx) {
fprintf(STDERR, "Got an error %d (%s) on the listener. "
."Shutting down.\n",
EventUtil::getLastSocketErrno(),
EventUtil::getLastSocketError());

$this->base->exit(NULL);
}

// Initialize SSL structures, create an EventSslContext
// Optionally create self-signed certificates
function init_ssl() {
// We *must* have entropy. Otherwise there's no point to crypto.
if (!EventUtil::sslRandPoll()) {
exit("EventUtil::sslRandPoll failed\n");
}

$local_cert = __DIR__."/cert.pem";
$local_pk = __DIR__."/privkey.pem";

if (!file_exists($local_cert) || !file_exists($local_pk)) {
echo "Couldn't read $local_cert or $local_pk file. To generate a key\n",
"and self-signed certificate, run:\n",
" openssl genrsa -out $local_pk 2048\n",
" openssl req -new -key $local_pk -out cert.req\n",
" openssl x509 -req -days 365 -in cert.req -signkey $local_pk -out $local_cert\n";

return FALSE;
}

$ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, array (
EventSslContext::OPT_LOCAL_CERT => $local_cert,
EventSslContext::OPT_LOCAL_PK => $local_pk,
//EventSslContext::OPT_PASSPHRASE => "echo server",
EventSslContext::OPT_VERIFY_PEER => true,
EventSslContext::OPT_ALLOW_SELF_SIGNED => false,
));

return $ctx;
}
}

// Allow to override the port
$port = 9999;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port\n");
}

$l = new MySslEchoServer($port);
$l->dispatch();
?>

例5 Signal handler

<?php
/*
Launch it in a terminal window:

$ php examples/signal.php

In another terminal window find out the pid and send SIGTERM, e.g.:

$ ps aux | grep examp
ruslan 3976 0.2 0.0 139896 11256 pts/1 S+ 10:25 0:00 php examples/signal.php
ruslan 3978 0.0 0.0 9572 864 pts/2 S+ 10:26 0:00 grep --color=auto examp
$ kill -TERM 3976

At the first terminal window you should catch the following:

Caught signal 15
*/
class MyEventSignal {
private $base;

function __construct($base) {
$this->base = $base;
}

function eventSighandler($no, $c) {
echo "Caught signal $no\n";
event_base_loopexit($c->base);
}
}

$base = event_base_new();
$c = new MyEventSignal($base);
$no = SIGTERM;
$ev = evsignal_new($base, $no, array($c,'eventSighandler'), $c);

evsignal_add($ev);

event_base_loop($base);
?>

例6 Use libevent's loop to process requests of `eio' extension

<?php
// Callback for eio_nop()
function my_nop_cb($d, $r) {
echo "step 6\n";
}

$dir = "/tmp/abc-eio-temp";
if (file_exists($dir)) {
rmdir($dir);
}

echo "step 1\n";

$base = new EventBase();

echo "step 2\n";

eio_init();

eio_mkdir($dir, 0750, EIO_PRI_DEFAULT, "my_nop_cb");

$event = new Event($base, eio_get_event_stream(),
Event::READ | Event::PERSIST, function ($fd, $events, $base) {
echo "step 5\n";

while (eio_nreqs()) {
eio_poll();
}

$base->stop();
}, $base);

echo "step 3\n";

$event->add();

echo "step 4\n";

$base->dispatch();

echo "Done\n";
?>

例7 Miscellaneous

<?php
/* {{{ Config & supported stuff */
echo "Supported methods:\n";
foreach (Event::getSupportedMethods() as $m) {
echo $m, PHP_EOL;
}

// Avoiding "select" method
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
echo "'select' method avoided\n";
}

// Create event_base associated with the config
$base = new EventBase($cfg);
echo "Event method used: ", $base->getMethod(), PHP_EOL;

echo "Features:\n";
$features = $base->getFeatures();
($features & EventConfig::FEATURE_ET) and print "ET - edge-triggered IO\n";
($features & EventConfig::FEATURE_O1) and print "O1 - O(1) operation for adding/deleting events\n";
($features & EventConfig::FEATURE_FDS) and print "FDS - arbitrary file descriptor types, and not just sockets\n";

// Require FDS feature
if ($cfg->requireFeatures(EventConfig::FEATURE_FDS)) {
echo "FDS feature is now required\n";

$base = new EventBase($cfg);
($base->getFeatures() & EventConfig::FEATURE_FDS)
and print "FDS - arbitrary file descriptor types, and not just sockets\n";
}
/* }}} */

/* {{{ Base */
$base = new EventBase();
$event = new Event($base, STDIN, Event::READ | Event::PERSIST, function ($fd, $events, $arg) {
static $max_iterations = 0;

if (++$max_iterations >= 5) {
/* exit after 5 iterations with timeout of 2.33 seconds */
echo "Stopping...\n";
$arg[0]->exit(2.33);
}

echo fgets($fd);
}, array (&$base));

$event->add();
$base->loop();
/* Base }}} */
?>

例8 Simple HTTP server

<?php
/*
* Simple HTTP server.
*
* To test it:
* 1) Run it on a port of your choice, e.g.:
* $ php examples/http.php 8010
* 2) In another terminal connect to some address on this port
* and make GET or POST request(others are turned off here), e.g.:
* $ nc -t 127.0.0.1 8010
* POST /about HTTP/1.0
* Content-Type: text/plain
* Content-Length: 4
* Connection: close
* (press Enter)
*
* It will output
* a=12
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
*
* $ nc -t 127.0.0.1 8010
* GET /dump HTTP/1.0
* Content-Type: text/plain
* Content-Encoding: UTF-8
* Connection: close
* (press Enter)
*
* It will output:
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
* (press Enter)
*
* $ nc -t 127.0.0.1 8010
* GET /unknown HTTP/1.0
* Connection: close
*
* It will output:
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
*
* 3) See what the server outputs on the previous terminal window.
*/

function _http_dump($req, $data) {
static $counter = 0;
static $max_requests = 2;

if (++$counter >= $max_requests) {
echo "Counter reached max requests $max_requests. Exiting\n";
exit();
}

echo __METHOD__, " called\n";
echo "request:"; var_dump($req);
echo "data:"; var_dump($data);

echo "\n===== DUMP =====\n";
echo "Command:", $req->getCommand(), PHP_EOL;
echo "URI:", $req->getUri(), PHP_EOL;
echo "Input headers:"; var_dump($req->getInputHeaders());
echo "Output headers:"; var_dump($req->getOutputHeaders());

echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";

echo "\n >> Reading input buffer ...\n";
$buf = $req->getInputBuffer();
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
echo "No more data in the buffer\n";
}

function _http_about($req) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

function _http_default($req, $data) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

$port = 8010;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

a=12
HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close
(press Enter)

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

例9 Simple HTTPS server

<?php
/*
* Simple HTTPS server.
*
* 1) Run the server: `php examples/https.php 9999`
* 2) Test it: `php examples/ssl-connection.php 9999`
*/

function _http_dump($req, $data) {
static $counter = 0;
static $max_requests = 200;

if (++$counter >= $max_requests) {
echo "Counter reached max requests $max_requests. Exiting\n";
exit();
}

echo __METHOD__, " called\n";
echo "request:"; var_dump($req);
echo "data:"; var_dump($data);

echo "\n===== DUMP =====\n";
echo "Command:", $req->getCommand(), PHP_EOL;
echo "URI:", $req->getUri(), PHP_EOL;
echo "Input headers:"; var_dump($req->getInputHeaders());
echo "Output headers:"; var_dump($req->getOutputHeaders());

echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";

$buf = $req->getInputBuffer();
echo "\n >> Reading input buffer (", $buf->length, ") ...\n";
while ($s = $buf->read(1024)) {
echo $s;
}
echo "\nNo more data in the buffer\n";
}

function _http_about($req) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

function _http_default($req, $data) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

function _http_400($req) {
$req->sendError(400);
}

function _init_ssl() {
$local_cert = __DIR__."/ssl-echo-server/cert.pem";
$local_pk = __DIR__."/ssl-echo-server/privkey.pem";

$ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, array (
EventSslContext::OPT_LOCAL_CERT => $local_cert,
EventSslContext::OPT_LOCAL_PK => $local_pk,
//EventSslContext::OPT_PASSPHRASE => "test",
EventSslContext::OPT_ALLOW_SELF_SIGNED => true,
));

return $ctx;
}

$port = 9999;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}
$ip = '0.0.0.0';

$base = new EventBase();
$ctx = _init_ssl();
$http = new EventHttp($base, $ctx);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setCallback("/err400", "_http_400");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind($ip, $port);
$base->dispatch();

例10 OpenSSL connection

<?php
/*
* Sample OpenSSL client.
*
* Usage:
* 1) Launch a server, e.g.:
* $ php examples/https.php 9999
*
* 2) Launch the client in another terminal:
* $ php examples/ssl-connection.php 9999
*/

function _request_handler($req, $base) {
echo __FUNCTION__, PHP_EOL;

if (is_null($req)) {
echo "Timed out\n";
} else {
$response_code = $req->getResponseCode();

if ($response_code == 0) {
echo "Connection refused\n";
} elseif ($response_code != 200) {
echo "Unexpected response: $response_code\n";
} else {
echo "Success: $response_code\n";
$buf = $req->getInputBuffer();
echo "Body:\n";
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
}
}

$base->exit(NULL);
}

function _init_ssl() {
$ctx = new EventSslContext(EventSslContext::SSLv3_CLIENT_METHOD, array ());

return $ctx;
}

// Allow to override the port
$port = 9999;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port\n");
}
$host = '127.0.0.1';

$ctx = _init_ssl();
if (!$ctx) {
trigger_error("Failed creating SSL context", E_USER_ERROR);
}

$base = new EventBase();
if (!$base) {
trigger_error("Failed to initialize event base", E_USER_ERROR);
}

$conn = new EventHttpConnection($base, NULL, $host, $port, $ctx);
$conn->setTimeout(50);

$req = new EventHttpRequest("_request_handler", $base);
$req->addHeader("Host", $host, EventHttpRequest::OUTPUT_HEADER);
$buf = $req->getOutputBuffer();
$buf->add("<html>HTML TEST</html>");
//$req->addHeader("Content-Length", $buf->length, EventHttpRequest::OUTPUT_HEADER);
//$req->addHeader("Connection", "close", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_POST, "/dump");

$base->dispatch();
echo "END\n";
?>

例11 EventHttpConnection::makeRequest() example

<?php
function _request_handler($req, $base) {
echo __FUNCTION__, PHP_EOL;

if (is_null($req)) {
echo "Timed out\n";
} else {
$response_code = $req->getResponseCode();

if ($response_code == 0) {
echo "Connection refused\n";
} elseif ($response_code != 200) {
echo "Unexpected response: $response_code\n";
} else {
echo "Success: $response_code\n";
$buf = $req->getInputBuffer();
echo "Body:\n";
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
}
}

$base->exit(NULL);
}

$address = "127.0.0.1";
$port = 80;

$base = new EventBase();
$conn = new EventHttpConnection($base, NULL, $address, $port);
$conn->setTimeout(5);
$req = new EventHttpRequest("_request_handler", $base);

$req->addHeader("Host", $address, EventHttpRequest::OUTPUT_HEADER);
$req->addHeader("Content-Length", "0", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_GET, "/index.cphp");

$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

_request_handler
Success: 200
Body:
PHP, date:
2013-03-13T20:27:52+05:00

例12 Connection listener based on a UNIX domain socket

<?php
/*
* Simple echo server based on libevent's connection listener.
*
* Usage:
* 1) In one terminal window run:
*
* $ php unix-domain-listener.php [path-to-socket]
*
* 2) In another terminal window open up connection
* to the socket, e.g.:
*
* $ socat - GOPEN:/tmp/1.sock
*
* 3) Start typing. The server should repeat the input.
*/

class MyListenerConnection {
private $bev, $base;

public function __destruct() {
if ($this->bev) {
$this->bev->free();
}
}

public function __construct($base, $fd) {
$this->base = $base;

$this->bev = new EventBufferEvent($base, $fd, EventBufferEvent::OPT_CLOSE_ON_FREE);

$this->bev->setCallbacks(array($this, "echoReadCallback"), NULL,
array($this, "echoEventCallback"), NULL);

if (!$this->bev->enable(Event::READ)) {
echo "Failed to enable READ\n";
return;
}
}

public function echoReadCallback($bev, $ctx) {
// Copy all the data from the input buffer to the output buffer
$bev->output->addBuffer($bev->input);
}

public function echoEventCallback($bev, $events, $ctx) {
if ($events & EventBufferEvent::ERROR) {
echo "Error from bufferevent\n";
}

if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
$bev->free();
$bev = NULL;
}
}
}

class MyListener {
public $base,
$listener,
$socket;
private $conn = array();

public function __destruct() {
foreach ($this->conn as &$c) $c = NULL;
}

public function __construct($sock_path) {
$this->base = new EventBase();
if (!$this->base) {
echo "Couldn't open event base";
exit(1);
}

if (file_exists($sock_path)) {
unlink($sock_path);
}

$this->listener = new EventListener($this->base,
array($this, "acceptConnCallback"), $this->base,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE, -1,
"unix:$sock_path");

if (!$this->listener) {
trigger_error("Couldn't create listener", E_USER_ERROR);
}

$this->listener->setErrorCallback(array($this, "accept_error_cb"));
}

public function dispatch() {
$this->base->dispatch();
}

// This callback is invoked when there is data to read on $bev
public function acceptConnCallback($listener, $fd, $address, $ctx) {
// We got a new connection! Set up a bufferevent for it. */
$base = $this->base;
$this->conn[] = new MyListenerConnection($base, $fd);
}

public function accept_error_cb($listener, $ctx) {
$base = $this->base;

fprintf(STDERR, "Got an error %d (%s) on the listener. "
."Shutting down.\n",
EventUtil::getLastSocketErrno(),
EventUtil::getLastSocketError());

$base->exit(NULL);
}
}

if ($argc <= 1) {
exit("Socket path is not provided\n");
}
$sock_path = $argv[1];

$l = new MyListener($sock_path);
$l->dispatch();
?>

例13 Simple SMTP server

<?php
/*
* Author: Andrew Rose <hello at andrewrose dot co dot uk>
*
* Usage:
* 1) Prepare cert.pem certificate and privkey.pem private key files.
* 2) Launch the server script
* 3) Open TLS connection, e.g.:
* $ openssl s_client -connect localhost:25 -starttls smtp -crlf
* 4) Start testing the commands listed in `cmd` method below.
*/

class Handler {
public $domainName = FALSE;
public $connections = [];
public $buffers = [];
public $maxRead = 256000;

public function __construct() {
$this->ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, [
EventSslContext::OPT_LOCAL_CERT => 'cert.pem',
EventSslContext::OPT_LOCAL_PK => 'privkey.pem',
//EventSslContext::OPT_PASSPHRASE => '',
EventSslContext::OPT_VERIFY_PEER => false, // change to true with authentic cert
EventSslContext::OPT_ALLOW_SELF_SIGNED => true // change to false with authentic cert
]);

$this->base = new EventBase();
if (!$this->base) {
exit("Couldn't open event base\n");
}

if (!$this->listener = new EventListener($this->base,
[$this, 'ev_accept'],
$this->ctx,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
-1,
'0.0.0.0:25'))
{
exit("Couldn't create listener\n");
}

$this->listener->setErrorCallback([$this, 'ev_error']);
$this->base->dispatch();
}

public function ev_accept($listener, $fd, $address, $ctx) {
static $id = 0;
$id += 1;

$this->connections[$id]['clientData'] = '';
$this->connections[$id]['cnx'] = new EventBufferEvent($this->base, $fd,
EventBufferEvent::OPT_CLOSE_ON_FREE);

if (!$this->connections[$id]['cnx']) {
echo "Failed creating buffer\n";
$this->base->exit(NULL);
exit(1);
}

$this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL,
[$this, 'ev_error'], $id);
$this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);

$this->ev_write($id, '220 '.$this->domainName." wazzzap?\r\n");
}

function ev_error($listener, $ctx) {
$errno = EventUtil::getLastSocketErrno();

fprintf(STDERR, "Got an error %d (%s) on the listener. Shutting down.\n",
$errno, EventUtil::getLastSocketError());

if ($errno != 0) {
$this->base->exit(NULL);
exit();
}
}

public function ev_close($id) {
$this->connections[$id]['cnx']->disable(Event::READ | Event::WRITE);
unset($this->connections[$id]);
}

protected function ev_write($id, $string) {
echo 'S('.$id.'): '.$string;
$this->connections[$id]['cnx']->write($string);
}

public function ev_read($buffer, $id) {
while($buffer->input->length > 0) {
$this->connections[$id]['clientData'] .= $buffer->input->read($this->maxRead);
$clientDataLen = strlen($this->connections[$id]['clientData']);

if($this->connections[$id]['clientData'][$clientDataLen-1] == "\n"
&& $this->connections[$id]['clientData'][$clientDataLen-2] == "\r")
{
// remove the trailing \r\n
$line = substr($this->connections[$id]['clientData'], 0,
strlen($this->connections[$id]['clientData']) - 2);

$this->connections[$id]['clientData'] = '';
$this->cmd($buffer, $id, $line);
}
}
}

protected function cmd($buffer, $id, $line) {
switch ($line) {
case strncmp('EHLO ', $line, 4):
$this->ev_write($id, "250-STARTTLS\r\n");
$this->ev_write($id, "250 OK ehlo\r\n");
break;

case strncmp('HELO ', $line, 4):
$this->ev_write($id, "250-STARTTLS\r\n");
$this->ev_write($id, "250 OK helo\r\n");
break;

case strncmp('QUIT', $line, 3):
$this->ev_write($id, "250 OK quit\r\n");
$this->ev_close($id);
break;

case strncmp('STARTTLS', $line, 3):
$this->ev_write($id, "220 Ready to start TLS\r\n");
$this->connections[$id]['cnx'] = EventBufferEvent::sslFilter($this->base,
$this->connections[$id]['cnx'], $this->ctx,
EventBufferEvent::SSL_ACCEPTING,
EventBufferEvent::OPT_CLOSE_ON_FREE);
$this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL, [$this, 'ev_error'], $id);
$this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);
break;

default:
echo 'unknown command: '.$line."\n";
break;
}
}
}

new Handler();


Event flags

Event::READ This flag indicates an event that becomes active when the provided file descriptor (usually a stream resource, or socket) is ready for reading.

Event::WRITE flag indicates an event that becomes active when the provided file descriptor (usually a stream resource, or socket) is ready for writing.

Event::SIGNAL used to implement signal detection. See "Constructing signal events" below.

Event::TIMEOUT indicates an event that becomes active after a timeout elapses. The Event::TIMEOUT flag is ignored when constructing an event: one can either set a timeout when event is added , or not. It is set in the $what argument to the callback function when a timeout has occurred.

See also » Fast portable non-blocking network programming with Libevent, Working with events, Event flags


About event persistence

By default, whenever a pending event becomes active (because its file descriptor is ready to read or write, or because its timeout expires), it becomes non-pending right before its callback is executed. Thus, to make the event pending again one may call Event::add() on it again from inside the callback function.

If the Event::PERSIST flag is set on an event, however, the event is persistent . This means that event remains pending even when its callback is activated. Event::del() method can be called to make it non-pending.

The timeout on a persistent event resets whenever the event's callback runs. Thus, if one has an event with flags Event::READ | Event::PERSIST and a timeout of five seconds, the event will become active:

  1. Whenever the socket or file descriptor is ready for reading.

  2. Whenever five seconds have passed since the event last became active.

See also » Fast portable non-blocking network programming with Libevent, About Event Persistence


Event callbacks

If a callback is registered for an event, it will be called when the event becomes active. To associate a callback with event one can pass a callable to either Event::__construct() , or Event::set() , or one of the factory methods like Event::timer() .

An event callback should match the following prototype:

callback( mixed $fd = null , int $what = ?, mixed $arg = null ): void

fd

The file descriptor, stream resource or socket associated with the event. For signal event fd is equal to the signal number.

what

Bit mask of all events triggered.

arg

User custom data.

Event::timer() expects the callback to match the following prototype:

callback( mixed $arg = null ): void

arg

User custom data.

Event::signal() expects the callback to match the following prototype:

callback( int $signum = ?, mixed $arg = null ): void

signum

The number of the triggered signal(e.g. SIGTERM ).

arg

User custom data.


Constructing signal events

Event can also watch for POSIX-style signals. To construct a handler for a signal, use Event::__construct() constructor with Event::SIGNAL flag, or Event::signal() factory method.

例1 Handling SIGTERM signal

<?php
/*
Launch it in a terminal window:

$ php examples/signal.php

In another terminal window find out the pid and send SIGTERM, e.g.:

$ ps aux | grep examp
ruslan 3976 0.2 0.0 139896 11256 pts/1 S+ 10:25 0:00 php examples/signal.php
ruslan 3978 0.0 0.0 9572 864 pts/2 S+ 10:26 0:00 grep --color=auto examp
$ kill -TERM 3976

At the first terminal window you should catch the following:

Caught signal 15
*/
class MyEventSignal {
private $base, $ev;

public function __construct($base) {
$this->base = $base;
$this->ev = Event::signal($base, SIGTERM, array($this, 'eventSighandler'));
$this->ev->add();
}

public function eventSighandler($no, $c) {
echo "Caught signal $no\n";
$this->base->exit();
}
}

$base = new EventBase();
$c = new MyEventSignal($base);

$base->loop();
?>

Note that signal callbacks are run in the event loop after the signal occurs, so it is safe for them to call functions that you are not supposed to call from a regular POSIX signal handler.

See also » Fast portable non-blocking network programming with Libevent, Constructing Signal Events .


The Event class

(PECL event >= 1.2.6-beta)

はじめに

Event class represents and event firing on a file descriptor being ready to read from or write to; a file descriptor becoming ready to read from or write to(edge-triggered I/O only); a timeout expiring; a signal occurring; a user-triggered event.

Every event is associated with EventBase . However, event will never fire until it is added (via Event::add() ). An added event remains in pending state until the registered event occurs, thus turning it to active state. To handle events user may register a callback which is called when event becomes active. If event is configured persistent , it remains pending. If it is not persistent, it stops being pending when it's callback runs. Event::del() method deletes event, thus making it non-pending. By means of Event::add() method it could be added again.

クラス概要

final class Event {
/* 定数 */
const int ET = 32;
const int PERSIST = 16;
const int READ = 2;
const int WRITE = 4;
const int SIGNAL = 8;
const int TIMEOUT = 1;
/* プロパティ */
public readonly bool $pending;
/* メソッド */
public add( float $timeout = ?): bool
public __construct(
EventBase $base ,
mixed $fd ,
int $what ,
callable $cb ,
mixed $arg = NULL
)
public del(): bool
public free(): void
public static getSupportedMethods(): array
public pending( int $flags ): bool
public set(
EventBase $base ,
mixed $fd ,
int $what = ?,
callable $cb = ?,
mixed $arg = ?
): bool
public setPriority( int $priority ): bool
public setTimer( EventBase $base , callable $cb , mixed $arg = ?): bool
public static signal(
EventBase $base ,
int $signum ,
callable $cb ,
mixed $arg = ?
): Event
public static timer( EventBase $base , callable $cb , mixed $arg = ?): Event
}

プロパティ

pending

Whether event is pending. See About event persistence .

定義済み定数

Event::ET

Indicates that the event should be edge-triggered, if the underlying event base backend supports edge-triggered events. This affects the semantics of Event::READ and Event::WRITE .

Event::PERSIST

Indicates that the event is persistent. See About event persistence .

Event::READ

This flag indicates an event that becomes active when the provided file descriptor(usually a stream resource, or socket) is ready for reading.

Event::WRITE

This flag indicates an event that becomes active when the provided file descriptor(usually a stream resource, or socket) is ready for reading.

Event::SIGNAL

Used to implement signal detection. See "Constructing signal events" below.

Event::TIMEOUT

This flag indicates an event that becomes active after a timeout elapses.

The Event::TIMEOUT flag is ignored when constructing an event: one can either set a timeout when event is added , or not. It is set in the $what argument to the callback function when a timeout has occurred.

目次

  • Event::add — Makes event pending
  • Event::addSignal — のエイリアス Event::add
  • Event::addTimer — のエイリアス Event::add
  • Event::__construct — Constructs Event object
  • Event::del — Makes event non-pending
  • Event::delSignal — のエイリアス Event::del
  • Event::delTimer — のエイリアス Event::del
  • Event::free — Make event non-pending and free resources allocated for this event
  • Event::getSupportedMethods — Returns array with of the names of the methods supported in this version of Libevent
  • Event::pending — Detects whether event is pending or scheduled
  • Event::set — Re-configures event
  • Event::setPriority — Set event priority
  • Event::setTimer — Re-configures timer event
  • Event::signal — Constructs signal event object
  • Event::timer — Constructs timer event object


Makes event pending

  • ≪ Event
  • Event::addSignal ≫
  • PHP Manual
  • Event
  • Makes event pending

Event::add

(PECL event >= 1.2.6-beta)

Event::add — Makes event pending

説明

public Event::add( float $timeout = ?): bool

Marks event pending. Non-pending event will never occur, and the event callback will never be called. In conjunction with Event::del() an event could be re-scheduled by user at any time.

If Event::add() is called on an already pending event, libevent will leave it pending and re-schedule it with the given timeout(if specified). If in this case timeout is not specified, Event::add() has no effect.

パラメータ

timeout

Timeout in seconds.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Adding a custom signal

<?php
/*
Launch it in a terminal window:

$ php examples/signal.php

In another terminal window find out the pid and send SIGTERM, e.g.:

$ ps aux | grep examp
ruslan 3976 0.2 0.0 139896 11256 pts/1 S+ 10:25 0:00 php examples/signal.php
ruslan 3978 0.0 0.0 9572 864 pts/2 S+ 10:26 0:00 grep --color=auto examp
$ kill -TERM 3976

At the first terminal window you should catch the following:

Caught signal 15
*/
class MyEventSignal {
private $base, $ev;

public function __construct($base) {
$this->base = $base;
$this->ev = Event::signal($base, SIGTERM, array($this, 'eventSighandler'));
$this->ev->add();
}

public function eventSighandler($no, $c) {
echo "Caught signal $no\n";
$this->base->exit();
}
}

$base = new EventBase();
$c = new MyEventSignal($base);

$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

Caught signal 15

例2 Adding a timer

<?php
$base = new EventBase();
$n = 2;
$e = Event::timer($base, function($n) use (&$e) {
echo "$n seconds elapsed\n";
$e->delTimer();
}, $n);
$e->add($n);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

2 seconds elapsed

参考

  • Event::add()
  • Event::del() - Makes event non-pending
  • Event::signal() - Constructs signal event object
  • Event::timer() - Constructs timer event object


のエイリアス Event::add

  • ≪ Event::add
  • Event::addTimer ≫
  • PHP Manual
  • Event
  • のエイリアス Event::add

Event::addSignal

(PECL event >= 1.2.6-beta)

Event::addSignal — のエイリアス Event::add()

説明

このメソッドは次のメソッドのエイリアスです。 Event::add()


のエイリアス Event::add

  • ≪ Event::addSignal
  • Event::__construct ≫
  • PHP Manual
  • Event
  • のエイリアス Event::add

Event::addTimer

(PECL event >= 1.2.6-beta)

Event::addTimer — のエイリアス Event::add()

説明

このメソッドは次のメソッドのエイリアスです。 Event::add()


Constructs Event object

  • ≪ Event::addTimer
  • Event::del ≫
  • PHP Manual
  • Event
  • Constructs Event object

Event::__construct

(PECL event >= 1.2.6-beta)

Event::__construct — Constructs Event object

説明

public Event::__construct(
EventBase $base ,
mixed $fd ,
int $what ,
callable $cb ,
mixed $arg = NULL
)

Constructs Event object.

パラメータ

base

The event base to associate with.

fd

stream resource, socket resource, or numeric file descriptor. For timer events pass -1 . For signal events pass the signal number, e.g. SIGHUP .

what

Event flags. See Event flags .

cb

The event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

参考

  • Event::signal() - Constructs signal event object
  • Event::timer() - Constructs timer event object


Makes event non-pending

  • ≪ Event::__construct
  • Event::delSignal ≫
  • PHP Manual
  • Event
  • Makes event non-pending

Event::del

(PECL event >= 1.2.6-beta)

Event::del — Makes event non-pending

説明

public Event::del(): bool

Removes an event from the set of monitored events, i.e. makes it non-pending.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Event::add() - Makes event pending


のエイリアス Event::del

  • ≪ Event::del
  • Event::delTimer ≫
  • PHP Manual
  • Event
  • のエイリアス Event::del

Event::delSignal

(PECL event >= 1.2.6-beta)

Event::delSignal — のエイリアス Event::del()

説明

このメソッドは次のメソッドのエイリアスです。 Event::del()


のエイリアス Event::del

  • ≪ Event::delSignal
  • Event::free ≫
  • PHP Manual
  • Event
  • のエイリアス Event::del

Event::delTimer

(PECL event >= 1.2.6-beta)

Event::delTimer — のエイリアス Event::del()

説明

このメソッドは次のメソッドのエイリアスです。 Event::del()


Make event non-pending and free resources allocated for this event

  • ≪ Event::delTimer
  • Event::getSupportedMethods ≫
  • PHP Manual
  • Event
  • Make event non-pending and free resources allocated for this event

Event::free

(PECL event >= 1.2.6-beta)

Event::free — Make event non-pending and free resources allocated for this event

説明

public Event::free(): void

Removes event from the list of events monitored by libevent, and free resources allocated for the event.

警告

The Event::free() method currently doesn't destruct the object itself. To destruct the object completely call unset() , or assign null.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • Event::__construct() - Constructs Event object


Returns array with of the names of the methods supported in this version of Libevent

  • ≪ Event::free
  • Event::pending ≫
  • PHP Manual
  • Event
  • Returns array with of the names of the methods supported in this version of Libevent

Event::getSupportedMethods

(PECL event >= 1.2.6-beta)

Event::getSupportedMethods — Returns array with of the names of the methods supported in this version of Libevent

説明

public static Event::getSupportedMethods(): array

Returns array with of the names of the methods(backends) supported in this version of Libevent.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns array.

参考

  • EventConfig


Detects whether event is pending or scheduled

  • ≪ Event::getSupportedMethods
  • Event::set ≫
  • PHP Manual
  • Event
  • Detects whether event is pending or scheduled

Event::pending

(PECL event >= 1.2.6-beta)

Event::pending — Detects whether event is pending or scheduled

説明

public Event::pending( int $flags ): bool

Detects whether event is pending or scheduled

パラメータ

flags

One of, or a composition of the following constants: Event::READ , Event::WRITE , Event::TIMEOUT , Event::SIGNAL .

戻り値

Returns true if event is pending or scheduled. Otherwise false.


Re-configures event

  • ≪ Event::pending
  • Event::setPriority ≫
  • PHP Manual
  • Event
  • Re-configures event

Event::set

(PECL event >= 1.2.6-beta)

Event::set — Re-configures event

説明

public Event::set(
EventBase $base ,
mixed $fd ,
int $what = ?,
callable $cb = ?,
mixed $arg = ?
): bool

Re-configures event. Note, this function doesn't invoke obsolete libevent's event_set. It calls event_assign instead.

パラメータ

base

The event base to associate the event with.

fd

Stream resource, socket resource, or numeric file descriptor. For timer events pass -1 . For signal events pass the signal number, e.g. SIGHUP .

what

See Event flags .

cb

The event callback. See Event callbacks .

arg

Custom data associated with the event. It will be passed to the callback when the event becomes active.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Set event priority

  • ≪ Event::set
  • Event::setTimer ≫
  • PHP Manual
  • Event
  • Set event priority

Event::setPriority

(PECL event >= 1.2.6-beta)

Event::setPriority — Set event priority

説明

public Event::setPriority( int $priority ): bool

Set event priority.

パラメータ

priority

The event priority.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Re-configures timer event

  • ≪ Event::setPriority
  • Event::signal ≫
  • PHP Manual
  • Event
  • Re-configures timer event

Event::setTimer

(PECL event >= 1.2.6-beta)

Event::setTimer — Re-configures timer event

説明

public Event::setTimer( EventBase $base , callable $cb , mixed $arg = ?): bool

Re-configures timer event. Note, this function doesn't invoke obsolete libevent's event_set . It calls event_assign instead.

パラメータ

base

The event base to associate with.

cb

The timer event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Event::__construct() - Constructs Event object
  • Event::timer() - Constructs timer event object


Constructs signal event object

  • ≪ Event::setTimer
  • Event::timer ≫
  • PHP Manual
  • Event
  • Constructs signal event object

Event::signal

(PECL event >= 1.2.6-beta)

Event::signal — Constructs signal event object

説明

public static Event::signal(
EventBase $base ,
int $signum ,
callable $cb ,
mixed $arg = ?
): Event

Constructs signal event object. This is a straightforward method to create a signal event. Note, the generic Event::__construct() method can contruct signal event objects too.

パラメータ

base

The associated event base object.

signum

The signal number.

cb

The signal event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

戻り値

Returns Event object on success. Otherwise false.

参考

  • Constructing signal events


Constructs timer event object

  • ≪ Event::signal
  • EventBase ≫
  • PHP Manual
  • Event
  • Constructs timer event object

Event::timer

(PECL event >= 1.2.6-beta)

Event::timer — Constructs timer event object

説明

public static Event::timer( EventBase $base , callable $cb , mixed $arg = ?): Event

Constructs timer event object. This is a straightforward method to create a timer event. Note, the generic Event::__construct() method can contruct signal event objects too.

パラメータ

base

The associated event base object.

cb

The signal event callback. See Event callbacks .

arg

Custom data. If specified, it will be passed to the callback when event triggers.

戻り値

Returns Event object on success. Otherwise false.


The EventBase class

(PECL event >= 1.2.6-beta)

はじめに

EventBase class represents libevent's event base structure. It holds a set of events and can poll to determine which events are active.

Each event base has a method , or a backend that it uses to determine which events are ready. The recognized methods are: select , poll , epoll , kqueue , devpoll , evport and win32 .

To configure event base to use, or avoid specific backend EventConfig class can be used.

警告

Do NOT destroy the EventBase object as long as resources of the associated Event objects are not released. Otherwise, it will lead to unpredictable results!

クラス概要

final class EventBase {
/* 定数 */
const int LOOP_ONCE = 1;
const int LOOP_NONBLOCK = 2;
const int NOLOCK = 1;
const int STARTUP_IOCP = 4;
const int NO_CACHE_TIME = 8;
const int EPOLL_USE_CHANGELIST = 16;
/* メソッド */
public __construct( EventConfig $cfg = ?)
public dispatch(): void
public exit( float $timeout = ?): bool
public free(): void
public getFeatures(): int
public getMethod(): string
public getTimeOfDayCached(): float
public gotExit(): bool
public gotStop(): bool
public loop( int $flags = ?): bool
public priorityInit( int $n_priorities ): bool
public reInit(): bool
public stop(): bool
}

定義済み定数

EventBase::LOOP_ONCE

Flag used with EventBase::loop() method which means: "block until libevent has an active event, then exit once all active events have had their callbacks run".

EventBase::LOOP_NONBLOCK

Flag used with EventBase::loop() method which means: "do not block: see which events are ready now, run the callbacks of the highest-priority ones, then exit".

EventBase::NOLOCK

Configuration flag. Do not allocate a lock for the event base, even if we have locking set up".

EventBase::STARTUP_IOCP

Windows-only configuration flag. Enables the IOCP dispatcher at startup.

EventBase::NO_CACHE_TIME

Configuration flag. Instead of checking the current time every time the event loop is ready to run timeout callbacks, check after each timeout callback.

EventBase::EPOLL_USE_CHANGELIST

If we are using the epoll backend, this flag says that it is safe to use Libevent's internal change-list code to batch up adds and deletes in order to try to do as few syscalls as possible.

Setting this flag can make code run faster, but it may trigger a Linux bug: it is not safe to use this flag if one has any fds cloned by dup(), or its variants. Doing so will produce strange and hard-to-diagnose bugs.

This flag can also be activated by settnig the EVENT_EPOLL_USE_CHANGELIST environment variable.

This flag has no effect if one winds up using a backend other than epoll .

目次

  • EventBase::__construct — Constructs EventBase object
  • EventBase::dispatch — Dispatch pending events
  • EventBase::exit — Stop dispatching events
  • EventBase::free — Free resources allocated for this event base
  • EventBase::getFeatures — Returns bitmask of features supported
  • EventBase::getMethod — Returns event method in use
  • EventBase::getTimeOfDayCached — Returns the current event base time
  • EventBase::gotExit — Checks if the event loop was told to exit
  • EventBase::gotStop — Checks if the event loop was told to exit
  • EventBase::loop — Dispatch pending events
  • EventBase::priorityInit — Sets number of priorities per event base
  • EventBase::reInit — Re-initialize event base(after a fork)
  • EventBase::stop — Tells event_base to stop dispatching events


Constructs EventBase object

  • ≪ EventBase
  • EventBase::dispatch ≫
  • PHP Manual
  • EventBase
  • Constructs EventBase object

EventBase::__construct

(PECL event >= 1.2.6-beta)

EventBase::__construct — Constructs EventBase object

説明

public EventBase::__construct( EventConfig $cfg = ?)

Constructs EventBase object

パラメータ

cfg

Optional EventConfig object.

エラー / 例外

If EventBase cannot be constructed with the provided configuration, a EventException will be thrown.

参考

  • EventConfig


Dispatch pending events

  • ≪ EventBase::__construct
  • EventBase::exit ≫
  • PHP Manual
  • EventBase
  • Dispatch pending events

EventBase::dispatch

(PECL event >= 1.2.6-beta)

EventBase::dispatch — Dispatch pending events

説明

public EventBase::dispatch(): void

Wait for events to become active, and run their callbacks. The same as EventBase::loop() with no flags set.

警告

Do NOT destroy the EventBase object as long as resources of the associated Event objects are not released. Otherwise, it will lead to unpredictable results!

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBase::loop() - Dispatch pending events


Stop dispatching events

  • ≪ EventBase::dispatch
  • EventBase::free ≫
  • PHP Manual
  • EventBase
  • Stop dispatching events

EventBase::exit

(PECL event >= 1.2.6-beta)

EventBase::exit — Stop dispatching events

説明

public EventBase::exit( float $timeout = ?): bool

Tells event base to stop optionally after given number of seconds.

パラメータ

timeout

Optional number of seconds after which the event base should stop dispatching events.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBase::stop() - Tells event_base to stop dispatching events


Free resources allocated for this event base

  • ≪ EventBase::exit
  • EventBase::getFeatures ≫
  • PHP Manual
  • EventBase
  • Free resources allocated for this event base

EventBase::free

(PECL event >= 1.10.0)

EventBase::free — Free resources allocated for this event base

説明

public EventBase::free(): void

Deallocates resources allocated by libevent for the EventBase object.

警告

The EventBase::free() method doesn't destruct the object itself. To destruct the object completely call unset() , or assign null.

This method does not deallocate or detach any of the events that are currently associated with the EventBase object, or close any of their sockets - beware.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EventBase::__construct() - Constructs EventBase object


Returns bitmask of features supported

  • ≪ EventBase::free
  • EventBase::getMethod ≫
  • PHP Manual
  • EventBase
  • Returns bitmask of features supported

EventBase::getFeatures

(PECL event >= 1.2.6-beta)

EventBase::getFeatures — Returns bitmask of features supported

説明

public EventBase::getFeatures(): int

Returns bitmask of features supported.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns integer representing a bitmask of supported features. See EventConfig::FEATURE_* constants .

例

例1 EventBase::getFeatures() example

<?php
// Avoiding "select" method
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
echo "'select' method avoided\n";
}

$base = new EventBase($cfg);

echo "Features:\n";
$features = $base->getFeatures();
($features & EventConfig::FEATURE_ET) and print "ET - edge-triggered IO\n";
($features & EventConfig::FEATURE_O1) and print "O1 - O(1) operation for adding/deleting events\n";
($features & EventConfig::FEATURE_FDS) and print "FDS - arbitrary file descriptor types, and not just sockets\n";
?>

参考

  • EventBase::getMethod() - Returns event method in use
  • EventConfig


Returns event method in use

  • ≪ EventBase::getFeatures
  • EventBase::getTimeOfDayCached ≫
  • PHP Manual
  • EventBase
  • Returns event method in use

EventBase::getMethod

(PECL event >= 1.2.6-beta)

EventBase::getMethod — Returns event method in use

説明

public EventBase::getMethod(): string

パラメータ

この関数にはパラメータはありません。

戻り値

String representing used event method(backend).

例

例1 EventBase::getMethod() example

<?php
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
echo "'select' method avoided\n";
}

// Create event_base associated with the config
$base = new EventBase($cfg);
echo "Event method used: ", $base->getMethod(), PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

`select' method avoided
Event method used: epoll

参考

  • EventBase::getFeatures() - Returns bitmask of features supported


Returns the current event base time

  • ≪ EventBase::getMethod
  • EventBase::gotExit ≫
  • PHP Manual
  • EventBase
  • Returns the current event base time

EventBase::getTimeOfDayCached

(PECL event >= 1.2.6-beta)

EventBase::getTimeOfDayCached — Returns the current event base time

説明

public EventBase::getTimeOfDayCached(): float

On success returns the current time(as returned by gettimeofday() ), looking at the cached value in base if possible, and calling gettimeofday() or clock_gettime() as appropriate if there is no cached time.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current event base time. On failure returns null.


Checks if the event loop was told to exit

  • ≪ EventBase::getTimeOfDayCached
  • EventBase::gotStop ≫
  • PHP Manual
  • EventBase
  • Checks if the event loop was told to exit

EventBase::gotExit

(PECL event >= 1.2.6-beta)

EventBase::gotExit — Checks if the event loop was told to exit

説明

public EventBase::gotExit(): bool

Checks if the event loop was told to exit by EventBase::exit() .

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true, event loop was told to exit by EventBase::exit() . Otherwise false.

参考

  • EventBase::exit() - Stop dispatching events
  • EventBase::stop() - Tells event_base to stop dispatching events
  • EventBase::gotStop() - Checks if the event loop was told to exit


Checks if the event loop was told to exit

  • ≪ EventBase::gotExit
  • EventBase::loop ≫
  • PHP Manual
  • EventBase
  • Checks if the event loop was told to exit

EventBase::gotStop

(PECL event >= 1.2.6-beta)

EventBase::gotStop — Checks if the event loop was told to exit

説明

public EventBase::gotStop(): bool

Checks if the event loop was told to exit by EventBase::stop() .

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true, event loop was told to stop by EventBase::stop() . Otherwise false.

参考

  • EventBase::exit() - Stop dispatching events
  • EventBase::stop() - Tells event_base to stop dispatching events
  • EventBase::gotExit() - Checks if the event loop was told to exit


Dispatch pending events

  • ≪ EventBase::gotStop
  • EventBase::priorityInit ≫
  • PHP Manual
  • EventBase
  • Dispatch pending events

EventBase::loop

(PECL event >= 1.2.6-beta)

EventBase::loop — Dispatch pending events

説明

public EventBase::loop( int $flags = ?): bool

Wait for events to become active, and run their callbacks.

警告

Do NOT destroy the EventBase object as long as resources of the associated Event objects are not released. Otherwise, it will lead to unpredictable results!

パラメータ

flags

Optional flags. One of EventBase::LOOP_* constants. See EventBase constants .

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBase::dispatch() - Dispatch pending events


Sets number of priorities per event base

  • ≪ EventBase::loop
  • EventBase::reInit ≫
  • PHP Manual
  • EventBase
  • Sets number of priorities per event base

EventBase::priorityInit

(PECL event >= 1.2.6-beta)

EventBase::priorityInit — Sets number of priorities per event base

説明

public EventBase::priorityInit( int $n_priorities ): bool

Sets number of priorities per event base.

パラメータ

n_priorities

The number of priorities per event base.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Event::setPriority() - Set event priority


Re-initialize event base(after a fork)

  • ≪ EventBase::priorityInit
  • EventBase::stop ≫
  • PHP Manual
  • EventBase
  • Re-initialize event base(after a fork)

EventBase::reInit

(PECL event >= 1.2.6-beta)

EventBase::reInit — Re-initialize event base(after a fork)

説明

public EventBase::reInit(): bool

Re-initialize event base. Should be called after a fork.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


Tells event_base to stop dispatching events

  • ≪ EventBase::reInit
  • EventBuffer ≫
  • PHP Manual
  • EventBase
  • Tells event_base to stop dispatching events

EventBase::stop

(PECL event >= 1.2.6-beta)

EventBase::stop — Tells event_base to stop dispatching events

説明

public EventBase::stop(): bool

Tells event_base to stop dispatching events

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBase::exit() - Stop dispatching events
  • EventBase::gotStop() - Checks if the event loop was told to exit


The EventBuffer class

(PECL event >= 1.5.0)

はじめに

EventBuffer represents Libevent's "evbuffer", an utility functionality for buffered I/O.

Event buffers are meant to be generally useful for doing the "buffer" part of buffered network I/O.

クラス概要

class EventBuffer {
/* 定数 */
const int EOL_ANY = 0;
const int EOL_CRLF = 1;
const int EOL_CRLF_STRICT = 2;
const int EOL_LF = 3;
const int PTR_SET = 0;
const int PTR_ADD = 1;
/* プロパティ */
public readonly int $length;
public readonly int $contiguous_space;
/* メソッド */
public add( string $data ): bool
public addBuffer( EventBuffer $buf ): bool
public appendFrom( EventBuffer $buf , int $len ): int
public __construct()
public copyout( string &$data , int $max_bytes ): int
public drain( int $len ): bool
public enableLocking(): void
public expand( int $len ): bool
public freeze( bool $at_front ): bool
public lock(): void
public prepend( string $data ): bool
public prependBuffer( EventBuffer $buf ): bool
public pullup( int $size ): string
public read( int $max_bytes ): string
public read( mixed $fd , int $howmuch ): int
public readLine( int $eol_style ): string
public search( string $what , int $start = -1 , int $end = -1 ): mixed
public searchEol( int $start = -1 , int $eol_style = EventBuffer::EOL_ANY ): mixed
public substr( int $start , int $length = ?): string
public unfreeze( bool $at_front ): bool
public unlock(): bool
public write( mixed $fd , int $howmuch = ?): int
}

プロパティ

length

The number of bytes stored in an event buffer.

contiguous_space

The number of bytes stored contiguously at the front of the buffer. The bytes in a buffer may be stored in multiple separate chunks of memory; the property returns the number of bytes currently stored in the first chunk.

定義済み定数

EventBuffer::EOL_ANY

The end of line is any sequence of any number of carriage return and linefeed characters. This format is not very useful; it exists mainly for backward compatibility.

EventBuffer::EOL_CRLF

The end of the line is an optional carriage return, followed by a linefeed. (In other words, it is either a "\r\n" or a "\n" .) This format is useful in parsing text-based Internet protocols, since the standards generally prescribe a "\r\n" line-terminator, but nonconformant clients sometimes say just "\n" .

EventBuffer::EOL_CRLF_STRICT

The end of a line is a single carriage return, followed by a single linefeed. (This is also known as "\r\n" . The ASCII values are 0x0D 0x0A ).

EventBuffer::EOL_LF

The end of a line is a single linefeed character. (This is also known as "\n" . It is ASCII value is 0x0A .)

EventBuffer::PTR_SET

Flag used as argument of EventBuffer::setPosition() method. If this flag specified, the position pointer is moved to an absolute position within the buffer.

EventBuffer::PTR_ADD

The same as EventBuffer::PTR_SET , except this flag causes EventBuffer::setPosition() method to move position forward up to the specified number of bytes(instead of setting absolute position).

目次

  • EventBuffer::add — Append data to the end of an event buffer
  • EventBuffer::addBuffer — Move all data from a buffer provided to the current instance of EventBuffer
  • EventBuffer::appendFrom — Moves the specified number of bytes from a source buffer to the end of the current buffer
  • EventBuffer::__construct — Constructs EventBuffer object
  • EventBuffer::copyout — Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain — Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::enableLocking — 説明
  • EventBuffer::expand — Reserves space in buffer
  • EventBuffer::freeze — Prevent calls that modify an event buffer from succeeding
  • EventBuffer::lock — Acquires a lock on buffer
  • EventBuffer::prepend — Prepend data to the front of the buffer
  • EventBuffer::prependBuffer — Moves all data from source buffer to the front of current buffer
  • EventBuffer::pullup — Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::read — Read data from an evbuffer and drain the bytes read
  • EventBuffer::readFrom — Read data from a file onto the end of the buffer
  • EventBuffer::readLine — Extracts a line from the front of the buffer
  • EventBuffer::search — Scans the buffer for an occurrence of a string
  • EventBuffer::searchEol — Scans the buffer for an occurrence of an end of line
  • EventBuffer::substr — Substracts a portion of the buffer data
  • EventBuffer::unfreeze — Re-enable calls that modify an event buffer
  • EventBuffer::unlock — Releases lock acquired by EventBuffer::lock
  • EventBuffer::write — Write contents of the buffer to a file or socket


Append data to the end of an event buffer

  • ≪ EventBuffer
  • EventBuffer::addBuffer ≫
  • PHP Manual
  • EventBuffer
  • Append data to the end of an event buffer

EventBuffer::add

(PECL event >= 1.2.6-beta)

EventBuffer::add — Append data to the end of an event buffer

説明

public EventBuffer::add( string $data ): bool

Append data to the end of an event buffer.

パラメータ

data

String to be appended to the end of the buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::addBuffer() - Move all data from a buffer provided to the current instance of EventBuffer


Move all data from a buffer provided to the current instance of EventBuffer

  • ≪ EventBuffer::add
  • EventBuffer::appendFrom ≫
  • PHP Manual
  • EventBuffer
  • Move all data from a buffer provided to the current instance of EventBuffer

EventBuffer::addBuffer

(PECL event >= 1.2.6-beta)

EventBuffer::addBuffer — Move all data from a buffer provided to the current instance of EventBuffer

説明

public EventBuffer::addBuffer( EventBuffer $buf ): bool

Move all data from the buffer provided in buf parameter to the end of current EventBuffer . This is a destructive add. The data from one buffer moves into the other buffer. However, no unnecessary memory copies occur.

パラメータ

buf

The source EventBuffer object.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::add() - Append data to the end of an event buffer


Moves the specified number of bytes from a source buffer to the end of the current buffer

  • ≪ EventBuffer::addBuffer
  • EventBuffer::__construct ≫
  • PHP Manual
  • EventBuffer
  • Moves the specified number of bytes from a source buffer to the end of the current buffer

EventBuffer::appendFrom

(PECL event >= 1.6.0)

EventBuffer::appendFrom — Moves the specified number of bytes from a source buffer to the end of the current buffer

説明

public EventBuffer::appendFrom( EventBuffer $buf , int $len ): int

Moves the specified number of bytes from a source buffer to the end of the current buffer. If there are fewer number of bytes, it moves all the bytes available from the source buffer.

パラメータ

buf

Source buffer.

len

戻り値

Returns the number of bytes read.

変更履歴

バージョン | 説明
PECL event 1.6.0 | Renamed EventBuffer::appendFrom()(the old method name) to EventBuffer::appendFrom().

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read


Constructs EventBuffer object

  • ≪ EventBuffer::appendFrom
  • EventBuffer::copyout ≫
  • PHP Manual
  • EventBuffer
  • Constructs EventBuffer object

EventBuffer::__construct

(PECL event >= 1.2.6-beta)

EventBuffer::__construct — Constructs EventBuffer object

説明

public EventBuffer::__construct()

Constructs EventBuffer object

パラメータ

この関数にはパラメータはありません。


Copies out specified number of bytes from the front of the buffer

  • ≪ EventBuffer::__construct
  • EventBuffer::drain ≫
  • PHP Manual
  • EventBuffer
  • Copies out specified number of bytes from the front of the buffer

EventBuffer::copyout

(PECL event >= 1.2.6-beta)

EventBuffer::copyout — Copies out specified number of bytes from the front of the buffer

説明

public EventBuffer::copyout( string &$data , int $max_bytes ): int

Behaves just like EventBuffer::read() , but does not drain any data from the buffer. I.e. it copies the first max_bytes bytes from the front of the buffer into data . If there are fewer than max_bytes bytes available, the function copies all the bytes there are.

パラメータ

data

Output string.

max_bytes

The number of bytes to copy.

戻り値

Returns the number of bytes copied, or -1 on failure.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer


Removes specified number of bytes from the front of the buffer without copying it anywhere

  • ≪ EventBuffer::copyout
  • EventBuffer::enableLocking ≫
  • PHP Manual
  • EventBuffer
  • Removes specified number of bytes from the front of the buffer without copying it anywhere

EventBuffer::drain

(PECL event >= 1.2.6-beta)

EventBuffer::drain — Removes specified number of bytes from the front of the buffer without copying it anywhere

説明

public EventBuffer::drain( int $len ): bool

Behaves as EventBuffer::read() , except that it does not copy the data: it just removes it from the front of the buffer.

パラメータ

len

The number of bytes to remove from the buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer


説明

  • ≪ EventBuffer::drain
  • EventBuffer::expand ≫
  • PHP Manual
  • EventBuffer
  • 説明

EventBuffer::enableLocking

(PECL event >= 1.2.6-beta)

EventBuffer::enableLocking —

説明

public EventBuffer::enableLocking(): void

Enable locking on an EventBuffer so that it can safely be used by multiple threads at the same time. When locking is enabled, the lock will be held when callbacks are invoked. This could result in deadlock if you aren't careful. Plan accordingly!

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • » Evbuffers and Thread-safety


Reserves space in buffer

  • ≪ EventBuffer::enableLocking
  • EventBuffer::freeze ≫
  • PHP Manual
  • EventBuffer
  • Reserves space in buffer

EventBuffer::expand

(PECL event >= 1.2.6-beta)

EventBuffer::expand — Reserves space in buffer

説明

public EventBuffer::expand( int $len ): bool

Alters the last chunk of memory in the buffer, or adds a new chunk, such that the buffer is now large enough to contain len bytes without any further allocations.

パラメータ

len

The number of bytes to reserve for the buffer

戻り値

成功した場合に true を、失敗した場合に false を返します。


Prevent calls that modify an event buffer from succeeding

  • ≪ EventBuffer::expand
  • EventBuffer::lock ≫
  • PHP Manual
  • EventBuffer
  • Prevent calls that modify an event buffer from succeeding

EventBuffer::freeze

(PECL event >= 1.2.6-beta)

EventBuffer::freeze — Prevent calls that modify an event buffer from succeeding

説明

public EventBuffer::freeze( bool $at_front ): bool

Prevent calls that modify an event buffer from succeeding

パラメータ

at_front

Whether to disable changes to the front or end of the buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::unfreeze() - Re-enable calls that modify an event buffer


Acquires a lock on buffer

  • ≪ EventBuffer::freeze
  • EventBuffer::prepend ≫
  • PHP Manual
  • EventBuffer
  • Acquires a lock on buffer

EventBuffer::lock

(PECL event >= 1.2.6-beta)

EventBuffer::lock — Acquires a lock on buffer

説明

public EventBuffer::lock(): void

Acquires a lock on buffer. Can be used in pair with EventBuffer::unlock() to make a set of operations atomic, i.e. thread-safe. Note, it is not needed to lock buffers for individual operations. When locking is enabled(see EventBuffer::enableLocking() ), individual operations on event buffers are already atomic.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EventBuffer::unlock() - Releases lock acquired by EventBuffer::lock


Prepend data to the front of the buffer

  • ≪ EventBuffer::lock
  • EventBuffer::prependBuffer ≫
  • PHP Manual
  • EventBuffer
  • Prepend data to the front of the buffer

EventBuffer::prepend

(PECL event >= 1.2.6-beta)

EventBuffer::prepend — Prepend data to the front of the buffer

説明

public EventBuffer::prepend( string $data ): bool

Prepend data to the front of the buffer.

パラメータ

data

String to be prepended to the front of the buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::prependBuffer() - Moves all data from source buffer to the front of current buffer
  • EventBuffer::add() - Append data to the end of an event buffer
  • EventBuffer::addBuffer() - Move all data from a buffer provided to the current instance of EventBuffer


Moves all data from source buffer to the front of current buffer

  • ≪ EventBuffer::prepend
  • EventBuffer::pullup ≫
  • PHP Manual
  • EventBuffer
  • Moves all data from source buffer to the front of current buffer

EventBuffer::prependBuffer

(PECL event >= 1.2.6-beta)

EventBuffer::prependBuffer — Moves all data from source buffer to the front of current buffer

説明

public EventBuffer::prependBuffer( EventBuffer $buf ): bool

Behaves as EventBuffer::addBuffer() , except that it moves data to the front of the buffer.

パラメータ

buf

Source buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::add() - Append data to the end of an event buffer
  • EventBuffer::addBuffer() - Move all data from a buffer provided to the current instance of EventBuffer
  • EventBuffer::prepend() - Prepend data to the front of the buffer


Linearizes data within buffer and returns it's contents as a string

  • ≪ EventBuffer::prependBuffer
  • EventBuffer::read ≫
  • PHP Manual
  • EventBuffer
  • Linearizes data within buffer and returns it's contents as a string

EventBuffer::pullup

(PECL event >= 1.2.6-beta)

EventBuffer::pullup — Linearizes data within buffer and returns it's contents as a string

説明

public EventBuffer::pullup( int $size ): string

"Linearizes" the first size bytes of the buffer, copying or moving them as needed to ensure that they are all contiguous and occupying the same chunk of memory. If size is negative, the function linearizes the entire buffer.

警告

Calling EventBuffer::pullup() with a large size can be quite slow, since it potentially needs to copy the entire buffer's contents.

パラメータ

size

The number of bytes required to be contiguous within the buffer.

戻り値

If size is greater than the number of bytes in the buffer, the function returns null. Otherwise, EventBuffer::pullup() returns string.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer


Read data from an evbuffer and drain the bytes read

  • ≪ EventBuffer::pullup
  • EventBuffer::readFrom ≫
  • PHP Manual
  • EventBuffer
  • Read data from an evbuffer and drain the bytes read

EventBuffer::read

(PECL event >= 1.6.0)

EventBuffer::read — Read data from an evbuffer and drain the bytes read

説明

public EventBuffer::read( int $max_bytes ): string

Read the first max_bytes from the buffer and drain the bytes read. If more max_bytes are requested than are available in the buffer, it only extracts as many bytes as available.

パラメータ

max_bytes

Maxmimum number of bytes to read from the buffer.

戻り値

Returns string read, or false on failure.

変更履歴

バージョン | 説明
PECL event 1.6.0 | Renamed EventBuffer::read()(the old method name) to EventBuffer::read(). EventBuffer::read() now takes only max_bytes argument; returns string instead of integer.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer


Read data from a file onto the end of the buffer

  • ≪ EventBuffer::read
  • EventBuffer::readLine ≫
  • PHP Manual
  • EventBuffer
  • Read data from a file onto the end of the buffer

EventBuffer::readFrom

(PECL event >= 1.7.0)

EventBuffer::readFrom — Read data from a file onto the end of the buffer

説明

public EventBuffer::read( mixed $fd , int $howmuch ): int

Read data from the file specified by fd onto the end of the buffer.

パラメータ

fd

Socket resource, stream, or numeric file descriptor.

howmuch

Maxmimum number of bytes to read.

戻り値

Returns the number of bytes read, or false on failure.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::readLine() - Extracts a line from the front of the buffer
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer


Extracts a line from the front of the buffer

  • ≪ EventBuffer::readFrom
  • EventBuffer::search ≫
  • PHP Manual
  • EventBuffer
  • Extracts a line from the front of the buffer

EventBuffer::readLine

(PECL event >= 1.2.6-beta)

EventBuffer::readLine — Extracts a line from the front of the buffer

説明

public EventBuffer::readLine( int $eol_style ): string

Extracts a line from the front of the buffer and returns it in a newly allocated string. If there is not a whole line to read, the function returns null. The line terminator is not included in the copied string.

パラメータ

eol_style

One of EventBuffer:EOL_* constants .

戻り値

On success returns the line read from the buffer, otherwise null.

参考

  • EventBuffer::copyout() - Copies out specified number of bytes from the front of the buffer
  • EventBuffer::drain() - Removes specified number of bytes from the front of the buffer without copying it anywhere
  • EventBuffer::pullup() - Linearizes data within buffer and returns it's contents as a string
  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read
  • EventBuffer::appendFrom() - Moves the specified number of bytes from a source buffer to the end of the current buffer


Scans the buffer for an occurrence of a string

  • ≪ EventBuffer::readLine
  • EventBuffer::searchEol ≫
  • PHP Manual
  • EventBuffer
  • Scans the buffer for an occurrence of a string

EventBuffer::search

(PECL event >= 1.2.6-beta)

EventBuffer::search — Scans the buffer for an occurrence of a string

説明

public EventBuffer::search( string $what , int $start = -1 , int $end = -1 ): mixed

Scans the buffer for an occurrence of the string what . It returns numeric position of the string, or false if the string was not found.

If the start argument is provided, it points to the position at which the search should begin; otherwise, the search is performed from the start of the string. If end argument provided, the search is performed between start and end buffer positions.

パラメータ

what

String to search.

start

Start search position.

end

End search position.

戻り値

Returns numeric position of the first occurrence of the string in the buffer, or false if string is not found.

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 EventBuffer::search() example

<?php
// Count total occurrences of 'str' in 'buf'
function count_instances($buf, $str) {
$total = 0;
$p = 0;
$i = 0;

while (1) {
$p = $buf->search($str, $p);
if ($p === FALSE) {
break;
}
++$total;
++$p;
}

return $total;
}

$buf = new EventBuffer();
$buf->add("Some string within a string inside another string");
var_dump(count_instances($buf, "str"));
?>

上の例の出力は、 たとえば以下のようになります。

int(3)

参考

  • EventBuffer::searchEol() - Scans the buffer for an occurrence of an end of line


Scans the buffer for an occurrence of an end of line

  • ≪ EventBuffer::search
  • EventBuffer::substr ≫
  • PHP Manual
  • EventBuffer
  • Scans the buffer for an occurrence of an end of line

EventBuffer::searchEol

(PECL event >= 1.5.0)

EventBuffer::searchEol — Scans the buffer for an occurrence of an end of line

説明

public EventBuffer::searchEol( int $start = -1 , int $eol_style = EventBuffer::EOL_ANY ): mixed

Scans the buffer for an occurrence of an end of line specified by eol_style parameter . It returns numeric position of the string, or false if the string was not found.

If the start argument is provided, it represents the position at which the search should begin; otherwise, the search is performed from the start of the string. If end argument provided, the search is performed between start and end buffer positions.

パラメータ

start

Start search position.

eol_style

One of EventBuffer:EOL_* constants .

戻り値

Returns numeric position of the first occurrence of end-of-line symbol in the buffer, or false if not found.

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

参考

  • EventBuffer::search() - Scans the buffer for an occurrence of a string


Substracts a portion of the buffer data

  • ≪ EventBuffer::searchEol
  • EventBuffer::unfreeze ≫
  • PHP Manual
  • EventBuffer
  • Substracts a portion of the buffer data

EventBuffer::substr

(PECL event >= 1.6.0)

EventBuffer::substr — Substracts a portion of the buffer data

説明

public EventBuffer::substr( int $start , int $length = ?): string

Substracts up to length bytes of the buffer data beginning at start position.

パラメータ

start

The start position of data to be substracted.

length

Maximum number of bytes to substract.

戻り値

Returns the data substracted as a string on success, or false on failure.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read


Re-enable calls that modify an event buffer

  • ≪ EventBuffer::substr
  • EventBuffer::unlock ≫
  • PHP Manual
  • EventBuffer
  • Re-enable calls that modify an event buffer

EventBuffer::unfreeze

(PECL event >= 1.2.6-beta)

EventBuffer::unfreeze — Re-enable calls that modify an event buffer

説明

public EventBuffer::unfreeze( bool $at_front ): bool

Re-enable calls that modify an event buffer.

パラメータ

at_front

Whether to enable events at the front or at the end of the buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::freeze() - Prevent calls that modify an event buffer from succeeding


Releases lock acquired by EventBuffer::lock

  • ≪ EventBuffer::unfreeze
  • EventBuffer::write ≫
  • PHP Manual
  • EventBuffer
  • Releases lock acquired by EventBuffer::lock

EventBuffer::unlock

(PECL event >= 1.2.6-beta)

EventBuffer::unlock — Releases lock acquired by EventBuffer::lock

説明

public EventBuffer::unlock(): bool

Releases lock acquired by EventBuffer::lock() .

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBuffer::lock() - Acquires a lock on buffer


Write contents of the buffer to a file or socket

  • ≪ EventBuffer::unlock
  • EventBufferEvent ≫
  • PHP Manual
  • EventBuffer
  • Write contents of the buffer to a file or socket

EventBuffer::write

(PECL event >= 1.6.0)

EventBuffer::write — Write contents of the buffer to a file or socket

説明

public EventBuffer::write( mixed $fd , int $howmuch = ?): int

Write contents of the buffer to a file descriptor. The buffer will be drained after the bytes have been successfully written.

パラメータ

fd

Socket resource, stream or numeric file descriptor associated normally associated with a socket.

howmuch

The maximum number of bytes to write.

戻り値

Returns the number of bytes written, or false on error.

参考

  • EventBuffer::read() - Read data from an evbuffer and drain the bytes read


The EventBufferEvent class

(PECL event >= 1.2.6-beta)

はじめに

Represents Libevent's buffer event.

Usually an application wants to perform some amount of data buffering in addition to just responding to events. When we want to write data, for example, the usual pattern looks like:

  1. Decide that we want to write some data to a connection; put that data in a buffer.

  2. Wait for the connection to become writable

  3. Write as much of the data as we can

  4. Remember how much we wrote, and if we still have more data to write, wait for the connection to become writable again.

This buffered I/O pattern is common enough that Libevent provides a generic mechanism for it. A "buffer event" consists of an underlying transport (like a socket), a read buffer, and a write buffer. Instead of regular events, which give callbacks when the underlying transport is ready to be read or written, a buffer event invokes its user-supplied callbacks when it has read or written enough data.

クラス概要

final class EventBufferEvent {
/* 定数 */
const int READING = 1;
const int WRITING = 2;
const int EOF = 16;
const int ERROR = 32;
const int TIMEOUT = 64;
const int CONNECTED = 128;
const int OPT_CLOSE_ON_FREE = 1;
const int OPT_THREADSAFE = 2;
const int OPT_DEFER_CALLBACKS = 4;
const int OPT_UNLOCK_CALLBACKS = 8;
const int SSL_OPEN = 0;
const int SSL_CONNECTING = 1;
const int SSL_ACCEPTING = 2;
/* プロパティ */
public int $fd;
public int $priority;
public readonly EventBuffer $input;
public readonly EventBuffer $output;
/* メソッド */
public close(): void
public connect( string $addr ): bool
public connectHost(
EventDnsBase $dns_base ,
string $hostname ,
int $port ,
int $family = EventUtil::AF_UNSPEC
): bool
public __construct(
EventBase $base ,
mixed $socket = null ,
int $options = 0 ,
callable $readcb = null ,
callable $writecb = null ,
callable $eventcb = null ,
mixed $arg = null
)
public static createPair( EventBase $base , int $options = 0 ): array
public disable( int $events ): bool
public enable( int $events ): bool
public free(): void
public getDnsErrorString(): string
public getEnabled(): int
public getInput(): EventBuffer
public getOutput(): EventBuffer
public read( int $size ): string
public readBuffer( EventBuffer $buf ): bool
public setCallbacks(
callable $readcb ,
callable $writecb ,
callable $eventcb ,
mixed $arg = ?
): void
public setPriority( int $priority ): bool
public setTimeouts( float $timeout_read , float $timeout_write ): bool
public setWatermark( int $events , int $lowmark , int $highmark ): void
public sslError(): string
public static sslFilter(
EventBase $base ,
EventBufferEvent $underlying ,
EventSslContext $ctx ,
int $state ,
int $options = 0
): EventBufferEvent
public sslGetCipherInfo(): string
public sslGetCipherName(): string
public sslGetCipherVersion(): string
public sslGetProtocol(): string
public sslRenegotiate(): void
public static sslSocket(
EventBase $base ,
mixed $socket ,
EventSslContext $ctx ,
int $state ,
int $options = ?
): EventBufferEvent
public write( string $data ): bool
public writeBuffer( EventBuffer $buf ): bool
}

プロパティ

fd

Numeric file descriptor associated with the buffer event. Normally represents a bound socket. Equals to null, if there is no file descriptor(socket) associated with the buffer event.

priority

The priority of the events used to implement the buffer event.

input

Underlying input buffer object( EventBuffer )

output

Underlying output buffer object( EventBuffer )

定義済み定数

EventBufferEvent::READING

An event occurred during a read operation on the bufferevent. See the other flags for which event it was.

EventBufferEvent::WRITING

An event occurred during a write operation on the bufferevent. See the other flags for which event it was.

EventBufferEvent::EOF

Got an end-of-file indication on the buffer event.

EventBufferEvent::ERROR

An error occurred during a bufferevent operation. For more information on what the error was, call EventUtil::getLastSocketErrno() and/or EventUtil::getLastSocketError() .

EventBufferEvent::TIMEOUT

EventBufferEvent::CONNECTED

Finished a requested connection on the bufferevent.

EventBufferEvent::OPT_CLOSE_ON_FREE

When the buffer event is freed, close the underlying transport. This will close an underlying socket, free an underlying buffer event, etc.

EventBufferEvent::OPT_THREADSAFE

Automatically allocate locks for the bufferevent, so that it's safe to use from multiple threads.

EventBufferEvent::OPT_DEFER_CALLBACKS

When this flag is set, the bufferevent defers all of its callbacks. See » Fast portable non-blocking network programming with Libevent, Deferred callbacks .

EventBufferEvent::OPT_UNLOCK_CALLBACKS

By default, when the bufferevent is set up to be threadsafe, the buffer event's locks are held whenever the any user-provided callback is invoked. Setting this option makes Libevent release the buffer event's lock when it's invoking the callbacks.

EventBufferEvent::SSL_OPEN

The SSL handshake is done

EventBufferEvent::SSL_CONNECTING

SSL is currently performing negotiation as a client

EventBufferEvent::SSL_ACCEPTING

SSL is currently performing negotiation as a server

目次

  • EventBufferEvent::close — Closes file descriptor associated with the current buffer event
  • EventBufferEvent::connect — Connect buffer event's file descriptor to given address or UNIX socket
  • EventBufferEvent::connectHost — Connects to a hostname with optionally asyncronous DNS resolving
  • EventBufferEvent::__construct — Constructs EventBufferEvent object
  • EventBufferEvent::createPair — Creates two buffer events connected to each other
  • EventBufferEvent::disable — Disable events read, write, or both on a buffer event
  • EventBufferEvent::enable — Enable events read, write, or both on a buffer event
  • EventBufferEvent::free — Free a buffer event
  • EventBufferEvent::getDnsErrorString — Returns string describing the last failed DNS lookup attempt
  • EventBufferEvent::getEnabled — Returns bitmask of events currently enabled on the buffer event
  • EventBufferEvent::getInput — Returns underlying input buffer associated with current buffer event
  • EventBufferEvent::getOutput — Returns underlying output buffer associated with current buffer event
  • EventBufferEvent::read — Read buffer's data
  • EventBufferEvent::readBuffer — Drains the entire contents of the input buffer and places them into buf
  • EventBufferEvent::setCallbacks — Assigns read, write and event(status) callbacks
  • EventBufferEvent::setPriority — Assign a priority to a bufferevent
  • EventBufferEvent::setTimeouts — Set the read and write timeout for a buffer event
  • EventBufferEvent::setWatermark — Adjusts read and/or write watermarks
  • EventBufferEvent::sslError — Returns most recent OpenSSL error reported on the buffer event
  • EventBufferEvent::sslFilter — Create a new SSL buffer event to send its data over another buffer event
  • EventBufferEvent::sslGetCipherInfo — Returns a textual description of the cipher
  • EventBufferEvent::sslGetCipherName — Returns the current cipher name of the SSL connection
  • EventBufferEvent::sslGetCipherVersion — Returns version of cipher used by current SSL connection
  • EventBufferEvent::sslGetProtocol — Returns the name of the protocol used for current SSL connection
  • EventBufferEvent::sslRenegotiate — Tells a bufferevent to begin SSL renegotiation
  • EventBufferEvent::sslSocket — Creates a new SSL buffer event to send its data over an SSL on a socket
  • EventBufferEvent::write — Adds data to a buffer event's output buffer
  • EventBufferEvent::writeBuffer — Adds contents of the entire buffer to a buffer event's output buffer


Closes file descriptor associated with the current buffer event

  • ≪ EventBufferEvent
  • EventBufferEvent::connect ≫
  • PHP Manual
  • EventBufferEvent
  • Closes file descriptor associated with the current buffer event

EventBufferEvent::close

(PECL event >= 1.10.0)

EventBufferEvent::close — Closes file descriptor associated with the current buffer event

説明

public EventBufferEvent::close(): void

Closes file descriptor associated with the current buffer event.

This method may be used in cases when the EventBufferEvent::OPT_CLOSE_ON_FREE option is not appropriate.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Connect buffer event's file descriptor to given address or UNIX socket

  • ≪ EventBufferEvent::close
  • EventBufferEvent::connectHost ≫
  • PHP Manual
  • EventBufferEvent
  • Connect buffer event's file descriptor to given address or UNIX socket

EventBufferEvent::connect

(PECL event >= 1.2.6-beta)

EventBufferEvent::connect — Connect buffer event's file descriptor to given address or UNIX socket

説明

public EventBufferEvent::connect( string $addr ): bool

Connect buffer event's file descriptor to given address(optionally with port), or a UNIX domain socket.

If socket is not assigned to the buffer event, this function allocates a new socket and makes it non-blocking internally.

To resolve DNS names(asyncronously), use EventBufferEvent::connectHost() method.

パラメータ

addr

Should contain an IP address with optional port number, or a path to UNIX domain socket. Recognized formats are:

[IPv6Address]:port
[IPv6Address]
IPv6Address
IPv4Address:port
IPv4Address
unix:path
Note, 'unix:' prefix is currently not case sensitive.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventBufferEvent::connect() example

<?php
/*
* 1. Connect to 127.0.0.1 at port 80
* by means of EventBufferEvent::connect().
*
* 2. Request /index.cphp via HTTP/1.0
* using the output buffer.
*
* 3. Asyncronously read the response and print it to stdout.
*/

/* Read callback */
function readcb($bev, $base) {
$input = $bev->getInput();

while (($n = $input->remove($buf, 1024)) > 0) {
echo $buf;
}
}

/* Event callback */
function eventcb($bev, $events, $base) {
if ($events & EventBufferEvent::CONNECTED) {
echo "Connected.\n";
} elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
if ($events & EventBufferEvent::ERROR) {
echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
}

echo "Closing\n";
$base->exit();
exit("Done\n");
}
}

$base = new EventBase();

echo "step 1\n";
$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS);
if (!$bev) {
exit("Failed creating bufferevent socket\n");
}

echo "step 2\n";
$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

echo "step 3\n";
/* Send request */
$output = $bev->getOutput();
if (!$output->add(
"GET /index.cphp HTTP/1.0\r\n".
"Connection: Close\r\n\r\n"
)) {
exit("Failed adding request to output buffer\n");
}

/* Connect to the host syncronously.
* We know the IP, and don't need to resolve DNS. */
if (!$bev->connect("127.0.0.1:80")) {
exit("Can't connect to host\n");
}

/* Dispatch pending events */
$base->dispatch();

上の例の出力は、 たとえば以下のようになります。

step 1
step 2
step 3
Connected.
HTTP/1.1 200 OK
Server: nginx/1.2.6
Date: Sat, 09 Mar 2013 10:06:58 GMT
Content-Type: text/html; CHARSET=shift-jis
Connection: close
X-Powered-By: PHP/5.4.11--pl2-gentoo

sdfsdfsf
Closing
Done

例2 Connect to UNIX domain socket which presumably is served by a server, read response from the server and output it to the console

<?php
class MyUnixSocketClient {
private $base, $bev;

function __construct($base, $sock_path) {
$this->base = $base;
$this->bev = new EventBufferEvent($base, NULL, EventBufferEvent::OPT_CLOSE_ON_FREE,
array ($this, "read_cb"), NULL, array ($this, "event_cb"));

if (!$this->bev->connect("unix:$sock_path")) {
trigger_error("Failed to connect to socket `$sock_path'", E_USER_ERROR);
}

$this->bev->enable(Event::READ);
}

function __destruct() {
if ($this->bev) {
$this->bev->free();
$this->bev = NULL;
}
}

function dispatch() {
$this->base->dispatch();
}

function read_cb($bev, $unused) {
$in = $bev->input;

printf("Received %ld bytes\n", $in->length);
printf("----- data ----\n");
printf("%ld:\t%s\n", (int) $in->length, $in->pullup(-1));

$this->bev->free();
$this->bev = NULL;
$this->base->exit(NULL);
}

function event_cb($bev, $events, $unused) {
if ($events & EventBufferEvent::ERROR) {
echo "Error from bufferevent\n";
}

if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
$bev->free();
$bev = NULL;
} elseif ($events & EventBufferEvent::CONNECTED) {
$bev->output->add("test\n");
}
}
}

if ($argc <= 1) {
exit("Socket path is not provided\n");
}
$sock_path = $argv[1];

$base = new EventBase();
$cl = new MyUnixSocketClient($base, $sock_path);
$cl->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Received 5 bytes
----- data ----
5:  test

参考

  • EventBufferEvent::connectHost() - Connects to a hostname with optionally asyncronous DNS resolving


Connects to a hostname with optionally asyncronous DNS resolving

  • ≪ EventBufferEvent::connect
  • EventBufferEvent::__construct ≫
  • PHP Manual
  • EventBufferEvent
  • Connects to a hostname with optionally asyncronous DNS resolving

EventBufferEvent::connectHost

(PECL event >= 1.2.6-beta)

EventBufferEvent::connectHost — Connects to a hostname with optionally asyncronous DNS resolving

説明

public EventBufferEvent::connectHost(
EventDnsBase $dns_base ,
string $hostname ,
int $port ,
int $family = EventUtil::AF_UNSPEC
): bool

Resolves the DNS name hostname, looking for addresses of type family ( EventUtil::AF_* constants). If the name resolution fails, it invokes the event callback with an error event. If it succeeds, it launches a connection attempt just as EventBufferEvent::connect() would.

dns_base is optional. May be null, or an object created with EventDnsBase::__construct() . For asyncronous hostname resolving pass a valid event dns base resource. Otherwise the hostname resolving will block.

注意:

EventDnsBase is available only if Event configured --with-event-extra ( event_extra library, libevent protocol-specific functionality support including HTTP, DNS, and RPC ).

注意:

EventBufferEvent::connectHost() requires libevent-2.0.3-alpha or greater.

パラメータ

dns_base

Object of EventDnsBase in case if DNS is to be resolved asyncronously. Otherwise null.

hostname

Hostname to connect to. Recognized formats are:

www.example.com (hostname)
 1.2.3.4 (ipv4address)
 ::1 (ipv6address)
[::1] ([ipv6address])

port

Port number

family

Address family. EventUtil::AF_UNSPEC , EventUtil::AF_INET , or EventUtil::AF_INET6 . See EventUtil constants .

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventBufferEvent::connectHost() example

<?php
/* Read callback */
function readcb($bev, $base) {
//$input = $bev->input; //$bev->getInput();

//$pos = $input->search("TTP");
$pos = $bev->input->search("TTP");

while (($n = $bev->input->remove($buf, 1024)) > 0) {
echo $buf;
}
}

/* Event callback */
function eventcb($bev, $events, $base) {
if ($events & EventBufferEvent::CONNECTED) {
echo "Connected.\n";
} elseif ($events & (EventBufferEvent::ERROR | EventBufferEvent::EOF)) {
if ($events & EventBufferEvent::ERROR) {
echo "DNS error: ", $bev->getDnsErrorString(), PHP_EOL;
}

echo "Closing\n";
$base->exit();
exit("Done\n");
}
}

$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // We'll use async DNS resolving
if (!$dns_base) {
exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
"readcb", /* writecb */ NULL, "eventcb", $base
);
if (!$bev) {
exit("Failed creating bufferevent socket\n");
}

//$bev->setCallbacks("readcb", /* writecb */ NULL, "eventcb", $base);
$bev->enable(Event::READ | Event::WRITE);

$output = $bev->output; //$bev->getOutput();
if (!$output->add(
"GET {$argv[2]} HTTP/1.0\r\n".
"Host: {$argv[1]}\r\n".
"Connection: Close\r\n\r\n"
)) {
exit("Failed adding request to output buffer\n");
}

if (!$bev->connectHost($dns_base, $argv[1], 80, EventUtil::AF_UNSPEC)) {
exit("Can't connect to host {$argv[1]}\n");
}

$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Connected.
HTTP/1.0 301 Moved Permanently
Location: http://www.google.co.uk/
Content-Type: text/html; CHARSET=shift-jis
Date: Sat, 09 Mar 2013 12:21:19 GMT
Expires: Mon, 08 Apr 2013 12:21:19 GMT
Cache-Control: public, max-age=2592000
Server: gws
Content-Length: 221
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN

<HTML><HEAD><meta http-equiv="content-type" content="text/html;CHARSET=shift-jis">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.co.uk/">here</A>.
</BODY></HTML>
Closing
Done

参考

  • EventBufferEvent::connect() - Connect buffer event's file descriptor to given address or UNIX socket


Constructs EventBufferEvent object

  • ≪ EventBufferEvent::connectHost
  • EventBufferEvent::createPair ≫
  • PHP Manual
  • EventBufferEvent
  • Constructs EventBufferEvent object

EventBufferEvent::__construct

(PECL event >= 1.2.6-beta)

EventBufferEvent::__construct — Constructs EventBufferEvent object

説明

public EventBufferEvent::__construct(
EventBase $base ,
mixed $socket = null ,
int $options = 0 ,
callable $readcb = null ,
callable $writecb = null ,
callable $eventcb = null ,
mixed $arg = null
)

Create a buffer event on a socket, stream or a file descriptor. Passing null to socket means that the socket should be created later, e.g. by means of EventBufferEvent::connect() .

パラメータ

base

Event base that should be associated with the new buffer event.

socket

May be created as a stream(not necessarily by means of sockets extension)

options

One of EventBufferEvent::OPT_* constants , or 0 .

readcb

Read event callback. See About buffer event callbacks .

writecb

Write event callback. See About buffer event callbacks .

eventcb

Status-change event callback. See About buffer event callbacks .

arg

A variable that will be passed to all the callbacks.

参考

  • EventBufferEvent::sslFilter() - Create a new SSL buffer event to send its data over another buffer event
  • EventBufferEvent::sslSocket() - Creates a new SSL buffer event to send its data over an SSL on a socket


Creates two buffer events connected to each other

  • ≪ EventBufferEvent::__construct
  • EventBufferEvent::disable ≫
  • PHP Manual
  • EventBufferEvent
  • Creates two buffer events connected to each other

EventBufferEvent::createPair

(PECL event >= 1.2.6-beta)

EventBufferEvent::createPair — Creates two buffer events connected to each other

説明

public static EventBufferEvent::createPair( EventBase $base , int $options = 0 ): array

Returns array of two EventBufferEvent objects connected to each other. All the usual options are supported, except for EventBufferEvent::OPT_CLOSE_ON_FREE , which has no effect, and EventBufferEvent::OPT_DEFER_CALLBACKS , which is always on.

パラメータ

base

Associated event base

options

EventBufferEvent::OPT_* constants combined with bitwise OR operator.

戻り値

Returns array of two EventBufferEvent objects connected to each other.

変更履歴

バージョン | 説明
PECL event 1.9.0 | Method made static.


Disable events read, write, or both on a buffer event

  • ≪ EventBufferEvent::createPair
  • EventBufferEvent::enable ≫
  • PHP Manual
  • EventBufferEvent
  • Disable events read, write, or both on a buffer event

EventBufferEvent::disable

(PECL event >= 1.2.6-beta)

EventBufferEvent::disable — Disable events read, write, or both on a buffer event

説明

public EventBufferEvent::disable( int $events ): bool

Disable events Event::READ , Event::WRITE , or Event::READ | Event::WRITE on a buffer event.

パラメータ

events

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBufferEvent::enable() - Enable events read, write, or both on a buffer event


Enable events read, write, or both on a buffer event

  • ≪ EventBufferEvent::disable
  • EventBufferEvent::free ≫
  • PHP Manual
  • EventBufferEvent
  • Enable events read, write, or both on a buffer event

EventBufferEvent::enable

(PECL event >= 1.2.6-beta)

EventBufferEvent::enable — Enable events read, write, or both on a buffer event

説明

public EventBufferEvent::enable( int $events ): bool

Enable events Event::READ , Event::WRITE , or Event::READ | Event::WRITE on a buffer event.

パラメータ

events

Event::READ , Event::WRITE , or Event::READ | Event::WRITE on a buffer event.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBufferEvent::disable() - Disable events read, write, or both on a buffer event


Free a buffer event

  • ≪ EventBufferEvent::enable
  • EventBufferEvent::getDnsErrorString ≫
  • PHP Manual
  • EventBufferEvent
  • Free a buffer event

EventBufferEvent::free

(PECL event >= 1.2.6-beta)

EventBufferEvent::free — Free a buffer event

説明

public EventBufferEvent::free(): void

Free resources allocated by buffer event.

Usually there is no need to call this method, since normally it is done within internal object destructors. However, sometimes we have a long-time script allocating lots of instances, or a script with a heavy memory usage, where we need to free resources as soon as possible. In such cases EventBufferEvent::free() may be used to protect the script against running up to the memory_limit .

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Returns string describing the last failed DNS lookup attempt

  • ≪ EventBufferEvent::free
  • EventBufferEvent::getEnabled ≫
  • PHP Manual
  • EventBufferEvent
  • Returns string describing the last failed DNS lookup attempt

EventBufferEvent::getDnsErrorString

(PECL event >= 1.2.6-beta)

EventBufferEvent::getDnsErrorString — Returns string describing the last failed DNS lookup attempt

説明

public EventBufferEvent::getDnsErrorString(): string

Returns string describing the last failed DNS lookup attempt made by EventBufferEvent::connectHost() , or an empty string, if there is no DNS error detected.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string describing DNS lookup error, or an empty string for no error.

参考

  • EventBufferEvent::connectHost() - Connects to a hostname with optionally asyncronous DNS resolving


Returns bitmask of events currently enabled on the buffer event

  • ≪ EventBufferEvent::getDnsErrorString
  • EventBufferEvent::getInput ≫
  • PHP Manual
  • EventBufferEvent
  • Returns bitmask of events currently enabled on the buffer event

EventBufferEvent::getEnabled

(PECL event >= 1.2.6-beta)

EventBufferEvent::getEnabled — Returns bitmask of events currently enabled on the buffer event

説明

public EventBufferEvent::getEnabled(): int

Returns bitmask of events currently enabled on the buffer event

パラメータ

この関数にはパラメータはありません。

戻り値

Returns integer representing a bitmask of events currently enabled on the buffer event

参考

  • EventBufferEvent::enable() - Enable events read, write, or both on a buffer event
  • EventBufferEvent::disable() - Disable events read, write, or both on a buffer event


Returns underlying input buffer associated with current buffer event

  • ≪ EventBufferEvent::getEnabled
  • EventBufferEvent::getOutput ≫
  • PHP Manual
  • EventBufferEvent
  • Returns underlying input buffer associated with current buffer event

EventBufferEvent::getInput

(PECL event >= 1.2.6-beta)

EventBufferEvent::getInput — Returns underlying input buffer associated with current buffer event

説明

public EventBufferEvent::getInput(): EventBuffer

Returns underlying input buffer associated with current buffer event. An input buffer is a storage for data to read.

Note, there is also input property of EventBufferEvent class.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns instance of EventBuffer input buffer associated with current buffer event.

例

例1 Buffer event's read callback

<?php
function readcb($bev, $base) {
$input = $bev->input; //$bev->getInput();

while (($n = $input->remove($buf, 1024)) > 0) {
echo $buf;
}
}
?>

参考

  • EventBufferEvent::getOutput() - Returns underlying output buffer associated with current buffer event


Returns underlying output buffer associated with current buffer event

  • ≪ EventBufferEvent::getInput
  • EventBufferEvent::read ≫
  • PHP Manual
  • EventBufferEvent
  • Returns underlying output buffer associated with current buffer event

EventBufferEvent::getOutput

(PECL event >= 1.2.6-beta)

EventBufferEvent::getOutput — Returns underlying output buffer associated with current buffer event

説明

public EventBufferEvent::getOutput(): EventBuffer

Returns underlying output buffer associated with current buffer event. An output buffer is a storage for data to be written.

Note, there is also output property of EventBufferEvent class.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns instance of EventBuffer output buffer associated with current buffer event.

例

例1 EventBufferEvent::getOutput() example

<?php
$base = new EventBase();

$dns_base = new EventDnsBase($base, TRUE); // Use async DNS resolving
if (!$dns_base) {
exit("Failed to init DNS Base\n");
}

$bev = new EventBufferEvent($base, /* use internal socket */ NULL,
EventBufferEvent::OPT_CLOSE_ON_FREE | EventBufferEvent::OPT_DEFER_CALLBACKS,
"readcb", /* writecb */ NULL, "eventcb", $base
);
if (!$bev) {
exit("Failed creating bufferevent socket\n");
}

$bev->enable(Event::READ | Event::WRITE);

$output = $bev->getOutput();
if (!$output->add(
"GET {$argv[2]} HTTP/1.0\r\n".
"Host: {$argv[1]}\r\n".
"Connection: Close\r\n\r\n"
)) {
exit("Failed adding request to output buffer\n");
}

/* ... */
?>

参考

  • EventBufferEvent::getInput() - Returns underlying input buffer associated with current buffer event


Read buffer's data

  • ≪ EventBufferEvent::getOutput
  • EventBufferEvent::readBuffer ≫
  • PHP Manual
  • EventBufferEvent
  • Read buffer's data

EventBufferEvent::read

(PECL event >= 1.2.6-beta)

EventBufferEvent::read — Read buffer's data

説明

public EventBufferEvent::read( int $size ): string

Removes up to size bytes from the input buffer. Returns a string of data read from the input buffer.

パラメータ

size

Maximum number of bytes to read

戻り値

Returns string of data read from the input buffer.

参考

  • EventBufferEvent::readBuffer() - Drains the entire contents of the input buffer and places them into buf


Drains the entire contents of the input buffer and places them into buf

  • ≪ EventBufferEvent::read
  • EventBufferEvent::setCallbacks ≫
  • PHP Manual
  • EventBufferEvent
  • Drains the entire contents of the input buffer and places them into buf

EventBufferEvent::readBuffer

(PECL event >= 1.2.6-beta)

EventBufferEvent::readBuffer — Drains the entire contents of the input buffer and places them into buf

説明

public EventBufferEvent::readBuffer( EventBuffer $buf ): bool

Drains the entire contents of the input buffer and places them into buf .

パラメータ

buf

Target buffer

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBufferEvent::read() - Read buffer's data


Assigns read, write and event(status) callbacks

  • ≪ EventBufferEvent::readBuffer
  • EventBufferEvent::setPriority ≫
  • PHP Manual
  • EventBufferEvent
  • Assigns read, write and event(status) callbacks

EventBufferEvent::setCallbacks

(PECL event >= 1.2.6-beta)

EventBufferEvent::setCallbacks — Assigns read, write and event(status) callbacks

説明

public EventBufferEvent::setCallbacks(
callable $readcb ,
callable $writecb ,
callable $eventcb ,
mixed $arg = ?
): void

Assigns read, write and event(status) callbacks.

パラメータ

readcb

Read event callback. See About buffer event callbacks .

writecb

Write event callback. See About buffer event callbacks .

eventcb

Status-change event callback. See About buffer event callbacks .

arg

A variable that will be passed to all the callbacks.

戻り値

値を返しません。

参考

  • EventBufferEvent::__construct() - Constructs EventBufferEvent object


Assign a priority to a bufferevent

  • ≪ EventBufferEvent::setCallbacks
  • EventBufferEvent::setTimeouts ≫
  • PHP Manual
  • EventBufferEvent
  • Assign a priority to a bufferevent

EventBufferEvent::setPriority

(PECL event >= 1.2.6-beta)

EventBufferEvent::setPriority — Assign a priority to a bufferevent

説明

public EventBufferEvent::setPriority( int $priority ): bool

Assign a priority to a bufferevent

警告

Only supported for socket buffer events

パラメータ

priority

Priority value.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Set the read and write timeout for a buffer event

  • ≪ EventBufferEvent::setPriority
  • EventBufferEvent::setWatermark ≫
  • PHP Manual
  • EventBufferEvent
  • Set the read and write timeout for a buffer event

EventBufferEvent::setTimeouts

(PECL event >= 1.2.6-beta)

EventBufferEvent::setTimeouts — Set the read and write timeout for a buffer event

説明

public EventBufferEvent::setTimeouts( float $timeout_read , float $timeout_write ): bool

Set the read and write timeout for a buffer event

パラメータ

timeout_read

Read timeout

timeout_write

Write timeout

戻り値

成功した場合に true を、失敗した場合に false を返します。


Adjusts read and/or write watermarks

  • ≪ EventBufferEvent::setTimeouts
  • EventBufferEvent::sslError ≫
  • PHP Manual
  • EventBufferEvent
  • Adjusts read and/or write watermarks

EventBufferEvent::setWatermark

(PECL event >= 1.2.6-beta)

EventBufferEvent::setWatermark — Adjusts read and/or write watermarks

説明

public EventBufferEvent::setWatermark( int $events , int $lowmark , int $highmark ): void

Adjusts the read watermarks, the write watermarks , or both, of a single buffer event.

A buffer event watermark is an edge, a value specifying number of bytes to be read or written before callback is invoked. By default every read/write event triggers a callback invokation. See » Fast portable non-blocking network programming with Libevent: Callbacks and watermarks

パラメータ

events

Bitmask of Event::READ , Event::WRITE , or both.

lowmark

Minimum watermark value.

highmark

Maximum watermark value. 0 means "unlimited".

戻り値

値を返しません。


Returns most recent OpenSSL error reported on the buffer event

  • ≪ EventBufferEvent::setWatermark
  • EventBufferEvent::sslFilter ≫
  • PHP Manual
  • EventBufferEvent
  • Returns most recent OpenSSL error reported on the buffer event

EventBufferEvent::sslError

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslError — Returns most recent OpenSSL error reported on the buffer event

説明

public EventBufferEvent::sslError(): string

Returns most recent OpenSSL error reported on the buffer event.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns OpenSSL error string reported on the buffer event, or false, if there is no more error to return.

例

例1 EventBufferEvent::sslError() example

<?php
// This callback is invoked when some even occurs on the event listener,
// e.g. connection closed, or an error occurred
function ssl_event_cb($bev, $events, $ctx) {
if ($events & EventBufferEvent::ERROR) {
// Fetch errors from the SSL error stack
while ($err = $bev->sslError()) {
fprintf(STDERR, "Bufferevent error %s.\n", $err);
}
}

if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
$bev->free();
}
}
?>

参考

  • EventBufferEvent::sslRenegotiate() - Tells a bufferevent to begin SSL renegotiation


Create a new SSL buffer event to send its data over another buffer event

  • ≪ EventBufferEvent::sslError
  • EventBufferEvent::sslGetCipherInfo ≫
  • PHP Manual
  • EventBufferEvent
  • Create a new SSL buffer event to send its data over another buffer event

EventBufferEvent::sslFilter

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslFilter — Create a new SSL buffer event to send its data over another buffer event

説明

public static EventBufferEvent::sslFilter(
EventBase $base ,
EventBufferEvent $underlying ,
EventSslContext $ctx ,
int $state ,
int $options = 0
): EventBufferEvent

Create a new SSL buffer event to send its data over another buffer event

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

base

Associated event base.

underlying

A socket buffer event to use for this SSL.

ctx

Object of EventSslContext class.

state

The current state of SSL connection: EventBufferEvent::SSL_OPEN , EventBufferEvent::SSL_ACCEPTING or EventBufferEvent::SSL_CONNECTING .

options

One or more buffer event options.

戻り値

Returns a new SSL EventBufferEvent object.

例

例1 Simple SMTP server

<?php
/*
* Author: Andrew Rose <hello at andrewrose dot co dot uk>
*
* Usage:
* 1) Prepare cert.pem certificate and privkey.pem private key files.
* 2) Launch the server script
* 3) Open TLS connection, e.g.:
* $ openssl s_client -connect localhost:25 -starttls smtp -crlf
* 4) Start testing the commands listed in `cmd` method below.
*/

class Handler {
public $domainName = FALSE;
public $connections = [];
public $buffers = [];
public $maxRead = 256000;

public function __construct() {
$this->ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, [
EventSslContext::OPT_LOCAL_CERT => 'cert.pem',
EventSslContext::OPT_LOCAL_PK => 'privkey.pem',
//EventSslContext::OPT_PASSPHRASE => '',
EventSslContext::OPT_VERIFY_PEER => false, // change to true with authentic cert
EventSslContext::OPT_ALLOW_SELF_SIGNED => true // change to false with authentic cert
]);

$this->base = new EventBase();
if (!$this->base) {
exit("Couldn't open event base\n");
}

if (!$this->listener = new EventListener($this->base,
[$this, 'ev_accept'],
$this->ctx,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
-1,
'0.0.0.0:25'))
{
exit("Couldn't create listener\n");
}

$this->listener->setErrorCallback([$this, 'ev_error']);
$this->base->dispatch();
}

public function ev_accept($listener, $fd, $address, $ctx) {
static $id = 0;
$id += 1;

$this->connections[$id]['clientData'] = '';
$this->connections[$id]['cnx'] = new EventBufferEvent($this->base, $fd,
EventBufferEvent::OPT_CLOSE_ON_FREE);

if (!$this->connections[$id]['cnx']) {
echo "Failed creating buffer\n";
$this->base->exit(NULL);
exit(1);
}

$this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL,
[$this, 'ev_error'], $id);
$this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);

$this->ev_write($id, '220 '.$this->domainName." wazzzap?\r\n");
}

function ev_error($listener, $ctx) {
$errno = EventUtil::getLastSocketErrno();

fprintf(STDERR, "Got an error %d (%s) on the listener. Shutting down.\n",
$errno, EventUtil::getLastSocketError());

if ($errno != 0) {
$this->base->exit(NULL);
exit();
}
}

public function ev_close($id) {
$this->connections[$id]['cnx']->disable(Event::READ | Event::WRITE);
unset($this->connections[$id]);
}

protected function ev_write($id, $string) {
echo 'S('.$id.'): '.$string;
$this->connections[$id]['cnx']->write($string);
}

public function ev_read($buffer, $id) {
while($buffer->input->length > 0) {
$this->connections[$id]['clientData'] .= $buffer->input->read($this->maxRead);
$clientDataLen = strlen($this->connections[$id]['clientData']);

if($this->connections[$id]['clientData'][$clientDataLen-1] == "\n"
&& $this->connections[$id]['clientData'][$clientDataLen-2] == "\r")
{
// remove the trailing \r\n
$line = substr($this->connections[$id]['clientData'], 0,
strlen($this->connections[$id]['clientData']) - 2);

$this->connections[$id]['clientData'] = '';
$this->cmd($buffer, $id, $line);
}
}
}

protected function cmd($buffer, $id, $line) {
switch ($line) {
case strncmp('EHLO ', $line, 4):
$this->ev_write($id, "250-STARTTLS\r\n");
$this->ev_write($id, "250 OK ehlo\r\n");
break;

case strncmp('HELO ', $line, 4):
$this->ev_write($id, "250-STARTTLS\r\n");
$this->ev_write($id, "250 OK helo\r\n");
break;

case strncmp('QUIT', $line, 3):
$this->ev_write($id, "250 OK quit\r\n");
$this->ev_close($id);
break;

case strncmp('STARTTLS', $line, 3):
$this->ev_write($id, "220 Ready to start TLS\r\n");
$this->connections[$id]['cnx'] = EventBufferEvent::sslFilter($this->base,
$this->connections[$id]['cnx'], $this->ctx,
EventBufferEvent::SSL_ACCEPTING,
EventBufferEvent::OPT_CLOSE_ON_FREE);
$this->connections[$id]['cnx']->setCallbacks([$this, "ev_read"], NULL, [$this, 'ev_error'], $id);
$this->connections[$id]['cnx']->enable(Event::READ | Event::WRITE);
break;

default:
echo 'unknown command: '.$line."\n";
break;
}
}
}

new Handler();

参考

  • EventBufferEvent::sslSocket() - Creates a new SSL buffer event to send its data over an SSL on a socket


Returns a textual description of the cipher

  • ≪ EventBufferEvent::sslFilter
  • EventBufferEvent::sslGetCipherName ≫
  • PHP Manual
  • EventBufferEvent
  • Returns a textual description of the cipher

EventBufferEvent::sslGetCipherInfo

(PECL event >= 1.10.0)

EventBufferEvent::sslGetCipherInfo — Returns a textual description of the cipher

説明

public EventBufferEvent::sslGetCipherInfo(): string

Retrieves description of the current cipher by means of the SSL_CIPHER_description SSL API function (see SSL_CIPHER_get_name(3) man page).

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a textual description of the cipher on success, or false on error.


Returns the current cipher name of the SSL connection

  • ≪ EventBufferEvent::sslGetCipherInfo
  • EventBufferEvent::sslGetCipherVersion ≫
  • PHP Manual
  • EventBufferEvent
  • Returns the current cipher name of the SSL connection

EventBufferEvent::sslGetCipherName

(PECL event >= 1.10.0)

EventBufferEvent::sslGetCipherName — Returns the current cipher name of the SSL connection

説明

public EventBufferEvent::sslGetCipherName(): string

Retrieves name of cipher used by current SSL connection.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current cipher name of the SSL connection, or false on error.


Returns version of cipher used by current SSL connection

  • ≪ EventBufferEvent::sslGetCipherName
  • EventBufferEvent::sslGetProtocol ≫
  • PHP Manual
  • EventBufferEvent
  • Returns version of cipher used by current SSL connection

EventBufferEvent::sslGetCipherVersion

(PECL event >= 1.10.0)

EventBufferEvent::sslGetCipherVersion — Returns version of cipher used by current SSL connection

説明

public EventBufferEvent::sslGetCipherVersion(): string

Retrieves version of cipher used by current SSL connection.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current cipher version of the SSL connection, or false on error.


Returns the name of the protocol used for current SSL connection

  • ≪ EventBufferEvent::sslGetCipherVersion
  • EventBufferEvent::sslRenegotiate ≫
  • PHP Manual
  • EventBufferEvent
  • Returns the name of the protocol used for current SSL connection

EventBufferEvent::sslGetProtocol

(PECL event >= 1.10.0)

EventBufferEvent::sslGetProtocol — Returns the name of the protocol used for current SSL connection

説明

public EventBufferEvent::sslGetProtocol(): string

Returns the name of the protocol used for current SSL connection.

注意:

This function is available only if Event is compiled with OpenSSL support.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the name of the protocol used for current SSL connection.


Tells a bufferevent to begin SSL renegotiation

  • ≪ EventBufferEvent::sslGetProtocol
  • EventBufferEvent::sslSocket ≫
  • PHP Manual
  • EventBufferEvent
  • Tells a bufferevent to begin SSL renegotiation

EventBufferEvent::sslRenegotiate

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslRenegotiate — Tells a bufferevent to begin SSL renegotiation

説明

public EventBufferEvent::sslRenegotiate(): void

Tells a bufferevent to begin SSL renegotiation.

警告

Calling this function tells the SSL to renegotiate, and the buffer event to invoke appropriate callbacks. This is an advanced topic; this should be generally avoided unless one really knows what he/she does, especially since many SSL versions have had known security issues related to renegotiation.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Creates a new SSL buffer event to send its data over an SSL on a socket

  • ≪ EventBufferEvent::sslRenegotiate
  • EventBufferEvent::write ≫
  • PHP Manual
  • EventBufferEvent
  • Creates a new SSL buffer event to send its data over an SSL on a socket

EventBufferEvent::sslSocket

(PECL event >= 1.2.6-beta)

EventBufferEvent::sslSocket — Creates a new SSL buffer event to send its data over an SSL on a socket

説明

public static EventBufferEvent::sslSocket(
EventBase $base ,
mixed $socket ,
EventSslContext $ctx ,
int $state ,
int $options = ?
): EventBufferEvent

Creates a new SSL buffer event to send its data over an SSL on a socket.

パラメータ

base

Associated event base.

socket

Socket to use for this SSL. Can be stream or socket resource, numeric file descriptor, or null. If socket is null, it is assumed that the file descriptor for the socket will be assigned later, for instance, by means of EventBufferEvent::connectHost() method.

ctx

Object of EventSslContext class.

state

The current state of SSL connection: EventBufferEvent::SSL_OPEN , EventBufferEvent::SSL_ACCEPTING or EventBufferEvent::SSL_CONNECTING .

options

The buffer event options.

戻り値

Returns EventBufferEvent object.

参考

  • EventBufferEvent::sslFilter() - Create a new SSL buffer event to send its data over another buffer event


Adds data to a buffer event's output buffer

  • ≪ EventBufferEvent::sslSocket
  • EventBufferEvent::writeBuffer ≫
  • PHP Manual
  • EventBufferEvent
  • Adds data to a buffer event's output buffer

EventBufferEvent::write

(PECL event >= 1.2.6-beta)

EventBufferEvent::write — Adds data to a buffer event's output buffer

説明

public EventBufferEvent::write( string $data ): bool

Adds data to a buffer event's output buffer

パラメータ

data

Data to be added to the underlying buffer.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBufferEvent::writeBuffer() - Adds contents of the entire buffer to a buffer event's output buffer


Adds contents of the entire buffer to a buffer event's output buffer

  • ≪ EventBufferEvent::write
  • About buffer event callbacks ≫
  • PHP Manual
  • EventBufferEvent
  • Adds contents of the entire buffer to a buffer event's output buffer

EventBufferEvent::writeBuffer

(PECL event >= 1.2.6-beta)

EventBufferEvent::writeBuffer — Adds contents of the entire buffer to a buffer event's output buffer

説明

public EventBufferEvent::writeBuffer( EventBuffer $buf ): bool

Adds contents of the entire buffer to a buffer event's output buffer

パラメータ

buf

Source EventBuffer object.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBufferEvent::write() - Adds data to a buffer event's output buffer


About buffer event callbacks

An object of EventBufferEvent class represents a buffer event . The asynchronous nature of I/O performed by Libevent implies that a socket(or other kind of file descriptor) is not always available. Event invokes corresponding callbacks when the resource becomes available for reading or writing, or when some event occurs(e.g. error, "end of line" etc.).

Read and write callbacks should match the following prototype:

callback( EventBufferEvent $bev = null , mixed $arg = null ): void

bev

Associated EventBufferEvent object.

arg

Custom variable attached to all callbacks via EventBufferEvent::__construct() , or EventBufferEvent::setCallbacks() .

Event callback should match the following prototype:

callback( EventBufferEvent $bev = null , int $events = 0 , mixed $arg = null ): void

bev

Associated EventBufferEvent object.

events

Bit mask of events: EventBufferEvent::READING , EventBufferEvent::WRITING , EventBufferEvent::EOL , EventBufferEvent::ERROR and EventBufferEvent::TIMEOUT . See EventBufferEvent constants

arg

Custom variable attached to all callbacks via EventBufferEvent::__construct() , or EventBufferEvent::setCallbacks() .


The EventConfig class

(PECL event >= 1.2.6-beta)

はじめに

Represents configuration structure which could be used in construction of the EventBase .

クラス概要

final class EventConfig {
/* 定数 */
const int FEATURE_ET = 1;
const int FEATURE_O1 = 2;
const int FEATURE_FDS = 4;
/* メソッド */
public avoidMethod( string $method ): bool
public __construct()
public requireFeatures( int $feature ): bool
public setFlags( int $flags ): bool
public setMaxDispatchInterval( int $max_interval , int $max_callbacks , int $min_priority ): void
}

定義済み定数

EventConfig::FEATURE_ET

Requires a backend method that supports edge-triggered I/O.

EventConfig::FEATURE_O1

Requires a backend method where adding or deleting a single event, or having a single event become active, is an O(1) operation.

EventConfig::FEATURE_FDS

Requires a backend method that can support arbitrary file descriptor types, and not just sockets.

目次

  • EventConfig::avoidMethod — Tells libevent to avoid specific event method
  • EventConfig::__construct — Constructs EventConfig object
  • EventConfig::requireFeatures — Enters a required event method feature that the application demands
  • EventConfig::setFlags — Sets one or more flags to configure the eventual EventBase will be initialized
  • EventConfig::setMaxDispatchInterval — Prevents priority inversion


Tells libevent to avoid specific event method

  • ≪ EventConfig
  • EventConfig::__construct ≫
  • PHP Manual
  • EventConfig
  • Tells libevent to avoid specific event method

EventConfig::avoidMethod

(PECL event >= 1.2.6-beta)

EventConfig::avoidMethod — Tells libevent to avoid specific event method

説明

public EventConfig::avoidMethod( string $method ): bool

Tells libevent to avoid specific event method(backend). See » Creating an event base .

パラメータ

method

The backend method to avoid. See EventConfig constants .

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventConfig::avoidMethod() example

<?php
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
echo "'select' method avoided\n";
}
?>

参考

  • EventBase::__construct() - Constructs EventBase object


Constructs EventConfig object

  • ≪ EventConfig::avoidMethod
  • EventConfig::requireFeatures ≫
  • PHP Manual
  • EventConfig
  • Constructs EventConfig object

EventConfig::__construct

(PECL event >= 1.2.6-beta)

EventConfig::__construct — Constructs EventConfig object

説明

public EventConfig::__construct()

Constructs EventConfig object which could be passed to EventBase::__construct() constructor.

パラメータ

この関数にはパラメータはありません。

例

例1 EventConfig::__construct() example

<?php
// Avoiding "select" method
$cfg = new EventConfig();
if ($cfg->avoidMethod("select")) {
echo "'select' method avoided\n";
}

// Create event_base associated with the config
$base = new EventBase($cfg);

/* Now $base is configured to avoid select backend(method) */
?>

参考

  • EventBase::__construct() - Constructs EventBase object


Enters a required event method feature that the application demands

  • ≪ EventConfig::__construct
  • EventConfig::setFlags ≫
  • PHP Manual
  • EventConfig
  • Enters a required event method feature that the application demands

EventConfig::requireFeatures

(PECL event >= 1.2.6-beta)

EventConfig::requireFeatures — Enters a required event method feature that the application demands

説明

public EventConfig::requireFeatures( int $feature ): bool

Enters a required event method feature that the application demands

パラメータ

feature

Bitmask of required features. See EventConfig::FEATURE_* constants

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventConfig::requireFeatures() example

<?php
$cfg = new EventConfig();

// Create event_base associated with the config
$base = new EventBase($cfg);

// Require FDS feature
if ($cfg->requireFeatures(EventConfig::FEATURE_FDS)) {
echo "FDS feature is now required\n";

$base = new EventBase($cfg);
($base->getFeatures() & EventConfig::FEATURE_FDS)
and print "FDS - arbitrary file descriptor types, and not just sockets\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

FDS feature is now required
FDS - arbitrary file descriptor types, and not just sockets

参考

  • EventBase::getFeatures() - Returns bitmask of features supported


Sets one or more flags to configure the eventual EventBase will be initialized

  • ≪ EventConfig::requireFeatures
  • EventConfig::setMaxDispatchInterval ≫
  • PHP Manual
  • EventConfig
  • Sets one or more flags to configure the eventual EventBase will be initialized

EventConfig::setFlags

(PECL event >= 2.0.2-alpha)

EventConfig::setFlags — Sets one or more flags to configure the eventual EventBase will be initialized

説明

public EventConfig::setFlags( int $flags ): bool

Sets one or more flags to configure what parts of the eventual EventBase will be initialized, and how they'll work.

パラメータ

flags

One of EventBase::LOOP_* constants. See EventBase constants.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventBase::getFeatures() - Returns bitmask of features supported


Prevents priority inversion

  • ≪ EventConfig::setFlags
  • EventDnsBase ≫
  • PHP Manual
  • EventConfig
  • Prevents priority inversion

EventConfig::setMaxDispatchInterval

(PECL event >= 2.1.0-alpha)

EventConfig::setMaxDispatchInterval — Prevents priority inversion

説明

public EventConfig::setMaxDispatchInterval( int $max_interval , int $max_callbacks , int $min_priority ): void

Prevents priority inversion by limiting how many low-priority event callbacks can be invoked before checking for more high-priority events.

注意:

Available since libevent 2.1.0-alpha .

パラメータ

max_interval

An interval after which Libevent should stop running callbacks and check for more events, or 0 , if there should be no such interval.

max_callbacks

A number of callbacks after which Libevent should stop running callbacks and check for more events, or -1 , if there should be no such limit.

min_priority

A priority below which max_interval and max_callbacks should not be enforced. If this is set to 0 , they are enforced for events of every priority; if it's set to 1 , they're enforced for events of priority 1 and above, and so on.

戻り値

成功した場合に true を、失敗した場合に false を返します。


The EventDnsBase class

(PECL event >= 1.2.6-beta)

はじめに

Represents Libevent's DNS base structure. Used to resolve DNS asyncronously, parse configuration files like resolv.conf etc.

クラス概要

final class EventDnsBase {
/* 定数 */
const int OPTION_SEARCH = 1;
const int OPTION_NAMESERVERS = 2;
const int OPTION_MISC = 4;
const int OPTION_HOSTSFILE = 8;
const int OPTIONS_ALL = 15;
const int DISABLE_WHEN_INACTIVE = 32768;
const int INITIALIZE_NAMESERVERS = 1;
const int NAMESERVERS_NO_DEFAULT = 65536;
/* メソッド */
public __construct( EventBase $base , int|bool $initialize )
public addNameserverIp( string $ip ): bool
public addSearch( string $domain ): void
public clearSearch(): void
public countNameservers(): int
public loadHosts( string $hosts ): bool
public parseResolvConf( int $flags , string $filename ): bool
public setOption( string $option , string $value ): bool
public setSearchNdots( int $ndots ): bool
}

定義済み定数

EventDnsBase::OPTION_SEARCH

Tells to read the domain and search fields from the resolv.conf file and the ndots option, and use them to decide which domains(if any) to search for hostnames that aren't fully-qualified.

EventDnsBase::OPTION_NAMESERVERS

Tells to learn the nameservers from the resolv.conf file.

EventDnsBase::OPTION_MISC

EventDnsBase::OPTION_HOSTSFILE

Tells to read a list of hosts from /etc/hosts as part of loading the resolv.conf file.

EventDnsBase::OPTIONS_ALL

Tells to learn as much as it can from the resolv.conf file.

EventDnsBase::DISABLE_WHEN_INACTIVE

Do not prevent the libevent event loop from exiting when we have no active DNS requests.

EventDnsBase::INITIALIZE_NAMESERVERS

Process the resolv.conf.

EventDnsBase::NAMESERVERS_NO_DEFAULT

Do not add default nameserver if there are no nameservers in the resolv.conf.

目次

  • EventDnsBase::addNameserverIp — Adds a nameserver to the DNS base
  • EventDnsBase::addSearch — Adds a domain to the list of search domains
  • EventDnsBase::clearSearch — Removes all current search suffixes
  • EventDnsBase::__construct — Constructs EventDnsBase object
  • EventDnsBase::countNameservers — Gets the number of configured nameservers
  • EventDnsBase::loadHosts — Loads a hosts file (in the same format as /etc/hosts) from hosts file
  • EventDnsBase::parseResolvConf — Scans the resolv.conf-formatted file
  • EventDnsBase::setOption — Set the value of a configuration option
  • EventDnsBase::setSearchNdots — Set the 'ndots' parameter for searches


Adds a nameserver to the DNS base

  • ≪ EventDnsBase
  • EventDnsBase::addSearch ≫
  • PHP Manual
  • EventDnsBase
  • Adds a nameserver to the DNS base

EventDnsBase::addNameserverIp

(PECL event >= 1.2.6-beta)

EventDnsBase::addNameserverIp — Adds a nameserver to the DNS base

説明

public EventDnsBase::addNameserverIp( string $ip ): bool

Adds a nameserver to the evdns_base.

パラメータ

ip

The nameserver string, either as an IPv4 address, an IPv6 address, an IPv4 address with a port ( IPv4:Port ), or an IPv6 address with a port ( [IPv6]:Port ).

戻り値

成功した場合に true を、失敗した場合に false を返します。


Adds a domain to the list of search domains

  • ≪ EventDnsBase::addNameserverIp
  • EventDnsBase::clearSearch ≫
  • PHP Manual
  • EventDnsBase
  • Adds a domain to the list of search domains

EventDnsBase::addSearch

(PECL event >= 1.2.6-beta)

EventDnsBase::addSearch — Adds a domain to the list of search domains

説明

public EventDnsBase::addSearch( string $domain ): void

Adds a domain to the list of search domains

パラメータ

domain

Search domain.

戻り値

値を返しません。


Removes all current search suffixes

  • ≪ EventDnsBase::addSearch
  • EventDnsBase::__construct ≫
  • PHP Manual
  • EventDnsBase
  • Removes all current search suffixes

EventDnsBase::clearSearch

(PECL event >= 1.2.6-beta)

EventDnsBase::clearSearch — Removes all current search suffixes

説明

public EventDnsBase::clearSearch(): void

Removes all current search suffixes from the DNS base; the EventDnsBase::addSearch() function adds a suffix.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EventDnsBase::addSearch() - Adds a domain to the list of search domains


Constructs EventDnsBase object

  • ≪ EventDnsBase::clearSearch
  • EventDnsBase::countNameservers ≫
  • PHP Manual
  • EventDnsBase
  • Constructs EventDnsBase object

EventDnsBase::__construct

(PECL event >= 1.2.6-beta)

EventDnsBase::__construct — Constructs EventDnsBase object

説明

public EventDnsBase::__construct( EventBase $base , int|bool $initialize )

Constructs EventDnsBase object.

パラメータ

base

Event base.

initialize

If initialize is true, it attempts to use the underlying operating system defaults to configure the DNS base senibly. If it is false, the DNS base is left unconfigured, with no nameservers or options set. In the latter case the DNS base should be configured manually, e.g. with EventDnsBase::parseResolvConf().

If initialize is an integer, it must be one of the following flags:

Flag | 説明
EventDnsBase::DISABLE_WHEN_INACTIVE | Do not prevent the libevent event loop from exiting when we have no active DNS requests.
EventDnsBase::INITIALIZE_NAMESERVERS | Process the resolv.conf.
EventDnsBase::NAMESERVERS_NO_DEFAULT | Do not add default nameserver if there are no nameservers in the resolv.conf.

エラー / 例外

If initialize has a type other than int|bool, a TypeError is thrown.

If the value of initialize is invalid, a EventException is thrown.

変更履歴

バージョン | 説明
PECL event 3.1.3 | If initialize has a type other than int|bool, a TypeError is thrown.
PECL event 3.1.0RC1 | The type of the initialize parameter has been changed from bool to mixed. The value can be either bool (preserving the previous meaning) or one of the following constants: EventDnsBase::DISABLE_WHEN_INACTIVE, EventDnsBase::INITIALIZE_NAMESERVERS, or EventDnsBase::NAMESERVERS_NO_DEFAULT.


Gets the number of configured nameservers

  • ≪ EventDnsBase::__construct
  • EventDnsBase::loadHosts ≫
  • PHP Manual
  • EventDnsBase
  • Gets the number of configured nameservers

EventDnsBase::countNameservers

(PECL event >= 1.2.6-beta)

EventDnsBase::countNameservers — Gets the number of configured nameservers

説明

public EventDnsBase::countNameservers(): int

Gets the number of configured nameservers

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of configured nameservers(not necessarily the number of running nameservers). This is useful for double-checking whether our calls to the various nameserver configuration functions have been successful.


Loads a hosts file (in the same format as /etc/hosts) from hosts file

  • ≪ EventDnsBase::countNameservers
  • EventDnsBase::parseResolvConf ≫
  • PHP Manual
  • EventDnsBase
  • Loads a hosts file (in the same format as /etc/hosts) from hosts file

EventDnsBase::loadHosts

(PECL event >= 1.2.6-beta)

EventDnsBase::loadHosts — Loads a hosts file (in the same format as /etc/hosts) from hosts file

説明

public EventDnsBase::loadHosts( string $hosts ): bool

Loads a hosts file (in the same format as /etc/hosts ) from hosts file.

パラメータ

hosts

Path to the hosts' file.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Scans the resolv.conf-formatted file

  • ≪ EventDnsBase::loadHosts
  • EventDnsBase::setOption ≫
  • PHP Manual
  • EventDnsBase
  • Scans the resolv.conf-formatted file

EventDnsBase::parseResolvConf

(PECL event >= 1.2.6-beta)

EventDnsBase::parseResolvConf — Scans the resolv.conf-formatted file

説明

public EventDnsBase::parseResolvConf( int $flags , string $filename ): bool

Scans the resolv.conf-formatted file stored in filename, and read in all the options from it that are listed in flags

パラメータ

flags

Determines what information is parsed from the resolv.conf file. See the man page for resolv.conf for the format of this file.

The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug .

If this function encounters an error, the possible return values are:

  • 1 = failed to open file
  • 2 = failed to stat file
  • 3 = file too large
  • 4 = out of memory
  • 5 = short read from file
  • 6 = no nameservers listed in the file

filename

Path to resolv.conf file.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Set the value of a configuration option

  • ≪ EventDnsBase::parseResolvConf
  • EventDnsBase::setSearchNdots ≫
  • PHP Manual
  • EventDnsBase
  • Set the value of a configuration option

EventDnsBase::setOption

(PECL event >= 1.2.6-beta)

EventDnsBase::setOption — Set the value of a configuration option

説明

public EventDnsBase::setOption( string $option , string $value ): bool

Set the value of a configuration option.

パラメータ

option

The currently available configuration options are: "ndots" , "timeout" , "max-timeouts" , "max-inflight" , and "attempts" .

value

Option value.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Set the 'ndots' parameter for searches

  • ≪ EventDnsBase::setOption
  • EventHttp ≫
  • PHP Manual
  • EventDnsBase
  • Set the 'ndots' parameter for searches

EventDnsBase::setSearchNdots

(PECL event >= 1.2.6-beta)

EventDnsBase::setSearchNdots — Set the 'ndots' parameter for searches

説明

public EventDnsBase::setSearchNdots( int $ndots ): bool

Set the 'ndots' parameter for searches. Sets the number of dots which, when found in a name, causes the first query to be without any search domain.

パラメータ

ndots

The number of dots.

戻り値

成功した場合に true を、失敗した場合に false を返します。


The EventHttp class

(PECL event >= 1.4.0-beta)

はじめに

Represents HTTP server.

クラス概要

final class EventHttp {
/* メソッド */
public accept( mixed $socket ): bool
public addServerAlias( string $alias ): bool
public bind( string $address , int $port ): void
public __construct( EventBase $base , EventSslContext $ctx = null )
public removeServerAlias( string $alias ): bool
public setAllowedMethods( int $methods ): void
public setCallback( string $path , string $cb , string $arg = ?): void
public setDefaultCallback( string $cb , string $arg = ?): void
public setMaxBodySize( int $value ): void
public setMaxHeadersSize( int $value ): void
public setTimeout( int $value ): void
}

目次

  • EventHttp::accept — Makes an HTTP server accept connections on the specified socket stream or resource
  • EventHttp::addServerAlias — Adds a server alias to the HTTP server object
  • EventHttp::bind — Binds an HTTP server on the specified address and port
  • EventHttp::__construct — Constructs EventHttp object (the HTTP server)
  • EventHttp::removeServerAlias — Removes server alias
  • EventHttp::setAllowedMethods — Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks
  • EventHttp::setCallback — Sets a callback for specified URI
  • EventHttp::setDefaultCallback — Sets default callback to handle requests that are not caught by specific callbacks
  • EventHttp::setMaxBodySize — Sets maximum request body size
  • EventHttp::setMaxHeadersSize — Sets maximum HTTP header size
  • EventHttp::setTimeout — Sets the timeout for an HTTP request


Makes an HTTP server accept connections on the specified socket stream or resource

  • ≪ EventHttp
  • EventHttp::addServerAlias ≫
  • PHP Manual
  • EventHttp
  • Makes an HTTP server accept connections on the specified socket stream or resource

EventHttp::accept

(PECL event >= 1.2.6-beta)

EventHttp::accept — Makes an HTTP server accept connections on the specified socket stream or resource

説明

public EventHttp::accept( mixed $socket ): bool

Makes an HTTP server accept connections on the specified socket stream or resource. The socket should be ready to accept connections.

Can be called multiple times to accept connections on different sockets.

注意:

To bind a socket, listen , and accept connections on the socket in s single call use EventHttp::bind() . EventHttp::accept() is needed only if one already has a socket ready to accept connections.

パラメータ

socket

Socket resource, stream or numeric file descriptor representing a socket ready to accept connections.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventHttp::accept() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$addresses = array (
8091 => "127.0.0.1",
8092 => "127.0.0.2",
);
$i = 0;

$socket = array();

foreach ($addresses as $port => $ip) {
echo $ip, " ", $port, PHP_EOL;
$socket[$i] = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if (!socket_bind($socket[$i], $ip, $port)) {
exit("socket_bind failed\n");
}
socket_listen($socket[$i], 0);
socket_set_nonblock($socket[$i]);

if (!$http->accept($socket[$i])) {
echo "Accept failed\n";
exit(1);
}

++$i;
}

$http->setCallback("/some-page", function() {
echo "(some-page)\n";
echo "URI: ", $req->getUri(), PHP_EOL;
$req->sendReply(200, "OK");
echo "OK\n";
});

$http->setDefaultCallback(function($req) {
echo "URI: ", $req->getUri(), PHP_EOL;
$req->sendReply(200, "OK");
echo "OK\n";
});

$signal = Event::signal($base, SIGINT, function () use ($base) {
echo "Caught SIGINT. Stopping...\n";
$base->stop();
});
$signal->add();

$base->dispatch();
echo "END\n";
// We didn't close sockets, since Libevent already sets
// CLOSE_ON_FREE and CLOSE_ON_EXEC flags on the file
// descriptor associated with the sockets.
?>

上の例の出力は、 たとえば以下のようになります。

Client:
$ nc 127.0.0.1 8091
GET /about HTTP/1.0
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

Server:
127.0.0.1 8091
127.0.0.2 8092
URI: /about
OK

参考

  • EventHttp::bind() - Binds an HTTP server on the specified address and port


Adds a server alias to the HTTP server object

  • ≪ EventHttp::accept
  • EventHttp::bind ≫
  • PHP Manual
  • EventHttp
  • Adds a server alias to the HTTP server object

EventHttp::addServerAlias

(PECL event >= 1.4.0-beta)

EventHttp::addServerAlias — Adds a server alias to the HTTP server object

説明

public EventHttp::addServerAlias( string $alias ): bool

Adds a server alias to the HTTP server object.

パラメータ

alias

The alias to add.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventHttp::addServerAlias() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!$http->bind("127.0.0.1", 8088)) {
exit("bind(1) failed\n");
};

if (!$http->addServerAlias("local.net")) {
exit("Failed to add server alias\n");
}

$http->setCallback("/about", function($req) {
echo "URI: ", $req->getUri(), PHP_EOL;
$req->sendReply(200, "OK");
});
$base->dispatch();
?>

参考

  • EventHttp::removeServerAlias() - Removes server alias


Binds an HTTP server on the specified address and port

  • ≪ EventHttp::addServerAlias
  • EventHttp::__construct ≫
  • PHP Manual
  • EventHttp
  • Binds an HTTP server on the specified address and port

EventHttp::bind

(PECL event >= 1.2.6-beta)

EventHttp::bind — Binds an HTTP server on the specified address and port

説明

public EventHttp::bind( string $address , int $port ): void

Binds an HTTP server on the specified address and port.

Can be called multiple times to bind the same HTTP server to multiple different ports.

パラメータ

address

A string containing the IP address to listen(2) on.

port

The port number to listen on.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventHttp::bind() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!$http->bind("127.0.0.1", 8088)) {
exit("bind(1) failed\n");
};
if (!$http->bind("127.0.0.1", 8089)) {
exit("bind(2) failed\n");
};

$http->setCallback("/about", function($req) {
echo "URI: ", $req->getUri(), PHP_EOL;
$req->sendReply(200, "OK");
echo "OK\n";
});

$base->dispatch();
?>

上の例の出力は、 たとえば以下のようになります。

Client:

$ nc 127.0.0.1 8088
GET /about HTTP/1.0
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

$ nc 127.0.0.1 8089
GET /unknown HTTP/1.0
Connection: close

HTTP/1.1 404 Not Found
Content-Type: text/html
Date: Wed, 13 Mar 2013 04:14:41 GMT
Content-Length: 149
Connection: close

<html><head><title>404 Not Found</title></head><body><h1>Not Found</h1><p>The requested URL /unknown was not found on this server.</p></body></html>

Server:
URI: /about
OK

参考

  • EventHttp::accept() - Makes an HTTP server accept connections on the specified socket stream or resource


Constructs EventHttp object (the HTTP server)

  • ≪ EventHttp::bind
  • EventHttp::removeServerAlias ≫
  • PHP Manual
  • EventHttp
  • Constructs EventHttp object (the HTTP server)

EventHttp::__construct

(PECL event >= 1.2.6-beta)

EventHttp::__construct — Constructs EventHttp object (the HTTP server)

説明

public EventHttp::__construct( EventBase $base , EventSslContext $ctx = null )

Constructs the HTTP server object.

パラメータ

base

Associated event base.

ctx

EventSslContext class object. Turns plain HTTP server into HTTPS server. It means that if ctx is configured correctly, then the underlying buffer events will be based on OpenSSL sockets. Thus, all traffic will pass through the SSL or TLS.

注意:

This parameter is available only if Event is compiled with OpenSSL support and only with Libevent 2.1.0-alpha and higher.

変更履歴

バージョン | 説明
PECL event 1.9.0 | OpenSSL support (ctx) added.

例

例1 Simple HTTP server

<?php
/*
* Simple HTTP server.
*
* To test it:
* 1) Run it on a port of your choice, e.g.:
* $ php examples/http.php 8010
* 2) In another terminal connect to some address on this port
* and make GET or POST request(others are turned off here), e.g.:
* $ nc -t 127.0.0.1 8010
* POST /about HTTP/1.0
* Content-Type: text/plain
* Content-Length: 4
* Connection: close
* (press Enter)
*
* It will output
* a=12
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
*
* $ nc -t 127.0.0.1 8010
* GET /dump HTTP/1.0
* Content-Type: text/plain
* Content-Encoding: UTF-8
* Connection: close
* (press Enter)
*
* It will output:
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
* (press Enter)
*
* $ nc -t 127.0.0.1 8010
* GET /unknown HTTP/1.0
* Connection: close
*
* It will output:
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
*
* 3) See what the server outputs on the previous terminal window.
*/

function _http_dump($req, $data) {
static $counter = 0;
static $max_requests = 2;

if (++$counter >= $max_requests) {
echo "Counter reached max requests $max_requests. Exiting\n";
exit();
}

echo __METHOD__, " called\n";
echo "request:"; var_dump($req);
echo "data:"; var_dump($data);

echo "\n===== DUMP =====\n";
echo "Command:", $req->getCommand(), PHP_EOL;
echo "URI:", $req->getUri(), PHP_EOL;
echo "Input headers:"; var_dump($req->getInputHeaders());
echo "Output headers:"; var_dump($req->getOutputHeaders());

echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";

echo "\n >> Reading input buffer ...\n";
$buf = $req->getInputBuffer();
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
echo "No more data in the buffer\n";
}

function _http_about($req) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

function _http_default($req, $data) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

$port = 8010;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

a=12
HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close
(press Enter)

HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close


Removes server alias

  • ≪ EventHttp::__construct
  • EventHttp::setAllowedMethods ≫
  • PHP Manual
  • EventHttp
  • Removes server alias

EventHttp::removeServerAlias

(PECL event >= 1.4.0-beta)

EventHttp::removeServerAlias — Removes server alias

説明

public EventHttp::removeServerAlias( string $alias ): bool

Removes server alias added with EventHttp::addServerAlias()

パラメータ

alias

The alias to remove.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventHttp::addServerAlias() - Adds a server alias to the HTTP server object


Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

  • ≪ EventHttp::removeServerAlias
  • EventHttp::setCallback ≫
  • PHP Manual
  • EventHttp
  • Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

EventHttp::setAllowedMethods

(PECL event >= 1.4.0-beta)

EventHttp::setAllowedMethods — Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

説明

public EventHttp::setAllowedMethods( int $methods ): void

Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks

If not supported they will generate a "405 Method not allowed" response.

By default this includes the following methods: GET , POST , HEAD , PUT , DELETE . See EventHttpRequest::CMD_* constants.

パラメータ

methods

A bit mask of EventHttpRequest::CMD_* constants .

戻り値

値を返しません。


Sets a callback for specified URI

  • ≪ EventHttp::setAllowedMethods
  • EventHttp::setDefaultCallback ≫
  • PHP Manual
  • EventHttp
  • Sets a callback for specified URI

EventHttp::setCallback

(PECL event >= 1.4.0-beta)

EventHttp::setCallback — Sets a callback for specified URI

説明

public EventHttp::setCallback( string $path , string $cb , string $arg = ?): void

Sets a callback for specified URI.

パラメータ

path

The path for which to invoke the callback.

cb

The callback callable that gets invoked on requested path . It should match the following prototype:

callback( EventHttpRequest $req = NULL , mixed $arg = NULL ): void

req

EventHttpRequest object.

arg

Custom data.

arg

Custom data.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventHttp::setCallback() example

<?php
/*
* Simple HTTP server.
*
* To test it:
* 1) Run it on a port of your choice, e.g.:
* $ php examples/http.php 8010
* 2) In another terminal connect to some address on this port
* and make GET or POST request(others are turned off here), e.g.:
* $ nc -t 127.0.0.1 8010
* POST /about HTTP/1.0
* Content-Type: text/plain
* Content-Length: 4
* Connection: close
* (press Enter)
*
* It will output
* a=12
* HTTP/1.0 200 OK
* Content-Type: text/html; charset=ISO-8859-1
* Connection: close
*
* 3) See what the server outputs on the previous terminal window.
*/

function _http_dump($req, $data) {
static $counter = 0;
static $max_requests = 2;

if (++$counter >= $max_requests) {
echo "Counter reached max requests $max_requests. Exiting\n";
exit();
}

echo __METHOD__, " called\n";
echo "request:"; var_dump($req);
echo "data:"; var_dump($data);

echo "\n===== DUMP =====\n";
echo "Command:", $req->getCommand(), PHP_EOL;
echo "URI:", $req->getUri(), PHP_EOL;
echo "Input headers:"; var_dump($req->getInputHeaders());
echo "Output headers:"; var_dump($req->getOutputHeaders());

echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";

echo "\n >> Reading input buffer ...\n";
$buf = $req->getInputBuffer();
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
echo "No more data in the buffer\n";
}

function _http_about($req) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

function _http_default($req, $data) {
echo __METHOD__, PHP_EOL;
echo "URI: ", $req->getUri(), PHP_EOL;
echo "\n >> Sending reply ...";
$req->sendReply(200, "OK");
echo "OK\n";
}

$port = 8010;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);
$http->setAllowedMethods(EventHttpRequest::CMD_GET | EventHttpRequest::CMD_POST);

$http->setCallback("/dump", "_http_dump", array(4, 8));
$http->setCallback("/about", "_http_about");
$http->setDefaultCallback("_http_default", "custom data value");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

a=12
HTTP/1.0 200 OK
Content-Type: text/html; charset=ISO-8859-1
Connection: close

参考

  • EventHttp::setDefaultCallback() - Sets default callback to handle requests that are not caught by specific callbacks


Sets default callback to handle requests that are not caught by specific callbacks

  • ≪ EventHttp::setCallback
  • EventHttp::setMaxBodySize ≫
  • PHP Manual
  • EventHttp
  • Sets default callback to handle requests that are not caught by specific callbacks

EventHttp::setDefaultCallback

(PECL event >= 1.4.0-beta)

EventHttp::setDefaultCallback — Sets default callback to handle requests that are not caught by specific callbacks

説明

public EventHttp::setDefaultCallback( string $cb , string $arg = ?): void

Sets default callback to handle requests that are not caught by specific callbacks

パラメータ

cb

The callback callable . It should match the following prototype:

callback( EventHttpRequest $req = NULL , mixed $arg = NULL ): void

req

EventHttpRequest object.

arg

Custom data.

arg

User custom data passed to the callback.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventHttp::setDefaultCallback() example

<?php
$base = new EventBase();
$http = new EventHttp($base);

$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!$http->bind("127.0.0.1", 8088)) {
exit("bind(1) failed\n");
};

$http->setDefaultCallback(function($req) {
echo "URI: ", $req->getUri(), PHP_EOL;
$req->sendReply(200, "OK");
});

$base->dispatch();
?>

参考

  • EventHttp::setCallback() - Sets a callback for specified URI


Sets maximum request body size

  • ≪ EventHttp::setDefaultCallback
  • EventHttp::setMaxHeadersSize ≫
  • PHP Manual
  • EventHttp
  • Sets maximum request body size

EventHttp::setMaxBodySize

(PECL event >= 1.4.0-beta)

EventHttp::setMaxBodySize — Sets maximum request body size

説明

public EventHttp::setMaxBodySize( int $value ): void

Sets maximum request body size.

パラメータ

value

The body size in bytes.

戻り値

値を返しません。

参考

  • EventHttp::setMaxHeadersSize() - Sets maximum HTTP header size


Sets maximum HTTP header size

  • ≪ EventHttp::setMaxBodySize
  • EventHttp::setTimeout ≫
  • PHP Manual
  • EventHttp
  • Sets maximum HTTP header size

EventHttp::setMaxHeadersSize

(PECL event >= 1.4.0-beta)

EventHttp::setMaxHeadersSize — Sets maximum HTTP header size

説明

public EventHttp::setMaxHeadersSize( int $value ): void

Sets maximum HTTP header size.

パラメータ

value

The header size in bytes.

戻り値

値を返しません。

参考

  • EventHttp::setMaxHeadersSize()


Sets the timeout for an HTTP request

  • ≪ EventHttp::setMaxHeadersSize
  • EventHttpConnection ≫
  • PHP Manual
  • EventHttp
  • Sets the timeout for an HTTP request

EventHttp::setTimeout

(PECL event >= 1.4.0-beta)

EventHttp::setTimeout — Sets the timeout for an HTTP request

説明

public EventHttp::setTimeout( int $value ): void

Sets the timeout for an HTTP request.

パラメータ

value

The timeout in seconds.

戻り値

値を返しません。


The EventHttpConnection class

(PECL event >= 1.4.0-beta)

はじめに

Represents an HTTP connection.

クラス概要

class EventHttpConnection {
/* メソッド */
public __construct(
EventBase $base ,
EventDnsBase $dns_base ,
string $address ,
int $port ,
EventSslContext $ctx = null
)
public getBase(): EventBase
public getPeer( string &$address , int &$port ): void
public makeRequest( EventHttpRequest $req , int $type , string $uri ): bool
public setCloseCallback( callable $callback , mixed $data = ?): void
public setLocalAddress( string $address ): void
public setLocalPort( int $port ): void
public setMaxBodySize( string $max_size ): void
public setMaxHeadersSize( string $max_size ): void
public setRetries( int $retries ): void
public setTimeout( int $timeout ): void
}

目次

  • EventHttpConnection::__construct — Constructs EventHttpConnection object
  • EventHttpConnection::getBase — Returns event base associated with the connection
  • EventHttpConnection::getPeer — Gets the remote address and port associated with the connection
  • EventHttpConnection::makeRequest — Makes an HTTP request over the specified connection
  • EventHttpConnection::setCloseCallback — Set callback for connection close
  • EventHttpConnection::setLocalAddress — Sets the IP address from which HTTP connections are made
  • EventHttpConnection::setLocalPort — Sets the local port from which connections are made
  • EventHttpConnection::setMaxBodySize — Sets maximum body size for the connection
  • EventHttpConnection::setMaxHeadersSize — Sets maximum header size
  • EventHttpConnection::setRetries — Sets the retry limit for the connection
  • EventHttpConnection::setTimeout — Sets the timeout for the connection


Constructs EventHttpConnection object

  • ≪ EventHttpConnection
  • EventHttpConnection::getBase ≫
  • PHP Manual
  • EventHttpConnection
  • Constructs EventHttpConnection object

EventHttpConnection::__construct

(PECL event >= 1.2.6-beta)

EventHttpConnection::__construct — Constructs EventHttpConnection object

説明

public EventHttpConnection::__construct(
EventBase $base ,
EventDnsBase $dns_base ,
string $address ,
int $port ,
EventSslContext $ctx = null
)

Constructs EventHttpConnection object.

パラメータ

base

Associated event base.

dns_base

If dns_base is null, hostname resolution will block.

address

The address to connect to.

port

The port to connect to.

ctx

EventSslContext class object. Enables OpenSSL.

注意:

This parameter is available only if Event is compiled with OpenSSL support and only with Libevent 2.1.0-alpha and higher.

変更履歴

バージョン | 説明
PECL event 1.9.0 | OpenSSL support (ctx) added.


Returns event base associated with the connection

  • ≪ EventHttpConnection::__construct
  • EventHttpConnection::getPeer ≫
  • PHP Manual
  • EventHttpConnection
  • Returns event base associated with the connection

EventHttpConnection::getBase

(PECL event >= 1.2.6-beta)

EventHttpConnection::getBase — Returns event base associated with the connection

説明

public EventHttpConnection::getBase(): EventBase

Returns event base associated with the connection.

パラメータ

この関数にはパラメータはありません。

戻り値

On success returns EventBase object associated with the connection. Otherwise false.


Gets the remote address and port associated with the connection

  • ≪ EventHttpConnection::getBase
  • EventHttpConnection::makeRequest ≫
  • PHP Manual
  • EventHttpConnection
  • Gets the remote address and port associated with the connection

EventHttpConnection::getPeer

(PECL event >= 1.2.6-beta)

EventHttpConnection::getPeer — Gets the remote address and port associated with the connection

説明

public EventHttpConnection::getPeer( string &$address , int &$port ): void

Gets the remote address and port associated with the connection

パラメータ

address

Address of the peer.

port

Port of the peer.

戻り値

値を返しません。


Makes an HTTP request over the specified connection

  • ≪ EventHttpConnection::getPeer
  • EventHttpConnection::setCloseCallback ≫
  • PHP Manual
  • EventHttpConnection
  • Makes an HTTP request over the specified connection

EventHttpConnection::makeRequest

(PECL event >= 1.4.0-beta)

EventHttpConnection::makeRequest — Makes an HTTP request over the specified connection

説明

public EventHttpConnection::makeRequest( EventHttpRequest $req , int $type , string $uri ): bool

Makes an HTTP request over the specified connection. type is one of EventHttpRequest::CMD_* constants.

パラメータ

req

The connection object over which to send the request.

type

One of EventHttpRequest::CMD_* constants .

uri

The URI associated with the request.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EventHttpConnection::makeRequest() example

<?php
function _request_handler($req, $base) {
echo __FUNCTION__, PHP_EOL;

if (is_null($req)) {
echo "Timed out\n";
} else {
$response_code = $req->getResponseCode();

if ($response_code == 0) {
echo "Connection refused\n";
} elseif ($response_code != 200) {
echo "Unexpected response: $response_code\n";
} else {
echo "Success: $response_code\n";
$buf = $req->getInputBuffer();
echo "Body:\n";
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
}
}

$base->exit(NULL);
}

$address = "127.0.0.1";
$port = 80;

$base = new EventBase();
$conn = new EventHttpConnection($base, NULL, $address, $port);
$conn->setTimeout(5);
$req = new EventHttpRequest("_request_handler", $base);

$req->addHeader("Host", $address, EventHttpRequest::OUTPUT_HEADER);
$req->addHeader("Content-Length", "0", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_GET, "/index.cphp");

$base->loop();
?>

上の例の出力は、 たとえば以下のようになります。

_request_handler
Success: 200
Body:
PHP, date:
2013-03-13T20:27:52+05:00

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request


Set callback for connection close

  • ≪ EventHttpConnection::makeRequest
  • EventHttpConnection::setLocalAddress ≫
  • PHP Manual
  • EventHttpConnection
  • Set callback for connection close

EventHttpConnection::setCloseCallback

(PECL event >= 1.8.0)

EventHttpConnection::setCloseCallback — Set callback for connection close

説明

public EventHttpConnection::setCloseCallback( callable $callback , mixed $data = ?): void

Sets callback for connection close.

パラメータ

callback

Callback which is called when connection is closed. Should match the following prototype:

callback( EventHttpConnection $conn = null , mixed $arg = null ): void

戻り値

値を返しません。

例

例1 EventHttpConnection::setCloseCallback() example

<?php
/*
* Setting up close-connection callback
*
* The script handles closed connections using HTTP API.
*
* Usage:
* 1) Launch the server:
* $ php examples/http_closecb.php 4242
*
* 2) Launch a client in another terminal. Telnet-like
* session should look like the following:
*
* $ nc -t 127.0.0.1 4242
* GET / HTTP/1.0
* Connection: close
*
* The server will output something similar to the following:
*
* HTTP/1.0 200 OK
* Content-Type: multipart/x-mixed-replace;boundary=boundarydonotcross
* Connection: close
*
* <html>
*
* 3) Terminate the client connection abruptly,
* i.e. kill the process, or just press Ctrl-C.
*
* 4) Check if the server called _close_callback.
* The script should output "_close_callback" string to standard output.
*
* 5) Check if the server's process has no orphaned connections,
* e.g. with `lsof` utility.
*/

function _close_callback($conn)
{
echo __FUNCTION__, PHP_EOL;
}

function _http_default($req, $dummy)
{
$conn = $req->getConnection();
$conn->setCloseCallback('_close_callback', NULL);

/*
By enabling Event::READ we protect the server against unclosed conections.
This is a peculiarity of Libevent. The library disables Event::READ events
on this connection, and the server is not notified about terminated
connections.

So each time client terminates connection abruptly, we get an orphaned
connection. For instance, the following is a part of `lsof -p $PID | grep TCP`
command after client has terminated connection:

57-php 15057 ruslan 6u unix 0xffff8802fb59c780 0t0 125187 socket
58:php 15057 ruslan 7u IPv4 125189 0t0 TCP *:4242 (LISTEN)
59:php 15057 ruslan 8u IPv4 124342 0t0 TCP localhost:4242->localhost:37375 (CLOSE_WAIT)

where $PID is our process ID.

The following block of code fixes such kind of orphaned connections.
*/
$bev = $req->getBufferEvent();
$bev->enable(Event::READ);
// We have to free it explicitly. See
EventHttpRequest::getConnection()
$bev->free(); // we have to free it explicitly

$req->addHeader(
'Content-Type',
'multipart/x-mixed-replace;boundary=boundarydonotcross',
EventHttpRequest::OUTPUT_HEADER
);

$buf = new EventBuffer();
$buf->add('<html>');

$req->sendReply(200, "OK");
$req->sendReplyChunk($buf);
}

$port = 4242;
if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}

$base = new EventBase();
$http = new EventHttp($base);

$http->setDefaultCallback("_http_default", NULL);
$http->bind("0.0.0.0", $port);
$base->loop();

?>


Sets the IP address from which HTTP connections are made

  • ≪ EventHttpConnection::setCloseCallback
  • EventHttpConnection::setLocalPort ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the IP address from which HTTP connections are made

EventHttpConnection::setLocalAddress

(PECL event >= 1.2.6-beta)

EventHttpConnection::setLocalAddress — Sets the IP address from which HTTP connections are made

説明

public EventHttpConnection::setLocalAddress( string $address ): void

Sets the IP address from which http connections are made.

パラメータ

address

The IP address from which HTTP connections are made.

戻り値

値を返しません。

参考

  • EventHttpConnection::setLocalPort() - Sets the local port from which connections are made


Sets the local port from which connections are made

  • ≪ EventHttpConnection::setLocalAddress
  • EventHttpConnection::setMaxBodySize ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the local port from which connections are made

EventHttpConnection::setLocalPort

(PECL event >= 1.2.6-beta)

EventHttpConnection::setLocalPort — Sets the local port from which connections are made

説明

public EventHttpConnection::setLocalPort( int $port ): void

Sets the local port from which connections are made.

パラメータ

port

The port number.

戻り値

参考

  • EventHttpConnection::setLocalAddress() - Sets the IP address from which HTTP connections are made


Sets maximum body size for the connection

  • ≪ EventHttpConnection::setLocalPort
  • EventHttpConnection::setMaxHeadersSize ≫
  • PHP Manual
  • EventHttpConnection
  • Sets maximum body size for the connection

EventHttpConnection::setMaxBodySize

(PECL event >= 1.2.6-beta)

EventHttpConnection::setMaxBodySize — Sets maximum body size for the connection

説明

public EventHttpConnection::setMaxBodySize( string $max_size ): void

Sets maximum body size for the connection.

パラメータ

max_size

The maximum body size in bytes.

戻り値

値を返しません。

参考

  • EventHttpConnection::setMaxHeadersSize() - Sets maximum header size


Sets maximum header size

  • ≪ EventHttpConnection::setMaxBodySize
  • EventHttpConnection::setRetries ≫
  • PHP Manual
  • EventHttpConnection
  • Sets maximum header size

EventHttpConnection::setMaxHeadersSize

(PECL event >= 1.2.6-beta)

EventHttpConnection::setMaxHeadersSize — Sets maximum header size

説明

public EventHttpConnection::setMaxHeadersSize( string $max_size ): void

Sets maximum header size for the connection.

パラメータ

max_size

The maximum header size in bytes.

戻り値

値を返しません。

参考

  • EventHttpConnection::setMaxBodySize() - Sets maximum body size for the connection


Sets the retry limit for the connection

  • ≪ EventHttpConnection::setMaxHeadersSize
  • EventHttpConnection::setTimeout ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the retry limit for the connection

EventHttpConnection::setRetries

(PECL event >= 1.2.6-beta)

EventHttpConnection::setRetries — Sets the retry limit for the connection

説明

public EventHttpConnection::setRetries( int $retries ): void

Sets the retry limit for the connection

パラメータ

retries

The retry limit. -1 means infinity.

戻り値

値を返しません。


Sets the timeout for the connection

  • ≪ EventHttpConnection::setRetries
  • EventHttpRequest ≫
  • PHP Manual
  • EventHttpConnection
  • Sets the timeout for the connection

EventHttpConnection::setTimeout

(PECL event >= 1.2.6-beta)

EventHttpConnection::setTimeout — Sets the timeout for the connection

説明

public EventHttpConnection::setTimeout( int $timeout ): void

Sets the timeout for the connection

パラメータ

timeout

Timeout in seconds.

戻り値

値を返しません。


The EventHttpRequest class

(PECL event >= 1.4.0-beta)

はじめに

Represents an HTTP request.

クラス概要

class EventHttpRequest {
/* 定数 */
const int CMD_GET = 1;
const int CMD_POST = 2;
const int CMD_HEAD = 4;
const int CMD_PUT = 8;
const int CMD_DELETE = 16;
const int CMD_OPTIONS = 32;
const int CMD_TRACE = 64;
const int CMD_CONNECT = 128;
const int CMD_PATCH = 256;
const int INPUT_HEADER = 1;
const int OUTPUT_HEADER = 2;
/* メソッド */
public addHeader( string $key , string $value , int $type ): bool
public cancel(): void
public clearHeaders(): void
public closeConnection(): void
public __construct( callable $callback , mixed $data = null )
public findHeader( string $key , string $type ): void
public free(): void
public closeConnection(): EventBufferEvent
public getCommand(): void
public closeConnection(): EventHttpConnection
public getHost(): string
public getInputBuffer(): EventBuffer
public getInputHeaders(): array
public getOutputBuffer(): EventBuffer
public getOutputHeaders(): void
public getResponseCode(): int
public getUri(): string
public removeHeader( string $key , string $type ): void
public sendError( int $error , string $reason = null ): void
public sendReply( int $code , string $reason , EventBuffer $buf = ?): void
public sendReplyChunk( EventBuffer $buf ): void
public sendReplyEnd(): void
public sendReplyStart( int $code , string $reason ): void
}

定義済み定数

EventHttpRequest::CMD_GET

GET method(command)

EventHttpRequest::CMD_POST

POST method(command)

EventHttpRequest::CMD_HEAD

HEAD method(command)

EventHttpRequest::CMD_PUT

PUT method(command)

EventHttpRequest::CMD_DELETE

DELETE command(method)

EventHttpRequest::CMD_OPTIONS

OPTIONS method(command)

EventHttpRequest::CMD_TRACE

TRACE method(command)

EventHttpRequest::CMD_CONNECT

CONNECT method(command)

EventHttpRequest::CMD_PATCH

PATCH method(command)

EventHttpRequest::INPUT_HEADER

Request input header type.

EventHttpRequest::OUTPUT_HEADER

Request output header type.

目次

  • EventHttpRequest::addHeader — Adds an HTTP header to the headers of the request
  • EventHttpRequest::cancel — Cancels a pending HTTP request
  • EventHttpRequest::clearHeaders — Removes all output headers from the header list of the request
  • EventHttpRequest::closeConnection — Closes associated HTTP connection
  • EventHttpRequest::__construct — Constructs EventHttpRequest object
  • EventHttpRequest::findHeader — Finds the value belonging a header
  • EventHttpRequest::free — Frees the object and removes associated events
  • EventHttpRequest::getBufferEvent — Returns EventBufferEvent object
  • EventHttpRequest::getCommand — Returns the request command(method)
  • EventHttpRequest::getConnection — Returns EventHttpConnection object
  • EventHttpRequest::getHost — Returns the request host
  • EventHttpRequest::getInputBuffer — Returns the input buffer
  • EventHttpRequest::getInputHeaders — Returns associative array of the input headers
  • EventHttpRequest::getOutputBuffer — Returns the output buffer of the request
  • EventHttpRequest::getOutputHeaders — Returns associative array of the output headers
  • EventHttpRequest::getResponseCode — Returns the response code
  • EventHttpRequest::getUri — Returns the request URI
  • EventHttpRequest::removeHeader — Removes an HTTP header from the headers of the request
  • EventHttpRequest::sendError — Send an HTML error message to the client
  • EventHttpRequest::sendReply — Send an HTML reply to the client
  • EventHttpRequest::sendReplyChunk — Send another data chunk as part of an ongoing chunked reply
  • EventHttpRequest::sendReplyEnd — Complete a chunked reply, freeing the request as appropriate
  • EventHttpRequest::sendReplyStart — Initiate a chunked reply


Adds an HTTP header to the headers of the request

  • ≪ EventHttpRequest
  • EventHttpRequest::cancel ≫
  • PHP Manual
  • EventHttpRequest
  • Adds an HTTP header to the headers of the request

EventHttpRequest::addHeader

(PECL event >= 1.4.0-beta)

EventHttpRequest::addHeader — Adds an HTTP header to the headers of the request

説明

public EventHttpRequest::addHeader( string $key , string $value , int $type ): bool

Adds an HTTP header to the headers of the request.

パラメータ

key

Header name.

value

Header value.

type

One of EventHttpRequest::*_HEADER constants .

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventHttpRequest::removeHeader() - Removes an HTTP header from the headers of the request


Cancels a pending HTTP request

  • ≪ EventHttpRequest::addHeader
  • EventHttpRequest::clearHeaders ≫
  • PHP Manual
  • EventHttpRequest
  • Cancels a pending HTTP request

EventHttpRequest::cancel

(PECL event >= 1.4.0-beta)

EventHttpRequest::cancel — Cancels a pending HTTP request

説明

public EventHttpRequest::cancel(): void

Cancels a pending HTTP request.

Cancels an ongoing HTTP request. The callback associated with this request is not executed and the request object is freed. If the request is currently being processed, e.g. it is ongoing, the corresponding EventHttpConnection object is going to get reset.

A request cannot be canceled if its callback has executed already. A request may be canceled reentrantly from its chunked callback.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Removes all output headers from the header list of the request

  • ≪ EventHttpRequest::cancel
  • EventHttpRequest::closeConnection ≫
  • PHP Manual
  • EventHttpRequest
  • Removes all output headers from the header list of the request

EventHttpRequest::clearHeaders

(PECL event >= 1.4.0-beta)

EventHttpRequest::clearHeaders — Removes all output headers from the header list of the request

説明

public EventHttpRequest::clearHeaders(): void

Removes all output headers from the header list of the request.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request


Closes associated HTTP connection

  • ≪ EventHttpRequest::clearHeaders
  • EventHttpRequest::__construct ≫
  • PHP Manual
  • EventHttpRequest
  • Closes associated HTTP connection

EventHttpRequest::closeConnection

(PECL event >= 1.8.0)

EventHttpRequest::closeConnection — Closes associated HTTP connection

説明

public EventHttpRequest::closeConnection(): void

Closes HTTP connection associated with the request.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Constructs EventHttpRequest object

  • ≪ EventHttpRequest::closeConnection
  • EventHttpRequest::findHeader ≫
  • PHP Manual
  • EventHttpRequest
  • Constructs EventHttpRequest object

EventHttpRequest::__construct

(PECL event >= 1.4.0-beta)

EventHttpRequest::__construct — Constructs EventHttpRequest object

説明

public EventHttpRequest::__construct( callable $callback , mixed $data = null )

Constructs EventHttpRequest object.

パラメータ

callback

Gets invoked on requesting path. Should match the following prototype:

callback( EventHttpRequest $req = null , mixed $arg = null ): void
data

User custom data passed to the callback.

例

例1 EventHttpRequest::__construct() example

<?php

function _request_handler($req, $base) {
echo __FUNCTION__, PHP_EOL;

if (is_null($req)) {
echo "Timed out\n";
} else {
$response_code = $req->getResponseCode();

if ($response_code == 0) {
echo "Connection refused\n";
} elseif ($response_code != 200) {
echo "Unexpected response: $response_code\n";
} else {
echo "Success: $response_code\n";
$buf = $req->getInputBuffer();
echo "Body:\n";
while ($s = $buf->readLine(EventBuffer::EOL_ANY)) {
echo $s, PHP_EOL;
}
}
}

$base->exit(NULL);
}

$address = "127.0.0.1";
$port = 80;

$base = new EventBase();
$conn = new EventHttpConnection($base, NULL, $address, $port);
$conn->setTimeout(5);
$req = new EventHttpRequest("_request_handler", $base);

$req->addHeader("Host", $address, EventHttpRequest::OUTPUT_HEADER);
$req->addHeader("Content-Length", "0", EventHttpRequest::OUTPUT_HEADER);
$conn->makeRequest($req, EventHttpRequest::CMD_GET, "/index.cphp");

$base->loop();
?>

参考

  • EventHttpRequest::cancel() - Cancels a pending HTTP request
  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request


Finds the value belonging a header

  • ≪ EventHttpRequest::__construct
  • EventHttpRequest::free ≫
  • PHP Manual
  • EventHttpRequest
  • Finds the value belonging a header

EventHttpRequest::findHeader

(PECL event >= 1.4.0-beta)

EventHttpRequest::findHeader — Finds the value belonging a header

説明

public EventHttpRequest::findHeader( string $key , string $type ): void

Finds the value belonging a header.

パラメータ

key

The header name.

type

One of EventHttpRequest::*_HEADER constants .

戻り値

Returns null if header not found.

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request


Frees the object and removes associated events

  • ≪ EventHttpRequest::findHeader
  • EventHttpRequest::getBufferEvent ≫
  • PHP Manual
  • EventHttpRequest
  • Frees the object and removes associated events

EventHttpRequest::free

(PECL event >= 1.4.0-beta)

EventHttpRequest::free — Frees the object and removes associated events

説明

public EventHttpRequest::free(): void

Frees the object and removes associated events.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Returns EventBufferEvent object

  • ≪ EventHttpRequest::free
  • EventHttpRequest::getCommand ≫
  • PHP Manual
  • EventHttpRequest
  • Returns EventBufferEvent object

EventHttpRequest::getBufferEvent

(PECL event >= 1.8.0)

EventHttpRequest::getBufferEvent — Returns EventBufferEvent object

説明

public EventHttpRequest::closeConnection(): EventBufferEvent

Returns EventBufferEvent object which represents buffer event that the connection is using.

警告

The reference counter of the returned object will be incremented by one to protect internal structures against premature destruction when the method is called from a user callback. So the EventBufferEvent object should be freed explicitly with EventBufferEvent::free() method. Otherwise memory will leak.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns EventBufferEvent object.

参考

  • EventHttpRequest::getConnection() - Returns EventHttpConnection object


Returns the request command(method)

  • ≪ EventHttpRequest::getBufferEvent
  • EventHttpRequest::getConnection ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the request command(method)

EventHttpRequest::getCommand

(PECL event >= 1.4.0-beta)

EventHttpRequest::getCommand — Returns the request command(method)

説明

public EventHttpRequest::getCommand(): void

Returns the request command, one of EventHttpRequest::CMD_* constants.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the request command, one of EventHttpRequest::CMD_* constants.


Returns EventHttpConnection object

  • ≪ EventHttpRequest::getCommand
  • EventHttpRequest::getHost ≫
  • PHP Manual
  • EventHttpRequest
  • Returns EventHttpConnection object

EventHttpRequest::getConnection

(PECL event >= 1.8.0)

EventHttpRequest::getConnection — Returns EventHttpConnection object

説明

public EventHttpRequest::closeConnection(): EventHttpConnection

Returns EventHttpConnection object which represents HTTP connection associated with the request.

警告

Libevent API allows HTTP request objects to be not bound to any HTTP connection. Therefore we can't unambiguously associate EventHttpRequest with EventHttpConnection . Thus, we construct EventHttpConnection object on-the-fly. Having no information about the event base, DNS base and connection-close callback, we just leave these fields unset.

EventHttpRequest::getConnection() method is usually useful when we need to set up a callback on connection close. See EventHttpConnection::setCloseCallback() .

パラメータ

この関数にはパラメータはありません。

戻り値

Returns EventHttpConnection object.

参考

  • EventHttpConnection::setCloseCallback() - Set callback for connection close
  • EventHttpRequest::getBufferEvent() - Returns EventBufferEvent object


Returns the request host

  • ≪ EventHttpRequest::getConnection
  • EventHttpRequest::getInputBuffer ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the request host

EventHttpRequest::getHost

(PECL event >= 1.4.0-beta)

EventHttpRequest::getHost — Returns the request host

説明

public EventHttpRequest::getHost(): string

Returns the request host.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the request host.

参考

  • EventHttpRequest::getUri() - Returns the request URI
  • EventHttpRequest::getCommand() - Returns the request command(method)


Returns the input buffer

  • ≪ EventHttpRequest::getHost
  • EventHttpRequest::getInputHeaders ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the input buffer

EventHttpRequest::getInputBuffer

(PECL event >= 1.4.0-beta)

EventHttpRequest::getInputBuffer — Returns the input buffer

説明

public EventHttpRequest::getInputBuffer(): EventBuffer

Returns the input buffer.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the input buffer.

参考

  • EventHttpRequest::getOutputBuffer() - Returns the output buffer of the request


Returns associative array of the input headers

  • ≪ EventHttpRequest::getInputBuffer
  • EventHttpRequest::getOutputBuffer ≫
  • PHP Manual
  • EventHttpRequest
  • Returns associative array of the input headers

EventHttpRequest::getInputHeaders

(PECL event >= 1.4.0-beta)

EventHttpRequest::getInputHeaders — Returns associative array of the input headers

説明

public EventHttpRequest::getInputHeaders(): array

Returns associative array of the input headers.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns associative array of the input headers.

参考

  • EventHttpRequest::getOutputHeaders() - Returns associative array of the output headers


Returns the output buffer of the request

  • ≪ EventHttpRequest::getInputHeaders
  • EventHttpRequest::getOutputHeaders ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the output buffer of the request

EventHttpRequest::getOutputBuffer

(PECL event >= 1.4.0-beta)

EventHttpRequest::getOutputBuffer — Returns the output buffer of the request

説明

public EventHttpRequest::getOutputBuffer(): EventBuffer

Returns the output buffer of the request.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the output buffer of the request.

参考

  • EventHttpRequest::getInputBuffer() - Returns the input buffer


Returns associative array of the output headers

  • ≪ EventHttpRequest::getOutputBuffer
  • EventHttpRequest::getResponseCode ≫
  • PHP Manual
  • EventHttpRequest
  • Returns associative array of the output headers

EventHttpRequest::getOutputHeaders

(PECL event >= 1.4.0-beta)

EventHttpRequest::getOutputHeaders — Returns associative array of the output headers

説明

public EventHttpRequest::getOutputHeaders(): void

Returns associative array of the output headers.

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • EventHttpRequest::getInputHeaders() - Returns associative array of the input headers


Returns the response code

  • ≪ EventHttpRequest::getOutputHeaders
  • EventHttpRequest::getUri ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the response code

EventHttpRequest::getResponseCode

(PECL event >= 1.4.0-beta)

EventHttpRequest::getResponseCode — Returns the response code

説明

public EventHttpRequest::getResponseCode(): int

Returns the response code.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the response code of the request.

参考

  • EventHttpRequest::getCommand() - Returns the request command(method)
  • EventHttpRequest::getHost() - Returns the request host
  • EventHttpRequest::getUri() - Returns the request URI


Returns the request URI

  • ≪ EventHttpRequest::getResponseCode
  • EventHttpRequest::removeHeader ≫
  • PHP Manual
  • EventHttpRequest
  • Returns the request URI

EventHttpRequest::getUri

(PECL event >= 1.4.0-beta)

EventHttpRequest::getUri — Returns the request URI

説明

public EventHttpRequest::getUri(): string

Returns the request URI

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the request URI

参考

  • EventHttpRequest::getCommand() - Returns the request command(method)
  • EventHttpRequest::getHost() - Returns the request host
  • EventHttpRequest::getResponseCode() - Returns the response code


Removes an HTTP header from the headers of the request

  • ≪ EventHttpRequest::getUri
  • EventHttpRequest::sendError ≫
  • PHP Manual
  • EventHttpRequest
  • Removes an HTTP header from the headers of the request

EventHttpRequest::removeHeader

(PECL event >= 1.4.0-beta)

EventHttpRequest::removeHeader — Removes an HTTP header from the headers of the request

説明

public EventHttpRequest::removeHeader( string $key , string $type ): void

Removes an HTTP header from the headers of the request.

パラメータ

key

The header name.

type

type is one of EventHttpRequest::*_HEADER constants.

戻り値

Removes an HTTP header from the headers of the request.

参考

  • EventHttpRequest::addHeader() - Adds an HTTP header to the headers of the request


Send an HTML error message to the client

  • ≪ EventHttpRequest::removeHeader
  • EventHttpRequest::sendReply ≫
  • PHP Manual
  • EventHttpRequest
  • Send an HTML error message to the client

EventHttpRequest::sendError

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendError — Send an HTML error message to the client

説明

public EventHttpRequest::sendError( int $error , string $reason = null ): void

Send an HTML error message to the client.

パラメータ

error

The HTTP error code.

reason

A brief explanation ofthe error. If null, the standard meaning of the error code will be used.

戻り値

値を返しません。

例

例1 EventHttpRequest::sendError() example

<?php
function _http_400($req) {
$req->sendError(400);
}

$base = new EventBase();
$http = new EventHttp($base);

$http->setCallback("/err400", "_http_400");

$http->bind("0.0.0.0", 8010);
$base->loop();
?>

参考

  • EventHttpRequest::sendReply() - Send an HTML reply to the client


Send an HTML reply to the client

  • ≪ EventHttpRequest::sendError
  • EventHttpRequest::sendReplyChunk ≫
  • PHP Manual
  • EventHttpRequest
  • Send an HTML reply to the client

EventHttpRequest::sendReply

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReply — Send an HTML reply to the client

説明

public EventHttpRequest::sendReply( int $code , string $reason , EventBuffer $buf = ?): void

Send an HTML reply to the client. The body of the reply consists of data in optional buf parameter.

パラメータ

code

The HTTP response code to send.

reason

A brief message to send with the response code.

buf

The body of the response.

戻り値

値を返しません。

参考

  • EventHttpRequest::sendError() - Send an HTML error message to the client
  • EventHttpRequest::sendReplyChunk() - Send another data chunk as part of an ongoing chunked reply


Send another data chunk as part of an ongoing chunked reply

  • ≪ EventHttpRequest::sendReply
  • EventHttpRequest::sendReplyEnd ≫
  • PHP Manual
  • EventHttpRequest
  • Send another data chunk as part of an ongoing chunked reply

EventHttpRequest::sendReplyChunk

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReplyChunk — Send another data chunk as part of an ongoing chunked reply

説明

public EventHttpRequest::sendReplyChunk( EventBuffer $buf ): void

Send another data chunk as part of an ongoing chunked reply. After calling this method buf will be empty.

パラメータ

buf

The data chunk to send as part of the reply.

戻り値

値を返しません。

参考

  • EventHttpRequest::sendReplyStart() - Initiate a chunked reply
  • EventHttpRequest::sendReplyEnd() - Complete a chunked reply, freeing the request as appropriate


Complete a chunked reply, freeing the request as appropriate

  • ≪ EventHttpRequest::sendReplyChunk
  • EventHttpRequest::sendReplyStart ≫
  • PHP Manual
  • EventHttpRequest
  • Complete a chunked reply, freeing the request as appropriate

EventHttpRequest::sendReplyEnd

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReplyEnd — Complete a chunked reply, freeing the request as appropriate

説明

public EventHttpRequest::sendReplyEnd(): void

Complete a chunked reply, freeing the request as appropriate.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • EventHttpRequest::sendReplyStart() - Initiate a chunked reply
  • EventHttpRequest::sendReplyChunk() - Send another data chunk as part of an ongoing chunked reply


Initiate a chunked reply

  • ≪ EventHttpRequest::sendReplyEnd
  • EventListener ≫
  • PHP Manual
  • EventHttpRequest
  • Initiate a chunked reply

EventHttpRequest::sendReplyStart

(PECL event >= 1.4.0-beta)

EventHttpRequest::sendReplyStart — Initiate a chunked reply

説明

public EventHttpRequest::sendReplyStart( int $code , string $reason ): void

Initiate a reply that uses Transfer-Encoding chunked .

This allows the caller to stream the reply back to the client and is useful when either not all of the reply data is immediately available or when sending very large replies.

The caller needs to supply data chunks with EventHttpRequest::sendReplyChunk() and complete the reply by calling EventHttpRequest::sendReplyEnd() .

パラメータ

code

The HTTP response code to send.

reason

A brief message to send with the response code.

戻り値

値を返しません。

参考

  • EventHttpRequest::sendReplyChunk() - Send another data chunk as part of an ongoing chunked reply
  • EventHttpRequest::sendReplyEnd() - Complete a chunked reply, freeing the request as appropriate


The EventListener class

(PECL event >= 1.5.0)

はじめに

Represents a connection listener.

クラス概要

final class EventListener {
/* 定数 */
const int OPT_LEAVE_SOCKETS_BLOCKING = 1;
const int OPT_CLOSE_ON_FREE = 2;
const int OPT_CLOSE_ON_EXEC = 4;
const int OPT_REUSEABLE = 8;
const int OPT_THREADSAFE = 16;
/* プロパティ */
public readonly int $fd;
/* メソッド */
public __construct(
EventBase $base ,
callable $cb ,
mixed $data ,
int $flags ,
int $backlog ,
mixed $target
)
public disable(): bool
public enable(): bool
public getBase(): void
public static getSocketName( string &$address , mixed &$port = ?): bool
public setCallback( callable $cb , mixed $arg = null ): void
public setErrorCallback( string $cb ): void
}

プロパティ

fd

Numeric file descriptor of the underlying socket. (Added in event-1.6.0 .)

定義済み定数

EventListener::OPT_LEAVE_SOCKETS_BLOCKING

By default Libevent turns underlying file descriptors, or sockets, to non-blocking mode. This flag tells Libevent to leave them in blocking mode.

EventListener::OPT_CLOSE_ON_FREE

If this option is set, the connection listener closes its underlying socket when the EventListener object is freed.

EventListener::OPT_CLOSE_ON_EXEC

If this option is set, the connection listener sets the close-on-exec flag on the underlying listener socket. See platform documentation for fcntl and FD_CLOEXEC for more information.

EventListener::OPT_REUSEABLE

By default on some platforms, once a listener socket is closed, no other socket can bind to the same port until a while has passed. Setting this option makes Libevent mark the socket as reusable, so that once it is closed, another socket can be opened to listen on the same port.

EventListener::OPT_THREADSAFE

Allocate locks for the listener, so that it's safe to use it from multiple threads.

目次

  • EventListener::__construct — Creates new connection listener associated with an event base
  • EventListener::disable — Disables an event connect listener object
  • EventListener::enable — Enables an event connect listener object
  • EventListener::getBase — Returns event base associated with the event listener
  • EventListener::getSocketName — Retreives the current address to which the listener's socket is bound
  • EventListener::setCallback — The setCallback purpose
  • EventListener::setErrorCallback — Set event listener's error callback


Creates new connection listener associated with an event base

  • ≪ EventListener
  • EventListener::disable ≫
  • PHP Manual
  • EventListener
  • Creates new connection listener associated with an event base

EventListener::__construct

(PECL event >= 1.2.6-beta)

EventListener::__construct — Creates new connection listener associated with an event base

説明

public EventListener::__construct(
EventBase $base ,
callable $cb ,
mixed $data ,
int $flags ,
int $backlog ,
mixed $target
)

Creates new connection listener associated with an event base.

パラメータ

base

Associated event base.

cb

A callable that will be invoked when new connection received.

data

Custom user data attached to cb .

flags

Bit mask of EventListener::OPT_* constants. See EventListener constants .

backlog

Controls the maximum number of pending connections that the network stack should allow to wait in a not-yet-accepted state at any time; see documentation for your system's listen function for more details. If backlog is negative, Libevent tries to pick a good value for the backlog ; if it is zero, Event assumes that listen is already called on the socket (target).

target

May be string, socket resource, or a stream associated with a socket. In case if target is a string, the string will be parsed as network address. It will be interpreted as a UNIX domain socket path, if prefixed with 'unix:' , e.g. 'unix:/tmp/my.sock' .

変更履歴

バージョン | 説明
PECL event 1.5.0 | UNIX domain sockets' support added.

例

例1 EventListener::__construct() example

<?php
/*
* Simple echo server based on libevent's connection listener.
*
* Usage:
* 1) In one terminal window run:
*
* $ php listener.php 9881
*
* 2) In another terminal window open up connection, e.g.:
*
* $ nc 127.0.0.1 9881
*
* 3) start typing. The server should repeat the input.
*/

class MyListenerConnection {
private $bev, $base;

public function __destruct() {
$this->bev->free();
}

public function __construct($base, $fd) {
$this->base = $base;

$this->bev = new EventBufferEvent($base, $fd, EventBufferEvent::OPT_CLOSE_ON_FREE);

$this->bev->setCallbacks(array($this, "echoReadCallback"), NULL,
array($this, "echoEventCallback"), NULL);

if (!$this->bev->enable(Event::READ)) {
echo "Failed to enable READ\n";
return;
}
}

public function echoReadCallback($bev, $ctx) {
// Copy all the data from the input buffer to the output buffer

// Variant #1
$bev->output->addBuffer($bev->input);

/* Variant #2 */
/*
$input = $bev->getInput();
$output = $bev->getOutput();
$output->addBuffer($input);
*/
}

public function echoEventCallback($bev, $events, $ctx) {
if ($events & EventBufferEvent::ERROR) {
echo "Error from bufferevent\n";
}

if ($events & (EventBufferEvent::EOF | EventBufferEvent::ERROR)) {
//$bev->free();
$this->__destruct();
}
}
}

class MyListener {
public $base,
$listener,
$socket;
private $conn = array();

public function __destruct() {
foreach ($this->conn as &$c) $c = NULL;
}

public function __construct($port) {
$this->base = new EventBase();
if (!$this->base) {
echo "Couldn't open event base";
exit(1);
}

// Variant #1
/*
$this->socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if (!socket_bind($this->socket, '0.0.0.0', $port)) {
echo "Unable to bind socket\n";
exit(1);
}
$this->listener = new EventListener($this->base,
array($this, "acceptConnCallback"), $this->base,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE,
-1, $this->socket);
*/

// Variant #2
$this->listener = new EventListener($this->base,
array($this, "acceptConnCallback"), $this->base,
EventListener::OPT_CLOSE_ON_FREE | EventListener::OPT_REUSEABLE, -1,
"0.0.0.0:$port");

if (!$this->listener) {
echo "Couldn't create listener";
exit(1);
}

$this->listener->setErrorCallback(array($this, "accept_error_cb"));
}

public function dispatch() {
$this->base->dispatch();
}

// This callback is invoked when there is data to read on $bev
public function acceptConnCallback($listener, $fd, $address, $ctx) {
// We got a new connection! Set up a bufferevent for it. */
$base = $this->base;
$this->conn[] = new MyListenerConnection($base, $fd);
}

public function accept_error_cb($listener, $ctx) {
$base = $this->base;

fprintf(STDERR, "Got an error %d (%s) on the listener. "
."Shutting down.\n",
EventUtil::getLastSocketErrno(),
EventUtil::getLastSocketError());

$base->exit(NULL);
}
}

$port = 9808;

if ($argc > 1) {
$port = (int) $argv[1];
}
if ($port <= 0 || $port > 65535) {
exit("Invalid port");
}

$l = new MyListener($port);
$l->dispatch();
?>


Disables an event connect listener object

  • ≪ EventListener::__construct
  • EventListener::enable ≫
  • PHP Manual
  • EventListener
  • Disables an event connect listener object

EventListener::disable

(PECL event >= 1.2.6-beta)

EventListener::disable — Disables an event connect listener object

説明

public EventListener::disable(): bool

Disables an event connect listener object

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventListener::enable() - Enables an event connect listener object


Enables an event connect listener object

  • ≪ EventListener::disable
  • EventListener::getBase ≫
  • PHP Manual
  • EventListener
  • Enables an event connect listener object

EventListener::enable

(PECL event >= 1.2.6-beta)

EventListener::enable — Enables an event connect listener object

説明

public EventListener::enable(): bool

Enables an event connect listener object

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • EventListener::disable() - Disables an event connect listener object


Returns event base associated with the event listener

  • ≪ EventListener::enable
  • EventListener::getSocketName ≫
  • PHP Manual
  • EventListener
  • Returns event base associated with the event listener

EventListener::getBase

(PECL event >= 1.2.6-beta)

EventListener::getBase — Returns event base associated with the event listener

説明

public EventListener::getBase(): void

Returns event base associated with the event listener.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns event base associated with the event listener.


Retreives the current address to which the listener's socket is bound

  • ≪ EventListener::getBase
  • EventListener::setCallback ≫
  • PHP Manual
  • EventListener
  • Retreives the current address to which the listener's socket is bound

EventListener::getSocketName

(PECL event >= 1.5.0)

EventListener::getSocketName — Retreives the current address to which the listener's socket is bound

説明

public static EventListener::getSocketName( string &$address , mixed &$port = ?): bool

Retreives the current address to which the listener's socket is bound.

パラメータ

address

Output parameter. IP-address depending on the socket address family.

port

Output parameter. The port the socket is bound to.

戻り値

成功した場合に true を、失敗した場合に false を返します。


The setCallback purpose

  • ≪ EventListener::getSocketName
  • EventListener::setErrorCallback ≫
  • PHP Manual
  • EventListener
  • The setCallback purpose

EventListener::setCallback

(PECL event >= 1.2.6-beta)

EventListener::setCallback — The setCallback purpose

説明

public EventListener::setCallback( callable $cb , mixed $arg = null ): void

Adjust event connect listener's callback and optionally the callback argument.

パラメータ

cb

The new callback for new connections. Ignored if null.

Should match the following prototype:

callback(
EventListener $listener = null ,
mixed $fd = null ,
array $address = null ,
mixed $arg = null
): void

listener

The EventListener object.

fd

The file descriptor or a resource associated with the listener.

address

Array of two elements: IP address and the server port.

arg

User custom data attached to the callback.

arg

Custom user data attached to the callback. Ignored if null.

戻り値

値を返しません。


Set event listener's error callback

  • ≪ EventListener::setCallback
  • EventSslContext ≫
  • PHP Manual
  • EventListener
  • Set event listener's error callback

EventListener::setErrorCallback

(PECL event >= 1.2.6-beta)

EventListener::setErrorCallback — Set event listener's error callback

説明

public EventListener::setErrorCallback( string $cb ): void

Set event listener's error callback

パラメータ

cb

The error callback. Should match the following prototype:

callback( EventListener $listener = null , mixed $data = null ): void

listener

The EventListener object.

data

User custom data attached to the callback.

戻り値

参考

  • EventListener::setCallback() - The setCallback purpose


The EventSslContext class

(PECL event >= 1.2.6-beta)

はじめに

Represents SSL_CTX structure. Provides methods and properties to configure the SSL context.

クラス概要

final class EventSslContext {
/* 定数 */
const int SSLv2_CLIENT_METHOD = 1;
const int SSLv3_CLIENT_METHOD = 2;
const int SSLv23_CLIENT_METHOD = 3;
const int TLS_CLIENT_METHOD = 4;
const int SSLv2_SERVER_METHOD = 5;
const int SSLv3_SERVER_METHOD = 6;
const int SSLv23_SERVER_METHOD = 7;
const int TLS_SERVER_METHOD = 8;
const int OPT_LOCAL_CERT = 1;
const int OPT_LOCAL_PK = 2;
const int OPT_PASSPHRASE = 3;
const int OPT_CA_FILE = 4;
const int OPT_CA_PATH = 5;
const int OPT_ALLOW_SELF_SIGNED = 6;
const int OPT_VERIFY_PEER = 7;
const int OPT_VERIFY_DEPTH = 8;
const int OPT_CIPHERS = 9;
/* プロパティ */
public string $local_cert;
public string $local_pk;
/* メソッド */
public __construct( string $method , string $options )
}

プロパティ

local_cert

Path to local certificate file on filesystem. It must be a PEM-encoded file which contains certificate. It can optionally contain the certificate chain of issuers.

local_pk

Path to local private key file

定義済み定数

EventSslContext::SSLv2_CLIENT_METHOD

SSLv2 client method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv3_CLIENT_METHOD

SSLv3 client method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv23_CLIENT_METHOD

SSLv23 client method. See SSL_CTX_new(3) man page.

EventSslContext::TLS_CLIENT_METHOD

TLS client method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv2_SERVER_METHOD

SSLv2 server method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv3_SERVER_METHOD

SSLv3 server method. See SSL_CTX_new(3) man page.

EventSslContext::SSLv23_SERVER_METHOD

SSLv23 server method. See SSL_CTX_new(3) man page.

EventSslContext::TLS_SERVER_METHOD

TLS server method. See SSL_CTX_new(3) man page.

EventSslContext::OPT_LOCAL_CERT

Key for an item of the options' array used in EventSslContext::__construct() . The option points to path of local certificate.

EventSslContext::OPT_LOCAL_PK

Key for an item of the options' array used in EventSslContext::__construct() . The option points to path of the private key.

EventSslContext::OPT_PASSPHRASE

Key for an item of the options' array used in EventSslContext::__construct() . Represents passphrase of the certificate.

EventSslContext::OPT_CA_FILE

Key for an item of the options' array used in EventSslContext::__construct() . Represents path of the certificate authority file.

EventSslContext::OPT_CA_PATH

Key for an item of the options' array used in EventSslContext::__construct() . Represents path where the certificate authority file should be searched for.

EventSslContext::OPT_ALLOW_SELF_SIGNED

Key for an item of the options' array used in EventSslContext::__construct() . Represents option that allows self-signed certificates.

EventSslContext::OPT_VERIFY_PEER

Key for an item of the options' array used in EventSslContext::__construct() . Represents option that tells Event to verify peer.

EventSslContext::OPT_VERIFY_DEPTH

Key for an item of the options' array used in EventSslContext::__construct() . Represents maximum depth for the certificate chain verification that shall be allowed for the SSL context.

EventSslContext::OPT_CIPHERS

Key for an item of the options' array used in EventSslContext::__construct() . Represents the cipher list for the SSL context.

目次

  • EventSslContext::__construct — Constructs an OpenSSL context for use with Event classes


Constructs an OpenSSL context for use with Event classes

  • ≪ EventSslContext
  • EventUtil ≫
  • PHP Manual
  • EventSslContext
  • Constructs an OpenSSL context for use with Event classes

EventSslContext::__construct

(PECL event >= 1.2.6-beta)

EventSslContext::__construct — Constructs an OpenSSL context for use with Event classes

説明

public EventSslContext::__construct( string $method , string $options )

Creates SSL context holding pointer to SSL_CTX (see the system manual).

パラメータ

method

One of EventSslContext::*_METHOD constants .

options

Associative array of SSL context options One of EventSslContext::OPT_* constants .

例

例1 EventSslContext::__construct() example

<?php
$ctx = new EventSslContext(EventSslContext::SSLv3_SERVER_METHOD, array(
EventSslContext::OPT_LOCAL_CERT => $local_cert,
EventSslContext::OPT_LOCAL_PK => $local_pk,
EventSslContext::OPT_PASSPHRASE => "echo server",
EventSslContext::OPT_VERIFY_PEER => true,
EventSslContext::OPT_ALLOW_SELF_SIGNED => false,
));
?>


The EventUtil class

(PECL event >= 1.5.0)

はじめに

EventUtil is a singleton with supplimentary methods and constants.

クラス概要

final class EventUtil {
/* 定数 */
const int AF_INET = 2;
const int AF_INET6 = 10;
const int AF_UNSPEC = 0;
const int LIBEVENT_VERSION_NUMBER = 33559808;
const int SO_DEBUG = 1;
const int SO_REUSEADDR = 2;
const int SO_KEEPALIVE = 9;
const int SO_DONTROUTE = 5;
const int SO_LINGER = 13;
const int SO_BROADCAST = 6;
const int SO_OOBINLINE = 10;
const int SO_SNDBUF = 7;
const int SO_RCVBUF = 8;
const int SO_SNDLOWAT = 19;
const int SO_RCVLOWAT = 18;
const int SO_SNDTIMEO = 21;
const int SO_RCVTIMEO = 20;
const int SO_TYPE = 3;
const int SO_ERROR = 4;
const int SOL_SOCKET = 1;
const int SOL_TCP = 6;
const int SOL_UDP = 17;
const int IPPROTO_IP = 0;
const int IPPROTO_IPV6 = 41;
/* メソッド */
abstract public __construct()
public static getLastSocketErrno( mixed $socket = null ): int
public static getLastSocketError( mixed $socket = ?): string
public static getSocketFd( mixed $socket ): int
public static getSocketName( mixed $socket , string &$address , mixed &$port = ?): bool
public static setSocketOption(
mixed $socket ,
int $level ,
int $optname ,
mixed $optval
): bool
public static sslRandPoll(): void
}

定義済み定数

EventUtil::AF_INET

IPv4 address family

EventUtil::AF_INET6

IPv6 address family

EventUtil::AF_UNSPEC

Unspecified IP address family

EventUtil::SO_DEBUG

Socket option. Enable socket debugging. Only allowed for processes with the CAP_NET_ADMIN capability or an effective user ID of 0 . (Added in event-1.6.0.)

EventUtil::SO_REUSEADDR

Socket option. Indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_KEEPALIVE

Socket option. Enable sending of keep-alive messages on connection-oriented sockets. Expects an integer boolean flag. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_DONTROUTE

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_LINGER

Socket option. When enabled, a close(2) or shutdown(2) will not return until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Otherwise, the call returns immediately and the closing is done in the background. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_BROADCAST

Socket option. Reports whether transmission of broadcast messages is supported. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_OOBINLINE

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_SNDBUF

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_RCVBUF

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_SNDLOWAT

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_RCVLOWAT

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_SNDTIMEO

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_RCVTIMEO

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_TYPE

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SO_ERROR

Socket option. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SOL_SOCKET

Socket option level. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SOL_TCP

Socket option level. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::SOL_UDP

Socket option level. See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::IPPROTO_IP

See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::IPPROTO_IPV6

See the socket(7) manual page. (Added in event-1.6.0.)

EventUtil::LIBEVENT_VERSION_NUMBER

Libevent' version number at the time when Event extension had been compiled with the library.

目次

  • EventUtil::__construct — The abstract constructor
  • EventUtil::getLastSocketErrno — Returns the most recent socket error number
  • EventUtil::getLastSocketError — Returns the most recent socket error
  • EventUtil::getSocketFd — Returns numeric file descriptor of a socket, or stream
  • EventUtil::getSocketName — Retreives the current address to which the socket is bound
  • EventUtil::setSocketOption — Sets socket options
  • EventUtil::sslRandPoll — Generates entropy by means of OpenSSL's RAND_poll()


The abstract constructor

  • ≪ EventUtil
  • EventUtil::getLastSocketErrno ≫
  • PHP Manual
  • EventUtil
  • The abstract constructor

EventUtil::__construct

(PECL event >= 1.2.6-beta)

EventUtil::__construct — The abstract constructor

説明

abstract public EventUtil::__construct()

EventUtil is a singleton. Therefore the constructor is abstract, and it is impossible to create objects based on this class.

パラメータ

この関数にはパラメータはありません。


Returns the most recent socket error number

  • ≪ EventUtil::__construct
  • EventUtil::getLastSocketError ≫
  • PHP Manual
  • EventUtil
  • Returns the most recent socket error number

EventUtil::getLastSocketErrno

(PECL event >= 1.2.6-beta)

EventUtil::getLastSocketErrno — Returns the most recent socket error number

説明

public static EventUtil::getLastSocketErrno( mixed $socket = null ): int

Returns the most recent socket error number( errno ).

パラメータ

socket

Socket resource, stream or a file descriptor of a socket.

戻り値

Returns the most recent socket error number( errno ).

参考

  • EventUtil::getLastSocketError() - Returns the most recent socket error


Returns the most recent socket error

  • ≪ EventUtil::getLastSocketErrno
  • EventUtil::getSocketFd ≫
  • PHP Manual
  • EventUtil
  • Returns the most recent socket error

EventUtil::getLastSocketError

(PECL event >= 1.2.6-beta)

EventUtil::getLastSocketError — Returns the most recent socket error

説明

public static EventUtil::getLastSocketError( mixed $socket = ?): string

Returns the most recent socket error.

パラメータ

socket

Socket resource, stream or a file descriptor of a socket.

戻り値

Returns the most recent socket error.

参考

  • EventUtil::getLastSocketErrno() - Returns the most recent socket error number


Returns numeric file descriptor of a socket, or stream

  • ≪ EventUtil::getLastSocketError
  • EventUtil::getSocketName ≫
  • PHP Manual
  • EventUtil
  • Returns numeric file descriptor of a socket, or stream

EventUtil::getSocketFd

(PECL event >= 1.7.0)

EventUtil::getSocketFd — Returns numeric file descriptor of a socket, or stream

説明

public static EventUtil::getSocketFd( mixed $socket ): int

Returns numeric file descriptor of a socket or stream specified by socket argument just like the Event extension does it internally for all methods accepting socket resource or stream.

パラメータ

socket

Socket resource or stream.

戻り値

Returns numeric file descriptor of a socket, or stream. EventUtil::getSocketFd() returns false in case if it is whether failed to recognize the type of the underlying file, or detected that the file descriptor associated with socket is not valid.


Retreives the current address to which the socket is bound

  • ≪ EventUtil::getSocketFd
  • EventUtil::setSocketOption ≫
  • PHP Manual
  • EventUtil
  • Retreives the current address to which the socket is bound

EventUtil::getSocketName

(PECL event >= 1.5.0)

EventUtil::getSocketName — Retreives the current address to which the socket is bound

説明

public static EventUtil::getSocketName( mixed $socket , string &$address , mixed &$port = ?): bool

Retreives the current address to which the socket is bound.

パラメータ

socket

Socket resource, stream or a file descriptor of a socket.

address

Output parameter. IP-address, or the UNIX domain socket path depending on the socket address family.

port

Output parameter. The port the socket is bound to. Has no meaning for UNIX domain sockets.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Sets socket options

  • ≪ EventUtil::getSocketName
  • EventUtil::sslRandPoll ≫
  • PHP Manual
  • EventUtil
  • Sets socket options

EventUtil::setSocketOption

(PECL event >= 1.6.0)

EventUtil::setSocketOption — Sets socket options

説明

public static EventUtil::setSocketOption(
mixed $socket ,
int $level ,
int $optname ,
mixed $optval
): bool

Sets socket options.

パラメータ

socket

Socket resource, stream, or numeric file descriptor associated with the socket.

level

One of EventUtil::SOL_* constants. Specifies the protocol level at which the option resides. For example, to retrieve options at the socket level, a level parameter of EventUtil::SOL_SOCKET would be used. Other levels, such as TCP, can be used by specifying the protocol number of that level. Protocol numbers can be found by using the getprotobyname() function. See EventUtil constants .

optname

Option name(type). Has the same meaning as corresponding parameter of socket_get_option() function. See EventUtil constants .

optval

Accepts the same values as optval parameter of the socket_get_option() function.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • socket_get_option() - ソケットのオプションを取得する
  • socket_set_option() - ソケットのオプションを設定する


Generates entropy by means of OpenSSL's RAND_poll()

  • ≪ EventUtil::setSocketOption
  • EventException ≫
  • PHP Manual
  • EventUtil
  • Generates entropy by means of OpenSSL's RAND_poll()

EventUtil::sslRandPoll

(PECL event >= 1.2.6-beta)

EventUtil::sslRandPoll — Generates entropy by means of OpenSSL's RAND_poll()

説明

public static EventUtil::sslRandPoll(): void

Generates entropy by means of OpenSSL's RAND_poll() (see the system manual).

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


The EventException class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

A EventException is thrown when the Event extension methods encounter invalid user input or identify an unrecoverable error. This exception serves as a signal for developers to handle exceptional situations gracefully.

クラス概要

class EventException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Error::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Error::getMessage(): string
final public Error::getPrevious(): ?Throwable
final public Error::getCode(): int
final public Error::getFile(): string
final public Error::getLine(): int
final public Error::getTrace(): array
final public Error::getTraceAsString(): string
public Error::__toString(): string
private Error::__clone(): void
}


FTP

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • FTP 関数
    • ftp_alloc — アップロードされるファイルのためのスペースを確保する
    • ftp_append — ファイルの内容をFTPサーバー上の別のファイルに追加する
    • ftp_cdup — 親ディレクトリに移動する
    • ftp_chdir — FTP サーバー上でディレクトリを移動する
    • ftp_chmod — FTP 経由でファイルのパーミッションを設定する
    • ftp_close — FTP 接続を閉じる
    • ftp_connect — FTP 接続をオープンする
    • ftp_delete — FTP サーバー上のファイルを削除する
    • ftp_exec — FTP サーバー上でのコマンドの実行をリクエストする
    • ftp_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
    • ftp_fput — オープン中のファイルを FTP サーバーにアップロードする
    • ftp_get — FTP サーバーからファイルをダウンロードする
    • ftp_get_option — カレントの FTP 接続での種々の実行時動作を取得する
    • ftp_login — FTP 接続にログインする
    • ftp_mdtm — 指定したファイルが最後に更新された時刻を返す
    • ftp_mkdir — ディレクトリを作成する
    • ftp_mlsd — ディレクトリに存在するファイルの一覧を返す
    • ftp_nb_continue — ファイルの取得/送信を継続する（非ブロッキング）
    • ftp_nb_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
    • ftp_nb_fput — オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
    • ftp_nb_get — FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
    • ftp_nb_put — FTP サーバーにファイルを保存する（非ブロッキング）
    • ftp_nlist — 指定したディレクトリのファイルの一覧を返す
    • ftp_pasv — パッシブモードをオンまたはオフにする
    • ftp_put — FTP サーバーにファイルをアップロードする
    • ftp_pwd — カレントのディレクトリ名を返す
    • ftp_quit — ftp_close のエイリアス
    • ftp_raw — FTP サーバーに任意のコマンドを送信する
    • ftp_rawlist — 指定したディレクトリの詳細なファイル一覧を返す
    • ftp_rename — FTP サーバー上のファイルまたはディレクトリの名前を変更する
    • ftp_rmdir — ディレクトリを削除する
    • ftp_set_option — さまざまな FTP 実行時オプションを設定する
    • ftp_site — SITEコマンドをサーバーに送信する
    • ftp_size — 指定したファイルのサイズを返す
    • ftp_ssl_connect — セキュアな SSL-FTP 接続をオープンする
    • ftp_systype — リモート FTP サーバーのシステム型 ID を返す
  • FTP\Connection — FTP\Connection クラス


はじめに

この拡張モジュールの関数は、» http://www.faqs.org/rfcs/rfc959 で定義された File Transfer Protocol (FTP) を使用してファイルサーバーに アクセスするクライアントの実装です。この拡張を利用することで、FTP サーバーにアクセスしてさまざまな操作をするスクリプトを作成することができます。 ただ単に FTP サーバー上のファイルを読み書きしたいだけなら、 ファイルシステム関数 で ftp:// ラッパー を用いることを考えてください。こちらのほうがシンプルで直感的な インターフェイスを提供します。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • FTP
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

PHP で FTP 関数を使用するには、PHP をインストールする際に --enable-ftp オプションを追加する必要があります。

Windows 版の PHP では、 この拡張モジュールは共有モジュールとしてビルドされます。 これらの関数を使うには、php.ini でモジュールを有効にする必要があります。


リソース型

PHP 8.1.0 より前のバージョンでは、 この拡張モジュールは、1 種類のリソース型を使用していました。 FTP 接続のリソース ID で、ftp_connect() あるいは ftp_ssl_connect() により返されたものです。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

FTP_ASCII (int)

FTP_AUTOSEEK (int)

ftp_set_option() を参照ください。

FTP_AUTORESUME (int)

GET と PUT において、自動的に通信を再開する位置と、通信を開始する位置を自動で決定します。 (FTP_AUTOSEEK が有効な場合のみ機能します)

FTP_FAILED (int)

非同期転送が失敗したことを示します。

FTP_FINISHED (int)

非同期転送が終了したことを示します。

FTP_MOREDATA (int)

非同期転送がまだ生きていることを示します。

FTP_TEXT (int)

FTP_ASCII のエイリアスです。

FTP_BINARY (int)

FTP_IMAGE (int)

FTP_BINARY のエイリアスです。

FTP_TIMEOUT_SEC (int)

ftp_set_option() を参照ください。

FTP_USEPASVADDRESS (int)

ftp_set_option() を参照ください。


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • FTP
  • 例

例

目次

  • 基本的な使用法


基本的な使用法

例1 FTP の例

<?php
// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// 接続できたか確認する
if ((!$ftp) || (!$login_result)) {
echo "FTP connection has failed!";
echo "Attempted to connect to $ftp_server for user $ftp_user_name";
exit;
} else {
echo "Connected to $ftp_server, for user $ftp_user_name";
}

// ファイルをアップロードする
$upload = ftp_put($ftp, $destination_file, $source_file, FTP_BINARY);

// アップロード状況を確認する
if (!$upload) {
echo "FTP upload has failed!";
} else {
echo "Uploaded $source_file to $ftp_server as $destination_file";
}

// FTP ストリームを閉じる
ftp_close($ftp);
?>


FTP 関数

目次

  • ftp_alloc — アップロードされるファイルのためのスペースを確保する
  • ftp_append — ファイルの内容をFTPサーバー上の別のファイルに追加する
  • ftp_cdup — 親ディレクトリに移動する
  • ftp_chdir — FTP サーバー上でディレクトリを移動する
  • ftp_chmod — FTP 経由でファイルのパーミッションを設定する
  • ftp_close — FTP 接続を閉じる
  • ftp_connect — FTP 接続をオープンする
  • ftp_delete — FTP サーバー上のファイルを削除する
  • ftp_exec — FTP サーバー上でのコマンドの実行をリクエストする
  • ftp_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_fput — オープン中のファイルを FTP サーバーにアップロードする
  • ftp_get — FTP サーバーからファイルをダウンロードする
  • ftp_get_option — カレントの FTP 接続での種々の実行時動作を取得する
  • ftp_login — FTP 接続にログインする
  • ftp_mdtm — 指定したファイルが最後に更新された時刻を返す
  • ftp_mkdir — ディレクトリを作成する
  • ftp_mlsd — ディレクトリに存在するファイルの一覧を返す
  • ftp_nb_continue — ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_nb_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
  • ftp_nb_fput — オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_get — FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_put — FTP サーバーにファイルを保存する（非ブロッキング）
  • ftp_nlist — 指定したディレクトリのファイルの一覧を返す
  • ftp_pasv — パッシブモードをオンまたはオフにする
  • ftp_put — FTP サーバーにファイルをアップロードする
  • ftp_pwd — カレントのディレクトリ名を返す
  • ftp_quit — ftp_close のエイリアス
  • ftp_raw — FTP サーバーに任意のコマンドを送信する
  • ftp_rawlist — 指定したディレクトリの詳細なファイル一覧を返す
  • ftp_rename — FTP サーバー上のファイルまたはディレクトリの名前を変更する
  • ftp_rmdir — ディレクトリを削除する
  • ftp_set_option — さまざまな FTP 実行時オプションを設定する
  • ftp_site — SITEコマンドをサーバーに送信する
  • ftp_size — 指定したファイルのサイズを返す
  • ftp_ssl_connect — セキュアな SSL-FTP 接続をオープンする
  • ftp_systype — リモート FTP サーバーのシステム型 ID を返す


アップロードされるファイルのためのスペースを確保する

  • ≪ FTP 関数
  • ftp_append ≫
  • PHP Manual
  • FTP 関数
  • アップロードされるファイルのためのスペースを確保する

ftp_alloc

(PHP 5, PHP 7, PHP 8)

ftp_alloc — アップロードされるファイルのためのスペースを確保する

説明

ftp_alloc(FTP\Connection $ftp, int $size, string &$response = null): bool

ALLO コマンドを FTP サーバーに送信し、 アップロードされるファイルのためのスペースを確保します。

注意:

多くの FTP サーバーはこのコマンドをサポートしていません。これらのサーバーの中には、 「そのコマンドをサポートしていない」という意味で失敗コード（false） を返すものもあれば 「事前に確保する必要はない」という意味で成功コード（true） を返すものもあります。このような理由から、事前のスペース確保が明示的に 要求されているサーバーに対してのみこの関数を使用するようにするとよいでしょう。

パラメータ

ftp

FTP\Connection クラスのインスタンス

size

確保したいバイト数。

response

response 変数が指定されていた場合、 サーバーからの応答テキストの内容の参照が格納されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_alloc() の例

<?php

$file = "/home/user/myfile";

// サーバーに接続する
$ftp = ftp_connect('ftp.example.com');
$login_result = ftp_login($ftp, 'anonymous', 'user@example.com');

if (ftp_alloc($ftp, filesize($file), $result)) {
echo "Space successfully allocated on server. Sending $file.\n";
ftp_put($ftp, '/incoming/myfile', $file, FTP_BINARY);
} else {
echo "Unable to allocate space on server. Server said: $result\n";
}

ftp_close($ftp);

?>

参考

  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする


ファイルの内容をFTPサーバー上の別のファイルに追加する

  • ≪ ftp_alloc
  • ftp_cdup ≫
  • PHP Manual
  • FTP 関数
  • ファイルの内容をFTPサーバー上の別のファイルに追加する

ftp_append

(PHP 7 >= 7.2.0, PHP 8)

ftp_append — ファイルの内容をFTPサーバー上の別のファイルに追加する

説明

ftp_append(
FTP\Connection $ftp,
string $remote_filename,
string $local_filename,
int $mode = FTP_BINARY
): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ftp

FTP\Connection クラスのインスタンス

remote_filename

local_filename

mode

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。


親ディレクトリに移動する

  • ≪ ftp_append
  • ftp_chdir ≫
  • PHP Manual
  • FTP 関数
  • 親ディレクトリに移動する

ftp_cdup

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_cdup — 親ディレクトリに移動する

説明

ftp_cdup(FTP\Connection $ftp): bool

親ディレクトリに移動します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_cdup() の例

<?php
// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// html ディレクトリに移動する
ftp_chdir($ftp, 'html');

echo ftp_pwd($ftp); // /html

// 親ディレクトリに戻る
if (ftp_cdup($ftp)) {
echo "cdup successful\n";
} else {
echo "cdup not successful\n";
}

echo ftp_pwd($ftp); // /

ftp_close($ftp);
?>

参考

  • ftp_chdir() - FTP サーバー上でディレクトリを移動する
  • ftp_pwd() - カレントのディレクトリ名を返す


FTP サーバー上でディレクトリを移動する

  • ≪ ftp_cdup
  • ftp_chmod ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上でディレクトリを移動する

ftp_chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_chdir — FTP サーバー上でディレクトリを移動する

説明

ftp_chdir(FTP\Connection $ftp, string $directory): bool

カレントディレクトリを、指定した場所に移動します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

directory

対象となるディレクトリ。

戻り値

成功した場合に true を、失敗した場合に false を返します。 ディレクトリの変更に失敗した場合は、PHP は警告を出します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_chdir() の例

<?php

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// 接続できたか確認する
if ((!$ftp) || (!$login_result)) {
die("FTP connection has failed !");
}

echo "Current directory: " . ftp_pwd($ftp) . "\n";

// somedir に移動する
if (ftp_chdir($ftp, "somedir")) {
echo "Current directory is now: " . ftp_pwd($ftp) . "\n";
} else {
echo "Couldn't change directory\n";
}

// 接続を閉じる
ftp_close($ftp);
?>

参考

  • ftp_cdup() - 親ディレクトリに移動する
  • ftp_pwd() - カレントのディレクトリ名を返す


FTP 経由でファイルのパーミッションを設定する

  • ≪ ftp_chdir
  • ftp_close ≫
  • PHP Manual
  • FTP 関数
  • FTP 経由でファイルのパーミッションを設定する

ftp_chmod

(PHP 5, PHP 7, PHP 8)

ftp_chmod — FTP 経由でファイルのパーミッションを設定する

説明

ftp_chmod(FTP\Connection $ftp, int $permissions, string $filename): int|false

指定したリモートファイルのパーミッションを permissions に設定します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

permissions

新しいパーミッション。8 進数 で指定します。

filename

リモートファイル。

戻り値

成功した場合に新しいパーミッションを、エラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_chmod() の例

<?php
$file = 'public_html/index.php';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $file のパーミッションを 644 に変更する
if (ftp_chmod($ftp, 0644, $file) !== false) {
echo "$file chmoded successfully to 644\n";
} else {
echo "could not chmod $file\n";
}

// 接続を閉じる
ftp_close($ftp);
?>

参考

  • chmod() - ファイルのモードを変更する


FTP 接続を閉じる

  • ≪ ftp_chmod
  • ftp_connect ≫
  • PHP Manual
  • FTP 関数
  • FTP 接続を閉じる

ftp_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftp_close — FTP 接続を閉じる

説明

ftp_close(FTP\Connection $ftp): bool

ftp_close() は、指定されたリンク ID を閉じて resource を開放します。

注意:

この関数をコールした後は、FTP 接続を利用することはできません。 利用するためには ftp_connect() で新しい接続を 作成しなければなりません。

パラメータ

ftp

FTP\Connection クラスのインスタンス

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_close() の例

<?php

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// 現在のディレクトリを表示する
echo ftp_pwd($ftp);

// 接続を閉じる
ftp_close($ftp);
?>

参考

  • ftp_connect() - FTP 接続をオープンする


FTP 接続をオープンする

  • ≪ ftp_close
  • ftp_delete ≫
  • PHP Manual
  • FTP 関数
  • FTP 接続をオープンする

ftp_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_connect — FTP 接続をオープンする

説明

ftp_connect(string $hostname, int $port = 21, int $timeout = 90): FTP\Connection|false

ftp_connect() は、指定した hostname への FTP 接続をオープンします。

パラメータ

hostname

FTP サーバーのアドレス。このパラメータには、最後のスラッシュや最初の ftp:// をつけてはいけません。

port

このパラメータは接続先のポートを指定します。もし指定しなかったり ゼロを指定したりした場合は、デフォルトの FTP ポートである 21 が用いられます。

timeout

このパラメータは、以降のネットワーク操作時のタイムアウトを秒単位で指定します。 指定されなかった場合のデフォルト値は 90 秒です。タイムアウトの変更や 参照は、ftp_set_option() や ftp_get_option() を用いていつでも可能です。

戻り値

成功した場合に FTP\Connection クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | FTP\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース が返されていました。

例

例1 ftp_connect() の例

<?php

$ftp_server = "ftp.example.com";

// 接続を確立します。できなければ終了します。
$ftp = ftp_connect($ftp_server) or die("Couldn't connect to $ftp_server");

?>

参考

  • ftp_close() - FTP 接続を閉じる
  • ftp_ssl_connect() - セキュアな SSL-FTP 接続をオープンする


FTP サーバー上のファイルを削除する

  • ≪ ftp_connect
  • ftp_exec ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上のファイルを削除する

ftp_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_delete — FTP サーバー上のファイルを削除する

説明

ftp_delete(FTP\Connection $ftp, string $filename): bool

ftp_delete() は、filename で指定したファイルを FTP サーバーから削除します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

filename

削除するファイル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_delete() の例

<?php
$file = 'public_html/old.txt';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $file の削除を試みる
if (ftp_delete($ftp, $file)) {
echo "$file deleted successful\n";
} else {
echo "could not delete $file\n";
}

// 接続を閉じる
ftp_close($ftp);
?>


FTP サーバー上でのコマンドの実行をリクエストする

  • ≪ ftp_delete
  • ftp_fget ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上でのコマンドの実行をリクエストする

ftp_exec

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

ftp_exec — FTP サーバー上でのコマンドの実行をリクエストする

説明

ftp_exec(FTP\Connection $ftp, string $command): bool

FTP サーバーに SITE EXEC command リクエストを 送信します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

command

実行したいコマンド。

戻り値

コマンドが成功した（サーバーの応答コードが 200） 場合に true を、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_exec() の例

<?php

// 変数を初期化します。
$command = 'ls -al >files.txt';

// 接続を確立します。
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードを指定してログインします。
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// コマンドを実行します。
if (ftp_exec($ftp, $command)) {
echo "$command executed successfully\n";
} else {
echo "could not execute $command\n";
}

// 接続を閉じます。
ftp_close($ftp);

?>

参考

  • ftp_raw() - FTP サーバーに任意のコマンドを送信する


FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する

  • ≪ ftp_exec
  • ftp_fput ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する

ftp_fget

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する

説明

ftp_fget(
FTP\Connection $ftp,
resource $stream,
string $remote_filename,
int $mode = FTP_BINARY,
int $offset = 0
): bool

ftp_fget() は、FTP サーバーから remote_filename を取得し、指定したファイルポインタに書きこみます。

パラメータ

ftp

FTP\Connection クラスのインスタンス

stream

オープンされているファイルのポインタ。ここにデータが保存されます。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル中で、ダウンロードを開始する位置。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_fget() の例

<?php

// リモートファイルへのパス。
$remote_file = 'somefile.txt';
$local_file = 'localfile.txt';

// 書き込み用のファイルをオープンします。
$handle = fopen($local_file, 'w');

// 接続を確立します。
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードを指定してログインします。
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $remote_file をダウンロードし、$handle に保存しようとします。
if (ftp_fget($ftp, $handle, $remote_file, FTP_ASCII, 0)) {
echo "successfully written to $local_file\n";
} else {
echo "There was a problem while downloading $remote_file to $local_file\n";
}

// 接続およびファイルハンドラを閉じます。
ftp_close($ftp);
fclose($handle);
?>

参考

  • ftp_get() - FTP サーバーからファイルをダウンロードする
  • ftp_nb_get() - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）


オープン中のファイルを FTP サーバーにアップロードする

  • ≪ ftp_fget
  • ftp_get ≫
  • PHP Manual
  • FTP 関数
  • オープン中のファイルを FTP サーバーにアップロードする

ftp_fput

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_fput — オープン中のファイルを FTP サーバーにアップロードする

説明

ftp_fput(
FTP\Connection $ftp,
string $remote_filename,
resource $stream,
int $mode = FTP_BINARY,
int $offset = 0
): bool

ftp_fput() は、ファイルポインタが指すデータを FTP サーバー上のリモートファイルへアップロードします。

パラメータ

ftp

FTP\Connection クラスのインスタンス

remote_filename

リモートファイルのパス。

stream

ローカルでオープンされているファイルのポインタ。 ファイルの終端まで進むと読み込みが終了します。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_fput() の例

<?php

// ファイルを読み込みモードで開く
$file = 'somefile.txt';
$fp = fopen($file, 'r');

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $file のアップロードを試みる
if (ftp_fput($ftp, $file, $fp, FTP_ASCII)) {
echo "Successfully uploaded $file\n";
} else {
echo "There was a problem while uploading $file\n";
}

// 接続を閉じ、ファイルを閉じる
ftp_close($ftp);
fclose($fp);

?>

参考

  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_nb_fput() - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_put() - FTP サーバーにファイルを保存する（非ブロッキング）


FTP サーバーからファイルをダウンロードする

  • ≪ ftp_fput
  • ftp_get_option ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルをダウンロードする

ftp_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_get — FTP サーバーからファイルをダウンロードする

説明

ftp_get(
FTP\Connection $ftp,
string $local_filename,
string $remote_filename,
int $mode = FTP_BINARY,
int $offset = 0
): bool

ftp_get() は FTP サーバーからリモートファイルを取得し、 それをローカルファイルに保存します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

local_filename

ローカルファイルのパス（ファイルがすでに存在する場合は上書きされます）。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイルの、ダウンロードを開始する位置。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_get() の例

<?php

// 変数を定義する
$local_file = 'local.zip';
$server_file = 'server.zip';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $server_file をダウンロードし、$local_file への保存を試みる
if (ftp_get($ftp, $local_file, $server_file, FTP_BINARY)) {
echo "Successfully written to $local_file\n";
} else {
echo "There was a problem\n";
}

// 接続を閉じる
ftp_close($ftp);

?>

参考

  • ftp_pasv() - パッシブモードをオンまたはオフにする
  • ftp_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_nb_get() - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）


カレントの FTP 接続での種々の実行時動作を取得する

  • ≪ ftp_get
  • ftp_login ≫
  • PHP Manual
  • FTP 関数
  • カレントの FTP 接続での種々の実行時動作を取得する

ftp_get_option

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftp_get_option — カレントの FTP 接続での種々の実行時動作を取得する

説明

ftp_get_option(FTP\Connection $ftp, int $option): int|bool

この関数は、指定した FTP 接続について option の値を返します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

option

現在、以下のオプションがサポートされています:

サポートされる実行時 FTP オプション
FTP_TIMEOUT_SEC | ネットワーク関連処理で使用されるカレントのタイムアウトを返します。
FTP_AUTOSEEK | オプションが設定されている場合に true を、それ以外の場合に false を返します。

戻り値

成功した場合はその値を、指定した option がサポートされていない場合は false を返します。後者の場合は、 同時に警告メッセージも発生します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_get_option() の例

<?php
// 指定した FTP ストリームのタイムアウトを取得する
$timeout = ftp_get_option($ftp, FTP_TIMEOUT_SEC);
?>

参考

  • ftp_set_option() - さまざまな FTP 実行時オプションを設定する


FTP 接続にログインする

  • ≪ ftp_get_option
  • ftp_mdtm ≫
  • PHP Manual
  • FTP 関数
  • FTP 接続にログインする

ftp_login

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_login — FTP 接続にログインする

説明

ftp_login(FTP\Connection $ftp, string $username, #[\SensitiveParameter] string $password): bool

指定した FTP 接続を使ってログインします。

パラメータ

ftp

FTP\Connection クラスのインスタンス

username

ユーザー名（USER）。

password

パスワード（PASS）。

戻り値

成功した場合に true を、失敗した場合に false を返します。 失敗した場合は、PHP が警告を発生します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_login() の例

<?php

$ftp_server = "ftp.example.com";
$ftp_user = "foo";
$ftp_pass = "bar";

// 接続を確立する。接続に失敗したら終了する。
$ftp = ftp_connect($ftp_server) or die("Couldn't connect to $ftp_server");

// ログインを試みる
if (@ftp_login($ftp, $ftp_user, $ftp_pass)) {
echo "Connected as $ftp_user@$ftp_server\n";
} else {
echo "Couldn't connect as $ftp_user\n";
}

// 接続を閉じる
ftp_close($ftp);
?>


指定したファイルが最後に更新された時刻を返す

  • ≪ ftp_login
  • ftp_mkdir ≫
  • PHP Manual
  • FTP 関数
  • 指定したファイルが最後に更新された時刻を返す

ftp_mdtm

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_mdtm — 指定したファイルが最後に更新された時刻を返す

説明

ftp_mdtm(FTP\Connection $ftp, string $filename): int

ftp_mdtm() はリモートファイルが最後に更新された時刻を取得します。

注意:

すべてのサーバーがこの機能をサポートしているわけではありません!

注意:

ftp_mdtm() はディレクトリに対しては機能しません。

パラメータ

ftp

FTP\Connection クラスのインスタンス

filename

最終更新時刻を取得するファイル。

戻り値

成功した場合に、最終更新時刻を ローカル 側のUNIXのタイムスタンプとして返します。 エラー時に -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_mdtm() の例

<?php

$file = 'somefile.txt';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// 最終更新時刻を取得する
$buff = ftp_mdtm($ftp, $file);

if ($buff != -1) {
// somefile.txt の最終更新時刻は: March 26 2003 14:16:41.
echo "$file was last modified on : " . date("F d Y H:i:s.", $buff);
} else {
echo "Couldn't get mdtime";
}

// 接続を閉じる
ftp_close($ftp);

?>


ディレクトリを作成する

  • ≪ ftp_mdtm
  • ftp_mlsd ≫
  • PHP Manual
  • FTP 関数
  • ディレクトリを作成する

ftp_mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_mkdir — ディレクトリを作成する

説明

ftp_mkdir(FTP\Connection $ftp, string $directory): string|false

FTP サーバー上に、指定した directory を作成します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

directory

作成されるディレクトリの名前。

戻り値

成功した時には新規に作成したディレクトリ名、エラー時に false を返します。

エラー / 例外

ディレクトリが既に存在していたり、 パーミッションによってディレクトリが作成できなかった場合、 E_WARNING レベルの警告が発生します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_mkdir() の例

<?php

$dir = 'www';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// ディレクトリ $dir の作成を試みる
if (ftp_mkdir($ftp, $dir)) {
echo "successfully created $dir\n";
} else {
echo "There was a problem while creating $dir\n";
}

// 接続を閉じる
ftp_close($ftp);
?>

参考

  • ftp_rmdir() - ディレクトリを削除する


ディレクトリに存在するファイルの一覧を返す

  • ≪ ftp_mkdir
  • ftp_nb_continue ≫
  • PHP Manual
  • FTP 関数
  • ディレクトリに存在するファイルの一覧を返す

ftp_mlsd

(PHP 7 >= 7.2.0, PHP 8)

ftp_mlsd — ディレクトリに存在するファイルの一覧を返す

説明

ftp_mlsd(FTP\Connection $ftp, string $directory): array|false

パラメータ

ftp

FTP\Connection クラスのインスタンス

directory

ファイルの一覧を得るディレクトリ

戻り値

成功したときは、指定されたディレクトリに存在するファイル情報を配列で返します。 エラーのときは false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_mlsd() の例

<?php

// 基本的な接続のセットアップ
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログイン
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// 現在のディレクトリの内容を取得
$contents = ftp_mlsd($ftp, ".");

// $contents の中身を出力
var_dump($contents);

?>

上の例の出力は、 たとえば以下のようになります。

array(5) {
  [0]=>
  array(8) {
    ["name"]=>
    string(1) "."
    ["modify"]=>
    string(14) "20171212154511"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(4) "cdir"
    ["unique"]=>
    string(11) "811U5740002"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [1]=>
  array(8) {
    ["name"]=>
    string(2) ".."
    ["modify"]=>
    string(14) "20171212154511"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(4) "pdir"
    ["unique"]=>
    string(11) "811U5740002"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [2]=>
  array(8) {
    ["name"]=>
    string(11) "public_html"
    ["modify"]=>
    string(14) "20171211171525"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(3) "dir"
    ["unique"]=>
    string(11) "811U5740525"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [3]=>
  array(8) {
    ["name"]=>
    string(10) "public_ftp"
    ["modify"]=>
    string(14) "20171211174536"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(3) "dir"
    ["unique"]=>
    string(11) "811U57405EE"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
  [4]=>
  array(8) {
    ["name"]=>
    string(3) "www"
    ["modify"]=>
    string(14) "www"
    ["perm"]=>
    string(7) "flcdmpe"
    ["type"]=>
    string(3) "dir"
    ["unique"]=>
    string(11) "811U5740780"
    ["UNIX.group"]=>
    string(2) "33"
    ["UNIX.mode"]=>
    string(4) "0755"
    ["UNIX.owner"]=>
    string(2) "33"
  }
}

参考

  • ftp_rawlist() - 指定したディレクトリの詳細なファイル一覧を返す
  • ftp_nlist() - 指定したディレクトリのファイルの一覧を返す


ファイルの取得/送信を継続する（非ブロッキング）

  • ≪ ftp_mlsd
  • ftp_nb_fget ≫
  • PHP Manual
  • FTP 関数
  • ファイルの取得/送信を継続する（非ブロッキング）

ftp_nb_continue

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_continue — ファイルの取得/送信を継続する（非ブロッキング）

説明

ftp_nb_continue(FTP\Connection $ftp): int

非ブロッキングモードで、ファイルの取得/送信を継続します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

戻り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_nb_continue() の例

<?php

// ダウンロードを開始する
$ret = ftp_nb_get($ftp, "test", "README", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

// ダウンロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error downloading the file...";
exit(1);
}
?>


FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

  • ≪ ftp_nb_continue
  • ftp_nb_fput ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

ftp_nb_fget

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_fget — FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）

説明

ftp_nb_fget(
FTP\Connection $ftp,
resource $stream,
string $remote_filename,
int $mode = FTP_BINARY,
int $offset = 0
): int

ftp_nb_fget() は、FTP サーバーからリモートファイルを取得します。

ftp_fget() との違いは、この関数が 非同期処理でファイルを取得するということです。そのため、 ファイルをダウンロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP\Connection クラスのインスタンス

stream

オープンされているファイルのポインタ。ここにデータが保存されます。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

ダウンロードを開始する、リモートファイル内の位置。

戻り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_fget() の例

<?php

// ファイルをオープンする
$file = 'index.php';
$fp = fopen($file, 'w');

$ftp = ftp_connect($ftp_server);

$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// ダウンロードを開始する
$ret = ftp_nb_fget($ftp, $fp, $file, FTP_BINARY);
while ($ret == FTP_MOREDATA) {

// 何かお好みの動作を
echo ".";

// ダウンロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error downloading the file...";
exit(1);
}

// ファイルポインタを閉じる
fclose($fp);
?>

参考

  • ftp_nb_get() - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_get() - FTP サーバーからファイルをダウンロードする


オープン中のファイルを FTP サーバーに保存する（非ブロッキング）

  • ≪ ftp_nb_fget
  • ftp_nb_get ≫
  • PHP Manual
  • FTP 関数
  • オープン中のファイルを FTP サーバーに保存する（非ブロッキング）

ftp_nb_fput

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_fput — オープン中のファイルを FTP サーバーに保存する（非ブロッキング）

説明

ftp_nb_fput(
FTP\Connection $ftp,
string $remote_filename,
resource $stream,
int $mode = FTP_BINARY,
int $offset = 0
): int

ftp_nb_fput() は、ファイルポインタが指すデータを FTP サーバー上のリモートファイルへアップロードします。

ftp_fput() との違いは、この関数が 非同期処理でファイルをアップロードするということです。そのため、 ファイルをアップロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP\Connection クラスのインスタンス

remote_filename

リモートファイルのパス。

stream

ローカルでオープンされているファイルのポインタ。 ファイルの終端まで進むと読み込みが終了します。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

戻り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_fput() の例

<?php

$file = 'index.php';

$fp = fopen($file, 'r');

$ftp = ftp_connect($ftp_server);

$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// アップロードを開始する
$ret = ftp_nb_fput($ftp, $file, $fp, FTP_BINARY);
while ($ret == FTP_MOREDATA) {

// 何かお好みの動作を
echo ".";

// アップロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error uploading the file...";
exit(1);
}

fclose($fp);
?>

参考

  • ftp_nb_put() - FTP サーバーにファイルを保存する（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする


FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）

  • ≪ ftp_nb_fput
  • ftp_nb_put ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）

ftp_nb_get

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_get — FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）

説明

ftp_nb_get(
FTP\Connection $ftp,
string $local_filename,
string $remote_filename,
int $mode = FTP_BINARY,
int $offset = 0
): int|false

ftp_nb_get() は FTP サーバーからリモートファイルを取得し、 それをローカルファイルに保存します。

ftp_get() との違いは、この関数が 非同期処理でファイルを取得するということです。そのため、 ファイルをダウンロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP\Connection クラスのインスタンス

local_filename

ローカルファイルのパス（ファイルがすでに存在する場合、上書きされます）。

remote_filename

リモートファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

ダウンロードを開始する、リモートファイル内の位置。

戻り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。 ローカルファイルをオープンできなかった場合は、false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_get() の例

<?php

// ダウンロードを開始する
$ret = ftp_nb_get($ftp, "test", "README", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

// 何かお好みの動作を
echo ".";

// ダウンロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error downloading the file...";
exit(1);
}
?>

例2 ftp_nb_get() でダウンロードを再開する

<?php

// 開始
$ret = ftp_nb_get($ftp, "test", "README", FTP_BINARY,
filesize("test"));
// あるいは: $ret = ftp_nb_get($my_connection, "test", "README",
// FTP_BINARY, FTP_AUTORESUME);
while ($ret == FTP_MOREDATA) {

// 何かお好みの動作を
echo ".";

// ダウンロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error downloading the file...";
exit(1);
}
?>

例3 ftp_nb_get() を用い、ファイルの 100 バイト目以降から ダウンロードを再開する

<?php

// 自動シークを無効にする
ftp_set_option($ftp, FTP_AUTOSEEK, false);

// 開始
$ret = ftp_nb_get($ftp, "newfile", "README", FTP_BINARY, 100);
while ($ret == FTP_MOREDATA) {

/* ... */

// ダウンロードを継続する...
$ret = ftp_nb_continue($ftp);
}
?>

上の例では、newfile のサイズは FTP サーバー上の README より 100 バイト小さくなります。なぜなら ダウンロードの開始位置を 100 バイトずらしたからです。 もし FTP_AUTOSEEK を無効にしなければ、 newfile の最初の 100 バイトは '\0' で埋められます。

参考

  • ftp_nb_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_fget() - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
  • ftp_get() - FTP サーバーからファイルをダウンロードする


FTP サーバーにファイルを保存する（非ブロッキング）

  • ≪ ftp_nb_get
  • ftp_nlist ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーにファイルを保存する（非ブロッキング）

ftp_nb_put

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_nb_put — FTP サーバーにファイルを保存する（非ブロッキング）

説明

ftp_nb_put(
FTP\Connection $ftp,
string $remote_filename,
string $local_filename,
int $mode = FTP_BINARY,
int $offset = 0
): int|false

ftp_nb_put() はローカルファイルを FTP サーバーに保存します。

ftp_put() との違いは、この関数が 非同期処理でファイルをアップロードするということです。そのため、 ファイルをアップロードしている最中に別の処理を行うことができます。

パラメータ

ftp

FTP\Connection クラスのインスタンス

remote_filename

リモートファイルのパス。

local_filename

ローカルファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

戻り値

FTP_FAILED、FTP_FINISHED あるいは FTP_MOREDATA を返します。 ローカルファイルのオープンに失敗した場合、false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_nb_put() の例

<?php

// アップロードを開始する
$ret = ftp_nb_put($ftp, "test.remote", "test.local", FTP_BINARY);
while ($ret == FTP_MOREDATA) {

// 何かお好みの動作を
echo ".";

// アップロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error uploading the file...";
exit(1);
}
?>

例2 ftp_nb_put() でアップロードを再開する

<?php

// 開始
$ret = ftp_nb_put($ftp, "test.remote", "test.local",
FTP_BINARY, ftp_size("test.remote"));
// あるいは: $ret = ftp_nb_put($my_connection, "test.remote", "test.local",
// FTP_BINARY, FTP_AUTORESUME);

while ($ret == FTP_MOREDATA) {

// 何かお好みの動作を
echo ".";

// アップロードを継続する...
$ret = ftp_nb_continue($ftp);
}
if ($ret != FTP_FINISHED) {
echo "There was an error uploading the file...";
exit(1);
}
?>

参考

  • ftp_nb_fput() - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_continue() - ファイルの取得/送信を継続する（非ブロッキング）
  • ftp_put() - FTP サーバーにファイルをアップロードする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする


指定したディレクトリのファイルの一覧を返す

  • ≪ ftp_nb_put
  • ftp_pasv ≫
  • PHP Manual
  • FTP 関数
  • 指定したディレクトリのファイルの一覧を返す

ftp_nlist

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_nlist — 指定したディレクトリのファイルの一覧を返す

説明

ftp_nlist(FTP\Connection $ftp, string $directory): array|false

パラメータ

ftp

FTP\Connection クラスのインスタンス

directory

一覧を表示するディレクトリ。このパラメータには引数を含めることができます。 例: ftp_nlist($ftp, "-la /your/dir"); このパラメータはエスケープ処理されません。スペースやその他の文字を含む ファイル名では問題が発生する可能性があることに注意してください。

戻り値

成功した場合は指定したディレクトリ内のファイル名の配列を、 エラー時には false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_nlist() の例

<?php

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// カレントディレクトリの内容を得る
$contents = ftp_nlist($ftp, ".");

// $contents を出力する
var_dump($contents);

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(11) "public_html"
  [1]=>
  string(10) "public_ftp"
  [2]=>
  string(3) "www"

参考

  • ftp_rawlist() - 指定したディレクトリの詳細なファイル一覧を返す
  • ftp_mlsd() - ディレクトリに存在するファイルの一覧を返す


パッシブモードをオンまたはオフにする

  • ≪ ftp_nlist
  • ftp_put ≫
  • PHP Manual
  • FTP 関数
  • パッシブモードをオンまたはオフにする

ftp_pasv

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_pasv — パッシブモードをオンまたはオフにする

説明

ftp_pasv(FTP\Connection $ftp, bool $enable): bool

ftp_pasv() はパッシブモードをオンまたはオフにします。 パッシブモードでは、データ接続はサーバーではなくクライアントにより 初期化されます。クライアントがファイアウォールの向こうにある場合に 必要となるでしょう。

ftp_pasv() をコールできるのは、 ログインに成功した後だけであることに注意しましょう。 それ以外の場合は、この関数のコールは失敗します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

enable

true, の場合はパッシブモードをオンに、そうでない場合はオフにします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_pasv() の例

<?php
$file = 'somefile.txt';
$remote_file = 'readme.txt';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// パッシブモードをオンにする
ftp_pasv($ftp, true);

// ファイルをアップロードする
if (ftp_put($ftp, $remote_file, $file, FTP_ASCII)) {
echo "successfully uploaded $file\n";
} else {
echo "There was a problem while uploading $file\n";
}

// 接続を閉じる
ftp_close($ftp);
?>


FTP サーバーにファイルをアップロードする

  • ≪ ftp_pasv
  • ftp_pwd ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーにファイルをアップロードする

ftp_put

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_put — FTP サーバーにファイルをアップロードする

説明

ftp_put(
FTP\Connection $ftp,
string $remote_filename,
string $local_filename,
int $mode = FTP_BINARY,
int $offset = 0
): bool

ftp_put() ローカルファイルを FTP サーバーに保存します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

remote_filename

リモートファイルのパス。

local_filename

ローカルファイルのパス。

mode

転送モード。FTP_ASCII または FTP_BINARY のどちらかを指定する必要があります。

offset

リモートファイル内での、アップロード開始位置。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。
7.3.0 | mode パラメータはオプションになりました。 これより前のバージョンでは、このパラメータは必須でした。

例

例1 ftp_put() の例

<?php
$file = 'somefile.txt';
$remote_file = 'readme.txt';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// ファイルをアップロードする
if (ftp_put($ftp, $remote_file, $file, FTP_ASCII)) {
echo "successfully uploaded $file\n";
} else {
echo "There was a problem while uploading $file\n";
}

// 接続を閉じる
ftp_close($ftp);
?>

参考

  • ftp_pasv() - パッシブモードをオンまたはオフにする
  • ftp_fput() - オープン中のファイルを FTP サーバーにアップロードする
  • ftp_nb_fput() - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
  • ftp_nb_put() - FTP サーバーにファイルを保存する（非ブロッキング）


カレントのディレクトリ名を返す

  • ≪ ftp_put
  • ftp_quit ≫
  • PHP Manual
  • FTP 関数
  • カレントのディレクトリ名を返す

ftp_pwd

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_pwd — カレントのディレクトリ名を返す

説明

ftp_pwd(FTP\Connection $ftp): string|false

パラメータ

ftp

FTP\Connection クラスのインスタンス

戻り値

カレントのディレクトリ名、またはエラー時には false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_pwd() の例

<?php

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// public_html ディレクトリに移動する
ftp_chdir($ftp, 'public_html');

// カレントのディレクトリ名を表示する
echo ftp_pwd($ftp); // /public_html

// 接続を閉じる
ftp_close($ftp);
?>

参考

  • ftp_chdir() - FTP サーバー上でディレクトリを移動する
  • ftp_cdup() - 親ディレクトリに移動する


ftp_close のエイリアス

  • ≪ ftp_pwd
  • ftp_raw ≫
  • PHP Manual
  • FTP 関数
  • ftp_close のエイリアス

ftp_quit

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_quit — ftp_close() のエイリアス

説明

この関数は次の関数のエイリアスです。 ftp_close().


FTP サーバーに任意のコマンドを送信する

  • ≪ ftp_quit
  • ftp_rawlist ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバーに任意のコマンドを送信する

ftp_raw

(PHP 5, PHP 7, PHP 8)

ftp_raw — FTP サーバーに任意のコマンドを送信する

説明

ftp_raw(FTP\Connection $ftp, string $command): ?array

任意の command を FTP サーバーに送信します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

command

実行したいコマンド。

戻り値

サーバーからの応答を文字列の配列で返します。 失敗した場合は null を返します。 結果の文字列に対して、何の処理も行いません。また、 ftp_raw() はそのコマンドが成功したのかどうかを 判断できません。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_raw() を用いて FTP サーバーに手動でログインする

<?php
$ftp = ftp_connect("ftp.example.com");

/* ftp_login($ftp, "joeblow", "secret");
を実行するのと同じ意味 */
ftp_raw($ftp, "USER joeblow");
ftp_raw($ftp, "PASS secret");
?>

参考

  • ftp_exec() - FTP サーバー上でのコマンドの実行をリクエストする


指定したディレクトリの詳細なファイル一覧を返す

  • ≪ ftp_raw
  • ftp_rename ≫
  • PHP Manual
  • FTP 関数
  • 指定したディレクトリの詳細なファイル一覧を返す

ftp_rawlist

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_rawlist — 指定したディレクトリの詳細なファイル一覧を返す

説明

ftp_rawlist(FTP\Connection $ftp, string $directory, bool $recursive = false): array|false

ftp_rawlist() は、FTP LIST コマンドを実行し、結果を配列として返します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

directory

ディレクトリのパス。 LIST コマンドの引数を含むこともあります。

recursive

true を設定した場合、発行されるコマンドは LIST -R となります。

戻り値

各要素が 1 行分のテキストに対応する配列を返します。 渡された directory が無効な場合は false を返します。

出力に関する処理は全く行われません。結果の解釈の仕方を定義するために ftp_systype() から返されるシステム型 ID を使用することができます。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_rawlist() の例

<?php

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// / のファイル一覧を得る
$buff = ftp_rawlist($ftp, '/');

// 接続を閉じる
ftp_close($ftp);

// バッファの内容を出力する
var_dump($buff);
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(65) "drwxr-x---   3 vincent  vincent      4096 Jul 12 12:16 public_ftp"
  [1]=>
  string(66) "drwxr-x---  15 vincent  vincent      4096 Nov  3 21:31 public_html"
  [2]=>
  string(73) "lrwxrwxrwx   1 vincent  vincent        11 Jul 12 12:16 www -> public_html"
}

参考

  • ftp_nlist() - 指定したディレクトリのファイルの一覧を返す
  • ftp_mlsd() - ディレクトリに存在するファイルの一覧を返す


FTP サーバー上のファイルまたはディレクトリの名前を変更する

  • ≪ ftp_rawlist
  • ftp_rmdir ≫
  • PHP Manual
  • FTP 関数
  • FTP サーバー上のファイルまたはディレクトリの名前を変更する

ftp_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_rename — FTP サーバー上のファイルまたはディレクトリの名前を変更する

説明

ftp_rename(FTP\Connection $ftp, string $from, string $to): bool

ftp_rename() は FTP サーバー上のファイルやディレクトリの 名前を変更します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

from

現在のファイル/ディレクトリの名前。

to

新しい名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。 失敗したとき(存在しないファイルを変更しようとしたときなど) は、 E_WARNING レベルのエラーが発生します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_rename() の例

<?php
$old_file = 'somefile.txt.bak';
$new_file = 'somefile.txt';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $old_file を $new_file に変更することを試みる
if (ftp_rename($ftp, $old_file, $new_file)) {
echo "Successfully renamed $old_file to $new_file\n";
} else {
echo "There was a problem while renaming $old_file to $new_file\n";
}

// 接続を閉じる
ftp_close($ftp);
?>


ディレクトリを削除する

  • ≪ ftp_rename
  • ftp_set_option ≫
  • PHP Manual
  • FTP 関数
  • ディレクトリを削除する

ftp_rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_rmdir — ディレクトリを削除する

説明

ftp_rmdir(FTP\Connection $ftp, string $directory): bool

FTP サーバー上の、指定した directory を削除します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

directory

削除するディレクトリ。空のディレクトリへの絶対パス または相対パスでなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_rmdir() の例

<?php

$dir = 'www/';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $dir ディレクトリの削除を試みる
if (ftp_rmdir($ftp, $dir)) {
echo "Successfully deleted $dir\n";
} else {
echo "There was a problem while deleting $dir\n";
}

ftp_close($ftp);

?>

参考

  • ftp_mkdir() - ディレクトリを作成する


さまざまな FTP 実行時オプションを設定する

  • ≪ ftp_rmdir
  • ftp_site ≫
  • PHP Manual
  • FTP 関数
  • さまざまな FTP 実行時オプションを設定する

ftp_set_option

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ftp_set_option — さまざまな FTP 実行時オプションを設定する

説明

ftp_set_option(FTP\Connection $ftp, int $option, int|bool $value): bool

この関数は、指定した FTP 接続に関してのさまざまな実行時オプションを 制御します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

option

現在、以下のオプションがサポートされています:

サポートされる実行時 FTP オプション
FTP_TIMEOUT_SEC | 全てのネットワーク関連関数に関して秒単位でタイムアウトを変更 します。valueは、 0 より大きい整数値である必要があります。 デフォルトのタイムアウトは90秒です。
FTP_AUTOSEEK | 有効になっている場合は、GET や PUT のリクエストが resumepos や startpos のパラメータ付きで実行されるとファイル中の該当位置をシークします。 デフォルトで有効になっています。
FTP_USEPASVADDRESS | このオプションを無効にすると、PHP は PASV コマンドからのレスポンスとして FTPサーバーから返されたIPアドレスを無視します。 代わりに、ftp_connect() で与えられた IPアドレスを使います。 value は、bool でなければなりません。

value

このパラメータの内容は、どの option を変更しようとしているかによって変わります。

戻り値

オプションが設定できた場合に true 、そうでない場合に false を返します。 option がサポートされていなかった場合や option が想定していない値を value に渡した場合は警告メッセージが発生します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_set_option() の例

<?php
// ネットワークのタイムアウトを 10 秒に設定する
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 10);
?>

参考

  • ftp_get_option() - カレントの FTP 接続での種々の実行時動作を取得する


SITEコマンドをサーバーに送信する

  • ≪ ftp_set_option
  • ftp_size ≫
  • PHP Manual
  • FTP 関数
  • SITEコマンドをサーバーに送信する

ftp_site

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_site — SITEコマンドをサーバーに送信する

説明

ftp_site(FTP\Connection $ftp, string $command): bool

ftp_site() は、指定された SITE コマンドを FTP サーバーに送信します。

SITE コマンドの規格は統一されていないため、 サーバーにより仕様が異なります．ファイルのパーミッションや グループメンバーの設定のような処理を行う際には有用です。

パラメータ

ftp

FTP\Connection クラスのインスタンス

command

SITE コマンド。このパラメータはエスケープされないので、スペースや その他の文字を含むファイル名は問題を引き起こす可能性があることに 注意してください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 SITE コマンドを FTP サーバーに送信する

<?php
// FTP サーバーに接続する
$ftp = ftp_connect('ftp.example.com');
if (!$ftp) die('Unable to connect to ftp.example.com');

// "user" として、パスワード "pass" でログインする
if (!ftp_login($ftp, 'user', 'pass')) die('Error logging into ftp.example.com');

// FTP サーバーに "SITE CHMOD 0600 /home/user/privatefile" コマンドを発行する
if (ftp_site($ftp, 'CHMOD 0600 /home/user/privatefile')) {
echo "Command executed successfully.\n";
} else {
die('Command failed.');
}
?>

参考

  • ftp_raw() - FTP サーバーに任意のコマンドを送信する


指定したファイルのサイズを返す

  • ≪ ftp_site
  • ftp_ssl_connect ≫
  • PHP Manual
  • FTP 関数
  • 指定したファイルのサイズを返す

ftp_size

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_size — 指定したファイルのサイズを返す

説明

ftp_size(FTP\Connection $ftp, string $filename): int

ftp_size() は指定されたファイルのサイズを バイト数で返します。

注意:

すべてのサーバーがこの機能をサポートしているわけではありません。

パラメータ

ftp

FTP\Connection クラスのインスタンス

filename

リモートファイル。

戻り値

成功した場合はファイルのサイズを、エラー時には -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_size() の例

<?php

$file = 'somefile.txt';

// 接続を確立する
$ftp = ftp_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

// $file のサイズを取得する
$res = ftp_size($ftp, $file);

if ($res != -1) {
echo "size of $file is $res bytes";
} else {
echo "couldn't get the size";
}

// 接続を閉じる
ftp_close($ftp);

?>

参考

  • ftp_rawlist() - 指定したディレクトリの詳細なファイル一覧を返す


セキュアな SSL-FTP 接続をオープンする

  • ≪ ftp_size
  • ftp_systype ≫
  • PHP Manual
  • FTP 関数
  • セキュアな SSL-FTP 接続をオープンする

ftp_ssl_connect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ftp_ssl_connect — セキュアな SSL-FTP 接続をオープンする

説明

ftp_ssl_connect(string $hostname, int $port = 21, int $timeout = 90): FTP\Connection|false

ftp_ssl_connect() は、指定した hostname への明示的な SSL-FTP 接続をオープンします。 サーバー側が SSL-FTP 接続に対応していなかったり、証明書が無効であったりした場合でも、 ftp_ssl_connect() は成功します。 そういった場合は、ftp_login() を呼んで AUTH FTP コマンドを送信した時点ではじめて、 ftp_login() が失敗することになります。

注意: この関数が存在しないことがあるのはなぜですか？

PHP 7.0.0 より前のバージョンでは、 ftp_ssl_connect() が使えるのは ftp拡張モジュールと OpenSSL が静的に PHP に組み込まれている場合だけでした。 つまり、Windows 版の PHP 公式ビルドではこの関数は使えなかったということです。 この関数を Windows で使いたい場合は、PHP バイナリを自分でコンパイルしなければなりませんでした。

注意:

ftp_ssl_connect() は、sFTP で使うための関数ではありません。 PHP で sFTP を使うには ssh2_sftp() を参照ください。

パラメータ

hostname

FTP サーバーのアドレス。このパラメータには、最後のスラッシュや 先頭の ftp:// をつけてはいけません。

port

port パラメータは別のポートに接続することを 指定します。これを省略するか 0 にした場合、デフォルトの FTP ポート、 つまり 21 が使用されます。

timeout

このパラメータは、以降の全てのネットワーク処理の タイムアウトを指定します。省略された場合の デフォルト値は、90 秒となります。timeout は、 ftp_set_option() および ftp_get_option() でいつでも変更および取得可能です。

戻り値

成功した場合に FTP\Connection クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | FTP\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。

例

例1 ftp_ssl_connect() の例

<?php

// SSL 接続を確立する
$ftp = ftp_ssl_connect($ftp_server);

// ユーザー名とパスワードでログインする
$login_result = ftp_login($ftp, $ftp_user_name, $ftp_user_pass);

if (!$login_result) {
// この場合は、すでに PHP 側で E_WARNING レベルのメッセージを発行しています。
die("can't login");
}

echo ftp_pwd($ftp);

// SSL 接続を閉じる
ftp_close($ftp);
?>

参考

  • ftp_connect() - FTP 接続をオープンする


リモート FTP サーバーのシステム型 ID を返す

  • ≪ ftp_ssl_connect
  • FTP\Connection ≫
  • PHP Manual
  • FTP 関数
  • リモート FTP サーバーのシステム型 ID を返す

ftp_systype

(PHP 4, PHP 5, PHP 7, PHP 8)

ftp_systype — リモート FTP サーバーのシステム型 ID を返す

説明

ftp_systype(FTP\Connection $ftp): string|false

リモート FTP サーバーのシステム型 ID を返します。

パラメータ

ftp

FTP\Connection クラスのインスタンス

戻り値

リモートシステム型を返します。エラー時には false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ftp は、FTP\Connection のインスタンスを期待するようになりました。 これより前のバージョンでは、リソース を期待していました。

例

例1 ftp_systype() の例

<?php

// 接続を確立する
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'user', 'password');

// システム型を取得する
if ($type = ftp_systype($ftp)) {
echo "Example.com is powered by $type\n";
} else {
echo "Couldn't get the systype";
}

?>

上の例の出力は、 たとえば以下のようになります。

Example.com is powered by UNIX


FTP\Connection クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、 ftp リソースを置き換える、完全不定形クラスです。

クラス概要

final class FTP\Connection {
}


Gearman

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
    • Basic usage
    • Basic Gearman client and worker, background
    • Basic Gearman client and worker, submitting tasks
  • GearmanClient — The GearmanClient class
    • GearmanClient::addOptions — Add client options
    • GearmanClient::addServer — Add a job server to the client
    • GearmanClient::addServers — Add a list of job servers to the client
    • GearmanClient::addTask — Add a task to be run in parallel
    • GearmanClient::addTaskBackground — Add a background task to be run in parallel
    • GearmanClient::addTaskHigh — Add a high priority task to run in parallel
    • GearmanClient::addTaskHighBackground — Add a high priority background task to be run in parallel
    • GearmanClient::addTaskLow — Add a low priority task to run in parallel
    • GearmanClient::addTaskLowBackground — Add a low priority background task to be run in parallel
    • GearmanClient::addTaskStatus — Add a task to get status
    • GearmanClient::clearCallbacks — Clear all task callback functions
    • GearmanClient::clone — Create a copy of a GearmanClient object
    • GearmanClient::__construct — Create a GearmanClient instance
    • GearmanClient::context — Get the application context
    • GearmanClient::data — Get the application data (deprecated)
    • GearmanClient::do — Run a single task and return a result [deprecated]
    • GearmanClient::doBackground — Run a task in the background
    • GearmanClient::doHigh — Run a single high priority task
    • GearmanClient::doHighBackground — Run a high priority task in the background
    • GearmanClient::doJobHandle — Get the job handle for the running task
    • GearmanClient::doLow — Run a single low priority task
    • GearmanClient::doLowBackground — Run a low priority task in the background
    • GearmanClient::doNormal — Run a single task and return a result
    • GearmanClient::doStatus — Get the status for the running task
    • GearmanClient::echo — Send data to all job servers to see if they echo it back [deprecated]
    • GearmanClient::error — Returns an error string for the last error encountered
    • GearmanClient::getErrno — Get an errno value
    • GearmanClient::jobStatus — Get the status of a background job
    • GearmanClient::ping — Send data to all job servers to see if they echo it back
    • GearmanClient::removeOptions — Remove client options
    • GearmanClient::returnCode — Get the last Gearman return code
    • GearmanClient::runTasks — Run a list of tasks in parallel
    • GearmanClient::setClientCallback — Callback function when there is a data packet for a task (deprecated)
    • GearmanClient::setCompleteCallback — Set a function to be called on task completion
    • GearmanClient::setContext — Set application context
    • GearmanClient::setCreatedCallback — Set a callback for when a task is queued
    • GearmanClient::setData — Set application data (deprecated)
    • GearmanClient::setDataCallback — Callback function when there is a data packet for a task
    • GearmanClient::setExceptionCallback — Set a callback for worker exceptions
    • GearmanClient::setFailCallback — Set callback for job failure
    • GearmanClient::setOptions — Set client options
    • GearmanClient::setStatusCallback — Set a callback for collecting task status
    • GearmanClient::setTimeout — Set socket I/O activity timeout
    • GearmanClient::setWarningCallback — Set a callback for worker warnings
    • GearmanClient::setWorkloadCallback — Set a callback for accepting incremental data updates
    • GearmanClient::timeout — Get current socket I/O activity timeout value
    • GearmanClient::wait — Wait for I/O activity on all connections in a client
  • GearmanJob — The GearmanJob class
    • GearmanJob::complete — Send the result and complete status (deprecated)
    • GearmanJob::__construct — Create a GearmanJob instance
    • GearmanJob::data — Send data for a running job (deprecated)
    • GearmanJob::exception — Send exception for running job (deprecated)
    • GearmanJob::fail — Send fail status (deprecated)
    • GearmanJob::functionName — Get function name
    • GearmanJob::handle — Get the job handle
    • GearmanJob::returnCode — Get last return code
    • GearmanJob::sendComplete — Send the result and complete status
    • GearmanJob::sendData — Send data for a running job
    • GearmanJob::sendException — Send exception for running job (exception)
    • GearmanJob::sendFail — Send fail status
    • GearmanJob::sendStatus — Send status
    • GearmanJob::sendWarning — Send a warning
    • GearmanJob::setReturn — Set a return value
    • GearmanJob::status — Send status (deprecated)
    • GearmanJob::unique — Get the unique identifier
    • GearmanJob::warning — Send a warning (deprecated)
    • GearmanJob::workload — Get workload
    • GearmanJob::workloadSize — Get size of work load
  • GearmanTask — The GearmanTask class
    • GearmanTask::__construct — Create a GearmanTask instance
    • GearmanTask::create — Create a task (deprecated)
    • GearmanTask::data — Get data returned for a task
    • GearmanTask::dataSize — Get the size of returned data
    • GearmanTask::function — Get associated function name (deprecated)
    • GearmanTask::functionName — Get associated function name
    • GearmanTask::isKnown — Determine if task is known
    • GearmanTask::isRunning — Test whether the task is currently running
    • GearmanTask::jobHandle — Get the job handle
    • GearmanTask::recvData — Read work or result data into a buffer for a task
    • GearmanTask::returnCode — Get the last return code
    • GearmanTask::sendData — Send data for a task (deprecated)
    • GearmanTask::sendWorkload — Send data for a task
    • GearmanTask::taskDenominator — Get completion percentage denominator
    • GearmanTask::taskNumerator — Get completion percentage numerator
    • GearmanTask::unique — Get the unique identifier for a task
    • GearmanTask::uuid — Get the unique identifier for a task (deprecated)
  • GearmanWorker — The GearmanWorker class
    • GearmanWorker::addFunction — Register and add callback function
    • GearmanWorker::addOptions — Add worker options
    • GearmanWorker::addServer — Add a job server
    • GearmanWorker::addServers — Add job servers
    • GearmanWorker::clone — Create a copy of the worker
    • GearmanWorker::__construct — Create a GearmanWorker instance
    • GearmanWorker::echo — Test job server response
    • GearmanWorker::error — Get the last error encountered
    • GearmanWorker::getErrno — Get errno
    • GearmanWorker::options — Get worker options
    • GearmanWorker::register — Register a function with the job server
    • GearmanWorker::removeOptions — Remove worker options
    • GearmanWorker::returnCode — Get last Gearman return code
    • GearmanWorker::setId — Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers
    • GearmanWorker::setOptions — Set worker options
    • GearmanWorker::setTimeout — Set socket I/O activity timeout
    • GearmanWorker::timeout — Get socket I/O activity timeout
    • GearmanWorker::unregister — Unregister a function name with the job servers
    • GearmanWorker::unregisterAll — Unregister all function names with the job servers
    • GearmanWorker::wait — Wait for activity from one of the job servers
    • GearmanWorker::work — Wait for and perform jobs
  • GearmanException — The GearmanException class


はじめに

» Gearman は、複数のマシンやプロセスに 作業を任せるための汎用的なアプリケーションフレームワークです。これにより、 アプリケーションはタスクを並列で遂行したり、処理の負荷を分散したり、 言語をまたいで関数を呼び出したりできます。このフレームワークは、可用性の高い Webサイトから、データベースのレプリケーションイベントの転送処理まで、 さまざまなアプリケーションで使用できます。

この拡張モジュールは、Gearman のクライアントとワーカーを書くためのクラスを提供します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Gearman
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

This extension requires the » libgearman, » libevent and » uuid libraries, and a running Gearman server.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gearman


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Return values. Always check GearmanClient::error() or GearmanWorker() for a string error, as it may contain more details:

GEARMAN_SUCCESS (int)
Whatever action was taken was successful.
GEARMAN_IO_WAIT (int)
When in non-blocking mode, an event is hit that would have blocked.
GEARMAN_ERRNO (int)
A system error. Check GearmanClient::errno() or GearmanWorker::errno() for the system error code that was returned.
GEARMAN_NO_ACTIVE_FDS (int)
GearmanClient::wait() or GearmanWorker() was called with no connections.
GEARMAN_UNEXPECTED_PACKET (int)
Indicates something going very wrong in gearmand. Applies only to GearmanWorker.
GEARMAN_GETADDRINFO (int)
DNS resolution failed (invalid host, port, etc).
GEARMAN_NO_SERVERS (int)
Did not call GearmanClient::addServer() before submitting jobs or tasks.
GEARMAN_LOST_CONNECTION (int)
Lost a connection during a request.
GEARMAN_MEMORY_ALLOCATION_FAILURE (int)
Memory allocation failed (ran out of memory).
GEARMAN_SERVER_ERROR (int)
Something went wrong in the Gearman server and it could not handle the request gracefully.
GEARMAN_WORK_DATA (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Sent to update the client with data from a running job. A worker uses this when it needs to send updates, send partial results, or flush data during long running jobs.
GEARMAN_WORK_WARNING (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Updates the client with a warning. The behavior is just like GEARMAN_WORK_DATA, but should be treated as a warning instead of normal response data.
GEARMAN_WORK_STATUS (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Sent to update the status of a long running job. Use GearmanClient::doStatus() to obtain the percentage complete of the task.
GEARMAN_WORK_EXCEPTION (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Indicates that a job failed with a given exception.
GEARMAN_WORK_FAIL (int)
Notice return code obtained with GearmanClient::returnCode() when using GearmanClient::do(). Indicates that the job failed.
GEARMAN_COULD_NOT_CONNECT (int)
Failed to connect to servers.
GEARMAN_INVALID_FUNCTION_NAME (int)
Trying to register a function name of NULL or using the callback interface without specifying callbacks.
GEARMAN_INVALID_WORKER_FUNCTION (int)
Trying to register a function with a NULL callback function.
GEARMAN_NO_REGISTERED_FUNCTIONS (int)
When a worker gets a job for a function it did not register.
GEARMAN_NO_JOBS (int)
For a non-blocking worker, when GearmanWorker::work() does not have any active jobs.
GEARMAN_ECHO_DATA_CORRUPTION (int)
After GearmanClient::echo() or GearmanWorker::echo() the data returned doesn't match the data sent.
GEARMAN_NEED_WORKLOAD_FN (int)
When the client opted to stream the workload of a task, but did not specify a workload callback function.
GEARMAN_PAUSE (int)
For the non-blocking client task interface, can be returned from the task callback to "pause" the call and return from GearmanClient::runTasks(). Call GearmanClient::runTasks() again to continue.
GEARMAN_UNKNOWN_STATE (int)
Internal client/worker state error.
GEARMAN_SEND_BUFFER_TOO_SMALL (int)
Internal error: trying to flush more data in one atomic chunk than is possible due to hard-coded buffer sizes.
GEARMAN_TIMEOUT (int)
Hit the timeout limit set by the client/worker.

GearmanClient options:

GEARMAN_CLIENT_GENERATE_UNIQUE (int)
Generate a unique id (UUID) for each task.
GEARMAN_CLIENT_NON_BLOCKING (int)
Run the cient in a non-blocking mode.
GEARMAN_CLIENT_UNBUFFERED_RESULT (int)
Allow the client to read data in chunks rather than have the library buffer the entire data result and pass that back.
GEARMAN_CLIENT_FREE_TASKS (int)
Automatically free task objects once they are complete. This is the default setting in this extension to prevent memory leaks.

GearmanWorker options:

GEARMAN_WORKER_NON_BLOCKING (int)
Run the worker in non-blocking mode.
GEARMAN_WORKER_GRAB_UNIQ (int)
Return the client assigned unique ID in addition to the job handle.

Base Gearman configuration:

GEARMAN_DEFAULT_TCP_HOST (string)
GEARMAN_DEFAULT_TCP_PORT (int)
GEARMAN_DEFAULT_SOCKET_TIMEOUT (int)
GEARMAN_DEFAULT_SOCKET_SEND_SIZE (int)
GEARMAN_DEFAULT_SOCKET_RECV_SIZE (int)
GEARMAN_MAX_ERROR_SIZE (int)
GEARMAN_PACKET_HEADER_SIZE (int)
GEARMAN_JOB_HANDLE_SIZE (int)
GEARMAN_OPTION_SIZE (int)
GEARMAN_UNIQUE_SIZE (int)
GEARMAN_MAX_COMMAND_ARGS (int)
GEARMAN_ARGS_BUFFER_SIZE (int)
GEARMAN_SEND_BUFFER_SIZE (int)
GEARMAN_RECV_BUFFER_SIZE (int)
GEARMAN_WORKER_WAIT_TIMEOUT (int)


例

目次

  • Basic usage
  • Basic Gearman client and worker, background
  • Basic Gearman client and worker, submitting tasks


Basic usage

例1 Basic Gearman client and worker

This example shows a very simple client and worker. The client sends a string to the job server, and the worker reverses the string and sends it back. The job is performed synchronously.

<?php

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
$result = $gmclient->doNormal("reverse", "Hello!");

# Check for various return packets and errors.
switch($gmclient->returnCode())
{
case GEARMAN_WORK_DATA:
echo "Data: $result\n";
break;
case GEARMAN_WORK_STATUS:
list($numerator, $denominator)= $gmclient->doStatus();
echo "Status: $numerator/$denominator complete\n";
break;
case GEARMAN_WORK_FAIL:
echo "Failed\n";
exit;
case GEARMAN_SUCCESS:
echo "Success: $result\n";
break;
default:
echo "RET: " . $gmclient->returnCode() . "\n";
exit;
}
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
echo "Received job: " . $job->handle() . "\n";

$workload = $job->workload();
$workload_size = $job->workloadSize();

echo "Workload: $workload ($workload_size)\n";

# This status loop is not needed, just showing how it works
for ($x= 0; $x < $workload_size; $x++)
{
echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
$job->sendStatus($x, $workload_size);
sleep(1);
}

$result= strrev($workload);
echo "Result: $result\n";

# Return what we want to send back to the client.
return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

% php reverse_worker.php
Starting
Waiting for job...
Received job: H:foo.local:36
Workload: Hello! (6)
Sending status: 1/6 complete
Sending status: 2/6 complete
Sending status: 3/6 complete
Sending status: 4/6 complete
Sending status: 5/6 complete
Sending status: 6/6 complete
Result: !olleH

% php reverse_client.php
Starting
Sending job
Status: 1/6 complete
Status: 2/6 complete
Status: 3/6 complete
Status: 4/6 complete
Status: 5/6 complete
Status: 6/6 complete
Success: !olleH


Basic Gearman client and worker, background

例1 Basic Gearman client and worker, background

This example shows a very simple client and worker. The client sends a string to the job server as a background job, and the worker reverses the string. Note that since the work is performed asynchronously, the client does not wait for the job to complete and exits (and hence the client never receives the results).

<?php

# create our client object
$gmclient= new GearmanClient();

# add the default server (localhost)
$gmclient->addServer();

# run reverse client in the background
$job_handle = $gmclient->doBackground("reverse", "this is a test");

if ($gmclient->returnCode() != GEARMAN_SUCCESS)
{
echo "bad return code\n";
exit;
}

echo "done!\n";

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
echo "Received job: " . $job->handle() . "\n";

$workload = $job->workload();
$workload_size = $job->workloadSize();

echo "Workload: $workload ($workload_size)\n";

# This status loop is not needed, just showing how it works
for ($x= 0; $x < $workload_size; $x++)
{
echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
$job->sendStatus($x, $workload_size);
sleep(1);
}

$result= strrev($workload);
echo "Result: $result\n";

# Return what we want to send back to the client.
return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

% php reverse_worker.php
Starting
Waiting for job...
Received job: H:foo.local:41
Workload: this is a test (14)
1/14 complete
2/14 complete
3/14 complete
4/14 complete
5/14 complete
6/14 complete
7/14 complete
8/14 complete
9/14 complete
10/14 complete
11/14 complete
12/14 complete
13/14 complete
14/14 complete
Result: tset a si siht

% php reverse_client_bg.php
done!


Basic Gearman client and worker, submitting tasks

例1 Basic Gearman client and worker, submitting tasks

In this example, the basic reverse client extended to run two tasks in parallel. The reverse worker is unchanged except to add sending of data back during processing.

<?php

# create the gearman client
$gmc= new GearmanClient();

# add the default server (localhost)
$gmc->addServer();

# register some callbacks
$gmc->setCreatedCallback("reverse_created");
$gmc->setDataCallback("reverse_data");
$gmc->setStatusCallback("reverse_status");
$gmc->setCompleteCallback("reverse_complete");
$gmc->setFailCallback("reverse_fail");

# set some arbitrary application data
$data['foo'] = 'bar';

# add two tasks
$task= $gmc->addTask("reverse", "foo", $data);
$task2= $gmc->addTaskLow("reverse", "bar", NULL);

# run the tasks in parallel (assuming multiple workers)
if (! $gmc->runTasks())
{
echo "ERROR " . $gmc->error() . "\n";
exit;
}

echo "DONE\n";

function reverse_created($task)
{
echo "CREATED: " . $task->jobHandle() . "\n";
}

function reverse_status($task)
{
echo "STATUS: " . $task->jobHandle() . " - " . $task->taskNumerator() .
"/" . $task->taskDenominator() . "\n";
}

function reverse_complete($task)
{
echo "COMPLETE: " . $task->jobHandle() . ", " . $task->data() . "\n";
}

function reverse_fail($task)
{
echo "FAILED: " . $task->jobHandle() . "\n";
}

function reverse_data($task)
{
echo "DATA: " . $task->data() . "\n";
}

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
echo "Received job: " . $job->handle() . "\n";

$workload = $job->workload();
$workload_size = $job->workloadSize();

echo "Workload: $workload ($workload_size)\n";

# This status loop is not needed, just showing how it works
for ($x= 0; $x < $workload_size; $x++)
{
echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
$job->sendStatus($x+1, $workload_size);
$job->sendData(substr($workload, $x, 1));
sleep(1);
}

$result= strrev($workload);
echo "Result: $result\n";

# Return what we want to send back to the client.
return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

% php reverse_worker.php
Starting
Waiting for job...
Received job: H:foo.local:45
Workload: foo (3)
1/3 complete
2/3 complete
3/3 complete
Result: oof
Received job: H:foo.local:44
Workload: bar (3)
1/3 complete
2/3 complete
3/3 complete
Result: rab

% php reverse_client_task.php
CREATED: H:foo.local:44
CREATED: H:foo.local:45
STATUS: H:foo.local:45 - 1/3
DATA: f
STATUS: H:foo.local:45 - 2/3
DATA: o
STATUS: H:foo.local:45 - 3/3
DATA: o
COMPLETE: H:foo.local:45, oof
STATUS: H:foo.local:44 - 1/3
DATA: b
STATUS: H:foo.local:44 - 2/3
DATA: a
STATUS: H:foo.local:44 - 3/3
DATA: r
COMPLETE: H:foo.local:44, rab
DONE


The GearmanClient class

(PECL gearman >= 0.5.0)

はじめに

Represents a class for connecting to a Gearman job server and making requests to perform some function on provided data. The function performed must be one registered by a Gearman worker and the data passed is opaque to the job server.

クラス概要

class GearmanClient {
/* メソッド */
public __construct()
public addOptions(int $option): bool
public addServer(string $host = null, int $port = 0, bool $setupExceptionHandler = true): bool
public addServers(string $servers = null, bool $setupExceptionHandler = true): bool
public addTask(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false
public addTaskBackground(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false
public addTaskHigh(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false
public addTaskHighBackground(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false
public addTaskLow(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false
public addTaskLowBackground(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false
public addTaskStatus(string $job_handle, mixed $context = null): GearmanTask|false
public clearCallbacks(): bool
public context(): string
public doBackground(string $function, string $workload, ?string $unique = null): string
public doHigh(string $function, string $workload, ?string $unique = null): string
public doHighBackground(string $function, string $workload, ?string $unique = null): string
public doJobHandle(): string
public doLow(string $function, string $workload, ?string $unique = null): string
public doLowBackground(string $function, string $workload, ?string $unique = null): string
public doNormal(string $function, string $workload, ?string $unique = null): string
public doStatus(): array
public error(): string|false
public getErrno(): int
public jobStatus(string $job_handle): array
public ping(string $workload): bool
public removeOptions(int $option): bool
public returnCode(): int
public runTasks(): bool
public setCompleteCallback(callable $function): bool
public setContext(string $data): bool
public setCreatedCallback(callable $function): bool
public setDataCallback(callable $function): bool
public setExceptionCallback(callable $function): bool
public setFailCallback(callable $function): bool
public setOptions(int $option): bool
public setStatusCallback(callable $function): bool
public setTimeout(int $timeout): bool
public setWarningCallback(callable $function): bool
public setWorkloadCallback(callable $function): bool
public timeout(): int
public wait(): bool
}

目次

  • GearmanClient::addOptions — Add client options
  • GearmanClient::addServer — Add a job server to the client
  • GearmanClient::addServers — Add a list of job servers to the client
  • GearmanClient::addTask — Add a task to be run in parallel
  • GearmanClient::addTaskBackground — Add a background task to be run in parallel
  • GearmanClient::addTaskHigh — Add a high priority task to run in parallel
  • GearmanClient::addTaskHighBackground — Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLow — Add a low priority task to run in parallel
  • GearmanClient::addTaskLowBackground — Add a low priority background task to be run in parallel
  • GearmanClient::addTaskStatus — Add a task to get status
  • GearmanClient::clearCallbacks — Clear all task callback functions
  • GearmanClient::clone — Create a copy of a GearmanClient object
  • GearmanClient::__construct — Create a GearmanClient instance
  • GearmanClient::context — Get the application context
  • GearmanClient::data — Get the application data (deprecated)
  • GearmanClient::do — Run a single task and return a result [deprecated]
  • GearmanClient::doBackground — Run a task in the background
  • GearmanClient::doHigh — Run a single high priority task
  • GearmanClient::doHighBackground — Run a high priority task in the background
  • GearmanClient::doJobHandle — Get the job handle for the running task
  • GearmanClient::doLow — Run a single low priority task
  • GearmanClient::doLowBackground — Run a low priority task in the background
  • GearmanClient::doNormal — Run a single task and return a result
  • GearmanClient::doStatus — Get the status for the running task
  • GearmanClient::echo — Send data to all job servers to see if they echo it back [deprecated]
  • GearmanClient::error — Returns an error string for the last error encountered
  • GearmanClient::getErrno — Get an errno value
  • GearmanClient::jobStatus — Get the status of a background job
  • GearmanClient::ping — Send data to all job servers to see if they echo it back
  • GearmanClient::removeOptions — Remove client options
  • GearmanClient::returnCode — Get the last Gearman return code
  • GearmanClient::runTasks — Run a list of tasks in parallel
  • GearmanClient::setClientCallback — Callback function when there is a data packet for a task (deprecated)
  • GearmanClient::setCompleteCallback — Set a function to be called on task completion
  • GearmanClient::setContext — Set application context
  • GearmanClient::setCreatedCallback — Set a callback for when a task is queued
  • GearmanClient::setData — Set application data (deprecated)
  • GearmanClient::setDataCallback — Callback function when there is a data packet for a task
  • GearmanClient::setExceptionCallback — Set a callback for worker exceptions
  • GearmanClient::setFailCallback — Set callback for job failure
  • GearmanClient::setOptions — Set client options
  • GearmanClient::setStatusCallback — Set a callback for collecting task status
  • GearmanClient::setTimeout — Set socket I/O activity timeout
  • GearmanClient::setWarningCallback — Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback — Set a callback for accepting incremental data updates
  • GearmanClient::timeout — Get current socket I/O activity timeout value
  • GearmanClient::wait — Wait for I/O activity on all connections in a client


Add client options

  • ≪ GearmanClient
  • GearmanClient::addServer ≫
  • PHP Manual
  • GearmanClient
  • Add client options

GearmanClient::addOptions

(PECL gearman >= 0.6.0)

GearmanClient::addOptions — Add client options

説明

public GearmanClient::addOptions(int $option): bool

Adds one or more options to those already set.

パラメータ

option

The options to add. One of the following constants, or a combination of them using the bitwise OR operator (|): GEARMAN_CLIENT_GENERATE_UNIQUE, GEARMAN_CLIENT_NON_BLOCKING, GEARMAN_CLIENT_UNBUFFERED_RESULT or GEARMAN_CLIENT_FREE_TASKS.

戻り値

Always returns true.


Add a job server to the client

  • ≪ GearmanClient::addOptions
  • GearmanClient::addServers ≫
  • PHP Manual
  • GearmanClient
  • Add a job server to the client

GearmanClient::addServer

(PECL gearman >= 0.5.0)

GearmanClient::addServer — Add a job server to the client

説明

public GearmanClient::addServer(string $host = null, int $port = 0, bool $setupExceptionHandler = true): bool

Adds a job server to a list of servers that can be used to run a task. No socket I/O happens here; the server is simply added to the list.

パラメータ

host

ジョブサーバーのホスト名。

port

ジョブサーバーのポート番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Adding two job servers

<?php

# Create our client object.
$gmclient= new GearmanClient();

# Add two job servers, the first on the default 4730 port
$gmclient->addServer("10.0.0.1");
$gmclient->addServer("10.0.0.2", 7003);

?>

参考

  • GearmanClient::addServers() - Add a list of job servers to the client


Add a list of job servers to the client

  • ≪ GearmanClient::addServer
  • GearmanClient::addTask ≫
  • PHP Manual
  • GearmanClient
  • Add a list of job servers to the client

GearmanClient::addServers

(PECL gearman >= 0.5.0)

GearmanClient::addServers — Add a list of job servers to the client

説明

public GearmanClient::addServers(string $servers = null, bool $setupExceptionHandler = true): bool

Adds a list of job servers that can be used to run a task. No socket I/O happens here; the servers are simply added to the full list of servers.

パラメータ

servers

A comma-separated list of servers, each server specified in the format 'host:port'.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Add two job servers

<?php

# Create our client object.
$gmclient= new GearmanClient();

# Add multiple job servers, the first on the default 4730 port
$gmclient->addServers("10.0.0.1,10.0.0.2:7003");

?>

参考

  • GearmanClient::addServer() - Add a job server to the client


Add a task to be run in parallel

  • ≪ GearmanClient::addServers
  • GearmanClient::addTaskBackground ≫
  • PHP Manual
  • GearmanClient
  • Add a task to be run in parallel

GearmanClient::addTask

(PECL gearman >= 0.5.0)

GearmanClient::addTask — Add a task to be run in parallel

説明

public GearmanClient::addTask(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false

Adds a task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Note that enough workers need to be available for the tasks to all run in parallel.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique_key

タスクを特定するために用いる一意な ID。

戻り値

A GearmanTask object or false if the task could not be added.

例

例1 Basic submission of two tasks

<?php

# Create our gearman client
$gmclient= new GearmanClient();

# add the default job server
$gmclient->addServer();

# set a function to be called when the work is complete
$gmclient->setCompleteCallback("complete");

# add a task to perform the "reverse" function on the string "Hello World!"
$gmclient->addTask("reverse", "Hello World!", null, "1");

# add another task to perform the "reverse" function on the string "!dlroW olleH"
$gmclient->addTask("reverse", "!dlroW olleH", null, "2");

# run the tasks
$gmclient->runTasks();

function complete($task)
{
print "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

COMPLETE: 2, Hello World!
COMPLETE: 1, !dlroW olleH

例2 Basic submission of two tasks with passing application context

<?php

$client = new GearmanClient();
$client->addServer();

# set a function to be called when the work is complete
$client->setCompleteCallback("reverse_complete");

# Add some tasks for a placeholder of where to put the results
$results = array();
$client->addTask("reverse", "Hello World!", $results, "t1");
$client->addTask("reverse", "!dlroW olleH", $results, "t2");

$client->runTasks();

# The results should now be filled in from the callbacks
foreach ($results as $id => $result)
echo $id . ": " . $result['handle'] . ", " . $result['data'] . "\n";

function reverse_complete($task, $results)
{
$results[$task->unique()] = array("handle"=>$task->jobHandle(), "data"=>$task->data());
}

?>

上の例の出力は、 たとえば以下のようになります。

t2: H.foo:21, Hello World!
t1: H:foo:22, !dlroW olleH

参考

  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel


Add a background task to be run in parallel

  • ≪ GearmanClient::addTask
  • GearmanClient::addTaskHigh ≫
  • PHP Manual
  • GearmanClient
  • Add a background task to be run in parallel

GearmanClient::addTaskBackground

(PECL gearman >= 0.5.0)

GearmanClient::addTaskBackground — Add a background task to be run in parallel

説明

public GearmanClient::addTaskBackground(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false

Adds a background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique_key

タスクを特定するために用いる一意な ID。

戻り値

A GearmanTask object or false if the task could not be added.

例

例1 Two tasks, one background and one not

This example illustrates the difference between running a background task and a normal task. The client adds two tasks to execute the same function, but one is added with addTaskBackground(). A callback is set so that progress of the job can be tracked. A simple worker with an artificial delay reports on the job progress and the client picks this up through the callback. Two workers are run for this example. Note that the background task does not show in the client output.

<?php

# The client script

# create our gearman client
$gmc= new GearmanClient();

# add the default job server
$gmc->addServer();

# set a couple of callbacks so we can track progress
$gmc->setCompleteCallback("reverse_complete");
$gmc->setStatusCallback("reverse_status");

# add a task for the "reverse" function
$task= $gmc->addTask("reverse", "Hello World!", null, "1");

# add another task, but this one to run in the background
$task= $gmc->addTaskBackground("reverse", "!dlroW olleH", null, "2");

if (! $gmc->runTasks())
{
echo "ERROR " . $gmc->error() . "\n";
exit;
}

echo "DONE\n";

function reverse_status($task)
{
echo "STATUS: " . $task->unique() . ", " . $task->jobHandle() . " - " . $task->taskNumerator() .
"/" . $task->taskDenominator() . "\n";
}

function reverse_complete($task)
{
echo "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>
<?php

# The worker script

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
echo "Received job: " . $job->handle() . "\n";

$workload = $job->workload();
$workload_size = $job->workloadSize();

echo "Workload: $workload ($workload_size)\n";

# This status loop is not needed, just showing how it works
for ($x= 0; $x < $workload_size; $x++)
{
echo "Sending status: " . ($x + 1) . "/$workload_size complete\n";
$job->sendStatus($x+1, $workload_size);
$job->sendData(substr($workload, $x, 1));
sleep(1);
}

$result= strrev($workload);
echo "Result: $result\n";

# Return what we want to send back to the client.
return $result;
}

?>

Worker output for two workers running:

Received job: H:foo.local:65
Workload: !dlroW olleH (12)
1/12 complete
Received job: H:foo.local:66
Workload: Hello World! (12)
Sending status: 1/12 complete
Sending status: 2/12 complete
Sending status: 2/12 complete
Sending status: 3/12 complete
Sending status: 3/12 complete
Sending status: 4/12 complete
Sending status: 4/12 complete
Sending status: 5/12 complete
Sending status: 5/12 complete
Sending status: 6/12 complete
Sending status: 6/12 complete
Sending status: 7/12 complete
Sending status: 7/12 complete
Sending status: 8/12 complete
Sending status: 8/12 complete
Sending status: 9/12 complete
Sending status: 9/12 complete
Sending status: 10/12 complete
Sending status: 10/12 complete
Sending status: 11/12 complete
Sending status: 11/12 complete
Sending status: 12/12 complete
Sending status: 12/12 complete
Result: !dlroW olleH
Result: Hello World!

Client output:

STATUS: 1, H:foo.local:66 - 1/12
STATUS: 1, H:foo.local:66 - 2/12
STATUS: 1, H:foo.local:66 - 3/12
STATUS: 1, H:foo.local:66 - 4/12
STATUS: 1, H:foo.local:66 - 5/12
STATUS: 1, H:foo.local:66 - 6/12
STATUS: 1, H:foo.local:66 - 7/12
STATUS: 1, H:foo.local:66 - 8/12
STATUS: 1, H:foo.local:66 - 9/12
STATUS: 1, H:foo.local:66 - 10/12
STATUS: 1, H:foo.local:66 - 11/12
STATUS: 1, H:foo.local:66 - 12/12
COMPLETE: 1, !dlroW olleH
DONE

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel


Add a high priority task to run in parallel

  • ≪ GearmanClient::addTaskBackground
  • GearmanClient::addTaskHighBackground ≫
  • PHP Manual
  • GearmanClient
  • Add a high priority task to run in parallel

GearmanClient::addTaskHigh

(PECL gearman >= 0.5.0)

GearmanClient::addTaskHigh — Add a high priority task to run in parallel

説明

public GearmanClient::addTaskHigh(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false

Adds a high priority task to be run in parallel with other tasks. Call this method for all the high priority tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a high priority will be selected from the queue before those of normal or low priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique_key

タスクを特定するために用いる一意な ID。

戻り値

A GearmanTask object or false if the task could not be added.

例

例1 A high priority task along with two normal tasks

A high priority task is included among two other tasks. A single worker is available, so that tasks are run one at a time, with the high priority task run first.

<?php

# create the gearman client
$gmc= new GearmanClient();

# add the default job server
$gmc->addServer();

# set the callback for when the job is complete
$gmc->setCompleteCallback("reverse_complete");

# add tasks, one of which is high priority
$task= $gmc->addTask("reverse", "Hello World!", null, "1");
$task= $gmc->addTaskHigh("reverse", "!dlroW olleH", null, "2");
$task= $gmc->addTask("reverse", "Hello World!", null, "3");

if (! $gmc->runTasks())
{
echo "ERROR " . $gmc->error() . "\n";
exit;
}
echo "DONE\n";

function reverse_complete($task)
{
echo "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

COMPLETE: 2, Hello World!
COMPLETE: 3, !dlroW olleH
COMPLETE: 1, !dlroW olleH
DONE

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel


Add a high priority background task to be run in parallel

  • ≪ GearmanClient::addTaskHigh
  • GearmanClient::addTaskLow ≫
  • PHP Manual
  • GearmanClient
  • Add a high priority background task to be run in parallel

GearmanClient::addTaskHighBackground

(PECL gearman >= 0.5.0)

GearmanClient::addTaskHighBackground — Add a high priority background task to be run in parallel

説明

public GearmanClient::addTaskHighBackground(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false

Adds a high priority background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a high priority will be selected from the queue before those of normal or low priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique_key

タスクを特定するために用いる一意な ID。

戻り値

A GearmanTask object or false if the task could not be added.

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel


Add a low priority task to run in parallel

  • ≪ GearmanClient::addTaskHighBackground
  • GearmanClient::addTaskLowBackground ≫
  • PHP Manual
  • GearmanClient
  • Add a low priority task to run in parallel

GearmanClient::addTaskLow

(PECL gearman >= 0.5.0)

GearmanClient::addTaskLow — Add a low priority task to run in parallel

説明

public GearmanClient::addTaskLow(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false

Adds a low priority background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a low priority will be selected from the queue after those of normal or low priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique_key

タスクを特定するために用いる一意な ID。

戻り値

A GearmanTask object or false if the task could not be added.

例

例1 A low priority task along with two normal tasks

A low priority task is included among two other tasks. A single worker is available, so that tasks are run one at a time, with the low priority task run last.

<?php

# create the gearman client
$gmc= new GearmanClient();

# add the default job server
$gmc->addServer();

# set the callback for when the job is complete
$gmc->setCompleteCallback("reverse_complete");

# add tasks, one of which is low priority
$task= $gmc->addTask("reverse", "Hello World!", null, "1");
$task= $gmc->addTaskLow("reverse", "!dlroW olleH", null, "2");
$task= $gmc->addTask("reverse", "Hello World!", null, "3");

if (! $gmc->runTasks())
{
echo "ERROR " . $gmc->error() . "\n";
exit;
}
echo "DONE\n";

function reverse_complete($task)
{
echo "COMPLETE: " . $task->unique() . ", " . $task->data() . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

COMPLETE: 3, !dlroW olleH
COMPLETE: 1, !dlroW olleH
COMPLETE: 2, Hello World!
DONE

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::addTaskLowBackground() - Add a low priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel


Add a low priority background task to be run in parallel

  • ≪ GearmanClient::addTaskLow
  • GearmanClient::addTaskStatus ≫
  • PHP Manual
  • GearmanClient
  • Add a low priority background task to be run in parallel

GearmanClient::addTaskLowBackground

(PECL gearman >= 0.5.0)

GearmanClient::addTaskLowBackground — Add a low priority background task to be run in parallel

説明

public GearmanClient::addTaskLowBackground(
string $function_name,
string|int|float $workload,
mixed $context = null,
?string $unique_key = null
): GearmanTask|false

Adds a low priority background task to be run in parallel with other tasks. Call this method for all the tasks to be run in parallel, then call GearmanClient::runTasks() to perform the work. Tasks with a low priority will be selected from the queue after those of normal or high priority.

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

context

タスクに関連づけるアプリケーションコンテキスト。

unique_key

タスクを特定するために用いる一意な ID。

戻り値

A GearmanTask object or false if the task could not be added.

参考

  • GearmanClient::addTask() - Add a task to be run in parallel
  • GearmanClient::addTaskHigh() - Add a high priority task to run in parallel
  • GearmanClient::addTaskLow() - Add a low priority task to run in parallel
  • GearmanClient::addTaskBackground() - Add a background task to be run in parallel
  • GearmanClient::addTaskHighBackground() - Add a high priority background task to be run in parallel
  • GearmanClient::runTasks() - Run a list of tasks in parallel


Add a task to get status

  • ≪ GearmanClient::addTaskLowBackground
  • GearmanClient::clearCallbacks ≫
  • PHP Manual
  • GearmanClient
  • Add a task to get status

GearmanClient::addTaskStatus

(PECL gearman >= 0.5.0)

GearmanClient::addTaskStatus — Add a task to get status

説明

public GearmanClient::addTaskStatus(string $job_handle, mixed $context = null): GearmanTask|false

Used to request status information from the Gearman server, which will call the specified status callback (set using GearmanClient::setStatusCallback()).

パラメータ

job_handle

The job handle for the task to get status for

context

Data to be passed to the status callback, generally a reference to an array or object

戻り値

A GearmanTask object or false on failure.

例

例1 Monitor completion of multiple background tasks

An artificial delay is introduced in the worker in this example to simulate a long running process. There is only one worker running for this example.

<?php

/* create our object */
$gmclient= new GearmanClient();

/* add the default server */
$gmclient->addServer();

/* start some background jobs and save the handles */
$handles = array();
$handles[0] = $gmclient->doBackground("reverse", "Hello World!");
$handles[1] = $gmclient->doBackground("reverse", "!dlroW olleH");

$gmclient->setStatusCallback("reverse_status");

/* Poll the server to see when those background jobs finish; */
/* a better method would be to use event callbacks */
do
{
/* Use the context variable to track how many tasks have completed */
$done = 0;
$gmclient->addTaskStatus($handles[0], &$done);
$gmclient->addTaskStatus($handles[1], &$done);
$gmclient->runTasks();
echo "Done: $done\n";
sleep(1);
}
while ($done != 2);

function reverse_status($task, $done)
{
if (!$task->isKnown())
$done++;
}

?>

上の例の出力は、 たとえば以下のようになります。

Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 0
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 1
Done: 2

参考

  • GearmanClient::setStatusCallback() - Set a callback for collecting task status


Clear all task callback functions

  • ≪ GearmanClient::addTaskStatus
  • GearmanClient::clone ≫
  • PHP Manual
  • GearmanClient
  • Clear all task callback functions

GearmanClient::clearCallbacks

(PECL gearman >= 0.5.0)

GearmanClient::clearCallbacks — Clear all task callback functions

説明

public GearmanClient::clearCallbacks(): bool

Clears all the task callback functions that have previously been set.

パラメータ

この関数にはパラメータはありません。

戻り値

Always returns true.

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Create a copy of a GearmanClient object

  • ≪ GearmanClient::clearCallbacks
  • GearmanClient::__construct ≫
  • PHP Manual
  • GearmanClient
  • Create a copy of a GearmanClient object

GearmanClient::clone

(PECL gearman >= 0.5.0)

GearmanClient::clone — Create a copy of a GearmanClient object

説明

public GearmanClient::clone(): GearmanClient

Creates a copy of a GearmanClient object.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanClient on success, false on failure.


Create a GearmanClient instance

  • ≪ GearmanClient::clone
  • GearmanClient::context ≫
  • PHP Manual
  • GearmanClient
  • Create a GearmanClient instance

GearmanClient::__construct

(PECL gearman >= 0.5.0)

GearmanClient::__construct — Create a GearmanClient instance

説明

public GearmanClient::__construct()

Creates a GearmanClient instance representing a client that connects to the job server and submits tasks to complete.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanClient object.

参考

  • GearmanClient::clone() - Create a copy of a GearmanClient object


Get the application context

  • ≪ GearmanClient::__construct
  • GearmanClient::data ≫
  • PHP Manual
  • GearmanClient
  • Get the application context

GearmanClient::context

(PECL gearman >= 0.6.0)

GearmanClient::context — Get the application context

説明

public GearmanClient::context(): string

Get the application context previously set with GearmanClient::setContext().

パラメータ

この関数にはパラメータはありません。

戻り値

The same context data structure set with GearmanClient::setContext()

参考

  • GearmanClient::setContext() - Set application context


Get the application data (deprecated)

  • ≪ GearmanClient::context
  • GearmanClient::do ≫
  • PHP Manual
  • GearmanClient
  • Get the application data (deprecated)

GearmanClient::data

(PECL gearman <= 0.5.0)

GearmanClient::data — Get the application data (deprecated)

説明

public GearmanClient::data(): string

Get the application data previously set with GearmanClient::setData().

注意:

This method was replaced by GearmanClient::setContext() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

戻り値

The same string data set with GearmanClient::setData()

参考

  • GearmanClient::setData() - Set application data (deprecated)


Run a single task and return a result [deprecated]

  • ≪ GearmanClient::data
  • GearmanClient::doBackground ≫
  • PHP Manual
  • GearmanClient
  • Run a single task and return a result [deprecated]

GearmanClient::do

(PECL gearman >= 0.5.0)

GearmanClient::do — Run a single task and return a result [deprecated]

説明

public GearmanClient::do(string $function_name, string $workload, string $unique = ?): string

The GearmanClient::do() method is deprecated as of pecl/gearman 1.0.0. Use GearmanClient::doNormal().

パラメータ

function_name

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

A string representing the results of running a task.

例

例1 Simple job submission with immediate return

<?php

# Client code

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

$result = $gmclient->doNormal("reverse", "Hello!");

echo "Success: $result\n";

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

Starting
Sending job
Success: !olleH

例2 Submitting a job and retrieving incremental status

A job is submitted and the script loops to retrieve status information. The worker has an artificial delay which results in a long running job and sends status and data as processing occurs. Each subsequent call to GearmanClient::do() produces status information on the running job.

<?php

# Client code

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
$result = $gmclient->doNormal("reverse", "Hello!");
# Check for various return packets and errors.

switch($gmclient->returnCode())
{
case GEARMAN_WORK_DATA:
echo "Data: $result\n";
break;
case GEARMAN_WORK_STATUS:
list($numerator, $denominator)= $gmclient->doStatus();
echo "Status: $numerator/$denominator complete\n";
break;
case GEARMAN_WORK_FAIL:
echo "Failed\n";
exit;
case GEARMAN_SUCCESS:
break;
default:
echo "RET: " . $gmclient->returnCode() . "\n";
echo "Error: " . $gmclient->error() . "\n";
echo "Errno: " . $gmclient->getErrno() . "\n";
exit;
}
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

echo "Success: $result\n";

?>
<?php

# Worker code

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
echo "Received job: " . $job->handle() . "\n";

$workload = $job->workload();
$workload_size = $job->workloadSize();

echo "Workload: $workload ($workload_size)\n";

# This status loop is not needed, just showing how it works
for ($x= 0; $x < $workload_size; $x++)
{
echo "Sending status: " + $x + 1 . "/$workload_size complete\n";
$job->sendStatus($x+1, $workload_size);
$job->sendData(substr($workload, $x, 1));
sleep(1);
}

$result= strrev($workload);
echo "Result: $result\n";

# Return what we want to send back to the client.
return $result;
}

?>

上の例の出力は、 たとえば以下のようになります。

Worker output:

Starting
Waiting for job...
Received job: H:foo.local:106
Workload: Hello! (6)
1/6 complete
2/6 complete
3/6 complete
4/6 complete
5/6 complete
6/6 complete
Result: !olleH

Client output:

Starting
Sending job
Status: 1/6 complete
Data: H
Status: 2/6 complete
Data: e
Status: 3/6 complete
Data: l
Status: 4/6 complete
Data: l
Status: 5/6 complete
Data: o
Status: 6/6 complete
Data: !
Success: !olleH

参考

  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background


Run a task in the background

  • ≪ GearmanClient::do
  • GearmanClient::doHigh ≫
  • PHP Manual
  • GearmanClient
  • Run a task in the background

GearmanClient::doBackground

(PECL gearman >= 0.5.0)

GearmanClient::doBackground — Run a task in the background

説明

public GearmanClient::doBackground(string $function, string $workload, ?string $unique = null): string

Runs a task in the background, returning a job handle which can be used to get the status of the running task.

パラメータ

function

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

The job handle for the submitted task.

例

例1 Submit and monitor a background job

The worker in this example has an artificial delay introduced to mimic a long running job. The client script periodically checks the status of the running job.

<?php

/* create our object */
$gmclient= new GearmanClient();

/* add the default server */
$gmclient->addServer();

/* run reverse client */
$job_handle = $gmclient->doBackground("reverse", "this is a test");

if ($gmclient->returnCode() != GEARMAN_SUCCESS)
{
echo "bad return code\n";
exit;
}

$done = false;
do
{
sleep(3);
$stat = $gmclient->jobStatus($job_handle);
if (!$stat[0]) // the job is known so it is not done
$done = true;
echo "Running: " . ($stat[1] ? "true" : "false") . ", numerator: " . $stat[2] . ", denominator: " . $stat[3] . "\n";
}
while(!$done);

echo "done!\n";

?>

上の例の出力は、 たとえば以下のようになります。

Running: true, numerator: 3, denominator: 14
Running: true, numerator: 6, denominator: 14
Running: true, numerator: 9, denominator: 14
Running: true, numerator: 12, denominator: 14
Running: false, numerator: 0, denominator: 0
done!

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background


Run a single high priority task

  • ≪ GearmanClient::doBackground
  • GearmanClient::doHighBackground ≫
  • PHP Manual
  • GearmanClient
  • Run a single high priority task

GearmanClient::doHigh

(PECL gearman >= 0.5.0)

GearmanClient::doHigh — Run a single high priority task

説明

public GearmanClient::doHigh(string $function, string $workload, ?string $unique = null): string

Runs a single high priority task and returns a string representation of the result. It is up to the GearmanClient and GearmanWorker to agree on the format of the result. High priority tasks will get precedence over normal and low priority tasks in the job queue.

パラメータ

function

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

A string representing the results of running a task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background


Run a high priority task in the background

  • ≪ GearmanClient::doHigh
  • GearmanClient::doJobHandle ≫
  • PHP Manual
  • GearmanClient
  • Run a high priority task in the background

GearmanClient::doHighBackground

(PECL gearman >= 0.5.0)

GearmanClient::doHighBackground — Run a high priority task in the background

説明

public GearmanClient::doHighBackground(string $function, string $workload, ?string $unique = null): string

Runs a high priority task in the background, returning a job handle which can be used to get the status of the running task. High priority tasks take precedence over normal and low priority tasks in the job queue.

パラメータ

function

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

The job handle for the submitted task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background


Get the job handle for the running task

  • ≪ GearmanClient::doHighBackground
  • GearmanClient::doLow ≫
  • PHP Manual
  • GearmanClient
  • Get the job handle for the running task

GearmanClient::doJobHandle

(PECL gearman >= 0.5.0)

GearmanClient::doJobHandle — Get the job handle for the running task

説明

public GearmanClient::doJobHandle(): string

Gets that job handle for a running task. This should be used between repeated GearmanClient::doNormal() calls. The job handle can then be used to get information on the task.

パラメータ

この関数にはパラメータはありません。

戻り値

The job handle for the running task.

参考

  • GearmanClient::jobStatus() - Get the status of a background job


Run a single low priority task

  • ≪ GearmanClient::doJobHandle
  • GearmanClient::doLowBackground ≫
  • PHP Manual
  • GearmanClient
  • Run a single low priority task

GearmanClient::doLow

(PECL gearman >= 0.5.0)

GearmanClient::doLow — Run a single low priority task

説明

public GearmanClient::doLow(string $function, string $workload, ?string $unique = null): string

Runs a single low priority task and returns a string representation of the result. It is up to the GearmanClient and GearmanWorker to agree on the format of the result. Normal and high priority tasks will get precedence over low priority tasks in the job queue.

パラメータ

function

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

A string representing the results of running a task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background


Run a low priority task in the background

  • ≪ GearmanClient::doLow
  • GearmanClient::doNormal ≫
  • PHP Manual
  • GearmanClient
  • Run a low priority task in the background

GearmanClient::doLowBackground

(PECL gearman >= 0.5.0)

GearmanClient::doLowBackground — Run a low priority task in the background

説明

public GearmanClient::doLowBackground(string $function, string $workload, ?string $unique = null): string

Runs a low priority task in the background, returning a job handle which can be used to get the status of the running task. Normal and high priority tasks take precedence over low priority tasks in the job queue.

パラメータ

function

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

The job handle for the submitted task.

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background


Run a single task and return a result

  • ≪ GearmanClient::doLowBackground
  • GearmanClient::doStatus ≫
  • PHP Manual
  • GearmanClient
  • Run a single task and return a result

GearmanClient::doNormal

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

GearmanClient::doNormal — Run a single task and return a result

説明

public GearmanClient::doNormal(string $function, string $workload, ?string $unique = null): string

Runs a single task and returns a string representation of the result. It is up to the GearmanClient and GearmanWorker to agree on the format of the result.

パラメータ

function

ワーカーが実行するために登録した関数。

workload

シリアライズしたデータ。

unique

タスクを特定するために用いる一意な ID。

戻り値

A string representing the results of running a task.

例

例1 Simple job submission with immediate return

<?php

?>
<?php

# Client code

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

$result = $gmclient->doNormal("reverse", "Hello!");

echo "Success: $result\n";

?>
<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
return strrev($job->workload());
}

?>

上の例の出力は、 たとえば以下のようになります。

Starting
Sending job
Success: !olleH

例2 Submitting a job and retrieving incremental status

A job is submitted and the script loops to retrieve status information. The worker has an artificial delay which results in a long running job and sends status and data as processing occurs. Each subsequent call to GearmanClient::doNormal() produces status information on the running job.

<?php

# Client code

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
$result = $gmclient->doNormal("reverse", "Hello!");
# Check for various return packets and errors.

switch($gmclient->returnCode())
{
case GEARMAN_WORK_DATA:
echo "Data: $result\n";
break;
case GEARMAN_WORK_STATUS:
list($numerator, $denominator)= $gmclient->doStatus();
echo "Status: $numerator/$denominator complete\n";
break;
case GEARMAN_WORK_FAIL:
echo "Failed\n";
exit;
case GEARMAN_SUCCESS:
break;
default:
echo "RET: " . $gmclient->returnCode() . "\n";
echo "Error: " . $gmclient->error() . "\n";
echo "Errno: " . $gmclient->getErrno() . "\n";
exit;
}
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

echo "Success: $result\n";

?>
<?php

# Worker code

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

function reverse_fn($job)
{
echo "Received job: " . $job->handle() . "\n";

$workload = $job->workload();
$workload_size = $job->workloadSize();

echo "Workload: $workload ($workload_size)\n";

# This status loop is not needed, just showing how it works
for ($x= 0; $x < $workload_size; $x++)
{
echo "Sending status: " + $x + 1 . "/$workload_size complete\n";
$job->sendStatus($x+1, $workload_size);
$job->sendData(substr($workload, $x, 1));
sleep(1);
}

$result= strrev($workload);
echo "Result: $result\n";

# Return what we want to send back to the client.
return $result;
}

?>

上の例の出力は、 たとえば以下のようになります。

Worker output:

Starting
Waiting for job...
Received job: H:foo.local:106
Workload: Hello! (6)
1/6 complete
2/6 complete
3/6 complete
4/6 complete
5/6 complete
6/6 complete
Result: !olleH

Client output:

Starting
Sending job
Status: 1/6 complete
Data: H
Status: 2/6 complete
Data: e
Status: 3/6 complete
Data: l
Status: 4/6 complete
Data: l
Status: 5/6 complete
Data: o
Status: 6/6 complete
Data: !
Success: !olleH

参考

  • GearmanClient::doHigh() - Run a single high priority task
  • GearmanClient::doLow() - Run a single low priority task
  • GearmanClient::doBackground() - Run a task in the background
  • GearmanClient::doHighBackground() - Run a high priority task in the background
  • GearmanClient::doLowBackground() - Run a low priority task in the background


Get the status for the running task

  • ≪ GearmanClient::doNormal
  • GearmanClient::echo ≫
  • PHP Manual
  • GearmanClient
  • Get the status for the running task

GearmanClient::doStatus

(PECL gearman >= 0.5.0)

GearmanClient::doStatus — Get the status for the running task

説明

public GearmanClient::doStatus(): array

Returns the status for the running task. This should be used between repeated GearmanClient::doNormal() calls.

パラメータ

この関数にはパラメータはありません。

戻り値

An array representing the percentage completion given as a fraction, with the first element the numerator and the second element the denomintor.

例

例1 Get the status of a long running job

The worker in this example has an artificial delay added during processing of the string to be reversed. After each delay it calls GearmanJob::status() which the client then picks up.

<?php

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
$result = $gmclient->doNormal("reverse", "Hello!");

# Check for various return packets and errors.
switch($gmclient->returnCode())
{
case GEARMAN_WORK_DATA:
break;
case GEARMAN_WORK_STATUS:
# get the current job status
list($numerator, $denominator)= $gmclient->doStatus();
echo "Status: $numerator/$denominator complete\n";
break;
case GEARMAN_WORK_FAIL:
echo "Failed\n";
exit;
case GEARMAN_SUCCESS:
break;
default:
echo "RET: " . $gmclient->returnCode() . "\n";
exit;
}
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);

echo "Success: $result\n";

?>

上の例の出力は、 たとえば以下のようになります。

Starting
Sending job
Status: 1/6 complete
Status: 2/6 complete
Status: 3/6 complete
Status: 4/6 complete
Status: 5/6 complete
Status: 6/6 complete
Success: !olleH

参考

  • GearmanClient::doNormal() - Run a single task and return a result
  • GearmanJob::status() - Send status (deprecated)


Send data to all job servers to see if they echo it back [deprecated]

  • ≪ GearmanClient::doStatus
  • GearmanClient::error ≫
  • PHP Manual
  • GearmanClient
  • Send data to all job servers to see if they echo it back [deprecated]

GearmanClient::echo

(PECL gearman >= 0.5.0)

GearmanClient::echo — Send data to all job servers to see if they echo it back [deprecated]

説明

public GearmanClient::echo(string $workload): bool

The GearmanClient::echo() method is deprecated as of pecl/gearman 1.0.0. Use GearmanClient::ping().

パラメータ

workload

Some arbitrary serialized data to be echo back

戻り値

成功した場合に true を、失敗した場合に false を返します。


Returns an error string for the last error encountered

  • ≪ GearmanClient::echo
  • GearmanClient::getErrno ≫
  • PHP Manual
  • GearmanClient
  • Returns an error string for the last error encountered

GearmanClient::error

(PECL gearman >= 0.5.0)

GearmanClient::error — Returns an error string for the last error encountered

説明

public GearmanClient::error(): string|false

Returns an error string for the last error encountered.

パラメータ

この関数にはパラメータはありません。

戻り値

A human readable error string, or false if there is no error message available.

参考

  • GearmanClient::getErrno() - Get an errno value


Get an errno value

  • ≪ GearmanClient::error
  • GearmanClient::jobStatus ≫
  • PHP Manual
  • GearmanClient
  • Get an errno value

GearmanClient::getErrno

(PECL gearman >= 0.5.0)

GearmanClient::getErrno — Get an errno value

説明

public GearmanClient::getErrno(): int

Value of errno in the case of a GEARMAN_ERRNO return value.

パラメータ

この関数にはパラメータはありません。

戻り値

A valid Gearman errno.

参考

  • GearmanClient::error() - Returns an error string for the last error encountered


Get the status of a background job

  • ≪ GearmanClient::getErrno
  • GearmanClient::ping ≫
  • PHP Manual
  • GearmanClient
  • Get the status of a background job

GearmanClient::jobStatus

gearman_job_status

(PECL gearman >= 0.5.0)

GearmanClient::jobStatus -- gearman_job_status — Get the status of a background job

説明

オブジェクト指向型 (method):

public GearmanClient::jobStatus(string $job_handle): array

Gets the status for a background job given a job handle. The status information will specify whether the job is known, whether the job is currently running, and the percentage completion.

パラメータ

job_handle

Gearman サーバーが割り当てたジョブハンドル。

戻り値

An array containing status information for the job corresponding to the supplied job handle. The first array element is a boolean indicating whether the job is even known, the second is a boolean indicating whether the job is still running, and the third and fourth elements correspond to the numerator and denominator of the fractional completion percentage, respectively.

例

例1 Monitor the status of a long running background job

<?php

/* create our object */
$gmclient= new GearmanClient();

/* add the default server */
$gmclient->addServer();

/* run reverse client */
$job_handle = $gmclient->doBackground("reverse", "this is a test");

if ($gmclient->returnCode() != GEARMAN_SUCCESS)
{
echo "bad return code\n";
exit;
}

$done = false;
do
{
sleep(3);
$stat = $gmclient->jobStatus($job_handle);
if (!$stat[0]) // the job is known so it is not done
$done = true;
echo "Running: " . ($stat[1] ? "true" : "false") . ", numerator: " . $stat[2] . ", denomintor: " . $stat[3] . "\n";
}
while(!$done);

echo "done!\n";

?>

上の例の出力は、 たとえば以下のようになります。

Running: true, numerator: 3, denomintor: 14
Running: true, numerator: 6, denomintor: 14
Running: true, numerator: 9, denomintor: 14
Running: true, numerator: 12, denomintor: 14
Running: false, numerator: 0, denomintor: 0
done!

参考

  • GearmanClient::doStatus() - Get the status for the running task


Send data to all job servers to see if they echo it back

  • ≪ GearmanClient::jobStatus
  • GearmanClient::removeOptions ≫
  • PHP Manual
  • GearmanClient
  • Send data to all job servers to see if they echo it back

GearmanClient::ping

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

GearmanClient::ping — Send data to all job servers to see if they echo it back

説明

public GearmanClient::ping(string $workload): bool

Sends some arbitrary data to all job servers to see if they echo it back. The data sent is not used or processed in any other way. Primarily used for testing and debugging.

パラメータ

workload

Some arbitrary serialized data to be echo back

戻り値

成功した場合に true を、失敗した場合に false を返します。


Remove client options

  • ≪ GearmanClient::ping
  • GearmanClient::returnCode ≫
  • PHP Manual
  • GearmanClient
  • Remove client options

GearmanClient::removeOptions

(PECL gearman >= 0.6.0)

GearmanClient::removeOptions — Remove client options

説明

public GearmanClient::removeOptions(int $option): bool

Removes (unsets) one or more options.

パラメータ

option

The options to be removed (unset)

戻り値

Always returns true.


Get the last Gearman return code

  • ≪ GearmanClient::removeOptions
  • GearmanClient::runTasks ≫
  • PHP Manual
  • GearmanClient
  • Get the last Gearman return code

GearmanClient::returnCode

(PECL gearman >= 0.5.0)

GearmanClient::returnCode — Get the last Gearman return code

説明

public GearmanClient::returnCode(): int

Returns the last Gearman return code.

パラメータ

この関数にはパラメータはありません。

戻り値

A valid Gearman return code.


Run a list of tasks in parallel

  • ≪ GearmanClient::returnCode
  • GearmanClient::setClientCallback ≫
  • PHP Manual
  • GearmanClient
  • Run a list of tasks in parallel

GearmanClient::runTasks

(PECL gearman >= 0.5.0)

GearmanClient::runTasks — Run a list of tasks in parallel

説明

public GearmanClient::runTasks(): bool

For a set of tasks previously added with GearmanClient::addTask(), GearmanClient::addTaskHigh(), GearmanClient::addTaskLow(), GearmanClient::addTaskBackground(), GearmanClient::addTaskHighBackground(), or GearmanClient::addTaskLowBackground(), this call starts running the tasks in parallel.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::addTask() - Add a task to be run in parallel


Callback function when there is a data packet for a task (deprecated)

  • ≪ GearmanClient::runTasks
  • GearmanClient::setCompleteCallback ≫
  • PHP Manual
  • GearmanClient
  • Callback function when there is a data packet for a task (deprecated)

GearmanClient::setClientCallback

(PECL gearman <= 0.5.0)

GearmanClient::setClientCallback — Callback function when there is a data packet for a task (deprecated)

説明

public GearmanClient::setClientCallback(callable $callback): void

Sets the callback function for accepting data packets for a task. The callback function should take a single argument, a GearmanTask object.

注意:

This method has been replaced by GearmanClient::setDataCallback() in the 0.6.0 release of the Gearman extension.

パラメータ

callback

A function or method to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set a function to be called on task completion

  • ≪ GearmanClient::setClientCallback
  • GearmanClient::setContext ≫
  • PHP Manual
  • GearmanClient
  • Set a function to be called on task completion

GearmanClient::setCompleteCallback

(PECL gearman >= 0.5.0)

GearmanClient::setCompleteCallback — Set a function to be called on task completion

説明

public GearmanClient::setCompleteCallback(callable $function): bool

Use to set a function to be called when a GearmanTask is completed, or when GearmanJob::sendComplete() is invoked by a worker (whichever happens first).

This callback executes only when executing a GearmanTask using GearmanClient::runTasks(). It is not used for individual jobs.

パラメータ

function

A function to be called

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set application context

  • ≪ GearmanClient::setCompleteCallback
  • GearmanClient::setCreatedCallback ≫
  • PHP Manual
  • GearmanClient
  • Set application context

GearmanClient::setContext

(PECL gearman >= 0.6.0)

GearmanClient::setContext — Set application context

説明

public GearmanClient::setContext(string $data): bool

Sets an arbitrary string to provide application context that can later be retrieved by GearmanClient::context().

パラメータ

data

Arbitrary context data

戻り値

Always returns true.

参考

  • GearmanClient::context() - Get the application context


Set a callback for when a task is queued

  • ≪ GearmanClient::setContext
  • GearmanClient::setData ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for when a task is queued

GearmanClient::setCreatedCallback

(PECL gearman >= 0.5.0)

GearmanClient::setCreatedCallback — Set a callback for when a task is queued

説明

public GearmanClient::setCreatedCallback(callable $function): bool

Sets a function to be called when a task is received and queued by the Gearman job server. The callback should accept a single argument, a GearmanTask object.

パラメータ

function

A function to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set application data (deprecated)

  • ≪ GearmanClient::setCreatedCallback
  • GearmanClient::setDataCallback ≫
  • PHP Manual
  • GearmanClient
  • Set application data (deprecated)

GearmanClient::setData

(PECL gearman <= 0.5.0)

GearmanClient::setData — Set application data (deprecated)

説明

public GearmanClient::setData(string $data): bool

Sets some arbitrary application data that can later be retrieved by GearmanClient::data().

注意:

This method has been replaced by GearmanCient::setContext() in the 0.6.0 release of the Gearman extension.

パラメータ

data

戻り値

Always returns true.

参考

  • GearmanClient::data() - Get the application data (deprecated)


Callback function when there is a data packet for a task

  • ≪ GearmanClient::setData
  • GearmanClient::setExceptionCallback ≫
  • PHP Manual
  • GearmanClient
  • Callback function when there is a data packet for a task

GearmanClient::setDataCallback

(PECL gearman >= 0.6.0)

GearmanClient::setDataCallback — Callback function when there is a data packet for a task

説明

public GearmanClient::setDataCallback(callable $function): bool

Sets the callback function for accepting data packets for a task. The callback function should take a single argument, a GearmanTask object.

パラメータ

function

A function or method to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set a callback for worker exceptions

  • ≪ GearmanClient::setDataCallback
  • GearmanClient::setFailCallback ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for worker exceptions

GearmanClient::setExceptionCallback

(PECL gearman >= 0.5.0)

GearmanClient::setExceptionCallback — Set a callback for worker exceptions

説明

public GearmanClient::setExceptionCallback(callable $function): bool

Specifies a function to call when a worker for a task sends an exception.

パラメータ

function

Function to call when the worker throws an exception

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set callback for job failure

  • ≪ GearmanClient::setExceptionCallback
  • GearmanClient::setOptions ≫
  • PHP Manual
  • GearmanClient
  • Set callback for job failure

GearmanClient::setFailCallback

(PECL gearman >= 0.5.0)

GearmanClient::setFailCallback — Set callback for job failure

説明

public GearmanClient::setFailCallback(callable $function): bool

Sets the callback function to be used when a task does not complete successfully. The function should accept a single argument, a GearmanTask object.

パラメータ

function

A function to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set client options

  • ≪ GearmanClient::setFailCallback
  • GearmanClient::setStatusCallback ≫
  • PHP Manual
  • GearmanClient
  • Set client options

GearmanClient::setOptions

(PECL gearman >= 0.5.0)

GearmanClient::setOptions — Set client options

説明

public GearmanClient::setOptions(int $option): bool

Sets one or more client options.

パラメータ

option

The options to be set

戻り値

Always returns true.


Set a callback for collecting task status

  • ≪ GearmanClient::setOptions
  • GearmanClient::setTimeout ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for collecting task status

GearmanClient::setStatusCallback

(PECL gearman >= 0.5.0)

GearmanClient::setStatusCallback — Set a callback for collecting task status

説明

public GearmanClient::setStatusCallback(callable $function): bool

Sets a callback function used for getting updated status information from a worker. The function should accept a single argument, a GearmanTask object.

パラメータ

function

A function to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set socket I/O activity timeout

  • ≪ GearmanClient::setStatusCallback
  • GearmanClient::setWarningCallback ≫
  • PHP Manual
  • GearmanClient
  • Set socket I/O activity timeout

GearmanClient::setTimeout

(PECL gearman >= 0.6.0)

GearmanClient::setTimeout — Set socket I/O activity timeout

説明

public GearmanClient::setTimeout(int $timeout): bool

Sets the timeout for socket I/O activity.

パラメータ

timeout

An interval of time in milliseconds

戻り値

Always returns true.


Set a callback for worker warnings

  • ≪ GearmanClient::setTimeout
  • GearmanClient::setWorkloadCallback ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for worker warnings

GearmanClient::setWarningCallback

(PECL gearman >= 0.5.0)

GearmanClient::setWarningCallback — Set a callback for worker warnings

説明

public GearmanClient::setWarningCallback(callable $function): bool

Sets a function to be called when a worker sends a warning. The callback should accept a single argument, a GearmanTask object.

パラメータ

function

A function to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWorkloadCallback() - Set a callback for accepting incremental data updates


Set a callback for accepting incremental data updates

  • ≪ GearmanClient::setWarningCallback
  • GearmanClient::timeout ≫
  • PHP Manual
  • GearmanClient
  • Set a callback for accepting incremental data updates

GearmanClient::setWorkloadCallback

(PECL gearman >= 0.5.0)

GearmanClient::setWorkloadCallback — Set a callback for accepting incremental data updates

説明

public GearmanClient::setWorkloadCallback(callable $function): bool

Sets a function to be called when a worker needs to send back data prior to job completion. A worker can do this when it needs to send updates, send partial results, or flush data during long running jobs. The callback should accept a single argument, a GearmanTask object.

パラメータ

function

A function to call

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::setDataCallback() - Callback function when there is a data packet for a task
  • GearmanClient::setCompleteCallback() - Set a function to be called on task completion
  • GearmanClient::setCreatedCallback() - Set a callback for when a task is queued
  • GearmanClient::setExceptionCallback() - Set a callback for worker exceptions
  • GearmanClient::setFailCallback() - Set callback for job failure
  • GearmanClient::setStatusCallback() - Set a callback for collecting task status
  • GearmanClient::setWarningCallback() - Set a callback for worker warnings


Get current socket I/O activity timeout value

  • ≪ GearmanClient::setWorkloadCallback
  • GearmanClient::wait ≫
  • PHP Manual
  • GearmanClient
  • Get current socket I/O activity timeout value

GearmanClient::timeout

(PECL gearman >= 0.6.0)

GearmanClient::timeout — Get current socket I/O activity timeout value

説明

public GearmanClient::timeout(): int

Returns the timeout in milliseconds to wait for I/O activity.

パラメータ

この関数にはパラメータはありません。

戻り値

Timeout in milliseconds to wait for I/O activity. A negative value means an infinite timeout.

参考

  • GearmanClient::setTimeout() - Set socket I/O activity timeout


Wait for I/O activity on all connections in a client

  • ≪ GearmanClient::timeout
  • GearmanJob ≫
  • PHP Manual
  • GearmanClient
  • Wait for I/O activity on all connections in a client

GearmanClient::wait

(PECL gearman >= 0.6.0)

GearmanClient::wait — Wait for I/O activity on all connections in a client

説明

public GearmanClient::wait(): bool

This waits for activity from any one of the connected servers.

パラメータ

この関数にはパラメータはありません。

戻り値

true on success false on an error.

参考

  • GearmanWorker::wait() - Wait for activity from one of the job servers


The GearmanJob class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

class GearmanJob {
/* メソッド */
public functionName(): false|string
public handle(): false|string
public returnCode(): int
public sendComplete(string $result): bool
public sendData(string $data): bool
public sendException(string $exception): bool
public sendFail(): bool
public sendStatus(int $numerator, int $denominator): bool
public sendWarning(string $warning): bool
public setReturn(int $gearman_return_t): bool
public unique(): false|string
public workload(): string
public workloadSize(): int
}

目次

  • GearmanJob::complete — Send the result and complete status (deprecated)
  • GearmanJob::__construct — Create a GearmanJob instance
  • GearmanJob::data — Send data for a running job (deprecated)
  • GearmanJob::exception — Send exception for running job (deprecated)
  • GearmanJob::fail — Send fail status (deprecated)
  • GearmanJob::functionName — Get function name
  • GearmanJob::handle — Get the job handle
  • GearmanJob::returnCode — Get last return code
  • GearmanJob::sendComplete — Send the result and complete status
  • GearmanJob::sendData — Send data for a running job
  • GearmanJob::sendException — Send exception for running job (exception)
  • GearmanJob::sendFail — Send fail status
  • GearmanJob::sendStatus — Send status
  • GearmanJob::sendWarning — Send a warning
  • GearmanJob::setReturn — Set a return value
  • GearmanJob::status — Send status (deprecated)
  • GearmanJob::unique — Get the unique identifier
  • GearmanJob::warning — Send a warning (deprecated)
  • GearmanJob::workload — Get workload
  • GearmanJob::workloadSize — Get size of work load


Send the result and complete status (deprecated)

  • ≪ GearmanJob
  • GearmanJob::__construct ≫
  • PHP Manual
  • GearmanJob
  • Send the result and complete status (deprecated)

GearmanJob::complete

(PECL gearman <= 0.5.0)

GearmanJob::complete — Send the result and complete status (deprecated)

説明

public GearmanJob::complete(string $result): bool

Sends result data and the complete status update for this job.

注意:

This method has been replaced by GearmanJob::sendComplete() in the 0.6.0 release of the Gearman extension.

パラメータ

result

Serialized result data.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendFail() - Send fail status
  • GearmanJob::setReturn() - Set a return value


Create a GearmanJob instance

  • ≪ GearmanJob::complete
  • GearmanJob::data ≫
  • PHP Manual
  • GearmanJob
  • Create a GearmanJob instance

GearmanJob::__construct

(PECL gearman >= 0.5.0)

GearmanJob::__construct — Create a GearmanJob instance

説明

public GearmanJob::__construct()

Creates a GearmanJob instance representing a job the worker is to complete.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanJob object.


Send data for a running job (deprecated)

  • ≪ GearmanJob::__construct
  • GearmanJob::exception ≫
  • PHP Manual
  • GearmanJob
  • Send data for a running job (deprecated)

GearmanJob::data

(PECL gearman <= 0.5.0)

GearmanJob::data — Send data for a running job (deprecated)

説明

public GearmanJob::data(string $data): bool

Sends data to the job server (and any listening clients) for this job.

注意:

This method has been replaced by GearmanJob::sendData() in the 0.6.0 release of the Gearman extension.

パラメータ

data

Arbitrary serialized data.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::workload() - Get workload
  • GearmanTask::data() - Get data returned for a task


Send exception for running job (deprecated)

  • ≪ GearmanJob::data
  • GearmanJob::fail ≫
  • PHP Manual
  • GearmanJob
  • Send exception for running job (deprecated)

GearmanJob::exception

(PECL gearman <= 0.5.0)

GearmanJob::exception — Send exception for running job (deprecated)

説明

public GearmanJob::exception(string $exception): bool

Sends the supplied exception when this job is running.

注意:

This method has been replaced by GearmanJob::sendException() in the 0.6.0 release of the Gearman extension.

パラメータ

exception

An exception description.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning


Send fail status (deprecated)

  • ≪ GearmanJob::exception
  • GearmanJob::functionName ≫
  • PHP Manual
  • GearmanJob
  • Send fail status (deprecated)

GearmanJob::fail

(PECL gearman <= 0.5.0)

GearmanJob::fail — Send fail status (deprecated)

説明

public GearmanJob::fail(): bool

Sends failure status for this job, indicating that the job failed in a known way (as opposed to failing due to a thrown exception).

注意:

This method has been replaced by GearmanJob::sendFail() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning


Get function name

  • ≪ GearmanJob::fail
  • GearmanJob::handle ≫
  • PHP Manual
  • GearmanJob
  • Get function name

GearmanJob::functionName

(PECL gearman >= 0.5.0)

GearmanJob::functionName — Get function name

説明

public GearmanJob::functionName(): false|string

Returns the function name for this job. This is the function the work will execute to perform the job.

パラメータ

この関数にはパラメータはありません。

戻り値

The name of a function, or false if the job has not yet been initialized.

参考

  • GearmanTask::function() - Get associated function name (deprecated)


Get the job handle

  • ≪ GearmanJob::functionName
  • GearmanJob::returnCode ≫
  • PHP Manual
  • GearmanJob
  • Get the job handle

GearmanJob::handle

(PECL gearman >= 0.5.0)

GearmanJob::handle — Get the job handle

説明

public GearmanJob::handle(): false|string

Returns the opaque job handle assigned by the job server.

パラメータ

この関数にはパラメータはありません。

戻り値

An opaque job handle, or false if the job has not yet been initialized.

参考

  • GearmanTask::jobHandle() - Get the job handle


Get last return code

  • ≪ GearmanJob::handle
  • GearmanJob::sendComplete ≫
  • PHP Manual
  • GearmanJob
  • Get last return code

GearmanJob::returnCode

(PECL gearman >= 0.5.0)

GearmanJob::returnCode — Get last return code

説明

public GearmanJob::returnCode(): int

Returns the last return code issued by the job server.

パラメータ

この関数にはパラメータはありません。

戻り値

A valid Gearman return code.

参考

  • GearmanTask::returnCode() - Get the last return code


Send the result and complete status

  • ≪ GearmanJob::returnCode
  • GearmanJob::sendData ≫
  • PHP Manual
  • GearmanJob
  • Send the result and complete status

GearmanJob::sendComplete

(PECL gearman >= 0.6.0)

GearmanJob::sendComplete — Send the result and complete status

説明

public GearmanJob::sendComplete(string $result): bool

Sends result data and the complete status update for this job.

パラメータ

result

Serialized result data.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendFail() - Send fail status
  • GearmanJob::setReturn() - Set a return value


Send data for a running job

  • ≪ GearmanJob::sendComplete
  • GearmanJob::sendException ≫
  • PHP Manual
  • GearmanJob
  • Send data for a running job

GearmanJob::sendData

(PECL gearman >= 0.6.0)

GearmanJob::sendData — Send data for a running job

説明

public GearmanJob::sendData(string $data): bool

Sends data to the job server (and any listening clients) for this job.

パラメータ

data

Arbitrary serialized data.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::workload() - Get workload
  • GearmanTask::data() - Get data returned for a task


Send exception for running job (exception)

  • ≪ GearmanJob::sendData
  • GearmanJob::sendFail ≫
  • PHP Manual
  • GearmanJob
  • Send exception for running job (exception)

GearmanJob::sendException

(PECL gearman >= 0.6.0)

GearmanJob::sendException — Send exception for running job (exception)

説明

public GearmanJob::sendException(string $exception): bool

Sends the supplied exception when this job is running.

パラメータ

exception

An exception description.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning


Send fail status

  • ≪ GearmanJob::sendException
  • GearmanJob::sendStatus ≫
  • PHP Manual
  • GearmanJob
  • Send fail status

GearmanJob::sendFail

(PECL gearman >= 0.6.0)

GearmanJob::sendFail — Send fail status

説明

public GearmanJob::sendFail(): bool

Sends failure status for this job, indicating that the job failed in a known way (as opposed to failing due to a thrown exception).

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::setReturn() - Set a return value
  • GearmanJob::sendStatus() - Send status
  • GearmanJob::sendWarning() - Send a warning


Send status

  • ≪ GearmanJob::sendFail
  • GearmanJob::sendWarning ≫
  • PHP Manual
  • GearmanJob
  • Send status

GearmanJob::sendStatus

(PECL gearman >= 0.6.0)

GearmanJob::sendStatus — Send status

説明

public GearmanJob::sendStatus(int $numerator, int $denominator): bool

Sends status information to the job server and any listening clients. Use this to specify what percentage of the job has been completed.

パラメータ

numerator

The numerator of the precentage completed expressed as a fraction.

denominator

The denominator of the precentage completed expressed as a fraction.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::jobStatus() - Get the status of a background job
  • GearmanTask::taskDenominator() - Get completion percentage denominator
  • GearmanTask::taskNumerator() - Get completion percentage numerator


Send a warning

  • ≪ GearmanJob::sendStatus
  • GearmanJob::setReturn ≫
  • PHP Manual
  • GearmanJob
  • Send a warning

GearmanJob::sendWarning

(PECL gearman >= 0.6.0)

GearmanJob::sendWarning — Send a warning

説明

public GearmanJob::sendWarning(string $warning): bool

Sends a warning for this job while it is running.

パラメータ

warning

A warning message.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendComplete() - Send the result and complete status
  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::sendFail() - Send fail status


Set a return value

  • ≪ GearmanJob::sendWarning
  • GearmanJob::status ≫
  • PHP Manual
  • GearmanJob
  • Set a return value

GearmanJob::setReturn

(PECL gearman >= 0.5.0)

GearmanJob::setReturn — Set a return value

説明

public GearmanJob::setReturn(int $gearman_return_t): bool

Sets the return value for this job, indicates how the job completed.

パラメータ

gearman_return_t

A valid Gearman return value.

戻り値

Description...


Send status (deprecated)

  • ≪ GearmanJob::setReturn
  • GearmanJob::unique ≫
  • PHP Manual
  • GearmanJob
  • Send status (deprecated)

GearmanJob::status

(PECL gearman <= 0.5.0)

GearmanJob::status — Send status (deprecated)

説明

public GearmanJob::status(int $numerator, int $denominator): bool

Sends status information to the job server and any listening clients. Use this to specify what percentage of the job has been completed.

注意:

This method has been replaced by GearmanJob::sendStatus() in the 0.6.0 release of the Gearman extenstion.

パラメータ

numerator

The numerator of the precentage completed expressed as a fraction.

denominator

The denominator of the precentage completed expressed as a fraction.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanClient::jobStatus() - Get the status of a background job
  • GearmanTask::taskDenominator() - Get completion percentage denominator
  • GearmanTask::taskNumerator() - Get completion percentage numerator


Get the unique identifier

  • ≪ GearmanJob::status
  • GearmanJob::warning ≫
  • PHP Manual
  • GearmanJob
  • Get the unique identifier

GearmanJob::unique

(PECL gearman >= 0.5.0)

GearmanJob::unique — Get the unique identifier

説明

public GearmanJob::unique(): false|string

Returns the unique identifier for this job. The identifier is assigned by the client.

パラメータ

この関数にはパラメータはありません。

戻り値

An opaque unique identifier, or false if the job has not yet been initialized.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanTask::uuid() - Get the unique identifier for a task (deprecated)


Send a warning (deprecated)

  • ≪ GearmanJob::unique
  • GearmanJob::workload ≫
  • PHP Manual
  • GearmanJob
  • Send a warning (deprecated)

GearmanJob::warning

(PECL gearman <= 0.5.0)

GearmanJob::warning — Send a warning (deprecated)

説明

public GearmanJob::warning(string $warning): bool

Sends a warning for this job while it is running.

注意:

This method has been replaced by GearmanJob::sendWarning() in the 0.6.0 release of the Gearman extension.

パラメータ

warning

A warning messages.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • GearmanJob::sendComplete() - Send the result and complete status
  • GearmanJob::sendException() - Send exception for running job (exception)
  • GearmanJob::sendFail() - Send fail status


Get workload

  • ≪ GearmanJob::warning
  • GearmanJob::workloadSize ≫
  • PHP Manual
  • GearmanJob
  • Get workload

GearmanJob::workload

(PECL gearman >= 0.5.0)

GearmanJob::workload — Get workload

説明

public GearmanJob::workload(): string

Returns the workload for the job. This is serialized data that is to be processed by the worker.

パラメータ

この関数にはパラメータはありません。

戻り値

Serialized data.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanJob::workloadSize() - Get size of work load


Get size of work load

  • ≪ GearmanJob::workload
  • GearmanTask ≫
  • PHP Manual
  • GearmanJob
  • Get size of work load

GearmanJob::workloadSize

(PECL gearman >= 0.5.0)

GearmanJob::workloadSize — Get size of work load

説明

public GearmanJob::workloadSize(): int

Returns the size of the job's work load (the data the worker is to process) in bytes.

パラメータ

この関数にはパラメータはありません。

戻り値

The size in bytes.

参考

  • GearmanJob::workload() - Get workload


The GearmanTask class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

class GearmanTask {
/* メソッド */
public __construct()
public data(): false|string
public dataSize(): int|false
public functionName(): false|string
public isKnown(): bool
public isRunning(): bool
public jobHandle(): false|string
public recvData(int $data_len): false|array
public returnCode(): int
public sendWorkload(string $data): int|false
public taskDenominator(): false|int
public taskNumerator(): false|int
public unique(): false|string
}

目次

  • GearmanTask::__construct — Create a GearmanTask instance
  • GearmanTask::create — Create a task (deprecated)
  • GearmanTask::data — Get data returned for a task
  • GearmanTask::dataSize — Get the size of returned data
  • GearmanTask::function — Get associated function name (deprecated)
  • GearmanTask::functionName — Get associated function name
  • GearmanTask::isKnown — Determine if task is known
  • GearmanTask::isRunning — Test whether the task is currently running
  • GearmanTask::jobHandle — Get the job handle
  • GearmanTask::recvData — Read work or result data into a buffer for a task
  • GearmanTask::returnCode — Get the last return code
  • GearmanTask::sendData — Send data for a task (deprecated)
  • GearmanTask::sendWorkload — Send data for a task
  • GearmanTask::taskDenominator — Get completion percentage denominator
  • GearmanTask::taskNumerator — Get completion percentage numerator
  • GearmanTask::unique — Get the unique identifier for a task
  • GearmanTask::uuid — Get the unique identifier for a task (deprecated)


Create a GearmanTask instance

  • ≪ GearmanTask
  • GearmanTask::create ≫
  • PHP Manual
  • GearmanTask
  • Create a GearmanTask instance

GearmanTask::__construct

(PECL gearman >= 0.5.0)

GearmanTask::__construct — Create a GearmanTask instance

説明

public GearmanTask::__construct()

Creates a GearmanTask instance representing a task to be submitted to a job server.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanTask object.


Create a task (deprecated)

  • ≪ GearmanTask::__construct
  • GearmanTask::data ≫
  • PHP Manual
  • GearmanTask
  • Create a task (deprecated)

GearmanTask::create

(PECL gearman <= 0.5.0)

GearmanTask::create — Create a task (deprecated)

説明

public GearmanTask::create(): GearmanTask|false

Returns a new GearmanTask object.

注意:

This method was removed in the 0.6.0 version of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanTask oject失敗した場合に false を返します.


Get data returned for a task

  • ≪ GearmanTask::create
  • GearmanTask::dataSize ≫
  • PHP Manual
  • GearmanTask
  • Get data returned for a task

GearmanTask::data

(PECL gearman >= 0.5.0)

GearmanTask::data — Get data returned for a task

説明

public GearmanTask::data(): false|string

Returns data being returned for a task by a worker.

パラメータ

この関数にはパラメータはありません。

戻り値

The serialized data, or false if no data is present.

参考

  • GearmanTask::dataSize() - Get the size of returned data


Get the size of returned data

  • ≪ GearmanTask::data
  • GearmanTask::function ≫
  • PHP Manual
  • GearmanTask
  • Get the size of returned data

GearmanTask::dataSize

(PECL gearman >= 0.5.0)

GearmanTask::dataSize — Get the size of returned data

説明

public GearmanTask::dataSize(): int|false

Returns the size of the data being returned for a task.

パラメータ

この関数にはパラメータはありません。

戻り値

The data size, or false if there is no data.

参考

  • GearmanTask::data() - Get data returned for a task


Get associated function name (deprecated)

  • ≪ GearmanTask::dataSize
  • GearmanTask::functionName ≫
  • PHP Manual
  • GearmanTask
  • Get associated function name (deprecated)

GearmanTask::function

(PECL gearman <= 0.5.0)

GearmanTask::function — Get associated function name (deprecated)

説明

public GearmanTask::function(): string

Returns the name of the function this task is associated with, i.e., the function the Gearman worker calls.

注意:

This method has been replaced by GearmanTask::functionName() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

戻り値

A function name.


Get associated function name

  • ≪ GearmanTask::function
  • GearmanTask::isKnown ≫
  • PHP Manual
  • GearmanTask
  • Get associated function name

GearmanTask::functionName

(PECL gearman >= 0.6.0)

GearmanTask::functionName — Get associated function name

説明

public GearmanTask::functionName(): false|string

Returns the name of the function this task is associated with, i.e., the function the Gearman worker calls.

パラメータ

この関数にはパラメータはありません。

戻り値

A function name, or false if the task has not yet been created.


Determine if task is known

  • ≪ GearmanTask::functionName
  • GearmanTask::isRunning ≫
  • PHP Manual
  • GearmanTask
  • Determine if task is known

GearmanTask::isKnown

(PECL gearman >= 0.5.0)

GearmanTask::isKnown — Determine if task is known

説明

public GearmanTask::isKnown(): bool

Gets the status information for whether or not this task is known to the job server.

パラメータ

この関数にはパラメータはありません。

戻り値

true if the task is known, false otherwise.


Test whether the task is currently running

  • ≪ GearmanTask::isKnown
  • GearmanTask::jobHandle ≫
  • PHP Manual
  • GearmanTask
  • Test whether the task is currently running

GearmanTask::isRunning

(PECL gearman >= 0.5.0)

GearmanTask::isRunning — Test whether the task is currently running

説明

public GearmanTask::isRunning(): bool

Indicates whether or not this task is currently running.

パラメータ

この関数にはパラメータはありません。

戻り値

true if the task is running, false otherwise.


Get the job handle

  • ≪ GearmanTask::isRunning
  • GearmanTask::recvData ≫
  • PHP Manual
  • GearmanTask
  • Get the job handle

GearmanTask::jobHandle

gearman_job_handle

(PECL gearman >= 0.5.0)

GearmanTask::jobHandle -- gearman_job_handle — Get the job handle

説明

public GearmanTask::jobHandle(): false|string

Returns the job handle for this task.

パラメータ

この関数にはパラメータはありません。

戻り値

The opaque job handle, or false if the task has not yet been created.

参考

  • GearmanClient::doJobHandle() - Get the job handle for the running task


Read work or result data into a buffer for a task

  • ≪ GearmanTask::jobHandle
  • GearmanTask::returnCode ≫
  • PHP Manual
  • GearmanTask
  • Read work or result data into a buffer for a task

GearmanTask::recvData

(PECL gearman >= 0.5.0)

GearmanTask::recvData — Read work or result data into a buffer for a task

説明

public GearmanTask::recvData(int $data_len): false|array

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

data_len

Length of data to be read.

戻り値

An array whose first element is the length of data read and the second is the data buffer. Returns false if the read failed.

参考

  • GearmanTask::sendData() - Send data for a task (deprecated)


Get the last return code

  • ≪ GearmanTask::recvData
  • GearmanTask::sendData ≫
  • PHP Manual
  • GearmanTask
  • Get the last return code

GearmanTask::returnCode

(PECL gearman >= 0.5.0)

GearmanTask::returnCode — Get the last return code

説明

public GearmanTask::returnCode(): int

Returns the last Gearman return code for this task.

パラメータ

この関数にはパラメータはありません。

戻り値

A valid Gearman return code.

参考

  • GearmanClient::returnCode() - Get the last Gearman return code


Send data for a task (deprecated)

  • ≪ GearmanTask::returnCode
  • GearmanTask::sendWorkload ≫
  • PHP Manual
  • GearmanTask
  • Send data for a task (deprecated)

GearmanTask::sendData

(PECL gearman <= 0.5.0)

GearmanTask::sendData — Send data for a task (deprecated)

説明

public GearmanTask::sendData(string $data): int

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

data

Data to send to the worker.

戻り値

The length of data sent, or false if the send failed.

参考

  • GearmanTask::recvData() - Read work or result data into a buffer for a task


Send data for a task

  • ≪ GearmanTask::sendData
  • GearmanTask::taskDenominator ≫
  • PHP Manual
  • GearmanTask
  • Send data for a task

GearmanTask::sendWorkload

(PECL gearman >= 0.6.0)

GearmanTask::sendWorkload — Send data for a task

説明

public GearmanTask::sendWorkload(string $data): int|false

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

data

Data to send to the worker.

戻り値

The length of data sent, or false if the send failed.

参考

  • GearmanTask::recvData() - Read work or result data into a buffer for a task


Get completion percentage denominator

  • ≪ GearmanTask::sendWorkload
  • GearmanTask::taskNumerator ≫
  • PHP Manual
  • GearmanTask
  • Get completion percentage denominator

GearmanTask::taskDenominator

(PECL gearman >= 0.5.0)

GearmanTask::taskDenominator — Get completion percentage denominator

説明

public GearmanTask::taskDenominator(): false|int

Returns the denominator of the percentage of the task that is complete expressed as a fraction.

パラメータ

この関数にはパラメータはありません。

戻り値

A number between 0 and 100, or false if cannot be determined.

参考

  • GearmanTask::taskNumerator() - Get completion percentage numerator


Get completion percentage numerator

  • ≪ GearmanTask::taskDenominator
  • GearmanTask::unique ≫
  • PHP Manual
  • GearmanTask
  • Get completion percentage numerator

GearmanTask::taskNumerator

(PECL gearman >= 0.5.0)

GearmanTask::taskNumerator — Get completion percentage numerator

説明

public GearmanTask::taskNumerator(): false|int

Returns the numerator of the percentage of the task that is complete expressed as a fraction.

パラメータ

この関数にはパラメータはありません。

戻り値

A number between 0 and 100, or false if cannot be determined.

参考

  • GearmanTask::taskDenominator() - Get completion percentage denominator


Get the unique identifier for a task

  • ≪ GearmanTask::taskNumerator
  • GearmanTask::uuid ≫
  • PHP Manual
  • GearmanTask
  • Get the unique identifier for a task

GearmanTask::unique

(PECL gearman >= 0.6.0)

GearmanTask::unique — Get the unique identifier for a task

説明

public GearmanTask::unique(): false|string

Returns the unique identifier for this task. This is assigned by the GearmanClient, as opposed to the job handle which is set by the Gearman job server.

パラメータ

この関数にはパラメータはありません。

戻り値

The unique identifier, or false if no identifier is assigned.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanClient::addTask() - Add a task to be run in parallel


Get the unique identifier for a task (deprecated)

  • ≪ GearmanTask::unique
  • GearmanWorker ≫
  • PHP Manual
  • GearmanTask
  • Get the unique identifier for a task (deprecated)

GearmanTask::uuid

(PECL gearman <= 0.5.0)

GearmanTask::uuid — Get the unique identifier for a task (deprecated)

説明

public GearmanTask::uuid(): string

Returns the unique identifier for this task. This is assigned by the GearmanClient, as opposed to the job handle which is set by the Gearman job server.

注意:

This method has been replaced by GearmanTask::unique() in the 0.6.0 release of the Gearman extension.

パラメータ

この関数にはパラメータはありません。

戻り値

The unique identifier, or false if no identifier is assigned.

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]
  • GearmanClient::addTask() - Add a task to be run in parallel


The GearmanWorker class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

class GearmanWorker {
/* メソッド */
public __construct()
public addFunction(
string $function_name,
callable $function,
mixed $context = null,
int $timeout = 0
): bool
public addOptions(int $option): true
public addServer(string $host = null, int $port = 0, bool $setupExceptionHandler = true): bool
public addServers(string $servers = null, bool $setupExceptionHandler = true): bool
public error(): string|false
public getErrno(): int
public options(): int
public register(string $function_name, int $timeout = 0): bool
public removeOptions(int $option): true
public returnCode(): int
public setId(string $id): bool
public setOptions(int $option): true
public setTimeout(int $timeout): true
public timeout(): int
public unregister(string $function_name): bool
public unregisterAll(): bool
public wait(): bool
public work(): bool
}

目次

  • GearmanWorker::addFunction — Register and add callback function
  • GearmanWorker::addOptions — Add worker options
  • GearmanWorker::addServer — Add a job server
  • GearmanWorker::addServers — Add job servers
  • GearmanWorker::clone — Create a copy of the worker
  • GearmanWorker::__construct — Create a GearmanWorker instance
  • GearmanWorker::echo — Test job server response
  • GearmanWorker::error — Get the last error encountered
  • GearmanWorker::getErrno — Get errno
  • GearmanWorker::options — Get worker options
  • GearmanWorker::register — Register a function with the job server
  • GearmanWorker::removeOptions — Remove worker options
  • GearmanWorker::returnCode — Get last Gearman return code
  • GearmanWorker::setId — Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers
  • GearmanWorker::setOptions — Set worker options
  • GearmanWorker::setTimeout — Set socket I/O activity timeout
  • GearmanWorker::timeout — Get socket I/O activity timeout
  • GearmanWorker::unregister — Unregister a function name with the job servers
  • GearmanWorker::unregisterAll — Unregister all function names with the job servers
  • GearmanWorker::wait — Wait for activity from one of the job servers
  • GearmanWorker::work — Wait for and perform jobs


Register and add callback function

  • ≪ GearmanWorker
  • GearmanWorker::addOptions ≫
  • PHP Manual
  • GearmanWorker
  • Register and add callback function

GearmanWorker::addFunction

(PECL gearman >= 0.5.0)

GearmanWorker::addFunction — Register and add callback function

説明

public GearmanWorker::addFunction(
string $function_name,
callable $function,
mixed $context = null,
int $timeout = 0
): bool

Registers a function name with the job server and specifies a callback corresponding to that function. Optionally specify extra application context data to be used when the callback is called and a timeout.

パラメータ

function_name

The name of a function to register with the job server

function

A callback that gets called when a job for the registered function name is submitted

context

A reference to arbitrary application context data that can be modified by the worker function

timeout

An interval of time in seconds

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Simple worker making use of extra application context data

<?php

# get a gearman worker
$worker= new GearmanWorker();

# add the default server (localhost)
$worker->addServer();

# define a variable to hold application data
$count= 0;

# add the "reverse" function
$worker->addFunction("reverse", "reverse_cb", $count);

# start the worker
while ($worker->work());

function reverse_cb($job, &$count)
{
$count++;
return "$count: " . strrev($job->workload());
}

?>

Running a client that submits two jobs for the reverse function would have output similar to the following:

1: olleh
2: dlrow

参考

  • GearmanClient::do() - Run a single task and return a result [deprecated]


Add worker options

  • ≪ GearmanWorker::addFunction
  • GearmanWorker::addServer ≫
  • PHP Manual
  • GearmanWorker
  • Add worker options

GearmanWorker::addOptions

(PECL gearman >= 0.6.0)

GearmanWorker::addOptions — Add worker options

説明

public GearmanWorker::addOptions(int $option): true

Adds one or more options to the options previously set.

パラメータ

option

The options to be added

戻り値

常に true を返します。

参考

  • GearmanWorker::options() - Get worker options
  • GearmanClient::setOptions() - Set client options
  • GearmanClient::removeOptions() - Remove client options


Add a job server

  • ≪ GearmanWorker::addOptions
  • GearmanWorker::addServers ≫
  • PHP Manual
  • GearmanWorker
  • Add a job server

GearmanWorker::addServer

(PECL gearman >= 0.5.0)

GearmanWorker::addServer — Add a job server

説明

public GearmanWorker::addServer(string $host = null, int $port = 0, bool $setupExceptionHandler = true): bool

Adds a job server to this worker. This goes into a list of servers than can be used to run jobs. No socket I/O happens here.

パラメータ

host

ジョブサーバーのホスト名。

port

ジョブサーバーのポート番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Add alternate Gearman servers

<?php
$worker= new GearmanWorker();
$worker->addServer("10.0.0.1");
$worker->addServer("10.0.0.2", 7003);
?>

参考

  • GearmanWorker::addServers() - Add job servers


Add job servers

  • ≪ GearmanWorker::addServer
  • GearmanWorker::clone ≫
  • PHP Manual
  • GearmanWorker
  • Add job servers

GearmanWorker::addServers

(PECL gearman >= 0.5.0)

GearmanWorker::addServers — Add job servers

説明

public GearmanWorker::addServers(string $servers = null, bool $setupExceptionHandler = true): bool

Adds one or more job servers to this worker. These go into a list of servers that can be used to run jobs. No socket I/O happens here.

パラメータ

servers

A comma separated list of job servers in the format host:port. If no port is specified, it defaults to 4730.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Add two job servers

<?php

$worker= new GearmanWorker();
$worker->addServers("10.0.0.1,10.0.0.2:7003");

?>

参考

  • GearmanWorker::addServer() - Add a job server


Create a copy of the worker

  • ≪ GearmanWorker::addServers
  • GearmanWorker::__construct ≫
  • PHP Manual
  • GearmanWorker
  • Create a copy of the worker

GearmanWorker::clone

(PECL gearman >= 0.5.0)

GearmanWorker::clone — Create a copy of the worker

説明

public GearmanWorker::clone(): void

Creates a copy of the worker.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanWorker object


Create a GearmanWorker instance

  • ≪ GearmanWorker::clone
  • GearmanWorker::echo ≫
  • PHP Manual
  • GearmanWorker
  • Create a GearmanWorker instance

GearmanWorker::__construct

(PECL gearman >= 0.5.0)

GearmanWorker::__construct — Create a GearmanWorker instance

説明

public GearmanWorker::__construct()

Creates a GearmanWorker instance representing a worker that connects to the job server and accepts tasks to run.

パラメータ

この関数にはパラメータはありません。

戻り値

A GearmanWorker object

参考

  • GearmanWorker::clone() - Create a copy of the worker


Test job server response

  • ≪ GearmanWorker::__construct
  • GearmanWorker::error ≫
  • PHP Manual
  • GearmanWorker
  • Test job server response

GearmanWorker::echo

(PECL gearman >= 0.6.0)

GearmanWorker::echo — Test job server response

説明

public GearmanWorker::echo(string $workload): bool

Sends data to all job servers to see if they echo it back. This is a test function to see if job servers are responding properly.

パラメータ

workload

Arbitrary serialized data

戻り値

Standard Gearman return value.

参考

  • GearmanClient::echo() - Send data to all job servers to see if they echo it back [deprecated]


Get the last error encountered

  • ≪ GearmanWorker::echo
  • GearmanWorker::getErrno ≫
  • PHP Manual
  • GearmanWorker
  • Get the last error encountered

GearmanWorker::error

(PECL gearman >= 0.5.0)

GearmanWorker::error — Get the last error encountered

説明

public GearmanWorker::error(): string|false

Returns an error string for the last error encountered.

パラメータ

この関数にはパラメータはありません。

戻り値

A human readable error string, or false if there is no error message available.

参考

  • GearmanWorker::getErrno() - Get errno


Get errno

  • ≪ GearmanWorker::error
  • GearmanWorker::options ≫
  • PHP Manual
  • GearmanWorker
  • Get errno

GearmanWorker::getErrno

(PECL gearman >= 0.5.0)

GearmanWorker::getErrno — Get errno

説明

public GearmanWorker::getErrno(): int

Returns the value of errno in the case of a GEARMAN_ERRNO return value.

パラメータ

この関数にはパラメータはありません。

戻り値

A valid errno.

参考

  • GearmanWorker::error() - Get the last error encountered


Get worker options

  • ≪ GearmanWorker::getErrno
  • GearmanWorker::register ≫
  • PHP Manual
  • GearmanWorker
  • Get worker options

GearmanWorker::options

(PECL gearman >= 0.6.0)

GearmanWorker::options — Get worker options

説明

public GearmanWorker::options(): int

Gets the options previously set for the worker.

パラメータ

この関数にはパラメータはありません。

戻り値

The options currently set for the worker.

参考

  • GearmanWorker::setOptions() - Set worker options


Register a function with the job server

  • ≪ GearmanWorker::options
  • GearmanWorker::removeOptions ≫
  • PHP Manual
  • GearmanWorker
  • Register a function with the job server

GearmanWorker::register

(PECL gearman >= 0.6.0)

GearmanWorker::register — Register a function with the job server

説明

public GearmanWorker::register(string $function_name, int $timeout = 0): bool

Registers a function name with the job server with an optional timeout. The timeout specifies how many seconds the server will wait before marking a job as failed. If the timeout is set to zero, there is no timeout.

パラメータ

function_name

The name of a function to register with the job server

timeout

An interval of time in seconds

戻り値

A standard Gearman return value.

参考

  • GearmanWorker::unregister() - Unregister a function name with the job servers
  • GearmanWorker::unregisterAll() - Unregister all function names with the job servers


Remove worker options

  • ≪ GearmanWorker::register
  • GearmanWorker::returnCode ≫
  • PHP Manual
  • GearmanWorker
  • Remove worker options

GearmanWorker::removeOptions

(PECL gearman >= 0.6.0)

GearmanWorker::removeOptions — Remove worker options

説明

public GearmanWorker::removeOptions(int $option): true

Removes (unsets) one or more worker options.

パラメータ

option

The options to be removed (unset)

戻り値

常に true を返します。

参考

  • GearmanWorker::options() - Get worker options
  • GearmanWorker::setOptions() - Set worker options
  • GearmanWorker::addOptions() - Add worker options


Get last Gearman return code

  • ≪ GearmanWorker::removeOptions
  • GearmanWorker::setId ≫
  • PHP Manual
  • GearmanWorker
  • Get last Gearman return code

GearmanWorker::returnCode

(PECL gearman >= 0.5.0)

GearmanWorker::returnCode — Get last Gearman return code

説明

public GearmanWorker::returnCode(): int

Returns the last Gearman return code.

パラメータ

この関数にはパラメータはありません。

戻り値

A valid Gearman return code.

参考

  • GearmanWorker::error() - Get the last error encountered
  • GearmanWorker::getErrno() - Get errno


Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers

  • ≪ GearmanWorker::returnCode
  • GearmanWorker::setOptions ≫
  • PHP Manual
  • GearmanWorker
  • Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers

GearmanWorker::setId

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

GearmanWorker::setId — Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers

説明

public GearmanWorker::setId(string $id): bool

Assigns the worker an identifier.

パラメータ

id

A string identifier.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 GearmanWorker::setId() example

Set an identifier for a simple worker.

<?php
$worker= new GearmanWorker();
$worker->setId('test');
?>

上の例の出力は、 たとえば以下のようになります。

Run the following command:
gearadmin --workers

Output:
30 ::3a3a:3361:3361:3a33%976303667 - : test


Set worker options

  • ≪ GearmanWorker::setId
  • GearmanWorker::setTimeout ≫
  • PHP Manual
  • GearmanWorker
  • Set worker options

GearmanWorker::setOptions

(PECL gearman >= 0.5.0)

GearmanWorker::setOptions — Set worker options

説明

public GearmanWorker::setOptions(int $option): true

Sets one or more options to the supplied value.

パラメータ

option

The options to be set

戻り値

常に true を返します。

参考

  • GearmanWorker::options() - Get worker options
  • GearmanWorker::addOptions() - Add worker options
  • GearmanWorker::removeOptions() - Remove worker options
  • GearmanClient::setOptions() - Set client options


Set socket I/O activity timeout

  • ≪ GearmanWorker::setOptions
  • GearmanWorker::timeout ≫
  • PHP Manual
  • GearmanWorker
  • Set socket I/O activity timeout

GearmanWorker::setTimeout

(PECL gearman >= 0.6.0)

GearmanWorker::setTimeout — Set socket I/O activity timeout

説明

public GearmanWorker::setTimeout(int $timeout): true

Sets the interval of time to wait for socket I/O activity.

パラメータ

timeout

An interval of time in milliseconds. A negative value indicates an infinite timeout.

戻り値

常に true を返します。

例

例1 A simple worker with a 5 second timeout

<?php

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server.
$gmworker->addFunction("reverse", "reverse_fn");

# Set the timeout to 5 seconds
$gmworker->setTimeout(5000);

echo "Waiting for job...\n";
while(@$gmworker->work() || $gmworker->returnCode() == GEARMAN_TIMEOUT)
{
if ($gmworker->returnCode() == GEARMAN_TIMEOUT)
{
# Normally one would want to do something useful here ...
echo "Timeout. Waiting for next job...\n";
continue;
}

if ($gmworker->returnCode() != GEARMAN_SUCCESS)
{
echo "return_code: " . $gmworker->returnCode() . "\n";
break;
}
}

echo "Done\n";

function reverse_fn($job)
{
return strrev($job->workload());
}

?>

Running the worker with no submitted jobs will generate output that looks like the following:

Starting
Waiting for job...
Timeout. Waiting for next job...
Timeout. Waiting for next job...
Timeout. Waiting for next job...

参考

  • GearmanWorker::timeout() - Get socket I/O activity timeout


Get socket I/O activity timeout

  • ≪ GearmanWorker::setTimeout
  • GearmanWorker::unregister ≫
  • PHP Manual
  • GearmanWorker
  • Get socket I/O activity timeout

GearmanWorker::timeout

(PECL gearman >= 0.6.0)

GearmanWorker::timeout — Get socket I/O activity timeout

説明

public GearmanWorker::timeout(): int

Returns the current time to wait, in milliseconds, for socket I/O activity.

パラメータ

この関数にはパラメータはありません。

戻り値

A time period is milliseconds. A negative value indicates an infinite timeout.

参考

  • GearmanWorker::setTimeout() - Set socket I/O activity timeout


Unregister a function name with the job servers

  • ≪ GearmanWorker::timeout
  • GearmanWorker::unregisterAll ≫
  • PHP Manual
  • GearmanWorker
  • Unregister a function name with the job servers

GearmanWorker::unregister

(PECL gearman >= 0.6.0)

GearmanWorker::unregister — Unregister a function name with the job servers

説明

public GearmanWorker::unregister(string $function_name): bool

Unregisters a function name with the job servers ensuring that no more jobs (for that function) are sent to this worker.

パラメータ

function_name

The name of a function to register with the job server

戻り値

A standard Gearman return value.

参考

  • GearmanWorker::register() - Register a function with the job server
  • GearmanWorker::unregisterAll() - Unregister all function names with the job servers


Unregister all function names with the job servers

  • ≪ GearmanWorker::unregister
  • GearmanWorker::wait ≫
  • PHP Manual
  • GearmanWorker
  • Unregister all function names with the job servers

GearmanWorker::unregisterAll

(PECL gearman >= 0.6.0)

GearmanWorker::unregisterAll — Unregister all function names with the job servers

説明

public GearmanWorker::unregisterAll(): bool

Unregisters all previously registered functions, ensuring that no more jobs are sent to this worker.

パラメータ

この関数にはパラメータはありません。

戻り値

A standard Gearman return value.

参考

  • GearmanWorker::register() - Register a function with the job server
  • GearmanWorker::unregister() - Unregister a function name with the job servers


Wait for activity from one of the job servers

  • ≪ GearmanWorker::unregisterAll
  • GearmanWorker::work ≫
  • PHP Manual
  • GearmanWorker
  • Wait for activity from one of the job servers

GearmanWorker::wait

(PECL gearman >= 0.6.0)

GearmanWorker::wait — Wait for activity from one of the job servers

説明

public GearmanWorker::wait(): bool

Causes the worker to wait for activity from one of the Gearman job servers when operating in non-blocking I/O mode. On failure, issues a E_WARNING with the last Gearman error encountered.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Running worker in non-blocking mode

<?php

echo "Starting\n";

# Create our worker object
$worker= new GearmanWorker();

# Make the worker non-blocking
$worker->addOptions(GEARMAN_WORKER_NON_BLOCKING);

# Add the default server (localhost, port 4730)
$worker->addServer();

# Add our reverse function
$worker->addFunction('reverse', 'reverse_fn');

# Try to grab a job
while (@$worker->work() ||
$worker->returnCode() == GEARMAN_IO_WAIT ||
$worker->returnCode() == GEARMAN_NO_JOBS)
{
if ($worker->returnCode() == GEARMAN_SUCCESS)
continue;

echo "Waiting for next job...\n";
if (!@$worker->wait())
{
if ($worker->returnCode() == GEARMAN_NO_ACTIVE_FDS)
{
# We are not connected to any servers, so wait a bit before
# trying to reconnect.
sleep(5);
continue;
}
break;
}
}

echo "Worker Error: " . $worker->error() . "\n";

function reverse_fn($job)
{
return strrev($job->workload());
}

?>

参考

  • GearmanWorker::work() - Wait for and perform jobs


Wait for and perform jobs

  • ≪ GearmanWorker::wait
  • GearmanException ≫
  • PHP Manual
  • GearmanWorker
  • Wait for and perform jobs

GearmanWorker::work

(PECL gearman >= 0.5.0)

GearmanWorker::work — Wait for and perform jobs

説明

public GearmanWorker::work(): bool

Waits for a job to be assigned and then calls the appropriate callback function. Issues an E_WARNING with the last Gearman error if the return code is not one of GEARMAN_SUCCESS, GEARMAN_IO_WAIT, or GEARMAN_WORK_FAIL.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 GearmanWorker::work() example

<?php

# create the worker
$worker = new GearmanWorker();

# add the default job server (localhost)
$worker->addServer();

# add the reverse function
$worker->addFunction("reverse", "my_reverse_function");

# start te worker listening for job submissions
while ($worker->work());

function my_reverse_function($job)
{
return strrev($job->workload());
}

?>

参考

  • GearmanWorker::addFunction() - Register and add callback function


The GearmanException class

(PECL gearman >= 0.5.0)

はじめに

クラス概要

/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


Lightweight Directory Access Protocol

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • PHP LDAP コールの使用法
  • LDAP コントロール
  • 例
    • 基本的な使用法
    • LDAP コントロール
  • LDAP 関数
    • ldap_8859_to_t61 — 8859 文字を t61 文字に変換する
    • ldap_add — LDAP ディレクトリにエントリを付加する
    • ldap_add_ext — LDAP ディレクトリにエントリを付加する
    • ldap_bind — LDAP ディレクトリにバインドする
    • ldap_bind_ext — LDAP ディレクトリにバインドする
    • ldap_close — ldap_unbind のエイリアス
    • ldap_compare — 指定した DN のエントリで見付かった属性の値を比較する
    • ldap_connect — LDAP サーバーへ接続する
    • ldap_connect_wallet — LDAP サーバに接続する
    • ldap_control_paged_result — LDAP ページネーション制御情報を送信する
    • ldap_control_paged_result_response — LDAP ページネーションクッキーを取得する
    • ldap_count_entries — 検索結果のエントリ数を数える
    • ldap_count_references — 検索結果に含まれる参照数を数える
    • ldap_delete — ディレクトリからエントリを削除する
    • ldap_delete_ext — ディレクトリからエントリを削除する
    • ldap_dn2ufn — DN をユーザーに分かりやすい名前のフォーマットに変換する
    • ldap_err2str — LDAP のエラー番号をエラーメッセージ文字列に変換する
    • ldap_errno — 直近の LDAP コマンドの LDAP エラー番号を返す
    • ldap_error — 直近の LDAP コマンドの LDAP エラーメッセージを返す
    • ldap_escape — LDAP フィルタまたは DN で使われる文字列をエスケープする
    • ldap_exop — 拡張されたオペレーションを実行する
    • ldap_exop_passwd — PASSWD 拡張オペレーションのヘルパ
    • ldap_exop_refresh — Refresh 拡張操作のヘルパ
    • ldap_exop_sync — 拡張されたオペレーションを実行する
    • ldap_exop_whoami — WHOAMI 拡張オペレーションのヘルパ
    • ldap_explode_dn — DN を構成要素ごとに分割する
    • ldap_first_attribute — 最初の属性を返す
    • ldap_first_entry — 最初の結果 ID を返す
    • ldap_first_reference — 最初のリファレンスを返す
    • ldap_free_result — 結果メモリを開放する
    • ldap_get_attributes — 検索結果エントリから属性を得る
    • ldap_get_dn — 結果エントリから DN を得る
    • ldap_get_entries — 全ての結果エントリを得る
    • ldap_get_option — 指定したオプションの現在の値を得る
    • ldap_get_values — 結果エントリから全ての値を得る
    • ldap_get_values_len — 結果エントリから全てのバイナリ値を得る
    • ldap_list — 単一階層の検索を行う
    • ldap_mod_add — 現在の属性に属性を追加する
    • ldap_mod_add_ext — 現在の属性に属性を追加する
    • ldap_mod_del — 現在の属性から属性を削除する
    • ldap_mod_del_ext — 現在の属性から属性を削除する
    • ldap_mod_replace — 属性を新規の値に置換する
    • ldap_mod_replace_ext — 属性を新規の値に置換する
    • ldap_modify — のエイリアス ldap_mod_replace
    • ldap_modify_batch — LDAP エントリの変更をまとめて実行する
    • ldap_next_attribute — 結果における次の属性を得る
    • ldap_next_entry — 次の結果エントリを得る
    • ldap_next_reference — 次のリファレンスを得る
    • ldap_parse_exop — LDAP拡張オペレーションの結果オブジェクトをパースする
    • ldap_parse_reference — 参照エントリから情報を展開する
    • ldap_parse_result — 結果から情報を展開する
    • ldap_read — エントリを読み込む
    • ldap_rename — エントリ名を修正する
    • ldap_rename_ext — エントリ名を修正する
    • ldap_sasl_bind — SASL を使用して LDAP ディレクトリにバインドする
    • ldap_search — LDAP ツリーを探索する
    • ldap_set_option — 指定したオプションの値を設定する
    • ldap_set_rebind_proc — 参照先を再バインドするためのコールバック関数を設定する
    • ldap_sort — LDAP 結果エントリをクライアント側でソートする
    • ldap_start_tls — TLS を開始する
    • ldap_t61_to_8859 — t61 文字を 8859 文字に変換する
    • ldap_unbind — LDAP ディレクトリへのバインドを解除する
  • LDAP\Connection — LDAP\Connection クラス
  • LDAP\Result — LDAP\Result クラス
  • LDAP\ResultEntry — LDAP\ResultEntry クラス


はじめに

LDAP とは Lightweight Directory Access Protocol を意味し、 "ディレクトリサーバー" にアクセスするために使用されるプロトコルです。 ディレクトリとは、 ツリー構造に情報を保持している特殊なデータベースのことです。

この概念は、ハードディスクのディレクトリ構造に似ています。 ただし、その内容は異なっており、ルートディレクトリは "世界" であり、 最初のレベルのサブディレクトリは "国" となります。ディレクトリ構造の 下位には会社や機関、場所のエントリがあります。さらに下位には、 人やおそらく道具や文書に関するディレクトリエントリもあります。

ハードディスク内のサブディレクトリにあるファイルを参照するには、 次のようにすることでしょう。

   /usr/local/myapp/docs

スラッシュが参照の各部分を区分し、左から右に解釈されます。

LDAP においてこの完全に正しいファイル参照に等価なものは "区分された名前(distinguished name)" であり、単に "dn" と表されます。 例として dn が次のようになっているとしましょう。

   cn=John Smith,ou=Accounts,o=My Company,c=US

カンマは各部分を区分し、右から左に解釈されます。この dn は 次のように解釈されます。

   country = US
   organization = My Company
   organizationalUnit = Accounts
   commonName = John Smith

ハードディスクのディレクトリ構造を管理する手法について明確な規約が ないのと同様に、ディレクトリサーバーマネージャーは、目的に適した あらゆる構造を設定することが可能です。しかし、実用的にはいくつかの 慣習があります。 利用可能なものに関する情報を持たずにデータベースを使用することが できないのと同様、ディレクトリの構造に関する情報なくして ディレクトリサーバーにアクセスするコードを書くことはできない ということが言えます。

LDAP に関する多くの情報が以下の場所にあります。

  • » Mozilla

  • » OpenLDAP Project

  • Internet Engineering Taskforce RFCs » 4510 から » 4519

Netscape SDK では、有用な » プログラマーズガイド が HTML 形式で公開されています。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • LDAP
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

LDAP サポートを有効にして PHP をコンパイルするには、 » OpenLDAP あるいは » Bind9.net から LDAP クライアント ライブラリを入手し、コンパイルしておく必要があります。 PHP 5.6 以降の場合は、OpenLDAP 2.4 以降のバージョンが必要です。


インストール手順

PHP の LDAP サポートはデフォルトで有効になっていません。 LDAP サポートを有効にして PHP をコンパイルするには、設定オプション --with-ldap[=DIR] を指定して PHP をコンパイルする必要があります。 DIR は LDAP をインストールしたディレクトリです。 SASL サポートを有効にするためには、システム上に sasl.h を用意し、 --with-ldap-sasl[=DIR] を指定する必要があります。

注意: Win32 ユーザーへの注意

この拡張モジュールを動作させるには、 Windows システムの PATH が通った場所に DLL ファイルが存在する必要があります。 FAQ の "Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?" で、その方法を説明しています。 DLL ファイルを PHP のフォルダから Windows のシステムディレクトリにコピーしても動作します (システムディレクトリは、デフォルトで PATH に含まれるからです) が、これは推奨しません。 この拡張モジュールを使用するには、以下のファイルが PATH の通った場所にある必要があります。 libeay32.dll および ssleay32.dll、 OpenSSL 1.1 以降の場合、 libcrypto-*.dll および libssl-*.dll

Oracle LDAP ライブラリを使用するには、Oracle 環境 が適切に設定されている 必要があります。


実行時設定

php.ini の設定により動作が変化します。

LDAP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
ldap.max_links | "-1" | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

ldap.max_links int

プロセスあたりの LDAP 接続の最大数。


リソース型

PHP 8.1.0 より前のバージョンでは、 ほとんどの LDAP 関数は、リソースを操作するか、 あるいはリソースを返していました。 (たとえば ldap_connect() は正の LDAP リンク ID を返し、ほとんどの LDAP 関数はそれを使用します)。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

LDAP_DEREF_NEVER (int)
エイリアスの解釈ルール - Never
LDAP_DEREF_SEARCHING (int)
エイリアスの解釈ルール - Searching
LDAP_DEREF_FINDING (int)
エイリアスの解釈ルール - Finding
LDAP_DEREF_ALWAYS (int)
エイリアスの解釈ルール - Always
LDAP_OPT_DEREF (int)
サーバーでエイリアスをたどるときの、別の規則を指定します。
LDAP_OPT_SIZELIMIT (int)

検索操作で返すことができるエントリの最大数を指定します。

注意: 実際のサイズ制限は、サーバー側で設定されている最大エントリ数にも影響を受けます。 これらふたつの設定のうち小さい方が実際のサイズ制限となります。

LDAP_OPT_TIMELIMIT (int)
検索結果を待ち続ける秒数を指定します。

注意: 実際の時間制限は、サーバー側で設定されている最大時間にも影響を受けます。 これらふたつの設定のうち小さい方が実際の時間制限となります。

LDAP_OPT_NETWORK_TIMEOUT (int)
ldap_set_option() 用のオプションで、 ネットワークのタイムアウトを設定します (PHP 5.3.0 以降で利用可能です)。
LDAP_OPT_PROTOCOL_VERSION (int)
使用する LDAP プロトコルのバージョン (V2 あるいは V3) を指定します。
LDAP_OPT_ERROR_NUMBER (int)
直近のセッションのエラー番号
LDAP_OPT_REFERRALS (int)
LDAP サーバーから返される参照を自動的にたどるかどうかを指定します。
LDAP_OPT_RESTART (int)
接続が暗黙のうちにリスタートすべきかどうかを指定します。
LDAP_OPT_HOST_NAME (int)
接続を試みるスペース区切りのホストを取得/設定します。
LDAP_OPT_ERROR_STRING (int)
LDAP_OPT_DIAGNOSTIC_MESSAGE のエイリアス
LDAP_OPT_DIAGNOSTIC_MESSAGE (int)
直近のセッションのエラーメッセージを取得します。
LDAP_OPT_MATCHED_DN (int)
接続に紐付いた DN にマッチする値を取得/設定します。
LDAP_OPT_SERVER_CONTROLS (int)
リクエストごとに送信するサーバーコントロールのデフォルトリストを指定します。
LDAP_OPT_CLIENT_CONTROLS (int)
リクエストごとに処理するクライアントコントロールのデフォルトリストを指定します。
LDAP_OPT_DEBUG_LEVEL (int)
デバッグトレース用のビットレベルを指定します。
LDAP_OPT_X_KEEPALIVE_IDLE (int)
TCP が keepalive probe を送信しはじめる前に接続がアイドルになる秒数
LDAP_OPT_X_KEEPALIVE_PROBES (int)
接続を切断する前に TCP が送信する keepalive probe の最大数を指定します。
LDAP_OPT_X_KEEPALIVE_INTERVAL (int)
個別の keepalive probe の間隔を指定します。
LDAP_OPT_X_TLS_CACERTDIR (int)
CA 証明書を含んだディレクトリのパスを指定します。
LDAP_OPT_X_TLS_CACERTFILE (int)
CA 証明書ファイルのフルパスを指定します。
LDAP_OPT_X_TLS_CERTFILE (int)
証明書ファイルのフルパスを指定します。
LDAP_OPT_X_TLS_CIPHER_SUITE (int)
許可された暗号スイートを指定します。
LDAP_OPT_X_TLS_CRLCHECK (int)
CRL の評価戦略を指定します。 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, LDAP_OPT_X_TLS_CRL_ALL のいずれかでなければなりません。

注意: このオプションは OpenSSL のみ有効です。

LDAP_OPT_X_TLS_CRLFILE (int)
CRL ファイルのフルパスを指定します。

注意: このオプションは GnuTLS のみ有効です。

LDAP_OPT_X_TLS_DHFILE (int)
Diffie-Hellman 鍵交換のパラメータを含んだファイルのフルパスを指定します。

注意: このオプションは GnuTLS や Mozilla NSS からは無視されます。

LDAP_OPT_X_TLS_KEYFILE (int)
証明書のキーファイルのフルパスを指定します。
LDAP_OPT_X_TLS_PROTOCOL_MIN (int)
プロトコルの最小バージョン。 LDAP_OPT_X_TLS_PROTOCOL_SSL2, LDAP_OPT_X_TLS_PROTOCOL_SSL3, LDAP_OPT_X_TLS_PROTOCOL_TLS1_0, LDAP_OPT_X_TLS_PROTOCOL_TLS1_1, LDAP_OPT_X_TLS_PROTOCOL_TLS1_2 のうちのいずれかです。
LDAP_OPT_X_TLS_RANDOM_FILE (int)
システムのデフォルトのrandomファイルが利用できない場合の、randomファイルを取得/設定する
LDAP_OPT_X_TLS_REQUIRE_CERT (int)
証明書のチェック戦略を指定します。 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY のうちのいずれかでなければなりません。 (PHP 7.0.0 以降で利用可能)
GSLC_SSL_NO_AUTH (int)
SSL 認証モード - 認証不要 (Oracle LDAPのみ)
GSLC_SSL_ONEWAY_AUTH (int)
SSL 認証モード - サーバー認証のみ必須 (Oracle LDAPのみ)
GSLC_SSL_TWOWAY_AUTH (int)
SSL 認証モード - サーバー認証とクライアント認証が両方必須 (Oracle LDAPのみ)
LDAP_EXOP_START_TLS (string)
拡張オペレーション定数 - Start TLS (» RFC 4511).
LDAP_EXOP_MODIFY_PASSWD (string)
拡張オペレーション定数 - Modify password (» RFC 3062).
LDAP_EXOP_REFRESH (string)
拡張オペレーション定数 - Refresh (» RFC 2589).
LDAP_EXOP_WHO_AM_I (string)
拡張オペレーション定数 - WHOAMI (» RFC 4532).
LDAP_EXOP_TURN (string)
拡張オペレーション定数 - Turn (» RFC 4531).
LDAP_CONTROL_MANAGEDSAIT (string)
コントロール定数 - Manage DSA IT (» RFC 3296). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PROXY_AUTHZ (string)
コントロール定数 - Proxied Authorization (» RFC 4370). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SUBENTRIES (string)
コントロール定数 - Subentries (» RFC 3672). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_VALUESRETURNFILTER (string)
コントロール定数 - Filter returned values (» RFC 3876). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_ASSERT (string)
コントロール定数 - Assertion (» RFC 4528). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PRE_READ (string)
コントロール定数 - Pre read (» RFC 4527). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_POST_READ (string)
コントロール定数 - Post read (» RFC 4527). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SORTREQUEST (string)
コントロール定数 - Sort request (» RFC 2891). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SORTRESPONSE (string)
コントロール定数 - Sort response (» RFC 2891). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PAGEDRESULTS (string)
コントロール定数 - Paged results (» RFC 2696). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_AUTHZID_REQUEST (string)
コントロール定数 - Authorization Identity Request (» RFC 3829). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_AUTHZID_RESPONSE (string)
コントロール定数 - Authorization Identity Response (» RFC 3829). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SYNC (string)
コントロール定数 - Content Synchronization Operation (» RFC 4533). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SYNC_STATE (string)
コントロール定数 - Content Synchronization Operation State (» RFC 4533). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_SYNC_DONE (string)
コントロール定数 - Content Synchronization Operation Done (» RFC 4533). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_DONTUSECOPY (string)
コントロール定数 - Don't Use Copy (» RFC 6171). PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PASSWORDPOLICYREQUEST (string)
コントロール定数 - パスワードポリシーのリクエスト PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_PASSWORDPOLICYRESPONSE (string)
コントロール定数 - パスワードポリシーのレスポンス PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_INCREMENTAL_VALUES (string)
コントロール定数 - Active Directory Incremental Values. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_DOMAIN_SCOPE (string)
コントロール定数 - Active Directory Domain Scope. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_PERMISSIVE_MODIFY (string)
コントロール定数 - Active Directory Permissive Modify. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_SEARCH_OPTIONS (string)
コントロール定数 - Active Directory Search Options. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_TREE_DELETE (string)
コントロール定数 - Active Directory Tree Delete. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_X_EXTENDED_DN (string)
コントロール定数 - Active Directory Extended DN. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_VLVREQUEST (string)
コントロール定数 - Virtual List View Request. PHP 7.3.0 以降で利用可能です。
LDAP_CONTROL_VLVRESPONSE (string)
コントロール定数 - Virtual List View Response. PHP 7.3.0 以降で利用可能です。


PHP LDAP コールの使用法

LDAP コールを使用する前に、以下のことを知っておいてください。

  • 使用するディレクトリサーバーの名前またはアドレス

  • サーバーの "base dn" (このサーバーがあるワールドディレクトリ の部分で、"o=My Company,c=US" のようにすることができます)

  • サーバーへのアクセスにパスワードを必要とするかどうか (多くのサーバーは "匿名バインド" に関して読みこみを 許可するが、他の処理についてはパスワードを要求します)。

アプリケーションとして作成する LDAP コールのシーケンスは、 通常、次のようなパターンに沿っています。

  ldap_connect()    // サーバーへの接続を確立
     |
  ldap_bind()       // 匿名または認証された "ログイン"
     |
  ディレクトリの検索または更新等を行い、結果を表示する
     |
  ldap_close()      // "ログアウト"


LDAP コントロール

コントロールは、リクエストを処理中にサーバーの振る舞いを変更するために LDAP リクエストと一緒に送られる特別なオブジェクトです。 サーバーがレスポンスと一緒に送ってくる、 追加の情報を提供するためのコントロールも存在します。 これは通常、リクエストに付けて送られたコントロールオブジェクトへの返答になります。

注意:

全てのコントロールが、全てのLDAPサーバーによってサポートされているとは限りません。 どのコントロールをサーバーがサポートしているのかを知るには、 フィルタ (objectClass=*) を付けて空の dn を読むことで、 root DSE に問い合わせる必要があります。

例1 ページ分けされた結果コントロールがサポートされているかをテストする

<?php

// $ds is a valid link identifier for a directory server

$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
die("This server does not support paged result control");
}

?>

PHP 7.3 以降では、全てのリクエスト関数で controls パラメータを使って コントロールを送信することができます。関数の拡張バージョンが存在する場合、 完全なレスポンスオブジェクトを取得したい場合は、それを使うべきです。 そうすれば、ldap_parse_result() を使ってレスポンスのコントロールをパースできます。

controls は、送信するコントロールごとに配列を含めなければなりません。 以下のキーが含まれます:

oid (string)
コントロールの OID。 LDAP_CONTROL_ から始まる定数を使うべきです。 LDAP の定数 を参照ください。
iscritical (bool)
コントロールを致命的なものとしてマークする場合、 サーバーがそのコントロールをサポートしていない場合、 またはサーバーが適用に失敗した場合、リクエストは失敗します。 コントロールによっては、 RFC で常に致命的だとマークされるべきだとされていることに注意してください。 デフォルトは false です。
value (mixed)
コントロールの値。詳細は以下を参照ください。

ほとんどのコントロールの値は、サーバーに BERエンコードして送られます。 あなたは値を自分で BERエンコードするか、 配列に正しいキーを渡すことでBERエンコードを行わせることができます。 配列で渡すことをサポートしているコントロールは以下のとおりです:

  • LDAP_CONTROL_PAGEDRESULTS 期待されるキーは [size] と [cookie] です。

  • LDAP_CONTROL_ASSERT 期待されるキーは filter です。

  • LDAP_CONTROL_VALUESRETURNFILTER 期待されるキーは filter です。

  • LDAP_CONTROL_PRE_READ 期待されるキーは attrs です。

  • LDAP_CONTROL_POST_READ 期待されるキーは attrs です。

  • LDAP_CONTROL_SORTREQUEST attr, [oid], [reverse] をキーとして持つ配列の配列を期待しています。

  • LDAP_CONTROL_VLVREQUEST 期待されるキーは、before, after, attrvalue|(offset, count), [context] です。

次のコントロールには、値は必要ありません:

  • LDAP_CONTROL_PASSWORDPOLICYREQUEST

  • LDAP_CONTROL_MANAGEDSAIT

  • LDAP_CONTROL_DONTUSECOPY

コントロール LDAP_CONTROL_PROXY_AUTHZ は特別です。 なぜなら値のBERエンコードが不要だからです。よって、値を直接文字列として扱うことが出来ます。

ldap_parse_result() によってコントロールがパースされる場合、 値はサポートされていれば配列に変換されます。 サポートされているのは以下です:

  • LDAP_CONTROL_PASSWORDPOLICYRESPONSE expire, grace, [error] がキーになります。

  • LDAP_CONTROL_PAGEDRESULTS size, cookie がキーになります

  • LDAP_CONTROL_PRE_READ dn と LDAP の属性名がキーになります。

  • LDAP_CONTROL_POST_READ dn と LDAP の属性名がキーになります。

  • LDAP_CONTROL_SORTRESPONSE errcode, [attribute] がキーになります。

  • LDAP_CONTROL_VLVRESPONSE target, count, errcode, context がキーになります。


  • ≪ LDAP コントロール
  • 基本的な使用法 ≫
  • PHP Manual
  • LDAP
  • 例

例

目次

  • 基本的な使用法
  • LDAP コントロール


基本的な使用法

あるディレクトリサーバーから姓が "S" から始まる全てのエントリに 関する情報を検索し、名前と電子メールアドレスで検索結果を表示します。

例1 LDAP 検索の例

<?php
// LDAP の基本シーケンスは、接続、バインド、検索、検索結果の解釈、
// 接続のクローズです。

echo "<h3>LDAP query test</h3>";
echo "Connecting ...";
$ds=ldap_connect("localhost"); // 有効な LDAP サーバーに違いない!
echo "connect result is " . $ds . "<br />";

if ($ds) {
echo "Binding ...";
$r=ldap_bind($ds); // これは "匿名" バインドで、通常は
// 読みこみのみのアクセスとなります。
echo "Bind result is " . $r . "<br />";

echo "Searching for (sn=S*) ...";
// 名前(surname)エントリを検索
$sr=ldap_search($ds, "o=My Company, c=US", "sn=S*");
echo "Search result is " . $sr . "<br />";

echo "Number of entries returned is " . ldap_count_entries($ds, $sr) . "<br />";

echo "Getting entries ...<p>";
$info = ldap_get_entries($ds, $sr);
echo "Data for " . $info["count"] . " items returned:<p>";

for ($i=0; $i<$info["count"]; $i++) {
echo "dn is: " . $info[$i]["dn"] . "<br />";
echo "first cn entry is: " . $info[$i]["cn"][0] . "<br />";
echo "first email entry is: " . $info[$i]["mail"][0] . "<br /><hr />";
}

echo "Closing connection";
ldap_close($ds);

} else {
echo "<h4>Unable to connect to LDAP server</h4>";
}
?>


LDAP コントロール

PHP >= 7.3.0 で LDAPコントロールを使う例をいくつか示します。

例1 policy(パスワードポリシー) 情報とバインドする

<?php

$user = 'cn=admin,dc=example,dc=com';
$passwd = 'adminpassword';

$ds = ldap_connect('ldap://localhost');

if ($ds) {
$r = ldap_bind_ext($ds, $user, $passwd, [['oid' => LDAP_CONTROL_PASSWORDPOLICYREQUEST]]);

if (ldap_parse_result($ds, $r, $errcode, $matcheddn, $errmsg, $referrals, $ctrls)) {
if ($errcode != 0) {
die("Error: $errmsg ($errcode)");
}
if (isset($ctrls[LDAP_CONTROL_PASSWORDPOLICYRESPONSE])) {
$value = $ctrls[LDAP_CONTROL_PASSWORDPOLICYRESPONSE]['value'];
echo "Expires in: ".$value['expire']." seconds\n";
echo "Number of auth left: ".$value['grace']."\n";
if (isset($value['error'])) {
echo "Policy error code: ".$value['error'];
}
}
}
} else {
die("Unable to connect to LDAP server");
}
?>

例2 空でない場合に限って、説明を変更する

<?php
// $link は、 LDAP 接続です

$result = ldap_mod_replace_ext(
$link,
'o=test,dc=example,dc=com',
['description' => 'New description'],
[
[
'oid' => LDAP_CONTROL_ASSERT,
'iscritical' => TRUE,
'value' => ['filter' => '(!(description=*))']
]
]
);

// ここからは、ldap_parse_result を使う
?>

例3 削除する前に、いくつか値を読み取る

<?php
// $link は、 LDAP 接続です

$result = ldap_delete_ext(
$link,
'o=test,dc=example,dc=com',
[
[
'oid' => LDAP_CONTROL_PRE_READ,
'iscritical' => TRUE,
'value' => ['attrs' => ['o', 'description']]
]
]
);

// ここからは、ldap_parse_result を使う
?>

例4 参照を削除する

<?php
// $link は、 LDAP 接続です

// コントロールが存在しない場合、参照されているノードを削除します。
// それを避けるためにも、control を critical として必ず設定してください。
$result = ldap_delete_ext(
$link,
'cn=reference,dc=example,dc=com',
[['oid' => LDAP_CONTROL_MANAGEDSAIT, 'iscritical' => TRUE]]
);

// ここからは、ldap_parse_result を使う
?>

例5 検索結果を複数ページに分割する

<?php
// $link は、 LDAP 接続です

$cookie = '';

do {
$result = ldap_search(
$link, 'dc=example,dc=base', '(cn=*)', ['cn'], 0, 0, 0, LDAP_DEREF_NEVER,
[['oid' => LDAP_CONTROL_PAGEDRESULTS, 'value' => ['size' => 2, 'cookie' => $cookie]]]
);
ldap_parse_result($link, $result, $errcode , $matcheddn , $errmsg , $referrals, $controls);
// 例を短くするために、エラー処理はテストしていません
$entries = ldap_get_entries($link, $result);
foreach ($entries as $entry) {
echo "cn: ".$entry['cn'][0]."\n";
}
if (isset($controls[LDAP_CONTROL_PAGEDRESULTS]['value']['cookie'])) {
// 最後の呼び出しから得られる cookie を次に引き渡す必要があります
$cookie = $controls[LDAP_CONTROL_PAGEDRESULTS]['value']['cookie'];
} else {
$cookie = '';
}
// cookie が空の場合、最後のページ
} while (strlen($cookie) > 0);
?>


LDAP 関数

目次

  • ldap_8859_to_t61 — 8859 文字を t61 文字に変換する
  • ldap_add — LDAP ディレクトリにエントリを付加する
  • ldap_add_ext — LDAP ディレクトリにエントリを付加する
  • ldap_bind — LDAP ディレクトリにバインドする
  • ldap_bind_ext — LDAP ディレクトリにバインドする
  • ldap_close — ldap_unbind のエイリアス
  • ldap_compare — 指定した DN のエントリで見付かった属性の値を比較する
  • ldap_connect — LDAP サーバーへ接続する
  • ldap_connect_wallet — LDAP サーバに接続する
  • ldap_control_paged_result — LDAP ページネーション制御情報を送信する
  • ldap_control_paged_result_response — LDAP ページネーションクッキーを取得する
  • ldap_count_entries — 検索結果のエントリ数を数える
  • ldap_count_references — 検索結果に含まれる参照数を数える
  • ldap_delete — ディレクトリからエントリを削除する
  • ldap_delete_ext — ディレクトリからエントリを削除する
  • ldap_dn2ufn — DN をユーザーに分かりやすい名前のフォーマットに変換する
  • ldap_err2str — LDAP のエラー番号をエラーメッセージ文字列に変換する
  • ldap_errno — 直近の LDAP コマンドの LDAP エラー番号を返す
  • ldap_error — 直近の LDAP コマンドの LDAP エラーメッセージを返す
  • ldap_escape — LDAP フィルタまたは DN で使われる文字列をエスケープする
  • ldap_exop — 拡張されたオペレーションを実行する
  • ldap_exop_passwd — PASSWD 拡張オペレーションのヘルパ
  • ldap_exop_refresh — Refresh 拡張操作のヘルパ
  • ldap_exop_sync — 拡張されたオペレーションを実行する
  • ldap_exop_whoami — WHOAMI 拡張オペレーションのヘルパ
  • ldap_explode_dn — DN を構成要素ごとに分割する
  • ldap_first_attribute — 最初の属性を返す
  • ldap_first_entry — 最初の結果 ID を返す
  • ldap_first_reference — 最初のリファレンスを返す
  • ldap_free_result — 結果メモリを開放する
  • ldap_get_attributes — 検索結果エントリから属性を得る
  • ldap_get_dn — 結果エントリから DN を得る
  • ldap_get_entries — 全ての結果エントリを得る
  • ldap_get_option — 指定したオプションの現在の値を得る
  • ldap_get_values — 結果エントリから全ての値を得る
  • ldap_get_values_len — 結果エントリから全てのバイナリ値を得る
  • ldap_list — 単一階層の検索を行う
  • ldap_mod_add — 現在の属性に属性を追加する
  • ldap_mod_add_ext — 現在の属性に属性を追加する
  • ldap_mod_del — 現在の属性から属性を削除する
  • ldap_mod_del_ext — 現在の属性から属性を削除する
  • ldap_mod_replace — 属性を新規の値に置換する
  • ldap_mod_replace_ext — 属性を新規の値に置換する
  • ldap_modify — のエイリアス ldap_mod_replace
  • ldap_modify_batch — LDAP エントリの変更をまとめて実行する
  • ldap_next_attribute — 結果における次の属性を得る
  • ldap_next_entry — 次の結果エントリを得る
  • ldap_next_reference — 次のリファレンスを得る
  • ldap_parse_exop — LDAP拡張オペレーションの結果オブジェクトをパースする
  • ldap_parse_reference — 参照エントリから情報を展開する
  • ldap_parse_result — 結果から情報を展開する
  • ldap_read — エントリを読み込む
  • ldap_rename — エントリ名を修正する
  • ldap_rename_ext — エントリ名を修正する
  • ldap_sasl_bind — SASL を使用して LDAP ディレクトリにバインドする
  • ldap_search — LDAP ツリーを探索する
  • ldap_set_option — 指定したオプションの値を設定する
  • ldap_set_rebind_proc — 参照先を再バインドするためのコールバック関数を設定する
  • ldap_sort — LDAP 結果エントリをクライアント側でソートする
  • ldap_start_tls — TLS を開始する
  • ldap_t61_to_8859 — t61 文字を 8859 文字に変換する
  • ldap_unbind — LDAP ディレクトリへのバインドを解除する


8859 文字を t61 文字に変換する

  • ≪ LDAP 関数
  • ldap_add ≫
  • PHP Manual
  • LDAP 関数
  • 8859 文字を t61 文字に変換する

ldap_8859_to_t61

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ldap_8859_to_t61 — 8859 文字を t61 文字に変換する

説明

ldap_8859_to_t61(string $value): string|false

ISO-8859 文字を t61 文字に変換します。

この関数は、 LDAPv2 サーバーとやり取りしなければならない場合に有用です。

パラメータ

value

変換するテキスト。

戻り値

value を t61 に変換したものを返します。 失敗した場合に false を返します

参考

  • ldap_t61_to_8859() - t61 文字を 8859 文字に変換する


LDAP ディレクトリにエントリを付加する

  • ≪ ldap_8859_to_t61
  • ldap_add_ext ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにエントリを付加する

ldap_add

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_add — LDAP ディレクトリにエントリを付加する

説明

ldap_add(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): bool

エントリを LDAP ディレクトリに追加します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

entry

そのエントリに関する情報を表す配列。 エントリの値は、個々の属性によりインデックスが作成されています。 ある属性に関して複数の値がある場合は、0 から始まる整数で 添字が作成されます。

<?php
$entry["attribute1"] = "value";
$entry["attribute2"][0] = "value1";
$entry["attribute2"][1] = "value2";
?>

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

例

例1 認証型バインドの例

<?php
$ds = ldap_connect("localhost"); // LDAP サーバーはこのホストであると仮定

if ($ds) {
// 更新アクセスを行うために適当な dn でバインドする
$r = ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");

// データを準備する
$info["cn"] = "John Jones";
$info["sn"] = "Jones";
$info["objectclass"] = "person";

// データをディレクトリに追加
$r = ldap_add($ds, "cn=John Jones, o=My Company, c=US", $info);

ldap_close($ds);
} else {
echo "LDAP サーバーに接続できません";
}
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_add_ext() - LDAP ディレクトリにエントリを付加する
  • ldap_delete() - ディレクトリからエントリを削除する


LDAP ディレクトリにエントリを付加する

  • ≪ ldap_add
  • ldap_bind ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにエントリを付加する

ldap_add_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_add_ext — LDAP ディレクトリにエントリを付加する

説明

ldap_add_ext(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): LDAP\Result|false

ldap_add() と同じですが、 ldap_parse_result() を使ってパースされた結果を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_add() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_add() - LDAP ディレクトリにエントリを付加する
  • ldap_parse_result() - 結果から情報を展開する


LDAP ディレクトリにバインドする

  • ≪ ldap_add_ext
  • ldap_bind_ext ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにバインドする

ldap_bind

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_bind — LDAP ディレクトリにバインドする

説明

ldap_bind(LDAP\Connection $ldap, ?string $dn = null, #[\SensitiveParameter] ?string $password = null): bool

指定した RDN およびパスワードを用いて LDAP ディレクトリにバインドします。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

password

password を省略または空にした場合は匿名バインドを試みます。 匿名バインドのため、dn も空のままにできます。 これは、https://tools.ietf.org/html/rfc2251#section-4.2.2 で定義されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

例

例1 LDAP バインドの使用

<?php

// ldap バインドを使用する
$ldaprdn = 'uname'; // ldap rdn あるいは dn
$ldappass = 'password'; // パスワード

// ldap サーバーに接続する
$ldapconn = ldap_connect("ldap.example.com")
or die("Could not connect to LDAP server.");

if ($ldapconn) {

// ldap サーバーにバインドする
$ldapbind = ldap_bind($ldapconn, $ldaprdn, $ldappass);

// バインド結果を検証する
if ($ldapbind) {
echo "LDAP bind successful...";
} else {
echo "LDAP bind failed...";
}

}

?>

例2 LDAP 匿名バインドの使用

<?php

// ldap 匿名バインドを使用する

// ldap サーバーに接続する
$ldapconn = ldap_connect("ldap.example.com")
or die("Could not connect to LDAP server.");

if ($ldapconn) {

// 匿名でバインドする
$ldapbind = ldap_bind($ldapconn);

if ($ldapbind) {
echo "LDAP bind anonymous successful...";
} else {
echo "LDAP bind anonymous failed...";
}

}

?>

参考

  • ldap_unbind() - LDAP ディレクトリへのバインドを解除する


LDAP ディレクトリにバインドする

  • ≪ ldap_bind
  • ldap_close ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリにバインドする

ldap_bind_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_bind_ext — LDAP ディレクトリにバインドする

説明

ldap_bind_ext(
LDAP\Connection $ldap,
?string $dn = null,
#[\SensitiveParameter] ?string $password = null,
?array $controls = null
): LDAP\Result|false

ldap_bind() と同じですが、 ldap_parse_result() を使ってパースされた結果を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_bind() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。

参考

  • ldap_bind() - LDAP ディレクトリにバインドする
  • ldap_parse_result() - 結果から情報を展開する


ldap_unbind のエイリアス

  • ≪ ldap_bind_ext
  • ldap_compare ≫
  • PHP Manual
  • LDAP 関数
  • ldap_unbind のエイリアス

ldap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_close — ldap_unbind() のエイリアス

説明

この関数は次の関数のエイリアスです。 ldap_unbind().


指定した DN のエントリで見付かった属性の値を比較する

  • ≪ ldap_close
  • ldap_connect ≫
  • PHP Manual
  • LDAP 関数
  • 指定した DN のエントリで見付かった属性の値を比較する

ldap_compare

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ldap_compare — 指定した DN のエントリで見付かった属性の値を比較する

説明

ldap_compare(
LDAP\Connection $ldap,
string $dn,
string $attribute,
string $value,
?array $controls = null
): bool|int

属性 attribute の値 value を、指定した LDAP ディレクトリエントリの同じ属性の値と比較します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

attribute

属性の名前。

value

比較する値。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

value がマッチする場合に true、その他の場合に false、エラーの場合に -1 を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

例

次の例は、指定したパスワードが DN の指定したエントリで定義された ものと一致するかどうかをチェックする方法を示しています。

例1 パスワード確認の例

<?php

$ds=ldap_connect("localhost"); // LDAP サーバーが同一ホストであると仮定

if ($ds) {

// バインド
if (ldap_bind($ds)) {

// データを準備
$dn = "cn=Matti Meikku, ou=My Unit, o=My Company, c=FI";
$value = "secretpassword";
$attr = "password";

// 値を比較
$r=ldap_compare($ds, $dn, $attr, $value);

if ($r === -1) {
echo "Error: " . ldap_error($ds);
} elseif ($r === true) {
echo "Password correct.";
} elseif ($r === false) {
echo "Wrong guess! Password incorrect.";
}

} else {
echo "Unable to bind to LDAP server.";
}

ldap_close($ds);

} else {
echo "Unable to connect to LDAP server.";
}
?>

注意

警告

ldap_compare() では BINARY 値を比較することはできません!


LDAP サーバーへ接続する

  • ≪ ldap_compare
  • ldap_connect_wallet ≫
  • PHP Manual
  • LDAP 関数
  • LDAP サーバーへ接続する

ldap_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_connect — LDAP サーバーへ接続する

説明

ldap_connect(?string $uri = null): LDAP\Connection|false
警告

PHP 8.3.0 以降では、次の シグネチャは推奨されなくなりました。

ldap_connect(?string $host = null, int $port = 389): LDAP\Connection|false

LDAP\Connection クラスのインスタンスを作成し、指定した uri が妥当であるかどうかを調べます。

注意: 注意: この関数は、接続を確立するするわけでは ありません。 指定したパラメータが妥当であり、必要に応じて接続をオープンできるかどうかを調べるだけです。

パラメータ

uri

完全な LDAP URI を指定します。ldap://hostname:port 形式、あるいは SSL を用いる場合は ldaps://hostname:port 形式が使えます。

複数の LDAP URI を指定する場合は、間にスペースをはさんだひとつの文字列とします。

hostname:port 形式は LDAP URI としてサポートされないことに注意しましょう。 スキーマが抜けているからです。

host

接続するホスト名

port

接続するポート。

戻り値

LDAP URI が妥当であると思われる場合には LDAP\Connection クラスのインスタンスを返します。 これは単なる構文チェックであり、実際にサーバーに接続するわけではありません。 構文チェックに失敗した場合は false を返します。 失敗していない場合は、ldap_connect() は常に LDAP\Connection クラスのインスタンスを返しますが、 実際には接続せずにパラメータの初期化だけを行います。 実際に接続するのは次に ldap_* 関数がコールされた際で、これは 通常は ldap_bind() です。

引数が指定されない場合、既に開かれている接続を示す LDAP\Connection クラスのインスタンスを返します。

変更履歴

バージョン | 説明
8.3.0 | ldap_connect() に、 hostname と port を別々に渡してコールすることは、推奨されなくなりました。
8.1.0 | LDAP\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 リソース を返していました。

例

例1 LDAP サーバーに接続する例

<?php

// LDAP 変数
$ldapuri = "ldap://ldap.example.com:389"; // ldap-uri

// LDAP に接続します
$ldapconn = ldap_connect($ldapuri)
or die("That LDAP-URI was not parseable");

?>

例2 LDAP サーバーへのセキュアな接続の例

<?php

// サーバー証明書が証明するホストであることを
// 確認する
$ldaphost = "ldaps://ldap.example.com/";

// LDAP に接続します
$ldapconn = ldap_connect($ldaphost)
or die("That LDAP-URI was not parseable");

?>

参考

  • ldap_bind() - LDAP ディレクトリにバインドする


LDAP サーバに接続する

  • ≪ ldap_connect
  • ldap_control_paged_result ≫
  • PHP Manual
  • LDAP 関数
  • LDAP サーバに接続する

ldap_connect_wallet

(PHP 8 >= 8.3.0)

ldap_connect_wallet — LDAP サーバに接続する

説明

ldap_connect_wallet(
?string $uri = null,
string $wallet,
#[\SensitiveParameter] string $password,
int $auth_mode = GSLC_SSL_NO_AUTH
): LDAP\Connection|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

uri

wallet

password

auth_mode

戻り値

参考

  • ldap_connect() - LDAP サーバーへ接続する


LDAP ページネーション制御情報を送信する

  • ≪ ldap_connect_wallet
  • ldap_control_paged_result_response ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ページネーション制御情報を送信する

ldap_control_paged_result

(PHP 5 >= 5.4.0, PHP 7)

ldap_control_paged_result — LDAP ページネーション制御情報を送信する

警告

この関数は PHP 7.4.0 以降で 推奨されなくなり、PHP 8.0.0 以降は 削除されています。 代替として、ldap_search() 関数の controls 引数を使うべきです。 詳細は LDAP コントロール も参照して下さい。

説明

ldap_control_paged_result(
resource $link,
int $pagesize,
bool $iscritical = false,
string $cookie = ""
): bool

LDAP ページネーションを有効にするため、ページネーション制御情報 (ページサイズやクッキーなど) を送信します。

パラメータ

link

ldap_connect() が返す LDAP リソース。

pagesize

ページあたりのエントリ数。

iscritical

ページネーションを必須にするかどうか。 true にすると、もしサーバーがページネーションに対応していなければ 検索結果を返しません。

cookie

サーバーから送られる opaque structure (ldap_control_paged_result_response())。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は削除されました。
7.4.0 | この関数は非推奨になりました。

例

次の例は、検索結果の最初のページを取得します。 ページあたり 1 エントリになります。

例1 LDAP ページネーション

<?php
// $ds is a valid link identifier (see ldap_connect)
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);

$dn = 'ou=example,dc=org';
$filter = '(|(sn=Doe*)(givenname=John*))';
$justthese = array('ou', 'sn', 'givenname', 'mail');

// enable pagination with a page size of 1.
ldap_control_paged_result($ds, 1);

$sr = ldap_search($ds, $dn, $filter, $justthese);

$info = ldap_get_entries($ds, $sr);

echo $info['count'] . ' entries returned' . PHP_EOL;

この例は、すべての結果を取得します。 ページあたり 100 エントリとなります。

例2 LDAP ページネーション

<?php
// $ds is a valid link identifier (see ldap_connect)
ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3);

$dn = 'ou=example,dc=org';
$filter = '(|(sn=Doe*)(givenname=John*))';
$justthese = array('ou', 'sn', 'givenname', 'mail');

// enable pagination with a page size of 100.
$pageSize = 100;

$cookie = '';
do {
ldap_control_paged_result($ds, $pageSize, true, $cookie);

$result = ldap_search($ds, $dn, $filter, $justthese);
$entries = ldap_get_entries($ds, $result);

foreach ($entries as $e) {
echo $e['dn'] . PHP_EOL;
}

ldap_control_paged_result_response($ds, $result, $cookie);

} while($cookie !== null && $cookie != '');

注意

注意:

ページネーション制御は、LDAPv3 プロトコルの機能です。

参考

  • ldap_control_paged_result_response() - LDAP ページネーションクッキーを取得する
  • » RFC2696 : LDAP Control Extension for Simple Paged Results Manipulation


LDAP ページネーションクッキーを取得する

  • ≪ ldap_control_paged_result
  • ldap_count_entries ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ページネーションクッキーを取得する

ldap_control_paged_result_response

(PHP 5 >= 5.4.0, PHP 7)

ldap_control_paged_result_response — LDAP ページネーションクッキーを取得する

警告

この関数は PHP 7.4.0 以降で 推奨されなくなり、PHP 8.0.0 以降は 削除されています。 代替として、ldap_search() 関数の controls 引数を使うべきです。 詳細は LDAP コントロール も参照して下さい。

説明

ldap_control_paged_result_response(
resource $link,
resource $result,
string &$cookie = ?,
int &$estimated = ?
): bool

サーバーから送られるページネーション情報を取得します。

パラメータ

link

ldap_connect() が返す LDAP リソース。

result

cookie

サーバーから送られる opaque structure。

estimated

取得するエントリ数の予測。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は削除されました。
7.4.0 | この関数は非推奨になりました。

参考

  • ldap_control_paged_result() - LDAP ページネーション制御情報を送信する
  • » RFC2696 : LDAP Control Extension for Simple Paged Results Manipulation


検索結果のエントリ数を数える

  • ≪ ldap_control_paged_result_response
  • ldap_count_references ≫
  • PHP Manual
  • LDAP 関数
  • 検索結果のエントリ数を数える

ldap_count_entries

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_count_entries — 検索結果のエントリ数を数える

説明

ldap_count_entries(LDAP\Connection $ldap, LDAP\Result $result): int

直前の検索結果として保存されたエントリの数を返します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

戻り値

結果のエントリ数を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。

例

例1 ldap_count_entries() の例

結果のエントリ数を取得します。

// $ds は、有効な LDAP\Connection のインスタンスです

$dn = 'ou=example,dc=org';
$filter = '(|(sn=Doe*)(givenname=John*))';
$justthese = array('ou', 'sn', 'givenname', 'mail');

$sr = ldap_search($ds, $dn, $filter, $justthese);

var_dump(ldap_count_entries($ds, $sr));

上の例の出力は、 たとえば以下のようになります。

int(1)


検索結果に含まれる参照数を数える

  • ≪ ldap_count_entries
  • ldap_delete ≫
  • PHP Manual
  • LDAP 関数
  • 検索結果に含まれる参照数を数える

ldap_count_references

(PHP 8)

ldap_count_references — 検索結果に含まれる参照数を数える

説明

ldap_count_references(LDAP\Connection $ldap, LDAP\Result $result): int

検索結果に含まれる参照数を数えます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

戻り値

検索結果に含まれる参照数を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。

参考

  • ldap_connect() - LDAP サーバーへ接続する


ディレクトリからエントリを削除する

  • ≪ ldap_count_references
  • ldap_delete_ext ≫
  • PHP Manual
  • LDAP 関数
  • ディレクトリからエントリを削除する

ldap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_delete — ディレクトリからエントリを削除する

説明

ldap_delete(LDAP\Connection $ldap, string $dn, ?array $controls = null): bool

指定したエントリを LDAP ディレクトリから削除します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

参考

  • ldap_delete_ext() - ディレクトリからエントリを削除する
  • ldap_add() - LDAP ディレクトリにエントリを付加する


ディレクトリからエントリを削除する

  • ≪ ldap_delete
  • ldap_dn2ufn ≫
  • PHP Manual
  • LDAP 関数
  • ディレクトリからエントリを削除する

ldap_delete_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_delete_ext — ディレクトリからエントリを削除する

説明

ldap_delete_ext(LDAP\Connection $ldap, string $dn, ?array $controls = null): LDAP\Result|false

ldap_delete() と同じですが、 ldap_parse_result() を使ってパースされた結果を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_delete() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。

参考

  • ldap_delete() - ディレクトリからエントリを削除する
  • ldap_parse_result() - 結果から情報を展開する


DN をユーザーに分かりやすい名前のフォーマットに変換する

  • ≪ ldap_delete_ext
  • ldap_err2str ≫
  • PHP Manual
  • LDAP 関数
  • DN をユーザーに分かりやすい名前のフォーマットに変換する

ldap_dn2ufn

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_dn2ufn — DN をユーザーに分かりやすい名前のフォーマットに変換する

説明

ldap_dn2ufn(string $dn): string|false

指定した dn をよりユーザーにわかりやすい形式にするため、 型名を取り除きます。

パラメータ

dn

LDAP エンティティの識別名。

戻り値

ユーザーにわかりやすい形式の名前を返します。 失敗した場合に false を返します


LDAP のエラー番号をエラーメッセージ文字列に変換する

  • ≪ ldap_dn2ufn
  • ldap_errno ≫
  • PHP Manual
  • LDAP 関数
  • LDAP のエラー番号をエラーメッセージ文字列に変換する

ldap_err2str

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_err2str — LDAP のエラー番号をエラーメッセージ文字列に変換する

説明

ldap_err2str(int $errno): string

この関数は、エラー番号 errno が意味する エラーメッセージ文字列を返します。LDAP errno 番号は標準化されていますが、 異なったライブラリでは、異なる（あるいはローカライズされた）エラーメッセージ が返されます。エラーメッセージの内容をチェックするのではなく、 必ずエラー番号をチェックするようにしてください。

パラメータ

errno

エラー番号。

戻り値

エラーメッセージを表す文字列を返します。

例

例1 全ての LDAP エラーメッセージに番号をふる

<?php
for ($i=0; $i<100; $i++) {
printf("Error $i: %s<br />\n", ldap_err2str($i));
}
?>

参考

  • ldap_errno() - 直近の LDAP コマンドの LDAP エラー番号を返す
  • ldap_error() - 直近の LDAP コマンドの LDAP エラーメッセージを返す


直近の LDAP コマンドの LDAP エラー番号を返す

  • ≪ ldap_err2str
  • ldap_error ≫
  • PHP Manual
  • LDAP 関数
  • 直近の LDAP コマンドの LDAP エラー番号を返す

ldap_errno

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_errno — 直近の LDAP コマンドの LDAP エラー番号を返す

説明

ldap_errno(LDAP\Connection $ldap): int

直近の LDAP コマンドにより返された、標準化されたエラー番号を返します。 この番号は、ldap_err2str() を用いてエラーメッセージ 文字列に変換することができます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

戻り値

このリンクに関する直近の LDAP コマンドの LDAP エラー番号を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

例

php.ini で警告レベルを十分に下げるか、警告出力を抑制するために LDAP コマンドに @ 文字をつけない限り、発生したエラーは、HTML 出力 にも表示されます。

例1 エラーを生成し、取得する

<?php
// この例には、エラーがあり、これを取得します。
$ld = ldap_connect("localhost");
$bind = ldap_bind($ld);
// フィルタ式に構文エラーがあります（errno 87）。
// 動作させるには、"objectclass=*" とする必要があります。
$res = @ldap_search($ld, "o=Myorg, c=DE", "objectclass");
if (!$res) {
echo "LDAP-Errno: " . ldap_errno($ld) . "<br />\n";
echo "LDAP-Error: " . ldap_error($ld) . "<br />\n";
die("Argh!<br />\n");
}
$info = ldap_get_entries($ld, $res);
echo $info["count"] . " matching entries.<br />\n";
?>

参考

  • ldap_err2str() - LDAP のエラー番号をエラーメッセージ文字列に変換する
  • ldap_error() - 直近の LDAP コマンドの LDAP エラーメッセージを返す


直近の LDAP コマンドの LDAP エラーメッセージを返す

  • ≪ ldap_errno
  • ldap_escape ≫
  • PHP Manual
  • LDAP 関数
  • 直近の LDAP コマンドの LDAP エラーメッセージを返す

ldap_error

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_error — 直近の LDAP コマンドの LDAP エラーメッセージを返す

説明

ldap_error(LDAP\Connection $ldap): string

指定した ldap に関して、 直近の LDAP コマンドにより生成されたエラーを表すエラーメッセージ文字列を返します。 LDAP errno 番号は標準化されていますが、ライブラリによって異なる （あるいはローカライズされた）エラーメッセージを返します。 エラーメッセージの内容をチェックするのではなく、 必ずエラー番号をチェックするようにしてください。

php.ini で警告レベルを十分に下げるか、 警告出力を抑制するために LDAP コマンドの前に @ 文字をつけない限り、発生したエラーは HTML 出力にも表示されます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

戻り値

エラーメッセージ文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

参考

  • ldap_err2str() - LDAP のエラー番号をエラーメッセージ文字列に変換する
  • ldap_errno() - 直近の LDAP コマンドの LDAP エラー番号を返す


LDAP フィルタまたは DN で使われる文字列をエスケープする

  • ≪ ldap_error
  • ldap_exop ≫
  • PHP Manual
  • LDAP 関数
  • LDAP フィルタまたは DN で使われる文字列をエスケープする

ldap_escape

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

ldap_escape — LDAP フィルタまたは DN で使われる文字列をエスケープする

説明

ldap_escape(string $value, string $ignore = "", int $flags = 0): string

flags で指示されたコンテキストで使う value をエスケープします。

パラメータ

value

エスケープする値

ignore

エスケープする際に無視する文字

flags

エスケープされた文字列が使われるコンテクスト: LDAP_ESCAPE_FILTER は、 ldap_search(), で使われるフィルタ。 LDAP_ESCAPE_DN は DN の場合に使います。 フラグが渡されなかった場合、全ての文字がエスケープされます。

戻り値

エスケープされた値を返します。

例

LDAP フィルタを組み立てる際、 LDAP_ESCAPE_FILTER を指定して ldap_escape を使うべきです。

例1 Eメールアドレスを検索する

<?php
// $ds is a valid LDAP\Connection instance for a directory server

// $mail is an email address provided by the user in a form

$base = "o=My Company, c=US";
$filter = "(mail=".ldap_escape($mail, "", LDAP_ESCAPE_FILTER).")";

$sr = ldap_search($ds, $base, $filter, array("sn", "givenname", "mail"));

$info = ldap_get_entries($ds, $sr);

echo $info["count"]." entries returned\n";
?>


拡張されたオペレーションを実行する

  • ≪ ldap_escape
  • ldap_exop_passwd ≫
  • PHP Manual
  • LDAP 関数
  • 拡張されたオペレーションを実行する

ldap_exop

(PHP 7 >= 7.2.0, PHP 8)

ldap_exop — 拡張されたオペレーションを実行する

説明

ldap_exop(
LDAP\Connection $ldap,
string $request_oid,
string $request_data = null,
array $controls = null,
string &$response_data = ?,
string &$response_oid = ?
): mixed

指定された ldap で オペレーションの OID を request_oid で指定し、 データを request_data で指定して拡張されたオペレーションを実行します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

request_oid

拡張オペレーションリクエストのOID。 LDAP_EXOP_START_TLS, LDAP_EXOP_MODIFY_PASSWD, LDAP_EXOP_REFRESH, LDAP_EXOP_WHO_AM_I, LDAP_EXOP_TURN のいずれか、 または送信したい操作のOIDを示す文字列。

request_data

拡張オペレーションリクエストのデータ。 LDAP_EXOP_WHO_AM_I のように、 操作によってはNULLで問題ない場合もありますし、 BERエンコードが必要な場合もあります。

controls

リクエストと一緒に送信する LDAP コントロール の配列

response_data

この値を指定すると、拡張オペレーションレスポンスの値で埋められます。 指定しなかった場合に後でこのデータを取得するには、 結果オブジェクトに対して ldap_parse_exop を使います。

response_oid

この値を指定すると、レスポンスのOIDで埋められます。 これは通常、リクエストのOIDと等しい値です。

戻り値

response_data を指定した場合、成功時に true を返し、エラー時に false を返します。 response_data を指定しなかった場合、結果識別子を返し、 エラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
7.3.0 | controls のサポートが追加されました。

例

例1 Whoami 拡張オペレーション

<?php
$ds = ldap_connect("localhost"); // assuming the LDAP server is on this host

if ($ds) {
// bind with appropriate dn to give update access
$bind = ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");
if (!$bind) {
echo "Unable to bind to LDAP server";
exit;
}

// Call WHOAMI EXOP
$r = ldap_exop($ds, LDAP_EXOP_WHO_AM_I);

// Parse the result object
ldap_parse_exop($ds, $r, $retdata);
// Output: string(31) "dn:cn=root, o=My Company, c=US"
var_dump($retdata);

// Same thing using $response_data parameter
$success = ldap_exop($ds, LDAP_EXOP_WHO_AM_I, NULL, NULL, $retdata, $retoid);
if ($success) {
var_dump($retdata);
}

ldap_close($ds);
} else {
echo "Unable to connect to LDAP server";
}
?>

参考

  • ldap_parse_result() - 結果から情報を展開する
  • ldap_parse_exop() - LDAP拡張オペレーションの結果オブジェクトをパースする
  • ldap_exop_whoami() - WHOAMI 拡張オペレーションのヘルパ
  • ldap_exop_refresh() - Refresh 拡張操作のヘルパ
  • ldap_exop_passwd() - PASSWD 拡張オペレーションのヘルパ


PASSWD 拡張オペレーションのヘルパ

  • ≪ ldap_exop
  • ldap_exop_refresh ≫
  • PHP Manual
  • LDAP 関数
  • PASSWD 拡張オペレーションのヘルパ

ldap_exop_passwd

(PHP 7 >= 7.2.0, PHP 8)

ldap_exop_passwd — PASSWD 拡張オペレーションのヘルパ

説明

ldap_exop_passwd(
LDAP\Connection $ldap,
string $user = "",
#[\SensitiveParameter] string $old_password = "",
#[\SensitiveParameter] string $new_password = "",
array &$controls = null
): string|bool

PASSWD 拡張オペレーションを実行します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

user

パスワードを変更するユーザーの dn

old_password

このユーザーの古いパスワード。 サーバーの設定によっては省略可能です。

new_password

このユーザーの新しいパスワード。 生成されたパスワードがある場合は、空にするか省略できます。

controls

指定された場合は、パスワードポリシーをリクエストするコントロールがリクエストと一緒に送信されます。 その場合、この値は リクエストと一緒に送信する LDAP コントロール の配列 で埋められます。

戻り値

new_password が空だったり省略されたりした場合は、 生成されたパスワードが返されます。 そうでなければ、成功時に true 、失敗時に false が返ります。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

例

例1 PASSWD 拡張オペレーション

<?php
$ds = ldap_connect("localhost"); // assuming the LDAP server is on this host

if ($ds) {
// bind with appropriate dn to give update access
$bind = ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");
if (!$bind) {
echo "Unable to bind to LDAP server";
exit;
}

// use PASSWD EXOP to change the user password for a generated one
$genpw = ldap_exop_passwd($ds, "cn=root, o=My Company, c=US", "secret");
if ($genpw) {
// use the generated password to bind
$bind = ldap_bind($ds, "cn=root, o=My Company, c=US", $genpw);
}

// set the password back to "secret"
ldap_exop_passwd($ds, "cn=root, o=My Company, c=US", $genpw, "secret");

ldap_close($ds);
} else {
echo "Unable to connect to LDAP server";
}
?>

参考

  • ldap_exop() - 拡張されたオペレーションを実行する
  • ldap_parse_exop() - LDAP拡張オペレーションの結果オブジェクトをパースする


Refresh 拡張操作のヘルパ

  • ≪ ldap_exop_passwd
  • ldap_exop_sync ≫
  • PHP Manual
  • LDAP 関数
  • Refresh 拡張操作のヘルパ

ldap_exop_refresh

(PHP 7 >= 7.3.0, PHP 8)

ldap_exop_refresh — Refresh 拡張操作のヘルパ

説明

ldap_exop_refresh(LDAP\Connection $ldap, string $dn, int $ttl): int|false

Refresh 拡張オペレーションを実行し、結果を返します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

リフレッシュするエンティティの識別名。

ttl

自動的に削除される前にエントリがディレクトリに存在する時間を秒単位 (1 から 31557600 の間)で指定します。

戻り値

RFC から: responseTtl フィールドは、そのエントリのttlとしてサーバーが選んだ時間です。 この値は、クライアントがリクエストした値よりも小さい値であってはいけませんが、 大きいのは構いません。 しかし、サーバーが比較的正確にディレクトリを維持できるようにするために、 かつクライアントが動的な拡張を悪用できないようにするために、 サーバーはクライアントがリクエストした ttl の値を 86400秒 (1日) まで短くすることを許可されています。 エラー時には false が返されます。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

参考

  • ldap_exop() - 拡張されたオペレーションを実行する


拡張されたオペレーションを実行する

  • ≪ ldap_exop_refresh
  • ldap_exop_whoami ≫
  • PHP Manual
  • LDAP 関数
  • 拡張されたオペレーションを実行する

ldap_exop_sync

(PHP 8 >= 8.3.0)

ldap_exop_sync — 拡張されたオペレーションを実行する

説明

ldap_exop_sync(
LDAP\Connection $ldap,
string $request_oid,
?string $request_data = null,
?array $controls = null,
string &$response_data = null,
string &$response_oid = null
): LDAP\Result|bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

request_oid

request_data

controls

response_data

response_oid

戻り値

参考

  • ldap_exop() - 拡張されたオペレーションを実行する


WHOAMI 拡張オペレーションのヘルパ

  • ≪ ldap_exop_sync
  • ldap_explode_dn ≫
  • PHP Manual
  • LDAP 関数
  • WHOAMI 拡張オペレーションのヘルパ

ldap_exop_whoami

(PHP 7 >= 7.2.0, PHP 8)

ldap_exop_whoami — WHOAMI 拡張オペレーションのヘルパ

説明

ldap_exop_whoami(LDAP\Connection $ldap): string|false

WHOAMI 拡張オペレーションを実行し、データを返します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

戻り値

サーバーが返したデータを返します。エラー時には false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

参考

  • ldap_exop() - 拡張されたオペレーションを実行する


DN を構成要素ごとに分割する

  • ≪ ldap_exop_whoami
  • ldap_first_attribute ≫
  • PHP Manual
  • LDAP 関数
  • DN を構成要素ごとに分割する

ldap_explode_dn

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_explode_dn — DN を構成要素ごとに分割する

説明

ldap_explode_dn(string $dn, int $with_attrib): array|false

ldap_get_dn() により返された DN を分割し、 複数の要素に分けます。各部分は、相対区分名 (Relative Distinguished Name または RDN) と呼ばれます。

パラメータ

dn

LDAP エンティティの識別名。

with_attrib

RDN が値のみを返すのか、 あるいは、属性を同時に返すのかを指定するために使用します。 属性を有する RDN (属性=値 フォーマットで) を得るためには with_attrib を 0 とし、 値のみを得るためには 1 に設定します。

戻り値

すべての DN 要素を配列で返します。失敗した場合に false を返します。 この配列の最初の要素のキーは count で、 これは返される値の数を表します。次の要素は、DN の数値添字配列となります。


最初の属性を返す

  • ≪ ldap_explode_dn
  • ldap_first_entry ≫
  • PHP Manual
  • LDAP 関数
  • 最初の属性を返す

ldap_first_attribute

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_first_attribute — 最初の属性を返す

説明

ldap_first_attribute(LDAP\Connection $ldap, LDAP\ResultEntry $entry): string|false

指定したエントリの最初の属性を取得します。残りの属性は、 ldap_next_attribute() を逐次コールして取得します。

エントリの読み込みと同様、 エントリからの属性の読み込みもひとつづつ行われます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

戻り値

成功した場合にエントリの最初の属性、エラーの場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。
8.0.0 | 未使用だった3番目のパラメータ ber_identifier は、 もはや使えなくなりました。

参考

  • ldap_next_attribute() - 結果における次の属性を得る
  • ldap_get_attributes() - 検索結果エントリから属性を得る


最初の結果 ID を返す

  • ≪ ldap_first_attribute
  • ldap_first_reference ≫
  • PHP Manual
  • LDAP 関数
  • 最初の結果 ID を返す

ldap_first_entry

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_first_entry — 最初の結果 ID を返す

説明

ldap_first_entry(LDAP\Connection $ldap, LDAP\Result $result): LDAP\ResultEntry|false

結果内の最初のエントリのエントリ ID を返します。このエントリ ID を ldap_next_entry() に渡し、 結果からそれ以降のエントリを取得します。

LDAP 結果におけるエントリは、ldap_first_entry() および ldap_next_entry() 関数を用いて連続的に 読み込まれます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

戻り値

成功時に、最初のエントリに関する結果エントリを表す、 LDAP\ResultEntry クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。
8.1.0 | LDAP\ResultEntry クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。

参考

  • ldap_get_entries() - 全ての結果エントリを得る


最初のリファレンスを返す

  • ≪ ldap_first_entry
  • ldap_free_result ≫
  • PHP Manual
  • LDAP 関数
  • 最初のリファレンスを返す

ldap_first_reference

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_first_reference — 最初のリファレンスを返す

説明

ldap_first_reference(LDAP\Connection $ldap, LDAP\Result $result): LDAP\ResultEntry|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


結果メモリを開放する

  • ≪ ldap_first_reference
  • ldap_get_attributes ≫
  • PHP Manual
  • LDAP 関数
  • 結果メモリを開放する

ldap_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_free_result — 結果メモリを開放する

説明

ldap_free_result(LDAP\Result $result): bool

内部での結果保持用に割り当てられていたメモリを開放します。 結果メモリは、スクリプトの終了時に自動的に開放されます。

通常、LDAP の結果用に確保された全てのメモリはスクリプトの実行終了時 に開放されます。連続的な検索を行うスクリプトのように大きな 結果セットを返す場合、スクリプトにより使用される実行用メモリを 小さく保つために ldap_free_result() をコールすることが可能です。

パラメータ

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。


検索結果エントリから属性を得る

  • ≪ ldap_free_result
  • ldap_get_dn ≫
  • PHP Manual
  • LDAP 関数
  • 検索結果エントリから属性を得る

ldap_get_attributes

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_attributes — 検索結果エントリから属性を得る

説明

ldap_get_attributes(LDAP\Connection $ldap, LDAP\ResultEntry $entry): array

検索結果エントリから属性と値を読み込みます。

ディレクトリに特定のエントリを置いている場合、この関数をコールする ことにより、そのエントリに関して保持されている情報得ることができます。 ディレクトリエントリを "ブラウズ" するか、ディレクトリエントリの 構造が未知であるアプリケーションにおいてこの関数を使用します。 多くのアプリケーションにおいては、電子メールアドレスや姓のような 特定の属性を検索するため、保持されている他のデータにどんなものがあるか ということは問題にならないと思われます。

return_value["count"] = そのエントリの属性の数
return_value[0] = 最初の属性
return_value[n] = n 番目の属性

return_value["attribute"]["count"] = その属性に関する値の数
return_value["attribute"][0] = その属性に関する最初の値
return_value["attribute"][i] = その属性に関する (i+1) 番目の値

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

戻り値

完全なエントリ情報を多次元配列で返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。

例

例1 特定のディレクトリエントリに関して保持されている属性のリストを表示

<?php
// $ds はディレクトリサーバーへの LDAP\Connection のインスタンス

// $sr は事前の LDAP のディレクトリ検索コールの有効な結果

$entry = ldap_first_entry($ds, $sr);

$attrs = ldap_get_attributes($ds, $entry);

echo $attrs["count"] . " attributes held for this entry:<p>";

for ($i=0; $i < $attrs["count"]; $i++) {
echo $attrs[$i] . "<br />";
}
?>

参考

  • ldap_first_attribute() - 最初の属性を返す
  • ldap_next_attribute() - 結果における次の属性を得る


結果エントリから DN を得る

  • ≪ ldap_get_attributes
  • ldap_get_entries ≫
  • PHP Manual
  • LDAP 関数
  • 結果エントリから DN を得る

ldap_get_dn

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_dn — 結果エントリから DN を得る

説明

ldap_get_dn(LDAP\Connection $ldap, LDAP\ResultEntry $entry): string|false

結果における、あるエントリの DN を見つけます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

戻り値

結果エントリの DN を返します。エラーの場合、falseを返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。


全ての結果エントリを得る

  • ≪ ldap_get_dn
  • ldap_get_option ≫
  • PHP Manual
  • LDAP 関数
  • 全ての結果エントリを得る

ldap_get_entries

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_entries — 全ての結果エントリを得る

説明

ldap_get_entries(LDAP\Connection $ldap, LDAP\Result $result): array|false

指定した結果から複数のエントリを読み込み、 その属性および複数の値を読み込みます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

戻り値

成功時に完全な結果情報を多次元配列で返します。 失敗した場合に false を返します

配列の構造は次のようになります。 属性インデックスは、小文字に変換されます (属性は大文字小文字を区別しませんが、配列インデックスとして使用する時は別です)。

return_value["count"] = 結果におけるエントリの数
return_value[0] : 最初のエントリの詳細情報を参照します

return_value[i]["dn"] =  結果における i 番目のエントリ DN

return_value[i]["count"] = i 番目のエントリにおける属性の数
return_value[i][j] = 結果における i 番目のエントリにおける j 番目の属性名

return_value[i]["attribute"]["count"] = i 番目のエントリにおける属性に関する値の数
return_value[i]["attribute"][j] = i 番目のエントリにおける j 番目の値

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。

参考

  • ldap_first_entry() - 最初の結果 ID を返す
  • ldap_next_entry() - 次の結果エントリを得る


指定したオプションの現在の値を得る

  • ≪ ldap_get_entries
  • ldap_get_values ≫
  • PHP Manual
  • LDAP 関数
  • 指定したオプションの現在の値を得る

ldap_get_option

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ldap_get_option — 指定したオプションの現在の値を得る

説明

ldap_get_option(LDAP\Connection $ldap, int $option, array|string|int &$value = null): bool

value を、指定したオプションの値として設定します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

option

パラメータ option は以下のいずれかとなります。

オプション | 型 | 利用可能になったバージョン
LDAP_OPT_DEREF int
LDAP_OPT_SIZELIMIT int
LDAP_OPT_TIMELIMIT int
LDAP_OPT_NETWORK_TIMEOUT int
LDAP_OPT_PROTOCOL_VERSION int
LDAP_OPT_ERROR_NUMBER int
LDAP_OPT_DIAGNOSTIC_MESSAGE string
LDAP_OPT_REFERRALS int
LDAP_OPT_RESTART int
LDAP_OPT_HOST_NAME string
LDAP_OPT_ERROR_STRING string
LDAP_OPT_MATCHED_DN string
LDAP_OPT_SERVER_CONTROLS array
LDAP_OPT_CLIENT_CONTROLS array
LDAP_OPT_X_KEEPALIVE_IDLE | int | 7.1
LDAP_OPT_X_KEEPALIVE_PROBES | int | 7.1
LDAP_OPT_X_KEEPALIVE_INTERVAL | int | 7.1
LDAP_OPT_X_TLS_CACERTDIR | string | 7.1
LDAP_OPT_X_TLS_CACERTFILE | string | 7.1
LDAP_OPT_X_TLS_CERTFILE | string | 7.1
LDAP_OPT_X_TLS_CIPHER_SUITE | string | 7.1
LDAP_OPT_X_TLS_CRLCHECK | int | 7.1
LDAP_OPT_X_TLS_CRL_NONE | int | 7.1
LDAP_OPT_X_TLS_CRL_PEER | int | 7.1
LDAP_OPT_X_TLS_CRL_ALL | int | 7.1
LDAP_OPT_X_TLS_CRLFILE | string | 7.1
LDAP_OPT_X_TLS_DHFILE | string | 7.1
LDAP_OPT_X_TLS_KEYFILE | string | 7.1
LDAP_OPT_X_TLS_PACKAGE | string | 7.1
LDAP_OPT_X_TLS_PROTOCOL_MIN | int | 7.1
LDAP_OPT_X_TLS_RANDOM_FILE | string | 7.1
LDAP_OPT_X_TLS_REQUIRE_CERT int

value

これが、オプションの値として設定されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

例

例1 プロトコルのバージョンを調べる

<?php
// $ds はディレクトリサーバーへの有効な LDAP\Connection のインスタンスです
if (ldap_get_option($ds, LDAP_OPT_PROTOCOL_VERSION, $version)) {
echo "使用中のプロトコルのバージョン: $version\n";
} else {
echo "プロトコルのバージョンを決定することができません\n";
}
?>

注意

注意:

この関数は、OpenLDAP 2.x.x または Netscape Directory SDK x.x を使用した場合にのみ利用可能です。

参考

  • ldap_set_option() - 指定したオプションの値を設定する


結果エントリから全ての値を得る

  • ≪ ldap_get_option
  • ldap_get_values_len ≫
  • PHP Manual
  • LDAP 関数
  • 結果エントリから全ての値を得る

ldap_get_values

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_values — 結果エントリから全ての値を得る

説明

ldap_get_values(LDAP\Connection $ldap, LDAP\ResultEntry $entry, string $attribute): array|false

結果内のエントリ属性の、すべての値を読み込みます。

この関数をコールするには、entry が必要です。このため、事前に LDAP の検索用関数のコールと個々の エントリ取得用関数のコールを行っておく必要があります。

アプリケーションでは、("surname" または "mail" のような)特定の属性 を探すためにその属性をコードに埋め込んで置くか、さもなくば、指定した エントリに関して存在する属性を調べるために ldap_get_attributes() をコールする必要があります。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

attribute

戻り値

成功した場合、指定した属性に関する値を配列を返します。エラーの場合は false を返します。値の数を調べるには、結果の配列の "count" という要素を確認します。個々の値にアクセスするには、 整数値のインデックスを指定して配列にアクセスします。 最初のインデックスは 0 となります。

LDAP では、ある属性に関して複数のエントリを持つことが可能です。 このため、たとえば一人の人間のディレクトリエントリに多数の 電子メールアドレスがあったとしても、それらをすべて "mail" という属性で管理することができます。

    return_value["count"] = 属性の値の数
    return_value[0] = 属性の最初の値
    return_value[i] = 属性の i 番目の値

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。

例

例1 あるディレクトリエントリの全ての "mail" 属性の一覧を表示する

<?php
// $ds はディレクトリサーバーの有効な LDAP\Connection のインスタンス

// $sr は事前の LDAP 検索コールのどれかから返された有効な検索結果

// $entry はディレクトリエントリを返すコールのどれかから返された有効な
// エントリ ID

$values = ldap_get_values($ds, $entry, "mail");

echo $values["count"] . " email addresses for this entry.<br />";

for ($i=0; $i < $values["count"]; $i++) {
echo $values[$i] . "<br />";
}
?>

参考

  • ldap_get_values_len() - 結果エントリから全てのバイナリ値を得る


結果エントリから全てのバイナリ値を得る

  • ≪ ldap_get_values
  • ldap_list ≫
  • PHP Manual
  • LDAP 関数
  • 結果エントリから全てのバイナリ値を得る

ldap_get_values_len

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_get_values_len — 結果エントリから全てのバイナリ値を得る

説明

ldap_get_values_len(LDAP\Connection $ldap, LDAP\ResultEntry $entry, string $attribute): array|false

結果のエントリから、属性のすべての値を読み込みます。

この関数は、文字列データではなくバイナリデータを処理すること以外は、 ldap_get_values() と全く同じです。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

attribute

戻り値

成功時に属性の値を配列で返し、エラー時に false を返します。 個々の値は、配列インデックスによりアクセスします。最初のインデックスは、0 です。 値の数は、結果の配列の "count" という要素で知ることができます。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。

参考

  • ldap_get_values() - 結果エントリから全ての値を得る


単一階層の検索を行う

  • ≪ ldap_get_values_len
  • ldap_mod_add ≫
  • PHP Manual
  • LDAP 関数
  • 単一階層の検索を行う

ldap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_list — 単一階層の検索を行う

説明

ldap_list(
LDAP\Connection|array $ldap,
array|string $base,
array|string $filter,
array $attributes = [],
int $attributes_only = 0,
int $sizelimit = -1,
int $timelimit = -1,
int $deref = LDAP_DEREF_NEVER,
?array $controls = null
): LDAP\Result|array|false

指定したフィルタ filter を使用し、スコープ LDAP_SCOPE_ONELEVEL でディレクトリを検索します。

LDAP_SCOPE_ONELEVEL は、コール時に指定した base の直下の階層から検索した結果のみを返すことを表します ("ls" と入力して、現在の作業ディレクトリのファイル/フォルダ 一覧を取得するのと同じようなものです)。

並列検索も可能です。並列検索を行うには、単一の LDAP\Connection のインスタンスではなく、それの配列を使用します。同じベース DN を使用したくない場合や全ての検索について同じフィルタを使用したくない場合、ベース DN の配列またはフィルタの配列を使用することが可能です。これらの配列は、LDAP\Connection の配列と同じ大きさである必要があります。これは、その配列の最初が一回の検索で使用され、2 番目のエントリが他の検索で使用されるといったようになるからです。並列検索を実行する際、エラーの場合を除き、LDAP\Result の配列が返されます。エラーの場合は、返される値は false になります。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

base

ディレクトリのベース DN。

filter

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。 したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。 属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、 事前に設定された数以上のエントリを返さないようになっているものもあります。 この場合、サーバーでは、それが結果セットのすべてではないことを通知します。 このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。 これを 0 にすると無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。 以下のいずれかとなります。

  • LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
  • LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
  • LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
  • LDAP_DEREF_ALWAYS - エイリアスを常に参照します。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

LDAP\Result のインスタンスか、LDAP\Result のインスタンスの配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

例

例1 ある組織の全ての組織単位を一覧表示する

<?php
// $ds はディレクトリサーバーの有効な LDAP\Connection のインスタンス

$basedn = "o=My Company, c=US";
$justthese = array("ou");

$sr = ldap_list($ds, $basedn, "ou=*", $justthese);

$info = ldap_get_entries($ds, $sr);

for ($i=0; $i < $info["count"]; $i++) {
echo $info[$i]["ou"][0];
}
?>

参考

  • ldap_search() - LDAP ツリーを探索する


現在の属性に属性を追加する

  • ≪ ldap_list
  • ldap_mod_add_ext ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性に属性を追加する

ldap_mod_add

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_mod_add — 現在の属性に属性を追加する

説明

ldap_mod_add(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): bool

指定した dn に属性を追加します。 新しいオブジェクト全体を追加する用途については、 ldap_add() 関数を参照ください。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

entry

追加する属性値を一覧にした連想配列。 属性が存在しない場合は追加されます。 属性が存在する場合は、その属性が複数の値をサポートしている場合のみ追加できます。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_mod_add_ext() - 現在の属性に属性を追加する
  • ldap_mod_del() - 現在の属性から属性を削除する
  • ldap_mod_replace() - 属性を新規の値に置換する
  • ldap_modify_batch() - LDAP エントリの変更をまとめて実行する


現在の属性に属性を追加する

  • ≪ ldap_mod_add
  • ldap_mod_del ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性に属性を追加する

ldap_mod_add_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_mod_add_ext — 現在の属性に属性を追加する

説明

ldap_mod_add_ext(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): LDAP\Result|false

ldap_mod_add() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_mod_add() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

参考

  • ldap_mod_add() - 現在の属性に属性を追加する
  • ldap_parse_result() - 結果から情報を展開する


現在の属性から属性を削除する

  • ≪ ldap_mod_add_ext
  • ldap_mod_del_ext ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性から属性を削除する

ldap_mod_del

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_mod_del — 現在の属性から属性を削除する

説明

ldap_mod_del(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): bool

ひとつあるいは複数の属性を、指定した dn から削除します。 オブジェクトレベルの削除は、ldap_delete() 関数により行います。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

entry

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

参考

  • ldap_mod_del_ext() - 現在の属性から属性を削除する
  • ldap_mod_add() - 現在の属性に属性を追加する
  • ldap_mod_replace() - 属性を新規の値に置換する
  • ldap_modify_batch() - LDAP エントリの変更をまとめて実行する


現在の属性から属性を削除する

  • ≪ ldap_mod_del
  • ldap_mod_replace ≫
  • PHP Manual
  • LDAP 関数
  • 現在の属性から属性を削除する

ldap_mod_del_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_mod_del_ext — 現在の属性から属性を削除する

説明

ldap_mod_del_ext(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): LDAP\Result|false

ldap_mod_del() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_mod_del() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

参考

  • ldap_mod_del() - 現在の属性から属性を削除する
  • ldap_parse_result() - 結果から情報を展開する


属性を新規の値に置換する

  • ≪ ldap_mod_del_ext
  • ldap_mod_replace_ext ≫
  • PHP Manual
  • LDAP 関数
  • 属性を新規の値に置換する

ldap_mod_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_mod_replace — 属性を新規の値に置換する

説明

ldap_mod_replace(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): bool

指定した dn でひとつあるいは複数の属性の置換を行います。 この関数は、属性の追加や削除も行えます。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

entry

置き換える属性を一覧にした連想配列。 空の配列を送ると、属性そのものが削除されます。 一方で、属性が存在していない値を送ると追加されます。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • ldap_mod_replace_ext() - 属性を新規の値に置換する
  • ldap_mod_del() - 現在の属性から属性を削除する
  • ldap_mod_add() - 現在の属性に属性を追加する
  • ldap_modify_batch() - LDAP エントリの変更をまとめて実行する


属性を新規の値に置換する

  • ≪ ldap_mod_replace
  • ldap_modify ≫
  • PHP Manual
  • LDAP 関数
  • 属性を新規の値に置換する

ldap_mod_replace_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_mod_replace_ext — 属性を新規の値に置換する

説明

ldap_mod_replace_ext(
LDAP\Connection $ldap,
string $dn,
array $entry,
?array $controls = null
): LDAP\Result|false

ldap_mod_replace() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_mod_replace() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

参考

  • ldap_mod_replace() - 属性を新規の値に置換する
  • ldap_parse_result() - 結果から情報を展開する


のエイリアス ldap_mod_replace

  • ≪ ldap_mod_replace_ext
  • ldap_modify_batch ≫
  • PHP Manual
  • LDAP 関数
  • のエイリアス ldap_mod_replace

ldap_modify

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_modify — のエイリアス ldap_mod_replace()

説明

この関数は次の関数のエイリアスです。 ldap_mod_replace().

参考

  • ldap_rename() - エントリ名を修正する


LDAP エントリの変更をまとめて実行する

  • ≪ ldap_modify
  • ldap_next_attribute ≫
  • PHP Manual
  • LDAP 関数
  • LDAP エントリの変更をまとめて実行する

ldap_modify_batch

(PHP 5.4 >= 5.4.26, PHP 5.5 >= 5.5.10, PHP 5.6 >= 5.6.0, PHP 7, PHP 8)

ldap_modify_batch — LDAP エントリの変更をまとめて実行する

説明

ldap_modify_batch(
LDAP\Connection $ldap,
string $dn,
array $modifications_info,
?array $controls = null
): bool

LDAP ディレクトリに存在する既存のエントリを変更します。 実行する変更の詳細な仕様を指定できます。

パラメータ

ldap

ldap_connect() で返された、LDAP リソース。

dn

LDAP エンティティの識別名。

modifications_info

行う変更を指定する配列。 この配列の個々のエントリは、2つまたは3つのキーからなる連想配列です: attrib は、変更する属性の名前に対応します。 modtype は、行う変更のタイプに対応し、 (変更のタイプによっては) values が変更に関連した属性値の配列に対応します。

modtype で有効な値は以下のとおりです:

LDAP_MODIFY_BATCH_ADD

values で指定された値が、 (追加の値として) attrib で指定された属性に追加されます。

LDAP_MODIFY_BATCH_REMOVE

values で指定された値が、 attrib で指定された属性から削除されます。 values に含まれていない属性の値は、そのまま残されます。

LDAP_MODIFY_BATCH_REMOVE_ALL

attrib で指定された属性名から、全ての値を削除します。 values エントリを指定してはいけません。

LDAP_MODIFY_BATCH_REPLACE

attrib の属性名の現在の全ての値が、 values で指定された値で置き換えられます。

以下の点に注意してください: attrib の値は文字列でなければいけません。 values の値は、文字列の配列でなければいけません。 そして、 modtype の値は、上で示した LDAP_MODIFY_BATCH_* 定数のうちのひとつでなければいけません。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

例

例1 contact に電話番号を追加する

<?php
$dn = "cn=John Smith,ou=Wizards,dc=example,dc=com";
$modifs = [
[
"attrib" => "telephoneNumber",
"modtype" => LDAP_MODIFY_BATCH_ADD,
"values" => ["+1 555 555 1717"],
],
];
ldap_modify_batch($connection, $dn, $modifs);
?>

例2 ユーザーの名前を変更する

<?php
$dn = "cn=John Smith,ou=Wizards,dc=example,dc=com";
$modifs = [
[
"attrib" => "sn",
"modtype" => LDAP_MODIFY_BATCH_REPLACE,
"values" => ["Smith-Jones"],
],
[
"attrib" => "givenName",
"modtype" => LDAP_MODIFY_BATCH_REPLACE,
"values" => ["Jack"],
],
];
ldap_modify_batch($connection, $dn, $modifs);
ldap_rename($connection, $dn, "cn=Jack Smith-Jones", NULL, TRUE);
?>

例3 ユーザーにEメールアドレスを2つ追加する

<?php
$dn = "cn=Jack Smith-Jones,ou=Wizards,dc=example,dc=com";
$modifs = [
[
"attrib" => "mail",
"modtype" => LDAP_MODIFY_BATCH_ADD,
"values" => [
"jack.smith@example.com",
"jack.smith-jones@example.com",
],
],
];
ldap_modify_batch($connection, $dn, $modifs);
?>

例4 ユーザーのパスワードを変更する

<?php
$dn = "cn=Jack Smith-Jones,ou=Wizards,dc=example,dc=com";
$modifs = [
[
"attrib" => "userPassword",
"modtype" => LDAP_MODIFY_BATCH_REMOVE,
"values" => ["Tr0ub4dor&3"],
],
[
"attrib" => "userPassword",
"modtype" => LDAP_MODIFY_BATCH_ADD,
"values" => ["correct horse battery staple"],
],
];
ldap_modify_batch($connection, $dn, $modifs);
?>

例5 ユーザーのパスワードを変更する(Active Directory)

<?php
function adifyPw($pw)
{
return iconv("UTF-8", "UTF-16LE", '"' . $pw . '"');
}

$dn = "cn=Jack Smith-Jones,ou=Wizards,dc=ad,dc=example,dc=com";
$modifs = [
[
"attrib" => "unicodePwd",
"modtype" => LDAP_MODIFY_BATCH_REMOVE,
"values" => [adifyPw("Tr0ub4dor&3")],
],
[
"attrib" => "unicodePwd",
"modtype" => LDAP_MODIFY_BATCH_ADD,
"values" => [adifyPw("correct horse battery staple")],
],
];
ldap_modify_batch($connection, $dn, $modifs);


結果における次の属性を得る

  • ≪ ldap_modify_batch
  • ldap_next_entry ≫
  • PHP Manual
  • LDAP 関数
  • 結果における次の属性を得る

ldap_next_attribute

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_next_attribute — 結果における次の属性を得る

説明

ldap_next_attribute(LDAP\Connection $ldap, LDAP\ResultEntry $entry): string|false

エントリ内の属性を取得します。 最初に ldap_next_attribute() をコールした際には ldap_first_attribute() から返される entry を使用します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

戻り値

成功した場合、エントリにおける次の属性を返します。エラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。
8.0.0 | 未使用だった3番目のパラメータ ber_identifier は、 もはや使えなくなりました。

参考

  • ldap_get_attributes() - 検索結果エントリから属性を得る


次の結果エントリを得る

  • ≪ ldap_next_attribute
  • ldap_next_reference ≫
  • PHP Manual
  • LDAP 関数
  • 次の結果エントリを得る

ldap_next_entry

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_next_entry — 次の結果エントリを得る

説明

ldap_next_entry(LDAP\Connection $ldap, LDAP\ResultEntry $entry): LDAP\ResultEntry|false

結果に保持されたエントリを取得します。 連続的に ldap_next_entry() をコールした場合、 エントリがなくなるまでエントリを一つずつ返します。 ldap_next_entry() への最初のコールは、 ldap_first_entry() から返された entry を指定してコールした後に、その結果を用いて行います。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

entry

LDAP\ResultEntry クラスのインスタンス。

戻り値

ldap_first_entry() によりエントリが読み始められた 結果において、次のエントリを表す LDAP\ResultEntry クラスのインスタンスを返します。 これ以上結果のエントリがない場合は、false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 entry は、 LDAP\ResultEntry クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result entry リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。

参考

  • ldap_get_entries() - 全ての結果エントリを得る


次のリファレンスを得る

  • ≪ ldap_next_entry
  • ldap_parse_exop ≫
  • PHP Manual
  • LDAP 関数
  • 次のリファレンスを得る

ldap_next_reference

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_next_reference — 次のリファレンスを得る

説明

ldap_next_reference(LDAP\Connection $ldap, LDAP\ResultEntry $entry): LDAP\ResultEntry|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


LDAP拡張オペレーションの結果オブジェクトをパースする

  • ≪ ldap_next_reference
  • ldap_parse_reference ≫
  • PHP Manual
  • LDAP 関数
  • LDAP拡張オペレーションの結果オブジェクトをパースする

ldap_parse_exop

(PHP 7 >= 7.2.0, PHP 8)

ldap_parse_exop — LDAP拡張オペレーションの結果オブジェクトをパースする

説明

ldap_parse_exop(
LDAP\Connection $ldap,
LDAP\Result $result,
string &$response_data = null,
string &$response_oid = null
): bool

LDAP拡張オペレーションの結果オブジェクト result データをパースします。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

response_data

レスポンスデータで埋められます。

response_oid

レスポンスのOIDで埋められます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。

参考

  • ldap_exop() - 拡張されたオペレーションを実行する


参照エントリから情報を展開する

  • ≪ ldap_parse_exop
  • ldap_parse_result ≫
  • PHP Manual
  • LDAP 関数
  • 参照エントリから情報を展開する

ldap_parse_reference

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_parse_reference — 参照エントリから情報を展開する

説明

ldap_parse_reference(LDAP\Connection $ldap, LDAP\ResultEntry $entry, array &$referrals): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


結果から情報を展開する

  • ≪ ldap_parse_reference
  • ldap_read ≫
  • PHP Manual
  • LDAP 関数
  • 結果から情報を展開する

ldap_parse_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_parse_result — 結果から情報を展開する

説明

ldap_parse_result(
LDAP\Connection $ldap,
LDAP\Result $result,
int &$error_code,
string &$matched_dn = null,
string &$error_message = null,
array &$referrals = null,
array &$controls = null
): bool

LDAP の検索結果をパースします。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

result

ldap_list() や ldap_search() が返す、LDAP\Result クラスのインスタンス。.

error_code

結果に含まれる LDAP エラーコードを格納する変数への参照。 エラーが発生しなかった場合は、この変数に 0 を格納します。

matched_dn

リクエスト内にマッチする DN があった場合に、それを格納する変数への参照。 なかった場合は、この変数に null を格納します。

error_message

結果に含まれる LDAP エラーメッセージを格納する変数への参照。 エラーが発生しなかった場合は、この変数に空文字列を格納します。

referrals

結果に含まれるすべての照会文字列の配列を格納する変数への参照。 存在しない場合は、この変数に空の配列を格納します。

controls

レスポンスを送信した LDAP コントロール の array。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | 引数 result は、 LDAP\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap result リソース を期待していました。
7.3.0 | controls のサポートが追加されました。

例

例1 ldap_parse_result() の例

<?php
$result = ldap_search($ldap, "cn=userref,dc=my-domain,dc=com", "(cn=user*)");
$errcode = $dn = $errmsg = $refs = null;
if (ldap_parse_result($ldap, $result, $errcode, $dn, $errmsg, $refs)) {
// $errcode や $dn、$errmsg、$refs を使って何かをします。
}
?>


エントリを読み込む

  • ≪ ldap_parse_result
  • ldap_rename ≫
  • PHP Manual
  • LDAP 関数
  • エントリを読み込む

ldap_read

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_read — エントリを読み込む

説明

ldap_read(
LDAP\Connection|array $ldap,
array|string $base,
array|string $filter,
array $attributes = [],
int $attributes_only = 0,
int $sizelimit = -1,
int $timelimit = -1,
int $deref = LDAP_DEREF_NEVER,
?array $controls = null
): LDAP\Result|array|false

指定したフィルタ filter を使用し、スコープ LDAP_SCOPE_BASE でディレクトリを検索します。これは、 ディレクトリからエントリを読み込むことと同じ意味です。

並列検索も可能です。並列検索を行うには、単一の LDAP\Connection のインスタンスではなく、それの配列を使用します。同じベース DN を使用したくない場合や全ての検索について同じフィルタを使用したくない場合、ベース DN の配列またはフィルタの配列を使用することが可能です。これらの配列は、LDAP\Connection の配列と同じ大きさである必要があります。これは、その配列の最初が一回の検索で使用され、2 番目のエントリが他の検索で使用されるといったようになるからです。並列検索を実行する際、エラーの場合を除き、LDAP\Result の配列が返されます。エラーの場合は、返される値は false になります。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

base

ディレクトリのベース DN。

filter

空のフィルタは指定できません。 このエントリに関する全ての情報を完全に取得したい場合は、 objectClass=* というフィルタを使用してください。 ディレクトリサーバーで使用されるエントリの型が分かっている場合、 objectClass=inetOrgPerson のように適切なフィルタを使用することができます。

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。 したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。 属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、 事前に設定された数以上のエントリを返さないようになっているものもあります。 この場合、サーバーでは、それが結果セットのすべてではないことを通知します。 このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。 これを 0 にすると無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。 以下のいずれかとなります。

  • LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
  • LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
  • LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
  • LDAP_DEREF_ALWAYS - エイリアスを常に参照します。 always.

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

LDAP\Result のインスタンスか、LDAP\Result のインスタンスの配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
4.0.5 | 並列検索のサポートが追加されました。詳細は ldap_search() を参照ください。
7.3.0 | controls のサポートが追加されました。


エントリ名を修正する

  • ≪ ldap_read
  • ldap_rename_ext ≫
  • PHP Manual
  • LDAP 関数
  • エントリ名を修正する

ldap_rename

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ldap_rename — エントリ名を修正する

説明

ldap_rename(
LDAP\Connection $ldap,
string $dn,
string $new_rdn,
string $new_parent,
bool $delete_old_rdn,
?array $controls = null
): bool

dn で指定したエントリについて、 名前の変更または移動を行います。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

dn

LDAP エンティティの識別名。

new_rdn

新しい RDN。

new_parent

新しい親エントリ。

delete_old_rdn

true の場合は古い RDN 値を削除します。それ以外の場合は古い RDN 値がそのエントリの non-distinguished 値として残されます。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

注意

注意:

この関数は、現在、LDAPv3 でのみ動作します。LDAPv3 でバインドする前に ldap_set_option() を使用する必要があるかもしれません。 この関数は、OpenLDAP 2.x.x または Netscape Directory SDK x.x を使用している場合にのみ使用可能です。

参考

  • ldap_rename_ext() - エントリ名を修正する
  • ldap_modify() - のエイリアス ldap_mod_replace


エントリ名を修正する

  • ≪ ldap_rename
  • ldap_sasl_bind ≫
  • PHP Manual
  • LDAP 関数
  • エントリ名を修正する

ldap_rename_ext

(PHP 7 >= 7.3.0, PHP 8)

ldap_rename_ext — エントリ名を修正する

説明

ldap_rename_ext(
LDAP\Connection $ldap,
string $dn,
string $new_rdn,
string $new_parent,
bool $delete_old_rdn,
?array $controls = null
): LDAP\Result|false

ldap_rename() と同じですが、 ldap_parse_result() を使ってパースされた LDAP 結果 を表す LDAP\Result クラスのインスタンスを返します。

パラメータ

ldap_rename() を参照ください。

戻り値

LDAP\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

参考

  • ldap_rename() - エントリ名を修正する
  • ldap_parse_result() - 結果から情報を展開する


SASL を使用して LDAP ディレクトリにバインドする

  • ≪ ldap_rename_ext
  • ldap_search ≫
  • PHP Manual
  • LDAP 関数
  • SASL を使用して LDAP ディレクトリにバインドする

ldap_sasl_bind

(PHP 5, PHP 7, PHP 8)

ldap_sasl_bind — SASL を使用して LDAP ディレクトリにバインドする

説明

ldap_sasl_bind(
LDAP\Connection $ldap,
?string $dn = null,
#[\SensitiveParameter] ?string $password = null,
?string $mech = null,
?string $realm = null,
?string $authc_id = null,
?string $authz_id = null,
?string $props = null
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | dn, password, mech, realm, authc_id, authz_id, props は、nullable になりました。

注意

注意: 前提条件
ldap_sasl_bind() は SASL のサポート（sasl.h）が必要です。PHP の configure 時に --with-ldap-sasl が指定されている ことを確認してください。さもないとこの関数は未定義となります。


LDAP ツリーを探索する

  • ≪ ldap_sasl_bind
  • ldap_set_option ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ツリーを探索する

ldap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_search — LDAP ツリーを探索する

説明

ldap_search(
LDAP\Connection|array $ldap,
array|string $base,
array|string $filter,
array $attributes = [],
int $attributes_only = 0,
int $sizelimit = -1,
int $timelimit = -1,
int $deref = LDAP_DEREF_NEVER,
?array $controls = null
): LDAP\Result|array|false

指定したフィルタを使用し、 スコープ LDAP_SCOPE_SUBTREE でディレクトリを検索します。これは、ディレクトリ全体を検索するのと同じ意味です。

並列検索も可能です。並列検索を行うには、単一の LDAP\Connection のインスタンスではなく、それの配列を使用します。同じベース DN を使用したくない場合や全ての検索について同じフィルタを使用したくない場合、ベース DN の配列またはフィルタの配列を使用することが可能です。これらの配列は、LDAP\Connection の配列と同じ大きさである必要があります。これは、その配列の最初が一回の検索で使用され、2 番目のエントリが他の検索で使用されるといったようになるからです。並列検索を実行する際、エラーの場合を除き、LDAP\Result の配列が返されます。エラーの場合は、返される値は false になります。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

base

ディレクトリのベース DN。

filter

検索フィルタは、LDAP ドキュメントに記述されたフォーマットの論理 演算子を用いて、簡単なものまたは高度なものとすることができます (フィルタに関する詳細な情報については、 » Netscape Directory SDK あるいは » RFC4515 を参照ください)。

attributes

必要な属性を、 array("mail", "sn", "cn") のような通常の PHP 文字列配列で保持します。 "dn" は要求された属性の型によらず常に返されることに注意してください。

このパラメータを使用すると、デフォルトの動作よりもかなり効率的になります (デフォルトでは、すべての属性とその値を返します)。 したがって、これを使用することを推奨します。

attributes_only

属性の型のみを取得したい場合は 1 を設定します。 属性の型および値の両方を取得したい場合は 0 を設定します (これがデフォルトの挙動です)。

sizelimit

取得するエントリ数の制限を設定します。 0 は無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている sizelimit を上書きすることはできません。それ以下の値を指定することはできます。

ディレクトリサーバーのホストによっては、 事前に設定された数以上のエントリを返さないようになっているものもあります。 この場合、サーバーでは、それが結果セットのすべてではないことを通知します。 このパラメータでエントリ数を制限した場合にも、同じことが起こります。

timelimit

検索に要する最大秒数を設定します。 これを 0 にすると無制限であることを表します。

注意:

このパラメータは、サーバー側で事前に設定されている timelimit を上書きすることはできません。それ以下の値を指定することはできます。

deref

検索時のエイリアスの扱いについて指定します。 以下のいずれかとなります。

  • LDAP_DEREF_NEVER - (デフォルト) エイリアスは参照されません。
  • LDAP_DEREF_SEARCHING - エイリアスを参照しますが、検索のベースオブジェクト上にいるときは参照しません。
  • LDAP_DEREF_FINDING - エイリアスの参照は、ベースオブジェクト上にいて検索中でない場合に行われます。
  • LDAP_DEREF_ALWAYS - エイリアスを常に参照します。

controls

リクエストと一緒に送信する LDAP コントロール の配列

戻り値

LDAP\Result のインスタンスか、LDAP\Result のインスタンスの配列を返します。失敗した場合に false を返します

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.1.0 | LDAP\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソース を返していました。
8.0.0 | controls は、nullable になりました。 これより前のバージョンでは、デフォルト値が [] でした。
7.3.0 | controls のサポートが追加されました。

例

以下の例は、"My Company" の全員について姓または名の一部に文字列 $person を含む人の組織単位、姓、名、電子メールアドレスを取得します。 この例は、複数の属性に関する情報についてサーバーに検索をかける論理 フィルタを使用します。

例1 LDAP 検索

<?php
// $ds は、ディレクトリサーバーの LDAP\Connection のインスタンス

// $person は、人名またはその一部。例 "Jo"

$dn = "o=My Company, c=US";
$filter="(|(sn=$person*)(givenname=$person*))";
$justthese = array("ou", "sn", "givenname", "mail");

$sr=ldap_search($ds, $dn, $filter, $justthese);

$info = ldap_get_entries($ds, $sr);

echo $info["count"]." 個のエントリが返されました\n";
?>


指定したオプションの値を設定する

  • ≪ ldap_search
  • ldap_set_rebind_proc ≫
  • PHP Manual
  • LDAP 関数
  • 指定したオプションの値を設定する

ldap_set_option

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ldap_set_option — 指定したオプションの値を設定する

説明

ldap_set_option(?LDAP\Connection $ldap, int $option, array|string|int|bool $value): bool

指定したオプションの値を value に設定します。

パラメータ

ldap

特定の接続に対してオプションを設定する場合は、 ldap_connect() が返す、 LDAP\Connection クラスのインスタンス。 オプションをグローバルに設定する場合は、 null を設定します。

option

パラメータ option は以下のいずれかとなります。

オプション | 型 | ～以降で使用可能
LDAP_OPT_DEREF int
LDAP_OPT_SIZELIMIT int
LDAP_OPT_TIMELIMIT int
LDAP_OPT_NETWORK_TIMEOUT int
LDAP_OPT_PROTOCOL_VERSION int
LDAP_OPT_ERROR_NUMBER int
LDAP_OPT_REFERRALS bool
LDAP_OPT_RESTART bool
LDAP_OPT_HOST_NAME string
LDAP_OPT_ERROR_STRING string
LDAP_OPT_DIAGNOSTIC_MESSAGE string
LDAP_OPT_MATCHED_DN string
LDAP_OPT_SERVER_CONTROLS array
LDAP_OPT_CLIENT_CONTROLS array
LDAP_OPT_X_KEEPALIVE_IDLE | int | PHP 7.1.0
LDAP_OPT_X_KEEPALIVE_PROBES | int | PHP 7.1.0
LDAP_OPT_X_KEEPALIVE_INTERVAL | int | PHP 7.1.0
LDAP_OPT_X_TLS_CACERTDIR | string | PHP 7.1.0
LDAP_OPT_X_TLS_CACERTFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_CERTFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_CIPHER_SUITE | string | PHP 7.1.0
LDAP_OPT_X_TLS_CRLCHECK | int | PHP 7.1.0
LDAP_OPT_X_TLS_CRLFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_DHFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_KEYFILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_PROTOCOL_MIN | int | PHP 7.1.0
LDAP_OPT_X_TLS_RANDOM_FILE | string | PHP 7.1.0
LDAP_OPT_X_TLS_REQUIRE_CERT | int | PHP 7.0.5

LDAP_OPT_SERVER_CONTROLS および LDAP_OPT_CLIENT_CONTROLS はコントロールのリストが必要です。 つまり、値がコントロールの配列である必要があるということです。 コントロールは、そのコントロールの ID である oid、オプションの value、オプションのフラグ criticality からなります。PHP において、 コントロールはキーが oid で値が文字列、 二つのオプションの要素からなる配列で指定されます。オプションの要素は、 キーが value で値が文字列、そしてキーが iscritical で値が論理値となります。 iscritical を省略した場合のデフォルトは false です。詳細は » draft-ietf-ldapext-ldap-c-api-xx.txt を参照ください。また以下の二番目の例も参照ください。

value

指定したオプション option の新しい値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

例

例1 プロトコルバージョンの設定

<?php
// $ds はディレクトリサーバーへの LDAP\Connection のインスタンス
if (ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3)) {
echo "LDAPv3 を使用します";
} else {
echo "プロトコルバージョンを 3 に設定できませんでした";
}
?>

例2 サーバーコントロールの設定

<?php
// $ds は値を持たないディレクトリサーバーコントロールへの LDAP\Connection のインスタンスです。
$ctrl1 = array("oid" => "1.2.752.58.10.1", "iscritical" => true);
// iscritical のデフォルトは、FALSE です。
$ctrl2 = array("oid" => "1.2.752.58.1.10", "value" => "magic");
// 両方のコントロールを試します
if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, $ctrl2))) {
echo "サーバーコントロールの設定に失敗しました。";
}
?>

注意

注意:

この関数は、OpenLDAP 2.x.x または Netscape Directory SDK x.x を使用している場合のみ利用可能です。

参考

  • ldap_get_option() - 指定したオプションの現在の値を得る


参照先を再バインドするためのコールバック関数を設定する

  • ≪ ldap_set_option
  • ldap_sort ≫
  • PHP Manual
  • LDAP 関数
  • 参照先を再バインドするためのコールバック関数を設定する

ldap_set_rebind_proc

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ldap_set_rebind_proc — 参照先を再バインドするためのコールバック関数を設定する

説明

ldap_set_rebind_proc(LDAP\Connection $ldap, ?callable $callback): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。
8.0.0 | callback は、nullable になりました。


LDAP 結果エントリをクライアント側でソートする

  • ≪ ldap_set_rebind_proc
  • ldap_start_tls ≫
  • PHP Manual
  • LDAP 関数
  • LDAP 結果エントリをクライアント側でソートする

ldap_sort

(PHP 4 >= 4.2.0, PHP 5, PHP 7)

ldap_sort — LDAP 結果エントリをクライアント側でソートする

警告

この関数は PHP 7.0.0 で 非推奨となり、PHP 8.0.0 で削除 されました。この関数に頼らないことを強く推奨します。

説明

ldap_sort(resource $link, resource $result, string $sortfilter): bool

ldap_search() が返す LDAP 検索結果をソートします。

この関数は、返された結果をクライアント側でソートします。そのため、 サーバー側の sizelimit や ldap_search() で定義した sizelimit に達した場合は期待どおりの結果を得られない可能性があります。

パラメータ

link

ldap_connect() が返す LDAP リソース。

result

ldap_search() が返す検索結果 ID。

sortfilter

ソートのキーとして使う属性。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | この関数は削除されました。

例

検索結果をソートします。

例1 LDAP のソート

<?php
// $ds は有効なリンク ID です (ldap_connect を参照)

$dn = 'ou=example,dc=org';
$filter = '(|(sn=Doe*)(givenname=John*))';
$justthese = array('ou', 'sn', 'givenname', 'mail');

$sr = ldap_search($ds, $dn, $filter, $justthese);

// ソート
ldap_sort($ds, $sr, 'sn');

// データの取得
$info = ldap_get_entries($ds, $sr);


TLS を開始する

  • ≪ ldap_sort
  • ldap_t61_to_8859 ≫
  • PHP Manual
  • LDAP 関数
  • TLS を開始する

ldap_start_tls

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ldap_start_tls — TLS を開始する

説明

ldap_start_tls(LDAP\Connection $ldap): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


t61 文字を 8859 文字に変換する

  • ≪ ldap_start_tls
  • ldap_unbind ≫
  • PHP Manual
  • LDAP 関数
  • t61 文字を 8859 文字に変換する

ldap_t61_to_8859

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ldap_t61_to_8859 — t61 文字を 8859 文字に変換する

説明

ldap_t61_to_8859(string $value): string|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


LDAP ディレクトリへのバインドを解除する

  • ≪ ldap_t61_to_8859
  • LDAP\Connection ≫
  • PHP Manual
  • LDAP 関数
  • LDAP ディレクトリへのバインドを解除する

ldap_unbind

(PHP 4, PHP 5, PHP 7, PHP 8)

ldap_unbind — LDAP ディレクトリへのバインドを解除する

説明

ldap_unbind(LDAP\Connection $ldap): bool

LDAP ディレクトリへのバインドを解除します。

パラメータ

ldap

ldap_connect() が返す LDAP\Connection クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | 引数 ldap は、LDAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な ldap link リソース を期待していました。

参考

  • ldap_bind() - LDAP ディレクトリにバインドする


LDAP\Connection クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、ldap リソースを置き換える、 完全不定形クラスです。

クラス概要

final class LDAP\Connection {
}


LDAP\Result クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、ldap result リソースを置き換える、 完全不定形クラスです。

クラス概要

final class LDAP\Result {
}


LDAP\ResultEntry クラス

(PHP 8 >= 8.1.0)

はじめに

PHP 8.1.0 以降、 ldap result entry リソースを置き換える、完全不定形クラスです。

クラス概要

final class LDAP\ResultEntry {
}


Memcache

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
    • 基本的な使用法
  • Memcache — Memcache クラス
    • Memcache::add — サーバーに項目を追加する
    • Memcache::addServer — コネクションプールに memcached サーバーを追加する
    • Memcache::close — memcached サーバーとの接続を閉じる
    • Memcache::connect — memcached サーバーへの接続をオープンする
    • Memcache::decrement — 項目の値を減らす
    • Memcache::delete — サーバーから項目を削除する
    • Memcache::flush — サーバー上のすべての既存項目を消去する
    • Memcache::get — サーバーから項目を取得する
    • Memcache::getExtendedStats — プール内のすべてのサーバーの統計情報を取得する
    • Memcache::getServerStatus — サーバーの状態を返す
    • Memcache::getStats — サーバーの統計情報を取得する
    • Memcache::getVersion — サーバーのバージョンを返す
    • Memcache::increment — 項目の値を増やす
    • Memcache::pconnect — memcached サーバーへの持続的な接続をオープンする
    • Memcache::replace — 既存項目の値を置換する
    • Memcache::set — データをサーバーに格納する
    • Memcache::setCompressThreshold — 大きな値に対する自動圧縮処理を有効にする
    • Memcache::setServerParams — サーバーのパラメータおよび状態を、実行時に変更する
  • Memcache 関数
    • memcache_debug — デバッグ出力のオン/オフを切り替える


はじめに

Memcache モジュールは、memcached に対する手続き型および オブジェクト指向のインターフェイスを提供します。これは非常に効率的な キャッシュデーモンで、動的な web アプリケーションでの データベースの読み込み量を減らすように設計されています。

Memcache モジュールは、セッション ハンドラ (memcache) も提供します。

memcached についてのより詳細な情報は » http://www.memcached.org/ にあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Memcache
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

このモジュールは、その場でのデータ圧縮機能をサポートするために » zlib の関数を使用しています。 このモジュールをインストールするには Zlib が必要となります。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/memcache.

注意:

オプションで、memcache セッションハンドラのサポートを無効にすることもできます。 'pecl install' のオプションでこれを指定します (デフォルトは有効になっています) が、 PHP のコンパイル時に静的に組み込む場合は configure オプション --disable-memcache-session を使用できます。


実行時設定

php.ini の設定により動作が変化します。

Memcache 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
memcache.allow_failover | "1" | INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.max_failover_attempts | "20" | INI_ALL | memcache 2.1.0 以降で使用可能です
memcache.chunk_size | "8192" | INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.default_port | "11211" | INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.hash_strategy | "standard" | INI_ALL | memcache 2.2.0 以降で使用可能です
memcache.hash_function | "crc32" | INI_ALL | memcache 2.2.0 以降で使用可能です
memcache.protocol | ascii | INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.redundancy | 1 | INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.session_redundancy | 2 | INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.compress_threshold | 20000 | INI_ALL | memcache 3.0.3 以降で使用可能です
memcache.lock_timeout | 15 | INI_ALL | memcache 3.0.4 以降で使用可能です
Memcache の振る舞いに影響する、セッションの設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
session.save_handler | "files" | INI_ALL | memcache 2.1.2 以降で利用可能です
session.save_path | "" | INI_ALL | memcache 2.1.2 以降で利用可能です
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

memcache.allow_failover bool

エラー時に、透過的なフェイルオーバーを行うかどうかを指定します。

memcache.max_failover_attempts int

データの設定や取得を試みるサーバーの数を指定します。 memcache.allow_failover を指定した場合にのみ使用します。

memcache.chunk_size int

データは、ここで指定した大きさに分割されます。 この値を小さくすると、ネットワークに対する書き込みが多くなります。 不可解な速度低下が発生する場合は、この値を 32768 まで大きくしてください。

memcache.default_port string

memcached サーバーに接続する際に、 デフォルトで使用される TCP ポート番号。

memcache.hash_strategy string

キーをサーバーと関連づけるために使用する方式を制御します。この値を consistent にすると、一貫したハッシュを使用します。 これにより、サーバーを追加したり削除したりした際にキーの再マッピングの必要がなくなります。 この値を standard にすると、以前の方法を使用します。

memcache.hash_function string

キーをサーバーに関連づける際に使用するハッシュ関数を制御します。 crc32 は標準の CRC32 ハッシュを、そして fnv は FNV-1a を使用します。

memcache.protocol string

memcache.redundancy int

memcache.session_redundancy int

memcache.compress_threshold int

memcache.lock_timeout int

session.save_handler string

memcache をセッションハンドラとして使用するには、この値を memcache と設定します。

session.save_path string

"tcp://host1:11211, tcp://host2:11211". セッションを格納するためのサーバーの URL を、カンマ区切りで指定します。 たとえば "tcp://host1:11211, tcp://host2:11211" のようになります。

個々の URL には、そのサーバー用のパラメータを含めることができます。 これは Memcache::addServer() メソッドと同じ形式です。 たとえば "tcp://host1:11211?persistent=1&weight=1&timeout=1&retry_interval=15" のようになります。


リソース型

memcache モジュールで使用されるリソースは 1 種類で、それは キャッシュサーバーとの接続を指す ID です。


定義済み定数

Memcache 定数
名前 | 説明
MEMCACHE_COMPRESSED (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() を実行する際に、同時にデータの圧縮を行います。
MEMCACHE_HAVE_SESSION (int) | この Memcache セッションハンドラが有効な場合に 1、それ以外の場合に 0 となります。
MEMCACHE_USER1 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。
MEMCACHE_USER2 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。
MEMCACHE_USER3 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。
MEMCACHE_USER4 (int) | Memcache::set()、 Memcache::add() そして Memcache::replace() でのユーザー定義のアプリケーションフラグとして使います。


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • Memcache
  • 例

例

目次

  • 基本的な使用法


基本的な使用法

例1 memcache 拡張モジュールの概要

この例では、オブジェクトをキャッシュに保存した後に、改めて取得しなおします。 オブジェクトやその他の非スカラー型のデータは、保存される前に シリアライズされます。そのため (接続 ID などの) リソース型を 保存することはできません。

<?php

$memcache = new Memcache;
$memcache->connect('localhost', 11211) or die ("接続できませんでした");

$version = $memcache->getVersion();
echo "サーバーのバージョン: ".$version."<br/>\n";

$tmp_object = new stdClass;
$tmp_object->str_attr = 'test';
$tmp_object->int_attr = 123;

$memcache->set('key', $tmp_object, false, 10) or die ("データをサーバーに保存できませんでした");
echo "データをキャッシュに保存します (データの有効期限は 10 秒です)<br/>\n";

$get_result = $memcache->get('key');
echo "キャッシュから取得したデータ:<br/>\n";

var_dump($get_result);

?>

例2 memcache セッションハンドラの使用例

<?php

$session_save_path = "tcp://$host:$port?persistent=1&weight=2&timeout=2&retry_interval=10, ,tcp://$host:$port ";
ini_set('session.save_handler', 'memcache');
ini_set('session.save_path', $session_save_path);

?>


Memcache クラス

(PECL memcache >= 0.2.0)

はじめに

memcache サーバーへの接続をあらわします。

クラス概要

class Memcache {
add(
string $key,
mixed $var,
int $flag = ?,
int $expire = ?
): bool
addServer(
string $host,
int $port = 11211,
bool $persistent = ?,
int $weight = ?,
int $timeout = ?,
int $retry_interval = ?,
bool $status = ?,
callable $failure_callback = ?,
int $timeoutms = ?
): bool
close(): bool
connect(string $host, int $port = ?, int $timeout = ?): bool
decrement(string $key, int $value = 1): int|false
delete(string $key, int $timeout = 0): bool
flush(): bool
get(string $key, int &$flags = ?): string
getExtendedStats(string $type = ?, int $slabid = ?, int $limit = 100): array
getServerStatus(string $host, int $port = 11211): int
getStats(string $type = ?, int $slabid = ?, int $limit = 100): array|false
getVersion(): string|false
increment(string $key, int $value = 1): int|false
pconnect(string $host, int $port = ?, int $timeout = ?): mixed
replace(
string $key,
mixed $var,
int $flag = ?,
int $expire = ?
): bool
set(
string $key,
mixed $var,
int $flag = ?,
int $expire = ?
): bool
setCompressThreshold(int $threshold, float $min_savings = ?): bool
setServerParams(
string $host,
int $port = 11211,
int $timeout = ?,
int $retry_interval = false,
bool $status = ?,
callable $failure_callback = ?
): bool
}

目次

  • Memcache::add — サーバーに項目を追加する
  • Memcache::addServer — コネクションプールに memcached サーバーを追加する
  • Memcache::close — memcached サーバーとの接続を閉じる
  • Memcache::connect — memcached サーバーへの接続をオープンする
  • Memcache::decrement — 項目の値を減らす
  • Memcache::delete — サーバーから項目を削除する
  • Memcache::flush — サーバー上のすべての既存項目を消去する
  • Memcache::get — サーバーから項目を取得する
  • Memcache::getExtendedStats — プール内のすべてのサーバーの統計情報を取得する
  • Memcache::getServerStatus — サーバーの状態を返す
  • Memcache::getStats — サーバーの統計情報を取得する
  • Memcache::getVersion — サーバーのバージョンを返す
  • Memcache::increment — 項目の値を増やす
  • Memcache::pconnect — memcached サーバーへの持続的な接続をオープンする
  • Memcache::replace — 既存項目の値を置換する
  • Memcache::set — データをサーバーに格納する
  • Memcache::setCompressThreshold — 大きな値に対する自動圧縮処理を有効にする
  • Memcache::setServerParams — サーバーのパラメータおよび状態を、実行時に変更する


サーバーに項目を追加する

  • ≪ Memcache
  • Memcache::addServer ≫
  • PHP Manual
  • Memcache
  • サーバーに項目を追加する

Memcache::add

(PECL memcache >= 0.2.0)

Memcache::add — サーバーに項目を追加する

説明

Memcache::add(
string $key,
mixed $var,
int $flag = ?,
int $expire = ?
): bool

Memcache::add() は、サーバーに同名のキーが存在しない 場合に限り、key というキーで 値 var を格納します。 memcache_add() 関数を使用することも可能です。

パラメータ

key

項目に関連付けられたキー。

var

格納する値。文字列および整数値はそのままの形式で、それ以外の型は シリアライズされて格納されます。

flag

項目を圧縮して格納する場合に MEMCACHE_COMPRESSED を使用します (zlib を使用します)。

expire

項目の有効期限。ゼロの場合は有効期限なし (いつまでも有効) となります。Unix タイムスタンプ形式、あるいは現在からの 秒数で指定することが可能ですが、後者の場合は秒数が 2592000 (30 日) を超えることはできません。

戻り値

成功した場合に true を、失敗した場合に false を返します。 もし同名のキーが既に存在する場合は false を返します。 それ以外は、Memcache::add() の振る舞いは Memcache::set() と同じです。

例

例1 Memcache::add() の例

<?php

$memcache_obj = memcache_connect("localhost", 11211);

/* 手続き型の API */
memcache_add($memcache_obj, 'var_key', 'test variable', false, 30);

/* オブジェクト指向の API */
$memcache_obj->add('var_key', 'test variable', false, 30);

?>

参考

  • Memcache::set() - データをサーバーに格納する
  • Memcache::replace() - 既存項目の値を置換する


コネクションプールに memcached サーバーを追加する

  • ≪ Memcache::add
  • Memcache::close ≫
  • PHP Manual
  • Memcache
  • コネクションプールに memcached サーバーを追加する

Memcache::addServer

(PECL memcache >= 2.0.0)

Memcache::addServer — コネクションプールに memcached サーバーを追加する

説明

Memcache::addServer(
string $host,
int $port = 11211,
bool $persistent = ?,
int $weight = ?,
int $timeout = ?,
int $retry_interval = ?,
bool $status = ?,
callable $failure_callback = ?,
int $timeoutms = ?
): bool

Memcache::addServer() は、コネクションプールに サーバーを追加します。 memcache_add_server() 関数を使用することも可能です。

(Memcache::connect() および Memcache::pconnect() ではなく) このメソッドを使用すると、ネットワーク接続は それが実際に必要となるときまで確立されません。 つまり、大量のサーバーをプールに追加した場合に、 それらすべてが使用されることはないとしてもオーバーヘッドが発生しないということです。

他のサーバーが使用可能である場合、あらゆるメソッドのあらゆる段階について ユーザーが意識しないままにフェイルオーバー処理が行われます。 ソケットあるいは Memcaches サーバーレベルで発生したあらゆるエラー (ただし out-of-memory は除く) に対してフェイルオーバーが動作します。 既存のキーを追加しようとしたなどの通常のクライアントエラーの場合は、 フェイルオーバー処理は起動しません。

注意:

この関数は、Memcache バージョン 2.0.0 で追加されました。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば unix:///path/to/memcached.sock のようにすると Unix ドメインソケットを使用できます。この場合、 port は 0 を指定しなければなりません。

port

memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを 0 とします。

port を指定しなかったときのデフォルトは memcache.default_port となります。そのため、このメソッドをコールするときにはポートを明示しておくことをおすすめします。

persistent

持続的な接続を使用するかどうかを指定します。 デフォルトは true です。

weight

このサーバーに対して割り当てる容器の数を指定します。これは、 このサーバーが選択される可能性を左右します。選択される可能性は、 すべてのサーバーの weight の合計に対するこのパラメータの割合で 決まります。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

retry_interval

サーバーとの接続が失敗した際に再試行を行う頻度を設定します。 デフォルト値は 15 秒です。このパラメータを -1 にすると、 自動的な再試行を行いません。 dl() を使用してこの拡張モジュールが動的に 読み込まれている場合は、このパラメータおよび persistent は何の効果も及ぼしません。

失敗した接続構造体は、個々にタイムアウト値を持っており、 タイムアウト時間が経過するまでは、バックエンドから新たな要求が来ても その構造体はスキップされます。時間が経過すると、 その接続が無事再接続されるか、あるいはさらに retry_interval 秒の間、接続失敗と記録されます。 典型的な効果は、ウェブサーバーの各子プロセスがページを送り出す際に retry_interval 秒ごとに接続を再試行することです。

status

サーバーがオンライン状態であるかどうかを制御します。このパラメータを false にし、retry_interval を -1 と設定すると、失敗したサーバーもコネクションプールに残します。 これにより、キー配布アルゴリズムに影響を与えないようにします。 このサーバーへのリクエストは、フェイルオーバーされるか失敗します。 どちらになるかは memcache.allow_failover の設定によって決まります。デフォルトは true で、 サーバーがオンライン状態であることを意味します。

failure_callback

エラーが発生した際に実行されるコールバック関数を指定できるようにします。 コールバック関数は、フェイルオーバー処理の前に実行されます。 この関数は、ふたつの引数 (ホスト名、失敗したサーバーのポート) を受け取ります。

timeoutms

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::addServer() の例

<?php

/* オブジェクト指向の API */

$memcache = new Memcache;
$memcache->addServer('memcache_host', 11211);
$memcache->addServer('memcache_host2', 11211);

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_add_server($memcache_obj, 'memcache_host2', 11211);

?>

注意

警告

port を省略した場合は、PHP の ini 設定 memcache.default_port の値をデフォルトとして使います。 もしこの値がアプリケーションのどこかで変更されていれば、予期せぬ結果を引き起こすかもしれません。 このメソッドをコールするときには、常にポートを明示しておくことをおすすめします。

参考

  • Memcache::connect() - memcached サーバーへの接続をオープンする
  • Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする
  • Memcache::close() - memcached サーバーとの接続を閉じる
  • Memcache::setServerParams() - サーバーのパラメータおよび状態を、実行時に変更する
  • Memcache::getServerStatus() - サーバーの状態を返す


memcached サーバーとの接続を閉じる

  • ≪ Memcache::addServer
  • Memcache::connect ≫
  • PHP Manual
  • Memcache
  • memcached サーバーとの接続を閉じる

Memcache::close

(PECL memcache >= 0.4.0)

Memcache::close — memcached サーバーとの接続を閉じる

説明

Memcache::close(): bool

Memcache::close() は、memcached サーバーとの接続を閉じます。 この関数は、持続的な接続については閉じません。持続的な接続が 閉じられるのは、Web サーバーのシャットダウン/再起動のときだけです。 memcache_close() 関数を使用することも可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::close() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/*
ここで何かを行います ..
*/
memcache_close($memcache_obj);

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/*
ここで何かを行います ..
*/
$memcache_obj->close();

?>

参考

  • Memcache::connect() - memcached サーバーへの接続をオープンする
  • Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする


memcached サーバーへの接続をオープンする

  • ≪ Memcache::close
  • Memcache::decrement ≫
  • PHP Manual
  • Memcache
  • memcached サーバーへの接続をオープンする

Memcache::connect

(PECL memcache >= 0.2.0)

Memcache::connect — memcached サーバーへの接続をオープンする

説明

Memcache::connect(string $host, int $port = ?, int $timeout = ?): bool

Memcache::connect() は、memcached サーバーへの接続を 確立します。 Memcache::connect() を使用してオープンされた接続は、 スクリプトの実行終了時に自動的に閉じられます。 Memcache::close() を使用して閉じることも可能です。 memcache_connect() 関数を使用することも可能です。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば unix:///path/to/memcached.sock のようにすると Unix ドメインソケットを使用できます。この場合、 port は 0 を指定しなければなりません。

port

memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを 0 とします。

port を指定しなかったときのデフォルトは memcache.default_port となります。そのため、このメソッドをコールするときにはポートを明示しておくことをおすすめします。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::connect() の例

<?php

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);

/* オブジェクト指向の API */

$memcache = new Memcache;
$memcache->connect('memcache_host', 11211);

?>

注意

警告

port を省略した場合は、PHP の ini 設定 memcache.default_port の値をデフォルトとして使います。 もしこの値がアプリケーションのどこかで変更されていれば、予期せぬ結果を引き起こすかもしれません。 このメソッドをコールするときには、常にポートを明示しておくことをおすすめします。

参考

  • Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする
  • Memcache::close() - memcached サーバーとの接続を閉じる


項目の値を減らす

  • ≪ Memcache::connect
  • Memcache::delete ≫
  • PHP Manual
  • Memcache
  • 項目の値を減らす

Memcache::decrement

(PECL memcache >= 0.2.0)

Memcache::decrement — 項目の値を減らす

説明

Memcache::decrement(string $key, int $value = 1): int|false

Memcache::decrement() は、項目の値を value だけ減らします。 Memcache::increment() と同様、項目の現在の値が まず数値に変換されてから value を引きます。

注意:

項目の新しい値をゼロより小さくすることはできません。

注意:

圧縮して格納されている項目に対して Memcache::decrement() を使用しないでください。 なぜなら、それ以降の Memcache::get() のコールが 失敗してしまうからです。

Memcache::decrement() は、指定した項目が 存在しない場合に項目を作成することは ありません。 memcache_decrement() 関数を使用することも可能です。

パラメータ

key

値を減らす項目のキー。

value

項目の値を value だけ減らします。

戻り値

項目の新しい値か、失敗した場合に false を返します。

例

例1 Memcache::decrement() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* 項目の値を 2 減らします */
$new_value = memcache_decrement($memcache_obj, 'test_item', 2);

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* 項目の値を 3 減らします */
$new_value = $memcache_obj->decrement('test_item', 3);
?>

参考

  • Memcache::increment() - 項目の値を増やす
  • Memcache::replace() - 既存項目の値を置換する


サーバーから項目を削除する

  • ≪ Memcache::decrement
  • Memcache::flush ≫
  • PHP Manual
  • Memcache
  • サーバーから項目を削除する

Memcache::delete

(PECL memcache >= 0.2.0)

Memcache::delete — サーバーから項目を削除する

説明

Memcache::delete(string $key, int $timeout = 0): bool

Memcache::delete() は、 key に対応する項目を削除します。

パラメータ

key

削除したい項目のキー。

timeout

この非推奨のパラメータはサポートしておらず、デフォルトで 0 秒になっています。 このパラメータを使ってはいけません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
Unknown | timeout パラメータを使うことは推奨しません。 このパラメータの挙動は memcached のバージョンによって異なりますが、 0 に設定しておけば安全です。 その他の値を指定すると、memcache の削除が失敗する原因となる可能性があります。

例

例1 Memcache::delete() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);

/* 項目をサーバーから削除します */
memcache_delete($memcache_obj, 'key_to_delete');

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);

$memcache_obj->delete('key_to_delete');

?>

参考

  • Memcache::set() - データをサーバーに格納する
  • Memcache::replace() - 既存項目の値を置換する


サーバー上のすべての既存項目を消去する

  • ≪ Memcache::delete
  • Memcache::get ≫
  • PHP Manual
  • Memcache
  • サーバー上のすべての既存項目を消去する

Memcache::flush

(PECL memcache >= 1.0.0)

Memcache::flush — サーバー上のすべての既存項目を消去する

説明

Memcache::flush(): bool

Memcache::flush() は、すべての既存項目を直ちに 無効にします。Memcache::flush() は 実際にリソースを開放するわけではなく、単にすべての項目に 有効期限切れのマークをつけるだけです。それらの項目が使用していた メモリは、新しい項目で上書きされるようになります。 memcache_flush() 関数を使用することも可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::flush() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);

memcache_flush($memcache_obj);

/* オブジェクト指向の API */

$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);

$memcache_obj->flush();

?>


サーバーから項目を取得する

  • ≪ Memcache::flush
  • Memcache::getExtendedStats ≫
  • PHP Manual
  • Memcache
  • サーバーから項目を取得する

Memcache::get

(PECL memcache >= 0.2.0)

Memcache::get — サーバーから項目を取得する

説明

Memcache::get(string $key, int &$flags = ?): string
Memcache::get(array $keys, array &$flags = ?): array

その時点でサーバー上の key にそのようなキーが存在する場合、 Memcache::get() は、前に格納されていたデータを返します。

Memcache::get() にキーの配列を渡すことにより、 値の配列を取得することができます。この配列には、サーバー上で見つかった キーと値のペアのみが含まれます。

パラメータ

key

取得したいキー (あるいはキーの配列)。

flags

存在した場合は、値とともに取得したフラグをここに書き込みます。 これらのフラグは、たとえば Memcache::set() に渡すものと同じです。int の最下位バイトは pecl/memcache で内部的に使用するために予約されています (たとえば圧縮やシリアライズに関する状態を表します)。

戻り値

key に関連付けられた値を返します。 key が配列の場合は、 見つかったキー・値のペアを配列で返します。 取得に失敗したり key が見つからなかったり、 あるいは key が空だったりした場合は false を返します。

例

例1 Memcache::get() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
$var = memcache_get($memcache_obj, 'some_key');

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
$var = $memcache_obj->get('some_key');

/*
キーの配列をパラメータとして使用することもできます。
もしキーに対応する項目がサーバー上で見つからなければ、
結果の配列の中にはそのキーは含まれません。
*/

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
$var = memcache_get($memcache_obj, Array('some_key', 'another_key'));

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
$var = $memcache_obj->get(Array('some_key', 'second_key'));

?>


プール内のすべてのサーバーの統計情報を取得する

  • ≪ Memcache::get
  • Memcache::getServerStatus ≫
  • PHP Manual
  • Memcache
  • プール内のすべてのサーバーの統計情報を取得する

Memcache::getExtendedStats

(PECL memcache >= 2.0.0)

Memcache::getExtendedStats — プール内のすべてのサーバーの統計情報を取得する

説明

Memcache::getExtendedStats(string $type = ?, int $slabid = ?, int $limit = 100): array

Memcache::getExtendedStats() は、サーバーの 統計情報を含む二次元の配列を返します。配列のキーが各サーバーの host:port に対応し、その値として個々のサーバーの統計情報を保持します。 取得に失敗したサーバーは、値に false が設定されます。 memcache_get_extended_stats() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.0.0 で追加されました。

パラメータ

type

取得する統計情報の型。使用可能な値は {reset, malloc, maps, cachedump, slabs, items, sizes} のいずれかです。 memcached プロトコルの仕様によると、これらの追加の引数は 「memcache の開発者の都合により、変更される可能性があります」 ということです。

slabid

type を cachedump と設定した場合に使用し、ダンプを取得する slab を指定します。 cachedump コマンドはサーバーと結びついており、デバッグ目的でのみ使用します。

limit

type を cachedump と設定した場合に使用し、ダンプするエントリの数を制限します。

警告

統計情報の型 cachedump は、セキュリティ上の理由により memcached デーモンから削除されました。

戻り値

サーバーの統計情報を含む二次元の配列を返します。失敗した場合は false を返します。

例

例1 Memcache::getExtendedStats() の例

<?php
$memcache_obj = new Memcache;
$memcache_obj->addServer('memcache_host', 11211);
$memcache_obj->addServer('failed_host', 11211);

$stats = $memcache_obj->getExtendedStats();
print_r($stats);
?>

上の例の出力は以下となります。

Array
(
    [memcache_host:11211] => Array
        (
            [pid] => 3756
            [uptime] => 603011
            [time] => 1133810435
            [version] => 1.1.12
            [rusage_user] => 0.451931
            [rusage_system] => 0.634903
            [curr_items] => 2483
            [total_items] => 3079
            [bytes] => 2718136
            [curr_connections] => 2
            [total_connections] => 807
            [connection_structures] => 13
            [cmd_get] => 9748
            [cmd_set] => 3096
            [get_hits] => 5976
            [get_misses] => 3772
            [bytes_read] => 3448968
            [bytes_written] => 2318883
            [limit_maxbytes] => 33554432
        )

    [failed_host:11211] => false
)

参考

  • Memcache::getVersion() - サーバーのバージョンを返す
  • Memcache::getStats() - サーバーの統計情報を取得する


サーバーの状態を返す

  • ≪ Memcache::getExtendedStats
  • Memcache::getStats ≫
  • PHP Manual
  • Memcache
  • サーバーの状態を返す

Memcache::getServerStatus

(PECL memcache >= 2.1.0)

Memcache::getServerStatus — サーバーの状態を返す

説明

Memcache::getServerStatus(string $host, int $port = 11211): int

Memcache::getServerStatus() は、サーバーがオンライン/オフラインのどちらであるかを返します。 memcache_get_server_status() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.1.0 で追加されました。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。

port

memcached が接続を待ち受けるポートを指定します。

戻り値

サーバーの状態を返します。サーバーに接続できなかった場合に 0、 それ以外の場合にはゼロ以外の値を返します。

例

例1 Memcache::getServerStatus() の例

<?php

/* オブジェクト指向の API */
$memcache = new Memcache;
$memcache->addServer('memcache_host', 11211);
echo $memcache->getServerStatus('memcache_host', 11211);

/* 手続き型の API */
$memcache = memcache_connect('memcache_host', 11211);
echo memcache_get_server_status($memcache, 'memcache_host', 11211);

?>

参考

  • Memcache::addServer() - コネクションプールに memcached サーバーを追加する
  • Memcache::setServerParams() - サーバーのパラメータおよび状態を、実行時に変更する


サーバーの統計情報を取得する

  • ≪ Memcache::getServerStatus
  • Memcache::getVersion ≫
  • PHP Manual
  • Memcache
  • サーバーの統計情報を取得する

Memcache::getStats

(PECL memcache >= 0.2.0)

Memcache::getStats — サーバーの統計情報を取得する

説明

Memcache::getStats(string $type = ?, int $slabid = ?, int $limit = 100): array|false

Memcache::getStats() は、サーバーの統計情報を含む 連想配列を返します。配列のキーが統計情報パラメータの名前、そして 配列の値がパラメータの値に対応します。 memcache_get_stats() 関数を使用することも可能です。

パラメータ

type

取得する統計情報の型。使用可能な値は {reset, malloc, maps, cachedump, slabs, items, sizes} のいずれかです。 memcached プロトコルの仕様によると、これらの追加の引数は 「memcache の開発者の都合により、変更される可能性があります」 ということです。

slabid

type を cachedump と設定した場合に使用し、ダンプを取得する slab を指定します。 cachedump コマンドはサーバーと結びついており、デバッグ目的でのみ使用します。

limit

type を cachedump と設定した場合に使用し、ダンプするエントリの数を制限します。

戻り値

サーバーの統計情報を含む連想配列を返します。 失敗した場合に false を返します。

参考

  • Memcache::getVersion() - サーバーのバージョンを返す
  • Memcache::getExtendedStats() - プール内のすべてのサーバーの統計情報を取得する


サーバーのバージョンを返す

  • ≪ Memcache::getStats
  • Memcache::increment ≫
  • PHP Manual
  • Memcache
  • サーバーのバージョンを返す

Memcache::getVersion

(PECL memcache >= 0.2.0)

Memcache::getVersion — サーバーのバージョンを返す

説明

Memcache::getVersion(): string|false

Memcache::getVersion() は、サーバーのバージョン番号を 文字列で返します。 memcache_get_version() 関数を使用することも可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

バージョン番号を表す文字列を返します。 失敗した場合に false を返します。

例

例1 Memcache::getVersion() の例

<?php

/* オブジェクト指向の API */
$memcache = new Memcache;
$memcache->connect('memcache_host', 11211);
echo $memcache->getVersion();

/* 手続き型の API */
$memcache = memcache_connect('memcache_host', 11211);
echo memcache_get_version($memcache);

?>

参考

  • Memcache::getExtendedStats() - プール内のすべてのサーバーの統計情報を取得する
  • Memcache::getStats() - サーバーの統計情報を取得する


項目の値を増やす

  • ≪ Memcache::getVersion
  • Memcache::pconnect ≫
  • PHP Manual
  • Memcache
  • 項目の値を増やす

Memcache::increment

(PECL memcache >= 0.2.0)

Memcache::increment — 項目の値を増やす

説明

Memcache::increment(string $key, int $value = 1): int|false

Memcache::increment() は、項目の値を value だけ増やします。 もし key に対応する値が数値ではなく、かつ 数値に変換できなかった場合は、その新しい値は value となります。 Memcache::increment() は、指定した項目が 存在しない場合に項目を作成することは ありません。

注意:

圧縮して格納されている項目に対して Memcache::increment() を使用しないでください。 なぜなら、それ以降の Memcache::get() のコールが 失敗してしまうからです。

memcache_increment() 関数を使用することも可能です。

パラメータ

key

値を増やす項目のキー。

value

項目の値を value だけ増やします。

戻り値

項目の新しい値か、失敗した場合に false を返します。

例

例1 Memcache::increment() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* カウンタを 2 増やします */
$current_value = memcache_increment($memcache_obj, 'counter', 2);

/* オブジェクト指向の API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* カウンタを 3 増やします */
$current_value = $memcache_obj->increment('counter', 3);

?>

参考

  • Memcache::decrement() - 項目の値を減らす
  • Memcache::replace() - 既存項目の値を置換する


memcached サーバーへの持続的な接続をオープンする

  • ≪ Memcache::increment
  • Memcache::replace ≫
  • PHP Manual
  • Memcache
  • memcached サーバーへの持続的な接続をオープンする

Memcache::pconnect

(PECL memcache >= 0.4.0)

Memcache::pconnect — memcached サーバーへの持続的な接続をオープンする

説明

Memcache::pconnect(string $host, int $port = ?, int $timeout = ?): mixed

Memcache::pconnect() は Memcache::connect() とほぼ同じですが、 確立する接続が持続的なものであるという点が違います。 この接続は、スクリプトの実行が終了したり Memcache::close() 関数を使ったりしても閉じません。 memcache_pconnect() 関数を使用することも可能です。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば unix:///path/to/memcached.sock のようにすると Unix ドメインソケットを使用できます。この場合、 port は 0 を指定しなければなりません。

port

memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを 0 とします。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

戻り値

Memcache オブジェクトを返します。 失敗した場合に false を返します。

例

例1 Memcache::pconnect() の例

<?php

/* 手続き型の API */
$memcache_obj = memcache_pconnect('memcache_host', 11211);

/* オブジェクト指向の API */

$memcache_obj = new Memcache;
$memcache_obj->pconnect('memcache_host', 11211);

?>

参考

  • Memcache::connect() - memcached サーバーへの接続をオープンする


既存項目の値を置換する

  • ≪ Memcache::pconnect
  • Memcache::set ≫
  • PHP Manual
  • Memcache
  • 既存項目の値を置換する

Memcache::replace

(PECL memcache >= 0.2.0)

Memcache::replace — 既存項目の値を置換する

説明

Memcache::replace(
string $key,
mixed $var,
int $flag = ?,
int $expire = ?
): bool

Memcache::replace() は、key
に対応する既存項目の値を置換するために使用します。
指定したキーに対応する項目がない場合は、
Memcache::replace() は false を返します。
それ以外の点では、Memcache::replace()
の振る舞いは Memcache::set() と同じです。
memcache_replace() 関数を使用することも可能です。

パラメータ

key

項目に関連付けられたキー。

var

格納する値。文字列および整数値はそのままの形式で、それ以外の型は シリアライズされて格納されます。

flag

項目を圧縮して格納する場合に MEMCACHE_COMPRESSED を使用します (zlib を使用します)。

expire

項目の有効期限。ゼロの場合は有効期限なし (いつまでも有効) となります。Unix タイムスタンプ形式、あるいは現在からの 秒数で指定することが可能ですが、後者の場合は秒数が 2592000 (30 日) を超えることはできません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::replace() の例

<?php

$memcache_obj = memcache_connect('memcache_host', 11211);

/* 手続き型の API */
memcache_replace($memcache_obj, "test_key", "some variable", false, 30);

/* オブジェクト指向の API */
$memcache_obj->replace("test_key", "some variable", false, 30);

?>

参考

  • Memcache::set() - データをサーバーに格納する
  • Memcache::add() - サーバーに項目を追加する


データをサーバーに格納する

  • ≪ Memcache::replace
  • Memcache::setCompressThreshold ≫
  • PHP Manual
  • Memcache
  • データをサーバーに格納する

Memcache::set

(PECL memcache >= 0.2.0)

Memcache::set — データをサーバーに格納する

説明

Memcache::set(
string $key,
mixed $var,
int $flag = ?,
int $expire = ?
): bool

Memcache::set() は、キー key に var という値を 関連付け、memcached サーバーに格納します。パラメータ expire は、データの有効期限を秒単位で指定します。もし 0 を指定した場合は その項目が期限切れになることはありません (これは、その項目のデータが memcached サーバー上にずっと残り続けることを保証するものではありません。 他の項目をキャッシュするための場所を確保するためにサーバーから 削除されてしまうこともあります)。 (zlib を使用して) その場でのデータの圧縮を行いたい場合は、 flag の値として、定数 MEMCACHE_COMPRESSED を指定します。

注意:

リソース型の変数 (たとえばファイル記述子や接続記述子など) はキャッシュに保存できないことを覚えておきましょう。これは、 シリアライズした状態ではそれらのデータを適切に表すことが できないためです。

memcache_set() 関数を使用することも可能です。

パラメータ

key

項目に関連付けられたキー。

var

格納する値。文字列および整数値はそのままの形式で、それ以外の型は シリアライズされて格納されます。

flag

項目を圧縮して格納する場合に MEMCACHE_COMPRESSED を使用します (zlib を使用します)。

expire

項目の有効期限。ゼロの場合は有効期限なし (いつまでも有効) となります。Unix タイムスタンプ形式、あるいは現在からの 秒数で指定することが可能ですが、後者の場合は秒数が 2592000 (30 日) を超えることはできません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::set() の例

<?php
/* 手続き型の API */

/* memcached サーバーに接続します */
$memcache_obj = memcache_connect('memcache_host', 11211);

/*
キー 'var_key' の項目の値を設定します。
flag の値として 0 を使用し、圧縮は使用しません。
有効期限は 30 秒です。
*/
memcache_set($memcache_obj, 'var_key', 'some variable', 0, 30);

echo memcache_get($memcache_obj, 'var_key');

?>

例2 Memcache::set() の例

<?php
/* オブジェクト指向の API */

$memcache_obj = new Memcache;

/* memcached サーバーに接続します */
$memcache_obj->connect('memcache_host', 11211);

/*
キー 'var_key' に対応する値を設定します。その際、データの圧縮を行います。
有効期限は 50 秒です。
*/
$memcache_obj->set('var_key', 'some really big variable', MEMCACHE_COMPRESSED, 50);

echo $memcache_obj->get('var_key');

?>

参考

  • Memcache::add() - サーバーに項目を追加する
  • Memcache::replace() - 既存項目の値を置換する


大きな値に対する自動圧縮処理を有効にする

  • ≪ Memcache::set
  • Memcache::setServerParams ≫
  • PHP Manual
  • Memcache
  • 大きな値に対する自動圧縮処理を有効にする

Memcache::setCompressThreshold

(PECL memcache >= 2.0.0)

Memcache::setCompressThreshold — 大きな値に対する自動圧縮処理を有効にする

説明

Memcache::setCompressThreshold(int $threshold, float $min_savings = ?): bool

Memcache::setCompressThreshold() は、 大きな値に対して自動圧縮処理を有効にします。 memcache_set_compress_threshold() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.0.0 で追加されました。

パラメータ

threshold

自動圧縮を試みる値の長さの最小値を指定します。

min_saving

値を圧縮する際の、最小の圧縮率を指定します。 値は 0 から 1 までの間で指定する必要があります。 デフォルト値は 0.2 で、最低 20% の圧縮を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::setCompressThreshold() の例

<?php

/* オブジェクト指向の API */

$memcache_obj = new Memcache;
$memcache_obj->addServer('memcache_host', 11211);
$memcache_obj->setCompressThreshold(20000, 0.2);

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_set_compress_threshold($memcache_obj, 20000, 0.2);

?>


サーバーのパラメータおよび状態を、実行時に変更する

  • ≪ Memcache::setCompressThreshold
  • Memcache 関数 ≫
  • PHP Manual
  • Memcache
  • サーバーのパラメータおよび状態を、実行時に変更する

Memcache::setServerParams

(PECL memcache >= 2.1.0)

Memcache::setServerParams — サーバーのパラメータおよび状態を、実行時に変更する

説明

Memcache::setServerParams(
string $host,
int $port = 11211,
int $timeout = ?,
int $retry_interval = false,
bool $status = ?,
callable $failure_callback = ?
): bool

Memcache::setServerParams() は、 サーバーのパラメータを実行時に変更します。 memcache_set_server_params() 関数を使用することも可能です。

注意:

この関数は、Memcache バージョン 2.1.0 で追加されました。

パラメータ

host

memcached が接続を待ち受けるホストを指定します。

port

memcached が接続を待ち受けるポートを指定します。

timeout

デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。

retry_interval

サーバーとの接続が失敗した際に再試行を行う頻度を設定します。 デフォルト値は 15 秒です。このパラメータを -1 にすると、 自動的な再試行を行いません。 dl() を使用してこの拡張モジュールが動的に 読み込まれている場合は、このパラメータおよび persistent は何の効果も及ぼしません。

status

サーバーがオンライン状態であるかどうかを制御します。このパラメータを false にし、retry_interval を -1 と設定すると、失敗したサーバーもコネクションプールに残します。 これにより、キー配布アルゴリズムに影響を与えないようにします。 このサーバーへのリクエストは、フェイルオーバーされるか失敗します。 どちらになるかは memcache.allow_failover の設定によって決まります。デフォルトは true で、 サーバーがオンライン状態であることを意味します。

failure_callback

エラーが発生した際に実行されるコールバック関数を指定できるようにします。 コールバック関数は、フェイルオーバー処理の前に実行されます。 この関数は、ふたつの引数 (ホスト名、失敗したサーバーのポート) を受け取ります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcache::setServerParams() の例

<?php

function _callback_memcache_failure($host, $port) {
print "memcache '$host:$port' failed";
}

/* オブジェクト指向の API */

$memcache = new Memcache;

// サーバーをオフラインモードで追加します
$memcache->addServer('memcache_host', 11211, false, 1, 1, -1, false);

// サーバーをオンラインに変更します
$memcache->setServerParams('memcache_host', 11211, 1, 15, true, '_callback_memcache_failure');

/* 手続き型の API */

$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_set_server_params($memcache_obj, 'memcache_host', 11211, 1, 15, true, '_callback_memcache_failure');

?>

参考

  • Memcache::addServer() - コネクションプールに memcached サーバーを追加する
  • Memcache::getServerStatus() - サーバーの状態を返す


  • ≪ Memcache::setServerParams
  • memcache_debug ≫
  • PHP Manual
  • Memcache
  • Memcache 関数

Memcache 関数

目次

  • memcache_debug — デバッグ出力のオン/オフを切り替える


デバッグ出力のオン/オフを切り替える

  • ≪ Memcache 関数
  • Memcached ≫
  • PHP Manual
  • Memcache 関数
  • デバッグ出力のオン/オフを切り替える

memcache_debug

(PECL memcache >= 0.2.0)

memcache_debug — デバッグ出力のオン/オフを切り替える

説明

memcache_debug(bool $on_off): bool

memcache_debug() は、パラメータ on_off が true の場合にデバッグ出力を有効にし、 false の場合には無効にします。

注意:

memcache_debug() は、PHP が --enable-debug オプションをつけてビルドされている場合にのみ使用可能で、 この場合は常に true を返します。そうでない場合は、この関数は 何も行わずに常に false を返します。

パラメータ

on_off

true にすると、デバッグ出力をオンにします。 false にすると、デバッグ出力をオフにします。

戻り値

PHP が --enable-debug オプションをつけてビルドされている場合に true、それ以外の場合に false を返します。


Memcached

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 有効期限
  • コールバック
    • Result コールバック
    • Read-through キャッシュコールバック
  • セッションのサポート
  • Memcached — Memcached クラス
    • Memcached::add — アイテムを新しいキーで追加する
    • Memcached::addByKey — 指定したサーバーにアイテムを新しいキーで追加する
    • Memcached::addServer — サーバーをサーバープールに追加する
    • Memcached::addServers — 複数のサーバーをサーバープールに追加する
    • Memcached::append — データを既存のアイテムに追記する
    • Memcached::appendByKey — 指定したサーバーでデータを既存のアイテムに追記する
    • Memcached::cas — アイテムを比較して入れ替える
    • Memcached::casByKey — 指定したサーバーでアイテムを比較して入れ替える
    • Memcached::__construct — Memcached のインスタンスを作成する
    • Memcached::decrement — 数値アイテムの値を減らす
    • Memcached::decrementByKey — 指定したサーバー上にある数値アイテムの値を減らす
    • Memcached::delete — アイテムを削除する
    • Memcached::deleteByKey — 指定したサーバーからアイテムを削除する
    • Memcached::deleteMulti — 複数のアイテムを削除する
    • Memcached::deleteMultiByKey — 指定したサーバーから複数のアイテムを削除する
    • Memcached::fetch — 次の結果を取得する
    • Memcached::fetchAll — 残りのすべての結果を取得する
    • Memcached::flush — キャッシュ内のすべてのアイテムを無効にする
    • Memcached::get — アイテムを取得する
    • Memcached::getAllKeys — すべてのサーバーのキーを取得する
    • Memcached::getByKey — 指定したサーバーからアイテムを取得する
    • Memcached::getDelayed — 複数のアイテムを要求する
    • Memcached::getDelayedByKey — 指定したサーバーに複数のアイテムを要求する
    • Memcached::getMulti — 複数のアイテムを取得する
    • Memcached::getMultiByKey — 指定したサーバーから複数のアイテムを取得する
    • Memcached::getOption — Memcached のオプションの値を取得する
    • Memcached::getResultCode — 直近の操作の結果コードを返す
    • Memcached::getResultMessage — 最後に実行した操作の結果を説明したメッセージを返す。
    • Memcached::getServerByKey — キーとサーバーを関連付ける
    • Memcached::getServerList — プール内のサーバーの一覧を取得する
    • Memcached::getStats — サーバープールの統計情報を取得する
    • Memcached::getVersion — サーバープールのバージョン情報を取得する
    • Memcached::increment — 数値アイテムの値を増やす
    • Memcached::incrementByKey — 指定したサーバー上にある数値アイテムの値を増やす
    • Memcached::isPersistent — memcache への接続で持続的接続を使っているかどうかを調べる
    • Memcached::isPristine — 直近に作られたインスタンスかどうかを調べる
    • Memcached::prepend — 既存のアイテムの前にデータを付加する
    • Memcached::prependByKey — 指定したサーバーで既存のアイテムの前にデータを付加する
    • Memcached::quit — 開いている接続を閉じる
    • Memcached::replace — 既存のキーのアイテムを入れ替える
    • Memcached::replaceByKey — 指定したサーバーで既存のキーのアイテムを入れ替える
    • Memcached::resetServerList — サーバーリストからすべてのサーバーを消去する
    • Memcached::set — アイテムを格納する
    • Memcached::setByKey — 指定したサーバーにアイテムを格納する
    • Memcached::setMulti — 複数のアイテムを格納する
    • Memcached::setMultiByKey — 指定したサーバーで複数のアイテムを格納する
    • Memcached::setOption — Memcached のオプションの値を設定する
    • Memcached::setOptions — Memcached のオプションの値を設定する
    • Memcached::setSaslAuthData — 認証用の資格情報を設定する
    • Memcached::touch — アイテムに新しい有効期限を設定する
    • Memcached::touchByKey — 指定したサーバー上のアイテムに新しい有効期限を設定する
  • MemcachedException — MemcachedException クラス


はじめに

» memcached は、 ハイパフォーマンスな分散型メモリオブジェクトキャッシュシステムです。汎用的ですが、 データベース読み込みの負荷を軽減することで動的なウェブアプリケーションの速度を向上させることを意図しています。

この拡張モジュールは、libmemcached ライブラリを使用して memcached サーバーとの通信用の API を提供しています。 また、セッション ハンドラ (memcached) も用意しています。

libmemcached に関する情報は » http://libmemcached.org/libMemcached.html をご覧ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Memcached
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

この拡張モジュールには » libmemcached クライアントライブラリ (バージョン 1.0.0 以降) が必要です。 SASL 認証に対応するには、libmemcached をビルドするときに SASL を有効にしておかないといけません。

バージョン 0.2.0 以降、この拡張モジュールは PHP 5.2.0 以降が必須となりました。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/memcached.

libmemcached のインストール先が標準の場所とは異なる場合は --with-libmemcached-dir=DIR スイッチを使用します。 ここで、DIR は libmemcached のインストールプレフィックスを表します。 このディレクトリ内に include/libmemcached/memcached.h がなければなりません。

圧縮をサポートするには Zlib が必要です。Zlib のインストール先が標準の場所とは異なる場合は、--with-zlib-dir=DIR スイッチを使用します。 ここで、DIR は Zlib のインストールプレフィックスを表します。

セッションハンドラのサポートはデフォルトで有効となります。これを無効にするには --disable-memcached-session スイッチを使用します。

SASL 認証のサポートはデフォルトで無効になっています。これを有効にするには --enable-memcached-sasl スイッチを使用します。 このスイッチを使うには、libsasl2 がインストールされていて、 かつ libmemcached のビルド時に SASL のサポートを有効にしておく必要があります。


実行時設定

php.ini の設定により動作が変化します。

Memcached 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
memcached.sess_locking | On | INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.sess_consistent_hash | On | INI_ALL | memcached 2.1.0 以降で利用可能です。memcached 3.0.0 以降は、デフォルト値は On です。
memcached.sess_binary | Off | INI_ALL | memcached 2.0.0 以降で利用可能です。memcached 3.0.0 以降は、memcached.sess_binary_protocol に置き換えられました。
memcached.sess_lock_wait | 150000 | INI_ALL | memcached 0.1.0 以降で利用可能ですが、memcached 3.0.0 以降では削除されています。
memcached.sess_prefix | memc.sess.key. | INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.sess_number_of_replicas | 0 | INI_ALL | memcached 2.1.0 以降で利用可能です。
memcached.sess_randomize_replica_read | Off | INI_ALL | memcached 2.1.0 以降で利用可能です。
memcached.sess_remove_failed | On | INI_ALL | memcached 2.1.0 以降で利用可能です。memcached 3.0.0 以降は、memcached.sess_remove_failed_servers に置き換えられました。
memcached.compression_type | fastlz | INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.compression_factor | 1.3 | INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.compression_threshold | 2000 | INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.serializer | igbinary | INI_ALL | memcached 0.1.0 以降で利用可能です。
memcached.use_sasl | Off | INI_ALL | memcached 2.2.0 以降で利用可能ですが、memcached 3.0.0 以降では削除されています。
memcached.default_binary_protocol | Off | INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.default_connect_timeout | 0 | INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.default_consistent_hash | Off | INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_binary_protocol | On | INI_ALL | memcached 3.0.0 以降で利用可能です。memcached.sess_binary を置き換えるものです。
memcached.sess_connect_timeout | 1000 | INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.sess_consistent_hash_type | ketama | INI_ALL | memcached 3.1.0 以降で利用可能です。
memcached.sess_lock_expire | 0 | INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.sess_lock_retries | 5 | INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_lock_wait_max | 150 | INI_ALL | memcached 3.0.0 以降で利用可能です。デフォルト値は memcached 3.1.0 以降は 150 です (それより前のバージョンでは 2000 でした)。
memcached.sess_lock_wait_min | 150 | INI_ALL | memcached 3.0.0 以降で利用可能です。デフォルト値は memcached 3.1.0 以降は 150 です (それより前のバージョンでは 1000 でした)。
memcached.sess_persistent | Off | INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_remove_failed_servers | Off | INI_ALL | memcached 3.0.0 以降で利用可能です。memcached.sess_remove_failed を置き換えるものです。
memcached.sess_server_failure_limit | 0 | INI_ALL | memcached 3.0.0 以降で利用可能です。
memcached.sess_sasl_password | null | INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.sess_sasl_username | null | INI_ALL | memcached 2.2.0 以降で利用可能です。
memcached.store_retry_count | 0 | INI_ALL | memcached 2.2.0 以降で利用可能です。 memcached 3.2.0 以降では、デフォルト値は 0 です。 (それより前のバージョンでは、2 でした)

以下に設定ディレクティブに関する 簡単な説明を示します。

memcached.sess_locking bool

セッション単位のロックを使う。設定値として On, Off が使えます。デフォルトは On です。

memcached.sess_consistent_hash bool

On にすると、セッション管理に コンシステント・ハッシュ法 (libketama) を使います。 コンシステント・ハッシュ法を使うと、既存のキーに煩わされることなく ノードを追加したり削除したりできます。デフォルトは On です。

memcached.sess_binary bool

セッション管理にmemcachedのバイナリプロトコルを使います。 Libmemcached のレプリカはこのバイナリモードが有効になっている場合にのみ動作します。 デフォルトは Off です。

memcached.sess_lock_wait int

セッションデータを書き込むときの spin lock の待ち時間をマイクロ秒単位で指定します。 この値を設定するときは注意してください。数値の値が設定できますが、 0 はデフォルトの値を使うと解釈されます。負の値を設定するとロックを掛けようと試みる 回数が減ってしまいます。デフォルトは 150000 です。

memcached.sess_prefix string

セッション管理に使うキーのプレフィックスです。 219バイト以下の文字列が使えます。デフォルトの値は memc.sess.key です。

memcached.sess_number_of_replicas int

データを書き込む、 追加の memcached サーバーの数を指定します。 これは、libmemcached が "poor man's HA" と呼んでいるものです。 この値が0より大きく、sess_remove_failed_servers が 有効な場合、 memcached サーバーがダウンした時にセッションはレプリカを使って継続されます。 しかし、ダウンした memcached サーバーが再び復帰した場合は、 セッションは古いデータを持つセッションを読みとる場合もありますし、 データを全く読み取れない場合もあります。デフォルト値は 0 です。

memcached.sess_randomize_replica_read bool

複数のサーバーのレプリカからセッションデータを読み取る際、読み取りを始める最初のサーバーをランダムに選ぶかを指定します。

memcached.sess_remove_failed int

通信に失敗した memcached サーバーを自動的にサーバーリストから外すかを指定します。

memcached.compression_type string

圧縮のタイプを指定します。fastlz, zlib が指定できます。デフォルトは fastlz です。

memcached.compression_factor float

圧縮係数。圧縮後のサイズが圧縮係数の限界値を超えていた場合にだけ値を圧縮して保存します。 元のサイズ > 圧縮後のサイズ * 圧縮係数の場合にだけ値を圧縮して保存します。 デフォルト値は 1.3 (23%強の圧縮率) です。

memcached.compression_threshold int

圧縮のしきい値。このしきい値を下回るシリアライズ済みの値は圧縮しません。 デフォルトは 2000 バイトです。

memcached.serializer string

新しい memcached オブジェクトのデフォルトのシリアライザを設定します。設定値として php, igbinary, json, json_array, msgpack が使えます。

json

標準的な JSON を使います。このシリアライザは高速でコンパクトですが、UTF-8 でエンコードされたデータでしか動作しませんし、完全なシリアライズを実装していません。詳細は JSON拡張モジュール を参照ください。 memcached 0.2.0 以降で利用可能です。

json_array

json と同じですが、シリアライズしたデータを配列に入れます。 memcached 2.0.0 以降で利用可能です。

php

標準的なPHPのシリアライザです。

igbinary

バイナリデータのシリアライザです。 memcached 0.1.4 以降で利用可能です。

msgpack

言語に依存しない、バイナリデータのシリアライザです。 memcached 2.2.0 以降で利用可能です。

デフォルトは 利用可能な場合 igbinary です。 igbinary が利用できない場合は msgpack が(利用可能な場合のみ) デフォルトになります。 いずれも利用できない場合は、php がデフォルトになります。

memcached.use_sasl bool

接続時に SASL認証 を使います。設定値として On, Off が使えます。デフォルトは Off です。

memcached.default_binary_protocol bool

新しい接続で使う、デフォルトの memcached プロトコルを設定します (セッションで使う memcached プロトコルを設定するには、 memcached.sess_binary_protocol を代わりに使って下さい)。 On にすると、memcached バイナリプロトコルをデフォルトで使います。 Off にすると、memcached テキストプロトコルを使います。 デフォルトは Off です。

memcached.default_connect_timeout int

新しい接続で使う、デフォルトの memcached の接続タイムアウト値を設定します (セッションで使う memcached の接続タイムアウト値を設定するには、 memcached.sess_connect_timeout を代わりに使って下さい)。 ノンブロッキングモードの場合、この値は ソケット接続中のタイムアウトの値をミリ秒単位で変更します。 -1 を指定すると、タイムアウトしません。 0 を指定すると、memcached ライブラリのデフォルトの接続タイムアウト値を使います。 デフォルトは 0 です。

memcached.default_consistent_hash bool

新しい接続で使う、デフォルトの コンシステント・ハッシュ法を指定します (セッションで使う コンシステント・ハッシュ法 を設定するには、 memcached.sess_consistent_hash を代わりに使って下さい)。 On にすると、セッション管理に コンシステント・ハッシュ法 (libketama) を使います。 コンシステント・ハッシュ法を使うと、既存のキーに煩わされることなく キャッシュノードを追加したり削除したりできます。デフォルトは Off です。

memcached.sess_binary_protocol bool

memcached でセッション管理を行う場合に、 memcached text プロトコルではなく memcached バイナリプロトコル を使うように指定します。 これは、libmemcached レプリカのバイナリモードが有効になっている場合にのみ有効です。 バイナリプロトコルが無効な場合にのみ動作するプロキシ(たとえば、twemproxy) もあります。 デフォルト値は libmemcached 1.0.18 以降は On です。 それより前のバージョンでは Off になっています。

注意: php-memcached の以前のバージョンでは、この設定は memcached.sess_binary と呼ばれていました。

memcached.sess_connect_timeout int

memcached の接続タイムアウト値を指定します。 ノンブロッキングモードの場合、この値は ソケット接続中のタイムアウトの値をミリ秒単位で変更します。 -1 を指定すると、タイムアウトしません。

memcached.sess_consistent_hash_type string

Memcached のセッション管理で使う、コンシステント・ハッシュ法を指定します。 ketama を指定すると、セッション管理にコンシステント・ハッシュ(libketama) を使います。 これは php-memcached 3.x のデフォルトです。 ketama_weighted を指定すると、重み付きのコンシステント・ハッシュ(libketama) をセッション管理に使います。 デフォルトは ketama です。 php-memcached 3.0 より前のバージョンでは、デフォルトは ketama_weighted でした。

memcached.sess_lock_expire int

ロックが解放されるまでの時間を秒単位で指定します。 0 を指定すると、デフォルトの動作になります。 つまり、PHP の max_execution_time の値を使います。 デフォルト値は 0 です。

memcached.sess_lock_retries int

セッションのロックを取得するためのリトライ回数を指定します。 この値には、最初の試行は含まれません。 デフォルト値は 5 です。

memcached.sess_lock_wait_max int

セッションのロック取得を試みる際に、 それぞれの試行の間に待つ最大の時間をミリ秒単位で指定します。 デフォルト値は 150 です。

memcached.sess_lock_wait_min int

セッションのロック取得を試みる際に、 それぞれの試行の間に待つ最小の時間をミリ秒単位で指定します。 ロック取得のリトライを行うたびに、memcached.sess_lock_wait_max に達するまで、 現在のリトライ時間を2倍して待ちます。 その後は、memcached.sess_lock_wait_max の間待ちます。 デフォルト値は 150 です。

memcached.sess_persistent bool

スクリプトの実行が終了した後、session.save_path に対応する memcached 接続を再利用するかどうかを指定します。 特定の設定 (たとえば SASL 設定や, sess_binary_protocol) がリクエスト間で上書きされる場合は、 この設定を使ってはいけません。 デフォルト値は Off です。

memcached.sess_remove_failed_servers bool

ダウンした memcahced サーバーを自動的に削除する機能を有効にします。 デフォルト値は Off です。

注意: 前のバージョンでは、この設定は memcached.sess_remove_failed と呼ばれていました。

memcached.sess_server_failure_limit int

指定した回数接続が失敗した場合に、サーバーを削除する機能を有効にします。 デフォルト値は 0 です。

memcached.sess_sasl_password string

セッションの SASL パスワードを指定します。 SASL を有効にするには、ユーザー名とパスワードを両方指定する必要があります。

memcached.sess_sasl_username string

セッションの SASL ユーザ名を指定します。 SASL を有効にするには、ユーザー名とパスワードを両方指定する必要があります。

memcached.store_retry_count int

store コマンドが失敗した場合に、行うリトライの回数を指定します。 この仕組みを使うと、 複数サーバー構成で set/increment/decrement/setMulti 操作が失敗した場合に、 セカンダリサーバーへ透過的なフェイルオーバーを行うことが出来ます。 デフォルト値は 2 です。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Memcached::OPT_COMPRESSION

ペイロードの圧縮を有効あるいは無効にします。有効にすると、 一定の閾値 (現在は 100 バイト) を超える長さのアイテムは 格納時に圧縮され、取得時に伸長されます。この操作は透過的に行われます。

型: bool、デフォルト: true

Memcached::OPT_SERIALIZER

非スカラ値のシリアライズに使うシリアライザを指定します。 有効なシリアライザは Memcached::SERIALIZER_PHP あるいは Memcached::SERIALIZER_IGBINARY です。 後者のシリアライザをサポートするのは memcached の configure 時に --enable-memcached-igbinary オプションを指定して igbinary 拡張を読み込んだときだけです。

型: int、デフォルト: Memcached::SERIALIZER_PHP

Memcached::SERIALIZER_PHP

デフォルトの PHP シリアライザ。

Memcached::SERIALIZER_IGBINARY

» igbinary シリアライザ。 テキスト表現ではなく、PHP のデータ構造をコンパクトなバイナリ形式で格納します。 その結果、容量と時間を節約できます。

Memcached::SERIALIZER_JSON

JSON シリアライザ。

Memcached::OPT_PREFIX_KEY

これを使うと、アイテムのキーに「ドメイン」を作成できます。 ここで指定した値がキーの名前の先頭に付きます。 128 文字より長くはできず、 ここで指定した値の分だけキーに指定できる長さが小さくなります。 プレフィックスが付くのはアイテムのキーだけであり、 サーバーのキーには付きません。

型: string、デフォルト: ""

Memcached::OPT_HASH

アイテムのキーに使うハッシュアルゴリズムを指定します。 有効な値は、定数 Memcached::HASH_* のいずれかです。 どのハッシュアルゴリズムにもそれぞれ利点や欠点があります。 よくわからない場合やあまり難しく考えたくない場合はデフォルトで進めましょう。

型: int、デフォルト: Memcached::HASH_DEFAULT

Memcached::HASH_DEFAULT

デフォルトのハッシュアルゴリズム (Jenkins one-at-a-time)。

Memcached::HASH_MD5

MD5 ハッシュアルゴリズム。

Memcached::HASH_CRC

CRC ハッシュアルゴリズム。

Memcached::HASH_FNV1_64

FNV1_64 ハッシュアルゴリズム。

Memcached::HASH_FNV1A_64

FNV1_64A ハッシュアルゴリズム。

Memcached::HASH_FNV1_32

FNV1_32 ハッシュアルゴリズム。

Memcached::HASH_FNV1A_32

FNV1_32A ハッシュアルゴリズム。

Memcached::HASH_HSIEH

Hsieh ハッシュアルゴリズム。

Memcached::HASH_MURMUR

Murmur ハッシュアルゴリズム。

Memcached::OPT_DISTRIBUTION

アイテムのキーをサーバーに振り分ける方式を指定します。 現在サポートしている方式は、モジュロとコンシステント・ハッシュの二種類です。 コンシステント・ハッシュのほうがよりうまく分散させられ、 サーバーをクラスタに追加するときにもキャッシュのロスを最小限に抑えられます。

型: int、デフォルト: Memcached::DISTRIBUTION_MODULA

Memcached::DISTRIBUTION_MODULA

モジュロベースのキー分散アルゴリズム。

Memcached::DISTRIBUTION_CONSISTENT

コンシステント・ハッシュを使ったキー分散アルゴリズム (libketama を利用)。

Memcached::OPT_LIBKETAMA_COMPATIBLE

libketama 風の挙動との互換性を有効あるいは無効にします。 有効にすると、アイテムのキーのハッシュアルゴリズムは MD5、 そして分散方式は重み付きコンシステント・ハッシュになります。 これを使うと、他の libketama ベースのクライアント (Python や Ruby など) を同じサーバー設定で使え、キーも透過的にアクセスできるようになるので有用です。

注意:

コンシステント・ハッシュを使うときは、このオプションを有効にしておくことを強く推奨します。 将来のリリースでは、これはデフォルトで有効になる予定です。

型: bool、デフォルト: false

Memcached::OPT_BUFFER_WRITES

バッファ入出力を有効あるいは無効にします。 バッファ入出力を有効にすると、ストレージへのコマンドを送信する代わりに 「バッファ」に向けるようになります。 データを取得するアクションを実行すると、このバッファをリモート接続に送信します。 接続を終了したり閉じたりしたときも、バッファに入ったデータをリモート接続に送信します。

型: bool、デフォルト: false

Memcached::OPT_BINARY_PROTOCOL

バイナリプロトコルを使えるようにします。 既に開いている接続ではこのオプションを切り替えられないことに注意しましょう。

型: bool、デフォルト: false

Memcached::OPT_NO_BLOCK

非同期入出力を有効あるいは無効にします。 これは、ストレージ関数で使える転送の中でも最も高速なものです。

型: bool、デフォルト: false

Memcached::OPT_NOREPLY

ストレージへのコマンド (set, add, replace, append, prepend, delete, increment, decrement など) の実行結果を無視するか、しないかを指定します。 ストレージへのコマンドは、送信された後、応答を待つのに時間を使いません。 (応答がない場合もあります) Memcached::get() のように、 データを取得するコマンドは、この設定による影響を受けません。

型: bool、デフォルト: false.

Memcached::OPT_TCP_NODELAY

ソケット接続用のno-delay機能 (環境によってはそのほうが高速化する) を有効あるいは無効にします。

型: bool、デフォルト: false

Memcached::OPT_SOCKET_SEND_SIZE

バッファに送信するソケットの最大のバイト数。

型: int、デフォルト: プラットフォームやカーネルの設定によって異なる

Memcached::OPT_SOCKET_RECV_SIZE

ソケットの受信バッファの最大のバイト数。

The maximum socket receive buffer in bytes.

型: int、デフォルト: プラットフォームやカーネルの設定によって異なる

Memcached::OPT_CONNECT_TIMEOUT

非ブロックモードの場合、ここにはソケット接続のタイムアウト値をミリ秒単位で指定します。

型: int、デフォルト: 1000

Memcached::OPT_RETRY_TIMEOUT

接続に失敗したときに、どれだけ失敗するまで接続を再試行するかどうかを、秒数で表す。

型: int、デフォルト: 0

Memcached::OPT_SEND_TIMEOUT

ソケットの送信タイムアウトをマイクロ秒で指定します。 非ブロックモードの入出力を使えない場合でも、 これを使ってデータ送信のタイムアウトを指定できます。

型: int、デフォルト: 0

Memcached::OPT_RECV_TIMEOUT

ソケットの読み込みタイムアウトをマイクロ秒で指定します。 非ブロックモードの入出力を使えない場合でも、 これを使ってデータ読み込みのタイムアウトを指定できます。

型: int、デフォルト: 0

Memcached::OPT_POLL_TIMEOUT

接続をポーリングする際のタイムアウト時間をミリ秒単位で指定します。

型: int、デフォルト: 1000

Memcached::OPT_CACHE_LOOKUPS

DNS ルックアップのキャッシュを有効あるいは無効にします。

型: bool、デフォルト: false

Memcached::OPT_SERVER_FAILURE_LIMIT

サーバーへの接続の最大試行回数を指定します。 指定した回数だけ接続の失敗が続くと、サーバーが削除されます。

型: int、デフォルト: 0

Memcached::HAVE_IGBINARY

igbqinary シリアライザのサポートが有効かどうかを示します。

型: bool

Memcached::HAVE_JSON

JSON シリアライザのサポートが有効かどうかを示します。

型: bool

Memcached::HAVE_MSGPACK

msgpack シリアライザのサポートが有効かどうかを示します。

Type: bool

Memcached 3.0.0 以降で使用可能です。

Memcached::HAVE_SESSION

Type: bool

Memcached 3.0.0 以降で使用可能です。

Memcached::HAVE_SASL

Type: bool

Memcached 3.0.0 以降で使用可能です。

Memcached::GET_EXTENDED

Memcached::get(), Memcached::getMulti(), Memcached::getMultiByKey() が CASトークンの値も返すかを保証するフラグ

Memcached 3.0.0 以降で使用可能です。

Memcached::GET_PRESERVE_ORDER

Memcached::getMulti() や Memcached::getMultiByKey() のフラグで、 リクエストしたときと同じ順番でキーを返すことを示します。 存在しないキーを指定すると、デフォルト値の NULL を返します。

Memcached::RES_SUCCESS

実行しようとした操作が成功したことを示します。

Memcached::RES_FAILURE

実行しようとした操作が何らかの点で失敗したことを示します。

Memcached::RES_HOST_LOOKUP_FAILURE

DNSの名前解決が失敗したことを示します。

Memcached::RES_UNKNOWN_READ_FAILURE

ネットワーク経由でのデータの読み取りに失敗したことを示します。

Memcached::RES_PROTOCOL_ERROR

memcached プロトコル内で不正なコマンドが実行されたことを示します。

Memcached::RES_CLIENT_ERROR

クライアント側でエラーが起きたことを示します。

Memcached::RES_SERVER_ERROR

サーバー側でエラーが起きたことを示します。

Memcached::RES_WRITE_FAILURE

ネットワーク経由でのデータの書き込みに失敗したことを示します。

Memcached::RES_DATA_EXISTS

比較と交換に失敗したことを示します。格納しようとしたアイテムは、 最後に取得したあとで変更されています。

Memcached::RES_NOTSTORED

アイテムが格納されなかったが、その原因はエラーではないということを示します。 これは通常、"add" や "replace" コマンドの要件を満たさなかったか あるいはアイテムが削除キューに入っていることを意味します。

Memcached::RES_NOTFOUND

このキーのアイテムが ("get" や "cas" の操作で) 見つからなかったことを示します。

Memcached::RES_PARTIAL_READ

ネットワーク経由でのデータの読み取りが一部失敗したことを示します。

Memcached::RES_SOME_ERRORS

multi-get を実行中にエラーが発生したことを示します。

Memcached::RES_NO_SERVERS

サーバーリストが空であることを示します。

Memcached::RES_END

結果セットの末尾を示します。

Memcached::RES_ERRNO

システムエラーを示します。

Memcached::RES_BUFFERED

実行している操作がバッファリングされていることを示します。

Memcached::RES_TIMEOUT

実行がタイムアウトしたことを示します。

Memcached::RES_BAD_KEY_PROVIDED

不正なキーを与えたことを示します。

Memcached::RES_CONNECTION_SOCKET_CREATE_FAILURE

ネットワークソケットの作成が失敗したことを示します。

Memcached::RES_PAYLOAD_FAILURE

ペイロードに関するエラー: つまり、値を シリアライズ/復元 したり、圧縮/解凍 することができなかったことを示します。

Memcached::RES_AUTH_PROBLEM

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_AUTH_FAILURE

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_AUTH_CONTINUE

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_E2BIG

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_KEY_TOO_BIG

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_SERVER_TEMPORARILY_DISABLED

Memcached 3.0.0 以降で使用可能です。

Memcached::RES_SERVER_MEMORY_ALLOCATION_FAILURE

Memcached 3.0.0 以降で使用可能です。


有効期限

格納用コマンドの中には、(アイテム単位あるいはクライアントから要求された操作単位の) 有効期限をサーバーに送信するものがあります。そのような場合に実際に送られる値は、 Unix タイム (1970 年 1 月 1 日からの経過秒数) あるいは現在時刻からの秒数となります。 後者の場合、最大の秒数は 60*60*24*30 (30 日間をあらわす秒数) までとなります。 もし有効期限がそれより長い場合は、現在時刻からの経過秒数ではなく Unix タイムであるとサーバーにみなされてしまいます。

有効期限を 0 (デフォルト) にすると、 アイテムは期限切れにならなくなります (しかし、他のアイテム用の場所を確保するためにサーバーから削除されることもありえます)。


  • ≪ 有効期限
  • Result コールバック ≫
  • PHP Manual
  • Memcached
  • コールバック

コールバック

目次

  • Result コールバック
  • Read-through キャッシュコールバック


Result コールバック

Result callable が起動されるのは、 Memcached::getDelayed() あるいは Memcached::getDelayedBykey() メソッドで結果セットの各アイテムに対してコールしたときです。 このコールバックに渡されるのは、Memcached オブジェクトと、 アイテム情報を含む配列です。 このコールバックは何も返す必要がありません。

例1 Result コールバックの例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$items = array(
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
);
$m->setMulti($items);
$m->getDelayed(array('key1', 'key3'), true, 'result_cb');

function result_cb($memc, $item)
{
var_dump($item);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["key"]=>
  string(4) "key1"
  ["value"]=>
  string(6) "value1"
  ["cas"]=>
  float(49)
}
array(3) {
  ["key"]=>
  string(4) "key3"
  ["value"]=>
  string(6) "value3"
  ["cas"]=>
  float(50)
}


Read-through キャッシュコールバック

Read-through キャッシュコールバックが起動されるのは、 アイテムをサーバーから取得できなかったときです。 このコールバックに渡されるのは Memcached オブジェクト、 要求されたキー、そして値を格納する変数への参照です。 このコールバックの役割は、値を設定して true あるいは false を返すことです。 コールバックが true を返した場合は、 Memcached は設定された値をサーバーに格納して呼び出し元の関数にその値を返します。 このコールバックをサポートしているのは Memcached::get() と Memcached::getByKey() のみです。 というのも memcache プロトコルでは、 複数のキーが要求されたときにどのキーが見つからなかったのかを知る方法がないからです。

例1 Read-through コールバックの例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$profile_info = $m->get('user:'.$user_id, 'user_info_cb');

function user_info_cb($memc, $key, &$value)
{
$user_id = substr($key, 5);
/* プロファイル情報を DB から探します */
/* ... */
$value = $profile_info;
return true;
}
?>


セッションのサポート

Memcached は独自のセッションハンドラを用意しており、 これを使用するとユーザーセッションを memcache に格納することができます。 内部的に使用するのは完全に分離された memcached インスタンスなので、 必要に応じて別のサーバープールを使用することができます。 セッションのキーは、プレフィックス memc.sess.key. をつけて格納されます。 同じサーバープールでセッションと一般のキャッシュを両方使用する場合は注意しましょう。

session.save_handler string

memcached を設定すると、セッションのサポートが有効となります。

session.save_path string

ホスト名:ポート 形式のエントリをカンマ区切りで指定します。 これをセッションサーバープールとして使用します。たとえば "sess1:11211, sess2:11211" のようになります。


Memcached クラス

(PECL memcached >= 0.1.0)

はじめに

memcached サーバー群への接続を表します。

クラス概要

class Memcached {
/* メソッド */
public __construct(?string $persistent_id = null, ?callable $callback = null, ?string $connection_str = null)
public add(string $key, mixed $value, int $expiration = 0): bool
public addByKey(
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool
public addServer(string $host, int $port, int $weight = 0): bool
public addServers(array $servers): bool
public append(string $key, string $value): ?bool
public appendByKey(string $server_key, string $key, string $value): ?bool
public cas(
string|int|float $cas_token,
string $key,
mixed $value,
int $expiration = 0
): bool
public casByKey(
string|int|float $cas_token,
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool
public decrement(
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false
public decrementByKey(
string $server_key,
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false
public delete(string $key, int $time = 0): bool
public deleteByKey(string $server_key, string $key, int $time = 0): bool
public deleteMulti(array $keys, int $time = 0): array
public deleteMultiByKey(string $server_key, array $keys, int $time = 0): array
public fetch(): array|false
public fetchAll(): array|false
public flush(int $delay = 0): bool
public get(string $key, ?callable $cache_cb = null, int $get_flags = 0): mixed
public getAllKeys(): array|false
public getByKey(
string $server_key,
string $key,
?callable $cache_cb = null,
int $get_flags = 0
): mixed
public getDelayed(array $keys, bool $with_cas = false, ?callable $value_cb = null): bool
public getDelayedByKey(
string $server_key,
array $keys,
bool $with_cas = false,
?callable $value_cb = null
): bool
public getMulti(array $keys, int $get_flags = 0): array|false
public getMultiByKey(string $server_key, array $keys, int $get_flags = 0): array|false
public getOption(int $option): mixed
public getResultCode(): int
public getResultMessage(): string
public getServerByKey(string $server_key): array|false
public getServerList(): array
public getStats(?string $type = null): array|false
public getVersion(): array|false
public increment(
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false
public incrementByKey(
string $server_key,
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false
public isPersistent(): bool
public isPristine(): bool
public prepend(string $key, string $value): ?bool
public prependByKey(string $server_key, string $key, string $value): ?bool
public quit(): bool
public replace(string $key, mixed $value, int $expiration = 0): bool
public replaceByKey(
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool
public resetServerList(): bool
public set(string $key, mixed $value, int $expiration = 0): bool
public setByKey(
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool
public setMulti(array $items, int $expiration = 0): bool
public setMultiByKey(string $server_key, array $items, int $expiration = 0): bool
public setOption(int $option, mixed $value): bool
public setOptions(array $options): bool
public setSaslAuthData(string $username, string $password): bool
public touch(string $key, int $expiration = 0): bool
public touchByKey(string $server_key, string $key, int $expiration = 0): bool
}

目次

  • Memcached::add — アイテムを新しいキーで追加する
  • Memcached::addByKey — 指定したサーバーにアイテムを新しいキーで追加する
  • Memcached::addServer — サーバーをサーバープールに追加する
  • Memcached::addServers — 複数のサーバーをサーバープールに追加する
  • Memcached::append — データを既存のアイテムに追記する
  • Memcached::appendByKey — 指定したサーバーでデータを既存のアイテムに追記する
  • Memcached::cas — アイテムを比較して入れ替える
  • Memcached::casByKey — 指定したサーバーでアイテムを比較して入れ替える
  • Memcached::__construct — Memcached のインスタンスを作成する
  • Memcached::decrement — 数値アイテムの値を減らす
  • Memcached::decrementByKey — 指定したサーバー上にある数値アイテムの値を減らす
  • Memcached::delete — アイテムを削除する
  • Memcached::deleteByKey — 指定したサーバーからアイテムを削除する
  • Memcached::deleteMulti — 複数のアイテムを削除する
  • Memcached::deleteMultiByKey — 指定したサーバーから複数のアイテムを削除する
  • Memcached::fetch — 次の結果を取得する
  • Memcached::fetchAll — 残りのすべての結果を取得する
  • Memcached::flush — キャッシュ内のすべてのアイテムを無効にする
  • Memcached::get — アイテムを取得する
  • Memcached::getAllKeys — すべてのサーバーのキーを取得する
  • Memcached::getByKey — 指定したサーバーからアイテムを取得する
  • Memcached::getDelayed — 複数のアイテムを要求する
  • Memcached::getDelayedByKey — 指定したサーバーに複数のアイテムを要求する
  • Memcached::getMulti — 複数のアイテムを取得する
  • Memcached::getMultiByKey — 指定したサーバーから複数のアイテムを取得する
  • Memcached::getOption — Memcached のオプションの値を取得する
  • Memcached::getResultCode — 直近の操作の結果コードを返す
  • Memcached::getResultMessage — 最後に実行した操作の結果を説明したメッセージを返す。
  • Memcached::getServerByKey — キーとサーバーを関連付ける
  • Memcached::getServerList — プール内のサーバーの一覧を取得する
  • Memcached::getStats — サーバープールの統計情報を取得する
  • Memcached::getVersion — サーバープールのバージョン情報を取得する
  • Memcached::increment — 数値アイテムの値を増やす
  • Memcached::incrementByKey — 指定したサーバー上にある数値アイテムの値を増やす
  • Memcached::isPersistent — memcache への接続で持続的接続を使っているかどうかを調べる
  • Memcached::isPristine — 直近に作られたインスタンスかどうかを調べる
  • Memcached::prepend — 既存のアイテムの前にデータを付加する
  • Memcached::prependByKey — 指定したサーバーで既存のアイテムの前にデータを付加する
  • Memcached::quit — 開いている接続を閉じる
  • Memcached::replace — 既存のキーのアイテムを入れ替える
  • Memcached::replaceByKey — 指定したサーバーで既存のキーのアイテムを入れ替える
  • Memcached::resetServerList — サーバーリストからすべてのサーバーを消去する
  • Memcached::set — アイテムを格納する
  • Memcached::setByKey — 指定したサーバーにアイテムを格納する
  • Memcached::setMulti — 複数のアイテムを格納する
  • Memcached::setMultiByKey — 指定したサーバーで複数のアイテムを格納する
  • Memcached::setOption — Memcached のオプションの値を設定する
  • Memcached::setOptions — Memcached のオプションの値を設定する
  • Memcached::setSaslAuthData — 認証用の資格情報を設定する
  • Memcached::touch — アイテムに新しい有効期限を設定する
  • Memcached::touchByKey — 指定したサーバー上のアイテムに新しい有効期限を設定する


アイテムを新しいキーで追加する

  • ≪ Memcached
  • Memcached::addByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを新しいキーで追加する

Memcached::add

(PECL memcached >= 0.1.0)

Memcached::add — アイテムを新しいキーで追加する

説明

public Memcached::add(string $key, mixed $value, int $expiration = 0): bool

Memcached::add() は Memcached::set() と似ていますが、 key が既にサーバー上に存在する場合は失敗します。

パラメータ

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 キーが既に存在する場合は、Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::addByKey() - 指定したサーバーにアイテムを新しいキーで追加する
  • Memcached::set() - アイテムを格納する
  • Memcached::replace() - 既存のキーのアイテムを入れ替える


指定したサーバーにアイテムを新しいキーで追加する

  • ≪ Memcached::add
  • Memcached::addServer ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーにアイテムを新しいキーで追加する

Memcached::addByKey

(PECL memcached >= 0.1.0)

Memcached::addByKey — 指定したサーバーにアイテムを新しいキーで追加する

説明

public Memcached::addByKey(
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool

Memcached::addByKey() は機能的に Memcached::add() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 キーが既に存在する場合は、Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::add() - アイテムを新しいキーで追加する
  • Memcached::set() - アイテムを格納する
  • Memcached::replace() - 既存のキーのアイテムを入れ替える


サーバーをサーバープールに追加する

  • ≪ Memcached::addByKey
  • Memcached::addServers ≫
  • PHP Manual
  • Memcached
  • サーバーをサーバープールに追加する

Memcached::addServer

(PECL memcached >= 0.1.0)

Memcached::addServer — サーバーをサーバープールに追加する

説明

public Memcached::addServer(string $host, int $port, int $weight = 0): bool

Memcached::addServer() は、指定したサーバーをサーバープールに追加します。 この時点では、サーバーへの接続は確立されません。しかし、一貫性のあるキー分散オプションを (Memcached::DISTRIBUTION_CONSISTENT あるいは Memcached::OPT_LIBKETAMA_COMPATIBLE で) 指定した場合は、 内部データ構造のうちの一部が更新されます。 したがって、もし複数のサーバーを追加したい場合は、 Memcached::addServers() を使用するほうがよいでしょう。 その場合、更新は一度しか発生しません。

同じサーバーがサーバープール内で複数回あらわれることもあります。 重複チェックはしていないからです。これは望ましい状態ではありません。 その代わりに weight オプションを使用して、 このサーバーを選択する重みを増やします。

パラメータ

host

memcache サーバーのホスト名。ホスト名が無効な場合は、データ関連の操作の結果コードに Memcached::RES_HOST_LOOKUP_FAILURE が設定されます。 バージョン 2.0.0b1 以降では、このパラメータにソケットのパス (/path/to/memcached.sock など) を指定すると、 UNIX ドメインソケットを使えるようになりました。 このとき、port には 0 を設定する必要があります。

port

memcache が動作しているポート。通常、これは 11211 となります。 バージョン 2.0.0b1 以降では、UNIX ドメインソケットを利用する際には 0 を設定します。

weight

プール内の全サーバーにおけるそのサーバーの重み。 これで、何か操作をしたときにそのサーバーが選択される確率を制御します。 これは、一貫性のある分散オプションを使っている場合にのみ使用でき、 通常はそのサーバー上で memcache が使用できるメモリの量に対応したものとなります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached::addServer() の例

<?php
$m = new Memcached();

/* 2 つのサーバーを追加し、2 番目のサーバーが
最初のサーバーの 2 倍の確率で選択されるようにします */
$m->addServer('mem1.domain.com', 11211, 33);
$m->addServer('mem2.domain.com', 11211, 67);
?>

参考

  • Memcached::addServers() - 複数のサーバーをサーバープールに追加する
  • Memcached::resetServerList() - サーバーリストからすべてのサーバーを消去する


複数のサーバーをサーバープールに追加する

  • ≪ Memcached::addServer
  • Memcached::append ≫
  • PHP Manual
  • Memcached
  • 複数のサーバーをサーバープールに追加する

Memcached::addServers

(PECL memcached >= 0.1.1)

Memcached::addServers — 複数のサーバーをサーバープールに追加する

説明

public Memcached::addServers(array $servers): bool

Memcached::addServers() は、 servers をサーバープールに追加します。 servers の各エントリは、 個々のサーバーのホスト名、ポート、重み (オプション) を含む配列となります。 この時点では、サーバーへの接続は確立されません。

同じサーバーがサーバープール内で複数回あらわれることもあります。 重複チェックはしていないからです。これは望ましい状態ではありません。 その代わりに weight オプションを使用して、 このサーバーを選択する重みを増やします。

パラメータ

array

プールに追加するサーバーの配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached::addServers() の例

<?php
$m = new Memcached();

$servers = array(
array('mem1.domain.com', 11211, 33),
array('mem2.domain.com', 11211, 67)
);
$m->addServers($servers);
?>

参考

  • Memcached::addServer() - サーバーをサーバープールに追加する
  • Memcached::resetServerList() - サーバーリストからすべてのサーバーを消去する


データを既存のアイテムに追記する

  • ≪ Memcached::addServers
  • Memcached::appendByKey ≫
  • PHP Manual
  • Memcached
  • データを既存のアイテムに追記する

Memcached::append

(PECL memcached >= 0.1.0)

Memcached::append — データを既存のアイテムに追記する

説明

public Memcached::append(string $key, string $value): ?bool

Memcached::append() は、指定した文字列 value を既存のアイテムの値として追記します。 value を文字列に強制変換する理由は、 異なる型を追記した場合の挙動が定義されていないからです。

注意:

Memcached::OPT_COMPRESSION が有効になっている場合は、 この操作は失敗して警告が発せられます。 すでに圧縮されている可能性のあるデータに圧縮したデータを追記することはできないからです。

パラメータ

key

値の格納先のキー。

value

追記する文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。 圧縮が有効になっている場合は null を返します。

エラー / 例外

圧縮が有効になっている場合は null を返し、 E_WARNING が発生します。

例

例1 Memcached::append() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$m->setOption(Memcached::OPT_COMPRESSION, false);

$m->set('foo', 'abc');
$m->append('foo', 'def');
var_dump($m->get('foo'));
?>

上の例の出力は以下となります。

string(6) "abcdef"

参考

  • Memcached::appendByKey() - 指定したサーバーでデータを既存のアイテムに追記する
  • Memcached::prepend() - 既存のアイテムの前にデータを付加する


指定したサーバーでデータを既存のアイテムに追記する

  • ≪ Memcached::append
  • Memcached::cas ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーでデータを既存のアイテムに追記する

Memcached::appendByKey

(PECL memcached >= 0.1.0)

Memcached::appendByKey — 指定したサーバーでデータを既存のアイテムに追記する

説明

public Memcached::appendByKey(string $server_key, string $key, string $value): ?bool

Memcached::appendByKey() は機能的に Memcached::append() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

追記する文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。 圧縮が有効になっている場合は null を返します。

エラー / 例外

圧縮が有効になっている場合は null を返し、 E_WARNING が発生します。

参考

  • Memcached::append() - データを既存のアイテムに追記する
  • Memcached::prepend() - 既存のアイテムの前にデータを付加する


アイテムを比較して入れ替える

  • ≪ Memcached::appendByKey
  • Memcached::casByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを比較して入れ替える

Memcached::cas

(PECL memcached >= 0.1.0)

Memcached::cas — アイテムを比較して入れ替える

説明

public Memcached::cas(
string|int|float $cas_token,
string $key,
mixed $value,
int $expiration = 0
): bool

Memcached::cas() は「チェックして設定」という操作を行います。 アイテムが格納されるのは、クライアントが最後にアイテムを取得して以降に 他のクライアントによるそのアイテムの更新がなかった場合のみです。 チェックは cas_token パラメータを使用して行います。 これは一意な 64 ビットの値で、既存のアイテムに対して memcache が割り当てます。 このトークンを取得する方法については Memcached::get*() メソッドのドキュメントを参照ください。 PHP の integer 型の範囲を超えるため、トークンは float 型であらわされることに注意しましょう。

パラメータ

cas_token

既存のアイテムに割り当てたれた一意な値。memcache が生成します。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 格納しようとしているアイテムが最後の取得以降に更新されている場合、 Memcached::getResultCode() は Memcached::RES_DATA_EXISTS を返します。

例

例1 Memcached::cas() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

do {
/* IP リストとそのトークンを取得します */
$ips = $m->get('ip_block', null, $cas);
/* リストが存在しない場合はまず作成してからアトミック名追加を行います。
誰かがすでに追加している場合は失敗します */
if ($m->getResultCode() == Memcached::RES_NOTFOUND) {
$ips = array($_SERVER['REMOTE_ADDR']);
$m->add('ip_block', $ips);
/* それ以外の場合は、IP をリストに追加して、トークンによる「比較して入れ替え」
方式で格納します。だれかがリストを更新している場合は失敗します */
} else {
$ips[] = $_SERVER['REMOTE_ADDR'];
$m->cas($cas, 'ip_block', $ips);
}
} while ($m->getResultCode() != Memcached::RES_SUCCESS);

?>

参考

  • Memcached::casByKey() - 指定したサーバーでアイテムを比較して入れ替える


指定したサーバーでアイテムを比較して入れ替える

  • ≪ Memcached::cas
  • Memcached::__construct ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーでアイテムを比較して入れ替える

Memcached::casByKey

(PECL memcached >= 0.1.0)

Memcached::casByKey — 指定したサーバーでアイテムを比較して入れ替える

説明

public Memcached::casByKey(
string|int|float $cas_token,
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool

Memcached::casByKey() は機能的に Memcached::cas() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

cas_token

既存のアイテムに割り当てたれた一意な値。memcache が生成します。

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 格納しようとしているアイテムが最後の取得以降に更新されている場合、 Memcached::getResultCode() は Memcached::RES_DATA_EXISTS を返します。

参考

  • Memcached::cas() - アイテムを比較して入れ替える


Memcached のインスタンスを作成する

  • ≪ Memcached::casByKey
  • Memcached::decrement ≫
  • PHP Manual
  • Memcached
  • Memcached のインスタンスを作成する

Memcached::__construct

(PECL memcached >= 0.1.0)

Memcached::__construct — Memcached のインスタンスを作成する

説明

public Memcached::__construct(?string $persistent_id = null, ?callable $callback = null, ?string $connection_str = null)

memcache サーバーとの接続を表す Memcached インスタンスを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

persistent_id

デフォルトでは、Memcached のインスタンスはリクエストの終了時に破棄されます。 リクエスト間で持続するインスタンスを作成するには、 persistent_id でそのインスタンスの一意な ID を指定します。 同じ persistent_id で作られたすべてのインスタンスは同じ接続を共有します。

callback

connection_str

例

例1 Memcached オブジェクトの作成

<?php
/* 通常のインスタンスを作成します */
$m = new Memcached();
echo get_class($m);

/* 持続するインスタンスを作成します */
$m2 = new Memcached('story_pool');
$m3 = new Memcached('story_pool');

/* これで $m2 と $m3 は同じ接続を共有するようになります */
?>


数値アイテムの値を減らす

  • ≪ Memcached::__construct
  • Memcached::decrementByKey ≫
  • PHP Manual
  • Memcached
  • 数値アイテムの値を減らす

Memcached::decrement

(PECL memcached >= 0.1.0)

Memcached::decrement — 数値アイテムの値を減らす

説明

public Memcached::decrement(
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false

Memcached::decrement() は、数値アイテムの値を offset で指定しただけ減らします。 アイテムの値が数値でない場合はエラーとなります。 操作後の値が 0 より小さくなる場合は、新しい値は 0 となります。 アイテムが存在しない場合、Memcached::decrement() は値を initial_value に設定します。

パラメータ

key

減らしたいアイテムのキー。

offset

値を減らしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

戻り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

例

例1 Memcached::decrement() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('counter', 5);
$n = $m->decrement('counter');
var_dump($n);

$n = $m->decrement('counter', 10);
var_dump($n);

var_dump($m->get('counter'));

$m->set('counter', 'abc');
$n = $m->increment('counter');
// アイテムの値が数値でないので、これは失敗します
var_dump($n);
?>

上の例の出力は以下となります。

int(4)
int(0)
int(0)
bool(false)

参考

  • Memcached::increment() - 数値アイテムの値を増やす
  • Memcached::incrementByKey() - 指定したサーバー上にある数値アイテムの値を増やす
  • Memcached::decrementByKey() - 指定したサーバー上にある数値アイテムの値を減らす


指定したサーバー上にある数値アイテムの値を減らす

  • ≪ Memcached::decrement
  • Memcached::delete ≫
  • PHP Manual
  • Memcached
  • 指定したサーバー上にある数値アイテムの値を減らす

Memcached::decrementByKey

(PECL memcached >= 2.0.0)

Memcached::decrementByKey — 指定したサーバー上にある数値アイテムの値を減らす

説明

public Memcached::decrementByKey(
string $server_key,
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false

Memcached::decrementByKey() は、数値アイテムの値を offset で指定しただけ減らします。 アイテムの値が数値でない場合はエラーとなります。 操作後の値が 0 より小さくなる場合は、新しい値は 0 となります。 アイテムが存在しない場合、Memcached::decrementByKey() は値を initial_value に設定します。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

減らしたいアイテムのキー。

offset

値を減らしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

戻り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

参考

  • Memcached::decrement() - 数値アイテムの値を減らす
  • Memcached::increment() - 数値アイテムの値を増やす
  • Memcached::incrementByKey() - 指定したサーバー上にある数値アイテムの値を増やす


アイテムを削除する

  • ≪ Memcached::decrementByKey
  • Memcached::deleteByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを削除する

Memcached::delete

(PECL memcached >= 0.1.0)

Memcached::delete — アイテムを削除する

説明

public Memcached::delete(string $key, int $time = 0): bool

key をサーバーから削除します。

パラメータ

key

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

注意: memcached 1.3.0 (2009年リリース) 以降は、 この機能はサポートされなくなりました。 ゼロでない time を渡すと、 削除は失敗します。 Memcached::getResultCode() は MEMCACHED_INVALID_ARGUMENTS を返します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

例

例1 Memcached::delete() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->delete('key1');
?>

参考

  • Memcached::deleteByKey() - 指定したサーバーからアイテムを削除する
  • Memcached::deleteMulti() - 複数のアイテムを削除する


指定したサーバーからアイテムを削除する

  • ≪ Memcached::delete
  • Memcached::deleteMulti ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーからアイテムを削除する

Memcached::deleteByKey

(PECL memcached >= 0.1.0)

Memcached::deleteByKey — 指定したサーバーからアイテムを削除する

説明

public Memcached::deleteByKey(string $server_key, string $key, int $time = 0): bool

Memcached::deleteByKey() は機能的に Memcached::delete() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

注意: memcached 1.3.0 (2009年リリース) 以降は、 この機能はサポートされなくなりました。 ゼロでない time を渡すと、 削除は失敗します。 Memcached::getResultCode() は MEMCACHED_INVALID_ARGUMENTS を返します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

参考

  • Memcached::delete() - アイテムを削除する
  • Memcached::deleteMulti() - 複数のアイテムを削除する
  • Memcached::deleteMultiByKey() - 指定したサーバーから複数のアイテムを削除する


複数のアイテムを削除する

  • ≪ Memcached::deleteByKey
  • Memcached::deleteMultiByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを削除する

Memcached::deleteMulti

(PECL memcached >= 2.0.0)

Memcached::deleteMulti — 複数のアイテムを削除する

説明

public Memcached::deleteMulti(array $keys, int $time = 0): array

キーの配列 keys をサーバーから削除します。

パラメータ

keys

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

注意: memcached 1.3.0 (2009年リリース) 以降は、 この機能はサポートされなくなりました。 ゼロでない time を渡すと、 削除は失敗します。 Memcached::getResultCode() は MEMCACHED_INVALID_ARGUMENTS を返します。

戻り値

keys をキーとした配列を返します。 それぞれの要素には、 対応するキーが削除された場合に true が入ります。 対応するキーの削除が失敗した場合、 定数 Memcached::RES_* のうちの一つが入ります。

Memcached::getResultCode() は、 最後に行われた削除操作の結果コードを返します。 つまり、keys の最後の要素に対する削除操作の結果を返します。

参考

  • Memcached::delete() - アイテムを削除する
  • Memcached::deleteByKey() - 指定したサーバーからアイテムを削除する
  • Memcached::deleteMultiByKey() - 指定したサーバーから複数のアイテムを削除する


指定したサーバーから複数のアイテムを削除する

  • ≪ Memcached::deleteMulti
  • Memcached::fetch ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーから複数のアイテムを削除する

Memcached::deleteMultiByKey

(PECL memcached >= 2.0.0)

Memcached::deleteMultiByKey — 指定したサーバーから複数のアイテムを削除する

説明

public Memcached::deleteMultiByKey(string $server_key, array $keys, int $time = 0): array

Memcached::deleteMultiByKey() は機能的に Memcached::deleteMulti() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

keys

削除したいキー。

time

サーバーがアイテムを削除するまでの待ち時間。

注意: memcached 1.3.0 (2009年リリース) 以降は、 この機能はサポートされなくなりました。 ゼロでない time を渡すと、 削除は失敗します。 Memcached::getResultCode() は MEMCACHED_INVALID_ARGUMENTS を返します。

戻り値

keys をキーとした配列を返します。 それぞれの要素には、 対応するキーが削除された場合に true が入ります。 対応するキーの削除が失敗した場合、 定数 Memcached::RES_* のうちの一つが入ります。

Memcached::getResultCode() は、 最後に行われた削除操作の結果コードを返します。 つまり、keys の最後の要素に対する削除操作の結果を返します。

参考

  • Memcached::delete() - アイテムを削除する
  • Memcached::deleteByKey() - 指定したサーバーからアイテムを削除する
  • Memcached::deleteMulti() - 複数のアイテムを削除する


次の結果を取得する

  • ≪ Memcached::deleteMultiByKey
  • Memcached::fetchAll ≫
  • PHP Manual
  • Memcached
  • 次の結果を取得する

Memcached::fetch

(PECL memcached >= 0.1.0)

Memcached::fetch — 次の結果を取得する

説明

public Memcached::fetch(): array|false

Memcached::fetch() は、直近のリクエストから次の結果を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

次の結果、あるいは false を返します。 結果セットをすべて処理し終えた場合、 Memcached::getResultCode() は Memcached::RES_END を返します。

例

例1 Memcached::fetch() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));

$m->getDelayed(array('int', 'array'), true);
while ($result = $m->fetch()) {
var_dump($result);
}
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["key"]=>
  string(3) "int"
  "value"]=>
  int(99)
  ["cas"]=>
  float(2363)
}
array(3) {
  ["key"]=>
  string(5) "array"
  ["value"]=>
  array(2) {
    [0]=>
    int(11)
    [1]=>
    int(12)
  }
  ["cas"]=>
  float(2365)
}

参考

  • Memcached::fetchAll() - 残りのすべての結果を取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する


残りのすべての結果を取得する

  • ≪ Memcached::fetch
  • Memcached::flush ≫
  • PHP Manual
  • Memcached
  • 残りのすべての結果を取得する

Memcached::fetchAll

(PECL memcached >= 0.1.0)

Memcached::fetchAll — 残りのすべての結果を取得する

説明

public Memcached::fetchAll(): array|false

Memcached::fetchAll() は、 直近のリクエストで残っているすべての結果を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

結果、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getDelayed() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));

$m->getDelayed(array('int', 'array'), true);
var_dump($m->fetchAll());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["key"]=>
    string(3) "int"
    ["value"]=>
    int(99)
    ["cas"]=>
    float(2363)
  }
  [1]=>
  array(3) {
    ["key"]=>
    string(5) "array"
    ["value"]=>
    array(2) {
      [0]=>
      int(11)
      [1]=>
      int(12)
    }
    ["cas"]=>
    float(2365)
  }
}

参考

  • Memcached::fetch() - 次の結果を取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する


キャッシュ内のすべてのアイテムを無効にする

  • ≪ Memcached::fetchAll
  • Memcached::get ≫
  • PHP Manual
  • Memcached
  • キャッシュ内のすべてのアイテムを無効にする

Memcached::flush

(PECL memcached >= 0.1.0)

Memcached::flush — キャッシュ内のすべてのアイテムを無効にする

説明

public Memcached::flush(int $delay = 0): bool

Memcached::flush() は、既存のキャッシュ内のすべてのアイテムを即時 (デフォルト) あるいは指定した delay の後に無効化します。 無効化した後は、取得系のコマンドには一切アイテムを返さなくなります (Memcached::flush() がアイテムを無効化したあとで同名のキーを改めて格納した場合は別です)。 既存のアイテムが確保していたメモリはその時点では開放されません。 新しいアイテムが格納されるたびに徐々に開放されていきます。

パラメータ

delay

アイテムの無効化までに待機する秒数。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::flush() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

/* 全アイテムを 10 秒後にフラッシュします */
$m->flush(10);
?>


アイテムを取得する

  • ≪ Memcached::flush
  • Memcached::getAllKeys ≫
  • PHP Manual
  • Memcached
  • アイテムを取得する

Memcached::get

(PECL memcached >= 0.1.0)

Memcached::get — アイテムを取得する

説明

public Memcached::get(string $key, ?callable $cache_cb = null, int $get_flags = 0): mixed

Memcached::get() は、キー key に格納されたアイテムを返します。 アイテムが存在して get_flags に Memcached::GET_EXTENDED が指定されていた場合には、 そのアイテムの CAS トークンの値も返します。CAS トークンの使用法は Memcached::cas() を参照ください。Read-through キャッシュコールバック は cache_cb パラメータで指定します。

パラメータ

key

取得したいアイテムのキー。

cache_cb

Read-through キャッシュコールバック、あるいは null。

get_flags

返される結果を制御するフラグ。Memcached::GET_EXTENDED を指定すると、CAS トークンも返すようになります。

戻り値

キャッシュに格納された値、あるいは false を返します。 get_flags に Memcached::GET_EXTENDED が設定されている場合は、キャッシュに格納された値と CAS トークンを含む配列を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_token パラメータが削除されました。 その代わりに新たに get_flags パラメータが追加され、ここに Memcached::GET_EXTENDED を指定すると、CAS トークンも含めて取得するようになります。

例

例1 Memcached::get() の例 #1

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('foo', 100);
var_dump($m->get('foo'));
?>

上の例の出力は以下となります。

int(100)

例2 Memcached::get() の例 #2

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

if (!($ip = $m->get('ip_block'))) {
if ($m->getResultCode() == Memcached::RES_NOTFOUND) {
$ip = array();
$m->set('ip_block', $ip);
} else {
/* エラーをログに記録します */
/* ... */
}
}
?>

参考

  • Memcached::getByKey() - 指定したサーバーからアイテムを取得する
  • Memcached::getMulti() - 複数のアイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する


すべてのサーバーのキーを取得する

  • ≪ Memcached::get
  • Memcached::getByKey ≫
  • PHP Manual
  • Memcached
  • すべてのサーバーのキーを取得する

Memcached::getAllKeys

(PECL memcached >= 2.0.0)

Memcached::getAllKeys — すべてのサーバーのキーを取得する

説明

public Memcached::getAllKeys(): array|false

Memcached::getAllKeys() は、 個々の memcache サーバーに問い合わせて、その時点で格納されているすべてのキーの配列を取得します。 これはアトミックな操作ではないので、ある時点でのすべてのキーのスナップショットを真の意味で取得したとは言えません。 また、memcache はすべてのキーを返すことを保証しないので、 すべてのキーを取得したものとみなすこともできません。

注意:

このメソッドはデバッグ目的に使うものです。 よって、大規模な運用環境で使うべきではありません。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合は全サーバーに格納されているキー、失敗した場合に false を返します。


指定したサーバーからアイテムを取得する

  • ≪ Memcached::getAllKeys
  • Memcached::getDelayed ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーからアイテムを取得する

Memcached::getByKey

(PECL memcached >= 0.1.0)

Memcached::getByKey — 指定したサーバーからアイテムを取得する

説明

public Memcached::getByKey(
string $server_key,
string $key,
?callable $cache_cb = null,
int $get_flags = 0
): mixed

Memcached::getByKey() は機能的に Memcached::get() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

取得したいアイテムのキー。

cache_cb

Read-through キャッシュコールバック、あるいは null。

get_flags

戻り値を制御するフラグ。 Memcached::GET_EXTENDED を渡すと、CASトークン を返します。

戻り値

キャッシュに格納された値、あるいは false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTFOUND を返します。

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_token パラメータは削除されました。 代替として get_flags が追加され、 これに Memcached::GET_EXTENDED を渡すと、 CAS トークンも取得するようになりました。

参考

  • Memcached::get() - アイテムを取得する
  • Memcached::getMulti() - 複数のアイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する


複数のアイテムを要求する

  • ≪ Memcached::getByKey
  • Memcached::getDelayedByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを要求する

Memcached::getDelayed

(PECL memcached >= 0.1.0)

Memcached::getDelayed — 複数のアイテムを要求する

説明

public Memcached::getDelayed(array $keys, bool $with_cas = false, ?callable $value_cb = null): bool

Memcached::getDelayed() は、keys 配列で指定した複数のキーのアイテムに対するリクエストを memcache に発行します。 このメソッドはサーバーからの応答を待たずにすぐに結果を返します。 アイテムを使用したくなったときには Memcached::fetch() あるいは Memcached::fetchAll() をコールします。 with_cas が true の場合は CAS トークンの値もリクエストします。

結果を明示的に取得するのではなく、result コールバック を value_cb パラメータで指定することもできます。

パラメータ

keys

要求するキーの配列。

with_cas

CAS トークンの値も要求するかどうか。

value_cb

result コールバック、あるいは null。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getDelayed() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));

$m->getDelayed(array('int', 'array'), true);
var_dump($m->fetchAll());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["key"]=>
    string(3) "int"
    ["value"]=>
    int(99)
    ["cas"]=>
    float(2363)
  }
  [1]=>
  array(3) {
    ["key"]=>
    string(5) "array"
    ["value"]=>
    array(2) {
      [0]=>
      int(11)
      [1]=>
      int(12)
    }
    ["cas"]=>
    float(2365)
  }
}

参考

  • Memcached::getDelayedByKey() - 指定したサーバーに複数のアイテムを要求する
  • Memcached::fetch() - 次の結果を取得する
  • Memcached::fetchAll() - 残りのすべての結果を取得する


指定したサーバーに複数のアイテムを要求する

  • ≪ Memcached::getDelayed
  • Memcached::getMulti ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーに複数のアイテムを要求する

Memcached::getDelayedByKey

(PECL memcached >= 0.1.0)

Memcached::getDelayedByKey — 指定したサーバーに複数のアイテムを要求する

説明

public Memcached::getDelayedByKey(
string $server_key,
array $keys,
bool $with_cas = false,
?callable $value_cb = null
): bool

Memcached::getDelayedByKey() は機能的に Memcached::getDelayed() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

keys

要求するキーの配列。

with_cas

CAS トークンの値も要求するかどうか。

value_cb

result コールバック、あるいは null。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::getDelayed() - 複数のアイテムを要求する
  • Memcached::fetch() - 次の結果を取得する
  • Memcached::fetchAll() - 残りのすべての結果を取得する


複数のアイテムを取得する

  • ≪ Memcached::getDelayedByKey
  • Memcached::getMultiByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを取得する

Memcached::getMulti

(PECL memcached >= 0.1.0)

Memcached::getMulti — 複数のアイテムを取得する

説明

public Memcached::getMulti(array $keys, int $get_flags = 0): array|false

Memcached::getMulti() は Memcached::get() と似ていますが、ひとつのキーのアイテムを取得するのではなく keys 配列で指定したキー群から複数のアイテムを取得します。

注意:

v3.0 より前のバージョンでは、二番目のパラメータ &cas_tokens が存在して、見つかったアイテムの CAS トークンが書き込まれるようになっていました。 この &cas_tokens パラメータは memcached 拡張モジュールの v3.0 で削除されました。 その代わりに追加されたのが Memcached::GET_EXTENDED フラグで、 これを get_flags に指定すれば CAS トークンを得られます。

get_flags パラメータを使用して、 Memcached::getMulti() 用の追加のオプションを設定します。 Memcached::GET_PRESERVE_ORDER は、要求したのと同じ順番でキーが返されることを保証します。 Memcached::GET_EXTENDED は、CAS トークンも含めて返すようにします。

パラメータ

keys

取得したいキーの配列。

get_flags

取得操作のオプション。

戻り値

見つかったアイテムの配列、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_tokens パラメータが削除されました。 Memcached::GET_EXTENDED が追加され、これをフラグとして渡すと CAS トークンも取得するようになりました。

例

例1 Memcached::getMulti() example for Memcached v3

<?php
// Valid for v3 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$items = array(
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
);
$m->setMulti($items);
$result = $m->getMulti(array('key1', 'key3', 'badkey'));
var_dump($result);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["key1"]=>
  string(6) "value1"
  ["key3"]=>
  string(6) "value3"
}

例2 Memcached::getMulti() example for Memcached v1 and v2

<?php
// Valid for v1 and v2 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$items = array(
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
);
$m->setMulti($items);
$result = $m->getMulti(array('key1', 'key3', 'badkey'), $cas);
var_dump($result, $cas);
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["key1"]=>
  string(6) "value1"
  ["key3"]=>
  string(6) "value3"
}
array(2) {
  ["key1"]=>
  float(2360)
  ["key3"]=>
  float(2362)
}

例3 Memcached v3 用の Memcached::GET_PRESERVE_ORDER の例

<?php
// Valid for v3 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$data = array(
'foo' => 'foo-data',
'bar' => 'bar-data',
'baz' => 'baz-data',
'lol' => 'lol-data',
'kek' => 'kek-data',
);

$m->setMulti($data, 3600);

$keys = array_keys($data);
$keys[] = 'zoo';
$got = $m->getMulti($keys, Memcached::GET_PRESERVE_ORDER);

foreach ($got as $k => $v) {
echo "$k $v\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

foo foo-data
bar bar-data
baz baz-data
lol lol-data
kek kek-data
zoo

例4 Memcached v1 および v2 用の Memcached::GET_PRESERVE_ORDER の例

<?php
// Valid for v1 and v2 of the extension

$m = new Memcached();
$m->addServer('localhost', 11211);

$data = array(
'foo' => 'foo-data',
'bar' => 'bar-data',
'baz' => 'baz-data',
'lol' => 'lol-data',
'kek' => 'kek-data',
);

$m->setMulti($data, 3600);

$null = null;
$keys = array_keys($data);
$keys[] = 'zoo';
$got = $m->getMulti($keys, $null, Memcached::GET_PRESERVE_ORDER);

foreach ($got as $k => $v) {
echo "$k $v\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

foo foo-data
bar bar-data
baz baz-data
lol lol-data
kek kek-data
zoo

参考

  • Memcached::getMultiByKey() - 指定したサーバーから複数のアイテムを取得する
  • Memcached::get() - アイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する


指定したサーバーから複数のアイテムを取得する

  • ≪ Memcached::getMulti
  • Memcached::getOption ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーから複数のアイテムを取得する

Memcached::getMultiByKey

(PECL memcached >= 0.1.0)

Memcached::getMultiByKey — 指定したサーバーから複数のアイテムを取得する

説明

public Memcached::getMultiByKey(string $server_key, array $keys, int $get_flags = 0): array|false

Memcached::getMultiByKey() は機能的に Memcached::getMulti() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

keys

取得したいキーの配列。

get_flags

取得操作のフラグ。

戻り値

見つかったアイテムの配列、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

変更履歴

バージョン | 説明
PECL memcached 3.0.0 | &cas_tokens パラメータは削除されました。 また、Memcached::GET_EXTENDED が追加され、 それがフラグとして渡された時にCASトークンを取得することを保証するようになりました。

参考

  • Memcached::getMulti() - 複数のアイテムを取得する
  • Memcached::get() - アイテムを取得する
  • Memcached::getDelayed() - 複数のアイテムを要求する


Memcached のオプションの値を取得する

  • ≪ Memcached::getMultiByKey
  • Memcached::getResultCode ≫
  • PHP Manual
  • Memcached
  • Memcached のオプションの値を取得する

Memcached::getOption

(PECL memcached >= 0.1.0)

Memcached::getOption — Memcached のオプションの値を取得する

説明

public Memcached::getOption(int $option): mixed

このメソッドは、Memcached のオプションの値を返します。 libmemcached で定義されているオプションに対応するものもあれば、 この拡張モジュールに固有のものもあります。詳細な情報は Memcached 定数 を参照ください。

パラメータ

option

Memcached::OPT_* 定数のいずれか。

戻り値

要求されたオプションの値、あるいはエラー時に false を返します。

例

例1 Memcached オプションの取得

<?php
$m = new Memcached();
var_dump($m->getOption(Memcached::OPT_COMPRESSION));
var_dump($m->getOption(Memcached::OPT_POLL_TIMEOUT));
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
int(1000)

参考

  • Memcached::getOption()
  • Memcached::setOption() - Memcached のオプションの値を設定する
  • Memcached 定数


直近の操作の結果コードを返す

  • ≪ Memcached::getOption
  • Memcached::getResultMessage ≫
  • PHP Manual
  • Memcached
  • 直近の操作の結果コードを返す

Memcached::getResultCode

(PECL memcached >= 0.1.0)

Memcached::getResultCode — 直近の操作の結果コードを返す

説明

public Memcached::getResultCode(): int

Memcached::getResultCode() は Memcached::RES_* 定数のいずれかを返します。 これは、直近に実行された Memcached メソッドの結果を表します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の Memcached 操作の結果コードを返します。

例

例1 Memcached::getResultCode() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->add('foo', 'bar');
if ($m->getResultCode() == Memcached::RES_NOTSTORED) {
/* ... */
}
?>


最後に実行した操作の結果を説明したメッセージを返す。

  • ≪ Memcached::getResultCode
  • Memcached::getServerByKey ≫
  • PHP Manual
  • Memcached
  • 最後に実行した操作の結果を説明したメッセージを返す。

Memcached::getResultMessage

(PECL memcached >= 1.0.0)

Memcached::getResultMessage — 最後に実行した操作の結果を説明したメッセージを返す。

説明

public Memcached::getResultMessage(): string

Memcached::getResultMessage()メソッドは、最後に実行した Memcached クラスのメソッドの結果コードの内容を説明した文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

最後に実行した Memcached クラスの操作結果を説明したメッセージ

例

例1 Memcached::getResultMessage()メソッドの例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->add('foo', 'bar'); // first time should succeed
$m->add('foo', 'bar');
echo $m->getResultMessage(),"\n";
?>

上の例の出力は以下となります。

NOT STORED


キーとサーバーを関連付ける

  • ≪ Memcached::getResultMessage
  • Memcached::getServerList ≫
  • PHP Manual
  • Memcached
  • キーとサーバーを関連付ける

Memcached::getServerByKey

(PECL memcached >= 0.1.0)

Memcached::getServerByKey — キーとサーバーを関連付ける

説明

public Memcached::getServerByKey(string $server_key): array|false

Memcached::getServerByKey() は、 Memcached::*ByKey() 系の操作で指定された server_key に対応するサーバーを返します。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

戻り値

成功した場合に配列を返します。この配列には host、 port そして weight の三つのキーが含まれます。 失敗した場合に false を返します 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::getServerByKey() の例

<?php
$m = new Memcached();
$m->addServers(array(
array('mem1.domain.com', 11211, 40),
array('mem2.domain.com', 11211, 40),
array('mem3.domain.com', 11211, 20),
));

$m->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);

var_dump($m->getServerByKey('user'));
var_dump($m->getServerByKey('log'));
var_dump($m->getServerByKey('ip'));
?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["host"]=>
  string(15) "mem3.domain.com"
  ["port"]=>
  int(11211)
  ["weight"]=>
  int(20)
}
array(3) {
  ["host"]=>
  string(15) "mem2.domain.com"
  ["port"]=>
  int(11211)
  ["weight"]=>
  int(40)
}
array(3) {
  ["host"]=>
  string(15) "mem2.domain.com"
  ["port"]=>
  int(11211)
  ["weight"]=>
  int(40)
}


プール内のサーバーの一覧を取得する

  • ≪ Memcached::getServerByKey
  • Memcached::getStats ≫
  • PHP Manual
  • Memcached
  • プール内のサーバーの一覧を取得する

Memcached::getServerList

(PECL memcached >= 0.1.0)

Memcached::getServerList — プール内のサーバーの一覧を取得する

説明

public Memcached::getServerList(): array

Memcached::getServerList() は、 サーバープール内のすべてのサーバーの一覧を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

サーバープール内のすべてのサーバーの一覧を返します。

例

例1 Memcached::getServerList() の例

<?php
$m = new Memcached();
$m->addServers(array(
array('mem1.domain.com', 11211, 20),
array('mem2.domain.com', 11311, 80),
));
var_dump($m->getServerList());
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  array(3) {
    ["host"]=>
    string(15) "mem1.domain.com"
    ["port"]=>
    int(11211)
    ["weight"]=>
    int(20)
  }
  [1]=>
  array(3) {
    ["host"]=>
    string(15) "mem2.domain.com"
    ["port"]=>
    int(11311)
    ["weight"]=>
    int(80)
  }
}


サーバープールの統計情報を取得する

  • ≪ Memcached::getServerList
  • Memcached::getVersion ≫
  • PHP Manual
  • Memcached
  • サーバープールの統計情報を取得する

Memcached::getStats

(PECL memcached >= 0.1.0)

Memcached::getStats — サーバープールの統計情報を取得する

説明

public Memcached::getStats(?string $type = null): array|false

Memcached::getStats() は、 すべての memcache サーバーの状態を含む配列を返します。 その詳細については、» memcache プロトコル の仕様を参照ください。

パラメータ

type

取得する統計情報のタイプ

戻り値

サーバーの統計情報の配列を返します。サーバーごとにひとつのエントリとなります。 失敗した場合に false を返します

例

例1 Memcached::getStats() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

print_r($m->getStats());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [localhost:11211] => Array
        (
            [pid] => 4933
            [uptime] => 786123
            [threads] => 1
            [time] => 1233868010
            [pointer_size] => 32
            [rusage_user_seconds] => 0
            [rusage_user_microseconds] => 140000
            [rusage_system_seconds] => 23
            [rusage_system_microseconds] => 210000
            [curr_items] => 145
            [total_items] => 2374
            [limit_maxbytes] => 67108864
            [curr_connections] => 2
            [total_connections] => 151
            [connection_structures] => 3
            [bytes] => 20345
            [cmd_get] => 213343
            [cmd_set] => 2381
            [get_hits] => 204223
            [get_misses] => 9120
            [evictions] => 0
            [bytes_read] => 9092476
            [bytes_written] => 15420512
            [version] => 1.2.6
        )

)


サーバープールのバージョン情報を取得する

  • ≪ Memcached::getStats
  • Memcached::increment ≫
  • PHP Manual
  • Memcached
  • サーバープールのバージョン情報を取得する

Memcached::getVersion

(PECL memcached >= 0.1.5)

Memcached::getVersion — サーバープールのバージョン情報を取得する

説明

public Memcached::getVersion(): array|false

Memcached::getVersion() は、全ての利用可能な memcached サーバーのバージョン情報を含んだ配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

memcached サーバーのバージョン情報の配列。サーバーひとつにつき配列の要素一つが割り当てられます。

例

例1 Memcached::getVersion() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

print_r($m->getVersion());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [localhost:11211] => 1.2.6
)


数値アイテムの値を増やす

  • ≪ Memcached::getVersion
  • Memcached::incrementByKey ≫
  • PHP Manual
  • Memcached
  • 数値アイテムの値を増やす

Memcached::increment

(PECL memcached >= 0.1.0)

Memcached::increment — 数値アイテムの値を増やす

説明

public Memcached::increment(
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false

Memcached::increment() は、数値アイテムの値を offset で指定しただけ増やします。 アイテムの値が数値でない場合はエラーとなります。 アイテムが存在しない場合、Memcached::increment() は値を initial_value に設定します。

パラメータ

key

増やしたいアイテムのキー。

offset

値を増やしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

戻り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

例

例1 Memcached::increment() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('counter', 0);
$m->increment('counter');
$n = $m->increment('counter', 10);
var_dump($n);

$m->set('counter', 'abc');
$n = $m->increment('counter');
// アイテムの値が数値でないので、これは失敗します
var_dump($n);
?>

上の例の出力は以下となります。

int(11)
bool(false)

参考

  • Memcached::decrement() - 数値アイテムの値を減らす
  • Memcached::decrementByKey() - 指定したサーバー上にある数値アイテムの値を減らす
  • Memcached::incrementByKey() - 指定したサーバー上にある数値アイテムの値を増やす


指定したサーバー上にある数値アイテムの値を増やす

  • ≪ Memcached::increment
  • Memcached::isPersistent ≫
  • PHP Manual
  • Memcached
  • 指定したサーバー上にある数値アイテムの値を増やす

Memcached::incrementByKey

(PECL memcached >= 2.0.0)

Memcached::incrementByKey — 指定したサーバー上にある数値アイテムの値を増やす

説明

public Memcached::incrementByKey(
string $server_key,
string $key,
int $offset = 1,
int $initial_value = 0,
int $expiry = 0
): int|false

Memcached::incrementByKey() は、数値アイテムの値を offset で指定しただけ増やします。 アイテムの値が数値でない場合はエラーとなります。 アイテムが存在しない場合、Memcached::incrementByKey() は値を initial_value に設定します。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

増やしたいアイテムのキー。

offset

値を増やしたい量。

initial_value

そのアイテムが存在しない場合に設定する値。

expiry

そのアイテムに設定する有効期限。

戻り値

成功した場合にアイテムの新しい値、失敗した場合に false を返します。

参考

  • Memcached::decrement() - 数値アイテムの値を減らす
  • Memcached::decrementByKey() - 指定したサーバー上にある数値アイテムの値を減らす
  • Memcached::increment() - 数値アイテムの値を増やす


memcache への接続で持続的接続を使っているかどうかを調べる

  • ≪ Memcached::incrementByKey
  • Memcached::isPristine ≫
  • PHP Manual
  • Memcached
  • memcache への接続で持続的接続を使っているかどうかを調べる

Memcached::isPersistent

(PECL memcached >= 2.0.0)

Memcached::isPersistent — memcache への接続で持続的接続を使っているかどうかを調べる

説明

public Memcached::isPersistent(): bool

Memcached::isPersistent() は、 memcache サーバーへの接続が持続的接続かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

Memcache インスタンスが持続的接続を使っている場合に true、それ以外の場合に false を返します。

参考

  • Memcached::isPristine() - 直近に作られたインスタンスかどうかを調べる


直近に作られたインスタンスかどうかを調べる

  • ≪ Memcached::isPersistent
  • Memcached::prepend ≫
  • PHP Manual
  • Memcached
  • 直近に作られたインスタンスかどうかを調べる

Memcached::isPristine

(PECL memcached >= 2.0.0)

Memcached::isPristine — 直近に作られたインスタンスかどうかを調べる

説明

public Memcached::isPristine(): bool

Memcached::isPristine() は、その Memcache インスタンスが直近に作られたものかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

直近に作られたインスタンスである場合に true、それ以外の場合に false を返します。

参考

  • Memcached::isPersistent() - memcache への接続で持続的接続を使っているかどうかを調べる


既存のアイテムの前にデータを付加する

  • ≪ Memcached::isPristine
  • Memcached::prependByKey ≫
  • PHP Manual
  • Memcached
  • 既存のアイテムの前にデータを付加する

Memcached::prepend

(PECL memcached >= 0.1.0)

Memcached::prepend — 既存のアイテムの前にデータを付加する

説明

public Memcached::prepend(string $key, string $value): ?bool

Memcached::prepend() は、指定した文字列 value を既存のアイテムの前に付加します。 value を文字列に強制変換する理由は、 異なる型を付加した場合の挙動が定義されていないからです。

注意:

Memcached::OPT_COMPRESSION が有効になっている場合は、 この操作は失敗して警告が発せられます。 すでに圧縮されている可能性のあるデータの先頭に圧縮したデータを付加することはできないからです。

パラメータ

key

データを先頭に付加したいアイテムのキー。

value

先頭に付加する文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。 圧縮が有効になっている場合は null を返します。

エラー / 例外

圧縮が有効になっている場合は null を返し、 E_WARNING が発生します。

例

例1 Memcached::prepend() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);
$m->setOption(Memcached::OPT_COMPRESSION, false);

$m->set('foo', 'abc');
$m->prepend('foo', 'def');
var_dump($m->get('foo'));
?>

上の例の出力は以下となります。

string(6) "defabc"

参考

  • Memcached::prependByKey() - 指定したサーバーで既存のアイテムの前にデータを付加する
  • Memcached::append() - データを既存のアイテムに追記する


指定したサーバーで既存のアイテムの前にデータを付加する

  • ≪ Memcached::prepend
  • Memcached::quit ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーで既存のアイテムの前にデータを付加する

Memcached::prependByKey

(PECL memcached >= 0.1.0)

Memcached::prependByKey — 指定したサーバーで既存のアイテムの前にデータを付加する

説明

public Memcached::prependByKey(string $server_key, string $key, string $value): ?bool

Memcached::prependByKey() は機能的に Memcached::prepend() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

データを先頭に付加したいアイテムのキー。

value

先頭に付加する文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。 圧縮が有効になっている場合は null を返します。

エラー / 例外

圧縮が有効になっている場合は null を返し、 E_WARNING が発生します。

参考

  • Memcached::prepend() - 既存のアイテムの前にデータを付加する
  • Memcached::append() - データを既存のアイテムに追記する


開いている接続を閉じる

  • ≪ Memcached::prependByKey
  • Memcached::replace ≫
  • PHP Manual
  • Memcached
  • 開いている接続を閉じる

Memcached::quit

(PECL memcached >= 2.0.0)

Memcached::quit — 開いている接続を閉じる

説明

public Memcached::quit(): bool

Memcached::quit() は、memcache サーバーとの接続をすべて閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


既存のキーのアイテムを入れ替える

  • ≪ Memcached::quit
  • Memcached::replaceByKey ≫
  • PHP Manual
  • Memcached
  • 既存のキーのアイテムを入れ替える

Memcached::replace

(PECL memcached >= 0.1.0)

Memcached::replace — 既存のキーのアイテムを入れ替える

説明

public Memcached::replace(string $key, mixed $value, int $expiration = 0): bool

Memcached::replace() は Memcached::set() と同等ですが、キー key がサーバー上にない場合は失敗します。

パラメータ

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::replaceByKey() - 指定したサーバーで既存のキーのアイテムを入れ替える
  • Memcached::set() - アイテムを格納する
  • Memcached::add() - アイテムを新しいキーで追加する


指定したサーバーで既存のキーのアイテムを入れ替える

  • ≪ Memcached::replace
  • Memcached::resetServerList ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーで既存のキーのアイテムを入れ替える

Memcached::replaceByKey

(PECL memcached >= 0.1.0)

Memcached::replaceByKey — 指定したサーバーで既存のキーのアイテムを入れ替える

説明

public Memcached::replaceByKey(
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool

Memcached::replaceByKey() は機能的に Memcached::replace() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 キーが存在しない場合、 Memcached::getResultCode() は Memcached::RES_NOTSTORED を返します。

参考

  • Memcached::replace() - 既存のキーのアイテムを入れ替える
  • Memcached::set() - アイテムを格納する
  • Memcached::add() - アイテムを新しいキーで追加する


サーバーリストからすべてのサーバーを消去する

  • ≪ Memcached::replaceByKey
  • Memcached::set ≫
  • PHP Manual
  • Memcached
  • サーバーリストからすべてのサーバーを消去する

Memcached::resetServerList

(PECL memcached >= 2.0.0)

Memcached::resetServerList — サーバーリストからすべてのサーバーを消去する

説明

public Memcached::resetServerList(): bool

Memcached::resetserverlist() は、 サーバーリストからすべての memcache サーバーを削除し、サーバーリストを空にします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • Memcached::addServer() - サーバーをサーバープールに追加する
  • Memcached::addServers() - 複数のサーバーをサーバープールに追加する


アイテムを格納する

  • ≪ Memcached::resetServerList
  • Memcached::setByKey ≫
  • PHP Manual
  • Memcached
  • アイテムを格納する

Memcached::set

(PECL memcached >= 0.1.0)

Memcached::set — アイテムを格納する

説明

public Memcached::set(string $key, mixed $value, int $expiration = 0): bool

Memcached::set() は、 指定したキー key で memcache サーバー上に value を格納します。 expiration パラメータで、 この値をいつ有効期限切れにするのかを制御することができます。

値に指定できるのは、リソース型以外の PHP の任意の型です。 リソース型はシリアライズすることができないため、使用することができません。 Memcached::OPT_COMPRESSION オプションをオンにすると、 シリアライズしたデータを格納する前に圧縮を行います。

パラメータ

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::set() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$m->set('int', 99);
$m->set('string', 'a simple string');
$m->set('array', array(11, 12));
/* expire 'object' key in 5 minutes */
$m->set('object', new stdClass, time() + 300);

var_dump($m->get('int'));
var_dump($m->get('string'));
var_dump($m->get('array'));
var_dump($m->get('object'));
?>

上の例の出力は、 たとえば以下のようになります。

int(99)
string(15) "a simple string"
array(2) {
  [0]=>
  int(11)
  [1]=>
  int(12)
}
object(stdClass)#1 (0) {
}

参考

  • Memcached::setByKey() - 指定したサーバーにアイテムを格納する
  • Memcached::add() - アイテムを新しいキーで追加する
  • Memcached::replace() - 既存のキーのアイテムを入れ替える


指定したサーバーにアイテムを格納する

  • ≪ Memcached::set
  • Memcached::setMulti ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーにアイテムを格納する

Memcached::setByKey

(PECL memcached >= 0.1.0)

Memcached::setByKey — 指定したサーバーにアイテムを格納する

説明

public Memcached::setByKey(
string $server_key,
string $key,
mixed $value,
int $expiration = 0
): bool

Memcached::setByKey() は機能的に Memcached::set() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

value

格納する値。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::setByKey() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

/* IP ブロック情報を特定のサーバー上に保持します */
$m->setByKey('api-cache', 'block-ip:169.254.253.252', 1);
$m->setByKey('api-cache', 'block-ip:169.127.127.202', 1);
?>

参考

  • Memcached::set() - アイテムを格納する


複数のアイテムを格納する

  • ≪ Memcached::setByKey
  • Memcached::setMultiByKey ≫
  • PHP Manual
  • Memcached
  • 複数のアイテムを格納する

Memcached::setMulti

(PECL memcached >= 0.1.0)

Memcached::setMulti — 複数のアイテムを格納する

説明

public Memcached::setMulti(array $items, int $expiration = 0): bool

Memcached::setMulti() は Memcached::set() と似ていますが、ひとつのキーのアイテムではなく items で設定した複数のアイテムに対して動作します。 有効期限 expiration は、すべてのアイテムに同時に適用されます。

パラメータ

items

サーバーに格納する キー/値 のペアの配列。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

例

例1 Memcached::setMulti() の例

<?php
$m = new Memcached();
$m->addServer('localhost', 11211);

$items = array(
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
);
$m->setMulti($items, time() + 300);
?>

参考

  • Memcached::setMultiByKey() - 指定したサーバーで複数のアイテムを格納する
  • Memcached::set() - アイテムを格納する


指定したサーバーで複数のアイテムを格納する

  • ≪ Memcached::setMulti
  • Memcached::setOption ≫
  • PHP Manual
  • Memcached
  • 指定したサーバーで複数のアイテムを格納する

Memcached::setMultiByKey

(PECL memcached >= 0.1.0)

Memcached::setMultiByKey — 指定したサーバーで複数のアイテムを格納する

説明

public Memcached::setMultiByKey(string $server_key, array $items, int $expiration = 0): bool

Memcached::setMultiByKey() は機能的に Memcached::setMulti() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。 これは、関連するキーを特定のサーバーに置き続けたいときなどに便利です。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

items

サーバーに格納する キー/値 のペアの配列。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::setMulti() - 複数のアイテムを格納する
  • Memcached::set() - アイテムを格納する


Memcached のオプションの値を設定する

  • ≪ Memcached::setMultiByKey
  • Memcached::setOptions ≫
  • PHP Manual
  • Memcached
  • Memcached のオプションの値を設定する

Memcached::setOption

(PECL memcached >= 0.1.0)

Memcached::setOption — Memcached のオプションの値を設定する

説明

public Memcached::setOption(int $option, mixed $value): bool

このメソッドは、Memcached のオプションの値を設定します。 libmemcached で定義されているオプションに対応するものもあれば、 この拡張モジュールに固有のものもあります。

パラメータ

option

定数 Memcached::OPT_* のうちのひとつ。 詳細は Memcached 定数 を参照ください。

value

設定する値

注意:

以下のオプションの値は、定数で指定する必要があります。

  • Memcached::OPT_HASH には Memcached::HASH_* の値を指定しなければなりません。
  • Memcached::OPT_DISTRIBUTION には Memcached::DISTRIBUTION_* の値を指定しなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached オプションの設定

<?php
$m = new Memcached();
var_dump($m->getOption(Memcached::OPT_HASH) == Memcached::HASH_DEFAULT);
$m->setOption(Memcached::OPT_HASH, Memcached::HASH_MURMUR);
$m->setOption(Memcached::OPT_PREFIX_KEY, "widgets");
echo "Prefix key is now: ", $m->getOption(Memcached::OPT_PREFIX_KEY), "\n";
?>

上の例の出力は以下となります。

bool(true)
Prefix key is now: widgets

参考

  • Memcached::getOption() - Memcached のオプションの値を取得する
  • Memcached::setOptions() - Memcached のオプションの値を設定する
  • Memcached 定数


Memcached のオプションの値を設定する

  • ≪ Memcached::setOption
  • Memcached::setSaslAuthData ≫
  • PHP Manual
  • Memcached
  • Memcached のオプションの値を設定する

Memcached::setOptions

(PECL memcached >= 2.0.0)

Memcached::setOptions — Memcached のオプションの値を設定する

説明

public Memcached::setOptions(array $options): bool

Memcached::setOptions() は Memcached::setOption() と似ていますが、設定するオプションの配列を受け取ります。

パラメータ

options

オプションの連想配列。設定するオプションを連想配列のキーに、 そしてそのオプションの新しい値を連想配列の値に設定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 Memcached オプションの設定

<?php
$m = new Memcached();
var_dump($m->getOption(Memcached::OPT_HASH) == Memcached::HASH_DEFAULT);

$m->setOptions(array(Memcached::OPT_HASH => Memcached::HASH_MURMUR, Memcached::OPT_PREFIX_KEY => "widgets"));

var_dump($m->getOption(Memcached::OPT_HASH) == Memcached::HASH_DEFAULT);
echo "Prefix key is now: ", $m->getOption(Memcached::OPT_PREFIX_KEY), "\n";
?>

上の例の出力は以下となります。

bool(true)
bool(false)
Prefix key is now: widgets

参考

  • Memcached::getOption() - Memcached のオプションの値を取得する
  • Memcached::setOption() - Memcached のオプションの値を設定する
  • Memcached 定数


認証用の資格情報を設定する

  • ≪ Memcached::setOptions
  • Memcached::touch ≫
  • PHP Manual
  • Memcached
  • 認証用の資格情報を設定する

Memcached::setSaslAuthData

(PECL memcached >= 2.0.0)

Memcached::setSaslAuthData — 認証用の資格情報を設定する

説明

public Memcached::setSaslAuthData(string $username, string $password): bool

Memcached::setSaslAuthData() は、ユーザー名とパスワードを設定します。 これらを、memcache サーバーでの SASL 認証に使います。

このメソッドを使えるのは、memcached 拡張モジュールを SASL サポートつきでビルドしたときだけです。 その方法については Memcached のインストール/設定 を参照ください。

パラメータ

username

認証で使うユーザー名。

password

認証で使うパスワード。

戻り値

成功した場合に true を、失敗した場合に false を返します。


アイテムに新しい有効期限を設定する

  • ≪ Memcached::setSaslAuthData
  • Memcached::touchByKey ≫
  • PHP Manual
  • Memcached
  • アイテムに新しい有効期限を設定する

Memcached::touch

(PECL memcached >= 2.0.0)

Memcached::touch — アイテムに新しい有効期限を設定する

説明

public Memcached::touch(string $key, int $expiration = 0): bool

Memcached::touch() は、指定したキーに新しい有効期限を設定します。

パラメータ

key

値の格納先のキー。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::touchByKey() - 指定したサーバー上のアイテムに新しい有効期限を設定する


指定したサーバー上のアイテムに新しい有効期限を設定する

  • ≪ Memcached::touch
  • MemcachedException ≫
  • PHP Manual
  • Memcached
  • 指定したサーバー上のアイテムに新しい有効期限を設定する

Memcached::touchByKey

(PECL memcached >= 2.0.0)

Memcached::touchByKey — 指定したサーバー上のアイテムに新しい有効期限を設定する

説明

public Memcached::touchByKey(string $server_key, string $key, int $expiration = 0): bool

Memcached::touchByKey() は機能的に Memcached::touch() と同等です。しかし、自由形式の server_key を使用して、 key を特定のサーバーに関連付けることができます。

パラメータ

server_key

値を格納したりデータを取得したりするサーバーを表すキー。 アイテムの実際のキーをハッシュするかわりにサーバーのキーをハッシュして、どの memcached サーバーとやりとりするのか選びます。 これで、関連するアイテムを一つのサーバーにまとめられるようになり、マルチ操作の効率が上がります。

key

値の格納先のキー。

expiration

期限切れとなるまでの時間。デフォルトは 0。詳細な情報は有効期限 を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。 必要に応じて Memcached::getResultCode() を使用しましょう。

参考

  • Memcached::touch() - アイテムに新しい有効期限を設定する


MemcachedException クラス

(PECL memcached >= 0.1.0)

はじめに

クラス概要

class MemcachedException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


mqseries

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • mqseries 関数
    • mqseries_back — MQSeries MQBACK
    • mqseries_begin — MQseries MQBEGIN
    • mqseries_close — MQSeries MQCLOSE
    • mqseries_cmit — MQSeries MQCMIT
    • mqseries_conn — MQSeries MQCONN
    • mqseries_connx — MQSeries MQCONNX
    • mqseries_disc — MQSeries MQDISC
    • mqseries_get — MQSeries MQGET
    • mqseries_inq — MQSeries MQINQ
    • mqseries_open — MQSeries MQOPEN
    • mqseries_put — MQSeries MQPUT
    • mqseries_put1 — MQSeries MQPUT1
    • mqseries_set — MQSeries MQSET
    • mqseries_strerror — 結果コード (MQRC) に対応するエラーメッセージを返す


はじめに

この拡張モジュールは、IBM WebSphere MQ Series のキューマネージャとの通信用のインターフェイスを提供します。

このインターフェイスは、WebSphere MQ Series の C 言語用 API のクライアントインターフェイスとできるだけ同じになるように作られています。 命名規約なども C の API と可能な限り一致させています。 この拡張モジュールを使いこなすには、 C の API についてある程度の知識が必要となるでしょう。

MQ-options、MQ-structures、MQ-results などについては、 WebSphere MQ Application Programming Guide および WebSphere MQ Application Programming Reference を参照ください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • mqseries
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

IBM WebSphere MQ をインストールする必要があります。 また、拡張モジュールをビルドするには IBM WebSphere MQ の SDK も必要です。

注意: IBM WebSphere MQ Client で実行した場合は、 いくつか使用できないメソッドがあることに注意しましょう。 これは、この拡張モジュールの問題ではなく、単に WebSphere MQ Client Interface の動作上の問題です。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/mqseries.

注意: この拡張モジュールの正式名称は mqseries です。

キューマネージャへの接続方法は、次の二通りです。 これは、拡張モジュールのコンパイル/リンクの方法によって決まります。

  • デフォルトで用いられるのは mqic ライブラリです。この IBM WebSphere MQSeries ライブラリをターゲットとしてコンパイル/リンクすると、 キューマネージャに対してクライアントインターフェイスで接続できるようになります。 リモート接続も、この方式で行えます。

  • もうひとつの方法は、mqm ライブラリをターゲットとしてコンパイル/リンクするものです。 このライブラリを使用すると、キューマネージャのトランザクション管理ができるようになります。

現時点では、使用するライブラリを選択するには直接 config.m4 ファイルを編集します。


  • ≪ インストール手順
  • リソース型 ≫
  • PHP Manual
  • インストール/設定
  • 実行時設定

実行時設定

php.ini の設定により動作が変化します。

設定パラメータは特にありません。


リソース型

この拡張モジュールでは、接続リソースおよびオブジェクトハンドルリソースを定義しています。

mqseries_conn() と mqseries_connx() が接続ハンドルを定義します。

mqseries_open() がオブジェクトハンドルを定義します。


定義済み定数

WebSphere MQ の各定数に対して、mqseries でも対応する定数を用意しています。

定数の定義や使用法については、WebSphere MQ Application Programming Guide および WebSphere MQ Application Programming Reference red books を参照ください。

mqseries での定数名は、WebSphere MQ の定数名に MQSERIES_ をつけたものとなります。 たとえば、完了コードの場合は次のようになります。

mqseries の定数
PHP の定数 | MQ の定数
MQSERIES_MQCC_OK | MQCC_OK
MQSERIES_MQCC_WARNING | MQCC_WARNING
MQSERIES_MQCC_FAILED | MQCC_FAILED
MQSERIES_MQCC_UNKNOWN | MQCC_UNKNOWN


mqseries 関数

目次

  • mqseries_back — MQSeries MQBACK
  • mqseries_begin — MQseries MQBEGIN
  • mqseries_close — MQSeries MQCLOSE
  • mqseries_cmit — MQSeries MQCMIT
  • mqseries_conn — MQSeries MQCONN
  • mqseries_connx — MQSeries MQCONNX
  • mqseries_disc — MQSeries MQDISC
  • mqseries_get — MQSeries MQGET
  • mqseries_inq — MQSeries MQINQ
  • mqseries_open — MQSeries MQOPEN
  • mqseries_put — MQSeries MQPUT
  • mqseries_put1 — MQSeries MQPUT1
  • mqseries_set — MQSeries MQSET
  • mqseries_strerror — 結果コード (MQRC) に対応するエラーメッセージを返す


MQSeries MQBACK

  • ≪ mqseries 関数
  • mqseries_begin ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQBACK

mqseries_back

(PECL mqseries >= 0.10.0)

mqseries_back — MQSeries MQBACK

説明

mqseries_back(resource $hconn, resource &$compCode, resource &$reason): void

mqseries_back() (MQBACK) は、キューマネージャに対して、 直近の同期ポイント以降に get あるいは put されたすべてのメッセージを戻すことを指示します。 作業ユニットの一部として put されたメッセージは削除されます。 作業ユニットの一部として取得したメッセージはキューに戻されます。

mqseries_back() は、 mqseries_begin() と組み合わせた場合にのみ動作します。 また、mqclient インターフェイスを介さずに 直接キューマネージャに接続した場合にのみ動作します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_back() の例

<?php
mqseries_back($conn, $comp_code, $reason);

if ($comp_code !== MQSERIES_MQCC_OK) {
printf("CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
}
?>

注意

注意:

mqseries_back() は、MQSeries Client を使用して Queueu Manager に接続した場合には動作しません。

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_begin() - MQseries MQBEGIN


MQseries MQBEGIN

  • ≪ mqseries_back
  • mqseries_close ≫
  • PHP Manual
  • mqseries 関数
  • MQseries MQBEGIN

mqseries_begin

(PECL mqseries >= 0.10.0)

mqseries_begin — MQseries MQBEGIN

説明

mqseries_begin(
resource $hconn,
array $beginOptions,
resource &$compCode,
resource &$reason
): void

mqseries_begin() (MQBEGIN) をコールすると、作業ユニットを開始します。 これはキューマネージャが扱うものですが、外部のリソースマネージャを使用することもあります。

mqseries_begin() は作業ユニットを開始します。作業ユニットを終了させるには mqseries_back() あるいは mqseries_cmit() を使用します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_begin() の例

<?php
$mqbo = array();
mqseries_begin( $conn,
$mqbo,
$comp_code,
$reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
/* コード 2121 は警告を表します。詳細は MQSeries のリファレンスマニュアルを参照ください */
if ($reason !== 2121) {
printf("CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
}
}
?>

注意

注意:

mqseries_begin() は、MQSeries Client を使用して Queueu Manager に接続した場合には動作しません。

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_back() - MQSeries MQBACK
  • mqseries_cmit() - MQSeries MQCMIT


MQSeries MQCLOSE

  • ≪ mqseries_begin
  • mqseries_cmit ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCLOSE

mqseries_close

(PECL mqseries >= 0.10.0)

mqseries_close — MQSeries MQCLOSE

説明

mqseries_close(
resource $hconn,
resource $hobj,
int $options,
resource &$compCode,
resource &$reason
): void

mqseries_close() (MQCLOSE) をコールするとオブジェクトへのアクセスを破棄します。これは mqseries_open() (MQOPEN) コールの逆の意味です。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

options

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_close() の例

<?php
mqseries_close($conn, $obj, MQSERIES_MQCO_NONE, $comp_code, $reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("close CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
}
?>

参考

  • mqseries_open() - MQSeries MQOPEN
  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX


MQSeries MQCMIT

  • ≪ mqseries_close
  • mqseries_conn ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCMIT

mqseries_cmit

(PECL mqseries >= 0.10.0)

mqseries_cmit — MQSeries MQCMIT

説明

mqseries_cmit(resource $hconn, resource &$compCode, resource &$reason): void

mqseries_cmit() (MQCMIT) は、キューマネージャに対して、 アプリケーションが同期ポイントに達したことと 直近の同期ポイント以降に get あるいは put されたすべてのメッセージを確定させることを指示します。 作業ユニットの一部として put されたメッセージは他のアプリケーションでも使用できるようになります。 作業ユニットの一部として取得したメッセージは削除されます。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_cmit() の例

<?php
mqseries_cmit($conn, $comp_code, $reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("cmit CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
}
?>

注意

注意:

mqseries_back() は、MQSeries Client を使用して Queueu Manager に接続した場合には動作しません。

参考

  • mqseries_begin() - MQseries MQBEGIN
  • mqseries_back() - MQSeries MQBACK
  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX


MQSeries MQCONN

  • ≪ mqseries_cmit
  • mqseries_connx ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCONN

mqseries_conn

(PECL mqseries >= 0.10.0)

mqseries_conn — MQSeries MQCONN

説明

mqseries_conn(
string $qManagerName,
resource &$hconn,
resource &$compCode,
resource &$reason
): void

The mqseries_conn() (MQCONN) をコールすると、アプリケーションプログラムをキューマネージャに接続します。 これによって取得した接続ハンドルを、 アプリケーション側でそれ以降のメッセージキューコールの際に使用します。

パラメータ

qManagerName

キューマネージャ名。

アプリケーションが接続したいキューマネージャの名前。

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_conn() の例

<?php
mqseries_conn('WMQ1', $conn, $comp_code, $reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("conn CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
exit;
}
?>

参考

  • mqseries_disc() - MQSeries MQDISC


MQSeries MQCONNX

  • ≪ mqseries_conn
  • mqseries_disc ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQCONNX

mqseries_connx

(PECL mqseries >= 0.10.0)

mqseries_connx — MQSeries MQCONNX

説明

mqseries_connx(
string $qManagerName,
array &$connOptions,
resource &$hconn,
resource &$compCode,
resource &$reason
): void

The mqseries_connx() (MQCONNX) call connects an application program to a queue manager. It provides a queue manager connection handle, which is used by the application on subsequent MQ calls.

The mqseries_connx() call is like the mqseries_conn() (MQCONN) call, except that MQCONNX allows options to be specified to control the way that the call works.

パラメータ

qManagerName

Name of queue manager.

Name of the queue manager the application wishes to connect.

connOps

Options that control the action of function

See also the MQCNO structure.

hConn

Connection handle.

This handle represents the connection to the queue manager.

compCode

Completion code.

reason

Reason code qualifying the compCode.

戻り値

値を返しません。

例

例1 mqseries_connx() example

<?php
$mqcno = array(
'Version' => MQSERIES_MQCNO_VERSION_2,
'Options' => MQSERIES_MQCNO_STANDARD_BINDING,
'MQCD' => array('ChannelName' => 'MQNX9420.CLIENT',
'ConnectionName' => 'localhost',
'TransportType' => MQSERIES_MQXPT_TCP)
);

mqseries_connx('MQNX9420', $mqcno, $conn, $comp_code,$reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("Connx CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
exit;
}

?>

例2 mqseries_connx() example using SSL connection & OCSP Responder URL

<?php
$mqcno = array(
'Version' => 4, //MQCNO_VERSION_4
'Options' => MQSERIES_MQCNO_STANDARD_BINDING,
'MQCD' => array(
'Version' => 7, //MQCD_VERSION_7
'ConnectionName' => 'localhost',
'TransportType' => MQSERIES_MQXPT_TCP,
'ChannelName' => 'CONNECTIONCHANNEL',
'SSLCipherSpec' => 'NULL_SHA'
),
'MQSCO' => array(
'KeyRepository' => '/var/mqm/qmgrs/QUEUEMGR/ssl/key', //Local path where the SSL key repository can be found
'MQAIR' => array(
'Version' => 2, //MQAIR_VERSION_2
'AuthInfoType' => 2, //MQAIT_OCSP
'OCSPResponderURL' => 'http://dummy.OCSP.responder'
)
)
);

mqseries_connx('QUEUEMGR', $mqcno, $conn, $comp_code,$reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("Connx CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
exit;
}

?>

参考

  • mqseries_disc() - MQSeries MQDISC


MQSeries MQDISC

  • ≪ mqseries_connx
  • mqseries_get ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQDISC

mqseries_disc

(PECL mqseries >= 0.10.0)

mqseries_disc — MQSeries MQDISC

説明

mqseries_disc(resource $hconn, resource &$compCode, resource &$reason): void

mqseries_disc() (MQDISC) をコールすると、キューマネージャとアプリケーションプログラムとの間の接続を切断します。 mqseries_conn() (MQCONN) や mqseries_connx() (MQCONNX) の逆の意味です。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_disc() の例

<?php
mqseries_disc($conn, $comp_code, $reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("disc CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
}
?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX


MQSeries MQGET

  • ≪ mqseries_disc
  • mqseries_inq ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQGET

mqseries_get

(PECL mqseries >= 0.10.0)

mqseries_get — MQSeries MQGET

説明

mqseries_get(
resource $hConn,
resource $hObj,
array &$md,
array &$gmo,
int &$bufferLength,
string &$msg,
int &$data_length,
resource &$compCode,
resource &$reason
): void

The mqseries_get() (MQGET) call retrieves a message from a local queue that has been opened using the mqseries_open() (MQOPEN) call

パラメータ

hConn

Connection handle.

This handle represents the connection to the queue manager.

hObj

Object handle.

This handle represents the object to be used.

md

Message descriptor (MQMD).

gmo

Get message options (MQGMO).

bufferLength

Expected length of the result buffer

msg

Buffer holding the message that was retrieved from the object.

data_length

Actual buffer length

compCode

Completion code.

reason

Reason code qualifying the compCode.

戻り値

値を返しません。

例

例1 mqseries_get() example

<?php
// open connection to the queue manager
mqseries_conn('WMQ1', $conn, $comp_code, $reason);
// $conn now hold the reference to the connection to the queue manager.

// open the connection to the testq queue
mqseries_open(
$conn,
array('ObjectName' => 'TESTQ'),
MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING | MQSERIES_MQOO_OUTPUT,
$obj,
$comp_code,
$reason);
// $obj now holds the reference to the object (TESTQ)

// setup empty message descriptor.
$mdg = array();
// setup get message options
$gmo = array('Options' => MQSERIES_MQGMO_FAIL_IF_QUIESCING | MQSERIES_MQGMO_WAIT, 'WaitInterval' => 3000);

// get the message from the queue
mqseries_get($conn, $obj, $mdg, $gmo, 255, $msg, $data_length, $comp_code, $reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("GET CompCode:%d Reason:%d Text:%s<br>", $comp_code, $reason, mqseries_strerror($reason));
}

// close the object reference $obj
mqseries_close($conn, $obj, MQSERIES_MQCO_NONE, $comp_code, $reason);

// disconnect from the queue manager.
mqseries_disc($conn, $comp_code, $reason);

?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN
  • mqseries_put() - MQSeries MQPUT


MQSeries MQINQ

  • ≪ mqseries_get
  • mqseries_open ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQINQ

mqseries_inq

(PECL mqseries >= 0.10.0)

mqseries_inq — MQSeries MQINQ

説明

mqseries_inq(
resource $hconn,
resource $hobj,
int $selectorCount,
array $selectors,
int $intAttrCount,
resource &$intAttr,
int $charAttrLength,
resource &$charAttr,
resource &$compCode,
resource &$reason
): void

mqseries_inq() (MQINQ) は、整数の配列と文字列を返します。 これはオブジェクトの属性を表します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

selectorCount

セレクタの数。

selectors

属性セレクタの配列。

intAttrLength

整数属性の数。

intAttr

整数属性の配列。

charAttrLength

文字属性バッファの長さ。

charAttr

文字属性。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_inq() の例

<?php
$int_attr = array();
$char_attr = "";

mqseries_inq($conn, $obj, 1, array(MQSERIES_MQCA_Q_MGR_NAME), 0, $int_attr, 48, $char_attr, $comp_code, $reason);

if ($comp_code !== MQSERIES_MQCC_OK) {
printf("INQ CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
} else {
echo "INQ QManager name result ".$char_attr."<br>\n";
}
?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN


MQSeries MQOPEN

  • ≪ mqseries_inq
  • mqseries_put ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQOPEN

mqseries_open

(PECL mqseries >= 0.10.0)

mqseries_open — MQSeries MQOPEN

説明

mqseries_open(
resource $hconn,
array &$objDesc,
int $option,
resource &$hobj,
resource &$compCode,
resource &$reason
): void

mqseries_open() (MQOPEN) は、オブジェクトへのアクセスを確立します。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

objDesc

オブジェクト記述子 (MQOD)。

options

関数の動作を制御するオプション。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_open() の例

<?php
$mqods = array('ObjectName' => 'TESTQ');
mqseries_open(
$conn,
$mqods,
MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING | MQSERIES_MQOO_OUTPUT,
$obj,
$comp_code,
$reason);
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("open CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
exit;
}
?>

参考

  • mqseries_close() - MQSeries MQCLOSE


MQSeries MQPUT

  • ≪ mqseries_open
  • mqseries_put1 ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQPUT

mqseries_put

(PECL mqseries >= 0.10.0)

mqseries_put — MQSeries MQPUT

説明

mqseries_put(
resource $hConn,
resource $hObj,
array &$md,
array &$pmo,
string $message,
resource &$compCode,
resource &$reason
): void

The mqseries_put() (MQPUT) は、メッセージをキューあるいは配送リストにおきます。 キューあるいは配送リストを事前にオープンしておく必要があります。

パラメータ

hConn

接続ハンドル。

このハンドルは、キューマネージャへの接続を表します。

hObj

オブジェクトハンドル。

このハンドルは、使用するオブジェクトを表します。

md

メッセージ記述子 (MQMD)。

pmo

Put メッセージのオプション (MQPMO)。

message

実際にキューに置くメッセージ。

compCode

完了コード。

reason

compCode の原因を表すコード。

戻り値

値を返しません。

例

例1 mqseries_put() の例

<?php
// キューマネージャへの接続をオープンします
mqseries_conn('WMQ1', $conn, $comp_code, $reason);
// これで、$conn がキューマネージャへの接続を指すようになります

// testq キューへの接続をオープンします
mqseries_open(
$conn,
array('ObjectName' => 'TESTQ'),
MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING | MQSERIES_MQOO_OUTPUT,
$obj,
$comp_code,
$reason);
// これで、$obj はオブジェクト (TESTQ) を指すようになります

// メッセージ記述子の配列を設定します。MQSeries のリファレンスマニュアルを参照ください
$md = array(
'Version' => MQSERIES_MQMD_VERSION_1,
'Expiry' => MQSERIES_MQEI_UNLIMITED,
'Report' => MQSERIES_MQRO_NONE,
'MsgType' => MQSERIES_MQMT_DATAGRAM,
'Format' => MQSERIES_MQFMT_STRING,
'Priority' => 1,
'Persistence' => MQSERIES_MQPER_PERSISTENT);

// Put メッセージのオプションを設定します
$pmo = array('Options' => MQSERIES_MQPMO_NEW_MSG_ID|MQSERIES_MQPMO_SYNCPOINT);

// 'Ping' というメッセージをキューに置きます
mqseries_put($conn, $obj, $md, $pmo, 'Ping', $comp_code, $reason);

if ($comp_code !== MQSERIES_MQCC_OK) {
printf("put CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
}

// オブジェクトへの参照 $obj を閉じます
mqseries_close($conn, $obj, MQSERIES_MQCO_NONE, $comp_code, $reason);

// キューマネージャとの接続を切断します
mqseries_disc($conn, $comp_code, $reason);

?>

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN
  • mqseries_get() - MQSeries MQGET


MQSeries MQPUT1

  • ≪ mqseries_put
  • mqseries_set ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQPUT1

mqseries_put1

(PECL mqseries >= 0.10.0)

mqseries_put1 — MQSeries MQPUT1

説明

mqseries_put1(
resource $hconn,
resource &$objDesc,
resource &$msgDesc,
resource &$pmo,
string $buffer,
resource &$compCode,
resource &$reason
): void

The mqseries_put1() (MQPUT1) call puts one message on a queue. The queue need not be open.

You can use both the mqseries_put() and mqseries_put1() calls to put messages on a queue; which call to use depends on the circumstances. Use the mqseries_put() (MQPUT) call to place multiple messages on the same queue. Use the mqseries_put1() (MQPUT1) call to put only one message on a queue. This call encapsulates the MQOPEN, MQPUT, and MQCLOSE calls into a single call, minimizing the number of calls that must be issued.

パラメータ

hConn

Connection handle.

This handle represents the connection to the queue manager.

objDesc

Object descriptor. (MQOD)

This is a structure which identifies the queue to which the message is added.

msgDesc

Message descriptor (MQMD).

pmo

Put message options (MQPMO).

compCode

Completion code.

reason

Reason code qualifying the compCode.

戻り値

値を返しません。

参考

  • mqseries_conn() - MQSeries MQCONN
  • mqseries_connx() - MQSeries MQCONNX
  • mqseries_open() - MQSeries MQOPEN
  • mqseries_get() - MQSeries MQGET


MQSeries MQSET

  • ≪ mqseries_put1
  • mqseries_strerror ≫
  • PHP Manual
  • mqseries 関数
  • MQSeries MQSET

mqseries_set

(PECL mqseries >= 0.10.0)

mqseries_set — MQSeries MQSET

説明

mqseries_set(
resource $hConn,
resource $hObj,
int $selectorCount,
array $selectors,
int $intAttrCount,
array $intAttrs,
int $charAttrLength,
array $charAttrs,
resource &$compCode,
resource &$reason
): void

The mqseries_set() (MQSET) call is used to change the attributes of an object represented by a handle. The object must be a queue.

パラメータ

hConn

Connection handle.

This handle represents the connection to the queue manager.

hObj

Object handle.

This handle represents the object to be used.

selectorCount

Count of selectors.

selectors

Array of attribute selectors.

intAttrCount

Count of integer attributes.

intAttrs

Array of integer attributes.

charAttrLength

Length of character attributes buffer.

charAttrs

Character attributes.

compCode

Completion code.

reason

Reason code qualifying the compCode.

戻り値

値を返しません。

参考

  • mqseries_inq() - MQSeries MQINQ


結果コード (MQRC) に対応するエラーメッセージを返す

  • ≪ mqseries_set
  • ネットワーク ≫
  • PHP Manual
  • mqseries 関数
  • 結果コード (MQRC) に対応するエラーメッセージを返す

mqseries_strerror

(PECL mqseries >= 0.10.0)

mqseries_strerror — 結果コード (MQRC) に対応するエラーメッセージを返す

説明

mqseries_strerror(int $reason): string

mqseries_strerror() は、結果コードに対応するメッセージを返します。

パラメータ

reason

compCode の原因を表すコード。

戻り値

原因コードのメッセージを文字列で返します。

例

例1 mqseries_strerror() の例

<?php
if ($comp_code !== MQSERIES_MQCC_OK) {
printf("open CompCode:%d Reason:%d Text:%s<br>\n", $comp_code, $reason, mqseries_strerror($reason));
exit;
}
?>

上の例の出力は以下となります。

Connx CompCode:2 Reason:2059 Text:Queue manager not available for connection.


ネットワーク

  • はじめに
  • インストール/設定
    • 要件
    • リソース型
  • 定義済み定数
  • ネットワーク 関数
    • checkdnsrr — 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
    • closelog — システムログへの接続を閉じる
    • dns_check_record — checkdnsrr のエイリアス
    • dns_get_mx — getmxrr のエイリアス
    • dns_get_record — ホスト名に関連する DNS リソースレコードを取得する
    • fsockopen — インターネット接続もしくは Unix ドメインソケット接続をオープンする
    • gethostbyaddr — 指定した IP アドレスに対応するインターネットホスト名を取得する
    • gethostbyname — インターネットホスト名に対応するIPv4アドレスを取得する
    • gethostbynamel — 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
    • gethostname — ホスト名を取得する
    • getmxrr — 指定したインターネットホスト名に対応する MX レコードを取得する
    • getprotobyname — プロトコル名のプロトコル番号を得る
    • getprotobynumber — プロトコル番号が指すプロトコル名を取得する
    • getservbyname — インターネットサービスおよびプロトコルが関連するポート番号を取得する
    • getservbyport — ポートおよびプロトコルに対応するインターネットサービスを得る
    • header — 生の HTTP ヘッダを送信する
    • header_register_callback — ヘッダ用の関数を登録する
    • header_remove — 以前に設定したHTTPヘッダを削除する
    • headers_list — 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
    • headers_sent — ヘッダが既に送信されているかどうかを調べる
    • http_response_code — HTTP レスポンスコードを取得または設定
    • inet_ntop — パックされたインターネットアドレスを、人間が読める形式に変換する
    • inet_pton — 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
    • ip2long — ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
    • long2ip — 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
    • net_get_interfaces — ネットワークインターフェイスを取得する
    • openlog — システムのロガーへの接続をオープンする
    • pfsockopen — 持続的な Internet または Unix ドメインソケット接続をオープンする
    • setcookie — クッキーを送信する
    • setrawcookie — 値を URL エンコードせずにクッキーを送信する
    • socket_get_status — stream_get_meta_data のエイリアス
    • socket_set_blocking — stream_set_blocking のエイリアス
    • socket_set_timeout — stream_set_timeout のエイリアス
    • syslog — システムログのメッセージを生成する


  • ≪ ネットワーク
  • インストール/設定 ≫
  • PHP Manual
  • ネットワーク
  • はじめに

はじめに

さまざまなネットワーク関数を提供します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • ネットワーク
  • インストール/設定

インストール/設定

目次

  • 要件
  • リソース型


要件

checkdnsrr()、getmxrr() および dns_get_record() には Linux の Bind が必要です。


リソース型

この拡張モジュールでは、ファイルポインタリソースを定義しています。これは fsockopen() および pfsockopen() で使用するものです。


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

openlog()オプション
定数 | 説明
LOG_CONS | システムロガーにデータを送信する際にエラーが発生した場合、 システムコンソールに直接書き込む。
LOG_NDELAY | ロガーにただちに接続をオープンする。
LOG_ODELAY | (デフォルト) 最初のメッセージが記録されるまで接続のオープンを 遅延させる。
LOG_NOWAIT |
LOG_PERROR | 標準エラー出力にもログメッセージを出力する
LOG_PID | 各メッセージにプロセスIDを含める
openlog() ファシリティ
定数 | 説明
LOG_AUTH | セキュリティ/認証メッセージ（LOG_AUTHPRIVが定義されているシステムであれば 代わりにそれを使用してください）
LOG_AUTHPRIV | セキュリティ/認証メッセージ (private)
LOG_CRON | 時刻デーモン (cron and at)
LOG_DAEMON | その他のシステムデーモン
LOG_KERN | カーネルメッセージ
LOG_LOCAL0 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL1 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL2 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL3 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL4 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL5 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL6 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LOCAL7 | ローカルで使用できるようリザーブされている。Windowsでは使用できない。
LOG_LPR | ラインプリンタサブシステム
LOG_MAIL | メールサブシステム
LOG_NEWS | USENETニュースサブシステム
LOG_SYSLOG | syslogdによって内部で生成されたメッセージ
LOG_USER | 一般ユーザーレベルのメッセージ
LOG_UUCP | UUCPサブシステム
syslog()プロパティ(降順)
定数 | 説明
LOG_EMERG | システムは使用不可
LOG_ALERT | アクションを直ちに起こすことが必要
LOG_CRIT | 危機的な条件
LOG_ERR | エラー条件
LOG_WARNING | 警告条件
LOG_NOTICE | 正常、しかし、注意すべき条件
LOG_INFO | 情報メッセージ
LOG_DEBUG | デバッグレベルメッセージ
dns_get_record()オプション
定数 | 説明
DNS_A | IPv4アドレスリソース
DNS_A6 | 初期のIPv6 で定義されていましたが、RFC 6563 によって歴史的な扱いに格下げされました。
DNS_CAA | Certification Authority Authorizationリソース (PHP 7.0.16 および 7.1.2 以降で使用可能)
DNS_MX | Mail Exchangerリソース
DNS_CNAME | エイリアス(Canonical Name)リソース
DNS_NAPTR | Naming Authorityポインタ
DNS_NS | Authoritative Name Serverリソース
DNS_PTR | ポインタリソース
DNS_HINFO | ホスト情報リソース（これらの値の意味については、IANA の » Operating System Names を参照ください）
DNS_SOA | 認証リソースの開始
DNS_SRV | サービスロケータ
DNS_TXT | テキストリソース
DNS_ANY | 全てのリソースレコード。多くのシステムでは、 これは、全てのリソースレコードを返します。 しかし、危機的な状況には対応できません。代わりに DNS_ALL を試してください。
DNS_AAAA | IPv6アドレスリソース
DNS_ALL | 利用可能なレコード型毎のネームサーバーへの反復クエリ。


ネットワーク 関数

目次

  • checkdnsrr — 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
  • closelog — システムログへの接続を閉じる
  • dns_check_record — checkdnsrr のエイリアス
  • dns_get_mx — getmxrr のエイリアス
  • dns_get_record — ホスト名に関連する DNS リソースレコードを取得する
  • fsockopen — インターネット接続もしくは Unix ドメインソケット接続をオープンする
  • gethostbyaddr — 指定した IP アドレスに対応するインターネットホスト名を取得する
  • gethostbyname — インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel — 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • gethostname — ホスト名を取得する
  • getmxrr — 指定したインターネットホスト名に対応する MX レコードを取得する
  • getprotobyname — プロトコル名のプロトコル番号を得る
  • getprotobynumber — プロトコル番号が指すプロトコル名を取得する
  • getservbyname — インターネットサービスおよびプロトコルが関連するポート番号を取得する
  • getservbyport — ポートおよびプロトコルに対応するインターネットサービスを得る
  • header — 生の HTTP ヘッダを送信する
  • header_register_callback — ヘッダ用の関数を登録する
  • header_remove — 以前に設定したHTTPヘッダを削除する
  • headers_list — 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • headers_sent — ヘッダが既に送信されているかどうかを調べる
  • http_response_code — HTTP レスポンスコードを取得または設定
  • inet_ntop — パックされたインターネットアドレスを、人間が読める形式に変換する
  • inet_pton — 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
  • ip2long — ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
  • long2ip — 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • net_get_interfaces — ネットワークインターフェイスを取得する
  • openlog — システムのロガーへの接続をオープンする
  • pfsockopen — 持続的な Internet または Unix ドメインソケット接続をオープンする
  • setcookie — クッキーを送信する
  • setrawcookie — 値を URL エンコードせずにクッキーを送信する
  • socket_get_status — stream_get_meta_data のエイリアス
  • socket_set_blocking — stream_set_blocking のエイリアス
  • socket_set_timeout — stream_set_timeout のエイリアス
  • syslog — システムログのメッセージを生成する


指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する

  • ≪ ネットワーク 関数
  • closelog ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する

checkdnsrr

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdnsrr — 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する

説明

checkdnsrr(string $hostname, string $type = "MX"): bool

hostname に対応する type 型のレコードを DNS から探します。

パラメータ

hostname

hostname は、ドットで 4 つに分けられた形式の IP アドレスか、あるいはホスト名です。

type

typeは、A, MX, NS, SOA, PTR, CNAME, AAAA, A6, SRV, NAPTR, ANY のどれか一つです。

戻り値

レコードが見つかった場合に true、 何も見つからないかエラーが発生した場合に false を返します。

注意

注意:

この関数が実装される前の Windows での互換性を保つには、 » PEAR の » Net_DNS クラスをお試しください。

参考

  • dns_get_record() - ホスト名に関連する DNS リソースレコードを取得する
  • getmxrr() - 指定したインターネットホスト名に対応する MX レコードを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • the named(8) manual page


システムログへの接続を閉じる

  • ≪ checkdnsrr
  • dns_check_record ≫
  • PHP Manual
  • ネットワーク 関数
  • システムログへの接続を閉じる

closelog

(PHP 4, PHP 5, PHP 7, PHP 8)

closelog — システムログへの接続を閉じる

説明

closelog(): true

closelog() はシステムログへの書きこみに使用されているデスクプリタを閉じます。 closelog() の使用はオプションです。

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。

参考

  • syslog() - システムログのメッセージを生成する
  • openlog() - システムのロガーへの接続をオープンする


checkdnsrr のエイリアス

  • ≪ closelog
  • dns_get_mx ≫
  • PHP Manual
  • ネットワーク 関数
  • checkdnsrr のエイリアス

dns_check_record

(PHP 5, PHP 7, PHP 8)

dns_check_record — checkdnsrr() のエイリアス

説明

この関数は次の関数のエイリアスです。 checkdnsrr().


getmxrr のエイリアス

  • ≪ dns_check_record
  • dns_get_record ≫
  • PHP Manual
  • ネットワーク 関数
  • getmxrr のエイリアス

dns_get_mx

(PHP 5, PHP 7, PHP 8)

dns_get_mx — getmxrr() のエイリアス

説明

この関数は次の関数のエイリアスです。 getmxrr().


ホスト名に関連する DNS リソースレコードを取得する

  • ≪ dns_get_mx
  • fsockopen ≫
  • PHP Manual
  • ネットワーク 関数
  • ホスト名に関連する DNS リソースレコードを取得する

dns_get_record

(PHP 5, PHP 7, PHP 8)

dns_get_record — ホスト名に関連する DNS リソースレコードを取得する

説明

dns_get_record(
string $hostname,
int $type = DNS_ANY,
array &$authoritative_name_servers = null,
array &$additional_records = null,
bool $raw = false
): array|false

指定した hostname に関連づけられた DNS リソースレコードを取得します。

パラメータ

hostname

hostname は、正しい DNS ホスト名、すなわち "www.example.com" のようなものでなければなりません。 in-addr.arpa 形式の表記を用いた逆引き検索は可能ですが、 たいていは gethostbyaddr() を用いるほうが適当です。

注意:

DNS の標準規格により、メールアドレスは user.host 形式で渡されます （たとえば、hostmaster.example.com が hostmaster@example.com の代わりとなります）。 この値をしっかり確認し、mail() のような関数で 利用する前には必要なら変更を加えることを忘れないようにしてください。

type

デフォルトでは、dns_get_record() は hostname に関連するすべてのリソースレコードを検索します。 これを制限するには、オプションの type パラメータを指定してください。 type は以下のうちのいずれかです。 DNS_A, DNS_CNAME, DNS_HINFO, DNS_CAA, DNS_MX, DNS_NS, DNS_PTR, DNS_SOA, DNS_TXT, DNS_AAAA, DNS_SRV, DNS_NAPTR, DNS_A6, DNS_ALL または DNS_ANY。

注意:

プラットフォーム依存の libresolv のおかしな挙動のせいで、 DNS_ANY が常にすべてのレコードを返すとは 限りません。速度は遅くなりますが、DNS_ALL のほうがより確実にすべてのレコードを取得できます。

注意:

Windows では、DNS_CAA はサポートされていませんし、 DNS_A6 は実装されていません。

authoritative_name_servers

参照で渡し、 Authoritative Name Servers のリソースレコードが格納されます。

additional_records

参照で渡し、 Additional Records が格納されます。

raw

type は生のDNSのタイプIDとして解釈されます。 (DNS_* 定数は使えません) 戻り値には手動でパースが必要な data キーが含まれます。

戻り値

この関数は、連想配列を要素にもつ配列を返します。 失敗した場合に false を返します。 それぞれの連想配列には 少なくとも 以下のキーが含まれています:

基本 DNS 属性
属性 | 意味
host | これ以降の関連するデータが参照する DNS 名。
class | dns_get_record() は Internet クラスのレコードのみを返すので、このパラメータは常に IN を返します。
type | レコード型を表す文字列。type の値に応じて、 結果の配列には追加の属性が含まれます。以下の表を参照ください。
ttl | このレコードの"有効期限 (Time To Live)"。レコードの本来の ttl と一致するとは 限りません。むしろ、 ネームサーバーへのクエリにかかった時間をそこから引いたものに一致します。

'type' に応じて連想配列に追加される項目
レコード型 | 追加項目
A | ip: ドット区切り 10 進数形式の IPv4 アドレス。
MX | pri: メールエクスチェンジャの優先度。 数字が小さいほど優先度が高い。 target: メールエクスチェンジャの FQDN 。 dns_get_mx() も参照ください。
CNAME | target: レコードのエイリアスの対象となっている場所の FQDN 。
NS | target: このホスト名に対する権威をもっているネームサーバーの FQDN 。
PTR | target: レコードが指している、DNS 名前空間内の場所
TXT | txt: このレコードに関連付けられている任意の文字列。
HINFO | cpu: このレコードが参照しているマシンの CPU を識別する IANA 番号。 os: このレコードが参照しているマシン上の OS を識別する IANA 番号。 これらの値の意味については、IANA の » Operating System Names を参照ください。
CAA | flags: 1バイトのビットフィールド; 現在はビット0だけが定義されており、'critical' を意味します。 他のビットは予約されており、無視されるべきです。 tag: CAA タグの名前 (alphanumeric な ASCII 文字列). value: CAA タグの値 (バイナリ文字列, サブフォーマットの使用可) 詳細は、» RFC 6844 を参照ください。
SOA | mname: リソースレコードの元となるマシンの FQDN 。 rname: このドメインの管理責任者の Email アドレス。 serial: ドメインのシリアル番号。 refresh: セカンダリネームサーバーがこのドメインのコピーを更新する際に参照するリフレッシュ間隔（秒単位）。 retry: リフレッシュが失敗した際に 2 度目のリフレッシュを試みるまでの間隔（秒単位） expire: セカンダリネームサーバーが、ゾーンデータの リフレッシュに失敗した場合にコピーのデータを破棄せず持ち続ける期間 （秒単位）。 minimum-ttl: クライアントが、 一度取得したデータを再リクエストすることなしに利用できる最小期間（秒単位）。 個々のリソースレコードによって上書きが可能。
AAAA | ipv6: IPv6 アドレス。
A6 | masklen: chain で指定された対象から引き継ぐビット長。 ipv6: chain とマージするためのこのレコードのアドレス。 chain: ipv6 データとマージするための親レコード。
SRV | pri: (Priority) 値が小さいものが優先されます。 weight: 同じ優先順位の targets からランダムに選択する際の重み。 target および port: リクエストされたサービスが存在するホスト名とポート。 詳細は » RFC 2782 を参照ください。
NAPTR | order および pref: 上の pri および weight と同じ。 flags, services, regex, および replacement: » RFC 2915 で定義されるパラメータ。

変更履歴

バージョン | 説明
7.0.16, 7.1.2 | CAA レコード型のサポートが追加されました。

例

例1 dns_get_record() の使用

<?php
$result = dns_get_record("php.net");
print_r($result);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)

例2 dns_get_record() と DNS_ANY の使用

MX レコードが解決されれば、たいていはメールサーバーの IP アドレスを 取得したくなるものです。そのため、dns_get_record() は additional_records に関連するレコードを含めて返します。 また、authoritative_name_servers には 権威のあるネームサーバーのリストを含めて返します。

<?php
/* php.net の "ANY" レコードを要求し、
それに付随する情報を格納した配列を
作成する。
$authns にはネームサーバーの一覧が、
また $addtl には追加レコードが
それぞれ格納される。 */
$result = dns_get_record("php.net", DNS_ANY, $authns, $addtl);
echo "Result = ";
print_r($result);
echo "Auth NS = ";
print_r($authns);
echo "Additional = ";
print_r($addtl);
?>

上の例の出力は、 たとえば以下のようになります。

Result = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)
Auth NS = Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [1] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => remote2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [2] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns1.easydns.com
            [class] => IN
            [ttl] => 10722
        )

    [3] => Array
        (
            [host] => php.net
            [type] => NS
            [target] => ns2.easydns.com
            [class] => IN
            [ttl] => 10722
        )

)
Additional = Array
(
    [0] => Array
        (
            [host] => pair2.php.net
            [type] => A
            [ip] => 216.92.131.5
            [class] => IN
            [ttl] => 6766
        )

    [1] => Array
        (
            [host] => remote1.easydns.com
            [type] => A
            [ip] => 64.39.29.212
            [class] => IN
            [ttl] => 100384
        )

    [2] => Array
        (
            [host] => remote2.easydns.com
            [type] => A
            [ip] => 212.100.224.80
            [class] => IN
            [ttl] => 81241
        )

    [3] => Array
        (
            [host] => ns1.easydns.com
            [type] => A
            [ip] => 216.220.40.243
            [class] => IN
            [ttl] => 81241
        )

    [4] => Array
        (
            [host] => ns2.easydns.com
            [type] => A
            [ip] => 216.220.40.244
            [class] => IN
            [ttl] => 81241
        )

)

参考

  • dns_get_mx() - getmxrr のエイリアス
  • dns_check_record() - checkdnsrr のエイリアス


インターネット接続もしくは Unix ドメインソケット接続をオープンする

  • ≪ dns_get_record
  • gethostbyaddr ≫
  • PHP Manual
  • ネットワーク 関数
  • インターネット接続もしくは Unix ドメインソケット接続をオープンする

fsockopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fsockopen — インターネット接続もしくは Unix ドメインソケット接続をオープンする

説明

fsockopen(
string $hostname,
int $port = -1,
int &$error_code = null,
string &$error_message = null,
?float $timeout = null
): resource|false

hostname で指定したリソースへのソケット接続を開始します。

サポートされるソケットトランスポートのリスト に記述されているように、PHP は Internet ドメインまたは Unix ドメインをサポートします。 サポートされるトランスポートのリストは、stream_get_transports() を使って取得することもできます。

ソケットはデフォルトでブロックモードで開かれます。 socket_set_blocking() を使用して、 非ブロックモードに切換えることができます。

stream_socket_client() 関数もこれと似ていますがより豊富なオプションを持っており、 非ブロック接続をしたりストリームコンテキストを提供したりする機能があります。

パラメータ

hostname

OpenSSL サポートが インストール されている場合、 hostname の前に ssl:// または tls:// を付加することにより、TCP/IP 経由でリモートホストに接続する際に SSL または TLS クライアント接続を使用することができます。

port

ポート番号。 unix:// のようにポートを使わないトランスポートの場合は、 -1 で無視してスキップさせることができます。

error_code

指定した場合は、システムコール connect() で発生したエラーのエラー番号が格納されます。

error_code は 0 なのに関数が false を返す場合、connect() をコールする前にエラーを発生したことを示します。 この場合、おそらくはソケットの初期化に原因があります。

error_message

エラーメッセージを表す文字列。

timeout

接続タイムアウト秒数。 null の場合は、 php.ini の default_socket_timeout 設定を使います。

注意:

ソケット経由でデータを読み書きする際のタイムアウトを設定する必要がある場合、 fsockopen() の timeout パラメータは、 ソケットに接続する間にだけ適用されるため、 socket_set_timeout() を使用してください。

戻り値

fsockopen()は、ファイルポインタを返します。 このファイルポインタは、 (fgets(), fgetss(), fputs(), fclose(), feof() のような) 他のファイル関数で使用可能です。 失敗した場合は false を返します。

エラー / 例外

hostname が有効なドメインでない場合は E_WARNING をスローします。

変更履歴

バージョン | 説明
8.0.0 | timeout は、nullable になりました。

例

例1 fsockopen() の例

<?php
$fp = fsockopen("www.example.com", 80, $errno, $errstr, 30);
if (!$fp) {
echo "$errstr ($errno)<br />\n";
} else {
$out = "GET / HTTP/1.1\r\n";
$out .= "Host: www.example.com\r\n";
$out .= "Connection: Close\r\n\r\n";
fwrite($fp, $out);
while (!feof($fp)) {
echo fgets($fp, 128);
}
fclose($fp);
}
?>

例2 UDP 接続の使用法

以下の例は、自分のマシンの UDP サービス "daytime" (ポート13) から日付と時間を取得する方法を示すものです。

<?php
$fp = fsockopen("udp://127.0.0.1", 13, $errno, $errstr);
if (!$fp) {
echo "ERROR: $errno - $errstr<br />\n";
} else {
fwrite($fp, "\n");
echo fread($fp, 26);
fclose($fp);
}
?>

注意

注意:

環境によっては Unix ドメインまたは オプションの接続タイムアウトが利用できないこともあります。

警告

UDPソケットは、リモートホストとの接続が確立されていない場合でも、 エラーを発生せずにオープンされたように見えることが時々あります。 このエラーは、そのソケットでデータを読み書きした際にのみ明らかになります。 この原因は、UDPが"コネクションレス"のプロトコルであり、 実際にデータを送受信する必要が生じるまで、 オペレーションシステムがソケット用のリンクを確立しようとしないためです。

注意: 数値で IPv6 アドレスを指定するときは、 (例 fe80::1) アドレスを角カッコでくくらなくてはなりません。たとえば、 tcp://[fe80::1]:80.

参考

  • pfsockopen() - 持続的な Internet または Unix ドメインソケット接続をオープンする
  • stream_socket_client() - インターネットドメインまたは Unix ドメインのソケット接続を開く
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する
  • stream_set_timeout() - ストリームにタイムアウトを設定する
  • fgets() - ファイルポインタから 1 行取得する
  • fgetss() - ファイルポインタから 1 行取り出し、HTML タグを取り除く
  • fwrite() - バイナリセーフなファイル書き込み処理
  • fclose() - オープンされたファイルポインタをクローズする
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • socket_connect() - ソケット上の接続を初期化する
  • Curl 拡張モジュール


指定した IP アドレスに対応するインターネットホスト名を取得する

  • ≪ fsockopen
  • gethostbyname ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定した IP アドレスに対応するインターネットホスト名を取得する

gethostbyaddr

(PHP 4, PHP 5, PHP 7, PHP 8)

gethostbyaddr — 指定した IP アドレスに対応するインターネットホスト名を取得する

説明

gethostbyaddr(string $ip): string|false

ip で指定したインターネットホストのホスト名を返します。

パラメータ

ip

ホストの IP アドレス。

戻り値

成功した場合はホスト名を返します。 失敗した場合は、そのままの形の ip を文字列で返します。 入力が壊れている場合は false を返します。

例

例1 単純な gethostbyaddr() の例

<?php
$hostname = gethostbyaddr($_SERVER['REMOTE_ADDR']);

echo $hostname;
?>

参考

  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する


インターネットホスト名に対応するIPv4アドレスを取得する

  • ≪ gethostbyaddr
  • gethostbynamel ≫
  • PHP Manual
  • ネットワーク 関数
  • インターネットホスト名に対応するIPv4アドレスを取得する

gethostbyname

(PHP 4, PHP 5, PHP 7, PHP 8)

gethostbyname — インターネットホスト名に対応するIPv4アドレスを取得する

説明

gethostbyname(string $hostname): string

hostname で指定したインターネットホストの IPv4 アドレスを返します。

パラメータ

hostname

ホスト名。

戻り値

IPv4 アドレスを返します。失敗した場合は、そのままの形の hostname を文字列で返します。

例

例1 単純な gethostbyname() の例

<?php
$ip = gethostbyname('www.example.com');

echo $ip;
?>

参考

  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • inet_pton() - 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
  • inet_ntop() - パックされたインターネットアドレスを、人間が読める形式に変換する


指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

  • ≪ gethostbyname
  • gethostname ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

gethostbynamel

(PHP 4, PHP 5, PHP 7, PHP 8)

gethostbynamel — 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する

説明

gethostbynamel(string $hostname): array|false

hostname で指定したインターネットホストを検索して得られた IPv4 アドレスのリストを返します。

パラメータ

hostname

ホスト名。

戻り値

IPv4 アドレスの配列を返します。 もし hostname が解決できなかった場合は false を返します。

例

例1 gethostbynamel() の例

<?php
$hosts = gethostbynamel('www.example.com');
print_r($hosts);
?>

上の例の出力は以下となります。

Array
(
    [0] => 192.0.34.166
)

参考

  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • checkdnsrr() - 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
  • getmxrr() - 指定したインターネットホスト名に対応する MX レコードを取得する
  • the named(8) manual page


ホスト名を取得する

  • ≪ gethostbynamel
  • getmxrr ≫
  • PHP Manual
  • ネットワーク 関数
  • ホスト名を取得する

gethostname

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gethostname — ホスト名を取得する

説明

gethostname(): string|false

gethostname() 関数は、ローカルのマシンに設定されている標準的なホスト名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時にはホスト名を示す文字列。失敗時には false を返します

例

例1 簡単な gethostname() 関数の使用例

<?php
echo gethostname(); // 出力の例: sandie
?>

参考

  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • php_uname() - PHP が稼動しているオペレーティングシステムに関する情報を返す


指定したインターネットホスト名に対応する MX レコードを取得する

  • ≪ gethostname
  • getprotobyname ≫
  • PHP Manual
  • ネットワーク 関数
  • 指定したインターネットホスト名に対応する MX レコードを取得する

getmxrr

(PHP 4, PHP 5, PHP 7, PHP 8)

getmxrr — 指定したインターネットホスト名に対応する MX レコードを取得する

説明

getmxrr(string $hostname, array &$hosts, array &$weights = null): bool

hostname に対応する MX レコードを DNS から探します。

パラメータ

hostname

インターネットホスト名。

hosts

見つかった MX レコードのリストが、配列 hosts に格納されます。

weights

配列 weights を指定すると、 そこに重み情報が格納されます。

戻り値

何かレコードが見つかった場合に true、 何も見つからないかエラーが発生した場合に false を返します。

注意

注意:

この関数をメールアドレスの確認の目的で使用すべきではありません。 DNS が検出したメールエクスチェンジャーを返すだけです。 しかし、» RFC 2821 によれば、 メールエクスチェンジャーがひとつも見つからなければ、 hostname 自体が唯一のメールエクスチェンジャー であるとみなされ、その優先度は 0（最高）となります。

注意:

この関数が実装される前の Windows での互換性を保つには、 » PEAR の » Net_DNS クラスを試してみてください。

参考

  • checkdnsrr() - 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
  • dns_get_record() - ホスト名に関連する DNS リソースレコードを取得する
  • gethostbyname() - インターネットホスト名に対応するIPv4アドレスを取得する
  • gethostbynamel() - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
  • gethostbyaddr() - 指定した IP アドレスに対応するインターネットホスト名を取得する
  • named(8) のマニュアルページ


プロトコル名のプロトコル番号を得る

  • ≪ getmxrr
  • getprotobynumber ≫
  • PHP Manual
  • ネットワーク 関数
  • プロトコル名のプロトコル番号を得る

getprotobyname

(PHP 4, PHP 5, PHP 7, PHP 8)

getprotobyname — プロトコル名のプロトコル番号を得る

説明

getprotobyname(string $protocol): int|false

getprotobyname()は、プロトコル protocol のプロトコル番号を /etc/protocols から取得して返します。

パラメータ

protocol

プロトコル名。

戻り値

プロトコル番号を返します。 失敗した場合に false を返します。

例

例1 getprotobyname() の例

<?php
$protocol = 'tcp';
$get_prot = getprotobyname($protocol);
if ($get_prot === FALSE) {
echo '無効なプロトコル';
} else {
echo 'プロトコル番号: ' . $get_prot;
}
?>

参考

  • getprotobynumber() - プロトコル番号が指すプロトコル名を取得する


プロトコル番号が指すプロトコル名を取得する

  • ≪ getprotobyname
  • getservbyname ≫
  • PHP Manual
  • ネットワーク 関数
  • プロトコル番号が指すプロトコル名を取得する

getprotobynumber

(PHP 4, PHP 5, PHP 7, PHP 8)

getprotobynumber — プロトコル番号が指すプロトコル名を取得する

説明

getprotobynumber(int $protocol): string|false

getprotobynumber() は、 /etc/protocols に基づき プロトコル番号 protocol が指すプロトコル名を返します。

パラメータ

protocol

プロトコル番号。

戻り値

プロトコル名を文字列で返します。失敗した場合に false を返します。

参考

  • getprotobyname() - プロトコル名のプロトコル番号を得る


インターネットサービスおよびプロトコルが関連するポート番号を取得する

  • ≪ getprotobynumber
  • getservbyport ≫
  • PHP Manual
  • ネットワーク 関数
  • インターネットサービスおよびプロトコルが関連するポート番号を取得する

getservbyname

(PHP 4, PHP 5, PHP 7, PHP 8)

getservbyname — インターネットサービスおよびプロトコルが関連するポート番号を取得する

説明

getservbyname(string $service, string $protocol): int|false

getservbyname() は、 /etc/services に基づき 指定したプロトコル protocol に関して service に対応するインターネットポートを返します。

パラメータ

service

インターネットサービス名を表す文字列。

protocol

protocol は "tcp" あるいは "udp" (小文字) のいずれかです。

戻り値

ポート番号を返します。 service あるいは protocol が見つからない場合は false を返します。

例

例1 getservbyname() の例

<?php
$services = array('http', 'ftp', 'ssh', 'telnet', 'imap',
'smtp', 'nicname', 'gopher', 'finger', 'pop3', 'www');

foreach ($services as $service) {
$port = getservbyname($service, 'tcp');
echo $service . ": " . $port . "<br />\n";
}
?>

参考

  • getservbyport() - ポートおよびプロトコルに対応するインターネットサービスを得る
  • ポート番号の完全なリストは » http://www.iana.org/assignments/port-numbers


ポートおよびプロトコルに対応するインターネットサービスを得る

  • ≪ getservbyname
  • header ≫
  • PHP Manual
  • ネットワーク 関数
  • ポートおよびプロトコルに対応するインターネットサービスを得る

getservbyport

(PHP 4, PHP 5, PHP 7, PHP 8)

getservbyport — ポートおよびプロトコルに対応するインターネットサービスを得る

説明

getservbyport(int $port, string $protocol): string|false

getservbyport() は、 /etc/services に基づき 指定したプロトコル protocol に関してポート port に関連するインターネットサービスを返します。

パラメータ

port

ポート番号。

protocol

protocol は "tcp" あるいは "udp" (小文字) のいずれかです。

戻り値

インターネットサービス名を文字列で返します。 失敗した場合に false を返します

参考

  • getservbyname() - インターネットサービスおよびプロトコルが関連するポート番号を取得する


生の HTTP ヘッダを送信する

  • ≪ getservbyport
  • header_register_callback ≫
  • PHP Manual
  • ネットワーク 関数
  • 生の HTTP ヘッダを送信する

header

(PHP 4, PHP 5, PHP 7, PHP 8)

header — 生の HTTP ヘッダを送信する

説明

header(string $header, bool $replace = true, int $response_code = 0): void

header() は、生の HTTP ヘッダを送信するために使用されます。 HTTP ヘッダについての詳細な情報は » HTTP/1.1 仕様 を参照ください。

覚えておいて頂きたいのは、header() 関数は、 通常の HTML タグまたは PHP からの出力にかかわらず、すべての実際の 出力の前にコールする必要があることです。 頻出するエラーとして、include または require 関数、他のファイルをアクセスする関数に 空白または空行があり、header() の前に出力が 行われてしまうというものがあります。同じ問題は、単一の PHP/HTML ファイルを使用している場合でも存在します。

<html>
<?php
/* これはエラーとなります。この上に出力があることに注目してください。
* それはheader()のコールより前であるということになります */
header('Location: http://www.example.com/');
exit;
?>

パラメータ

header

ヘッダ文字列。

特殊な header コールが 2 種類あります。最初のものは、 文字列 "HTTP/" から始まる全てのヘッダ (大文字・小文字は区別されません) です。 このヘッダは、送信する HTTP ステータスコードを示すために使用されます。 例えば、存在しないファイルへのリクエストを処理するためにある PHP スクリプトを使用するよう (ErrorDocument ディレクティブにより) Apache を設定する場合、 そのスクリプトが正しいステータスコードを返すようにする必要があります。

<?php
// この例は、"HTTP/" から始まる特別な場合を示しています。
// これより良い、典型的な使い方として、以下があげられます:
// 1. header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
// (HTTP/1.0 を使いながら、httpステータスメッセージを上書きする)
// 2. http_response_code(404); (デフォルトのメッセージを使う)
header("HTTP/1.1 404 Not Found");
?>

2 番目の特別なヘッダは、"Location:" ヘッダです。このヘッダがブラウザに返されるだけではなく、 ブラウザに REDIRECT (302) ステータスコードを返します (201 や 3xx ステータスコードが既に送信されていない場合にのみ)。

<?php
header("Location: http://www.example.com/"); /* ブラウザをリダイレクトします */

/* リダイレクトする際に、これ以降のコードが実行されないことを確認してください */
exit;
?>

replace

オプションのパラメータ replace は、ヘッダが 前に送信された類似のヘッダを置換するか、または、同じ形式の二番目の ヘッダを追加するかどうかを指定します。デフォルトでは、この関数は 置換を行ないますが、二番目の引数に false を指定すると、同じ型の 複数のヘッダを強制的に生成します。例えば、

<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>

response_code

HTTP レスポンスコードを強制的に指定の値にします。このパラメータが意味をなすのは header が空文字列でないときだけであることに注意しましょう。

戻り値

値を返しません。

エラー / 例外

ヘッダを予定通りに送信できなかった場合、 header() 関数は E_WARNING レベルの警告を発生させます。

例

例1 ダウンロードダイアログ

PDF ファイルを生成した場合など、 それをダウンロードするかの確認ダイアログを表示させたいことがあるでしょう。 そんな場合は、» Content-Disposition ヘッダを使用してファイル名を指定すると、ブラウザ側でダイアログを表示させることができます。

<?php
// PDFを出力します
header('Content-Type: application/pdf');

// downloaded.pdf という名前で保存させます
header('Content-Disposition: attachment; filename="downloaded.pdf"');

// もとの PDF ソースは original.pdf です
readfile('original.pdf');
?>

例2 キャッシュディレクティブ

PHP スクリプトはしばしば動的に HTML を生成するため、クライアント ブラウザやサーバーおよびクライアントブラウザの間でプロキシがキャッシュを 行ったりするべきではありません。多くのプロキシとクライアントでは、 以下のコードにより強制的にキャッシュを無効にできます。

<?php
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // 過去の日付
?>

注意:

上記のヘッダを全て出力しなかったとしてもページのキャッシュが 行われない場合があることに気付くかもしれません。デフォルトの ブラウザのキャッシュの動作をユーザーが変更できる手段はいくつもあります。 上記のヘッダを送信することにより、スクリプトの出力がキャッシュされる 可能性がある設定を上書きするべきです。

さらに、session_cache_limiter() および 設定 session.cache_limiter を用いると、 セッションが使用された際にキャッシュ関係の正しいヘッダを 自動的に生成させることもできます。

例3 クッキーを設定する

setcookie() は、クッキーを設定する便利な方法を提供します。
setcookie() がサポートしていない属性をクッキーに設定する方法として、
header() が使えます。

たとえば、以下のコードは Partitioned 属性を含むクッキーを設定します。

<?php
header('Set-Cookie: name=value; Secure; Path=/; SameSite=None; Partitioned;');
?>

注意

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

注意:

出力のバッファリングを使用してこの問題を回避することができます。 この場合、ブラウザへの出力が送信するまでサーバーに 全てバッファリングされるオーバーヘッドがあります。出力バッファリングは、 ob_start() と ob_end_flush() をスクリプトでコールするか php.ini またはサーバー設定ファイルの設定ディレクティブ output_buffering を設定することにより 行うことが可能です。

注意:

実際に header() が最初にコールされたか どうかにかかわらず、HTTP ステータスヘッダ行は クライアントに対し常に最初に送信されます。 HTTP ヘッダが既に送信されていない限り、 header() をコールすることでステータスは 常に上書きされます。

注意:

最近のクライアントの大半は » Location: への引数として相対 URI も受け付けますが、 古いクライアントの中にはスキームとホスト名そして絶対パスを含む絶対 URL しか受け付けないものもあります。 通常は、相対 URI から絶対 URI を作成するためには $_SERVER['HTTP_HOST']、 $_SERVER['PHP_SELF'] および dirname() を使用できます。

<?php
/* カレントディレクトリの別のページにリダイレクトします */
$host = $_SERVER['HTTP_HOST'];
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
$extra = 'mypage.php';
header("Location: http://$host$uri/$extra");
exit;
?>

注意:

session.use_trans_sid が有効であったとしても、セッション ID が Location ヘッダとともに 渡されることはありません。SID 定数を使用して 手動で渡す必要があります。

参考

  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
  • setcookie() - クッキーを送信する
  • http_response_code() - HTTP レスポンスコードを取得または設定
  • header_remove() - 以前に設定したHTTPヘッダを削除する
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • HTTP 認証


ヘッダ用の関数を登録する

  • ≪ header
  • header_remove ≫
  • PHP Manual
  • ネットワーク 関数
  • ヘッダ用の関数を登録する

header_register_callback

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

header_register_callback — ヘッダ用の関数を登録する

説明

header_register_callback(callable $callback): bool

PHP が出力を送信しはじめるときにコールする関数を登録します。

callback が実行されるのは、 PHP がすべてのヘッダを送出し終えてからその他の出力を始めるまでの間です。 ここで、送信する前のヘッダを操作できます。

パラメータ

callback

ヘッダを送信する前にコールする関数。パラメータは受け取らず、戻り値も無視されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 header_register_callback() の例

<?php

header('Content-Type: text/plain');
header('X-Test: foo');

function foo() {
foreach (headers_list() as $header) {
if (strpos($header, 'X-Powered-By:') !== false) {
header_remove('X-Powered-By');
}
header_remove('X-Test');
}
}

$result = header_register_callback('foo');
echo "a";
?>

上の例の出力は、 たとえば以下のようになります。

Content-Type: text/plain

a

注意

header_register_callback() はヘッダを送出しようとするときに実行されるので、 この関数の中で何らかの出力をしてしまうと出力が壊れてしまいます。

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

参考

  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • header_remove() - 以前に設定したHTTPヘッダを削除する
  • header() - 生の HTTP ヘッダを送信する


以前に設定したHTTPヘッダを削除する

  • ≪ header_register_callback
  • headers_list ≫
  • PHP Manual
  • ネットワーク 関数
  • 以前に設定したHTTPヘッダを削除する

header_remove

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

header_remove — 以前に設定したHTTPヘッダを削除する

説明

header_remove(?string $name = null): void

header()関数を使って以前に設定したHTTPヘッダを削除します。

パラメータ

name

削除するヘッダの名前。 null の場合は、以前に設定されたヘッダ全てが削除されます。

注意: このパラメータは大文字小文字を区別しません

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | name は、nullable になりました。

例

例1 特定のヘッダを削除する

<?php
header("X-Foo: Bar");
header("X-Bar: Baz");
header_remove("X-Foo");
?>

上の例の出力は、 たとえば以下のようになります。

X-Bar: Baz

例2 以前設定したすべてヘッダを削除する

<?php
header("X-Foo: Bar");
header("X-Bar: Baz");
header_remove();
?>

上の例の出力は、 たとえば以下のようになります。

注意

警告

    この関数はPHPが設定した すべての ヘッダを削除します。
    削除されるヘッダには、cookie や セッション、X-Powered-By があります。

注意:

    ヘッダにアクセスできたりヘッダを出力したりするのは、
    それに対応した SAPI を使っている場合のみです。

参考

  • header() - 生の HTTP ヘッダを送信する
    •

  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
    •


送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

  • ≪ header_remove
  • headers_sent ≫
  • PHP Manual
  • ネットワーク 関数
  • 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

headers_list

(PHP 5, PHP 7, PHP 8)

headers_list — 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す

説明

headers_list(): array

headers_list() はブラウザもしくはクライアントに送信されるヘッダの数値配列を返します。 これらのヘッダが送信されたかどうかを判断するためには headers_sent() を使用します。

パラメータ

この関数にはパラメータはありません。

戻り値

ヘッダを、数値添字の配列で返します。

例

例1 Example using headers_list()

<?php

/* setcookie() でレスポンスヘッダをそれ自身に追加します */
setcookie('foo', 'bar');

/* 独自のレスポンスヘッダを定義します。
これはほとんどのクライアントで無視されます */
header("Example-Test: foo");

/* レスポンスがプレーンテキストだと宣言します */
header('Content-Type: text/plain; CHARSET=shift-jis');

/* 送信しようとしているヘッダは? */
var_dump(headers_list());

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  [0]=>
  string(19) "Set-Cookie: foo=bar"
  [1]=>
  string(17) "Example-Test: foo"
  [2]=>
  string(39) "Content-Type: text/plain; CHARSET=shift-jis"
}

注意

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

参考

  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
  • header() - 生の HTTP ヘッダを送信する
  • setcookie() - クッキーを送信する
  • apache_response_headers() - HTTPレスポンスヘッダを全て取得する
  • http_response_code() - HTTP レスポンスコードを取得または設定


ヘッダが既に送信されているかどうかを調べる

  • ≪ headers_list
  • http_response_code ≫
  • PHP Manual
  • ネットワーク 関数
  • ヘッダが既に送信されているかどうかを調べる

headers_sent

(PHP 4, PHP 5, PHP 7, PHP 8)

headers_sent — ヘッダが既に送信されているかどうかを調べる

説明

headers_sent(string &$filename = null, int &$line = null): bool

ヘッダがすでに送信されているかどうかを調べます。

ヘッダブロックがいったん送信されてしまった後で header() 関数を使って新たなヘッダ行を送信することはできません。 この関数を使うには、少なくとも HTTP ヘッダ関連のエラーを予防する必要があります。 あるいは、出力バッファリング を使う方法もあります。

パラメータ

filename

オプション引数の filename と line がセットされている場合、 PHP のソースファイル名と出力が開始された行番号が、それぞれ filename と line に格納されます。

注意:

PHP のソースファイルを実行する前(たとえば、実行開始時にエラーが発生した場合) に出力が開始された場合、 filename は空文字列になります。

line

出力を開始した行番号。

戻り値

headers_sent() は、HTTP ヘッダがまだ送信されていない場合に false、 そうでないでない場合に true を返します。

例

例1 headers_sent() 関数の使用例

<?php

// ヘッダがまだ何も送信されていない場合に、送信します
if (!headers_sent()) {
header('Location: http://www.example.com/');
exit;
}

// オプションのfileとlineパラメータの使用例
// $filename と $linenum が後で使用されていることに注目。
// これらの変数に事前に値を与えたりしてはいけません。
if (!headers_sent($filename, $linenum)) {
header('Location: http://www.example.com/');
exit;

// おそらく、ここでエラー処理を行うでしょう。
} else {

echo "$filename の $linenum 行目でヘッダがすでに送信されています。\n" .
"リダイレクトできません。代わりにこの <a " .
"href=\"http://www.example.com\">リンク</a> をクリックしてください。\n";
exit;
}

?>

注意

注意:

ヘッダにアクセスできたりヘッダを出力したりするのは、 それに対応した SAPI を使っている場合のみです。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
  • 関連する詳細な情報については header() - 生の HTTP ヘッダを送信する


HTTP レスポンスコードを取得または設定

  • ≪ headers_sent
  • inet_ntop ≫
  • PHP Manual
  • ネットワーク 関数
  • HTTP レスポンスコードを取得または設定

http_response_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

http_response_code — HTTP レスポンスコードを取得または設定

説明

http_response_code(int $response_code = 0): int|bool

HTTP レスポンスのステータスコードを取得したり設定したりします。

パラメータ

response_code

オプションの response_code は、レスポンスコードを設定します。

戻り値

response_code を指定した場合は、変更前に設定されていたステータスコードを返します。 response_code を省略した場合は、現在のステータスコードを返します。 どちらの場合でも、Web サーバー環境におけるデフォルトのステータスコードは 200 です。

response_code が省略されており、 かつ Web サーバー環境以外 (CLI アプリケーションなど) で実行した場合には、false を返します。 response_code を指定して、 かつ Web サーバー環境以外 (CLI アプリケーションなど) で実行した場合 (ただし、事前にレスポンスのステータスが設定されていない場合に限る) には、true を返します。

例

例1 Web サーバー環境における http_response_code() の使用例

<?php

// 現在のレスポンスコードを取得して、新しいコードを設定します
var_dump(http_response_code(404));

// 新しいレスポンスコードを取得します
var_dump(http_response_code());
?>

上の例の出力は以下となります。

int(200)
int(404)

例2 CLI 環境における http_response_code() の使用例

<?php

// 現在のデフォルトのレスポンスコードを取得します
var_dump(http_response_code());

// レスポンスコードを設定します
var_dump(http_response_code(201));

// 新しいレスポンスコードを取得します
var_dump(http_response_code());
?>

上の例の出力は以下となります。

bool(false)
bool(true)
int(201)

参考

  • header() - 生の HTTP ヘッダを送信する
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す


パックされたインターネットアドレスを、人間が読める形式に変換する

  • ≪ http_response_code
  • inet_pton ≫
  • PHP Manual
  • ネットワーク 関数
  • パックされたインターネットアドレスを、人間が読める形式に変換する

inet_ntop

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

inet_ntop — パックされたインターネットアドレスを、人間が読める形式に変換する

説明

inet_ntop(string $ip): string|false

この関数は 32 ビット IPv4 形式あるいは 128 ビット IPv6 形式 (PHP が IPv6 サポートを有効にしてビルドされている場合) のアドレスを文字列表現のアドレスに変換します。

パラメータ

ip

32 ビット IPv4、あるいは 128b ビット IPv6 形式のアドレス。

戻り値

アドレスを文字列で表したものを返します。失敗した場合に false を返します。

例

例1 inet_ntop() の例

<?php
$packed = chr(127) . chr(0) . chr(0) . chr(1);
$expanded = inet_ntop($packed);

/* 出力: 127.0.0.1 */
echo $expanded;

$packed = str_repeat(chr(0), 15) . chr(1);
$expanded = inet_ntop($packed);

/* 出力: ::1 */
echo $expanded;
?>

参考

  • long2ip() - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • ip2long() - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
  • inet_pton() - 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する


人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

  • ≪ inet_ntop
  • ip2long ≫
  • PHP Manual
  • ネットワーク 関数
  • 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

inet_pton

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

inet_pton — 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する

説明

inet_pton(string $ip): string|false

この関数は、人間が読める形式の IPv4 あるいは IPv6 (PHP が IPv6 サポートを有効にしてビルドされている場合) のアドレスを 32 ビットあるいは 128 ビットのバイナリ形式に変換します。

パラメータ

ip

可読形式の IPv4 アドレスあるいは IPv6 アドレス。

戻り値

指定した ip を in_addr 形式で表したものを返します。 構文的に無効な ip (ドットのない IPv4 アドレスやコロンのない IPv6 アドレスなど) を指定した場合は false を返します。

例

例1 inet_pton() の例

<?php
$in_addr = inet_pton('127.0.0.1');

$in6_addr = inet_pton('::1');
?>

参考

  • ip2long() - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
  • long2ip() - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • inet_ntop() - パックされたインターネットアドレスを、人間が読める形式に変換する


ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

  • ≪ inet_pton
  • long2ip ≫
  • PHP Manual
  • ネットワーク 関数
  • ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

ip2long

(PHP 4, PHP 5, PHP 7, PHP 8)

ip2long — ドット表記の (IPv4) IP アドレスを、長整数表現に変換する

説明

ip2long(string $ip): int|false

関数 ip2long() は、インターネット標準形式 (ドット表記の文字列) 表現から、長整数表現の IPv4 インターネットネットアドレスを生成します。

ip2long() は不完全な形式の IP アドレスに対しても動作します。詳しい情報は » http://ps-2.kev009.com/wisclibrary/aix52/usr/share/man/info/en_US/a_doc_lib/libs/commtrf2/inet_addr.htm を参照ください。

パラメータ

ip

標準形式のアドレス。

戻り値

長整数値、あるいは ip が不正な形式の場合に false を返します。

例

例1 ip2long() の例

<?php
$ip = gethostbyname('www.example.com');
$out = "以下の URL は同じ意味です:<br />\n";
$out .= 'http://www.example.com/, http://' . $ip . '/, そして http://' . sprintf("%u", ip2long($ip)) . "/<br />\n";
echo $out;
?>

例2 IP アドレスの表示

2 番目の例は、変換されたアドレスを printf() 関数で出力する方法を示すものです。

<?php
$ip = gethostbyname('www.example.com');
$long = ip2long($ip);

if ($long == -1 || $long === FALSE) {
echo '無効な IP です。もういちど確認してください。';
} else {
echo $ip . "\n"; // 192.0.34.166
echo $long . "\n"; // 3221234342 (32 ビット・システムでの -1073732954。整数オーバーフローによるものです)
printf("%u\n", ip2long($ip)); // 3221234342
}
?>

注意

注意:

PHP の整数型は符号付き形式であり、32 ビットアーキテクチャ上では 多くの IP アドレスが負の整数値になります。 そのため、符号なし IP アドレスを文字列形式で取得するには sprintf() や printf() で "%u" を使用する必要があります。

注意:

32 ビット・システムでは、整数オーバーフローにより、ip2long() は -1 を返します。

参考

  • long2ip() - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
  • sprintf() - フォーマットされた文字列を返す


長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する

  • ≪ ip2long
  • net_get_interfaces ≫
  • PHP Manual
  • ネットワーク 関数
  • 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する

long2ip

(PHP 4, PHP 5, PHP 7, PHP 8)

long2ip — 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する

説明

long2ip(int $ip): string

関数long2ip() は、長整数表現のアドレスからドット表記 (例:aaa.bbb.ccc.ddd)のインターネットアドレスを生成します。

パラメータ

ip

長整数で表した、正しい形式のアドレス。

戻り値

インターネットの IP アドレスを表す文字列を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.1.0 | ip の型が string から int に変更されました。

注意

注意:

32ビットアーキテクチャでは、IPアドレスの整数表現を string から int にキャストしても PHP_INT_MAX を超える数値については正しい結果を得られません。

参考

  • ip2long() - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する


ネットワークインターフェイスを取得する

  • ≪ long2ip
  • openlog ≫
  • PHP Manual
  • ネットワーク 関数
  • ネットワークインターフェイスを取得する

net_get_interfaces

(PHP 7 >= 7.3, PHP 8)

net_get_interfaces — ネットワークインターフェイスを取得する

説明

net_get_interfaces(): array|false

ローカルマシン上にあるネットワークインターフェイス(アダプタ) の一覧を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an associative array where the key is the name of the interface and the value an associative array of interface attributes, 失敗した場合に false を返します.

Each interface associative array contains:

インターフェイスの属性
名前 | 説明
description | インターフェイスの説明を示すオプションの値。 Windows でのみ有効です。
mac | インターフェイスのMACアドレスを示すオプションの値。 Windows でのみ有効です。
mtu | インターフェイスのMTUを示す整数値。 Windows でのみ有効です。
unicast | 連想配列の配列。 詳細は以下のユニキャストに関する属性を参照ください。
up | インターフェイスの状態 (on/off) を示す Boolean の値。

Unicast attributes
名前 | 説明
flags | 整数値。
family | 整数値。
address | IPv4 または IPv6 形式の、アドレスを示す文字列。
netmask | IPv4 または IPv6 形式の、ネットマスクを示す文字列。

エラー / 例外

インターフェイス情報を取得できなかった場合は、 E_WARNING が発生します。


システムのロガーへの接続をオープンする

  • ≪ net_get_interfaces
  • pfsockopen ≫
  • PHP Manual
  • ネットワーク 関数
  • システムのロガーへの接続をオープンする

openlog

(PHP 4, PHP 5, PHP 7, PHP 8)

openlog — システムのロガーへの接続をオープンする

説明

openlog(string $prefix, int $flags, int $facility): true

openlog() は、プログラムによるシステムロガーへの接続をオープンします。

openlog() の使用は必須ではありません。この関数は、 必要に応じて syslog() により自動的に呼び出されます。 この場合、prefix のデフォルト値は false となります。

パラメータ

prefix

文字列 prefix が、各メッセージに追加されます。

flags

flags 引数は、 ログメッセージの生成時に使用されるロギング用オプションを指定します。

openlog() のオプション
定数 | 説明
LOG_CONS | システムロガーにデータが送信される間にエラーが発生した場合、 直接、システムコンソールに書き込まれます。
LOG_NDELAY | 直ちにロガーへの接続をオープンします。
LOG_ODELAY | (デフォルト) 最初のメッセージがロギングされるまで接続のオープンを遅延します。
LOG_PERROR | 標準エラー出力にもログメッセージを出力します。
LOG_PID | 各メッセージに PID も含めます。
これらのオプションを一つまたは複数設定することが可能です。 複数のオプションを使用する場合、その論理和を指定します。 つまり、直ちに接続をオープンし、コンソールに書き込み、 各メッセージに PID を含めるには、 LOG_CONS | LOG_NDELAY | LOG_PID とします。

facility

引数 facility には、 ロギングを行う際のメッセージ型を指定します。これにより、 (使用するシステムの syslog の設定に関して) 異なった facility を有するメッセージをどのように処理するかを指定できるようになります。

openlog() の機能
定数 | 説明
LOG_AUTH | セキュリティ/認証用メッセージ (定数 LOG_AUTHPRIV が定義されているシステムでは、代わりにそれを使用してください)
LOG_AUTHPRIV | セキュリティ/認証 メッセージ (プライベート)
LOG_CRON | クロックデーモン (cron や at)
LOG_DAEMON | 他のシステムデーモン
LOG_KERN | カーネルメッセージ
LOG_LOCAL0 ... LOG_LOCAL7 | ローカルでの使用のために確保されているもので、Windows では使用できません
LOG_LPR | ラインプリンタサブシステム
LOG_MAIL | メールサブシステム
LOG_NEWS | USENET ニュース サブシステム
LOG_SYSLOG | syslogd で内部的に生成されたメッセージ
LOG_USER | 一般的なユーザーレベルのメッセージ
LOG_UUCP | UUCP サブシステム

注意:

Windows 環境で使用できるのは LOG_USER だけです。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。

参考

  • syslog() - システムログのメッセージを生成する
  • closelog() - システムログへの接続を閉じる


持続的な Internet または Unix ドメインソケット接続をオープンする

  • ≪ openlog
  • setcookie ≫
  • PHP Manual
  • ネットワーク 関数
  • 持続的な Internet または Unix ドメインソケット接続をオープンする

pfsockopen

(PHP 4, PHP 5, PHP 7, PHP 8)

pfsockopen — 持続的な Internet または Unix ドメインソケット接続をオープンする

説明

pfsockopen(
string $hostname,
int $port = -1,
int &$error_code = null,
string &$error_message = null,
?float $timeout = null
): resource|false

この関数は、fsockopen() と全く同様に動作します。 ただし、この関数による接続はリクエストが終了した後でも閉じられないという違いがあります。 この関数は、fsockopen() の持続的接続版です。

パラメータ

パラメータについての情報は fsockopen() のドキュメントを参照ください。

戻り値

pfsockopen() は、 他のファイル関数 (fgets(), fgetss(), fwrite(), fclose(), feof()) で使うファイルポインタを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | timeout は、nullable になりました。

参考

  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする


クッキーを送信する

  • ≪ pfsockopen
  • setrawcookie ≫
  • PHP Manual
  • ネットワーク 関数
  • クッキーを送信する

setcookie

(PHP 4, PHP 5, PHP 7, PHP 8)

setcookie — クッキーを送信する

説明

setcookie(
string $name,
string $value = "",
int $expires_or_options = 0,
string $path = "",
string $domain = "",
bool $secure = false,
bool $httponly = false
): bool

PHP 7.3.0 以降で使える代替のシグネチャ(名前付き引数をサポートしていません):

setcookie(string $name, string $value = "", array $options = []): bool

setcookie() は、その他のヘッダ情報と共に 送信するクッキーを定義します。 ほかのヘッダ情報と同様に、 クッキーは、スクリプトによる他のあらゆる出力よりも前に 送信される必要があります（これはHTTPプロトコルの制約です）。 <html> や <head> タグはもちろん 空白も含め、あらゆる出力よりも前にこの関数をコールするようにしなければなりません。

一度クッキーが送信されると、次のページのロードからは $_COOKIE 配列によってクッキーにアクセスできます。 クッキーの値は $_REQUEST 配列からもアクセスできるかもしれません。

パラメータ

setcookie() の各パラメータがどのように作用するのかを知るには » RFC 6265 を参照ください。

name

クッキーの名前。

value

クッキーの値。この値はクライアントのコンピュータに保存されますので、 重要な情報は格納しないでください。 name が 'cookiename' だとすると、 その値は $_COOKIE['cookiename'] で取得することができます。

expires_or_options

クッキーの有効期限。これは Unix タイムスタンプなので Epoch（1970 年 1 月 1 日）からの経過秒数となります。 この値を設定するひとつの方法として、 time() が返した値に、 期限としたい必要な秒数を加算することが考えられます。 たとえば、time()+60*60*24*30 はクッキーの有効期限を 30 日後にセットします。 別のやり方として、mktime() を使うことも考えられます。 この値に 0 を設定したり省略したりした場合は、 クッキーはセッションの最後(つまりブラウザを閉じるとき) が有効期限となります。

注意:

expires_or_options パラメータには、Wdy, DD-Mon-YYYY HH:MM:SS GMT といった形式ではなく Unix タイムスタンプを渡していることにお気づきでしょうか。 これは、PHP の内部で自動的に変換を行っているからです。

path

サーバー上での、クッキーを有効としたいパス '/' をセットすると、クッキーは domain 配下の全てで有効となります。 '/foo/' をセットすると、クッキーは /foo/ ディレクトリとそのサブディレクトリ配下 (例えば /foo/bar/) で有効となります。 デフォルト値は、クッキーがセットされたときのカレントディレクトリです。

domain

クッキーが有効な (サブ) ドメイン。これを 'www.example.com' などのサブドメインに設定すると、 www サブドメインおよびそれ自身のすべてのサブドメイン (w2.www.example.com など) でクッキーが使えるようになります。 サブドメインを含むドメイン全体でクッキーを有効にしたければ、そのドメイン自体 (この場合は 'example.com') を設定します。

古いブラウザの中には、非推奨になった » RFC 2109 を実装しているものが未だに残っているかもしれません。 そのようなブラウザでは、すべてのサブドメインにマッチさせるためには先頭に . が必要となります。

secure

クライアントからのセキュアな HTTPS 接続の場合にのみクッキーが送信されるようにします。 true を設定すると、セキュアな接続が存在する場合にのみクッキーを設定します。 サーバー側では、このようにセキュアな接続の場合にのみクッキーを送信するという処理は プログラマの責任で行うことになります (たとえば $_SERVER["HTTPS"] の内容を使用します)。

httponly

true を設定すると、HTTP を通してのみクッキーにアクセスできるようになります。 つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。 この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせる (が、すべてのブラウザがこの設定をサポートしているというわけではありません) と言われていますが、これはしばしば議論の対象となります。 true あるいは false で指定します。

options

expires, path, domain, secure, httponly および samesite のうちから、任意のキーを設定可能な連想配列(array)です。 これら以外のキーが存在する場合、E_WARNING レベルの警告が発生します。 値については、キーと同じ名前のパラメーターで説明した意味と同じです。 samesite 要素の値は、 None, Lax または Strict です。 上記で許されているオプションのうち、与えられなかったものについては、 デフォルト値は明示的にパラメータを与えた場合のデフォルト値と同じです。 samesite 要素が省略された場合は、SameSite クッキー属性は設定されません。

注意:

上のリストにないキーをクッキーの属性に設定する場合、 header() を使います。

戻り値

もしもこの関数をコールする前に何らかの出力がある場合には、 setcookie() は失敗し false を返します。 setcookie() が正常に実行されると、true を返します。 この関数では、ユーザーがクッキーを受け入れたかどうかを判断することはできません。

変更履歴

バージョン | 説明
8.2.0 | Cookie の日付フォーマットが 'D, d M Y H:i:s \G\M\T' になりました。 これより前のバージョンでは 'D, d-M-Y H:i:s T' でした。
7.3.0 | options 配列をサポートする追加のシグネチャが追加されました。 このシグネチャは、SameSite クッキー属性の設定もサポートしています。

例

以下はクッキーを送信する例です。

例1 setcookie() での送信の例

<?php

$value = 'something from somewhere';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600); /* 有効期限は一時間です */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);

?>

クッキーの value の部分は、クッキーの送信を行う際に自動的に URL エンコードされ、またクッキーを受信した際は、自動的にデコード されてクッキー名と同じ名前の変数に格納されることに注意してください。 この挙動が気に入らない場合、 代わりに setrawcookie() を使ってください。 スクリプト内部で TestCookie の内容を見たい場合は、 以下のいずれかの例を使用します。

<?php
// 個々のクッキーを表示します
echo $_COOKIE["TestCookie"];

// デバッグ／テスト用には、全てのクッキーを見る方法があります。
print_r($_COOKIE);
?>

例2 setcookie() による削除の例

クッキーを削除する場合には、ブラウザの削除機構を起動するために 必ず有効期限を過去に設定する必要があります。 次に、先ほどの例で送信したクッキーを削除する例を示します。

<?php
// 有効期限を一時間前に設定します
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>

例3 setcookie() と配列

クッキー名で配列を記述することにより、クッキーの配列を設定することも可能です。 これにより配列要素と同数のクッキーを設定されますが、 クッキーがスクリプトに受信された際に、 値はクッキー名を有する配列に置きかえられます。

<?php
// クッキーを設定します
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// ページを再読み込みした後に、表示します
if (isset($_COOKIE['cookie'])) {
foreach ($_COOKIE['cookie'] as $name => $value) {
$name = htmlspecialchars($name);
$value = htmlspecialchars($value);
echo "$name : $value <br />\n";
}
}
?>

上の例の出力は以下となります。

three : cookiethree
two : cookietwo
one : cookieone

注意: [ や ] のような区切り文字を Cookie の名前の一部として使ってしまうと、RFC 6265 section 4 違反になります。 しかし、RFC 6265, section 5 によると、 ユーザーエージェントがこうした区切り文字をサポートしていることが想定されています。

注意

注意:

この関数をコールする前でも出力できるように、 スクリプトの全ての出力をサーバー内にバッファリングさせることができます。 そのためには、ob_start() や ob_end_flush() を使用するか、あるいは php.ini やサーバー設定ファイルの output_buffering を使用します。

陥りやすい失敗:

  • クッキーは、クッキーを有効にするために次にページをロードするまで アクセスすることができません。クッキーが正常にセットされたか テストするために、クッキーの有効期限が切れる前に次のページを ロードしてクッキーをチェックしてください。 有効期限は expires_or_options 引数でセットされます。 クッキーの利用についてデバッグするのに良い方法は print_r($_COOKIE); をコールすることです。
  • クッキーは設定されたものと同じパラメータで削除する必要があります。 value が空文字列で、その他の全ての引数が前に setcookie() をコールした時と同じである場合に、指定された名前のクッキーが リモートクライアント上から削除されます。 内部的な動作として、これは値を 'deleted' に変更した上で有効期限を 過去に設定しています。
  • クッキーの値として false を設定すると、クッキーを削除しようとします。 そのため、boolean 値は使用できません。その代わりとして、 false ではなく 0、そして true ではなく 1 を使用します。
  • クッキー名で配列を記述することにより、 クッキーの配列を設定することも可能ですが、複数のクッキー がユーザーのシステム上に保存されることになります。 explode() を使用して ひとつのクッキー上に複数の名前と値をセットすることも 考慮してください。serialize() の使用はセキュリティーホールになり得るため、 この目的のために使用することはお勧めしません。

setcookie() を複数回コールした場合は、コールした順番で実行されます。

参考

  • header() - 生の HTTP ヘッダを送信する
  • setrawcookie() - 値を URL エンコードせずにクッキーを送信する
  • クッキー
  • » RFC 6265
  • » RFC 2109


値を URL エンコードせずにクッキーを送信する

  • ≪ setcookie
  • socket_get_status ≫
  • PHP Manual
  • ネットワーク 関数
  • 値を URL エンコードせずにクッキーを送信する

setrawcookie

(PHP 5, PHP 7, PHP 8)

setrawcookie — 値を URL エンコードせずにクッキーを送信する

説明

setrawcookie(
string $name,
string $value = ?,
int $expires_or_options = 0,
string $path = ?,
string $domain = ?,
bool $secure = false,
bool $httponly = false
): bool

PHP 7.3.0 以降で使える代替のシグネチャ(名前付き引数をサポートしていません):

setrawcookie(string $name, string $value = ?, array $options = []): bool

setrawcookie() は、 ブラウザに送信される際クッキーの値が自動的に URL エンコードされないことを除き、 setcookie() と等価です。

パラメータ

パラメータについての情報は setcookie() のドキュメントを参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | options 配列をサポートする追加のシグネチャが追加されました。 このシグネチャは、SameSite クッキー属性の設定もサポートしています。

参考

  • setcookie() - クッキーを送信する


stream_get_meta_data のエイリアス

  • ≪ setrawcookie
  • socket_set_blocking ≫
  • PHP Manual
  • ネットワーク 関数
  • stream_get_meta_data のエイリアス

socket_get_status

(PHP 4, PHP 5, PHP 7, PHP 8)

socket_get_status — stream_get_meta_data() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_get_meta_data().


stream_set_blocking のエイリアス

  • ≪ socket_get_status
  • socket_set_timeout ≫
  • PHP Manual
  • ネットワーク 関数
  • stream_set_blocking のエイリアス

socket_set_blocking

(PHP 4, PHP 5, PHP 7, PHP 8)

socket_set_blocking — stream_set_blocking() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_set_blocking().


stream_set_timeout のエイリアス

  • ≪ socket_set_blocking
  • syslog ≫
  • PHP Manual
  • ネットワーク 関数
  • stream_set_timeout のエイリアス

socket_set_timeout

(PHP 4, PHP 5, PHP 7, PHP 8)

socket_set_timeout — stream_set_timeout() のエイリアス

説明

この関数は次の関数のエイリアスです。 stream_set_timeout().


システムログのメッセージを生成する

  • ≪ socket_set_timeout
  • RRD ≫
  • PHP Manual
  • ネットワーク 関数
  • システムログのメッセージを生成する

syslog

(PHP 4, PHP 5, PHP 7, PHP 8)

syslog — システムログのメッセージを生成する

説明

syslog(int $priority, string $message): true

syslog() はシステムログが出力するログメッセージを生成します。

ユーザー定義のログハンドラの設定に関する情報については、Unix マニュアルの syslog.conf (5) を参照ください。 syslog の facility と option に関するより詳細な情報は、 Unix マシンの syslog (3) にあります。

パラメータ

priority

priority は、容易さ (facility) とレベル (level) の組み合わせです。以下の値が使用できます。

syslog() の優先順位 (降順)
定数 | 説明
LOG_EMERG | システムは使用不可
LOG_ALERT | アクションを直ちにおこす必要がある
LOG_CRIT | 致命的な条件
LOG_ERR | エラーを発生する条件
LOG_WARNING | 警告を発生する条件
LOG_NOTICE | 通常の動作だが、特徴的な条件
LOG_INFO | 情報を与えるメッセージ
LOG_DEBUG | デバッグ用のメッセージ

message

送信するメッセージ

戻り値

常に true を返します。

例

例1 syslog() の使用例

<?php
// syslogをオープンし、プロセスIDをインクルードし、標準エラー出力にも
// ログを出力します。そして、ユーザー定義のログ記録機構を使用します。
openlog("myScriptLog", LOG_PID | LOG_PERROR, LOG_LOCAL0);

// 何らかのコード

if (authorized_client()) {
// 何かをする
} else {
// クライアントは未認証!
// ログを記録する
$access = date("Y/m/d H:i:s");
syslog(LOG_WARNING, "Unauthorized client: $access {$_SERVER['REMOTE_ADDR']} ({$_SERVER['HTTP_USER_AGENT']})");
}

closelog();
?>

注意

Windows では、syslog サービスはイベントログを使用してエミュレートされます。

注意:

Windows 環境では、openlog() の facility パラメータに LOG_LOCAL0 から LOG_LOCAL7 までを使用することはできません。

参考

  • openlog() - システムのロガーへの接続をオープンする
  • closelog() - システムログへの接続を閉じる
  • syslog.filter INI ディレクティブ(PHP 7.3 以降)


RRDtool

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
    • Procedural PECL/rrd example
    • OOP PECL/rrd example
  • RRD 関数
    • rrd_create — Creates rrd database file
    • rrd_error — Gets latest error message
    • rrd_fetch — Fetch the data for graph as array
    • rrd_first — Gets the timestamp of the first sample from rrd file
    • rrd_graph — Creates image from a data
    • rrd_info — Gets information about rrd file
    • rrd_last — Gets unix timestamp of the last sample
    • rrd_lastupdate — Gets information about last updated data
    • rrd_restore — Restores the RRD file from XML dump
    • rrd_tune — Tunes some RRD database file header options
    • rrd_update — Updates the RRD database
    • rrd_version — Gets information about underlying rrdtool library
    • rrd_xport — Exports the information about RRD database
    • rrdc_disconnect — Close any outstanding connection to rrd caching daemon
  • RRDCreator — RRDCreator クラス
    • RRDCreator::addArchive — Adds RRA - archive of data values for each data source
    • RRDCreator::addDataSource — Adds data source definition for RRD database
    • RRDCreator::__construct — Creates new RRDCreator instance
    • RRDCreator::save — Saves the RRD database to a file
  • RRDGraph — RRDGraph クラス
    • RRDGraph::__construct — Creates new RRDGraph instance
    • RRDGraph::save — Saves the result of query into image
    • RRDGraph::saveVerbose — Saves the RRD database query into image and returns the verbose information about generated graph
    • RRDGraph::setOptions — Sets the options for rrd graph export
  • RRDUpdater — RRDUpdater クラス
    • RRDUpdater::__construct — Creates new RRDUpdater instance
    • RRDUpdater::update — Update the RRD database file


はじめに

The PECL/rrd extension provides bindings to the RRDtool C library. RRDtool is the open source industry standard, high performance data logging and graphing system for time series data.

The RRDtool homepage is » http://www.mrtg.org/rrdtool/.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • RRD
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

You need to install librrd first to be able to use PECL/rrd. Most common option is using of librrd-dev package from your favourite Linux distro. PECL/rrd is tested with librrd 1.4.3, older or newer versions might or might not work for you.

警告

Librrd and hence extension itself aren't mostly thread safe. There are many global and shared states in librrd. It can be dangerous use this extension in multi threaded environments like Apache2 mpm worker. If there are many parallel requests, one request can change some global librrd state of other runnig requests.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/rrd.


  • ≪ インストール手順
  • Procedural PECL/rrd example ≫
  • PHP Manual
  • RRD
  • 例

例

目次

  • Procedural PECL/rrd example
  • OOP PECL/rrd example


Procedural PECL/rrd example

例1 Procedural usage of rrd

<?php
$rrdFile = dirname(__FILE__) . "/speed.rrd";

//create rrd file
rrd_create($rrdFile,
array(
"--start",920804400,
"DS:speed:COUNTER:600:U:U",
"RRA:AVERAGE:0.5:1:24",
"RRA:AVERAGE:0.5:6:10"
)
);

//update rrd file
rrd_update($rrdFile,
array(
"920804700:12345",
"920805000:12357"
)
);

//graph output
rrd_graph(dirname(__FILE__) . "/speed.png",
array(
"--start", "920804400",
"--end", "920808000",
"--vertical-label", "m/s",
"DEF:myspeed=$rrdFile:speed:AVERAGE",
"CDEF:realspeed=myspeed,1000,*",
"LINE2:realspeed#FF0000"
)
);
?>


OOP PECL/rrd example

例1 OO usage of rrd

<?php
$rrdFile = dirname(__FILE__) . "/speed.rrd";
$outputPngFile = dirname(__FILE__) . "/speed.png";

$creator = new RRDCreator($rrdFile, "now -10d", 500);
$creator->addDataSource("speed:COUNTER:600:U:U");
$creator->addArchive("AVERAGE:0.5:1:24");
$creator->addArchive("AVERAGE:0.5:6:10");
$creator->save();

$updater = new RRDUpdater($rrdFile);
$updater->update(array("speed" => "12345"), "920804700");
$updater->update(array("speed" => "12357"), "920805000");

$graphObj = new RRDGraph($outputPngFile);
$graphObj->setOptions(
array(
"--start" => "920804400",
"--end" => 920808000,
"--vertical-label" => "m/s",
"DEF:myspeed=$rrdFile:speed:AVERAGE",
"CDEF:realspeed=myspeed,1000,*",
"LINE2:realspeed#FF0000"
)
);
$graphObj->save();
?>


RRD 関数

目次

  • rrd_create — Creates rrd database file
  • rrd_error — Gets latest error message
  • rrd_fetch — Fetch the data for graph as array
  • rrd_first — Gets the timestamp of the first sample from rrd file
  • rrd_graph — Creates image from a data
  • rrd_info — Gets information about rrd file
  • rrd_last — Gets unix timestamp of the last sample
  • rrd_lastupdate — Gets information about last updated data
  • rrd_restore — Restores the RRD file from XML dump
  • rrd_tune — Tunes some RRD database file header options
  • rrd_update — Updates the RRD database
  • rrd_version — Gets information about underlying rrdtool library
  • rrd_xport — Exports the information about RRD database
  • rrdc_disconnect — Close any outstanding connection to rrd caching daemon


Creates rrd database file

  • ≪ RRD 関数
  • rrd_error ≫
  • PHP Manual
  • RRD 関数
  • Creates rrd database file

rrd_create

(PECL rrd >= 0.9.0)

rrd_create — Creates rrd database file

説明

rrd_create(string $filename, array $options): bool

Creates the rdd database file.

パラメータ

filename

Filename for newly created rrd file.

options

Options for rrd create - list of strings. See man page of rrd create for whole list of options.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Gets latest error message

  • ≪ rrd_create
  • rrd_fetch ≫
  • PHP Manual
  • RRD 関数
  • Gets latest error message

rrd_error

(PECL rrd >= 0.9.0)

rrd_error — Gets latest error message

説明

rrd_error(): string

Returns latest global rrd error message.

パラメータ

この関数にはパラメータはありません。

戻り値

Latest error message.


Fetch the data for graph as array

  • ≪ rrd_error
  • rrd_first ≫
  • PHP Manual
  • RRD 関数
  • Fetch the data for graph as array

rrd_fetch

(PECL rrd >= 0.9.0)

rrd_fetch — Fetch the data for graph as array

説明

rrd_fetch(string $filename, array $options): array

Gets data for graph output from RRD database file as array. This function has same result as rrd_graph(), but fetched data are returned as array, no image file is created.

パラメータ

filename

RRD database file name.

options

Array of options for resolution specification.

戻り値

Returns information about retrieved graph data.


Gets the timestamp of the first sample from rrd file

  • ≪ rrd_fetch
  • rrd_graph ≫
  • PHP Manual
  • RRD 関数
  • Gets the timestamp of the first sample from rrd file

rrd_first

(PECL rrd >= 0.9.0)

rrd_first — Gets the timestamp of the first sample from rrd file

説明

rrd_first(string $file, int $raaindex = 0): int

Returns the first data sample from the specified RRA of the RRD file.

パラメータ

file

RRD database file name.

raaindex

The index number of the RRA that is to be examined. Default value is 0.

戻り値

Integer number of unix timestamp,失敗した場合に false を返します.


Creates image from a data

  • ≪ rrd_first
  • rrd_info ≫
  • PHP Manual
  • RRD 関数
  • Creates image from a data

rrd_graph

(PECL rrd >= 0.9.0)

rrd_graph — Creates image from a data

説明

rrd_graph(string $filename, array $options): array

Creates image for a particular data from RRD file.

パラメータ

filename

The filename to output the graph to. This will generally end in either .png, .svg or .eps, depending on the format you want to output.

options

Options for generating image. See man page of rrd graph for all possible options. All options (data definitions, variable definitions, etc.) are allowed.

戻り値

Array with information about generated image is returned,失敗した場合に false を返します.


Gets information about rrd file

  • ≪ rrd_graph
  • rrd_last ≫
  • PHP Manual
  • RRD 関数
  • Gets information about rrd file

rrd_info

(PECL rrd >= 0.9.0)

rrd_info — Gets information about rrd file

説明

rrd_info(string $filename): array

Returns information about particular RRD database file.

パラメータ

file

RRD database file name.

戻り値

Array with information about requested RRD file,失敗した場合に false を返します.


Gets unix timestamp of the last sample

  • ≪ rrd_info
  • rrd_lastupdate ≫
  • PHP Manual
  • RRD 関数
  • Gets unix timestamp of the last sample

rrd_last

(PECL rrd >= 0.9.0)

rrd_last — Gets unix timestamp of the last sample

説明

rrd_last(string $filename): int

Returns the UNIX timestamp of the most recent update of the RRD database.

パラメータ

filename

RRD database file name.

戻り値

Integer as unix timestamp of the most recent data from the RRD database.


Gets information about last updated data

  • ≪ rrd_last
  • rrd_restore ≫
  • PHP Manual
  • RRD 関数
  • Gets information about last updated data

rrd_lastupdate

(PECL rrd >= 0.9.0)

rrd_lastupdate — Gets information about last updated data

説明

rrd_lastupdate(string $filename): array

Gets array of the UNIX timestamp and the values stored for each date in the most recent update of the RRD database file.

パラメータ

file

RRD database file name.

戻り値

Array of information about last update,失敗した場合に false を返します.


Restores the RRD file from XML dump

  • ≪ rrd_lastupdate
  • rrd_tune ≫
  • PHP Manual
  • RRD 関数
  • Restores the RRD file from XML dump

rrd_restore

(PECL rrd >= 0.9.0)

rrd_restore — Restores the RRD file from XML dump

説明

rrd_restore(string $xml_file, string $rrd_file, array $options = ?): bool

Restores the RRD file from the XML dump.

パラメータ

xml_file

XML filename with the dump of the original RRD database file.

rrd_file

Restored RRD database file name.

options

Array of options for restoring. See man page for rrd restore.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Tunes some RRD database file header options

  • ≪ rrd_restore
  • rrd_update ≫
  • PHP Manual
  • RRD 関数
  • Tunes some RRD database file header options

rrd_tune

(PECL rrd >= 0.9.0)

rrd_tune — Tunes some RRD database file header options

説明

rrd_tune(string $filename, array $options): bool

Change some options in the RRD dabase header file. E.g. renames the source for the data etc.

パラメータ

filename

RRD database file name.

options

Options with RRD database file properties which will be changed. See rrd tune man page for details.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Updates the RRD database

  • ≪ rrd_tune
  • rrd_version ≫
  • PHP Manual
  • RRD 関数
  • Updates the RRD database

rrd_update

(PECL rrd >= 0.9.0)

rrd_update — Updates the RRD database

説明

rrd_update(string $filename, array $options): bool

Updates the RRD database file. The input data is time interpolated according to the properties of the RRD database file.

パラメータ

filename

RRD database file name. This database will be updated.

options

Options for updating the RRD database. This is list of strings. See man page of rrd update for whole list of options.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Gets information about underlying rrdtool library

  • ≪ rrd_update
  • rrd_xport ≫
  • PHP Manual
  • RRD 関数
  • Gets information about underlying rrdtool library

rrd_version

(PECL rrd >= 1.0.0)

rrd_version — Gets information about underlying rrdtool library

説明

rrd_version(): string

Returns information about underlying rrdtool library.

パラメータ

この関数にはパラメータはありません。

戻り値

String with rrdtool version number e.g. "1.4.3".


Exports the information about RRD database

  • ≪ rrd_version
  • rrdc_disconnect ≫
  • PHP Manual
  • RRD 関数
  • Exports the information about RRD database

rrd_xport

(PECL rrd >= 0.9.0)

rrd_xport — Exports the information about RRD database

説明

rrd_xport(array $options): array

Exports the information about RRD database file. This data can be converted to XML file via user space PHP script and then restored back as RRD database file.

パラメータ

options

Array of options for the export, see rrd xport man page.

戻り値

Array with information about RRD database file,失敗した場合に false を返します.


Close any outstanding connection to rrd caching daemon

  • ≪ rrd_xport
  • RRDCreator ≫
  • PHP Manual
  • RRD 関数
  • Close any outstanding connection to rrd caching daemon

rrdc_disconnect

(PECL rrd >= 1.1.2)

rrdc_disconnect — Close any outstanding connection to rrd caching daemon

説明

rrdc_disconnect(): void

Close any outstanding connection to rrd caching daemon.

This function is automatically called when the whole PHP process is terminated. It depends on used SAPI. For example, it's called automatically at the end of command line script.

It's up user whether he wants to call this function at the end of every request or otherwise.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


RRDCreator クラス

(PECL rrd >= 0.9.0)

はじめに

RRD データベースファイルの生成クラス

クラス概要

class RRDCreator {
/* メソッド */
public __construct(string $path, string $startTime = ?, int $step = 0)
public addArchive(string $description): void
public addDataSource(string $description): void
public save(): bool
}

目次

  • RRDCreator::addArchive — Adds RRA - archive of data values for each data source
  • RRDCreator::addDataSource — Adds data source definition for RRD database
  • RRDCreator::__construct — Creates new RRDCreator instance
  • RRDCreator::save — Saves the RRD database to a file


Adds RRA - archive of data values for each data source

  • ≪ RRDCreator
  • RRDCreator::addDataSource ≫
  • PHP Manual
  • RRDCreator
  • Adds RRA - archive of data values for each data source

RRDCreator::addArchive

(PECL rrd >= 0.9.0)

RRDCreator::addArchive — Adds RRA - archive of data values for each data source

説明

public RRDCreator::addArchive(string $description): void

Adds RRA definition by description of archive. Archive consists of a number of data values or statistics for each of the defined data-sources (DS). Data sources are defined by method RRDCreator::addDataSource(). You need call this method for each requested archive.

パラメータ

description

Definition of archive - RRA. This has same format as RRA definition in rrd create command. See man page of rrd create for more details.

戻り値

値を返しません。


Adds data source definition for RRD database

  • ≪ RRDCreator::addArchive
  • RRDCreator::__construct ≫
  • PHP Manual
  • RRDCreator
  • Adds data source definition for RRD database

RRDCreator::addDataSource

(PECL rrd >= 0.9.0)

RRDCreator::addDataSource — Adds data source definition for RRD database

説明

public RRDCreator::addDataSource(string $description): void

RRD can accept input from several data sources (DS), e.g incoming and outgoing traffic. This method adds data source by description. You need call this method for each data source.

パラメータ

description

Definition of data source - DS. This has same format as DS definition in rrd create command. See man page of rrd create for more details.

戻り値

値を返しません。


Creates new RRDCreator instance

  • ≪ RRDCreator::addDataSource
  • RRDCreator::save ≫
  • PHP Manual
  • RRDCreator
  • Creates new RRDCreator instance

RRDCreator::__construct

(PECL rrd >= 0.9.0)

RRDCreator::__construct — Creates new RRDCreator instance

説明

public RRDCreator::__construct(string $path, string $startTime = ?, int $step = 0)

Creates new RRDCreator instance.

パラメータ

path

Path for newly created RRD database file.

startTime

Time for the first value in RRD database. Parameter supports all formats which are supported by rrd create call.

intstep

Base interval in seconds with which data will be fed into the RRD database.


Saves the RRD database to a file

  • ≪ RRDCreator::__construct
  • RRDGraph ≫
  • PHP Manual
  • RRDCreator
  • Saves the RRD database to a file

RRDCreator::save

(PECL rrd >= 0.9.0)

RRDCreator::save — Saves the RRD database to a file

説明

public RRDCreator::save(): bool

Saves the RRD database into file, which name is defined by RRDCreator::__construct().

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


RRDGraph クラス

(PECL rrd >= 0.9.0)

はじめに

RRD データベースから画像ファイルにデータをエクスポートするクラス

クラス概要

class RRDGraph {
/* メソッド */
public __construct(string $path)
public save(): array
public saveVerbose(): array
public setOptions(array $options): void
}

目次

  • RRDGraph::__construct — Creates new RRDGraph instance
  • RRDGraph::save — Saves the result of query into image
  • RRDGraph::saveVerbose — Saves the RRD database query into image and returns the verbose information about generated graph
  • RRDGraph::setOptions — Sets the options for rrd graph export


Creates new RRDGraph instance

  • ≪ RRDGraph
  • RRDGraph::save ≫
  • PHP Manual
  • RRDGraph
  • Creates new RRDGraph instance

RRDGraph::__construct

(PECL rrd >= 0.9.0)

RRDGraph::__construct — Creates new RRDGraph instance

説明

public RRDGraph::__construct(string $path)

Creates new RRDGraph instance. This instance is responsible for rendering the result of RRD database query into image.

パラメータ

path

Full path for the newly created image.


Saves the result of query into image

  • ≪ RRDGraph::__construct
  • RRDGraph::saveVerbose ≫
  • PHP Manual
  • RRDGraph
  • Saves the result of query into image

RRDGraph::save

(PECL rrd >= 0.9.0)

RRDGraph::save — Saves the result of query into image

説明

public RRDGraph::save(): array

Saves the result of RRD database query into image defined by RRDGraph::__construct().

パラメータ

この関数にはパラメータはありません。

戻り値

Returns array with information about generated image,失敗した場合に false を返します.


Saves the RRD database query into image and returns the verbose information about generated graph

  • ≪ RRDGraph::save
  • RRDGraph::setOptions ≫
  • PHP Manual
  • RRDGraph
  • Saves the RRD database query into image and returns the verbose information about generated graph

RRDGraph::saveVerbose

(PECL rrd >= 0.9.0)

RRDGraph::saveVerbose — Saves the RRD database query into image and returns the verbose information about generated graph

説明

public RRDGraph::saveVerbose(): array

Saves the RRD database query into image file defined by method RRDGraph::__construct() and returns the verbose information about generated graph, if "-" is used as image filename, image data are also returned in result array.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns array with detailed information about generated image,失敗した場合に false を返します.


Sets the options for rrd graph export

  • ≪ RRDGraph::saveVerbose
  • RRDUpdater ≫
  • PHP Manual
  • RRDGraph
  • Sets the options for rrd graph export

RRDGraph::setOptions

(PECL rrd >= 0.9.0)

RRDGraph::setOptions — Sets the options for rrd graph export

説明

public RRDGraph::setOptions(array $options): void

パラメータ

options

List of options for the image generation from the RRD database file. It can be list of strings or list of strings with keys for better readability. Read the rrd graph man pages for list of available options.

戻り値

値を返しません。

例

例1 RRDGraph::setOptions() example

<?php
$graphObj->setOptions(array(
"--start" => "920804400",
"--end" => 920808000,
"--vertical-label" => "m/s",
"DEF:myspeed=$rrdFile:speed:AVERAGE",
"CDEF:realspeed=myspeed,1000,*",
"LINE2:realspeed#FF0000"
));
?>

例2 Set multiple color options

<?php
$graphObj->setOptions(array(
"--start" => "920804400",
"--end" => 920808000,
"--vertical-label" => "m/s",
"--color=BACK#00000000",
"--color=GRID#00000000",
"--color=MGRID#00000000",
"DEF:myspeed=$rrdFile:speed:AVERAGE",
"CDEF:realspeed=myspeed,1000,*",
"LINE2:realspeed#FF0000"
));
?>

Don't use key value syntax for same rrd option. It looks more readable, but it doesn't work.

<?php
$graphObj->setOptions(array(
"--color" => "BACK#00000000",
"--color" => "GRID#00000000",
"--color" => "MGRID#00000000"
));
?>

In nature of php it's same as

<?php
$graphObj->setOptions(array(
"--color" => "MGRID#00000000"
));
?>


RRDUpdater クラス

(PECL rrd >= 0.9.0)

はじめに

RDD データベースファイルを更新するクラス

クラス概要

class RRDUpdater {
/* メソッド */
public __construct(string $path)
public update(array $values, string $time = time() ): bool
}

目次

  • RRDUpdater::__construct — Creates new RRDUpdater instance
  • RRDUpdater::update — Update the RRD database file


Creates new RRDUpdater instance

  • ≪ RRDUpdater
  • RRDUpdater::update ≫
  • PHP Manual
  • RRDUpdater
  • Creates new RRDUpdater instance

RRDUpdater::__construct

(PECL rrd >= 0.9.0)

RRDUpdater::__construct — Creates new RRDUpdater instance

説明

public RRDUpdater::__construct(string $path)

Creates new RRDUpdater instance. This instance is responsible for updating the RRD database file.

パラメータ

path

Filesystem path for RRD database file, which will be updated.


Update the RRD database file

  • ≪ RRDUpdater::__construct
  • ScoutAPM ≫
  • PHP Manual
  • RRDUpdater
  • Update the RRD database file

RRDUpdater::update

(PECL rrd >= 0.9.0)

RRDUpdater::update — Update the RRD database file

説明

public RRDUpdater::update(array $values, string $time = time() ): bool

Updates the RRD file defined via RRDUpdater::__construct(). The file is updated with a specific values.

パラメータ

values

Data for update. Key is data source name.

time

Time value for updating the RRD with a particular data. Default value is current time.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

Throws a Exception on error.

例

例1 RRDUpdater::update() examples

<?php
$updator = new RRDUpdater("speed.rrd");
//updates the data source "speed" with value "12411"
//for time defined by timestamp "920807700"
$updator->update(array("speed" => "12411"), "920807700");
?>


ScoutAPM

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Scoutapm 関数
    • scoutapm_get_calls — 収集する処理が呼ばれた情報の一覧を返す
    • scoutapm_list_instrumented_functions — scoutapm がデータを収集する関数の一覧


はじめに

注意: この拡張モジュールは Windows 環境では利用できません。

ScoutAPM 拡張モジュールは、土台となる PHP のユーザーランドのライブラリを使うだけで、 アプリケーションをモニタリングするための追加機能を提供します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • ScoutAPM
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

  • PHP >= 7.1.0
  • Windows は現在サポートされていません。


インストール手順

この拡張モジュールは PECL で利用可能です。以下を実行してください:

$ sudo pecl install scoutapm
php.ini に Scout の共有ライブラリを追加する必要があるかもしれません。 たとえば、以下のようになります:
extension=scoutapm.so


Scoutapm 関数

目次

  • scoutapm_get_calls — 収集する処理が呼ばれた情報の一覧を返す
  • scoutapm_list_instrumented_functions — scoutapm がデータを収集する関数の一覧


収集する処理が呼ばれた情報の一覧を返す

  • ≪ Scoutapm 関数
  • scoutapm_list_instrumented_functions ≫
  • PHP Manual
  • Scoutapm 関数
  • 収集する処理が呼ばれた情報の一覧を返す

scoutapm_get_calls

(PECL scoutapm >= 1.0.0)

scoutapm_get_calls — 収集する処理が呼ばれた情報の一覧を返す

説明

scoutapm_get_calls(): array

scoutapm_get_calls() が最後に呼び出された後から行われた、 収集対象の関数が呼ばれた全ての情報のリストを返します。 この関数が呼ばれるごとに、リストはクリアされます。

パラメータ

この関数にはパラメータはありません。

戻り値

scoutapm_get_calls() は、 収集対象の関数に対する、全ての記録された呼び出しのリストを配列として返します。

例

例1 収集された呼び出しを取得する

<?php

file_get_contents('a.txt');
file_get_contents('b.txt');

print_r(scoutapm_get_calls());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [function] => file_get_contents
            [entered] => 1576839727.7934
            [exited] => 1576839727.7935
            [time_taken] => 2.7894973754883E-5
            [argv] => Array
                (
                    [0] => a.txt
                )

        )

    [1] => Array
        (
            [function] => file_get_contents
            [entered] => 1576839727.7935
            [exited] => 1576839727.7935
            [time_taken] => 7.8678131103516E-6
            [argv] => Array
                (
                    [0] => b.txt
                )

        )

)


scoutapm がデータを収集する関数の一覧

  • ≪ scoutapm_get_calls
  • SNMP ≫
  • PHP Manual
  • Scoutapm 関数
  • scoutapm がデータを収集する関数の一覧

scoutapm_list_instrumented_functions

(PECL scoutapm >= 1.0.2)

scoutapm_list_instrumented_functions — scoutapm がデータを収集する関数の一覧

説明

scoutapm_list_instrumented_functions(): array

この拡張モジュールがデータを収集する関数の一覧を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

scoutapm_list_instrumented_functions() は 拡張モジュールが現在のインストールで収集できる、 全ての関数のリストを含んだ配列を返します。

例

例1 scoutapm が情報を収集する関数の一覧を取得する

<?php
print_r(scoutapm_list_instrumented_functions());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => file_get_contents
    [1] => file_put_contents
    [2] => fopen
    [3] => fread
    [4] => fwrite
    [5] => pdo->exec
    [6] => pdo->query
    [7] => pdo->prepare
    [8] => pdostatement->execute
)


SNMP

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • SNMP 関数
    • snmp_get_quick_print — NET-SNMP ライブラリの quick_print の現在の設定値を取得する
    • snmp_get_valueretrieval — SNMP の値が返される方法を返す
    • snmp_read_mib — アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする
    • snmp_set_enum_print — すべての enum を、実際の整数値ではなく enum 値とともに返す
    • snmp_set_oid_numeric_print — snmp_set_oid_output_format のエイリアス
    • snmp_set_oid_output_format — OID の出力形式を設定する
    • snmp_set_quick_print — NET-SNMP ライブラリで enable の値を設定する
    • snmp_set_valueretrieval — SNMP の値が返される方法を設定する
    • snmp2_get — SNMP オブジェクトを取得する
    • snmp2_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmp2_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
    • snmp2_set — SNMP オブジェクトの値を設定する
    • snmp2_walk — すべての SNMP オブジェクトをエージェントから取得する
    • snmp3_get — SNMP オブジェクトを取得する
    • snmp3_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmp3_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
    • snmp3_set — SNMP オブジェクトの値を設定する
    • snmp3_walk — すべての SNMP オブジェクトをエージェントから取得する
    • snmpget — SNMP オブジェクトを取得する
    • snmpgetnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmprealwalk — 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す
    • snmpset — SNMP オブジェクトの値を設定する
    • snmpwalk — エージェントから全ての SNMP オブジェクトを取得する
    • snmpwalkoid — ネットワークエンティティに関する情報ツリーを検索する
  • SNMP — SNMP クラス
    • SNMP::close — SNMP セッションを閉じる
    • SNMP::__construct — リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する
    • SNMP::get — SNMP オブジェクトを取得する
    • SNMP::getErrno — 直近のエラーコードを取得する
    • SNMP::getError — 直近のエラーメッセージを取得する
    • SNMP::getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • SNMP::set — SNMP オブジェクトの値を設定する
    • SNMP::setSecurity — セキュリティ関連の SNMPv3 セッションパラメータを設定する
    • SNMP::walk — SNMP オブジェクトのサブツリーを取得する
  • SNMPException — SNMPException クラス


はじめに

SNMP 拡張モジュールは非常にシンプルで使い勝手の良いツール群です。 Simple Network Managment Protocol を使ってリモートデバイスを管理することができます。

これは Net-SNMP ライブラリのラッパーなので、 基本的な考え方はこのライブラリと同じです。また、Net-SNMP の設定ファイルや環境変数によって PHP の関数の挙動も変わります。

Net-SNMP についての詳細な情報は » http://www.net-snmp.org/ にあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SNMP
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

SNMP 関数を使用するためには、» Net-SNMP パッケージをインストールする必要があります。 SNMPv3 関数が使えるのは、» OpenSSL パッケージもインストールされている場合のみです。

Unix 環境にインストールするためには Net-SNMP バージョン 5.3 以降、そして Windows 環境にインストールするためには Net-SNMP バージョン 5.4 以降が必要となります。


インストール手順

Windows 版の » Net-SNMP には、 SNMP サポート用ファイルがが含まれています。 サポート用ファイルは mibs ディレクトリにあります。 このディレクトリを、Windows の環境変数 MIBDIRS に追加しなければいけません。 環境変数の値は、mibs ディレクトリへのフルパス (例: c:\usr\mibs) となります。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

snmp_set_oid_output_format() 用
SNMP_OID_OUTPUT_SUFFIX (int)
SNMP_OID_OUTPUT_MODULE (int)
SNMP_OID_OUTPUT_FULL (int)
SNMP_OID_OUTPUT_NUMERIC (int)
SNMP_OID_OUTPUT_UCD (int)
SNMP_OID_OUTPUT_NONE (int)
snmp_set_valueretrieval() 用
SNMP_VALUE_LIBRARY (int)
SNMP_VALUE_PLAIN (int)
SNMP_VALUE_OBJECT (int)
snmp_set_valueretrieval() で SNMP_VALUE_OBJECT を使った場合に返される SNMP の型
SNMP_BIT_STR (int)
SNMP_OCTET_STR (int)
SNMP_OPAQUE (int)
SNMP_NULL (int)
SNMP_OBJECT_ID (int)
SNMP_IPADDRESS (int)
SNMP_COUNTER (int)
SNMP_UNSIGNED (int)
SNMP_TIMETICKS (int)
SNMP_UINTEGER (int)
SNMP_INTEGER (int)
SNMP_COUNTER64 (int)


SNMP 関数

目次

  • snmp_get_quick_print — NET-SNMP ライブラリの quick_print の現在の設定値を取得する
  • snmp_get_valueretrieval — SNMP の値が返される方法を返す
  • snmp_read_mib — アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする
  • snmp_set_enum_print — すべての enum を、実際の整数値ではなく enum 値とともに返す
  • snmp_set_oid_numeric_print — snmp_set_oid_output_format のエイリアス
  • snmp_set_oid_output_format — OID の出力形式を設定する
  • snmp_set_quick_print — NET-SNMP ライブラリで enable の値を設定する
  • snmp_set_valueretrieval — SNMP の値が返される方法を設定する
  • snmp2_get — SNMP オブジェクトを取得する
  • snmp2_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • snmp2_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
  • snmp2_set — SNMP オブジェクトの値を設定する
  • snmp2_walk — すべての SNMP オブジェクトをエージェントから取得する
  • snmp3_get — SNMP オブジェクトを取得する
  • snmp3_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • snmp3_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す
  • snmp3_set — SNMP オブジェクトの値を設定する
  • snmp3_walk — すべての SNMP オブジェクトをエージェントから取得する
  • snmpget — SNMP オブジェクトを取得する
  • snmpgetnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • snmprealwalk — 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す
  • snmpset — SNMP オブジェクトの値を設定する
  • snmpwalk — エージェントから全ての SNMP オブジェクトを取得する
  • snmpwalkoid — ネットワークエンティティに関する情報ツリーを検索する


NET-SNMP ライブラリの quick_print の現在の設定値を取得する

  • ≪ SNMP 関数
  • snmp_get_valueretrieval ≫
  • PHP Manual
  • SNMP 関数
  • NET-SNMP ライブラリの quick_print の現在の設定値を取得する

snmp_get_quick_print

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp_get_quick_print — NET-SNMP ライブラリの quick_print の現在の設定値を取得する

説明

snmp_get_quick_print(): bool

NET-SNMP ライブラリに保持された quick_print の現在の値を返します。 デフォルトでは、quick_print はオフです。

パラメータ

この関数にはパラメータはありません。

戻り値

quick_print がオンの場合に true、それ以外の場合に false を返します。

例

例1 snmp_get_quick_print() の例

<?php
$quickprint = snmp_get_quick_print();
?>

参考

  • quick_print の役割に関する詳細な説明は、 snmp_set_quick_print() - NET-SNMP ライブラリで enable の値を設定する を参照ください。


SNMP の値が返される方法を返す

  • ≪ snmp_get_quick_print
  • snmp_read_mib ≫
  • PHP Manual
  • SNMP 関数
  • SNMP の値が返される方法を返す

snmp_get_valueretrieval

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

snmp_get_valueretrieval — SNMP の値が返される方法を返す

説明

snmp_get_valueretrieval(): int

パラメータ

この関数にはパラメータはありません。

戻り値

OR でつないだ定数 ( SNMP_VALUE_LIBRARY あるいは SNMP_VALUE_PLAIN) に、場合によって SNMP_VALUE_OBJECT を組み合わせて返します。

例

例1 snmp_get_valueretrieval() の使用法

<?php
$ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
if (snmp_get_valueretrieval() & SNMP_VALUE_OBJECT) {
echo $ret->value;
} else {
echo $ret;
}
?>

参考

  • snmp_set_valueretrieval() - SNMP の値が返される方法を設定する
  • 定義済み定数


アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする

  • ≪ snmp_get_valueretrieval
  • snmp_set_enum_print ≫
  • PHP Manual
  • SNMP 関数
  • アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする

snmp_read_mib

(PHP 5, PHP 7, PHP 8)

snmp_read_mib — アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする

説明

snmp_read_mib(string $filename): bool

この関数は、ベンダー固有などの追加の MIB を読み込んで、 VENDOR-MIB::foo.1 のような可読形式の OID を取得します。

MIB を読み込む順序は重要で、参照先のオブジェクトが解決できなければ Net-SNMP ライブラリが警告を表示します。

パラメータ

filename

MIB のファイル名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 snmp_read_mib() の使用法

<?php
print_r( snmprealwalk('localhost', 'public', '.1.3.6.1.2.1.2.3.4.5') );

snmp_read_mib('./FOO-BAR-MIB.txt');
print_r( snmprealwalk('localhost', 'public', 'FOO-BAR-MIB::someTable') );
?>

上の例の結果は次のようになります。

Array
(
    [iso.3.6.1.2.1.2.3.4.5.0] => Gauge32: 6
)
Array
(
    [FOO-BAR-MIB::someTable.0] => Gauge32: 6
)


すべての enum を、実際の整数値ではなく enum 値とともに返す

  • ≪ snmp_read_mib
  • snmp_set_oid_numeric_print ≫
  • PHP Manual
  • SNMP 関数
  • すべての enum を、実際の整数値ではなく enum 値とともに返す

snmp_set_enum_print

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

snmp_set_enum_print — すべての enum を、実際の整数値ではなく enum 値とともに返す

説明

snmp_set_enum_print(bool $enable): true

この関数は、snmpwalk/snmpget などが自動的に MIB の enum 値を探して可読形式の文字列で返すかどうかを切り替えます。

パラメータ

enable

この値は boolean として Net-SNMP ライブラリが解釈します。"0" あるいは "1" しか指定できません。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 snmp_set_enum_print() の使用法

<?php
snmp_set_enum_print(0);
echo snmpget('localhost', 'public', 'IF-MIB::ifOperStatus.3') . "\n";
snmp_set_enum_print(1);
echo snmpget('localhost', 'public', 'IF-MIB::ifOperStatus.3') . "\n";
?>

上の例の結果は次のようになります。

INTEGER: up(1)
 INTEGER: 1


snmp_set_oid_output_format のエイリアス

  • ≪ snmp_set_enum_print
  • snmp_set_oid_output_format ≫
  • PHP Manual
  • SNMP 関数
  • snmp_set_oid_output_format のエイリアス

snmp_set_oid_numeric_print

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

snmp_set_oid_numeric_print — snmp_set_oid_output_format() のエイリアス

説明

この関数は次の関数のエイリアスです。 snmp_set_oid_output_format()

参考

  • snmp_set_oid_output_format() - OID の出力形式を設定する


OID の出力形式を設定する

  • ≪ snmp_set_oid_numeric_print
  • snmp_set_quick_print ≫
  • PHP Manual
  • SNMP 関数
  • OID の出力形式を設定する

snmp_set_oid_output_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

snmp_set_oid_output_format — OID の出力形式を設定する

説明

snmp_set_oid_output_format(int $format): true

snmp_set_oid_output_format() は、 出力形式を完全か数値のいずれかに設定します。

パラメータ

format
format の値による OID .1.3.6.1.2.1.1.3.0 の表しかた
SNMP_OID_OUTPUT_FULL | .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NUMERIC | .1.3.6.1.2.1.1.3.0
SNMP_OID_OUTPUT_MODULE | DISMAN-EVENT-MIB::sysUpTimeInstance
SNMP_OID_OUTPUT_SUFFIX | sysUpTimeInstance
SNMP_OID_OUTPUT_UCD | system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NONE | Undefined

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 snmprealwalk() の使用法

<?php

snmp_read_mib("/usr/share/mibs/netsnmp/NET-SNMP-TC");

// デフォルト、あるいは SNMP_OID_OUTPUT_MODULE
print_r( snmprealwalk('localhost', 'public', 'RFC1213-MIB::sysObjectID') );

snmp_set_oid_output_format(SNMP_OID_OUTPUT_NUMERIC);
print_r( snmprealwalk('localhost', 'public', 'RFC1213-MIB::sysObjectID') );

snmp_set_oid_output_format(SNMP_OID_OUTPUT_FULL);
print_r( snmprealwalk('localhost', 'public', 'RFC1213-MIB::sysObjectID') );
?>

上の例の結果は次のようになります。

Array
 (
    [RFC1213-MIB::sysObjectID.0] => OID: NET-SNMP-TC::linux
 )
 Array
 (
    [.1.3.6.1.2.1.1.2.0] => OID: .1.3.6.1.4.1.8072.3.2.10
 )
 Array
 (
    [.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID.0] => OID: .iso.org.dod.internet.private.enterprises.netSnmp.netSnmpEnumerations.netSnmpAgentOIDs.linux
 )


NET-SNMP ライブラリで enable の値を設定する

  • ≪ snmp_set_oid_output_format
  • snmp_set_valueretrieval ≫
  • PHP Manual
  • SNMP 関数
  • NET-SNMP ライブラリで enable の値を設定する

snmp_set_quick_print

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp_set_quick_print — NET-SNMP ライブラリで enable の値を設定する

説明

snmp_set_quick_print(bool $enable): true

NET-SNMP ライブラリで enable の値を設定します。この値を (1) に設定した場合、SNMP ライブラリは、'簡潔に表示された (quick printed)' 値を返します。 これは、値のみが出力されることを意味します。 enable が有効でない場合(デフォルト)、NET-SNMP ライブラリは、 (IP アドレスまたは OID のような)その値の種類を含む、より詳細な情報を 出力します。 加えて、quick_print が有効でない場合、ライブラリは 3 文字以下の全ての 文字列について 16 進数値も出力します。

デフォルトで、NET-SNMP ライブラリは冗長な値を返します。 quick_print は、値のみを返すために用いられます。

現在、文字列は引用符で括られて返されますが、 この動作は将来のリリースでは修正される予定です。

パラメータ

enable

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

quick_print の設定は、結果を表示するよりもその内容を使いたい場合によく行われます。

例1 snmp_set_quick_print() の使用例

<?php
snmp_set_quick_print(0);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a\n";
snmp_set_quick_print(1);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a\n";
?>

上の例の出力は、 たとえば以下のようになります。

'Timeticks: (0) 0:00:00.00'
'0:00:00.00'

参考

  • snmp_get_quick_print() - NET-SNMP ライブラリの quick_print の現在の設定値を取得する


SNMP の値が返される方法を設定する

  • ≪ snmp_set_quick_print
  • snmp2_get ≫
  • PHP Manual
  • SNMP 関数
  • SNMP の値が返される方法を設定する

snmp_set_valueretrieval

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

snmp_set_valueretrieval — SNMP の値が返される方法を設定する

説明

snmp_set_valueretrieval(int $method): true

パラメータ

method
型
SNMP_VALUE_LIBRARY | Net-SNMP ライブラリの返す形式のままで返します。
SNMP_VALUE_PLAIN | SNMP の型情報を含まないプレーンな値を返します。
SNMP_VALUE_OBJECT | プロパティ value および type をもつオブジェクトを返します。 type は SNMP_OCTET_STR や SNMP_COUNTER などの定数のいずれかとなります。 value を返す方法は、定数 SNMP_VALUE_LIBRARY, SNMP_VALUE_PLAIN のどちらが設定されているかによって決まります。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 snmp_set_valueretrieval() の使用法

<?php
snmp_set_valueretrieval(SNMP_VALUE_LIBRARY);
$ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
// $ret = "STRING: lo"

snmp_set_valueretrieval(SNMP_VALUE_PLAIN);
$ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
// $ret = "lo";

snmp_set_valueretrieval(SNMP_VALUE_OBJECT);
$ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
// stdClass Object
// (
// [type] => 4 <-- SNMP_OCTET_STR, see constants
// [value] => lo
// )

snmp_set_valueretrieval(SNMP_VALUE_OBJECT | SNMP_VALUE_PLAIN);
$ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
// stdClass Object
// (
// [type] => 4 <-- SNMP_OCTET_STR, see constants
// [value] => lo
// )

snmp_set_valueretrieval(SNMP_VALUE_OBJECT | SNMP_VALUE_LIBRARY);
$ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
// stdClass Object
// (
// [type] => 4 <-- SNMP_OCTET_STR, see constants
// [value] => STRING: lo
// )

?>

参考

  • snmp_get_valueretrieval() - SNMP の値が返される方法を返す
  • 定義済み定数


SNMP オブジェクトを取得する

  • ≪ snmp_set_valueretrieval
  • snmp2_getnext ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトを取得する

snmp2_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

snmp2_get — SNMP オブジェクトを取得する

説明

snmp2_get(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): mixed

snmp2_get() 関数は、 object_id で指定した SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント。

community

リードコミュニティ。

object_id

SNMP オブジェクト。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。

例

例1 snmp2_get() の使用法

<?php
$syscontact = snmp2_get("127.0.0.1", "public", "system.SysContact.0");
?>

参考

  • snmp2_set() - SNMP オブジェクトの値を設定する


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ snmp2_get
  • snmp2_real_walk ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

snmp2_getnext

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

snmp2_getnext(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): mixed

snmp2_get_next() 関数は、 object_id で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクトの ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmp2_get_next() の使用法

<?php
$nameOfSecondInterface = snmp2_get_next('localhost', 'public', 'IF-MIB::ifName.1');
?>

参考

  • snmp2_get() - SNMP オブジェクトを取得する
  • snmp2_walk() - すべての SNMP オブジェクトをエージェントから取得する


指定したすべてのオブジェクトとそのオブジェクト ID を返す

  • ≪ snmp2_getnext
  • snmp2_set ≫
  • PHP Manual
  • SNMP 関数
  • 指定したすべてのオブジェクトとそのオブジェクト ID を返す

snmp2_real_walk

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す

説明

snmp2_real_walk(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmp2_real_walk() 関数は、 object_id から始まる SNMP オブジェクトを走査し、その値とオブジェクト ID を返します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクト ID とその値の連想配列。エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmp2_real_walk() の使用法

<?php
print_r(snmp2_real_walk("localhost", "public", "IF-MIB::ifName"));
?>

上の例の結果は次のようになります。

Array
      (
      [IF-MIB::ifName.1] => STRING: lo
      [IF-MIB::ifName.2] => STRING: eth0
      [IF-MIB::ifName.3] => STRING: eth2
      [IF-MIB::ifName.4] => STRING: sit0
      [IF-MIB::ifName.5] => STRING: sixxs
    )

参考

  • snmp2_walk() - すべての SNMP オブジェクトをエージェントから取得する


SNMP オブジェクトの値を設定する

  • ≪ snmp2_real_walk
  • snmp2_walk ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトの値を設定する

snmp2_set

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_set — SNMP オブジェクトの値を設定する

説明

snmp2_set(
string $hostname,
string $community,
array|string $object_id,
array|string $type,
array|string $value,
int $timeout = -1,
int $retries = -1
): bool

snmp2_set() は、 object_id で指定した SNMP オブジェクトの値を設定します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

ライトコミュニティ。

object_id

SNMP オブジェクト ID。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

SNMP ホストがデータ型を却下すると、"Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." のような' E_WARNING メッセージが表示されます。未知の OID あるいは無効な OID を指定した場合は、おそらく "Could not add variable" のような警告となります。

例

例1 snmp2_set() の使用法

<?php
snmp2_set("localhost", "public", "IF-MIB::ifAlias.3", "s", "foo");
?>

例2 BITS SNMP オブジェクト ID を設定した snmp2_set() の使用法

<?php
snmp2_set("localhost", "public", 'FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
snmp2_set("localhost", "public", 'FOO-MIB::bar.42', 'x', 'F0');
?>

参考

  • snmp2_get() - SNMP オブジェクトを取得する


すべての SNMP オブジェクトをエージェントから取得する

  • ≪ snmp2_set
  • snmp3_get ≫
  • PHP Manual
  • SNMP 関数
  • すべての SNMP オブジェクトをエージェントから取得する

snmp2_walk

(PHP >= 5.2.0, PHP 7, PHP 8)

snmp2_walk — すべての SNMP オブジェクトをエージェントから取得する

説明

snmp2_walk(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmp2_walk() は、 hostname で指定した SNMP エージェントからすべての値を読み込みます。

パラメータ

hostname

SNMP エージェント (サーバー)。

community

リードコミュニティ。

object_id

null の場合は object_id は SNMP オブジェクトツリーのルートとなり、 ツリー配下のすべてのオブジェクトを配列で返します。

object_id を指定すると、 その object_id 以下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

object_id をルートとするすべての SNMP オブジェクトの値の配列、あるいはエラー時に false を返します。

例

例1 snmp2_pwalk() の例

<?php
$a = snmp2_walk("127.0.0.1", "public", "");

foreach ($a as $val) {
echo "$val\n";
}

?>

この例は、ローカルホストで動作している SNMP エージェントからすべての SNMP オブジェクトを返します。 この値をループで順次処理することができます。

参考

  • snmp2_real_walk() - 指定したすべてのオブジェクトとそのオブジェクト ID を返す


SNMP オブジェクトを取得する

  • ≪ snmp2_walk
  • snmp3_getnext ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトを取得する

snmp3_get

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_get — SNMP オブジェクトを取得する

説明

snmp3_get(
string $hostname,
string $security_name,
string $security_level,
string $auth_protocol,
string $auth_passphrase,
string $privacy_protocol,
string $privacy_passphrase,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): mixed

snmp3_get() 関数は、 object_id で指定した SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル ("MD5", "SHA", "SHA256", "SHA512")。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | auth_protocol は、 libnetsnmp がサポートする場合に、 新たに "SHA256" と "SHA512" を受け入れるようになりました。

例

例1 snmp3_get() の使用法

<?php
$nameOfSecondInterface = snmp3_get('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName.2');
?>

参考

  • snmp3_set() - SNMP オブジェクトの値を設定する


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ snmp3_get
  • snmp3_real_walk ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

snmp3_getnext

(PHP 5, PHP 7, PHP 8)

snmp3_getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

snmp3_getnext(
string $hostname,
string $security_name,
string $security_level,
string $auth_protocol,
string $auth_passphrase,
string $privacy_protocol,
string $privacy_passphrase,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): mixed

snmp3_getnext() 関数は、 object_id で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル ("MD5", "SHA", "SHA256", "SHA512")。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。 エラー時には E_WARNING が発生します。

変更履歴

バージョン | 説明
8.1.0 | auth_protocol は、 libnetsnmp がサポートする場合に、 新たに "SHA256" と "SHA512" を受け入れるようになりました。

例

例1 snmp3_getnext() の使用法

<?php
$nameOfSecondInterface = snmp3_getnext('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName.1');
?>

参考

  • snmp3_get() - SNMP オブジェクトを取得する
  • snmp3_walk() - すべての SNMP オブジェクトをエージェントから取得する


指定したすべてのオブジェクトとそのオブジェクト ID を返す

  • ≪ snmp3_getnext
  • snmp3_set ≫
  • PHP Manual
  • SNMP 関数
  • 指定したすべてのオブジェクトとそのオブジェクト ID を返す

snmp3_real_walk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_real_walk — 指定したすべてのオブジェクトとそのオブジェクト ID を返す

説明

snmp3_real_walk(
string $hostname,
string $security_name,
string $security_level,
string $auth_protocol,
string $auth_passphrase,
string $privacy_protocol,
string $privacy_passphrase,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmp3_real_walk() 関数は、 object_id から始まる SNMP オブジェクトを走査し、その値とオブジェクト ID を返します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル ("MD5", "SHA", "SHA256", "SHA512")。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクト ID とその値の連想配列。エラー時に false を返します。 エラー時には E_WARNING が発生します。

変更履歴

バージョン | 説明
8.1.0 | auth_protocol は、 libnetsnmp がサポートする場合に、 新たに "SHA256" と "SHA512" を受け入れるようになりました。

例

例1 snmp3_real_walk() の使用法

<?php
var_export(snmp3_real_walk('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName'));
?>

上の例の結果は次のようになります。

array (
  'IF-MIB::ifName.1' => 'STRING: lo',
  'IF-MIB::ifName.2' => 'STRING: eth0',
  'IF-MIB::ifName.3' => 'STRING: eth2',
  'IF-MIB::ifName.4' => 'STRING: sit0',
  'IF-MIB::ifName.5' => 'STRING: sixxs',
)

参考

  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する


SNMP オブジェクトの値を設定する

  • ≪ snmp3_real_walk
  • snmp3_walk ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトの値を設定する

snmp3_set

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_set — SNMP オブジェクトの値を設定する

説明

snmp3_set(
string $hostname,
string $security_name,
string $security_level,
string $auth_protocol,
string $auth_passphrase,
string $privacy_protocol,
string $privacy_passphrase,
array|string $object_id,
array|string $type,
array|string $value,
int $timeout = -1,
int $retries = -1
): bool

snmp3_set() は、 object_id で指定した SNMP オブジェクトの値を設定します。

セキュリティレベルに auth や priv を使っていなくても、 protocol/password には有効な値を指定しなくてはなりません。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル (MD5 あるいは SHA)。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

SNMP オブジェクト ID。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

SNMP ホストがデータ型を却下すると、"Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." のような' E_WARNING メッセージが表示されます。未知の OID あるいは無効な OID を指定した場合は、おそらく "Could not add variable" のような警告となります。

例

例1 snmp3_set() の使用法

<?php
snmp3_set('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifAlias.3', 's', "foo");
?>

例2 BITS SNMP オブジェクト ID を設定した snmp3_set() の使用法

<?php
snmp3_set('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
snmp3_set('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'FOO-MIB::bar.42', 'x', 'F0');
?>


すべての SNMP オブジェクトをエージェントから取得する

  • ≪ snmp3_set
  • snmpget ≫
  • PHP Manual
  • SNMP 関数
  • すべての SNMP オブジェクトをエージェントから取得する

snmp3_walk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmp3_walk — すべての SNMP オブジェクトをエージェントから取得する

説明

snmp3_walk(
string $hostname,
string $security_name,
string $security_level,
string $auth_protocol,
string $auth_passphrase,
string $privacy_protocol,
string $privacy_passphrase,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmp3_walk() 関数は、 hostname で指定した SNMP エージェントからすべての値を読み込みます。

セキュリティレベルに auth や priv を使っていなくても、 protocol/password には有効な値を指定しなくてはなりません。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

security_name

セキュリティ名。通常はユーザー名のようなもの。

security_level

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

auth_protocol

認証プロトコル ("MD5", "SHA", "SHA256", "SHA512")。

auth_passphrase

認証パスフレーズ。

privacy_protocol

プライバシープロトコル (DES あるいは AES)。

privacy_passphrase

プライバシーパスフレーズ。

object_id

null の場合は object_id は SNMP オブジェクトツリーのルートとなり、 ツリー配下のすべてのオブジェクトを配列で返します。

object_id を指定すると、 その object_id 以下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

object_id をルートとするすべての SNMP オブジェクトの値の配列、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.1.0 | auth_protocol は、 libnetsnmp がサポートする場合に、 新たに "SHA256" と "SHA512" を受け入れるようになりました。

例

例1 snmp3_walk() の例

<?php
$ret = snmp3_walk('localhost', 'james', 'authPriv', 'SHA', 'secret007', 'AES', 'secret007', 'IF-MIB::ifName');
var_export($ret);
?>

上の関数コールは、ローカルホストで動作している SNMP エージェントからすべての SNMP オブジェクトを返します。

array (
  0 => 'STRING: lo',
  1 => 'STRING: eth0',
  2 => 'STRING: eth2',
  3 => 'STRING: sit0',
  4 => 'STRING: sixxs',
)

参考

  • snmp3_real_walk() - 指定したすべてのオブジェクトとそのオブジェクト ID を返す


SNMP オブジェクトを取得する

  • ≪ snmp3_walk
  • snmpgetnext ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトを取得する

snmpget

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpget — SNMP オブジェクトを取得する

説明

snmpget(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): mixed

snmpget() は object_id で指定した SNMP オブジェクトの値を読みとるために使用されます。

パラメータ

hostname

SNMP エージェント。

community

リードコミュニティ。

object_id

SNMP オブジェクト。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウトが発生したときの再試行の回数。

戻り値

成功した場合に SNMP オブジェクトの値、失敗した場合に false を返します。

例

例1 snmpget() の使用例

<?php
$syscontact = snmpget("127.0.0.1", "public", "system.SysContact.0");
?>

参考

  • snmpset() - SNMP オブジェクトの値を設定する


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ snmpget
  • snmprealwalk ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

snmpgetnext

(PHP 5, PHP 7, PHP 8)

snmpgetnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

snmpgetnext(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): mixed

snmpgetnext() 関数は、 object_id で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクトの ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクトの値、エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmpgetnext() の使用法

<?php
$nameOfSecondInterface = snmpgetnetxt('localhost', 'public', 'IF-MIB::ifName.1');
?>

参考

  • snmpget() - SNMP オブジェクトを取得する
  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する


指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

  • ≪ snmpgetnext
  • snmpset ≫
  • PHP Manual
  • SNMP 関数
  • 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

snmprealwalk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmprealwalk — 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す

説明

snmprealwalk(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmprealwalk() 関数は、 object_id から始まる SNMP オブジェクトを走査し、その値とオブジェクト ID を返します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

リードコミュニティ。

object_id

前にある SNMP オブジェクト ID。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に SNMP オブジェクト ID とその値の連想配列。エラー時に false を返します。 エラー時には E_WARNING が発生します。

例

例1 snmprealwalk() の使用法

<?php
print_r(snmprealwalk("localhost", "public", "IF-MIB::ifName"));
?>

上の例の結果は次のようになります。

Array
      (
      [IF-MIB::ifName.1] => STRING: lo
      [IF-MIB::ifName.2] => STRING: eth0
      [IF-MIB::ifName.3] => STRING: eth2
      [IF-MIB::ifName.4] => STRING: sit0
      [IF-MIB::ifName.5] => STRING: sixxs
    )

参考

  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する


SNMP オブジェクトの値を設定する

  • ≪ snmprealwalk
  • snmpwalk ≫
  • PHP Manual
  • SNMP 関数
  • SNMP オブジェクトの値を設定する

snmpset

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpset — SNMP オブジェクトの値を設定する

説明

snmpset(
string $hostname,
string $community,
array|string $object_id,
array|string $type,
array|string $value,
int $timeout = -1,
int $retries = -1
): bool

snmpset() 関数は、 object_idで指定した SNMP オブジェクトの 値を設定するために使用します。

パラメータ

hostname

SNMP エージェント (サーバー) のホスト名。

community

ライトコミュニティ。

object_id

SNMP オブジェクト ID。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

成功した場合に true を、失敗した場合に false を返します。

SNMP ホストがデータ型を却下すると、"Warning: Error in packet. Reason: (badValue) The value given has the wrong type or length." のような' E_WARNING メッセージが表示されます。未知の OID あるいは無効な OID を指定した場合は、おそらく "Could not add variable" のような警告となります。

例

例1 snmpset() の使用法

<?php
snmpset("localhost", "public", "IF-MIB::ifAlias.3", "s", "foo");
?>

例2 BITS SNMP オブジェクト ID を設定した snmpset() の使用法

<?php
snmpset("localhost", "public", 'FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
snmpset("localhost", "public", 'FOO-MIB::bar.42', 'x', 'F0');
?>

参考

  • snmpget() - SNMP オブジェクトを取得する


エージェントから全ての SNMP オブジェクトを取得する

  • ≪ snmpset
  • snmpwalkoid ≫
  • PHP Manual
  • SNMP 関数
  • エージェントから全ての SNMP オブジェクトを取得する

snmpwalk

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpwalk — エージェントから全ての SNMP オブジェクトを取得する

説明

snmpwalk(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmpwalk() 関数は、hostname で指定した SNMP エージェントから全ての値を読みとるのに使用します。

パラメータ

hostname

SNMP エージェント (サーバー)。

community

リードコミュニティ。

object_id

null の場合は、object_id が SNMP オブジェクトツリーのルートとして解釈され、 ツリーの配下のすべてのオブジェクトを配列として返します。

object_id を指定した場合は、 その object_id の配下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

object_id() からの SNMP オブジェクトの値の配列をルートとして返します。 エラーの場合に false を返します。

例

例1 snmpwalk() の例

<?php
$a = snmpwalk("127.0.0.1", "public", "");

foreach ($a as $val) {
echo "$val\n";
}

?>

上記の関数コールは、ローカルホスト上で稼働する SNMP エージェントからすべての SNMP オブジェクトを返します。 ループ処理により値を一つずつとりだすことができます。

参考

  • snmprealwalk() - 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す


ネットワークエンティティに関する情報ツリーを検索する

  • ≪ snmpwalk
  • SNMP ≫
  • PHP Manual
  • SNMP 関数
  • ネットワークエンティティに関する情報ツリーを検索する

snmpwalkoid

(PHP 4, PHP 5, PHP 7, PHP 8)

snmpwalkoid — ネットワークエンティティに関する情報ツリーを検索する

説明

snmpwalkoid(
string $hostname,
string $community,
array|string $object_id,
int $timeout = -1,
int $retries = -1
): array|false

snmpwalkoid() 関数は、hostname で指定した SNMP エージェントから すべてのオブジェクト ID とその値を読みこむために使用します。

snmpwalkoid() および snmpwalk() は、歴史的経緯により残されているものです。 どちらも、下位互換のために提供されています。 代わりに snmprealwalk() を使用してください。

パラメータ

hostname

SNMP エージェント。

community

リードコミュニティ。

object_id

null の場合は、object_id が SNMP オブジェクトツリーのルートとして解釈され、 ツリーの配下のすべてのオブジェクトを配列として返します。

object_id を指定した場合は、 その object_id の配下のすべての SNMP オブジェクトを返します。

timeout

最初のタイムアウトまでのマイクロ秒数。

retries

タイムアウト発生時の再試行回数。

戻り値

object_id() からの SNMP オブジェクトの値の配列をルートとして返します。 エラーの場合に false を返します。

例

例1 snmpwalkoid() の例

<?php
$a = snmpwalkoid("127.0.0.1", "public", "");
for (reset($a); $i = key($a); next($a)) {
echo "$i: $a[$i]<br />\n";
}
?>

上記の関数コールは、ローカルホスト上で稼働する SNMP エージェントからすべての SNMP オブジェクトを返します。 ループ処理により値を一つずつとりだすことができます。

参考

  • snmpwalk() - エージェントから全ての SNMP オブジェクトを取得する


SNMP クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SNMP セッションを表します。

クラス概要

class SNMP {
/* 定数 */
public const int VERSION_1;
public const int VERSION_2c;
public const int VERSION_2C;
public const int VERSION_3;
public const int ERRNO_NOERROR;
public const int ERRNO_ANY;
public const int ERRNO_GENERIC;
public const int ERRNO_TIMEOUT;
public const int ERRNO_ERROR_IN_REPLY;
public const int ERRNO_OID_NOT_INCREASING;
public const int ERRNO_OID_PARSING_ERROR;
public const int ERRNO_MULTIPLE_SET_QUERIES;
/* プロパティ */
public readonly array $info;
public ?int $max_oids;
public int $valueretrieval;
public bool $quick_print;
public bool $enum_print;
public int $oid_output_format;
public bool $oid_increasing_check;
public int $exceptions_enabled;
/* メソッド */
public __construct(
int $version,
string $hostname,
string $community,
int $timeout = -1,
int $retries = -1
)
public close(): bool
public get(array|string $objectId, bool $preserveKeys = false): mixed
public getErrno(): int
public getError(): string
public getnext(array|string $objectId): mixed
public set(array|string $objectId, array|string $type, array|string $value): bool
public setSecurity(
string $securityLevel,
string $authProtocol = "",
string $authPassphrase = "",
string $privacyProtocol = "",
string $privacyPassphrase = "",
string $contextName = "",
string $contextEngineId = ""
): bool
public walk(
array|string $objectId,
bool $suffixAsKey = false,
int $maxRepetitions = -1,
int $nonRepeaters = -1
): array|false
}

プロパティ

max_oids

GET/SET/GETBULK リクエスト単位の最大の OID

valueretrieval

SNMP の値を返す方法

SNMP_VALUE_LIBRARY | Net-SNMP ライブラリの返す値を返します。
SNMP_VALUE_PLAIN | SNMP 型情報を含まないプレーンな値を返します。
SNMP_VALUE_OBJECT | オブジェクトを返します。このオブジェクトはプロパティ "value" および "type" を持ち、後者のプロパティの値は SNMP_OCTET_STR, SNMP_COUNTER などの定数となります。 "value" の中身は SNMP_VALUE_LIBRARY と SNMP_VALUE_PLAIN のどちらが設定されているかによって変わります。
quick_print

NET-SNMP ライブラリ内の quick_print の値

NET-SNMP ライブラリ内の quick_print の値を指定します。 これを (1 に) 設定すると、SNMP ライブラリは「手早く表示」した値を返します。 つまり、単なる値だけを表示するということです。quick_print を有効にしなければ (デフォルト)、NET-SNMP ライブラリは追加情報 (値の型、たとえば IpAddress や OID) も表示します。 さらに、quick_print が有効でない場合は、三文字以下のすべての文字列に対して追加の十六進値を表示します。

enum_print

enum 値の表示方法

walk や get などが、自動的に MIB 内の enum 値の元をたどって その値も可読形式の文字列にするかどうかを設定します。

oid_output_format

OID の出力フォーマットの制御

oid_output_format の値による、OID .1.3.6.1.2.1.1.3.0 の表示方法の変化
SNMP_OID_OUTPUT_FULL | .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NUMERIC | .1.3.6.1.2.1.1.3.0
SNMP_OID_OUTPUT_MODULE | DISMAN-EVENT-MIB::sysUpTimeInstance
SNMP_OID_OUTPUT_SUFFIX | sysUpTimeInstance
SNMP_OID_OUTPUT_UCD | system.sysUpTime.sysUpTimeInstance
SNMP_OID_OUTPUT_NONE | Undefined
oid_increasing_check

OID ツリーを走査中の OID 増加チェックの無効化

SNMP エージェントの中には、 OID を返す順番がおかしくても走査はできるというものがあります。 それ以外のエージェントの場合、OID を返す順番がおかしくなると SNMP::walk() が無限ループになり、 メモリを食いつぶしてしまいます。PHP の SNMP ライブラリは、 デフォルトで OID の増加チェックを行い、もし OID ツリーの走査中に OID が増加しないパターンがあればそこで走査を終了します。 oid_increasing_check を false にすると、このチェックが無効になります。

exceptions_enabled

警告ではなく SNMPException を発生させるのがどの失敗なのかを設定します。 Use bitwise OR'ed SNMP::ERRNO_* constants. By default all SNMP exceptions are disabled.

info

読み込み専用のプロパティで、リモートエージェントの設定を表します。 ホスト名やポート、デフォルトのタイムアウト、デフォルトの再試行回数を含みます。

定義済み定数

SNMP エラー型

SNMP::ERRNO_NOERROR

SNMP に関するエラーは発生していません。

SNMP::ERRNO_GENERIC

SNMP のエラーが発生しました。

SNMP::ERRNO_TIMEOUT

SNMP エージェントへのリクエストがタイムアウトしました。

SNMP::ERRNO_ERROR_IN_REPLY

SNMP エージェントがエラーの応答を返しました。

SNMP::ERRNO_OID_NOT_INCREASING

SNMP エージェントが、(BULK)WALK コマンドの実行中に前の OID から増加していない OID に当たりました。 リモート SNMP エージェントが偽物である可能性があります。

SNMP::ERRNO_OID_PARSING_ERROR

OID (や SET コマンドの型) のパースに失敗しました。 クエリは作成されませんでした。

SNMP::ERRNO_MULTIPLE_SET_QUERIES

要求された SET 操作で複数のクエリを使います。 この操作はトランザクション内の操作ではないので、 二番目以降のクエリに型や値の問題があれば失敗するかもしれません。

SNMP::ERRNO_ANY

すべての SNMP::ERRNO_* コードをビット OR したもの。

SNMP プロトコルバージョン

SNMP::VERSION_1

SNMP::VERSION_2C, SNMP::VERSION_2c

SNMP::VERSION_3

目次

  • SNMP::close — SNMP セッションを閉じる
  • SNMP::__construct — リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する
  • SNMP::get — SNMP オブジェクトを取得する
  • SNMP::getErrno — 直近のエラーコードを取得する
  • SNMP::getError — 直近のエラーメッセージを取得する
  • SNMP::getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
  • SNMP::set — SNMP オブジェクトの値を設定する
  • SNMP::setSecurity — セキュリティ関連の SNMPv3 セッションパラメータを設定する
  • SNMP::walk — SNMP オブジェクトのサブツリーを取得する


SNMP セッションを閉じる

  • ≪ SNMP
  • SNMP::__construct ≫
  • PHP Manual
  • SNMP
  • SNMP セッションを閉じる

SNMP::close

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::close — SNMP セッションを閉じる

説明

public SNMP::close(): bool

SNMP セッションオブジェクトを閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SNMP::close() の例

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
# ...
# get, walk, etc goes here
# ...
$session->close();
?>

参考

  • SNMP::__construct() - リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する


リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

  • ≪ SNMP::close
  • SNMP::get ≫
  • PHP Manual
  • SNMP
  • リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

SNMP::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::__construct — リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する

説明

public SNMP::__construct(
int $version,
string $hostname,
string $community,
int $timeout = -1,
int $retries = -1
)

The function description goes here.

パラメータ

version

SNMP プロトコルのバージョン。
SNMP::VERSION_1、
SNMP::VERSION_2C あるいは
SNMP::VERSION_3。

hostname

SNMP エージェント。hostname には、オプションでコロンに続けて SNMP エージェントのポートを指定できます。 IPv6 アドレスでポートを指定する場合は、アドレス部を角括弧で囲まなければなりません。 hostname で FQDN を使うと、その解決に使われるのは php-snmp ライブラリであり、Net-SNMP エンジンは使いません。 FQDN を指定するときに IPv6 アドレスを使うには、FQDN を角括弧で囲まなければなりません。 いくつか例を示します。

IPv4 (デフォルトのポート) | 127.0.0.1
IPv6 (デフォルトのポート) | ::1 あるいは [::1]
IPv4 (ポートを指定) | 127.0.0.1:1161
IPv6 (ポートを指定) | [::1]:1161
FQDN (デフォルトのポート) | host.domain
FQDN (ポートを指定) | host.domain:1161
FQDN (デフォルトのポート)、IPv6 アドレスを強制 | [host.domain]
FQDN (ポートを指定)、IPv6 アドレスを強制 | [host.domain]:1161

community

community の目的は SNMP のバージョンによって異なります。

SNMP::VERSION_1 | SNMP コミュニティ
SNMP::VERSION_2C | SNMP コミュニティ
SNMP::VERSION_3 | SNMPv3 セキュリティ名
timeout

最初のタイムアウトまでのミリ秒数。

retries

タイムアウト発生時の再試行回数。

エラー / 例外

SNMP::__construct() が例外を発生させるのは、 パラメータの数や型が間違っていたり未知の SNMP プロトコルバージョンを指定したりした場合です。

例

例1 sysLocation の取得

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$sysdescr = $session->get("sysDescr.0");
echo "$sysdescr\n";
?>

上の例の出力は、 たとえば以下のようになります。

STRING: Test server

参考

  • SNMP::close() - SNMP セッションを閉じる


SNMP オブジェクトを取得する

  • ≪ SNMP::__construct
  • SNMP::getErrno ≫
  • PHP Manual
  • SNMP
  • SNMP オブジェクトを取得する

SNMP::get

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::get — SNMP オブジェクトを取得する

説明

public SNMP::get(array|string $objectId, bool $preserveKeys = false): mixed

objectId で指定した SNMP オブジェクトを GET クエリで取得します。

パラメータ

objectId が文字列の場合は SNMP::get() は SNMP オブジェクトを文字列で返します。 objectId が配列の場合は、要求されたすべての SNMP オブジェクトを SNMP オブジェクトの id とその値の連想配列で返します。

objectId

SNMP オブジェクト (OID)。

preserveKeys

objectId が配列のときに preserveKeys を true にすると、結果のキーは完全に objectId となります。 それ以外の場合は SNMP::oid_output_format プロパティを使ってキーの形式を判断します。

戻り値

objectId で指定した SNMP オブジェクトの値を objectId にあわせて文字列か配列で返します。 エラー時には false を返します。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 単一の SNMP オブジェクト

ひとつの SNMP オブジェクトに対するリクエストは二通りの方法で行えます。 文字列でリクエストすると結果は文字列で返され、要素がひとつだけの配列でリクエストすると結果は連想配列で返されます。

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$sysdescr = $session->get("sysDescr.0");
echo "$sysdescr\n";
$sysdescr = $session->get(array("sysDescr.0"));
print_r($sysdescr);
?>

上の例の出力は、 たとえば以下のようになります。

STRING: Test server
Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
)

例2 複数の SNMP オブジェクト

$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$results = $session->get(array("sysDescr.0", "sysName.0"));
print_r($results);
$session->close();

上の例の出力は、 たとえば以下のようになります。

Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
    [SNMPv2-MIB::sysName.0] => STRING: myhost.nodomain
)

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する
  • SNMP::getError() - 直近のエラーメッセージを取得する


直近のエラーコードを取得する

  • ≪ SNMP::get
  • SNMP::getError ≫
  • PHP Manual
  • SNMP
  • 直近のエラーコードを取得する

SNMP::getErrno

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::getErrno — 直近のエラーコードを取得する

説明

public SNMP::getErrno(): int

直近の SNMP リクエストのエラーコードを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

定数のページで説明した SNMP エラーコードのいずれかを返します。

例

例1 SNMP::getErrno() の例

<?php
$session = new SNMP(SNMP::VERSION_2c, '127.0.0.1', 'boguscommunity');
var_dump(@$session->get('.1.3.6.1.2.1.1.1.0'));
var_dump($session->getErrno() == SNMP::ERRNO_TIMEOUT);
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • SNMP::getError() - 直近のエラーメッセージを取得する


直近のエラーメッセージを取得する

  • ≪ SNMP::getErrno
  • SNMP::getnext ≫
  • PHP Manual
  • SNMP
  • 直近のエラーメッセージを取得する

SNMP::getError

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::getError — 直近のエラーメッセージを取得する

説明

public SNMP::getError(): string

直近の SNMP リクエストのエラー文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の SNMP リクエストからのエラーを表す文字列を返します。

例

例1 SNMP::getError() の例

<?php
$session = new SNMP(SNMP::VERSION_2c, '127.0.0.1', 'boguscommunity');
var_dump(@$session->get('.1.3.6.1.2.1.1.1.0'));
var_dump($session->getError());
?>

上の例の出力は以下となります。

bool(false)
string(26) "No response from 127.0.0.1"

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する


指定したオブジェクト ID に続く SNMP オブジェクトを取得する

  • ≪ SNMP::getError
  • SNMP::set ≫
  • PHP Manual
  • SNMP
  • 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

SNMP::getnext

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::getnext — 指定したオブジェクト ID に続く SNMP オブジェクトを取得する

説明

public SNMP::getnext(array|string $objectId): mixed

objectId で指定したオブジェクトに続く SNMP オブジェクトの値を取得します。

パラメータ

objectId が文字列の場合は SNMP::getnext() は SNMP オブジェクトを文字列で返します。 objectId が配列の場合は、要求されたすべての SNMP オブジェクトを SNMP オブジェクトの id とその値の連想配列で返します。

objectId

SNMP オブジェクト (OID)。

戻り値

SNMP オブジェクトの値を objectId にあわせて文字列か配列で返します。 エラー時には false を返します。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 単一の SNMP オブジェクト

ひとつの SNMP オブジェクトに対するリクエストは二通りの方法で行えます。 文字列でリクエストすると結果は文字列で返され、要素がひとつだけの配列でリクエストすると結果は連想配列で返されます。

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$nsysdescr = $session->getnext("sysDescr.0");
echo "$nsysdescr\n";
$nsysdescr = $session->getnext(array("sysDescr.0"));
print_r($nsysdescr);
?>

上の例の出力は、 たとえば以下のようになります。

OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
Array
(
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
)

例2 複数の SNMP オブジェクト

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$results = $session->getnext(array("sysDescr.0", "sysName.0"));
print_r($results);
$session->close();
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
    [SNMPv2-MIB::sysLocation.0] => STRING: Nowhere
)

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する
  • SNMP::getError() - 直近のエラーメッセージを取得する


SNMP オブジェクトの値を設定する

  • ≪ SNMP::getnext
  • SNMP::setSecurity ≫
  • PHP Manual
  • SNMP
  • SNMP オブジェクトの値を設定する

SNMP::set

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::set — SNMP オブジェクトの値を設定する

説明

public SNMP::set(array|string $objectId, array|string $type, array|string $value): bool

リモート SNMP エージェントに対して、 objectId で指定した SNMP オブジェクトの値を設定させます。

パラメータ

objectId が文字列のときは、 type と value も文字列にしなければなりません。 objectId が配列のときは、 value も同じサイズの配列にして、対応する値を含めなければなりません。 type は、文字列でもいいし (この値を、すべての objectId-value ペアに適用する)、 同じサイズの配列 (OID ごとに設定する) でもかまいません。 その他の組み合わせで指定すると、E_WARNING メッセージが表示されます。

objectId

SNMP オブジェクト ID。

object_id 配列の OID 数がオブジェクトの max_oids プロパティより多ければ、set メソッドは複数のクエリで値の更新をしなければなりません。 この場合、型や値のチェックはチャンク単位で行われるので、 二番目以降のクエリでリクエストする ODI に対して型や値の問題があれば失敗するかもしれません。 そのため、object_id 配列の OID 数が max_oids プロパティより多いときには警告が発生します。

type

MIB は、オブジェクトIDごとのタイプを定義します。 これは、以下の一覧から指定される一文字でなければなりません。

types
= MIBから取得するタイプ
i | INTEGER
u | INTEGER
s | STRING
x | HEX STRING
d | DECIMAL STRING
n | NULLOBJ
o | OBJID
t | TIMETICKS
a | IPADDRESS
b | BITS

SNMP ライブラリをコンパイルする際、 OPAQUE_SPECIAL_TYPES が定義されていた場合、 以下も正しい値になります:

types
U | unsigned int64
I | signed int64
F | float
D | double

これらの大半は、対応する ASN.1 の型を使います。's', 'x', 'd' および 'b' はどれも OCTET STRING を異なる方法で表したものであり、'u' も Gauge32 値を扱うためのものです。

MIB ファイルが "snmp_read_mib" や libsnmp の設定で MIB ツリーに読み込まれている場合は、 type に '=' を使うことができます。 これはすべてのオブジェクト ID を表し、型は自動的に MIB から読み込みます。

"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}" のような BITS 型の値変数を設定する方法は二通りあることに注意しましょう。

  • 型として "b" を使い、ビット番号の一覧を指定する。この方法はおすすめしません。 同じ OID に対して GET クエリを実行しても 0xF8 などを返すからです。
  • Using type "x" and a hex number but without(!) the usual "0x" prefix. 型として "x" を使い、通常のプレフィックス "0x" をつけずに(!) 16 進数を指定する。

詳細は、サンプルを参照ください。

value

新しい値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 単一の SNMP オブジェクト ID の設定

<?php
$session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
$session->set('SNMPv2-MIB::sysContact.0', 's', "Nobody");
?>

例2 単一の SNMP::set() コールによる複数の値の設定

<?php
$session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
$session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), array('s', 's'), array("Nobody", "Nowhere"));
// あるいは
$session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), 's', array("Nobody", "Nowhere"));
?>

例3 BITS SNMP オブジェクト ID の設定による SNMP::set() の使用法

<?php
$session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
$session->set('FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// あるいは
$session->set('FOO-MIB::bar.42', 'x', 'F0');
?>

参考

  • SNMP::get() - SNMP オブジェクトを取得する


セキュリティ関連の SNMPv3 セッションパラメータを設定する

  • ≪ SNMP::set
  • SNMP::walk ≫
  • PHP Manual
  • SNMP
  • セキュリティ関連の SNMPv3 セッションパラメータを設定する

SNMP::setSecurity

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::setSecurity — セキュリティ関連の SNMPv3 セッションパラメータを設定する

説明

public SNMP::setSecurity(
string $securityLevel,
string $authProtocol = "",
string $authPassphrase = "",
string $privacyProtocol = "",
string $privacyPassphrase = "",
string $contextName = "",
string $contextEngineId = ""
): bool

setSecurity は、 SNMP プロトコルバージョン 3 で使うセキュリティ関連のセッションパラメータを設定します。

パラメータ

securityLevel

セキュリティレベル (noAuthNoPriv|authNoPriv|authPriv)。

authProtocol

認証プロトコル (MD5 あるいは SHA)。

authPassphrase

認証パスフレーズ。

privacyProtocol

プライバシープロトコル (DES あるいは AES)。

privacyPassphrase

プライバシーパスフレーズ。

contextName

コンテキスト名。

contextEngineId

コンテキスト EngineID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SNMP::setSecurity() の例

<?php
$session = new SNMP(SNMP::VERSION_3, $hostname, $rwuser, $timeout, $retries);
$session->setSecurity('authPriv', 'MD5', $auth_pass, 'AES', $priv_pass, '', 'aeeeff');
?>

参考

  • SNMP::__construct() - リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する


SNMP オブジェクトのサブツリーを取得する

  • ≪ SNMP::setSecurity
  • SNMPException ≫
  • PHP Manual
  • SNMP
  • SNMP オブジェクトのサブツリーを取得する

SNMP::walk

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SNMP::walk — SNMP オブジェクトのサブツリーを取得する

説明

public SNMP::walk(
array|string $objectId,
bool $suffixAsKey = false,
int $maxRepetitions = -1,
int $nonRepeaters = -1
): array|false

SNMP::walk() を使い、 指定した objectId を起点とする SNMP サブツリーを読み込みます。

パラメータ

objectId

取得するサブツリーのルート。

suffixAsKey

デフォルトでは、完全な OID 記法を出力配列のキーとして使います。 true にすると、サブツリーのプレフィックスはキーから取り除き、 object_id のサフィックスだけを残します。

nonRepeaters

これは、渡された変数の中で反復処理の対象外とする変数の数を指定します。 デフォルトは、SNMP オブジェクトでの設定を使います。

maxRepetitions

これは、繰り返す変数の反復処理の最大数を指定します。 デフォルトは、SNMP オブジェクトでの設定を使います。

戻り値

成功した場合は SNMP オブジェクトの ID とその値の連想配列を返します。エラー時には false を返します。 SNMP エラーが発生した場合は、SNMP::getErrno() および SNMP::getError() を使えばエラー番号(SNMP 拡張モジュールで設定したもの。クラス定数を参照) とエラーメッセージをそれぞれ取得できます。

エラー / 例外

このメソッドは、デフォルトでは一切例外をスローしません。ライブラリでエラーが発生したときに SNMPException をスローさせるには SNMP クラスパラメータ exceptions_enabled に値を設定しなければなりません。 詳細は SNMP::$exceptions_enabled の説明を参照ください。

例

例1 SNMP::walk() の例

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$fulltree = $session->walk(".");
print_r($fulltree);
$session->close();
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [SNMPv2-MIB::sysDescr.0] => STRING: Test server
    [SNMPv2-MIB::sysObjectID.0] => OID: NET-SNMP-MIB::netSnmpAgentOIDs.8
    [DISMAN-EVENT-MIB::sysUpTimeInstance] => Timeticks: (1150681750) 133 days, 4:20:17.50
    [SNMPv2-MIB::sysContact.0] => STRING: Nobody
    [SNMPv2-MIB::sysName.0] => STRING: server.localdomain
    ...
)

例2 suffixAsKey の例

suffixAsKey は、複数の SNMP サブツリーをひとつにまとめるときに使えます。この例では、インターフェイス名とその型を関連付けます。

<?php
$session = new SNMP(SNMP::VERSION_1, "127.0.0.1", "public");
$session->valueretrieval = SNMP_VALUE_PLAIN;
$ifDescr = $session->walk(".1.3.6.1.2.1.2.2.1.2", TRUE);
$session->valueretrieval = SNMP_VALUE_LIBRARY;
$ifType = $session->walk(".1.3.6.1.2.1.2.2.1.3", TRUE);
print_r($ifDescr);
print_r($ifType);
$result = array();
foreach($ifDescr as $i => $n) {
$result[$n] = $ifType[$i];
}
print_r($result);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [1] => igb0
    [2] => igb1
    [3] => ipfw0
    [4] => lo0
    [5] => lagg0
)
Array
(
    [1] => INTEGER: ieee8023adLag(161)
    [2] => INTEGER: ieee8023adLag(161)
    [3] => INTEGER: ethernetCsmacd(6)
    [4] => INTEGER: softwareLoopback(24)
    [5] => INTEGER: ethernetCsmacd(6)
)
Array
(
    [igb0] => INTEGER: ieee8023adLag(161)
    [igb1] => INTEGER: ieee8023adLag(161)
    [ipfw0] => INTEGER: ethernetCsmacd(6)
    [lo0] => INTEGER: softwareLoopback(24)
    [lagg0] => INTEGER: ethernetCsmacd(6)
)

参考

  • SNMP::getErrno() - 直近のエラーコードを取得する
  • SNMP::getError() - 直近のエラーメッセージを取得する


SNMPException クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SNMP で発生するエラーを表します。自分のコードから SNMPException をスローしてはいけません。 PHP における例外処理の詳細な情報は 例外 を参照ください。

クラス概要

class SNMPException extends RuntimeException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

code

SNMP ライブラリのエラーコード。Exception::getCode() でアクセスします。


ソケット

  • はじめに
  • インストール/設定
    • インストール手順
    • リソース型
  • 定義済み定数
  • 例
  • ソケットのエラー
  • ソケット 関数
    • socket_accept — ソケットへの接続を許可する
    • socket_addrinfo_bind — 与えられた addrinfo から、ソケットを作成してバインドする
    • socket_addrinfo_connect — 与えられた addrinfo から、ソケットを作って接続する
    • socket_addrinfo_explain — addrinfo に関する情報を取得する
    • socket_addrinfo_lookup — 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
    • socket_atmark — ソケットに帯域外マークが付けられているかを調べる
    • socket_bind — ソケットに名前をバインドする
    • socket_clear_error — ソケットのエラーまたは直近のエラーコードをクリアする
    • socket_close — Socket クラスのインスタンスを閉じる
    • socket_cmsg_space — メッセージバッファサイズを計算する
    • socket_connect — ソケット上の接続を初期化する
    • socket_create — ソケット（通信時の終端）を作成する
    • socket_create_listen — 接続を受けつけるためにポートにソケットをオープンする
    • socket_create_pair — 区別できないソケットの組を作成し、配列に保存する
    • socket_export_stream — ソケットをカプセル化したストリームに、ソケットをエクスポートする
    • socket_get_option — ソケットのオプションを取得する
    • socket_getopt — socket_get_option のエイリアス
    • socket_getpeername — 指定したソケットのリモート側に問い合わせる
    • socket_getsockname — 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
    • socket_import_stream — ストリームをインポートする
    • socket_last_error — ソケットの直近のエラーを返す
    • socket_listen — ソケット上で接続待ち(listen)する
    • socket_read — ソケットから最大バイト長まで読みこむ
    • socket_recv — 接続したソケットからデータを受信する
    • socket_recvfrom — 接続しているかどうかによらず、ソケットからデータを受信する
    • socket_recvmsg — メッセージを読む
    • socket_select — 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する
    • socket_send — 接続したソケットにデータを送信する
    • socket_sendmsg — メッセージを送信する
    • socket_sendto — 接続しているかどうかによらずソケットにメッセージを送信する
    • socket_set_block — ソケットのブロッキングモードを設定する
    • socket_set_nonblock — ソケットリソースを非ブロックモードに設定する
    • socket_set_option — ソケットのオプションを設定する
    • socket_setopt — socket_set_option のエイリアス
    • socket_shutdown — 受信、送信、または送受信用のソケットをシャットダウンする
    • socket_strerror — ソケットエラーの内容を文字列として返す
    • socket_write — ソケットに書き込む
    • socket_wsaprotocol_info_export — WSAPROTOCOL_INFO 構造体をエクスポートする
    • socket_wsaprotocol_info_import — 別のプロセスからソケットをインポートする
    • socket_wsaprotocol_info_release — エクスポートした WSAPROTOCOL_INF 構造体を解放する
  • Socket — Socket クラス
  • AddressInfo — AddressInfo クラス


はじめに

ソケット拡張モジュールは、一般的な BSD ソケットに基づくソケット通信に関する低レベルインターフェイスを実装し、 クライアントだけでなく、 ソケットサーバーとして動作させることが可能となります。

より一般的なクライアントサイドのソケットインターフェイスについては、
stream_socket_client()、
stream_socket_server()、
fsockopen() および
pfsockopen() を参照ください。

ここで説明するソケット関数を使用する場合、多くの関数は C 言語に同じ名前の関数が存在しますが、 しばしば定義が異なっていることに注意してください。 混乱を避けるには、説明をよく読んでください。

このようにソケットプログラミングと異なっている点はありますが、 それでも有用な多くの Unix man ページを参照することができます。 Web 上に C 言語のソケットプログラミングのチュートリアル情報が存在し、 その多くは、若干の修正により、 PHP におけるソケットプログラミングに適用することが可能です。 » Unix Socket FAQ が、 手始めとして適しているでしょう。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • ソケット
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • リソース型


インストール手順

ここに既述されたソケット関数は PHP 拡張モジュールの一部であり、 コンパイル時に configure にオプション --enable-sockets を指定することにより 使用可能となります。


リソース型

PHP 8.0.0 より前のバージョンでは、
socket_accept(), socket_import_stream(),
socket_addrinfo_connect(), socket_addrinfo_bind(),
socket_create_listen(), socket_wsaprotocol_info_import() および
socket_create() はソケットリソースを返していました。

PHP 8.0.0 より前のバージョンでは、 socket_addrinfo_lookup() は AddressInfo リソースの配列を返していました。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

AF_UNIX (int)
Unixドメイン中のファイルシステムパス名を示す、 ソケットアドレスファミリです。
AF_INET (int)
インターネットドメインにおける、IPv4 のソケットアドレスファミリです。
AF_INET6 (int)
インターネットドメインにおける、IPv6 のソケットアドレスファミリです。 IPv6 サポートつきでコンパイルした場合にのみ使用可能です。
AF_DIVERT (int)
PHP 8.3.0 以降で利用可能(FreeBSD のみ)
SOCK_STREAM (int)
SOCK_DGRAM (int)
SOCK_RAW (int)
SOCK_SEQPACKET (int)
SOCK_RDM (int)
MSG_OOB (int)
MSG_WAITALL (int)
MSG_PEEK (int)
MSG_DONTROUTE (int)
MSG_EOR (int)
Windows プラットフォームでは使用できません。
MSG_EOF (int)
Windows プラットフォームでは使用できません。
MSG_ZEROCOPY (int)
PHP 8.2.0 以降で利用可能。
SO_DEBUG (int)
SO_REUSEADDR (int)
SO_REUSEPORT (int)
この定数は、ソケットオプション SO_REUSEPORT に対応したプラットフォーム上でだけ使えます。 Linux, macOS や *BSD はこのソケットオプションに対応していますが、 Windows は対応していません。
SO_KEEPALIVE (int)
SO_DONTROUTE (int)
SO_LINGER (int)
SO_BROADCAST (int)
SO_OOBINLINE (int)
SO_SNDBUF (int)
SO_RCVBUF (int)
SO_SNDLOWAT (int)
SO_RCVLOWAT (int)
SO_SNDTIMEO (int)
SO_RCVTIMEO (int)
SO_TYPE (int)
SO_ERROR (int)
SO_ZEROCOPY (int)
PHP 8.2.0 以降で利用可能。
TCP_NODELAY (int)
Nagle TCP アルゴリズムを無効にするために使用します。
TCP_KEEPCNT (int)
PHP 8.2.0 以降で利用可能。
TCP_KEEPIDLE (int)
PHP 8.2.0 以降で利用可能。
TCP_KEEPINTVL (int)
PHP 8.2.0 以降で利用可能。
TCP_KEEPALIVE (int)
PHP 8.2.0 以降で利用可能。
TCP_NOTSENT_LOWAT (int)
PHP 8.2.0 以降で利用可能。
SO_MARK (int)
PHP 8.1.0 以降で利用可能。
SO_USER_COOKIE (int)
PHP 8.1.0 以降で利用可能。
SO_RTABLE (int)
PHP 8.2.0 以降で利用可能。
SO_ACCEPTFILTER (int)
PHP 8.1.0 以降で利用可能。
SO_DONTTRUNC (int)
PHP 8.1.0 以降で利用可能。
SO_WANTMORE (int)
PHP 8.1.0 以降で利用可能。
SO_INCOMING_CPU (int)
PHP 8.2.0 以降で利用可能。
SO_MEMINFO (int)
PHP 8.2.0 以降で利用可能。
SO_BPF_EXTENSIONS (int)
PHP 8.2.0 以降で利用可能。
SO_SETFIB (int)
PHP 8.2.0 以降で利用可能。
SO_ATTACH_REUSEPORT_CBPF (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
SO_DETACH_BPF (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
SO_DETACH_FILTER (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
SO_RERROR (int)
PHP 8.3.0 以降で利用可能(NetBSD のみ)。
SO_ZEROIZE (int)
PHP 8.3.0 以降で利用可能(OpenBSD のみ)。
SO_SPLICE (int)
PHP 8.3.0 以降で利用可能(OpenBSD のみ)。
SO_REUSEPORT_LB (int)
PHP 8.3.0 以降で利用可能(FreeBSD のみ)。
SOL_FILTER (int)
PHP 8.2.0 以降で利用可能。
SOL_UDPLITE (int)
PHP 8.3.0 以降で利用可能。
UDPLITE_RECV_CSCOV (int)
PHP 8.3.0 以降で利用可能。
UDPLITE_SEND_CSCOV (int)
PHP 8.3.0 以降で利用可能。
TCP_DEFER_ACCEPT (int)
PHP 8.1.0 以降で利用可能。
TCP_CONGESTION (int)
PHP 8.2.0 以降で利用可能。
TCP_QUICKACK (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
TCP_REPAIR (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_DONTFRAG (int)
PHP 8.3.0 以降で利用可能(FreeBSD のみ)。
IP_MTU_DISCOVER (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_PMTUDISC_DO (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_PMTUDISC_DONT (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_PMTUDISC_WANT (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_PMTUDISC_PROBE (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_PMTUDISC_INTERFACE (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_PMTUDISC_OMIT (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
IP_BIND_ADDRESS_NO_PORT (int)
PHP 8.3.0 以降で利用可能(Linux のみ)。
SOL_SOCKET (int)
PHP_NORMAL_READ (int)
PHP_BINARY_READ (int)
SOL_TCP (int)
SOL_UDP (int)

以下の定数は Windows でのみ定義されています。

SOCKET_EINTR (int)
Interrupted system call.
SOCKET_EBADF (int)
Bad file descriptor number.
SOCKET_EACCES (int)
Permission denied.
SOCKET_EFAULT (int)
Bad address.
SOCKET_EINVAL (int)
Invalid argument.
SOCKET_EMFILE (int)
Too many open files.
SOCKET_ENAMETOOLONG (int)
File name too long.
SOCKET_ENOTEMPTY (int)
Directory not empty.
SOCKET_ELOOP (int)
Too many symbolic links encountered.
SOCKET_EWOULDBLOCK (int)
Operation would block.
SOCKET_EREMOTE (int)
Object is remote.
SOCKET_EUSERS (int)
Too many users.
SOCKET_ENOTSOCK (int)
Socket operation on non-socket.
SOCKET_EDESTADDRREQ (int)
Destination address required.
SOCKET_EMSGSIZE (int)
Message too long.
SOCKET_EPROTOTYPE (int)
Protocol wrong type for socket.
SOCKET_EPROTONOSUPPORT (int)
Protocol not supported.
SOCKET_ESOCKTNOSUPPORT (int)
Socket type not supported.
SOCKET_EOPNOTSUPP (int)
Operation not supported on transport endpoint.
SOCKET_EPFNOSUPPORT (int)
Protocol family not supported.
SOCKET_EAFNOSUPPORT (int)
Address family not supported by protocol.
SOCKET_EADDRNOTAVAIL (int)
Cannot assign requested address.
SOCKET_ENETDOWN (int)
Network is down.
SOCKET_ENETUNREACH (int)
Network is unreachable.
SOCKET_ENETRESET (int)
Network dropped connection because of reset.
SOCKET_ECONNABORTED (int)
Software caused connection abort.
SOCKET_ECONNRESET (int)
Connection reset by peer.
SOCKET_ENOBUFS (int)
No buffer space available.
SOCKET_EISCONN (int)
Transport endpoint is already connected.
SOCKET_ENOTCONN (int)
Transport endpoint is not connected.
SOCKET_ESHUTDOWN (int)
Cannot send after transport endpoint shutdown.
SOCKET_ETIMEDOUT (int)
Connection timed out.
SOCKET_ECONNREFUSED (int)
Connection refused.
SOCKET_EHOSTDOWN (int)
Host is down.
SOCKET_EHOSTUNREACH (int)
No route to host.
SOCKET_EALREADY (int)
Operation already in progress.
SOCKET_EINPROGRESS (int)
Operation now in progress.

The following constants are only defined under Windows.

SOCKET_ENOPROTOOPT (int)
SOCKET_EADDRINUSE (int)
SOCKET_ETOOMYREFS (int)
SOCKET_EPROCLIM (int)
SOCKET_EDUOT (int)
SOCKET_ESTALE (int)
SOCKET_EDISCON (int)
SOCKET_SYSNOTREADY (int)
SOCKET_VERNOTSUPPORTED (int)
SOCKET_NOTINITIALISED (int)
SOCKET_HOST_NOT_FOUND (int)
SOCKET_TRY_AGAIN (int)
SOCKET_NO_RECOVERY (int)
SOCKET_NO_DATA (int)
SOCKET_NO_ADDRESS (int)

以下の定数は UNIX ライクなプラットフォームでのみ使用可能です。 各定数は、そのプラットフォーム上で同等のものが定義されている場合にのみ定義されています。

SOCKET_EPERM (int)
Operation not permitted.
SOCKET_ENOENT (int)
No such file or directory.
SOCKET_EIO (int)
I/O error.
SOCKET_ENXIO (int)
No such device or address.
SOCKET_E2BIG (int)
Arg list too long.
SOCKET_EAGAIN (int)
Try again.
SOCKET_ENOMEM (int)
Out of memory.
SOCKET_ENOTBLK (int)
Block device required.
SOCKET_EBUSY (int)
Device or resource busy.
SOCKET_EEXIST (int)
File exists.
SOCKET_EXDEV (int)
Cross-device link.
SOCKET_ENODEV (int)
No such device.
SOCKET_ENOTDIR (int)
Not a directory.
SOCKET_EISDIR (int)
Is a directory.
SOCKET_ENFILE (int)
File table overflow.
SOCKET_ENOTTY (int)
Not a typewriter.
SOCKET_ENOSPC (int)
No space left on device.
SOCKET_ESPIPE (int)
Illegal seek.
SOCKET_EROFS (int)
Read-only file system.
SOCKET_EMLINK (int)
Too many links.
SOCKET_EPIPE (int)
Broken pipe.
SOCKET_ENOLCK (int)
No record locks available.
SOCKET_ENOSYS (int)
Function not implemented.
SOCKET_ENOMSG (int)
No message of desired type.
SOCKET_EIDRM (int)
Identifier removed.
SOCKET_ECHRNG (int)
Channel number out of range.
SOCKET_EL2NSYNC (int)
Level 2 not synchronized.
SOCKET_EL3HLT (int)
Level 3 halted.
SOCKET_EL3RST (int)
Level 3 reset.
SOCKET_ELNRNG (int)
Link number out of range.
SOCKET_EUNATCH (int)
Protocol driver not attached.
SOCKET_ENOCSI (int)
No CSI structure available.
SOCKET_EL2HLT (int)
Level 2 halted.
SOCKET_EBADE (int)
Invalid exchange.
SOCKET_EBADR (int)
Invalid request descriptor.
SOCKET_EXFULL (int)
Exchange full.
SOCKET_ENOANO (int)
No anode.
SOCKET_EBADRQC (int)
Invalid request code.
SOCKET_EBADSLT (int)
Invalid slot.
SOCKET_ENOSTR (int)
Device not a stream.
SOCKET_ENODATA (int)
No data available.
SOCKET_ETIME (int)
Timer expired.
SOCKET_ENOSR (int)
Out of streams resources.
SOCKET_ENONET (int)
Machine is not on the network.
SOCKET_ENOLINK (int)
Link has been severed.
SOCKET_EADV (int)
Advertise error.
SOCKET_ESRMNT (int)
Srmount error.
SOCKET_ECOMM (int)
Communication error on send.
SOCKET_EPROTO (int)
Protocol error.
SOCKET_EMULTIHOP (int)
Multihop attempted.
SOCKET_EBADMSG (int)
Not a data message.
SOCKET_ENOTUNIQ (int)
Name not unique on network.
SOCKET_EBADFD (int)
File descriptor in bad state.
SOCKET_EREMCHG (int)
Remote address changed.
SOCKET_ERESTART (int)
Interrupted system call should be restarted.
SOCKET_ESTRPIPE (int)
Streams pipe error.
SOCKET_EPROTOOPT (int)
Protocol not available.
SOCKET_ADDRINUSE (int)
Address already in use.
SOCKET_ETOOMANYREFS (int)
Too many references: cannot splice.
SOCKET_EISNAM (int)
Is a named type file.
SOCKET_EREMOTEIO (int)
Remote I/O error.
SOCKET_EDQUOT (int)
Quota exceeded.
SOCKET_ENOMEDIUM (int)
No medium found.
SOCKET_EMEDIUMTYPE (int)
Wrong medium type.
SCM_RIGHTS (int)
Send or receive a set of open file descriptors from another process.
SCM_CREDENTIALS (int)
SCM_CREDS (int)
PHP 8.2.0 以降で利用可能。
SCM_CREDS2 (int)
PHP 8.2.0 以降で利用可能。
LOCAL_CREDS (int)
PHP 8.2.0 以降で利用可能。
LOCAL_CREDS_PERSISTENT (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_OFF (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_PROTOCOL (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_PKTTYPE (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_IFINDEX (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_NLATTR (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_NLATTR_NEST (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_MARK (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_QUEUE (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_HATYPE (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_RXHASH (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_CPU (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_ALU_XOR_X (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_VLAN_TAG (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_VLAN_TAG_PRESENT (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_PAY_OFFSET (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_RANDOM (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_VLAN_TPID (int)
PHP 8.2.0 以降で利用可能。
SKF_AD_MAX (int)
PHP 8.2.0 以降で利用可能。
AI_ADDRCONFIG (int)
AI_ALL (int)
AI_CANONIDN (int)
AI_CANONNAME (int)
AI_IDN (int)
AI_NUMERICHOST (int)
AI_NUMERICSERV (int)
AI_PASSIVE (int)
AI_V4MAPPED (int)
FIL_ATTACH (int)
FIL_DETACH (int)
IPPROTO_IP (int)
IPPROTO_IPV6 (int)
IPV6_HOPLIMIT (int)
IPV6_MULTICAST_HOPS (int)
IPV6_MULTICAST_IF (int)
IPV6_MULTICAST_LOOP (int)
IPV6_PKTINFO (int)
IPV6_RECVHOPLIMIT (int)
IPV6_RECVPKTINFO (int)
IPV6_RECVTCLASS (int)
IPV6_TCLASS (int)
IPV6_UNICAST_HOPS (int)
IPV6_V6ONLY (int)
IP_MULTICAST_IF (int)
IP_MULTICAST_LOOP (int)
IP_MULTICAST_TTL (int)
MCAST_BLOCK_SOURCE (int)
MCAST_JOIN_GROUP (int)
MCAST_JOIN_SOURCE_GROUP (int)
MCAST_LEAVE_GROUP (int)
MCAST_LEAVE_SOURCE_GROUP (int)
MCAST_UNBLOCK_SOURCE (int)
MSG_CMSG_CLOEXEC (int)
MSG_CONFIRM (int)
MSG_CTRUNC (int)
MSG_DONTWAIT (int)
MSG_ERRQUEUE (int)
MSG_MORE (int)
MSG_NOSIGNAL (int)
MSG_TRUNC (int)
MSG_WAITFORONE (int)
SOL_LOCAL (int)
SOMAXCONN (int)
SO_BINDTODEVICE (int)
SO_FAMILY (int)
SO_LABEL (int)
SO_LISTENQLEN (int)
SO_LISTENQLIMIT (int)
SO_PASSCRED (int)
SO_PEERLABEL (int)


例

例1 ソケットの例: 簡易 TCP/IP サーバー

この例は、簡単な応答サーバーです。変数 address と port を設定と実行環境に合うように変更してください。 このサーバーに次のようなコマンドで接続することが可能です。 : telnet 192.168.1.53 10000 (ただし、 アドレスとポートは設定に合わせます)入力したものは、サーバー側の出力となり、 エコーバックされます。接続を閉じるには、'quit' を入力します。

#!/usr/local/bin/php -q
<?php
error_reporting(E_ALL);

/* Allow the script to hang around waiting for connections. */
set_time_limit(0);

/* Turn on implicit output flushing so we see what we're getting
* as it comes in. */
ob_implicit_flush();

$address = '192.168.1.53';
$port = 10000;

if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}

if (socket_bind($sock, $address, $port) === false) {
echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}

if (socket_listen($sock, 5) === false) {
echo "socket_listen() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}

do {
if (($msgsock = socket_accept($sock)) === false) {
echo "socket_accept() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
break;
}
/* Send instructions. */
$msg = "\nWelcome to the PHP Test Server. \n" .
"To quit, type 'quit'. To shut down the server type 'shutdown'.\n";
socket_write($msgsock, $msg, strlen($msg));

do {
if (false === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) {
echo "socket_read() failed: reason: " . socket_strerror(socket_last_error($msgsock)) . "\n";
break 2;
}
if (!$buf = trim($buf)) {
continue;
}
if ($buf == 'quit') {
break;
}
if ($buf == 'shutdown') {
socket_close($msgsock);
break 2;
}
$talkback = "PHP: You said '$buf'.\n";
socket_write($msgsock, $talkback, strlen($talkback));
echo "$buf\n";
} while (true);
socket_close($msgsock);
} while (true);

socket_close($sock);
?>

例2 ソケットの例: 簡易 TCP/IP クライアント

この例は、簡単な一回限りの HTTP クライアントです。ここでは、 あるページに接続して HEAD リクエストを送信し、応答を出力た後で終了します。

<?php
error_reporting(E_ALL);

echo "<h2>TCP/IP Connection</h2>\n";

/* Get the port for the WWW service. */
$service_port = getservbyname('www', 'tcp');

/* Get the IP address for the target host. */
$address = gethostbyname('www.example.com');

/* Create a TCP/IP socket. */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
echo "OK.\n";
}

echo "Attempting to connect to '$address' on port '$service_port'...";
$result = socket_connect($socket, $address, $service_port);
if ($result === false) {
echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
echo "OK.\n";
}

$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: www.example.com\r\n";
$in .= "Connection: Close\r\n\r\n";
$out = '';

echo "Sending HTTP HEAD request...";
socket_write($socket, $in, strlen($in));
echo "OK.\n";

echo "Reading response:\n\n";
while ($out = socket_read($socket, 2048)) {
echo $out;
}

echo "Closing socket...";
socket_close($socket);
echo "OK.\n\n";
?>


ソケットのエラー

ソケット拡張モジュールは、 強力な BSD ソケットへの有用なインターフェイスを提供するために作成されました。 関数は、Win32 および Unix の実装において等しく動作するように注意が払われています。 ソケット関数の多くは特定の条件で失敗し、エラーを記述する E_WARNING メッセージを出力します。 これは、時々開発者が望まない時に発生することがあります。例えば、 関数 socket_read() は突然 E_WARNING メッセージを出力する可能性があります。 これは、予測しない接続断が発生したためです。 @ 演算子により警告出力を抑制し、 socket_last_error() 関数によりアプリケーション内でエラーコードを取得することが一般に行われています。 エラーを記述する文字列を取得するためにこのエラーコードを指定して socket_strerror() 関数をコールすることが可能です。 詳細は、この関数の説明を参照ください。

注意:

E_WARNING メッセージは、 ソケット拡張モジュールにより英語で生成されますが、取得されるエラーメッセージは、 現在のロケール (LC_MESSAGES) に依存します。

Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet


ソケット 関数

目次

  • socket_accept — ソケットへの接続を許可する
  • socket_addrinfo_bind — 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_connect — 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_explain — addrinfo に関する情報を取得する
  • socket_addrinfo_lookup — 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
  • socket_atmark — ソケットに帯域外マークが付けられているかを調べる
  • socket_bind — ソケットに名前をバインドする
  • socket_clear_error — ソケットのエラーまたは直近のエラーコードをクリアする
  • socket_close — Socket クラスのインスタンスを閉じる
  • socket_cmsg_space — メッセージバッファサイズを計算する
  • socket_connect — ソケット上の接続を初期化する
  • socket_create — ソケット（通信時の終端）を作成する
  • socket_create_listen — 接続を受けつけるためにポートにソケットをオープンする
  • socket_create_pair — 区別できないソケットの組を作成し、配列に保存する
  • socket_export_stream — ソケットをカプセル化したストリームに、ソケットをエクスポートする
  • socket_get_option — ソケットのオプションを取得する
  • socket_getopt — socket_get_option のエイリアス
  • socket_getpeername — 指定したソケットのリモート側に問い合わせる
  • socket_getsockname — 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
  • socket_import_stream — ストリームをインポートする
  • socket_last_error — ソケットの直近のエラーを返す
  • socket_listen — ソケット上で接続待ち(listen)する
  • socket_read — ソケットから最大バイト長まで読みこむ
  • socket_recv — 接続したソケットからデータを受信する
  • socket_recvfrom — 接続しているかどうかによらず、ソケットからデータを受信する
  • socket_recvmsg — メッセージを読む
  • socket_select — 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する
  • socket_send — 接続したソケットにデータを送信する
  • socket_sendmsg — メッセージを送信する
  • socket_sendto — 接続しているかどうかによらずソケットにメッセージを送信する
  • socket_set_block — ソケットのブロッキングモードを設定する
  • socket_set_nonblock — ソケットリソースを非ブロックモードに設定する
  • socket_set_option — ソケットのオプションを設定する
  • socket_setopt — socket_set_option のエイリアス
  • socket_shutdown — 受信、送信、または送受信用のソケットをシャットダウンする
  • socket_strerror — ソケットエラーの内容を文字列として返す
  • socket_write — ソケットに書き込む
  • socket_wsaprotocol_info_export — WSAPROTOCOL_INFO 構造体をエクスポートする
  • socket_wsaprotocol_info_import — 別のプロセスからソケットをインポートする
  • socket_wsaprotocol_info_release — エクスポートした WSAPROTOCOL_INF 構造体を解放する


ソケットへの接続を許可する

  • ≪ ソケット 関数
  • socket_addrinfo_bind ≫
  • PHP Manual
  • ソケット 関数
  • ソケットへの接続を許可する

socket_accept

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_accept — ソケットへの接続を許可する

説明

socket_accept(Socket $socket): Socket|false

socket_create() を使用してソケット socket を作成した後、 socket_bind() で名前に関連付け、 socket_listen() で接続をモニタします。この関数は、 このソケットへの接続を許可します。接続に成功すると、新しい Socket クラスのインスタンスが返されます。 このインスタンスは通信の際に使用されます。 ソケット上に複数の接続がキューで待っている場合、最初の接続が使用 されます。接続待ちがない場合、socket_accept() は接続が存在するまでブロックされます。 socket が socket_set_blocking() または socket_set_nonblock() により非ブロックモードで 作成された場合、false が返されます。

socket_accept() により返された Socket クラスのインスタンスは、 新規接続を許可するために使用することはできません。この場合でも 元の接続待ちのソケット socket は オープンされたままであり、再使用可能です。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

戻り値

成功した場合に新しい Socket クラスのインスタンスを、 エラー時に false を返します。 実際のエラーコードは、socket_last_error() を コールすることで取得可能です。このコードを socket_strerror() に渡すことで、 エラーの内容を文字列で取得することが可能です。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

参考

  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_bind() - ソケットに名前をバインドする
  • socket_strerror() - ソケットエラーの内容を文字列として返す


与えられた addrinfo から、ソケットを作成してバインドする

  • ≪ socket_accept
  • socket_addrinfo_connect ≫
  • PHP Manual
  • ソケット 関数
  • 与えられた addrinfo から、ソケットを作成してバインドする

socket_addrinfo_bind

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_bind — 与えられた addrinfo から、ソケットを作成してバインドする

説明

socket_addrinfo_bind(AddressInfo $address): Socket|false

Socket クラスのインスタンスを作成し、 与えられた AddressInfo インスタンスにバインドします。 この関数の戻り値は socket_listen() で使えます。

パラメータ

address

socket_addrinfo_lookup() 関数で作られた AddressInfo クラスのインスタンス。

戻り値

成功したときは Socket クラスのインスタンスを返します。 失敗したときは null を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。
8.0.0 | address は、AddressInfo クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_addrinfo_connect() - 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_explain() - addrinfo に関する情報を取得する
  • socket_addrinfo_lookup() - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
  • socket_listen() - ソケット上で接続待ち(listen)する


与えられた addrinfo から、ソケットを作って接続する

  • ≪ socket_addrinfo_bind
  • socket_addrinfo_explain ≫
  • PHP Manual
  • ソケット 関数
  • 与えられた addrinfo から、ソケットを作って接続する

socket_addrinfo_connect

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_connect — 与えられた addrinfo から、ソケットを作って接続する

説明

socket_addrinfo_connect(AddressInfo $address): Socket|false

Socket クラスのインスタンスを作り、 与えられた AddressInfo インスタンスに接続します。 この関数の戻り値で、残りのソケット関数が使えます。

パラメータ

address

socket_addrinfo_lookup() 関数で作られた AddressInfo クラスのインスタンス。

戻り値

成功したときは Socket クラスのインスタンスを返します。 失敗したときは null を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。
8.0.0 | address は、AddressInfo クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_explain() - addrinfo に関する情報を取得する
  • socket_addrinfo_lookup() - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する


addrinfo に関する情報を取得する

  • ≪ socket_addrinfo_connect
  • socket_addrinfo_lookup ≫
  • PHP Manual
  • ソケット 関数
  • addrinfo に関する情報を取得する

socket_addrinfo_explain

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_explain — addrinfo に関する情報を取得する

説明

socket_addrinfo_explain(AddressInfo $address): array

socket_addrinfo_explain() 関数は、下層にある addrinfo 構造体の内容を公開します。

パラメータ

address

socket_addrinfo_lookup() で作られた AddressInfo クラスのインスタンス。

戻り値

addrinfo 構造体に入っているフィールドが含まれた配列を返します。

変更履歴

バージョン | 説明
8.0.0 | address は、AddressInfo クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_connect() - 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_lookup() - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する


与えられたホスト名に関する getaddrinfo の内容を配列で取得する

  • ≪ socket_addrinfo_explain
  • socket_atmark ≫
  • PHP Manual
  • ソケット 関数
  • 与えられたホスト名に関する getaddrinfo の内容を配列で取得する

socket_addrinfo_lookup

(PHP 7 >= 7.2.0, PHP 8)

socket_addrinfo_lookup — 与えられたホスト名に関する getaddrinfo の内容を配列で取得する

説明

socket_addrinfo_lookup(string $host, ?string $service = null, array $hints = []): array|false

host に接続できる別のやり方を探します。 この関数が返す配列は socket_addrinfo_bind() を使ってバインドできる AddressInfo クラスのインスタンスが含まれています。

パラメータ

host

探す対象のホスト名

service

接続するサービス。service が数値形式の文字列の場合、 ポート番号に翻訳されます。 それ以外の場合、ネットワークサービス名に翻訳されます。 これは、オペレーティングシステムによってポート番号にマップされます。

hints

アドレスを選択する条件を与えるヒント。 getaddrinfo によって定義されるヒントを指定できます。

戻り値

socket_addrinfo_()* 関数で使える AddressInfo クラスのインスタンスの配列を返します。 失敗した場合、false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は AddressInfo クラスのインスタンスの配列を返すようになりました。 これより前のバージョンでは、リソースの配列を返していました。
8.0.0 | service は、nullable になりました。

参考

  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする
  • socket_addrinfo_connect() - 与えられた addrinfo から、ソケットを作って接続する
  • socket_addrinfo_explain() - addrinfo に関する情報を取得する


ソケットに帯域外マークが付けられているかを調べる

  • ≪ socket_addrinfo_lookup
  • socket_bind ≫
  • PHP Manual
  • ソケット 関数
  • ソケットに帯域外マークが付けられているかを調べる

socket_atmark

(PHP 8 >= 8.3.0, PHP 8)

socket_atmark — ソケットに帯域外マークが付けられているかを調べる

説明

socket_atmark(Socket $socket): bool

socket に帯域外マークが付けられているかを調べます。

パラメータ

socket

socket_create() で作成した Socket のインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ソースアドレスを設定するために socket_atmark() を使う例

<?php
// Create a new socket
$sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
var_dump(socket_atmark($sock));
// Close
socket_close($sock);
?>

参考

  • socket_connect() - ソケット上の接続を初期化する
  • socket_create() - ソケット（通信時の終端）を作成する


ソケットに名前をバインドする

  • ≪ socket_atmark
  • socket_clear_error ≫
  • PHP Manual
  • ソケット 関数
  • ソケットに名前をバインドする

socket_bind

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_bind — ソケットに名前をバインドする

説明

socket_bind(Socket $socket, string $address, int $port = 0): bool

address で指定した名前を socket で指定したソケットにバインドします。 これは、socket_connect() あるいは socket_listen() を使用して接続が確立される前に行われます。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

address

ソケットの種類が AF_INET の場合、 address はドットで 4 つに区切られた表記 （例: 127.0.0.1）の IP アドレス。

ソケットの種類が AF_UNIX の場合、 address は Unix ドメインソケット （例: /tmp/my.sock）。

port（オプション）

パラメータ port は AF_INET ソケットにバインドする場合にのみ使用され、 接続するリモートホストのポートを指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラーコードは socket_last_error() により取得できます。 このコードを socket_strerror() に渡すことにより、 エラー内容を表すテキストを得ることができます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_bind() を使用してソースアドレスを指定する

<?php
// 新しいソケットを作成する
$sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

// コンピュータが所有する IP アドレスリストの例
$sourceips['kevin'] = '127.0.0.1';
$sourceips['madcoder'] = '127.0.0.2';

// ソースアドレスをバインドする
socket_bind($sock, $sourceips['madcoder']);

// 接続先アドレスと接続する
socket_connect($sock, '127.0.0.1', 80);

// 書き込む
$request = 'GET / HTTP/1.1' . "\r\n" .
'Host: example.com' . "\r\n\r\n";
socket_write($sock, $request);

// 閉じる
socket_close($sock);

?>

注意

注意:

この関数は、 socket_connect() の前に実行されている必要があります。

注意:

Windows 9x/ME 互換性の注意: マシンに属しないアドレスにソケットをバインドしようとした場合、 socket_last_error() は 無効なエラーコードを返すことがあります。

参考

  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


ソケットのエラーまたは直近のエラーコードをクリアする

  • ≪ socket_bind
  • socket_close ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのエラーまたは直近のエラーコードをクリアする

socket_clear_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

socket_clear_error — ソケットのエラーまたは直近のエラーコードをクリアする

説明

socket_clear_error(?Socket $socket = null): void

この関数は、指定したソケットまたは直近のグローバルなソケットエラー のエラーコードをクリアします。

この関数により、 ソケットまたは直近のグローバルな拡張エラーコードとなる エラーコードの値を明示的にリセットすることが可能になります。 これは、エラーが発生したかどうかをアプリケーション内で検出する際に有用です。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | socket は、nullable になりました。

参考

  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


Socket クラスのインスタンスを閉じる

  • ≪ socket_clear_error
  • socket_cmsg_space ≫
  • PHP Manual
  • ソケット 関数
  • Socket クラスのインスタンスを閉じる

socket_close

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_close — Socket クラスのインスタンスを閉じる

説明

socket_close(Socket $socket): void

socket_close() は、 socket で指定した Socket クラスのインスタンスを閉じます。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_strerror() - ソケットエラーの内容を文字列として返す


メッセージバッファサイズを計算する

  • ≪ socket_close
  • socket_connect ≫
  • PHP Manual
  • ソケット 関数
  • メッセージバッファサイズを計算する

socket_cmsg_space

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

socket_cmsg_space — メッセージバッファサイズを計算する

説明

socket_cmsg_space(int $level, int $type, int $num = 0): ?int

付随データを受信するために確保するバッファのサイズを計算します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

level

type

戻り値

参考

  • socket_recvmsg() - メッセージを読む
  • socket_sendmsg() - メッセージを送信する


ソケット上の接続を初期化する

  • ≪ socket_cmsg_space
  • socket_create ≫
  • PHP Manual
  • ソケット 関数
  • ソケット上の接続を初期化する

socket_connect

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_connect — ソケット上の接続を初期化する

説明

socket_connect(Socket $socket, string $address, ?int $port = null): bool

Socket クラスのインスタンスを用いて、 address への接続を初期化します。 このインスタンスは、socket_create() で作成した有効な Socket クラスのインスタンスである必要があります。

パラメータ

socket

socket_create() 関数で生成した Socket クラスのインスタンス。

address

パラメータ address には、 socket の種類が AF_INET の場合はドット区切り表記の IPv4 アドレス (例: 127.0.0.1)、 IPv6 サポートが有効で socket の種類が AF_INET6 の場合は IPv6 アドレス (例: ::1)、 AF_UNIX の場合は Unix ドメインソケットのパス名を指定します。

port

パラメータ port は AF_INET ソケット あるいは AF_INET6 に接続する場合にのみ必須となり、 接続するリモートホストのポートを指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 エラーコードは、 socket_last_error() により取得できます。 このコードを socket_strerror() に渡すことにより、 エラー内容を表すテキストを得ることができます。

注意:

ソケットが非ブロッキングモードの場合、この関数は false を返し、エラー Operation now in progress を発生させます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | port は、nullable になりました。

参考

  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


ソケット（通信時の終端）を作成する

  • ≪ socket_connect
  • socket_create_listen ≫
  • PHP Manual
  • ソケット 関数
  • ソケット（通信時の終端）を作成する

socket_create

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_create — ソケット（通信時の終端）を作成する

説明

socket_create(int $domain, int $type, int $protocol): Socket|false

通信のエンドポイント(終端)と呼ばれることもある Socket クラスのインスタンスを作成し、 返します。典型的なネットワーク接続は、2つのソケットから成り立ちます。 このとき、片方はクライアント、もう片方はサーバーの役割をします。

パラメータ

domain

パラメータ domain には、 ソケットが利用するプロトコルファミリーを指定します。

指定可能なアドレス/プロトコルファミリーの一覧
ドメイン | 説明
AF_INET | IPv4 インターネットプロトコル。 このプロトコルファミリーに属するプロトコルとしてよく知られているのは、 TCP や UDP です。
AF_INET6 | IPv6 インターネットプロトコル。TCP と UDP が、このプロトコルファミリーで一般的なプロトコルです。
AF_UNIX | ローカルでのコミュニケーションに用いられるプロトコルファミリーです。 高い効率と低いオーバーヘッドを誇るため、IPC (プロセス間通信) でよく使われます。
type

type パラメータは、 ソケットが利用する通信方式を指定します。

利用できるソケットのタイプ
タイプ | 説明
SOCK_STREAM | このタイプでは、時系列的、高信頼性、全二重、接続型のバイトストリームが利用できます。 帯域外のデータ転送メカニズムがサポートされている場合もあります。 TCP プロトコルは、このソケットタイプに基づきます。
SOCK_DGRAM | このタイプでは、データグラム(非接続型で、信頼性の高くない 固定バイト長のメッセージ) がサポートされます。 UDP プロトコルは、このソケットタイプに基づきます。
SOCK_SEQPACKET | このタイプでは、時系列的な、信頼性のある、 双方向の接続指向型の固定長データグラム転送が利用できます。 パケットを消費する側は、一つのパケット全部を一度の read コールで読み込む必要があります。
SOCK_RAW | このタイプでは、素のネットワークプロトコルを操作できます。 この特殊なソケットを使って、どのタイプのプロトコルでもユーザーの手で構築することができます。 よくある使い方として、(ping のような) ICMP リクエストの作成があります。
SOCK_RDM | このタイプでは、信頼に足る、非時系列的なデータグラム転送が利用できます。 ほとんどのオペレーティングシステムでは実装されていないでしょう。
protocol

protocol は、ソケット上の通信で使われる domain で指定されたファミリーに属するプロトコルを指定します。 正しい値は、getprotobyname() を使うことで取得できます。利用したいプロトコルが、TCP または UDP の場合は、定数 SOL_TCP と SOL_UDP を指定することもできます。

一般的なプロトコルの一覧
名称 | 説明
icmp | Internet Control Message Protocol は、主にゲートウェイやホストが、 データグラム通信におけるエラーを報告するのに使われます。 "ping" コマンド (最近のほとんどのオペーレーティングシステムに 搭載されています) が ICMP アプリケーションの一例です。
udp | User Datagram Protocol は、非接続指向の、信頼性の高くない、 固定のレコード長を用いるプロトコルです。このような側面のおかげで、 UDP はプロトコルとして最小限のオーバーへッドしか要求しません。
tcp | Transmission Control Protocol は、信頼性の高い、接続指向かつ ストリーム指向の全二重通信プロトコルです。TCP は、 すべてのパケットが、送信された順序で(時系列的に)受信されることを 保証します。もし、何らかの理由でパケットが通信中に失われた場合、 TCP では、送信先から通知があるまで、パケットが再送信されるように なっています。信頼性とパフォーマンス上の理由から、TCP の実装は、 下層にあるデータグラム通信レイヤーのオクテット幅を 適当な長さに決定します。このため、TCP アプリケーションは、 レコードの全部が一度に転送されない場合も考慮しなければなりません。

戻り値

socket_create() は、 成功時に Socket クラスのインスタンス、 失敗時に false を返します。 実際のエラーコードは、socket_last_error() を コールすることにより取得できます。このエラーコードをさらに socket_strerror()に渡すことにより、 エラーの内容を文字列で取得することが可能です。

エラー / 例外

domain や type に 不正な値が与えられた場合、socket_create() は、これらを それぞれ AF_INET と SOCK_STREAM であるとみなし、E_WARNING メッセージを出します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


接続を受けつけるためにポートにソケットをオープンする

  • ≪ socket_create
  • socket_create_pair ≫
  • PHP Manual
  • ソケット 関数
  • 接続を受けつけるためにポートにソケットをオープンする

socket_create_listen

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_create_listen — 接続を受けつけるためにポートにソケットをオープンする

説明

socket_create_listen(int $port, int $backlog = SOMAXCONN): Socket|false

socket_create_listen() は、 AF_INET 型で すべての ローカルインターフェイスの指定したポート上で新規接続を待ち受ける 新しい Socket クラスのインスタンスを作成します。

この関数は、新規接続のみを受け入れるソケットを作成しやすくするためのものです。

パラメータ

port

すべてのインターフェイスで待ち受けるポート。

backlog

backlog パラメータは、 接続の順番待ちのキューをどれだけの長さまで保持するかを定義します。 SOMAXCONN を backlog パラメータに渡します。詳細な情報は socket_listen() を参照ください。

戻り値

socket_create_listen() は、 成功した場合に新しい Socket クラスのインスタンスを、 エラー時に false を返します。エラーコードは socket_last_error() で取得可能です。このコードを socket_strerror() に渡すと、エラーの詳細が文字列で取得可能です。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

注意

注意:

特定のインターフェイスのみを listen するソケットを作成したい場合は socket_create()、 socket_bind() および socket_listen() を使用します。

参考

  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_create_pair() - 区別できないソケットの組を作成し、配列に保存する
  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


区別できないソケットの組を作成し、配列に保存する

  • ≪ socket_create_listen
  • socket_export_stream ≫
  • PHP Manual
  • ソケット 関数
  • 区別できないソケットの組を作成し、配列に保存する

socket_create_pair

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_create_pair — 区別できないソケットの組を作成し、配列に保存する

説明

socket_create_pair(
int $domain,
int $type,
int $protocol,
array &$pair
): bool

socket_create_pair() は、接続されており区別できない 2 つのソケットを作成し、それを pair に保存します。 この関数は、一般に IPC（InterProcess Communication: プロセス間通信） で使用します。

パラメータ

domain

domain は、ソケットで使用するプロトコルの種類を指定します。 完全な一覧は socket_create() を参照ください。

type

type では、ソケットが使用する通信の形式を選択します。 完全な一覧は socket_create() を参照ください。

protocol

protocol は、指定した domain の中の特定のプロトコルを指定します。これは、返されるソケットとの通信に使用されます。 使用可能な値の名前は getprotobyname() で取得可能です。もし要求されるプロトコルが TCP あるいは UDP の場合、 対応する定数 SOL_TCP および SOL_UDP も使用可能です。

サポートするプロトコルの完全な一覧は socket_create() を参照ください。

pair

2 つの Socket クラスのインスタンスが格納される配列への参照。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | pair は、 Socket クラスのインスタンスの配列へのリファレンスになりました。 これより前のバージョンでは、リソースの配列へのリファレンスでした。

例

例1 socket_create_pair() の例

<?php
$sockets = array();

/* Windows では AF_INET を使う必要があります */
$domain = (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN' ? AF_INET : AF_UNIX);

/* ソケットの組の設定 */
if (socket_create_pair($domain, SOCK_STREAM, 0, $sockets) === false) {
echo "socket_create_pair failed. Reason: ".socket_strerror(socket_last_error());
}
/* データの送受信 */
if (socket_write($sockets[0], "ABCdef123\n", strlen("ABCdef123\n")) === false) {
echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($sockets[0]));
}
if (($data = socket_read($sockets[1], strlen("ABCdef123\n"), PHP_BINARY_READ)) === false) {
echo "socket_read() failed. Reason: ".socket_strerror(socket_last_error($sockets[1]));
}
var_dump($data);

/* ソケットのクローズ */
socket_close($sockets[0]);
socket_close($sockets[1]);
?>

例2 socket_create_pair() での IPC の例

<?php
$ary = array();
$strone = 'Message From Parent.';
$strtwo = 'Message From Child.';

if (socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $ary) === false) {
echo "socket_create_pair() failed. Reason: ".socket_strerror(socket_last_error());
}
$pid = pcntl_fork();
if ($pid == -1) {
echo 'プロセスを fork できません。';
} elseif ($pid) {
/* 親プロセス */
socket_close($ary[0]);
if (socket_write($ary[1], $strone, strlen($strone)) === false) {
echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($ary[1]));
}
if (socket_read($ary[1], strlen($strtwo), PHP_BINARY_READ) == $strtwo) {
echo "Received $strtwo\n";
}
socket_close($ary[1]);
} else {
/* 子プロセス */
socket_close($ary[1]);
if (socket_write($ary[0], $strtwo, strlen($strtwo)) === false) {
echo "socket_write() failed. Reason: ".socket_strerror(socket_last_error($ary[0]));
}
if (socket_read($ary[0], strlen($strone), PHP_BINARY_READ) == $strone) {
echo "Received $strone\n";
}
socket_close($ary[0]);
}
?>

参考

  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_create_listen() - 接続を受けつけるためにポートにソケットをオープンする
  • socket_bind() - ソケットに名前をバインドする
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


ソケットをカプセル化したストリームに、ソケットをエクスポートする

  • ≪ socket_create_pair
  • socket_get_option ≫
  • PHP Manual
  • ソケット 関数
  • ソケットをカプセル化したストリームに、ソケットをエクスポートする

socket_export_stream

(PHP 7 >= 7.0.7, PHP 8)

socket_export_stream — ソケットをカプセル化したストリームに、ソケットをエクスポートする

説明

socket_export_stream(Socket $socket): resource|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

socket

戻り値

リソースを返します。失敗した場合に false を返します.

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。


ソケットのオプションを取得する

  • ≪ socket_export_stream
  • socket_getopt ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのオプションを取得する

socket_get_option

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

socket_get_option — ソケットのオプションを取得する

説明

socket_get_option(Socket $socket, int $level, int $option): array|int|false

socket_get_option() 関数は、ソケット socket のオプション option の値を取得します。socket_get_option() は、失敗した場合に false を返します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

level

level パラメータは、オプションのプロトコルレベルを指定します。 例えば、オプションをソケットレベルで取得するには level パラメータに SOL_SOCKET を指定します。 TCP のようなそれ以外のレベルの場合、そのレベルのプロトコル番号を指定します。 プロトコル番号は getprotobyname() 関数を使用して取得可能です。

option
使用可能なソケットオプション
オプション | 説明 | 型
SO_DEBUG | デバッグ情報を記録するかどうかを報告します。 | int
SO_BROADCAST | ブロードキャストメッセージの送信がサポートされているかどうかを報告します。 | int
SO_REUSEADDR | ローカルアドレスが再利用可能かどうかを報告します。 | int
SO_REUSEPORT | ローカルポートが再利用可能かどうかを報告します。 | int
SO_KEEPALIVE | 定期的なメッセージの送信によって接続がアクティブになっているかどうかを報告します。 もしソケットがこれらのメッセージに応答できなかった場合、 接続は崩壊し、ソケットへの書き込みを行うと SIGPIPE シグナルを受け取ります。 | int
SO_LINGER

データがまだ残っているうちに socket_close() をコールした場合に、socket を残存させるかどうかを報告します。 デフォルトでは、ソケットが閉じられる際には未送信のデータをすべて送信しようとします。 接続ベースのソケットでは、 socket_close() は接続先がデータを認識するまで閉じるのを待ちます。

l_onoff が非ゼロで l_linger がゼロの場合は、 その時点で未送信のデータはすべて破棄されます。 接続ベースのソケットの場合、接続先には RST (リセット) を送信します。

一方 l_onoff が非ゼロで l_linger も非ゼロの場合は、 socket_close() は 全データを送信し終えるか l_linger で指定した時間が経過するまで処理をブロックします。 ソケットが非ブロックモードの場合は、 socket_close() は失敗してエラーを返します。

array。配列に含まれるキーは l_onoff および l_linger のふたつ。
SO_OOBINLINE | socket が帯域外のデータをインラインに残し続けるかを報告します。 | int
SO_SNDBUF | 送信バッファのサイズを報告します。 | int
SO_RCVBUF | 受信バッファのサイズを報告します。 | int
SO_ERROR | エラーステータスに関する情報を報告し、それをクリアします。 | int (socket_set_option() で設定することはできません)
SO_TYPE | socket の型 (たとえば SOCK_STREAM) を報告します。 | int (socket_set_option() で設定することはできません)
SO_DONTROUTE | 送信メッセージがルータを越えるかどうかを報告します。 | int
SO_RCVLOWAT | socket の入力操作を行う際の最小バイト数を報告します。 | int
SO_RCVTIMEO | 入力操作のタイムアウト値を報告します。 | array。配列に含まれるキーはふたつ。 sec はタイムアウトの秒単位の部分で、 usec はタイムアウトのマイクロ秒位の部分。
SO_SNDTIMEO | 出力関数がフロー制御のためにブロックするタイムアウト値を報告します。 | array。配列に含まれるキーはふたつ。 sec はタイムアウトの秒単位の部分で、 usec はタイムアウトのマイクロ秒位の部分。
SO_SNDLOWAT | socket の出力操作を行う際の最小バイト数を報告します。 | int
TCP_NODELAY | Nagle TCP アルゴリズムが無効になっているかどうかを報告します。 | int
MCAST_JOIN_GROUP | マルチキャストグループに参加します。 | 二つのキー "group" と "interface" を含む配列。"group" には IPv4 あるいは IPv6 のマルチキャストアドレスを文字列で指定します。 "interface" には、インターフェイス番号 (整数値) あるいは "eth0" などのインターフェイス名 (文字列) を指定します。 0 を指定すると、ルーティングテーブルを使ってインターフェイスを選択します (socket_set_option() でのみ利用可能)。
MCAST_LEAVE_GROUP | マルチキャストグループから離れます。 | 配列。詳細は MCAST_JOIN_GROUP を参照ください (socket_set_option() でのみ利用可能)。
MCAST_BLOCK_SOURCE | 特定のソースから、そのマルチキャストグループにやってくるパケットをブロックします。 そのマルチキャストグループに事前に参加しておく必要があります。 | MCAST_JOIN_GROUP と同じキーを含み、さらに追加でもうひとつのキーを含む配列。 追加のキーは source で、 ブロック対象となるソースの IPv4 アドレスあるいは IPv6 アドレスを文字列で指定します (socket_set_option() でのみ利用可能)。
MCAST_UNBLOCK_SOURCE | 特定のソースから、そのマルチキャストグループにやってくるパケットのブロックを解除 (そして、受信を再開) します。 そのマルチキャストグループに事前に参加しておく必要があります。 | MCAST_BLOCK_SOURCE と同じ形式の配列 (socket_set_option() でのみ利用可能)。
MCAST_JOIN_SOURCE_GROUP | 特定の値にマッチするソースアドレスからそのマルチキャストグループにやってきたパケットを受信します。 | MCAST_BLOCK_SOURCE と同じ形式の配列 (socket_set_option() でのみ利用可能)。
MCAST_LEAVE_SOURCE_GROUP | 特定の値にマッチするソースアドレスからそのマルチキャストグループにやってきたパケットの受信を停止します。 | MCAST_BLOCK_SOURCE と同じ形式の配列 (socket_set_option() でのみ利用可能)。
IP_MULTICAST_IF | IPv4 マルチキャストパケットの送信インターフェイス。 | インターフェイス番号を表す整数値か、インターフェイス名を表す eth0 のような文字列。 0 を指定すると、ルーティングテーブルを使ってインターフェイスを選択します。 socket_get_option() 関数の戻り値は、インターフェイスのインデックスとなります。 注意すべき点は、C の API とは違ってこのオプションには IP アドレスを渡せないということです。 そのため、 IP_MULTICAST_IF と IPV6_MULTICAST_IF のインターフェイスの相違はなくなります。
IPV6_MULTICAST_IF | IPv6 マルチキャストパケットの送信インターフェイス。 | IP_MULTICAST_IF と同じ。
IP_MULTICAST_LOOP | IPv4 パケットのマルチキャストループバックポリシー。 これを有効にすると、以前に参加したグループに、 マルチキャストのデータをループバックさせることができます。 このオプションの効果は、unix で有効にするか Windows で有効にするかで異なります。 前者は受信先のパスに影響するのに対し、 後者では送信元のパスに影響します。 | 整数値 (0 あるいは 1)。socket_set_option() では任意の値を受け付けますが、通常の PHP のルールに従ってそれを boolean 値に変換します。
IPV6_MULTICAST_LOOP | IP_MULTICAST_LOOP の IPv6 版。 | 整数値。IP_MULTICAST_LOOP を参照ください。
IP_MULTICAST_TTL | IPv4 送信パケットの有効期間。0 (このインターフェイスから離れない) から 255 までの値を指定しなければなりません。デフォルトは 1 (ローカルネットワークにだけ到達する) です。 | 0 から 255 までの整数値。
IPV6_MULTICAST_HOPS | IP_MULTICAST_TTL の IPv6 版。 値として -1 を指定することもでき、これはデフォルトのルートを使うことを意味します。 | -1 から 255 までの整数値。
SO_MARK | Linux でパケットフィルタを行う目的で、 ソケットの識別子を設定します。 | int
SO_ACCEPTFILTER | listen しているソケットに対し、accept filter を追加します (FreeBSD/NetBSD)。 accept filter カーネルモジュールは、FreeBSD では前もってロードしておく必要があります (e.g. accf_http)。 | フィルタの名前を示す文字列 (最大15文字)
SO_USER_COOKIE | FreeBSD でパケットフィルタを行う目的で、 ソケットの識別子を設定します。 | int
SO_RTABLE | OpenBSD でパケットフィルタを行う目的で、 ソケットの識別子を設定します。 | int
SO_DONTTRUNC | 未読のデータを保持します。 | int
SO_WANTMORE | さらにデータが読み取れる時にヒントを与えます。 | int
TCP_DEFER_ACCEPT | データが利用可能になるまでソケットに通知しません。 | int
SO_INCOMING_CPU | ソケットの CPU affinity の情報を取得/設定します。 | int
SO_MEMINFO | ソケットの meminfo を全て取得します。 | int
SO_BPF_EXTENSIONS | ソケットにアタッチするための、 kernel がサポートしている BPF 拡張を取得します。 | int
SO_SETFIB | ソケットの route table (FIB) を設定します(FreeBSD のみ) | int
SOL_FILTER | ソケットの属性をフィルタします(Solaris/Illumos のみ) | int
TCP_KEEPCNT | 接続を切断する前に、TCP が送信すべき keepalive プローブの最大数を設定します | int
TCP_KEEPIDLE | 接続がアイドル状態である必要がある、時間を設定します | int
TCP_KEEPINTVL | 個別の keepalive プローブを送信する間隔を設定します | int
TCP_KEEPALIVE | 接続がアイドル状態である必要がある、時間を設定します(macOS のみ) | int
TCP_NOTSENT_LOWAT | ソケットストリームの書き込みキュー中の、未送信のデータ数を制限します(Linuxのみ) | int

戻り値

指定したオプションの値を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_get_option() の例

<?php
$socket = socket_create_listen(1223);

$linger = array('l_linger' => 1, 'l_onoff' => 1);
socket_set_option($socket, SOL_SOCKET, SO_LINGER, $linger);

var_dump(socket_get_option($socket, SOL_SOCKET, SO_REUSEADDR));
?>

参考

  • socket_create_listen() - 接続を受けつけるためにポートにソケットをオープンする
  • socket_set_option() - ソケットのオプションを設定する


socket_get_option のエイリアス

  • ≪ socket_get_option
  • socket_getpeername ≫
  • PHP Manual
  • ソケット 関数
  • socket_get_option のエイリアス

socket_getopt

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_getopt — socket_get_option() のエイリアス

説明

この関数は次の関数のエイリアスです。 socket_get_option()


指定したソケットのリモート側に問い合わせる

  • ≪ socket_getopt
  • socket_getsockname ≫
  • PHP Manual
  • ソケット 関数
  • 指定したソケットのリモート側に問い合わせる

socket_getpeername

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_getpeername — 指定したソケットのリモート側に問い合わせる

説明

socket_getpeername(Socket $socket, string &$address, int &$port = null): bool

指定したソケットのリモート側に問い合わせ、 その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

address

指定されたソケットの型が AF_INET あるいは AF_INET6 であった場合、socket_getpeername() はピア（リモート）の IP アドレス を適切な書式（例: 127.0.0.1 あるいは fe80::1）に したものを address パラメータに、そしてもし オプションの port パラメータが指定されていれば そこにポートを格納します。

指定されたソケットの型が AF_UNIX であった場合、 socket_getpeername() は Unix ファイルシステムの パス（例: /var/run/daemon.sock）を address パラメータに格納します。

port

指定した場合は、 address に関連付けるポートを保持します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 socket_getpeername() は、 ソケットの型が AF_INET、 AF_INET6 あるいは AF_UNIX のいずれでもない場合にも false を返します。この場合には、 直近のソケットエラーコードは更新されません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

注意

注意:

socket_getpeername() は、 socket_accept() で作成した AF_UNIX ソケットとともに使用することはできません。意味のある値が返されるのは、 socket_connect() で作成したソケットか socket_bind() に続くプライマリサーバーソケットのみです。

注意:

socket_getpeername() に何らかの意味のある値を返させるには、 もちろんソケット自体が "peer" の概念を満たしている必要があります。

参考

  • socket_getsockname() - 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

  • ≪ socket_getpeername
  • socket_import_stream ≫
  • PHP Manual
  • ソケット 関数
  • 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

socket_getsockname

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_getsockname — 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す

説明

socket_getsockname(Socket $socket, string &$address, int &$port = null): bool

注意: socket_getsockname() は、 socket_accept() で作成した AF_UNIX ソケットとともに使用することはできません。意味のある値が返されるのは、 socket_accept() で作成したソケットか socket_bind() に続くプライマリサーバーソケットのみです。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

address

指定されたソケットの型が AF_INET あるいは AF_INET6 であった場合、socket_getsockname() はローカルの IP アドレス を適切な書式（例: 127.0.0.1 あるいは fe80::1）に したものを address パラメータに、そしてもし オプションの port パラメータが指定されていれば そこにポートを格納します。

指定されたソケットの型が AF_UNIX であった場合、 socket_getpeername() は Unix ファイルシステムのパス （例: /var/run/daemon.sock）を address パラメータに格納します。

port

指定した場合は、関連付けるポートを保持します。

戻り値

成功した場合に true を、失敗した場合に false を返します。 socket_getsockname() は、 ソケットの型が AF_INET、 AF_INET6 あるいは AF_UNIX のいずれでもない場合にも false を返します。この場合には、 直近のソケットエラーコードは更新されません。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_getpeername() - 指定したソケットのリモート側に問い合わせる
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


ストリームをインポートする

  • ≪ socket_getsockname
  • socket_last_error ≫
  • PHP Manual
  • ソケット 関数
  • ストリームをインポートする

socket_import_stream

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

socket_import_stream — ストリームをインポートする

説明

socket_import_stream(resource $stream): Socket|false

ストリームをインポートし、ソケットをソケットリソースにカプセル化します。

パラメータ

stream

インポートするストリームリソース。

戻り値

失敗した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

例

例1 socket_import_stream() の例

<?php
$stream = stream_socket_server("udp://0.0.0.0:58380", $errno, $errstr, STREAM_SERVER_BIND);
$sock = socket_import_stream($stream);
?>

参考

  • stream_socket_server() - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する


ソケットの直近のエラーを返す

  • ≪ socket_import_stream
  • socket_listen ≫
  • PHP Manual
  • ソケット 関数
  • ソケットの直近のエラーを返す

socket_last_error

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_last_error — ソケットの直近のエラーを返す

説明

socket_last_error(?Socket $socket = null): int

Socket クラスのインスタンスをこの関数に渡すと、この特定のソケットに発生した 直近のエラーが返されます。socket が null の場合、 直近にエラーを発生したソケット関数のエラーコードが返されます。 後者は、失敗した場合にソケットを返さない socket_create() のような関数や 特定のソケットに直接関係ない理由で失敗する可能性がある socket_select() で特に有用です。 このエラーコードは、指定したエラーコードを表す文字列を得るために socket_strerror() に渡すものとしても適しています。

エラーが発生していない場合や socket_clear_error() でクリアされた後である場合は、 この関数は 0 を返します。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

戻り値

この関数は、ソケットのエラーコードを返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | socket は、nullable になりました。

例

例1 socket_last_error() の例

<?php
$socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if ($socket === false) {
$errorcode = socket_last_error();
$errormsg = socket_strerror($errorcode);

die("ソケットを作成できません: [$errorcode] $errormsg");
}
?>

注意

注意:

socket_last_error() はエラーコードをクリアしません。 クリアするには socket_clear_error() を使用してください。


ソケット上で接続待ち(listen)する

  • ≪ socket_last_error
  • socket_read ≫
  • PHP Manual
  • ソケット 関数
  • ソケット上で接続待ち(listen)する

socket_listen

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_listen — ソケット上で接続待ち(listen)する

説明

socket_listen(Socket $socket, int $backlog = 0): bool

ソケット socket が socket_create() を用いて作成され、 socket_bind() で名前が付けられた後、 socket 上の接続要求を待つための通信ができるようになります。

socket_listen() は、ソケットが SOCK_STREAM 型または SOCK_SEQPACKET 型の場合のみ利用可能です。

パラメータ

socket

socket_create() または socket_addrinfo_bind() で作成した 有効な Socket クラスのインスタンス。

backlog

最大 backlog 個の接続を処理用の キューで待ち受けることが可能です。もし待ちうけ用のキューが いっぱいになった場合、クライアントでは ECONNREFUSED の通知とともにエラーが発生します。あるいは、もし基盤となるプロトコルが リクエストの再送をサポートしている場合、再試行が成功するまで リクエストは無視されます。

注意:

backlog パラメータに指定できる値の最大値は プラットフォームに大きく依存します。Linux では、最大値は SOMAXCONN に切り詰められます。win32 では、 もし SOMAXCONN を渡した場合、backlog の 最大値を適切な値に設定する責任はサービスの 提供側が負います。 このプラットフォームでは、実際の backlog の値を見つける標準的な 手段が提供されていません。

戻り値

成功した場合に true を、失敗した場合に false を返します。 エラーコードは socket_last_error() で取得可能で、このコードを socket_strerror() に指定することにより エラーの内容を文字列として取得可能です。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_strerror() - ソケットエラーの内容を文字列として返す
  • socket_addrinfo_bind() - 与えられた addrinfo から、ソケットを作成してバインドする


ソケットから最大バイト長まで読みこむ

  • ≪ socket_listen
  • socket_recv ≫
  • PHP Manual
  • ソケット 関数
  • ソケットから最大バイト長まで読みこむ

socket_read

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_read — ソケットから最大バイト長まで読みこむ

説明

socket_read(Socket $socket, int $length, int $mode = PHP_BINARY_READ): string|false

関数 socket_read() は、関数
socket_create() または
socket_accept() により作成された
Socket クラスのインスタンス
socket から読み込みます。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

length

読み込まれる最大バイト長は、length パラメータで 指定します。 読み込みを終了するために \r、\n、 \0 を使用することが可能です (これは、以下に示す mode に依存します)。

mode

オプションのパラメータ mode は、名前のある定数です。

  • PHP_BINARY_READ (デフォルト) - システムの recv() 関数を 使用します。バイナリデータ読み込みに関して安全です。
  • PHP_NORMAL_READ - 読み込みは、\n あるいは \r で中断されます。

戻り値

socket_read() は、成功時に文字列としてデータを返し、 エラー時 (リモートホストが接続をクローズした場合を含みます) に false を返します。 エラーコードは socket_last_error() で取得可能であり、 このコードは、エラー文字列を取得するために socket_strerror() に渡すことができます。

注意:

socket_read() は、読み込むデータがもう存在しない 場合に長さゼロの文字列("")を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す
  • socket_write() - ソケットに書き込む


接続したソケットからデータを受信する

  • ≪ socket_read
  • socket_recvfrom ≫
  • PHP Manual
  • ソケット 関数
  • 接続したソケットからデータを受信する

socket_recv

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_recv — 接続したソケットからデータを受信する

説明

socket_recv(
Socket $socket,
?string &$data,
int $length,
int $flags
): int|false

socket_recv() 関数は、 socket から length バイトのデータを受信して data に格納します。 socket_recv() を使うと、 接続したソケットからデータを収集することができます。 さらに、フラグを指定して関数の挙動を変更することもできます。

data は参照渡しなので、 引数リストには変数で渡さなければなりません。 socket から socket_recv() で読み込んだデータが data に入ります。

パラメータ

socket

socket は、事前に socket_create() で作成した Socket クラスのインスタンスでなければなりません。

data

受信したデータが、 data で指定した変数に格納されます。 エラーが発生したり接続がリセットされたりデータが存在しなかったりした場合は、 data には null が設定されます。

length

最大 length バイトまでをリモートホストから取得します。

flags

flags の値は、次のフラグを論理 OR (|) 演算子で組み合わせたものとなります。

flags のとりうる値
フラグ | 説明
MSG_OOB | out-of-band を処理します。
MSG_PEEK | 受信キューの先頭からデータを取得し、受信したデータをキューから削除しません。
MSG_WAITALL | 最低 length バイト受信するまでブロックします。 しかし、シグナルを受け取ったりリモートホストが接続を切断したりした場合は、 この関数が返すデータがそれより少なくなる可能性があります。
MSG_DONTWAIT | このフラグを設定すると、正常にブロックされている状態でも関数が結果を返します。

戻り値

socket_recv() は、受信したバイト数を返します。 エラーが発生した場合は false を返します。 実際のエラーコードを取得するには socket_last_error() をコールします。 このエラーコードを socket_strerror() に渡すと、エラーに関する説明テキストを取得することができます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_recv() の例

この例は、 例 の最初の例を書き換えて socket_recv() を使う形式にしたものです。

<?php
error_reporting(E_ALL);

echo "<h2>TCP/IP Connection</h2>\n";

/* WWW サービスのポートを取得します */
$service_port = getservbyname('www', 'tcp');

/* 対象となるホストの IP アドレスを取得します */
$address = gethostbyname('www.example.com');

/* TCP/IP ソケットを作成します */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
echo "OK.\n";
}

echo "Attempting to connect to '$address' on port '$service_port'...";
$result = socket_connect($socket, $address, $service_port);
if ($result === false) {
echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
echo "OK.\n";
}

$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: www.example.com\r\n";
$in .= "Connection: Close\r\n\r\n";
$out = '';

echo "Sending HTTP HEAD request...";
socket_write($socket, $in, strlen($in));
echo "OK.\n";

echo "Reading response:\n\n";
$buf = 'This is my buffer.';
if (false !== ($bytes = socket_recv($socket, $buf, 2048, MSG_WAITALL))) {
echo "Read $bytes bytes from socket_recv(). Closing socket...";
} else {
echo "socket_recv() failed; reason: " . socket_strerror(socket_last_error($socket)) . "\n";
}
socket_close($socket);

echo $buf . "\n";
echo "OK.\n\n";
?>

上の例の出力は、このようになります。

<h2>TCP/IP Connection</h2>
OK.
Attempting to connect to '208.77.188.166' on port '80'...OK.
Sending HTTP HEAD request...OK.
Reading response:

Read 123 bytes from socket_recv(). Closing socket...HTTP/1.1 200 OK
Date: Mon, 14 Sep 2009 08:56:36 GMT
Server: Apache/2.2.3 (Red Hat)
Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT
ETag: "b80f4-1b6-80bfd280"
Accept-Ranges: bytes
Content-Length: 438
Connection: close
Content-Type: text/html; CHARSET=shift-jis

OK.


接続しているかどうかによらず、ソケットからデータを受信する

  • ≪ socket_recv
  • socket_recvmsg ≫
  • PHP Manual
  • ソケット 関数
  • 接続しているかどうかによらず、ソケットからデータを受信する

socket_recvfrom

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_recvfrom — 接続しているかどうかによらず、ソケットからデータを受信する

説明

socket_recvfrom(
Socket $socket,
string &$data,
int $length,
int $flags,
string &$address,
int &$port = null
): int|false

socket_recvfrom() 関数は、 ポート port (AF_UNIX 型のソケットである場合を除く) 上の address から受信した length バイトのデータを data に格納します。 socket_recvfrom() は、 接続済みのソケットだけでなく接続していないソケットに対しても使用可能です。 さらに、フラグを指定することでこの関数の挙動を設定できます。

address と port は参照渡しとしなければなりません。接続していないソケットの場合は、 address はリモートホストの IP アドレスか UNIX ソケットへのパスとなります。接続済みのソケットの場合は、 address は null とします。 また、AF_INET あるいは AF_INET6 形式のまだ接続していないソケットの場合、 port にはリモートホストのポート番号を指定します。

注意: この関数はバイナリデータに対応しています。

パラメータ

socket

socket には、 socket_create() で作成した Socket クラスのインスタンスを指定します。

data

受信したデータが data に格納されます。

length

最大 length バイトまでのデータをリモートホストから取得します。

flags

flags の値は、以下のフラグの任意の組み合わせを 論理 OR 演算子 (|) で連結したものとなります。

flags に使用できる値
フラグ | 説明
MSG_OOB | 帯域外 (out-of-band) のデータを処理する。
MSG_PEEK | 受信キューの先頭にあるデータを受信し、 そのデータをそのままキューに残しておく。
MSG_WAITALL | 少なくとも length バイト受信するまではブロックする。 しかし、もし何らかのシグナルを受信したりリモートホストとの接続が切断された場合は これより少ないバイト数を返す可能性がある。
MSG_DONTWAIT | 通常はブロックする場面であってもそのまま return する。
address

AF_UNIX 型のソケットの場合は、 address はファイルへのパスとなります。 それ以外の場合は、未接続のソケットの場合には address はリモートホストの IP アドレスとなります。 接続済みソケットの場合は null となります。

port

この引数は AF_INET 型あるいは AF_INET6 型のソケットに対してのみ適用され、 データを受信するリモートホストのポートを指定します。 接続済みソケットの場合は port は null となります。

戻り値

socket_recvfrom() は、受信したバイト数を返します。 あるいはエラー時には false を返します。 エラーコードを取得するには socket_last_error() をコールします。取得したエラーコードを socket_strerror() に渡すと、 そのエラーについての説明を得ることができます。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_recvfrom() の例

<?php

$socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
socket_bind($socket, '127.0.0.1', 1223);

$from = '';
$port = 0;
socket_recvfrom($socket, $buf, 12, 0, $from, $port);

echo "リモートアドレス $from のポート $port から $buf を受信しました" . PHP_EOL;
?>

この例は、127.0.0.1 のポート 1223 との UDP ソケットを確立し、受信したデータを最大 12 バイトまで表示します。

参考

  • socket_recv() - 接続したソケットからデータを受信する
  • socket_send() - 接続したソケットにデータを送信する
  • socket_sendto() - 接続しているかどうかによらずソケットにメッセージを送信する
  • socket_create() - ソケット（通信時の終端）を作成する


メッセージを読む

  • ≪ socket_recvfrom
  • socket_select ≫
  • PHP Manual
  • ソケット 関数
  • メッセージを読む

socket_recvmsg

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

socket_recvmsg — メッセージを読む

説明

socket_recvmsg(Socket $socket, array &$message, int $flags = 0): int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

socket

message

flags

戻り値

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_sendmsg() - メッセージを送信する
  • socket_cmsg_space() - メッセージバッファサイズを計算する


与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する

  • ≪ socket_recvmsg
  • socket_send ≫
  • PHP Manual
  • ソケット 関数
  • 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する

socket_select

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_select — 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する

説明

socket_select(
?array &$read,
?array &$write,
?array &$except,
?int $seconds,
int $microseconds = 0
): int|false

socket_select() はソケットの配列を受け取り、 それらの状態が変化するまで待ちます。BSD のソケットについての知識がある方なら、 これらのソケットの配列が、いわゆるファイル記述子セットであることがご理解いただけるでしょう。 3 つの独立した配列でソケットを監視します。

パラメータ

read

配列 read に挙げられたソケットでは、 文字が読み込み可能になっているかどうか（厳密に言うと、読み込みが ブロックされていないかどうか - 実際には、ソケット記述子はファイルの 終端でも有効です。そのような場合、socket_read() は長さゼロの文字列を返します）を監視します。

write

配列 write に挙げられたソケットでは、 書き込みがブロックされていないかどうかを監視します。

except

配列 except に挙げられたソケットでは、 例外を監視します。

seconds

seconds および microseconds は、ともにタイムアウトを指定するパラメータです。 タイムアウトは、socket_select() が結果を返すまでの経過時間の最大値です。 seconds はゼロにすることも可能で、そうすると socket_select() は結果をすぐに返します。 これはポーリングをする際に有用です。seconds に null（タイムアウトしない）を指定すると、 socket_select() は無期限にブロックします。

microseconds

警告

終了時に配列は書き換えられ、 どのソケットの状態が変わったのかがわかるようになります。

socket_select() のすべての配列を設定する必要はありません。 使用しないものについては空の配列や null をかわりに指定しておくことが可能です。 また、これらの配列は参照渡し であり、 socket_select() をコールした後でその中身が書き換えられていることに注意しましょう。

注意:

現状の Zend Engine の制限により、関数の参照渡しパラメータに null のような定数値を直接渡すことができません。一時的な変数を使用するか、 あるいは一番左に一時変数を使用する式を使用してください。

例1 socket_select() での null の使用

<?php
$e = NULL;
socket_select($r, $w, $e, 0);
?>

戻り値

成功した場合は、socket_select() は配列内で 変化のあったソケットの数を返します。もし何かがおこる前に タイムアウト時間が経過した場合は、ゼロを返すことになります。 エラー時には false が返されます。エラーコードは socket_last_error() で取得可能です。

注意:

エラーかどうかを調べる際には、必ず === 演算子を 使用するようにしましょう。socket_select() は 0 を返す場合もあり、このような場合に == を用いて比較すると、エラーと判定されてしまいます。

例2 socket_select() の返す結果を知る

<?php
$e = NULL;
if (false === socket_select($r, $w, $e, 0)) {
echo "socket_select() は失敗しました。原因: " .
socket_strerror(socket_last_error()) . "\n";
}
?>

例

例3 socket_select() の例

<?php
/* 読み込み用の配列を準備する */
$read = array($socket1, $socket2);
$write = NULL;
$except = NULL;
$num_changed_sockets = socket_select($read, $write, $except, 0);

if ($num_changed_sockets === false) {
/* エラー処理 */
} else if ($num_changed_sockets > 0) {
/* すくなくともひとつのソケットで、何らかの出来事が起こっています */
}
?>

注意

注意:

ソケットの実装によっては、取り扱いに注意すべきものがあることを知っておいてください。 基本的なルールは以下のとおりです。

  • 基本的に socket_select() のタイムアウトは 指定しないように心がけましょう。もしデータがなかった場合に、 プログラム側でそれを判定できなくなってしまいます。タイムアウトに 依存しているコードは移植性が悪く、デバッグが困難です。
  • socket_select() のコール後に値をチェックして 適切に処理するつもりがないソケットは、決して配列に追加してはいけません。 socket_select() から値が返ってきたあとは、 配列内のすべてのソケットをチェックする必要があります。 すべての書き込み用ソケットは書き込める必要がありますし、 またすべての読み込み用ソケットは読み込める必要があります。
  • 配列で返されたソケットに対して読み込み/書き込みをする場合には、 指定したデータを必ずしもすべて読み込み/書き込みするとは限らないことを 知っておいてください。たった 1 バイトしか読み込み/書き込みが できなかった場合にも対処できるよう準備しておきましょう。
  • ほとんどのソケット実装で、except でキャッチできる 例外はただひとつ、すなわちソケットが受け取ったデータが帯域外で あったということだけです。

参考

  • socket_read() - ソケットから最大バイト長まで読みこむ
  • socket_write() - ソケットに書き込む
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_strerror() - ソケットエラーの内容を文字列として返す


接続したソケットにデータを送信する

  • ≪ socket_select
  • socket_sendmsg ≫
  • PHP Manual
  • ソケット 関数
  • 接続したソケットにデータを送信する

socket_send

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_send — 接続したソケットにデータを送信する

説明

socket_send(
Socket $socket,
string $data,
int $length,
int $flags
): int|false

関数 socket_send() は、 data からソケット socket に length バイトのデータを送信します。

パラメータ

socket

socket_create() あるいは socket_accept() が作成した有効な Socket クラスのインスタンス。

data

リモートホストに送信するデータを含むバッファ。

length

data からリモートホストに送信するバイト数。

flags

flags の値は、以下のフラグの任意の組み合わせを 論理 OR 演算子 (|) で連結したものとなります。

flags がとりうる値
MSG_OOB | OOB（out-of-band: 帯域外）データを送信します。
MSG_EOR | レコードにマークをつけます。 レコードでデータがそろいます。
MSG_EOF | ソケットの送信側を閉じ、そのことを知らせる通知を送信データの最後に付加します。 トランザクションでデータがそろいます。
MSG_DONTROUTE | ルータを使用せず、直接つながっているインターフェイスのみを使用します。

戻り値

socket_send() は、送信したバイト数あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_sendto() - 接続しているかどうかによらずソケットにメッセージを送信する


メッセージを送信する

  • ≪ socket_send
  • socket_sendto ≫
  • PHP Manual
  • ソケット 関数
  • メッセージを送信する

socket_sendmsg

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

socket_sendmsg — メッセージを送信する

説明

socket_sendmsg(Socket $socket, array $message, int $flags = 0): int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

socket

message

flags

戻り値

送信したバイト数を返します。失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_recvmsg() - メッセージを読む
  • socket_cmsg_space() - メッセージバッファサイズを計算する


接続しているかどうかによらずソケットにメッセージを送信する

  • ≪ socket_sendmsg
  • socket_set_block ≫
  • PHP Manual
  • ソケット 関数
  • 接続しているかどうかによらずソケットにメッセージを送信する

socket_sendto

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_sendto — 接続しているかどうかによらずソケットにメッセージを送信する

説明

socket_sendto(
Socket $socket,
string $data,
int $length,
int $flags,
string $address,
?int $port = null
): int|false

関数 socket_sendto() は、 アドレス addr の port を使用し、 data からソケット socket に length バイトのデータを送信します。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

data

送信するデータが、data から取り出されます。

length

data から length バイト分のデータが送信されます。

flags

flags の値は、以下のフラグの任意の組み合わせを 論理 OR 演算子 (|) で連結したものとなります。

flags がとりうる値
MSG_OOB | OOB（out-of-band: 帯域外）データを送信します。
MSG_EOR | レコードにマークをつけます。 レコードでデータがそろいます。
MSG_EOF | ソケットの送信側を閉じ、そのことを知らせる通知を送信データの最後に付加します。 トランザクションでデータがそろいます。
MSG_DONTROUTE | ルータを使用せず、直接つながっているインターフェイスのみを使用します。

address

リモートホストの IP アドレス。

port

port は、 データの送信先となるリモートホストのポート番号です。

戻り値

socket_sendto() は、リモートホストに送信したバイト数を返します。 エラーが発生した場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | port は、nullable になりました。

例

例1 socket_sendto() の例

<?php
$sock = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);

$msg = "Ping !";
$len = strlen($msg);

socket_sendto($sock, $msg, $len, 0, '127.0.0.1', 1223);
socket_close($sock);
?>

参考

  • socket_send() - 接続したソケットにデータを送信する


ソケットのブロッキングモードを設定する

  • ≪ socket_sendto
  • socket_set_nonblock ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのブロッキングモードを設定する

socket_set_block

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

socket_set_block — ソケットのブロッキングモードを設定する

説明

socket_set_block(Socket $socket): bool

socket_set_block() 関数は、 socket パラメータで指定したソケットから O_NONBLOCK フラグを取り除きます。

受信や送信、接続、待機といった操作をブロックモードのソケットに対して行うと、 その処理が完了するか何らかのシグナルを受信するまではスクリプトを停止します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_set_block() の例

<?php
$socket = socket_create_listen(1223);
socket_set_block($socket);

socket_accept($socket);
?>

この例は、すべてのインターフェイス上でポート 1223 を待ち受けるソケットを作成し、それを O_BLOCK モードに設定します。 socket_accept() は、 接続が受け付けられるまで処理を停止して待ち続けます。

参考

  • socket_set_nonblock() - ソケットリソースを非ブロックモードに設定する
  • socket_set_option() - ソケットのオプションを設定する


ソケットリソースを非ブロックモードに設定する

  • ≪ socket_set_block
  • socket_set_option ≫
  • PHP Manual
  • ソケット 関数
  • ソケットリソースを非ブロックモードに設定する

socket_set_nonblock

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_set_nonblock — ソケットリソースを非ブロックモードに設定する

説明

socket_set_nonblock(Socket $socket): bool

socket_set_nonblock() 関数は、 socket パラメータで指定したソケットに O_NONBLOCK フラグを設定します。

受信や送信、接続、待機といった操作を非ブロックモードのソケットに対して行うと、 その処理が完了するか何らかのシグナルを受信するまではスクリプトは停止しません。 また、その操作がブロックされると、呼び出し元の関数は失敗します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_set_nonblock() の例

<?php
$socket = socket_create_listen(1223);
socket_set_nonblock($socket);

socket_accept($socket);
?>

この例は、すべてのインターフェイス上でポート 1223 を待ち受けるソケットを作成し、それを O_NONBLOCK モードに設定します。 socket_accept() は、 その時点で待機中の接続がない場合はすぐに失敗します。

参考

  • socket_set_block() - ソケットのブロッキングモードを設定する
  • socket_set_option() - ソケットのオプションを設定する
  • stream_set_blocking() - ストリームのブロックモードを有効にする / 解除する


ソケットのオプションを設定する

  • ≪ socket_set_nonblock
  • socket_setopt ≫
  • PHP Manual
  • ソケット 関数
  • ソケットのオプションを設定する

socket_set_option

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

socket_set_option — ソケットのオプションを設定する

説明

socket_set_option(
Socket $socket,
int $level,
int $option,
array|string|int $value
): bool

socket_set_option() 関数は、level が指すプロトコルレベルでソケット socket のオプション option に値 value を設定します。

パラメータ

socket

socket_create() あるいは socket_accept() で作成した Socket クラスのインスタンス。

level

level パラメータは、オプションのプロトコルレベルを指定します。 例えば、オプションをソケットレベルで設定するには level パラメータに SOL_SOCKET を指定します。 TCP のようなそれ以外のレベルの場合、そのレベルのプロトコル番号を指定します。 プロトコル番号は getprotobyname() 関数を使用して取得可能です。

option

使用可能なソケットオプションは socket_get_option() 関数と同じです。

value

オプションの値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

例

例1 socket_set_option() の例

<?php
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);

if (!is_resource($socket)) {
echo 'ソケットを作成できません: '. socket_strerror(socket_last_error()) . PHP_EOL;
}

if (!socket_set_option($socket, SOL_SOCKET, SO_REUSEADDR, 1)) {
echo 'ソケットのオプションを設定できません: '. socket_strerror(socket_last_error()) . PHP_EOL;
}

if (!socket_bind($socket, '127.0.0.1', 1223)) {
echo 'ソケットをバインドできません: '. socket_strerror(socket_last_error()) . PHP_EOL;
}

$rval = socket_get_option($socket, SOL_SOCKET, SO_REUSEADDR);

if ($rval === false) {
echo 'ソケットのオプションを取得できません: '. socket_strerror(socket_last_error()) . PHP_EOL;
} else if ($rval !== 0) {
echo 'SO_REUSEADDR がソケットに設定されています!' . PHP_EOL;
}
?>

参考

  • socket_create() - ソケット（通信時の終端）を作成する
  • socket_bind() - ソケットに名前をバインドする
  • socket_strerror() - ソケットエラーの内容を文字列として返す
  • socket_last_error() - ソケットの直近のエラーを返す
  • socket_get_option() - ソケットのオプションを取得する


socket_set_option のエイリアス

  • ≪ socket_set_option
  • socket_shutdown ≫
  • PHP Manual
  • ソケット 関数
  • socket_set_option のエイリアス

socket_setopt

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_setopt — socket_set_option() のエイリアス

説明

この関数は次の関数のエイリアスです。 socket_set_option()


受信、送信、または送受信用のソケットをシャットダウンする

  • ≪ socket_setopt
  • socket_strerror ≫
  • PHP Manual
  • ソケット 関数
  • 受信、送信、または送受信用のソケットをシャットダウンする

socket_shutdown

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_shutdown — 受信、送信、または送受信用のソケットをシャットダウンする

説明

socket_shutdown(Socket $socket, int $mode = 2): bool

socket_shutdown() 関数は、socket から送られてくる受信、送信あるいはすべて（デフォルト）のデータを停止します。

注意:

関連するバッファの内容は、空になるかもしれないしならないかもしれません。

パラメータ

socket

socket_create() で作成した Socket クラスのインスタンス。

mode

mode の値は以下のうちのひとつです。

mode のとりうる値
0 | ソケットの読み込みを停止します。
1 | ソケットの書き込みを停止します。
2 | ソケットの読み込み・書き込みを停止します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。


ソケットエラーの内容を文字列として返す

  • ≪ socket_shutdown
  • socket_write ≫
  • PHP Manual
  • ソケット 関数
  • ソケットエラーの内容を文字列として返す

socket_strerror

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_strerror — ソケットエラーの内容を文字列として返す

説明

socket_strerror(int $error_code): string

socket_strerror() は、パラメータ error_code に socket_last_error() の返すソケットエラーコードを受け取り、 対応する内容を文字列で返します。

注意:

socket 拡張モジュールが出すエラーメッセージは英語ですが、 この関数から取得したシステムメッセージは現在のロケール (LC_MESSAGES) にあわせた表示となります。

パラメータ

error_code

ソケットのエラー番号。たいていは socket_last_error() が返したものとなるでしょう。

戻り値

error_code パラメータに対応するエラーメッセージを返します。

例

例1 socket_strerror() の例

<?php
if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}

if (false == (@socket_bind($socket, '127.0.0.1', 80))) {
echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($socket)) . "\n";
}
?>

上記の例の出力はおそらく次のようになります (このスクリプトがルート権限で実行されていないことを仮定します)。

socket_bind() failed: reason: Permission denied

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_create() - ソケット（通信時の終端）を作成する


ソケットに書き込む

  • ≪ socket_strerror
  • socket_wsaprotocol_info_export ≫
  • PHP Manual
  • ソケット 関数
  • ソケットに書き込む

socket_write

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

socket_write — ソケットに書き込む

説明

socket_write(Socket $socket, string $data, ?int $length = null): int|false

関数 socket_write() は、 data の内容をソケット socket に書き込みます。

パラメータ

socket

data

書き込まれるバッファ。

length

オプションのパラメータ length で、 ソケットに書き込むバイト数を指定することが可能です。 この値がバッファの長さより大きい場合、自動的にバッファのサイズに切り詰められます。

戻り値

ソケットへの書き込みに成功したデータのバイト数を返します。失敗した場合に false を返します。 エラーコードは socket_last_error() を用いて取得することができ、この値を socket_strerror() に渡すことでエラー情報を文字列で取得可能です。

注意:

socket_write() がゼロを返すことも十分ありえます。 これは、書き込むデータが存在しなかったことを意味します。 エラーをチェックするために false かどうかを調べる際には、必ず === 演算子を使用しましょう。

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。
8.0.0 | length は、nullable になりました。

注意

注意:

socket_write() は、バッファの内容を必ずしもすべて 書き込むとは限りません。ネットワークバッファの状態にもよりますが、 たとえ 1 バイトだけ書き込まれたのであったとしても、それはエラーではなく正常な動作です。 そのため、データがすべて書き込まれたのかどうかに注意する必要があります。

参考

  • socket_accept() - ソケットへの接続を許可する
  • socket_bind() - ソケットに名前をバインドする
  • socket_connect() - ソケット上の接続を初期化する
  • socket_listen() - ソケット上で接続待ち(listen)する
  • socket_read() - ソケットから最大バイト長まで読みこむ
  • socket_strerror() - ソケットエラーの内容を文字列として返す


WSAPROTOCOL_INFO 構造体をエクスポートする

  • ≪ socket_write
  • socket_wsaprotocol_info_import ≫
  • PHP Manual
  • ソケット 関数
  • WSAPROTOCOL_INFO 構造体をエクスポートする

socket_wsaprotocol_info_export

(PHP 7 >= 7.3.0, PHP 8)

socket_wsaprotocol_info_export — WSAPROTOCOL_INFO 構造体をエクスポートする

説明

socket_wsaprotocol_info_export(Socket $socket, int $process_id): string|false

WSAPROTOCOL_INFO 構造体を共有メモリにエクスポートし、 socket_wsaprotocol_info_import() で使える識別子を返します。 エクスポートされるIDは、与えられた process_id 向けのものだけが有効です。

注意: この関数は Windows でのみ利用可能です。

パラメータ

socket

有効な Socket クラスのインスタンス。

process_id

ソケットをインポートするプロセスのID

戻り値

インポートに使われる識別子を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | socket は、Socket クラスのインスタンスになりました。 これより前のバージョンでは、リソース型でした。

参考

  • socket_wsaprotocol_info_import() - 別のプロセスからソケットをインポートする
  • socket_wsaprotocol_info_release() - エクスポートした WSAPROTOCOL_INF 構造体を解放する


別のプロセスからソケットをインポートする

  • ≪ socket_wsaprotocol_info_export
  • socket_wsaprotocol_info_release ≫
  • PHP Manual
  • ソケット 関数
  • 別のプロセスからソケットをインポートする

socket_wsaprotocol_info_import

(PHP 7 >= 7.3.0, PHP 8)

socket_wsaprotocol_info_import — 別のプロセスからソケットをインポートする

説明

socket_wsaprotocol_info_import(string $info_id): Socket|false

以前別のプロセスからエクスポートされたソケットをインポートします。

注意: この関数は Windows でのみ利用可能です。

パラメータ

info_id

socket_wsaprotocol_info_export() 関数が以前の呼び出しで返したID

戻り値

成功した時に、Socket クラスのインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | 成功した場合に、この関数は Socket クラスのインスタンスを返すようになりました。 これより前のバージョンでは、リソースを返していました。

参考

  • socket_wsaprotocol_info_export() - WSAPROTOCOL_INFO 構造体をエクスポートする


エクスポートした WSAPROTOCOL_INF 構造体を解放する

  • ≪ socket_wsaprotocol_info_import
  • Socket ≫
  • PHP Manual
  • ソケット 関数
  • エクスポートした WSAPROTOCOL_INF 構造体を解放する

socket_wsaprotocol_info_release

(PHP 7 >= 7.3.0, PHP 8)

socket_wsaprotocol_info_release — エクスポートした WSAPROTOCOL_INF 構造体を解放する

説明

socket_wsaprotocol_info_release(string $info_id): bool

与えられた info_id に対応する共有メモリを解放します。

注意: この関数は Windows でのみ利用可能です。

パラメータ

info_id

socket_wsaprotocol_info_export() 関数が以前の呼び出しで返したID

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • socket_wsaprotocol_info_export() - WSAPROTOCOL_INFO 構造体をエクスポートする


  • ≪ socket_wsaprotocol_info_release
  • AddressInfo ≫
  • PHP Manual
  • ソケット
  • Socket クラス

Socket クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 Socket リソースを置き換える完全不透明クラスです。

クラス概要

final class Socket {
}


AddressInfo クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 AddressInfo リソースを置き換える完全不透明クラスです。

クラス概要

final class AddressInfo {
}


Secure Shell2

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • SSH2 関数
    • ssh2_auth_agent — SSH の認証を、ssh agent を使って行う
    • ssh2_auth_hostbased_file — ホスト公開鍵を使用して認証を行う
    • ssh2_auth_none — "none" として認証する
    • ssh2_auth_password — SSH 上でプレーンなパスワードを使用した認証を行う
    • ssh2_auth_pubkey_file — 公開鍵を使用した認証を行う
    • ssh2_connect — SSH サーバーに接続する
    • ssh2_disconnect — Close a connection to a remote SSH server
    • ssh2_exec — リモートサーバー上でコマンドを実行する
    • ssh2_fetch_stream — 拡張データストリームを取得する
    • ssh2_fingerprint — リモートサーバーのフィンガープリントを処理する
    • ssh2_forward_accept — リスナーによって作られた接続を受け付ける
    • ssh2_forward_listen — リモートサーバー上のポートにバインドし、接続を待つ
    • ssh2_methods_negotiated — ネゴシエートされたメソッドのリストを返す
    • ssh2_poll — チャンネル/リスナー/ストリーム のイベントをポーリングする
    • ssh2_publickey_add — 認証済み公開鍵を追加する
    • ssh2_publickey_init — 公開鍵サブシステムを初期化する
    • ssh2_publickey_list — 現在認証済みの公開鍵の一覧を表示する
    • ssh2_publickey_remove — 認証済み公開鍵を取り除く
    • ssh2_scp_recv — SCP 経由でファイルを要求する
    • ssh2_scp_send — SCP 経由でファイルを送信する
    • ssh2_send_eof — ストリームに EOF を送信する
    • ssh2_sftp — SFTP サブシステムを初期化する
    • ssh2_sftp_chmod — ファイルのモードを変更する
    • ssh2_sftp_lstat — シンボリックリンクの情報を取得する
    • ssh2_sftp_mkdir — ディレクトリを作成する
    • ssh2_sftp_readlink — シンボリックリンクのターゲットを返す
    • ssh2_sftp_realpath — 指定されたパス文字列の実パスを解決する
    • ssh2_sftp_rename — リモートファイルを改名する
    • ssh2_sftp_rmdir — ディレクトリを削除する
    • ssh2_sftp_stat — リモートファイルシステム上のファイルの情報を取得する
    • ssh2_sftp_symlink — シンボリックリンクを作成する
    • ssh2_sftp_unlink — ファイルを削除する
    • ssh2_shell — 対話式のシェルを要求する
    • ssh2_tunnel — リモートサーバーを経由するトンネルをオープンする


はじめに

安全な暗号化通信を使用したリモートマシン上にあるリソースへのアクセス手段 (シェル、リモート実行、トンネリング、ファイル転送) を提供する » libssh2 のバインディングです。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SSH2
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

» OpenSSL および » libssh2 ライブラリは必須です。 開発用のライブラリがインストールされていることを確認しておきましょう。 おそらく openssl-dev のような名前のパッケージになっているでしょう。

libssh2 ライブラリのバージョン 1.2 以降が必須となります。しかし、 pecl/ssh2 の新しいリリースでは、より新しいバージョンを要求することになるかもしれません (リリースノートを参照ください)。

ssh2_auth_agent() 関数を使うには、 libssh >= 1.2.3 が必要です。

チャネルストリームで stream_set_timeout() に対応するには、 libssh >= 1.2.9 が必要です。

libssh2 には二種類の形式があります。gcrypt を使ったものと openssl を使ったものです。 libssh2 のビルドに gcrypt ライブラリを使っている Linux ディストリビューションもあれば、 そうではなく openssl を使っているものもあります。 libssh2 を gcrypt でコンパイルしたときにはいくつかの問題が発生するので、openssl を使いましょう。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ssh2.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


リソース型

この拡張モジュールは、以下のリソース型を定義しています:

  • SSH2 セッション
  • SSH2 リスナー
  • SSH2 SFTP
  • SSH2 公開鍵サブシステム (ssh2 0.10 以降)


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SSH2_FINGERPRINT_MD5 (int)
ホスト鍵のフィンガープリントを MD5 ハッシュとして要求する ssh2_fingerprint() 用フラグ
SSH2_FINGERPRINT_SHA1 (int)
ホスト鍵のフィンガープリントを SHA1 ハッシュとして要求する ssh2_fingerprint() 用フラグ
SSH2_FINGERPRINT_HEX (int)
ホスト鍵のフィンガープリントを 16 進法の文字列として要求する ssh2_fingerprint() 用フラグ
SSH2_FINGERPRINT_RAW (int)
ホスト鍵のフィンガープリントを 8 ビットキャラクタの文字列として要求する ssh2_fingerprint() 用フラグ
SSH2_TERM_UNIT_CHARS (int)
文字単位で 幅 と 高さ を指定するための ssh2_shell() 用フラグ
SSH2_TERM_UNIT_PIXELS (int)
ピクセル単位で 幅 と 高さ を指定するための ssh2_shell() 用フラグ
SSH2_DEFAULT_TERM_WIDTH (int)
ssh2_shell() で要求されるデフォルトのターミナル幅
SSH2_DEFAULT_TERM_HEIGHT (int)
ssh2_shell() で要求されるデフォルトのターミナル高さ
SSH2_DEFAULT_TERM_UNIT (int)
ssh2_shell() で要求されるデフォルトのターミナル単位
SSH2_STREAM_STDIO (int)
STDIO サブチャネルを要求する ssh2_fetch_stream() 用フラグ
SSH2_STREAM_STDERR (int)
STDERR サブチャネルを要求する ssh2_fetch_stream() 用フラグ
SSH2_DEFAULT_TERMINAL (string)
ssh2_shell() によって要求される デフォルトのターミナル型 (例えば vt102, ansi, xterm, vanilla)
SSH2_POLLIN (int)
SSH2_POLLEXT (int)
SSH2_POLLOUT (int)
SSH2_POLLERR (int)
SSH2_POLLHUP (int)
SSH2_POLLNVAL (int)
SSH2_POLL_SESSION_CLOSED (int)
SSH2_POLL_CHANNEL_CLOSED (int)
SSH2_POLL_LISTENER_CLOSED (int)


SSH2 関数

目次

  • ssh2_auth_agent — SSH の認証を、ssh agent を使って行う
  • ssh2_auth_hostbased_file — ホスト公開鍵を使用して認証を行う
  • ssh2_auth_none — "none" として認証する
  • ssh2_auth_password — SSH 上でプレーンなパスワードを使用した認証を行う
  • ssh2_auth_pubkey_file — 公開鍵を使用した認証を行う
  • ssh2_connect — SSH サーバーに接続する
  • ssh2_disconnect — Close a connection to a remote SSH server
  • ssh2_exec — リモートサーバー上でコマンドを実行する
  • ssh2_fetch_stream — 拡張データストリームを取得する
  • ssh2_fingerprint — リモートサーバーのフィンガープリントを処理する
  • ssh2_forward_accept — リスナーによって作られた接続を受け付ける
  • ssh2_forward_listen — リモートサーバー上のポートにバインドし、接続を待つ
  • ssh2_methods_negotiated — ネゴシエートされたメソッドのリストを返す
  • ssh2_poll — チャンネル/リスナー/ストリーム のイベントをポーリングする
  • ssh2_publickey_add — 認証済み公開鍵を追加する
  • ssh2_publickey_init — 公開鍵サブシステムを初期化する
  • ssh2_publickey_list — 現在認証済みの公開鍵の一覧を表示する
  • ssh2_publickey_remove — 認証済み公開鍵を取り除く
  • ssh2_scp_recv — SCP 経由でファイルを要求する
  • ssh2_scp_send — SCP 経由でファイルを送信する
  • ssh2_send_eof — ストリームに EOF を送信する
  • ssh2_sftp — SFTP サブシステムを初期化する
  • ssh2_sftp_chmod — ファイルのモードを変更する
  • ssh2_sftp_lstat — シンボリックリンクの情報を取得する
  • ssh2_sftp_mkdir — ディレクトリを作成する
  • ssh2_sftp_readlink — シンボリックリンクのターゲットを返す
  • ssh2_sftp_realpath — 指定されたパス文字列の実パスを解決する
  • ssh2_sftp_rename — リモートファイルを改名する
  • ssh2_sftp_rmdir — ディレクトリを削除する
  • ssh2_sftp_stat — リモートファイルシステム上のファイルの情報を取得する
  • ssh2_sftp_symlink — シンボリックリンクを作成する
  • ssh2_sftp_unlink — ファイルを削除する
  • ssh2_shell — 対話式のシェルを要求する
  • ssh2_tunnel — リモートサーバーを経由するトンネルをオープンする


SSH の認証を、ssh agent を使って行う

  • ≪ SSH2 関数
  • ssh2_auth_hostbased_file ≫
  • PHP Manual
  • SSH2 関数
  • SSH の認証を、ssh agent を使って行う

ssh2_auth_agent

(PECL ssh2 >= 0.12)

ssh2_auth_agent — SSH の認証を、ssh agent を使って行う

説明

ssh2_auth_agent(resource $session, string $username): bool

SSH の認証を、ssh agent を使って行います。

注意: ssh2_auth_agent() 関数が使えるのは、 ssh2 拡張モジュールのコンパイルに libssh >= 1.2.3 を使った場合だけです。

パラメータ

session

SSH 接続リンク ID。 ssh2_connect() を呼んで取得したもの。

username

リモートのユーザー名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ssh agent による認証

<?php
$connection = ssh2_connect('shell.example.com', 22);

if (ssh2_auth_agent($connection, 'username')) {
echo "Authentication Successful!\n";
} else {
die('Authentication Failed...');
}
?>


ホスト公開鍵を使用して認証を行う

  • ≪ ssh2_auth_agent
  • ssh2_auth_none ≫
  • PHP Manual
  • SSH2 関数
  • ホスト公開鍵を使用して認証を行う

ssh2_auth_hostbased_file

(PECL ssh2 >= 0.9.0)

ssh2_auth_hostbased_file — ホスト公開鍵を使用して認証を行う

説明

ssh2_auth_hostbased_file(
resource $session,
string $username,
string $hostname,
string $pubkeyfile,
string $privkeyfile,
string $passphrase = ?,
string $local_username = ?
): bool

ファイルから読み込まれたホスト公開鍵を使用して認証を行います。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

hostname

pubkeyfile

privkeyfile

passphrase

もし privkeyfile が暗号化されている (そのはずです) 場合、パスフレーズを渡す必要があります。

local_username

もし local_username を省略した場合、 username の値を使用します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ホスト公開鍵を使用した認証

<?php
$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));

if (ssh2_auth_hostbased_file($connection, 'remoteusername', 'myhost.example.com',
'/usr/local/etc/hostkey_rsa.pub',
'/usr/local/etc/hostkey_rsa', 'secret',
'localusername')) {
echo "Public Key Hostbased Authentication Successful\n";
} else {
die('Public Key Hostbased Authentication Failed');
}
?>

注意

注意:

ssh2_auth_hostbased_file() には libssh2 >= 0.7 と PHP/SSH2 >= 0.7 が必要です。


"none" として認証する

  • ≪ ssh2_auth_hostbased_file
  • ssh2_auth_password ≫
  • PHP Manual
  • SSH2 関数
  • "none" として認証する

ssh2_auth_none

(PECL ssh2 >= 0.9.0)

ssh2_auth_none — "none" として認証する

説明

ssh2_auth_none(resource $session, string $username): mixed

通常失敗する（そしてそうあるべき）"none" 認証を試みます。 失敗の一環として、サーバーは可能な認証メソッドの一覧を返します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

リモートのユーザー名。

戻り値

もしサーバーが username に対する認証メソッドとして "none" を受け入れる場合、この関数は単純に true を返します。

例

例1 認証メソッドの一覧の取得

<?php
$connection = ssh2_connect('shell.example.com', 22);

$auth_methods = ssh2_auth_none($connection, 'user');

if (in_array('password', $auth_methods)) {
echo "Server supports password based authentication\n";
}
?>


SSH 上でプレーンなパスワードを使用した認証を行う

  • ≪ ssh2_auth_none
  • ssh2_auth_pubkey_file ≫
  • PHP Manual
  • SSH2 関数
  • SSH 上でプレーンなパスワードを使用した認証を行う

ssh2_auth_password

(PECL ssh2 >= 0.9.0)

ssh2_auth_password — SSH 上でプレーンなパスワードを使用した認証を行う

説明

ssh2_auth_password(resource $session, string $username, string $password): bool

SSH 上でプレーンなパスワードを使用した認証を行います。 バージョン 0.12 以降、この関数は keyboard_interactive 方式にも対応するようになりました。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

リモートのユーザー名。

password

username のパスワード。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 パスワードを用いた認証

<?php
$connection = ssh2_connect('shell.example.com', 22);

if (ssh2_auth_password($connection, 'username', 'secret')) {
echo "Authentication Successful!\n";
} else {
die('Authentication Failed...');
}
?>


公開鍵を使用した認証を行う

  • ≪ ssh2_auth_password
  • ssh2_connect ≫
  • PHP Manual
  • SSH2 関数
  • 公開鍵を使用した認証を行う

ssh2_auth_pubkey_file

(PECL ssh2 >= 0.9.0)

ssh2_auth_pubkey_file — 公開鍵を使用した認証を行う

説明

ssh2_auth_pubkey_file(
resource $session,
string $username,
string $pubkeyfile,
string $privkeyfile,
string $passphrase = ?
): bool

ファイルから読み込んだ公開鍵を使用した認証を行います。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

username

pubkeyfile

公開鍵ファイル。OpenSSH 形式で表す必要があり、たとえば次のようになります。

ssh-rsa AAAAB3NzaC1yc2EAAA....NX6sqSnHA8= rsa-key-20121110

privkeyfile

passphrase

もし、privkeyfile が暗号化されている (そうあるべきです) 場合、パスフレーズも引数に渡す必要があります。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 公開鍵を用いた認証

<?php
$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));

if (ssh2_auth_pubkey_file($connection, 'username',
'/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa', 'secret')) {
echo "Public Key Authentication Successful\n";
} else {
die('Public Key Authentication Failed');
}
?>

注意

注意:

この関数が使っている libssh ライブラリは、部分的な認証のサポートがうまくできません。 公開鍵とパスワードの両方が必要な場合に、まるで関数が失敗したかのように見えてしまいます。 この場合の関数呼び出しの失敗は、単に認証がまだ完了していないということを表しているにすぎません。 この呼び出し失敗は無視し、続けて ssh2_auth_password() を呼ばなければ認証は完了しません。


SSH サーバーに接続する

  • ≪ ssh2_auth_pubkey_file
  • ssh2_disconnect ≫
  • PHP Manual
  • SSH2 関数
  • SSH サーバーに接続する

ssh2_connect

(PECL ssh2 >= 0.9.0)

ssh2_connect — SSH サーバーに接続する

説明

ssh2_connect(
string $host,
int $port = 22,
array $methods = ?,
array $callbacks = ?
): resource|false

リモートの SSH サーバーとの接続を確立します。

一度接続すると、クライアントは ssh2_fingerprint() を使用してサーバーのホスト鍵を検証し、 パスワードもしくは公開鍵を使用して認証します。

パラメータ

host

port

methods

methods は以下に示された4つのパラメータを持つ連想配列です。

methods は以下のパラメータのいくつかあるいは全てを含む連想配列
インデックス | 意味 | サポートする値*
kex | 通知する鍵交換メソッドのリスト。優先する順にカンマ区切りにする。 | diffie-hellman-group1-sha1、 diffie-hellman-group14-sha1 および diffie-hellman-group-exchange-sha1
hostkey | 通知するホスト鍵メソッドのリスト。優先する順にカンマ区切りにする。 | ssh-rsa および ssh-dss
client_to_server | クライアントからサーバーに送信されるメッセージのために優先する暗号化、 圧縮、メッセージ認証コード (MAC) メソッドを含む連想配列。
server_to_client | サーバーからクライアントに送信されるメッセージのために優先する暗号化、 圧縮、メッセージ認証コード (MAC) メソッドを含む連想配列。

* - サポートする値は、 構成するライブラリがサポートしているメソッドに依存します。 追加情報については » libssh2 ドキュメントを参照ください。

client_to_server と server_to_client は以下のパラメータのいくつかあるいは全てを含む連想配列
インデックス | 意味 | サポートする値*
crypt | 通知する暗号化メソッドのリスト。 優先する順にカンマ区切りにする。 | rijndael-cbc@lysator.liu.se、 aes256-cbc、 aes192-cbc、 aes128-cbc、 3des-cbc、 blowfish-cbc、 cast128-cbc、 arcfour および none**
comp | 通知する圧縮メソッドのリスト。 優先する順にカンマ区切りにする。 | zlib および none
mac | 通知する MAC メソッドのリスト。 優先する順にカンマ区切りにする。 | hmac-sha1、 hmac-sha1-96、 hmac-ripemd160、 hmac-ripemd160@openssh.com および none**

注意: 暗号化、MAC メソッドの "none"

セキュリティ上の問題で、none は ビルド時に適切な ./configure オプションを使用して明示的に有効にしない限り、構成している » libssh2 によって無効にされます。 詳細は構成するライブラリのドキュメントを参照ください。

callbacks

callbacks は以下のパラメータのいくつかあるいは全てを含む連想配列

コールバックパラメータ
インデックス | 意味 | プロトタイプ
ignore | SSH2_MSG_IGNORE パケットを受信したときにコールする関数名 | void ignore_cb($message)
debug | SSH2_MSG_DEBUG パケットを受信したときにコールする関数名 | void debug_cb($message, $language, $always_display)
macerror | パケットを受信したがメッセージ認証コードに失敗した場合にコールされる関数名。 もしコールバックが true を返す場合、不整合は無視されます。 そうでない場合、接続は終了します。 | bool macerror_cb($packet)
disconnect | SSH2_MSG_DISCONNECT パケットを受信したときにコールする関数名 | void disconnect_cb($reason, $message, $language)

戻り値

成功した場合にリソース、エラー時に false を返します。

例

例1 ssh2_connect() の例

パケット送信時に 3des-cbc 、 パケット受信時に任意の強度の aes cipher、 両方向で無圧縮、 Group1 での鍵交換という設定で強制的に接続をオープンします。

<?php
/* もしサーバーが接続を終了した場合、ユーザーに通知する */
function my_ssh_disconnect($reason, $message, $language) {
printf("Server disconnected with reason code [%d] and message: %s\n",
$reason, $message);
}

$methods = array(
'kex' => 'diffie-hellman-group1-sha1',
'client_to_server' => array(
'crypt' => '3des-cbc',
'comp' => 'none'),
'server_to_client' => array(
'crypt' => 'aes256-cbc,aes192-cbc,aes128-cbc',
'comp' => 'none'));

$callbacks = array('disconnect' => 'my_ssh_disconnect');

$connection = ssh2_connect('shell.example.com', 22, $methods, $callbacks);
if (!$connection) die('Connection failed');
?>

参考

  • ssh2_fingerprint() - リモートサーバーのフィンガープリントを処理する
  • ssh2_auth_none() - "none" として認証する
  • ssh2_auth_password() - SSH 上でプレーンなパスワードを使用した認証を行う
  • ssh2_auth_pubkey_file() - 公開鍵を使用した認証を行う
  • ssh2_disconnect() - Close a connection to a remote SSH server


Close a connection to a remote SSH server

  • ≪ ssh2_connect
  • ssh2_exec ≫
  • PHP Manual
  • SSH2 関数
  • Close a connection to a remote SSH server

ssh2_disconnect

(PECL ssh2 >= 1.0)

ssh2_disconnect — Close a connection to a remote SSH server

説明

ssh2_disconnect(resource $session): bool

Close a connection to a remote SSH server.

パラメータ

session

An SSH connection link identifier, obtained from a call to ssh2_connect().

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ssh2_connect() - SSH サーバーに接続する


リモートサーバー上でコマンドを実行する

  • ≪ ssh2_disconnect
  • ssh2_fetch_stream ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバー上でコマンドを実行する

ssh2_exec

(PECL ssh2 >= 0.9.0)

ssh2_exec — リモートサーバー上でコマンドを実行する

説明

ssh2_exec(
resource $session,
string $command,
string $pty = ?,
array $env = ?,
int $width = 80,
int $height = 25,
int $width_height_type = SSH2_TERM_UNIT_CHARS
): resource|false

コマンドをリモートエンドで実行し、チャネルを割り当てます。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

command

pty

env

env には、 対象となる環境で設定する名前/値のペアを連想配列で渡します。

width

仮想端末の幅。

height

仮想端末の高さ。

width_height_type

width_height_type は、 SSH2_TERM_UNIT_CHARS あるいは SSH2_TERM_UNIT_PIXELS のいずれかです。

戻り値

成功時にストリームを返し、失敗した場合に false を返します。

例

例1 コマンドの実行

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_exec($connection, '/usr/local/bin/php -i');
?>

参考

  • ssh2_connect() - SSH サーバーに接続する
  • ssh2_shell() - 対話式のシェルを要求する
  • ssh2_tunnel() - リモートサーバーを経由するトンネルをオープンする


拡張データストリームを取得する

  • ≪ ssh2_exec
  • ssh2_fingerprint ≫
  • PHP Manual
  • SSH2 関数
  • 拡張データストリームを取得する

ssh2_fetch_stream

(PECL ssh2 >= 0.9.0)

ssh2_fetch_stream — 拡張データストリームを取得する

説明

ssh2_fetch_stream(resource $channel, int $streamid): resource

SSH2 チャネルストリームと関連付けられたサブストリームを取得します。 SSH2 プロトコルは現在ただ 1 つのサブストリーム STDERR を定義しています。これはサブストリーム ID として SSH2_STREAM_STDERR (1 として定義) を持ちます。

パラメータ

channel

streamid

SSH2 チャネルストリーム。

戻り値

ストリームリソースを返します。

例

例1 シェルをオープンし、それと関連付けられた stderr ストリームを処理する

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stdio_stream = ssh2_shell($connection);
$stderr_stream = ssh2_fetch_stream($stdio_stream, SSH2_STREAM_STDERR);
?>

参考

  • ssh2_shell() - 対話式のシェルを要求する
  • ssh2_exec() - リモートサーバー上でコマンドを実行する
  • ssh2_connect() - SSH サーバーに接続する


リモートサーバーのフィンガープリントを処理する

  • ≪ ssh2_fetch_stream
  • ssh2_forward_accept ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバーのフィンガープリントを処理する

ssh2_fingerprint

(PECL ssh2 >= 0.9.0)

ssh2_fingerprint — リモートサーバーのフィンガープリントを処理する

説明

ssh2_fingerprint(resource $session, int $flags = SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX): string

アクティブなセッションからサーバーホスト鍵のハッシュを返します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

flags

flags は SSH2_FINGERPRINT_MD5、 SSH2_FINGERPRINT_HEX で論理和された SSH2_FINGERPRINT_SHA1、 SSH2_FINGERPRINT_RAW のいずれかです。

戻り値

ホストキーのハッシュを文字列で返します。

例

例1 既知の値に対するフィンガープリントのチェック

<?php
$known_host = '6F89C2F0A719B30CC38ABDF90755F2E4';

$connection = ssh2_connect('shell.example.com', 22);

$fingerprint = ssh2_fingerprint($connection,
SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX);

if ($fingerprint != $known_host) {
die("HOSTKEY MISMATCH!\n" .
"Possible Man-In-The-Middle Attack?");
}
?>


リスナーによって作られた接続を受け付ける

  • ≪ ssh2_fingerprint
  • ssh2_forward_listen ≫
  • PHP Manual
  • SSH2 関数
  • リスナーによって作られた接続を受け付ける

ssh2_forward_accept

(PECL ssh2 >= 0.9.0)

ssh2_forward_accept — リスナーによって作られた接続を受け付ける

説明

ssh2_forward_accept(resource $listener): resource|false

リスナーによって作られた接続を受け付けます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

desc

SSH2 リスナーのリソースを指定します。 これは、ssh2_forward_listen() を呼び出すことで得られます。

戻り値

ストリームリソースを返します。 失敗した場合に false を返します.


リモートサーバー上のポートにバインドし、接続を待つ

  • ≪ ssh2_forward_accept
  • ssh2_methods_negotiated ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバー上のポートにバインドし、接続を待つ

ssh2_forward_listen

(PECL ssh2 >= 0.9.0)

ssh2_forward_listen — リモートサーバー上のポートにバインドし、接続を待つ

説明

ssh2_forward_listen(
resource $session,
int $port,
string $host = ?,
int $max_connections = 16
): resource|false

リモートサーバー上のポートにバインドし、接続を待ちます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

session

SSH セッションのリソースを指定します。 この値は、ssh2_connect() を呼び出すことで得られます。

port

リモートサーバー上のポート番号を指定します。

host

max_connections

戻り値

SSH2 リスナーを返します。 失敗した場合に false を返します.

参考

  • ssh2_forward_accept() - リスナーによって作られた接続を受け付ける


ネゴシエートされたメソッドのリストを返す

  • ≪ ssh2_forward_listen
  • ssh2_poll ≫
  • PHP Manual
  • SSH2 関数
  • ネゴシエートされたメソッドのリストを返す

ssh2_methods_negotiated

(PECL ssh2 >= 0.9.0)

ssh2_methods_negotiated — ネゴシエートされたメソッドのリストを返す

説明

ssh2_methods_negotiated(resource $session): array

ネゴシエートされたメソッドのリストを返します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

戻り値

例

例1 どのメソッドでネゴシエートされたかの判定

<?php
$connection = ssh2_connect('shell.example.com', 22);
$methods = ssh2_methods_negotiated($connection);

echo "Encryption keys were negotiated using: {$methods['kex']}\n";
echo "Server identified using an {$methods['hostkey']} with ";
echo "fingerprint: " . ssh2_fingerprint($connection) . "\n";

echo "Client to Server packets will use methods:\n";
echo "\tCrypt: {$methods['client_to_server']['crypt']}\n";
echo "\tComp: {$methods['client_to_server']['comp']}\n";
echo "\tMAC: {$methods['client_to_server']['mac']}\n";

echo "Server to Client packets will use methods:\n";
echo "\tCrypt: {$methods['server_to_client']['crypt']}\n";
echo "\tComp: {$methods['server_to_client']['comp']}\n";
echo "\tMAC: {$methods['server_to_client']['mac']}\n";

?>

参考

  • ssh2_connect() - SSH サーバーに接続する


チャンネル/リスナー/ストリーム のイベントをポーリングする

  • ≪ ssh2_methods_negotiated
  • ssh2_publickey_add ≫
  • PHP Manual
  • SSH2 関数
  • チャンネル/リスナー/ストリーム のイベントをポーリングする

ssh2_poll

(PECL ssh2 >= 0.9.0)

ssh2_poll — チャンネル/リスナー/ストリーム のイベントをポーリングする

説明

ssh2_poll(array &$desc, int $timeout = 30): int

チャンネル/リスナー/ストリーム のイベントをポーリングし、 1個以上のイベントを返したディスクリプタの数を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

desc

'resource' と 'events' をキーとした配列の、インデックス付きの配列。 リソースの値は、(チャンネルの)ストリーム、 または SSH2 リスナーのリソースです。 イベントの値は、SSH2_POLL* フラグを bitwise OR でまとめて指定します。 それぞれの配列は、返される際に 'revents' 要素にまとめられ、 発生したイベントの SSH2_POLL* フラグが bitwize OR でまとまったものがその値になります。

timeout

タイムアウトさせる時間を秒単位で指定します。

戻り値

1個以上のイベントを返したディスクリプタの数を返します。


認証済み公開鍵を追加する

  • ≪ ssh2_poll
  • ssh2_publickey_init ≫
  • PHP Manual
  • SSH2 関数
  • 認証済み公開鍵を追加する

ssh2_publickey_add

(PECL ssh2 >= 0.10)

ssh2_publickey_add — 認証済み公開鍵を追加する

説明

ssh2_publickey_add(
resource $pkey,
string $algoname,
string $blob,
bool $overwrite = false,
array $attributes = ?
): bool

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

パラメータ

pkey

ssh2_publickey_init() が作成した、 公開鍵サブシステムのリソース。

algoname

公開鍵のアルゴリズム。例: ssh-dss、ssh-rsa

blob

生のバイナリデータとしての blob 形式の公開鍵。

overwrite

指定したキーがすでに存在する場合に、それを上書きしますか?

attributes

この公開鍵に代入する属性の連想配列。サポートされる属性の一覧は、 ietf-secsh-publickey-subsystem を参照ください。 必須属性を設定するには、属性名の先頭にアスタリスクをつけてください。 サーバーが必須属性をサポートしていない場合、追加処理は異常終了します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ssh2_publickey_add() で公開鍵を追加する

<?php
$ssh2 = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($ssh2, 'jdoe', 'password');
$pkey = ssh2_publickey_init($ssh2);

$keyblob = base64_decode('
AAAAB3NzaC1yc2EAAAABIwAAAIEA5HVt6VqSGd5PTrLRdjNONxXH1tVFGn0
Bd26BF0aCP9qyJRlvdJ3j4WBeX4ZmrveGrjMgkseSYc4xZ26sDHwfL351xj
zaLpipu\BGRrw17mWVBhuCExo476ri5tQFzbTc54VEHYckxQ16CjSTibI5X
69GmnYC9PNqEYq/1TP+HF10=');

ssh2_publickey_add($pkey, 'ssh-rsa', $keyblob, false, array('comment'=>"John's Key"));
?>

参考

  • ssh2_publickey_init() - 公開鍵サブシステムを初期化する
  • ssh2_publickey_remove() - 認証済み公開鍵を取り除く
  • ssh2_publickey_list() - 現在認証済みの公開鍵の一覧を表示する


公開鍵サブシステムを初期化する

  • ≪ ssh2_publickey_add
  • ssh2_publickey_list ≫
  • PHP Manual
  • SSH2 関数
  • 公開鍵サブシステムを初期化する

ssh2_publickey_init

(PECL ssh2 >= 0.10)

ssh2_publickey_init — 公開鍵サブシステムを初期化する

説明

ssh2_publickey_init(resource $session): resource|false

すでに接続している SSH2 サーバーから、公開鍵サブシステムを要求します。

公開鍵サブシステムを使用すると、 すでに接続・認証済みのクライアントが、 対象のサーバーに保存されている認証済み公開鍵の一覧を管理できるようになります。 管理方法は、サーバーの実装に依存しません。 リモートサーバーが公開鍵サブシステムをサポートしていない場合、 ssh2_publickey_init() 関数は false を返します。

パラメータ

session

戻り値

他のすべての ssh2_publickey_*() メソッドで使用する、 SSH2 公開鍵サブシステムリソースを返します。 失敗した場合に false を返します。

注意

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

参考

  • ssh2_publickey_add() - 認証済み公開鍵を追加する
  • ssh2_publickey_remove() - 認証済み公開鍵を取り除く
  • ssh2_publickey_list() - 現在認証済みの公開鍵の一覧を表示する


現在認証済みの公開鍵の一覧を表示する

  • ≪ ssh2_publickey_init
  • ssh2_publickey_remove ≫
  • PHP Manual
  • SSH2 関数
  • 現在認証済みの公開鍵の一覧を表示する

ssh2_publickey_list

(PECL ssh2 >= 0.10)

ssh2_publickey_list — 現在認証済みの公開鍵の一覧を表示する

説明

ssh2_publickey_list(resource $pkey): array

現在認証済みの公開鍵の一覧を表示します。

パラメータ

pkey

公開鍵サブシステムのリソース。

戻り値

鍵を、数値添字の配列で返します。 個々の要素は連想配列となっており、その内容は name、blob、および attrs です。

公開鍵の要素
配列のキー | 意味
name | この公開鍵で使用しているアルゴリズムの名前。例: ssh-dss あるいは ssh-rsa。
blob | 生のバイナリデータとしての blob 形式の公開鍵。
attrs | この公開鍵に割り当てる属性。 もっとも一般的な属性であり、バージョン 1 の公開鍵サーバーが唯一サポートしている属性は comment です。これは任意の書式の文字列です。

例

例1 認証済みの鍵の一覧を ssh2_publickey_list() で表示する

<?php
$ssh2 = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($ssh2, 'jdoe', 'secret');
$pkey = ssh2_publickey_init($ssh2);

$list = ssh2_publickey_list($pkey);

foreach($list as $key) {
echo "Key: {$key['name']}\n";
echo "Blob: " . chunk_split(base64_encode($key['blob']), 40, "\n") . "\n";
echo "Comment: {$key['attrs']['comment']}\n\n";
}
?>

上の例の出力は以下となります。

Key: ssh-rsa
Blob: AAAAB3NzaC1yc2EAAAABIwAAAIEA5HVt6VqSGd5P
TrLRdjNONxXH1tVFGn0Bd26BF0aCP9qyJRlvdJ3j
4WBeX4ZmrveGrjMgkseSYc4xZ26sDHwfL351xjza
Lpipu\BGRrw17mWVBhuCExo476ri5tQFzbTc54VE
HYckxQ16CjSTibI5X69GmnYC9PNqEYq/1TP+HF10
Comment: John's Key

Key: ssh-rsa
Blob: AAAAB3NzaHVt6VqSGd5C1yc2EAAAABIwA232dnJA
AIEA5HVt6VqSGd5PTrLRdjNONxX/1TP+HF1HVt6V
qSGd50H1tVFGn0BB3NzaC1yc2EAd26BF0aCP9qyJ
RlvdJ3j4WBeX4ZmrveGrjMgkseSYc4xZ26HVt6Vq
SGd5sDHwfL351xjzaLpipu\BGB3NzaC1yc2EA/1T
Comment: Alice's Key

注意

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

参考

  • ssh2_publickey_init() - 公開鍵サブシステムを初期化する
  • ssh2_publickey_add() - 認証済み公開鍵を追加する
  • ssh2_publickey_remove() - 認証済み公開鍵を取り除く


認証済み公開鍵を取り除く

  • ≪ ssh2_publickey_list
  • ssh2_scp_recv ≫
  • PHP Manual
  • SSH2 関数
  • 認証済み公開鍵を取り除く

ssh2_publickey_remove

(PECL ssh2 >= 0.10)

ssh2_publickey_remove — 認証済み公開鍵を取り除く

説明

ssh2_publickey_remove(resource $pkey, string $algoname, string $blob): bool

認証済み公開鍵を取り除きます。

パラメータ

pkey

公開鍵サブシステムのリソース。

algoname

公開鍵のアルゴリズム。例: ssh-dss、ssh-rsa

blob

生のバイナリデータとしての blob 形式の公開鍵。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

注意: この公開鍵サブシステムは、クライアントが認証 済 の 公開鍵をサーバー上で管理するために使用されます。 公開鍵認証によりリモートシステムで認証を行うには、かわりに ssh2_auth_pubkey_file() 関数を使用してください。

参考

  • ssh2_publickey_init() - 公開鍵サブシステムを初期化する
  • ssh2_publickey_add() - 認証済み公開鍵を追加する
  • ssh2_publickey_list() - 現在認証済みの公開鍵の一覧を表示する


SCP 経由でファイルを要求する

  • ≪ ssh2_publickey_remove
  • ssh2_scp_send ≫
  • PHP Manual
  • SSH2 関数
  • SCP 経由でファイルを要求する

ssh2_scp_recv

(PECL ssh2 >= 0.9.0)

ssh2_scp_recv — SCP 経由でファイルを要求する

説明

ssh2_scp_recv(resource $session, string $remote_file, string $local_file): bool

リモートサーバーからローカルファイルシステムに SCP プロトコルを使用してコピーします。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

remote_file

リモートファイルへのパス。

local_file

ローカルファイルへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SCP 経由でのファイルのダウンロード

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

ssh2_scp_recv($connection, '/remote/filename', '/local/filename');
?>

参考

  • ssh2_scp_send() - SCP 経由でファイルを送信する
  • copy() - ファイルをコピーする


SCP 経由でファイルを送信する

  • ≪ ssh2_scp_recv
  • ssh2_send_eof ≫
  • PHP Manual
  • SSH2 関数
  • SCP 経由でファイルを送信する

ssh2_scp_send

(PECL ssh2 >= 0.9.0)

ssh2_scp_send — SCP 経由でファイルを送信する

説明

ssh2_scp_send(
resource $session,
string $local_file,
string $remote_file,
int $create_mode = 0644
): bool

ローカルファイルシステムからリモートサーバーに SCP プロトコルを使用してコピーします。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

local_file

ローカルファイルへのパス。

remote_file

リモートファイルへのパス。

create_mode

ファイルは create_mode で指定されたモードで作成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SCP 経由でのファイルのアップロード

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

ssh2_scp_send($connection, '/local/filename', '/remote/filename', 0644);
?>

参考

  • ssh2_scp_recv() - SCP 経由でファイルを要求する
  • copy() - ファイルをコピーする


ストリームに EOF を送信する

  • ≪ ssh2_scp_send
  • ssh2_sftp ≫
  • PHP Manual
  • SSH2 関数
  • ストリームに EOF を送信する

ssh2_send_eof

(PECL ssh2 >= 1.3)

ssh2_send_eof — ストリームに EOF を送信する

説明

ssh2_send_eof(resource $channel): bool

ストリームに EOF を送信します。 この関数は通常、標準入力をクローズしつつ、 標準出力と標準エラー出力は活かしておく用途に使います。 たとえば、リモートのプロセスに標準入力経由でデータを送信し、 処理する際にはそれをクローズします。 そうすれば、追加のファイルを作ることなく、 処理結果を読み取ることが出来ます。

パラメータ

channel

SSH のストリーム。 ssh2_fetch_stream() や ssh2_connect() のような関数から取得できます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ssh2_fetch_stream() - 拡張データストリームを取得する


SFTP サブシステムを初期化する

  • ≪ ssh2_send_eof
  • ssh2_sftp_chmod ≫
  • PHP Manual
  • SSH2 関数
  • SFTP サブシステムを初期化する

ssh2_sftp

(PECL ssh2 >= 0.9.0)

ssh2_sftp — SFTP サブシステムを初期化する

説明

ssh2_sftp(resource $session): resource|false

すでに接続された SSH2 サーバーから SFTP サブシステムを要求します。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

戻り値

このメソッドは全ての他の ssh2_sftp_*() や ssh2.sftp:// fopen ラッパーで使用する SSH2 SFTP リソースを返します。 失敗した場合に false を返します

例

例1 SFTP 経由でのファイルのオープン

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);

$stream = fopen('ssh2.sftp://' . intval($sftp) . '/path/to/file', 'r');
?>

参考

  • ssh2_scp_recv() - SCP 経由でファイルを要求する
  • ssh2_scp_send() - SCP 経由でファイルを送信する


ファイルのモードを変更する

  • ≪ ssh2_sftp
  • ssh2_sftp_lstat ≫
  • PHP Manual
  • SSH2 関数
  • ファイルのモードを変更する

ssh2_sftp_chmod

(PECL ssh2 >= 0.12)

ssh2_sftp_chmod — ファイルのモードを変更する

説明

ssh2_sftp_chmod(resource $sftp, string $filename, int $mode): bool

指定したファイルのモードの mode への変更を試みます。

パラメータ

sftp

SSH2 SFTP リソース。ssh2_sftp() で開いたもの。

filename

ファイルへのパス。

mode

ファイルのパーミッション。このパラメータの詳細は chmod() を参照ください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 リモートサーバー上でのファイルのモード変更

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_chmod($sftp, '/somedir/somefile', 0755);
?>

参考

  • chmod() - ファイルのモードを変更する
  • ssh2_sftp() - SFTP サブシステムを初期化する
  • ssh2_connect() - SSH サーバーに接続する


シンボリックリンクの情報を取得する

  • ≪ ssh2_sftp_chmod
  • ssh2_sftp_mkdir ≫
  • PHP Manual
  • SSH2 関数
  • シンボリックリンクの情報を取得する

ssh2_sftp_lstat

(PECL ssh2 >= 0.9.0)

ssh2_sftp_lstat — シンボリックリンクの情報を取得する

説明

ssh2_sftp_lstat(resource $sftp, string $path): array

リンクを辿らないで リモートファイルシステムのシンボリックリンクの情報を取得します。

この関数は ssh2.sftp:// ラッパーを使用した場合の lstat() 関数と同様です。 戻り値も同じです。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

path

リモートのシンボリックリンクへのパス。

戻り値

戻り値の詳細については stat() のドキュメントを参照ください。

例

例1 SFTP 経由でのシンボリックリンクの情報の取得

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);
$statinfo = ssh2_sftp_lstat($sftp, '/path/to/symlink');

$filesize = $statinfo['size'];
$group = $statinfo['gid'];
$owner = $statinfo['uid'];
$atime = $statinfo['atime'];
$mtime = $statinfo['mtime'];
$mode = $statinfo['mode'];
?>

参考

  • ssh2_sftp_stat() - リモートファイルシステム上のファイルの情報を取得する
  • lstat() - ファイルあるいはシンボリックリンクの情報を取得する
  • stat() - ファイルに関する情報を取得する


ディレクトリを作成する

  • ≪ ssh2_sftp_lstat
  • ssh2_sftp_readlink ≫
  • PHP Manual
  • SSH2 関数
  • ディレクトリを作成する

ssh2_sftp_mkdir

(PECL ssh2 >= 0.9.0)

ssh2_sftp_mkdir — ディレクトリを作成する

説明

ssh2_sftp_mkdir(
resource $sftp,
string $dirname,
int $mode = 0777,
bool $recursive = false
): bool

リモートファイルサーバーに mode で指定された権限でディレクトリを作成します。

この関数は ssh2.sftp:// ラッパーを使用した場合の mkdir() と同様です。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

dirname

新しいディレクトリへのパス。

mode

新しいディレクトリのパーミッション。 実際のパーミッションの値は、現在の umask の影響を受けます。

recursive

もし recursive が true の場合、 dirname に必要とされる全ての親ディレクトリは自動的に作成されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 リモートサーバー上へのディレクトリの作成

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_mkdir($sftp, '/home/username/newdir');
/* もしくは次の通り: mkdir("ssh2.sftp://$sftp/home/username/newdir"); */
?>

参考

  • mkdir() - ディレクトリを作る
  • ssh2_sftp_rmdir() - ディレクトリを削除する


シンボリックリンクのターゲットを返す

  • ≪ ssh2_sftp_mkdir
  • ssh2_sftp_realpath ≫
  • PHP Manual
  • SSH2 関数
  • シンボリックリンクのターゲットを返す

ssh2_sftp_readlink

(PECL ssh2 >= 0.9.0)

ssh2_sftp_readlink — シンボリックリンクのターゲットを返す

説明

ssh2_sftp_readlink(resource $sftp, string $link): string

シンボリックリンクのターゲットを返します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

link

シンボリックリンクへのパス。

戻り値

シンボリックリンク link のターゲットを返します。

例

例1 シンボリックリンクの読み込み

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

$target = ssh2_sftp_readlink($sftp, '/tmp/mysql.sock');
/* $target は例えば次のような感じ: '/var/run/mysql.sock' */
?>

参考

  • readlink() - シンボリックリンク先を返す
  • ssh2_sftp_symlink() - シンボリックリンクを作成する


指定されたパス文字列の実パスを解決する

  • ≪ ssh2_sftp_readlink
  • ssh2_sftp_rename ≫
  • PHP Manual
  • SSH2 関数
  • 指定されたパス文字列の実パスを解決する

ssh2_sftp_realpath

(PECL ssh2 >= 0.9.0)

ssh2_sftp_realpath — 指定されたパス文字列の実パスを解決する

説明

ssh2_sftp_realpath(resource $sftp, string $filename): string

filename をリモートファイルシステム上の有効な実パスに変換します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

filename

戻り値

実際のパスを表す文字列を返します。

例

例1 パス名の解決

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

$realpath = ssh2_sftp_realpath($sftp, '/home/username/../../../..//./usr/../etc/passwd');
/* $realpath は次の通り: '/etc/passwd' */
?>

参考

  • realpath() - 正規化された絶対パス名を返す
  • ssh2_sftp_symlink() - シンボリックリンクを作成する
  • ssh2_sftp_readlink() - シンボリックリンクのターゲットを返す


リモートファイルを改名する

  • ≪ ssh2_sftp_realpath
  • ssh2_sftp_rmdir ≫
  • PHP Manual
  • SSH2 関数
  • リモートファイルを改名する

ssh2_sftp_rename

(PECL ssh2 >= 0.9.0)

ssh2_sftp_rename — リモートファイルを改名する

説明

ssh2_sftp_rename(resource $sftp, string $from, string $to): bool

リモートファイルシステム上のファイルを改名します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

from

名前を変更したいファイル。

to

from のかわりに新しく使用したいファイル名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 sftp 経由でのファイルの改名

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_rename($sftp, '/home/username/oldname', '/home/username/newname');
?>

参考

  • rename() - ファイルをリネームする


ディレクトリを削除する

  • ≪ ssh2_sftp_rename
  • ssh2_sftp_stat ≫
  • PHP Manual
  • SSH2 関数
  • ディレクトリを削除する

ssh2_sftp_rmdir

(PECL ssh2 >= 0.9.0)

ssh2_sftp_rmdir — ディレクトリを削除する

説明

ssh2_sftp_rmdir(resource $sftp, string $dirname): bool

リモートのファイルサーバーからディレクトリを削除します。

この関数は ssh2.sftp:// ラッパーを使用した場合の rmdir() と同様です。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

dirname

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 リモートサーバー上のディレクトリの削除

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_rmdir($sftp, '/home/username/deltodel');
/* もしくは次の通り: rmdir("ssh2.sftp://$sftp/home/username/dirtodel"); */
?>

参考

  • rmdir() - ディレクトリを削除する
  • ssh2_sftp_mkdir() - ディレクトリを作成する


リモートファイルシステム上のファイルの情報を取得する

  • ≪ ssh2_sftp_rmdir
  • ssh2_sftp_symlink ≫
  • PHP Manual
  • SSH2 関数
  • リモートファイルシステム上のファイルの情報を取得する

ssh2_sftp_stat

(PECL ssh2 >= 0.9.0)

ssh2_sftp_stat — リモートファイルシステム上のファイルの情報を取得する

説明

ssh2_sftp_stat(resource $sftp, string $path): array

シンボリックリンクを辿って リモートファイルシステム上のファイルの情報を取得します。

この関数は ssh2.sftp:// ラッパーを使用した場合の stat() 関数と同様です。 返される値も同じです。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

path

戻り値

どのような値が返されるのかについての詳細は、 stat() を参照ください。

例

例1 SFTP 経由でのファイルの情報の取得

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);
$statinfo = ssh2_sftp_stat($sftp, '/path/to/file');

$filesize = $statinfo['size'];
$group = $statinfo['gid'];
$owner = $statinfo['uid'];
$atime = $statinfo['atime'];
$mtime = $statinfo['mtime'];
$mode = $statinfo['mode'];
?>

参考

  • ssh2_sftp_lstat() - シンボリックリンクの情報を取得する
  • lstat() - ファイルあるいはシンボリックリンクの情報を取得する
  • stat() - ファイルに関する情報を取得する


シンボリックリンクを作成する

  • ≪ ssh2_sftp_stat
  • ssh2_sftp_unlink ≫
  • PHP Manual
  • SSH2 関数
  • シンボリックリンクを作成する

ssh2_sftp_symlink

(PECL ssh2 >= 0.9.0)

ssh2_sftp_symlink — シンボリックリンクを作成する

説明

ssh2_sftp_symlink(resource $sftp, string $target, string $link): bool

リモートファイルシステム上に target を指す link という名称のシンボリックリンクを作成します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

target

シンボリックリンクのリンク対象。

link

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 シンボリックリンクの作成

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_symlink($sftp, '/var/run/mysql.sock', '/tmp/mysql.sock');
?>

参考

  • ssh2_sftp_readlink() - シンボリックリンクのターゲットを返す
  • symlink() - シンボリックリンクを作成する


ファイルを削除する

  • ≪ ssh2_sftp_symlink
  • ssh2_shell ≫
  • PHP Manual
  • SSH2 関数
  • ファイルを削除する

ssh2_sftp_unlink

(PECL ssh2 >= 0.9.0)

ssh2_sftp_unlink — ファイルを削除する

説明

ssh2_sftp_unlink(resource $sftp, string $filename): bool

リモートファイルシステム上のファイルを削除します。

パラメータ

sftp

ssh2_sftp() でオープンした SSH2 SFTP リソース。

filename

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ファイルの削除

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_unlink($sftp, '/home/username/stale_file');
?>

参考

  • unlink() - ファイルを削除する


対話式のシェルを要求する

  • ≪ ssh2_sftp_unlink
  • ssh2_tunnel ≫
  • PHP Manual
  • SSH2 関数
  • 対話式のシェルを要求する

ssh2_shell

(PECL ssh2 >= 0.9.0)

ssh2_shell — 対話式のシェルを要求する

説明

ssh2_shell(
resource $session,
string $termtype = "vanilla",
?array $env = null,
int $width = 80,
int $height = 25,
int $width_height_type = SSH2_TERM_UNIT_CHARS
): resource|false

リモートエンド上のシェルをオープンし、そのためのストリームを割り当てます。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

termtype

termtype は対象システムの /etc/termcap に記載されたエントリの一つに相当します。

env

env には、 対象の環境に設定する名前/値の組の連想配列を渡すことができます。

width

仮想端末の幅。

height

仮想端末の高さ。

width_height_type

width_height_type は SSH2_TERM_UNIT_CHARS あるいは SSH2_TERM_UNIT_PIXELS のいずれかです。

戻り値

成功した場合、ストリームリソースを返します。 失敗した場合に false を返します.

例

例1 対話シェルのリクエスト

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_shell($connection, 'vt102', null, 80, 24, SSH2_TERM_UNIT_CHARS);
?>

参考

  • ssh2_exec() - リモートサーバー上でコマンドを実行する
  • ssh2_tunnel() - リモートサーバーを経由するトンネルをオープンする
  • ssh2_fetch_stream() - 拡張データストリームを取得する


リモートサーバーを経由するトンネルをオープンする

  • ≪ ssh2_shell
  • Stomp ≫
  • PHP Manual
  • SSH2 関数
  • リモートサーバーを経由するトンネルをオープンする

ssh2_tunnel

(PECL ssh2 >= 0.9.0)

ssh2_tunnel — リモートサーバーを経由するトンネルをオープンする

説明

ssh2_tunnel(resource $session, string $host, int $port): resource

現在接続している SSH サーバーを経由して、 任意のホスト/ポートへのソケットストリームをオープンします。

パラメータ

session

ssh2_connect() のコールによって取得した SSH 接続リンク ID。

host

port

戻り値

例

例1 任意のホストへのトンネルのオープン

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_pubkey_file($connection, 'username', 'id_dsa.pub', 'id_dsa');

$tunnel = ssh2_tunnel($connection, '10.0.0.101', 12345);
?>

参考

  • ssh2_connect() - SSH サーバーに接続する
  • fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする


Stomp Client

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 例
  • Stomp 関数
    • stomp_connect_error — Returns a string description of the last connect error
    • stomp_version — Gets the current stomp extension version
  • Stomp — The Stomp class
    • Stomp::abort — Rolls back a transaction in progress
    • Stomp::ack — Acknowledges consumption of a message
    • Stomp::begin — Starts a transaction
    • Stomp::commit — Commits a transaction in progress
    • Stomp::__construct — Opens a connection
    • Stomp::__destruct — Closes stomp connection
    • Stomp::error — Gets the last stomp error
    • Stomp::getReadTimeout — Gets read timeout
    • Stomp::getSessionId — Gets the current stomp session ID
    • Stomp::hasFrame — Indicates whether or not there is a frame ready to read
    • Stomp::readFrame — Reads the next frame
    • Stomp::send — Sends a message
    • Stomp::setReadTimeout — Sets read timeout
    • Stomp::subscribe — Registers to listen to a given destination
    • Stomp::unsubscribe — Removes an existing subscription
  • StompFrame — The StompFrame class
    • StompFrame::__construct — Constructor
  • StompException — The StompException class
    • StompException::getDetails — Get exception details


はじめに

This extension allows php applications to communicate with any Stomp compliant Message Brokers through easy object-oriented and procedural interfaces. » Stomp official site


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Stomp
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

The » OpenSSL package >= 0.9.6 and the openssl extension may also be required to use stomp over SSL.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/stomp


実行時設定

php.ini の設定により動作が変化します。

Stomp 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
stomp.default_broker | tcp://localhost:61613 | INI_ALL |
stomp.default_connection_timeout_sec | 2 | INI_ALL |
stomp.default_connection_timeout_usec | 0 | INI_ALL |
stomp.default_read_timeout_sec | 2 | INI_ALL |
stomp.default_read_timeout_usec | 0 | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

stomp.default_broker string

The default broker URI to use when connecting to the message broker if no other URI is specified.

stomp.default_connection_timeout_sec int

The seconds part of the default connection timeout.

stomp.default_connection_timeout_usec int

The microseconds part of the default connection timeout.

stomp.default_read_timeout_sec int

The seconds part of the default reading timeout.

stomp.default_read_timeout_usec int

The microseconds part of the default reading timeout.


リソース型

There is only one resource type used in the stomp extension - it's the link identifier for a stomp connection.


例

例1 オブジェクト指向型

<?php

$queue = '/queue/foo';
$msg = 'bar';

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

/* send a message to the queue 'foo' */
$stomp->send($queue, $msg);

/* subscribe to messages from the queue 'foo' */
$stomp->subscribe($queue);

/* read a frame */
$frame = $stomp->readFrame();

if ($frame->body === $msg) {
var_dump($frame);

/* acknowledge that the frame was received */
$stomp->ack($frame);
}

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

object(StompFrame)#2 (3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["headers"]=>
  array(5) {
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:2:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257226805828"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
  ["body"]=>
  string(3) "bar"
}

例2 手続き型

<?php

$queue = '/queue/foo';
$msg = 'bar';

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, $queue, $msg, array('transaction' => 't1'));

/* commit a transaction */
stomp_commit($link, 't1');

/* subscribe to messages from the queue 'foo' */
stomp_subscribe($link, $queue);

/* read a frame */
$frame = stomp_read_frame($link);

if ($frame['body'] === $msg) {
var_dump($frame);

/* acknowledge that the frame was received */
stomp_ack($link, $frame['headers']['message-id']);
}

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["body"]=>
  string(3) "bar"
  ["headers"]=>
  array(6) {
    ["transaction"]=>
    string(2) "t1"
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:3:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257227037059"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
}


Stomp 関数

目次

  • stomp_connect_error — Returns a string description of the last connect error
  • stomp_version — Gets the current stomp extension version


Returns a string description of the last connect error

  • ≪ Stomp 関数
  • stomp_version ≫
  • PHP Manual
  • Stomp 関数
  • Returns a string description of the last connect error

stomp_connect_error

(PECL stomp >= 0.3.0)

stomp_connect_error — Returns a string description of the last connect error

説明

stomp_connect_error(): string

Returns a string description of the last connect error.

パラメータ

この関数にはパラメータはありません。

戻り値

A string that describes the error, or null if no error occurred.

例

例1 stomp_connect_error() example

<?php
$link = stomp_connect('http://localhost:61613');

if(!$link) {
die('Connection failed: ' . stomp_connect_error());
}
?>

上の例の出力は、 たとえば以下のようになります。

Connection failed: Invalid Broker URI scheme


Gets the current stomp extension version

  • ≪ stomp_connect_error
  • Stomp ≫
  • PHP Manual
  • Stomp 関数
  • Gets the current stomp extension version

stomp_version

(PECL stomp >= 0.1.0)

stomp_version — Gets the current stomp extension version

説明

stomp_version(): string

Returns a string containing the version of the current stomp extension.

パラメータ

この関数にはパラメータはありません。

戻り値

It returns the current stomp extension version

例

例1 stomp_version() example

<?php

var_dump(stomp_version());

?>

上の例の出力は、 たとえば以下のようになります。

string(5) "0.2.0"


The Stomp class

(PECL stomp >= 0.1.0)

はじめに

Represents a connection between PHP and a Stomp compliant Message Broker.

クラス概要

class Stomp {
/* メソッド */
public __construct(
string $broker = ini_get("stomp.default_broker_uri"),
string $username = ?,
string $password = ?,
array $headers = ?
)
public abort(string $transaction_id, array $headers = ?): bool
stomp_abort(resource $link, string $transaction_id, array $headers = ?): bool
public ack(mixed $msg, array $headers = ?): bool
stomp_ack(resource $link, mixed $msg, array $headers = ?): bool
public begin(string $transaction_id, array $headers = ?): bool
stomp_begin(resource $link, string $transaction_id, array $headers = ?): bool
public commit(string $transaction_id, array $headers = ?): bool
stomp_commit(resource $link, string $transaction_id, array $headers = ?): bool
stomp_connect(
string $broker = ini_get("stomp.default_broker_uri"),
string $username = ?,
string $password = ?,
array $headers = ?
): resource
stomp_close(resource $link): bool
public error(): string
stomp_error(resource $link): string
public getReadTimeout(): array
stomp_get_read_timeout(resource $link): array
public getSessionId(): string|false
stomp_get_session_id(resource $link): string|false
public hasFrame(): bool
stomp_has_frame(resource $link): bool
public readFrame(string $class_name = "stompFrame"): stompframe
stomp_read_frame(resource $link): array
public send(string $destination, mixed $msg, array $headers = ?): bool
stomp_send(
resource $link,
string $destination,
mixed $msg,
array $headers = ?
): bool
public setReadTimeout(int $seconds, int $microseconds = ?): void
stomp_set_read_timeout(resource $link, int $seconds, int $microseconds = ?): void
public subscribe(string $destination, array $headers = ?): bool
stomp_subscribe(resource $link, string $destination, array $headers = ?): bool
public unsubscribe(string $destination, array $headers = ?): bool
stomp_unsubscribe(resource $link, string $destination, array $headers = ?): bool
public __destruct()
}

目次

  • Stomp::abort — Rolls back a transaction in progress
  • Stomp::ack — Acknowledges consumption of a message
  • Stomp::begin — Starts a transaction
  • Stomp::commit — Commits a transaction in progress
  • Stomp::__construct — Opens a connection
  • Stomp::__destruct — Closes stomp connection
  • Stomp::error — Gets the last stomp error
  • Stomp::getReadTimeout — Gets read timeout
  • Stomp::getSessionId — Gets the current stomp session ID
  • Stomp::hasFrame — Indicates whether or not there is a frame ready to read
  • Stomp::readFrame — Reads the next frame
  • Stomp::send — Sends a message
  • Stomp::setReadTimeout — Sets read timeout
  • Stomp::subscribe — Registers to listen to a given destination
  • Stomp::unsubscribe — Removes an existing subscription


Rolls back a transaction in progress

  • ≪ Stomp
  • Stomp::ack ≫
  • PHP Manual
  • Stomp
  • Rolls back a transaction in progress

Stomp::abort

stomp_abort

(PECL stomp >= 0.1.0)

Stomp::abort -- stomp_abort — Rolls back a transaction in progress

説明

オブジェクト指向型 (method):

public Stomp::abort(string $transaction_id, array $headers = ?): bool

手続き型:

stomp_abort(resource $link, string $transaction_id, array $headers = ?): bool

Rolls back a transaction in progress.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

transaction_id

The transaction to abort.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

/* begin a transaction */
$stomp->begin('t1');

/* send a message to the queue */
$stomp->send('/queue/foo', 'bar', array('transaction' => 't1'));

/* rollback */
$stomp->abort('t1');

/* close connection */
unset($stomp);
?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('tcp://localhost:61613');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, '/queue/foo', 'bar', array('transaction' => 't1'));

/* rollback */
stomp_abort($link, 't1');

/* close connection */
stomp_close($link);

?>

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


Acknowledges consumption of a message

  • ≪ Stomp::abort
  • Stomp::begin ≫
  • PHP Manual
  • Stomp
  • Acknowledges consumption of a message

Stomp::ack

stomp_ack

(PECL stomp >= 0.1.0)

Stomp::ack -- stomp_ack — Acknowledges consumption of a message

説明

オブジェクト指向型 (method):

public Stomp::ack(mixed $msg, array $headers = ?): bool

手続き型:

stomp_ack(resource $link, mixed $msg, array $headers = ?): bool

Acknowledges consumption of a message from a subscription using client acknowledgment.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

msg

The message/messageId to be acknowledged.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php

$queue = '/queue/foo';
$msg = 'bar';

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

/* send a message to the queue 'foo' */
$stomp->send($queue, $msg);

/* subscribe to messages from the queue 'foo' */
$stomp->subscribe($queue);

/* read a frame */
$frame = $stomp->readFrame();

if ($frame->body === $msg) {
/* acknowledge that the frame was received */
$stomp->ack($frame);
}

/* remove the subscription */
$stomp->unsubscribe($queue);

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

$queue = '/queue/foo';
$msg = 'bar';

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, $queue, $msg, array('transaction' => 't1'));

/* commit a transaction */
stomp_commit($link, 't1');

/* subscribe to messages from the queue 'foo' */
stomp_subscribe($link, $queue);

/* read a frame */
$frame = stomp_read_frame($link);

if ($frame['body'] === $msg) {
/* acknowledge that the frame was received */
stomp_ack($link, $frame['headers']['message-id']);
}

/* remove the subscription */
stomp_unsubscribe($link, $queue);

/* close connection */
stomp_close($link);

?>

注意

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


Starts a transaction

  • ≪ Stomp::ack
  • Stomp::commit ≫
  • PHP Manual
  • Stomp
  • Starts a transaction

Stomp::begin

stomp_begin

(PECL stomp >= 0.1.0)

Stomp::begin -- stomp_begin — Starts a transaction

説明

オブジェクト指向型 (method):

public Stomp::begin(string $transaction_id, array $headers = ?): bool

手続き型:

stomp_begin(resource $link, string $transaction_id, array $headers = ?): bool

Starts a transaction.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

transaction_id

The transaction id.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

See stomp_commit() or stomp_abort().

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


Commits a transaction in progress

  • ≪ Stomp::begin
  • Stomp::__construct ≫
  • PHP Manual
  • Stomp
  • Commits a transaction in progress

Stomp::commit

stomp_commit

(PECL stomp >= 0.1.0)

Stomp::commit -- stomp_commit — Commits a transaction in progress

説明

オブジェクト指向型 (method):

public Stomp::commit(string $transaction_id, array $headers = ?): bool

手続き型:

stomp_commit(resource $link, string $transaction_id, array $headers = ?): bool

Commits a transaction in progress.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

transaction_id

The transaction id.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

/* begin a transaction */
$stomp->begin('t1');

/* send a message to the queue */
$stomp->send('/queue/foo', 'bar', array('transaction' => 't1'));

/* commit */
$stomp->commit('t1');

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('tcp://localhost:61613');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

/* begin a transaction */
stomp_begin($link, 't1');

/* send a message to the queue 'foo' */
stomp_send($link, '/queue/foo', 'bar', array('transaction' => 't1'));

/* commit */
stomp_commit($link, 't1');

/* close connection */
stomp_close($link);

?>

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


Opens a connection

  • ≪ Stomp::commit
  • Stomp::__destruct ≫
  • PHP Manual
  • Stomp
  • Opens a connection

Stomp::__construct

stomp_connect

(PECL stomp >= 0.1.0)

Stomp::__construct -- stomp_connect — Opens a connection

説明

オブジェクト指向型 (constructor):

public Stomp::__construct(
string $broker = ini_get("stomp.default_broker_uri"),
string $username = ?,
string $password = ?,
array $headers = ?
)

手続き型:

stomp_connect(
string $broker = ini_get("stomp.default_broker_uri"),
string $username = ?,
string $password = ?,
array $headers = ?
): resource

Opens a connection to a stomp compliant Message Broker.

パラメータ

broker

The broker URI

username

The username.

password

The password.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

変更履歴

バージョン | 説明
PECL stomp 1.0.1 | The headers parameter was added

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

/* close connection */
stomp_close($link);

?>


Closes stomp connection

  • ≪ Stomp::__construct
  • Stomp::error ≫
  • PHP Manual
  • Stomp
  • Closes stomp connection

Stomp::__destruct

stomp_close

(PECL stomp >= 0.1.0)

Stomp::__destruct -- stomp_close — Closes stomp connection

説明

オブジェクト指向型 (destructor):

public Stomp::__destruct()

手続き型:

stomp_close(resource $link): bool

Closes a previously opened connection.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

See stomp_connect().


Gets the last stomp error

  • ≪ Stomp::__destruct
  • Stomp::getReadTimeout ≫
  • PHP Manual
  • Stomp
  • Gets the last stomp error

Stomp::error

stomp_error

(PECL stomp >= 0.1.0)

Stomp::error -- stomp_error — Gets the last stomp error

説明

オブジェクト指向型 (method):

public Stomp::error(): string

手続き型:

stomp_error(resource $link): string

Gets the last stomp error.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

戻り値

Returns an error string or false if no error occurred.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

var_dump($stomp->error());

if (!$stomp->abort('unknown-transaction', array('receipt' => 'foo'))) {
var_dump($stomp->error());
}

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
string(43) "Invalid transaction id: unknown-transaction"

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

var_dump(stomp_error($link));

if (!stomp_abort($link, 'unknown-transaction', array('receipt' => 'foo'))) {
var_dump(stomp_error($link));
}

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
string(43) "Invalid transaction id: unknown-transaction"


Gets read timeout

  • ≪ Stomp::error
  • Stomp::getSessionId ≫
  • PHP Manual
  • Stomp
  • Gets read timeout

Stomp::getReadTimeout

stomp_get_read_timeout

(PECL stomp >= 0.3.0)

Stomp::getReadTimeout -- stomp_get_read_timeout — Gets read timeout

説明

オブジェクト指向型 (method):

public Stomp::getReadTimeout(): array

手続き型:

stomp_get_read_timeout(resource $link): array

Gets read timeout

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

戻り値

Returns an array with 2 elements: sec and usec.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

var_dump($stomp->getReadTimeout());

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["sec"]=>
  int(2)
  ["usec"]=>
  int(0)
}

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

var_dump(stomp_get_read_timeout($link));

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["sec"]=>
  int(2)
  ["usec"]=>
  int(0)
}


Gets the current stomp session ID

  • ≪ Stomp::getReadTimeout
  • Stomp::hasFrame ≫
  • PHP Manual
  • Stomp
  • Gets the current stomp session ID

Stomp::getSessionId

stomp_get_session_id

(PECL stomp >= 0.1.0)

Stomp::getSessionId -- stomp_get_session_id — Gets the current stomp session ID

説明

オブジェクト指向型 (method):

public Stomp::getSessionId(): string|false

手続き型:

stomp_get_session_id(resource $link): string|false

Gets the current stomp session ID.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

戻り値

string session id on success失敗した場合に false を返します.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

var_dump($stomp->getSessionId());

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

string(35) "ID:php.net-52873-1257291895530-4:14"

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

var_dump(stomp_get_session_id($link));

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

string(35) "ID:php.net-52873-1257291895530-4:14"


Indicates whether or not there is a frame ready to read

  • ≪ Stomp::getSessionId
  • Stomp::readFrame ≫
  • PHP Manual
  • Stomp
  • Indicates whether or not there is a frame ready to read

Stomp::hasFrame

stomp_has_frame

(PECL stomp >= 0.1.0)

Stomp::hasFrame -- stomp_has_frame — Indicates whether or not there is a frame ready to read

説明

オブジェクト指向型 (method):

public Stomp::hasFrame(): bool

手続き型:

stomp_has_frame(resource $link): bool

Indicates whether or not there is a frame ready to read.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

戻り値

Returns true if a frame is ready to read, or false otherwise.


Reads the next frame

  • ≪ Stomp::hasFrame
  • Stomp::send ≫
  • PHP Manual
  • Stomp
  • Reads the next frame

Stomp::readFrame

stomp_read_frame

(PECL stomp >= 0.1.0)

Stomp::readFrame -- stomp_read_frame — Reads the next frame

説明

オブジェクト指向型 (method):

public Stomp::readFrame(string $class_name = "stompFrame"): stompframe

手続き型:

stomp_read_frame(resource $link): array

Reads the next frame. It is possible to instantiate an object of a specific class, and pass parameters to that class's constructor.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

class_name

The name of the class to instantiate. If not specified, a stompFrame object is returned.

戻り値

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

変更履歴

バージョン | 説明
Stomp 0.4.0 | class_name parameter was added.

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

/* subscribe to messages from the queue 'foo' */
$stomp->subscribe('/queue/foo');

/* read a frame */
var_dump($stomp->readFrame());

/* close connection */
unset($stomp);

?>

上の例の出力は、 たとえば以下のようになります。

object(StompFrame)#2 (3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["headers"]=>
  array(5) {
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:2:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257226805828"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
  ["body"]=>
  string(3) "bar"
}

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

/* subscribe to messages from the queue 'foo' */
stomp_subscribe($link, '/queue/foo');

/* read a frame */
$frame = stomp_read_frame($link);

/* close connection */
stomp_close($link);

?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
  ["command"]=>
  string(7) "MESSAGE"
  ["body"]=>
  string(3) "bar"
  ["headers"]=>
  array(6) {
    ["transaction"]=>
    string(2) "t1"
    ["message-id"]=>
    string(41) "ID:php.net-55293-1257226743606-4:3:-1:1:1"
    ["destination"]=>
    string(10) "/queue/foo"
    ["timestamp"]=>
    string(13) "1257227037059"
    ["expires"]=>
    string(1) "0"
    ["priority"]=>
    string(1) "0"
  }
}


Sends a message

  • ≪ Stomp::readFrame
  • Stomp::setReadTimeout ≫
  • PHP Manual
  • Stomp
  • Sends a message

Stomp::send

stomp_send

(PECL stomp >= 0.1.0)

Stomp::send -- stomp_send — Sends a message

説明

オブジェクト指向型 (method):

public Stomp::send(string $destination, mixed $msg, array $headers = ?): bool

手続き型:

stomp_send(
resource $link,
string $destination,
mixed $msg,
array $headers = ?
): bool

Sends a message to the Message Broker.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

destination

Where to send the message

msg

Message to send.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

See stomp_ack().

注意

注意:

トランザクションヘッダを指定し、そのメッセージがトランザクションの一部であることを示します。

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


Sets read timeout

  • ≪ Stomp::send
  • Stomp::subscribe ≫
  • PHP Manual
  • Stomp
  • Sets read timeout

Stomp::setReadTimeout

stomp_set_read_timeout

(PECL stomp >= 0.3.0)

Stomp::setReadTimeout -- stomp_set_read_timeout — Sets read timeout

説明

オブジェクト指向型 (method):

public Stomp::setReadTimeout(int $seconds, int $microseconds = ?): void

手続き型:

stomp_set_read_timeout(resource $link, int $seconds, int $microseconds = ?): void

Sets read timeout.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

seconds

The seconds part of the timeout to be set.

microseconds

The microseconds part of the timeout to be set.

戻り値

値を返しません。

例

例1 オブジェクト指向型

<?php

/* connection */
try {
$stomp = new Stomp('tcp://localhost:61613');
} catch(StompException $e) {
die('Connection failed: ' . $e->getMessage());
}

$stomp->setReadTimeout(10);

/* close connection */
unset($stomp);

?>

例2 手続き型

<?php

/* connection */
$link = stomp_connect('ssl://localhost:61612');

/* check connection */
if (!$link) {
die('Connection failed: ' . stomp_connect_error());
}

stomp_set_read_timeout($link, 10);

/* close connection */
stomp_close($link);

?>


Registers to listen to a given destination

  • ≪ Stomp::setReadTimeout
  • Stomp::unsubscribe ≫
  • PHP Manual
  • Stomp
  • Registers to listen to a given destination

Stomp::subscribe

stomp_subscribe

(PECL stomp >= 0.1.0)

Stomp::subscribe -- stomp_subscribe — Registers to listen to a given destination

説明

オブジェクト指向型 (method):

public Stomp::subscribe(string $destination, array $headers = ?): bool

手続き型:

stomp_subscribe(resource $link, string $destination, array $headers = ?): bool

Registers to listen to a given destination.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

destination

Destination to subscribe to.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

See stomp_ack().

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


Removes an existing subscription

  • ≪ Stomp::subscribe
  • StompFrame ≫
  • PHP Manual
  • Stomp
  • Removes an existing subscription

Stomp::unsubscribe

stomp_unsubscribe

(PECL stomp >= 0.1.0)

Stomp::unsubscribe -- stomp_unsubscribe — Removes an existing subscription

説明

オブジェクト指向型 (method):

public Stomp::unsubscribe(string $destination, array $headers = ?): bool

手続き型:

stomp_unsubscribe(resource $link, string $destination, array $headers = ?): bool

Removes an existing subscription.

パラメータ

link

手続き型のみ: stomp_connect() が返す stomp リンク ID。

destination

Subscription to remove.

headers

追加のヘッダ (例: receipt) を含む連想配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

See stomp_ack().

注意

ヒント

Stomp は本来非同期です。同期通信を実装するには receipt ヘッダを追加します。これを追加すると、サーバーがメッセージを受領するかタイムアウトに達するまではメソッドが何も返さないようになります。


The StompFrame class

(PECL stomp >= 0.1.0)

はじめに

Represents a message which was sent or received from a Stomp compliant Message Broker.

クラス概要

class StompFrame {
/* プロパティ */
public $command;
public $headers;
public $body;
/* メソッド */
__construct(string $command = ?, array $headers = ?, string $body = ?)
}

プロパティ

command

Frame command.

headers

Frame headers (array).

body

Frame body.

目次

  • StompFrame::__construct — Constructor


Constructor

  • ≪ StompFrame
  • StompException ≫
  • PHP Manual
  • StompFrame
  • Constructor

StompFrame::__construct

(PECL stomp >= 0.1.0)

StompFrame::__construct — Constructor

説明

StompFrame::__construct(string $command = ?, array $headers = ?, string $body = ?)

Constructor.

パラメータ

command

Frame command

headers

Frame headers (array).

body

Frame body.


The StompException class

(PECL stomp >= 0.1.0)

はじめに

Represents an error raised by the stomp extension. See Exceptions for more information about Exceptions in PHP.

クラス概要

class StompException extends Exception {
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
/* メソッド */
public getDetails(): string
}

目次

  • StompException::getDetails — Get exception details


Get exception details

  • ≪ StompException
  • SVM ≫
  • PHP Manual
  • StompException
  • Get exception details

StompException::getDetails

(PECL stomp >= 0.1.0)

StompException::getDetails — Get exception details

説明

public StompException::getDetails(): string

Get exception details.

パラメータ

この関数にはパラメータはありません。

戻り値

string containing the error details.


サポートベクターマシン

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
  • SVM — The SVM class
    • SVM::__construct — SVM オブジェクトを新規構築
    • SVM::crossvalidate — Test training params on subsets of the training data
    • SVM::getOptions — 現在の訓練パラメータを返す
    • SVM::setOptions — 訓練パラメータを設定
    • SVM::train — Create a SVMModel based on training data
  • SVMModel — SVMModel クラス
    • SVMModel::checkProbabilityModel — モデルが確率情報を持つ場合 TRUE を返す
    • SVMModel::__construct — SVMModel を新規構築
    • SVMModel::getLabels — モデルが訓練されたラベルを取得
    • SVMModel::getNrClass — モデルが訓練されたクラスの個数を返す
    • SVMModel::getSvmType — モデルが訓練された SVM の種類を取得
    • SVMModel::getSvrProbability — 回帰モデルに対するσ（シグマ）値を取得
    • SVMModel::load — 保管された SVM モデルを読み込み
    • SVMModel::predict — Predict a value for previously unseen data
    • SVMModel::predict_probability — Return class probabilities for previous unseen data
    • SVMModel::save — モデルをファイルに保管


はじめに

LibSVM は、SVM 識別と回帰の問題用の効率的なソルバーです。 PHP スクリプトで簡単に使用できるように、 svm 拡張モジュールは、PHP インターフェイスでこれを隠蔽します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SVM
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

libsvm 自体が必要です。libsvm は、いくつかのパッケージ管理を介して入手可能です。 たとえば、RPM ベースのシステムでは libsvm-devel、Debian ベースのシステムでは libsvm-dev です。 あるいは Web サイトから直接入手可能です。 » 公式サイト からインストールする場合、 パッケージが自動的にインストールされないようにいくつかのステップが取られる必要があります。 例えば、最新バージョンが 3.1 と仮定しましょう。

wget http://www.csie.ntu.edu.tw/~cjlin/cgi-bin/libsvm.cgi?+http://www.csie.ntu.edu.tw/~cjlin/libsvm+tar.gz
tar xvzf libsvm-3.1.tar.gz
cd libsvm-3.1
make lib
cp libsvm.so.1 /usr/lib
ln -s libsvm.so.1 libsvm.so
ldconfig
ldconfig --print | grep libsvm

この最後のステップでは、libsvm がインストールされたことが表示されることでしょう。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/svm


例

The basic process is to define parameters, supply training data to generate a model on, then make predictions based on the model. There are a default set of parameters that should get some results with most any input, so we'll start by looking at the data.

Data is supplied in either a file, a stream, or as an array. If supplied in a file or a stream, it must contain one line per training example, which must be formatted as an integer class (usually 1 and -1) followed by a series of feature/value pairs, in increasing feature order. The features are integers, the values floats, usually scaled 0-1. For example:

-1 1:0.43 3:0.12 9284:0.2

In a document classification problem, say a spam checker, each line would represent a document. There would be two classes, -1 for spam, 1 for ham. Each feature would represent some word, and the value would represent that importance of that word to the document (perhaps the frequency count, with the total scaled to unit length). Features that were 0 (e.g. the word did not appear in the document at all) would simply not be included.

In array mode, the data must be passed as an array of arrays. Each sub-array must have the class as the first element, then key => value sets for the feature values pairs.

This data is passed to the SVM class's train function, which will return an SVM model is successful.

Once a model has been generated, it can be used to make predictions about previously unseen data. This can be passed as an array to the model's predict function, in the same format as before, but without the label. The response will be the class.

Models can be saved and restored as required, using the save and load functions, which both take a file location.

例1 Train from array

<?php
$data = array(
array(-1, 1 => 0.43, 3 => 0.12, 9284 => 0.2),
array(1, 1 => 0.22, 5 => 0.01, 94 => 0.11),
);

$svm = new SVM();
$model = $svm->train($data);

$data = array(1 => 0.43, 3 => 0.12, 9284 => 0.2);
$result = $model->predict($data);
var_dump($result);
$model->save('model.svm');
?>

上の例の出力は、 たとえば以下のようになります。

int(-1)

例2 Train from a file

<?php
$svm = new SVM();
$model = $svm->train("traindata.txt");
?>


The SVM class

(PECL svm >= 0.1.0)

はじめに

クラス概要

class SVM {
/* 定数 */
const int C_SVC = 0;
const int NU_SVC = 1;
const int ONE_CLASS = 2;
const int EPSILON_SVR = 3;
const int NU_SVR = 4;
const int KERNEL_LINEAR = 0;
const int KERNEL_POLY = 1;
const int KERNEL_RBF = 2;
const int KERNEL_SIGMOID = 3;
const int KERNEL_PRECOMPUTED = 4;
const int OPT_TYPE = 101;
const int OPT_KERNEL_TYPE = 102;
const int OPT_DEGREE = 103;
const int OPT_SHRINKING = 104;
const int OPT_PROPABILITY = 105;
const int OPT_GAMMA = 201;
const int OPT_NU = 202;
const int OPT_EPS = 203;
const int OPT_P = 204;
const int OPT_COEF_ZERO = 205;
const int OPT_C = 206;
const int OPT_CACHE_SIZE = 207;
/* メソッド */
public __construct()
public svm::crossvalidate(array $problem, int $number_of_folds): float
public getOptions(): array
public setOptions(array $params): bool
public svm::train(array $problem, array $weights = ?): SVMModel
}

定義済み定数

SVM Constants

SVM::C_SVC

The basic C_SVC SVM type. The default, and a good starting point

SVM::NU_SVC

The NU_SVC type uses a different, more flexible, error weighting

SVM::ONE_CLASS

One class SVM type. Train just on a single class, using outliers as negative examples

SVM::EPSILON_SVR

A SVM type for regression (predicting a value rather than just a class)

SVM::NU_SVR

A NU style SVM regression type

SVM::KERNEL_LINEAR

A very simple kernel, can work well on large document classification problems

SVM::KERNEL_POLY

A polynomial kernel

SVM::KERNEL_RBF

The common Gaussian RBD kernel. Handles non-linear problems well and is a good default for classification

SVM::KERNEL_SIGMOID

A kernel based on the sigmoid function. Using this makes the SVM very similar to a two layer sigmoid based neural network

SVM::KERNEL_PRECOMPUTED

A precomputed kernel - currently unsupported.

SVM::OPT_TYPE

The options key for the SVM type

SVM::OPT_KERNEL_TYPE

The options key for the kernel type

SVM::OPT_DEGREE

SVM::OPT_SHRINKING

Training parameter, boolean, for whether to use the shrinking heuristics

SVM::OPT_PROBABILITY

Training parameter, boolean, for whether to collect and use probability estimates

SVM::OPT_GAMMA

Algorithm parameter for Poly, RBF and Sigmoid kernel types.

SVM::OPT_NU

The option key for the nu parameter, only used in the NU_ SVM types

SVM::OPT_EPS

The option key for the Epsilon parameter, used in epsilon regression

SVM::OPT_P

Training parameter used by Episilon SVR regression

SVM::OPT_COEF_ZERO

Algorithm parameter for poly and sigmoid kernels

SVM::OPT_C

The option for the cost parameter that controls tradeoff between errors and generality - effectively the penalty for misclassifying training examples.

SVM::OPT_CACHE_SIZE

Memory cache size, in MB

目次

  • SVM::__construct — SVM オブジェクトを新規構築
  • SVM::crossvalidate — Test training params on subsets of the training data
  • SVM::getOptions — 現在の訓練パラメータを返す
  • SVM::setOptions — 訓練パラメータを設定
  • SVM::train — Create a SVMModel based on training data


SVM オブジェクトを新規構築

  • ≪ SVM
  • SVM::crossvalidate ≫
  • PHP Manual
  • SVM
  • SVM オブジェクトを新規構築

SVM::__construct

(PECL svm >= 0.1.0)

SVM::__construct — SVM オブジェクトを新規構築

説明

public SVM::__construct()

訓練データを受け取る準備ができている SVM オブジェクトを新規構成します。

パラメータ

この関数にはパラメータはありません。

エラー / 例外

libsvm ライブラリが読み込まれなかった場合、 SVMException をスローします。


Test training params on subsets of the training data

  • ≪ SVM::__construct
  • SVM::getOptions ≫
  • PHP Manual
  • SVM
  • Test training params on subsets of the training data

SVM::crossvalidate

(PECL svm >= 0.1.0)

SVM::crossvalidate — Test training params on subsets of the training data

説明

public svm::crossvalidate(array $problem, int $number_of_folds): float

Crossvalidate can be used to test the effectiveness of the current parameter set on a subset of the training data. Given a problem set and a n "folds", it separates the problem set into n subsets, and the repeatedly trains on one subset and tests on another. While the accuracy will generally be lower than a SVM trained on the enter data set, the accuracy score returned should be relatively useful, so it can be used to test different training parameters.

パラメータ

problem

The problem data. This can either be in the form of an array, the URL of an SVMLight formatted file, or a stream to an opened SVMLight formatted datasource.

number_of_folds

The number of sets the data should be divided into and cross tested. A higher number means smaller training sets and less reliability. 5 is a good number to start with.

戻り値

The correct percentage, expressed as a floating point number from 0-1. In the case of NU_SVC or EPSILON_SVR kernels the mean squared error will returned instead.

参考

  • SVM::train() - Create a SVMModel based on training data


現在の訓練パラメータを返す

  • ≪ SVM::crossvalidate
  • SVM::setOptions ≫
  • PHP Manual
  • SVM
  • 現在の訓練パラメータを返す

SVM::getOptions

(PECL svm >= 0.1.0)

SVM::getOptions — 現在の訓練パラメータを返す

説明

public SVM::getOptions(): array

訓練パラメータを含む配列を取得します。 パラメータは、所定の SVM 定数がキーになります。

パラメータ

この関数にはパラメータはありません。

戻り値

構成の設定配列を返します。


訓練パラメータを設定

  • ≪ SVM::getOptions
  • SVM::train ≫
  • PHP Manual
  • SVM
  • 訓練パラメータを設定

SVM::setOptions

(PECL svm >= 0.1.0)

SVM::setOptions — 訓練パラメータを設定

説明

public SVM::setOptions(array $params): bool

1 つ以上の訓練パラメータを設定します。

パラメータ

params

訓練パラメータの配列。SVM 定数がキーになります。

戻り値

成功した場合に TRUE を返し、エラーの場合に SVMExceptionFALSE をスローします。


Create a SVMModel based on training data

  • ≪ SVM::setOptions
  • SVMModel ≫
  • PHP Manual
  • SVM
  • Create a SVMModel based on training data

SVM::train

(PECL svm >= 0.1.0)

SVM::train — Create a SVMModel based on training data

説明

public svm::train(array $problem, array $weights = ?): SVMModel

Train a support vector machine based on the supplied training data.

パラメータ

problem

The problem can be provided in three different ways. An array, where the data should start with the class label (usually 1 or -1) then followed by a sparse data set of dimension => data pairs. A URL to a file containing a SVM Light formatted problem, with the each line being a new training example, the start of each line containing the class (1, -1) then a series of tab separated data values shows as key:value. A opened stream pointing to a data source formatted as in the file above.

weights

Weights are an optional set of weighting parameters for the different classes, to help account for unbalanced training sets. For example, if the classes were 1 and -1, and -1 had significantly more example than one, the weight for -1 could be 0.5. Weights should be in the range 0-1.

戻り値

Returns an SVMModel that can be used to classify previously unseen data. Throws SVMException on error


SVMModel クラス

(PECL svm >= 0.1.0)

はじめに

SVMModel は、訓練処理の結果です。 それは、以前は目に見えなかったデータを分類するために使用できます。

クラス概要

class SVMModel {
/* メソッド */
public __construct(string $filename = ?)
public checkProbabilityModel(): bool
public getLabels(): array
public getNrClass(): int
public getSvmType(): int
public getSvrProbability(): float
public load(string $filename): bool
public predict(array $data): float
public predict_probability(array $data): float
public save(string $filename): bool
}

目次

  • SVMModel::checkProbabilityModel — モデルが確率情報を持つ場合 TRUE を返す
  • SVMModel::__construct — SVMModel を新規構築
  • SVMModel::getLabels — モデルが訓練されたラベルを取得
  • SVMModel::getNrClass — モデルが訓練されたクラスの個数を返す
  • SVMModel::getSvmType — モデルが訓練された SVM の種類を取得
  • SVMModel::getSvrProbability — 回帰モデルに対するσ（シグマ）値を取得
  • SVMModel::load — 保管された SVM モデルを読み込み
  • SVMModel::predict — Predict a value for previously unseen data
  • SVMModel::predict_probability — Return class probabilities for previous unseen data
  • SVMModel::save — モデルをファイルに保管


モデルが確率情報を持つ場合 TRUE を返す

  • ≪ SVMModel
  • SVMModel::__construct ≫
  • PHP Manual
  • SVMModel
  • モデルが確率情報を持つ場合 TRUE を返す

SVMModel::checkProbabilityModel

(PECL svm >= 0.1.5)

SVMModel::checkProbabilityModel — モデルが確率情報を持つ場合 TRUE を返す

説明

public SVMModel::checkProbabilityModel(): bool

モデルが確率情報を含む場合 TRUE を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ブール値を返します


SVMModel を新規構築

  • ≪ SVMModel::checkProbabilityModel
  • SVMModel::getLabels ≫
  • PHP Manual
  • SVMModel
  • SVMModel を新規構築

SVMModel::__construct

(PECL svm >= 0.1.0)

SVMModel::__construct — SVMModel を新規構築

説明

public SVMModel::__construct(string $filename = ?)

SVMModel を新規構築します。 モデルは、通常は SVM::train 関数から作成されますが、 しかし、保管されたモデルが直接復元されるかもしれません。

パラメータ

filename

このモデルを読み込むべき、保管されたモデルファイルのファイル名

エラー / 例外

エラー時に SVMException をスローします。

参考

  • SVMModel::load() - 保管された SVM モデルを読み込み


モデルが訓練されたラベルを取得

  • ≪ SVMModel::__construct
  • SVMModel::getNrClass ≫
  • PHP Manual
  • SVMModel
  • モデルが訓練されたラベルを取得

SVMModel::getLabels

(PECL svm >= 0.1.5)

SVMModel::getLabels — モデルが訓練されたラベルを取得

説明

public SVMModel::getLabels(): array

モデルが訓練されたラベルの配列を返します。 回帰および 1 つのクラスのモデルでは、空の配列が返されます。

パラメータ

この関数にはパラメータはありません。

戻り値

ラベルの配列を返します

参考

  • SVMModel::getNrClass() - モデルが訓練されたクラスの個数を返す


モデルが訓練されたクラスの個数を返す

  • ≪ SVMModel::getLabels
  • SVMModel::getSvmType ≫
  • PHP Manual
  • SVMModel
  • モデルが訓練されたクラスの個数を返す

SVMModel::getNrClass

(PECL svm >= 0.1.5)

SVMModel::getNrClass — モデルが訓練されたクラスの個数を返す

説明

public SVMModel::getNrClass(): int

モデルが訓練されたクラスの個数を返します。 １つのクラスおよび複数の回帰モデルにたいしては、2 を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

整数のクラスの個数を返します


モデルが訓練された SVM の種類を取得

  • ≪ SVMModel::getNrClass
  • SVMModel::getSvrProbability ≫
  • PHP Manual
  • SVMModel
  • モデルが訓練された SVM の種類を取得

SVMModel::getSvmType

(PECL svm >= 0.1.5)

SVMModel::getSvmType — モデルが訓練された SVM の種類を取得

説明

public SVMModel::getSvmType(): int

使用された SVM モデルの種類を表現する整数値を返します。例) SVM::C_SVC

パラメータ

この関数にはパラメータはありません。

戻り値

整数の SVM の種類を返します


回帰モデルに対するσ（シグマ）値を取得

  • ≪ SVMModel::getSvmType
  • SVMModel::load ≫
  • PHP Manual
  • SVMModel
  • 回帰モデルに対するσ（シグマ）値を取得

SVMModel::getSvrProbability

(PECL svm >= 0.1.5)

SVMModel::getSvrProbability — 回帰モデルに対するσ（シグマ）値を取得

説明

public SVMModel::getSvrProbability(): float

回帰モデルに対するσ（シグマ）値を返します。 確率情報がないか、またはモデルが SVR ではない場合、0 が返されます。

パラメータ

この関数にはパラメータはありません。

戻り値

σ（シグマ）値を返します


保管された SVM モデルを読み込み

  • ≪ SVMModel::getSvrProbability
  • SVMModel::predict ≫
  • PHP Manual
  • SVMModel
  • 保管された SVM モデルを読み込み

SVMModel::load

(PECL svm >= 0.1.00.1.0)

SVMModel::load — 保管された SVM モデルを読み込み

説明

public SVMModel::load(string $filename): bool

識別および回帰の準備ができたモデルファイルを読み込みます。

パラメータ

filename

モデルのファイル名

戻り値

エラー時に SVMException をスローします。 成功時に true を返します。

参考

  • SVMModel::save() - モデルをファイルに保管


Predict a value for previously unseen data

  • ≪ SVMModel::load
  • SVMModel::predict_probability ≫
  • PHP Manual
  • SVMModel
  • Predict a value for previously unseen data

SVMModel::predict

(PECL svm >= 0.1.0)

SVMModel::predict — Predict a value for previously unseen data

説明

public SVMModel::predict(array $data): float

This function accepts an array of data and attempts to predict the class or regression value based on the model extracted from previously trained data.

パラメータ

data

The array to be classified. This should be a series of key => value pairs in increasing key order, but not necessarily continuous.

戻り値

Float the predicted value. This will be a class label in the case of classification, a real value in the case of regression. Throws SVMException on error

参考

  • SVM::train() - Create a SVMModel based on training data


Return class probabilities for previous unseen data

  • ≪ SVMModel::predict
  • SVMModel::save ≫
  • PHP Manual
  • SVMModel
  • Return class probabilities for previous unseen data

SVMModel::predict_probability

(PECL svm >= 0.1.4)

SVMModel::predict_probability — Return class probabilities for previous unseen data

説明

public SVMModel::predict_probability(array $data): float

This function accepts an array of data and attempts to predict the class, as with the predict function. Additionally, however, this function returns an array of probabilities, one per class in the model, which represent the estimated chance of the data supplied being a member of that class. Requires that the model to be used has been trained with the probability parameter set to true.

パラメータ

data

The array to be classified. This should be a series of key => value pairs in increasing key order, but not necessarily continuous.

probabilities

The supplied value will be filled with the probabilities. This will be either null, in the case of a model without probability information, or an array where the index is the class name and the value the predicted probability.

戻り値

Float the predicted value. This will be a class label in the case of classification, a real value in the case of regression. Throws SVMException on error

参考

  • SVM::predict()


モデルをファイルに保管

  • ≪ SVMModel::predict_probability
  • SVN ≫
  • PHP Manual
  • SVMModel
  • モデルをファイルに保管

SVMModel::save

(PECL svm >= 0.1.0)

SVMModel::save — モデルをファイルに保管

説明

public SVMModel::save(string $filename): bool

後で使用するために、モデルデータをファイルに保管します。

パラメータ

filename

モデルを保管するファイル

戻り値

エラー時に SVMException をスローします。 成功時に true を返します。

参考

  • SVMModel::load() - 保管された SVM モデルを読み込み


Subversion

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • SVN 関数
    • svn_add — Schedules the addition of an item in a working directory
    • svn_auth_get_parameter — 認証パラメータを取得する
    • svn_auth_set_parameter — 認証パラメータを設定する
    • svn_blame — ファイルの SVN blame を取得する
    • svn_cat — リポジトリ内のファイルの内容を返す
    • svn_checkout — リポジトリから作業コピーをチェックアウトする
    • svn_cleanup — 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する
    • svn_client_version — SVN クライアントライブラリのバージョンを返す
    • svn_commit — Sends changes from the local working copy to the repository
    • svn_delete — Delete items from a working copy or repository
    • svn_diff — ふたつのパスの差分を再帰的に取得する
    • svn_export — Export the contents of a SVN directory
    • svn_fs_abort_txn — トランザクションを中断する
    • svn_fs_apply_text — 置換に使用するストリームを作成して返す
    • svn_fs_begin_txn2 — 新しいトランザクションを作成する
    • svn_fs_change_node_prop — 成功したら true、失敗したら false を返す
    • svn_fs_check_path — 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる
    • svn_fs_contents_changed — コンテンツが変更されている場合に true、されていない場合に false を返す
    • svn_fs_copy — ファイルまたはディレクトリをコピーする
    • svn_fs_delete — ファイルまたはディレクトリを削除する
    • svn_fs_dir_entries — 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す
    • svn_fs_file_contents — 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す
    • svn_fs_file_length — 指定したバージョンの fs から、ファイルの長さを返す
    • svn_fs_is_dir — 指定されたパスがディレクトリかを判定する
    • svn_fs_is_file — 指定されたパスがファイルかを判定する
    • svn_fs_make_dir — 新しい空のディレクトリを作成する
    • svn_fs_make_file — 新しい空のファイルを作成する
    • svn_fs_node_created_rev — fsroot 配下のパスが作成されたリビジョンを返す
    • svn_fs_node_prop — ノードのプロパティの値を返す
    • svn_fs_props_changed — プロパティが変更されている場合に true、それ以外の場合に false を返す
    • svn_fs_revision_prop — 指定したプロパティの値を取得する
    • svn_fs_revision_root — リポジトリのルートの指定したバージョンのハンドルを取得する
    • svn_fs_txn_root — トランザクションのルートを作成して返す
    • svn_fs_youngest_rev — ファイルシステム内で一番若いリビジョン番号を返す
    • svn_import — バージョン管理されていないパスをリポジトリにインポートする
    • svn_log — 指定したリポジトリ URL のコミットログメッセージを返す
    • svn_ls — Returns list of directory contents in repository URL, optionally at revision number
    • svn_mkdir — 作業コピーあるいはリポジトリ内にディレクトリを作成する
    • svn_repos_create — 新しい subversion リポジトリを指定したパスに作成する
    • svn_repos_fs — リポジトリ用に、ファイルシステム上のハンドルを取得する
    • svn_repos_fs_begin_txn_for_commit — 新しいトランザクションを作成する
    • svn_repos_fs_commit_txn — トランザクションをコミットし、新しいリビジョンを返す
    • svn_repos_hotcopy — repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする
    • svn_repos_open — Open a shared lock on a repository
    • svn_repos_recover — Run recovery procedures on the repository located at path
    • svn_revert — Revert changes to the working copy
    • svn_status — Returns the status of working copy files and directories
    • svn_update — Update working copy


はじめに

この拡張モジュールは、バージョン管理システム » Subversion (SVN) を PHP から操作するためのものです。 コマンドラインから svn をコールせずに PHP スクリプトから SVN リポジトリや作業コピーを操作することができます。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SVN
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

この拡張モジュールを使うのに、Subversion のバイナリは不要です。しかし、この拡張モジュールをコンパイルする際には libsvn (Subversion のヘッダ) が必須となります。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/svn

./configure が SVN 関連のファイルを見つけられない場合 (Subversion が標準とは異なる場所にインストールされている場合など) は、./configure --with-svn=$USR_PATH として include/subversion-1/ フォルダの場所を指定します

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

警告

この拡張モジュールを libsvn 1.3 でコンパイルした場合は、 Subversion 1.4 で作成した作業コピーを操作しようとすると失敗します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SVN_REVISION_HEAD (int)
HEAD リビジョンを指すマジックナンバー (-1)。
svn_auth_set_parameter() で使用する定数
SVN_AUTH_PARAM_DEFAULT_USERNAME (string)
ベーシック認証で使用するデフォルトのユーザー名を表すプロパティ。
SVN_AUTH_PARAM_DEFAULT_PASSWORD (string)
ベーシック認証で使用するデフォルトのパスワードを表すプロパティ。
SVN_AUTH_PARAM_NON_INTERACTIVE (string)
SVN_AUTH_PARAM_DONT_STORE_PASSWORDS (string)
SVN_AUTH_PARAM_NO_AUTH_CACHE (string)
SVN_AUTH_PARAM_SSL_SERVER_FAILURES (string)
SVN_AUTH_PARAM_SSL_SERVER_CERT_INFO (string)
SVN_AUTH_PARAM_CONFIG (string)
SVN_AUTH_PARAM_SERVER_GROUP (string)
SVN_AUTH_PARAM_CONFIG_DIR (string)
PHP_SVN_AUTH_PARAM_IGNORE_SSL_VERIFY_ERRORS (string)
SSL 証明書の検証エラーを無視するカスタムプロパティ。
ファイルシステムの定数
SVN_FS_CONFIG_FS_TYPE (string)
ファイルシステムの形式を決める設定キー。
SVN_FS_TYPE_BDB (string)
ファイルシステムは Berkeley-DB です。
SVN_FS_TYPE_FSFS (string)
ファイルシステムはネイティブのファイルシステムです。
予約されているプロパティの定数
SVN_PROP_REVISION_DATE (string)
svn:date
SVN_PROP_REVISION_ORIG_DATE (string)
svn:original-date
SVN_PROP_REVISION_AUTHOR (string)
svn:author
SVN_PROP_REVISION_LOG (string)
svn:log
作業コピーの状態に関する定数
SVN_WC_STATUS_NONE (int)
状態が存在しません。
SVN_WC_STATUS_UNVERSIONED (int)
この作業コピー内でバージョン管理されていません。
SVN_WC_STATUS_NORMAL (int)
アイテムは存在しますが、特に何もない状態です。
SVN_WC_STATUS_ADDED (int)
追加予約されています。
SVN_WC_STATUS_MISSING (int)
バージョン管理されているアイテムですが、作業コピー内に存在しません。
SVN_WC_STATUS_DELETED (int)
削除予約されています。
SVN_WC_STATUS_REPLACED (int)
いったん削除されたあとに再度追加されました。
SVN_WC_STATUS_MODIFIED (int)
アイテム (の内容あるいはプロパティ) が変更されました。
SVN_WC_STATUS_MERGED (int)
ローカルでの変更内容がリポジトリの変更内容とマージされました。
SVN_WC_STATUS_CONFLICTED (int)
ローカルでの変更内容がリポジトリでの変更内容と衝突 (conflict) しています。
SVN_WC_STATUS_IGNORED (int)
バージョン管理されていないアイテムですが、無視するよう設定されています。
SVN_WC_STATUS_OBSTRUCTED (int)
バージョン管理されていないアイテムが、 バージョン管理下のリソースを邪魔しています。
SVN_WC_STATUS_EXTERNAL (int)
バージョン管理されていないパスで、 svn:externals を使用しています。
SVN_WC_STATUS_INCOMPLETE (int)
ディレクトリのエントリ一覧がありません。
ノードの種類を表す定数
SVN_NODE_NONE (int)
存在しない。
SVN_NODE_FILE (int)
ファイル。
SVN_NODE_DIR (int)
ディレクトリ。
SVN_NODE_UNKNOWN (int)
Subversion が判別できない何か。


SVN 関数

目次

  • svn_add — Schedules the addition of an item in a working directory
  • svn_auth_get_parameter — 認証パラメータを取得する
  • svn_auth_set_parameter — 認証パラメータを設定する
  • svn_blame — ファイルの SVN blame を取得する
  • svn_cat — リポジトリ内のファイルの内容を返す
  • svn_checkout — リポジトリから作業コピーをチェックアウトする
  • svn_cleanup — 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する
  • svn_client_version — SVN クライアントライブラリのバージョンを返す
  • svn_commit — Sends changes from the local working copy to the repository
  • svn_delete — Delete items from a working copy or repository
  • svn_diff — ふたつのパスの差分を再帰的に取得する
  • svn_export — Export the contents of a SVN directory
  • svn_fs_abort_txn — トランザクションを中断する
  • svn_fs_apply_text — 置換に使用するストリームを作成して返す
  • svn_fs_begin_txn2 — 新しいトランザクションを作成する
  • svn_fs_change_node_prop — 成功したら true、失敗したら false を返す
  • svn_fs_check_path — 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる
  • svn_fs_contents_changed — コンテンツが変更されている場合に true、されていない場合に false を返す
  • svn_fs_copy — ファイルまたはディレクトリをコピーする
  • svn_fs_delete — ファイルまたはディレクトリを削除する
  • svn_fs_dir_entries — 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す
  • svn_fs_file_contents — 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す
  • svn_fs_file_length — 指定したバージョンの fs から、ファイルの長さを返す
  • svn_fs_is_dir — 指定されたパスがディレクトリかを判定する
  • svn_fs_is_file — 指定されたパスがファイルかを判定する
  • svn_fs_make_dir — 新しい空のディレクトリを作成する
  • svn_fs_make_file — 新しい空のファイルを作成する
  • svn_fs_node_created_rev — fsroot 配下のパスが作成されたリビジョンを返す
  • svn_fs_node_prop — ノードのプロパティの値を返す
  • svn_fs_props_changed — プロパティが変更されている場合に true、それ以外の場合に false を返す
  • svn_fs_revision_prop — 指定したプロパティの値を取得する
  • svn_fs_revision_root — リポジトリのルートの指定したバージョンのハンドルを取得する
  • svn_fs_txn_root — トランザクションのルートを作成して返す
  • svn_fs_youngest_rev — ファイルシステム内で一番若いリビジョン番号を返す
  • svn_import — バージョン管理されていないパスをリポジトリにインポートする
  • svn_log — 指定したリポジトリ URL のコミットログメッセージを返す
  • svn_ls — Returns list of directory contents in repository URL, optionally at revision number
  • svn_mkdir — 作業コピーあるいはリポジトリ内にディレクトリを作成する
  • svn_repos_create — 新しい subversion リポジトリを指定したパスに作成する
  • svn_repos_fs — リポジトリ用に、ファイルシステム上のハンドルを取得する
  • svn_repos_fs_begin_txn_for_commit — 新しいトランザクションを作成する
  • svn_repos_fs_commit_txn — トランザクションをコミットし、新しいリビジョンを返す
  • svn_repos_hotcopy — repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする
  • svn_repos_open — Open a shared lock on a repository
  • svn_repos_recover — Run recovery procedures on the repository located at path
  • svn_revert — Revert changes to the working copy
  • svn_status — Returns the status of working copy files and directories
  • svn_update — Update working copy


Schedules the addition of an item in a working directory

  • ≪ SVN 関数
  • svn_auth_get_parameter ≫
  • PHP Manual
  • SVN 関数
  • Schedules the addition of an item in a working directory

svn_add

(PECL svn >= 0.1.0)

svn_add — Schedules the addition of an item in a working directory

説明

svn_add(string $path, bool $recursive = true, bool $force = false): bool

Adds the file, directory or symbolic link at path to the working directory. The item will be added to the repository the next time you call svn_commit() on the working copy.

パラメータ

path

Path of item to add.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

recursive

If item is directory, whether or not to recursively add all of its contents. Default is true

force

If true, Subversion will recurse into already versioned directories in order to add unversioned files that may be hiding in those directories. Default is false

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 svn_add() example

In a working directory where svn status returns:

$ svn status
?      foobar.txt

...this code:

<?php
svn_add('foobar.txt');
?>

...will schedule foobar.txt for addition into the repository.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • » SVN documentation on svn add


認証パラメータを取得する

  • ≪ svn_add
  • svn_auth_set_parameter ≫
  • PHP Manual
  • SVN 関数
  • 認証パラメータを取得する

svn_auth_get_parameter

(PECL svn >= 0.1.0)

svn_auth_get_parameter — 認証パラメータを取得する

説明

svn_auth_get_parameter(string $key): string

認証パラメータ key を取得します。 使用できるキーとその意味については 認証定数の一覧 を参照ください。

パラメータ

key

キーの名前。認証に関する定数 のいずれかを指定します。

戻り値

key の値を文字列で返します。 パラメータが存在しない場合は null を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_auth_set_parameter() - 認証パラメータを設定する
  • 認証定数


認証パラメータを設定する

  • ≪ svn_auth_get_parameter
  • svn_blame ≫
  • PHP Manual
  • SVN 関数
  • 認証パラメータを設定する

svn_auth_set_parameter

(PECL svn >= 0.1.0)

svn_auth_set_parameter — 認証パラメータを設定する

説明

svn_auth_set_parameter(string $key, string $value): void

認証パラメータ key の値を value に設定します。 使用できるキーとその意味については 認証定数の一覧 を参照ください。

パラメータ

key

キーの名前。認証に関する定数 のいずれかを指定します。

value

そのパラメータに指定する値。 値の書式は、パラメータによって異なります。

戻り値

値を返しません。

例

例1 デフォルトの認証の例

この例は、SVN のデフォルトのユーザー名を 'Bob'、デフォルトのパスワードを 'abc123' に設定します。

<?php
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_USERNAME, 'Bob');
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_PASSWORD, 'abc123');
?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_auth_get_parameter() - 認証パラメータを取得する
  • 認証定数


ファイルの SVN blame を取得する

  • ≪ svn_auth_set_parameter
  • svn_cat ≫
  • PHP Manual
  • SVN 関数
  • ファイルの SVN blame を取得する

svn_blame

(PECL svn >= 0.3.0)

svn_blame — ファイルの SVN blame を取得する

説明

svn_blame(string $repository_url, int $revision_no = SVN_REVISION_HEAD): array

リポジトリの URL を指定して、ファイルの SVN blame を取得します。

パラメータ

repository_url

リポジトリの URL。

revision_no

リビジョン番号。

戻り値

SVN blame 情報を配列で返します。行ごとに区切られ、 リビジョン番号と行番号、コードの行、作者、日付が含まれます。

例

例1 svn_blame() の例

<?php
$svnurl = 'http://svn.example.org/svnroot/foo/trunk/index.php';

print_r( svn_blame($svnurl) );

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] = Array
          (
           [rev] = 1
           [line_no] = 1
           [line] = Hello World
           [author] = joesmith
           [date] = 2007-07-02T05:51:26.628396Z
          )
    [1] = Array
          ...

参考

  • svn_diff() - ふたつのパスの差分を再帰的に取得する
  • svn_logs()
  • svn_status() - Returns the status of working copy files and directories


リポジトリ内のファイルの内容を返す

  • ≪ svn_blame
  • svn_checkout ≫
  • PHP Manual
  • SVN 関数
  • リポジトリ内のファイルの内容を返す

svn_cat

(PECL svn >= 0.1.0)

svn_cat — リポジトリ内のファイルの内容を返す

説明

svn_cat(string $repos_url, int $revision_no = ?): string

リポジトリ内のファイルを指す URL repos_url の中身を返します。オプションでリビジョン番号 revision_no を指定します。

パラメータ

repos_url

リポジトリ内のアイテムへのパスを表す URL 文字列。

revision_no

取得したいリビジョン番号を表す整数値。デフォルトは HEAD リビジョン。

戻り値

成功した場合にアイテムの内容を表す文字列、失敗した場合に false を返します。

例

例1 基本的な例

この例は、あるファイルのリビジョン 20 の内容を取得します。

<?php
$contents = svn_cat('http://www.example.com/svnroot/calc/gui.c', 28)
?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_list()
  • » SVN ドキュメントの svn cat


リポジトリから作業コピーをチェックアウトする

  • ≪ svn_cat
  • svn_cleanup ≫
  • PHP Manual
  • SVN 関数
  • リポジトリから作業コピーをチェックアウトする

svn_checkout

(PECL svn >= 0.1.0)

svn_checkout — リポジトリから作業コピーをチェックアウトする

説明

svn_checkout(
string $repos,
string $targetpath,
int $revision = ?,
int $flags = 0
): bool

repos にあるリポジトリの リビジョン revision を、 targetpath の作業コピーにチェックアウトします。

パラメータ

repos

チェックアウトしたいリポジトリ内のディレクトリを表す URL 文字列。

targetpath

チェックアウト先ディレクトリのローカルパス。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

revision

チェックアウトしたいリビジョン番号を表す整数値。デフォルトは HEAD リビジョンで、これは最新のリビジョンを表します。

flags

SVN_NON_RECURSIVE および SVN_IGNORE_EXTERNALS の任意の組み合わせ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な例

この例は、リポジトリ内のディレクトリを calc という名前のローカルディレクトリにチェックアウトします。

<?php
svn_checkout('http://www.example.com/svnroot/calc/trunk', dirname(__FILE__) . '/calc');
?>

dirname(__FILE__) を使用して、 相対パス calc を絶対パスに変換する必要があります。 もし calc ディレクトリが存在するのなら、 realpath() を使って絶対パスを取得することもできます。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_add() - Schedules the addition of an item in a working directory
  • svn_commit() - Sends changes from the local working copy to the repository
  • svn_status() - Returns the status of working copy files and directories
  • svn_update() - Update working copy
  • » SVN ドキュメントの svn checkout


作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する

  • ≪ svn_checkout
  • svn_client_version ≫
  • PHP Manual
  • SVN 関数
  • 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する

svn_cleanup

(PECL svn >= 0.1.0)

svn_cleanup — 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する

説明

svn_cleanup(string $workingdir): bool

作業コピーディレクトリ workingdir を再帰的にクリーンアップし、中途半端になっている操作を完了してロックを削除します。 作業コピーが中途半端な状態になってしまったときに、 再度使用可能にするために用います。

パラメータ

workingdir

クリーンアップしたい作業ディレクトリへのパス。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な例

この例は、help-me という作業ディレクトリのクリーンアップを行います。

<?php
svn_cleanup(realpath('help-me'));
?>

SVN における相対パスの扱いは少々変わっているので、 realpath() のコールは必須です。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • update()
  • » SVN ドキュメントの svn cleanup


SVN クライアントライブラリのバージョンを返す

  • ≪ svn_cleanup
  • svn_commit ≫
  • PHP Manual
  • SVN 関数
  • SVN クライアントライブラリのバージョンを返す

svn_client_version

(PECL svn >= 0.1.0)

svn_client_version — SVN クライアントライブラリのバージョンを返す

説明

svn_client_version(): string

SVN クライアントライブラリのバージョンを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

バージョン番号を表す文字列を返します。通常は x.y.z 形式となります。

例

例1 基本的な例

<?php
echo svn_client_version();
?>

上の例の出力は、 たとえば以下のようになります。

1.3.1

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


Sends changes from the local working copy to the repository

  • ≪ svn_client_version
  • svn_delete ≫
  • PHP Manual
  • SVN 関数
  • Sends changes from the local working copy to the repository

svn_commit

(PECL svn >= 0.1.0)

svn_commit — Sends changes from the local working copy to the repository

説明

svn_commit(string $log, array $targets, bool $recursive = true): array

Commits changes made in the local working copy files enumerated in the targets array to the repository, with the log message log. Directories in the targets array will be recursively committed unless recursive is set to false.

注意: This function does not have any parameters for specifying authentication, so a username and password must be set using svn_auth_set_parameter()

パラメータ

log

String log text to commit

targets

Array of local paths of files to be committed

警告

This parameter must be an array, a string for a single target is not acceptable.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

recursive

Boolean flag to disable recursive committing of directories in the targets array. Default is true.

戻り値

Returns array in form of:

array(
    0 => integer revision number of commit
    1 => string ISO 8601 date and time of commit
    2 => name of committer
)

Returns false on failure.

例

例1 Basic example

This example commits the calculator directory to a repository, using the username Bob and the password abc123 (hopefully, his password is stronger):

<?php
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_USERNAME, 'Bob');
svn_auth_set_parameter(SVN_AUTH_PARAM_DEFAULT_PASSWORD, 'abc123');
var_dump(svn_commit('Log message of Bob\'s commit', array(realpath('calculator'))));
?>

上の例の出力は以下となります。

array(
  0 => 1415,
  1 => '2007-05-26T01:44:28.453125Z',
  2 => 'Bob'
)

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_auth_set_parameter() - 認証パラメータを設定する
  • » SVN documentation on svn commit


Delete items from a working copy or repository

  • ≪ svn_commit
  • svn_diff ≫
  • PHP Manual
  • SVN 関数
  • Delete items from a working copy or repository

svn_delete

(PECL svn >= 0.4.0)

svn_delete — Delete items from a working copy or repository

説明

svn_delete(string $path, bool $force = false): bool

Deletes the file, directory or symbolic link at path from the working directory. The item will be deleted from the repository the next time you call svn_commit() on the working copy.

パラメータ

path

Path of item to delete.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

force

If true, the file will be deleted even if it has local modifications. Otherwise, local modifications will result in a failure. Default is false

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • » SVN documentation on svn delete


ふたつのパスの差分を再帰的に取得する

  • ≪ svn_delete
  • svn_export ≫
  • PHP Manual
  • SVN 関数
  • ふたつのパスの差分を再帰的に取得する

svn_diff

(PECL svn >= 0.1.0)

svn_diff — ふたつのパスの差分を再帰的に取得する

説明

svn_diff(
string $path1,
int $rev1,
string $path2,
int $rev2
): array

ふたつのパス path1 および path2 の差分を再帰的に取得します。

注意:

汎用的な diff ツールとは異なり、 バージョン管理の対象になっているローカルファイルしか差分取得の対象となりません。 その他のファイルの差分は取得できません。

パラメータ

path1

最初のパス。SVN リポジトリのファイル/ディレクトリを指す URL、 あるいはローカルのファイル/ディレクトリのパスのいずれかとなります。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

警告

ローカルファイルのパスを指定する際に、 バックスラッシュのみを使用して通常のスラッシュが存在しない場合は、 パスの検出に失敗してしまいます。この関数を使う際には、 バックスラッシュをすべてスラッシュに置き換えるようにしましょう。

rev1

最初のパスのリビジョン番号。最新のリビジョンを指定したい場合は SVN_REVISION_HEAD を使用します。

path2

もうひとつのパス。詳細は path1 の説明を参照ください。

rev2

もうひとつのパスのリビジョン番号。詳細は rev1 の説明を参照ください。

戻り値

ふたつのストリームの内容を含む配列のリストを返します。 最初のストリームが diff の出力で、もうひとつはエラー出力です。 このストリームを読み込むには fread() を使用します。エラーが発生した場合は false あるいは null を返します。

デフォルトでは、diff の出力は Subversion 版の unified diff 形式となります。しかし、Subversion の設定によっては » 外部の diff エンジン を使うこともできます。

例

例1 基本的な例

ここでは、この関数の基本的な使用法と結果の取得法を示します。

<?php
list($diff, $errors) = svn_diff(
'http://www.example.com/svnroot/trunk/foo', SVN_REVISION_HEAD,
'http://www.example.com/svnroot/branches/dev/foo', SVN_REVISION_HEAD
);
if (!$diff) exit;
$contents = '';
while (!feof($diff)) {
$contents .= fread($diff, 8192);
}
fclose($diff);
fclose($errors);
var_dump($contents);
?>

上の例の出力は以下となります。

Index: http://www.example.com/svnroot/trunk/foo
===================================================================
--- http://www.example.com/svnroot/trunk/foo        (.../foo) (revision 23)
+++ http://www.example.com/svnroot/branches/dev/foo (.../foo) (revision 27)
 // この後に diff の内容が続きます

例2 あるパスのふたつのリビジョンの差分の取得

この例では、外部リポジトリ上の同じパスのアイテムについて、 ふたつのリビジョン間の差分を簡単に取得できるようにしたラッパー関数を実装します (デフォルトの構文だと少々冗長なので)。

<?php
function svn_diff_same_item($path, $rev1, $rev2) {
return svn_diff($path, $rev1, $path, $rev2);
}
?>

例3 ローカルファイルの差分の取得

この例では、ふたつのローカルファイルの差分を 簡単に取得できるようなラッパー関数を実装します。 realpath() による補正と、 バックスラッシュに関するバグの対応を含めています。

<?php
function svn_diff_local($path1, $rev1, $path2, $rev2) {
$path1 = str_replace('\\', '/', realpath($path1));
$path2 = str_replace('\\', '/', realpath($path2));
return svn_diff($path1, $rev1, $path2, $rev2);
}
?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • » SVN ドキュメントの svn diff


Export the contents of a SVN directory

  • ≪ svn_diff
  • svn_fs_abort_txn ≫
  • PHP Manual
  • SVN 関数
  • Export the contents of a SVN directory

svn_export

(PECL svn >= 0.3.0)

svn_export — Export the contents of a SVN directory

説明

svn_export(
string $frompath,
string $topath,
bool $working_copy = true,
int $revision_no = -1
): bool

Export the contents of either a working copy or repository into a 'clean' directory.

パラメータ

frompath

The path to the current repository.

topath

The path to the new repository.

working_copy

If true, it will export uncommitted files from the working copy.

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 svn_export() example

<?php
$working_dir = '../';
$new_working_dir = '/home/user/devel/foo/trunk';

svn_export($working_dir, $new_working_dir);
?>

参考

  • svn_import() - バージョン管理されていないパスをリポジトリにインポートする


トランザクションを中断する

  • ≪ svn_export
  • svn_fs_apply_text ≫
  • PHP Manual
  • SVN 関数
  • トランザクションを中断する

svn_fs_abort_txn

(PECL svn >= 0.2.0)

svn_fs_abort_txn — トランザクションを中断する

説明

svn_fs_abort_txn(resource $txn): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

トランザクションを中断します。

パラメータ

txn

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


置換に使用するストリームを作成して返す

  • ≪ svn_fs_abort_txn
  • svn_fs_begin_txn2 ≫
  • PHP Manual
  • SVN 関数
  • 置換に使用するストリームを作成して返す

svn_fs_apply_text

(PECL svn >= 0.2.0)

svn_fs_apply_text — 置換に使用するストリームを作成して返す

説明

svn_fs_apply_text(resource $root, string $path): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

置換に使用するストリームを作成して返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


新しいトランザクションを作成する

  • ≪ svn_fs_apply_text
  • svn_fs_change_node_prop ≫
  • PHP Manual
  • SVN 関数
  • 新しいトランザクションを作成する

svn_fs_begin_txn2

(PECL svn >= 0.2.0)

svn_fs_begin_txn2 — 新しいトランザクションを作成する

説明

svn_fs_begin_txn2(resource $repos, int $rev): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しいトランザクションを作成します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


成功したら true、失敗したら false を返す

  • ≪ svn_fs_begin_txn2
  • svn_fs_check_path ≫
  • PHP Manual
  • SVN 関数
  • 成功したら true、失敗したら false を返す

svn_fs_change_node_prop

(PECL svn >= 0.2.0)

svn_fs_change_node_prop — 成功したら true、失敗したら false を返す

説明

svn_fs_change_node_prop(
resource $root,
string $path,
string $name,
string $value
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

成功したら true、失敗したら false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる

  • ≪ svn_fs_change_node_prop
  • svn_fs_contents_changed ≫
  • PHP Manual
  • SVN 関数
  • 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる

svn_fs_check_path

(PECL svn >= 0.1.0)

svn_fs_check_path — 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる

説明

svn_fs_check_path(resource $fsroot, string $path): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べます。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


コンテンツが変更されている場合に true、されていない場合に false を返す

  • ≪ svn_fs_check_path
  • svn_fs_copy ≫
  • PHP Manual
  • SVN 関数
  • コンテンツが変更されている場合に true、されていない場合に false を返す

svn_fs_contents_changed

(PECL svn >= 0.2.0)

svn_fs_contents_changed — コンテンツが変更されている場合に true、されていない場合に false を返す

説明

svn_fs_contents_changed(
resource $root1,
string $path1,
resource $root2,
string $path2
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

コンテンツが変更されている場合に true、されていない場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


ファイルまたはディレクトリをコピーする

  • ≪ svn_fs_contents_changed
  • svn_fs_delete ≫
  • PHP Manual
  • SVN 関数
  • ファイルまたはディレクトリをコピーする

svn_fs_copy

(PECL svn >= 0.2.0)

svn_fs_copy — ファイルまたはディレクトリをコピーする

説明

svn_fs_copy(
resource $from_root,
string $from_path,
resource $to_root,
string $to_path
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルまたはディレクトリをコピーします。

パラメータ

from_root

from_path

to_root

to_path

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


ファイルまたはディレクトリを削除する

  • ≪ svn_fs_copy
  • svn_fs_dir_entries ≫
  • PHP Manual
  • SVN 関数
  • ファイルまたはディレクトリを削除する

svn_fs_delete

(PECL svn >= 0.2.0)

svn_fs_delete — ファイルまたはディレクトリを削除する

説明

svn_fs_delete(resource $root, string $path): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルまたはディレクトリを削除します。

パラメータ

root

path

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す

  • ≪ svn_fs_delete
  • svn_fs_file_contents ≫
  • PHP Manual
  • SVN 関数
  • 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す

svn_fs_dir_entries

(PECL svn >= 0.1.0)

svn_fs_dir_entries — 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す

説明

svn_fs_dir_entries(resource $fsroot, string $path): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す

  • ≪ svn_fs_dir_entries
  • svn_fs_file_length ≫
  • PHP Manual
  • SVN 関数
  • 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す

svn_fs_file_contents

(PECL svn >= 0.1.0)

svn_fs_file_contents — 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す

説明

svn_fs_file_contents(resource $fsroot, string $path): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定したバージョンの fs から、ファイルの長さを返す

  • ≪ svn_fs_file_contents
  • svn_fs_is_dir ≫
  • PHP Manual
  • SVN 関数
  • 指定したバージョンの fs から、ファイルの長さを返す

svn_fs_file_length

(PECL svn >= 0.1.0)

svn_fs_file_length — 指定したバージョンの fs から、ファイルの長さを返す

説明

svn_fs_file_length(resource $fsroot, string $path): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したバージョンの fs から、ファイルの長さを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定されたパスがディレクトリかを判定する

  • ≪ svn_fs_file_length
  • svn_fs_is_file ≫
  • PHP Manual
  • SVN 関数
  • 指定されたパスがディレクトリかを判定する

svn_fs_is_dir

(PECL svn >= 0.2.0)

svn_fs_is_dir — 指定されたパスがディレクトリかを判定する

説明

svn_fs_is_dir(resource $root, string $path): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定されたパスがディレクトリかを判定します。

パラメータ

root

path

戻り値

指定されたパスがディレクトリであれば true を返します。 そうでない場合、false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定されたパスがファイルかを判定する

  • ≪ svn_fs_is_dir
  • svn_fs_make_dir ≫
  • PHP Manual
  • SVN 関数
  • 指定されたパスがファイルかを判定する

svn_fs_is_file

(PECL svn >= 0.2.0)

svn_fs_is_file — 指定されたパスがファイルかを判定する

説明

svn_fs_is_file(resource $root, string $path): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定されたパスがファイルかを判定します。

パラメータ

root

path

戻り値

指定されたパスがファイルであれば true を返します。 そうでない場合、false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


新しい空のディレクトリを作成する

  • ≪ svn_fs_is_file
  • svn_fs_make_file ≫
  • PHP Manual
  • SVN 関数
  • 新しい空のディレクトリを作成する

svn_fs_make_dir

(PECL svn >= 0.2.0)

svn_fs_make_dir — 新しい空のディレクトリを作成する

説明

svn_fs_make_dir(resource $root, string $path): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい空のディレクトリを作成します。

パラメータ

root

path

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


新しい空のファイルを作成する

  • ≪ svn_fs_make_dir
  • svn_fs_node_created_rev ≫
  • PHP Manual
  • SVN 関数
  • 新しい空のファイルを作成する

svn_fs_make_file

(PECL svn >= 0.2.0)

svn_fs_make_file — 新しい空のファイルを作成する

説明

svn_fs_make_file(resource $root, string $path): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい空のファイルを作成します。

パラメータ

root

path

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


fsroot 配下のパスが作成されたリビジョンを返す

  • ≪ svn_fs_make_file
  • svn_fs_node_prop ≫
  • PHP Manual
  • SVN 関数
  • fsroot 配下のパスが作成されたリビジョンを返す

svn_fs_node_created_rev

(PECL svn >= 0.1.0)

svn_fs_node_created_rev — fsroot 配下のパスが作成されたリビジョンを返す

説明

svn_fs_node_created_rev(resource $fsroot, string $path): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

fsroot 配下のパスが作成されたリビジョンを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


ノードのプロパティの値を返す

  • ≪ svn_fs_node_created_rev
  • svn_fs_props_changed ≫
  • PHP Manual
  • SVN 関数
  • ノードのプロパティの値を返す

svn_fs_node_prop

(PECL svn >= 0.1.0)

svn_fs_node_prop — ノードのプロパティの値を返す

説明

svn_fs_node_prop(resource $fsroot, string $path, string $propname): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ノードのプロパティの値を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


プロパティが変更されている場合に true、それ以外の場合に false を返す

  • ≪ svn_fs_node_prop
  • svn_fs_revision_prop ≫
  • PHP Manual
  • SVN 関数
  • プロパティが変更されている場合に true、それ以外の場合に false を返す

svn_fs_props_changed

(PECL svn >= 0.2.0)

svn_fs_props_changed — プロパティが変更されている場合に true、それ以外の場合に false を返す

説明

svn_fs_props_changed(
resource $root1,
string $path1,
resource $root2,
string $path2
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

プロパティが変更されている場合に true、それ以外の場合に false を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


指定したプロパティの値を取得する

  • ≪ svn_fs_props_changed
  • svn_fs_revision_root ≫
  • PHP Manual
  • SVN 関数
  • 指定したプロパティの値を取得する

svn_fs_revision_prop

(PECL svn >= 0.1.0)

svn_fs_revision_prop — 指定したプロパティの値を取得する

説明

svn_fs_revision_prop(resource $fs, int $revnum, string $propname): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定したプロパティの値を取得します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


リポジトリのルートの指定したバージョンのハンドルを取得する

  • ≪ svn_fs_revision_prop
  • svn_fs_txn_root ≫
  • PHP Manual
  • SVN 関数
  • リポジトリのルートの指定したバージョンのハンドルを取得する

svn_fs_revision_root

(PECL svn >= 0.1.0)

svn_fs_revision_root — リポジトリのルートの指定したバージョンのハンドルを取得する

説明

svn_fs_revision_root(resource $fs, int $revnum): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

リポジトリのルートの指定したバージョンのハンドルを取得します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


トランザクションのルートを作成して返す

  • ≪ svn_fs_revision_root
  • svn_fs_youngest_rev ≫
  • PHP Manual
  • SVN 関数
  • トランザクションのルートを作成して返す

svn_fs_txn_root

(PECL svn >= 0.2.0)

svn_fs_txn_root — トランザクションのルートを作成して返す

説明

svn_fs_txn_root(resource $txn): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

トランザクションのルートを作成して返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


ファイルシステム内で一番若いリビジョン番号を返す

  • ≪ svn_fs_txn_root
  • svn_import ≫
  • PHP Manual
  • SVN 関数
  • ファイルシステム内で一番若いリビジョン番号を返す

svn_fs_youngest_rev

(PECL svn >= 0.1.0)

svn_fs_youngest_rev — ファイルシステム内で一番若いリビジョン番号を返す

説明

svn_fs_youngest_rev(resource $fs): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ファイルシステム内で一番若いリビジョン番号を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


バージョン管理されていないパスをリポジトリにインポートする

  • ≪ svn_fs_youngest_rev
  • svn_log ≫
  • PHP Manual
  • SVN 関数
  • バージョン管理されていないパスをリポジトリにインポートする

svn_import

(PECL svn >= 0.2.0)

svn_import — バージョン管理されていないパスをリポジトリにインポートする

説明

svn_import(string $path, string $url, bool $nonrecursive): bool

バージョン管理されていないパス path を、 url で指定したリポジトリにコミットします。 path がディレクトリで nonrecursive が false の場合は、 再帰的にインポートします。

パラメータ

path

インポートするファイルあるいはディレクトリのパス。

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

url

インポート先のリポジトリの URL。

nonrecursive

ディレクトリを再帰処理するかどうか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な例

この例は、関数の基本的な使用法を示すものです。 new-files というディレクトリを http://www.example.com/svnroot/incoming/abc にインポートするには、次のようにします。

<?php
svn_import(realpath('new-files'), 'http://www.example.com/svnroot/incoming/abc', false);
?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_add() - Schedules the addition of an item in a working directory
  • » SVN ドキュメントの svn import


指定したリポジトリ URL のコミットログメッセージを返す

  • ≪ svn_import
  • svn_ls ≫
  • PHP Manual
  • SVN 関数
  • 指定したリポジトリ URL のコミットログメッセージを返す

svn_log

(PECL svn >= 0.1.0)

svn_log — 指定したリポジトリ URL のコミットログメッセージを返す

説明

svn_log(
string $repos_url,
int $start_revision = ?,
int $end_revision = ?,
int $limit = 0,
int $flags = SVN_DISCOVER_CHANGED_PATHS | SVN_STOP_ON_COPY
): array

svn_log() は、指定したリビジョン URL repos_url の中身の完全な履歴を返します。 start_revision を指定した場合は、そのリビジョンの履歴を返します。 この関数は、svn log --verbose -r $start_revision $repos_url と同等です。

パラメータ

repos_url

履歴を取得したいアイテムのリポジトリ URL。

start_revision

ログを取得したい最初のリビジョン番号。直近のリビジョンからのログを取得する場合は SVN_REVISION_HEAD を使用します。

end_revision

ログを取得したい最後のリビジョン番号。デフォルトは、 start_revision を指定した場合はそれと同じで 指定しなかった場合は SVN_REVISION_INITIAL となります。

limit

取得したいログの数。

flags

SVN_OMIT_MESSAGES、 SVN_DISCOVER_CHANGED_PATHS および SVN_STOP_ON_COPY の任意の組み合わせ。

戻り値

成功した場合は、この関数は次のような構造の配列を返します。

[0] => Array (最新のリポジトリから順に並びます)
(
    [rev] => リビジョン番号
    [author] => コミットした人の名前
    [msg] => ログメッセージ
    [date] => ISO 8601 形式、つまり date('c') と同じ形式の日付文字列
    [paths] => Array (変更したファイルについての説明)
        (
            [0] => Array
                (
                    [action] => 変更の種類を表す文字
                    [path] =>  変更されたファイルの絶対パス
                )
            [1] => ...
        )
)
[1] => ...

注意:

出力は、常に数値添字の二次元配列となります。 ログメッセージがなかったり、ひとつだけだったりする場合でも同じです。

action の値は、 » status の出力の最初の列の内容 のサブセットで、以下のいずれかとなります。

アクション
文字 | 説明
M | アイテム/プロパティが変更されました
A | アイテムが追加されました
D | アイテムが削除されました
R | アイテムが置き換えられました

何も変更されていない場合は、空の配列を返します。

例

例1 svn_log() の例

<?php
print_r( svn_log('http://www.example.com/', 23) );
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
    (
        [rev] => 23
        [author] => 'joe'
        [msg] => 'チーズとサラミをサンドイッチに追加した。'
        [date] => '2007-04-06T16:00:27-04:00'
        [paths] => Array
            (
                [0] => Array
                    (
                        [action] => 'M'
                        [path] =>  '/sandwich.txt'
                    )
            )
    )
)

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • » SVN ドキュメントの svn log


Returns list of directory contents in repository URL, optionally at revision number

  • ≪ svn_log
  • svn_mkdir ≫
  • PHP Manual
  • SVN 関数
  • Returns list of directory contents in repository URL, optionally at revision number

svn_ls

(PECL svn >= 0.1.0)

svn_ls — Returns list of directory contents in repository URL, optionally at revision number

説明

svn_ls(
string $repos_url,
int $revision_no = SVN_REVISION_HEAD,
bool $recurse = false,
bool $peg = false
): array

This function queries the repository URL and returns a list of files and directories, optionally from a specific revision. This is equivalent to svn list $repos_url[@$revision_no]

注意:

This function does not work with working copies. repos_url must be a repository URL.

パラメータ

url

URL of the repository, eg. http://www.example.com/svnroot. To access a local Subversion repository via filesystem, use the file URI scheme, eg. file:///home/user/svn-repos

revision

Integer revision number to retrieve listing of. When omitted, the HEAD revision is used.

recurse

Enables recursion.

戻り値

On success, this function returns an array file listing in the format of:

[0] => Array
    (
        [created_rev] => integer revision number of last edit
        [last_author] => string author name of last edit
        [size] => integer byte file size of file
        [time] => string date of last edit in form 'M d H:i'
                  or 'M d Y', depending on how old the file is
        [time_t] => integer unix timestamp of last edit
        [name] => name of file/directory
        [type] => type, can be 'file' or 'dir'
    )
[1] => ...

例

例1 svn_ls() example

<?php
print_r( svn_ls('http://www.example.com/svnroot/') );
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [created_rev] => 20
            [last_author] => Joe
            [size] => 0
            [time] => Apr 02 09:28
            [time_t] => 1175520529
            [name] => tags
            [type] => dir
        )
    [1] => Array
        (
            [created_rev] => 23
            [last_author] => Bob
            [size] => 0
            [time] => Apr 02 15:15
            [time_t] => 1175541322
            [name] => trunk
            [type] => dir
        )
)

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • » SVN documentation on svn list


作業コピーあるいはリポジトリ内にディレクトリを作成する

  • ≪ svn_ls
  • svn_repos_create ≫
  • PHP Manual
  • SVN 関数
  • 作業コピーあるいはリポジトリ内にディレクトリを作成する

svn_mkdir

(PECL svn >= 0.4.0)

svn_mkdir — 作業コピーあるいはリポジトリ内にディレクトリを作成する

説明

svn_mkdir(string $path, string $log_message = ?): bool

作業コピーあるいはリポジトリ内にディレクトリを作成します。

パラメータ

path

作業コピーあるいはリポジトリへのパス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • svn_add() - Schedules the addition of an item in a working directory
  • svn_copy()


新しい subversion リポジトリを指定したパスに作成する

  • ≪ svn_mkdir
  • svn_repos_fs ≫
  • PHP Manual
  • SVN 関数
  • 新しい subversion リポジトリを指定したパスに作成する

svn_repos_create

(PECL svn >= 0.1.0)

svn_repos_create — 新しい subversion リポジトリを指定したパスに作成する

説明

svn_repos_create(string $path, array $config = ?, array $fsconfig = ?): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい subversion リポジトリを指定したパスに作成します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


リポジトリ用に、ファイルシステム上のハンドルを取得する

  • ≪ svn_repos_create
  • svn_repos_fs_begin_txn_for_commit ≫
  • PHP Manual
  • SVN 関数
  • リポジトリ用に、ファイルシステム上のハンドルを取得する

svn_repos_fs

(PECL svn >= 0.1.0)

svn_repos_fs — リポジトリ用に、ファイルシステム上のハンドルを取得する

説明

svn_repos_fs(resource $repos): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

リポジトリ用に、ファイルシステム上のハンドルを取得します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


新しいトランザクションを作成する

  • ≪ svn_repos_fs
  • svn_repos_fs_commit_txn ≫
  • PHP Manual
  • SVN 関数
  • 新しいトランザクションを作成する

svn_repos_fs_begin_txn_for_commit

(PECL svn >= 0.2.0)

svn_repos_fs_begin_txn_for_commit — 新しいトランザクションを作成する

説明

svn_repos_fs_begin_txn_for_commit(
resource $repos,
int $rev,
string $author,
string $log_msg
): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しいトランザクションを作成します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


トランザクションをコミットし、新しいリビジョンを返す

  • ≪ svn_repos_fs_begin_txn_for_commit
  • svn_repos_hotcopy ≫
  • PHP Manual
  • SVN 関数
  • トランザクションをコミットし、新しいリビジョンを返す

svn_repos_fs_commit_txn

(PECL svn >= 0.2.0)

svn_repos_fs_commit_txn — トランザクションをコミットし、新しいリビジョンを返す

説明

svn_repos_fs_commit_txn(resource $txn): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

トランザクションをコミットし、新しいリビジョンを返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする

  • ≪ svn_repos_fs_commit_txn
  • svn_repos_open ≫
  • PHP Manual
  • SVN 関数
  • repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする

svn_repos_hotcopy

(PECL svn >= 0.1.0)

svn_repos_hotcopy — repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする

説明

svn_repos_hotcopy(string $repospath, string $destpath, bool $cleanlogs): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

repospath にあるリポジトリのホットコピーを作成し、destpath にコピーします。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


Open a shared lock on a repository

  • ≪ svn_repos_hotcopy
  • svn_repos_recover ≫
  • PHP Manual
  • SVN 関数
  • Open a shared lock on a repository

svn_repos_open

(PECL svn >= 0.1.0)

svn_repos_open — Open a shared lock on a repository

説明

svn_repos_open(string $path): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

Open a shared lock on a repository.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


Run recovery procedures on the repository located at path

  • ≪ svn_repos_open
  • svn_revert ≫
  • PHP Manual
  • SVN 関数
  • Run recovery procedures on the repository located at path

svn_repos_recover

(PECL svn >= 0.1.0)

svn_repos_recover — Run recovery procedures on the repository located at path

説明

svn_repos_recover(string $path): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

Run recovery procedures on the repository located at path.

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。


Revert changes to the working copy

  • ≪ svn_repos_recover
  • svn_status ≫
  • PHP Manual
  • SVN 関数
  • Revert changes to the working copy

svn_revert

(PECL svn >= 0.3.0)

svn_revert — Revert changes to the working copy

説明

svn_revert(string $path, bool $recursive = false): bool

Revert any local changes to the path in a working copy.

パラメータ

path

The path to the working repository.

recursive

Optionally make recursive changes.

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • svn_delete() - Delete items from a working copy or repository
  • svn_export() - Export the contents of a SVN directory


Returns the status of working copy files and directories

  • ≪ svn_revert
  • svn_update ≫
  • PHP Manual
  • SVN 関数
  • Returns the status of working copy files and directories

svn_status

(PECL svn >= 0.1.0)

svn_status — Returns the status of working copy files and directories

説明

svn_status(string $path, int $flags = 0): array

Returns the status of working copy files and directories, giving modifications, additions, deletions and other changes to items in the working copy.

パラメータ

path

Local path to file or directory to retrieve status of.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

flags

Any combination of Svn::NON_RECURSIVE, Svn::ALL (regardless of modification status), Svn::SHOW_UPDATES (entries will be added for items that are out-of-date), Svn::NO_IGNORE (disregard svn:ignore properties when scanning for new files) and Svn::IGNORE_EXTERNALS.

戻り値

Returns a numerically indexed array of associative arrays detailing the status of items in the repository:

Array (
    [0] => Array (
        // information on item
    )
    [1] => ...
)

The information on the item is an associative array that can contain the following keys:

path
String path to file/directory of this entry on local filesystem.
text_status
Status of item's text. とりうる値については 状態に関する定数 を参照ください。
repos_text_status
Status of item's text in repository. Only accurate if update was set to true. とりうる値については 状態に関する定数 を参照ください。
prop_status
Status of item's properties. とりうる値については 状態に関する定数 を参照ください。
repos_prop_status
Status of item's property in repository. Only accurate if update was set to true. とりうる値については 状態に関する定数 を参照ください。
locked
Whether or not the item is locked. (Only set if true.)
copied
Whether or not the item was copied (scheduled for addition with history). (Only set if true.)
switched
Whether or not the item was switched using the switch command. (Only set if true)

These keys are only set if the item is versioned:

name
Base name of item in repository.
url
URL of item in repository.
repos
Base URL of repository.
revision
Integer revision of item in working copy.
kind
Type of item, i.e. file or directory. とりうる値については 型に関する定数 を参照ください。
schedule
Scheduled action for item, i.e. addition or deletion. Constants for these magic numbers are not available, they can be emulated by using:
<?php
if (!defined('svn_wc_schedule_normal')) {
define('svn_wc_schedule_normal', 0); // nothing special
define('svn_wc_schedule_add', 1); // item will be added
define('svn_wc_schedule_delete', 2); // item will be deleted
define('svn_wc_schedule_replace', 3); // item will be added and deleted
}
?>
deleted
Whether or not the item was deleted, but parent revision lags behind. (Only set if true.)
absent
Whether or not the item is absent, that is, Subversion knows that there should be something there but there isn't. (Only set if true.)
incomplete
Whether or not the entries file for a directory is incomplete. (Only set if true.)
cmt_date
Integer Unix timestamp of last commit date. (Unaffected by update.)
cmt_rev
Integer revision of last commit. (Unaffected by update.)
cmt_author
String author of last commit. (Unaffected by update.)
prop_time
Integer Unix timestamp of last up-to-date time for properties
text_time
Integer Unix timestamp of last up-to-date time for text

例

例1 Basic example

This example demonstrates a basic, theoretical usage of this function.

<?php
print_r(svn_status(realpath('wc')));
?>

上の例の出力は、 たとえば以下のようになります。

Array (
    [0] => Array (
        [path] => /home/bob/wc/sandwich.txt
        [text_status] => 8 // item was modified
        [repos_text_status] => 1 // no information available, use update
        [prop_status] => 3 // no changes
        [repos_prop_status] => 1 // no information available, use update
        [name] => sandwich.txt
        [url] => http://www.example.com/svnroot/deli/trunk/sandwich.txt
        [repos] => http://www.example.com/svnroot/
        [revision] => 123
        [kind] => 1 // file
        [schedule] => 0 // no special actions scheduled
        [cmt_date] => 1165543135
        [cmt_rev] => 120
        [cmt_author] => Alice
        [prop_time] => 1180201728
        [text_time] => 1180201729
    )
)

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_update() - Update working copy
  • svn_log() - 指定したリポジトリ URL のコミットログメッセージを返す
  • » SVN documentation for svn status


Update working copy

  • ≪ svn_status
  • TCP ≫
  • PHP Manual
  • SVN 関数
  • Update working copy

svn_update

(PECL svn >= 0.1.0)

svn_update — Update working copy

説明

svn_update(string $path, int $revno = SVN_REVISION_HEAD, bool $recurse = true): int

Update working copy at path to revision revno. If recurse is true, directories will be recursively updated.

パラメータ

path

Path to local working copy.

注意: 相対パスは、PHP バイナリが存在するディレクトリを基準として解決されます。呼び出しもとのスクリプトの作業ディレクトリを基準とするには、realpath() あるいは dirname(__FILE__) を使用してください。

revno

Revision number to update to, default is SVN_REVISION_HEAD.

recurse

Whether or not to recursively update directories.

戻り値

Returns new revision number on success, returns false on failure.

例

例1 Basic example

This example demonstrates basic usage of this function:

<?php
echo svn_update(realpath('working-copy'));
?>

上の例の出力は、 たとえば以下のようになります。

234

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • svn_checkout() - リポジトリから作業コピーをチェックアウトする
  • svn_commit() - Sends changes from the local working copy to the repository
  • » SVN documentation for svn update


TCP ラッパー

  • はじめに
  • インストール/設定
    • インストール手順
  • TCP 関数
    • tcpwrap_check — tcpwrap のチェックを実行する


はじめに

TCP ラッパーは、古典的な Unix のメカニズムを提供します。 これはリモートクライアントが指定した IP アドレスから接続できるかどうかを 調べるように設計されています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • TCP
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/tcpwrap.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


  • ≪ インストール手順
  • tcpwrap_check ≫
  • PHP Manual
  • TCP
  • TCP 関数

TCP 関数

目次

  • tcpwrap_check — tcpwrap のチェックを実行する


tcpwrap のチェックを実行する

  • ≪ TCP 関数
  • Varnish ≫
  • PHP Manual
  • TCP 関数
  • tcpwrap のチェックを実行する

tcpwrap_check

(PECL tcpwrap >= 0.1.0)

tcpwrap_check — tcpwrap のチェックを実行する

説明

tcpwrap_check(
string $daemon,
string $address,
string $user = ?,
bool $nodns = false
): bool

この関数は /etc/hosts.allow および /etc/hosts.deny の内容をもとに、あるクライアントが daemon サービスへのアクセスを許可されているか 否かを調べます。

パラメータ

daemon

サービスの名前。

address

クライアントのリモートアドレス。IP アドレスあるいはドメイン名の どちらでも指定可能。

user

ユーザー名（オプション）。

nodns

address がドメイン名の場合、それを IP アドレスに名前解決するために DNS が使用されます。 nodns を true に指定すると、この処理を 禁止します。

戻り値

アクセスが許可されている場合に true 、それ以外の場合に false を返します。

例

例1 ローカルホストからの全接続を拒否する

/etc/hosts.deny ファイルに以下の行が含まれており、

php: 127.0.0.1

以下のようなコードを実行する

<?php
if (!tcpwrap_check('php', $_SERVER['REMOTE_ADDR'])) {
die('You are not welcome here');
}
?>

参考

詳細な情報は、hosts_access(3) の man ページを参照ください。


Varnish

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
    • 基本的な VarnishAdmin の使用法
    • 基本的な VarnishStat の使用法
    • 基本的な VarnishLog の使用法
  • VarnishAdmin — VarnishAdmin クラス
    • VarnishAdmin::auth — varnish インスタンス上で認証する
    • VarnishAdmin::ban — VCL の式を使って URL を禁止する
    • VarnishAdmin::banUrl — VCL の式を使って URL を禁止する
    • VarnishAdmin::clearPanic — varnish インスタンスのパニックメッセージをクリアする
    • VarnishAdmin::connect — varnish インスタンスの管理インターフェイスに接続する
    • VarnishAdmin::__construct — VarnishAdmin のコンストラクタ
    • VarnishAdmin::disconnect — varnish インスタンスの管理インターフェイスとの接続を切断する
    • VarnishAdmin::getPanic — varnish インスタンスの直近のパニックメッセージを取得する
    • VarnishAdmin::getParams — 現在の varnish インスタンスの設定パラメータを取得する
    • VarnishAdmin::isRunning — varnish のスレーブプロセスが現在実行中かどうかを調べる
    • VarnishAdmin::setCompat — クラスのオプション compat を設定する
    • VarnishAdmin::setHost — クラスのオプション host を設定する
    • VarnishAdmin::setIdent — クラスのオプション ident を設定する
    • VarnishAdmin::setParam — 現在の varnish インスタンスの構成パラメータを設定する
    • VarnishAdmin::setPort — クラスのオプション port を設定する
    • VarnishAdmin::setSecret — クラスのオプション secret を設定する
    • VarnishAdmin::setTimeout — クラスのオプション timeout を設定する
    • VarnishAdmin::start — varnish ワーカープロセスを開始する
    • VarnishAdmin::stop — varnish ワーカープロセスを停止する
  • VarnishStat — VarnishStat クラス
    • VarnishStat::__construct — VarnishStat のコンストラクタ
    • VarnishStat::getSnapshot — 現在の varnish インスタンスの統計スナップショットを取得する
  • VarnishLog — VarnishLog クラス
    • VarnishLog::__construct — Varnishlog のコンストラクタ
    • VarnishLog::getLine — ログの次の行を取得する
    • VarnishLog::getTagName — ログのタグ文字列を、インデックスから取得する


はじめに

Varnish Cache は、オープンソースな最先端のウェブアプリケーションアクセラレーターです。 この拡張モジュールを使えば、実行中の varnish インスタンスとのやりとりを TCP ソケット経由あるいは共有メモリ経由でできます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Varnish
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

この拡張モジュールを使うには、 バージョン 3.0 以降の Varnish Cache をインストールして使えるようにしておく必要があります。 これは、» Varnish キャッシュのホームページ で取得できます。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/varnish.

このモジュールの DLL は、» http://windows.php.net/downloads/pecl/releases/varnish/ にあります。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

VARNISH_STATUS_SYNTAX (int)
VARNISH_STATUS_UNKNOWN (int)
VARNISH_STATUS_UNIMPL (int)
VARNISH_STATUS_TOOFEW (int)
VARNISH_STATUS_TOOMANY (int)
VARNISH_STATUS_PARAM (int)
VARNISH_STATUS_AUTH (int)
VARNISH_STATUS_OK (int)
VARNISH_STATUS_CANT (int)
VARNISH_STATUS_COMMS (int)
VARNISH_STATUS_CLOSE (int)
VARNISH_CONFIG_IDENT (string)
VARNISH_CONFIG_HOST (string)
VARNISH_CONFIG_PORT (string)
VARNISH_CONFIG_TIMEOUT (string)
VARNISH_CONFIG_SECRET (string)
VARNISH_CONFIG_COMPAT (string)
VARNISH_COMPAT_2 (int)
VARNISH_COMPAT_3 (int)


例

目次

  • 基本的な VarnishAdmin の使用法
  • 基本的な VarnishStat の使用法
  • 基本的な VarnishLog の使用法


基本的な VarnishAdmin の使用法

禁止機能の簡単な使用法を示します。

例1 URL を禁止する

<?php

$args = array(
VARNISH_CONFIG_HOST => "::1",
VARNISH_CONFIG_PORT => 6082,
VARNISH_CONFIG_SECRET => "5174826b-8595-4958-aa7a-0609632ad7ca",
VARNISH_CONFIG_TIMEOUT => 300,
);

$va = new VarnishAdmin($args);

try {
if(!$va->connect()) {
throw new VarnishException("Connection failed\n");
}
} catch (VarnishException $e) {
echo $e->getMessage();
exit(3);
}

try {
if(!$va->auth()) {
throw new VarnishException("Auth failed\n");
}
} catch (VarnishException $e) {
echo $e->getMessage();
exit(3);
}

try {
$status = $va->ban('req.url ~ "^/$"');
if (VARNISH_STATUS_OK != $status) {
throw new VarnishException("Ban method returned $status status\n");
}
} catch (VarnishException $e) {
echo $e->getMessage();
exit(3);
}

exit(0);

?>


基本的な VarnishStat の使用法

共用メモリから、varnish 統計のスナップショットを取得する例を示します。

例1 統計のスナップショットを取得する

<?php

$vs = new VarnishStat;

try {
$data = $vs->getSnapshot();
} catch (VarnishException $e) {
echo $e->getMessage();
exit(3);
}

exit(0);
?>


基本的な VarnishLog の使用法

共用メモリから、varnish のログを読み取る例を示します。

例1 varnish の共用メモリログを読み取る

<?php

$vl = new VarnishLog;
while(1) {
$line = $vl->getLine();
printf("%s %d %s", VarnishLog::getTagName($line['tag']), $line['id'],
$line['data']);
}

exit(0);
?>


VarnishAdmin クラス

(PECL varnish >= 0.3)

はじめに

クラス概要

class VarnishAdmin {
/* メソッド */
public auth(): bool
public ban(string $vcl_regex): int
public banUrl(string $vcl_regex): int
public clearPanic(): int
public connect(): bool
public __construct(array $args = ?)
public disconnect(): bool
public getPanic(): string
public getParams(): array
public isRunning(): bool
public setCompat(int $compat): void
public setHost(string $host): void
public setIdent(string $ident): void
public setParam(string $name, string|int $value): int
public setPort(int $port): void
public setSecret(string $secret): void
public setTimeout(int $timeout): void
public start(): int
public stop(): int
}

目次

  • VarnishAdmin::auth — varnish インスタンス上で認証する
  • VarnishAdmin::ban — VCL の式を使って URL を禁止する
  • VarnishAdmin::banUrl — VCL の式を使って URL を禁止する
  • VarnishAdmin::clearPanic — varnish インスタンスのパニックメッセージをクリアする
  • VarnishAdmin::connect — varnish インスタンスの管理インターフェイスに接続する
  • VarnishAdmin::__construct — VarnishAdmin のコンストラクタ
  • VarnishAdmin::disconnect — varnish インスタンスの管理インターフェイスとの接続を切断する
  • VarnishAdmin::getPanic — varnish インスタンスの直近のパニックメッセージを取得する
  • VarnishAdmin::getParams — 現在の varnish インスタンスの設定パラメータを取得する
  • VarnishAdmin::isRunning — varnish のスレーブプロセスが現在実行中かどうかを調べる
  • VarnishAdmin::setCompat — クラスのオプション compat を設定する
  • VarnishAdmin::setHost — クラスのオプション host を設定する
  • VarnishAdmin::setIdent — クラスのオプション ident を設定する
  • VarnishAdmin::setParam — 現在の varnish インスタンスの構成パラメータを設定する
  • VarnishAdmin::setPort — クラスのオプション port を設定する
  • VarnishAdmin::setSecret — クラスのオプション secret を設定する
  • VarnishAdmin::setTimeout — クラスのオプション timeout を設定する
  • VarnishAdmin::start — varnish ワーカープロセスを開始する
  • VarnishAdmin::stop — varnish ワーカープロセスを停止する


varnish インスタンス上で認証する

  • ≪ VarnishAdmin
  • VarnishAdmin::ban ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンス上で認証する

VarnishAdmin::auth

(PECL varnish >= 0.3)

VarnishAdmin::auth — varnish インスタンス上で認証する

説明

public VarnishAdmin::auth(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


VCL の式を使って URL を禁止する

  • ≪ VarnishAdmin::auth
  • VarnishAdmin::banUrl ≫
  • PHP Manual
  • VarnishAdmin
  • VCL の式を使って URL を禁止する

VarnishAdmin::ban

(PECL varnish >= 0.3)

VarnishAdmin::ban — VCL の式を使って URL を禁止する

説明

public VarnishAdmin::ban(string $vcl_regex): int

パラメータ

vcl_regex

Varnish VCL の式。varnish の ban コマンドに基づくもの。

戻り値

varnish のコマンドステータスを返します。


VCL の式を使って URL を禁止する

  • ≪ VarnishAdmin::ban
  • VarnishAdmin::clearPanic ≫
  • PHP Manual
  • VarnishAdmin
  • VCL の式を使って URL を禁止する

VarnishAdmin::banUrl

(PECL varnish >= 0.3)

VarnishAdmin::banUrl — VCL の式を使って URL を禁止する

説明

public VarnishAdmin::banUrl(string $vcl_regex): int

パラメータ

vcl_regex

PCRE 互換形式で指定した、URL の正規表現。 varnish の ban.url コマンドに基づくもの。

戻り値

varnish のコマンドステータスを返します。


varnish インスタンスのパニックメッセージをクリアする

  • ≪ VarnishAdmin::banUrl
  • VarnishAdmin::connect ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスのパニックメッセージをクリアする

VarnishAdmin::clearPanic

(PECL varnish >= 0.4)

VarnishAdmin::clearPanic — varnish インスタンスのパニックメッセージをクリアする

説明

public VarnishAdmin::clearPanic(): int

パラメータ

この関数にはパラメータはありません。

戻り値

varnish のコマンドステータスを返します。


varnish インスタンスの管理インターフェイスに接続する

  • ≪ VarnishAdmin::clearPanic
  • VarnishAdmin::__construct ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスの管理インターフェイスに接続する

VarnishAdmin::connect

(PECL varnish >= 0.3)

VarnishAdmin::connect — varnish インスタンスの管理インターフェイスに接続する

説明

public VarnishAdmin::connect(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


VarnishAdmin のコンストラクタ

  • ≪ VarnishAdmin::connect
  • VarnishAdmin::disconnect ≫
  • PHP Manual
  • VarnishAdmin
  • VarnishAdmin のコンストラクタ

VarnishAdmin::__construct

(PECL varnish >= 0.3)

VarnishAdmin::__construct — VarnishAdmin のコンストラクタ

説明

public VarnishAdmin::__construct(array $args = ?)

パラメータ

args

設定用の引数。次のキーが使えます。

VARNISH_CONFIG_IDENT - ローカル varnish インスタンスの ident パス。
VARNISH_CONFIG_HOST - varnish インスタンスの IP アドレス。
VARNISH_CONFIG_PORT - varnish インスタンスのポート。
VARNISH_CONFIG_SECRET - varnish インスタンスの secret。
VARNISH_CONFIG_TIMEOUT - 接続の読み取りタイムアウト。
VARNISH_CONFIG_COMPAT - varnish メジャーバージョンの互換性。

戻り値

例

例1 VarnishAdmin::__construct() の例

<?php
$args = array(
VARNISH_CONFIG_HOST => "::1",
VARNISH_CONFIG_PORT => 6082,
VARNISH_CONFIG_SECRET => "5174826b-8595-4958-aa7a-0609632ad7ca",
VARNISH_CONFIG_TIMEOUT => 300,
);
$va = new VarnishAdmin($args);
?>


varnish インスタンスの管理インターフェイスとの接続を切断する

  • ≪ VarnishAdmin::__construct
  • VarnishAdmin::getPanic ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスの管理インターフェイスとの接続を切断する

VarnishAdmin::disconnect

(PECL varnish >= 1.0.0)

VarnishAdmin::disconnect — varnish インスタンスの管理インターフェイスとの接続を切断する

説明

public VarnishAdmin::disconnect(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


varnish インスタンスの直近のパニックメッセージを取得する

  • ≪ VarnishAdmin::disconnect
  • VarnishAdmin::getParams ≫
  • PHP Manual
  • VarnishAdmin
  • varnish インスタンスの直近のパニックメッセージを取得する

VarnishAdmin::getPanic

(PECL varnish >= 0.4)

VarnishAdmin::getPanic — varnish インスタンスの直近のパニックメッセージを取得する

説明

public VarnishAdmin::getPanic(): string

パラメータ

この関数にはパラメータはありません。

戻り値

現在の varnish インスタンスの直近のパニックメッセージを返します。


現在の varnish インスタンスの設定パラメータを取得する

  • ≪ VarnishAdmin::getPanic
  • VarnishAdmin::isRunning ≫
  • PHP Manual
  • VarnishAdmin
  • 現在の varnish インスタンスの設定パラメータを取得する

VarnishAdmin::getParams

(PECL varnish >= 0.4)

VarnishAdmin::getParams — 現在の varnish インスタンスの設定パラメータを取得する

説明

public VarnishAdmin::getParams(): array

パラメータ

この関数にはパラメータはありません。

戻り値

varnish 設定パラメータの配列を返します。


varnish のスレーブプロセスが現在実行中かどうかを調べる

  • ≪ VarnishAdmin::getParams
  • VarnishAdmin::setCompat ≫
  • PHP Manual
  • VarnishAdmin
  • varnish のスレーブプロセスが現在実行中かどうかを調べる

VarnishAdmin::isRunning

(PECL varnish >= 0.3)

VarnishAdmin::isRunning — varnish のスレーブプロセスが現在実行中かどうかを調べる

説明

public VarnishAdmin::isRunning(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


クラスのオプション compat を設定する

  • ≪ VarnishAdmin::isRunning
  • VarnishAdmin::setHost ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション compat を設定する

VarnishAdmin::setCompat

(PECL varnish >= 0.9.2)

VarnishAdmin::setCompat — クラスのオプション compat を設定する

説明

public VarnishAdmin::setCompat(int $compat): void

パラメータ

compat

Varnish の compat オプション。

戻り値


クラスのオプション host を設定する

  • ≪ VarnishAdmin::setCompat
  • VarnishAdmin::setIdent ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション host を設定する

VarnishAdmin::setHost

(PECL varnish >= 0.8)

VarnishAdmin::setHost — クラスのオプション host を設定する

説明

public VarnishAdmin::setHost(string $host): void

パラメータ

host

接続の host パラメータ。

戻り値


クラスのオプション ident を設定する

  • ≪ VarnishAdmin::setHost
  • VarnishAdmin::setParam ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション ident を設定する

VarnishAdmin::setIdent

(PECL varnish >= 0.8)

VarnishAdmin::setIdent — クラスのオプション ident を設定する

説明

public VarnishAdmin::setIdent(string $ident): void

パラメータ

ident

接続の ident パラメータ。

戻り値


現在の varnish インスタンスの構成パラメータを設定する

  • ≪ VarnishAdmin::setIdent
  • VarnishAdmin::setPort ≫
  • PHP Manual
  • VarnishAdmin
  • 現在の varnish インスタンスの構成パラメータを設定する

VarnishAdmin::setParam

(PECL varnish >= 0.4)

VarnishAdmin::setParam — 現在の varnish インスタンスの構成パラメータを設定する

説明

public VarnishAdmin::setParam(string $name, string|int $value): int

パラメータ

name

Varnish のパラメータ名。

value

Varnish のパラメータの値。

戻り値

varnish のコマンドステータスを返します。


クラスのオプション port を設定する

  • ≪ VarnishAdmin::setParam
  • VarnishAdmin::setSecret ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション port を設定する

VarnishAdmin::setPort

(PECL varnish >= 0.8)

VarnishAdmin::setPort — クラスのオプション port を設定する

説明

public VarnishAdmin::setPort(int $port): void

パラメータ

port

接続の port パラメータ。

戻り値


クラスのオプション secret を設定する

  • ≪ VarnishAdmin::setPort
  • VarnishAdmin::setTimeout ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション secret を設定する

VarnishAdmin::setSecret

(PECL varnish >= 0.8)

VarnishAdmin::setSecret — クラスのオプション secret を設定する

説明

public VarnishAdmin::setSecret(string $secret): void

パラメータ

secret

接続の secret パラメータ。

戻り値


クラスのオプション timeout を設定する

  • ≪ VarnishAdmin::setSecret
  • VarnishAdmin::start ≫
  • PHP Manual
  • VarnishAdmin
  • クラスのオプション timeout を設定する

VarnishAdmin::setTimeout

(PECL varnish >= 0.8)

VarnishAdmin::setTimeout — クラスのオプション timeout を設定する

説明

public VarnishAdmin::setTimeout(int $timeout): void

パラメータ

timeout

接続の timeout パラメータ。

戻り値


varnish ワーカープロセスを開始する

  • ≪ VarnishAdmin::setTimeout
  • VarnishAdmin::stop ≫
  • PHP Manual
  • VarnishAdmin
  • varnish ワーカープロセスを開始する

VarnishAdmin::start

(PECL varnish >= 0.3)

VarnishAdmin::start — varnish ワーカープロセスを開始する

説明

public VarnishAdmin::start(): int

パラメータ

この関数にはパラメータはありません。

戻り値

varnish のコマンドステータスを返します。


varnish ワーカープロセスを停止する

  • ≪ VarnishAdmin::start
  • VarnishStat ≫
  • PHP Manual
  • VarnishAdmin
  • varnish ワーカープロセスを停止する

VarnishAdmin::stop

(PECL varnish >= 0.3)

VarnishAdmin::stop — varnish ワーカープロセスを停止する

説明

public VarnishAdmin::stop(): int

パラメータ

この関数にはパラメータはありません。

戻り値

varnish のコマンドステータスを返します。


VarnishStat クラス

(PECL varnish >= 0.3)

はじめに

クラス概要

class VarnishStat {
/* メソッド */
public __construct(array $args = ?)
public getSnapshot(): array
}

目次

  • VarnishStat::__construct — VarnishStat のコンストラクタ
  • VarnishStat::getSnapshot — 現在の varnish インスタンスの統計スナップショットを取得する


VarnishStat のコンストラクタ

  • ≪ VarnishStat
  • VarnishStat::getSnapshot ≫
  • PHP Manual
  • VarnishStat
  • VarnishStat のコンストラクタ

VarnishStat::__construct

(PECL varnish >= 0.3)

VarnishStat::__construct — VarnishStat のコンストラクタ

説明

public VarnishStat::__construct(array $args = ?)

パラメータ

args

設定用の引数。次のキーが使えます。

VARNISH_CONFIG_IDENT - ローカル varnish インスタンスの ident パス。

戻り値


現在の varnish インスタンスの統計スナップショットを取得する

  • ≪ VarnishStat::__construct
  • VarnishLog ≫
  • PHP Manual
  • VarnishStat
  • 現在の varnish インスタンスの統計スナップショットを取得する

VarnishStat::getSnapshot

(PECL varnish >= 0.3)

VarnishStat::getSnapshot — 現在の varnish インスタンスの統計スナップショットを取得する

説明

public VarnishStat::getSnapshot(): array

パラメータ

この関数にはパラメータはありません。

戻り値

varnish 統計のスナップショットを配列で返します。 配列のキーは varnishstat ツールと同じです。


VarnishLog クラス

(PECL varnish >= 0.6)

はじめに

クラス概要

class VarnishLog {
/* 定数 */
const int TAG_Debug = 0;
const int TAG_Error = 1;
const int TAG_CLI = 2;
const int TAG_StatSess = 3;
const int TAG_ReqEnd = 4;
const int TAG_SessionOpen = 5;
const int TAG_SessionClose = 6;
const int TAG_BackendOpen = 7;
const int TAG_BackendXID = 8;
const int TAG_BackendReuse = 9;
const int TAG_BackendClose = 10;
const int TAG_HttpGarbage = 11;
const int TAG_Backend = 12;
const int TAG_Length = 13;
const int TAG_FetchError = 14;
const int TAG_RxRequest = 15;
const int TAG_RxResponse = 16;
const int TAG_RxStatus = 17;
const int TAG_RxURL = 18;
const int TAG_RxProtocol = 19;
const int TAG_RxHeader = 20;
const int TAG_TxRequest = 21;
const int TAG_TxResponse = 22;
const int TAG_TxStatus = 23;
const int TAG_TxURL = 24;
const int TAG_TxProtocol = 25;
const int TAG_TxHeader = 26;
const int TAG_ObjRequest = 27;
const int TAG_ObjResponse = 28;
const int TAG_ObjStatus = 29;
const int TAG_ObjURL = 30;
const int TAG_ObjProtocol = 31;
const int TAG_ObjHeader = 32;
const int TAG_LostHeader = 33;
const int TAG_TTL = 34;
const int TAG_Fetch_Body = 35;
const int TAG_VCL_acl = 36;
const int TAG_VCL_call = 37;
const int TAG_VCL_trace = 38;
const int TAG_VCL_return = 39;
const int TAG_VCL_error = 40;
const int TAG_ReqStart = 41;
const int TAG_Hit = 42;
const int TAG_HitPass = 43;
const int TAG_ExpBan = 44;
const int TAG_ExpKill = 45;
const int TAG_WorkThread = 46;
const int TAG_ESI_xmlerror = 47;
const int TAG_Hash = 48;
const int TAG_Backend_health = 49;
const int TAG_VCL_Log = 50;
const int TAG_Gzip = 51;
/* メソッド */
public __construct(array $args = ?)
public getLine(): array
public static getTagName(int $index): string
}

定義済み定数

VarnishLog::TAG_Debug

VarnishLog::TAG_Error

VarnishLog::TAG_CLI

VarnishLog::TAG_StatSess

VarnishLog::TAG_ReqEnd

VarnishLog::TAG_SessionOpen

VarnishLog::TAG_SessionClose

VarnishLog::TAG_BackendOpen

VarnishLog::TAG_BackendXID

VarnishLog::TAG_BackendReuse

VarnishLog::TAG_BackendClose

VarnishLog::TAG_HttpGarbage

VarnishLog::TAG_Backend

VarnishLog::TAG_Length

VarnishLog::TAG_FetchError

VarnishLog::TAG_RxRequest

VarnishLog::TAG_RxResponse

VarnishLog::TAG_RxStatus

VarnishLog::TAG_RxURL

VarnishLog::TAG_RxProtocol

VarnishLog::TAG_RxHeader

VarnishLog::TAG_TxRequest

VarnishLog::TAG_TxResponse

VarnishLog::TAG_TxStatus

VarnishLog::TAG_TxURL

VarnishLog::TAG_TxProtocol

VarnishLog::TAG_TxHeader

VarnishLog::TAG_ObjRequest

VarnishLog::TAG_ObjResponse

VarnishLog::TAG_ObjStatus

VarnishLog::TAG_ObjURL

VarnishLog::TAG_ObjProtocol

VarnishLog::TAG_ObjHeader

VarnishLog::TAG_LostHeader

VarnishLog::TAG_TTL

VarnishLog::TAG_Fetch_Body

VarnishLog::TAG_VCL_acl

VarnishLog::TAG_VCL_call

VarnishLog::TAG_VCL_trace

VarnishLog::TAG_VCL_return

VarnishLog::TAG_VCL_error

VarnishLog::TAG_ReqStart

VarnishLog::TAG_Hit

VarnishLog::TAG_HitPass

VarnishLog::TAG_ExpBan

VarnishLog::TAG_ExpKill

VarnishLog::TAG_WorkThread

VarnishLog::TAG_ESI_xmlerror

VarnishLog::TAG_Hash

VarnishLog::TAG_Backend_health

VarnishLog::TAG_VCL_Log

VarnishLog::TAG_Gzip

目次

  • VarnishLog::__construct — Varnishlog のコンストラクタ
  • VarnishLog::getLine — ログの次の行を取得する
  • VarnishLog::getTagName — ログのタグ文字列を、インデックスから取得する


Varnishlog のコンストラクタ

  • ≪ VarnishLog
  • VarnishLog::getLine ≫
  • PHP Manual
  • VarnishLog
  • Varnishlog のコンストラクタ

VarnishLog::__construct

(PECL varnish >= 0.6)

VarnishLog::__construct — Varnishlog のコンストラクタ

説明

public VarnishLog::__construct(array $args = ?)

パラメータ

args

設定用の引数。次のキーが使えます。

VARNISH_CONFIG_IDENT - ローカル varnish インスタンスの ident パス。

戻り値


ログの次の行を取得する

  • ≪ VarnishLog::__construct
  • VarnishLog::getTagName ≫
  • PHP Manual
  • VarnishLog
  • ログの次の行を取得する

VarnishLog::getLine

(PECL varnish >= 0.6)

VarnishLog::getLine — ログの次の行を取得する

説明

public VarnishLog::getLine(): array

パラメータ

この関数にはパラメータはありません。

戻り値

ログの行のデータを配列で返します。


ログのタグ文字列を、インデックスから取得する

  • ≪ VarnishLog::getLine
  • YAZ ≫
  • PHP Manual
  • VarnishLog
  • ログのタグ文字列を、インデックスから取得する

VarnishLog::getTagName

(PECL varnish >= 0.6)

VarnishLog::getTagName — ログのタグ文字列を、インデックスから取得する

説明

public static VarnishLog::getTagName(int $index): string

パラメータ

index

ログのタグのインデックス。

戻り値

ログのタグ名を文字列で返します。


YAZ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 例
  • YAZ 関数
    • yaz_addinfo — 詳細なエラー情報を返す
    • yaz_ccl_conf — CCL パーサを設定する
    • yaz_ccl_parse — CCL パーサを起動する
    • yaz_close — YAZ 接続をクローズする
    • yaz_connect — Z39.50 サーバーへの接続を準備する
    • yaz_database — セッション内のデータベースを指定する
    • yaz_element — 取得時の要素集合の名前を指定する
    • yaz_errno — エラー番号を返す
    • yaz_error — エラーの内容を返す
    • yaz_es — 拡張サービスのリクエストを準備する
    • yaz_es_result — 拡張サービスの結果を調査する
    • yaz_get_option — 接続に関するオプションの値を返す
    • yaz_hits — 直近の検索に関するヒット数を返す
    • yaz_itemorder — ILL リクエストパッケージを関して Z39.50 Item Order を準備する
    • yaz_present — (Z39.50による)取得の準備を行う
    • yaz_range — 取得するレコードの範囲を指定する
    • yaz_record — レコードを返す
    • yaz_scan — スキャンの準備をする
    • yaz_scan_result — スキャンリクエストの結果を返す
    • yaz_schema — 取得するスキーマを指定する
    • yaz_search — 検索を準備する
    • yaz_set_option — 接続に関するひとつあるいは複数のオプションを設定する
    • yaz_sort — ソート条件を設定する
    • yaz_syntax — 取得用に適当なレコード構文を指定する
    • yaz_wait — Z39.50 リクエストが完了するまで待つ


はじめに

この拡張モジュールは、» 情報取得用の Z39.50 プロトコル を実装する YAZ ツールキットへの PHP インターフェイスを 提供するものです。この拡張モジュールにより、Z39.50 ターゲット（サーバー） を並列に検索またはスキャンする Z39.50 オリジン（クライアント）を 容易に実装することが可能になります。

このモジュールは Z39.50 の複雑さを隠蔽するため、使用法がかなり容易になります。 PHP で利用可能な様々な RDB の API により提供されているものに非常によく似た、 ステートレスな持続的接続がサポートされています。 これは、セッションはステートレスですが、ユーザー間で共有されるということを意味します。 これにより多くの場合に接続および初期化手順が保存されます。

YAZ は、» http://www.indexdata.dk/yaz/ で取得可能です。 この拡張モジュールに関する新しい情報、スクリプトの例等を » http://www.indexdata.dk/phpyaz/ にて参照可能です。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.0.0.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • YAZ
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

YAZ (ANSI/NISO Z39.50 サポート) をインストールします。 YAZ のソースやさまざまなビルド済みパッケージは » YAZ archive から取得できます。 Debian GNU/Linux や Suse Linux、FreeBSD といったシステムには、 ディストリビューションの一部として YAZ が含まれています。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yaz

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

注意: Windows ユーザーへの情報

php_yaz.dll は yaz.dll に依存しています。yaz.dll は、PHP のサイトから取得できる Win32 版の ZIP に含まれています。 また、 » YAZ WIN32 area にある Windows 版の YAZ の中にも含まれています。

Windows では、PHP のディレクトリを PATH に追加することを忘れないようにしましょう。 そうすれば、yaz.dll がシステムから見つけられるようになります。

警告

IMAP、recode、 YAZ 拡張モジュールは、組み合わせて使用することはできません。 これは、これらすべてが同一の内部シンボルを使用しているためです。 注意: Yaz 2.0 以降ではこの問題は発生しません。


  • ≪ インストール手順
  • 例 ≫
  • PHP Manual
  • インストール/設定
  • 実行時設定

実行時設定

設定ディレクティブは定義されていません。


例

PHP/YAZ はターゲット(Z-Associations)との接続を保持し続けます。 正の整数で特定の接続のIDを表します。

以下のスクリプトは、API の並列検索機能のデモです。引数を指定せずにコールした場合、 この関数はクエリフォームを出力します。そうでない場合 （引数を指定した場合）は、配列 host にあるターゲットを検索します。

例1 YAZ による並列検索

<?php
$host=$_REQUEST[host];
$query=$_REQUEST[query];
$num_hosts = count($host);
if (empty($query) || count($host) == 0) {
echo '<form method="get">
<input type="checkbox"
name="host[]" value="bagel.indexdata.dk/gils" />
GILS test
<input type="checkbox"
name="host[]" value="localhost:9999/Default" />
local test
<input type="checkbox" checked="checked"
name="host[]" value="z3950.loc.gov:7090/voyager" />
Library of Congress
<br />
RPN Query:
<input type="text" size="30" name="query" />
<input type="submit" name="action" value="Search" />
</form>
';
} else {
echo 'You searched for ' . htmlspecialchars($query) . '<br />';
for ($i = 0; $i < $num_hosts; $i++) {
$id[] = yaz_connect($host[$i]);
yaz_syntax($id[$i], "usmarc");
yaz_range($id[$i], 1, 10);
yaz_search($id[$i], "rpn", $query);
}
yaz_wait();
for ($i = 0; $i < $num_hosts; $i++) {
echo '<hr />' . $host[$i] . ':';
$error = yaz_error($id[$i]);
if (!empty($error)) {
echo "Error: $error";
} else {
$hits = yaz_hits($id[$i]);
echo "Result Count $hits";
}
echo '<dl>';
for ($p = 1; $p <= 10; $p++) {
$rec = yaz_record($id[$i], $p, "string");
if (empty($rec)) continue;
echo "<dt><b>$p</b></dt><dd>";
echo nl2br($rec);
echo "</dd>";
}
echo '</dl>';
}
}
?>


YAZ 関数

目次

  • yaz_addinfo — 詳細なエラー情報を返す
  • yaz_ccl_conf — CCL パーサを設定する
  • yaz_ccl_parse — CCL パーサを起動する
  • yaz_close — YAZ 接続をクローズする
  • yaz_connect — Z39.50 サーバーへの接続を準備する
  • yaz_database — セッション内のデータベースを指定する
  • yaz_element — 取得時の要素集合の名前を指定する
  • yaz_errno — エラー番号を返す
  • yaz_error — エラーの内容を返す
  • yaz_es — 拡張サービスのリクエストを準備する
  • yaz_es_result — 拡張サービスの結果を調査する
  • yaz_get_option — 接続に関するオプションの値を返す
  • yaz_hits — 直近の検索に関するヒット数を返す
  • yaz_itemorder — ILL リクエストパッケージを関して Z39.50 Item Order を準備する
  • yaz_present — (Z39.50による)取得の準備を行う
  • yaz_range — 取得するレコードの範囲を指定する
  • yaz_record — レコードを返す
  • yaz_scan — スキャンの準備をする
  • yaz_scan_result — スキャンリクエストの結果を返す
  • yaz_schema — 取得するスキーマを指定する
  • yaz_search — 検索を準備する
  • yaz_set_option — 接続に関するひとつあるいは複数のオプションを設定する
  • yaz_sort — ソート条件を設定する
  • yaz_syntax — 取得用に適当なレコード構文を指定する
  • yaz_wait — Z39.50 リクエストが完了するまで待つ


詳細なエラー情報を返す

  • ≪ YAZ 関数
  • yaz_ccl_conf ≫
  • PHP Manual
  • YAZ 関数
  • 詳細なエラー情報を返す

yaz_addinfo

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_addinfo — 詳細なエラー情報を返す

説明

yaz_addinfo(resource $id): string

サーバー上での直近のリクエストに関する詳細なエラーメッセージを返します。

サーバーによっては、この関数は yaz_error() と同じ 文字列を返すことがあります。

パラメータ

id

yaz_connect() が返す接続リソース。

戻り値

エラーの詳細情報を文字列で返します。直近の処理が成功したか、あるいは サーバーから詳細な情報が提供されていない場合には、空の文字列を返します。

参考

  • yaz_error() - エラーの内容を返す
  • yaz_errno() - エラー番号を返す


CCL パーサを設定する

  • ≪ yaz_addinfo
  • yaz_ccl_parse ≫
  • PHP Manual
  • YAZ 関数
  • CCL パーサを設定する

yaz_ccl_conf

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_ccl_conf — CCL パーサを設定する

説明

yaz_ccl_conf(resource $id, array $config): void

この関数は、アクセスポイント(CCL限定辞)が定義するサーバーに関して CCL クエリパーサと RPN へのマッピングを設定します。

特定の CCL クエリを後で RPN にマップするには、 yaz_ccl_parse() 関数をコールしてください。

パラメータ

id

yaz_connect() が返す接続リソース。

config

設定の配列。配列の各キーが CCL フィールドの名前で、対応する値は RPN へのマッピングを指定する文字列です。

マッピングは、属性型と属性値の組が並んだものです。 属性型と属性値は、等号（=）で区切られ、 組と組の間は空白で区切られます。

詳細な情報は » CCL のページを 参照ください。

戻り値

値を返しません。

例

以下の例では、CCL パーサは ti、 au、isbn という 3 つの CCL フィールドをサポートするように設定されます。各フィールドは、等価な BIB-1 へマップされます。 この例では、$id が接続 ID であることを仮定しています。

例1 CCL 設定

<?php
$fields = array(
"ti" => "1=4",
"au" => "1=1",
"isbn" => "1=7"
);
yaz_ccl_conf($id, $fields);
?>

参考

  • yaz_ccl_parse() - CCL パーサを起動する


CCL パーサを起動する

  • ≪ yaz_ccl_conf
  • yaz_close ≫
  • PHP Manual
  • YAZ 関数
  • CCL パーサを起動する

yaz_ccl_parse

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_ccl_parse — CCL パーサを起動する

説明

yaz_ccl_parse(resource $id, string $query, array &$result): bool

この関数は、CCL パーサを起動します。パーサは、指定された CCL FIND クエリを RPN クエリに変換します。これは検索を実行する yaz_search() 関数に渡すためのものです。

有効な CCL フィールドの組を定義するには、この関数の前に yaz_ccl_conf() をコールします。

パラメータ

id

yaz_connect() が返す接続リソース。

query

CCL FIND クエリ。

result

関数が成功した場合、キー rpn に有効な RPN クエリを含む配列となります。

失敗した場合は、以下の 3 つの添え字を含む配列となり、失敗の原因を示します。

  • errorcode - CCL エラーコード（整数）

  • errorstring - CCL エラー文字列

  • errorpos - クエリが失敗したおおよその位置 （文字の位置を整数で表す）

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 CCL のパース

CCL を利用して検索します。以下の例で、$ccl は CCL クエリです。

<?php

yaz_ccl_conf($id, $fields); // yaz_ccl_conf のサンプルを参照ください
if (!yaz_ccl_parse($id, $ccl, &$cclresult)) {
echo 'Error: ' . $cclresult["errorstring"];
} else {
$rpn = $cclresult["rpn"];
yaz_search($id, "rpn", $rpn);
}
?>


YAZ 接続をクローズする

  • ≪ yaz_ccl_parse
  • yaz_connect ≫
  • PHP Manual
  • YAZ 関数
  • YAZ 接続をクローズする

yaz_close

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_close — YAZ 接続をクローズする

説明

yaz_close(resource $id): bool

id で指定した接続をクローズします。

注意:

この関数は、persistent オプションを false にして yaz_connect() でオープンした 持続的でない接続のみをクローズします。

パラメータ

id

yaz_connect() が返す接続リソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • yaz_connect() - Z39.50 サーバーへの接続を準備する


Z39.50 サーバーへの接続を準備する

  • ≪ yaz_close
  • yaz_database ≫
  • PHP Manual
  • YAZ 関数
  • Z39.50 サーバーへの接続を準備する

yaz_connect

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_connect — Z39.50 サーバーへの接続を準備する

説明

yaz_connect(string $zurl, mixed $options = ?): mixed

この関数は、成功した場合に接続リソース、失敗した場合にゼロを返します。

yaz_connect() は Z39.50 サーバーへの接続を準備します。 この関数は非ブロックモードで動作し、接続を確立しようとしません - 単にあとで yaz_wait() がコールされた際に 接続を実行する準備を行うだけです。

注意:

» YAZ プロキシ は、フリーで使用可能な Z39.50 のプロキシです。

パラメータ

zurl

host[:port][/database] という形式の文字列です。 port が省略された場合、210 が使用されます。database が省略された 場合、Default が使用されます。

options

文字列が指定された場合、 Z39.50 V2 認証文字列(OpenAuth)として処理されます。

配列が指定された場合、その配列の内容はオプションとして処理されます。

user

認証用のユーザー名

group

認証用のグループ

password

認証用のパスワード

cookie

セッションクッキー（YAZ プロキシ）

proxy

接続用プロキシ（YAZ プロキシ）

persistent

論理値。true の場合、接続は持続的となります。false の 場合、接続は持続的ではありません。デフォルトでは 接続は持続的です。

注意:

持続的な接続をオープンした場合、後でそれを yaz_close() によってクローズすることは できません。

piggyback

論理値。true の場合、検索時の piggyback が有効になります。 false の場合、piggyback が無効になります。デフォルトでは piggyback は有効です。

piggyback を有効にするとより効率的となり、 通常、レコードを最初に取得する際のネットワーク往復時間を 節約することが可能です。しかし、少数の Z39.50 ターゲットは piggyback をサポートしていないか、エレメント集合名を無視します。 この場合、piggyback を無効とする必要があります。

charset

Z39.50 の言語および文字セットネゴシエーションに使用する 文字セットを指定する文字列。以下のような文字列を使用します。 ISO-8859-1、UTF-8、 UTF-16 。

ほとんどの Z39.50 サーバーはこの機能をサポートしません（そのため、 無視されます）。ほとんどのサーバーは、クエリやメッセージに ISO-8859-1 エンコーディングを使用します。MARC21/USMARC レコードは この設定の影響を受けません。

preferredMessageSize

ターゲットから取得される全レコードの最大バイト数を指定する整数値。 詳細な情報は » Z39.50 standard を参照ください。

注意:

このオプションは PECL YAZ 1.0.5 以降でサポートされます。

maximumRecordSize

ターゲットから取得される単一のレコードの最大バイト数を指定する 整数値。この項目は、 » Z39.50 standard の Exceptional-record-size として参照されます。

注意:

このオプションは PECL YAZ 1.0.5 以降でサポートされます。

戻り値

成功した場合に接続リソース、エラー時に false を返します。

変更履歴

バージョン | 説明
4.1.0 | options が追加されました。

参考

  • yaz_close() - YAZ 接続をクローズする


セッション内のデータベースを指定する

  • ≪ yaz_connect
  • yaz_element ≫
  • PHP Manual
  • YAZ 関数
  • セッション内のデータベースを指定する

yaz_database

(PHP 4 >= 4.0.6, PECL yaz >= 0.9.0)

yaz_database — セッション内のデータベースを指定する

説明

yaz_database(resource $id, string $databases): bool

この関数は、検索、取得等で使用する１つまたは複数のデータベースを指定します。 yaz_connect() をコールする際に指定したデータベースを上書きします。

パラメータ

id

yaz_connect() が返す接続リソース。

databases

ひとつあるいは複数のデータベースを表す文字列。複数のデータベースは、可算記号 + で区切ります。

戻り値

成功した場合に true を、失敗した場合に false を返します。


取得時の要素集合の名前を指定する

  • ≪ yaz_database
  • yaz_errno ≫
  • PHP Manual
  • YAZ 関数
  • 取得時の要素集合の名前を指定する

yaz_element

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_element — 取得時の要素集合の名前を指定する

説明

yaz_element(resource $id, string $elementset): bool

この関数は、取得時の要素集合の名前を指定します。

この関数は、yaz_search() あるいは yaz_present() をコールする前に、 取得するレコードの要素集合の名前を指定するために使用します。

注意:

この関数が動作していないように見える場合は、 yaz_connect() の piggybacking オプションについての説明を 参照ください。

パラメータ

id

yaz_connect() が返す接続リソース。

elementset

ほとんどのサーバーは、 F（完全版）および B（短縮版） をサポートします。

戻り値

成功した場合に true を、失敗した場合に false を返します。


エラー番号を返す

  • ≪ yaz_element
  • yaz_error ≫
  • PHP Manual
  • YAZ 関数
  • エラー番号を返す

yaz_errno

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_errno — エラー番号を返す

説明

yaz_errno(resource $id): int

id で表される サーバーの（直近のリクエストについての）エラー番号を返します。

yaz_errno() は、各ターゲットへのネットワーク接続が 確立された後(つまり、yaz_wait()の後)に コールされる必要があり、直近の操作(例えば検索)が成功したか 失敗したかを判定します。

パラメータ

id

yaz_connect() が返す接続リソース。

戻り値

エラーコードを返します。エラーコードは Z39.50 診断コード （通常は Bib-1 診断）あるいは PHP/YAZ が生成するクライアント側の エラーコード（たとえば "Connect failed"、"Init Rejected" など） のいずれかです。

参考

  • yaz_error() - エラーの内容を返す
  • yaz_addinfo() - 詳細なエラー情報を返す


エラーの内容を返す

  • ≪ yaz_errno
  • yaz_es ≫
  • PHP Manual
  • YAZ 関数
  • エラーの内容を返す

yaz_error

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_error — エラーの内容を返す

説明

yaz_error(resource $id): string

yaz_error() は、yaz_errno() で返された直近のエラー番号に対応する英語のメッセージを返します。

パラメータ

id

yaz_connect() が返す接続リソース。

戻り値

id で表される(直近のリクエストの) サーバーに関するエラーメッセージを返します。 直近の操作が成功した場合には空の文字列が返されます。

参考

  • yaz_errno() - エラー番号を返す
  • yaz_addinfo() - 詳細なエラー情報を返す


拡張サービスのリクエストを準備する

  • ≪ yaz_error
  • yaz_es_result ≫
  • PHP Manual
  • YAZ 関数
  • 拡張サービスのリクエストを準備する

yaz_es

(PECL yaz >= 0.9.0)

yaz_es — 拡張サービスのリクエストを準備する

説明

yaz_es( resource $id , string $type , array $args ): void

この関数は、拡張サービスのリクエストを準備します。 拡張サービスとは、レコードの更新や蔵書の注文、データベースの管理などの Z39.50 のさまざまな機能のことです。

注意:

Z39.50 サーバーの多くは、拡張サービスをサポートしていません。

yaz_es() は、拡張サービスリクエストのパッケージを作成し、
それを操作キューに配置します。リクエストをサーバーに送信するには
yaz_wait() を使用します。
yaz_wait() の処理が完了すると、拡張サービス操作の結果が
yaz_es_result() で取得できるようになります。

パラメータ

id

yaz_connect() が返す接続リソース。

type

拡張サービスの形式を表す文字列。 itemorder (蔵書の注文)、 create (データベースの作成)、 drop (データベースの削除)、 commit (操作のコミット)、 update (レコードの更新)、 xmlupdate (XMLの更新) のいずれかです。 個々の形式については、以下の節で指定されます。

args

拡張サービスのオプションに加えてパッケージ固有のオプションを指定する配列。 オプションの形式は、ZOOM C の C API で提供されているものと同じです。 ZOOM » Extended Services を参照ください。

戻り値

値を返しません。

例

例1 レコードの更新

<?php
$con = yaz_connect("myhost/database");
$args = array (
"record" => "<gils><title>some title</title></gils>",
"syntax" => "xml",
"action" => "specialUpdate"
);
yaz_es($con, "update", $args);
yaz_wait();
$result = yaz_es_result($id);
?>

参考

  • yaz_es_result() - 拡張サービスの結果を調査する


拡張サービスの結果を調査する

  • ≪ yaz_es
  • yaz_get_option ≫
  • PHP Manual
  • YAZ 関数
  • 拡張サービスの結果を調査する

yaz_es_result

(PHP 4 >= 4.2.0, PECL yaz >= 0.9.0)

yaz_es_result — 拡張サービスの結果を調査する

説明

yaz_es_result(resource $id): array

この関数は、サーバーから返された直近の拡張サービスの結果を調査します。 拡張サービスは、yaz_item_order() あるいは yaz_es() で起動します。

パラメータ

id

yaz_connect() が返す接続リソース。

戻り値

要素 targetReference を持つ配列を返します。 この要素には (サーバー側で生成して返された) 拡張サービス操作への参照が格納されます。

参考

  • yaz_es() - 拡張サービスのリクエストを準備する


接続に関するオプションの値を返す

  • ≪ yaz_es_result
  • yaz_hits ≫
  • PHP Manual
  • YAZ 関数
  • 接続に関するオプションの値を返す

yaz_get_option

(PECL yaz >= 0.9.0)

yaz_get_option — 接続に関するオプションの値を返す

説明

yaz_get_option(resource $id, string $name): string

name で指定したオプションの値を返します。

パラメータ

id

yaz_connect() が返す接続リソース。

name

オプションの名前。

戻り値

指定したオプションの値を返します。オプションが設定されていない場合は 空文字列を返します。

参考

  • 使用可能なオプションについては、yaz_set_option() - 接続に関するひとつあるいは複数のオプションを設定する を参照ください。


直近の検索に関するヒット数を返す

  • ≪ yaz_get_option
  • yaz_itemorder ≫
  • PHP Manual
  • YAZ 関数
  • 直近の検索に関するヒット数を返す

yaz_hits

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_hits — 直近の検索に関するヒット数を返す

説明

yaz_hits(resource $id, array &$searchresult = ?): int

yaz_hits() は、直近の検索に関するヒット数を返します。

パラメータ

id

yaz_connect() が返す接続リソース。

searchresult

詳細な検索結果情報の配列。

戻り値

直近の検索に関するヒット数を返します。検索が行われていない場合は 0 を返します。

検索結果配列がもし指定されていた場合、そこには Z39.50 サーバーが返す情報が 含まれます。この情報の形式は、検索結果の応答の一部である SearchResult-1 フォーマットとなります。 SearchResult-1 フォーマットは、さまざまなクエリ(サブクエリ)のヒット数に 関する情報を取得するために使用可能です。 特に、クエリ内の個々の検索語句に関するヒット数を得ることが可能です。 最初のサブクエリについての情報が $array[0] に、2 番目のサブクエリについての 情報が $array[1] に、というような形式となります。

検索結果の項目
要素 | 説明
id | サブクエリの ID2 (string)
count | 結果のカウント / ヒット数 (integer)
subquery.term | サブクエリの語句 (string)
interpretation.term | 解釈されたサブクエリの語句 (string)
recommendation.term | 推奨されるサブクエリの語句 (string)

注意:

SearchResult 機能を使用するには、PECL YAZ 1.0.5 以降 および YAZ 2.1.9 以降が必要です。

注意:

SearchResult 機能をサポートしている Z39.50 実装は ほとんどありません。


ILL リクエストパッケージを関して Z39.50 Item Order を準備する

  • ≪ yaz_hits
  • yaz_present ≫
  • PHP Manual
  • YAZ 関数
  • ILL リクエストパッケージを関して Z39.50 Item Order を準備する

yaz_itemorder

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_itemorder — ILL リクエストパッケージを関して Z39.50 Item Order を準備する

説明

yaz_itemorder(resource $id, array $args): void

この関数は、Transport ILL (Profile/1) への Z39.50 Item Order Extended Service 用のプロファイルを使用する Extended Services リクエストを準備します。 » このページ および » 仕様 を参照ください。

パラメータ

id

yaz_connect() が返す接続リソース。

args

送信する Item Order リクエストに関する情報を有するハッシュ配列とする必要があります。 このハッシュ配列のキーは、対応する ASN.1 タグのパス名です。たとえば、 Item-ID 以下に ISBN がある場合のキーは item-id,ISBN となります。

ILL-Request パラメータは次のようになります。

protocol-version-num
transaction-id,initial-requester-id,person-or-institution-symbol,person
transaction-id,initial-requester-id,person-or-institution-symbol,institution
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution
transaction-id,transaction-group-qualifier
transaction-id,transaction-qualifier
transaction-id,sub-transaction-qualifier
service-date-time,this,date
service-date-time,this,time
service-date-time,original,date
service-date-time,original,time
requester-id,person-or-institution-symbol,person
requester-id,person-or-institution-symbol,institution
requester-id,name-of-person-or-institution,name-of-person
requester-id,name-of-person-or-institution,name-of-institution
responder-id,person-or-institution-symbol,person
responder-id,person-or-institution-symbol,institution
responder-id,name-of-person-or-institution,name-of-person
responder-id,name-of-person-or-institution,name-of-institution
transaction-type
delivery-address,postal-address,name-of-person-or-institution,name-of-person
delivery-address,postal-address,name-of-person-or-institution,name-of-institution
delivery-address,postal-address,extended-postal-delivery-address
delivery-address,postal-address,street-and-number
delivery-address,postal-address,post-office-box
delivery-address,postal-address,city
delivery-address,postal-address,region
delivery-address,postal-address,country
delivery-address,postal-address,postal-code
delivery-address,electronic-address,telecom-service-identifier
delivery-address,electronic-address,telecom-service-addreess
billing-address,postal-address,name-of-person-or-institution,name-of-person
billing-address,postal-address,name-of-person-or-institution,name-of-institution
billing-address,postal-address,extended-postal-delivery-address
billing-address,postal-address,street-and-number
billing-address,postal-address,post-office-box
billing-address,postal-address,city
billing-address,postal-address,region
billing-address,postal-address,country
billing-address,postal-address,postal-code
billing-address,electronic-address,telecom-service-identifier
billing-address,electronic-address,telecom-service-addreess
ill-service-type
requester-optional-messages,can-send-RECEIVED
requester-optional-messages,can-send-RETURNED
requester-optional-messages,requester-SHIPPED
requester-optional-messages,requester-CHECKED-IN
search-type,level-of-service
search-type,need-before-date
search-type,expiry-date
search-type,expiry-flag
place-on-hold
client-id,client-name
client-id,client-status
client-id,client-identifier
item-id,item-type
item-id,call-number
item-id,author
item-id,title
item-id,sub-title
item-id,sponsoring-body
item-id,place-of-publication
item-id,publisher
item-id,series-title-number
item-id,volume-issue
item-id,edition
item-id,publication-date
item-id,publication-date-of-component
item-id,author-of-article
item-id,title-of-article
item-id,pagination
item-id,ISBN
item-id,ISSN
item-id,additional-no-letters
item-id,verification-reference-source
copyright-complicance
retry-flag
forward-flag
requester-note
forward-note

Extended Services Request パッケージおよび ItemOrder パッケージにも 次のようないくつかのパラメータがあります。

package-name
user-id
contact-name
contact-phone
contact-email
itemorder-item

戻り値

値を返しません。


(Z39.50による)取得の準備を行う

  • ≪ yaz_itemorder
  • yaz_range ≫
  • PHP Manual
  • YAZ 関数
  • (Z39.50による)取得の準備を行う

yaz_present

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_present — (Z39.50による)取得の準備を行う

説明

yaz_present(resource $id): bool

この関数は、検索に成功した後でレコードを取得するための準備を行います。

この関数をコールする前に、取得するレコードの範囲を指定するために まず yaz_range() をコールしておく必要があります。

パラメータ

id

yaz_connect() が返す接続リソース。

戻り値

成功した場合に true を、失敗した場合に false を返します。


取得するレコードの範囲を指定する

  • ≪ yaz_present
  • yaz_record ≫
  • PHP Manual
  • YAZ 関数
  • 取得するレコードの範囲を指定する

yaz_range

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_range — 取得するレコードの範囲を指定する

説明

yaz_range(resource $id, int $start, int $number): void

取得するレコードの範囲を指定します。

この関数は、yaz_search() あるいは yaz_present() の前にコールしなければなりません。

パラメータ

id

yaz_connect() が返す接続リソース。

start

取得する最初のレコードの位置を指定します。レコード番号は 1 から yaz_hits() までです。

number

取得するレコードの数を指定します。

戻り値

値を返しません。


レコードを返す

  • ≪ yaz_range
  • yaz_scan ≫
  • PHP Manual
  • YAZ 関数
  • レコードを返す

yaz_record

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_record — レコードを返す

説明

yaz_record(resource $id, int $pos, string $type): string

yaz_record() 関数は、現在の結果セットの pos で指定した位置にあるレコードを調べます。

パラメータ

id

yaz_connect() が返す接続リソース。

pos

レコードの位置。結果セット内の位置は 1, 2, ... $hits で表されます。 ここで、$hits は yaz_hits() が返す値です。

type

type は、返されるレコードの型を指定します。

注意:

Z39.50/SRW サーバーから適切な形式でレコードが返されたことを 確認するのは、アプリケーション側の役目です。このパラメータは 単にクライアント側（PHP/YAZ 内）での型変換についてのみ設定します。

レコードを文字列/配列に変換することに加え、PHP/YAZ はレコードの 文字セットを変換することも可能です。 特に USMARC/MARC21 の場合に文字セット変換が推奨されます。なぜなら これらは一般的に結果を MARC-8 文字セットで返しますが、ブラウザでは この文字セットがサポートされていないからです。変換を指定するには、 ; charset=from, to を追加します。 from はレコードの元の文字セットで、 to は結果の文字セット（PHP によって 表示されるもの）です。

string

レコードは、単純な形式の文字列で返されます。 このモードではすべての MARC レコードが ISO2709 の行単位 フォーマットに変換されますが、これは非常に読みにくいものです。 XML レコードおよび SUTRS は、本来のフォーマットのまま返されます。 GRS-1 は（醜い）行単位フォーマットで返されます。

このフォーマットが役に立つのは、結果を手っ取り早く表示したい場合 - デバッグ中など - の場合です。適切な形式で表示するのには適していません。

xml

レコードは、可能ならば XML 文字列として返されます。 このモードでは、すべての MARC レコードは » MARCXML に変換されます。 XML レコードおよび SUTRS は、本来のフォーマットのままで返されます。 GRS-1 はサポートしていません。

このフォーマットは string と似ていますが、 MARC レコードが MARCXML に変換される点が違います。

このフォーマットは、レコードが XML パーサや XSLT プロセッサに 渡される場合に役立ちます。

raw

レコードは、その本来のフォーマットのままで返されます。 MARC、XML および SUTRS で使用可能です。GRS-1 では動作しません。

MARC レコードは ISO2709 文字列として返されます。XML および SUTRS は文字列として返されます。

syntax

レコードの構文が文字列で返されます。たとえば USmarc、GRS-1、 XML などです。

database

レコードの該当位置に関連するデータベースの名前を文字列で返します。

array

レコードは、GRS-1 の構造を反映した配列で返されます。 この型は MARC および GRS-1 で使用可能です。XML、SUTRS はサポートされておらず、実際のレコードが XML あるいは SUTRS であった場合は空文字列が返されます。

返される配列には、GRS-1 の各リーフ/内部ノードに対応するリストが 含まれます。個々のリスト内にもリストがあり、 最初の要素が path でその次が data です（もし data が存在する場合）。

path は、ルートから各リーフまでの（構造化された GRS-1 レコードの） ツリーコンポーネントの一覧を保持します。各コンポーネントはタグ型で、 タグの値は (type, value のような形式のペアとなります。

tags 文字列は、一般に type 3 の tag に対応します。 MARC は配列で返すことも可能です（内部で GRS-1 に変換されます）。

戻り値

位置 pos のレコードを返します。もし指定した位置に レコードが存在しない場合は空文字列を返します。

もし指定した位置にデータベースのレコードが存在しない場合、 空文字列が返されます。

例

例1 GRS-1 レコードの配列

このような GRS-1 レコードを想定します。

(4,52)Robert M. Pirsig
(4,70)
      (4,90)
            (2,7)Transworld Publishers, ltd.
このレコードは、ルートに 2 つのノードを持っています。ルートレベルの 最初の要素は (4,52) [tag type 4, tag value 52] で、そのデータは Robert M. Pirsig です。ルートレベルの 2 番目の 要素 (4,70) はサブツリーを持っており、そこにはひとつの要素 (4,90) があります。(4,90) はまた別のサブツリー (2,7) を持っており、 そのデータは Transworld Publishers, ltd. です。

このレコードが $p の位置にあるとすると、

<?php

$ar = yaz_record($id, $p, "array");
print_r($ar);

?>
この出力は以下のようになります。
Array
(
    [0] => Array
        (
            [0] => (4,52)
            [1] => Robert M. Pirsig
        )
    [1] => Array
        (
            [0] => (4,70)
        )
    [2] => Array
        (
            [0] => (4,70)(4,90)
        )
    [3] => Array
        (
            [0] => (4,70)(4,90)(2,7)
            [1] => Transworld Publishers, ltd.
        )
)

例2 MARCXML の使用

この PHP コードは、MARC21/USMARC レコードを MARCXML として返します。 元のレコードは marc-8（ほとんどの XML パーサはこれを理解できません）なので、 これを UTF-8（すべての XML パーサはこれを理解できなければなりません） に変換します。

<?php
$rec = yaz_record($id, $p, "xml; charset=marc-8,utf-8");
?>

レコード $rec は Sablotron XSLT を使用して 以下のように処理可能です。

<?php

$xslfile = 'display.xsl';
$processor = xslt_create();
$parms = array('/_xml' => $rec);
$res = xslt_process($processor, 'arg:/_xml', $xslfile, NULL, $parms);
xslt_free($processor);
$res = preg_replace("'</?html[^>]*>'", '', $res);
echo $res;

?>


スキャンの準備をする

  • ≪ yaz_record
  • yaz_scan_result ≫
  • PHP Manual
  • YAZ 関数
  • スキャンの準備をする

yaz_scan

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_scan — スキャンの準備をする

説明

yaz_scan(
resource $id,
string $type,
string $startterm,
array $flags = ?
): void

この関数は、指定した接続上で Z39.50 スキャンリクエストの 準備をします。

実際にスキャンリクエストをサーバーへ送信して応答を受信するには、
yaz_wait() をコールする必要があります。
yaz_wait() のコールが完了した後、応答を処理するために
yaz_error() および yaz_scan_result()
をコールします。

パラメータ

id

yaz_connect() が返す接続リソース。

type

現時点では rpn 型のみがサポートされています。

startterm

スキャンを開始する項目の位置。

開始項目の形式は、パラメータ type で与えられます。

このパラメータの構文は、 yaz_search() で説明した RPN クエリに似ています。 startterm は、ゼロ以上の @attr 演算子の後に トークンがひとつだけ続く形式となります。

flags

オプションのパラメータで、スキャンリクエストの動作を制御する 追加情報を指定します。現在、次の3つの添字が flags 配列から 読み込まれます。 number（リクエストされた語の数）、 position（要求された語の位置）、 stepSize（要求されたステップ数）

戻り値

値を返しません。

例

例1 タイトルをスキャンする PHP 関数

<?php
function scan_titles($id, $startterm)
{
yaz_scan($id, "rpn", "@attr 1=4 " . $startterm);
yaz_wait();
$errno = yaz_errno($id);
if ($errno == 0) {
$ar = yaz_scan_result($id, $options);
echo 'Scan ok; ';
foreach ($options as $key => $val) {
echo "$key = $val &nbsp;";
}
echo '<br /><table>';
while (list($key, list($k, $term, $tcount)) = each($ar)) {
if (empty($k)) continue;
echo "<tr><td>$term</td><td>$tcount</td></tr>";
}
echo '</table>';
} else {
echo "Scan failed. Error: " . yaz_error($id) . "<br />";
}
}
?>


スキャンリクエストの結果を返す

  • ≪ yaz_scan
  • yaz_schema ≫
  • PHP Manual
  • YAZ 関数
  • スキャンリクエストの結果を返す

yaz_scan_result

(PHP 4 >= 4.0.5, PECL yaz >= 0.9.0)

yaz_scan_result — スキャンリクエストの結果を返す

説明

yaz_scan_result(resource $id, array &$result = ?): array

yaz_scan_result() は、直近の yaz_scan() の実行時にサーバーから受信した 項目と関連情報を返します。

パラメータ

id

yaz_connect() が返す接続リソース。

result

指定された場合、この配列にスキャン時の応答から得られた追加情報が 代入されます。

  • number - 返されたエントリの数。

  • stepsize - ステップサイズ。

  • position - 項目の位置。

  • status - スキャンステータス。

戻り値

配列 (0..n-1) を返します。n は返された項目の数です。個々の値は ペアになっており、最初の値が項目名、2 つめの値が結果の数となります。


取得するスキーマを指定する

  • ≪ yaz_scan_result
  • yaz_search ≫
  • PHP Manual
  • YAZ 関数
  • 取得するスキーマを指定する

yaz_schema

(PHP 4 >= 4.2.0, PECL yaz >= 0.9.0)

yaz_schema — 取得するスキーマを指定する

説明

yaz_schema(resource $id, string $schema): void

yaz_schema() は取得するスキーマを指定します。

この関数は、 yaz_search() あるいは yaz_present() より前にコールしなければなりません。

パラメータ

id

yaz_connect() が返す接続リソース。

schema

ドット記法の（1.2.840.10003.13.4 のような） OID あるいは登録されているスキーマのひとつ、たとえば GILS-schema、Holdings、 Zthes などのいずれかで指定する必要があります。

戻り値

値を返しません。


検索を準備する

  • ≪ yaz_schema
  • yaz_set_option ≫
  • PHP Manual
  • YAZ 関数
  • 検索を準備する

yaz_search

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_search — 検索を準備する

説明

yaz_search(resource $id, string $type, string $query): bool

yaz_search() は、指定した接続で検索を行う準備をします。

yaz_connect() と同様にこの関数は非ブロックモードで 動作し、後で yaz_wait() がコールされたときのために 検索の準備をするだけです。

パラメータ

id

yaz_connect() が返す接続リソース。

type

クエリの型を表します。現在は "rpn" のみがサポート されており、この場合 3 番目の引数には Type-1 クエリを前置表記で 指定します。

query

RPN クエリは、Z39.50 規格により定義された Type-1 クエリのテキスト 表現です。しかし、YAZ により使用されるテキスト表現では、演算子が オペランドの前にある前置表記が使用されます。クエリ文字列はトークンの 並びであり、このトークンでは 2 重引用符で括られない限り空白文字は 無視されます。アットマーク(@)で始まるトークンは 演算子とみなされ、そうでない場合は検索項目として処理されます。

RPN 演算子
構文 | 説明
@and query1 query2 | query1 および query2 の積集合
@or query1 query2 | query1 および query2 の和集合
@not query1 query2 | query1 であり、query2 でない
@set name | 結果セットへのリファレンス
@attrset set query | クエリの属性セットを指定します。この構造が使用できるのは 全てのクエリの始めに一回だけです。
@attr [set] type=value query | クエリに属性を適用します。型と値は属性型と属性値をそれぞれ指定する 整数です。この組みが指定された場合、属性の組を指定します。

属性についての情報は » Z39.50 Maintenance Agency サイトにあります。

注意:

もう少しわかりやすい記法を利用したい場合は、CCL パーサ関数 - yaz_ccl_conf() および yaz_ccl_parse() を使用してください。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 クエリの例

単純な検索は以下のように行います。

computer
は、"computer" を含む文書にマッチします。属性は指定されていません。

クエリ

"knuth donald"
は、"knuth donald" を含む文書にマッチします（サーバーが複数の単語による 検索をサポートしている場合）。

このクエリは、同じフレーズに対して 2 つの属性を適用しています。

@attr 1=1003 @attr 4=1 "knuth donald"
最初の属性は type 1 (Bib-1 use) で、その値は 1003 (Author) です。 2 番目の属性は type 4 (structure) で、その値は 1 (phrase) です。つまりこれは、Donald Knuth が著者である文書にマッチする ことになります。

クエリ

@and @or a b @not @or c d e
は、次のような意味になります。(a or b) and ((c or d) not e)

さらに複雑な例です。

@attrset gils @and @attr 1=4 art @attr 1=2000 company
このクエリは GILS 属性セットをすべて使用しています。このクエリは 表題（Title）に art が含まれ（GILS,BIB-1）、 配布者（Distributor）に company が含まれる（GILS） 文書にマッチします。


接続に関するひとつあるいは複数のオプションを設定する

  • ≪ yaz_search
  • yaz_sort ≫
  • PHP Manual
  • YAZ 関数
  • 接続に関するひとつあるいは複数のオプションを設定する

yaz_set_option

(PECL yaz >= 0.9.0)

yaz_set_option — 接続に関するひとつあるいは複数のオプションを設定する

説明

yaz_set_option(resource $id, string $name, string $value): void
yaz_set_option(resource $id, array $options): void

指定した接続について、ひとつあるいは複数のオプションを設定します。

パラメータ

id

yaz_connect() が返す接続リソース。

name あるいは options

文字列あるいは配列です。

文字列を指定すると、指定するオプションの名前として扱われます。 その value を指定する必要があります。

配列を指定すると、連想配列（オプション名 -> オプションの値）として 扱われます。

PHP/YAZ 接続オプション
名前 | 説明
implementationName | サーバーの実装名。
implementationVersion | サーバーの実装バージョン。
implementationId | サーバーの実装 ID 。
schema | 取得するスキーマ。デフォルトではスキーマを使用しません。 このオプションを設定することは、yaz_schema() を使用することと等価です。
preferredRecordSyntax | 取得するレコードの構文。 デフォルトでは構文を 使用しません。このオプションを設定することは、 yaz_syntax() を使用することと等価です。
start | yaz_search() あるいは yaz_present() で取得する最初のレコードのオフセット。最初のレコードの 番号は 0 で、2 番目のレコードは 1 です。 このオプションを count とともに設定する ことは、yaz_range() をコールすることと 同じですが、yaz_range() ではレコードの 番号が 1 から始まる点が違います。
count | yaz_search() あるいは yaz_present() で取得するレコードの最大数。
elementSetName | 取得するエレメントセットの名前。このオプションを設定することは、 yaz_element() を使用することと等価です。
value

オプションの新しい値。変更前の値が文字列である場合にのみ これを使用します。

戻り値

値を返しません。


ソート条件を設定する

  • ≪ yaz_set_option
  • yaz_syntax ≫
  • PHP Manual
  • YAZ 関数
  • ソート条件を設定する

yaz_sort

(PHP 4 >= 4.0.7, PECL yaz >= 0.9.0)

yaz_sort — ソート条件を設定する

説明

yaz_sort(resource $id, string $criteria): void

この関数は、ソート条件を設定して Z39.50 Sort を有効にします。

この関数は、yaz_search() の前に コールします。この関数を単独で使用しても何も意味はありません。 yaz_search() と組み合わせて使用した場合、 検索応答が受信されてから全ての Z39.50 Present で取得される前に Z39.50 Sort が送信されます。

パラメータ

id

yaz_connect() が返す接続リソース。

criteria

field1 flags1 field2 flags2 のような 形式の文字列。field1 は最初にソートする属性を、そして field2 は 2 番目の属性を... のように指定します。

フィールドは、カンマで区切られた 型 = 値 の組からなる数値属性の 組み合わせ（例 1=4,2=1）、または 文字列の方法を指定することも可能です（例 title）。 フラグは次の文字の並びからなり、空白により区切ることはありません。

ソートフラグ
a

昇順ソート

d

降順ソート

i

大文字小文字を区別しないソート

s

大文字小文字を区別するソート

戻り値

値を返しません。

例

例1 ソート条件

Bib1 属性のタイトル（title）で大文字小文字を区別しない昇順のソートを 行うには、以下のソート方法を使用してください。

1=4 ia

2 番目のソート条件として著者（author）を指定し、大文字小文字を区別する 昇順のソートを行うには以下のようにします。

1=4 ia 1=1003 sa


取得用に適当なレコード構文を指定する

  • ≪ yaz_sort
  • yaz_wait ≫
  • PHP Manual
  • YAZ 関数
  • 取得用に適当なレコード構文を指定する

yaz_syntax

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_syntax — 取得用に適当なレコード構文を指定する

説明

yaz_syntax(resource $id, string $syntax): void

yaz_syntax() は、取得するレコードの構文を指定します。

この関数は yaz_search() あるいは yaz_present() より前にコールしなければなりません。

パラメータ

id

yaz_connect() が返す接続リソース。

syntax

ドット記法の（1.2.840.10003.5.10 のような） OID あるいは登録されている構文のひとつ（たとえば sutrs、 usmarc、grs1、xml など）のいずれかで指定する必要があります。

戻り値

値を返しません。


Z39.50 リクエストが完了するまで待つ

  • ≪ yaz_syntax
  • 0MQ messaging ≫
  • PHP Manual
  • YAZ 関数
  • Z39.50 リクエストが完了するまで待つ

yaz_wait

(PHP 4 >= 4.0.1, PECL yaz >= 0.9.0)

yaz_wait — Z39.50 リクエストが完了するまで待つ

説明

yaz_wait(array &$options = ?): mixed

この関数は、関数 yaz_connect()、
yaz_search()、yaz_present()、
yaz_scan()、yaz_itemorder()
により準備された発行済のリクエストを、ネットワーク経由で（ブロック
モードで）伝送します。

yaz_wait()は、全てのターゲットが全てのリクエストを 完了したか、（エラーの場合には）中断された場合に処理を戻します。

パラメータ

options

オプションの連想配列。

timeout

タイムアウトの秒数を設定します。ターゲットが時間内に応答しなかった 場合は動作していないとみなされ、yaz_wait() は終了します。タイムアウトのデフォルト値は 15 秒です。

event

論理型の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。 イベントモードでは、成功した場合にリソース、失敗した場合に false を返します。


ZMQ

  • はじめに
  • インストール/設定
    • 要件
  • ZMQ — The ZMQ class
    • ZMQ::__construct — ZMQ constructor
  • ZMQContext — The ZMQContext class
    • ZMQContext::__construct — Construct a new ZMQContext object
    • ZMQContext::getOpt — Get context option
    • ZMQContext::getSocket — Create a new socket
    • ZMQContext::isPersistent — Whether the context is persistent
    • ZMQContext::setOpt — Set a socket option
  • ZMQSocket — The ZMQSocket class
    • ZMQSocket::bind — Bind the socket
    • ZMQSocket::connect — Connect the socket
    • ZMQSocket::__construct — Construct a new ZMQSocket
    • ZMQSocket::disconnect — Disconnect a socket
    • ZMQSocket::getEndpoints — Get list of endpoints
    • ZMQSocket::getPersistentId — Get the persistent id
    • ZMQSocket::getSocketType — Get the socket type
    • ZMQSocket::getSockOpt — Get socket option
    • ZMQSocket::isPersistent — Whether the socket is persistent
    • ZMQSocket::recv — Receives a message
    • ZMQSocket::recvMulti — Receives a multipart message
    • ZMQSocket::send — Sends a message
    • ZMQSocket::sendmulti — マルチパートメッセージを送る
    • ZMQSocket::setSockOpt — Set a socket option
    • ZMQSocket::unbind — Unbind the socket
  • ZMQPoll — The ZMQPoll class
    • ZMQPoll::add — Add item to the poll set
    • ZMQPoll::clear — Clear the poll set
    • ZMQPoll::count — Count items in the poll set
    • ZMQPoll::getLastErrors — Get poll errors
    • ZMQPoll::poll — Poll the items
    • ZMQPoll::remove — Remove item from poll set
  • ZMQDevice — The ZMQDevice class
    • ZMQDevice::__construct — Construct a new device
    • ZMQDevice::getIdleTimeout — Get the idle timeout
    • ZMQDevice::getTimerTimeout — Get the timer timeout
    • ZMQDevice::run — Run the new device
    • ZMQDevice::setIdleCallback — Set the idle callback function
    • ZMQDevice::setIdleTimeout — Set the idle timeout
    • ZMQDevice::setTimerCallback — Set the timer callback function
    • ZMQDevice::setTimerTimeout — Set the timer timeout


はじめに

"OMQ is a software library that lets you quickly design and implement a fast message-based application." --0MQ Website

For more information about 0MQ, see » http://zeromq.org/.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • 0MQ messaging
  • インストール/設定

インストール/設定

目次

  • 要件


要件

ZMQ extension requires 0MQ version 2.0.7 or higher. 0MQ can be acquired from » http://zeromq.org/area:download.

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/zmq


The ZMQ class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

class ZMQ {
/* 定数 */
const int SOCKET_PAIR;
const int SOCKET_PUB;
const int SOCKET_SUB;
const int SOCKET_REQ;
const int SOCKET_REP;
const int SOCKET_XREQ;
const int SOCKET_XREP;
const int SOCKET_PUSH;
const int SOCKET_PULL;
const int SOCKET_ROUTER;
const int SOCKET_DEALER;
const int SOCKET_XPUB;
const int SOCKET_XSUB;
const int SOCKET_STREAM;
const int SOCKOPT_HWM;
const int SOCKOPT_SNDHWM;
const int SOCKOPT_RCVHWM;
const int SOCKOPT_AFFINITY;
const int SOCKOPT_IDENTITY;
const int SOCKOPT_SUBSCRIBE;
const int SOCKOPT_UNSUBSCRIBE;
const int SOCKOPT_RATE;
const int SOCKOPT_RECOVERY_IVL;
const int SOCKOPT_RECONNECT_IVL;
const int SOCKOPT_RECONNECT_IVL_MAX;
const int SOCKOPT_MCAST_LOOP;
const int SOCKOPT_SNDBUF;
const int SOCKOPT_RCVBUF;
const int SOCKOPT_RCVMORE;
const int SOCKOPT_TYPE;
const int SOCKOPT_LINGER;
const int SOCKOPT_BACKLOG;
const int SOCKOPT_MAXMSGSIZE;
const int SOCKOPT_SNDTIMEO;
const int SOCKOPT_RCVTIMEO;
const int SOCKOPT_IPV4ONLY;
const int SOCKOPT_LAST_ENDPOINT;
const int SOCKOPT_TCP_KEEPALIVE_IDLE;
const int SOCKOPT_TCP_KEEPALIVE_CNT;
const int SOCKOPT_TCP_KEEPALIVE_INTVL;
const int SOCKOPT_TCP_ACCEPT_FILTER;
const int SOCKOPT_TCP_ACCEPT_FILTER;
const int SOCKOPT_DELAY_ATTACH_ON_CONNECT;
const int SOCKOPT_XPUB_VERBOSE;
const int SOCKOPT_ROUTER_RAW;
const int SOCKOPT_IPV6;
const int CTXOPT_MAX_SOCKETS;
const int POLL_IN;
const int POLL_OUT;
const int MODE_NOBLOCK;
const int MODE_DONTWAIT;
const int MODE_SNDMORE;
const int ERR_INTERNAL;
const int ERR_EAGAIN;
const int ERR_ENOTSUP;
const int ERR_EFSM;
const int ERR_ETERM;
/* メソッド */
private __construct()
}

定義済み定数

ZMQ Constant Types

ZMQ::SOCKET_PAIR

Exclusive pair pattern

ZMQ::SOCKET_PUB

Publisher socket

ZMQ::SOCKET_SUB

Subscriber socket

ZMQ::SOCKET_REQ

Request socket

ZMQ::SOCKET_REP

Reply socket

ZMQ::SOCKET_XREQ

Alias for SOCKET_DEALER

ZMQ::SOCKET_XREP

Alias for SOCKET_ROUTER

ZMQ::SOCKET_PUSH

Pipeline upstream push socket

ZMQ::SOCKET_PULL

Pipeline downstream pull socket

ZMQ::SOCKET_ROUTER

Extended REP socket that can route replies to requesters

ZMQ::SOCKET_DEALER

Extended REQ socket that load balances to all connected peers

ZMQ::SOCKET_XPUB

Similar to SOCKET_PUB, except you can receive subscriptions as messages. The subscription message is 0 (unsubscribe) or 1 (subscribe) followed by the topic.

ZMQ::SOCKET_XSUB

Similar to SOCKET_SUB, except you can send subscriptions as messages. See SOCKET_XPUB for format.

ZMQ::SOCKET_STREAM

Used to send and receive TCP data from a non-OMQ peer. Available if compiled against ZeroMQ 4.x or higher (Value: int).

ZMQ::SOCKOPT_HWM

The high water mark for inbound and outbound messages is a hard limit on the maximum number of outstanding messages OMQ shall queue in memory for any single peer that the specified socket is communicating with. Setting this option on a socket will only affect connections made after the option has been set. On ZeroMQ 3.x this is a wrapper for setting both SNDHWM and RCVHWM. (Value: int).

ZMQ::SOCKOPT_SNDHWM

The ZMQ_SNDHWM option shall set the high water mark for outbound messages on the specified socket. Available if compiled against ZeroMQ 3.x or higher (Value: int).

ZMQ::SOCKOPT_RCVHWM

The SOCKOPT_RCVHWM option shall set the high water mark for inbound messages on the specified socket. Available if compiled against ZeroMQ 3.x or higher (Value: int).

ZMQ::SOCKOPT_AFFINITY

Set I/O thread affinity (Value: int)

ZMQ::SOCKOPT_IDENTITY

Set socket identity (Value: string)

ZMQ::SOCKOPT_SUBSCRIBE

Establish message filter. Valid for subscriber socket (Value: string)

ZMQ::SOCKOPT_UNSUBSCRIBE

Remove message filter. Valid for subscriber socket (Value: string)

ZMQ::SOCKOPT_RATE

Set rate for multicast sockets (pgm) (Value: int >= 0)

ZMQ::SOCKOPT_RECOVERY_IVL

Set multicast recovery interval (Value: int >= 0)

ZMQ::SOCKOPT_RECONNECT_IVL

Set the initial reconnection interval (Value: int >= 0)

ZMQ::SOCKOPT_RECONNECT_IVL_MAX

Set the max reconnection interval (Value: int >= 0)

ZMQ::SOCKOPT_MCAST_LOOP

Control multicast loopback (Value: int >= 0)

ZMQ::SOCKOPT_SNDBUF

Set kernel transmit buffer size (Value: int >= 0)

ZMQ::SOCKOPT_RCVBUF

Set kernel receive buffer size (Value: int >= 0)

ZMQ::SOCKOPT_RCVMORE

Receive multi-part messages (Value: int)

ZMQ::SOCKOPT_TYPE

Get the socket type. Valid for getSockOpt (Value: int)

ZMQ::SOCKOPT_LINGER

The linger value of the socket. Specifies how long the socket blocks trying flush messages after it has been closed (Value: int)

ZMQ::SOCKOPT_BACKLOG

The SOCKOPT_BACKLOG option shall set the maximum length of the queue of outstanding peer connections for the specified socket; this only applies to connection-oriented transports. (Value: int)

ZMQ::SOCKOPT_MAXMSGSIZE

Limits the maximum size of the inbound message. Value -1 means no limit. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_SNDTIMEO

Sets the timeout for send operation on the socket. Value -1 means no limit. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_RCVTIMEO

Sets the timeout for receive operation on the socket. Value -1 means no limit. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_IPV4ONLY

Disable IPV6 support if 1. Available if compiled against ZeroMQ 3.x (Value: int)

ZMQ::SOCKOPT_LAST_ENDPOINT

Retrieve the last connected endpoint - for use with * wildcard ports. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_TCP_KEEPALIVE_IDLE

Idle time for TCP keepalive. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_TCP_KEEPALIVE_CNT

Count time for TCP keepalive. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_TCP_KEEPALIVE_INTVL

Interval for TCP keepalive. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::SOCKOPT_DELAY_ATTACH_ON_CONNECT

Set a CIDR string to match against incoming TCP connections. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_TCP_ACCEPT_FILTER

Set a CIDR string to match against incoming TCP connections. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_XPUB_VERBOSE

Set the XPUB to receive an application message on each instance of a subscription. Available if compiled against ZeroMQ 3.x or higher (Value: string)

ZMQ::SOCKOPT_ROUTER_RAW

Sets the raw mode on the ROUTER, when set to 1. In raw mode when using tcp:// transport the socket will read and write without ZeroMQ framing. Available if compiled against ZeroMQ 4.0 or higher (Value: string)

ZMQ::SOCKOPT_IPV6

Enable IPV6. Available if compiled against ZeroMQ 4.0 or higher (Value: string)

ZMQ::CTXOPT_MAX_SOCKETS

The socket limit for this context. Available if compiled against ZeroMQ 3.x or higher (Value: int)

ZMQ::POLL_IN

Poll for incoming data

ZMQ::POLL_OUT

Poll for outgoing data

ZMQ::MODE_NOBLOCK

Non-blocking operation. Deprecated, use ZMQ::MODE_DONTWAIT instead

ZMQ::MODE_DONTWAIT

Non-blocking operation

ZMQ::MODE_SNDMORE

Send multi-part message

ZMQ::DEVICE_FORWARDER

Forwarder device

ZMQ::DEVICE_QUEUE

Queue device

ZMQ::DEVICE_STREAMER

Streamer device

ZMQ::ERR_INTERNAL

ZMQ extension internal error

ZMQ::ERR_EAGAIN

Implies that the operation would block when ZMQ::MODE_DONTWAIT is used

ZMQ::ERR_ENOTSUP

The operation is not supported by the socket type

ZMQ::ERR_EFSM

The operation can not be executed because the socket is not in correct state

ZMQ::ERR_ETERM

The context has been terminated

目次

  • ZMQ::__construct — ZMQ constructor


ZMQ constructor

  • ≪ ZMQ
  • ZMQContext ≫
  • PHP Manual
  • ZMQ
  • ZMQ constructor

ZMQ::__construct

(PECL zmq >= 0.5.0)

ZMQ::__construct — ZMQ constructor

説明

private ZMQ::__construct()

Private constructor to prevent direct initialization. This class holds the constants for ZMQ extension.

パラメータ

この関数にはパラメータはありません。

戻り値


The ZMQContext class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

class ZMQContext {
/* メソッド */
public __construct(int $io_threads = 1, bool $is_persistent = true)
public getOpt(string $key): mixed
public getSocket(int $type, string $persistent_id = null, callable $on_new_socket = null): ZMQSocket
public isPersistent(): bool
public setOpt(int $key, mixed $value): ZMQContext
}

目次

  • ZMQContext::__construct — Construct a new ZMQContext object
  • ZMQContext::getOpt — Get context option
  • ZMQContext::getSocket — Create a new socket
  • ZMQContext::isPersistent — Whether the context is persistent
  • ZMQContext::setOpt — Set a socket option


Construct a new ZMQContext object

  • ≪ ZMQContext
  • ZMQContext::getOpt ≫
  • PHP Manual
  • ZMQContext
  • Construct a new ZMQContext object

ZMQContext::__construct

(PECL zmq >= 0.5.0)

ZMQContext::__construct — Construct a new ZMQContext object

説明

public ZMQContext::__construct(int $io_threads = 1, bool $is_persistent = true)

Constructs a new ZMQ context. The context is used to initialize sockets. A persistent context is required to initialize persistent sockets.

パラメータ

io_threads

Number of io-threads in the context.

is_persistent

Whether the context is persistent. Persistent context is stored over multiple requests and is a requirement for persistent sockets.

エラー / 例外

Throws ZMQContextException if context initialization fails.

例

例1 A ZMQContext() example

Construct a new context and allocate request socket from it

<?php
/* Allocate a new context */
$context = new ZMQContext();

/* Create a new socket */
$socket = $context->getSocket(ZMQ::SOCKET_REQ, 'my sock');

/* Connect the socket */
$socket->connect("tcp://example.com:1234");

/* Send a request */
$socket->send("Hello there");

/* Receive back the response */
$message = $socket->recv();
?>


Get context option

  • ≪ ZMQContext::__construct
  • ZMQContext::getSocket ≫
  • PHP Manual
  • ZMQContext
  • Get context option

ZMQContext::getOpt

(PECL zmq >= 1.0.4)

ZMQContext::getOpt — Get context option

説明

public ZMQContext::getOpt(string $key): mixed

Returns the value of a context option.

パラメータ

key

An integer representing the option. See the ZMQ::CTXOPT_* constants.

戻り値

Returns either a string or an int depending on key. Throws ZMQContextException on error.


Create a new socket

  • ≪ ZMQContext::getOpt
  • ZMQContext::isPersistent ≫
  • PHP Manual
  • ZMQContext
  • Create a new socket

ZMQContext::getSocket

(PECL zmq >= 0.5.0)

ZMQContext::getSocket — Create a new socket

説明

public ZMQContext::getSocket(int $type, string $persistent_id = null, callable $on_new_socket = null): ZMQSocket

Shortcut for creating new sockets from the context. If the context is not persistent the persistent_id parameter is ignored and the socket falls back to being non-persistent. The on_new_socket is called only when a new underlying socket structure is created.

パラメータ

type

ZMQ::SOCKET_* constant to specify socket type.

persistent_id

If persistent_id is specified the socket will be persisted over multiple requests.

on_new_socket

Callback function, which is executed when a new socket structure is created. This function does not get invoked if the underlying persistent connection is re-used. The callback takes ZMQSocket and persistent_id as two arguments.

戻り値

Returns a ZMQSocket object.

エラー / 例外

Throws ZMQSocketException on error.

例

例1 A ZMQContext() example

Basic usage

<?php
/* Allocate a new context */
$context = new ZMQContext();

/* Create a new socket */
$socket = $context->getSocket(ZMQ::SOCKET_REQ, 'my sock');

/* Connect the socket */
$socket->connect("tcp://example.com:1234");

/* Send a request */
$socket->send("Hello there");

/* Receive back the response */
$message = $socket->recv();
echo "Received message: {$message}\n";
?>


Whether the context is persistent

  • ≪ ZMQContext::getSocket
  • ZMQContext::setOpt ≫
  • PHP Manual
  • ZMQContext
  • Whether the context is persistent

ZMQContext::isPersistent

(PECL zmq >= 0.5.0)

ZMQContext::isPersistent — Whether the context is persistent

説明

public ZMQContext::isPersistent(): bool

Whether the context is persistent. Persistent context is needed for persistent connections as each socket is allocated from a context.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true if the context is persistent and false if the context is non-persistent.


Set a socket option

  • ≪ ZMQContext::isPersistent
  • ZMQSocket ≫
  • PHP Manual
  • ZMQContext
  • Set a socket option

ZMQContext::setOpt

(PECL zmq >= 1.0.4)

ZMQContext::setOpt — Set a socket option

説明

public ZMQContext::setOpt(int $key, mixed $value): ZMQContext

Sets a ZMQ context option. The type of the value depends on the key. See ZMQ Constant Types for more information.

パラメータ

key

One of the ZMQ::CTXOPT_* constants.

value

The value of the parameter.

戻り値

Returns the current object. Throws ZMQContextException on error.


The ZMQSocket class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

class ZMQSocket {
/* メソッド */
public bind(string $dsn, bool $force = false): ZMQSocket
public connect(string $dsn, bool $force = false): ZMQSocket
public __construct(
ZMQContext $context,
int $type,
string $persistent_id = null,
callable $on_new_socket = null
)
public disconnect(string $dsn): ZMQSocket
public getEndpoints(): array
public getPersistentId(): string
public getSocketType(): int
public getSockOpt(string $key): mixed
public isPersistent(): bool
public recv(int $mode = 0): string
public recvMulti(int $mode = 0): array
public send(string $message, int $mode = 0): ZMQSocket
public sendmulti(array $message, int $mode = 0): ZMQSocket
public setSockOpt(int $key, mixed $value): ZMQSocket
public unbind(string $dsn): ZMQSocket
}

目次

  • ZMQSocket::bind — Bind the socket
  • ZMQSocket::connect — Connect the socket
  • ZMQSocket::__construct — Construct a new ZMQSocket
  • ZMQSocket::disconnect — Disconnect a socket
  • ZMQSocket::getEndpoints — Get list of endpoints
  • ZMQSocket::getPersistentId — Get the persistent id
  • ZMQSocket::getSocketType — Get the socket type
  • ZMQSocket::getSockOpt — Get socket option
  • ZMQSocket::isPersistent — Whether the socket is persistent
  • ZMQSocket::recv — Receives a message
  • ZMQSocket::recvMulti — Receives a multipart message
  • ZMQSocket::send — Sends a message
  • ZMQSocket::sendmulti — マルチパートメッセージを送る
  • ZMQSocket::setSockOpt — Set a socket option
  • ZMQSocket::unbind — Unbind the socket


Bind the socket

  • ≪ ZMQSocket
  • ZMQSocket::connect ≫
  • PHP Manual
  • ZMQSocket
  • Bind the socket

ZMQSocket::bind

(PECL zmq >= 0.5.0)

ZMQSocket::bind — Bind the socket

説明

public ZMQSocket::bind(string $dsn, bool $force = false): ZMQSocket

Bind the socket to an endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The bind dsn, for example transport://address.

force

Tries to bind even if the socket has already been bound to the given endpoint.

戻り値

Returns the current object. Throws ZMQSocketException on error.


Connect the socket

  • ≪ ZMQSocket::bind
  • ZMQSocket::__construct ≫
  • PHP Manual
  • ZMQSocket
  • Connect the socket

ZMQSocket::connect

(PECL zmq >= 0.5.0)

ZMQSocket::connect — Connect the socket

説明

public ZMQSocket::connect(string $dsn, bool $force = false): ZMQSocket

Connect the socket to a remote endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The connect dsn, for example transport://address.

force

Tries to connect even if the socket has already been connected to given endpoint.

戻り値

Returns the current object.

エラー / 例外

Throws ZMQSocketException on error.

例

例1 A ZMQContext() example

Construct a new context and allocate request socket from it

<?php
/* Server hostname */
$dsn = "tcp://127.0.0.1:5555";

/* Create a socket */
$socket = new ZMQSocket(new ZMQContext(), ZMQ::SOCKET_REQ, 'my socket');

/* Get list of connected endpoints */
$endpoints = $socket->getEndpoints();

/* Check if the socket is connected */
if (!in_array($dsn, $endpoints['connect'])) {
echo "<p>Connecting to $dsn</p>";
$socket->connect($dsn);
} else {
echo "<p>Already connected to $dsn</p>";
}

/* Send and receive */
$socket->send("Hello!");
$message = $socket->recv();

echo "<p>Server said: {$message}</p>";
?>


Construct a new ZMQSocket

  • ≪ ZMQSocket::connect
  • ZMQSocket::disconnect ≫
  • PHP Manual
  • ZMQSocket
  • Construct a new ZMQSocket

ZMQSocket::__construct

(PECL zmq >= 0.5.0)

ZMQSocket::__construct — Construct a new ZMQSocket

説明

public ZMQSocket::__construct(
ZMQContext $context,
int $type,
string $persistent_id = null,
callable $on_new_socket = null
)

Constructs a ZMQSocket object. persistent_id parameter can be used to allocated a persistent socket. A persistent socket has to be allocated from a persistent context and it stays connected over multiple requests. The persistent_id parameter can be used to recall the same socket over multiple requests. The on_new_socket is called only when a new underlying socket structure is created.

パラメータ

context

ZMQContext object.

type

The socket type. See ZMQ::SOCKET_* constants.

persistent_id

If persistent_id is specified the socket will be persisted over multiple requests. If context is not persistent the socket falls back to non-persistent mode.

on_new_socket

Callback function, which is executed when a new socket structure is created. This function does not get invoked if the underlying persistent connection is re-used.

callback(ZMQSocket $socket, string $persistent_id = null)

エラー / 例外

Throws ZMQSocketException on error.

例

例1 A ZMQSocket() example

Using callback the bind/connect socket

<?php

/*
The socket is persistent so this function is called only on the
first request to the script.
*/
function on_new_socket_cb(ZMQSocket $socket, $persistent_id = null)
{
if ($persistent_id === 'server') {
$socket->bind("tcp://localhost:12122");
} else {
$socket->connect("tcp://localhost:12122");
}
}

/* Allocate a new context */
$context = new ZMQContext();

/* Create a new socket */
$socket = $context->getSocket(ZMQ::SOCKET_REP, 'server', 'on_new_socket_cb');

$message = $socket->recv();
echo "Received message: {$message}\n";
?>


Disconnect a socket

  • ≪ ZMQSocket::__construct
  • ZMQSocket::getEndpoints ≫
  • PHP Manual
  • ZMQSocket
  • Disconnect a socket

ZMQSocket::disconnect

(PECL zmq >= 1.0.4)

ZMQSocket::disconnect — Disconnect a socket

説明

public ZMQSocket::disconnect(string $dsn): ZMQSocket

Disconnect the socket from a previously connected remote endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The connect dsn, for example transport://address.

戻り値

Returns the current object. Throws ZMQSocketException on error.


Get list of endpoints

  • ≪ ZMQSocket::disconnect
  • ZMQSocket::getPersistentId ≫
  • PHP Manual
  • ZMQSocket
  • Get list of endpoints

ZMQSocket::getEndpoints

(PECL zmq >= 0.5.0)

ZMQSocket::getEndpoints — Get list of endpoints

説明

public ZMQSocket::getEndpoints(): array

Returns a list of endpoints where the socket is connected or bound to.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array containing elements 'bind' and 'connect'.


Get the persistent id

  • ≪ ZMQSocket::getEndpoints
  • ZMQSocket::getSocketType ≫
  • PHP Manual
  • ZMQSocket
  • Get the persistent id

ZMQSocket::getPersistentId

(PECL zmq >= 0.5.0)

ZMQSocket::getPersistentId — Get the persistent id

説明

public ZMQSocket::getPersistentId(): string

Returns the persistent id of the socket.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the persistent id string assigned of the object and null if socket is not persistent.


Get the socket type

  • ≪ ZMQSocket::getPersistentId
  • ZMQSocket::getSockOpt ≫
  • PHP Manual
  • ZMQSocket
  • Get the socket type

ZMQSocket::getSocketType

(PECL zmq >= 0.5.0)

ZMQSocket::getSocketType — Get the socket type

説明

public ZMQSocket::getSocketType(): int

Gets the socket type.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer representing the socket type. The integer can be compared against ZMQ::SOCKET_* constants.


Get socket option

  • ≪ ZMQSocket::getSocketType
  • ZMQSocket::isPersistent ≫
  • PHP Manual
  • ZMQSocket
  • Get socket option

ZMQSocket::getSockOpt

(PECL zmq >= 0.5.0)

ZMQSocket::getSockOpt — Get socket option

説明

public ZMQSocket::getSockOpt(string $key): mixed

Returns the value of a socket option.

パラメータ

key

An integer representing the option. See the ZMQ::SOCKOPT_* constants.

戻り値

Returns either a string or an int depending on key. Throws ZMQSocketException on error.


Whether the socket is persistent

  • ≪ ZMQSocket::getSockOpt
  • ZMQSocket::recv ≫
  • PHP Manual
  • ZMQSocket
  • Whether the socket is persistent

ZMQSocket::isPersistent

(PECL zmq >= 0.5.0)

ZMQSocket::isPersistent — Whether the socket is persistent

説明

public ZMQSocket::isPersistent(): bool

Check whether the socket is persistent.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a bool based on whether the socket is persistent or not.


Receives a message

  • ≪ ZMQSocket::isPersistent
  • ZMQSocket::recvMulti ≫
  • PHP Manual
  • ZMQSocket
  • Receives a message

ZMQSocket::recv

(PECL zmq >= 0.5.0)

ZMQSocket::recv — Receives a message

説明

public ZMQSocket::recv(int $mode = 0): string

Receive a message from a socket. By default receiving will block until a message is available unless ZMQ::MODE_DONTWAIT flag is used. ZMQ::SOCKOPT_RCVMORE socket option can be used for receiving multi-part messages. See ZMQSocket::setSockOpt() for more information.

パラメータ

mode

Pass mode flags to receive multipart messages or non-blocking operation. See ZMQ::MODE_* constants.

戻り値

Returns the message. If ZMQ::MODE_DONTWAIT is used and the operation would block false shall be returned.

エラー / 例外

Throws ZMQSocketException on error.

例

例1 A send/recv example

Non-blocking send / receive

<?php

/* Create new queue object, there needs to be a server at the other end */
$queue = new ZMQSocket(new ZMQContext(), ZMQ::SOCKET_REQ);
$queue->connect("tcp://127.0.0.1:5555");

/* Assign socket 1 to the queue, send and receive */
$retries = 5;
$sending = true;

/* Start a loop */
do {
try {
/* Try to send / receive */
if ($sending) {
echo "Sending message\n";
$queue->send("This is a message", ZMQ::MODE_DONTWAIT);
$sending = false;
} else {
echo "Got response: " . $queue->recv(ZMQ::MODE_DONTWAIT) . "\n";
break;
}
} catch (ZMQSocketException $e) {
/* EAGAIN means that the operation would have blocked, retry */
if ($e->getCode() === ZMQ::ERR_EAGAIN) {
echo " - Got EAGAIN, retrying ($retries)\n";
} else {
die(" - Error: " . $e->getMessage());
}
}
/* Sleep a bit between operations */
usleep(5);
} while (--$retries);
?>

上の例の出力は、 たとえば以下のようになります。

Sending message
 - Unable to execute operation, retrying (4)
Got response: This is a message


Receives a multipart message

  • ≪ ZMQSocket::recv
  • ZMQSocket::send ≫
  • PHP Manual
  • ZMQSocket
  • Receives a multipart message

ZMQSocket::recvMulti

(PECL zmq >= 0.8.0)

ZMQSocket::recvMulti — Receives a multipart message

説明

public ZMQSocket::recvMulti(int $mode = 0): array

Receive an array multipart message from a socket. By default receiving will block until a message is available unless ZMQ::MODE_NOBLOCK flag is used.

パラメータ

mode

Pass mode flags to receive multipart messages or non-blocking operation. See ZMQ::MODE_* constants.

戻り値

Returns the array of message parts. Throws ZMQSocketException in error. If ZMQ::MODE_NOBLOCK is used and the operation would block bool false shall be returned.


Sends a message

  • ≪ ZMQSocket::recvMulti
  • ZMQSocket::sendmulti ≫
  • PHP Manual
  • ZMQSocket
  • Sends a message

ZMQSocket::send

(PECL zmq >= 0.5.0)

ZMQSocket::send — Sends a message

説明

public ZMQSocket::send(string $message, int $mode = 0): ZMQSocket

Send a message using the socket. The operation can block unless ZMQ::MODE_NOBLOCK is used.

パラメータ

message

The message to send.

mode

Pass mode flags to receive multipart messages or non-blocking operation. See ZMQ::MODE_* constants.

戻り値

Returns the current object. Throws ZMQSocketException on error. If ZMQ::MODE_NOBLOCK is used and the operation would block bool false shall be returned.


マルチパートメッセージを送る

  • ≪ ZMQSocket::send
  • ZMQSocket::setSockOpt ≫
  • PHP Manual
  • ZMQSocket
  • マルチパートメッセージを送る

ZMQSocket::sendmulti

(PECL zmq >= 0.8.0)

ZMQSocket::sendmulti — マルチパートメッセージを送る

説明

public ZMQSocket::sendmulti(array $message, int $mode = 0): ZMQSocket

ソケットを使ってマルチパートメッセージを送ります。 この操作は ZMQ::MODE_NOBLOCK を使わないとブロックされる可能性があります。

パラメータ

message

送信するメッセージ - 文字列の配列

mode

マルチパートメッセージを受け取るか、 ノンブロッキング操作を行うかのモードフラグ。 ZMQ::MODE_* 定数を参照ください。

戻り値

現在のオブジェクトを返します。 エラーの場合は ZMQSocketException をスローします。 ZMQ::MODE_NOBLOCK が使われていた場合、 操作はブロックされ、false が返されます。


Set a socket option

  • ≪ ZMQSocket::sendmulti
  • ZMQSocket::unbind ≫
  • PHP Manual
  • ZMQSocket
  • Set a socket option

ZMQSocket::setSockOpt

(PECL zmq >= 0.5.0)

ZMQSocket::setSockOpt — Set a socket option

説明

public ZMQSocket::setSockOpt(int $key, mixed $value): ZMQSocket

Sets a ZMQ socket option. The type of the value depends on the key. See ZMQ Constant Types for more information.

パラメータ

key

One of the ZMQ::SOCKOPT_* constants.

value

The value of the parameter.

戻り値

Returns the current object. Throws ZMQSocketException on error.


Unbind the socket

  • ≪ ZMQSocket::setSockOpt
  • ZMQPoll ≫
  • PHP Manual
  • ZMQSocket
  • Unbind the socket

ZMQSocket::unbind

(PECL zmq >= 1.0.4)

ZMQSocket::unbind — Unbind the socket

説明

public ZMQSocket::unbind(string $dsn): ZMQSocket

Unbind the socket from an endpoint. The endpoint is defined in format transport://address where transport is one of the following: inproc, ipc, tcp, pgm or epgm.

パラメータ

dsn

The previously bound dsn, for example transport://address.

戻り値

Returns the current object. Throws ZMQSocketException on error.


The ZMQPoll class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

class ZMQPoll {
/* メソッド */
public add(mixed $entry, int $type): string
public clear(): ZMQPoll
public count(): int
public getLastErrors(): array
public poll(array &$readable, array &$writable, int $timeout = -1): int
public remove(mixed $item): bool
}

目次

  • ZMQPoll::add — Add item to the poll set
  • ZMQPoll::clear — Clear the poll set
  • ZMQPoll::count — Count items in the poll set
  • ZMQPoll::getLastErrors — Get poll errors
  • ZMQPoll::poll — Poll the items
  • ZMQPoll::remove — Remove item from poll set


Add item to the poll set

  • ≪ ZMQPoll
  • ZMQPoll::clear ≫
  • PHP Manual
  • ZMQPoll
  • Add item to the poll set

ZMQPoll::add

(PECL zmq >= 0.5.0)

ZMQPoll::add — Add item to the poll set

説明

public ZMQPoll::add(mixed $entry, int $type): string

Adds a new item to the poll set and returns the internal id of the added item. The item can be removed from the poll set using the returned string id.

パラメータ

entry

ZMQSocket object or a PHP stream resource

type

Defines what activity the socket is polled for. See ZMQ::POLL_IN and ZMQ::POLL_OUT constants.

戻り値

Returns a string id of the added item which can be later used to remove the item. Throws ZMQPollException on error.


Clear the poll set

  • ≪ ZMQPoll::add
  • ZMQPoll::count ≫
  • PHP Manual
  • ZMQPoll
  • Clear the poll set

ZMQPoll::clear

(PECL zmq >= 0.5.0)

ZMQPoll::clear — Clear the poll set

説明

public ZMQPoll::clear(): ZMQPoll

Clears all elements from the poll set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the current object.


Count items in the poll set

  • ≪ ZMQPoll::clear
  • ZMQPoll::getLastErrors ≫
  • PHP Manual
  • ZMQPoll
  • Count items in the poll set

ZMQPoll::count

(PECL zmq >= 0.5.0)

ZMQPoll::count — Count items in the poll set

説明

public ZMQPoll::count(): int

Count the items in the poll set.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an int representing the amount of items in the poll set.


Get poll errors

  • ≪ ZMQPoll::count
  • ZMQPoll::poll ≫
  • PHP Manual
  • ZMQPoll
  • Get poll errors

ZMQPoll::getLastErrors

(PECL zmq >= 0.5.0)

ZMQPoll::getLastErrors — Get poll errors

説明

public ZMQPoll::getLastErrors(): array

Returns the ids of the objects that had errors in the last poll.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array containing ids for the items that had errors in the last poll. Empty array is returned if there were no errors.


Poll the items

  • ≪ ZMQPoll::getLastErrors
  • ZMQPoll::remove ≫
  • PHP Manual
  • ZMQPoll
  • Poll the items

ZMQPoll::poll

(PECL zmq >= 0.5.0)

ZMQPoll::poll — Poll the items

説明

public ZMQPoll::poll(array &$readable, array &$writable, int $timeout = -1): int

Polls the items in the current poll set. The readable and writable items are returned in the readable and writable parameters. ZMQPoll::getLastErrors() can be used to check if there were errors.

パラメータ

readable

Array where readable ZMQSockets/PHP streams are returned. The array will be cleared at the beginning of the operation.

writable

Array where writable ZMQSockets/PHP streams are returned. The array will be cleared at the beginning of the operation.

timeout

Timeout for the operation. -1 means that poll waits until at least one item has activity. Please note that starting from version 1.0.0 the poll timeout is defined in milliseconds, rather than microseconds.

戻り値

Returns an integer representing the amount of items with activity.

エラー / 例外

Throws ZMQPollException on error.

例

例1 A ZMQPoll() example

Create a simple poll server

<?php

/* Create socket, request-reply pattern (reply socket) */
$context = new ZMQContext();
$server = $context->getSocket(ZMQ::SOCKET_REP);

/* Bind to port 5555 on 127.0.0.1 */
$server->bind("tcp://127.0.0.1:5555");

/* Create new pollset for incoming/outgoing message */
$poll = new ZMQPoll();

/* Add the object and listen for poll in/out */
$id = $poll->add($server, ZMQ::POLL_IN | ZMQ::POLL_OUT);
echo "Added object with id " . $id . "\n";

/* Initialise readable and writable arrays */
$readable = array();
$writable = array();

while (true) {
/* Amount of events retrieved */
$events = 0;

try {
/* Poll until there is something to do */
$events = $poll->poll($readable, $writable, -1);
$errors = $poll->getLastErrors();

if (count($errors) > 0) {
foreach ($errors as $error) {
echo "Error polling object " . $error . "\n";
}
}
} catch (ZMQPollException $e) {
echo "poll failed: " . $e->getMessage() . "\n";
}

if ($events > 0) {
/* Loop through readable objects and recv messages */
foreach ($readable as $r) {
try {
echo "Received message: " . $r->recv() . "\n";
} catch (ZMQException $e) {
echo "recv failed: " . $e->getMessage() . "\n";
}
}

/* Loop through writable and send back messages */
foreach ($writable as $w) {
try {
$w->send("Got it!");
} catch (ZMQException $e) {
echo "send failed: " . $e->getMessage() . "\n";
}
}
}
}
?>


Remove item from poll set

  • ≪ ZMQPoll::poll
  • ZMQDevice ≫
  • PHP Manual
  • ZMQPoll
  • Remove item from poll set

ZMQPoll::remove

(PECL zmq >= 0.5.0)

ZMQPoll::remove — Remove item from poll set

説明

public ZMQPoll::remove(mixed $item): bool

Remove item from the poll set. The item parameter can be ZMQSocket object, a stream resource or the id returned from ZMQPoll::add() method.

パラメータ

item

The ZMQSocket object, PHP stream or string id of the item.

戻り値

Returns true if the item was removed and false if the object with given id does not exist in the poll set.


The ZMQDevice class

(PECL zmq >= 0.5.0)

はじめに

クラス概要

class ZMQDevice {
/* メソッド */
public __construct(ZMQSocket $frontend, ZMQSocket $backend, ZMQSocket $listener = ?)
public getIdleTimeout(): ZMQDevice
public getTimerTimeout(): ZMQDevice
public run(): void
public setIdleCallback(callable $cb_func, int $timeout, mixed $user_data = ?): ZMQDevice
public setIdleTimeout(int $timeout): ZMQDevice
public setTimerCallback(callable $cb_func, int $timeout, mixed $user_data = ?): ZMQDevice
public setTimerTimeout(int $timeout): ZMQDevice
}

目次

  • ZMQDevice::__construct — Construct a new device
  • ZMQDevice::getIdleTimeout — Get the idle timeout
  • ZMQDevice::getTimerTimeout — Get the timer timeout
  • ZMQDevice::run — Run the new device
  • ZMQDevice::setIdleCallback — Set the idle callback function
  • ZMQDevice::setIdleTimeout — Set the idle timeout
  • ZMQDevice::setTimerCallback — Set the timer callback function
  • ZMQDevice::setTimerTimeout — Set the timer timeout


Construct a new device

  • ≪ ZMQDevice
  • ZMQDevice::getIdleTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Construct a new device

ZMQDevice::__construct

(PECL zmq >= 0.5.0)

ZMQDevice::__construct — Construct a new device

説明

public ZMQDevice::__construct(ZMQSocket $frontend, ZMQSocket $backend, ZMQSocket $listener = ?)

"OMQ devices can do intermediation of addresses, services, queues, or any other abstraction you care to define above the message and socket layers." -- zguide

パラメータ

frontend

Frontend parameter for the devices. Usually where there messages are coming.

backend

Backend parameter for the devices. Usually where there messages going to.

listener

Listener socket, which receives a copy of all messages going both directions. The type of this socket should be SUB, PULL or DEALER.

戻り値

Call to this method will prepare the device. Usually devices are very long running processes so running this method from interactive script is not recommended. This method throw ZMQDeviceException if the device cannot be started.


Get the idle timeout

  • ≪ ZMQDevice::__construct
  • ZMQDevice::getTimerTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Get the idle timeout

ZMQDevice::getIdleTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::getIdleTimeout — Get the idle timeout

説明

public ZMQDevice::getIdleTimeout(): ZMQDevice

Gets the idle callback timeout value. Added in ZMQ extension version 1.1.0.

パラメータ

この関数にはパラメータはありません。

戻り値

This method returns the idle callback timeout value.


Get the timer timeout

  • ≪ ZMQDevice::getIdleTimeout
  • ZMQDevice::run ≫
  • PHP Manual
  • ZMQDevice
  • Get the timer timeout

ZMQDevice::getTimerTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::getTimerTimeout — Get the timer timeout

説明

public ZMQDevice::getTimerTimeout(): ZMQDevice

Gets the timer callback timeout value. Added in ZMQ extension version 1.1.0.

パラメータ

この関数にはパラメータはありません。

戻り値

This method returns the timer timeout value.


Run the new device

  • ≪ ZMQDevice::getTimerTimeout
  • ZMQDevice::setIdleCallback ≫
  • PHP Manual
  • ZMQDevice
  • Run the new device

ZMQDevice::run

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::run — Run the new device

説明

public ZMQDevice::run(): void

Runs the device.

パラメータ

この関数にはパラメータはありません。

戻り値

Call to this method will block until the device is running. It is not recommended that devices are used from interactive scripts. On failure this method will throw ZMQDeviceException.


Set the idle callback function

  • ≪ ZMQDevice::run
  • ZMQDevice::setIdleTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Set the idle callback function

ZMQDevice::setIdleCallback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setIdleCallback — Set the idle callback function

説明

public ZMQDevice::setIdleCallback(callable $cb_func, int $timeout, mixed $user_data = ?): ZMQDevice

Sets the idle callback function. If idle timeout is defined the idle callback function shall be called if the internal poll loop times out without events. If the callback function returns false or a value that evaluates to false the device is stopped. The callback function signature is callback (mixed $user_data).

パラメータ

cb_func

Callback function to invoke when the device is idle. Returning false or a value that evaluates to false from this function will cause the device to stop.

timeout

How often to invoke the idle callback in milliseconds. The idle callback is invoked periodically when there is no activity on the device. The timeout value guarantees that there is at least this amount of milliseconds between invocations of the callback function.

user_data

Additional data to pass to the callback function.

戻り値

On success this method returns the current object.


Set the idle timeout

  • ≪ ZMQDevice::setIdleCallback
  • ZMQDevice::setTimerCallback ≫
  • PHP Manual
  • ZMQDevice
  • Set the idle timeout

ZMQDevice::setIdleTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setIdleTimeout — Set the idle timeout

説明

public ZMQDevice::setIdleTimeout(int $timeout): ZMQDevice

Sets the idle callback timeout value. The idle callback is invoked periodically when the device is idle.

パラメータ

timeout

The idle callback timeout value.

戻り値

On success this method returns the current object.


Set the timer callback function

  • ≪ ZMQDevice::setIdleTimeout
  • ZMQDevice::setTimerTimeout ≫
  • PHP Manual
  • ZMQDevice
  • Set the timer callback function

ZMQDevice::setTimerCallback

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setTimerCallback — Set the timer callback function

説明

public ZMQDevice::setTimerCallback(callable $cb_func, int $timeout, mixed $user_data = ?): ZMQDevice

Sets the timer callback function. The timer callback will be invoked after timeout has passed. The difference between idle and timer callbacks are that idle callback is invoked only when the device is idle. The callback function signature is callback (mixed $user_data). Added in ZMQ extension version 1.1.0.

パラメータ

cb_func

Callback function to invoke when the device is idle. Returning false or a value that evaluates to false from this function will cause the device to stop.

timeout

How often to invoke the idle callback in milliseconds. The idle callback is invoked periodically when there is no activity on the device. The timeout value guarantees that there is at least this amount of milliseconds between invocations of the callback function.

user_data

Additional data to pass to the callback function.

戻り値

On success this method returns the current object.


Set the timer timeout

  • ≪ ZMQDevice::setTimerCallback
  • ZooKeeper ≫
  • PHP Manual
  • ZMQDevice
  • Set the timer timeout

ZMQDevice::setTimerTimeout

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ZMQDevice::setTimerTimeout — Set the timer timeout

説明

public ZMQDevice::setTimerTimeout(int $timeout): ZMQDevice

Sets the timer callback timeout value. The timer callback is invoked periodically if it's set. Added in ZMQ extension version 1.1.0.

パラメータ

timeout

The timer callback timeout value.

戻り値

On success this method returns the current object.


ZooKeeper

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • ZooKeeper 関数
    • zookeeper_dispatch — Calls callbacks for pending operations
  • Zookeeper — The Zookeeper class
    • Zookeeper::addAuth — Specify application credentials
    • Zookeeper::close — Close the zookeeper handle and free up any resources
    • Zookeeper::connect — Create a handle to used communicate with zookeeper
    • Zookeeper::__construct — Create a handle to used communicate with zookeeper
    • Zookeeper::create — Create a node synchronously
    • Zookeeper::delete — Delete a node in zookeeper synchronously
    • Zookeeper::exists — Checks the existence of a node in zookeeper synchronously
    • Zookeeper::get — Gets the data associated with a node synchronously
    • Zookeeper::getAcl — Gets the acl associated with a node synchronously
    • Zookeeper::getChildren — Lists the children of a node synchronously
    • Zookeeper::getClientId — Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
    • Zookeeper::getConfig — Get instance of ZookeeperConfig
    • Zookeeper::getRecvTimeout — Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect
    • Zookeeper::getState — Get the state of the zookeeper connection
    • Zookeeper::isRecoverable — Checks if the current zookeeper connection state can be recovered
    • Zookeeper::set — Sets the data associated with a node
    • Zookeeper::setAcl — Sets the acl associated with a node synchronously
    • Zookeeper::setDebugLevel — Sets the debugging level for the library
    • Zookeeper::setDeterministicConnOrder — Enable/disable quorum endpoint order randomization
    • Zookeeper::setLogStream — Sets the stream to be used by the library for logging
    • Zookeeper::setWatcher — Set a watcher function
  • ZookeeperConfig — The ZookeeperConfig class
    • ZookeeperConfig::add — Add servers to the ensemble
    • ZookeeperConfig::get — Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
    • ZookeeperConfig::remove — Remove servers from the ensemble
    • ZookeeperConfig::set — Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperException — The ZookeeperException class
  • ZookeeperAuthenticationException — The ZookeeperAuthenticationException class
  • ZookeeperConnectionException — The ZookeeperConnectionException class
  • ZookeeperMarshallingException — The ZookeeperMarshallingException class
  • ZookeeperNoNodeException — The ZookeeperNoNodeException class
  • ZookeeperOperationTimeoutException — The ZookeeperOperationTimeoutException class
  • ZookeeperSessionException — The ZookeeperSessionException class


はじめに

This extension uses libzookeeper library to provide API for communicating with ZooKeeper service.

ZooKeeper is an Apache project that enables centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • ZooKeeper
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

This extension requires » ZooKeeper C Binding (version 3.4.1 or greater). For more information, see » ZooKeeper Programmer's Guide.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/zookeeper.

To enable zookeeper support, configure with --with-libzookeeper-dir=DIR. DIR is the install prefix of ZooKeeper C Binding, which must contain the include/zookeeper/zookeeper.h

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


実行時設定

php.ini の設定により動作が変化します。

Zookeeper 設定オプション
名前 | デフォルト | 変更可能 | Changelog
zookeeper.recv_timeout | 10000 | INI_ALL |
zookeeper.session_lock | 1 | INI_SYSTEM |
zookeeper.sess_lock_wait | 150000 | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

zookeeper.recv_timeout int

Default the timeout for any ZooKeeper session.

zookeeper.session_lock int

Enable PHP session locking.

zookeeper.sess_lock_wait int

PHP Session spin lock retry wait time in microseconds. Be carefull when setting this value. Valid values are integers, where 0 is interpreted as the default value. Negative values result in a reduces locking to a try lock.


  • ≪ 実行時設定
  • zookeeper_dispatch ≫
  • PHP Manual
  • ZooKeeper
  • ZooKeeper 関数

ZooKeeper 関数

目次

  • zookeeper_dispatch — Calls callbacks for pending operations


Calls callbacks for pending operations

  • ≪ ZooKeeper 関数
  • Zookeeper ≫
  • PHP Manual
  • ZooKeeper 関数
  • Calls callbacks for pending operations

zookeeper_dispatch

(PECL zookeeper >= 0.4.0)

zookeeper_dispatch — Calls callbacks for pending operations

説明

zookeeper_dispatch(): void

The zookeeper_dispatch() function calls the callbacks passed by operations like Zookeeper::get() or Zookeeper::exists().

警告

Since version 0.4.0, this function must be called manually to achieve asynchronous operations. If you want that to be done automatically, you also can declare ticks at the beginning of your program.

After PHP 7.1, you can ignore this function. This extension uses EG(vm_interrupt) to implement async dispatch.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

This method emits PHP warning when callback could not be invoked.

例

例1 zookeeper_dispatch() example #1

Dispatch callbacks manually.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->get('/zookeeper', function() {
echo "Callback was called".PHP_EOL;
});
while(true) {
sleep(1);
zookeeper_dispatch();
}
?>

例2 zookeeper_dispatch() example #2

Declare ticks.

<?php
declare(ticks=1);

$client = new Zookeeper();
$client->connect('localhost:2181');
$client->get('/zookeeper', function() {
echo "Callback was called".PHP_EOL;
});
while(true) {
sleep(1);
}
?>

参考

  • Zookeeper::addAuth() - Specify application credentials
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::exists() - Checks the existence of a node in zookeeper synchronously
  • Zookeeper::get() - Gets the data associated with a node synchronously
  • Zookeeper::getChildren() - Lists the children of a node synchronously
  • Zookeeper::setWatcher() - Set a watcher function


The Zookeeper class

(PECL zookeeper >= 0.1.0)

はじめに

Represents ZooKeeper session.

クラス概要

class Zookeeper {
/* メソッド */
public __construct(string $host = '', callable $watcher_cb = null, int $recv_timeout = 10000)
public addAuth(string $scheme, string $cert, callable $completion_cb = null): bool
public close(): void
public connect(string $host, callable $watcher_cb = null, int $recv_timeout = 10000): void
public create(
string $path,
string $value,
array $acls,
int $flags = null
): string
public delete(string $path, int $version = -1): bool
public exists(string $path, callable $watcher_cb = null): array
public get(
string $path,
callable $watcher_cb = null,
array &$stat = null,
int $max_size = 0
): string
public getAcl(string $path): array
public getChildren(string $path, callable $watcher_cb = null): array
public getClientId(): int
public getConfig(): ZookeeperConfig
public getRecvTimeout(): int
public getState(): int
public isRecoverable(): bool
public set(
string $path,
string $value,
int $version = -1,
array &$stat = null
): bool
public setAcl(string $path, int $version, array $acl): bool
public static setDebugLevel(int $logLevel): bool
public static setDeterministicConnOrder(bool $yesOrNo): bool
public setLogStream(resource $stream): bool
public setWatcher(callable $watcher_cb): bool
/* 定数 */
const int PERM_READ = 1;
const int PERM_WRITE = 2;
const int PERM_CREATE = 4;
const int PERM_DELETE = 8;
const int PERM_ADMIN = 16;
const int PERM_ALL = 31;
const int EPHEMERAL = 1;
const int SEQUENCE = 2;
const int LOG_LEVEL_ERROR = 1;
const int LOG_LEVEL_WARN = 2;
const int LOG_LEVEL_INFO = 3;
const int LOG_LEVEL_DEBUG = 4;
const int EXPIRED_SESSION_STATE = -112;
const int AUTH_FAILED_STATE = -113;
const int CONNECTING_STATE = 1;
const int ASSOCIATING_STATE = 2;
const int CONNECTED_STATE = 3;
const int READONLY_STATE = 5;
const int NOTCONNECTED_STATE = 999;
const int CREATED_EVENT = 1;
const int DELETED_EVENT = 2;
const int CHANGED_EVENT = 3;
const int CHILD_EVENT = 4;
const int SESSION_EVENT = -1;
const int NOTWATCHING_EVENT = -2;
const int SYSTEMERROR = -1;
const int RUNTIMEINCONSISTENCY = -2;
const int DATAINCONSISTENCY = -3;
const int CONNECTIONLOSS = -4;
const int MARSHALLINGERROR = -5;
const int UNIMPLEMENTED = -6;
const int OPERATIONTIMEOUT = -7;
const int BADARGUMENTS = -8;
const int INVALIDSTATE = -9;
const int NEWCONFIGNOQUORUM = -13;
const int RECONFIGINPROGRESS = -14;
const int OK = 0;
const int APIERROR = -100;
const int NONODE = -101;
const int NOAUTH = -102;
const int BADVERSION = -103;
const int NOCHILDRENFOREPHEMERALS = -108;
const int NODEEXISTS = -110;
const int NOTEMPTY = -111;
const int SESSIONEXPIRED = -112;
const int INVALIDCALLBACK = -113;
const int INVALIDACL = -114;
const int AUTHFAILED = -115;
const int CLOSING = -116;
const int NOTHING = -117;
const int SESSIONMOVED = -118;
const int NOTREADONLY = -119;
const int EPHEMERALONLOCALSESSION = -120;
const int NOWATCHER = -121;
const int RECONFIGDISABLED = -122;
}

定義済み定数

ZooKeeper Permissions

Zookeeper::PERM_READ

Can read nodes value and list its children

Zookeeper::PERM_WRITE

Can set the nodes value

Zookeeper::PERM_CREATE

Can create children

Zookeeper::PERM_DELETE

Can delete children

Zookeeper::PERM_ADMIN

Can execute set_acl()

Zookeeper::PERM_ALL

All of the above flags ORd together

ZooKeeper Create Flags

Zookeeper::EPHEMERAL

If Zookeeper::EPHEMERAL flag is set, the node will automatically get removed if the client session goes away.

Zookeeper::SEQUENCE

If the Zookeeper::SEQUENCE flag is set, a unique monotonically increasing sequence number is appended to the path name. The sequence number is always fixed length of 10 digits, 0 padded.

ZooKeeper Log Levels

Zookeeper::LOG_LEVEL_ERROR

Outputs only error mesages

Zookeeper::LOG_LEVEL_WARN

Outputs errors/warnings

Zookeeper::LOG_LEVEL_INFO

Outputs big action messages besides errors/warnings

Zookeeper::LOG_LEVEL_DEBUG

Outputs all

ZooKeeper States

Zookeeper::EXPIRED_SESSION_STATE

Connected but session expired

Zookeeper::AUTH_FAILED_STATE

Connected but auth failed

Zookeeper::CONNECTING_STATE

Connecting

Zookeeper::ASSOCIATING_STATE

Associating

Zookeeper::CONNECTED_STATE

Connected

Zookeeper::READONLY_STATE

TODO: help us improve this extension.

Zookeeper::NOTCONNECTED_STATE

Connection failed

ZooKeeper Watch Types

Zookeeper::CREATED_EVENT

A node has been created

This is only generated by watches on non-existent nodes. These watches are set using Zookeeper::exists.

Zookeeper::DELETED_EVENT

A node has been deleted

This is only generated by watches on nodes. These watches are set using Zookeeper::exists and Zookeeper::get.

Zookeeper::CHANGED_EVENT

A node has changed

This is only generated by watches on nodes. These watches are set using Zookeeper::exists and Zookeeper::get.

Zookeeper::CHILD_EVENT

A change as occurred in the list of children

This is only generated by watches on the child list of a node. These watches are set using Zookeeper::getChildren.

Zookeeper::SESSION_EVENT

A session has been lost

This is generated when a client loses contact or reconnects with a server.

Zookeeper::NOTWATCHING_EVENT

A watch has been removed

This is generated when the server for some reason, probably a resource constraint, will no longer watch a node for a client.

ZooKeeper System and Server-side Errors

Zookeeper::SYSTEMERROR

This is never thrown by the server, it shouldn't be used other than to indicate a range. Specifically error codes greater than this value, but lesser than Zookeeper::APIERROR, are system errors.

Zookeeper::RUNTIMEINCONSISTENCY

A runtime inconsistency was found.

Zookeeper::DATAINCONSISTENCY

A data inconsistency was found.

Zookeeper::CONNECTIONLOSS

Connection to the server has been lost.

Zookeeper::MARSHALLINGERROR

Error while marshalling or unmarshalling data.

Zookeeper::UNIMPLEMENTED

Operation is unimplemented.

Zookeeper::OPERATIONTIMEOUT

Operation timeout.

Zookeeper::BADARGUMENTS

Invalid arguments.

Zookeeper::INVALIDSTATE

Invalid zhandle state.

Zookeeper::NEWCONFIGNOQUORUM

No quorum of new config is connected and up-to-date with the leader of last committed config - try invoking reconfiguration after new servers are connected and synced.

Available as of ZooKeeper 3.5.0

Zookeeper::RECONFIGINPROGRESS

Reconfiguration requested while another reconfiguration is currently in progress. This is currently not supported. Please retry.

Available as of ZooKeeper 3.5.0

ZooKeeper API Errors

Zookeeper::OK

Everything is OK.

Zookeeper::APIERROR

This is never thrown by the server, it shouldn't be used other than to indicate a range. Specifically error codes greater than this value are API errors (while values less than this indicate a Zookeeper::SYSTEMERROR).

Zookeeper::NONODE

Node does not exist.

Zookeeper::NOAUTH

Not authenticated.

Zookeeper::BADVERSION

Version conflict.

Zookeeper::NOCHILDRENFOREPHEMERALS

Ephemeral nodes may not have children.

Zookeeper::NODEEXISTS

The node already exists.

Zookeeper::NOTEMPTY

The node has children.

Zookeeper::SESSIONEXPIRED

The session has been expired by the server.

Zookeeper::INVALIDCALLBACK

Invalid callback specified.

Zookeeper::INVALIDACL

Invalid ACL specified.

Zookeeper::AUTHFAILED

Client authentication failed.

Zookeeper::CLOSING

ZooKeeper is closing.

Zookeeper::NOTHING

(not error) No server responses to process.

Zookeeper::SESSIONMOVED

Session moved to another server, so operation is ignored.

Zookeeper::NOTREADONLY

State-changing request is passed to read-only server.

Zookeeper::EPHEMERALONLOCALSESSION

Attempt to create ephemeral node on a local session.

Zookeeper::NOWATCHER

The watcher couldn't be found.

Zookeeper::RECONFIGDISABLED

Attempts to perform a reconfiguration operation when reconfiguration feature is disabled.

目次

  • Zookeeper::addAuth — Specify application credentials
  • Zookeeper::close — Close the zookeeper handle and free up any resources
  • Zookeeper::connect — Create a handle to used communicate with zookeeper
  • Zookeeper::__construct — Create a handle to used communicate with zookeeper
  • Zookeeper::create — Create a node synchronously
  • Zookeeper::delete — Delete a node in zookeeper synchronously
  • Zookeeper::exists — Checks the existence of a node in zookeeper synchronously
  • Zookeeper::get — Gets the data associated with a node synchronously
  • Zookeeper::getAcl — Gets the acl associated with a node synchronously
  • Zookeeper::getChildren — Lists the children of a node synchronously
  • Zookeeper::getClientId — Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
  • Zookeeper::getConfig — Get instance of ZookeeperConfig
  • Zookeeper::getRecvTimeout — Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect
  • Zookeeper::getState — Get the state of the zookeeper connection
  • Zookeeper::isRecoverable — Checks if the current zookeeper connection state can be recovered
  • Zookeeper::set — Sets the data associated with a node
  • Zookeeper::setAcl — Sets the acl associated with a node synchronously
  • Zookeeper::setDebugLevel — Sets the debugging level for the library
  • Zookeeper::setDeterministicConnOrder — Enable/disable quorum endpoint order randomization
  • Zookeeper::setLogStream — Sets the stream to be used by the library for logging
  • Zookeeper::setWatcher — Set a watcher function


Specify application credentials

  • ≪ Zookeeper
  • Zookeeper::close ≫
  • PHP Manual
  • Zookeeper
  • Specify application credentials

Zookeeper::addAuth

(PECL zookeeper >= 0.1.0)

Zookeeper::addAuth — Specify application credentials

説明

public Zookeeper::addAuth(string $scheme, string $cert, callable $completion_cb = null): bool

The application calls this function to specify its credentials for purposes of authentication. The server will use the security provider specified by the scheme parameter to authenticate the client connection. If the authentication request has failed: - the server connection is dropped. - the watcher is called with the ZOO_AUTH_FAILED_STATE value as the state parameter.

パラメータ

scheme

The id of authentication scheme. Natively supported: "digest" password-based authentication

cert

Application credentials. The actual value depends on the scheme.

completion_cb

The routine to invoke when the request completes. One of the following result codes may be passed into the completion callback: - ZOK operation completed successfully - ZAUTHFAILED authentication failed

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::addAuth() example

Add auth before requesting node value.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$zookeeper->set($path, $value);

$zookeeper->addAuth('digest', 'user0:passwd0');
$r = $zookeeper->get($path);
if ($r)
echo $r;
else
echo 'ERR';
?>

上の例の出力は以下となります。

nodevalue

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::setAcl() - Sets the acl associated with a node synchronously
  • Zookeeper::getAcl() - Gets the acl associated with a node synchronously
  • ZooKeeper States
  • ZookeeperException


Close the zookeeper handle and free up any resources

  • ≪ Zookeeper::addAuth
  • Zookeeper::connect ≫
  • PHP Manual
  • Zookeeper
  • Close the zookeeper handle and free up any resources

Zookeeper::close

(PECL zookeeper >= 0.5.0)

Zookeeper::close — Close the zookeeper handle and free up any resources

説明

public Zookeeper::close(): void

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

This method emits ZookeeperException and it's derivatives when closing an uninitialized instance.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException


Create a handle to used communicate with zookeeper

  • ≪ Zookeeper::close
  • Zookeeper::__construct ≫
  • PHP Manual
  • Zookeeper
  • Create a handle to used communicate with zookeeper

Zookeeper::connect

(PECL zookeeper >= 0.2.0)

Zookeeper::connect — Create a handle to used communicate with zookeeper

説明

public Zookeeper::connect(string $host, callable $watcher_cb = null, int $recv_timeout = 10000): void

This method creates a new handle and a zookeeper session that corresponds to that handle. Session establishment is asynchronous, meaning that the session should not be considered established until (and unless) an event of state ZOO_CONNECTED_STATE is received.

パラメータ

host

Comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"

watcher_cb

The global watcher callback function. When notifications are triggered this function will be invoked.

recv_timeout

The timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE).

戻り値

値を返しません。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or could not init instance.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • ZookeeperException


Create a handle to used communicate with zookeeper

  • ≪ Zookeeper::connect
  • Zookeeper::create ≫
  • PHP Manual
  • Zookeeper
  • Create a handle to used communicate with zookeeper

Zookeeper::__construct

(PECL zookeeper >= 0.1.0)

Zookeeper::__construct — Create a handle to used communicate with zookeeper

説明

public Zookeeper::__construct(string $host = '', callable $watcher_cb = null, int $recv_timeout = 10000)

This method creates a new handle and a zookeeper session that corresponds to that handle. Session establishment is asynchronous, meaning that the session should not be considered established until (and unless) an event of state ZOO_CONNECTED_STATE is received.

パラメータ

host

comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"

watcher_cb

the global watcher callback function. When notifications are triggered this function will be invoked.

recv_timeout

the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE).

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or could not init instance.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException


Create a node synchronously

  • ≪ Zookeeper::__construct
  • Zookeeper::delete ≫
  • PHP Manual
  • Zookeeper
  • Create a node synchronously

Zookeeper::create

(PECL zookeeper >= 0.1.0)

Zookeeper::create — Create a node synchronously

説明

public Zookeeper::create(
string $path,
string $value,
array $acls,
int $flags = null
): string

This method will create a node in ZooKeeper. A node can only be created if it does not already exists. The Create Flags affect the creation of nodes. If ZOO_EPHEMERAL flag is set, the node will automatically get removed if the client session goes away. If the ZOO_SEQUENCE flag is set, a unique monotonically increasing sequence number is appended to the path name.

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

value

The data to be stored in the node.

acls

The initial ACL of the node. The ACL must not be null or empty.

flags

this parameter can be set to 0 for normal create or an OR of the Create Flags

戻り値

Returns the path of the new node (this might be different than the supplied path because of the ZOO_SEQUENCE flag) on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to create node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::create() example

Create a new node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$aclArray = array(
array(
'perms' => Zookeeper::PERM_ALL,
'scheme' => 'world',
'id' => 'anyone',
)
);
$path = '/path/to/newnode';
$realPath = $zookeeper->create($path, null, $aclArray);
if ($realPath)
echo $realPath;
else
echo 'ERR';
?>

上の例の出力は以下となります。

/path/to/newnode

参考

  • Zookeeper::delete() - Delete a node in zookeeper synchronously
  • Zookeeper::getChildren() - Lists the children of a node synchronously
  • ZooKeeper Permissions
  • ZookeeperException


Delete a node in zookeeper synchronously

  • ≪ Zookeeper::create
  • Zookeeper::exists ≫
  • PHP Manual
  • Zookeeper
  • Delete a node in zookeeper synchronously

Zookeeper::delete

(PECL zookeeper >= 0.2.0)

Zookeeper::delete — Delete a node in zookeeper synchronously

説明

public Zookeeper::delete(string $path, int $version = -1): bool

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to delete node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::delete() example

Delete a existing node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$r = $zookeeper->delete($path);
if ($r)
echo 'SUCCESS';
else
echo 'ERR';
?>

上の例の出力は以下となります。

SUCCESS

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::getChildren() - Lists the children of a node synchronously
  • ZookeeperException


Checks the existence of a node in zookeeper synchronously

  • ≪ Zookeeper::delete
  • Zookeeper::get ≫
  • PHP Manual
  • Zookeeper
  • Checks the existence of a node in zookeeper synchronously

Zookeeper::exists

(PECL zookeeper >= 0.1.0)

Zookeeper::exists — Checks the existence of a node in zookeeper synchronously

説明

public Zookeeper::exists(string $path, callable $watcher_cb = null): array

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

watcher_cb

if nonzero, a watch will be set at the server to notify the client if the node changes. The watch will be set even if the node does not

戻り値

Returns the value of stat for the path if the given node exists, otherwise false.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to check the existence of a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::exists() example

Check the existence of a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$r = $zookeeper->exists($path);
if ($r)
echo 'EXISTS';
else
echo 'N/A or ERR';
?>

上の例の出力は以下となります。

EXISTS

参考

  • Zookeeper::get() - Gets the data associated with a node synchronously
  • ZookeeperException


Gets the data associated with a node synchronously

  • ≪ Zookeeper::exists
  • Zookeeper::getAcl ≫
  • PHP Manual
  • Zookeeper
  • Gets the data associated with a node synchronously

Zookeeper::get

(PECL zookeeper >= 0.1.0)

Zookeeper::get — Gets the data associated with a node synchronously

説明

public Zookeeper::get(
string $path,
callable $watcher_cb = null,
array &$stat = null,
int $max_size = 0
): string

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

watcher_cb

If nonzero, a watch will be set at the server to notify the client if the node changes.

stat

If not NULL, will hold the value of stat for the path on return.

max_size

Max size of the data. If 0 is used, this method will return the whole data.

戻り値

Returns the data on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to get value from node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::get() example

Get value from node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$zookeeper->set($path, $value);

$r = $zookeeper->get($path);
if ($r)
echo $r;
else
echo 'ERR';
?>

上の例の出力は以下となります。

nodevalue

例2 Zookeeper::get() stat example

Get node stat info.

<?php
$zookeeper = new Zookeeper('localhost:2181');
$path = '/path/to/node';
$stat = [];
$zookeeper->get($path, null, $stat);
var_dump($stat);
?>

上の例の出力は以下となります。

array(11) {
  ["czxid"]=>
  float(0)
  ["mzxid"]=>
  float(0)
  ["ctime"]=>
  float(0)
  ["mtime"]=>
  float(0)
  ["version"]=>
  int(0)
  ["cversion"]=>
  int(-2)
  ["aversion"]=>
  int(0)
  ["ephemeralOwner"]=>
  float(0)
  ["dataLength"]=>
  int(0)
  ["numChildren"]=>
  int(2)
  ["pzxid"]=>
  float(0)
}

参考

  • Zookeeper::set() - Sets the data associated with a node
  • ZookeeperException


Gets the acl associated with a node synchronously

  • ≪ Zookeeper::get
  • Zookeeper::getChildren ≫
  • PHP Manual
  • Zookeeper
  • Gets the acl associated with a node synchronously

Zookeeper::getAcl

(PECL zookeeper >= 0.1.0)

Zookeeper::getAcl — Gets the acl associated with a node synchronously

説明

public Zookeeper::getAcl(string $path): array

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

戻り値

Return acl array on success and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to get ACL of a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::getAcl() example

Get ACL of a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$aclArray = array(
array(
'perms' => Zookeeper::PERM_ALL,
'scheme' => 'world',
'id' => 'anyone',
)
);
$path = '/path/to/newnode';
$zookeeper->setAcl($path, $aclArray);

$r = $zookeeper->getAcl($path);
if ($r)
var_dump($r);
else
echo 'ERR';
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(3) {
    ["perms"]=>
    int(31)
    ["scheme"]=>
    string(5) "world"
    ["id"]=>
    string(6) "anyone"
  }
}

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::setAcl() - Sets the acl associated with a node synchronously
  • ZooKeeper Permissions
  • ZookeeperException


Lists the children of a node synchronously

  • ≪ Zookeeper::getAcl
  • Zookeeper::getClientId ≫
  • PHP Manual
  • Zookeeper
  • Lists the children of a node synchronously

Zookeeper::getChildren

(PECL zookeeper >= 0.1.0)

Zookeeper::getChildren — Lists the children of a node synchronously

説明

public Zookeeper::getChildren(string $path, callable $watcher_cb = null): array

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

watcher_cb

If nonzero, a watch will be set at the server to notify the client if the node changes.

戻り値

Returns an array with children paths on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to list children of a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::getChildren() example

Lists children of a node.

<?php

$zookeeper = new Zookeeper('locahost:2181');
$path = '/zookeeper';
$r = $zookeeper->getchildren($path);

if ($r) {
var_dump($r);
} else {
echo 'ERR';
}

?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  string(6) "config"
}

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::delete() - Delete a node in zookeeper synchronously
  • ZookeeperException


Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)

  • ≪ Zookeeper::getChildren
  • Zookeeper::getConfig ≫
  • PHP Manual
  • Zookeeper
  • Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)

Zookeeper::getClientId

(PECL zookeeper >= 0.1.0)

Zookeeper::getClientId — Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)

説明

public Zookeeper::getClientId(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the client session id on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when it could not get client session id.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::getState() - Get the state of the zookeeper connection
  • ZooKeeper States
  • ZookeeperException


Get instance of ZookeeperConfig

  • ≪ Zookeeper::getClientId
  • Zookeeper::getRecvTimeout ≫
  • PHP Manual
  • Zookeeper
  • Get instance of ZookeeperConfig

Zookeeper::getConfig

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

Zookeeper::getConfig — Get instance of ZookeeperConfig

説明

public Zookeeper::getConfig(): ZookeeperConfig

パラメータ

この関数にはパラメータはありません。

戻り値

Returns instance of ZookeeperConfig.

参考

  • ZookeeperConfig


Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect

  • ≪ Zookeeper::getConfig
  • Zookeeper::getState ≫
  • PHP Manual
  • Zookeeper
  • Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect

Zookeeper::getRecvTimeout

(PECL zookeeper >= 0.1.0)

Zookeeper::getRecvTimeout — Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect

説明

public Zookeeper::getRecvTimeout(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the timeout for this session on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException


Get the state of the zookeeper connection

  • ≪ Zookeeper::getRecvTimeout
  • Zookeeper::isRecoverable ≫
  • PHP Manual
  • Zookeeper
  • Get the state of the zookeeper connection

Zookeeper::getState

(PECL zookeeper >= 0.1.0)

Zookeeper::getState — Get the state of the zookeeper connection

説明

public Zookeeper::getState(): int

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the state of zookeeper connection on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when it fails to get state of zookeeper connection.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::getClientId() - Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
  • ZooKeeper States
  • ZookeeperException


Checks if the current zookeeper connection state can be recovered

  • ≪ Zookeeper::getState
  • Zookeeper::set ≫
  • PHP Manual
  • Zookeeper
  • Checks if the current zookeeper connection state can be recovered

Zookeeper::isRecoverable

(PECL zookeeper >= 0.1.0)

Zookeeper::isRecoverable — Checks if the current zookeeper connection state can be recovered

説明

public Zookeeper::isRecoverable(): bool

The application must close the handle and try to reconnect.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true/false on success, and false on failure.

エラー / 例外

This method emits PHP error/warning when operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • Zookeeper::getClientId() - Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
  • ZooKeeper States
  • ZookeeperException


Sets the data associated with a node

  • ≪ Zookeeper::isRecoverable
  • Zookeeper::setAcl ≫
  • PHP Manual
  • Zookeeper
  • Sets the data associated with a node

Zookeeper::set

(PECL zookeeper >= 0.1.0)

Zookeeper::set — Sets the data associated with a node

説明

public Zookeeper::set(
string $path,
string $value,
int $version = -1,
array &$stat = null
): bool

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

value

The data to be stored in the node.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to save value to node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::set() example

Save value to node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$path = '/path/to/node';
$value = 'nodevalue';
$r = $zookeeper->set($path, $value);
if ($r)
echo 'SUCCESS';
else
echo 'ERR';
?>

上の例の出力は以下となります。

SUCCESS

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::get() - Gets the data associated with a node synchronously
  • ZookeeperException


Sets the acl associated with a node synchronously

  • ≪ Zookeeper::set
  • Zookeeper::setDebugLevel ≫
  • PHP Manual
  • Zookeeper
  • Sets the acl associated with a node synchronously

Zookeeper::setAcl

(PECL zookeeper >= 0.1.0)

Zookeeper::setAcl — Sets the acl associated with a node synchronously

説明

public Zookeeper::setAcl(string $path, int $version, array $acl): bool

パラメータ

path

The name of the node. Expressed as a file name with slashes separating ancestors of the node.

version

The expected version of the path.

acl

The acl to be set on the path.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to set ACL for a node.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::setAcl() example

Set ACL for a node.

<?php
$zookeeper = new Zookeeper('locahost:2181');
$aclArray = array(
array(
'perms' => Zookeeper::PERM_ALL,
'scheme' => 'world',
'id' => 'anyone',
)
);
$path = '/path/to/newnode';
$zookeeper->setAcl($path, $aclArray);

$r = $zookeeper->getAcl($path);
if ($r)
var_dump($r);
else
echo 'ERR';
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  array(3) {
    ["perms"]=>
    int(31)
    ["scheme"]=>
    string(5) "world"
    ["id"]=>
    string(6) "anyone"
  }
}

参考

  • Zookeeper::create() - Create a node synchronously
  • Zookeeper::getAcl() - Gets the acl associated with a node synchronously
  • ZooKeeper Permissions
  • ZookeeperException


Sets the debugging level for the library

  • ≪ Zookeeper::setAcl
  • Zookeeper::setDeterministicConnOrder ≫
  • PHP Manual
  • Zookeeper
  • Sets the debugging level for the library

Zookeeper::setDebugLevel

(PECL zookeeper >= 0.1.0)

Zookeeper::setDebugLevel — Sets the debugging level for the library

説明

public static Zookeeper::setDebugLevel(int $logLevel): bool

パラメータ

logLevel

ZooKeeper log level constants.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to set debug level.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

例

例1 Zookeeper::setDebugLevel() example

Set debugl level.

<?php
$r = Zookeeper::setDebugLevel(Zookeeper::LOG_LEVEL_WARN);
if ($r)
echo 'SUCCESS';
else
echo 'ERR';
?>
?>

上の例の出力は以下となります。

SUCCESS

参考

  • ZooKeeper Log Levels
  • ZookeeperException


Enable/disable quorum endpoint order randomization

  • ≪ Zookeeper::setDebugLevel
  • Zookeeper::setLogStream ≫
  • PHP Manual
  • Zookeeper
  • Enable/disable quorum endpoint order randomization

Zookeeper::setDeterministicConnOrder

(PECL zookeeper >= 0.1.0)

Zookeeper::setDeterministicConnOrder — Enable/disable quorum endpoint order randomization

説明

public static Zookeeper::setDeterministicConnOrder(bool $yesOrNo): bool

If passed a true value, will make the client connect to quorum peers in the order as specified in the zookeeper_init() call. A false value causes zookeeper_init() to permute the peer endpoints which is good for more even client connection distribution among the quorum peers. ZooKeeper C Client uses false by default.

パラメータ

yesOrNo

Disable/enable quorum endpoint order randomization.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::__construct() - Create a handle to used communicate with zookeeper
  • Zookeeper::connect() - Create a handle to used communicate with zookeeper
  • ZookeeperException


Sets the stream to be used by the library for logging

  • ≪ Zookeeper::setDeterministicConnOrder
  • Zookeeper::setWatcher ≫
  • PHP Manual
  • Zookeeper
  • Sets the stream to be used by the library for logging

Zookeeper::setLogStream

(PECL zookeeper >= 0.1.0)

Zookeeper::setLogStream — Sets the stream to be used by the library for logging

説明

public Zookeeper::setLogStream(resource $stream): bool

The zookeeper library uses stderr as its default log stream. Application must make sure the stream is writable. Passing in NULL resets the stream to its default value (stderr).

パラメータ

stream

The stream to be used by the library for logging.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or operation fails.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::setDebugLevel() - Sets the debugging level for the library
  • ZookeeperException


Set a watcher function

  • ≪ Zookeeper::setLogStream
  • ZookeeperConfig ≫
  • PHP Manual
  • Zookeeper
  • Set a watcher function

Zookeeper::setWatcher

(PECL zookeeper >= 0.1.0)

Zookeeper::setWatcher — Set a watcher function

説明

public Zookeeper::setWatcher(callable $watcher_cb): bool

パラメータ

watcher_cb

A watch will be set at the server to notify the client if the node changes.

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

This method emits PHP error/warning when parameters count or types are wrong or fail to set watcher.

警告

Since version 0.3.0, this method emits ZookeeperException and it's derivatives.

参考

  • Zookeeper::exists() - Checks the existence of a node in zookeeper synchronously
  • Zookeeper::get() - Gets the data associated with a node synchronously
  • ZookeeperException


The ZookeeperConfig class

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

はじめに

The ZooKeeper Config handling class.

クラス概要

class ZookeeperConfig {
/* メソッド */
public add(string $members, int $version = -1, array &$stat = null): void
public get(callable $watcher_cb = null, array &$stat = null): string
public remove(string $id_list, int $version = -1, array &$stat = null): void
public set(string $members, int $version = -1, array &$stat = null): void
}

目次

  • ZookeeperConfig::add — Add servers to the ensemble
  • ZookeeperConfig::get — Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::remove — Remove servers from the ensemble
  • ZookeeperConfig::set — Change ZK cluster ensemble membership and roles of ensemble peers


Add servers to the ensemble

  • ≪ ZookeeperConfig
  • ZookeeperConfig::get ≫
  • PHP Manual
  • ZookeeperConfig
  • Add servers to the ensemble

ZookeeperConfig::add

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::add — Add servers to the ensemble

説明

public ZookeeperConfig::add(string $members, int $version = -1, array &$stat = null): void

パラメータ

members

Comma separated list of servers to be added to the ensemble. Each has a configuration line for a server to be added (as would appear in a configuration file), only for maj. quorums.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

戻り値

値を返しません。

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to save value to node.

例

例1 ZookeeperConfig::add() example

Add members.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->addAuth('digest', 'timandes:timandes');
$zkConfig = $client->getConfig();
$zkConfig->set("server.1=localhost:2888:3888:participant;0.0.0.0:2181");
$zkConfig->add("server.2=localhost:2889:3889:participant;0.0.0.0:2182");
$r = $zkConfig->get();
if ($r)
echo $r;
else
echo 'ERR';
?>

上の例の出力は以下となります。

server.1=localhost:2888:3888:participant;0.0.0.0:2181
server.2=localhost:2889:3889:participant;0.0.0.0:2182
version=0xca01e881a2

参考

  • ZookeeperConfig::get() - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::set() - Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperConfig::remove() - Remove servers from the ensemble
  • ZookeeperException


Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously

  • ≪ ZookeeperConfig::add
  • ZookeeperConfig::remove ≫
  • PHP Manual
  • ZookeeperConfig
  • Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously

ZookeeperConfig::get

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::get — Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously

説明

public ZookeeperConfig::get(callable $watcher_cb = null, array &$stat = null): string

パラメータ

watcher_cb

If nonzero, a watch will be set at the server to notify the client if the node changes.

stat

If not NULL, will hold the value of stat for the path on return.

戻り値

Returns the configuration string on success, and false on failure.

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to get configuration.

例

例1 ZookeeperConfig::get() example

Get configuration.

<?php
$zk = new Zookeeper();
$zk->connect('localhost:2181');
$zk->addAuth('digest', 'timandes:timandes');
$zkConfig = $zk->getConfig();
$r = $zkConfig->get();
if ($r)
echo $r;
else
echo 'ERR';
?>

上の例の出力は以下となります。

server.1=localhost:2888:3888:participant;0.0.0.0:2181
version=0xca01e881a2

参考

  • ZookeeperConfig::set() - Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperConfig::add() - Add servers to the ensemble
  • ZookeeperConfig::remove() - Remove servers from the ensemble
  • ZookeeperException


Remove servers from the ensemble

  • ≪ ZookeeperConfig::get
  • ZookeeperConfig::set ≫
  • PHP Manual
  • ZookeeperConfig
  • Remove servers from the ensemble

ZookeeperConfig::remove

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::remove — Remove servers from the ensemble

説明

public ZookeeperConfig::remove(string $id_list, int $version = -1, array &$stat = null): void

パラメータ

id_list

Comma separated list of server IDs to be removed from the ensemble. Each has an id of a server to be removed, only for maj. quorums.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

戻り値

値を返しません。

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to save value to node.

例

例1 ZookeeperConfig::remove() example

Remove members.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->addAuth('digest', 'timandes:timandes');
$zkConfig = $client->getConfig();
$zkConfig->set("server.1=localhost:2888:3888:participant;0.0.0.0:2181,server.2=localhost:2889:3889:participant;0.0.0.0:2182");
$zkConfig->remove("2");
echo $zkConfig->get();
if ($r)
echo $r;
else
echo 'ERR';
?>

上の例の出力は以下となります。

server.1=localhost:2888:3888:participant;0.0.0.0:2181
version=0xca01e881a2

参考

  • ZookeeperConfig::get() - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::add() - Add servers to the ensemble
  • ZookeeperConfig::set() - Change ZK cluster ensemble membership and roles of ensemble peers
  • ZookeeperException


Change ZK cluster ensemble membership and roles of ensemble peers

  • ≪ ZookeeperConfig::remove
  • ZookeeperException ≫
  • PHP Manual
  • ZookeeperConfig
  • Change ZK cluster ensemble membership and roles of ensemble peers

ZookeeperConfig::set

(PECL zookeeper >= 0.6.0, ZooKeeper >= 3.5.0)

ZookeeperConfig::set — Change ZK cluster ensemble membership and roles of ensemble peers

説明

public ZookeeperConfig::set(string $members, int $version = -1, array &$stat = null): void

パラメータ

members

Comma separated list of new membership (e.g., contents of a membership configuration file) - for use only with a non-incremental reconfiguration.

version

The expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.

stat

If not NULL, will hold the value of stat for the path on return.

戻り値

値を返しません。

エラー / 例外

This method emits ZookeeperException and it's derivatives when parameters count or types are wrong or fail to save value to node.

例

例1 ZookeeperConfig::set() example

Reconfig.

<?php
$client = new Zookeeper();
$client->connect('localhost:2181');
$client->addAuth('digest', 'timandes:timandes');
$zkConfig = $client->getConfig();
$zkConfig->set("server.1=localhost:2888:3888:participant;0.0.0.0:2181");
?>

参考

  • ZookeeperConfig::get() - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
  • ZookeeperConfig::add() - Add servers to the ensemble
  • ZookeeperConfig::remove() - Remove servers from the ensemble
  • ZookeeperException


The ZookeeperException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper exception handling class.

クラス概要

class ZookeeperException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The ZookeeperAuthenticationException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper authentication exception handling class.

クラス概要

class ZookeeperAuthenticationException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The ZookeeperConnectionException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper connection exception handling class.

クラス概要

class ZookeeperConnectionException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The ZookeeperMarshallingException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper exception (while marshalling or unmarshalling data) handling class.

クラス概要

class ZookeeperMarshallingException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The ZookeeperNoNodeException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper exception (when node does not exist) handling class.

クラス概要

class ZookeeperNoNodeException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The ZookeeperOperationTimeoutException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper operation timeout exception handling class.

クラス概要

class ZookeeperOperationTimeoutException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The ZookeeperSessionException class

(PECL zookeeper >= 0.3.0)

はじめに

The ZooKeeper session exception handling class.

クラス概要

class ZookeeperSessionException extends ZookeeperException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


検索エンジン用の拡張モジュール

  • Solr — Apache Solr
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Solr 関数
    • 例
    • SolrUtils — SolrUtils クラス
    • SolrInputDocument — SolrInputDocument クラス
    • SolrDocument — The SolrDocument class
    • SolrDocumentField — SolrDocumentField クラス
    • SolrObject — SolrObject クラス
    • SolrClient — The SolrClient class
    • SolrResponse — SolrResponse クラス
    • SolrQueryResponse — SolrQueryResponse クラス
    • SolrUpdateResponse — SolrUpdateResponse クラス
    • SolrPingResponse — SolrPingResponse クラス
    • SolrGenericResponse — SolrGenericResponse クラス
    • SolrParams — SolrParams クラス
    • SolrModifiableParams — SolrModifiableParams クラス
    • SolrQuery — The SolrQuery class
    • SolrDisMaxQuery — The SolrDisMaxQuery class
    • SolrCollapseFunction — The SolrCollapseFunction class
    • SolrException — SolrException クラス
    • SolrClientException — SolrClientException クラス
    • SolrServerException — SolrServerException クラス
    • SolrIllegalArgumentException — SolrIllegalArgumentException クラス
    • SolrIllegalOperationException — SolrIllegalOperationException クラス
    • SolrMissingMandatoryParameterException — The SolrMissingMandatoryParameterException class


Apache Solr

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • Solr 関数
    • solr_get_version — Apache Solr 拡張モジュールの現行バージョンを返す
  • 例
  • SolrUtils — SolrUtils クラス
    • SolrUtils::digestXmlResponse — Parses an response XML string into a SolrObject
    • SolrUtils::escapeQueryChars — Escapes a lucene query string
    • SolrUtils::getSolrVersion — Solr 拡張モジュールの現行バージョンを返す
    • SolrUtils::queryPhrase — Prepares a phrase from an unescaped lucene string
  • SolrInputDocument — SolrInputDocument クラス
    • SolrInputDocument::addChildDocument — Adds a child document for block indexing
    • SolrInputDocument::addChildDocuments — Adds an array of child documents
    • SolrInputDocument::addField — 文書にフィールドを追加
    • SolrInputDocument::clear — 入力した文書をリセット
    • SolrInputDocument::__clone — SolrDocument のコピーを作成
    • SolrInputDocument::__construct — コンストラクタ
    • SolrInputDocument::deleteField — 文書からフィールドを除去
    • SolrInputDocument::__destruct — デストラクタ
    • SolrInputDocument::fieldExists — フィールドが存在するかチェック
    • SolrInputDocument::getBoost — 文書に対する現行の boost 値を取得
    • SolrInputDocument::getChildDocuments — Returns an array of child documents (SolrInputDocument)
    • SolrInputDocument::getChildDocumentsCount — Returns the number of child documents
    • SolrInputDocument::getField — 名前でフィールドを取得
    • SolrInputDocument::getFieldBoost — 特定のフィールドに対する boost 値を取得
    • SolrInputDocument::getFieldCount — 文書内のフィールド数を返す
    • SolrInputDocument::getFieldNames — 文書内のフィールドを全て含む配列を返す
    • SolrInputDocument::hasChildDocuments — Returns true if the document has any child documents
    • SolrInputDocument::merge — Merges one input document into another
    • SolrInputDocument::reset — SolrInputDocument::clear のエイリアス
    • SolrInputDocument::setBoost — この文書に対する boost 値を設定
    • SolrInputDocument::setFieldBoost — フィールドに対するインデキシング時間の boost 値を設定
    • SolrInputDocument::sort — Sorts the fields within the document
    • SolrInputDocument::toArray — 入力した文書の配列表現を返す
  • SolrDocument — The SolrDocument class
    • SolrDocument::addField — 文書にフィールドを追加
    • SolrDocument::clear — Drops all the fields in the document
    • SolrDocument::__clone — SolrDocument オブジェクトのコピーを作成
    • SolrDocument::__construct — コンストラクタ
    • SolrDocument::current — 現行のフィールドを取得
    • SolrDocument::deleteField — 文書からフィールドを除去
    • SolrDocument::__destruct — デストラクタ
    • SolrDocument::fieldExists — Checks if a field exists in the document
    • SolrDocument::__get — プロパティとしてフィールドにアクセス
    • SolrDocument::getChildDocuments — Returns an array of child documents (SolrDocument)
    • SolrDocument::getChildDocumentsCount — Returns the number of child documents
    • SolrDocument::getField — 名前でフィールドを取得
    • SolrDocument::getFieldCount — この文書内のフィールド数を返す
    • SolrDocument::getFieldNames — 文書内のフィールド名の配列を返す
    • SolrDocument::getInputDocument — Returns a SolrInputDocument equivalent of the object
    • SolrDocument::hasChildDocuments — Checks whether the document has any child documents
    • SolrDocument::__isset — フィールドが存在するかチェック
    • SolrDocument::key — 現行のキーを返す
    • SolrDocument::merge — Merges source to the current SolrDocument
    • SolrDocument::next — 内部ポインタを次のフィールドに移動
    • SolrDocument::offsetExists — 特定のフィールドが存在するかどうかチェック
    • SolrDocument::offsetGet — フィールドを取得
    • SolrDocument::offsetSet — 文書にフィールドを追加
    • SolrDocument::offsetUnset — フィールドを除去
    • SolrDocument::reset — SolrDocument::clear のエイリアス
    • SolrDocument::rewind — 内部ポインタを先頭にリセット
    • SolrDocument::serialize — カスタムのシリアライズで使われます
    • SolrDocument::__set — Adds another field to the document
    • SolrDocument::sort — Sorts the fields in the document
    • SolrDocument::toArray — 文書の配列表現を返す
    • SolrDocument::unserialize — Custom serialization of SolrDocument objects
    • SolrDocument::__unset — 文書からフィールドを除去
    • SolrDocument::valid — Checks if the current position internally is still valid
  • SolrDocumentField — SolrDocumentField クラス
    • SolrDocumentField::__construct — コンストラクタ
    • SolrDocumentField::__destruct — デストラクタ
  • SolrObject — SolrObject クラス
    • SolrObject::__construct — Solr オブジェクトを生成
    • SolrObject::__destruct — デストラクタ
    • SolrObject::getPropertyNames — 全てのプロパティ名の配列を返す
    • SolrObject::offsetExists — プロパティが存在するかチェック
    • SolrObject::offsetGet — プロパティを取得するために使用される
    • SolrObject::offsetSet — プロパティに対して値を設定
    • SolrObject::offsetUnset — プロパティに対して値の設定を解除
  • SolrClient — The SolrClient class
    • SolrClient::addDocument — Adds a document to the index
    • SolrClient::addDocuments — Adds a collection of SolrInputDocument instances to the index
    • SolrClient::commit — Finalizes all add/deletes made to the index
    • SolrClient::__construct — Constructor for the SolrClient object
    • SolrClient::deleteById — Delete by Id
    • SolrClient::deleteByIds — Deletes by Ids
    • SolrClient::deleteByQueries — Removes all documents matching any of the queries
    • SolrClient::deleteByQuery — Deletes all documents matching the given query
    • SolrClient::__destruct — SolrClient に対するデストラクタ
    • SolrClient::getById — Get Document By Id. Utilizes Solr Realtime Get (RTG)
    • SolrClient::getByIds — Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)
    • SolrClient::getDebug — Returns the debug data for the last connection attempt
    • SolrClient::getOptions — Returns the client options set internally
    • SolrClient::optimize — Defragments the index
    • SolrClient::ping — Checks if Solr server is still up
    • SolrClient::query — Sends a query to the server
    • SolrClient::request — Sends a raw update request
    • SolrClient::rollback — Rollbacks all add/deletes made to the index since the last commit
    • SolrClient::setResponseWriter — Sets the response writer used to prepare the response from Solr
    • SolrClient::setServlet — Changes the specified servlet type to a new value
    • SolrClient::system — Retrieve Solr Server information
    • SolrClient::threads — スレッドの状態をチェック
  • SolrResponse — SolrResponse クラス
    • SolrResponse::getDigestedResponse — シリアライズされた PHP データとして XML レスポンスを返す
    • SolrResponse::getHttpStatus — レスポンスの HTTP ステータスを返す
    • SolrResponse::getHttpStatusMessage — HTTP ステータスに関する詳細を返す
    • SolrResponse::getRawRequest — Solr サーバーに送られた生のリクエストを返す
    • SolrResponse::getRawRequestHeaders — Solr サーバーに送られた生のリクエストヘッダを返す
    • SolrResponse::getRawResponse — Solr サーバーからの生のレスポンスを返す
    • SolrResponse::getRawResponseHeaders — Solr サーバーからの生のレスポンスヘッダを返す
    • SolrResponse::getRequestUrl — リクエストが送られた完全な URL を返す
    • SolrResponse::getResponse — サーバーからの XML レスポンスを表現する SolrObject を返す
    • SolrResponse::setParseMode — パースモードを設定
    • SolrResponse::success — リクエストが成功したか
  • SolrQueryResponse — SolrQueryResponse クラス
    • SolrQueryResponse::__construct — コンストラクタ
    • SolrQueryResponse::__destruct — デストラクタ
  • SolrUpdateResponse — SolrUpdateResponse クラス
    • SolrUpdateResponse::__construct — コンストラクタ
    • SolrUpdateResponse::__destruct — デストラクタ
  • SolrPingResponse — SolrPingResponse クラス
    • SolrPingResponse::__construct — コンストラクタ
    • SolrPingResponse::__destruct — デストラクタ
    • SolrPingResponse::getResponse — サーバーからのレスポンスを返す
  • SolrGenericResponse — SolrGenericResponse クラス
    • SolrGenericResponse::__construct — コンストラクタ
    • SolrGenericResponse::__destruct — デストラクタ
  • SolrParams — SolrParams クラス
    • SolrParams::add — SolrParams::addParam のエイリアス
    • SolrParams::addParam — オブジェクトにパラメータを追加
    • SolrParams::get — SolrParams::getParam のエイリアス
    • SolrParams::getParam — パラメータ値を返す
    • SolrParams::getParams — URL エンコードされていないパラメータの配列を返す
    • SolrParams::getPreparedParams — URL エンコードされたパラメータの配列を返す
    • SolrParams::serialize — カスタムのシリアライズで使われます
    • SolrParams::set — SolrParams::setParam のエイリアス
    • SolrParams::setParam — パラメータを指定された値に設定
    • SolrParams::toString — オブジェクト内の名前と値のペアのパラメータを全て返します
    • SolrParams::unserialize — カスタムのシリアライズで使われます
  • SolrModifiableParams — SolrModifiableParams クラス
    • SolrModifiableParams::__construct — コンストラクタ
    • SolrModifiableParams::__destruct — デストラクタ
  • SolrQuery — The SolrQuery class
    • SolrQuery::addExpandFilterQuery — Overrides main filter query, determines which documents to include in the main group
    • SolrQuery::addExpandSortField — Orders the documents within the expanded groups (expand.sort parameter)
    • SolrQuery::addFacetDateField — Maps to facet.date
    • SolrQuery::addFacetDateOther — Adds another facet.date.other parameter
    • SolrQuery::addFacetField — Adds another field to the facet
    • SolrQuery::addFacetQuery — Adds a facet query
    • SolrQuery::addField — Specifies which fields to return in the result
    • SolrQuery::addFilterQuery — Specifies a filter query
    • SolrQuery::addGroupField — Add a field to be used to group results
    • SolrQuery::addGroupFunction — Allows grouping results based on the unique values of a function query (group.func parameter)
    • SolrQuery::addGroupQuery — Allows grouping of documents that match the given query
    • SolrQuery::addGroupSortField — Add a group sort field (group.sort parameter)
    • SolrQuery::addHighlightField — Maps to hl.fl
    • SolrQuery::addMltField — Sets a field to use for similarity
    • SolrQuery::addMltQueryField — Maps to mlt.qf
    • SolrQuery::addSortField — Used to control how the results should be sorted
    • SolrQuery::addStatsFacet — Requests a return of sub results for values within the given facet
    • SolrQuery::addStatsField — Maps to stats.field parameter
    • SolrQuery::collapse — Collapses the result set to a single document per group
    • SolrQuery::__construct — コンストラクタ
    • SolrQuery::__destruct — デストラクタ
    • SolrQuery::getExpand — Returns true if group expanding is enabled
    • SolrQuery::getExpandFilterQueries — Returns the expand filter queries
    • SolrQuery::getExpandQuery — Returns the expand query expand.q parameter
    • SolrQuery::getExpandRows — Returns The number of rows to display in each group (expand.rows)
    • SolrQuery::getExpandSortFields — Returns an array of fields
    • SolrQuery::getFacet — Returns the value of the facet parameter
    • SolrQuery::getFacetDateEnd — Returns the value for the facet.date.end parameter
    • SolrQuery::getFacetDateFields — Returns all the facet.date fields
    • SolrQuery::getFacetDateGap — Returns the value of the facet.date.gap parameter
    • SolrQuery::getFacetDateHardEnd — Returns the value of the facet.date.hardend parameter
    • SolrQuery::getFacetDateOther — Returns the value for the facet.date.other parameter
    • SolrQuery::getFacetDateStart — Returns the lower bound for the first date range for all date faceting on this field
    • SolrQuery::getFacetFields — Returns all the facet fields
    • SolrQuery::getFacetLimit — Returns the maximum number of constraint counts that should be returned for the facet fields
    • SolrQuery::getFacetMethod — Returns the value of the facet.method parameter
    • SolrQuery::getFacetMinCount — Returns the minimum counts for facet fields should be included in the response
    • SolrQuery::getFacetMissing — Returns the current state of the facet.missing parameter
    • SolrQuery::getFacetOffset — Returns an offset into the list of constraints to be used for pagination
    • SolrQuery::getFacetPrefix — Returns the facet prefix
    • SolrQuery::getFacetQueries — Returns all the facet queries
    • SolrQuery::getFacetSort — Returns the facet sort type
    • SolrQuery::getFields — Returns the list of fields that will be returned in the response
    • SolrQuery::getFilterQueries — Returns an array of filter queries
    • SolrQuery::getGroup — Returns true if grouping is enabled
    • SolrQuery::getGroupCachePercent — Returns group cache percent value
    • SolrQuery::getGroupFacet — Returns the group.facet parameter value
    • SolrQuery::getGroupFields — Returns group fields (group.field parameter values)
    • SolrQuery::getGroupFormat — Returns the group.format value
    • SolrQuery::getGroupFunctions — Returns group functions (group.func parameter values)
    • SolrQuery::getGroupLimit — Returns the group.limit value
    • SolrQuery::getGroupMain — Returns the group.main value
    • SolrQuery::getGroupNGroups — Returns the group.ngroups value
    • SolrQuery::getGroupOffset — Returns the group.offset value
    • SolrQuery::getGroupQueries — Returns all the group.query parameter values
    • SolrQuery::getGroupSortFields — Returns the group.sort value
    • SolrQuery::getGroupTruncate — Returns the group.truncate value
    • SolrQuery::getHighlight — Returns the state of the hl parameter
    • SolrQuery::getHighlightAlternateField — Returns the highlight field to use as backup or default
    • SolrQuery::getHighlightFields — Returns all the fields that Solr should generate highlighted snippets for
    • SolrQuery::getHighlightFormatter — Returns the formatter for the highlighted output
    • SolrQuery::getHighlightFragmenter — Returns the text snippet generator for highlighted text
    • SolrQuery::getHighlightFragsize — Returns the number of characters of fragments to consider for highlighting
    • SolrQuery::getHighlightHighlightMultiTerm — Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries
    • SolrQuery::getHighlightMaxAlternateFieldLength — Returns the maximum number of characters of the field to return
    • SolrQuery::getHighlightMaxAnalyzedChars — Returns the maximum number of characters into a document to look for suitable snippets
    • SolrQuery::getHighlightMergeContiguous — Returns whether or not the collapse contiguous fragments into a single fragment
    • SolrQuery::getHighlightRegexMaxAnalyzedChars — Returns the maximum number of characters from a field when using the regex fragmenter
    • SolrQuery::getHighlightRegexPattern — Returns the regular expression for fragmenting
    • SolrQuery::getHighlightRegexSlop — Returns the deviation factor from the ideal fragment size
    • SolrQuery::getHighlightRequireFieldMatch — Returns if a field will only be highlighted if the query matched in this particular field
    • SolrQuery::getHighlightSimplePost — Returns the text which appears after a highlighted term
    • SolrQuery::getHighlightSimplePre — Returns the text which appears before a highlighted term
    • SolrQuery::getHighlightSnippets — Returns the maximum number of highlighted snippets to generate per field
    • SolrQuery::getHighlightUsePhraseHighlighter — Returns the state of the hl.usePhraseHighlighter parameter
    • SolrQuery::getMlt — Returns whether or not MoreLikeThis results should be enabled
    • SolrQuery::getMltBoost — Returns whether or not the query will be boosted by the interesting term relevance
    • SolrQuery::getMltCount — Returns the number of similar documents to return for each result
    • SolrQuery::getMltFields — Returns all the fields to use for similarity
    • SolrQuery::getMltMaxNumQueryTerms — Returns the maximum number of query terms that will be included in any generated query
    • SolrQuery::getMltMaxNumTokens — Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support
    • SolrQuery::getMltMaxWordLength — Returns the maximum word length above which words will be ignored
    • SolrQuery::getMltMinDocFrequency — Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs
    • SolrQuery::getMltMinTermFrequency — Returns the frequency below which terms will be ignored in the source document
    • SolrQuery::getMltMinWordLength — Returns the minimum word length below which words will be ignored
    • SolrQuery::getMltQueryFields — Returns the query fields and their boosts
    • SolrQuery::getQuery — 主なクエリーを返す
    • SolrQuery::getRows — Returns the maximum number of documents
    • SolrQuery::getSortFields — Returns all the sort fields
    • SolrQuery::getStart — Returns the offset in the complete result set
    • SolrQuery::getStats — Returns whether or not stats is enabled
    • SolrQuery::getStatsFacets — Returns all the stats facets that were set
    • SolrQuery::getStatsFields — Returns all the statistics fields
    • SolrQuery::getTerms — Returns whether or not the TermsComponent is enabled
    • SolrQuery::getTermsField — Returns the field from which the terms are retrieved
    • SolrQuery::getTermsIncludeLowerBound — Returns whether or not to include the lower bound in the result set
    • SolrQuery::getTermsIncludeUpperBound — Returns whether or not to include the upper bound term in the result set
    • SolrQuery::getTermsLimit — Returns the maximum number of terms Solr should return
    • SolrQuery::getTermsLowerBound — Returns the term to start at
    • SolrQuery::getTermsMaxCount — Returns the maximum document frequency
    • SolrQuery::getTermsMinCount — Returns the minimum document frequency to return in order to be included
    • SolrQuery::getTermsPrefix — Returns the term prefix
    • SolrQuery::getTermsReturnRaw — Whether or not to return raw characters
    • SolrQuery::getTermsSort — Returns an integer indicating how terms are sorted
    • SolrQuery::getTermsUpperBound — Returns the term to stop at
    • SolrQuery::getTimeAllowed — Returns the time in milliseconds allowed for the query to finish
    • SolrQuery::removeExpandFilterQuery — Removes an expand filter query
    • SolrQuery::removeExpandSortField — Removes an expand sort field from the expand.sort parameter
    • SolrQuery::removeFacetDateField — Removes one of the facet date fields
    • SolrQuery::removeFacetDateOther — Removes one of the facet.date.other parameters
    • SolrQuery::removeFacetField — Removes one of the facet.date parameters
    • SolrQuery::removeFacetQuery — Removes one of the facet.query parameters
    • SolrQuery::removeField — Removes a field from the list of fields
    • SolrQuery::removeFilterQuery — Removes a filter query
    • SolrQuery::removeHighlightField — Removes one of the fields used for highlighting
    • SolrQuery::removeMltField — Removes one of the moreLikeThis fields
    • SolrQuery::removeMltQueryField — Removes one of the moreLikeThis query fields
    • SolrQuery::removeSortField — Removes one of the sort fields
    • SolrQuery::removeStatsFacet — Removes one of the stats.facet parameters
    • SolrQuery::removeStatsField — Removes one of the stats.field parameters
    • SolrQuery::setEchoHandler — Toggles the echoHandler parameter
    • SolrQuery::setEchoParams — Determines what kind of parameters to include in the response
    • SolrQuery::setExpand — Enables/Disables the Expand Component
    • SolrQuery::setExpandQuery — Sets the expand.q parameter
    • SolrQuery::setExpandRows — Sets the number of rows to display in each group (expand.rows). Server Default 5
    • SolrQuery::setExplainOther — Sets the explainOther common query parameter
    • SolrQuery::setFacet — Maps to the facet parameter. Enables or disables facetting
    • SolrQuery::setFacetDateEnd — Maps to facet.date.end
    • SolrQuery::setFacetDateGap — Maps to facet.date.gap
    • SolrQuery::setFacetDateHardEnd — Maps to facet.date.hardend
    • SolrQuery::setFacetDateStart — Maps to facet.date.start
    • SolrQuery::setFacetEnumCacheMinDefaultFrequency — Sets the minimum document frequency used for determining term count
    • SolrQuery::setFacetLimit — Maps to facet.limit
    • SolrQuery::setFacetMethod — Specifies the type of algorithm to use when faceting a field
    • SolrQuery::setFacetMinCount — Maps to facet.mincount
    • SolrQuery::setFacetMissing — Maps to facet.missing
    • SolrQuery::setFacetOffset — Sets the offset into the list of constraints to allow for pagination
    • SolrQuery::setFacetPrefix — Specifies a string prefix with which to limits the terms on which to facet
    • SolrQuery::setFacetSort — Determines the ordering of the facet field constraints
    • SolrQuery::setGroup — Enable/Disable result grouping (group parameter)
    • SolrQuery::setGroupCachePercent — Enables caching for result grouping
    • SolrQuery::setGroupFacet — Sets group.facet parameter
    • SolrQuery::setGroupFormat — Sets the group format, result structure (group.format parameter)
    • SolrQuery::setGroupLimit — Specifies the number of results to return for each group. The server default value is 1
    • SolrQuery::setGroupMain — If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
    • SolrQuery::setGroupNGroups — If true, Solr includes the number of groups that have matched the query in the results
    • SolrQuery::setGroupOffset — Sets the group.offset parameter
    • SolrQuery::setGroupTruncate — If true, facet counts are based on the most relevant document of each group matching the query
    • SolrQuery::setHighlight — Enables or disables highlighting
    • SolrQuery::setHighlightAlternateField — Specifies the backup field to use
    • SolrQuery::setHighlightFormatter — Specify a formatter for the highlight output
    • SolrQuery::setHighlightFragmenter — Sets a text snippet generator for highlighted text
    • SolrQuery::setHighlightFragsize — The size of fragments to consider for highlighting
    • SolrQuery::setHighlightHighlightMultiTerm — Use SpanScorer to highlight phrase terms
    • SolrQuery::setHighlightMaxAlternateFieldLength — Sets the maximum number of characters of the field to return
    • SolrQuery::setHighlightMaxAnalyzedChars — Specifies the number of characters into a document to look for suitable snippets
    • SolrQuery::setHighlightMergeContiguous — Whether or not to collapse contiguous fragments into a single fragment
    • SolrQuery::setHighlightRegexMaxAnalyzedChars — Specify the maximum number of characters to analyze
    • SolrQuery::setHighlightRegexPattern — Specify the regular expression for fragmenting
    • SolrQuery::setHighlightRegexSlop — Sets the factor by which the regex fragmenter can stray from the ideal fragment size
    • SolrQuery::setHighlightRequireFieldMatch — Require field matching during highlighting
    • SolrQuery::setHighlightSimplePost — Sets the text which appears after a highlighted term
    • SolrQuery::setHighlightSimplePre — Sets the text which appears before a highlighted term
    • SolrQuery::setHighlightSnippets — Sets the maximum number of highlighted snippets to generate per field
    • SolrQuery::setHighlightUsePhraseHighlighter — Whether to highlight phrase terms only when they appear within the query phrase
    • SolrQuery::setMlt — Enables or disables moreLikeThis
    • SolrQuery::setMltBoost — Set if the query will be boosted by the interesting term relevance
    • SolrQuery::setMltCount — Set the number of similar documents to return for each result
    • SolrQuery::setMltMaxNumQueryTerms — Sets the maximum number of query terms included
    • SolrQuery::setMltMaxNumTokens — Specifies the maximum number of tokens to parse
    • SolrQuery::setMltMaxWordLength — Sets the maximum word length
    • SolrQuery::setMltMinDocFrequency — Sets the mltMinDoc frequency
    • SolrQuery::setMltMinTermFrequency — Sets the frequency below which terms will be ignored in the source docs
    • SolrQuery::setMltMinWordLength — Sets the minimum word length
    • SolrQuery::setOmitHeader — Exclude the header from the returned results
    • SolrQuery::setQuery — 検索クエリーを設定
    • SolrQuery::setRows — Specifies the maximum number of rows to return in the result
    • SolrQuery::setShowDebugInfo — Flag to show debug information
    • SolrQuery::setStart — Specifies the number of rows to skip
    • SolrQuery::setStats — Enables or disables the Stats component
    • SolrQuery::setTerms — Enables or disables the TermsComponent
    • SolrQuery::setTermsField — Sets the name of the field to get the Terms from
    • SolrQuery::setTermsIncludeLowerBound — Include the lower bound term in the result set
    • SolrQuery::setTermsIncludeUpperBound — Include the upper bound term in the result set
    • SolrQuery::setTermsLimit — Sets the maximum number of terms to return
    • SolrQuery::setTermsLowerBound — Specifies the Term to start from
    • SolrQuery::setTermsMaxCount — Sets the maximum document frequency
    • SolrQuery::setTermsMinCount — Sets the minimum document frequency
    • SolrQuery::setTermsPrefix — Restrict matches to terms that start with the prefix
    • SolrQuery::setTermsReturnRaw — Return the raw characters of the indexed term
    • SolrQuery::setTermsSort — Specifies how to sort the returned terms
    • SolrQuery::setTermsUpperBound — Sets the term to stop at
    • SolrQuery::setTimeAllowed — The time allowed for search to finish
  • SolrDisMaxQuery — The SolrDisMaxQuery class
    • SolrDisMaxQuery::addBigramPhraseField — Adds a Phrase Bigram Field (pf2 parameter)
    • SolrDisMaxQuery::addBoostQuery — Adds a boost query field with value and optional boost (bq parameter)
    • SolrDisMaxQuery::addPhraseField — Adds a Phrase Field (pf parameter)
    • SolrDisMaxQuery::addQueryField — Add a query field with optional boost (qf parameter)
    • SolrDisMaxQuery::addTrigramPhraseField — Adds a Trigram Phrase Field (pf3 parameter)
    • SolrDisMaxQuery::addUserField — Adds a field to User Fields Parameter (uf)
    • SolrDisMaxQuery::__construct — Class Constructor
    • SolrDisMaxQuery::removeBigramPhraseField — Removes phrase bigram field (pf2 parameter)
    • SolrDisMaxQuery::removeBoostQuery — Removes a boost query partial by field name (bq)
    • SolrDisMaxQuery::removePhraseField — Removes a Phrase Field (pf parameter)
    • SolrDisMaxQuery::removeQueryField — Removes a Query Field (qf parameter)
    • SolrDisMaxQuery::removeTrigramPhraseField — Removes a Trigram Phrase Field (pf3 parameter)
    • SolrDisMaxQuery::removeUserField — Removes a field from The User Fields Parameter (uf)
    • SolrDisMaxQuery::setBigramPhraseFields — Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
    • SolrDisMaxQuery::setBigramPhraseSlop — Sets Bigram Phrase Slop (ps2 parameter)
    • SolrDisMaxQuery::setBoostFunction — Sets a Boost Function (bf parameter)
    • SolrDisMaxQuery::setBoostQuery — Directly Sets Boost Query Parameter (bq)
    • SolrDisMaxQuery::setMinimumMatch — Set Minimum "Should" Match (mm)
    • SolrDisMaxQuery::setPhraseFields — Sets Phrase Fields and their boosts (and slops) using pf2 parameter
    • SolrDisMaxQuery::setPhraseSlop — Sets the default slop on phrase queries (ps parameter)
    • SolrDisMaxQuery::setQueryAlt — Set Query Alternate (q.alt parameter)
    • SolrDisMaxQuery::setQueryPhraseSlop — Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)
    • SolrDisMaxQuery::setTieBreaker — Sets Tie Breaker parameter (tie parameter)
    • SolrDisMaxQuery::setTrigramPhraseFields — Directly Sets Trigram Phrase Fields (pf3 parameter)
    • SolrDisMaxQuery::setTrigramPhraseSlop — Sets Trigram Phrase Slop (ps3 parameter)
    • SolrDisMaxQuery::setUserFields — Sets User Fields parameter (uf)
    • SolrDisMaxQuery::useDisMaxQueryParser — Switch QueryParser to be DisMax Query Parser
    • SolrDisMaxQuery::useEDisMaxQueryParser — Switch QueryParser to be EDisMax
  • SolrCollapseFunction — The SolrCollapseFunction class
    • SolrCollapseFunction::__construct — Constructor
    • SolrCollapseFunction::getField — Returns the field that is being collapsed on
    • SolrCollapseFunction::getHint — Returns collapse hint
    • SolrCollapseFunction::getMax — Returns max parameter
    • SolrCollapseFunction::getMin — Returns min parameter
    • SolrCollapseFunction::getNullPolicy — Returns null policy
    • SolrCollapseFunction::getSize — Returns size parameter
    • SolrCollapseFunction::setField — Sets the field to collapse on
    • SolrCollapseFunction::setHint — Sets collapse hint
    • SolrCollapseFunction::setMax — Selects the group heads by the max value of a numeric field or function query
    • SolrCollapseFunction::setMin — Sets the initial size of the collapse data structures when collapsing on a numeric field only
    • SolrCollapseFunction::setNullPolicy — Sets the NULL Policy
    • SolrCollapseFunction::setSize — Sets the initial size of the collapse data structures when collapsing on a numeric field only
    • SolrCollapseFunction::__toString — Returns a string representing the constructed collapse function
  • SolrException — SolrException クラス
    • SolrException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrClientException — SolrClientException クラス
    • SolrClientException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrServerException — SolrServerException クラス
    • SolrServerException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrIllegalArgumentException — SolrIllegalArgumentException クラス
    • SolrIllegalArgumentException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrIllegalOperationException — SolrIllegalOperationException クラス
    • SolrIllegalOperationException::getInternalInfo — 例外がスローされた際の内部情報を返す
  • SolrMissingMandatoryParameterException — The SolrMissingMandatoryParameterException class


はじめに

Solr 拡張モジュールにより、PHP で Apache Solr サーバーと効果的に通信できます。

Solr 拡張モジュールは、PHP 開発者が Solr サーバーのインスタンスと効果的に通信できるようにする、とても速くて軽量で、豊富な機能を持つライブラリです。

PECL 拡張モジュールのバージョン 1.x は、Apache Solr Server 1.3 から 3.x までをサポートします。

PECL 拡張モジュールのバージョン 2.x は、Apache Solr Server 4.0 以降をサポートします。

文書を追加したり、Solr サーバーに更新を行なったりする組み込みツールがあります。

文書検索時に高度なクエリをサーバーに構築できるようにするツールも含みます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Solr
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

Apache Solr 拡張モジュールを使うには、 libxml および curl 拡張モジュールも使える状態にしておく必要があります。

libxml2 2.6.31 以降が必要です。

libcurl 7.18.0 以降も必要です。

上記のライブラリのバージョンが必要です。コードをハックして何とかコンパイルしようとするのはおすすめしません。 きっとエラーが出て失敗するだろうし、そのデバッグも難しくなるでしょう。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/solr.

ヘルプやサポート用として、この拡張モジュール用の Google グループがあります。 » Apache Solr PHP Extension をごらんください。

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

注意:

Solr モジュールをデバッグモードでコンパイルするには、configure のときに --enable-solr-debug フラグを渡します。

手動でビルドする際には、curl および libxml のサポートを忘れずに含めましょう。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SOLR_MAJOR_VERSION (int)
SOLR_MINOR_VERSION (int)
SOLR_PATCH_VERSION (int)
SOLR_EXTENSION_VERSION (string)


  • ≪ 定義済み定数
  • solr_get_version ≫
  • PHP Manual
  • Solr
  • Solr 関数

Solr 関数

目次

  • solr_get_version — Apache Solr 拡張モジュールの現行バージョンを返す


Apache Solr 拡張モジュールの現行バージョンを返す

  • ≪ Solr 関数
  • 例 ≫
  • PHP Manual
  • Solr 関数
  • Apache Solr 拡張モジュールの現行バージョンを返す

solr_get_version

(PECL solr >= 0.9.1)

solr_get_version — Apache Solr 拡張モジュールの現行バージョンを返す

説明

solr_get_version(): string

この関数は、拡張モジュールの現行バージョンを文字列として返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時に文字列、失敗時に false を返します。

エラー / 例外

この関数はエラーや例外をスローしません。

例

例1 solr_get_version() の例

<?php

$solr_version = solr_get_version();

print $solr_version;

?>

上の例の出力は、 たとえば以下のようになります。

0.9.6

参考

  • SolrUtils::getSolrVersion() - Solr 拡張モジュールの現行バージョンを返す


例

PHP で Apache Solr 拡張モジュールを使用する方法の例

例1 ブートストラップ・ファイルの内容

<?php

/* Solr サーバーのドメイン名 */
define('SOLR_SERVER_HOSTNAME', 'solr.example.com');

/* セキュアなモードで動作するかどうか */
define('SOLR_SECURE', true);

/* 接続する HTTP ポート */
define('SOLR_SERVER_PORT', ((SOLR_SECURE) ? 8443 : 8983));

/* HTTP Basic 認証ユーザー名 */
define('SOLR_SERVER_USERNAME', 'admin');

/* HTTP Basic 認証パスワード */
define('SOLR_SERVER_PASSWORD', 'changeit');

/* HTTP 接続タイムアウト */
/* HTTP データ転送動作に許される、秒単位の最大時間。既定値は３０秒 */
define('SOLR_SERVER_TIMEOUT', 10);

/* PEM 形式のプライベートキーとプライベート証明書に対するファイル名（その順序で連結されます） */
define('SOLR_SSL_CERT', 'certs/combo.pem');

/* PEM 形式のプライベート証明書のみに対するファイル名 */
define('SOLR_SSL_CERT_ONLY', 'certs/solr.crt');

/* PEM 形式のプライベートキーに対するファイル名 */
define('SOLR_SSL_KEY', 'certs/solr.key');

/* PEM 形式のプライベートキー・ファイルに対するパスワード */
define('SOLR_SSL_KEYPASSWORD', 'StrongAndSecurePassword');

/* 同等であることを証明する、一つ以上の CA 証明書を持つファイル名 */
define('SOLR_SSL_CAINFO', 'certs/cacert.crt');

/* 同等であることを証明する、複数の CA 証明書があるディレクトリ名 */
define('SOLR_SSL_CAPATH', 'certs/');

?>

例2 インデックスに文書を追加

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$updateResponse = $client->addDocument($doc);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 446
        )

)

例3 ある文書を他の文書にマージ

<?php

include "bootstrap.php";

$doc = new SolrDocument();

$second_doc = new SolrDocument();

$doc->addField('id', 1123);

$doc->features = "PHP Client Side";
$doc->features = "Fast development cycles";

$doc['cat'] = 'Software';
$doc['cat'] = 'Custom Search';
$doc->cat = 'Information Technology';

$second_doc->addField('cat', 'Lucene Search');

$second_doc->merge($doc, true);

print_r($second_doc->toArray());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [document_boost] => 0
    [field_count] => 3
    [fields] => Array
        (
            [0] => SolrDocumentField Object
                (
                    [name] => cat
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => Software
                            [1] => Custom Search
                            [2] => Information Technology
                        )

                )

            [1] => SolrDocumentField Object
                (
                    [name] => id
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => 1123
                        )

                )

            [2] => SolrDocumentField Object
                (
                    [name] => features
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => PHP Client Side
                            [1] => Fast development cycles
                        )

                )

        )

)

例4 文書を検索 - SolrObject レスポンス

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('lucene');

$query->setStart(0);

$query->setRows(50);

$query->addField('cat')->addField('features')->addField('id')->addField('timestamp');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [wt] => xml
                    [rows] => 50
                    [start] => 0
                    [indent] => on
                    [q] => lucene
                    [fl] => cat,features,id,timestamp
                    [version] => 2.2
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 3
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [cat] => Array
                                (
                                    [0] => Software
                                    [1] => Lucene
                                )

                            [id] => 334456
                        )

                    [1] => SolrObject Object
                        (
                            [cat] => Array
                                (
                                    [0] => Software
                                    [1] => Lucene
                                )

                            [id] => 334455
                        )

                    [2] => SolrObject Object
                        (
                            [cat] => Array
                                (
                                    [0] => software
                                    [1] => search
                                )

                            [features] => Array
                                (
                                    [0] => Advanced Full-Text Search Capabilities using Lucene
                                    [1] => Optimized for High Volume Web Traffic
                                    [2] => Standards Based Open Interfaces - XML and HTTP
                                    [3] => Comprehensive HTML Administration Interfaces
                                    [4] => Scalability - Efficient Replication to other Solr Search Servers
                                    [5] => Flexible and Adaptable with XML configuration and Schema
                                    [6] => Good unicode support: hello (hello with an accent over the e)
                                )

                            [id] => SOLR1000
                            [timestamp] => 2009-09-04T20:38:55.906
                        )

                )

        )

)

例5 文書を検索 - SolrDocument レスポンス

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('lucene');

$query->setStart(0);

$query->setRows(50);

$query->addField('cat')->addField('features')->addField('id')->addField('timestamp');

$query_response = $client->query($query);

$query_response->setParseMode(SolrQueryResponse::PARSE_SOLR_DOC);

$response = $query_response->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [wt] => xml
                    [rows] => 50
                    [start] => 0
                    [indent] => on
                    [q] => lucene
                    [fl] => cat,features,id,timestamp
                    [version] => 2.2
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 3
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrDocument Object
                        (
                            [_hashtable_index:SolrDocument:private] => 19740
                        )

                    [1] => SolrDocument Object
                        (
                            [_hashtable_index:SolrDocument:private] => 25485
                        )

                    [2] => SolrDocument Object
                        (
                            [_hashtable_index:SolrDocument:private] => 25052
                        )

                )

        )

)

例6 簡単な TermsComponent 例 - 基本

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setTerms(true);

$query->setTermsField('cat');

$updateResponse = $client->query($query);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 2
        )

    [terms] => SolrObject Object
        (
            [cat] => SolrObject Object
                (
                    [electronics] => 14
                    [Lucene] => 4
                    [Software] => 4
                    [memory] => 3
                    [card] => 2
                    [connector] => 2
                    [drive] => 2
                    [graphics] => 2
                    [hard] => 2
                    [monitor] => 2
                )

        )

)

例7 簡単な TermsComponent 例 - 接頭辞を使用

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setTerms(true);

/* $prefix で始まる語だけを返す */
$prefix = 'c';

$query->setTermsField('cat')->setTermsPrefix($prefix);

$updateResponse = $client->query($query);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
        )

    [terms] => SolrObject Object
        (
            [cat] => SolrObject Object
                (
                    [card] => 2
                    [connector] => 2
                    [camera] => 1
                    [copier] => 1
                )

        )

)

例8 簡単な TermsComponent 例 - 最小の頻度を指定

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setTerms(true);

/* $prefix で始まる語だけを返す */
$prefix = 'c';

/* 2回以上の頻度の語だけを返す */
$min_frequency = 2;

$query->setTermsField('cat')->setTermsPrefix($prefix)->setTermsMinCount($min_frequency);

$updateResponse = $client->query($query);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 0
        )

    [terms] => SolrObject Object
        (
            [cat] => SolrObject Object
                (
                    [card] => 2
                    [connector] => 2
                )

        )

)

例9 簡単なファセット例

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetField('cat')->addFacetField('name')->setFacetMinCount(2);

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_fields;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [cat] => SolrObject Object
        (
            [electronics] => 14
            [memory] => 3
            [Lucene] => 2
            [Software] => 2
            [card] => 2
            [connector] => 2
            [drive] => 2
            [graphics] => 2
            [hard] => 2
            [monitor] => 2
            [search] => 2
            [software] => 2
        )

    [name] => SolrObject Object
        (
            [gb] => 6
            [1] => 3
            [184] => 3
            [2] => 3
            [3200] => 3
            [400] => 3
            [500] => 3
            [ddr] => 3
            [i] => 3
            [ipod] => 3
            [memori] => 3
            [pc] => 3
            [pin] => 3
            [pod] => 3
            [sdram] => 3
            [system] => 3
            [unbuff] => 3
            [canon] => 2
            [corsair] => 2
            [drive] => 2
            [hard] => 2
            [mb] => 2
            [n] => 2
            [power] => 2
            [retail] => 2
            [video] => 2
            [x] => 2
        )

)

例10 簡単なファセット例 - mincount を越える任意の項目と共に

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetField('cat')->addFacetField('name')->setFacetMinCount(2)->setFacetMinCount(4, 'name');

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_fields;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [cat] => SolrObject Object
        (
            [electronics] => 14
            [memory] => 3
            [Lucene] => 2
            [Software] => 2
            [card] => 2
            [connector] => 2
            [drive] => 2
            [graphics] => 2
            [hard] => 2
            [monitor] => 2
            [search] => 2
            [software] => 2
        )

    [name] => SolrObject Object
        (
            [gb] => 6
        )

)

例11 Facet Date の例

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetDateField('manufacturedate_dt');

$query->setFacetDateStart('2006-02-13T00:00:00Z');

$query->setFacetDateEnd('2012-02-13T00:00:00Z');

$query->setFacetDateGap('+1YEAR');

$query->setFacetDateHardEnd(1);

$query->addFacetDateOther('before');

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_dates;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [manufacturedate_dt] => SolrObject Object
        (
            [2006-02-13T00:00:00Z] => 9
            [2007-02-13T00:00:00Z] => 0
            [2008-02-13T00:00:00Z] => 0
            [2009-02-13T00:00:00Z] => 0
            [2010-02-13T00:00:00Z] => 0
            [2011-02-13T00:00:00Z] => 0
            [gap] => +1YEAR
            [start] => 2006-02-13T00:00:00Z
            [end] => 2012-02-13T00:00:00Z
            [before] => 2
        )

)

例12 SSL 対応サーバーに接続

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'timeout' => SOLR_SERVER_TIMEOUT,
'secure' => SOLR_SECURE,
'ssl_cert' => SOLR_SSL_CERT_ONLY,
'ssl_key' => SOLR_SSL_KEY,
'ssl_keypassword' => SOLR_SSL_KEYPASSWORD,
'ssl_cainfo' => SOLR_SSL_CAINFO,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetField('cat')->addFacetField('name')->setFacetMinCount(2)->setFacetMinCount(4, 'name');

$updateResponse = $client->query($query);

$response_array = $updateResponse->getResponse();

$facet_data = $response_array->facet_counts->facet_fields;

print_r($facet_data);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [cat] => SolrObject Object
        (
            [electronics] => 14
            [memory] => 3
            [Lucene] => 2
            [Software] => 2
            [card] => 2
            [connector] => 2
            [drive] => 2
            [graphics] => 2
            [hard] => 2
            [monitor] => 2
            [search] => 2
            [software] => 2
        )

    [name] => SolrObject Object
        (
            [gb] => 6
        )

)

例13 Collapsing a SolrQuery

<?php
include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_PATH
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$collapseFunction = new SolrCollapseFunction('manu_id_s');

$collapseFunction
->setSize(2)
->setNullPolicy(SolrCollapseFunction::NULLPOLICY_IGNORE);

$query
->collapse($collapseFunction)
->setRows(4);

$queryResponse = $client->query($query);

$response = $queryResponse->getResponse();

print_r($response);
?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [q] => *:*
                    [indent] => on
                    [fq] => {!collapse field=manu_id_s size=2 nullPolicy=ignore}
                    [rows] => 4
                    [version] => 2.2
                    [wt] => xml
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 14
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => SP2514N
                            [name] => Array
                                (
                                    [0] => Samsung SpinPoint P120 SP2514N - hard drive - 250 GB - ATA-133
                                )

                            [manu] => Array
                                (
                                    [0] => Samsung Electronics Co. Ltd.
                                )

                            [manu_id_s] => samsung
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => 7200RPM, 8MB cache, IDE Ultra ATA-133
                                    [1] => NoiseGuard, SilentSeek technology, Fluid Dynamic Bearing (FDB) motor
                                )

                            [price] => Array
                                (
                                    [0] => 92
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [store] => Array
                                (
                                    [0] => 35.0752,-97.032
                                )

                            [_version_] => 1510294336412057600
                        )

                    [1] => SolrObject Object
                        (
                            [id] => 6H500F0
                            [name] => Array
                                (
                                    [0] => Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300
                                )

                            [manu] => Array
                                (
                                    [0] => Maxtor Corp.
                                )

                            [manu_id_s] => maxtor
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => SATA 3.0Gb/s, NCQ
                                    [1] => 8.5ms seek
                                    [2] => 16MB cache
                                )

                            [price] => Array
                                (
                                    [0] => 350
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 45.17614,-93.87341
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [_version_] => 1510294336449806336
                        )

                    [2] => SolrObject Object
                        (
                            [id] => F8V7067-APL-KIT
                            [name] => Array
                                (
                                    [0] => Belkin Mobile Power Cord for iPod w/ Dock
                                )

                            [manu] => Array
                                (
                                    [0] => Belkin
                                )

                            [manu_id_s] => belkin
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => connector
                                )

                            [features] => Array
                                (
                                    [0] => car power adapter, white
                                )

                            [weight] => Array
                                (
                                    [0] => 4
                                )

                            [price] => Array
                                (
                                    [0] => 19.95
                                )

                            [popularity] => Array
                                (
                                    [0] => 1
                                )

                            [inStock] => Array
                                (
                                    [0] =>
                                )

                            [store] => Array
                                (
                                    [0] => 45.18014,-93.87741
                                )

                            [manufacturedate_dt] => 2005-08-01T16:30:25Z
                            [_version_] => 1510294336458194944
                        )

                    [3] => SolrObject Object
                        (
                            [id] => MA147LL/A
                            [name] => Array
                                (
                                    [0] => Apple 60 GB iPod with Video Playback Black
                                )

                            [manu] => Array
                                (
                                    [0] => Apple Computer Inc.
                                )

                            [manu_id_s] => apple
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => music
                                )

                            [features] => Array
                                (
                                    [0] => iTunes, Podcasts, Audiobooks
                                    [1] => Stores up to 15,000 songs, 25,000 photos, or 150 hours of video
                                    [2] => 2.5-inch, 320x240 color TFT LCD display with LED backlight
                                    [3] => Up to 20 hours of battery life
                                    [4] => Plays AAC, MP3, WAV, AIFF, Audible, Apple Lossless, H.264 video
                                    [5] => Notes, Calendar, Phone book, Hold button, Date display, Photo wallet, Built-in games, JPEG photo playback, Upgradeable firmware, USB 2.0 compatibility, Playback speed control, Rechargeable capability, Battery level indication
                                )

                            [includes] => Array
                                (
                                    [0] => earbud headphones, USB cable
                                )

                            [weight] => Array
                                (
                                    [0] => 5.5
                                )

                            [price] => Array
                                (
                                    [0] => 399
                                )

                            [popularity] => Array
                                (
                                    [0] => 10
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 37.7752,-100.0232
                                )

                            [manufacturedate_dt] => 2005-10-12T08:00:00Z
                            [_version_] => 1510294336562003968
                        )

                )

        )

)

例14 Solr Real Time Get (RTG) の例 SolrClient::getById()

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_PATH
);

$client = new SolrClient($options);
$response = $client->getById('GB18030TEST');
print_r($response->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [doc] => SolrObject Object
        (
            [id] => GB18030TEST
            [name] => Array
                (
                    [0] => Test with some GB18030 encoded characters
                )

            [features] => Array
                (
                    [0] => No accents here
                    [1] => (訳注:ここに記載されている中国語文字列は、英語版マニュアルでご確認ください)
                    [2] => This is a feature (translated)
                    [3] => (訳注:ここに記載されている中国語文字列は、英語版マニュアルでご確認ください)
                    [4] => This document is very shiny (translated)
                )

            [price] => Array
                (
                    [0] => 0
                )

            [inStock] => Array
                (
                    [0] => 1
                )

            [_version_] => 1510294336239042560
        )

)


SolrUtils クラス

(PECL solr >= 0.9.2)

はじめに

拡張モジュールの現行バージョンを取得し、クエリ句を準備するための ユーティリティ・メソッドを含みます。

クエリ文字列をエスケープしたり、XML レスポンスをパースするためのメソッドも含みます。

クラス概要

abstract class SolrUtils {
/* メソッド */
public static digestXmlResponse(string $xmlresponse, int $parse_mode = 0): SolrObject
public static escapeQueryChars(string $str): string|false
public static getSolrVersion(): string
public static queryPhrase(string $str): string
}

目次

  • SolrUtils::digestXmlResponse — Parses an response XML string into a SolrObject
  • SolrUtils::escapeQueryChars — Escapes a lucene query string
  • SolrUtils::getSolrVersion — Solr 拡張モジュールの現行バージョンを返す
  • SolrUtils::queryPhrase — Prepares a phrase from an unescaped lucene string


Parses an response XML string into a SolrObject

  • ≪ SolrUtils
  • SolrUtils::escapeQueryChars ≫
  • PHP Manual
  • SolrUtils
  • Parses an response XML string into a SolrObject

SolrUtils::digestXmlResponse

(PECL solr >= 0.9.2)

SolrUtils::digestXmlResponse — Parses an response XML string into a SolrObject

説明

public static SolrUtils::digestXmlResponse(string $xmlresponse, int $parse_mode = 0): SolrObject

This method parses an response XML string from the Apache Solr server into a SolrObject. It throws a SolrException if there was an error.

パラメータ

xmlresponse

The XML response string from the Solr server.

parse_mode

Use SolrResponse::PARSE_SOLR_OBJ or SolrResponse::PARSE_SOLR_DOC

戻り値

Returns the SolrObject representing the XML response.

If the parse_mode parameter is set to SolrResponse::PARSE_SOLR_OBJ Solr documents will be parses as SolrObject instances.

If it is set to SolrResponse::PARSE_SOLR_DOC, they will be parsed as SolrDocument instances.


Escapes a lucene query string

  • ≪ SolrUtils::digestXmlResponse
  • SolrUtils::getSolrVersion ≫
  • PHP Manual
  • SolrUtils
  • Escapes a lucene query string

SolrUtils::escapeQueryChars

(PECL solr >= 0.9.2)

SolrUtils::escapeQueryChars — Escapes a lucene query string

説明

public static SolrUtils::escapeQueryChars(string $str): string|false

Lucene supports escaping special characters that are part of the query syntax.

The current list special characters are:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /

These characters are part of the query syntax and must be escaped

パラメータ

str

This is the query string to be escaped.

戻り値

Returns the escaped string失敗した場合に false を返します.


Solr 拡張モジュールの現行バージョンを返す

  • ≪ SolrUtils::escapeQueryChars
  • SolrUtils::queryPhrase ≫
  • PHP Manual
  • SolrUtils
  • Solr 拡張モジュールの現行バージョンを返す

SolrUtils::getSolrVersion

(PECL solr >= 0.9.2)

SolrUtils::getSolrVersion — Solr 拡張モジュールの現行バージョンを返す

説明

public static SolrUtils::getSolrVersion(): string

Solr の現行バージョンを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Apache Solr 拡張モジュールの現行バージョン。


Prepares a phrase from an unescaped lucene string

  • ≪ SolrUtils::getSolrVersion
  • SolrInputDocument ≫
  • PHP Manual
  • SolrUtils
  • Prepares a phrase from an unescaped lucene string

SolrUtils::queryPhrase

(PECL solr >= 0.9.2)

SolrUtils::queryPhrase — Prepares a phrase from an unescaped lucene string

説明

public static SolrUtils::queryPhrase(string $str): string

Prepares a phrase from an unescaped lucene string.

パラメータ

str

The lucene phrase.

戻り値

Returns the phrase contained in double quotes.


SolrInputDocument クラス

(PECL solr >= 0.9.2)

はじめに

このクラスは、Solr インデックスにサブミットされようとしている Solr 文書を表現します。

クラス概要

final class SolrInputDocument {
/* 定数 */
const int SORT_DEFAULT = 1;
const int SORT_ASC = 1;
const int SORT_DESC = 2;
const int SORT_FIELD_NAME = 1;
const int SORT_FIELD_VALUE_COUNT = 2;
const int SORT_FIELD_BOOST_VALUE = 4;
/* メソッド */
public __construct()
public addChildDocument(SolrInputDocument $child): void
public addChildDocuments(array &$docs): void
public addField(string $fieldName, string $fieldValue, float $fieldBoostValue = 0.0): bool
public clear(): bool
public __clone(): void
public deleteField(string $fieldName): bool
public fieldExists(string $fieldName): bool
public getBoost(): float
public getChildDocuments(): array
public getChildDocumentsCount(): int
public getField(string $fieldName): SolrDocumentField
public getFieldBoost(string $fieldName): float
public getFieldCount(): int|false
public getFieldNames(): array
public hasChildDocuments(): bool
public merge(SolrInputDocument $sourceDoc, bool $overwrite = true): bool
public reset(): bool
public setBoost(float $documentBoostValue): bool
public setFieldBoost(string $fieldName, float $fieldBoostValue): bool
public sort(int $sortOrderBy, int $sortDirection = SolrInputDocument::SORT_ASC): bool
public toArray(): array
public __destruct()
}

定義済み定数

SolrInputDocument クラス定数

SolrInputDocument::SORT_DEFAULT

フィールドを昇順でソート

SolrInputDocument::SORT_ASC

フィールドを昇順でソート

SolrInputDocument::SORT_DESC

フィールドを降順でソート

SolrInputDocument::SORT_FIELD_NAME

フィールドを名前でソート

SolrInputDocument::SORT_FIELD_VALUE_COUNT

フィールドを値の数でソート

SolrInputDocument::SORT_FIELD_BOOST_VALUE

boost 値でフィールドをソート

目次

  • SolrInputDocument::addChildDocument — Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments — Adds an array of child documents
  • SolrInputDocument::addField — 文書にフィールドを追加
  • SolrInputDocument::clear — 入力した文書をリセット
  • SolrInputDocument::__clone — SolrDocument のコピーを作成
  • SolrInputDocument::__construct — コンストラクタ
  • SolrInputDocument::deleteField — 文書からフィールドを除去
  • SolrInputDocument::__destruct — デストラクタ
  • SolrInputDocument::fieldExists — フィールドが存在するかチェック
  • SolrInputDocument::getBoost — 文書に対する現行の boost 値を取得
  • SolrInputDocument::getChildDocuments — Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount — Returns the number of child documents
  • SolrInputDocument::getField — 名前でフィールドを取得
  • SolrInputDocument::getFieldBoost — 特定のフィールドに対する boost 値を取得
  • SolrInputDocument::getFieldCount — 文書内のフィールド数を返す
  • SolrInputDocument::getFieldNames — 文書内のフィールドを全て含む配列を返す
  • SolrInputDocument::hasChildDocuments — Returns true if the document has any child documents
  • SolrInputDocument::merge — Merges one input document into another
  • SolrInputDocument::reset — SolrInputDocument::clear のエイリアス
  • SolrInputDocument::setBoost — この文書に対する boost 値を設定
  • SolrInputDocument::setFieldBoost — フィールドに対するインデキシング時間の boost 値を設定
  • SolrInputDocument::sort — Sorts the fields within the document
  • SolrInputDocument::toArray — 入力した文書の配列表現を返す


Adds a child document for block indexing

  • ≪ SolrInputDocument
  • SolrInputDocument::addChildDocuments ≫
  • PHP Manual
  • SolrInputDocument
  • Adds a child document for block indexing

SolrInputDocument::addChildDocument

(PECL solr >= 2.3.0)

SolrInputDocument::addChildDocument — Adds a child document for block indexing

説明

public SolrInputDocument::addChildDocument(SolrInputDocument $child): void

Adds a child document to construct a document block with nested documents.

パラメータ

child

A SolrInputDocument object.

戻り値

値を返しません。

エラー / 例外

Throws SolrIllegalArgumentException on failure.

Throws SolrException on internal failure.

例

例1 SolrInputDocument::addChildDocument() example

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_STORE_PATH,
);

$client = new SolrClient($options);

$product = new SolrInputDocument();

$product->addField('id', 'P-BLACK');
$product->addField('cat', 'tshirt');
$product->addField('cat', 'polo');
$product->addField('content_type', 'product');

$small = new SolrInputDocument();
$small->addField('id', 'TS-BLK-S');
$small->addField('content_type', 'sku');
$small->addField('size', 'S');
$small->addField('inventory', 100);

$medium = new SolrInputDocument();
$medium->addField('id', 'TS-BLK-M');
$medium->addField('content_type', 'sku');
$medium->addField('size', 'M');
$medium->addField('inventory', 200);

$large = new SolrInputDocument();
$large->addField('id', 'TS-BLK-L');
$large->addField('content_type', 'sku');
$large->addField('size', 'L');
$large->addField('inventory', 300);

// add child documents
$product->addChildDocument($small);
$product->addChildDocument($medium);
$product->addChildDocument($large);

// add product document block to the index
$updateResponse = $client->addDocument(
$product,
true, // overwrite if the document exists
10000 // commit within 10 seconds
);

print_r($updateResponse->getResponse());

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 5
        )
)

参考

  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents


Adds an array of child documents

  • ≪ SolrInputDocument::addChildDocument
  • SolrInputDocument::addField ≫
  • PHP Manual
  • SolrInputDocument
  • Adds an array of child documents

SolrInputDocument::addChildDocuments

(PECL solr >= 2.3.0)

SolrInputDocument::addChildDocuments — Adds an array of child documents

説明

public SolrInputDocument::addChildDocuments(array &$docs): void

Adds an array of child documents to the current input document.

パラメータ

docs

An array of SolrInputDocument objects.

戻り値

値を返しません。

エラー / 例外

Throws SolrIllegalArgumentException on failure.

Throws SolrException on internal failure.

例

例1 SolrInputDocument::addChildDocuments() example

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_STORE_PATH,
);

$client = new SolrClient($options);

$product = new SolrInputDocument();

$product->addField('id', 'P-BLACK');
$product->addField('cat', 'tshirt');
$product->addField('cat', 'polo');
$product->addField('content_type', 'product');

$small = new SolrInputDocument();
$small->addField('id', 'TS-BLK-S');
$small->addField('content_type', 'sku');
$small->addField('size', 'S');
$small->addField('inventory', 100);

$medium = new SolrInputDocument();
$medium->addField('id', 'TS-BLK-M');
$medium->addField('content_type', 'sku');
$medium->addField('size', 'M');
$medium->addField('inventory', 200);

$large = new SolrInputDocument();
$large->addField('id', 'TS-BLK-L');
$large->addField('content_type', 'sku');
$large->addField('size', 'L');
$large->addField('inventory', 300);

// add child documents
$skus = [$small, $medium, $large];
$product->addChildDocuments($skus);

// add the product document block to the index
$updateResponse = $client->addDocument(
$product,
true, // overwrite if the document exists
10000 // commit within 10 seconds
);

print_r($updateResponse->getResponse());

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 5
        )
)

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents


文書にフィールドを追加

  • ≪ SolrInputDocument::addChildDocuments
  • SolrInputDocument::clear ≫
  • PHP Manual
  • SolrInputDocument
  • 文書にフィールドを追加

SolrInputDocument::addField

(PECL solr >= 0.9.2)

SolrInputDocument::addField — 文書にフィールドを追加

説明

public SolrInputDocument::addField(string $fieldName, string $fieldValue, float $fieldBoostValue = 0.0): bool

複数値の項目に対しては、もし有効な boost 値が指定されると、 指定された値とこのフィールドに対する現行の boost 値 とが掛け算されます。

パラメータ

fieldName

フィールド名

fieldValue

このフィールドに対する値

fieldBoostValue

フィールドに対するインデキシング時間の boost。 負の値にはできませんが、それでも 1.0 未満の価格を渡せます。しかし、それらはゼロより大きくなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


入力した文書をリセット

  • ≪ SolrInputDocument::addField
  • SolrInputDocument::__clone ≫
  • PHP Manual
  • SolrInputDocument
  • 入力した文書をリセット

SolrInputDocument::clear

(PECL solr >= 0.9.2)

SolrInputDocument::clear — 入力した文書をリセット

説明

public SolrInputDocument::clear(): bool

全フィールドをドロップして文書をリセットし、文書の boost をゼロにリセットします。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


SolrDocument のコピーを作成

  • ≪ SolrInputDocument::clear
  • SolrInputDocument::__construct ≫
  • PHP Manual
  • SolrInputDocument
  • SolrDocument のコピーを作成

SolrInputDocument::__clone

(PECL solr >= 0.9.2)

SolrInputDocument::__clone — SolrDocument のコピーを作成

説明

public SolrInputDocument::__clone(): void

直接呼出しされてはいけません。SolrInputDocument のディープコピー作成に使用されます。

パラメータ

この関数にはパラメータはありません。

戻り値

SolrInputDocument インスタンスを新規作成。


コンストラクタ

  • ≪ SolrInputDocument::__clone
  • SolrInputDocument::deleteField ≫
  • PHP Manual
  • SolrInputDocument
  • コンストラクタ

SolrInputDocument::__construct

(PECL solr >= 0.9.2)

SolrInputDocument::__construct — コンストラクタ

説明

public SolrInputDocument::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


文書からフィールドを除去

  • ≪ SolrInputDocument::__construct
  • SolrInputDocument::__destruct ≫
  • PHP Manual
  • SolrInputDocument
  • 文書からフィールドを除去

SolrInputDocument::deleteField

(PECL solr >= 0.9.2)

SolrInputDocument::deleteField — 文書からフィールドを除去

説明

public SolrInputDocument::deleteField(string $fieldName): bool

文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

戻り値

成功した場合に true を、失敗した場合に false を返します。


デストラクタ

  • ≪ SolrInputDocument::deleteField
  • SolrInputDocument::fieldExists ≫
  • PHP Manual
  • SolrInputDocument
  • デストラクタ

SolrInputDocument::__destruct

(PECL solr >= 0.9.2)

SolrInputDocument::__destruct — デストラクタ

説明

public SolrInputDocument::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


フィールドが存在するかチェック

  • ≪ SolrInputDocument::__destruct
  • SolrInputDocument::getBoost ≫
  • PHP Manual
  • SolrInputDocument
  • フィールドが存在するかチェック

SolrInputDocument::fieldExists

(PECL solr >= 0.9.2)

SolrInputDocument::fieldExists — フィールドが存在するかチェック

説明

public SolrInputDocument::fieldExists(string $fieldName): bool

フィールドが存在するかチェックします。

パラメータ

fieldName

フィールド名

戻り値

フィールドが見つかった場合 true 、見つからなかった場合 false を返します。


文書に対する現行の boost 値を取得

  • ≪ SolrInputDocument::fieldExists
  • SolrInputDocument::getChildDocuments ≫
  • PHP Manual
  • SolrInputDocument
  • 文書に対する現行の boost 値を取得

SolrInputDocument::getBoost

(PECL solr >= 0.9.2)

SolrInputDocument::getBoost — 文書に対する現行の boost 値を取得

説明

public SolrInputDocument::getBoost(): float

文書に対する現行の boost 値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合は boost 値、失敗した場合は false を返します。


Returns an array of child documents (SolrInputDocument)

  • ≪ SolrInputDocument::getBoost
  • SolrInputDocument::getChildDocumentsCount ≫
  • PHP Manual
  • SolrInputDocument
  • Returns an array of child documents (SolrInputDocument)

SolrInputDocument::getChildDocuments

(PECL solr >= 2.3.0)

SolrInputDocument::getChildDocuments — Returns an array of child documents (SolrInputDocument)

説明

public SolrInputDocument::getChildDocuments(): array

Returns an array of child documents (SolrInputDocument)

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents


Returns the number of child documents

  • ≪ SolrInputDocument::getChildDocuments
  • SolrInputDocument::getField ≫
  • PHP Manual
  • SolrInputDocument
  • Returns the number of child documents

SolrInputDocument::getChildDocumentsCount

(PECL solr >= 2.3.0)

SolrInputDocument::getChildDocumentsCount — Returns the number of child documents

説明

public SolrInputDocument::getChildDocumentsCount(): int

Returns the number of child documents

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::hasChildDocuments() - Returns true if the document has any child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)


名前でフィールドを取得

  • ≪ SolrInputDocument::getChildDocumentsCount
  • SolrInputDocument::getFieldBoost ≫
  • PHP Manual
  • SolrInputDocument
  • 名前でフィールドを取得

SolrInputDocument::getField

(PECL solr >= 0.9.2)

SolrInputDocument::getField — 名前でフィールドを取得

説明

public SolrInputDocument::getField(string $fieldName): SolrDocumentField

文書内のフィールドを取得します。

パラメータ

fieldName

フィールド名

戻り値

成功時には SolrDocumentField オブジェクト、失敗時には false を返します。


特定のフィールドに対する boost 値を取得

  • ≪ SolrInputDocument::getField
  • SolrInputDocument::getFieldCount ≫
  • PHP Manual
  • SolrInputDocument
  • 特定のフィールドに対する boost 値を取得

SolrInputDocument::getFieldBoost

(PECL solr >= 0.9.2)

SolrInputDocument::getFieldBoost — 特定のフィールドに対する boost 値を取得

説明

public SolrInputDocument::getFieldBoost(string $fieldName): float

特定のフィールドに対する boost 値を取得します。

パラメータ

fieldName

フィールド名

戻り値

フィールドの boost 値、またはエラーがあった場合には false を返します。


文書内のフィールド数を返す

  • ≪ SolrInputDocument::getFieldBoost
  • SolrInputDocument::getFieldNames ≫
  • PHP Manual
  • SolrInputDocument
  • 文書内のフィールド数を返す

SolrInputDocument::getFieldCount

(PECL solr >= 0.9.2)

SolrInputDocument::getFieldCount — 文書内のフィールド数を返す

説明

public SolrInputDocument::getFieldCount(): int|false

文書内のフィールド数を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に整数、失敗した場合に false を返します.


文書内のフィールドを全て含む配列を返す

  • ≪ SolrInputDocument::getFieldCount
  • SolrInputDocument::hasChildDocuments ≫
  • PHP Manual
  • SolrInputDocument
  • 文書内のフィールドを全て含む配列を返す

SolrInputDocument::getFieldNames

(PECL solr >= 0.9.2)

SolrInputDocument::getFieldNames — 文書内のフィールドを全て含む配列を返す

説明

public SolrInputDocument::getFieldNames(): array

文書内のフィールドを全て含む配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時には配列、失敗時には false を返します。


Returns true if the document has any child documents

  • ≪ SolrInputDocument::getFieldNames
  • SolrInputDocument::merge ≫
  • PHP Manual
  • SolrInputDocument
  • Returns true if the document has any child documents

SolrInputDocument::hasChildDocuments

(PECL solr >= 2.3.0)

SolrInputDocument::hasChildDocuments — Returns true if the document has any child documents

説明

public SolrInputDocument::hasChildDocuments(): bool

Checks whether the document has any child documents

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrInputDocument::addChildDocument() - Adds a child document for block indexing
  • SolrInputDocument::addChildDocuments() - Adds an array of child documents
  • SolrInputDocument::getChildDocuments() - Returns an array of child documents (SolrInputDocument)
  • SolrInputDocument::getChildDocumentsCount() - Returns the number of child documents


Merges one input document into another

  • ≪ SolrInputDocument::hasChildDocuments
  • SolrInputDocument::reset ≫
  • PHP Manual
  • SolrInputDocument
  • Merges one input document into another

SolrInputDocument::merge

(PECL solr >= 0.9.2)

SolrInputDocument::merge — Merges one input document into another

説明

public SolrInputDocument::merge(SolrInputDocument $sourceDoc, bool $overwrite = true): bool

Merges one input document into another.

パラメータ

sourceDoc

The source document.

overwrite

If this is true it will replace matching fields in the destination document.

戻り値

成功した場合に true を、失敗した場合に false を返します。 In the future, this will be modified to return the number of fields in the new document.


SolrInputDocument::clear のエイリアス

  • ≪ SolrInputDocument::merge
  • SolrInputDocument::setBoost ≫
  • PHP Manual
  • SolrInputDocument
  • SolrInputDocument::clear のエイリアス

SolrInputDocument::reset

(PECL solr >= 0.9.2)

SolrInputDocument::reset — SolrInputDocument::clear() のエイリアス

説明

public SolrInputDocument::reset(): bool

これは、SolrInputDocument::clear のエイリアスです

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


この文書に対する boost 値を設定

  • ≪ SolrInputDocument::reset
  • SolrInputDocument::setFieldBoost ≫
  • PHP Manual
  • SolrInputDocument
  • この文書に対する boost 値を設定

SolrInputDocument::setBoost

(PECL solr >= 0.9.2)

SolrInputDocument::setBoost — この文書に対する boost 値を設定

説明

public SolrInputDocument::setBoost(float $documentBoostValue): bool

この文書に対する boost 値を設定します。

パラメータ

documentBoostValue

この文書に対するインデキシング時間の boost 値

戻り値

成功した場合に true を、失敗した場合に false を返します。


フィールドに対するインデキシング時間の boost 値を設定

  • ≪ SolrInputDocument::setBoost
  • SolrInputDocument::sort ≫
  • PHP Manual
  • SolrInputDocument
  • フィールドに対するインデキシング時間の boost 値を設定

SolrInputDocument::setFieldBoost

(PECL solr >= 0.9.2)

SolrInputDocument::setFieldBoost — フィールドに対するインデキシング時間の boost 値を設定

説明

public SolrInputDocument::setFieldBoost(string $fieldName, float $fieldBoostValue): bool

フィールドに対するインデキシング時間の boost 値を設定します。 これは、このフィールドに対する現行の boost 値を置換します。

パラメータ

fieldName

フィールド名

fieldBoostValue

インデキシング時間の boost 値

戻り値

成功した場合に true を、失敗した場合に false を返します。


Sorts the fields within the document

  • ≪ SolrInputDocument::setFieldBoost
  • SolrInputDocument::toArray ≫
  • PHP Manual
  • SolrInputDocument
  • Sorts the fields within the document

SolrInputDocument::sort

(PECL solr >= 0.9.2)

SolrInputDocument::sort — Sorts the fields within the document

説明

public SolrInputDocument::sort(int $sortOrderBy, int $sortDirection = SolrInputDocument::SORT_ASC): bool

The fields are rearranged according to the specified criteria and sort direction

   Fields can be sorted by boost values, field names and number of values.

   The $order_by parameter must be one of :

   * SolrInputDocument::SORT_FIELD_NAME
   * SolrInputDocument::SORT_FIELD_BOOST_VALUE
   * SolrInputDocument::SORT_FIELD_VALUE_COUNT

   The sort direction can be one of :

   * SolrInputDocument::SORT_DEFAULT
   * SolrInputDocument::SORT_ASC
   * SolrInputDocument::SORT_DESC

パラメータ

sortOrderBy

The sort criteria

sortDirection

The sort direction

戻り値

成功した場合に true を、失敗した場合に false を返します。


入力した文書の配列表現を返す

  • ≪ SolrInputDocument::sort
  • SolrDocument ≫
  • PHP Manual
  • SolrInputDocument
  • 入力した文書の配列表現を返す

SolrInputDocument::toArray

(PECL solr >= 0.9.2)

SolrInputDocument::toArray — 入力した文書の配列表現を返す

説明

public SolrInputDocument::toArray(): array

入力した文書の配列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

フィールドを含む配列を返します。失敗時には false を返します。


The SolrDocument class

(PECL solr >= 0.9.2)

はじめに

Represents a Solr document retrieved from a query response.

クラス概要

final class SolrDocument implements ArrayAccess, Iterator, Serializable {
/* 定数 */
const int SORT_DEFAULT = 1;
const int SORT_ASC = 1;
const int SORT_DESC = 2;
const int SORT_FIELD_NAME = 1;
const int SORT_FIELD_VALUE_COUNT = 2;
const int SORT_FIELD_BOOST_VALUE = 4;
/* メソッド */
public __construct()
public addField(string $fieldName, string $fieldValue): bool
public clear(): bool
public __clone(): void
public current(): SolrDocumentField
public deleteField(string $fieldName): bool
public fieldExists(string $fieldName): bool
public __get(string $fieldName): SolrDocumentField
public getChildDocuments(): array
public getChildDocumentsCount(): int
public getField(string $fieldName): SolrDocumentField
public getFieldCount(): int
public getFieldNames(): array
public getInputDocument(): SolrInputDocument
public hasChildDocuments(): bool
public __isset(string $fieldName): bool
public key(): string
public merge(SolrDocument $sourceDoc, bool $overwrite = true): bool
public next(): void
public offsetExists(string $fieldName): bool
public offsetGet(string $fieldName): SolrDocumentField
public offsetSet(string $fieldName, string $fieldValue): void
public offsetUnset(string $fieldName): void
public reset(): bool
public rewind(): void
public serialize(): string
public __set(string $fieldName, string $fieldValue): bool
public sort(int $sortOrderBy, int $sortDirection = SolrDocument::SORT_ASC): bool
public toArray(): array
public unserialize(string $serialized): void
public __unset(string $fieldName): bool
public valid(): bool
public __destruct()
}

定義済み定数

SolrDocument::SORT_DEFAULT

Default mode for sorting fields within the document.

SolrDocument::SORT_ASC

Sorts the fields in ascending order

SolrDocument::SORT_DESC

Sorts the fields in descending order

SolrDocument::SORT_FIELD_NAME

Sorts the fields by field name.

SolrDocument::SORT_FIELD_VALUE_COUNT

Sorts the fields by number of values in each field.

SolrDocument::SORT_FIELD_BOOST_VALUE

Sorts the fields by thier boost values.

目次

  • SolrDocument::addField — 文書にフィールドを追加
  • SolrDocument::clear — Drops all the fields in the document
  • SolrDocument::__clone — SolrDocument オブジェクトのコピーを作成
  • SolrDocument::__construct — コンストラクタ
  • SolrDocument::current — 現行のフィールドを取得
  • SolrDocument::deleteField — 文書からフィールドを除去
  • SolrDocument::__destruct — デストラクタ
  • SolrDocument::fieldExists — Checks if a field exists in the document
  • SolrDocument::__get — プロパティとしてフィールドにアクセス
  • SolrDocument::getChildDocuments — Returns an array of child documents (SolrDocument)
  • SolrDocument::getChildDocumentsCount — Returns the number of child documents
  • SolrDocument::getField — 名前でフィールドを取得
  • SolrDocument::getFieldCount — この文書内のフィールド数を返す
  • SolrDocument::getFieldNames — 文書内のフィールド名の配列を返す
  • SolrDocument::getInputDocument — Returns a SolrInputDocument equivalent of the object
  • SolrDocument::hasChildDocuments — Checks whether the document has any child documents
  • SolrDocument::__isset — フィールドが存在するかチェック
  • SolrDocument::key — 現行のキーを返す
  • SolrDocument::merge — Merges source to the current SolrDocument
  • SolrDocument::next — 内部ポインタを次のフィールドに移動
  • SolrDocument::offsetExists — 特定のフィールドが存在するかどうかチェック
  • SolrDocument::offsetGet — フィールドを取得
  • SolrDocument::offsetSet — 文書にフィールドを追加
  • SolrDocument::offsetUnset — フィールドを除去
  • SolrDocument::reset — SolrDocument::clear のエイリアス
  • SolrDocument::rewind — 内部ポインタを先頭にリセット
  • SolrDocument::serialize — カスタムのシリアライズで使われます
  • SolrDocument::__set — Adds another field to the document
  • SolrDocument::sort — Sorts the fields in the document
  • SolrDocument::toArray — 文書の配列表現を返す
  • SolrDocument::unserialize — Custom serialization of SolrDocument objects
  • SolrDocument::__unset — 文書からフィールドを除去
  • SolrDocument::valid — Checks if the current position internally is still valid


文書にフィールドを追加

  • ≪ SolrDocument
  • SolrDocument::clear ≫
  • PHP Manual
  • SolrDocument
  • 文書にフィールドを追加

SolrDocument::addField

(PECL solr >= 0.9.2)

SolrDocument::addField — 文書にフィールドを追加

説明

public SolrDocument::addField(string $fieldName, string $fieldValue): bool

このメソッドは、SolrDocument インスタンスにフィールドを追加します。

パラメータ

fieldName

フィールド名

fieldValue

フィールドの値

戻り値

成功した場合に true を、失敗した場合に false を返します。


Drops all the fields in the document

  • ≪ SolrDocument::addField
  • SolrDocument::__clone ≫
  • PHP Manual
  • SolrDocument
  • Drops all the fields in the document

SolrDocument::clear

(PECL solr >= 0.9.2)

SolrDocument::clear — Drops all the fields in the document

説明

public SolrDocument::clear(): bool

Resets the current object. Discards all the fields and resets the document boost to zero.

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


SolrDocument オブジェクトのコピーを作成

  • ≪ SolrDocument::clear
  • SolrDocument::__construct ≫
  • PHP Manual
  • SolrDocument
  • SolrDocument オブジェクトのコピーを作成

SolrDocument::__clone

(PECL solr >= 0.9.2)

SolrDocument::__clone — SolrDocument オブジェクトのコピーを作成

説明

public SolrDocument::__clone(): void

SolrDocument オブジェクトのコピーを作成します。直接呼出しされません。

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


コンストラクタ

  • ≪ SolrDocument::__clone
  • SolrDocument::current ≫
  • PHP Manual
  • SolrDocument
  • コンストラクタ

SolrDocument::__construct

(PECL solr >= 0.9.2)

SolrDocument::__construct — コンストラクタ

説明

public SolrDocument::__construct()

SolrDocument に対するコンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値


現行のフィールドを取得

  • ≪ SolrDocument::__construct
  • SolrDocument::deleteField ≫
  • PHP Manual
  • SolrDocument
  • 現行のフィールドを取得

SolrDocument::current

(PECL solr >= 0.9.2)

SolrDocument::current — 現行のフィールドを取得

説明

public SolrDocument::current(): SolrDocumentField

現行のフィールドを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

フィールドを返します。


文書からフィールドを除去

  • ≪ SolrDocument::current
  • SolrDocument::__destruct ≫
  • PHP Manual
  • SolrDocument
  • 文書からフィールドを除去

SolrDocument::deleteField

(PECL solr >= 0.9.2)

SolrDocument::deleteField — 文書からフィールドを除去

説明

public SolrDocument::deleteField(string $fieldName): bool

文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

戻り値

成功した場合に true を、失敗した場合に false を返します。


デストラクタ

  • ≪ SolrDocument::deleteField
  • SolrDocument::fieldExists ≫
  • PHP Manual
  • SolrDocument
  • デストラクタ

SolrDocument::__destruct

(PECL solr >= 0.9.2)

SolrDocument::__destruct — デストラクタ

説明

public SolrDocument::__destruct()

SolrDocument に対するデストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値


Checks if a field exists in the document

  • ≪ SolrDocument::__destruct
  • SolrDocument::__get ≫
  • PHP Manual
  • SolrDocument
  • Checks if a field exists in the document

SolrDocument::fieldExists

(PECL solr >= 0.9.2)

SolrDocument::fieldExists — Checks if a field exists in the document

説明

public SolrDocument::fieldExists(string $fieldName): bool

Checks if the requested field as a valid fieldname in the document.

パラメータ

fieldName

The name of the field.

戻り値

Returns true if the field is present and false if it does not.


プロパティとしてフィールドにアクセス

  • ≪ SolrDocument::fieldExists
  • SolrDocument::getChildDocuments ≫
  • PHP Manual
  • SolrDocument
  • プロパティとしてフィールドにアクセス

SolrDocument::__get

(PECL solr >= 0.9.2)

SolrDocument::__get — プロパティとしてフィールドにアクセス

説明

public SolrDocument::__get(string $fieldName): SolrDocumentField

プロパティとしてフィールドにアクセスするためのマジックメソッド

パラメータ

fieldName

フィールド名

戻り値

SolrDocumentField インスタンスを返します。


Returns an array of child documents (SolrDocument)

  • ≪ SolrDocument::__get
  • SolrDocument::getChildDocumentsCount ≫
  • PHP Manual
  • SolrDocument
  • Returns an array of child documents (SolrDocument)

SolrDocument::getChildDocuments

(PECL solr >= 2.3.0)

SolrDocument::getChildDocuments — Returns an array of child documents (SolrDocument)

説明

public SolrDocument::getChildDocuments(): array

Returns an array of child documents (SolrDocument)

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrDocument::hasChildDocuments() - Checks whether the document has any child documents
  • SolrDocument::getChildDocumentsCount() - Returns the number of child documents


Returns the number of child documents

  • ≪ SolrDocument::getChildDocuments
  • SolrDocument::getField ≫
  • PHP Manual
  • SolrDocument
  • Returns the number of child documents

SolrDocument::getChildDocumentsCount

(PECL solr >= 2.3.0)

SolrDocument::getChildDocumentsCount — Returns the number of child documents

説明

public SolrDocument::getChildDocumentsCount(): int

Returns the number of child documents

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrDocument::hasChildDocuments() - Checks whether the document has any child documents
  • SolrDocument::getChildDocuments() - Returns an array of child documents (SolrDocument)


名前でフィールドを取得

  • ≪ SolrDocument::getChildDocumentsCount
  • SolrDocument::getFieldCount ≫
  • PHP Manual
  • SolrDocument
  • 名前でフィールドを取得

SolrDocument::getField

(PECL solr >= 0.9.2)

SolrDocument::getField — 名前でフィールドを取得

説明

public SolrDocument::getField(string $fieldName): SolrDocumentField

名前でフィールドを取得します。

パラメータ

fieldName

フィールド名

戻り値

成功時には SolrDocumentField、失敗時には false を返します。


この文書内のフィールド数を返す

  • ≪ SolrDocument::getField
  • SolrDocument::getFieldNames ≫
  • PHP Manual
  • SolrDocument
  • この文書内のフィールド数を返す

SolrDocument::getFieldCount

(PECL solr >= 0.9.2)

SolrDocument::getFieldCount — この文書内のフィールド数を返す

説明

public SolrDocument::getFieldCount(): int

この文書内のフィールド数を返します。 複数値のフィールドは１回だけ数えられます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時には整数、失敗時には false を返します。


文書内のフィールド名の配列を返す

  • ≪ SolrDocument::getFieldCount
  • SolrDocument::getInputDocument ≫
  • PHP Manual
  • SolrDocument
  • 文書内のフィールド名の配列を返す

SolrDocument::getFieldNames

(PECL solr >= 0.9.2)

SolrDocument::getFieldNames — 文書内のフィールド名の配列を返す

説明

public SolrDocument::getFieldNames(): array

文書内のフィールド名の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

この文書内のフィールド名を含む配列を返します。


Returns a SolrInputDocument equivalent of the object

  • ≪ SolrDocument::getFieldNames
  • SolrDocument::hasChildDocuments ≫
  • PHP Manual
  • SolrDocument
  • Returns a SolrInputDocument equivalent of the object

SolrDocument::getInputDocument

(PECL solr >= 0.9.2)

SolrDocument::getInputDocument — Returns a SolrInputDocument equivalent of the object

説明

public SolrDocument::getInputDocument(): SolrInputDocument

Returns a SolrInputDocument equivalent of the object. This is useful if one wishes to resubmit/update a document retrieved from a query.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a SolrInputDocument on success and null on failure.


Checks whether the document has any child documents

  • ≪ SolrDocument::getInputDocument
  • SolrDocument::__isset ≫
  • PHP Manual
  • SolrDocument
  • Checks whether the document has any child documents

SolrDocument::hasChildDocuments

(PECL solr >= 2.3.0)

SolrDocument::hasChildDocuments — Checks whether the document has any child documents

説明

public SolrDocument::hasChildDocuments(): bool

Checks whether the document has any child documents

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrDocument::getChildDocuments() - Returns an array of child documents (SolrDocument)
  • SolrDocument::getChildDocumentsCount() - Returns the number of child documents


フィールドが存在するかチェック

  • ≪ SolrDocument::hasChildDocuments
  • SolrDocument::key ≫
  • PHP Manual
  • SolrDocument
  • フィールドが存在するかチェック

SolrDocument::__isset

(PECL solr >= 0.9.2)

SolrDocument::__isset — フィールドが存在するかチェック

説明

public SolrDocument::__isset(string $fieldName): bool

フィールドが存在するかチェックします。

パラメータ

fieldName

フィールド名

戻り値

成功した場合に true を、失敗した場合に false を返します。


現行のキーを返す

  • ≪ SolrDocument::__isset
  • SolrDocument::merge ≫
  • PHP Manual
  • SolrDocument
  • 現行のキーを返す

SolrDocument::key

(PECL solr >= 0.9.2)

SolrDocument::key — 現行のキーを返す

説明

public SolrDocument::key(): string

現行のキーを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現行のキーを返します。


Merges source to the current SolrDocument

  • ≪ SolrDocument::key
  • SolrDocument::next ≫
  • PHP Manual
  • SolrDocument
  • Merges source to the current SolrDocument

SolrDocument::merge

(PECL solr >= 0.9.2)

SolrDocument::merge — Merges source to the current SolrDocument

説明

public SolrDocument::merge(SolrDocument $sourceDoc, bool $overwrite = true): bool

Merges source to the current SolrDocument.

パラメータ

sourceDoc

The source document.

overwrite

If this is true then fields with the same name in the destination document will be overwritten.

戻り値

成功した場合に true を、失敗した場合に false を返します。


内部ポインタを次のフィールドに移動

  • ≪ SolrDocument::merge
  • SolrDocument::offsetExists ≫
  • PHP Manual
  • SolrDocument
  • 内部ポインタを次のフィールドに移動

SolrDocument::next

(PECL solr >= 0.9.2)

SolrDocument::next — 内部ポインタを次のフィールドに移動

説明

public SolrDocument::next(): void

内部ポインタを次のフィールドに移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

この関数に戻り値はありません。


特定のフィールドが存在するかどうかチェック

  • ≪ SolrDocument::next
  • SolrDocument::offsetGet ≫
  • PHP Manual
  • SolrDocument
  • 特定のフィールドが存在するかどうかチェック

SolrDocument::offsetExists

(PECL solr >= 0.9.2)

SolrDocument::offsetExists — 特定のフィールドが存在するかどうかチェック

説明

public SolrDocument::offsetExists(string $fieldName): bool

特定のフィールドが存在するかどうかチェックします。これは、オブジェクトが配列として扱われる際に使用されます。

パラメータ

fieldName

フィールド名

戻り値

成功した場合に true を、失敗した場合に false を返します。


フィールドを取得

  • ≪ SolrDocument::offsetExists
  • SolrDocument::offsetSet ≫
  • PHP Manual
  • SolrDocument
  • フィールドを取得

SolrDocument::offsetGet

(PECL solr >= 0.9.2)

SolrDocument::offsetGet — フィールドを取得

説明

public SolrDocument::offsetGet(string $fieldName): SolrDocumentField

これは、オブジェクトが配列として扱われる際に、フィールドを取得するために使用されます。

パラメータ

fieldName

フィールド名

戻り値

SolrDocumentField オブジェクトを返します。


文書にフィールドを追加

  • ≪ SolrDocument::offsetGet
  • SolrDocument::offsetUnset ≫
  • PHP Manual
  • SolrDocument
  • 文書にフィールドを追加

SolrDocument::offsetSet

(PECL solr >= 0.9.2)

SolrDocument::offsetSet — 文書にフィールドを追加

説明

public SolrDocument::offsetSet(string $fieldName, string $fieldValue): void

オブジェクトが配列として扱われる際に、文書にフィールドを追加するために使用されます。

パラメータ

fieldName

フィールド名

fieldValue

このフィールドに対する値

戻り値

成功した場合に true を、失敗した場合に false を返します。


フィールドを除去

  • ≪ SolrDocument::offsetSet
  • SolrDocument::reset ≫
  • PHP Manual
  • SolrDocument
  • フィールドを除去

SolrDocument::offsetUnset

(PECL solr >= 0.9.2)

SolrDocument::offsetUnset — フィールドを除去

説明

public SolrDocument::offsetUnset(string $fieldName): void

文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

戻り値

戻り値はありません。


SolrDocument::clear のエイリアス

  • ≪ SolrDocument::offsetUnset
  • SolrDocument::rewind ≫
  • PHP Manual
  • SolrDocument
  • SolrDocument::clear のエイリアス

SolrDocument::reset

(PECL solr >= 0.9.2)

SolrDocument::reset — SolrDocument::clear() のエイリアス

説明

public SolrDocument::reset(): bool

これは、SolrDocument::clear()へのエイリアスです。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


内部ポインタを先頭にリセット

  • ≪ SolrDocument::reset
  • SolrDocument::serialize ≫
  • PHP Manual
  • SolrDocument
  • 内部ポインタを先頭にリセット

SolrDocument::rewind

(PECL solr >= 0.9.2)

SolrDocument::rewind — 内部ポインタを先頭にリセット

説明

public SolrDocument::rewind(): void

内部ポインタを先頭にリセットします。

パラメータ

この関数にはパラメータはありません。

戻り値

この関数に戻り値はありません。


カスタムのシリアライズで使われます

  • ≪ SolrDocument::rewind
  • SolrDocument::__set ≫
  • PHP Manual
  • SolrDocument
  • カスタムのシリアライズで使われます

SolrDocument::serialize

(PECL solr >= 0.9.2)

SolrDocument::serialize — カスタムのシリアライズで使われます

説明

public SolrDocument::serialize(): string

カスタムのシリアライズで使われます.

パラメータ

この関数にはパラメータはありません。

戻り値

シリアライズされた Solr 文書を表現する文字列を返します。


Adds another field to the document

  • ≪ SolrDocument::serialize
  • SolrDocument::sort ≫
  • PHP Manual
  • SolrDocument
  • Adds another field to the document

SolrDocument::__set

(PECL solr >= 0.9.2)

SolrDocument::__set — Adds another field to the document

説明

public SolrDocument::__set(string $fieldName, string $fieldValue): bool

Adds another field to the document. Used to set the fields as new properties.

パラメータ

fieldName

Name of the field.

fieldValue

Field value.

戻り値

成功した場合に true を、失敗した場合に false を返します。


Sorts the fields in the document

  • ≪ SolrDocument::__set
  • SolrDocument::toArray ≫
  • PHP Manual
  • SolrDocument
  • Sorts the fields in the document

SolrDocument::sort

(PECL solr >= 0.9.2)

SolrDocument::sort — Sorts the fields in the document

説明

public SolrDocument::sort(int $sortOrderBy, int $sortDirection = SolrDocument::SORT_ASC): bool

The fields are rearranged according to the specified criteria and sort direction

   Fields can be sorted by boost values, field names and number of values.

   The sortOrderBy parameter must be one of :

   * SolrDocument::SORT_FIELD_NAME
   * SolrDocument::SORT_FIELD_BOOST_VALUE
   * SolrDocument::SORT_FIELD_VALUE_COUNT

   The sortDirection can be one of :

   * SolrDocument::SORT_DEFAULT
   * SolrDocument::SORT_ASC
   * SolrDocument::SORT_DESC

   The default way is to sort in ascending order.

パラメータ

sortOrderBy

The sort criteria.

sortDirection

The sort direction.

戻り値

成功した場合に true を、失敗した場合に false を返します。


文書の配列表現を返す

  • ≪ SolrDocument::sort
  • SolrDocument::unserialize ≫
  • PHP Manual
  • SolrDocument
  • 文書の配列表現を返す

SolrDocument::toArray

(PECL solr >= 0.9.2)

SolrDocument::toArray — 文書の配列表現を返す

説明

public SolrDocument::toArray(): array

文書の配列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

文書の配列表現を返します。

例

例1 SolrDocument::toArray() の例

<?php

$doc = new SolrDocument();

$doc->addField('id', 1123);

$doc->features = "PHP Client Side";
$doc->features = "Fast development cycles";

$doc['cat'] = 'Software';
$doc['cat'] = 'Custom Search';
$doc->cat = 'Information Technology';

print_r($doc->toArray());

?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [document_boost] => 0
    [field_count] => 3
    [fields] => Array
        (
            [0] => SolrDocumentField Object
                (
                    [name] => id
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => 1123
                        )

                )

            [1] => SolrDocumentField Object
                (
                    [name] => features
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => PHP Client Side
                            [1] => Fast development cycles
                        )

                )

            [2] => SolrDocumentField Object
                (
                    [name] => cat
                    [boost] => 0
                    [values] => Array
                        (
                            [0] => Software
                            [1] => Custom Search
                            [2] => Information Technology
                        )

                )

        )

)


Custom serialization of SolrDocument objects

  • ≪ SolrDocument::toArray
  • SolrDocument::__unset ≫
  • PHP Manual
  • SolrDocument
  • Custom serialization of SolrDocument objects

SolrDocument::unserialize

(PECL solr >= 0.9.2)

SolrDocument::unserialize — Custom serialization of SolrDocument objects

説明

public SolrDocument::unserialize(string $serialized): void

Custom serialization of SolrDocument objects

パラメータ

serialized

An XML representation of the document.

戻り値

None.


文書からフィールドを除去

  • ≪ SolrDocument::unserialize
  • SolrDocument::valid ≫
  • PHP Manual
  • SolrDocument
  • 文書からフィールドを除去

SolrDocument::__unset

(PECL solr >= 0.9.2)

SolrDocument::__unset — 文書からフィールドを除去

説明

public SolrDocument::__unset(string $fieldName): bool

フィールドがオブジェクトのプロパティとしてアクセスされる場合、文書からフィールドを除去します。

パラメータ

fieldName

フィールド名

戻り値

成功した場合に true を、失敗した場合に false を返します。


Checks if the current position internally is still valid

  • ≪ SolrDocument::__unset
  • SolrDocumentField ≫
  • PHP Manual
  • SolrDocument
  • Checks if the current position internally is still valid

SolrDocument::valid

(PECL solr >= 0.9.2)

SolrDocument::valid — Checks if the current position internally is still valid

説明

public SolrDocument::valid(): bool

Checks if the current position internally is still valid. It is used during foreach operations.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns true on success and false if the current position is no longer valid.


SolrDocumentField クラス

(PECL solr >= 0.9.2)

はじめに

Solr 文書のフィールドを表現します。そのプロパティは全て読み取り専用です。

クラス概要

final class SolrDocumentField {
/* プロパティ */
public readonly string $name;
public readonly float $boost;
public readonly array $values;
/* メソッド */
public __construct()
public __destruct()
}

プロパティ

name

フィールド名

boost

フィールドの boost 値

values

このフィールドに対する値の配列

目次

  • SolrDocumentField::__construct — コンストラクタ
  • SolrDocumentField::__destruct — デストラクタ


コンストラクタ

  • ≪ SolrDocumentField
  • SolrDocumentField::__destruct ≫
  • PHP Manual
  • SolrDocumentField
  • コンストラクタ

SolrDocumentField::__construct

(PECL solr >= 0.9.2)

SolrDocumentField::__construct — コンストラクタ

説明

public SolrDocumentField::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


デストラクタ

  • ≪ SolrDocumentField::__construct
  • SolrObject ≫
  • PHP Manual
  • SolrDocumentField
  • デストラクタ

SolrDocumentField::__destruct

(PECL solr >= 0.9.2)

SolrDocumentField::__destruct — デストラクタ

説明

public SolrDocumentField::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


SolrObject クラス

(PECL solr >= 0.9.2)

はじめに

これはオブジェクトで、そのプロパティは、配列の文法を使用してアクセスされることもできます。 その全てのプロパティは読み取り専用です。

クラス概要

final class SolrObject implements ArrayAccess {
/* メソッド */
public __construct()
public getPropertyNames(): array
public offsetExists(string $property_name): bool
public offsetGet(string $property_name): mixed
public offsetSet(string $property_name, string $property_value): void
public offsetUnset(string $property_name): void
public __destruct()
}

目次

  • SolrObject::__construct — Solr オブジェクトを生成
  • SolrObject::__destruct — デストラクタ
  • SolrObject::getPropertyNames — 全てのプロパティ名の配列を返す
  • SolrObject::offsetExists — プロパティが存在するかチェック
  • SolrObject::offsetGet — プロパティを取得するために使用される
  • SolrObject::offsetSet — プロパティに対して値を設定
  • SolrObject::offsetUnset — プロパティに対して値の設定を解除


Solr オブジェクトを生成

  • ≪ SolrObject
  • SolrObject::__destruct ≫
  • PHP Manual
  • SolrObject
  • Solr オブジェクトを生成

SolrObject::__construct

(PECL solr >= 0.9.2)

SolrObject::__construct — Solr オブジェクトを生成

説明

public SolrObject::__construct()

Solr オブジェクトを生成します。

パラメータ

この関数にはパラメータはありません。

戻り値

ありません

例

例1 SolrObject::__construct() 例

<?php
/* ... */
?>

上の例の出力は、 たとえば以下のようになります。

...


デストラクタ

  • ≪ SolrObject::__construct
  • SolrObject::getPropertyNames ≫
  • PHP Manual
  • SolrObject
  • デストラクタ

SolrObject::__destruct

(PECL solr >= 0.9.2)

SolrObject::__destruct — デストラクタ

説明

public SolrObject::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


全てのプロパティ名の配列を返す

  • ≪ SolrObject::__destruct
  • SolrObject::offsetExists ≫
  • PHP Manual
  • SolrObject
  • 全てのプロパティ名の配列を返す

SolrObject::getPropertyNames

(PECL solr >= 0.9.2)

SolrObject::getPropertyNames — 全てのプロパティ名の配列を返す

説明

public SolrObject::getPropertyNames(): array

全てのプロパティ名の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

配列を返します。


プロパティが存在するかチェック

  • ≪ SolrObject::getPropertyNames
  • SolrObject::offsetGet ≫
  • PHP Manual
  • SolrObject
  • プロパティが存在するかチェック

SolrObject::offsetExists

(PECL solr >= 0.9.2)

SolrObject::offsetExists — プロパティが存在するかチェック

説明

public SolrObject::offsetExists(string $property_name): bool

プロパティが存在するかチェックします。これは、オブジェクトが配列として扱われる際に使用されます。

パラメータ

property_name

プロパティ名

戻り値

成功した場合に true を、失敗した場合に false を返します。


プロパティを取得するために使用される

  • ≪ SolrObject::offsetExists
  • SolrObject::offsetSet ≫
  • PHP Manual
  • SolrObject
  • プロパティを取得するために使用される

SolrObject::offsetGet

(PECL solr >= 0.9.2)

SolrObject::offsetGet — プロパティを取得するために使用される

説明

public SolrObject::offsetGet(string $property_name): mixed

プロパティの値を取得するために使用されます。これは、オブジェクトが配列として扱われる際に使用されます。

パラメータ

property_name

プロパティ名

戻り値

プロパティの値を返します。


プロパティに対して値を設定

  • ≪ SolrObject::offsetGet
  • SolrObject::offsetUnset ≫
  • PHP Manual
  • SolrObject
  • プロパティに対して値を設定

SolrObject::offsetSet

(PECL solr >= 0.9.2)

SolrObject::offsetSet — プロパティに対して値を設定

説明

public SolrObject::offsetSet(string $property_name, string $property_value): void

プロパティに対して値を設定します。 これは、オブジェクトが配列として扱われる際に使用されます。 このオブジェクトは読み込み専用です。これは、決して試みられてはいけません。

パラメータ

property_name

プロパティ名

property_value

新しい値

戻り値

ありません


プロパティに対して値の設定を解除

  • ≪ SolrObject::offsetSet
  • SolrClient ≫
  • PHP Manual
  • SolrObject
  • プロパティに対して値の設定を解除

SolrObject::offsetUnset

(PECL solr >= 0.9.2)

SolrObject::offsetUnset — プロパティに対して値の設定を解除

説明

public SolrObject::offsetUnset(string $property_name): void

プロパティに対して値の設定を解除します。これは、オブジェクトが配列として扱われる際に使用されます。 このオブジェクトは読み込み専用です。これは、決して試みられてはいけません。

パラメータ

property_name

プロパティ名

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SolrObject::offsetUnset() の例

<?php
/* ... */
?>

上の例の出力は、 たとえば以下のようになります。

...


The SolrClient class

(PECL solr >= 0.9.2)

はじめに

Used to send requests to a Solr server. Currently, cloning and serialization of SolrClient instances is not supported.

クラス概要

final class SolrClient {
/* 定数 */
const int SEARCH_SERVLET_TYPE = 1;
const int UPDATE_SERVLET_TYPE = 2;
const int THREADS_SERVLET_TYPE = 4;
const int PING_SERVLET_TYPE = 8;
const int TERMS_SERVLET_TYPE = 16;
const int SYSTEM_SERVLET_TYPE = 32;
const string DEFAULT_SEARCH_SERVLET = select;
const string DEFAULT_UPDATE_SERVLET = update;
const string DEFAULT_THREADS_SERVLET = admin/threads;
const string DEFAULT_PING_SERVLET = admin/ping;
const string DEFAULT_TERMS_SERVLET = terms;
const string DEFAULT_SYSTEM_SERVLET = admin/system;
/* メソッド */
public __construct(array $clientOptions)
public addDocument(SolrInputDocument $doc, bool $overwrite = true, int $commitWithin = 0): SolrUpdateResponse
public addDocuments(array $docs, bool $overwrite = true, int $commitWithin = 0): void
public commit(bool $softCommit = false, bool $waitSearcher = true, bool $expungeDeletes = false): SolrUpdateResponse
public deleteById(string $id): SolrUpdateResponse
public deleteByIds(array $ids): SolrUpdateResponse
public deleteByQueries(array $queries): SolrUpdateResponse
public deleteByQuery(string $query): SolrUpdateResponse
public getById(string $id): SolrQueryResponse
public getByIds(array $ids): SolrQueryResponse
public getDebug(): string
public getOptions(): array
public optimize(int $maxSegments = 1, bool $softCommit = true, bool $waitSearcher = true): SolrUpdateResponse
public ping(): SolrPingResponse
public query(SolrParams $query): SolrQueryResponse
public request(string $raw_request): SolrUpdateResponse
public rollback(): SolrUpdateResponse
public setResponseWriter(string $responseWriter): void
public setServlet(int $type, string $value): bool
public system(): void
public threads(): void
public __destruct()
}

定義済み定数

SolrClient::SEARCH_SERVLET_TYPE

Used when updating the search servlet.

SolrClient::UPDATE_SERVLET_TYPE

Used when updating the update servlet.

SolrClient::THREADS_SERVLET_TYPE

Used when updating the threads servlet.

SolrClient::PING_SERVLET_TYPE

Used when updating the ping servlet.

SolrClient::TERMS_SERVLET_TYPE

Used when updating the terms servlet.

SolrClient::SYSTEM_SERVLET_TYPE

Used when retrieving system information from the system servlet.

SolrClient::DEFAULT_SEARCH_SERVLET

This is the initial value for the search servlet.

SolrClient::DEFAULT_UPDATE_SERVLET

This is the initial value for the update servlet.

SolrClient::DEFAULT_THREADS_SERVLET

This is the initial value for the threads servlet.

SolrClient::DEFAULT_PING_SERVLET

This is the initial value for the ping servlet.

SolrClient::DEFAULT_TERMS_SERVLET

This is the initial value for the terms servlet used for the TermsComponent

SolrClient::DEFAULT_SYSTEM_SERVLET

This is the initial value for the system servlet used to obtain Solr Server information

目次

  • SolrClient::addDocument — Adds a document to the index
  • SolrClient::addDocuments — Adds a collection of SolrInputDocument instances to the index
  • SolrClient::commit — Finalizes all add/deletes made to the index
  • SolrClient::__construct — Constructor for the SolrClient object
  • SolrClient::deleteById — Delete by Id
  • SolrClient::deleteByIds — Deletes by Ids
  • SolrClient::deleteByQueries — Removes all documents matching any of the queries
  • SolrClient::deleteByQuery — Deletes all documents matching the given query
  • SolrClient::__destruct — SolrClient に対するデストラクタ
  • SolrClient::getById — Get Document By Id. Utilizes Solr Realtime Get (RTG)
  • SolrClient::getByIds — Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)
  • SolrClient::getDebug — Returns the debug data for the last connection attempt
  • SolrClient::getOptions — Returns the client options set internally
  • SolrClient::optimize — Defragments the index
  • SolrClient::ping — Checks if Solr server is still up
  • SolrClient::query — Sends a query to the server
  • SolrClient::request — Sends a raw update request
  • SolrClient::rollback — Rollbacks all add/deletes made to the index since the last commit
  • SolrClient::setResponseWriter — Sets the response writer used to prepare the response from Solr
  • SolrClient::setServlet — Changes the specified servlet type to a new value
  • SolrClient::system — Retrieve Solr Server information
  • SolrClient::threads — スレッドの状態をチェック


Adds a document to the index

  • ≪ SolrClient
  • SolrClient::addDocuments ≫
  • PHP Manual
  • SolrClient
  • Adds a document to the index

SolrClient::addDocument

(PECL solr >= 0.9.2)

SolrClient::addDocument — Adds a document to the index

説明

public SolrClient::addDocument(SolrInputDocument $doc, bool $overwrite = true, int $commitWithin = 0): SolrUpdateResponse

This method adds a document to the index.

パラメータ

doc

The SolrInputDocument instance.

overwrite

Whether to overwrite existing document or not. If false there will be duplicates (several documents with the same ID).

警告

PECL Solr < 2.0 $allowDups was used instead of $overwrite, which does the same functionality with exact opposite bool flag.

$allowDups = false is the same as $overwrite = true

commitWithin

Number of milliseconds within which to auto commit this document. Available since Solr 1.4 . Default (0) means disabled.

When this value specified, it leaves the control of when to do the commit to Solr itself, optimizing number of commits to a minimum while still fulfilling the update latency requirements, and Solr will automatically do a commit when the oldest add in the buffer is due.

戻り値

Returns a SolrUpdateResponse object or throws an Exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

例

例1 SolrClient::addDocument() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$updateResponse = $client->addDocument($doc);

// you will have to commit changes to be written if you didn't use $commitWithin
$client->commit();

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
        )

)

例2 SolrClient::addDocument() example 2

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

// No need to call commit() because $commitWithin is passed, so Solr Server will auto commit within 10 seconds
$updateResponse = $client->addDocument($doc, false, 10000);

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
        )

)

参考

  • SolrClient::addDocuments() - Adds a collection of SolrInputDocument instances to the index
  • SolrClient::commit() - Finalizes all add/deletes made to the index


Adds a collection of SolrInputDocument instances to the index

  • ≪ SolrClient::addDocument
  • SolrClient::commit ≫
  • PHP Manual
  • SolrClient
  • Adds a collection of SolrInputDocument instances to the index

SolrClient::addDocuments

(PECL solr >= 0.9.2)

SolrClient::addDocuments — Adds a collection of SolrInputDocument instances to the index

説明

public SolrClient::addDocuments(array $docs, bool $overwrite = true, int $commitWithin = 0): void

Adds a collection of documents to the index.

パラメータ

docs

An array containing the collection of SolrInputDocument instances. This array must be an actual variable.

overwrite

Whether to overwrite existing documents or not. If false there will be duplicates (several documents with the same ID).

警告

PECL Solr < 2.0 $allowDups was used instead of $overwrite, which does the same functionality with exact opposite bool flag.

$allowDups = false is the same as $overwrite = true

commitWithin

Number of milliseconds within which to auto commit this document. Available since Solr 1.4 . Default (0) means disabled.

When this value specified, it leaves the control of when to do the commit to Solr itself, optimizing number of commits to a minimum while still fulfilling the update latency requirements, and Solr will automatically do a commit when the oldest add in the buffer is due.

戻り値

Returns a SolrUpdateResponse object or throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

例

例1 SolrClient::addDocuments() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$doc2 = clone $doc;

$doc2->deleteField('id');
$doc2->addField('id', 334456);

$docs = array($doc, $doc2);

$updateResponse = $client->addDocuments($docs);

// no changes will be written to disk unless $commitWithin is passed or SolrClient::commit is called

print_r($updateResponse->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 2
        )

)

参考

  • SolrClient::addDocument() - Adds a document to the index
  • SolrClient::commit() - Finalizes all add/deletes made to the index


Finalizes all add/deletes made to the index

  • ≪ SolrClient::addDocuments
  • SolrClient::__construct ≫
  • PHP Manual
  • SolrClient
  • Finalizes all add/deletes made to the index

SolrClient::commit

(PECL solr >= 0.9.2)

SolrClient::commit — Finalizes all add/deletes made to the index

説明

public SolrClient::commit(bool $softCommit = false, bool $waitSearcher = true, bool $expungeDeletes = false): SolrUpdateResponse

This method finalizes all add/deletes made to the index.

パラメータ

softCommit

This will refresh the 'view' of the index in a more performant manner, but without "on-disk" guarantees. (Solr4.0+)

A soft commit is much faster since it only makes index changes visible and does not fsync index files or write a new index descriptor. If the JVM crashes or there is a loss of power, changes that occurred after the last hard commit will be lost. Search collections that have near-real-time requirements (that want index changes to be quickly visible to searches) will want to soft commit often but hard commit less frequently.

waitSearcher

block until a new searcher is opened and registered as the main query searcher, making the changes visible.

expungeDeletes

Merge segments with deletes away. (Solr1.4+)

戻り値

Returns a SolrUpdateResponse object on success or throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

変更履歴

バージョン | 説明
PECL solr 1.1.0, 2.0.0 | $maxSegments removed
PECL solr 2.0.0b | API Changed: SolrClient::commit ([ int $maxSegments = 0 [, bool $softCommit = false [, bool $waitSearcher = true[, bool $expungeDeletes = false ]]] )
PECL solr 0.9.2 | Signature: SolrClient::commit ([ int $maxSegments = 1 [, bool $waitFlush = true [, bool $waitSearcher = true ]]] ). $waitFlush: Block until index changes are flushed to disk.

注意

警告

PECL Solr >= 2.0 only supports Solr Server >= 4.0

参考

  • SolrClient::optimize() - Defragments the index
  • SolrClient::rollback() - Rollbacks all add/deletes made to the index since the last commit


Constructor for the SolrClient object

  • ≪ SolrClient::commit
  • SolrClient::deleteById ≫
  • PHP Manual
  • SolrClient
  • Constructor for the SolrClient object

SolrClient::__construct

(PECL solr >= 0.9.2)

SolrClient::__construct — Constructor for the SolrClient object

説明

public SolrClient::__construct(array $clientOptions)

Constructor for the SolrClient object

パラメータ

clientOptions

This is an array containing one of the following keys :

- secure          (Boolean value indicating whether or not to connect in secure mode)
 - hostname        (The hostname for the Solr server)
 - port            (The port number)
 - path            (The path to solr)
 - wt              (The name of the response writer e.g. xml, json)
 - login           (The username used for HTTP Authentication, if any)
 - password        (The HTTP Authentication password)
 - proxy_host      (The hostname for the proxy server, if any)
 - proxy_port      (The proxy port)
 - proxy_login     (The proxy username)
 - proxy_password  (The proxy password)
 - timeout         (This is maximum time in seconds allowed for the http data transfer operation. Default is 30 seconds)
 - ssl_cert        (File name to a PEM-formatted file containing the private key + private certificate (concatenated in that order) )
 - ssl_key         (File name to a PEM-formatted private key file only)
 - ssl_keypassword (Password for private key)
 - ssl_cainfo      (Name of file holding one or more CA certificates to verify peer with)
 - ssl_capath      (Name of directory holding multiple CA certificates to verify peer with )

 Please note the if the ssl_cert file only contains the private certificate, you have to specify a separate ssl_key file

 The ssl_keypassword option is required if the ssl_cert or ssl_key options are set.

エラー / 例外

Throws SolrIllegalArgumentException on failure.

例

例1 SolrClient::__construct() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_PATH_TO_SOLR,
'wt' => 'xml',
);

$client = new SolrClient($options);

$doc = new SolrInputDocument();

$doc->addField('id', 334455);
$doc->addField('cat', 'Software');
$doc->addField('cat', 'Lucene');

$updateResponse = $client->addDocument($doc);

?>

上の例の出力は、 たとえば以下のようになります。

参考

  • SolrClient::getOptions() - Returns the client options set internally
    •


Delete by Id

  • ≪ SolrClient::__construct
  • SolrClient::deleteByIds ≫
  • PHP Manual
  • SolrClient
  • Delete by Id

SolrClient::deleteById

(PECL solr >= 0.9.2)

SolrClient::deleteById — Delete by Id

説明

public SolrClient::deleteById(string $id): SolrUpdateResponse

Deletes the document with the specified ID. Where ID is the value of the uniqueKey field declared in the schema

パラメータ

id

The value of the uniqueKey field declared in the schema

戻り値

Returns a SolrUpdateResponse on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

参考

  • SolrClient::deleteByIds() - Deletes by Ids
  • SolrClient::deleteByQuery() - Deletes all documents matching the given query
  • SolrClient::deleteByQueries() - Removes all documents matching any of the queries


Deletes by Ids

  • ≪ SolrClient::deleteById
  • SolrClient::deleteByQueries ≫
  • PHP Manual
  • SolrClient
  • Deletes by Ids

SolrClient::deleteByIds

(PECL solr >= 0.9.2)

SolrClient::deleteByIds — Deletes by Ids

説明

public SolrClient::deleteByIds(array $ids): SolrUpdateResponse

Deletes a collection of documents with the specified set of ids.

パラメータ

ids

An array of IDs representing the uniqueKey field declared in the schema for each document to be deleted. This must be an actual php variable.

戻り値

Returns a SolrUpdateResponse on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

参考

  • SolrClient::deleteById() - Delete by Id
  • SolrClient::deleteByQuery() - Deletes all documents matching the given query
  • SolrClient::deleteByQueries() - Removes all documents matching any of the queries


Removes all documents matching any of the queries

  • ≪ SolrClient::deleteByIds
  • SolrClient::deleteByQuery ≫
  • PHP Manual
  • SolrClient
  • Removes all documents matching any of the queries

SolrClient::deleteByQueries

(PECL solr >= 0.9.2)

SolrClient::deleteByQueries — Removes all documents matching any of the queries

説明

public SolrClient::deleteByQueries(array $queries): SolrUpdateResponse

Removes all documents matching any of the queries

パラメータ

queries

The array of queries. This must be an actual php variable.

戻り値

Returns a SolrUpdateResponse on success and throws a SolrClientException on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

参考

  • SolrClient::deleteById() - Delete by Id
  • SolrClient::deleteByIds() - Deletes by Ids
  • SolrClient::deleteByQuery() - Deletes all documents matching the given query


Deletes all documents matching the given query

  • ≪ SolrClient::deleteByQueries
  • SolrClient::__destruct ≫
  • PHP Manual
  • SolrClient
  • Deletes all documents matching the given query

SolrClient::deleteByQuery

(PECL solr >= 0.9.2)

SolrClient::deleteByQuery — Deletes all documents matching the given query

説明

public SolrClient::deleteByQuery(string $query): SolrUpdateResponse

Deletes all documents matching the given query.

パラメータ

query

The query

戻り値

Returns a SolrUpdateResponse on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

例

例1 SolrQuery::deleteByQuery() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

//This will erase the entire index
$client->deleteByQuery("*:*");
$client->commit();

?>

参考

  • SolrClient::deleteById() - Delete by Id
  • SolrClient::deleteByIds() - Deletes by Ids
  • SolrClient::deleteByQueries() - Removes all documents matching any of the queries


SolrClient に対するデストラクタ

  • ≪ SolrClient::deleteByQuery
  • SolrClient::getById ≫
  • PHP Manual
  • SolrClient
  • SolrClient に対するデストラクタ

SolrClient::__destruct

(PECL solr >= 0.9.2)

SolrClient::__destruct — SolrClient に対するデストラクタ

説明

public SolrClient::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

SolrClient に対するデストラクタ

参考

  • SolrClient::__construct() - Constructor for the SolrClient object


Get Document By Id. Utilizes Solr Realtime Get (RTG)

  • ≪ SolrClient::__destruct
  • SolrClient::getByIds ≫
  • PHP Manual
  • SolrClient
  • Get Document By Id. Utilizes Solr Realtime Get (RTG)

SolrClient::getById

(PECL solr >= 2.2.0)

SolrClient::getById — Get Document By Id. Utilizes Solr Realtime Get (RTG)

説明

public SolrClient::getById(string $id): SolrQueryResponse

Get Document By Id. Utilizes Solr Realtime Get (RTG).

パラメータ

id

Document ID

戻り値

SolrQueryResponse

例

例1 SolrClient::getById() example

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_PATH
);

$client = new SolrClient($options);
$response = $client->getById('GB18030TEST');
print_r($response->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [doc] => SolrObject Object
        (
            [id] => GB18030TEST
            [name] => Array
                (
                    [0] => Test with some GB18030 encoded characters
                )

            [features] => Array
                (
                    [0] => No accents here
                    [1] => ?是一个功能
                    [2] => This is a feature (translated)
                    [3] => ??文件是很有光?
                    [4] => This document is very shiny (translated)
                )

            [price] => Array
                (
                    [0] => 0
                )

            [inStock] => Array
                (
                    [0] => 1
                )

            [_version_] => 1510294336239042560
        )

)

参考

  • SolrClient::getByIds() - Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)


Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

  • ≪ SolrClient::getById
  • SolrClient::getDebug ≫
  • PHP Manual
  • SolrClient
  • Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

SolrClient::getByIds

(PECL solr >= 2.2.0)

SolrClient::getByIds — Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)

説明

public SolrClient::getByIds(array $ids): SolrQueryResponse

Get Documents by their Ids. Utilizes Solr Realtime Get (RTG).

パラメータ

ids

Document ids

戻り値

SolrQueryResponse

例

例1 SolrClient::getByIds() example

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_PATH
);

$client = new SolrClient($options);
$response = $client->getByIds(['GB18030TEST', '6H500F0']);

print_r($response->getResponse());

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [response] => SolrObject Object
        (
            [numFound] => 2
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => GB18030TEST
                            [name] => Array
                                (
                                    [0] => Test with some GB18030 encoded characters
                                )

                            [features] => Array
                                (
                                    [0] => No accents here
                                    [1] => ?是一个功能
                                    [2] => This is a feature (translated)
                                    [3] => ??文件是很有光?
                                    [4] => This document is very shiny (translated)
                                )

                            [price] => Array
                                (
                                    [0] => 0
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [_version_] => 1510294336239042560
                        )

                    [1] => SolrObject Object
                        (
                            [id] => 6H500F0
                            [name] => Array
                                (
                                    [0] => Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300
                                )

                            [manu] => Array
                                (
                                    [0] => Maxtor Corp.
                                )

                            [manu_id_s] => maxtor
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => SATA 3.0Gb/s, NCQ
                                    [1] => 8.5ms seek
                                    [2] => 16MB cache
                                )

                            [price] => Array
                                (
                                    [0] => 350
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 45.17614,-93.87341
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [_version_] => 1510294336449806336
                        )

                )

        )

)

参考

  • SolrClient::getById() - Get Document By Id. Utilizes Solr Realtime Get (RTG)


Returns the debug data for the last connection attempt

  • ≪ SolrClient::getByIds
  • SolrClient::getOptions ≫
  • PHP Manual
  • SolrClient
  • Returns the debug data for the last connection attempt

SolrClient::getDebug

(PECL solr >= 0.9.7)

SolrClient::getDebug — Returns the debug data for the last connection attempt

説明

public SolrClient::getDebug(): string

Returns the debug data for the last connection attempt

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string on success and null if there is nothing to return.


Returns the client options set internally

  • ≪ SolrClient::getDebug
  • SolrClient::optimize ≫
  • PHP Manual
  • SolrClient
  • Returns the client options set internally

SolrClient::getOptions

(PECL solr >= 0.9.6)

SolrClient::getOptions — Returns the client options set internally

説明

public SolrClient::getOptions(): array

Returns the client options set internally. Very useful for debugging. The values returned are readonly and can only be set when the object is instantiated.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array containing all the options for the SolrClient object set internally.

参考

  • SolrClient::__construct() - Constructor for the SolrClient object


Defragments the index

  • ≪ SolrClient::getOptions
  • SolrClient::ping ≫
  • PHP Manual
  • SolrClient
  • Defragments the index

SolrClient::optimize

(PECL solr >= 0.9.2)

SolrClient::optimize — Defragments the index

説明

public SolrClient::optimize(int $maxSegments = 1, bool $softCommit = true, bool $waitSearcher = true): SolrUpdateResponse

Defragments the index for faster search performance.

パラメータ

maxSegments

Optimizes down to at most this number of segments. Since Solr 1.3

softCommit

This will refresh the 'view' of the index in a more performant manner, but without "on-disk" guarantees. (Solr4.0+)

waitSearcher

Block until a new searcher is opened and registered as the main query searcher, making the changes visible.

戻り値

Returns a SolrUpdateResponse on success or throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to process the request.

注意

警告

PECL Solr >= 2.0 only supports Solr Server >= 4.0

Prior to PECL Solr 2.0 this method used to accept these arguments "int $maxSegments, bool $waitFlush, bool $waitSearcher".

参考

  • SolrClient::commit() - Finalizes all add/deletes made to the index
  • SolrClient::rollback() - Rollbacks all add/deletes made to the index since the last commit


Checks if Solr server is still up

  • ≪ SolrClient::optimize
  • SolrClient::query ≫
  • PHP Manual
  • SolrClient
  • Checks if Solr server is still up

SolrClient::ping

(PECL solr >= 0.9.2)

SolrClient::ping — Checks if Solr server is still up

説明

public SolrClient::ping(): SolrPingResponse

Checks if the Solr server is still alive. Sends a HEAD request to the Apache Solr server.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a SolrPingResponse object on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to satisfy the request.

例

例1 SolrClient::ping() example

<?php
$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$pingresponse = $client->ping();

?>

上の例の出力は、 たとえば以下のようになります。


Sends a query to the server

  • ≪ SolrClient::ping
  • SolrClient::request ≫
  • PHP Manual
  • SolrClient
  • Sends a query to the server

SolrClient::query

(PECL solr >= 0.9.2)

SolrClient::query — Sends a query to the server

説明

public SolrClient::query(SolrParams $query): SolrQueryResponse

Sends a query to the server.

パラメータ

query

A SolrParams object. It is recommended to use SolrQuery for advanced queries.

戻り値

Returns a SolrQueryResponse object on success and throws an exception on failure.

エラー / 例外

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to satisfy the query.

例

例1 SolrClient::query() example

<?php

$options = array
(
'hostname' => 'localhost',
'login' => 'username',
'password' => 'password',
'port' => '8983',
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('lucene');

$query->setStart(0);

$query->setRows(50);

$query->addField('cat')->addField('features')->addField('id')->addField('timestamp');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 3
            [params] => SolrObject Object
                (
                    [fl] => cat,features,id,timestamp
                    [indent] => on
                    [start] => 0
                    [q] => lucene
                    [wt] => xml
                    [version] => 2.2
                    [rows] => 50
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 1
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => SOLR1000
                            [cat] => Array
                                (
                                    [0] => software
                                    [1] => search
                                )

                            [features] => Array
                                (
                                    [0] => Advanced Full-Text Search Capabilities using Lucene
                                    [1] => Optimized for High Volume Web Traffic
                                    [2] => Standards Based Open Interfaces - XML and HTTP
                                    [3] => Comprehensive HTML Administration Interfaces
                                    [4] => Scalability - Efficient Replication to other Solr Search Servers
                                    [5] => Flexible and Adaptable with XML configuration and Schema
                                    [6] => Good unicode support: hello (hello with an accent over the e)
                                )

                        )

                )

        )

)


Sends a raw update request

  • ≪ SolrClient::query
  • SolrClient::rollback ≫
  • PHP Manual
  • SolrClient
  • Sends a raw update request

SolrClient::request

(PECL solr >= 0.9.2)

SolrClient::request — Sends a raw update request

説明

public SolrClient::request(string $raw_request): SolrUpdateResponse

Sends a raw XML update request to the server

パラメータ

raw_request

An XML string with the raw request to the server.

戻り値

Returns a SolrUpdateResponse on success. Throws an exception on failure.

エラー / 例外

Throws SolrIllegalArgumentException if raw_request was an empty string

Throws SolrClientException if the client had failed, or there was a connection issue.

Throws SolrServerException if the Solr Server had failed to satisfy the query.

例

例1 SolrClient::request() example

<?php
$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$update_response = $client->request("<commit/>");

$response = $update_response->getResponse();

print_r($response);
?>

上の例の出力は、 たとえば以下のようになります。

...


Rollbacks all add/deletes made to the index since the last commit

  • ≪ SolrClient::request
  • SolrClient::setResponseWriter ≫
  • PHP Manual
  • SolrClient
  • Rollbacks all add/deletes made to the index since the last commit

SolrClient::rollback

(PECL solr >= 0.9.2)

SolrClient::rollback — Rollbacks all add/deletes made to the index since the last commit

説明

public SolrClient::rollback(): SolrUpdateResponse

Rollbacks all add/deletes made to the index since the last commit. It neither calls any event listeners nor creates a new searcher.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a SolrUpdateResponse on success or throws a SolrClientException on failure.

参考

  • SolrClient::commit() - Finalizes all add/deletes made to the index
  • SolrClient::optimize() - Defragments the index


Sets the response writer used to prepare the response from Solr

  • ≪ SolrClient::rollback
  • SolrClient::setServlet ≫
  • PHP Manual
  • SolrClient
  • Sets the response writer used to prepare the response from Solr

SolrClient::setResponseWriter

(PECL solr >= 0.9.11)

SolrClient::setResponseWriter — Sets the response writer used to prepare the response from Solr

説明

public SolrClient::setResponseWriter(string $responseWriter): void

Sets the response writer used to prepare the response from Solr

パラメータ

responseWriter

One of the following:

  • json
  • phps
  • xml

戻り値

値を返しません。

例

例1 SolrClient::setResponseWriter() example

<?php

// This is my custom class for objects
class SolrClass
{
public $_properties = array();

public function __get($property_name) {

if (property_exists($this, $property_name)) {

return $this->$property_name;

} else if (isset($_properties[$property_name])) {

return $_properties[$property_name];
}

return null;
}
}

$options = array
(
'hostname' => 'localhost',
'port' => 8983,
'path' => '/solr/core1'
);

$client = new SolrClient($options);

$client->setResponseWriter("json");

//$response = $client->ping();

$query = new SolrQuery();

$query->setQuery("*:*");

$query->set("objectClassName", "SolrClass");

$query->set("objectPropertiesStorageMode", 1); // 0 for independent properties, 1 for combined

try
{

$response = $client->query($query);

$resp = $response->getResponse();

print_r($response);

print_r($resp);

} catch (Exception $e) {

print_r($e);

}

?>


Changes the specified servlet type to a new value

  • ≪ SolrClient::setResponseWriter
  • SolrClient::system ≫
  • PHP Manual
  • SolrClient
  • Changes the specified servlet type to a new value

SolrClient::setServlet

(PECL solr >= 0.9.2)

SolrClient::setServlet — Changes the specified servlet type to a new value

説明

public SolrClient::setServlet(int $type, string $value): bool

Changes the specified servlet type to a new value

パラメータ

type

One of the following :

- SolrClient::SEARCH_SERVLET_TYPE
 - SolrClient::UPDATE_SERVLET_TYPE
 - SolrClient::THREADS_SERVLET_TYPE
 - SolrClient::PING_SERVLET_TYPE
 - SolrClient::TERMS_SERVLET_TYPE

value

The new value for the servlet

戻り値

成功した場合に true を、失敗した場合に false を返します。


Retrieve Solr Server information

  • ≪ SolrClient::setServlet
  • SolrClient::threads ≫
  • PHP Manual
  • SolrClient
  • Retrieve Solr Server information

SolrClient::system

(PECL solr >= 2.0.0)

SolrClient::system — Retrieve Solr Server information

説明

public SolrClient::system(): void

Retrieve Solr Server information

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a SolrGenericResponse object on success.

エラー / 例外

Emits SolrClientException if the client failed, or there was a connection issue.

Emits SolrServerException if the Solr Server failed to satisfy the query.


スレッドの状態をチェック

  • ≪ SolrClient::system
  • SolrResponse ≫
  • PHP Manual
  • SolrClient
  • スレッドの状態をチェック

SolrClient::threads

(PECL solr >= 0.9.2)

SolrClient::threads — スレッドの状態をチェック

説明

public SolrClient::threads(): void

スレッドの状態をチェック

パラメータ

この関数にはパラメータはありません。

戻り値

SolrGenericResponse オブジェクトを返します。

エラー / 例外

クライアントの処理が失敗した場合や接続に問題が発生した場合に SolrClientException をスローします。

Solr サーバーがリクエストの処理に失敗した場合に SolrServerException をスローします。


SolrResponse クラス

(PECL solr >= 0.9.2)

はじめに

Solr サーバーからのレスポンスを表現

クラス概要

abstract class SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0;
const int PARSE_SOLR_DOC = 1;
/* プロパティ */
protected int $http_status;
protected int $parser_mode;
protected bool $success;
protected string $http_status_message;
protected string $http_request_url;
protected string $http_raw_request_headers;
protected string $http_raw_request;
protected string $http_raw_response_headers;
protected string $http_raw_response;
protected string $http_digested_response;
/* メソッド */
public getDigestedResponse(): string
public getHttpStatus(): int
public getHttpStatusMessage(): string
public getRawRequest(): string
public getRawRequestHeaders(): string
public getRawResponse(): string
public getRawResponseHeaders(): string
public getRequestUrl(): string
public getResponse(): SolrObject
public setParseMode(int $parser_mode = 0): bool
public success(): bool
}

プロパティ

http_status

レスポンスの HTTP ステータス

parser_mode

Solr 文書を SolrObject または SolrDocument インスタンスとしてパースするかどうか

success

リクエスト中にエラーがあったか

http_status_message

HTTP ステータスについての詳細メッセージ

http_request_url

リクエスト URL

http_raw_request_headers

リクエスト中に送信される生のヘッダ文字列

http_raw_request

サーバーに送信される生のリクエスト

http_raw_response_headers

Solr サーバーからのレスポンスヘッダ

http_raw_response

サーバーからのレスポンスメッセージ

http_digested_response

PHP シリアライズ形式でのレスポンス

定義済み定数

SolrResponse クラス定数

SolrResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrResponse::getDigestedResponse — シリアライズされた PHP データとして XML レスポンスを返す
  • SolrResponse::getHttpStatus — レスポンスの HTTP ステータスを返す
  • SolrResponse::getHttpStatusMessage — HTTP ステータスに関する詳細を返す
  • SolrResponse::getRawRequest — Solr サーバーに送られた生のリクエストを返す
  • SolrResponse::getRawRequestHeaders — Solr サーバーに送られた生のリクエストヘッダを返す
  • SolrResponse::getRawResponse — Solr サーバーからの生のレスポンスを返す
  • SolrResponse::getRawResponseHeaders — Solr サーバーからの生のレスポンスヘッダを返す
  • SolrResponse::getRequestUrl — リクエストが送られた完全な URL を返す
  • SolrResponse::getResponse — サーバーからの XML レスポンスを表現する SolrObject を返す
  • SolrResponse::setParseMode — パースモードを設定
  • SolrResponse::success — リクエストが成功したか


シリアライズされた PHP データとして XML レスポンスを返す

  • ≪ SolrResponse
  • SolrResponse::getHttpStatus ≫
  • PHP Manual
  • SolrResponse
  • シリアライズされた PHP データとして XML レスポンスを返す

SolrResponse::getDigestedResponse

(PECL solr >= 0.9.2)

SolrResponse::getDigestedResponse — シリアライズされた PHP データとして XML レスポンスを返す

説明

public SolrResponse::getDigestedResponse(): string

シリアライズされた PHP データとして XML レスポンスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

シリアライズされた PHP データとして XML レスポンスを返します。


レスポンスの HTTP ステータスを返す

  • ≪ SolrResponse::getDigestedResponse
  • SolrResponse::getHttpStatusMessage ≫
  • PHP Manual
  • SolrResponse
  • レスポンスの HTTP ステータスを返す

SolrResponse::getHttpStatus

(PECL solr >= 0.9.2)

SolrResponse::getHttpStatus — レスポンスの HTTP ステータスを返す

説明

public SolrResponse::getHttpStatus(): int

レスポンスの HTTP ステータスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

レスポンスの HTTP ステータスを返します。


HTTP ステータスに関する詳細を返す

  • ≪ SolrResponse::getHttpStatus
  • SolrResponse::getRawRequest ≫
  • PHP Manual
  • SolrResponse
  • HTTP ステータスに関する詳細を返す

SolrResponse::getHttpStatusMessage

(PECL solr >= 0.9.2)

SolrResponse::getHttpStatusMessage — HTTP ステータスに関する詳細を返す

説明

public SolrResponse::getHttpStatusMessage(): string

HTTP ステータスに関する詳細を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

HTTP ステータスに関する詳細を返します。


Solr サーバーに送られた生のリクエストを返す

  • ≪ SolrResponse::getHttpStatusMessage
  • SolrResponse::getRawRequestHeaders ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーに送られた生のリクエストを返す

SolrResponse::getRawRequest

(PECL solr >= 0.9.2)

SolrResponse::getRawRequest — Solr サーバーに送られた生のリクエストを返す

説明

public SolrResponse::getRawRequest(): string

Solr サーバーに送られた生のリクエストを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Solr サーバーに送られた生のリクエストを返します。


Solr サーバーに送られた生のリクエストヘッダを返す

  • ≪ SolrResponse::getRawRequest
  • SolrResponse::getRawResponse ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーに送られた生のリクエストヘッダを返す

SolrResponse::getRawRequestHeaders

(PECL solr >= 0.9.2)

SolrResponse::getRawRequestHeaders — Solr サーバーに送られた生のリクエストヘッダを返す

説明

public SolrResponse::getRawRequestHeaders(): string

Solr サーバーに送られた生のリクエストヘッダを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Solr サーバーに送られた生のリクエストヘッダを返します。


Solr サーバーからの生のレスポンスを返す

  • ≪ SolrResponse::getRawRequestHeaders
  • SolrResponse::getRawResponseHeaders ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーからの生のレスポンスを返す

SolrResponse::getRawResponse

(PECL solr >= 0.9.2)

SolrResponse::getRawResponse — Solr サーバーからの生のレスポンスを返す

説明

public SolrResponse::getRawResponse(): string

Solr サーバーからの生のレスポンスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Solr サーバーからの生のレスポンスを返します。


Solr サーバーからの生のレスポンスヘッダを返す

  • ≪ SolrResponse::getRawResponse
  • SolrResponse::getRequestUrl ≫
  • PHP Manual
  • SolrResponse
  • Solr サーバーからの生のレスポンスヘッダを返す

SolrResponse::getRawResponseHeaders

(PECL solr >= 0.9.2)

SolrResponse::getRawResponseHeaders — Solr サーバーからの生のレスポンスヘッダを返す

説明

public SolrResponse::getRawResponseHeaders(): string

Solr サーバーからの生のレスポンスヘッダを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Solr サーバーからの生のレスポンスヘッダを返します。


リクエストが送られた完全な URL を返す

  • ≪ SolrResponse::getRawResponseHeaders
  • SolrResponse::getResponse ≫
  • PHP Manual
  • SolrResponse
  • リクエストが送られた完全な URL を返す

SolrResponse::getRequestUrl

(PECL solr >= 0.9.2)

SolrResponse::getRequestUrl — リクエストが送られた完全な URL を返す

説明

public SolrResponse::getRequestUrl(): string

リクエストが送られた完全な URL を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

リクエストが送られた完全な URL を返します。


サーバーからの XML レスポンスを表現する SolrObject を返す

  • ≪ SolrResponse::getRequestUrl
  • SolrResponse::setParseMode ≫
  • PHP Manual
  • SolrResponse
  • サーバーからの XML レスポンスを表現する SolrObject を返す

SolrResponse::getResponse

(PECL solr >= 0.9.2)

SolrResponse::getResponse — サーバーからの XML レスポンスを表現する SolrObject を返す

説明

public SolrResponse::getResponse(): SolrObject

サーバーからの XML レスポンスを表現する SolrObject を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

サーバーからの XML レスポンスを表現する SolrObject を返します。


パースモードを設定

  • ≪ SolrResponse::getResponse
  • SolrResponse::success ≫
  • PHP Manual
  • SolrResponse
  • パースモードを設定

SolrResponse::setParseMode

(PECL solr >= 0.9.2)

SolrResponse::setParseMode — パースモードを設定

説明

public SolrResponse::setParseMode(int $parser_mode = 0): bool

パースモードを設定します。

パラメータ

parser_mode

SolrResponse::PARSE_SOLR_DOC は、SolrDocument インスタンス内の文書をパースします。 SolrResponse::PARSE_SOLR_OBJ は、SolrObjects 内に文書をパースします。

戻り値

成功した場合に true を、失敗した場合に false を返します。


リクエストが成功したか

  • ≪ SolrResponse::setParseMode
  • SolrQueryResponse ≫
  • PHP Manual
  • SolrResponse
  • リクエストが成功したか

SolrResponse::success

(PECL solr >= 0.9.2)

SolrResponse::success — リクエストが成功したか

説明

public SolrResponse::success(): bool

サーバーへのリクエストが成功したかチェックするために使用されます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合 true 、失敗した場合 false 。


SolrQueryResponse クラス

(PECL solr >= 0.9.2)

はじめに

クエリーリクエストに対するレスポンスを表現

クラス概要

final class SolrQueryResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0;
const int PARSE_SOLR_DOC = 1;
/* 継承したプロパティ */
const int SolrResponse::PARSE_SOLR_OBJ = 0;
const int SolrResponse::PARSE_SOLR_DOC = 1;
protected int $http_status;
protected int $parser_mode;
protected bool $success;
protected string $http_status_message;
protected string $http_request_url;
protected string $http_raw_request_headers;
protected string $http_raw_request;
protected string $http_raw_response_headers;
protected string $http_raw_response;
protected string $http_digested_response;
/* メソッド */
public __construct()
public __destruct()
/* 継承したメソッド */
public SolrResponse::getDigestedResponse(): string
public SolrResponse::getHttpStatus(): int
public SolrResponse::getHttpStatusMessage(): string
public SolrResponse::getRawRequest(): string
public SolrResponse::getRawRequestHeaders(): string
public SolrResponse::getRawResponse(): string
public SolrResponse::getRawResponseHeaders(): string
public SolrResponse::getRequestUrl(): string
public SolrResponse::getResponse(): SolrObject
public SolrResponse::setParseMode(int $parser_mode = 0): bool
public SolrResponse::success(): bool
}

定義済み定数

SolrQueryResponse クラス定数

SolrQueryResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrQueryResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrQueryResponse::__construct — コンストラクタ
  • SolrQueryResponse::__destruct — デストラクタ


コンストラクタ

  • ≪ SolrQueryResponse
  • SolrQueryResponse::__destruct ≫
  • PHP Manual
  • SolrQueryResponse
  • コンストラクタ

SolrQueryResponse::__construct

(PECL solr >= 0.9.2)

SolrQueryResponse::__construct — コンストラクタ

説明

public SolrQueryResponse::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


デストラクタ

  • ≪ SolrQueryResponse::__construct
  • SolrUpdateResponse ≫
  • PHP Manual
  • SolrQueryResponse
  • デストラクタ

SolrQueryResponse::__destruct

(PECL solr >= 0.9.2)

SolrQueryResponse::__destruct — デストラクタ

説明

public SolrQueryResponse::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


SolrUpdateResponse クラス

(PECL solr >= 0.9.2)

はじめに

更新リクエストに対するレスポンスを表現

クラス概要

final class SolrUpdateResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0;
const int PARSE_SOLR_DOC = 1;
/* 継承したプロパティ */
const int SolrResponse::PARSE_SOLR_OBJ = 0;
const int SolrResponse::PARSE_SOLR_DOC = 1;
protected int $http_status;
protected int $parser_mode;
protected bool $success;
protected string $http_status_message;
protected string $http_request_url;
protected string $http_raw_request_headers;
protected string $http_raw_request;
protected string $http_raw_response_headers;
protected string $http_raw_response;
protected string $http_digested_response;
/* メソッド */
public __construct()
public __destruct()
/* 継承したメソッド */
public SolrResponse::getDigestedResponse(): string
public SolrResponse::getHttpStatus(): int
public SolrResponse::getHttpStatusMessage(): string
public SolrResponse::getRawRequest(): string
public SolrResponse::getRawRequestHeaders(): string
public SolrResponse::getRawResponse(): string
public SolrResponse::getRawResponseHeaders(): string
public SolrResponse::getRequestUrl(): string
public SolrResponse::getResponse(): SolrObject
public SolrResponse::setParseMode(int $parser_mode = 0): bool
public SolrResponse::success(): bool
}

定義済み定数

SolrUpdateResponse クラス定数

SolrUpdateResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrUpdateResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrUpdateResponse::__construct — コンストラクタ
  • SolrUpdateResponse::__destruct — デストラクタ


コンストラクタ

  • ≪ SolrUpdateResponse
  • SolrUpdateResponse::__destruct ≫
  • PHP Manual
  • SolrUpdateResponse
  • コンストラクタ

SolrUpdateResponse::__construct

(PECL solr >= 0.9.2)

SolrUpdateResponse::__construct — コンストラクタ

説明

public SolrUpdateResponse::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


デストラクタ

  • ≪ SolrUpdateResponse::__construct
  • SolrPingResponse ≫
  • PHP Manual
  • SolrUpdateResponse
  • デストラクタ

SolrUpdateResponse::__destruct

(PECL solr >= 0.9.2)

SolrUpdateResponse::__destruct — デストラクタ

説明

public SolrUpdateResponse::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


SolrPingResponse クラス

(PECL solr >= 0.9.2)

はじめに

サーバーへの ping リクエストに対するレスポンスを表現

クラス概要

final class SolrPingResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0;
const int PARSE_SOLR_DOC = 1;
/* プロパティ */
/* メソッド */
public __construct()
public getResponse(): string
public __destruct()
/* 継承したメソッド */
public SolrResponse::getDigestedResponse(): string
public SolrResponse::getHttpStatus(): int
public SolrResponse::getHttpStatusMessage(): string
public SolrResponse::getRawRequest(): string
public SolrResponse::getRawRequestHeaders(): string
public SolrResponse::getRawResponse(): string
public SolrResponse::getRawResponseHeaders(): string
public SolrResponse::getRequestUrl(): string
public SolrResponse::getResponse(): SolrObject
public SolrResponse::setParseMode(int $parser_mode = 0): bool
public SolrResponse::success(): bool
}

プロパティ

http_status

レスポンスの HTTP ステータス

parser_mode

Solr 文書を SolrObject または SolrDocument インスタンスとしてパースするかどうか

success

リクエスト中にエラーがあったか

http_status_message

HTTP ステータスについての詳細メッセージ

http_request_url

リクエスト URL

http_raw_request_headers

リクエスト中に送信される生のヘッダ文字列

http_raw_request

サーバーに送信される生のリクエスト

http_raw_response_headers

Solr サーバーからのレスポンスヘッダ

http_raw_response

サーバーからのレスポンスメッセージ

http_digested_response

PHP シリアライズ形式でのレスポンス

定義済み定数

SolrPingResponse クラス定数

SolrPingResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrPingResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrPingResponse::__construct — コンストラクタ
  • SolrPingResponse::__destruct — デストラクタ
  • SolrPingResponse::getResponse — サーバーからのレスポンスを返す


コンストラクタ

  • ≪ SolrPingResponse
  • SolrPingResponse::__destruct ≫
  • PHP Manual
  • SolrPingResponse
  • コンストラクタ

SolrPingResponse::__construct

(PECL solr >= 0.9.2)

SolrPingResponse::__construct — コンストラクタ

説明

public SolrPingResponse::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


デストラクタ

  • ≪ SolrPingResponse::__construct
  • SolrPingResponse::getResponse ≫
  • PHP Manual
  • SolrPingResponse
  • デストラクタ

SolrPingResponse::__destruct

(PECL solr >= 0.9.2)

SolrPingResponse::__destruct — デストラクタ

説明

public SolrPingResponse::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


サーバーからのレスポンスを返す

  • ≪ SolrPingResponse::__destruct
  • SolrGenericResponse ≫
  • PHP Manual
  • SolrPingResponse
  • サーバーからのレスポンスを返す

SolrPingResponse::getResponse

(PECL solr >= 0.9.2)

SolrPingResponse::getResponse — サーバーからのレスポンスを返す

説明

public SolrPingResponse::getResponse(): string

サーバーからのレスポンスを返します。 HEAD リクエストとしてのリクエストなので、これは空になるはずです。

パラメータ

この関数にはパラメータはありません。

戻り値

空文字列を返します。


SolrGenericResponse クラス

(PECL solr >= 0.9.2)

はじめに

Solr サーバーからのレスポンスを表現

クラス概要

final class SolrGenericResponse extends SolrResponse {
/* 定数 */
const int PARSE_SOLR_OBJ = 0;
const int PARSE_SOLR_DOC = 1;
/* 継承したプロパティ */
const int SolrResponse::PARSE_SOLR_OBJ = 0;
const int SolrResponse::PARSE_SOLR_DOC = 1;
protected int $http_status;
protected int $parser_mode;
protected bool $success;
protected string $http_status_message;
protected string $http_request_url;
protected string $http_raw_request_headers;
protected string $http_raw_request;
protected string $http_raw_response_headers;
protected string $http_raw_response;
protected string $http_digested_response;
/* メソッド */
public __construct()
public __destruct()
/* 継承したメソッド */
public SolrResponse::getDigestedResponse(): string
public SolrResponse::getHttpStatus(): int
public SolrResponse::getHttpStatusMessage(): string
public SolrResponse::getRawRequest(): string
public SolrResponse::getRawRequestHeaders(): string
public SolrResponse::getRawResponse(): string
public SolrResponse::getRawResponseHeaders(): string
public SolrResponse::getRequestUrl(): string
public SolrResponse::getResponse(): SolrObject
public SolrResponse::setParseMode(int $parser_mode = 0): bool
public SolrResponse::success(): bool
}

定義済み定数

SolrGenericResponse クラス定数

SolrGenericResponse::PARSE_SOLR_OBJ

文書は、SolrObject インスタンスとしてパースされなければなりません

SolrGenericResponse::PARSE_SOLR_DOC

文書は、SolrDocument インスタンスとしてパースされなければなりません

目次

  • SolrGenericResponse::__construct — コンストラクタ
  • SolrGenericResponse::__destruct — デストラクタ


コンストラクタ

  • ≪ SolrGenericResponse
  • SolrGenericResponse::__destruct ≫
  • PHP Manual
  • SolrGenericResponse
  • コンストラクタ

SolrGenericResponse::__construct

(PECL solr >= 0.9.2)

SolrGenericResponse::__construct — コンストラクタ

説明

public SolrGenericResponse::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


デストラクタ

  • ≪ SolrGenericResponse::__construct
  • SolrParams ≫
  • PHP Manual
  • SolrGenericResponse
  • デストラクタ

SolrGenericResponse::__destruct

(PECL solr >= 0.9.2)

SolrGenericResponse::__destruct — デストラクタ

説明

public SolrGenericResponse::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


SolrParams クラス

(PECL solr >= 0.9.2)

はじめに

リクエスト中に Solr サーバーに送信される、名前と値のペアの集合を表します。

クラス概要

abstract class SolrParams implements Serializable {
/* メソッド */
final public add(string $name, string $value): SolrParams
public addParam(string $name, string $value): SolrParams
final public get(string $param_name): mixed
final public getParam(string $param_name = ?): mixed
final public getParams(): array
final public getPreparedParams(): array
final public serialize(): string
final public set(string $name, string $value): void
public setParam(string $name, string $value): SolrParams
final public toString(bool $url_encode = false): string
final public unserialize(string $serialized): void
}

目次

  • SolrParams::add — SolrParams::addParam のエイリアス
  • SolrParams::addParam — オブジェクトにパラメータを追加
  • SolrParams::get — SolrParams::getParam のエイリアス
  • SolrParams::getParam — パラメータ値を返す
  • SolrParams::getParams — URL エンコードされていないパラメータの配列を返す
  • SolrParams::getPreparedParams — URL エンコードされたパラメータの配列を返す
  • SolrParams::serialize — カスタムのシリアライズで使われます
  • SolrParams::set — SolrParams::setParam のエイリアス
  • SolrParams::setParam — パラメータを指定された値に設定
  • SolrParams::toString — オブジェクト内の名前と値のペアのパラメータを全て返します
  • SolrParams::unserialize — カスタムのシリアライズで使われます


SolrParams::addParam のエイリアス

  • ≪ SolrParams
  • SolrParams::addParam ≫
  • PHP Manual
  • SolrParams
  • SolrParams::addParam のエイリアス

SolrParams::add

(PECL solr >= 0.9.2)

SolrParams::add — SolrParams::addParam() のエイリアス

説明

final public SolrParams::add(string $name, string $value): SolrParams

これは、SolrParams::addParam に対するエイリアスです。

パラメータ

name

パラメータ名

value

パラメータ値

戻り値

成功時に SolrParams インスタンスを返します


オブジェクトにパラメータを追加

  • ≪ SolrParams::add
  • SolrParams::get ≫
  • PHP Manual
  • SolrParams
  • オブジェクトにパラメータを追加

SolrParams::addParam

(PECL solr >= 0.9.2)

SolrParams::addParam — オブジェクトにパラメータを追加

説明

public SolrParams::addParam(string $name, string $value): SolrParams

オブジェクトにパラメータを追加します。 これは、複数回指定されることのあるパラメータで使われます。

パラメータ

name

パラメータ名

value

パラメータ値

戻り値

成功時に SolrParam オブジェクト、失敗時に false を返します。


SolrParams::getParam のエイリアス

  • ≪ SolrParams::addParam
  • SolrParams::getParam ≫
  • PHP Manual
  • SolrParams
  • SolrParams::getParam のエイリアス

SolrParams::get

(PECL solr >= 0.9.2)

SolrParams::get — SolrParams::getParam() のエイリアス

説明

final public SolrParams::get(string $param_name): mixed

これは、SolrParams::getParam に対するエイリアスです。

パラメータ

param_name

パラメータ名

戻り値

パラメータの種類により、配列または文字列を返します


パラメータ値を返す

  • ≪ SolrParams::get
  • SolrParams::getParams ≫
  • PHP Manual
  • SolrParams
  • パラメータ値を返す

SolrParams::getParam

(PECL solr >= 0.9.2)

SolrParams::getParam — パラメータ値を返す

説明

final public SolrParams::getParam(string $param_name = ?): mixed

param_name という名前のパラメータを返します。

パラメータ

param_name

パラメータ名

戻り値

パラメータの種類により、文字列または配列を返します


URL エンコードされていないパラメータの配列を返す

  • ≪ SolrParams::getParam
  • SolrParams::getPreparedParams ≫
  • PHP Manual
  • SolrParams
  • URL エンコードされていないパラメータの配列を返す

SolrParams::getParams

(PECL solr >= 0.9.2)

SolrParams::getParams — URL エンコードされていないパラメータの配列を返す

説明

final public SolrParams::getParams(): array

URL エンコードされていないパラメータの配列を返します

パラメータ

この関数にはパラメータはありません。

戻り値

URL エンコードされていないパラメータの配列を返します


URL エンコードされたパラメータの配列を返す

  • ≪ SolrParams::getParams
  • SolrParams::serialize ≫
  • PHP Manual
  • SolrParams
  • URL エンコードされたパラメータの配列を返す

SolrParams::getPreparedParams

(PECL solr >= 0.9.2)

SolrParams::getPreparedParams — URL エンコードされたパラメータの配列を返す

説明

final public SolrParams::getPreparedParams(): array

URL エンコードされたパラメータに対する配列を返します

パラメータ

この関数にはパラメータはありません。

戻り値

URL エンコードされたパラメータに対する配列を返します


カスタムのシリアライズで使われます

  • ≪ SolrParams::getPreparedParams
  • SolrParams::set ≫
  • PHP Manual
  • SolrParams
  • カスタムのシリアライズで使われます

SolrParams::serialize

(PECL solr >= 0.9.2)

SolrParams::serialize — カスタムのシリアライズで使われます

説明

final public SolrParams::serialize(): string

カスタムのシリアライズで使われます

パラメータ

この関数にはパラメータはありません。

戻り値

カスタムのシリアライズで使われます


SolrParams::setParam のエイリアス

  • ≪ SolrParams::serialize
  • SolrParams::setParam ≫
  • PHP Manual
  • SolrParams
  • SolrParams::setParam のエイリアス

SolrParams::set

(PECL solr >= 0.9.2)

SolrParams::set — SolrParams::setParam() のエイリアス

説明

final public SolrParams::set(string $name, string $value): void

SolrParams::setParam のエイリアス

パラメータ

name

パラメータ名

value

パラメータ値

戻り値

成功時に、SolrParams オブジェクトのインスタンスを返します


パラメータを指定された値に設定

  • ≪ SolrParams::set
  • SolrParams::toString ≫
  • PHP Manual
  • SolrParams
  • パラメータを指定された値に設定

SolrParams::setParam

(PECL solr >= 0.9.2)

SolrParams::setParam — パラメータを指定された値に設定

説明

public SolrParams::setParam(string $name, string $value): SolrParams

クエリーパラメータを指定された値に設定します。 これは、一回だけ指定可能なパラメータで使われます。 同じパラメータ名で後で呼び出すと、既存の値を上書きします。

パラメータ

name

パラメータ名

value

パラメータ値

戻り値

成功時に SolrParam オブジェクト、値の場合に false を返します。

例

例1 SolrParams::setParam() の例

<?php

$param = new SolrParams();

$param->setParam('q', 'solr')->setParam('rows', 2);

?>

上の例の出力は、 たとえば以下のようになります。


オブジェクト内の名前と値のペアのパラメータを全て返します

  • ≪ SolrParams::setParam
  • SolrParams::unserialize ≫
  • PHP Manual
  • SolrParams
  • オブジェクト内の名前と値のペアのパラメータを全て返します

SolrParams::toString

(PECL solr >= 0.9.2)

SolrParams::toString — オブジェクト内の名前と値のペアのパラメータを全て返します

説明

final public SolrParams::toString(bool $url_encode = false): string

オブジェクト内の名前と値のペアのパラメータを全て返します

パラメータ

url_encode

URL エンコードされた値が返されるかどうか

戻り値

成功時に文字列、失敗時に false を返します。


カスタムのシリアライズで使われます

  • ≪ SolrParams::toString
  • SolrModifiableParams ≫
  • PHP Manual
  • SolrParams
  • カスタムのシリアライズで使われます

SolrParams::unserialize

(PECL solr >= 0.9.2)

SolrParams::unserialize — カスタムのシリアライズで使われます

説明

final public SolrParams::unserialize(string $serialized): void

カスタムのシリアライズで使われます

パラメータ

serialized

オブジェクトのシリアライズされた表現

戻り値

ありません


SolrModifiableParams クラス

(PECL solr >= 0.9.2)

はじめに

リクエスト中に Solr サーバーに送信される名前と値のペアの集合を表現します。

クラス概要

class SolrModifiableParams extends SolrParams implements Serializable {
/* メソッド */
public __construct()
public __destruct()
/* 継承したメソッド */
final public SolrParams::add(string $name, string $value): SolrParams
public SolrParams::addParam(string $name, string $value): SolrParams
final public SolrParams::get(string $param_name): mixed
final public SolrParams::getParam(string $param_name = ?): mixed
final public SolrParams::getParams(): array
final public SolrParams::getPreparedParams(): array
final public SolrParams::serialize(): string
final public SolrParams::set(string $name, string $value): void
public SolrParams::setParam(string $name, string $value): SolrParams
final public SolrParams::toString(bool $url_encode = false): string
final public SolrParams::unserialize(string $serialized): void
}

目次

  • SolrModifiableParams::__construct — コンストラクタ
  • SolrModifiableParams::__destruct — デストラクタ


コンストラクタ

  • ≪ SolrModifiableParams
  • SolrModifiableParams::__destruct ≫
  • PHP Manual
  • SolrModifiableParams
  • コンストラクタ

SolrModifiableParams::__construct

(PECL solr >= 0.9.2)

SolrModifiableParams::__construct — コンストラクタ

説明

public SolrModifiableParams::__construct()

コンストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


デストラクタ

  • ≪ SolrModifiableParams::__construct
  • SolrQuery ≫
  • PHP Manual
  • SolrModifiableParams
  • デストラクタ

SolrModifiableParams::__destruct

(PECL solr >= 0.9.2)

SolrModifiableParams::__destruct — デストラクタ

説明

public SolrModifiableParams::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


The SolrQuery class

(PECL solr >= 0.9.2)

はじめに

Represents a collection of name-value pairs sent to the Solr server during a request.

クラス概要

class SolrQuery extends SolrModifiableParams implements Serializable {
/* 定数 */
const int ORDER_ASC = 0;
const int ORDER_DESC = 1;
const int FACET_SORT_INDEX = 0;
const int FACET_SORT_COUNT = 1;
const int TERMS_SORT_INDEX = 0;
const int TERMS_SORT_COUNT = 1;
/* プロパティ */
/* メソッド */
public __construct(string $q = ?)
public addExpandFilterQuery(string $fq): SolrQuery
public addExpandSortField(string $field, string $order = ?): SolrQuery
public addFacetDateField(string $dateField): SolrQuery
public addFacetDateOther(string $value, string $field_override = ?): SolrQuery
public addFacetField(string $field): SolrQuery
public addFacetQuery(string $facetQuery): SolrQuery
public addField(string $field): SolrQuery
public addFilterQuery(string $fq): SolrQuery
public addGroupField(string $value): SolrQuery
public addGroupFunction(string $value): SolrQuery
public addGroupQuery(string $value): SolrQuery
public addGroupSortField(string $field, int $order = ?): SolrQuery
public addHighlightField(string $field): SolrQuery
public addMltField(string $field): SolrQuery
public addMltQueryField(string $field, float $boost): SolrQuery
public addSortField(string $field, int $order = SolrQuery::ORDER_DESC): SolrQuery
public addStatsFacet(string $field): SolrQuery
public addStatsField(string $field): SolrQuery
public collapse(SolrCollapseFunction $collapseFunction): SolrQuery
public getExpand(): bool
public getExpandFilterQueries(): array
public getExpandQuery(): array
public getExpandRows(): int
public getExpandSortFields(): array
public getFacet(): bool
public getFacetDateEnd(string $field_override = ?): string
public getFacetDateFields(): array
public getFacetDateGap(string $field_override = ?): string
public getFacetDateHardEnd(string $field_override = ?): string
public getFacetDateOther(string $field_override = ?): array
public getFacetDateStart(string $field_override = ?): string
public getFacetFields(): array
public getFacetLimit(string $field_override = ?): int
public getFacetMethod(string $field_override = ?): string
public getFacetMinCount(string $field_override = ?): int
public getFacetMissing(string $field_override = ?): bool
public getFacetOffset(string $field_override = ?): int
public getFacetPrefix(string $field_override = ?): string
public getFacetQueries(): array
public getFacetSort(string $field_override = ?): int
public getFields(): array
public getFilterQueries(): array
public getGroup(): bool
public getGroupCachePercent(): int
public getGroupFacet(): bool
public getGroupFields(): array
public getGroupFormat(): string
public getGroupFunctions(): array
public getGroupLimit(): int
public getGroupMain(): bool
public getGroupNGroups(): bool
public getGroupOffset(): int
public getGroupQueries(): array
public getGroupSortFields(): array
public getGroupTruncate(): bool
public getHighlight(): bool
public getHighlightAlternateField(string $field_override = ?): string
public getHighlightFields(): array
public getHighlightFormatter(string $field_override = ?): string
public getHighlightFragmenter(string $field_override = ?): string
public getHighlightFragsize(string $field_override = ?): int
public getHighlightHighlightMultiTerm(): bool
public getHighlightMaxAlternateFieldLength(string $field_override = ?): int
public getHighlightMaxAnalyzedChars(): int
public getHighlightMergeContiguous(string $field_override = ?): bool
public getHighlightRegexMaxAnalyzedChars(): int
public getHighlightRegexPattern(): string
public getHighlightRegexSlop(): float
public getHighlightRequireFieldMatch(): bool
public getHighlightSimplePost(string $field_override = ?): string
public getHighlightSimplePre(string $field_override = ?): string
public getHighlightSnippets(string $field_override = ?): int
public getHighlightUsePhraseHighlighter(): bool
public getMlt(): bool
public getMltBoost(): bool
public getMltCount(): int
public getMltFields(): array
public getMltMaxNumQueryTerms(): int
public getMltMaxNumTokens(): int
public getMltMaxWordLength(): int
public getMltMinDocFrequency(): int
public getMltMinTermFrequency(): int
public getMltMinWordLength(): int
public getMltQueryFields(): array
public getQuery(): string
public getRows(): int
public getSortFields(): array
public getStart(): int
public getStats(): bool
public getStatsFacets(): array
public getStatsFields(): array
public getTerms(): bool
public getTermsField(): string
public getTermsIncludeLowerBound(): bool
public getTermsIncludeUpperBound(): bool
public getTermsLimit(): int
public getTermsLowerBound(): string
public getTermsMaxCount(): int
public getTermsMinCount(): int
public getTermsPrefix(): string
public getTermsReturnRaw(): bool
public getTermsSort(): int
public getTermsUpperBound(): string
public getTimeAllowed(): int
public removeExpandFilterQuery(string $fq): SolrQuery
public removeExpandSortField(string $field): SolrQuery
public removeFacetDateField(string $field): SolrQuery
public removeFacetDateOther(string $value, string $field_override = ?): SolrQuery
public removeFacetField(string $field): SolrQuery
public removeFacetQuery(string $value): SolrQuery
public removeField(string $field): SolrQuery
public removeFilterQuery(string $fq): SolrQuery
public removeHighlightField(string $field): SolrQuery
public removeMltField(string $field): SolrQuery
public removeMltQueryField(string $queryField): SolrQuery
public removeSortField(string $field): SolrQuery
public removeStatsFacet(string $value): SolrQuery
public removeStatsField(string $field): SolrQuery
public setEchoHandler(bool $flag): SolrQuery
public setEchoParams(string $type): SolrQuery
public setExpand(bool $value): SolrQuery
public setExpandQuery(string $q): SolrQuery
public setExpandRows(int $value): SolrQuery
public setExplainOther(string $query): SolrQuery
public setFacet(bool $flag): SolrQuery
public setFacetDateEnd(string $value, string $field_override = ?): SolrQuery
public setFacetDateGap(string $value, string $field_override = ?): SolrQuery
public setFacetDateHardEnd(bool $value, string $field_override = ?): SolrQuery
public setFacetDateStart(string $value, string $field_override = ?): SolrQuery
public setFacetEnumCacheMinDefaultFrequency(int $frequency, string $field_override = ?): SolrQuery
public setFacetLimit(int $limit, string $field_override = ?): SolrQuery
public setFacetMethod(string $method, string $field_override = ?): SolrQuery
public setFacetMinCount(int $mincount, string $field_override = ?): SolrQuery
public setFacetMissing(bool $flag, string $field_override = ?): SolrQuery
public setFacetOffset(int $offset, string $field_override = ?): SolrQuery
public setFacetPrefix(string $prefix, string $field_override = ?): SolrQuery
public setFacetSort(int $facetSort, string $field_override = ?): SolrQuery
public setGroup(bool $value): SolrQuery
public setGroupCachePercent(int $percent): SolrQuery
public setGroupFacet(bool $value): SolrQuery
public setGroupFormat(string $value): SolrQuery
public setGroupLimit(int $value): SolrQuery
public setGroupMain(string $value): SolrQuery
public setGroupNGroups(bool $value): SolrQuery
public setGroupOffset(int $value): SolrQuery
public setGroupTruncate(bool $value): SolrQuery
public setHighlight(bool $flag): SolrQuery
public setHighlightAlternateField(string $field, string $field_override = ?): SolrQuery
public setHighlightFormatter(string $formatter, string $field_override = ?): SolrQuery
public setHighlightFragmenter(string $fragmenter, string $field_override = ?): SolrQuery
public setHighlightFragsize(int $size, string $field_override = ?): SolrQuery
public setHighlightHighlightMultiTerm(bool $flag): SolrQuery
public setHighlightMaxAlternateFieldLength(int $fieldLength, string $field_override = ?): SolrQuery
public setHighlightMaxAnalyzedChars(int $value): SolrQuery
public setHighlightMergeContiguous(bool $flag, string $field_override = ?): SolrQuery
public setHighlightRegexMaxAnalyzedChars(int $maxAnalyzedChars): SolrQuery
public setHighlightRegexPattern(string $value): SolrQuery
public setHighlightRegexSlop(float $factor): SolrQuery
public setHighlightRequireFieldMatch(bool $flag): SolrQuery
public setHighlightSimplePost(string $simplePost, string $field_override = ?): SolrQuery
public setHighlightSimplePre(string $simplePre, string $field_override = ?): SolrQuery
public setHighlightSnippets(int $value, string $field_override = ?): SolrQuery
public setHighlightUsePhraseHighlighter(bool $flag): SolrQuery
public setMlt(bool $flag): SolrQuery
public setMltBoost(bool $flag): SolrQuery
public setMltCount(int $count): SolrQuery
public setMltMaxNumQueryTerms(int $value): SolrQuery
public setMltMaxNumTokens(int $value): SolrQuery
public setMltMaxWordLength(int $maxWordLength): SolrQuery
public setMltMinDocFrequency(int $minDocFrequency): SolrQuery
public setMltMinTermFrequency(int $minTermFrequency): SolrQuery
public setMltMinWordLength(int $minWordLength): SolrQuery
public setOmitHeader(bool $flag): SolrQuery
public setQuery(string $query): SolrQuery
public setRows(int $rows): SolrQuery
public setShowDebugInfo(bool $flag): SolrQuery
public setStart(int $start): SolrQuery
public setStats(bool $flag): SolrQuery
public setTerms(bool $flag): SolrQuery
public setTermsField(string $fieldname): SolrQuery
public setTermsIncludeLowerBound(bool $flag): SolrQuery
public setTermsIncludeUpperBound(bool $flag): SolrQuery
public setTermsLimit(int $limit): SolrQuery
public setTermsLowerBound(string $lowerBound): SolrQuery
public setTermsMaxCount(int $frequency): SolrQuery
public setTermsMinCount(int $frequency): SolrQuery
public setTermsPrefix(string $prefix): SolrQuery
public setTermsReturnRaw(bool $flag): SolrQuery
public setTermsSort(int $sortType): SolrQuery
public setTermsUpperBound(string $upperBound): SolrQuery
public setTimeAllowed(int $timeAllowed): SolrQuery
public __destruct()
/* 継承したメソッド */
public SolrModifiableParams::__construct()
public SolrModifiableParams::__destruct()
}

定義済み定数

SolrQuery::ORDER_ASC

Used to specify that the sorting should be in acending order

SolrQuery::ORDER_DESC

Used to specify that the sorting should be in descending order

SolrQuery::FACET_SORT_INDEX

Used to specify that the facet should sort by index

SolrQuery::FACET_SORT_COUNT

Used to specify that the facet should sort by count

SolrQuery::TERMS_SORT_INDEX

Used in the TermsComponent

SolrQuery::TERMS_SORT_COUNT

Used in the TermsComponent

目次

  • SolrQuery::addExpandFilterQuery — Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::addExpandSortField — Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::addFacetDateField — Maps to facet.date
  • SolrQuery::addFacetDateOther — Adds another facet.date.other parameter
  • SolrQuery::addFacetField — Adds another field to the facet
  • SolrQuery::addFacetQuery — Adds a facet query
  • SolrQuery::addField — Specifies which fields to return in the result
  • SolrQuery::addFilterQuery — Specifies a filter query
  • SolrQuery::addGroupField — Add a field to be used to group results
  • SolrQuery::addGroupFunction — Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery — Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField — Add a group sort field (group.sort parameter)
  • SolrQuery::addHighlightField — Maps to hl.fl
  • SolrQuery::addMltField — Sets a field to use for similarity
  • SolrQuery::addMltQueryField — Maps to mlt.qf
  • SolrQuery::addSortField — Used to control how the results should be sorted
  • SolrQuery::addStatsFacet — Requests a return of sub results for values within the given facet
  • SolrQuery::addStatsField — Maps to stats.field parameter
  • SolrQuery::collapse — Collapses the result set to a single document per group
  • SolrQuery::__construct — コンストラクタ
  • SolrQuery::__destruct — デストラクタ
  • SolrQuery::getExpand — Returns true if group expanding is enabled
  • SolrQuery::getExpandFilterQueries — Returns the expand filter queries
  • SolrQuery::getExpandQuery — Returns the expand query expand.q parameter
  • SolrQuery::getExpandRows — Returns The number of rows to display in each group (expand.rows)
  • SolrQuery::getExpandSortFields — Returns an array of fields
  • SolrQuery::getFacet — Returns the value of the facet parameter
  • SolrQuery::getFacetDateEnd — Returns the value for the facet.date.end parameter
  • SolrQuery::getFacetDateFields — Returns all the facet.date fields
  • SolrQuery::getFacetDateGap — Returns the value of the facet.date.gap parameter
  • SolrQuery::getFacetDateHardEnd — Returns the value of the facet.date.hardend parameter
  • SolrQuery::getFacetDateOther — Returns the value for the facet.date.other parameter
  • SolrQuery::getFacetDateStart — Returns the lower bound for the first date range for all date faceting on this field
  • SolrQuery::getFacetFields — Returns all the facet fields
  • SolrQuery::getFacetLimit — Returns the maximum number of constraint counts that should be returned for the facet fields
  • SolrQuery::getFacetMethod — Returns the value of the facet.method parameter
  • SolrQuery::getFacetMinCount — Returns the minimum counts for facet fields should be included in the response
  • SolrQuery::getFacetMissing — Returns the current state of the facet.missing parameter
  • SolrQuery::getFacetOffset — Returns an offset into the list of constraints to be used for pagination
  • SolrQuery::getFacetPrefix — Returns the facet prefix
  • SolrQuery::getFacetQueries — Returns all the facet queries
  • SolrQuery::getFacetSort — Returns the facet sort type
  • SolrQuery::getFields — Returns the list of fields that will be returned in the response
  • SolrQuery::getFilterQueries — Returns an array of filter queries
  • SolrQuery::getGroup — Returns true if grouping is enabled
  • SolrQuery::getGroupCachePercent — Returns group cache percent value
  • SolrQuery::getGroupFacet — Returns the group.facet parameter value
  • SolrQuery::getGroupFields — Returns group fields (group.field parameter values)
  • SolrQuery::getGroupFormat — Returns the group.format value
  • SolrQuery::getGroupFunctions — Returns group functions (group.func parameter values)
  • SolrQuery::getGroupLimit — Returns the group.limit value
  • SolrQuery::getGroupMain — Returns the group.main value
  • SolrQuery::getGroupNGroups — Returns the group.ngroups value
  • SolrQuery::getGroupOffset — Returns the group.offset value
  • SolrQuery::getGroupQueries — Returns all the group.query parameter values
  • SolrQuery::getGroupSortFields — Returns the group.sort value
  • SolrQuery::getGroupTruncate — Returns the group.truncate value
  • SolrQuery::getHighlight — Returns the state of the hl parameter
  • SolrQuery::getHighlightAlternateField — Returns the highlight field to use as backup or default
  • SolrQuery::getHighlightFields — Returns all the fields that Solr should generate highlighted snippets for
  • SolrQuery::getHighlightFormatter — Returns the formatter for the highlighted output
  • SolrQuery::getHighlightFragmenter — Returns the text snippet generator for highlighted text
  • SolrQuery::getHighlightFragsize — Returns the number of characters of fragments to consider for highlighting
  • SolrQuery::getHighlightHighlightMultiTerm — Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries
  • SolrQuery::getHighlightMaxAlternateFieldLength — Returns the maximum number of characters of the field to return
  • SolrQuery::getHighlightMaxAnalyzedChars — Returns the maximum number of characters into a document to look for suitable snippets
  • SolrQuery::getHighlightMergeContiguous — Returns whether or not the collapse contiguous fragments into a single fragment
  • SolrQuery::getHighlightRegexMaxAnalyzedChars — Returns the maximum number of characters from a field when using the regex fragmenter
  • SolrQuery::getHighlightRegexPattern — Returns the regular expression for fragmenting
  • SolrQuery::getHighlightRegexSlop — Returns the deviation factor from the ideal fragment size
  • SolrQuery::getHighlightRequireFieldMatch — Returns if a field will only be highlighted if the query matched in this particular field
  • SolrQuery::getHighlightSimplePost — Returns the text which appears after a highlighted term
  • SolrQuery::getHighlightSimplePre — Returns the text which appears before a highlighted term
  • SolrQuery::getHighlightSnippets — Returns the maximum number of highlighted snippets to generate per field
  • SolrQuery::getHighlightUsePhraseHighlighter — Returns the state of the hl.usePhraseHighlighter parameter
  • SolrQuery::getMlt — Returns whether or not MoreLikeThis results should be enabled
  • SolrQuery::getMltBoost — Returns whether or not the query will be boosted by the interesting term relevance
  • SolrQuery::getMltCount — Returns the number of similar documents to return for each result
  • SolrQuery::getMltFields — Returns all the fields to use for similarity
  • SolrQuery::getMltMaxNumQueryTerms — Returns the maximum number of query terms that will be included in any generated query
  • SolrQuery::getMltMaxNumTokens — Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support
  • SolrQuery::getMltMaxWordLength — Returns the maximum word length above which words will be ignored
  • SolrQuery::getMltMinDocFrequency — Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs
  • SolrQuery::getMltMinTermFrequency — Returns the frequency below which terms will be ignored in the source document
  • SolrQuery::getMltMinWordLength — Returns the minimum word length below which words will be ignored
  • SolrQuery::getMltQueryFields — Returns the query fields and their boosts
  • SolrQuery::getQuery — 主なクエリーを返す
  • SolrQuery::getRows — Returns the maximum number of documents
  • SolrQuery::getSortFields — Returns all the sort fields
  • SolrQuery::getStart — Returns the offset in the complete result set
  • SolrQuery::getStats — Returns whether or not stats is enabled
  • SolrQuery::getStatsFacets — Returns all the stats facets that were set
  • SolrQuery::getStatsFields — Returns all the statistics fields
  • SolrQuery::getTerms — Returns whether or not the TermsComponent is enabled
  • SolrQuery::getTermsField — Returns the field from which the terms are retrieved
  • SolrQuery::getTermsIncludeLowerBound — Returns whether or not to include the lower bound in the result set
  • SolrQuery::getTermsIncludeUpperBound — Returns whether or not to include the upper bound term in the result set
  • SolrQuery::getTermsLimit — Returns the maximum number of terms Solr should return
  • SolrQuery::getTermsLowerBound — Returns the term to start at
  • SolrQuery::getTermsMaxCount — Returns the maximum document frequency
  • SolrQuery::getTermsMinCount — Returns the minimum document frequency to return in order to be included
  • SolrQuery::getTermsPrefix — Returns the term prefix
  • SolrQuery::getTermsReturnRaw — Whether or not to return raw characters
  • SolrQuery::getTermsSort — Returns an integer indicating how terms are sorted
  • SolrQuery::getTermsUpperBound — Returns the term to stop at
  • SolrQuery::getTimeAllowed — Returns the time in milliseconds allowed for the query to finish
  • SolrQuery::removeExpandFilterQuery — Removes an expand filter query
  • SolrQuery::removeExpandSortField — Removes an expand sort field from the expand.sort parameter
  • SolrQuery::removeFacetDateField — Removes one of the facet date fields
  • SolrQuery::removeFacetDateOther — Removes one of the facet.date.other parameters
  • SolrQuery::removeFacetField — Removes one of the facet.date parameters
  • SolrQuery::removeFacetQuery — Removes one of the facet.query parameters
  • SolrQuery::removeField — Removes a field from the list of fields
  • SolrQuery::removeFilterQuery — Removes a filter query
  • SolrQuery::removeHighlightField — Removes one of the fields used for highlighting
  • SolrQuery::removeMltField — Removes one of the moreLikeThis fields
  • SolrQuery::removeMltQueryField — Removes one of the moreLikeThis query fields
  • SolrQuery::removeSortField — Removes one of the sort fields
  • SolrQuery::removeStatsFacet — Removes one of the stats.facet parameters
  • SolrQuery::removeStatsField — Removes one of the stats.field parameters
  • SolrQuery::setEchoHandler — Toggles the echoHandler parameter
  • SolrQuery::setEchoParams — Determines what kind of parameters to include in the response
  • SolrQuery::setExpand — Enables/Disables the Expand Component
  • SolrQuery::setExpandQuery — Sets the expand.q parameter
  • SolrQuery::setExpandRows — Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExplainOther — Sets the explainOther common query parameter
  • SolrQuery::setFacet — Maps to the facet parameter. Enables or disables facetting
  • SolrQuery::setFacetDateEnd — Maps to facet.date.end
  • SolrQuery::setFacetDateGap — Maps to facet.date.gap
  • SolrQuery::setFacetDateHardEnd — Maps to facet.date.hardend
  • SolrQuery::setFacetDateStart — Maps to facet.date.start
  • SolrQuery::setFacetEnumCacheMinDefaultFrequency — Sets the minimum document frequency used for determining term count
  • SolrQuery::setFacetLimit — Maps to facet.limit
  • SolrQuery::setFacetMethod — Specifies the type of algorithm to use when faceting a field
  • SolrQuery::setFacetMinCount — Maps to facet.mincount
  • SolrQuery::setFacetMissing — Maps to facet.missing
  • SolrQuery::setFacetOffset — Sets the offset into the list of constraints to allow for pagination
  • SolrQuery::setFacetPrefix — Specifies a string prefix with which to limits the terms on which to facet
  • SolrQuery::setFacetSort — Determines the ordering of the facet field constraints
  • SolrQuery::setGroup — Enable/Disable result grouping (group parameter)
  • SolrQuery::setGroupCachePercent — Enables caching for result grouping
  • SolrQuery::setGroupFacet — Sets group.facet parameter
  • SolrQuery::setGroupFormat — Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupLimit — Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain — If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups — If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupOffset — Sets the group.offset parameter
  • SolrQuery::setGroupTruncate — If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setHighlight — Enables or disables highlighting
  • SolrQuery::setHighlightAlternateField — Specifies the backup field to use
  • SolrQuery::setHighlightFormatter — Specify a formatter for the highlight output
  • SolrQuery::setHighlightFragmenter — Sets a text snippet generator for highlighted text
  • SolrQuery::setHighlightFragsize — The size of fragments to consider for highlighting
  • SolrQuery::setHighlightHighlightMultiTerm — Use SpanScorer to highlight phrase terms
  • SolrQuery::setHighlightMaxAlternateFieldLength — Sets the maximum number of characters of the field to return
  • SolrQuery::setHighlightMaxAnalyzedChars — Specifies the number of characters into a document to look for suitable snippets
  • SolrQuery::setHighlightMergeContiguous — Whether or not to collapse contiguous fragments into a single fragment
  • SolrQuery::setHighlightRegexMaxAnalyzedChars — Specify the maximum number of characters to analyze
  • SolrQuery::setHighlightRegexPattern — Specify the regular expression for fragmenting
  • SolrQuery::setHighlightRegexSlop — Sets the factor by which the regex fragmenter can stray from the ideal fragment size
  • SolrQuery::setHighlightRequireFieldMatch — Require field matching during highlighting
  • SolrQuery::setHighlightSimplePost — Sets the text which appears after a highlighted term
  • SolrQuery::setHighlightSimplePre — Sets the text which appears before a highlighted term
  • SolrQuery::setHighlightSnippets — Sets the maximum number of highlighted snippets to generate per field
  • SolrQuery::setHighlightUsePhraseHighlighter — Whether to highlight phrase terms only when they appear within the query phrase
  • SolrQuery::setMlt — Enables or disables moreLikeThis
  • SolrQuery::setMltBoost — Set if the query will be boosted by the interesting term relevance
  • SolrQuery::setMltCount — Set the number of similar documents to return for each result
  • SolrQuery::setMltMaxNumQueryTerms — Sets the maximum number of query terms included
  • SolrQuery::setMltMaxNumTokens — Specifies the maximum number of tokens to parse
  • SolrQuery::setMltMaxWordLength — Sets the maximum word length
  • SolrQuery::setMltMinDocFrequency — Sets the mltMinDoc frequency
  • SolrQuery::setMltMinTermFrequency — Sets the frequency below which terms will be ignored in the source docs
  • SolrQuery::setMltMinWordLength — Sets the minimum word length
  • SolrQuery::setOmitHeader — Exclude the header from the returned results
  • SolrQuery::setQuery — 検索クエリーを設定
  • SolrQuery::setRows — Specifies the maximum number of rows to return in the result
  • SolrQuery::setShowDebugInfo — Flag to show debug information
  • SolrQuery::setStart — Specifies the number of rows to skip
  • SolrQuery::setStats — Enables or disables the Stats component
  • SolrQuery::setTerms — Enables or disables the TermsComponent
  • SolrQuery::setTermsField — Sets the name of the field to get the Terms from
  • SolrQuery::setTermsIncludeLowerBound — Include the lower bound term in the result set
  • SolrQuery::setTermsIncludeUpperBound — Include the upper bound term in the result set
  • SolrQuery::setTermsLimit — Sets the maximum number of terms to return
  • SolrQuery::setTermsLowerBound — Specifies the Term to start from
  • SolrQuery::setTermsMaxCount — Sets the maximum document frequency
  • SolrQuery::setTermsMinCount — Sets the minimum document frequency
  • SolrQuery::setTermsPrefix — Restrict matches to terms that start with the prefix
  • SolrQuery::setTermsReturnRaw — Return the raw characters of the indexed term
  • SolrQuery::setTermsSort — Specifies how to sort the returned terms
  • SolrQuery::setTermsUpperBound — Sets the term to stop at
  • SolrQuery::setTimeAllowed — The time allowed for search to finish


Overrides main filter query, determines which documents to include in the main group

  • ≪ SolrQuery
  • SolrQuery::addExpandSortField ≫
  • PHP Manual
  • SolrQuery
  • Overrides main filter query, determines which documents to include in the main group

SolrQuery::addExpandFilterQuery

(PECL solr >= 2.2.0)

SolrQuery::addExpandFilterQuery — Overrides main filter query, determines which documents to include in the main group

説明

public SolrQuery::addExpandFilterQuery(string $fq): SolrQuery

Overrides main filter query, determines which documents to include in the main group.

パラメータ

fq

戻り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query


Orders the documents within the expanded groups (expand.sort parameter)

  • ≪ SolrQuery::addExpandFilterQuery
  • SolrQuery::addFacetDateField ≫
  • PHP Manual
  • SolrQuery
  • Orders the documents within the expanded groups (expand.sort parameter)

SolrQuery::addExpandSortField

(PECL solr >= 2.2.0)

SolrQuery::addExpandSortField — Orders the documents within the expanded groups (expand.sort parameter)

説明

public SolrQuery::addExpandSortField(string $field, string $order = ?): SolrQuery

Orders the documents within the expanded groups (expand.sort parameter).

パラメータ

field

field name

order

Order ASC/DESC, utilizes SolrQuery::ORDER_* constants.

Default: SolrQuery::ORDER_DESC

戻り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query


Maps to facet.date

  • ≪ SolrQuery::addExpandSortField
  • SolrQuery::addFacetDateOther ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date

SolrQuery::addFacetDateField

(PECL solr >= 0.9.2)

SolrQuery::addFacetDateField — Maps to facet.date

説明

public SolrQuery::addFacetDateField(string $dateField): SolrQuery

This method allows you to specify a field which should be treated as a facet.

It can be used multiple times with different field names to indicate multiple facet fields

パラメータ

dateField

The name of the date field.

戻り値

Returns a SolrQuery object.


Adds another facet.date.other parameter

  • ≪ SolrQuery::addFacetDateField
  • SolrQuery::addFacetField ≫
  • PHP Manual
  • SolrQuery
  • Adds another facet.date.other parameter

SolrQuery::addFacetDateOther

(PECL solr >= 0.9.2)

SolrQuery::addFacetDateOther — Adds another facet.date.other parameter

説明

public SolrQuery::addFacetDateOther(string $value, string $field_override = ?): SolrQuery

Sets the facet.date.other parameter. Accepts an optional field override

パラメータ

value

The value to use.

field_override

The field name for the override.

戻り値

Returns the current SolrQuery object, if the return value is used.


Adds another field to the facet

  • ≪ SolrQuery::addFacetDateOther
  • SolrQuery::addFacetQuery ≫
  • PHP Manual
  • SolrQuery
  • Adds another field to the facet

SolrQuery::addFacetField

(PECL solr >= 0.9.2)

SolrQuery::addFacetField — Adds another field to the facet

説明

public SolrQuery::addFacetField(string $field): SolrQuery

Adds another field to the facet

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.

例

例1 SolrQuery::addFacetField() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery($query);

$query->addField('price')->addField('color');

$query->setFacet(true);

$query->addFacetField('price')->addFacetField('color');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response['facet_counts']['facet_fields']);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [color] => SolrObject Object
        (
            [blue] => 20
            [green] => 100
        )

)


Adds a facet query

  • ≪ SolrQuery::addFacetField
  • SolrQuery::addField ≫
  • PHP Manual
  • SolrQuery
  • Adds a facet query

SolrQuery::addFacetQuery

(PECL solr >= 0.9.2)

SolrQuery::addFacetQuery — Adds a facet query

説明

public SolrQuery::addFacetQuery(string $facetQuery): SolrQuery

Adds a facet query

パラメータ

facetQuery

The facet query

戻り値

Returns the current SolrQuery object, if the return value is used.

例

例1 SolrQuery::addFacetField() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$query->setFacet(true);

$query->addFacetQuery('price:[* TO 500]')->addFacetQuery('price:[500 TO *]');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response->facet_counts->facet_queries);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [price:[* TO 500]] => 14
    [price:[500 TO *]] => 2
)


Specifies which fields to return in the result

  • ≪ SolrQuery::addFacetQuery
  • SolrQuery::addFilterQuery ≫
  • PHP Manual
  • SolrQuery
  • Specifies which fields to return in the result

SolrQuery::addField

(PECL solr >= 0.9.2)

SolrQuery::addField — Specifies which fields to return in the result

説明

public SolrQuery::addField(string $field): SolrQuery

This method is used to used to specify a set of fields to return, thereby restricting the amount of data returned in the response.

It should be called multiple time, once for each field name.

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object


Specifies a filter query

  • ≪ SolrQuery::addField
  • SolrQuery::addGroupField ≫
  • PHP Manual
  • SolrQuery
  • Specifies a filter query

SolrQuery::addFilterQuery

(PECL solr >= 0.9.2)

SolrQuery::addFilterQuery — Specifies a filter query

説明

public SolrQuery::addFilterQuery(string $fq): SolrQuery

Specifies a filter query

パラメータ

fq

The filter query

戻り値

Returns the current SolrQuery object.

例

例1 SolrQuery::addFilterQuery() example

<?php

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
);

$client = new SolrClient($options);

$query = new SolrQuery();

$query->setQuery('*:*');

$query->addFilterQuery('color:blue,green');

$query_response = $client->query($query);

$response = $query_response->getResponse();

print_r($response['facet_counts']['facet_fields']);

?>

上の例の出力は、 たとえば以下のようになります。

&fq=color:blue,green


Add a field to be used to group results

  • ≪ SolrQuery::addFilterQuery
  • SolrQuery::addGroupFunction ≫
  • PHP Manual
  • SolrQuery
  • Add a field to be used to group results

SolrQuery::addGroupField

(PECL solr >= 2.2.0)

SolrQuery::addGroupField — Add a field to be used to group results

説明

public SolrQuery::addGroupField(string $value): SolrQuery

The name of the field by which to group results. The field must be single-valued, and either be indexed or a field type that has a value source and works in a function query, such as ExternalFileField. It must also be a string-based field, such as StrField or TextField Uses group.field parameter

パラメータ

value

The name of the field.

戻り値

Returns an instance of SolrQuery.

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Allows grouping results based on the unique values of a function query (group.func parameter)

  • ≪ SolrQuery::addGroupField
  • SolrQuery::addGroupQuery ≫
  • PHP Manual
  • SolrQuery
  • Allows grouping results based on the unique values of a function query (group.func parameter)

SolrQuery::addGroupFunction

(PECL solr >= 2.2.0)

SolrQuery::addGroupFunction — Allows grouping results based on the unique values of a function query (group.func parameter)

説明

public SolrQuery::addGroupFunction(string $value): SolrQuery

Adds a group function (group.func parameter) Allows grouping results based on the unique values of a function query.

パラメータ

value

戻り値

SolrQuery

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Allows grouping of documents that match the given query

  • ≪ SolrQuery::addGroupFunction
  • SolrQuery::addGroupSortField ≫
  • PHP Manual
  • SolrQuery
  • Allows grouping of documents that match the given query

SolrQuery::addGroupQuery

(PECL solr >= 2.2.0)

SolrQuery::addGroupQuery — Allows grouping of documents that match the given query

説明

public SolrQuery::addGroupQuery(string $value): SolrQuery

Allows grouping of documents that match the given query. Adds query to the group.query parameter

パラメータ

value

戻り値

SolrQuery

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Add a group sort field (group.sort parameter)

  • ≪ SolrQuery::addGroupQuery
  • SolrQuery::addHighlightField ≫
  • PHP Manual
  • SolrQuery
  • Add a group sort field (group.sort parameter)

SolrQuery::addGroupSortField

(PECL solr >= 2.2.0)

SolrQuery::addGroupSortField — Add a group sort field (group.sort parameter)

説明

public SolrQuery::addGroupSortField(string $field, int $order = ?): SolrQuery

Allow sorting group documents, using group sort field (group.sort parameter).

パラメータ

field

Field name

order

Order ASC/DESC, utilizes SolrQuery::ORDER_* constants

戻り値

例

例1 SolrQuery::addGroupSortField() example

<?php

$solrQuery = new SolrQuery('*:*');
$solrQuery
->setGroup(true)
->addGroupSortField('price', SolrQuery::ORDER_ASC);

echo $solrQuery;
?>

上の例の出力は、 たとえば以下のようになります。

q=*:*&group=true&group.sort=price asc

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Maps to hl.fl

  • ≪ SolrQuery::addGroupSortField
  • SolrQuery::addMltField ≫
  • PHP Manual
  • SolrQuery
  • Maps to hl.fl

SolrQuery::addHighlightField

(PECL solr >= 0.9.2)

SolrQuery::addHighlightField — Maps to hl.fl

説明

public SolrQuery::addHighlightField(string $field): SolrQuery

Maps to hl.fl. This is used to specify that highlighted snippets should be generated for a particular field

パラメータ

field

Name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets a field to use for similarity

  • ≪ SolrQuery::addHighlightField
  • SolrQuery::addMltQueryField ≫
  • PHP Manual
  • SolrQuery
  • Sets a field to use for similarity

SolrQuery::addMltField

(PECL solr >= 0.9.2)

SolrQuery::addMltField — Sets a field to use for similarity

説明

public SolrQuery::addMltField(string $field): SolrQuery

Maps to mlt.fl. It specifies that a field should be used for similarity.

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to mlt.qf

  • ≪ SolrQuery::addMltField
  • SolrQuery::addSortField ≫
  • PHP Manual
  • SolrQuery
  • Maps to mlt.qf

SolrQuery::addMltQueryField

(PECL solr >= 0.9.2)

SolrQuery::addMltQueryField — Maps to mlt.qf

説明

public SolrQuery::addMltQueryField(string $field, float $boost): SolrQuery

Maps to mlt.qf. It is used to specify query fields and their boosts

パラメータ

field

The name of the field

boost

Its boost value

戻り値

Returns the current SolrQuery object, if the return value is used.


Used to control how the results should be sorted

  • ≪ SolrQuery::addMltQueryField
  • SolrQuery::addStatsFacet ≫
  • PHP Manual
  • SolrQuery
  • Used to control how the results should be sorted

SolrQuery::addSortField

(PECL solr >= 0.9.2)

SolrQuery::addSortField — Used to control how the results should be sorted

説明

public SolrQuery::addSortField(string $field, int $order = SolrQuery::ORDER_DESC): SolrQuery

Used to control how the results should be sorted.

パラメータ

field

The name of the field

order

The sort direction. This should be either SolrQuery::ORDER_ASC or SolrQuery::ORDER_DESC.

戻り値

Returns the current SolrQuery object.


Requests a return of sub results for values within the given facet

  • ≪ SolrQuery::addSortField
  • SolrQuery::addStatsField ≫
  • PHP Manual
  • SolrQuery
  • Requests a return of sub results for values within the given facet

SolrQuery::addStatsFacet

(PECL solr >= 0.9.2)

SolrQuery::addStatsFacet — Requests a return of sub results for values within the given facet

説明

public SolrQuery::addStatsFacet(string $field): SolrQuery

Requests a return of sub results for values within the given facet. Maps to the stats.facet field

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to stats.field parameter

  • ≪ SolrQuery::addStatsFacet
  • SolrQuery::collapse ≫
  • PHP Manual
  • SolrQuery
  • Maps to stats.field parameter

SolrQuery::addStatsField

(PECL solr >= 0.9.2)

SolrQuery::addStatsField — Maps to stats.field parameter

説明

public SolrQuery::addStatsField(string $field): SolrQuery

Maps to stats.field parameter This methods adds another stats.field parameter.

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Collapses the result set to a single document per group

  • ≪ SolrQuery::addStatsField
  • SolrQuery::__construct ≫
  • PHP Manual
  • SolrQuery
  • Collapses the result set to a single document per group

SolrQuery::collapse

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrQuery::collapse — Collapses the result set to a single document per group

説明

public SolrQuery::collapse(SolrCollapseFunction $collapseFunction): SolrQuery

Collapses the result set to a single document per group before it forwards the result set to the rest of the search components.

So all downstream components (faceting, highlighting, etc...) will work with the collapsed result set.

パラメータ

collapseFunction

戻り値

Returns the current SolrQuery object

例

例1 SolrQuery::collapse() example

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_PATH
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$collapseFunction = new SolrCollapseFunction('manu_id_s');

$collapseFunction
->setSize(2)
->setNullPolicy(SolrCollapseFunction::NULLPOLICY_IGNORE);

$query
->collapse($collapseFunction)
->setRows(4);

$queryResponse = $client->query($query);

$response = $queryResponse->getResponse();

print_r($response);

?>

上の例の出力は、 たとえば以下のようになります。

SolrObject Object
(
    [responseHeader] => SolrObject Object
        (
            [status] => 0
            [QTime] => 1
            [params] => SolrObject Object
                (
                    [q] => *:*
                    [indent] => on
                    [fq] => {!collapse field=manu_id_s size=2 nullPolicy=ignore}
                    [rows] => 4
                    [version] => 2.2
                    [wt] => xml
                )

        )

    [response] => SolrObject Object
        (
            [numFound] => 14
            [start] => 0
            [docs] => Array
                (
                    [0] => SolrObject Object
                        (
                            [id] => SP2514N
                            [name] => Array
                                (
                                    [0] => Samsung SpinPoint P120 SP2514N - hard drive - 250 GB - ATA-133
                                )

                            [manu] => Array
                                (
                                    [0] => Samsung Electronics Co. Ltd.
                                )

                            [manu_id_s] => samsung
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => 7200RPM, 8MB cache, IDE Ultra ATA-133
                                    [1] => NoiseGuard, SilentSeek technology, Fluid Dynamic Bearing (FDB) motor
                                )

                            [price] => Array
                                (
                                    [0] => 92
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [store] => Array
                                (
                                    [0] => 35.0752,-97.032
                                )

                            [_version_] => 1510294336412057600
                        )

                    [1] => SolrObject Object
                        (
                            [id] => 6H500F0
                            [name] => Array
                                (
                                    [0] => Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300
                                )

                            [manu] => Array
                                (
                                    [0] => Maxtor Corp.
                                )

                            [manu_id_s] => maxtor
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => hard drive
                                )

                            [features] => Array
                                (
                                    [0] => SATA 3.0Gb/s, NCQ
                                    [1] => 8.5ms seek
                                    [2] => 16MB cache
                                )

                            [price] => Array
                                (
                                    [0] => 350
                                )

                            [popularity] => Array
                                (
                                    [0] => 6
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 45.17614,-93.87341
                                )

                            [manufacturedate_dt] => 2006-02-13T15:26:37Z
                            [_version_] => 1510294336449806336
                        )

                    [2] => SolrObject Object
                        (
                            [id] => F8V7067-APL-KIT
                            [name] => Array
                                (
                                    [0] => Belkin Mobile Power Cord for iPod w/ Dock
                                )

                            [manu] => Array
                                (
                                    [0] => Belkin
                                )

                            [manu_id_s] => belkin
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => connector
                                )

                            [features] => Array
                                (
                                    [0] => car power adapter, white
                                )

                            [weight] => Array
                                (
                                    [0] => 4
                                )

                            [price] => Array
                                (
                                    [0] => 19.95
                                )

                            [popularity] => Array
                                (
                                    [0] => 1
                                )

                            [inStock] => Array
                                (
                                    [0] =>
                                )

                            [store] => Array
                                (
                                    [0] => 45.18014,-93.87741
                                )

                            [manufacturedate_dt] => 2005-08-01T16:30:25Z
                            [_version_] => 1510294336458194944
                        )

                    [3] => SolrObject Object
                        (
                            [id] => MA147LL/A
                            [name] => Array
                                (
                                    [0] => Apple 60 GB iPod with Video Playback Black
                                )

                            [manu] => Array
                                (
                                    [0] => Apple Computer Inc.
                                )

                            [manu_id_s] => apple
                            [cat] => Array
                                (
                                    [0] => electronics
                                    [1] => music
                                )

                            [features] => Array
                                (
                                    [0] => iTunes, Podcasts, Audiobooks
                                    [1] => Stores up to 15,000 songs, 25,000 photos, or 150 hours of video
                                    [2] => 2.5-inch, 320x240 color TFT LCD display with LED backlight
                                    [3] => Up to 20 hours of battery life
                                    [4] => Plays AAC, MP3, WAV, AIFF, Audible, Apple Lossless, H.264 video
                                    [5] => Notes, Calendar, Phone book, Hold button, Date display, Photo wallet, Built-in games, JPEG photo playback, Upgradeable firmware, USB 2.0 compatibility, Playback speed control, Rechargeable capability, Battery level indication
                                )

                            [includes] => Array
                                (
                                    [0] => earbud headphones, USB cable
                                )

                            [weight] => Array
                                (
                                    [0] => 5.5
                                )

                            [price] => Array
                                (
                                    [0] => 399
                                )

                            [popularity] => Array
                                (
                                    [0] => 10
                                )

                            [inStock] => Array
                                (
                                    [0] => 1
                                )

                            [store] => Array
                                (
                                    [0] => 37.7752,-100.0232
                                )

                            [manufacturedate_dt] => 2005-10-12T08:00:00Z
                            [_version_] => 1510294336562003968
                        )

                )

        )

)


コンストラクタ

  • ≪ SolrQuery::collapse
  • SolrQuery::__destruct ≫
  • PHP Manual
  • SolrQuery
  • コンストラクタ

SolrQuery::__construct

(PECL solr >= 0.9.2)

SolrQuery::__construct — コンストラクタ

説明

public SolrQuery::__construct(string $q = ?)

コンストラクタ

パラメータ

q

任意の検索クエリ

戻り値

ありません

エラー / 例外

無効なパラメータが渡されたときに SolrIllegalArgumentException が発生します。

変更履歴

バージョン | 説明
PECL solr 2.0.0 | q が無効な場合に SolrIllegalArgumentException が発生するようになりました。以前のバージョンではエラーになっていました。


デストラクタ

  • ≪ SolrQuery::__construct
  • SolrQuery::getExpand ≫
  • PHP Manual
  • SolrQuery
  • デストラクタ

SolrQuery::__destruct

(PECL solr >= 0.9.2)

SolrQuery::__destruct — デストラクタ

説明

public SolrQuery::__destruct()

デストラクタ

パラメータ

この関数にはパラメータはありません。

戻り値

ありません


Returns true if group expanding is enabled

  • ≪ SolrQuery::__destruct
  • SolrQuery::getExpandFilterQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns true if group expanding is enabled

SolrQuery::getExpand

(PECL solr >= 2.2.0)

SolrQuery::getExpand — Returns true if group expanding is enabled

説明

public SolrQuery::getExpand(): bool

Returns true if group expanding is enabled

パラメータ

この関数にはパラメータはありません。

戻り値

Returns whether group expanding is enabled.


Returns the expand filter queries

  • ≪ SolrQuery::getExpand
  • SolrQuery::getExpandQuery ≫
  • PHP Manual
  • SolrQuery
  • Returns the expand filter queries

SolrQuery::getExpandFilterQueries

(PECL solr >= 2.2.0)

SolrQuery::getExpandFilterQueries — Returns the expand filter queries

説明

public SolrQuery::getExpandFilterQueries(): array

Returns the expand filter queries

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the expand filter queries.


Returns the expand query expand.q parameter

  • ≪ SolrQuery::getExpandFilterQueries
  • SolrQuery::getExpandRows ≫
  • PHP Manual
  • SolrQuery
  • Returns the expand query expand.q parameter

SolrQuery::getExpandQuery

(PECL solr >= 2.2.0)

SolrQuery::getExpandQuery — Returns the expand query expand.q parameter

説明

public SolrQuery::getExpandQuery(): array

Returns the expand query expand.q parameter

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the expand query.


Returns The number of rows to display in each group (expand.rows)

  • ≪ SolrQuery::getExpandQuery
  • SolrQuery::getExpandSortFields ≫
  • PHP Manual
  • SolrQuery
  • Returns The number of rows to display in each group (expand.rows)

SolrQuery::getExpandRows

(PECL solr >= 2.2.0)

SolrQuery::getExpandRows — Returns The number of rows to display in each group (expand.rows)

説明

public SolrQuery::getExpandRows(): int

Returns The number of rows to display in each group (expand.rows)

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the number of rows.


Returns an array of fields

  • ≪ SolrQuery::getExpandRows
  • SolrQuery::getFacet ≫
  • PHP Manual
  • SolrQuery
  • Returns an array of fields

SolrQuery::getExpandSortFields

(PECL solr >= 2.2.0)

SolrQuery::getExpandSortFields — Returns an array of fields

説明

public SolrQuery::getExpandSortFields(): array

Returns an array of fields

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of fields.


Returns the value of the facet parameter

  • ≪ SolrQuery::getExpandSortFields
  • SolrQuery::getFacetDateEnd ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet parameter

SolrQuery::getFacet

(PECL solr >= 0.9.2)

SolrQuery::getFacet — Returns the value of the facet parameter

説明

public SolrQuery::getFacet(): bool

Returns the value of the facet parameter.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set


Returns the value for the facet.date.end parameter

  • ≪ SolrQuery::getFacet
  • SolrQuery::getFacetDateFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the value for the facet.date.end parameter

SolrQuery::getFacetDateEnd

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateEnd — Returns the value for the facet.date.end parameter

説明

public SolrQuery::getFacetDateEnd(string $field_override = ?): string

Returns the value for the facet.date.end parameter. This method accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set


Returns all the facet.date fields

  • ≪ SolrQuery::getFacetDateEnd
  • SolrQuery::getFacetDateGap ≫
  • PHP Manual
  • SolrQuery
  • Returns all the facet.date fields

SolrQuery::getFacetDateFields

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateFields — Returns all the facet.date fields

説明

public SolrQuery::getFacetDateFields(): array

Returns all the facet.date fields

パラメータ

この関数にはパラメータはありません。

戻り値

Returns all the facet.date fields as an array or null if none was set


Returns the value of the facet.date.gap parameter

  • ≪ SolrQuery::getFacetDateFields
  • SolrQuery::getFacetDateHardEnd ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet.date.gap parameter

SolrQuery::getFacetDateGap

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateGap — Returns the value of the facet.date.gap parameter

説明

public SolrQuery::getFacetDateGap(string $field_override = ?): string

Returns the value of the facet.date.gap parameter. It accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set


Returns the value of the facet.date.hardend parameter

  • ≪ SolrQuery::getFacetDateGap
  • SolrQuery::getFacetDateOther ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet.date.hardend parameter

SolrQuery::getFacetDateHardEnd

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateHardEnd — Returns the value of the facet.date.hardend parameter

説明

public SolrQuery::getFacetDateHardEnd(string $field_override = ?): string

Returns the value of the facet.date.hardend parameter. Accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set


Returns the value for the facet.date.other parameter

  • ≪ SolrQuery::getFacetDateHardEnd
  • SolrQuery::getFacetDateStart ≫
  • PHP Manual
  • SolrQuery
  • Returns the value for the facet.date.other parameter

SolrQuery::getFacetDateOther

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateOther — Returns the value for the facet.date.other parameter

説明

public SolrQuery::getFacetDateOther(string $field_override = ?): array

Returns the value for the facet.date.other parameter. This method accepts an optional field override.

パラメータ

field_override

The name of the field

戻り値

Returns an array on success and null if not set.


Returns the lower bound for the first date range for all date faceting on this field

  • ≪ SolrQuery::getFacetDateOther
  • SolrQuery::getFacetFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the lower bound for the first date range for all date faceting on this field

SolrQuery::getFacetDateStart

(PECL solr >= 0.9.2)

SolrQuery::getFacetDateStart — Returns the lower bound for the first date range for all date faceting on this field

説明

public SolrQuery::getFacetDateStart(string $field_override = ?): string

Returns the lower bound for the first date range for all date faceting on this field. Accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set


Returns all the facet fields

  • ≪ SolrQuery::getFacetDateStart
  • SolrQuery::getFacetLimit ≫
  • PHP Manual
  • SolrQuery
  • Returns all the facet fields

SolrQuery::getFacetFields

(PECL solr >= 0.9.2)

SolrQuery::getFacetFields — Returns all the facet fields

説明

public SolrQuery::getFacetFields(): array

Returns all the facet fields

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of all the fields and null if none was set


Returns the maximum number of constraint counts that should be returned for the facet fields

  • ≪ SolrQuery::getFacetFields
  • SolrQuery::getFacetMethod ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of constraint counts that should be returned for the facet fields

SolrQuery::getFacetLimit

(PECL solr >= 0.9.2)

SolrQuery::getFacetLimit — Returns the maximum number of constraint counts that should be returned for the facet fields

説明

public SolrQuery::getFacetLimit(string $field_override = ?): int

Returns the maximum number of constraint counts that should be returned for the facet fields. This method accepts an optional field override

パラメータ

field_override

The name of the field to override for

戻り値

Returns an integer on success and null if not set


Returns the value of the facet.method parameter

  • ≪ SolrQuery::getFacetLimit
  • SolrQuery::getFacetMinCount ≫
  • PHP Manual
  • SolrQuery
  • Returns the value of the facet.method parameter

SolrQuery::getFacetMethod

(PECL solr >= 0.9.2)

SolrQuery::getFacetMethod — Returns the value of the facet.method parameter

説明

public SolrQuery::getFacetMethod(string $field_override = ?): string

Returns the value of the facet.method parameter. This accepts an optional field override.

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set


Returns the minimum counts for facet fields should be included in the response

  • ≪ SolrQuery::getFacetMethod
  • SolrQuery::getFacetMissing ≫
  • PHP Manual
  • SolrQuery
  • Returns the minimum counts for facet fields should be included in the response

SolrQuery::getFacetMinCount

(PECL solr >= 0.9.2)

SolrQuery::getFacetMinCount — Returns the minimum counts for facet fields should be included in the response

説明

public SolrQuery::getFacetMinCount(string $field_override = ?): int

Returns the minimum counts for facet fields should be included in the response. It accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns an integer on success and null if not set


Returns the current state of the facet.missing parameter

  • ≪ SolrQuery::getFacetMinCount
  • SolrQuery::getFacetOffset ≫
  • PHP Manual
  • SolrQuery
  • Returns the current state of the facet.missing parameter

SolrQuery::getFacetMissing

(PECL solr >= 0.9.2)

SolrQuery::getFacetMissing — Returns the current state of the facet.missing parameter

説明

public SolrQuery::getFacetMissing(string $field_override = ?): bool

Returns the current state of the facet.missing parameter. This accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a boolean on success and null if not set


Returns an offset into the list of constraints to be used for pagination

  • ≪ SolrQuery::getFacetMissing
  • SolrQuery::getFacetPrefix ≫
  • PHP Manual
  • SolrQuery
  • Returns an offset into the list of constraints to be used for pagination

SolrQuery::getFacetOffset

(PECL solr >= 0.9.2)

SolrQuery::getFacetOffset — Returns an offset into the list of constraints to be used for pagination

説明

public SolrQuery::getFacetOffset(string $field_override = ?): int

Returns an offset into the list of constraints to be used for pagination. Accepts an optional field override

パラメータ

field_override

The name of the field to override for.

戻り値

Returns an integer on success and null if not set


Returns the facet prefix

  • ≪ SolrQuery::getFacetOffset
  • SolrQuery::getFacetQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns the facet prefix

SolrQuery::getFacetPrefix

(PECL solr >= 0.9.2)

SolrQuery::getFacetPrefix — Returns the facet prefix

説明

public SolrQuery::getFacetPrefix(string $field_override = ?): string

Returns the facet prefix

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set.


Returns all the facet queries

  • ≪ SolrQuery::getFacetPrefix
  • SolrQuery::getFacetSort ≫
  • PHP Manual
  • SolrQuery
  • Returns all the facet queries

SolrQuery::getFacetQueries

(PECL solr >= 0.9.2)

SolrQuery::getFacetQueries — Returns all the facet queries

説明

public SolrQuery::getFacetQueries(): array

Returns all the facet queries

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns the facet sort type

  • ≪ SolrQuery::getFacetQueries
  • SolrQuery::getFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the facet sort type

SolrQuery::getFacetSort

(PECL solr >= 0.9.2)

SolrQuery::getFacetSort — Returns the facet sort type

説明

public SolrQuery::getFacetSort(string $field_override = ?): int

Returns an integer (SolrQuery::FACET_SORT_INDEX or SolrQuery::FACET_SORT_COUNT)

パラメータ

field_override

The name of the field

戻り値

Returns an integer (SolrQuery::FACET_SORT_INDEX or SolrQuery::FACET_SORT_COUNT) on success or null if not set.


Returns the list of fields that will be returned in the response

  • ≪ SolrQuery::getFacetSort
  • SolrQuery::getFilterQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns the list of fields that will be returned in the response

SolrQuery::getFields

(PECL solr >= 0.9.2)

SolrQuery::getFields — Returns the list of fields that will be returned in the response

説明

public SolrQuery::getFields(): array

Returns the list of fields that will be returned in the response

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns an array of filter queries

  • ≪ SolrQuery::getFields
  • SolrQuery::getGroup ≫
  • PHP Manual
  • SolrQuery
  • Returns an array of filter queries

SolrQuery::getFilterQueries

(PECL solr >= 0.9.2)

SolrQuery::getFilterQueries — Returns an array of filter queries

説明

public SolrQuery::getFilterQueries(): array

Returns an array of filter queries. These are queries that can be used to restrict the super set of documents that can be returned, without influencing score

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns true if grouping is enabled

  • ≪ SolrQuery::getFilterQueries
  • SolrQuery::getGroupCachePercent ≫
  • PHP Manual
  • SolrQuery
  • Returns true if grouping is enabled

SolrQuery::getGroup

(PECL solr >= 2.2.0)

SolrQuery::getGroup — Returns true if grouping is enabled

説明

public SolrQuery::getGroup(): bool

Returns true if grouping is enabled

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)


Returns group cache percent value

  • ≪ SolrQuery::getGroup
  • SolrQuery::getGroupFacet ≫
  • PHP Manual
  • SolrQuery
  • Returns group cache percent value

SolrQuery::getGroupCachePercent

(PECL solr >= 2.2.0)

SolrQuery::getGroupCachePercent — Returns group cache percent value

説明

public SolrQuery::getGroupCachePercent(): int

Returns group cache percent value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Returns the group.facet parameter value

  • ≪ SolrQuery::getGroupCachePercent
  • SolrQuery::getGroupFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.facet parameter value

SolrQuery::getGroupFacet

(PECL solr >= 2.2.0)

SolrQuery::getGroupFacet — Returns the group.facet parameter value

説明

public SolrQuery::getGroupFacet(): bool

Returns the group.facet parameter value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupFacet() - Sets group.facet parameter


Returns group fields (group.field parameter values)

  • ≪ SolrQuery::getGroupFacet
  • SolrQuery::getGroupFormat ≫
  • PHP Manual
  • SolrQuery
  • Returns group fields (group.field parameter values)

SolrQuery::getGroupFields

(PECL solr >= 2.2.0)

SolrQuery::getGroupFields — Returns group fields (group.field parameter values)

説明

public SolrQuery::getGroupFields(): array

Returns group fields (group.field parameter values)

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::addGroupField() - Add a field to be used to group results


Returns the group.format value

  • ≪ SolrQuery::getGroupFields
  • SolrQuery::getGroupFunctions ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.format value

SolrQuery::getGroupFormat

(PECL solr >= 2.2.0)

SolrQuery::getGroupFormat — Returns the group.format value

説明

public SolrQuery::getGroupFormat(): string

Returns the group.format value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)


Returns group functions (group.func parameter values)

  • ≪ SolrQuery::getGroupFormat
  • SolrQuery::getGroupLimit ≫
  • PHP Manual
  • SolrQuery
  • Returns group functions (group.func parameter values)

SolrQuery::getGroupFunctions

(PECL solr >= 2.2.0)

SolrQuery::getGroupFunctions — Returns group functions (group.func parameter values)

説明

public SolrQuery::getGroupFunctions(): array

Returns group functions (group.func parameter values)

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)


Returns the group.limit value

  • ≪ SolrQuery::getGroupFunctions
  • SolrQuery::getGroupMain ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.limit value

SolrQuery::getGroupLimit

(PECL solr >= 2.2.0)

SolrQuery::getGroupLimit — Returns the group.limit value

説明

public SolrQuery::getGroupLimit(): int

Returns the group.limit value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1


Returns the group.main value

  • ≪ SolrQuery::getGroupLimit
  • SolrQuery::getGroupNGroups ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.main value

SolrQuery::getGroupMain

(PECL solr >= 2.2.0)

SolrQuery::getGroupMain — Returns the group.main value

説明

public SolrQuery::getGroupMain(): bool

Returns the group.main value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple


Returns the group.ngroups value

  • ≪ SolrQuery::getGroupMain
  • SolrQuery::getGroupOffset ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.ngroups value

SolrQuery::getGroupNGroups

(PECL solr >= 2.2.0)

SolrQuery::getGroupNGroups — Returns the group.ngroups value

説明

public SolrQuery::getGroupNGroups(): bool

Returns the group.ngroups value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results


Returns the group.offset value

  • ≪ SolrQuery::getGroupNGroups
  • SolrQuery::getGroupQueries ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.offset value

SolrQuery::getGroupOffset

(PECL solr >= 2.2.0)

SolrQuery::getGroupOffset — Returns the group.offset value

説明

public SolrQuery::getGroupOffset(): int

Returns the group.offset value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupOffset() - Sets the group.offset parameter


Returns all the group.query parameter values

  • ≪ SolrQuery::getGroupOffset
  • SolrQuery::getGroupSortFields ≫
  • PHP Manual
  • SolrQuery
  • Returns all the group.query parameter values

SolrQuery::getGroupQueries

(PECL solr >= 2.2.0)

SolrQuery::getGroupQueries — Returns all the group.query parameter values

説明

public SolrQuery::getGroupQueries(): array

Returns all the group.query parameter values

パラメータ

この関数にはパラメータはありません。

戻り値

array

参考

  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query


Returns the group.sort value

  • ≪ SolrQuery::getGroupQueries
  • SolrQuery::getGroupTruncate ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.sort value

SolrQuery::getGroupSortFields

(PECL solr >= 2.2.0)

SolrQuery::getGroupSortFields — Returns the group.sort value

説明

public SolrQuery::getGroupSortFields(): array

Returns the group.sort value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)


Returns the group.truncate value

  • ≪ SolrQuery::getGroupSortFields
  • SolrQuery::getHighlight ≫
  • PHP Manual
  • SolrQuery
  • Returns the group.truncate value

SolrQuery::getGroupTruncate

(PECL solr >= 2.2.0)

SolrQuery::getGroupTruncate — Returns the group.truncate value

説明

public SolrQuery::getGroupTruncate(): bool

Returns the group.truncate value

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query


Returns the state of the hl parameter

  • ≪ SolrQuery::getGroupTruncate
  • SolrQuery::getHighlightAlternateField ≫
  • PHP Manual
  • SolrQuery
  • Returns the state of the hl parameter

SolrQuery::getHighlight

(PECL solr >= 0.9.2)

SolrQuery::getHighlight — Returns the state of the hl parameter

説明

public SolrQuery::getHighlight(): bool

Returns a boolean indicating whether or not to enable highlighted snippets to be generated in the query response.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns the highlight field to use as backup or default

  • ≪ SolrQuery::getHighlight
  • SolrQuery::getHighlightFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the highlight field to use as backup or default

SolrQuery::getHighlightAlternateField

(PECL solr >= 0.9.2)

SolrQuery::getHighlightAlternateField — Returns the highlight field to use as backup or default

説明

public SolrQuery::getHighlightAlternateField(string $field_override = ?): string

Returns the highlight field to use as backup or default. It accepts an optional override.

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set.


Returns all the fields that Solr should generate highlighted snippets for

  • ≪ SolrQuery::getHighlightAlternateField
  • SolrQuery::getHighlightFormatter ≫
  • PHP Manual
  • SolrQuery
  • Returns all the fields that Solr should generate highlighted snippets for

SolrQuery::getHighlightFields

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFields — Returns all the fields that Solr should generate highlighted snippets for

説明

public SolrQuery::getHighlightFields(): array

Returns all the fields that Solr should generate highlighted snippets for

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns the formatter for the highlighted output

  • ≪ SolrQuery::getHighlightFields
  • SolrQuery::getHighlightFragmenter ≫
  • PHP Manual
  • SolrQuery
  • Returns the formatter for the highlighted output

SolrQuery::getHighlightFormatter

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFormatter — Returns the formatter for the highlighted output

説明

public SolrQuery::getHighlightFormatter(string $field_override = ?): string

Returns the formatter for the highlighted output

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set.


Returns the text snippet generator for highlighted text

  • ≪ SolrQuery::getHighlightFormatter
  • SolrQuery::getHighlightFragsize ≫
  • PHP Manual
  • SolrQuery
  • Returns the text snippet generator for highlighted text

SolrQuery::getHighlightFragmenter

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFragmenter — Returns the text snippet generator for highlighted text

説明

public SolrQuery::getHighlightFragmenter(string $field_override = ?): string

Returns the text snippet generator for highlighted text. Accepts an optional field override.

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set.


Returns the number of characters of fragments to consider for highlighting

  • ≪ SolrQuery::getHighlightFragmenter
  • SolrQuery::getHighlightHighlightMultiTerm ≫
  • PHP Manual
  • SolrQuery
  • Returns the number of characters of fragments to consider for highlighting

SolrQuery::getHighlightFragsize

(PECL solr >= 0.9.2)

SolrQuery::getHighlightFragsize — Returns the number of characters of fragments to consider for highlighting

説明

public SolrQuery::getHighlightFragsize(string $field_override = ?): int

Returns the number of characters of fragments to consider for highlighting. Zero implies no fragmenting. The entire field should be used.

パラメータ

field_override

The name of the field

戻り値

Returns an integer on success or null if not set.


Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

  • ≪ SolrQuery::getHighlightFragsize
  • SolrQuery::getHighlightMaxAlternateFieldLength ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

SolrQuery::getHighlightHighlightMultiTerm

(PECL solr >= 0.9.2)

SolrQuery::getHighlightHighlightMultiTerm — Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

説明

public SolrQuery::getHighlightHighlightMultiTerm(): bool

Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns the maximum number of characters of the field to return

  • ≪ SolrQuery::getHighlightHighlightMultiTerm
  • SolrQuery::getHighlightMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of characters of the field to return

SolrQuery::getHighlightMaxAlternateFieldLength

(PECL solr >= 0.9.2)

SolrQuery::getHighlightMaxAlternateFieldLength — Returns the maximum number of characters of the field to return

説明

public SolrQuery::getHighlightMaxAlternateFieldLength(string $field_override = ?): int

Returns the maximum number of characters of the field to return

パラメータ

field_override

The name of the field

戻り値

Returns an integer on success and null if not set.


Returns the maximum number of characters into a document to look for suitable snippets

  • ≪ SolrQuery::getHighlightMaxAlternateFieldLength
  • SolrQuery::getHighlightMergeContiguous ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of characters into a document to look for suitable snippets

SolrQuery::getHighlightMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::getHighlightMaxAnalyzedChars — Returns the maximum number of characters into a document to look for suitable snippets

説明

public SolrQuery::getHighlightMaxAnalyzedChars(): int

Returns the maximum number of characters into a document to look for suitable snippets

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns whether or not the collapse contiguous fragments into a single fragment

  • ≪ SolrQuery::getHighlightMaxAnalyzedChars
  • SolrQuery::getHighlightRegexMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not the collapse contiguous fragments into a single fragment

SolrQuery::getHighlightMergeContiguous

(PECL solr >= 0.9.2)

SolrQuery::getHighlightMergeContiguous — Returns whether or not the collapse contiguous fragments into a single fragment

説明

public SolrQuery::getHighlightMergeContiguous(string $field_override = ?): bool

Returns whether or not the collapse contiguous fragments into a single fragment. Accepts an optional field override.

パラメータ

field_override

The name of the field

戻り値

Returns a boolean on success and null if not set.


Returns the maximum number of characters from a field when using the regex fragmenter

  • ≪ SolrQuery::getHighlightMergeContiguous
  • SolrQuery::getHighlightRegexPattern ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of characters from a field when using the regex fragmenter

SolrQuery::getHighlightRegexMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRegexMaxAnalyzedChars — Returns the maximum number of characters from a field when using the regex fragmenter

説明

public SolrQuery::getHighlightRegexMaxAnalyzedChars(): int

Returns the maximum number of characters from a field when using the regex fragmenter

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the regular expression for fragmenting

  • ≪ SolrQuery::getHighlightRegexMaxAnalyzedChars
  • SolrQuery::getHighlightRegexSlop ≫
  • PHP Manual
  • SolrQuery
  • Returns the regular expression for fragmenting

SolrQuery::getHighlightRegexPattern

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRegexPattern — Returns the regular expression for fragmenting

説明

public SolrQuery::getHighlightRegexPattern(): string

Returns the regular expression used for fragmenting

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string on success and null if not set.


Returns the deviation factor from the ideal fragment size

  • ≪ SolrQuery::getHighlightRegexPattern
  • SolrQuery::getHighlightRequireFieldMatch ≫
  • PHP Manual
  • SolrQuery
  • Returns the deviation factor from the ideal fragment size

SolrQuery::getHighlightRegexSlop

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRegexSlop — Returns the deviation factor from the ideal fragment size

説明

public SolrQuery::getHighlightRegexSlop(): float

Returns the factor by which the regex fragmenter can deviate from the ideal fragment size to accommodate the regular expression

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a float on success and null if not set.


Returns if a field will only be highlighted if the query matched in this particular field

  • ≪ SolrQuery::getHighlightRegexSlop
  • SolrQuery::getHighlightSimplePost ≫
  • PHP Manual
  • SolrQuery
  • Returns if a field will only be highlighted if the query matched in this particular field

SolrQuery::getHighlightRequireFieldMatch

(PECL solr >= 0.9.2)

SolrQuery::getHighlightRequireFieldMatch — Returns if a field will only be highlighted if the query matched in this particular field

説明

public SolrQuery::getHighlightRequireFieldMatch(): bool

Returns if a field will only be highlighted if the query matched in this particular field.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns the text which appears after a highlighted term

  • ≪ SolrQuery::getHighlightRequireFieldMatch
  • SolrQuery::getHighlightSimplePre ≫
  • PHP Manual
  • SolrQuery
  • Returns the text which appears after a highlighted term

SolrQuery::getHighlightSimplePost

(PECL solr >= 0.9.2)

SolrQuery::getHighlightSimplePost — Returns the text which appears after a highlighted term

説明

public SolrQuery::getHighlightSimplePost(string $field_override = ?): string

Returns the text which appears after a highlighted term. Accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set.


Returns the text which appears before a highlighted term

  • ≪ SolrQuery::getHighlightSimplePost
  • SolrQuery::getHighlightSnippets ≫
  • PHP Manual
  • SolrQuery
  • Returns the text which appears before a highlighted term

SolrQuery::getHighlightSimplePre

(PECL solr >= 0.9.2)

SolrQuery::getHighlightSimplePre — Returns the text which appears before a highlighted term

説明

public SolrQuery::getHighlightSimplePre(string $field_override = ?): string

Returns the text which appears before a highlighted term. Accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns a string on success and null if not set.


Returns the maximum number of highlighted snippets to generate per field

  • ≪ SolrQuery::getHighlightSimplePre
  • SolrQuery::getHighlightUsePhraseHighlighter ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of highlighted snippets to generate per field

SolrQuery::getHighlightSnippets

(PECL solr >= 0.9.2)

SolrQuery::getHighlightSnippets — Returns the maximum number of highlighted snippets to generate per field

説明

public SolrQuery::getHighlightSnippets(string $field_override = ?): int

Returns the maximum number of highlighted snippets to generate per field. Accepts an optional field override

パラメータ

field_override

The name of the field

戻り値

Returns an integer on success and null if not set.


Returns the state of the hl.usePhraseHighlighter parameter

  • ≪ SolrQuery::getHighlightSnippets
  • SolrQuery::getMlt ≫
  • PHP Manual
  • SolrQuery
  • Returns the state of the hl.usePhraseHighlighter parameter

SolrQuery::getHighlightUsePhraseHighlighter

(PECL solr >= 0.9.2)

SolrQuery::getHighlightUsePhraseHighlighter — Returns the state of the hl.usePhraseHighlighter parameter

説明

public SolrQuery::getHighlightUsePhraseHighlighter(): bool

Returns whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns whether or not MoreLikeThis results should be enabled

  • ≪ SolrQuery::getHighlightUsePhraseHighlighter
  • SolrQuery::getMltBoost ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not MoreLikeThis results should be enabled

SolrQuery::getMlt

(PECL solr >= 0.9.2)

SolrQuery::getMlt — Returns whether or not MoreLikeThis results should be enabled

説明

public SolrQuery::getMlt(): bool

Returns whether or not MoreLikeThis results should be enabled

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns whether or not the query will be boosted by the interesting term relevance

  • ≪ SolrQuery::getMlt
  • SolrQuery::getMltCount ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not the query will be boosted by the interesting term relevance

SolrQuery::getMltBoost

(PECL solr >= 0.9.2)

SolrQuery::getMltBoost — Returns whether or not the query will be boosted by the interesting term relevance

説明

public SolrQuery::getMltBoost(): bool

Returns whether or not the query will be boosted by the interesting term relevance

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns the number of similar documents to return for each result

  • ≪ SolrQuery::getMltBoost
  • SolrQuery::getMltFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the number of similar documents to return for each result

SolrQuery::getMltCount

(PECL solr >= 0.9.2)

SolrQuery::getMltCount — Returns the number of similar documents to return for each result

説明

public SolrQuery::getMltCount(): int

Returns the number of similar documents to return for each result

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns all the fields to use for similarity

  • ≪ SolrQuery::getMltCount
  • SolrQuery::getMltMaxNumQueryTerms ≫
  • PHP Manual
  • SolrQuery
  • Returns all the fields to use for similarity

SolrQuery::getMltFields

(PECL solr >= 0.9.2)

SolrQuery::getMltFields — Returns all the fields to use for similarity

説明

public SolrQuery::getMltFields(): array

Returns all the fields to use for similarity

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns the maximum number of query terms that will be included in any generated query

  • ≪ SolrQuery::getMltFields
  • SolrQuery::getMltMaxNumTokens ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of query terms that will be included in any generated query

SolrQuery::getMltMaxNumQueryTerms

(PECL solr >= 0.9.2)

SolrQuery::getMltMaxNumQueryTerms — Returns the maximum number of query terms that will be included in any generated query

説明

public SolrQuery::getMltMaxNumQueryTerms(): int

Returns the maximum number of query terms that will be included in any generated query

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

  • ≪ SolrQuery::getMltMaxNumQueryTerms
  • SolrQuery::getMltMaxWordLength ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

SolrQuery::getMltMaxNumTokens

(PECL solr >= 0.9.2)

SolrQuery::getMltMaxNumTokens — Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

説明

public SolrQuery::getMltMaxNumTokens(): int

Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the maximum word length above which words will be ignored

  • ≪ SolrQuery::getMltMaxNumTokens
  • SolrQuery::getMltMinDocFrequency ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum word length above which words will be ignored

SolrQuery::getMltMaxWordLength

(PECL solr >= 0.9.2)

SolrQuery::getMltMaxWordLength — Returns the maximum word length above which words will be ignored

説明

public SolrQuery::getMltMaxWordLength(): int

Returns the maximum word length above which words will be ignored

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

  • ≪ SolrQuery::getMltMaxWordLength
  • SolrQuery::getMltMinTermFrequency ≫
  • PHP Manual
  • SolrQuery
  • Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

SolrQuery::getMltMinDocFrequency

(PECL solr >= 0.9.2)

SolrQuery::getMltMinDocFrequency — Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

説明

public SolrQuery::getMltMinDocFrequency(): int

Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the frequency below which terms will be ignored in the source document

  • ≪ SolrQuery::getMltMinDocFrequency
  • SolrQuery::getMltMinWordLength ≫
  • PHP Manual
  • SolrQuery
  • Returns the frequency below which terms will be ignored in the source document

SolrQuery::getMltMinTermFrequency

(PECL solr >= 0.9.2)

SolrQuery::getMltMinTermFrequency — Returns the frequency below which terms will be ignored in the source document

説明

public SolrQuery::getMltMinTermFrequency(): int

Returns the frequency below which terms will be ignored in the source document

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the minimum word length below which words will be ignored

  • ≪ SolrQuery::getMltMinTermFrequency
  • SolrQuery::getMltQueryFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the minimum word length below which words will be ignored

SolrQuery::getMltMinWordLength

(PECL solr >= 0.9.2)

SolrQuery::getMltMinWordLength — Returns the minimum word length below which words will be ignored

説明

public SolrQuery::getMltMinWordLength(): int

Returns the minimum word length below which words will be ignored

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the query fields and their boosts

  • ≪ SolrQuery::getMltMinWordLength
  • SolrQuery::getQuery ≫
  • PHP Manual
  • SolrQuery
  • Returns the query fields and their boosts

SolrQuery::getMltQueryFields

(PECL solr >= 0.9.2)

SolrQuery::getMltQueryFields — Returns the query fields and their boosts

説明

public SolrQuery::getMltQueryFields(): array

Returns the query fields and their boosts

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


主なクエリーを返す

  • ≪ SolrQuery::getMltQueryFields
  • SolrQuery::getRows ≫
  • PHP Manual
  • SolrQuery
  • 主なクエリーを返す

SolrQuery::getQuery

(PECL solr >= 0.9.2)

SolrQuery::getQuery — 主なクエリーを返す

説明

public SolrQuery::getQuery(): string

主な検索クエリーを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合は文字列、設定されなかった場合には null を返します。


Returns the maximum number of documents

  • ≪ SolrQuery::getQuery
  • SolrQuery::getSortFields ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of documents

SolrQuery::getRows

(PECL solr >= 0.9.2)

SolrQuery::getRows — Returns the maximum number of documents

説明

public SolrQuery::getRows(): int

Returns the maximum number of documents from the complete result set to return to the client for every request

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns all the sort fields

  • ≪ SolrQuery::getRows
  • SolrQuery::getStart ≫
  • PHP Manual
  • SolrQuery
  • Returns all the sort fields

SolrQuery::getSortFields

(PECL solr >= 0.9.2)

SolrQuery::getSortFields — Returns all the sort fields

説明

public SolrQuery::getSortFields(): array

Returns all the sort fields

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if none of the parameters was set.


Returns the offset in the complete result set

  • ≪ SolrQuery::getSortFields
  • SolrQuery::getStats ≫
  • PHP Manual
  • SolrQuery
  • Returns the offset in the complete result set

SolrQuery::getStart

(PECL solr >= 0.9.2)

SolrQuery::getStart — Returns the offset in the complete result set

説明

public SolrQuery::getStart(): int

Returns the offset in the complete result set for the queries where the set of returned documents should begin.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns whether or not stats is enabled

  • ≪ SolrQuery::getStart
  • SolrQuery::getStatsFacets ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not stats is enabled

SolrQuery::getStats

(PECL solr >= 0.9.2)

SolrQuery::getStats — Returns whether or not stats is enabled

説明

public SolrQuery::getStats(): bool

Returns whether or not stats is enabled

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns all the stats facets that were set

  • ≪ SolrQuery::getStats
  • SolrQuery::getStatsFields ≫
  • PHP Manual
  • SolrQuery
  • Returns all the stats facets that were set

SolrQuery::getStatsFacets

(PECL solr >= 0.9.2)

SolrQuery::getStatsFacets — Returns all the stats facets that were set

説明

public SolrQuery::getStatsFacets(): array

Returns all the stats facets that were set

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns all the statistics fields

  • ≪ SolrQuery::getStatsFacets
  • SolrQuery::getTerms ≫
  • PHP Manual
  • SolrQuery
  • Returns all the statistics fields

SolrQuery::getStatsFields

(PECL solr >= 0.9.2)

SolrQuery::getStatsFields — Returns all the statistics fields

説明

public SolrQuery::getStatsFields(): array

Returns all the statistics fields

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array on success and null if not set.


Returns whether or not the TermsComponent is enabled

  • ≪ SolrQuery::getStatsFields
  • SolrQuery::getTermsField ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not the TermsComponent is enabled

SolrQuery::getTerms

(PECL solr >= 0.9.2)

SolrQuery::getTerms — Returns whether or not the TermsComponent is enabled

説明

public SolrQuery::getTerms(): bool

Returns whether or not the TermsComponent is enabled

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns the field from which the terms are retrieved

  • ≪ SolrQuery::getTerms
  • SolrQuery::getTermsIncludeLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Returns the field from which the terms are retrieved

SolrQuery::getTermsField

(PECL solr >= 0.9.2)

SolrQuery::getTermsField — Returns the field from which the terms are retrieved

説明

public SolrQuery::getTermsField(): string

Returns the field from which the terms are retrieved

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string on success and null if not set.


Returns whether or not to include the lower bound in the result set

  • ≪ SolrQuery::getTermsField
  • SolrQuery::getTermsIncludeUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not to include the lower bound in the result set

SolrQuery::getTermsIncludeLowerBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsIncludeLowerBound — Returns whether or not to include the lower bound in the result set

説明

public SolrQuery::getTermsIncludeLowerBound(): bool

Returns whether or not to include the lower bound in the result set

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns whether or not to include the upper bound term in the result set

  • ≪ SolrQuery::getTermsIncludeLowerBound
  • SolrQuery::getTermsLimit ≫
  • PHP Manual
  • SolrQuery
  • Returns whether or not to include the upper bound term in the result set

SolrQuery::getTermsIncludeUpperBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsIncludeUpperBound — Returns whether or not to include the upper bound term in the result set

説明

public SolrQuery::getTermsIncludeUpperBound(): bool

Returns whether or not to include the upper bound term in the result set

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns the maximum number of terms Solr should return

  • ≪ SolrQuery::getTermsIncludeUpperBound
  • SolrQuery::getTermsLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum number of terms Solr should return

SolrQuery::getTermsLimit

(PECL solr >= 0.9.2)

SolrQuery::getTermsLimit — Returns the maximum number of terms Solr should return

説明

public SolrQuery::getTermsLimit(): int

Returns the maximum number of terms Solr should return

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the term to start at

  • ≪ SolrQuery::getTermsLimit
  • SolrQuery::getTermsMaxCount ≫
  • PHP Manual
  • SolrQuery
  • Returns the term to start at

SolrQuery::getTermsLowerBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsLowerBound — Returns the term to start at

説明

public SolrQuery::getTermsLowerBound(): string

Returns the term to start at

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string on success and null if not set.


Returns the maximum document frequency

  • ≪ SolrQuery::getTermsLowerBound
  • SolrQuery::getTermsMinCount ≫
  • PHP Manual
  • SolrQuery
  • Returns the maximum document frequency

SolrQuery::getTermsMaxCount

(PECL solr >= 0.9.2)

SolrQuery::getTermsMaxCount — Returns the maximum document frequency

説明

public SolrQuery::getTermsMaxCount(): int

Returns the maximum document frequency

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the minimum document frequency to return in order to be included

  • ≪ SolrQuery::getTermsMaxCount
  • SolrQuery::getTermsPrefix ≫
  • PHP Manual
  • SolrQuery
  • Returns the minimum document frequency to return in order to be included

SolrQuery::getTermsMinCount

(PECL solr >= 0.9.2)

SolrQuery::getTermsMinCount — Returns the minimum document frequency to return in order to be included

説明

public SolrQuery::getTermsMinCount(): int

Returns the minimum document frequency to return in order to be included

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the term prefix

  • ≪ SolrQuery::getTermsMinCount
  • SolrQuery::getTermsReturnRaw ≫
  • PHP Manual
  • SolrQuery
  • Returns the term prefix

SolrQuery::getTermsPrefix

(PECL solr >= 0.9.2)

SolrQuery::getTermsPrefix — Returns the term prefix

説明

public SolrQuery::getTermsPrefix(): string

Returns the prefix to which matching terms must be restricted. This will restrict matches to only terms that start with the prefix

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string on success and null if not set.


Whether or not to return raw characters

  • ≪ SolrQuery::getTermsPrefix
  • SolrQuery::getTermsSort ≫
  • PHP Manual
  • SolrQuery
  • Whether or not to return raw characters

SolrQuery::getTermsReturnRaw

(PECL solr >= 0.9.2)

SolrQuery::getTermsReturnRaw — Whether or not to return raw characters

説明

public SolrQuery::getTermsReturnRaw(): bool

Returns a boolean indicating whether or not to return the raw characters of the indexed term, regardless of if it is human readable

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a boolean on success and null if not set.


Returns an integer indicating how terms are sorted

  • ≪ SolrQuery::getTermsReturnRaw
  • SolrQuery::getTermsUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Returns an integer indicating how terms are sorted

SolrQuery::getTermsSort

(PECL solr >= 0.9.2)

SolrQuery::getTermsSort — Returns an integer indicating how terms are sorted

説明

public SolrQuery::getTermsSort(): int

SolrQuery::TERMS_SORT_INDEX indicates that the terms are returned by index order. SolrQuery::TERMS_SORT_COUNT implies that the terms are sorted by term frequency (highest count first)

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an integer on success and null if not set.


Returns the term to stop at

  • ≪ SolrQuery::getTermsSort
  • SolrQuery::getTimeAllowed ≫
  • PHP Manual
  • SolrQuery
  • Returns the term to stop at

SolrQuery::getTermsUpperBound

(PECL solr >= 0.9.2)

SolrQuery::getTermsUpperBound — Returns the term to stop at

説明

public SolrQuery::getTermsUpperBound(): string

Returns the term to stop at

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string on success and null if not set.


Returns the time in milliseconds allowed for the query to finish

  • ≪ SolrQuery::getTermsUpperBound
  • SolrQuery::removeExpandFilterQuery ≫
  • PHP Manual
  • SolrQuery
  • Returns the time in milliseconds allowed for the query to finish

SolrQuery::getTimeAllowed

(PECL solr >= 0.9.2)

SolrQuery::getTimeAllowed — Returns the time in milliseconds allowed for the query to finish

説明

public SolrQuery::getTimeAllowed(): int

Returns the time in milliseconds allowed for the query to finish.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns and integer on success and null if it is not set.


Removes an expand filter query

  • ≪ SolrQuery::getTimeAllowed
  • SolrQuery::removeExpandSortField ≫
  • PHP Manual
  • SolrQuery
  • Removes an expand filter query

SolrQuery::removeExpandFilterQuery

(PECL solr >= 2.2.0)

SolrQuery::removeExpandFilterQuery — Removes an expand filter query

説明

public SolrQuery::removeExpandFilterQuery(string $fq): SolrQuery

Removes an expand filter query.

パラメータ

fq

戻り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group


Removes an expand sort field from the expand.sort parameter

  • ≪ SolrQuery::removeExpandFilterQuery
  • SolrQuery::removeFacetDateField ≫
  • PHP Manual
  • SolrQuery
  • Removes an expand sort field from the expand.sort parameter

SolrQuery::removeExpandSortField

(PECL solr >= 2.2.0)

SolrQuery::removeExpandSortField — Removes an expand sort field from the expand.sort parameter

説明

public SolrQuery::removeExpandSortField(string $field): SolrQuery

Removes an expand sort field from the expand.sort parameter.

パラメータ

field

field name

戻り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query


Removes one of the facet date fields

  • ≪ SolrQuery::removeExpandSortField
  • SolrQuery::removeFacetDateOther ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet date fields

SolrQuery::removeFacetDateField

(PECL solr >= 0.9.2)

SolrQuery::removeFacetDateField — Removes one of the facet date fields

説明

public SolrQuery::removeFacetDateField(string $field): SolrQuery

The name of the field

パラメータ

field

The name of the date field to remove

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the facet.date.other parameters

  • ≪ SolrQuery::removeFacetDateField
  • SolrQuery::removeFacetField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet.date.other parameters

SolrQuery::removeFacetDateOther

(PECL solr >= 0.9.2)

SolrQuery::removeFacetDateOther — Removes one of the facet.date.other parameters

説明

public SolrQuery::removeFacetDateOther(string $value, string $field_override = ?): SolrQuery

Removes one of the facet.date.other parameters

パラメータ

value

The value

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the facet.date parameters

  • ≪ SolrQuery::removeFacetDateOther
  • SolrQuery::removeFacetQuery ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet.date parameters

SolrQuery::removeFacetField

(PECL solr >= 0.9.2)

SolrQuery::removeFacetField — Removes one of the facet.date parameters

説明

public SolrQuery::removeFacetField(string $field): SolrQuery

Removes one of the facet.date parameters

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the facet.query parameters

  • ≪ SolrQuery::removeFacetField
  • SolrQuery::removeField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the facet.query parameters

SolrQuery::removeFacetQuery

(PECL solr >= 0.9.2)

SolrQuery::removeFacetQuery — Removes one of the facet.query parameters

説明

public SolrQuery::removeFacetQuery(string $value): SolrQuery

Removes one of the facet.query parameters.

パラメータ

value

The value

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes a field from the list of fields

  • ≪ SolrQuery::removeFacetQuery
  • SolrQuery::removeFilterQuery ≫
  • PHP Manual
  • SolrQuery
  • Removes a field from the list of fields

SolrQuery::removeField

(PECL solr >= 0.9.2)

SolrQuery::removeField — Removes a field from the list of fields

説明

public SolrQuery::removeField(string $field): SolrQuery

Removes a field from the list of fields

パラメータ

field

Name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes a filter query

  • ≪ SolrQuery::removeField
  • SolrQuery::removeHighlightField ≫
  • PHP Manual
  • SolrQuery
  • Removes a filter query

SolrQuery::removeFilterQuery

(PECL solr >= 0.9.2)

SolrQuery::removeFilterQuery — Removes a filter query

説明

public SolrQuery::removeFilterQuery(string $fq): SolrQuery

Removes a filter query.

パラメータ

fq

The filter query to remove

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the fields used for highlighting

  • ≪ SolrQuery::removeFilterQuery
  • SolrQuery::removeMltField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the fields used for highlighting

SolrQuery::removeHighlightField

(PECL solr >= 0.9.2)

SolrQuery::removeHighlightField — Removes one of the fields used for highlighting

説明

public SolrQuery::removeHighlightField(string $field): SolrQuery

Removes one of the fields used for highlighting.

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the moreLikeThis fields

  • ≪ SolrQuery::removeHighlightField
  • SolrQuery::removeMltQueryField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the moreLikeThis fields

SolrQuery::removeMltField

(PECL solr >= 0.9.2)

SolrQuery::removeMltField — Removes one of the moreLikeThis fields

説明

public SolrQuery::removeMltField(string $field): SolrQuery

Removes one of the moreLikeThis fields.

パラメータ

field

Name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the moreLikeThis query fields

  • ≪ SolrQuery::removeMltField
  • SolrQuery::removeSortField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the moreLikeThis query fields

SolrQuery::removeMltQueryField

(PECL solr >= 0.9.2)

SolrQuery::removeMltQueryField — Removes one of the moreLikeThis query fields

説明

public SolrQuery::removeMltQueryField(string $queryField): SolrQuery

Removes one of the moreLikeThis query fields.

パラメータ

queryField

The query field

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the sort fields

  • ≪ SolrQuery::removeMltQueryField
  • SolrQuery::removeStatsFacet ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the sort fields

SolrQuery::removeSortField

(PECL solr >= 0.9.2)

SolrQuery::removeSortField — Removes one of the sort fields

説明

public SolrQuery::removeSortField(string $field): SolrQuery

Removes one of the sort fields

パラメータ

field

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the stats.facet parameters

  • ≪ SolrQuery::removeSortField
  • SolrQuery::removeStatsField ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the stats.facet parameters

SolrQuery::removeStatsFacet

(PECL solr >= 0.9.2)

SolrQuery::removeStatsFacet — Removes one of the stats.facet parameters

説明

public SolrQuery::removeStatsFacet(string $value): SolrQuery

Removes one of the stats.facet parameters

パラメータ

value

The value

戻り値

Returns the current SolrQuery object, if the return value is used.


Removes one of the stats.field parameters

  • ≪ SolrQuery::removeStatsFacet
  • SolrQuery::setEchoHandler ≫
  • PHP Manual
  • SolrQuery
  • Removes one of the stats.field parameters

SolrQuery::removeStatsField

(PECL solr >= 0.9.2)

SolrQuery::removeStatsField — Removes one of the stats.field parameters

説明

public SolrQuery::removeStatsField(string $field): SolrQuery

Removes one of the stats.field parameters

パラメータ

field

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Toggles the echoHandler parameter

  • ≪ SolrQuery::removeStatsField
  • SolrQuery::setEchoParams ≫
  • PHP Manual
  • SolrQuery
  • Toggles the echoHandler parameter

SolrQuery::setEchoHandler

(PECL solr >= 0.9.2)

SolrQuery::setEchoHandler — Toggles the echoHandler parameter

説明

public SolrQuery::setEchoHandler(bool $flag): SolrQuery

If set to true, Solr places the name of the handle used in the response to the client for debugging purposes.

パラメータ

flag

true or false

戻り値

Returns the current SolrQuery object, if the return value is used.


Determines what kind of parameters to include in the response

  • ≪ SolrQuery::setEchoHandler
  • SolrQuery::setExpand ≫
  • PHP Manual
  • SolrQuery
  • Determines what kind of parameters to include in the response

SolrQuery::setEchoParams

(PECL solr >= 0.9.2)

SolrQuery::setEchoParams — Determines what kind of parameters to include in the response

説明

public SolrQuery::setEchoParams(string $type): SolrQuery

Instructs Solr what kinds of Request parameters should be included in the response for debugging purposes, legal values include:

- none - don't include any request parameters for debugging
- explicit - include the parameters explicitly specified by the client in the request
- all - include all parameters involved in this request, either specified explicitly by the client, or implicit because of the request handler configuration.

パラメータ

type

The type of parameters to include

戻り値

Returns the current SolrQuery object, if the return value is used.


Enables/Disables the Expand Component

  • ≪ SolrQuery::setEchoParams
  • SolrQuery::setExpandQuery ≫
  • PHP Manual
  • SolrQuery
  • Enables/Disables the Expand Component

SolrQuery::setExpand

(PECL solr >= 2.2.0)

SolrQuery::setExpand — Enables/Disables the Expand Component

説明

public SolrQuery::setExpand(bool $value): SolrQuery

Enables/Disables the Expand Component.

パラメータ

value

Bool flag

戻り値

SolrQuery

例

例1 SolrQuery::setExpand() example

<?php

$query = new SolrQuery('lucene');

$query
->setExpand(true)
->setExpandRows(50)
->setExpandQuery('text:product')
->addExpandFilterQuery('manu:apple')
->addExpandFilterQuery('inStock:true')
->addExpandSortField('score', SolrQuery::ORDER_DESC)
->addExpandSortField('title', SolrQuery::ORDER_ASC);

echo $query.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&expand=true&expand.rows=50&expand.q=text:product&expand.fq=manu:apple&expand.fq=inStock:true&expand.sort=score desc,title asc

参考

  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query


Sets the expand.q parameter

  • ≪ SolrQuery::setExpand
  • SolrQuery::setExpandRows ≫
  • PHP Manual
  • SolrQuery
  • Sets the expand.q parameter

SolrQuery::setExpandQuery

(PECL solr >= 2.2.0)

SolrQuery::setExpandQuery — Sets the expand.q parameter

説明

public SolrQuery::setExpandQuery(string $q): SolrQuery

Sets the expand.q parameter.

Overrides the main q parameter, determines which documents to include in the main group.

パラメータ

q

戻り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandRows() - Sets the number of rows to display in each group (expand.rows). Server Default 5
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query


Sets the number of rows to display in each group (expand.rows). Server Default 5

  • ≪ SolrQuery::setExpandQuery
  • SolrQuery::setExplainOther ≫
  • PHP Manual
  • SolrQuery
  • Sets the number of rows to display in each group (expand.rows). Server Default 5

SolrQuery::setExpandRows

(PECL solr >= 2.2.0)

SolrQuery::setExpandRows — Sets the number of rows to display in each group (expand.rows). Server Default 5

説明

public SolrQuery::setExpandRows(int $value): SolrQuery

Sets the number of rows to display in each group (expand.rows). Server Default 5

パラメータ

value

戻り値

SolrQuery

参考

  • SolrQuery::setExpand() - Enables/Disables the Expand Component
  • SolrQuery::addExpandSortField() - Orders the documents within the expanded groups (expand.sort parameter)
  • SolrQuery::removeExpandSortField() - Removes an expand sort field from the expand.sort parameter
  • SolrQuery::setExpandQuery() - Sets the expand.q parameter
  • SolrQuery::addExpandFilterQuery() - Overrides main filter query, determines which documents to include in the main group
  • SolrQuery::removeExpandFilterQuery() - Removes an expand filter query


Sets the explainOther common query parameter

  • ≪ SolrQuery::setExpandRows
  • SolrQuery::setFacet ≫
  • PHP Manual
  • SolrQuery
  • Sets the explainOther common query parameter

SolrQuery::setExplainOther

(PECL solr >= 0.9.2)

SolrQuery::setExplainOther — Sets the explainOther common query parameter

説明

public SolrQuery::setExplainOther(string $query): SolrQuery

Sets the explainOther common query parameter

パラメータ

query

The Lucene query to identify a set of documents

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to the facet parameter. Enables or disables facetting

  • ≪ SolrQuery::setExplainOther
  • SolrQuery::setFacetDateEnd ≫
  • PHP Manual
  • SolrQuery
  • Maps to the facet parameter. Enables or disables facetting

SolrQuery::setFacet

(PECL solr >= 0.9.2)

SolrQuery::setFacet — Maps to the facet parameter. Enables or disables facetting

説明

public SolrQuery::setFacet(bool $flag): SolrQuery

Enables or disables faceting.

パラメータ

value

true enables faceting and false disables it.

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.date.end

  • ≪ SolrQuery::setFacet
  • SolrQuery::setFacetDateGap ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.end

SolrQuery::setFacetDateEnd

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateEnd — Maps to facet.date.end

説明

public SolrQuery::setFacetDateEnd(string $value, string $field_override = ?): SolrQuery

Maps to facet.date.end

パラメータ

value

See facet.date.end

field_override

Name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.date.gap

  • ≪ SolrQuery::setFacetDateEnd
  • SolrQuery::setFacetDateHardEnd ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.gap

SolrQuery::setFacetDateGap

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateGap — Maps to facet.date.gap

説明

public SolrQuery::setFacetDateGap(string $value, string $field_override = ?): SolrQuery

Maps to facet.date.gap

パラメータ

value

See facet.date.gap

field_override

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.date.hardend

  • ≪ SolrQuery::setFacetDateGap
  • SolrQuery::setFacetDateStart ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.hardend

SolrQuery::setFacetDateHardEnd

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateHardEnd — Maps to facet.date.hardend

説明

public SolrQuery::setFacetDateHardEnd(bool $value, string $field_override = ?): SolrQuery

Maps to facet.date.hardend

パラメータ

value

See facet.date.hardend

field_override

The name of the field

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.date.start

  • ≪ SolrQuery::setFacetDateHardEnd
  • SolrQuery::setFacetEnumCacheMinDefaultFrequency ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.date.start

SolrQuery::setFacetDateStart

(PECL solr >= 0.9.2)

SolrQuery::setFacetDateStart — Maps to facet.date.start

説明

public SolrQuery::setFacetDateStart(string $value, string $field_override = ?): SolrQuery

Maps to facet.date.start

パラメータ

value

See facet.date.start

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the minimum document frequency used for determining term count

  • ≪ SolrQuery::setFacetDateStart
  • SolrQuery::setFacetLimit ≫
  • PHP Manual
  • SolrQuery
  • Sets the minimum document frequency used for determining term count

SolrQuery::setFacetEnumCacheMinDefaultFrequency

(PECL solr >= 0.9.2)

SolrQuery::setFacetEnumCacheMinDefaultFrequency — Sets the minimum document frequency used for determining term count

説明

public SolrQuery::setFacetEnumCacheMinDefaultFrequency(int $frequency, string $field_override = ?): SolrQuery

Sets the minimum document frequency used for determining term count

パラメータ

value

The minimum frequency

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.limit

  • ≪ SolrQuery::setFacetEnumCacheMinDefaultFrequency
  • SolrQuery::setFacetMethod ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.limit

SolrQuery::setFacetLimit

(PECL solr >= 0.9.2)

SolrQuery::setFacetLimit — Maps to facet.limit

説明

public SolrQuery::setFacetLimit(int $limit, string $field_override = ?): SolrQuery

Maps to facet.limit. Sets the maximum number of constraint counts that should be returned for the facet fields.

パラメータ

limit

The maximum number of constraint counts

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies the type of algorithm to use when faceting a field

  • ≪ SolrQuery::setFacetLimit
  • SolrQuery::setFacetMinCount ≫
  • PHP Manual
  • SolrQuery
  • Specifies the type of algorithm to use when faceting a field

SolrQuery::setFacetMethod

(PECL solr >= 0.9.2)

SolrQuery::setFacetMethod — Specifies the type of algorithm to use when faceting a field

説明

public SolrQuery::setFacetMethod(string $method, string $field_override = ?): SolrQuery

Specifies the type of algorithm to use when faceting a field. This method accepts optional field override.

パラメータ

method

The method to use.

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.mincount

  • ≪ SolrQuery::setFacetMethod
  • SolrQuery::setFacetMissing ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.mincount

SolrQuery::setFacetMinCount

(PECL solr >= 0.9.2)

SolrQuery::setFacetMinCount — Maps to facet.mincount

説明

public SolrQuery::setFacetMinCount(int $mincount, string $field_override = ?): SolrQuery

Sets the minimum counts for facet fields that should be included in the response

パラメータ

mincount

The minimum count

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Maps to facet.missing

  • ≪ SolrQuery::setFacetMinCount
  • SolrQuery::setFacetOffset ≫
  • PHP Manual
  • SolrQuery
  • Maps to facet.missing

SolrQuery::setFacetMissing

(PECL solr >= 0.9.2)

SolrQuery::setFacetMissing — Maps to facet.missing

説明

public SolrQuery::setFacetMissing(bool $flag, string $field_override = ?): SolrQuery

Used to indicate that in addition to the Term-based constraints of a facet field, a count of all matching results which have no value for the field should be computed

パラメータ

flag

true turns this feature on. false disables it.

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the offset into the list of constraints to allow for pagination

  • ≪ SolrQuery::setFacetMissing
  • SolrQuery::setFacetPrefix ≫
  • PHP Manual
  • SolrQuery
  • Sets the offset into the list of constraints to allow for pagination

SolrQuery::setFacetOffset

(PECL solr >= 0.9.2)

SolrQuery::setFacetOffset — Sets the offset into the list of constraints to allow for pagination

説明

public SolrQuery::setFacetOffset(int $offset, string $field_override = ?): SolrQuery

Sets the offset into the list of constraints to allow for pagination.

パラメータ

offset

The offset

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies a string prefix with which to limits the terms on which to facet

  • ≪ SolrQuery::setFacetOffset
  • SolrQuery::setFacetSort ≫
  • PHP Manual
  • SolrQuery
  • Specifies a string prefix with which to limits the terms on which to facet

SolrQuery::setFacetPrefix

(PECL solr >= 0.9.2)

SolrQuery::setFacetPrefix — Specifies a string prefix with which to limits the terms on which to facet

説明

public SolrQuery::setFacetPrefix(string $prefix, string $field_override = ?): SolrQuery

Specifies a string prefix with which to limits the terms on which to facet.

パラメータ

prefix

The prefix string

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Determines the ordering of the facet field constraints

  • ≪ SolrQuery::setFacetPrefix
  • SolrQuery::setGroup ≫
  • PHP Manual
  • SolrQuery
  • Determines the ordering of the facet field constraints

SolrQuery::setFacetSort

(PECL solr >= 0.9.2)

SolrQuery::setFacetSort — Determines the ordering of the facet field constraints

説明

public SolrQuery::setFacetSort(int $facetSort, string $field_override = ?): SolrQuery

Determines the ordering of the facet field constraints

パラメータ

facetSort

Use SolrQuery::FACET_SORT_INDEX for sorting by index order or SolrQuery::FACET_SORT_COUNT for sorting by count.

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Enable/Disable result grouping (group parameter)

  • ≪ SolrQuery::setFacetSort
  • SolrQuery::setGroupCachePercent ≫
  • PHP Manual
  • SolrQuery
  • Enable/Disable result grouping (group parameter)

SolrQuery::setGroup

(PECL solr >= 2.2.0)

SolrQuery::setGroup — Enable/Disable result grouping (group parameter)

説明

public SolrQuery::setGroup(bool $value): SolrQuery

Enable/Disable result grouping (group parameter)

パラメータ

value

戻り値

参考

  • SolrQuery::getGroup() - Returns true if grouping is enabled
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Enables caching for result grouping

  • ≪ SolrQuery::setGroup
  • SolrQuery::setGroupFacet ≫
  • PHP Manual
  • SolrQuery
  • Enables caching for result grouping

SolrQuery::setGroupCachePercent

(PECL solr >= 2.2.0)

SolrQuery::setGroupCachePercent — Enables caching for result grouping

説明

public SolrQuery::setGroupCachePercent(int $percent): SolrQuery

Setting this parameter to a number greater than 0 enables caching for result grouping. Result Grouping executes two searches; this option caches the second search. The server default value is 0. Testing has shown that group caching only improves search time with Boolean, wildcard, and fuzzy queries. For simple queries like term or "match all" queries, group caching degrades performance. group.cache.percent parameter

パラメータ

percent

戻り値

エラー / 例外

Emits SolrIllegalArgumentException in case of an invalid parameter was passed.

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)


Sets group.facet parameter

  • ≪ SolrQuery::setGroupCachePercent
  • SolrQuery::setGroupFormat ≫
  • PHP Manual
  • SolrQuery
  • Sets group.facet parameter

SolrQuery::setGroupFacet

(PECL solr >= 2.2.0)

SolrQuery::setGroupFacet — Sets group.facet parameter

説明

public SolrQuery::setGroupFacet(bool $value): SolrQuery

Determines whether to compute grouped facets for the field facets specified in facet.field parameters. Grouped facets are computed based on the first specified group.

パラメータ

value

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Sets the group format, result structure (group.format parameter)

  • ≪ SolrQuery::setGroupFacet
  • SolrQuery::setGroupLimit ≫
  • PHP Manual
  • SolrQuery
  • Sets the group format, result structure (group.format parameter)

SolrQuery::setGroupFormat

(PECL solr >= 2.2.0)

SolrQuery::setGroupFormat — Sets the group format, result structure (group.format parameter)

説明

public SolrQuery::setGroupFormat(string $value): SolrQuery

Sets the group.format parameter. If this parameter is set to simple, the grouped documents are presented in a single flat list, and the start and rows parameters affect the numbers of documents instead of groups. Accepts: grouped/simple

パラメータ

value

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Specifies the number of results to return for each group. The server default value is 1

  • ≪ SolrQuery::setGroupFormat
  • SolrQuery::setGroupMain ≫
  • PHP Manual
  • SolrQuery
  • Specifies the number of results to return for each group. The server default value is 1

SolrQuery::setGroupLimit

(PECL solr >= 2.2.0)

SolrQuery::setGroupLimit — Specifies the number of results to return for each group. The server default value is 1

説明

public SolrQuery::setGroupLimit(int $value): SolrQuery

Specifies the number of results to return for each group. The server default value is 1.

パラメータ

value

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

  • ≪ SolrQuery::setGroupLimit
  • SolrQuery::setGroupNGroups ≫
  • PHP Manual
  • SolrQuery
  • If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

SolrQuery::setGroupMain

(PECL solr >= 2.2.0)

SolrQuery::setGroupMain — If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple

説明

public SolrQuery::setGroupMain(string $value): SolrQuery

If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple.

パラメータ

value

If true, the result of the first field grouping command is used as the main result list in the response.

戻り値

Returns an instance of SolrQuery.

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupMain()
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


If true, Solr includes the number of groups that have matched the query in the results

  • ≪ SolrQuery::setGroupMain
  • SolrQuery::setGroupOffset ≫
  • PHP Manual
  • SolrQuery
  • If true, Solr includes the number of groups that have matched the query in the results

SolrQuery::setGroupNGroups

(PECL solr >= 2.2.0)

SolrQuery::setGroupNGroups — If true, Solr includes the number of groups that have matched the query in the results

説明

public SolrQuery::setGroupNGroups(bool $value): SolrQuery

If true, Solr includes the number of groups that have matched the query in the results.

パラメータ

value

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Sets the group.offset parameter

  • ≪ SolrQuery::setGroupNGroups
  • SolrQuery::setGroupTruncate ≫
  • PHP Manual
  • SolrQuery
  • Sets the group.offset parameter

SolrQuery::setGroupOffset

(PECL solr >= 2.2.0)

SolrQuery::setGroupOffset — Sets the group.offset parameter

説明

public SolrQuery::setGroupOffset(int $value): SolrQuery

Sets the group.offset parameter.

パラメータ

value

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupTruncate() - If true, facet counts are based on the most relevant document of each group matching the query
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


If true, facet counts are based on the most relevant document of each group matching the query

  • ≪ SolrQuery::setGroupOffset
  • SolrQuery::setHighlight ≫
  • PHP Manual
  • SolrQuery
  • If true, facet counts are based on the most relevant document of each group matching the query

SolrQuery::setGroupTruncate

(PECL solr >= 2.2.0)

SolrQuery::setGroupTruncate — If true, facet counts are based on the most relevant document of each group matching the query

説明

public SolrQuery::setGroupTruncate(bool $value): SolrQuery

If true, facet counts are based on the most relevant document of each group matching the query. The server default value is false. group.truncate parameter

パラメータ

value

戻り値

参考

  • SolrQuery::setGroup() - Enable/Disable result grouping (group parameter)
  • SolrQuery::addGroupField() - Add a field to be used to group results
  • SolrQuery::addGroupFunction() - Allows grouping results based on the unique values of a function query (group.func parameter)
  • SolrQuery::addGroupQuery() - Allows grouping of documents that match the given query
  • SolrQuery::addGroupSortField() - Add a group sort field (group.sort parameter)
  • SolrQuery::setGroupFacet() - Sets group.facet parameter
  • SolrQuery::setGroupOffset() - Sets the group.offset parameter
  • SolrQuery::setGroupLimit() - Specifies the number of results to return for each group. The server default value is 1
  • SolrQuery::setGroupMain() - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
  • SolrQuery::setGroupNGroups() - If true, Solr includes the number of groups that have matched the query in the results
  • SolrQuery::setGroupFormat() - Sets the group format, result structure (group.format parameter)
  • SolrQuery::setGroupCachePercent() - Enables caching for result grouping


Enables or disables highlighting

  • ≪ SolrQuery::setGroupTruncate
  • SolrQuery::setHighlightAlternateField ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables highlighting

SolrQuery::setHighlight

(PECL solr >= 0.9.2)

SolrQuery::setHighlight — Enables or disables highlighting

説明

public SolrQuery::setHighlight(bool $flag): SolrQuery

Setting it to true enables highlighted snippets to be generated in the query response.

Setting it to false disables highlighting

パラメータ

flag

Enable or disable highlighting

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies the backup field to use

  • ≪ SolrQuery::setHighlight
  • SolrQuery::setHighlightFormatter ≫
  • PHP Manual
  • SolrQuery
  • Specifies the backup field to use

SolrQuery::setHighlightAlternateField

(PECL solr >= 0.9.2)

SolrQuery::setHighlightAlternateField — Specifies the backup field to use

説明

public SolrQuery::setHighlightAlternateField(string $field, string $field_override = ?): SolrQuery

If a snippet cannot be generated because there were no matching terms, one can specify a field to use as the backup or default summary

パラメータ

field

The name of the backup field

field_override

The name of the field we are overriding this setting for.

戻り値

Returns the current SolrQuery object, if the return value is used.


Specify a formatter for the highlight output

  • ≪ SolrQuery::setHighlightAlternateField
  • SolrQuery::setHighlightFragmenter ≫
  • PHP Manual
  • SolrQuery
  • Specify a formatter for the highlight output

SolrQuery::setHighlightFormatter

(PECL solr >= 0.9.2)

SolrQuery::setHighlightFormatter — Specify a formatter for the highlight output

説明

public SolrQuery::setHighlightFormatter(string $formatter, string $field_override = ?): SolrQuery

Specify a formatter for the highlight output.

パラメータ

formatter

Currently the only legal value is "simple"

field_override

The name of the field.

戻り値

Returns an instance of SolrQuery.


Sets a text snippet generator for highlighted text

  • ≪ SolrQuery::setHighlightFormatter
  • SolrQuery::setHighlightFragsize ≫
  • PHP Manual
  • SolrQuery
  • Sets a text snippet generator for highlighted text

SolrQuery::setHighlightFragmenter

(PECL solr >= 0.9.2)

SolrQuery::setHighlightFragmenter — Sets a text snippet generator for highlighted text

説明

public SolrQuery::setHighlightFragmenter(string $fragmenter, string $field_override = ?): SolrQuery

Specify a text snippet generator for highlighted text.

パラメータ

fragmenter

The standard fragmenter is gap. Another option is regex, which tries to create fragments that resembles a certain regular expression

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


The size of fragments to consider for highlighting

  • ≪ SolrQuery::setHighlightFragmenter
  • SolrQuery::setHighlightHighlightMultiTerm ≫
  • PHP Manual
  • SolrQuery
  • The size of fragments to consider for highlighting

SolrQuery::setHighlightFragsize

(PECL solr >= 0.9.2)

SolrQuery::setHighlightFragsize — The size of fragments to consider for highlighting

説明

public SolrQuery::setHighlightFragsize(int $size, string $field_override = ?): SolrQuery

Sets the size, in characters, of fragments to consider for highlighting. "0" indicates that the whole field value should be used (no fragmenting).

パラメータ

size

The size, in characters, of fragments to consider for highlighting

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Use SpanScorer to highlight phrase terms

  • ≪ SolrQuery::setHighlightFragsize
  • SolrQuery::setHighlightMaxAlternateFieldLength ≫
  • PHP Manual
  • SolrQuery
  • Use SpanScorer to highlight phrase terms

SolrQuery::setHighlightHighlightMultiTerm

(PECL solr >= 0.9.2)

SolrQuery::setHighlightHighlightMultiTerm — Use SpanScorer to highlight phrase terms

説明

public SolrQuery::setHighlightHighlightMultiTerm(bool $flag): SolrQuery

Use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document.

パラメータ

flag

Whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document.

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the maximum number of characters of the field to return

  • ≪ SolrQuery::setHighlightHighlightMultiTerm
  • SolrQuery::setHighlightMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of characters of the field to return

SolrQuery::setHighlightMaxAlternateFieldLength

(PECL solr >= 0.9.2)

SolrQuery::setHighlightMaxAlternateFieldLength — Sets the maximum number of characters of the field to return

説明

public SolrQuery::setHighlightMaxAlternateFieldLength(int $fieldLength, string $field_override = ?): SolrQuery

If SolrQuery::setHighlightAlternateField() was passed the value true, this parameter specifies the maximum number of characters of the field to return

Any value less than or equal to 0 means unlimited.

パラメータ

fieldLength

The length of the field

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies the number of characters into a document to look for suitable snippets

  • ≪ SolrQuery::setHighlightMaxAlternateFieldLength
  • SolrQuery::setHighlightMergeContiguous ≫
  • PHP Manual
  • SolrQuery
  • Specifies the number of characters into a document to look for suitable snippets

SolrQuery::setHighlightMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::setHighlightMaxAnalyzedChars — Specifies the number of characters into a document to look for suitable snippets

説明

public SolrQuery::setHighlightMaxAnalyzedChars(int $value): SolrQuery

Specifies the number of characters into a document to look for suitable snippets

パラメータ

value

The number of characters into a document to look for suitable snippets

戻り値

Returns the current SolrQuery object, if the return value is used.


Whether or not to collapse contiguous fragments into a single fragment

  • ≪ SolrQuery::setHighlightMaxAnalyzedChars
  • SolrQuery::setHighlightRegexMaxAnalyzedChars ≫
  • PHP Manual
  • SolrQuery
  • Whether or not to collapse contiguous fragments into a single fragment

SolrQuery::setHighlightMergeContiguous

(PECL solr >= 0.9.2)

SolrQuery::setHighlightMergeContiguous — Whether or not to collapse contiguous fragments into a single fragment

説明

public SolrQuery::setHighlightMergeContiguous(bool $flag, string $field_override = ?): SolrQuery

Whether or not to collapse contiguous fragments into a single fragment

パラメータ

value

Whether or not to collapse contiguous fragments into a single fragment

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Specify the maximum number of characters to analyze

  • ≪ SolrQuery::setHighlightMergeContiguous
  • SolrQuery::setHighlightRegexPattern ≫
  • PHP Manual
  • SolrQuery
  • Specify the maximum number of characters to analyze

SolrQuery::setHighlightRegexMaxAnalyzedChars

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRegexMaxAnalyzedChars — Specify the maximum number of characters to analyze

説明

public SolrQuery::setHighlightRegexMaxAnalyzedChars(int $maxAnalyzedChars): SolrQuery

Specify the maximum number of characters to analyze from a field when using the regex fragmenter

パラメータ

maxAnalyzedChars

The maximum number of characters to analyze from a field when using the regex fragmenter

戻り値

Returns the current SolrQuery object, if the return value is used.


Specify the regular expression for fragmenting

  • ≪ SolrQuery::setHighlightRegexMaxAnalyzedChars
  • SolrQuery::setHighlightRegexSlop ≫
  • PHP Manual
  • SolrQuery
  • Specify the regular expression for fragmenting

SolrQuery::setHighlightRegexPattern

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRegexPattern — Specify the regular expression for fragmenting

説明

public SolrQuery::setHighlightRegexPattern(string $value): SolrQuery

Specifies the regular expression for fragmenting. This could be used to extract sentences

パラメータ

value

The regular expression for fragmenting. This could be used to extract sentences

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the factor by which the regex fragmenter can stray from the ideal fragment size

  • ≪ SolrQuery::setHighlightRegexPattern
  • SolrQuery::setHighlightRequireFieldMatch ≫
  • PHP Manual
  • SolrQuery
  • Sets the factor by which the regex fragmenter can stray from the ideal fragment size

SolrQuery::setHighlightRegexSlop

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRegexSlop — Sets the factor by which the regex fragmenter can stray from the ideal fragment size

説明

public SolrQuery::setHighlightRegexSlop(float $factor): SolrQuery

The factor by which the regex fragmenter can stray from the ideal fragment size ( specfied by SolrQuery::setHighlightFragsize )to accommodate the regular expression

パラメータ

factor

The factor by which the regex fragmenter can stray from the ideal fragment size

戻り値

Returns the current SolrQuery object, if the return value is used.


Require field matching during highlighting

  • ≪ SolrQuery::setHighlightRegexSlop
  • SolrQuery::setHighlightSimplePost ≫
  • PHP Manual
  • SolrQuery
  • Require field matching during highlighting

SolrQuery::setHighlightRequireFieldMatch

(PECL solr >= 0.9.2)

SolrQuery::setHighlightRequireFieldMatch — Require field matching during highlighting

説明

public SolrQuery::setHighlightRequireFieldMatch(bool $flag): SolrQuery

If true, then a field will only be highlighted if the query matched in this particular field.

This will only work if SolrQuery::setHighlightUsePhraseHighlighter() was set to true

パラメータ

flag

true or false

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the text which appears after a highlighted term

  • ≪ SolrQuery::setHighlightRequireFieldMatch
  • SolrQuery::setHighlightSimplePre ≫
  • PHP Manual
  • SolrQuery
  • Sets the text which appears after a highlighted term

SolrQuery::setHighlightSimplePost

(PECL solr >= 0.9.2)

SolrQuery::setHighlightSimplePost — Sets the text which appears after a highlighted term

説明

public SolrQuery::setHighlightSimplePost(string $simplePost, string $field_override = ?): SolrQuery

Sets the text which appears before a highlighted term

パラメータ

simplePost

Sets the text which appears after a highlighted term

The default is </em>

field_override

The name of the field.

戻り値

Returns an instance of SolrQuery.


Sets the text which appears before a highlighted term

  • ≪ SolrQuery::setHighlightSimplePost
  • SolrQuery::setHighlightSnippets ≫
  • PHP Manual
  • SolrQuery
  • Sets the text which appears before a highlighted term

SolrQuery::setHighlightSimplePre

(PECL solr >= 0.9.2)

SolrQuery::setHighlightSimplePre — Sets the text which appears before a highlighted term

説明

public SolrQuery::setHighlightSimplePre(string $simplePre, string $field_override = ?): SolrQuery

Sets the text which appears before a highlighted term

The default is <em>

パラメータ

simplePre

The text which appears before a highlighted term

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the maximum number of highlighted snippets to generate per field

  • ≪ SolrQuery::setHighlightSimplePre
  • SolrQuery::setHighlightUsePhraseHighlighter ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of highlighted snippets to generate per field

SolrQuery::setHighlightSnippets

(PECL solr >= 0.9.2)

SolrQuery::setHighlightSnippets — Sets the maximum number of highlighted snippets to generate per field

説明

public SolrQuery::setHighlightSnippets(int $value, string $field_override = ?): SolrQuery

Sets the maximum number of highlighted snippets to generate per field

パラメータ

value

The maximum number of highlighted snippets to generate per field

field_override

The name of the field.

戻り値

Returns the current SolrQuery object, if the return value is used.


Whether to highlight phrase terms only when they appear within the query phrase

  • ≪ SolrQuery::setHighlightSnippets
  • SolrQuery::setMlt ≫
  • PHP Manual
  • SolrQuery
  • Whether to highlight phrase terms only when they appear within the query phrase

SolrQuery::setHighlightUsePhraseHighlighter

(PECL solr >= 0.9.2)

SolrQuery::setHighlightUsePhraseHighlighter — Whether to highlight phrase terms only when they appear within the query phrase

説明

public SolrQuery::setHighlightUsePhraseHighlighter(bool $flag): SolrQuery

Sets whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document

パラメータ

value

Whether or not to use SpanScorer to highlight phrase terms only when they appear within the query phrase in the document

戻り値

Returns the current SolrQuery object, if the return value is used.


Enables or disables moreLikeThis

  • ≪ SolrQuery::setHighlightUsePhraseHighlighter
  • SolrQuery::setMltBoost ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables moreLikeThis

SolrQuery::setMlt

(PECL solr >= 0.9.2)

SolrQuery::setMlt — Enables or disables moreLikeThis

説明

public SolrQuery::setMlt(bool $flag): SolrQuery

Enables or disables moreLikeThis

パラメータ

flag

true enables it and false turns it off.

戻り値

Returns the current SolrQuery object, if the return value is used.


Set if the query will be boosted by the interesting term relevance

  • ≪ SolrQuery::setMlt
  • SolrQuery::setMltCount ≫
  • PHP Manual
  • SolrQuery
  • Set if the query will be boosted by the interesting term relevance

SolrQuery::setMltBoost

(PECL solr >= 0.9.2)

SolrQuery::setMltBoost — Set if the query will be boosted by the interesting term relevance

説明

public SolrQuery::setMltBoost(bool $flag): SolrQuery

Set if the query will be boosted by the interesting term relevance

パラメータ

value

Sets to true or false

戻り値

Returns the current SolrQuery object, if the return value is used.


Set the number of similar documents to return for each result

  • ≪ SolrQuery::setMltBoost
  • SolrQuery::setMltMaxNumQueryTerms ≫
  • PHP Manual
  • SolrQuery
  • Set the number of similar documents to return for each result

SolrQuery::setMltCount

(PECL solr >= 0.9.2)

SolrQuery::setMltCount — Set the number of similar documents to return for each result

説明

public SolrQuery::setMltCount(int $count): SolrQuery

Set the number of similar documents to return for each result

パラメータ

count

The number of similar documents to return for each result

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the maximum number of query terms included

  • ≪ SolrQuery::setMltCount
  • SolrQuery::setMltMaxNumTokens ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of query terms included

SolrQuery::setMltMaxNumQueryTerms

(PECL solr >= 0.9.2)

SolrQuery::setMltMaxNumQueryTerms — Sets the maximum number of query terms included

説明

public SolrQuery::setMltMaxNumQueryTerms(int $value): SolrQuery

Sets the maximum number of query terms that will be included in any generated query.

パラメータ

value

The maximum number of query terms that will be included in any generated query

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies the maximum number of tokens to parse

  • ≪ SolrQuery::setMltMaxNumQueryTerms
  • SolrQuery::setMltMaxWordLength ≫
  • PHP Manual
  • SolrQuery
  • Specifies the maximum number of tokens to parse

SolrQuery::setMltMaxNumTokens

(PECL solr >= 0.9.2)

SolrQuery::setMltMaxNumTokens — Specifies the maximum number of tokens to parse

説明

public SolrQuery::setMltMaxNumTokens(int $value): SolrQuery

Specifies the maximum number of tokens to parse in each example doc field that is not stored with TermVector support.

パラメータ

value

The maximum number of tokens to parse

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the maximum word length

  • ≪ SolrQuery::setMltMaxNumTokens
  • SolrQuery::setMltMinDocFrequency ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum word length

SolrQuery::setMltMaxWordLength

(PECL solr >= 0.9.2)

SolrQuery::setMltMaxWordLength — Sets the maximum word length

説明

public SolrQuery::setMltMaxWordLength(int $maxWordLength): SolrQuery

Sets the maximum word length above which words will be ignored.

パラメータ

maxWordLength

The maximum word length above which words will be ignored

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the mltMinDoc frequency

  • ≪ SolrQuery::setMltMaxWordLength
  • SolrQuery::setMltMinTermFrequency ≫
  • PHP Manual
  • SolrQuery
  • Sets the mltMinDoc frequency

SolrQuery::setMltMinDocFrequency

(PECL solr >= 0.9.2)

SolrQuery::setMltMinDocFrequency — Sets the mltMinDoc frequency

説明

public SolrQuery::setMltMinDocFrequency(int $minDocFrequency): SolrQuery

The frequency at which words will be ignored which do not occur in at least this many docs.

パラメータ

minDocFrequency

Sets the frequency at which words will be ignored which do not occur in at least this many docs.

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the frequency below which terms will be ignored in the source docs

  • ≪ SolrQuery::setMltMinDocFrequency
  • SolrQuery::setMltMinWordLength ≫
  • PHP Manual
  • SolrQuery
  • Sets the frequency below which terms will be ignored in the source docs

SolrQuery::setMltMinTermFrequency

(PECL solr >= 0.9.2)

SolrQuery::setMltMinTermFrequency — Sets the frequency below which terms will be ignored in the source docs

説明

public SolrQuery::setMltMinTermFrequency(int $minTermFrequency): SolrQuery

Sets the frequency below which terms will be ignored in the source docs

パラメータ

minTermFrequency

The frequency below which terms will be ignored in the source docs

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the minimum word length

  • ≪ SolrQuery::setMltMinTermFrequency
  • SolrQuery::setOmitHeader ≫
  • PHP Manual
  • SolrQuery
  • Sets the minimum word length

SolrQuery::setMltMinWordLength

(PECL solr >= 0.9.2)

SolrQuery::setMltMinWordLength — Sets the minimum word length

説明

public SolrQuery::setMltMinWordLength(int $minWordLength): SolrQuery

Sets the minimum word length below which words will be ignored.

パラメータ

minWordLength

The minimum word length below which words will be ignored

戻り値

Returns the current SolrQuery object, if the return value is used.


Exclude the header from the returned results

  • ≪ SolrQuery::setMltMinWordLength
  • SolrQuery::setQuery ≫
  • PHP Manual
  • SolrQuery
  • Exclude the header from the returned results

SolrQuery::setOmitHeader

(PECL solr >= 0.9.2)

SolrQuery::setOmitHeader — Exclude the header from the returned results

説明

public SolrQuery::setOmitHeader(bool $flag): SolrQuery

Exclude the header from the returned results.

パラメータ

flag

true excludes the header from the result.

戻り値

Returns the current SolrQuery object, if the return value is used.


検索クエリーを設定

  • ≪ SolrQuery::setOmitHeader
  • SolrQuery::setRows ≫
  • PHP Manual
  • SolrQuery
  • 検索クエリーを設定

SolrQuery::setQuery

(PECL solr >= 0.9.2)

SolrQuery::setQuery — 検索クエリーを設定

説明

public SolrQuery::setQuery(string $query): SolrQuery

検索クエリーを設定します。

パラメータ

query

検索クエリー

戻り値

現行の SolrQuery オブジェクトを返します。


Specifies the maximum number of rows to return in the result

  • ≪ SolrQuery::setQuery
  • SolrQuery::setShowDebugInfo ≫
  • PHP Manual
  • SolrQuery
  • Specifies the maximum number of rows to return in the result

SolrQuery::setRows

(PECL solr >= 0.9.2)

SolrQuery::setRows — Specifies the maximum number of rows to return in the result

説明

public SolrQuery::setRows(int $rows): SolrQuery

Specifies the maximum number of rows to return in the result

パラメータ

rows

The maximum number of rows to return

戻り値

Returns the current SolrQuery object.


Flag to show debug information

  • ≪ SolrQuery::setRows
  • SolrQuery::setStart ≫
  • PHP Manual
  • SolrQuery
  • Flag to show debug information

SolrQuery::setShowDebugInfo

(PECL solr >= 0.9.2)

SolrQuery::setShowDebugInfo — Flag to show debug information

説明

public SolrQuery::setShowDebugInfo(bool $flag): SolrQuery

Whether to show debug info

パラメータ

flag

Whether to show debug info. true or false

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies the number of rows to skip

  • ≪ SolrQuery::setShowDebugInfo
  • SolrQuery::setStats ≫
  • PHP Manual
  • SolrQuery
  • Specifies the number of rows to skip

SolrQuery::setStart

(PECL solr >= 0.9.2)

SolrQuery::setStart — Specifies the number of rows to skip

説明

public SolrQuery::setStart(int $start): SolrQuery

Specifies the number of rows to skip. Useful in pagination of results.

パラメータ

start

The number of rows to skip.

戻り値

Returns the current SolrQuery object.


Enables or disables the Stats component

  • ≪ SolrQuery::setStart
  • SolrQuery::setTerms ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables the Stats component

SolrQuery::setStats

(PECL solr >= 0.9.2)

SolrQuery::setStats — Enables or disables the Stats component

説明

public SolrQuery::setStats(bool $flag): SolrQuery

Enables or disables the Stats component.

パラメータ

flag

true turns on the stats component and false disables it.

戻り値

Returns the current SolrQuery object, if the return value is used.


Enables or disables the TermsComponent

  • ≪ SolrQuery::setStats
  • SolrQuery::setTermsField ≫
  • PHP Manual
  • SolrQuery
  • Enables or disables the TermsComponent

SolrQuery::setTerms

(PECL solr >= 0.9.2)

SolrQuery::setTerms — Enables or disables the TermsComponent

説明

public SolrQuery::setTerms(bool $flag): SolrQuery

Enables or disables the TermsComponent

パラメータ

flag

true enables it. false turns it off

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the name of the field to get the Terms from

  • ≪ SolrQuery::setTerms
  • SolrQuery::setTermsIncludeLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Sets the name of the field to get the Terms from

SolrQuery::setTermsField

(PECL solr >= 0.9.2)

SolrQuery::setTermsField — Sets the name of the field to get the Terms from

説明

public SolrQuery::setTermsField(string $fieldname): SolrQuery

Sets the name of the field to get the terms from

パラメータ

fieldname

The field name

戻り値

Returns the current SolrQuery object, if the return value is used.


Include the lower bound term in the result set

  • ≪ SolrQuery::setTermsField
  • SolrQuery::setTermsIncludeUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Include the lower bound term in the result set

SolrQuery::setTermsIncludeLowerBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsIncludeLowerBound — Include the lower bound term in the result set

説明

public SolrQuery::setTermsIncludeLowerBound(bool $flag): SolrQuery

Include the lower bound term in the result set.

パラメータ

flag

Include the lower bound term in the result set

戻り値

Returns the current SolrQuery object, if the return value is used.


Include the upper bound term in the result set

  • ≪ SolrQuery::setTermsIncludeLowerBound
  • SolrQuery::setTermsLimit ≫
  • PHP Manual
  • SolrQuery
  • Include the upper bound term in the result set

SolrQuery::setTermsIncludeUpperBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsIncludeUpperBound — Include the upper bound term in the result set

説明

public SolrQuery::setTermsIncludeUpperBound(bool $flag): SolrQuery

Include the upper bound term in the result set.

パラメータ

flag

true or false

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the maximum number of terms to return

  • ≪ SolrQuery::setTermsIncludeUpperBound
  • SolrQuery::setTermsLowerBound ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum number of terms to return

SolrQuery::setTermsLimit

(PECL solr >= 0.9.2)

SolrQuery::setTermsLimit — Sets the maximum number of terms to return

説明

public SolrQuery::setTermsLimit(int $limit): SolrQuery

Sets the maximum number of terms to return

パラメータ

limit

The maximum number of terms to return. All the terms will be returned if the limit is negative.

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies the Term to start from

  • ≪ SolrQuery::setTermsLimit
  • SolrQuery::setTermsMaxCount ≫
  • PHP Manual
  • SolrQuery
  • Specifies the Term to start from

SolrQuery::setTermsLowerBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsLowerBound — Specifies the Term to start from

説明

public SolrQuery::setTermsLowerBound(string $lowerBound): SolrQuery

Specifies the Term to start from

パラメータ

lowerBound

The lower bound Term

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the maximum document frequency

  • ≪ SolrQuery::setTermsLowerBound
  • SolrQuery::setTermsMinCount ≫
  • PHP Manual
  • SolrQuery
  • Sets the maximum document frequency

SolrQuery::setTermsMaxCount

(PECL solr >= 0.9.2)

SolrQuery::setTermsMaxCount — Sets the maximum document frequency

説明

public SolrQuery::setTermsMaxCount(int $frequency): SolrQuery

Sets the maximum document frequency.

パラメータ

frequency

The maximum document frequency.

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the minimum document frequency

  • ≪ SolrQuery::setTermsMaxCount
  • SolrQuery::setTermsPrefix ≫
  • PHP Manual
  • SolrQuery
  • Sets the minimum document frequency

SolrQuery::setTermsMinCount

(PECL solr >= 0.9.2)

SolrQuery::setTermsMinCount — Sets the minimum document frequency

説明

public SolrQuery::setTermsMinCount(int $frequency): SolrQuery

Sets the minimum doc frequency to return in order to be included

パラメータ

frequency

The minimum frequency

戻り値

Returns the current SolrQuery object, if the return value is used.


Restrict matches to terms that start with the prefix

  • ≪ SolrQuery::setTermsMinCount
  • SolrQuery::setTermsReturnRaw ≫
  • PHP Manual
  • SolrQuery
  • Restrict matches to terms that start with the prefix

SolrQuery::setTermsPrefix

(PECL solr >= 0.9.2)

SolrQuery::setTermsPrefix — Restrict matches to terms that start with the prefix

説明

public SolrQuery::setTermsPrefix(string $prefix): SolrQuery

Restrict matches to terms that start with the prefix

パラメータ

prefix

Restrict matches to terms that start with the prefix

戻り値

Returns the current SolrQuery object, if the return value is used.


Return the raw characters of the indexed term

  • ≪ SolrQuery::setTermsPrefix
  • SolrQuery::setTermsSort ≫
  • PHP Manual
  • SolrQuery
  • Return the raw characters of the indexed term

SolrQuery::setTermsReturnRaw

(PECL solr >= 0.9.2)

SolrQuery::setTermsReturnRaw — Return the raw characters of the indexed term

説明

public SolrQuery::setTermsReturnRaw(bool $flag): SolrQuery

If true, return the raw characters of the indexed term, regardless of if it is human readable

パラメータ

value

true or false

戻り値

Returns the current SolrQuery object, if the return value is used.


Specifies how to sort the returned terms

  • ≪ SolrQuery::setTermsReturnRaw
  • SolrQuery::setTermsUpperBound ≫
  • PHP Manual
  • SolrQuery
  • Specifies how to sort the returned terms

SolrQuery::setTermsSort

(PECL solr >= 0.9.2)

SolrQuery::setTermsSort — Specifies how to sort the returned terms

説明

public SolrQuery::setTermsSort(int $sortType): SolrQuery

If SolrQuery::TERMS_SORT_COUNT, sorts the terms by the term frequency (highest count first). If SolrQuery::TERMS_SORT_INDEX, returns the terms in index order

パラメータ

sortType

SolrQuery::TERMS_SORT_INDEX or SolrQuery::TERMS_SORT_COUNT

戻り値

Returns the current SolrQuery object, if the return value is used.


Sets the term to stop at

  • ≪ SolrQuery::setTermsSort
  • SolrQuery::setTimeAllowed ≫
  • PHP Manual
  • SolrQuery
  • Sets the term to stop at

SolrQuery::setTermsUpperBound

(PECL solr >= 0.9.2)

SolrQuery::setTermsUpperBound — Sets the term to stop at

説明

public SolrQuery::setTermsUpperBound(string $upperBound): SolrQuery

Sets the term to stop at

パラメータ

upperBound

The term to stop at

戻り値

Returns the current SolrQuery object, if the return value is used.


The time allowed for search to finish

  • ≪ SolrQuery::setTermsUpperBound
  • SolrDisMaxQuery ≫
  • PHP Manual
  • SolrQuery
  • The time allowed for search to finish

SolrQuery::setTimeAllowed

(PECL solr >= 0.9.2)

SolrQuery::setTimeAllowed — The time allowed for search to finish

説明

public SolrQuery::setTimeAllowed(int $timeAllowed): SolrQuery

The time allowed for a search to finish. This value only applies to the search and not to requests in general. Time is in milliseconds. Values less than or equal to zero implies no time restriction. Partial results may be returned, if there are any.

パラメータ

timeAllowed

The time allowed for a search to finish.

戻り値

Returns the current SolrQuery object, if the return value is used.


The SolrDisMaxQuery class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

class SolrDisMaxQuery extends SolrQuery implements Serializable {
/* 継承したプロパティ */
const int SolrQuery::ORDER_ASC = 0;
const int SolrQuery::ORDER_DESC = 1;
const int SolrQuery::FACET_SORT_INDEX = 0;
const int SolrQuery::FACET_SORT_COUNT = 1;
const int SolrQuery::TERMS_SORT_INDEX = 0;
const int SolrQuery::TERMS_SORT_COUNT = 1;
/* メソッド */
public __construct(string $q = ?)
public addBigramPhraseField(string $field, string $boost, string $slop = ?): SolrDisMaxQuery
public addBoostQuery(string $field, string $value, string $boost = ?): SolrDisMaxQuery
public addPhraseField(string $field, string $boost, string $slop = ?): SolrDisMaxQuery
public addQueryField(string $field, string $boost = ?): SolrDisMaxQuery
public addTrigramPhraseField(string $field, string $boost, string $slop = ?): SolrDisMaxQuery
public addUserField(string $field): SolrDisMaxQuery
public removeBigramPhraseField(string $field): SolrDisMaxQuery
public removeBoostQuery(string $field): SolrDisMaxQuery
public removePhraseField(string $field): SolrDisMaxQuery
public removeQueryField(string $field): SolrDisMaxQuery
public removeTrigramPhraseField(string $field): SolrDisMaxQuery
public removeUserField(string $field): SolrDisMaxQuery
public setBigramPhraseFields(string $fields): SolrDisMaxQuery
public setBigramPhraseSlop(string $slop): SolrDisMaxQuery
public setBoostFunction(string $function): SolrDisMaxQuery
public setBoostQuery(string $q): SolrDisMaxQuery
public setMinimumMatch(string $value): SolrDisMaxQuery
public setPhraseFields(string $fields): SolrDisMaxQuery
public setPhraseSlop(string $slop): SolrDisMaxQuery
public setQueryAlt(string $q): SolrDisMaxQuery
public setQueryPhraseSlop(string $slop): SolrDisMaxQuery
public setTieBreaker(string $tieBreaker): SolrDisMaxQuery
public setTrigramPhraseFields(string $fields): SolrDisMaxQuery
public setTrigramPhraseSlop(string $slop): SolrDisMaxQuery
public setUserFields(string $fields): SolrDisMaxQuery
public useDisMaxQueryParser(): SolrDisMaxQuery
public useEDisMaxQueryParser(): SolrDisMaxQuery
/* 継承したメソッド */
public SolrQuery::addExpandFilterQuery(string $fq): SolrQuery
public SolrQuery::addExpandSortField(string $field, string $order = ?): SolrQuery
public SolrQuery::addFacetDateField(string $dateField): SolrQuery
public SolrQuery::addFacetDateOther(string $value, string $field_override = ?): SolrQuery
public SolrQuery::addFacetField(string $field): SolrQuery
public SolrQuery::addFacetQuery(string $facetQuery): SolrQuery
public SolrQuery::addField(string $field): SolrQuery
public SolrQuery::addFilterQuery(string $fq): SolrQuery
public SolrQuery::addGroupField(string $value): SolrQuery
public SolrQuery::addGroupFunction(string $value): SolrQuery
public SolrQuery::addGroupQuery(string $value): SolrQuery
public SolrQuery::addGroupSortField(string $field, int $order = ?): SolrQuery
public SolrQuery::addHighlightField(string $field): SolrQuery
public SolrQuery::addMltField(string $field): SolrQuery
public SolrQuery::addMltQueryField(string $field, float $boost): SolrQuery
public SolrQuery::addSortField(string $field, int $order = SolrQuery::ORDER_DESC): SolrQuery
public SolrQuery::addStatsFacet(string $field): SolrQuery
public SolrQuery::addStatsField(string $field): SolrQuery
public SolrQuery::collapse(SolrCollapseFunction $collapseFunction): SolrQuery
public SolrQuery::getExpand(): bool
public SolrQuery::getExpandFilterQueries(): array
public SolrQuery::getExpandQuery(): array
public SolrQuery::getExpandRows(): int
public SolrQuery::getExpandSortFields(): array
public SolrQuery::getFacet(): bool
public SolrQuery::getFacetDateEnd(string $field_override = ?): string
public SolrQuery::getFacetDateFields(): array
public SolrQuery::getFacetDateGap(string $field_override = ?): string
public SolrQuery::getFacetDateHardEnd(string $field_override = ?): string
public SolrQuery::getFacetDateOther(string $field_override = ?): array
public SolrQuery::getFacetDateStart(string $field_override = ?): string
public SolrQuery::getFacetFields(): array
public SolrQuery::getFacetLimit(string $field_override = ?): int
public SolrQuery::getFacetMethod(string $field_override = ?): string
public SolrQuery::getFacetMinCount(string $field_override = ?): int
public SolrQuery::getFacetMissing(string $field_override = ?): bool
public SolrQuery::getFacetOffset(string $field_override = ?): int
public SolrQuery::getFacetPrefix(string $field_override = ?): string
public SolrQuery::getFacetQueries(): array
public SolrQuery::getFacetSort(string $field_override = ?): int
public SolrQuery::getFields(): array
public SolrQuery::getFilterQueries(): array
public SolrQuery::getGroup(): bool
public SolrQuery::getGroupCachePercent(): int
public SolrQuery::getGroupFacet(): bool
public SolrQuery::getGroupFields(): array
public SolrQuery::getGroupFormat(): string
public SolrQuery::getGroupFunctions(): array
public SolrQuery::getGroupLimit(): int
public SolrQuery::getGroupMain(): bool
public SolrQuery::getGroupNGroups(): bool
public SolrQuery::getGroupOffset(): int
public SolrQuery::getGroupQueries(): array
public SolrQuery::getGroupSortFields(): array
public SolrQuery::getGroupTruncate(): bool
public SolrQuery::getHighlight(): bool
public SolrQuery::getHighlightAlternateField(string $field_override = ?): string
public SolrQuery::getHighlightFields(): array
public SolrQuery::getHighlightFormatter(string $field_override = ?): string
public SolrQuery::getHighlightFragmenter(string $field_override = ?): string
public SolrQuery::getHighlightFragsize(string $field_override = ?): int
public SolrQuery::getHighlightHighlightMultiTerm(): bool
public SolrQuery::getHighlightMaxAlternateFieldLength(string $field_override = ?): int
public SolrQuery::getHighlightMaxAnalyzedChars(): int
public SolrQuery::getHighlightMergeContiguous(string $field_override = ?): bool
public SolrQuery::getHighlightRegexMaxAnalyzedChars(): int
public SolrQuery::getHighlightRegexPattern(): string
public SolrQuery::getHighlightRegexSlop(): float
public SolrQuery::getHighlightRequireFieldMatch(): bool
public SolrQuery::getHighlightSimplePost(string $field_override = ?): string
public SolrQuery::getHighlightSimplePre(string $field_override = ?): string
public SolrQuery::getHighlightSnippets(string $field_override = ?): int
public SolrQuery::getHighlightUsePhraseHighlighter(): bool
public SolrQuery::getMlt(): bool
public SolrQuery::getMltBoost(): bool
public SolrQuery::getMltCount(): int
public SolrQuery::getMltFields(): array
public SolrQuery::getMltMaxNumQueryTerms(): int
public SolrQuery::getMltMaxNumTokens(): int
public SolrQuery::getMltMaxWordLength(): int
public SolrQuery::getMltMinDocFrequency(): int
public SolrQuery::getMltMinTermFrequency(): int
public SolrQuery::getMltMinWordLength(): int
public SolrQuery::getMltQueryFields(): array
public SolrQuery::getQuery(): string
public SolrQuery::getRows(): int
public SolrQuery::getSortFields(): array
public SolrQuery::getStart(): int
public SolrQuery::getStats(): bool
public SolrQuery::getStatsFacets(): array
public SolrQuery::getStatsFields(): array
public SolrQuery::getTerms(): bool
public SolrQuery::getTermsField(): string
public SolrQuery::getTermsIncludeLowerBound(): bool
public SolrQuery::getTermsIncludeUpperBound(): bool
public SolrQuery::getTermsLimit(): int
public SolrQuery::getTermsLowerBound(): string
public SolrQuery::getTermsMaxCount(): int
public SolrQuery::getTermsMinCount(): int
public SolrQuery::getTermsPrefix(): string
public SolrQuery::getTermsReturnRaw(): bool
public SolrQuery::getTermsSort(): int
public SolrQuery::getTermsUpperBound(): string
public SolrQuery::getTimeAllowed(): int
public SolrQuery::removeExpandFilterQuery(string $fq): SolrQuery
public SolrQuery::removeExpandSortField(string $field): SolrQuery
public SolrQuery::removeFacetDateField(string $field): SolrQuery
public SolrQuery::removeFacetDateOther(string $value, string $field_override = ?): SolrQuery
public SolrQuery::removeFacetField(string $field): SolrQuery
public SolrQuery::removeFacetQuery(string $value): SolrQuery
public SolrQuery::removeField(string $field): SolrQuery
public SolrQuery::removeFilterQuery(string $fq): SolrQuery
public SolrQuery::removeHighlightField(string $field): SolrQuery
public SolrQuery::removeMltField(string $field): SolrQuery
public SolrQuery::removeMltQueryField(string $queryField): SolrQuery
public SolrQuery::removeSortField(string $field): SolrQuery
public SolrQuery::removeStatsFacet(string $value): SolrQuery
public SolrQuery::removeStatsField(string $field): SolrQuery
public SolrQuery::setEchoHandler(bool $flag): SolrQuery
public SolrQuery::setEchoParams(string $type): SolrQuery
public SolrQuery::setExpand(bool $value): SolrQuery
public SolrQuery::setExpandQuery(string $q): SolrQuery
public SolrQuery::setExpandRows(int $value): SolrQuery
public SolrQuery::setExplainOther(string $query): SolrQuery
public SolrQuery::setFacet(bool $flag): SolrQuery
public SolrQuery::setFacetDateEnd(string $value, string $field_override = ?): SolrQuery
public SolrQuery::setFacetDateGap(string $value, string $field_override = ?): SolrQuery
public SolrQuery::setFacetDateHardEnd(bool $value, string $field_override = ?): SolrQuery
public SolrQuery::setFacetDateStart(string $value, string $field_override = ?): SolrQuery
public SolrQuery::setFacetEnumCacheMinDefaultFrequency(int $frequency, string $field_override = ?): SolrQuery
public SolrQuery::setFacetLimit(int $limit, string $field_override = ?): SolrQuery
public SolrQuery::setFacetMethod(string $method, string $field_override = ?): SolrQuery
public SolrQuery::setFacetMinCount(int $mincount, string $field_override = ?): SolrQuery
public SolrQuery::setFacetMissing(bool $flag, string $field_override = ?): SolrQuery
public SolrQuery::setFacetOffset(int $offset, string $field_override = ?): SolrQuery
public SolrQuery::setFacetPrefix(string $prefix, string $field_override = ?): SolrQuery
public SolrQuery::setFacetSort(int $facetSort, string $field_override = ?): SolrQuery
public SolrQuery::setGroup(bool $value): SolrQuery
public SolrQuery::setGroupCachePercent(int $percent): SolrQuery
public SolrQuery::setGroupFacet(bool $value): SolrQuery
public SolrQuery::setGroupFormat(string $value): SolrQuery
public SolrQuery::setGroupLimit(int $value): SolrQuery
public SolrQuery::setGroupMain(string $value): SolrQuery
public SolrQuery::setGroupNGroups(bool $value): SolrQuery
public SolrQuery::setGroupOffset(int $value): SolrQuery
public SolrQuery::setGroupTruncate(bool $value): SolrQuery
public SolrQuery::setHighlight(bool $flag): SolrQuery
public SolrQuery::setHighlightAlternateField(string $field, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightFormatter(string $formatter, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightFragmenter(string $fragmenter, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightFragsize(int $size, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightHighlightMultiTerm(bool $flag): SolrQuery
public SolrQuery::setHighlightMaxAlternateFieldLength(int $fieldLength, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightMaxAnalyzedChars(int $value): SolrQuery
public SolrQuery::setHighlightMergeContiguous(bool $flag, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightRegexMaxAnalyzedChars(int $maxAnalyzedChars): SolrQuery
public SolrQuery::setHighlightRegexPattern(string $value): SolrQuery
public SolrQuery::setHighlightRegexSlop(float $factor): SolrQuery
public SolrQuery::setHighlightRequireFieldMatch(bool $flag): SolrQuery
public SolrQuery::setHighlightSimplePost(string $simplePost, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightSimplePre(string $simplePre, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightSnippets(int $value, string $field_override = ?): SolrQuery
public SolrQuery::setHighlightUsePhraseHighlighter(bool $flag): SolrQuery
public SolrQuery::setMlt(bool $flag): SolrQuery
public SolrQuery::setMltBoost(bool $flag): SolrQuery
public SolrQuery::setMltCount(int $count): SolrQuery
public SolrQuery::setMltMaxNumQueryTerms(int $value): SolrQuery
public SolrQuery::setMltMaxNumTokens(int $value): SolrQuery
public SolrQuery::setMltMaxWordLength(int $maxWordLength): SolrQuery
public SolrQuery::setMltMinDocFrequency(int $minDocFrequency): SolrQuery
public SolrQuery::setMltMinTermFrequency(int $minTermFrequency): SolrQuery
public SolrQuery::setMltMinWordLength(int $minWordLength): SolrQuery
public SolrQuery::setOmitHeader(bool $flag): SolrQuery
public SolrQuery::setQuery(string $query): SolrQuery
public SolrQuery::setRows(int $rows): SolrQuery
public SolrQuery::setShowDebugInfo(bool $flag): SolrQuery
public SolrQuery::setStart(int $start): SolrQuery
public SolrQuery::setStats(bool $flag): SolrQuery
public SolrQuery::setTerms(bool $flag): SolrQuery
public SolrQuery::setTermsField(string $fieldname): SolrQuery
public SolrQuery::setTermsIncludeLowerBound(bool $flag): SolrQuery
public SolrQuery::setTermsIncludeUpperBound(bool $flag): SolrQuery
public SolrQuery::setTermsLimit(int $limit): SolrQuery
public SolrQuery::setTermsLowerBound(string $lowerBound): SolrQuery
public SolrQuery::setTermsMaxCount(int $frequency): SolrQuery
public SolrQuery::setTermsMinCount(int $frequency): SolrQuery
public SolrQuery::setTermsPrefix(string $prefix): SolrQuery
public SolrQuery::setTermsReturnRaw(bool $flag): SolrQuery
public SolrQuery::setTermsSort(int $sortType): SolrQuery
public SolrQuery::setTermsUpperBound(string $upperBound): SolrQuery
public SolrQuery::setTimeAllowed(int $timeAllowed): SolrQuery
}

定義済み定数

SolrDisMaxQuery::ORDER_ASC

Used to specify that the sorting should be in acending order (Duplicated for easier migration)

SolrDisMaxQuery::ORDER_DESC

Used to specify that the sorting should be in descending order (Duplicated for easier migration)

SolrDisMaxQuery::FACET_SORT_INDEX

Used to specify that the facet should sort by index (Duplicated for easier migration)

SolrDisMaxQuery::FACET_SORT_COUNT

Used to specify that the facet should sort by count (Duplicated for easier migration)

SolrDisMaxQuery::TERMS_SORT_INDEX

Used in the TermsComponent (Duplicated for easier migration)

SolrDisMaxQuery::TERMS_SORT_COUNT

Used in the TermsComponent (Duplicated for easier migration)

目次

  • SolrDisMaxQuery::addBigramPhraseField — Adds a Phrase Bigram Field (pf2 parameter)
  • SolrDisMaxQuery::addBoostQuery — Adds a boost query field with value and optional boost (bq parameter)
  • SolrDisMaxQuery::addPhraseField — Adds a Phrase Field (pf parameter)
  • SolrDisMaxQuery::addQueryField — Add a query field with optional boost (qf parameter)
  • SolrDisMaxQuery::addTrigramPhraseField — Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::addUserField — Adds a field to User Fields Parameter (uf)
  • SolrDisMaxQuery::__construct — Class Constructor
  • SolrDisMaxQuery::removeBigramPhraseField — Removes phrase bigram field (pf2 parameter)
  • SolrDisMaxQuery::removeBoostQuery — Removes a boost query partial by field name (bq)
  • SolrDisMaxQuery::removePhraseField — Removes a Phrase Field (pf parameter)
  • SolrDisMaxQuery::removeQueryField — Removes a Query Field (qf parameter)
  • SolrDisMaxQuery::removeTrigramPhraseField — Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::removeUserField — Removes a field from The User Fields Parameter (uf)
  • SolrDisMaxQuery::setBigramPhraseFields — Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setBigramPhraseSlop — Sets Bigram Phrase Slop (ps2 parameter)
  • SolrDisMaxQuery::setBoostFunction — Sets a Boost Function (bf parameter)
  • SolrDisMaxQuery::setBoostQuery — Directly Sets Boost Query Parameter (bq)
  • SolrDisMaxQuery::setMinimumMatch — Set Minimum "Should" Match (mm)
  • SolrDisMaxQuery::setPhraseFields — Sets Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setPhraseSlop — Sets the default slop on phrase queries (ps parameter)
  • SolrDisMaxQuery::setQueryAlt — Set Query Alternate (q.alt parameter)
  • SolrDisMaxQuery::setQueryPhraseSlop — Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)
  • SolrDisMaxQuery::setTieBreaker — Sets Tie Breaker parameter (tie parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields — Directly Sets Trigram Phrase Fields (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop — Sets Trigram Phrase Slop (ps3 parameter)
  • SolrDisMaxQuery::setUserFields — Sets User Fields parameter (uf)
  • SolrDisMaxQuery::useDisMaxQueryParser — Switch QueryParser to be DisMax Query Parser
  • SolrDisMaxQuery::useEDisMaxQueryParser — Switch QueryParser to be EDisMax


Adds a Phrase Bigram Field (pf2 parameter)

  • ≪ SolrDisMaxQuery
  • SolrDisMaxQuery::addBoostQuery ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a Phrase Bigram Field (pf2 parameter)

SolrDisMaxQuery::addBigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addBigramPhraseField — Adds a Phrase Bigram Field (pf2 parameter)

説明

public SolrDisMaxQuery::addBigramPhraseField(string $field, string $boost, string $slop = ?): SolrDisMaxQuery

Adds a Phrase Bigram Field (pf2 parameter) output format: field~slop^boost OR field^boost Slop is optional

パラメータ

field

boost

slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addBigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
->addBigramPhraseField('cat', 2, 5.1)
->addBigramPhraseField('feature', 4.5)
;
echo $dismaxQuery;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf2=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::removeBigramPhraseField() - Removes phrase bigram field (pf2 parameter)
  • SolrDisMaxQuery::setBigramPhraseFields() - Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setBigramPhraseSlop() - Sets Bigram Phrase Slop (ps2 parameter)


Adds a boost query field with value and optional boost (bq parameter)

  • ≪ SolrDisMaxQuery::addBigramPhraseField
  • SolrDisMaxQuery::addPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a boost query field with value and optional boost (bq parameter)

SolrDisMaxQuery::addBoostQuery

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addBoostQuery — Adds a boost query field with value and optional boost (bq parameter)

説明

public SolrDisMaxQuery::addBoostQuery(string $field, string $value, string $boost = ?): SolrDisMaxQuery

Adds a Boost Query field with value [and boost] (bq parameter)

パラメータ

field

value

boost

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addBoostQuery() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
->addBoostQuery('cat', 'clothing', 2)
->addBoostQuery('cat', 'electronics', 5.1)
;
echo $dismaxQuery.PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bq=cat:clothing^2 cat:electronics^5.1

参考

  • SolrDisMaxQuery::removeBoostQuery() - Removes a boost query partial by field name (bq)
  • SolrDisMaxQuery::setBoostQuery() - Directly Sets Boost Query Parameter (bq)


Adds a Phrase Field (pf parameter)

  • ≪ SolrDisMaxQuery::addBoostQuery
  • SolrDisMaxQuery::addQueryField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a Phrase Field (pf parameter)

SolrDisMaxQuery::addPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addPhraseField — Adds a Phrase Field (pf parameter)

説明

public SolrDisMaxQuery::addPhraseField(string $field, string $boost, string $slop = ?): SolrDisMaxQuery

Adds a Phrase Field (pf parameter)

パラメータ

field

field name

boost

slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addPhraseField() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
->addPhraseField('cat', 3, 1)
->addPhraseField('third', 4, 2)
->addPhraseField('source', 55)
;
echo $dismaxQuery;
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf=cat~1^3 third~2^4 source^55

参考

  • SolrDisMaxQuery::removePhraseField() - Removes a Phrase Field (pf parameter)
  • SolrDisMaxQuery::setPhraseFields() - Sets Phrase Fields and their boosts (and slops) using pf2 parameter


Add a query field with optional boost (qf parameter)

  • ≪ SolrDisMaxQuery::addPhraseField
  • SolrDisMaxQuery::addTrigramPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Add a query field with optional boost (qf parameter)

SolrDisMaxQuery::addQueryField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addQueryField — Add a query field with optional boost (qf parameter)

説明

public SolrDisMaxQuery::addQueryField(string $field, string $boost = ?): SolrDisMaxQuery

Add a query field with optional boost (qf parameter)

パラメータ

field

field name

boost

Boost value. Boosts documents with matching terms.

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addQueryField() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
->addQueryField("location", 4)
->addQueryField("price")
->addQueryField("sku")
->addQueryField("title",3.4)
;
echo $dismaxQuery;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&qf=location^4 price sku title^3.4

参考

  • SolrDisMaxQuery::removeQueryField() - Removes a Query Field (qf parameter)


Adds a Trigram Phrase Field (pf3 parameter)

  • ≪ SolrDisMaxQuery::addQueryField
  • SolrDisMaxQuery::addUserField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a Trigram Phrase Field (pf3 parameter)

SolrDisMaxQuery::addTrigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addTrigramPhraseField — Adds a Trigram Phrase Field (pf3 parameter)

説明

public SolrDisMaxQuery::addTrigramPhraseField(string $field, string $boost, string $slop = ?): SolrDisMaxQuery

Adds a Trigram Phrase Field (pf3 parameter)

パラメータ

field

Field Name

boost

Field Boost

slop

Field Slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addTrigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addTrigramPhraseField('cat', 2, 5.1)
->addTrigramPhraseField('feature', 4.5)
;
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=%s&pf3=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::removeTrigramPhraseField() - Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop() - Sets Trigram Phrase Slop (ps3 parameter)


Adds a field to User Fields Parameter (uf)

  • ≪ SolrDisMaxQuery::addTrigramPhraseField
  • SolrDisMaxQuery::__construct ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Adds a field to User Fields Parameter (uf)

SolrDisMaxQuery::addUserField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::addUserField — Adds a field to User Fields Parameter (uf)

説明

public SolrDisMaxQuery::addUserField(string $field): SolrDisMaxQuery

Adds a field to The User Fields Parameter (uf)

パラメータ

field

Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::addUserField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addUserField('cat')
->addUserField('text')
->addUserField('*_dt');

echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&uf=cat text *_dt

参考

  • SolrDisMaxQuery::removeUserField() - Removes a field from The User Fields Parameter (uf)
  • SolrDisMaxQuery::setUserFields() - Sets User Fields parameter (uf)


Class Constructor

  • ≪ SolrDisMaxQuery::addUserField
  • SolrDisMaxQuery::removeBigramPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Class Constructor

SolrDisMaxQuery::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::__construct — Class Constructor

説明

public SolrDisMaxQuery::__construct(string $q = ?)

Class constructor initializes the object and sets the q parameter if passed

パラメータ

q

Search Query (q parameter)

戻り値

エラー / 例外

Emits SolrIllegalArgumentException in case of an invalid parameter was passed.

例

例1 SolrDisMaxQuery::__construct() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
echo $dismaxQuery;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax


Removes phrase bigram field (pf2 parameter)

  • ≪ SolrDisMaxQuery::__construct
  • SolrDisMaxQuery::removeBoostQuery ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes phrase bigram field (pf2 parameter)

SolrDisMaxQuery::removeBigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeBigramPhraseField — Removes phrase bigram field (pf2 parameter)

説明

public SolrDisMaxQuery::removeBigramPhraseField(string $field): SolrDisMaxQuery

Removes a Bigram Phrase Field (pf2 parameter) that was previously added using SolrDisMaxQuery::addBigramPhraseField()

パラメータ

field

The Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeBigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
->addBigramPhraseField('cat', 2, 5.1)
->addBigramPhraseField('feature', 4.5)
;
echo $dismaxQuery.PHP_EOL;

// remove cat from pf2
$dismaxQuery
->removeBigramPhraseField('cat');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf2=cat~5.1^2 feature^4.5
q=lucene&defType=edismax&pf2=feature^4.5

参考

  • SolrDisMaxQuery::addBigramPhraseField() - Adds a Phrase Bigram Field (pf2 parameter)
  • SolrDisMaxQuery::setBigramPhraseFields() - Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
  • SolrDisMaxQuery::setBigramPhraseSlop() - Sets Bigram Phrase Slop (ps2 parameter)


Removes a boost query partial by field name (bq)

  • ≪ SolrDisMaxQuery::removeBigramPhraseField
  • SolrDisMaxQuery::removePhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a boost query partial by field name (bq)

SolrDisMaxQuery::removeBoostQuery

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeBoostQuery — Removes a boost query partial by field name (bq)

説明

public SolrDisMaxQuery::removeBoostQuery(string $field): SolrDisMaxQuery

Removes a boost query partial from the existing query, only if SolrDisMaxQuery::addBoostQuery() was used.

パラメータ

field

Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeBoostQuery() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery
->addBoostQuery('cat', 'electronics', 5.1)
->addBoostQuery('cat', 'hard drive')
;
echo $dismaxQuery.PHP_EOL;
// now remove a query part with field 'cat'
$dismaxQuery
->removeBoostQuery('cat');
echo $dismaxQuery . PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bq=cat:electronics^5.1 cat:hard drive
q=lucene&defType=edismax&bq=cat:hard drive

参考

  • SolrDisMaxQuery::addBoostQuery() - Adds a boost query field with value and optional boost (bq parameter)
  • SolrDisMaxQuery::setBoostQuery() - Directly Sets Boost Query Parameter (bq)


Removes a Phrase Field (pf parameter)

  • ≪ SolrDisMaxQuery::removeBoostQuery
  • SolrDisMaxQuery::removeQueryField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a Phrase Field (pf parameter)

SolrDisMaxQuery::removePhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removePhraseField — Removes a Phrase Field (pf parameter)

説明

public SolrDisMaxQuery::removePhraseField(string $field): SolrDisMaxQuery

Removes a Phrase Field (pf parameter) that was previously added using SolrDisMaxQuery::addPhraseField

パラメータ

field

Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removePhraseField() example

<?php
$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addPhraseField('first', 3, 1)
->addPhraseField('second', 4, 1)
->addPhraseField('cat', 55);
echo $dismaxQuery . PHP_EOL;
echo $dismaxQuery->removePhraseField('second');
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf=first~1^3 second~1^4 cat^55
q=lucene&defType=edismax&pf=first~1^3 cat^55

参考

  • SolrDisMaxQuery::addPhraseField() - Adds a Phrase Field (pf parameter)
  • SolrDisMaxQuery::setPhraseFields() - Sets Phrase Fields and their boosts (and slops) using pf2 parameter


Removes a Query Field (qf parameter)

  • ≪ SolrDisMaxQuery::removePhraseField
  • SolrDisMaxQuery::removeTrigramPhraseField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a Query Field (qf parameter)

SolrDisMaxQuery::removeQueryField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeQueryField — Removes a Query Field (qf parameter)

説明

public SolrDisMaxQuery::removeQueryField(string $field): SolrDisMaxQuery

Removes a Query Field (qf parameter) from the field list added by SolrDisMaxQuery::addQueryField()

qf: When building DisjunctionMaxQueries from the user's query it specifies the fields to search in, and boosts for those fields.

パラメータ

field

Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeQueryField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addQueryField('first', 3)
->addQueryField('second', 0.2)
->addQueryField('cat');
echo $dismaxQuery . PHP_EOL;
// remove field 'second'
echo $dismaxQuery->removeQueryField('second');
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&qf=first^3 second^0.2 cat
q=lucene&defType=edismax&qf=first^3 cat

参考

  • SolrDisMaxQuery::addQueryField() - Add a query field with optional boost (qf parameter)


Removes a Trigram Phrase Field (pf3 parameter)

  • ≪ SolrDisMaxQuery::removeQueryField
  • SolrDisMaxQuery::removeUserField ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a Trigram Phrase Field (pf3 parameter)

SolrDisMaxQuery::removeTrigramPhraseField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeTrigramPhraseField — Removes a Trigram Phrase Field (pf3 parameter)

説明

public SolrDisMaxQuery::removeTrigramPhraseField(string $field): SolrDisMaxQuery

Removes a Trigram Phrase Field (pf3 parameter)

パラメータ

field

Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeTrigramPhraseField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addTrigramPhraseField('cat', 2, 5.1)
->addTrigramPhraseField('feature', 4.5)
;
echo $dismaxQuery.PHP_EOL;
// reverse
$dismaxQuery
->removeTrigramPhraseField('cat');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=%s&pf3=cat~5.1^2 feature^4.5
q=lucene&defType=%s&pf3=feature^4.5

参考

  • SolrDisMaxQuery::addTrigramPhraseField() - Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop() - Sets Trigram Phrase Slop (ps3 parameter)


Removes a field from The User Fields Parameter (uf)

  • ≪ SolrDisMaxQuery::removeTrigramPhraseField
  • SolrDisMaxQuery::setBigramPhraseFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Removes a field from The User Fields Parameter (uf)

SolrDisMaxQuery::removeUserField

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::removeUserField — Removes a field from The User Fields Parameter (uf)

説明

public SolrDisMaxQuery::removeUserField(string $field): SolrDisMaxQuery

Removes a field from The User Fields Parameter (uf)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

field

Field Name

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::removeUserField() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery
->addUserField('cat')
->addUserField('text')
->addUserField('*_dt')
;
echo $dismaxQuery.PHP_EOL;

// remove field named 'text'
$dismaxQuery
->removeUserField('text');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=%s&uf=cat text *_dt
q=lucene&defType=%s&uf=cat *_dt

参考

  • SolrDisMaxQuery::addUserField() - Adds a field to User Fields Parameter (uf)
  • SolrDisMaxQuery::setUserFields() - Sets User Fields parameter (uf)


Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter

  • ≪ SolrDisMaxQuery::removeUserField
  • SolrDisMaxQuery::setBigramPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter

SolrDisMaxQuery::setBigramPhraseFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBigramPhraseFields — Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter

説明

public SolrDisMaxQuery::setBigramPhraseFields(string $fields): SolrDisMaxQuery

Sets Bigram Phrase Fields (pf2) and their boosts (and slops)

パラメータ

fields

Fields boosts (slops)

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBigramPhraseFields() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery->setBigramPhraseFields("cat~5.1^2 feature^4.5");
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf2=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::setBigramPhraseSlop() - Sets Bigram Phrase Slop (ps2 parameter)
  • SolrDisMaxQuery::addBigramPhraseFields()
  • SolrDisMaxQuery::removeBigramPhraseField() - Removes phrase bigram field (pf2 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)


Sets Bigram Phrase Slop (ps2 parameter)

  • ≪ SolrDisMaxQuery::setBigramPhraseFields
  • SolrDisMaxQuery::setBoostFunction ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Bigram Phrase Slop (ps2 parameter)

SolrDisMaxQuery::setBigramPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBigramPhraseSlop — Sets Bigram Phrase Slop (ps2 parameter)

説明

public SolrDisMaxQuery::setBigramPhraseSlop(string $slop): SolrDisMaxQuery

Sets Bigram Phrase Slop (ps2 parameter). A default slop for Bigram phrase fields.

パラメータ

slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBigramPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');

$dismaxQuery->setBigramPhraseSlop(5);
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&ps2=5


Sets a Boost Function (bf parameter)

  • ≪ SolrDisMaxQuery::setBigramPhraseSlop
  • SolrDisMaxQuery::setBoostQuery ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets a Boost Function (bf parameter)

SolrDisMaxQuery::setBoostFunction

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBoostFunction — Sets a Boost Function (bf parameter)

説明

public SolrDisMaxQuery::setBoostFunction(string $function): SolrDisMaxQuery

Sets Boost Function (bf parameter).

Functions (with optional boosts) that will be included in the user's query to influence the score. Any function supported natively by Solr can be used, along with a boost value. e.g.:

recip(rord(myfield),1,2,3)^1.5

パラメータ

function

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBoostFunction() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');

$boostRecentDocsFunction = "recip(ms(NOW,mydatefield),3.16e-11,1,1)";
$dismaxQuery->setBoostFunction($boostRecentDocsFunction);

echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bf=recip(ms(NOW,mydatefield),3.16e-11,1,1)


Directly Sets Boost Query Parameter (bq)

  • ≪ SolrDisMaxQuery::setBoostFunction
  • SolrDisMaxQuery::setMinimumMatch ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Directly Sets Boost Query Parameter (bq)

SolrDisMaxQuery::setBoostQuery

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setBoostQuery — Directly Sets Boost Query Parameter (bq)

説明

public SolrDisMaxQuery::setBoostQuery(string $q): SolrDisMaxQuery

Sets Boost Query Parameter (bq)

パラメータ

q

query

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setBoostQuery() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");

$dismaxQuery->setBoostQuery('cat:electronics manu:local^2');
echo $dismaxQuery.PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&bq=cat:electronics manu:local^2

参考

  • SolrDisMaxQuery::addBoostQuery() - Adds a boost query field with value and optional boost (bq parameter)
  • SolrDisMaxQuery::removeBoostQuery() - Removes a boost query partial by field name (bq)


Set Minimum "Should" Match (mm)

  • ≪ SolrDisMaxQuery::setBoostQuery
  • SolrDisMaxQuery::setPhraseFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Set Minimum "Should" Match (mm)

SolrDisMaxQuery::setMinimumMatch

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setMinimumMatch — Set Minimum "Should" Match (mm)

説明

public SolrDisMaxQuery::setMinimumMatch(string $value): SolrDisMaxQuery

Set Minimum "Should" Match parameter (mm). If the default query operator is AND then mm=100%, if the default query operator (q.op) is OR, then mm=0%.

パラメータ

value

Minimum match value/expression

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setMinimumMatch() example

<?php

$dismaxQuery = new SolrDisMaxQuery("lucene");
// 75% of the query clauses must match
$dismaxQuery->setMinimumMatch("75%");
echo $dismaxQuery . PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax&mm=75%


Sets Phrase Fields and their boosts (and slops) using pf2 parameter

  • ≪ SolrDisMaxQuery::setMinimumMatch
  • SolrDisMaxQuery::setPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Phrase Fields and their boosts (and slops) using pf2 parameter

SolrDisMaxQuery::setPhraseFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setPhraseFields — Sets Phrase Fields and their boosts (and slops) using pf2 parameter

説明

public SolrDisMaxQuery::setPhraseFields(string $fields): SolrDisMaxQuery

Sets Phrase Fields (pf) and their boosts (and slops)

パラメータ

fields

Fields, boosts [, slops]

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setPhraseFields() example

<?php
$dismaxQuery = new SolrDisMaxQuery("lucene");
$dismaxQuery->setPhraseFields("cat~5.1^2 feature^4.5");
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&pf=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::addPhraseFields()
  • SolrDisMaxQuery::removePhraseField() - Removes a Phrase Field (pf parameter)


Sets the default slop on phrase queries (ps parameter)

  • ≪ SolrDisMaxQuery::setPhraseFields
  • SolrDisMaxQuery::setQueryAlt ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets the default slop on phrase queries (ps parameter)

SolrDisMaxQuery::setPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setPhraseSlop — Sets the default slop on phrase queries (ps parameter)

説明

public SolrDisMaxQuery::setPhraseSlop(string $slop): SolrDisMaxQuery

Sets the default amount of slop on phrase queries built with "pf", "pf2" and/or "pf3" fields (affects boosting). "ps" parameter

パラメータ

slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');

$dismaxQuery->setPhraseSlop(4);
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax&ps=4


Set Query Alternate (q.alt parameter)

  • ≪ SolrDisMaxQuery::setPhraseSlop
  • SolrDisMaxQuery::setQueryPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Set Query Alternate (q.alt parameter)

SolrDisMaxQuery::setQueryAlt

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setQueryAlt — Set Query Alternate (q.alt parameter)

説明

public SolrDisMaxQuery::setQueryAlt(string $q): SolrDisMaxQuery

Set Query Alternate (q.alt parameter)

When the main q parameter is not specified or is blank. The q.alt parameter is used

パラメータ

q

Query String

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setQueryAlt() example

<?php

$dismaxQuery = new DisMaxQuery();
$dismaxQuery->setQueryAlt('*:*');

?>

上の例の出力は、 たとえば以下のようになります。

defType=edismax&q.alt=*:*&q=


Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)

  • ≪ SolrDisMaxQuery::setQueryAlt
  • SolrDisMaxQuery::setTieBreaker ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)

SolrDisMaxQuery::setQueryPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setQueryPhraseSlop — Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)

説明

public SolrDisMaxQuery::setQueryPhraseSlop(string $slop): SolrDisMaxQuery

The Query Phrase Slop is the amount of slop permitted on phrase queries explicitly included in the user's query string with the qf parameter.

slop refers to the number of positions one token needs to be moved in relation to another token in order to match a phrase specified in a query.

パラメータ

slop

Amount of slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setQueryPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->setQueryPhraseSlop(3);
echo $dismaxQuery;
?>

上の例の出力は、 たとえば以下のようになります。

defType=edismax&qs=3


Sets Tie Breaker parameter (tie parameter)

  • ≪ SolrDisMaxQuery::setQueryPhraseSlop
  • SolrDisMaxQuery::setTrigramPhraseFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Tie Breaker parameter (tie parameter)

SolrDisMaxQuery::setTieBreaker

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setTieBreaker — Sets Tie Breaker parameter (tie parameter)

説明

public SolrDisMaxQuery::setTieBreaker(string $tieBreaker): SolrDisMaxQuery

Sets Tie Breaker parameter (tie parameter)

パラメータ

tieBreaker

The tie parameter specifies a float value (which should be something much less than 1) to use as tiebreaker in DisMax queries.

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setTieBreaker() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->setTieBreaker(0.1);

echo $dismaxQuery;

?>

上の例の出力は以下となります。

defType=edismax&tie=0.1


Directly Sets Trigram Phrase Fields (pf3 parameter)

  • ≪ SolrDisMaxQuery::setTieBreaker
  • SolrDisMaxQuery::setTrigramPhraseSlop ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Directly Sets Trigram Phrase Fields (pf3 parameter)

SolrDisMaxQuery::setTrigramPhraseFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setTrigramPhraseFields — Directly Sets Trigram Phrase Fields (pf3 parameter)

説明

public SolrDisMaxQuery::setTrigramPhraseFields(string $fields): SolrDisMaxQuery

Directly Sets Trigram Phrase Fields (pf3 parameter)

パラメータ

fields

Trigram Phrase Fields

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setTrigramPhraseFields() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery->setTrigramPhraseFields('cat~5.1^2 feature^4.5');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は以下となります。

q=lucene&defType=edismax&pf3=cat~5.1^2 feature^4.5

参考

  • SolrDisMaxQuery::addTrigramPhraseField() - Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::removeTrigramPhraseField() - Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseSlop() - Sets Trigram Phrase Slop (ps3 parameter)


Sets Trigram Phrase Slop (ps3 parameter)

  • ≪ SolrDisMaxQuery::setTrigramPhraseFields
  • SolrDisMaxQuery::setUserFields ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets Trigram Phrase Slop (ps3 parameter)

SolrDisMaxQuery::setTrigramPhraseSlop

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setTrigramPhraseSlop — Sets Trigram Phrase Slop (ps3 parameter)

説明

public SolrDisMaxQuery::setTrigramPhraseSlop(string $slop): SolrDisMaxQuery

Sets Trigram Phrase Slop (ps3 parameter)

パラメータ

slop

Phrase slop

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setTrigramPhraseSlop() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery->setTrigramPhraseSlop(2);
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&ps3=2

参考

  • SolrDisMaxQuery::addTrigramPhraseField() - Adds a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::removeTrigramPhraseField() - Removes a Trigram Phrase Field (pf3 parameter)
  • SolrDisMaxQuery::setTrigramPhraseFields() - Directly Sets Trigram Phrase Fields (pf3 parameter)


Sets User Fields parameter (uf)

  • ≪ SolrDisMaxQuery::setTrigramPhraseSlop
  • SolrDisMaxQuery::useDisMaxQueryParser ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Sets User Fields parameter (uf)

SolrDisMaxQuery::setUserFields

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::setUserFields — Sets User Fields parameter (uf)

説明

public SolrDisMaxQuery::setUserFields(string $fields): SolrDisMaxQuery

Sets User Fields parameter (uf)

User Fields: Specifies which schema fields the end user shall be allowed to query.

パラメータ

fields

Fields names separated by space

This parameter supports wildcards.

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::setUserFields() example

<?php

$dismaxQuery = new SolrDisMaxQuery('lucene');
$dismaxQuery->setUserFields('field1 field2 *_txt');
echo $dismaxQuery.PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

q=lucene&defType=edismax&uf=field1 field2 *_txt

参考

  • SolrDisMaxQuery::addUserField() - Adds a field to User Fields Parameter (uf)
  • SolrDisMaxQuery::removeUserField() - Removes a field from The User Fields Parameter (uf)


Switch QueryParser to be DisMax Query Parser

  • ≪ SolrDisMaxQuery::setUserFields
  • SolrDisMaxQuery::useEDisMaxQueryParser ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Switch QueryParser to be DisMax Query Parser

SolrDisMaxQuery::useDisMaxQueryParser

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::useDisMaxQueryParser — Switch QueryParser to be DisMax Query Parser

説明

public SolrDisMaxQuery::useDisMaxQueryParser(): SolrDisMaxQuery

Switch QueryParser to be DisMax Query Parser

パラメータ

この関数にはパラメータはありません。

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::useDisMaxQueryParser() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->useDisMaxQueryParser();
echo $dismaxQuery;
?>

上の例の出力は、 たとえば以下のようになります。

defType=dismax

参考

  • SolrDisMaxQuery::useDisMaxQueryParser()


Switch QueryParser to be EDisMax

  • ≪ SolrDisMaxQuery::useDisMaxQueryParser
  • SolrCollapseFunction ≫
  • PHP Manual
  • SolrDisMaxQuery
  • Switch QueryParser to be EDisMax

SolrDisMaxQuery::useEDisMaxQueryParser

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SolrDisMaxQuery::useEDisMaxQueryParser — Switch QueryParser to be EDisMax

説明

public SolrDisMaxQuery::useEDisMaxQueryParser(): SolrDisMaxQuery

Switch QueryParser to be EDisMax. By default the query builder uses edismax, if it was switched using SolrDisMaxQuery::useDisMaxQueryParser(), it can be switched back using this method.

パラメータ

この関数にはパラメータはありません。

戻り値

SolrDisMaxQuery

例

例1 SolrDisMaxQuery::useEDisMaxQueryParser() example

<?php

$dismaxQuery = new SolrDisMaxQuery();
$dismaxQuery->useEDisMaxQueryParser();
echo $dismaxQuery;

?>

上の例の出力は、 たとえば以下のようになります。

defType=edismax


The SolrCollapseFunction class

(PECL solr >= 2.2.0)

はじめに

クラス概要

class SolrCollapseFunction {
/* 定数 */
const string NULLPOLICY_IGNORE = ignore;
const string NULLPOLICY_EXPAND = expand;
const string NULLPOLICY_COLLAPSE = collapse;
/* メソッド */
public __construct(string $field = ?)
public getField(): string
public getHint(): string
public getMax(): string
public getMin(): string
public getNullPolicy(): string
public getSize(): int
public setField(string $fieldName): SolrCollapseFunction
public setHint(string $hint): SolrCollapseFunction
public setMax(string $max): SolrCollapseFunction
public setMin(string $min): SolrCollapseFunction
public setNullPolicy(string $nullPolicy): SolrCollapseFunction
public setSize(int $size): SolrCollapseFunction
public __toString(): string
}

定義済み定数

SolrCollapseFunction::NULLPOLICY_IGNORE

SolrCollapseFunction::NULLPOLICY_EXPAND

SolrCollapseFunction::NULLPOLICY_COLLAPSE

目次

  • SolrCollapseFunction::__construct — Constructor
  • SolrCollapseFunction::getField — Returns the field that is being collapsed on
  • SolrCollapseFunction::getHint — Returns collapse hint
  • SolrCollapseFunction::getMax — Returns max parameter
  • SolrCollapseFunction::getMin — Returns min parameter
  • SolrCollapseFunction::getNullPolicy — Returns null policy
  • SolrCollapseFunction::getSize — Returns size parameter
  • SolrCollapseFunction::setField — Sets the field to collapse on
  • SolrCollapseFunction::setHint — Sets collapse hint
  • SolrCollapseFunction::setMax — Selects the group heads by the max value of a numeric field or function query
  • SolrCollapseFunction::setMin — Sets the initial size of the collapse data structures when collapsing on a numeric field only
  • SolrCollapseFunction::setNullPolicy — Sets the NULL Policy
  • SolrCollapseFunction::setSize — Sets the initial size of the collapse data structures when collapsing on a numeric field only
  • SolrCollapseFunction::__toString — Returns a string representing the constructed collapse function


Constructor

  • ≪ SolrCollapseFunction
  • SolrCollapseFunction::getField ≫
  • PHP Manual
  • SolrCollapseFunction
  • Constructor

SolrCollapseFunction::__construct

(PECL solr >= 2.2.0)

SolrCollapseFunction::__construct — Constructor

説明

public SolrCollapseFunction::__construct(string $field = ?)

Collapse Function constructor

パラメータ

field

The field name to collapse on.

In order to collapse a result. The field type must be a single valued String, Int or Float.

例

例1 SolrCollapseFunction::__construct() example

<?php

include "bootstrap.php";

$options = array
(
'hostname' => SOLR_SERVER_HOSTNAME,
'login' => SOLR_SERVER_USERNAME,
'password' => SOLR_SERVER_PASSWORD,
'port' => SOLR_SERVER_PORT,
'path' => SOLR_SERVER_PATH
);

$client = new SolrClient($options);

$query = new SolrQuery('*:*');

$func = new SolrCollapseFunction('field_name');

$func->setMax('sum(cscore(),field(some_other_field))');
$func->setSize(100);
$func->setNullPolicy(SolrCollapseFunction::NULLPOLICY_EXPAND);

$query->collapse($func);

$queryResponse = $client->query($query);

$response = $queryResponse->getResponse();

print_r($response);

?>

参考

  • SolrQuery::collapse() - Collapses the result set to a single document per group


Returns the field that is being collapsed on

  • ≪ SolrCollapseFunction::__construct
  • SolrCollapseFunction::getHint ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns the field that is being collapsed on

SolrCollapseFunction::getField

(PECL solr >= 2.2.0)

SolrCollapseFunction::getField — Returns the field that is being collapsed on

説明

public SolrCollapseFunction::getField(): string

Returns the field that is being collapsed on.

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrCollapseFunction::setField() - Sets the field to collapse on


Returns collapse hint

  • ≪ SolrCollapseFunction::getField
  • SolrCollapseFunction::getMax ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns collapse hint

SolrCollapseFunction::getHint

(PECL solr >= 2.2.0)

SolrCollapseFunction::getHint — Returns collapse hint

説明

public SolrCollapseFunction::getHint(): string

Returns collapse hint

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrCollapseFunction::setHint() - Sets collapse hint


Returns max parameter

  • ≪ SolrCollapseFunction::getHint
  • SolrCollapseFunction::getMin ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns max parameter

SolrCollapseFunction::getMax

(PECL solr >= 2.2.0)

SolrCollapseFunction::getMax — Returns max parameter

説明

public SolrCollapseFunction::getMax(): string

Returns max parameter

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrCollapseFunction::setMax() - Selects the group heads by the max value of a numeric field or function query


Returns min parameter

  • ≪ SolrCollapseFunction::getMax
  • SolrCollapseFunction::getNullPolicy ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns min parameter

SolrCollapseFunction::getMin

(PECL solr >= 2.2.0)

SolrCollapseFunction::getMin — Returns min parameter

説明

public SolrCollapseFunction::getMin(): string

Returns min parameter

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrCollapseFunction::setMin() - Sets the initial size of the collapse data structures when collapsing on a numeric field only


Returns null policy

  • ≪ SolrCollapseFunction::getMin
  • SolrCollapseFunction::getSize ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns null policy

SolrCollapseFunction::getNullPolicy

(PECL solr >= 2.2.0)

SolrCollapseFunction::getNullPolicy — Returns null policy

説明

public SolrCollapseFunction::getNullPolicy(): string

Returns null policy used or null

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrCollapseFunction::setNullPolicy() - Sets the NULL Policy


Returns size parameter

  • ≪ SolrCollapseFunction::getNullPolicy
  • SolrCollapseFunction::setField ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns size parameter

SolrCollapseFunction::getSize

(PECL solr >= 2.2.0)

SolrCollapseFunction::getSize — Returns size parameter

説明

public SolrCollapseFunction::getSize(): int

Gets the initial size of the collapse data structures when collapsing on a numeric field only

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • SolrCollapseFunction::setSize() - Sets the initial size of the collapse data structures when collapsing on a numeric field only


Sets the field to collapse on

  • ≪ SolrCollapseFunction::getSize
  • SolrCollapseFunction::setHint ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the field to collapse on

SolrCollapseFunction::setField

(PECL solr >= 2.2.0)

SolrCollapseFunction::setField — Sets the field to collapse on

説明

public SolrCollapseFunction::setField(string $fieldName): SolrCollapseFunction

The field name to collapse on. In order to collapse a result. The field type must be a single valued String, Int or Float.

パラメータ

fieldName

戻り値

SolrCollapseFunction


Sets collapse hint

  • ≪ SolrCollapseFunction::setField
  • SolrCollapseFunction::setMax ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets collapse hint

SolrCollapseFunction::setHint

(PECL solr >= 2.2.0)

SolrCollapseFunction::setHint — Sets collapse hint

説明

public SolrCollapseFunction::setHint(string $hint): SolrCollapseFunction

Sets collapse hint

パラメータ

hint

Currently there is only one hint available "top_fc", which stands for top level FieldCache

戻り値

SolrCollapseFunction

例

例1 SolrCollapseFunction::setHint() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...


Selects the group heads by the max value of a numeric field or function query

  • ≪ SolrCollapseFunction::setHint
  • SolrCollapseFunction::setMin ≫
  • PHP Manual
  • SolrCollapseFunction
  • Selects the group heads by the max value of a numeric field or function query

SolrCollapseFunction::setMax

(PECL solr >= 2.2.0)

SolrCollapseFunction::setMax — Selects the group heads by the max value of a numeric field or function query

説明

public SolrCollapseFunction::setMax(string $max): SolrCollapseFunction

Selects the group heads by the max value of a numeric field or function query.

パラメータ

max

戻り値

SolrCollapseFunction

例

例1 SolrCollapseFunction::setMax() example

<?php

$func = new SolrCollapseFunction('field_name');

$func->setMax('sum(cscore(),field(some_field))');

$query = new SolrQuery('*:*');

$query->collapse($func);

?>


Sets the initial size of the collapse data structures when collapsing on a numeric field only

  • ≪ SolrCollapseFunction::setMax
  • SolrCollapseFunction::setNullPolicy ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the initial size of the collapse data structures when collapsing on a numeric field only

SolrCollapseFunction::setMin

(PECL solr >= 2.2.0)

SolrCollapseFunction::setMin — Sets the initial size of the collapse data structures when collapsing on a numeric field only

説明

public SolrCollapseFunction::setMin(string $min): SolrCollapseFunction

Sets the initial size of the collapse data structures when collapsing on a numeric field only

パラメータ

min

戻り値

SolrCollapseFunction


Sets the NULL Policy

  • ≪ SolrCollapseFunction::setMin
  • SolrCollapseFunction::setSize ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the NULL Policy

SolrCollapseFunction::setNullPolicy

(PECL solr >= 2.2.0)

SolrCollapseFunction::setNullPolicy — Sets the NULL Policy

説明

public SolrCollapseFunction::setNullPolicy(string $nullPolicy): SolrCollapseFunction

Sets the NULL Policy. One of the 3 policies defined as class constants shall be passed. Accepts ignore, expand, or collapse policies.

パラメータ

nullPolicy

戻り値

SolrCollapseFunction


Sets the initial size of the collapse data structures when collapsing on a numeric field only

  • ≪ SolrCollapseFunction::setNullPolicy
  • SolrCollapseFunction::__toString ≫
  • PHP Manual
  • SolrCollapseFunction
  • Sets the initial size of the collapse data structures when collapsing on a numeric field only

SolrCollapseFunction::setSize

(PECL solr >= 2.2.0)

SolrCollapseFunction::setSize — Sets the initial size of the collapse data structures when collapsing on a numeric field only

説明

public SolrCollapseFunction::setSize(int $size): SolrCollapseFunction

Sets the initial size of the collapse data structures when collapsing on a numeric field only.

パラメータ

size

戻り値

SolrCollapseFunction


Returns a string representing the constructed collapse function

  • ≪ SolrCollapseFunction::setSize
  • SolrException ≫
  • PHP Manual
  • SolrCollapseFunction
  • Returns a string representing the constructed collapse function

SolrCollapseFunction::__toString

(PECL solr >= 2.2.0)

SolrCollapseFunction::__toString — Returns a string representing the constructed collapse function

説明

public SolrCollapseFunction::__toString(): string

Returns a string representing the constructed collapse function

パラメータ

この関数にはパラメータはありません。

戻り値


SolrException クラス

(PECL solr >= 0.9.2)

はじめに

Solr 拡張モジュールのクラスによってスローされる、全ての例外に対する基底クラスです。

クラス概要

class SolrException extends Exception {
/* プロパティ */
protected int $sourceline;
protected string $sourcefile;
protected string $zif_name;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public getInternalInfo(): array
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

sourceline

例外が生成された、カーネル空間の PHP ソースファイルの行

sourcefile

例外が生成された、カーネル空間の PHP ソースファイル

zif_name

例外が生成された、カーネル空間の関数

目次

  • SolrException::getInternalInfo — 例外がスローされた際の内部情報を返す


例外がスローされた際の内部情報を返す

  • ≪ SolrException
  • SolrClientException ≫
  • PHP Manual
  • SolrException
  • 例外がスローされた際の内部情報を返す

SolrException::getInternalInfo

(PECL solr >= 0.9.2)

SolrException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrException::getInternalInfo(): array

例外がスローされた際の内部情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがスローされた際の内部情報を含む配列を返します。拡張モジュールの開発者によるデバッグのためだけに使われます。


SolrClientException クラス

(PECL solr >= 0.9.2)

はじめに

クライアントからサーバーにリクエスト中にエラーがある際にスローされる例外。

クラス概要

class SolrClientException extends SolrException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
protected int $sourceline;
protected string $sourcefile;
protected string $zif_name;
/* メソッド */
public getInternalInfo(): array
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
public SolrException::getInternalInfo(): array
}

目次

  • SolrClientException::getInternalInfo — 例外がスローされた際の内部情報を返す


例外がスローされた際の内部情報を返す

  • ≪ SolrClientException
  • SolrServerException ≫
  • PHP Manual
  • SolrClientException
  • 例外がスローされた際の内部情報を返す

SolrClientException::getInternalInfo

(PECL solr >= 0.9.2)

SolrClientException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrClientException::getInternalInfo(): array

例外がスローされた際の内部情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがスローされた際の内部情報を含む配列を返します。拡張モジュールの開発者によるデバッグのためだけに使われます。


SolrServerException クラス

(PECL Solr >= 1.1.0, >=2.0.0)

はじめに

Solr サーバー自身によって生成されたエラーがあると、このオブジェクトがスローされます。

クラス概要

class SolrServerException extends SolrException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
protected int $sourceline;
protected string $sourcefile;
protected string $zif_name;
/* メソッド */
public getInternalInfo(): array
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
public SolrException::getInternalInfo(): array
}

目次

  • SolrServerException::getInternalInfo — 例外がスローされた際の内部情報を返す


例外がスローされた際の内部情報を返す

  • ≪ SolrServerException
  • SolrIllegalArgumentException ≫
  • PHP Manual
  • SolrServerException
  • 例外がスローされた際の内部情報を返す

SolrServerException::getInternalInfo

(PECL solr >= 1.1.0, >=2.0.0)

SolrServerException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrServerException::getInternalInfo(): array

例外がスローされた際の内部情報を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがスローされた際の内部情報を含む配列を返します。拡張モジュールの開発者によるデバッグのためだけに使われます。


SolrIllegalArgumentException クラス

(PECL solr >= 0.9.2)

はじめに

規則外の、または無効な引数がメソッドに渡されると、このオブジェクトがスローされます。

クラス概要

class SolrIllegalArgumentException extends SolrException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
protected int $sourceline;
protected string $sourcefile;
protected string $zif_name;
/* メソッド */
public getInternalInfo(): array
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
public SolrException::getInternalInfo(): array
}

目次

  • SolrIllegalArgumentException::getInternalInfo — 例外がスローされた際の内部情報を返す


例外がスローされた際の内部情報を返す

  • ≪ SolrIllegalArgumentException
  • SolrIllegalOperationException ≫
  • PHP Manual
  • SolrIllegalArgumentException
  • 例外がスローされた際の内部情報を返す

SolrIllegalArgumentException::getInternalInfo

(PECL solr >= 0.9.2)

SolrIllegalArgumentException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrIllegalArgumentException::getInternalInfo(): array

例外がスローされた際の内部情報を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがスローされた際の内部情報を含む配列を返します。拡張モジュールの開発者によるデバッグのためだけに使われます。


SolrIllegalOperationException クラス

(PECL solr >= 0.9.2)

はじめに

オブジェクトに対して規則外の、またはサポートされていない操作が実行されると、このオブジェクトがスローされます。

クラス概要

class SolrIllegalOperationException extends SolrException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
protected int $sourceline;
protected string $sourcefile;
protected string $zif_name;
/* メソッド */
public getInternalInfo(): array
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
public SolrException::getInternalInfo(): array
}

目次

  • SolrIllegalOperationException::getInternalInfo — 例外がスローされた際の内部情報を返す


例外がスローされた際の内部情報を返す

  • ≪ SolrIllegalOperationException
  • SolrMissingMandatoryParameterException ≫
  • PHP Manual
  • SolrIllegalOperationException
  • 例外がスローされた際の内部情報を返す

SolrIllegalOperationException::getInternalInfo

(PECL solr >= 0.9.2)

SolrIllegalOperationException::getInternalInfo — 例外がスローされた際の内部情報を返す

説明

public SolrIllegalOperationException::getInternalInfo(): array

例外がスローされた際の内部情報を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがスローされた際の内部情報を含む配列を返します。拡張モジュールの開発者によるデバッグのためだけに使われます。


The SolrMissingMandatoryParameterException class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

class SolrMissingMandatoryParameterException extends SolrException {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
protected int $sourceline;
protected string $sourcefile;
protected string $zif_name;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
public SolrException::getInternalInfo(): array
}


サーバー固有のモジュール

  • Apache
    • はじめに
    • インストール/設定
    • Apache 関数
  • FastCGI Process Manager(FPM)
    • はじめに
    • インストール/設定
    • オブザーバビリティ(可観測性)
    • FPM 関数


Apache

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • Apache 関数
    • apache_child_terminate — このリクエストの後にApacheプロセスを終了する
    • apache_get_modules — ロードされた Apache モジュールのリストを取得する
    • apache_get_version — Apache のバージョンを取得する
    • apache_getenv — Apache の subprocess_env 変数を取得する
    • apache_lookup_uri — リクエストの一部を指定したURIに対して行い、全ての情報を返す
    • apache_note — Apacheリクエスト記号(note)を取得/設定する
    • apache_request_headers — すべての HTTP リクエストヘッダを取得する
    • apache_response_headers — HTTPレスポンスヘッダを全て取得する
    • apache_setenv — Apacheサブプロセスの環境変数を設定する
    • getallheaders — 全てのHTTPリクエストヘッダを取得する
    • virtual — Apache サブリクエストを実行する


  • ≪ Apache
  • インストール/設定 ≫
  • PHP Manual
  • Apache
  • はじめに

はじめに

これらの関数は、Apacheモジュール版のPHPを実行している場合のみ利用可能です。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Apache
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


  • ≪ インストール/設定
  • 実行時設定 ≫
  • PHP Manual
  • インストール/設定
  • インストール手順

インストール手順

PHPのApacheへのインストール方法については、インストールの章を参照ください。


実行時設定

Apache PHPモジュールの動作は、php.ini の設定により影響を受けます。 php.ini の設定は、サーバーの設定ファイル内の php_flag の設定、 またはローカルなファイル .htaccess により上書きすることができます。

例1 .htaccess により、あるディレクトリの PHP によるパースを無効にする

php_flag engine off

Apache設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
engine | "1" | INI_ALL |
child_terminate | "0" | INI_ALL |
last_modified | "0" | INI_ALL |
xbithack | "0" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

設定ディレクティブの短い説明を以下に示します。

engine bool

PHP によるパースのオン/オフを切り替えます。 このディレクティブは、Apacheモジュール版のPHPでのみ有効です。 このディレクティブは、ディレクティブ毎または仮想サーバー毎にPHPに よるパースを有効または無効にしたいサイトで使用されます。 httpd.confファイルの適当な場所に engine offを置くことにより、PHPを有効また は無効にすることができます。

child_terminate bool

リクエストの終了時にPHPスクリプトが子プロセスの終了を指定するか どうかを指定します。 apache_child_terminate()も参照ください。

last_modified bool

PHPスクリプトの修正日をこのリクエストのLast-Modified:ヘッダとし て送信します。

xbithack bool

PHPがファイル終端を無視して実行ビットが設定されているファイルを パースするようにします。


Apache 関数

目次

  • apache_child_terminate — このリクエストの後にApacheプロセスを終了する
  • apache_get_modules — ロードされた Apache モジュールのリストを取得する
  • apache_get_version — Apache のバージョンを取得する
  • apache_getenv — Apache の subprocess_env 変数を取得する
  • apache_lookup_uri — リクエストの一部を指定したURIに対して行い、全ての情報を返す
  • apache_note — Apacheリクエスト記号(note)を取得/設定する
  • apache_request_headers — すべての HTTP リクエストヘッダを取得する
  • apache_response_headers — HTTPレスポンスヘッダを全て取得する
  • apache_setenv — Apacheサブプロセスの環境変数を設定する
  • getallheaders — 全てのHTTPリクエストヘッダを取得する
  • virtual — Apache サブリクエストを実行する


このリクエストの後にApacheプロセスを終了する

  • ≪ Apache 関数
  • apache_get_modules ≫
  • PHP Manual
  • Apache 関数
  • このリクエストの後にApacheプロセスを終了する

apache_child_terminate

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

apache_child_terminate — このリクエストの後にApacheプロセスを終了する

説明

apache_child_terminate(): void

apache_child_terminate() は、カレントのPHPリク エストを実行しているApacheプロセスをリクエスト終了時点で終了しま す。この関数は、メモリ消費量が大きなスクリプトを実行した後プロセ スを使用するために使用することが可能です。これは、メモリは通常内 部的にのみ解放され、オペレーティングシステムに戻されないためです。

この関数は、Apache, FastCGI ウェブサーバーで動作します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

注意

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • exit() - メッセージを出力し、現在のスクリプトを終了する


ロードされた Apache モジュールのリストを取得する

  • ≪ apache_child_terminate
  • apache_get_version ≫
  • PHP Manual
  • Apache 関数
  • ロードされた Apache モジュールのリストを取得する

apache_get_modules

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

apache_get_modules — ロードされた Apache モジュールのリストを取得する

説明

apache_get_modules(): array

ロードされた Apache モジュールのリストを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ロードされた Apache モジュールの配列 array を返します。

例

例1 apache_get_modules() の例

<?php
print_r(apache_get_modules());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => core
    [1] => http_core
    [2] => mod_so
    [3] => sapi_apache2
    [4] => mod_mime
    [5] => mod_rewrite
)


Apache のバージョンを取得する

  • ≪ apache_get_modules
  • apache_getenv ≫
  • PHP Manual
  • Apache 関数
  • Apache のバージョンを取得する

apache_get_version

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

apache_get_version — Apache のバージョンを取得する

説明

apache_get_version(): string|false

Apache のバージョンを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功時は Apache のバージョン、失敗した場合に false を返します。

例

例1 apache_get_version() の例

<?php
$version = apache_get_version();
echo "$version\n";
?>

上の例の出力は、 たとえば以下のようになります。

Apache/1.3.29 (Unix) PHP/4.3.4

参考

  • phpinfo() - PHP の設定情報を出力する


Apache の subprocess_env 変数を取得する

  • ≪ apache_get_version
  • apache_lookup_uri ≫
  • PHP Manual
  • Apache 関数
  • Apache の subprocess_env 変数を取得する

apache_getenv

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

apache_getenv — Apache の subprocess_env 変数を取得する

説明

apache_getenv(string $variable, bool $walk_to_top = false): string|false

variable で指定された Apache 環境変数を取得します。

パラメータ

variable

Apache の環境変数を指定します。

walk_to_top

全ての Apache レイヤについてのトップレベル変数を取得するかどうか を指定します。

戻り値

成功時は Apache 環境変数の値、失敗時は false を返します。

例

例1 apache_getenv() の例

この例は、Apache の環境変数 SERVER_ADDR をどの様に取得するかを示しています。

<?php
$ret = apache_getenv("SERVER_ADDR");
echo $ret;
?>

上の例の出力は、 たとえば以下のようになります。

42.24.42.240

参考

  • apache_setenv() - Apacheサブプロセスの環境変数を設定する
  • getenv() - 環境変数の値をひとつ、または全て取得する
  • スーパーグローバル


リクエストの一部を指定したURIに対して行い、全ての情報を返す

  • ≪ apache_getenv
  • apache_note ≫
  • PHP Manual
  • Apache 関数
  • リクエストの一部を指定したURIに対して行い、全ての情報を返す

apache_lookup_uri

(PHP 4, PHP 5, PHP 7, PHP 8)

apache_lookup_uri — リクエストの一部を指定したURIに対して行い、全ての情報を返す

説明

apache_lookup_uri(string $filename): object|false

この関数は、URIにリクエストの一部を行います。このリクエストは指定した リソースに関する全ての重要な情報を得るのに十分なものです。

この関数は、 PHP が apache モジュールとしてインストールされた場合のみサポートされます。

パラメータ

filename

リクエストされているファイル名 (URI)。

戻り値

URI に関する情報のオブジェクトです。返される object のプロパティは次のようなものです。

  • status
  • the_request
  • status_line
  • method
  • content_type
  • handler
  • uri
  • filename
  • path_info
  • args
  • boundary
  • no_cache
  • no_local_copy
  • allowed
  • send_bodyct
  • bytes_sent
  • byterange
  • clength
  • unparsed_uri
  • mtime
  • request_time

失敗時に false を返します。

例

例1 apache_lookup_uri() の例

<?php
$info = apache_lookup_uri('index.php?var=value');
print_r($info);

if (file_exists($info->filename)) {
echo 'file exists!';
}
?>

上の例の出力は、 たとえば以下のようになります。

stdClass Object
(
    [status] => 200
    [the_request] => GET /dir/file.php HTTP/1.1
    [method] => GET
    [mtime] => 0
    [clength] => 0
    [chunked] => 0
    [content_type] => application/x-httpd-php
    [no_cache] => 0
    [no_local_copy] => 1
    [unparsed_uri] => /dir/index.php?var=value
    [uri] => /dir/index.php
    [filename] => /home/htdocs/dir/index.php
    [args] => var=value
    [allowed] => 0
    [sent_bodyct] => 0
    [bytes_sent] => 0
    [request_time] => 1074282764
)
file exists!


Apacheリクエスト記号(note)を取得/設定する

  • ≪ apache_lookup_uri
  • apache_request_headers ≫
  • PHP Manual
  • Apache 関数
  • Apacheリクエスト記号(note)を取得/設定する

apache_note

(PHP 4, PHP 5, PHP 7, PHP 8)

apache_note — Apacheリクエスト記号(note)を取得/設定する

説明

apache_note(string $note_name, ?string $note_value = null): string|false

この関数は、Apache の table_get および table_set のラッパーです。 リクエスト中に存在する note のテーブルを編集します。 このテーブルは、Apache モジュール間の通信に用いるものです。

apache_note() の主な使用法は、 同一リクエスト内でのモジュール間の情報のやりとりです。

パラメータ

note_name

記号の名前

note_value

記号の値

戻り値

note_value が省略されるか、null の場合、 note_name の現在の値が返されます。 そうでない場合、記号note_name の値をnote_valueにセットし、前の記号 note_nameの値を返します。 もし記号が処理できない場合、false が返されます。

変更履歴

バージョン | 説明
8.0.0 | note_value は、nullable になりました。

例

例1 PHP と Perl との間での情報のやりとり

<?php

apache_note('name', 'Fredrik Ekengren');

// perl スクリプトをコールします
virtual("/perl/some_script.pl");

$result = apache_note("resultdata");
?>
# Apache リクエストオブジェクトを取得します
my $r = Apache->request()->main();

# 受け取ったデータを取得します
my $name = $r->notes('name');

# 何らかの処理をします

# 結果を PHP 側に戻します
$r->notes('resultdata', $result);

例2 access.log への出力

<?php

apache_note('sessionID', session_id());

?>
# "%{sessionID}n" を LogFormat ディレクティブで使用できます

参考

  • virtual() - Apache サブリクエストを実行する


すべての HTTP リクエストヘッダを取得する

  • ≪ apache_note
  • apache_response_headers ≫
  • PHP Manual
  • Apache 関数
  • すべての HTTP リクエストヘッダを取得する

apache_request_headers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

apache_request_headers — すべての HTTP リクエストヘッダを取得する

説明

apache_request_headers(): array

現在のリクエストにおけるすべての HTTP リクエストヘッダを取得します。 Apache, FastCGI, CLI, FPM ウェブサーバーで動作します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のリクエストにおけるすべての HTTP ヘッダの連想配列、 あるいは失敗時は false を返します。

変更履歴

バージョン | 説明
7.3.0 | FPM SAPI でもこの関数が使えるようになりました。

例

例1 apache_request_headers() の例

<?php
$headers = apache_request_headers();

foreach ($headers as $header => $value) {
echo "$header: $value <br />\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0
Host: www.example.com
Connection: Keep-Alive

注意

注意:

環境変数を読み込むことにより、共通の CGI 変数の値を取得することも可能です。 これは、PHPがApacheモジュール として使用されているかどうかにはよらず動作します。 利用可能な環境変数 の一覧を見るには、phpinfo()を使用してください。

参考

  • apache_response_headers() - HTTPレスポンスヘッダを全て取得する


HTTPレスポンスヘッダを全て取得する

  • ≪ apache_request_headers
  • apache_setenv ≫
  • PHP Manual
  • Apache 関数
  • HTTPレスポンスヘッダを全て取得する

apache_response_headers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

apache_response_headers — HTTPレスポンスヘッダを全て取得する

説明

apache_response_headers(): array|false

全てのApacheレスポンスヘッダを配列として取得します。 Apache, FastCGI, CLI, FPM ウェブサーバーで動作します。

パラメータ

この関数にはパラメータはありません。

戻り値

全てのApacheレスポンスヘッダの配列、失敗した場合に false を返します。

例

例1 apache_response_headers() の例

<?php
print_r(apache_response_headers());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Accept-Ranges] => bytes
    [X-Powered-By] => PHP/4.3.8
)

参考

  • apache_request_headers() - すべての HTTP リクエストヘッダを取得する
  • headers_sent() - ヘッダが既に送信されているかどうかを調べる
  • headers_list() - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す


Apacheサブプロセスの環境変数を設定する

  • ≪ apache_response_headers
  • getallheaders ≫
  • PHP Manual
  • Apache 関数
  • Apacheサブプロセスの環境変数を設定する

apache_setenv

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

apache_setenv — Apacheサブプロセスの環境変数を設定する

説明

apache_setenv(string $variable, string $value, bool $walk_to_top = false): bool

apache_setenv() は variable で指定された Apache 環境変数の値を設定します。

注意:

Apache 環境変数を設定しても、対応する $_SERVER の値は変更されません。

パラメータ

variable

設定する環境変数

value

variable の新しい値

walk_to_top

全ての Apache レイヤに対して有効なトップレベルの変数を設定するかどうか

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 apache_setenv() を使った Apache 環境変数の設定

<?php
apache_setenv("EXAMPLE_VAR", "Example Value");
?>

注意

注意:

apache_setenv() は、分割されたページや PHP スクリプトによって取り込まれた Server Side Includes (.shtml) に渡すための変数を設定する場合、 apache_getenv() と対にして使用することができます。

参考

  • apache_getenv() - Apache の subprocess_env 変数を取得する


全てのHTTPリクエストヘッダを取得する

  • ≪ apache_setenv
  • virtual ≫
  • PHP Manual
  • Apache 関数
  • 全てのHTTPリクエストヘッダを取得する

getallheaders

(PHP 4, PHP 5, PHP 7, PHP 8)

getallheaders — 全てのHTTPリクエストヘッダを取得する

説明

getallheaders(): array

すべての HTTP ヘッダを現在のリクエストから取得します。

この関数は、 apache_request_headers()のエイリアスです。 この関数は、カレントのリクエストにおける全てのHTTPヘッダーを有する 連想配列を返します。この関数の動作に関する詳細については、 apache_request_headers()のドキュメントを参照して ください。

パラメータ

この関数にはパラメータはありません。

戻り値

全てのHTTPリクエストヘッダの連想配列、もしくは失敗時に false を返します。

変更履歴

バージョン | 説明
7.3.0 | FPM SAPI でもこの関数が使えるようになりました。

例

例1 getallheaders() の例

<?php

foreach (getallheaders() as $name => $value) {
echo "$name: $value\n";
}

?>

参考

  • apache_response_headers() - HTTPレスポンスヘッダを全て取得する


Apache サブリクエストを実行する

  • ≪ getallheaders
  • FastCGI Process Manager(FPM) ≫
  • PHP Manual
  • Apache 関数
  • Apache サブリクエストを実行する

virtual

(PHP 4, PHP 5, PHP 7, PHP 8)

virtual — Apache サブリクエストを実行する

説明

virtual(string $uri): bool

virtual() は、mod_include の <!--#include virtual...--> と似ている Apache 用関数です。 この関数は、Apache サブリクエストを実行します。 CGI スクリプトまたは .shtml ファイル、Apache を通して解釈を行う 他のものがある場合にこの関数は有用です。 CGI スクリプトの場合、そのスクリプトは、有効な CGI ヘッダを生成する 必要があることに注意してください。 最低でも、Content-Type ヘッダを生成する必要があります。

サブリクエストを実行するには、全てのバッファを終了、ブラウザへフラッシュし、 待機状態のヘッダも送信しておきます。

この関数は、 PHP が apache モジュールとしてインストールされた場合のみサポートされます。

パラメータ

uri

virtual コマンドが実行されるファイル

戻り値

成功時は virtual コマンドの実行、失敗時は false を返します。

例

apache_note() の例を参照ください。

注意

警告

クエリ文字列をインクルードされるファイルに渡す事ができますが、 $_GET は親スクリプトからコピーされ、 $_SERVER['QUERY_STRING'] は渡されたクエリ文字列に なります。クエリ文字列は、Apache 2 を使用している場合の見渡されます。 要求されたファイルは Apache アクセスログに出力されません。

注意:

要求されたファイルの中で設定された環境変数は、呼び出し元の スクリプトからは見えません。

注意:

この関数を PHP ファイルに対して使ってもかまいません。 しかし、一般的に、PHP ファイルに対しては include あるいは require を使うほうがいいでしょう。

参考

  • apache_note() - Apacheリクエスト記号(note)を取得/設定する


FastCGI Process Manager(FPM)

  • はじめに
  • インストール/設定
  • オブザーバビリティ(可観測性)
    • FPM の情報ページ
  • FPM 関数
    • fastcgi_finish_request — すべてのレスポンスデータをクライアントにフラッシュする
    • fpm_get_status — 現在の FPMプール の状態を返す


はじめに

FPM (FastCGI Process Manager) は、PHP における FastCGI 実装です。(主に)高負荷のサイトで有用な機能が含まれています。

この SAPI は、PHP 本体にバンドルされています。


  • ≪ はじめに
  • オブザーバビリティ(可観測性) ≫
  • PHP Manual
  • FastCGI Process Manager(FPM)
  • インストール/設定

インストール/設定

FPM のインストールおよび設定についての情報は、PHP マニュアルの インストールと設定 で見つかります。


  • ≪ インストール/設定
  • FPM の情報ページ ≫
  • PHP Manual
  • FastCGI Process Manager(FPM)
  • オブザーバビリティ(可観測性)

オブザーバビリティ(可観測性)

目次

  • FPM の情報ページ


FPM の情報ページ

このページは、FPM の情報ページをセットアップする方法の説明と、 表示される内容について記しています。 fpm_get_status() も参照ください。

設定

FPM の情報ページは、 FPM プールの設定にある pm.status_path パラメータを設定することで有効にできます。

警告

セキュリティを考慮して、 FPM の情報ページへのアクセスは、 内部的なリクエスト または既知のクライアントIPからのリクエストに限定すべきです。 なぜなら、この情報ページはリクエストURLや、 利用可能なリソースに関する情報を晒してしまっているからです。

ウェブサーバーの設定によっては、 PHP スクリプトをバイパスさせ、 このパスへの直接アクセスを許可する必要があるかもしれません。 Unix Domain Socket(UDS) 経由で listen している FPM と Apache を設定する例は、下記のようになります。 ここでは、 pm.status_path に /fpm-status を設定しています:

<LocationMatch "/fpm-status">
 Order Allow,Deny
 Allow from 127.0.0.1
 ProxyPass "unix:/var/run/php-fpm.sock|fcgi://localhost/fpm-status"
</LocationMatch>

FPM とウェブサーバーをリロードまたは再起動した後、 情報ページがブラウザからアクセスできるようになっているはずです。 (IP アドレス制限が設定されている場合は、 リクエストが許可したIPアドレスから来ている場合に限ります)

クエリパラメータ

情報ページの出力フォーマットは、以下のクエリパラメータのうちひとつを指定することで変更できます:

  • html
  • json
  • openmetrics
  • xml

クエリパラメータ full を使うことで、 追加の情報を出力させることもできます。

情報ページのURLの例は、下記のとおりです:

  • https://localhost/fpm-status - デフォルトのテキストフォーマットで、概要を出力します。
  • https://localhost/fpm-status?full - デフォルトのテキストフォーマットで、全ての情報を出力します。
  • https://localhost/fpm-status?json - JSON で 概要を出力します。
  • https://localhost/fpm-status?html&full - HTML フォーマットで、全ての情報を出力します。

表示される情報

日付/時刻 の値は、JSON と XML 出力では Unixタイムスタンプを使います。 それ以外の場合は、 "03/Jun/2021:07:21:46 +0100" のようなフォーマットを使います。

基本情報 - 常に表示されます
パラメータ | 説明
pool | FPM プロセスプールの名前
proccess manager | プロセスマネージャーのタイプ - static, dynamic, または ondemand.
start time | プロセスプールが最後に起動した日付/時刻
start since | プロセスプールが最後に起動してから経過した秒数
accepted conn | 受け入れた接続の合計数
listen queue | 空きのプロセスを待っている(backlogに入っている)現在のリクエスト数
max listen queue | ある一時点でlisten キューに入ったリクエストの最大数
listen queue len | 許可されているlisten キューの最大サイズ
idle processes | (リクエストを待っている)現在アイドルなプロセス数
active processes | 現在リクエストを処理しているプロセス数
total processes | 現在のプロセスの合計数
max active processes | 同時にアクティブになったプロセスの最大数
max children reached | プロセスの最大数に達したことがあるかを示します。 ある場合、表示は 1 以上になります。 ない場合、表示は 0 になります。
slow requests | 設定した request_slowlog_timeout に到達したリクエストの合計
プロセス単位の情報 - 出力モードが full の場合にだけ表示されます
パラメータ | 説明
pid | プロセスの PID
state | プロセスの状態 - Idle, Running, ...
start time | プロセスが起動した日付/時刻
start since | プロセスが起動後、経過した秒数
requests | 処理したリクエスト数
request duration | 直近のリクエストを処理するのに使った時間の合計(ミリ秒単位)
request method | 直近のリクエストの HTTP メソッド
request uri | 最後に処理したリクエストのURL(webサーバーが処理した後のもの。フロントコントローラーパターンを使っている場合、常に /index.php になる場合があります)
content length | 直近のリクエストの、body の長さ(バイト単位)
user | 直近のリクエストの HTTP ユーザー (PHP_AUTH_USER)
script | 直近のリクエストで実行されたスクリプトのフルパス。 適用できない場合(例: FPM 情報ページへのリクエスト)は、 '-' になります。
last request cpu | 直近のリクエストの、%cpu の値。 プロセスがアイドルでない場合、この値は0になります。 なぜなら、リクエストの処理が終わった時にこの値は計算されるからです。 この値は100%を超えることがあります。 なぜならこのメトリクスは、 直近のリクエストで使われたCPU時間の合計をパーセント単位で示すからです - つまりこの値はすべてのコアのプロセスを考慮しますが、 コアがひとつの場合は、100% になります。
last request memory | 直近のリクエストが消費したメモリの最大値。 プロセスがアイドルでない場合、この値は0になります。 なぜなら、リクエストの処理が終わった時にこの値は計算されるからです。

注意:

プールに特有の全ての値は、FPM が再起動されるとリセットされます。

注意:

OpenMetrics フォーマットの出力は、 OpenMetrics に準拠した、異なるパラメータタイプを使います。 出力のパラメータとその説明は、 OpenMetrics フォーマット出力に含まれています。

変更履歴

バージョン | 説明
8.1.0 | openmetrics フォーマットが追加されました。


FPM 関数

目次

  • fastcgi_finish_request — すべてのレスポンスデータをクライアントにフラッシュする
  • fpm_get_status — 現在の FPMプール の状態を返す


すべてのレスポンスデータをクライアントにフラッシュする

  • ≪ FPM 関数
  • fpm_get_status ≫
  • PHP Manual
  • FPM 関数
  • すべてのレスポンスデータをクライアントにフラッシュする

fastcgi_finish_request

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

fastcgi_finish_request — すべてのレスポンスデータをクライアントにフラッシュする

説明

fastcgi_finish_request(): bool

この関数は、すべてのレスポンスデータをクライアントにフラッシュし、 リクエストを終わらせます。 これにより、クライアントへの接続を開いたままにすることなく、 時間のかかる処理を実行することができます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


現在の FPMプール の状態を返す

  • ≪ fastcgi_finish_request
  • セッション関連 ≫
  • PHP Manual
  • FPM 関数
  • 現在の FPMプール の状態を返す

fpm_get_status

(PHP 7 >= 7.3, PHP 8)

fpm_get_status — 現在の FPMプール の状態を返す

説明

fpm_get_status(): array|false

この関数は、現在の FPMプール の状態を全て格納し、連想配列で返します。 この関数は、プロセス単位の情報を含んだ、全ての状態を常に返します。 詳細については、 FPM の情報ページ を参照ください。

この関数は、FPM を使ってスクリプトを実行している場合にだけ定義されることに注意して下さい。

パラメータ

この関数にはパラメータはありません。

戻り値

FPMプール の状態を全て含む連想配列を返します。 失敗した場合に false を返します


セッション関連

  • Sessions — セッション処理
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • セッションのアップロード状況
    • セッション と セキュリティ
    • セッション関数
    • SessionHandler — SessionHandler クラス
    • SessionHandlerInterface — SessionHandlerInterface クラス
    • SessionIdInterface — SessionIdInterface クラス
    • SessionUpdateTimestampHandlerInterface — SessionUpdateTimestampHandlerInterface クラス


セッション処理

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
    • 基本的な使用法
    • セッションIDの受渡し
    • カスタムセッションハンドラ
  • セッションのアップロード状況
  • セッション と セキュリティ
    • セッション管理の基礎
    • セッションに関連する INI 設定をセキュアにする
  • セッション関数
    • session_abort — session 配列の変更を破棄してセッションを終了します
    • session_cache_expire — 現在のキャッシュの有効期限を取得/設定する
    • session_cache_limiter — 現在のキャッシュリミッタを取得または設定する
    • session_commit — session_write_close のエイリアス
    • session_create_id — 新しいセッションIDを作成する
    • session_decode — セッションエンコードされた文字列からセッションデータをデコードする
    • session_destroy — セッションに登録されたデータを全て破棄する
    • session_encode — 現在のセッションデータを、セッションエンコードされた文字列に変換する
    • session_gc — セッションデータのガベージコレクションを実行する
    • session_get_cookie_params — セッションクッキーのパラメータを得る
    • session_id — 現在のセッション ID を取得または設定する
    • session_module_name — 現在のセッションモジュールを取得または設定する
    • session_name — 現在のセッション名を取得または設定する
    • session_regenerate_id — 現在のセッションIDを新しく生成したものと置き換える
    • session_register_shutdown — セッションのシャットダウン関数
    • session_reset — session 配列を元の値で再初期化します
    • session_save_path — 現在のセッションデータ保存パスを取得または設定する
    • session_set_cookie_params — セッションクッキーパラメータを設定する
    • session_set_save_handler — ユーザー定義のセッション保存関数を設定する
    • session_start — 新しいセッションを開始、あるいは既存のセッションを再開する
    • session_status — 現在のセッションの状態を返す
    • session_unset — 全てのセッション変数を開放する
    • session_write_close — セッションデータを書き込んでセッションを終了する
  • SessionHandler — SessionHandler クラス
    • SessionHandler::close — セッションを閉じる
    • SessionHandler::create_sid — 新規セッション ID を返す
    • SessionHandler::destroy — セッションを破棄する
    • SessionHandler::gc — 古いセッションを削除する
    • SessionHandler::open — セッションを開始する
    • SessionHandler::read — セッションのデータを読み込む
    • SessionHandler::write — セッションのデータを書き込む
  • SessionHandlerInterface — SessionHandlerInterface クラス
    • SessionHandlerInterface::close — セッションを閉じる
    • SessionHandlerInterface::destroy — セッションを破棄する
    • SessionHandlerInterface::gc — 古いセッションを削除する
    • SessionHandlerInterface::open — セッションを開始する
    • SessionHandlerInterface::read — セッションのデータを読み込む
    • SessionHandlerInterface::write — セッションのデータを書き込む
  • SessionIdInterface — SessionIdInterface クラス
    • SessionIdInterface::create_sid — セッションIDを作成する
  • SessionUpdateTimestampHandlerInterface — SessionUpdateTimestampHandlerInterface クラス
    • SessionUpdateTimestampHandlerInterface::updateTimestamp — タイムスタンプを更新する
    • SessionUpdateTimestampHandlerInterface::validateId — セッションIDを検証する


はじめに

PHPのセッションサポート機能は、複数回のアクセスを通じて特定のデータを保持する手段を実現するものです。

Web サイトの訪問者にはセッションIDというセッションIDと呼ばれるユニークなIDが割りつけられ ます。このIDは、ユーザー側にクッキーとして保存するか、または、URL に埋め込みます。

セッションサポート機能により、スーパーグローバル配列 $_SESSION を使ってリクエスト間でデータを格納できるようになります。 来訪者がサイトにアクセスした際、 PHP は特定のセッションIDがリクエストとともに送信されているかどうかを ( session.auto_startが1の場合は)自動的に、または (session_start() により明示的な) 要求を受けて確認します。 このIDが送信されている場合には、以前保存された変数が再現されます。

警告

session.auto_start をオンにした場合にオブジェクトをセッションに代入する唯一の方法は、 クラスの定義を auto_prepend_file でロードしておき、オブジェクトを serialize() したうえで後で unserialize() することです。

$_SESSION (およびそこに登録されたすべての変数) は、リクエストが終了したときに PHP が内部的にシリアライズします。 シリアライズの方式として、ini 設定 session.serialize_handler で指定したハンドラを使います。 未定義の登録変数は、未定義としてマーク付けされます。 これらの変数は、後でユーザーが定義しない限り、以降のアクセスにおいて セッションモジュールにより定義されません。

警告

セッションデータはシリアライズされるので、 resource 型の変数はセッションに格納できません。

シリアライズハンドラ (php および php_binary) は、register_globals の制約を引き継いでいます。 そのため、数値のインデックスや特殊文字 (| や !) を含む文字列のインデックスは使えません。 これらを使っていると、スクリプトのシャットダウン時にエラーが発生します。 php_serialize には、そのような制約はありません。

注意:

セッションを処理している時、 スーパーグローバル配列$_SESSION へ新しいキーを 追加して変数が登録されるまで、 セッションのレコードは作成されないことに注意してください。 これは、セッションが session_start() 関数により開始されている場合でも当てはまります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Sessions
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

外部ライブラリは必要ありません。

注意:

オプションで、Ralf S. Engelschallにより開発されたセッションの保 存用の共有メモリ(mm)を使用することも可能です。 » mmをダウンロードし、インストールす ることができます。このオプションは、Windowsプラットフォームでは 利用できません。mm用セッション保存モジュールは同一セッションのロッ クに問題があるため、同時アクセスを保証することはできません。 ファイルにセッションを保存するためには、 (Solaris/Linux の tmpfs または BSD の /dev/md のように) 共有メモリベースのファイルシステムを使用するほうがよいでしょう。 セッションのデータはメモリに保存されます。そのため、Web サーバーを 再起動するとデータが削除されます。


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-session

セッション記憶領域として共有メモリ(mm)を使用するには、PHP の configure オプションに --with-mm[=DIR] を指定します。


実行時設定

php.ini の設定により動作が変化します。

セッションの設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
session.save_path | "" | INI_ALL |
session.name | "PHPSESSID" | INI_ALL |
session.save_handler | "files" | INI_ALL |
session.auto_start | "0" | INI_PERDIR |
session.gc_probability | "1" | INI_ALL |
session.gc_divisor | "100" | INI_ALL |
session.gc_maxlifetime | "1440" | INI_ALL |
session.serialize_handler | "php" | INI_ALL |
session.cookie_lifetime | "0" | INI_ALL |
session.cookie_path | "/" | INI_ALL |
session.cookie_domain | "" | INI_ALL |
session.cookie_secure | "0" | INI_ALL | PHP 7.2.0 より前のバージョンでは、デフォルト値は "" でした。
session.cookie_httponly | "0" | INI_ALL | PHP 7.2.0 より前のバージョンでは、デフォルト値は "" でした。""
session.cookie_samesite | "" | INI_ALL | PHP 7.3.0 から利用可能
session.use_strict_mode | "0" | INI_ALL |
session.use_cookies | "1" | INI_ALL |
session.use_only_cookies | "1" | INI_ALL |
session.referer_check | "" | INI_ALL |
session.cache_limiter | "nocache" | INI_ALL |
session.cache_expire | "180" | INI_ALL |
session.use_trans_sid | "0" | INI_ALL |
session.trans_sid_tags | "a=href,area=href,frame=src,form=" | INI_ALL | PHP 7.1.0 から利用可能
session.trans_sid_hosts | $_SERVER['HTTP_HOST'] | INI_ALL | PHP 7.1.0 から利用可能
session.sid_length | "32" | INI_ALL | PHP 7.1.0 から利用可能
session.sid_bits_per_character | "4" | INI_ALL | PHP 7.1.0 から利用可能
session.upload_progress.enabled | "1" | INI_PERDIR |
session.upload_progress.cleanup | "1" | INI_PERDIR |
session.upload_progress.prefix | "upload_progress_" | INI_PERDIR |
session.upload_progress.name | "PHP_SESSION_UPLOAD_PROGRESS" | INI_PERDIR |
session.upload_progress.freq | "1%" | INI_PERDIR |
session.upload_progress.min_freq | "1" | INI_PERDIR |
session.lazy_write | "1" | INI_ALL |
session.hash_function | "0" | INI_ALL | PHP 7.1.0 で削除されました。
session.hash_bits_per_character | "4" | INI_ALL | PHP 7.1.0 で削除されました。
session.entropy_file | "" | INI_ALL | PHP 7.1.0 で削除されました。
session.entropy_length | "0" | INI_ALL | PHP 7.1.0 で削除されました。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

セッション管理システムは、php.iniファイルに記述可能な多くの設定オ プションをサポートします。以下に概要を示します。

session.save_handler string
session.save_handler は、 セッションに関連するデータの保存および取得時に使用するハンドラを定義します。 デフォルトは、files です。各拡張モジュールで、 独自の save_handler を使用できることに注意しましょう。 インストール環境単位で登録されているハンドラを取得するには phpinfo() を使用します。 session_set_save_handler() も参照ください。
session.save_path string
session.save_path は、保存ハンドラに渡される 引数を定義します。デフォルトのファイルハンドラを選択した場合、 ファイルが作成される場所のパスになります。 session_save_path() も参照ください。

オプションの引数として N（数値）を指定できます。 これはセッションファイルを分散して保存する際に ディレクトリ階層レベルを決定します。 例えば、'5;/tmp'とすると /tmp/4/b/1/e/3/sess_4b1e384ad74619bd212e236e52a5a174If という位置にセッションファイルを生成します。 N を使用するには、これらすべてのディレクトリが 事前に作成されている必要があります。 そのためのシェルスクリプトがext/sessionに mod_files.shというファイル名であります。 Windows 版の mod_files.bat もあります。 また、0以上の N が指定されている場合には自動ガーベッジコレクション が機能しないことに注意してください。詳細は php.ini を見てください。 また、N を指定する場合は、 session.save_pathを"quotes"で囲う必要があります。 なぜならセパレータ(;) は php.ini ではコメントとしても利用されているからです。

ファイルストレージモジュールが作るファイルのモードは、デフォルトで 600 になります。 このデフォルトを変更するには、オプションの引数 MODE を利用します。 N;MODE;/path のように使い、MODE の部分に八進形式のモードを指定します。MODE を設定しても、そのプロセスの umask は変わりません。

警告

この設定を /tmp (デフォルト) のようにどこか らでも読み込み可能なディレクトリに設定した場合、サーバー上 の他のユーザーがこのディレクトリのファイルのリストを取得すること により、セッションをハイジャックをすることが可能となります。

警告

オプションのディレクトリレベル定数 N で、 1 あるいは 2 以外の値を使うのは、大半のサイトでは不適切です。 大量のディレクトリが必要になってしまうからです。たとえば、この値を 3 にすると、 ファイルシステム上のディレクトリの数が (2 ** session.sid_bits_per_character) ** 3 にもなり、 ディスク容量や inode の無駄遣いになってしまいます。

N を 2 より大きくするのは、 それを必要とするような大規模サイトに限るようにしましょう。

session.name string
session.name はセッション名を指定し、 クッキー名として使用されます。 アルファベット文字のみで指定する必要があります。 デフォルトは、PHPSESSID です。 session_name()も参照ください。
session.auto_start bool
session.auto_start はリクエスト開始時に セッションモジュールがセッションを自動的に開始するかどうかを 指定します。デフォルトは、0(無効)です。
session.serialize_handler string
session.serialize_handler は、シリアル化または シリアル化データを復元するために使用されるハンドラの名前を定義します。 PHP シリアライズフォーマット (php_serialize)、 PHP 内部フォーマット (php あるいは php_binary)、 そして WDDX (wddx) に対応しています。WDDX は、PHP がWDDX サポート を有効にしてコンパイルされている場合のみ使用可能です。 php_serialize はプレーンな serialize/unserialize 関数を内部的に使っており、php や php_binary のような制約はありません。これらのシリアライズハンドラでは、$_SESSION の中で数値のインデックスや特殊文字 (| や !) を含む文字列のインデックスを使えませんでした。 php_serialize を使えば、 スクリプトの終了時に数値インデックスや特殊文字インデックスのエラーが出ないようにできます。 デフォルトは php です。
session.gc_probability int
session.gc_probabilityと session.gc_divisorの組み合わせでgc （ガーベッジコレクション）ルーチンの始動を制御します。 デフォルトは、1 です。 詳細はsession.gc_divisor をご覧ください
session.gc_divisor int
session.gc_divisorと session.gc_probabilityの組み合わせで すべてのセッションの初期化過程でgc（ガーベッジコネクション）プロセス も始動する確率を制御します。確率は gc_probability/gc_divisor で計算されます。例えば、1/100は各リクエスト毎に1%の確率でGCプロセスが 始動します。 session.gc_divisorのデフォルトは100です。
session.gc_maxlifetime int
session.gc_maxlifetime は、データが 'ごみ' とみなされ、消去されるまでの秒数を指定します。 ガベージコレクション (ごみの収集) は、 セッションの開始時に行われます (session.gc_probability と session.gc_divisor に依存します)。 デフォルトは 1440 (24分) です。

注意: 異なる値を session.gc_maxlifetime に指定している 別々のスクリプトがセッションデータの保存場所を共有している場合、 一番小さい設定値に達した時点でデータが消去されます。このような場合には、 お互いに session.save_path を使用します。

session.referer_check string
session.referer_check には、HTTP Referer に おいて確認を行う文字列を指定します。Refererがクライアントにより 送信されており、かつ、指定した文字列が見付からない場合、埋め込 まれたセッションIDは無効となります。デフォルトは空の文字列です。
session.entropy_file string
session.entropy_file は、 セッションIDを作成する際の別のエントロピーソースとして使用する 外部リソースへのパスを指定します。 例としては、多くの UNIX で利用可能な /dev/random または /dev/urandom があげられます。 この機能は、Windows でもサポートされています。 session.entropy_length にゼロ以外の値を設定すると、 PHP は Windows Random API をエントロピーソースとして使います。

注意: PHP 7.1.0 で削除されました。 /dev/urandom あるいは /dev/arandom が使えるときは、 それが session.entropy_file のデフォルトになります。

session.entropy_length int
session.entropy_length は、前記のファイルから 読みこむバイト数を指定します。デフォルトは、32 です。 PHP 7.1.0 で削除されました。
session.use_strict_mode bool
session.use_strict_mode は、 厳格なセッション ID モードを利用するかどうかを指定します。 有効にすると、初期化していないセッション ID を受け付けなくなります。 初期化していないセッション ID がブラウザから送信された場合は、 新しいセッション ID をブラウザに送り返します。 このモードを利用すると、セッションアダプションを利用したセッション固定攻撃からアプリケーションを保護できます。 デフォルトは 0 (無効) です。

注意: 一般的なセッションのセキュリティを踏まえると、 session.use_strict_mode を有効にしておく必要があります。 すべてのサイトでこれを有効にすることを推奨します。 詳細は session_create_id() のサンプルコードを参照ください。

警告

カスタムのセッションハンドラが session_set_save_handler() 経由で登録され、 それが SessionUpdateTimestampHandlerInterface::validateId() を実装せず、 validate_sid コールバックを提供しない場合、 このディレクティブの値に関わらず、厳格なセッションIDモードは無効になります。 SessionHandler クラスは SessionHandler::validateId() を実装して いない ことに特に注意して下さい。

session.use_cookies bool
session.use_cookiesによりクライアント側にセッ ションIDを保存する際にクッキーを使用するかどうかを指定します。デ フォルトは1 (有効)です。
session.use_only_cookies bool
session.use_only_cookies は、 このモジュールがクライアント側へのセッション ID の保存に Cookie のみ を使用することを指定します。 この設定を有効にすることにより、セッション ID を URL に埋め込む攻撃を防ぐことができます。 デフォルトは 1 (有効) となります。
session.cookie_lifetime int
session.cookie_lifetime は、 ブラウザに送信するクッキーの有効期間を秒単位で指定します。 0 を指定すると "ブラウザを閉じるまで" という意味になります。 デフォルトは、0 です。 session_get_cookie_params() および session_set_cookie_params() も参照ください。

注意: 有効期限のタイムスタンプは、サーバーの時刻に基づいて決まります。 クライアントのブラウザの時刻がこれと同じであるとは限りません。

session.cookie_path string
session.cookie_path によりセッションクッキーで設定するパスを指定します。 デフォルトは/です。 session_get_cookie_params()および session_set_cookie_params()も参照ください。
session.cookie_domain string
session.cookie_domain によりセッションクッキーで指定するドメインを指定します。 デフォルトでは指定されません。 この場合は、クッキーの仕様によって、クッキーを作成したサーバーの ホスト名が指定されます。 session_get_cookie_params() および session_set_cookie_params() も参照ください。
session.cookie_secure bool
クッキーはセキュアな接続を通じてのみ送信すべきものです。 このオプションを on にすると、 セッションは HTTPS 接続の場合にのみ動作します。 off の場合には、HTTP と HTTPS 接続の両方で動作します。 デフォルトは off です。
session.cookie_httponly bool
クッキーに対して、HTTP を通してのみアクセスできるようにします。 つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。 この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせます (が、すべてのブラウザがこの設定をサポートしているというわけではありません)。
session.cookie_samesite string
クロスサイトリクエストで、サーバーにクッキーを送信しないよう指示できるようにします。 これを用いると、ユーザーエージェントによる生成元とは異なる場所への情報漏洩のリスクを軽減できます。 また、CSRF攻撃に対する防御策のひとつにもなります。 この仕組みはすべてのブラウザがサポートしているわけではないことに注意しましょう。 この項目に空の値を設定した場合は、クッキーのSameSite属性は送信されません。 Lax や Strict を設定した場合は、 サイトをまたがる POST リクエストではクッキーを送信しません。GET リクエストの場合は、 Lax はサイトをまたがるリクエストでもクッキーを送信しますが、 Strict は送信しません。
session.cache_limiter string
session.cache_limiter により、セッションページにおけるキャッシュ制御の方法を指定します。 nocache、private、 private_no_expire あるいは public のいずれかとなります。デフォルトは nocache です。 これらの値の意味については session_cache_limiter() のドキュメントも参照ください。
session.cache_expire int
session.cache_expireによりキャッシュされた セッションページの有効期間を分単位で指定します。 このオプションは、nocacheリミッタに関しては効果がありません。 デフォルトは、180です。 session_cache_expire()も参照ください。
session.use_trans_sid bool
session.use_trans_sidは、透過的なセッション IDの付加をするかどうかを指定します。 デフォルトは、0(無効)です。

注意: URLに基づくセッション管理は、Cookieに基づくセッション管理と比べ てセキュリティリスクが大きくなります。例えば、ユーザーは、emailに より友人にアクティブなセッションIDを含むURLを送信する可能性があ り、また、ユーザーは自分のブックマークにセッションIDを含むURLを保 存し、常に同じセッションIDで使用するサイトにアクセスする可能性 があります。 PHP 7.1.0 以降では、https://php.net/ のような完全な URL パスが、透過的セッションID機能で扱われるようになります。 これより前のバージョンでは、相対 URL パスだけが対象でした。 リライト対象のホストは session.trans_sid_hosts で定義します。

session.trans_sid_tags string
session.trans_sid_tags は、透過的セッションIDのサポートが有効な場合にどの HTML タグをリライトするかを指定します。 デフォルトは a=href,area=href,frame=src,input=src,form= です。 form は特別なタグで、<input hidden="session_id" name="session_name"> がフォーム変数に追加されます。

注意: PHP 7.1.0 より前のバージョンでは、この目的で使われていた設定項目は url_rewriter.tags でした。 PHP 7.1.0 以降は、fieldset が特別なタグとはみなされなくなります。

session.trans_sid_hosts string
session.trans_sid_hosts は、 は、透過的セッションIDのサポートが有効な場合にどのホストをセッションIDつきにリライトするかを指定します。 デフォルトは $_SERVER['HTTP_HOST'] です。 複数のホストを指定する場合は "," で区切ってつなぎます。 ホストとホストの間にスペースを入れることはできません。つまり、たとえば php.net,wiki.php.net,bugs.php.net のように指定します。
session.sid_length int
session.sid_length は、セッション ID 文字列の長さを指定します。 22 から 256 までの値が使えます。 デフォルトは 32 です。互換性を考慮するなら 32 や 40 などを使ってもかまいません。 セッション ID は長ければ長いほど推測されにくくなります。少なくとも 32 を指定することを推奨します。
ヒント

互換性に関するメモ: session.hash_function=0 (MD5) で session.hash_bits_per_character=4 の場合、あるいは session.hash_function=1 (SHA1) で session.hash_bits_per_character=6 の場合は 32 を使います。 session.hash_function=0 (MD5) で session.hash_bits_per_character=5 の場合は、26 を使います。 session.hash_function=0 (MD5) で session.hash_bits_per_character=6 の場合は、22 を使います。 INI 設定で、セッション ID を少なくとも 128 ビットにしておく必要があります。 session.sid_bits_per_character に適切な値を指定することを忘れないようにしましょう。 そうしないと、脆弱なセッション ID を使うことになってしまいます。

注意: この設定は PHP 7.1.0 で導入されました。

session.sid_bits_per_character int
session.sid_bits_per_character エンコードされたセッション ID 文字のビット数を指定します。指定できる値は '4' (0-9, a-f)、'5' (0-9, a-v)、'6' (0-9, a-z, A-Z, "-", ",") です。 デフォルトは 4 です。大きいほどセッション ID が強力になります。 大半のシステムでは、5 を推奨します。

注意: この設定は PHP 7.1.0 で導入されました。

session.hash_function mixed
session.hash_function によりセッション ID を生成するために使用されるハッシュアルゴリズムを指定することが可能です。 '0' は MD5 (128 ビット) で、'1' は SHA-1 (160 ビット) を意味します。

hash 拡張モジュール の任意のアルゴリズムが (この拡張モジュールが使用可能な場合に) 指定できます。たとえば sha512 や whirlpool などです。 サポートされているアルゴリズムの一覧は、 hash_algos() 関数で取得できます。

注意:

この設定は、PHP 7.1.0 で削除されました。

session.hash_bits_per_character int
session.hash_bits_per_character により バイナリのハッシュデータを何らかの可読なデータに変換する際、 それぞれの文字に何ビットストアさせるかを定義することが可能です。 指定可能な値は、'4' (0-9, a-f)、'5' (0-9, a-v) そして '6' (0-9, a-z, A-Z, "-", ",") です。

注意:

この設定は、PHP 7.1.0 で削除されました。

session.upload_progress.enabled bool
アップロードの進捗を追跡して $_SESSION 変数に格納するかどうか。 デフォルトは 1 で、この機能は有効になっています。
session.upload_progress.cleanup bool
すべての POST データを読み終えた (つまり、アップロードが完了した) 時点ですぐに進捗状況を消去するかどうか。 デフォルトは 1 で、この機能は有効になっています。

注意: この機能を有効にしておくことを強くおすすめします。

session.upload_progress.prefix string
アップロードの進捗を $_SESSION で管理するときに使うキーのプレフィックス。 このキーを $_POST[ini_get("session.upload_progress.name")] の値と連結して、一意なインデックスを作ります。 デフォルトは "upload_progress_" です。
session.upload_progress.name string
進捗情報を $_SESSION に格納するときに使うキーの名前。 session.upload_progress.prefix も参照ください。 $_POST[ini_get("session.upload_progress.name")] が渡されていない場合や存在しない場合は、アップロードの進捗を記録しません。 デフォルトは "PHP_SESSION_UPLOAD_PROGRESS" です。
session.upload_progress.freq mixed
アップロードの進捗を更新する頻度を定義します。 バイト数 (100 バイトごとに進捗を更新するなど) あるいはパーセンテージ (ファイル全体のサイズの 1% ごとに進捗を更新するなど) で指定できます。 デフォルトは "1%" です。
session.upload_progress.min_freq int
更新間隔の最小値。単位は秒。 デフォルトは "1" (1 秒) です。
session.lazy_write bool
session.lazy_write を 1 に設定すると、 セッションのデータが変更されたときにだけ再書き込みを行います。 デフォルトは 1 で、この機能は有効になっています。

アップロードの進捗は、 session.upload_progress.enabled を有効にして $_POST[ini_get("session.upload_progress.name")] を設定するまでは登録されません。 この機能の詳細は セッションのアップロードの進捗 を参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SID (string)
"name=ID" 形式でセッション名とセッション ID を格納している定数。 セッション ID がセッションクッキーに適切にセットされている場合には空文字列が入る。 これは session_id() が返す ID と同一になる。
PHP_SESSION_DISABLED (int)
セッションが無効な場合の session_status() の戻り値。
PHP_SESSION_NONE (int)
セッションが有効だけれどもセッションが存在しない場合の session_status() の戻り値。
PHP_SESSION_ACTIVE (int)
セッションが有効で、かつセッションが存在する場合の session_status() の戻り値。


  • ≪ 定義済み定数
  • 基本的な使用法 ≫
  • PHP Manual
  • Sessions
  • 例

例

目次

  • 基本的な使用法
  • セッションIDの受渡し
  • カスタムセッションハンドラ


基本的な使用法

セッションは、シンプルな方法で個々のユーザーのデータを格納する仕組みで、 個々のユーザーに対して一意なセッション ID を用意します。 これを用いて、複数ページにまたがるリクエストの間で状態の情報を永続させることができます。 セッション ID をブラウザに送信するときには、通常はセッションクッキーを利用します。 また、その ID を使って既存のセッションデータを取得します。 その ID やセッションクッキーが存在しなければ PHP に対して新たなセッションを作るよう伝え、 新たなセッション ID を生成します。

セッションの処理の流れは単純です。セッションを開始すると、 PHP はまず、(通常はセッションクッキーから受け取る) ID を使って既存のセッションを取得しようとします。 ID を受け取らなかった場合は新しいセッションを作成します。 セッションを開始すると、PHP はスーパーグローバル $_SESSION にすべてのセッションデータを格納します。PHP スクリプトの処理が終了するときには、 スーパーグローバル $_SESSION の中身を自動的に受け取ってシリアライズし、 ストレージに送信します。この一連の操作にはセッション保存ハンドラを使います。

デフォルトでは、PHP が使う保存ハンドラは files です。これは session.save_handler で設定します。 このハンドラは、サーバー上の session.save_path で指定した場所にセッションデータを保存します。

セッションを手動で開始するには session_start() 関数を使います。 session.auto_start に 1 を設定している場合は、 リクエストの開始時に自動的にセッションを開始します。

通常は、PHP がスクリプトの処理を終了するときに、セッションは自動的に終了します。 手動でセッションを終了させるには session_write_close() 関数を使います。

例1 $_SESSIONで変数を登録

<?php
session_start();
if (!isset($_SESSION['count'])) {
$_SESSION['count'] = 0;
} else {
$_SESSION['count']++;
}
?>

例2 変数を $_SESSION から削除する

<?php
session_start();
unset($_SESSION['count']);
?>

警告

unset($_SESSION)によって 全ての$_SESSIONを初期化してはいけません。 $_SESSIONスーパーグローバル変数を用いた セッション変数の登録ができなくなってしまうからです。

警告

セッション変数において参照を使用することはできません。 他の変数への参照を復元する方法がないからです。

注意:

ファイルベースのセッション (PHP のデフォルト) は、 session_start() でオープンしたり session.auto_start で暗黙のうちに開始したりしたセッションのセッションファイルをロックします。 いったんロックがかかったら、そのスクリプトが終了するなり session_write_close() を呼んでセッションを閉じるなりしない限り、 他のスクリプトからはそのセッションファイルにアクセスできません。

これは、たとえば AJAX を使いまくっていて同時に複数のリクエストが発生したりするウェブサイトで問題になります。 この問題への対処方法として一番お手軽なのは、セッションに対して必要な変更が終わったらすぐに session_write_close() を呼ぶことです。スクリプトの最初のほうで呼ぶほうが好ましいでしょう。 あるいは、ファイルではなく別のバックエンド (同時アクセスに対応しているもの) を使うという手もあります。


セッションIDの受渡し

セッションIDの通知を行うためには次の二つの方法があります。

  • Cookies
  • URLパラメータ

sessionモジュールは、両方の方法をサポートします。 Cookieは最適ですが、(クライアントがCookieを受け入れない可能性が あるため)信頼性がなく、これに依存することができません。2番目の方 法は、セッションIDを直接URLに埋め込みます。

PHPには、透過的にリンクを変換する機能を有しています。 この実行時オプション session.use_trans_sidが有効な場合、 相対URIは自動的にセッションIDを含むように変換されます。

注意:

arg_separator.output php.ini ディレクティブにより、引数セパレータをカスタマイズする ことができます。XHTMLに完全準拠するためには、ここに &amp; を指定してください。

もしくは、セッションが開始している場合に定義されている定数 SID を使用することもできます。クライアントが適当な セッションクッキーを送信しなかった場合、この定数は session_name=session_id の形式となります。 他方、送信された場合には、この定数は空の文字列に展開されます。 このため、この定数を無条件に URL に埋め込むことができます。

次の例は、変数の登録法および SID を用いて他のページに正しくリンクする方法のデモです。

例1 単一のユーザーに関するヒット数を数える

<?php

session_start();

if (empty($_SESSION['count'])) {
$_SESSION['count'] = 1;
} else {
$_SESSION['count']++;
}
?>

<p>
こんにちは、あなたがこのページに来たのは <?php echo $_SESSION['count']; ?> 回目ですね。
</p>

<p>
続けるには、<a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">ここをクリック</A>
してください。
</p>

XSSに関係する攻撃を防止するためにSIDを出力する際に、 htmlspecialchars()を使用します。

PHPをコンパイルする際に --enable-trans-sid を使用した場合、 上の例のように SID を出力する必要はありません。

注意:

相対URLでないURLは外部サイトを指していると仮定され、SID が追加されません。これは、SID を外部のサーバーに開示することはセキュリティ上のリスクとなる可能性があるためです。


カスタムセッションハンドラ

セッション情報をデータベースに保存する機能か他の保存法を実装するには、 一連のユーザーレベルの保存関数を作成し、 session_set_save_handler()を使用する必要があります。 SessionHandlerInterface を使ったり、SessionHandler を継承して PHP の内部セッションハンドラを拡張したりしてセッションハンドラを作成できます。

session_set_save_handler() で指定したコールバックメソッドが、 セッションのライフサイクル内で PHP からコールされます。 セッションの open、read、write、 close、そしてセッションの削除 (destroy) や定期的なガベージコレクション (gc) などのときです。

したがって、PHP では常にセッション保存ハンドラが必要となります。デフォルトは、通常はファイルベースの保存ハンドラです。 自作の保存ハンドラは session_set_save_handler() で設定できます。 内部的な保存ハンドラとして、デフォルト以外のものも PHP の拡張モジュールとして用意されています。 sqlite や memcache そして memcached などで、これらは session.save_handler で設定できます。

セッションが開始するときに、PHP は内部的に open ハンドラをコールします。 それに続けて read コールバックを実行し、 このコールバックがエンコードされた文字列を返します。これは最初にセッションストレージに渡されたものと同じ形式になります。 read コールバックがエンコードした文字列を返したら、 PHP がそれをデコードしてデコード後の配列をスーパーグローバル $_SESSION に格納します。

PHP のスクリプトが終了するとき (あるいは session_write_close() がコールされたとき) には、 PHP が内部的にスーパーグローバル $_SESSION をエンコードします。 そして、それをセッション ID とともに write コールバックに渡します。 write コールバックが終了すると、PHP は内部的に close コールバックハンドラを実行します。

セッションが明確に破棄されたときには、PHP は destroy ハンドラをセッション ID つきでコールします。

PHP はときどき gc コールバックを実行し、 設定されているセッション有効期限にもとづいて期限切れのセッションレコードを無効化します。 この処理では、最後にアクセスされてからの時間が $lifetime を超えているすべてのレコードを永続ストレージから削除しなければなりません。


セッションのアップロード状況

INI オプション session.upload_progress.enabled を有効にすると、アップロード中の個々のファイルの進捗状況を PHP で追えるようになります。 この情報は、アップロードのリクエスト自体にとっては特に有用ではありませんが、 ファイルのアップロード中にアプリケーションから別のエンドポイントに POST リクエストを (XHR などで) 送って状態をチェックできるようになります。

アップロードの状況は、アップロードの処理中にスーパーグローバル $_SESSION で取得できます。また、 INI オプション session.upload_progress.name で設定した名前でも POST されます。PHP 側では、この POST リクエストを検出すると $_SESSION 内の配列に値を格納します。配列のインデックスは、INI オプション session.upload_progress.prefix と session.upload_progress.name の値をつなげたものです。つまり、これらの INI 設定を読んで次のようにキーを取得することになります。

<?php
$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);
?>

現在進行中のファイルアップロードをキャンセルすることもできます。 キャンセルするには、$_SESSION[$key]["cancel_upload"] に true を設定します。複数のファイルをひとつのリクエストでアップロードしている場合は、 これでキャンセルできるのは現在進行中のアップロードとそれ以降にアップロードする予定だったファイルだけです。 既にアップロードが完了したファイルは削除されません。この方法でアップロードをキャンセルした場合、 $_FILES 配列のキー error に UPLOAD_ERR_EXTENSION が設定されます。

INI オプション session.upload_progress.freq および session.upload_progress.min_freq で、アップロードの進捗状況を再計算する頻度を制御します。 これらを適切に設定すれば、進捗状況の取得によるオーバーヘッドはほぼ無視できる程度になります。

例1 情報の例

アップロード進捗状況の配列の構造を示す例です。

<form action="upload.php" method="POST" enctype="multipart/form-data">
 <input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
 <input type="file" name="file1" />
 <input type="file" name="file2" />
 <input type="submit" />
</form>

セッションに格納されるデータは、このようになります。

<?php
$_SESSION["upload_progress_123"] = array(
"start_time" => 1234567890, // リクエストされた時刻
"content_length" => 57343257, // POST されたコンテンツの長さ
"bytes_processed" => 453489, // 受信して処理済みのバイト数
"done" => false, // POST ハンドラが (正常かどうかにかかわらず) 完了した場合に true
"files" => array(
0 => array(
"field_name" => "file1", // <input/> フィールドの name
// 次の 3 つの要素は $_FILES と同じ内容です
"name" => "foo.avi",
"tmp_name" => "/tmp/phpxxxxxx",
"error" => 0,
"done" => true, // POST ハンドラがこのファイルの処理を終えたときに true
"start_time" => 1234567890, // このファイルの処理が始まった時刻
"bytes_processed" => 57343250, // このファイルにおける、受信して処理済みのバイト数
),
// 同じリクエスト内で、まだアップロードが完了していない別のファイル
1 => array(
"field_name" => "file2",
"name" => "bar.avi",
"tmp_name" => NULL,
"error" => 0,
"done" => false,
"start_time" => 1234567899,
"bytes_processed" => 54554,
),
)
);

警告

ウェブサーバーのリクエストバッファリングを無効にしておかないと、うまく動作しません。 リクエストバッファリングが有効になっていると、PHP 側ではアップロードが完全に終わるまでアップロードされたことがわかりません。 たとえば Nginx などのサーバーは、大きなリクエストをバッファリングするようになっています。

警告

アップロード状況の情報は、あらゆるスクリプトを実行する前に、セッションに書き込まれます。 よって、セッション名を ini_set() 関数や session_name() 関数で変更してしまうと、 アップロード状況の情報が欠落したセッションが提供されることになります。


セッション と セキュリティ

目次

  • セッション管理の基礎
  • セッションに関連する INI 設定をセキュアにする

外部リンク: » Session fixation

HTTP におけるセッション管理は、web セキュリティのコアに相当します。 セッションがセキュアであることを保証するために、 全てのとりうる軽減策を採用すべきです。 開発者はまた、適用可能なセキュリティ対策を 有効/実行 すべきです。


セッション管理の基礎

セッションのセキュリティ

セッションモジュールは、セッションに保存された情報を 作成したユーザーだけが見られることを保証できません。 セッションに紐付けられた値によっては、 セッションの機密性を守るために追加の対策が必要です。

セッションに保存されているデータがどれくらい重要かを評価し、 さらなる防御策を展開すべきかもしれません。 通常、そうしてしまうとコストが高く付きます。 たとえば、ユーザーの利便性を損なうことが挙げられます。 たとえば、ユーザーを単純なソーシャルエンジニアリングから守るためには、 session.use_only_cookies を有効にする必要があります。 この場合、クッキーを無条件にクライアント側でも有効にしなければなりません。 さもないとセッションが動作しないからです。

既存のセッションIDをサードパーティに漏らす方法は複数あります。 JavaScriptインジェクション、セッションID を URL に埋め込む方法、 パケット盗聴、デバイスへの物理アクセス、などです。 セッションIDが漏れてしまうと、 サードパーティがその特定のIDに紐付けられた全てのリソースに アクセスできるようになってしまいます。 既存のセッションIDを漏らす最初の方法は、URL でセッションIDを持ち回すやり方です。 もし外部サイトやリソースへのリンクが存在したとすると、 セッションIDを含むURLが、外部サイトのリファラログに保存されるかもしれません。 ふたつめは、より積極的な攻撃者がネットワークトラフィックを盗聴しているかもしれません。 ネットワークトラフィックが暗号化されていないと、 セッションIDがネットワーク越しにプレーンテキスト内に流出してしまいます。 防御策は、SSL/TLS をサーバー側で実装し、ユーザーがそれを使うように強制することです。 HSTS も、セキュリティを向上させるために使えるはずです。

注意: HTTPS でさえも、あらゆる時に機密データを保護することはできません。 たとえば、CRIME や Beast 脆弱性が、攻撃者にデータを読めるようにしてしまうかもしれません。 また、多くのネットワークは HTTPS の MITMプロキシ を監査の目的で採用しています。 攻撃者も、そうしたプロキシをセットアップしているかもしれません。

セッションアダプションを防ぐためのセッション管理

PHP のセッションマネージャーは、 現状ではデフォルトでセッションアダプション攻撃が可能です。 アダプション攻撃が可能なセッションマネージャーは、 追加のリスクを背負うことになります。

session.use_strict_modeを有効にし、かつセッションの保存ハンドラがサポートしている場合、 初期化されていないセッションIDは拒否され、新しいものが作成されます。 これによって、攻撃者がユーザーに既知のセッションIDを強制的に使わせることを防止できます。 攻撃者はセッションID付きのリンクをペーストしたり、 そうしたリンクを含んだメールを送るかもしれません。 たとえば http://example.com/page.php?PHPSESSID=123456789 のようなものです。 session.use_trans_sid が有効な場合、 ユーザーは攻撃者が提供したセッションIDを使ってセッションを開始してしまいます。 session.use_strict_mode は、 こうしたリスクを軽減します。

警告

ユーザー定義の保存ハンドラも、セッションIDの検証を行うことで 厳格なセッションモードをサポートできます。 保存ハンドラを定義した全てのユーザーは、セッションIDの検証を実装すべきです。

セッションIDクッキーは、domain, path, httponly, secure, そして PHP 7.3 以降では、SameSite 属性とともに設定できます。 これは、ブラウザで定義されたものが優先します。 この優先される仕組みを使い、攻撃者は永久に使えるセッションIDを設定できてしまいます。 session.use_only_cookies はこの問題を解決できません。 session.use_strict_mode を使うとこのリスクを軽減できます。 session.use_strict_mode=On にすると、 初期化されていないセッションIDは拒否されます。

注意: session.use_strict_mode はアダプション可能なセッション管理機構のリスクを軽減しますが、 攻撃者は自らが生成したセッションIDを、 初期化済みセッションIDとして使わせることが出来てしまいます。 たとえば JavaScriptインジェクション攻撃です。 この攻撃はこのマニュアルで推奨する方法で軽減できます。 このマニュアルに従い、開発者は session.use_strict_mode を有効にし、タイムスタンプベースのセッション管理を行い、 推奨する手続きを使って session_regenerate_id() を使い セッションIDの再生成を行うべきです。 開発者が上記全てに従えば、攻撃者が生成したセッションIDは、結局は削除されます。 有効期限が切れたセッションにアクセスされたときのために、 開発者は全てのアクティブなユーザーのセッションデータを保存すべきです。 この情報は後に行われる調査とも関係があります。 ユーザーは全てのセッションから強制的にログアウトさせられるべきです。 つまり、再認証させるべきです。 こうすることで、攻撃者が盗まれたセッションを悪用することを防止できます。

警告

有効期限が切れたセッションにアクセスすることが、 必ずしも攻撃であることを示しているとは限りません。 不安定なネットワークや、 アクティブなセッションをすぐに削除してしまったりすることが原因で、 正当なユーザーが、有効期限が切れたセッションにアクセスすることがあるからです。

PHP 7.1.0 以降、session_create_id() が追加されました。 この関数は、セッションIDの前にユーザー定義のIDをつけることで、 全てのアクティブなユーザーのセッションに効率的にアクセスできます。 session.use_strict_mode を有効にすることが重要です。有効にしないと、 悪意のあるユーザーが悪意のあるセッションIDを他のユーザーに設定できてしまいます。

注意: PHP 7.1.0 より前のバージョンのユーザーは新しいセッションIDを生成する のに CSPRNG、 つまり /dev/urandom や random_bytes() やハッシュ関数を使うべき です。 session_create_id() には衝突を検出する機能があり、 セッションの INI 設定に従ってセッションIDを生成します。 session_create_id() の利用が好ましいです。

セッションID の再生成

session.use_strict_mode は良い軽減策ですが、十分ではありません。開発者はセッションのセキュリティのために session_regenerate_id() を同時に使うべきです。

セッションIDを再生成すると、盗まれたセッションIDを使われるリスクが減らせるので、 session_regenerate_id() 関数は定期的に呼び出されなければなりません。 たとえば、セキュリティに敏感な内容を扱っているのなら、 セッションIDを15分毎に再生成するようにしてください。 セッションID が盗まれた場合でも、正当なユーザーと攻撃者のセッションは両方時間切れになります。 言い換えれば、ユーザーだろうと攻撃者のアクセスだろうと、 期限切れのセッションにアクセスしたとしてエラーになるのです。

セッションID はユーザーの権限が上昇したときは再生成されなければ なりません。 たとえば認証が成功した後などです。 session_regenerate_id() は、 認証情報を $_SESSION に設定する前に必ずコールされなければなりません。 (session_regenerate_id() は タイムスタンプなどを保存するために、現在のセッションにセッションデータを自動的に保存します) 必ず新しいセッションだけに、認証済みのフラグが含まれるようにしてください。

開発者は session.gc_maxlifetime によるセッションの期限切れに依存しては いけません。 攻撃者は、認証済みのセッションも含めて、期限切れを防いで悪用を続けるため、 ターゲットのセッションIDに定期的にアクセスしている可能性があるからです。

そのかわりに、開発者はタイムスタンプベースのセッション管理を実装しなければなりません。

警告

セッションマネージャーはタイムスタンプを透過的に管理できますが、 この機能はまだ実装されていません。 古いセッションデータは GC されるまで保持されなければなりません。 同時に、開発者は期限切れになったセッションデータが削除されることを保証しなければなりません。 たとえば、session_regenerate_id(true); と session_destroy() をアクティブなセッションに対して同時に呼んでは絶対にいけません。 これは矛盾したように聞こえますが、これは必須条件です。

session_regenerate_id() は、 デフォルトで期限切れのセッションを削除 しません。 期限切れの認証済みのセッションが存在するかもしれません。 開発者は期限切れのセッションは、誰からも消費されないようにしなければなりません。 期限切れのセッションデータへのアクセスを、タイムスタンプを使うことで禁止すべきです。

警告

アクティブなセッションを突然削除すると、望まない副作用が起きます。 Webアプリケーションへの同時接続が起きた かつ/または ネットワークが不安定な場合に、セッションが突然消える可能性があります。

アクティブなセッションが突然消えてしまうと、 悪意のあるアクセスの可能性を検出することができなくなります。

期限切れのセッションを突然削除するのではなく、 開発者は短い期限切れの時間(タイムスタンプ)を $_SESSION に設定し、セッションデータにアクセスすることを自分で禁止すべきです。

開発者は session_regenerate_id() を呼び出した後すぐに、 古いセッションデータへのアクセスを禁止してはいけません。 その後の段階で禁止しなければなりません。 たとえば、有線ネットワークのような安定したネットワークは数秒後、 無線LAN や携帯電話のような不安定なネットワークの場合は、2, 3分後です。

ユーザーのアクセスが期限切れのセッションだった場合、 アクセスを拒否するべきです。攻撃されている可能性があるすべてのユーザーから、 認証済みのステータスを削除することも推奨します。

session.use_only_cookies と session_regenerate_id() を適切に使うことで、 攻撃者によって設定された、削除できないクッキーを伴うDOSが発生することがあります。 この場合、開発者はユーザーに Cookie を削除させ、 セキュリティ上の問題に晒されていることを教えることができます。 攻撃者は、脆弱なWebアプリケーションや ウイルスに感染したブラウザのプラグイン、 物理的に侵害されたデバイスなどを経由して悪意のあるCookieを設定している可能性があります。

警告

DOS のリスクを誤解しないでください。 session.use_strict_mode=On は一般的なセッションIDのセキュリティには必須です! 全てのサイトが session.use_strict_mode を有効にすることをお勧めします。

DOS はアカウントが攻撃されている場合にだけ発生する可能性があります。 アプリケーションに存在する JavaScript インジェクションの脆弱性がもっともよくある原因です。

セッションデータを削除する

期限切れのセッションデータは、アクセス不能にし、削除しなければなりません。 現状のセッションモジュールはこの機能をうまく扱えません。

期限切れのセッションデータは、できるだけ早く削除すべきです。 しかしながら、アクティブなセッションは、すぐに削除してはいけません。 これらの要求を満たすためには、 開発者はタイムスタンプベースのセッション管理を自分自身で実装する必要があります。

期限切れのタイムスタンプを $_SESSION に設定し、管理します。 期限切れのセッションデータへのアクセスは禁止します。 期限切れのセッションデータへのアクセスが検出された場合、 そのユーザーのセッションから認証済みのステータスを全て取り除き、 強制的に再認証させることをおすすめします。 期限切れのセッションデータへのアクセスは、攻撃されている可能性があります。 これを実現するために、 開発者はユーザーごとに全てのアクティブなセッションを追跡しなければなりません。

注意: 期限切れのセッションへのアクセスは、ネットワークが不安定だったり、 Webサイトへの同時アクセスも原因で起こりえます。 たとえば、サーバーは新しいセッションIDを Cookie 経由で設定しようとしたが、 接続が失われたため Set-Cookie のパケットが クライアントに届かなかったりする可能性があります。 ある接続で、session_regenerate_id() によって新しいセッションIDが発行されたけれども、 別の同時接続が、まだ新しいセッションIDを受け取っていない可能性もあります。 よって、開発者は期限切れのセッションへのアクセスを後の段階で禁止しなければなりません。 すなわち、タイムスタンプベースのセッション管理が必須なのです。

まとめると、セッションデータは session_regenerate_id() や session_destroy() を使って破棄してはいけません。 むしろ、セッションデータへのアクセスを制御するためにタイムスタンプを使わなければなりません。 session_gc() 関数に、 セッションデータストレージから、期限切れのデータを削除させましょう。

Session とロック

セッションデータはレースコンディションを避けるため、デフォルトでロックされます。 ロックを掛けることは複数のリクエスト間でセッションデータの一貫性を保つため、必須です。

しかしながら、セッションをロックしてしまうと、 攻撃者がDOS攻撃に悪用する可能性があります。 セッションをロックすることによるDOS攻撃のリスクを軽減するためには、 ロックを最小限にすることです。 セッションデータを更新する必要がないときは、読み取り専用のセッションを使うようにします。 session_start(['read_and_close'=>1]); $_SESSION を更新した後は、session_commit() を使って できるだけ早くセッションを閉じるようにします。

現状のセッションモジュールは、 セッションがアクティブでない時に $_SESSION が変更されたかを検知 しません。 セッションがアクティブでない時に $_SESSION を変更しないことは、開発者の責任です。

アクティブなセッション

開発者は、ユーザーごとにアクティブなセッションを追跡し続けるべきです。 そして、アクティブなセッションの数がどれくらいあるかや、 どのIP(や地域) からかとか、どのくらいの期間アクティブなのか、などです。 PHP はこれらを追跡しません。開発者が行うことが想定されています。

これを実装するやり方はたくさんあります。 ひとつの可能な実装は、データベースをセットアップして必須のデータを追跡し、 関連するあらゆる情報を保存することです。 セッションデータは GC されるので、開発者はアクティブなセッションのデータベースが一貫性を保つように GC されたデータに注意を払わなければなりません。

一番簡単な実装は、"ユーザーIDをセッションIDの前に付ける" ことで、 必須の情報を $_SESSION に保存することです。 多くのデータベースは文字列の prefix を選択するのに良いパフォーマンスを発揮します。 開発者は session_regenerate_id() と session_create_id() をこの目的で使うこともできます。

警告

秘密のデータを prefix に絶対に使わないでください。 ユーザーIDが秘密の場合、hash_hmac() を使うことも検討しましょう。

警告

session.use_strict_mode はこの場合に必須です。必ず有効にするようにしてください。 そうしなければ、アクティブなセッションデータベースが侵害される可能性があります。

タイムスタンプベースのセッション管理は、時間切れのセッションへのアクセスを検知するのに必須です。 時間切れのセッションへのアクセスが検知された場合、 そのユーザーの全てのアクティブなセッションから認証済みのフラグを削除すべきです。 こうすることで、攻撃者が盗んだセッションを悪用し続けることを防げます。

Session と自動ログイン

開発者は有効期間が長いセッションを、自動ログインに使ってはいけません。 なぜなら、セッションが盗まれるリスクが増えるからです。 自動ログイン機能は、開発者が実装すべきです。

setcookie() を使い、 セキュアなワンタイムハッシュを自動ログインのキーとして使います。 SHA-2 より強いセキュアなハッシュを使います。 たとえば、 random_bytes() や /dev/urandom で生成したランダムデータを SHA-256 またはそれより強いハッシュ関数と一緒に使います。

ユーザーが認証されていなかったら、ワンタイムの自動ログインキーが有効かどうかをチェックします。 もし、キーが正しければ、ユーザーを認証し、新しいセキュアなワンタイムハッシュキーを設定します。 自動ログインキーを使うのは一度きりです。つまり、再利用してはいけません。 常に新しいものを生成するようにします。

自動ログインのキーが長期間有効な認証キーである場合、 できるだけ手厚く保護すべきです。 path/httponly/secure/SameSite クッキー属性をセキュアにするために使います。 つまり、自動ログインキーを必要ないのに送信しないでください。

開発者は自動ログインを無効にする機能や、 不要な自動ログインのキーを削除する機能を実装しなければなりません。

CSRF (Cross-Site Request Forgeries) 攻撃

セッションと認証は、CSRF 攻撃を防ぐことはありません。 開発者は CSRF への防御を自分で実装しなければなりません。

CSRF 攻撃を防ぐために、 output_add_rewrite_var() 関数が使えます。 詳細はマニュアルページを参照ください。

注意: PHP 7.2.0 より前のバージョンでは、この関数は trans sid と同じ出力バッファとINI 設定を使っていました。 よって、PHP 7.2.0 より前のバージョンで output_add_rewrite_var() を使うことはおすすめしません。

ほとんどの Webアプリケーションフレームワークは、CSRF から防御する機能をサポートしています。 詳細は、Webアプリケーションフレームワークのマニュアルを参照ください。

PHP 7.3 以降では、セッションクッキーにSameSite 属性が設定できます。 この属性も、CSRF 脆弱性を軽減できる追加の対策になります。


セッションに関連する INI 設定をセキュアにする

セッション関連のINI設定をセキュアにすることで、 開発者はセッションのセキュリティを改善できます。 重要な INI 設定であっても、推奨される設定がないものがあります。 開発者にはセッションの設定を強固にする責任があります。

  • session.cookie_lifetime=0

    0 には特別な意味があります。 これは、恒久的なストレージにクッキーを保存しないようブラウザに指示します。 よって、ブラウザが終了した場合、セッションIDクッキーはすぐに削除されます。 開発者がこの値を0以外にすると、他のユーザーがセッションIDを使うことを許す可能性があります。 このため、ほとんどのWebアプリケーションは、"0" を使うべきです。

    自動ログイン機能が必須の場合、 開発者は自前のセキュアな自動ログイン機能を実装しなければなりません。 この機能のために、有効期間が長いセッションIDを使ってはいけません。 前のページの関連するセクションで、より多くの情報が見つかるかもしれません。

  • session.use_cookies=On

    session.use_only_cookies=On

    HTTP クッキーはいくつか問題を抱えていますが、 クッキーはセッションIDを管理する手段として好ましい方法であり続けています。 セッションIDの管理に、可能であればクッキーだけを使うようにしましょう。 ほとんどのアプリケーションはセッションIDの管理にクッキーを使うべきです。

    session.use_only_cookies=Off の場合、 セッションモジュールは、たとえセッションIDクッキーが未初期化であっても、 セッションIDが与えられた GET や POST によって設定されたものをセッションIDに使うようになります。

  • session.use_strict_mode=On

    セッションをセキュアにするために session.use_strict_mode を有効にすることは必須ですが、 デフォルトでは無効になっています。

    有効にすることで、セッションモジュールが未初期化のセッションIDを使うことを防げます。 別の言い方をすると、セッションモジュールは、 セッションモジュールが生成した有効なセッションIDだけを受け入れるようになるということです。 この設定は、ユーザーによって与えられたあらゆるセッションIDを拒否します。

    Cookie の仕様によって、 攻撃者はローカルにクッキーのデータベースを設定したり、 JavaScriptインジェクションの脆弱性を突くことで、 削除できないセッションIDクッキーを置くことが可能です。 session.use_strict_mode によって、 攻撃者が初期化したセッションIDが使われるのを防ぐことができます。

    注意:

    攻撃者は自分のデバイスでセッションIDを初期化し、 ターゲットユーザーのセッションIDを設定するかもしれません。 攻撃者は悪用するセッションIDをアクティブな状態に保たなければなりません。 攻撃者はこのシナリオで攻撃を実行するには追加のステップが必要です。 よって、session.use_strict_mode が軽減策として役に立つのです。

  • session.cookie_httponly=On

    セッションクッキーを JavaScript からアクセスさせることを拒否します。 この設定によって、JavaScriptインジェクションによってクッキーを盗むことを防げます。

    セッションIDをCSRFトークンとして使うことも可能ですが、 推奨されません。たとえば、HTMLソースが保存され、他のユーザに送られることがあるからです。 開発者は、セキュリティを向上させるため、セッションIDをWebサイトに出力すべきではありません。 ほとんどのアプリケーションは、httponly 属性をセッションIDクッキーに設定しなければなりません。

    注意:

    CSRF トークンも、セッションIDと同じように定期的に更新すべきです。

  • session.cookie_secure=On

    セッションIDクッキーを、プロトコルがHTTPSの場合にだけアクセスすることを許可します。 website が HTTPS 経由でのみアクセス可能であるなら、この設定を有効にすべきです。

    HTTPS 経由でのみアクセス可能なWebサイト向けに、HSTS も検討すべきです。

  • session.cookie_samesite="Lax" または session.cookie_samesite="Strict"

    PHP 7.3 以降では、セッションIDクッキー向けに "SameSite" 属性が設定できます。 この属性は、CSRF (Cross Site Request Forgery) 攻撃を軽減する手段です。

    Lax と Strict の違いは、 HTTP GETリクエストを使う別の登録可能なドメインへのリクエストに対して、クッキーへのアクセスを許可するかどうかです。 Lax を使っているクッキーは別の登録可能なドメインへのGETリクエストからアクセス可能ですが、 Strict を使っているクッキーはそうではありません。

  • session.gc_maxlifetime=[choose smallest possible]

    session.gc_maxlifetime は期限切れのセッションIDを削除する設定です。 この設定に依存することは推奨しません。 開発者はタイムスタンプを使って、セッションの有効期間を自前で管理すべきです。

    セッションGC(ガベージコレクション)は、 session_gc() を使って行うのが最適です。 session_gc() 関数は、タスクマネージャーを使って実行すべきです。 たとえば、UNIXライクなシステムだと cron が挙げられます。

    GC処理はデフォルトでは確率的に行われます。 この設定は期限切れのセッションが削除されることを保証 しません。 開発者はこの設定に依存することはできませんが、 可能な限り最小の値を指定することを推奨します。 session.gc_probability と session.gc_divisor の値を、 適切な頻度で期限切れのセッションが削除されるように調整してください。 自動ログイン機能が必須の場合、開発者は自前のセキュアな自動ログイン機能を実装しなければなりません。 詳細な情報は前のページを参照ください。 自動ログイン機能のために、有効期限が長いセッションIDを絶対に使わないでください。

    注意:

    セッション保存ハンドラモジュールによっては、 期限切れの処理を確率ベースで行うためにこの設定を使わないものもあります。 たとえば memcached, memcache が挙げられます。 詳細については、セッション保存ハンドラのドキュメントを参照ください。

  • session.use_trans_sid=Off

    透過的なセッションID管理を使うことは禁止されていません。 開発者は必要な場合は採用しても構いません。 しかし、透過的なセッションID管理を無効にすると、 セッションIDインジェクションやリークの可能性が排除できるので、 一般的なセッションIDのセキュリティを改善できます。

    注意:

    セッションIDは、ブックマークされたURLや、電子メールに埋め込まれたURLや、 保存されたHTMLソースなどから漏れる可能性があります。

  • session.trans_sid_tags=[limited tags]

    (PHP 7.1.0 >=) 開発者は必要ないのにHTMLタグを書き換えるべきではありません。 デフォルト値でほとんどの場合は十分です。古いPHPバージョンの場合は、 url_rewriter.tags を代わりに使ってください。

  • session.trans_sid_hosts=[limited hosts]

    (PHP 7.1.0 >=) この INI 設定は、 trans sid の書き換えを許可するホストをホワイトリスト形式で定義します。 信頼できないホストを絶対に追加しないでください。 セッションモジュールは、この設定が空の場合、 $_SERVER['HTTP_HOST'] だけを許可します。

  • session.referer_check=[originating URL]

    session.use_trans_sid が有効になっている場合、 この設定はセッションIDインジェクションのリスクを減らします。 website が http://example.com/ の場合、 http://example.com/ を設定してください。 HTTPS ブラウザはリファラヘッダを送信しないことに注意してください。 ブラウザはリファラヘッダを設定によって送信しない可能性もあります。 よって、この設定は信頼できるセキュリティ対策ではありませんが、 この設定を使うことは推奨します。

  • session.cache_limiter=nocache

    HTTP コンテンツを認証済みのセッションに関してはキャッシュしないようにします。 コンテンツがプライベートでない場合だけ、キャッシュを許可します。 そうしない場合、コンテンツが外部に流出する可能性があります。 "private" は、HTTPコンテンツがセキュリティに敏感なデータを含まない場合であれば採用しても構いません。 "private" は、 共有されたクライアントによってキャッシュされた、 プライベートなデータを送信する可能性があることに注意してください。 "public" は、 HTTPコンテンツがプライベートなデータを一切含んでいない場合にのみ使わなければなりません。

  • session.sid_length="48"

    (PHP 7.1.0 >=) 長いセッションIDであればあるほど、強いセッションIDになります。 開発者はセッションIDの長さを32文字以上にすることを検討すべきです。 session.sid_bits_per_character="5" の場合、 少なくとも 26文字以上が必須です。

  • session.sid_bits_per_character="6"

    (PHP 7.1.0 >=) セッションIDの文字に多くのbitを使うほど、 セッションモジュールが生成するセッションIDは、 長さが同じであっても強くなります。

  • session.hash_function="sha256"

    (PHP 7.1.0 <) より強いハッシュ関数は、より強いセッションIDを生成します。 ハッシュの衝突が起こる可能性は、MD5 ハッシュアルゴリズムを使っても低いですが、 開発者は SHA2 またはそれより強い sha384 や sha512 のようなハッシュアルゴリズムを使うべきです。 開発者は、十分に長い entropy をハッシュ関数を使うときに必ず与えなければなりません。

  • session.save_path=[どこからでも読み取り可能なディレクトリにしない]

    この設定を /tmp (デフォルト) のようにどこか らでも読み込み可能なディレクトリに設定した場合、サーバー上 の他のユーザーがこのディレクトリのファイルのリストを取得すること により、セッションをハイジャックをすることが可能となります。


セッション関数

目次

  • session_abort — session 配列の変更を破棄してセッションを終了します
  • session_cache_expire — 現在のキャッシュの有効期限を取得/設定する
  • session_cache_limiter — 現在のキャッシュリミッタを取得または設定する
  • session_commit — session_write_close のエイリアス
  • session_create_id — 新しいセッションIDを作成する
  • session_decode — セッションエンコードされた文字列からセッションデータをデコードする
  • session_destroy — セッションに登録されたデータを全て破棄する
  • session_encode — 現在のセッションデータを、セッションエンコードされた文字列に変換する
  • session_gc — セッションデータのガベージコレクションを実行する
  • session_get_cookie_params — セッションクッキーのパラメータを得る
  • session_id — 現在のセッション ID を取得または設定する
  • session_module_name — 現在のセッションモジュールを取得または設定する
  • session_name — 現在のセッション名を取得または設定する
  • session_regenerate_id — 現在のセッションIDを新しく生成したものと置き換える
  • session_register_shutdown — セッションのシャットダウン関数
  • session_reset — session 配列を元の値で再初期化します
  • session_save_path — 現在のセッションデータ保存パスを取得または設定する
  • session_set_cookie_params — セッションクッキーパラメータを設定する
  • session_set_save_handler — ユーザー定義のセッション保存関数を設定する
  • session_start — 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_status — 現在のセッションの状態を返す
  • session_unset — 全てのセッション変数を開放する
  • session_write_close — セッションデータを書き込んでセッションを終了する


session 配列の変更を破棄してセッションを終了します

  • ≪ セッション関数
  • session_cache_expire ≫
  • PHP Manual
  • セッション関数
  • session 配列の変更を破棄してセッションを終了します

session_abort

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

session_abort — session 配列の変更を破棄してセッションを終了します

説明

session_abort(): bool

session_abort() は、データを保存せずにセッションを終了します。 したがって、セッション・データの元の値が保持されます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | この関数の戻り値の型は bool になりました。 以前は void でした。

参考

  • $_SESSION
  • session.auto_start 構成ディレクティブ
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_reset() - session 配列を元の値で再初期化します
  • session_commit() - session_write_close のエイリアス


現在のキャッシュの有効期限を取得/設定する

  • ≪ session_abort
  • session_cache_limiter ≫
  • PHP Manual
  • セッション関数
  • 現在のキャッシュの有効期限を取得/設定する

session_cache_expire

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

session_cache_expire — 現在のキャッシュの有効期限を取得/設定する

説明

session_cache_expire(?int $value = null): int|false

session_cache_expire() は現在の session.cache_expire の設定を返します。

リクエストがあった時点で、キャッシュの有効期限は session.cache_expire で設定されたデフォルト値にリセットされます。 そのため、すべてのリクエストにおいて (そしてsession_start() をコールする前に) session_cache_expire() をコールする必要があります。

パラメータ

value

value が指定され、null でない場合、 現在のキャッシュの有効期限は、 value で置換されます。

注意: session.cache_limiterが nocache 以外の値にセットされている場合にのみ valueが有効となります。

戻り値

session.cache_expire の現在の設定を返します。 戻り値は分単位で、デフォルトは 180 です。 値の変更に失敗した場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | value は、nullable になりました。

例

例1 session_cache_expire() の例

<?php

/* set the cache limiter to 'private' */

session_cache_limiter('private');
$cache_limiter = session_cache_limiter();

/* set the cache expire to 30 minutes */
session_cache_expire(30);
$cache_expire = session_cache_expire();

/* start the session */

session_start();

echo "The cache limiter is now set to $cache_limiter<br />";
echo "The cached session pages expire after $cache_expire minutes";
?>

参考

  • session.cache_expire
  • session.cache_limiter
  • session_cache_limiter() - 現在のキャッシュリミッタを取得または設定する


現在のキャッシュリミッタを取得または設定する

  • ≪ session_cache_expire
  • session_commit ≫
  • PHP Manual
  • セッション関数
  • 現在のキャッシュリミッタを取得または設定する

session_cache_limiter

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

session_cache_limiter — 現在のキャッシュリミッタを取得または設定する

説明

session_cache_limiter(?string $value = null): string|false

session_cache_limiter() は、 現在のキャッシュリミッタの名前を返します。

キャッシュリミッタは、クライアントに送信されるキャッシュ制御用の HTTPヘッダを制御します。これらのヘッダは、ページの内容をクライアントやプロキシがキャッシュ する規則を定義します。例えば、キャッシュリミッタを nocacheに設定した場合、クライアント/プロキシのキャッ シュは無効になります。しかし、publicの場合は、 キャッシュを許可します。privateと設定すること も可能で、この場合、プロキシがキャッシュすることは許可しませんが クライアントがキャッシュすることは許可されます。

privateモードにおいて、Expireヘッダがクライア ントに送信されます。これは、Mozilla のようないくつかのブラウザを混乱させます。これを避けるには、 private_no_expireモードを使用してください。 このモードでは、Expireヘッダはクライアントに送信されません。

キャッシュリミッタを '' にすると、 キャッシュヘッダの自動送信を完全に無効化します。

キャッシュリミッタは、リクエスト開始時に session.cache_limiterに保存されたデフォルト値 にリセットされます。つまり、各リクエスト毎に(アウトプットバッファ が無効な場合は、session_start()がコールされる 前に) session_cache_limiter()をコールする必要 があります。

パラメータ

value

value が指定され、null でない場合、 現在のキャッシュリミッタは新しい値に変更されます。

取り得る値
値 送信されるヘッダ
public
Expires: (未来のいつか、session.cache_expires による)
Cache-Control: public, max-age=(未来のいつか、session.cache_expire による)
Last-Modified: (セッションが最後に保存されたときのタイムスタンプ)
private_no_expire
Cache-Control: private, max-age=(session.cache_expire ぶんだけ未来)
Last-Modified: (セッションが最後に保存されたときのタイムスタンプ)
private
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: private, max-age=(session.cache_expire ぶんだけ未来)
Last-Modified: (セッションが最後に保存されたときのタイムスタンプ)
nocache
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache

戻り値

現在のキャッシュリミッタの名前を返します。 値の変更に失敗した場合は、false を返します。

変更履歴

バージョン | 説明
8.0.0 | value は、nullable になりました。

例

例1 session_cache_limiter() の例

<?php

/* キャッシュリミッタを'private'に設定する */

session_cache_limiter('private');
$cache_limiter = session_cache_limiter();

echo "The cache limiter is now set to $cache_limiter<br />";
?>

参考

  • session.cache_limiter


session_write_close のエイリアス

  • ≪ session_cache_limiter
  • session_create_id ≫
  • PHP Manual
  • セッション関数
  • session_write_close のエイリアス

session_commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

session_commit — session_write_close() のエイリアス

説明

この関数は次の関数のエイリアスです。 session_write_close().


新しいセッションIDを作成する

  • ≪ session_commit
  • session_decode ≫
  • PHP Manual
  • セッション関数
  • 新しいセッションIDを作成する

session_create_id

(PHP 7 >= 7.1.0, PHP 8)

session_create_id — 新しいセッションIDを作成する

説明

session_create_id(string $prefix = ""): string|false

session_create_id() 関数は、 現在のセッションのための新しいセッションIDを作成するのに使われます。 この関数は、衝突しないセッションIDを返します。

セッションがアクティブでなければ、衝突しているかどうかのチェックは省略されます。

php.ini の設定に従って、セッションIDは作成されます。

重要なのは、あなたの Webサーバーが使っているものと同じユーザIDを、 GC タスクのスクリプトで使うことが重要です。 そうしないと、特にファイルの保存ハンドラでパーミッションの問題が起こるかもしれません。

パラメータ

prefix

prefix が指定されると、 新しいセッションIDの前に、 prefix が付きます。 セッションIDに全ての文字が許されているわけではありません。 a-z A-Z 0-9 , (コンマ) そして - (マイナス) が許可されています。 最大の長さは256文字です。

戻り値

session_create_id() 関数は、 現在のセッションのための、衝突しない新しいセッションIDを返します。 セッションがアクティブでない時に使われると、 衝突しているかどうかのチェックは省略されます。 失敗した場合は、false を返します。

例

例1 session_regenerate_id() と一緒に、session_create_id() を使う例

<?php
// タイムスタンプによる管理をサポートした
// 自前のセッション開始関数
function my_session_start() {
session_start();
// 古過ぎるセッションIDを使うことを許してはいけない
if (!empty($_SESSION['deleted_time']) && $_SESSION['deleted_time'] < time() - 180) {
session_destroy();
session_start();
}
}

// 自前のセッションID再生成関数
function my_session_regenerate_id() {
// セッションがアクティブな間は、
// 衝突しないことを確実にするため
// session_create_id() を呼び出す
if (session_status() != PHP_SESSION_ACTIVE) {
session_start();
}
// 警告: 秘密の文字列を prefix に使ってはいけない!
$newid = session_create_id('myprefix-');

// 削除時のタイムスタンプを設定
// セッションデータは、それなりの理由があるので、すぐに削除してはいけない
$_SESSION['deleted_time'] = time();
// セッションを終了する
session_commit();
// ユーザー定義のセッションIDを確実に受け入れるようにする
// 注意: 通常の操作のためには、use_strict_mode は有効でなければならない
ini_set('session.use_strict_mode', 0);
// 新しいカスタムのセッションIDを設定
session_id($newid);
// カスタムのセッションIDでセッションを開始
session_start();
}

// use_strict_mode を確実に有効にする
// use_strict_mode は、セキュリティ上の都合で強制する
ini_set('session.use_strict_mode', 1);
my_session_start();

// セッションID は以下の場合に再生成しなければならない
// - ユーザーのログイン時
// - ユーザーがログアウト時
// - 一定時間経過時
my_session_regenerate_id();

// Write useful codes
?>

参考

  • session_regenerate_id() - 現在のセッションIDを新しく生成したものと置き換える
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session.use_strict_mode
  • SessionHandler::create_sid() - 新規セッション ID を返す


セッションエンコードされた文字列からセッションデータをデコードする

  • ≪ session_create_id
  • session_destroy ≫
  • PHP Manual
  • セッション関数
  • セッションエンコードされた文字列からセッションデータをデコードする

session_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

session_decode — セッションエンコードされた文字列からセッションデータをデコードする

説明

session_decode(string $data): bool

session_decode() は、 $data のセッションデータをデコードし、 スーパーグローバル $_SESSION にその結果を格納します。

デフォルトのアンシリアライズの方法は PHP が内部的に実装しているものであり、 unserialize() とは違います。 シリアライズの方法は、session.serialize_handler で設定できます。

パラメータ

data

エンコードされたデータ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • session_encode() - 現在のセッションデータを、セッションエンコードされた文字列に変換する
  • session.serialize_handler


セッションに登録されたデータを全て破棄する

  • ≪ session_decode
  • session_encode ≫
  • PHP Manual
  • セッション関数
  • セッションに登録されたデータを全て破棄する

session_destroy

(PHP 4, PHP 5, PHP 7, PHP 8)

session_destroy — セッションに登録されたデータを全て破棄する

説明

session_destroy(): bool

session_destroy()は、現在のセッションに 関連づけられたすべてのデータを破棄します。この関数は、 セッションに関するグローバル変数を破棄しません。 また、セッションクッキーを破棄しません。 セッション変数の利用を再開するには session_start() をコールする必要があります。

注意: 通常のコードでは、session_destroy() を呼ぶ必要はありません。 セッションデータを破棄するよりも、 $_SESSION 配列をクリーンアップしてください。

セッションを切断するには、 セッション ID の割り当ても解除する必要があります。セッション ID の受け渡しに クッキーが使用されている場合（デフォルト）には、セッションクッキーも 削除されなければなりません。 そのために setcookie() が利用できます。

session.use_strict_mode が有効になっている場合、 古くなった セッションID のクッキーを削除する必要はありません。 なぜなら、セッションモジュールはセッションIDに紐付いたデータがないとき、 セッションID のクッキーを受け入れないからです。 全てのサイトで、 session.use_strict_mode を有効にすることを推奨します。

警告

すぐにセッションを削除してしまうと、 望まない結果が起こる可能性があります。 並列にリクエストが行われたときに、 他のリクエストの接続は突然データが消えたように見えるかもしれません。 たとえば、JavaScript または/もしくは URLリンクからのリクエストが同時に実行された場合です。

現在のセッションモジュールは、空のセッションIDを受け入れません。 しかし、すぐにセッションを削除してしまうと、 クライアント(ブラウザ)サイドとの競合によって、 空のセッションIDクッキーが発生するかもしれません。 これにより、不必要なのにクライアント側が たくさんのセッションIDを作ってしまうことになります。

こうした事象を防ぐためには、 $_SESSION に削除時のタイムスタンプを設定し、 それより後のアクセスを拒否するようにしなければなりません。 もしくは、アプリケーションが同時に 複数のリクエストを受け付けないようにすることです。 同じことは、session_regenerate_id() 関数にも当てはまります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 $_SESSIONでセッションを破棄する

<?php
// セッションの初期化
// session_name("something")を使用している場合は特にこれを忘れないように!
session_start();

// セッション変数を全て解除する
$_SESSION = array();

// セッションを切断するにはセッションクッキーも削除する。
// Note: セッション情報だけでなくセッションを破壊する。
if (ini_get("session.use_cookies")) {
$params = session_get_cookie_params();
setcookie(session_name(), '', time() - 42000,
$params["path"], $params["domain"],
$params["secure"], $params["httponly"]
);
}

// 最終的に、セッションを破壊する
session_destroy();
?>

参考

  • session.use_strict_mode
  • session_reset() - session 配列を元の値で再初期化します
  • session_regenerate_id() - 現在のセッションIDを新しく生成したものと置き換える
  • unset() - 指定した変数の割当を解除する
  • setcookie() - クッキーを送信する


現在のセッションデータを、セッションエンコードされた文字列に変換する

  • ≪ session_destroy
  • session_gc ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションデータを、セッションエンコードされた文字列に変換する

session_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

session_encode — 現在のセッションデータを、セッションエンコードされた文字列に変換する

説明

session_encode(): string|false

session_encode() は、 現在のセッションの内容をシリアライズした文字列を返します． 現在のセッションの内容は、スーパーグローバル $_SESSION から取得します。

デフォルトのアンシリアライズの方法は PHP が内部的に実装しているものであり、 unserialize() とは違います。 シリアライズの方法は、session.serialize_handler で設定できます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のセッションの内容をエンコードしたものを返します。 失敗した場合に false を返します

注意

警告

session_encode() を使う前には session_start() を呼ぶ必要があります。

参考

  • session_decode() - セッションエンコードされた文字列からセッションデータをデコードする
  • session.serialize_handler


セッションデータのガベージコレクションを実行する

  • ≪ session_encode
  • session_get_cookie_params ≫
  • PHP Manual
  • セッション関数
  • セッションデータのガベージコレクションを実行する

session_gc

(PHP 7 >= 7.1.0, PHP 8)

session_gc — セッションデータのガベージコレクションを実行する

説明

session_gc(): int|false

session_gc() は、セッションデータの GC (ガベージコレクション) を実行するために使用されます。PHPは、デフォルトで確率ベースのセッション GC を行います。

確率ベースの GC は多少は機能しますが、いくつかの問題があります。 1) トラフィックが少ないサイトのセッションデータは、優先期間内に削除されないことがあります。 2) トラフィックの多いサイトでは、GC が頻繁になる可能性があります。 3) ユーザーの要求の際に GC が実行され、ユーザーは GC 遅延を感じます。

そのため、例えば UNIX 系のシステムでは「cron」を使用して、 本稼動システムに対して定期的に GC を実行することをお勧めします。 session.gc_probability を 0 に設定して、 確率ベースのGCを無効にしてください。

パラメータ

この関数にはパラメータはありません。

戻り値

session_gc() は、 成功時には削除されたセッションデータの数、 失敗時には false を返します。

古いセーブハンドラは、削除されたセッションデータの数を返さず、成功/失敗フラグのみを返します。 この場合、実際に削除されたデータにかかわらず、削除されたセッションデータの数は 1 になります。

例

例1 cron のようなタスクマネージャでの session_gc() の例

<?php
// 注 : このスクリプトは、Web サーバープロセスと同じユーザーで実行される必要があります。

// セッションデータストレージアクセスを初期化するには、アクティブセッションが必要です。
session_start();

// 直ちに GC を実行します
session_gc();

// session_gc() によって作成されたセッション ID をクリーンアップします
session_destroy();
?>

例2 ユーザーがアクセス可能なスクリプトでの session_gc() の例

<?php
// 注 : session_gc() は、タスクマネージャスクリプトで使用することをお勧めしますが、次のように使用できます。

// 最後の GC 時間チェックに使用
$gc_time = '/tmp/php_session_last_gc';
$gc_period = 1800;

session_start();
// GC 期限が経過したときにのみ GC を実行します。
// つまり、リクエストのたびに session_gc() をコールすることはリソースの無駄です。
if (file_exists($gc_time)) {
if (filemtime($gc_time) < time() - $gc_period) {
session_gc();
touch($gc_time);
}
} else {
touch($gc_time);
}
?>

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_destroy() - セッションに登録されたデータを全て破棄する
  • session.gc_probability


セッションクッキーのパラメータを得る

  • ≪ session_gc
  • session_id ≫
  • PHP Manual
  • セッション関数
  • セッションクッキーのパラメータを得る

session_get_cookie_params

(PHP 4, PHP 5, PHP 7, PHP 8)

session_get_cookie_params — セッションクッキーのパラメータを得る

説明

session_get_cookie_params(): array

セッションクッキーのパラメータを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のセッションクッキーの情報を配列として返します。 この配列には次のような項目が含まれています。

  • "lifetime" - クッキーの生存期間(lifetime)
  • "path" - 情報が保存されている場所のパス
  • "domain" - クッキーのドメイン
  • "secure" - クッキーはセキュアな接続でのみ送信されます。
  • "httponly" - クッキーは HTTP を通してのみアクセス可能となります。
  • "samesite" - クロスドメイン間で送信されるクッキーを制御します。

変更履歴

バージョン | 説明
7.3.0 | 返される配列に、"samesite" エントリが追加されました。

参考

  • session.cookie_lifetime
  • session.cookie_path
  • session.cookie_domain
  • session.cookie_secure
  • session.cookie_httponly
  • session.cookie_samesite
  • session_set_cookie_params() - セッションクッキーパラメータを設定する


現在のセッション ID を取得または設定する

  • ≪ session_get_cookie_params
  • session_module_name ≫
  • PHP Manual
  • セッション関数
  • 現在のセッション ID を取得または設定する

session_id

(PHP 4, PHP 5, PHP 7, PHP 8)

session_id — 現在のセッション ID を取得または設定する

説明

session_id(?string $id = null): string|false

session_id() は現在のセッション ID を取得 または設定するために使用されます。

現在の名前とセッション ID を、URL に追加可能な文字列として取得する ために定数 SID も使用できます。 セッションハンドリング も参照ください。

パラメータ

id

id が指定され、null でない場合、現在の セッション ID を置換します。その際、 この関数は session_start() より前にコールされている必要があります。 セッションハンドラによっては、セッション ID として使用できる文字に 制限がある場合があります。例えば、ファイルによるセッションハンドラでは セッション ID として使える文字は a-z A-Z 0-9 , (カンマ) そして - (マイナス) に限られます!

注意: セッション保持にクッキーを使用している場合、 session_id() において id 引数を指定すると、 現在のセッション ID がセットされるものと まったく同一であるかどうかに関わらず、 session_start() が呼び出される際に常に新しいクッキーが送信されます。

戻り値

session_id() は現在のセッションのセッション ID を返します。 現在のセッションが存在しない (現在のセッション ID が存在しない) 場合は空文字列 ("") を返します。 失敗時には、false を返します。

変更履歴

バージョン | 説明
8.0.0 | id は、nullable になりました。

参考

  • session_regenerate_id() - 現在のセッションIDを新しく生成したものと置き換える
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_set_save_handler() - ユーザー定義のセッション保存関数を設定する
  • session.save_handler


現在のセッションモジュールを取得または設定する

  • ≪ session_id
  • session_name ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションモジュールを取得または設定する

session_module_name

(PHP 4, PHP 5, PHP 7, PHP 8)

session_module_name — 現在のセッションモジュールを取得または設定する

説明

session_module_name(?string $module = null): string|false

session_module_name()は、 現在のセッションモジュールの名前を返します。 これは session.save_handler としても知られています。

パラメータ

module

module が指定され、null でない場合、 そのモジュールを代わりに使用します。 このパラメーターに "user" を渡すことは禁止されています。 ユーザー定義のセッションハンドラを設定するには、この関数のかわりに session_set_save_handler() 関数 を呼び出さなければなりません。

戻り値

現在のセッションモジュールの名前を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | module は、nullable になりました。
7.2.0 | モジュール名に "user" を設定することは、 明示的に禁止されるようになりました。 これより前のバージョンでは、 "user" を設定しても静かに無視されていました。


現在のセッション名を取得または設定する

  • ≪ session_module_name
  • session_regenerate_id ≫
  • PHP Manual
  • セッション関数
  • 現在のセッション名を取得または設定する

session_name

(PHP 4, PHP 5, PHP 7, PHP 8)

session_name — 現在のセッション名を取得または設定する

説明

session_name(?string $name = null): string|false

session_name() は、現在のセッション名を返します。 name を渡すと、 session_name() はセッション名を上書きして 元の セッション名を返します。

新しいセッションの name が与えられると、 session_name() 関数は HTTPクッキー を 変更します(そして、session.transid が有効なときは、出力内容も変更します)。 HTTPクッキー が一度送信されると、 session_name() 関数はエラーになります。 session_name() 関数は、 セッションを適切に動作させるためには、 session_start() の前に呼び出さなければなりません。

リクエストが開始された際にセッション名はリセットされ、 session.name に保存されたデフォルト値に戻ります。 よって、各リクエスト毎に(そして session_start() をコールする前に) session_name() をコールする必要があります。

パラメータ

name

セッションの名前を参照します。これは、クッキーや URL (例: PHPSESSID) で使われます。 セッション名は英数字のみで構成されている必要があり、また、 短く、その内容が分かるようなものである必要があります (これは、クッキー警告を有効にしているユーザー用です)。 name が指定され、null でない場合、 現在のセッションの名前が、指定された値に置き換えられます。

警告

セッション名は数字だけで構成することはできません。 少なくとも文字がひとつ以上現れる必要があります。そうでない場合、 新規セッション ID が毎回生成されます。

戻り値

現在のセッションの名前を返します。 name を渡すと、 session_name() はセッション名を上書きして 元のセッション名を返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
7.2.0 | name は、nullable になりました。
7.2.0 | session_name() 関数は、 セッションの状態をチェックするようになりました。 これより前のバージョンでは、 クッキー の状態をチェックするだけでした。 そのため、古い session_name() 関数は session_start() 関数の後に session_name() 関数を呼び出すことを許して しまっており、それが PHP のクラッシュや不具合を起こす可能性がありました。

例

例1 session_name() の例

<?php

/* セッション名をWebsiteIDに設定する */

$previous_name = session_name("WebsiteID");

echo "前回のセッション名は $previous_name でした<br />";
?>

参考

  • 設定ディレクティブ session.name


現在のセッションIDを新しく生成したものと置き換える

  • ≪ session_name
  • session_register_shutdown ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションIDを新しく生成したものと置き換える

session_regenerate_id

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

session_regenerate_id — 現在のセッションIDを新しく生成したものと置き換える

説明

session_regenerate_id(bool $delete_old_session = false): bool

session_regenerate_id() は現在のセッションIDを 新しいものと置き換えます。その際、現在のセッション情報は維持されます。

session.use_trans_sid が有効な場合は、 session_regenerate_id() を呼んでから出力を始めないといけません。 それ以前の出力には、古いセッション ID が使われます。

警告

現在の session_regenerate_id は、不安定なネットワークをうまく扱えません。 たとえば、モバイルネットワークや WiFi ネットワークです。 よって、 session_regenerate_id を 呼ぶことで、セッションの消失を経験するかもしれません。

すぐに古いセッションデータを破棄すべきではありませんが、 古いセッションID のタイムスタンプと、 アクセス制御は破棄すべきでしょう。 さもないと、ページへの同時アクセスによって、 状態の不整合が発生したり、セッションが失われたり、 クライアント(ブラウザ) 側のレースコンディションが発生したり、 不必要なセッションIDをたくさん作らなければならなくなるかもしれません。 セッションデータをすぐに破棄してしまうと、 セッションハイジャックの検出だけでなく、 防止もできなくしてしまいます。

パラメータ

delete_old_session

関連付けられた古いセッションを削除するかどうか。 削除による競合を防いだり、セッションハイジャックを 検出/防ぐ 必要がある場合には、古いセッションを削除すべきではありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 session_regenerate_id() の使用例

<?php
// 注意: このコードは完全に動作するわけではありません。一例です！

session_start();

// 破棄されたタイムスタンプをチェック
if (isset($_SESSION['destroyed'])
&& $_SESSION['destroyed'] < time() - 300) {
// 通常は起こるべきではない。攻撃や不安定なネットワークによる可能性がある
// このユーザーのセッションから、全ての認証ステータスを削除
remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
throw(new DestroyedSessionAccessException);
}

$old_sessionid = session_id();

// 破棄されたタイムスタンプを設定
$_SESSION['destroyed'] = time(); // session_regenerate_id() は古いセッションデータを保存します。

// 単に session_regenerate_id() を呼ぶだけでは、セッションの消失などに繋がる可能性があります。
// 次の例を見てください。
session_regenerate_id();

// 新しいセッションには、破棄されたタイムスタンプは不要
unset($_SESSION['destroyed']);

$new_sessionid = session_id();

echo "古いセッション: $old_sessionid<br />";
echo "新しいセッション: $new_sessionid<br />";

print_r($_SESSION);
?>

現在のセッションモジュールは、不安定なネットワークをうまく扱えません。 session_regenerate_id によるセッションの消失を避けるために、 セッションIDを管理すべきです。

例2 session_regenerate_id() による、セッションの消失を避ける

<?php
// 注意: このコードは完全に動作するわけではありません。一例です！
// my_session_start() and my_session_regenerate_id() によって、
// 不安定なネットワークによるセッションの消失を避けています。
// それに加えて、このコードは攻撃者から、盗まれたセッションを利用した
// 攻撃を防ぐ可能性もあります。

function my_session_start() {
session_start();
if (isset($_SESSION['destroyed'])) {
if ($_SESSION['destroyed'] < time()-300) {
// 通常は起こるべきではない。攻撃や不安定なネットワークによる可能性がある
// このユーザーのセッションから、全ての認証ステータスを削除
remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
throw(new DestroyedSessionAccessException);
}
if (isset($_SESSION['new_session_id'])) {
// 完全に expire してはいない。
// Cookie が不安定なネットワークによって失われた可能性がある。
// 適切なセッションIDのクッキーを設定するためにリトライする。
// 注意: 認証フラグを削除したい場合は、セッションIDを再度設定しようとしてはいけない。
session_commit();
session_id($_SESSION['new_session_id']);
// 新しいセッションIDが存在しているはず
session_start();
return;
}
}
}

function my_session_regenerate_id() {
// 不安定なネットワークのために、セッションID が設定されなかったときは、
// 新しいセッションID が、適切なセッションIDに設定されることが必須。
$new_session_id = session_create_id();
$_SESSION['new_session_id'] = $new_session_id;

// 破棄された時のタイムスタンプを設定
$_SESSION['destroyed'] = time();

// 現在のセッションを書き込んで閉じる
session_commit();

// 新しいセッションを新しいセッションIDで開始
session_id($new_session_id);
ini_set('session.use_strict_mode', 0);
session_start();
ini_set('session.use_strict_mode', 1);

// 新しいセッションには、以下の情報は不要
unset($_SESSION['destroyed']);
unset($_SESSION['new_session_id']);
}
?>

参考

  • session_id() - 現在のセッション ID を取得または設定する
  • session_create_id() - 新しいセッションIDを作成する
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_destroy() - セッションに登録されたデータを全て破棄する
  • session_reset() - session 配列を元の値で再初期化します
  • session_name() - 現在のセッション名を取得または設定する


セッションのシャットダウン関数

  • ≪ session_regenerate_id
  • session_reset ≫
  • PHP Manual
  • セッション関数
  • セッションのシャットダウン関数

session_register_shutdown

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

session_register_shutdown — セッションのシャットダウン関数

説明

session_register_shutdown(): void

session_write_close() をシャットダウン関数として登録します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

シャットダウン関数の登録に失敗した場合に E_WARNING が発生します。


session 配列を元の値で再初期化します

  • ≪ session_register_shutdown
  • session_save_path ≫
  • PHP Manual
  • セッション関数
  • session 配列を元の値で再初期化します

session_reset

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

session_reset — session 配列を元の値で再初期化します

説明

session_reset(): bool

session_reset() は、セッション・ストレージに保存されていた元の値でセッションを再初期化します。 この関数は、$_SESSION 内の変更を破棄しますが、そうするためにアクティブなセッションが必要です。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

変更履歴

バージョン | 説明
7.2.0 | この関数の戻り値の型は bool になりました。 以前は void でした。

参考

  • $_SESSION
  • session.auto_start 構成ディレクティブ
  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する
  • session_abort() - session 配列の変更を破棄してセッションを終了します
  • session_commit() - session_write_close のエイリアス


現在のセッションデータ保存パスを取得または設定する

  • ≪ session_reset
  • session_set_cookie_params ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションデータ保存パスを取得または設定する

session_save_path

(PHP 4, PHP 5, PHP 7, PHP 8)

session_save_path — 現在のセッションデータ保存パスを取得または設定する

説明

session_save_path(?string $path = null): string|false

session_save_path() は、 現在のセッションデータ保存パスを返します。

パラメータ

path

セッションデータのパス。これに null でない値を指定すると、 データを保存するパスが変更されます。ただしそのためには session_start() がコールされる前に session_save_path() がコールされている必要があります。

注意:

いくつかのオペレーションシステムでは、多くの小さなファイルを効率的に 処理するファイルシステム上にパスを指定することが望ましいです。 例えば、Linux では ext2fs よりも reiserfs の方が性能面でより 優れています。

戻り値

現在のデータ保存先ディレクトリのパスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | path は、nullable になりました。

参考

  • 設定ディレクティブ session.save_path


セッションクッキーパラメータを設定する

  • ≪ session_save_path
  • session_set_save_handler ≫
  • PHP Manual
  • セッション関数
  • セッションクッキーパラメータを設定する

session_set_cookie_params

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_cookie_params — セッションクッキーパラメータを設定する

説明

session_set_cookie_params(
int $lifetime_or_options,
?string $path = null,
?string $domain = null,
?bool $secure = null,
?bool $httponly = null
): bool

PHP 7.3.0 以降で使える代替のシグネチャ:

session_set_cookie_params(array $lifetime_or_options): bool

ファイル php.ini で定義されたクッキーパラメータを設定します。 この関数の効果が持続するのは、スクリプトの実行が終了するまでです。 したがって、リクエスト毎や session_start() がコールされる前に session_set_cookie_params() をコールする必要があります。

この関数は、PHP の ini 設定の値を実行時に上書きします。値の取得には ini_get() が使えます。

パラメータ

lifetime_or_options

最初のシグネチャを使う場合、セッションクッキーの 有効期限。秒数で定義します。

二番目のシグネチャを使う場合、 以下に示すキーを持つことができる連想配列です。 lifetime, path, domain, secure, httponly および samesite. 対応する値は、キーと同じ名前のパラメータで説明されているものと同じ意味です。 samesite 要素の値は、 Lax または Strict になるはずです。 上記の許可されているオプションがいずれも設定されなかった場合、 デフォルト値は、明示的なパラメーターのデフォルト値と同じです。 samesite 要素が省略されると、SameSite クッキー属性は設定されません。

path

クッキーが動作するドメイン上の パス。単一のスラッシュ ('/') を指定すると、ドメイン上のすべてのパスで動作します。

domain

クッキーの ドメイン。たとえば 'www.php.net'。 すべてのサブドメインでクッキーを有効にしたい場合は、先頭にドットをつけて '.php.net' のようにします。

secure

true の場合は、セキュア な接続の場合にのみクッキーを送信します。

httponly

true の場合は、PHP でセッションクッキーを設定する際に httponly フラグの送信を試みます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | path, domain, secure, httponly は、 nullable になりました。
7.3.0 | 連想配列 lifetime_or_options をサポートする、 別のシグネチャが追加されました。 このシグネチャは、SameSite クッキー属性の設定もサポートします。
7.2.0 | 成功した場合に true を、失敗した場合に false を返します。 以前はこの関数は void を返していました。

参考

  • session.cookie_lifetime
  • session.cookie_path
  • session.cookie_domain
  • session.cookie_secure
  • session.cookie_httponly
  • session.cookie_samesite
  • session_get_cookie_params() - セッションクッキーのパラメータを得る


ユーザー定義のセッション保存関数を設定する

  • ≪ session_set_cookie_params
  • session_start ≫
  • PHP Manual
  • セッション関数
  • ユーザー定義のセッション保存関数を設定する

session_set_save_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_save_handler — ユーザー定義のセッション保存関数を設定する

説明

session_set_save_handler(
callable $open,
callable $close,
callable $read,
callable $write,
callable $destroy,
callable $gc,
callable $create_sid = ?,
callable $validate_sid = ?,
callable $update_timestamp = ?
): bool

次のプロトタイプでも登録できます。

session_set_save_handler(object $sessionhandler, bool $register_shutdown = true): bool

session_set_save_handler() は、セッションに 関連するデータを保存および取得するために使用されるユーザー定義の セッション保存関数を設定します。この関数は、PHP セッションにより 提供されるもの以外の保存方法を使用したい場合に有用です。 例えば、セッションデータをローカルデータベースに保存します。

パラメータ

この関数には二種類のプロトタイプがあります。

sessionhandler

SessionHandlerInterface、 SessionIdInterface(オプション) または SessionUpdateTimestampHandlerInterface を実装したクラス、たとえば SessionHandler のインスタンスで、 これをセッションハンドラとして登録する。

register_shutdown

session_write_close() を register_shutdown_function() 関数として登録するかどうか。

あるいは
open

以下のシグネチャを持つ callable:

open(string $savePath, string $sessionName): bool

open コールバックはクラスのコンストラクタのようなもので、セッションを開くときに実行されます。 セッションが自動で開始したり、あるいは手動で session_start() で開始させたりするときに、最初に実行されるコールバック関数がこれです。 成功した場合は true、失敗した場合は false を返します。

close

以下のシグネチャを持つ callable:

close(): bool

close コールバックはクラスのデストラクタのようなもので、write コールバックがコールされた後で実行されます。 また、session_write_close() がコールされたときにも実行されます。 成功した場合は true、失敗した場合は false を返します。

read

以下のシグネチャを持つ callable:

read(string $sessionId): string

read コールバックは、常にセッションエンコード (シリアライズ) された文字列を返さなければなりません。何もデータを読み込まなかった場合は空文字列を返します。

このコールバックは、セッションが開始したときや session_start() がコールされたときに PHP が内部的に実行します。 このコールバックを実行する前に、PHP は open コールバックを実行します。

このコールバックが返す値は、 write コールバックがストレージに渡した形式とまったく同じシリアライズ形式でなければなりません。 返された値を PHP が自動的にアンシリアライズして、スーパーグローバル $_SESSION に格納します。データの形式は serialize() したものと似ていますが、実際は違う形式であることに注意しましょう。 シリアライズの方法は ini 設定 session.serialize_handler で指定します。

write

以下のシグネチャを持つ callable:

write(string $sessionId, string $data): bool

write コールバックは、セッションの保存や終了が必要となったときにコールされます。 このコールバックが受け取るのは、現在のセッション ID とシリアライズ後のスーパーグローバル $_SESSION です。 PHP が内部で利用するシリアライズ方法は、ini 設定 session.serialize_handler で指定します。

このコールバックに渡されたシリアライズ後のセッションデータを、 渡されたセッション ID に対応させて格納しなければなりません。 このデータを取得した read コールバックは、 write コールバックに最初に渡されたのとまったく同じ値を返さなければなりません。

このコールバックが実行されるのは、PHP のスクリプトが終了するときか、あるいは明示的に session_write_close() がコールされたときです。この関数の実行後には、PHP が内部的に close コールバックを実行することに注意しましょう。

注意:

"write" ハンドラは、出力ストリームが閉じてから実行されます。 したがって、"write" ハンドラ内でデバッグ出力を行っても、 それはブラウザに表示されません。 デバッグ出力が必要なら、それをファイルに書き出すようにしましょう。

destroy

以下のシグネチャを持つ callable:

destroy(string $sessionId): bool

このコールバックが実行されるのは、 session_destroy() あるいは session_regenerate_id() (destroy パラメータを true にした場合) を実行し、セッションを破棄した場合です。 成功した場合は true、失敗した場合は false を返します。

gc

以下のシグネチャを持つ callable:

gc(int $lifetime): bool

ガベージコレクタコールバックは PHP が内部で定期的に実行し、古いセッションデータを破棄します。 実行頻度は session.gc_probability および session.gc_divisor で設定します。 この関数に渡される有効期限の値は session.gc_maxlifetime で設定できます。 成功した場合は true、失敗した場合は false を返します。

create_sid

以下のシグネチャを持つ callable:

create_sid(): string

このコールバックは、新しいセッション ID が必要になったときに実行されます。 パラメータは不要です。戻り値は、使っているハンドラで有効なセッション ID を表す文字列となります。

validate_sid

以下のシグネチャを持つ callable:

validate_sid(string $key): bool

このコールバックは、セッションが開始された場合に実行されます。 但し、セッションID が渡され、 session.use_strict_mode が有効な場合に限ります。 key は検証する セッションID を指定します。 渡されたID のセッションが既に存在する場合、セッションID は有効です。 成功した場合は true、失敗した場合は false を返します。

update_timestamp

以下のシグネチャを持つ callable:

update_timestamp(string $key, string $val): bool

このコールバックは、セッションが更新された時に実行されます。 key はセッションID、 val はセッションデータを指定します。 成功した場合は true、失敗した場合は false を返します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 自作のセッションハンドラ: 完全なコードは SessionHandlerInterface を参照

ここでは実行するところだけを示します。完全な例は、上でリンクしている SessionHandlerInterface のページを参照ください。

session_set_save_handler() でオブジェクト指向型のプロトタイプを使っていることと、 シャットダウン関数をその parameter フラグで登録していることに注目しましょう。 オブジェクトをセッション保存ハンドラとして使うときには、この方法をおすすめします。

<?php
class MySessionHandler implements SessionHandlerInterface
{
// ここでインターフェイスを実装します
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// $_SESSION への値の設定や格納されている値の取得を進めます

注意

警告

write ハンドラおよび close ハンドラはオブジェクトが破棄されたあとにコールされます。 そのため、これらのハンドラでオブジェクトを使ったり例外をスローしたりすることはできません。 例外をキャッチできないのでその情報をトレースすることもできず、 例外は単純に無視されてしまいます。 しかし、オブジェクトのデストラクタではセッションを使えます。

この「ニワトリが先かタマゴが先か」の問題を解決するために、 デストラクタから session_write_close() をコールできますが、より確実なのは先述のとおりシャットダウン関数を登録することです。

警告

SAPI の種類によっては、スクリプトの終了時にセッションを閉じると 現在の作業ディレクトリが変わってしまうことがあります。これを防ぐには、 事前に session_write_close() でセッションを閉じます。

参考

  • 設定ディレクティブ session.save_handler
  • 設定ディレクティブ session.serialize_handler
  • register_shutdown_function() - シャットダウン時に実行する関数を登録する
  • session_register_shutdown() - セッションのシャットダウン関数
  • 手続き型の完全なリファレンス実装は » save_handler.inc を参照ください。


新しいセッションを開始、あるいは既存のセッションを再開する

  • ≪ session_set_save_handler
  • session_status ≫
  • PHP Manual
  • セッション関数
  • 新しいセッションを開始、あるいは既存のセッションを再開する

session_start

(PHP 4, PHP 5, PHP 7, PHP 8)

session_start — 新しいセッションを開始、あるいは既存のセッションを再開する

説明

session_start(array $options = []): bool

session_start() は、セッションを作成します。 もしくは、リクエスト上で GET, POST またはクッキーにより渡されたセッション ID に基づき現在のセッションを復帰します。

session_start() がコールされたりセッションが自動的に開始したりするときに、 PHP はセッションの open ハンドラおよび read ハンドラをコールします。 このハンドラとしては、デフォルトで組み込まれている保存ハンドラの他に PHP 拡張モジュールで提供されているもの (SQLite や Memcached など) も使えます。また、自作のハンドラを session_set_save_handler() で定義することもできます。 read コールバックは既存のセッションデータ (独自のシリアライズフォーマットで保存されているもの) を読み込み、 それを復元して自動的にスーパーグローバル $_SESSION に格納します。

名前付きのセッションを使用したい場合、 session_start() の前に session_name() をコールする必要があります。

session_start() は、 session.use_trans_sid が有効の場合に URL 書換え用の内部出力ハンドラを登録します。

ユーザーが ob_start() と共に ob_gzhandler または類似のものを使用している場合、 出力ハンドラの順番は正しく出力を行うために重要です。例えば、 セッション開始時にユーザーは ob_gzhandler を登録する必要があります。

パラメータ

options

オプションの連想配列を指定することができます。これは、現在設定されている セッションの設定ディレクティブ を上書きします。 連想配列のキーにはプレフィックス session. を含めてはいけません。

通常の設定ディレクティブ群に加えて、 read_and_close オプションを指定することもできます。 これを true にすると、セッションを読み込んだらその場ですぐにクローズします。 セッションのデータを書き換えるつもりがない場合は、こうしておけば、意図せぬロックを防げます。

戻り値

この関数は、セッションが正常に開始した場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
7.1.0 | セッションを開始できなかった場合、 session_start() は、false を返し、 $_SESSION を初期化しないようになりました。

例

基本的なセッションの例

例1 page1.php

<?php
// page1.php

session_start();

echo 'Welcome to page #1';

$_SESSION['favcolor'] = 'green';
$_SESSION['animal'] = 'cat';
$_SESSION['time'] = time();

// セッションクッキーが有効なら動作します
echo '<br /><a href="page2.php">page 2</a>';

// あるいは必要に応じてセッション ID を渡します
echo '<br /><a href="page2.php?' . SID . '">page 2</a>';
?>

page1.php を表示した後なら、 page2.php はセッション上の情報を含んでいるはずです。 セッションについてのリファレンス を読むと、 セッションIDの伝達 に関する情報が得られます。 例えば、SID とは何かといったことです。

例2 page2.php

<?php
// page2.php

session_start();

echo 'Welcome to page #2<br />';

echo $_SESSION['favcolor']; // green
echo $_SESSION['animal']; // cat
echo date('Y m d H:i:s', $_SESSION['time']);

// page1.php と同様に、ここで SID を使うこともできます
echo '<br /><a href="page1.php">page 1</a>';
?>

session_start() のオプションの指定

例3 クッキーの有効期限の上書き

<?php
// これは、有効期限が1日の永続クッキーを送信します
session_start([
'cookie_lifetime' => 86400,
]);
?>

例4 セッションの読み込みとクローズ

<?php
// セッション内で何も変更する必要がないことがわかっている場合は、
// セッションを読み込んですぐにクローズしてしまえば、
// セッションファイルをロックして他のページをブロックしてしまうことを防げます
session_start([
'cookie_lifetime' => 86400,
'read_and_close' => true,
]);

注意

注意:

クッキーに基づくセッションを使用している場合、ブラウザに何か出力を行う前に session_start() をコールする必要があります。

注意:

ob_gzhandler() よりも zlib.output_compression の使用が推奨されています。

注意:

この関数は、設定によって複数の HTTP ヘッダを送信します。 これらのヘッダをカスタマイズするには session_cache_limiter() を参照ください。

参考

  • $_SESSION
  • 設定ディレクティブ session.auto_start
  • session_id() - 現在のセッション ID を取得または設定する


現在のセッションの状態を返す

  • ≪ session_start
  • session_unset ≫
  • PHP Manual
  • セッション関数
  • 現在のセッションの状態を返す

session_status

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

session_status — 現在のセッションの状態を返す

説明

session_status(): int

session_status() を使うと、現在のセッションの状態を取得できます。

パラメータ

この関数にはパラメータはありません。

戻り値

  • セッションが無効な場合は PHP_SESSION_DISABLED
  • セッションが有効だけれどもセッションが存在しない場合は PHP_SESSION_NONE
  • セッションが有効で、かつセッションが存在する場合は PHP_SESSION_ACTIVE

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する


全てのセッション変数を開放する

  • ≪ session_status
  • session_write_close ≫
  • PHP Manual
  • セッション関数
  • 全てのセッション変数を開放する

session_unset

(PHP 4, PHP 5, PHP 7, PHP 8)

session_unset — 全てのセッション変数を開放する

説明

session_unset(): bool

関数 session_unset() は現在登録されている全てのセッション変数を開放します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | この関数の戻り値の型は bool になりました。 以前は void でした。

注意

注意:

$_SESSION が使用されている場合、セッション変数の登録を削除するために unset() すなわち、unset($_SESSION['varname']); を使用してください。

警告

$_SESSION スーパーグローバルを使用した セッション変数の登録が不可能になってしまうため、 unset($_SESSION) を使って $_SESSION を完全に unset しないでください。

注意:

session_unset() 関数は、 $_SESSION = [] と同等です。

警告

この関数は、セッションがアクティブな場合にのみ動作します。 セッションが開始されていなかったり、既に破棄されている場合には、 この関数は $_SESSION 配列をクリアしません。 すべてのセッション変数をクリアする場合は、 たとえセッションがアクティブでない場合でも $_SESSION = [] を使いましょう。


セッションデータを書き込んでセッションを終了する

  • ≪ session_unset
  • SessionHandler ≫
  • PHP Manual
  • セッション関数
  • セッションデータを書き込んでセッションを終了する

session_write_close

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

session_write_close — セッションデータを書き込んでセッションを終了する

説明

session_write_close(): bool

現在のセッションを終了し、セッションデータを書き込みます。

セッションデータは、session_write_close() をコールしなくても、スクリプト終了時に保存されます。しかし、 セッションデータは、同時書き込みを防ぐためにロックされるため、 ある時点であるセッションの処理ができるスクリプトは、1つだけです。 セッションでフレームセットを使用する場合、 このロックのためにフレームがひとつずつロードされるような経験をするでしょう。 セッションへの全ての変更が行われるとすぐにセッションを終了することにより、 全てのフレームのロードに要する時間を減らすことができます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
7.2.0 | この関数の戻り値の型は bool になりました。 以前は void でした。

参考

  • session_register_shutdown() - セッションのシャットダウン関数


SessionHandler クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SessionHandler は特殊なクラスで、 これを継承したクラスを作れば PHP が内部的に使っているセッション保存ハンドラを拡張できます。 このクラスには七つのメソッドがあり、それぞれが七つのセッション保存ハンドラコールバック (open, close, read, write, destroy, gc および create_sid) に対応しています。デフォルトでは、このクラスは session.save_handler で定義された内部セッションハンドラをラップします。 通常は files がデフォルトになっています。 それ以外には、PHP の拡張モジュールとして提供されている SQLite (sqlite) や Memcache (memcache) そして Memcached (memcached) が使えます。

SessionHandler のインスタンスを session_set_save_handler() でハンドラとして指定すると、 そのインスタンスが現在の保存ハンドラをラップします。 SessionHandler を継承したクラスを作ると、 親クラスのメソッド、つまり PHP の内部セッションハンドラのメソッドをラップして オーバーライドしたり処理を割り込ませたりフィルタをかけたりできるようになります。

これを利用すると、たとえば read と write メソッドに処理を割り込ませ、セッションデータの暗号化/復号の処理を追加することができます。 あるいは、ガベージコレクションコールバック gc を完全に自前の処理で置き換えてしまうこともできます。

SessionHandler は現在の内部保存ハンドラのメソッドをラップしているので、 先述の暗号化の例は任意の保存ハンドラに適用することができます。その際に、ハンドラの内部的な動きを知っておく必要はありません。

このクラスを使うには、まず最初に公開したいハンドラを session.save_handler で設定してから、 SessionHandler あるいはそれを継承したクラスのインスタンスを session_set_save_handler() に渡します。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。 コールバックの戻り値も、PHP が内部的に利用するだけです。 セッションの処理の流れについての詳しい情報は session_set_save_handler() を参照ください。

クラス概要

class SessionHandler implements SessionHandlerInterface, SessionIdInterface {
/* メソッド */
public close(): bool
public create_sid(): string
public destroy(string $id): bool
public gc(int $max_lifetime): int|false
public open(string $path, string $name): bool
public read(string $id): string|false
public write(string $id, string $data): bool
}

注意

警告

このクラスは現在の PHP 内部セッション保存ハンドラを公開するように作られています。 自作の保存ハンドラを用意したい場合は、SessionHandler を継承するのではなく SessionHandlerInterface を実装したクラスを作るようにしましょう。

例

例1 SessionHandler を使って PHP の保存ハンドラに暗号化機能を追加する例

<?php

/**
* decrypt AES 256
*
* @param data $edata
* @param string $password
* @return decrypted data
*/
function decrypt($edata, $password) {
$data = base64_decode($edata);
$salt = substr($data, 0, 16);
$ct = substr($data, 16);

$rounds = 3; // キーの長さに依存します
$data00 = $password.$salt;
$hash = array();
$hash[0] = hash('sha256', $data00, true);
$result = $hash[0];
for ($i = 1; $i < $rounds; $i++) {
$hash[$i] = hash('sha256', $hash[$i - 1].$data00, true);
$result .= $hash[$i];
}
$key = substr($result, 0, 32);
$iv = substr($result, 32,16);

return openssl_decrypt($ct, 'AES-256-CBC', $key, true, $iv);
}

/**
* crypt AES 256
*
* @param data $data
* @param string $password
* @return base64 encrypted data
*/
function encrypt($data, $password) {
// 暗号学的にセキュアな、ランダムなソルト値を、random_bytes() を使って生成します。
$salt = random_bytes(16);

$salted = '';
$dx = '';
// Salt the key(32) and iv(16) = 48
while (strlen($salted) < 48) {
$dx = hash('sha256', $dx.$password.$salt, true);
$salted .= $dx;
}

$key = substr($salted, 0, 32);
$iv = substr($salted, 32,16);

$encrypted_data = openssl_encrypt($data, 'AES-256-CBC', $key, true, $iv);
return base64_encode($salt . $encrypted_data);
}

class EncryptedSessionHandler extends SessionHandler
{
private $key;

public function __construct($key)
{
$this->key = $key;
}

public function read($id)
{
$data = parent::read($id);

if (!$data) {
return "";
} else {
return decrypt($data, $this->key);
}
}

public function write($id, $data)
{
$data = encrypt($data, $this->key);

return parent::write($id, $data);
}
}

// この例では標準の 'files' ハンドラを横取りしていますが、他のネイティブハンドラである
// PHP 拡張モジュール 'sqlite'、'memcache'、'memcached'
// の場合でもまったく同じように使えます。
ini_set('session.save_handler', 'files');

$key = 'secret_string';
$handler = new EncryptedSessionHandler($key);
session_set_save_handler($handler, true);
session_start();

// $_SESSION への値の設定や格納されている値の取得を進めます

注意:

このクラスのメソッドは、セッション処理の一環として PHP が内部的にコールするためのものとして作られています。 そのため、子クラスから親のメソッド (実際のネイティブハンドラ) をコールすると、 (自動で開始するか、あるいは session_start() を実行するなどして) セッションを実際に開始していない限りはその戻り値が false となります。 この点は、ユニットテストを書く際に注意が必要です。というのも、 ユニットテストではクラスのメソッドを手動でコールする可能性があるからです。

目次

  • SessionHandler::close — セッションを閉じる
  • SessionHandler::create_sid — 新規セッション ID を返す
  • SessionHandler::destroy — セッションを破棄する
  • SessionHandler::gc — 古いセッションを削除する
  • SessionHandler::open — セッションを開始する
  • SessionHandler::read — セッションのデータを読み込む
  • SessionHandler::write — セッションのデータを書き込む


セッションを閉じる

  • ≪ SessionHandler
  • SessionHandler::create_sid ≫
  • PHP Manual
  • SessionHandler
  • セッションを閉じる

SessionHandler::close

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::close — セッションを閉じる

説明

public SessionHandler::close(): bool

現在のセッションを閉じます。この関数はセッションを閉じるときに自動的に実行されます。 あるいは、明示的に session_write_close() 経由で実行することもできます (このときは、まず最初に SessionHandler::write() をコールします)。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の close メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしたりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::close() のドキュメントを参照ください。

パラメータ

この関数にはパラメータはありません。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。


新規セッション ID を返す

  • ≪ SessionHandler::close
  • SessionHandler::destroy ≫
  • PHP Manual
  • SessionHandler
  • 新規セッション ID を返す

SessionHandler::create_sid

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

SessionHandler::create_sid — 新規セッション ID を返す

説明

public SessionHandler::create_sid(): string

新規セッション ID を生成して返します。

パラメータ

この関数にはパラメータはありません。

戻り値

デフォルトのセッション・ハンドラに対して有効なセッションです。

参考

  • session_id() - 現在のセッション ID を取得または設定する
  • session_create_id() - 新しいセッションIDを作成する


セッションを破棄する

  • ≪ SessionHandler::create_sid
  • SessionHandler::gc ≫
  • PHP Manual
  • SessionHandler
  • セッションを破棄する

SessionHandler::destroy

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::destroy — セッションを破棄する

説明

public SessionHandler::destroy(string $id): bool

セッションを破棄します。session_regenerate_id() ($destory を true にしたとき) や session_destroy() からコールされ、session_decode() が失敗したときにもコールされます。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の destroy メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::destroy() のドキュメントを参照ください。

パラメータ

id

破棄するセッション ID。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。


古いセッションを削除する

  • ≪ SessionHandler::destroy
  • SessionHandler::open ≫
  • PHP Manual
  • SessionHandler
  • 古いセッションを削除する

SessionHandler::gc

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::gc — 古いセッションを削除する

説明

public SessionHandler::gc(int $max_lifetime): int|false

有効期限を過ぎたセッションを削除します。PHP がセッションを開始したとき、あるいは session_start() を実行したときにコールされます。 コールされる頻度は、session.gc_divisor および session.gc_probability の設定に基づいて決まります。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の gc メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::gc() のドキュメントを参照ください。

パラメータ

max_lifetime

直近の max_lifetime 秒の間に更新されていないセッションを削除します。

戻り値

成功時には、削除されたセッションの数を返します。 失敗した場合に false を返します。 この値は、処理を続けるために PHP の内部にも返される点に注意して下さい。

変更履歴

バージョン | 説明
7.1.0 | これより前のバージョンでは、この関数は成功時に true を返していました。


セッションを開始する

  • ≪ SessionHandler::gc
  • SessionHandler::read ≫
  • PHP Manual
  • SessionHandler
  • セッションを開始する

SessionHandler::open

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::open — セッションを開始する

説明

public SessionHandler::open(string $path, string $name): bool

新しいセッションを作成するか、あるいは既存のセッションを再度初期化します。 PHP が自動的にセッションを開始させたり、あるいは session_start() を実行したときにコールされます。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の open メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したりできます。

このメソッドに関する詳細は、 SessionHandlerInterface::open() のドキュメントを参照ください。

パラメータ

path

セッションを格納/取得するパス。

name

セッション名。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session.auto-start


セッションのデータを読み込む

  • ≪ SessionHandler::open
  • SessionHandler::write ≫
  • PHP Manual
  • SessionHandler
  • セッションのデータを読み込む

SessionHandler::read

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::read — セッションのデータを読み込む

説明

public SessionHandler::read(string $id): string|false

セッションのデータをセッションストレージから読み込み、その結果を PHP の内部処理用に返します。 このメソッドは PHP がセッションを自動的に開始したとき、あるいは session_start() を実行したときにコールされ、内部的に SessionHandler::open() で処理されます。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の read メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したり (親の read メソッドが返す $data を復号したりなど) できます。

このメソッドに関する詳細は、 SessionHandlerInterface::read() のドキュメントを参照ください。

パラメータ

id

データを読み込むセッションの id。

戻り値

読み込んだデータを常に文字列で返します。何も読まなかった場合は false を返さなければなりません。 この値は、PHP の内部で処理されるものであることに注意しましょう。

参考

  • session.serialize_handler


セッションのデータを書き込む

  • ≪ SessionHandler::read
  • SessionHandlerInterface ≫
  • PHP Manual
  • SessionHandler
  • セッションのデータを書き込む

SessionHandler::write

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandler::write — セッションのデータを書き込む

説明

public SessionHandler::write(string $id, string $data): bool

セッションのデータをセッションストレージに書き込みます。
リクエストの終了時や session_write_close() を実行したとき、そして
session_register_shutdown() が失敗したときにコールされます。
PHP は、このメソッドの戻り値を受け取るとすぐに SessionHandler::close() をコールします。

このメソッドは、このハンドラが session_set_save_handler() で設定される前に ini 設定 session.save_handler で定義されていた PHP の保存ハンドラをラップします。

このクラスを継承して拡張する場合は、親の write メソッドをコールすればこのメソッドのラッパーを実行でき、それに付随する内部コールバックも実行されます。 こうすれば、メソッドをオーバーライドしたり処理を横取りしてフィルタを追加したり (親の write メソッドに送る前に $data を暗号化したりなど) できます。

このメソッドに関する詳細は、 SessionHandlerInterface::write() のドキュメントを参照ください。

パラメータ

id

セッション id。

data

エンコードされたセッションのデータ。 これは、PHP が内部的にスーパーグローバル $_SESSION をエンコードしてシリアライズし、それを渡したものです。 セッションが使うシリアライズ方式は、通常のシリアライズとは別のものであることに注意しましょう。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session.serialize_handler


SessionHandlerInterface クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

SessionHandlerInterface は カスタムセッションハンドラを作成する際の最低限のプロトタイプを定義したインターフェイスです。 自作のセッションハンドラを オブジェクト指向型 の起動方法で session_set_save_handler() に渡すために、このインターフェイスを実装することができます。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。

インターフェイス概要

interface SessionHandlerInterface {
/* メソッド */
public close(): bool
public destroy(string $id): bool
public gc(int $max_lifetime): int|false
public open(string $path, string $name): bool
public read(string $id): string|false
public write(string $id, string $data): bool
}

例

例1 SessionHandlerInterface の使用例

この例では、ファイルベースのセッションストレージをつくります。これは PHP のデフォルトのセッション保存ハンドラである files と似たものです。この例をさらに拡張すれば、 PHP がサポートするお好みのデータベースを使ってセッションを保存させるようにするのも簡単です。

session_set_save_handler() でオブジェクト指向型のプロトタイプを使っていることと、 シャットダウン関数をその parameter フラグで登録していることに注目しましょう。 オブジェクトをセッション保存ハンドラとして使うときには、この方法をおすすめします。

警告

コードを簡潔にするため、以下の例では入力値の検証を省略しています。 しかし、$id パラメータは パストラバーサル問題のような脆弱性を避けるために、 適切な 検証/無害化 が必須になる値です。 よって、ここで示した例を改変することなく、 本番の実環境で用いないでください

<?php
class MySessionHandler implements SessionHandlerInterface
{
private $savePath;

public function open($savePath, $sessionName): bool
{
$this->savePath = $savePath;
if (!is_dir($this->savePath)) {
mkdir($this->savePath, 0777);
}

return true;
}

public function close(): bool
{
return true;
}

#[\ReturnTypeWillChange]
public function read($id)
{
return (string)@file_get_contents("$this->savePath/sess_$id");
}

public function write($id, $data): bool
{
return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
}

public function destroy($id): bool
{
$file = "$this->savePath/sess_$id";
if (file_exists($file)) {
unlink($file);
}

return true;
}

#[\ReturnTypeWillChange]
public function gc($maxlifetime)
{
foreach (glob("$this->savePath/sess_*") as $file) {
if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
unlink($file);
}
}

return true;
}
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// $_SESSION への値の設定や格納されている値の取得を進めます

目次

  • SessionHandlerInterface::close — セッションを閉じる
  • SessionHandlerInterface::destroy — セッションを破棄する
  • SessionHandlerInterface::gc — 古いセッションを削除する
  • SessionHandlerInterface::open — セッションを開始する
  • SessionHandlerInterface::read — セッションのデータを読み込む
  • SessionHandlerInterface::write — セッションのデータを書き込む


セッションを閉じる

  • ≪ SessionHandlerInterface
  • SessionHandlerInterface::destroy ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションを閉じる

SessionHandlerInterface::close

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::close — セッションを閉じる

説明

public SessionHandlerInterface::close(): bool

現在のセッションを閉じます。この関数はセッションを閉じるときに自動的に実行されます。 あるいは、明示的に session_write_close() 経由で実行することもできます。

パラメータ

この関数にはパラメータはありません。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。


セッションを破棄する

  • ≪ SessionHandlerInterface::close
  • SessionHandlerInterface::gc ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションを破棄する

SessionHandlerInterface::destroy

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::destroy — セッションを破棄する

説明

public SessionHandlerInterface::destroy(string $id): bool

セッションを破棄します。session_regenerate_id() ($destroy = true) や session_destroy() からコールされ、session_decode() が失敗したときにもコールされます。

パラメータ

id

破棄するセッション ID。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。


古いセッションを削除する

  • ≪ SessionHandlerInterface::destroy
  • SessionHandlerInterface::open ≫
  • PHP Manual
  • SessionHandlerInterface
  • 古いセッションを削除する

SessionHandlerInterface::gc

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::gc — 古いセッションを削除する

説明

public SessionHandlerInterface::gc(int $max_lifetime): int|false

有効期限を過ぎたセッションを削除します。 session.gc_divisor、 session.gc_probability および session.gc_maxlifetime の設定に基づいて、 session_start() からコールされます。

パラメータ

max_lifetime

直近の max_lifetime 秒の間に更新されていないセッションを削除します。

戻り値

成功時に、削除したセッションの数を返します。 失敗した場合に false を返します。 この値は、処理を続けるために PHP の内部にも返される点に注意して下さい。

変更履歴

バージョン | 説明
7.1.0 | これより前のバージョンでは、この関数は成功時に true を返していました。


セッションを開始する

  • ≪ SessionHandlerInterface::gc
  • SessionHandlerInterface::read ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションを開始する

SessionHandlerInterface::open

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::open — セッションを開始する

説明

public SessionHandlerInterface::open(string $path, string $name): bool

既存のセッションを再度初期化するか、あるいは新しいセッションを作成します。 セッションが開始したり session_start() が実行されたりしたときにコールされます。

パラメータ

path

セッションを格納/取得するパス。

name

セッション名。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session_name() - 現在のセッション名を取得または設定する
  • session.auto-start


セッションのデータを読み込む

  • ≪ SessionHandlerInterface::open
  • SessionHandlerInterface::write ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションのデータを読み込む

SessionHandlerInterface::read

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::read — セッションのデータを読み込む

説明

public SessionHandlerInterface::read(string $id): string|false

セッションのデータをセッションストレージから読み込み、その結果を返します。 セッションを開始した直後、あるいは session_start() を実行したときにコールされます。 このメソッドがコールされる直前に SessionHandlerInterface::open() が実行されることに注意しましょう。

このメソッドは、セッションが開始するときに PHP 自身がコールします。 このメソッドは、指定したセッション ID のセッションデータをストレージから取得しなければなりません。 返す文字列の書式は、SessionHandlerInterface::write() に渡されたものと同様にシリアライズされたものでなければなりません。 データが見つからない場合は false を返します。

このメソッドが返すデータは、PHP が内部的にデコードします。デコードに使うメソッドは session.serialize_handler で指定します。デコードした結果をスーパーグローバル $_SESSION に格納します。

シリアライズ方式は unserialize() とは異なっており、アクセスするためには session_decode() を使うことに注意しましょう。

パラメータ

id

セッション id。

戻り値

読み込んだデータをエンコードした文字列を返します。 何も読まなかった場合は false を返さなければなりません。 この値は、PHP が内部的に使うためだけのものであることに注意しましょう。

参考

  • session.serialize_handler


セッションのデータを書き込む

  • ≪ SessionHandlerInterface::read
  • SessionIdInterface ≫
  • PHP Manual
  • SessionHandlerInterface
  • セッションのデータを書き込む

SessionHandlerInterface::write

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SessionHandlerInterface::write — セッションのデータを書き込む

説明

public SessionHandlerInterface::write(string $id, string $data): bool

セッションのデータをセッションストレージに書き込みます。
session_write_close() からコールされ、
session_register_shutdown() が失敗したときや通常のシャットダウン時にもコールされます。
SessionHandlerInterface::close() がこの関数の直後にコールされることに注意しましょう。

PHP は、セッションの保存と終了の準備ができたときにこのメソッドをコールします。 スーパーグローバル $_SESSION のセッションデータをエンコードして 文字列にシリアライズし、セッション ID とともにこのメソッドに渡して格納させます。 シリアライズの方式は session.serialize_handler で設定します。

このメソッドが PHP からコールされるのは、通常は出力バッファが閉じた後であることに注意しましょう。ただし、 明示的に session_write_close() をコールした場合は別です。

パラメータ

id

セッション id。

data

エンコードされたセッションデータ。 これは、PHP がスーパーグローバル $_SESSION の内容を内部的にシリアライズした結果の文字列で、それがこのパラメータに渡されます。 セッションのシリアライズには通常とは別の方式を使っていることに注意しましょう。

戻り値

返り値 (通常は、true が成功そして false が失敗を表します)。この値は PHP で内部的に処理されるものであることに注意しましょう。

参考

  • session.serialize_handler


SessionIdInterface クラス

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

はじめに

SessionIdInterface は カスタムのセッションハンドラを作成するためのオプションのメソッドを定義します。 オブジェクト指向型 の呼び出しを使い、 カスタムのセッションハンドラを session_set_save_handler() に渡すために、 このインターフェイスを実装することができます。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。

インターフェイス概要

interface SessionIdInterface {
/* メソッド */
public create_sid(): string
}

目次

  • SessionIdInterface::create_sid — セッションIDを作成する


セッションIDを作成する

  • ≪ SessionIdInterface
  • SessionUpdateTimestampHandlerInterface ≫
  • PHP Manual
  • SessionIdInterface
  • セッションIDを作成する

SessionIdInterface::create_sid

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

SessionIdInterface::create_sid — セッションIDを作成する

説明

public SessionIdInterface::create_sid(): string

新しい セッションID を生成します。 この関数は、新しい セッションID を生成する必要がある場合に自動的に実行されます。

パラメータ

この関数にはパラメータはありません。

戻り値

新しい セッションID を返します。 この値は、PHP が処理を行うために内部的に返す値であることに注意して下さい。

参考

  • SessionHandler::create_sid() - 新規セッション ID を返す


SessionUpdateTimestampHandlerInterface クラス

(PHP 7, PHP 8)

はじめに

SessionUpdateTimestampHandlerInterface は カスタムセッションハンドラを作成する際の最低限のプロトタイプを定義したインターフェイスです。 自作のセッションハンドラを オブジェクト指向型 の起動方法で session_set_save_handler() に渡すために、このインターフェイスを実装することができます。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。

クラス概要

interface SessionUpdateTimestampHandlerInterface {
/* メソッド */
public updateTimestamp(string $id, string $data): bool
public validateId(string $id): bool
}

目次

  • SessionUpdateTimestampHandlerInterface::updateTimestamp — タイムスタンプを更新する
  • SessionUpdateTimestampHandlerInterface::validateId — セッションIDを検証する


タイムスタンプを更新する

  • ≪ SessionUpdateTimestampHandlerInterface
  • SessionUpdateTimestampHandlerInterface::validateId ≫
  • PHP Manual
  • SessionUpdateTimestampHandlerInterface
  • タイムスタンプを更新する

SessionUpdateTimestampHandlerInterface::updateTimestamp

(PHP 7, PHP 8)

SessionUpdateTimestampHandlerInterface::updateTimestamp — タイムスタンプを更新する

説明

public SessionUpdateTimestampHandlerInterface::updateTimestamp(string $id, string $data): bool

セッションが最後に変更されたタイムスタンプを更新します。 この関数はセッションが更新された場合に自動的に実行されます。

パラメータ

id

セッションID

data

セッションデータ

戻り値

タイムスタンプが更新されたら true を、 そうでなければ false を返します。 この値は、PHP が処理を行うために内部的に返す値であることに注意して下さい。


セッションIDを検証する

  • ≪ SessionUpdateTimestampHandlerInterface::updateTimestamp
  • テキスト処理 ≫
  • PHP Manual
  • SessionUpdateTimestampHandlerInterface
  • セッションIDを検証する

SessionUpdateTimestampHandlerInterface::validateId

(PHP 7, PHP 8)

SessionUpdateTimestampHandlerInterface::validateId — セッションIDを検証する

説明

public SessionUpdateTimestampHandlerInterface::validateId(string $id): bool

与えられた セッションID を検証します。 そのID を持つセッションが既に存在している場合、セッションID は有効です。 この関数はセッションが開始されようとしている時に、 セッションID が与えられ、かつ session.use_strict_mode が有効な場合に自動的に実行されます。

パラメータ

id

セッションID

戻り値

セッションIDが正しければ true を、そうでなければ false を返します。 この値は、PHP が処理を行うために内部的に返す値であることに注意して下さい。


テキスト処理

  • CommonMark
    • はじめに
    • インストール/設定
    • 定義済み定数
    • CommonMark\Node\Document — Document concrete CommonMark\Node
    • CommonMark\Node\Heading — Heading concrete CommonMark\Node
    • CommonMark\Node\Paragraph — Paragraph concrete CommonMark\Node
    • CommonMark\Node\BlockQuote — BlockQuote concrete CommonMark\Node
    • CommonMark\Node\BulletList — BulletList concrete CommonMark\Node
    • CommonMark\Node\OrderedList — OrderedList concrete CommonMark\Node
    • CommonMark\Node\Item — Item concrete CommonMark\Node
    • CommonMark\Node\Text — Text concrete CommonMark\Node
    • CommonMark\Node\Text\Strong — Strong concrete CommonMark\Node
    • CommonMark\Node\Text\Emphasis — Emphasis concrete CommonMark\Node
    • CommonMark\Node\ThematicBreak — ThematicBreak concrete CommonMark\Node
    • CommonMark\Node\SoftBreak — SoftBreak concrete CommonMark\Node
    • CommonMark\Node\LineBreak — LineBreak concrete CommonMark\Node
    • CommonMark\Node\Code — Code concrete CommonMark\Node
    • CommonMark\Node\CodeBlock — CodeBlock concrete CommonMark\Node
    • CommonMark\Node\HTMLBlock — HTMLBlock concrete CommonMark\Node
    • CommonMark\Node\HTMLInline — HTMLInline concrete CommonMark\Node
    • CommonMark\Node\Image — Image concrete CommonMark\Node
    • CommonMark\Node\Link — Link concrete CommonMark\Node
    • CommonMark\Node\CustomBlock — CustomBlock concrete CommonMark\Node
    • CommonMark\Node\CustomInline — CustomInline concrete CommonMark\Node
    • CommonMark\Node — Abstract CommonMark\Node
    • CommonMark\Interfaces\IVisitor — The CommonMark\Interfaces\IVisitor interface
    • CommonMark\Interfaces\IVisitable — The CommonMark\Interfaces\IVisitable interface
    • CommonMark\Parser — The CommonMark\Parser class
    • CommonMark\CQL — The CommonMark\CQL class
    • CommonMark 関数
  • Parle — Parsing and lexing
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Pattern matching — Parle pattern matching
    • 例
    • Parle\Lexer — The Parle\Lexer class
    • Parle\RLexer — The Parle\RLexer class
    • Parle\Parser — The Parle\Parser class
    • Parle\RParser — The Parle\RParser class
    • Parle\Stack — The Parle\Stack class
    • Parle\Token — The Parle\Token class
    • Parle\ErrorInfo — The Parle\ErrorInfo class
    • Parle\LexerException — The Parle\LexerException class
    • Parle\ParserException — The Parle\ParserException class
  • PCRE — 正規表現 (Perl 互換)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • PCRE のパターン
    • PCRE 関数
  • ssdeep — ssdeep Fuzzy Hashing
    • はじめに
    • インストール/設定
    • ssdeep 関数
  • 文字列
    • はじめに
    • インストール/設定
    • 定義済み定数
    • String 関数
    • 変更履歴


CommonMark

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • CommonMark\Node\Document — Document concrete CommonMark\Node
  • CommonMark\Node\Heading — Heading concrete CommonMark\Node
    • CommonMark\Node\Heading::__construct — Heading Construction
  • CommonMark\Node\Paragraph — Paragraph concrete CommonMark\Node
  • CommonMark\Node\BlockQuote — BlockQuote concrete CommonMark\Node
  • CommonMark\Node\BulletList — BulletList concrete CommonMark\Node
    • CommonMark\Node\BulletList::__construct — BulletList Construction
  • CommonMark\Node\OrderedList — OrderedList concrete CommonMark\Node
    • CommonMark\Node\OrderedList::__construct — OrderedList Construction
  • CommonMark\Node\Item — Item concrete CommonMark\Node
  • CommonMark\Node\Text — Text concrete CommonMark\Node
    • CommonMark\Node\Text::__construct — Text Construction
  • CommonMark\Node\Text\Strong — Strong concrete CommonMark\Node
  • CommonMark\Node\Text\Emphasis — Emphasis concrete CommonMark\Node
  • CommonMark\Node\ThematicBreak — ThematicBreak concrete CommonMark\Node
  • CommonMark\Node\SoftBreak — SoftBreak concrete CommonMark\Node
  • CommonMark\Node\LineBreak — LineBreak concrete CommonMark\Node
  • CommonMark\Node\Code — Code concrete CommonMark\Node
  • CommonMark\Node\CodeBlock — CodeBlock concrete CommonMark\Node
    • CommonMark\Node\CodeBlock::__construct — CodeBlock Construction
  • CommonMark\Node\HTMLBlock — HTMLBlock concrete CommonMark\Node
  • CommonMark\Node\HTMLInline — HTMLInline concrete CommonMark\Node
  • CommonMark\Node\Image — Image concrete CommonMark\Node
    • CommonMark\Node\Image::__construct — Image Construction
  • CommonMark\Node\Link — Link concrete CommonMark\Node
    • CommonMark\Node\Link::__construct — Link Construction
  • CommonMark\Node\CustomBlock — CustomBlock concrete CommonMark\Node
  • CommonMark\Node\CustomInline — CustomInline concrete CommonMark\Node
  • CommonMark\Node — Abstract CommonMark\Node
    • CommonMark\Node::appendChild — AST Manipulation
    • CommonMark\Node::prependChild — AST Manipulation
    • CommonMark\Node::insertAfter — AST Manipulation
    • CommonMark\Node::insertBefore — AST Manipulation
    • CommonMark\Node::replace — AST Manipulation
    • CommonMark\Node::unlink — AST Manipulation
    • CommonMark\Node::accept — Visitation
  • CommonMark\Interfaces\IVisitor — The CommonMark\Interfaces\IVisitor interface
    • CommonMark\Interfaces\IVisitor::enter — Visitation
    • CommonMark\Interfaces\IVisitor::leave — Visitation
  • CommonMark\Interfaces\IVisitable — The CommonMark\Interfaces\IVisitable interface
    • CommonMark\Interfaces\IVisitable::accept — Visitation
  • CommonMark\Parser — The CommonMark\Parser class
    • CommonMark\Parser::__construct — Parsing
    • CommonMark\Parser::parse — Parsing
    • CommonMark\Parser::finish — Parsing
  • CommonMark\CQL — The CommonMark\CQL class
    • CommonMark\CQL::__construct — CQL Construction
    • CommonMark\CQL::__invoke — CQL Execution
  • CommonMark 関数
    • CommonMark\Parse — Parsing
    • CommonMark\Render — Rendering
    • CommonMark\Render\HTML — Rendering
    • CommonMark\Render\Latex — Rendering
    • CommonMark\Render\Man — Rendering
    • CommonMark\Render\XML — Rendering


はじめに

This extension provides access to the reference implementation of CommonMark, a rationalized version of Markdown syntax with a specification.

Parsing:

The CommonMark extension provides a simple parsing API:

CommonMark\Parse(string $content, int $options = ?): CommonMark\Node

Rendering:

The CommonMark extension provides simple rendering API that supports multiple formats:

CommonMark\Render(CommonMark\Node $node, int $options = ?, int $width = ?): string
CommonMark\Render\HTML(CommonMark\Node $node, int $options = ?): string
CommonMark\Render\XML(CommonMark\Node $node, int $options = ?): string
CommonMark\Render\Man(CommonMark\Node $node, int $options = ?, int $width = ?): string
CommonMark\Render\Latex(CommonMark\Node $node, int $options = ?, int $width = ?): string

AST:

The CommonMark extension implements visitation for CommonMark\Node objects:

public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void

CQL:

The CommonMark extension provides an interface to CQL, CommonMark Query Language:

public CommonMark\CQL::__construct(string $query)


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • CommonMark
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

The CommonMark extension requires the (C) reference implementation of » cmark.


インストール手順

The CommonMark extension releases are hosted by PECL and source is hosted on » github, the easiest route to installation is the normal PECL route: » https://pecl.php.net/package/cmark.

Windows users can download prebuilt release binaries from the » PECL website.

警告

Windows users need to take the additional step of adding cmark.dll (distributed with Windows releases) to their PATH.


定義済み定数

CommonMark\Parser\Normal (int)
CommonMark\Parser\Normalize (int)
CommonMark\Parser\Smart (int)
CommonMark\Parser\ValidateUTF8 (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\NoBreaks (int)
CommonMark\Render\Normal (int)
CommonMark\Render\Safe (int)
CommonMark\Render\SourcePos (int)


Document concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Document extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


Heading concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Heading extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public int $level;
/* Constructor */
public __construct()
public __construct(int $level)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\Heading::__construct — Heading Construction


Heading Construction

  • ≪ CommonMark\Node\Heading
  • CommonMark\Node\Paragraph ≫
  • PHP Manual
  • CommonMark\Node\Heading
  • Heading Construction

CommonMark\Node\Heading::__construct

(cmark >= 1.0.0)

CommonMark\Node\Heading::__construct — Heading Construction

説明

public CommonMark\Node\Heading::__construct()
public CommonMark\Node\Heading::__construct(int $level)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。


Paragraph concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Paragraph extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


BlockQuote concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\BlockQuote extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


BulletList concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\BulletList extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public bool $tight;
public int $delimiter;
/* Constructor */
public __construct()
public __construct(int $tight)
public __construct(int $tight, int $delimiter)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\BulletList::__construct — BulletList Construction


BulletList Construction

  • ≪ CommonMark\Node\BulletList
  • CommonMark\Node\OrderedList ≫
  • PHP Manual
  • CommonMark\Node\BulletList
  • BulletList Construction

CommonMark\Node\BulletList::__construct

(cmark >= 1.0.0)

CommonMark\Node\BulletList::__construct — BulletList Construction

説明

public CommonMark\Node\BulletList::__construct()
public CommonMark\Node\BulletList::__construct(int $tight)
public CommonMark\Node\BulletList::__construct(int $tight, int $delimiter)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。


OrderedList concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\OrderedList extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public bool $tight;
public int $delimiter;
public int $start;
/* Constructor */
public __construct()
public __construct(int $tight)
public __construct(int $tight, int $delimiter)
public __construct(int $tight, int $delimiter, int $start)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\OrderedList::__construct — OrderedList Construction


OrderedList Construction

  • ≪ CommonMark\Node\OrderedList
  • CommonMark\Node\Item ≫
  • PHP Manual
  • CommonMark\Node\OrderedList
  • OrderedList Construction

CommonMark\Node\OrderedList::__construct

(cmark >= 1.0.0)

CommonMark\Node\OrderedList::__construct — OrderedList Construction

説明

public CommonMark\Node\OrderedList::__construct()
public CommonMark\Node\OrderedList::__construct(int $tight)
public CommonMark\Node\OrderedList::__construct(int $tight, int $delimiter)
public CommonMark\Node\OrderedList::__construct(int $tight, int $delimiter, int $start)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tight

delimiter

start


Item concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Item extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


Text concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Text extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public ?string $literal;
/* Constructor */
public __construct()
public __construct(string $literal)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\Text::__construct — Text Construction


Text Construction

  • ≪ CommonMark\Node\Text
  • CommonMark\Node\Text\Strong ≫
  • PHP Manual
  • CommonMark\Node\Text
  • Text Construction

CommonMark\Node\Text::__construct

(cmark >= 1.0.0)

CommonMark\Node\Text::__construct — Text Construction

説明

public CommonMark\Node\Text::__construct()
public CommonMark\Node\Text::__construct(string $literal)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

literal


Strong concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Text\Strong extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


Emphasis concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Text\Emphasis extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


ThematicBreak concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\ThematicBreak extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


SoftBreak concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\SoftBreak extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


LineBreak concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\LineBreak extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


Code concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Code extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
public ?string $literal;
/* Constructor */
public CommonMark\Node\Text::__construct()
public CommonMark\Node\Text::__construct(string $literal)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


CodeBlock concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\CodeBlock extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
public ?string $literal;
/* プロパティ */
public ?string $fence;
/* Constructor */
public CommonMark\Node\Text::__construct()
public CommonMark\Node\Text::__construct(string $literal)
public __construct(string $fence, string $literal)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\CodeBlock::__construct — CodeBlock Construction


CodeBlock Construction

  • ≪ CommonMark\Node\CodeBlock
  • CommonMark\Node\HTMLBlock ≫
  • PHP Manual
  • CommonMark\Node\CodeBlock
  • CodeBlock Construction

CommonMark\Node\CodeBlock::__construct

(cmark >= 1.0.0)

CommonMark\Node\CodeBlock::__construct — CodeBlock Construction

説明

public CommonMark\Node\CodeBlock::__construct(string $fence, string $literal)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fence

literal


HTMLBlock concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\HTMLBlock extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
public ?string $literal;
/* Constructor */
public CommonMark\Node\Text::__construct()
public CommonMark\Node\Text::__construct(string $literal)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


HTMLInline concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\HTMLInline extends CommonMark\Node\Text implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
public ?string $literal;
/* Constructor */
public CommonMark\Node\Text::__construct()
public CommonMark\Node\Text::__construct(string $literal)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


Image concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Image extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public ?string $url;
public ?string $title;
/* Constructor */
public __construct()
public __construct(string $url)
public __construct(string $url, string $title)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\Image::__construct — Image Construction


Image Construction

  • ≪ CommonMark\Node\Image
  • CommonMark\Node\Link ≫
  • PHP Manual
  • CommonMark\Node\Image
  • Image Construction

CommonMark\Node\Image::__construct

(cmark >= 1.0.0)

CommonMark\Node\Image::__construct — Image Construction

説明

public CommonMark\Node\Image::__construct()
public CommonMark\Node\Image::__construct(string $url)
public CommonMark\Node\Image::__construct(string $url, string $title)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

url

title


Link concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\Link extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public ?string $url;
public ?string $title;
/* Constructor */
public __construct()
public __construct(string $url)
public __construct(string $url, string $title)
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node\Link::__construct — Link Construction


Link Construction

  • ≪ CommonMark\Node\Link
  • CommonMark\Node\CustomBlock ≫
  • PHP Manual
  • CommonMark\Node\Link
  • Link Construction

CommonMark\Node\Link::__construct

(cmark >= 1.0.0)

CommonMark\Node\Link::__construct — Link Construction

説明

public CommonMark\Node\Link::__construct()
public CommonMark\Node\Link::__construct(string $url)
public CommonMark\Node\Link::__construct(string $url, string $title)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

url

title


CustomBlock concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\CustomBlock extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public ?string $onEnter;
public ?string $onLeave;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


CustomInline concrete CommonMark\Node

(cmark >= 1.0.0)

クラス概要

final class CommonMark\Node\CustomInline extends CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* 継承したプロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* プロパティ */
public ?string $onEnter;
public ?string $onLeave;
/* 継承したメソッド */
public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node
public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node
public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node
public CommonMark\Node::unlink(): void
public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void
}


Abstract CommonMark\Node

(cmark >= 1.0.0)

はじめに

Represents an Abstract Node, this final abstract is not for direct use by the programmer.

クラス概要

final abstract class CommonMark\Node implements CommonMark\Interfaces\IVisitable, Traversable {
/* プロパティ */
public readonly ?Node $parent;
public readonly ?Node $previous;
public readonly ?Node $next;
public readonly ?Node $lastChild;
public readonly ?Node $firstChild;
public readonly int $startLine;
public readonly int $endLine;
public readonly int $startColumn;
public readonly int $endColumn;
/* メソッド */
public appendChild(CommonMark\Node $child): CommonMark\Node
public prependChild(CommonMark\Node $child): CommonMark\Node
public insertAfter(CommonMark\Node $sibling): CommonMark\Node
public insertBefore(CommonMark\Node $sibling): CommonMark\Node
public replace(CommonMark\Node $target): CommonMark\Node
public unlink(): void
public accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Node::appendChild — AST Manipulation
  • CommonMark\Node::prependChild — AST Manipulation
  • CommonMark\Node::insertAfter — AST Manipulation
  • CommonMark\Node::insertBefore — AST Manipulation
  • CommonMark\Node::replace — AST Manipulation
  • CommonMark\Node::unlink — AST Manipulation
  • CommonMark\Node::accept — Visitation


AST Manipulation

  • ≪ CommonMark\Node
  • CommonMark\Node::prependChild ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::appendChild

(cmark >= 1.0.0)

CommonMark\Node::appendChild — AST Manipulation

説明

public CommonMark\Node::appendChild(CommonMark\Node $child): CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

child

戻り値


AST Manipulation

  • ≪ CommonMark\Node::appendChild
  • CommonMark\Node::insertAfter ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::prependChild

(cmark >= 1.0.0)

CommonMark\Node::prependChild — AST Manipulation

説明

public CommonMark\Node::prependChild(CommonMark\Node $child): CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

child

戻り値


AST Manipulation

  • ≪ CommonMark\Node::prependChild
  • CommonMark\Node::insertBefore ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::insertAfter

(cmark >= 1.0.0)

CommonMark\Node::insertAfter — AST Manipulation

説明

public CommonMark\Node::insertAfter(CommonMark\Node $sibling): CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sibling

戻り値


AST Manipulation

  • ≪ CommonMark\Node::insertAfter
  • CommonMark\Node::replace ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::insertBefore

(cmark >= 1.0.0)

CommonMark\Node::insertBefore — AST Manipulation

説明

public CommonMark\Node::insertBefore(CommonMark\Node $sibling): CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sibling

戻り値


AST Manipulation

  • ≪ CommonMark\Node::insertBefore
  • CommonMark\Node::unlink ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::replace

(cmark >= 1.0.0)

CommonMark\Node::replace — AST Manipulation

説明

public CommonMark\Node::replace(CommonMark\Node $target): CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

target

戻り値


AST Manipulation

  • ≪ CommonMark\Node::replace
  • CommonMark\Node::accept ≫
  • PHP Manual
  • CommonMark\Node
  • AST Manipulation

CommonMark\Node::unlink

(cmark >= 1.0.0)

CommonMark\Node::unlink — AST Manipulation

説明

public CommonMark\Node::unlink(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Visitation

  • ≪ CommonMark\Node::unlink
  • CommonMark\Interfaces\IVisitor ≫
  • PHP Manual
  • CommonMark\Node
  • Visitation

CommonMark\Node::accept

(cmark >= 1.0.0)

CommonMark\Node::accept — Visitation

説明

public CommonMark\Node::accept(CommonMark\Interfaces\IVisitor $visitor): void

パラメータ

visitor

An object implementing CommonMark\Interfaces\IVisitor

参考

  • CommonMark\Interfaces\IVisitor::enter
  • CommonMark\Interfaces\IVisitor::leave


The CommonMark\Interfaces\IVisitor interface

(cmark >= 1.0.0)

はじめに

クラス概要

final class CommonMark\Interfaces\IVisitor {
/* 定数 */
const int Done;
const int Enter;
const int Leave;
/* メソッド */
abstract public enter(IVisitable $visitable): int|IVisitable|null
abstract public leave(IVisitable $visitable): int|IVisitable|null
}

目次

  • CommonMark\Interfaces\IVisitor::enter — Visitation
  • CommonMark\Interfaces\IVisitor::leave — Visitation


Visitation

  • ≪ CommonMark\Interfaces\IVisitor
  • CommonMark\Interfaces\IVisitor::leave ≫
  • PHP Manual
  • CommonMark\Interfaces\IVisitor
  • Visitation

CommonMark\Interfaces\IVisitor::enter

(cmark >= 1.0.0)

CommonMark\Interfaces\IVisitor::enter — Visitation

説明

abstract public CommonMark\Interfaces\IVisitor::enter(IVisitable $visitable): int|IVisitable|null

パラメータ

visitable

The current CommonMark\Interfaces\IVisitable being entered

戻り値

Returning CommonMark\Interfaces\IVisitor::Done will cause the backing iterator to exit.

Returning CommonMark\Interfaces\IVisitor::Enter will reset the backing iterator at entering the current IVisitable

Returning CommonMark\Interfaces\IVisitor::Leave will reset the backing iterator at exiting the current IVisitable

Returning an IVisitable will reset the backing iterator at entering the given IVisitable

Returning nothing will allow the backing iterator to continue

参考

  • CommonMark\Interfaces\IVisitable::accept


Visitation

  • ≪ CommonMark\Interfaces\IVisitor::enter
  • CommonMark\Interfaces\IVisitable ≫
  • PHP Manual
  • CommonMark\Interfaces\IVisitor
  • Visitation

CommonMark\Interfaces\IVisitor::leave

(cmark >= 1.0.0)

CommonMark\Interfaces\IVisitor::leave — Visitation

説明

abstract public CommonMark\Interfaces\IVisitor::leave(IVisitable $visitable): int|IVisitable|null

パラメータ

visitable

The current CommonMark\Interfaces\IVisitable being exited

戻り値

Returning CommonMark\Interfaces\IVisitor::Done will cause the backing iterator to exit.

Returning CommonMark\Interfaces\IVisitor::Enter will reset the backing iterator at entering the current IVisitable

Returning CommonMark\Interfaces\IVisitor::Leave will reset the backing iterator at exiting the current IVisitable

Returning an IVisitable will reset the backing iterator at exiting the given IVisitable

Returning nothing will allow the backing iterator to continue

参考

  • CommonMark\Interfaces\IVisitable::accept


The CommonMark\Interfaces\IVisitable interface

(cmark >= 1.0.0)

はじめに

クラス概要

final class CommonMark\Interfaces\IVisitable {
abstract public accept(CommonMark\Interfaces\IVisitor $visitor): void
}

目次

  • CommonMark\Interfaces\IVisitable::accept — Visitation


Visitation

  • ≪ CommonMark\Interfaces\IVisitable
  • CommonMark\Parser ≫
  • PHP Manual
  • CommonMark\Interfaces\IVisitable
  • Visitation

CommonMark\Interfaces\IVisitable::accept

(cmark >= 1.0.0)

CommonMark\Interfaces\IVisitable::accept — Visitation

説明

abstract public CommonMark\Interfaces\IVisitable::accept(CommonMark\Interfaces\IVisitor $visitor): void

パラメータ

visitor

An object implementing CommonMark\Interfaces\IVisitor

参考

  • CommonMark\Interfaces\IVisitor::enter
  • CommonMark\Interfaces\IVisitor::leave


The CommonMark\Parser class

(cmark >= 1.0.0)

はじめに

Provides an incremental parser as an alternative to the simple Parsing API function

クラス概要

final class CommonMark\Parser {
/* Constructor */
public __construct(int $options = ?)
/* メソッド */
public parse(string $buffer): void
public finish(): CommonMark\Node
}

目次

  • CommonMark\Parser::__construct — Parsing
  • CommonMark\Parser::parse — Parsing
  • CommonMark\Parser::finish — Parsing


Parsing

  • ≪ CommonMark\Parser
  • CommonMark\Parser::parse ≫
  • PHP Manual
  • CommonMark\Parser
  • Parsing

CommonMark\Parser::__construct

(cmark >= 1.0.0)

CommonMark\Parser::__construct — Parsing

説明

public CommonMark\Parser::__construct(int $options = ?)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

options

A mask of:

CommonMark\Parser\Normal (int)
CommonMark\Parser\Normalize (int)
CommonMark\Parser\ValidateUTF8 (int)
CommonMark\Parser\Smart (int)


Parsing

  • ≪ CommonMark\Parser::__construct
  • CommonMark\Parser::finish ≫
  • PHP Manual
  • CommonMark\Parser
  • Parsing

CommonMark\Parser::parse

(cmark >= 1.0.0)

CommonMark\Parser::parse — Parsing

説明

public CommonMark\Parser::parse(string $buffer): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

buffer

戻り値


Parsing

  • ≪ CommonMark\Parser::parse
  • CommonMark\CQL ≫
  • PHP Manual
  • CommonMark\Parser
  • Parsing

CommonMark\Parser::finish

(cmark >= 1.0.0)

CommonMark\Parser::finish — Parsing

説明

public CommonMark\Parser::finish(): CommonMark\Node

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


The CommonMark\CQL class

(cmark >= 1.1.0)

はじめに

CommonMark Query Language is a DSL for describing how to travel through a CommonMark Node tree implemented as a parser and compiler for a small set of instructions, and a virtual machine for executing those instructions.

Paths:

In it's most simplistic form, a CQL query combines the following paths and / to describe how to travel through a tree:

  • firstChild
  • lastChild
  • previous
  • next
  • parent
For example, /firstChild/lastChild would travel to the last child node of the first child node.

Loops

CQL can be instructed to loop, for example through the children of, or siblings to a particular node, by using the path children, or siblings. For example, /firstChild/children will travel to all the children of the first child node.

Subqueries

CQL can be instructed how to travel by using a subquery like [/firstChild]. For example, /firstChild/children[/firstChild] will travel to the first child node of all the children of the first child node.

Loop Constraints

While looping, CQL can be instructed to constrict the travelled path to nodes of particular type. For example /children(BlockQuote) will travel to the children of a node where the type is BlockQuote. The following types are recognized (case insensitively):

  • BlockQuote
  • List
  • Item
  • CodeBlock
  • HtmlBlock
  • CustomBlock
  • Paragraph
  • Heading
  • ThematicBreak
  • Text
  • SoftBreak
  • LineBreak
  • Code
  • HtmlInline
  • CustomInline
  • Emphasis
  • Strong
  • Link
  • Image
Types may be used as a union, for example /children(BlockQuote|List) will travel to the children of a node where the type is BlockQuote or List. Types, or unions of types, may be also negated. For example /children(~BlockQuote) will travel to the children of a node where the type is not BlockQuote, and /children(~BlockQuote|Paragraph) will travel to the children of a node where the type is not BlockQuote or Paragraph

Path Constraints

CQL can be instructed to create a loop to travel to a node of a particular type, at a particular path. For example, /firstChild(BlockQuote) will travel to the first child node where the type is BlockQuote. Note that like other loops for children and siblings, this kind of path can only be followed by a subquery.

Implementation Notes

While CQL has been implemented as part of the PHP CommonMark extension, it stands separately from PHP and does not use PHP's virtual machine or internal representation of values.

クラス概要

class CommonMark\CQL {
/* Constructor */
public __construct(string $query)
/* メソッド */
public __invoke(CommonMark\Node $root, callable $handler)
}

目次

  • CommonMark\CQL::__construct — CQL Construction
  • CommonMark\CQL::__invoke — CQL Execution


CQL Construction

  • ≪ CommonMark\CQL
  • CommonMark\CQL::__invoke ≫
  • PHP Manual
  • CommonMark\CQL
  • CQL Construction

CommonMark\CQL::__construct

(cmark >= 1.1.0)

CommonMark\CQL::__construct — CQL Construction

説明

public CommonMark\CQL::__construct(string $query)

パラメータ

query

a CQL string


CQL Execution

  • ≪ CommonMark\CQL::__construct
  • CommonMark 関数 ≫
  • PHP Manual
  • CommonMark\CQL
  • CQL Execution

CommonMark\CQL::__invoke

(cmark >= 1.1.0)

CommonMark\CQL::__invoke — CQL Execution

説明

public CommonMark\CQL::__invoke(CommonMark\Node $root, callable $handler)

Shall invoke the current CQL function on the given root, executing the given handler on entry to a CommonMark\Node

パラメータ

root

the root node of a tree

handler

should have the prototype:

handler(CommonMark\Node $root, CommonMark\Node $entering): ?bool
  • Should handler fail to return (void), or return null, CQL will continue executing
  • Should the handler return a truthy value, CQL will continue executing.
  • Should the handler return a falsy value, CQL will stop executing


CommonMark 関数

目次

  • CommonMark\Parse — Parsing
  • CommonMark\Render — Rendering
  • CommonMark\Render\HTML — Rendering
  • CommonMark\Render\Latex — Rendering
  • CommonMark\Render\Man — Rendering
  • CommonMark\Render\XML — Rendering


Parsing

  • ≪ CommonMark 関数
  • CommonMark\Render ≫
  • PHP Manual
  • CommonMark 関数
  • Parsing

CommonMark\Parse

(cmark >= 1.0.0)

CommonMark\Parse — Parsing

説明

CommonMark\Parse(string $content, int $options = ?): CommonMark\Node

Shall parse content

パラメータ

content

markdown string

options

A mask of:

CommonMark\Parser\Normal (int)
CommonMark\Parser\Normalize (int)
CommonMark\Parser\ValidateUTF8 (int)
CommonMark\Parser\Smart (int)

戻り値

Shall return root CommonMark\Node


Rendering

  • ≪ CommonMark\Parse
  • CommonMark\Render\HTML ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render

(cmark >= 1.0.0)

CommonMark\Render — Rendering

説明

CommonMark\Render(CommonMark\Node $node, int $options = ?, int $width = ?): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)
width

戻り値


Rendering

  • ≪ CommonMark\Render
  • CommonMark\Render\Latex ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\HTML

(cmark >= 1.0.0)

CommonMark\Render\HTML — Rendering

説明

CommonMark\Render\HTML(CommonMark\Node $node, int $options = ?): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)

戻り値


Rendering

  • ≪ CommonMark\Render\HTML
  • CommonMark\Render\Man ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\Latex

(cmark >= 1.0.0)

CommonMark\Render\Latex — Rendering

説明

CommonMark\Render\Latex(CommonMark\Node $node, int $options = ?, int $width = ?): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)
width

戻り値


Rendering

  • ≪ CommonMark\Render\Latex
  • CommonMark\Render\XML ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\Man

(cmark >= 1.0.0)

CommonMark\Render\Man — Rendering

説明

CommonMark\Render\Man(CommonMark\Node $node, int $options = ?, int $width = ?): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)
width

戻り値


Rendering

  • ≪ CommonMark\Render\Man
  • Parle ≫
  • PHP Manual
  • CommonMark 関数
  • Rendering

CommonMark\Render\XML

(cmark >= 1.0.0)

CommonMark\Render\XML — Rendering

説明

CommonMark\Render\XML(CommonMark\Node $node, int $options = ?): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

node

options

A mask of:

CommonMark\Render\Normal (int)
CommonMark\Render\SourcePos (int)
CommonMark\Render\HardBreaks (int)
CommonMark\Render\Safe (int)
CommonMark\Render\NoBreaks (int)

戻り値


Parsing and lexing

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • Pattern matching — Parle pattern matching
  • 例
    • Lexer examples
    • Parser examples
  • Parle\Lexer — The Parle\Lexer class
    • Parle\Lexer::advance — Process next lexer rule
    • Parle\Lexer::build — Finalize the lexer rule set
    • Parle\Lexer::callout — Define token callback
    • Parle\Lexer::consume — Pass the data for processing
    • Parle\Lexer::dump — Dump the state machine
    • Parle\Lexer::getToken — Retrieve the current token
    • Parle\Lexer::insertMacro — Insert regex macro
    • Parle\Lexer::push — Add a lexer rule
    • Parle\Lexer::reset — Reset lexer
  • Parle\RLexer — The Parle\RLexer class
    • Parle\RLexer::advance — Process next lexer rule
    • Parle\RLexer::build — Finalize the lexer rule set
    • Parle\RLexer::callout — Define token callback
    • Parle\RLexer::consume — Pass the data for processing
    • Parle\RLexer::dump — Dump the state machine
    • Parle\RLexer::getToken — Retrieve the current token
    • Parle\RLexer::insertMacro — Insert regex macro
    • Parle\RLexer::push — Add a lexer rule
    • Parle\RLexer::pushState — Push a new start state
    • Parle\RLexer::reset — Reset lexer
  • Parle\Parser — The Parle\Parser class
    • Parle\Parser::advance — Process next parser rule
    • Parle\Parser::build — Finalize the grammar rules
    • Parle\Parser::consume — Consume the data for processing
    • Parle\Parser::dump — Dump the grammar
    • Parle\Parser::errorInfo — Retrieve the error information
    • Parle\Parser::left — Declare a token with left-associativity
    • Parle\Parser::nonassoc — Declare a token with no associativity
    • Parle\Parser::precedence — Declare a precedence rule
    • Parle\Parser::push — Add a grammar rule
    • Parle\Parser::reset — Reset parser state
    • Parle\Parser::right — Declare a token with right-associativity
    • Parle\Parser::sigil — Retrieve a matching part of a rule
    • Parle\Parser::sigilCount — Number of elements in matched rule
    • Parle\Parser::sigilName — Retrieve a rule or token name
    • Parle\Parser::token — Declare a token
    • Parle\Parser::tokenId — Get token id
    • Parle\Parser::trace — Trace the parser operation
    • Parle\Parser::validate — Validate input
  • Parle\RParser — The Parle\RParser class
    • Parle\RParser::advance — Process next parser rule
    • Parle\RParser::build — Finalize the grammar rules
    • Parle\RParser::consume — Consume the data for processing
    • Parle\RParser::dump — Dump the grammar
    • Parle\RParser::errorInfo — Retrieve the error information
    • Parle\RParser::left — Declare a token with left-associativity
    • Parle\RParser::nonassoc — Declare a token with no associativity
    • Parle\RParser::precedence — Declare a precedence rule
    • Parle\RParser::push — Add a grammar rule
    • Parle\RParser::reset — Reset parser state
    • Parle\RParser::right — Declare a token with right-associativity
    • Parle\RParser::sigil — Retrieve a matching part of a rule
    • Parle\RParser::sigilCount — Number of elements in matched rule
    • Parle\RParser::sigilName — Retrieve a rule or token name
    • Parle\RParser::token — Declare a token
    • Parle\RParser::tokenId — Get token id
    • Parle\RParser::trace — Trace the parser operation
    • Parle\RParser::validate — Validate input
  • Parle\Stack — The Parle\Stack class
    • Parle\Stack::pop — Pop an item from the stack
    • Parle\Stack::push — Push an item into the stack
  • Parle\Token — The Parle\Token class
  • Parle\ErrorInfo — The Parle\ErrorInfo class
  • Parle\LexerException — The Parle\LexerException class
  • Parle\ParserException — The Parle\ParserException class


はじめに

The parle extension provides general purpose lexing and parsing facilities. The implementation is based on » Ben Hanson's libraries and requires a » C++14 capable compiler. The lexer is based on the regex matching, the parser is LALR(1). Lexers and parsers are generated on the fly and can be used immediately after they've been finalized. Parle deals with parsing and lexing, the appropriate data structures representation and processing are the implementer's task. Serialization and code generation are not supported by the extension, yet.

Lexer analysis is a process of splitting a character sequence into a list of lexemes. The lexeme list can be then used for the syntax analysis against a formal grammar. These operations are also known as lexing and parsing. This documentation doesn't aim to provide an exhaustive information on lexing and parsing. Good information in this regard is available on the numerous resources on the net. Several usage examples are included, to show the functionality. The extension is useful for PHP programmers both willing to learn or to utilize parsing and lexing. State machines and grammar parsing don't have to be implemented manually, these complex tasks are taken away by parle. Thanks to that, the development can be focused on the actual problem solving.

The common use case for parle is, when a data format is too complex to be handled by the regex matching with PCRE. The practical application is herewith wide. Be it a specific data format, a behavior modification of existing functions, even an own programming language and beyond. The helper methods such as Parle\Lexer::dump() to inspect the generated state machine, or Parle\Parser::dump() to inspect the generated grammar, are useful. The method Parle\Parser::trace() can also be used to track the parsing operation.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Parle
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

PHP 7.4 or above is supported. A C++14 capable compiler is required. A successful extension build was produced with at least clang 5.0, GCC 5.0 and Visual Studio 2015.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/parle.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/parle/.

Available configure options
Option | Description
--enable-parle | Enable parle extension.
--enable-parle-utf32 | Enable internal UTF-32 support. Available since parle 0.7.2.


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Parle\INTERNAL_UTF32 bool
Flag whether the internal UTF-32 support is compiled in. Available since parle 0.7.2.


Parle pattern matching

Parle supports regex matching similar to flex. Also supported are the following POSIX character sets: [:alnum:], [:alpha:], [:blank:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], [:xdigit:] .

The Unicode character classes are currently not enabled by default, pass --enable-parle-utf32 to make them available. A particular encoding can be mapped with a correctly constructed regex. For example, to match the EURO symbol encoded in UTF-8, the regular expression [\xe2][\x82][\xac] can be used. The pattern for an UTF-8 encoded string could be [ -\x7f]{+}[\x80-\xbf]{+}[\xc2-\xdf]{+}[\xe0-\xef]{+}[\xf0-\xff]+.

Character representations

Character representations
Sequence | Description
\a | Alert (bell).
\b | Backspace.
\e | ESC character, \x1b.
\n | Newline.
\r | Carriage return.
\f | Form feed, \x0c.
\t | Horizontal tab, \x09.
\v | Vertical tab, \x0b.
\oct | Character specified by a three-digit octal code.
\xhex | Character specified by a hex code.
\cchar | Named control character.

Character classes

Character classes
Sequence | Description
[...] | A single character listed or contained within a listed range. Ranges can be combined with the {+} and {-} operators. For example [a-z]{+}[0-9] is the same as [0-9a-z] and [a-z]{-}[aeiou] is the same as [b-df-hj-np-tv-z].
[^...] | A single character not listed and not contained within a listed range.
. | Any character, default [^\n].
\d | Digit character, [0-9].
\D | Non-digit character, [^0-9].
\s | White space character, [ \t\n\r\f\v].
\S | Non-white space character, [^ \t\n\r\f\v].
\w | Word character, [a-zA-Z0-9_].
\W | Non-word character, [^a-zA-Z0-9_].

Unicode character classes

Unicode character classes
Sequence | Description
\p{C} | Other.
\p{Cc} | Other, control.
\p{Cf} | Other, format.
\p{Co} | Other, private use.
\p{Cs} | Other, surrogate.
\p{L} | Letter.
\p{LC} | Letter, cased.
\p{Ll} | Letter, lowercase.
\p{Lm} | Letter, modifier.
\p{Lo} | Letter, other.
\p{Lt} | Letter, titlecase.
\p{Lu} | Letter, uppercase.
\p{M} | Mark.
\p{Mc} | Mark, space combining.
\p{Me} | Mark, enclosing.
\p{Mn} | Mark, nonspacing.
\p{N} | Number.
\p{Nd} | Number, decimal digit.
\p{Nl} | Number, letter.
\p{No} | Number, other.
\p{P} | Punctuation.
\p{Pc} | Punctiation, connector.
\p{Pd} | Punctuation, dash.
\p{Pe} | Punctuation, close.
\p{Pf} | Punctuation, final quote.
\p{Pi} | Punctuation, initial quote.
\p{Po} | Punctuation, other.
\p{Ps} | Punctuation, open.
\p{S} | Symbol.
\p{Sc} | Symbol, currency.
\p{Sk} | Symbol, modifier.
\p{Sm} | Symbol, math.
\p{So} | Symbol, other.
\p{Z} | Separator.
\p{Zl} | Separator, line.
\p{Zp} | Separator, paragraph.
\p{Zs} | Separator, space.

These character classes are only available, if the option --enable-parle-utf32 was passed at the compilation time.

Alternation and repetition

Alternation and repetition
Sequence | Greedy | Description
...|... | - | Try sub-patterns in alternation.
* | yes | Match 0 or more times.
+ | yes | Match 1 or more times.
? | yes | Match 0 or 1 times.
{n} | no | Match exactly n times.
{n,} | yes | Match at least n times.
{n,m} | yes | Match at least n times but no more than m times.
*? | no | Match 0 or more times.
+? | no | Match 1 or more times.
?? | no | Match 0 or 1 times.
{n,}? | no | Match at least n times.
{n,m}? | no | Match at least n times but no more than m times.
{MACRO} | - | Include the regex MACRO in the current regex.

Anchors

Anchors
Sequence | Description
^ | Start of string or after a newline.
$ | End of string or before a newline.

Grouping

Grouping
Sequence | Description
(...) | Group a regular expression to override default operator precedence.
(?r-s:pattern) | Apply option r and omit option s while interpreting pattern. Options may be zero or more of the characters i, s, or x. i means case-insensitive. -i means case-sensitive. s alters the meaning of . to match any character whatsoever. -s alters the meaning of . to match any character except \n. x ignores comments and whitespace in patterns. Whitespace is ignored unless it is backslash-escaped, contained within ""s, or appears inside a character range. These options can be applied globally at the rules level by passing a combination of the bit flags to the lexer.
(?# comment ) | Omit everything within (). The first ) character encountered ends the pattern. It is not possible for the comment to contain a ) character. The comment may span lines.


  • ≪ Pattern matching
  • Lexer examples ≫
  • PHP Manual
  • Parle
  • 例

例

目次

  • Lexer examples
  • Parser examples


Lexer examples

例1 Tokenize comma separated integer list

<?php

use Parle\Token;
use Parle\Lexer;
use Parle\LexerException;

/* name => id */
$token = array(
"COMMA" => 1,
"CRLF" => 2,
"DECIMAL" => 3,
);
/* id => name */
$tokenIdToName = array_flip($token);

$lex = new Lexer;
$lex->push("[\x2c]", $token["COMMA"]);
$lex->push("[\r][\n]", $token["CRLF"]);
$lex->push("[\d]+", $token["DECIMAL"]);
$lex->build();

$in = "0,1,2\r\n3,42,5\r\n6,77,8\r\n";

$lex->consume($in);

do {
$lex->advance();
$tok = $lex->getToken();

if (Token::UNKNOWN == $tok->id) {
throw new LexerException("Unknown token '{$tok->value}' at offset {$lex->marker}.");
}

echo "TOKEN: ", $tokenIdToName[$tok->id], PHP_EOL;
} while (Token::EOI != $tok->id);

例2 Tokenize assign statement

<?php

use Parle\{Token, Lexer};

$lex = new Lexer;

$lex->push("\$[a-zA-Z_][a-zA-Z0-9_]*", 1);
$lex->push("=", 2);
$lex->push("\d+", 3);
$lex->push(";", 4);

$lex->build();

$lex->consume('$x = 42; $y = 24;');

do {
$lex->advance();
$tok = $lex->getToken();
var_dump($tok);
} while (Token::EOI != $tok->id);


Parser examples

例1 Simple calculator

<?php

use Parle\{Parser, ParserException, Lexer, Token};

$p = new Parser;
$p->token("INTEGER");
$p->left("'+' '-' '*' '/'");

$p->push("start", "exp");
$prod_add = $p->push("exp", "exp '+' exp");
$prod_sub = $p->push("exp", "exp '-' exp");
$prod_mul = $p->push("exp", "exp '*' exp");
$prod_div = $p->push("exp", "exp '/' exp");
$p->push("exp", "INTEGER"); /* Production index unused. */

$p->build();

$lex = new Lexer;
$lex->push("[+]", $p->tokenId("'+'"));
$lex->push("[-]", $p->tokenId("'-'"));
$lex->push("[*]", $p->tokenId("'*'"));
$lex->push("[/]", $p->tokenId("'/'"));
$lex->push("\\d+", $p->tokenId("INTEGER"));
$lex->push("\\s+", Token::SKIP);

$lex->build();

$exp = array(
"1 + 1",
"33 / 10",
"100 * 45",
"17 - 45",
);

foreach ($exp as $in) {
if (!$p->validate($in, $lex)) {
throw new ParserException("Failed to validate input");
}

$p->consume($in, $lex);

while (Parser::ACTION_ERROR != $p->action && Parser::ACTION_ACCEPT != $p->action) {
switch ($p->action) {
case Parser::ACTION_ERROR:
throw new ParserException("Parser error");
break;
case Parser::ACTION_SHIFT:
case Parser::ACTION_GOTO:
case Parser::ACTION_ACCEPT:
break;
case Parser::ACTION_REDUCE:
switch ($p->reduceId) {
case $prod_add:
$l = $p->sigil(0);
$r = $p->sigil(2);
echo "$l + $r = " . ($l + $r) . "\n";
break;
case $prod_sub:
$l = $p->sigil(0);
$r = $p->sigil(2);
echo "$l - $r = " . ($l - $r) . "\n";
break;
case $prod_mul:
$l = $p->sigil(0);
$r = $p->sigil(2);
echo "$l * $r = " . ($l * $r) . "\n";
break;
case $prod_div:
$l = $p->sigil(0);
$r = $p->sigil(2);
echo "$l / $r = " . ($l / $r) . "\n";
break;
}
break;
}
$p->advance();
}
}

例2 Parse words out from a sentence

<?php

use Parle\{Lexer, Token, Parser, ParserException};

$p = new Parser;
$p->token("WORD");
$p->push("START", "SENTENCE");
$p->push("SENTENCE", "WORDS");
$prod_word_0 = $p->push("WORDS", "WORDS WORD");
$prod_word_1 = $p->push("WORDS", "WORD");
$p->build();

$lex = new Lexer;
$lex->push("[^\s]{-}[\.,\:\;\?]+", $p->tokenId("WORD"));
$lex->push("[\s\.,\:\;\?]+", Token::SKIP);
$lex->build();

$in = "Dis-moi ou est ton papa?";
$p->consume($in, $lex);
do {
switch ($p->action) {
case Parser::ACTION_ERROR:
throw new ParserException("Error");
break;
case Parser::ACTION_SHIFT:
case Parser::ACTION_GOTO:
/* var_dump($p->trace());*/
break;
case Parser::ACTION_REDUCE:
$rid = $p->reduceId();
if ($rid == $prod_word_1) {
var_dump($p->sigil(0));
} if ($rid == $prod_word_0) {
var_dump($p->sigil(1));
}
break;
}
$p->advance();
} while (Parser::ACTION_ACCEPT != $p->action);


The Parle\Lexer class

(PECL parle >= 0.5.1)

はじめに

Single state lexer class. Lexemes can be defined on the fly. If the particular lexer instance is meant to be used with Parle\Parser, the token IDs need to be taken from there. Otherwise, arbitrary token IDs can be supplied. This lexer can give a certain performance advantage over Parle\RLexer, if no multiple states are required. Note, that Parle\RParser is not compatible with this lexer.

クラス概要

class Parle\Lexer {
/* 定数 */
const int ICASE = 1;
const int DOT_NOT_LF = 2;
const int DOT_NOT_CRLF = 4;
const int SKIP_WS = 8;
const int MATCH_ZERO_LEN = 16;
/* プロパティ */
public bool $bol = false;
public int $flags = 0;
public int $state = 0;
public int $marker = 0;
public int $cursor = 0;
/* メソッド */
public advance(): void
public build(): void
public callout(int $id, callable $callback): void
public consume(string $data): void
public dump(): void
public getToken(): Parle\Token
public insertMacro(string $name, string $regex): void
public push(string $regex, int $id): void
public reset(int $pos): void
}

定義済み定数

Parle\Lexer::ICASE

Parle\Lexer::DOT_NOT_LF

Parle\Lexer::DOT_NOT_CRLF

Parle\Lexer::SKIP_WS

Parle\Lexer::MATCH_ZERO_LEN

プロパティ

bol

Start of input flag.

flags

Lexer flags.

state

Current lexer state, readonly.

marker

Position of the latest token match, readonly.

cursor

Current input offset, readonly.

目次

  • Parle\Lexer::advance — Process next lexer rule
  • Parle\Lexer::build — Finalize the lexer rule set
  • Parle\Lexer::callout — Define token callback
  • Parle\Lexer::consume — Pass the data for processing
  • Parle\Lexer::dump — Dump the state machine
  • Parle\Lexer::getToken — Retrieve the current token
  • Parle\Lexer::insertMacro — Insert regex macro
  • Parle\Lexer::push — Add a lexer rule
  • Parle\Lexer::reset — Reset lexer


Process next lexer rule

  • ≪ Parle\Lexer
  • Parle\Lexer::build ≫
  • PHP Manual
  • Parle\Lexer
  • Process next lexer rule

Parle\Lexer::advance

(PECL parle >= 0.5.1)

Parle\Lexer::advance — Process next lexer rule

説明

public Parle\Lexer::advance(): void

Processes the next rule and prepares the resulting token data.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Finalize the lexer rule set

  • ≪ Parle\Lexer::advance
  • Parle\Lexer::callout ≫
  • PHP Manual
  • Parle\Lexer
  • Finalize the lexer rule set

Parle\Lexer::build

(PECL parle >= 0.5.1)

Parle\Lexer::build — Finalize the lexer rule set

説明

public Parle\Lexer::build(): void

Rules, previously added with Parle\Lexer::push() are finalized. This method call has to be done after all the necessary rules was pushed. The rule set becomes read only. The lexing can begin.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Define token callback

  • ≪ Parle\Lexer::build
  • Parle\Lexer::consume ≫
  • PHP Manual
  • Parle\Lexer
  • Define token callback

Parle\Lexer::callout

(PECL parle >= 0.7.2)

Parle\Lexer::callout — Define token callback

説明

public Parle\Lexer::callout(int $id, callable $callback): void

Define a callback to be invoked once lexer encounters a particular token.

パラメータ

id

Token id.

callback

Callable to be invoked. The callable doesn't receive any arguments and its return value is ignored.

戻り値

値を返しません。


Pass the data for processing

  • ≪ Parle\Lexer::callout
  • Parle\Lexer::dump ≫
  • PHP Manual
  • Parle\Lexer
  • Pass the data for processing

Parle\Lexer::consume

(PECL parle >= 0.5.1)

Parle\Lexer::consume — Pass the data for processing

説明

public Parle\Lexer::consume(string $data): void

Consume the data for lexing.

パラメータ

data

Data to be lexed.

戻り値

値を返しません。


Dump the state machine

  • ≪ Parle\Lexer::consume
  • Parle\Lexer::getToken ≫
  • PHP Manual
  • Parle\Lexer
  • Dump the state machine

Parle\Lexer::dump

(PECL parle >= 0.5.1)

Parle\Lexer::dump — Dump the state machine

説明

public Parle\Lexer::dump(): void

Dump the current state machine to stdout.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Retrieve the current token

  • ≪ Parle\Lexer::dump
  • Parle\Lexer::insertMacro ≫
  • PHP Manual
  • Parle\Lexer
  • Retrieve the current token

Parle\Lexer::getToken

(PECL parle >= 0.5.1)

Parle\Lexer::getToken — Retrieve the current token

説明

public Parle\Lexer::getToken(): Parle\Token

Retrieve the current token.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an instance of Parle\Token.


Insert regex macro

  • ≪ Parle\Lexer::getToken
  • Parle\Lexer::push ≫
  • PHP Manual
  • Parle\Lexer
  • Insert regex macro

Parle\Lexer::insertMacro

(PECL parle >= 0.5.1)

Parle\Lexer::insertMacro — Insert regex macro

説明

public Parle\Lexer::insertMacro(string $name, string $regex): void

Insert a regex macro, that can be later used as a shortcut and included in other regular expressions.

パラメータ

name

Name of the macros.

regex

Regular expression.

戻り値

値を返しません。


Add a lexer rule

  • ≪ Parle\Lexer::insertMacro
  • Parle\Lexer::reset ≫
  • PHP Manual
  • Parle\Lexer
  • Add a lexer rule

Parle\Lexer::push

(PECL parle >= 0.5.1)

Parle\Lexer::push — Add a lexer rule

説明

public Parle\Lexer::push(string $regex, int $id): void

Push a pattern for lexeme recognition.

パラメータ

regex

Regular expression used for token matching.

id

Token id. If the lexer instance is meant to be used standalone, this can be an arbitrary number. If the lexer instance is going to be passed to the parser, it has to be an id returned by Parle\Parser::tokenid().

戻り値

値を返しません。


Reset lexer

  • ≪ Parle\Lexer::push
  • Parle\RLexer ≫
  • PHP Manual
  • Parle\Lexer
  • Reset lexer

Parle\Lexer::reset

(PECL parle >= 0.7.1)

Parle\Lexer::reset — Reset lexer

説明

public Parle\Lexer::reset(int $pos): void

Reset lexing optionally supplying the desired offset.

パラメータ

pos

Reset position.

戻り値

値を返しません。


The Parle\RLexer class

(PECL parle >= 0.5.1)

はじめに

Multistate lexer class. Lexemes can be defined on the fly. If the particular lexer instance is meant to be used with Parle\RParser, the token IDs need to be taken from there. Otherwise, arbitrary token IDs can be supplied. Note, that Parle\Parser is not compatible with this lexer.

クラス概要

class Parle\RLexer {
/* 定数 */
const int ICASE = 1;
const int DOT_NOT_LF = 2;
const int DOT_NOT_CRLF = 4;
const int SKIP_WS = 8;
const int MATCH_ZERO_LEN = 16;
/* プロパティ */
public bool $bol = false;
public int $flags = 0;
public int $state = 0;
public int $marker = 0;
public int $cursor = 0;
/* メソッド */
public advance(): void
public build(): void
public callout(int $id, callable $callback): void
public consume(string $data): void
public dump(): void
public getToken(): Parle\Token
public insertMacro(string $name, string $regex): void
public push(string $regex, int $id): void
public push(
string $state,
string $regex,
int $id,
string $newState
): void
public push(string $state, string $regex, string $newState): void
public pushState(string $state): int
public reset(int $pos): void
}

定義済み定数

Parle\RLexer::ICASE

Parle\RLexer::DOT_NOT_LF

Parle\RLexer::DOT_NOT_CRLF

Parle\RLexer::SKIP_WS

Parle\RLexer::MATCH_ZERO_LEN

プロパティ

bol

Start of input flag.

flags

Lexer flags.

state

Current lexer state, readonly.

marker

Position of the latest token match, readonly.

cursor

Current input offset, readonly.

目次

  • Parle\RLexer::advance — Process next lexer rule
  • Parle\RLexer::build — Finalize the lexer rule set
  • Parle\RLexer::callout — Define token callback
  • Parle\RLexer::consume — Pass the data for processing
  • Parle\RLexer::dump — Dump the state machine
  • Parle\RLexer::getToken — Retrieve the current token
  • Parle\RLexer::insertMacro — Insert regex macro
  • Parle\RLexer::push — Add a lexer rule
  • Parle\RLexer::pushState — Push a new start state
  • Parle\RLexer::reset — Reset lexer


Process next lexer rule

  • ≪ Parle\RLexer
  • Parle\RLexer::build ≫
  • PHP Manual
  • Parle\RLexer
  • Process next lexer rule

Parle\RLexer::advance

(PECL parle >= 0.5.1)

Parle\RLexer::advance — Process next lexer rule

説明

public Parle\RLexer::advance(): void

Processes the next rule and prepares the resulting token data.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Finalize the lexer rule set

  • ≪ Parle\RLexer::advance
  • Parle\RLexer::callout ≫
  • PHP Manual
  • Parle\RLexer
  • Finalize the lexer rule set

Parle\RLexer::build

(PECL parle >= 0.5.1)

Parle\RLexer::build — Finalize the lexer rule set

説明

public Parle\RLexer::build(): void

Rules, previously added with Parle\RLexer::push() are finalized. This method call has to be done after all the necessary rules was pushed. The rule set becomes read only. The lexing can begin.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Define token callback

  • ≪ Parle\RLexer::build
  • Parle\RLexer::consume ≫
  • PHP Manual
  • Parle\RLexer
  • Define token callback

Parle\RLexer::callout

(PECL parle >= 0.7.2)

Parle\RLexer::callout — Define token callback

説明

public Parle\RLexer::callout(int $id, callable $callback): void

Define a callback to be invoked once lexer encounters a particular token.

パラメータ

id

Token id.

callback

Callable to be invoked. The callable doesn't receive any arguments and its return value is ignored.

戻り値

値を返しません。


Pass the data for processing

  • ≪ Parle\RLexer::callout
  • Parle\RLexer::dump ≫
  • PHP Manual
  • Parle\RLexer
  • Pass the data for processing

Parle\RLexer::consume

(PECL parle >= 0.5.1)

Parle\RLexer::consume — Pass the data for processing

説明

public Parle\RLexer::consume(string $data): void

Consume the data for lexing.

パラメータ

data

Data to be lexed.

戻り値

値を返しません。


Dump the state machine

  • ≪ Parle\RLexer::consume
  • Parle\RLexer::getToken ≫
  • PHP Manual
  • Parle\RLexer
  • Dump the state machine

Parle\RLexer::dump

(PECL parle >= 0.5.1)

Parle\RLexer::dump — Dump the state machine

説明

public Parle\RLexer::dump(): void

Dump the current state machine to stdout.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Retrieve the current token

  • ≪ Parle\RLexer::dump
  • Parle\RLexer::insertMacro ≫
  • PHP Manual
  • Parle\RLexer
  • Retrieve the current token

Parle\RLexer::getToken

(PECL parle >= 0.5.1)

Parle\RLexer::getToken — Retrieve the current token

説明

public Parle\RLexer::getToken(): Parle\Token

Retrive the current token.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an instance of Parle\Token.


Insert regex macro

  • ≪ Parle\RLexer::getToken
  • Parle\RLexer::push ≫
  • PHP Manual
  • Parle\RLexer
  • Insert regex macro

Parle\RLexer::insertMacro

(PECL parle >= 0.5.1)

Parle\RLexer::insertMacro — Insert regex macro

説明

public Parle\RLexer::insertMacro(string $name, string $regex): void

Insert a regex macro, that can be later used as a shortcut and included in other regular expressions.

パラメータ

name

Name of the macros.

regex

Regular expression.

戻り値

値を返しません。


Add a lexer rule

  • ≪ Parle\RLexer::insertMacro
  • Parle\RLexer::pushState ≫
  • PHP Manual
  • Parle\RLexer
  • Add a lexer rule

Parle\RLexer::push

(PECL parle >= 0.5.1)

Parle\RLexer::push — Add a lexer rule

説明

public Parle\RLexer::push(string $regex, int $id): void
public Parle\RLexer::push(
string $state,
string $regex,
int $id,
string $newState
): void
public Parle\RLexer::push(string $state, string $regex, string $newState): void

Push a pattern for lexeme recognition.

A 'start state' and 'exit state' can be specified by using a suitable signature.

パラメータ

regex

Regular expression used for token matching.

id

Token id. If the lexer instance is meant to be used standalone, this can be an arbitrary number. If the lexer instance is going to be passed to the parser, it has to be an id returned by Parle\RParser::tokenid().

state

State name. If '*' is used as start state, then the rule is applied to all lexer states.

newState

New state name, after the rule was applied.

If '.' is specified as the exit state, then the lexer state is unchanged when that rule matches. An exit state with '>' before the name means push. Use the signature without id for either continuation or to start matching, when a continuation or recursion is required.

If '<' is specified as exit state, it means pop. In that case, the signature containing the id can be used to identify the match. Note that even in the case an id is specified, the rule will finish first when all the previous pushes popped.

戻り値

値を返しません。


Push a new start state

  • ≪ Parle\RLexer::push
  • Parle\RLexer::reset ≫
  • PHP Manual
  • Parle\RLexer
  • Push a new start state

Parle\RLexer::pushState

(PECL parle >= 0.5.1)

Parle\RLexer::pushState — Push a new start state

説明

public Parle\RLexer::pushState(string $state): int

This lexer type can have more than one state machine. This allows you to lex different tokens depending on context, thus allowing simple parsing to take place. Once a state pushed, it can be used with a suitable Parle\RLexer::push() signature variant.

パラメータ

state

Name of the state.

戻り値


Reset lexer

  • ≪ Parle\RLexer::pushState
  • Parle\Parser ≫
  • PHP Manual
  • Parle\RLexer
  • Reset lexer

Parle\RLexer::reset

(PECL parle >= 0.7.1)

Parle\RLexer::reset — Reset lexer

説明

public Parle\RLexer::reset(int $pos): void

Reset lexing optionally supplying the desired offset.

パラメータ

pos

Reset position.

戻り値

値を返しません。


The Parle\Parser class

(PECL parle >= 0.5.1)

はじめに

Parser class. Rules can be defined on the fly. Once finalized, a Parle\Lexer instance is required to deliver the token stream.

クラス概要

class Parle\Parser {
/* 定数 */
const int ACTION_ERROR = 0;
const int ACTION_SHIFT = 1;
const int ACTION_REDUCE = 2;
const int ACTION_GOTO = 3;
const int ACTION_ACCEPT = 4;
const int ERROR_SYNTAX = 0;
const int ERROR_NON_ASSOCIATIVE = 1;
const int ERROR_UNKNOWN_TOKEN = 2;
/* プロパティ */
public int $action = 0;
public int $reduceId = 0;
/* メソッド */
public advance(): void
public build(): void
public consume(string $data, Parle\Lexer $lexer): void
public dump(): void
public errorInfo(): Parle\ErrorInfo
public left(string $tok): void
public nonassoc(string $tok): void
public precedence(string $tok): void
public push(string $name, string $rule): int
public reset(int $tokenId = ?): void
public right(string $tok): void
public sigil(int $idx): string
public sigilCount(): int
public sigilName(int $idx): string
public token(string $tok): void
public tokenId(string $tok): int
public trace(): string
public validate(string $data, Parle\Lexer $lexer): bool
}

定義済み定数

Parle\Parser::ACTION_ERROR

Parle\Parser::ACTION_SHIFT

Parle\Parser::ACTION_REDUCE

Parle\Parser::ACTION_GOTO

Parle\Parser::ACTION_ACCEPT

Parle\Parser::ERROR_SYNTAX

Parle\Parser::ERROR_NON_ASSOCIATIVE

Parle\Parser::ERROR_UNKNOWN_TOKEN

プロパティ

action

Current parser action that matches one of the action class constants, readonly.

reduceId

Grammar rule id just processed in the reduce action. The value corresponds either to a token or to a production id. Readonly.

目次

  • Parle\Parser::advance — Process next parser rule
  • Parle\Parser::build — Finalize the grammar rules
  • Parle\Parser::consume — Consume the data for processing
  • Parle\Parser::dump — Dump the grammar
  • Parle\Parser::errorInfo — Retrieve the error information
  • Parle\Parser::left — Declare a token with left-associativity
  • Parle\Parser::nonassoc — Declare a token with no associativity
  • Parle\Parser::precedence — Declare a precedence rule
  • Parle\Parser::push — Add a grammar rule
  • Parle\Parser::reset — Reset parser state
  • Parle\Parser::right — Declare a token with right-associativity
  • Parle\Parser::sigil — Retrieve a matching part of a rule
  • Parle\Parser::sigilCount — Number of elements in matched rule
  • Parle\Parser::sigilName — Retrieve a rule or token name
  • Parle\Parser::token — Declare a token
  • Parle\Parser::tokenId — Get token id
  • Parle\Parser::trace — Trace the parser operation
  • Parle\Parser::validate — Validate input


Process next parser rule

  • ≪ Parle\Parser
  • Parle\Parser::build ≫
  • PHP Manual
  • Parle\Parser
  • Process next parser rule

Parle\Parser::advance

(PECL parle >= 0.5.1)

Parle\Parser::advance — Process next parser rule

説明

public Parle\Parser::advance(): void

Process next parser rule.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Finalize the grammar rules

  • ≪ Parle\Parser::advance
  • Parle\Parser::consume ≫
  • PHP Manual
  • Parle\Parser
  • Finalize the grammar rules

Parle\Parser::build

(PECL parle >= 0.5.1)

Parle\Parser::build — Finalize the grammar rules

説明

public Parle\Parser::build(): void

Any tokens and grammar rules previously added are finalized. The rule set becomes readonly and the parser is ready to start.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Consume the data for processing

  • ≪ Parle\Parser::build
  • Parle\Parser::dump ≫
  • PHP Manual
  • Parle\Parser
  • Consume the data for processing

Parle\Parser::consume

(PECL parle >= 0.5.1)

Parle\Parser::consume — Consume the data for processing

説明

public Parle\Parser::consume(string $data, Parle\Lexer $lexer): void

Consume the data for parsing.

パラメータ

data

Data to be parsed.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

戻り値

値を返しません。


Dump the grammar

  • ≪ Parle\Parser::consume
  • Parle\Parser::errorInfo ≫
  • PHP Manual
  • Parle\Parser
  • Dump the grammar

Parle\Parser::dump

(PECL parle >= 0.5.1)

Parle\Parser::dump — Dump the grammar

説明

public Parle\Parser::dump(): void

Dump the current grammar to stdout.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Retrieve the error information

  • ≪ Parle\Parser::dump
  • Parle\Parser::left ≫
  • PHP Manual
  • Parle\Parser
  • Retrieve the error information

Parle\Parser::errorInfo

(PECL parle >= 0.5.1)

Parle\Parser::errorInfo — Retrieve the error information

説明

public Parle\Parser::errorInfo(): Parle\ErrorInfo

Retrieve the error information in case Parle\Parser::action() returned the error action.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an instance of Parle\ErrorInfo.


Declare a token with left-associativity

  • ≪ Parle\Parser::errorInfo
  • Parle\Parser::nonassoc ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token with left-associativity

Parle\Parser::left

(PECL parle >= 0.5.1)

Parle\Parser::left — Declare a token with left-associativity

説明

public Parle\Parser::left(string $tok): void

Declare a terminal with left associativity.

パラメータ

tok

Token name.

戻り値

値を返しません。


Declare a token with no associativity

  • ≪ Parle\Parser::left
  • Parle\Parser::precedence ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token with no associativity

Parle\Parser::nonassoc

(PECL parle >= 0.5.1)

Parle\Parser::nonassoc — Declare a token with no associativity

説明

public Parle\Parser::nonassoc(string $tok): void

Declare a terminal, that cannot appear more than once in the row.

パラメータ

tok

Token name.

戻り値

値を返しません。


Declare a precedence rule

  • ≪ Parle\Parser::nonassoc
  • Parle\Parser::push ≫
  • PHP Manual
  • Parle\Parser
  • Declare a precedence rule

Parle\Parser::precedence

(PECL parle >= 0.5.1)

Parle\Parser::precedence — Declare a precedence rule

説明

public Parle\Parser::precedence(string $tok): void

Declares a precedence rule for a fictitious terminal symbol. This rule can be later used in the specific grammar rules.

パラメータ

tok

Token name.

戻り値

値を返しません。


Add a grammar rule

  • ≪ Parle\Parser::precedence
  • Parle\Parser::reset ≫
  • PHP Manual
  • Parle\Parser
  • Add a grammar rule

Parle\Parser::push

(PECL parle >= 0.5.1)

Parle\Parser::push — Add a grammar rule

説明

public Parle\Parser::push(string $name, string $rule): int

Push a grammar rule. The production id returned can be used later in the parsing process to identify the rule matched.

パラメータ

name

Rule name.

rule

The rule to be added. The syntax is Bison compatible.

戻り値

Returns int representing the rule index.


Reset parser state

  • ≪ Parle\Parser::push
  • Parle\Parser::right ≫
  • PHP Manual
  • Parle\Parser
  • Reset parser state

Parle\Parser::reset

(PECL parle >= 0.7.1)

Parle\Parser::reset — Reset parser state

説明

public Parle\Parser::reset(int $tokenId = ?): void

Reset parser state using the given token id.

パラメータ

tokenId

Token id.

戻り値

値を返しません。


Declare a token with right-associativity

  • ≪ Parle\Parser::reset
  • Parle\Parser::sigil ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token with right-associativity

Parle\Parser::right

(PECL parle >= 0.5.1)

Parle\Parser::right — Declare a token with right-associativity

説明

public Parle\Parser::right(string $tok): void

Declare a terminal with right associativity.

パラメータ

tok

Token name.

戻り値

値を返しません。


Retrieve a matching part of a rule

  • ≪ Parle\Parser::right
  • Parle\Parser::sigilCount ≫
  • PHP Manual
  • Parle\Parser
  • Retrieve a matching part of a rule

Parle\Parser::sigil

(PECL parle >= 0.5.1)

Parle\Parser::sigil — Retrieve a matching part of a rule

説明

public Parle\Parser::sigil(int $idx): string

Retrieve a part of the match by a rule. This method is equivalent to the pseudo variable functionality in Bison.

パラメータ

idx

Match index, zero based.

戻り値

Returns a string with the matched part.


Number of elements in matched rule

  • ≪ Parle\Parser::sigil
  • Parle\Parser::sigilName ≫
  • PHP Manual
  • Parle\Parser
  • Number of elements in matched rule

Parle\Parser::sigilCount

(PECL parle >= 0.8.4)

Parle\Parser::sigilCount — Number of elements in matched rule

説明

public Parle\Parser::sigilCount(): int

Get number of elements in the matched rule.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns int


Retrieve a rule or token name

  • ≪ Parle\Parser::sigilCount
  • Parle\Parser::token ≫
  • PHP Manual
  • Parle\Parser
  • Retrieve a rule or token name

Parle\Parser::sigilName

(PECL parle >= 0.8.4)

Parle\Parser::sigilName — Retrieve a rule or token name

説明

public Parle\Parser::sigilName(int $idx): string

Retrieve a partial rule name or token name corresponding to the sigil index.

パラメータ

idx

Match index, zero based.

戻り値

Returns a string with the matched part.


Declare a token

  • ≪ Parle\Parser::sigilName
  • Parle\Parser::tokenId ≫
  • PHP Manual
  • Parle\Parser
  • Declare a token

Parle\Parser::token

(PECL parle >= 0.5.1)

Parle\Parser::token — Declare a token

説明

public Parle\Parser::token(string $tok): void

Declare a terminal to be used in the grammar.

パラメータ

tok

Token name.

戻り値

値を返しません。


Get token id

  • ≪ Parle\Parser::token
  • Parle\Parser::trace ≫
  • PHP Manual
  • Parle\Parser
  • Get token id

Parle\Parser::tokenId

(PECL parle >= 0.5.1)

Parle\Parser::tokenId — Get token id

説明

public Parle\Parser::tokenId(string $tok): int

Retrieve the id of the named token.

パラメータ

tok

Name of the token as used in Parle\Parser::token().

戻り値

Returns int representing the token id.


Trace the parser operation

  • ≪ Parle\Parser::tokenId
  • Parle\Parser::validate ≫
  • PHP Manual
  • Parle\Parser
  • Trace the parser operation

Parle\Parser::trace

(PECL parle >= 0.5.1)

Parle\Parser::trace — Trace the parser operation

説明

public Parle\Parser::trace(): string

Retrieve the current parser operation description. This can be especially useful for studying the parser and to optimize the grammar.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string with the trace information.


Validate input

  • ≪ Parle\Parser::trace
  • Parle\RParser ≫
  • PHP Manual
  • Parle\Parser
  • Validate input

Parle\Parser::validate

(PECL parle >= 0.5.1)

Parle\Parser::validate — Validate input

説明

public Parle\Parser::validate(string $data, Parle\Lexer $lexer): bool

Validate an input string. The string is parsed internally, thus this method is useful for the quick input validation.

パラメータ

data

String to be validated.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

戻り値

Returns bool witnessing whether the input chimes or not with the defined rules.


The Parle\RParser class

(PECL parle >= 0.7.0)

はじめに

Parser class. Rules can be defined on the fly. Once finalized, a Parle\RLexer instance is required to deliver the token stream.

クラス概要

class Parle\RParser {
/* 定数 */
const int ACTION_ERROR = 0;
const int ACTION_SHIFT = 1;
const int ACTION_REDUCE = 2;
const int ACTION_GOTO = 3;
const int ACTION_ACCEPT = 4;
const int ERROR_SYNTAX = 0;
const int ERROR_NON_ASSOCIATIVE = 1;
const int ERROR_UNKNOWN_TOKEN = 2;
/* プロパティ */
public int $action = 0;
public int $reduceId = 0;
/* メソッド */
public advance(): void
public build(): void
public consume(string $data, Parle\RLexer $rlexer): void
public dump(): void
public errorInfo(): Parle\ErrorInfo
public left(string $tok): void
public nonassoc(string $tok): void
public precedence(string $tok): void
public push(string $name, string $rule): int
public reset(int $tokenId = ?): void
public right(string $tok): void
public sigil(int $idx = ?): string
public sigilCount(): int
public sigilName(int $idx): string
public token(string $tok): void
public tokenId(string $tok): int
public trace(): string
public validate(string $data, Parle\RLexer $lexer): bool
}

定義済み定数

Parle\RParser::ACTION_ERROR

Parle\RParser::ACTION_SHIFT

Parle\RParser::ACTION_REDUCE

Parle\RParser::ACTION_GOTO

Parle\RParser::ACTION_ACCEPT

Parle\RParser::ERROR_SYNTAX

Parle\RParser::ERROR_NON_ASSOCIATIVE

Parle\RParser::ERROR_UNKNOWN_TOKEN

プロパティ

action

Current parser action that matches one of the action class constants, readonly.

reduceId

Grammar rule id just processed in the reduce action. The value corresponds either to a token or to a production id. Readonly.

目次

  • Parle\RParser::advance — Process next parser rule
  • Parle\RParser::build — Finalize the grammar rules
  • Parle\RParser::consume — Consume the data for processing
  • Parle\RParser::dump — Dump the grammar
  • Parle\RParser::errorInfo — Retrieve the error information
  • Parle\RParser::left — Declare a token with left-associativity
  • Parle\RParser::nonassoc — Declare a token with no associativity
  • Parle\RParser::precedence — Declare a precedence rule
  • Parle\RParser::push — Add a grammar rule
  • Parle\RParser::reset — Reset parser state
  • Parle\RParser::right — Declare a token with right-associativity
  • Parle\RParser::sigil — Retrieve a matching part of a rule
  • Parle\RParser::sigilCount — Number of elements in matched rule
  • Parle\RParser::sigilName — Retrieve a rule or token name
  • Parle\RParser::token — Declare a token
  • Parle\RParser::tokenId — Get token id
  • Parle\RParser::trace — Trace the parser operation
  • Parle\RParser::validate — Validate input


Process next parser rule

  • ≪ Parle\RParser
  • Parle\RParser::build ≫
  • PHP Manual
  • Parle\RParser
  • Process next parser rule

Parle\RParser::advance

(PECL parle >= 0.7.0)

Parle\RParser::advance — Process next parser rule

説明

public Parle\RParser::advance(): void

Prosess next parser rule.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Finalize the grammar rules

  • ≪ Parle\RParser::advance
  • Parle\RParser::consume ≫
  • PHP Manual
  • Parle\RParser
  • Finalize the grammar rules

Parle\RParser::build

(PECL parle >= 0.7.0)

Parle\RParser::build — Finalize the grammar rules

説明

public Parle\RParser::build(): void

Any tokens and grammar rules previously added are finalized. The rule set becomes readonly and the parser is ready to start.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Consume the data for processing

  • ≪ Parle\RParser::build
  • Parle\RParser::dump ≫
  • PHP Manual
  • Parle\RParser
  • Consume the data for processing

Parle\RParser::consume

(PECL parle >= 0.7.0)

Parle\RParser::consume — Consume the data for processing

説明

public Parle\RParser::consume(string $data, Parle\RLexer $rlexer): void

Consume the data for parsing.

パラメータ

data

Data to be parsed.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

戻り値

値を返しません。


Dump the grammar

  • ≪ Parle\RParser::consume
  • Parle\RParser::errorInfo ≫
  • PHP Manual
  • Parle\RParser
  • Dump the grammar

Parle\RParser::dump

(PECL parle >= 0.7.0)

Parle\RParser::dump — Dump the grammar

説明

public Parle\RParser::dump(): void

Dump the current grammar to stdout.

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Retrieve the error information

  • ≪ Parle\RParser::dump
  • Parle\RParser::left ≫
  • PHP Manual
  • Parle\RParser
  • Retrieve the error information

Parle\RParser::errorInfo

(PECL parle >= 0.7.0)

Parle\RParser::errorInfo — Retrieve the error information

説明

public Parle\RParser::errorInfo(): Parle\ErrorInfo

Retrieve the error information in case Parle\RParser::action() returned the error action.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an instance of Parle\ErrorInfo.


Declare a token with left-associativity

  • ≪ Parle\RParser::errorInfo
  • Parle\RParser::nonassoc ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token with left-associativity

Parle\RParser::left

(PECL parle >= 0.7.0)

Parle\RParser::left — Declare a token with left-associativity

説明

public Parle\RParser::left(string $tok): void

Declare a terminal with left associativity.

パラメータ

tok

Token name.

戻り値

値を返しません。


Declare a token with no associativity

  • ≪ Parle\RParser::left
  • Parle\RParser::precedence ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token with no associativity

Parle\RParser::nonassoc

(PECL parle >= 0.7.0)

Parle\RParser::nonassoc — Declare a token with no associativity

説明

public Parle\RParser::nonassoc(string $tok): void

Declare a terminal, that cannot appear more than once in the row.

パラメータ

tok

Token name.

戻り値

値を返しません。


Declare a precedence rule

  • ≪ Parle\RParser::nonassoc
  • Parle\RParser::push ≫
  • PHP Manual
  • Parle\RParser
  • Declare a precedence rule

Parle\RParser::precedence

(PECL parle >= 0.7.0)

Parle\RParser::precedence — Declare a precedence rule

説明

public Parle\RParser::precedence(string $tok): void

Declares a precedence rule for a fictious terminal symbol. This rule can be later used in the specific grammar rules.

パラメータ

tok

Token name.

戻り値

値を返しません。


Add a grammar rule

  • ≪ Parle\RParser::precedence
  • Parle\RParser::reset ≫
  • PHP Manual
  • Parle\RParser
  • Add a grammar rule

Parle\RParser::push

(PECL parle >= 0.7.0)

Parle\RParser::push — Add a grammar rule

説明

public Parle\RParser::push(string $name, string $rule): int

Push a grammar rule. The production id returned can be used later in the parsing process to identify the rule matched.

パラメータ

name

Rule name.

rule

The rule to be added. The syntax is Bison compatible.

戻り値

Returns int representing the rule index.


Reset parser state

  • ≪ Parle\RParser::push
  • Parle\RParser::right ≫
  • PHP Manual
  • Parle\RParser
  • Reset parser state

Parle\RParser::reset

(PECL parle >= 0.7.1)

Parle\RParser::reset — Reset parser state

説明

public Parle\RParser::reset(int $tokenId = ?): void

Reset parser state using the given token id.

パラメータ

tokenId

Token id.

戻り値

値を返しません。


Declare a token with right-associativity

  • ≪ Parle\RParser::reset
  • Parle\RParser::sigil ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token with right-associativity

Parle\RParser::right

(PECL parle >= 0.7.0)

Parle\RParser::right — Declare a token with right-associativity

説明

public Parle\RParser::right(string $tok): void

Declare a terminal with right associativity.

パラメータ

tok

Token name.

戻り値

値を返しません。


Retrieve a matching part of a rule

  • ≪ Parle\RParser::right
  • Parle\RParser::sigilCount ≫
  • PHP Manual
  • Parle\RParser
  • Retrieve a matching part of a rule

Parle\RParser::sigil

(PECL parle >= 0.7.0)

Parle\RParser::sigil — Retrieve a matching part of a rule

説明

public Parle\RParser::sigil(int $idx = ?): string

Retrieve a part of the match by a rule. This method is equivalent to the pseudo variable functionality in Bison.

パラメータ

idx

Match index, zero based.

戻り値

Returns a string with the matched part.


Number of elements in matched rule

  • ≪ Parle\RParser::sigil
  • Parle\RParser::sigilName ≫
  • PHP Manual
  • Parle\RParser
  • Number of elements in matched rule

Parle\RParser::sigilCount

(PECL parle >= 0.8.4)

Parle\RParser::sigilCount — Number of elements in matched rule

説明

public Parle\RParser::sigilCount(): int

Get number of elements in the matched rule.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns int


Retrieve a rule or token name

  • ≪ Parle\RParser::sigilCount
  • Parle\RParser::token ≫
  • PHP Manual
  • Parle\RParser
  • Retrieve a rule or token name

Parle\RParser::sigilName

(PECL parle >= 0.8.4)

Parle\RParser::sigilName — Retrieve a rule or token name

説明

public Parle\RParser::sigilName(int $idx): string

Retrieve a partial rule name or token name corresponding to the sigil index.

パラメータ

idx

Match index, zero based.

戻り値

Returns a string with the matched part.


Declare a token

  • ≪ Parle\RParser::sigilName
  • Parle\RParser::tokenId ≫
  • PHP Manual
  • Parle\RParser
  • Declare a token

Parle\RParser::token

(PECL parle >= 0.7.0)

Parle\RParser::token — Declare a token

説明

public Parle\RParser::token(string $tok): void

Declare a terminal to be used in the grammar.

パラメータ

tok

Token name.

戻り値

値を返しません。


Get token id

  • ≪ Parle\RParser::token
  • Parle\RParser::trace ≫
  • PHP Manual
  • Parle\RParser
  • Get token id

Parle\RParser::tokenId

(PECL parle >= 0.7.0)

Parle\RParser::tokenId — Get token id

説明

public Parle\RParser::tokenId(string $tok): int

Retrieve the id of the named token.

パラメータ

tok

Name of the token as used in Parle\RParser::token().

戻り値

Returns int representing the token id.


Trace the parser operation

  • ≪ Parle\RParser::tokenId
  • Parle\RParser::validate ≫
  • PHP Manual
  • Parle\RParser
  • Trace the parser operation

Parle\RParser::trace

(PECL parle >= 0.7.0)

Parle\RParser::trace — Trace the parser operation

説明

public Parle\RParser::trace(): string

Retrieve the current parser operation description. This can be especially useful to study the parser and to optimize the grammar.

パラメータ

この関数にはパラメータはありません。

戻り値

Returns a string with the trace information.


Validate input

  • ≪ Parle\RParser::trace
  • Parle\Stack ≫
  • PHP Manual
  • Parle\RParser
  • Validate input

Parle\RParser::validate

(PECL parle >= 0.7.0)

Parle\RParser::validate — Validate input

説明

public Parle\RParser::validate(string $data, Parle\RLexer $lexer): bool

Validate an input string. The string is parsed internally, thus this method is useful for the quick input validation.

パラメータ

data

String to be validated.

lexer

A lexer object containing the lexing rules prepared for the particular grammar.

戻り値

Returns bool whitnessing whether the input chimes or not with the defined rules.


The Parle\Stack class

(PECL parle >= 0.7.0)

はじめに

Parle\Stack is a LIFO stack. The elements are inserted and removed only from one end.

クラス概要

class Parle\Stack {
/* プロパティ */
public bool $empty = true;
public int $size = 0;
public mixed $top;
/* メソッド */
public pop(): void
public push(mixed $item): void
}

プロパティ

empty

Whether the stack is empty, readonly.

size

Stack size, readonly.

top

Element on the top of the stack.

目次

  • Parle\Stack::pop — Pop an item from the stack
  • Parle\Stack::push — Push an item into the stack


Pop an item from the stack

  • ≪ Parle\Stack
  • Parle\Stack::push ≫
  • PHP Manual
  • Parle\Stack
  • Pop an item from the stack

Parle\Stack::pop

(PECL parle >= 0.5.1)

Parle\Stack::pop — Pop an item from the stack

説明

public Parle\Stack::pop(): void

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。


Push an item into the stack

  • ≪ Parle\Stack::pop
  • Parle\Token ≫
  • PHP Manual
  • Parle\Stack
  • Push an item into the stack

Parle\Stack::push

(PECL parle >= 0.5.1)

Parle\Stack::push — Push an item into the stack

説明

public Parle\Stack::push(mixed $item): void

パラメータ

item

Variable to be pushed.

戻り値

値を返しません。


The Parle\Token class

(PECL parle >= 0.5.2)

はじめに

This class represents a token. Lexer returns instances of this class.

クラス概要

class Parle\Token {
/* 定数 */
const int EOI = 0;
const int UNKNOWN = -1;
const int SKIP = -2;
/* プロパティ */
public int $id;
public string $value;
/* メソッド */
}

プロパティ

id

Token id.

value

Token value.

定義済み定数

Parle\Token::EOI

End of input token id.

Parle\Token::UNKNOWN

Unknown token id.

Parle\Token::SKIP

Skip token id.


The Parle\ErrorInfo class

(PECL parle >= 0.5.2)

はじめに

The class represents detailed error information as supplied by Parle\Parser::errorInfo()

クラス概要

class Parle\ErrorInfo {
/* プロパティ */
public int $id;
public int $position;
public mixed $token;
/* メソッド */
}

プロパティ

id

Error id.

position

Position in the input, where the error occurred.

token

If applicable - the Parle\Token related to the error, otherwise null.


The Parle\LexerException class

(PECL parle >= 0.5.1)

はじめに

クラス概要

class Parle\LexerException extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


The Parle\ParserException class

(PECL parle >= 0.5.1)

はじめに

クラス概要

class Parle\ParserException extends Exception implements Throwable {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


正規表現 (Perl 互換)

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • 例
  • PCRE のパターン
    • 正規表現パターンに使用可能な修飾子 — パターン修飾子
    • Perl とは異なる点 — Perl との違い
    • PCRE 正規表現構文 — パターン構文
  • PCRE 関数
    • preg_filter — 正規表現による検索と置換を行う
    • preg_grep — パターンにマッチする配列の要素を返す
    • preg_last_error — 直近の PCRE 正規表現処理のエラーコードを返す
    • preg_last_error_msg — 最後に実行した PCRE 正規表現に関するエラーメッセージを返す
    • preg_match — 正規表現によるマッチングを行う
    • preg_match_all — 繰り返し正規表現検索を行う
    • preg_quote — 正規表現文字をクオートする
    • preg_replace — 正規表現検索および置換を行う
    • preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う
    • preg_replace_callback_array — 正規表現検索を行い、コールバック関数を使用して置換を行う
    • preg_split — 正規表現で文字列を分割する


はじめに

この正規表現関数で使用するパターンの構文は、Perl と類似しています。 正規表現は、スラッシュ (/) などのデリミタで囲う必要があります。 デリミタには使用できるのは、非英数字、非空白文字の任意の ASCII 文字ですが、バックスラッシュ (\) と null バイトは使用できません。 デリミタ文字を正規表現本体において使用する必要がある場合は、 バックスラッシュでエスケープします。 Perl形式の (), {}, [], <> を使用することもできるでしょう。 パターンの詳細については、パターン構文 を参照ください。

様々な修飾子を終端デリミタの後に付け、 マッチングに変化を与えることができます。 パターン修飾子 を参照ください。

注意:

この拡張モジュールでは、コンパイルした正規表現のために スレッド単位のグローバルキャッシュ (最大 4096) を管理しています。

警告

PCRE には、いくつかの制限があります。詳細は、» http://www.pcre.org/pcre.txt を参照ください。

PCRE ライブラリは、Perl 5 と同じ文法構文を用いた 正規表現パターンマッチ処理を実装した関数群ですが、多少異なる点もあります (以下を参照ください)。現在の実装は Perl 5.005 に対応しています。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • PCRE
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

PCRE は PHP のコア拡張モジュールなので、常に有効となっています。 デフォルトでは、この拡張モジュールのコンパイルには、バンドルされている PCRE ライブラリを利用します。別の PCRE ライブラリを使ってコンパイルする場合は、オプション --with-pcre-regex=DIR を利用します。 このとき DIR には、PCRE のインクルードファイルやライブラリファイルがある場所を指定します。 PCRE 8.10 以降を使うことを推奨します。PHP 7.3.0 以降では、PCRE2 が必須になっています。

PCRE の JIT(ジャストインタイムコンパイル) 機能はデフォルトでサポートされています。 PHP 7.0.12 以降では、--without-pcre-jit 構成オプションで無効化できます。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

PCRE は活発なプロジェクトであり、変化し続けています。 PHP で使える機能もそれに依存しています。 PHP のドキュメントも部分的に時代遅れになっている可能性があり、 PCRE の最新機能は網羅できていないかもしれません。 変更点の一覧は、 » PCRE ライブラリの変更履歴 を参照ください。また、バンドルされている PCRE の履歴も参考になるでしょう。

バンドルされている PCRE ライブラリの更新履歴
PHP バージョン | PCRE バージョン | 備考
8.2.0 | 10.40 |
8.1.0 | 10.39 |
7.4.12, 8.0.0 | 10.35 |
7.4.6 | 10.34 |
7.4.0 | 10.33 |
7.3.0 | 10.32 |
7.2.0 | 8.41 |
7.0.3 | 8.38 | See CVE-2015-8383, CVE-2015-8386, CVE-2015-8387, CVE-2015-8389, CVE-2015-8390, CVE-2015-8391, CVE-2015-8393, CVE-2015-8394
7.0.0 | 8.37 | See CVE-2015-2325, CVE-2015-2326


実行時設定

php.ini の設定により動作が変化します。

PCRE 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
pcre.backtrack_limit | "1000000" | INI_ALL |
pcre.recursion_limit | "100000" | INI_ALL |
pcre.jit | "1" | INI_ALL |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

pcre.backtrack_limit int

PCRE のバックトラック処理の制限値。 PHP < 5.3.7 ではデフォルトが 100000 でした。

pcre.recursion_limit int

PCRE の再帰処理の制限値です。この値を大きくすると、 使用可能なプロセススタックを使い切ってしまい、 (OS のスタックサイズの制限値に達して) PHP をクラッシュさせてしまうことに注意しましょう。

pcre.jit bool

PCRE の just-in-time コンパイルを利用するかどうか。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

PREG 定数
定数 | 説明 | 使用可能
PREG_PATTERN_ORDER (int) | $matches[0] はパターン全体にマッチした文字列の配列、 $matches[1] は第 1 のキャプチャ用サブパターンにマッチした文字列の配列、 といったように結果の順序を指定します。 このフラグは、preg_match_all() でのみ使用されます。 |
PREG_SET_ORDER (int) | $matches[0] は 1 回目のマッチングでキャプチャした値の配列、 $matches[1] は 2 回目のマッチングでキャプチャした値の配列、 といったように結果の順序を指定します。 このフラグは、preg_match_all() でのみ使用されます。 |
PREG_OFFSET_CAPTURE (int) | PREG_SPLIT_OFFSET_CAPTURE の説明を参照ください。 |
PREG_SPLIT_NO_EMPTY (int) | このフラグは、preg_split() が、空文字列でないものだけ を返すようにします。 |
PREG_SPLIT_DELIM_CAPTURE (int) | このフラグは、preg_split() が 文字列分割用のパターン中のカッコによるサブパターンでキャプチャされた値も 同時に返すようにします。 |
PREG_SPLIT_OFFSET_CAPTURE (int) | このフラグを設定した場合、各マッチに対応する文字列のオフセットも返されます。 これにより、戻り値は配列となり、配列の要素 0 はマッチした文字列、 要素 1 は対象文字列中におけるマッチした文字列のオフセット値となることに注意してください。 このフラグは preg_split() のみで使用されます。 |
PREG_UNMATCHED_AS_NULL (int) | このフラグは、 preg_match() と preg_match_all() 関数で マッチしなかったサブパターンがあった場合に、 $matches に null を入れることで伝えます。 このフラグがないと、マッチしなかったサブパターンは いかにも空文字列にマッチしたかのように空文字列として通知されます。 このフラグを設定することで、これらふたつの場合を区別できます。 | 7.2.0
PREG_NO_ERROR (int) | エラーが存在しなかった場合に preg_last_error() から返されます。 | 5.2.0
PREG_INTERNAL_ERROR (int) | PCRE 内部エラーが発生した場合に preg_last_error() から返されます。 | 5.2.0
PREG_BACKTRACK_LIMIT_ERROR (int) | backtrack limit に達した場合に preg_last_error() から返されます。 | 5.2.0
PREG_RECURSION_LIMIT_ERROR (int) | recursion limit に達した場合に preg_last_error() から返されます。 | 5.2.0
PREG_BAD_UTF8_ERROR (int) | 壊れている UTF8 データによって直近のエラーが発生した場合に preg_last_error() から返されます (UTF-8 モード で正規表現を実行した場合のみ)。 | 5.2.0
PREG_BAD_UTF8_OFFSET_ERROR (int) | オフセットが妥当な UTF-8 コードポイントの開始位置に対応しない場合に preg_last_error() から返されます (UTF-8 モード で正規表現を実行した場合のみ)。 | 5.3.0
PREG_JIT_STACKLIMIT_ERROR (int) | 直近の PCRE 関数の実行が JIT スタック空間の制限によって失敗した場合に preg_last_error() から返されます。 | 7.0.0
PCRE_VERSION (string) | PCRE のバージョンおよびリリース日 (例: "7.0 18-Dec-2006")。 | 5.2.4
PCRE_VERSION_MAJOR (int) | PCRE のメジャーバージョン番号 |
PCRE_VERSION_MINOR (int) | PCRE のマイナーバージョン番号 |
PCRE_JIT_SUPPORT (bool) | PCRE JIT サポートが有効かどうかを示します。 |
PREG_GREP_INVERT (int) | 指定されたパターンにマッチしない要素を返します。 |


例

例1 有効なパターンの例

  • /<\/\w+>/
  • |(\d{3})-\d+|Sm
  • /^(?i)php[34]/
  • {^\s+(\s+)?$}

例2 無効なパターンの例

  • /href='(.*)' - 終端デリミタが抜けている
  • /\w+\s*\w+/J - 未知の修飾子 'J'
  • 1-\d3-\d3-\d4| - 始端デリミタが抜けている


  • ≪ 例
  • 正規表現パターンに使用可能な修飾子 ≫
  • PHP Manual
  • PCRE
  • PCRE のパターン

PCRE のパターン

目次

  • 正規表現パターンに使用可能な修飾子
  • Perl とは異なる点
  • PCRE 正規表現構文


パターン修飾子

現在使用可能な PCRE 修飾子の一覧を以下に示します。 括弧の中の名前は、これらの修飾子に関する PCRE 内部の名前です。 修飾子中での空白文字および改行は無視されます。他の文字はエラーになります。

i (PCRE_CASELESS)
この修飾子を設定すると、パターンの中の文字は 大文字にも小文字にもマッチします。
m (PCRE_MULTILINE)
デフォルトで、PCRE は、検索対象文字列を（実際には複数行からなる 場合でも）単一の行からなるとして処理します。 「行頭」メタ文字 (^) は、対象文字列の最初にしかマッチしません。 一方、「行末」メタ文字 ($) は、文字列の最後、または （D 修飾子が設定されていない場合） 最後にある改行記号の前のみにしかマッチしません。 この動作は Perl と同じです。 この修飾子を設定すると、「行頭」および「行末」メタ文字は 対象文字列において、文字列の最初と最後に加えて、 各改行の直前と直後にそれぞれマッチします。 この動作は、Perl の /m 修飾子と同じです。 対象文字列の中に "\n" 文字がない場合や、 またはパターンに ^ または $ がない場合は、 この修飾子を設定しても意味はありません。
s (PCRE_DOTALL)
この修飾子を設定すると、パターン中のドットメタ文字は 改行を含む全ての文字にマッチします。 これを設定しない場合は、改行にはマッチしません。 この修飾子は、Perl の /s 修飾子と同じです。 [^a] のような否定の文字クラスは、 この修飾子の設定によらず、常に改行文字にマッチします。
x (PCRE_EXTENDED)
この修飾子を設定すると、エスケープするか 文字クラスの内部を除き、 パターンの空白文字は完全に無視されます。 文字クラスの外にあって、かつエスケープされていない # と次の改行文字の間の文字も無視されます。 この動作は、Perl の /x 修飾子と同じであり、複雑なパターンの内部に コメントを記述することが可能となります。 しかし、この修飾子は、データ文字にのみ適用されることに注意 してください。空白文字をパターンの特殊文字の並びの中、 例えば条件付きサブパターン (?( の内部に置くことはできません。
A (PCRE_ANCHORED)
この修飾子を設定すると、パターンは強制的に固定 (anchored) となります。 つまり、検索対象文字列の先頭でのみマッチするように制限されます。 パターン自体の中に適当な指定を行うことでも同様の効果を得ることが可能です。 Perl ではパターン中に指定する方法しか使用できません。
D (PCRE_DOLLAR_ENDONLY)
この修飾子を設定すると、パターン内のドルメタ文字は、検索対象文字列の 終わりにのみマッチします。この修飾子を設定しない場合、ドル記号は、 検索対象文字列の最後の文字が改行文字であれば、その直前にもマッチします。 この修飾子は、m を設定している場合に無視されます。 Perl には、この修飾子に等価なものはありません。
S
あるパターンを複数回使用する場合は、マッチングにかかる時間を 高速化することを目的として、パターンの分析に幾分か時間をかけても 良いでしょう。この修飾子を設定すると、追加のパターン分析が 行われます。現在、パターン分析は、最初の文字が単一ではなく、 かつ固定でないパターンに対してのみ有用です。
U (PCRE_UNGREEDY)
この修飾子を設定すると、量指定子の「貪欲さ」が反転します。 つまり、量指定子は、デフォルトで貪欲でなく、 疑問符を後ろに付けてはじめて貪欲になるようになります。 この修飾子は Perl 互換では有りません。 同様の設定は、(?U) 修飾子を パターン内で設定 するか、（.*? のように）量指定子の後に疑問符を 付けるかすることで行うこともできます。

注意:

通常は、非貪欲モードでは pcre.backtrack_limit 文字を超えるマッチができません。

X (PCRE_EXTRA)
この修正子は、Perl 非互換な PCRE の機能を有効にします。 パターン内で後ろに文字が続くバックスラッシュで特別な意味がないものは、 将来的な拡張の際の互換性の維持のため、エラーになります。 デフォルトでは、Perl のように文字が後ろに続くバックスラッシュ で特に意味がないものは、リテラルとして処理されます。 この修飾子により制御される機能は、現在の所、これだけです。
J (PCRE_INFO_JCHANGED)
(?J) 内部オプションは、ローカルのオプション PCRE_DUPNAMES の設定を変更します。 サブパターンで重複した名前を使用できるようになります。 7.2.0 以降、J も同様に修飾子としてサポートされます。
u (PCRE_UTF8)
この修正子は、Perl 非互換な PCRE の機能を有効にします。パターンと対象文字列は、 UTF-8 として処理されます。 無効な対象文字列を preg_* 関数に渡しても、何もマッチしません。 無効なパターンを渡すと、E_WARNING レベルのエラーが発生します。 5オクテットおよび6オクテットの UTF-8 シーケンスは無効とみなされます。
n (PCRE_NO_AUTO_CAPTURE)
この修正子を使うと、単純な (xyz) 形式でのグループ化ではキャプチャを行いません。 (?<name>xyz) のような、名前付きのグループ化を使う場合にのみ、キャプチャを行うようになります。 これによって影響を受けるのは、どのグループがキャプチャされるかだけです。 番号付きのサブパターンによる参照もまだ使えますし、 その場合マッチ結果が格納される配列には数値が含まれています。 PHP 8.2.0 以降で利用可能です。


Perl との違い

Perl 5.005 との違いについて以下に説明します。

  1. デフォルトでは、空白文字は C ライブラリ関数 isspace() が認識する文字となります。PCRE を別の文字型テーブルを用いて コンパイルすることも可能です。通常、isspace() はスペース、改ページ、 改行、復帰、水平タブ、垂直タブにマッチします。 Perl 5 では、現在、 垂直タブが空白文字として扱われていません。 Perl ドキュメントには \v というエスケープが記載されていましたが、実際は認識されていませんでした。 ただし、垂直タブ文字は少なくとも 5.002 までは空白文字として 処理されていました。 5.004 および 5.005 では、\s にマッチしなくなっています。
  2. PCRE では、先読み言明に量指定子を指定できません。Perl では可能ですが、思ったような動作を意味しないかもしれません。 例えば、(?!a){3} は、続く 3 文字が "a" でないことの言明ではありません。 この指定は、次の 1 文字が "a" ではないことを 3 回言明するだけです。
  3. 否定の先読み言明の中に記述したキャプチャ用サブパターンは カウントされますが、対応するオフセットにそのエントリは セットされません。 Perlでは、言明のマッチングに失敗する前に マッチしたパターンからその変数を設定しますが、それが行われるのは、 否定の先読み言明中の選択肢が 1 つだけの場合のみです。
  4. ヌル文字は、検索対象文字列においては使用できますが、 パターン文字列内では使用できません。これは、パターン文字列が 0 を終端とする通常の C 文字列として渡されるためです。パターン中では、 エスケープシーケンス "\x00" を使ってヌル文字を表すことができます。
  5. 次の Perl エスケープシーケンスはサポートされせん。 \l, \u, \L, \U。 これらのエスケープシーケンスは、Perl のパターンマッチエンジン内 ではなく、文字列処理の部分で実装されているためです。
  6. Perl の \G 言明は、単一のパターンマッチに対しては意味がなく、 サポートされません。
  7. 当然ながら、PCRE により、(?{code}) 構文および (??{code}) 構文はサポートされません。しかし、再帰的なパターンはサポートしています。
  8. Perl 5.005_02 では、パターンの一部を繰り返すと、キャプチャ文字列の セットに関して奇妙な動作をすることがあるようです。例えば、"aba" を パターン /^(a(b)?)+$/ に対してマッチングを行うと、 $2 には値 "b" が設定されますが、"aabbaa" を /^(aa(bb)?)+$/ に対して マッチングを行うと、$2 はセットされません。 しかし、パターンを /^(aa(b(b))?)+$/ に変えると、 $2 (および $3) はセットされます。 Perl 5.004 では、どちらの場合も $2 はセットされます。 PCRE の場合も、 どちらの場合でもセットされます。将来的に Perl が矛盾のない状態に 変更された場合は、PCRE も追従する可能性があります。
  9. 他の未解決の食い違いとして、パターン /^(a)?(?(1)a|b)+$/ は、 Perl 5.005_02 では文字列 "a" にマッチしますが、PCRE ではマッチしない ということがあります。しかし、Perl と PCRE のいずれでも、/^(a)?a/ で "a" をマッチした場合は $1 が未定義のままとなります。

  10. PCRE では、Perl の正規表現の機能よりさらに拡張された機能を使うことができます。

    1. 戻り読み言明は、固定長の文字列にマッチする必要がありますが、 このとき、戻り読み言明内の選択肢は、それぞれ異なる長さの文字列に マッチするパターンとしても問題ありません。Perl 5.005 では すべての選択肢が同じ長さである必要があります。
    2. PCRE_DOLLAR_ENDONLY が設定され PCRE_MULTILINE が設定されていない場合、メタ文字 $ は文字列の終端にのみ マッチします。
    3. PCRE_EXTRA を設定すると、バックスラッシュの後に意味がない文字が続くと エラーとなります。
    4. PCRE_UNGREEDY を設定すると、量指定子の貪欲さが反転します。つまり、量指定子は、 デフォルトで貪欲でなく、疑問符を後ろに付けてはじめて 貪欲になるようになります。


パターン構文

目次

  • はじめに
  • デリミタ
  • メタ文字
  • エスケープシーケンス
  • Unicode 文字プロパティ
  • アンカー
  • ドット
  • 文字クラス
  • 選択肢
  • 内部オプション設定
  • サブパターン
  • 繰り返し
  • 後方参照
  • 言明
  • 再試行無しのサブパターン
  • 条件付きサブパターン
  • コメント
  • 再帰的パターン
  • パフォーマンス


はじめに

PCRE がサポートする正規表現の構文と意味体系を以下に示します。 正規表現については、Perl のドキュメントや他の多くの書籍においても 解説されており、実例が豊富に記載されているものもあります。特に、 O'Reilly 発刊 Jeffrey Friedl 著 "Mastering Regular Expressions" (ISBN 1-56592-257) 〔日本語版：「詳説 正規表現」〕には、 たいへん詳細に解説されています。

以降の説明は、参考文書 (reference documentation) として 扱われることを想定しています。

正規表現は、ある種のパターンであり、検索対象文字列 (subject string) に対して左から右〔文字列の初めから終わり〕の順にマッチングが行われます。 一部の例外を除き、パターン中の文字はその文字自体を表し、 検索対象文字列内の同じ文字にマッチします。簡単な例をあげると、パターン

      The quick brown fox
は、検索対象文字列内にある、このパターンと同一の部分にマッチします。


デリミタ

PCRE 関数を使うときには、パターンを delimiters で囲まなければなりません。 英数字、バックスラッシュ、空白文字以外の任意の文字をデリミタとして使うことができます。 有効なデリミタの前に空白文字を付けても、黙って無視されます。

デリミタとしてよく使われる文字は、スラッシュ (/)、 ハッシュ記号 (#) およびチルダ (~) です。 次に示す例は、どれも正しいデリミタです。

/foo bar/
#^[^0-9]$#
+php+
%[a-zA-Z0-9_-]%

角括弧形式のデリミタを使うこともできます。 これは、開き角括弧と閉じ角括弧がそれぞれ開始デリミタ、終了デリミタを表す形式です。 ()、 {}、[] そして <> はどれも、角括弧形式のデリミタとして有効です。

(this [is] a (pattern))
{this [is] a (pattern)}
[this [is] a (pattern)]
<this [is] a (pattern)>
角括弧形式のデリミタを使う場合は、パターン内でメタ文字を使うときのエスケープは不要です。 しかし、他のデリミタと同様、(メタ文字としてではなく) リテラルとして扱う場合は、 エスケープする必要があります。

パターンの中でデリミタ文字をマッチさせたい場合は、バックスラッシュでエスケープしなければなりません。 パターン内でデリミタが頻繁にあらわれる場合は、 デリミタを別の文字に変更したほうが読みやすくなります。

/http:\/\//
#http://#
preg_quote() 関数を使うと、パターンに使う文字列をエスケープすることができます。 オプションの二番目のパラメータで、エスケープするデリミタを指定します。

終了デリミタの後に パターン修飾子 を付加することもできます。次の例は、大文字小文字を区別しないマッチを行うものです。

#[a-z]#i


メタ文字

正規表現の強力さは、パターン中に選択肢や繰り返しを記述できることに あります。選択肢や繰り返しは、メタ文字 (meta-character) を使ってパターン中に記述します。メタ文字は、 その文字自体を表わさず、代わって特別な解釈が行われます。

メタ文字には、2 種類あります。ひとつは、角カッコ内を除き、 パターン中のどこででも使用できる文字です。もうひとつは、 角カッコで括られた中でだけ使用できる文字です。

前者の角カッコ外で使用できるメタ文字には、次のものがあります。

角カッコ外で使用できるメタ文字
メタ文字 | 説明
\ | 多目的に使う一般的なエスケープ文字
^ | 検索対象（複数行モードでは行）の始まりを言明
$ | 検索対象の終わりあるいは終端の改行文字の前（複数行モードでは行の終わり）を言明
. | 改行を除くすべての文字にマッチ（デフォルト時）
[ | 文字クラス定義の開始
] | 文字クラス定義の終了
| | 選択枝の開始
( | サブパターンの開始
) | サブパターンの終了
? | ( の意味を拡張／0 または 1 回マッチ／なるべく少ない回数だけマッチ (繰り返し を参照)
* | 0 回以上の繰り返し
+ | 1 回以上の繰り返し
{ | 最小／最大を指定する量指定子の開始
} | 最小／最大を指定する量指定子の終了
パターン中の角カッコで括まれた部分を「文字クラス」と言います。 文字クラスで使えるメタ文字は、次のものだけです。
角カッコ内のメタ文字 (文字クラス)
Meta-character | Description
\ | 一般的なエスケープ文字
^ | クラスの否定。ただし、文字クラスの最初の文字に用いた場合のみ
- | 文字の範囲の指定
以降のセクションで、各メタ文字の使用法の説明を行います。


エスケープシーケンス

バックスラッシュ〔日本語環境では円記号となる場合もある〕には、 いくつかの使用法があります。ひとつめの使用法は、 非英数字の前に記述する場合で、続く文字が表す特別な意味を取り去ります。 このエスケープ文字としての使用法は、 文字クラスの内外部いずれでも可能です。

たとえば、"*" 文字とマッチさせたい場合は、パターンを "\*" と記述します。 続く文字がメタ文字として解釈されるものであるかには関係ありませんので、 いかなる非英数字に対しても、"\" を付けると、その文字自体が 表わされることになります。特に、 バックスラッシュとマッチさせたい場合は、"\\" と記述します。

注意:

シングルクォートあるいはダブルクォートで囲まれた PHP の 文字列 の中では、バックスラッシュは特別な意味を表します。 そのため、正規表現 \\ を使用して \ とマッチさせたい場合は PHP のコード内では "\\\\" あるいは '\\\\' と記述する必要があります。

パターンを、 PCRE_EXTENDED オプションを付けてコンパイルすると、（文字クラス内部を除き） パターン中の空白文字、および "#" とその次の改行文字との間の文字は 無視されます。空白文字や "#" をパターン中に含めるには、 バックスラッシュを用いてエスケープします。

バックスラッシュの 2 番目の使用法は、非表示文字〔制御コードなど〕を パターン中に目に見える形で記述するための方法です。ヌル文字は パターンを終了させてしまうため使えませんが、その他の非表示文字は、 パターンにそのまま含めても問題はありません。しかし、パターンの編集には、 バイナリ文字をそのまま用いるよりも、以下に示すエスケープシーケンスを 用いる方が便利でしょう。

\a
アラーム、ベル文字 (16進 07)
\cx
"control-x", ここで x は任意の文字
\e
エスケープ文字 (16進 1B)
\f
改ページ (formfeed) (16進 0C)
\n
改行 (newline) (16進 0A)
\p{xx}
xx プロパティを持つ文字、詳細は unicode プロパティ を参照
\P{xx}
xx プロパティを持たない文字、詳細は unicode プロパティ を参照
\r
復帰 (carriage return) (16進 0D)
\R
改行: \n、\r、\r\n にマッチする
\t
タブ (16進 09)
\xhh
16 進コードで hh の文字
\ddd
8 進コードで ddd の文字、もしくは、後方参照

"\cx" の正確な働きは、次の通りです。 "x" が小文字の場合、 大文字に変換されます。続いて、文字の 6 ビット目 (16進数 40) が 反転されます。つまり、"\cz" は 16 進数の 1A になり、 "\c{" は 3B になり、 "\c;" は 7B になります。

"\x" の後では、2 桁までの 16 進数が読まれます （大小文字どちらも可能です）。 UTF-8 モード では、 "\x{...}" という記法も使えます。 この場合、波括弧の中身は16進数を示す文字列です。 この文字列は、16進数の数値でコードポイントを表す UTF-8 文字として解釈されます。 オリジナルの16進のエスケープシーケンス \xhh は、 値が127より大きい場合、2バイトのUTF-8 文字とマッチします。

"\0" の後では、さらに 2 桁の 8 進数が 読みこまれます。いずれの場合も、2 桁より少ない場合、桁があるだけ 読みこまれます。つまり、"\0\x\07" は ヌル文字 2 つの後にベル文字が 続いたものを表します。8 進数を指定する場合は、必ず最初のゼロに続いて 残りの 2 桁の数字を指定するように注意してください。

バックスラッシュの後に 0 以外の数字が続く場合の処理は複雑です。 文字クラスの外部では、 PCRE は、続く数字全体を 10 進数として読みます。 数字が 10 よりも小さい場合、または、正規表現の中に含まれる キャプチャ用左カッコの数以下の場合、 後方参照 として解釈されます。 この動作に関する詳しい説明は、後ほど、カッコによるサブパターンの説明を 行ってから示します

文字クラスの中、または、指定された 10 進数が 9 より大きく、 キャプチャ用サブパターンの数がこの数に満たない場合は、PCRE は バックスラッシュの後から最大 3 文字の 8 進数を再度読みこみ、 その値の最下位 8 ビットから 1 バイトを生成します。 その後に続く数字は、それ自体を表します。以下に例を示します。

\040
スペースの別の表記法
\40
上と同じ。ただし、キャプチャ用サブパターンが 40 個未満の場合
\7
常に後方参照
\11
後方参照、または、タブの別記法
\011
常にタブ
\0113
タブの後に文字 "3" が続いたもの
\113
8進コードで 113 の文字 (99 を超える後方参照は存在しないため)
\377
全ビットが 1 である 1 バイト
\81
後方参照、または、ヌル文字の後に 2つの文字 "8" および "1" が続いたもの

3 桁を超えて 8 進数は読みこまれないため、100 以上の 8 進数には ゼロを前につけてはいけないことに注意してください。

これらの 1 バイト値を定義するエスケープシーケンスは、 文字クラスの内外部のいずれでも使用できます。加えて、文字クラス内では エスケープシーケンス "\b" はバックスペース (16進 08) として解釈されます。 文字クラス外では、別の意味を有します（別記参照）。

バックスラッシュの第 3 の使用法は、包括的な文字型を指定する用途です。

\d
10 進数字
\D
10 進数字でない文字
\h
水平方向の空白文字
\H
水平方向の空白文字でない文字
\s
空白文字
\S
空白文字でない文字
\v
垂直方向の空白文字
\V
垂直方向の空白文字でない文字
\w
単語構成文字 (word character)
\W
非単語構成文字 (non-word character)

これらエスケープシーケンスの各組により、文字集合が 2 つに分割されます。 文字は、各組のどちらか片方だけにマッチします。

空白文字とは HT (9)、LF (10)、FF (12)、CR (13)、スペース (32) のことです。 しかし、ロケールを指定したマッチングを行った場合には、 128から255までのコードポイントの文字 (たとえば NBSP (A0)) も空白文字とみなされる可能性があります。

単語構成文字とは、英字または数字またはアンダースコア文字であり、Perl が定義するところの「単語」と成り得る文字のことです。文字および数字の 定義は、PCRE の文字テーブルにより制御され、ロケールを指定して マッチングを行うと変わる可能性があります。 例えば、"fr" （フランス語）ロケールの場合、128 を超える 文字コードのいくつかは、アクセント付きの文字に使われており、 これらは \w とマッチします。

これらの文字型表記は、文字クラスの内外によらず使用可能で、 対応する型のたかだか 1 文字とマッチします。現在のマッチング位置が 検索対象文字列の終端である場合、マッチできる文字が無いので、 マッチは失敗します。

バックスラッシュの第 4 の使用法は、簡単な言明 (assertion) です。 言明とは、マッチがある特定の位置でだけ可能だという条件を指定するもので、 検索対象文字列から文字を消費 (consume)〔つまり文字自体にマッチ〕 しません。サブパターンを使ったより複雑な言明の方法もありますが、 それについての解説は後ほど行います。バックスラッシュを使った言明は、 次のものがあります

\b
単語境界
\B
非単語境界
\A
検索対象文字列の始端（複数行モードとは独立）
\Z
検索対象文字列の終端、または終端の改行（複数行モードとは独立）
\z
検索対象文字列の終端（複数行モードとは独立）
\G
マッチングの開始位置

これらの言明は、文字クラス内では使用できません（また、文字クラス内では、 "\b" はバックスペース文字という別の意味を持つので 注意してください）。

単語境界 (word boundary) とは、検索対象文字列において、 カレントの文字およびその前の文字が同時に \w もしくは \W にマッチしない（すなわち、片方が \w にマッチし、もう片方が \W にマッチする）位置、もしくは、文字列の始めか終わりで、 その始めか終わりの文字が \w にマッチする位置の ことです。

言明 \A, \Z, \z は、（アンカー で説明する）ハット記号やドル記号とは 異なり、オプション設定によらず、文字列の始端または終端だけに マッチします。これらの言明は、PCRE_MULTILINE および PCRE_DOLLAR_ENDONLY オプションの影響を受けません。 \Z と \z との違いは、 \Z は文字列の末尾の改行の前の位置および文字列の 終端にマッチするのに対し、\z は文字列の終端にのみ マッチすることです。

言明 \G は、カレントのマッチング位置が、 preg_match() 関数の offset 引数に指定されたマッチングの開始位置である場合に真になります。 offset が非ゼロの場合は、\A と等価ではありません。

\Q と \E とを使って、 パターン中のメタ文字を無視させることができます。 たとえば、 \w+\Q.$.\E$ は、文字列の終端において1つ以上の単語構成文字のあとに .$. というリテラルが続いたものにマッチします。 これらは、デリミタの動作を変更しないことに注意して下さい。 たとえば、#\Q#\E#$ は無効なパターンです。 なぜなら、# がパターンの終端としてマークされ、 \E# が無効な修正子と解釈されるからです。

\K を使用すると、マッチの開始位置をリセットできます。 たとえば、パターン foo\Kbar は "foobar" にマッチしますが、 結果は "bar" にマッチしたと報告されます。 \K を使用しても、キャプチャした部分文字列には影響を及ぼしません。 たとえば、パターン (foo)\Kbar が "foobar" にマッチしたときの最初の部分文字列は "foo" です。


Unicode 文字プロパティ

PHP 5.1.0 以降、UTF-8 モード を設定した場合に、 一般的な文字タイプにマッチする新たなエスケープシーケンスが 3 つ追加されました。

\p{xx}
xx プロパティを持つ文字
\P{xx}
xx プロパティを持たない文字
\X
拡張 Unicode シーケンス

ここで xx で表されているプロパティ名は、Unicode で 一般カテゴリプロパティ (general category properties) として規定されているものに なります。すべての文字は、いずれかひとつのプロパティを持ちます。 プロパティは、2 文字の略語で表されます。Perl と同じく、 開き波カッコとプロパティ名との間にハット文字を記述することで否定を指定できます。 たとえば、\p{^Lu} は \P{Lu} と同じです。

\p もしくは \P の後に、一文字だけを記述すると その文字で始まるすべてのプロパティが指定されたことになります。 この場合、否定の指定をしていない場合、波カッコを使用しなくても構いません。 以下の 2 つの例は等価になります。

\p{L}
\pL

使用可能なプロパティコード
プロパティ | マッチ | 備考
C | その他 (Other) |
Cc | コントロール文字 (Control) |
Cf | 非可視整形用文字 (Format) |
Cn | 未定義コードポイント (Unassigned) |
Co | 私的利用領域 (Private use) |
Cs | サロゲート (Surrogate) |
L | アルファベット (Letter) | Ll、 Lm、Lo、Lt および Lu を含む
Ll | 小文字アルファベット (Lower case letter) |
Lm | 擬似文字 (Modifier letter) |
Lo | その他の文字 (Other letter) |
Lt | タイトル文字 (Title case letter) |
Lu | 大文字アルファベット (Upper case letter) |
M | 記号 (Mark) |
Mc | 修飾文字 (Spacing mark) |
Me | 他の文字を囲むための文字 (Enclosing mark) |
Mn | 他の文字を修飾するための文字 (Non-spacing mark) |
N | 数字 (Number) |
Nd | 10 進数字 (Decimal number) |
Nl | 数値を表す文字 (Letter number) |
No | その他の数字 (Other number) |
P | 句読記号 (Punctuation) |
Pc | 連結用句読記号 (Connector punctuation) |
Pd | ダッシュ (Dash punctuation) |
Pe | 閉じ句読記号 (Close punctuation) |
Pf | 末尾句読記号 (Final punctuation) |
Pi | 先頭句読記号 (Initial punctuation) |
Po | その他の句読記号 (Other punctuation) |
Ps | 開き句読記号 (Open punctuation) |
S | 記号 (Symbol) |
Sc | 通貨記号 (Currency symbol) |
Sk | 合わせ文字 (Modifier symbol) |
Sm | 数学記号 (Mathematical symbol) |
So | その他の記号 (Other symbol) |
Z | 区切り文字 (Separator) |
Zl | 行区切り文字 (Line separator) |
Zp | 段落区切り文字 (Paragraph separator) |
Zs | 空白文字 (Space separator) |

InMusicalSymbols のような拡張プロパティ (extended properties) を、PCRE はサポートしていません。

大小文字を区別しないマッチングを設定していても、これらのエスケープ シーケンスには影響しません。たとえば、\p{Lu} は 常に大文字にのみマッチします。

Unicode の文字は、何らかのスクリプトに属するものとして定義されています。 スクリプト名を指定すれば、そのスクリプトの文字群の一文字にマッチさせることができます。 たとえば、次のように使います。

  • \p{Greek}
  • \P{Han}

どのスクリプトにも属しない文字は、ぜんぶまとめて Common で表します。現在サポートするスクリプトは次のとおりです。

サポートするスクリプト
Arabic | Armenian | Avestan | Balinese | Bamum
Batak | Bengali | Bopomofo | Brahmi | Braille
Buginese | Buhid | Canadian_Aboriginal | Carian | Chakma
Cham | Cherokee | Common | Coptic | Cuneiform
Cypriot | Cyrillic | Deseret | Devanagari | Egyptian_Hieroglyphs
Ethiopic | Georgian | Glagolitic | Gothic | Greek
Gujarati | Gurmukhi | Han | Hangul | Hanunoo
Hebrew | Hiragana | Imperial_Aramaic | Inherited | Inscriptional_Pahlavi
Inscriptional_Parthian | Javanese | Kaithi | Kannada | Katakana
Kayah_Li | Kharoshthi | Khmer | Lao | Latin
Lepcha | Limbu | Linear_B | Lisu | Lycian
Lydian | Malayalam | Mandaic | Meetei_Mayek | Meroitic_Cursive
Meroitic_Hieroglyphs | Miao | Mongolian | Myanmar | New_Tai_Lue
Nko | Ogham | Old_Italic | Old_Persian | Old_South_Arabian
Old_Turkic | Ol_Chiki | Oriya | Osmanya | Phags_Pa
Phoenician | Rejang | Runic | Samaritan | Saurashtra
Sharada | Shavian | Sinhala | Sora_Sompeng | Sundanese
Syloti_Nagri | Syriac | Tagalog | Tagbanwa | Tai_Le
Tai_Tham | Tai_Viet | Takri | Tamil | Telugu
Thaana | Thai | Tibetan | Tifinagh | Ugaritic
Vai | Yi |  |  |

\X は、Unicode 拡張書記素クラスタにマッチします。 拡張書記素クラスタとは、ひとつあるいは複数の Unicode 文字の組み合わせで単一のグリフを構成するものです。 事実上、これは Unicode 版の . だと考えてかまいません。 その文字をレンダリングするために実際に何文字が使われているかは考えずに、ひとつの合成文字に対応します。

8.32 より古いバージョンの PCRE (これは、組み込みの PCRE ライブラリを使っている場合には PHP 5.4.14 より前のバージョンにあたります) では、 \X は (?>\PM\pM*) と等価です。 つまり、記号 (mark) プロパティの付いていない文字と、その後に続く 0 以上の 記号プロパティ付きの文字にマッチし、その並びをアトミック (atomic) な まとまりとして取り扱います。記号プロパティ付きの文字とは、アクセント記号などの 直前の文字に対して影響するようなもののことです。

Unicode プロパティを使った文字列マッチングは速くありません。PCRE は 15,000 以上のデータからなるデータ構造を検索する必要が有るためです。 そのため、PCRE では、\d や \w といった 以前から有るエスケープシーケンスは Unicode プロパティを使用しないように なっています。


アンカー

ハット記号 (^) は、文字クラス外でマッチモード (matching mode) がデフォルトの場合、 カレントのマッチング位置が対象文字列の始端である場合に真だ という言明です。文字クラス内では、ハット記号 (^) はまったく別の意味と なります（別記参照）。

パターン中で選択肢を用いる場合は、ハット記号 (^) は、それが必要な選択肢の 先頭に記述すればよく、パターン全体の先頭にしか記述できない訳では ありません。すべての選択肢がハット記号 (^) で始まる場合、つまり パターンが対象文字列の始端でのみマッチするように制限されている パターンは、固定 (anchored) パターンと呼ばれます（もちろん、 他にもパターンを固定にする方法はあります）。

ドル記号 ($) は、（デフォルトでは）カレントのマッチング位置が 対象文字列の終端にあるか、文字列の終わりの改行文字の直前にある場合に 真だという言明です。パターン中で選択肢を用いる場合は、ドル記号 ($) は、 必要な選択肢の最後に記述すればよく、パターン全体の最後にしか 記述できない訳ではありません。 ドル記号は、文字クラス内では特別な意味を持ちません。

コンパイル時またはマッチング時に PCRE_DOLLAR_ENDONLY オプションを設定すると、ドル記号の動作を文字列の終端でのみ マッチするように変更することができます このオプションは \Z 言明には影響しません。

ハット記号とドル記号の動作は、PCRE_MULTILINE オプションを設定すると変化します。この場合、対象文字列の始端および 終端にマッチするのに加えて、対象文字列の "\n" 文字の直前および直後に それぞれマッチします。例えば、パターン /^abc$/ は、複数行モードに おいては、対象文字列 "def\nabc" にマッチしますが、 複数行モードでない場合はマッチしません。すなわち、すべての選択肢が "^" で始まっており単一行モードでは固定のパターンも、複数行モードでは 固定パターンでなくなります。PCRE_DOLLAR_ENDONLY オプションは、 PCRE_MULTILINE オプションが設定されている場合は無視されます。

どちらのモードでも、エスケープシーケンス \A, \Z, \z は、 対象文字列の始端および終端にマッチすることに注意してください。ですので、 パターン中の選択肢がすべて \A で始まる場合、PCRE_MULTILINE オプションの設定によらず、そのパターンは固定となります。


ドット

パターン中のドット（ピリオド、終止符）は、文字クラス外では、 対象文字列の任意の 1 文字にマッチします。非出力文字も含まれます。 ただし、（デフォルトでは）改行文字とはマッチしません。 PCRE_DOTALL オプションを設定すると、ドットは改行にもマッチするようになります。 ドットの処理は、ハット記号およびドル記号とは完全に独立しています。 共通な点は共に改行文字と関連することだけです。ドットは、 文字クラス内では特別な意味を持ちません。

\C は単一バイトの文字にマッチします。 これは、UTF-8 モード で、ドットが複数バイトの文字にも マッチするような場合に有用です。


文字クラス

開き角カッコは文字クラス (character class) の開始を表し、 閉じ角カッコにより文字クラスは終了します。閉じ角カッコだけでは、 特別な意味を持ちません。閉じ角カッコを文字クラスのメンバとしたい場合は、 文字クラスの最初の文字（否定のハット記号がある場合はその直後）とするか、 バックスラッシュでエスケープする必要があります。

文字クラスは、検索対象文字列のたかだか 1 文字にマッチします。 マッチする文字は、その文字クラスによって定義された文字集合のうちの どれかです。ただし、文字クラスの最初の文字がハット記号の場合は、 マッチする文字は、その文字クラスに定義されていない文字となります。 ハット記号自体をクラスのメンバとしたい場合は、文字クラスの 最初の文字としないか、バックスラッシュでエスケープしてください。

例えば、文字クラス [aeiou] は小文字の母音にマッチしますが、[^aeiou] は 小文字の母音以外の文字にマッチします。ハット記号は、含まれない文字を 列挙することにより文字クラスに含まれる文字を指定するための簡略表記です。 文字クラスは、言明ではありません。対象文字列から文字を消費します。また、 カレントのポインタが文字列の終端にある場合には、マッチに失敗します。

大小文字を区別しないマッチングを行うよう設定した場合は、 クラス内の文字は大小文字の両方を表します。例えば、 大小文字を区別しない場合、[aeiou] は "a" にも "A" にもマッチします。 同じく大小文字を区別しない場合 [^aeiou] は "A" にマッチしませんが、 区別する場合はマッチします

PCRE_DOTALL または PCRE_MULTILINE オプションをどのように設定しようとも、改行文字は、文字クラスにおいて 特別な扱いはされません。たとえば、 [^a] のようなクラスは、 常に改行にマッチします。

マイナス (ハイフン) 記号は、文字クラスで文字の範囲を指定するために 使われます。例えば、[d-m] は d と m の間のあらゆる文字にマッチします。 マイナス記号が文字クラス内に必要な場合は、バックスラッシュで エスケープしてください。もしくは、文字クラスの最初または最後など、 範囲を示すと解釈されない場所に記述してください。

文字リテラル "]" を、文字範囲を示す最後の文字として使うことは できません。 [W-]46] というパターンは、2 つの文字 ("W" および"-") が 含まれるクラスの後に文字列リテラル "46]" が続いていると解釈され、 "W46]" や "-46]" にマッチします。しかし、"]" をバックスラッシュで エスケープすると文字範囲の終端として解釈され、 [W-]46] は、 範囲指定の後に 2 つの文字が続く 1 つのクラスとして解釈されます。 "]" の 8 進あるいは 16 進表現も文字範囲の終端として使用可能です。

文字範囲指定では、ASCII 照合順序 (collating sequence) が用いられます 〔つまり、範囲指定する際の文字の並び順として ASCII が用いられます〕。 [\000-\037] のような、数値的な文字の指定も使用可能です。大小文字を 区別しないマッチングを行うよう設定した場合、パターン中の英字は 大小文字の両方にマッチします。例えば、[W-c] は、[][\^_`wxyzabc] に 等価であり、大小文字に関係なくマッチします。また、 "fr" ロケールの文字テーブルを使う場合、[\xc8-\xcb] は、 大小文字の区別無くアクセント付きの E にマッチします。

文字型 \d, \D, \s, \S, \w, \W も、文字クラス内で使え、 マッチする文字を追加することが可能です。例えば、[ABCDEF] は、 16進数にマッチします。ハット記号と大文字の文字型を組み合わせることで、 小文字の文字型がマッチするものより狭い文字集合を 簡便に指定することができます。例えば、クラス [^\W_] は、 〔単語構成〕文字および数字にマッチしますが、アンダースコアには マッチしません。

\, -, (始端の)^ および終端の ] 以外のすべての非英数字は、 文字クラスにおいて特別な意味を持たない文字ですが、 エスケープしても問題はありません。 パターンの終端文字は常に特別扱いされるので、 正規表現内で私用する場合は必ずエスケープしなければなりません。

Perl は、POSIX 記法の文字クラスもサポートしています。これは、 [: と :] で囲んだ名前を角カッコ内で使うものです。 PCRE でもこの記法に対応しています。たとえば [01[:alpha:]%] は "0"、"1"、任意のアルファベット、あるいは "%" にマッチします。対応しているクラス名は次のとおりです。

文字クラス
alnum | letters and digits
alpha | letters
ascii | character codes 0 - 127
blank | space or tab only
cntrl | control characters
digit | decimal digits (same as \d)
graph | printing characters, excluding space
lower | lower case letters
print | printing characters, including space
punct | printing characters, excluding letters and digits
space | white space (not quite the same as \s)
upper | upper case letters
word | "word" characters (same as \w)
xdigit | hexadecimal digits
space 文字は HT (9), LF (10), VT (11), FF (12), CR (13), およびスペース (32) です。この中に VT 文字 (コード 11) が含まれていることに注目しましょう。 この点で、"space" は \s と異なります。こちらは VT を含みません (Perl との互換性のため)。

word は Perl 拡張で、blank は Perl 5.8 からの GNU 拡張です。それ以外の Perl 拡張には否定があります。否定を指示するには ^ をコロンの後に続けます。たとえば [12[:^digit:]] は "1"、"2"、あるいは任意の非数値にマッチします。

UTF-8 モードでは、128 より大きなコードはどの POSIX 文字クラスにもマッチしません。 libpcre 8.10 以降では、 いくつかの文字クラスが Unicode 文字プロパティを使うように変わりました。 それらの文字クラスでは、ここに挙げた制約はあてはまりません。 詳細は、» PCRE(3) のマニュアル を参照ください。

Unicode 文字プロパティは、文字クラスに含めることができます。 しかし、範囲指定に含めることはできません。 マイナス (ハイフン) を Unicode 文字クラスの後に続けた場合は、その文字としてマッチします。 範囲指定を Unicode 文字プロパティで終えようとすると、警告が発生します。


選択肢

縦線は、パターンに選択肢 (alternative) を列挙するために使われます。 例えば、パターン gilbert|sullivan は、"gilbert" または "sullivan" にマッチします。 選択肢の数に制限はありません。また、空の選択肢も可能です (空の文字列にマッチします)。マッチの手順としては、 各選択肢が左から右に順にマッチするかどうか試行され、 最初にマッチに成功した選択肢が使われます。選択肢を（後述する） サブパターン内に記述した場合、マッチの「成功」とは、 サブパターン内の選択肢も、メインのパターンの他の部分もマッチした ということを意味します。


内部オプション設定

PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL PCRE_UNGREEDY, PCRE_EXTRA, PCRE_EXTENDED および PCRE_DUPNAMES オプションの設定は、パターン中で変更できます。これには、Perl オプション文字を "(?" と ")" とで括った並びを用います。 オプション文字には以下のものがあります。

内部オプション文字
i | PCRE_CASELESS
m | PCRE_MULTILINE
s | PCRE_DOTALL
x | PCRE_EXTENDED
U | PCRE_UNGREEDY
X | PCRE_EXTRA (PHP 7.3.0 以降はサポートされません)
J | PCRE_INFO_JCHANGED

例えば、(?im) は、大小文字を区別しない、複数行モードのマッチングを 設定します。ハイフンを前につけることにより、そのオプションを 解除することも可能です。 (?im-sx) のように設定と解除とを 組み合わせることも可能です。この場合、PCRE_CASELESS と PCRE_MULTILINE とが設定され、PCRE_DOTALL と PCRE_EXTENDED とが解除されます。 オプション文字がハイフンの前にも後にも指定された場合、 そのオプションは解除されます。

オプションの変更がトップレベル（つまりサブパターンのカッコの外）で行われた場合、 その変更はパターンの後ろの部分に適用されます。 パターン /ab(?i)c/ は "abc" および "abC" にマッチします。

サブパターンの内部でオプションの変更を行った場合は、 その効果は違ったものになります。この動作変更は、Perl 5.005 で行われました。サブパターン中のオプション変更は、そのサブパターンの 設定が行われた場所以降の部分にのみ影響します。そのため、パターン (a(?i)b)c は、abc および aBc にマッチし、他の文字列にはマッチしません （PCRE_CASELESS が設定されていないと仮定）。このように、パターンの各場所に 異なった設定を行うようなオプション指定が可能です。 ある選択肢に行われた設定変更は、同じサブパターン中の後に続く選択肢に 波及します。例えば、パターン (a(?i)b|c) は、"ab", "aB", "c", "C" にマッチします。"C" にマッチする場合を 見てみると、オプション設定が行われている最初の選択肢は マッチせずに捨てられてしまっています。それでも、オプションの設定は 行われ "C" にマッチします。これは、オプション設定の効果が コンパイル時に生じることによります。さもないと、 非常に奇妙な動作をするかもしれません。

PCRE 特有のオプション PCRE_UNGREEDY および PCRE_EXTRA は、 それぞれ文字 U および X を用いて、Perl 互換のオプションと同様に 変更することが可能です。 (?X) フラグの設定は特別で、最上位においても、 パターン中で他の設定を有効にする前に指定する必要があります。 このフラグは、最初に指定するのが最善です。


サブパターン

サブパターンは、丸カッコで括られたパターンのことで、ネストも可能です。 パターンの一部をサブパターンにすると、以下の 2 つのことが可能になります。

  1. 選択肢の範囲の指定 (localize)。例えば、パターン cat(aract|erpillar|) は、単語 "cat", "cataract", "caterpillar" にマッチします。 カッコをつけないと、このパターンは、"cataract", "erpillar" または空の文字列にマッチしてしまいます。

  2. サブパターンによる値の取得（キャプチャ）。 パターン全体としてマッチに成功した場合、対象文字列の内、 サブパターンにマッチした部分の値がコールした側に (pcre_exec() の引数 ovector で) 返されます。 開きカッコの数が（1 から始まって）左から右に数えられ、 キャプチャ用サブパターン (capturing subpattern) の番号が指定されます。

例えば、文字列 "the red king" に対し、パターン

      the ((red|white) (king|queen))
をマッチングさせた場合、キャプチャされる部分文字列は、 "red king", "red", "king" であり、 それぞれ 1 番, 2 番, 3 番と番号がふられます。

カッコに 2 つの機能があるということが、いつも良い方に働くわけでは ありません。値をキャプチャする必要はないが、グループ分けのために サブパターンを複数用いたい場合も少なくありません。開きカッコの後に "?:" を付けると、そのサブパターンは値のキャプチャを行わず、 キャプチャ用サブパターンの番号としてもカウントされません。例えば、 文字列 "the white queen" に対し、次のパターンをマッチングさせてみましょう。

      the ((?:red|white) (king|queen))
キャプチャされる部分文字列は、"white queen" と "queen" であり、 それぞれ 1 番と 2 番に番号付けされます。キャプチャ可能な部分文字列の 数は最大で 65535 までです。 そんな大量のパターンをコンパイルするのはそもそも無理かもしれませんが、 そのあたりは libpcre の configure 時のオプションしだいです。

簡略形として、値のキャプチャをしないサブパターンの先頭で オプションの設定をする場合、オプションの文字を "?" と ":" の間に入れることができます。つまり、次の 2 つのパターン、

(?i:saturday|sunday)
(?:(?i)saturday|sunday)

は、まったく同じ文字列集合にマッチします。 選択肢は左から右に試行され、オプションはサブパターンの終端に達するまで リセットされないので、ある選択枝にあるオプション設定は後に続く 選択枝にも作用します。このため、上のパターンは、"Saturday" と同様に "SUNDAY" にもマッチします

(?P<name>pattern) という記法を用いて サブパターンに名前をつけることができます。 このサブパターンにマッチした部分は、マッチ時に返される配列内で 通常どおりの数値添字によるアクセスだけでなく名前でもアクセスできるようになります。 二通りの別の構文 (?<name>pattern) および (?'name'pattern) も用意されています。

複数の条件にマッチさせたいときに、 ひとつの正規表現の中でサブグループを切り替えなければならないこともあります。 通常は、たとえその中のいずれかひとつにしかマッチしなかったとしても それぞれに個別の後方参照番号が振られます。 これを解決するために使えるのが (?| 構文で、 重複した番号を振ることができるようになります。 次の正規表現で文字列 Sunday をマッチングするとどうなるでしょうか。

(?:(Sat)ur|(Sun))day

Sun が後方参照 2 に格納され、 後方参照 1 は空となります。 Saturday にマッチした場合は 後方参照 1 に存在する Sat に入り、 後方参照 2 は存在しません。 この問題を解決するには、パターンを変更して (?| を使うようにします。

(?|(Sat)ur|(Sun))day

このパターンを使えば、Sun と Sat の両方が後方参照 1 に格納されます。


繰り返し

繰り返し (repetition) は、量指定子 (quantifier) を使って指定します。 量指定子は、以下の要素の後に付けることが出来ます。

  • 個々の文字。エスケープされた文字も含む
  • メタ文字 . （ドット）
  • 文字クラス
  • 後方参照 (次のセクションを参照)
  • カッコで括られたサブパターン（言明は除く - 別記参照）

汎用の量指定子 (general repetition quantifier) は、波カッコの中に 2 つの数をカンマで区切って記述したもので、マッチ可能な 最小と最大の繰り返し数を指定します。ただし、65536 以上の数は 指定できません。さらに、最初の数は 2 番目の数以下である必要があります。 例えば、パターン

      z{2,4}
は、"zz", "zzz", "zzzz" にマッチします。閉じ波カッコだけでは 特別な意味を持ちません。カンマを残したまま 2 番目の数だけを省略すると、 繰り返しの上限が設定されません。 2 番目の数字とカンマの両方を省略すると、 必要なマッチの数を過不足なく指定できます。つまり、
      [aeiou]{3,}
は、最短で 3 回母音が連続するものにマッチし、 もっと多く連続する場合にもマッチします。一方、
      \d{8}
は、ぴったり 8 桁の数字にのみマッチします。開き波カッコは、 量指定子を置けない場所、つまり量指定子の構文に適合しない場所に 記述された場合、文字リテラルとして解釈されます。例えば、 {,6} は量指定子ではなく、4つの文字からなる文字リテラルとなります。

{0} という量指定子の指定も可能です。 直前の項目および量指定子が存在しないという指定になります。

簡単（および歴史的な互換性）のため、よく使われる 3 つの量指定子には、 次のような 1 文字の省略型があります。

単一文字の量指定子
* | {0,} と同じ
+ | {1,} と同じ
? | {0,1} と同じ

たとえば

      (a?)*
の様に、「文字無し」にマッチし得るサブパターンの後ろに 上限指定の無い量指定子を記述すると、無限ループができてしまう可能性が あります。

以前のバージョンの Perl および PCRE は、このようなパターンに関して コンパイル時にエラーを発生していました。しかし、有用な場合もあるので、 現在はこのようなパターンも許可されています。ただし、 繰り返しが指定されたサブパターンが文字無しにマッチすると、 ループは強制的に中断されます。

デフォルトでは、量指定子は「貪欲 (greedy)」です。つまり、 残りのパターンが失敗しない限りにおいて、（許可された回数の上限まで） 出来るだけ多くマッチします。 この動作が問題を生じる場合もあります。 そのよく知られた例としては、 C プログラムのコメントに マッチさせようとする場合が挙げられます。 /* と */ との間が コメントですが、コメント中にも文字 * や / が現れる可能性があります。 そこで、C のコメントにマッチさせようとして、パターン

      /\*.*\*/
を使って、文字列
      /* first comment */  not comment  /* second comment */
に対して、マッチングを行うと、文字列全体にマッチしてしまい上手く行きません。 .* 要素が貪欲であるためです。

しかし、量指定子の後に疑問符を付けると、貪欲さは消え、 できるだけ少ない回数だけマッチします。このため、パターン

      /\*.*?\*/
は、C コメントに正しくマッチします。量指定子の他の意味は変化せず、 マッチの回数だけが変更されます。疑問符のこの使用法と、 量指定子としての使用法とを混同しないようにしてください。 このように疑問符には 2 種類の使用法があるため、
      \d??\d
のように 2 重に使うこともできます。 このパターンは、可能であれば 1 桁の数字にマッチします。 パターンの残り部分がそうでないとマッチできない場合に限り、 2 桁の数字にもマッチします。

PCRE_UNGREEDY オプション（Perl ではこのオプションは利用できません）を設定すると、 量指定子は、デフォルトで貪欲でなくなり、 各量指定子の後ろに疑問符をつけてはじめて貪欲になります。言いかえると、 疑問符のデフォルトの動作を逆転します。

量指定子の後ろに + を記述すると「独占的 (possessive)」 になります。可能なだけ多くの文字を取り込み、パターンの残りの部分のマッチの際に 取り込んだ文字を戻すことはしません。したがって、パターン .*abc は "aabc" にマッチしますが、.*+abc はマッチしません。 これは、.*+ が対象文字列のすべてを取り込んでしまうためです。 独占的量指定子を使って処理速度を向上させることができます。

カッコを使ったサブパターンに、最小の繰り返し回数（1 以上）や 最大の繰り返し回数を指定した場合、その繰り返し数の大きさに応じて、 コンパイル済みのパターンが用いる記憶領域がより多く必要となります。

パターンが .* または .{0,} で始まっており、PCRE_DOTALL オプション（Perl の /s に相当）が設定されている（つまり、 . が改行文字にもマッチする）場合、そのパターンは暗黙的に 固定パターンになります。.* もしくは .{0,} の後に続くパターンは、 対象文字列のすべての位置でマッチングが行われますが、パターン全体としては 対象文字列の始端以外でマッチングを再試行しても無駄だからです。PCRE は、 このようなパターンについては、その前に \A が記述されているものとして 扱います。こうした最適化を利用するために、 対象文字列が改行文字を含んでいなことが明らかな場合は、 .* で始まるパターンに対し PCRE_DOTALL を設定するか、 ^ を用いて明示的に固定パターンとなるよう指定すると良いでしょう。

キャプチャ用サブパターンを繰り返した場合、キャプチャされる値は、 繰り返しの最後でマッチした部分文字列です。例えば、

      (tweedle[dume]{3}\s*)+
を "tweedledum tweedledee" にマッチングさせた場合、キャプチャされる 部分文字列は、 "tweedledee" です。しかし、キャプチャ用サブパターンが ネストしている場合、キャプチャされる値は、より前の繰り返しで 得られたものとなる可能性があります。例えば
      /(a|(b))+/
を "aba" にマッチングさせると、キャプチャされた部分文字列の 2 番目のものは、 "b" になります。


後方参照

文字クラス外で、バックスラッシュに続いて 1 以上の数値（複数桁可） を記述したものは、パターン中のより前方（すなわち左）にある キャプチャ用サブパターンに対する後方参照 (back reference) です。ただし、 その左方に、その数値以上の個数のキャプチャ用サブパターンの開きカッコが ある必要があります。

なお、バックスラッシュの後に 10 未満の 10 進数が続く場合は 常に後方参照として解釈され、パターン全体で指定した個数以上の キャプチャ用サブパターンが無いとエラーが発生します。言いかえると、 参照されるカッコは、10未満の番号に対しては、参照する側の左にある必要がないということです。 "前方にある後方参照 (forward back reference)" が意味をなすのは、 繰り返しが含まれていて、右側へのサブパターンがその前の反復に含まれている場合です。 バックスラッシュの後に数字が続く場合の処理の詳細については、 エスケープシーケンス のセクションを参照ください。

後方参照は、カレントの対象文字列においてキャプチャ用サブパターンが 実際にマッチした文字列にマッチします。サブパターンがパターンとして マッチし得るものではありません。すなわち、パターン

      (sens|respons)e and \1ibility
は、"sense and sensibility" および "response and responsibility" にマッチしますが、 "sense and responsibility" にはマッチしません。また、 後方参照が記述されている位置で大小文字を区別するマッチングが有効ならば、 文字の大小文字の別も関係します。例えば、
      ((?i)rah)\s+\1
は、"rah rah" および "RAH RAH" にマッチしますが、 元のキャプチャ用サブパターンは大小文字を区別しないマッチングを 行っているにもかかわらず、"RAH rah" にはマッチしません

同じサブパターンに対して、複数回の後方参照を行うことができます。 また、使われなかったサブパターンに対する後方参照を行おうとすると、 マッチが失敗します。例えば、パターン

      (a|(bc))\2
は、はじめに "bc" でなく "a" にマッチした場合は、マッチが失敗します。 最大 99 番までの後方参照を使用できるため、バックスラッシュの後に 数字が続くものはすべて後方参照番号の可能性があるものとして解釈されます。 後に数字が続く場合、後方参照を終了するためになんらかの区切り文字を 置く必要があります。PCRE_EXTENDED オプションを設定している場合は空白文字を区切り文字として使えます。 その他の場合は空のコメントを使います。

後方参照を、それ自身が参照するサブパターンのカッコ内に記述した場合、 そのサブパターンが最初に使われた際にマッチが失敗します。ですので、 (a\1) は、何にもマッチしません。しかし、このような参照は、 複数回繰り返されるサブパターンの内部では有用です。例えば、パターン

      (a|b\1)+
は、"a" が連続するものや "aba", "ababba" 等にマッチします。 サブパターンが繰り返される場合、後方参照は、直前の繰り返しで一致した 文字列にマッチします。こうしたパターンを動作させるためには、 繰り返しの1 回目に、後方参照を含むパターンとのマッチングが 行われないことが必要です。これには、上の例のように選択肢を使うか、 下限が 0 回の量指定子を使います。

エスケープシーケンス \g を使ってサブパターンの絶対参照および相対参照を行うことができます。 このエスケープシーケンスの後には符号なしの数値あるいは負の数値を続けなければなりません。 数値は波括弧で囲むこともできます。\1 と \g1 および \g{1} は、 すべて同じ意味になります。符号なし数値でこの方式を使えば、 バックスラッシュの後に数値を続ける方式がもつあいまいさを排除できます。 この方式を使えば後方参照と八進数値を明確に区別することができ、 さらに、後方参照のあとに数値リテラルが続く \g{2}1 のようなパターンも書きやすくなります。

\g シーケンスで負の数値を使うと、 それは相対参照を表します。たとえば (foo)(bar)\g{-1} は "foobarbar" にマッチし、(foo)(bar)\g{-2} は "foobarfoo" にマッチします。 これは、長いパターンの中で特定のサブパターンを参照する場合に便利です。 それが何番目のサブパターンになるかをいちいち覚えておくかわりに、 相対指定することができるからです。

名前を指定したサブパターンへの後方参照を行うには (?P=name) とします。 これ以外にも \k<name>, \k'name', \k{name}, \g{name}, \g<name>, \g'name' の形も使えます。


言明

言明 (assertion) とは、カレントのマッチング位置の直前・直後の文字に対する テストであり、文字を消費 (consume)〔つまり文字自体にマッチ〕しません。 単純な言明コード \b, \B, \A, \Z, \z, ^ および $ については、 エスケープシーケンス で説明しました。より複雑な言明は、サブパターンを用いて記述します 〔言明サブパターン (assertion subpattern) と呼ばれる〕。 言明サブパターンには、2 種類あります。対象文字列において カレントの位置の先を読むものと、後ろを読むものです。

言明サブパターンは、カレントのマッチング位置を変更しないことを除き、 通常と同じようにマッチングが行われます。先読み言明 (lookahead assertion) は、 肯定の言明 (positive assertion) の場合 (?= で始まり、 否定の言明 (negative assertion) の場合 (?! で始まります。例えば、

      \w+(?=;)
は、セミコロンが後に続く単語にマッチしますが、 マッチ対象それ自体にはセミコロンは含まれません。また、
      foo(?!bar)
は、"bar" が後ろに続かない "foo" にマッチします。 なお、一見、良く似たパターンですが
      (?!foo)bar
は、"foo" 以外のものの後にある "bar" を見つけるものではないことに 注意してください。これは、どこにある "bar" とでもマッチしてしまいます。 続く 3 文字が "bar" である場合、 (?!foo) は常に真となってしまうからです。 このような探索を実現するためには、戻り読み言明 (lookbehind assertion) が必要です。

戻り読み言明は、肯定の言明の場合 (?<= で始まり、 否定の言明の場合 (?<! で始まります。例えば、

      (?<!foo)bar
は、"foo" 以外の後にある "bar" の存在を見つけるものです。 戻り読み言明内のパターンは、それがマッチし得る文字列の長さが 固定でなければなりません〔繰り返しを指定できません〕。ただし、 選択肢を用いた場合、各選択肢は〔固定長でなければいけませんが〕 すべて同じ長さである必要はありません。つまり、
      (?<=bullock|donkey)
とはできますが、
      (?<!dogs?|cats?)
は、コンパイル時にエラーになります。 戻り読み言明の最上位においてのみ、異なる長さの文字列にマッチするような 選択肢が使用可能です。Perl 5.005 においては、すべての選択肢が 同じ長さの文字列にマッチする必要があります。つまり、この機能は PCRE の拡張モジュールです。
      (?<=ab(c|de))
という戻り読み言明は、最上位にひとつの選択肢しかなく、 その選択肢は異なる長さの文字列にマッチしうるので、不正です。 しかし、
      (?<=abc|abde)
のように、最上位において選択肢を 2 つ用いるように 書き換えると使用可能です。

後方言明の実装においては、選択肢ことに一時的に固定の幅だけ カレントの位置を後退させ、マッチを試みます。カレントの位置の前に 十分な文字がない場合は、マッチは失敗とみなされます。 再試行無しのサブパターンと組み合わせた戻り読み言明は、 文字列の終端でのマッチングに特に有用です。 再試行無しのサブパターンについてのセクションの最後にて例を示します。

（任意の種類の）複数の言明を連続して指定することも可能です。例えば、

      (?<=\d{3})(?<!999)foo
は、"999" でない 3 桁の数字の後にある "foo" にマッチします。 それぞれの言明は、対象文字列の同じ場所に独立して適用されることに 注意して下さい。まず、前の 3 文字がすべて数字であることがチェックされ、 続いて、同じ 3 文字が "999" でないことが確認されます。このパターンは、 "foo" の前に 6 個の文字があり、その前半が数字で後半の 3 文字が "999" でないというパターンにマッチするものではありません。例えば、"123abcfoo" にはマッチしません。これを行うパターンは次のようになります。
      (?<=\d{3}...)(?<!999)foo

この時、最初の言明は、先行する 6 つの文字を探し、 最初の 3 文字が数字であることを確認します。続いて、2 番目の言明は、 先行する 3 文字が "999" でないことを確認します。

言明は、自由に組み合わせてネスト可能です。例えば、

      (?<=(?<!foo)bar)baz
は、"foo" 以外の後にある "bar" の後に有る "bar" があればマッチします。 一方、
      (?<=\d{3}...(?<!999))foo
は、999 でない 3 桁の数字とさらに 3 文字の後に続く "foo" にマッチするパターンです。

言明サブパターンは、キャプチャ用サブパターンではありません 〔値のキャプチャは行われません〕。繰り返しもできません。 同じことを複数回言明しても意味がないからです。 キャプチャ用サブパターンが言明の内部に含まれている場合、 言明の種類に関係なく、キャプチャ用サブパターンの番号付けにあたって カウントされます。しかし、文字列のキャプチャは、肯定の言明に対してのみ 行われます。否定の言明の中で行っても無意味だからです。

カッコ付サブパターンによる言明は、最大 200 まで用いることができます。


再試行無しのサブパターン

繰り返し回数の下限もしくは上限の指定をした場合、 〔繰り返しを指定した要素の〕続きがマッチに失敗すると、 繰り返し指定した要素が再評価され、繰り返し回数を変えた上で 残りのパターンがマッチするかどうか試されます。 マッチングを続けても無駄なことが明らかな場合、マッチングの性質を変え、 より速くマッチに失敗させるために、こうした動作を停止させることが 有用な場合があります。

例えば、パターン \d+foo を "123456bar" という対象文字列に適用した場合を考えてみましょう。

\d+ が 6 桁の数字すべてにマッチしますが、その後 "foo" とのマッチが失敗します。通常のマッチング処理の動作だと、5桁の数字のみが \d+ にマッチするとして再試行され、次いで 4 桁等々と続けられ、 最後には完全にマッチが失敗します。再試行無しのサブパターン (once-only subpattern) を用いると、パターンの一部が一度マッチしたら、 その後再評価されないよう指定することができます。つまり、最初に "foo" とのマッチに失敗した時点で、ただちにマッチングを取り止めることが 可能となります。表記には、

      (?>\d+)bar
のように、(?> で始まる特別なカッコを用います。

この種類のカッコは、一度マッチしたパターンの部分に鍵をかけ (lock up) ます。そのパターンへの再マッチは失敗し、バックトラック (backtrack) が起こらないようにします。それより前の要素に対するバックトラックは、 通常と同様に動作します。

別の説明をすると、このタイプのサブパターンは、同一のスタンドアローンの パターンが対象文字列のカレントの位置に固定されたかのように、 文字列とマッチします。

再試行無しのサブパターンは、キャプチャ用サブパターンではありません 〔つまり、値のキャプチャは行われません〕。上の簡単な例では、 できるだけ多くのものを呑み込むよう繰り返しが最大化されました。つまり、 + や +? は残りのパターンがマッチするよう数字の桁数が調整されるのに 対して、 (?>+) は数字の並び全体に対するマッチングだけしか行われません。

この構文には、どんな複雑なものでも、任意のサブパターンを含むことができ、 ネストも可能です。

再試行無しのサブパターンと戻り読み言明とを組み合わせると、 対象文字列の終端における効率的なマッチングを行うことができます。

      abcd$
というパターンを見てましょう。 マッチが成功しない長い文字列に適用した場合を考えます。 マッチングは左から右に行われるため、PCRE は対象文字列のすべての "a" を探し、 後に続く文字が残りのパターンにマッチするかどうか調べられます。 パターンを
      ^.*abcd$
のように少し変更してみます。 この場合、最初の .* は、まず文字列全体にマッチします。 （"a" がその後に続かないので）マッチが失敗すると、最後の 1 文字を除く 文字列にマッチするようバックトラックが行なわれ、続いて最後の 2 文字を 除く文字列に、という風に動作します。 "a" の検索は、やはり文字列全体に 対して、右から左に、行われるため効率は良くありません。 しかし、パターンを
      ^(?>.*)(?<=abcd)
のようにしてみましょう。 要素 .* に対してバックトラックは行われず、文字列全体にのみマッチします。 続く戻り読み言明は、最後の 4 文字に対するテストを 1 回だけ行います。 テストが失敗すると、マッチはただちに失敗します。長い文字列に対しては、 この方法を用いると実行時間にかなりの差が生じます。

パターン中にサブパターンがあって、その中に繰り返し数に 上限の無い要素があり、そのサブパターン自身も何回でも繰り返しが 可能な場合、マッチの失敗に非常に長い時間がかかってしまう事があります。 それを避ける唯一の方法は再試行無しのサブパターンを使うことです。 パターン

      (\D+|<\d+>)*[!?]
は、非数字もしくは <> で括られた数字に ! または ? が続く 任意の長さの部分文字列にマッチします。マッチが成功するような 対象文字列に対しては、速く動作します。 しかし、これを
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
に適用すると、マッチが失敗するまでに長い時間がかかります。これは、 この対象文字列を分割するやり方が数多くあり、それらすべてに対し マッチを試みられる事になるためです。 （この例で、終端に単一の文字ではなく [!?] を使っているのは、 PCRE と Perl の双方とも、〔終端に〕単一の文字が使われると、 より速く失敗と判定できるように最適化が行われる 〔ので、それを避ける〕ためです。マッチに必要な最後の一文字が記憶され、 文字列にその文字が無い場合、早期に失敗と判定されます。） このパターンを
      ((?>\D+)|<\d+>)*[!?]
のように変更した場合、非数字の部分が分割されることがなくなるので、 より速くマッチが失敗するようになります。


条件付きサブパターン

サブパターンを条件付きでマッチング処理させることが可能です。 言明の結果や直前のキャプチャ用サブパターンがマッチしたかどうかにより、 サブパターン中の 2 つの選択肢を選択させます。条件付きサブパターン (conditional subpattern) には、 2 つの形式があります。

(?(条件)真パターン)
(?(条件)真パターン|偽パターン)

条件が満たされた場合、真パターンが使われます。そうでない場合は、 （もしあれば）偽パターンが使われます。サブパターン内に 3 つ以上の 選択肢があると、コンパイル時にエラーになります。

条件には 2 種類あります。条件のカッコ内が数値の場合、 その番号のキャプチャ用サブパターンがマッチしている場合に条件が 真となります。カッコ内の数値は 1 以上でないといけません。 次のパターンを見てみましょう。可読性を高めるために意味のない空白文字が 挿入され（PCRE_EXTENDED オプションが指定されていると仮定します）、 説明を簡単にするため 3 つの部分に分割されています。

( \( )?    [^()]+    (?(1) \) )

最初の部分は、オプションで、開きカッコにマッチします。 開きカッコが有る場合、1 番のキャプチャ文字列にセットされます。 第 2 の部分は、カッコでない一つ以上の文字にマッチします。第 3 の部分は、 最初のカッコがマッチしたかどうかをテストする条件付きサブパターンです。 カッコにマッチしている場合、つまり、対象文字列が開きカッコで 始まっている場合、条件は真となり、真パターンが実行され、閉じカッコが 必要となります。そうでない場合、偽パターンが存在しないため、 サブパターンは何にもマッチしません。言いかえると、このパターンは、 カッコなしの並びにマッチするものですが、オプションで カッコで囲まれた並びにもマッチします。

(R) という文字列を条件として指定すると、パターン全体もしくは サブパターンへの再帰的呼び出しがなされた場合に、その条件が満たされることになります。 「トップレベル」においては、この条件は偽となります。

数値の他にも、条件として言明が使用できます。先読み言明と 戻り読み言明のいずれも使え、肯定の言明も否定の言明も使用できます。 次のパターンを見てみましょう。このパターンにも意味のない空白文字が 挿入されており、2 行目に 2 つの選択肢が 書かれています。

(?(?=[^a-z]*[a-z])
\d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )

条件は、肯定の先読み言明であり、英字以外の文字の並びの後に英字が 続くものにマッチします。言いかえると、対象文字列に少なくとも英字が 一つあるかどうかが調べられます。英字がみつかると、最初の選択肢に対して 検索対象とのマッチングが行われます。みつからない場合は、2番目の選択肢に 対してマッチングが行われます。このパターンは、2つの形式 dd-aaa-dd または dd-dd-dd のどちらかの文字列にマッチします。ここで、aaa は英字、 dd は数字です。


コメント

コメントは、(?# という並びにより始まり、次の閉じカッコで終わります。 カッコのネストはできません。コメント内の文字は、パターンマッチには 全く関係しません。

PCRE_EXTENDED オプションが設定されている場合は、パターン中の文字クラス外にある エスケープされていない # 文字からもコメントが始まり、 次の改行文字で終わります。

例1 パターンの中でのコメントの使い方

<?php

$subject = 'test';

/* PCRE_EXTENDED を有効にせずにコメントを追加するには, (?# を使います */
$match = preg_match('/te(?# this is a comment)st/', $subject);
var_dump($match);

/* 空白文字と # は、PCRE_EXTENDED が無効の場合、パターンの一部として扱われます */
$match = preg_match('/te #~~~~
st/', $subject);
var_dump($match);

/* PCRE_EXTENDED が有効な場合、全ての空白文字のデータや、エスケープされていない # の後に続く全てが無視されます */
$match = preg_match('/te #~~~~
st/x', $subject);
var_dump($match);

上の例の出力は以下となります。

int(1)
int(0)
int(1)


再帰的パターン

どうすればカッコに括られた文字列とマッチできるか、という問題を 考えて見ましょう。このとき、カッコは何回でもネストできるとします。 再帰が使えないとすると、パターンを用いて、せいぜい、ある一定の深さの ネストまでしかマッチできないでしょう。任意の深さのネストを 処理することは不可能です。Perl 5.6 では、正規表現において再帰を行う 実験的な機能が導入されています。 PCRE では、再帰という特殊なケースに対して専用のシーケンス (?R) が導入されました。上記のカッコ問題を解決する PCRE のコードは 以下のようになります（PCRE_EXTENDED オプションが設定され空白文字が無視されると仮定）。

      \( ( (?>[^()]+) | (?R) )* \)

まず、このパターンは開きカッコにマッチします。続いて、 カッコ以外の文字が並んでいるか、または、再帰的にパターン自体に マッチする（すなわち正しくカッコで括られている）かする部分文字列に 何回でもマッチします。最後に閉じカッコにマッチします。

このパターン例には、ネストした無制限の繰り返しが含まれているため、 マッチが成功し得ない文字列に対してこのパターンが適用される場合も考えて、 カッコ以外の文字列にマッチングさせる部分に再試行無しのサブパターンを 使うことが重要です。例えば、このパターンを

      (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
という文字列に適用すると、「マッチしない」という判定が速やかに 行われます。しかし、再試行無しのサブパターンを使わないと、 対象文字列を分割し得る + と * の繰り返し数の種類が非常に多く、 そのすべてが確認された後にマッチの失敗が報告されるため、 マッチングに非常に時間がかかります。

キャプチャ用サブパターンにセットされる値は、そのサブパターンに 値がセットされ得る最も外側で最も後の再帰レベルからのものになります。 上記のパターンを

      (ab(cd)ef)
にマッチングさせると、キャプチャされる値は "ef" であり、 最上位レベルの最後の値です
      \( ( ( (?>[^()]+) | (?R) )* ) \)
次のようにカッコを追加すると、キャプチャされる文字列は、"ab(cd)ef" となり、最上位レベルのカッコの中身となります。一つのパターン中に 15 以上のキャプチャ用サブパターンを用いると、PCRE は 再帰を行っている間のデータ保存用に追加の記憶領域を確保する必要が あります。記憶領域が確保できない場合、メモリ不足エラーを再帰の内側から 出力する手段がないため、最初の 15 個のキャプチャ用サブパターンに ついてのみデータが保存されます。

(?1), (?2) といった記法が 再帰的サブパターンとして使用可能です。 (?P>name) あるいは (?&name) といった名前付きのサブパターンも使用可能です。

この再帰的サブパターンの記法は（数字によるものも名前によるものの双方とも） 参照するカッコの外で使用でき、プログラム言語のサブルーチンの様に処理されます。 前に示した例で、パターン (sens|respons)e and \1ibility は "sense and sensibility" および "response and responsibility" にはマッチしますが "sense and responsibility" にはマッチしませんでした。 一方、パターン (sens|respons)e and (?1)ibility は、 上記 2 つに加え "sense and responsibility" にもマッチします。 ただし、参照先のサブパターンの後に記述する必要があります。

対象文字列の最大の長さは、integer 型の最大の値となります。 しかし、PCRE は再帰を使用してサブパターンの処理や繰り返し処理を行います。 つまり、そのパターンで処理する対象文字列の長さによって、 使用可能なスタック空間の大きさが制限されるということです。


パフォーマンス

パターンに記述可能な要素のうち、幾つかの要素は、他の要素よりも 効率的に処理されます。 (a|e|i|o|u) のような選択肢の集合よりも [aeiou] のような文字クラスの方が効率的です。一般に、構文が 最も単純なものが、たいてい最も効率が良くなります。Jeffrey Friedl の本には、正規表現の性能を向上させる最適化について 様々な検討が行われています。

パターンが .* で始まり、PCRE_DOTALL オプションを設定した場合、対象文字列の始端でしかマッチできないため、 PCRE は、暗黙のうちにそのパターンを固定パターンとみなします。しかし、 PCRE_DOTALL を設定しない場合、メタ文字 . が改行にマッチせず、 対象文字列が改行を含む場合、パターンは文字列の始端からではなく各改行の 直後の文字からマッチする可能性があるため、PCRE は この最適化を行うことができません。 例えば、パターン

      (.*) second
を、対象文字列 "first\nand second"（ここで、\n は改行文字を意味します）に マッチングさせます。 1 番目のキャプチャ文字列は、"and" になります。 このような動作をするには、 PCRE は対象文字列の各改行文字の後から マッチングを繰り返し行う必要があります。

このようなパターンを、改行を含まない対象文字列に適用する場合は、 PCRE_DOTALL を設定するか、固定パターンであることを明示的に示すためにパターンを ^.* で開始すると最高の性能が得られます。そうすることで、PCRE が対象文字列の改行を探し、そこからマッチングが再び始められることを 防止します。

制限のない繰り返しをネストするようなパターンについては注意が必要です。 そのようなパターンが、マッチが成功し得ない文字列に適用された場合には、 実行に長い時間を要します。

      (a+)*
というパターンを考えてみましょう。

このパターンが "aaaa" にマッチし得る方法は 33 通りもあります（つまり、 * による繰り返しは 0, 1, 2, 3 もしくは 4 回の繰り返しにマッチし、 0 回以外のそれぞれの場合について、 + による繰り返しは様々な回数分 マッチします)〔訳注：a 1文字の 4 回繰り返しとか、 a 1文字とa 3文字の 組合せとかを意味する〕。この数は、文字列が長くなるにつれて急激に 増大します。このパターンの後ろに、マッチが失敗するような別のパターンが 続いていて、パターン全体としてマッチが失敗してしまう場合、PCREは、基本的に 取り得るすべての選択肢を調べるため、非常に長い時間がかかります。

      (a+)*b
のように単一の文字リテラルが最後にある場合には最適化が行われます。 標準のマッチング手順に着手する前に、PCRE は対象文字列の後方に "b" があるかどうかを調べます。無い場合には、直ちにマッチは失敗します。 文字リテラルが最後にない場合には、この最適化は行われません。
      (a+)*\d
というパターンと上に挙げたパターンの動作を比較してみましょう。 "a" 文字だけが連続する行に適用した場合、前者のパターンでは、 ほぼ瞬間的に失敗と判定されます。一方、後者のパターンでは、 文字列の長さがおよそ 20 文字を超えると、かなりの時間がかかります。


PCRE 関数

目次

  • preg_filter — 正規表現による検索と置換を行う
  • preg_grep — パターンにマッチする配列の要素を返す
  • preg_last_error — 直近の PCRE 正規表現処理のエラーコードを返す
  • preg_last_error_msg — 最後に実行した PCRE 正規表現に関するエラーメッセージを返す
  • preg_match — 正規表現によるマッチングを行う
  • preg_match_all — 繰り返し正規表現検索を行う
  • preg_quote — 正規表現文字をクオートする
  • preg_replace — 正規表現検索および置換を行う
  • preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_replace_callback_array — 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_split — 正規表現で文字列を分割する


正規表現による検索と置換を行う

  • ≪ PCRE 関数
  • preg_grep ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現による検索と置換を行う

preg_filter

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

preg_filter — 正規表現による検索と置換を行う

説明

preg_filter(
string|array $pattern,
string|array $replacement,
string|array $subject,
int $limit = -1,
int &$count = null
): string|array|null

preg_filter() は preg_replace() と似ていますが、マッチした結果 (を変換したもの) のみを返します。 この関数の挙動の詳細については preg_replace() のドキュメントを参照ください。

パラメータ

引数の説明は、 preg_replace() にあります。

戻り値

subject が配列の場合は配列を、それ以外の場合は文字列を返します。

マッチする結果が見つからなかったりエラーが発生したりした場合は、 subject が array なら空の配列を返し、そうでなければ null を返します。

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

例

例1 preg_filter() と preg_replace() の比較

<?php
$subject = array('1', 'a', '2', 'b', '3', 'A', 'B', '4');
$pattern = array('/\d/', '/[a-z]/', '/[1a]/');
$replace = array('A:$0', 'B:$0', 'C:$0');

echo "preg_filter returns\n";
print_r(preg_filter($pattern, $replace, $subject));

echo "preg_replace returns\n";
print_r(preg_replace($pattern, $replace, $subject));
?>

上の例の出力は以下となります。

preg_filter returns
Array
(
    [0] => A:C:1
    [1] => B:C:a
    [2] => A:2
    [3] => B:b
    [4] => A:3
    [7] => A:4
)
preg_replace returns
Array
(
    [0] => A:C:1
    [1] => B:C:a
    [2] => A:2
    [3] => B:b
    [4] => A:3
    [5] => A
    [6] => B
    [7] => A:4
)

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_replace() - 正規表現検索および置換を行う
  • preg_replace_callback() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_grep() - パターンにマッチする配列の要素を返す
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す


パターンにマッチする配列の要素を返す

  • ≪ preg_filter
  • preg_last_error ≫
  • PHP Manual
  • PCRE 関数
  • パターンにマッチする配列の要素を返す

preg_grep

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_grep — パターンにマッチする配列の要素を返す

説明

preg_grep(string $pattern, array $array, int $flags = 0): array|false

array 配列の要素のうち、 指定した pattern にマッチするものを要素とする配列を返します。

パラメータ

pattern

検索するパターンを表す文字列。

array

入力の配列。

flags

PREG_GREP_INVERT を設定すると、この関数は 与えた pattern にマッチ しない 要素を返します。

戻り値

array 配列のキーを使用した配列を返します。 失敗した場合に false を返します

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

例

例1 preg_grep() の例

<?php
// すべての浮動小数点数を含む配列要素を返す
$fl_array = preg_grep("/^(\d+)?\.\d+$/", $array);
?>

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_filter() - 正規表現による検索と置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す


直近の PCRE 正規表現処理のエラーコードを返す

  • ≪ preg_grep
  • preg_last_error_msg ≫
  • PHP Manual
  • PCRE 関数
  • 直近の PCRE 正規表現処理のエラーコードを返す

preg_last_error

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

preg_last_error — 直近の PCRE 正規表現処理のエラーコードを返す

説明

preg_last_error(): int

直近の PCRE 正規表現処理のエラーコードを返します。

例1 preg_last_error() の例

<?php

preg_match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');

if (preg_last_error() == PREG_BACKTRACK_LIMIT_ERROR) {
echo 'Backtrack limit was exhausted!';
}

?>

上の例の出力は以下となります。

Backtrack limit was exhausted!

パラメータ

この関数にはパラメータはありません。

戻り値

以下の定数のいずれかを返します (別のページで説明します)。

  • PREG_NO_ERROR
  • PREG_INTERNAL_ERROR
  • PREG_BACKTRACK_LIMIT_ERROR (pcre.backtrack_limit も参照ください)
  • PREG_RECURSION_LIMIT_ERROR (pcre.recursion_limit も参照ください)
  • PREG_BAD_UTF8_ERROR
  • PREG_BAD_UTF8_OFFSET_ERROR
  • PREG_JIT_STACKLIMIT_ERROR

参考

  • preg_last_error_msg() - 最後に実行した PCRE 正規表現に関するエラーメッセージを返す


最後に実行した PCRE 正規表現に関するエラーメッセージを返す

  • ≪ preg_last_error
  • preg_match ≫
  • PHP Manual
  • PCRE 関数
  • 最後に実行した PCRE 正規表現に関するエラーメッセージを返す

preg_last_error_msg

(PHP 8)

preg_last_error_msg — 最後に実行した PCRE 正規表現に関するエラーメッセージを返す

説明

preg_last_error_msg(): string

最後に実行した PCRE 正規表現に関するエラーメッセージを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合はエラーメッセージを返します。 エラーが起きていない場合は、"No error" を返します。

例

例1 preg_last_error_msg() example

<?php

preg_match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');

if (preg_last_error() !== PREG_NO_ERROR) {
echo preg_last_error_msg();
}

?>

上の例の出力は以下となります。

Backtrack limit exhausted

参考

  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す


正規表現によるマッチングを行う

  • ≪ preg_last_error_msg
  • preg_match_all ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現によるマッチングを行う

preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match — 正規表現によるマッチングを行う

説明

preg_match(
string $pattern,
string $subject,
array &$matches = null,
int $flags = 0,
int $offset = 0
): int|false

pattern で指定した正規表現により subject を検索します。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

matches

matches を指定した場合、検索結果が代入されます。 $matches[0] にはパターン全体にマッチしたテキストが代入され、 $matches[1] には 1 番目のキャプチャ用サブパターンにマッチした 文字列が代入され、といったようになります。

flags

flags には以下のフラグの組み合わせを指定できます。

PREG_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも(バイト単位で)返されます。 これは、matches の値を配列に変更することに注意してください。 その配列のすべての要素は、 オフセット 0 で一致した文字列、 およびその文字列のオフセット 1 での subject へのオフセットからなります。

<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => foobarbaz
            [1] => 0
        )

    [1] => Array
        (
            [0] => foo
            [1] => 0
        )

    [2] => Array
        (
            [0] => bar
            [1] => 3
        )

    [3] => Array
        (
            [0] => baz
            [1] => 6
        )

)

PREG_UNMATCHED_AS_NULL

このフラグが渡されると、マッチしなかったサブパターンは null として通知されます。 渡されなかった場合、空の string として通知されます。

<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  string(0) ""
  [3]=>
  string(1) "c"
}
array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  NULL
  [3]=>
  string(1) "c"
}

offset

通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ offset を使用して 検索の開始位置を (バイト単位で) 指定することも可能です。

注意:

offset を用いるのと、 substr($subject, $offset) を preg_match()の対象文字列として指定するのとは 等価ではありません。 これは、pattern には、 ^, $ や (?<=x) のような言明を含めることができるためです。 以下を比べてみてください。

<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);
?>

上の例の出力は以下となります。

Array
(
)

一方、この例を見てください。

<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

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

Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )

)

substr() 関数を利用しない別の方法として、 ^ アンカーではなく、 言明 \G または A 修正子を使う方法があります。 これらは両方とも offset パラメータとともに動作します。

戻り値

preg_match() は、pattern が指定した subject にマッチした場合に 1 を返します。 マッチしなかった場合は 0 を返します。 失敗した場合に false を返します

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

変更履歴

バージョン | 説明
7.2.0 | $flags パラメータが PREG_UNMATCHED_AS_NULL をサポートしました。

例

例1 文字列 "php" を探す

<?php
// パターンのデリミタの後の "i" は、大小文字を区別しない検索を示す
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
echo "A match was found.";
} else {
echo "A match was not found.";
}
?>

例2 単語 "web" を探す

<?php
/* パターン内の \b は単語の境界を示す。このため、独立した単語の
* "web"にのみマッチし、"webbing" や "cobweb" のような単語の一部にはマッチしない */
if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
echo "A match was found.";
} else {
echo "A match was not found.";
}

if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
echo "A match was found.";
} else {
echo "A match was not found.";
}
?>

例3 URL からドメイン名を得る

<?php
// get host name from URL
preg_match('@^(?:http://)?([^/]+)@i',
"http://www.php.net/index.html", $matches);
$host = $matches[1];

// get last two segments of host name
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "domain name is: {$matches[0]}\n";
?>

上の例の出力は以下となります。

domain name is: php.net

例4 名前つきサブパターンの使用法

<?php

$str = 'foobar: 2008';

preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

/* 別のやり方 */
// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

上の例の出力は以下となります。

Array
(
    [0] => foobar: 2008
    [name] => foobar
    [1] => foobar
    [digit] => 2008
    [2] => 2008
)

注意

ヒント

ある文字列が他の文字列内に含まれているかどうかを調べるためだけに preg_match() を使うのは避けた方が良いでしょう。 strpos() 関数を使うほうが速くなります。

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • preg_last_error_msg() - 最後に実行した PCRE 正規表現に関するエラーメッセージを返す


繰り返し正規表現検索を行う

  • ≪ preg_match
  • preg_quote ≫
  • PHP Manual
  • PCRE 関数
  • 繰り返し正規表現検索を行う

preg_match_all

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match_all — 繰り返し正規表現検索を行う

説明

preg_match_all(
string $pattern,
string $subject,
array &$matches = null,
int $flags = 0,
int $offset = 0
): int|false

subject を検索し、 pattern に指定した正規表現にマッチした すべての文字列を、flags で指定した 順番で、matches に代入します。

正規表現にマッチすると、そのマッチした文字列の後から 検索が続行されます。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

matches

マッチしたすべての内容を含む、 flags で指定した形式の多次元配列。

flags

以下のフラグの組み合わせ (PREG_PATTERN_ORDER を PREG_SET_ORDER と組み合わせて使用することは 無意味ですので注意してください)。

PREG_PATTERN_ORDER

$matches[0] はパターン全体にマッチした文字列の配列、 $matches[1] は第 1 のキャプチャ用サブパターンにマッチした文字列の配列、 といった順番となります。

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
"<b>example: </b><div align=left>this is a test</div>",
$out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

上の例の出力は以下となります。

<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test

$out[0] はパターン全体にマッチした文字列の配列を有しており、 $out[1] はタグで囲まれた文字列の配列を有しています。

パターンに名前付きサブパターンが含まれる場合は、$matches にはサブパターン名のキーも含まれるようになります。

サブパターンの名前が重複している場合は、いちばん右側のサブパターンだけが $matches[NAME] に格納されます。

<?php
preg_match_all(
'/(?J)(?<match>foo)|(?<match>bar)/',
'foo bar',
$matches,
PREG_PATTERN_ORDER
);
print_r($matches['match']);
?>

上の例の出力は以下となります。

Array
(
    [0] =>
    [1] => bar
)

PREG_SET_ORDER

$matches[0] は 1 回目のマッチングでキャプチャした値の配列、 $matches[1] は 2 回目のマッチングでキャプチャした値の配列、 といった順序となります。

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
"<b>example: </b><div align=\"left\">this is a test</div>",
$out, PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

上の例の出力は以下となります。

<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test

PREG_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも(バイト単位で)返されます。 これは、matches の値を配列の配列に変更することに注意してください。 その配列のすべての要素は、 オフセット 0 で一致した文字列 およびその文字列のオフセット 1 での subject へのオフセットからなります。

<?php
preg_match_all('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => foobarbaz
                    [1] => 0
                )

        )

    [1] => Array
        (
            [0] => Array
                (
                    [0] => foo
                    [1] => 0
                )

        )

    [2] => Array
        (
            [0] => Array
                (
                    [0] => bar
                    [1] => 3
                )

        )

    [3] => Array
        (
            [0] => Array
                (
                    [0] => baz
                    [1] => 6
                )

        )

)

PREG_UNMATCHED_AS_NULL

このフラグが渡されると、 マッチしなかったサブパターンがあった場合 null として通知されます。 このフラグが渡されない場合、 空の string として通知されます。

flags を指定しない場合は、 PREG_PATTERN_ORDER が指定されたことになります。

offset

通常、検索は対象文字列の先頭から開始されます。 オプションのパラメータ offset を使用して 検索の開始位置を (バイト単位で) 指定することも可能です。

注意:

offset を用いるのと、 substr($subject, $offset) を preg_match_all()の対象文字列として指定するのとは 等価ではありません。 これは、pattern には、 ^, $ や (?<=x) のような言明を含めることができるためです。 これに関する例については、 preg_match() を参照ください。

戻り値

パターンがマッチした総数を返します（ゼロとなる可能性もあります）。 失敗した場合に false を返します

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

変更履歴

バージョン | 説明
7.2.0 | $flags パラメータが PREG_UNMATCHED_AS_NULL をサポートしました。

例

例1 テキストからすべての電話番号を得る

<?php
preg_match_all("/\(? (\d{3})? \)? (?(1) [\-\s] ) \d{3}-\d{4}/x",
"Call 555-1212 or 1-800-555-1212", $phones);
?>

例2 HTML タグにマッチするものを見付ける（貪欲）

<?php
// \\2 は後方参照の例。これは、pcre に正規表現中の括弧の 2 番目の
// 組、つまりこの場合は ([\w]+)、にマッチする。文字列が二重引用符で
// 括られているため、バックスラッシュの追加が必要。
$html = "<b>bold text</b><a href=howdy.html>click me</a>";

preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);

foreach ($matches as $val) {
echo "matched: " . $val[0] . "\n";
echo "part 1: " . $val[1] . "\n";
echo "part 2: " . $val[2] . "\n";
echo "part 3: " . $val[3] . "\n";
echo "part 4: " . $val[4] . "\n\n";
}
?>

上の例の出力は以下となります。

matched: <b>bold text</b>
part 1: <b>
part 2: b
part 3: bold text
part 4: </b>

matched: <a href=howdy.html>click me</a>
part 1: <a href=howdy.html>
part 2: a
part 3: click me
part 4: </a>

例3 名前つきサブパターンの使用法

<?php

$str = <<<FOO
a: 1
b: 2
c: 3
FOO;

preg_match_all('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

/* 別のやり方 */
// preg_match_all('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => a: 1
            [1] => b: 2
            [2] => c: 3
        )

    [name] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [1] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [digit] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

    [2] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

)

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_match() - 正規表現によるマッチングを行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_split() - 正規表現で文字列を分割する
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す


正規表現文字をクオートする

  • ≪ preg_match_all
  • preg_replace ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現文字をクオートする

preg_quote

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_quote — 正規表現文字をクオートする

説明

preg_quote(string $str, ?string $delimiter = null): string

preg_quote() は、str を引数とし、正規表現構文の特殊文字の前にバックスラッシュを挿入します。 この関数は、実行時に生成される文字列をパターンとしてマッチングを行う必要があり、 その文字列には正規表現の特殊文字が含まれているかも知れない場合に有用です。

正規表現の特殊文字は、次のものです。 . \ + * ? [ ^ ] $ ( ) { } = ! < > | : - #

/ は正規表現の特殊文字ではないことに注意しましょう。

注意:

preg_quote() は、 preg_replace() などにおける $replacement 文字列に使うことを想定したものではありません。

パラメータ

str

入力文字列。

delimiter

オプションの delimiter を指定すると、 ここで指定した文字もエスケープされます。これは、PCRE 関数が使用する デリミタをエスケープする場合に便利です。/ がデリミタとしては 最も一般的に使用されています。

戻り値

クォートされた (エスケープした) 文字列を返します。

変更履歴

バージョン | 説明
7.3.0 | # 文字がクォートされるようになりました。
7.2.0 | delimiter は、nullable になりました。

例

例1 preg_quote() の例

<?php
$keywords = '$40 for a g3/400';
$keywords = preg_quote($keywords, '/');
echo $keywords; // \$40 for a g3\/400 を返します
?>

例2 テキスト内の単語の斜体変換

<?php
// この例では、preg_quote($word) を使って、アスタリスクが
// 正規表現での特殊な意味を帯びないようにしています

$textbody = "This book is *very* difficult to find.";
$word = "*very*";
$textbody = preg_replace ("/" . preg_quote($word, '/') . "/",
"<i>" . $word . "</i>",
$textbody);
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • PCRE パターン
  • escapeshellcmd() - シェルのメタ文字をエスケープする


正規表現検索および置換を行う

  • ≪ preg_quote
  • preg_replace_callback ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現検索および置換を行う

preg_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_replace — 正規表現検索および置換を行う

説明

preg_replace(
string|array $pattern,
string|array $replacement,
string|array $subject,
int $limit = -1,
int &$count = null
): string|array|null

subject に関して pattern を用いて検索を行い、 replacement に置換します。

パターンではなく、文字列と正確にマッチさせたい場合、 この関数の代わりに str_replace() や str_ireplace() を使うことを検討してください。

パラメータ

pattern

検索を行うパターン。文字列もしくは配列とすることができます。

PCRE 修飾子 も使えます。

replacement

置換を行う文字列もしくは文字列の配列。 この引数が文字列で、pattern 引数が配列の場合、 すべてのパターンがこの文字列に置換されます。 pattern および replacement のいずれもが配列の場合、各 pattern は 対応する replacement に置換されます。 もし、replacement 配列の要素の数が pattern 配列よりも少ない場合は、余った pattern は 空文字に置換されます。

replacement では、 \n 形式または $n 形式で参照を指定することができます。 後者の形式の方が好ましい形式です。各参照は、n 番目のキャプチャ用サブパターンにマッチしたテキストにより置換されます。 n は 0 から 99 までとすることができ、 \0 または $0 は パターン全体にマッチするテキストを参照します。キャプチャ用サブパターンの番号 については、その左括弧が左から右に（1から）カウントされます。 string に含まれるバックスラッシュリテラルは、エスケープが必須であることに注意して下さい。

後方参照の直後に他の数字が続くような置換 (replacement) パターンを 使用する場合（すなわち、マッチしたパターンの直後に数字リテラルを置く 場合）、後方参照を行うために通常の \1 表記を 使用することができません。例えば、\11　は、 後方参照 \1 の後にリテラル 1 が続くのか、後方参照 \11 で その後には何も続かないのかが不明のため、 preg_replace() を混乱させる可能性があります。 この場合、解決策は、${1}1 を使用することです。 こうすることで、1 はリテラルとなり、後方参照 $1 を明確に作成できます。

非推奨の e 修飾子を使用する際に、 この関数は後方参照を置換する文字列のうちの特定の文字 (具体的には '、"、 \ および NULL) をエスケープします。 これは、後方参照をシングルクォートやダブルクォートを共用した場合 (たとえば 'strlen(\'$1\')+strlen("$2")') に構文エラーが発生しないようにするためのものです。 PHP の 文字列構文 を意識し、 文字列がどのように解釈されるのかを正確に知っておくようにしましょう。

subject

検索・置換対象となる文字列もしくは文字列の配列

subject が配列の場合、検索と置換は subject の各要素に対して行われ、戻り値も配列となります。

subject が連想配列の場合、 キーは戻り値でも保持されます。

limit

subject 文字列において、各パターンによる 置換を行う最大回数。デフォルトは -1 (制限無し)。

count

この引数が指定されると、置換回数が渡されます。

戻り値

preg_replace() は、 subject 引数が配列の場合は配列を、 その他の場合は文字列を返します。

パターンがマッチした場合、〔置換が行われた〕新しい subject を返します。マッチしなかった場合、subject をそのまま返します。エラーが発生した場合、null を返します。

エラー / 例外

"\e" 修飾子を使うと、 E_WARNING レベルのエラーが発生します。

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

例

例1 数字リテラルが後に続く後方参照

<?php
$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?>

上の例の出力は以下となります。

April1,2003

例2 添字配列の使用

<?php
$string = 'The quick brown fox jumps over the lazy dog.';
$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';
$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?>

上の例の出力は以下となります。

The bear black slow jumps over the lazy dog.

pattern と replacement を ksort すると、所望のものが得られます。

<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?>

上の例の出力は以下となります。

The slow black bear jumps over the lazy dog.

例3 複数値の置換

<?php
$patterns = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
'/^\s*{(\w+)}\s*=/');
$replace = array ('\3/\4/\1\2', '$\1 =');
echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
?>

上の例の出力は以下となります。

$startDate = 5/27/1999

例4 空白の削除

この例は、文字列から余分な空白を取り除きます。

<?php
$str = 'foo o';
$str = preg_replace('/\s\s+/', ' ', $str);
// This will be 'foo o' now
echo $str;
?>

例5 count 引数の使用

<?php
$count = 0;

echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; //3
?>

上の例の出力は以下となります。

xp***to
3

注意

注意:

pattern および replacement を使用する際、配列の並び順に処理されます。添字は整数であっても、 その並びは値の小さい順になっているとは限りません。 ですから、配列の添字を使って、どの pattern が、どの replacement に置換されるかを指定しようとする場合は、 preg_replace() をコールする前に、各配列に対し ksort() を実行しておくべきです。

注意:

pattern と replacement が両方配列の場合、 ルールのマッチは順番に行われます。 つまり、 二番目の pattern/replacement のペアは、最初の pattern/replacement のペアの適用結果に対して行われます。 オリジナルの文字列に対しては行われません。 ふたつの値の交換のような、置換の操作を並列で行わせたい場合は、 中間のプレースホルダー内で一方のパターンを置換した後に、 そのプレースホルダーに対して望んだ置換を行うようにしましょう。

<?php
$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');
print_r(preg_replace($p, $r, 'a'));
// prints d
?>

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • preg_filter() - 正規表現による検索と置換を行う
  • preg_match() - 正規表現によるマッチングを行う
  • preg_replace_callback() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_split() - 正規表現で文字列を分割する
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • str_replace() - 検索文字列に一致したすべての文字列を置換する


正規表現検索を行い、コールバック関数を使用して置換を行う

  • ≪ preg_replace
  • preg_replace_callback_array ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現検索を行い、コールバック関数を使用して置換を行う

preg_replace_callback

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う

説明

preg_replace_callback(
string|array $pattern,
callable $callback,
string|array $subject,
int $limit = -1,
int &$count = null,
int $flags = 0
): string|array|null

この関数の動作は、ほぼ preg_replace() と同じですが、 replacement の代わりに callback を指定するところが異なります。

パラメータ

pattern

検索するパターン。 文字列あるいは文字列の配列のいずれかとなります。

callback

このコールバック関数は、検索対象文字列でマッチした要素の配列が指定されて コールされます。このコールバック関数は、置換後の文字列を返す必要があります。 コールバックのシグネチャは、次のとおりです。

handler(array $matches): string

preg_replace_callback() 用の callback 関数が、 ひとつの場所だけで必要となることがあります。 そんな場合は、 無名関数 を使って宣言した無名関数を preg_replace_callback() のコール時に使用します。 このようにすることにより、コールに関するすべての情報を 1 ヶ所に集め、 他の場所で使用されないコールバック関数名で関数の名前空間を 汚染しないようにすることができます。

例1 preg_replace_callback() と無名関数

<?php
/* Unix 方式のコマンドラインフィルタです。
* 段落の冒頭の大文字を、小文字に変換します。*/
$fp = fopen("php://stdin", "r") or die("標準入力から読み込めません");
while (!feof($fp)) {
$line = fgets($fp);
$line = preg_replace_callback(
'|<p>\s*\w|',
function ($matches) {
return strtolower($matches[0]);
},
$line
);
echo $line;
}
fclose($fp);
?>

subject

文字列あるいは文字列の配列で、 検索および置換の対象となる文字列を指定します。

limit

subject 文字列における 各パターンの最大置換回数。デフォルトは -1 (無制限) です。

count

指定した場合は、置換を行った回数がここに格納されます。

flags

flags には、 PREG_OFFSET_CAPTURE と PREG_UNMATCHED_AS_NULL の組み合わせが指定できます。 これは matches 配列のフォーマットに影響します。 詳細は preg_match() 関数の説明を参照ください。

戻り値

preg_replace_callback() は、 subject が配列の場合には配列を、 それ以外の場合は文字列を返します。 エラー時の戻り値は null となります。

マッチするものが見つかった場合は新しい subject を返し、それ以外の場合はもとの subject をそのまま返します。

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

変更履歴

バージョン | 説明
7.4.0 | パラメータ flags が追加されました。

例

例2 preg_replace_callback() の例

<?php
// このテキストは 2002 に使われていたものなのですが、
// これを 2003 年対応の日付に変更したいのです
$text = "エイプリルフールの日付は 04/01/2002 です\n";
$text.= "この前のクリスマスの日付は 12/24/2001 でした\n";
// コールバック関数
function next_year($matches)
{
// 通常は、$matches[0] がマッチした全体を表します。
// $matches[1] は、マッチした中で、パターン内の最初の '(...)'
// にあてはまる部分を表します。それ以降も同様です。
return $matches[1].($matches[2]+1);
}
echo preg_replace_callback(
"|(\d{2}/\d{2}/)(\d{4})|",
"next_year",
$text);

?>

上の例の出力は以下となります。

エイプリルフールの日付は 04/01/2003 です
この前のクリスマスの日付は 12/24/2002 でした

例3 カプセル化された BB code を処理するための、 preg_replace_callback() での再帰構造の使用

<?php
$input = "通常の位置 [indent] 字下げ [indent] もっと字下げ [/indent] 字下げ [/indent] 通常の位置";

function parseTagsRecursive($input)
{

$regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';

if (is_array($input)) {
$input = '<div style="margin-left: 10px">'.$input[1].'</div>';
}

return preg_replace_callback($regex, 'parseTagsRecursive', $input);
}

$output = parseTagsRecursive($input);

echo $output;
?>

参考

  • PCRE のパターン
  • preg_replace_callback_array() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_quote() - 正規表現文字をクオートする
  • preg_replace() - 正規表現検索および置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • 無名関数


正規表現検索を行い、コールバック関数を使用して置換を行う

  • ≪ preg_replace_callback
  • preg_split ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現検索を行い、コールバック関数を使用して置換を行う

preg_replace_callback_array

(PHP 7, PHP 8)

preg_replace_callback_array — 正規表現検索を行い、コールバック関数を使用して置換を行う

説明

preg_replace_callback_array(
array $pattern,
string|array $subject,
int $limit = -1,
int &$count = null,
int $flags = 0
): string|array|null

この関数の動作は、preg_replace_callback() に似ていますが、 コールバック関数が、パターン単位ペースで実行されるところが異なります。

パラメータ

pattern

パターンをキーとし、callable を値とする連想配列です。

subject

文字列あるいは文字列の配列で、 検索および置換の対象となる文字列を指定します。

limit

subject 文字列における 各パターンの最大置換回数。デフォルトは -1 (無制限) です。

count

指定した場合は、置換を行った回数がここに格納されます。

flags

flags には、 PREG_OFFSET_CAPTURE と PREG_UNMATCHED_AS_NULL の組み合わせが指定できます。 これは matches 配列のフォーマットに影響します。 詳細は preg_match() 関数の説明を参照ください。

戻り値

preg_replace_callback_array() は、 subject が配列の場合には配列を、 それ以外の場合は文字列を返します。 エラー時の戻り値は null となります。

マッチするものが見つかった場合は新しい subject を返し、それ以外の場合はもとの subject をそのまま返します。

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

変更履歴

バージョン | 説明
7.4.0 | パラメータ flags が追加されました。

例

例1 preg_replace_callback_array() の例

<?php
$subject = 'Aaaaaa Bbb';

preg_replace_callback_array(
[
'~[a]+~i' => function ($match) {
echo strlen($match[0]), ' matches for "a" found', PHP_EOL;
},
'~[b]+~i' => function ($match) {
echo strlen($match[0]), ' matches for "b" found', PHP_EOL;
}
],
$subject
);
?>

上の例の出力は以下となります。

6 matches for "a" found
3 matches for "b" found

参考

  • PCRE のパターン
  • preg_replace_callback() - 正規表現検索を行い、コールバック関数を使用して置換を行う
  • preg_quote() - 正規表現文字をクオートする
  • preg_replace() - 正規表現検索および置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
  • 無名関数


正規表現で文字列を分割する

  • ≪ preg_replace_callback_array
  • ssdeep ≫
  • PHP Manual
  • PCRE 関数
  • 正規表現で文字列を分割する

preg_split

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_split — 正規表現で文字列を分割する

説明

preg_split(
string $pattern,
string $subject,
int $limit = -1,
int $flags = 0
): array|false

指定した文字列を、正規表現で分割します。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

limit

これを指定した場合、最大 limit 個の部分文字列を返します。 残りの文字列は、最後の部分文字列に含めて返されます。 limit が -1 あるいは 0 の場合は「制限が無い」ことを意味します。

flags

flags は、次のフラグを組み合わせたものとする （ビット和演算子 | で組み合わせる）ことが可能です。

PREG_SPLIT_NO_EMPTY
このフラグを設定すると、空文字列でないものだけが preg_split() により返されます。
PREG_SPLIT_DELIM_CAPTURE
このフラグを設定すると、文字列分割用のパターン中の カッコによるサブパターンでキャプチャされた値も同時に返されます。
PREG_SPLIT_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも返されます。 これにより、戻り値は配列となり、配列の要素 0 はマッチした文字列、 要素 1 は subject におけるマッチした文字列のオフセット値となることに 注意してください。

戻り値

pattern にマッチした境界で分割した subject の部分文字列の配列を返します。失敗した場合に false を返します。

エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、E_WARNING が発生します。

例

例1 preg_split() の例 : 検索文字列のある部分を取得

<?php
// カンマまたは " ", \r, \t, \n , \f などの空白文字で句を分割する。
$keywords = preg_split("/[\s,]+/", "hypertext language, programming");
print_r($keywords);
?>

上の例の出力は以下となります。

Array
(
    [0] => hypertext
    [1] => language
    [2] => programming
)

例2 文字列を文字要素に分割

<?php
$str = 'string';
$chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
print_r($chars);
?>

上の例の出力は以下となります。

Array
(
    [0] => s
    [1] => t
    [2] => r
    [3] => i
    [4] => n
    [5] => g
)

例3 文字列をマッチするものとそのオフセットに分割

<?php
$str = 'hypertext language programming';
$chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
print_r($chars);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => hypertext
            [1] => 0
        )

    [1] => Array
        (
            [0] => language
            [1] => 10
        )

    [2] => Array
        (
            [0] => programming
            [1] => 19
        )

)

注意

ヒント

正規表現の威力を必要としないのなら、より高速な (機能はシンプルですが) 代替関数として explode() あるいは str_split() のような選択肢があります。

ヒント

マッチングに失敗した場合は、要素が一つだけの配列を返します。その要素の内容は、入力文字列そのままになります。

参考

  • PCRE のパターン
  • preg_quote() - 正規表現文字をクオートする
  • implode() - 配列要素を文字列により連結する
  • preg_match() - 正規表現によるマッチングを行う
  • preg_match_all() - 繰り返し正規表現検索を行う
  • preg_replace() - 正規表現検索および置換を行う
  • preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す


ssdeep Fuzzy Hashing

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • ssdeep 関数
    • ssdeep_fuzzy_compare — Calculates the match score between two fuzzy hash signatures
    • ssdeep_fuzzy_hash — Create a fuzzy hash from a string
    • ssdeep_fuzzy_hash_filename — Create a fuzzy hash from a file


はじめに

ssdeep is a utility for creating and comparing fuzzy hashes or » context-triggered piecewise hashing.

Fuzzy hashing can match signatures which have "...sequences of identical bytes in the same order, although bytes in between these sequences may be different in both content and length". (» ssdeep project page)

This extension provides functions for creating and comparing fuzzy hashes.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • ssdeep
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

この拡張モジュールには、» ssdeep ライブラリが必要です。


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ssdeep.


ssdeep 関数

目次

  • ssdeep_fuzzy_compare — Calculates the match score between two fuzzy hash signatures
  • ssdeep_fuzzy_hash — Create a fuzzy hash from a string
  • ssdeep_fuzzy_hash_filename — Create a fuzzy hash from a file


Calculates the match score between two fuzzy hash signatures

  • ≪ ssdeep 関数
  • ssdeep_fuzzy_hash ≫
  • PHP Manual
  • ssdeep 関数
  • Calculates the match score between two fuzzy hash signatures

ssdeep_fuzzy_compare

(PECL ssdeep >= 1.0.0)

ssdeep_fuzzy_compare — Calculates the match score between two fuzzy hash signatures

説明

ssdeep_fuzzy_compare(string $signature1, string $signature2): int

Calculates the match score between signature1 and signature2 using » context-triggered piecewise hashing, and returns the match score.

パラメータ

signature1

The first fuzzy hash signature string.

signature2

The second fuzzy hash signature string.

戻り値

Returns an integer from 0 to 100 on success, false otherwise.


Create a fuzzy hash from a string

  • ≪ ssdeep_fuzzy_compare
  • ssdeep_fuzzy_hash_filename ≫
  • PHP Manual
  • ssdeep 関数
  • Create a fuzzy hash from a string

ssdeep_fuzzy_hash

(PECL ssdeep >= 1.0.0)

ssdeep_fuzzy_hash — Create a fuzzy hash from a string

説明

ssdeep_fuzzy_hash(string $to_hash): string

ssdeep_fuzzy_hash() calculates the hash of to_hash using » context-triggered piecewise hashing, and returns that hash.

パラメータ

to_hash

The input string.

戻り値

Returns a string on success, false otherwise.


Create a fuzzy hash from a file

  • ≪ ssdeep_fuzzy_hash
  • 文字列 ≫
  • PHP Manual
  • ssdeep 関数
  • Create a fuzzy hash from a file

ssdeep_fuzzy_hash_filename

(PECL ssdeep >= 1.0.0)

ssdeep_fuzzy_hash_filename — Create a fuzzy hash from a file

説明

ssdeep_fuzzy_hash_filename(string $file_name): string

ssdeep_fuzzy_hash_filename() calculates the hash of the file specified by file_name using » context-triggered piecewise hashing, and returns that hash.

パラメータ

file_name

The filename of the file to hash.

戻り値

Returns a string on success, false otherwise.


文字列

  • はじめに
  • インストール/設定
    • インストール手順
  • 定義済み定数
  • String 関数
    • addcslashes — C 言語と同様にスラッシュで文字列をクォートする
    • addslashes — 文字列をスラッシュでクォートする
    • bin2hex — バイナリのデータを16進表現に変換する
    • chop — rtrim のエイリアス
    • chr — 数値から、1バイトの文字列を生成する
    • chunk_split — 文字列をより小さな部分に分割する
    • convert_cyr_string — キリル文字セットを他のものに変換する
    • convert_uudecode — uuencode された文字列をデコードする
    • convert_uuencode — 文字列を uuencode する
    • count_chars — 文字列で使用されている文字に関する情報を返す
    • crc32 — 文字列の crc32 多項式計算を行う
    • crypt — 文字列の一方向のハッシュ化を行う
    • echo — 1 つ以上の文字列を出力する
    • explode — 文字列を文字列により分割する
    • fprintf — フォーマットされた文字列をストリームに書き込む
    • get_html_translation_table — htmlspecialchars および htmlentities で使用される変換テーブルを返す
    • hebrev — 論理表記のヘブライ語を物理表記に変換する
    • hebrevc — 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する
    • hex2bin — 16進エンコードされたバイナリ文字列をデコードする
    • html_entity_decode — HTML エンティティを対応する文字に変換する
    • htmlentities — 適用可能な文字を全て HTML エンティティに変換する
    • htmlspecialchars — 特殊文字を HTML エンティティに変換する
    • htmlspecialchars_decode — 特殊な HTML エンティティを文字に戻す
    • implode — 配列要素を文字列により連結する
    • join — implode のエイリアス
    • lcfirst — 文字列の最初の文字を小文字にする
    • levenshtein — 二つの文字列のレーベンシュタイン距離を計算する
    • localeconv — 数値に関するフォーマット情報を得る
    • ltrim — 文字列の最初から空白 (もしくはその他の文字) を取り除く
    • md5 — 文字列のmd5ハッシュ値を計算する
    • md5_file — 指定したファイルのMD5ハッシュ値を計算する
    • metaphone — 文字列の metaphone キーを計算する
    • money_format — 数値を金額文字列にフォーマットする
    • nl_langinfo — 言語およびロケール情報を検索する
    • nl2br — 改行文字の前に HTML の改行タグを挿入する
    • number_format — 数字を千の位毎にグループ化してフォーマットする
    • ord — 文字列の先頭バイトを、0 から 255 までの値に変換する
    • parse_str — 文字列を処理し、変数に代入する
    • print — 文字列を出力する
    • printf — フォーマット済みの文字列を出力する
    • quoted_printable_decode — quoted-printable 文字列を 8 ビット文字列に変換する
    • quoted_printable_encode — 8 ビット文字列を quoted-printable 文字列に変換する
    • quotemeta — メタ文字をクォートする
    • rtrim — 文字列の最後から空白 (もしくはその他の文字) を取り除く
    • setlocale — ロケール情報を設定する
    • sha1 — 文字列の sha1 ハッシュを計算する
    • sha1_file — ファイルの sha1 ハッシュを計算する
    • similar_text — 二つの文字列の間の類似性を計算する
    • soundex — 文字列の soundex キーを計算する
    • sprintf — フォーマットされた文字列を返す
    • sscanf — フォーマット文字列に基づき入力を処理する
    • str_contains — 指定された部分文字列が、文字列に含まれるかを調べる
    • str_decrement — 英数字からなる文字列をデクリメントする
    • str_ends_with — 文字列が、指定された文字列で終わるかを調べる。
    • str_getcsv — CSV 文字列をパースして配列に格納する
    • str_increment — 英数字からなる文字列をインクリメントする
    • str_ireplace — 大文字小文字を区別しない str_replace
    • str_pad — 文字列を固定長の他の文字列で埋める
    • str_repeat — 文字列を反復する
    • str_replace — 検索文字列に一致したすべての文字列を置換する
    • str_rot13 — 文字列に rot13 変換を行う
    • str_shuffle — 文字列をランダムにシャッフルする
    • str_split — 文字列を配列に変換する
    • str_starts_with — 文字列が指定された部分文字列で始まるかを調べる
    • str_word_count — 文字列に使用されている単語についての情報を返す
    • strcasecmp — 大文字小文字を区別しないバイナリセーフな文字列比較を行う
    • strchr — strstr のエイリアス
    • strcmp — バイナリセーフな文字列比較
    • strcoll — ロケールに基づく文字列比較
    • strcspn — マスクにマッチしない最初のセグメントの長さを返す
    • strip_tags — 文字列から HTML および PHP タグを取り除く
    • stripcslashes — addcslashes でクォートされた文字列をアンクォートする
    • stripos — 大文字小文字を区別せずに文字列が最初に現れる位置を探す
    • stripslashes — クォートされた文字列のクォート部分を取り除く
    • stristr — 大文字小文字を区別しない strstr
    • strlen — 文字列の長さを得る
    • strnatcasecmp — "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う
    • strnatcmp — "自然順"アルゴリズムにより文字列比較を行う
    • strncasecmp — バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
    • strncmp — 最初の n 文字についてバイナリセーフな文字列比較を行う
    • strpbrk — 文字列の中から任意の文字を探す
    • strpos — 文字列内の部分文字列が最初に現れる場所を見つける
    • strrchr — 文字列中に文字が最後に現れる場所を取得する
    • strrev — 文字列を逆順にする
    • strripos — 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
    • strrpos — 文字列中に、ある部分文字列が最後に現れる場所を探す
    • strspn — 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す
    • strstr — 文字列が最初に現れる位置を見つける
    • strtok — 文字列をトークンに分割する
    • strtolower — 文字列を小文字にする
    • strtoupper — 文字列を大文字にする
    • strtr — 文字の変換あるいは部分文字列の置換を行う
    • substr — 文字列の一部分を返す
    • substr_compare — 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
    • substr_count — 副文字列の出現回数を数える
    • substr_replace — 文字列の一部を置換する
    • trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く
    • ucfirst — 文字列の最初の文字を大文字にする
    • ucwords — 文字列の各単語の最初の文字を大文字にする
    • utf8_decode — UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する
    • utf8_encode — ISO-8859-1 文字列を UTF-8 に変換する
    • vfprintf — フォーマットされた文字列をストリームに書き込む
    • vprintf — フォーマットされた文字列を出力する
    • vsprintf — フォーマットされた文字列を返す
    • wordwrap — 指定した文字数で文字列を分割する
  • 変更履歴


はじめに

このセクションにある関数はすべて、 文字列をいろいろな方法で操作します。正規表現 や URL 処理の節にも関連する記述があります。

文字列の動作に関する情報、特にシングルクオート、ダブルクオート、 エスケープシーケンスについては、マニュアルの 型 の節にある 文字列 エントリを参照ください。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • 文字列
  • インストール/設定

インストール/設定

目次

  • インストール手順


インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

PHP 8.1.0 以降では、configure オプション --with-external-libcrypt を指定することで、システムの crypt ライブラリを使って crypt() をビルドできるようになっています。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

CRYPT_SALT_LENGTH (int)
CRYPT_STD_DES (int)
標準のDESベースのハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_EXT_DES (int)
拡張DESベースのハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_MD5 (int)
MD5ハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_BLOWFISH (int)
Blowfishハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_SHA256 (int)
SHA-256ハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
CRYPT_SHA512 (int)
SHA-512ハッシュが crypt() 関数でサポートされているかどうかを示します。 値は常に 1 です。
HTML_SPECIALCHARS (int)
HTML_ENTITIES (int)
ENT_COMPAT (int)
ENT_QUOTES (int)
ENT_NOQUOTES (int)
ENT_IGNORE (int)
ENT_SUBSTITUTE (int)
ENT_DISALLOWED (int)
ENT_HTML401 (int)
ENT_XML1 (int)
ENT_XHTML (int)
ENT_HTML5 (int)
CHAR_MAX (int)
LC_CTYPE (int)
ロケール設定の影響を受ける文字の分類と変換
LC_NUMERIC (int)
ロケール設定の影響を受ける数値のセパレータ
LC_TIME (int)
ロケール設定の影響を受ける日付と時刻のフォーマット
LC_COLLATE (int)
ロケール設定の影響を受ける文字列比較
LC_MONETARY (int)
ロケール設定の影響を受けるお金のフォーマット
LC_ALL (int)
その他の LC_* 定数が影響を受ける、全ての機能
LC_MESSAGES (int)
ロケール設定の影響を受ける、システムレスポンス。 PHP が libintl と一緒にコンパイルされている場合に利用可能です。
STR_PAD_LEFT (int)
STR_PAD_RIGHT (int)
STR_PAD_BOTH (int)
nl_langinfo() LC_TIME カテゴリの定数
定数 | 説明
ABDAY_1 (int) | 週の最初の曜日の略式表記
ABDAY_2 (int) | 週の2番目の曜日の略式表記
ABDAY_3 (int) | 週の3番目の曜日の略式表記
ABDAY_4 (int) | 週の4番目の曜日の略式表記
ABDAY_5 (int) | 週の5番目の曜日の略式表記
ABDAY_6 (int) | 週の6番目の曜日の略式表記
ABDAY_7 (int) | 週の7番目の曜日の略式表記
DAY_1 (int) | 週の最初の日の名前
DAY_2 (int) | 週の2番目の日の名前
DAY_3 (int) | 週の3番目の日の名前
DAY_4 (int) | 週の4番目の日の名前
DAY_5 (int) | 週の5番目の日の名前
DAY_6 (int) | 週の6番目の日の名前
DAY_7 (int) | 週の7番目の日の名前
ABMON_1 (int) | 年の最初の月の略式表記
ABMON_2 (int) | 年の2番目の月の略式表記
ABMON_3 (int) | 年の3番目の月の略式表記
ABMON_4 (int) | 年の4番目の月の略式表記
ABMON_5 (int) | 年の5番目の月の略式表記
ABMON_6 (int) | 年の6番目の月の略式表記
ABMON_7 (int) | 年の7番目の月の略式表記
ABMON_8 (int) | 年の8番目の月の略式表記
ABMON_9 (int) | 年の9番目の月の略式表記
ABMON_10 (int) | 年の10番目の月の略式表記
ABMON_11 (int) | 年の11番目の月の略式表記
ABMON_12 (int) | 年の12番目の月の略式表記
MON_1 (int) | 年の最初の月の名前
MON_2 (int) | 年の2番目の月の名前
MON_3 (int) | 年の3番目の月の名前
MON_4 (int) | 年の4番目の月の名前
MON_5 (int) | 年の5番目の月の名前
MON_6 (int) | 年の6番目の月の名前
MON_7 (int) | 年の7番目の月の名前
MON_8 (int) | 年の8番目の月の名前
MON_9 (int) | 年の9番目の月の名前
MON_10 (int) | 年の10番目の月の名前
MON_11 (int) | 年の11番目の月の名前
MON_12 (int) | 年の12番目の月の名前
AM_STR (int) | 午前を表す文字列
PM_STR (int) | 午後を表す文字列
D_T_FMT (int) | strftime() で日時を表すためのフォーマット文字列として使用することが可能な文字列
D_FMT (int) | strftime() で日付を表すためのフォーマット文字列として使用することが可能な文字列
T_FMT (int) | strftime() で時刻を表すためのフォーマット文字列として使用することが可能な文字列
T_FMT_AMPM (int) | strftime() でAM/PM付き 12 時間表記を表すためのフォーマット文字列として使用することが可能な文字列
ERA (int) | ロケール固有の元号付きフォーマット
ERA_YEAR (int) | ロケール固有の元号付きフォーマットでの年
ERA_D_T_FMT (int) | ロケール固有の元号付きフォーマットでの日時 (strftime() で使用可能な文字列)
ERA_D_FMT (int) | ロケール固有の元号付きフォーマットでの日付 (strftime() で使用可能な文字列)
ERA_T_FMT (int) | ロケール固有の元号付きフォーマットでの時刻 (strftime() で使用可能な文字列)
ALT_DIGITS (int) | 数値の代替記号
nl_langinfo() LC_MONETARY カテゴリの定数
定数 | 説明
INT_CURR_SYMBOL (int) | 国際通貨記号
CURRENCY_SYMBOL (int) | 地域通貨記号
CRNCYSTR (int) | CURRENCY_SYMBOL と同じ値
MON_DECIMAL_POINT (int) | 小数点文字
MON_THOUSANDS_SEP (int) | 1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字
MON_GROUPING (int) | 'grouping' と同じ
POSITIVE_SIGN (int) | 正値の表示に使用される記号
NEGATIVE_SIGN (int) | 負値の表示に使用される記号
INT_FRAC_DIGITS (int) | 国際的な方法で表現する際の小数点以下の桁数
FRAC_DIGITS (int) | 地域的な方法で表現する際の小数点以下の桁数
P_CS_PRECEDES (int) | CURRENCY_SYMBOL の前に正値がある場合 1 を返す
P_SEP_BY_SPACE (int) | CURRENCY_SYMBOL と正値がスペースで区切られる場合 1 を返す
N_CS_PRECEDES (int) | CURRENCY_SYMBOL の前に負値がある場合 1 を返す
N_SEP_BY_SPACE (int) | CURRENCY_SYMBOL と負値がスペースで区切られる場合 1 を返す
P_SIGN_POSN (int)

  • 量および CURRENCY_SYMBOL を括弧で括る場合、0 を返す
  • 量および CURRENCY_SYMBOL の前に符号文字列を置く場合、1 を返す
  • 量および CURRENCY_SYMBOL の後に符号文字列を置く場合、2 を返す
  • CURRENCY_SYMBOL の直前に符号文字列を置く場合、3 を返す
  • CURRENCY_SYMBOL の直後に符号文字列を置く場合、4 を返す

N_SIGN_POSN (int)
nl_langinfo() LC_NUMERIC カテゴリの定数
定数 | 説明
DECIMAL_POINT (int) | 小数点文字
RADIXCHAR (int) | DECIMAL_POINT と同じ値
THOUSANDS_SEP (int) | 1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字
THOUSEP (int) | THOUSANDS_SEP と同じ値
GROUPING (int) |
nl_langinfo() LC_MESSAGES カテゴリの定数
定数 | 説明
YESEXPR (int) | "はい" の入力にマッチさせるための正規表現
NOEXPR (int) | "いいえ" の入力にマッチさせるための正規表現
YESSTR (int) | "はい" のための出力文字列
NOSTR (int) | "いいえ" のための出力文字列
nl_langinfo() LC_CTYPE カテゴリの定数
定数 | 説明
CODESET (int) | 文字エンコーディング名の文字列を返す


String 関数

参考

より強力な文字列処理および処理関数については、 Perl 互換正規表現関数 を参照ください。 マルチバイト文字のエンコーディングを扱うときは、 マルチバイト文字列関数. を参照ください。

目次

  • addcslashes — C 言語と同様にスラッシュで文字列をクォートする
  • addslashes — 文字列をスラッシュでクォートする
  • bin2hex — バイナリのデータを16進表現に変換する
  • chop — rtrim のエイリアス
  • chr — 数値から、1バイトの文字列を生成する
  • chunk_split — 文字列をより小さな部分に分割する
  • convert_cyr_string — キリル文字セットを他のものに変換する
  • convert_uudecode — uuencode された文字列をデコードする
  • convert_uuencode — 文字列を uuencode する
  • count_chars — 文字列で使用されている文字に関する情報を返す
  • crc32 — 文字列の crc32 多項式計算を行う
  • crypt — 文字列の一方向のハッシュ化を行う
  • echo — 1 つ以上の文字列を出力する
  • explode — 文字列を文字列により分割する
  • fprintf — フォーマットされた文字列をストリームに書き込む
  • get_html_translation_table — htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • hebrev — 論理表記のヘブライ語を物理表記に変換する
  • hebrevc — 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する
  • hex2bin — 16進エンコードされたバイナリ文字列をデコードする
  • html_entity_decode — HTML エンティティを対応する文字に変換する
  • htmlentities — 適用可能な文字を全て HTML エンティティに変換する
  • htmlspecialchars — 特殊文字を HTML エンティティに変換する
  • htmlspecialchars_decode — 特殊な HTML エンティティを文字に戻す
  • implode — 配列要素を文字列により連結する
  • join — implode のエイリアス
  • lcfirst — 文字列の最初の文字を小文字にする
  • levenshtein — 二つの文字列のレーベンシュタイン距離を計算する
  • localeconv — 数値に関するフォーマット情報を得る
  • ltrim — 文字列の最初から空白 (もしくはその他の文字) を取り除く
  • md5 — 文字列のmd5ハッシュ値を計算する
  • md5_file — 指定したファイルのMD5ハッシュ値を計算する
  • metaphone — 文字列の metaphone キーを計算する
  • money_format — 数値を金額文字列にフォーマットする
  • nl_langinfo — 言語およびロケール情報を検索する
  • nl2br — 改行文字の前に HTML の改行タグを挿入する
  • number_format — 数字を千の位毎にグループ化してフォーマットする
  • ord — 文字列の先頭バイトを、0 から 255 までの値に変換する
  • parse_str — 文字列を処理し、変数に代入する
  • print — 文字列を出力する
  • printf — フォーマット済みの文字列を出力する
  • quoted_printable_decode — quoted-printable 文字列を 8 ビット文字列に変換する
  • quoted_printable_encode — 8 ビット文字列を quoted-printable 文字列に変換する
  • quotemeta — メタ文字をクォートする
  • rtrim — 文字列の最後から空白 (もしくはその他の文字) を取り除く
  • setlocale — ロケール情報を設定する
  • sha1 — 文字列の sha1 ハッシュを計算する
  • sha1_file — ファイルの sha1 ハッシュを計算する
  • similar_text — 二つの文字列の間の類似性を計算する
  • soundex — 文字列の soundex キーを計算する
  • sprintf — フォーマットされた文字列を返す
  • sscanf — フォーマット文字列に基づき入力を処理する
  • str_contains — 指定された部分文字列が、文字列に含まれるかを調べる
  • str_decrement — 英数字からなる文字列をデクリメントする
  • str_ends_with — 文字列が、指定された文字列で終わるかを調べる。
  • str_getcsv — CSV 文字列をパースして配列に格納する
  • str_increment — 英数字からなる文字列をインクリメントする
  • str_ireplace — 大文字小文字を区別しない str_replace
  • str_pad — 文字列を固定長の他の文字列で埋める
  • str_repeat — 文字列を反復する
  • str_replace — 検索文字列に一致したすべての文字列を置換する
  • str_rot13 — 文字列に rot13 変換を行う
  • str_shuffle — 文字列をランダムにシャッフルする
  • str_split — 文字列を配列に変換する
  • str_starts_with — 文字列が指定された部分文字列で始まるかを調べる
  • str_word_count — 文字列に使用されている単語についての情報を返す
  • strcasecmp — 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • strchr — strstr のエイリアス
  • strcmp — バイナリセーフな文字列比較
  • strcoll — ロケールに基づく文字列比較
  • strcspn — マスクにマッチしない最初のセグメントの長さを返す
  • strip_tags — 文字列から HTML および PHP タグを取り除く
  • stripcslashes — addcslashes でクォートされた文字列をアンクォートする
  • stripos — 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • stripslashes — クォートされた文字列のクォート部分を取り除く
  • stristr — 大文字小文字を区別しない strstr
  • strlen — 文字列の長さを得る
  • strnatcasecmp — "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う
  • strnatcmp — "自然順"アルゴリズムにより文字列比較を行う
  • strncasecmp — バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • strncmp — 最初の n 文字についてバイナリセーフな文字列比較を行う
  • strpbrk — 文字列の中から任意の文字を探す
  • strpos — 文字列内の部分文字列が最初に現れる場所を見つける
  • strrchr — 文字列中に文字が最後に現れる場所を取得する
  • strrev — 文字列を逆順にする
  • strripos — 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strrpos — 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strspn — 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す
  • strstr — 文字列が最初に現れる位置を見つける
  • strtok — 文字列をトークンに分割する
  • strtolower — 文字列を小文字にする
  • strtoupper — 文字列を大文字にする
  • strtr — 文字の変換あるいは部分文字列の置換を行う
  • substr — 文字列の一部分を返す
  • substr_compare — 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
  • substr_count — 副文字列の出現回数を数える
  • substr_replace — 文字列の一部を置換する
  • trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • ucfirst — 文字列の最初の文字を大文字にする
  • ucwords — 文字列の各単語の最初の文字を大文字にする
  • utf8_decode — UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する
  • utf8_encode — ISO-8859-1 文字列を UTF-8 に変換する
  • vfprintf — フォーマットされた文字列をストリームに書き込む
  • vprintf — フォーマットされた文字列を出力する
  • vsprintf — フォーマットされた文字列を返す
  • wordwrap — 指定した文字数で文字列を分割する


C 言語と同様にスラッシュで文字列をクォートする

  • ≪ String 関数
  • addslashes ≫
  • PHP Manual
  • String 関数
  • C 言語と同様にスラッシュで文字列をクォートする

addcslashes

(PHP 4, PHP 5, PHP 7, PHP 8)

addcslashes — C 言語と同様にスラッシュで文字列をクォートする

説明

addcslashes(string $string, string $characters): string

characters パラメータに羅列された文字の前にバックスラッシュを付けた文字列を返します。

パラメータ

string

エスケープしたい文字列。

characters

エスケープの対象となる文字を並べたもの。 characters が \n, \r 等の文字を含んでいる場合、 C言語と同様の手法によりエスケープされます。 アスキーコードが32未満または126より大きい文字は、8進表現に変換されます。

characters 引数の文字の列びを定義する際には、 範囲の最初と最後で指定する文字集合に含まれる文字の種類を把握するようにしてください。

<?php
echo addcslashes('foo[ ]', 'A..z');
// 出力: \f\o\o\[ \]
// 全ての大文字と小文字はエスケープされます。
// ... しかし、[\]^_` もエスケープされてしまいます。
?>
また、ある範囲を指定する最初の文字がその範囲の2番目の文字よりも大きな ASCII 値を有している場合、範囲は定義されません。 最初と最後の文字とピリオド文字のみがエスケープされます。 ある文字の ASCII 値を見つけるには、 ord() 関数を使用してください。
<?php
echo addcslashes("zoo['.']", 'z..A');
// 出力: \zoo['\.']
?>

0, a, b, f, n, r, t そして v といった文字をエスケープするときには注意しましょう。 変換結果はそれぞれ \0, \a, \b, \f, \n, \r, \t そして \v となりますが、 これらはすべて、C 言語では定義済みのエスケープシーケンスです。 その多くは C 言語に由来する他の言語でもエスケープシーケンスとして定義されており、 PHP も例外ではありません。つまり、characters にこれらの文字を定義した状態で addcslashes() を使って他の言語のコードを生成したときに、 期待通りの結果が得られない可能性があるということです。

戻り値

エスケープされた文字列を返します。

例

"\0..\37" のように characters に範囲を指定可能です。この場合、アスキーコードが 0 から 31 の範囲の文字は全てエスケープされます。

例1 addcslashes() の例

<?php
$escaped = addcslashes($not_escaped, "\0..\37!@\177..\377");
?>

参考

  • stripcslashes() - addcslashes でクォートされた文字列をアンクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • addslashes() - 文字列をスラッシュでクォートする
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • quotemeta() - メタ文字をクォートする


文字列をスラッシュでクォートする

  • ≪ addcslashes
  • bin2hex ≫
  • PHP Manual
  • String 関数
  • 文字列をスラッシュでクォートする

addslashes

(PHP 4, PHP 5, PHP 7, PHP 8)

addslashes — 文字列をスラッシュでクォートする

説明

addslashes(string $string): string

エスケープすべき文字の前にバックスラッシュを付けて返します。 エスケープすべき文字とは、以下のとおりです。

  • シングルクォート (')
  • ダブルクォート (")
  • バックスラッシュ (\)
  • NUL (null バイト)

addslashes() 関数 を使うケースとして、 PHPが評価する文字列データに含まれる、既に述べた文字をエスケープする場合があります。

<?php
$str = "O'Reilly?";
eval("echo '" . addslashes($str) . "';");
?>

addslashes() 関数は、 SQLインジェクション を防止しようとして誤った使い方がされることがあります。 この関数を使うのではなく、データベース特有のエスケープ関数 および/もしくは プリペアドステートメントを使うようにしてください。

パラメータ

string

エスケープしたい文字列。

戻り値

エスケープされた文字列を返します。

例

例1 addslashes() の例

<?php
$str = "Is your name O'Reilly?";

// 出力: Is your name O\'Reilly?
echo addslashes($str);
?>

参考

  • stripcslashes() - addcslashes でクォートされた文字列をアンクォートする
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • addcslashes() - C 言語と同様にスラッシュで文字列をクォートする
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • quotemeta() - メタ文字をクォートする
  • get_magic_quotes_gpc() - magic_quotes_gpc の現在の設定を得る


バイナリのデータを16進表現に変換する

  • ≪ addslashes
  • chop ≫
  • PHP Manual
  • String 関数
  • バイナリのデータを16進表現に変換する

bin2hex

(PHP 4, PHP 5, PHP 7, PHP 8)

bin2hex — バイナリのデータを16進表現に変換する

説明

bin2hex(string $string): string

string を16進表現に変換したASCII文字列を返します。変換は、上位ニブルからバイト毎に行われます。

パラメータ

string

文字列。

戻り値

指定した文字列を16進表現に変換したものを返します。

例

例1 bin2hex() の例

<?php

$hex = bin2hex('Hello world!');

var_dump($hex);
var_dump(hex2bin($hex));
?>

上の例の出力は以下となります。

string(24) "48656c6c6f20776f726c6421"
string(12) "Hello world!"

参考

  • hex2bin() - 16進エンコードされたバイナリ文字列をデコードする
  • pack() - データをバイナリ文字列にパックする


rtrim のエイリアス

  • ≪ bin2hex
  • chr ≫
  • PHP Manual
  • String 関数
  • rtrim のエイリアス

chop

(PHP 4, PHP 5, PHP 7, PHP 8)

chop — rtrim() のエイリアス

説明

この関数は次の関数のエイリアスです。 rtrim().

注意

注意:

chop() は、文字列の末尾の文字を削除する Perl の chop()関数とは異なります。


数値から、1バイトの文字列を生成する

  • ≪ chop
  • chunk_split ≫
  • PHP Manual
  • String 関数
  • 数値から、1バイトの文字列を生成する

chr

(PHP 4, PHP 5, PHP 7, PHP 8)

chr — 数値から、1バイトの文字列を生成する

説明

chr(int $codepoint): string

codepoint を符号なし数値と解釈することによって指定された文字を含む、 1文字からなる文字列を返します。

この関数は、ASCII, ISO-8859, Windows 1252 のような シングルバイトエンコーディング においては、文字セットのマッピングテーブルにある望みの文字の位置を 渡すことで、一文字の文字列を作り出すのに使えます。 しかし、この関数は string のエンコーディングについて知りませんし、 特に UTF-8 や UTF-16 のようなマルチバイトエンコーディングについては、 この関数に Unicode のコードポイントは渡せないことに注意してください。

この関数はord()の逆の動作をします。

パラメータ

codepoint

0 から 255 までの数値

妥当な範囲 (0..255) 外の値を渡した場合は、255 とのビット AND を行います。 この処理は、以下のコードと同様のアルゴリズムです。

while ($bytevalue < 0) {
$bytevalue += 256;
}
$bytevalue %= 256;

戻り値

指定されたバイトを含む、一文字からなる文字列を返します。

変更履歴

バージョン | 説明
7.4.0 | codepoint に対して、 サポートされていない入力が与えられた場合、 黙って0 にキャストする動作をしなくなりました。

例

例1 chr() の例

<?php
// Assumes the string will be used as ASCII or an ASCII-compatible encoding

$str = "この文字列はエスケープで終了します: ";
$str .= chr(27); /* $str の最後にエスケープ文字を付加する */

/* こちらの方がより便利なことが多い */

$str = sprintf("この文字列はエスケープで終了します: %c", 27);
?>

例2 オーバーフローの挙動

<?php
echo chr(-159), chr(833), PHP_EOL;
?>

上の例の出力は以下となります。

aA

例3 個別のバイトから、UTF-8 文字列を組み立てる

<?php
$str = chr(240) . chr(159) . chr(144) . chr(152);
echo $str;
?>

上の例の出力は以下となります。

??

参考

  • sprintf() - フォーマットされた文字列を返す のフォーマット文字列 %c
  • ord() - 文字列の先頭バイトを、0 から 255 までの値に変換する
  • » ASCII テーブル
  • mb_chr() - Unicode のコードポイントに対応する文字を返す
  • IntlChar::chr() - コードポイント値に対応する、Unicode 文字を返す


文字列をより小さな部分に分割する

  • ≪ chr
  • convert_cyr_string ≫
  • PHP Manual
  • String 関数
  • 文字列をより小さな部分に分割する

chunk_split

(PHP 4, PHP 5, PHP 7, PHP 8)

chunk_split — 文字列をより小さな部分に分割する

説明

chunk_split(string $string, int $length = 76, string $separator = "\r\n"): string

文字列をより小さな部分に分割する際に使用され、 base64_encode() の出力を RFC 2045の規約に基づいた出力に変換するといった用途に適しています。 この関数は、length 文字毎に文字列 separator を挿入します。

パラメータ

string

分割したい文字列。

length

各部分の長さ。

separator

行末の区切り。

戻り値

分割した文字列を返します。

例

例1 chunk_split() の例

<?php
// RFC 2045 に基づき $data をフォーマットします
$new_string = chunk_split(base64_encode($data));
?>

参考

  • str_split() - 文字列を配列に変換する
  • explode() - 文字列を文字列により分割する
  • wordwrap() - 指定した文字数で文字列を分割する
  • » RFC 2045


キリル文字セットを他のものに変換する

  • ≪ chunk_split
  • convert_uudecode ≫
  • PHP Manual
  • String 関数
  • キリル文字セットを他のものに変換する

convert_cyr_string

(PHP 4, PHP 5, PHP 7)

convert_cyr_string — キリル文字セットを他のものに変換する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

convert_cyr_string(string $str, string $from, string $to): string

キリル文字セットを、別の文字セットに変換します。

パラメータ

str

変換したい文字列。

from

変換元のキリル文字セットを一文字で表したもの。

to

変換先のキリル文字セットを一文字で表したもの。

サポートされている文字セットは次のとおりです。

  • k - koi8-r
  • w - windows-1251
  • i - iso8859-5
  • a - x-cp866
  • d - x-cp866
  • m - x-mac-cyrillic

戻り値

変換した文字列を返します。

注意

注意: この関数はバイナリデータに対応しています。

参考

  • mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


uuencode された文字列をデコードする

  • ≪ convert_cyr_string
  • convert_uuencode ≫
  • PHP Manual
  • String 関数
  • uuencode された文字列をデコードする

convert_uudecode

(PHP 5, PHP 7, PHP 8)

convert_uudecode — uuencode された文字列をデコードする

説明

convert_uudecode(string $string): string|false

convert_uudecode() は、uuencode された文字列をデコードします。

注意: convert_uudecode() は、 uuencode された ファイル に含まれる begin, end を両方受け入れません。

パラメータ

string

uuencode されたデータ。

戻り値

デコードしたデータを文字列で返します。失敗した場合に false を返します。

例

例1 convert_uudecode() の例

<?php
echo convert_uudecode("+22!L;W9E(%!(4\"$`\n`");
?>

上の例の出力は以下となります。

I love PHP!

参考

  • convert_uuencode() - 文字列を uuencode する


文字列を uuencode する

  • ≪ convert_uudecode
  • count_chars ≫
  • PHP Manual
  • String 関数
  • 文字列を uuencode する

convert_uuencode

(PHP 5, PHP 7, PHP 8)

convert_uuencode — 文字列を uuencode する

説明

convert_uuencode(string $string): string

convert_uuencode() は、uuencode アルゴリズムを使用して文字列をエンコードします。

uuencode はすべての文字(バイナリを含む)を表示可能な文字に変換し、 ネットワーク上での転送を可能にします。uuencode されたデータは、 元のデータより約 35% 大きくなります。

注意: convert_uuencode() 関数は、 uuencode された ファイル に含まれる begin や end を両方生成しません。

パラメータ

string

エンコードしたいデータ。

戻り値

uuencode されたデータを返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 空文字列を変換しようとすると、特別な理由がないのに false を返していました。

例

例1 convert_uuencode() の例

<?php
$some_string = "test\ntext text\r\n";

echo convert_uuencode($some_string);
?>

上の例の出力は以下となります。

0=&5S=`IT97AT('1E>'0-"@``
`

参考

  • convert_uudecode() - uuencode された文字列をデコードする
  • base64_encode() - MIME base64 方式でデータをエンコードする


文字列で使用されている文字に関する情報を返す

  • ≪ convert_uuencode
  • crc32 ≫
  • PHP Manual
  • String 関数
  • 文字列で使用されている文字に関する情報を返す

count_chars

(PHP 4, PHP 5, PHP 7, PHP 8)

count_chars — 文字列で使用されている文字に関する情報を返す

説明

count_chars(string $string, int $mode = 0): array|string

string において各バイト値 (0..255) が存在する数をかぞえ、様々な手法で返します。

パラメータ

string

調べたい文字列。

mode

戻り値を参照ください。

戻り値

mode の値により、 count_chars() は以下の値のどれかを返します。

  • 0 - 各バイト値をキー、各バイトの出現回数を値とする配列。
  • 1 - 0と同じですが、各バイト値の出現回数がゼロより大きいものの一覧となります。
  • 2 - 0と同じですが、各バイト値の出現回数がゼロであるものの一覧となります。
  • 3 - すべての一意な文字を含む文字列を返します。
  • 4 - 使用されていない全ての文字を含む文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、この関数は失敗時に false を返していました。

例

例1 count_chars() の例

<?php
$data = "Two Ts and one F.";

foreach (count_chars($data, 1) as $i => $val) {
echo "There were $val instance(s) of \"" , chr($i) , "\" in the string.\n";
}
?>

上の例の出力は以下となります。

There were 4 instance(s) of " " in the string.
There were 1 instance(s) of "." in the string.
There were 1 instance(s) of "F" in the string.
There were 2 instance(s) of "T" in the string.
There were 1 instance(s) of "a" in the string.
There were 1 instance(s) of "d" in the string.
There were 1 instance(s) of "e" in the string.
There were 2 instance(s) of "n" in the string.
There were 2 instance(s) of "o" in the string.
There were 1 instance(s) of "s" in the string.
There were 1 instance(s) of "w" in the string.

参考

  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • substr_count() - 副文字列の出現回数を数える


文字列の crc32 多項式計算を行う

  • ≪ count_chars
  • crypt ≫
  • PHP Manual
  • String 関数
  • 文字列の crc32 多項式計算を行う

crc32

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

crc32 — 文字列の crc32 多項式計算を行う

説明

crc32(string $string): int

string の 32 ビット長の CRC (cyclic redundancy checksum) チェックサムを生成します。 これは通常、送信したデータの整合性を検証するために使用します。

警告

PHP の整数型は符号付きで、多くの crc32 チェックサムは 32 ビットシステム上では負の整数になります。 しかし、64 ビット環境では crc32() の結果はすべて正の整数となります。

つまり、符号なしの crc32() チェックサムの文字列表記を 十進形式で取得するには、 sprintf() もしくは printf() の "%u" フォーマッタを使う必要があります。

チェックサムの十六進表記を取得するには、sprintf() あるいは printf() の "%x" フォーマッタを使うか、あるいは変換関数 dechex() を使います。これらはいずれも、 crc32() の結果を符号なし整数に変換することも行います。

64 ビット環境でも、大きな戻り値に対して負の整数を返すことが検討されました。 しかしその場合、負の整数には余計な オフセット 0xFFFFFFFF######## が付くので、十六進変換が壊れてしまいます。 十六進表現は最もよく使われる形式なので、この処理が壊れないようにしました。 32 ビット環境から 64 ビット環境に移したときに ほぼ 50% の確率で十進形式での比較が失敗してしまいますが、 それよりも十六進表記のほうを優先したのです。

今思えば、この関数が整数値を返すようにしたというのがまずい判断でした。 最初から、md5() のように十六進形式の文字列を直接返すようにしておけばよかったのでしょう。

移植性を考慮した選択肢として、より汎用的な hash() を使う方法もあります。 hash("crc32b", $str) は str_pad(dechex(crc32($str)), 8, '0', STR_PAD_LEFT) と同じ文字列を返します。

パラメータ

string

データ。

戻り値

string の crc32 チェックサムを整数値で返します。

例

例1 crc32 チェックサムの表示

この例は printf() 関数を用いた変換後のチェックサムの表示方法を示しています。

<?php
$checksum = crc32("The quick brown fox jumped over the lazy dog.");
printf("%u\n", $checksum);
?>

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • md5() - 文字列のmd5ハッシュ値を計算する
  • sha1() - 文字列の sha1 ハッシュを計算する


文字列の一方向のハッシュ化を行う

  • ≪ crc32
  • echo ≫
  • PHP Manual
  • String 関数
  • 文字列の一方向のハッシュ化を行う

crypt

(PHP 4, PHP 5, PHP 7, PHP 8)

crypt — 文字列の一方向のハッシュ化を行う

警告

この関数は (まだ)バイナリデータ対応ではありません!

説明

crypt(#[\SensitiveParameter] string $string, string $salt): string

crypt() 文字列のハッシュを返します。
Unix 標準の DES ベースのアルゴリズムか、
代替のアルゴリズムを使用します。
password_verify() は
crypt() と互換性があるので、
crypt() が作ったパスワードハッシュは
password_verify() でも使えます。

PHP 8.0.0 より前のバージョンでは、salt パラメータは必須ではありませんでした。ただ、これを省略すると crypt() が作るハッシュが弱いものになってしまっていました。 このパラメータを省略した場合には、E_NOTICE が発生していました。 十分に強い salt を指定して、セキュリティを確保しましょう。

password_hash() は、強力なハッシュを使い、強力なソルトを生成して、それを複数回自動的に適用します。
password_hash() は crypt() のシンプルなラッパーであり、既存のパスワードハッシュと互換性があります。
password_hash() を使うことを推奨します。

ハッシュ方式は、salt 引数によって決まります。 salt を省略した場合は、標準の 2 文字 (DES) の salt を自動生成します。 あるいは、MD5 crypt() が使えれば 12 文字 (MD5) の salt を自動生成します。 PHP の定数 CRYPT_SALT_LENGTH には、 ハッシュで使用できる salt の最大長が格納されています。

標準の DES ベースの場合、crypt() は出力の最初の 2 文字を salt として使用します。また、 string の最初の 8 文字しか使用しません。 つまり、最初の 8 文字が同じである長い文字列は、 同じ salt を使う限り同じ結果となります。

以下のハッシュ形式がサポートされています:

  • CRYPT_STD_DES - 標準の DES ベースのハッシュで、 アルファベット "./0-9A-Za-z" からなる 2 文字の salt を使用するもの。 salt として無効な文字を使うと crypt() は失敗します。
  • CRYPT_EXT_DES - 拡張した DES ベースのハッシュ。 "salt" は 9 文字で、 アンダースコアの後に 4 文字の反復回数と 4 文字の salt が続きます。 これらの4文字それぞれが、24ビットにエンコードされ、 下位の文字から順に並びます。 0 から 63 までの値は ./0-9A-Za-z の範囲内の文字でエンコードされます。 salt に無効な文字を使うと crypt() は失敗します。
  • CRYPT_MD5 - $1$ ではじまる 12 文字の salt を使用する MD5 ハッシュ。
  • CRYPT_BLOWFISH - Blowfish ハッシュ。salt の形式は、 "$2a$" か "$2x$" あるいは "$2y$"、2 桁のコストパラメータ、"$"、そして文字 "./0-9A-Za-z" からなる 22 文字となります。 この範囲外の文字を salt に使うと、crypt() は長さゼロの文字列を返します。 2 桁のコストパラメータは反復回数の 2 を底とする対数で、 これは Blowfish ベースのハッシュアルゴリズムで使います。 この値は 04 から 31 までの範囲でなければならず、 それ以外の値の場合は crypt() は失敗します。 "$2x$" ハッシュは潜在的に弱いハッシュです。 "$2a$" ハッシュはこれと互換性があり、この弱点を軽減します。 新しくハッシュを生成する場合は、"$2y$" を使うべきです。
  • CRYPT_SHA256 - SHA-256 ハッシュに $5$ で始まる 16 文字の salt を組み合わせたもの。salt 文字列が 'rounds=<N>$' で始まる場合は、数値 N がハッシュループの実行回数を表します。 これは Blowfish のコストパラメータのようなものです。 rounds のデフォルトは 5000 で、1000 から 999,999,999 までの値を指定できます。 この範囲外の N を指定すると、近い方の境界値に切り詰められます。
  • CRYPT_SHA512 - SHA-512 ハッシュに $6$ で始まる 16 文字の salt を組み合わせたもの。salt 文字列が 'rounds=<N>$' で始まる場合は、数値 N がハッシュループの実行回数を表します。 これは Blowfish のコストパラメータのようなものです。 rounds のデフォルトは 5000 で、1000 から 999,999,999 までの値を指定できます。 この範囲外の N を指定すると、近い方の境界値に切り詰められます。

パラメータ

string

ハッシュしたい文字列。

警告

CRYPT_BLOWFISH を使うと、 string が最大 72 バイトまでに切り詰められます。

salt

ハッシュのもととなる salt 文字列。省略した場合の挙動は アルゴリズムの実装によって決まるので、予期せぬ結果となることがあり得ます。

戻り値

ハッシュした文字列を返します。 失敗した場合は、salt とは異なることが保証されている 13 文字未満の文字列を返します。

警告

パスワードを検証するときの文字列比較関数は、 タイミング攻撃に対して脆弱ではないものでなければいけません。 これをもちいて、crypt() の出力と既知のハッシュとを比較します。 この比較を行うために、hash_equals() 関数が使えます。

変更履歴

バージョン | 説明
8.0.0 | salt は、オプションではなくなりました。

例

例1 crypt() の例

<?php
$user_input = 'rasmuslerdorf';
$hashed_password = '$6$rounds=1000000$NJy4rIPjpOaU$0ACEYGg/aKCY3v8O8AfyiO7CTfZQ8/W231Qfh2tRLmfdvFD6XfHk12u6hMr9cYIA4hnpjLNSTRtUwYr9km9Ij/';

// PHP 以外のソフトウェアと互換性がある方法で、既存の crypt() ハッシュを検証します
if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
echo "Password verified!";
}
?>

注意

注意: 復号するための関数はありません。 crypt() が使用しているのは単方向アルゴリズムだからです。

参考

  • hash_equals() - タイミング攻撃に対しても安全な文字列比較
  • password_hash() - パスワードハッシュを作る
  • 暗号化関数についての Unix man ページ


1 つ以上の文字列を出力する

  • ≪ crypt
  • explode ≫
  • PHP Manual
  • String 関数
  • 1 つ以上の文字列を出力する

echo

(PHP 4, PHP 5, PHP 7, PHP 8)

echo — 1 つ以上の文字列を出力する

説明

echo(string ...$expressions): void

ひとつ以上の(文字列として評価される)式を出力します。末尾に改行やスペースを付加することはありません。

echo は実際には関数ではなく、言語構造です。 echo キーワードの後に続く引数は、 コンマで区切られた(文字列として評価される)式のリストであり、括弧で括る必要はありません。 他の言語構造と異なり echo には戻り値がありません。そのため、 式のコンテクストでは使うことができません。

echo には、開始タグの直後に等号を付ける短縮構文もあります。 この短縮構文は、設定オプションshort_open_tag が無効な場合でも使えます。

I have <?=$foo?> foo.

print との主な違いは、 echo がリスト形式の引数を受け付け、戻り値を持たないことです。

パラメータ

expressions

出力したいひとつ以上の文字列として評価される式。 コンマで区切ります。 文字列として評価されない値を渡した場合、文字列に強制的に変換されます。 これは、strict_types ディレクティブ が有効になっていても同じです。

戻り値

値を返しません。

例

例1 echo の例

<?php
echo "echo does not require parentheses.";

// 文字列は、複数の引数として個別に渡すこともできますし、
// 連結し、ひとつの引数として渡すこともできます。
echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', "\n";
echo 'This ' . 'string ' . 'was ' . 'made ' . 'with concatenation.' . "\n";

// 改行やスペースが付加されることはありません; 以下は、"helloworld" を一行で出力します。
echo "hello";
echo "world";

// 上と同じです。
echo "hello", "world";

echo "This string spans
multiple lines. The newlines will be
output as well";

echo "This string spans\nmultiple lines. The newlines will be\noutput as well.";

// 引数は文字列を生成するあらゆる式を指定することができます。
$foo = "example";
echo "foo is $foo"; // foo is example

$fruits = ["lemon", "orange", "banana"];
echo implode(" and ", $fruits); // lemon and orange and banana

// 文字列でない値は、文字列に強制されます。たとえ declare(strict_types=1) が使われていても同じです。
echo 6 * 7; // 42

// echo は式として振る舞わないので、以下のコードは正しくありません。
($some_var) ? echo 'true' : echo 'false';

// しかし、以下の例は動作します:
($some_var) ? print 'true' : print 'false'; // print も言語構造ですが、
// これは正しい式であり、1を返します。
// よって、式のコンテクストで使うことが出来ます。

echo $some_var ? 'true': 'false'; // 式を最初に評価し、echo に渡します。
?>

注意

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

注意: 括弧を使う

echo に対して引数をひとつだけ括弧で囲んで渡しても文法エラーにはなりませんが、 通常の関数コールのような文法に見えてしまいます。 しかし、これは誤解を招く恐れがあります。 なぜなら、括弧は実際には出力を構成する式の一部であり、 echo の文法の一部ではないからです。

<?php
echo "hello";
// "hello" を出力します。

echo("hello");
// 同じく"hello" を出力します。なぜなら ("hello") は正しい式だからです。

echo(1 + 2) * 3;
// "9" を出力します; 括弧によって 1+2 が先に評価され、3*3がその次に評価されます。
// echo 文は、式の評価結果全体をひとつの引数とみなします。

echo "hello", " world";
// "hello world" を出力します。

echo("hello"), (" world");
// "hello world" を出力します; 括弧は個々の式の一部です。

echo("hello", " world");
// Parse Error をスローします。なぜなら、 ("hello", " world") は正しい式ではないからです。
?>

ヒント

複数の引数をecho に渡すことで、 PHP におけるピリオド演算子の優先順位が高いことによる複雑な挙動を避けることができます。 たとえば、ピリオド演算子は三項演算子より演算子が高くなっています。さらにPHP 8.0.0 より前のバージョンでは、加算および減算演算子と優先順位が同じでした:

<?php
// 以下の例では、'Hello ' . isset($name) という式が先に評価されます。
// そして、常にこれは true と評価されるので、echo への引数は常に $name になります。
echo 'Hello ' . isset($name) ? $name : 'John Doe' . '!';

// 上の例を意図した振る舞いにしようとするなら、以下のように追加の括弧が必要です。
echo 'Hello ' . (isset($name) ? $name : 'John Doe') . '!';

// PHP 8.0.0 より前のバージョンでは、以下は "Sum: 3" ではなく、"2" を出力していました。
echo 'Sum: ' . 1 + 2;

// 繰り返しますが、括弧を追加することで、意図通りの評価順序を保証できます。
echo 'Sum: ' . (1 + 2);

複数の引数を渡した場合、 優先順位を強制するための括弧は不要です。 なぜなら、それぞれの文字列表現は別のものだからです:

<?php
echo "Hello ", isset($name) ? $name : "John Doe", "!";

echo "Sum: ", 1 + 2;

参考

  • print - 文字列を出力する
  • printf() - フォーマット済みの文字列を出力する
  • flush() - システム出力バッファをフラッシュする
  • 文字列リテラルを指定する方法


文字列を文字列により分割する

  • ≪ echo
  • fprintf ≫
  • PHP Manual
  • String 関数
  • 文字列を文字列により分割する

explode

(PHP 4, PHP 5, PHP 7, PHP 8)

explode — 文字列を文字列により分割する

説明

explode(string $separator, string $string, int $limit = PHP_INT_MAX): array

文字列の配列を返します。この配列の各要素は、 string を文字列 separator で区切った部分文字列となります。

パラメータ

separator

区切り文字列。

string

入力文字列。

limit

limit に正の値が指定された場合、返される配列には 最大 limit の要素が含まれ、その最後の要素には string の残りの部分が全て含まれます。

もし limit パラメータが負の場合、 最後の -limit 個の要素を除く全ての構成要素が返されます。

limit パラメータがゼロの場合は、1 を指定したものとみなされます。

注意:

PHP 8.0 より前のバージョンでは、implode() はいずれのパラメータ順も受け入れることができていましたが、 explode() はそのようなことはサポートしていません。 つまり、string 引数の前に必ず separator 引数がくることを確認しなければいけません。

戻り値

string の内容を separator で分割した文字列の配列を返します。

空の文字列 ("") が separator として使用された場合、 explode() は ValueError をスローします。 separator に引数 string に含まれていない値が含まれている場合は、 limit が負の値なら空の配列、そうでなければ 引数 string を含む配列を返します。 separator の値が string の最初か最後に現れた場合、その位置に応じて、 返される配列の最初か最後に空の配列が追加されます。

変更履歴

バージョン | 説明
8.0.0 | 引数 separator に空文字列 ("") を渡した場合、 ValueError をスローするようになりました。 それより前のバージョンでは、 explode() は false を返していました。

例

例1 explode() の例

<?php
// 例 1
$pizza = "piece1 piece2 piece3 piece4 piece5 piece6";
$pieces = explode(" ", $pizza);
echo $pieces[0]; // piece1
echo $pieces[1]; // piece2

// 例 2
$data = "foo:*:1023:1000::/home/foo:/bin/sh";
list($user, $pass, $uid, $gid, $gecos, $home, $shell) = explode(":", $data);
echo $user; // foo
echo $pass; // *

?>

例2 explode() の戻り値の例

<?php
/*
デリミタを含まない文字列の場合は、
単に元の文字列だけを含む一要素の配列を返します
*/
$input1 = "hello";
$input2 = "hello,there";
$input3 = ',';
var_dump( explode( ',', $input1 ) );
var_dump( explode( ',', $input2 ) );
var_dump( explode( ',', $input3 ) );

?>

上の例の出力は以下となります。

array(1)
(
    [0] => string(5) "hello"
)
array(2)
(
    [0] => string(5) "hello"
    [1] => string(5) "there"
)
array(2)
(
    [0] => string(0) ""
    [1] => string(0) ""
)

例3 limit パラメータの例

<?php
$str = 'one|two|three|four';

// 正の値を持つ limit
print_r(explode('|', $str, 2));

// 負の値を持つ limit
print_r(explode('|', $str, -1));
?>

上の例の出力は以下となります。

Array
(
    [0] => one
    [1] => two|three|four
)
Array
(
    [0] => one
    [1] => two
    [2] => three
)

注意

注意: この関数はバイナリデータに対応しています。

参考

  • preg_split() - 正規表現で文字列を分割する
  • str_split() - 文字列を配列に変換する
  • mb_split() - マルチバイト文字列を正規表現により分割する
  • str_word_count() - 文字列に使用されている単語についての情報を返す
  • strtok() - 文字列をトークンに分割する
  • implode() - 配列要素を文字列により連結する


フォーマットされた文字列をストリームに書き込む

  • ≪ explode
  • get_html_translation_table ≫
  • PHP Manual
  • String 関数
  • フォーマットされた文字列をストリームに書き込む

fprintf

(PHP 5, PHP 7, PHP 8)

fprintf — フォーマットされた文字列をストリームに書き込む

説明

fprintf(resource $stream, string $format, mixed ...$values): int

format によって作成された文字列を stream で指定したストリームに書き込みます。

パラメータ

stream

fopen() を使用して作成したファイルシステムポインタリソース。

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 * を指定します。 * を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

Precision

ピリオド . の後に数値を続けるか、 * を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g, G, h, H 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 * を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は整数として扱われ、2進数値として表現されます。
c | 引数は整数として扱われ、ASCII文字として表現されます。
d | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は整数として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は整数として扱われ、符号なし10進数値として表現されます。
x | 引数は整数として扱われ、16進数値(小文字)として表現されます。
X | 引数は整数として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
int | d, u, c, o, x, X, b
float | e, E, f, F, g, G, h, H

values

戻り値

書き込まれた文字列の長さを返します。

エラー / 例外

  PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ArgumentCountError がスローされます。 これより前のバージョンでは、代わりに false を返し、E_WARNING を発生させていました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ArgumentCountError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

例

例1 fprintf(): 数値のゼロ埋め

<?php
if (!($fp = fopen('currency.txt', 'w'))) {
return;
}

fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
// ISO 形式にフォーマットした日付を date.txt に書き込みます
?>

例2 fprintf(): 金額のフォーマット

<?php
if (!($fp = fopen('date.txt', 'w'))) {
return;
}

$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money は "123.1" を出力します
$len = fprintf($fp, '%01.2f', $money);
// "123.10" を currency.txt に書き込みます

echo "$len バイトを currency.txt に書き込みました";
// fprintf の戻り値を使用して、書き込まれたバイト数を取得します
?>

参考

  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • vprintf() - フォーマットされた文字列を出力する
  • vsprintf() - フォーマットされた文字列を返す
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する


htmlspecialchars および htmlentities で使用される変換テーブルを返す

  • ≪ fprintf
  • hebrev ≫
  • PHP Manual
  • String 関数
  • htmlspecialchars および htmlentities で使用される変換テーブルを返す

get_html_translation_table

(PHP 4, PHP 5, PHP 7, PHP 8)

get_html_translation_table — htmlspecialchars() および htmlentities() で使用される変換テーブルを返す

説明

get_html_translation_table(int $table = HTML_SPECIALCHARS, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, string $encoding = "UTF-8"): array

get_html_translation_table() は、
htmlspecialchars() および
htmlentities()
において内部的に使用される変換テーブルを返します。

注意:

特殊文字はいくつかの方法でエンコードすることができます。 例えば、" は &quot;, &#34; もしくは &#x22 としてエンコードすることができます。 get_html_translation_table() の返す値は、 htmlspecialchars() や htmlentities() で使っている形式だけです。

パラメータ

table

どちらのテーブルを返すか。HTML_ENTITIES あるいは HTML_SPECIALCHARS。

flags

以下のフラグのビットマスクによる組み合わせで、 どのクォートをテーブルに含めるのか、そしてどのドキュメント形式用のテーブルにするのかを指定します。 デフォルトは ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 です。

使用可能な flags 定数
定数名 | 説明
ENT_COMPAT | テーブルにダブルクォート用のエンティティを含めますが、シングルクォート用は含めません。
ENT_QUOTES | テーブルにダブルクォート用、シングルクォート用の両方のエンティティを含めます。
ENT_NOQUOTES | テーブルにダブルクォート用、シングルクォート用のどちらのエンティティも含めません。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#FFFD; となります。
ENT_HTML401 | HTML 4.01 用のテーブル。
ENT_XML1 | XML 1 用のテーブル。
ENT_XHTML | XHTML 用のテーブル。
ENT_HTML5 | HTML 5 用のテーブル。

encoding

使用するエンコーディング。省略した場合のデフォルト値は UTF-8 となります。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

戻り値

変換テーブルを配列で返します。元の文字がキー、そしてエンティティが値となります。

変更履歴

バージョン | 説明
8.1.0 | flags のデフォルト値が ENT_COMPAT から ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 に変更されました。

例

例1 変換テーブルの例

<?php
var_dump(get_html_translation_table(HTML_ENTITIES, ENT_QUOTES | ENT_HTML5));
?>

上の例の出力は、 たとえば以下のようになります。

array(1510) {
  ["
"]=>
  string(9) "&NewLine;"
  ["!"]=>
  string(6) "&excl;"
  ["""]=>
  string(6) "&quot;"
  ["#"]=>
  string(5) "&num;"
  ["$"]=>
  string(8) "&dollar;"
  ["%"]=>
  string(8) "&percnt;"
  ["&"]=>
  string(5) "&amp;"
  ["'"]=>
  string(6) "&apos;"
  // ...
}

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • html_entity_decode() - HTML エンティティを対応する文字に変換する


論理表記のヘブライ語を物理表記に変換する

  • ≪ get_html_translation_table
  • hebrevc ≫
  • PHP Manual
  • String 関数
  • 論理表記のヘブライ語を物理表記に変換する

hebrev

(PHP 4, PHP 5, PHP 7, PHP 8)

hebrev — 論理表記のヘブライ語を物理表記に変換する

説明

hebrev(string $string, int $max_chars_per_line = 0): string

論理表記のヘブライ語を物理表記に変換します。

この関数は、単語の分断をできるだけ回避しようとします。

パラメータ

string

ヘブライ語の入力文字列。

max_chars_per_line

このオプションのパラメータは、 出力される行毎の最大文字数を返します。

戻り値

物理表記の文字列を返します。

参考

  • hebrevc() - 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する


論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

  • ≪ hebrev
  • hex2bin ≫
  • PHP Manual
  • String 関数
  • 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

hebrevc

(PHP 4, PHP 5, PHP 7)

hebrevc — 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

hebrevc(string $hebrew_text, int $max_chars_per_line = 0): string

この関数は、hebrev() に似ていますが、 改行 (\n) を "<br>\n" に変換するところが異なります。

この関数は、単語の分断をできるだけ回避しようとします。

パラメータ

hebrew_text

ヘブライ語の入力文字列。

max_chars_per_line

このオプションのパラメータは、 出力される行毎の最大文字数を返します。

戻り値

物理表記の文字列を返します。

参考

  • hebrev() - 論理表記のヘブライ語を物理表記に変換する


16進エンコードされたバイナリ文字列をデコードする

  • ≪ hebrevc
  • html_entity_decode ≫
  • PHP Manual
  • String 関数
  • 16進エンコードされたバイナリ文字列をデコードする

hex2bin

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

hex2bin — 16進エンコードされたバイナリ文字列をデコードする

説明

hex2bin(string $string): string|false

16進エンコードされたバイナリ文字列をデコードします。

警告

これは、16進数を2進数に変換する関数ではありません。 2進数への変換には base_convert() 関数を使いましょう。

パラメータ

string

16進表現のデータ。

戻り値

指定したデータを2進表現に変換したものを返します。 失敗した場合に false を返します。

エラー / 例外

16進表現の入力文字列長が奇数の場合や入力文字列が16進文字列として不正な場合は E_WARNING レベルのエラーが発生します。

例

例1 hex2bin() の例

<?php
$hex = hex2bin("6578616d706c65206865782064617461");
var_dump($hex);
?>

上の例の出力は、 たとえば以下のようになります。

string(16) "example hex data"

参考

  • bin2hex() - バイナリのデータを16進表現に変換する
  • unpack() - バイナリ文字列からデータを切り出す


HTML エンティティを対応する文字に変換する

  • ≪ hex2bin
  • htmlentities ≫
  • PHP Manual
  • String 関数
  • HTML エンティティを対応する文字に変換する

html_entity_decode

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

html_entity_decode — HTML エンティティを対応する文字に変換する

説明

html_entity_decode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, ?string $encoding = null): string

html_entity_decode() は htmlentities() の反対で、string にある HTML エンティティを対応する文字に変換します。

厳密に言うと、この関数は次の二つの条件を満たすすべての (数値エンティティを含む) エンティティをデコードします。それ以外のエンティティは、何も変換しません。 1) 選択したドキュメントタイプで必然的に有効になるもの。つまり XML の場合には、DTD で定義されている名前付きエンティティはデコードしません。 2) 選択したエンコーディングに関連づけられている符号化文字集合に含まれる文字で、 選択したドキュメントタイプで許可されているもの。

パラメータ

string

入力文字列。

flags

以下のフラグのビットマスクによる組み合わせで、クォートの扱いやドキュメントの形式を指定します。 デフォルトは ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 です。

使用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクォートを変換し、シングルクォートはそのままにします。
ENT_QUOTES | ダブルクォート、シングルクォートの両方を変換します。
ENT_NOQUOTES | ダブルクォート、シングルクォートの両方とも変換しません。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#FFFD; となります。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

encoding

オプションの引数。文字を変換するときに使うエンコーディングを定義します。

省略した場合の encoding のデフォルト値は、 default_charset の値を使います。

技術的にはこの引数を省略可能ですが、 default_charset の指定が入力とは違う文字セットになっている可能性もあるので、 適切な値を指定しておくことを強く推奨します。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

戻り値

デコードされた文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | flags のデフォルト値が ENT_COMPAT から ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 に変更されました。
8.0.0 | encoding は、nullable になりました。

例

例1 HTML エンティティのデコード

<?php
$orig = "I'll \"walk\" the <b>dog</b> now";

$a = htmlentities($orig);

$b = html_entity_decode($a);

echo $a; // I'll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now

echo $b; // I'll "walk" the <b>dog</b> now
?>

注意

注意:

trim(html_entity_decode('&nbsp;')); の結果が空の文字列に ならないことを疑問に思う人もいるでしょう。なぜそうなるのかというと、 デフォルトのエンコーディング ISO-8859-1 では '&nbsp;' エンティティが ASCII コード 32 (これは trim() で取り除かれる) ではなく ASCII コード 160 (0xa0) に変換されるからです。

参考

  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • urldecode() - URL エンコードされた文字列をデコードする


適用可能な文字を全て HTML エンティティに変換する

  • ≪ html_entity_decode
  • htmlspecialchars ≫
  • PHP Manual
  • String 関数
  • 適用可能な文字を全て HTML エンティティに変換する

htmlentities

(PHP 4, PHP 5, PHP 7, PHP 8)

htmlentities — 適用可能な文字を全て HTML エンティティに変換する

説明

htmlentities(
string $string,
int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
?string $encoding = null,
bool $double_encode = true
): string

この関数はhtmlspecialchars()と同じですが、 HTML エンティティと等価な意味を有する文字をHTMLエンティティに変換します。 指定する flags 定数に応じて使われる変換テーブルを得るには、 get_html_translation_table() を使います。

もしデコード (逆の処理) をしたい場合、 html_entity_decode() を使用することができます。

パラメータ

string

入力文字列。

flags

以下のフラグを組み合わせたビットマスクです。 クォートや無効な符号単位シーケンス、そして文書型の扱いを指定します。 デフォルトは ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 です。

利用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクオートは変換しますがシングルクオートは変換しません。
ENT_QUOTES | シングルクオートとダブルクオートを共に変換します。
ENT_NOQUOTES | シングルクオートとダブルクオートは共に変換されません。
ENT_IGNORE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく無効な部分を切り捨てるようになります。 このフラグは使わないようにしましょう。 » セキュリティの問題が発生する可能性があります。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#FFFD; となります。
ENT_DISALLOWED | 指定した文書型において無効な符号位置を、Unicode の代替文字である U+FFFD (UTF-8) あるいは &#FFFD; で置き換えます。 これを設定しなければ、無効な符号位置をそのまま残します。 これは、外部コンテンツを埋め込んだ XML 文書を整形式に保つために有用です。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

encoding

オプションの引数。文字を変換するときに使うエンコーディングを定義します。

省略した場合の encoding のデフォルト値は、 default_charset の値を使います。

技術的にはこの引数を省略可能ですが、 default_charset の指定が入力とは違う文字セットになっている可能性もあるので、 適切な値を指定しておくことを強く推奨します。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

double_encode

double_encode をオフにすると、PHP は既存の html エンティティをエンコードしません。 デフォルトでは、既存のエンティティも含めてすべてを変換します。

戻り値

エンコードした文字列を返します。

入力文字列の中に、指定した encoding で無効な符号単位シーケンスが含まれる場合は、 ENT_IGNORE あるいは ENT_SUBSTITUTE フラグが設定されていない限りは空文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | flags のデフォルト値が ENT_COMPAT から ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 に変更されました。
8.0.0 | encoding は、nullable になりました。

例

例1 htmlentities() の例

<?php
$str = "A 'quote' is <b>bold</b>";

// 出力: A 'quote' is &lt;b&gt;bold&lt;/b&gt;
echo htmlentities($str);

// 出力: A &#039;quote&#039; is &lt;b&gt;bold&lt;/b&gt;
echo htmlentities($str, ENT_QUOTES);
?>

例2 ENT_IGNORE の使用例

<?php
$str = "\x8F!!!";

// 出力: 空の文字列
echo htmlentities($str, ENT_QUOTES, "UTF-8");

// 出力: "!!!"
echo htmlentities($str, ENT_QUOTES | ENT_IGNORE, "UTF-8");
?>

参考

  • html_entity_decode() - HTML エンティティを対応する文字に変換する
  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • nl2br() - 改行文字の前に HTML の改行タグを挿入する
  • urlencode() - 文字列を URL エンコードする


特殊文字を HTML エンティティに変換する

  • ≪ htmlentities
  • htmlspecialchars_decode ≫
  • PHP Manual
  • String 関数
  • 特殊文字を HTML エンティティに変換する

htmlspecialchars

(PHP 4, PHP 5, PHP 7, PHP 8)

htmlspecialchars — 特殊文字を HTML エンティティに変換する

説明

htmlspecialchars(
string $string,
int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
?string $encoding = null,
bool $double_encode = true
): string

文字の中には HTML において特殊な意味を持つものがあり、 それらの本来の値を表示したければ HTML の表現形式に変換してやらなければなりません。 この関数は、これらの変換を行った結果の文字列を返します。 入力文字列の中で名前付きエンティティに関連づけられたものを すべて変換する必要がある場合には、代わりに htmlentities() を使用してください。

この関数への入力文字列と最終的なドキュメントとの間で文字セットが一致している場合は、 この関数を使えば HTML ドキュメントに組み込むための準備として十分です。 しかし、この関数への入力の中に、最終的なドキュメントの文字セットでは符号化できない文字がある場合もあります。 そんな文字も (数値エンティティや名前つきエンティティなどで) 残したい場合は、 この関数と htmlentities() (これは、名前付きエンティティに対応する文字しか置換しません) を使うだけでは不十分です。そんな場合は mb_encode_numericentity() を使う必要があります。

変換対象となる文字
変換前 | 変換後
& (アンパサンド) | &amp;
" (ダブルクォート) | ENT_NOQUOTES が指定されていない場合、&quot;
' (シングルクォート) | &#039; (ENT_HTML401 の場合) あるいは &apos; ( ENT_XML1、ENT_XHTML、 ENT_HTML5 の場合)。ただし ENT_QUOTES が指定されている場合に限る
< (小なり) | &lt;
> (大なり) | &gt;

パラメータ

string

変換される文字列。

flags

以下のフラグを組み合わせたビットマスクです。 クォートや無効な符号単位シーケンス、そして文書型の扱いを指定します。 デフォルトは ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 です。

利用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクオートは変換しますがシングルクオートは変換しません。
ENT_QUOTES | シングルクオートとダブルクオートを共に変換します。
ENT_NOQUOTES | シングルクオートとダブルクオートは共に変換されません。
ENT_IGNORE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく無効な部分を切り捨てるようになります。 このフラグは使わないようにしましょう。 » セキュリティの問題が発生する可能性があります。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#xFFFD; となります。
ENT_DISALLOWED | 指定した文書型において無効な符号位置を、Unicode の代替文字である U+FFFD (UTF-8) あるいは &#xFFFD; で置き換えます。 これを設定しなければ、無効な符号位置をそのまま残します。 これは、外部コンテンツを埋め込んだ XML 文書を整形式に保つために有用です。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

encoding

オプションの引数。文字を変換するときに使うエンコーディングを定義します。

省略した場合の encoding のデフォルト値は、 default_charset の値を使います。

技術的にはこの引数を省略可能ですが、 default_charset の指定が入力とは違う文字セットになっている可能性もあるので、 適切な値を指定しておくことを強く推奨します。

この関数を使ううえでは ISO-8859-1 と ISO-8859-15、 UTF-8、cp866、 cp1251、cp1252 そして KOI8-R は事実上同等です。 string 自体がそのエンコーディングにおける有効な文字列である限り、 これらのエンコーディングでは htmlspecialchars() の影響が及ぶ文字がみな同じ位置にあるからです。

以下の文字セットをサポートします。

サポートする文字セット
文字セット | エイリアス | 説明
ISO-8859-1 | ISO8859-1 | 西欧、Latin-1
ISO-8859-5 | ISO8859-5 | ほとんど使われないキリル文字セット (Latin/Cyrillic)。
ISO-8859-15 | ISO8859-15 | 西欧、Latin-9 。Latin-1(ISO-8859-1) に欠けている ユーロ記号やフランス・フィンランドの文字を追加したもの。
UTF-8 | ASCII 互換のマルチバイト 8 ビット Unicode 。
cp866 | ibm866, 866 | DOS 固有のキリル文字セット。
cp1251 | Windows-1251, win-1251, 1251 | Windows 固有のキリル文字セット。
cp1252 | Windows-1252, 1252 | 西欧のための Windows 固有の文字セット。
KOI8-R | koi8-ru, koi8r | ロシア語。
BIG5 | 950 | 繁体字中国語。主に台湾で使用されます。
GB2312 | 936 | 簡体字中国語。国の標準文字セットです。
BIG5-HKSCS | Big5 に香港の拡張を含めたもの。繁体字中国語。
Shift_JIS | SJIS, SJIS-win, cp932, 932 | 日本語。
EUC-JP | EUCJP, eucJP-win | 日本語。
MacRoman | Mac OS で使われる文字セット。
'' 空文字列を指定すると、 スクリプトのエンコーディング (Zend multibyte)、 default_charset、 そして現在のロケール (nl_langinfo() および setlocale() を参照ください) の順でエンコーディングを検出します。 この方法はおすすめしません。

注意: これら以外の文字セットは理解できません。 かわりにデフォルトのエンコーディングを使用し、警告を発生させます。

double_encode

double_encode をオフにすると、PHP は既存の html エンティティをエンコードしません。 デフォルトでは、既存のエンティティも含めてすべてを変換します。

戻り値

変換後の文字列を返します。

入力の string の中に エンコーディング encoding における無効なコードユニットシーケンスが含まれており、 かつ ENT_IGNORE フラグが設定されていなければ、 htmlspecialchars() は空文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | flags のデフォルト値が ENT_COMPAT から ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 に変更されました。

例

例1 htmlspecialchars() の例

<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>

注意

注意:

この関数は上記のあげたもの以外に関しては一切の変換を行わないことに注意してください。 すべての変換を行うには htmlentities() を参照ください。

注意:

flags の値が曖昧な場合、以下のルールが適用されます:

  • ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES のいずれも存在しない場合、 デフォルトは ENT_NOQUOTES になります。
  • ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES のうちひとつ以上が存在する場合、 ENT_QUOTES がもっとも優先度が高くなり、 その後に ENT_COMPAT が続きます。
  • ENT_HTML401, ENT_HTML5, ENT_XHTML, ENT_XML1 のいずれも存在しなければ、 デフォルトは ENT_HTML401 になります。
  • ENT_HTML401, ENT_HTML5, ENT_XHTML, ENT_XML1 のうちひとつ以上が存在している場合、 ENT_HTML5 が最も優先度が高くなり、 ENT_XHTML, ENT_XML1 そして ENT_HTML401 の順に続きます。
  • ENT_DISALLOWED, ENT_IGNORE, ENT_SUBSTITUTE のうち、ひとつ以上が存在している場合、 ENT_IGNORE の優先度がもっとも高くなり、 ENT_SUBSTITUTE がその後に続きます。

参考

  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す
  • htmlspecialchars_decode() - 特殊な HTML エンティティを文字に戻す
  • strip_tags() - 文字列から HTML および PHP タグを取り除く
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • nl2br() - 改行文字の前に HTML の改行タグを挿入する


特殊な HTML エンティティを文字に戻す

  • ≪ htmlspecialchars
  • implode ≫
  • PHP Manual
  • String 関数
  • 特殊な HTML エンティティを文字に戻す

htmlspecialchars_decode

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

htmlspecialchars_decode — 特殊な HTML エンティティを文字に戻す

説明

htmlspecialchars_decode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401): string

この関数は htmlspecialchars() の反対です。 特殊な HTML エンティティを文字に戻します。

変換されるエンティティは次のものです。&amp;、 &quot; (ENT_NOQUOTES が設定されていない場合)、 &#039; (ENT_QUOTES が設定されている場合)、 &lt; および &gt;。

パラメータ

string

デコードする文字列。

flags

以下のフラグのビットマスクによる組み合わせで、クォートの扱いやドキュメントの形式を指定します。 デフォルトは ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 です。

使用可能な flags 定数
定数名 | 説明
ENT_COMPAT | ダブルクォートを変換し、シングルクォートはそのままにします。
ENT_QUOTES | ダブルクォート、シングルクォートの両方を変換します。
ENT_NOQUOTES | ダブルクォート、シングルクォートの両方をそのままにします。
ENT_SUBSTITUTE | 無効な符号単位シーケンスを含む文字列を渡したときに、 空の文字列を返すのではなく Unicode の置換文字に置き換えます。 UTF-8 の場合は U+FFFD、それ以外の場合は &#FFFD; となります。
ENT_HTML401 | コードを HTML 4.01 として処理します。
ENT_XML1 | コードを XML 1 として処理します。
ENT_XHTML | コードを XHTML として処理します。
ENT_HTML5 | コードを HTML 5 として処理します。

戻り値

デコードされた文字列を返します。

変更履歴

バージョン | 説明
8.1.0 | flags のデフォルト値が ENT_COMPAT から ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401 に変更されました。

例

例1 htmlspecialchars_decode() の例

<?php
$str = "<p>this -&gt; &quot;</p>\n";

echo htmlspecialchars_decode($str);

// クォートが変換されないことに注意しましょう
echo htmlspecialchars_decode($str, ENT_NOQUOTES);
?>

上の例の出力は以下となります。

<p>this -> "</p>
<p>this -> &quot;</p>

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • html_entity_decode() - HTML エンティティを対応する文字に変換する
  • get_html_translation_table() - htmlspecialchars および htmlentities で使用される変換テーブルを返す


配列要素を文字列により連結する

  • ≪ htmlspecialchars_decode
  • join ≫
  • PHP Manual
  • String 関数
  • 配列要素を文字列により連結する

implode

(PHP 4, PHP 5, PHP 7, PHP 8)

implode — 配列要素を文字列により連結する

説明

implode(string $separator, array $array): string

代替のシグネチャ(名前付き引数をサポートしていません):

implode(array $array): string

古いシグネチャ(PHP 7.4.0 で非推奨となり、PHP 8.0.0 以降は削除されています):

implode(array $array, string $separator): string

配列の要素を separator 文字列で連結します。

パラメータ

separator

オプションです。 デフォルトは空文字列です。

array

連結したい文字列の配列。

戻り値

すべての配列要素の順序を変えずに、各要素間に separator 文字列をはさんで 1 つの文字列にして返します。

変更履歴

バージョン | 説明
8.0.0 | array の後に separator を渡すことは、サポートされなくなりました。
7.4.0 | array の後に separator を渡すこと (つまり、古いシグネチャを使うこと) は、推奨されなくなりました。

例

例1 implode() の例

<?php

$array = ['lastname', 'email', 'phone'];
var_dump(implode(",", $array)); // string(20) "lastname,email,phone"

// 空の配列を使うと空文字列となります
var_dump(implode('hello', [])); // string(0) ""

// separator はオプションです。
var_dump(implode(['a', 'b', 'c'])); // string(3) "abc"

?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • explode() - 文字列を文字列により分割する
  • preg_split() - 正規表現で文字列を分割する
  • http_build_query() - URL エンコードされたクエリ文字列を生成する


implode のエイリアス

  • ≪ implode
  • lcfirst ≫
  • PHP Manual
  • String 関数
  • implode のエイリアス

join

(PHP 4, PHP 5, PHP 7, PHP 8)

join — implode() のエイリアス

説明

この関数は次の関数のエイリアスです。 implode().


文字列の最初の文字を小文字にする

  • ≪ join
  • levenshtein ≫
  • PHP Manual
  • String 関数
  • 文字列の最初の文字を小文字にする

lcfirst

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

lcfirst — 文字列の最初の文字を小文字にする

説明

lcfirst(string $string): string

string の最初の文字が ASCII の "A" (0x41) から "Z" (0x5a) までの範囲にあれば、 それを小文字にします。

パラメータ

string

入力文字列。

戻り値

変換後の文字列を返します。

変更履歴

バージョン | 説明
8.2.0 | ケース変換は、setlocale() で設定されたロケールに依存しなくなりました。 ASCII 文字のみが変換されます。

例

例1 lcfirst() の例

<?php
$foo = 'HelloWorld';
$foo = lcfirst($foo); // helloWorld

$bar = 'HELLO WORLD!';
$bar = lcfirst($bar); // hELLO WORLD!
$bar = lcfirst(strtoupper($bar)); // hELLO WORLD!
?>

参考

  • ucfirst() - 文字列の最初の文字を大文字にする
  • strtolower() - 文字列を小文字にする
  • strtoupper() - 文字列を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする


二つの文字列のレーベンシュタイン距離を計算する

  • ≪ lcfirst
  • localeconv ≫
  • PHP Manual
  • String 関数
  • 二つの文字列のレーベンシュタイン距離を計算する

levenshtein

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

levenshtein — 二つの文字列のレーベンシュタイン距離を計算する

説明

levenshtein(
string $string1,
string $string2,
int $insertion_cost = 1,
int $replacement_cost = 1,
int $deletion_cost = 1
): int

レーベンシュタイン距離は、string1 を string2 に変換するために置換、挿入、削除 しなければならない最小の文字数として定義されます。アルゴリズムの計算量は、 O(m*n) です。 ここで、n および m はそれぞれ string1 および string2 の長さです。 O(max(n,m)**3) となる similar_text() よりは良いですが、 まだかなりの計算量です)。

insertion_cost, replacement_cost かつ/または deletion_cost が 1 以外の場合、 変換コストが最も小さいアルゴリズムを採用します。 たとえば、$insertion_cost + $deletion_cost < $replacement_cost の場合、 置換をせず、挿入と削除が行われます。

パラメータ

string1

レーベンシュタイン距離を計算する文字列のひとつ。

string2

レーベンシュタイン距離を計算する文字列のひとつ。

insertion_cost

挿入のコストを定義します。

replacement_cost

置換のコストを定義します。

deletion_cost

削除のコストを定義します。

戻り値

この関数は、引数で指定した二つの文字列のレーベンシュタイン距離を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 引数を2個、または5個指定して呼び出さなければなりませんでした。
8.0.0 | これより前のバージョンでは、 引数文字列の一つが 255 文字の制限より長い場合に -1 を返していました。

例

例1 levenshtein() の例

<?php
// スペルミスした単語を入力します
$input = 'carrrot';

// チェックするための単語の配列
$words = array('apple','pineapple','banana','orange',
'radish','carrot','pea','bean','potato');

// まだ最短距離は見つかっていません
$shortest = -1;

// 最短距離を見つけるため単語をループします
foreach ($words as $word) {

// 入力した単語と現在の単語の距離を
// 計算します
$lev = levenshtein($input, $word);

// マッチするかどうかチェックします
if ($lev == 0) {

// 最短な単語はこれだ (マッチした)
$closest = $word;
$shortest = 0;

// ループを抜ける; マッチしたものを見つけました
break;
}

// もし距離が次に見つけた最短距離よりも短い場合、
// もしくは次の最短の単語がまだ見つかっていない場合
if ($lev <= $shortest || $shortest < 0) {
// 最短のマッチと最短距離をセットします
$closest = $word;
$shortest = $lev;
}
}

echo "入力した単語: $input\n";
if ($shortest == 0) {
echo "一致するものが見つかりました: $closest\n";
} else {
echo "もしかして: $closest\n";
}

?>

上の例の出力は以下となります。

入力した単語: carrrot
もしかして: carrot

参考

  • soundex() - 文字列の soundex キーを計算する
  • similar_text() - 二つの文字列の間の類似性を計算する
  • metaphone() - 文字列の metaphone キーを計算する


数値に関するフォーマット情報を得る

  • ≪ levenshtein
  • ltrim ≫
  • PHP Manual
  • String 関数
  • 数値に関するフォーマット情報を得る

localeconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

localeconv — 数値に関するフォーマット情報を得る

説明

localeconv(): array

ローカルな数値および通貨フォーマット情報を有する連想配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

localeconv() は、 setlocale() で設定された現在のロケールに基づきデータを返します。 返される連想配列は、次のフィールドを有します。

配列要素 | 説明
decimal_point | 小数点文字
thousands_sep | 千毎の区切り文字
grouping | 数値集合を有する配列
int_curr_symbol | 国際通貨記号 (すなわち、USD)
currency_symbol | ローカルな通貨記号 (すなわち、$)
mon_decimal_point | 通貨用の小数点文字
mon_thousands_sep | 通貨用の千毎の区切り文字
mon_grouping | 通貨集合を有する配列
positive_sign | 正の値を表す記号
negative_sign | 負の値を表す記号
int_frac_digits | 国際分割桁
frac_digits | ローカルな分割桁
p_cs_precedes | currency_symbol が正の値を前に置く場合にtrue、後に置く場合に false
p_sep_by_space | 正の値から currency_symbol を1文字の空白で区切る場合にtrue、 そうでない場合にfalse
n_cs_precedes | currency_symbol が負の値を前に置く場合にtrue、後に置く場合に false
n_sep_by_space | 負の値から currency_symbol を1文字の空白で区切る場合にtrue、 そうでない場合にfalse
p_sign_posn
  • 0 - 量および通貨記号を括る括弧
  • 1 - 量および通貨記号の前に置く符号文字列
  • 2 - 量および通貨記号の後に置く符号文字列
  • 3 - 通貨記号の直前に置く符号文字列
  • 4 - 通貨記号の直後に置く符号文字列
n_sign_posn
  • 0 - 量および通貨記号を括る括弧
  • 1 - 量および通貨記号の前に置く符号文字列
  • 2 - 量および通貨記号の後に置く符号文字列
  • 3 - 通貨記号の直前に置く符号文字列
  • 4 - 通貨記号の直後に置く符号文字列

n_sign_posn や n_sign_posn は、フォーマッタオプションの文字列を含みます。それぞれの数字は 上に一覧されている条件の 1 つを表します。

groupingフィールドには、グループ化する方法を表す数字を定義する配 列が含まれます。例えば、nl_NL ロケール用の通貨 groupingフィールド (UTF-8 モードでのユーロ記号) には、 3、3を値とする要素数2の配列が含まれます。この配列のより高い添字に は、より左側のグループに関するものが含まれます。 ある配列要素が、CHAR_MAX に等しい場合、 さらにグループは行われません。配列要素が0に等しい場合、 前の要素が使用されています。

例

例1 localeconv() の例

<?php
if (false !== setlocale(LC_ALL, 'nl_NL.UTF-8@euro')) {
$locale_info = localeconv();
print_r($locale_info);
}
?>

上の例の出力は以下となります。

Array
(
    [decimal_point] => .
    [thousands_sep] =>
    [int_curr_symbol] => EUR
    [currency_symbol] => ?
    [mon_decimal_point] => ,
    [mon_thousands_sep] =>
    [positive_sign] =>
    [negative_sign] => -
    [int_frac_digits] => 2
    [frac_digits] => 2
    [p_cs_precedes] => 1
    [p_sep_by_space] => 1
    [n_cs_precedes] => 1
    [n_sep_by_space] => 1
    [p_sign_posn] => 1
    [n_sign_posn] => 2
    [grouping] => Array
        (
        )

    [mon_grouping] => Array
        (
            [0] => 3
            [1] => 3
        )

)

参考

  • setlocale() - ロケール情報を設定する


文字列の最初から空白 (もしくはその他の文字) を取り除く

  • ≪ localeconv
  • md5 ≫
  • PHP Manual
  • String 関数
  • 文字列の最初から空白 (もしくはその他の文字) を取り除く

ltrim

(PHP 4, PHP 5, PHP 7, PHP 8)

ltrim — 文字列の最初から空白 (もしくはその他の文字) を取り除く

説明

ltrim(string $string, string $characters = " \n\r\t\v\x00"): string

文字列の最初から空白 (もしくはその他の文字) を取り除きます。

パラメータ

string

入力文字列。

characters

charactersパラメータにより、削除する 文字を指定することも可能です。削除したい全ての文字をリストに してください。..を文字の範囲を指定する際に 使用可能です。

戻り値

この関数は string の最初から空白文字を取り除き、 取り除かれた文字列を返します。2番目のパラメータを指定しない場合、 ltrim()は以下の文字を削除します。

  • " " (ASCII 32 (0x20)), 通常の空白。
  • "\t" (ASCII 9 (0x09)), タブ。
  • "\n" (ASCII 10 (0x0A)), 改行。
  • "\r" (ASCII 13 (0x0D)), 復帰。
  • "\0" (ASCII 0 (0x00)), NUL バイト。
  • "\v" (ASCII 11 (0x0B)), 垂直タブ。

例

例1 ltrim() の使用例

<?php

$text = "\t\tThese are a few words :) ... ";
$binary = "\x09Example string\x0A";
$hello = "Hello World";
var_dump($text, $binary, $hello);

print "\n";

$trimmed = ltrim($text);
var_dump($trimmed);

$trimmed = ltrim($text, " \t.");
var_dump($trimmed);

$trimmed = ltrim($hello, "Hdle");
var_dump($trimmed);

// ASCII 制御文字 (0 から 31 まで) を
// $binary の先頭から取り除きます
$clean = ltrim($binary, "\x00..\x1F");
var_dump($clean);

?>

上の例の出力は以下となります。

string(32) "        These are a few words :) ...  "
string(16) "    Example string
"
string(11) "Hello World"

string(30) "These are a few words :) ...  "
string(30) "These are a few words :) ...  "
string(7) "o World"
string(15) "Example string
"

参考

  • trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • rtrim() - 文字列の最後から空白 (もしくはその他の文字) を取り除く


文字列のmd5ハッシュ値を計算する

  • ≪ ltrim
  • md5_file ≫
  • PHP Manual
  • String 関数
  • 文字列のmd5ハッシュ値を計算する

md5

(PHP 4, PHP 5, PHP 7, PHP 8)

md5 — 文字列のmd5ハッシュ値を計算する

警告

パスワードを守るためにこの関数を使うことはおすすめしません。 ハッシュアルゴリズムの高速性がその理由です。 詳細とベストプラクティスについては、パスワードハッシュ FAQを参照ください。

説明

md5(string $string, bool $binary = false): string

» RSA Data Security, Inc. の MD5メッセージダイジェストアルゴリズム を用いて string の MD5 ハッシュ値を計算し、 そのハッシュを返します。

パラメータ

string

文字列。

binary

オプションのbinary に true が指定された場合、 md5 ダイジェストが 16 バイト長のバイナリ形式で返されます。

戻り値

32 文字の 16 進数からなるハッシュを返します。

例

例1 md5() の例

<?php
$str = 'apple';

if (md5($str) === '1f3870be274f6c49b3e31a0c6728957f') {
echo "Would you like a green or red apple?";
}
?>

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • password_hash() - パスワードハッシュを作る


指定したファイルのMD5ハッシュ値を計算する

  • ≪ md5
  • metaphone ≫
  • PHP Manual
  • String 関数
  • 指定したファイルのMD5ハッシュ値を計算する

md5_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

md5_file — 指定したファイルのMD5ハッシュ値を計算する

説明

md5_file(string $filename, bool $binary = false): string|false

» RSA Data Security, Inc. MD5 メッセージダイジェストアルゴリズムを用いて filenameパラメータで指定したファイルの MD5ハッシュを計算し、そのハッシュを返します。 ハッシュは、32 文字の 16 進数です。

パラメータ

filename

ファイル名

binary

true の場合、長さ 16 の生のバイナリフォーマットで ダイジェストを返します。

戻り値

成功時は文字列、そうでなければ false

例

例1 md5_file() の使用例

<?php
$file = 'php-5.3.0alpha2-Win32-VC9-x64.zip';

echo 'MD5 file hash of ' . $file . ': ' . md5_file($file);
?>

参考

  • hash_file() - ファイルの内容から、ハッシュ値を生成する
  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • md5() - 文字列のmd5ハッシュ値を計算する


文字列の metaphone キーを計算する

  • ≪ md5_file
  • money_format ≫
  • PHP Manual
  • String 関数
  • 文字列の metaphone キーを計算する

metaphone

(PHP 4, PHP 5, PHP 7, PHP 8)

metaphone — 文字列の metaphone キーを計算する

説明

metaphone(string $string, int $max_phonemes = 0): string

string の metaphone キーを計算します。

soundex() と同様に metaphone は、 発音が似た単語について同じキーを作成します。metaphone は、 英語の発音の基本的ルールを知っているので、 soundex() よりも正確です。 metaphone が生成するキーは可変長です。

metaphone は、Lawrence Philips <lphilips at verity dot com> により 開発されました。["Practical Algorithms for Programmers", Binstock & Rex, Addison Wesley, 1995] で解説されています。

パラメータ

string

入力文字列。

max_phonemes

このパラメータは、返される metaphone キーの長さを最大 max_phonemes 文字 までに制限します。 しかし、phonemes は完全に書き換えられるので、 結果の文字列の長さは、max_phonemes よりも少し長くなります。 デフォルト値の 0 は、無制限であることを意味します。

戻り値

metaphone キーを文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。

例

例1 metaphone() の基本的な例

<?php
var_dump(metaphone('programming'));
var_dump(metaphone('programmer'));
?>

上の例の出力は以下となります。

string(7) "PRKRMNK"
string(6) "PRKRMR"

例2 phonemes パラメータの使用例

<?php
var_dump(metaphone('programming', 5));
var_dump(metaphone('programmer', 5));
?>

上の例の出力は以下となります。

string(5) "PRKRM"
string(5) "PRKRM"

例3 phonemes 引数を使う

この例では、 metaphone() 関数は5文字の文字列を生成するように指定されていますが、 最後の音素を分割する必要がある ('x' は 'KS' に書き換えられるとします), ため、返される文字列は6文字になります。

<?php
var_dump(metaphone('Asterix', 5));
?>

上の例の出力は以下となります。

string(6) "ASTRKS"


数値を金額文字列にフォーマットする

  • ≪ metaphone
  • nl_langinfo ≫
  • PHP Manual
  • String 関数
  • 数値を金額文字列にフォーマットする

money_format

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

money_format — 数値を金額文字列にフォーマットする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

money_format(string $format, float $number): string

money_format() は、number をフォーマットして返します。この関数は C のライブラリ関数 strfmon() をラップしたものですが、一度に 変換できる数値がひとつだけであるという点が異なります。

パラメータ

format

フォーマット指定の書式は以下の順になります。

  • % 文字

  • フラグ(オプション)

  • フィールドの幅(オプション)

  • 左精度(オプション)

  • 右精度(オプション)

  • 変換文字(必須)

フラグ

以下のフラグのうちひとつあるいは複数が使用可能です。

=f

文字 = の後に続く(シングルバイトの)文字 f が、数値埋め文字として使用されます。 デフォルトはスペース文字です。

^

グループ化文字(現在のロケールで定義されている)を使用しないようにします。

+ あるいは (

正の数、負の数の書式を指定します。+ が使用された場合、 + および - に該当する そのロケールの符号マークが使用されます。( が使用された場合、負の数は括弧で囲まれます。何も指定しなかった場合、 デフォルトは + です。

!

出力文字列から通貨記号を除きます。

-

指定した場合、すべてのフィールドを左詰め(右側に数値埋め文字が追加される) にします。デフォルトはこれと反対で、すべてのフィールドを右詰め (左側に数値埋め文字が追加される)にします。

フィールドの幅

w

10 進の数値形式の文字列で、フィールドの幅の最小値を指定します。フラグ - が使用されていない限り、フィールドは 右詰めとなります。デフォルト値は 0(ゼロ) です。

左精度

#n

10 進の基準文字(例: 小数点)より左側の最大の桁数 (n) を指定します。これは通常、 n より少ない桁数の数値に対して 数値埋め文字を使用することで、出力の桁位置をそろえるために 使用されます。実際の桁数が n より 大きい場合、この設定は無視されます。

^ フラグでグループ化文字が抑止されていない場合、 (もし存在するなら)数値埋め文字が追加される前にグループ化文字が 挿入されます。グループ化文字は数値埋め文字には適用されません。 たとえ数値埋め文字が数字であったとしても同様です。

位置あわせを確実にするため、出力中の数値の前後に表れる文字(たとえば 通貨記号や符号など)は、必要に応じて(正の数と負の数の長さをそろえるなど の理由で)スペース文字が付加されることがあります。

右精度

.p

ピリオドに続く数値(p) で、10 進の基準文字以降の桁数を指定します。 p の値が 0(ゼロ)であった場合、基準文字と それ以降の数値は省略されます。右精度が指定されていない場合、 使用中の現在のロケールからデフォルト値を検出します。 フォーマットされる数値は、フォーマット前にこの桁数に丸められます。

変換文字

i

ロケールの国際通貨フォーマット(例: USA ロケールでは USD 1,234.56)によってフォーマットします。

n

ロケールの国内通貨フォーマット(例: de_DE ロケールでは EU1.234,56) によってフォーマットします。

%

% 文字を返します。

number

フォーマットする数値。

戻り値

フォーマットした文字列を返します。 フォーマット文字列の前後の文字は、そのまま返されます。 number が非数値の場合は null を返し、 E_WARNING を発行します。

変更履歴

バージョン | 説明
7.4.0 | この関数は非推奨になりました。 代わりに、NumberFormatter::formatCurrency() を使ってください。

例

例1 money_format() の例

この関数の使用法を詳しく説明するために、 さまざまなロケールおよびフォーマット指定を使用します。

<?php

$number = 1234.56;

// en_US ロケールの国際フォーマットで表示します
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";
// USD 1,234.56

// イタリアの国内フォーマットで小数点以下 2 桁で表示します
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// Eu 1.234,56

// 負の数を使用します
$number = -1234.5672;

// US の国際フォーマットで、負の数には () を使用して
// 左精度を 10 桁にします
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($ 1,234.57)

// 上と同じですが、それに加えて右精度を 2 桁
// 数値埋め文字として '*' を使用します
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)

// 左詰め、幅 14 桁、左精度 8 桁、右精度 2 桁、グループ化文字なしで
// de_DE ロケールの国際フォーマットを使用します。
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// Eu 1234,56****

// 変換指定の前後に宣伝文句を追加します
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'The final value is %i (after a 10%% discount)';
echo money_format($fmt, 1234.56) . "\n";
// The final value is GBP 1,234.56 (after a 10% discount)

?>

注意

注意:

システムで strfmon が使用可能な場合のみ money_format() 関数が定義されます。例えば、Windows では strfmon は使用できません。 そのため money_format() は Windows では 定義されていません。

注意:

ロケール設定のうち、LC_MONETARY カテゴリの内容が この関数の振る舞いに影響します。この関数を使用する前に、 setlocale() で適切なデフォルトロケールを 設定してください。

参考

  • setlocale() - ロケール情報を設定する
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • sprintf() - フォーマットされた文字列を返す
  • printf() - フォーマット済みの文字列を出力する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする


言語およびロケール情報を検索する

  • ≪ money_format
  • nl2br ≫
  • PHP Manual
  • String 関数
  • 言語およびロケール情報を検索する

nl_langinfo

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

nl_langinfo — 言語およびロケール情報を検索する

説明

nl_langinfo(int $item): string|false

nl_langinfo() はロケールカテゴリの独立した要素にアクセスするために使用されます。 localeconv() と異なり、全ての要素を返します。 nl_langinfo() はいかなる特定要素も取得可能です。

パラメータ

item

item は要素の整数値、もしくは要素の定数名です。 以下は、使用される item に対する定数名と説明の一覧です。 これらの定数のいくつかは特定のロケールに対して未定義、 もしくは値がありません。

nl_langinfo 定数
定数 | 説明
LC_TIME カテゴリの定数
ABDAY_(1-7) | 一週間中の n 番目の曜日名の略式表記
DAY_(1-7) | 一週間中の n 番目の曜日名 (DAY_1 = 日曜日)
ABMON_(1-12) | n 番目の月の名前の略式表記
MON_(1-12) | n 番目の月の名前
AM_STR | 午前を表す文字列
PM_STR | 午後を表す文字列
D_T_FMT | strftime() で日時を表すためのフォーマット文字列として使用することが可能な文字列
D_FMT | strftime() で日付を表すためのフォーマット文字列として使用することが可能な文字列
T_FMT | strftime() で時刻を表すためのフォーマット文字列として使用することが可能な文字列
T_FMT_AMPM | strftime() でAM/PM付き 12 時間表記を表すためのフォーマット文字列として使用することが可能な文字列
ERA | ロケール固有の元号付きフォーマット
ERA_YEAR | ロケール固有の元号付きフォーマットでの年
ERA_D_T_FMT | ロケール固有の元号付きフォーマットでの日時 (strftime() で使用可能な文字列)
ERA_D_FMT | ロケール固有の元号付きフォーマットでの日付 (strftime() で使用可能な文字列)
ERA_T_FMT | ロケール固有の元号付きフォーマットでの時刻 (strftime() で使用可能な文字列)
LC_MONETARY カテゴリの定数
INT_CURR_SYMBOL | 国際通貨記号
CURRENCY_SYMBOL | 地域通貨記号
CRNCYSTR | CURRENCY_SYMBOL と同じ値
MON_DECIMAL_POINT | 小数点文字
MON_THOUSANDS_SEP | 1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字
MON_GROUPING | 'grouping' と同じ
POSITIVE_SIGN | 正値の表示に使用される記号
NEGATIVE_SIGN | 負値の表示に使用される記号
INT_FRAC_DIGITS | 国際的な方法で表現する際の小数点以下の桁数
FRAC_DIGITS | 地域的な方法で表現する際の小数点以下の桁数
P_CS_PRECEDES | CURRENCY_SYMBOL の前に正値がある場合 1 を返す
P_SEP_BY_SPACE | CURRENCY_SYMBOL と正値がスペースで区切られる場合 1 を返す
N_CS_PRECEDES | CURRENCY_SYMBOL の前に負値がある場合 1 を返す
N_SEP_BY_SPACE | CURRENCY_SYMBOL と負値がスペースで区切られる場合 1 を返す
P_SIGN_POSN
  • 量および CURRENCY_SYMBOL を括弧で括る場合、0 を返す
  • 量および CURRENCY_SYMBOL の前に符号文字列を置く場合、1 を返す
  • 量および CURRENCY_SYMBOL の後に符号文字列を置く場合、2 を返す
  • CURRENCY_SYMBOL の直前に符号文字列を置く場合、3 を返す
  • CURRENCY_SYMBOL の直後に符号文字列を置く場合、4 を返す
N_SIGN_POSN
LC_NUMERIC カテゴリの定数
DECIMAL_POINT | 小数点文字
RADIXCHAR | DECIMAL_POINT と同じ値
THOUSANDS_SEP | 1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字
THOUSEP | THOUSANDS_SEP と同じ値
GROUPING
LC_MESSAGES カテゴリの定数
YESEXPR | "はい" の入力にマッチさせるための正規表現
NOEXPR | "いいえ" の入力にマッチさせるための正規表現
YESSTR | "はい" のための出力文字列
NOSTR | "いいえ" のための出力文字列
LC_CTYPE カテゴリの定数
CODESET | 文字エンコーディング名の文字列を返す

戻り値

要素を文字列で返します。item が有効でない場合は false を返します。

例

例1 nl_langinfo() の例

<?php

var_dump(nl_langinfo(CODESET));
var_dump(nl_langinfo(YESEXPR));
?>

上の例の出力は、 たとえば以下のようになります。

string(14) "ANSI_X3.4-1968"
string(5) "^[yY]"

注意

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • setlocale() - ロケール情報を設定する
  • localeconv() - 数値に関するフォーマット情報を得る


改行文字の前に HTML の改行タグを挿入する

  • ≪ nl_langinfo
  • number_format ≫
  • PHP Manual
  • String 関数
  • 改行文字の前に HTML の改行タグを挿入する

nl2br

(PHP 4, PHP 5, PHP 7, PHP 8)

nl2br — 改行文字の前に HTML の改行タグを挿入する

説明

nl2br(string $string, bool $use_xhtml = true): string

string に含まれるすべての改行文字 (\r\n、 \n\r、\n および \r) の前に <br /> あるいは <br> を挿入して返します。

パラメータ

string

入力文字列。

use_xhtml

XHTML 準拠の改行を使うか否か。

戻り値

変更後の文字列を返します。

例

例1 nl2br() の使用法

<?php
echo nl2br("foo isn't\n bar");
?>

上の例の出力は以下となります。

foo isn't<br />
 bar

例2 use_xhtml パラメータを使い、妥当な HTML 形式のマークアップを生成する

<?php
echo nl2br("Welcome\r\nThis is my HTML document", false);
?>

上の例の出力は以下となります。

Welcome<br>
This is my HTML document

例3 さまざまな改行文字

<?php
$string = "This\r\nis\n\ra\nstring\r";
echo nl2br($string);
?>

上の例の出力は以下となります。

This<br />
is<br />
a<br />
string<br />

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • wordwrap() - 指定した文字数で文字列を分割する
  • str_replace() - 検索文字列に一致したすべての文字列を置換する


数字を千の位毎にグループ化してフォーマットする

  • ≪ nl2br
  • ord ≫
  • PHP Manual
  • String 関数
  • 数字を千の位毎にグループ化してフォーマットする

number_format

(PHP 4, PHP 5, PHP 7, PHP 8)

number_format — 数字を千の位毎にグループ化してフォーマットする

説明

number_format(
float $num,
int $decimals = 0,
?string $decimal_separator = ".",
?string $thousands_separator = ","
): string

数値を千の位毎にグループ化し、オプションで小数の桁も追加してフォーマットします。小数の桁を追加する場合、四捨五入のルールを使います。

パラメータ

num

フォーマットする数値。

decimals

小数点以下の桁数。 0 を指定すると、 戻り値の decimal_separator は省略されます。

decimal_separator

小数点を表す区切り文字。

thousands_separator

千の位毎の区切り文字。

戻り値

num をフォーマットした結果を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 number_format() 関数は 引数を1個、2個、または4個受け入れていました(つまり、3個はダメでした)。
7.2.0 | number_format() は、 -0 を返さないように変更されました。 これより前のバージョンでは、 num が -0.01 のようなケースで -0 が返される場合がありました。

例

例1 number_format() の例

例えばフランスの表記法では、通常カンマ (',') を小数の区切りとした二桁の小数と、千位毎の区切りとしてスペース (' ') を用います。数値を書式設定するさまざまな方法を次の例で示します。

<?php

$number = 1234.56;

// 英語での表記 (デフォルト)
$english_format_number = number_format($number);
// 1,235

// フランスの表記
$nombre_format_francais = number_format($number, 2, ',', ' ');
// 1 234,56

$number = 1234.5678;

// 千位毎の区切りがない英語での表記
$english_format_number = number_format($number, 2, '.', '');
// 1234.57

?>

参考

  • money_format() - 数値を金額文字列にフォーマットする
  • sprintf() - フォーマットされた文字列を返す
  • printf() - フォーマット済みの文字列を出力する
  • sscanf() - フォーマット文字列に基づき入力を処理する


文字列の先頭バイトを、0 から 255 までの値に変換する

  • ≪ number_format
  • parse_str ≫
  • PHP Manual
  • String 関数
  • 文字列の先頭バイトを、0 から 255 までの値に変換する

ord

(PHP 4, PHP 5, PHP 7, PHP 8)

ord — 文字列の先頭バイトを、0 から 255 までの値に変換する

説明

ord(string $character): int

character の先頭バイトのバイナリ値を、 0 から 255 までの符号なしの整数値として解釈します。

string が ASCII, ISO-8859, Windows 1252 のような シングルバイトエンコーディング だった場合、 これは文字セットのマッピングテーブルにある文字の位置を返すことと同義です。 しかし、この関数は string のエンコーディングについて知りませんし、 特に UTF-8 や UTF-16 のようなマルチバイトエンコーディングについては、 この関数からは Unicode のコードポイントは絶対にわからないことに注意してください。

この関数は chr() と逆の動作をします。

パラメータ

character

文字列。

戻り値

0 から 255 までの整数値を返します。

例

例1 ord() の例

<?php
$str = "\n";
if (ord($str) == 10) {
echo "\$str の先頭は改行文字です。\n";
}
?>

例2 UTF-8 の文字列をバイト単位で調べる

<?php
declare(encoding='UTF-8');
$str = "??";
for ( $pos=0; $pos < strlen($str); $pos ++ ) {
$byte = substr($str, $pos);
echo 'Byte ' . $pos . ' of $str has value ' . ord($byte) . PHP_EOL;
}
?>

上の例の出力は以下となります。

Byte 0 of $str has value 240
Byte 1 of $str has value 159
Byte 2 of $str has value 144
Byte 3 of $str has value 152

参考

  • chr() - 数値から、1バイトの文字列を生成する
  • » ASCII 値の表
  • IntlChar::ord() - 文字に対応する Unicode コードポイントを返す


文字列を処理し、変数に代入する

  • ≪ ord
  • print ≫
  • PHP Manual
  • String 関数
  • 文字列を処理し、変数に代入する

parse_str

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_str — 文字列を処理し、変数に代入する

説明

parse_str(string $string, array &$result): void

URL 経由で渡されるクエリ文字列と同様に string を処理し、現在のスコープに変数をセットします。 (result が指定された場合は、配列 result にセットします)

パラメータ

string

入力文字列。

result

2 番目の引数 result が指定された場合、 変数は、代わりに配列の要素としてこの変数に保存されます。

警告

この関数を result パラメータを指定せずに使うことは 絶対に おすすめしません し、 PHP 7.2 以降では 推奨されません。 PHP 8.0.0 以降では、result パラメータの指定が 必須 になっています。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | result は、オプションではなくなりました。
7.2.0 | parse_str()関数を 第二引数を指定せずに使うと E_DEPRECATED レベルの警告が発生するようになりました。

例

例1 parse_str() の使用法

<?php
$str = "first=value&arr[]=foo+bar&arr[]=baz";

// 推奨
parse_str($str, $output);
echo $output['first']; // value
echo $output['arr'][0]; // foo bar
echo $output['arr'][1]; // baz

// お勧めできない
parse_str($str);
echo $first; // value
echo $arr[0]; // foo bar
echo $arr[1]; // baz
?>

PHP における変数は、名前にドットやスペースを許容しないので、 そういった値はアンダースコアに変換されます。同じことは、 この関数に result パラメータを指定した 場合の、配列のキーの名前にも当てはまります。

例2 parse_str() name mangling

<?php
parse_str("My Value=Something");
echo $My_Value; // Something

parse_str("My Value=Something", $output);
echo $output['My_Value']; // Something
?>

注意

注意:

全ての作成された変数 (第二引数が設定された場合は配列に設定される値) の値は、既に urldecode() されています。

注意:

現在の QUERY_STRING を取得するには、変数 $_SERVER['QUERY_STRING'] を使用する事ができます。また、 外部から来る変数 のセクションも読んでください。

参考

  • parse_url() - URL を解釈し、その構成要素を返す
  • pathinfo() - ファイルパスに関する情報を返す
  • http_build_query() - URL エンコードされたクエリ文字列を生成する
  • urldecode() - URL エンコードされた文字列をデコードする


文字列を出力する

  • ≪ parse_str
  • printf ≫
  • PHP Manual
  • String 関数
  • 文字列を出力する

print

(PHP 4, PHP 5, PHP 7, PHP 8)

print — 文字列を出力する

説明

print(string $expression): int

expression を出力します。

printは実際には関数ではなく、 言語構造です。 引数は、print の後に文字列として評価される式を指定し、括弧で括る必要はありません。

echo との主な違いは、 print が単一の引数のみ受け付け、常に 1 を返すことです。

パラメータ

expression

出力する文字列として評価される式。 文字列として評価できない値は、 強制的に文字列に変換されます。 これは、 strict_types ディレクティブ が有効になっていても同じです。

戻り値

常に 1 を返します。

例

例1 print の例

<?php
print "print に括弧は不要です";

// 改行やスペースは付加されません; 以下は、"helloworld" を一行で出力します
print "hello";
print "world";

print "This string spans
multiple lines. The newlines will be
output as well";

print "This string spans\nmultiple lines. The newlines will be\noutput as well.";

// 引数は文字列を生成するあらゆる式を指定することができます。
$foo = "example";
print "foo is $foo"; // foo is example

$fruits = ["lemon", "orange", "banana"];
print implode(" and ", $fruits); // lemon and orange and banana

// 文字列でない値は、文字列に強制されます。たとえ declare(strict_types=1) が使われていても同じです。
print 6 * 7; // 42

// print は戻り値があるため、式の中で使うことができます。
// 以下は "hello world" を出力します。
if ( print "hello" ) {
echo " world";
}

// 以下は "true" を出力します。
( 1 === 1 ) ? print 'true' : print 'false';
?>

注意

注意: 括弧を使う

printの引数を括弧で囲んで渡しても文法エラーにはなりませんが、 通常の関数コールのような文法に見えてしまいます。 しかし、これは誤解を招く恐れがあります。 なぜなら、括弧は実際には出力を構成する式の一部であり、 print の文法の一部ではないからです。

<?php
print "hello";
// "hello" を出力します。

print("hello");
// 同じく"hello" を出力します。なぜなら ("hello") は正しい式だからです。

print(1 + 2) * 3;
// "9" を出力します; 括弧によって 1+2 が先に評価され、3*3がその次に評価されます。
// print 文は、式の評価結果全体をひとつの引数とみなします。

if ( print("hello") && false ) {
print " - inside if";
}
else {
print " - inside else";
}
// " - inside if" を出力します。
// ("hello") && false という式が最初に評価され、
// 評価された false が空文字列 "" に強制的に変換され、print に渡され、1を返します。
// よって、if ブロックの内部のコードが実行されます。
?>

print を大きな式で使う場合、 意図した結果を得るためには、キーワードと引数を括弧で囲む必要があるかもしれません:

<?php
if ( (print "hello") && false ) {
print " - inside if";
}
else {
print " - inside else";
}
// "hello - inside else" を出力します。
// 直前の例と異なり、(print "hello") が最初に評価され、
// "hello" を出力した後、print が1を返します。
// 1 && false は false なので、else ブロックの中身が実行されます。

print "hello " && print "world";
// "world1"; を出力します。print "world" が先に評価され、
// "hello " && 1 が次に評価され、左辺の print に渡されます。

(print "hello ") && (print "world");
// "hello world" を出力します; 括弧が print を && より前に評価させているからです。
?>

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

参考

  • echo - 1 つ以上の文字列を出力する
  • printf() - フォーマット済みの文字列を出力する
  • flush() - システム出力バッファをフラッシュする
  • 文字列リテラルの指定方法


フォーマット済みの文字列を出力する

  • ≪ print
  • quoted_printable_decode ≫
  • PHP Manual
  • String 関数
  • フォーマット済みの文字列を出力する

printf

(PHP 4, PHP 5, PHP 7, PHP 8)

printf — フォーマット済みの文字列を出力する

説明

printf(string $format, mixed ...$values): int

format にしたがって、出力を生成します。

パラメータ

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 * を指定します。 * を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

Precision

ピリオド . の後に数値を続けるか、 * を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g, G, h, H 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 * を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は整数として扱われ、2進数値として表現されます。
c | 引数は整数として扱われ、ASCII文字として表現されます。
d | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は整数として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は整数として扱われ、符号なし10進数値として表現されます。
x | 引数は整数として扱われ、16進数値(小文字)として表現されます。
X | 引数は整数として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
int | d, u, c, o, x, X, b
float | e, E, f, F, g, G, h, H

values

戻り値

出力した文字列の長さを返します。

エラー / 例外

  PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ArgumentCountError がスローされます。 これより前のバージョンでは、代わりに false を返し、E_WARNING を発生させていました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ArgumentCountError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

例

例1 printf(): の様々な例

<?php
$n = 43951789;
$u = -43951789;
$c = 65; // ASCII の 65番目は 'A'

// %% は、リテラル '%' 文字を出力することに注意
printf("%%b = '%b'\n", $n); // バイナリ表現
printf("%%c = '%c'\n", $c); // ASCII 文字を出力。chr() 関数と同じ
printf("%%d = '%d'\n", $n); // 標準的な整数表現
printf("%%e = '%e'\n", $n); // 科学的記法
printf("%%u = '%u'\n", $n); // 正の整数の符号なし整数表現
printf("%%u = '%u'\n", $u); // 負の整数の符号なし整数表現
printf("%%f = '%f'\n", $n); // 浮動小数点表現
printf("%%o = '%o'\n", $n); // 8進数表現
printf("%%s = '%s'\n", $n); // 文字列表現
printf("%%x = '%x'\n", $n); // 16進数の表現(小文字)
printf("%%X = '%X'\n", $n); // 16進数の表現(大文字)

printf("%%+d = '%+d'\n", $n); // 正の整数値の符号
printf("%%+d = '%+d'\n", $u); // 負の整数値の符号
?>

上の例の出力は以下となります。

%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'

例2 printf(): 文字列の指定子

<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n", $s); // 通常の文字列出力
printf("[%10s]\n", $s); // スペースで右寄せにする
printf("[%-10s]\n", $s); // スペースで左寄せにする
printf("[%010s]\n", $s); // ゼロ埋めは文字列でも機能します
printf("[%'#10s]\n", $s); // '#' 文字を使ったカスタムの文字埋め
printf("[%'#*s]\n", 10, $s); // 追加の引数を指定し、文字埋めの幅を指定
printf("[%10.9s]\n", $t); // 右寄せ。但し8文字で切り捨て
printf("[%-10.9s]\n", $t); // 左寄せ。但し8文字で切り捨て
?>

上の例の出力は以下となります。

[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[####monkey]
[ many monk]
[many monk ]

参考

  • print - 文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • fprintf() - フォーマットされた文字列をストリームに書き込む
  • vprintf() - フォーマットされた文字列を出力する
  • vsprintf() - フォーマットされた文字列を返す
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する
  • flush() - システム出力バッファをフラッシュする


quoted-printable 文字列を 8 ビット文字列に変換する

  • ≪ printf
  • quoted_printable_encode ≫
  • PHP Manual
  • String 関数
  • quoted-printable 文字列を 8 ビット文字列に変換する

quoted_printable_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

quoted_printable_decode — quoted-printable 文字列を 8 ビット文字列に変換する

説明

quoted_printable_decode(string $string): string

この関数は、quoted printable 文字列をデコードし、 8 ビットバイナリ文字列を返します (» RFC2821 の section 4.5.2 ではなく » RFC2045 の section 6.7 によれば、付随するピリオドは行の開始から削除されません) 。

この関数は imap_qprint() に似ていますが、 動作に IMAP モジュールを必要としないという違いがあります。

パラメータ

string

入力文字列。

戻り値

8 ビットバイナリ文字列を返します。

例

例1 quoted_printable_decode() の例

<?php
$encoded = quoted_printable_encode('Mochten Sie ein paar Apfel?');
var_dump($encoded);
var_dump(quoted_printable_decode($encoded));
?>

上の例の出力は以下となります。

string(37) "M=C3=B6chten Sie ein paar =C3=84pfel?"
string(29) "Mochten Sie ein paar Apfel?"

参考

  • quoted_printable_encode() - 8 ビット文字列を quoted-printable 文字列に変換する


8 ビット文字列を quoted-printable 文字列に変換する

  • ≪ quoted_printable_decode
  • quotemeta ≫
  • PHP Manual
  • String 関数
  • 8 ビット文字列を quoted-printable 文字列に変換する

quoted_printable_encode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

quoted_printable_encode — 8 ビット文字列を quoted-printable 文字列に変換する

説明

quoted_printable_encode(string $string): string

» RFC2045 の section 6.7 に従って作成した quoted printable 文字列を返します。

この関数は imap_8bit() に似ていますが、 動作に IMAP モジュールを必要としないという違いがあります。

パラメータ

string

入力文字列。

戻り値

エンコードされた文字列を返します。

例

例1 quoted_printable_encode() の例

<?php

$encoded = quoted_printable_encode('Mochten Sie ein paar Apfel?');

var_dump($encoded);
var_dump(quoted_printable_decode($encoded));
?>

上の例の出力は以下となります。

string(37) "M=C3=B6chten Sie ein paar =C3=84pfel?"
string(29) "Mochten Sie ein paar Apfel?"

参考

  • quoted_printable_decode() - quoted-printable 文字列を 8 ビット文字列に変換する


メタ文字をクォートする

  • ≪ quoted_printable_encode
  • rtrim ≫
  • PHP Manual
  • String 関数
  • メタ文字をクォートする

quotemeta

(PHP 4, PHP 5, PHP 7, PHP 8)

quotemeta — メタ文字をクォートする

説明

quotemeta(string $string): string

文字列 str について、

. \ + * ? [ ^ ] ( $ )
の前にバックスラッシュ文字 (\) でクォートして返します。

パラメータ

string

入力文字列。

戻り値

メタ文字をクォートした文字列を返します。 空文字を string に渡した場合は false を返します。

例

例1 quotemeta() の例

<?php

var_dump(quotemeta('PHP is a popular scripting language. Fast, flexible, and pragmatic.'));
?>

上の例の出力は以下となります。

string(69) "PHP is a popular scripting language\. Fast, flexible, and pragmatic\."

注意

注意: この関数はバイナリデータに対応しています。

参考

  • addslashes() - 文字列をスラッシュでクォートする
  • addcslashes() - C 言語と同様にスラッシュで文字列をクォートする
  • htmlentities() - 適用可能な文字を全て HTML エンティティに変換する
  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する
  • nl2br() - 改行文字の前に HTML の改行タグを挿入する
  • stripslashes() - クォートされた文字列のクォート部分を取り除く
  • stripcslashes() - addcslashes でクォートされた文字列をアンクォートする
  • preg_quote() - 正規表現文字をクオートする


文字列の最後から空白 (もしくはその他の文字) を取り除く

  • ≪ quotemeta
  • setlocale ≫
  • PHP Manual
  • String 関数
  • 文字列の最後から空白 (もしくはその他の文字) を取り除く

rtrim

(PHP 4, PHP 5, PHP 7, PHP 8)

rtrim — 文字列の最後から空白 (もしくはその他の文字) を取り除く

説明

rtrim(string $string, string $characters = " \n\r\t\v\x00"): string

この関数は文字列 string の最後から空白文字 (あるいはその他の文字) を取り除き、 取り除かれた文字列を返します。

2 番目のパラメータを指定しない場合、 rtrim() は以下の文字を削除します。

  • " " (ASCII 32 (0x20)), 通常の空白。
  • "\t" (ASCII 9 (0x09)), タブ。
  • "\n" (ASCII 10 (0x0A)), 改行。
  • "\r" (ASCII 13 (0x0D)), 復帰。
  • "\0" (ASCII 0 (0x00)), NULL バイト。
  • "\v" (ASCII 11 (0x0B)), 垂直タブ。

パラメータ

string

入力文字列。

characters

characters パラメータにより、 削除する文字を指定することも可能です。 削除したい全ての文字をリストにしてください。.. を文字の範囲を指定する際に使用可能です。

戻り値

変更後の文字列を返します。

例

例1 rtrim() の使用例

<?php

$text = "\t\tThese are a few words :) ... ";
$binary = "\x09Example string\x0A";
$hello = "Hello World";
var_dump($text, $binary, $hello);

print "\n";

$trimmed = rtrim($text);
var_dump($trimmed);

$trimmed = rtrim($text, " \t.");
var_dump($trimmed);

$trimmed = rtrim($hello, "Hdle");
var_dump($trimmed);

// ASCII 制御文字 (0 から 31 まで) を
// $binary の末尾から取り除きます
$clean = rtrim($binary, "\x00..\x1F");
var_dump($clean);

?>

上の例の出力は以下となります。

string(32) "        These are a few words :) ...  "
string(16) "    Example string
"
string(11) "Hello World"

string(30) "        These are a few words :) ..."
string(26) "        These are a few words :)"
string(9) "Hello Wor"
string(15) "    Example string"

参考

  • trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • ltrim() - 文字列の最初から空白 (もしくはその他の文字) を取り除く


ロケール情報を設定する

  • ≪ rtrim
  • sha1 ≫
  • PHP Manual
  • String 関数
  • ロケール情報を設定する

setlocale

(PHP 4, PHP 5, PHP 7, PHP 8)

setlocale — ロケール情報を設定する

説明

setlocale(int $category, string $locales, string ...$rest): string|false

代替のシグネチャ (名前付き引数をサポートしていません):

setlocale(int $category, array $locale_array): string|false

ロケール情報を設定します。

警告

ロケール情報は、スレッド毎ではなくプロセス毎に維持されます。 もし PHP を マルチスレッドサーバーAPI 上で動作させている場合、 スクリプトを実行している間にロケールの設定が突然変わるのを 経験するかも知れませんが、スクリプト自身は決して setlocale() 自身をコールしていません。 これは同時に同一プロセスの異なるスレッドで実行されている他のスクリプトが setlocale() を使用してプロセスワイドなロケールを変更する事により発生します。 Windows では、PHP 7.0.5 以降、 ロケール情報はスレッド単位で維持されるようになっています。

パラメータ

category

categoryは、名前付きの定数(または文字列)であり、 ロケール設定により影響を受ける関数のカテゴリを指定します。

  • LC_ALL 以下のものすべて
  • LC_COLLATE 文字列の比較用。strcoll() も参照
  • LC_CTYPE 文字の分類と変換。たとえば ctype_alpha()
  • LC_MONETARY localeconv() 用
  • LC_NUMERIC 数字の区切り文字用(localeconv() も参照ください)
  • LC_TIME 日時。strftime()でフォーマットに使用
  • LC_MESSAGES システムの応答用(PHP が libintl とともにコンパイルされている場合のみ使用可能)

locales

localesが空の文字列 "" の場合、ロケール名は上記のカテゴリと同じ名前の環境変数の値、 または環境変数 "LANG" からセットされます。

locales が "0" の場合、 ロケール設定は適用されず、単に現在の設定が返されます。

locales に追加のパラメータが続く場合、 それぞれのパラメータは成功するまで新規ロケールとしてセットされます。 これは、ロケールが異なるシステムで異なる名前を持っている、 もしくはロケールが利用できない場合のフォールバックを提供するといった場合に有用です。

rest

オプションの文字列。ロケール設定が成功するまで設定を試みます。

locale_array

それぞれの配列の要素が、 新しいロケールとして設定が成功するまで設定を試みます。 これは、異なるシステムでロケールが違う名前として認識されたり、 ロケールが利用できない可能性がある場合にフォールバックさせる目的で使うと便利です。

注意:

Windows では、setlocale(LC_ALL, '') を使用するとシステムの 地域と言語の設定の値を使用します (コントロールパネルで確認できます)。

戻り値

現在の新しいロケールを返します。ロケール機能が未実装、 指定されたロケールが存在しない、カテゴリ名が無効などの場合は false を返します。

また、カテゴリ名が無効の場合は警告メッセージが発生します。 カテゴリやロケール名は、 » RFC 1766 や » ISO 639 にあります。 ロケールの命名方式は、システムによって異なります。

注意:

setlocale() の戻り値は、 PHP が実行されているシステムに依存します。 システムの setlocale 関数が返す値を返すためです。

例

例1 setlocale() の例

<?php
/* ロケールをオランダ語に設定 */
setlocale(LC_ALL, 'nl_NL');

/* 出力: vrijdag 22 december 1978 */
echo strftime("%A %e %B %Y", mktime(0, 0, 0, 12, 22, 1978));

/* ドイツに対して利用可能な異なるロケール名を使用する */
$loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'de', 'ge');
echo "Preferred locale for german on this system is '$loc_de'";
?>

例2 Windows での setlocale() の例

<?php
/* ロケールをオランダ語に設定 */
setlocale(LC_ALL, 'nld_nld');

/* 出力: vrijdag 22 december 1978 */
echo strftime("%A %d %B %Y", mktime(0, 0, 0, 12, 22, 1978));

/* ドイツに対して利用可能な異なるロケール名を使用する */
$loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'deu_deu');
echo "Preferred locale for german on this system is '$loc_de'";
?>

注意

ヒント

Windows ユーザーは Microsoft の MSDN の Web サイトに locales 文字列に関する有用な情報を見つけることができるでしょう。 サポートしている言語文字列は » 言語文字列のドキュメント、 そしてサポートしている国/地域文字列は » 国/地域文字列のドキュメント にあります。


文字列の sha1 ハッシュを計算する

  • ≪ setlocale
  • sha1_file ≫
  • PHP Manual
  • String 関数
  • 文字列の sha1 ハッシュを計算する

sha1

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

sha1 — 文字列の sha1 ハッシュを計算する

警告

パスワードを守るためにこの関数を使うことはおすすめしません。 ハッシュアルゴリズムの高速性がその理由です。 詳細とベストプラクティスについては、パスワードハッシュ FAQを参照ください。

説明

sha1(string $string, bool $binary = false): string

» US Secure Hash Algorithm 1 を使用して string の sha1 ハッシュを計算します。

パラメータ

string

入力文字列。

binary

オプションの binary に true が指定された場合、sha1 ダイジェストは 20 バイト長のバイナリ形式で返されます。 それ以外の場合は、戻り値は 40 文字の 16 進数となります。

戻り値

sha1 ハッシュを文字列で返します。

例

例1 sha1() の例

<?php
$str = 'apple';

if (sha1($str) === 'd0be2dc421be4fcd0172e5afceea3970e2f3d940') {
echo "Would you like a green or red apple?";
}
?>

参考

  • hash() - ハッシュ値 (メッセージダイジェスト) を生成する
  • password_hash() - パスワードハッシュを作る


ファイルの sha1 ハッシュを計算する

  • ≪ sha1
  • similar_text ≫
  • PHP Manual
  • String 関数
  • ファイルの sha1 ハッシュを計算する

sha1_file

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

sha1_file — ファイルの sha1 ハッシュを計算する

説明

sha1_file(string $filename, bool $binary = false): string|false

» US Secure Hash Algorithm 1 を使用して filename の sha1 ハッシュを計算し、そのハッシュを 返します。ハッシュは 40 文字の 16 進数となります。

パラメータ

filename

ハッシュしたいファイルのファイル名。

binary

true を指定すると、長さ 20 のバイナリフォーマットで ダイジェストを返します。

戻り値

成功した場合に文字列、それ以外の場合に false を返します。

例

例1 sha1_file() の例

<?php
foreach(glob('/home/Kalle/myproject/*.php') as $ent)
{
if(is_dir($ent))
{
continue;
}

echo $ent . ' (SHA1: ' . sha1_file($ent) . ')', PHP_EOL;
}
?>

参考

  • hash_file() - ファイルの内容から、ハッシュ値を生成する
  • hash_init() - 段階的なハッシュコンテキストを初期化する
  • sha1() - 文字列の sha1 ハッシュを計算する


二つの文字列の間の類似性を計算する

  • ≪ sha1_file
  • soundex ≫
  • PHP Manual
  • String 関数
  • 二つの文字列の間の類似性を計算する

similar_text

(PHP 4, PHP 5, PHP 7, PHP 8)

similar_text — 二つの文字列の間の類似性を計算する

説明

similar_text(string $string1, string $string2, float &$percent = null): int

この関数は、Programming Classics: Implementing the World's Best Algorithms by Oliver (ISBN 0-131-00413-1) に記述されたように二つの文字列の間の類似性を計算します。 この実装は Oliver の擬似コードの様にスタックを使用せず、 プロセス全体の速度が改善されるかどうかにかかわらず再帰呼び出しを行うことに注意してください。 このアルゴリズムの計算量は、O(N**3) であることにも注意してください。 ただし、N は最も長い文字列の長さです。

パラメータ

string1

最初の文字列。

string2

次の文字列。

注意:

string1 と string2 を入れ替えると、 結果は異なるものになります; 例を参照ください。

percent

3 番目の引数としてリファレンスを渡すことにより、 similar_text() は類似性をパーセントで計算します。 これは、similar_text() の結果を、 与えられた文字列の長さの平均を 100 倍した値で割ることで出しています。

戻り値

両方の文字列でマッチした文字の数を返します。

マッチする文字数は、 最初の共通最長部分文字列を探し、 同じことをその文字列の 前後の文字列に対して再帰的に行うことで計算されます。 そうして見つかった全ての共通部分文字列の長さが追加されます。

例

例1 similar_text() で、引数を入れ替えた場合の例

以下のコードは、 string1 と string2 を入れ替えると、異なる結果になる可能性を示しています。

<?php
$sim = similar_text('bafoobar', 'barfoo', $perc);
echo "類似度: $sim ($perc %)\n";
$sim = similar_text('barfoo', 'bafoobar', $perc);
echo "類似度: $sim ($perc %)\n";

上の例の出力は、 たとえば以下のようになります。

類似度: 5 (71.428571428571 %)
類似度: 3 (42.857142857143 %)

参考

  • levenshtein() - 二つの文字列のレーベンシュタイン距離を計算する
  • soundex() - 文字列の soundex キーを計算する


文字列の soundex キーを計算する

  • ≪ similar_text
  • sprintf ≫
  • PHP Manual
  • String 関数
  • 文字列の soundex キーを計算する

soundex

(PHP 4, PHP 5, PHP 7, PHP 8)

soundex — 文字列の soundex キーを計算する

説明

soundex(string $string): string

string の soundex キーを計算します。

soundex キーには、似たような発音の単語に関して同じ soundex キーが生成されるという特性があります。 このため、発音は知っているが、スペルがわからない場合に、 データベースを検索することを容易にすることができます。

この soundex 関数についての説明は、Donald Knuth の "The Art Of Computer Programming, vol. 3: Sorting And Searching", Addison-Wesley (1973), pp. 391-392 にあります。

パラメータ

string

入力文字列。

戻り値

soundex キーを、4文字からなる文字列で返します。 少なくとも1文字が string に含まれていた場合、 返される文字列はその文字から始まります。 そうでない場合、"0000" を返します。

変更履歴

バージョン | 説明
8.0.0 | これより前のバージョンでは、 空文字列をこの関数に渡すと、特別な理由がないのに false を返していました。

例

例1 Soundex の例

<?php
soundex("Euler") == soundex("Ellery"); // E460
soundex("Gauss") == soundex("Ghosh"); // G200
soundex("Hilbert") == soundex("Heilbronn"); // H416
soundex("Knuth") == soundex("Kant"); // K530
soundex("Lloyd") == soundex("Ladd"); // L300
soundex("Lukasiewicz") == soundex("Lissajous"); // L222
?>

参考

  • levenshtein() - 二つの文字列のレーベンシュタイン距離を計算する
  • metaphone() - 文字列の metaphone キーを計算する
  • similar_text() - 二つの文字列の間の類似性を計算する


フォーマットされた文字列を返す

  • ≪ soundex
  • sscanf ≫
  • PHP Manual
  • String 関数
  • フォーマットされた文字列を返す

sprintf

(PHP 4, PHP 5, PHP 7, PHP 8)

sprintf — フォーマットされた文字列を返す

説明

sprintf(string $format, mixed ...$values): string

フォーマット文字列 format に基づき生成された文字列を返します。

パラメータ

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 * を指定します。 * を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

Precision

ピリオド . の後に数値を続けるか、 * を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g, G, h, H 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 * を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は整数として扱われ、2進数値として表現されます。
c | 引数は整数として扱われ、ASCII文字として表現されます。
d | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は整数として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は整数として扱われ、符号なし10進数値として表現されます。
x | 引数は整数として扱われ、16進数値(小文字)として表現されます。
X | 引数は整数として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
int | d, u, c, o, x, X, b
float | e, E, f, F, g, G, h, H

values

戻り値

フォーマット文字列 format に基づき生成された文字列を返します。

エラー / 例外

  PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ArgumentCountError がスローされます。 これより前のバージョンでは、代わりに false を返し、E_WARNING を発生させていました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ArgumentCountError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

例

例1 引数の交換

フォーマット文字列における引数の 番号付け/交換 をサポートしています。以下に例を示します。

<?php
$num = 5;
$location = 'tree';

$format = 'There are %d monkeys in the %s';
echo sprintf($format, $num, $location);
?>

上の例の出力は以下となります。

There are 5 monkeys in the tree

ここで、フォーマット文字列が別のファイルにある場合を考えてみましょう。 これは、出力を国際化したりする場合に行われる可能性があります。 たとえばフォーマット文字列が次のように書き換えられたとすると、

<?php
$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>

ここで、問題が発生します。フォーマット文字列における置換指示子の順番は、 コードにおける引数の順番と一致していません。 だからといってコードを変更するのではなく、 むしろ置換指示子が参照するフォーマット文字列のほうで指示を行う方が望ましいでしょう。 フォーマット文字列を次のように書き換えてみましょう。

<?php
$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>

こうすることによるもうひとつの利点は、 同じ置換指示子を複数回使用する際にコードに引数を追加せずにすむことです。 例えば、次のようになります。

<?php
$format = 'The %2$s contains %1$d monkeys.
That\'s a nice %2$s full of %1$d monkeys.';
echo sprintf($format, $num, $location);
?>

引数の交換を使うときには、 位置指定子 n$ をパーセント記号 (%) の直後に置かなければならず、 間に他の指定を入れてはいけません。次の例を示します。

例2 埋める文字を指定する

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>

上の例の出力は以下となります。

......123
000000123

例3 位置指定子と他の指定との共用

<?php
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>

上の例の出力は以下となります。

The tree contains 0005 monkeys

例4 sprintf(): ゼロ埋めされた数値

<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>

例5 sprintf(): 通貨フォーマット

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money;
echo "\n";
$formatted = sprintf("%01.2f", $money);
echo $formatted;
?>

上の例の出力は以下となります。

123.1
123.10

例6 sprintf(): 科学的記法

<?php
$number = 362525200;

echo sprintf("%.3e", $number);
?>

上の例の出力は以下となります。

3.625e+8

参考

  • printf() - フォーマット済みの文字列を出力する
  • fprintf() - フォーマットされた文字列をストリームに書き込む
  • vprintf() - フォーマットされた文字列を出力する
  • vsprintf() - フォーマットされた文字列を返す
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する


フォーマット文字列に基づき入力を処理する

  • ≪ sprintf
  • str_contains ≫
  • PHP Manual
  • String 関数
  • フォーマット文字列に基づき入力を処理する

sscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

sscanf — フォーマット文字列に基づき入力を処理する

説明

sscanf(string $string, string $format, mixed &...$vars): array|int|null

関数 sscanf() は、printf() の入力版です。sscanf() は、文字列 string を読み込み、これを指定したフォーマット format に基づき解釈します。

フォーマット文字列の中のあらゆる空白文字は、入力文字列の中の 空白文字列にマッチします。つまり、フォーマット文字列の中にタブ文字 (\t) が含まれていても、 それは入力中の半角スペースにマッチしてしまうということです。

パラメータ

string

入力文字列。

format

string を解釈するフォーマット。 sprintf() のドキュメントにある説明と比べて、以下の違いがあります。

  • ロケールに対応していません。
  • F、g、G および b はサポートしていません。
  • D は十進数値を表します。
  • i は基数検出つきの整数値を表します。
  • n は処理する文字数を表します。
  • s は、空白文字を読み取ると停止することを示します。
  • argnum$ の代わりに * を指定すると、 この変換仕様に従った値の代入を抑制します。

vars

オプションで指定する参照渡しの変数に、 パースされた値が格納されます。

戻り値

この関数のパラメータが二つだけの場合、処理された値は配列として返されます。 それ以外の場合は、もしオプションのパラメータが渡されればこの関数は 割り当てられた値の数を返します。オプションのパラメータは 参照渡しにする必要があります。

format で期待する部分文字列のほうが 実際に string に存在するものより多い場合は null を返します。

例

例1 sscanf() の例

<?php
// シリアル番号を得る
list($serial) = sscanf("SN/2350001", "SN/%d");
// 続いて製造日を得る
$mandate = "January 01 2000";
list($month, $day, $year) = sscanf($mandate, "%s %d %d");
echo "Item $serial was manufactured on: $year-" . substr($month, 0, 3) . "-$day\n";
?>

オプションのパラメータが指定された場合、この関数は、代入された値の数を返します。

例2 sscanf() - オプションパラメータの使用法

<?php
// author 情報を取得し、DocBook エントリを生成
$auth = "24\tLewis Carroll";
$n = sscanf($auth, "%d\t%s %s", $id, $first, $last);
echo "<author id='$id'>
<firstname>$first</firstname>
<surname>$last</surname>
</author>\n";
?>

参考

  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • fprintf() - フォーマットされた文字列をストリームに書き込む
  • vprintf() - フォーマットされた文字列を出力する
  • vsprintf() - フォーマットされた文字列を返す
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する


指定された部分文字列が、文字列に含まれるかを調べる

  • ≪ sscanf
  • str_decrement ≫
  • PHP Manual
  • String 関数
  • 指定された部分文字列が、文字列に含まれるかを調べる

str_contains

(PHP 8)

str_contains — 指定された部分文字列が、文字列に含まれるかを調べる

説明

str_contains(string $haystack, string $needle): bool

needle が haystack に含まれるかを調べます。 大文字小文字は区別されます。

パラメータ

haystack

検索対象の文字列

needle

haystack で調べる部分文字列

戻り値

haystack に needle が含まれていた場合 true そうでない場合、false を返します。

例

例1 空文字列 '' を使った場合

<?php
if (str_contains('abc', '')) {
echo "Checking the existence of the empty string will always return true";
}
?>

上の例の出力は以下となります。

Checking the existence of the empty string will always return true

例2 大文字小文字の区別

<?php
$string = 'The lazy fox jumped over the fence';

if (str_contains($string, 'lazy')) {
echo "The string 'lazy' was found in the string\n";
}

if (str_contains($string, 'Lazy')) {
echo 'The string "Lazy" was found in the string';
} else {
echo '"Lazy" was not found because the case does not match';
}

?>

上の例の出力は以下となります。

The string 'lazy' was found in the string
"Lazy" was not found because the case does not match

注意

注意: この関数はバイナリデータに対応しています。

参考

  • str_ends_with() - 文字列が、指定された文字列で終わるかを調べる。
  • str_starts_with() - 文字列が指定された部分文字列で始まるかを調べる
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strstr() - 文字列が最初に現れる位置を見つける
  • strpbrk() - 文字列の中から任意の文字を探す
  • substr() - 文字列の一部分を返す
  • preg_match() - 正規表現によるマッチングを行う


英数字からなる文字列をデクリメントする

  • ≪ str_contains
  • str_ends_with ≫
  • PHP Manual
  • String 関数
  • 英数字からなる文字列をデクリメントする

str_decrement

(PHP 8 >= 8.3.0)

str_decrement — 英数字からなる文字列をデクリメントする

説明

str_decrement(string $string): string

英数字からなる ASCII 文字列 string をデクリメントし、結果の文字列を返します。

パラメータ

string

入力文字列。

戻り値

デクリメント済みの、英数字からなる ASCII 文字列を返します。

エラー / 例外

string が空の場合、 ValueError がスローされます。

string が、英数字からなる ASCII 文字列でない場合、ValueError がスローされます。

string がデクリメントできない場合、ValueError がスローされます。たとえば、"A" や "0" の場合です。

例

例1 str_decrement() の基本的な使い方

<?php
$str = 'ABC';
var_dump(str_decrement($str));
?>

上の例の出力は以下となります。

string(3) "ABB"

例2 繰り下がりがある、str_decrement() の例

<?php
$str = 'ZA';
var_dump(str_decrement($str));

$str = 'AA';
var_dump(str_decrement($str));
?>

上の例の出力は以下となります。

string(2) "YZ"
string(1) "Z"

参考

  • str_increment() - 英数字からなる文字列をインクリメントする


文字列が、指定された文字列で終わるかを調べる。

  • ≪ str_decrement
  • str_getcsv ≫
  • PHP Manual
  • String 関数
  • 文字列が、指定された文字列で終わるかを調べる。

str_ends_with

(PHP 8)

str_ends_with — 文字列が、指定された文字列で終わるかを調べる。

説明

str_ends_with(string $haystack, string $needle): bool

haystack が needle で終わるかを調べます。 大文字小文字は区別されます。

パラメータ

haystack

検索対象の文字列。

needle

haystack で調べる部分文字列

戻り値

haystack が needle で終わる場合、true を返します。 そうでない場合、false を返します。

例

例1 空文字列 '' を使う場合

<?php
if (str_ends_with('abc', '')) {
echo "All strings end with the empty string";
}
?>

上の例の出力は以下となります。

All strings end with the empty string

例2 大文字小文字の区別

<?php
$string = 'The lazy fox jumped over the fence';

if (str_ends_with($string, 'fence')) {
echo "The string ends with 'fence'\n";
}

if (str_ends_with($string, 'Fence')) {
echo 'The string ends with "Fence"';
} else {
echo '"Fence" was not found because the case does not match';
}

?>

上の例の出力は以下となります。

The string ends with 'fence'
"Fence" was not found because the case does not match

注意

注意: この関数はバイナリデータに対応しています。

参考

  • str_contains() - 指定された部分文字列が、文字列に含まれるかを調べる
  • str_starts_with() - 文字列が指定された部分文字列で始まるかを調べる
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strstr() - 文字列が最初に現れる位置を見つける
  • strpbrk() - 文字列の中から任意の文字を探す
  • substr() - 文字列の一部分を返す
  • preg_match() - 正規表現によるマッチングを行う


CSV 文字列をパースして配列に格納する

  • ≪ str_ends_with
  • str_increment ≫
  • PHP Manual
  • String 関数
  • CSV 文字列をパースして配列に格納する

str_getcsv

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

str_getcsv — CSV 文字列をパースして配列に格納する

説明

str_getcsv(
string $string,
string $separator = ",",
string $enclosure = "\"",
string $escape = "\\"
): array

CSV 形式の文字列入力のフィールドをパースして、 読み込んだフィールドの内容を配列で返します。

注意:

この関数はロケール設定を考慮します。もし LC_CTYPE が例えば en_US.UTF-8 の場合、 1 バイトエンコーディングの文字列は間違って読み込まれるかもしれません。

パラメータ

string

パースする文字列。

separator

フィールド区切り文字 (シングルバイト文字 1 文字のみ)。

enclosure

フィールド囲み文字 (シングルバイト文字 1 文字のみ)。

escape

エスケープ文字 (シングルバイト文字 最大1文字)。デフォルトはバックスラッシュ (\)。 空文字列 ("") を指定すると、 (RFC 4180 に準拠していない) 独自仕様のエスケープ機構を無効にします。

注意: 通常、 enclosure の文字は、 フィールドの中では二回出力されることでエスケープされます。 しかし、escape の文字を代わりに使うこともできます。 よって、デフォルト値 "" および \" は同じ意味になります。 enclosure 文字をエスケープすることを許可する以外に、 escape 文字は特別な意味を何ら持ちません; つまり、自分自身をエスケープすることすら意味しません。

戻り値

読み込んだフィールドの内容を配列で返します。

変更履歴

バージョン | 説明
7.4.0 | escape 引数は、 空文字列を、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構を無効にするシグナルとして解釈するようになりました。 これより前のバージョンでは、空文字列はデフォルト値のように扱われていました。

例

例1 str_getcsv() の例

<?php

$string = 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string);

var_dump($data);
?>

上の例の出力は以下となります。

array(5) {
  [0]=>
  string(3) "PHP"
  [1]=>
  string(4) "Java"
  [2]=>
  string(6) "Python"
  [3]=>
  string(6) "Kotlin"
  [4]=>
  string(5) "Swift"
}

例2 str_getcsv() に空文字列を指定した例

警告

この関数に空文字列を指定すると、 空の配列ではなく 値 [null] を返します。

<?php

$string = '';
$data = str_getcsv($string);

var_dump($data);
?>

上の例の出力は以下となります。

array(1) {
  [0]=>
  NULL
}

参考

  • fgetcsv() - ファイルポインタから行を取得し、CSVフィールドを処理する


英数字からなる文字列をインクリメントする

  • ≪ str_getcsv
  • str_ireplace ≫
  • PHP Manual
  • String 関数
  • 英数字からなる文字列をインクリメントする

str_increment

(PHP 8 >= 8.3.0)

str_increment — 英数字からなる文字列をインクリメントする

説明

str_increment(string $string): string

英数字からなる ASCII 文字列 string をインクリメントし、結果の文字列を返します。

パラメータ

string

入力文字列。

戻り値

インクリメント済みの、英数字からなる ASCII 文字列を返します。

エラー / 例外

string が空の場合、 ValueError がスローされます。

string が、英数字からなる ASCII 文字列でない場合、ValueError がスローされます。

例

例1 str_increment() の基本的な使い方

<?php
$str = 'ABC';
var_dump(str_increment($str));
?>

上の例の出力は以下となります。

string(3) "ABD"

例2 繰り上げがある、str_increment() の例

<?php
$str = 'DZ';
var_dump(str_increment($str));

$str = 'ZZ';
var_dump(str_increment($str));
?>

上の例の出力は以下となります。

string(2) "EA"
string(3) "AAA"

参考

  • str_decrement() - 英数字からなる文字列をデクリメントする


大文字小文字を区別しない str_replace

  • ≪ str_increment
  • str_pad ≫
  • PHP Manual
  • String 関数
  • 大文字小文字を区別しない str_replace

str_ireplace

(PHP 5, PHP 7, PHP 8)

str_ireplace — 大文字小文字を区別しない str_replace()

説明

str_ireplace(
array|string $search,
array|string $replace,
string|array $subject,
int &$count = null
): string|array

この関数は、subject の中に現れるすべての search(大文字小文字を区別しない)を replace に置き換えた文字列あるいは配列を返します。

固定の文字列ではなく、パターンベースでテキストを置換したい場合、 preg_replace() 関数を パターン修飾子 i と一緒に使ってください。

パラメータ

search および replace が配列の場合は、 str_ireplace() はそれぞれの配列から取り出した 値を使用して subject の置換を行います。 replace の要素数が search より少ない場合は、残りの要素は 空の文字列に置き換えられます。もし search が配列で replace が文字列だった場合は すべての search が同じ文字列に置き換えられます。 しかし、逆は意味がありません。

search あるいは replace が配列の場合は、配列の最初の要素から順に処理されます。

search

探したい値。needle (針) と呼ばれることもあります。 配列を使えば、複数の値を指定することもできます。

replace

見つかった search を置き換える値。 配列を使えば、複数の値を指定することもできます。

subject

検索・置換の対象となる文字列あるいは配列。 haystack (干し草の山) と呼ばれることもあります。

subject が配列の場合は、そのすべての要素に 対して検索と置換が行われ、返される結果も配列となります。

count

指定した場合は、マッチして置換が行われた箇所の個数がここに格納されます。

戻り値

置換した文字列あるいは配列を返します。

変更履歴

バージョン | 説明
8.2.0 | ケースフォールディングは、setlocale() で設定されたロケールに依存しなくなりました。 ASCII のケースフォールディングのみが行われます。 ASCII でないバイト列は、バイト値として比較されます。

例

例1 str_ireplace() の例

<?php
$bodytag = str_ireplace("%body%", "black", "<body text=%BODY%>");
echo $bodytag; // <body text=black>
?>

注意

注意: この関数はバイナリデータに対応しています。

警告

置換の順番に関するメモ

str_ireplace() は左から右へと置換を行うので、 複数の置換を行うときには、前に追加された値を置換する可能性もあります。 str_replace() のドキュメントにある 2 番目の例が、これが及ぼす影響の実例です。

参考

  • str_replace() - 検索文字列に一致したすべての文字列を置換する
  • preg_replace() - 正規表現検索および置換を行う
  • strtr() - 文字の変換あるいは部分文字列の置換を行う


文字列を固定長の他の文字列で埋める

  • ≪ str_ireplace
  • str_repeat ≫
  • PHP Manual
  • String 関数
  • 文字列を固定長の他の文字列で埋める

str_pad

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

str_pad — 文字列を固定長の他の文字列で埋める

説明

str_pad(
string $string,
int $length,
string $pad_string = " ",
int $pad_type = STR_PAD_RIGHT
): string

この関数は文字列 string の左、右または両側を指定した長さで埋めます。オプションの引数 pad_string が指定されていない場合は、 string は空白で埋められ、それ以外の場合は、 pad_string からの文字で制限まで埋められます。

パラメータ

string

入力文字列。

length

埋めた結果としての、最終的な文字列の長さ。 length の値が負、 または入力文字列の長さ以下である場合、埋める操作は行われません。 string をそのまま返します。

pad_string

注意:

必要とされる埋める文字数が pad_string の長さで均等に分割できない場合、pad_string は切り捨てられます。

pad_type

オプションの引数 pad_type には、 STR_PAD_RIGHT, STR_PAD_LEFT, STR_PAD_BOTH を指定可能です。 pad_typeが指定されない場合、 STR_PAD_RIGHT を仮定します。

戻り値

埋めた後の文字列を返します。

例

例1 str_pad() の例

<?php
$input = "Alien";
echo str_pad($input, 10); // 結果は "Alien "
echo str_pad($input, 10, "-=", STR_PAD_LEFT); // 結果は "-=-=-Alien"
echo str_pad($input, 10, "_", STR_PAD_BOTH); // 結果は "__Alien___"
echo str_pad($input, 6, "___"); // 結果は "Alien_"
echo str_pad($input, 3, "*"); // 結果は "Alien"
?>

参考

  • mb_str_pad() - マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める


文字列を反復する

  • ≪ str_pad
  • str_replace ≫
  • PHP Manual
  • String 関数
  • 文字列を反復する

str_repeat

(PHP 4, PHP 5, PHP 7, PHP 8)

str_repeat — 文字列を反復する

説明

str_repeat(string $string, int $times): string

string を times 回を繰り返した文字列を返します。

パラメータ

string

繰り返す文字列。

times

string を繰り返す回数。

times は 0 以上でなければなりません。 times が 0 に設定された場合、この関数は空文字を返します。

戻り値

繰り返した文字列を返します。

例

例1 str_repeat() の例

<?php
echo str_repeat("-=", 10);
?>

上の例の出力は以下となります。

-=-=-=-=-=-=-=-=-=-=

参考

  • for
  • str_pad() - 文字列を固定長の他の文字列で埋める
  • substr_count() - 副文字列の出現回数を数える


検索文字列に一致したすべての文字列を置換する

  • ≪ str_repeat
  • str_rot13 ≫
  • PHP Manual
  • String 関数
  • 検索文字列に一致したすべての文字列を置換する

str_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

str_replace — 検索文字列に一致したすべての文字列を置換する

説明

str_replace(
array|string $search,
array|string $replace,
string|array $subject,
int &$count = null
): string|array

この関数は、subject の中の search を全て replace に置換します。

固定の文字列ではなく、パターンベースでテキストを置換したい場合、 preg_replace() を使ってください。

パラメータ

search と replace が配列の場合、str_replace() は各配列から値をひとつ取り出し、 subject 上で検索と置換を行うために使用します。 replace の値が search よりも少ない場合、 置換される値の残りの部分には空の文字列が使用されます。 search が配列で replace が文字列の場合、この置換文字列が search の各値について使用されます。しかし、 逆は意味がありません。

search あるいは replace が配列の場合は、配列の最初の要素から順に処理されます。

search

探したい値。needle (針) と呼ばれることもあります。 配列を使えば、複数の値を指定することもできます。

replace

見つかった search を置き換える値。 配列を使えば、複数の値を指定することもできます。

subject

検索・置換の対象となる文字列あるいは配列。 haystack (干し草の山) と呼ばれることもあります。

subject が配列の場合、 subject の各エントリについて検索と置換が行われ、 戻り値は同様に配列となります。

count

指定した場合は、マッチして置換が行われた箇所の個数がここに格納されます。

戻り値

この関数は、置換後の文字列あるいは配列を返します。

例

例1 基本的な str_replace() の例

<?php
// <body text='black'> となります
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");

// Hll Wrld f PHP となります
$vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
$onlyconsonants = str_replace($vowels, "", "Hello World of PHP");

// You should eat pizza, beer, and ice cream every day となります
$phrase = "You should eat fruits, vegetables, and fiber every day.";
$healthy = array("fruits", "vegetables", "fiber");
$yummy = array("pizza", "beer", "ice cream");

$newphrase = str_replace($healthy, $yummy, $phrase);

// 2 となります
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count;
?>

例2 str_replace() に関するちょっとした事実

<?php
// 置換の順番を指定します
$str = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
$order = array("\r\n", "\n", "\r");
$replace = '<br />';

// まず最初に \r\n を置換するので、二重に変換されることはありません
$newstr = str_replace($order, $replace, $str);

// 出力は F となります。A が B に、そして B が C に、そして......
// 最終的に E が F に置換されるからです。置換は左から右へと順に行われます
$search = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject);

// 出力は apearpearle pear となります
// 上で説明したのと同じ理由です
$letters = array('a', 'p');
$fruit = array('apple', 'pear');
$text = 'a p';
$output = str_replace($letters, $fruit, $text);
echo $output;
?>

注意

注意: この関数はバイナリデータに対応しています。

警告

置換の順番に関するメモ

str_replace() は左から右へと置換を行うので、 複数の置換を行うときには、前に追加された値を置換する可能性もあります。 このドキュメントのサンプルを参照ください。

注意:

この関数は大文字小文字を区別します。区別せずに置換するには str_ireplace() を使用します。

参考

  • str_ireplace() - 大文字小文字を区別しない str_replace
  • substr_replace() - 文字列の一部を置換する
  • preg_replace() - 正規表現検索および置換を行う
  • strtr() - 文字の変換あるいは部分文字列の置換を行う


文字列に rot13 変換を行う

  • ≪ str_replace
  • str_shuffle ≫
  • PHP Manual
  • String 関数
  • 文字列に rot13 変換を行う

str_rot13

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

str_rot13 — 文字列に rot13 変換を行う

説明

str_rot13(string $string): string

引数 string に対して ROT13 変換を施し、 その結果の文字列を返します。

ROT13 は、各文字をアルファベット順に 13 文字シフトさせ、 アルファベット以外の文字はそのままとするエンコードを行います。 エンコードとデコードは同じ関数で行われます。 引数にエンコードされた文字列を指定した場合には、元の文字列が返されます。

パラメータ

string

入力文字列。

戻り値

指定した文字列を ROT13 変換した結果を返します。

例

例1 str_rot13() の例

<?php

echo str_rot13('PHP 4.3.0'); // CUC 4.3.0

?>


文字列をランダムにシャッフルする

  • ≪ str_rot13
  • str_split ≫
  • PHP Manual
  • String 関数
  • 文字列をランダムにシャッフルする

str_shuffle

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

str_shuffle — 文字列をランダムにシャッフルする

説明

str_shuffle(string $string): string

str_shuffle() は文字列をシャッフルします。 考えられるすべての順列のうちのひとつを作成します。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

string

入力文字列。

戻り値

シャッフルされた文字列を返します。

変更履歴

バージョン | 説明
7.1.0 | 内部的なランダム化アルゴリズムは、 libc の rand 関数ではなく、 » メルセンヌツイスタ 乱数生成器を使うように 変更されました

例

例1 str_shuffle() の例

<?php
$str = 'abcdef';
$shuffled = str_shuffle($str);

// bfdaec のような文字列を返します
echo $shuffled;
?>

参考

  • Random\Randomizer::shuffleBytes() - 指定された文字列の、バイト単位の順列を取得する
  • Random\Randomizer::shuffleArray() - 配列の順列を取得する


文字列を配列に変換する

  • ≪ str_shuffle
  • str_starts_with ≫
  • PHP Manual
  • String 関数
  • 文字列を配列に変換する

str_split

(PHP 5, PHP 7, PHP 8)

str_split — 文字列を配列に変換する

説明

str_split(string $string, int $length = 1): array

文字列を配列に変換します。

パラメータ

string

入力文字列。

length

分割した部分の最大長。

戻り値

オプションのパラメータ length が指定されている場合、 返される配列の各要素は、length の長さとなります。但し、平等に分割できない場合、 最後の要素だけはその長さより短くなります。 デフォルトでは、 length の値は 1 です。 つまり、 1バイトずつ分割された配列となります。

エラー / 例外

length が1より小さい場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.2.0 | string が空の場合、 空の配列が返されるようになりました。 これより前のバージョンでは、空文字列がひとつ入った配列が返されていました。
8.0.0 | length が1より小さい場合、 ValueError がスローされるようになりました。 それより前のバージョンでは、 E_WARNING レベルの警告が発生し、 false を返していました。

例

例1 str_split() の使用例

<?php

$str = "Hello Friend";

$arr1 = str_split($str);
$arr2 = str_split($str, 3);

print_r($arr1);
print_r($arr2);

?>

上の例の出力は以下となります。

Array
(
    [0] => H
    [1] => e
    [2] => l
    [3] => l
    [4] => o
    [5] =>
    [6] => F
    [7] => r
    [8] => i
    [9] => e
    [10] => n
    [11] => d
)

Array
(
    [0] => Hel
    [1] => lo
    [2] => Fri
    [3] => end
)

注意

注意:

str_split() でのマルチバイト文字列の扱いは、文字単位ではなくバイト単位での分割になります。 コードポイント単位で文字列を分割するには、 mb_str_split() を使います。

参考

  • mb_str_split() - マルチバイト文字列を受取り、文字の配列を返す
  • chunk_split() - 文字列をより小さな部分に分割する
  • preg_split() - 正規表現で文字列を分割する
  • explode() - 文字列を文字列により分割する
  • count_chars() - 文字列で使用されている文字に関する情報を返す
  • str_word_count() - 文字列に使用されている単語についての情報を返す
  • for


文字列が指定された部分文字列で始まるかを調べる

  • ≪ str_split
  • str_word_count ≫
  • PHP Manual
  • String 関数
  • 文字列が指定された部分文字列で始まるかを調べる

str_starts_with

(PHP 8)

str_starts_with — 文字列が指定された部分文字列で始まるかを調べる

説明

str_starts_with(string $haystack, string $needle): bool

haystack が needle で始まるかを調べます。 大文字小文字は区別されます。

パラメータ

haystack

検索対象の文字列

needle

haystack で調べる部分文字列

戻り値

haystack が needle で始まる場合、 true を返します。そうでない場合、false を返します。

例

例1 空文字列 '' を使う場合

<?php
if (str_starts_with('abc', '')) {
echo "All strings start with the empty string";
}
?>

上の例の出力は以下となります。

All strings start with the empty string

例2 大文字小文字の区別

<?php
$string = 'The lazy fox jumped over the fence';

if (str_starts_with($string, 'The')) {
echo "The string starts with 'The'\n";
}

if (str_starts_with($string, 'the')) {
echo 'The string starts with "the"';
} else {
echo '"the" was not found because the case does not match';
}

?>

上の例の出力は以下となります。

The string starts with 'The'
"the" was not found because the case does not match

注意

注意: この関数はバイナリデータに対応しています。

参考

  • str_contains() - 指定された部分文字列が、文字列に含まれるかを調べる
  • str_ends_with() - 文字列が、指定された文字列で終わるかを調べる。
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strstr() - 文字列が最初に現れる位置を見つける
  • strpbrk() - 文字列の中から任意の文字を探す
  • substr() - 文字列の一部分を返す
  • preg_match() - 正規表現によるマッチングを行う


文字列に使用されている単語についての情報を返す

  • ≪ str_starts_with
  • strcasecmp ≫
  • PHP Manual
  • String 関数
  • 文字列に使用されている単語についての情報を返す

str_word_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

str_word_count — 文字列に使用されている単語についての情報を返す

説明

str_word_count(string $string, int $format = 0, ?string $characters = null): array|int

string に含まれる単語数を数えます。 オプションの format が指定されていない場合、 見つかった単語の数を整数値で返します。 format が指定されている場合は結果が配列で返され、 配列の内容は format に依存します。 format に設定できる値と対応する出力については 以下で示します。

この関数を使用するうえで、'単語' は「ロケールに依存したアルファベットから なる文字列で、その先頭以外の部分に "'" および "-" を含 めることができる」ものと定義されています。 マルチバイト文字列を使うロケールはサポートされていないので、注意が必要です。

パラメータ

string

文字列。

format

この関数の戻り値を設定します。現在サポートされている値は 以下のとおりです。

  • 0 - 見つかった単語の数を返します。
  • 1 - string の中に見つかった単語を含む 配列を返します。
  • 2 - 連想配列を返します。string の中での 単語の開始位置がキー、単語自体を対応する値となります。

characters

'単語' とみなされる文字に追加する文字のリスト。

戻り値

選択した format に応じて、配列あるいは整数を返します。

変更履歴

バージョン | 説明
8.0.0 | characters は、nullable になりました。

例

例1 str_word_count() の例

<?php

$str = "Hello fri3nd, you're
looking good today!";

print_r(str_word_count($str, 1));
print_r(str_word_count($str, 2));
print_r(str_word_count($str, 1, 'aaac3'));

echo str_word_count($str);

?>

上の例の出力は以下となります。

Array
(
    [0] => Hello
    [1] => fri
    [2] => nd
    [3] => you're
    [4] => looking
    [5] => good
    [6] => today
)

Array
(
    [0] => Hello
    [6] => fri
    [10] => nd
    [14] => you're
    [29] => looking
    [46] => good
    [51] => today
)

Array
(
    [0] => Hello
    [1] => fri3nd
    [2] => you're
    [3] => looking
    [4] => good
    [5] => today
)

7

参考

  • explode() - 文字列を文字列により分割する
  • preg_split() - 正規表現で文字列を分割する
  • count_chars() - 文字列で使用されている文字に関する情報を返す
  • substr_count() - 副文字列の出現回数を数える


大文字小文字を区別しないバイナリセーフな文字列比較を行う

  • ≪ str_word_count
  • strchr ≫
  • PHP Manual
  • String 関数
  • 大文字小文字を区別しないバイナリセーフな文字列比較を行う

strcasecmp

(PHP 4, PHP 5, PHP 7, PHP 8)

strcasecmp — 大文字小文字を区別しないバイナリセーフな文字列比較を行う

説明

strcasecmp(string $string1, string $string2): int

大文字小文字を区別しないバイナリセーフな文字列比較を行います。 ここで行う比較は、ロケールを考慮しません。 つまり、ASCII文字だけが、大文字小文字を区別せず比較されます。

パラメータ

string1

最初の文字列。

string2

次の文字列。

戻り値

string1 が string2 より小さい場合は -1、string1 が string2 より大きい場合は 1、等しい場合は 0 を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。

例

例1 strcasecmp() の例

<?php
$var1 = "Hello";
$var2 = "hello";
if (strcasecmp($var1, $var2) == 0) {
echo '$var1 is equal to $var2 in a case-insensitive string comparison';
}
?>

参考

  • strcmp() - バイナリセーフな文字列比較
  • preg_match() - 正規表現によるマッチングを行う
  • substr_compare() - 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
  • strncasecmp() - バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • stristr() - 大文字小文字を区別しない strstr
  • substr() - 文字列の一部分を返す


strstr のエイリアス

  • ≪ strcasecmp
  • strcmp ≫
  • PHP Manual
  • String 関数
  • strstr のエイリアス

strchr

(PHP 4, PHP 5, PHP 7, PHP 8)

strchr — strstr() のエイリアス

説明

この関数は次の関数のエイリアスです。 strstr().


バイナリセーフな文字列比較

  • ≪ strchr
  • strcoll ≫
  • PHP Manual
  • String 関数
  • バイナリセーフな文字列比較

strcmp

(PHP 4, PHP 5, PHP 7, PHP 8)

strcmp — バイナリセーフな文字列比較

説明

strcmp(string $string1, string $string2): int

この比較は大文字小文字を区別することに注意してください。

パラメータ

string1

最初の文字列。

string2

次の文字列。

戻り値

string1 が string2 よりも小さければ -1 を、string1が string2よりも大きければ 1 を、 等しければ 0 を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。

例

例1 strcmp() の例

<?php
$var1 = "Hello";
$var2 = "hello";
if (strcmp($var1, $var2) !== 0) {
echo '$var1 is not equal to $var2 in a case sensitive string comparison';
}
?>

参考

  • strcasecmp() - 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • preg_match() - 正規表現によるマッチングを行う
  • substr_compare() - 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
  • strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う
  • strstr() - 文字列が最初に現れる位置を見つける
  • substr() - 文字列の一部分を返す


ロケールに基づく文字列比較

  • ≪ strcmp
  • strcspn ≫
  • PHP Manual
  • String 関数
  • ロケールに基づく文字列比較

strcoll

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

strcoll — ロケールに基づく文字列比較

説明

strcoll(string $string1, string $string2): int

この比較は大文字小文字を区別すること、そして、 strcmp() とは異なり、 バイナリセーフではないことに注意してください。

strcoll() は比較を行う際に現在のロケールを使用します。 ロケールが C または POSIX の場合、この関数は strcmp() と等価です。

パラメータ

string1

最初の文字列。

string2

次の文字列。

戻り値

string1 が string2 より小さい場合に 0 未満の値、string1 が string2 より大きい場合に 0 より大きな値、 両者が等しい場合に 0 を返します。

参考

  • preg_match() - 正規表現によるマッチングを行う
  • strcmp() - バイナリセーフな文字列比較
  • strcasecmp() - 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • substr() - 文字列の一部分を返す
  • stristr() - 大文字小文字を区別しない strstr
  • strncasecmp() - バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う
  • strstr() - 文字列が最初に現れる位置を見つける
  • setlocale() - ロケール情報を設定する


マスクにマッチしない最初のセグメントの長さを返す

  • ≪ strcoll
  • strip_tags ≫
  • PHP Manual
  • String 関数
  • マスクにマッチしない最初のセグメントの長さを返す

strcspn

(PHP 4, PHP 5, PHP 7, PHP 8)

strcspn — マスクにマッチしない最初のセグメントの長さを返す

説明

strcspn(
string $string,
string $characters,
int $offset = 0,
?int $length = null
): int

string において characters の文字がどれも含まれていない最初のセグメントの長さを返します。

offset と length を省略した場合は、string の全体を調べます。 これらのパラメータを指定した場合は、 strcspn(substr($string, $offset, $length), $characters) をコールするのと同じ動きになります。 (詳細は substr を参照ください)。

パラメータ

string

調べたい文字列。

characters

許可しない文字をすべて含む文字列。

offset

string の中で調べ始める位置。

offset に非負の値を指定した場合は、 strcspn() は、 string の offset 番目の文字から調べ始めます。 たとえば 'abcdef' という文字列があったとすると、 0 番目の文字が 'a' で 2 番目の文字は 'c' のようになります。

offset に負の値を指定した場合は、 strcspn() は、 string の後ろから offset 番目の文字から調べ始めます。

length

string の中での調べるセグメントの長さ。

length に非負の値を指定した場合は、 string の開始位置から length 文字ぶんだけ調べます。

length に負の値を指定した場合は、 string の開始位置から調べ始めて、 string の末尾から length 文字目のところまで調べます。

戻り値

string の中で、 characters の文字をまったく含まない 最初のセグメントの長さを返します。

注意:

offset を指定した場合は、その位置から長さを数え始めます。 string の先頭から数えるわけではありません。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 strcspn() の例

<?php
$a = strcspn('abcd', 'apple');
$b = strcspn('abcd', 'banana');
$c = strcspn('hello', 'l');
$d = strcspn('hello', 'world');
$e = strcspn('abcdhelloabcd', 'abcd', -9);
$f = strcspn('abcdhelloabcd', 'abcd', -9, -5);

var_dump($a);
var_dump($b);
var_dump($c);
var_dump($d);
var_dump($e);
var_dump($f);
?>

上の例の出力は以下となります。

int(0)
int(0)
int(2)
int(2)
int(5)
int(4)

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strspn() - 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す


文字列から HTML および PHP タグを取り除く

  • ≪ strcspn
  • stripcslashes ≫
  • PHP Manual
  • String 関数
  • 文字列から HTML および PHP タグを取り除く

strip_tags

(PHP 4, PHP 5, PHP 7, PHP 8)

strip_tags — 文字列から HTML および PHP タグを取り除く

説明

strip_tags(string $string, array|string|null $allowed_tags = null): string

この関数は、指定した文字列 (string) から全ての NULL バイトと HTML および PHP タグを取り除きます。 この関数は、fgetss() 関数と同じタグ除去アルゴリズムを使用します。

パラメータ

string

入力文字列。

allowed_tags

オプションの2番目の引数により、取り除かないタグを指定できます。 これは string で指定できますが、PHP 7.4.0 以降では array でも指定可能です。 この引数のフォーマットについては、以下の例を参照ください。

注意:

HTML コメントや PHP タグも削除されるようになりました。この機能はハードコードされており、 allowed_tags で変更することはできません。

注意:

allowed_tags で使えるのは自己終了型でない XHTML タグだけです。 自己終了型の XHTML タグは無視されます。たとえば、 <br> と <br/> の両方を許可したい場合は、以下のようにしなければいけません。

<?php
strip_tags($input, '<br>');
?>

戻り値

タグを除去した文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | allowed_tags は、nullable になりました。
7.4.0 | allowed_tags は、array も受け入れるようになりました。

例

例1 strip_tags() の例

<?php
$text = '<p>Test paragraph.</p><!-- Comment --> <a href="#fragment">Other text</a>';
echo strip_tags($text);
echo "\n";

// <p> と <a> は許可します
echo strip_tags($text, '<p><a>');

// PHP 7.4.0 以降では、上の行は以下のように書けます:
// echo strip_tags($text, ['p', 'a']);
?>

上の例の出力は以下となります。

Test paragraph. Other text
<p>Test paragraph.</p> <a href="#fragment">Other text</a>

注意

警告

XSS攻撃を防ぐ目的で、この関数を使うべきではありません。 htmlspecialchars() のような、より適切な関数、 もしくは、出力のコンテキストによっては他の手段を使うようにしてください。

警告

strip_tags() は HTML の検証を行わないため、 不完全または壊れたタグにより予想以上に多くのテキスト/データが削除される可能性があります。

警告

この関数は、allowed_tags で許可した全てのタグの属性を修正しません。 これには、style および onmouseover属性が含まれており、 悪意のあるユーザーが他のユーザーに見せるようなテキストを投稿する際に危険な行為を行う可能性があります。

注意:

HTML の中にあるタグの中で 1023 バイトより長い名前のものがあれば、 たとえ allowed_tags パラメータに指定していたとしても無効なタグと見なされます。

参考

  • htmlspecialchars() - 特殊文字を HTML エンティティに変換する


addcslashes でクォートされた文字列をアンクォートする

  • ≪ strip_tags
  • stripos ≫
  • PHP Manual
  • String 関数
  • addcslashes でクォートされた文字列をアンクォートする

stripcslashes

(PHP 4, PHP 5, PHP 7, PHP 8)

stripcslashes — addcslashes() でクォートされた文字列をアンクォートする

説明

stripcslashes(string $string): string

バックスラッシュを取り除いた文字列を返します。C言語と同様に \n, \r ..., 8進表現, 16進表現を認識します。

パラメータ

string

元に戻したい文字列。

戻り値

元に戻した文字列を返します。

例

例1 stripcslashes() の例

<?php

var_dump(stripcslashes('I\'d have a coffee.\nNot a problem.') === "I'd have a coffee.
Not a problem."); // true
?>

参考

  • addcslashes() - C 言語と同様にスラッシュで文字列をクォートする


大文字小文字を区別せずに文字列が最初に現れる位置を探す

  • ≪ stripcslashes
  • stripslashes ≫
  • PHP Manual
  • String 関数
  • 大文字小文字を区別せずに文字列が最初に現れる位置を探す

stripos

(PHP 5, PHP 7, PHP 8)

stripos — 大文字小文字を区別せずに文字列が最初に現れる位置を探す

説明

stripos(string $haystack, string $needle, int $offset = 0): int|false

文字列 haystack の中で needle が最初に現れる位置を探します。

strpos() と異なり、stripos() は大文字小文字を区別しません。

パラメータ

haystack

検索対象の文字列。

needle

検索する文字列。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

offset

指定すると、文字列内での検索開始位置がその位置になります。 負の数を指定すると、文字列の末尾からこの数だけ戻った場所から検索を開始します。

戻り値

needle が見つかった位置を、 haystack 文字列の先頭 (offset の値とは無関係) からの相対位置で返します。 文字列の開始位置は 0 であり、1 ではないことに注意しましょう。

needle が見つからない場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.2.0 | ケースフォールディングは、setlocale() で設定されたロケールに依存しなくなりました。 ASCII のケースフォールディングのみが行われます。 ASCII でないバイト列は、バイト値として比較されます。
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。
7.1.0 | 負の offset をサポートするようになりました。

例

例1 stripos() の例

<?php
$findme = 'a';
$mystring1 = 'xyz';
$mystring2 = 'ABC';

$pos1 = stripos($mystring1, $findme);
$pos2 = stripos($mystring2, $findme);

// いいえ、'a' は明らかに 'xyz' の中には存在しません
if ($pos1 === false) {
echo "The string '$findme' was not found in the string '$mystring1'";
}

// === を使用していることに注意しましょう。単に == としても期待通りに動作
// しません。なぜなら 'a' は 0 番目(最初) の文字だからです。
if ($pos2 !== false) {
echo "We found '$findme' in '$mystring2' at position $pos2";
}
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • mb_stripos() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
  • str_contains() - 指定された部分文字列が、文字列に含まれるかを調べる
  • str_ends_with() - 文字列が、指定された文字列で終わるかを調べる。
  • str_starts_with() - 文字列が指定された部分文字列で始まるかを調べる
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • stristr() - 大文字小文字を区別しない strstr
  • substr() - 文字列の一部分を返す
  • str_ireplace() - 大文字小文字を区別しない str_replace


クォートされた文字列のクォート部分を取り除く

  • ≪ stripos
  • stristr ≫
  • PHP Manual
  • String 関数
  • クォートされた文字列のクォート部分を取り除く

stripslashes

(PHP 4, PHP 5, PHP 7, PHP 8)

stripslashes — クォートされた文字列のクォート部分を取り除く

説明

stripslashes(string $string): string

クォートされた文字列を元に戻します。

stripslashes() は、 (データベースのような)エスケープする必要がある 場所にデータをまだ挿入していない場合に使うことができます。 例えば、単純に HTML フォームからのデータを直接出力するような場合です。

パラメータ

string

入力文字列。

戻り値

バックスラッシュが取り除かれた文字列を返します(\' が ' になるなど)。 2 つ並んだバックスラッシュ (\\) は 1 つのバックスラッシュ (\) になります。

例

例1 stripslashes() の例

<?php
$str = "Is your name O\'reilly?";

// 出力: Is your name O'reilly?
echo stripslashes($str);
?>

注意:

stripslashes() は再帰的な処理を行いません。 この関数を多次元配列に適用する場合は、 再帰的な関数を使用する必要があります。

例2 配列に対する stripslashes() の使用

<?php
function stripslashes_deep($value)
{
$value = is_array($value) ?
array_map('stripslashes_deep', $value) :
stripslashes($value);

return $value;
}

// 例
$array = array("f\\'oo", "b\\'ar", array("fo\\'o", "b\\'ar"));
$array = stripslashes_deep($array);

// 出力
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [0] => f'oo
    [1] => b'ar
    [2] => Array
        (
            [0] => fo'o
            [1] => b'ar
        )

)

参考

  • addslashes() - 文字列をスラッシュでクォートする
  • get_magic_quotes_gpc() - magic_quotes_gpc の現在の設定を得る


大文字小文字を区別しない strstr

  • ≪ stripslashes
  • strlen ≫
  • PHP Manual
  • String 関数
  • 大文字小文字を区別しない strstr

stristr

(PHP 4, PHP 5, PHP 7, PHP 8)

stristr — 大文字小文字を区別しない strstr()

説明

stristr(string $haystack, string $needle, bool $before_needle = false): string|false

haystack において needle が最初に見つかった位置を含めてそこから最後までを返します。

パラメータ

haystack

検索対象の文字列。

needle

検索する文字列。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

before_needle

true にすると、stristr() の戻り値は、haystack の中で最初に needle があらわれる箇所より前の部分となります (needle は含めません)。

needle および haystack は大文字小文字を区別せずに評価されます。

戻り値

マッチした部分文字列を返します。needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.2.0 | ケースフォールディングは、setlocale() で設定されたロケールに依存しなくなりました。 ASCII のケースフォールディングのみが行われます。 ASCII でないバイト列は、バイト値として比較されます。
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。

例

例1 stristr() の例

<?php
$email = 'USER@EXAMPLE.com';
echo stristr($email, 'e'); // 出力は ER@EXAMPLE.com となります
echo stristr($email, 'e', true); // 出力は US となります
?>

例2 文字列が見つかるかどうかをテストする

<?php
$string = 'Hello World!';
if(stristr($string, 'earth') === FALSE) {
echo '"earth" not found in string';
}
// 出力は "earth" not found in string となります
?>

例3 文字列以外の needle の指定

<?php
$string = 'APPLE';
echo stristr($string, 97); // 97 = 小文字の a
// 出力は APPLE となります
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strstr() - 文字列が最初に現れる位置を見つける
  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strpbrk() - 文字列の中から任意の文字を探す
  • preg_match() - 正規表現によるマッチングを行う


文字列の長さを得る

  • ≪ stristr
  • strnatcasecmp ≫
  • PHP Manual
  • String 関数
  • 文字列の長さを得る

strlen

(PHP 4, PHP 5, PHP 7, PHP 8)

strlen — 文字列の長さを得る

説明

strlen(string $string): int

与えられた string の長さを返します。

パラメータ

string

長さを調べる文字列。

戻り値

string の長さをバイト単位で返します。

例

例1 strlen() の例

<?php
$str = 'abcdef';
echo strlen($str); // 6

$str = ' ab cd ';
echo strlen($str); // 7
?>

注意

注意:

strlen() が返すのはバイト数であり、 文字数ではありません。

参考

  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える
  • grapheme_strlen() - 書記素単位で文字列の長さを取得する
  • iconv_strlen() - 文字列の文字数を返す
  • mb_strlen() - 文字列の長さを得る


"自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う

  • ≪ strlen
  • strnatcmp ≫
  • PHP Manual
  • String 関数
  • "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う

strnatcasecmp

(PHP 4, PHP 5, PHP 7, PHP 8)

strnatcasecmp — "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う

説明

strnatcasecmp(string $string1, string $string2): int

この関数は、人間が行うような手法でアルファベットまたは数字の 文字列の順序を比較するアルゴリズムを実装します。この関数の動作は、 strnatcmp() に似ていますが、 比較が大文字小文字を区別しない違いがあります。 詳細な情報については、Martin Pool の » 自然順文字列比較 のページを参照ください。

パラメータ

string1

最初の文字列。

string2

次の文字列。

戻り値

他の文字列比較関数と同様に、この関数は、 string1がstring2 より小さい場合に -1、string1が string2より大きい場合に 1、等しい場合に 0 を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。

例

例1 strnatcasecmp() の例

<?php

var_dump(strnatcasecmp('Apple', 'Banana'));
var_dump(strnatcasecmp('Banana', 'Apple'));
var_dump(strnatcasecmp('apple', 'Apple'));
?>

上の例の出力は以下となります。

int(-1)
int(1)
int(0)

参考

  • preg_match() - 正規表現によるマッチングを行う
  • strcmp() - バイナリセーフな文字列比較
  • strcasecmp() - 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • substr() - 文字列の一部分を返す
  • stristr() - 大文字小文字を区別しない strstr
  • strncasecmp() - バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う
  • strstr() - 文字列が最初に現れる位置を見つける
  • setlocale() - ロケール情報を設定する


"自然順"アルゴリズムにより文字列比較を行う

  • ≪ strnatcasecmp
  • strncasecmp ≫
  • PHP Manual
  • String 関数
  • "自然順"アルゴリズムにより文字列比較を行う

strnatcmp

(PHP 4, PHP 5, PHP 7, PHP 8)

strnatcmp — "自然順"アルゴリズムにより文字列比較を行う

説明

strnatcmp(string $string1, string $string2): int

この関数は、人間が行うような手法でアルファベットまたは数字の 文字列の順序を比較するアルゴリズムを実装します。この手法は、"自然順" と言われます。 この比較は、大文字小文字を区別することに注意してください。

パラメータ

string1

最初の文字列。

string2

次の文字列。

戻り値

他の文字列比較関数と同様に、この関数は、 string1 が string2 より小さいに場合に -1、string1 が string2 より大きい場合に 1、等しい場合に 0 を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。

例

このアルゴリズムと (strcmp() を使用した) 通常のコンピュータ文字列ソートの間の違いの例を次に示します。

<?php
$arr1 = $arr2 = array("img12.png", "img10.png", "img2.png", "img1.png");
echo "標準の文字列比較\n";
usort($arr1, "strcmp");
print_r($arr1);
echo "\n自然順での文字列比較\n";
usort($arr2, "strnatcmp");
print_r($arr2);
?>

上の例の出力は以下となります。

標準の文字列比較
Array
(
    [0] => img1.png
    [1] => img10.png
    [2] => img12.png
    [3] => img2.png
)

自然順での文字列比較
Array
(
    [0] => img1.png
    [1] => img2.png
    [2] => img10.png
    [3] => img12.png
)
詳細な情報については、Martin Pool の » 自然順文字列比較 のページを参照ください。

参考

  • preg_match() - 正規表現によるマッチングを行う
  • strcasecmp() - 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • substr() - 文字列の一部分を返す
  • stristr() - 大文字小文字を区別しない strstr
  • strcmp() - バイナリセーフな文字列比較
  • strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う
  • strncasecmp() - バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • strnatcasecmp() - "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う
  • strstr() - 文字列が最初に現れる位置を見つける
  • natsort() - "自然順"アルゴリズムで配列をソートする
  • natcasesort() - 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする


バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う

  • ≪ strnatcmp
  • strncmp ≫
  • PHP Manual
  • String 関数
  • バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う

strncasecmp

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

strncasecmp — バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う

説明

strncasecmp(string $string1, string $string2, int $length): int

この関数は、strcasecmp() に似ていますが、 各文字列から比較する文字数(の上限)(len) を指定できるという違いがあります。どちらかの文字列が lenより短い場合、その文字列の長さが比較時に使用されます。

パラメータ

string1

最初の文字列。

string2

次の文字列。

length

比較する文字列の長さ。

戻り値

string1 が string2 より短い場合に -1 を返し、string1 が string2 より大きい場合に 1、等しい場合に 0 を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。

例

例1 strncasecmp() の例

<?php

$var1 = 'Hello John';
$var2 = 'hello Doe';
if (strncasecmp($var1, $var2, 5) === 0) {
echo 'First 5 characters of $var1 and $var2 are equals in a case-insensitive string comparison';
}
?>

参考

  • strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う
  • preg_match() - 正規表現によるマッチングを行う
  • substr_compare() - 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
  • strcasecmp() - 大文字小文字を区別しないバイナリセーフな文字列比較を行う
  • stristr() - 大文字小文字を区別しない strstr
  • substr() - 文字列の一部分を返す


最初の n 文字についてバイナリセーフな文字列比較を行う

  • ≪ strncasecmp
  • strpbrk ≫
  • PHP Manual
  • String 関数
  • 最初の n 文字についてバイナリセーフな文字列比較を行う

strncmp

(PHP 4, PHP 5, PHP 7, PHP 8)

strncmp — 最初の n 文字についてバイナリセーフな文字列比較を行う

説明

strncmp(string $string1, string $string2, int $length): int

この関数は strcmp() に似ていますが、 各文字列から(最大)文字数(len) を比較に使用するところが異なります。

比較は大文字小文字を区別することに注意してください。

パラメータ

string1

最初の文字列。

string2

次の文字列。

length

比較する文字数。

戻り値

string1 が string2 より小さい場合に -1、string1 が string2 より大きい場合に 1、等しい場合に 0 を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。

例

例1 strncmp() の例

<?php

$var1 = 'Hello John';
$var2 = 'Hello Doe';
if (strncmp($var1, $var2, 5) === 0) {
echo 'First 5 characters of $var1 and $var2 are equals in a case-sensitive string comparison';
}
?>

参考

  • strncasecmp() - バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
  • preg_match() - 正規表現によるマッチングを行う
  • substr_compare() - 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
  • strcmp() - バイナリセーフな文字列比較
  • strstr() - 文字列が最初に現れる位置を見つける
  • substr() - 文字列の一部分を返す


文字列の中から任意の文字を探す

  • ≪ strncmp
  • strpos ≫
  • PHP Manual
  • String 関数
  • 文字列の中から任意の文字を探す

strpbrk

(PHP 5, PHP 7, PHP 8)

strpbrk — 文字列の中から任意の文字を探す

説明

strpbrk(string $string, string $characters): string|false

strpbrk() は、文字列 string から characters を探します。

パラメータ

string

characters を探す文字列。

characters

このパラメータは大文字小文字を区別します。

戻り値

見つかった文字から始まる文字列、あるいは見つからなかった場合に false を返します。

例

例1 strpbrk() の例

<?php

$text = 'This is a Simple text.';

// これは "is is a Simple text." を出力します。なぜなら 'i' が最初にマッチするからです。
echo strpbrk($text, 'mi');

// これは "Simple text." を出力します。なぜなら大文字小文字が区別されるからです。
echo strpbrk($text, 'S');
?>

参考

  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • strstr() - 文字列が最初に現れる位置を見つける
  • preg_match() - 正規表現によるマッチングを行う


文字列内の部分文字列が最初に現れる場所を見つける

  • ≪ strpbrk
  • strrchr ≫
  • PHP Manual
  • String 関数
  • 文字列内の部分文字列が最初に現れる場所を見つける

strpos

(PHP 4, PHP 5, PHP 7, PHP 8)

strpos — 文字列内の部分文字列が最初に現れる場所を見つける

説明

strpos(string $haystack, string $needle, int $offset = 0): int|false

文字列 haystack の中で、 needle が最初に現れる位置を探します。

パラメータ

haystack

検索対象の文字列。

needle

検索する文字列。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

offset

指定すると、文字列内での検索開始位置がその位置になります。 負の数を指定すると、文字列の末尾からこの数だけ戻った場所から検索を開始します。

戻り値

needle が見つかった位置を、 haystack 文字列の先頭 (offset の値とは無関係) からの相対位置で返します。 文字列の開始位置は 0 であり、1 ではないことに注意しましょう。

needle が見つからない場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。
7.1.0 | 負の offset をサポートするようになりました。

例

例1 === の使用

<?php
$mystring = 'abc';
$findme = 'a';
$pos = strpos($mystring, $findme);

// === を使用していることに注目しましょう。単純に == を使ったのでは
// 期待通りに動作しません。なぜなら 'a' が 0 番目 (最初) の文字だからです。
if ($pos === false) {
echo "文字列 '$findme' は、文字列 '$mystring' の中で見つかりませんでした";
} else {
echo "文字列 '$findme' が文字列 '$mystring' の中で見つかりました";
echo " 見つかった位置は $pos です";
}
?>

例2 !== の使用

<?php
$mystring = 'abc';
$findme = 'a';
$pos = strpos($mystring, $findme);

// !== 演算子も使用可能です。ここで != を使っても期待通りに動作しません。
// なぜなら 'a' が 0 番目の文字だからです。(0 != false) を評価すると
// false になってしまいます。
if ($pos !== false) {
echo "文字列 '$findme' が文字列 '$mystring' の中で見つかりました";
echo " 見つかった位置は $pos です";
} else {
echo "文字列 '$findme' は、文字列 '$mystring' の中で見つかりませんでした";
}
?>

例3 オフセットの使用

<?php
// オフセット以前の内容を無視して文字を探すこともできます。
$newstring = 'abcdef abcdef';
$pos = strpos($newstring, 'a', 1); // $pos は 0 ではなく 7 となります。
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • str_contains() - 指定された部分文字列が、文字列に含まれるかを調べる
  • str_ends_with() - 文字列が、指定された文字列で終わるかを調べる。
  • str_starts_with() - 文字列が指定された部分文字列で始まるかを調べる
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strstr() - 文字列が最初に現れる位置を見つける
  • strpbrk() - 文字列の中から任意の文字を探す
  • substr() - 文字列の一部分を返す
  • preg_match() - 正規表現によるマッチングを行う


文字列中に文字が最後に現れる場所を取得する

  • ≪ strpos
  • strrev ≫
  • PHP Manual
  • String 関数
  • 文字列中に文字が最後に現れる場所を取得する

strrchr

(PHP 4, PHP 5, PHP 7, PHP 8)

strrchr — 文字列中に文字が最後に現れる場所を取得する

説明

strrchr(string $haystack, string $needle, bool $before_needle = false): string|false

この関数は、文字列 haystack の中で needle が最後に現れた位置から、 haystack の終わりまでを返します。

パラメータ

haystack

検索対象の文字列。

needle

needle がひとつ以上の文字を含んでいる場合は、 最初のもののみが使われます。この動作は、 strstr() とは異なります。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

before_needle

true にすると、 haystack の中で 最後に needle が現れる箇所より前の部分を返します (needle は含めません)。

戻り値

この関数は、部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.3.0 | before_needle が追加されました。
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。

例

例1 strrchr() の例

<?php
$ext = strrchr('somefile.txt', '.');
echo "file extension: $ext \n";
$ext = $ext ? strtolower(substr($ext, 1)) : '';
echo "file extension: $ext";
?>

上の例の出力は、 たとえば以下のようになります。

file extension: .txt
file extension: txt

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strstr() - 文字列が最初に現れる位置を見つける
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す


文字列を逆順にする

  • ≪ strrchr
  • strripos ≫
  • PHP Manual
  • String 関数
  • 文字列を逆順にする

strrev

(PHP 4, PHP 5, PHP 7, PHP 8)

strrev — 文字列を逆順にする

説明

strrev(string $string): string

string を逆順にして返します。

パラメータ

string

逆順にしたい文字列。

戻り値

逆順にした文字列を返します。

例

例1 strrev() で文字列を逆順にする

<?php
echo strrev("Hello world!"); // 出力は "!dlrow olleH" となります
?>


文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す

  • ≪ strrev
  • strrpos ≫
  • PHP Manual
  • String 関数
  • 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す

strripos

(PHP 5, PHP 7, PHP 8)

strripos — 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す

説明

strripos(string $haystack, string $needle, int $offset = 0): int|false

文字列 haystack の中で、 needle が最後に現れる位置を探します。

strrpos() と異なり、strripos() は大文字小文字を区別しません。

パラメータ

haystack

検索対象の文字列。

needle

検索する文字列。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

offset

ゼロまたは正の値の場合、 haystack の 最初の offset バイトをスキップし、 左から右に検索が行われます。

負の値の場合、 haystack の 最後の offset バイトをスキップし、 右から左に検索が行われ、 needle が最初に現れる場所を探します。

注意:

この方が、最後の offset バイトより前にある、 最後の needle を効率的に探せます。

戻り値

needle が見つかった位置を、 haystack 文字列の先頭 (offset の値とは無関係) からの相対位置で返します。

注意: 文字列の開始位置は 0 であり、1 ではありません。

needle が見つからない場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.2.0 | ケースフォールディングは、setlocale() で設定されたロケールに依存しなくなりました。 ASCII のケースフォールディングのみが行われます。 ASCII でないバイト列は、バイト値として比較されます。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。

例

例1 単純な strripos() の例

<?php
$haystack = 'ababcd';
$needle = 'aB';

$pos = strripos($haystack, $needle);

if ($pos === false) {
echo "ごめんなさい、($needle) が ($haystack) の中に見つかりませんでした。";
} else {
echo "おめでとう!\n";
echo "($needle) が最後に ($haystack) に現れた位置は ($pos) です。";
}
?>

上の例の出力は以下となります。

おめでとう!
   (aB) が最後に (ababcd) に現れた位置は (2) です。

参考

  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • stristr() - 大文字小文字を区別しない strstr
  • substr() - 文字列の一部分を返す


文字列中に、ある部分文字列が最後に現れる場所を探す

  • ≪ strripos
  • strspn ≫
  • PHP Manual
  • String 関数
  • 文字列中に、ある部分文字列が最後に現れる場所を探す

strrpos

(PHP 4, PHP 5, PHP 7, PHP 8)

strrpos — 文字列中に、ある部分文字列が最後に現れる場所を探す

説明

strrpos(string $haystack, string $needle, int $offset = 0): int|false

文字列 haystack の中で、 needle が最後に現れる位置を探します。

パラメータ

haystack

検索対象の文字列。

needle

検索する文字列。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

offset

ゼロまたは正の値の場合、 haystack の 最初の offset バイトをスキップし、 左から右に検索が行われます。

負の値の場合、 haystack の 最初ではなく、最後から offset バイトの箇所より検索を開始します。 検索は右から左に行われ、 検索を開始した箇所から needle が最初に現れる場所を探します。

注意:

この方が、最後の offset バイト、またはそれより前にある 最後の needle を効率的に探せます。

戻り値

needle が見つかった位置を、 haystack 文字列の先頭 (offset の値とは無関係) からの相対位置で返します。

注意: 文字列の開始位置は 0 であり、1 ではありません。

needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。

例

例1 needle が haystack の中にあるかどうかの確認

"位置 0 に文字が見つかった" と "文字が見つからなかった" 場合の戻り値は混同しやすいです。この違いを見分ける方法を以下に示します。

<?php

$pos = strrpos($mystring, "b");
if ($pos === false) { // 注意: 等号が 3 つ並んでいます
// 見つからない...
}

?>

例2 オフセットつきの検索

<?php
$foo = "0123456789a123456789b123456789c";

// Looking for '0' from the 0th byte (from the beginning)
var_dump(strrpos($foo, '0', 0));

// Looking for '0' from the 1st byte (after byte "0")
var_dump(strrpos($foo, '0', 1));

// Looking for '7' from the 21th byte (after byte 20)
var_dump(strrpos($foo, '7', 20));

// Looking for '7' from the 29th byte (after byte 28)
var_dump(strrpos($foo, '7', 28));

// Looking for '7' right to left from the 5th byte from the end
var_dump(strrpos($foo, '7', -5));

// Looking for 'c' right to left from the 2nd byte from the end
var_dump(strrpos($foo, 'c', -2));

// Looking for '9c' right to left from the 2nd byte from the end
var_dump(strrpos($foo, '9c', -2));
?>

上の例の出力は以下となります。

int(0)
bool(false)
int(27)
bool(false)
int(17)
bool(false)
int(29)

参考

  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
  • strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • substr() - 文字列の一部分を返す


指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す

  • ≪ strrpos
  • strstr ≫
  • PHP Manual
  • String 関数
  • 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す

strspn

(PHP 4, PHP 5, PHP 7, PHP 8)

strspn — 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す

説明

strspn(
string $string,
string $characters,
int $offset = 0,
?int $length = null
): int

string の中で、 characters 内の文字だけを含む最初の部分の長さを返します。

offset と length を省略した場合は、string 全体を調べます。 指定した場合は、strspn(substr($string, $offset, $length), $characters) をコールするのと同じ動きになります。 (詳細は substr を参照ください)

たとえば、

<?php
$var = strspn("42 is the answer to the 128th question.", "1234567890");
?>
このコードは、$var に 2 を代入します。これは、 string の中で "1234567890" 内の文字だけで構成される 最初の部分が "42" であるためです。

パラメータ

string

調べたい文字列。

characters

許可する文字の一覧。

offset

string の中で調べ始める位置。

offset に非負の値を指定すると、 strspn() は string の offset 番目の位置から調査を始めます。 たとえば、文字列 'abcdef' において 0 番目の位置にある文字は 'a' で 2 番目の位置にある文字は 'c' のようになります。

offset に負の値を指定すると、 strspn() は string の最後から offset 番目の位置から調査を始めます。

length

string 内で調べる部分の長さ。

length に非負の値を指定すると、 string の開始位置から length 文字分の範囲を調査します。

length に負の値を指定すると、 string の調査範囲は 開始位置から始まって string の最後から length だけさかのぼったところまでとなります。

戻り値

string の中で、全て characters の中の文字からなる最初のセグメントの長さを返します。

注意:

offset パラメータを設定した場合は、返される長さはその位置からのものとなります。 string の先頭からの長さではありません。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 strspn() の例

<?php
// subjectの最初の文字がmaskのどの文字とも一致しません
var_dump(strspn("foo", "o"));

// subject のオフセット 1 から 2 文字を調べます
var_dump(strspn("foo", "o", 1, 2));

// subject のオフセット 1 から 1 文字を調べます
var_dump(strspn("foo", "o", 1, 1));
?>

上の例の出力は以下となります。

int(0)
int(2)
int(1)

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strcspn() - マスクにマッチしない最初のセグメントの長さを返す


文字列が最初に現れる位置を見つける

  • ≪ strspn
  • strtok ≫
  • PHP Manual
  • String 関数
  • 文字列が最初に現れる位置を見つける

strstr

(PHP 4, PHP 5, PHP 7, PHP 8)

strstr — 文字列が最初に現れる位置を見つける

説明

strstr(string $haystack, string $needle, bool $before_needle = false): string|false

haystack の中で needle が最初に現れる場所を含めてそこから文字列の終わりまでを返します。

注意:

この関数は大文字小文字を区別することに注意してください。 大文字小文字を区別しない検索を行う場合は、stristr() を使用してください。

注意:

もし特定の haystack に needle があるかどうかを調べるだけの場合、 より高速でメモリ消費も少ない strpos() を代わりに使用してください。

パラメータ

haystack

入力文字列。

needle

検索する文字列。

PHP 8.0.0 より前のバージョンでは、needle が文字列でない場合、 数値に変換され、文字の通常の値として扱われていました。 この振る舞いは PHP 7.3.0 以降では推奨されないので、 この機能を使用しないことを強く推奨します。 意図した動作に依存する場合、 needle を string に明示的にキャストするか、 明示的に chr() 関数を呼び出すべきでしょう。

before_needle

true にすると、strstr() の戻り値は、haystack の中で最初に needle があらわれる箇所より前の部分となります (needle は含めません)。

戻り値

部分文字列を返します。 needle が見つからない場合は false を返します。

変更履歴

バージョン | 説明
8.0.0 | needle は、空文字列を受け入れるようになりました。
8.0.0 | needle に数値を渡すことはサポートされなくなりました。
7.3.0 | needle に数値を渡すことは非推奨になりました。

例

例1 strstr() の例

<?php
$email = 'name@example.com';
$domain = strstr($email, '@');
echo $domain; // @example.com と表示します

$user = strstr($email, '@', true);
echo $user; // name と表示します
?>

参考

  • stristr() - 大文字小文字を区別しない strstr
  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • strpbrk() - 文字列の中から任意の文字を探す
  • preg_match() - 正規表現によるマッチングを行う


文字列をトークンに分割する

  • ≪ strstr
  • strtolower ≫
  • PHP Manual
  • String 関数
  • 文字列をトークンに分割する

strtok

(PHP 4, PHP 5, PHP 7, PHP 8)

strtok — 文字列をトークンに分割する

説明

strtok(string $string, string $token): string|false

代替のシグネチャ (名前付き引数をサポートしていません):

strtok(string $token): string|false

strtok() は文字列 (string) を 何らかの文字 token によって区切られている小さな文字列 (トークン) に分割します。 "This is an example string" のような文字列がある場合、 空白文字を token に指定することでこの文字列を個々の単語に分割することができます。

strtok は最初のコールの時のみ string 引数を使用することに注意してください。 strtok は、文字列のどこにいるのかの情報を保持しているため、 2回目以降のコールでは token のみが必要です。 最初からやりなおす場合や新しい文字列をトークンに分割する場合、 初期化するために再度 string 引数を指定して strtok をコールします。 文字列は、token の文字のどれかが見つかった場合はトークンに分割されます。

注意:

この関数は、explode() 関数に慣れている人が期待する動きとは、 ちょっと異なる振る舞いをします。 まず、token の ふたつ以上の連続する文字が文字列に含まれていた場合、 その連続する文字は、単一の区切り文字として扱われます。 また、文字列の最初と最後に存在する token は無視されてしまいます。 たとえば、文字列が ";aaa;;bbb;" の場合、 token に ";" を指定して strtok() を 連続してコールすると、 "aaa" と "bbb" を返し、最後に false を返します。 結果として、文字列はふたつにしか分割されません。 一方で explode(";", $string) は 5つの要素からなる配列を返します。

パラメータ

string

より小さい文字列 (トークン) に分割する文字列。

token

string を分割する際に使用する区切り文字。

戻り値

トークンを文字列で返します。 トークンがない場合は、false を返します。

変更履歴

バージョン | 説明
8.3.0 | token が渡されない場合、E_WARNING が発生するようになりました。

例

例1 strtok() の例

<?php
$string = "This is\tan example\nstring";
/* タブと改行をトークンの区切りとして使用します */
$tok = strtok($string, " \n\t");

while ($tok !== false) {
echo "Word=$tok<br />";
$tok = strtok(" \n\t");
}
?>

例2 空の部分が見つかった場合の strtok() の動作

<?php
$first_token = strtok('/something', '/');
$second_token = strtok('/');
var_dump($first_token, $second_token);
?>

上の例の出力は以下となります。

string(9) "something"
    bool(false)

例3 strtok() と explode() の違い

<?php
$string = ";aaa;;bbb;";
$parts = [];
$tok = strtok($string, ";");
while ($tok !== false) {
$parts[] = $tok;
$tok = strtok(";");
}
echo json_encode($parts),"\n";
$parts = explode(";", $string);
echo json_encode($parts),"\n";

上の例の出力は以下となります。

["aaa","bbb"]
["","aaa","","bbb",""]

注意

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

参考

  • explode() - 文字列を文字列により分割する


文字列を小文字にする

  • ≪ strtok
  • strtoupper ≫
  • PHP Manual
  • String 関数
  • 文字列を小文字にする

strtolower

(PHP 4, PHP 5, PHP 7, PHP 8)

strtolower — 文字列を小文字にする

説明

strtolower(string $string): string

string の、ASCII のアルファベット部分をすべて小文字にして返します｡

"A" (0x41) から "Z" (0x5a) までの範囲のバイト列は、それぞれのバイト値に 32 を加えることによって 対応する小文字に変換されます。

マルチバイトの UTF-8 文字は無視されるので、 UTF-8 でエンコードされた文字列中にある ASCII 文字を変換する際も、 このやり方が使えます。 マルチバイトの ASCII でない文字を変換するには、 mb_strtolower() を使います。

パラメータ

string

入力文字列。

戻り値

小文字に変換した文字列を返します。

変更履歴

バージョン | 説明
8.2.0 | ケース変換は、setlocale() で設定されたロケールに依存しなくなりました。 ASCII 文字のみが変換されます。

例

例1 strtolower() の例

<?php
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = strtolower($str);
echo $str; // mary had a little lamb and she loved it so を返します
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strtoupper() - 文字列を大文字にする
  • ucfirst() - 文字列の最初の文字を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする
  • mb_strtolower() - 文字列を小文字にする


文字列を大文字にする

  • ≪ strtolower
  • strtr ≫
  • PHP Manual
  • String 関数
  • 文字列を大文字にする

strtoupper

(PHP 4, PHP 5, PHP 7, PHP 8)

strtoupper — 文字列を大文字にする

説明

strtoupper(string $string): string

string の、ASCII のアルファベット部分をすべて大文字にして返します｡

"a" (0x61) から "z" (0x7a) までの範囲のバイト列は、それぞれのバイト値から 32 を引くことによって 対応する大文字に変換されます。

マルチバイトの UTF-8 文字は無視されるので、 UTF-8 でエンコードされた文字列中にある ASCII 文字を変換する際も、 このやり方が使えます。 マルチバイトの ASCII でない文字を変換するには、 mb_strtoupper() を使います。

パラメータ

string

入力文字列。

戻り値

大文字にした文字列を返します。

変更履歴

バージョン | 説明
8.2.0 | ケース変換は、setlocale() で設定されたロケールに依存しなくなりました。 ASCII 文字のみが変換されます。

例

例1 strtoupper() の例

<?php
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = strtoupper($str);
echo $str; // 「MARY HAD A LITTLE LAMB AND SHE LOVED IT SO」を出力します。
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strtolower() - 文字列を小文字にする
  • ucfirst() - 文字列の最初の文字を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする
  • mb_strtoupper() - 文字列を大文字にする


文字の変換あるいは部分文字列の置換を行う

  • ≪ strtoupper
  • substr ≫
  • PHP Manual
  • String 関数
  • 文字の変換あるいは部分文字列の置換を行う

strtr

(PHP 4, PHP 5, PHP 7, PHP 8)

strtr — 文字の変換あるいは部分文字列の置換を行う

説明

strtr(string $string, string $from, string $to): string

代替のシグネチャ (名前付き引数をサポートしていません):

strtr(string $string, array $replace_pairs): string

引数を三つ渡した場合、この関数は string のコピーを返します。その際に、文字列中に from の各文字 (シングルバイト) があれば to の対応する文字に変換します。つまり、すべての $from[$n] が $to[$n] に置換されることになります。ここで $n は、どちらの引数でも共通に有効なオフセットです。

from と to の長さが異なる場合、長い方の余分な文字は無視されます。 返される文字列の長さは、もとの string と同じになります。

引数を二つだけ渡す場合は、二番目の引数を array('from' => 'to', ...) 形式の配列にしなければなりません。 返される値は文字列で、もとの文字列中にある配列のキーと同じ部分を対応する値で置換したものとなります。 一番長いキーから順に調べます。一度部分文字列の置換を行うと、 置換後の文字列がさらに置換の対象となることはありません。

この場合は、配列のキーと値は任意の長さにすることができますが、キーを空にすることだけはできません。 さらに、返される文字列の長さはもとの string とは異なる可能性があります。 しかし、この関数が最も効率的に働くのは、すべてのキーが同じ長さである場合です。

パラメータ

string

変換する文字列。

from

to に変換される文字列。

to

from を置換する文字列。

replace_pairs

replace_pairs パラメータを to や from のかわりに使用することができます。この場合は array('from' => 'to', ...) 形式の配列となります。

replace_pairs の中に空文字列 ("") のキーがある場合は、その要素は無視されます。 PHP 8.0.0 以降では、この場合 E_WARNING が発生します。

戻り値

変換後の文字列を返します。

例

例1 strtr() の例

<?php
// この形式の場合、strtr() はバイト単位での変換を行います。
// したがって、ここではシングルバイトエンコーディングを想定しています。
$addr = strtr($addr, "aao", "aao");
?>

次の例は、引数を二つだけ指定して strtr() をコールしたときの挙動を示すものです。置換の優先度 ("h" よりもっと長いキーに一致しているので、この置換は行われていないこと)、 そして一度置換した文字列はもう置換の対象にならないことを確認しましょう。

例2 2 つの引数を伴う strtr() の例

<?php
$trans = array("h" => "-", "hello" => "hi", "hi" => "hello");
echo strtr("hi all, I said hello", $trans);
?>

上の例の出力は以下となります。

hello all, I said hi

これらふたつのモードの挙動は大きく異なります。引数が三つの場合は strtr() はバイト単位で置換し、二つの場合はより長い部分文字列を置換します。

例3 strtr() の挙動の比較

<?php
echo strtr("baab", "ab", "01"),"\n";

$trans = array("ab" => "01");
echo strtr("baab", $trans);
?>

上の例の出力は以下となります。

1001
ba01

参考

  • str_replace() - 検索文字列に一致したすべての文字列を置換する
  • preg_replace() - 正規表現検索および置換を行う


文字列の一部分を返す

  • ≪ strtr
  • substr_compare ≫
  • PHP Manual
  • String 関数
  • 文字列の一部分を返す

substr

(PHP 4, PHP 5, PHP 7, PHP 8)

substr — 文字列の一部分を返す

説明

substr(string $string, int $offset, ?int $length = null): string

文字列 string の、offset で指定された位置から length バイト分の文字列を返します。

パラメータ

string

入力文字列。

offset

offset が正の場合、返される文字列は、 string の 0 から数えて offset番目から始まる文字列となります。 例えば、文字列'abcdef'において位置 0にある文字は、'a'であり、 位置2には'c'があります。

offset が負の場合、返される文字列は、 stringの後ろから数えて offset番目から始まる文字列となります。

string の長さが offset 文字より短い場合は、 空の文字列が返されます。

例1 負の offset の使用

<?php
$rest = substr("abcdef", -1); // "f" を返す
$rest = substr("abcdef", -2); // "ef" を返す
$rest = substr("abcdef", -3, 1); // "d" を返す
?>

length

length が指定され、かつ正である場合、 返される文字列は offset (string の長さに依存します) から数えてlength文字数分となります。

length が指定され、かつ負である場合、 string の終端からその文字数分の文字が省略されます (offset が負の場合は、 開始位置を算出したあとで)。 もし offset が切り出し位置を超える場合、 空の文字列が返されます。

length が指定され、かつ 0 であれば、空の文字が返されます。

length を省略した場合、または null の場合は、 offset の位置から文字列の最後までの部分文字列を返します。

例2 負の length の使用

<?php
$rest = substr("abcdef", 0, -1); // "abcde" を返す
$rest = substr("abcdef", 2, -1); // "cde" を返す
$rest = substr("abcdef", 4, -4); // "" を返す。PHP 8.0.0 より前のバージョンでは、false を返していました。
$rest = substr("abcdef", -3, -1); // "de" を返す
?>

戻り値

string の一部を返すか、空文字列を返します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。 length に明示的に null を設定すると、 文字列の最後までを含む部分文字列を返すようになっています。 これより前のバージョンでは、空文字列を返していました。
8.0.0 | この関数は、前のバージョンで false を返す場合に、空文字列を返すようになりました。

例

例3 基本的な substr() の使用法

<?php
echo substr('abcdef', 1); // bcdef
echo substr("abcdef", 1, null); // bcdef, PHP 8.0.0 より前のバージョンでは、空の文字列を返していました。
echo substr('abcdef', 1, 3); // bcd
echo substr('abcdef', 0, 4); // abcd
echo substr('abcdef', 0, 8); // abcdef
echo substr('abcdef', -1, 1); // f

// 文字列中の 1 文字にアクセスすることも
// "角括弧" を使用することで可能
$string = 'abcdef';
echo $string[0]; // a
echo $string[3]; // d
echo $string[strlen($string)-1]; // f

?>

例4 substr() でのキャストの挙動

<?php
class apple {
public function __toString() {
return "green";
}
}

echo "1) ".var_export(substr("pear", 0, 2), true).PHP_EOL;
echo "2) ".var_export(substr(54321, 0, 2), true).PHP_EOL;
echo "3) ".var_export(substr(new apple(), 0, 2), true).PHP_EOL;
echo "4) ".var_export(substr(true, 0, 1), true).PHP_EOL;
echo "5) ".var_export(substr(false, 0, 1), true).PHP_EOL;
echo "6) ".var_export(substr("", 0, 1), true).PHP_EOL;
echo "7) ".var_export(substr(1.2e3, 0, 4), true).PHP_EOL;
?>

上の例の出力は以下となります。

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) ''
6) ''
7) '1200'

例5 文字列の範囲が不正な場合

指定された文字列の範囲が正しくない場合、 substr() は PHP 8.0.0 以降では空文字列を返します。 それより前のバージョンでは、false を返していました。

<?php
var_dump(substr('a', 2));
?>

上の例の PHP 8 での出力は、このようになります。:

string(0) ""

上の例の PHP 7 での出力は、このようになります。

bool(false)

参考

  • strrchr() - 文字列中に文字が最後に現れる場所を取得する
  • substr_replace() - 文字列の一部を置換する
  • preg_match() - 正規表現によるマッチングを行う
  • trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • mb_substr() - 文字列の一部を得る
  • wordwrap() - 指定した文字数で文字列を分割する
  • 文字列への文字単位のアクセスと修正


指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する

  • ≪ substr
  • substr_count ≫
  • PHP Manual
  • String 関数
  • 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する

substr_compare

(PHP 5, PHP 7, PHP 8)

substr_compare — 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する

説明

substr_compare(
string $haystack,
string $needle,
int $offset,
?int $length = null,
bool $case_insensitive = false
): int

substr_compare() は、haystack の offset 文字目以降の最大 length 文字を、needle と比較します。

パラメータ

haystack

比較したい最初の文字列。

needle

比較したい二番目の文字列。

offset

比較を開始する位置。 負の値を指定した場合は、文字列の最後から数えます。

length

比較する長さ。デフォルト値は、 haystack の長さから offset を引いたものと needle の長さのうち、長いほうです。

case_insensitive

case_insensitive が true の場合、 大文字小文字を区別せずに比較します。

戻り値

haystack の offset 以降が needle より小さい場合に -1、 needle より大きい場合に 1、 等しい場合に 0 を返します。 offset が haystack と等しい (PHP 7.2.18, 7.3.5 より前のバージョン) か、 haystack より長い場合、 もしくは length が設定されていて0未満である場合、 substr_compare() は警告を表示して false を返します。

変更履歴

バージョン | 説明
8.2.0 | これより前のバージョンで負の数と正の数を返していた場合に、 この関数は -1 と 1 を返すようになりました。
8.0.0 | length は、nullable になりました。
7.2.18, 7.3.5 | offset の値は、 haystack の長さと等しくても問題なくなりました。

例

例1 substr_compare() の例

<?php
echo substr_compare("abcde", "bc", 1, 2); // 0
echo substr_compare("abcde", "de", -2, 2); // 0
echo substr_compare("abcde", "bcg", 1, 2); // 0
echo substr_compare("abcde", "BC", 1, 2, true); // 0
echo substr_compare("abcde", "bc", 1, 3); // 1
echo substr_compare("abcde", "cd", 1, 2); // -1
echo substr_compare("abcde", "abc", 5, 1); // 警告
?>

参考

  • strncmp() - 最初の n 文字についてバイナリセーフな文字列比較を行う


副文字列の出現回数を数える

  • ≪ substr_compare
  • substr_replace ≫
  • PHP Manual
  • String 関数
  • 副文字列の出現回数を数える

substr_count

(PHP 4, PHP 5, PHP 7, PHP 8)

substr_count — 副文字列の出現回数を数える

説明

substr_count(
string $haystack,
string $needle,
int $offset = 0,
?int $length = null
): int

substr_count() は、文字列 haystack の中での副文字列 needle の出現回数を返します。 needle は英大小文字を区別することに注意してください。

注意:

この関数は重なり合う副文字列をカウントしません。以下の例を見てください !

パラメータ

haystack

検索対象の文字列

needle

検索する副文字列

offset

開始位置のオフセット。 負の数を指定すると、文字列の末尾から数えます。

length

指定したオフセット以降に副文字列で検索する最大長。 オフセットと長さの総和が haystack の長さよりも長い場合、警告が発生します。 負の数を指定すると、haystack の末尾から数えます。

戻り値

この関数は 整数を返します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。
7.1.0 | 負の offset と length をサポートするようになりました。 length は、0 を指定しても問題ありません。

例

例1 substr_count() の例

<?php
$text = 'This is a test';
echo strlen($text); // 14

echo substr_count($text, 'is'); // 2

// 文字列は 's is a test' になっているので, 1 が表示される
echo substr_count($text, 'is', 3);

// テキストは 's i' になっているので, 0 が表示される
echo substr_count($text, 'is', 3, 3);

// 5+10 > 14 なので、警告が発生する
echo substr_count($text, 'is', 5, 10);

// 重なっている副文字列はカウントされないので、1 が表示される
$text2 = 'gcdgcdgcd';
echo substr_count($text2, 'gcdgcd');
?>

参考

  • count_chars() - 文字列で使用されている文字に関する情報を返す
  • strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
  • substr() - 文字列の一部分を返す
  • strstr() - 文字列が最初に現れる位置を見つける


文字列の一部を置換する

  • ≪ substr_count
  • trim ≫
  • PHP Manual
  • String 関数
  • 文字列の一部を置換する

substr_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

substr_replace — 文字列の一部を置換する

説明

substr_replace(
array|string $string,
array|string $replace,
array|int $offset,
array|int|null $length = null
): string|array

substr_replace()は、文字列 stringの offset および (オプションの) length パラメータで区切られた部分を replace で指定した文字列に置換します。

パラメータ

string

入力文字列。

文字列の配列を指定することもでき、各文字列について順に置換を行います。 この場合、他のパラメータ replace、offset および length がスカラ値なら それを各入力文字列に順次適用し、配列なら各入力文字列に対応する要素の値を適用します。

replace

置換する文字列。

offset

offset が負ではない場合、置換は string で offset 番目の文字から始まります。

offset が負の場合、置換は string の終端から offset 番目の文字から始まります。

length

正の値を指定した場合、 string の置換される部分の長さを表します。 負の場合、置換を停止する位置が string の終端から何文字目であるかを表します。このパラメータが省略された場合、 デフォルト値は strlen(string)、すなわち、 string の終端まで置換することになります。 当然、もし length がゼロだったら、 この関数は string の最初から offset の位置に replace を挿入するということになります。

戻り値

結果の文字列を返します。もし、string が配列の場合、配列が返されます。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 シンプルな substr_replace() の例

<?php
$var = 'ABCDEFGH:/MNRPQR/';
echo "Original: $var<hr />\n";

/* 以下の2つの例は、全ての $var で 'bob' で置換します。 */
echo substr_replace($var, 'bob', 0) . "<br />\n";
echo substr_replace($var, 'bob', 0, strlen($var)) . "<br />\n";

/* $var の先頭に 'bob' を挿入します */
echo substr_replace($var, 'bob', 0, 0) . "<br />\n";

/* 次の2つの例は、$var の 'MNRPQR' を 'bob'で置換します */
echo substr_replace($var, 'bob', 10, -1) . "<br />\n";
echo substr_replace($var, 'bob', -7, -1) . "<br />\n";

/* $var から 'MNRPQR' を削除します */
echo substr_replace($var, '', 10, -1) . "<br />\n";
?>

例2 substr_replace() で複数の文字列を一度に置換する例

<?php
$input = array('A: XXX', 'B: XXX', 'C: XXX');

// シンプルなケース: 各文字列の XXX を YYY で置換します
echo implode('; ', substr_replace($input, 'YYY', 3, 3))."\n";

// より複雑で、各文字列で置換する値が異なるケース
$replace = array('AAA', 'BBB', 'CCC');
echo implode('; ', substr_replace($input, $replace, 3, 3))."\n";

// 置換する文字数が異なるケース
$length = array(1, 2, 3);
echo implode('; ', substr_replace($input, $replace, 3, $length))."\n";
?>

上の例の出力は以下となります。

A: YYY; B: YYY; C: YYY
A: AAA; B: BBB; C: CCC
A: AAAXX; B: BBBX; C: CCC

注意

注意: この関数はバイナリデータに対応しています。

参考

  • str_replace() - 検索文字列に一致したすべての文字列を置換する
  • substr() - 文字列の一部分を返す
  • 文字列への文字単位のアクセスと修正


文字列の先頭および末尾にあるホワイトスペースを取り除く

  • ≪ substr_replace
  • ucfirst ≫
  • PHP Manual
  • String 関数
  • 文字列の先頭および末尾にあるホワイトスペースを取り除く

trim

(PHP 4, PHP 5, PHP 7, PHP 8)

trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く

説明

trim(string $string, string $characters = " \n\r\t\v\x00"): string

この関数は string の最初および最後から空白文字を取り除き、 取り除かれた文字列を返します。2番目のパラメータを指定しない場合、 trim()は以下の文字を削除します。

  • " " (ASCII 32 (0x20)), 通常の空白。
  • "\t" (ASCII 9 (0x09)), タブ。
  • "\n" (ASCII 10 (0x0A)), リターン。
  • "\r" (ASCII 13 (0x0D)), 改行。
  • "\0" (ASCII 0 (0x00)), NULバイト
  • "\v" (ASCII 11 (0x0B)), 垂直タブ

パラメータ

string

ホワイトスペースを取り除く string

characters

charactersパラメータにより、削除する 文字を指定することも可能です。削除したい全ての文字をリストに してください。.. を連続した文字の範囲を指定する際に 使用可能です。

戻り値

ホワイトスペースを取り除いた文字列

例

例1 trim()の使用例

<?php

$text = "\t\tThese are a few words :) ... ";
$binary = "\x09Example string\x0A";
$hello = "Hello World";
var_dump($text, $binary, $hello);

print "\n";

$trimmed = trim($text);
var_dump($trimmed);

$trimmed = trim($text, " \t.");
var_dump($trimmed);

$trimmed = trim($hello, "Hdle");
var_dump($trimmed);

$trimmed = trim($hello, 'HdWr');
var_dump($trimmed);

// ASCII 制御文字 (0 から 31 まで) を
// $binary の先頭および末尾から取り除きます
$clean = trim($binary, "\x00..\x1F");
var_dump($clean);

?>

上の例の出力は以下となります。

string(32) "        These are a few words :) ...  "
string(16) "    Example string
"
string(11) "Hello World"

string(28) "These are a few words :) ..."
string(24) "These are a few words :)"
string(5) "o Wor"
string(9) "ello Worl"
string(14) "Example string"

例2 trim() を用いて配列の値をトリミングする

<?php
function trim_value(&$value)
{
$value = trim($value);
}

$fruit = array('apple','banana ', ' cranberry ');
var_dump($fruit);

array_walk($fruit, 'trim_value');
var_dump($fruit);

?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(5) "apple"
  [1]=>
  string(7) "banana "
  [2]=>
  string(11) " cranberry "
}
array(3) {
  [0]=>
  string(5) "apple"
  [1]=>
  string(6) "banana"
  [2]=>
  string(9) "cranberry"
}

注意

注意: わかるかな?: 途中の文字が取り除かれる

trim() は string の先頭と末尾から文字を取り除くので、 文字列の途中にある文字がを取り除かれたり (あるいは取り除かれなかったり) すると少し戸惑うことでしょう。 trim('abc', 'bad') は 'a' と 'b' を両方取り除きます。 なぜなら、まず 'a' を取り除いた時点で 'b' が先頭の文字となり、それも取り除く対象だからです。 したがって、この処理は正しく動きます。一方、 trim('abc', 'b') は動かないでしょう。

参考

  • ltrim() - 文字列の最初から空白 (もしくはその他の文字) を取り除く
  • rtrim() - 文字列の最後から空白 (もしくはその他の文字) を取り除く
  • str_replace() - 検索文字列に一致したすべての文字列を置換する


文字列の最初の文字を大文字にする

  • ≪ trim
  • ucwords ≫
  • PHP Manual
  • String 関数
  • 文字列の最初の文字を大文字にする

ucfirst

(PHP 4, PHP 5, PHP 7, PHP 8)

ucfirst — 文字列の最初の文字を大文字にする

説明

ucfirst(string $string): string

string の最初の文字が "a" (0x61) から "z" (0x7a) までの ASCII 文字の場合、 それを大文字にします。

パラメータ

string

入力文字列。

戻り値

変換後の文字列を返します。

変更履歴

バージョン | 説明
8.2.0 | ケース変換は、setlocale() で設定されたロケールに依存しなくなりました。 ASCII 文字のみが変換されます。

例

例1 ucfirst() の例

<?php
$foo = 'hello world!';
$foo = ucfirst($foo); // Hello world!

$bar = 'HELLO WORLD!';
$bar = ucfirst($bar); // HELLO WORLD!
$bar = ucfirst(strtolower($bar)); // Hello world!
?>

参考

  • lcfirst() - 文字列の最初の文字を小文字にする
  • strtolower() - 文字列を小文字にする
  • strtoupper() - 文字列を大文字にする
  • ucwords() - 文字列の各単語の最初の文字を大文字にする
  • mb_convert_case() - 文字列に対してケースフォールディングを行う


文字列の各単語の最初の文字を大文字にする

  • ≪ ucfirst
  • utf8_decode ≫
  • PHP Manual
  • String 関数
  • 文字列の各単語の最初の文字を大文字にする

ucwords

(PHP 4, PHP 5, PHP 7, PHP 8)

ucwords — 文字列の各単語の最初の文字を大文字にする

説明

ucwords(string $string, string $separators = " \t\r\n\f\v"): string

文字が "a" (0x61) から "z" (0x7a) までのアルファベットの場合、 string の各単語の最初の文字を大文字にしたものを返します。

この関数における "単語" とは、 separators に含まれていない文字からなる文字列です。 separators のデフォルトはスペース、 フォームフィード、改行、キャリッジリターン、 水平タブ、垂直タブ です。

マルチバイト文字列に対して類似の変換を行うには、 mb_convert_case() を MB_CASE_TITLE モードで使います。

パラメータ

string

入力文字列。

separators

オプションの separators で、単語の区切り文字を指定します。

戻り値

変更後の文字列を返します。

変更履歴

バージョン | 説明
8.2.0 | ケース変換は、setlocale() で設定されたロケールに依存しなくなりました。 ASCII 文字のみが変換されます。

例

例1 ucwords() の例

<?php
$foo = 'hello world!';
$foo = ucwords($foo); // Hello World!

$bar = 'HELLO WORLD!';
$bar = ucwords($bar); // HELLO WORLD!
$bar = ucwords(strtolower($bar)); // Hello World!
?>

例2 ucwords() で、区切り文字を指定する例

<?php
$foo = 'hello|world!';
$bar = ucwords($foo); // Hello|world!

$baz = ucwords($foo, "|"); // Hello|World!
?>

例3 ucwords() で、追加の区切り文字を指定する例

<?php
$foo = "mike o'hara";
$bar = ucwords($foo); // Mike O'hara

$baz = ucwords($foo, " \t\r\n\f\v'"); // Mike O'Hara
?>

注意

注意: この関数はバイナリデータに対応しています。

参考

  • strtoupper() - 文字列を大文字にする
  • strtolower() - 文字列を小文字にする
  • ucfirst() - 文字列の最初の文字を大文字にする
  • mb_convert_case() - 文字列に対してケースフォールディングを行う


UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する

  • ≪ ucwords
  • utf8_encode ≫
  • PHP Manual
  • String 関数
  • UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する

utf8_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

utf8_decode — UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する

警告

この関数は PHP 8.2.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

utf8_decode(string $string): string

この関数は、文字列 string を UTF-8 エンコードから ISO-8859-1 へ変換します。 有効な UTF-8 ではない文字列バイト、 および ISO-8859-1 に存在しない UTF-8 の文字 (つまり、U+00FF 以降のコードポイント) は、 ? に置き換えられます。

注意:

ISO-8859-1 文字エンコーディングを使っているとマークされている 多くの Web ページが、実際にはそれと似た Windows-1252 を使っており、 Web ブラウザは ISO-8859-1 Web ページを Windows-1252 として解釈しています。Windows-1252 は ISO-8859-1 のある制御文字の代わりに、ユーロ記号 (?) や curly quote (" ") を印字可能な文字として追加しています。 この関数はそうした Windows-1252 文字を正しく変換しません。 Windows-1252 の変換が必要な場合は、別の関数を使ってください。

パラメータ

string

UTF-8 エンコードされた文字列。

戻り値

string を ISO-8859-1 に変換した結果を返します。

変更履歴

バージョン | 説明
8.2.0 | この関数は、推奨されなくなりました。
7.2.0 | この関数は、XML拡張モジュールから PHP のコアに移動しました。 これより前のバージョンでは、 この関数は XML拡張モジュール をインストールしていた場合にのみ利用可能でした。

例

例1 基本的な例

<?php
// Convert the string 'Zoe' from UTF-8 to ISO 8859-1
$utf8_string = "\x5A\x6F\xC3\xAB";
$iso8859_1_string = utf8_decode($utf8_string);
echo bin2hex($iso8859_1_string), "\n";
// Invalid UTF-8 sequences are replaced with '?'
$invalid_utf8_string = "\xC3";
$iso8859_1_string = utf8_decode($invalid_utf8_string);
var_dump($iso8859_1_string);
// Characters which don't exist in ISO 8859-1, such as
// '?' (Euro Sign) are also replaced with '?'
$utf8_string = "\xE2\x82\xAC";
$iso8859_1_string = utf8_decode($utf8_string);
var_dump($iso8859_1_string);
?>

上の例の出力は以下となります。

5a6feb
string(1) "?"
string(1) "?"

注意

注意: この関数は推奨されません。代替については下記のとおりです。

この関数は、PHP 8.2.0 以降は推奨されなくなり、 将来のバージョンで削除される予定です。 この関数を使っているコードをチェックし、適切な代替に置き換えるべきです。

この関数と似た機能は、 mb_convert_encoding() で実現できます。 この関数は、ISO-8859-1 と、多くの他の文字エンコーディングをサポートしています。

<?php
$utf8_string = "\xC3\xAB"; // 'e' (e with diaeresis) in UTF-8
$iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');
echo bin2hex($iso8859_1_string), "\n";

$utf8_string = "\xCE\xBB"; // 'λ' (Greek lower-case lambda) in UTF-8
$iso8859_7_string = mb_convert_encoding($utf8_string, 'ISO-8859-7', 'UTF-8');
echo bin2hex($iso8859_7_string), "\n";

$utf8_string = "\xE2\x82\xAC"; // '?' (Euro sign) in UTF-8 (not present in ISO-8859-1)
$windows_1252_string = mb_convert_encoding($utf8_string, 'Windows-1252', 'UTF-8');
echo bin2hex($windows_1252_string), "\n";
?>

上の例の出力は以下となります。

eb
eb
80

他の代替として、インストールされている拡張機能に依存した関数ですが、 UConverter::transcode() と iconv() が挙げられます。

次のコードは、いずれも同じ結果を返します:

<?php
$utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoe' in UTF-8
$iso8859_1_string = utf8_decode($utf8_string);
echo bin2hex($iso8859_1_string), "\n";

$iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');
echo bin2hex($iso8859_1_string), "\n";

$iso8859_1_string = iconv('UTF-8', 'ISO-8859-1', $utf8_string);
echo bin2hex($iso8859_1_string), "\n";

$iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF8');
echo bin2hex($iso8859_1_string), "\n";
?>

上の例の出力は以下となります。

5a6feb
5a6feb
5a6feb
5a6feb
UConverter::transcode() に 'to_subst' オプションとして '?' を指定すると、 ISO-8859-1 で表現できないか、不正な文字列の場合の utf8_decode() 関数と同じ結果を返します。
<?php
$utf8_string = "\xE2\x82\xAC"; // ? (Euro Sign) does not exist in ISO 8859-1
$iso8859_1_string = UConverter::transcode(
$utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
);
var_dump($iso8859_1_string);
?>

上の例の出力は以下となります。

sring(1) "?"

参考

  • utf8_encode() - ISO-8859-1 文字列を UTF-8 に変換する
  • mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • UConverter::transcode() - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


ISO-8859-1 文字列を UTF-8 に変換する

  • ≪ utf8_decode
  • vfprintf ≫
  • PHP Manual
  • String 関数
  • ISO-8859-1 文字列を UTF-8 に変換する

utf8_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

utf8_encode — ISO-8859-1 文字列を UTF-8 に変換する

警告

この関数は PHP 8.2.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

utf8_encode(string $string): string

この関数は、文字列 string を ISO-8859-1 エンコードから UTF-8 へ変換します。

注意:

この関数は、指定された文字列の現在の文字エンコーディングを推測しません。 代わりに、 ISO-8859-1 ("Latin 1" とも呼ばれています) としてエンコードされていると解釈し、UTF-8 に変換します。 全てのバイト列は有効な ISO-8859-1 の文字列であるため、 この関数は決してエラーになりません。 しかし、異なるエンコーディングを意図していた場合、 有用な結果にはならないでしょう。

ISO-8859-1 文字エンコーディングを使っているとマークされている 多くの Web ページが、実際にはそれと似た Windows-1252 を使っており、 Web ブラウザは ISO-8859-1 Web ページを Windows-1252 として解釈しています。Windows-1252 は ISO-8859-1 のある制御文字の代わりに、ユーロ記号 (?) や curly quote (" ") を印字可能な文字として追加しています。 この関数はそうした Windows-1252 文字を正しく変換しません。 Windows-1252 の変換が必要な場合は、別の関数を使ってください。

パラメータ

string

ISO-8859-1 形式の文字列。

戻り値

string を UTF-8 に変換した結果を返します。

変更履歴

バージョン | 説明
8.2.0 | この関数は、推奨されなくなりました。
7.2.0 | この関数は、XML拡張モジュール から PHP のコアに移動しました。 これより前のバージョンでは、 この関数は XML拡張モジュール をインストールしていた場合にのみ利用可能でした。

例

例1 基本的な例

<?php
// Convert the string 'Zoe' from ISO 8859-1 to UTF-8
$iso8859_1_string = "\x5A\x6F\xEB";
$utf8_string = utf8_encode($iso8859_1_string);
echo bin2hex($utf8_string), "\n";
?>

上の例の出力は以下となります。

5a6fc3ab

注意

注意: この関数は推奨されません。代替については下記のとおりです。

この関数は、PHP 8.2.0 以降は 推奨されなくなり、 将来のバージョンで削除される予定です。 この関数を使っているコードをチェックし、適切な代替に置き換えるべきです。

この関数と似た機能は、 mb_convert_encoding() で実現できます。 この関数は、ISO-8859-1 と、多くの他の文字エンコーディングをサポートしています。

<?php
$iso8859_1_string = "\xEB"; // 'e' (e with diaeresis) in ISO-8859-1
$utf8_string = mb_convert_encoding($iso8859_1_string, 'UTF-8', 'ISO-8859-1');
echo bin2hex($utf8_string), "\n";

$iso8859_7_string = "\xEB"; // the same string in ISO-8859-7 represents 'λ' (Greek lower-case lambda)
$utf8_string = mb_convert_encoding($iso8859_7_string, 'UTF-8', 'ISO-8859-7');
echo bin2hex($utf8_string), "\n";

$windows_1252_string = "\x80"; // '?' (Euro sign) in Windows-1252, but not in ISO-8859-1
$utf8_string = mb_convert_encoding($windows_1252_string, 'UTF-8', 'Windows-1252');
echo bin2hex($utf8_string), "\n";
?>

上の例の出力は以下となります。

c3ab
cebb
e282ac

他の代替として、インストールされている拡張機能に依存した関数ですが、 UConverter::transcode() と iconv() が挙げられます。

次のコードは、いずれも同じ結果を返します:

<?php
$iso8859_1_string = "\x5A\x6F\xEB"; // 'Zoe' in ISO-8859-1

$utf8_string = utf8_encode($iso8859_1_string);
echo bin2hex($utf8_string), "\n";

$utf8_string = mb_convert_encoding($iso8859_1_string, 'UTF-8', 'ISO-8859-1');
echo bin2hex($utf8_string), "\n";

$utf8_string = UConverter::transcode($iso8859_1_string, 'UTF8', 'ISO-8859-1');
echo bin2hex($utf8_string), "\n";

$utf8_string = iconv('ISO-8859-1', 'UTF-8', $iso8859_1_string);
echo bin2hex($utf8_string), "\n";
?>

上の例の出力は以下となります。

5a6fc3ab
5a6fc3ab
5a6fc3ab
5a6fc3ab

参考

  • utf8_decode() - UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する
  • mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  • UConverter::transcode() - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
  • iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する


フォーマットされた文字列をストリームに書き込む

  • ≪ utf8_encode
  • vprintf ≫
  • PHP Manual
  • String 関数
  • フォーマットされた文字列をストリームに書き込む

vfprintf

(PHP 5, PHP 7, PHP 8)

vfprintf — フォーマットされた文字列をストリームに書き込む

説明

vfprintf(resource $stream, string $format, array $values): int

format によって作成された文字列を stream で指定したストリームに書き込みます。

fprintf() と同様の動作をしますが、 可変引数ではなく引数の配列を受け取って処理します。

パラメータ

stream

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 * を指定します。 * を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

Precision

ピリオド . の後に数値を続けるか、 * を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g, G, h, H 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 * を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は整数として扱われ、2進数値として表現されます。
c | 引数は整数として扱われ、ASCII文字として表現されます。
d | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は整数として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は整数として扱われ、符号なし10進数値として表現されます。
x | 引数は整数として扱われ、16進数値(小文字)として表現されます。
X | 引数は整数として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
int | d, u, c, o, x, X, b
float | e, E, f, F, g, G, h, H

values

戻り値

出力された文字列の長さを返します。

エラー / 例外

  PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ValueError がスローされます。 これより前のバージョンでは、代わりに false を返し、E_WARNING を発生させていました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

例

例1 vfprintf(): 数値のゼロ埋め

<?php
if (!($fp = fopen('date.txt', 'w')))
return;

vfprintf($fp, "%04d-%02d-%02d", array($year, $month, $day));
// ISO 形式にフォーマットした日付を date.txt に書き込みます
?>

参考

  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • fprintf() - フォーマットされた文字列をストリームに書き込む
  • vprintf() - フォーマットされた文字列を出力する
  • vsprintf() - フォーマットされた文字列を返す
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する


フォーマットされた文字列を出力する

  • ≪ vfprintf
  • vsprintf ≫
  • PHP Manual
  • String 関数
  • フォーマットされた文字列を出力する

vprintf

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

vprintf — フォーマットされた文字列を出力する

説明

vprintf(string $format, array $values): int

formatに基づき文字列フォーマットされた文字列を出力します (フォーマットは sprintf() のドキュメントに既述されています)。

printf() と動作は同じですが、可変長の引数ではなく、 配列を引数として受け取ります。

パラメータ

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 * を指定します。 * を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

Precision

ピリオド . の後に数値を続けるか、 * を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g, G, h, H 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 * を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は整数として扱われ、2進数値として表現されます。
c | 引数は整数として扱われ、ASCII文字として表現されます。
d | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は整数として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は整数として扱われ、符号なし10進数値として表現されます。
x | 引数は整数として扱われ、16進数値(小文字)として表現されます。
X | 引数は整数として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
int | d, u, c, o, x, X, b
float | e, E, f, F, g, G, h, H

values

戻り値

出力された文字列の長さを返します。

エラー / 例外

  PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ValueError がスローされます。 これより前のバージョンでは、代わりに false を返し、E_WARNING を発生させていました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

例

例1 vprintf(): 整数のゼロ埋め

<?php
vprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>

上の例の出力は以下となります。

1988-08-01

参考

  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • fprintf() - フォーマットされた文字列をストリームに書き込む
  • vsprintf() - フォーマットされた文字列を返す
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する


フォーマットされた文字列を返す

  • ≪ vprintf
  • wordwrap ≫
  • PHP Manual
  • String 関数
  • フォーマットされた文字列を返す

vsprintf

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

vsprintf — フォーマットされた文字列を返す

説明

vsprintf(string $format, array $values): string

sprintf()と動作は同じですが、 可変長の引数ではなく配列を引数とします。

パラメータ

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ | 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) | スペースに変換される詰め物です。 これがデフォルトです。
0 | 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) | 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 * を指定します。 * を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

Precision

ピリオド . の後に数値を続けるか、 * を続けますが、 その意味は指定子に依存します:

  • e, E, f と F 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • g, G, h, H 指定子の場合: 表示する最大の有効桁数
  • s 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 * を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

指定子の一覧
指定子 | 説明
% 文字通り、パーセント文字です。 引数は不要です。
b | 引数は整数として扱われ、2進数値として表現されます。
c | 引数は整数として扱われ、ASCII文字として表現されます。
d | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
e | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
E | e 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
f | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
F | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
g

汎用フォーマット

P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 E 指定子の変換結果は、 X乗になります。

P > X ? ?4 の場合、E 指定子の変換結果となり、精度は、P ? (X + 1) になります。 そうでない場合、e 指定子の変換結果となり、 精度は、P - 1 になります。

G | g 指定子に似ていますが、 E と f を使います。
h | g 指定子に似ていますが、 F を使います。 PHP 8.0.0 以降で利用可能です。
H | g 指定子に似ていますが、 E と F を使います。 PHP 8.0.0 以降で利用可能です。
o | 引数は整数として扱われ、8進数値として表現されます。
s | 引数は文字列として扱われ、文字列として表現されます。
u | 引数は整数として扱われ、符号なし10進数値として表現されます。
x | 引数は整数として扱われ、16進数値(小文字)として表現されます。
X | 引数は整数として扱われ、16進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

値は、指定子の型に合うように強制されます:

型のハンドリング
型 | 指定子
string | s
int | d, u, c, o, x, X, b
float | e, E, f, F, g, G, h, H

values

戻り値

format に基づき、 フォーマットされた文字列の配列を返します。

エラー / 例外

  PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ValueError がスローされます。 これより前のバージョンでは、代わりに false を返し、E_WARNING を発生させていました。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に false を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。

例

例1 vsprintf(): 整数のゼロ埋め

<?php
print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>

上の例の出力は以下となります。

1988-08-01

参考

  • printf() - フォーマット済みの文字列を出力する
  • sprintf() - フォーマットされた文字列を返す
  • fprintf() - フォーマットされた文字列をストリームに書き込む
  • vprintf() - フォーマットされた文字列を出力する
  • vfprintf() - フォーマットされた文字列をストリームに書き込む
  • sscanf() - フォーマット文字列に基づき入力を処理する
  • fscanf() - フォーマットに基づきファイルからの入力を処理する
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • date() - Unixタイムスタンプを書式化する


指定した文字数で文字列を分割する

  • ≪ vsprintf
  • 変更履歴 ≫
  • PHP Manual
  • String 関数
  • 指定した文字数で文字列を分割する

wordwrap

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

wordwrap — 指定した文字数で文字列を分割する

説明

wordwrap(
string $string,
int $width = 75,
string $break = "\n",
bool $cut_long_words = false
): string

指定した文字数で、指定した文字を用いて文字列を分割します。

パラメータ

string

入力文字列。

width

文字列を分割するときの文字数。

break

オプションのパラメータ break を用いて行を分割します。

cut_long_words

cut_long_words を true に設定すると、 文字列は常に指定した width でラップされます。このため、 指定した幅よりも長い単語がある場合には、分割されます (2 番目の例を参照ください)。 false にすると、たとえ width が単語の長さより短かった場合でも、その単語を分割しません。

戻り値

受け取った文字列を指定した長さで分割したものを返します。

例

例1 wordwrap() の例

<?php
$text = "The quick brown fox jumped over the lazy dog.";
$newtext = wordwrap($text, 20, "<br />\n");

echo $newtext;
?>

上の例の出力は以下となります。

The quick brown fox<br />
jumped over the lazy<br />
dog.

例2 wordwrap() の例

<?php
$text = "A very long woooooooooooord.";
$newtext = wordwrap($text, 8, "\n", true);

echo "$newtext\n";
?>

上の例の出力は以下となります。

A very
long
wooooooo
ooooord.

例3 wordwrap() の例

<?php
$text = "A very long woooooooooooooooooord. and something";
$newtext = wordwrap($text, 8, "\n", false);

echo "$newtext\n";
?>

上の例の出力は以下となります。

A very
long
woooooooooooooooooord.
and
something

参考

  • nl2br() - 改行文字の前に HTML の改行タグを挿入する
  • chunk_split() - 文字列をより小さな部分に分割する


変数・データ型関連

  • 配列
    • はじめに
    • 定義済み定数
    • 配列のソート
    • 配列 関数
  • クラス/オブジェクト — クラス/オブジェクトの情報
    • はじめに
    • 例
    • クラス/オブジェクト関数
  • Ctype — 文字タイプチェック
    • はじめに
    • インストール/設定
    • Ctype 関数
  • Filter — データのフィルタリング
    • はじめに
    • インストール/設定
    • フィルタの型
    • 定義済み定数
    • 例
    • Filter 関数
  • 関数処理
    • はじめに
    • 関数処理 関数
  • Quickhash
    • はじめに
    • インストール/設定
    • 例
    • QuickHashIntSet — The QuickHashIntSet class
    • QuickHashIntHash — The QuickHashIntHash class
    • QuickHashStringIntHash — The QuickHashStringIntHash class
    • QuickHashIntStringHash — The QuickHashIntStringHash class
  • リフレクション
    • はじめに
    • 定義済み定数
    • 例
    • 拡張
    • Reflection — Reflection クラス
    • ReflectionClass — ReflectionClass クラス
    • ReflectionClassConstant — ReflectionClassConstant クラス
    • ReflectionEnum — ReflectionEnum クラス
    • ReflectionEnumUnitCase — ReflectionEnumUnitCase クラス
    • ReflectionEnumBackedCase — ReflectionEnumBackedCase クラス
    • ReflectionZendExtension — ReflectionZendExtension クラス
    • ReflectionExtension — ReflectionExtension クラス
    • ReflectionFunction — ReflectionFunction クラス
    • ReflectionFunctionAbstract — ReflectionFunctionAbstract クラス
    • ReflectionMethod — ReflectionMethod クラス
    • ReflectionNamedType — ReflectionNamedType クラス
    • ReflectionObject — ReflectionObject クラス
    • ReflectionParameter — ReflectionParameter クラス
    • ReflectionProperty — ReflectionProperty クラス
    • ReflectionType — ReflectionType クラス
    • ReflectionUnionType — ReflectionUnionType クラス
    • ReflectionGenerator — ReflectionGenerator クラス
    • ReflectionFiber — ReflectionFiber クラス
    • ReflectionIntersectionType — ReflectionIntersectionType クラス
    • ReflectionReference — ReflectionReference クラス
    • ReflectionAttribute — ReflectionAttribute クラス
    • Reflector — Reflector インターフェイス
    • ReflectionException — ReflectionException クラス
  • 変数操作
    • はじめに
    • インストール/設定
    • 変数操作 関数


配列

  • はじめに
  • 定義済み定数
  • 配列のソート
  • 配列 関数
    • array — 配列を生成する
    • array_change_key_case — 配列のすべてのキーの大文字小文字を変更する
    • array_chunk — 配列を分割する
    • array_column — 入力配列から単一のカラムの値を返す
    • array_combine — 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する
    • array_count_values — 配列内に存在する、異なる値の出現回数を数える
    • array_diff — 配列の差を計算する
    • array_diff_assoc — 追加された添字の確認を含めて配列の差を計算する
    • array_diff_key — キーを基準にして配列の差を計算する
    • array_diff_uassoc — ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
    • array_diff_ukey — キーを基準にし、コールバック関数を用いて配列の差を計算する
    • array_fill — 配列を指定した値で埋める
    • array_fill_keys — キーを指定して、配列を値で埋める
    • array_filter — コールバック関数を使用して、配列の要素をフィルタリングする
    • array_flip — 配列のキーと値を反転する
    • array_intersect — 配列の共通項を計算する
    • array_intersect_assoc — 追加された添字の確認も含めて配列の共通項を確認する
    • array_intersect_key — キーを基準にして配列の共通項を計算する
    • array_intersect_uassoc — 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
    • array_intersect_ukey — キーを基準にし、コールバック関数を用いて 配列の共通項を計算する
    • array_is_list — 指定された配列がリストかどうかをチェックする
    • array_key_exists — 指定したキーまたは添字が配列にあるかどうかを調べる
    • array_key_first — 配列の最初のキーを得る
    • array_key_last — 配列の最後のキーを得る
    • array_keys — 配列のキーすべて、あるいはその一部を返す
    • array_map — 指定した配列の要素にコールバック関数を適用する
    • array_merge — ひとつまたは複数の配列をマージする
    • array_merge_recursive — 一つ以上の配列を再帰的にマージする
    • array_multisort — 複数または多次元の配列をソートする
    • array_pad — 指定長、指定した値で配列を埋める
    • array_pop — 配列の末尾から要素を取り除く
    • array_product — 配列の値の積を計算する
    • array_push — 一つ以上の要素を配列の最後に追加する
    • array_rand — 配列から一つ以上のキーをランダムに取得する
    • array_reduce — コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる
    • array_replace — 渡された配列の要素を置き換える
    • array_replace_recursive — 渡された配列の要素を再帰的に置き換える
    • array_reverse — 要素を逆順にした配列を返す
    • array_search — 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す
    • array_shift — 配列の先頭から要素を一つ取り出す
    • array_slice — 配列の一部を展開する
    • array_splice — 配列の一部を削除し、他の要素で置換する
    • array_sum — 配列の中の値の合計を計算する
    • array_udiff — データの比較にコールバック関数を用い、配列の差を計算する
    • array_udiff_assoc — データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
    • array_udiff_uassoc — データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
    • array_uintersect — データの比較にコールバック関数を用い、配列の共通項を計算する
    • array_uintersect_assoc — データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
    • array_uintersect_uassoc — データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
    • array_unique — 配列から重複した値を削除する
    • array_unshift — 一つ以上の要素を配列の最初に加える
    • array_values — 配列の全ての値を返す
    • array_walk — 配列の全ての要素にユーザー定義の関数を適用する
    • array_walk_recursive — 配列の全ての要素に、ユーザー関数を再帰的に適用する
    • arsort — 連想キーと要素との関係を維持しつつ配列を降順にソートする
    • asort — 連想キーと要素との関係を維持しつつ配列を昇順にソートする
    • compact — 変数名とその値から配列を作成する
    • count — 配列または Countable オブジェクトに含まれるすべての要素の数を数える
    • current — 配列内の現在の要素を返す
    • each — 配列から現在のキーと値のペアを返して、カーソルを進める
    • end — 配列の内部ポインタを最終要素にセットする
    • extract — 配列からシンボルテーブルに変数をインポートする
    • in_array — 配列に値があるかチェックする
    • key — 配列からキーを取り出す
    • key_exists — array_key_exists のエイリアス
    • krsort — 配列をキーで降順にソートする
    • ksort — 配列をキーで昇順にソートする
    • list — 配列と同様の形式で、複数の変数への代入を行う
    • natcasesort — 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする
    • natsort — "自然順"アルゴリズムで配列をソートする
    • next — 配列の内部ポインタを進める
    • pos — current のエイリアス
    • prev — 内部の配列ポインタをひとつ前に戻す
    • range — ある範囲の要素を含む配列を作成する
    • reset — 配列の内部ポインタを先頭の要素にセットする
    • rsort — 配列を降順にソートする
    • shuffle — 配列をシャッフルする
    • sizeof — count のエイリアス
    • sort — 配列を昇順にソートする
    • uasort — ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する
    • uksort — ユーザー定義の比較関数を用いて、キーで配列をソートする
    • usort — ユーザー定義の比較関数を使用して、配列を値でソートする


はじめに

これらの関数により様々な手法で配列にアクセスし、操作することが可能になります。 配列は、変数の組を保存、管理、操作する基本的な要素です。

通常の配列および多次元配列がサポートされており、ユーザーが定義したり、 他の関数で作成することも可能です。いくつかのデータベース処理関数は、 データベースのクエリから配列を返しますし、いくつかの関数は配列を返します。

PHP での配列の実装や使用方法の詳細については、マニュアルの 配列に関する節を参照ください。 その他の配列の操作方法については、 配列演算子 も参照ください。


定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

CASE_LOWER (int)
CASE_LOWERは、 array_change_key_case()で使用され、 配列のキーを小文字に変換するために使用されます。小文字は、 array_change_key_case()のデフォルトのケースで もあります。PHP 8.2.0 以降では、ASCII 文字のみが変換されます。
CASE_UPPER (int)
CASE_UPPERは、 array_change_key_case()で使用され、配列のキー を大文字に変換するために使用されます。 PHP 8.2.0 以降では、ASCII 文字のみが変換されます。

ソース順のフラグ:

SORT_ASC (int)
SORT_ASCは、 array_multisort()でソート順を昇順にするために 使用されます。
SORT_DESC (int) (integer)
SORT_DESCは、 array_multisort()でソート順を降順にするために 使用されます。

ソート型のフラグ: 種々のソート関数で使用されます

SORT_REGULAR (int)
SORT_REGULARは通常の比較するために使用され ます。
SORT_NUMERIC (int)
SORT_NUMERICは数値で比較を行うために使用さ れます。
SORT_STRING (int)
SORT_STRINGは文字列として比較を行うために使 用されます。
SORT_LOCALE_STRING (int)
SORT_LOCALE_STRINGは現在のロケールに基づいた 文字列として比較を行うために使用されます。
SORT_NATURAL (int)
SORT_NATURAL は、要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
SORT_FLAG_CASE (int)
SORT_FLAG_CASE は SORT_STRING や SORT_NATURAL と (ビット OR で) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。 PHP 8.2.0 以降では、ASCII のケースフォールディングのみが行われます。

フィルターのフラグ

ARRAY_FILTER_USE_KEY (int)
ARRAY_FILTER_USE_KEY は array_filter() で使うもので、 各キーをコールバック関数の最初の引数として渡すよう指示します。
ARRAY_FILTER_USE_BOTH (int)
ARRAY_FILTER_USE_BOTH は array_filter() で使うもので、 値とキーの両方をコールバック関数の引数として渡すよう指示します。

COUNT_NORMAL (int)
COUNT_RECURSIVE (int)
EXTR_OVERWRITE (int)
EXTR_SKIP (int)
EXTR_PREFIX_SAME (int)
EXTR_PREFIX_ALL (int)
EXTR_PREFIX_INVALID (int)
EXTR_PREFIX_IF_EXISTS (int)
EXTR_IF_EXISTS (int)
EXTR_REFS (int)


配列のソート

PHP には配列をソートする関数が複数用意されています。 このページでは、それらの違いについて説明します。

主な相違点は次のとおりです。

  • 配列のキーでソートするものと、値でソートするものがあります。 $array['キー'] = '値';
  • キーと値の相関関係をソート後にも保持するものと保持しないものがあります。 保持しないものは、ソート後にキーを (0,1,2 ... と) 振りなおします。
  • ソート順による違いがあります。アルファベット順、 昇順、降順、自然順、ランダム、ユーザー定義の順などです。
  • 注意: ソート関数は、すべて配列自身を直接変更します。 ソートした配列を新しく作って返すわけではありません。
  • これらのソート関数でふたつのメンバーが等しいと判断された場合、 それらの順番は保持されます。 PHP 8.0.0 より前のバージョンでは、 それらの並び順は未定義でした(並び順が場合によって変わる可能性がありました)。

ソート関数の特性
関数名 | ソートの基準 | キーと値の相関関係 | ソート順 | 関連する関数
array_multisort() | 値 | 文字列がキーの場合は維持し、数値添字配列の場合は維持しない | 最初の配列、あるいはソートオプション | array_walk()
asort() | 値 | 維持する | 昇順 | arsort()
arsort() | 値 | 維持する | 降順 | asort()
krsort() | キー | 維持する | 降順 | ksort()
ksort() | キー | 維持する | 昇順 | krsort()
natcasesort() | 値 | 維持する | 大文字小文字を区別しない自然順 | natsort()
natsort() | 値 | 維持する | 自然順 | natcasesort()
rsort() | 値 | 維持しない | 降順 | sort()
shuffle() | 値 | 維持しない | ランダム | array_rand()
sort() | 値 | 維持しない | 昇順 | rsort()
uasort() | 値 | 維持する | ユーザー定義 | uksort()
uksort() | キー | 維持する | ユーザー定義 | uasort()
usort() | 値 | 維持しない | ユーザー定義 | uasort()


配列 関数

参考

is_array(), explode(),
implode(),
preg_split(), および join()
も参照ください。

目次

  • array — 配列を生成する
  • array_change_key_case — 配列のすべてのキーの大文字小文字を変更する
  • array_chunk — 配列を分割する
  • array_column — 入力配列から単一のカラムの値を返す
  • array_combine — 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する
  • array_count_values — 配列内に存在する、異なる値の出現回数を数える
  • array_diff — 配列の差を計算する
  • array_diff_assoc — 追加された添字の確認を含めて配列の差を計算する
  • array_diff_key — キーを基準にして配列の差を計算する
  • array_diff_uassoc — ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_diff_ukey — キーを基準にし、コールバック関数を用いて配列の差を計算する
  • array_fill — 配列を指定した値で埋める
  • array_fill_keys — キーを指定して、配列を値で埋める
  • array_filter — コールバック関数を使用して、配列の要素をフィルタリングする
  • array_flip — 配列のキーと値を反転する
  • array_intersect — 配列の共通項を計算する
  • array_intersect_assoc — 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_key — キーを基準にして配列の共通項を計算する
  • array_intersect_uassoc — 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_intersect_ukey — キーを基準にし、コールバック関数を用いて 配列の共通項を計算する
  • array_is_list — 指定された配列がリストかどうかをチェックする
  • array_key_exists — 指定したキーまたは添字が配列にあるかどうかを調べる
  • array_key_first — 配列の最初のキーを得る
  • array_key_last — 配列の最後のキーを得る
  • array_keys — 配列のキーすべて、あるいはその一部を返す
  • array_map — 指定した配列の要素にコールバック関数を適用する
  • array_merge — ひとつまたは複数の配列をマージする
  • array_merge_recursive — 一つ以上の配列を再帰的にマージする
  • array_multisort — 複数または多次元の配列をソートする
  • array_pad — 指定長、指定した値で配列を埋める
  • array_pop — 配列の末尾から要素を取り除く
  • array_product — 配列の値の積を計算する
  • array_push — 一つ以上の要素を配列の最後に追加する
  • array_rand — 配列から一つ以上のキーをランダムに取得する
  • array_reduce — コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる
  • array_replace — 渡された配列の要素を置き換える
  • array_replace_recursive — 渡された配列の要素を再帰的に置き換える
  • array_reverse — 要素を逆順にした配列を返す
  • array_search — 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す
  • array_shift — 配列の先頭から要素を一つ取り出す
  • array_slice — 配列の一部を展開する
  • array_splice — 配列の一部を削除し、他の要素で置換する
  • array_sum — 配列の中の値の合計を計算する
  • array_udiff — データの比較にコールバック関数を用い、配列の差を計算する
  • array_udiff_assoc — データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc — データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_uintersect — データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_uintersect_assoc — データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc — データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_unique — 配列から重複した値を削除する
  • array_unshift — 一つ以上の要素を配列の最初に加える
  • array_values — 配列の全ての値を返す
  • array_walk — 配列の全ての要素にユーザー定義の関数を適用する
  • array_walk_recursive — 配列の全ての要素に、ユーザー関数を再帰的に適用する
  • arsort — 連想キーと要素との関係を維持しつつ配列を降順にソートする
  • asort — 連想キーと要素との関係を維持しつつ配列を昇順にソートする
  • compact — 変数名とその値から配列を作成する
  • count — 配列または Countable オブジェクトに含まれるすべての要素の数を数える
  • current — 配列内の現在の要素を返す
  • each — 配列から現在のキーと値のペアを返して、カーソルを進める
  • end — 配列の内部ポインタを最終要素にセットする
  • extract — 配列からシンボルテーブルに変数をインポートする
  • in_array — 配列に値があるかチェックする
  • key — 配列からキーを取り出す
  • key_exists — array_key_exists のエイリアス
  • krsort — 配列をキーで降順にソートする
  • ksort — 配列をキーで昇順にソートする
  • list — 配列と同様の形式で、複数の変数への代入を行う
  • natcasesort — 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする
  • natsort — "自然順"アルゴリズムで配列をソートする
  • next — 配列の内部ポインタを進める
  • pos — current のエイリアス
  • prev — 内部の配列ポインタをひとつ前に戻す
  • range — ある範囲の要素を含む配列を作成する
  • reset — 配列の内部ポインタを先頭の要素にセットする
  • rsort — 配列を降順にソートする
  • shuffle — 配列をシャッフルする
  • sizeof — count のエイリアス
  • sort — 配列を昇順にソートする
  • uasort — ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する
  • uksort — ユーザー定義の比較関数を用いて、キーで配列をソートする
  • usort — ユーザー定義の比較関数を使用して、配列を値でソートする


配列を生成する

  • ≪ 配列 関数
  • array_change_key_case ≫
  • PHP Manual
  • 配列 関数
  • 配列を生成する

array

(PHP 4, PHP 5, PHP 7, PHP 8)

array — 配列を生成する

説明

array(mixed ...$values): array

配列を作成します。 配列に関するより詳しい情報は配列型 のセクションをご覧ください。

パラメータ

values

カンマで区切った構文 "index => values" で、インデックスと値を定義します。 インデックスは文字列または数値とすることが可能です。 インデックスが省略された場合、0から始まる整数インデックスが自動的に生成されます。 インデックスが整数の場合、次に生成されるインデックスは、 整数インデックスの最大値 + 1 となります。同じインデックスを二度定義した場合、 後の定義により最初の定義が上書きされることに注意してください。

一般的ではありませんが、 最後に定義された配列エントリの後に続くカンマがある場合、 これは有効な構文です。

戻り値

パラメータの配列を返します。パラメータには、 =>演算子によりインデックスを指定することもできます。 配列に関するより詳しい情報は配列型 のセクションをご覧ください。

例

以下の例では、二次元配列の生成方法、連想配列のキーの指定方法、 および通常の配列において添字番号をスキップし、 それに続く要素にアクセスする方法についてご紹介しています。

例1 array() の例

<?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")
);
?>

例2 array() における自動インデックス

<?php
$array = array(1, 1, 1, 1, 1, 8 => 1, 4 => 1, 19, 3 => 13);
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [0] => 1
    [1] => 1
    [2] => 1
    [3] => 13
    [4] => 1
    [8] => 1
    [9] => 19
)

インデックス '3' は二度定義されており、後の値 13 が保持されることに注意してください。 インデックス 4 はインデックス 8 の後に定義され、 次に生成されるインデックス (値は 19) は、最大のインデックスが 8 であるため、9 となります。

次の例は、1 から始まる配列を作成します。

例3 array() で 1 から始まる配列を作成

<?php
$firstquarter = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>

上の例の出力は以下となります。

Array
(
    [1] => January
    [2] => February
    [3] => March
)

Perl では、ダブルクオートで囲まれた配列の値にアクセスすることができます。 しかしながら、PHP では配列を中括弧で囲む必要があります。

例4 ダブルクオートで囲まれた配列にアクセスする

<?php

$foo = array('bar' => 'baz');
echo "Hello {$foo['bar']}!"; // Hello baz!

?>

注意

注意:

array()は、実際にはリテラル配列を表現するための 言語構造であり、通常の関数ではありません。

参考

  • array_pad() - 指定長、指定した値で配列を埋める
  • list() - 配列と同様の形式で、複数の変数への代入を行う
  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える
  • range() - ある範囲の要素を含む配列を作成する
  • foreach
  • array 型


配列のすべてのキーの大文字小文字を変更する

  • ≪ array
  • array_chunk ≫
  • PHP Manual
  • 配列 関数
  • 配列のすべてのキーの大文字小文字を変更する

array_change_key_case

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

array_change_key_case — 配列のすべてのキーの大文字小文字を変更する

説明

array_change_key_case(array $array, int $case = CASE_LOWER): array

array のすべてのキーを小文字あるいは大文字にした配列を返します。 数値添字はそのままとなります。

パラメータ

array

処理を行う配列。

case

CASE_UPPER あるいは CASE_LOWER (デフォルト)。

戻り値

すべてのキーを小文字あるいは大文字にした配列を返します。

例

例1 array_change_key_case() の例

<?php
$input_array = array("FirSt" => 1, "SecOnd" => 4);
print_r(array_change_key_case($input_array, CASE_UPPER));
?>

上の例の出力は以下となります。

Array
(
    [FIRST] => 1
    [SECOND] => 4
)

注意

注意:

配列の添字に、この関数を使うことによって同じになってしまうものがある場合 (例: "keY" と "kEY")、 配列の後のほうにある値が他の値を上書きします。


配列を分割する

  • ≪ array_change_key_case
  • array_column ≫
  • PHP Manual
  • 配列 関数
  • 配列を分割する

array_chunk

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

array_chunk — 配列を分割する

説明

array_chunk(array $array, int $length, bool $preserve_keys = false): array

配列を、要素数が length の配列に分割します。 最後の部分の要素数は length より小さくなることもあります。

パラメータ

array

処理を行う配列。

length

各部分のサイズ。

preserve_keys

true の場合はキーをそのまま保持します。 デフォルトは false で、各部分のキーをあらためて数字で振りなおします。

戻り値

数値添字の多次元配列を返します。添え字はゼロから始まり、 各次元の要素数が length となります。

エラー / 例外

length が 1 より小さい場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | length が 1 より小さい場合、ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、 null を返していました。

例

例1 array_chunk() の例

<?php
$input_array = array('a', 'b', 'c', 'd', 'e');
print_r(array_chunk($input_array, 2));
print_r(array_chunk($input_array, 2, true));
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => a
            [1] => b
        )

    [1] => Array
        (
            [0] => c
            [1] => d
        )

    [2] => Array
        (
            [0] => e
        )

)
Array
(
    [0] => Array
        (
            [0] => a
            [1] => b
        )

    [1] => Array
        (
            [2] => c
            [3] => d
        )

    [2] => Array
        (
            [4] => e
        )

)

参考

  • array_slice() - 配列の一部を展開する


入力配列から単一のカラムの値を返す

  • ≪ array_chunk
  • array_combine ≫
  • PHP Manual
  • 配列 関数
  • 入力配列から単一のカラムの値を返す

array_column

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

array_column — 入力配列から単一のカラムの値を返す

説明

array_column(array $array, int|string|null $column_key, int|string|null $index_key = null): array

array_column() は、 配列 array の中から column_key で指定した単一のカラムの値を返します。 オプションで index_key も指定できます。 これを指定すると、 入力配列内のカラム index_key の値をキーとし、 カラム column_key を値とした配列が返されます。

パラメータ

array

値を取り出したい多次元配列 (あるいはオブジェクトの配列)。 オブジェクトの配列を指定した場合は、public プロパティはそのまま取得できます。 protected や private なプロパティを取得したい場合は、そのクラスがマジックメソッド __get() および __isset() を実装している必要があります。

column_key

値を返したいカラム。 取得したいカラムの番号を整数値で指定することもできるし、 連想配列のキーやプロパティの名前を指定することもできます。 null を指定すると、配列やオブジェクト全体を返します (index_key との組み合わせで、配列の並べ替えをするときに便利です)。

index_key

返す配列のインデックス/キーとして使うカラム。 カラム番号を表す整数値、あるいはキーの名前を表す文字列になります。 この値は、いつものように配列のキーとして キャストされます。 (PHP 8.0.0 より前のバージョンでは、 文字列への変換をサポートしているオブジェクトも許可されていました)

戻り値

入力配列の単一のカラムを表す値の配列を返します。

変更履歴

バージョン | 説明
8.0.0 | index_key で指定されたカラムにオブジェクトが含まれていても、 文字列にキャストされなくなりました。 代わりに、TypeError が発生するようになっています。

例

例1 レコードセットからのファーストネームの取得

<?php
// データベースから返ってきたレコードセットの例
$records = array(
array(
'id' => 2135,
'first_name' => 'John',
'last_name' => 'Doe',
),
array(
'id' => 3245,
'first_name' => 'Sally',
'last_name' => 'Smith',
),
array(
'id' => 5342,
'first_name' => 'Jane',
'last_name' => 'Jones',
),
array(
'id' => 5623,
'first_name' => 'Peter',
'last_name' => 'Doe',
)
);

$first_names = array_column($records, 'first_name');
print_r($first_names);
?>

上の例の出力は以下となります。

Array
(
    [0] => John
    [1] => Sally
    [2] => Jane
    [3] => Peter
)

例2 レコードセットから姓を取得し、"id"で並べ替える例

<?php
// 先ほどの例と同じ $records 配列を使います
$last_names = array_column($records, 'last_name', 'id');
print_r($last_names);
?>

上の例の出力は以下となります。

Array
(
    [2135] => Doe
    [3245] => Smith
    [5342] => Jones
    [5623] => Doe
)

例3 オブジェクトの public プロパティ "username" からユーザー名を取得する例

<?php

class User
{
public $username;

public function __construct(string $username)
{
$this->username = $username;
}
}

$users = [
new User('user 1'),
new User('user 2'),
new User('user 3'),
];

print_r(array_column($users, 'username'));
?>

上の例の出力は以下となります。

Array
(
    [0] => user 1
    [1] => user 2
    [2] => user 3
)

例4 オブジェクトの private プロパティ "name" から、マジックメソッド __get() を使って名前を取得する例

<?php

class Person
{
private $name;

public function __construct(string $name)
{
$this->name = $name;
}

public function __get($prop)
{
return $this->$prop;
}

public function __isset($prop) : bool
{
return isset($this->$prop);
}
}

$people = [
new Person('Fred'),
new Person('Jane'),
new Person('John'),
];

print_r(array_column($people, 'name'));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fred
    [1] => Jane
    [2] => John
)
__isset() が用意されていなければ、空の配列が返されます。


一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する

  • ≪ array_column
  • array_count_values ≫
  • PHP Manual
  • 配列 関数
  • 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する

array_combine

(PHP 5, PHP 7, PHP 8)

array_combine — 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する

説明

array_combine(array $keys, array $values): array

keys 配列の値をキーとして、また values 配列の値を対応する値として生成した 配列 を作成します。

パラメータ

keys

キーとして使用する配列。無効な値を渡すと文字列に変換されます。

values

値として使用する配列。

戻り値

作成した配列を返します。

エラー / 例外

PHP 8.0.0 以降では、keys および values の要素数が一致しなかった場合は ValueError がスローされます。 それより前のバージョンでは、 E_WARNING が発生していました。

変更履歴

バージョン | 説明
8.0.0 | それぞれの配列の要素数が一致しなかった場合、 array_combine() は ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。

例

例1 array_combine()の簡単な例

<?php
$a = array('green', 'red', 'yellow');
$b = array('avocado', 'apple', 'banana');
$c = array_combine($a, $b);

print_r($c);
?>

上の例の出力は以下となります。

Array
(
    [green]  => avocado
    [red]    => apple
    [yellow] => banana
)

参考

  • array_merge() - ひとつまたは複数の配列をマージする
  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する
  • array_values() - 配列の全ての値を返す
  • array_map() - 指定した配列の要素にコールバック関数を適用する


配列内に存在する、異なる値の出現回数を数える

  • ≪ array_combine
  • array_diff ≫
  • PHP Manual
  • 配列 関数
  • 配列内に存在する、異なる値の出現回数を数える

array_count_values

(PHP 4, PHP 5, PHP 7, PHP 8)

array_count_values — 配列内に存在する、異なる値の出現回数を数える

説明

array_count_values(array $array): array

array_count_values() は、 配列 array の値 (数値または文字列でなければいけません) をキーとし、 array におけるその値の出現回数を値とした配列を返します。

パラメータ

array

値を数える配列。

戻り値

array のキーとその登場回数を組み合わせた連想配列を返します。

エラー / 例外

string あるいは int 以外の型の要素が登場するたびに E_WARNING が発生します。

例

例1 array_count_values() の例

<?php
$array = array(1, "hello", 1, "world", "hello");
print_r(array_count_values($array));
?>

上の例の出力は以下となります。

Array
(
    [1] => 2
    [hello] => 2
    [world] => 1
)

参考

  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える
  • array_unique() - 配列から重複した値を削除する
  • array_values() - 配列の全ての値を返す
  • count_chars() - 文字列で使用されている文字に関する情報を返す


配列の差を計算する

  • ≪ array_count_values
  • array_diff_assoc ≫
  • PHP Manual
  • 配列 関数
  • 配列の差を計算する

array_diff

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

array_diff — 配列の差を計算する

説明

array_diff(array $array, array ...$arrays): array

array を他の配列と比較し、 array の要素の中で他の配列には存在しないものだけを返します。

パラメータ

array

比較元の配列。

arrays

比較対象の配列。

戻り値

array のエントリのうち、他のどの配列にも含まれない要素のみを含む配列を返します。 array の配列のキーは維持されます。

変更履歴

バージョン | 説明
8.0.0 | この関数は、引数をひとつだけ渡しても呼び出せるようになりました。 これより前のバージョンでは、少なくともふたつの引数が必須でした。

例

例1 array_diff() の例

<?php
$array1 = array("a" => "green", "red", "blue", "red");
$array2 = array("b" => "green", "yellow", "red");
$result = array_diff($array1, $array2);

print_r($result);
?>

$array1 に複数存在する場合でも全て同様に処理されます。 この出力は次の通りです。

Array
(
    [1] => blue
)

例2 型が一致しない場合の array_diff() の例

(string) $elem1 === (string) $elem2 の場合のみ、 つまり、文字列表現 が同等な場合のみ、 2つの要素は等しいとみなされます。

<?php
// 以下の例は、配列が文字列にキャストできないので警告が発生します
$source = [1, 2, 3, 4];
$filter = [3, 4, [5], 6];
$result = array_diff($source, $filter);

// 一方で、以下の例は問題ありません。なぜなら、オブジェクトは文字列にキャストできるからです。
class S {
private $v;

public function __construct(string $v) {
$this->v = $v;
}

public function __toString() {
return $this->v;
}
}

$source = [new S('a'), new S('b'), new S('c')];
$filter = [new S('b'), new S('c'), new S('d')];

$result = array_diff($source, $filter);

// $result には、S('a') のインスタンスが一つ含まれます。
?>

別の比較関数を使いたい場合は、array_udiff() を参照ください。

注意

注意:

この関数は n 次元配列の一つの次元しかチェックしません。 もちろん、array_diff($array1[0], $array2[0]); のようにすることでより深い次元でのチェックもできます。

参考

  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する


追加された添字の確認を含めて配列の差を計算する

  • ≪ array_diff
  • array_diff_key ≫
  • PHP Manual
  • 配列 関数
  • 追加された添字の確認を含めて配列の差を計算する

array_diff_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

array_diff_assoc — 追加された添字の確認を含めて配列の差を計算する

説明

array_diff_assoc(array $array, array ...$arrays): array

array を arrays と比較し、 その差を返します。array_diff() とは異なり、 配列のキーも用いて比較を行います。

パラメータ

array

比較元の配列。

arrays

比較する対象となる配列。

戻り値

array の要素のうち、 その他の配列のいずれにも含まれないものだけを残した配列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、引数をひとつだけ渡しても呼び出せるようになりました。 これより前のバージョンでは、少なくともふたつの引数が必須でした。

例

例1 array_diff_assoc() の例

この例で、"a" => "green" の組が両方の配列に現れており、 このため、この関数の出力には含まれていません。 これとは異なり、0 => "red" は出力の中に現れています。 これは、最初の配列の "red" のキーには自動的に 0 が割り当てられる一方で、 二番目の配列では 0 には既に yellow というキーがあるため、 "red" には 1 が割り当てられるためです。

<?php
$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "green", "yellow", "red");
$result = array_diff_assoc($array1, $array2);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [b] => brown
    [c] => blue
    [0] => red
)

例2 array_diff_assoc() の例

key => value の組からの二つの値は、 (string) $elem1 === (string) $elem2 が成り立つ場合のみ等しいと見なされます。 言い替えると、厳密なチェックが行われるため、 文字列表現が同じである必要があります。

<?php
$array1 = array(0, 1, 2);
$array2 = array("00", "01", "2");
$result = array_diff_assoc($array1, $array2);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [0] => 0
    [1] => 1
)

注意

注意: この関数は、N 次元配列の一次元だけを調べます。例えば array_diff_assoc($array1[0], $array2[0]); とすることにより、より深い次元でチェックを行うことも可能です。

注意: 同様の配列で、より多くのキーがあるものを比較するときには、引数を正しい順で渡すようにしましょう。 新しい配列が、リストの先頭になければいけません。

参考

  • array_diff() - 配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する


キーを基準にして配列の差を計算する

  • ≪ array_diff_assoc
  • array_diff_uassoc ≫
  • PHP Manual
  • 配列 関数
  • キーを基準にして配列の差を計算する

array_diff_key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

array_diff_key — キーを基準にして配列の差を計算する

説明

array_diff_key(array $array, array ...$arrays): array

array のキーを arrays のキーと比較し、その差を返します。 この関数は array_diff() に似ていますが、 値ではなくキーを用いて比較するという点が異なります。

パラメータ

array

比較元の配列。

arrays

比較する対象となる配列。

戻り値

array の要素のうち、 その他の配列のいずれにも含まれないキーのものだけを残した配列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、引数をひとつだけ渡しても呼び出せるようになりました。 これより前のバージョンでは、少なくともふたつの引数が必須でした。

例

例1 array_diff_key() の例

ふたつの key => value のペアが等しいとみなされるのは、 (string) $key1 === (string) $key2 である場合のみです。つまり、厳密な型チェックを行うということです。 文字列表現が一致しなければなりません。

<?php
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'yellow' => 7, 'cyan' => 8);

var_dump(array_diff_key($array1, $array2));
?>

上の例の出力は以下となります。

array(3) {
  ["blue"]=>
  int(1)
  ["red"]=>
  int(2)
  ["purple"]=>
  int(4)
}
<?php
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'yellow' => 7, 'cyan' => 8);
$array3 = array('blue' => 6, 'yellow' => 7, 'mauve' => 8);

var_dump(array_diff_key($array1, $array2, $array3));
?>

上の例の出力は以下となります。

array(2) {
  ["red"]=>
  int(2)
  ["purple"]=>
  int(4)
}

注意

注意:

この関数は n 次元配列の一つの次元しかチェックしません。 もちろん、array_diff_key($array1[0], $array2[0]); のようにすることでより深い次元でのチェックもできます。

参考

  • array_diff() - 配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_diff_ukey() - キーを基準にし、コールバック関数を用いて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_intersect_key() - キーを基準にして配列の共通項を計算する
  • array_intersect_ukey() - キーを基準にし、コールバック関数を用いて 配列の共通項を計算する


ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する

  • ≪ array_diff_key
  • array_diff_ukey ≫
  • PHP Manual
  • 配列 関数
  • ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する

array_diff_uassoc

(PHP 5, PHP 7, PHP 8)

array_diff_uassoc — ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する

説明

array_diff_uassoc(array $array, array ...$arrays, callable $key_compare_func): array

array のキーを arrays のキーと比較し、その差を返します。 この関数は array_diff() に似ていますが、 配列のキーを用いて比較するという点が異なります。

array_diff_assoc() とは異なり、 内部関数ではなくユーザーが指定したコールバック関数を用いて添字を比較します。

パラメータ

array

比較元の配列。

arrays

比較する対象となる配列。

key_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

array の要素のうち、 その他の配列のいずれにも含まれないものだけを残した配列を返します。

例

例1 array_diff_uassoc() の例

この例では、"a" => "green" の組み合わせが両方の配列に存在し、 関数の出力には存在しないことが確認できます。 これとは異なり、0 => "red" は出力されています。 これは、最初の配列の "red" のキーには自動的に 0 が割り当てられる一方で、 二番目の配列では 0 には既に yellow というキーがあるため、 "red" には 1 が割り当てられるためです。

<?php
function key_compare_func($a, $b)
{
if ($a === $b) {
return 0;
}
return ($a > $b)? 1:-1;
}

$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "green", "yellow", "red");
$result = array_diff_uassoc($array1, $array2, "key_compare_func");
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [b] => brown
    [c] => blue
    [0] => red
)

2 つのインデックスが等しいかどうかは、 ユーザーが指定したコールバック関数で調べます。

注意

注意:

この関数は n 次元配列の一つの次元しかチェックしません。 array_diff_uassoc($array1[0], $array2[0], "key_compare_func"); のようにすることで、より深い次元でのチェックもできます。

参考

  • array_diff() - 配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_uintersect() - データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


キーを基準にし、コールバック関数を用いて配列の差を計算する

  • ≪ array_diff_uassoc
  • array_fill ≫
  • PHP Manual
  • 配列 関数
  • キーを基準にし、コールバック関数を用いて配列の差を計算する

array_diff_ukey

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

array_diff_ukey — キーを基準にし、コールバック関数を用いて配列の差を計算する

説明

array_diff_ukey(array $array, array ...$arrays, callable $key_compare_func): array

array のキーを arrays のキーと比較し、その差を返します。 この関数は array_diff() に似ていますが、 値ではなくキーを用いて比較するという点が異なります。

array_diff_key() とは異なり、 内部関数ではなくユーザーが指定したコールバック関数を用いて添字を比較します。

パラメータ

array

比較元の配列。

arrays

比較する対象となる配列。

key_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

array の要素のうち、 その他の配列のいずれにも含まれないものだけを残した配列を返します。

例

例1 array_diff_ukey() の例

<?php
function key_compare_func($key1, $key2)
{
if ($key1 == $key2)
return 0;
else if ($key1 > $key2)
return 1;
else
return -1;
}

$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);

var_dump(array_diff_ukey($array1, $array2, 'key_compare_func'));
?>

上の例の出力は以下となります。

array(2) {
  ["red"]=>
  int(2)
  ["purple"]=>
  int(4)
}

注意

注意:

この関数は n 次元配列の一つの次元しかチェックしません。 もちろん、array_diff_ukey($array1[0], $array2[0], 'callback_func'); のようにすることでより深い次元でのチェックもできます。

参考

  • array_diff() - 配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_diff_key() - キーを基準にして配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_intersect_key() - キーを基準にして配列の共通項を計算する
  • array_intersect_ukey() - キーを基準にし、コールバック関数を用いて 配列の共通項を計算する


配列を指定した値で埋める

  • ≪ array_diff_ukey
  • array_fill_keys ≫
  • PHP Manual
  • 配列 関数
  • 配列を指定した値で埋める

array_fill

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

array_fill — 配列を指定した値で埋める

説明

array_fill(int $start_index, int $count, mixed $value): array

パラメータ value を値とする count 個のエントリからなる配列を埋めます。 この際、キーは、start_index パラメータから開始します。

パラメータ

start_index

返される配列の最初のインデックス。

PHP 8.0.0 より前のバージョンでは、 start_index が負の場合、 返される配列の最初のインデックスが start_index となり、それ以降のインデックスはゼロから始まっていました。 PHP 8.0.0 以降のバージョンでは、 start_index が負の場合でも、 インデックスの値が通常通りインクリメントされるようになっています。 (例を参照ください)。

count

挿入する要素数。 ゼロ以上の数でなければなりません。 かつ、2147483647 以下である必要があります。

value

要素に使用する値。

戻り値

値を埋めた配列を返します。

エラー / 例外

count が範囲外の値の場合に、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | count が範囲外の値の場合に、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、false を返していました。

例

例1 array_fill() の例

<?php
$a = array_fill(5, 6, 'banana');
print_r($a);
?>

上の例の出力は以下となります。

Array
(
    [5]  => banana
    [6]  => banana
    [7]  => banana
    [8]  => banana
    [9]  => banana
    [10] => banana
)

例2 最初のインデックスが負の場合の、array_fill() の例

<?php
$a = array_fill(-2, 4, 'pear');
print_r($a);
?>

上の例の PHP 7 での出力は、このようになります。

Array
(
    [-2] => pear
    [0] => pear
    [1] => pear
    [2] => pear
)

上の例の PHP 8 での出力は、このようになります。:

Array
(
    [-2] => pear
    [-1] => pear
    [0] => pear
    [1] => pear
)

PHP 8.0.0 より前のバージョンでは、 -1 が存在していないことに注意しましょう。

注意

負の値をキーに指定した場合についての詳細な説明は、マニュアルの 配列 のセクションを参照ください。

参考

  • array_fill_keys() - キーを指定して、配列を値で埋める
  • str_repeat() - 文字列を反復する
  • range() - ある範囲の要素を含む配列を作成する


キーを指定して、配列を値で埋める

  • ≪ array_fill
  • array_filter ≫
  • PHP Manual
  • 配列 関数
  • キーを指定して、配列を値で埋める

array_fill_keys

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

array_fill_keys — キーを指定して、配列を値で埋める

説明

array_fill_keys(array $keys, mixed $value): array

パラメータ value で指定した値で配列を埋めます。 キーとして、配列 keys で指定した値を使用します。

パラメータ

keys

キーとして使用する値の配列。キーとして無効な値は string に変換されます。

value

埋めたい値。

戻り値

値を埋めた配列を返します。

例

例1 array_fill_keys() の例

<?php
$keys = array('foo', 5, 10, 'bar');
$a = array_fill_keys($keys, 'banana');
print_r($a);
?>

上の例の出力は以下となります。

Array
(
    [foo] => banana
    [5] => banana
    [10] => banana
    [bar] => banana
)

参考

  • array_fill() - 配列を指定した値で埋める
  • array_combine() - 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する


コールバック関数を使用して、配列の要素をフィルタリングする

  • ≪ array_fill_keys
  • array_flip ≫
  • PHP Manual
  • 配列 関数
  • コールバック関数を使用して、配列の要素をフィルタリングする

array_filter

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

array_filter — コールバック関数を使用して、配列の要素をフィルタリングする

説明

array_filter(array $array, ?callable $callback = null, int $mode = 0): array

callback 関数によりフィルタ処理が行われた array の全ての要素を含む配列を返します。 callback 関数が true を返した場合、 array の現在の値が結果の配列に入ります。

配列のキーは保存されます。 array にインデックスが振られていた場合、結果が異なる場合があります。 結果の array のインデックスは、 array_values() 関数を使って振り直すことができます。

パラメータ

array

処理する配列。

callback

使用するコールバック関数。

コールバック関数が与えられなかった場合、 array のエントリの中で空のものはすべて削除されます。 この場合の「空」の定義については、empty() 関数を参照ください。

mode

引数として、何を callback に送るのかを決めるフラグ。

  • ARRAY_FILTER_USE_KEY - 値ではなく、キーだけを callback の引数として渡す
  • ARRAY_FILTER_USE_BOTH - 値だけではなく、値とキーの両方を callback の引数として渡す
デフォルトは 0 で値のみをcallbackの引数として渡します。

戻り値

フィルタリングされた結果の配列を返します。

変更履歴

バージョン | 説明
8.0.0 | callback は、nullable になりました。
8.0.0 | callback がリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 array_filter() の例

<?php
function odd($var)
{
// 渡された整数が奇数かどうかを返します
return $var & 1;
}

function even($var)
{
// 渡された整数が偶数かどうかを返します
return !($var & 1);
}

$array1 = ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5];
$array2 = [6, 7, 8, 9, 10, 11, 12];

echo "Odd :\n";
print_r(array_filter($array1, "odd"));
echo "Even:\n";
print_r(array_filter($array2, "even"));
?>

上の例の出力は以下となります。

Odd :
Array
(
    [a] => 1
    [c] => 3
    [e] => 5
)
Even:
Array
(
    [0] => 6
    [2] => 8
    [4] => 10
    [6] => 12
)

例2 callback がない array_filter()

<?php

$entry = [
0 => 'foo',
1 => false,
2 => -1,
3 => null,
4 => '',
5 => '0',
6 => 0,
];

print_r(array_filter($entry));
?>

上の例の出力は以下となります。

Array
(
    [0] => foo
    [2] => -1
)

例3 array_filter() で mode を使う例

<?php

$arr = ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4];

var_dump(array_filter($arr, function($k) {
return $k == 'b';
}, ARRAY_FILTER_USE_KEY));

var_dump(array_filter($arr, function($v, $k) {
return $k == 'b' || $v == 4;
}, ARRAY_FILTER_USE_BOTH));
?>

上の例の出力は以下となります。

array(1) {
  ["b"]=>
  int(2)
}
array(2) {
  ["b"]=>
  int(2)
  ["d"]=>
  int(4)
}

注意

警告

配列の内容がコールバック関数内で変更された場合 (たとえば要素が追加されたりunsetされたりなど) のこの関数の挙動は未定義です。

参考

  • array_intersect() - 配列の共通項を計算する
  • array_map() - 指定した配列の要素にコールバック関数を適用する
  • array_reduce() - コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる
  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する


配列のキーと値を反転する

  • ≪ array_filter
  • array_intersect ≫
  • PHP Manual
  • 配列 関数
  • 配列のキーと値を反転する

array_flip

(PHP 4, PHP 5, PHP 7, PHP 8)

array_flip — 配列のキーと値を反転する

説明

array_flip(array $array): array

array_flip() は、配列を反転して返します。 すなわち、array のキーが値となり、 array の値がキーとなります。

array の値は有効なキーを必要とすることに注意してください。 すなわち、キーは、int または string である必要があります。ある値が間違った型である場合、 警告が出力され、問題のこのキー/値の組は結果には含まれません。

ある値が複数回出現した場合、最後のキーがその値として使用され、 その他の値は失われます。

パラメータ

array

反転を行うキー/値の組。

戻り値

反転した配列を返します。

例

例1 array_flip() の例

<?php
$input = array("oranges", "apples", "pears");
$flipped = array_flip($input);

print_r($flipped);
?>

上の例の出力は以下となります。

Array
(
    [oranges] => 0
    [apples] => 1
    [pears] => 2
)

例2 array_flip() の例 : 衝突

<?php
$input = array("a" => 1, "b" => 1, "c" => 2);
$flipped = array_flip($input);

print_r($flipped);
?>

上の例の出力は以下となります。

Array
(
    [1] => b
    [2] => c
)

参考

  • array_values() - 配列の全ての値を返す
  • array_keys() - 配列のキーすべて、あるいはその一部を返す
  • array_reverse() - 要素を逆順にした配列を返す


配列の共通項を計算する

  • ≪ array_flip
  • array_intersect_assoc ≫
  • PHP Manual
  • 配列 関数
  • 配列の共通項を計算する

array_intersect

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

array_intersect — 配列の共通項を計算する

説明

array_intersect(array $array, array ...$arrays): array

array_intersect() は、他の全ての引数に存在する array の値を全て有する配列を返します。 キーと値の関係は維持されることに注意してください。

パラメータ

array

値を調べるもととなる配列。

arrays

値を比較する対象となる配列。

戻り値

array の値のうち、 すべての引数に存在する値のものを含む連想配列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、引数をひとつだけ渡しても呼び出せるようになりました。 これより前のバージョンでは、少なくともふたつの引数が必須でした。

例

例1 array_intersect() の例

<?php
$array1 = array("a" => "green", "red", "blue");
$array2 = array("b" => "green", "yellow", "red");
$result = array_intersect($array1, $array2);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [a] => green
    [0] => red
)

注意

注意: 二つの要素は、 (string) $elem1 === (string) $elem2 の場合のみ等しいとみなされます。言い換えると、文字列表現が同じ場合となります。

参考

  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_diff() - 配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する


追加された添字の確認も含めて配列の共通項を確認する

  • ≪ array_intersect
  • array_intersect_key ≫
  • PHP Manual
  • 配列 関数
  • 追加された添字の確認も含めて配列の共通項を確認する

array_intersect_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

array_intersect_assoc — 追加された添字の確認も含めて配列の共通項を確認する

説明

array_intersect_assoc(array $array, array ...$arrays): array

array_intersect_assoc() は、全ての引数に現れる array の全ての値を含む配列を返します。 array_intersect() と異なり、 キーも比較に使用されることに注意してください。

パラメータ

array

値を調べるもととなる配列。

arrays

値を比較する対象となる配列。

戻り値

array の値のうち、すべての引数に存在するものを含む連想配列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、引数をひとつだけ渡しても呼び出せるようになりました。 これより前のバージョンでは、少なくともふたつの引数が必須でした。

例

例1 array_intersect_assoc() の例

<?php
$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "green", "b" => "yellow", "blue", "red");
$result_array = array_intersect_assoc($array1, $array2);
print_r($result_array);
?>

上の例の出力は以下となります。

Array
(
    [a] => green
)

上の例で、"a" => "green" の組のみが両方の配列に現れており、 よって配列として返されていることがわかります。 値 "red" は返されません。これは、 $array1 においてはそのキーが 0 であり、一方、$array2 においてはキーが 1 であるためです。 また、キー "b" は返されません。 これは、その値がそれぞれの配列で異なるためです。

key => value の組からの二つの値は、 (string) $elem1 === (string) $elem2 が成り立つ場合にのみ等しいと見なされます。 言い替えると、厳密なチェックが行われるため、 文字列表現が同じである必要があります。

参考

  • array_intersect() - 配列の共通項を計算する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_diff() - 配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する


キーを基準にして配列の共通項を計算する

  • ≪ array_intersect_assoc
  • array_intersect_uassoc ≫
  • PHP Manual
  • 配列 関数
  • キーを基準にして配列の共通項を計算する

array_intersect_key

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

array_intersect_key — キーを基準にして配列の共通項を計算する

説明

array_intersect_key(array $array, array ...$arrays): array

array_intersect_key() は、 array のエントリのうち、 その他のすべての引数の中に共通して存在するキーと一致するキーの値からなる配列を返します。

パラメータ

array

値を調べるもととなる配列。

arrays

キーを比較する対象となる配列。

戻り値

array のエントリのうち、 すべての引数に存在するキーのものを含む連想配列を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、引数をひとつだけ渡しても呼び出せるようになりました。 これより前のバージョンでは、少なくともふたつの引数が必須でした。

例

例1 array_intersect_key() の例

<?php
$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);

var_dump(array_intersect_key($array1, $array2));
?>

上の例の出力は以下となります。

array(2) {
  ["blue"]=>
  int(1)
  ["green"]=>
  int(3)
}

この例では、両方の配列に存在するキーが 'blue' と 'green' だけであり、それが返されていることが わかります。また、ふたつの配列の間で 'blue' と 'green' に対応する値が違うことにも注意しましょう。 それでも一致していると判定されるのは、ただキーだけがチェックされているからです。 返される値は array のものです。

二つの要素は、 (string) $elem1 === (string) $elem2 の場合のみ等しいとみなされます。言い換えると、 文字列表現が同じ場合となります。

参考

  • array_diff() - 配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_diff_key() - キーを基準にして配列の差を計算する
  • array_diff_ukey() - キーを基準にし、コールバック関数を用いて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_intersect_ukey() - キーを基準にし、コールバック関数を用いて 配列の共通項を計算する


追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する

  • ≪ array_intersect_key
  • array_intersect_ukey ≫
  • PHP Manual
  • 配列 関数
  • 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する

array_intersect_uassoc

(PHP 5, PHP 7, PHP 8)

array_intersect_uassoc — 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する

説明

array_intersect_uassoc(array $array, array ...$arrays, callable $key_compare_func): array

array_intersect_uassoc() は、全ての引数に現れる array の全ての値を含む配列を返します。 array_intersect() と異なり、 キーが比較に使用されることに注意してください。

パラメータ

array

比較元となる最初の配列。

arrays

キーを比較する対象となる配列。

key_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

array の値のうち、 すべての引数に存在するもののみを返します。

例

例1 array_intersect_uassoc() の例

<?php
$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");

print_r(array_intersect_uassoc($array1, $array2, "strcasecmp"));
?>

上の例の出力は以下となります。

Array
(
    [b] => brown
)

参考

  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_intersect_key() - キーを基準にして配列の共通項を計算する
  • array_intersect_ukey() - キーを基準にし、コールバック関数を用いて 配列の共通項を計算する


キーを基準にし、コールバック関数を用いて 配列の共通項を計算する

  • ≪ array_intersect_uassoc
  • array_is_list ≫
  • PHP Manual
  • 配列 関数
  • キーを基準にし、コールバック関数を用いて 配列の共通項を計算する

array_intersect_ukey

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

array_intersect_ukey — キーを基準にし、コールバック関数を用いて 配列の共通項を計算する

説明

array_intersect_ukey(array $array, array ...$arrays, callable $key_compare_func): array

array_intersect_ukey() は、他の全ての引数に存在する array の値を全て有する配列を返します。

パラメータ

array

比較元となる最初の配列。

arrays

キーを比較する対象となる配列。

key_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

array の値のうち、 すべての引数に存在するキーのものを含む連想配列を返します。

例

例1 array_intersect_ukey() の例

<?php
function key_compare_func($key1, $key2)
{
if ($key1 == $key2)
return 0;
else if ($key1 > $key2)
return 1;
else
return -1;
}

$array1 = array('blue' => 1, 'red' => 2, 'green' => 3, 'purple' => 4);
$array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan' => 8);

var_dump(array_intersect_ukey($array1, $array2, 'key_compare_func'));
?>

上の例の出力は以下となります。

array(2) {
  ["blue"]=>
  int(1)
  ["green"]=>
  int(3)
}

この例では、両方の配列に存在するキーが 'blue' と 'green' だけであり、それが返されていることがわかります。 また、ふたつの配列の間で 'blue' と 'green' に対応する値が違うことにも注意しましょう。 それでも一致していると判定されるのは、ただキーだけがチェックされているからです。 返される値は array のものです。

参考

  • array_diff() - 配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_diff_key() - キーを基準にして配列の差を計算する
  • array_diff_ukey() - キーを基準にし、コールバック関数を用いて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_intersect_key() - キーを基準にして配列の共通項を計算する


指定された配列がリストかどうかをチェックする

  • ≪ array_intersect_ukey
  • array_key_exists ≫
  • PHP Manual
  • 配列 関数
  • 指定された配列がリストかどうかをチェックする

array_is_list

(PHP 8 >= 8.1.0)

array_is_list — 指定された配列がリストかどうかをチェックする

説明

array_is_list(array $array): bool

指定された array がリストかどうかを判定します。 配列のキーが連続した数値 (0 から count($array)-1) である場合、 リストと判定されます。

パラメータ

array

評価する配列。

戻り値

配列がリストと判定された場合は true を返します。 そうでない場合は false を返します。

例

例1 array_is_list() example

<?php

array_is_list([]); // true
array_is_list(['apple', 2, 3]); // true
array_is_list([0 => 'apple', 'orange']); // true

// 配列が 0 から始まっていない場合
array_is_list([1 => 'apple', 'orange']); // false

// キーの順序が正しくない場合
array_is_list([1 => 'apple', 0 => 'orange']); // false

// キーが数値でない場合
array_is_list([0 => 'apple', 'foo' => 'bar']); // false

// 数値のキーが連続していない場合
array_is_list([0 => 'apple', 2 => 'bar']); // false
?>

注意

注意:

この関数は、空の配列に対しても true を返します。

参考

  • array_values() - 配列の全ての値を返す


指定したキーまたは添字が配列にあるかどうかを調べる

  • ≪ array_is_list
  • array_key_first ≫
  • PHP Manual
  • 配列 関数
  • 指定したキーまたは添字が配列にあるかどうかを調べる

array_key_exists

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

array_key_exists — 指定したキーまたは添字が配列にあるかどうかを調べる

説明

array_key_exists(string|int|float|bool|resource|null $key, array $array): bool

指定した key が配列に設定されている場合、 array_key_exists() は true を返します。 key は配列添字として使用できる全ての値を使用可能です。

パラメータ

key

調べる値。

array

キーが存在するかどうかを調べたい配列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

注意:

array_key_exists() は、最初のレベルのキーだけを捜します。 多次元配列のネストされたキーは、この関数では見つけられません。

変更履歴

バージョン | 説明
8.0.0 | key パラメータは bool, float, int, null, resource, string を引数として受け入れるようになりました。

例

例1 array_key_exists() の例

<?php
$search_array = array('first' => 1, 'second' => 4);
if (array_key_exists('first', $search_array)) {
echo "この配列には 'first' という要素が存在します";
}
?>

例2 array_key_exists() 対 isset()

isset() は null 値を持つ配列キーに対して true を返しません。一方、array_key_exists() は true を返します。

<?php
$search_array = array('first' => null, 'second' => 4);

// false を返します
isset($search_array['first']);

// true を返します
array_key_exists('first', $search_array);
?>

注意

注意:

過去との互換性を保つため、key が仮に array で指定したオブジェクトのプロパティであっても array_key_exists() は true を返します。 この挙動は PHP 7.4.0 で非推奨となり、PHP 8.0.0 以降で削除されています。

オブジェクトのプロパティが存在するかどうかを調べるには、 property_exists() を使いましょう。

参考

  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • array_keys() - 配列のキーすべて、あるいはその一部を返す
  • in_array() - 配列に値があるかチェックする
  • property_exists() - オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる


配列の最初のキーを得る

  • ≪ array_key_exists
  • array_key_last ≫
  • PHP Manual
  • 配列 関数
  • 配列の最初のキーを得る

array_key_first

(PHP 7 >= 7.3.0, PHP 8)

array_key_first — 配列の最初のキーを得る

説明

array_key_first(array $array): int|string|null

与えられた array の最初のキーを返します。 これは内部的な配列のポインタに影響を与えません。

パラメータ

array

入力となる配列

戻り値

配列が空でなければ、 array の最初のキーを返します。 そうでなければ、null を返します。

例

例1 基本的な array_key_first() 関数の使い方

<?php
$array = ['a' => 1, 'b' => 2, 'c' => 3];

$firstKey = array_key_first($array);

var_dump($firstKey);
?>

上の例の出力は以下となります。

string(1) "a"

注意

ヒント

PHP 7.3.0 より前のバージョンでは、この関数の機能を実現する方法は複数ありました。 array_keys() を使うことも可能でしたが、 かなり非効率になる可能性があります。 reset() と key() を使うこともできますが、 配列の内部ポインタを変更する可能性があります。 この関数は、効率が良く、かつ内部ポインタを変更しないポリフィルとして書かれました。

<?php
if (!function_exists('array_key_first')) {
function array_key_first(array $arr) {
foreach($arr as $key => $unused) {
return $key;
}
return NULL;
}
}
?>

参考

  • array_key_last() - 配列の最後のキーを得る
  • reset() - 配列の内部ポインタを先頭の要素にセットする


配列の最後のキーを得る

  • ≪ array_key_first
  • array_keys ≫
  • PHP Manual
  • 配列 関数
  • 配列の最後のキーを得る

array_key_last

(PHP 7 >= 7.3.0, PHP 8)

array_key_last — 配列の最後のキーを得る

説明

array_key_last(array $array): int|string|null

与えられた array の最後のキーを返します。 これは内部的な配列のポインタに影響を与えません。

パラメータ

array

入力となる配列

戻り値

配列が空でなければ、 array の最後のキーを返します。 そうでなければ、null を返します。

参考

  • array_key_first() - 配列の最初のキーを得る
  • end() - 配列の内部ポインタを最終要素にセットする


配列のキーすべて、あるいはその一部を返す

  • ≪ array_key_last
  • array_map ≫
  • PHP Manual
  • 配列 関数
  • 配列のキーすべて、あるいはその一部を返す

array_keys

(PHP 4, PHP 5, PHP 7, PHP 8)

array_keys — 配列のキーすべて、あるいはその一部を返す

説明

array_keys(array $array): array
array_keys(array $array, mixed $filter_value, bool $strict = false): array

array_keys() は、配列 array から全てのキー (数値および文字列) を返します。

filter_value が指定された場合、 指定した値に関するキーのみが返されます。指定されない場合は、 array から全てのキーが返されます。

パラメータ

array

返すキーを含む配列。

filter_value

指定した場合は、この値を含むキーのみを返します。

strict

検索時に厳密な比較 (===) を行うかどうか。

戻り値

array のすべてのキーを配列で返します。

例

例1 array_keys() の例

<?php
$array = array(0 => 100, "color" => "red");
print_r(array_keys($array));

$array = array("blue", "red", "green", "blue", "blue");
print_r(array_keys($array, "blue"));

$array = array("color" => array("blue", "red", "green"),
"size" => array("small", "medium", "large"));
print_r(array_keys($array));
?>

上の例の出力は以下となります。

Array
(
    [0] => 0
    [1] => color
)
Array
(
    [0] => 0
    [1] => 3
    [2] => 4
)
Array
(
    [0] => color
    [1] => size
)

参考

  • array_values() - 配列の全ての値を返す
  • array_combine() - 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する
  • array_key_exists() - 指定したキーまたは添字が配列にあるかどうかを調べる
  • array_search() - 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す


指定した配列の要素にコールバック関数を適用する

  • ≪ array_keys
  • array_merge ≫
  • PHP Manual
  • 配列 関数
  • 指定した配列の要素にコールバック関数を適用する

array_map

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

array_map — 指定した配列の要素にコールバック関数を適用する

説明

array_map(?callable $callback, array $array, array ...$arrays): array

array_map() は、array (および、 それ以上の配列が与えられた場合は arrays) の各要素に callback を適用した後、 適用後の要素を含む array を返します。 callback 関数が受け付けるパラメータの数は、 array_map() に渡される配列の数に一致している必要があります。 それより配列の数が多かった場合、溢れた分は無視されます。 少なかった場合、ArgumentCountError がスローされます。

パラメータ

callback

配列の各要素に適用する callable。

複数の配列に zip 操作を行うために、 callback に null を渡すことができます。 array のみが与えられた場合、 array_map() は、入力された配列を返します。

array

コールバック関数を適用する配列。

arrays

callback に渡す引数を指定する配列の可変リスト。

戻り値

array (および、 それ以上の配列が与えられた場合は arrays) の各要素に callback 関数を適用した後、 適用後の要素を含む array を返します。

引数で渡した配列のキーがそのまま維持されるのは、渡した配列がひとつだけである場合のみです。 複数の配列を渡した場合は、戻り値の配列のキーは整数値が振り直されます。

変更履歴

バージョン | 説明
8.0.0 | callback がリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 array_map() の例

<?php
function cube($n)
{
return ($n * $n * $n);
}

$a = [1, 2, 3, 4, 5];
$b = array_map('cube', $a);
print_r($b);
?>

この例では、$b の内容は以下のようになります。

Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)

例2 array_map() でラムダ関数を使用する例

<?php
$func = function(int $value): int {
return $value * 2;
};

print_r(array_map($func, range(1, 5)));

// PHP 7.4.0 以降は、以下の書き方も出来ます:

print_r(array_map(fn($value): int => $value * 2, range(1, 5)));

?>
Array
(
    [0] => 2
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 10
)

例3 array_map() - もっと配列を使ってみる例

<?php
function show_Spanish(int $n, string $m): string
{
return "The number {$n} is called {$m} in Spanish";
}

function map_Spanish(int $n, string $m): array
{
return [$n => $m];
}

$a = [1, 2, 3, 4, 5];
$b = ['uno', 'dos', 'tres', 'cuatro', 'cinco'];

$c = array_map('show_Spanish', $a, $b);
print_r($c);

$d = array_map('map_Spanish', $a , $b);
print_r($d);
?>

上の例の出力は以下となります。

// printout of $c
Array
(
    [0] => The number 1 is called uno in Spanish
    [1] => The number 2 is called dos in Spanish
    [2] => The number 3 is called tres in Spanish
    [3] => The number 4 is called cuatro in Spanish
    [4] => The number 5 is called cinco in Spanish
)

// printout of $d
Array
(
    [0] => Array
        (
            [1] => uno
        )

    [1] => Array
        (
            [2] => dos
        )

    [2] => Array
        (
            [3] => tres
        )

    [3] => Array
        (
            [4] => cuatro
        )

    [4] => Array
        (
            [5] => cinco
        )

)

通常、二つ以上の配列を使用する場合、 それらの長さは等しい必要があります。 これは、 コールバック関数が対応する要素に対して並行して適用されるためです。 配列の長さが等しくない場合、要素数の少ない配列は空の要素で拡張して、最も長い配列の要素数に合わせます。

この関数の面白い使用方法として、 配列の配列を構築するというものがあります。 これは、コールバック関数の名前として null を使用することにより、簡単に実行できるものです。

例4 配列のzip操作を行う

<?php
$a = [1, 2, 3, 4, 5];
$b = ['one', 'two', 'three', 'four', 'five'];
$c = ['uno', 'dos', 'tres', 'cuatro', 'cinco'];

$d = array_map(null, $a, $b, $c);
print_r($d);
?>

上の例の出力は以下となります。

Array
(
    [0] => Array
        (
            [0] => 1
            [1] => one
            [2] => uno
        )

    [1] => Array
        (
            [0] => 2
            [1] => two
            [2] => dos
        )

    [2] => Array
        (
            [0] => 3
            [1] => three
            [2] => tres
        )

    [3] => Array
        (
            [0] => 4
            [1] => four
            [2] => cuatro
        )

    [4] => Array
        (
            [0] => 5
            [1] => five
            [2] => cinco
        )

)

例5 null を callback に渡し、 array だけを渡す例

<?php
$array = [1, 2, 3];
var_dump(array_map(null, $array));
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

例6 array_map() - 文字列キーの例

<?php
$arr = ['stringkey' => 'value'];
function cb1($a) {
return [$a];
}
function cb2($a, $b) {
return [$a, $b];
}
var_dump(array_map('cb1', $arr));
var_dump(array_map('cb2', $arr, $arr));
var_dump(array_map(null, $arr));
var_dump(array_map(null, $arr, $arr));
?>

上の例の出力は以下となります。

array(1) {
  ["stringkey"]=>
  array(1) {
    [0]=>
    string(5) "value"
  }
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(5) "value"
    [1]=>
    string(5) "value"
  }
}
array(1) {
  ["stringkey"]=>
  string(5) "value"
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(5) "value"
    [1]=>
    string(5) "value"
  }
}

例7 array_map() と連想配列

array_map() は、配列のキーを入力として直接サポートしていませんが、 array_keys() を使うと、配列のキーを入力とした動きをシミュレートできます。

<?php
$arr = [
'v1' => 'First release',
'v2' => 'Second release',
'v3' => 'Third release',
];

// Note: 7.4.0 より前のバージョンでは、無名関数を使うにはもっと長い書き方を使う必要があります
$callback = fn(string $k, string $v): string => "$k was the $v";

$result = array_map($callback, array_keys($arr), array_values($arr));

var_dump($result);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(24) "v1 was the First release"
  [1]=>
  string(25) "v2 was the Second release"
  [2]=>
  string(24) "v3 was the Third release"
}

参考

  • array_filter() - コールバック関数を使用して、配列の要素をフィルタリングする
  • array_reduce() - コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる
  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する


ひとつまたは複数の配列をマージする

  • ≪ array_map
  • array_merge_recursive ≫
  • PHP Manual
  • 配列 関数
  • ひとつまたは複数の配列をマージする

array_merge

(PHP 4, PHP 5, PHP 7, PHP 8)

array_merge — ひとつまたは複数の配列をマージする

説明

array_merge(array ...$arrays): array

前の配列の後ろに配列を追加することにより、 ひとつまたは複数の配列の要素をマージし、得られた配列を返します。

入力配列が同じキー文字列を有していた場合、そのキーに関する後に指定された値が、 前の値を上書きします。しかし、配列が同じ添字番号を有していても 値は追記されるため、このようなことは起きません。

入力配列の中にある数値添字要素の添字の数値は、 結果の配列ではゼロから始まる連続した数値に置き換えられます。

パラメータ

arrays

マージしていく任意の数の配列のリスト。

戻り値

結果の配列を返します。 引数なしで呼ばれた場合、空の array を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は、引数なしでも呼び出せるようになりました。 このバージョンより前では、少なくともひとつの引数が必須でした。

例

例1 array_merge() の例

<?php
$array1 = array("color" => "red", 2, 4);
$array2 = array("a", "b", "color" => "green", "shape" => "trapezoid", 4);
$result = array_merge($array1, $array2);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [color] => green
    [0] => 2
    [1] => 4
    [2] => a
    [3] => b
    [shape] => trapezoid
    [4] => 4
)

例2 簡単な array_merge() の例

<?php
$array1 = array();
$array2 = array(1 => "data");
$result = array_merge($array1, $array2);
?>

数値添字が振りなおされることに注意!

Array
(
    [0] => data
)

二番目の配列の要素を最初の配列に追加したい (最初の配列に存在する要素は上書きせず、添字も変更しない) 場合は、配列結合演算子 + を使います。

<?php
$array1 = array(0 => 'zero_a', 2 => 'two_a', 3 => 'three_a');
$array2 = array(1 => 'one_b', 3 => 'three_b', 4 => 'four_b');
$result = $array1 + $array2;
var_dump($result);
?>

最初の配列のキーはそのまま残ります。 両方の配列に同じキーが存在する場合は最初の配列のものが残り、 二番目の配列の内容は無視されます。

array(5) {
  [0]=>
  string(6) "zero_a"
  [2]=>
  string(5) "two_a"
  [3]=>
  string(7) "three_a"
  [1]=>
  string(5) "one_b"
  [4]=>
  string(6) "four_b"
}

例3 array_merge() で配列以外の型を扱う例

<?php
$beginning = 'foo';
$end = array(1 => 'bar');
$result = array_merge((array)$beginning, (array)$end);
print_r($result);
?>

上の例の出力は以下となります。

Array
    (
        [0] => foo
        [1] => bar
    )

参考

  • array_merge_recursive() - 一つ以上の配列を再帰的にマージする
  • array_replace() - 渡された配列の要素を置き換える
  • array_combine() - 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する
  • 配列演算子


一つ以上の配列を再帰的にマージする

  • ≪ array_merge
  • array_multisort ≫
  • PHP Manual
  • 配列 関数
  • 一つ以上の配列を再帰的にマージする

array_merge_recursive

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

array_merge_recursive — 一つ以上の配列を再帰的にマージする

説明

array_merge_recursive(array ...$arrays): array

array_merge_recursive() は、 一つ以上の配列の要素をマージし、 前の配列の最後にもう一つの配列の値を追加します。 マージした後の配列を返します。

入力配列が同じ文字列のキーを有している場合、 マージした後の配列ではこれらのキーの値がひとつにまとめられます。 この処理は再帰的に行われます。 このため、値の一つが配列自体を指している場合、 この関数は別の配列の対応するエントリもマージします。 しかし、配列が同じ数値キーを有している場合、 後の値は元の値を上書せず、追加されます。

パラメータ

arrays

再帰的にマージしていく配列の可変リスト。

戻り値

すべての引数の配列をマージした結果の配列を返します。 引数なしで呼び出された場合、空の配列を返します。

変更履歴

バージョン | 説明
7.4.0 | この関数は、引数なしでも呼び出せるようになりました。 このバージョンより前では、少なくともひとつの引数が必須でした。

例

例1 array_merge_recursive() の例

<?php
$ar1 = array("color" => array("favorite" => "red"), 5);
$ar2 = array(10, "color" => array("favorite" => "green", "blue"));
$result = array_merge_recursive($ar1, $ar2);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [color] => Array
        (
            [favorite] => Array
                (
                    [0] => red
                    [1] => green
                )

            [0] => blue
        )

    [0] => 5
    [1] => 10
)

参考

  • array_merge() - ひとつまたは複数の配列をマージする
  • array_replace_recursive() - 渡された配列の要素を再帰的に置き換える


複数または多次元の配列をソートする

  • ≪ array_merge_recursive
  • array_pad ≫
  • PHP Manual
  • 配列 関数
  • 複数または多次元の配列をソートする

array_multisort

(PHP 4, PHP 5, PHP 7, PHP 8)

array_multisort — 複数または多次元の配列をソートする

説明

array_multisort(
array &$array1,
mixed $array1_sort_order = SORT_ASC,
mixed $array1_sort_flags = SORT_REGULAR,
mixed ...$rest
): bool

array_multisort() は、複数の配列を一度に、 または、多次元の配列をその次元の一つでソートする際に使用可能です。

連想配列のキー (string) は不変ですが、 数値添字は再度振り直されます。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array1

ソートしたい配列。

array1_sort_order

先ほどの引数 array のソート順。 SORT_ASC はアイテムを昇順にソートし、 SORT_DESC はアイテムを降順にソートします。

この引数は、array1_sort_flags と入れ替えることもできるし、完全に省略することもできます。 省略した場合は SORT_ASC とみなします。

array1_sort_flags

先ほどの引数 array のソート方法。

これらのフラグが使えます。

  • SORT_REGULAR - アイテムを通常通り比較します (型を変更しません)。
  • SORT_NUMERIC - アイテムを数値として比較します。
  • SORT_STRING - アイテムを文字列として比較します。
  • SORT_LOCALE_STRING - 現在のロケールを考慮して、アイテムを文字列として比較します。利用するロケールは setlocale() で変更できます。
  • SORT_NATURAL - natsort() と同様の「自然順」で、アイテムを文字列として比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビット OR で) 組み合わせて、 大文字小文字を区別しない文字列のソートを指定します。

この引数は、array1_sort_order と入れ替えることもできるし、完全に省略することもできます。 省略した場合は SORT_REGULAR とみなします。

rest

追加の配列。オプションで並び順やフラグが続きます。 前の配列の比較結果が等しい要素に対応する要素群だけを比較します。 要するに、辞書的 (lexicographical) なソートを行うということです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 複数の配列をソートする

<?php
$ar1 = array(10, 100, 100, 0);
$ar2 = array(1, 3, 2, 4);
array_multisort($ar1, $ar2);

var_dump($ar1);
var_dump($ar2);
?>

この例では、ソートの後で、最初の配列は、0, 10, 100, 100 となります。 2番目の配列は、4, 1, 2, 3 を有します。最初の配列で等しい要素 (100 および 100) に対応している二番目の配列のエントリは、 同じ順にソートされます。

array(4) {
  [0]=> int(0)
  [1]=> int(10)
  [2]=> int(100)
  [3]=> int(100)
}
array(4) {
  [0]=> int(4)
  [1]=> int(1)
  [2]=> int(2)
  [3]=> int(3)
}

例2 多次元の配列をソートする

<?php
$ar = array(
array("10", 11, 100, 100, "a"),
array( 1, 2, "2", 3, 1)
);
array_multisort($ar[0], SORT_ASC, SORT_STRING,
$ar[1], SORT_NUMERIC, SORT_DESC);
var_dump($ar);
?>

この例では、ソートされた後、最初の配列は "10", 100, 100, 11, "a" (文字列として昇順でソートされています) に変換され、二番目の配列は、 1, 3, "2", 2, 1 (数値として降順にソートされています) となっています。

array(2) {
  [0]=> array(5) {
    [0]=> string(2) "10"
    [1]=> int(100)
    [2]=> int(100)
    [3]=> int(11)
    [4]=> string(1) "a"
  }
  [1]=> array(5) {
    [0]=> int(1)
    [1]=> int(3)
    [2]=> string(1) "2"
    [3]=> int(2)
    [4]=> int(1)
  }
}

例3 データベースの結果をソートする

この例では、配列 data の個々の要素がテーブルのひとつの行を表しています。 これは、データベースのレコードの典型的な形式です。

データの例:

volume | edition
-------+--------
    67 |       2
    86 |       1
    85 |       6
    98 |       2
    86 |       6
    67 |       7

データは data という名前の配列に格納します。 これは、例えば mysql_fetch_assoc() の結果をループさせたりすれば得られます。

<?php
$data[] = array('volume' => 67, 'edition' => 2);
$data[] = array('volume' => 86, 'edition' => 1);
$data[] = array('volume' => 85, 'edition' => 6);
$data[] = array('volume' => 98, 'edition' => 2);
$data[] = array('volume' => 86, 'edition' => 6);
$data[] = array('volume' => 67, 'edition' => 7);
?>

この例では、データを volume の降順、 edition の昇順に並べ替えます。

私たちが今もっているのは行方向の配列ですが、 array_multisort() で必要なのは列方向の配列です。 そこで、以下のコードで列方向の配列を得たあとでソートを行います。

<?php
// 列方向の配列を得る
foreach ($data as $key => $row) {
$volume[$key] = $row['volume'];
$edition[$key] = $row['edition'];
}

// 上記のコードの代わりに array_column() を使用できます
$volume = array_column($data, 'volume');
$edition = array_column($data, 'edition');

// データを volume の降順、edition の昇順にソートする。
// $data を最後のパラメータとして渡し、同じキーでソートする。
array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
?>

データセットの行はソートされ、以下のようになります:

volume | edition
-------+--------
    98 |       2
    86 |       1
    86 |       6
    85 |       6
    67 |       2
    67 |       7

例4 大文字・小文字を区別しないソート

SORT_STRING と SORT_REGULAR はどちらも大文字・小文字を区別し、 大文字ではじまる文字列が小文字で始まる文字列より前になります。

大文字・小文字を区別しないためには、 元の配列の内容をすべて小文字に変換した配列を用意し、 それをソートの基準にします。

<?php
$array = array('Alpha', 'atomic', 'Beta', 'bank');
$array_lowercase = array_map('strtolower', $array);

array_multisort($array_lowercase, SORT_ASC, SORT_STRING, $array);

print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [0] => Alpha
    [1] => atomic
    [2] => bank
    [3] => Beta
)

参考

  • usort() - ユーザー定義の比較関数を使用して、配列を値でソートする
  • 配列ソート関数の比較


指定長、指定した値で配列を埋める

  • ≪ array_multisort
  • array_pop ≫
  • PHP Manual
  • 配列 関数
  • 指定長、指定した値で配列を埋める

array_pad

(PHP 4, PHP 5, PHP 7, PHP 8)

array_pad — 指定長、指定した値で配列を埋める

説明

array_pad(array $array, int $length, mixed $value): array

array_pad() は、length で指定した長さになるように値 value で埋めて array のコピーを返します。 length が正の場合、配列の右側が埋められます。 負の場合、配列の左側が埋められます。 length の絶対値が array の長さ以下の場合、埋める処理は行われません。

パラメータ

array

値を埋めるもととなる配列。

length

新しい配列のサイズ。

value

array が length より小さいときに、 埋めるために使用する値。

戻り値

length で指定した長さになるように値 value で埋めて array のコピーを返します。 length が正の場合、配列の右側が埋められます。 負の場合、配列の左側が埋められます。 length の絶対値が array の長さ以下の場合、埋める処理は行われません。

変更履歴

バージョン | 説明
8.3.0 | PHP 8.3 より前のバージョンでは、 一度に 1048576 個の要素しか追加できませんでした。 このバージョンからは、制限は配列の最大サイズのみになりました。

例

例1 array_pad() の例

<?php
$input = array(12, 10, 9);

$result = array_pad($input, 5, 0);
// 結果は、array(12, 10, 9, 0, 0) です。

$result = array_pad($input, -7, -1);
// 結果は、array(-1, -1, -1, -1, 12, 10, 9) です。

$result = array_pad($input, 2, "noop");
// 埋める処理は行われません。
?>

参考

  • array_fill() - 配列を指定した値で埋める
  • range() - ある範囲の要素を含む配列を作成する


配列の末尾から要素を取り除く

  • ≪ array_pad
  • array_product ≫
  • PHP Manual
  • 配列 関数
  • 配列の末尾から要素を取り除く

array_pop

(PHP 4, PHP 5, PHP 7, PHP 8)

array_pop — 配列の末尾から要素を取り除く

説明

array_pop(array &$array): mixed

array_pop() は配列 array の最後の要素の値を取り出して返します。 配列 array は、要素一つ分短くなります。

注意: この関数は、 入力配列のポインタを、使用した後にリセット (reset()) します。

パラメータ

array

値を取り出す配列。

戻り値

配列 array の最後の要素の値を取り出して返します。 array が空の場合、 null が返されます。

例

例1 array_pop() の例

<?php
$stack = array("orange", "banana", "apple", "raspberry");
$fruit = array_pop($stack);
print_r($stack);
?>

この後、$stack の要素は三つのみとなります。

Array
(
    [0] => orange
    [1] => banana
    [2] => apple
)

そして、raspberry が $fruit に代入されます。

参考

  • array_push() - 一つ以上の要素を配列の最後に追加する
  • array_shift() - 配列の先頭から要素を一つ取り出す
  • array_unshift() - 一つ以上の要素を配列の最初に加える


配列の値の積を計算する

  • ≪ array_pop
  • array_push ≫
  • PHP Manual
  • 配列 関数
  • 配列の値の積を計算する

array_product

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

array_product — 配列の値の積を計算する

説明

array_product(array $array): int|float

array_product() は、配列の値の積を計算します。

パラメータ

array

配列。

戻り値

積を、integer あるいは float で返します。

変更履歴

バージョン | 説明
8.3.0 | array の値が整数や浮動小数点数に変換できない場合、 E_WARNING が発生するようになりました。 これより前のバージョンでは、 配列とオブジェクトが渡されても無視され、 それ以外の値は整数に変換されていました。 さらに、数値へのキャストが定義されているオブジェクト (例: GMP) は無視されるのではなく、 数値にキャストされるようになりました。

例

例1 array_product() の例

<?php

$a = array(2, 4, 6, 8);
echo "product(a) = " . array_product($a) . "\n";
echo "product(array()) = " . array_product(array()) . "\n";

?>

上の例の出力は以下となります。

product(a) = 384
product(array()) = 1


一つ以上の要素を配列の最後に追加する

  • ≪ array_product
  • array_rand ≫
  • PHP Manual
  • 配列 関数
  • 一つ以上の要素を配列の最後に追加する

array_push

(PHP 4, PHP 5, PHP 7, PHP 8)

array_push — 一つ以上の要素を配列の最後に追加する

説明

array_push(array &$array, mixed ...$values): int

array_push()は、array をスタックとして処理し、渡された変数を array の最後に加えます。配列 array の長さは渡された変数の数だけ増加します。 各 value1 毎に以下を繰り返すことと同じ効果があります。

<?php
$array[] = $var;
?>
各 value1 で繰り返されます。

注意: もし配列にひとつの要素を加えるために array_push() を使用するなら、 関数を呼ぶオーバーヘッドがないので、$array[] = を使用するほうがいいです。

注意: 最初の引数が配列でない場合、array_push() は警告を発生させます。これは、PHP 7.1.0 より前のバージョンの、 新規配列を生成する場合における $var[] の動作と異なっていました。

パラメータ

array

入力の配列。

values

array の最後に追加する値。

戻り値

処理後の配列の中の要素の数を返します。

変更履歴

バージョン | 説明
7.3.0 | この関数は、1 つのパラメータでのみ呼び出すことができるようになりました。 前は、少なくとも 2 つのパラメータが必要でした。

例

例1 array_push() の例

<?php
$stack = array("orange", "banana");
array_push($stack, "apple", "raspberry");
print_r($stack);
?>

上の例の出力は以下となります。

Array
(
    [0] => orange
    [1] => banana
    [2] => apple
    [3] => raspberry
)

参考

  • array_pop() - 配列の末尾から要素を取り除く
  • array_shift() - 配列の先頭から要素を一つ取り出す
  • array_unshift() - 一つ以上の要素を配列の最初に加える


配列から一つ以上のキーをランダムに取得する

  • ≪ array_push
  • array_reduce ≫
  • PHP Manual
  • 配列 関数
  • 配列から一つ以上のキーをランダムに取得する

array_rand

(PHP 4, PHP 5, PHP 7, PHP 8)

array_rand — 配列から一つ以上のキーをランダムに取得する

説明

array_rand(array $array, int $num = 1): int|string|array

一つ以上のランダムなエントリを配列から取り出し、 取り出したエントリのキーを返します。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

array

入力の配列。 空配列にはできません。

num

取得するエントリの数を指定します。 1以上 array の要素数以下である必要があります。

戻り値

エントリを一つだけ取得する場合、 array_rand() はランダムなエントリのキーを返します。 その他の場合は、ランダムなエントリのキーの配列を返します。 これにより、ランダムな値だけではなくランダムなキーも配列から取得できるようになります。 複数のキーが返される場合、配列に格納された順番と同じ順で返されます。

エラー / 例外

array が空か num が範囲外の値の場合に、 ValueError がスローされます。

変更履歴

バージョン | 説明
8.0.0 | num が範囲外の値の場合に、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、null を返していました。
8.0.0 | array が空の場合に、 ValueError がスローされるようになりました。 これより前のバージョンでは、 E_WARNING が発生し、null を返していました。
7.1.0 | 内部的なランダム化アルゴリズムは、 libc の rand 関数ではなく、 » メルセンヌツイスタ 乱数生成器を使うように 変更されました

例

例1 array_rand() の例

<?php
srand((float) microtime() * 10000000);
$input = array("ネオ", "モーフィアス", "トリニティ", "サイファー", "タンク");
$rand_keys = array_rand($input, 2);
echo $input[$rand_keys[0]] . "\n";
echo $input[$rand_keys[1]] . "\n";
?>

注意

注意: srand() または mt_srand() によりランダム数生成器にシードを与える必要はありません。 これは、この処理が自動的に行われるためです。

参考

  • Random\Randomizer::pickArrayKeys() - ランダムに配列のキーを選択する
  • Random\Randomizer::shuffleArray() - 配列の順列を取得する


コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる

  • ≪ array_rand
  • array_replace ≫
  • PHP Manual
  • 配列 関数
  • コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる

array_reduce

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

array_reduce — コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる

説明

array_reduce(array $array, callable $callback, mixed $initial = null): mixed

array_reduce() は、配列 array の各要素に callback 関数を繰り返し適用し、 配列をひとつの値にまとめます。

パラメータ

array

入力の配列。

callback
callback(mixed $carry, mixed $item): mixed
carry

前回の反復処理の結果を保持します。最初の反復処理のときには、 initial の値を保持しています。

item

現在の反復処理の値を保持します。

initial

オプションの intial が利用可能な場合、処理の最初で使用されたり、 配列が空の場合の最終結果として使用されます。

戻り値

結果の値を返します。

配列が空で initial が渡されなかった場合は、 array_reduce() は null を返します。

変更履歴

バージョン | 説明
8.0.0 | callback がリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 array_reduce() の例

<?php
function sum($carry, $item)
{
$carry += $item;
return $carry;
}

function product($carry, $item)
{
$carry *= $item;
return $carry;
}

$a = array(1, 2, 3, 4, 5);
$x = array();

var_dump(array_reduce($a, "sum")); // int(15)
var_dump(array_reduce($a, "product", 10)); // int(1200), because: 10*1*2*3*4*5
var_dump(array_reduce($x, "sum", "No data to reduce")); // string(17) "No data to reduce"
?>

参考

  • array_filter() - コールバック関数を使用して、配列の要素をフィルタリングする
  • array_map() - 指定した配列の要素にコールバック関数を適用する
  • array_unique() - 配列から重複した値を削除する
  • array_count_values() - 配列内に存在する、異なる値の出現回数を数える


渡された配列の要素を置き換える

  • ≪ array_reduce
  • array_replace_recursive ≫
  • PHP Manual
  • 配列 関数
  • 渡された配列の要素を置き換える

array_replace

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

array_replace — 渡された配列の要素を置き換える

説明

array_replace(array $array, array ...$replacements): array

array_replace() は、 array の値をそれ以降の配列の同じ要素の値で置き換えます。 最初の配列のキーと同じキーが 2 番目の配列にあれば、 2 番目の配列の値が最初の配列の値を上書きします。 2 番目の配列に存在するキーが最初の配列に存在しなければ、 そのキーが新たに最初の配列内に作られます。 最初の配列にしか存在しないキーについては何も変わりません。 置き換え用の配列が複数渡された場合は渡した順に処理を行い、 後から渡した配列の値のほうが優先されます。

array_replace() は再起的な処理を行いません。 2 番目の配列の値がどんな型であっても、最初の配列の値を置き換えます。

パラメータ

array

要素を置き換えたい配列。

replacements

置き換えたい要素を含む配列。 後から渡した配列の値のほうが優先されます。

戻り値

配列を返します。

例

例1 array_replace() の例

<?php
$base = array("orange", "banana", "apple", "raspberry");
$replacements = array(0 => "pineapple", 4 => "cherry");
$replacements2 = array(0 => "grape");

$basket = array_replace($base, $replacements, $replacements2);
print_r($basket);
?>

上の例の出力は以下となります。

Array
(
    [0] => grape
    [1] => banana
    [2] => apple
    [3] => raspberry
    [4] => cherry
)

参考

  • array_replace_recursive() - 渡された配列の要素を再帰的に置き換える
  • array_merge() - ひとつまたは複数の配列をマージする


渡された配列の要素を再帰的に置き換える

  • ≪ array_replace
  • array_reverse ≫
  • PHP Manual
  • 配列 関数
  • 渡された配列の要素を再帰的に置き換える

array_replace_recursive

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

array_replace_recursive — 渡された配列の要素を再帰的に置き換える

説明

array_replace_recursive(array $array, array ...$replacements): array

array_replace_recursive() は、 array の値をそれ以降の配列の同じ要素の値で置き換えます。 最初の配列のキーと同じキーが 2 番目の配列にあれば、 2 番目の配列の値が最初の配列の値を上書きします。 2 番目の配列に存在するキーが最初の配列に存在しなければ、 そのキーが新たに最初の配列内に作られます。 最初の配列にしか存在しないキーについては何も変わりません。 置き換え用の配列が複数渡された場合は渡した順に処理を行い、 後から渡した配列の値のほうが優先されます。

array_replace_recursive() は再帰的な処理を行います。 配列を再帰的にたどり、内部の値に対しても同じ手順で処理します。

最初の配列の値がスカラーの場合は、 2 番目の配列の値がスカラーであるか配列であるかにかかわらずそれで置き換えられます。 最初の配列の値と 2番目の配列 の値が両方配列である場合は、array_replace_recursive() が対応する値を再帰的に処理します。

パラメータ

array

要素を置き換えたい配列。

replacements

置き換えたい要素を含む配列。

戻り値

配列を返します。

例

例1 array_replace_recursive() の例

<?php
$base = array('citrus' => array( "orange") , 'berries' => array("blackberry", "raspberry"), );
$replacements = array('citrus' => array('pineapple'), 'berries' => array('blueberry'));

$basket = array_replace_recursive($base, $replacements);
print_r($basket);

$basket = array_replace($base, $replacements);
print_r($basket);
?>

上の例の出力は以下となります。

Array
(
    [citrus] => Array
        (
            [0] => pineapple
        )

    [berries] => Array
        (
            [0] => blueberry
            [1] => raspberry
        )

)
Array
(
    [citrus] => Array
        (
            [0] => pineapple
        )

    [berries] => Array
        (
            [0] => blueberry
        )

)

例2 array_replace_recursive() での再帰的な挙動の例

<?php
$base = array('citrus' => array("orange") , 'berries' => array("blackberry", "raspberry"), 'others' => 'banana' );
$replacements = array('citrus' => 'pineapple', 'berries' => array('blueberry'), 'others' => array('litchis'));
$replacements2 = array('citrus' => array('pineapple'), 'berries' => array('blueberry'), 'others' => 'litchis');

$basket = array_replace_recursive($base, $replacements, $replacements2);
print_r($basket);

?>

上の例の出力は以下となります。

Array
(
    [citrus] => Array
        (
            [0] => pineapple
        )

    [berries] => Array
        (
            [0] => blueberry
            [1] => raspberry
        )

    [others] => litchis
)

参考

  • array_replace() - 渡された配列の要素を置き換える
  • array_merge_recursive() - 一つ以上の配列を再帰的にマージする


要素を逆順にした配列を返す

  • ≪ array_replace_recursive
  • array_search ≫
  • PHP Manual
  • 配列 関数
  • 要素を逆順にした配列を返す

array_reverse

(PHP 4, PHP 5, PHP 7, PHP 8)

array_reverse — 要素を逆順にした配列を返す

説明

array_reverse(array $array, bool $preserve_keys = false): array

配列を受け取って、要素の順番を逆にした新しい配列を返します。

パラメータ

array

入力の配列。

preserve_keys

true の場合は数値のキーを保持します。 非数値のキーは、この設定にかかわらず常に保持されます。

戻り値

逆転させた配列を返します。

例

例1 array_reverse() の例

<?php
$input = array("php", 4.0, array("green", "red"));
$reversed = array_reverse($input);
$preserved = array_reverse($input, true);

print_r($input);
print_r($reversed);
print_r($preserved);
?>

上の例の出力は以下となります。

Array
(
    [0] => php
    [1] => 4
    [2] => Array
        (
            [0] => green
            [1] => red
        )

)
Array
(
    [0] => Array
        (
            [0] => green
            [1] => red
        )

    [1] => 4
    [2] => php
)
Array
(
    [2] => Array
        (
            [0] => green
            [1] => red
        )

    [1] => 4
    [0] => php
)

参考

  • array_flip() - 配列のキーと値を反転する


指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す

  • ≪ array_reverse
  • array_shift ≫
  • PHP Manual
  • 配列 関数
  • 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す

array_search

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

array_search — 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す

説明

array_search(mixed $needle, array $haystack, bool $strict = false): int|string|false

haystack 内の needle を検索します。

パラメータ

needle

検索したい値。

注意:

needle が文字列の場合、 大文字小文字を区別して比較が行われます。

haystack

配列。

strict

オプションの3番目のパラメータ strict に true が指定された場合、 array_search() は identical 要素を haystack から探します。 つまり、haystack の中で needle の厳密な型比較を実行します。 およびオブジェクトが同一のインスタンスであるかどうかも確認します。

戻り値

needle が見つかった場合に配列のキー、 それ以外の場合に false を返します。

もし haystack に 1 つ以上の needle に見つかった場合、 最初にマッチしたキーが返されます。全てのマッチした値に対するキーを返すためには、代わりに array_keys() にパラメータ filter_value を付けて使用してください。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

例

例1 array_search() の例

<?php
$array = array(0 => 'blue', 1 => 'red', 2 => 'green', 3 => 'red');

$key = array_search('green', $array); // $key = 2;
$key = array_search('red', $array); // $key = 1;
?>

参考

  • array_keys() - 配列のキーすべて、あるいはその一部を返す
  • array_values() - 配列の全ての値を返す
  • array_key_exists() - 指定したキーまたは添字が配列にあるかどうかを調べる
  • in_array() - 配列に値があるかチェックする


配列の先頭から要素を一つ取り出す

  • ≪ array_search
  • array_slice ≫
  • PHP Manual
  • 配列 関数
  • 配列の先頭から要素を一つ取り出す

array_shift

(PHP 4, PHP 5, PHP 7, PHP 8)

array_shift — 配列の先頭から要素を一つ取り出す

説明

array_shift(array &$array): mixed

array_shift() は、array の最初の値を取り出して返します。配列 array は、要素一つ分だけ短くなり、全ての要素は前にずれます。 数値添字の配列のキーはゼロから順に新たに振りなおされますが、 リテラルのキーには影響しません。

注意: この関数は、 入力配列のポインタを、使用した後にリセット (reset()) します。

パラメータ

array

入力の配列。

戻り値

取り出した値を返します。array が空の場合や配列でない場合は null を返します。

例

例1 array_shift() の例

<?php
$stack = array("orange", "banana", "apple", "raspberry");
$fruit = array_shift($stack);
print_r($stack);
?>

上の例の出力は以下となります。

Array
(
    [0] => banana
    [1] => apple
    [2] => raspberry
)

そして、$fruit には orange が代入されます。

参考

  • array_unshift() - 一つ以上の要素を配列の最初に加える
  • array_push() - 一つ以上の要素を配列の最後に追加する
  • array_pop() - 配列の末尾から要素を取り除く


配列の一部を展開する

  • ≪ array_shift
  • array_splice ≫
  • PHP Manual
  • 配列 関数
  • 配列の一部を展開する

array_slice

(PHP 4, PHP 5, PHP 7, PHP 8)

array_slice — 配列の一部を展開する

説明

array_slice(
array $array,
int $offset,
?int $length = null,
bool $preserve_keys = false
): array

array_slice()は、array から引数 offset および length で指定された連続する要素を返します。

パラメータ

array

入力の配列。

offset

offset が負の値ではない場合、要素位置の計算は、 配列 array の offset から始められます。

offset が負の場合、要素位置の計算は array の最後から行われます。

offset は、配列の位置を表します。配列のキーではありません。

length

lengthが指定され、正の場合、 配列の要素の中から最大でその数までの要素を返します。

配列の要素数が length より少ない場合は、 配列から取得できる要素だけを返します。

length が指定され、負の場合、配列の末尾から連続する複数の要素が返されます。

省略された場合、offset から配列の最後までの全ての要素が返されます。

preserve_keys

注意:

array_slice() はデフォルトで配列の数値キーを並べなおし、 リセットします。 preserve_keys を true にする事でこの動作を変更することができます。 文字列のキーは、このパラメータの値にかかわらず常に保存されます。

戻り値

切り取った部分を返します。オフセットが配列のサイズより大きい場合は、空の配列を返します。

例

例1 array_slice() の例

<?php
$input = array("a", "b", "c", "d", "e");

$output = array_slice($input, 2); // "c", "d", "e" を返す
$output = array_slice($input, -2, 1); // "d" を返す
$output = array_slice($input, 0, 3); // "a", "b", "c" を返す

// 配列キーの違いに注意
print_r(array_slice($input, 2, -1));
print_r(array_slice($input, 2, -1, true));
?>

上の例の出力は以下となります。

Array
(
    [0] => c
    [1] => d
)
Array
(
    [2] => c
    [3] => d
)

例2 array_slice() と、キーが1から始まる配列

<?php
$input = array(1 => "a", "b", "c", "d", "e");
print_r(array_slice($input, 1, 2));
?>

上の例の出力は以下となります。

Array
(
    [0] => b
    [1] => c
)

例3 array_slice() に、数値と文字列のキーが混じった配列を渡す例

<?php
$ar = array('a'=>'apple', 'b'=>'banana', '42'=>'pear', 'd'=>'orange');
print_r(array_slice($ar, 0, 3));
print_r(array_slice($ar, 0, 3, true));
?>

上の例の出力は以下となります。

Array
(
    [a] => apple
    [b] => banana
    [0] => pear
)
Array
(
    [a] => apple
    [b] => banana
    [42] => pear
)

参考

  • array_chunk() - 配列を分割する
  • array_splice() - 配列の一部を削除し、他の要素で置換する
  • unset() - 指定した変数の割当を解除する


配列の一部を削除し、他の要素で置換する

  • ≪ array_slice
  • array_sum ≫
  • PHP Manual
  • 配列 関数
  • 配列の一部を削除し、他の要素で置換する

array_splice

(PHP 4, PHP 5, PHP 7, PHP 8)

array_splice — 配列の一部を削除し、他の要素で置換する

説明

array_splice(
array &$array,
int $offset,
?int $length = null,
mixed $replacement = []
): array

配列 array から offset および length で指定された要素を削除し、配列 replacement でそれを置換します。

注意:

array の配列の数値添字は保存されないことに注意しましょう。

注意: replacement が配列でない場合は、 型変換 を行います (つまり (array) $replacement とします)。 たとえば replacement にオブジェクトや null などを指定した場合に、 予期せぬ動きをする可能性があります。

パラメータ

array

入力の配列。

offset

offset が正の場合、削除される部分は 配列 array の最初から指定オフセットの ぶんだけ進んだ位置からとなります。

offset が負の場合、削除される部分は、 array の末尾から数えた位置からとなります。

length

length が省略された場合、 offset から配列の最後までが全て削除されます。

length が指定され、正の場合、複数の要素が削除されます。

負の length が指定された場合、削除される部分の末尾の位置は配列の末尾を基準にして計算されます。

length にゼロを指定した場合は、どの要素も削除しません。

ヒント

replacement も指定した場合に offset から配列の最後まで全てを削除するには、 length を求めるために count($input) を使用してください。

replacement

配列 replacement が指定された場合、 削除された要素は、この配列の要素で置換されます。

offset および length で何も削除しないと指定した場合、配列 replacement の要素は offset で指定された位置に挿入されます。

注意:

置換される配列のキーは保存されないことに注意してください。

もし replacement に一つしか要素がない場合、 要素そのものが配列やオブジェクトあるいは null でない限り、array() や 角括弧 で括る必要はありません。

戻り値

抽出された要素を含む配列を返します。

変更履歴

バージョン | 説明
8.0.0 | length は、nullable になりました。

例

例1 array_splice() の例

<?php
$input = array("red", "green", "blue", "yellow");
array_splice($input, 2);
var_dump($input);

$input = array("red", "green", "blue", "yellow");
array_splice($input, 1, -1);
var_dump($input);

$input = array("red", "green", "blue", "yellow");
array_splice($input, 1, count($input), "orange");
var_dump($input);

$input = array("red", "green", "blue", "yellow");
array_splice($input, -1, 1, array("black", "maroon"));
var_dump($input);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  string(3) "red"
  [1]=>
  string(5) "green"
}
array(2) {
  [0]=>
  string(3) "red"
  [1]=>
  string(6) "yellow"
}
array(2) {
  [0]=>
  string(3) "red"
  [1]=>
  string(6) "orange"
}
array(5) {
  [0]=>
  string(3) "red"
  [1]=>
  string(5) "green"
  [2]=>
  string(4) "blue"
  [3]=>
  string(5) "black"
  [4]=>
  string(6) "maroon"
}

例2 同じ動きをする、array_splice() の様々な例

以下の文は、すべて2つとも同じ意味です:

<?php

// $input に 2 つの要素を追加します
array_push($input, $x, $y);
array_splice($input, count($input), 0, array($x, $y));

// $input の最後の要素を削除します
array_pop($input);
array_splice($input, -1);

// $input の最初の要素を削除します
array_shift($input);
array_splice($input, 0, 1);

// $input の先頭に要素を挿入します
array_unshift($input, $x, $y);
array_splice($input, 0, 0, array($x, $y));

// インデックス $x の $input を置き換えます
$input[$x] = $y; // キーがオフセットと等価な配列に対して
array_splice($input, $x, 1, $y);

?>

参考

  • array_merge() - ひとつまたは複数の配列をマージする
  • array_slice() - 配列の一部を展開する
  • unset() - 指定した変数の割当を解除する


配列の中の値の合計を計算する

  • ≪ array_splice
  • array_udiff ≫
  • PHP Manual
  • 配列 関数
  • 配列の中の値の合計を計算する

array_sum

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

array_sum — 配列の中の値の合計を計算する

説明

array_sum(array $array): int|float

array_sum() は、配列の中の値の合計を整数または float として返します。

パラメータ

array

入力の配列。

戻り値

値の合計を整数または float として返します。 array が空の場合は 0 を返します。

変更履歴

バージョン | 説明
8.3.0 | array の値が整数や浮動小数点数に変換できない場合、 E_WARNING が発生するようになりました。 これより前のバージョンでは、 配列とオブジェクトが渡されても無視され、 それ以外の値は整数に変換されていました。 さらに、数値へのキャストが定義されているオブジェクト (例: GMP) は無視されるのではなく、 数値にキャストされるようになりました。

例

例1 array_sum() の例

<?php
$a = array(2, 4, 6, 8);
echo "sum(a) = " . array_sum($a) . "\n";

$b = array("a" => 1.2, "b" => 2.3, "c" => 3.4);
echo "sum(b) = " . array_sum($b) . "\n";
?>

上の例の出力は以下となります。

sum(a) = 20
sum(b) = 6.9


データの比較にコールバック関数を用い、配列の差を計算する

  • ≪ array_sum
  • array_udiff_assoc ≫
  • PHP Manual
  • 配列 関数
  • データの比較にコールバック関数を用い、配列の差を計算する

array_udiff

(PHP 5, PHP 7, PHP 8)

array_udiff — データの比較にコールバック関数を用い、配列の差を計算する

説明

array_udiff(array $array, array ...$arrays, callable $value_compare_func): array

データの比較にコールバック関数を用い、配列の差を計算します。 この関数は array_diff() と異なり、 データの比較に内部関数を利用します。

パラメータ

array

最初の配列。

arrays

比較対象の配列。

value_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

警告

ソートに使うコールバック関数は、任意の配列からの任意の値を、もともとの順番に関係なく、任意の順番で処理できなければいけません。なぜなら、個々の配列は、他の配列と比較する前に最初にソートされるからです。 サンプルコードは、以下のようになります:

<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 と $item2 は "string", 1, ["value" => 1] のいずれでも構いません
$compareFunc = static function ($item1, $item2) {
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
return $value1 <=> $value2;
};
?>

戻り値

他の引数のいずれにも存在しない array の値の全てを有する配列を返します。

例

例1 array_udiff() で stdClass オブジェクトを使う例

<?php
// 比較する配列
$array1 = array(new stdClass, new stdClass,
new stdClass, new stdClass,
);

$array2 = array(
new stdClass, new stdClass,
);

// オブジェクトにプロパティを設定します
$array1[0]->width = 11; $array1[0]->height = 3;
$array1[1]->width = 7; $array1[1]->height = 1;
$array1[2]->width = 2; $array1[2]->height = 9;
$array1[3]->width = 5; $array1[3]->height = 7;

$array2[0]->width = 7; $array2[0]->height = 5;
$array2[1]->width = 9; $array2[1]->height = 2;

function compare_by_area($a, $b) {
$areaA = $a->width * $a->height;
$areaB = $b->width * $b->height;

if ($areaA < $areaB) {
return -1;
} elseif ($areaA > $areaB) {
return 1;
} else {
return 0;
}
}

print_r(array_udiff($array1, $array2, 'compare_by_area'));
?>

上の例の出力は以下となります。

Array
(
    [0] => stdClass Object
        (
            [width] => 11
            [height] => 3
        )

    [1] => stdClass Object
        (
            [width] => 7
            [height] => 1
        )

)

例2 array_udiff() で DateTime オブジェクトを使う例

<?php
class MyCalendar {
public $free = array();
public $booked = array();

public function __construct($week = 'now') {
$start = new DateTime($week);
$start->modify('Monday this week midnight');
$end = clone $start;
$end->modify('Friday this week midnight');
$interval = new DateInterval('P1D');
foreach (new DatePeriod($start, $interval, $end) as $freeTime) {
$this->free[] = $freeTime;
}
}

public function bookAppointment(DateTime $date, $note) {
$this->booked[] = array('date' => $date->modify('midnight'), 'note' => $note);
}

public function checkAvailability() {
return array_udiff($this->free, $this->booked, array($this, 'customCompare'));
}

public function customCompare($free, $booked) {
if (is_array($free)) $a = $free['date'];
else $a = $free;
if (is_array($booked)) $b = $booked['date'];
else $b = $booked;
if ($a == $b) {
return 0;
} elseif ($a > $b) {
return 1;
} else {
return -1;
}
}
}

// 毎週の予約用のカレンダーを作ります
$myCalendar = new MyCalendar;

// 今週の予約を入れます
$myCalendar->bookAppointment(new DateTime('Monday this week'), "Cleaning GoogleGuy's apartment.");
$myCalendar->bookAppointment(new DateTime('Wednesday this week'), "Going on a snowboarding trip.");
$myCalendar->bookAppointment(new DateTime('Friday this week'), "Fixing buggy code.");

// 空きが何日あるかを調べるため、$booked の日数と $free の日数を比べます
echo "I'm available on the following days this week...\n\n";
foreach ($myCalendar->checkAvailability() as $free) {
echo $free->format('l'), "\n";
}
echo "\n\n";
echo "I'm busy on the following days this week...\n\n";
foreach ($myCalendar->booked as $booked) {
echo $booked['date']->format('l'), ": ", $booked['note'], "\n";
}
?>

上の例の出力は以下となります。

I'm available on the following days this week...

Tuesday
Thursday

I'm busy on the following days this week...

Monday: Cleaning GoogleGuy's apartment.
Wednesday: Going on a snowboarding trip.
Friday: Fixing buggy code.

注意

注意: この関数は n 次元配列の一つの次元しかチェックしないことに注意してください。 もちろん、array_udiff($array1[0], $array2[0], "data_compare_func"); のようにすることでより深い次元でのチェックもできます。

参考

  • array_diff() - 配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_uintersect() - データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する

  • ≪ array_udiff
  • array_udiff_uassoc ≫
  • PHP Manual
  • 配列 関数
  • データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する

array_udiff_assoc

(PHP 5, PHP 7, PHP 8)

array_udiff_assoc — データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する

説明

array_udiff_assoc(array $array, array ...$arrays, callable $value_compare_func): array

データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算します。

注意: この関数は n 次元配列の一つの次元しかチェックしないことに注意してください。 もちろん、array_udiff_assoc($array1[0], $array2[0], "some_comparison_func"); のようにすることでより深い次元でのチェックもできます。

パラメータ

array

最初の配列。

arrays

比較対象の配列。

value_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

警告

ソートに使うコールバック関数は、任意の配列からの任意の値を、もともとの順番に関係なく、任意の順番で処理できなければいけません。なぜなら、個々の配列は、他の配列と比較する前に最初にソートされるからです。 サンプルコードは、以下のようになります:

<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 と $item2 は "string", 1, ["value" => 1] のいずれでも構いません
$compareFunc = static function ($item1, $item2) {
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
return $value1 <=> $value2;
};
?>

戻り値

array_udiff_assoc() は、 array から他の引数の配列の中に現れない全ての値を含む array を返します。 array_diff() や array_udiff() と異なり、キーが比較に使用されることに注意してください。 配列のデータの比較は、ユーザーが指定したコールバックを用いて行われます。 この点で、array_diff_assoc() は反対の動作、つまり 内部関数を利用した比較を行います。

例

例1 array_udiff_assoc() の例

<?php
class cr {
private $priv_member;
function __construct($val)
{
$this->priv_member = $val;
}

static function comp_func_cr($a, $b)
{
if ($a->priv_member === $b->priv_member) return 0;
return ($a->priv_member > $b->priv_member)? 1:-1;
}
}

$a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
$b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);

$result = array_udiff_assoc($a, $b, array("cr", "comp_func_cr"));
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [0.1] => cr Object
        (
            [priv_member:private] => 9
        )

    [0.5] => cr Object
        (
            [priv_member:private] => 12
        )

    [0] => cr Object
        (
            [priv_member:private] => 23
        )
)

上の例で、"1" => new cr(4) の組み合わせが両方の配列にあること、 そしてそれが関数の出力に含まれていないことが確認できます。

参考

  • array_diff() - 配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_diff_uassoc() - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_udiff_uassoc() - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_uintersect() - データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する

  • ≪ array_udiff_assoc
  • array_uintersect ≫
  • PHP Manual
  • 配列 関数
  • データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する

array_udiff_uassoc

(PHP 5, PHP 7, PHP 8)

array_udiff_uassoc — データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する

説明

array_udiff_uassoc(
array $array,
array ...$arrays,
callable $value_compare_func,
callable $key_compare_func
): array

データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算します。

array_diff() や array_udiff() と異なり、キーが比較に使用されることに注意してください。

パラメータ

array

最初の配列。

arrays

比較対象の配列。

value_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

警告

ソートに使うコールバック関数は、任意の配列からの任意の値を、もともとの順番に関係なく、任意の順番で処理できなければいけません。なぜなら、個々の配列は、他の配列と比較する前に最初にソートされるからです。 サンプルコードは、以下のようになります:

<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 と $item2 は "string", 1, ["value" => 1] のいずれでも構いません
$compareFunc = static function ($item1, $item2) {
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
return $value1 <=> $value2;
};
?>

key_compare_func

キー（添字）の比較は、コールバック関数 key_compare_func で行われます。 array_udiff_assoc() では後者の比較が内部関数で 行われるという点で、この関数とは異なります。

戻り値

array から他の引数の配列の中に現れない全ての 値を含むarray を返します。

例

例1 array_udiff_uassoc() の例

<?php
class cr {
private $priv_member;
function __construct($val)
{
$this->priv_member = $val;
}

static function comp_func_cr($a, $b)
{
if ($a->priv_member === $b->priv_member) return 0;
return ($a->priv_member > $b->priv_member)? 1:-1;
}

static function comp_func_key($a, $b)
{
if ($a === $b) return 0;
return ($a > $b)? 1:-1;
}
}
$a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
$b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);

$result = array_udiff_uassoc($a, $b, array("cr", "comp_func_cr"), array("cr", "comp_func_key"));
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [0.1] => cr Object
        (
            [priv_member:private] => 9
        )

    [0.5] => cr Object
        (
            [priv_member:private] => 12
        )

    [0] => cr Object
        (
            [priv_member:private] => 23
        )
)

上の例で、"1" => new cr(4) の組み合わせが両方の配列にあること、 そしてそれが関数の出力に含まれていないことが確認できます。 コールバック関数を 2 つ指定しなければならないことに注意してください。

注意

注意: この関数は n 次元配列の一つの次元しかチェックしないことに注意してください。 もちろん、array_udiff_uassoc($array1[0], $array2[0], "data_compare_func", "key_compare_func"); のようにすることでより深い次元でのチェックもできます。

参考

  • array_diff() - 配列の差を計算する
  • array_diff_assoc() - 追加された添字の確認を含めて配列の差を計算する
  • array_udiff() - データの比較にコールバック関数を用い、配列の差を計算する
  • array_udiff_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_uintersect() - データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


データの比較にコールバック関数を用い、配列の共通項を計算する

  • ≪ array_udiff_uassoc
  • array_uintersect_assoc ≫
  • PHP Manual
  • 配列 関数
  • データの比較にコールバック関数を用い、配列の共通項を計算する

array_uintersect

(PHP 5, PHP 7, PHP 8)

array_uintersect — データの比較にコールバック関数を用い、配列の共通項を計算する

説明

array_uintersect(array $array, array ...$arrays, callable $value_compare_func): array

データの比較にコールバック関数を用い、配列の共通項を計算します。

パラメータ

array

最初の配列。

arrays

比較対象の配列。

value_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

警告

ソートに使うコールバック関数は、任意の配列からの任意の値を、もともとの順番に関係なく、任意の順番で処理できなければいけません。なぜなら、個々の配列は、他の配列と比較する前に最初にソートされるからです。 サンプルコードは、以下のようになります:

<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 と $item2 は "string", 1, ["value" => 1] のいずれでも構いません
$compareFunc = static function ($item1, $item2) {
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
return $value1 <=> $value2;
};
?>

戻り値

他の全ての引数に存在する array の値を全て有する配列を返します。

例

例1 array_uintersect() の例

<?php
$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");

print_r(array_uintersect($array1, $array2, "strcasecmp"));
?>

上の例の出力は以下となります。

Array
(
    [a] => green
    [b] => brown
    [0] => red
)

参考

  • array_intersect() - 配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する

  • ≪ array_uintersect
  • array_uintersect_uassoc ≫
  • PHP Manual
  • 配列 関数
  • データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する

array_uintersect_assoc

(PHP 5, PHP 7, PHP 8)

array_uintersect_assoc — データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する

説明

array_uintersect_assoc(array $array, array ...$arrays, callable $value_compare_func): array

データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算します。

array_uintersect()と異なり、キーが比較に使用される ことに注意してください。データはコールバック関数を用いて比較されます。

パラメータ

array

最初の配列。

arrays

比較対象の配列。

value_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

警告

ソートに使うコールバック関数は、任意の配列からの任意の値を、もともとの順番に関係なく、任意の順番で処理できなければいけません。なぜなら、個々の配列は、他の配列と比較する前に最初にソートされるからです。 サンプルコードは、以下のようになります:

<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 と $item2 は "string", 1, ["value" => 1] のいずれでも構いません
$compareFunc = static function ($item1, $item2) {
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
return $value1 <=> $value2;
};
?>

戻り値

全ての引数に現れる array の全ての値を含む配列を返します。

例

例1 array_uintersect_assoc() の例

<?php
$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");

print_r(array_uintersect_assoc($array1, $array2, "strcasecmp"));
?>

上の例の出力は以下となります。

Array
(
    [a] => green
)

参考

  • array_uintersect() - データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_uintersect_uassoc() - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する

  • ≪ array_uintersect_assoc
  • array_unique ≫
  • PHP Manual
  • 配列 関数
  • データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する

array_uintersect_uassoc

(PHP 5, PHP 7, PHP 8)

array_uintersect_uassoc — データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する

説明

array_uintersect_uassoc(
array $array1,
array ...$arrays,
callable $value_compare_func,
callable $key_compare_func
): array

データと添字の比較にそれぞれ別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算します。

パラメータ

array1

最初の配列。

arrays

残りの配列。

value_compare_func

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

警告

ソートに使うコールバック関数は、任意の配列からの任意の値を、もともとの順番に関係なく、任意の順番で処理できなければいけません。なぜなら、個々の配列は、他の配列と比較する前に最初にソートされるからです。 サンプルコードは、以下のようになります:

<?php
$arrayA = ["string", 1];
$arrayB = [["value" => 1]];
// $item1 と $item2 は "string", 1, ["value" => 1] のいずれでも構いません
$compareFunc = static function ($item1, $item2) {
$value1 = is_string($item1) ? strlen($item1) : (is_array($item1) ? $item1["value"] : $item1);
$value2 = is_string($item2) ? strlen($item2) : (is_array($item2) ? $item2["value"] : $item2);
return $value1 <=> $value2;
};
?>

key_compare_func

キーの比較用のコールバック関数。

戻り値

全ての引数に現れる array1 の全ての値を含む配列を返します。

例

例1 array_uintersect_uassoc() の例

<?php
$array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");

print_r(array_uintersect_uassoc($array1, $array2, "strcasecmp", "strcasecmp"));
?>

上の例の出力は以下となります。

Array
(
    [a] => green
    [b] => brown
)

参考

  • array_uintersect() - データの比較にコールバック関数を用い、配列の共通項を計算する
  • array_intersect_assoc() - 追加された添字の確認も含めて配列の共通項を確認する
  • array_intersect_uassoc() - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
  • array_uintersect_assoc() - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する


配列から重複した値を削除する

  • ≪ array_uintersect_uassoc
  • array_unshift ≫
  • PHP Manual
  • 配列 関数
  • 配列から重複した値を削除する

array_unique

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

array_unique — 配列から重複した値を削除する

説明

array_unique(array $array, int $flags = SORT_STRING): array

array を入力とし、値に重複のない新規配列を返します。

キーは保持されることに注意してください。 指定された flags において、 複数の要素が等しかった場合、はじめの要素のキーと値が保持されます。

注意: (string) $elem1 === (string) $elem2 の場合のみ二つの要素は等しいとみなされます。 つまり、文字列表現が同じである場合は、最初の要素を使用します。

パラメータ

array

入力の配列。

flags

オプションの 2 番目のパラメータ flags にこれらの値を使用して、比較の挙動を変更します。

比較形式のフラグは次のとおりです。

  • SORT_REGULAR - 通常の比較 (型変換をしない) を行います
  • SORT_NUMERIC - 数値として比較します
  • SORT_STRING - 文字列として比較します
  • SORT_LOCALE_STRING - 現在のロケールにもとづいて文字列として比較します。

戻り値

処理済の配列を返します。

変更履歴

バージョン | 説明
7.2.0 | flags が SORT_STRING の場合、 新しい配列が生成され、ユニークな要素が追加されるようになりました。 これによって、異なった数値のインデックスが振られる可能性があります。 これより前のバージョンでは、 array がコピーされ、 (配列を後にパックせずに) ユニークでない値が削除されていました。

例

例1 array_unique() の例

<?php
$input = array("a" => "green", "red", "b" => "green", "blue", "red");
$result = array_unique($input);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [a] => green
    [0] => red
    [1] => blue
)

例2 array_unique() と型

<?php
$input = array(4, "4", "3", 4, 3, "3");
$result = array_unique($input);
var_dump($result);
?>

上の例の出力は以下となります。

array(2) {
  [0] => int(4)
  [2] => string(1) "3"
}

注意

注意: array_unique() は、 多次元配列での使用を想定したものではないことに注意しましょう。

参考

  • array_count_values() - 配列内に存在する、異なる値の出現回数を数える


一つ以上の要素を配列の最初に加える

  • ≪ array_unique
  • array_values ≫
  • PHP Manual
  • 配列 関数
  • 一つ以上の要素を配列の最初に加える

array_unshift

(PHP 4, PHP 5, PHP 7, PHP 8)

array_unshift — 一つ以上の要素を配列の最初に加える

説明

array_unshift(array &$array, mixed ...$values): int

array_unshift() は、array の先頭に指定された要素を加えます。リストの要素は全体として加えられるため、 加えられた要素の順番は変わらないことに注意してください。 配列の数値添字はすべて新たにゼロから振りなおされます。 リテラルのキーについては変更されません。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

values

加える値。

戻り値

処理後の array の要素の数を返します。

変更履歴

バージョン | 説明
7.3.0 | この関数は、1 つのパラメータでのみ呼び出すことができるようになりました。 前は、少なくとも 2 つのパラメータが必要でした。

例

例1 array_unshift() の例

<?php
$queue = [
"orange",
"banana"
];

array_unshift($queue, "apple", "raspberry");
var_dump($queue);
?>

上の例の出力は以下となります。

array(4) {
  [0] =>
  string(5) "apple"
  [1] =>
  string(9) "raspberry"
  [2] =>
  string(6) "orange"
  [3] =>
  string(6) "banana"
}

例2 連想配列と一緒に使う例

連想配列を別の連想配列の前に加える場合、 追加される配列は、もともとある配列の整数のインデックスに追加されます。

<?php
$foods = [
'apples' => [
'McIntosh' => 'red',
'Granny Smith' => 'green',
],
'oranges' => [
'Navel' => 'orange',
'Valencia' => 'orange',
],
];
$vegetables = [
'lettuce' => [
'Iceberg' => 'green',
'Butterhead' => 'green',
],
'carrots' => [
'Deep Purple Hybrid' => 'purple',
'Imperator' => 'orange',
],
'cucumber' => [
'Kirby' => 'green',
'Gherkin' => 'green',
],
];

array_unshift($foods, $vegetables);
var_dump($foods);

上の例の出力は以下となります。

array(3) {
  [0] =>
  array(3) {
    'lettuce' =>
    array(2) {
      'Iceberg' =>
      string(5) "green"
      'Butterhead' =>
      string(5) "green"
    }
    'carrots' =>
    array(2) {
      'Deep Purple Hybrid' =>
      string(6) "purple"
      'Imperator' =>
      string(6) "orange"
    }
    'cucumber' =>
    array(2) {
      'Kirby' =>
      string(5) "green"
      'Gherkin' =>
      string(5) "green"
    }
  }
  'apples' =>
  array(2) {
    'McIntosh' =>
    string(3) "red"
    'Granny Smith' =>
    string(5) "green"
  }
  'oranges' =>
  array(2) {
    'Navel' =>
    string(6) "orange"
    'Valencia' =>
    string(6) "orange"
  }
}

参考

  • array_merge() - ひとつまたは複数の配列をマージする
  • array_shift() - 配列の先頭から要素を一つ取り出す
  • array_push() - 一つ以上の要素を配列の最後に追加する
  • array_pop() - 配列の末尾から要素を取り除く


配列の全ての値を返す

  • ≪ array_unshift
  • array_walk ≫
  • PHP Manual
  • 配列 関数
  • 配列の全ての値を返す

array_values

(PHP 4, PHP 5, PHP 7, PHP 8)

array_values — 配列の全ての値を返す

説明

array_values(array $array): array

array_values() は、配列 array から全ての値を取り出し、数値添字をつけた配列を返します。

パラメータ

array

配列。

戻り値

数値添字の値の配列を返します。

例

例1 array_values() の例

<?php
$array = array("size" => "XL", "color" => "gold");
print_r(array_values($array));
?>

上の例の出力は以下となります。

Array
(
    [0] => XL
    [1] => gold
)

参考

  • array_keys() - 配列のキーすべて、あるいはその一部を返す
  • array_combine() - 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する


配列の全ての要素にユーザー定義の関数を適用する

  • ≪ array_values
  • array_walk_recursive ≫
  • PHP Manual
  • 配列 関数
  • 配列の全ての要素にユーザー定義の関数を適用する

array_walk

(PHP 4, PHP 5, PHP 7, PHP 8)

array_walk — 配列の全ての要素にユーザー定義の関数を適用する

説明

array_walk(array|object &$array, callable $callback, mixed $arg = null): true

array 配列の各要素にユーザー定義関数 callback を適用します。

array_walk() は array の内部配列ポインタに影響されません。array_walk() はポインタの位置に関わらず配列の全てに渡って適用されます。

パラメータ

array

入力の配列。

callback

通常、 callback は引数を二つとります。 array パラメータの値が最初の引数、 キー/添字は二番目の引数となります。

注意:

callback により配列の値そのものを変更する必要がある場合、 callback の最初の引数は リファレンス として渡す必要があります。この場合、配列の要素に加えた変更は、 配列自体に対して行われます。

注意:

内部関数の多く (たとえば strtolower()) は、 期待しているよりも多い引数を受け取ると警告が発生します。 そのため、callback に直接指定することはできません。

変更される可能性があるのは配列の値だけであり、 その構造を変更することはできません。つまり、 プログラマは要素の追加や削除そして並べ替えなどができないということです。 コールバック関数がこの条件を満たさない場合は、 この関数の動作は未定義で予期せぬ結果を得ることになります。

arg

オプションの arg パラメータが指定された場合、 コールバック関数 callback への三番目の引数として渡されます。

戻り値

常に true を返します。

エラー / 例外

PHP 7.1.0 以降では、callback 関数が 2個より多いパラメータ（配列メンバーの値およびキー）を必要とする場合、 または、(arg も渡されている場合) 3個より多いパラメータを必要とする場合、 ArgumentCountError がスローされます。 7.1.0 より前のバージョンでは、callback 関数が 2 つより多いパラメータを必要とする場合、 array_walk() が callback をコールする度にエラーレベル E_WARNING が 発生させていました。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.0.0 | callback が、 2番目と3番目の引数にリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 array_walk() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");

function test_alter(&$item1, $key, $prefix)
{
$item1 = "$prefix: $item1";
}

function test_print($item2, $key)
{
echo "$key. $item2\n";
}

echo "Before ...:\n";
array_walk($fruits, 'test_print');

array_walk($fruits, 'test_alter', 'fruit');
echo "... and after:\n";

array_walk($fruits, 'test_print');
?>

上の例の出力は以下となります。

Before ...:
d. lemon
a. orange
b. banana
c. apple
... and after:
d. fruit: lemon
a. fruit: orange
b. fruit: banana
c. fruit: apple

例2 無名関数を使った、array_walk() の例

<?php
$elements = ['a', 'b', 'c'];

array_walk($elements, function ($value, $key) {
echo "{$key} => {$value}\n";
});

?>

上の例の出力は以下となります。

0 => a
1 => b
2 => c

参考

  • array_walk_recursive() - 配列の全ての要素に、ユーザー関数を再帰的に適用する
  • iterator_apply() - ユーザー関数をイテレータのすべての要素でコールする
  • list() - 配列と同様の形式で、複数の変数への代入を行う
  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める
  • call_user_func_array() - パラメータの配列を指定してコールバック関数をコールする
  • array_map() - 指定した配列の要素にコールバック関数を適用する
  • foreach


配列の全ての要素に、ユーザー関数を再帰的に適用する

  • ≪ array_walk
  • arsort ≫
  • PHP Manual
  • 配列 関数
  • 配列の全ての要素に、ユーザー関数を再帰的に適用する

array_walk_recursive

(PHP 5, PHP 7, PHP 8)

array_walk_recursive — 配列の全ての要素に、ユーザー関数を再帰的に適用する

説明

array_walk_recursive(array|object &$array, callable $callback, mixed $arg = null): true

array 配列の各要素にユーザー定義関数 callbackを適用します。 この関数は配列の要素内を再帰的にたどっていきます。

パラメータ

array

入力の配列。

callback

通常、 callback は引数を二つとります。 array パラメータの値が最初の引数、 キー/添字は二番目の引数となります。

注意:

callback により配列の値そのものを変更する必要がある場合、 callback の最初の引数は リファレンス として渡す必要があります。この場合、配列の要素に加えた変更は、 配列自体に対して行われます。

arg

オプションの arg パラメータが指定された場合、 コールバック関数 callback への三番目の引数として渡されます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 array_walk_recursive() の例

<?php
$sweet = array('a' => 'apple', 'b' => 'banana');
$fruits = array('sweet' => $sweet, 'sour' => 'lemon');

function test_print($item, $key)
{
echo "$key holds $item\n";
}

array_walk_recursive($fruits, 'test_print');
?>

上の例の出力は以下となります。

a holds apple
b holds banana
sour holds lemon

キー 'sweet' が表示されないことにお気づきでしょう。array を要素として持つキーは関数に渡されません。

参考

  • array_walk() - 配列の全ての要素にユーザー定義の関数を適用する


連想キーと要素との関係を維持しつつ配列を降順にソートする

  • ≪ array_walk_recursive
  • asort ≫
  • PHP Manual
  • 配列 関数
  • 連想キーと要素との関係を維持しつつ配列を降順にソートする

arsort

(PHP 4, PHP 5, PHP 7, PHP 8)

arsort — 連想キーと要素との関係を維持しつつ配列を降順にソートする

説明

arsort(array &$array, int $flags = SORT_REGULAR): true

各配列のキーと要素との関係を維持しつつ、array を降順にソートします。

この関数は、主に実際の要素の並び方が重要である連想配列をソートするために使われます。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 arsort() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
arsort($fruits);
foreach ($fruits as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

a = orange
d = lemon
b = banana
c = apple

fruits はアルファベットの降順にソートされ、 各要素とキーとの関係は維持されます。

参考

  • sort() - 配列を昇順にソートする
  • asort() - 連想キーと要素との関係を維持しつつ配列を昇順にソートする
  • 配列ソート関数の比較


連想キーと要素との関係を維持しつつ配列を昇順にソートする

  • ≪ arsort
  • compact ≫
  • PHP Manual
  • 配列 関数
  • 連想キーと要素との関係を維持しつつ配列を昇順にソートする

asort

(PHP 4, PHP 5, PHP 7, PHP 8)

asort — 連想キーと要素との関係を維持しつつ配列を昇順にソートする

説明

asort(array &$array, int $flags = SORT_REGULAR): true

配列のキーと要素との関係を維持しつつ、 array を昇順にソートします。

この関数は、 主に実際の要素の並び方が重要である連想配列をソートするために使われます。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 asort() の例

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
asort($fruits);
foreach ($fruits as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

c = apple
b = banana
d = lemon
a = orange

fruits はアルファベットの昇順にソートされ、 各要素とキーとの関係は維持されます。

参考

  • sort() - 配列を昇順にソートする
  • arsort() - 連想キーと要素との関係を維持しつつ配列を降順にソートする
  • 配列ソート関数の比較


変数名とその値から配列を作成する

  • ≪ asort
  • count ≫
  • PHP Manual
  • 配列 関数
  • 変数名とその値から配列を作成する

compact

(PHP 4, PHP 5, PHP 7, PHP 8)

compact — 変数名とその値から配列を作成する

説明

compact(array|string $var_name, array|string ...$var_names): array

変数名とその値から配列を作成します。

各引数について、compact() は現在のシンボルテーブルにおいてその名前を有する変数を探し、 変数名がキー、変数の値がそのキーに関する値となるように追加します。 端的に言うと、extract() の逆の動作をします。

注意:

PHP 7.3 より前のバージョンでは、設定されていない全ての文字列は、単にスキップされます。

パラメータ

var_name
var_names

compact() がとるパラメータの数は可変です。 各パラメータは、変数名を値とする文字列か、 変数名の配列のどちらかとすることができます。 配列は、変数名を値とする別の配列を持つことができます。 compact()はこれを再帰的に処理します。

戻り値

追加された全ての変数を値とする出力配列を返します。

エラー / 例外

compact() は、与えられた文字列が示す変数が未定義の場合、 E_WARNING レベルのエラーを発行します。

変更履歴

バージョン | 説明
7.3.0 | compact() は、与えられた文字列が示す変数が未定義の場合、 E_NOTICE レベルのエラーを発行するようになりました。 以前のバージョンでは、設定されていない全ての文字列は、単にスキップされます。

例

例1 compact() の例

<?php
$city = "San Francisco";
$state = "CA";
$event = "SIGGRAPH";

$location_vars = array("city", "state");

$result = compact("event", $location_vars);
print_r($result);
?>

上の例の出力は以下となります。

Array
(
    [event] => SIGGRAPH
    [city] => San Francisco
    [state] => CA
)

注意

注意: 分かった!

可変変数 は関数内で PHP の スーパーグローバル配列 と併用してはいけませんので、 スーパーグローバル配列を compact() に渡してはいけません。

参考

  • extract() - 配列からシンボルテーブルに変数をインポートする


配列または Countable オブジェクトに含まれるすべての要素の数を数える

  • ≪ compact
  • current ≫
  • PHP Manual
  • 配列 関数
  • 配列または Countable オブジェクトに含まれるすべての要素の数を数える

count

(PHP 4, PHP 5, PHP 7, PHP 8)

count — 配列または Countable オブジェクトに含まれるすべての要素の数を数える

説明

count(Countable|array $value, int $mode = COUNT_NORMAL): int

配列の場合は、配列の全ての要素を数えます。 Countable インターフェイスを実装したオブジェクトの場合は、 Countable::count() の戻り値を返します。

パラメータ

value

配列あるいは Countable オブジェクト。

mode

オプションのmode 引数が COUNT_RECURSIVE (または 1) にセットされた場合、count() は再帰的に配列をカウントします。 これは多次元配列の全ての要素をカウントするといった場合に特に有効です。

警告

count() は、再帰を検出して無限ループを回避するようになっています。 しかしその場合 (配列の中に自分自身が複数回登場する場合) は毎回 E_WARNING を発行し、期待する結果より大きい数を返します。

戻り値

value の要素の数を返します。 PHP 8.0.0 より前のバージョンでは、 パラメータが配列でもなく Countable インターフェイスを 実装したオブジェクトでもない場合、1 が返されていました。 ただし、value が null の場合、 0 が返されていました。

変更履歴

バージョン | 説明
8.0.0 | value パラメータに不正な型を渡した場合に、 TypeError をスローするようになりました。
7.2.0 | value パラメータに不正な型を渡した場合に、 警告を発生させるようになりました。

例

例1 count() の例

<?php
$a[0] = 1;
$a[1] = 3;
$a[2] = 5;
var_dump(count($a));

$b[0] = 7;
$b[5] = 9;
$b[10] = 11;
var_dump(count($b));
?>

上の例の出力は以下となります。

int(3)
int(3)

例2 Countable|array でない値を渡した場合の count() の例 (悪い例です - 真似しないでね！)

<?php
$b[0] = 7;
$b[5] = 9;
$b[10] = 11;
var_dump(count($b));

var_dump(count(null));

var_dump(count(false));
?>

上の例の出力は以下となります。

int(3)
int(0)
int(1)

上の例の PHP 7.2 での出力は、このようになります。

int(3)

Warning: count(): Parameter must be an array or an object that implements Countable in ... on line 12
int(0)

Warning: count(): Parameter must be an array or an object that implements Countable in ... on line 14
int(1)

上の例の PHP 8 での出力は、このようになります。:

int(3)

Fatal error: Uncaught TypeError: count(): Argument #1 ($var) must be of type Countable .. on line 12

例3 再帰的な count() の例

<?php
$food = array('fruits' => array('orange', 'banana', 'apple'),
'veggie' => array('carrot', 'collard', 'pea'));

// recursive count
var_dump(count($food, COUNT_RECURSIVE));

// normal count
var_dump(count($food));

?>

上の例の出力は以下となります。

int(8)
int(2)

例4 Countable オブジェクトの例

<?php
class CountOfMethods implements Countable
{
private function someMethod()
{
}

public function count(): int
{
return count(get_class_methods($this));
}
}

$obj = new CountOfMethods();
var_dump(count($obj));
?>

上の例の出力は以下となります。

int(2)

参考

  • is_array() - 変数が配列かどうかを検査する
  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • empty() - 変数が空であるかどうかを検査する
  • strlen() - 文字列の長さを得る
  • is_countable() - 引数が、数えられる値かどうかを調べる
  • Arrays


配列内の現在の要素を返す

  • ≪ count
  • each ≫
  • PHP Manual
  • 配列 関数
  • 配列内の現在の要素を返す

current

(PHP 4, PHP 5, PHP 7, PHP 8)

current — 配列内の現在の要素を返す

説明

current(array|object $array): mixed

各配列は、"カレント"の要素へのポインタを有しています。 このポインタは、配列に挿入された最初の要素を指すように初期化されます。

パラメータ

array

配列。

戻り値

current() 関数は、 単に内部ポインタが現在指している配列要素の値を返します。 この関数は、ポインタを全く移動しません。 内部ポインタが最終要素の次を指していたり 配列が空だったりした場合、 current() は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.1.0 | この関数を object に対してコールすることは、推奨されなくなりました。 object に対して最初に get_mangled_object_vars() を使って配列に変換するか、ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。
7.4.0 | SPL クラスのインスタンスは、プロパティを持たない空のオブジェクトのように扱われるようになりました。これより前のバージョンでは、この関数と同じ名前の Iterator のメソッドをコールしていました。

例

例1 current() と類似関数の使用例

<?php
$transport = array('foot', 'bike', 'car', 'plane');
$mode = current($transport); // $mode = 'foot';
$mode = next($transport); // $mode = 'bike';
$mode = current($transport); // $mode = 'bike';
$mode = prev($transport); // $mode = 'foot';
$mode = end($transport); // $mode = 'plane';
$mode = current($transport); // $mode = 'plane';

$arr = array();
var_dump(current($arr)); // bool(false)

$arr = array(array());
var_dump(current($arr)); // array(0) { }
?>

注意

注意: 配列の最終要素の次を指していた場合や、 空の配列に対して、current() を呼び出した時の結果は、 bool false 要素を指していた場合と区別できません。 false 要素を含む配列を順に処理するには、制御構文 foreach を参照ください。 それでも current() を使い、 値が本当に配列の要素であることを適切にチェックするには、 current() が指す要素の key() の値が、 厳密に null ではないことをチェックすべきです。

参考

  • end() - 配列の内部ポインタを最終要素にセットする
  • key() - 配列からキーを取り出す
  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める
  • prev() - 内部の配列ポインタをひとつ前に戻す
  • reset() - 配列の内部ポインタを先頭の要素にセットする
  • next() - 配列の内部ポインタを進める
  • foreach


配列から現在のキーと値のペアを返して、カーソルを進める

  • ≪ current
  • end ≫
  • PHP Manual
  • 配列 関数
  • 配列から現在のキーと値のペアを返して、カーソルを進める

each

(PHP 4, PHP 5, PHP 7)

each — 配列から現在のキーと値のペアを返して、カーソルを進める

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

each(array|object &$array): array

配列から現在のキーと値のペアを返して、カーソルを進めます。

each() を実行した後、配列カーソルは、 配列の次の要素に移動します。配列の最終要素にカーソルがある場合は、 最終要素にとどまります。再度 each を使用して配列を走査するには、 reset() を使用する必要があります。

パラメータ

array

入力の配列。

戻り値

配列 array から現在のキーと値のペアを返します。 このペアは 4 つの要素を持つ配列で、 それぞれの要素は 0, 1, key, value というキーを有しています。 要素 0とkey の各々は配列要素のキー名称を保持しており、1 と value の各々はそのデータを保持しています。

配列の内部ポインタが配列の最終要素以降を指す場合、 each() は false を返します。

例

例1 each() の例

<?php
$foo = array("bob", "fred", "jussi", "jouni", "egon", "marliese");
$bar = each($foo);
print_r($bar);
?>

$bar は、ここでは以下のキー/値のペアを保持しています。

Array
(
    [1] => bob
    [value] => bob
    [0] => 0
    [key] => 0
)

<?php
$foo = array("Robert" => "Bob", "Seppo" => "Sepi");
$bar = each($foo);
print_r($bar);
?>

$bar は次のようなキー/値のペアを持つようになります。

Array
(
    [1] => Bob
    [value] => Bob
    [0] => Robert
    [key] => Robert
)

通常 each() は、配列の走査をするために list() と共に使用します。 例えばこのようになります。

例2 each() によって配列を走査する

<?php
$fruit = array('a' => 'apple', 'b' => 'banana', 'c' => 'cranberry');

reset($fruit);
while (list($key, $val) = each($fruit)) {
echo "$key => $val\n";
}
?>

上の例の出力は以下となります。

a => apple
b => banana
c => cranberry

警告

配列を他の変数に代入すると、もとの配列の内部ポインタがリセットされます。 そのため、上の例のループ内で $fruit を他の変数に代入すると、無限ループを引き起こしてしまいます。

警告

each() をオブジェクトに対して使用することもできますが、 予期せぬ結果を返すことになるかもしれません。 オブジェクトのプロパティを each() で反復処理することはおすすめしません。

参考

  • key() - 配列からキーを取り出す
  • list() - 配列と同様の形式で、複数の変数への代入を行う
  • current() - 配列内の現在の要素を返す
  • reset() - 配列の内部ポインタを先頭の要素にセットする
  • next() - 配列の内部ポインタを進める
  • prev() - 内部の配列ポインタをひとつ前に戻す
  • foreach
  • オブジェクトのイタレーション


配列の内部ポインタを最終要素にセットする

  • ≪ each
  • extract ≫
  • PHP Manual
  • 配列 関数
  • 配列の内部ポインタを最終要素にセットする

end

(PHP 4, PHP 5, PHP 7, PHP 8)

end — 配列の内部ポインタを最終要素にセットする

説明

end(array|object &$array): mixed

end() は array の内部ポインタを最後の要素まで進め、その値を返します。

パラメータ

array

配列。この配列は参照渡しとなります。関数内で配列の中身を変更するからです。 つまり、ここには配列そのものを渡さなければならず、 配列を返す関数を指定することはできません。 参照渡しできるのは、実際の変数だけだからです。

戻り値

最後の要素の値、あるいは空の配列の場合は false を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数を object に対してコールすることは、推奨されなくなりました。 object に対して最初に get_mangled_object_vars() を使って配列に変換するか、ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。
7.4.0 | SPL クラスのインスタンスは、プロパティを持たない空のオブジェクトのように扱われるようになりました。これより前のバージョンでは、この関数と同じ名前の Iterator のメソッドをコールしていました。

例

例1 end() の例

<?php

$fruits = array('リンゴ', 'バナナ', 'クランベリー');
echo end($fruits); // クランベリー

?>

参考

  • current() - 配列内の現在の要素を返す
  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める
  • prev() - 内部の配列ポインタをひとつ前に戻す
  • reset() - 配列の内部ポインタを先頭の要素にセットする
  • next() - 配列の内部ポインタを進める
  • array_key_last() - 配列の最後のキーを得る


配列からシンボルテーブルに変数をインポートする

  • ≪ end
  • in_array ≫
  • PHP Manual
  • 配列 関数
  • 配列からシンボルテーブルに変数をインポートする

extract

(PHP 4, PHP 5, PHP 7, PHP 8)

extract — 配列からシンボルテーブルに変数をインポートする

説明

extract(array &$array, int $flags = EXTR_OVERWRITE, string $prefix = ""): int

配列からシンボルテーブルに変数をインポートします。

各キーについて変数名として有効であるかどうか、 そして、シンボルテーブルの既存の変数と衝突しないかどうかを確認します。

警告

ユーザーの入力、例えば $_GET や $_FILES のような、 信頼できないデータに extract() を使用しないでください。

パラメータ

array

この関数は連想配列 var_array を引数とし、そのキーを変数名、値を変数の値として処理します。 各キー/値の組に関して、flags および prefix パラメータに基づき、 現在のシンボルテーブルに変数を一つ作成します。

連想配列を使用する必要があります。EXTR_PREFIX_ALL または EXTR_PREFIX_INVALID を使用しない限り、 数値添字の配列には結果は出力されません。

flags

無効または数値キーおよび衝突に関する対処法は、 flags で定義されます。 これは以下の値のどれかとなります。

EXTR_OVERWRITE
衝突があった場合、存在する変数が上書きされます。
EXTR_SKIP
衝突があった場合、存在する変数は上書きされません。
EXTR_PREFIX_SAME
衝突があった場合、prefix を前につけた新しい変数となります。
EXTR_PREFIX_ALL
全ての変数の前に prefix を付けます。
EXTR_PREFIX_INVALID
無効または数値の変数名のみに接頭辞 prefix を付けます。
EXTR_IF_EXISTS
現在のシンボルテーブルに既に存在する場合にのみ上書きします。 例えば $_REQUEST からあなたが定義した変数のみを展開し 有効な変数としたいような場合に有用です。
EXTR_PREFIX_IF_EXISTS
同じ変数だが接頭辞をつけていないバージョンの変数が 現在のシンボルテーブルに存在する場合にのみ 変数を生成します。
EXTR_REFS
変数を参照として展開します。 これはインポート済みの変数が、 array パラメータの値に常に参照付けられることを意味します。 このフラグを単独で使用するか、 あるいはflagsと和算することにより、 他のフラグとそれを組み合わせることができます。

flags が指定されない場合、 EXTR_OVERWRITE とみなされます。

prefix

prefix は、 flags が EXTR_PREFIX_SAME、EXTR_PREFIX_ALL、 EXTR_PREFIX_INVALID あるいは EXTR_PREFIX_IF_EXISTS の場合にのみ必要であることに注意してください。 接頭辞を付けた変数名が有効な変数名でない場合、 この変数はシンボルテーブルにインポートされません。接頭辞は、 アンダースコア文字で配列のキーから自動的に分割されます。

戻り値

シンボルテーブルにインポートした変数の数を返します。

例

例1 extract() の例

extract の使用例としては、シンボルテーブルに wddx_deserialize() から返された連想配列を インポートすることが考えられます。

<?php

/* $var_array はwddx_deserializeから返された配列と仮定します */

$size = "large";
$var_array = array("color" => "blue",
"size" => "medium",
"shape" => "sphere");
extract($var_array, EXTR_PREFIX_SAME, "wddx");

echo "$color, $size, $shape, $wddx_size\n";

?>

上の例の出力は以下となります。

blue, large, sphere, medium

EXTR_PREFIX_SAME を指定したため、$size は上書きされず、$wddx_size が作成されます。 EXTR_SKIP が指定された場合、$wddx_size は作成されません。 EXTR_OVERWRITE の場合は、$size の値は "medium" となります。 EXTR_PREFIX_ALL の場合は新規の変数 $wddx_color, $wddx_size, $wddx_shape が作成されます。

注意

警告

extract() をユーザー入力 ($_GET や $_FILES など) のような信頼できないデータについて使用しないでください。 もし行う場合、 EXTR_SKIP のような flags の値が上書きされていないことを確認してください。そして php.ini の variables_order で定義されたものと同じ順で展開すべきであることに留意してください。

参考

  • compact() - 変数名とその値から配列を作成する
  • list() - 配列と同様の形式で、複数の変数への代入を行う


配列に値があるかチェックする

  • ≪ extract
  • key ≫
  • PHP Manual
  • 配列 関数
  • 配列に値があるかチェックする

in_array

(PHP 4, PHP 5, PHP 7, PHP 8)

in_array — 配列に値があるかチェックする

説明

in_array(mixed $needle, array $haystack, bool $strict = false): bool

haystack 内の needle を検索します。 strict が設定されていない限りは型の比較は行いません。

パラメータ

needle

探す値。

注意:

needle が文字列の場合、 比較の際に大文字小文字は区別されます。

haystack

配列。

strict

三番目のパラメータ strict が true に設定された場合、 in_array() は、haystack の中の needle の 型も確認します。

注意:

PHP 8.0.0 より前のバージョンでは、 strict フラグが指定されていない場合に、 配列の値が 0 の場合でも文字列にマッチしてしまっていました。逆も同じです。 これにより、望ましくない結果が生じる可能性があります。 似たようなエッジケースは他の型でも存在します。 値の型が完全にわからない場合には、 予期せぬ振る舞いを避けるために常に strict フラグを使うようにして下さい。

戻り値

配列で needle が見つかった場合に true、それ以外の場合は、false を返します。

例

例1 in_array() の例

<?php
$os = array("Mac", "NT", "Irix", "Linux");
if (in_array("Irix", $os)) {
echo "Got Irix";
}
if (in_array("mac", $os)) {
echo "Got mac";
}
?>

二番目の条件式は失敗します。in_array() は大文字小文字を区別するからです。したがって次のような出力になります。

Got Irix

例2 strict を指定した in_array() の例

<?php
$a = array('1.10', 12.4, 1.13);

if (in_array('12.4', $a, true)) {
echo "'12.4' found with strict check\n";
}

if (in_array(1.13, $a, true)) {
echo "1.13 found with strict check\n";
}
?>

上の例の出力は以下となります。

1.13 found with strict check

例3 needleが配列の場合の in_array()

<?php
$a = array(array('p', 'h'), array('p', 'r'), 'o');

if (in_array(array('p', 'h'), $a)) {
echo "'ph' was found\n";
}

if (in_array(array('f', 'i'), $a)) {
echo "'fi' was found\n";
}

if (in_array('o', $a)) {
echo "'o' was found\n";
}
?>

上の例の出力は以下となります。

'ph' was found
  'o' was found

参考

  • array_search() - 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す
  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • array_key_exists() - 指定したキーまたは添字が配列にあるかどうかを調べる


配列からキーを取り出す

  • ≪ in_array
  • key_exists ≫
  • PHP Manual
  • 配列 関数
  • 配列からキーを取り出す

key

(PHP 4, PHP 5, PHP 7, PHP 8)

key — 配列からキーを取り出す

説明

key(array|object $array): int|string|null

key() は、 現在の配列位置における連想配列要素のキーを返します。

パラメータ

array

配列。

戻り値

key() 関数は、内部ポインタが現在指している配列要素のキーを返します。 ポインタを移動することはありません。内部ポインタが要素リストの末尾にいる場合や配列が空の場合は key() は null を返します。

変更履歴

バージョン | 説明
8.1.0 | この関数を object に対してコールすることは、推奨されなくなりました。 object に対して最初に get_mangled_object_vars() を使って配列に変換するか、ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。
7.4.0 | SPL クラスのインスタンスは、プロパティを持たない空のオブジェクトのように扱われるようになりました。これより前のバージョンでは、この関数と同じ名前の Iterator のメソッドをコールしていました。

例

例1 key() の例

<?php
$array = array(
'fruit1' => 'リンゴ',
'fruit2' => 'オレンジ',
'fruit3' => 'ブドウ',
'fruit4' => 'リンゴ',
'fruit5' => 'リンゴ');

// このループは値が "リンゴ" である
// 全ての連想配列のキーを表示します
while ($fruit_name = current($array)) {
if ($fruit_name == 'リンゴ') {
echo key($array), "\n";
}
next($array);
}
?>

上の例の出力は以下となります。

fruit1
fruit4
fruit5

参考

  • current() - 配列内の現在の要素を返す
  • next() - 配列の内部ポインタを進める
  • array_key_first() - 配列の最初のキーを得る
  • foreach


array_key_exists のエイリアス

  • ≪ key
  • krsort ≫
  • PHP Manual
  • 配列 関数
  • array_key_exists のエイリアス

key_exists

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

key_exists — array_key_exists() のエイリアス

説明

この関数は次の関数のエイリアスです。 array_key_exists()


配列をキーで降順にソートする

  • ≪ key_exists
  • ksort ≫
  • PHP Manual
  • 配列 関数
  • 配列をキーで降順にソートする

krsort

(PHP 4, PHP 5, PHP 7, PHP 8)

krsort — 配列をキーで降順にソートする

説明

krsort(array &$array, int $flags = SORT_REGULAR): true

array をキーで降順にソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.2.0 | SORT_REGULAR を使って数値文字列の比較を行う際に、 PHP 8 で標準になっているルールを使うようになりました。

例

例1 krsort() の例

<?php
$fruits = array("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
krsort($fruits);
foreach ($fruits as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

d = lemon
c = apple
b = banana
a = orange

参考

  • sort() - 配列を昇順にソートする
  • ksort() - 配列をキーで昇順にソートする
  • 配列ソート関数の比較


配列をキーで昇順にソートする

  • ≪ krsort
  • list ≫
  • PHP Manual
  • 配列 関数
  • 配列をキーで昇順にソートする

ksort

(PHP 4, PHP 5, PHP 7, PHP 8)

ksort — 配列をキーで昇順にソートする

説明

ksort(array &$array, int $flags = SORT_REGULAR): true

array をキーで昇順にソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.2.0 | SORT_REGULAR を使って数値文字列の比較を行う際に、 PHP 8 で標準になっているルールを使うようになりました。

例

例1 ksort() の例

<?php
$fruits = array("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
ksort($fruits);
foreach ($fruits as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

a = orange
b = banana
c = apple
d = lemon

例2 数値がキーの場合の ksort() の振る舞い

<?php
$a = [0 => 'First', 2 => 'Last', 1 => 'Middle'];
var_dump($a);
ksort($a);
var_dump($a);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(5) "First"
  [2]=>
  string(4) "Last"
  [1]=>
  string(6) "Middle"
}
array(3) {
  [0]=>
  string(5) "First"
  [1]=>
  string(6) "Middle"
  [2]=>
  string(4) "Last"
}

参考

  • sort() - 配列を昇順にソートする
  • krsort() - 配列をキーで降順にソートする
  • 配列ソート関数の比較


配列と同様の形式で、複数の変数への代入を行う

  • ≪ ksort
  • natcasesort ≫
  • PHP Manual
  • 配列 関数
  • 配列と同様の形式で、複数の変数への代入を行う

list

(PHP 4, PHP 5, PHP 7, PHP 8)

list — 配列と同様の形式で、複数の変数への代入を行う

説明

list(mixed $var, mixed ...$vars = ?): array

array() と同様に、 この関数は実際には関数ではなく言語構造です。 list() は、 単一の操作で一連の変数に値を代入するために使われます。 この関数は、文字列を扱うことは出来ませんし、 list() には、空の式を指定できません。

注意:

PHP 7.1.0 より前のバージョンでは、list() は数値添字の配列でのみ動作し、 また、添字は 0 から始まることを想定していました。

パラメータ

var

変数。

vars

残りの変数。

戻り値

代入した配列を返します。

変更履歴

バージョン | 説明
7.3.0 | 配列へ分割して代入する操作が、リファレンスへの代入をサポートしました。
7.1.0 | キーを list() 関数で指定できるようになりました。 これによって、キーが数値でなかったり、連続していなかったりした場合に配列の構造を変えることができるようになります。

例

例1 list() の例

<?php

$info = array('コーヒー', '茶色', 'カフェイン');

// すべての変数の取得
list($drink, $color, $power) = $info;
echo "$drink の色は $color で、$power が含まれています。\n";

// 一部の変数の取得
list($drink, , $power) = $info;
echo "$drink には $power が含まれています。\n";

// 三番目のみの取得
list( , , $power) = $info;
echo "$power 欲しい!\n";

// list() は文字列では動作しません
list($bar) = "abcde";
var_dump($bar); // NULL
?>

例2 list() の使用法の例

<?php
result = $pdo->query("SELECT id, name FROM employees");
while (list($id, $name) = $result->fetch(PDO::FETCH_NUM)) {
echo "id: $id, name: $name\n";
}
?>

例3 ネストした list() の使用法

<?php

list($a, list($b, $c)) = array(1, array(2, 3));

var_dump($a, $b, $c);

?>
int(1)
int(2)
int(3)

例4 list() と添字の定義順

list() が配列の要素をどの順に処理するかは、配列の添字とは無関係です。

<?php
$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');
$foo[1] = 'd';
list($x, $y, $z) = $foo;
var_dump($foo, $x, $y, $z);

結果は次のようになります (list() 内で要素をどの順で利用しているかに注目しましょう)。

array(4) {
  [2]=>
  string(1) "a"
  ["foo"]=>
  string(1) "b"
  [0]=>
  string(1) "c"
  [1]=>
  string(1) "d"
}
string(1) "c"
string(1) "d"
string(1) "a"

例5 list() をキーを指定して使う

PHP 7.1.0 以降では、list() に明示的に キーを含めることができるようになりました。 任意の式も指定可能です。 数値や文字のキーも許されますが、 キーがない要素とある要素を混ぜることは許されません

<?php
$data = [
["id" => 1, "name" => 'Tom'],
["id" => 2, "name" => 'Fred'],
];
foreach ($data as ["id" => $id, "name" => $name]) {
echo "id: $id, name: $name\n";
}
echo PHP_EOL;
list(1 => $second, 3 => $fourth) = [1, 2, 3, 4];
echo "$second, $fourth\n";

上の例の出力は以下となります。

id: 1, name: Tom
id: 2, name: Fred

2, 4

参考

  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める
  • array() - 配列を生成する
  • extract() - 配列からシンボルテーブルに変数をインポートする


大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする

  • ≪ list
  • natsort ≫
  • PHP Manual
  • 配列 関数
  • 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする

natcasesort

(PHP 4, PHP 5, PHP 7, PHP 8)

natcasesort — 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする

説明

natcasesort(array &$array): true

natcasesort() は、大文字小文字を区別しないバージョンの natsort() です。

この関数は、人間が行うような手法でアルファベットまたは数字の文字列の順番を キー/値の関係を保持したままソートします。 これは、"自然順(natural ordering)"と呼ばれているものです。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 natcasesort() の例

<?php
$array1 = $array2 = array('IMG0.png', 'img12.png', 'img10.png', 'img2.png', 'img1.png', 'IMG3.png');

sort($array1);
echo "Standard sorting\n";
print_r($array1);

natcasesort($array2);
echo "\nNatural order sorting (case-insensitive)\n";
print_r($array2);
?>

上の例の出力は以下となります。

Standard sorting
Array
(
    [0] => IMG0.png
    [1] => IMG3.png
    [2] => img1.png
    [3] => img10.png
    [4] => img12.png
    [5] => img2.png
)

Natural order sorting (case-insensitive)
Array
(
    [0] => IMG0.png
    [4] => img1.png
    [3] => img2.png
    [5] => IMG3.png
    [2] => img10.png
    [1] => img12.png
)

より詳細な情報については、Martin Poolの » Natural Order String Comparison ページを参照ください。

参考

  • natsort() - "自然順"アルゴリズムで配列をソートする
  • 配列ソート関数の比較
  • strnatcmp() - "自然順"アルゴリズムにより文字列比較を行う
  • strnatcasecmp() - "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う


"自然順"アルゴリズムで配列をソートする

  • ≪ natcasesort
  • next ≫
  • PHP Manual
  • 配列 関数
  • "自然順"アルゴリズムで配列をソートする

natsort

(PHP 4, PHP 5, PHP 7, PHP 8)

natsort — "自然順"アルゴリズムで配列をソートする

説明

natsort(array &$array): true

この関数は、人間が行うような手法でアルファベットまたは数字の文字列の順番を キー/値の関係を保持したままソートします。 これは、"自然順(natural ordering)"と呼ばれているものです。 このアルゴリズムと (sort() を用いた) 通常のコンピュータ文字列ソートアルゴリズムの違いを示す例を以下に示します。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 natsort() の基本的な使用例

<?php
$array1 = $array2 = array("img12.png", "img10.png", "img2.png", "img1.png");

asort($array1);
echo "Standard sorting\n";
print_r($array1);

natsort($array2);
echo "\nNatural order sorting\n";
print_r($array2);
?>

上の例の出力は以下となります。

Standard sorting
Array
(
    [3] => img1.png
    [1] => img10.png
    [0] => img12.png
    [2] => img2.png
)

Natural order sorting
Array
(
    [3] => img1.png
    [2] => img2.png
    [1] => img10.png
    [0] => img12.png
)

より詳細な情報については、Martin Poolの » Natural Order String Comparison ページを参照ください。

例2 natsort() をより知るための例

<?php
echo "負の数\n";
$negative = array('-5','3','-2','0','-1000','9','1');
print_r($negative);
natsort($negative);
print_r($negative);

echo "ゼロ埋め\n";
$zeros = array('09', '8', '10', '009', '011', '0');
print_r($zeros);
natsort($zeros);
print_r($zeros);
?>

上の例の出力は以下となります。

負の数
Array
(
    [0] => -5
    [1] => 3
    [2] => -2
    [3] => 0
    [4] => -1000
    [5] => 9
    [6] => 1
)
Array
(
    [2] => -2
    [0] => -5
    [4] => -1000
    [3] => 0
    [6] => 1
    [1] => 3
    [5] => 9
)

ゼロ埋め
Array
(
    [0] => 09
    [1] => 8
    [2] => 10
    [3] => 009
    [4] => 011
    [5] => 0
)
Array
(
    [5] => 0
    [1] => 8
    [3] => 009
    [0] => 09
    [2] => 10
    [4] => 011
)

参考

  • natcasesort() - 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする
  • 配列ソート関数の比較
  • strnatcmp() - "自然順"アルゴリズムにより文字列比較を行う
  • strnatcasecmp() - "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う


配列の内部ポインタを進める

  • ≪ natsort
  • pos ≫
  • PHP Manual
  • 配列 関数
  • 配列の内部ポインタを進める

next

(PHP 4, PHP 5, PHP 7, PHP 8)

next — 配列の内部ポインタを進める

説明

next(array|object &$array): mixed

next() は、ひとつの違いを除いて
current() と同じです。
next() は要素を返す前に内部配列ポインタをひとつ先に進めます。
つまり、次の配列要素を返すとともに内部配列ポインタをひとつ進めるということです。

パラメータ

array

対象となる配列。

戻り値

内部配列ポインタが指す場所の次の場所の値を返します。 それ以上要素がない場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.1.0 | この関数を object に対してコールすることは、推奨されなくなりました。 object に対して最初に get_mangled_object_vars() を使って配列に変換するか、ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。
7.4.0 | SPL クラスのインスタンスは、プロパティを持たない空のオブジェクトのように扱われるようになりました。これより前のバージョンでは、この関数と同じ名前の Iterator のメソッドをコールしていました。

例

例1 next() および類似関数の使用例

<?php
$transport = array('foot', 'bike', 'car', 'plane');
$mode = current($transport); // $mode = 'foot';
$mode = next($transport); // $mode = 'bike';
$mode = next($transport); // $mode = 'car';
$mode = prev($transport); // $mode = 'bike';
$mode = end($transport); // $mode = 'plane';
?>

注意

注意: 配列の最後の要素に対してこの関数を実行した結果は、 次の要素が bool false だった場合と区別できません。 false 要素を含む配列を順に処理するには、foreach 関数を参照ください。 それでも next() 関数を使い、 適切に配列の最後に達していることをチェックするには、 key() 関数の結果が null であることを確認するようにしてください。

参考

  • current() - 配列内の現在の要素を返す
  • end() - 配列の内部ポインタを最終要素にセットする
  • prev() - 内部の配列ポインタをひとつ前に戻す
  • reset() - 配列の内部ポインタを先頭の要素にセットする
  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める


current のエイリアス

  • ≪ next
  • prev ≫
  • PHP Manual
  • 配列 関数
  • current のエイリアス

pos

(PHP 4, PHP 5, PHP 7, PHP 8)

pos — current() のエイリアス

説明

この関数は次の関数のエイリアスです。 current()


内部の配列ポインタをひとつ前に戻す

  • ≪ pos
  • range ≫
  • PHP Manual
  • 配列 関数
  • 内部の配列ポインタをひとつ前に戻す

prev

(PHP 4, PHP 5, PHP 7, PHP 8)

prev — 内部の配列ポインタをひとつ前に戻す

説明

prev(array|object &$array): mixed

内部の配列ポインタをひとつ前に戻します。

prev() は、 内部の配列ポインタを進めるのではなく戻すということを除けば next() と同じです。

パラメータ

array

入力の配列。

戻り値

内部の配列ポインタが指している前の場所の配列値を返します。 もう要素がない場合は false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.1.0 | この関数を object に対してコールすることは、推奨されなくなりました。 object に対して最初に get_mangled_object_vars() を使って配列に変換するか、ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。
7.4.0 | SPL クラスのインスタンスは、プロパティを持たない空のオブジェクトのように扱われるようになりました。これより前のバージョンでは、この関数と同じ名前の Iterator のメソッドをコールしていました。

例

例1 prev() および類似関数の使用例

<?php
$transport = array('foot', 'bike', 'car', 'plane');
$mode = current($transport); // $mode = 'foot';
$mode = next($transport); // $mode = 'bike';
$mode = next($transport); // $mode = 'car';
$mode = prev($transport); // $mode = 'bike';
$mode = end($transport); // $mode = 'plane';
?>

注意

注意: 配列の先頭でこの関数を実行した結果は、 先頭が bool の false だった場合と区別できません。 区別するには、prev() 要素の key() 要素が null でないかを確認するようにしてください。

参考

  • current() - 配列内の現在の要素を返す
  • end() - 配列の内部ポインタを最終要素にセットする
  • next() - 配列の内部ポインタを進める
  • reset() - 配列の内部ポインタを先頭の要素にセットする
  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める


ある範囲の要素を含む配列を作成する

  • ≪ prev
  • reset ≫
  • PHP Manual
  • 配列 関数
  • ある範囲の要素を含む配列を作成する

range

(PHP 4, PHP 5, PHP 7, PHP 8)

range — ある範囲の要素を含む配列を作成する

説明

range(string|int|float $start, string|int|float $end, int|float $step = 1): array

ある範囲の要素を含む配列を作成します。

start と end が両方文字列で、かつ step が整数の場合、 生成される配列はバイト列のシーケンスになります。 そうでない場合、生成される配列は数値のシーケンスになります。

start が end よりも小さい場合、シーケンスは増加します。 そうでない場合、シーケンスは減少します。

パラメータ

start

シーケンスの最初の値。

end

シーケンスの最後としてあり得る値。

step

step は、生成されるシーケンスの個別の値が どれくらい離れているかを指定します。

シーケンスが減少する場合、step は負の値を指定しても構いません。

step が 端数のない float の場合、整数として解釈されます。

戻り値

要素のシーケンスを配列として返します。 最初の要素は start になり、 end になるまで続きます。 シーケンスのそれぞれの値は、step だけ離れています。

返される配列の最後の要素は、 end または シーケンスの直前の要素になります。 どちらになるかは、step の値によります。

start と end が両方文字列で、かつ step が整数の場合、 生成される配列は、バイト列のシーケンスになります。 一般的にはラテン文字の ASCII 文字からなるシーケンスです。

start, end, step のうち少なくともひとつが float の場合、 生成される配列は float のシーケンスになります。

その他の場合、生成される配列は整数のシーケンスになります。

エラー / 例外

  • step が 0 の場合、ValueError がスローされます。
  • start, end, step が有限の値(is_finite()) でない場合、 ValueError がスローされます。
  • step が負の値なのに、生成される範囲が増えている(つまり、 $start <= $end) 場合、 ValueError がスローされます。
  • start または end が空文字列 '' の場合、E_WARNING が発生し、空文字列は 0 として解釈されます。
  • start または end が 数値形式の文字列 でない、長さが1バイトより大きい値の場合、E_WARNING が発生します。
  • start または end が 暗黙のうちに整数にキャストされた文字列の場合、 E_WARNING が発生します。なぜなら、他の境界の入力値は数値だからです。
  • step が float の場合、 かつ start と end が 数値形式の文字列 でない場合、E_WARNING が発生します。

変更履歴

バージョン | 説明
8.3.0 | start と end が両方文字列の場合、range() は常にバイト列を要素とした配列を生成するようになりました。 これより前のバージョンでは、境界の値のうちのひとつが数値形式の文字列の場合に、もう一方の境界の値を整数にキャストしていました。
8.3.0 | start または end が 暗黙のうちに整数にキャストされた文字列の場合、 E_WARNING が発生するようになりました。 なぜなら、他の境界の入力値が数値だからです。
8.3.0 | start または end が数値形式の文字列でなく、かつ長さが1バイトより大きい値の場合、 E_WARNING が発生するようになりました。
8.3.0 | start または end が空文字列の場合、E_WARNING が発生するようになりました。
8.3.0 | step が 端数のない float の場合、整数として解釈されるようになりました。
8.3.0 | step が負の値なのに、生成される範囲が増えている場合、 ValueError がスローされるようになりました。
8.3.0 | step が有限の値でない場合、 ValueError がスローされるようになりました。
8.3.0 | start または end が配列、object、resource の場合、 TypeError がスローされるようになりました。 これより前のバージョンでは、これらの値は暗黙のうちに整数にキャストされていました。

例

例1 range() の例

<?php
echo implode(', ', range(0, 12)), PHP_EOL;

echo implode(', ', range(0, 100, 10)), PHP_EOL;

echo implode(', ', range('a', 'i')), PHP_EOL;

echo implode(', ', range('c', 'a')), PHP_EOL;

echo implode(', ', range('A', 'z')), PHP_EOL;
?>

上の例の出力は以下となります。

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100
a, b, c, d, e, f, g, h, i
c, b, a
A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, [, \, ], ^, _, `, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z

参考

  • shuffle() - 配列をシャッフルする
  • array_fill() - 配列を指定した値で埋める
  • foreach


配列の内部ポインタを先頭の要素にセットする

  • ≪ range
  • rsort ≫
  • PHP Manual
  • 配列 関数
  • 配列の内部ポインタを先頭の要素にセットする

reset

(PHP 4, PHP 5, PHP 7, PHP 8)

reset — 配列の内部ポインタを先頭の要素にセットする

説明

reset(array|object &$array): mixed

reset() は、array の内部ポインタの先頭の要素に戻し、配列の最初の要素の値を返します。

パラメータ

array

入力の配列。

戻り値

配列の最初の要素の値を返します。 配列が空の場合 false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

変更履歴

バージョン | 説明
8.1.0 | この関数を object に対してコールすることは、推奨されなくなりました。 object に対して最初に get_mangled_object_vars() を使って配列に変換するか、ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。
7.4.0 | SPL クラスのインスタンスは、プロパティを持たない空のオブジェクトのように扱われるようになりました。これより前のバージョンでは、この関数と同じ名前の Iterator のメソッドをコールしていました。

例

例1 reset() の例

<?php

$array = array('step one', 'step two', 'step three', 'step four');

// デフォルトでは、ポインタは先頭要素を指しています
echo current($array) . "<br />\n"; // "step one"

// 次の２ステップをとばします
next($array);
next($array);
echo current($array) . "<br />\n"; // "step three"

// ポインタをリセットし、再度ステップ１開始します
reset($array);
echo current($array) . "<br />\n"; // "step one"

?>

注意

注意: 空の配列に対してこの関数を実行した場合の戻り値は、 配列の先頭要素に bool false がある配列に対して 実行した場合の戻り値と区別できません。 配列の先頭に false が含まれている可能性がある値を適切にチェックするには、 まず最初に 配列の count() をチェックするか、 reset() を呼び出した後に、 要素の key() が null でないことを確かめるようにしてください。

参考

  • current() - 配列内の現在の要素を返す
  • each() - 配列から現在のキーと値のペアを返して、カーソルを進める
  • end() - 配列の内部ポインタを最終要素にセットする
  • next() - 配列の内部ポインタを進める
  • prev() - 内部の配列ポインタをひとつ前に戻す
  • array_key_first() - 配列の最初のキーを得る


配列を降順にソートする

  • ≪ reset
  • shuffle ≫
  • PHP Manual
  • 配列 関数
  • 配列を降順にソートする

rsort

(PHP 4, PHP 5, PHP 7, PHP 8)

rsort — 配列を降順にソートする

説明

rsort(array &$array, int $flags = SORT_REGULAR): true

array を、値で降順にソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意: この関数は、 array パラメータの要素に対して新しいキーを割り当てます。 その際、単純にキーを並べ替える代わりに、 すでに割り当てられている既存のキーを削除してしまいます。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 rsort() の例

<?php
$fruits = array("lemon", "orange", "banana", "apple");
rsort($fruits);
foreach ($fruits as $key => $val) {
echo "$key = $val\n";
}
?>

上の例の出力は以下となります。

0 = orange
1 = lemon
2 = banana
3 = apple

fruits はアルファベットの降順にソートされました。

参考

  • sort() - 配列を昇順にソートする
  • arsort() - 連想キーと要素との関係を維持しつつ配列を降順にソートする
  • krsort() - 配列をキーで降順にソートする
  • 配列ソート関数の比較


配列をシャッフルする

  • ≪ rsort
  • sizeof ≫
  • PHP Manual
  • 配列 関数
  • 配列をシャッフルする

shuffle

(PHP 4, PHP 5, PHP 7, PHP 8)

shuffle — 配列をシャッフルする

説明

shuffle(array &$array): true

この関数は、配列をシャッフル (要素の順番をランダムに) します。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int() と random_bytes() 関数が、オペレーティングシステムの CSPRNG を使った、 便利で安全な API を提供します。

パラメータ

array

配列。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
7.1.0 | 内部的なランダム化のアルゴリズムが、 libc の rand 関数ではなく、 » メルセンヌツイスタ 乱数生成器 を使うように 変更されました。

例

例1 shuffle() の例

<?php
$numbers = range(1, 20);
shuffle($numbers);
foreach ($numbers as $number) {
echo "$number ";
}
?>

注意

注意: この関数は、 array パラメータの要素に対して新しいキーを割り当てます。 その際、単純にキーを並べ替える代わりに、 すでに割り当てられている既存のキーを削除してしまいます。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

参考

  • Random\Randomizer::shuffleArray() - 配列の順列を取得する
  • Random\Randomizer::shuffleBytes() - 指定された文字列の、バイト単位の順列を取得する
  • Random\Randomizer::pickArrayKeys() - ランダムに配列のキーを選択する
  • 配列ソート関数の比較


count のエイリアス

  • ≪ shuffle
  • sort ≫
  • PHP Manual
  • 配列 関数
  • count のエイリアス

sizeof

(PHP 4, PHP 5, PHP 7, PHP 8)

sizeof — count() のエイリアス

説明

この関数は次の関数のエイリアスです。 count().


配列を昇順にソートする

  • ≪ sizeof
  • uasort ≫
  • PHP Manual
  • 配列 関数
  • 配列を昇順にソートする

sort

(PHP 4, PHP 5, PHP 7, PHP 8)

sort — 配列を昇順にソートする

説明

sort(array &$array, int $flags = SORT_REGULAR): true

array を値で昇順にソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意: この関数は、 array パラメータの要素に対して新しいキーを割り当てます。 その際、単純にキーを並べ替える代わりに、 すでに割り当てられている既存のキーを削除してしまいます。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

flags

オプションの第二引数 flags によりソートの動作を修正可能です。 使える値は下記の通りです:

ソートタイプのフラグ:

  • SORT_REGULAR - 通常通りに項目を比較します。 詳細は 比較演算子 で説明されています。
  • SORT_NUMERIC - 数値として項目を比較します。
  • SORT_STRING - 文字列として項目を比較します。
  • SORT_LOCALE_STRING - 現在のロケールに基づいて、文字列として項目を比較します。 比較に使うロケールは、setlocale() 関数で変更できます。
  • SORT_NATURAL - 要素の比較を文字列として行い、 natsort() と同様の「自然順」で比較します。
  • SORT_FLAG_CASE - SORT_STRING や SORT_NATURAL と (ビットORで) 組み合わせて使い、 文字列のソートで大文字小文字を区別しないようにします。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。

例

例1 sort() の例

<?php

$fruits = array("lemon", "orange", "banana", "apple");
sort($fruits);
foreach ($fruits as $key => $val) {
echo "fruits[" . $key . "] = " . $val . "\n";
}

?>

上の例の出力は以下となります。

fruits[0] = apple
fruits[1] = banana
fruits[2] = lemon
fruits[3] = orange

fruits はアルファベットの昇順にソートされました。

例2 sort() で、大文字小文字を区別せずに自然順での並べ替えを行う例

<?php

$fruits = array(
"Orange1", "orange2", "Orange3", "orange20"
);
sort($fruits, SORT_NATURAL | SORT_FLAG_CASE);
foreach ($fruits as $key => $val) {
echo "fruits[" . $key . "] = " . $val . "\n";
}

?>

上の例の出力は以下となります。

fruits[0] = Orange1
fruits[1] = orange2
fruits[2] = Orange3
fruits[3] = orange20

fruits が natcasesort() と同じようにソートされました。

注意

注意: PHP の大半のソート関数と同様、sort() は » Quicksort でそれを実装しています。 ピボットは、既にソート済みの部分に対して時間的に最適なところを選択します。 しかしこれはあくまでも内部の実装の話なので、これに依存したコードを書いてはいけません。

警告

flags が SORT_REGULARの場合に 複数の型が混在する配列をソートする場合には、注意してください。 sort() が期待しない結果を出力することがあります。

参考

  • rsort() - 配列を降順にソートする
  • 配列ソート関数の比較


ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する

  • ≪ sort
  • uksort ≫
  • PHP Manual
  • 配列 関数
  • ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する

uasort

(PHP 4, PHP 5, PHP 7, PHP 8)

uasort — ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する

説明

uasort(array &$array, callable $callback): true

インデックスとそれに対応する要素を関連づけて array をソートします。 ソートには、ユーザー定義の比較関数を使います。

主に実際の配列の順序に意味がある連想配列をソートするためにこの関数は使用されます。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.0.0 | callback がリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 基本的な uasort() の例

<?php
// 比較用の関数
function cmp($a, $b) {
if ($a == $b) {
return 0;
}
return ($a < $b) ? -1 : 1;
}

// ソートしたい配列
$array = array('a' => 4, 'b' => 8, 'c' => -1, 'd' => -9, 'e' => 2, 'f' => 5, 'g' => 3, 'h' => -4);
print_r($array);

// ソートした結果の配列を表示します
uasort($array, 'cmp');
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [a] => 4
    [b] => 8
    [c] => -1
    [d] => -9
    [e] => 2
    [f] => 5
    [g] => 3
    [h] => -4
)
Array
(
    [d] => -9
    [h] => -4
    [c] => -1
    [e] => 2
    [g] => 3
    [a] => 4
    [f] => 5
    [b] => 8
)

参考

  • usort() - ユーザー定義の比較関数を使用して、配列を値でソートする
  • uksort() - ユーザー定義の比較関数を用いて、キーで配列をソートする
  • 配列ソート関数の比較


ユーザー定義の比較関数を用いて、キーで配列をソートする

  • ≪ uasort
  • usort ≫
  • PHP Manual
  • 配列 関数
  • ユーザー定義の比較関数を用いて、キーで配列をソートする

uksort

(PHP 4, PHP 5, PHP 7, PHP 8)

uksort — ユーザー定義の比較関数を用いて、キーで配列をソートする

説明

uksort(array &$array, callable $callback): true

順序を決めるユーザー定義の比較関数を用いて、 array のキーをソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意:

この関数をコールすると、配列の内部ポインタは最初の要素にリセットされます。

パラメータ

array

入力の配列。

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.0.0 | callback がリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 uksort() の例

<?php
function cmp($a, $b)
{
$a = preg_replace('@^(a|an|the) @', '', $a);
$b = preg_replace('@^(a|an|the) @', '', $b);
return strcasecmp($a, $b);
}

$a = array("John" => 1, "the Earth" => 2, "an apple" => 3, "a banana" => 4);

uksort($a, "cmp");

foreach ($a as $key => $value) {
echo "$key: $value\n";
}
?>

上の例の出力は以下となります。

an apple: 3
a banana: 4
the Earth: 2
John: 1

参考

  • usort() - ユーザー定義の比較関数を使用して、配列を値でソートする
  • uasort() - ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する
  • 配列ソート関数の比較


ユーザー定義の比較関数を使用して、配列を値でソートする

  • ≪ uksort
  • クラス/オブジェクト ≫
  • PHP Manual
  • 配列 関数
  • ユーザー定義の比較関数を使用して、配列を値でソートする

usort

(PHP 4, PHP 5, PHP 7, PHP 8)

usort — ユーザー定義の比較関数を使用して、配列を値でソートする

説明

usort(array &$array, callable $callback): true

順序を決めるユーザー定義の比較関数により、 array をその値でソートします。

注意:

比較結果が等しくなる二つの要素があった場合、それらの並び順は保持されます。PHP 8.0.0 より前のバージョンでは、ソートした配列におけるそれらの並び順は不定でした。

注意: この関数は、 array パラメータの要素に対して新しいキーを割り当てます。 その際、単純にキーを並べ替える代わりに、 すでに割り当てられている既存のキーを削除してしまいます。

パラメータ

array

入力の配列。

callback

比較関数は、最初の引数と二番目の引数の比較結果を返します。最初の引数のほうが二番目の引数より大きい場合は正の整数を、二番目の引数と等しい場合はゼロを、そして二番目の引数より小さい場合は負の整数を返す必要があります。

callback(mixed $a, mixed $b): int
警告

float のような 非整数 を比較関数が返すと、その返り値を内部的に int にキャストして使います。 つまり、0.99 や 0.1 といった値は整数値 0 にキャストされ、 値が等しいとみなされます。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、true になりました。これより前のバージョンでは、bool でした。
8.0.0 | callback がリファレンス渡しされる引数を期待している場合、 この関数は E_WARNING を発生させるようになりました。

例

例1 usort() の例

<?php
function cmp($a, $b)
{
if ($a == $b) {
return 0;
}
return ($a < $b) ? -1 : 1;
}

$a = array(3, 2, 5, 6, 1);

usort($a, "cmp");

foreach ($a as $key => $value) {
echo "$key: $value\n";
}
?>

上の例の出力は以下となります。

0: 1
1: 2
2: 3
3: 5
4: 6

内部的な比較をさらにシンプルにするために、 宇宙船演算子を使うこともできます。

<?php
function cmp($a, $b)
{
return $a <=> $b;
}

$a = array(3, 2, 5, 6, 1);

usort($a, "cmp");

foreach ($a as $key => $value) {
echo "$key: $value\n";
}
?>

注意:

もちろん、このような簡単な例では rsort() 関数の方がより適当です。

例2 多次元配列を使用する usort() の例

<?php
function cmp($a, $b)
{
return strcmp($a["fruit"], $b["fruit"]);
}

$fruits[0]["fruit"] = "lemons";
$fruits[1]["fruit"] = "apples";
$fruits[2]["fruit"] = "grapes";

usort($fruits, "cmp");

foreach ($fruits as $key => $value) {
echo "\$fruits[$key]: " . $value["fruit"] . "\n";
}
?>

多次元配列をソートする際には、$a と $b は配列の最初のインデックスへの参照を保持しています。

上の例の出力は以下となります。

$fruits[0]: apples
$fruits[1]: grapes
$fruits[2]: lemons

例3 usort() でオブジェクトのメンバ関数を使用する例

<?php
class TestObj {
private string $name;

function __construct($name)
{
$this->name = $name;
}

/* これは、比較用のstaticメソッドです */
static function cmp_obj($a, $b)
{
return strtolower($a->name) <=> strtolower($b->name);
}
}

$a[] = new TestObj("c");
$a[] = new TestObj("b");
$a[] = new TestObj("d");

usort($a, [TestObj::class, "cmp_obj"]);

foreach ($a as $item) {
echo $item->name . "\n";
}
?>

上の例の出力は以下となります。

b
c
d

例4 usort() で クロージャ を使って多次元配列をソートする例

<?php
$array[0] = array('key_a' => 'z', 'key_b' => 'c');
$array[1] = array('key_a' => 'x', 'key_b' => 'b');
$array[2] = array('key_a' => 'y', 'key_b' => 'a');

function build_sorter($key) {
return function ($a, $b) use ($key) {
return strnatcmp($a[$key], $b[$key]);
};
}

usort($array, build_sorter('key_b'));

foreach ($array as $item) {
echo $item['key_a'] . ', ' . $item['key_b'] . "\n";
}
?>

上の例の出力は以下となります。

y, a
x, b
z, c

例5 usort() と宇宙船演算子

宇宙船演算子は、 複数の軸をまたがった複合的な値を明快に比較する用途に使えます。 以下の例は、$people を last name で比較し、 それが一致するものについては first name で比較します。

<?php
$people[0] = ['first' => 'Adam', 'last' => 'West'];
$people[1] = ['first' => 'Alec', 'last' => 'Baldwin'];
$people[2] = ['first' => 'Adam', 'last' => 'Baldwin'];

function sorter(array $a, array $b) {
return [$a['last'], $a['first']] <=> [$b['last'], $b['first']];
}

usort($people, 'sorter');

foreach ($people as $person) {
print $person['last'] . ', ' . $person['first'] . PHP_EOL;
}
?>

上の例の出力は以下となります。

Baldwin, Adam
Baldwin, Alec
West, Adam

参考

  • uasort() - ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する
  • uksort() - ユーザー定義の比較関数を用いて、キーで配列をソートする
  • 配列ソート関数の比較


クラス/オブジェクトの情報

  • はじめに
  • 例
  • クラス/オブジェクト関数
    • __autoload — 未定義のクラスのロードを試みる
    • class_alias — クラスのエイリアスを作成する
    • class_exists — クラスが定義済みかどうかを確認する
    • enum_exists — 列挙型が定義されているかを調べる
    • get_called_class — "遅延静的束縛" のクラス名
    • get_class — オブジェクトのクラス名を返す
    • get_class_methods — クラスメソッドの名前を取得する
    • get_class_vars — クラスのデフォルトプロパティを取得する
    • get_declared_classes — 定義済のクラスの名前を配列として返す
    • get_declared_interfaces — 宣言されている全てのインターフェイスの配列を返す
    • get_declared_traits — 宣言されているすべてのトレイトの配列を返す
    • get_mangled_object_vars — マングリングされたオブジェクトのプロパティを配列で返す
    • get_object_vars — 指定したオブジェクトのプロパティを取得する
    • get_parent_class — オブジェクトの親クラスの名前を取得する
    • interface_exists — インターフェイスが宣言されているかどうかを確認する
    • is_a — オブジェクトが指定された型のものか、部分型であるかを調べる
    • is_subclass_of — あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる
    • method_exists — クラスメソッドが存在するかどうかを確認する
    • property_exists — オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる
    • trait_exists — トレイトが存在するかどうかを調べる


はじめに

以下の関数により、クラスやインスタンスオブジェクトに関する情報を得ることが可能となります。 オブジェクトが属するクラスの名前、そのメンバープロパティ、メソッドを取得可能です。 この関数を使用することにより、オブジェクトのクラスメンバーだけでなく親クラス (すなわちそのオブジェクトクラスの派生元) の情報を得ることも可能です。

このマニュアルの オブジェクト のページに、クラスやオブジェクトがどのように実装されていて PHP でどのように使うのかについての詳しい説明があります。


例

この例では、まず基底クラスおよびそのクラスの派生クラスを定義します。 基底クラスは食用かどうか、色とかいった、一般的な野菜を記述します。 サブクラス Spinach は、 その野菜の料理法と調理済であるかどうかの情報を追加します。

例1 クラスの定義

Vegetable

<?php

class Vegetable {
public $edible;

public $color;

public function __construct($edible, $color = "green")
{
$this->edible = $edible;
$this->color = $color;
}

public function isEdible()
{
return $this->edible;
}

public function getColor()
{
return $this->color;
}
}

?>

Spinach

<?php

class Spinach extends Vegetable {
public $cooked = false;

public function __construct()
{
parent::__construct(true, "green");
}

public function cook()
{
$this->cooked = true;
}

public function isCooked()
{
return $this->cooked;
}
}

?>

続いて、これらのクラスから二つのオブジェクトのインスタンスを作成し、 親クラスを含む情報を出力します。 また、いくつかのユーティリティ関数を定義します。これらは主に変数 を格好良く表示するためのものです。

例2 test_script.php

<?php

// クラスを読み込むためにオートローダーを登録する
spl_autoload_register();

function printProperties($obj)
{
foreach (get_object_vars($obj) as $prop => $val) {
echo "\t$prop = $val\n";
}
}

function printMethods($obj)
{
$arr = get_class_methods(get_class($obj));
foreach ($arr as $method) {
echo "\tfunction $method()\n";
}
}

function objectBelongsTo($obj, $class)
{
if (is_subclass_of($obj, $class)) {
echo "Object belongs to class " . get_class($obj);
echo ", a subclass of $class\n";
} else {
echo "Object does not belong to a subclass of $class\n";
}
}

// 2つのオブジェクトをインスタンス化する
$veggie = new Vegetable(true, "blue");
$leafy = new Spinach();

// オブジェクトの情報を出力
echo "veggie: CLASS " . get_class($veggie) . "\n";
echo "leafy: CLASS " . get_class($leafy);
echo ", PARENT " . get_parent_class($leafy) . "\n";

// 変数 veggie のプロパティを表示
echo "\nveggie: Properties\n";
printProperties($veggie);

// 変数 leafy のメソッドも表示
echo "\nleafy: Methods\n";
printMethods($leafy);

echo "\nParentage:\n";
objectBelongsTo($leafy, Spinach::class);
objectBelongsTo($leafy, Vegetable::class);

?>

上の例の出力は以下となります。

veggie: CLASS Vegetable
leafy: CLASS Spinach, PARENT Vegetable

veggie: Properties
        edible = 1
        color = blue

leafy: Methods
        function __construct()
        function cook()
        function isCooked()
        function isEdible()
        function getColor()

Parentage:
Object does not belong to a subclass of Spinach
Object belongs to class Spinach, a subclass of Vegetable

注意すべき大事な点ですが、上記の例ではオブジェクト $leafy は Vegetable のサブクラスであるクラス Spinach のインスタンスです。


クラス/オブジェクト関数

目次

  • __autoload — 未定義のクラスのロードを試みる
  • class_alias — クラスのエイリアスを作成する
  • class_exists — クラスが定義済みかどうかを確認する
  • enum_exists — 列挙型が定義されているかを調べる
  • get_called_class — "遅延静的束縛" のクラス名
  • get_class — オブジェクトのクラス名を返す
  • get_class_methods — クラスメソッドの名前を取得する
  • get_class_vars — クラスのデフォルトプロパティを取得する
  • get_declared_classes — 定義済のクラスの名前を配列として返す
  • get_declared_interfaces — 宣言されている全てのインターフェイスの配列を返す
  • get_declared_traits — 宣言されているすべてのトレイトの配列を返す
  • get_mangled_object_vars — マングリングされたオブジェクトのプロパティを配列で返す
  • get_object_vars — 指定したオブジェクトのプロパティを取得する
  • get_parent_class — オブジェクトの親クラスの名前を取得する
  • interface_exists — インターフェイスが宣言されているかどうかを確認する
  • is_a — オブジェクトが指定された型のものか、部分型であるかを調べる
  • is_subclass_of — あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる
  • method_exists — クラスメソッドが存在するかどうかを確認する
  • property_exists — オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる
  • trait_exists — トレイトが存在するかどうかを調べる


未定義のクラスのロードを試みる

  • ≪ クラス/オブジェクト関数
  • class_alias ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • 未定義のクラスのロードを試みる

__autoload

(PHP 5, PHP 7)

__autoload — 未定義のクラスのロードを試みる

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

__autoload(string $class): void

この関数を定義すれば、クラスのオートローディング を有効にできます。

パラメータ

class

ロードするクラスの名前。

戻り値

値を返しません。

参考

  • spl_autoload_register() - 指定した関数を __autoload() の実装として登録する


クラスのエイリアスを作成する

  • ≪ __autoload
  • class_exists ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • クラスのエイリアスを作成する

class_alias

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

class_alias — クラスのエイリアスを作成する

説明

class_alias(string $class, string $alias, bool $autoload = true): bool

alias という名前のエイリアスを、 ユーザー定義のクラス class に対して作成します。 エイリアスは、元のクラスとまったく同一のものとなります。

注意: PHP 8.3.0 以降では、class_alias() は PHP の内部クラスのエイリアスを作る機能もサポートしています。

パラメータ

class

元となるクラス。

alias

クラスのエイリアス名。

autoload

元のクラスが見つからない場合に オートロード するかどうか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.3.0 | class_alias() は、内部クラスのエイリアスを作る機能をサポートしました。

例

例1 class_alias() の例

<?php

class Foo { }

class_alias('Foo', 'Bar');

$a = new Foo;
$b = new Bar;

// オブジェクトは同一となります
var_dump($a == $b, $a === $b);
var_dump($a instanceof $b);

// クラスは同一となります
var_dump($a instanceof Foo);
var_dump($a instanceof Bar);

var_dump($b instanceof Foo);
var_dump($b instanceof Bar);

?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)

注意

注意:

クラス名は、大文字小文字を区別しません。 また、その振る舞いはこの関数にも反映されています。 class_alias() によって作られたエイリアスは、 小文字で宣言されます。 たとえばクラス MyClass について、 class_alias('MyClass', 'MyClassAlias') を実行すると、myclassalias という名前の新しいクラスエイリアスが宣言されます。

参考

  • get_parent_class() - オブジェクトの親クラスの名前を取得する
  • is_subclass_of() - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる


クラスが定義済みかどうかを確認する

  • ≪ class_alias
  • enum_exists ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • クラスが定義済みかどうかを確認する

class_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

class_exists — クラスが定義済みかどうかを確認する

説明

class_exists(string $class, bool $autoload = true): bool

この関数は指定したクラスが定義されているかどうかを調べます。

パラメータ

class

クラス名。大文字小文字は区別しません。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

クラス class が定義されている場合に true、 それ以外の場合に false を返します。

例

例1 class_exists() の例

<?php
// クラスを使用する前に、それが存在するかどうかを調べます
if (class_exists('MyClass')) {
$myclass = new MyClass();
}

?>

例2 autoload パラメータの例

<?php
spl_autoload_register(function ($class_name) {
include $class_name . '.php';

// クラス宣言を含むかどうか確認する
if (!class_exists($class_name, false)) {
throw new LogicException("Unable to load class: $class_name");
}
});

if (class_exists(MyClass::class)) {
$myclass = new MyClass();
}

?>

参考

  • function_exists() - 指定した関数が定義されている場合に true を返す
  • enum_exists() - 列挙型が定義されているかを調べる
  • interface_exists() - インターフェイスが宣言されているかどうかを確認する
  • get_declared_classes() - 定義済のクラスの名前を配列として返す


列挙型が定義されているかを調べる

  • ≪ class_exists
  • get_called_class ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • 列挙型が定義されているかを調べる

enum_exists

(PHP 8 >= 8.1.0)

enum_exists — 列挙型が定義されているかを調べる

説明

enum_exists(string $enum, bool $autoload = true): bool

この関数は、指定された 列挙型 が定義されているかを調べます。

パラメータ

enum

列挙型の名前。この名前は、大文字小文字を区別せずに比較されます。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

enum が定義済みの列挙型である場合、 true を返します。そうでない場合、false を返します。

例

例1 enum_exists() の例

<?php
// Check that the enum exists before trying to use it
if (enum_exists(Suit::class)) {
$myclass = Suit::Hearts;
}
?>

参考

  • function_exists() - 指定した関数が定義されている場合に true を返す
  • class_exists() - クラスが定義済みかどうかを確認する
  • interface_exists() - インターフェイスが宣言されているかどうかを確認する
  • get_declared_classes() - 定義済のクラスの名前を配列として返す


"遅延静的束縛" のクラス名

  • ≪ enum_exists
  • get_class ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • "遅延静的束縛" のクラス名

get_called_class

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

get_called_class — "遅延静的束縛" のクラス名

説明

get_called_class(): string

staticメソッドのコール元のクラス名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス名を返します。

エラー / 例外

get_called_class() がクラスの外部からコールされた場合、 Error がスローされます。PHP 8.0.0 より前のバージョンでは、 E_WARNING が発生していました。

変更履歴

バージョン | 説明
8.0.0 | この関数をクラスの外部からコールした場合に、 Error がスローされるようになりました。 これより前のバージョンでは、E_WARNING が発生し、false を返していました。

例

例1 get_called_class() の使用法

<?php

class foo {
static public function test() {
var_dump(get_called_class());
}
}

class bar extends foo {
}

foo::test();
bar::test();

?>

上の例の出力は以下となります。

string(3) "foo"
string(3) "bar"

参考

  • get_parent_class() - オブジェクトの親クラスの名前を取得する
  • get_class() - オブジェクトのクラス名を返す
  • is_subclass_of() - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる


オブジェクトのクラス名を返す

  • ≪ get_called_class
  • get_class_methods ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • オブジェクトのクラス名を返す

get_class

(PHP 4, PHP 5, PHP 7, PHP 8)

get_class — オブジェクトのクラス名を返す

説明

get_class(object $object = ?): string

指定した object のクラス名を取得します。

パラメータ

object

調べるオブジェクト。

注意: object に明示的に null を渡すことは、 PHP 7.2.0 以降許されなくなり、E_WARNING レベルの警告が発生します。 PHP 8.0.0 以降では、null を渡すと TypeError がスローされます。

戻り値

オブジェクト object がインスタンス であるクラスの名前を返します。

object が 名前空間の中に存在しているクラスのインスタンスだった場合、 名前空間で修飾されたクラス名が返されます。

エラー / 例外

オブジェクト以外に対して get_class() をコールすると、 TypeError がスローされます。 PHP 8.0.0 より前のバージョンでは、 E_WARNING レベルの警告が発生していました。

get_class() が、クラスの外部から引数なしで呼ばれた場合、 Error が発生します。PHP 8.0.0 より前のバージョンでは、 E_WARNING レベルの警告が発生していました。

変更履歴

バージョン | 説明
8.3.0 | get_class() を引数なしでコールすると、 E_DEPRECATED が発生するようになりました。 これより前のバージョンでは、クラスの内部でこの関数をコールすると、 そのクラスの名前を返していました。
8.0.0 | この関数をクラスの外部から引数なしで呼び出すと、 Error が発生するようになりました。 これより前のバージョンでは、 E_WARNING レベルの警告が発生し、 false を返していました。
7.2.0 | null は、object のデフォルトのパラメータとして 扱われなくなり、 正しい入力ではなくなりました。 これより前のバージョンでは、object のデフォルトのパラメータは null であり、何も値を渡さないのと同じ意味でした。

例

例1 get_class() の使用例

<?php

class foo {
function name()
{
echo "My name is " , get_class($this) , "\n";
}
}

// オブジェクトを生成
$bar = new foo();

// 外部からコール
echo "Its name is " , get_class($bar) , "\n";

// 内部からコール
$bar->name();

?>

上の例の出力は以下となります。

Its name is foo
My name is foo

例2 get_class() のスーパークラスでの使用例

<?php

abstract class bar {
public function __construct()
{
var_dump(get_class($this));
var_dump(get_class());
}
}

class foo extends bar {
}

new foo;

?>

上の例の出力は以下となります。

string(3) "foo"
string(3) "bar"

例3 名前空間の中にあるクラスを get_class() で使う

<?php

namespace Foo\Bar;

class Baz {
public function __construct()
{

}
}

$baz = new \Foo\Bar\Baz;

var_dump(get_class($baz));
?>

上の例の出力は以下となります。

string(11) "Foo\Bar\Baz"

参考

  • get_called_class() - "遅延静的束縛" のクラス名
  • get_parent_class() - オブジェクトの親クラスの名前を取得する
  • gettype() - 変数の型を取得する
  • get_debug_type() - 変数の型名をデバッグしやすい形で取得する
  • is_subclass_of() - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる


クラスメソッドの名前を取得する

  • ≪ get_class
  • get_class_vars ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • クラスメソッドの名前を取得する

get_class_methods

(PHP 4, PHP 5, PHP 7, PHP 8)

get_class_methods — クラスメソッドの名前を取得する

説明

get_class_methods(object|string $object_or_class): array

クラスメソッドの名前を取得します。

パラメータ

object_or_class

オブジェクトのインスタンスのクラス名。

戻り値

この関数は、指定したクラス object_or_class についてメソッドの名前を配列として返します。 エラー時には null を返します。

変更履歴

バージョン | 説明
8.0.0 | object_or_class は、 オブジェクトまたは有効なクラス名を受け入れるようになりました。

例

例1 get_class_methods() の例

<?php

class myclass {
// コンストラクタ
function __construct()
{
return(true);
}

// メソッド1
function myfunc1()
{
return(true);
}

// メソッド2
function myfunc2()
{
return(true);
}
}

$class_methods = get_class_methods('myclass');
// あるいは
$class_methods = get_class_methods(new myclass());

foreach ($class_methods as $method_name) {
echo "$method_name\n";
}

?>

上の例の出力は以下となります。

__construct
myfunc1
myfunc2

参考

  • get_class() - オブジェクトのクラス名を返す
  • get_class_vars() - クラスのデフォルトプロパティを取得する
  • get_object_vars() - 指定したオブジェクトのプロパティを取得する


クラスのデフォルトプロパティを取得する

  • ≪ get_class_methods
  • get_declared_classes ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • クラスのデフォルトプロパティを取得する

get_class_vars

(PHP 4, PHP 5, PHP 7, PHP 8)

get_class_vars — クラスのデフォルトプロパティを取得する

説明

get_class_vars(string $class): array

指定したクラスのデフォルトプロパティを取得します。

パラメータ

class

クラス名。

戻り値

宣言されているプロパティのうち、現在のスコープから見えるものとそのデフォルト値を連想配列で返します。 返される配列要素は、変数名 => 値 の形式となります。 エラーが発生した場合は false を返します。

例

例1 get_class_vars() の例

<?php

class myclass {

var $var1; // この変数にはデフォルト値がありません...
var $var2 = "xyz";
var $var3 = 100;
private $var4;

// コンストラクタ
function __construct() {
// いくつかのプロパティを変更する
$this->var1 = "foo";
$this->var2 = "bar";
return true;
}

}

$my_class = new myclass();

$class_vars = get_class_vars(get_class($my_class));

foreach ($class_vars as $name => $value) {
echo "$name : $value\n";
}

?>

上の例の出力は以下となります。

var1 :
var2 : xyz
var3 : 100

例2 get_class_vars() でのスコープの挙動

<?php
function format($array)
{
return implode('|', array_keys($array)) . "\r\n";
}

class TestCase
{
public $a = 1;
protected $b = 2;
private $c = 3;

public static function expose()
{
echo format(get_class_vars(__CLASS__));
}
}

TestCase::expose();
echo format(get_class_vars('TestCase'));
?>

上の例の出力は以下となります。

// 5.0.0
a| * b| TestCase c
a| * b| TestCase c

// 5.0.1 - 5.0.2
a|b|c
a|b|c

// 5.0.3 +
a|b|c
a

参考

  • get_class_methods() - クラスメソッドの名前を取得する
  • get_object_vars() - 指定したオブジェクトのプロパティを取得する


定義済のクラスの名前を配列として返す

  • ≪ get_class_vars
  • get_declared_interfaces ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • 定義済のクラスの名前を配列として返す

get_declared_classes

(PHP 4, PHP 5, PHP 7, PHP 8)

get_declared_classes — 定義済のクラスの名前を配列として返す

説明

get_declared_classes(): array

定義済のクラスの名前を配列として返します。

パラメータ

この関数にはパラメータはありません。

戻り値

この関数は、現在のスクリプトで宣言されたクラスの名前の配列を返します。

注意:

PHP にコンパイル時に組み込んだり読み込んだりしている拡張モジュールの種類に依存して、 他のクラスも存在する可能性があることに注意しましょう。 これは、自作のクラスをそれらと同じ名前で作成できないことを意味します。 定義済みのクラスについては付録の定義済みクラスのセクションを 参照ください。

変更履歴

バージョン | 説明
7.4.0 | 以前のバージョンでは、get_declared_classes() 関数は 子クラスの前に親クラスを常に返していました。 このバージョンからは、そうした動きはなくなりました。 この関数の戻り値について、特定の順序は保証されません。

例

例1 get_declared_classes() の例

<?php
print_r(get_declared_classes());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => stdClass
    [1] => __PHP_Incomplete_Class
    [2] => Directory
)

参考

  • class_exists() - クラスが定義済みかどうかを確認する
  • get_declared_interfaces() - 宣言されている全てのインターフェイスの配列を返す
  • get_defined_functions() - 定義済みの全ての関数を配列で返す


宣言されている全てのインターフェイスの配列を返す

  • ≪ get_declared_classes
  • get_declared_traits ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • 宣言されている全てのインターフェイスの配列を返す

get_declared_interfaces

(PHP 5, PHP 7, PHP 8)

get_declared_interfaces — 宣言されている全てのインターフェイスの配列を返す

説明

get_declared_interfaces(): array

宣言されているインターフェイスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のスクリプトで宣言されているインターフェイス名の配列を返します。

例

例1 get_declared_interfaces() の例

<?php
print_r(get_declared_interfaces());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Traversable
    [1] => IteratorAggregate
    [2] => Iterator
    [3] => ArrayAccess
    [4] => reflector
    [5] => RecursiveIterator
    [6] => SeekableIterator
)

参考

  • interface_exists() - インターフェイスが宣言されているかどうかを確認する
  • get_declared_classes() - 定義済のクラスの名前を配列として返す
  • class_implements() - 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す


宣言されているすべてのトレイトの配列を返す

  • ≪ get_declared_interfaces
  • get_mangled_object_vars ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • 宣言されているすべてのトレイトの配列を返す

get_declared_traits

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

get_declared_traits — 宣言されているすべてのトレイトの配列を返す

説明

get_declared_traits(): array

パラメータ

この関数にはパラメータはありません。

戻り値

宣言されているすべてのトレイトの名前を値に持つ配列を返します。

参考

  • class_uses() - 指定したクラスが使っているトレイトを返す
  • trait_exists() - トレイトが存在するかどうかを調べる


マングリングされたオブジェクトのプロパティを配列で返す

  • ≪ get_declared_traits
  • get_object_vars ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • マングリングされたオブジェクトのプロパティを配列で返す

get_mangled_object_vars

(PHP 7 >= 7.4.0, PHP 8)

get_mangled_object_vars — マングリングされたオブジェクトのプロパティを配列で返す

説明

get_mangled_object_vars(object $object): array

object のプロパティを要素とする配列を返します。 配列のキーはメンバ変数の名前ですが、 注意すべき例外がいくつかあります。 private な変数については、キーの前にクラス名が付きます。 そして、protected な変数については、 キーの前に * が付きます。 これらの付加される値は、両側に NUL バイトが付いています。 未初期化の 型付きプロパティ は黙って捨てられます。

パラメータ

object

オブジェクトのインスタンス。

戻り値

アクセス権に関わらず、 object の全てのプロパティを含む配列を返します。

例

例1 get_mangled_object_vars() の例

<?php

class A
{
public $public = 1;

protected $protected = 2;

private $private = 3;
}

class B extends A
{
private $private = 4;
}

$object = new B;
$object->dynamic = 5;
$object->{'6'} = 6;

var_dump(get_mangled_object_vars($object));

class AO extends ArrayObject
{
private $private = 1;
}

$arrayObject = new AO(['x' => 'y']);
$arrayObject->dynamic = 2;

var_dump(get_mangled_object_vars($arrayObject));

上の例の出力は以下となります。

array(6) {
  ["Bprivate"]=>
  int(4)
  ["public"]=>
  int(1)
  ["*protected"]=>
  int(2)
  ["Aprivate"]=>
  int(3)
  ["dynamic"]=>
  int(5)
  [6]=>
  int(6)
}
array(2) {
  ["AOprivate"]=>
  int(1)
  ["dynamic"]=>
  int(2)
}

参考

  • get_class_vars() - クラスのデフォルトプロパティを取得する
  • get_object_vars() - 指定したオブジェクトのプロパティを取得する


指定したオブジェクトのプロパティを取得する

  • ≪ get_mangled_object_vars
  • get_parent_class ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • 指定したオブジェクトのプロパティを取得する

get_object_vars

(PHP 4, PHP 5, PHP 7, PHP 8)

get_object_vars — 指定したオブジェクトのプロパティを取得する

説明

get_object_vars(object $object): array

指定した object について、 そのスコープ内でアクセス可能な非 static プロパティを取得します。

パラメータ

object

オブジェクトのインスタンス。

戻り値

指定したオブジェクト object について、 そのスコープ内でアクセス可能な非 static プロパティを連想配列として返します。

例

例1 get_object_vars() の使用例

<?php

class foo {
private $a;
public $b = 1;
public $c;
private $d;
static $e;

public function test() {
var_dump(get_object_vars($this));
}
}

$test = new foo;
var_dump(get_object_vars($test));

$test->test();

?>

上の例の出力は以下となります。

array(2) {
  ["b"]=>
  int(1)
  ["c"]=>
  NULL
}
array(4) {
  ["a"]=>
  NULL
  ["b"]=>
  int(1)
  ["c"]=>
  NULL
  ["d"]=>
  NULL
}

注意:

初期化されていないプロパティは、アクセス不能とみなされるため、 結果の配列には含まれません。

参考

  • get_class_methods() - クラスメソッドの名前を取得する
  • get_class_vars() - クラスのデフォルトプロパティを取得する


オブジェクトの親クラスの名前を取得する

  • ≪ get_object_vars
  • interface_exists ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • オブジェクトの親クラスの名前を取得する

get_parent_class

(PHP 4, PHP 5, PHP 7, PHP 8)

get_parent_class — オブジェクトの親クラスの名前を取得する

説明

get_parent_class(object|string $object_or_class = ?): string|false

オブジェクトあるいはクラスの親クラスの名前を取得します。

パラメータ

object_or_class

調べたいオブジェクトあるいはクラスの名前。

戻り値

object_or_class がインスタンスあるいは名前であるクラスの親クラス名を返します。

注意:

オブジェクトが親を持たない場合や、 指定したクラスが存在しない場合は false を返します。

変更履歴

バージョン | 説明
8.3.0 | get_parent_class() を引数なしでコールすると、 E_DEPRECATED が発生するようになりました。 これより前のバージョンでは、クラスの内部でこの関数をコールすると、 そのクラスの名前を返していました。
8.0.0 | object_or_class は、 オブジェクトまたは有効なクラス名を受け入れるようになりました。

例

例1 get_parent_class() の使用例

<?php

class Dad {
function __construct()
{
// ロジックを実装する
}
}

class Child extends Dad {
function __construct()
{
echo "I'm " , get_parent_class($this) , "'s son\n";
}
}

class Child2 extends Dad {
function __construct()
{
echo "I'm " , get_parent_class('child2') , "'s son too\n";
}
}

$foo = new child();
$bar = new child2();

?>

上の例の出力は以下となります。

I'm Dad's son
I'm Dad's son too

参考

  • get_class() - オブジェクトのクラス名を返す
  • is_subclass_of() - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる
  • class_parents() - 与えられたクラスの親クラスを返す


インターフェイスが宣言されているかどうかを確認する

  • ≪ get_parent_class
  • is_a ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • インターフェイスが宣言されているかどうかを確認する

interface_exists

(PHP 5 >= 5.0.2, PHP 7, PHP 8)

interface_exists — インターフェイスが宣言されているかどうかを確認する

説明

interface_exists(string $interface, bool $autoload = true): bool

指定したインターフェイスが定義されているかどうかを調べます。

パラメータ

interface

インターフェイス名。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

interface で与えられたインターフェイスが宣言されていれば true を返します。 そうでなければ false を返します。

例

例1 interface_exists() の例

<?php
// 使用する前にインターフェイスが存在するかどうかを確認する
if (interface_exists('MyInterface')) {
class MyClass implements MyInterface
{
// メソッド
}
}

?>

参考

  • get_declared_interfaces() - 宣言されている全てのインターフェイスの配列を返す
  • class_implements() - 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
  • class_exists() - クラスが定義済みかどうかを確認する
  • enum_exists() - 列挙型が定義されているかを調べる


オブジェクトが指定された型のものか、部分型であるかを調べる

  • ≪ interface_exists
  • is_subclass_of ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • オブジェクトが指定された型のものか、部分型であるかを調べる

is_a

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_a — オブジェクトが指定された型のものか、部分型であるかを調べる

説明

is_a(mixed $object_or_class, string $class, bool $allow_string = false): bool

指定した object_or_class が class オブジェクトの型であるか、 あるいは class が、 その上位型のひとつであるかを調べます。

パラメータ

object_or_class

調べたいクラス名、またはオブジェクトのインスタンス

class

クラスまたはインターフェイスの名前。

allow_string

このパラメータを false にすると、 クラス名を表す文字列を object_or_class に指定できなくなります。 そして、クラスが存在しない場合のオートローダーの呼び出しもしなくなります。

戻り値

object_or_class が class オブジェクトの型であるか、 あるいは class が、その上位型のひとつである場合に true、それ以外の場合に false を返します。

例

例1 is_a() の例

<?php
// クラス定義
class WidgetFactory
{
var $oink = 'moo';
}

// オブジェクトを作成します
$WF = new WidgetFactory();

if (is_a($WF, 'WidgetFactory')) {
echo "はい、\$WF は WidgetFactory です\n";
}
?>

例2 instanceof 演算子の使用

<?php
if ($WF instanceof WidgetFactory) {
echo 'はい、$WF は WidgetFactory です';
}
?>

参考

  • get_class() - オブジェクトのクラス名を返す
  • get_parent_class() - オブジェクトの親クラスの名前を取得する
  • is_subclass_of() - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる


あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる

  • ≪ is_a
  • method_exists ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる

is_subclass_of

(PHP 4, PHP 5, PHP 7, PHP 8)

is_subclass_of — あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる

説明

is_subclass_of(mixed $object_or_class, string $class, bool $allow_string = true): bool

指定した object_or_class が、その親のひとつに class を持つか (あるいは class を実装しているか) どうかを調べます。

パラメータ

object_or_class

クラス名あるいはオブジェクトのインスタンス。 そのクラスが存在しなくても、エラーにはなりません。

class

クラス名。

allow_string

このパラメータを false にすると、 クラス名を表す文字列を object_or_class に指定できなくなります。 そして、クラスが存在しない場合のオートローダーの呼び出しもしなくなります。

戻り値

この関数は、オブジェクト object_or_class が class のサブクラスであるクラスに属する場合に true、その他の場合に false を返します。

例

例1 is_subclass_of() の例

<?php
// クラスを定義する
class WidgetFactory
{
var $oink = 'moo';
}

// 子クラスを定義する
class WidgetFactory_Child extends WidgetFactory
{
var $oink = 'oink';
}

// 新規オブジェクトを生成する
$WF = new WidgetFactory();
$WFC = new WidgetFactory_Child();

if (is_subclass_of($WFC, 'WidgetFactory')) {
echo "yes, \$WFC is a subclass of WidgetFactory\n";
} else {
echo "no, \$WFC is not a subclass of WidgetFactory\n";
}

if (is_subclass_of($WF, 'WidgetFactory')) {
echo "yes, \$WF is a subclass of WidgetFactory\n";
} else {
echo "no, \$WF is not a subclass of WidgetFactory\n";
}

if (is_subclass_of('WidgetFactory_Child', 'WidgetFactory')) {
echo "yes, WidgetFactory_Child is a subclass of WidgetFactory\n";
} else {
echo "no, WidgetFactory_Child is not a subclass of WidgetFactory\n";
}
?>

上の例の出力は以下となります。

yes, $WFC is a subclass of WidgetFactory
no, $WF is not a subclass of WidgetFactory
yes, WidgetFactory_Child is a subclass of WidgetFactory

例2 is_subclass_of() でインターフェイスを使う例

<?php
// インターフェイスの定義
interface MyInterface
{
public function MyFunction();
}

// インターフェイスの実装クラスの定義
class MyClass implements MyInterface
{
public function MyFunction()
{
return "MyClass Implements MyInterface!";
}
}

// オブジェクトのインスタンスを作ります
$my_object = new MyClass;

// 次の例は 5.3.7 以降で動作します

// クラスのインスタンスを調べます
if (is_subclass_of($my_object, 'MyInterface')) {
echo "Yes, \$my_object is a subclass of MyInterface\n";
} else {
echo "No, \$my_object is not a subclass of MyInterface\n";
}

// クラス名を表す文字列を調べます
if (is_subclass_of('MyClass', 'MyInterface')) {
echo "Yes, MyClass is a subclass of MyInterface\n";
} else {
echo "No, MyClass is not a subclass of MyInterface\n";
}
?>

上の例の出力は以下となります。

Yes, $my_object is a subclass of MyInterface
Yes, MyClass is a subclass of MyInterface

注意

注意:

この関数を使うと、未知のクラスに対しては登録済みの autoloader を使用します。

参考

  • get_class() - オブジェクトのクラス名を返す
  • get_parent_class() - オブジェクトの親クラスの名前を取得する
  • is_a() - オブジェクトが指定された型のものか、部分型であるかを調べる
  • class_parents() - 与えられたクラスの親クラスを返す


クラスメソッドが存在するかどうかを確認する

  • ≪ is_subclass_of
  • property_exists ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • クラスメソッドが存在するかどうかを確認する

method_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

method_exists — クラスメソッドが存在するかどうかを確認する

説明

method_exists(object|string $object_or_class, string $method): bool

指定した object_or_class にクラスメソッドが存在するかどうかを調べます。

パラメータ

object_or_class

オブジェクトのインスタンス、あるいはクラス名。

method

メソッドの名前。

戻り値

method で指定したメソッドが 指定した object_or_class において定義されている場合に true、そうでない場合に false を返します。

例

例1 method_exists() の例

<?php
$directory = new Directory('.');
var_dump(method_exists($directory,'read'));
?>

上の例の出力は以下となります。

bool(true)

例2 staticメソッドに対する method_exists() の例

<?php
var_dump(method_exists('Directory','read'));
?>

上の例の出力は以下となります。

bool(true)

注意

注意:

この関数を使うと、未知のクラスに対しては登録済みの autoloader を使用します。

参考

  • function_exists() - 指定した関数が定義されている場合に true を返す
  • is_callable() - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
  • class_exists() - クラスが定義済みかどうかを確認する


オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる

  • ≪ method_exists
  • trait_exists ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる

property_exists

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

property_exists — オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる

説明

property_exists(object|string $object_or_class, string $property): bool

この関数は、与えられたプロパティ property が 指定されたクラスに存在するかどうかを確認します。

注意:

isset() とは対照的に、 プロパティの値が null の場合でも property_exists() は true を返します。

パラメータ

object_or_class

確認するクラス名、もしくはクラスのオブジェクトを指定します。

property

プロパティ名を指定します。

戻り値

プロパティが存在している場合は true、存在していない場合に false を返します。

例

例1 property_exists() の例

<?php

class myClass {
public $mine;
private $xpto;
static protected $test;

static function test() {
var_dump(property_exists('myClass', 'xpto')); //true
}
}

var_dump(property_exists('myClass', 'mine')); //true
var_dump(property_exists(new myClass, 'mine')); //true
var_dump(property_exists('myClass', 'xpto')); //true
var_dump(property_exists('myClass', 'bar')); //false
var_dump(property_exists('myClass', 'test')); //true
myClass::test();

?>

注意

注意:

この関数を使うと、未知のクラスに対しては登録済みの autoloader を使用します。

注意:

property_exists() 関数は、マジックメソッド __get を使ってアクセスするプロパティを検出することはできません。

参考

  • method_exists() - クラスメソッドが存在するかどうかを確認する


トレイトが存在するかどうかを調べる

  • ≪ property_exists
  • Ctype ≫
  • PHP Manual
  • クラス/オブジェクト関数
  • トレイトが存在するかどうかを調べる

trait_exists

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

trait_exists — トレイトが存在するかどうかを調べる

説明

trait_exists(string $trait, bool $autoload = true): bool

パラメータ

trait

調べたいトレイトの名前。

autoload

まだロードされていない場合に オートロード するかどうか。

戻り値

トレイトが存在する場合に true、存在しない場合に false を返します。


文字タイプチェック

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • Ctype 関数
    • ctype_alnum — 英数字かどうかを調べる
    • ctype_alpha — 英字かどうかを調べる
    • ctype_cntrl — 制御文字かどうかを調べる
    • ctype_digit — 数字かどうかを調べる
    • ctype_graph — 空白以外の印字可能な文字かどうかを調べる
    • ctype_lower — 小文字かどうかを調べる
    • ctype_print — 印字可能な文字かどうかを調べる
    • ctype_punct — 空白、英数字以外の出力可能な文字かどうかを調べる
    • ctype_space — 空白文字かどうか調べる
    • ctype_upper — 大文字かどうか調べる
    • ctype_xdigit — 16 進数を表す文字かどうかを調べる


はじめに

以下の関数は、現在のロケール(setlocale()も参照) に基づき文字または文字列がある文字クラスに含まれるかどうかを調べます。

整数の引数を指定してコールした場合、これらの関数は、ctype.h に記述された C の同名の関数と全く同様に動作します。 これは、256 より小さな整数が指定された場合、 指定した範囲 (数値は 0x30-0x39) に収まっているかどうかを 調べるために、そのアスキー値を使用することを意味します。 数値が -128 および -1 (境界を含む) の間の場合、256 が追加され、 その数字に関してチェックが行われます。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

文字列引数を指定してコールした場合、これらの関数は、その文字列の全 ての文字を調べ、その文字列の全ての文字が要求された基準に一致する場 合にのみ true を返します。空文字列を渡して呼び出した場合、結果は常に false になります。

文字列または整数以外のものを指定した場合は、直ちに false が 返されます。

ctype 関数は、正規表現よりもつねに好ましく、さらに "str_*" および "is_*" のような いくつかの等価な関数よりも好ましいことに注意してください。 これは、ctype 関数がネイティブな C ライブラリを使用しており、処理が著しく 高速であるためです。

注意:

これらの関数は、Python の "ctypes" ライブラリとはまったく無関係です。 この拡張モジュールの名前は C のヘッダファイル ctype.h からとったもので、このヘッダファイルには C 言語における同等の機能が定義されています。

また、この拡張モジュールのほうが Python の "ctypes" より先に登場しているわけで、 こんなややこしいことになってしまったのも、決して PHP のせいではないわけで...。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Ctype
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

常に利用可能な標準 C ライブラリ関数以外は不要です。


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-ctype

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


Ctype 関数

目次

  • ctype_alnum — 英数字かどうかを調べる
  • ctype_alpha — 英字かどうかを調べる
  • ctype_cntrl — 制御文字かどうかを調べる
  • ctype_digit — 数字かどうかを調べる
  • ctype_graph — 空白以外の印字可能な文字かどうかを調べる
  • ctype_lower — 小文字かどうかを調べる
  • ctype_print — 印字可能な文字かどうかを調べる
  • ctype_punct — 空白、英数字以外の出力可能な文字かどうかを調べる
  • ctype_space — 空白文字かどうか調べる
  • ctype_upper — 大文字かどうか調べる
  • ctype_xdigit — 16 進数を表す文字かどうかを調べる


英数字かどうかを調べる

  • ≪ Ctype 関数
  • ctype_alpha ≫
  • PHP Manual
  • Ctype 関数
  • 英数字かどうかを調べる

ctype_alnum

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_alnum — 英数字かどうかを調べる

説明

ctype_alnum(mixed $text): bool

与えられた文字列 text のすべての文字が英字または 数字であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が英字または数字だった場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 A ctype_alnum() の例 (デフォルトのロケールを使用)

<?php
$strings = array('AbCd1zyZ9', 'foo!#$bar');
foreach ($strings as $testcase) {
if (ctype_alnum($testcase)) {
echo "The string $testcase consists of all letters or digits.\n";
} else {
echo "The string $testcase does not consist of all letters or digits.\n";
}
}
?>

上の例の出力は以下となります。

The string AbCd1zyZ9 consists of all letters or digits.
The string foo!#$bar does not consist of all letters or digits.

参考

  • ctype_alpha() - 英字かどうかを調べる
  • ctype_digit() - 数字かどうかを調べる
  • setlocale() - ロケール情報を設定する
  • IntlChar::isalnum() - コードポイントが英数字であるかを調べる


英字かどうかを調べる

  • ≪ ctype_alnum
  • ctype_cntrl ≫
  • PHP Manual
  • Ctype 関数
  • 英字かどうかを調べる

ctype_alpha

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_alpha — 英字かどうかを調べる

説明

ctype_alpha(mixed $text): bool

与えられた文字列 text のすべての文字が 英字であるかどうかを調べます。 標準の C ロケールの場合、文字は [A-Za-z] で、ctype_alpha() は $text が一文字のみの場合の (ctype_upper($text) || ctype_lower($text)) と等価です。 しかし、他の言語には大文字でも小文字でもない文字が含まれています。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が英字だった場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_alpha()の例 (デフォルトのロケールを使用)

<?php
$strings = array('KjgWZC', 'arf12');
foreach ($strings as $testcase) {
if (ctype_alpha($testcase)) {
echo "文字列 $testcase は全て文字からなります。\n";
} else {
echo "文字列 $testcase は全てが文字から構成されているわけではありません。\n";
}
}
?>

上の例の出力は以下となります。

文字列 KjqWZC は全て文字からなります。
文字列 arf12 は全てが文字から構成されているわけではありません。

参考

  • ctype_upper() - 大文字かどうか調べる
  • ctype_lower() - 小文字かどうかを調べる
  • setlocale() - ロケール情報を設定する
  • IntlChar::isalpha() - コードポイントがアルファベットかを調べる


制御文字かどうかを調べる

  • ≪ ctype_alpha
  • ctype_digit ≫
  • PHP Manual
  • Ctype 関数
  • 制御文字かどうかを調べる

ctype_cntrl

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_cntrl — 制御文字かどうかを調べる

説明

ctype_cntrl(mixed $text): bool

与えられた文字列 text のすべての文字が制御文字であるかどうかを調べます。 制御文字とは、例えばラインフィードやタブ、エスケープなどです。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が現在のロケールの制御文字だった場合に true、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_cntrl() の例

<?php
$strings = array('string1' => "\n\r\t", 'string2' => 'arf12');
foreach ($strings as $name => $testcase) {
if (ctype_cntrl($testcase)) {
echo "The string '$name' consists of all control characters.\n";
} else {
echo "The string '$name' does not consist of all control characters.\n";
}
}
?>

上の例の出力は以下となります。

The string 'string1' consists of all control characters.
The string 'string2' does not consist of all control characters.

参考

  • ctype_print() - 印字可能な文字かどうかを調べる
  • IntlChar::iscntrl() - コードポイントが制御文字かどうかを調べる


数字かどうかを調べる

  • ≪ ctype_cntrl
  • ctype_graph ≫
  • PHP Manual
  • Ctype 関数
  • 数字かどうかを調べる

ctype_digit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_digit — 数字かどうかを調べる

説明

ctype_digit(mixed $text): bool

与えられた文字列 text のすべての文字が 数字であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

string text のすべての文字が 10 進数字だった場合に true、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_digit() の例

<?php
$strings = array('1820.20', '10002', 'wsl!12');
foreach ($strings as $testcase) {
if (ctype_digit($testcase)) {
echo "The string $testcase consists of all digits.\n";
} else {
echo "The string $testcase does not consist of all digits.\n";
}
}
?>

上の例の出力は以下となります。

The string 1820.20 does not consist of all digits.
The string 10002 consists of all digits.
The string wsl!12 does not consist of all digits.

例2 ctype_digit() で文字列と整数値を比較する例

<?php

$numeric_string = '42';
$integer = 42;

ctype_digit($numeric_string); // true
ctype_digit($integer); // false (ASCII 42 は * です)

is_numeric($numeric_string); // true
is_numeric($integer); // true
?>

参考

  • ctype_alnum() - 英数字かどうかを調べる
  • ctype_xdigit() - 16 進数を表す文字かどうかを調べる
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_string() - 変数の型が文字列かどうかを調べる
  • IntlChar::isdigit() - コードポイントが、数字であるかを調べる


空白以外の印字可能な文字かどうかを調べる

  • ≪ ctype_digit
  • ctype_lower ≫
  • PHP Manual
  • Ctype 関数
  • 空白以外の印字可能な文字かどうかを調べる

ctype_graph

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_graph — 空白以外の印字可能な文字かどうかを調べる

説明

ctype_graph(mixed $text): bool

与えられた文字列 text のすべての文字が 実際に目に見える出力を行うかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が印字可能で実際に目に見える 出力を行う（空白でない）場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_graph() の例

<?php
$strings = array('string1' => "asdf\n\r\t", 'string2' => 'arf12', 'string3' => 'LKA#@%.54');
foreach ($strings as $name => $testcase) {
if (ctype_graph($testcase)) {
echo "The string '$name' consists of all (visibly) printable characters.\n";
} else {
echo "The string '$name' does not consist of all (visibly) printable characters.\n";
}
}
?>

上の例の出力は以下となります。

The string 'string1' does not consist of all (visibly) printable characters.
The string 'string2' consists of all (visibly) printable characters.
The string 'string3' consists of all (visibly) printable characters.

参考

  • ctype_alnum() - 英数字かどうかを調べる
  • ctype_print() - 印字可能な文字かどうかを調べる
  • ctype_punct() - 空白、英数字以外の出力可能な文字かどうかを調べる
  • IntlChar::isgraph() - コードポイントが図形文字であるかを調べる


小文字かどうかを調べる

  • ≪ ctype_graph
  • ctype_print ≫
  • PHP Manual
  • Ctype 関数
  • 小文字かどうかを調べる

ctype_lower

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_lower — 小文字かどうかを調べる

説明

ctype_lower(mixed $text): bool

text のすべての文字が小文字だった場合に true 、そうでない場合に false を返します。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字がカレントのロケールで 小文字だった場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_lower() の例（デフォルトのロケールを利用）

<?php
$strings = array('aac123', 'qiutoas', 'QASsdks');
foreach ($strings as $testcase) {
if (ctype_lower($testcase)) {
echo "The string $testcase consists of all lowercase letters.\n";
} else {
echo "The string $testcase does not consist of all lowercase letters.\n";
}
}
?>

上の例の出力は以下となります。

The string aac123 does not consist of all lowercase letters.
The string qiutoas consists of all lowercase letters.
The string QASsdks does not consist of all lowercase letters.

参考

  • ctype_alpha() - 英字かどうかを調べる
  • ctype_upper() - 大文字かどうか調べる
  • setlocale() - ロケール情報を設定する
  • IntlChar::islower() - コードポイントが小文字かどうかを調べる


印字可能な文字かどうかを調べる

  • ≪ ctype_lower
  • ctype_punct ≫
  • PHP Manual
  • Ctype 関数
  • 印字可能な文字かどうかを調べる

ctype_print

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_print — 印字可能な文字かどうかを調べる

説明

ctype_print(mixed $text): bool

与えられた文字列 text のすべての文字が 印字可能な文字であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が（空白を含めて）実際に 出力を行う場合に true 、text に制御文字 またはまったく出力も制御も行わない文字が含まれる場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_print() の例

<?php
$strings = array('string1' => "asdf\n\r\t", 'string2' => 'arf12', 'string3' => 'LKA#@%.54');
foreach ($strings as $name => $testcase) {
if (ctype_print($testcase)) {
echo "The string '$name' consists of all printable characters.\n";
} else {
echo "The string '$name' does not consist of all printable characters.\n";
}
}
?>

上の例の出力は以下となります。

The string 'string1' does not consist of all printable characters.
The string 'string2' consists of all printable characters.
The string 'string3' consists of all printable characters.

参考

  • ctype_cntrl() - 制御文字かどうかを調べる
  • ctype_graph() - 空白以外の印字可能な文字かどうかを調べる
  • ctype_punct() - 空白、英数字以外の出力可能な文字かどうかを調べる
  • IntlChar::isprint() - コードポイントが印字可能な文字かを調べる


空白、英数字以外の出力可能な文字かどうかを調べる

  • ≪ ctype_print
  • ctype_space ≫
  • PHP Manual
  • Ctype 関数
  • 空白、英数字以外の出力可能な文字かどうかを調べる

ctype_punct

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_punct — 空白、英数字以外の出力可能な文字かどうかを調べる

説明

ctype_punct(mixed $text): bool

与えられた文字列 text のすべての文字が 句読点であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が出力可能であり、 かつ文字でも数字でも空白でもなかった場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_punct() の例

<?php
$strings = array('ABasdk!@!$#', '!@ # $', '*&$()');
foreach ($strings as $testcase) {
if (ctype_punct($testcase)) {
echo "The string $testcase consists of all punctuation.\n";
} else {
echo "The string $testcase does not consist of all punctuation.\n";
}
}
?>

上の例の出力は以下となります。

The string ABasdk!@!$# does not consist of all punctuation.
The string !@ # $ does not consist of all punctuation.
The string *&$() consists of all punctuation.

参考

  • ctype_cntrl() - 制御文字かどうかを調べる
  • ctype_graph() - 空白以外の印字可能な文字かどうかを調べる
  • IntlChar::ispunct() - コードポイントが句読点の文字かどうかを調べる


空白文字かどうか調べる

  • ≪ ctype_punct
  • ctype_upper ≫
  • PHP Manual
  • Ctype 関数
  • 空白文字かどうか調べる

ctype_space

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_space — 空白文字かどうか調べる

説明

ctype_space(mixed $text): bool

与えられた文字列 text のすべての文字が 空白文字であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字がなんらかの空白文字を 生成する場合に true 、そうでない場合に false を返します。 空白文字には、タブ・垂直タブ・改行・復帰・フォームフィード文字も 含まれます。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_space() の例

<?php
$strings = array(
'string1' => "\n\r\t",
'string2' => "\narf12",
'string3' => '\n\r\t' // 単一引用符に注意してください。
);

foreach ($strings as $name => $testcase) {
if (ctype_space($testcase)) {
echo "The string '$name' consists of whitespace characters only.\n";
} else {
echo "The string '$name' contains non-whitespace characters.\n";
}
}
?>

上の例の出力は以下となります。

The string 'string1' consists of whitespace characters only.
The string 'string2' contains non-whitespace characters.
The string 'string3' contains non-whitespace characters.

参考

  • ctype_cntrl() - 制御文字かどうかを調べる
  • ctype_graph() - 空白以外の印字可能な文字かどうかを調べる
  • ctype_punct() - 空白、英数字以外の出力可能な文字かどうかを調べる
  • IntlChar::isspace() - コードポイントが、スペース文字であるかを調べる


大文字かどうか調べる

  • ≪ ctype_space
  • ctype_xdigit ≫
  • PHP Manual
  • Ctype 関数
  • 大文字かどうか調べる

ctype_upper

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_upper — 大文字かどうか調べる

説明

ctype_upper(mixed $text): bool

与えられた文字列 text のすべての文字が 大文字であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字がカレントのロケールで 大文字だった場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_upper() の例（デフォルトのロケールを利用）

<?php
$strings = array('AKLWC139', 'LMNSDO', 'akwSKWsm');
foreach ($strings as $testcase) {
if (ctype_upper($testcase)) {
echo "The string $testcase consists of all uppercase letters.\n";
} else {
echo "The string $testcase does not consist of all uppercase letters.\n";
}
}
?>

上の例の出力は以下となります。

The string AKLWC139 does not consist of all uppercase letters.
The string LMNSDO consists of all uppercase letters.
The string akwSKWsm does not consist of all uppercase letters.

参考

  • ctype_alpha() - 英字かどうかを調べる
  • ctype_lower() - 小文字かどうかを調べる
  • setlocale() - ロケール情報を設定する
  • IntlChar::isupper() - コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する


16 進数を表す文字かどうかを調べる

  • ≪ ctype_upper
  • Filter ≫
  • PHP Manual
  • Ctype 関数
  • 16 進数を表す文字かどうかを調べる

ctype_xdigit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ctype_xdigit — 16 進数を表す文字かどうかを調べる

説明

ctype_xdigit(mixed $text): bool

与えられた文字列 text のすべての文字が 16 進の '数字' であるかどうかを調べます。

パラメータ

text

調べる文字列。

注意:

-128 から 255 までの int を渡すと、ひとつの文字の ASCII 値とみなします (負の値には 256 を足して、拡張 ASCII の範囲に収まるようにします)。 それ以外の整数値は、10 進数を含む文字列とみなします。

警告

PHP 8.1.0 以降は、ctype関数 に文字列でない引数を渡すことは、推奨されなくなりました。将来のバージョンでは、引数は ASCII コードポイントではなく、文字列として解釈されるようになります。ユーザが意図する振る舞いによっては、引数を文字列にキャストするか、 chr() を明示的にコールすべきです。

戻り値

text のすべての文字が 16 進の '数字' つまり 10 進の数字または [A-Fa-f] だった場合に true 、そうでない場合に false を返します。 空文字列を渡して呼び出した場合、結果は常に false になります。

例

例1 ctype_xdigit() の例

<?php
$strings = array('AB10BC99', 'AR1012', 'ab12bc99');
foreach ($strings as $testcase) {
if (ctype_xdigit($testcase)) {
echo "The string $testcase consists of all hexadecimal digits.\n";
} else {
echo "The string $testcase does not consist of all hexadecimal digits.\n";
}
}
?>

上の例の出力は以下となります。

The string AB10BC99 consists of all hexadecimal digits.
The string AR1012 does not consist of all hexadecimal digits.
The string ab12bc99 consists of all hexadecimal digits.

参考

  • ctype_digit() - 数字かどうかを調べる
  • IntlChar::isxdigit() - コードポイントが、16進数の文字であるかを調べる


データのフィルタリング

  • はじめに
  • インストール/設定
    • インストール手順
    • 実行時設定
  • フィルタの型
    • 検証フィルタ
    • 除去フィルタ
    • その他のフィルタ
    • フィルタフラグ
  • 定義済み定数
  • 例
    • 検証
    • 除去
  • Filter 関数
    • filter_has_var — 指定した型の変数が存在するかどうかを調べる
    • filter_id — フィルタの名前からフィルタ ID を返す
    • filter_input — 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
    • filter_input_array — 外部から変数を受け取り、オプションでそれらをフィルタリングする
    • filter_list — サポートされるフィルタの一覧を返す
    • filter_var — 指定したフィルタでデータをフィルタリングする
    • filter_var_array — 複数の変数を受け取り、オプションでそれらをフィルタリングする


はじめに

この拡張モジュールは、データの検証や除去を行います。 未知の (外部からの) データ、たとえばユーザーの入力などを扱う際に便利です。 HTML フォームから送られてくるデータなどがこれにあたります。

フィルタリングの方式には、大きく分けて 検証 (validation) と 除去 (sanitization) のふたつがあります。

検証 は、 データが何らかの条件を満たしているかどうかをチェックします。 たとえば FILTER_VALIDATE_EMAIL を渡すと、 データがメールアドレスとして正しい形式かどうかを調べます。 データ自体には何も手を加えません。

除去 は、 望まれていない文字を除去するなどしてデータを変更します。 たとえば FILTER_SANITIZE_EMAIL を渡すと、 メールアドレスとして無効な文字が含まれている場合にそれを除去します。 つまり、データの検証を行うわけではありません。

検証および除去のいずれについても、必要に応じて フラグ を使用して挙動を変更することができます。たとえば URL のフィルタリング時に FILTER_FLAG_PATH_REQUIRED を渡すと、パス (http://example.org/foo における /foo など) を必須とすることができます。


  • ≪ はじめに
  • インストール手順 ≫
  • PHP Manual
  • Filter
  • インストール/設定

インストール/設定

目次

  • インストール手順
  • 実行時設定


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-filter


実行時設定

php.ini の設定により動作が変化します。

フィルタ設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
filter.default | "unsafe_raw" | INI_PERDIR | PHP 8.1.0 以降は非推奨
filter.default_flags | NULL | INI_PERDIR |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

filter.default string

このフィルタで $_GET, $_POST, $_COOKIE, $_REQUEST および $_SERVER のすべてのデータをフィルタリングします。 もとのデータへは filter_input() でアクセスが可能です。

デフォルトで使用するフィルタの名前を指定することができます。 既存のフィルタの一覧を参照し、フィルタ名を指定してください。

注意:

デフォルトフィルタのデフォルトのフラグ設定には注意しましょう。 意識して、明示的に望みの値に設定しなければなりません。 たとえば、デフォルトフィルタの設定を htmlspecialchars() とまったく同様にするには デフォルトのフラグを以下のように 0 にしなければなりません。

例1 デフォルトフィルタを htmlspecialchars と同様の挙動にする設定

filter.default = full_special_chars
filter.default_flags = 0

filter.default_flags int

デフォルトのフラグ。デフォルトフィルタが設定されたときに適用されます。 過去との互換性を保つため、デフォルトは FILTER_FLAG_NO_ENCODE_QUOTES となっています。 フラグの一覧で、フラグ名を参照ください。


  • ≪ 実行時設定
  • 検証フィルタ ≫
  • PHP Manual
  • Filter
  • フィルタの型

フィルタの型

目次

  • 検証フィルタ
  • 除去フィルタ
  • その他のフィルタ
  • フィルタフラグ


検証フィルタ

検証用のフィルタの一覧
ID | 名前 | オプション | フラグ | 説明
FILTER_VALIDATE_BOOLEAN, FILTER_VALIDATE_BOOL | "boolean" | default | FILTER_NULL_ON_FAILURE | "1"、"true"、"on" および "yes" の場合に true、 それ以外の場合に false を返します。 FILTER_NULL_ON_FAILURE が設定されている場合は、 false が返されるのは "0"、"false"、"off"、"no" および "" の場合のみとなります。 boolean 以外の値については null を返します。 文字列の値については、 比較する前に先頭および末尾にあるホワイトスペースが取り除かれます。 取り除くために、trim() 関数を使います。
FILTER_VALIDATE_DOMAIN | "validate_domain" | default | FILTER_FLAG_HOSTNAME, FILTER_NULL_ON_FAILURE | ドメイン名ラベルの長さが妥当であるかを検証します。 ドメイン名が RFC 1034, RFC 1035, RFC 952, RFC 1123, RFC 2732, RFC 2181, RFC 1123 に照らして正しいかを検証します。 オプションのフラグ FILTER_FLAG_HOSTNAME を使うと、 ホスト名 (アルファベットか数字で始まり、 アルファベットか数字、もしくはハイフンのみが 含まれている必要があります) も追加で検証できます。
FILTER_VALIDATE_EMAIL | "validate_email" | default | FILTER_FLAG_EMAIL_UNICODE, FILTER_NULL_ON_FAILURE | 値が妥当な e-mail アドレスであるかどうかを検証します。 この検証は、e-mail アドレスが » RFC 822 の addr-spec 形式 に沿ったものであるかどうかを確かめます。 ただし、コメント、空白の折り返し (whitespace folding) および ドットなしドメイン名 (dotless domain name) には対応していません。
FILTER_VALIDATE_FLOAT | "float" | default, decimal, min_range, max_range | FILTER_FLAG_ALLOW_THOUSAND, FILTER_NULL_ON_FAILURE | 値が float であるかどうかを検証し、オプションで指定された範囲にあるかを調べます。成功した場合は値を float に変換します。 文字列の値については、 比較する前に先頭および末尾にあるホワイトスペースが取り除かれます。 取り除くために、trim() 関数を使います。
FILTER_VALIDATE_INT | "int" | default, min_range, max_range | FILTER_FLAG_ALLOW_OCTAL, FILTER_FLAG_ALLOW_HEX, FILTER_NULL_ON_FAILURE | 値が整数であるかどうか、オプションで指定した範囲内にあるかどうかを検証し、成功した場合は整数に変換します。 文字列の値については、 比較する前に先頭および末尾にあるホワイトスペースが取り除かれます。 取り除くために、trim() 関数を使います。
FILTER_VALIDATE_IP | "validate_ip" | default | FILTER_FLAG_IPV4, FILTER_FLAG_IPV6, FILTER_FLAG_NO_PRIV_RANGE, FILTER_FLAG_NO_RES_RANGE, FILTER_FLAG_GLOBAL_RANGE, FILTER_NULL_ON_FAILURE | 値が IP アドレスであるかどうかを検証します。 オプションで IPv4 あるいは IPv6 のみの指定、 プライベートアドレスや予約済みアドレスではないことの指定もできます。
FILTER_VALIDATE_MAC | "validate_mac_address" | default | FILTER_NULL_ON_FAILURE | 値が MAC アドレスであるかどうかを検証します。
FILTER_VALIDATE_REGEXP | "validate_regexp" | default, regexp | FILTER_NULL_ON_FAILURE | 値が、Perl 互換の 正規表現 regexp に一致するかどうかを検証します。
FILTER_VALIDATE_URL | "validate_url" | default | FILTER_FLAG_SCHEME_REQUIRED, FILTER_FLAG_HOST_REQUIRED, FILTER_FLAG_PATH_REQUIRED, FILTER_FLAG_QUERY_REQUIRED, FILTER_NULL_ON_FAILURE | 値が URL 形式である (» http://www.faqs.org/rfcs/rfc2396 に準拠している) かどうか、 オプションで、必須コンポーネントが含まれているかどうかを検証します。 妥当な URL が、HTTP プロトコル http:// を指定しているとは限りません。 つまり、その URL が期待通りのプロトコル (ssh:// や mailto: など) を使っているかどうか、さらなる検証が必要だということです。 この関数は、ASCII の URL のみを正しいとみなすことに注意しましょう。 国際化ドメイン名 (非 ASCII 文字を含むもの) は失敗します。

注意:

オプションに default を設定すると、値が検証されなかったときに default の値を使います。

変更履歴

バージョン | 説明
8.0.0 | FILTER_FLAG_SCHEME_REQUIRED および、 FILTER_VALIDATE_URL フィルタのための FILTER_FLAG_HOST_REQUIRED フラグは削除されました。 scheme と host は (かつてもそうでしたが) 常に必須になっています。
8.0.0 | FILTER_VALIDATE_BOOLEAN のエイリアスとして FILTER_VALIDATE_BOOL が追加されました。 FILTER_VALIDATE_BOOL を使う方が好ましいです。
7.4.0 | FILTER_VALIDATE_FLOAT 向けに min_range と max_range オプションが追加されました。
7.0.0 | FILTER_FLAG_HOSTNAME と FILTER_VALIDATE_DOMAIN が追加されました。


除去フィルタ

除去フィルタの一覧
ID | 名前 | フラグ | 説明
FILTER_SANITIZE_EMAIL | "email" |  | 英字、数字および !#$%&'*+-=?^_`{|}~@.[] 以外のすべての文字を取り除きます。
FILTER_SANITIZE_ENCODED | "encoded" | FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_STRIP_BACKTICK, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH | 文字列を URL エンコードします。オプションで、 特殊文字を取り除いたりエンコードしたりします。
FILTER_SANITIZE_MAGIC_QUOTES | "magic_quotes" |  | addslashes() を適用します。 (PHP 7.3.0 以降は非推奨になり、 PHP 8.0.0 以降 削除 されています。 代わりに FILTER_SANITIZE_ADD_SLASHES を使ってください)
FILTER_SANITIZE_ADD_SLASHES | "add_slashes" |  | addslashes() を適用します。 (PHP 7.3.0 以降で利用可能です)
FILTER_SANITIZE_NUMBER_FLOAT | "number_float" | FILTER_FLAG_ALLOW_FRACTION, FILTER_FLAG_ALLOW_THOUSAND, FILTER_FLAG_ALLOW_SCIENTIFIC | 数字、+- および オプションで .,eE 以外のすべての文字を取り除きます。
FILTER_SANITIZE_NUMBER_INT | "number_int" |  | 数字、プラス記号、マイナス記号 以外のすべての文字を取り除きます。
FILTER_SANITIZE_SPECIAL_CHARS | "special_chars" | FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_STRIP_BACKTICK, FILTER_FLAG_ENCODE_HIGH | '"<>& および ASCII 値が 32 未満の文字を HTML エンコードします。オプションで、 その他の特殊文字を取り除いたりエンコードしたりします。
FILTER_SANITIZE_FULL_SPECIAL_CHARS | "full_special_chars" | FILTER_FLAG_NO_ENCODE_QUOTES | htmlspecialchars() に ENT_QUOTES を指定してコールするのと同じです。 クォートのエンコードを無効にするには FILTER_FLAG_NO_ENCODE_QUOTES を設定します。 htmlspecialchars() と同様、このフィルタは default_charset に対応しています。 現在の文字セットで無効な文字となるバイトシーケンスが検出されると文字列全体を拒否し、 結果は長さ 0 の文字列となります。 このフィルタをデフォルトのフィルタとして使う場合は、以下の警告を参考にして デフォルトのフラグを 0 に設定しましょう。
FILTER_SANITIZE_STRING | "string" | FILTER_FLAG_NO_ENCODE_QUOTES, FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_STRIP_BACKTICK, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH, FILTER_FLAG_ENCODE_AMP | タグと、エンコードされたシングルクォート、 ダブルクォートを取り除きます。 オプションで、 特殊文字を取り除いたりエンコードしたりします。 クォートをエンコードする動作は、 FILTER_FLAG_NO_ENCODE_QUOTES を設定することで無効に出来ます。 (PHP 8.1.0 以降は 非推奨 になりました。 代わりに htmlspecialchars() を使って下さい)
FILTER_SANITIZE_STRIPPED | "stripped" |  | "string" フィルタのエイリアス。 (PHP 8.1.0 以降は 非推奨 になりました。 代わりに htmlspecialchars() を使って下さい)
FILTER_SANITIZE_URL | "url" |  | 英字、数字および $-_.+!*'(),{}|\\^~[]`<>#%";/?:@&= 以外のすべての文字を取り除きます。
FILTER_UNSAFE_RAW | "unsafe_raw" | FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_STRIP_BACKTICK, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH, FILTER_FLAG_ENCODE_AMP | 何もせず、オプションで特殊文字を取り除いたりエンコードしたりします。 FILTER_DEFAULT は、このフィルタのエイリアスです。

警告

これらのフィルタのいずれかを ini ファイルやウェブサーバーの設定でデフォルトフィルタとして使用すると、 デフォルトのフラグは FILTER_FLAG_NO_ENCODE_QUOTES となります。 デフォルトでクォートをエンコードさせるには、 明示的に filter.default_flags を 0 としなければなりません。

例1 デフォルトのフィルタを htmlspecialchars と同様の挙動にする設定

filter.default = full_special_chars
filter.default_flags = 0

変更履歴

バージョン | 説明
8.1.0 | FILTER_SANITIZE_STRING と FILTER_SANITIZE_STRIPPED は推奨されなくなりました。
8.0.0 | FILTER_SANITIZE_MAGIC_QUOTES が削除されました。
7.3.0 | FILTER_SANITIZE_MAGIC_QUOTES の代替として FILTER_SANITIZE_ADD_SLASHES が追加されました。
7.3.0 | FILTER_SANITIZE_MAGIC_QUOTES は推奨されなくなりました。


その他のフィルタ

その他のフィルタの一覧
ID | 名前 | オプション | フラグ | 説明
FILTER_CALLBACK | "callback" | callable 関数あるいはメソッド |  | ユーザー定義の関数をコールしてデータをフィルタリングします。


フィルタフラグ

フィルタフラグの一覧
ID | 使える場所 | 説明
FILTER_FLAG_STRIP_LOW | FILTER_SANITIZE_ENCODED, FILTER_SANITIZE_SPECIAL_CHARS, FILTER_SANITIZE_STRING, FILTER_UNSAFE_RAW | コードが 32 未満の文字を除去します。
FILTER_FLAG_STRIP_HIGH | FILTER_SANITIZE_ENCODED, FILTER_SANITIZE_SPECIAL_CHARS, FILTER_SANITIZE_STRING, FILTER_UNSAFE_RAW | コードが 127 より大きい文字を除去します。
FILTER_FLAG_STRIP_BACKTICK | FILTER_SANITIZE_ENCODED, FILTER_SANITIZE_SPECIAL_CHARS, FILTER_SANITIZE_STRING, FILTER_UNSAFE_RAW | バッククォート文字を除去します。
FILTER_FLAG_ALLOW_FRACTION | FILTER_SANITIZE_NUMBER_FLOAT | ピリオド (.) を数値の小数点として許可します。
FILTER_FLAG_ALLOW_THOUSAND | FILTER_SANITIZE_NUMBER_FLOAT, FILTER_VALIDATE_FLOAT | カンマ (,) を数値の桁区切り文字として許可します。
FILTER_FLAG_ALLOW_SCIENTIFIC | FILTER_SANITIZE_NUMBER_FLOAT | e あるいは E を、 科学記法の数値として許可します。
FILTER_FLAG_NO_ENCODE_QUOTES | FILTER_SANITIZE_STRING | このフラグを指定すると、シングルクォート (') およびダブルクォート (") をエンコードしません。
FILTER_FLAG_ENCODE_LOW | FILTER_SANITIZE_ENCODED, FILTER_SANITIZE_STRING, FILTER_UNSAFE_RAW | コードが 32 未満のすべての文字をエンコードします。
FILTER_FLAG_ENCODE_HIGH | FILTER_SANITIZE_ENCODED, FILTER_SANITIZE_SPECIAL_CHARS, FILTER_SANITIZE_STRING, FILTER_UNSAFE_RAW | コードが 127 より大きいすべての文字をエンコードします。
FILTER_FLAG_ENCODE_AMP | FILTER_SANITIZE_STRING, FILTER_UNSAFE_RAW | アンパサンド (&) をエンコードします。
FILTER_NULL_ON_FAILURE | FILTER_VALIDATE_BOOLEAN, FILTER_VALIDATE_BOOL 任意の FILTER_VALIDATE_* 定数。 | 認識できない値の場合に null を返します。
FILTER_FLAG_ALLOW_OCTAL | FILTER_VALIDATE_INT | ゼロ (0) で始まる入力を八進数とみなします。 ゼロの後には 0-7 しか続けることができません。
FILTER_FLAG_ALLOW_HEX | FILTER_VALIDATE_INT | 0x あるいは 0X で始まる入力を十六進数とみなします。 後に続けられる文字は a-fA-F0-9 だけです。
FILTER_FLAG_EMAIL_UNICODE | FILTER_VALIDATE_EMAIL | email アドレスのローカルパートに Unicode 文字を含めることを許可します。
FILTER_FLAG_IPV4 | FILTER_VALIDATE_IP | IPv4 形式の IP アドレスを許可します。
FILTER_FLAG_IPV6 | FILTER_VALIDATE_IP | IPv6 形式の IP アドレスを許可します。
FILTER_FLAG_NO_PRIV_RANGE | FILTER_VALIDATE_IP | IPv4 プライベート領域 10.0.0.0/8, 172.16.0.0/12 および 192.168.0.0/16 を許可しません。 FD あるいは FC ではじまる IPv6 アドレスを許可しません。
FILTER_FLAG_NO_RES_RANGE | FILTER_VALIDATE_IP | 予約済みの IPv4 範囲 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8 および 240.0.0.0/4 を許可しません。 予約済みの IPv6 範囲 ::1/128、::/128、 ::ffff:0:0/96 および fe80::/10 を許可しません。 これらの IP の範囲は、 » RFC 6890 で、 プロトコルによって予約されているとマークされているものです。
FILTER_FLAG_GLOBAL_RANGE | FILTER_VALIDATE_IP | » RFC 6890 で Global 属性が False になっている、グローバルでない IPv4/IPv6 アドレスについては、 検証が失敗します。
FILTER_FLAG_SCHEME_REQUIRED | FILTER_VALIDATE_URL | URL がスキームを含むことを要求します。
FILTER_FLAG_HOST_REQUIRED | FILTER_VALIDATE_URL | URL がホストを含むことを要求します。
FILTER_FLAG_PATH_REQUIRED | FILTER_VALIDATE_URL | URL で、パス部分を必須とします。
FILTER_FLAG_QUERY_REQUIRED | FILTER_VALIDATE_URL | URL で、クエリ文字列を必須とします。
FILTER_REQUIRE_SCALAR |  | 値がスカラーであることを必須とします。
FILTER_REQUIRE_ARRAY |  | 値が配列であることを必須とします。 指定されたフィルタは、配列の個々のスカラーの要素に適用されます。
FILTER_FORCE_ARRAY |  | 値がスカラーである場合は、スカラー値をひとつだけ持つ配列として扱います。

変更履歴

バージョン | 説明
8.2.0 | FILTER_VALIDATE_IP に指定できるフラグとして、 FILTER_FLAG_GLOBAL_RANGE が追加されました。
7.3.0 | FILTER_FLAG_SCHEME_REQUIRED と FILTER_FLAG_HOST_REQUIRED を明示的に使用することは推奨されなくなりました。
7.1.0 | FILTER_FLAG_EMAIL_UNICODE が追加されました。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

INPUT_POST (int)
POST 変数。
INPUT_GET (int)
GET 変数。
INPUT_COOKIE (int)
COOKIE 変数。
INPUT_ENV (int)
ENV 変数。
INPUT_SERVER (int)
SERVER 変数。
INPUT_SESSION (int)
SESSION 変数 (まだ実装されていません)。
INPUT_REQUEST (int)
REQUEST 変数 (まだ実装されていません)。
FILTER_FLAG_NONE (int)
フィルタしない。
FILTER_REQUIRE_SCALAR (int)
入力値としてスカラーを要求するために使用するフラグ。
FILTER_REQUIRE_ARRAY (int)
入力として配列を要求します。
FILTER_FORCE_ARRAY (int)
常に配列として返します。
FILTER_NULL_ON_FAILURE (int)
失敗した場合に FALSE ではなく NULL を使用します。
FILTER_VALIDATE_INT (int)
"int" フィルタの ID。
FILTER_VALIDATE_BOOL (int)
FILTER_VALIDATE_BOOLEAN のエイリアス。
FILTER_VALIDATE_BOOLEAN (int)
"boolean" フィルタの ID。
FILTER_VALIDATE_FLOAT (int)
"float" フィルタの ID。
FILTER_VALIDATE_REGEXP (int)
"validate_regexp" フィルタの ID。
FILTER_VALIDATE_URL (int)
"validate_url" フィルタの ID。
FILTER_VALIDATE_DOMAIN (int)
"validate_domain" フィルタの ID。 (PHP 7.0.0 以降で利用可能)
FILTER_VALIDATE_EMAIL (int)
"validate_email" フィルタの ID。
FILTER_VALIDATE_IP (int)
"validate_ip" フィルタの ID。
FILTER_VALIDATE_MAC (int)
"validate_mac_address" フィルタの ID。
FILTER_DEFAULT (int)
デフォルト ("unsafe_raw") フィルタの ID。 これは FILTER_UNSAFE_RAW と同等です。
FILTER_UNSAFE_RAW (int)
"unsafe_raw" フィルタの ID。
FILTER_SANITIZE_STRING (int)
"string" フィルタの ID。 (PHP 8.1.0 以降は 非推奨 になりました。 代わりに htmlspecialchars() を使って下さい)
FILTER_SANITIZE_STRIPPED (int)
"stripped" フィルタの ID。 (PHP 8.1.0 以降は 非推奨 になりました。 代わりに htmlspecialchars() を使って下さい)
FILTER_SANITIZE_ENCODED (int)
"encoded" フィルタの ID。
FILTER_SANITIZE_SPECIAL_CHARS (int)
"special_chars" フィルタの ID。
FILTER_SANITIZE_EMAIL (int)
"email" フィルタの ID。
FILTER_SANITIZE_URL (int)
"url" フィルタの ID。
FILTER_SANITIZE_NUMBER_INT (int)
"number_int" フィルタの ID。
FILTER_SANITIZE_NUMBER_FLOAT (int)
"number_float" フィルタの ID。
FILTER_SANITIZE_MAGIC_QUOTES (int)
"magic_quotes" フィルタの ID。 (PHP 7.3.0 以降は非推奨になり、 PHP 8.0.0 以降 削除 されています。 代わりに FILTER_SANITIZE_ADD_SLASHES を使ってください)
FILTER_SANITIZE_ADD_SLASHES (int)
"add_slashes" フィルタの ID。 (PHP 7.3.0 以降で利用可能)
FILTER_CALLBACK (int)
"callback" フィルタの ID。
FILTER_FLAG_ALLOW_OCTAL (int)
"int" フィルタで 8 進表記 (0[0-7]+) を許可します。
FILTER_FLAG_ALLOW_HEX (int)
"int" フィルタで 16 進表記 (0x[0-9a-fA-F]+) を許可します。
FILTER_FLAG_STRIP_LOW (int)
ASCII 値が 32 未満の文字を取り除きます。
FILTER_FLAG_STRIP_HIGH (int)
ASCII 値が 127 より大きい文字を取り除きます。
FILTER_FLAG_STRIP_BACKTICK (int)
バッククォート文字を取り除きます。
FILTER_FLAG_ENCODE_LOW (int)
ASCII 値が 32 未満の文字をエンコードします。
FILTER_FLAG_ENCODE_HIGH (int)
ASCII 値が 127 より大きい文字をエンコードします。
FILTER_FLAG_ENCODE_AMP (int)
& をエンコードします。
FILTER_FLAG_NO_ENCODE_QUOTES (int)
' および " をエンコードしません。
FILTER_FLAG_EMPTY_STRING_NULL (int)
(現在は使用されていません)
FILTER_FLAG_ALLOW_FRACTION (int)
"number_float" フィルタで小数を許可します。
FILTER_FLAG_ALLOW_THOUSAND (int)
"number_float" フィルタで桁区切り文字 (,) を許可します。
FILTER_FLAG_ALLOW_SCIENTIFIC (int)
"number_float" フィルタで科学記法 (e, E) を許可します。
FILTER_FLAG_PATH_REQUIRED (int)
"validate_url" フィルタでパスを必須とします。
FILTER_FLAG_QUERY_REQUIRED (int)
"validate_url" フィルタでクエリ文字列を必須とします。
FILTER_FLAG_SCHEME_REQUIRED (int)
"validate_url" フィルタで scheme を必須とします。 ("validate_url" フィルタに含まれるようになったため、 PHP 7.3.0 以降は非推奨になり、PHP 8.0.0 で削除されました。)
FILTER_FLAG_HOST_REQUIRED (int)
"validate_url" フィルタで host 部分を必須とします。 ("validate_url" フィルタに含まれるようになったため、 PHP 7.3.0 以降は非推奨になり、PHP 8.0.0 で削除されました。)
FILTER_FLAG_HOSTNAME (int)
アルファベットと数字から始まり、アルファベットと数字およびハイフンだけを含むホスト名を必須とします。 (PHP 7.0.0 以降で利用可能です)
FILTER_FLAG_IPV4 (int)
"validate_ip" フィルタで IPv4 アドレスのみを許可します。
FILTER_FLAG_IPV6 (int)
"validate_ip" フィルタで IPv6 アドレスのみを許可します。
FILTER_FLAG_NO_RES_RANGE (int)
"validate_ip" フィルタで予約済みアドレスを拒否します。
FILTER_FLAG_NO_PRIV_RANGE (int)
"validate_ip" フィルタでプライベートアドレスを拒否します。
FILTER_FLAG_EMAIL_UNICODE (int)
"validate_email" フィルタで、ローカルパートに Unicode 文字を許可します。 (PHP 7.1.0 以降で利用可能)


  • ≪ 定義済み定数
  • 検証 ≫
  • PHP Manual
  • Filter
  • 例

例

目次

  • 検証
  • 除去


検証

例1 filter_var() でのメールアドレスの検証

<?php
$email_a = 'joe@example.com';
$email_b = 'bogus';

if (filter_var($email_a, FILTER_VALIDATE_EMAIL)) {
echo "'$email_a' はメールアドレスとして有効です。\n";
}
if (filter_var($email_b, FILTER_VALIDATE_EMAIL)) {
echo "'$email_b' はメールアドレスとして有効です。\n";
} else {
echo "'$email_b' はメールアドレスとして無効です。\n";
}
?>

上の例の出力は以下となります。

'joe@example.com' はメールアドレスとして有効です。
'bogus' はメールアドレスとして無効です。

例2 filter_var() での IP アドレスの検証

<?php
$ip_a = '127.0.0.1';
$ip_b = '42.42';

if (filter_var($ip_a, FILTER_VALIDATE_IP)) {
echo "'$ip_a' は IP アドレスとして有効です。";
}
if (filter_var($ip_b, FILTER_VALIDATE_IP)) {
echo "'$ip_b' は IP アドレスとして有効です。";
}
?>

上の例の出力は以下となります。

'127.0.0.1' は IP アドレスとして有効です。

例3 filter_var() でのオプションの指定

<?php
$int_a = '1';
$int_b = '-1';
$int_c = '4';
$options = array(
'options' => array(
'min_range' => 0,
'max_range' => 3,
)
);
if (filter_var($int_a, FILTER_VALIDATE_INT, $options) !== FALSE) {
echo "整数値 A '$int_a' は有効な値 (0 から 3 までの間) です。\n";
}
if (filter_var($int_b, FILTER_VALIDATE_INT, $options) !== FALSE) {
echo "整数値 B '$int_b' は有効な値 (0 から 3 までの間) です。\n";
}
if (filter_var($int_c, FILTER_VALIDATE_INT, $options) !== FALSE) {
echo "整数値 C '$int_c' は有効な値 (0 から 3 までの間) です。\n";
}

$options['options']['default'] = 1;
if (($int_c = filter_var($int_c, FILTER_VALIDATE_INT, $options)) !== FALSE) {
echo "整数値 C '$int_c' は有効な値 (0 から 3 までの間) です。";
}
?>

上の例の出力は以下となります。

整数値 A '1' は有効な値 (0 から 3 までの間) です。
整数値 C '1' は有効な値 (0 から 3 までの間) です。


除去

例1 メールアドレスの検証、および不正な部分の除去

<?php
$a = 'joe@example.org';
$b = 'bogus - at - example dot org';
$c = '(bogus@example.org)';

$sanitized_a = filter_var($a, FILTER_SANITIZE_EMAIL);
if (filter_var($sanitized_a, FILTER_VALIDATE_EMAIL)) {
echo "処理済の (a) はメールアドレスとして有効です。\n";
}

$sanitized_b = filter_var($b, FILTER_SANITIZE_EMAIL);
if (filter_var($sanitized_b, FILTER_VALIDATE_EMAIL)) {
echo "処理済のメールアドレスは有効です。";
} else {
echo "処理済の (b) はメールアドレスとして無効です。\n";
}

$sanitized_c = filter_var($c, FILTER_SANITIZE_EMAIL);
if (filter_var($sanitized_c, FILTER_VALIDATE_EMAIL)) {
echo "処理済の (c) はメールアドレスとして有効です。\n";
echo "処理前: $c\n";
echo "処理後: $sanitized_c\n";
}
?>

上の例の出力は以下となります。

処理済の (a) はメールアドレスとして有効です。
処理済の (b) はメールアドレスとして無効です。
処理済の (c) はメールアドレスとして有効です。
処理前: (bogus@example.org)
処理後: bogus@example.org

例2 デフォルトのフィルタの設定

filter.default = full_special_chars
filter.default_flags = 0


Filter 関数

目次

  • filter_has_var — 指定した型の変数が存在するかどうかを調べる
  • filter_id — フィルタの名前からフィルタ ID を返す
  • filter_input — 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
  • filter_input_array — 外部から変数を受け取り、オプションでそれらをフィルタリングする
  • filter_list — サポートされるフィルタの一覧を返す
  • filter_var — 指定したフィルタでデータをフィルタリングする
  • filter_var_array — 複数の変数を受け取り、オプションでそれらをフィルタリングする


指定した型の変数が存在するかどうかを調べる

  • ≪ Filter 関数
  • filter_id ≫
  • PHP Manual
  • Filter 関数
  • 指定した型の変数が存在するかどうかを調べる

filter_has_var

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_has_var — 指定した型の変数が存在するかどうかを調べる

説明

filter_has_var(int $input_type, string $var_name): bool

パラメータ

input_type

INPUT_GET、INPUT_POST、 INPUT_COOKIE、INPUT_SERVER、 INPUT_ENV のいずれか。

var_name

調べたい変数の名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。


フィルタの名前からフィルタ ID を返す

  • ≪ filter_has_var
  • filter_input ≫
  • PHP Manual
  • Filter 関数
  • フィルタの名前からフィルタ ID を返す

filter_id

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_id — フィルタの名前からフィルタ ID を返す

説明

filter_id(string $name): int|false

パラメータ

name

取得したいフィルタの名前。

戻り値

フィルタの ID を返します。フィルタが存在しない場合は false を返します。

参考

  • filter_list() - サポートされるフィルタの一覧を返す


指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする

  • ≪ filter_id
  • filter_input_array ≫
  • PHP Manual
  • Filter 関数
  • 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする

filter_input

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_input — 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする

説明

filter_input(
int $type,
string $var_name,
int $filter = FILTER_DEFAULT,
array|int $options = 0
): mixed

パラメータ

type

INPUT_GET、INPUT_POST、 INPUT_COOKIE、INPUT_SERVER あるいは INPUT_ENV のいずれか。

var_name

取得する変数の名前。

filter

適用するフィルタの ID。フィルタの型 に、利用できるフィルタの一覧があります。

省略した場合は FILTER_DEFAULT を使います。これは FILTER_UNSAFE_RAW と同等です。 結果的に、デフォルトでは何もフィルタリングをしません。

options

オプションあるいはフラグの論理和の連想配列。 オプションを指定可能なフィルタの場合、この配列の "flags" フィールドにフラグを指定します。

戻り値

成功した場合は要求された変数の値、フィルタリングに失敗した場合に false、 あるいは変数 var_name が設定されていない場合に null を返します。フラグ FILTER_NULL_ON_FAILURE が指定されている場合は、変数が設定されていなければ false、 フィルタリングに失敗したら null を返します。

例

例1 filter_input() の例

<?php
$search_html = filter_input(INPUT_GET, 'search', FILTER_SANITIZE_SPECIAL_CHARS);
$search_url = filter_input(INPUT_GET, 'search', FILTER_SANITIZE_ENCODED);
echo "You have searched for $search_html.\n";
echo "<a href='?search=$search_url'>Search again.</a>";
?>

上の例の出力は、 たとえば以下のようになります。

You have searched for Me &#38; son.
<a href='?search=Me%20%26%20son'>Search again.</a>

参考

  • filter_var() - 指定したフィルタでデータをフィルタリングする
  • filter_input_array() - 外部から変数を受け取り、オプションでそれらをフィルタリングする
  • filter_var_array() - 複数の変数を受け取り、オプションでそれらをフィルタリングする
  • フィルタの型


外部から変数を受け取り、オプションでそれらをフィルタリングする

  • ≪ filter_input
  • filter_list ≫
  • PHP Manual
  • Filter 関数
  • 外部から変数を受け取り、オプションでそれらをフィルタリングする

filter_input_array

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_input_array — 外部から変数を受け取り、オプションでそれらをフィルタリングする

説明

filter_input_array(int $type, array|int $options = FILTER_DEFAULT, bool $add_empty = true): array|false|null

この関数を使用すると、大量のデータを取得する際に filter_input() を繰り返しコールする必要がなくなるので便利です。

パラメータ

type

INPUT_GET、INPUT_POST、 INPUT_COOKIE、INPUT_SERVER あるいは INPUT_ENV のいずれか。

options

引数を定義する配列。配列のキーとして使用できるのは 変数名を string で表したものです。 対応する値に使用できるのは、フィルタの型か配列 (フィルタ・フラグ・オプションを指定したもの) です。 配列の値として配列を使用する場合に使用できるキーは、 filter (フィルタの型)、 flags (フィルタに適用するフラグ) および options (フィルタに適用するオプション) です。理解を深めるために、以下の例を参照ください。

このパラメータには、フィルタ定数 を表す整数値を指定することもできます。 こうすると、入力配列のすべての値がそのフィルタで処理されます。

add_empty

存在しないキーは null として戻り値に追加します。

戻り値

成功した場合は要求された変数の値を含む配列。 FILTER_NULL_ON_FAILURE フラグが指定されない場合、 かつ type で指定された入力値の配列が得られなかった場合は、 この関数は null を返します。 type で指定された入力値の配列が得られなかった場合、 かつ FILTER_NULL_ON_FAILURE フラグが指定されていた場合は、 この関数は false を返します。その他の理由で失敗した場合でも false を返します。

フィルタが失敗した場合、配列の値は false になります。 変数が設定されていない場合は、null になります。 フラグ FILTER_NULL_ON_FAILURE が指定されている場合は、変数が設定されていないときに false、 フィルタリングに失敗した場合に null となります。 add_empty パラメータが false の場合、 配列の要素は追加されません。

例

例1 filter_input_array() の例

<?php

/* データは、実際には POST リクエストでやってきます
$_POST = array(
'product_id' => 'libgd<script>',
'component' => array('10'),
'version' => '2.0.33',
'testarray' => array('2', '23', '10', '12'),
'testscalar' => '2',
);
*/

$args = array(
'product_id' => FILTER_SANITIZE_ENCODED,
'component' => array('filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_ARRAY,
'options' => array('min_range' => 1, 'max_range' => 10)
),
'version' => FILTER_SANITIZE_ENCODED,
'doesnotexist' => FILTER_VALIDATE_INT,
'testscalar' => array(
'filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_SCALAR,
),
'testarray' => array(
'filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_ARRAY,
)

);

$myinputs = filter_input_array(INPUT_POST, $args);

var_dump($myinputs);
echo "\n";
?>

上の例の出力は以下となります。

array(6) {
  ["product_id"]=>
  string(17) "libgd%3Cscript%3E"
  ["component"]=>
  array(1) {
    [0]=>
    int(10)
  }
  ["version"]=>
  string(6) "2.0.33"
  ["doesnotexist"]=>
  NULL
  ["testscalar"]=>
  int(2)
  ["testarray"]=>
  array(4) {
    [0]=>
    int(2)
    [1]=>
    int(23)
    [2]=>
    int(10)
    [3]=>
    int(12)
  }
}

注意

注意:

INPUT_SERVER 配列には、 キー REQUEST_TIME が存在しません。 あとで $_SERVER に追加されるからです。

参考

  • filter_input() - 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
  • filter_var_array() - 複数の変数を受け取り、オプションでそれらをフィルタリングする
  • フィルタの型


サポートされるフィルタの一覧を返す

  • ≪ filter_input_array
  • filter_var ≫
  • PHP Manual
  • Filter 関数
  • サポートされるフィルタの一覧を返す

filter_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_list — サポートされるフィルタの一覧を返す

説明

filter_list(): array

パラメータ

この関数にはパラメータはありません。

戻り値

サポートされる全フィルタの名前の配列を返します。 フィルタが存在しない場合は空の配列を返します。 この配列のインデックスはフィルタの ID ではありません。 ID を取得するには filter_id() にフィルタ名を渡します。

例

例1 filter_list() の例

<?php
print_r(filter_list());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => int
    [1] => boolean
    [2] => float
    [3] => validate_regexp
    [4] => validate_url
    [5] => validate_email
    [6] => validate_ip
    [7] => string
    [8] => stripped
    [9] => encoded
    [10] => special_chars
    [11] => unsafe_raw
    [12] => email
    [13] => url
    [14] => number_int
    [15] => number_float
    [16] => magic_quotes
    [17] => callback
)


指定したフィルタでデータをフィルタリングする

  • ≪ filter_list
  • filter_var_array ≫
  • PHP Manual
  • Filter 関数
  • 指定したフィルタでデータをフィルタリングする

filter_var

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_var — 指定したフィルタでデータをフィルタリングする

説明

filter_var(mixed $value, int $filter = FILTER_DEFAULT, array|int $options = 0): mixed

パラメータ

value

フィルタリングする値。値をフィルタリングする前に、 内部的に 文字列への変換 が行われることに注意しましょう。

filter

適用するフィルタの ID。フィルタの型 に、利用できるフィルタの一覧があります。

省略した場合は FILTER_DEFAULT を使います。これは FILTER_UNSAFE_RAW と同等です。 結果的に、デフォルトでは何もフィルタリングをしません。

options

オプションあるいはフラグの論理和の連想配列。 オプションを指定可能なフィルタの場合、この配列の "flags" フィールドにフラグを指定します。 "callback" フィルタの場合は、callable 型を渡さなければなりません。 コールバックは、フィルタリングする値を引数として受け取り、 処理後の値を返すようにしなければなりません。

<?php
// オプションを許可するフィルタは、このような形式となります
$options = array(
'options' => array(
'default' => 3, // フィルタが失敗した場合に返す値
// その他のオプションをここに書きます
'min_range' => 0
),
'flags' => FILTER_FLAG_ALLOW_OCTAL,
);
$var = filter_var('0755', FILTER_VALIDATE_INT, $options);

// フラグのみを許可するフィルタは、それを直接記述します
$var = filter_var('oops', FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);

// フラグのみを許可するフィルタは、配列として渡すこともできます
$var = filter_var('oops', FILTER_VALIDATE_BOOLEAN,
array('flags' => FILTER_NULL_ON_FAILURE));

// コールバック検証フィルタ
function foo($value)
{
// 期待する書式: Surname, GivenNames
if (strpos($value, ", ") === false) return false;
list($surname, $givennames) = explode(", ", $value, 2);
$empty = (empty($surname) || empty($givennames));
$notstrings = (!is_string($surname) || !is_string($givennames));
if ($empty || $notstrings) {
return false;
} else {
return $value;
}
}
$var = filter_var('Doe, Jane Sue', FILTER_CALLBACK, array('options' => 'foo'));
?>

戻り値

フィルタリングされたデータ、あるいは処理に失敗した場合に false を返します。

例

例1 filter_var() の例

<?php
var_dump(filter_var('bob@example.com', FILTER_VALIDATE_EMAIL));
var_dump(filter_var('http://example.com', FILTER_VALIDATE_URL, FILTER_FLAG_PATH_REQUIRED));
?>

上の例の出力は以下となります。

string(15) "bob@example.com"
bool(false)

例2 配列をフィルタする例

<?php
$emails = [
"bob@example.com",
"test@example.local",
"invalidemail"
];

var_dump(filter_var($emails, FILTER_VALIDATE_EMAIL, FILTER_REQUIRE_ARRAY));
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  string(15) "bob@example.com"
  [1]=>
  string(18) "test@example.local"
  [2]=>
  bool(false)
}

参考

  • filter_var_array() - 複数の変数を受け取り、オプションでそれらをフィルタリングする
  • filter_input() - 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
  • filter_input_array() - 外部から変数を受け取り、オプションでそれらをフィルタリングする
  • フィルタの型


複数の変数を受け取り、オプションでそれらをフィルタリングする

  • ≪ filter_var
  • 関数処理 ≫
  • PHP Manual
  • Filter 関数
  • 複数の変数を受け取り、オプションでそれらをフィルタリングする

filter_var_array

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_var_array — 複数の変数を受け取り、オプションでそれらをフィルタリングする

説明

filter_var_array(array $array, array|int $options = FILTER_DEFAULT, bool $add_empty = true): array|false|null

この関数を使用すると、大量の変数を取得する際に filter_var() を繰り返しコールする必要がなくなるので便利です。

パラメータ

array

文字列キーの配列。フィルタリングするデータを保持します。

options

引数を定義する配列。配列のキーとして使用できるのは 変数名を string で表したものです。 対応する値に使用できるのは、 フィルタの型か配列 (フィルタ・フラグ・オプションを指定したもの) です。 配列の値として配列を使用する場合に使用できるキーは、 filter (フィルタの型)、 flags (フィルタに適用するフラグ) および options (フィルタに適用するオプション) です。理解を深めるために、以下の例を参照ください。

このパラメータには、フィルタ定数 を表す整数値を指定することもできます。 こうすると、入力配列のすべての値がそのフィルタで処理されます。

add_empty

存在しないキーは null として戻り値に追加します。

戻り値

成功した場合は要求された変数の値を含む配列、 あるいは失敗した場合に false を返します。 配列の値は、フィルタリングに失敗した場合には false、 変数が設定されていない場合は null となります。

例

例1 filter_var_array() の例

<?php

$data = array(
'product_id' => 'libgd<script>',
'component' => '10',
'versions' => '2.0.33',
'testscalar' => array('2', '23', '10', '12'),
'testarray' => '2',
);

$args = array(
'product_id' => FILTER_SANITIZE_ENCODED,
'component' => array('filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_FORCE_ARRAY,
'options' => array('min_range' => 1, 'max_range' => 10)
),
'versions' => FILTER_SANITIZE_ENCODED,
'doesnotexist' => FILTER_VALIDATE_INT,
'testscalar' => array(
'filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_REQUIRE_SCALAR,
),
'testarray' => array(
'filter' => FILTER_VALIDATE_INT,
'flags' => FILTER_FORCE_ARRAY,
)

);

$myinputs = filter_var_array($data, $args);

var_dump($myinputs);
echo "\n";
?>

上の例の出力は以下となります。

array(6) {
  ["product_id"]=>
  string(17) "libgd%3Cscript%3E"
  ["component"]=>
  array(1) {
    [0]=>
    int(10)
  }
  ["versions"]=>
  string(6) "2.0.33"
  ["doesnotexist"]=>
  NULL
  ["testscalar"]=>
  bool(false)
  ["testarray"]=>
  array(1) {
    [0]=>
    int(2)
  }
}

参考

  • filter_input_array() - 外部から変数を受け取り、オプションでそれらをフィルタリングする
  • filter_var() - 指定したフィルタでデータをフィルタリングする
  • filter_input() - 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
  • フィルタの型


関数処理

  • はじめに
  • 関数処理 関数
    • call_user_func — 最初の引数で指定したコールバック関数をコールする
    • call_user_func_array — パラメータの配列を指定してコールバック関数をコールする
    • create_function — 文字列のコードを評価し、動的に関数を作成する
    • forward_static_call — static メソッドをコールする
    • forward_static_call_array — static メソッドをコールし、引数を配列で渡す
    • func_get_arg — 引数のリストから要素をひとつ返す
    • func_get_args — 関数の引数リストを配列として返す
    • func_num_args — 関数に渡された引数の数を返す
    • function_exists — 指定した関数が定義されている場合に true を返す
    • get_defined_functions — 定義済みの全ての関数を配列で返す
    • register_shutdown_function — シャットダウン時に実行する関数を登録する
    • register_tick_function — 各 tick で実行する関数を登録する
    • unregister_tick_function — 各 tick の実行用の関数の登録を解除する


  • ≪ 関数処理
  • 関数処理 関数 ≫
  • PHP Manual
  • 関数処理
  • はじめに

はじめに

これらの関数は、関数で行う様々な処理を行います。


関数処理 関数

目次

  • call_user_func — 最初の引数で指定したコールバック関数をコールする
  • call_user_func_array — パラメータの配列を指定してコールバック関数をコールする
  • create_function — 文字列のコードを評価し、動的に関数を作成する
  • forward_static_call — static メソッドをコールする
  • forward_static_call_array — static メソッドをコールし、引数を配列で渡す
  • func_get_arg — 引数のリストから要素をひとつ返す
  • func_get_args — 関数の引数リストを配列として返す
  • func_num_args — 関数に渡された引数の数を返す
  • function_exists — 指定した関数が定義されている場合に true を返す
  • get_defined_functions — 定義済みの全ての関数を配列で返す
  • register_shutdown_function — シャットダウン時に実行する関数を登録する
  • register_tick_function — 各 tick で実行する関数を登録する
  • unregister_tick_function — 各 tick の実行用の関数の登録を解除する


最初の引数で指定したコールバック関数をコールする

  • ≪ 関数処理 関数
  • call_user_func_array ≫
  • PHP Manual
  • 関数処理 関数
  • 最初の引数で指定したコールバック関数をコールする

call_user_func

(PHP 4, PHP 5, PHP 7, PHP 8)

call_user_func — 最初の引数で指定したコールバック関数をコールする

説明

call_user_func(callable $callback, mixed ...$args): mixed

パラメータ callback で指定したユーザー定義のコールバック関数をコールします。

パラメータ

callback

コールする callable。

args

コールバック関数に渡す、ゼロ個以上のパラメータ。

注意:

call_user_func() のパラメータは 参照渡しではないことに注意しましょう。

例1 call_user_func() の例と参照

<?php
error_reporting(E_ALL);
function increment(&$var)
{
$var++;
}

$a = 0;
call_user_func('increment', $a);
echo $a."\n";

// このようにしてもかまいません
call_user_func_array('increment', array(&$a));
echo $a."\n";

// 関数名を変数として使ってもかまいません
$increment = 'increment';
$increment($a);
echo $a."\n";
?>

上の例の出力は以下となります。

Warning: Parameter 1 to increment() expected to be a reference, value given in ...
0
1
2

戻り値

コールバック関数の結果を返します。

例

例2 call_user_func() の例

<?php
function barber($type)
{
echo "$type ですね、わかりました。\n";
}
call_user_func('barber', "マッシュルームカット");
call_user_func('barber', "髭剃り");
?>

上の例の出力は以下となります。

マッシュルームカット ですね、わかりました。
髭剃り ですね、わかりました。

例3 名前空間を使用した call_user_func()

<?php

namespace Foobar;

class Foo {
static public function test() {
print "Hello world!\n";
}
}

call_user_func(__NAMESPACE__ .'\Foo::test');
call_user_func(array(__NAMESPACE__ .'\Foo', 'test'));

?>

上の例の出力は以下となります。

Hello world!
Hello world!

例4 call_user_func() でのクラスメソッドの使用

<?php

class myclass {
static function say_hello()
{
echo "Hello!\n";
}
}

$classname = "myclass";

call_user_func(array($classname, 'say_hello'));
call_user_func($classname .'::say_hello');

$myobject = new myclass();

call_user_func(array($myobject, 'say_hello'));

?>

上の例の出力は以下となります。

Hello!
Hello!
Hello!

例5 call_user_func() でのラムダ関数の使用

<?php
call_user_func(function($arg) { print "[$arg]\n"; }, 'test');
?>

上の例の出力は以下となります。

[test]

注意

注意:

call_user_func() や call_user_func_array() で登録されたコールバックは、 前のコールバックからスローされた例外がキャッチされていない場合はコールされません。

参考

  • call_user_func_array() - パラメータの配列を指定してコールバック関数をコールする
  • is_callable() - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
  • Variable functions
  • ReflectionFunction::invoke() - 関数を起動する
  • ReflectionMethod::invoke() - 実行する


パラメータの配列を指定してコールバック関数をコールする

  • ≪ call_user_func
  • create_function ≫
  • PHP Manual
  • 関数処理 関数
  • パラメータの配列を指定してコールバック関数をコールする

call_user_func_array

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

call_user_func_array — パラメータの配列を指定してコールバック関数をコールする

説明

call_user_func_array(callable $callback, array $args): mixed

args にパラメータを指定して、 callback で指定したユーザー定義関数をコールします。

パラメータ

callback

コールするcallable。

args

コールバック関数に渡すパラメータを指定する配列。

args のキーがすべて数値の場合、 キーは無視され、それぞれの要素が callback の位置を指定した引数として順番に渡されます。

args のキーのいずれかが文字列の場合、 それらの要素は callback の名前付き引数として渡されます。 その場合、名前は配列のキーが使われます。

args の数値のキーが文字列のキーの後に現れたり、 文字列のキーが callback の パラメータの名前にマッチしない場合、致命的なエラーが発生します。

戻り値

コールバック関数の結果、あるいはエラー時に false を返します。

変更履歴

バージョン | 説明
8.0.0 | args のキーは、無視されず、 パラメーター名として解釈されるようになりました。

例

例1 call_user_func_array() の例

<?php
function foobar($arg, $arg2) {
echo __FUNCTION__, " got $arg and $arg2\n";
}
class foo {
function bar($arg, $arg2) {
echo __METHOD__, " got $arg and $arg2\n";
}
}

// foobar() 関数に引数を 2 つ渡してコールします
call_user_func_array("foobar", array("one", "two"));

// $foo->bar() メソッドに引数を 2 つ渡してコールします
$foo = new foo;
call_user_func_array(array($foo, "bar"), array("three", "four"));
?>

上の例の出力は、 たとえば以下のようになります。

foobar got one and two
foo::bar got three and four

例2 call_user_func_array() での名前空間の使用法

<?php

namespace Foobar;

class Foo {
static public function test($name) {
print "Hello {$name}!\n";
}
}

call_user_func_array(__NAMESPACE__ .'\Foo::test', array('Hannes'));

call_user_func_array(array(__NAMESPACE__ .'\Foo', 'test'), array('Philip'));

?>

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!
Hello Philip!

例3 ラムダ関数の使用

<?php

$func = function($arg1, $arg2) {
return $arg1 * $arg2;
};

var_dump(call_user_func_array($func, array(2, 4)));

?>

上の例の出力は以下となります。

int(8)

例4 値の参照渡し

<?php

function mega(&$a){
$a = 55;
echo "function mega \$a=$a\n";
}
$bar = 77;
call_user_func_array('mega',array(&$bar));
echo "global \$bar=$bar\n";

?>

上の例の出力は以下となります。

function mega $a=55
global $bar=55

例5 call_user_func_array() を名前付き引数と一緒に使う

<?php
function foobar($first, $second) {
echo __FUNCTION__, " got $first and $second\n";
}

// foobar() を名前付き引数を使いつつ、位置を指定せずにコールする
call_user_func_array("foobar", array("second" => "two", "first" => "one"));

// foobar() を名前付き引数をひとつだけ使ってコールする
call_user_func_array("foobar", array("foo", "second" => "bar"));

// Fatal error: Cannot use positional argument after named argument
call_user_func_array("foobar", array("first" => "one", "bar"));

?>

上の例の出力は、 たとえば以下のようになります。

foobar got one and two
foobar got foo and bar

Fatal error: Uncaught Error: Cannot use positional argument after named argument

注意

注意:

call_user_func() や call_user_func_array() で登録されたコールバックは、 前のコールバックからスローされた例外がキャッチされていない場合はコールされません。

参考

  • call_user_func() - 最初の引数で指定したコールバック関数をコールする
  • ReflectionFunction::invokeArgs() - 引数を指定して関数を起動する
  • ReflectionMethod::invokeArgs() - 実行する


文字列のコードを評価し、動的に関数を作成する

  • ≪ call_user_func_array
  • forward_static_call ≫
  • PHP Manual
  • 関数処理 関数
  • 文字列のコードを評価し、動的に関数を作成する

create_function

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

create_function — 文字列のコードを評価し、動的に関数を作成する

警告

この関数は PHP 7.2.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

create_function(string $args, string $code): string

指定したパラメータにより動的に関数を作成し、その関数のユニークな名前を返します。

警告

この関数は、内部的に eval() を実行しているので、 eval() と同様にセキュリティ上のリスクがあります。 さらに、パフォーマンスやメモリ使用効率の面でも問題があります。 なぜなら、この関数で作成された関数はグローバルに存在し、 解放できないからです。

この関数ではなく、ネイティブの 無名関数 を使うべきです。

パラメータ

通常、argsには、シングルクオートで括った文字列 を 指定することが推奨されます。 ダブルクオート を使用した場合には、\$somevarのように変数名を 注意深くエスケープする必要があります。

args

関数の引数を、カンマ区切りの文字列で指定します。

code

関数のコード。

戻り値

一意な関数名を表す文字列を返します。 失敗した場合に false を返します。 返される名前には、 印字できない文字("\0") が含まれているので注意して下さい。 よって、この名前を出力したり、 他の文字列に組み込む場合は特別な注意を払うべきです。

例

例1 create_function() や無名関数を使い、動的に関数を作成する

(たとえば) 実行時に取得した情報をもとにして関数を作成するために、動的に作成した関数が使えます。まず create_function() を使ってみます:

<?php
$newfunc = create_function('$a,$b', 'return "ln($a) + ln($b) = " . log($a * $b);');
echo $newfunc(2, M_E) . "\n";
?>

同じコードは、無名関数 でも実現できます。コードや引数は、文字列に含まれていない点に注意して下さい:

<?php
$newfunc = function($a,$b) { return "ln($a) + ln($b) = " . log($a * $b); };
echo $newfunc(2, M_E) . "\n";
?>

上の例の出力は以下となります。

ln(2) + ln(2.718281828459) = 1.6931471805599

例2 create_function() や無名関数を使い、一般的な処理を行う関数を作成する

もしくは、パラメータリストに一連の処理を行うことができる 一般的なハンドラ関数を定義できます:

<?php
function process($var1, $var2, $farr)
{
foreach ($farr as $f) {
echo $f($var1, $var2) . "\n";
}
}

// 数学関数群を作成します
$farr = array(
create_function('$x,$y', 'return "some trig: ".(sin($x) + $x*cos($y));'),
create_function('$x,$y', 'return "a hypotenuse: ".sqrt($x*$x + $y*$y);'),
create_function('$a,$b', 'if ($a >=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;}'),
create_function('$a,$b', "return \"min(b^2+a, a^2,b) = \".min(\$a*\$a+\$b,\$b*\$b+\$a);"),
create_function('$a,$b', 'if ($a > 0 && $b != 0) {return "ln(a)/b = ".log($a)/$b; } else { return false; }')
);

echo "\nUsing the first array of dynamic functions\n";
echo "parameters: 2.3445, M_PI\n";
process(2.3445, M_PI, $farr);

// 文字列処理関数群を作成します
$garr = array(
create_function('$b,$a', 'if (strncmp($a, $b, 3) == 0) return "** \"$a\" '.
'and \"$b\"\n** Look the same to me! (looking at the first 3 chars)";'),
create_function('$a,$b', 'return "CRCs: " . crc32($a) . ", ".crc32($b);'),
create_function('$a,$b', 'return "similar(a,b) = " . similar_text($a, $b, $p) . "($p%)";')
);
echo "\nUsing the second array of dynamic functions\n";
process("Twas brilling and the slithy toves", "Twas the night", $garr);
?>

ここでも、 同じことが 無名関数 で実現できます。 変数名をエスケープする必要がないことに注意して下さい。 なぜなら、文字列に埋め込まれていないからです。

<?php
function process($var1, $var2, $farr)
{
foreach ($farr as $f) {
echo $f($var1, $var2) . "\n";
}
}

// 数学関数群を作成します
$farr = array(
function($x,$y) { return "some trig: ".(sin($x) + $x*cos($y)); },
function($x,$y) { return "a hypotenuse: ".sqrt($x*$x + $y*$y); },
function($a,$b) { if ($a >=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;} },
function($a,$b) { return "min(b^2+a, a^2,b) = " . min($a*$a+$b, $b*$b+$a); },
function($a,$b) { if ($a > 0 && $b != 0) {return "ln(a)/b = ".log($a)/$b; } else { return false; } }
);

echo "\nUsing the first array of dynamic functions\n";
echo "parameters: 2.3445, M_PI\n";
process(2.3445, M_PI, $farr);

// 文字列処理関数群を作成します
$garr = array(
function($b,$a) { if (strncmp($a, $b, 3) == 0) return "** \"$a\" " .
"and \"$b\"\n** Look the same to me! (looking at the first 3 chars)"; },
function($a,$b) { return "CRCs: " . crc32($a) . ", ".crc32($b); },
function($a,$b) { return "similar(a,b) = " . similar_text($a, $b, $p) . "($p%)"; }
);
echo "\nUsing the second array of dynamic functions\n";
process("Twas brilling and the slithy toves", "Twas the night", $garr);
?>

上の例の出力は以下となります。

Using the first array of dynamic functions
parameters: 2.3445, M_PI
some trig: -1.6291725057799
a hypotenuse: 3.9199852871011
b*a^2 = 4.8103313314525
min(b^2+a, a^2,b) = 8.6382729035898
ln(a)/b = 0.27122299212594

Using the second array of dynamic functions
** "Twas the night" and "Twas brilling and the slithy toves"
** Look the same to me! (looking at the first 3 chars)
CRCs: 3569586014, 342550513
similar(a,b) = 11(45.833333333333%)

例3 動的な関数をコールバック関数として使う

おそらく、動的な関数のもっとも一般的な用途は、コールバックに渡すことでしょう。 たとえば array_walk() あるいは usort() などで使用します。

<?php
$av = array("the ", "a ", "that ", "this ");
array_walk($av, create_function('&$v,$k', '$v = $v . "mango";'));
print_r($av);
?>

無名関数 を使うと、下記のようになります:

<?php
$av = array("the ", "a ", "that ", "this ");
array_walk($av, function(&$v,$k) { $v = $v . "mango"; });
print_r($av);
?>

上の例の出力は以下となります。

Array
(
  [0] => the mango
  [1] => a mango
  [2] => that mango
  [3] => this mango
)

create_function() を使い、文字列を長いものから短いものに並べます:

<?php
$sv = array("small", "a big string", "larger", "it is a string thing");
echo "Original:\n";
print_r($sv);
echo "Sorted:\n";
usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);'));
print_r($sv);
?>

無名関数 を使うと、下記のようになります:

<?php
$sv = array("small", "a big string", "larger", "it is a string thing");
echo "Original:\n";
print_r($sv);
echo "Sorted:\n";
usort($sv, function($a,$b) { return strlen($b) - strlen($a); });
print_r($sv);
?>

上の例の出力は以下となります。

Original:
Array
(
  [0] => small
  [1] => a big string
  [2] => larger
  [3] => it is a string thing
)
Sorted:
Array
(
  [0] => it is a string thing
  [1] => a big string
  [2] => larger
  [3] => small
)

参考

  • 無名関数


static メソッドをコールする

  • ≪ create_function
  • forward_static_call_array ≫
  • PHP Manual
  • 関数処理 関数
  • static メソッドをコールする

forward_static_call

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

forward_static_call — static メソッドをコールする

説明

forward_static_call(callable $callback, mixed ...$args): mixed

callback パラメータで指定したユーザー定義の関数あるいはメソッドを、 それに続く引数を指定してコールします。この関数はメソッドのコンテキストでコールしなければなりません。 クラスの外部で使用することはできません。 この関数は 遅延静的束縛 を使います。

パラメータ

callback

コールしたい関数あるいはメソッド。このパラメータは、 クラス名とメソッド名を指定した配列あるいは関数名を指定した文字列となります。

args

関数に渡したいパラメータ。

戻り値

関数の結果、あるいはエラー時に false を返します。

例

例1 forward_static_call() の例

<?php

class A
{
const NAME = 'A';
public static function test() {
$args = func_get_args();
echo static::NAME, " ".join(',', $args)." \n";
}
}

class B extends A
{
const NAME = 'B';

public static function test() {
echo self::NAME, "\n";
forward_static_call(array('A', 'test'), 'more', 'args');
forward_static_call( 'test', 'other', 'args');
}
}

B::test('foo');

function test() {
$args = func_get_args();
echo "C ".join(',', $args)." \n";
}

?>

上の例の出力は以下となります。

B
B more,args
C other,args

参考

  • forward_static_call_array() - static メソッドをコールし、引数を配列で渡す
  • call_user_func_array() - パラメータの配列を指定してコールバック関数をコールする
  • call_user_func() - 最初の引数で指定したコールバック関数をコールする
  • is_callable() - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる


static メソッドをコールし、引数を配列で渡す

  • ≪ forward_static_call
  • func_get_arg ≫
  • PHP Manual
  • 関数処理 関数
  • static メソッドをコールし、引数を配列で渡す

forward_static_call_array

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

forward_static_call_array — static メソッドをコールし、引数を配列で渡す

説明

forward_static_call_array(callable $callback, array $args): mixed

callback パラメータで指定したユーザー定義の関数あるいはメソッドをコールします。 この関数はメソッドのコンテキストでコールしなければなりません。 クラスの外部で使用することはできません。 この関数は 遅延静的束縛 を使います。 転送先のメソッドへのすべての引数は値渡しで、 call_user_func_array() と同様に配列で指定します。

パラメータ

callback

コールしたい関数あるいはメソッド。このパラメータは、 クラス名とメソッド名を指定した配列あるいは関数名を指定した文字列となります。

parameter

このひとつのパラメータに、メソッドに渡すすべてのパラメータを配列で指定します。

注意:

forward_static_call_array() へのパラメータは参照渡しではないことに注意しましょう。

戻り値

関数の結果、あるいはエラー時に false を返します。

例

例1 forward_static_call_array() の例

<?php

class A
{
const NAME = 'A';
public static function test() {
$args = func_get_args();
echo static::NAME, " ".join(',', $args)." \n";
}
}

class B extends A
{
const NAME = 'B';

public static function test() {
echo self::NAME, "\n";
forward_static_call_array(array('A', 'test'), array('more', 'args'));
forward_static_call_array( 'test', array('other', 'args'));
}
}

B::test('foo');

function test() {
$args = func_get_args();
echo "C ".join(',', $args)." \n";
}

?>

上の例の出力は以下となります。

B
B more,args
C other,args

参考

  • forward_static_call() - static メソッドをコールする
  • call_user_func() - 最初の引数で指定したコールバック関数をコールする
  • call_user_func_array() - パラメータの配列を指定してコールバック関数をコールする
  • is_callable() - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる


引数のリストから要素をひとつ返す

  • ≪ forward_static_call_array
  • func_get_args ≫
  • PHP Manual
  • 関数処理 関数
  • 引数のリストから要素をひとつ返す

func_get_arg

(PHP 4, PHP 5, PHP 7, PHP 8)

func_get_arg — 引数のリストから要素をひとつ返す

説明

func_get_arg(int $position): mixed

ユーザーが定義した関数の引数リストから、指定した引数を取得します。

この関数は、 func_num_args()および func_get_args()と組み合わせて使用され、これにより ユーザー定義の関数が可変長の引数リストをとることができるようになります。

パラメータ

position

引数の位置。関数の引数はゼロから数え始めます。

戻り値

指定した引数、あるいはエラー時に false を返します。

エラー / 例外

ユーザー定義関数の外部からコールされた場合、あるいは position が実際に渡された引数の数より多い場合に警告を発生します。

例

例1 func_get_arg() の例

<?php
function foo()
{
$numargs = func_num_args();
echo "引数の数は $numargs\n";
if ($numargs >= 2) {
echo "二番目の引数は " . func_get_arg(1) . " です。\n";
}
}

foo(1, 2, 3);
?>

上の例の出力は以下となります。

引数の数は 3
二番目の引数は 2 です。

例2 func_get_arg() での引数の参照渡しと値渡しの例

<?php
function byVal($arg) {
echo 'As passed : ', var_export(func_get_arg(0)), PHP_EOL;
$arg = 'baz';
echo 'After change : ', var_export(func_get_arg(0)), PHP_EOL;
}

function byRef(&$arg) {
echo 'As passed : ', var_export(func_get_arg(0)), PHP_EOL;
$arg = 'baz';
echo 'After change : ', var_export(func_get_arg(0)), PHP_EOL;
}

$arg = 'bar';
byVal($arg);
byRef($arg);
?>

上の例の出力は以下となります。

As passed : 'bar'
After change : 'baz'
As passed : 'bar'
After change : 'baz'

注意

注意:

PHP 8.0.0 以降における func_*() 関数ファミリは、名前付き引数に関しては、ほぼ透過的に動作するはずです。つまり、渡された全ての引数は位置を指定したかのように扱われ、引数が指定されない場合は、デフォルト値で置き換えられるということです。 この関数は、未知の名前付きの可変長引数を無視します。 未知の名前付き引数は、可変長引数を通じてのみアクセスできます。

注意:

引数をリファレンス渡しにすると、その引数への変更がすべてこの関数の返り値に反映されます。 PHP 7 からは、引数が値渡しされた場合には現在の値も返されるようになりました。

注意: この関数は、渡された引数のみのコピーを返します。 デフォルトの (渡されていない) 引数については関知しません。

参考

  • ... 構文
  • func_get_args() - 関数の引数リストを配列として返す
  • func_num_args() - 関数に渡された引数の数を返す


関数の引数リストを配列として返す

  • ≪ func_get_arg
  • func_num_args ≫
  • PHP Manual
  • 関数処理 関数
  • 関数の引数リストを配列として返す

func_get_args

(PHP 4, PHP 5, PHP 7, PHP 8)

func_get_args — 関数の引数リストを配列として返す

説明

func_get_args(): array

関数の引数リストを配列で取得します。

この関数は func_num_args() および func_get_arg() と組み合わせて使用され、 これによりユーザー定義の章において可変長の引数リストを使用することができるようになります。

パラメータ

この関数にはパラメータはありません。

戻り値

配列を返します。この配列の各要素は、 現在のユーザー定義関数の引数リストにおける対応するメンバのコピーとなります。

エラー / 例外

ユーザー定義関数の外部からコールされた際に警告を発生します。

例

例1 func_get_args() の例

<?php
function foo()
{
$numargs = func_num_args();
echo "引数の数: $numargs \n";
if ($numargs >= 2) {
echo "二番目の引数は: " . func_get_arg(1) . " です。\n";
}
$arg_list = func_get_args();
for ($i = 0; $i < $numargs; $i++) {
echo "引数 $i は: " . $arg_list[$i] . " です。\n";
}
}

foo(1, 2, 3);
?>

上の例の出力は以下となります。

引数の数: 3
二番目の引数は: 2 です。
引数 0 は: 1 です。
引数 1 は: 2 です。
引数 2 は: 3 です。

例2 func_get_args() での引数の参照渡しと値渡しの例

<?php
function byVal($arg) {
echo 'As passed : ', var_export(func_get_args()), PHP_EOL;
$arg = 'baz';
echo 'After change : ', var_export(func_get_args()), PHP_EOL;
}

function byRef(&$arg) {
echo 'As passed : ', var_export(func_get_args()), PHP_EOL;
$arg = 'baz';
echo 'After change : ', var_export(func_get_args()), PHP_EOL;
}

$arg = 'bar';
byVal($arg);
byRef($arg);
?>

上の例の出力は以下となります。

As passed : array (
0 => 'bar',
)
After change : array (
0 => 'baz',
)
As passed : array (
0 => 'bar',
)
After change : array (
0 => 'baz',
)

注意

注意:

PHP 8.0.0 以降における func_*() 関数ファミリは、名前付き引数に関しては、ほぼ透過的に動作するはずです。つまり、渡された全ての引数は位置を指定したかのように扱われ、引数が指定されない場合は、デフォルト値で置き換えられるということです。 この関数は、未知の名前付きの可変長引数を無視します。 未知の名前付き引数は、可変長引数を通じてのみアクセスできます。

注意:

引数をリファレンス渡しにすると、その引数への変更がすべてこの関数の返り値に反映されます。 PHP 7 からは、引数が値渡しされた場合には現在の値も返されるようになりました。

注意: この関数は、渡された引数のみのコピーを返します。 デフォルトの（渡されていない）引数については考慮しません。

参考

  • ... 構文
  • func_get_arg() - 引数のリストから要素をひとつ返す
  • func_num_args() - 関数に渡された引数の数を返す
  • ReflectionFunctionAbstract::getParameters() - パラメータを取得する


関数に渡された引数の数を返す

  • ≪ func_get_args
  • function_exists ≫
  • PHP Manual
  • 関数処理 関数
  • 関数に渡された引数の数を返す

func_num_args

(PHP 4, PHP 5, PHP 7, PHP 8)

func_num_args — 関数に渡された引数の数を返す

説明

func_num_args(): int

関数に渡された引数の数を取得します。

この関数は func_get_arg() および func_get_args() と組み合わせて使用され、 ユーザー定義関数において可変長の引数リストを使用することができるようになります。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のユーザー定義関数に渡された引数の数を返します。

エラー / 例外

ユーザー定義関数の外部からコールされた場合に警告を発生します。

例

例1 func_num_args() の例

<?php
function foo()
{
echo "引数の数: ", func_num_args(), PHP_EOL;
}

foo(1, 2, 3);
?>

上の例の出力は以下となります。

引数の数: 3

注意

注意:

PHP 8.0.0 以降における func_*() 関数ファミリは、名前付き引数に関しては、ほぼ透過的に動作するはずです。つまり、渡された全ての引数は位置を指定したかのように扱われ、引数が指定されない場合は、デフォルト値で置き換えられるということです。 この関数は、未知の名前付きの可変長引数を無視します。 未知の名前付き引数は、可変長引数を通じてのみアクセスできます。

参考

  • ... 構文
  • func_get_arg() - 引数のリストから要素をひとつ返す
  • func_get_args() - 関数の引数リストを配列として返す
  • ReflectionFunctionAbstract::getNumberOfParameters() - パラメータ数を取得する


指定した関数が定義されている場合に true を返す

  • ≪ func_num_args
  • get_defined_functions ≫
  • PHP Manual
  • 関数処理 関数
  • 指定した関数が定義されている場合に true を返す

function_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

function_exists — 指定した関数が定義されている場合に true を返す

説明

function_exists(string $function): bool

組み込みの内部関数およびユーザー定義関数の中から、 function で指定した名前の関数を探します。

パラメータ

function

関数名を表す文字列。

戻り値

function が存在し、関数である場合に true、 それ以外の場合に false を返します。

注意:

この関数は、 include_once や echo のような言語構造については false を返します。

例

例1 function_exists() の例

<?php
if (function_exists('imap_open')) {
echo "IMAP 関数が利用可能です。<br />\n";
} else {
echo "IMAP 関数は利用できません。<br />\n";
}
?>

注意

注意:

ある関数がそれ自体設定やコンパイルオプションの問題で使用できない 場合でもその関数の名前が存在する可能性があることに注意してください (例としては image 関数などがあります)。

参考

  • method_exists() - クラスメソッドが存在するかどうかを確認する
  • is_callable() - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
  • get_defined_functions() - 定義済みの全ての関数を配列で返す
  • class_exists() - クラスが定義済みかどうかを確認する
  • extension_loaded() - ある拡張モジュールがロードされているかどうかを調べる


定義済みの全ての関数を配列で返す

  • ≪ function_exists
  • register_shutdown_function ≫
  • PHP Manual
  • 関数処理 関数
  • 定義済みの全ての関数を配列で返す

get_defined_functions

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

get_defined_functions — 定義済みの全ての関数を配列で返す

説明

get_defined_functions(bool $exclude_disabled = true): array

すべての定義済み関数を配列で返します。

パラメータ

exclude_disabled

無効な関数を戻り値から除外するかどうかを指定します。

戻り値

この関数は、組込 (内部) 関数およびユーザー定義関数を共に含む定義済み の全ての関数のリストを有する多次元配列を返します。内部関数は、 $arr["internal"]、ユーザー定義関数は $arr["user"] によりアクセス可能となります (以下の例を参照ください)。

変更履歴

バージョン | 説明
8.0.0 | exclude_disabled のデフォルト値が、 false から true に変更されました。
7.0.15, 7.1.1 | exclude_disabled パラメータが追加されました。

例

例1 get_defined_functions() の例

<?php
function myrow($id, $data)
{
return "<tr><th>$id</th><td>$data</td></tr>\n";
}

$arr = get_defined_functions();

print_r($arr);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [internal] => Array
        (
            [0] => zend_version
            [1] => func_num_args
            [2] => func_get_arg
            [3] => func_get_args
            [4] => strlen
            [5] => strcmp
            [6] => strncmp
            ...
            [750] => bcscale
            [751] => bccomp
        )

    [user] => Array
        (
            [0] => myrow
        )

)

参考

  • function_exists() - 指定した関数が定義されている場合に true を返す
  • get_defined_vars() - 全ての定義済の変数を配列で返す
  • get_defined_constants() - すべての定数の名前とその値を連想配列として返す
  • get_declared_classes() - 定義済のクラスの名前を配列として返す


シャットダウン時に実行する関数を登録する

  • ≪ get_defined_functions
  • register_tick_function ≫
  • PHP Manual
  • 関数処理 関数
  • シャットダウン時に実行する関数を登録する

register_shutdown_function

(PHP 4, PHP 5, PHP 7, PHP 8)

register_shutdown_function — シャットダウン時に実行する関数を登録する

説明

register_shutdown_function(callable $callback, mixed ...$args): void

スクリプト処理が完了したとき、あるいは exit() がコールされたときに実行するコールバック関数を登録します。

register_shutdown_function() は複数回コールする ことが可能で、登録された順に関数がコールされます。 登録した関数内で exit() をコールした場合、 処理はそこで終了してその他のシャットダウン関数はコールされません。

シャットダウン関数は、 別のシャットダウン関数をキューの最後に追加するために、 register_shutdown_function() そのものをコールしても構いません。

パラメータ

callback

登録するコールバック。

シャットダウン時のコールバックは、リクエストの一部として実行されます。 したがって、コールバック関数からも出力を送信できるし、出力バッファにもアクセスできます。

args

シャットダウン関数にパラメータを渡すには、ここで追加のパラメータを渡します。

戻り値

値を返しません。

例

例1 register_shutdown_function() の例

<?php
function shutdown()
{
// これがシャットダウン関数で、
// スクリプトの処理が完了する前に
// ここで何らかの操作をすることができます

echo 'Script executed with success', PHP_EOL;
}

register_shutdown_function('shutdown');
?>

注意

注意:

Apache などいくつかの Web サーバーでは、スクリプトの実行時ディレクトリを シャットダウン関数内で変更可能です。

注意:

SIGTERM あるいは SIGKILL でプロセスが終了した場合は、シャットダウン関数を実行しません。 SIGKILL を横取りすることはできませんが、SIGTERM 用のハンドラは pcntl_signal() で登録できます。ここで exit() を使えば、きれいに終わらせることができます。

注意:

シャットダウン関数は、 max_execution_time の経過とは別に実行されます。 つまり、プロセスが非常に長時間実行された後に終了しても、 シャットダウン関数はコールされます。 さらに、 シャットダウン関数を実行中に max_execution_time が経過しても、実行中の関数は終了しません。

参考

  • auto_append_file
  • exit() - メッセージを出力し、現在のスクリプトを終了する
  • fastcgi_finish_request() - すべてのレスポンスデータをクライアントにフラッシュする
  • 接続処理


各 tick で実行する関数を登録する

  • ≪ register_shutdown_function
  • unregister_tick_function ≫
  • PHP Manual
  • 関数処理 関数
  • 各 tick で実行する関数を登録する

register_tick_function

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

register_tick_function — 各 tick で実行する関数を登録する

説明

register_tick_function(callable $callback, mixed ...$args): bool

tick がコールされた際に実行される callback という名前の関数を登録します。

パラメータ

callback

登録する関数

args

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 register_tick_function() の例

<?php
declare(ticks=1);

// 関数をコールバックとして使用します
register_tick_function('my_function', true);

// オブジェクトのメソッドを使用します
$object = new my_class();
register_tick_function(array($object, 'my_method'), true);
?>

参考

  • declare
  • unregister_tick_function() - 各 tick の実行用の関数の登録を解除する


各 tick の実行用の関数の登録を解除する

  • ≪ register_tick_function
  • Quickhash ≫
  • PHP Manual
  • 関数処理 関数
  • 各 tick の実行用の関数の登録を解除する

unregister_tick_function

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

unregister_tick_function — 各 tick の実行用の関数の登録を解除する

説明

unregister_tick_function(callable $callback): void

callback という名前の関数の登録を解除します。 これにより、tick がコールされた 場合でもこの関数は実行されなくなります。

パラメータ

callback

登録を解除する関数

戻り値

値を返しません。

参考

  • register_tick_function() - 各 tick で実行する関数を登録する


Quickhash

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
  • QuickHashIntSet — The QuickHashIntSet class
    • QuickHashIntSet::add — This method adds a new entry to the set
    • QuickHashIntSet::__construct — Creates a new QuickHashIntSet object
    • QuickHashIntSet::delete — This method deletes an entry from the set
    • QuickHashIntSet::exists — This method checks whether a key is part of the set
    • QuickHashIntSet::getSize — Returns the number of elements in the set
    • QuickHashIntSet::loadFromFile — This factory method creates a set from a file
    • QuickHashIntSet::loadFromString — This factory method creates a set from a string
    • QuickHashIntSet::saveToFile — This method stores an in-memory set to disk
    • QuickHashIntSet::saveToString — This method returns a serialized version of the set
  • QuickHashIntHash — The QuickHashIntHash class
    • QuickHashIntHash::add — This method adds a new entry to the hash
    • QuickHashIntHash::__construct — Creates a new QuickHashIntHash object
    • QuickHashIntHash::delete — This method deletes an entry from the hash
    • QuickHashIntHash::exists — This method checks whether a key is part of the hash
    • QuickHashIntHash::get — This method retrieves a value from the hash by its key
    • QuickHashIntHash::getSize — Returns the number of elements in the hash
    • QuickHashIntHash::loadFromFile — This factory method creates a hash from a file
    • QuickHashIntHash::loadFromString — This factory method creates a hash from a string
    • QuickHashIntHash::saveToFile — This method stores an in-memory hash to disk
    • QuickHashIntHash::saveToString — This method returns a serialized version of the hash
    • QuickHashIntHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
    • QuickHashIntHash::update — This method updates an entry in the hash with a new value
  • QuickHashStringIntHash — The QuickHashStringIntHash class
    • QuickHashStringIntHash::add — This method adds a new entry to the hash
    • QuickHashStringIntHash::__construct — Creates a new QuickHashStringIntHash object
    • QuickHashStringIntHash::delete — This method deletes an entry from the hash
    • QuickHashStringIntHash::exists — This method checks whether a key is part of the hash
    • QuickHashStringIntHash::get — This method retrieves a value from the hash by its key
    • QuickHashStringIntHash::getSize — Returns the number of elements in the hash
    • QuickHashStringIntHash::loadFromFile — This factory method creates a hash from a file
    • QuickHashStringIntHash::loadFromString — This factory method creates a hash from a string
    • QuickHashStringIntHash::saveToFile — This method stores an in-memory hash to disk
    • QuickHashStringIntHash::saveToString — This method returns a serialized version of the hash
    • QuickHashStringIntHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
    • QuickHashStringIntHash::update — This method updates an entry in the hash with a new value
  • QuickHashIntStringHash — The QuickHashIntStringHash class
    • QuickHashIntStringHash::add — This method adds a new entry to the hash
    • QuickHashIntStringHash::__construct — Creates a new QuickHashIntStringHash object
    • QuickHashIntStringHash::delete — This method deletes an entry from the hash
    • QuickHashIntStringHash::exists — This method checks whether a key is part of the hash
    • QuickHashIntStringHash::get — This method retrieves a value from the hash by its key
    • QuickHashIntStringHash::getSize — Returns the number of elements in the hash
    • QuickHashIntStringHash::loadFromFile — This factory method creates a hash from a file
    • QuickHashIntStringHash::loadFromString — This factory method creates a hash from a string
    • QuickHashIntStringHash::saveToFile — This method stores an in-memory hash to disk
    • QuickHashIntStringHash::saveToString — This method returns a serialized version of the hash
    • QuickHashIntStringHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
    • QuickHashIntStringHash::update — This method updates an entry in the hash with a new value


はじめに

The quickhash extension contains a set of specific strongly-typed classes to deal with specific set and hash implementations.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Quickhash
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


  • ≪ インストール/設定
  • インストール手順 ≫
  • PHP Manual
  • インストール/設定
  • 要件

要件

This extension requires no additional libraries.


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/quickhash


例

例1 Quickhash Example

<?php
$set = new QuickHashIntSet( 1024, QuickHashIntSet::CHECK_FOR_DUPES );
$set->add( 1 );
$set->add( 3 );

var_dump( $set->exists( 3 ) );
var_dump( $set->exists( 4 ) );

$set->saveToFile( "/tmp/test-set.set" );

$newSet = QuickHashIntSet::loadFromFile(
"/tmp/test-set.set"
);

var_dump( $newSet->exists( 3 ) );
var_dump( $newSet->exists( 4 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)
bool(true)
bool(false)

例2 Quickhash ArrayAccess Example

<?php
$hash = new QuickHashIntHash( 64 );

// Adding and updating hash entries.
$hash[3] = 145926;
$hash[3] = 1415926;
$hash[2] = 72;

// Checking if keys exist
var_dump( isset( $hash[3] ) );

// Removing hash entries
unset( $hash[2] );

// Retrieving the value stored for a hash
echo $hash[3], "\n";
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
1415926

例3 Quickhash Iterator Example

<?php
$hash = new QuickHashIntHash( 64 );

// Adding hash entries.
$hash[1] = 145926;
$hash[2] = 1415926;
$hash[3] = 72;
$hash[4] = 712314;
$hash[5] = -4234;

foreach( $hash as $key => $value )
{
echo $key, ' => ', $value, "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

5 => -4234
4 => 712314
1 => 145926
2 => 1415926
3 => 72

例4 Quickhash String Values Example

<?php
$hash = new QuickHashIntStringHash( 64 );

// Adding hash entries.
$hash[1] = "one million four hundred fifteen thousand nine hundred twenty six";
$hash->add( 2, "one more" );

foreach( $hash as $key => $value )
{
echo $key, ' => ', $value, "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

1 => one million four hundred fifteen thousand nine hundred twenty six
2 => one more


The QuickHashIntSet class

(PECL quickhash >= Unknown)

はじめに

This class wraps around a set containing integer numbers.

Sets can also be iterated over with foreach as the Iterator interface is implemented as well. The order of which elements are returned in is not guaranteed.

クラス概要

class QuickHashIntSet {
/* 定数 */
const int CHECK_FOR_DUPES = 1;
const int DO_NOT_USE_ZEND_ALLOC = 2;
const int HASHER_NO_HASH = 256;
const int HASHER_JENKINS1 = 512;
const int HASHER_JENKINS2 = 1024;
/* メソッド */
public add(int $key): bool
public __construct(int $size, int $options = ?)
public delete(int $key): bool
public exists(int $key): bool
publicgetSize(): int
public static loadFromFile(string $filename, int $size = ?, int $options = ?): QuickHashIntSet
public static loadFromString(string $contents, int $size = ?, int $options = ?): QuickHashIntSet
public saveToFile(string $filename): void
public saveToString(): string
}

定義済み定数

QuickHashIntSet::CHECK_FOR_DUPES

If enabled, adding duplicate elements to a set (through either QuickHashIntSet::add() or QuickHashIntSet::loadFromFile()) will result in those elements to be dropped from the set. This will take up extra time, so only used when it is required.

QuickHashIntSet::DO_NOT_USE_ZEND_ALLOC

Disables the use of PHP's internal memory manager for internal set structures. With this option enabled, internal allocations will not count towards the memory_limit settings.

QuickHashIntSet::HASHER_NO_HASH

Selects to not use a hashing function, but merely use a modulo to find the bucket list index. This is not faster than normal hashing, and gives more collisions.

QuickHashIntSet::HASHER_JENKINS1

This is the default hashing function to turn the integer hashes into bucket list indexes.

QuickHashIntSet::HASHER_JENKINS2

Selects a variant hashing algorithm.

目次

  • QuickHashIntSet::add — This method adds a new entry to the set
  • QuickHashIntSet::__construct — Creates a new QuickHashIntSet object
  • QuickHashIntSet::delete — This method deletes an entry from the set
  • QuickHashIntSet::exists — This method checks whether a key is part of the set
  • QuickHashIntSet::getSize — Returns the number of elements in the set
  • QuickHashIntSet::loadFromFile — This factory method creates a set from a file
  • QuickHashIntSet::loadFromString — This factory method creates a set from a string
  • QuickHashIntSet::saveToFile — This method stores an in-memory set to disk
  • QuickHashIntSet::saveToString — This method returns a serialized version of the set


This method adds a new entry to the set

  • ≪ QuickHashIntSet
  • QuickHashIntSet::__construct ≫
  • PHP Manual
  • QuickHashIntSet
  • This method adds a new entry to the set

QuickHashIntSet::add

(PECL quickhash >= Unknown)

QuickHashIntSet::add — This method adds a new entry to the set

説明

public QuickHashIntSet::add(int $key): bool

This method adds a new entry to the set, and returns whether the entry was added. Entries are by default always added unless QuickHashIntSet::CHECK_FOR_DUPES has been passed when the set was created.

パラメータ

key

The key of the entry to add.

戻り値

true when the entry was added, and false if the entry was not added.

例

例1 QuickHashIntSet::add() example

<?php
echo "without dupe checking\n";
$set = new QuickHashIntSet( 1024 );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );

echo "\nwith dupe checking\n";
$set = new QuickHashIntSet( 1024, QuickHashIntSet::CHECK_FOR_DUPES );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );
?>

上の例の出力は、 たとえば以下のようになります。

without dupe checking
bool(false)
bool(true)
bool(true)
bool(true)

with dupe checking
bool(false)
bool(true)
bool(true)
bool(false)


Creates a new QuickHashIntSet object

  • ≪ QuickHashIntSet::add
  • QuickHashIntSet::delete ≫
  • PHP Manual
  • QuickHashIntSet
  • Creates a new QuickHashIntSet object

QuickHashIntSet::__construct

(PECL quickhash >= Unknown)

QuickHashIntSet::__construct — Creates a new QuickHashIntSet object

説明

public QuickHashIntSet::__construct(int $size, int $options = ?)

This constructor creates a new QuickHashIntSet. The size is the amount of bucket lists to create. The more lists there are, the less collisions you will have. Options are also supported.

パラメータ

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The options that you can pass in are: QuickHashIntSet::CHECK_FOR_DUPES, which makes sure no duplicate entries are added to the set; QuickHashIntSet::DO_NOT_USE_ZEND_ALLOC to not use PHP's internal memory manager as well as one of QuickHashIntSet::HASHER_NO_HASH, QuickHashIntSet::HASHER_JENKINS1 or QuickHashIntSet::HASHER_JENKINS2. These last three configure which hashing algorithm to use. All options can be combined using bitmasks.

戻り値

Returns a new QuickHashIntSet object.

例

例1 QuickHashIntSet::__construct() example

<?php
var_dump( new QuickHashIntSet( 1024 ) );
var_dump( new QuickHashIntSet( 1024, QuickHashIntSet::CHECK_FOR_DUPES ) );
var_dump(
new QuickHashIntSet(
1024,
QuickHashIntSet::DO_NOT_USE_ZEND_ALLOC | QuickHashIntSet::HASHER_JENKINS2
)
);
?>


This method deletes an entry from the set

  • ≪ QuickHashIntSet::__construct
  • QuickHashIntSet::exists ≫
  • PHP Manual
  • QuickHashIntSet
  • This method deletes an entry from the set

QuickHashIntSet::delete

(PECL quickhash >= Unknown)

QuickHashIntSet::delete — This method deletes an entry from the set

説明

public QuickHashIntSet::delete(int $key): bool

This method deletes an entry from the set, and returns whether the entry was deleted or not. Associated memory structures will not be freed immediately, but rather when the set itself is freed.

パラメータ

key

The key of the entry to delete.

戻り値

true when the entry was deleted, and false if the entry was not deleted.

例

例1 QuickHashIntSet::delete() example

<?php
$set = new QuickHashIntSet( 1024 );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );
var_dump( $set->delete( 4 ) );
var_dump( $set->exists( 4 ) );
var_dump( $set->delete( 4 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
bool(true)
bool(false)
bool(false)


This method checks whether a key is part of the set

  • ≪ QuickHashIntSet::delete
  • QuickHashIntSet::getSize ≫
  • PHP Manual
  • QuickHashIntSet
  • This method checks whether a key is part of the set

QuickHashIntSet::exists

(PECL quickhash >= Unknown)

QuickHashIntSet::exists — This method checks whether a key is part of the set

説明

public QuickHashIntSet::exists(int $key): bool

This method checks whether an entry with the provided key exists in the set.

パラメータ

key

The key of the entry to check for whether it exists in the set.

戻り値

Returns true when the entry was found, or false when the entry is not found.

例

例1 QuickHashIntSet::exists() example

<?php
//generate 200000 elements
$array = range( 0, 199999 );
$existingEntries = array_rand( array_flip( $array ), 180000 );
$testForEntries = array_rand( array_flip( $array ), 1000 );
$foundCount = 0;

echo "Creating set: ", microtime( true ), "\n";
$set = new QuickHashIntSet( 100000 );
echo "Adding elements: ", microtime( true ), "\n";
foreach( $existingEntries as $key )
{
$set->add( $key );
}

echo "Doing 1000 tests: ", microtime( true ), "\n";
foreach( $testForEntries as $key )
{
$foundCount += $set->exists( $key );
}
echo "Done, $foundCount found: ", microtime( true ), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Creating set: 1263588703.0748
Adding elements: 1263588703.0757
Doing 1000 tests: 1263588703.7851
Done, 898 found: 1263588703.7897


Returns the number of elements in the set

  • ≪ QuickHashIntSet::exists
  • QuickHashIntSet::loadFromFile ≫
  • PHP Manual
  • QuickHashIntSet
  • Returns the number of elements in the set

QuickHashIntSet::getSize

(PECL quickhash >= Unknown)

QuickHashIntSet::getSize — Returns the number of elements in the set

説明

publicQuickHashIntSet::getSize(): int

Returns the number of elements in the set.

パラメータ

この関数にはパラメータはありません。

戻り値

The number of elements in the set.

例

例1 QuickHashIntSet::getSize() example

<?php
$set = new QuickHashIntSet( 8 );
var_dump( $set->add( 2 ) );
var_dump( $set->add( 3 ) );
var_dump( $set->getSize() );
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
int(2)


This factory method creates a set from a file

  • ≪ QuickHashIntSet::getSize
  • QuickHashIntSet::loadFromString ≫
  • PHP Manual
  • QuickHashIntSet
  • This factory method creates a set from a file

QuickHashIntSet::loadFromFile

(PECL quickhash >= Unknown)

QuickHashIntSet::loadFromFile — This factory method creates a set from a file

説明

public static QuickHashIntSet::loadFromFile(string $filename, int $size = ?, int $options = ?): QuickHashIntSet

This factory method creates a new set from a definition file on disk. The file format consists of 32 bit signed integers packed together in the Endianness that the system that the code runs on uses.

パラメータ

filename

The filename of the file to read the set from.

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the set, rounded up to the nearest power of two with a maximum limit of 4194304.

戻り値

Returns a new QuickHashIntSet.

例

例1 QuickHashIntSet::loadFromFile() example

<?php
$file = dirname( __FILE__ ) . "/simple.set";
$set = QuickHashIntSet::loadFromFile(
$file,
QuickHashIntSet::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
printf( "Key %3d (%2x) is %s\n",
$key, $key,
$set->exists( $key ) ? 'set' : 'unset'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Key   0 ( 0) is unset
Key   1 ( 1) is set
Key   2 ( 2) is set
Key   3 ( 3) is set
Key   4 ( 4) is unset
Key   5 ( 5) is set
Key   6 ( 6) is unset
Key   7 ( 7) is set
Key   8 ( 8) is unset
Key   9 ( 9) is unset
Key  10 ( a) is unset
Key  11 ( b) is set
Key  12 ( c) is unset
Key  13 ( d) is set
Key  14 ( e) is unset
Key  15 ( f) is unset


This factory method creates a set from a string

  • ≪ QuickHashIntSet::loadFromFile
  • QuickHashIntSet::saveToFile ≫
  • PHP Manual
  • QuickHashIntSet
  • This factory method creates a set from a string

QuickHashIntSet::loadFromString

(PECL quickhash >= Unknown)

QuickHashIntSet::loadFromString — This factory method creates a set from a string

説明

public static QuickHashIntSet::loadFromString(string $contents, int $size = ?, int $options = ?): QuickHashIntSet

This factory method creates a new set from a definition in a string. The file format consists of 32 bit signed integers packed together in the Endianness that the system that the code runs on uses.

パラメータ

contents

The string containing a serialized format of the set.

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the set, rounded up to the nearest power of two automatically limited from 64 to 4194304.

戻り値

Returns a new QuickHashIntSet.

例

例1 QuickHashIntSet::loadFromString() example

<?php
$contents = file_get_contents( dirname( __FILE__ ) . "/simple.set" );
$set = QuickHashIntSet::loadFromString(
$contents,
QuickHashIntSet::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
printf( "Key %3d (%2x) is %s\n",
$key, $key,
$set->exists( $key ) ? 'set' : 'unset'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Key   0 ( 0) is unset
Key   1 ( 1) is set
Key   2 ( 2) is set
Key   3 ( 3) is set
Key   4 ( 4) is unset
Key   5 ( 5) is set
Key   6 ( 6) is unset
Key   7 ( 7) is set
Key   8 ( 8) is unset
Key   9 ( 9) is unset
Key  10 ( a) is unset
Key  11 ( b) is set
Key  12 ( c) is unset
Key  13 ( d) is set
Key  14 ( e) is unset
Key  15 ( f) is unset


This method stores an in-memory set to disk

  • ≪ QuickHashIntSet::loadFromString
  • QuickHashIntSet::saveToString ≫
  • PHP Manual
  • QuickHashIntSet
  • This method stores an in-memory set to disk

QuickHashIntSet::saveToFile

(PECL quickhash >= Unknown)

QuickHashIntSet::saveToFile — This method stores an in-memory set to disk

説明

public QuickHashIntSet::saveToFile(string $filename): void

This method stores an existing set to a file on disk, in the same format that QuickHashIntSet::loadFromFile() can read.

パラメータ

filename

The filename of the file to store the hash in.

戻り値

値を返しません。

例

例1 QuickHashIntSet::saveToFile() example

<?php
$set = new QuickHashIntSet( 1024 );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );

$set->saveToFile( '/tmp/test.set' );
?>


This method returns a serialized version of the set

  • ≪ QuickHashIntSet::saveToFile
  • QuickHashIntHash ≫
  • PHP Manual
  • QuickHashIntSet
  • This method returns a serialized version of the set

QuickHashIntSet::saveToString

(PECL quickhash >= Unknown)

QuickHashIntSet::saveToString — This method returns a serialized version of the set

説明

public QuickHashIntSet::saveToString(): string

This method returns a serialized version of the set in the same format that QuickHashIntSet::loadFromString() can read.

パラメータ

この関数にはパラメータはありません。

戻り値

This method returns a string containing a serialized format of the set. Each element is stored as a four byte value in the Endianness that the current system uses.

例

例1 QuickHashIntSet::saveToString() example

<?php
$set = new QuickHashIntSet( 1024 );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );
var_dump( $set->exists( 4 ) );
var_dump( $set->add( 4 ) );

var_dump( $set->saveToString() );
?>


The QuickHashIntHash class

(PECL quickhash >= Unknown)

はじめに

This class wraps around a hash containing integer numbers, where the values are also integer numbers. Hashes are also available as implementation of the ArrayAccess interface.

Hashes can also be iterated over with foreach as the Iterator interface is implemented as well. The order of which elements are returned in is not guaranteed.

クラス概要

class QuickHashIntHash {
/* 定数 */
const int CHECK_FOR_DUPES = 1;
const int DO_NOT_USE_ZEND_ALLOC = 2;
const int HASHER_NO_HASH = 256;
const int HASHER_JENKINS1 = 512;
const int HASHER_JENKINS2 = 1024;
/* メソッド */
public add(int $key, int $value = ?): bool
public __construct(int $size, int $options = ?)
public delete(int $key): bool
public exists(int $key): bool
public get(int $key): int
public getSize(): int
public static loadFromFile(string $filename, int $options = ?): QuickHashIntHash
public static loadFromString(string $contents, int $options = ?): QuickHashIntHash
public saveToFile(string $filename): void
public saveToString(): string
public set(int $key, int $value): bool
public update(int $key, int $value): bool
}

定義済み定数

QuickHashIntHash::CHECK_FOR_DUPES

If enabled, adding duplicate elements to a set (through either QuickHashIntHash::add() or QuickHashIntHash::loadFromFile()) will result in those elements to be dropped from the set. This will take up extra time, so only used when it is required.

QuickHashIntHash::DO_NOT_USE_ZEND_ALLOC

Disables the use of PHP's internal memory manager for internal set structures. With this option enabled, internal allocations will not count towards the memory_limit settings.

QuickHashIntHash::HASHER_NO_HASH

Selects to not use a hashing function, but merely use a modulo to find the bucket list index. This is not faster than normal hashing, and gives more collisions.

QuickHashIntHash::HASHER_JENKINS1

This is the default hashing function to turn the integer hashes into bucket list indexes.

QuickHashIntHash::HASHER_JENKINS2

Selects a variant hashing algorithm.

目次

  • QuickHashIntHash::add — This method adds a new entry to the hash
  • QuickHashIntHash::__construct — Creates a new QuickHashIntHash object
  • QuickHashIntHash::delete — This method deletes an entry from the hash
  • QuickHashIntHash::exists — This method checks whether a key is part of the hash
  • QuickHashIntHash::get — This method retrieves a value from the hash by its key
  • QuickHashIntHash::getSize — Returns the number of elements in the hash
  • QuickHashIntHash::loadFromFile — This factory method creates a hash from a file
  • QuickHashIntHash::loadFromString — This factory method creates a hash from a string
  • QuickHashIntHash::saveToFile — This method stores an in-memory hash to disk
  • QuickHashIntHash::saveToString — This method returns a serialized version of the hash
  • QuickHashIntHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
  • QuickHashIntHash::update — This method updates an entry in the hash with a new value


This method adds a new entry to the hash

  • ≪ QuickHashIntHash
  • QuickHashIntHash::__construct ≫
  • PHP Manual
  • QuickHashIntHash
  • This method adds a new entry to the hash

QuickHashIntHash::add

(PECL quickhash >= Unknown)

QuickHashIntHash::add — This method adds a new entry to the hash

説明

public QuickHashIntHash::add(int $key, int $value = ?): bool

This method adds a new entry to the hash, and returns whether the entry was added. Entries are by default always added unless QuickHashIntHash::CHECK_FOR_DUPES has been passed when the hash was created.

パラメータ

key

The key of the entry to add.

value

The optional value of the entry to add. If no value is specified, 1 will be used.

戻り値

true when the entry was added, and false if the entry was not added.

例

例1 QuickHashIntHash::add() example

<?php
echo "without dupe checking\n";
$hash = new QuickHashIntHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, 22 ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, 12 ) );

echo "\nwith dupe checking\n";
$hash = new QuickHashIntHash( 1024, QuickHashIntHash::CHECK_FOR_DUPES );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, 78 ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, 9 ) );

echo "\ndefault value\n";
var_dump( $hash->add( 5 ) );
var_dump( $hash->get( 5 ) );
?>

上の例の出力は、 たとえば以下のようになります。

without dupe checking
bool(false)
bool(false)
bool(true)
bool(true)
int(22)
bool(true)

with dupe checking
bool(false)
bool(false)
bool(true)
bool(true)
int(78)
bool(false)

default value
bool(true)
int(1)


Creates a new QuickHashIntHash object

  • ≪ QuickHashIntHash::add
  • QuickHashIntHash::delete ≫
  • PHP Manual
  • QuickHashIntHash
  • Creates a new QuickHashIntHash object

QuickHashIntHash::__construct

(PECL quickhash >= Unknown)

QuickHashIntHash::__construct — Creates a new QuickHashIntHash object

説明

public QuickHashIntHash::__construct(int $size, int $options = ?)

This constructor creates a new QuickHashIntHash. The size is the amount of bucket lists to create. The more lists there are, the less collisions you will have. Options are also supported.

パラメータ

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 64 to 4194304.

options

The options that you can pass in are: QuickHashIntHash::CHECK_FOR_DUPES, which makes sure no duplicate entries are added to the hash; QuickHashIntHash::DO_NOT_USE_ZEND_ALLOC to not use PHP's internal memory manager as well as one of QuickHashIntHash::HASHER_NO_HASH, QuickHashIntHash::HASHER_JENKINS1 or QuickHashIntHash::HASHER_JENKINS2. These last three configure which hashing algorithm to use. All options can be combined using bitmasks.

戻り値

Returns a new QuickHashIntHash object.

例

例1 QuickHashIntHash::__construct() example

<?php
var_dump( new QuickHashIntHash( 1024 ) );
var_dump( new QuickHashIntHash( 1024, QuickHashIntHash::CHECK_FOR_DUPES ) );
var_dump(
new QuickHashIntHash(
1024,
QuickHashIntHash::DO_NOT_USE_ZEND_ALLOC | QuickHashIntHash::HASHER_JENKINS2
)
);
?>


This method deletes an entry from the hash

  • ≪ QuickHashIntHash::__construct
  • QuickHashIntHash::exists ≫
  • PHP Manual
  • QuickHashIntHash
  • This method deletes an entry from the hash

QuickHashIntHash::delete

(PECL quickhash >= Unknown)

QuickHashIntHash::delete — This method deletes an entry from the hash

説明

public QuickHashIntHash::delete(int $key): bool

This method deletes an entry from the hash, and returns whether the entry was deleted or not. Associated memory structures will not be freed immediately, but rather when the hash itself is freed.

Elements can not be deleted when the hash is used in an iterator. The method will not throw an exception, but simply return false like would happen with any other deletion failure.

パラメータ

key

The key of the entry to delete.

戻り値

true when the entry was deleted, and false if the entry was not deleted.

例

例1 QuickHashIntHash::delete() example

<?php
$hash = new QuickHashIntHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, 5 ) );
var_dump( $hash->delete( 4 ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->delete( 4 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
bool(true)
bool(false)
bool(false)


This method checks whether a key is part of the hash

  • ≪ QuickHashIntHash::delete
  • QuickHashIntHash::get ≫
  • PHP Manual
  • QuickHashIntHash
  • This method checks whether a key is part of the hash

QuickHashIntHash::exists

(PECL quickhash >= Unknown)

QuickHashIntHash::exists — This method checks whether a key is part of the hash

説明

public QuickHashIntHash::exists(int $key): bool

This method checks whether an entry with the provided key exists in the hash.

パラメータ

key

The key of the entry to check for whether it exists in the hash.

戻り値

Returns true when the entry was found, or false when the entry is not found.

例

例1 QuickHashIntHash::exists() example

<?php
//generate 200000 elements
$array = range( 0, 199999 );
$existingEntries = array_rand( array_flip( $array ), 180000 );
$testForEntries = array_rand( array_flip( $array ), 1000 );
$foundCount = 0;

echo "Creating hash: ", microtime( true ), "\n";
$hash = new QuickHashIntHash( 100000 );
echo "Adding elements: ", microtime( true ), "\n";
foreach( $existingEntries as $key )
{
$hash->add( $key, 56 );
}

echo "Doing 1000 tests: ", microtime( true ), "\n";
foreach( $testForEntries as $key )
{
$foundCount += $hash->exists( $key );
}
echo "Done, $foundCount found: ", microtime( true ), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Creating hash: 1263588703.0748
Adding elements: 1263588703.0757
Doing 1000 tests: 1263588703.7851
Done, 898 found: 1263588703.7897


This method retrieves a value from the hash by its key

  • ≪ QuickHashIntHash::exists
  • QuickHashIntHash::getSize ≫
  • PHP Manual
  • QuickHashIntHash
  • This method retrieves a value from the hash by its key

QuickHashIntHash::get

(PECL quickhash >= Unknown)

QuickHashIntHash::get — This method retrieves a value from the hash by its key

説明

public QuickHashIntHash::get(int $key): int

This method retrieves a value from the hash by its key.

パラメータ

key

The key of the entry to retrieve.

戻り値

The value if the key exists, or null if the key wasn't part of the hash.

例

例1 QuickHashIntHash::get() example

<?php
$hash = new QuickHashIntHash( 8 );
var_dump( $hash->get( 1 ) );

var_dump( $hash->add( 2 ) );
var_dump( $hash->get( 2 ) );

var_dump( $hash->add( 3, 5 ) );
var_dump( $hash->get( 3 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
int(1)
bool(true)
int(5)


Returns the number of elements in the hash

  • ≪ QuickHashIntHash::get
  • QuickHashIntHash::loadFromFile ≫
  • PHP Manual
  • QuickHashIntHash
  • Returns the number of elements in the hash

QuickHashIntHash::getSize

(PECL quickhash >= Unknown)

QuickHashIntHash::getSize — Returns the number of elements in the hash

説明

public QuickHashIntHash::getSize(): int

Returns the number of elements in the hash.

パラメータ

この関数にはパラメータはありません。

戻り値

The number of elements in the hash.

例

例1 QuickHashIntHash::getSize() example

<?php
$hash = new QuickHashIntHash( 8 );
var_dump( $hash->add( 2 ) );
var_dump( $hash->add( 3, 5 ) );
var_dump( $hash->getSize() );
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
int(2)


This factory method creates a hash from a file

  • ≪ QuickHashIntHash::getSize
  • QuickHashIntHash::loadFromString ≫
  • PHP Manual
  • QuickHashIntHash
  • This factory method creates a hash from a file

QuickHashIntHash::loadFromFile

(PECL quickhash >= Unknown)

QuickHashIntHash::loadFromFile — This factory method creates a hash from a file

説明

public static QuickHashIntHash::loadFromFile(string $filename, int $options = ?): QuickHashIntHash

This factory method creates a new hash from a definition file on disk. The file format consists of a signature 'QH\0x11\0', the number of elements as a 32 bit signed integer in system Endianness, followed by 32 bit signed integers packed together in the Endianness that the system that the code runs on uses. For each hash element there are two 32 bit signed integers stored. The first of each element is the key, and the second is the value belonging to the key. An example could be:

例1 QuickHash IntHash file format

00000000  51 48 11 00 02 00 00 00  01 00 00 00 01 00 00 00  |QH..............|
00000010  03 00 00 00 09 00 00 00                           |........|
00000018

例2 QuickHash IntHash file format

header signature ('QH'; key type: 1; value type: 1; filler: \0x00)
00000000  51 48 11 00

number of elements:
00000004  02 00 00 00

data string:
00000000  01 00 00 00 01 00 00 00  03 00 00 00 09 00 00 00

key/value 1 (key = 1, value = 1)
01 00 00 00  01 00 00 00

key/value 2 (key = 3, value = 9)
03 00 00 00  09 00 00 00

パラメータ

filename

The filename of the file to read the hash from.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the hash, rounded up to the nearest power of two with a maximum limit of 4194304.

戻り値

Returns a new QuickHashIntHash.

例

例3 QuickHashIntHash::loadFromFile() example

<?php
$file = dirname( __FILE__ ) . "/simple.hash";
$hash = QuickHashIntHash::loadFromFile(
$file,
QuickHashIntHash::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
printf( "Key %3d (%2x) is %s\n",
$key, $key,
$hash->exists( $key ) ? 'set' : 'unset'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Key   0 ( 0) is unset
Key   1 ( 1) is set
Key   2 ( 2) is set
Key   3 ( 3) is set
Key   4 ( 4) is unset
Key   5 ( 5) is set
Key   6 ( 6) is unset
Key   7 ( 7) is set
Key   8 ( 8) is unset
Key   9 ( 9) is unset
Key  10 ( a) is unset
Key  11 ( b) is set
Key  12 ( c) is unset
Key  13 ( d) is set
Key  14 ( e) is unset
Key  15 ( f) is unset


This factory method creates a hash from a string

  • ≪ QuickHashIntHash::loadFromFile
  • QuickHashIntHash::saveToFile ≫
  • PHP Manual
  • QuickHashIntHash
  • This factory method creates a hash from a string

QuickHashIntHash::loadFromString

(PECL quickhash >= Unknown)

QuickHashIntHash::loadFromString — This factory method creates a hash from a string

説明

public static QuickHashIntHash::loadFromString(string $contents, int $options = ?): QuickHashIntHash

This factory method creates a new hash from a definition in a string. The file format consists of 32 bit signed integers packed together in the Endianness that the system that the code runs on uses. For each element there are two 32 bit signed integers stored. The first of each element is the key, and the second is the value belonging to the key.

パラメータ

contents

The string containing a serialized format of the hash.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the hash, rounded up to the nearest power of two with a maximum limit of 4194304.

戻り値

Returns a new QuickHashIntHash.

例

例1 QuickHashIntHash::loadFromString() example

<?php
$contents = file_get_contents( dirname( __FILE__ ) . "/simple.hash" );
$hash = QuickHashIntHash::loadFromString(
$contents,
QuickHashIntHash::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
printf( "Key %3d (%2x) is %s\n",
$key, $key,
$hash->exists( $key ) ? 'set' : 'unset'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Key   0 ( 0) is unset
Key   1 ( 1) is set
Key   2 ( 2) is set
Key   3 ( 3) is set
Key   4 ( 4) is unset
Key   5 ( 5) is set
Key   6 ( 6) is unset
Key   7 ( 7) is set
Key   8 ( 8) is unset
Key   9 ( 9) is unset
Key  10 ( a) is unset
Key  11 ( b) is set
Key  12 ( c) is unset
Key  13 ( d) is set
Key  14 ( e) is unset
Key  15 ( f) is unset


This method stores an in-memory hash to disk

  • ≪ QuickHashIntHash::loadFromString
  • QuickHashIntHash::saveToString ≫
  • PHP Manual
  • QuickHashIntHash
  • This method stores an in-memory hash to disk

QuickHashIntHash::saveToFile

(PECL quickhash >= Unknown)

QuickHashIntHash::saveToFile — This method stores an in-memory hash to disk

説明

public QuickHashIntHash::saveToFile(string $filename): void

This method stores an existing hash to a file on disk, in the same format that QuickHashIntHash::loadFromFile() can read.

パラメータ

filename

The filename of the file to store the hash in.

戻り値

値を返しません。

例

例1 QuickHashIntHash::saveToFile() example

<?php
$hash = new QuickHashIntHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, 43 ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, 52 ) );

$hash->saveToFile( '/tmp/test.hash' );
?>


This method returns a serialized version of the hash

  • ≪ QuickHashIntHash::saveToFile
  • QuickHashIntHash::set ≫
  • PHP Manual
  • QuickHashIntHash
  • This method returns a serialized version of the hash

QuickHashIntHash::saveToString

(PECL quickhash >= Unknown)

QuickHashIntHash::saveToString — This method returns a serialized version of the hash

説明

public QuickHashIntHash::saveToString(): string

This method returns a serialized version of the hash in the same format that QuickHashIntHash::loadFromString() can read.

パラメータ

この関数にはパラメータはありません。

戻り値

This method returns a string containing a serialized format of the hash. Each element is stored as a four byte value in the Endianness that the current system uses.

例

例1 QuickHashIntHash::saveToString() example

<?php
$hash = new QuickHashIntHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, 34 ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, 55 ) );

var_dump( $hash->saveToString() );
?>


This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

  • ≪ QuickHashIntHash::saveToString
  • QuickHashIntHash::update ≫
  • PHP Manual
  • QuickHashIntHash
  • This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

QuickHashIntHash::set

(PECL quickhash >= Unknown)

QuickHashIntHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

説明

public QuickHashIntHash::set(int $key, int $value): bool

This method tries to update an entry with a new value. In case the entry did not yet exist, it will instead add a new entry. It returns whether the entry was added or update. If there are duplicate keys, only the first found element will get an updated value. Use QuickHashIntHash::CHECK_FOR_DUPES during hash creation to prevent duplicate keys from being part of the hash.

パラメータ

key

The key of the entry to add or update.

value

The new value to set the entry with.

戻り値

2 if the entry was found and updated, 1 if the entry was newly added or 0 if there was an error.

例

例1 QuickHashIntHash::set() example

<?php
$hash = new QuickHashIntHash( 1024 );

echo "Set->Add\n";
var_dump( $hash->get( 46692 ) );
var_dump( $hash->set( 46692, 16091 ) );
var_dump( $hash->get( 46692 ) );

echo "Set->Update\n";
var_dump( $hash->set( 46692, 29906 ) );
var_dump( $hash->get( 46692 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
int(2)
int(16091)
Set->Update
int(1)
int(29906)


This method updates an entry in the hash with a new value

  • ≪ QuickHashIntHash::set
  • QuickHashStringIntHash ≫
  • PHP Manual
  • QuickHashIntHash
  • This method updates an entry in the hash with a new value

QuickHashIntHash::update

(PECL quickhash >= Unknown)

QuickHashIntHash::update — This method updates an entry in the hash with a new value

説明

public QuickHashIntHash::update(int $key, int $value): bool

This method updates an entry with a new value, and returns whether the entry was update. If there are duplicate keys, only the first found element will get an updated value. Use QuickHashIntHash::CHECK_FOR_DUPES during hash creation to prevent duplicate keys from being part of the hash.

パラメータ

key

The key of the entry to update.

value

The new value to update the entry with.

戻り値

true when the entry was found and updated, and false if the entry was not part of the hash already.

例

例1 QuickHashIntHash::update() example

<?php
$hash = new QuickHashIntHash( 1024 );

var_dump( $hash->add( 141421, 173205 ) );
var_dump( $hash->update( 141421, 223606 ) );
var_dump( $hash->get( 141421 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
int(223606)


The QuickHashStringIntHash class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

This class wraps around a hash containing strings, where the values are integer numbers. Hashes are also available as implementation of the ArrayAccess interface.

Hashes can also be iterated over with foreach as the Iterator interface is implemented as well. The order of which elements are returned in is not guaranteed.

クラス概要

class QuickHashStringIntHash {
/* 定数 */
const int CHECK_FOR_DUPES = 1;
const int DO_NOT_USE_ZEND_ALLOC = 2;
/* メソッド */
public add(string $key, int $value): bool
public __construct(int $size, int $options = 0)
public delete(string $key): bool
public exists(string $key): bool
public get(string $key): mixed
public getSize(): int
public static loadFromFile(string $filename, int $size = 0, int $options = 0): QuickHashStringIntHash
public static loadFromString(string $contents, int $size = 0, int $options = 0): QuickHashStringIntHash
public saveToFile(string $filename): void
public saveToString(): string
public set(string $key, int $value): int
public update(string $key, int $value): bool
}

定義済み定数

QuickHashStringIntHash::CHECK_FOR_DUPES

If enabled, adding duplicate elements to a set (through either QuickHashStringIntHash::add() or QuickHashStringIntHash::loadFromFile()) will result in those elements to be dropped from the set. This will take up extra time, so only used when it is required.

QuickHashStringIntHash::DO_NOT_USE_ZEND_ALLOC

Disables the use of PHP's internal memory manager for internal set structures. With this option enabled, internal allocations will not count towards the memory_limit settings.

目次

  • QuickHashStringIntHash::add — This method adds a new entry to the hash
  • QuickHashStringIntHash::__construct — Creates a new QuickHashStringIntHash object
  • QuickHashStringIntHash::delete — This method deletes an entry from the hash
  • QuickHashStringIntHash::exists — This method checks whether a key is part of the hash
  • QuickHashStringIntHash::get — This method retrieves a value from the hash by its key
  • QuickHashStringIntHash::getSize — Returns the number of elements in the hash
  • QuickHashStringIntHash::loadFromFile — This factory method creates a hash from a file
  • QuickHashStringIntHash::loadFromString — This factory method creates a hash from a string
  • QuickHashStringIntHash::saveToFile — This method stores an in-memory hash to disk
  • QuickHashStringIntHash::saveToString — This method returns a serialized version of the hash
  • QuickHashStringIntHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
  • QuickHashStringIntHash::update — This method updates an entry in the hash with a new value


This method adds a new entry to the hash

  • ≪ QuickHashStringIntHash
  • QuickHashStringIntHash::__construct ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method adds a new entry to the hash

QuickHashStringIntHash::add

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::add — This method adds a new entry to the hash

説明

public QuickHashStringIntHash::add(string $key, int $value): bool

This method adds a new entry to the hash, and returns whether the entry was added. Entries are by default always added unless QuickHashStringIntHash::CHECK_FOR_DUPES has been passed when the hash was created.

パラメータ

key

The key of the entry to add.

value

The value of the entry to add.

戻り値

true when the entry was added, and false if the entry was not added.

例

例1 QuickHashStringIntHash::add() example

<?php
echo "without dupe checking\n";
$hash = new QuickHashStringIntHash( 1024 );
var_dump( $hash );
var_dump( $hash->exists( "four" ) );
var_dump( $hash->get( "four" ) );
var_dump( $hash->add( "four", 22 ) );
var_dump( $hash->exists( "four" ) );
var_dump( $hash->get( "four" ) );
var_dump( $hash->add( "four", 12 ) );

echo "\nwith dupe checking\n";
$hash = new QuickHashStringIntHash( 1024, QuickHashStringIntHash::CHECK_FOR_DUPES );
var_dump( $hash );
var_dump( $hash->exists( "four" ) );
var_dump( $hash->get( "four" ) );
var_dump( $hash->add( "four", 78 ) );
var_dump( $hash->exists( "four" ) );
var_dump( $hash->get( "four" ) );
var_dump( $hash->add( "four", 9 ) );
?>

上の例の出力は、 たとえば以下のようになります。

without dupe checking
object(QuickHashStringIntHash)#1 (0) {
}
bool(false)
bool(false)
bool(true)
bool(true)
int(22)
bool(true)

with dupe checking
object(QuickHashStringIntHash)#2 (0) {
}
bool(false)
bool(false)
bool(true)
bool(true)
int(78)
bool(false)


Creates a new QuickHashStringIntHash object

  • ≪ QuickHashStringIntHash::add
  • QuickHashStringIntHash::delete ≫
  • PHP Manual
  • QuickHashStringIntHash
  • Creates a new QuickHashStringIntHash object

QuickHashStringIntHash::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::__construct — Creates a new QuickHashStringIntHash object

説明

public QuickHashStringIntHash::__construct(int $size, int $options = 0)

This constructor creates a new QuickHashStringIntHash. The size is the amount of bucket lists to create. The more lists there are, the less collisions you will have. Options are also supported.

パラメータ

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 64 to 4194304.

options

The options that you can pass in are: QuickHashStringIntHash::CHECK_FOR_DUPES, which makes sure no duplicate entries are added to the hash and QuickHashStringIntHash::DO_NOT_USE_ZEND_ALLOC to not use PHP's internal memory manager.

戻り値

Returns a new QuickHashStringIntHash object.

例

例1 QuickHashStringIntHash::__construct() example

<?php
var_dump( new QuickHashStringIntHash( 1024 ) );
var_dump( new QuickHashStringIntHash( 1024, QuickHashStringIntHash::CHECK_FOR_DUPES ) );
?>


This method deletes an entry from the hash

  • ≪ QuickHashStringIntHash::__construct
  • QuickHashStringIntHash::exists ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method deletes an entry from the hash

QuickHashStringIntHash::delete

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::delete — This method deletes an entry from the hash

説明

public QuickHashStringIntHash::delete(string $key): bool

This method deletes an entry from the hash, and returns whether the entry was deleted or not. Associated memory structures will not be freed immediately, but rather when the hash itself is freed.

Elements can not be deleted when the hash is used in an iterator. The method will not throw an exception, but simply return false like would happen with any other deletion failure.

パラメータ

key

The key of the entry to delete.

戻り値

true when the entry was deleted, and false if the entry was not deleted.

例

例1 QuickHashStringIntHash::delete() example

<?php
$hash = new QuickHashStringIntHash( 1024 );
var_dump( $hash->exists( 'four' ) );
var_dump( $hash->add( 'four', 5 ) );
var_dump( $hash->get( 'four' ) );
var_dump( $hash->delete( 'four' ) );
var_dump( $hash->exists( 'four' ) );
var_dump( $hash->get( 'four' ) );
var_dump( $hash->delete( 'four' ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
int(5)
bool(true)
bool(false)
bool(false)
bool(false)


This method checks whether a key is part of the hash

  • ≪ QuickHashStringIntHash::delete
  • QuickHashStringIntHash::get ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method checks whether a key is part of the hash

QuickHashStringIntHash::exists

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::exists — This method checks whether a key is part of the hash

説明

public QuickHashStringIntHash::exists(string $key): bool

This method checks whether an entry with the provided key exists in the hash.

パラメータ

key

The key of the entry to check for whether it exists in the hash.

戻り値

Returns true when the entry was found, or false when the entry is not found.


This method retrieves a value from the hash by its key

  • ≪ QuickHashStringIntHash::exists
  • QuickHashStringIntHash::getSize ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method retrieves a value from the hash by its key

QuickHashStringIntHash::get

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::get — This method retrieves a value from the hash by its key

説明

public QuickHashStringIntHash::get(string $key): mixed

This method retrieves a value from the hash by its key.

パラメータ

key

The key of the entry to retrieve.

戻り値

The value if the key exists, or null if the key wasn't part of the hash.

例

例1 QuickHashStringIntHash::get() example

<?php
$hash = new QuickHashStringIntHash( 8 );
var_dump( $hash->get( "one" ) );

var_dump( $hash->add( "two", 2 ) );
var_dump( $hash->get( "two" ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
int(2)


Returns the number of elements in the hash

  • ≪ QuickHashStringIntHash::get
  • QuickHashStringIntHash::loadFromFile ≫
  • PHP Manual
  • QuickHashStringIntHash
  • Returns the number of elements in the hash

QuickHashStringIntHash::getSize

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::getSize — Returns the number of elements in the hash

説明

public QuickHashStringIntHash::getSize(): int

Returns the number of elements in the hash.

パラメータ

この関数にはパラメータはありません。

戻り値

The number of elements in the hash.

例

例1 QuickHashStringIntHash::getSize() example

<?php
$hash = new QuickHashStringIntHash( 8 );
var_dump( $hash->add( "two", 2 ) );
var_dump( $hash->add( "three", 5 ) );
var_dump( $hash->getSize() );
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
int(2)


This factory method creates a hash from a file

  • ≪ QuickHashStringIntHash::getSize
  • QuickHashStringIntHash::loadFromString ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This factory method creates a hash from a file

QuickHashStringIntHash::loadFromFile

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::loadFromFile — This factory method creates a hash from a file

説明

public static QuickHashStringIntHash::loadFromFile(string $filename, int $size = 0, int $options = 0): QuickHashStringIntHash

This factory method creates a new hash from a definition file on disk. The file format consists of a signature 'QH\0x21\0', the number of elements as a 32 bit signed integer in system Endianness, an unsigned 32 bit integer containing the number of element data to follow in characters. This element data contains all the strings. The follows another signed 32 bit integer containing the number of bucket lists. After the header and the strings, the elements follow. They are ordered by bucket list so that the keys don't have to be hashed in order to restore the hash. For each bucket list, the following information is stored (all as 32 bit integers): the bucket list index, the number of elements in that list, and then in pairs of two unsigned 32 bit integers the elements, where the first one is the index into the string list containing the keys, and the second one the value. An example could be:

例1 QuickHash StringIntHash file format

00000000  51 48 21 00 02 00 00 00  09 00 00 00 40 00 00 00  |QH!.........@...|
00000010  4f 4e 45 00 4e 49 4e 45  00 07 00 00 00 01 00 00  |ONE.NINE........|
00000020  00 00 00 00 00 01 00 00  00 2f 00 00 00 01 00 00  |........./......|
00000030  00 04 00 00 00 03 00 00  00                       |.........|
00000039

例2 QuickHash IntHash file format

header signature ('QH'; key type: 2; value type: 1; filler: \0x00)
00000000  51 48 21 00

number of elements:
00000004  02 00 00 00

length of string values (9 characters):
00000008  09 00 00 00

number of hash bucket lists (this is configured for hashes as argument to the
constructor normally, 64 in this case):
0000000C  40 00 00 00

string values:
00000010  4f 4e 45 00 4e 49 4e 45  00

bucket lists:
  bucket list 1 (with key 7, and 1 element):
    header:
    07 00 00 00 01 00 00 00
    elements (key index: 0 ('ONE'), value = 0):
    00 00 00 00 01 00 00 00
  bucket list 2 (with key 0x2f, and 1 element):
    header:
    2f 00 00 00 01 00 00 00
    elements (key index: 4 ('NINE'), value = 3):
    04 00 00 00 03 00 00 00

パラメータ

filename

The filename of the file to read the hash from.

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The same options that the class' constructor takes; except that the size option is ignored. It is read from the file format (unlike the QuickHashIntHash and QuickHashIntStringHash classes, where it is automatically calculated from the number of entries in the hash.)

戻り値

Returns a new QuickHashStringIntHash.

例

例3 QuickHashStringIntHash::loadFromFile() example

<?php
$file = dirname( __FILE__ ) . "/simple.hash.string";
$hash = QuickHashStringIntHash::loadFromFile(
$file,
QuickHashStringIntHash::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
$i = 48712 + $key * 1631;
$k = base_convert( $i, 10, 36 );
echo $k, ' => ', $hash->get( $k ), "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

11l4 => 48712
12uf => 50343
143q => 51974
15d1 => 53605
16mc => 55236
17vn => 56867
194y => 58498
1ae9 => 60129
1bnk => 61760
1cwv => 63391
1e66 => 65022
1ffh => 66653
1gos => 68284
1hy3 => 69915
1j7e => 71546
1kgp => 73177


This factory method creates a hash from a string

  • ≪ QuickHashStringIntHash::loadFromFile
  • QuickHashStringIntHash::saveToFile ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This factory method creates a hash from a string

QuickHashStringIntHash::loadFromString

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::loadFromString — This factory method creates a hash from a string

説明

public static QuickHashStringIntHash::loadFromString(string $contents, int $size = 0, int $options = 0): QuickHashStringIntHash

This factory method creates a new hash from a definition in a string. The format is the same as the one used in "loadFromFile".

パラメータ

contents

The string containing a serialized format of the hash.

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the hash, rounded up to the nearest power of two with a maximum limit of 4194304.

戻り値

Returns a new QuickHashStringIntHash.

例

例1 QuickHashStringIntHash::loadFromString() example

<?php
$contents = file_get_contents( dirname( __FILE__ ) . "/simple.hash.string" );
$hash = QuickHashStringIntHash::loadFromString(
$contents,
QuickHashStringIntHash::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
$i = 48712 + $key * 1631;
$k = base_convert( $i, 10, 36 );
echo $k, ' => ', $hash->get( $k ), "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

11l4 => 48712
12uf => 50343
143q => 51974
15d1 => 53605
16mc => 55236
17vn => 56867
194y => 58498
1ae9 => 60129
1bnk => 61760
1cwv => 63391
1e66 => 65022
1ffh => 66653
1gos => 68284
1hy3 => 69915
1j7e => 71546
1kgp => 73177


This method stores an in-memory hash to disk

  • ≪ QuickHashStringIntHash::loadFromString
  • QuickHashStringIntHash::saveToString ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method stores an in-memory hash to disk

QuickHashStringIntHash::saveToFile

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::saveToFile — This method stores an in-memory hash to disk

説明

public QuickHashStringIntHash::saveToFile(string $filename): void

This method stores an existing hash to a file on disk, in the same format that loadFromFile() can read.

パラメータ

filename

The filename of the file to store the hash in.

戻り値

値を返しません。

例

例1 QuickHashStringIntHash::saveToFile() example

<?php
$hash = new QuickHashStringIntHash( 1024 );
var_dump( $hash->add( "forty three", 42 ) );
var_dump( $hash->add( "fifty two", 52 ) );

$hash->saveToFile( '/tmp/test.hash.string' );
?>


This method returns a serialized version of the hash

  • ≪ QuickHashStringIntHash::saveToFile
  • QuickHashStringIntHash::set ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method returns a serialized version of the hash

QuickHashStringIntHash::saveToString

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::saveToString — This method returns a serialized version of the hash

説明

public QuickHashStringIntHash::saveToString(): string

This method returns a serialized version of the hash in the same format that QuickHashStringIntHash::loadFromString() can read.

パラメータ

この関数にはパラメータはありません。

戻り値

This method returns a serialized format of an existing hash, in the same format that QuickHashStringIntHash::loadFromString() can read.

例

例1 QuickHashStringIntHash::saveToString() example

<?php
$hash = new QuickHashStringIntHash( 1024 );
var_dump( $hash->add( "forty three", 42 ) );
var_dump( $hash->add( "fifty two", 52 ) );

var_dump( $hash->saveToString() );
?>


This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

  • ≪ QuickHashStringIntHash::saveToString
  • QuickHashStringIntHash::update ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

QuickHashStringIntHash::set

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

説明

public QuickHashStringIntHash::set(string $key, int $value): int

This method tries to update an entry with a new value. In case the entry did not yet exist, it will instead add a new entry. It returns whether the entry was added or update. If there are duplicate keys, only the first found element will get an updated value. Use QuickHashStringIntHash::CHECK_FOR_DUPES during hash creation to prevent duplicate keys from being part of the hash.

パラメータ

key

The key of the entry to add or update.

value

The value of the entry to add. If a non-string is passed, it will be converted to a string automatically if possible.

戻り値

2 if the entry was found and updated, 1 if the entry was newly added or 0 if there was an error.

例

例1 QuickHashStringIntHash::set() example

<?php
$hash = new QuickHashStringIntHash( 1024 );

echo "Set->Add\n";
var_dump( $hash->get( "forty six thousand six hundred ninety two" ) );
var_dump( $hash->set( "forty six thousand six hundred ninety two", 16091 ) );
var_dump( $hash->get( "forty six thousand six hundred ninety two" ) );

echo "Set->Update\n";
var_dump( $hash->set( "forty six thousand six hundred ninety two", 29906 ) );
var_dump( $hash->get( "forty six thousand six hundred ninety two" ) );
?>

上の例の出力は、 たとえば以下のようになります。

Set->Add
bool(false)
int(2)
int(16091)
Set->Update
int(1)
int(29906)


This method updates an entry in the hash with a new value

  • ≪ QuickHashStringIntHash::set
  • QuickHashIntStringHash ≫
  • PHP Manual
  • QuickHashStringIntHash
  • This method updates an entry in the hash with a new value

QuickHashStringIntHash::update

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

QuickHashStringIntHash::update — This method updates an entry in the hash with a new value

説明

public QuickHashStringIntHash::update(string $key, int $value): bool

This method updates an entry with a new value, and returns whether the entry was update. If there are duplicate keys, only the first found element will get an updated value. Use QuickHashStringIntHash::CHECK_FOR_DUPES during hash creation to prevent duplicate keys from being part of the hash.

パラメータ

key

The key of the entry to update.

value

The new value for the entry. If a non-string is passed, it will be converted to a string automatically if possible.

戻り値

true when the entry was found and updated, and false if the entry was not part of the hash already.

例

例1 QuickHashStringIntHash::update() example

<?php
$hash = new QuickHashStringIntHash( 1024 );

$hash->add( 'six', 314159265 );
$hash->add( "a lot", 314159265 );

echo $hash->get( 'six' ), "\n";
echo $hash->get( 'a lot' ), "\n";

var_dump( $hash->update( 'a lot', 314159266 ) );
var_dump( $hash->update( "a lot plus one", 314159999 ) );

echo $hash->get( 'six' ), "\n";
echo $hash->get( 'a lot' ), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

314159265
314159265
bool(true)
bool(false)
314159265
314159266


The QuickHashIntStringHash class

(PECL quickhash >= Unknown)

はじめに

This class wraps around a hash containing integer numbers, where the values are strings. Hashes are also available as implementation of the ArrayAccess interface.

Hashes can also be iterated over with foreach as the Iterator interface is implemented as well. The order of which elements are returned in is not guaranteed.

クラス概要

class QuickHashIntStringHash {
/* 定数 */
const int CHECK_FOR_DUPES = 1;
const int DO_NOT_USE_ZEND_ALLOC = 2;
const int HASHER_NO_HASH = 256;
const int HASHER_JENKINS1 = 512;
const int HASHER_JENKINS2 = 1024;
/* メソッド */
public add(int $key, string $value): bool
public __construct(int $size, int $options = 0)
public delete(int $key): bool
public exists(int $key): bool
public get(int $key): mixed
public getSize(): int
public static loadFromFile(string $filename, int $size = 0, int $options = 0): QuickHashIntStringHash
public static loadFromString(string $contents, int $size = 0, int $options = 0): QuickHashIntStringHash
public saveToFile(string $filename): void
public saveToString(): string
public set(int $key, string $value): int
public update(int $key, string $value): bool
}

定義済み定数

QuickHashIntStringHash::CHECK_FOR_DUPES

If enabled, adding duplicate elements to a set (through either QuickHashIntStringHash::add() or QuickHashIntStringHash::loadFromFile()) will result in those elements to be dropped from the set. This will take up extra time, so only used when it is required.

QuickHashIntStringHash::DO_NOT_USE_ZEND_ALLOC

Disables the use of PHP's internal memory manager for internal set structures. With this option enabled, internal allocations will not count towards the memory_limit settings.

QuickHashIntStringHash::HASHER_NO_HASH

Selects to not use a hashing function, but merely use a modulo to find the bucket list index. This is not faster than normal hashing, and gives more collisions.

QuickHashIntStringHash::HASHER_JENKINS1

This is the default hashing function to turn the integer hashes into bucket list indexes.

QuickHashIntStringHash::HASHER_JENKINS2

Selects a variant hashing algorithm.

目次

  • QuickHashIntStringHash::add — This method adds a new entry to the hash
  • QuickHashIntStringHash::__construct — Creates a new QuickHashIntStringHash object
  • QuickHashIntStringHash::delete — This method deletes an entry from the hash
  • QuickHashIntStringHash::exists — This method checks whether a key is part of the hash
  • QuickHashIntStringHash::get — This method retrieves a value from the hash by its key
  • QuickHashIntStringHash::getSize — Returns the number of elements in the hash
  • QuickHashIntStringHash::loadFromFile — This factory method creates a hash from a file
  • QuickHashIntStringHash::loadFromString — This factory method creates a hash from a string
  • QuickHashIntStringHash::saveToFile — This method stores an in-memory hash to disk
  • QuickHashIntStringHash::saveToString — This method returns a serialized version of the hash
  • QuickHashIntStringHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
  • QuickHashIntStringHash::update — This method updates an entry in the hash with a new value


This method adds a new entry to the hash

  • ≪ QuickHashIntStringHash
  • QuickHashIntStringHash::__construct ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method adds a new entry to the hash

QuickHashIntStringHash::add

(PECL quickhash >= Unknown)

QuickHashIntStringHash::add — This method adds a new entry to the hash

説明

public QuickHashIntStringHash::add(int $key, string $value): bool

This method adds a new entry to the hash, and returns whether the entry was added. Entries are by default always added unless QuickHashIntStringHash::CHECK_FOR_DUPES has been passed when the hash was created.

パラメータ

key

The key of the entry to add.

value

The value of the entry to add. If a non-string is passed, it will be converted to a string automatically if possible.

戻り値

true when the entry was added, and false if the entry was not added.

例

例1 QuickHashIntStringHash::add() example

<?php
echo "without dupe checking\n";
$hash = new QuickHashIntStringHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, "twenty two" ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, "twelve" ) );

echo "\nwith dupe checking\n";
$hash = new QuickHashIntStringHash( 1024, QuickHashIntStringHash::CHECK_FOR_DUPES );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, "seventy eight" ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->get( 4 ) );
var_dump( $hash->add( 4, "nine" ) );
?>

上の例の出力は、 たとえば以下のようになります。

without dupe checking
bool(false)
bool(false)
bool(true)
bool(true)
string(10) "twenty two"
bool(true)

with dupe checking
bool(false)
bool(false)
bool(true)
bool(true)
string(13) "seventy eight"
bool(false)


Creates a new QuickHashIntStringHash object

  • ≪ QuickHashIntStringHash::add
  • QuickHashIntStringHash::delete ≫
  • PHP Manual
  • QuickHashIntStringHash
  • Creates a new QuickHashIntStringHash object

QuickHashIntStringHash::__construct

(PECL quickhash >= Unknown)

QuickHashIntStringHash::__construct — Creates a new QuickHashIntStringHash object

説明

public QuickHashIntStringHash::__construct(int $size, int $options = 0)

This constructor creates a new QuickHashIntStringHash. The size is the amount of bucket lists to create. The more lists there are, the less collisions you will have. Options are also supported.

パラメータ

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 64 to 4194304.

options

The options that you can pass in are: QuickHashIntStringHash::CHECK_FOR_DUPES, which makes sure no duplicate entries are added to the hash; QuickHashIntStringHash::DO_NOT_USE_ZEND_ALLOC to not use PHP's internal memory manager as well as one of QuickHashIntStringHash::HASHER_NO_HASH, QuickHashIntStringHash::HASHER_JENKINS1 or QuickHashIntStringHash::HASHER_JENKINS2. These last three configure which hashing algorithm to use. All options can be combined using bitmasks.

戻り値

Returns a new QuickHashIntStringHash object.

例

例1 QuickHashIntStringHash::__construct() example

<?php
var_dump( new QuickHashIntStringHash( 1024 ) );
var_dump( new QuickHashIntStringHash( 1024, QuickHashIntStringHash::CHECK_FOR_DUPES ) );
var_dump(
new QuickHashIntStringHash(
1024,
QuickHashIntStringHash::DO_NOT_USE_ZEND_ALLOC | QuickHashIntStringHash::HASHER_JENKINS2
)
);
?>


This method deletes an entry from the hash

  • ≪ QuickHashIntStringHash::__construct
  • QuickHashIntStringHash::exists ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method deletes an entry from the hash

QuickHashIntStringHash::delete

(PECL quickhash >= Unknown)

QuickHashIntStringHash::delete — This method deletes an entry from the hash

説明

public QuickHashIntStringHash::delete(int $key): bool

This method deletes an entry from the hash, and returns whether the entry was deleted or not. Associated memory structures will not be freed immediately, but rather when the hash itself is freed.

Elements can not be deleted when the hash is used in an iterator. The method will not throw an exception, but simply return false like would happen with any other deletion failure.

パラメータ

key

The key of the entry to delete.

戻り値

true when the entry was deleted, and false if the entry was not deleted.

例

例1 QuickHashIntStringHash::delete() example

<?php
$hash = new QuickHashIntStringHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, "five" ) );
var_dump( $hash->delete( 4 ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->delete( 4 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
bool(true)
bool(false)
bool(false)


This method checks whether a key is part of the hash

  • ≪ QuickHashIntStringHash::delete
  • QuickHashIntStringHash::get ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method checks whether a key is part of the hash

QuickHashIntStringHash::exists

(PECL quickhash >= Unknown)

QuickHashIntStringHash::exists — This method checks whether a key is part of the hash

説明

public QuickHashIntStringHash::exists(int $key): bool

This method checks whether an entry with the provided key exists in the hash.

パラメータ

key

The key of the entry to check for whether it exists in the hash.

戻り値

Returns true when the entry was found, or false when the entry is not found.


This method retrieves a value from the hash by its key

  • ≪ QuickHashIntStringHash::exists
  • QuickHashIntStringHash::getSize ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method retrieves a value from the hash by its key

QuickHashIntStringHash::get

(PECL quickhash >= Unknown)

QuickHashIntStringHash::get — This method retrieves a value from the hash by its key

説明

public QuickHashIntStringHash::get(int $key): mixed

This method retrieves a value from the hash by its key.

パラメータ

key

The key of the entry to retrieve.

戻り値

The value if the key exists, or null if the key wasn't part of the hash.

例

例1 QuickHashIntStringHash::get() example

<?php
$hash = new QuickHashIntStringHash( 8 );
var_dump( $hash->get( 1 ) );

var_dump( $hash->add( 2, "two" ) );
var_dump( $hash->get( 2 ) );

var_dump( $hash->add( 3, 5 ) );
var_dump( $hash->get( 3 ) );
?>

上の例の出力は、 たとえば以下のようになります。

bool(false)
bool(true)
string(3) "two"
bool(true)
string(1) "5"


Returns the number of elements in the hash

  • ≪ QuickHashIntStringHash::get
  • QuickHashIntStringHash::loadFromFile ≫
  • PHP Manual
  • QuickHashIntStringHash
  • Returns the number of elements in the hash

QuickHashIntStringHash::getSize

(PECL quickhash >= Unknown)

QuickHashIntStringHash::getSize — Returns the number of elements in the hash

説明

public QuickHashIntStringHash::getSize(): int

Returns the number of elements in the hash.

パラメータ

この関数にはパラメータはありません。

戻り値

The number of elements in the hash.

例

例1 QuickHashIntStringHash::getSize() example

<?php
$hash = new QuickHashIntStringHash( 8 );
var_dump( $hash->add( 2, "two" ) );
var_dump( $hash->add( 3, 5 ) );
var_dump( $hash->getSize() );
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
int(2)


This factory method creates a hash from a file

  • ≪ QuickHashIntStringHash::getSize
  • QuickHashIntStringHash::loadFromString ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This factory method creates a hash from a file

QuickHashIntStringHash::loadFromFile

(PECL quickhash >= Unknown)

QuickHashIntStringHash::loadFromFile — This factory method creates a hash from a file

説明

public static QuickHashIntStringHash::loadFromFile(string $filename, int $size = 0, int $options = 0): QuickHashIntStringHash

This factory method creates a new hash from a definition file on disk. The file format consists of a signature 'QH\0x12\0', the number of elements as a 32 bit signed integer in system Endianness, an unsigned 32 bit integer containing the number of element data to follow in characters. This element data contains all the strings. After the header and the strings, the elements follow in pairs of two unsigned 32 bit integers where the first one is the key, and the second one the index in the element data string. An example could be:

例1 QuickHash IntString file format

00000000  51 48 12 00 02 00 00 00  09 00 00 00 4f 4e 45 00  |QH..........ONE.|
00000010  4e 49 4e 45 00 01 00 00  00 00 00 00 00 03 00 00  |NINE............|
00000020  00 04 00 00 00                                    |.....|
00000025

例2 QuickHash IntString file format

header signature ('QH'; key type: 1; value type: 2; filler: \0x00)
00000000  51 48 12 00

number of elements:
00000004  02 00 00 00

length of string values (9 characters):
00000008  09 00 00 00

string values:
0000000C  4f 4e 45 00 4e 49 4e 45  00

data string:
00000015  01 00 00 00 00 00 00 00  03 00 00 00 04 00 00 00

key/value 1 (key = 1, string index = 0 ("ONE")):
01 00 00 00  00 00 00 00

key/value 2 (key = 3, string index = 4 ("NINE")):
03 00 00 00  04 00 00 00

パラメータ

filename

The filename of the file to read the hash from.

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the hash, rounded up to the nearest power of two with a maximum limit of 4194304.

戻り値

Returns a new QuickHashIntStringHash.

例

例3 QuickHashIntStringHash::loadFromFile() example

<?php
$file = dirname( __FILE__ ) . "/simple.string.hash";
$hash = QuickHashIntStringHash::loadFromFile(
$file,
QuickHashIntStringHash::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
printf( "Key %3d (%2x) is %s\n",
$key, $key,
$hash->exists( $key ) ? 'set' : 'unset'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Key   0 ( 0) is unset
Key   1 ( 1) is set
Key   2 ( 2) is set
Key   3 ( 3) is set
Key   4 ( 4) is unset
Key   5 ( 5) is set
Key   6 ( 6) is unset
Key   7 ( 7) is set
Key   8 ( 8) is unset
Key   9 ( 9) is unset
Key  10 ( a) is unset
Key  11 ( b) is set
Key  12 ( c) is unset
Key  13 ( d) is set
Key  14 ( e) is unset
Key  15 ( f) is unset


This factory method creates a hash from a string

  • ≪ QuickHashIntStringHash::loadFromFile
  • QuickHashIntStringHash::saveToFile ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This factory method creates a hash from a string

QuickHashIntStringHash::loadFromString

(PECL quickhash >= Unknown)

QuickHashIntStringHash::loadFromString — This factory method creates a hash from a string

説明

public static QuickHashIntStringHash::loadFromString(string $contents, int $size = 0, int $options = 0): QuickHashIntStringHash

This factory method creates a new hash from a definition in a string. The format is the same as the one used in "loadFromFile".

パラメータ

contents

The string containing a serialized format of the hash.

size

The amount of bucket lists to configure. The number you pass in will be automatically rounded up to the next power of two. It is also automatically limited from 4 to 4194304.

options

The same options that the class' constructor takes; except that the size option is ignored. It is automatically calculated to be the same as the number of entries in the hash, rounded up to the nearest power of two with a maximum limit of 4194304.

戻り値

Returns a new QuickHashIntStringHash.

例

例1 QuickHashIntStringHash::loadFromString() example

<?php
$contents = file_get_contents( dirname( __FILE__ ) . "/simple.hash" );
$hash = QuickHashIntStringHash::loadFromString(
$contents,
QuickHashIntStringHash::DO_NOT_USE_ZEND_ALLOC
);
foreach( range( 0, 0x0f ) as $key )
{
printf( "Key %3d (%2x) is %s\n",
$key, $key,
$hash->exists( $key ) ? 'set' : 'unset'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Key   0 ( 0) is unset
Key   1 ( 1) is set
Key   2 ( 2) is set
Key   3 ( 3) is set
Key   4 ( 4) is unset
Key   5 ( 5) is set
Key   6 ( 6) is unset
Key   7 ( 7) is set
Key   8 ( 8) is unset
Key   9 ( 9) is unset
Key  10 ( a) is unset
Key  11 ( b) is set
Key  12 ( c) is unset
Key  13 ( d) is set
Key  14 ( e) is unset
Key  15 ( f) is unset


This method stores an in-memory hash to disk

  • ≪ QuickHashIntStringHash::loadFromString
  • QuickHashIntStringHash::saveToString ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method stores an in-memory hash to disk

QuickHashIntStringHash::saveToFile

(PECL quickhash >= Unknown)

QuickHashIntStringHash::saveToFile — This method stores an in-memory hash to disk

説明

public QuickHashIntStringHash::saveToFile(string $filename): void

This method stores an existing hash to a file on disk, in the same format that loadFromFile() can read.

パラメータ

filename

The filename of the file to store the hash in.

戻り値

値を返しません。

例

例1 QuickHashIntStringHash::saveToFile() example

<?php
$hash = new QuickHashIntStringHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, "forty three" ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, "fifty two" ) );

$hash->saveToFile( '/tmp/test.string.hash' );
?>


This method returns a serialized version of the hash

  • ≪ QuickHashIntStringHash::saveToFile
  • QuickHashIntStringHash::set ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method returns a serialized version of the hash

QuickHashIntStringHash::saveToString

(PECL quickhash >= Unknown)

QuickHashIntStringHash::saveToString — This method returns a serialized version of the hash

説明

public QuickHashIntStringHash::saveToString(): string

This method returns a serialized version of the hash in the same format that QuickHashIntStringHash::loadFromString() can read.

パラメータ

この関数にはパラメータはありません。

戻り値

This method returns a string containing a serialized format of the hash. Each element is stored as a four byte value in the Endianness that the current system uses.

例

例1 QuickHashIntStringHash::saveToString() example

<?php
$hash = new QuickHashIntStringHash( 1024 );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 4, "thirty four" ) );
var_dump( $hash->exists( 4 ) );
var_dump( $hash->add( 5, "fifty five" ) );

var_dump( $hash->saveToString() );
?>


This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

  • ≪ QuickHashIntStringHash::saveToString
  • QuickHashIntStringHash::update ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

QuickHashIntStringHash::set

(PECL quickhash >= Unknown)

QuickHashIntStringHash::set — This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist

説明

public QuickHashIntStringHash::set(int $key, string $value): int

This method tries to update an entry with a new value. In case the entry did not yet exist, it will instead add a new entry. It returns whether the entry was added or update. If there are duplicate keys, only the first found element will get an updated value. Use QuickHashIntStringHash::CHECK_FOR_DUPES during hash creation to prevent duplicate keys from being part of the hash.

パラメータ

key

The key of the entry to add or update.

value

The value of the entry to add. If a non-string is passed, it will be converted to a string automatically if possible.

戻り値

2 if the entry was found and updated, 1 if the entry was newly added or 0 if there was an error.

例

例1 QuickHashIntStringHash::set() example

<?php
$hash = new QuickHashIntStringHash( 1024 );

echo "Set->Add\n";
var_dump( $hash->get( 46692 ) );
var_dump( $hash->set( 46692, "sixteen thousand ninety one" ) );
var_dump( $hash->get( 46692 ) );

echo "Set->Update\n";
var_dump( $hash->set( 46692, "twenty nine thousand nine hundred six" ) );
var_dump( $hash->get( 46692 ) );
?>

上の例の出力は、 たとえば以下のようになります。

Set->Add
bool(false)
int(2)
string(27) "sixteen thousand ninety one"
Set->Update
int(1)
string(37) "twenty nine thousand nine hundred six"


This method updates an entry in the hash with a new value

  • ≪ QuickHashIntStringHash::set
  • リフレクション ≫
  • PHP Manual
  • QuickHashIntStringHash
  • This method updates an entry in the hash with a new value

QuickHashIntStringHash::update

(PECL quickhash >= Unknown)

QuickHashIntStringHash::update — This method updates an entry in the hash with a new value

説明

public QuickHashIntStringHash::update(int $key, string $value): bool

This method updates an entry with a new value, and returns whether the entry was update. If there are duplicate keys, only the first found element will get an updated value. Use QuickHashIntStringHash::CHECK_FOR_DUPES during hash creation to prevent duplicate keys from being part of the hash.

パラメータ

key

The key of the entry to update.

value

The new value for the entry. If a non-string is passed, it will be converted to a string automatically if possible.

戻り値

true when the entry was found and updated, and false if the entry was not part of the hash already.

例

例1 QuickHashIntStringHash::update() example

<?php
$hash->add( 161803398, "--" );
$hash->add( 314159265, "a lot" );

echo $hash->get( 161803398 ), "\n";
echo $hash->get( 314159265 ), "\n";

var_dump( $hash->update( 314159265, "a lot plus one" ) );
var_dump( $hash->update( 314159999, "a lot plus one" ) );

echo $hash->get( 161803398 ), "\n";
echo $hash->get( 314159265 ), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

--
a lot
bool(true)
bool(false)
--
a lot plus one


リフレクション

  • はじめに
  • 定義済み定数
  • 例
  • 拡張
  • Reflection — Reflection クラス
    • Reflection::export — エクスポートする
    • Reflection::getModifierNames — 修飾子の名前を取得する
  • ReflectionClass — ReflectionClass クラス
    • ReflectionClass::__construct — ReflectionClass を作成する
    • ReflectionClass::export — クラスをエクスポートする
    • ReflectionClass::getAttributes — アトリビュートを取得する
    • ReflectionClass::getConstant — 定義されている定数を取得する
    • ReflectionClass::getConstants — 定数を取得する
    • ReflectionClass::getConstructor — クラスのコンストラクタを取得する
    • ReflectionClass::getDefaultProperties — デフォルトプロパティを取得する
    • ReflectionClass::getDocComment — ドキュメントコメントを取得する
    • ReflectionClass::getEndLine — 終了行を取得する
    • ReflectionClass::getExtension — クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する
    • ReflectionClass::getExtensionName — クラスを定義する拡張モジュールの名前を取得する
    • ReflectionClass::getFileName — クラスが定義されているファイルのファイル名を取得する
    • ReflectionClass::getInterfaceNames — インターフェイスの名前を取得する
    • ReflectionClass::getInterfaces — インターフェイスを取得する
    • ReflectionClass::getMethod — クラスメソッドの ReflectionMethod を取得する
    • ReflectionClass::getMethods — メソッドの配列を取得する
    • ReflectionClass::getModifiers — クラス修飾子を取得する
    • ReflectionClass::getName — クラスの名前を取得する
    • ReflectionClass::getNamespaceName — 名前空間の名前を取得する
    • ReflectionClass::getParentClass — 親クラスを取得する
    • ReflectionClass::getProperties — プロパティを取得する
    • ReflectionClass::getProperty — クラスのプロパティを表す ReflectionProperty を取得する
    • ReflectionClass::getReflectionConstant — クラス定数の ReflectionClassConstant を取得する
    • ReflectionClass::getReflectionConstants — クラス定数を取得する
    • ReflectionClass::getShortName — 短い名前を取得する
    • ReflectionClass::getStartLine — 開始行を取得する
    • ReflectionClass::getStaticProperties — staticプロパティを取得する
    • ReflectionClass::getStaticPropertyValue — staticプロパティの値を取得する
    • ReflectionClass::getTraitAliases — トレイトのエイリアスの配列を返す
    • ReflectionClass::getTraitNames — このクラスが使うトレイトの名前の配列を返す
    • ReflectionClass::getTraits — このクラスが使うトレイトの配列を返す
    • ReflectionClass::hasConstant — 定数が定義されているかどうかを調べる
    • ReflectionClass::hasMethod — メソッドが定義されているかどうかを調べる
    • ReflectionClass::hasProperty — プロパティが定義されているかどうかを調べる
    • ReflectionClass::implementsInterface — インターフェイスの実装を調べる
    • ReflectionClass::inNamespace — 名前空間内にあるかどうかを調べる
    • ReflectionClass::isAbstract — 抽象クラスであるかどうかを調べる
    • ReflectionClass::isAnonymous — クラスが無名クラスかを調べる
    • ReflectionClass::isCloneable — このクラスがクローン可能かどうかを返す
    • ReflectionClass::isEnum — 列挙型であるかどうかを返す
    • ReflectionClass::isFinal — final クラスであるかどうかを調べる
    • ReflectionClass::isInstance — クラスのインスタンスであるかどうかを調べる
    • ReflectionClass::isInstantiable — クラスのインスタンス化が可能であるかどうかを調べる
    • ReflectionClass::isInterface — このクラスがインターフェイスであるかどうかを調べる
    • ReflectionClass::isInternal — 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる
    • ReflectionClass::isIterable — このクラスがイテレーション可能かを調べる
    • ReflectionClass::isIterateable — のエイリアス ReflectionClass::isIterable
    • ReflectionClass::isReadOnly — クラスが readonly かを調べる
    • ReflectionClass::isSubclassOf — サブクラスであるかどうかを調べる
    • ReflectionClass::isTrait — トレイトであるかどうかを返す
    • ReflectionClass::isUserDefined — ユーザー定義であるかどうかを調べる
    • ReflectionClass::newInstance — 指定した引数でクラスの新しいインスタンスを作成する
    • ReflectionClass::newInstanceArgs — 指定した引数でクラスの新しいインスタンスを作成する
    • ReflectionClass::newInstanceWithoutConstructor — コンストラクタを起動せずに新しいクラスのインスタンスを作成する
    • ReflectionClass::setStaticPropertyValue — staticプロパティの値を設定する
    • ReflectionClass::__toString — ReflectionClass オブジェクトの文字列表現を返す
  • ReflectionClassConstant — ReflectionClassConstant クラス
    • ReflectionClassConstant::__construct — ReflectionClassConstant を構築する
    • ReflectionClassConstant::export — リフレクションをエクスポートする
    • ReflectionClassConstant::getAttributes — アトリビュートを取得する
    • ReflectionClassConstant::getDeclaringClass — 定数を宣言しているクラスを取得する
    • ReflectionClassConstant::getDocComment — クラス定数のドキュメントコメントを取得する
    • ReflectionClassConstant::getModifiers — クラス定数の修飾子を取得する
    • ReflectionClassConstant::getName — 定数名を取得する
    • ReflectionClassConstant::getValue — 値を取得する
    • ReflectionClassConstant::isEnumCase — クラス定数が、列挙型の case かどうかを調べる
    • ReflectionClassConstant::isFinal — クラス定数が final かどうかを調べる
    • ReflectionClassConstant::isPrivate — クラス定数がprivateかを調べる
    • ReflectionClassConstant::isProtected — クラス定数が protected かを調べる
    • ReflectionClassConstant::isPublic — クラス定数が public かを調べる
    • ReflectionClassConstant::__toString — ReflectionClassConstant オブジェクトの文字列表現を返す
  • ReflectionEnum — ReflectionEnum クラス
    • ReflectionEnum::__construct — ReflectionEnum オブジェクトをインスタンス化する
    • ReflectionEnum::getBackingType — 存在する場合に、列挙型が依存する型を取得する
    • ReflectionEnum::getCase — 列挙型の特定の case を返す
    • ReflectionEnum::getCases — 列挙型の全ての case を返す
    • ReflectionEnum::hasCase — 列挙型が case を持つかを調べる
    • ReflectionEnum::isBacked — 列挙型が Backed Enum かを調べる
  • ReflectionEnumUnitCase — ReflectionEnumUnitCase クラス
    • ReflectionEnumUnitCase::__construct — ReflectionEnumUnitCase オブジェクトをインスタンス化する
    • ReflectionEnumUnitCase::getEnum — この case が属するリフレクションオブジェクトを取得する
    • ReflectionEnumUnitCase::getValue — このリフレクションオブジェクトが表す case オブジェクトを取得する
  • ReflectionEnumBackedCase — ReflectionEnumBackedCase クラス
    • ReflectionEnumBackedCase::__construct — ReflectionEnumBackedCase オブジェクトをインスタンス化する
    • ReflectionEnumBackedCase::getBackingValue — Backed Enum の case が持つスカラー値を取得する
  • ReflectionZendExtension — ReflectionZendExtension クラス
    • ReflectionZendExtension::__clone — Clone のハンドラ
    • ReflectionZendExtension::__construct — ReflectionZendExtension オブジェクトを作成する
    • ReflectionZendExtension::export — エクスポート
    • ReflectionZendExtension::getAuthor — 作者を取得する
    • ReflectionZendExtension::getCopyright — 著作権情報を取得する
    • ReflectionZendExtension::getName — 名前を取得する
    • ReflectionZendExtension::getURL — URL を取得する
    • ReflectionZendExtension::getVersion — バージョンを取得する
    • ReflectionZendExtension::__toString — 文字列変換のハンドラ
  • ReflectionExtension — ReflectionExtension クラス
    • ReflectionExtension::__clone — クローンする
    • ReflectionExtension::__construct — ReflectionExtension を作成する
    • ReflectionExtension::export — エクスポートする
    • ReflectionExtension::getClasses — クラスを取得する
    • ReflectionExtension::getClassNames — クラス名を取得する
    • ReflectionExtension::getConstants — 定数を取得する
    • ReflectionExtension::getDependencies — 依存性を取得する
    • ReflectionExtension::getFunctions — 拡張モジュールの関数を取得する
    • ReflectionExtension::getINIEntries — 拡張モジュールの ini エントリを取得する
    • ReflectionExtension::getName — 拡張モジュール名を取得する
    • ReflectionExtension::getVersion — 拡張モジュールのバージョンを取得する
    • ReflectionExtension::info — 拡張モジュールの情報を表示する
    • ReflectionExtension::isPersistent — この拡張モジュールが永続性のあるものかどうかを返す
    • ReflectionExtension::isTemporary — この拡張モジュールが一時的なものかどうかを返す
    • ReflectionExtension::__toString — 文字列に変換する
  • ReflectionFunction — ReflectionFunction クラス
    • ReflectionFunction::__construct — ReflectionFunction オブジェクトを作成する
    • ReflectionFunction::export — 関数をエクスポートする
    • ReflectionFunction::getClosure — この関数に動的に作成されたクロージャを返す
    • ReflectionFunction::invoke — 関数を起動する
    • ReflectionFunction::invokeArgs — 引数を指定して関数を起動する
    • ReflectionFunction::isAnonymous — 関数が無名関数かどうかを調べる
    • ReflectionFunction::isDisabled — 関数が無効になっているかどうかを調べる
    • ReflectionFunction::__toString — ReflectionFunction を表現する文字列を返す
  • ReflectionFunctionAbstract — ReflectionFunctionAbstract クラス
    • ReflectionFunctionAbstract::__clone — 関数のクローンを作成する
    • ReflectionFunctionAbstract::getAttributes — アトリビュートを取得する
    • ReflectionFunctionAbstract::getClosureScopeClass — クロージャに関連づけられたスコープクラスを返す
    • ReflectionFunctionAbstract::getClosureThis — クロージャにバインドした this ポインタを返す
    • ReflectionFunctionAbstract::getClosureUsedVariables — クロージャ内で使われている変数の配列を返す
    • ReflectionFunctionAbstract::getDocComment — ドキュメントコメントを取得する
    • ReflectionFunctionAbstract::getEndLine — 終了行番号を取得する
    • ReflectionFunctionAbstract::getExtension — 拡張モジュールの情報を取得する
    • ReflectionFunctionAbstract::getExtensionName — 拡張モジュールの名前を取得する
    • ReflectionFunctionAbstract::getFileName — ファイル名を取得する
    • ReflectionFunctionAbstract::getName — 関数名を取得する
    • ReflectionFunctionAbstract::getNamespaceName — 名前空間名を取得する
    • ReflectionFunctionAbstract::getNumberOfParameters — パラメータ数を取得する
    • ReflectionFunctionAbstract::getNumberOfRequiredParameters — 必須パラメータの数を取得する
    • ReflectionFunctionAbstract::getParameters — パラメータを取得する
    • ReflectionFunctionAbstract::getReturnType — 指定された関数の戻り値の型を取得する
    • ReflectionFunctionAbstract::getShortName — 関数の短い名前を取得する
    • ReflectionFunctionAbstract::getStartLine — 開始行番号を取得する
    • ReflectionFunctionAbstract::getStaticVariables — static変数を取得する
    • ReflectionFunctionAbstract::getTentativeReturnType — 関数に関連付けられた仮の戻り値の型を返す
    • ReflectionFunctionAbstract::hasReturnType — 関数が戻り値の型を指定しているかを調べる
    • ReflectionFunctionAbstract::hasTentativeReturnType — 戻り値の型を仮で宣言しているかを返す
    • ReflectionFunctionAbstract::inNamespace — 関数が名前空間内にあるかどうかを調べる
    • ReflectionFunctionAbstract::isClosure — クロージャであるかどうかを調べる
    • ReflectionFunctionAbstract::isDeprecated — 非推奨であるかどうかを調べる
    • ReflectionFunctionAbstract::isGenerator — この関数がジェネレータかどうかを返す
    • ReflectionFunctionAbstract::isInternal — 内部関数かどうかを調べる
    • ReflectionFunctionAbstract::isStatic — 関数が static であるかどうかを調べる
    • ReflectionFunctionAbstract::isUserDefined — ユーザー定義関数であるかどうかを調べる
    • ReflectionFunctionAbstract::isVariadic — この関数の引数が可変長かを調べる
    • ReflectionFunctionAbstract::returnsReference — 参照返しかどうかを調べる
    • ReflectionFunctionAbstract::__toString — ReflectionFunctionAbstract を表現する文字列を返す
  • ReflectionMethod — ReflectionMethod クラス
    • ReflectionMethod::__construct — ReflectionMethod を作成する
    • ReflectionMethod::createFromMethodName — ReflectionMethod を作成する
    • ReflectionMethod::export — メソッドをエクスポートする
    • ReflectionMethod::getClosure — このメソッドに動的に作成されたクロージャを返す
    • ReflectionMethod::getDeclaringClass — メソッドが宣言されているクラスを取得する
    • ReflectionMethod::getModifiers — メソッドの修飾子を取得する
    • ReflectionMethod::getPrototype — メソッドのプロトタイプを (存在すれば) 取得する
    • ReflectionMethod::hasPrototype — メソッドがプロトタイプを持つかを調べる
    • ReflectionMethod::invoke — 実行する
    • ReflectionMethod::invokeArgs — 実行する
    • ReflectionMethod::isAbstract — 抽象メソッドであるかどうかを調べる
    • ReflectionMethod::isConstructor — コンストラクタであるかどうかを調べる
    • ReflectionMethod::isDestructor — デストラクタであるかどうかを調べる
    • ReflectionMethod::isFinal — final メソッドであるかどうかを調べる
    • ReflectionMethod::isPrivate — private メソッドであるかどうかを調べる
    • ReflectionMethod::isProtected — protected メソッドであるかどうかを調べる
    • ReflectionMethod::isPublic — public メソッドであるかどうかを調べる
    • ReflectionMethod::setAccessible — メソッドのアクセス範囲を設定する
    • ReflectionMethod::__toString — ReflectionMethod オブジェクトの文字列表現を返す
  • ReflectionNamedType — ReflectionNamedType クラス
    • ReflectionNamedType::getName — 型の名前の文字列を取得する
    • ReflectionNamedType::isBuiltin — 組み込みの型であるかを調べる
  • ReflectionObject — ReflectionObject クラス
    • ReflectionObject::__construct — ReflectionObject を作成する
    • ReflectionObject::export — エクスポートする
  • ReflectionParameter — ReflectionParameter クラス
    • ReflectionParameter::allowsNull — null を許可するかどうかを調べる
    • ReflectionParameter::canBePassedByValue — このパラメータが値渡し可能かどうかを返す
    • ReflectionParameter::__clone — クローンする
    • ReflectionParameter::__construct — コンストラクタ
    • ReflectionParameter::export — エクスポートする
    • ReflectionParameter::getAttributes — アトリビュートを取得する
    • ReflectionParameter::getClass — リフレクションされた ReflectionClass を取得する。
    • ReflectionParameter::getDeclaringClass — 宣言しているクラスを取得する
    • ReflectionParameter::getDeclaringFunction — 宣言している関数を取得する
    • ReflectionParameter::getDefaultValue — パラメータのデフォルト値を取得する
    • ReflectionParameter::getDefaultValueConstantName — デフォルト値が定数あるいは null の場合に、その定数名を返す
    • ReflectionParameter::getName — パラメータ名を取得する
    • ReflectionParameter::getPosition — パラメータの位置を取得する
    • ReflectionParameter::getType — 引数の型を取得する
    • ReflectionParameter::hasType — 引数が型を持つかを調べる
    • ReflectionParameter::isArray — 配列を受け取るパラメータであるかどうかを調べる
    • ReflectionParameter::isCallable — パラメータが callable かどうかを返す
    • ReflectionParameter::isDefaultValueAvailable — デフォルト値が存在するかどうかを調べる
    • ReflectionParameter::isDefaultValueConstant — このパラメータのデフォルト値が定数かどうかを返す
    • ReflectionParameter::isOptional — 省略可能であるかどうかを調べる
    • ReflectionParameter::isPassedByReference — 参照渡しかどうかを調べる
    • ReflectionParameter::isVariadic — 引数が可変長の個数であるかをチェックする
    • ReflectionParameter::__toString — 文字列に変換する
  • ReflectionProperty — ReflectionProperty クラス
    • ReflectionProperty::__clone — クローンする
    • ReflectionProperty::__construct — ReflectionProperty オブジェクトを作成する
    • ReflectionProperty::export — エクスポートする
    • ReflectionProperty::getAttributes — アトリビュートを取得する
    • ReflectionProperty::getDeclaringClass — 宣言しているクラスを取得する
    • ReflectionProperty::getDefaultValue — プロパティで宣言されたデフォルト値を返す
    • ReflectionProperty::getDocComment — プロパティのドキュメントコメントを取得する
    • ReflectionProperty::getModifiers — プロパティの修飾子を取得する
    • ReflectionProperty::getName — プロパティ名を取得する
    • ReflectionProperty::getType — プロパティの型を取得する
    • ReflectionProperty::getValue — 値を取得する
    • ReflectionProperty::hasDefaultValue — デフォルト値が宣言されているかをチェックする
    • ReflectionProperty::hasType — プロパティが型を持つかをチェックする
    • ReflectionProperty::isDefault — デフォルトプロパティであるかどうかを調べる
    • ReflectionProperty::isInitialized — プロパティが初期化されているかをチェックする
    • ReflectionProperty::isPrivate — private プロパティであるかどうかを調べる
    • ReflectionProperty::isPromoted — プロパティがコンストラクタの引数から昇格したものかを調べる
    • ReflectionProperty::isProtected — protected プロパティであるかどうかを調べる
    • ReflectionProperty::isPublic — public プロパティであるかどうかを調べる
    • ReflectionProperty::isReadOnly — プロパティが readonly かを調べる
    • ReflectionProperty::isStatic — staticプロパティであるかどうかを調べる
    • ReflectionProperty::setAccessible — プロパティのアクセス範囲を設定する
    • ReflectionProperty::setValue — プロパティの値を設定する
    • ReflectionProperty::__toString — 文字列に変換する
  • ReflectionType — ReflectionType クラス
    • ReflectionType::allowsNull — null が許されるかをチェックする
    • ReflectionType::__toString — 文字列に変換する
  • ReflectionUnionType — ReflectionUnionType クラス
    • ReflectionUnionType::getTypes — union 型に含まれる型を返す。
  • ReflectionGenerator — ReflectionGenerator クラス
    • ReflectionGenerator::__construct — ReflectionGenerator オブジェクトを構築する
    • ReflectionGenerator::getExecutingFile — 現在実行中のジェネレータのファイル名を取得する
    • ReflectionGenerator::getExecutingGenerator — 実行中の Generator オブジェクトを取得する
    • ReflectionGenerator::getExecutingLine — 現在実行中のジェネレータの行を取得する
    • ReflectionGenerator::getFunction — ジェネレータの関数名を取得する
    • ReflectionGenerator::getThis — ジェネレータの $this の値を取得する
    • ReflectionGenerator::getTrace — 実行中のジェネレータのトレースを取得する
  • ReflectionFiber — ReflectionFiber クラス
    • ReflectionFiber::__construct — Constructs a ReflectionFiber オブジェクトを構築する
    • ReflectionFiber::getCallable — Fiber の構築に使われた callable を取得する
    • ReflectionFiber::getExecutingFile — 現在実行中のファイル名を取得する
    • ReflectionFiber::getExecutingLine — 現在実行中の行番号を取得する
    • ReflectionFiber::getFiber — リフレクションされた Fiber クラスのインスタンスを取得する
    • ReflectionFiber::getTrace — 現在実行している時点のバックトレースを取得する
  • ReflectionIntersectionType — ReflectionIntersectionType クラス
    • ReflectionIntersectionType::getTypes — 交差型に含まれている型を返す
  • ReflectionReference — ReflectionReference クラス
    • ReflectionReference::__construct — private なコンストラクタのため、直接インスタンス化できません
    • ReflectionReference::fromArrayElement — 配列の要素から、ReflectionReference を生成する
    • ReflectionReference::getId — リファレンスのユニークなIDを取得する
  • ReflectionAttribute — ReflectionAttribute クラス
    • ReflectionAttribute::__construct — private なコンストラクタのため、直接インスタンス化できません
    • ReflectionAttribute::getArguments — アトリビュートに渡された引数を取得する
    • ReflectionAttribute::getName — アトリビュートの名前を取得する
    • ReflectionAttribute::getTarget — アトリビュートのターゲットをビットマスクとして返す
    • ReflectionAttribute::isRepeated — この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得する
    • ReflectionAttribute::newInstance — アトリビュートクラスをインスタンス化する
  • Reflector — Reflector インターフェイス
    • Reflector::export — エクスポートする
  • ReflectionException — ReflectionException クラス


はじめに

PHP には完全なリフレクション API が付属しており、 クラス、インターフェイス、関数、メソッド、そして拡張モジュールについて 型やプロパティを実行時に調べることができます。 さらに、このリフレクション API は関数、クラス、メソッドに 関するドキュメントコメントも取得することができます。

内部 API の一部には、Reflection 拡張モジュールに対応するために必要なコードが欠けているものがあることに注意しましょう。 たとえば、内部 PHP クラスにはプロパティについてのリフレクションデータがありません。 しかし、こういった例はバグだと見なされており、見つけたら修正しなければなりません。


  • ≪ はじめに
  • 例 ≫
  • PHP Manual
  • リフレクション
  • 定義済み定数

定義済み定数

各クラスでそれぞれの定数について説明します。


例

リフレクションのドキュメントの中には多くの例が示されています。 特に、各クラスの __construct のドキュメントを見るといいでしょう。

例1 シェル (ターミナル) からのリフレクションの例

$ php --rf strlen
$ php --rc finfo
$ php --re json
$ php --ri dom

上の例の出力は、 たとえば以下のようになります。

Function [ <internal:Core> function strlen ] {

  - Parameters [1] {
    Parameter #0 [ <required> $str ]
  }
}

Class [ <internal:fileinfo> class finfo ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [4] {
    Method [ <internal:fileinfo, ctor> public method finfo ] {

      - Parameters [2] {
        Parameter #0 [ <optional> $options ]
        Parameter #1 [ <optional> $arg ]
      }
    }

    Method [ <internal:fileinfo> public method set_flags ] {

      - Parameters [1] {
        Parameter #0 [ <required> $options ]
      }
    }

    Method [ <internal:fileinfo> public method file ] {

      - Parameters [3] {
        Parameter #0 [ <required> $filename ]
        Parameter #1 [ <optional> $options ]
        Parameter #2 [ <optional> $context ]
      }
    }

    Method [ <internal:fileinfo> public method buffer ] {

      - Parameters [3] {
        Parameter #0 [ <required> $string ]
        Parameter #1 [ <optional> $options ]
        Parameter #2 [ <optional> $context ]
      }
    }
  }
}

Extension [ <persistent> extension #23 json version 1.2.1 ] {

  - Constants [10] {
    Constant [ integer JSON_HEX_TAG ] { 1 }
    Constant [ integer JSON_HEX_AMP ] { 2 }
    Constant [ integer JSON_HEX_APOS ] { 4 }
    Constant [ integer JSON_HEX_QUOT ] { 8 }
    Constant [ integer JSON_FORCE_OBJECT ] { 16 }
    Constant [ integer JSON_ERROR_NONE ] { 0 }
    Constant [ integer JSON_ERROR_DEPTH ] { 1 }
    Constant [ integer JSON_ERROR_STATE_MISMATCH ] { 2 }
    Constant [ integer JSON_ERROR_CTRL_CHAR ] { 3 }
    Constant [ integer JSON_ERROR_SYNTAX ] { 4 }
  }

  - Functions {
    Function [ <internal:json> function json_encode ] {

      - Parameters [2] {
        Parameter #0 [ <required> $value ]
        Parameter #1 [ <optional> $options ]
      }
    }
    Function [ <internal:json> function json_decode ] {

      - Parameters [3] {
        Parameter #0 [ <required> $json ]
        Parameter #1 [ <optional> $assoc ]
        Parameter #2 [ <optional> $depth ]
      }
    }
    Function [ <internal:json> function json_last_error ] {

      - Parameters [0] {
      }
    }
  }
}

dom

DOM/XML => enabled
DOM/XML API Version => 20031129
libxml Version => 2.7.3
HTML Support => enabled
XPath Support => enabled
XPointer Support => enabled
Schema Support => enabled
RelaxNG Support => enabled


拡張

組み込みクラスの特別なバージョンを作成したい場合 (例えば、エクスポートする際に色づけしたHTMLを作成したり、 メソッドの代わりに簡単にアクセスできるメンバー変数を作成したり、 補助的なメソッドを作成したり) は、クラスを拡張してみましょう。

例1 組み込みクラスを拡張する

<?php
/**
* 独自の Reflection_Method クラス
*/
class My_Reflection_Method extends ReflectionMethod
{
public $visibility = array();

public function __construct($o, $m)
{
parent::__construct($o, $m);
$this->visibility = Reflection::getModifierNames($this->getModifiers());
}
}

/**
* デモクラス #1
*
*/
class T {
protected function x() {}
}

/**
* デモクラス #2
*
*/
class U extends T {
function x() {}
}

// 情報を表示します
var_dump(new My_Reflection_Method('U', 'x'));
?>

上の例の出力は、 たとえば以下のようになります。

object(My_Reflection_Method)#1 (3) {
  ["visibility"]=>
  array(1) {
    [0]=>
    string(6) "public"
  }
  ["name"]=>
  string(1) "x"
  ["class"]=>
  string(1) "U"
}
警告

コンストラクタを上書きする場合は、 挿入するコードの前に親クラスのコンストラクタをコールすることを忘れないようにしましょう。 これを怠ると、以下のようなエラーを発生します。 Fatal error: Internal error: Failed to retrieve the reflection object


Reflection クラス

(PHP 5, PHP 7, PHP 8)

はじめに

リフレクションクラスです。

クラス概要

class Reflection {
/* メソッド */
public static export(Reflector $reflector, bool $return = false): string
public static getModifierNames(int $modifiers): array
}

目次

  • Reflection::export — エクスポートする
  • Reflection::getModifierNames — 修飾子の名前を取得する


エクスポートする

  • ≪ Reflection
  • Reflection::getModifierNames ≫
  • PHP Manual
  • Reflection
  • エクスポートする

Reflection::export

(PHP 5, PHP 7)

Reflection::export — エクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static Reflection::export(Reflector $reflector, bool $return = false): string

リフレクションをエクスポートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reflector

エクスポートするリフレクション。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

return パラメータを true に設定すると、エクスポートを文字列で返します。それ以外の場合は null を返します。

参考

  • Reflection::getModifierNames() - 修飾子の名前を取得する


修飾子の名前を取得する

  • ≪ Reflection::export
  • ReflectionClass ≫
  • PHP Manual
  • Reflection
  • 修飾子の名前を取得する

Reflection::getModifierNames

(PHP 5, PHP 7, PHP 8)

Reflection::getModifierNames — 修飾子の名前を取得する

説明

public static Reflection::getModifierNames(int $modifiers): array

修飾子の名前を取得します。

パラメータ

modifiers

取得する主食師のビットフィールド

戻り値

修飾子の名前の配列を返します。

例

例1 Reflection::getModifierNames() の例

<?php
class Testing
{
final public static function foo()
{
return;
}

public function bar()
{
return;
}
}

$foo = new ReflectionMethod('Testing', 'foo');

echo "Modifiers for method foo():\n";
echo $foo->getModifiers() . "\n";
echo implode(' ', Reflection::getModifierNames($foo->getModifiers())) . "\n";

$bar = new ReflectionMethod('Testing', 'bar');

echo "Modifiers for method bar():\n";
echo $bar->getModifiers() . "\n";
echo implode(' ', Reflection::getModifierNames($bar->getModifiers()));

上の例の出力は、 たとえば以下のようになります。

Modifiers for method foo():
261
final public static
Modifiers for method bar():
65792
public

参考

  • ReflectionClass::getModifiers() - クラス修飾子を取得する
  • ReflectionClassConstant::getModifiers() - クラス定数の修飾子を取得する
  • ReflectionMethod::getModifiers() - メソッドの修飾子を取得する
  • ReflectionProperty::getModifiers() - プロパティの修飾子を取得する


ReflectionClass クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionClass クラスは クラスについての情報を報告します。

クラス概要

class ReflectionClass implements Reflector {
/* 定数 */
public const int IS_IMPLICIT_ABSTRACT;
public const int IS_EXPLICIT_ABSTRACT;
public const int IS_FINAL;
public const int IS_READONLY;
/* プロパティ */
public string $name;
/* メソッド */
public __construct(object|string $objectOrClass)
public static export(mixed $argument, bool $return = false): string
public getAttributes(?string $name = null, int $flags = 0): array
public getConstant(string $name): mixed
public getConstants(?int $filter = null): array
public getConstructor(): ?ReflectionMethod
public getDefaultProperties(): array
public getDocComment(): string|false
public getEndLine(): int|false
public getExtension(): ?ReflectionExtension
public getExtensionName(): string|false
public getFileName(): string|false
public getInterfaceNames(): array
public getInterfaces(): array
public getMethod(string $name): ReflectionMethod
public getMethods(?int $filter = null): array
public getModifiers(): int
public getName(): string
public getNamespaceName(): string
public getParentClass(): ReflectionClass|false
public getProperties(?int $filter = null): array
public getProperty(string $name): ReflectionProperty
public getReflectionConstant(string $name): ReflectionClassConstant|false
public getReflectionConstants(?int $filter = null): array
public getShortName(): string
public getStartLine(): int|false
public getStaticProperties(): array
public getStaticPropertyValue(string $name, mixed &$def_value = ?): mixed
public getTraitAliases(): array
public getTraitNames(): array
public getTraits(): array
public hasConstant(string $name): bool
public hasMethod(string $name): bool
public hasProperty(string $name): bool
public implementsInterface(ReflectionClass|string $interface): bool
public inNamespace(): bool
public isAbstract(): bool
public isAnonymous(): bool
public isCloneable(): bool
public isEnum(): bool
public isFinal(): bool
public isInstance(object $object): bool
public isInstantiable(): bool
public isInterface(): bool
public isInternal(): bool
public isIterable(): bool
public isReadOnly(): bool
public isSubclassOf(ReflectionClass|string $class): bool
public isTrait(): bool
public isUserDefined(): bool
public newInstance(mixed ...$args): object
public newInstanceArgs(array $args = []): ?object
public newInstanceWithoutConstructor(): object
public setStaticPropertyValue(string $name, mixed $value): void
public __toString(): string
}

プロパティ

name

クラス名。読み込み専用で、書き込もうとすると ReflectionException をスローします。

定義済み定数

ReflectionClass の修飾子

ReflectionClass::IS_IMPLICIT_ABSTRACT

抽象メソッドを持っているので abstract クラスであることを示します。

ReflectionClass::IS_EXPLICIT_ABSTRACT

その定義から abstract クラスであることを示します。

ReflectionClass::IS_FINAL

final クラスであることを示します。

ReflectionClass::IS_READONLY

readonly クラスであることを示します。

変更履歴

バージョン | 説明
8.0.0 | ReflectionClass::export() は、削除されました。

目次

  • ReflectionClass::__construct — ReflectionClass を作成する
  • ReflectionClass::export — クラスをエクスポートする
  • ReflectionClass::getAttributes — アトリビュートを取得する
  • ReflectionClass::getConstant — 定義されている定数を取得する
  • ReflectionClass::getConstants — 定数を取得する
  • ReflectionClass::getConstructor — クラスのコンストラクタを取得する
  • ReflectionClass::getDefaultProperties — デフォルトプロパティを取得する
  • ReflectionClass::getDocComment — ドキュメントコメントを取得する
  • ReflectionClass::getEndLine — 終了行を取得する
  • ReflectionClass::getExtension — クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する
  • ReflectionClass::getExtensionName — クラスを定義する拡張モジュールの名前を取得する
  • ReflectionClass::getFileName — クラスが定義されているファイルのファイル名を取得する
  • ReflectionClass::getInterfaceNames — インターフェイスの名前を取得する
  • ReflectionClass::getInterfaces — インターフェイスを取得する
  • ReflectionClass::getMethod — クラスメソッドの ReflectionMethod を取得する
  • ReflectionClass::getMethods — メソッドの配列を取得する
  • ReflectionClass::getModifiers — クラス修飾子を取得する
  • ReflectionClass::getName — クラスの名前を取得する
  • ReflectionClass::getNamespaceName — 名前空間の名前を取得する
  • ReflectionClass::getParentClass — 親クラスを取得する
  • ReflectionClass::getProperties — プロパティを取得する
  • ReflectionClass::getProperty — クラスのプロパティを表す ReflectionProperty を取得する
  • ReflectionClass::getReflectionConstant — クラス定数の ReflectionClassConstant を取得する
  • ReflectionClass::getReflectionConstants — クラス定数を取得する
  • ReflectionClass::getShortName — 短い名前を取得する
  • ReflectionClass::getStartLine — 開始行を取得する
  • ReflectionClass::getStaticProperties — staticプロパティを取得する
  • ReflectionClass::getStaticPropertyValue — staticプロパティの値を取得する
  • ReflectionClass::getTraitAliases — トレイトのエイリアスの配列を返す
  • ReflectionClass::getTraitNames — このクラスが使うトレイトの名前の配列を返す
  • ReflectionClass::getTraits — このクラスが使うトレイトの配列を返す
  • ReflectionClass::hasConstant — 定数が定義されているかどうかを調べる
  • ReflectionClass::hasMethod — メソッドが定義されているかどうかを調べる
  • ReflectionClass::hasProperty — プロパティが定義されているかどうかを調べる
  • ReflectionClass::implementsInterface — インターフェイスの実装を調べる
  • ReflectionClass::inNamespace — 名前空間内にあるかどうかを調べる
  • ReflectionClass::isAbstract — 抽象クラスであるかどうかを調べる
  • ReflectionClass::isAnonymous — クラスが無名クラスかを調べる
  • ReflectionClass::isCloneable — このクラスがクローン可能かどうかを返す
  • ReflectionClass::isEnum — 列挙型であるかどうかを返す
  • ReflectionClass::isFinal — final クラスであるかどうかを調べる
  • ReflectionClass::isInstance — クラスのインスタンスであるかどうかを調べる
  • ReflectionClass::isInstantiable — クラスのインスタンス化が可能であるかどうかを調べる
  • ReflectionClass::isInterface — このクラスがインターフェイスであるかどうかを調べる
  • ReflectionClass::isInternal — 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる
  • ReflectionClass::isIterable — このクラスがイテレーション可能かを調べる
  • ReflectionClass::isIterateable — のエイリアス ReflectionClass::isIterable
  • ReflectionClass::isReadOnly — クラスが readonly かを調べる
  • ReflectionClass::isSubclassOf — サブクラスであるかどうかを調べる
  • ReflectionClass::isTrait — トレイトであるかどうかを返す
  • ReflectionClass::isUserDefined — ユーザー定義であるかどうかを調べる
  • ReflectionClass::newInstance — 指定した引数でクラスの新しいインスタンスを作成する
  • ReflectionClass::newInstanceArgs — 指定した引数でクラスの新しいインスタンスを作成する
  • ReflectionClass::newInstanceWithoutConstructor — コンストラクタを起動せずに新しいクラスのインスタンスを作成する
  • ReflectionClass::setStaticPropertyValue — staticプロパティの値を設定する
  • ReflectionClass::__toString — ReflectionClass オブジェクトの文字列表現を返す


ReflectionClass を作成する

  • ≪ ReflectionClass
  • ReflectionClass::export ≫
  • PHP Manual
  • ReflectionClass
  • ReflectionClass を作成する

ReflectionClass::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionClass::__construct — ReflectionClass を作成する

説明

public ReflectionClass::__construct(object|string $objectOrClass)

新しい ReflectionClass オブジェクトを作成します。

パラメータ

objectOrClass

調べたいクラスのクラス名をあらわす文字列か、そのクラスのオブジェクト。

エラー / 例外

リフレクションするクラスが存在しない場合、 ReflectionException がスローされます。

例

例1 ReflectionClass の基本的な使用例

<?php
$reflection = new ReflectionClass('Exception');
echo $reflection;
?>

上の例の出力は、 たとえば以下のようになります。

Class [ <internal:Core> class Exception implements Stringable, Throwable ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [7] {
    Property [ protected $message = '' ]
    Property [ private string $string = '' ]
    Property [ protected $code = 0 ]
    Property [ protected string $file = '' ]
    Property [ protected int $line = 0 ]
    Property [ private array $trace = [] ]
    Property [ private ?Throwable $previous = NULL ]
  }

  - Methods [11] {
    Method [ <internal:Core> private method __clone ] {

      - Parameters [0] {
      }
      - Return [ void ]
    }

    Method [ <internal:Core, ctor> public method __construct ] {

      - Parameters [3] {
        Parameter #0 [ <optional> string $message = "" ]
        Parameter #1 [ <optional> int $code = 0 ]
        Parameter #2 [ <optional> ?Throwable $previous = null ]
      }
    }

    Method [ <internal:Core> public method __wakeup ] {

      - Parameters [0] {
      }
      - Tentative return [ void ]
    }

    Method [ <internal:Core, prototype Throwable> final public method getMessage ] {

      - Parameters [0] {
      }
      - Return [ string ]
    }

    Method [ <internal:Core, prototype Throwable> final public method getCode ] {

      - Parameters [0] {
      }
    }

    Method [ <internal:Core, prototype Throwable> final public method getFile ] {

      - Parameters [0] {
      }
      - Return [ string ]
    }

    Method [ <internal:Core, prototype Throwable> final public method getLine ] {

      - Parameters [0] {
      }
      - Return [ int ]
    }

    Method [ <internal:Core, prototype Throwable> final public method getTrace ] {

      - Parameters [0] {
      }
      - Return [ array ]
    }

    Method [ <internal:Core, prototype Throwable> final public method getPrevious ] {

      - Parameters [0] {
      }
      - Return [ ?Throwable ]
    }

    Method [ <internal:Core, prototype Throwable> final public method getTraceAsString ] {

      - Parameters [0] {
      }
      - Return [ string ]
    }

    Method [ <internal:Core, prototype Stringable> public method __toString ] {

      - Parameters [0] {
      }
      - Return [ string ]
    }
  }
}

参考

  • ReflectionObject::__construct() - ReflectionObject を作成する
  • コンストラクタ


クラスをエクスポートする

  • ≪ ReflectionClass::__construct
  • ReflectionClass::getAttributes ≫
  • PHP Manual
  • ReflectionClass
  • クラスをエクスポートする

ReflectionClass::export

(PHP 5, PHP 7)

ReflectionClass::export — クラスをエクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionClass::export(mixed $argument, bool $return = false): string

調べているクラスをエクスポートします。

パラメータ

argument

エクスポートするリフレクション。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

return パラメータを true に設定すると、エクスポートを文字列で返します。それ以外の場合は null を返します。

例

例1 ReflectionClass::export() の基本的な使用例

<?php
class Apple {
public $var1;
public $var2 = 'Orange';

public function type() {
return 'Apple';
}
}
ReflectionClass::export('Apple');
?>

上の例の出力は、 たとえば以下のようになります。

Class [ <user> class Apple ] {
  @@ php shell code 1-8

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [2] {
    Property [ <default> public $var1 ]
    Property [ <default> public $var2 ]
  }

  - Methods [1] {
    Method [ <user> public method type ] {
      @@ php shell code 5 - 7
    }
  }
}

参考

  • ReflectionClass::getName() - クラスの名前を取得する
  • ReflectionClass::__toString() - ReflectionClass オブジェクトの文字列表現を返す


アトリビュートを取得する

  • ≪ ReflectionClass::export
  • ReflectionClass::getConstant ≫
  • PHP Manual
  • ReflectionClass
  • アトリビュートを取得する

ReflectionClass::getAttributes

(PHP 8)

ReflectionClass::getAttributes — アトリビュートを取得する

説明

public ReflectionClass::getAttributes(?string $name = null, int $flags = 0): array

このクラスで宣言されている全てのアトリビュートを ReflectionAttribute の配列として返します。

パラメータ

name

指定したクラス名にマッチするアトリビュートの、 ReflectionAttribute のみを含むようにフィルタします。

flags

name が指定されていた場合に、 結果をどうフィルタするかを決めるフラグ。

デフォルトは 0 です。 この場合、アトリビュートのクラス名が name であるものだけを返します。

他の利用可能なオプションは、 ReflectionAttribute::IS_INSTANCEOF です。 この場合、フィルタリングに instanceof を使います。

戻り値

アトリビュートの配列を、 ReflectionAttribute オブジェクトの配列として返します。

例

例1 基本的な使用法

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

#[Fruit]
#[Red]
class Apple {
}

$class = new ReflectionClass('Apple');
$attributes = $class->getAttributes();
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
    [1] => Red
)

例2 クラス名で結果をフィルタする

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

#[Fruit]
#[Red]
class Apple {
}

$class = new ReflectionClass('Apple');
$attributes = $class->getAttributes('Fruit');
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
)

例3 クラス名、かつ継承も考慮して結果をフィルタする

<?php
interface Color {
}

#[Attribute]
class Fruit {
}

#[Attribute]
class Red implements Color {
}

#[Fruit]
#[Red]
class Apple {
}

$class = new ReflectionClass('Apple');
$attributes = $class->getAttributes(Color::class, ReflectionAttribute::IS_INSTANCEOF);
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Red
)

参考

  • ReflectionClassConstant::getAttributes() - アトリビュートを取得する
  • ReflectionFunctionAbstract::getAttributes() - アトリビュートを取得する
  • ReflectionParameter::getAttributes() - アトリビュートを取得する
  • ReflectionProperty::getAttributes() - アトリビュートを取得する


定義されている定数を取得する

  • ≪ ReflectionClass::getAttributes
  • ReflectionClass::getConstants ≫
  • PHP Manual
  • ReflectionClass
  • 定義されている定数を取得する

ReflectionClass::getConstant

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getConstant — 定義されている定数を取得する

説明

public ReflectionClass::getConstant(string $name): mixed

定義されている定数を取得します。

パラメータ

name

取得する対象のクラス定数の名前。

戻り値

name で指定した名前の定数の値を返します。 そのクラスに定数が見つからなかった場合は、false を返します。

例

例1 ReflectionClass::getConstant() の使い方

<?php

class Example {
const C1 = false;
const C2 = 'I am a constant';
}

$reflection = new ReflectionClass('Example');

var_dump($reflection->getConstant('C1'));
var_dump($reflection->getConstant('C2'));
var_dump($reflection->getConstant('C3'));
?>

上の例の出力は以下となります。

bool(false)
string(15) "I am a constant"
bool(false)

参考

  • ReflectionClass::getConstants() - 定数を取得する


定数を取得する

  • ≪ ReflectionClass::getConstant
  • ReflectionClass::getConstructor ≫
  • PHP Manual
  • ReflectionClass
  • 定数を取得する

ReflectionClass::getConstants

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getConstants — 定数を取得する

説明

public ReflectionClass::getConstants(?int $filter = null): array

アクセス権にかかわらず、クラスで定義されているすべての定数を取得します。

パラメータ

filter

オプションのフィルタで、取得したい定数の型を絞り込みます。 ReflectionClassConstant クラスの定数 で設定し、デフォルトではすべての定数を取得します。

戻り値

定数の配列を返します。 キーは名前を保持し、値は定数の値を保持します。

変更履歴

バージョン | 説明
8.0.0 | filter が追加されました。

参考

  • ReflectionClass::getConstant() - 定義されている定数を取得する


クラスのコンストラクタを取得する

  • ≪ ReflectionClass::getConstants
  • ReflectionClass::getDefaultProperties ≫
  • PHP Manual
  • ReflectionClass
  • クラスのコンストラクタを取得する

ReflectionClass::getConstructor

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getConstructor — クラスのコンストラクタを取得する

説明

public ReflectionClass::getConstructor(): ?ReflectionMethod

クラスのコンストラクタを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスのコンストラクタを表す ReflectionMethod オブジェクトを返します。 クラスのコンストラクタがない場合は null を返します。

例

例1 ReflectionClass::getConstructor() の基本的な使用例

<?php
$class = new ReflectionClass('ReflectionClass');
$constructor = $class->getConstructor();
var_dump($constructor);
?>

上の例の出力は以下となります。

object(ReflectionMethod)#2 (2) {
  ["name"]=>
  string(11) "__construct"
  ["class"]=>
  string(15) "ReflectionClass"
}

参考

  • ReflectionClass::getName() - クラスの名前を取得する


デフォルトプロパティを取得する

  • ≪ ReflectionClass::getConstructor
  • ReflectionClass::getDocComment ≫
  • PHP Manual
  • ReflectionClass
  • デフォルトプロパティを取得する

ReflectionClass::getDefaultProperties

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getDefaultProperties — デフォルトプロパティを取得する

説明

public ReflectionClass::getDefaultProperties(): array

クラスのデフォルトプロパティ (継承したプロパティを含む) を取得します。

注意:

このメソッドで static プロパティを扱えるのは、内部クラスの場合だけです。 ユーザー定義クラスで使った場合は、 クラスの static なプロパティのデフォルト値はこのメソッドでは追跡できません。

パラメータ

この関数にはパラメータはありません。

戻り値

デフォルトプロパティの配列を返します。プロパティ名が配列のキー、 そしてそのプロパティのデフォルト値が配列の値 (デフォルト値が存在しない場合は null) となります。 この関数はstaticプロパティとそうでないプロパティを区別せず、 アクセス修飾子も考慮しません。

例

例1 ReflectionClass::getDefaultProperties() の例

<?php
class Bar {
protected $inheritedProperty = 'inheritedDefault';
}

class Foo extends Bar {
public $property = 'propertyDefault';
private $privateProperty = 'privatePropertyDefault';
public static $staticProperty = 'staticProperty';
public $defaultlessProperty;
}

$reflectionClass = new ReflectionClass('Foo');
var_dump($reflectionClass->getDefaultProperties());
?>

上の例の出力は以下となります。

array(5) {
   ["staticProperty"]=>
   string(14) "staticProperty"
   ["property"]=>
   string(15) "propertyDefault"
   ["privateProperty"]=>
   string(22) "privatePropertyDefault"
   ["defaultlessProperty"]=>
   NULL
   ["inheritedProperty"]=>
   string(16) "inheritedDefault"
}

参考

  • ReflectionClass::getProperties() - プロパティを取得する
  • ReflectionClass::getStaticProperties() - staticプロパティを取得する
  • ReflectionClass::getProperty() - クラスのプロパティを表す ReflectionProperty を取得する


ドキュメントコメントを取得する

  • ≪ ReflectionClass::getDefaultProperties
  • ReflectionClass::getEndLine ≫
  • PHP Manual
  • ReflectionClass
  • ドキュメントコメントを取得する

ReflectionClass::getDocComment

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getDocComment — ドキュメントコメントを取得する

説明

public ReflectionClass::getDocComment(): string|false

クラスのドキュメントコメントを取得します。 ドキュメントコメントは、 /** で始まり、 ホワイトスペースがその後に続きます。 クラス定義に複数のドキュメントコメントが存在した場合、 クラスに一番近いコメントを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ドキュメントコメントが存在すればそれを返します。存在しなければ false を返します。

例

例1 ReflectionClass::getDocComment() の例

<?php
/**
* A test class
*
* @param foo bar
* @return baz
*/
class TestClass { }

$rc = new ReflectionClass('TestClass');
var_dump($rc->getDocComment());
?>

上の例の出力は以下となります。

string(61) "/**
 * A test class
 *
 * @param  foo bar
 * @return baz
 */"

参考

  • ReflectionClass::getName() - クラスの名前を取得する


終了行を取得する

  • ≪ ReflectionClass::getDocComment
  • ReflectionClass::getExtension ≫
  • PHP Manual
  • ReflectionClass
  • 終了行を取得する

ReflectionClass::getEndLine

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getEndLine — 終了行を取得する

説明

public ReflectionClass::getEndLine(): int|false

ユーザー定義クラスの定義の終了行を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ユーザー定義クラスの定義の終了行を返します。不明な場合は false を返します。

例

例1 ReflectionClass::getEndLine() の例

<?php
// テストクラス
class TestClass { }

$rc = new ReflectionClass('TestClass');

echo $rc->getEndLine();
?>

上の例の出力は以下となります。

3

参考

  • ReflectionClass::getStartLine() - 開始行を取得する


クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する

  • ≪ ReflectionClass::getEndLine
  • ReflectionClass::getExtensionName ≫
  • PHP Manual
  • ReflectionClass
  • クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する

ReflectionClass::getExtension

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getExtension — クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する

説明

public ReflectionClass::getExtension(): ?ReflectionExtension

クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを返します。 ユーザー定義のクラスの場合は null を返します。

例

例1 ReflectionClass::getExtension() の基本的な使用例

<?php
$class = new ReflectionClass('ReflectionClass');
$extension = $class->getExtension();
var_dump($extension);
?>

上の例の出力は以下となります。

object(ReflectionExtension)#2 (1) {
  ["name"]=>
  string(10) "Reflection"
}

参考

  • ReflectionClass::getExtensionName() - クラスを定義する拡張モジュールの名前を取得する


クラスを定義する拡張モジュールの名前を取得する

  • ≪ ReflectionClass::getExtension
  • ReflectionClass::getFileName ≫
  • PHP Manual
  • ReflectionClass
  • クラスを定義する拡張モジュールの名前を取得する

ReflectionClass::getExtensionName

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getExtensionName — クラスを定義する拡張モジュールの名前を取得する

説明

public ReflectionClass::getExtensionName(): string|false

クラスを定義する拡張モジュールの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスを定義する拡張モジュールの名前を返します。 ユーザー定義のクラスの場合は false を返します。

例

例1 ReflectionClass::getExtensionName() の基本的な使用例

<?php
$class = new ReflectionClass('ReflectionClass');
$extension = $class->getExtensionName();
var_dump($extension);
?>

上の例の出力は以下となります。

string(10) "Reflection"

参考

  • ReflectionClass::getExtension() - クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する


クラスが定義されているファイルのファイル名を取得する

  • ≪ ReflectionClass::getExtensionName
  • ReflectionClass::getInterfaceNames ≫
  • PHP Manual
  • ReflectionClass
  • クラスが定義されているファイルのファイル名を取得する

ReflectionClass::getFileName

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getFileName — クラスが定義されているファイルのファイル名を取得する

説明

public ReflectionClass::getFileName(): string|false

クラスが定義されているファイルのファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスが定義されているファイルのファイル名を返します。 そのクラスが PHP のコアあるいは PHP の拡張モジュール内で定義されている場合は false を返します。

参考

  • ReflectionClass::getExtensionName() - クラスを定義する拡張モジュールの名前を取得する


インターフェイスの名前を取得する

  • ≪ ReflectionClass::getFileName
  • ReflectionClass::getInterfaces ≫
  • PHP Manual
  • ReflectionClass
  • インターフェイスの名前を取得する

ReflectionClass::getInterfaceNames

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionClass::getInterfaceNames — インターフェイスの名前を取得する

説明

public ReflectionClass::getInterfaceNames(): array

インターフェイスの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

インターフェイス名の配列を返します。

例

例1 ReflectionClass::getInterfaceNames() の例

<?php
interface Foo { }

interface Bar { }

class Baz implements Foo, Bar { }

$rc1 = new ReflectionClass("Baz");

print_r($rc1->getInterfaceNames());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Foo
    [1] => Bar
)

参考

  • ReflectionClass::getInterfaces() - インターフェイスを取得する


インターフェイスを取得する

  • ≪ ReflectionClass::getInterfaceNames
  • ReflectionClass::getMethod ≫
  • PHP Manual
  • ReflectionClass
  • インターフェイスを取得する

ReflectionClass::getInterfaces

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getInterfaces — インターフェイスを取得する

説明

public ReflectionClass::getInterfaces(): array

インターフェイスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

インターフェイスの連想配列を返します。インターフェイス名が連想配列のキー、対応する値が ReflectionClass オブジェクトとなります。

例

例1 ReflectionClass::getInterfaces() の例

<?php
interface Foo { }

interface Bar { }

class Baz implements Foo, Bar { }

$rc1 = new ReflectionClass("Baz");

print_r($rc1->getInterfaces());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Foo] => ReflectionClass Object
        (
            [name] => Foo
        )

    [Bar] => ReflectionClass Object
        (
            [name] => Bar
        )

)

参考

  • ReflectionClass::getInterfaceNames() - インターフェイスの名前を取得する


クラスメソッドの ReflectionMethod を取得する

  • ≪ ReflectionClass::getInterfaces
  • ReflectionClass::getMethods ≫
  • PHP Manual
  • ReflectionClass
  • クラスメソッドの ReflectionMethod を取得する

ReflectionClass::getMethod

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getMethod — クラスメソッドの ReflectionMethod を取得する

説明

public ReflectionClass::getMethod(string $name): ReflectionMethod

クラスメソッドに関する ReflectionMethod を取得します。

パラメータ

name

調べたいメソッドの名前。

戻り値

ReflectionMethod を返します。

エラー / 例外

メソッドが存在しない場合に ReflectionException が発生します。

例

例1 ReflectionClass::getMethod() の基本的な使用例

<?php
$class = new ReflectionClass('ReflectionClass');
$method = $class->getMethod('getMethod');
var_dump($method);
?>

上の例の出力は以下となります。

object(ReflectionMethod)#2 (2) {
  ["name"]=>
  string(9) "getMethod"
  ["class"]=>
  string(15) "ReflectionClass"
}

参考

  • ReflectionClass::getMethods() - メソッドの配列を取得する


メソッドの配列を取得する

  • ≪ ReflectionClass::getMethod
  • ReflectionClass::getModifiers ≫
  • PHP Manual
  • ReflectionClass
  • メソッドの配列を取得する

ReflectionClass::getMethods

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getMethods — メソッドの配列を取得する

説明

public ReflectionClass::getMethods(?int $filter = null): array

クラスのメソッドの配列を取得します。

パラメータ

filter

結果をフィルタして、特定の属性を持つメソッドだけを含めるようにします。 デフォルトは、何もフィルタしません。

ReflectionMethod::IS_STATIC、
ReflectionMethod::IS_PUBLIC、
ReflectionMethod::IS_PROTECTED、
ReflectionMethod::IS_PRIVATE、
ReflectionMethod::IS_ABSTRACT、
ReflectionMethod::IS_FINAL
の任意の組み合わせ。
指定した属性の いずれか を持つすべてのメソッドを返します。

注意: その他のビット演算 (~ など) は期待通りの挙動にはなりません。 つまり、たとえば static ではないメソッドをすべて取得するなどといったことはできません。

戻り値

各メソッドを表す ReflectionMethod オブジェクトの配列を返します。

変更履歴

バージョン | 説明
7.2.0 | filter は、nullable になりました。

例

例1 ReflectionClass::getMethods() の基本的な使用例

<?php
class Apple {
public function firstMethod() { }
final protected function secondMethod() { }
private static function thirdMethod() { }
}

$class = new ReflectionClass('Apple');
$methods = $class->getMethods();
var_dump($methods);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  object(ReflectionMethod)#2 (2) {
    ["name"]=>
    string(11) "firstMethod"
    ["class"]=>
    string(5) "Apple"
  }
  [1]=>
  object(ReflectionMethod)#3 (2) {
    ["name"]=>
    string(12) "secondMethod"
    ["class"]=>
    string(5) "Apple"
  }
  [2]=>
  object(ReflectionMethod)#4 (2) {
    ["name"]=>
    string(11) "thirdMethod"
    ["class"]=>
    string(5) "Apple"
  }
}

例2 ReflectionClass::getMethods() のフィルタリング

<?php
class Apple {
public function firstMethod() { }
final protected function secondMethod() { }
private static function thirdMethod() { }
}

$class = new ReflectionClass('Apple');
$methods = $class->getMethods(ReflectionMethod::IS_STATIC | ReflectionMethod::IS_FINAL);
var_dump($methods);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  object(ReflectionMethod)#2 (2) {
    ["name"]=>
    string(12) "secondMethod"
    ["class"]=>
    string(5) "Apple"
  }
  [1]=>
  object(ReflectionMethod)#3 (2) {
    ["name"]=>
    string(11) "thirdMethod"
    ["class"]=>
    string(5) "Apple"
  }
}

参考

  • ReflectionClass::getMethod() - クラスメソッドの ReflectionMethod を取得する
  • get_class_methods() - クラスメソッドの名前を取得する


クラス修飾子を取得する

  • ≪ ReflectionClass::getMethods
  • ReflectionClass::getName ≫
  • PHP Manual
  • ReflectionClass
  • クラス修飾子を取得する

ReflectionClass::getModifiers

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getModifiers — クラス修飾子を取得する

説明

public ReflectionClass::getModifiers(): int

このクラスのアクセス修飾子のビットフィールドを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

修飾子定数 のビットマスクを返します。

参考

  • ReflectionClass::getProperties() - プロパティを取得する
  • Reflection::getModifierNames() - 修飾子の名前を取得する


クラスの名前を取得する

  • ≪ ReflectionClass::getModifiers
  • ReflectionClass::getNamespaceName ≫
  • PHP Manual
  • ReflectionClass
  • クラスの名前を取得する

ReflectionClass::getName

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getName — クラスの名前を取得する

説明

public ReflectionClass::getName(): string

クラスの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスの名前を返します。

例

例1 ReflectionClass::getName() の例

<?php
namespace A\B;

class Foo { }

$function = new \ReflectionClass('stdClass');

var_dump($function->inNamespace());
var_dump($function->getName());
var_dump($function->getNamespaceName());
var_dump($function->getShortName());

$function = new \ReflectionClass('A\\B\\Foo');

var_dump($function->inNamespace());
var_dump($function->getName());
var_dump($function->getNamespaceName());
var_dump($function->getShortName());
?>

上の例の出力は以下となります。

bool(false)
string(8) "stdClass"
string(0) ""
string(8) "stdClass"

bool(true)
string(7) "A\B\Foo"
string(3) "A\B"
string(3) "Foo"

参考

  • ReflectionClass::getNamespaceName() - 名前空間の名前を取得する


名前空間の名前を取得する

  • ≪ ReflectionClass::getName
  • ReflectionClass::getParentClass ≫
  • PHP Manual
  • ReflectionClass
  • 名前空間の名前を取得する

ReflectionClass::getNamespaceName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionClass::getNamespaceName — 名前空間の名前を取得する

説明

public ReflectionClass::getNamespaceName(): string

名前空間の名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

名前空間の名前を返します。

例

例1 ReflectionClass::getNamespaceName() の例

<?php
namespace A\B;

class Foo { }

$class = new \ReflectionClass('stdClass');

var_dump($class->inNamespace());
var_dump($class->getName());
var_dump($class->getNamespaceName());
var_dump($class->getShortName());

$class = new \ReflectionClass('A\\B\\Foo');

var_dump($class->inNamespace());
var_dump($class->getName());
var_dump($class->getNamespaceName());
var_dump($class->getShortName());
?>

上の例の出力は以下となります。

bool(false)
string(8) "stdClass"
string(0) ""
string(8) "stdClass"

bool(true)
string(7) "A\B\Foo"
string(3) "A\B"
string(3) "Foo"

参考

  • ReflectionClass::getParentClass() - 親クラスを取得する
  • 名前空間


親クラスを取得する

  • ≪ ReflectionClass::getNamespaceName
  • ReflectionClass::getProperties ≫
  • PHP Manual
  • ReflectionClass
  • 親クラスを取得する

ReflectionClass::getParentClass

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getParentClass — 親クラスを取得する

説明

public ReflectionClass::getParentClass(): ReflectionClass|false

親クラスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionClass を返します。 親が存在しない場合は、false を返します。

参考

  • ReflectionClass::__construct() - ReflectionClass を作成する


プロパティを取得する

  • ≪ ReflectionClass::getParentClass
  • ReflectionClass::getProperty ≫
  • PHP Manual
  • ReflectionClass
  • プロパティを取得する

ReflectionClass::getProperties

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getProperties — プロパティを取得する

説明

public ReflectionClass::getProperties(?int $filter = null): array

プロパティを取得します。

パラメータ

filter

オプションのフィルタで、取得したいプロパティの型を絞り込みます。 ReflectionProperty の定数 で設定し、デフォルトではすべてのプロパティ型を取得します。

戻り値

ReflectionProperty オブジェクトの配列を返します。

変更履歴

バージョン | 説明
7.2.0 | filter は、nullable になりました。

例

例1 ReflectionClass::getProperties() でのフィルタリングの例

この例では、オプションのパラメータ filter を使って private プロパティを読み飛ばします。

<?php
class Foo {
public $foo = 1;
protected $bar = 2;
private $baz = 3;
}

$foo = new Foo();

$reflect = new ReflectionClass($foo);
$props = $reflect->getProperties(ReflectionProperty::IS_PUBLIC | ReflectionProperty::IS_PROTECTED);

foreach ($props as $prop) {
print $prop->getName() . "\n";
}

var_dump($props);

?>

上の例の出力は、 たとえば以下のようになります。

foo
bar
array(2) {
  [0]=>
  object(ReflectionProperty)#3 (2) {
    ["name"]=>
    string(3) "foo"
    ["class"]=>
    string(3) "Foo"
  }
  [1]=>
  object(ReflectionProperty)#4 (2) {
    ["name"]=>
    string(3) "bar"
    ["class"]=>
    string(3) "Foo"
  }
}

参考

  • ReflectionClass::getProperty() - クラスのプロパティを表す ReflectionProperty を取得する
  • ReflectionProperty
  • ReflectionProperty の修飾子定数


クラスのプロパティを表す ReflectionProperty を取得する

  • ≪ ReflectionClass::getProperties
  • ReflectionClass::getReflectionConstant ≫
  • PHP Manual
  • ReflectionClass
  • クラスのプロパティを表す ReflectionProperty を取得する

ReflectionClass::getProperty

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getProperty — クラスのプロパティを表す ReflectionProperty を取得する

説明

public ReflectionClass::getProperty(string $name): ReflectionProperty

クラスのプロパティを表す ReflectionProperty を取得します。

パラメータ

name

プロパティの名前。

戻り値

ReflectionProperty を返します。

例

例1 ReflectionClass::getProperty() の基本的な使用例

<?php
$class = new ReflectionClass('ReflectionClass');
$property = $class->getProperty('name');
var_dump($property);
?>

上の例の出力は以下となります。

object(ReflectionProperty)#2 (2) {
  ["name"]=>
  string(4) "name"
  ["class"]=>
  string(15) "ReflectionClass"
}

参考

  • ReflectionClass::getProperties() - プロパティを取得する


クラス定数の ReflectionClassConstant を取得する

  • ≪ ReflectionClass::getProperty
  • ReflectionClass::getReflectionConstants ≫
  • PHP Manual
  • ReflectionClass
  • クラス定数の ReflectionClassConstant を取得する

ReflectionClass::getReflectionConstant

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClass::getReflectionConstant — クラス定数の ReflectionClassConstant を取得する

説明

public ReflectionClass::getReflectionConstant(string $name): ReflectionClassConstant|false

クラス定数の ReflectionClassConstant を取得します。

パラメータ

name

クラス定数の名前

戻り値

ReflectionClassConstant を返します。 失敗した場合に false を返します

参考

  • ReflectionClass::getReflectionConstants() - クラス定数を取得する
  • ReflectionClassConstant


クラス定数を取得する

  • ≪ ReflectionClass::getReflectionConstant
  • ReflectionClass::getShortName ≫
  • PHP Manual
  • ReflectionClass
  • クラス定数を取得する

ReflectionClass::getReflectionConstants

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClass::getReflectionConstants — クラス定数を取得する

説明

public ReflectionClass::getReflectionConstants(?int $filter = null): array

リフレクションされた定数を取得します。

パラメータ

filter

オプションのフィルタで、取得したい定数の型を絞り込みます。 ReflectionClassConstant の定数 で設定し、デフォルトではすべての定数を取得します。

戻り値

ReflectionClassConstant の配列を返します。

変更履歴

バージョン | 説明
8.0.0 | filter が追加されました。

例

例1 基本的な ReflectionClass::getReflectionConstants() の例

<?php
class Foo {
public const FOO = 1;
protected const BAR = 2;
private const BAZ = 3;
}

$foo = new Foo();

$reflect = new ReflectionClass($foo);
$consts = $reflect->getReflectionConstants();

foreach ($consts as $const) {
print $const->getName() . "\n";
}

var_dump($consts);

?>

上の例の出力は、 たとえば以下のようになります。

FOO
BAR
BAZ
array(3) {
  [0]=>
  object(ReflectionClassConstant)#3 (2) {
    ["name"]=>
    string(3) "FOO"
    ["class"]=>
    string(3) "Foo"
  }
  [1]=>
  object(ReflectionClassConstant)#4 (2) {
    ["name"]=>
    string(3) "BAR"
    ["class"]=>
    string(3) "Foo"
  }
  [2]=>
  object(ReflectionClassConstant)#5 (2) {
    ["name"]=>
    string(3) "BAZ"
    ["class"]=>
    string(3) "Foo"
  }
}

参考

  • ReflectionClass::getReflectionConstant() - クラス定数の ReflectionClassConstant を取得する
  • ReflectionClassConstant


短い名前を取得する

  • ≪ ReflectionClass::getReflectionConstants
  • ReflectionClass::getStartLine ≫
  • PHP Manual
  • ReflectionClass
  • 短い名前を取得する

ReflectionClass::getShortName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionClass::getShortName — 短い名前を取得する

説明

public ReflectionClass::getShortName(): string

名前空間部分を除いた、クラスの短い名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスの短い名前を返します。

例

例1 ReflectionClass::getShortName() の例

<?php
namespace A\B;

class Foo { }

$function = new \ReflectionClass('stdClass');

var_dump($function->inNamespace());
var_dump($function->getName());
var_dump($function->getNamespaceName());
var_dump($function->getShortName());

$function = new \ReflectionClass('A\\B\\Foo');

var_dump($function->inNamespace());
var_dump($function->getName());
var_dump($function->getNamespaceName());
var_dump($function->getShortName());
?>

上の例の出力は以下となります。

bool(false)
string(8) "stdClass"
string(0) ""
string(8) "stdClass"

bool(true)
string(7) "A\B\Foo"
string(3) "A\B"
string(3) "Foo"

参考

  • ReflectionClass::getName() - クラスの名前を取得する


開始行を取得する

  • ≪ ReflectionClass::getShortName
  • ReflectionClass::getStaticProperties ≫
  • PHP Manual
  • ReflectionClass
  • 開始行を取得する

ReflectionClass::getStartLine

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getStartLine — 開始行を取得する

説明

public ReflectionClass::getStartLine(): int|false

開始行を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

開始行を整数で返します。 開始行が不明な場合は、false を返します。

参考

  • ReflectionClass::getEndLine() - 終了行を取得する


staticプロパティを取得する

  • ≪ ReflectionClass::getStartLine
  • ReflectionClass::getStaticPropertyValue ≫
  • PHP Manual
  • ReflectionClass
  • staticプロパティを取得する

ReflectionClass::getStaticProperties

(PHP 5, PHP 7, PHP 8)

ReflectionClass::getStaticProperties — staticプロパティを取得する

説明

public ReflectionClass::getStaticProperties(): array

staticプロパティを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

staticプロパティを配列で返します。

変更履歴

バージョン | 説明
8.3.0 | ReflectionClass::getStaticProperties() の戻り値の型が、?array から array に変更されました。

参考

  • ReflectionClass::getStaticPropertyValue() - staticプロパティの値を取得する
  • ReflectionClass::setStaticPropertyValue() - staticプロパティの値を設定する


staticプロパティの値を取得する

  • ≪ ReflectionClass::getStaticProperties
  • ReflectionClass::getTraitAliases ≫
  • PHP Manual
  • ReflectionClass
  • staticプロパティの値を取得する

ReflectionClass::getStaticPropertyValue

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionClass::getStaticPropertyValue — staticプロパティの値を取得する

説明

public ReflectionClass::getStaticPropertyValue(string $name, mixed &$def_value = ?): mixed

このクラスのstaticプロパティの値を取得します。

パラメータ

name

値を返したいstaticプロパティの名前。

def_value

指定した名前のstaticプロパティがそのクラスに存在しない場合に返す、デフォルト値。 プロパティが存在せず、かつこの引数も省略されていた場合は、 ReflectionException が発生します。

戻り値

staticプロパティの値を返します。

例

例1 ReflectionClass::getStaticPropertyValue() の基本的な使用例

<?php
class Apple {
public static $color = 'Red';
}

$class = new ReflectionClass('Apple');
var_dump($class->getStaticPropertyValue('color'));
?>

上の例の出力は以下となります。

string(3) "Red"

参考

  • ReflectionClass::getStaticProperties() - staticプロパティを取得する
  • ReflectionClass::setStaticPropertyValue() - staticプロパティの値を設定する


トレイトのエイリアスの配列を返す

  • ≪ ReflectionClass::getStaticPropertyValue
  • ReflectionClass::getTraitNames ≫
  • PHP Manual
  • ReflectionClass
  • トレイトのエイリアスの配列を返す

ReflectionClass::getTraitAliases

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionClass::getTraitAliases — トレイトのエイリアスの配列を返す

説明

public ReflectionClass::getTraitAliases(): array

現在のクラスで定義された、トレイトのメソッドのエイリアスの配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

新しいメソッド名をキー、その元の名前 ("TraitName::original" 形式) を値とする配列を返します。


このクラスが使うトレイトの名前の配列を返す

  • ≪ ReflectionClass::getTraitAliases
  • ReflectionClass::getTraits ≫
  • PHP Manual
  • ReflectionClass
  • このクラスが使うトレイトの名前の配列を返す

ReflectionClass::getTraitNames

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionClass::getTraitNames — このクラスが使うトレイトの名前の配列を返す

説明

public ReflectionClass::getTraitNames(): array

このクラスが使うトレイトの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

トレイト名を値とする配列を返します。


このクラスが使うトレイトの配列を返す

  • ≪ ReflectionClass::getTraitNames
  • ReflectionClass::hasConstant ≫
  • PHP Manual
  • ReflectionClass
  • このクラスが使うトレイトの配列を返す

ReflectionClass::getTraits

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionClass::getTraits — このクラスが使うトレイトの配列を返す

説明

public ReflectionClass::getTraits(): array

このクラスが使うトレイトの配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

トレイト名をキー、トレイトの ReflectionClass のインスタンスを値とする配列を返します。 エラー時には null を返します。


定数が定義されているかどうかを調べる

  • ≪ ReflectionClass::getTraits
  • ReflectionClass::hasMethod ≫
  • PHP Manual
  • ReflectionClass
  • 定数が定義されているかどうかを調べる

ReflectionClass::hasConstant

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionClass::hasConstant — 定数が定義されているかどうかを調べる

説明

public ReflectionClass::hasConstant(string $name): bool

そのクラスで特定の定数が定義されているかどうかを調べます。

パラメータ

name

調べたい定数の名前。

戻り値

定数が定義されている場合に true、それ以外の場合に false を返します。

例

例1 ReflectionClass::hasConstant() の例

<?php
class Foo {
const c1 = 1;
}

$class = new ReflectionClass("Foo");

var_dump($class->hasConstant("c1"));
var_dump($class->hasConstant("c2"));
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • ReflectionClass::hasMethod() - メソッドが定義されているかどうかを調べる
  • ReflectionClass::hasProperty() - プロパティが定義されているかどうかを調べる


メソッドが定義されているかどうかを調べる

  • ≪ ReflectionClass::hasConstant
  • ReflectionClass::hasProperty ≫
  • PHP Manual
  • ReflectionClass
  • メソッドが定義されているかどうかを調べる

ReflectionClass::hasMethod

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionClass::hasMethod — メソッドが定義されているかどうかを調べる

説明

public ReflectionClass::hasMethod(string $name): bool

そのクラスで特定のメソッドが定義されているかどうかを調べます。

パラメータ

name

調べたいメソッドの名前。

戻り値

メソッドが定義されている場合に true、それ以外の場合に false を返します。

例

例1 ReflectionClass::hasMethod() の例

<?php
Class C {
public function publicFoo() {
return true;
}

protected function protectedFoo() {
return true;
}

private function privateFoo() {
return true;
}

static function staticFoo() {
return true;
}
}

$rc = new ReflectionClass("C");

var_dump($rc->hasMethod('publicFoo'));

var_dump($rc->hasMethod('protectedFoo'));

var_dump($rc->hasMethod('privateFoo'));

var_dump($rc->hasMethod('staticFoo'));

// C には bar メソッドがありません
var_dump($rc->hasMethod('bar'));

// メソッド名は大文字小文字を区別しません
var_dump($rc->hasMethod('PUBLICfOO'));
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)
bool(true)
bool(false)
bool(true)

参考

  • ReflectionClass::hasConstant() - 定数が定義されているかどうかを調べる
  • ReflectionClass::hasProperty() - プロパティが定義されているかどうかを調べる


プロパティが定義されているかどうかを調べる

  • ≪ ReflectionClass::hasMethod
  • ReflectionClass::implementsInterface ≫
  • PHP Manual
  • ReflectionClass
  • プロパティが定義されているかどうかを調べる

ReflectionClass::hasProperty

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionClass::hasProperty — プロパティが定義されているかどうかを調べる

説明

public ReflectionClass::hasProperty(string $name): bool

特定のプロパティが定義されているかどうかを調べます。

パラメータ

name

調べたいプロパティの名前。

戻り値

プロパティが定義されている場合に true、それ以外の場合に false を返します。

例

例1 ReflectionClass::hasProperty() の例

<?php
class Foo {
public $p1;
protected $p2;
private $p3;

}

$obj = new ReflectionObject(new Foo());

var_dump($obj->hasProperty("p1"));
var_dump($obj->hasProperty("p2"));
var_dump($obj->hasProperty("p3"));
var_dump($obj->hasProperty("p4"));
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(true)
bool(true)
bool(false)

参考

  • ReflectionClass::hasConstant() - 定数が定義されているかどうかを調べる
  • ReflectionClass::hasMethod() - メソッドが定義されているかどうかを調べる


インターフェイスの実装を調べる

  • ≪ ReflectionClass::hasProperty
  • ReflectionClass::inNamespace ≫
  • PHP Manual
  • ReflectionClass
  • インターフェイスの実装を調べる

ReflectionClass::implementsInterface

(PHP 5, PHP 7, PHP 8)

ReflectionClass::implementsInterface — インターフェイスの実装を調べる

説明

public ReflectionClass::implementsInterface(ReflectionClass|string $interface): bool

インターフェイスを実装しているかどうかを調べます。

パラメータ

interface

インターフェイスの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

ReflectionClass::implementsInterface() は、 interface がインターフェイスでない場合に ReflectionException をスローします。

参考

  • ReflectionClass::isInterface() - このクラスがインターフェイスであるかどうかを調べる
  • ReflectionClass::isSubclassOf() - サブクラスであるかどうかを調べる
  • interface_exists() - インターフェイスが宣言されているかどうかを確認する
  • オブジェクト インターフェイス


名前空間内にあるかどうかを調べる

  • ≪ ReflectionClass::implementsInterface
  • ReflectionClass::isAbstract ≫
  • PHP Manual
  • ReflectionClass
  • 名前空間内にあるかどうかを調べる

ReflectionClass::inNamespace

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionClass::inNamespace — 名前空間内にあるかどうかを調べる

説明

public ReflectionClass::inNamespace(): bool

このクラスが名前空間内で定義されているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::inNamespace() の例

<?php
namespace A\B;

class Foo { }

$function = new \ReflectionClass('stdClass');

var_dump($function->inNamespace());
var_dump($function->getName());
var_dump($function->getNamespaceName());
var_dump($function->getShortName());

$function = new \ReflectionClass('A\\B\\Foo');

var_dump($function->inNamespace());
var_dump($function->getName());
var_dump($function->getNamespaceName());
var_dump($function->getShortName());
?>

上の例の出力は以下となります。

bool(false)
string(8) "stdClass"
string(0) ""
string(8) "stdClass"

bool(true)
string(7) "A\B\Foo"
string(3) "A\B"
string(3) "Foo"

参考

  • ReflectionClass::getNamespaceName() - 名前空間の名前を取得する
  • PHP 名前空間


抽象クラスであるかどうかを調べる

  • ≪ ReflectionClass::inNamespace
  • ReflectionClass::isAnonymous ≫
  • PHP Manual
  • ReflectionClass
  • 抽象クラスであるかどうかを調べる

ReflectionClass::isAbstract

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isAbstract — 抽象クラスであるかどうかを調べる

説明

public ReflectionClass::isAbstract(): bool

抽象クラスであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isAbstract() の例

<?php
class TestClass { }
abstract class TestAbstractClass { }

$testClass = new ReflectionClass('TestClass');
$abstractClass = new ReflectionClass('TestAbstractClass');

var_dump($testClass->isAbstract());
var_dump($abstractClass->isAbstract());
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionClass::isInterface() - このクラスがインターフェイスであるかどうかを調べる
  • クラスの抽象化


クラスが無名クラスかを調べる

  • ≪ ReflectionClass::isAbstract
  • ReflectionClass::isCloneable ≫
  • PHP Manual
  • ReflectionClass
  • クラスが無名クラスかを調べる

ReflectionClass::isAnonymous

(PHP 7, PHP 8)

ReflectionClass::isAnonymous — クラスが無名クラスかを調べる

説明

public ReflectionClass::isAnonymous(): bool

クラスが無名クラスかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isAnonymous() の例

<?php
class TestClass {}
$anonClass = new class {};

$normalClass = new ReflectionClass('TestClass');
$anonClass = new ReflectionClass($anonClass);

var_dump($normalClass->isAnonymous());
var_dump($anonClass->isAnonymous());

?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionClass::isFinal() - final クラスであるかどうかを調べる


このクラスがクローン可能かどうかを返す

  • ≪ ReflectionClass::isAnonymous
  • ReflectionClass::isEnum ≫
  • PHP Manual
  • ReflectionClass
  • このクラスがクローン可能かどうかを返す

ReflectionClass::isCloneable

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionClass::isCloneable — このクラスがクローン可能かどうかを返す

説明

public ReflectionClass::isCloneable(): bool

このクラスがクローン可能かどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

このクラスがクローン可能である場合に true、そうでない場合に false を返します。

例

例1 ReflectionClass::isCloneable() の基本的な使用例

<?php
class NotCloneable {
public $var1;

private function __clone() {
}
}

class Cloneable {
public $var1;
}

$notCloneable = new ReflectionClass('NotCloneable');
$cloneable = new ReflectionClass('Cloneable');

var_dump($notCloneable->isCloneable());
var_dump($cloneable->isCloneable());
?>

上の例の出力は以下となります。

bool(false)
bool(true)


列挙型であるかどうかを返す

  • ≪ ReflectionClass::isCloneable
  • ReflectionClass::isFinal ≫
  • PHP Manual
  • ReflectionClass
  • 列挙型であるかどうかを返す

ReflectionClass::isEnum

(PHP 8 >= 8.1.0)

ReflectionClass::isEnum — 列挙型であるかどうかを返す

説明

public ReflectionClass::isEnum(): bool

このクラスが、列挙型(Enum) かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

このクラスが 列挙型(Enum) の場合に true を返します。 そうでない場合、false を返します。


final クラスであるかどうかを調べる

  • ≪ ReflectionClass::isEnum
  • ReflectionClass::isInstance ≫
  • PHP Manual
  • ReflectionClass
  • final クラスであるかどうかを調べる

ReflectionClass::isFinal

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isFinal — final クラスであるかどうかを調べる

説明

public ReflectionClass::isFinal(): bool

final クラスであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isFinal() の例

<?php
class TestClass { }
final class TestFinalClass { }

$normalClass = new ReflectionClass('TestClass');
$finalClass = new ReflectionClass('TestFinalClass');

var_dump($normalClass->isFinal());
var_dump($finalClass->isFinal());

?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionClass::isAbstract() - 抽象クラスであるかどうかを調べる
  • Final キーワード


クラスのインスタンスであるかどうかを調べる

  • ≪ ReflectionClass::isFinal
  • ReflectionClass::isInstantiable ≫
  • PHP Manual
  • ReflectionClass
  • クラスのインスタンスであるかどうかを調べる

ReflectionClass::isInstance

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isInstance — クラスのインスタンスであるかどうかを調べる

説明

public ReflectionClass::isInstance(object $object): bool

あるオブジェクトがクラスのインスタンスであるかどうかを調べます。

パラメータ

object

比べたいオブジェクト。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isInstance() の例

<?php
// 使用例
$class = new ReflectionClass('Foo');

if ($class->isInstance($arg)) {
echo "Yes";
}

// これも同じ意味です
if ($arg instanceof Foo) {
echo "Yes";
}

// これも同じ意味です
if (is_a($arg, 'Foo')) {
echo "Yes";
}
?>

上の例の出力は、 たとえば以下のようになります。

Yes
Yes
Yes

参考

  • ReflectionClass::isInterface() - このクラスがインターフェイスであるかどうかを調べる
  • 型演算子 (instanceof)
  • オブジェクト インターフェイス
  • is_a() - オブジェクトが指定された型のものか、部分型であるかを調べる


クラスのインスタンス化が可能であるかどうかを調べる

  • ≪ ReflectionClass::isInstance
  • ReflectionClass::isInterface ≫
  • PHP Manual
  • ReflectionClass
  • クラスのインスタンス化が可能であるかどうかを調べる

ReflectionClass::isInstantiable

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isInstantiable — クラスのインスタンス化が可能であるかどうかを調べる

説明

public ReflectionClass::isInstantiable(): bool

クラスのインスタンス化が可能であるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isInstantiable() の例

<?php
class C { }

interface iface {
function f1();
}

class ifaceImpl implements iface {
function f1() {}
}

abstract class abstractClass {
function f1() { }
abstract function f2();
}

class D extends abstractClass {
function f2() { }
}

trait T {
function f1() {}
}

class privateConstructor {
private function __construct() { }
}

$classes = array(
"C",
"iface",
"ifaceImpl",
"abstractClass",
"D",
"T",
"privateConstructor",
);

foreach($classes as $class ) {
$reflectionClass = new ReflectionClass($class);
echo "Is $class instantiable? ";
var_dump($reflectionClass->isInstantiable());
}

?>

上の例の出力は以下となります。

Is C instantiable?  bool(true)
Is iface instantiable?  bool(false)
Is ifaceImpl instantiable?  bool(true)
Is abstractClass instantiable?  bool(false)
Is D instantiable?  bool(true)
Is T instantiable?  bool(false)
Is privateConstructor instantiable?  bool(false)

参考

  • ReflectionClass::isInstance() - クラスのインスタンスであるかどうかを調べる


このクラスがインターフェイスであるかどうかを調べる

  • ≪ ReflectionClass::isInstantiable
  • ReflectionClass::isInternal ≫
  • PHP Manual
  • ReflectionClass
  • このクラスがインターフェイスであるかどうかを調べる

ReflectionClass::isInterface

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isInterface — このクラスがインターフェイスであるかどうかを調べる

説明

public ReflectionClass::isInterface(): bool

このクラスがインターフェイスであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isInterface() の基本的な使用例

<?php
interface SomeInterface {
public function interfaceMethod();
}

$class = new ReflectionClass('SomeInterface');
var_dump($class->isInterface());
?>

上の例の出力は以下となります。

bool(true)

参考

  • ReflectionClass::isInstance() - クラスのインスタンスであるかどうかを調べる


拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる

  • ≪ ReflectionClass::isInterface
  • ReflectionClass::isIterable ≫
  • PHP Manual
  • ReflectionClass
  • 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる

ReflectionClass::isInternal

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isInternal — 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる

説明

public ReflectionClass::isInternal(): bool

そのクラスが拡張モジュールやコアで定義された内部クラスである (ユーザーが定義したものではない) かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 ReflectionClass::isInternal() の基本的な使用例

<?php
$internalclass = new ReflectionClass('ReflectionClass');

class Apple {}
$userclass = new ReflectionClass('Apple');

var_dump($internalclass->isInternal());
var_dump($userclass->isInternal());
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • ReflectionClass::isUserDefined() - ユーザー定義であるかどうかを調べる


このクラスがイテレーション可能かを調べる

  • ≪ ReflectionClass::isInternal
  • ReflectionClass::isIterateable ≫
  • PHP Manual
  • ReflectionClass
  • このクラスがイテレーション可能かを調べる

ReflectionClass::isIterable

(PHP 7 >= 7.2.0, PHP 8)

ReflectionClass::isIterable — このクラスがイテレーション可能かを調べる

説明

public ReflectionClass::isIterable(): bool

このクラスがイテレーション可能か(つまり、foreach の内部で使えるか)を調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 基本的な ReflectionClass::isIterable() の例

<?php

class IteratorClass implements Iterator {
public function __construct() { }
public function key() { }
public function current() { }
function next() { }
function valid() { }
function rewind() { }
}
class DerivedClass extends IteratorClass { }
class NonIterator { }

function dump_iterable($class) {
$reflection = new ReflectionClass($class);
var_dump($reflection->isIterable());
}

$classes = array("ArrayObject", "IteratorClass", "DerivedClass", "NonIterator");

foreach ($classes as $class) {
echo "Is $class iterable? ";
dump_iterable($class);
}
?>

上の例の出力は以下となります。

Is ArrayObject iterable? bool(true)
Is IteratorClass iterable? bool(true)
Is DerivedClass iterable? bool(true)
Is NonIterator iterable? bool(false)

参考

  • ReflectionClass::__construct() - ReflectionClass を作成する


のエイリアス ReflectionClass::isIterable

  • ≪ ReflectionClass::isIterable
  • ReflectionClass::isReadOnly ≫
  • PHP Manual
  • ReflectionClass
  • のエイリアス ReflectionClass::isIterable

ReflectionClass::isIterateable

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isIterateable — のエイリアス ReflectionClass::isIterable()

説明

のエイリアス ReflectionClass::isIterable()

PHP 7.2.0 以降は、スペルミスがある RefectionClass::isIterateable() の代わりに、 ReflectionClass::isIterable() を使うのが好ましいです。


クラスが readonly かを調べる

  • ≪ ReflectionClass::isIterateable
  • ReflectionClass::isSubclassOf ≫
  • PHP Manual
  • ReflectionClass
  • クラスが readonly かを調べる

ReflectionClass::isReadOnly

(PHP 8 >= 8.2.0)

ReflectionClass::isReadOnly — クラスが readonly かを調べる

説明

public ReflectionClass::isReadOnly(): bool

クラスが readonly かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クラスが readonly の場合は true を返します。そうでない場合、false を返します。

例

例1 ReflectionClass::isReadOnly() の例

<?php
class TestClass { }
readonly class TestReadOnlyClass { }

$normalClass = new ReflectionClass('TestClass');
$readonlyClass = new ReflectionClass('TestReadOnlyClass');

var_dump($normalClass->isReadOnly());
var_dump($readonlyClass->isReadOnly());

?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionClass::isAbstract() - 抽象クラスであるかどうかを調べる
  • 読み取り専用クラス


サブクラスであるかどうかを調べる

  • ≪ ReflectionClass::isReadOnly
  • ReflectionClass::isTrait ≫
  • PHP Manual
  • ReflectionClass
  • サブクラスであるかどうかを調べる

ReflectionClass::isSubclassOf

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isSubclassOf — サブクラスであるかどうかを調べる

説明

public ReflectionClass::isSubclassOf(ReflectionClass|string $class): bool

指定したクラスを継承している、あるいは指定したインターフェイスを実装しているかどうかを調べます。

パラメータ

class

調べたいクラス名の string または、ReflectionClass のオブジェクト

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ReflectionClass::isInterface() - このクラスがインターフェイスであるかどうかを調べる
  • ReflectionClass::implementsInterface() - インターフェイスの実装を調べる
  • is_subclass_of() - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる
  • get_parent_class() - オブジェクトの親クラスの名前を取得する


トレイトであるかどうかを返す

  • ≪ ReflectionClass::isSubclassOf
  • ReflectionClass::isUserDefined ≫
  • PHP Manual
  • ReflectionClass
  • トレイトであるかどうかを返す

ReflectionClass::isTrait

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionClass::isTrait — トレイトであるかどうかを返す

説明

public ReflectionClass::isTrait(): bool

ReflectionClass が、トレイトを参照しているかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

これがトレイトである場合に true、そうでない場合に false を返します。


ユーザー定義であるかどうかを調べる

  • ≪ ReflectionClass::isTrait
  • ReflectionClass::newInstance ≫
  • PHP Manual
  • ReflectionClass
  • ユーザー定義であるかどうかを調べる

ReflectionClass::isUserDefined

(PHP 5, PHP 7, PHP 8)

ReflectionClass::isUserDefined — ユーザー定義であるかどうかを調べる

説明

public ReflectionClass::isUserDefined(): bool

そのクラスが (内部クラスではなく) ユーザーが定義したものであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • ReflectionClass::isInternal() - 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる


指定した引数でクラスの新しいインスタンスを作成する

  • ≪ ReflectionClass::isUserDefined
  • ReflectionClass::newInstanceArgs ≫
  • PHP Manual
  • ReflectionClass
  • 指定した引数でクラスの新しいインスタンスを作成する

ReflectionClass::newInstance

(PHP 5, PHP 7, PHP 8)

ReflectionClass::newInstance — 指定した引数でクラスの新しいインスタンスを作成する

説明

public ReflectionClass::newInstance(mixed ...$args): object

クラスの新しいインスタンスを作成します。指定した引数をクラスのコンストラクタに渡します。

パラメータ

args

可変長の引数を受け付け、それを call_user_func() と同じ方式でクラスのコンストラクタに渡します。

戻り値

エラー / 例外

コンストラクタが public でない場合は ReflectionException が発生します。

クラスにコンストラクタがないときに args を指定すると ReflectionException が発生します。

参考

  • ReflectionClass::newInstanceArgs() - 指定した引数でクラスの新しいインスタンスを作成する
  • ReflectionClass::newInstanceWithoutConstructor() - コンストラクタを起動せずに新しいクラスのインスタンスを作成する


指定した引数でクラスの新しいインスタンスを作成する

  • ≪ ReflectionClass::newInstance
  • ReflectionClass::newInstanceWithoutConstructor ≫
  • PHP Manual
  • ReflectionClass
  • 指定した引数でクラスの新しいインスタンスを作成する

ReflectionClass::newInstanceArgs

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

ReflectionClass::newInstanceArgs — 指定した引数でクラスの新しいインスタンスを作成する

説明

public ReflectionClass::newInstanceArgs(array $args = []): ?object

クラスの新しいインスタンスを作成します。指定した引数をクラスのコンストラクタに渡します。

パラメータ

args

クラスのコンストラクタに渡すパラメータを配列で指定します。

戻り値

クラスの新しいインスタンスを返します。 失敗した場合は null を返します。

エラー / 例外

コンストラクタが public でない場合は ReflectionException が発生します。

クラスにコンストラクタがないときに args を指定すると ReflectionException が発生します。

例

例1 ReflectionClass::newInstanceArgs() の基本的な使用例

<?php
$class = new ReflectionClass('ReflectionFunction');
$instance = $class->newInstanceArgs(array('substr'));
var_dump($instance);
?>

上の例の出力は以下となります。

object(ReflectionFunction)#2 (1) {
  ["name"]=>
  string(6) "substr"
}

参考

  • ReflectionClass::newInstance() - 指定した引数でクラスの新しいインスタンスを作成する
  • ReflectionClass::newInstanceWithoutConstructor() - コンストラクタを起動せずに新しいクラスのインスタンスを作成する


コンストラクタを起動せずに新しいクラスのインスタンスを作成する

  • ≪ ReflectionClass::newInstanceArgs
  • ReflectionClass::setStaticPropertyValue ≫
  • PHP Manual
  • ReflectionClass
  • コンストラクタを起動せずに新しいクラスのインスタンスを作成する

ReflectionClass::newInstanceWithoutConstructor

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionClass::newInstanceWithoutConstructor — コンストラクタを起動せずに新しいクラスのインスタンスを作成する

説明

public ReflectionClass::newInstanceWithoutConstructor(): object

クラスの新しいインスタンスを、そのクラスのコンストラクタを実行せずに作成します。

パラメータ

戻り値

エラー / 例外

そのクラスが内部クラスであり、コンストラクタを実行せずにインスタンスを作成することができなかった場合に ReflectionException が発生します。 この例外が発生するのは、 final な内部クラスに限られます。

参考

  • ReflectionClass::newInstance() - 指定した引数でクラスの新しいインスタンスを作成する
  • ReflectionClass::newInstanceArgs() - 指定した引数でクラスの新しいインスタンスを作成する


staticプロパティの値を設定する

  • ≪ ReflectionClass::newInstanceWithoutConstructor
  • ReflectionClass::__toString ≫
  • PHP Manual
  • ReflectionClass
  • staticプロパティの値を設定する

ReflectionClass::setStaticPropertyValue

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionClass::setStaticPropertyValue — staticプロパティの値を設定する

説明

public ReflectionClass::setStaticPropertyValue(string $name, mixed $value): void

staticプロパティの値を設定します。

パラメータ

name

プロパティの名前。

value

新しいプロパティの値。

戻り値

値を返しません。

参考

  • ReflectionClass::getStaticPropertyValue() - staticプロパティの値を取得する


ReflectionClass オブジェクトの文字列表現を返す

  • ≪ ReflectionClass::setStaticPropertyValue
  • ReflectionClassConstant ≫
  • PHP Manual
  • ReflectionClass
  • ReflectionClass オブジェクトの文字列表現を返す

ReflectionClass::__toString

(PHP 5, PHP 7, PHP 8)

ReflectionClass::__toString — ReflectionClass オブジェクトの文字列表現を返す

説明

public ReflectionClass::__toString(): string

ReflectionClass オブジェクトの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

この ReflectionClass インスタンスの文字列表現を返します。

例

例1 ReflectionClass::__toString() の例

<?php
$reflectionClass = new ReflectionClass('Exception');
echo $reflectionClass->__toString();
?>

上の例の出力は以下となります。

Class [ <internal:Core> class Exception ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [7] {
    Property [ <default> protected $message ]
    Property [ <default> private $string ]
    Property [ <default> protected $code ]
    Property [ <default> protected $file ]
    Property [ <default> protected $line ]
    Property [ <default> private $trace ]
    Property [ <default> private $previous ]
  }

  - Methods [10] {
    Method [ <internal:Core> final private method __clone ] {
    }

    Method [ <internal:Core, ctor> public method __construct ] {

      - Parameters [3] {
        Parameter #0 [ <optional> $message ]
        Parameter #1 [ <optional> $code ]
        Parameter #2 [ <optional> $previous ]
      }
    }

    Method [ <internal:Core> final public method getMessage ] {
    }

    Method [ <internal:Core> final public method getCode ] {
    }

    Method [ <internal:Core> final public method getFile ] {
    }

    Method [ <internal:Core> final public method getLine ] {
    }

    Method [ <internal:Core> final public method getTrace ] {
    }

    Method [ <internal:Core> final public method getPrevious ] {
    }

    Method [ <internal:Core> final public method getTraceAsString ] {
    }

    Method [ <internal:Core> public method __toString ] {
    }
  }
}

参考

  • ReflectionClass::export() - クラスをエクスポートする
  • __toString()


ReflectionClassConstant クラス

(PHP 7 >= 7.1.0, PHP 8)

はじめに

ReflectionClassConstant クラスは、クラス定数に関する情報を報告します。

クラス概要

class ReflectionClassConstant implements Reflector {
/* 定数 */
public const int IS_PUBLIC;
public const int IS_PROTECTED;
public const int IS_PRIVATE;
public const int IS_FINAL;
/* プロパティ */
public string $name;
public string $class;
/* メソッド */
public __construct(object|string $class, string $constant)
public static export(mixed $class, string $name, bool $return = ?): string
public getAttributes(?string $name = null, int $flags = 0): array
public getDeclaringClass(): ReflectionClass
public getDocComment(): string|false
public getModifiers(): int
public getName(): string
public getValue(): mixed
public isEnumCase(): bool
public isFinal(): bool
public isPrivate(): bool
public isProtected(): bool
public isPublic(): bool
public __toString(): string
}

プロパティ

name

クラス定数の名前。読み取り専用です。 書き込もうとすると ReflectionException がスローされます。

class

クラス定数が定義されたクラス名。読み取り専用です。 書き込もうとすると ReflectionException がスローされます。

定義済み定数

ReflectionClassConstant の修飾子

ReflectionClassConstant::IS_PUBLIC

アクセス権が public であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 256 でした。

ReflectionClassConstant::IS_PROTECTED

アクセス権が protected であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 512 でした。

ReflectionClassConstant::IS_PRIVATE

アクセス権が private であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 1024 でした。

ReflectionClassConstant::IS_FINAL

定数が final であることを示します。 PHP 8.1.0 以降で利用可能です。

注意:

これらの定数の値は、PHP のバージョンが異なると変更される可能性があります。 これらの値を直接用いず、常に定数を使うことを推奨します。

変更履歴

バージョン | 説明
8.0.0 | ReflectionClassConstant::export() は、削除されました。

目次

  • ReflectionClassConstant::__construct — ReflectionClassConstant を構築する
  • ReflectionClassConstant::export — リフレクションをエクスポートする
  • ReflectionClassConstant::getAttributes — アトリビュートを取得する
  • ReflectionClassConstant::getDeclaringClass — 定数を宣言しているクラスを取得する
  • ReflectionClassConstant::getDocComment — クラス定数のドキュメントコメントを取得する
  • ReflectionClassConstant::getModifiers — クラス定数の修飾子を取得する
  • ReflectionClassConstant::getName — 定数名を取得する
  • ReflectionClassConstant::getValue — 値を取得する
  • ReflectionClassConstant::isEnumCase — クラス定数が、列挙型の case かどうかを調べる
  • ReflectionClassConstant::isFinal — クラス定数が final かどうかを調べる
  • ReflectionClassConstant::isPrivate — クラス定数がprivateかを調べる
  • ReflectionClassConstant::isProtected — クラス定数が protected かを調べる
  • ReflectionClassConstant::isPublic — クラス定数が public かを調べる
  • ReflectionClassConstant::__toString — ReflectionClassConstant オブジェクトの文字列表現を返す


ReflectionClassConstant を構築する

  • ≪ ReflectionClassConstant
  • ReflectionClassConstant::export ≫
  • PHP Manual
  • ReflectionClassConstant
  • ReflectionClassConstant を構築する

ReflectionClassConstant::__construct

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::__construct — ReflectionClassConstant を構築する

説明

public ReflectionClassConstant::__construct(object|string $class, string $constant)

新しい ReflectionClassConstant を構築します。

パラメータ

class

リフレクションするクラス名を含んだ文字列か、object

constant

クラス定数の名前

エラー / 例外

与えられたクラス定数が存在しない場合は、Exception をスローします。

参考

  • Constructors


リフレクションをエクスポートする

  • ≪ ReflectionClassConstant::__construct
  • ReflectionClassConstant::getAttributes ≫
  • PHP Manual
  • ReflectionClassConstant
  • リフレクションをエクスポートする

ReflectionClassConstant::export

(PHP 7 >= 7.1.0)

ReflectionClassConstant::export — リフレクションをエクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionClassConstant::export(mixed $class, string $name, bool $return = ?): string

リフレクションをエクスポートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

class

エクスポートするリフレクション。

name

クラス定数の名前

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

参考

  • ReflectionClassConstant::__toString() - ReflectionClassConstant オブジェクトの文字列表現を返す


アトリビュートを取得する

  • ≪ ReflectionClassConstant::export
  • ReflectionClassConstant::getDeclaringClass ≫
  • PHP Manual
  • ReflectionClassConstant
  • アトリビュートを取得する

ReflectionClassConstant::getAttributes

(PHP 8)

ReflectionClassConstant::getAttributes — アトリビュートを取得する

説明

public ReflectionClassConstant::getAttributes(?string $name = null, int $flags = 0): array

このクラス定数上で宣言されている全てのアトリビュートを ReflectionAttribute の配列として返します。

パラメータ

name

指定したクラス名にマッチするアトリビュートの、 ReflectionAttribute のみを含むようにフィルタします。

flags

name が指定されていた場合に、 結果をどうフィルタするかを決めるフラグ。

デフォルトは 0 です。 この場合、アトリビュートのクラス名が name であるものだけを返します。

他の利用可能なオプションは、 ReflectionAttribute::IS_INSTANCEOF です。 この場合、フィルタリングに instanceof を使います。

戻り値

アトリビュートの配列を、 ReflectionAttribute オブジェクトの配列として返します。

例

例1 基本的な使い方

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

class Basket {
#[Fruit]
#[Red]
public const APPLE = 'apple';
}

$classConstant = new ReflectionClassConstant('Basket', 'APPLE');
$attributes = $classConstant->getAttributes();
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
    [1] => Red
)

例2 クラス名で結果をフィルタする

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

class Basket {
#[Fruit]
#[Red]
public const APPLE = 'apple';
}

$classConstant = new ReflectionClassConstant('Basket', 'APPLE');
$attributes = $classConstant->getAttributes('Fruit');
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
)

例3 クラス名、かつ継承も考慮して結果をフィルタする

<?php
interface Color {
}

#[Attribute]
class Fruit {
}

#[Attribute]
class Red implements Color {
}

class Basket {
#[Fruit]
#[Red]
public const APPLE = 'apple';
}

$classConstant = new ReflectionClassConstant('Basket', 'APPLE');
$attributes = $classConstant->getAttributes('Color', ReflectionAttribute::IS_INSTANCEOF);
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Red
)

参考

  • ReflectionClass::getAttributes() - アトリビュートを取得する
  • ReflectionFunctionAbstract::getAttributes() - アトリビュートを取得する
  • ReflectionParameter::getAttributes() - アトリビュートを取得する
  • ReflectionProperty::getAttributes() - アトリビュートを取得する


定数を宣言しているクラスを取得する

  • ≪ ReflectionClassConstant::getAttributes
  • ReflectionClassConstant::getDocComment ≫
  • PHP Manual
  • ReflectionClassConstant
  • 定数を宣言しているクラスを取得する

ReflectionClassConstant::getDeclaringClass

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::getDeclaringClass — 定数を宣言しているクラスを取得する

説明

public ReflectionClassConstant::getDeclaringClass(): ReflectionClass

定数を宣言しているクラスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionClass オブジェクトを返します。


クラス定数のドキュメントコメントを取得する

  • ≪ ReflectionClassConstant::getDeclaringClass
  • ReflectionClassConstant::getModifiers ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数のドキュメントコメントを取得する

ReflectionClassConstant::getDocComment

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::getDocComment — クラス定数のドキュメントコメントを取得する

説明

public ReflectionClassConstant::getDocComment(): string|false

クラス定数のドキュメントコメントを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ドキュメントコメントが存在した場合その文字列。存在しない場合は false を返します。


クラス定数の修飾子を取得する

  • ≪ ReflectionClassConstant::getDocComment
  • ReflectionClassConstant::getName ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数の修飾子を取得する

ReflectionClassConstant::getModifiers

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::getModifiers — クラス定数の修飾子を取得する

説明

public ReflectionClassConstant::getModifiers(): int

クラス定数のアクセス修飾子のビットフィールドを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

アクセス修飾子の数値表現を返します。 これらの修飾子の実際の意味は、 定義済みの定数 で説明しています。

参考

  • Reflection::getModifierNames() - 修飾子の名前を取得する


定数名を取得する

  • ≪ ReflectionClassConstant::getModifiers
  • ReflectionClassConstant::getValue ≫
  • PHP Manual
  • ReflectionClassConstant
  • 定数名を取得する

ReflectionClassConstant::getName

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::getName — 定数名を取得する

説明

public ReflectionClassConstant::getName(): string

パラメータ

この関数にはパラメータはありません。

戻り値

定数の名前を返します。

変更履歴

バージョン | 説明
8.1.0 | name プロパティが初期化されていない場合は、 Error をスローするようになりました。 これより前のバージョンでは、失敗時に false を返していました。


値を取得する

  • ≪ ReflectionClassConstant::getName
  • ReflectionClassConstant::isEnumCase ≫
  • PHP Manual
  • ReflectionClassConstant
  • 値を取得する

ReflectionClassConstant::getValue

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::getValue — 値を取得する

説明

public ReflectionClassConstant::getValue(): mixed

クラス定数の値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス定数の値を返します。


クラス定数が、列挙型の case かどうかを調べる

  • ≪ ReflectionClassConstant::getValue
  • ReflectionClassConstant::isFinal ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数が、列挙型の case かどうかを調べる

ReflectionClassConstant::isEnumCase

(PHP 8 >= 8.1.0)

ReflectionClassConstant::isEnumCase — クラス定数が、列挙型の case かどうかを調べる

説明

public ReflectionClassConstant::isEnumCase(): bool

クラス定数が、列挙型 の case かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス定数が、列挙型の case である場合に true を返します。 そうでない場合、false を返します。

例

例1 ReflectionClassConstant::isEnumCase() の例

通常のクラス定数と、列挙型の case を区別する例です。

<?php
enum Status
{
const BORING_CONSTANT = 'test';
const ENUM_VALUE = Status::PUBLISHED;

case DRAFT;
case PUBLISHED;
case ARCHIVED;
}

$reflection = new ReflectionEnum(Status::class);
foreach ($reflection->getReflectionConstants() as $constant) {
echo "{$constant->name} is ",
$constant->isEnumCase() ? "an enum case" : "a regular class constant",
PHP_EOL;
}
?>

上の例の出力は以下となります。

BORING_CONSTANT is a regular class constant
ENUM_VALUE is a regular class constant
DRAFT is an enum case
PUBLISHED is an enum case
ARCHIVED is an enum case

参考

  • ReflectionEnum


クラス定数が final かどうかを調べる

  • ≪ ReflectionClassConstant::isEnumCase
  • ReflectionClassConstant::isPrivate ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数が final かどうかを調べる

ReflectionClassConstant::isFinal

(PHP 8 >= 8.1.0)

ReflectionClassConstant::isFinal — クラス定数が final かどうかを調べる

説明

public ReflectionClassConstant::isFinal(): bool

クラス定数が final かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス定数が final の場合、true を返します。 そうでない場合、false を返します。

参考

  • ReflectionClassConstant::isPublic() - クラス定数が public かを調べる
  • ReflectionClassConstant::isPrivate() - クラス定数がprivateかを調べる
  • ReflectionClassConstant::isProtected() - クラス定数が protected かを調べる


クラス定数がprivateかを調べる

  • ≪ ReflectionClassConstant::isFinal
  • ReflectionClassConstant::isProtected ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数がprivateかを調べる

ReflectionClassConstant::isPrivate

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::isPrivate — クラス定数がprivateかを調べる

説明

public ReflectionClassConstant::isPrivate(): bool

クラス定数がprivateかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス定数が private なら true を返します。 そうでないなら false を返します。

参考

  • ReflectionClassConstant::isFinal() - クラス定数が final かどうかを調べる
  • ReflectionClassConstant::isPublic() - クラス定数が public かを調べる
  • ReflectionClassConstant::isProtected() - クラス定数が protected かを調べる


クラス定数が protected かを調べる

  • ≪ ReflectionClassConstant::isPrivate
  • ReflectionClassConstant::isPublic ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数が protected かを調べる

ReflectionClassConstant::isProtected

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::isProtected — クラス定数が protected かを調べる

説明

public ReflectionClassConstant::isProtected(): bool

クラス定数が protected かを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス定数が protected なら true を返します。 そうでなければ false を返します。

参考

  • ReflectionClassConstant::isFinal() - クラス定数が final かどうかを調べる
  • ReflectionClassConstant::isPublic() - クラス定数が public かを調べる
  • ReflectionClassConstant::isPrivate() - クラス定数がprivateかを調べる


クラス定数が public かを調べる

  • ≪ ReflectionClassConstant::isProtected
  • ReflectionClassConstant::__toString ≫
  • PHP Manual
  • ReflectionClassConstant
  • クラス定数が public かを調べる

ReflectionClassConstant::isPublic

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::isPublic — クラス定数が public かを調べる

説明

public ReflectionClassConstant::isPublic(): bool

クラス定数が public かを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

クラス定数が public なら true を返します。 そうでないなら、false を返します。

参考

  • ReflectionClassConstant::isFinal() - クラス定数が final かどうかを調べる
  • ReflectionClassConstant::isPrivate() - クラス定数がprivateかを調べる
  • ReflectionClassConstant::isProtected() - クラス定数が protected かを調べる


ReflectionClassConstant オブジェクトの文字列表現を返す

  • ≪ ReflectionClassConstant::isPublic
  • ReflectionEnum ≫
  • PHP Manual
  • ReflectionClassConstant
  • ReflectionClassConstant オブジェクトの文字列表現を返す

ReflectionClassConstant::__toString

(PHP 7 >= 7.1.0, PHP 8)

ReflectionClassConstant::__toString — ReflectionClassConstant オブジェクトの文字列表現を返す

説明

public ReflectionClassConstant::__toString(): string

ReflectionClassConstant オブジェクトの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

この ReflectionClassConstant インスタンスの文字列表現を返します。

参考

  • ReflectionClassConstant::export() - リフレクションをエクスポートする
  • __toString()


ReflectionEnum クラス

(PHP 8 >= 8.1.0)

はじめに

ReflectionEnum クラスは、 列挙型に関する情報を報告します。

クラス概要

class ReflectionEnum extends ReflectionClass {
/* 継承した定数 */
public const int ReflectionClass::IS_IMPLICIT_ABSTRACT;
public const int ReflectionClass::IS_EXPLICIT_ABSTRACT;
public const int ReflectionClass::IS_FINAL;
public const int ReflectionClass::IS_READONLY;
/* 継承したプロパティ */
public string $name;
/* メソッド */
public __construct(object|string $objectOrClass)
public getBackingType(): ?ReflectionNamedType
public getCase(string $name): ReflectionEnumUnitCase
public getCases(): array
public hasCase(string $name): bool
public isBacked(): bool
/* 継承したメソッド */
public static ReflectionClass::export(mixed $argument, bool $return = false): string
public ReflectionClass::getAttributes(?string $name = null, int $flags = 0): array
public ReflectionClass::getConstant(string $name): mixed
public ReflectionClass::getConstants(?int $filter = null): array
public ReflectionClass::getConstructor(): ?ReflectionMethod
public ReflectionClass::getDefaultProperties(): array
public ReflectionClass::getDocComment(): string|false
public ReflectionClass::getEndLine(): int|false
public ReflectionClass::getExtension(): ?ReflectionExtension
public ReflectionClass::getExtensionName(): string|false
public ReflectionClass::getFileName(): string|false
public ReflectionClass::getInterfaceNames(): array
public ReflectionClass::getInterfaces(): array
public ReflectionClass::getMethod(string $name): ReflectionMethod
public ReflectionClass::getMethods(?int $filter = null): array
public ReflectionClass::getModifiers(): int
public ReflectionClass::getName(): string
public ReflectionClass::getNamespaceName(): string
public ReflectionClass::getParentClass(): ReflectionClass|false
public ReflectionClass::getProperties(?int $filter = null): array
public ReflectionClass::getProperty(string $name): ReflectionProperty
public ReflectionClass::getReflectionConstant(string $name): ReflectionClassConstant|false
public ReflectionClass::getReflectionConstants(?int $filter = null): array
public ReflectionClass::getShortName(): string
public ReflectionClass::getStartLine(): int|false
public ReflectionClass::getStaticProperties(): array
public ReflectionClass::getStaticPropertyValue(string $name, mixed &$def_value = ?): mixed
public ReflectionClass::getTraitAliases(): array
public ReflectionClass::getTraitNames(): array
public ReflectionClass::getTraits(): array
public ReflectionClass::hasConstant(string $name): bool
public ReflectionClass::hasMethod(string $name): bool
public ReflectionClass::hasProperty(string $name): bool
public ReflectionClass::implementsInterface(ReflectionClass|string $interface): bool
public ReflectionClass::inNamespace(): bool
public ReflectionClass::isAbstract(): bool
public ReflectionClass::isAnonymous(): bool
public ReflectionClass::isCloneable(): bool
public ReflectionClass::isEnum(): bool
public ReflectionClass::isFinal(): bool
public ReflectionClass::isInstance(object $object): bool
public ReflectionClass::isInstantiable(): bool
public ReflectionClass::isInterface(): bool
public ReflectionClass::isInternal(): bool
public ReflectionClass::isIterable(): bool
public ReflectionClass::isReadOnly(): bool
public ReflectionClass::isSubclassOf(ReflectionClass|string $class): bool
public ReflectionClass::isTrait(): bool
public ReflectionClass::isUserDefined(): bool
public ReflectionClass::newInstance(mixed ...$args): object
public ReflectionClass::newInstanceArgs(array $args = []): ?object
public ReflectionClass::newInstanceWithoutConstructor(): object
public ReflectionClass::setStaticPropertyValue(string $name, mixed $value): void
public ReflectionClass::__toString(): string
}

参考

  • 列挙型(Enum)

目次

  • ReflectionEnum::__construct — ReflectionEnum オブジェクトをインスタンス化する
  • ReflectionEnum::getBackingType — 存在する場合に、列挙型が依存する型を取得する
  • ReflectionEnum::getCase — 列挙型の特定の case を返す
  • ReflectionEnum::getCases — 列挙型の全ての case を返す
  • ReflectionEnum::hasCase — 列挙型が case を持つかを調べる
  • ReflectionEnum::isBacked — 列挙型が Backed Enum かを調べる


ReflectionEnum オブジェクトをインスタンス化する

  • ≪ ReflectionEnum
  • ReflectionEnum::getBackingType ≫
  • PHP Manual
  • ReflectionEnum
  • ReflectionEnum オブジェクトをインスタンス化する

ReflectionEnum::__construct

(PHP 8 >= 8.1.0)

ReflectionEnum::__construct — ReflectionEnum オブジェクトをインスタンス化する

説明

public ReflectionEnum::__construct(object|string $objectOrClass)

パラメータ

objectOrClass

列挙型のインスタンス、またはその名前。


存在する場合に、列挙型が依存する型を取得する

  • ≪ ReflectionEnum::__construct
  • ReflectionEnum::getCase ≫
  • PHP Manual
  • ReflectionEnum
  • 存在する場合に、列挙型が依存する型を取得する

ReflectionEnum::getBackingType

(PHP 8 >= 8.1.0)

ReflectionEnum::getBackingType — 存在する場合に、列挙型が依存する型を取得する

説明

public ReflectionEnum::getBackingType(): ?ReflectionNamedType

列挙型が Backed Enum の場合、 このメソッドは 列挙型が依存する型を ReflectionType のインスタンスとして返します。 Backed Enum でない場合は、null を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

列挙型が依存する型を ReflectionNamedType として返します。依存する型がない場合は、null を返します。

変更履歴

バージョン | 説明
8.2.0 | 戻り値の型が、 ?ReflectionNamedType として宣言されるようになりました。 これより前のバージョンでは、 ?ReflectionType が宣言されていました。

例

例1 ReflectionEnum::getBackingType() の例

<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}

$rEnum = new ReflectionEnum(Suit::class);

$rBackingType = $rEnum->getBackingType();

var_dump((string)$rBackingType);
?>

上の例の出力は以下となります。

string(6) "string"

参考

  • 列挙型(Enum)
  • ReflectionEnum::isBacked() - 列挙型が Backed Enum かを調べる


列挙型の特定の case を返す

  • ≪ ReflectionEnum::getBackingType
  • ReflectionEnum::getCases ≫
  • PHP Manual
  • ReflectionEnum
  • 列挙型の特定の case を返す

ReflectionEnum::getCase

(PHP 8 >= 8.1.0)

ReflectionEnum::getCase — 列挙型の特定の case を返す

説明

public ReflectionEnum::getCase(string $name): ReflectionEnumUnitCase

列挙型の特定の case を名前で指定すると、 リフレクションオブジェクトを返します。 指定された case が定義されていない場合、 ReflectionException がスローされます。

パラメータ

name

取得する case の名前。

戻り値

ReflectionEnumUnitCase または ReflectionEnumBackedCase のインスタンスを適切に返します。

例

例1 ReflectionEnum::getCase() の例

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

$rEnum = new ReflectionEnum(Suit::class);

$rCase = $rEnum->getCase('Clubs');

var_dump($rCase->getValue());
?>

上の例の出力は以下となります。

enum(Suit::Clubs)

参考

  • 列挙型(Enum)
  • ReflectionEnum::getCases() - 列挙型の全ての case を返す
  • ReflectionEnum::hasCase() - 列挙型が case を持つかを調べる
  • ReflectionEnum::isBacked() - 列挙型が Backed Enum かを調べる


列挙型の全ての case を返す

  • ≪ ReflectionEnum::getCase
  • ReflectionEnum::hasCase ≫
  • PHP Manual
  • ReflectionEnum
  • 列挙型の全ての case を返す

ReflectionEnum::getCases

(PHP 8 >= 8.1.0)

ReflectionEnum::getCases — 列挙型の全ての case を返す

説明

public ReflectionEnum::getCases(): array

列挙型には、ひとつ以上の case を含めることができます。 このメソッドは、定義済みの全ての case を字句解析順 (つまり、ソースコードに現れる順) に取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

列挙型のリフレクションオブジェクトの配列を返します。 ひとつひとつが、列挙型の case を表します。 Pure Enum の場合、すべてのインスタンスが ReflectionEnumUnitCase になります。 Backed Enum の場合、すべてのインスタンスが ReflectionEnumBackedCase になります。

例

例1 ReflectionEnum::getCases() の例

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

$rEnum = new ReflectionEnum(Suit::class);

$cases = $rEnum->getCases();

foreach ($cases as $rCase) {
var_dump($rCase->getValue());
}
?>

上の例の出力は以下となります。

enum(Suit::Hearts)
enum(Suit::Diamonds)
enum(Suit::Clubs)
enum(Suit::Spades)

参考

  • 列挙型(Enum)
  • ReflectionEnum::getCase() - 列挙型の特定の case を返す
  • ReflectionEnum::isBacked() - 列挙型が Backed Enum かを調べる


列挙型が case を持つかを調べる

  • ≪ ReflectionEnum::getCases
  • ReflectionEnum::isBacked ≫
  • PHP Manual
  • ReflectionEnum
  • 列挙型が case を持つかを調べる

ReflectionEnum::hasCase

(PHP 8 >= 8.1.0)

ReflectionEnum::hasCase — 列挙型が case を持つかを調べる

説明

public ReflectionEnum::hasCase(string $name): bool

指定された case が列挙型に定義されているかを判定します。

パラメータ

name

調べる case の名前。

戻り値

case が定義されていたら true を返します。 そうでない場合、false を返します。

例

例1 ReflectionEnum::hasCase() の例

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

$rEnum = new ReflectionEnum(Suit::class);

var_dump($rEnum->hasCase('Hearts'));
var_dump($rEnum->hasCase('Horseshoes'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • 列挙型(Enum)
  • ReflectionEnum::getCase() - 列挙型の特定の case を返す
  • ReflectionEnum::getCases() - 列挙型の全ての case を返す


列挙型が Backed Enum かを調べる

  • ≪ ReflectionEnum::hasCase
  • ReflectionEnumUnitCase ≫
  • PHP Manual
  • ReflectionEnum
  • 列挙型が Backed Enum かを調べる

ReflectionEnum::isBacked

(PHP 8 >= 8.1.0)

ReflectionEnum::isBacked — 列挙型が Backed Enum かを調べる

説明

public ReflectionEnum::isBacked(): bool

Backed Enum は、 ネイティブのスカラー型と同等の情報を持つ列挙型です。 文字列か、整数のどちらかです。 全ての列挙型が Backed Enum であるとは限りません。

パラメータ

この関数にはパラメータはありません。

戻り値

列挙型がスカラーと同等の Backed Enum の場合は true を返します。 そうでない場合は、false を返します。

例

例1 ReflectionEnum::isBacked() の例

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

enum BackedSuit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}

var_dump((new ReflectionEnum(Suit::class))->isBacked());
var_dump((new ReflectionEnum(BackedSuit::class))->isBacked());
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • 列挙型(Enum)
  • ReflectionEnum::getBackingType() - 存在する場合に、列挙型が依存する型を取得する


ReflectionEnumUnitCase クラス

(PHP 8 >= 8.1.0)

はじめに

ReflectionEnumUnitCase クラスは、 列挙型 の case に関する情報を報告します。 これは、スカラー型の情報を持っていません。

クラス概要

class ReflectionEnumUnitCase extends ReflectionClassConstant {
/* 継承した定数 */
public const int ReflectionClassConstant::IS_PUBLIC;
public const int ReflectionClassConstant::IS_PROTECTED;
public const int ReflectionClassConstant::IS_PRIVATE;
public const int ReflectionClassConstant::IS_FINAL;
/* 継承したプロパティ */
public string $name;
public string $class;
/* メソッド */
public __construct(object|string $class, string $constant)
public getEnum(): ReflectionEnum
public getValue(): UnitEnum
/* 継承したメソッド */
public static ReflectionClassConstant::export(mixed $class, string $name, bool $return = ?): string
public ReflectionClassConstant::getAttributes(?string $name = null, int $flags = 0): array
public ReflectionClassConstant::getDeclaringClass(): ReflectionClass
public ReflectionClassConstant::getDocComment(): string|false
public ReflectionClassConstant::getModifiers(): int
public ReflectionClassConstant::getName(): string
public ReflectionClassConstant::getValue(): mixed
public ReflectionClassConstant::isEnumCase(): bool
public ReflectionClassConstant::isFinal(): bool
public ReflectionClassConstant::isPrivate(): bool
public ReflectionClassConstant::isProtected(): bool
public ReflectionClassConstant::isPublic(): bool
public ReflectionClassConstant::__toString(): string
}

参考

  • 列挙型(Enum)
  • ReflectionEnumBackedCase

目次

  • ReflectionEnumUnitCase::__construct — ReflectionEnumUnitCase オブジェクトをインスタンス化する
  • ReflectionEnumUnitCase::getEnum — この case が属するリフレクションオブジェクトを取得する
  • ReflectionEnumUnitCase::getValue — このリフレクションオブジェクトが表す case オブジェクトを取得する


ReflectionEnumUnitCase オブジェクトをインスタンス化する

  • ≪ ReflectionEnumUnitCase
  • ReflectionEnumUnitCase::getEnum ≫
  • PHP Manual
  • ReflectionEnumUnitCase
  • ReflectionEnumUnitCase オブジェクトをインスタンス化する

ReflectionEnumUnitCase::__construct

(PHP 8 >= 8.1.0)

ReflectionEnumUnitCase::__construct — ReflectionEnumUnitCase オブジェクトをインスタンス化する

説明

public ReflectionEnumUnitCase::__construct(object|string $class, string $constant)

パラメータ

class

列挙型のインスタンス、またはその名前。

constant

列挙型の定数名。


この case が属するリフレクションオブジェクトを取得する

  • ≪ ReflectionEnumUnitCase::__construct
  • ReflectionEnumUnitCase::getValue ≫
  • PHP Manual
  • ReflectionEnumUnitCase
  • この case が属するリフレクションオブジェクトを取得する

ReflectionEnumUnitCase::getEnum

(PHP 8 >= 8.1.0)

ReflectionEnumUnitCase::getEnum — この case が属するリフレクションオブジェクトを取得する

説明

public ReflectionEnumUnitCase::getEnum(): ReflectionEnum

この case が属するリフレクションオブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

この case が属する列挙型を示す ReflectionEnum のインスタンスを返します。

参考

  • 列挙型(Enum)


このリフレクションオブジェクトが表す case オブジェクトを取得する

  • ≪ ReflectionEnumUnitCase::getEnum
  • ReflectionEnumBackedCase ≫
  • PHP Manual
  • ReflectionEnumUnitCase
  • このリフレクションオブジェクトが表す case オブジェクトを取得する

ReflectionEnumUnitCase::getValue

(PHP 8 >= 8.1.0)

ReflectionEnumUnitCase::getValue — このリフレクションオブジェクトが表す case オブジェクトを取得する

説明

public ReflectionEnumUnitCase::getValue(): UnitEnum

このリフレクションオブジェクトが表す 列挙型の case オブジェクトを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

このリフレクションオブジェクトが表す 列挙型の case オブジェクトを返します。

例

例1 ReflectionEnum::getValue() の例

<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}

$rEnum = new ReflectionEnum(Suit::class);

$rCase = $rEnum->getCase('Diamonds');

var_dump($rCase->getValue());
?>

上の例の出力は以下となります。

enum(Suit::Diamonds)

参考

  • 列挙型(Enum)


ReflectionEnumBackedCase クラス

(PHP 8 >= 8.1.0)

はじめに

ReflectionEnumBackedCase クラスは、 Backed Enum の case に関する情報を報告します。 これは、スカラー型の情報を持っています。

クラス概要

class ReflectionEnumBackedCase extends ReflectionEnumUnitCase {
/* 継承した定数 */
public const int ReflectionClassConstant::IS_PUBLIC;
public const int ReflectionClassConstant::IS_PROTECTED;
public const int ReflectionClassConstant::IS_PRIVATE;
public const int ReflectionClassConstant::IS_FINAL;
/* 継承したプロパティ */
public string $name;
public string $class;
/* メソッド */
public __construct(object|string $class, string $constant)
public getBackingValue(): int|string
/* 継承したメソッド */
public ReflectionEnumUnitCase::getEnum(): ReflectionEnum
public ReflectionEnumUnitCase::getValue(): UnitEnum
public static ReflectionClassConstant::export(mixed $class, string $name, bool $return = ?): string
public ReflectionClassConstant::getAttributes(?string $name = null, int $flags = 0): array
public ReflectionClassConstant::getDeclaringClass(): ReflectionClass
public ReflectionClassConstant::getDocComment(): string|false
public ReflectionClassConstant::getModifiers(): int
public ReflectionClassConstant::getName(): string
public ReflectionClassConstant::getValue(): mixed
public ReflectionClassConstant::isEnumCase(): bool
public ReflectionClassConstant::isFinal(): bool
public ReflectionClassConstant::isPrivate(): bool
public ReflectionClassConstant::isProtected(): bool
public ReflectionClassConstant::isPublic(): bool
public ReflectionClassConstant::__toString(): string
}

参考

  • 列挙型(Enum)
  • ReflectionEnumUnitCase

目次

  • ReflectionEnumBackedCase::__construct — ReflectionEnumBackedCase オブジェクトをインスタンス化する
  • ReflectionEnumBackedCase::getBackingValue — Backed Enum の case が持つスカラー値を取得する


ReflectionEnumBackedCase オブジェクトをインスタンス化する

  • ≪ ReflectionEnumBackedCase
  • ReflectionEnumBackedCase::getBackingValue ≫
  • PHP Manual
  • ReflectionEnumBackedCase
  • ReflectionEnumBackedCase オブジェクトをインスタンス化する

ReflectionEnumBackedCase::__construct

(PHP 8 >= 8.1.0)

ReflectionEnumBackedCase::__construct — ReflectionEnumBackedCase オブジェクトをインスタンス化する

説明

public ReflectionEnumBackedCase::__construct(object|string $class, string $constant)

パラメータ

class

列挙型のインスタンス、またはその名前。

constant

列挙型の定数名。


Backed Enum の case が持つスカラー値を取得する

  • ≪ ReflectionEnumBackedCase::__construct
  • ReflectionZendExtension ≫
  • PHP Manual
  • ReflectionEnumBackedCase
  • Backed Enum の case が持つスカラー値を取得する

ReflectionEnumBackedCase::getBackingValue

(PHP 8 >= 8.1.0)

ReflectionEnumBackedCase::getBackingValue — Backed Enum の case が持つスカラー値を取得する

説明

public ReflectionEnumBackedCase::getBackingValue(): int|string

Backed Enum の case が持つスカラー値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

この列挙型の case が持つスカラーの値を返します。

例

例1 ReflectionEnum::getBackingValue() の例

<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}

$rEnum = new ReflectionEnum(Suit::class);

$rCase = $rEnum->getCase('Spades');

var_dump($rCase->getBackingValue());
?>

上の例の出力は以下となります。

string(1) "S"

参考

  • 列挙型(Enum)


ReflectionZendExtension クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

はじめに

クラス概要

class ReflectionZendExtension implements Reflector {
/* プロパティ */
public string $name;
/* メソッド */
public __construct(string $name)
private __clone(): void
public static export(string $name, bool $return = ?): string
public getAuthor(): string
public getCopyright(): string
public getName(): string
public getURL(): string
public getVersion(): string
public __toString(): string
}

プロパティ

name

拡張モジュール名。読み込み専用で、書き込もうとすると ReflectionException をスローします。

変更履歴

バージョン | 説明
8.0.0 | ReflectionZendExtension::export() は、削除されました。

目次

  • ReflectionZendExtension::__clone — Clone のハンドラ
  • ReflectionZendExtension::__construct — ReflectionZendExtension オブジェクトを作成する
  • ReflectionZendExtension::export — エクスポート
  • ReflectionZendExtension::getAuthor — 作者を取得する
  • ReflectionZendExtension::getCopyright — 著作権情報を取得する
  • ReflectionZendExtension::getName — 名前を取得する
  • ReflectionZendExtension::getURL — URL を取得する
  • ReflectionZendExtension::getVersion — バージョンを取得する
  • ReflectionZendExtension::__toString — 文字列変換のハンドラ


Clone のハンドラ

  • ≪ ReflectionZendExtension
  • ReflectionZendExtension::__construct ≫
  • PHP Manual
  • ReflectionZendExtension
  • Clone のハンドラ

ReflectionZendExtension::__clone

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::__clone — Clone のハンドラ

説明

private ReflectionZendExtension::__clone(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

変更履歴

バージョン | 説明
8.1.0 | このメソッドは、final ではなくなりました。


ReflectionZendExtension オブジェクトを作成する

  • ≪ ReflectionZendExtension::__clone
  • ReflectionZendExtension::export ≫
  • PHP Manual
  • ReflectionZendExtension
  • ReflectionZendExtension オブジェクトを作成する

ReflectionZendExtension::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::__construct — ReflectionZendExtension オブジェクトを作成する

説明

public ReflectionZendExtension::__construct(string $name)

新しい ReflectionZendExtension オブジェクトを作成します。

パラメータ

name

拡張機能の名前

エラー / 例外

リフレクションする拡張機能が存在しない場合、 ReflectionException がスローされます。


エクスポート

  • ≪ ReflectionZendExtension::__construct
  • ReflectionZendExtension::getAuthor ≫
  • PHP Manual
  • ReflectionZendExtension
  • エクスポート

ReflectionZendExtension::export

(PHP 5 >= 5.4.0, PHP 7)

ReflectionZendExtension::export — エクスポート

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionZendExtension::export(string $name, bool $return = ?): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

name

return

戻り値

参考

  • ReflectionClassConstant::__toString() - ReflectionClassConstant オブジェクトの文字列表現を返す


作者を取得する

  • ≪ ReflectionZendExtension::export
  • ReflectionZendExtension::getCopyright ≫
  • PHP Manual
  • ReflectionZendExtension
  • 作者を取得する

ReflectionZendExtension::getAuthor

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::getAuthor — 作者を取得する

説明

public ReflectionZendExtension::getAuthor(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


著作権情報を取得する

  • ≪ ReflectionZendExtension::getAuthor
  • ReflectionZendExtension::getName ≫
  • PHP Manual
  • ReflectionZendExtension
  • 著作権情報を取得する

ReflectionZendExtension::getCopyright

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::getCopyright — 著作権情報を取得する

説明

public ReflectionZendExtension::getCopyright(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


名前を取得する

  • ≪ ReflectionZendExtension::getCopyright
  • ReflectionZendExtension::getURL ≫
  • PHP Manual
  • ReflectionZendExtension
  • 名前を取得する

ReflectionZendExtension::getName

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::getName — 名前を取得する

説明

public ReflectionZendExtension::getName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


URL を取得する

  • ≪ ReflectionZendExtension::getName
  • ReflectionZendExtension::getVersion ≫
  • PHP Manual
  • ReflectionZendExtension
  • URL を取得する

ReflectionZendExtension::getURL

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::getURL — URL を取得する

説明

public ReflectionZendExtension::getURL(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


バージョンを取得する

  • ≪ ReflectionZendExtension::getURL
  • ReflectionZendExtension::__toString ≫
  • PHP Manual
  • ReflectionZendExtension
  • バージョンを取得する

ReflectionZendExtension::getVersion

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::getVersion — バージョンを取得する

説明

public ReflectionZendExtension::getVersion(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


文字列変換のハンドラ

  • ≪ ReflectionZendExtension::getVersion
  • ReflectionExtension ≫
  • PHP Manual
  • ReflectionZendExtension
  • 文字列変換のハンドラ

ReflectionZendExtension::__toString

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionZendExtension::__toString — 文字列変換のハンドラ

説明

public ReflectionZendExtension::__toString(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


ReflectionExtension クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionExtension クラスは 拡張モジュールについての情報を報告します。

クラス概要

class ReflectionExtension implements Reflector {
/* プロパティ */
public string $name;
/* メソッド */
public __construct(string $name)
private __clone(): void
public static export(string $name, string $return = false): string
public getClasses(): array
public getClassNames(): array
public getConstants(): array
public getDependencies(): array
public getFunctions(): array
public getINIEntries(): array
public getName(): string
public getVersion(): ?string
public info(): void
public isPersistent(): bool
public isTemporary(): bool
public __toString(): string
}

プロパティ

name

拡張モジュールの名前。 ReflectionExtension::getName() メソッドをコールするのと同じ。

変更履歴

バージョン | 説明
8.0.0 | ReflectionExtension::export() は、削除されました。

目次

  • ReflectionExtension::__clone — クローンする
  • ReflectionExtension::__construct — ReflectionExtension を作成する
  • ReflectionExtension::export — エクスポートする
  • ReflectionExtension::getClasses — クラスを取得する
  • ReflectionExtension::getClassNames — クラス名を取得する
  • ReflectionExtension::getConstants — 定数を取得する
  • ReflectionExtension::getDependencies — 依存性を取得する
  • ReflectionExtension::getFunctions — 拡張モジュールの関数を取得する
  • ReflectionExtension::getINIEntries — 拡張モジュールの ini エントリを取得する
  • ReflectionExtension::getName — 拡張モジュール名を取得する
  • ReflectionExtension::getVersion — 拡張モジュールのバージョンを取得する
  • ReflectionExtension::info — 拡張モジュールの情報を表示する
  • ReflectionExtension::isPersistent — この拡張モジュールが永続性のあるものかどうかを返す
  • ReflectionExtension::isTemporary — この拡張モジュールが一時的なものかどうかを返す
  • ReflectionExtension::__toString — 文字列に変換する


クローンする

  • ≪ ReflectionExtension
  • ReflectionExtension::__construct ≫
  • PHP Manual
  • ReflectionExtension
  • クローンする

ReflectionExtension::__clone

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::__clone — クローンする

説明

private ReflectionExtension::__clone(): void

このメソッドは、オブジェクトをクローンさせないようにします。 Reflection オブジェクトはクローンすることができません。

パラメータ

この関数にはパラメータはありません。

戻り値

値は返しません。もしコールされれば致命的なエラーとなります。

変更履歴

バージョン | 説明
8.1.0 | このメソッドは、final ではなくなりました。

参考

  • ReflectionExtension::__construct() - ReflectionExtension を作成する
  • オブジェクトのクローン作成


ReflectionExtension を作成する

  • ≪ ReflectionExtension::__clone
  • ReflectionExtension::export ≫
  • PHP Manual
  • ReflectionExtension
  • ReflectionExtension を作成する

ReflectionExtension::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::__construct — ReflectionExtension を作成する

説明

public ReflectionExtension::__construct(string $name)

ReflectionExtension オブジェクトを作成します。

パラメータ

name

拡張モジュールの名前。

エラー / 例外

リフレクションする拡張機能が存在しない場合、 ReflectionException がスローされます。

例

例1 ReflectionExtension の例

<?php
$ext = new ReflectionExtension('Reflection');

printf('Extension: %s (version: %s)', $ext->getName(), $ext->getVersion());
?>

上の例の出力は、 たとえば以下のようになります。

Extension: Reflection (version: $Revision$)

参考

  • ReflectionExtension::info() - 拡張モジュールの情報を表示する
  • コンストラクタ


エクスポートする

  • ≪ ReflectionExtension::__construct
  • ReflectionExtension::getClasses ≫
  • PHP Manual
  • ReflectionExtension
  • エクスポートする

ReflectionExtension::export

(PHP 5, PHP 7)

ReflectionExtension::export — エクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionExtension::export(string $name, string $return = false): string

拡張モジュールの情報をエクスポートします。この関数の出力フォーマットは CLI で引数 --re [extension] を指定したときのものと同じです。

パラメータ

name

エクスポートするリフレクション。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

return パラメータを true に設定すると、エクスポートを文字列で返します。それ以外の場合は null を返します。

参考

  • ReflectionExtension::info() - 拡張モジュールの情報を表示する
  • ReflectionExtension::__toString() - 文字列に変換する


クラスを取得する

  • ≪ ReflectionExtension::export
  • ReflectionExtension::getClassNames ≫
  • PHP Manual
  • ReflectionExtension
  • クラスを取得する

ReflectionExtension::getClasses

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getClasses — クラスを取得する

説明

public ReflectionExtension::getClasses(): array

拡張モジュールのクラス一覧を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionClass オブジェクトの配列を返します。 各要素が、拡張モジュール内のクラスを表します。 クラスが定義されていない場合は空の配列を返します。

例

例1 ReflectionExtension::getClasses() の例

<?php
$ext = new ReflectionExtension('XMLWriter');
var_dump($ext->getClasses());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  ["XMLWriter"]=>
  object(ReflectionClass)#2 (1) {
    ["name"]=>
    string(9) "XMLWriter"
  }
}

参考

  • ReflectionExtension::getClassNames() - クラス名を取得する


クラス名を取得する

  • ≪ ReflectionExtension::getClasses
  • ReflectionExtension::getConstants ≫
  • PHP Manual
  • ReflectionExtension
  • クラス名を取得する

ReflectionExtension::getClassNames

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getClassNames — クラス名を取得する

説明

public ReflectionExtension::getClassNames(): array

拡張モジュールで定義されているのクラス名の一覧を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡張モジュールで定義されているクラス名の配列を返します。 クラスが定義されていない場合は空の配列を返します。

例

例1 ReflectionExtension::getClassNames() の例

<?php
$ext = new ReflectionExtension('XMLWriter');
var_dump($ext->getClassNames());
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  string(9) "XMLWriter"
}

参考

  • ReflectionExtension::getClasses() - クラスを取得する
  • ReflectionExtension::getName() - 拡張モジュール名を取得する


定数を取得する

  • ≪ ReflectionExtension::getClassNames
  • ReflectionExtension::getDependencies ≫
  • PHP Manual
  • ReflectionExtension
  • 定数を取得する

ReflectionExtension::getConstants

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getConstants — 定数を取得する

説明

public ReflectionExtension::getConstants(): array

拡張モジュールで定義されている定数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

定数名をキーとする連想配列を返します。

例

例1 ReflectionExtension::getConstants() の例

<?php
$ext = new ReflectionExtension('DOM');

print_r($ext->getConstants());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [XML_ELEMENT_NODE] => 1
    [XML_ATTRIBUTE_NODE] => 2
    [XML_TEXT_NODE] => 3
    [XML_CDATA_SECTION_NODE] => 4
    [XML_ENTITY_REF_NODE] => 5
    [XML_ENTITY_NODE] => 6
    [XML_PI_NODE] => 7
    [XML_COMMENT_NODE] => 8
    [XML_DOCUMENT_NODE] => 9
    [XML_DOCUMENT_TYPE_NODE] => 10
    [XML_DOCUMENT_FRAG_NODE] => 11
    [XML_NOTATION_NODE] => 12
    [XML_HTML_DOCUMENT_NODE] => 13
    [XML_DTD_NODE] => 14
    [XML_ELEMENT_DECL_NODE] => 15
    [XML_ATTRIBUTE_DECL_NODE] => 16
    [XML_ENTITY_DECL_NODE] => 17
    [XML_NAMESPACE_DECL_NODE] => 18
    [XML_LOCAL_NAMESPACE] => 18
    [XML_ATTRIBUTE_CDATA] => 1
    [XML_ATTRIBUTE_ID] => 2
    [XML_ATTRIBUTE_IDREF] => 3
    [XML_ATTRIBUTE_IDREFS] => 4
    [XML_ATTRIBUTE_ENTITY] => 6
    [XML_ATTRIBUTE_NMTOKEN] => 7
    [XML_ATTRIBUTE_NMTOKENS] => 8
    [XML_ATTRIBUTE_ENUMERATION] => 9
    [XML_ATTRIBUTE_NOTATION] => 10
    [DOM_PHP_ERR] => 0
    [DOM_INDEX_SIZE_ERR] => 1
    [DOMSTRING_SIZE_ERR] => 2
    [DOM_HIERARCHY_REQUEST_ERR] => 3
    [DOM_WRONG_DOCUMENT_ERR] => 4
    [DOM_INVALID_CHARACTER_ERR] => 5
    [DOM_NO_DATA_ALLOWED_ERR] => 6
    [DOM_NO_MODIFICATION_ALLOWED_ERR] => 7
    [DOM_NOT_FOUND_ERR] => 8
    [DOM_NOT_SUPPORTED_ERR] => 9
    [DOM_INUSE_ATTRIBUTE_ERR] => 10
    [DOM_INVALID_STATE_ERR] => 11
    [DOM_SYNTAX_ERR] => 12
    [DOM_INVALID_MODIFICATION_ERR] => 13
    [DOM_NAMESPACE_ERR] => 14
    [DOM_INVALID_ACCESS_ERR] => 15
    [DOM_VALIDATION_ERR] => 16
)

参考

  • ReflectionExtension::getINIEntries() - 拡張モジュールの ini エントリを取得する


依存性を取得する

  • ≪ ReflectionExtension::getConstants
  • ReflectionExtension::getFunctions ≫
  • PHP Manual
  • ReflectionExtension
  • 依存性を取得する

ReflectionExtension::getDependencies

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

ReflectionExtension::getDependencies — 依存性を取得する

説明

public ReflectionExtension::getDependencies(): array

必須の依存性、衝突する依存性の両方を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

依存する拡張モジュールをキー、そして Required、Optional あるいは Conflicts のいずれかを値とする連想配列を返します。

例

例1 ReflectionExtension::getDependencies() の例

<?php
$dom = new ReflectionExtension('dom');

print_r($dom->getDependencies());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [libxml] => Required
    [domxml] => Conflicts
)

参考

  • ReflectionClass::getVersion()


拡張モジュールの関数を取得する

  • ≪ ReflectionExtension::getDependencies
  • ReflectionExtension::getINIEntries ≫
  • PHP Manual
  • ReflectionExtension
  • 拡張モジュールの関数を取得する

ReflectionExtension::getFunctions

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getFunctions — 拡張モジュールの関数を取得する

説明

public ReflectionExtension::getFunctions(): array

拡張モジュールで定義されている関数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionFunction オブジェクトの連想配列を返します。 拡張モジュール内で定義されている関数名がキーとなります。 関数が定義されていない場合は空の配列を返します。

例

例1 ReflectionExtension::getFunctions() の例

<?php
$dom = new ReflectionExtension('SimpleXML');

print_r($dom->getFunctions());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [simplexml_load_file] => ReflectionFunction Object
        (
            [name] => simplexml_load_file
        )

    [simplexml_load_string] => ReflectionFunction Object
        (
            [name] => simplexml_load_string
        )

    [simplexml_import_dom] => ReflectionFunction Object
        (
            [name] => simplexml_import_dom
        )

)

参考

  • ReflectionExtension::getClasses() - クラスを取得する
  • get_extension_funcs() - あるモジュールの関数名を配列として返す


拡張モジュールの ini エントリを取得する

  • ≪ ReflectionExtension::getFunctions
  • ReflectionExtension::getName ≫
  • PHP Manual
  • ReflectionExtension
  • 拡張モジュールの ini エントリを取得する

ReflectionExtension::getINIEntries

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getINIEntries — 拡張モジュールの ini エントリを取得する

説明

public ReflectionExtension::getINIEntries(): array

拡張モジュールの ini エントリを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ini エントリをキー、定義されている値をキーに対応する値とした連想配列を返します。

例

例1 ReflectionExtension::getINIEntries() の例

<?php
$ext = new ReflectionExtension('mysql');

print_r($ext->getINIEntries());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [mysql.allow_persistent] => 1
    [mysql.max_persistent] => -1
    [mysql.max_links] => -1
    [mysql.default_host] =>
    [mysql.default_user] =>
    [mysql.default_password] =>
    [mysql.default_port] =>
    [mysql.default_socket] =>
    [mysql.connect_timeout] => 60
    [mysql.trace_mode] =>
    [mysql.allow_local_infile] => 1
    [mysql.cache_size] => 2000
)

参考

  • ini_get_all() - すべての設定オプションを得る
  • ReflectionExtension::getConstants() - 定数を取得する


拡張モジュール名を取得する

  • ≪ ReflectionExtension::getINIEntries
  • ReflectionExtension::getVersion ≫
  • PHP Manual
  • ReflectionExtension
  • 拡張モジュール名を取得する

ReflectionExtension::getName

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getName — 拡張モジュール名を取得する

説明

public ReflectionExtension::getName(): string

拡張モジュールの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡張モジュールの名前を返します。

例

例1 ReflectionExtension::getName() の例

<?php
$ext = new ReflectionExtension('mysqli');
var_dump($ext->getName());
?>

上の例の出力は、 たとえば以下のようになります。

string(6) "mysqli"

参考

  • ReflectionExtension::getClassNames() - クラス名を取得する


拡張モジュールのバージョンを取得する

  • ≪ ReflectionExtension::getName
  • ReflectionExtension::info ≫
  • PHP Manual
  • ReflectionExtension
  • 拡張モジュールのバージョンを取得する

ReflectionExtension::getVersion

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::getVersion — 拡張モジュールのバージョンを取得する

説明

public ReflectionExtension::getVersion(): ?string

拡張モジュールのバージョンを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡張モジュールのバージョンを返します。 バージョン情報がない場合は、null を返します。

例

例1 ReflectionExtension::getVersion() の例

<?php
$ext = new ReflectionExtension('mysqli');
var_dump($ext->getVersion());
?>

上の例の出力は、 たとえば以下のようになります。

string(3) "0.1"

参考

  • ReflectionExtension::info() - 拡張モジュールの情報を表示する


拡張モジュールの情報を表示する

  • ≪ ReflectionExtension::getVersion
  • ReflectionExtension::isPersistent ≫
  • PHP Manual
  • ReflectionExtension
  • 拡張モジュールの情報を表示する

ReflectionExtension::info

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

ReflectionExtension::info — 拡張モジュールの情報を表示する

説明

public ReflectionExtension::info(): void

指定した拡張モジュールに関する "phpinfo()" の情報を表示します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡張モジュールの情報を返します。

例

例1 ReflectionExtension::info() の例

<?php
$ext = new ReflectionExtension('mysqli');
$ext->info();
?>

上の例の出力は、 たとえば以下のようになります。

mysqli

MysqlI Support => enabled
Client API library version => mysqlnd 5.0.5-dev - 081106 - $Revision$
Active Persistent Links => 0
Inactive Persistent Links => 0
Active Links => 0
Persistent cache => enabled
put_hits => 0
put_misses => 0
get_hits => 0
get_misses => 0
size => 2000
free_items => 2000
references => 2

Directive => Local Value => Master Value
mysqli.max_links => Unlimited => Unlimited
mysqli.max_persistent => Unlimited => Unlimited
mysqli.allow_persistent => On => On
mysqli.default_host => no value => no value
mysqli.default_user => no value => no value
mysqli.default_pw => no value => no value
mysqli.default_port => 3306 => 3306
mysqli.default_socket => no value => no value
mysqli.reconnect => Off => Off
mysqli.allow_local_infile => On => On
mysqli.cache_size => 2000 => 2000

参考

  • ReflectionExtension::getName() - 拡張モジュール名を取得する
  • phpinfo() - PHP の設定情報を出力する


この拡張モジュールが永続性のあるものかどうかを返す

  • ≪ ReflectionExtension::info
  • ReflectionExtension::isTemporary ≫
  • PHP Manual
  • ReflectionExtension
  • この拡張モジュールが永続性のあるものかどうかを返す

ReflectionExtension::isPersistent

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionExtension::isPersistent — この拡張モジュールが永続性のあるものかどうかを返す

説明

public ReflectionExtension::isPersistent(): bool

この拡張モジュールが永続性のあるものかどうかを調べます。

php.ini を使って読み込まれている場合、拡張機能は永続性があります。 dl() を使って読み込まれている場合、拡張機能は一時的なもので、永続性はありません。

パラメータ

この関数にはパラメータはありません。

戻り値

この拡張モジュールが extension で読み込まれたものである場合に true、そうでない場合に false を返します。

参考

  • ReflectionExtension::isTemporary() - この拡張モジュールが一時的なものかどうかを返す


この拡張モジュールが一時的なものかどうかを返す

  • ≪ ReflectionExtension::isPersistent
  • ReflectionExtension::__toString ≫
  • PHP Manual
  • ReflectionExtension
  • この拡張モジュールが一時的なものかどうかを返す

ReflectionExtension::isTemporary

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionExtension::isTemporary — この拡張モジュールが一時的なものかどうかを返す

説明

public ReflectionExtension::isTemporary(): bool

この拡張モジュールが一時的なものかどうかを調べます。

dl() を使って読み込まれている場合、 拡張モジュールは一時的なものです。

パラメータ

この関数にはパラメータはありません。

戻り値

この拡張モジュールが dl() で読み込まれたものである場合に true、 そうでない場合に false を返します。

参考

  • ReflectionExtension::isPersistent() - この拡張モジュールが永続性のあるものかどうかを返す


文字列に変換する

  • ≪ ReflectionExtension::isTemporary
  • ReflectionFunction ≫
  • PHP Manual
  • ReflectionExtension
  • 文字列に変換する

ReflectionExtension::__toString

(PHP 5, PHP 7, PHP 8)

ReflectionExtension::__toString — 文字列に変換する

説明

public ReflectionExtension::__toString(): string

調べた拡張モジュールをエクスポートし、文字列として返します。 これは、ReflectionExtension::export() のパラメータ return を true に設定するのと同じ意味です。

パラメータ

この関数にはパラメータはありません。

戻り値

エクスポートした拡張モジュールを文字列で返します。 ReflectionExtension::export() と同じ形式となります。

参考

  • ReflectionExtension::__construct() - ReflectionExtension を作成する
  • ReflectionExtension::export() - エクスポートする
  • __toString()


ReflectionFunction クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionFunction クラスは 関数についての情報を報告します。

クラス概要

class ReflectionFunction extends ReflectionFunctionAbstract {
/* 定数 */
public const int IS_DEPRECATED;
/* 継承したプロパティ */
public string $name;
/* メソッド */
public __construct(Closure|string $function)
public static export(string $name, string $return = ?): string
public getClosure(): Closure
public invoke(mixed ...$args): mixed
public invokeArgs(array $args): mixed
public isAnonymous(): bool
public isDisabled(): bool
public __toString(): string
/* 継承したメソッド */
private ReflectionFunctionAbstract::__clone(): void
public ReflectionFunctionAbstract::getAttributes(?string $name = null, int $flags = 0): array
public ReflectionFunctionAbstract::getClosureScopeClass(): ?ReflectionClass
public ReflectionFunctionAbstract::getClosureThis(): ?object
public ReflectionFunctionAbstract::getClosureUsedVariables(): array
public ReflectionFunctionAbstract::getDocComment(): string|false
public ReflectionFunctionAbstract::getEndLine(): int|false
public ReflectionFunctionAbstract::getExtension(): ?ReflectionExtension
public ReflectionFunctionAbstract::getExtensionName(): string|false
public ReflectionFunctionAbstract::getFileName(): string|false
public ReflectionFunctionAbstract::getName(): string
public ReflectionFunctionAbstract::getNamespaceName(): string
public ReflectionFunctionAbstract::getNumberOfParameters(): int
public ReflectionFunctionAbstract::getNumberOfRequiredParameters(): int
public ReflectionFunctionAbstract::getParameters(): array
public ReflectionFunctionAbstract::getReturnType(): ?ReflectionType
public ReflectionFunctionAbstract::getShortName(): string
public ReflectionFunctionAbstract::getStartLine(): int|false
public ReflectionFunctionAbstract::getStaticVariables(): array
public ReflectionFunctionAbstract::getTentativeReturnType(): ?ReflectionType
public ReflectionFunctionAbstract::hasReturnType(): bool
public ReflectionFunctionAbstract::hasTentativeReturnType(): bool
public ReflectionFunctionAbstract::inNamespace(): bool
public ReflectionFunctionAbstract::isClosure(): bool
public ReflectionFunctionAbstract::isDeprecated(): bool
public ReflectionFunctionAbstract::isGenerator(): bool
public ReflectionFunctionAbstract::isInternal(): bool
public ReflectionFunctionAbstract::isStatic(): bool
public ReflectionFunctionAbstract::isUserDefined(): bool
public ReflectionFunctionAbstract::isVariadic(): bool
public ReflectionFunctionAbstract::returnsReference(): bool
abstract public ReflectionFunctionAbstract::__toString(): void
}

定義済み定数

ReflectionFunction の修飾子

ReflectionFunction::IS_DEPRECATED

非推奨の関数であることを示します。

変更履歴

バージョン | 説明
8.0.0 | ReflectionFunction::export() は、削除されました。

目次

  • ReflectionFunction::__construct — ReflectionFunction オブジェクトを作成する
  • ReflectionFunction::export — 関数をエクスポートする
  • ReflectionFunction::getClosure — この関数に動的に作成されたクロージャを返す
  • ReflectionFunction::invoke — 関数を起動する
  • ReflectionFunction::invokeArgs — 引数を指定して関数を起動する
  • ReflectionFunction::isAnonymous — 関数が無名関数かどうかを調べる
  • ReflectionFunction::isDisabled — 関数が無効になっているかどうかを調べる
  • ReflectionFunction::__toString — ReflectionFunction を表現する文字列を返す


ReflectionFunction オブジェクトを作成する

  • ≪ ReflectionFunction
  • ReflectionFunction::export ≫
  • PHP Manual
  • ReflectionFunction
  • ReflectionFunction オブジェクトを作成する

ReflectionFunction::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionFunction::__construct — ReflectionFunction オブジェクトを作成する

説明

public ReflectionFunction::__construct(Closure|string $function)

ReflectionFunction オブジェクトを作成します。

パラメータ

function

調べたい関数あるいはクロージャの名前。

エラー / 例外

function パラメータが正しい関数名でない場合に ReflectionException が発生します。

例

例1 ReflectionFunction::__construct() の例

<?php
/**
* 簡単なカウンタ
*
* @return int
*/
function counter1()
{
static $c = 0;
return ++$c;
}

/**
* 別の簡単なカウンタ
*
* @return int
*/
$counter2 = function()
{
static $d = 0;
return ++$d;

};

function dumpReflectionFunction($func)
{
// 基本情報を表示します
printf(
"\n\n===> The %s function '%s'\n".
" declared in %s\n".
" lines %d to %d\n",
$func->isInternal() ? 'internal' : 'user-defined',
$func->getName(),
$func->getFileName(),
$func->getStartLine(),
$func->getEndline()
);

// ドキュメントコメントを表示します
printf("---> Documentation:\n %s\n", var_export($func->getDocComment(), 1));

// static変数が存在すれば表示します
if ($statics = $func->getStaticVariables())
{
printf("---> Static variables: %s\n", var_export($statics, 1));
}
}

// ReflectionFunction クラスのインスタンスを作成します
dumpReflectionFunction(new ReflectionFunction('counter1'));
dumpReflectionFunction(new ReflectionFunction($counter2));
?>

上の例の出力は、 たとえば以下のようになります。

===> The user-defined function 'counter1'
     declared in Z:\reflectcounter.php
     lines 7 to 11
---> Documentation:
 '/**
 * 簡単なカウンタ
 *
 * @return    int
 */'
---> Static variables: array (
  'c' => 0,
)

===> The user-defined function '{closure}'
     declared in Z:\reflectcounter.php
     lines 18 to 23
---> Documentation:
 '/**
 * 別の簡単なカウンタ
 *
 * @return    int
 */'
---> Static variables: array (
  'd' => 0,
)

参考

  • ReflectionMethod::__construct() - ReflectionMethod を作成する
  • コンストラクタ


関数をエクスポートする

  • ≪ ReflectionFunction::__construct
  • ReflectionFunction::getClosure ≫
  • PHP Manual
  • ReflectionFunction
  • 関数をエクスポートする

ReflectionFunction::export

(PHP 5, PHP 7)

ReflectionFunction::export — 関数をエクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionFunction::export(string $name, string $return = ?): string

調べた関数をエクスポートします。

パラメータ

name

エクスポートするリフレクション。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

return パラメータを true に設定すると、エクスポートを文字列で返します。それ以外の場合は null を返します。

参考

  • ReflectionFunction::invoke() - 関数を起動する
  • ReflectionFunction::__toString() - ReflectionFunction を表現する文字列を返す


この関数に動的に作成されたクロージャを返す

  • ≪ ReflectionFunction::export
  • ReflectionFunction::invoke ≫
  • PHP Manual
  • ReflectionFunction
  • この関数に動的に作成されたクロージャを返す

ReflectionFunction::getClosure

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionFunction::getClosure — この関数に動的に作成されたクロージャを返す

説明

public ReflectionFunction::getClosure(): Closure

この関数に動的に作成されたクロージャを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

新しく作成された Closure を返します。

参考

  • 第一級callableを生成する記法


関数を起動する

  • ≪ ReflectionFunction::getClosure
  • ReflectionFunction::invokeArgs ≫
  • PHP Manual
  • ReflectionFunction
  • 関数を起動する

ReflectionFunction::invoke

(PHP 5, PHP 7, PHP 8)

ReflectionFunction::invoke — 関数を起動する

説明

public ReflectionFunction::invoke(mixed ...$args): mixed

調べた関数を起動します。

パラメータ

args

渡す引数のリスト。可変長の引数を指定でき、 call_user_func() と同じようにして関数に渡されます。

戻り値

起動した関数の結果を返します。

例

例1 ReflectionFunction::invoke() の例

<?php
function title($title, $name)
{
return sprintf("%s. %s\r\n", $title, $name);
}

$function = new ReflectionFunction('title');

echo $function->invoke('Dr', 'Phil');
?>

上の例の出力は以下となります。

Dr. Phil

注意

注意:

ReflectionFunction::invoke() は、 リファレンスが引数に期待されている場合は使えません。 その場合は、(引数リストにリファレンスを渡して) ReflectionFunction::invokeArgs() を代わりに使うべきです。

参考

  • ReflectionFunction::export() - 関数をエクスポートする
  • __invoke()
  • call_user_func() - 最初の引数で指定したコールバック関数をコールする


引数を指定して関数を起動する

  • ≪ ReflectionFunction::invoke
  • ReflectionFunction::isAnonymous ≫
  • PHP Manual
  • ReflectionFunction
  • 引数を指定して関数を起動する

ReflectionFunction::invokeArgs

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionFunction::invokeArgs — 引数を指定して関数を起動する

説明

public ReflectionFunction::invokeArgs(array $args): mixed

関数を起動して、その引数を配列として渡します。

パラメータ

args

関数に渡す引数を含む配列。 call_user_func_array() と同じように動作します。

戻り値

起動した関数の結果を返します。

変更履歴

バージョン | 説明
8.0.0 | args のキーは、 静かに無視されるのではなく、パラメータの名前として解釈されるようになりました。

例

例1 ReflectionFunction::invokeArgs() の例

<?php
function title($title, $name)
{
return sprintf("%s. %s\r\n", $title, $name);
}

$function = new ReflectionFunction('title');

echo $function->invokeArgs(array('Dr', 'Phil'));
?>

上の例の出力は以下となります。

Dr. Phil

例2 ReflectionFunction::invokeArgs() で参照を使う例

<?php
function get_false_conditions(array $conditions, array &$false_conditions)
{
foreach ($conditions as $condition) {
if (!$condition) {
$false_conditions[] = $condition;
}
}
}

$function_ref = new ReflectionFunction('get_false_conditions');

$conditions = array(true, false, -1, 0, 1);
$false_conditions = array();

$function_ref->invokeArgs(array($conditions, &$false_conditions));

var_dump($false_conditions);
?>

上の例の出力は以下となります。

array(2) {
  [0]=>
  bool(false)
  [1]=>
  int(0)
}

注意

注意:

関数の引数の中にリファレンス渡しを要するものがある場合は、 渡す引数の中でもリファレンスにしておく必要があります。

参考

  • ReflectionFunction::invoke() - 関数を起動する
  • ReflectionFunctionAbstract::getNumberOfParameters() - パラメータ数を取得する
  • __invoke()
  • call_user_func_array() - パラメータの配列を指定してコールバック関数をコールする


関数が無名関数かどうかを調べる

  • ≪ ReflectionFunction::invokeArgs
  • ReflectionFunction::isDisabled ≫
  • PHP Manual
  • ReflectionFunction
  • 関数が無名関数かどうかを調べる

ReflectionFunction::isAnonymous

(PHP 8 >= 8.2.0)

ReflectionFunction::isAnonymous — 関数が無名関数かどうかを調べる

説明

public ReflectionFunction::isAnonymous(): bool

関数が 無名関数 かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

関数が無名関数の場合、true を返します。そうでない場合、false を返します。

例

例1 ReflectionFunction::isAnonymous() の例

<?php

$rf = new ReflectionFunction(function() {});
var_dump($rf->isAnonymous());

$rf = new ReflectionFunction('strlen');
var_dump($rf->isAnonymous());
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • 無名関数


関数が無効になっているかどうかを調べる

  • ≪ ReflectionFunction::isAnonymous
  • ReflectionFunction::__toString ≫
  • PHP Manual
  • ReflectionFunction
  • 関数が無効になっているかどうかを調べる

ReflectionFunction::isDisabled

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunction::isDisabled — 関数が無効になっているかどうかを調べる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

public ReflectionFunction::isDisabled(): bool

disable_functions ディレクティブで関数が無効になっているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

無効になっている場合に true、それ以外の場合に false を返します。

参考

  • ReflectionFunctionAbstract::isUserDefined() - ユーザー定義関数であるかどうかを調べる
  • disable_functions ディレクティブ


ReflectionFunction を表現する文字列を返す

  • ≪ ReflectionFunction::isDisabled
  • ReflectionFunctionAbstract ≫
  • PHP Manual
  • ReflectionFunction
  • ReflectionFunction を表現する文字列を返す

ReflectionFunction::__toString

(PHP 5, PHP 7, PHP 8)

ReflectionFunction::__toString — ReflectionFunction を表現する文字列を返す

説明

public ReflectionFunction::__toString(): string

関数を表現した、人間が読める説明を取得します。 パラメータと戻り値が含まれます。

パラメータ

この関数にはパラメータはありません。

戻り値

文字列を返します。

例

例1 ReflectionFunction::__toString() の例

<?php
function title($title, $name)
{
return sprintf("%s. %s\r\n", $title, $name);
}

echo new ReflectionFunction('title');
?>

上の例の出力は、 たとえば以下のようになります。

Function [ <user> function title ] {
  @@ Command line code 1 - 1

  - Parameters [2] {
    Parameter #0 [ <required> $title ]
    Parameter #1 [ <required> $name ]
  }
}

参考

  • ReflectionFunction::export() - 関数をエクスポートする
  • __toString()


ReflectionFunctionAbstract クラス

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

はじめに

ReflectionFunction の親クラスです。 詳細はこのクラスの説明を参照ください。

クラス概要

abstract class ReflectionFunctionAbstract implements Reflector {
/* プロパティ */
public string $name;
/* メソッド */
private __clone(): void
public getAttributes(?string $name = null, int $flags = 0): array
public getClosureScopeClass(): ?ReflectionClass
public getClosureThis(): ?object
public getClosureUsedVariables(): array
public getDocComment(): string|false
public getEndLine(): int|false
public getExtension(): ?ReflectionExtension
public getExtensionName(): string|false
public getFileName(): string|false
public getName(): string
public getNamespaceName(): string
public getNumberOfParameters(): int
public getNumberOfRequiredParameters(): int
public getParameters(): array
public getReturnType(): ?ReflectionType
public getShortName(): string
public getStartLine(): int|false
public getStaticVariables(): array
public getTentativeReturnType(): ?ReflectionType
public hasReturnType(): bool
public hasTentativeReturnType(): bool
public inNamespace(): bool
public isClosure(): bool
public isDeprecated(): bool
public isGenerator(): bool
public isInternal(): bool
public isStatic(): bool
public isUserDefined(): bool
public isVariadic(): bool
public returnsReference(): bool
abstract public __toString(): void
}

プロパティ

name

関数名。読み込み専用で、書き込もうとすると ReflectionException をスローします。

目次

  • ReflectionFunctionAbstract::__clone — 関数のクローンを作成する
  • ReflectionFunctionAbstract::getAttributes — アトリビュートを取得する
  • ReflectionFunctionAbstract::getClosureScopeClass — クロージャに関連づけられたスコープクラスを返す
  • ReflectionFunctionAbstract::getClosureThis — クロージャにバインドした this ポインタを返す
  • ReflectionFunctionAbstract::getClosureUsedVariables — クロージャ内で使われている変数の配列を返す
  • ReflectionFunctionAbstract::getDocComment — ドキュメントコメントを取得する
  • ReflectionFunctionAbstract::getEndLine — 終了行番号を取得する
  • ReflectionFunctionAbstract::getExtension — 拡張モジュールの情報を取得する
  • ReflectionFunctionAbstract::getExtensionName — 拡張モジュールの名前を取得する
  • ReflectionFunctionAbstract::getFileName — ファイル名を取得する
  • ReflectionFunctionAbstract::getName — 関数名を取得する
  • ReflectionFunctionAbstract::getNamespaceName — 名前空間名を取得する
  • ReflectionFunctionAbstract::getNumberOfParameters — パラメータ数を取得する
  • ReflectionFunctionAbstract::getNumberOfRequiredParameters — 必須パラメータの数を取得する
  • ReflectionFunctionAbstract::getParameters — パラメータを取得する
  • ReflectionFunctionAbstract::getReturnType — 指定された関数の戻り値の型を取得する
  • ReflectionFunctionAbstract::getShortName — 関数の短い名前を取得する
  • ReflectionFunctionAbstract::getStartLine — 開始行番号を取得する
  • ReflectionFunctionAbstract::getStaticVariables — static変数を取得する
  • ReflectionFunctionAbstract::getTentativeReturnType — 関数に関連付けられた仮の戻り値の型を返す
  • ReflectionFunctionAbstract::hasReturnType — 関数が戻り値の型を指定しているかを調べる
  • ReflectionFunctionAbstract::hasTentativeReturnType — 戻り値の型を仮で宣言しているかを返す
  • ReflectionFunctionAbstract::inNamespace — 関数が名前空間内にあるかどうかを調べる
  • ReflectionFunctionAbstract::isClosure — クロージャであるかどうかを調べる
  • ReflectionFunctionAbstract::isDeprecated — 非推奨であるかどうかを調べる
  • ReflectionFunctionAbstract::isGenerator — この関数がジェネレータかどうかを返す
  • ReflectionFunctionAbstract::isInternal — 内部関数かどうかを調べる
  • ReflectionFunctionAbstract::isStatic — 関数が static であるかどうかを調べる
  • ReflectionFunctionAbstract::isUserDefined — ユーザー定義関数であるかどうかを調べる
  • ReflectionFunctionAbstract::isVariadic — この関数の引数が可変長かを調べる
  • ReflectionFunctionAbstract::returnsReference — 参照返しかどうかを調べる
  • ReflectionFunctionAbstract::__toString — ReflectionFunctionAbstract を表現する文字列を返す


関数のクローンを作成する

  • ≪ ReflectionFunctionAbstract
  • ReflectionFunctionAbstract::getAttributes ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数のクローンを作成する

ReflectionFunctionAbstract::__clone

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::__clone — 関数のクローンを作成する

説明

private ReflectionFunctionAbstract::__clone(): void

関数のクローンを作成します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.1.0 | このメソッドは、final ではなくなりました。

参考

  • オブジェクトのクローン作成


アトリビュートを取得する

  • ≪ ReflectionFunctionAbstract::__clone
  • ReflectionFunctionAbstract::getClosureScopeClass ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • アトリビュートを取得する

ReflectionFunctionAbstract::getAttributes

(PHP 8)

ReflectionFunctionAbstract::getAttributes — アトリビュートを取得する

説明

public ReflectionFunctionAbstract::getAttributes(?string $name = null, int $flags = 0): array

この関数で宣言されている全てのアトリビュートを、 ReflectionAttribute として返します。

パラメータ

name

指定したクラス名にマッチするアトリビュートの、 ReflectionAttribute のみを含むようにフィルタします。

flags

name が指定されていた場合に、 結果をどうフィルタするかを決めるフラグ。

デフォルトは 0 です。 この場合、アトリビュートのクラス名が name であるものだけを返します。

他の利用可能なオプションは、 ReflectionAttribute::IS_INSTANCEOF です。 この場合、フィルタリングに instanceof を使います。

戻り値

アトリビュートの配列を、 ReflectionAttribute オブジェクトの配列として返します。

例

例1 メソッドを使った、基本的な使い方

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

class Factory {
#[Fruit]
#[Red]
public function makeApple(): string
{
return 'apple';
}
}

$method = new ReflectionMethod('Factory', 'makeApple');
$attributes = $method->getAttributes();
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
    [1] => Red
)

例2 関数を使った、基本的な使い方

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

#[Fruit]
#[Red]
function makeApple(): string
{
return 'apple';
}

$function = new ReflectionFunction('makeApple');
$attributes = $function->getAttributes();
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
    [1] => Red
)

例3 クラス名を使って結果をフィルタする

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

#[Fruit]
#[Red]
function makeApple(): string
{
return 'apple';
}

$function = new ReflectionFunction('makeApple');
$attributes = $function->getAttributes('Fruit');
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
)

例4 クラス名、かつ継承も考慮して結果をフィルタする

<?php
interface Color {
}

#[Attribute]
class Fruit {
}

#[Attribute]
class Red implements Color {
}

#[Fruit]
#[Red]
function makeApple(): string
{
return 'apple';
}

$function = new ReflectionFunction('makeApple');
$attributes = $function->getAttributes('Color', ReflectionAttribute::IS_INSTANCEOF);
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Red
)

参考

  • ReflectionClass::getAttributes() - アトリビュートを取得する
  • ReflectionClassConstant::getAttributes() - アトリビュートを取得する
  • ReflectionParameter::getAttributes() - アトリビュートを取得する
  • ReflectionProperty::getAttributes() - アトリビュートを取得する


クロージャに関連づけられたスコープクラスを返す

  • ≪ ReflectionFunctionAbstract::getAttributes
  • ReflectionFunctionAbstract::getClosureThis ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • クロージャに関連づけられたスコープクラスを返す

ReflectionFunctionAbstract::getClosureScopeClass

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getClosureScopeClass — クロージャに関連づけられたスコープクラスを返す

説明

public ReflectionFunctionAbstract::getClosureScopeClass(): ?ReflectionClass

クロージャの宣言を囲んだクラスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合にクラスを返します。 関数がクロージャでなかったり、クラスで囲まれていない場合は null を返します。


クロージャにバインドした this ポインタを返す

  • ≪ ReflectionFunctionAbstract::getClosureScopeClass
  • ReflectionFunctionAbstract::getClosureUsedVariables ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • クロージャにバインドした this ポインタを返す

ReflectionFunctionAbstract::getClosureThis

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getClosureThis — クロージャにバインドした this ポインタを返す

説明

public ReflectionFunctionAbstract::getClosureThis(): ?object

関数が static でないクロージャの場合に、 クロージャ内部で $this にバインドされたオブジェクト所得します。

パラメータ

この関数にはパラメータはありません。

戻り値

$this ポインタを返します。 エラー時には null を返します。


クロージャ内で使われている変数の配列を返す

  • ≪ ReflectionFunctionAbstract::getClosureThis
  • ReflectionFunctionAbstract::getDocComment ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • クロージャ内で使われている変数の配列を返す

ReflectionFunctionAbstract::getClosureUsedVariables

(PHP 8 >= 8.1.0)

ReflectionFunctionAbstract::getClosureUsedVariables — クロージャ内で使われている変数の配列を返す

説明

public ReflectionFunctionAbstract::getClosureUsedVariables(): array

Closure の中で内で使われている変数の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Closure の中で内で使われている変数の配列を返します。

例

例1 ReflectionFunctionAbstract::getClosureUsedVariables() の例

<?php

$one = 1;
$two = 2;

$function = function() use ($one, $two) {
static $three = 3;
};

$reflector = new ReflectionFunction($function);

var_dump($reflector->getClosureUsedVariables());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["one"]=>
  int(1)
  ["two"]=>
  int(2)
}

参考

  • ReflectionFunctionAbstract::getClosureScopeClass() - クロージャに関連づけられたスコープクラスを返す
  • ReflectionFunctionAbstract::getClosureThis() - クロージャにバインドした this ポインタを返す


ドキュメントコメントを取得する

  • ≪ ReflectionFunctionAbstract::getClosureUsedVariables
  • ReflectionFunctionAbstract::getEndLine ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • ドキュメントコメントを取得する

ReflectionFunctionAbstract::getDocComment

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getDocComment — ドキュメントコメントを取得する

説明

public ReflectionFunctionAbstract::getDocComment(): string|false

関数のドキュメントコメントを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ドキュメントコメントが存在する場合はそれを返します。それ以外の場合は false を返します。

参考

  • ReflectionFunctionAbstract::getStartLine() - 開始行番号を取得する


終了行番号を取得する

  • ≪ ReflectionFunctionAbstract::getDocComment
  • ReflectionFunctionAbstract::getExtension ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 終了行番号を取得する

ReflectionFunctionAbstract::getEndLine

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getEndLine — 終了行番号を取得する

説明

public ReflectionFunctionAbstract::getEndLine(): int|false

終了行番号を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ユーザー定義関数の終了行番号を返します。不明な場合は false を返します。

参考

  • ReflectionFunctionAbstract::getStartLine() - 開始行番号を取得する


拡張モジュールの情報を取得する

  • ≪ ReflectionFunctionAbstract::getEndLine
  • ReflectionFunctionAbstract::getExtensionName ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 拡張モジュールの情報を取得する

ReflectionFunctionAbstract::getExtension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getExtension — 拡張モジュールの情報を取得する

説明

public ReflectionFunctionAbstract::getExtension(): ?ReflectionExtension

関数の拡張モジュール情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡張モジュールの情報を ReflectionExtension オブジェクトで返します。 ユーザー定義の関数の場合は、null を返します。

参考

  • ReflectionFunctionAbstract::getExtensionName() - 拡張モジュールの名前を取得する


拡張モジュールの名前を取得する

  • ≪ ReflectionFunctionAbstract::getExtension
  • ReflectionFunctionAbstract::getFileName ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 拡張モジュールの名前を取得する

ReflectionFunctionAbstract::getExtensionName

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getExtensionName — 拡張モジュールの名前を取得する

説明

public ReflectionFunctionAbstract::getExtensionName(): string|false

拡張モジュールの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

拡張モジュールの名前を返します。 ユーザー定義の関数の場合は、false を返します。

参考

  • ReflectionFunctionAbstract::getExtension() - 拡張モジュールの情報を取得する


ファイル名を取得する

  • ≪ ReflectionFunctionAbstract::getExtensionName
  • ReflectionFunctionAbstract::getName ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • ファイル名を取得する

ReflectionFunctionAbstract::getFileName

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getFileName — ファイル名を取得する

説明

public ReflectionFunctionAbstract::getFileName(): string|false

ユーザー定義関数のファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

関数が定義されたファイル名を返します。 PHP コアや拡張モジュールで定義されていた場合は、false を返します。

参考

  • ReflectionFunctionAbstract::getNamespaceName() - 名前空間名を取得する


関数名を取得する

  • ≪ ReflectionFunctionAbstract::getFileName
  • ReflectionFunctionAbstract::getNamespaceName ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数名を取得する

ReflectionFunctionAbstract::getName

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getName — 関数名を取得する

説明

public ReflectionFunctionAbstract::getName(): string

関数の名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

関数の名前を返します。

参考

  • ReflectionFunctionAbstract::getExtensionName() - 拡張モジュールの名前を取得する
  • ReflectionFunctionAbstract::isUserDefined() - ユーザー定義関数であるかどうかを調べる


名前空間名を取得する

  • ≪ ReflectionFunctionAbstract::getName
  • ReflectionFunctionAbstract::getNumberOfParameters ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 名前空間名を取得する

ReflectionFunctionAbstract::getNamespaceName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getNamespaceName — 名前空間名を取得する

説明

public ReflectionFunctionAbstract::getNamespaceName(): string

クラスが定義されている名前空間の名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

名前空間名を返します。

参考

  • ReflectionFunctionAbstract::getFileName() - ファイル名を取得する
  • 名前空間


パラメータ数を取得する

  • ≪ ReflectionFunctionAbstract::getNamespaceName
  • ReflectionFunctionAbstract::getNumberOfRequiredParameters ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • パラメータ数を取得する

ReflectionFunctionAbstract::getNumberOfParameters

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getNumberOfParameters — パラメータ数を取得する

説明

public ReflectionFunctionAbstract::getNumberOfParameters(): int

関数で定義されているパラメータの数を、必須と任意の両方を含めて取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

パラメータの数を返します。

参考

  • ReflectionFunctionAbstract::getNumberOfRequiredParameters() - 必須パラメータの数を取得する
  • func_num_args() - 関数に渡された引数の数を返す


必須パラメータの数を取得する

  • ≪ ReflectionFunctionAbstract::getNumberOfParameters
  • ReflectionFunctionAbstract::getParameters ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 必須パラメータの数を取得する

ReflectionFunctionAbstract::getNumberOfRequiredParameters

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getNumberOfRequiredParameters — 必須パラメータの数を取得する

説明

public ReflectionFunctionAbstract::getNumberOfRequiredParameters(): int

関数で定義されている必須パラメータの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

必須パラメータの数を返します。

参考

  • ReflectionFunctionAbstract::getNumberOfParameters() - パラメータ数を取得する


パラメータを取得する

  • ≪ ReflectionFunctionAbstract::getNumberOfRequiredParameters
  • ReflectionFunctionAbstract::getReturnType ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • パラメータを取得する

ReflectionFunctionAbstract::getParameters

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getParameters — パラメータを取得する

説明

public ReflectionFunctionAbstract::getParameters(): array

パラメータをソースコードで定義された順に ReflectionParameter の配列で取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

パラメータを ReflectionParameter オブジェクトの配列で返します。

参考

  • ReflectionFunctionAbstract::getNumberOfParameters() - パラメータ数を取得する
  • func_get_args() - 関数の引数リストを配列として返す


指定された関数の戻り値の型を取得する

  • ≪ ReflectionFunctionAbstract::getParameters
  • ReflectionFunctionAbstract::getShortName ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 指定された関数の戻り値の型を取得する

ReflectionFunctionAbstract::getReturnType

(PHP 7, PHP 8)

ReflectionFunctionAbstract::getReturnType — 指定された関数の戻り値の型を取得する

説明

public ReflectionFunctionAbstract::getReturnType(): ?ReflectionType

指定されたリフレクションされた関数の戻り値の型を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

戻り値の型が指定されていた場合は ReflectionType オブジェクトを返します。 指定されていない場合は null を返します。

例

例1 ReflectionFunctionAbstract::getReturnType() の例

<?php

function to_int($param) : int {
return (int) $param;
}

$reflection1 = new ReflectionFunction('to_int');
echo $reflection1->getReturnType();

上の例の出力は以下となります。

int

例2 ビルトイン関数で使う場合

<?php

$reflection2 = new ReflectionFunction('array_merge');

var_dump($reflection2->getReturnType());

上の例の出力は以下となります。

null

こうなるのは、たくさんの内部関数が引数や戻り値で型を指定していないからです。 よって、このメソッドをビルトイン関数に使うのを避けるのが最適です。

参考

  • ReflectionFunctionAbstract::hasReturnType() - 関数が戻り値の型を指定しているかを調べる
  • ReflectionType::__toString() - 文字列に変換する


関数の短い名前を取得する

  • ≪ ReflectionFunctionAbstract::getReturnType
  • ReflectionFunctionAbstract::getStartLine ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数の短い名前を取得する

ReflectionFunctionAbstract::getShortName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getShortName — 関数の短い名前を取得する

説明

public ReflectionFunctionAbstract::getShortName(): string

関数の短い名前 (名前空間部分を除いた名前) を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

関数の短い名前を返します。

参考

  • ReflectionFunctionAbstract::getNamespaceName() - 名前空間名を取得する
  • 名前空間


開始行番号を取得する

  • ≪ ReflectionFunctionAbstract::getShortName
  • ReflectionFunctionAbstract::getStaticVariables ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 開始行番号を取得する

ReflectionFunctionAbstract::getStartLine

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getStartLine — 開始行番号を取得する

説明

public ReflectionFunctionAbstract::getStartLine(): int|false

関数の開始行番号を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

開始行番号を返します。 開始行が不明な場合は、false を返します。

参考

  • ReflectionFunctionAbstract::getEndLine() - 終了行番号を取得する


static変数を取得する

  • ≪ ReflectionFunctionAbstract::getStartLine
  • ReflectionFunctionAbstract::getTentativeReturnType ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • static変数を取得する

ReflectionFunctionAbstract::getStaticVariables

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::getStaticVariables — static変数を取得する

説明

public ReflectionFunctionAbstract::getStaticVariables(): array

static変数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

static変数の配列を返します。

参考

  • ReflectionFunctionAbstract::getParameters() - パラメータを取得する


関数に関連付けられた仮の戻り値の型を返す

  • ≪ ReflectionFunctionAbstract::getStaticVariables
  • ReflectionFunctionAbstract::hasReturnType ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数に関連付けられた仮の戻り値の型を返す

ReflectionFunctionAbstract::getTentativeReturnType

(PHP 8 >= 8.1.0)

ReflectionFunctionAbstract::getTentativeReturnType — 関数に関連付けられた仮の戻り値の型を返す

説明

public ReflectionFunctionAbstract::getTentativeReturnType(): ?ReflectionType

関数に関連付けられた仮の戻り値の型を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

仮の戻り値の型が指定されている場合は ReflectionType オブジェクトを返します。 そうでない場合は、null を返します。

例

例1 ReflectionFunctionAbstract::getTentativeReturnType() の例

<?php

$method = new ReflectionMethod(\ArrayAccess::class, 'offsetGet');
var_dump($method->getTentativeReturnType());

上の例の出力は、 たとえば以下のようになります。

object(ReflectionNamedType)#2 (0) {
}

参考

  • ReflectionFunctionAbstract::getReturnType() - 指定された関数の戻り値の型を取得する
  • ReflectionFunctionAbstract::hasTentativeReturnType() - 戻り値の型を仮で宣言しているかを返す
  • 内部クラスと戻り値の型の互換性


関数が戻り値の型を指定しているかを調べる

  • ≪ ReflectionFunctionAbstract::getTentativeReturnType
  • ReflectionFunctionAbstract::hasTentativeReturnType ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数が戻り値の型を指定しているかを調べる

ReflectionFunctionAbstract::hasReturnType

(PHP 7, PHP 8)

ReflectionFunctionAbstract::hasReturnType — 関数が戻り値の型を指定しているかを調べる

説明

public ReflectionFunctionAbstract::hasReturnType(): bool

リフレクションされた関数が、戻り値の型を指定しているかを調べます

パラメータ

この関数にはパラメータはありません。

戻り値

関数が戻り値の型を指定しているなら true を返します。 指定していないなら false を返します。

例

例1 ReflectionFunctionAbstract::hasReturnType() の例

<?php

function to_int($param) : int {
return (int) $param;
}

$reflection1 = new ReflectionFunction('to_int');
var_dump($reflection1->hasReturnType());

上の例の出力は以下となります。

bool(true)

例2 ビルトイン関数で使う

<?php

$reflection2 = new ReflectionFunction('array_merge');

var_dump($reflection2->hasReturnType());

上の例の出力は以下となります。

bool(false)

こうなるのは、たくさんの内部関数が引数や戻り値に型を指定していないからです。 よって、このメソッドはビルトイン関数に使わないのが最適です。

参考

  • ReflectionFunctionAbstract::getReturnType() - 指定された関数の戻り値の型を取得する


戻り値の型を仮で宣言しているかを返す

  • ≪ ReflectionFunctionAbstract::hasReturnType
  • ReflectionFunctionAbstract::inNamespace ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 戻り値の型を仮で宣言しているかを返す

ReflectionFunctionAbstract::hasTentativeReturnType

(PHP 8 >= 8.1.0)

ReflectionFunctionAbstract::hasTentativeReturnType — 戻り値の型を仮で宣言しているかを返す

説明

public ReflectionFunctionAbstract::hasTentativeReturnType(): bool

関数が戻り値の型を仮で(とりあえず)宣言しているかどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

関数が仮の(とりあえず)戻り値の型を持つ場合、true を返します。 そうでない場合、false を返します。

例

例1 ReflectionFunctionAbstract::hasTentativeReturnType() の例

<?php

$method = new ReflectionMethod(\ArrayAccess::class, 'offsetGet');
var_dump($method->hasTentativeReturnType());

上の例の出力は以下となります。

bool(true)

参考

  • ReflectionFunctionAbstract::getTentativeReturnType() - 関数に関連付けられた仮の戻り値の型を返す
  • ReflectionFunctionAbstract::hasReturnType() - 関数が戻り値の型を指定しているかを調べる
  • 内部クラスと戻り値の型の互換性


関数が名前空間内にあるかどうかを調べる

  • ≪ ReflectionFunctionAbstract::hasTentativeReturnType
  • ReflectionFunctionAbstract::isClosure ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数が名前空間内にあるかどうかを調べる

ReflectionFunctionAbstract::inNamespace

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::inNamespace — 関数が名前空間内にあるかどうかを調べる

説明

public ReflectionFunctionAbstract::inNamespace(): bool

関数が名前空間内で定義されているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

名前空間内にある場合に true、それ以外の場合に false を返します。

参考

  • ReflectionFunctionAbstract::getNamespaceName() - 名前空間名を取得する
  • 名前空間


クロージャであるかどうかを調べる

  • ≪ ReflectionFunctionAbstract::inNamespace
  • ReflectionFunctionAbstract::isDeprecated ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • クロージャであるかどうかを調べる

ReflectionFunctionAbstract::isClosure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::isClosure — クロージャであるかどうかを調べる

説明

public ReflectionFunctionAbstract::isClosure(): bool

この関数が Closure であるかどうかを調べます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

この関数が Closure である場合に true、それ以外の場合に false を返します。

例

例1 ReflectionFunctionAbstract::isClosure() の例

<?php
// クロージャではない
$function1 = 'str_replace';
$reflection1 = new ReflectionFunction($function1);
var_dump($reflection1->isClosure());

// クロージャである
$function2 = function () {};
$reflection2 = new ReflectionFunction($function2);
var_dump($reflection2->isClosure());
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionFunctionAbstract::isGenerator() - この関数がジェネレータかどうかを返す


非推奨であるかどうかを調べる

  • ≪ ReflectionFunctionAbstract::isClosure
  • ReflectionFunctionAbstract::isGenerator ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 非推奨であるかどうかを調べる

ReflectionFunctionAbstract::isDeprecated

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::isDeprecated — 非推奨であるかどうかを調べる

説明

public ReflectionFunctionAbstract::isDeprecated(): bool

この関数が非推奨であるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

非推奨である場合に true、それ以外の場合に false を返します。

例

例1 ReflectionFunctionAbstract::isDeprecated() の例

<?php
$rf = new ReflectionFunction('ereg');
var_dump($rf->isDeprecated());
?>

上の例の出力は以下となります。

bool(true)

参考

  • ReflectionFunctionAbstract::getDocComment() - ドキュメントコメントを取得する


この関数がジェネレータかどうかを返す

  • ≪ ReflectionFunctionAbstract::isDeprecated
  • ReflectionFunctionAbstract::isInternal ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • この関数がジェネレータかどうかを返す

ReflectionFunctionAbstract::isGenerator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::isGenerator — この関数がジェネレータかどうかを返す

説明

public ReflectionFunctionAbstract::isGenerator(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

この関数がジェネレータである場合に true、そうでない場合に false を返します。 処理に失敗した場合に null を返します。


内部関数かどうかを調べる

  • ≪ ReflectionFunctionAbstract::isGenerator
  • ReflectionFunctionAbstract::isStatic ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 内部関数かどうかを調べる

ReflectionFunctionAbstract::isInternal

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::isInternal — 内部関数かどうかを調べる

説明

public ReflectionFunctionAbstract::isInternal(): bool

この関数が内部関数なのかユーザー定義関数なのかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

内部関数である場合に true、それ以外の場合に false を返します。

参考

  • ReflectionFunctionAbstract::isUserDefined() - ユーザー定義関数であるかどうかを調べる


関数が static であるかどうかを調べる

  • ≪ ReflectionFunctionAbstract::isInternal
  • ReflectionFunctionAbstract::isUserDefined ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 関数が static であるかどうかを調べる

ReflectionFunctionAbstract::isStatic

(PHP 5, PHP 7, PHP 8)

ReflectionFunctionAbstract::isStatic — 関数が static であるかどうかを調べる

説明

public ReflectionFunctionAbstract::isStatic(): bool

関数が static であるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

関数が static である場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.1.0 | このメソッドは親クラスに移動しました。 これより前のバージョンでは、このメソッドは ReflectionMethod で定義されていました。

参考

  • ReflectionMethod::isFinal() - final メソッドであるかどうかを調べる


ユーザー定義関数であるかどうかを調べる

  • ≪ ReflectionFunctionAbstract::isStatic
  • ReflectionFunctionAbstract::isVariadic ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • ユーザー定義関数であるかどうかを調べる

ReflectionFunctionAbstract::isUserDefined

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::isUserDefined — ユーザー定義関数であるかどうかを調べる

説明

public ReflectionFunctionAbstract::isUserDefined(): bool

この関数がユーザー定義関数なのか内部関数なのかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

ユーザー定義関数である場合に true、それ以外の場合に false を返します。

参考

  • ReflectionFunctionAbstract::isInternal() - 内部関数かどうかを調べる


この関数の引数が可変長かを調べる

  • ≪ ReflectionFunctionAbstract::isUserDefined
  • ReflectionFunctionAbstract::returnsReference ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • この関数の引数が可変長かを調べる

ReflectionFunctionAbstract::isVariadic

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::isVariadic — この関数の引数が可変長かを調べる

説明

public ReflectionFunctionAbstract::isVariadic(): bool

この関数の 引数が可変長 かを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

この関数の引数が可変長なら true を返します。そうでないなら false を返します。


参照返しかどうかを調べる

  • ≪ ReflectionFunctionAbstract::isVariadic
  • ReflectionFunctionAbstract::__toString ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • 参照返しかどうかを調べる

ReflectionFunctionAbstract::returnsReference

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::returnsReference — 参照返しかどうかを調べる

説明

public ReflectionFunctionAbstract::returnsReference(): bool

関数が参照を返すかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

参照返しである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionFunctionAbstract::isClosure() - クロージャであるかどうかを調べる


ReflectionFunctionAbstract を表現する文字列を返す

  • ≪ ReflectionFunctionAbstract::returnsReference
  • ReflectionMethod ≫
  • PHP Manual
  • ReflectionFunctionAbstract
  • ReflectionFunctionAbstract を表現する文字列を返す

ReflectionFunctionAbstract::__toString

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

ReflectionFunctionAbstract::__toString — ReflectionFunctionAbstract を表現する文字列を返す

説明

abstract public ReflectionFunctionAbstract::__toString(): void

関数を表現した、人間が読める説明を取得します。 パラメータと戻り値が含まれます。

パラメータ

この関数にはパラメータはありません。

戻り値

文字列を返します。

参考

  • ReflectionFunction::__toString() - ReflectionFunction を表現する文字列を返す
  • ReflectionMethod::__toString() - ReflectionMethod オブジェクトの文字列表現を返す
  • __toString()


ReflectionMethod クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionMethod クラスは メソッドについての情報を報告します。

クラス概要

class ReflectionMethod extends ReflectionFunctionAbstract {
/* 定数 */
public const int IS_STATIC;
public const int IS_PUBLIC;
public const int IS_PROTECTED;
public const int IS_PRIVATE;
public const int IS_ABSTRACT;
public const int IS_FINAL;
/* プロパティ */
public string $class;
/* 継承したプロパティ */
public string $name;
/* メソッド */
public __construct(object|string $objectOrMethod, string $method)
public __construct(string $classMethod)
public static createFromMethodName(string $method): static
public static export(string $class, string $name, bool $return = false): string
public getClosure(?object $object = null): Closure
public getDeclaringClass(): ReflectionClass
public getModifiers(): int
public getPrototype(): ReflectionMethod
public hasPrototype(): bool
public invoke(?object $object, mixed ...$args): mixed
public invokeArgs(?object $object, array $args): mixed
public isAbstract(): bool
public isConstructor(): bool
public isDestructor(): bool
public isFinal(): bool
public isPrivate(): bool
public isProtected(): bool
public isPublic(): bool
public setAccessible(bool $accessible): void
public __toString(): string
/* 継承したメソッド */
private ReflectionFunctionAbstract::__clone(): void
public ReflectionFunctionAbstract::getAttributes(?string $name = null, int $flags = 0): array
public ReflectionFunctionAbstract::getClosureScopeClass(): ?ReflectionClass
public ReflectionFunctionAbstract::getClosureThis(): ?object
public ReflectionFunctionAbstract::getClosureUsedVariables(): array
public ReflectionFunctionAbstract::getDocComment(): string|false
public ReflectionFunctionAbstract::getEndLine(): int|false
public ReflectionFunctionAbstract::getExtension(): ?ReflectionExtension
public ReflectionFunctionAbstract::getExtensionName(): string|false
public ReflectionFunctionAbstract::getFileName(): string|false
public ReflectionFunctionAbstract::getName(): string
public ReflectionFunctionAbstract::getNamespaceName(): string
public ReflectionFunctionAbstract::getNumberOfParameters(): int
public ReflectionFunctionAbstract::getNumberOfRequiredParameters(): int
public ReflectionFunctionAbstract::getParameters(): array
public ReflectionFunctionAbstract::getReturnType(): ?ReflectionType
public ReflectionFunctionAbstract::getShortName(): string
public ReflectionFunctionAbstract::getStartLine(): int|false
public ReflectionFunctionAbstract::getStaticVariables(): array
public ReflectionFunctionAbstract::getTentativeReturnType(): ?ReflectionType
public ReflectionFunctionAbstract::hasReturnType(): bool
public ReflectionFunctionAbstract::hasTentativeReturnType(): bool
public ReflectionFunctionAbstract::inNamespace(): bool
public ReflectionFunctionAbstract::isClosure(): bool
public ReflectionFunctionAbstract::isDeprecated(): bool
public ReflectionFunctionAbstract::isGenerator(): bool
public ReflectionFunctionAbstract::isInternal(): bool
public ReflectionFunctionAbstract::isStatic(): bool
public ReflectionFunctionAbstract::isUserDefined(): bool
public ReflectionFunctionAbstract::isVariadic(): bool
public ReflectionFunctionAbstract::returnsReference(): bool
abstract public ReflectionFunctionAbstract::__toString(): void
}

プロパティ

name

メソッド名

class

クラス名

定義済み定数

ReflectionMethod の修飾子

ReflectionMethod::IS_STATIC

メソッドが static であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 1 でした。

ReflectionMethod::IS_PUBLIC

メソッドが public であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 256 でした。

ReflectionMethod::IS_PROTECTED

メソッドが protected であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 512 でした。

ReflectionMethod::IS_PRIVATE

メソッドが private であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 1024 でした。

ReflectionMethod::IS_ABSTRACT

メソッドが abstract であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 2 でした。

ReflectionMethod::IS_FINAL

メソッドが final であることを示します。 PHP 7.4.0 より前のバージョンでは、この値は 4 でした。

注意:

これらの定数の値は、PHP のバージョンが異なると変更される可能性があります。 これらの値を直接用いず、常に定数を使うことを推奨します。

変更履歴

バージョン | 説明
8.0.0 | ReflectionMethod::export() は、削除されました。

目次

  • ReflectionMethod::__construct — ReflectionMethod を作成する
  • ReflectionMethod::createFromMethodName — ReflectionMethod を作成する
  • ReflectionMethod::export — メソッドをエクスポートする
  • ReflectionMethod::getClosure — このメソッドに動的に作成されたクロージャを返す
  • ReflectionMethod::getDeclaringClass — メソッドが宣言されているクラスを取得する
  • ReflectionMethod::getModifiers — メソッドの修飾子を取得する
  • ReflectionMethod::getPrototype — メソッドのプロトタイプを (存在すれば) 取得する
  • ReflectionMethod::hasPrototype — メソッドがプロトタイプを持つかを調べる
  • ReflectionMethod::invoke — 実行する
  • ReflectionMethod::invokeArgs — 実行する
  • ReflectionMethod::isAbstract — 抽象メソッドであるかどうかを調べる
  • ReflectionMethod::isConstructor — コンストラクタであるかどうかを調べる
  • ReflectionMethod::isDestructor — デストラクタであるかどうかを調べる
  • ReflectionMethod::isFinal — final メソッドであるかどうかを調べる
  • ReflectionMethod::isPrivate — private メソッドであるかどうかを調べる
  • ReflectionMethod::isProtected — protected メソッドであるかどうかを調べる
  • ReflectionMethod::isPublic — public メソッドであるかどうかを調べる
  • ReflectionMethod::setAccessible — メソッドのアクセス範囲を設定する
  • ReflectionMethod::__toString — ReflectionMethod オブジェクトの文字列表現を返す


ReflectionMethod を作成する

  • ≪ ReflectionMethod
  • ReflectionMethod::createFromMethodName ≫
  • PHP Manual
  • ReflectionMethod
  • ReflectionMethod を作成する

ReflectionMethod::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::__construct — ReflectionMethod を作成する

説明

public ReflectionMethod::__construct(object|string $objectOrMethod, string $method)

代替のシグネチャ (名前付き引数をサポートしていません):

public ReflectionMethod::__construct(string $classMethod)

新しい ReflectionMethod を作成します。

パラメータ

objectOrMethod

メソッドを含むクラスの名前あるいはオブジェクト (クラスのインスタンス)。

method

メソッドの名前。

classMethod

クラス名とメソッド名を :: で区切ったもの。

エラー / 例外

指定したメソッドが存在しない場合に ReflectionException が発生します。

例

例1 ReflectionMethod::__construct() の例

<?php
class Counter
{
private static $c = 0;

/**
* カウンタをインクリメントする
*
* @final
* @static
* @access public
* @return int
*/
final public static function increment()
{
return ++self::$c;
}
}

// ReflectionMethod のインスタンスを作成します
$method = new ReflectionMethod('Counter', 'increment');

// 基本情報を表示します
printf(
"===> The %s%s%s%s%s%s%s method '%s' (which is %s)\n" .
" declared in %s\n" .
" lines %d to %d\n" .
" having the modifiers %d[%s]\n",
$method->isInternal() ? 'internal' : 'user-defined',
$method->isAbstract() ? ' abstract' : '',
$method->isFinal() ? ' final' : '',
$method->isPublic() ? ' public' : '',
$method->isPrivate() ? ' private' : '',
$method->isProtected() ? ' protected' : '',
$method->isStatic() ? ' static' : '',
$method->getName(),
$method->isConstructor() ? 'the constructor' : 'a regular method',
$method->getFileName(),
$method->getStartLine(),
$method->getEndline(),
$method->getModifiers(),
implode(' ', Reflection::getModifierNames($method->getModifiers()))
);

// ドキュメントコメントを表示します
printf("---> Documentation:\n %s\n", var_export($method->getDocComment(), true));

// static 変数があれば表示します
if ($statics= $method->getStaticVariables()) {
printf("---> Static variables: %s\n", var_export($statics, true));
}

// メソッドを実行します
printf("---> Invocation results in: ");
var_dump($method->invoke(NULL));
?>

上の例の出力は、 たとえば以下のようになります。

===> The user-defined final public static method 'increment' (which is a regular method)
     declared in /Users/philip/cvs/phpdoc/test.php
     lines 14 to 17
     having the modifiers 261[final public static]
---> Documentation:
 '/**
     * カウンタをインクリメントする
     *
     * @final
     * @static
     * @access  public
     * @return  int
     */'
---> Invocation results in: int(1)

参考

  • ReflectionMethod::export() - メソッドをエクスポートする
  • コンストラクタ


ReflectionMethod を作成する

  • ≪ ReflectionMethod::__construct
  • ReflectionMethod::export ≫
  • PHP Manual
  • ReflectionMethod
  • ReflectionMethod を作成する

ReflectionMethod::createFromMethodName

(PHP 8 >= 8.3.0)

ReflectionMethod::createFromMethodName — ReflectionMethod を作成する

説明

public static ReflectionMethod::createFromMethodName(string $method): static

新しい ReflectionMethod を作成します。

パラメータ

method

:: で区切られたクラス名とメソッド名。

戻り値

成功した場合、新しい ReflectionMethod を返します。

エラー / 例外

指定したメソッドが存在しない場合は、 ReflectionException がスローされます。

例

例1 ReflectionMethod::createFromMethodName() の例

<?php

class Foo {
public function bar() {

}
}

$methodInfo = ReflectionMethod::createFromMethodName("Foo::bar");
var_dump($methodInfo);
?>

上の例の出力は以下となります。

object(ReflectionMethod)#1 (2) {
  ["name"]=>
  string(3) "bar"
  ["class"]=>
  string(3) "Foo"
}


メソッドをエクスポートする

  • ≪ ReflectionMethod::createFromMethodName
  • ReflectionMethod::getClosure ≫
  • PHP Manual
  • ReflectionMethod
  • メソッドをエクスポートする

ReflectionMethod::export

(PHP 5, PHP 7)

ReflectionMethod::export — メソッドをエクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionMethod::export(string $class, string $name, bool $return = false): string

ReflectionMethod をエクスポートします。

パラメータ

class

クラス名。

name

メソッド名。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

return パラメータを true に設定すると、エクスポートを文字列で返します。それ以外の場合は null を返します。

参考

  • ReflectionMethod::__construct() - ReflectionMethod を作成する
  • ReflectionMethod::__toString() - ReflectionMethod オブジェクトの文字列表現を返す


このメソッドに動的に作成されたクロージャを返す

  • ≪ ReflectionMethod::export
  • ReflectionMethod::getDeclaringClass ≫
  • PHP Manual
  • ReflectionMethod
  • このメソッドに動的に作成されたクロージャを返す

ReflectionMethod::getClosure

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionMethod::getClosure — このメソッドに動的に作成されたクロージャを返す

説明

public ReflectionMethod::getClosure(?object $object = null): Closure

メソッドをコールするクロージャを作成します。

パラメータ

object

staticメソッドの場合は不要、その他のメソッドの場合は必須となります。

戻り値

新しく作成した Closure を返します。

エラー / 例外

object が null なのに、 メソッドが static ではない場合、 ValueError がスローされます。

object が、 このメソッドが宣言されたクラスのインスタンスでない場合、 ReflectionException がスローされます。

変更履歴

バージョン | 説明
8.0.0 | object は、nullable になりました。

参考

  • 第一級callableを生成する記法


メソッドが宣言されているクラスを取得する

  • ≪ ReflectionMethod::getClosure
  • ReflectionMethod::getModifiers ≫
  • PHP Manual
  • ReflectionMethod
  • メソッドが宣言されているクラスを取得する

ReflectionMethod::getDeclaringClass

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::getDeclaringClass — メソッドが宣言されているクラスを取得する

説明

public ReflectionMethod::getDeclaringClass(): ReflectionClass

そのメソッドが宣言されているクラスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

そのメソッドが属するクラスをあらわす ReflectionClass オブジェクトを返します。

例

例1 ReflectionMethod::getDeclaringClass() の例

<?php
class HelloWorld {

protected function sayHelloTo($name) {
return 'Hello ' . $name;
}

}

$reflectionMethod = new ReflectionMethod(new HelloWorld(), 'sayHelloTo');
var_dump($reflectionMethod->getDeclaringClass());
?>

上の例の出力は以下となります。

object(ReflectionClass)#2 (1) {
  ["name"]=>
  string(10) "HelloWorld"
}

参考

  • ReflectionMethod::isAbstract() - 抽象メソッドであるかどうかを調べる


メソッドの修飾子を取得する

  • ≪ ReflectionMethod::getDeclaringClass
  • ReflectionMethod::getPrototype ≫
  • PHP Manual
  • ReflectionMethod
  • メソッドの修飾子を取得する

ReflectionMethod::getModifiers

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::getModifiers — メソッドの修飾子を取得する

説明

public ReflectionMethod::getModifiers(): int

このメソッドのアクセス修飾子のビットフィールドを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

修飾子をあらわす数値を返します。修飾子の一覧は以下のとおりです。 これらの修飾子の実際の意味については 定義済みの定数 に説明があります。

例

例1 ReflectionMethod::getModifiers() の例

<?php
class Testing
{
final public static function foo()
{
return;
}
public function bar()
{
return;
}
}

$foo = new ReflectionMethod('Testing', 'foo');

echo "Modifiers for method foo():\n";
echo $foo->getModifiers() . "\n";
echo implode(' ', Reflection::getModifierNames($foo->getModifiers())) . "\n";

$bar = new ReflectionMethod('Testing', 'bar');

echo "Modifiers for method bar():\n";
echo $bar->getModifiers() . "\n";
echo implode(' ', Reflection::getModifierNames($bar->getModifiers()));
?>

上の例の出力は、 たとえば以下のようになります。

Modifiers for method foo():
49
final public static
Modifiers for method bar():
1
public

参考

  • Reflection::getModifierNames() - 修飾子の名前を取得する


メソッドのプロトタイプを (存在すれば) 取得する

  • ≪ ReflectionMethod::getModifiers
  • ReflectionMethod::hasPrototype ≫
  • PHP Manual
  • ReflectionMethod
  • メソッドのプロトタイプを (存在すれば) 取得する

ReflectionMethod::getPrototype

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionMethod::getPrototype — メソッドのプロトタイプを (存在すれば) 取得する

説明

public ReflectionMethod::getPrototype(): ReflectionMethod

メソッドのプロトタイプを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

メソッドのプロトタイプの ReflectionMethod オブジェクトを返します。

エラー / 例外

メソッドがプロトタイプを持たない場合に ReflectionException をスローします。

例

例1 ReflectionMethod::getPrototype() の例

<?php
class Hello {

public function sayHelloTo($name) {
return 'Hello ' . $name;
}

}
class HelloWorld extends Hello {

public function sayHelloTo($name) {
return 'Hello world: ' . $name;
}

}

$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
var_dump($reflectionMethod->getPrototype());
?>

上の例の出力は以下となります。

object(ReflectionMethod)#2 (2) {
  ["name"]=>
  string(10) "sayHelloTo"
  ["class"]=>
  string(5) "Hello"
}

参考

  • ReflectionMethod::getModifiers() - メソッドの修飾子を取得する
  • ReflectionMethod::hasPrototype() - メソッドがプロトタイプを持つかを調べる


メソッドがプロトタイプを持つかを調べる

  • ≪ ReflectionMethod::getPrototype
  • ReflectionMethod::invoke ≫
  • PHP Manual
  • ReflectionMethod
  • メソッドがプロトタイプを持つかを調べる

ReflectionMethod::hasPrototype

(PHP 8 >= 8.2.0)

ReflectionMethod::hasPrototype — メソッドがプロトタイプを持つかを調べる

説明

public ReflectionMethod::hasPrototype(): bool

メソッドがプロトタイプを持つかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

メソッドがプロトタイプを持つ場合、true を返します。そうでない場合、false を返します。

例

例1 ReflectionMethod::hasPrototype() の例

<?php

class Hello
{
public function sayHelloTo($name)
{
return 'Hello '.$name;
}
}

class HelloWorld extends Hello
{
public function sayHelloTo($name)
{
return 'Hello world: '.$name;
}
}
$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
var_dump($reflectionMethod->hasPrototype());
?>

上の例の出力は以下となります。

bool(true)

参考

  • ReflectionMethod::getPrototype() - メソッドのプロトタイプを (存在すれば) 取得する


実行する

  • ≪ ReflectionMethod::hasPrototype
  • ReflectionMethod::invokeArgs ≫
  • PHP Manual
  • ReflectionMethod
  • 実行する

ReflectionMethod::invoke

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::invoke — 実行する

説明

public ReflectionMethod::invoke(?object $object, mixed ...$args): mixed

メソッドを実行します。

パラメータ

object

メソッドを実行するオブジェクト。staticメソッドを実行する場合は、このパラメータには null を渡すことができます。

args

メソッドに渡すパラメータ。可変長のパラメータを渡すことができます。

戻り値

メソッドの結果を返します。

エラー / 例外

メソッドが宣言されているクラスのインスタンス以外を object パラメータで指定すると ReflectionException が発生します。

メソッドの実行に失敗すると ReflectionException が発生します。

例

例1 ReflectionMethod::invoke() の例

<?php
class HelloWorld {

public function sayHelloTo($name) {
return 'Hello ' . $name;
}

}

$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
echo $reflectionMethod->invoke(new HelloWorld(), 'Mike');
?>

上の例の出力は以下となります。

Hello Mike

注意

注意:

ReflectionMethod::invoke() は、 リファレンスが引数に期待されている場合は使えません。 その場合は、(引数リストにリファレンスを渡して) ReflectionMethod::invokeArgs() を代わりに使うべきです。

参考

  • ReflectionMethod::invokeArgs() - 実行する
  • __invoke()
  • call_user_func() - 最初の引数で指定したコールバック関数をコールする


実行する

  • ≪ ReflectionMethod::invoke
  • ReflectionMethod::isAbstract ≫
  • PHP Manual
  • ReflectionMethod
  • 実行する

ReflectionMethod::invokeArgs

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionMethod::invokeArgs — 実行する

説明

public ReflectionMethod::invokeArgs(?object $object, array $args): mixed

リフレクション対象のメソッドを実行し、その引数を配列として渡します。

パラメータ

object

メソッドを実行するオブジェクト。staticメソッドを実行する場合は、このパラメータには null を渡すことができます。

args

メソッドに渡すパラメータを配列で指定します。

戻り値

メソッドの結果を返します。

エラー / 例外

メソッドが宣言されているクラスのインスタンス以外を object パラメータで指定すると ReflectionException が発生します。

メソッドの実行に失敗すると ReflectionException が発生します。

変更履歴

バージョン | 説明
8.0.0 | args のキーは、 静かに無視されるのではなく、パラメータの名前として解釈されるようになりました。

例

例1 ReflectionMethod::invokeArgs() の例

<?php
class HelloWorld {

public function sayHelloTo($name) {
return 'Hello ' . $name;
}

}

$reflectionMethod = new ReflectionMethod('HelloWorld', 'sayHelloTo');
echo $reflectionMethod->invokeArgs(new HelloWorld(), array('Mike'));
?>

上の例の出力は以下となります。

Hello Mike

注意

注意:

関数の引数の中にリファレンス渡しを要するものがある場合は、 渡す引数の中でもリファレンスにしておく必要があります。

参考

  • ReflectionMethod::invoke() - 実行する
  • __invoke()
  • call_user_func_array() - パラメータの配列を指定してコールバック関数をコールする


抽象メソッドであるかどうかを調べる

  • ≪ ReflectionMethod::invokeArgs
  • ReflectionMethod::isConstructor ≫
  • PHP Manual
  • ReflectionMethod
  • 抽象メソッドであるかどうかを調べる

ReflectionMethod::isAbstract

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isAbstract — 抽象メソッドであるかどうかを調べる

説明

public ReflectionMethod::isAbstract(): bool

抽象メソッドであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

抽象メソッドである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::getDeclaringClass() - メソッドが宣言されているクラスを取得する


コンストラクタであるかどうかを調べる

  • ≪ ReflectionMethod::isAbstract
  • ReflectionMethod::isDestructor ≫
  • PHP Manual
  • ReflectionMethod
  • コンストラクタであるかどうかを調べる

ReflectionMethod::isConstructor

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isConstructor — コンストラクタであるかどうかを調べる

説明

public ReflectionMethod::isConstructor(): bool

コンストラクタであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

コンストラクタである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::__construct() - ReflectionMethod を作成する
  • ReflectionMethod::isAbstract() - 抽象メソッドであるかどうかを調べる
  • ReflectionMethod::isDestructor() - デストラクタであるかどうかを調べる


デストラクタであるかどうかを調べる

  • ≪ ReflectionMethod::isConstructor
  • ReflectionMethod::isFinal ≫
  • PHP Manual
  • ReflectionMethod
  • デストラクタであるかどうかを調べる

ReflectionMethod::isDestructor

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isDestructor — デストラクタであるかどうかを調べる

説明

public ReflectionMethod::isDestructor(): bool

デストラクタであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

デストラクタである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::isConstructor() - コンストラクタであるかどうかを調べる


final メソッドであるかどうかを調べる

  • ≪ ReflectionMethod::isDestructor
  • ReflectionMethod::isPrivate ≫
  • PHP Manual
  • ReflectionMethod
  • final メソッドであるかどうかを調べる

ReflectionMethod::isFinal

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isFinal — final メソッドであるかどうかを調べる

説明

public ReflectionMethod::isFinal(): bool

final メソッドであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

final メソッドである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::isStatic()


private メソッドであるかどうかを調べる

  • ≪ ReflectionMethod::isFinal
  • ReflectionMethod::isProtected ≫
  • PHP Manual
  • ReflectionMethod
  • private メソッドであるかどうかを調べる

ReflectionMethod::isPrivate

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isPrivate — private メソッドであるかどうかを調べる

説明

public ReflectionMethod::isPrivate(): bool

private メソッドであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

private メソッドである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::isPublic() - public メソッドであるかどうかを調べる


protected メソッドであるかどうかを調べる

  • ≪ ReflectionMethod::isPrivate
  • ReflectionMethod::isPublic ≫
  • PHP Manual
  • ReflectionMethod
  • protected メソッドであるかどうかを調べる

ReflectionMethod::isProtected

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isProtected — protected メソッドであるかどうかを調べる

説明

public ReflectionMethod::isProtected(): bool

protected メソッドであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

protected メソッドである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::isPrivate() - private メソッドであるかどうかを調べる


public メソッドであるかどうかを調べる

  • ≪ ReflectionMethod::isProtected
  • ReflectionMethod::setAccessible ≫
  • PHP Manual
  • ReflectionMethod
  • public メソッドであるかどうかを調べる

ReflectionMethod::isPublic

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::isPublic — public メソッドであるかどうかを調べる

説明

public ReflectionMethod::isPublic(): bool

public メソッドであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

public メソッドである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionMethod::isPrivate() - private メソッドであるかどうかを調べる


メソッドのアクセス範囲を設定する

  • ≪ ReflectionMethod::isPublic
  • ReflectionMethod::__toString ≫
  • PHP Manual
  • ReflectionMethod
  • メソッドのアクセス範囲を設定する

ReflectionMethod::setAccessible

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

ReflectionMethod::setAccessible — メソッドのアクセス範囲を設定する

説明

public ReflectionMethod::setAccessible(bool $accessible): void

ReflectionMethod::invoke() メソッド経由で、 protected や private なメソッドを呼び出し可能にします。

注意: PHP 8.1.0 以降は、このメソッドをコールしても何も起こりません。 つまり、全てのメソッドはデフォルトで呼び出し可能です。

パラメータ

accessible

true を指定すると、アクセスできるようになります。

戻り値

値を返しません。

例

例1 簡単なクラス定義

<?php
class MyClass
{
private function foo()
{
return 'bar';
}
}

$method = new ReflectionMethod("MyClass", "foo");
$method->setAccessible(true);

$obj = new MyClass();
echo $method->invoke($obj);
echo $obj->foo();
?>

上の例の出力は、 たとえば以下のようになります。

bar
Fatal error: Uncaught Error: Call to private method MyClass::foo() from global scope in /in/qdaZS:16

参考

  • ReflectionMethod::isPrivate() - private メソッドであるかどうかを調べる
  • ReflectionMethod::isProtected() - protected メソッドであるかどうかを調べる


ReflectionMethod オブジェクトの文字列表現を返す

  • ≪ ReflectionMethod::setAccessible
  • ReflectionNamedType ≫
  • PHP Manual
  • ReflectionMethod
  • ReflectionMethod オブジェクトの文字列表現を返す

ReflectionMethod::__toString

(PHP 5, PHP 7, PHP 8)

ReflectionMethod::__toString — ReflectionMethod オブジェクトの文字列表現を返す

説明

public ReflectionMethod::__toString(): string

ReflectionMethod オブジェクトの文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionMethod のインスタンスの文字列表現を返します。

例

例1 ReflectionMethod::__toString() の例

<?php
class HelloWorld {

public function sayHelloTo($name) {
return 'Hello ' . $name;
}

}

$reflectionMethod = new ReflectionMethod(new HelloWorld(), 'sayHelloTo');
echo $reflectionMethod;
?>

上の例の出力は以下となります。

Method [ <user> public method sayHelloTo ] {
  @@ /var/www/examples/reflection.php 16 - 18

  - Parameters [1] {
    Parameter #0 [ <required> $name ]
  }
}

参考

  • ReflectionMethod::export() - メソッドをエクスポートする
  • __toString()


ReflectionNamedType クラス

(PHP 7 >= 7.1.0, PHP 8)

はじめに

クラス概要

class ReflectionNamedType extends ReflectionType {
/* メソッド */
public getName(): string
public isBuiltin(): bool
/* 継承したメソッド */
public ReflectionType::allowsNull(): bool
public ReflectionType::__toString(): string
}

目次

  • ReflectionNamedType::getName — 型の名前の文字列を取得する
  • ReflectionNamedType::isBuiltin — 組み込みの型であるかを調べる


型の名前の文字列を取得する

  • ≪ ReflectionNamedType
  • ReflectionNamedType::isBuiltin ≫
  • PHP Manual
  • ReflectionNamedType
  • 型の名前の文字列を取得する

ReflectionNamedType::getName

(PHP 7 >= 7.1.0, PHP 8)

ReflectionNamedType::getName — 型の名前の文字列を取得する

説明

public ReflectionNamedType::getName(): string

パラメータ

この関数にはパラメータはありません。

戻り値

リフレクションされた型の名前を返します。

参考

  • ReflectionType::__toString() - 文字列に変換する


組み込みの型であるかを調べる

  • ≪ ReflectionNamedType::getName
  • ReflectionObject ≫
  • PHP Manual
  • ReflectionNamedType
  • 組み込みの型であるかを調べる

ReflectionNamedType::isBuiltin

(PHP 7, PHP 8)

ReflectionNamedType::isBuiltin — 組み込みの型であるかを調べる

説明

public ReflectionNamedType::isBuiltin(): bool

PHP に元々組み込まれた型であるかを調べます。 元々組み込まれた型とは、クラス、インターフェイス、トレイトのいずれでもない型を指します。

パラメータ

この関数にはパラメータはありません。

戻り値

組み込みの型である場合は true を、そうでない場合は false を返します。

例

例1 ReflectionNamedType::isBuiltin() の例

<?php
class SomeClass {}

function someFunction(string $param, SomeClass $param2, stdClass $param3) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParams = $reflectionFunc->getParameters();

var_dump($reflectionParams[0]->getType()->isBuiltin());
var_dump($reflectionParams[1]->getType()->isBuiltin());
var_dump($reflectionParams[2]->getType()->isBuiltin());

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)

ReflectionNamedType::isBuiltin() メソッドは、 内部クラスとカスタムのクラスを区別しないことに注意して下さい。 それらを区別するには、返されたクラス名に対して ReflectionClass::isInternal() メソッドを使うべきです。

参考

  • ReflectionType::allowsNull() - null が許されるかをチェックする
  • ReflectionType::__toString() - 文字列に変換する
  • ReflectionClass::isInternal() - 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる
  • ReflectionParameter::getType() - 引数の型を取得する


ReflectionObject クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionObject クラスは オブジェクトについての情報を報告します。

クラス概要

class ReflectionObject extends ReflectionClass {
/* 継承した定数 */
public const int ReflectionClass::IS_IMPLICIT_ABSTRACT;
public const int ReflectionClass::IS_EXPLICIT_ABSTRACT;
public const int ReflectionClass::IS_FINAL;
public const int ReflectionClass::IS_READONLY;
/* 継承したプロパティ */
public string $name;
/* メソッド */
public __construct(object $object)
/* 継承したメソッド */
public static ReflectionClass::export(mixed $argument, bool $return = false): string
public ReflectionClass::getAttributes(?string $name = null, int $flags = 0): array
public ReflectionClass::getConstant(string $name): mixed
public ReflectionClass::getConstants(?int $filter = null): array
public ReflectionClass::getConstructor(): ?ReflectionMethod
public ReflectionClass::getDefaultProperties(): array
public ReflectionClass::getDocComment(): string|false
public ReflectionClass::getEndLine(): int|false
public ReflectionClass::getExtension(): ?ReflectionExtension
public ReflectionClass::getExtensionName(): string|false
public ReflectionClass::getFileName(): string|false
public ReflectionClass::getInterfaceNames(): array
public ReflectionClass::getInterfaces(): array
public ReflectionClass::getMethod(string $name): ReflectionMethod
public ReflectionClass::getMethods(?int $filter = null): array
public ReflectionClass::getModifiers(): int
public ReflectionClass::getName(): string
public ReflectionClass::getNamespaceName(): string
public ReflectionClass::getParentClass(): ReflectionClass|false
public ReflectionClass::getProperties(?int $filter = null): array
public ReflectionClass::getProperty(string $name): ReflectionProperty
public ReflectionClass::getReflectionConstant(string $name): ReflectionClassConstant|false
public ReflectionClass::getReflectionConstants(?int $filter = null): array
public ReflectionClass::getShortName(): string
public ReflectionClass::getStartLine(): int|false
public ReflectionClass::getStaticProperties(): array
public ReflectionClass::getStaticPropertyValue(string $name, mixed &$def_value = ?): mixed
public ReflectionClass::getTraitAliases(): array
public ReflectionClass::getTraitNames(): array
public ReflectionClass::getTraits(): array
public ReflectionClass::hasConstant(string $name): bool
public ReflectionClass::hasMethod(string $name): bool
public ReflectionClass::hasProperty(string $name): bool
public ReflectionClass::implementsInterface(ReflectionClass|string $interface): bool
public ReflectionClass::inNamespace(): bool
public ReflectionClass::isAbstract(): bool
public ReflectionClass::isAnonymous(): bool
public ReflectionClass::isCloneable(): bool
public ReflectionClass::isEnum(): bool
public ReflectionClass::isFinal(): bool
public ReflectionClass::isInstance(object $object): bool
public ReflectionClass::isInstantiable(): bool
public ReflectionClass::isInterface(): bool
public ReflectionClass::isInternal(): bool
public ReflectionClass::isIterable(): bool
public ReflectionClass::isReadOnly(): bool
public ReflectionClass::isSubclassOf(ReflectionClass|string $class): bool
public ReflectionClass::isTrait(): bool
public ReflectionClass::isUserDefined(): bool
public ReflectionClass::newInstance(mixed ...$args): object
public ReflectionClass::newInstanceArgs(array $args = []): ?object
public ReflectionClass::newInstanceWithoutConstructor(): object
public ReflectionClass::setStaticPropertyValue(string $name, mixed $value): void
public ReflectionClass::__toString(): string
}

変更履歴

バージョン | 説明
8.0.0 | ReflectionObject::export() は、削除されました。

目次

  • ReflectionObject::__construct — ReflectionObject を作成する
  • ReflectionObject::export — エクスポートする


ReflectionObject を作成する

  • ≪ ReflectionObject
  • ReflectionObject::export ≫
  • PHP Manual
  • ReflectionObject
  • ReflectionObject を作成する

ReflectionObject::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionObject::__construct — ReflectionObject を作成する

説明

public ReflectionObject::__construct(object $object)

ReflectionObject を作成します。

パラメータ

object

オブジェクトのインスタンス。

参考

  • ReflectionObject::export() - エクスポートする
  • コンストラクタ


エクスポートする

  • ≪ ReflectionObject::__construct
  • ReflectionParameter ≫
  • PHP Manual
  • ReflectionObject
  • エクスポートする

ReflectionObject::export

(PHP 5, PHP 7)

ReflectionObject::export — エクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionObject::export(string $argument, bool $return = ?): string

リフレクションをエクスポートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

argument

エクスポートするリフレクション。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

return パラメータを true に設定すると、エクスポートを文字列で返します。それ以外の場合は null を返します。

参考

  • ReflectionObject::__construct() - ReflectionObject を作成する


ReflectionParameter クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionParameter クラスは、 関数またはメソッドのパラメータに関する情報を取得します。

関数パラメータの内部を調べる際には、まず ReflectionFunction クラスまたは ReflectionMethod クラスのインスタンスを作成する必要があります。次に、 ReflectionFunctionAbstract::getParameters() メソッドを使ってパラメータの配列を取得します。

クラス概要

class ReflectionParameter implements Reflector {
/* プロパティ */
public string $name;
/* メソッド */
public __construct(string|array|object $function, int|string $param)
public allowsNull(): bool
public canBePassedByValue(): bool
private __clone(): void
public static export(string $function, string $parameter, bool $return = ?): string
public getAttributes(?string $name = null, int $flags = 0): array
public getClass(): ?ReflectionClass
public getDeclaringClass(): ?ReflectionClass
public getDeclaringFunction(): ReflectionFunctionAbstract
public getDefaultValue(): mixed
public getDefaultValueConstantName(): ?string
public getName(): string
public getPosition(): int
public getType(): ?ReflectionType
public hasType(): bool
public isArray(): bool
public isCallable(): bool
public isDefaultValueAvailable(): bool
public isDefaultValueConstant(): bool
public isOptional(): bool
public isPassedByReference(): bool
public isVariadic(): bool
public __toString(): string
}

プロパティ

name

パラメータ名。読み込み専用で、書き込もうとすると ReflectionException をスローします。

変更履歴

バージョン | 説明
8.0.0 | ReflectionParameter::export() は、削除されました。

目次

  • ReflectionParameter::allowsNull — null を許可するかどうかを調べる
  • ReflectionParameter::canBePassedByValue — このパラメータが値渡し可能かどうかを返す
  • ReflectionParameter::__clone — クローンする
  • ReflectionParameter::__construct — コンストラクタ
  • ReflectionParameter::export — エクスポートする
  • ReflectionParameter::getAttributes — アトリビュートを取得する
  • ReflectionParameter::getClass — リフレクションされた ReflectionClass を取得する。
  • ReflectionParameter::getDeclaringClass — 宣言しているクラスを取得する
  • ReflectionParameter::getDeclaringFunction — 宣言している関数を取得する
  • ReflectionParameter::getDefaultValue — パラメータのデフォルト値を取得する
  • ReflectionParameter::getDefaultValueConstantName — デフォルト値が定数あるいは null の場合に、その定数名を返す
  • ReflectionParameter::getName — パラメータ名を取得する
  • ReflectionParameter::getPosition — パラメータの位置を取得する
  • ReflectionParameter::getType — 引数の型を取得する
  • ReflectionParameter::hasType — 引数が型を持つかを調べる
  • ReflectionParameter::isArray — 配列を受け取るパラメータであるかどうかを調べる
  • ReflectionParameter::isCallable — パラメータが callable かどうかを返す
  • ReflectionParameter::isDefaultValueAvailable — デフォルト値が存在するかどうかを調べる
  • ReflectionParameter::isDefaultValueConstant — このパラメータのデフォルト値が定数かどうかを返す
  • ReflectionParameter::isOptional — 省略可能であるかどうかを調べる
  • ReflectionParameter::isPassedByReference — 参照渡しかどうかを調べる
  • ReflectionParameter::isVariadic — 引数が可変長の個数であるかをチェックする
  • ReflectionParameter::__toString — 文字列に変換する


null を許可するかどうかを調べる

  • ≪ ReflectionParameter
  • ReflectionParameter::canBePassedByValue ≫
  • PHP Manual
  • ReflectionParameter
  • null を許可するかどうかを調べる

ReflectionParameter::allowsNull

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::allowsNull — null を許可するかどうかを調べる

説明

public ReflectionParameter::allowsNull(): bool

パラメータが null を許可するかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

null を許可する場合に true、それ以外の場合に false を返します。

参考

  • ReflectionParameter::isOptional() - 省略可能であるかどうかを調べる


このパラメータが値渡し可能かどうかを返す

  • ≪ ReflectionParameter::allowsNull
  • ReflectionParameter::__clone ≫
  • PHP Manual
  • ReflectionParameter
  • このパラメータが値渡し可能かどうかを返す

ReflectionParameter::canBePassedByValue

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionParameter::canBePassedByValue — このパラメータが値渡し可能かどうかを返す

説明

public ReflectionParameter::canBePassedByValue(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

このパラメータが値渡し可能な場合に true、それ以外の場合に false を返します。 エラー時には null を返します。


クローンする

  • ≪ ReflectionParameter::canBePassedByValue
  • ReflectionParameter::__construct ≫
  • PHP Manual
  • ReflectionParameter
  • クローンする

ReflectionParameter::__clone

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::__clone — クローンする

説明

private ReflectionParameter::__clone(): void

クローンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

変更履歴

バージョン | 説明
8.1.0 | このメソッドは、final ではなくなりました。

参考

  • ReflectionParameter::toString()
  • オブジェクトのクローン作成


コンストラクタ

  • ≪ ReflectionParameter::__clone
  • ReflectionParameter::export ≫
  • PHP Manual
  • ReflectionParameter
  • コンストラクタ

ReflectionParameter::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::__construct — コンストラクタ

説明

public ReflectionParameter::__construct(string|array|object $function, int|string $param)

ReflectionParameter クラスのインスタンスを構築します。

パラメータ

function

パラメータを調べたい関数。

param

パラメータの位置を指定する int (0から始まります)、 もしくはパラメータの名前を string で指定します。

例

例1 ReflectionParameter クラスの使用

<?php
function foo($a, $b, $c) { }
function bar(Exception $a, &$b, $c) { }
function baz(ReflectionFunction $a, $b = 1, $c = null) { }
function abc() { }

$reflect = new ReflectionFunction('foo');

echo $reflect;

foreach ($reflect->getParameters() as $i => $param) {
printf(
"-- Parameter #%d: %s {\n".
" Class: %s\n".
" Allows NULL: %s\n".
" Passed to by reference: %s\n".
" Is optional?: %s\n".
"}\n",
$i, // $param->getPosition() can be used
$param->getName(),
var_export($param->getClass(), 1),
var_export($param->allowsNull(), 1),
var_export($param->isPassedByReference(), 1),
$param->isOptional() ? 'yes' : 'no'
);
}
?>

上の例の出力は、 たとえば以下のようになります。

Function [ <user> function foo ] {
  @@ /Users/philip/cvs/phpdoc/a 2 - 2

  - Parameters [3] {
    Parameter #0 [ <required> $a ]
    Parameter #1 [ <required> $b ]
    Parameter #2 [ <required> $c ]
  }
}
-- Parameter #0: a {
   Class: NULL
   Allows NULL: true
   Passed to by reference: false
   Is optional?: no
}
-- Parameter #1: b {
   Class: NULL
   Allows NULL: true
   Passed to by reference: false
   Is optional?: no
}
-- Parameter #2: c {
   Class: NULL
   Allows NULL: true
   Passed to by reference: false
   Is optional?: no
}

参考

  • ReflectionFunctionAbstract::getParameters() - パラメータを取得する
  • ReflectionFunction::__construct() - ReflectionFunction オブジェクトを作成する
  • ReflectionMethod::__construct() - ReflectionMethod を作成する
  • コンストラクタ


エクスポートする

  • ≪ ReflectionParameter::__construct
  • ReflectionParameter::getAttributes ≫
  • PHP Manual
  • ReflectionParameter
  • エクスポートする

ReflectionParameter::export

(PHP 5, PHP 7)

ReflectionParameter::export — エクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionParameter::export(string $function, string $parameter, bool $return = ?): string

エクスポートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

function

関数名。

parameter

パラメータ名。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

エクスポート結果を返します。

参考

  • ReflectionParameter::__toString() - 文字列に変換する


アトリビュートを取得する

  • ≪ ReflectionParameter::export
  • ReflectionParameter::getClass ≫
  • PHP Manual
  • ReflectionParameter
  • アトリビュートを取得する

ReflectionParameter::getAttributes

(PHP 8)

ReflectionParameter::getAttributes — アトリビュートを取得する

説明

public ReflectionParameter::getAttributes(?string $name = null, int $flags = 0): array

この引数上で宣言されている全てのアトリビュートを、 ReflectionAttribute の配列として返します。

パラメータ

name

指定したクラス名にマッチするアトリビュートの、 ReflectionAttribute のみを含むようにフィルタします。

flags

name が指定されていた場合に、 結果をどうフィルタするかを決めるフラグ。

デフォルトは 0 です。 この場合、アトリビュートのクラス名が name であるものだけを返します。

他の利用可能なオプションは、 ReflectionAttribute::IS_INSTANCEOF です。 この場合、フィルタリングに instanceof を使います。

戻り値

アトリビュートの配列を、 ReflectionAttribute オブジェクトの配列として返します。

例

例1 基本的な使い方

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

function fruitBasket(
#[Fruit]
#[Red]
string $apple
) { }

$reflection = new ReflectionFunction('fruitBasket');
$parameter = $reflection->getParameter('apple');
$attributes = $parameter->getAttributes();
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
    [1] => Red
)

例2 クラス名で結果をフィルタする

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

function fruitBasket(
#[Fruit]
#[Red]
string $apple
) { }

$reflection = new ReflectionFunction('fruitBasket');
$parameter = $reflection->getParameter('apple');
$attributes = $parameter->getAttributes('Fruit');
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
)

例3 クラス名、かつ継承も考慮して結果をフィルタする

<?php
interface Color {
}

#[Attribute]
class Fruit {
}

function fruitBasket(
#[Fruit]
#[Red]
string $apple
) { }

$reflection = new ReflectionFunction('fruitBasket');
$parameter = $reflection->getParameter('apple');
$attributes = $parameter->getAttributes('Color', ReflectionAttribute::IS_INSTANCEOF);
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Red
)

参考

  • ReflectionClass::getAttributes() - アトリビュートを取得する
  • ReflectionClassConstant::getAttributes() - アトリビュートを取得する
  • ReflectionFunctionAbstract::getAttributes() - アトリビュートを取得する
  • ReflectionProperty::getAttributes() - アトリビュートを取得する


リフレクションされた ReflectionClass を取得する。

  • ≪ ReflectionParameter::getAttributes
  • ReflectionParameter::getDeclaringClass ≫
  • PHP Manual
  • ReflectionParameter
  • リフレクションされた ReflectionClass を取得する。

ReflectionParameter::getClass

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::getClass — リフレクションされた ReflectionClass を取得する。

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

public ReflectionParameter::getClass(): ?ReflectionClass

パラメータとしてリフレクションされたクラスを、 ReflectionClass オブジェクトとして取得するか、null を返します。

PHP 8.0.0 以降は、この関数を使うことは推奨されなくなりました。 代わりに、引数の型を調べるために ReflectionType を取得して下さい。 それを取得するには、ReflectionParameter::getType() を使います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionClass オブジェクトを返します。 型が宣言されていないか、 宣言されていてもクラスやインターフェイスでない場合は、null を返します。

例

例1 ReflectionParameter クラスの利用法

<?php
function foo(Exception $a) { }

$functionReflection = new ReflectionFunction('foo');
$parameters = $functionReflection->getParameters();
$aParameter = $parameters[0];

echo $aParameter->getClass()->name;
?>

参考

  • ReflectionParameter::getDeclaringClass() - 宣言しているクラスを取得する


宣言しているクラスを取得する

  • ≪ ReflectionParameter::getClass
  • ReflectionParameter::getDeclaringFunction ≫
  • PHP Manual
  • ReflectionParameter
  • 宣言しているクラスを取得する

ReflectionParameter::getDeclaringClass

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

ReflectionParameter::getDeclaringClass — 宣言しているクラスを取得する

説明

public ReflectionParameter::getDeclaringClass(): ?ReflectionClass

宣言しているクラスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionClass オブジェクトを返します。 関数の中で呼ばれた場合、null を返します。

例

例1 メソッドを宣言しているクラスの取得

<?php
class Foo
{
public function bar(\DateTime $datetime)
{
}
}

class Baz extends Foo
{
}

$param = new \ReflectionParameter(['Baz', 'bar'], 0);

var_dump($param->getDeclaringClass());

上の例の出力は以下となります。

object(ReflectionClass)#2 (1) {
  ["name"]=>
  string(3) "Foo"
}

参考

  • ReflectionParameter::getClass() - リフレクションされた ReflectionClass を取得する。


宣言している関数を取得する

  • ≪ ReflectionParameter::getDeclaringClass
  • ReflectionParameter::getDefaultValue ≫
  • PHP Manual
  • ReflectionParameter
  • 宣言している関数を取得する

ReflectionParameter::getDeclaringFunction

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

ReflectionParameter::getDeclaringFunction — 宣言している関数を取得する

説明

public ReflectionParameter::getDeclaringFunction(): ReflectionFunctionAbstract

宣言している関数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionFunction オブジェクトを返します。

参考

  • ReflectionParameter::getDeclaringClass() - 宣言しているクラスを取得する


パラメータのデフォルト値を取得する

  • ≪ ReflectionParameter::getDeclaringFunction
  • ReflectionParameter::getDefaultValueConstantName ≫
  • PHP Manual
  • ReflectionParameter
  • パラメータのデフォルト値を取得する

ReflectionParameter::getDefaultValue

(PHP 5 >= 5.0.3, PHP 7, PHP 8)

ReflectionParameter::getDefaultValue — パラメータのデフォルト値を取得する

説明

public ReflectionParameter::getDefaultValue(): mixed

(内部またはユーザー定義の) 関数あるいはメソッドで、パラメータのデフォルト値を取得します。 省略可能なパラメータでない場合は ReflectionException がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

パラメータのデフォルト対を返します。

変更履歴

バージョン | 説明
8.0.0 | ビルトイン関数 や ビルトインクラス のメソッドについても、デフォルト値を取得できるようになりました。 これより前のバージョンでは、ReflectionException がスローされていました。

例

例1 関数のパラメータのデフォルト値を取得する

<?php
function foo($test, $bar = 'baz')
{
echo $test . $bar;
}

$function = new ReflectionFunction('foo');

foreach ($function->getParameters() as $param) {
echo 'Name: ' . $param->getName() . PHP_EOL;
if ($param->isOptional()) {
echo 'Default value: ' . $param->getDefaultValue() . PHP_EOL;
}
echo PHP_EOL;
}
?>

上の例の出力は以下となります。

Name: test

Name: bar
Default value: baz

参考

  • ReflectionParameter::isOptional() - 省略可能であるかどうかを調べる
  • ReflectionParameter::isDefaultValueAvailable() - デフォルト値が存在するかどうかを調べる
  • ReflectionParameter::getDefaultValueConstantName() - デフォルト値が定数あるいは null の場合に、その定数名を返す
  • ReflectionParameter::isPassedByReference() - 参照渡しかどうかを調べる


デフォルト値が定数あるいは null の場合に、その定数名を返す

  • ≪ ReflectionParameter::getDefaultValue
  • ReflectionParameter::getName ≫
  • PHP Manual
  • ReflectionParameter
  • デフォルト値が定数あるいは null の場合に、その定数名を返す

ReflectionParameter::getDefaultValueConstantName

(PHP 5 >= 5.4.6, PHP 7, PHP 8)

ReflectionParameter::getDefaultValueConstantName — デフォルト値が定数あるいは null の場合に、その定数名を返す

説明

public ReflectionParameter::getDefaultValueConstantName(): ?string

デフォルト値が定数か null の場合に、 (内部またはユーザー定義の) 関数やメソッドのデフォルト値の定数名を返します。 パラメータがオプションでない場合は、 ReflectionException がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に文字列、失敗した場合に null を返します。

変更履歴

バージョン | 説明
8.0.0 | ビルトイン関数 や ビルトインクラス のメソッドについても、デフォルト値の定数名を取得できるようになりました。 これより前のバージョンでは、ReflectionException がスローされていました。

例

例1 関数のパラメーターのデフォルト値の定数を取得する

<?php
function foo($test, $bar = PHP_INT_MIN)
{
echo $test . $bar;
}

$function = new ReflectionFunction('foo');

foreach ($function->getParameters() as $param) {
echo 'Name: ' . $param->getName() . PHP_EOL;
if ($param->isOptional()) {
echo 'Default value: ' . $param->getDefaultValueConstantName() . PHP_EOL;
}
echo PHP_EOL;
}
?>

上の例の出力は以下となります。

Name: test

Name: bar
Default value: PHP_INT_MIN

参考

  • ReflectionParameter::isOptional() - 省略可能であるかどうかを調べる
  • ReflectionParameter::isDefaultValueConstant() - このパラメータのデフォルト値が定数かどうかを返す
  • ReflectionParameter::getDefaultValue() - パラメータのデフォルト値を取得する


パラメータ名を取得する

  • ≪ ReflectionParameter::getDefaultValueConstantName
  • ReflectionParameter::getPosition ≫
  • PHP Manual
  • ReflectionParameter
  • パラメータ名を取得する

ReflectionParameter::getName

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::getName — パラメータ名を取得する

説明

public ReflectionParameter::getName(): string

パラメータ名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

パラメータ名を返します。

参考

  • ReflectionParameter::getValue()


パラメータの位置を取得する

  • ≪ ReflectionParameter::getName
  • ReflectionParameter::getType ≫
  • PHP Manual
  • ReflectionParameter
  • パラメータの位置を取得する

ReflectionParameter::getPosition

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

ReflectionParameter::getPosition — パラメータの位置を取得する

説明

public ReflectionParameter::getPosition(): int

パラメータの位置を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

パラメータの位置を取得します。左から右へ数え、最初のパラメータが 0 番目となります。

参考

  • ReflectionParameter::getName() - パラメータ名を取得する


引数の型を取得する

  • ≪ ReflectionParameter::getPosition
  • ReflectionParameter::hasType ≫
  • PHP Manual
  • ReflectionParameter
  • 引数の型を取得する

ReflectionParameter::getType

(PHP 7, PHP 8)

ReflectionParameter::getType — 引数の型を取得する

説明

public ReflectionParameter::getType(): ?ReflectionType

引数の型を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

引数の型が指定されていれば ReflectionType オブジェクトを返します。 そうでなければ null を返します。

例

例1 PHP 7.1.0 以降での ReflectionParameter::getType() の使い方

PHP 7.1.0 以降では、 ReflectionType::__toString() が推奨されなくなったので、 ReflectionParameter::getType() は ReflectionNamedType を返す 可能性があります。 この場合、引数の方の名前を取得するために、ReflectionNamedType() が利用可能です。

<?php
function someFunction(int $param, $param2) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParams = $reflectionFunc->getParameters();
$reflectionType1 = $reflectionParams[0]->getType();
$reflectionType2 = $reflectionParams[1]->getType();

assert($reflectionType1 instanceof ReflectionNamedType);
echo $reflectionType1->getName(), PHP_EOL;
var_dump($reflectionType2);
?>

上の例の出力は以下となります。

int
NULL

例2 PHP 7.1.0 より前の ReflectionParameter::getType() の使い方

<?php
function someFunction(int $param, $param2) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParams = $reflectionFunc->getParameters();
$reflectionType1 = $reflectionParams[0]->getType();
$reflectionType2 = $reflectionParams[1]->getType();

echo $reflectionType1, PHP_EOL;
var_dump($reflectionType2);
?>

上の例の PHP 7.0 での出力は、このようになります。

int
NULL

例3 PHP 8.0.0 以降の ReflectionParameter::getType() の使い方

PHP 8.0.0 以降では、このメソッドは ReflectionNamedType や ReflectionUnionType のインスタンスを返す可能性があります。 後者は前者の集合です。後者の型を解析するには、 ReflectionNamedType の配列に正規化する方が便利です。 以下の例に示す関数は、0 または ReflectionNamedType のインスタンスの配列を返します。

<?php
function getAllTypes(ReflectionParameter $reflectionParameter): array
{
$reflectionType = $reflectionParameter->getType();
if (!$reflectionType) return [];
return $reflectionType instanceof ReflectionUnionType
? $reflectionType->getTypes()
: [$reflectionType];
}
?>

参考

  • ReflectionParameter::hasType() - 引数が型を持つかを調べる
  • ReflectionType::__toString() - 文字列に変換する


引数が型を持つかを調べる

  • ≪ ReflectionParameter::getType
  • ReflectionParameter::isArray ≫
  • PHP Manual
  • ReflectionParameter
  • 引数が型を持つかを調べる

ReflectionParameter::hasType

(PHP 7, PHP 8)

ReflectionParameter::hasType — 引数が型を持つかを調べる

説明

public ReflectionParameter::hasType(): bool

引数が、関連する型を持つかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

型が指定されていれば true を。そうでなければ false を返します。

例

例1 ReflectionParameter::hasType() の例

<?php
function someFunction(string $param, $param2 = null) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParams = $reflectionFunc->getParameters();

var_dump($reflectionParams[0]->hasType());
var_dump($reflectionParams[1]->hasType());

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)

参考

  • ReflectionParameter::getType() - 引数の型を取得する


配列を受け取るパラメータであるかどうかを調べる

  • ≪ ReflectionParameter::hasType
  • ReflectionParameter::isCallable ≫
  • PHP Manual
  • ReflectionParameter
  • 配列を受け取るパラメータであるかどうかを調べる

ReflectionParameter::isArray

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

ReflectionParameter::isArray — 配列を受け取るパラメータであるかどうかを調べる

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

配列を受け取るパラメータかどうかを調べる別の方法については、下に示す例を参照ください。

説明

public ReflectionParameter::isArray(): bool

配列を受け取るパラメータであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

配列を受け取るパラメータである場合に true、それ以外の場合に false を返します。

例

例1 PHP 8.0.0 以降で同等のことを行うには

PHP 8.0.0 以降では、以下のコードは union の一部であった場合も含めて、配列型を宣言しているかどうかを報告します。

<?php
function declaresArray(ReflectionParameter $reflectionParameter): bool
{
$reflectionType = $reflectionParameter->getType();
if (!$reflectionType) return false;
$types = $reflectionType instanceof ReflectionUnionType
? $reflectionType->getTypes()
: [$reflectionType];
return in_array('array', array_map(fn(ReflectionNamedType $t) => $t->getName(), $types));
}
?>

参考

  • ReflectionParameter::isOptional() - 省略可能であるかどうかを調べる


パラメータが callable かどうかを返す

  • ≪ ReflectionParameter::isArray
  • ReflectionParameter::isDefaultValueAvailable ≫
  • PHP Manual
  • ReflectionParameter
  • パラメータが callable かどうかを返す

ReflectionParameter::isCallable

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

ReflectionParameter::isCallable — パラメータが callable かどうかを返す

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

パラメータが callable かどうかを調べる別の方法については、下に示す例を参照ください。

説明

public ReflectionParameter::isCallable(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

例

例1 PHP 8.0.0 以降で同等のことを行うには

PHP 8.0.0 以降では、union 型の一部であるかも含めて、 以下のコードが callable 型を受け取るかどうかを報告します。

<?php
function declaresCallable(ReflectionParameter $reflectionParameter): bool
{
$reflectionType = $reflectionParameter->getType();
if (!$reflectionType) return false;
$types = $reflectionType instanceof ReflectionUnionType
? $reflectionType->getTypes()
: [$reflectionType];
return in_array('callable', array_map(fn(ReflectionNamedType $t) => $t->getName(), $types));
}
?>

戻り値

パラメータが callable の場合に true、そうではない場合に false を返します。 失敗した場合は null を返します。


デフォルト値が存在するかどうかを調べる

  • ≪ ReflectionParameter::isCallable
  • ReflectionParameter::isDefaultValueConstant ≫
  • PHP Manual
  • ReflectionParameter
  • デフォルト値が存在するかどうかを調べる

ReflectionParameter::isDefaultValueAvailable

(PHP 5 >= 5.0.3, PHP 7, PHP 8)

ReflectionParameter::isDefaultValueAvailable — デフォルト値が存在するかどうかを調べる

説明

public ReflectionParameter::isDefaultValueAvailable(): bool

パラメータのデフォルト値が存在するかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

デフォルト値が存在する場合に true、それ以外の場合に false を返します。

参考

  • ReflectionParameter::getDefaultValue() - パラメータのデフォルト値を取得する
  • ReflectionParameter::isDefaultValueConstant() - このパラメータのデフォルト値が定数かどうかを返す
  • ReflectionParameter::getName() - パラメータ名を取得する


このパラメータのデフォルト値が定数かどうかを返す

  • ≪ ReflectionParameter::isDefaultValueAvailable
  • ReflectionParameter::isOptional ≫
  • PHP Manual
  • ReflectionParameter
  • このパラメータのデフォルト値が定数かどうかを返す

ReflectionParameter::isDefaultValueConstant

(PHP 5 >= 5.4.6, PHP 7, PHP 8)

ReflectionParameter::isDefaultValueConstant — このパラメータのデフォルト値が定数かどうかを返す

説明

public ReflectionParameter::isDefaultValueConstant(): bool

このパラメータのデフォルト値が定数かどうかを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

デフォルト値が定数である場合は true を返します。 そうでなければ false を返します。

参考

  • ReflectionParameter::getDefaultValueConstantName() - デフォルト値が定数あるいは null の場合に、その定数名を返す
  • ReflectionParameter::isDefaultValueAvailable() - デフォルト値が存在するかどうかを調べる


省略可能であるかどうかを調べる

  • ≪ ReflectionParameter::isDefaultValueConstant
  • ReflectionParameter::isPassedByReference ≫
  • PHP Manual
  • ReflectionParameter
  • 省略可能であるかどうかを調べる

ReflectionParameter::isOptional

(PHP 5 >= 5.0.3, PHP 7, PHP 8)

ReflectionParameter::isOptional — 省略可能であるかどうかを調べる

説明

public ReflectionParameter::isOptional(): bool

パラメータが省略可能であるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

省略可能である場合に true、それ以外の場合に false を返します。

参考

  • ReflectionParameter::getName() - パラメータ名を取得する


参照渡しかどうかを調べる

  • ≪ ReflectionParameter::isOptional
  • ReflectionParameter::isVariadic ≫
  • PHP Manual
  • ReflectionParameter
  • 参照渡しかどうかを調べる

ReflectionParameter::isPassedByReference

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::isPassedByReference — 参照渡しかどうかを調べる

説明

public ReflectionParameter::isPassedByReference(): bool

パラメータが参照渡しであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

パラメータが参照渡しである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionParameter::getName() - パラメータ名を取得する


引数が可変長の個数であるかをチェックする

  • ≪ ReflectionParameter::isPassedByReference
  • ReflectionParameter::__toString ≫
  • PHP Manual
  • ReflectionParameter
  • 引数が可変長の個数であるかをチェックする

ReflectionParameter::isVariadic

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

ReflectionParameter::isVariadic — 引数が可変長の個数であるかをチェックする

説明

public ReflectionParameter::isVariadic(): bool

引数が 可変長引数リスト として宣言されているかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

引数が可変長であれば true を、そうでなければ false を返します。


文字列に変換する

  • ≪ ReflectionParameter::isVariadic
  • ReflectionProperty ≫
  • PHP Manual
  • ReflectionParameter
  • 文字列に変換する

ReflectionParameter::__toString

(PHP 5, PHP 7, PHP 8)

ReflectionParameter::__toString — 文字列に変換する

説明

public ReflectionParameter::__toString(): string

人間が読めるパラメータの説明を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

文字列を返します。

例

例1 ReflectionParameter::__toString() の例

<?php
echo new ReflectionParameter('substr', 0);
?>

上の例の出力は、 たとえば以下のようになります。

Parameter #0 [ <required> string $string ]

参考

  • ReflectionParameter::export() - エクスポートする
  • __toString()


ReflectionProperty クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionProperty クラスは クラスのプロパティについての情報を報告します。

クラス概要

class ReflectionProperty implements Reflector {
/* 定数 */
public const int IS_STATIC;
public const int IS_READONLY;
public const int IS_PUBLIC;
public const int IS_PROTECTED;
public const int IS_PRIVATE;
/* プロパティ */
public string $name;
public string $class;
/* メソッド */
public __construct(object|string $class, string $property)
private __clone(): void
public static export(mixed $class, string $name, bool $return = ?): string
public getAttributes(?string $name = null, int $flags = 0): array
public getDeclaringClass(): ReflectionClass
public getDefaultValue(): mixed
public getDocComment(): string|false
public getModifiers(): int
public getName(): string
public getType(): ?ReflectionType
public getValue(?object $object = null): mixed
public hasDefaultValue(): bool
public hasType(): bool
public isDefault(): bool
public isInitialized(?object $object = null): bool
public isPrivate(): bool
public isPromoted(): bool
public isProtected(): bool
public isPublic(): bool
public isReadOnly(): bool
public isStatic(): bool
public setAccessible(bool $accessible): void
public setValue(object $object, mixed $value): void
public __toString(): string
}

プロパティ

name

プロパティ名。読み込み専用で、書き込もうとすると ReflectionException をスローします。

class

プロパティが定義されているクラス名。読み込み専用で、書き込もうとすると ReflectionException をスローします。

定義済み定数

ReflectionProperty の修飾子

ReflectionProperty::IS_STATIC

static プロパティを示します。 PHP 7.4.0 より前のバージョンでは、この値は 1 でした。

ReflectionProperty::IS_READONLY

readonly プロパティを示します。 PHP 8.1.0 以降で利用可能です。

ReflectionProperty::IS_PUBLIC

public プロパティを示します。 PHP 7.4.0 より前のバージョンでは、この値は 256 でした。

ReflectionProperty::IS_PROTECTED

protected プロパティを示します。 PHP 7.4.0 より前のバージョンでは、この値は 512 でした。

ReflectionProperty::IS_PRIVATE

private プロパティを示します。 PHP 7.4.0 より前のバージョンでは、この値は 1024 でした。

注意:

これらの定数の値は、PHP のバージョンが異なると変更される可能性があります。 これらの値を直接用いず、常に定数を使うことを推奨します。

変更履歴

バージョン | 説明
8.0.0 | ReflectionProperty::export() は、削除されました。

目次

  • ReflectionProperty::__clone — クローンする
  • ReflectionProperty::__construct — ReflectionProperty オブジェクトを作成する
  • ReflectionProperty::export — エクスポートする
  • ReflectionProperty::getAttributes — アトリビュートを取得する
  • ReflectionProperty::getDeclaringClass — 宣言しているクラスを取得する
  • ReflectionProperty::getDefaultValue — プロパティで宣言されたデフォルト値を返す
  • ReflectionProperty::getDocComment — プロパティのドキュメントコメントを取得する
  • ReflectionProperty::getModifiers — プロパティの修飾子を取得する
  • ReflectionProperty::getName — プロパティ名を取得する
  • ReflectionProperty::getType — プロパティの型を取得する
  • ReflectionProperty::getValue — 値を取得する
  • ReflectionProperty::hasDefaultValue — デフォルト値が宣言されているかをチェックする
  • ReflectionProperty::hasType — プロパティが型を持つかをチェックする
  • ReflectionProperty::isDefault — デフォルトプロパティであるかどうかを調べる
  • ReflectionProperty::isInitialized — プロパティが初期化されているかをチェックする
  • ReflectionProperty::isPrivate — private プロパティであるかどうかを調べる
  • ReflectionProperty::isPromoted — プロパティがコンストラクタの引数から昇格したものかを調べる
  • ReflectionProperty::isProtected — protected プロパティであるかどうかを調べる
  • ReflectionProperty::isPublic — public プロパティであるかどうかを調べる
  • ReflectionProperty::isReadOnly — プロパティが readonly かを調べる
  • ReflectionProperty::isStatic — staticプロパティであるかどうかを調べる
  • ReflectionProperty::setAccessible — プロパティのアクセス範囲を設定する
  • ReflectionProperty::setValue — プロパティの値を設定する
  • ReflectionProperty::__toString — 文字列に変換する


クローンする

  • ≪ ReflectionProperty
  • ReflectionProperty::__construct ≫
  • PHP Manual
  • ReflectionProperty
  • クローンする

ReflectionProperty::__clone

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::__clone — クローンする

説明

private ReflectionProperty::__clone(): void

クローンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

変更履歴

バージョン | 説明
8.1.0 | このメソッドは、final ではなくなりました。

参考

  • ReflectionProperty::export() - エクスポートする
  • オブジェクトのクローン作成


ReflectionProperty オブジェクトを作成する

  • ≪ ReflectionProperty::__clone
  • ReflectionProperty::export ≫
  • PHP Manual
  • ReflectionProperty
  • ReflectionProperty オブジェクトを作成する

ReflectionProperty::__construct

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::__construct — ReflectionProperty オブジェクトを作成する

説明

public ReflectionProperty::__construct(object|string $class, string $property)

パラメータ

class

リフレクションするクラス、またはオブジェクトの名前を含む文字列。

property

調べたいプロパティの名前。

エラー / 例外

private あるいは protected なプロパティの値を取得あるいは設定しようとすると、 例外がスローされます。

例

例1 ReflectionProperty::__construct() の例

<?php

class Str
{
public $length = 5;
}

// ReflectionProperty クラスのインスタンスを作成します
$prop = new ReflectionProperty('Str', 'length');

// 基本情報を表示します
printf(
"===> The%s%s%s%s property '%s' (which was %s)\n" .
" having the modifiers %s\n",
$prop->isPublic() ? ' public' : '',
$prop->isPrivate() ? ' private' : '',
$prop->isProtected() ? ' protected' : '',
$prop->isStatic() ? ' static' : '',
$prop->getName(),
$prop->isDefault() ? 'declared at compile-time' : 'created at run-time',
var_export(Reflection::getModifierNames($prop->getModifiers()), true)
);

// Str のインスタンスを作成します
$obj= new Str();

// 現在の値を取得します
printf("---> Value is: ");
var_dump($prop->getValue($obj));

// 値を変更します
$prop->setValue($obj, 10);
printf("---> Setting value to 10, new value is: ");
var_dump($prop->getValue($obj));

// オブジェクトを出力します
var_dump($obj);

?>

上の例の出力は、 たとえば以下のようになります。

===> The public property 'length' (which was declared at compile-time)
     having the modifiers array (
  0 => 'public',
)
---> Value is: int(5)
---> Setting value to 10, new value is: int(10)
object(Str)#2 (1) {
  ["length"]=>
  int(10)
}

例2 ReflectionProperty クラスを用いた、private および protected プロパティの値の取得

<?php

class Foo
{
public $x = 1;
protected $y = 2;
private $z = 3;
}

$obj = new Foo;

$prop = new ReflectionProperty('Foo', 'y');
$prop->setAccessible(true);
var_dump($prop->getValue($obj)); // int(2)

$prop = new ReflectionProperty('Foo', 'z');
$prop->setAccessible(true);
var_dump($prop->getValue($obj)); // int(2)

?>

上の例の出力は、 たとえば以下のようになります。

int(2)
int(3)

参考

  • ReflectionProperty::getName() - プロパティ名を取得する
  • コンストラクタ


エクスポートする

  • ≪ ReflectionProperty::__construct
  • ReflectionProperty::getAttributes ≫
  • PHP Manual
  • ReflectionProperty
  • エクスポートする

ReflectionProperty::export

(PHP 5, PHP 7)

ReflectionProperty::export — エクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static ReflectionProperty::export(mixed $class, string $name, bool $return = ?): string

エクスポートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

argument

エクスポートするリフレクション。

name

プロパティ名。

return

true に設定すると、エクスポートを発行するのではなく返します。 false (デフォルト) の場合はその逆です。

戻り値

参考

  • ReflectionProperty::__toString() - 文字列に変換する


アトリビュートを取得する

  • ≪ ReflectionProperty::export
  • ReflectionProperty::getDeclaringClass ≫
  • PHP Manual
  • ReflectionProperty
  • アトリビュートを取得する

ReflectionProperty::getAttributes

(PHP 8)

ReflectionProperty::getAttributes — アトリビュートを取得する

説明

public ReflectionProperty::getAttributes(?string $name = null, int $flags = 0): array

このクラスプロパティで宣言されている全てのアトリビュートを、 ReflectionAttribute の配列として返します。

パラメータ

name

指定したクラス名にマッチするアトリビュートの、 ReflectionAttribute のみを含むようにフィルタします。

flags

name が指定されていた場合に、 結果をどうフィルタするかを決めるフラグ。

デフォルトは 0 です。 この場合、アトリビュートのクラス名が name であるものだけを返します。

他の利用可能なオプションは、 ReflectionAttribute::IS_INSTANCEOF です。 この場合、フィルタリングに instanceof を使います。

戻り値

アトリビュートの配列を、 ReflectionAttribute オブジェクトの配列として返します。

例

例1 基本的な使い方

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

class Basket {
#[Fruit]
#[Red]
public string $apple = 'apple';
}

$property = new ReflectionProperty('Basket', 'apple');
$attributes = $property->getAttributes();
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
    [1] => Red
)

例2 クラス名で結果をフィルタする

<?php
#[Attribute]
class Fruit {
}

#[Attribute]
class Red {
}

class Basket {
#[Fruit]
#[Red]
public string $apple = 'apple';
}

$property = new ReflectionProperty('Basket', 'apple');
$attributes = $property->getAttributes('Fruit');
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Fruit
)

例3 クラス名、かつ継承も考慮して結果をフィルタする

<?php
interface Color {
}

#[Attribute]
class Fruit {
}

#[Attribute]
class Red implements Color {
}

class Basket {
#[Fruit]
#[Red]
public string $apple = 'apple';
}

$property = new ReflectionProperty('Basket', 'apple');
$attributes = $property->getAttributes('Color', ReflectionAttribute::IS_INSTANCEOF);
print_r(array_map(fn($attribute) => $attribute->getName(), $attributes));
?>

上の例の出力は以下となります。

Array
(
    [0] => Red
)

参考

  • ReflectionClass::getAttributes() - アトリビュートを取得する
  • ReflectionClassConstant::getAttributes() - アトリビュートを取得する
  • ReflectionFunctionAbstract::getAttributes() - アトリビュートを取得する
  • ReflectionParameter::getAttributes() - アトリビュートを取得する


宣言しているクラスを取得する

  • ≪ ReflectionProperty::getAttributes
  • ReflectionProperty::getDefaultValue ≫
  • PHP Manual
  • ReflectionProperty
  • 宣言しているクラスを取得する

ReflectionProperty::getDeclaringClass

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::getDeclaringClass — 宣言しているクラスを取得する

説明

public ReflectionProperty::getDeclaringClass(): ReflectionClass

宣言しているクラスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionClass オブジェクトを返します。

参考

  • ReflectionProperty::getName() - プロパティ名を取得する


プロパティで宣言されたデフォルト値を返す

  • ≪ ReflectionProperty::getDeclaringClass
  • ReflectionProperty::getDocComment ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティで宣言されたデフォルト値を返す

ReflectionProperty::getDefaultValue

(PHP 8)

ReflectionProperty::getDefaultValue — プロパティで宣言されたデフォルト値を返す

説明

public ReflectionProperty::getDefaultValue(): mixed

プロパティに明示または黙示的に宣言されているデフォルト値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティに何かしらデフォルト値が存在する場合(nullも含みます)、 それを返します。デフォルト値がない場合、null を返します。 デフォルト値が null の場合と、型付きプロパティが初期化されてない場合は区別できません。 それらを区別するには、ReflectionProperty::hasDefaultValue() を使って下さい。

例

例1 ReflectionProperty::getDefaultValue() の例

<?php
class Foo {
public $bar = 1;
public ?int $baz;
public int $boing = 0;
public function __construct(public string $bak = "default") { }
}

$ro = new ReflectionClass(Foo::class);
var_dump($ro->getProperty('bar')->getDefaultValue());
var_dump($ro->getProperty('baz')->getDefaultValue());
var_dump($ro->getProperty('boing')->getDefaultValue());
var_dump($ro->getProperty('bak')->getDefaultValue());
?>

上の例の出力は以下となります。

int(1)
NULL
int(0)
NULL

参考

  • ReflectionProperty::hasDefaultValue() - デフォルト値が宣言されているかをチェックする


プロパティのドキュメントコメントを取得する

  • ≪ ReflectionProperty::getDefaultValue
  • ReflectionProperty::getModifiers ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティのドキュメントコメントを取得する

ReflectionProperty::getDocComment

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ReflectionProperty::getDocComment — プロパティのドキュメントコメントを取得する

説明

public ReflectionProperty::getDocComment(): string|false

プロパティのドキュメントコメントを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティのドキュメントコメントを返します。 ドキュメントコメントが存在しない場合は、false を返します。

例

例1 ReflectionProperty::getDocComment() の例

<?php
class Str
{
/**
* @var int The length of the string
*/
public $length = 5;
}

$prop = new ReflectionProperty('Str', 'length');

var_dump($prop->getDocComment());

?>

上の例の出力は、 たとえば以下のようになります。

string(53) "/**
     * @var int  The length of the string
     */"

例2 複数のプロパティを宣言している場合

複数のプロパティの宣言が、 単一のドキュメントコメントの後に行われている場合、 ドキュメントコメントは最初のプロパティのみを参照します。

<?php
class Foo
{
/** @var string */
public $a, $b;
}
$class = new \ReflectionClass('Foo');
foreach ($class->getProperties() as $property) {
echo $property->getName() . ': ' . var_export($property->getDocComment(), true) . PHP_EOL;
}
?>

上の例の出力は以下となります。

a: '/** @var string */'
b: false

参考

  • ReflectionProperty::getModifiers() - プロパティの修飾子を取得する
  • ReflectionProperty::getName() - プロパティ名を取得する
  • ReflectionProperty::getValue() - 値を取得する


プロパティの修飾子を取得する

  • ≪ ReflectionProperty::getDocComment
  • ReflectionProperty::getName ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティの修飾子を取得する

ReflectionProperty::getModifiers

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::getModifiers — プロパティの修飾子を取得する

説明

public ReflectionProperty::getModifiers(): int

修飾子を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

修飾子の数値表現を返します。 これらの修飾子の実際の意味は、 定義済みの定数 で説明しています。

参考

  • ReflectionProperty::isPrivate() - private プロパティであるかどうかを調べる
  • Reflection::getModifierNames() - 修飾子の名前を取得する


プロパティ名を取得する

  • ≪ ReflectionProperty::getModifiers
  • ReflectionProperty::getType ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティ名を取得する

ReflectionProperty::getName

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::getName — プロパティ名を取得する

説明

public ReflectionProperty::getName(): string

プロパティ名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

調べているプロパティの名前を返します。

参考

  • ReflectionProperty::getValue() - 値を取得する


プロパティの型を取得する

  • ≪ ReflectionProperty::getName
  • ReflectionProperty::getValue ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティの型を取得する

ReflectionProperty::getType

(PHP 7 >= 7.4.0, PHP 8)

ReflectionProperty::getType — プロパティの型を取得する

説明

public ReflectionProperty::getType(): ?ReflectionType

プロパティに関連付けられた型を取得する

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティが型を持っていれば、ReflectionType を返します。そうでなければ、 null を返します。

例

例1 ReflectionProperty::getType() の例

<?php
class User
{
public string $name;
}

$rp = new ReflectionProperty('User', 'name');
echo $rp->getType()->getName();
?>

上の例の出力は以下となります。

string

参考

  • ReflectionProperty::hasType() - プロパティが型を持つかをチェックする
  • ReflectionProperty::isInitialized() - プロパティが初期化されているかをチェックする


値を取得する

  • ≪ ReflectionProperty::getType
  • ReflectionProperty::hasDefaultValue ≫
  • PHP Manual
  • ReflectionProperty
  • 値を取得する

ReflectionProperty::getValue

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::getValue — 値を取得する

説明

public ReflectionProperty::getValue(?object $object = null): mixed

プロパティの値を取得します。

パラメータ

object

static でないプロパティの場合は、プロパティを取得したいオブジェクトを指定しなければなりません。 オブジェクトを指定せずにデフォルトのプロパティを取得したい場合は、かわりに ReflectionClass::getDefaultProperties() を使います。

戻り値

プロパティの現在の値を返します。

変更履歴

バージョン | 説明
8.1.0 | private と protected なプロパティは ReflectionProperty::getValue() ですぐにアクセスできるようになりました。 これより前のバージョンでは、 ReflectionProperty::setAccessible() をコールすることでアクセスできるようにする必要がありました。 そうしない場合、 ReflectionException がスローされていました。
8.0.0 | object は、nullable になりました。

例

例1 ReflectionProperty::getValue() の例

<?php
class Foo {
public static $staticProperty = 'foobar';

public $property = 'barfoo';
protected $privateProperty = 'foofoo';
}

$reflectionClass = new ReflectionClass('Foo');

var_dump($reflectionClass->getProperty('staticProperty')->getValue());
var_dump($reflectionClass->getProperty('property')->getValue(new Foo));

$reflectionProperty = $reflectionClass->getProperty('privateProperty');
$reflectionProperty->setAccessible(true); // PHP 8.1.0 より前のバージョンのみ、この行の実行が必須でした
var_dump($reflectionProperty->getValue(new Foo));
?>

上の例の出力は以下となります。

string(6) "foobar"
string(6) "barfoo"
string(6) "foofoo"

参考

  • ReflectionProperty::setValue() - プロパティの値を設定する
  • ReflectionProperty::setAccessible() - プロパティのアクセス範囲を設定する
  • ReflectionClass::getDefaultProperties() - デフォルトプロパティを取得する
  • ReflectionClass::getStaticPropertyValue() - staticプロパティの値を取得する


デフォルト値が宣言されているかをチェックする

  • ≪ ReflectionProperty::getValue
  • ReflectionProperty::hasType ≫
  • PHP Manual
  • ReflectionProperty
  • デフォルト値が宣言されているかをチェックする

ReflectionProperty::hasDefaultValue

(PHP 8)

ReflectionProperty::hasDefaultValue — デフォルト値が宣言されているかをチェックする

説明

public ReflectionProperty::hasDefaultValue(): bool

プロパティにデフォルト値が宣言されているかをチェックします。 暗黙の null のデフォルト値も含めてチェックが行われます。 デフォルト値が存在しない型付きプロパティ(または動的なプロパティ)の場合は、false が返されます。

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティが何かしらデフォルト値を持っている場合(nullを含みます)、true を返します。 プロパティにデフォルト値が宣言されていないか、動的なプロパティの場合は、false を返します。

例

例1 ReflectionProperty::hasDefaultValue() の例

<?php
class Foo {
public $bar;
public ?int $baz;
public ?int $foo = null;
public int $boing;

public function __construct()
{
$this->ping = '';
}
}

$ro = new ReflectionObject(new Foo());
var_dump($ro->getProperty('bar')->hasDefaultValue());
var_dump($ro->getProperty('baz')->hasDefaultValue());
var_dump($ro->getProperty('foo')->hasDefaultValue());
var_dump($ro->getProperty('boing')->hasDefaultValue());
var_dump($ro->getProperty('ping')->hasDefaultValue()); // 動的なプロパティ
var_dump($ro->getProperty('pong')->hasDefaultValue()); // 未定義のプロパティ
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(true)
bool(false)
bool(false)

Fatal error: Uncaught ReflectionException: Property Foo::$pong does not exist in example.php

参考

  • ReflectionProperty::getDefaultValue() - プロパティで宣言されたデフォルト値を返す


プロパティが型を持つかをチェックする

  • ≪ ReflectionProperty::hasDefaultValue
  • ReflectionProperty::isDefault ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティが型を持つかをチェックする

ReflectionProperty::hasType

(PHP 7 >= 7.4.0, PHP 8)

ReflectionProperty::hasType — プロパティが型を持つかをチェックする

説明

public ReflectionProperty::hasType(): bool

プロパティが、自身に関連付けられた型を持つかをチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

型が指定されていれば true そうでなければ false

例

例1 ReflectionProperty::hasType() の例

<?php
class User
{
public string $name;
}

$rp = new ReflectionProperty('User', 'name');
var_dump($rp->hasType());
?>

上の例の出力は以下となります。

bool(true)

参考

  • ReflectionProperty::getType() - プロパティの型を取得する
  • ReflectionProperty::isInitialized() - プロパティが初期化されているかをチェックする


デフォルトプロパティであるかどうかを調べる

  • ≪ ReflectionProperty::hasType
  • ReflectionProperty::isInitialized ≫
  • PHP Manual
  • ReflectionProperty
  • デフォルトプロパティであるかどうかを調べる

ReflectionProperty::isDefault

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::isDefault — デフォルトプロパティであるかどうかを調べる

説明

public ReflectionProperty::isDefault(): bool

そのプロパティがコンパイル時に宣言されたものなのか、実行時に動的に宣言されたものなのかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティがコンパイル時に宣言された者である場合に true、 実行時に作られたものである場合に false を返します。

例

例1 ReflectionProperty::isDefault() の例

<?php
class Foo {
public $bar;
}

$o = new Foo();
$o->bar = 42;
$o->baz = 42;

$ro = new ReflectionObject($o);
var_dump($ro->getProperty('bar')->isDefault());
var_dump($ro->getProperty('baz')->isDefault());
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • ReflectionProperty::getValue() - 値を取得する


プロパティが初期化されているかをチェックする

  • ≪ ReflectionProperty::isDefault
  • ReflectionProperty::isPrivate ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティが初期化されているかをチェックする

ReflectionProperty::isInitialized

(PHP 7 >= 7.4.0, PHP 8)

ReflectionProperty::isInitialized — プロパティが初期化されているかをチェックする

説明

public ReflectionProperty::isInitialized(?object $object = null): bool

プロパティが初期化されているかをチェックします。

パラメータ

object

プロパティが static でない場合、プロパティを取得する対象のオブジェクトを与えなければなりません。

戻り値

型付きのプロパティが初期化される前か、明示的に unset() されたプロパティの場合は、 false を返します。 それ以外の全てのプロパティは、 true が返されます。

エラー / 例外

プロパティがアクセス不能な場合、 ReflectionException がスローされます。 ReflectionProperty::setAccessible() を使えば、protected や private なプロパティをアクセス可能にすることが出来ます。

変更履歴

バージョン | 説明
8.0.0 | object は、nullable になりました。

例

例1 ReflectionProperty::isInitialized() の例

<?php
class User
{
public string $name;
}

$rp = new ReflectionProperty('User', 'name');
$user = new User;
var_dump($rp->isInitialized($user));
$user->name = 'Nikita';
var_dump($rp->isInitialized($user));
?>

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionProperty::hasType() - プロパティが型を持つかをチェックする


private プロパティであるかどうかを調べる

  • ≪ ReflectionProperty::isInitialized
  • ReflectionProperty::isPromoted ≫
  • PHP Manual
  • ReflectionProperty
  • private プロパティであるかどうかを調べる

ReflectionProperty::isPrivate

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::isPrivate — private プロパティであるかどうかを調べる

説明

public ReflectionProperty::isPrivate(): bool

private プロパティであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

private プロパティである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionProperty::isPublic() - public プロパティであるかどうかを調べる
  • ReflectionProperty::isProtected() - protected プロパティであるかどうかを調べる
  • ReflectionProperty::isReadOnly() - プロパティが readonly かを調べる
  • ReflectionProperty::isStatic() - staticプロパティであるかどうかを調べる


プロパティがコンストラクタの引数から昇格したものかを調べる

  • ≪ ReflectionProperty::isPrivate
  • ReflectionProperty::isProtected ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティがコンストラクタの引数から昇格したものかを調べる

ReflectionProperty::isPromoted

(PHP 8)

ReflectionProperty::isPromoted — プロパティがコンストラクタの引数から昇格したものかを調べる

説明

public ReflectionProperty::isPromoted(): bool

プロパティが コンストラクタの引数から昇格 したものかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティがコンストラクタの引数から昇格したものなら true を返します。 そうでない場合は、false を返します。

例

例1 ReflectionProperty::isPromoted() の例

<?php
class Foo {
public $baz;

public function __construct(public $bar) {}
}

$o = new Foo(42);
$o->baz = 42;

$ro = new ReflectionObject($o);
var_dump($ro->getProperty('bar')->isPromoted());
var_dump($ro->getProperty('baz')->isPromoted());
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • ReflectionProperty::isDefault() - デフォルトプロパティであるかどうかを調べる
  • ReflectionProperty::isInitialized() - プロパティが初期化されているかをチェックする
  • ReflectionProperty::getValue() - 値を取得する


protected プロパティであるかどうかを調べる

  • ≪ ReflectionProperty::isPromoted
  • ReflectionProperty::isPublic ≫
  • PHP Manual
  • ReflectionProperty
  • protected プロパティであるかどうかを調べる

ReflectionProperty::isProtected

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::isProtected — protected プロパティであるかどうかを調べる

説明

public ReflectionProperty::isProtected(): bool

protected プロパティであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

protected プロパティである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionProperty::isPublic() - public プロパティであるかどうかを調べる
  • ReflectionProperty::isPrivate() - private プロパティであるかどうかを調べる
  • ReflectionProperty::isReadOnly() - プロパティが readonly かを調べる
  • ReflectionProperty::isStatic() - staticプロパティであるかどうかを調べる


public プロパティであるかどうかを調べる

  • ≪ ReflectionProperty::isProtected
  • ReflectionProperty::isReadOnly ≫
  • PHP Manual
  • ReflectionProperty
  • public プロパティであるかどうかを調べる

ReflectionProperty::isPublic

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::isPublic — public プロパティであるかどうかを調べる

説明

public ReflectionProperty::isPublic(): bool

public プロパティであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

public プロパティである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionProperty::isProtected() - protected プロパティであるかどうかを調べる
  • ReflectionProperty::isPrivate() - private プロパティであるかどうかを調べる
  • ReflectionProperty::isReadOnly() - プロパティが readonly かを調べる
  • ReflectionProperty::isStatic() - staticプロパティであるかどうかを調べる


プロパティが readonly かを調べる

  • ≪ ReflectionProperty::isPublic
  • ReflectionProperty::isStatic ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティが readonly かを調べる

ReflectionProperty::isReadOnly

(PHP 8 >= 8.1.0)

ReflectionProperty::isReadOnly — プロパティが readonly かを調べる

説明

public ReflectionProperty::isReadOnly(): bool

プロパティが readonly かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

プロパティが readonly の場合は true を返します。 そうでない場合、false を返します。

参考

  • ReflectionProperty::isPublic() - public プロパティであるかどうかを調べる
  • ReflectionProperty::isProtected() - protected プロパティであるかどうかを調べる
  • ReflectionProperty::isPrivate() - private プロパティであるかどうかを調べる
  • ReflectionProperty::isStatic() - staticプロパティであるかどうかを調べる


staticプロパティであるかどうかを調べる

  • ≪ ReflectionProperty::isReadOnly
  • ReflectionProperty::setAccessible ≫
  • PHP Manual
  • ReflectionProperty
  • staticプロパティであるかどうかを調べる

ReflectionProperty::isStatic

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::isStatic — staticプロパティであるかどうかを調べる

説明

public ReflectionProperty::isStatic(): bool

staticプロパティであるかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

staticプロパティである場合に true、それ以外の場合に false を返します。

参考

  • ReflectionProperty::isPublic() - public プロパティであるかどうかを調べる
  • ReflectionProperty::isProtected() - protected プロパティであるかどうかを調べる
  • ReflectionProperty::isPrivate() - private プロパティであるかどうかを調べる
  • ReflectionProperty::isReadOnly() - プロパティが readonly かを調べる


プロパティのアクセス範囲を設定する

  • ≪ ReflectionProperty::isStatic
  • ReflectionProperty::setValue ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティのアクセス範囲を設定する

ReflectionProperty::setAccessible

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

ReflectionProperty::setAccessible — プロパティのアクセス範囲を設定する

説明

public ReflectionProperty::setAccessible(bool $accessible): void

ReflectionProperty::getValue() や ReflectionProperty::setValue() メソッド経由で、 protected や private なプロパティにアクセス可能にします。

注意: PHP 8.1.0 以降は、このメソッドをコールしても何も起こりません。 つまり、全てのプロパティはデフォルトでアクセス可能です。

パラメータ

accessible

true を指定すると、アクセスできるようになります。

戻り値

値を返しません。

例

例1 簡単なクラス定義

<?php
class MyClass
{
private $foo = 'bar';
}

$property = new ReflectionProperty("MyClass", "foo");
$property->setAccessible(true);

$obj = new MyClass();
echo $property->getValue($obj);
echo $obj->foo;
?>

上の例の出力は、 たとえば以下のようになります。

bar
Fatal error: Uncaught Error: Cannot access private property MyClass::$foo in /in/WJqTv:12

参考

  • ReflectionProperty::isPrivate() - private プロパティであるかどうかを調べる
  • ReflectionProperty::isProtected() - protected プロパティであるかどうかを調べる


プロパティの値を設定する

  • ≪ ReflectionProperty::setAccessible
  • ReflectionProperty::__toString ≫
  • PHP Manual
  • ReflectionProperty
  • プロパティの値を設定する

ReflectionProperty::setValue

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::setValue — プロパティの値を設定する

説明

public ReflectionProperty::setValue(object $object, mixed $value): void
public ReflectionProperty::setValue(mixed $value): void

プロパティの値を設定 (変更) します。

注意: PHP 8.3.0 以降では、このメソッドにひとつだけ引数を渡してコールすることは、推奨されなくなりました。ReflectionClass::setStaticPropertyValue() を使いましょう。

パラメータ

object

static でないプロパティの場合は、プロパティを変更したいオブジェクトを指定しなければなりません。 staticプロパティ の場合、null を指定しなければ なりません。

value

新しい値。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.3.0 | このメソッドにひとつだけ引数を渡してコールすることは、推奨されなくなりました。static プロパティを変更する場合は、代わりに ReflectionClass::setStaticPropertyValue() を使ってください。
8.1.0 | private と protected なプロパティは ReflectionProperty::setValue() ですぐにアクセスできるようになりました。 これより前のバージョンでは、 ReflectionProperty::setAccessible() をコールすることでアクセスできるようにする必要がありました。 そうしない場合、 ReflectionException がスローされていました。

例

例1 ReflectionProperty::setValue() の例

<?php
class Foo {
public static $staticProperty;

public $property;
protected $privateProperty;
}

$reflectionClass = new ReflectionClass('Foo');

// PHP 8.3 以降では、static プロパティを設定する目的で setValue メソッドを使うべきではありません。代わりに、setStaticPropertyValue() を使いましょう。
$reflectionClass->setStaticPropertyValue('staticProperty', 'foo');
var_dump(Foo::$staticProperty);

$foo = new Foo;

$reflectionClass->getProperty('property')->setValue($foo, 'bar');
var_dump($foo->property);

$reflectionProperty = $reflectionClass->getProperty('privateProperty');
$reflectionProperty->setAccessible(true); // PHP 8.1.0 より前のバージョンのみ、この行の実行が必須でした
$reflectionProperty->setValue($foo, 'foobar');
var_dump($reflectionProperty->getValue($foo));
?>

上の例の出力は以下となります。

string(3) "foo"
string(3) "bar"
string(6) "foobar"

参考

  • ReflectionProperty::getValue() - 値を取得する
  • ReflectionProperty::setAccessible() - プロパティのアクセス範囲を設定する
  • ReflectionClass::setStaticPropertyValue() - staticプロパティの値を設定する


文字列に変換する

  • ≪ ReflectionProperty::setValue
  • ReflectionType ≫
  • PHP Manual
  • ReflectionProperty
  • 文字列に変換する

ReflectionProperty::__toString

(PHP 5, PHP 7, PHP 8)

ReflectionProperty::__toString — 文字列に変換する

説明

public ReflectionProperty::__toString(): string

プロパティを表現した文字列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

文字列を返します。

参考

  • __toString()


ReflectionType クラス

(PHP 7, PHP 8)

はじめに

ReflectionType クラスは、 関数の引数や戻り値の型、 またはクラスのプロパティの型に関する情報を報告します。 リフレクション拡張モジュールでは、以下のサブクラスが宣言されています。

  • ReflectionNamedType (PHP 7.1.0 以降)
  • ReflectionUnionType (PHP 8.0.0 以降)
  • ReflectionIntersectionType (PHP 8.1.0 以降)

クラス概要

abstract class ReflectionType implements Stringable {
/* メソッド */
public allowsNull(): bool
public __toString(): string
}

変更履歴

バージョン | 説明
8.0.0 | ReflectionType は、抽象クラスになり、 ReflectionType::isBuiltin() は、 ReflectionNamedType::isBuiltin() に移動しました。

目次

  • ReflectionType::allowsNull — null が許されるかをチェックする
  • ReflectionType::__toString — 文字列に変換する


null が許されるかをチェックする

  • ≪ ReflectionType
  • ReflectionType::__toString ≫
  • PHP Manual
  • ReflectionType
  • null が許されるかをチェックする

ReflectionType::allowsNull

(PHP 7, PHP 8)

ReflectionType::allowsNull — null が許されるかをチェックする

説明

public ReflectionType::allowsNull(): bool

引数が null を許容するかをチェックします。

パラメータ

この関数にはパラメータはありません。

戻り値

null が許容されるなら true を、そうでないなら false を返します。

例

例1 ReflectionType::allowsNull() の例

<?php
function someFunction(string $param, stdClass $param2 = null) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParams = $reflectionFunc->getParameters();

var_dump($reflectionParams[0]->getType()->allowsNull());
var_dump($reflectionParams[1]->getType()->allowsNull());

上の例の出力は以下となります。

bool(false)
bool(true)

参考

  • ReflectionNamedType::isBuiltin() - 組み込みの型であるかを調べる
  • ReflectionType::__toString() - 文字列に変換する
  • ReflectionParameter::getType() - 引数の型を取得する


文字列に変換する

  • ≪ ReflectionType::allowsNull
  • ReflectionUnionType ≫
  • PHP Manual
  • ReflectionType
  • 文字列に変換する

ReflectionType::__toString

(PHP 7, PHP 8)

ReflectionType::__toString — 文字列に変換する

説明

public ReflectionType::__toString(): string

引数の型の名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

引数の型を返します。

変更履歴

バージョン | 説明
8.0.0 | ReflectionType::__toString() は非推奨ではなくなりました。
7.1.0 | ReflectionType::__toString() は非推奨になりました。

例

例1 ReflectionType::__toString() の例

<?php
function someFunction(string $param) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParam = $reflectionFunc->getParameters()[0];

echo $reflectionParam->getType();

上の例の出力は、 たとえば以下のようになります。

string

参考

  • ReflectionNamedType::getName() - 型の名前の文字列を取得する
  • ReflectionNamedType::isBuiltin() - 組み込みの型であるかを調べる
  • ReflectionType::allowsNull() - null が許されるかをチェックする
  • ReflectionUnionType::getTypes() - union 型に含まれる型を返す。
  • ReflectionParameter::getType() - 引数の型を取得する


ReflectionUnionType クラス

(PHP 8)

はじめに

クラス概要

class ReflectionUnionType extends ReflectionType {
/* メソッド */
public getTypes(): array
/* 継承したメソッド */
public ReflectionType::allowsNull(): bool
public ReflectionType::__toString(): string
}

目次

  • ReflectionUnionType::getTypes — union 型に含まれる型を返す。


union 型に含まれる型を返す。

  • ≪ ReflectionUnionType
  • ReflectionGenerator ≫
  • PHP Manual
  • ReflectionUnionType
  • union 型に含まれる型を返す。

ReflectionUnionType::getTypes

(PHP 8)

ReflectionUnionType::getTypes — union 型に含まれる型を返す。

説明

public ReflectionUnionType::getTypes(): array

union 型に含まれるリフレクションの型を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionType オブジェクトの配列を返します。

例

例1 ReflectionUnionType::getTypes() の例

<?php
function someFunction(int|float $number) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParam = $reflectionFunc->getParameters()[0];

var_dump($reflectionParam->getType()->getTypes());

上の例の出力は、 たとえば以下のようになります。

array(2) {
    [0] =>
    class ReflectionNamedType#4(0) {
    }
    [1] =>
    class ReflectionNamedType#5(0) {
    }
}

参考

  • ReflectionType::allowsNull() - null が許されるかをチェックする
  • ReflectionParameter::getType() - 引数の型を取得する


ReflectionGenerator クラス

(PHP 7, PHP 8)

はじめに

ReflectionGenerator クラスは、ジェネレータに関する情報を報告します。

クラス概要

final class ReflectionGenerator {
/* メソッド */
public __construct(Generator $generator)
public getExecutingFile(): string
public getExecutingGenerator(): Generator
public getExecutingLine(): int
public getFunction(): ReflectionFunctionAbstract
public getThis(): ?object
public getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT): array
}

変更履歴

バージョン | 説明
8.0.0 | このクラスは final として定義され、 継承できなくなりました。

目次

  • ReflectionGenerator::__construct — ReflectionGenerator オブジェクトを構築する
  • ReflectionGenerator::getExecutingFile — 現在実行中のジェネレータのファイル名を取得する
  • ReflectionGenerator::getExecutingGenerator — 実行中の Generator オブジェクトを取得する
  • ReflectionGenerator::getExecutingLine — 現在実行中のジェネレータの行を取得する
  • ReflectionGenerator::getFunction — ジェネレータの関数名を取得する
  • ReflectionGenerator::getThis — ジェネレータの $this の値を取得する
  • ReflectionGenerator::getTrace — 実行中のジェネレータのトレースを取得する


ReflectionGenerator オブジェクトを構築する

  • ≪ ReflectionGenerator
  • ReflectionGenerator::getExecutingFile ≫
  • PHP Manual
  • ReflectionGenerator
  • ReflectionGenerator オブジェクトを構築する

ReflectionGenerator::__construct

(PHP 7, PHP 8)

ReflectionGenerator::__construct — ReflectionGenerator オブジェクトを構築する

説明

public ReflectionGenerator::__construct(Generator $generator)

ReflectionGenerator オブジェクトを構築します。

パラメータ

generator

ジェネレータオブジェクト

例

例1 ReflectionGenerator::__construct() の例

<?php

function gen()
{
yield 1;
}

$gen = gen();

$reflectionGen = new ReflectionGenerator($gen);

echo <<< output
{$reflectionGen->getFunction()->name}
Line: {$reflectionGen->getExecutingLine()}
File: {$reflectionGen->getExecutingFile()}
output;

上の例の出力は、 たとえば以下のようになります。

gen
Line: 5
File: /path/to/file/example.php

参考

  • ReflectionGenerator::getFunction() - ジェネレータの関数名を取得する
  • ReflectionGenerator::getExecutingLine() - 現在実行中のジェネレータの行を取得する
  • ReflectionGenerator::getExecutingFile() - 現在実行中のジェネレータのファイル名を取得する


現在実行中のジェネレータのファイル名を取得する

  • ≪ ReflectionGenerator::__construct
  • ReflectionGenerator::getExecutingGenerator ≫
  • PHP Manual
  • ReflectionGenerator
  • 現在実行中のジェネレータのファイル名を取得する

ReflectionGenerator::getExecutingFile

(PHP 7, PHP 8)

ReflectionGenerator::getExecutingFile — 現在実行中のジェネレータのファイル名を取得する

説明

public ReflectionGenerator::getExecutingFile(): string

現在実行中のジェネレータのファイル名をフルパスで取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在実行中のジェネレータのファイル名をフルパスを返します。

例

例1 ReflectionGenerator::getExecutingFile() の例

<?php

class GenExample
{
public function gen()
{
yield 1;
}
}

$gen = (new GenExample)->gen();

$reflectionGen = new ReflectionGenerator($gen);

echo "File: {$reflectionGen->getExecutingFile()}";

上の例の出力は、 たとえば以下のようになります。

File: /path/to/file/example.php

参考

  • ReflectionGenerator::getExecutingLine() - 現在実行中のジェネレータの行を取得する
  • ReflectionGenerator::getExecutingGenerator() - 実行中の Generator オブジェクトを取得する


実行中の Generator オブジェクトを取得する

  • ≪ ReflectionGenerator::getExecutingFile
  • ReflectionGenerator::getExecutingLine ≫
  • PHP Manual
  • ReflectionGenerator
  • 実行中の Generator オブジェクトを取得する

ReflectionGenerator::getExecutingGenerator

(PHP 7, PHP 8)

ReflectionGenerator::getExecutingGenerator — 実行中の Generator オブジェクトを取得する

説明

public ReflectionGenerator::getExecutingGenerator(): Generator

実行中の Generator オブジェクトを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在実行中の Generator オブジェクトを返します。

例

例1 ReflectionGenerator::getExecutingGenerator() の例

<?php

class GenExample
{
public function gen()
{
yield 1;
}
}

$gen = (new GenExample)->gen();

$reflectionGen = new ReflectionGenerator($gen);

$gen2 = $reflectionGen->getExecutingGenerator();

var_dump($gen2 === $gen);
var_dump($gen2->current());

上の例の出力は、 たとえば以下のようになります。

bool(true)
int(1);

参考

  • ReflectionGenerator::getExecutingLine() - 現在実行中のジェネレータの行を取得する
  • ReflectionGenerator::getExecutingFile() - 現在実行中のジェネレータのファイル名を取得する


現在実行中のジェネレータの行を取得する

  • ≪ ReflectionGenerator::getExecutingGenerator
  • ReflectionGenerator::getFunction ≫
  • PHP Manual
  • ReflectionGenerator
  • 現在実行中のジェネレータの行を取得する

ReflectionGenerator::getExecutingLine

(PHP 7, PHP 8)

ReflectionGenerator::getExecutingLine — 現在実行中のジェネレータの行を取得する

説明

public ReflectionGenerator::getExecutingLine(): int

現在実行中のジェネレータの行を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在実行中のジェネレータの式の行番号を返します。

例

例1 ReflectionGenerator::getExecutingLine() の例

<?php

class GenExample
{
public function gen()
{
yield 1;
}
}

$gen = (new GenExample)->gen();

$reflectionGen = new ReflectionGenerator($gen);

echo "Line: {$reflectionGen->getExecutingLine()}";

上の例の出力は、 たとえば以下のようになります。

Line: 7

参考

  • ReflectionGenerator::getExecutingGenerator() - 実行中の Generator オブジェクトを取得する
  • ReflectionGenerator::getExecutingFile() - 現在実行中のジェネレータのファイル名を取得する


ジェネレータの関数名を取得する

  • ≪ ReflectionGenerator::getExecutingLine
  • ReflectionGenerator::getThis ≫
  • PHP Manual
  • ReflectionGenerator
  • ジェネレータの関数名を取得する

ReflectionGenerator::getFunction

(PHP 7, PHP 8)

ReflectionGenerator::getFunction — ジェネレータの関数名を取得する

説明

public ReflectionGenerator::getFunction(): ReflectionFunctionAbstract

ReflectionFunctionAbstract から派生したクラスを返すことによって、 取得したジェネレータの関数名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionFunctionAbstract クラスを返します。 これは 関数の場合は ReflectionFunction ですし、 メソッドの場合は ReflectionMethod になります。

例

例1 ReflectionGenerator::getFunction() の例

<?php

function gen()
{
yield 1;
}

$gen = gen();

$reflectionGen = new ReflectionGenerator($gen);

var_dump($reflectionGen->getFunction());

上の例の出力は、 たとえば以下のようになります。

object(ReflectionFunction)#3 (1) {
  ["name"]=>
  string(3) "gen"
}

参考

  • ReflectionGenerator::getThis() - ジェネレータの $this の値を取得する
  • ReflectionGenerator::getTrace() - 実行中のジェネレータのトレースを取得する


ジェネレータの $this の値を取得する

  • ≪ ReflectionGenerator::getFunction
  • ReflectionGenerator::getTrace ≫
  • PHP Manual
  • ReflectionGenerator
  • ジェネレータの $this の値を取得する

ReflectionGenerator::getThis

(PHP 7, PHP 8)

ReflectionGenerator::getThis — ジェネレータの $this の値を取得する

説明

public ReflectionGenerator::getThis(): ?object

ジェネレータがアクセスできる $this の値を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

$this の値を返します。 ジェネレータがクラスコンテキストの中で作られていない場合は null を返します。

例

例1 ReflectionGenerator::getThis() の例

<?php

class GenExample
{
public function gen()
{
yield 1;
}
}

$gen = (new GenExample)->gen();

$reflectionGen = new ReflectionGenerator($gen);

var_dump($reflectionGen->getThis());

上の例の出力は、 たとえば以下のようになります。

object(GenExample)#3 (0) {
}

参考

  • ReflectionGenerator::getFunction() - ジェネレータの関数名を取得する
  • ReflectionGenerator::getTrace() - 実行中のジェネレータのトレースを取得する


実行中のジェネレータのトレースを取得する

  • ≪ ReflectionGenerator::getThis
  • ReflectionFiber ≫
  • PHP Manual
  • ReflectionGenerator
  • 実行中のジェネレータのトレースを取得する

ReflectionGenerator::getTrace

(PHP 7, PHP 8)

ReflectionGenerator::getTrace — 実行中のジェネレータのトレースを取得する

説明

public ReflectionGenerator::getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT): array

現在実行中のジェネレータのトレースを取得します。

パラメータ

options

options の値は以下のフラグのうちのいずれかです:

利用可能なオプション
オプション | 説明
DEBUG_BACKTRACE_PROVIDE_OBJECT | デフォルト
DEBUG_BACKTRACE_IGNORE_ARGS | スタックトレース内の関数に引数の情報を含めない

戻り値

現在実行中のジェネレータのトレースを返します。

例

例1 ReflectionGenerator::getTrace() の例

<?php
function foo() {
yield 1;
}

function bar()
{
yield from foo();
}

function baz()
{
yield from bar();
}

$gen = baz();
$gen->valid(); // ジェネレータを開始

var_dump((new ReflectionGenerator($gen))->getTrace());

上の例の出力は、 たとえば以下のようになります。

array(2) {
  [0]=>
  array(4) {
    ["file"]=>
    string(18) "example.php"
    ["line"]=>
    int(8)
    ["function"]=>
    string(3) "foo"
    ["args"]=>
    array(0) {
    }
  }
  [1]=>
  array(4) {
    ["file"]=>
    string(18) "example.php"
    ["line"]=>
    int(12)
    ["function"]=>
    string(3) "bar"
    ["args"]=>
    array(0) {
    }
  }
}

参考

  • ReflectionGenerator::getFunction() - ジェネレータの関数名を取得する
  • ReflectionGenerator::getThis() - ジェネレータの $this の値を取得する


ReflectionFiber クラス

(PHP 8 >= 8.1.0)

はじめに

クラス概要

final class ReflectionFiber {
/* メソッド */
public __construct(Fiber $fiber)
public getCallable(): callable
public getExecutingFile(): ?string
public getExecutingLine(): ?int
public getFiber(): Fiber
public getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT): array
}

目次

  • ReflectionFiber::__construct — Constructs a ReflectionFiber オブジェクトを構築する
  • ReflectionFiber::getCallable — Fiber の構築に使われた callable を取得する
  • ReflectionFiber::getExecutingFile — 現在実行中のファイル名を取得する
  • ReflectionFiber::getExecutingLine — 現在実行中の行番号を取得する
  • ReflectionFiber::getFiber — リフレクションされた Fiber クラスのインスタンスを取得する
  • ReflectionFiber::getTrace — 現在実行している時点のバックトレースを取得する


Constructs a ReflectionFiber オブジェクトを構築する

  • ≪ ReflectionFiber
  • ReflectionFiber::getCallable ≫
  • PHP Manual
  • ReflectionFiber
  • Constructs a ReflectionFiber オブジェクトを構築する

ReflectionFiber::__construct

(PHP 8 >= 8.1.0)

ReflectionFiber::__construct — Constructs a ReflectionFiber オブジェクトを構築する

説明

public ReflectionFiber::__construct(Fiber $fiber)

ReflectionFiber オブジェクトを構築します。

パラメータ

fiber

リフレクションする Fiber オブジェクト。


Fiber の構築に使われた callable を取得する

  • ≪ ReflectionFiber::__construct
  • ReflectionFiber::getExecutingFile ≫
  • PHP Manual
  • ReflectionFiber
  • Fiber の構築に使われた callable を取得する

ReflectionFiber::getCallable

(PHP 8 >= 8.1.0)

ReflectionFiber::getCallable — Fiber の構築に使われた callable を取得する

説明

public ReflectionFiber::getCallable(): callable

Fiber の構築に使われた callable を返します。 Fiber が既に終了している場合、 Error がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

Fiber の構築に使われた callable を返します。


現在実行中のファイル名を取得する

  • ≪ ReflectionFiber::getCallable
  • ReflectionFiber::getExecutingLine ≫
  • PHP Manual
  • ReflectionFiber
  • 現在実行中のファイル名を取得する

ReflectionFiber::getExecutingFile

(PHP 8 >= 8.1.0)

ReflectionFiber::getExecutingFile — 現在実行中のファイル名を取得する

説明

public ReflectionFiber::getExecutingFile(): ?string

リフレクションされた Fiber が実行しているファイル名のフルパスを返します。 Fiber が開始していないか、既に終了している場合、 Error がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

リフレクションされた Fiber が実行しているファイル名のフルパスを返します。 リフレクションされた Fiber がユーザー定義関数の外側で使われている場合、 null を返します。


現在実行中の行番号を取得する

  • ≪ ReflectionFiber::getExecutingFile
  • ReflectionFiber::getFiber ≫
  • PHP Manual
  • ReflectionFiber
  • 現在実行中の行番号を取得する

ReflectionFiber::getExecutingLine

(PHP 8 >= 8.1.0)

ReflectionFiber::getExecutingLine — 現在実行中の行番号を取得する

説明

public ReflectionFiber::getExecutingLine(): ?int

リフレクションされた Fiber が現在実行している行番号を返します。 Fiber が開始していないか、既に終了している場合、 Error がスローされます。

パラメータ

この関数にはパラメータはありません。

戻り値

Fiber が現在実行している行番号を返します。 リフレクションされた Fiber が現在実行している行番号を返します。 リフレクションされた fiber がユーザー定義関数の外側で実行されている場合、 fiber がまだ開始していないか、既に終了している場合、 Error がスローされます。


リフレクションされた Fiber クラスのインスタンスを取得する

  • ≪ ReflectionFiber::getExecutingLine
  • ReflectionFiber::getTrace ≫
  • PHP Manual
  • ReflectionFiber
  • リフレクションされた Fiber クラスのインスタンスを取得する

ReflectionFiber::getFiber

(PHP 8 >= 8.1.0)

ReflectionFiber::getFiber — リフレクションされた Fiber クラスのインスタンスを取得する

説明

public ReflectionFiber::getFiber(): Fiber

リフレクションされた Fiber クラスのインスタンスを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

リフレクションされた Fiber クラスのインスタンスを返します。


現在実行している時点のバックトレースを取得する

  • ≪ ReflectionFiber::getFiber
  • ReflectionIntersectionType ≫
  • PHP Manual
  • ReflectionFiber
  • 現在実行している時点のバックトレースを取得する

ReflectionFiber::getTrace

(PHP 8 >= 8.1.0)

ReflectionFiber::getTrace — 現在実行している時点のバックトレースを取得する

説明

public ReflectionFiber::getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT): array

リフレクションされた Fiber で、 現在実行している時点のバックトレースを取得します。

パラメータ

options

options の値には、以下のフラグが指定できます。

利用可能なオプション
オプション | 説明
DEBUG_BACKTRACE_PROVIDE_OBJECT | これがデフォルトの値です。
DEBUG_BACKTRACE_IGNORE_ARGS | スタックトレースに、関数の引数に関する情報を含めない。

戻り値

Fiber で、現在実行している時点のバックトレースを返します。


ReflectionIntersectionType クラス

(PHP 8 >= 8.1.0)

はじめに

クラス概要

class ReflectionIntersectionType extends ReflectionType {
/* メソッド */
public getTypes(): array
/* 継承したメソッド */
public ReflectionType::allowsNull(): bool
public ReflectionType::__toString(): string
}

目次

  • ReflectionIntersectionType::getTypes — 交差型に含まれている型を返す


交差型に含まれている型を返す

  • ≪ ReflectionIntersectionType
  • ReflectionReference ≫
  • PHP Manual
  • ReflectionIntersectionType
  • 交差型に含まれている型を返す

ReflectionIntersectionType::getTypes

(PHP 8 >= 8.1.0)

ReflectionIntersectionType::getTypes — 交差型に含まれている型を返す

説明

public ReflectionIntersectionType::getTypes(): array

交差型に含まれている型を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ReflectionType オブジェクトの配列を返します。

例

例1 ReflectionIntersectionType::getTypes() の例

<?php

function someFunction(Iterator&Countable $value) {}

$reflectionFunc = new ReflectionFunction('someFunction');
$reflectionParam = $reflectionFunc->getParameters()[0];

var_dump($reflectionParam->getType()->getTypes());
?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
    [0] =>
    class ReflectionNamedType#4(0) {
    }
    [1] =>
    class ReflectionNamedType#5(0) {
    }
}

参考

  • ReflectionType::allowsNull() - null が許されるかをチェックする
  • ReflectionParameter::getType() - 引数の型を取得する


ReflectionReference クラス

(PHP 7 >= 7.4.0, PHP 8)

はじめに

ReflectionReference クラスは、リファレンスに関する情報を提供します。

クラス概要

final class ReflectionReference {
/* メソッド */
private __construct()
public static fromArrayElement(array $array, int|string $key): ?ReflectionReference
public getId(): string
}

目次

  • ReflectionReference::__construct — private なコンストラクタのため、直接インスタンス化できません
  • ReflectionReference::fromArrayElement — 配列の要素から、ReflectionReference を生成する
  • ReflectionReference::getId — リファレンスのユニークなIDを取得する


private なコンストラクタのため、直接インスタンス化できません

  • ≪ ReflectionReference
  • ReflectionReference::fromArrayElement ≫
  • PHP Manual
  • ReflectionReference
  • private なコンストラクタのため、直接インスタンス化できません

ReflectionReference::__construct

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

ReflectionReference::__construct — private なコンストラクタのため、直接インスタンス化できません

説明

private ReflectionReference::__construct()

パラメータ

この関数にはパラメータはありません。


配列の要素から、ReflectionReference を生成する

  • ≪ ReflectionReference::__construct
  • ReflectionReference::getId ≫
  • PHP Manual
  • ReflectionReference
  • 配列の要素から、ReflectionReference を生成する

ReflectionReference::fromArrayElement

(PHP 7 >= 7.4.0, PHP 8)

ReflectionReference::fromArrayElement — 配列の要素から、ReflectionReference を生成する

説明

public static ReflectionReference::fromArrayElement(array $array, int|string $key): ?ReflectionReference

配列の要素から、ReflectionReference を生成します。

パラメータ

array

リファレンスの情報が含まれる array。

key

キー。int または string。

戻り値

$array[$key] がリファレンスの場合、 ReflectionReference のインスタンスを返します。 そうでない場合、null を返します。

エラー / 例外

array が array でない場合、 または key が int でも string でもない場合、 TypeError がスローされます。 $array[$key] が存在しない場合、 ReflectionException がスローされます。


リファレンスのユニークなIDを取得する

  • ≪ ReflectionReference::fromArrayElement
  • ReflectionAttribute ≫
  • PHP Manual
  • ReflectionReference
  • リファレンスのユニークなIDを取得する

ReflectionReference::getId

(PHP 7 >= 7.4.0, PHP 8)

ReflectionReference::getId — リファレンスのユニークなIDを取得する

説明

public ReflectionReference::getId(): string

リファレンスが生きている間、リファレンス単位でユニークなIDを返します。 このIDは同じリファレンスであるかを比較するのに使えますし、 既知のリファレンスのマッピングを管理するのにも使えます。

パラメータ

この関数にはパラメータはありません。

戻り値

文字列を返します。フォーマットは決まっていません。

例

例1 ReflectionReference::getId() の基本的な使い方

<?php
$val1 = 'foo';
$val2 = 'bar';
$arr = [&$val1, &$val2, &$val1];

$rr1 = ReflectionReference::fromArrayElement($arr, 0);
$rr2 = ReflectionReference::fromArrayElement($arr, 1);
$rr3 = ReflectionReference::fromArrayElement($arr, 2);

var_dump($rr1->getId() === $rr2->getId());
var_dump($rr1->getId() === $rr3->getId());
?>

上の例の出力は以下となります。

bool(false)
bool(true)


ReflectionAttribute クラス

(PHP 8)

はじめに

ReflectionAttribute クラスは、 アトリビュート に関する情報を提供します。

クラス概要

class ReflectionAttribute implements Reflector {
/* 定数 */
public const int IS_INSTANCEOF;
/* メソッド */
private __construct()
public getArguments(): array
public getName(): string
public getTarget(): int
public isRepeated(): bool
public newInstance(): object
}

定義済み定数

ReflectionAttribute のフラグ

ReflectionAttribute::IS_INSTANCEOF

instanceof のチェックを使い、 アトリビュートを取得します。

注意:

これらの定数の値は、 PHP のバージョンによっては変更される可能性があります。 値そのものに依存せず、定数を使うことを推奨します。

目次

  • ReflectionAttribute::__construct — private なコンストラクタのため、直接インスタンス化できません
  • ReflectionAttribute::getArguments — アトリビュートに渡された引数を取得する
  • ReflectionAttribute::getName — アトリビュートの名前を取得する
  • ReflectionAttribute::getTarget — アトリビュートのターゲットをビットマスクとして返す
  • ReflectionAttribute::isRepeated — この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得する
  • ReflectionAttribute::newInstance — アトリビュートクラスをインスタンス化する


private なコンストラクタのため、直接インスタンス化できません

  • ≪ ReflectionAttribute
  • ReflectionAttribute::getArguments ≫
  • PHP Manual
  • ReflectionAttribute
  • private なコンストラクタのため、直接インスタンス化できません

ReflectionAttribute::__construct

(PHP 8)

ReflectionAttribute::__construct — private なコンストラクタのため、直接インスタンス化できません

説明

private ReflectionAttribute::__construct()

パラメータ

この関数にはパラメータはありません。


アトリビュートに渡された引数を取得する

  • ≪ ReflectionAttribute::__construct
  • ReflectionAttribute::getName ≫
  • PHP Manual
  • ReflectionAttribute
  • アトリビュートに渡された引数を取得する

ReflectionAttribute::getArguments

(PHP 8)

ReflectionAttribute::getArguments — アトリビュートに渡された引数を取得する

説明

public ReflectionAttribute::getArguments(): array

アトリビュートに渡された引数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

アトリビュートに渡された引数を返します。


アトリビュートの名前を取得する

  • ≪ ReflectionAttribute::getArguments
  • ReflectionAttribute::getTarget ≫
  • PHP Manual
  • ReflectionAttribute
  • アトリビュートの名前を取得する

ReflectionAttribute::getName

(PHP 8)

ReflectionAttribute::getName — アトリビュートの名前を取得する

説明

public ReflectionAttribute::getName(): string

アトリビュートの名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

アトリビュートの名前を返します。


アトリビュートのターゲットをビットマスクとして返す

  • ≪ ReflectionAttribute::getName
  • ReflectionAttribute::isRepeated ≫
  • PHP Manual
  • ReflectionAttribute
  • アトリビュートのターゲットをビットマスクとして返す

ReflectionAttribute::getTarget

(PHP 8)

ReflectionAttribute::getTarget — アトリビュートのターゲットをビットマスクとして返す

説明

public ReflectionAttribute::getTarget(): int

アトリビュートのターゲットをビットマスクとして取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

アトリビュートのターゲットをビットマスクとして返します。


この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得する

  • ≪ ReflectionAttribute::getTarget
  • ReflectionAttribute::newInstance ≫
  • PHP Manual
  • ReflectionAttribute
  • この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得する

ReflectionAttribute::isRepeated

(PHP 8)

ReflectionAttribute::isRepeated — この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得する

説明

public ReflectionAttribute::isRepeated(): bool

この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

アトリビュートが繰り返し使われている場合は true を返します。 そうでない場合は、false を返します。


アトリビュートクラスをインスタンス化する

  • ≪ ReflectionAttribute::isRepeated
  • Reflector ≫
  • PHP Manual
  • ReflectionAttribute
  • アトリビュートクラスをインスタンス化する

ReflectionAttribute::newInstance

(PHP 8)

ReflectionAttribute::newInstance — アトリビュートクラスをインスタンス化する

説明

public ReflectionAttribute::newInstance(): object

この ReflectionAttribute クラスと引数を表現する、 アトリビュートクラスをインスタンス化します。

パラメータ

この関数にはパラメータはありません。

戻り値

アトリビュートの新しいインスタンスを返します。


Reflector インターフェイス

(PHP 5, PHP 7, PHP 8)

はじめに

Reflector は、 すべてのエクスポート可能なリフレクションクラスが実装しているインターフェイスです。

インターフェイス概要

interface Reflector extends Stringable {
/* 継承したメソッド */
public Stringable::__toString(): string
}

変更履歴

バージョン | 説明
8.0.0 | Reflector::export() は、削除されました。
8.0.0 | Reflector は、 Stringable を継承するようになりました。 これによって Reflector::__toString() を置き換える形で、 Stringable::__toString() が継承されるようになりました。

参考

  • Reflector::export()

目次

  • Reflector::export — エクスポートする


エクスポートする

  • ≪ Reflector
  • ReflectionException ≫
  • PHP Manual
  • Reflector
  • エクスポートする

Reflector::export

(PHP 5, PHP 7)

Reflector::export — エクスポートする

警告

この関数は PHP 7.4.0 で 非推奨 になり、PHP 8.0.0 で 削除 されました。この関数に頼らないことを強く推奨します。

説明

public static Reflector::export(): string

エクスポートします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

参考

  • Reflection::__toString()


ReflectionException クラス

(PHP 5, PHP 7, PHP 8)

はじめに

ReflectionException クラスです。

クラス概要

class ReflectionException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


変数操作

  • はじめに
  • インストール/設定
    • 実行時設定
  • 変数操作 関数
    • boolval — 変数の boolean としての値を取得する
    • debug_zval_dump — 内部的な zval を表す文字列をダンプする
    • doubleval — floatval のエイリアス
    • empty — 変数が空であるかどうかを検査する
    • floatval — 変数の float 値を取得する
    • get_debug_type — 変数の型名をデバッグしやすい形で取得する
    • get_defined_vars — 全ての定義済の変数を配列で返す
    • get_resource_id — 指定されたリソースの、数値の識別子を返す
    • get_resource_type — リソース型を返す
    • gettype — 変数の型を取得する
    • intval — 変数の整数としての値を取得する
    • is_array — 変数が配列かどうかを検査する
    • is_bool — 変数が boolean であるかを調べる
    • is_callable — 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
    • is_countable — 引数が、数えられる値かどうかを調べる
    • is_double — is_float のエイリアス
    • is_float — 変数の型が float かどうか調べる
    • is_int — 変数が整数型かどうかを検査する
    • is_integer — is_int のエイリアス
    • is_iterable — 変数の内容が反復可能な値であることを確認する
    • is_long — is_int のエイリアス
    • is_null — 変数が null かどうか調べる
    • is_numeric — 変数が数字または数値形式の文字列であるかを調べる
    • is_object — 変数がオブジェクトかどうかを検査する
    • is_real — is_float のエイリアス
    • is_resource — 変数がリソースかどうかを調べる
    • is_scalar — 変数がスカラかどうかを調べる
    • is_string — 変数の型が文字列かどうかを調べる
    • isset — 変数が宣言されていること、そして null とは異なることを検査する
    • print_r — 指定した変数に関する情報を解りやすく出力する
    • serialize — 値の保存可能な表現を生成する
    • settype — 変数の型をセットする
    • strval — 変数の文字列としての値を取得する
    • unserialize — 保存用表現から PHP の値を生成する
    • unset — 指定した変数の割当を解除する
    • var_dump — 変数に関する情報をダンプする
    • var_export — 変数の文字列表現を出力または返す


はじめに

変数の動作に関する情報については、このマニュアルの 言語リファレンスセクションにある 変数のエントリを参照ください。


  • ≪ はじめに
  • 実行時設定 ≫
  • PHP Manual
  • 変数操作
  • インストール/設定

インストール/設定

目次

  • 実行時設定


実行時設定

php.ini の設定により動作が変化します。

変数設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
unserialize_callback_func | null | INI_ALL |
unserialize_max_depth | "4096" | INI_ALL | PHP 7.4.0 以降で利用可能。
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

unserialize_callback_func string

unserialize() が未定義のクラスを使おうとしたときに、ここで指定したコールバックをコールします。 指定したコールバック関数が定義されていない場合や そのコールバック関数が未定義のクラスの定義に失敗したときに警告が発生します。

unserialize() および クラスのオートローディング も参照ください。

unserialize_max_depth int

unserialize() を使ったアンシリアライズ処理の間に許される、 データ構造の再帰の深さの最大値を設定します。 これは、スタックオーバーフローを防ぐためのものです。 unserialize_max_depth=0 に設定すると、 この設定を無効にすることができます。

unserialize() および クラスのオートローディング も参照ください。


変数操作 関数

目次

  • boolval — 変数の boolean としての値を取得する
  • debug_zval_dump — 内部的な zval を表す文字列をダンプする
  • doubleval — floatval のエイリアス
  • empty — 変数が空であるかどうかを検査する
  • floatval — 変数の float 値を取得する
  • get_debug_type — 変数の型名をデバッグしやすい形で取得する
  • get_defined_vars — 全ての定義済の変数を配列で返す
  • get_resource_id — 指定されたリソースの、数値の識別子を返す
  • get_resource_type — リソース型を返す
  • gettype — 変数の型を取得する
  • intval — 変数の整数としての値を取得する
  • is_array — 変数が配列かどうかを検査する
  • is_bool — 変数が boolean であるかを調べる
  • is_callable — 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
  • is_countable — 引数が、数えられる値かどうかを調べる
  • is_double — is_float のエイリアス
  • is_float — 変数の型が float かどうか調べる
  • is_int — 変数が整数型かどうかを検査する
  • is_integer — is_int のエイリアス
  • is_iterable — 変数の内容が反復可能な値であることを確認する
  • is_long — is_int のエイリアス
  • is_null — 変数が null かどうか調べる
  • is_numeric — 変数が数字または数値形式の文字列であるかを調べる
  • is_object — 変数がオブジェクトかどうかを検査する
  • is_real — is_float のエイリアス
  • is_resource — 変数がリソースかどうかを調べる
  • is_scalar — 変数がスカラかどうかを調べる
  • is_string — 変数の型が文字列かどうかを調べる
  • isset — 変数が宣言されていること、そして null とは異なることを検査する
  • print_r — 指定した変数に関する情報を解りやすく出力する
  • serialize — 値の保存可能な表現を生成する
  • settype — 変数の型をセットする
  • strval — 変数の文字列としての値を取得する
  • unserialize — 保存用表現から PHP の値を生成する
  • unset — 指定した変数の割当を解除する
  • var_dump — 変数に関する情報をダンプする
  • var_export — 変数の文字列表現を出力または返す


変数の boolean としての値を取得する

  • ≪ 変数操作 関数
  • debug_zval_dump ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の boolean としての値を取得する

boolval

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

boolval — 変数の boolean としての値を取得する

説明

boolval(mixed $value): bool

value の bool としての値を返します。

パラメータ

value

bool に変換したいスカラー値。

戻り値

value の bool としての値を返します。

例

例1 boolval() の例

<?php
echo '0: '.(boolval(0) ? 'true' : 'false')."\n";
echo '42: '.(boolval(42) ? 'true' : 'false')."\n";
echo '0.0: '.(boolval(0.0) ? 'true' : 'false')."\n";
echo '4.2: '.(boolval(4.2) ? 'true' : 'false')."\n";
echo '"": '.(boolval("") ? 'true' : 'false')."\n";
echo '"string": '.(boolval("string") ? 'true' : 'false')."\n";
echo '"0": '.(boolval("0") ? 'true' : 'false')."\n";
echo '"1": '.(boolval("1") ? 'true' : 'false')."\n";
echo '[1, 2]: '.(boolval([1, 2]) ? 'true' : 'false')."\n";
echo '[]: '.(boolval([]) ? 'true' : 'false')."\n";
echo 'stdClass: '.(boolval(new stdClass) ? 'true' : 'false')."\n";
?>

上の例の出力は以下となります。

0:        false
42:       true
0.0:      false
4.2:      true
"":       false
"string": true
"0":      false
"1":      true
[1, 2]:   true
[]:       false
stdClass: true

参考

  • floatval() - 変数の float 値を取得する
  • intval() - 変数の整数としての値を取得する
  • strval() - 変数の文字列としての値を取得する
  • settype() - 変数の型をセットする
  • is_bool() - 変数が boolean であるかを調べる
  • 型の相互変換


内部的な zval を表す文字列をダンプする

  • ≪ boolval
  • doubleval ≫
  • PHP Manual
  • 変数操作 関数
  • 内部的な zval を表す文字列をダンプする

debug_zval_dump

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

debug_zval_dump — 内部的な zval を表す文字列をダンプする

説明

debug_zval_dump(mixed $value, mixed ...$values): void

内部的な zval (Zend の値) を表す文字列表現をダンプします。 これは Zend Engine や PHP 拡張モジュールの実装の詳細をデバッグしたり、理解したりするのに役立ちます。

パラメータ

value

ダンプする変数または値。

values

ダンプする追加の変数または値。

戻り値

値を返しません。

例

例1 debug_zval_dump() の例

<?php
$var1 = 'Hello';
$var1 .= ' World';
$var2 = $var1;

debug_zval_dump($var1);
?>

上の例の出力は以下となります。

string(11) "Hello World" refcount(3)

注意: refcount を理解する

Zend Engine の実装の詳細を理解していないと、 この関数が表示する refcount の値に驚くかもしれません。

Zend Engine は、リファレンスカウントを以下の2つの用途で使います:

  • "コピーオンライト" と呼ばれるテクニックを使ってメモリを最適化し、 値が同じ複数の値を保持する複数の変数を、メモリ上の同じコピーを指すようにします。 この場合、変数の値が変更された時に、 その変数は新しいメモリ上のコピーの値を指すようになります。 そして、その変数のリファレンスカウントは1になります。
  • リファレンス渡しされたり、リファレンスが代入されている値( リファレンスの説明 も参照ください) を追跡する用途にも使います。 この用途のリファレンスカウントは、 現在の値を指しているものとは別の、リファレンス用の zval に保存されています。 この追加の zval は、現状 debug_zval_dump() では見えません。

debug_zval_dump() は、値渡しされた通常の引数を入力として受け取るので、 コピーオンライトのテクニックを使います: つまり、データをコピーせず、 関数呼び出しが行われている間、リファレンスカウントをひとつ増やします。 関数が受け取った引数を変更すると、データのコピーが行われます。 コピーを行わないと、呼び出しスコープの中でリファレンスカウントがひとつ増えてしまうからです。

渡す引数によっては、debug_zval_dump() はリファレンスが割り当てられている変数を表示しません。 この動きを示すために、上の例をちょっと変更した例を考えてみましょう:

<?php
$var1 = 'Hello';
$var1 .= ' World';
// Point three variables as references to the same value
$var2 =& $var1;
$var3 =& $var1;

debug_zval_dump($var1);
?>

上の例の出力は以下となります。

string(11) "Hello World" refcount(2)

$var1, $var2, $var3 はリファレンスで結びついていますが、 値 だけが debug_zval_dump() に渡されます。 この値は、リファレンスの設定に一度使われ、 debug_zval_dump() の中で一度使われます。 よって、リファレンスカウントは2になります。

データ型によっては、Zend Engine 内で最適化が行われてしまうため、 ユーザはさらに混乱してしまいます。 整数のように "コピーオンライト" を行わないデータ型の変数では、 リファレンスカウントを全く表示しません。 別の場合、このリファレンスカウントの値は、 内部的に使われる追加のコピーの値を表示する場合もあります。 たとえば、文字列リテラルや配列が、命令セットの一部として保存されているような場合です。

参考

  • var_dump() - 変数に関する情報をダンプする
  • debug_backtrace() - バックトレースを生成する
  • リファレンスの説明
  • » References Explained (by Derick Rethans)


floatval のエイリアス

  • ≪ debug_zval_dump
  • empty ≫
  • PHP Manual
  • 変数操作 関数
  • floatval のエイリアス

doubleval

(PHP 4, PHP 5, PHP 7, PHP 8)

doubleval — floatval() のエイリアス

説明

この関数は次の関数のエイリアスです。 floatval().


変数が空であるかどうかを検査する

  • ≪ doubleval
  • floatval ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が空であるかどうかを検査する

empty

(PHP 4, PHP 5, PHP 7, PHP 8)

empty — 変数が空であるかどうかを検査する

説明

empty(mixed $var): bool

変数が空であるかどうかを検査します。 変数が空であるとみなされるのは、変数が存在しない場合や 変数の値が false に等しい場合です。 empty() は、変数が存在しない場合でも警告を発しません。

パラメータ

var

チェックする変数

変数が存在しなくても警告は発生しません。 つまり、empty() は本質的に !isset($var) || $var == false と同じことを簡潔に記述しているだけです。

戻り値

var が存在しない、 または空や0の値が設定されている場合、 つまり boolean のコンテキストで false と見なされる場合、 true を返します。 詳細は boolean への変換 を参照ください。 それ以外の場合は false を返します。

例

例1 簡単な empty() / isset() の比較

<?php
$var = 0;

// $var が空なのでtrueと評価されます
if (empty($var)) {
echo '$var is either 0, empty, or not set at all';
}

// $var が設定されているのでtrueと評価されます
if (isset($var)) {
echo '$var is set even though it is empty';
}
?>

例2 文字列のオフセットに対する empty()

<?php
$expected_array_got_string = 'somestring';
var_dump(empty($expected_array_got_string['some_key']));
var_dump(empty($expected_array_got_string[0]));
var_dump(empty($expected_array_got_string['0']));
var_dump(empty($expected_array_got_string[0.5]));
var_dump(empty($expected_array_got_string['0.5']));
var_dump(empty($expected_array_got_string['0 Mostel']));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)
bool(false)
bool(true)
bool(true)

注意

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

注意:

オブジェクトのアクセス不能なプロパティに対して empty() を使用した場合は、もしオーバーロードメソッド __isset() が宣言されていればそれをコールします。

参考

  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • __isset()
  • unset() - 指定した変数の割当を解除する
  • array_key_exists() - 指定したキーまたは添字が配列にあるかどうかを調べる
  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える
  • strlen() - 文字列の長さを得る
  • PHP 型の比較表


変数の float 値を取得する

  • ≪ empty
  • get_debug_type ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の float 値を取得する

floatval

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

floatval — 変数の float 値を取得する

説明

floatval(mixed $value): float

value の float 値を返します。

パラメータ

value

あらゆるスカラ型を指定できます。オブジェクトに floatval() を使用することはできません。 その場合は E_WARNING レベルのエラーを発して 1 を返します。

戻り値

指定した変数の float 値を返します。 空の配列の場合は 0、空でない配列の場合は 1 を返します。

文字列の場合、ほとんどは 0 を返しますが、先頭の文字が何であるかによってこれは変わります。 float 型へのキャスト と同じルールに従います。

変更履歴

バージョン | 説明
8.0.0 | オブジェクトを指定して変換しようとした場合のエラーレベルが、 E_NOTICE から E_WARNING に変更されました。

例

例1 floatval() の例

<?php
$var = '122.34343The';
$float_value_of_var = floatval($var);
echo $float_value_of_var; // 122.34343
?>

例2 floatval() で、先頭が非数値である場合の例

<?php
$var = 'The122.34343';
$float_value_of_var = floatval($var);
echo $float_value_of_var; // 0
?>

参考

  • boolval() - 変数の boolean としての値を取得する
  • intval() - 変数の整数としての値を取得する
  • strval() - 変数の文字列としての値を取得する
  • settype() - 変数の型をセットする
  • 型の相互変換


変数の型名をデバッグしやすい形で取得する

  • ≪ floatval
  • get_defined_vars ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の型名をデバッグしやすい形で取得する

get_debug_type

(PHP 8)

get_debug_type — 変数の型名をデバッグしやすい形で取得する

説明

get_debug_type(mixed $value): string

PHP の変数 value の、解決済みの名前を返します。 この関数は、オブジェクトをクラス名に、 リソースをリソース型の名前に、 そしてスカラー型の値を型宣言で使われている通常の名前に解決します。

gettype() は、歴史的な理由で決まった型の名前を返します。 この関数は、それよりも実際に使われている型により近い名前を返すという点が異なります。

パラメータ

value

型をチェックする変数。

戻り値

返される文字列としてあり得るのは、以下になります:

型 + 状態 | 戻り値 | 備考
null | "null" | -
boolean (true または false) | "bool" | -
整数型 | "int" | -
浮動小数点型 | "float" | -
文字列 | "string" | -
配列 | "array" | -
リソース | "resource (resourcename)" | -
リソース(閉じられたもの) | "resource (closed)" | 例: fclose で閉じられたファイルストリーム
名前付きのクラスのオブジェクト | 名前空間も含めた、クラスの完全修飾名。 例: Foo\Bar | -
無名クラスのオブジェクト | "class@anonymous" | 無名クラスのオブジェクトは、$x = new class { ... } という文法で作成されます。

例

例1 get_debug_type() の例

<?php
echo get_debug_type(null) . PHP_EOL;
echo get_debug_type(true) . PHP_EOL;
echo get_debug_type(1) . PHP_EOL;
echo get_debug_type(0.1) . PHP_EOL;
echo get_debug_type("foo") . PHP_EOL;
echo get_debug_type([]) . PHP_EOL;

$fp = fopen(__FILE__, 'rb');
echo get_debug_type($fp) . PHP_EOL;

fclose($fp);
echo get_debug_type($fp) . PHP_EOL;

echo get_debug_type(new stdClass) . PHP_EOL;
echo get_debug_type(new class {}) . PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

null
bool
int
float
string
array
resource (stream)
resource (closed)
stdClass
class@anonymous

参考

  • gettype() - 変数の型を取得する
  • get_class() - オブジェクトのクラス名を返す


全ての定義済の変数を配列で返す

  • ≪ get_debug_type
  • get_resource_id ≫
  • PHP Manual
  • 変数操作 関数
  • 全ての定義済の変数を配列で返す

get_defined_vars

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

get_defined_vars — 全ての定義済の変数を配列で返す

説明

get_defined_vars(): array

この関数は、環境変数、サーバー変数、get_defined_vars() がコールされたスコープ内でユーザーが定義した変数を含む、全ての の定義済の変数のリストを有する多次元の配列を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

すべての変数を含む多次元の配列を返します。

例

例1 get_defined_vars() の例

<?php
$b = array(1, 1, 2, 3, 5, 8);

$arr = get_defined_vars();

// $b を出力
print_r($arr["b"]);

// PHPインタプリタのパスを出力 (CGIとして使用された場合)
// 例えば、/usr/local/bin/php
echo $arr["_"];

// コマンドラインパラメータがある場合に出力
print_r($arr["argv"]);

// サーバー変数を全て表示
print_r($arr["_SERVER"]);

// 変数の配列で利用可能なキーを全て出力
print_r(array_keys(get_defined_vars()));
?>

参考

  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • get_defined_functions() - 定義済みの全ての関数を配列で返す
  • get_defined_constants() - すべての定数の名前とその値を連想配列として返す


指定されたリソースの、数値の識別子を返す

  • ≪ get_defined_vars
  • get_resource_type ≫
  • PHP Manual
  • 変数操作 関数
  • 指定されたリソースの、数値の識別子を返す

get_resource_id

(PHP 8)

get_resource_id — 指定されたリソースの、数値の識別子を返す

説明

get_resource_id(resource $resource): int

この関数は、リソースの数値の識別子を識別するための、 型安全な方法を提供します。

パラメータ

resource

評価されるリソースハンドル

戻り値

resource の識別子を数値で返します。

この関数は、本質的には resource をint にキャストしたものですが、 リソースID をより簡単に取得できるようにするものです。

例

例1 get_resource_id() が、リソースを数値にキャストした場合と同じ結果になる例

<?php
$handle = fopen("php://stdout", "w");

echo (int) $handle . "\n";

echo get_resource_id($handle);

?>

上の例の出力は、 たとえば以下のようになります。

698
698

参考

  • get_resource_type() - リソース型を返す


リソース型を返す

  • ≪ get_resource_id
  • gettype ≫
  • PHP Manual
  • 変数操作 関数
  • リソース型を返す

get_resource_type

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

get_resource_type — リソース型を返す

説明

get_resource_type(resource $resource): string

この関数は、指定したリソースの型を取得します。

パラメータ

resource

評価されるリソースハンドル。

戻り値

指定された resource がリソースであった場合、 この関数はその型を表す文字列を返します。この関数で型が判別できなかった 場合は、戻り値は文字列 Unknown となります。

もし resource が resource でない場合、 この関数は null を返し、エラーを発生させます。

例

例1 get_resource_type() の例

<?php
$fp = fopen("foo", "w");
echo get_resource_type($fp) . "\n";

// PHP 8.0.0 以降は curl_init 関数がリソースの代わりに CurlHandle オブジェクトを返すようになったので、以下のコードは動作しません。
$c = curl_init();
echo get_resource_type($c) . "\n";
?>

上の例の PHP 7 での出力は、このようになります。

stream
curl

参考

  • get_resource_id() - 指定されたリソースの、数値の識別子を返す


変数の型を取得する

  • ≪ get_resource_type
  • intval ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の型を取得する

gettype

(PHP 4, PHP 5, PHP 7, PHP 8)

gettype — 変数の型を取得する

説明

gettype(mixed $value): string

PHP 変数 value の型を返します。 型のチェックには、この関数ではなく is_* 関数を使います。

パラメータ

value

型を調べたい変数。

戻り値

返された文字列は、以下のいずれかの値を持ちます。

  • "boolean"
  • "integer"
  • "double" (歴史的な理由により float の場合は、"float" ではなく、 "double" が返されます)
  • "string"
  • "array"
  • "object"
  • "resource"
  • "resource (closed)" (PHP 7.2.0 以降)
  • "NULL"
  • "unknown type"

変更履歴

バージョン | 説明
7.2.0 | クローズ済みのリソースを渡すと 'resource (closed)'を返すようになりました。 以前は 'unknown type'を返していました。

例

例1 gettype() の例

<?php

$data = array(1, 1., NULL, new stdClass, 'foo');

foreach ($data as $value) {
echo gettype($value), "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

integer
double
NULL
object
string

参考

  • get_debug_type() - 変数の型名をデバッグしやすい形で取得する
  • settype() - 変数の型をセットする
  • get_class() - オブジェクトのクラス名を返す
  • is_array() - 変数が配列かどうかを検査する
  • is_bool() - 変数が boolean であるかを調べる
  • is_callable() - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_null() - 変数が null かどうか調べる
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_resource() - 変数がリソースかどうかを調べる
  • is_scalar() - 変数がスカラかどうかを調べる
  • is_string() - 変数の型が文字列かどうかを調べる
  • function_exists() - 指定した関数が定義されている場合に true を返す
  • method_exists() - クラスメソッドが存在するかどうかを確認する


変数の整数としての値を取得する

  • ≪ gettype
  • is_array ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の整数としての値を取得する

intval

(PHP 4, PHP 5, PHP 7, PHP 8)

intval — 変数の整数としての値を取得する

説明

intval(mixed $value, int $base = 10): int

指定された値 base を基数（デフォルトは 10）とする、 value の int としての値を返します。 オブジェクトに intval() を使用することはできません。 その場合は E_WARNING レベルのエラーを発して 1 を返します。

パラメータ

value

整数に変換するスカラー値

base

変換のための基数

注意:

base が 0 の場合は、 value のフォーマットに基づいて利用する基数を決めます。

  • 文字列の先頭が "0x" (あるいは "0X") の場合は、基数を 16 (十六進数) とします。
  • 文字列の先頭が "0b" (あるいは "0B") の場合は、基数を 2 (二進数) とします。
  • 文字列の先頭が "0" の場合は、基数を 8 (八進数) とします。
  • それ以外の場合は、基数を 10 (十進数) とします。

戻り値

成功時は value の整数値、失敗時は 0。 空の配列の場合は 0、空でない配列の場合は 1 を返します。

最大値はシステムに依存します。32 ビットシステムでは、 最大の符号付き整数の範囲 -2147483648 ～ 2147483647 となります。 このため、そのようなシステムでは intval('1000000000000') は 2147483647 を返します。 64 ビットシステムにおける最大の符号付き整数は 9223372036854775807 となります。

文字列の場合、文字列の最左の文字に依存しますが、ほとんどの場合で 0 を返します。 整数への変換 の一般的なルールが適用されます。

変更履歴

バージョン | 説明
8.0.0 | オブジェクトを指定して変換しようとした場合のエラーレベルが、 E_NOTICE から E_WARNING に変更されました。

例

例1 intval() の例

以下の例は 64 ビットシステムに基づきます。

<?php
echo intval(42); // 42
echo intval(4.2); // 4
echo intval('42'); // 42
echo intval('+42'); // 42
echo intval('-42'); // -42
echo intval(042); // 34
echo intval('042'); // 42
echo intval(1e10); // 10000000000
echo intval('1e10'); // 10000000000
echo intval(0x1A); // 26
echo intval('0x1A'); // 0
echo intval('0x1A', 0); // 26
echo intval(42000000); // 42000000
echo intval(420000000000000000000); // -4275113695319687168
echo intval('420000000000000000000'); // 9223372036854775807
echo intval(42, 8); // 42
echo intval('42', 8); // 34
echo intval(array()); // 0
echo intval(array('foo', 'bar')); // 1
echo intval(false); // 0
echo intval(true); // 1

?>

注意

注意:

パラメータ base はパラメータ value が文字列でない限り意味がありません。

参考

  • boolval() - 変数の boolean としての値を取得する
  • floatval() - 変数の float 値を取得する
  • strval() - 変数の文字列としての値を取得する
  • settype() - 変数の型をセットする
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • 型の相互変換
  • BCMath任意精度数学関数


変数が配列かどうかを検査する

  • ≪ intval
  • is_bool ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が配列かどうかを検査する

is_array

(PHP 4, PHP 5, PHP 7, PHP 8)

is_array — 変数が配列かどうかを検査する

説明

is_array(mixed $value): bool

与えられた変数が配列かどうかを検査します。

パラメータ

value

評価する変数

戻り値

value が 配列型 の場合 true、 そうでない場合 false を返します。

例

例1 変数が配列かどうか検査する

<?php
$yes = array('this', 'is', 'an array');

echo is_array($yes) ? 'Array' : 'not an Array';
echo "\n";

$no = 'this is a string';

echo is_array($no) ? 'Array' : 'not an Array';
?>

上の例の出力は以下となります。

Array
not an Array

参考

  • array_is_list() - 指定された配列がリストかどうかをチェックする
  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する


変数が boolean であるかを調べる

  • ≪ is_array
  • is_callable ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が boolean であるかを調べる

is_bool

(PHP 4, PHP 5, PHP 7, PHP 8)

is_bool — 変数が boolean であるかを調べる

説明

is_bool(mixed $value): bool

指定した変数が boolean であるかどうかを調べます。

パラメータ

value

評価する変数。

戻り値

value が bool である場合に true 、それ以外の場合に false を返します。

例

例1 is_bool() の例

<?php
$a = false;
$b = 0;

// $a は boolean なので、これは true となります
if (is_bool($a) === true) {
echo "Yes, this is a boolean";
}

// $b は boolean ではないので、これは false となります
if (is_bool($b) === false) {
echo "No, this is not a boolean";
}
?>

参考

  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_array() - 変数が配列かどうかを検査する


引数が、現在のスコープから関数としてコール可能な値かどうかを調べる

  • ≪ is_bool
  • is_countable ≫
  • PHP Manual
  • 変数操作 関数
  • 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる

is_callable

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

is_callable — 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる

説明

is_callable(mixed $value, bool $syntax_only = false, string &$callable_name = null): bool

引数の内容が、callable かどうかを調べます。

パラメータ

value

チェックする値。

syntax_only

true の場合、この関数は単に value が関数またはメソッドであるかどうかだけを調べます。 文字列以外の型の変数や不正な形式の配列は、 引数として受け付けられません。有効な配列の形式は、 最初のエントリがオブジェクトあるいは文字列で、2 番目のエントリが文字列である 2 つのエントリからなるものです。

callable_name

"呼び出し名" を受け取ります。下の例では "someClass::someMethod" です。これは someClass::SomeMethod() が static メソッドであるかのようにみえますが、 そうではないことに注意しましょう。

戻り値

value がコール可能な場合に true、 それ以外の場合に false を返します。

例

例1 is_callable() の例

<?php
// 変数が、関数としてコール可能かどうかを確かめます。

//
// 関数名を含む単純な配列
//

function someFunction()
{
}

$functionVariable = 'someFunction';

var_dump(is_callable($functionVariable, false, $callable_name)); // bool(true)

echo $callable_name, "\n"; // someFunction

//
// メソッドを含む配列
//

class someClass {

function someMethod()
{
}

}

$anObject = new someClass();

$methodVariable = array($anObject, 'someMethod');

var_dump(is_callable($methodVariable, true, $callable_name)); // bool(true)

echo $callable_name, "\n"; // someClass::someMethod

?>

例2 is_callable() とコンストラクタ

is_callable() はコンストラクタを callable だとはみなしません。

<?php

class Foo
{
public function __construct() {}
public function foo() {}
}

var_dump(
is_callable(array('Foo', '__construct')),
is_callable(array('Foo', 'foo'))
);

上の例の出力は以下となります。

bool(false)
bool(false)

注意

  • オブジェクトは、 __invoke() を実装していれば常にコール可能ですし、 そのメソッドは現在のスコープからアクセス可能です。
  • __callStatic() を実装したクラスの場合、そのクラス名はコール可能です。
  • __call() を実装しているオブジェクトが存在する場合、 この関数は、そのオブジェクトのあらゆるメソッドに対して true を返します。 たとえそのメソッドが定義されていなくてもです。
  • この関数を、クラス名を指定してコールすると、 オートローディングが行われる可能性があります。

参考

  • function_exists() - 指定した関数が定義されている場合に true を返す
  • method_exists() - クラスメソッドが存在するかどうかを確認する


引数が、数えられる値かどうかを調べる

  • ≪ is_callable
  • is_double ≫
  • PHP Manual
  • 変数操作 関数
  • 引数が、数えられる値かどうかを調べる

is_countable

(PHP 7 >= 7.3.0, PHP 8)

is_countable — 引数が、数えられる値かどうかを調べる

説明

is_countable(mixed $value): bool

引数の内容が、array または Countable を実装したオブジェクトかどうかを調べます。

パラメータ

value

チェックする値

戻り値

value が数えられる場合に true、 それ以外の場合に false を返します。

変更履歴

バージョン | 説明
7.3.0 | is_countable() が追加されました。

例

例1 is_countable() の例

<?php
var_dump(is_countable([1, 2, 3])); // bool(true)
var_dump(is_countable(new ArrayIterator(['foo', 'bar', 'baz']))); // bool(true)
var_dump(is_countable(new ArrayIterator())); // bool(true)
var_dump(is_countable(new stdClass())); // bool(false)

参考

  • is_array() - 変数が配列かどうかを検査する
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_iterable() - 変数の内容が反復可能な値であることを確認する
  • is_bool() - 変数が boolean であるかを調べる


is_float のエイリアス

  • ≪ is_countable
  • is_float ≫
  • PHP Manual
  • 変数操作 関数
  • is_float のエイリアス

is_double

(PHP 4, PHP 5, PHP 7, PHP 8)

is_double — is_float() のエイリアス

説明

この関数は次の関数のエイリアスです。 is_float().


変数の型が float かどうか調べる

  • ≪ is_double
  • is_int ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の型が float かどうか調べる

is_float

(PHP 4, PHP 5, PHP 7, PHP 8)

is_float — 変数の型が float かどうか調べる

説明

is_float(mixed $value): bool

与えられた変数の型が float かどうかを調べます。

注意:

変数が数値もしくは数値形式の文字列の場合 (フォームからの入力の場合は 常に文字列となります) 、is_numeric() を使用する必要があります。

パラメータ

value

評価する変数

戻り値

もし value が float 型 の場合 true、 そうでない場合は false を返します。

例

例1 is_float() の例

<?php

var_dump(is_float(27.25));
var_dump(is_float('abc'));
var_dump(is_float(23));
var_dump(is_float(23.5));
var_dump(is_float(1e7)); // 科学記法
var_dump(is_float(true));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
bool(false)
bool(true)
bool(true)
bool(false)

参考

  • is_bool() - 変数が boolean であるかを調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_array() - 変数が配列かどうかを検査する
  • is_object() - 変数がオブジェクトかどうかを検査する


変数が整数型かどうかを検査する

  • ≪ is_float
  • is_integer ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が整数型かどうかを検査する

is_int

(PHP 4, PHP 5, PHP 7, PHP 8)

is_int — 変数が整数型かどうかを検査する

説明

is_int(mixed $value): bool

与えられた変数の型が整数型かどうかを検査します。

注意:

変数が数値か数値形式の文字列かを判断したい場合 (フォームからの入力の場合は 常に文字列となります) 、is_numeric() を使用する必要があります。

パラメータ

value

評価する変数

戻り値

もし value が 整数型(int)の場合 true、 そうでない場合は false を返します。

例

例1 is_int() の例

<?php
$values = array(23, "23", 23.5, "23.5", null, true, false);
foreach ($values as $value) {
echo "is_int(";
var_export($value);
echo ") = ";
var_dump(is_int($value));
}
?>

上の例の出力は以下となります。

is_int(23) = bool(true)
is_int('23') = bool(false)
is_int(23.5) = bool(false)
is_int('23.5') = bool(false)
is_int(NULL) = bool(false)
is_int(true) = bool(false)
is_int(false) = bool(false)

参考

  • is_bool() - 変数が boolean であるかを調べる
  • is_float() - 変数の型が float かどうか調べる
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_array() - 変数が配列かどうかを検査する
  • is_object() - 変数がオブジェクトかどうかを検査する


is_int のエイリアス

  • ≪ is_int
  • is_iterable ≫
  • PHP Manual
  • 変数操作 関数
  • is_int のエイリアス

is_integer

(PHP 4, PHP 5, PHP 7, PHP 8)

is_integer — is_int() のエイリアス

説明

この関数は次の関数のエイリアスです。 is_int().


変数の内容が反復可能な値であることを確認する

  • ≪ is_integer
  • is_long ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の内容が反復可能な値であることを確認する

is_iterable

(PHP 7 >= 7.1.0, PHP 8)

is_iterable — 変数の内容が反復可能な値であることを確認する

説明

is_iterable(mixed $value): bool

変数の内容が iterable 疑似型で許容されること、すなわち array、あるいは Traversable のどちらかを実装したオブジェクトであることを確認する。

パラメータ

value

チェックする値

戻り値

value が反復可能であれば true を、そうでなければ false を返す。

例

例1 is_iterable() の例

<?php

var_dump(is_iterable([1, 2, 3])); // bool(true)
var_dump(is_iterable(new ArrayIterator([1, 2, 3]))); // bool(true)
var_dump(is_iterable((function () { yield 1; })())); // bool(true)
var_dump(is_iterable(1)); // bool(false)
var_dump(is_iterable(new stdClass())); // bool(false)

?>

参考

  • is_array() - 変数が配列かどうかを検査する


is_int のエイリアス

  • ≪ is_iterable
  • is_null ≫
  • PHP Manual
  • 変数操作 関数
  • is_int のエイリアス

is_long

(PHP 4, PHP 5, PHP 7, PHP 8)

is_long — is_int() のエイリアス

説明

この関数は次の関数のエイリアスです。 is_int().


変数が null かどうか調べる

  • ≪ is_long
  • is_numeric ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が null かどうか調べる

is_null

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

is_null — 変数が null かどうか調べる

説明

is_null(mixed $value): bool

指定した変数が null かどうかを調べます。

パラメータ

value

評価する変数。

戻り値

value が null の場合に true、 それ以外の場合に false を返します。

例

例1 is_null() の例

<?php

error_reporting(E_ALL);

$foo = NULL;
var_dump(is_null($inexistent), is_null($foo));

?>
Notice: Undefined variable: inexistent in ...
bool(true)
bool(true)

参考

  • null 型
  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • is_bool() - 変数が boolean であるかを調べる
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_array() - 変数が配列かどうかを検査する


変数が数字または数値形式の文字列であるかを調べる

  • ≪ is_null
  • is_object ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が数字または数値形式の文字列であるかを調べる

is_numeric

(PHP 4, PHP 5, PHP 7, PHP 8)

is_numeric — 変数が数字または数値形式の文字列であるかを調べる

説明

is_numeric(mixed $value): bool

指定した変数が数値または 数値形式の文字列であるかどうかを調べます。

パラメータ

value

評価する変数。

戻り値

value が数値または 数値形式の文字列 である場合に true、それ以外の場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 空白文字で終わる数値形式の文字列 ("42 ") に対して、この関数は true を返すようになりました。 これより前のバージョンでは、false を返していました。

例

例1 is_numeric() の例

<?php
$tests = array(
"42",
1337,
0x539,
02471,
0b10100111001,
1337e0,
"0x539",
"02471",
"0b10100111001",
"1337e0",
"not numeric",
array(),
9.1,
null,
'',
);

foreach ($tests as $element) {
if (is_numeric($element)) {
echo var_export($element, true) . " is numeric", PHP_EOL;
} else {
echo var_export($element, true) . " is NOT numeric", PHP_EOL;
}
}
?>

上の例の出力は以下となります。

'42' is numeric
1337 is numeric
1337 is numeric
1337 is numeric
1337 is numeric
1337.0 is numeric
'0x539' is NOT numeric
'02471' is numeric
'0b10100111001' is NOT numeric
'1337e0' is numeric
'not numeric' is NOT numeric
array (
) is NOT numeric
9.1 is numeric
NULL is NOT numeric
'' is NOT numeric

例2 空白文字と is_numeric() 関数

<?php
$tests = [
" 42",
"42 ",
"\u{A0}9001", // non-breaking space
"9001\u{A0}", // non-breaking space
];

foreach ($tests as $element) {
if (is_numeric($element)) {
echo var_export($element, true) . " is numeric", PHP_EOL;
} else {
echo var_export($element, true) . " is NOT numeric", PHP_EOL;
}
}
?>

上の例の PHP 8 での出力は、このようになります。:

' 42' is numeric
'42 ' is numeric
' 9001' is NOT numeric
'9001 ' is NOT numeric

上の例の PHP 7 での出力は、このようになります。

' 42' is numeric
'42 ' is NOT numeric
' 9001' is NOT numeric
'9001 ' is NOT numeric

参考

  • 数値形式の文字列
  • ctype_digit() - 数字かどうかを調べる
  • is_bool() - 変数が boolean であるかを調べる
  • is_null() - 変数が null かどうか調べる
  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_array() - 変数が配列かどうかを検査する
  • filter_var() - 指定したフィルタでデータをフィルタリングする


変数がオブジェクトかどうかを検査する

  • ≪ is_numeric
  • is_real ≫
  • PHP Manual
  • 変数操作 関数
  • 変数がオブジェクトかどうかを検査する

is_object

(PHP 4, PHP 5, PHP 7, PHP 8)

is_object — 変数がオブジェクトかどうかを検査する

説明

is_object(mixed $value): bool

与えられた変数がオブジェクトかどうかを調べます。

パラメータ

value

評価する変数。

戻り値

もし value が object型 の場合 true、 そうでない場合は false を返します。

変更履歴

バージョン | 説明
7.2.0 | クラス定義が存在せず (__PHP_Incomplete_Class クラス)、 かつシリアライズされていないオブジェクトに対して、 is_object() 関数は true を返すようになりました。 これより前のバージョンでは、false を返していました。

例

例1 is_object() の例

<?php
// オブジェクトから配列を返す
// シンプルな関数を宣言します
function get_students($obj)
{
if (!is_object($obj)) {
return false;
}

return $obj->students;
}

// 新しいクラスのインスタンスを宣言し、
// 値を設定します
$obj = new stdClass();
$obj->students = array('Kalle', 'Ross', 'Felipe');

var_dump(get_students(null));
var_dump(get_students($obj));
?>

参考

  • is_bool() - 変数が boolean であるかを調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_float() - 変数の型が float かどうか調べる
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_array() - 変数が配列かどうかを検査する


is_float のエイリアス

  • ≪ is_object
  • is_resource ≫
  • PHP Manual
  • 変数操作 関数
  • is_float のエイリアス

is_real

(PHP 4, PHP 5, PHP 7, PHP 8)

is_real — is_float() のエイリアス

説明

この関数は次の関数のエイリアスです。 is_float().

警告

このエイリアスは PHP 7.4.0 で 非推奨 となり、PHP 8.0.0 で 削除 されました。


変数がリソースかどうかを調べる

  • ≪ is_real
  • is_scalar ≫
  • PHP Manual
  • 変数操作 関数
  • 変数がリソースかどうかを調べる

is_resource

(PHP 4, PHP 5, PHP 7, PHP 8)

is_resource — 変数がリソースかどうかを調べる

説明

is_resource(mixed $value): bool

指定した変数が resource かどうかを調べます。

パラメータ

value

評価する変数。

戻り値

value が resource の場合に true、 それ以外の場合に false を返します。

例

例1 is_resource() の例

<?php

$handle = fopen("php://stdout", "w");
if (is_resource($handle)) {
echo '$handle is a resource';
}

?>

上の例の出力は以下となります。

$handle is a resource

注意

注意:

is_resource() は、厳格な型チェックを行うわけではありません。 value がすでに閉じられたリソース変数である場合は、false を返します。

参考

  • リソース型のドキュメント
  • get_resource_type() - リソース型を返す


変数がスカラかどうかを調べる

  • ≪ is_resource
  • is_string ≫
  • PHP Manual
  • 変数操作 関数
  • 変数がスカラかどうかを調べる

is_scalar

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

is_scalar — 変数がスカラかどうかを調べる

説明

is_scalar(mixed $value): bool

指定した変数がスカラかどうかを調べます。

スカラ変数には int、float、string あるいは bool が含まれます。 array、object、 resource、null はスカラではありません。

注意:

リソース型は現在整数に基づく抽象型であるため、 is_scalar() は resource 型の値を スカラ値と判定しません。この実装の詳細は変更される可能性があるため、 前堤にするべきではありません。

注意:

is_scalar() は、NULL をスカラとは見なしません。

パラメータ

value

評価する変数。

戻り値

value がスカラの場合に true、 それ以外の場合に false を返します。

例

例1 is_scalar() の例

<?php
function show_var($var)
{
if (is_scalar($var)) {
echo $var;
} else {
var_dump($var);
}
}
$pi = 3.1416;
$proteins = array("hemoglobin", "cytochrome c oxidase", "ferredoxin");

show_var($pi);
show_var($proteins)

?>

上の例の出力は以下となります。

3.1416
array(3) {
  [0]=>
  string(10) "hemoglobin"
  [1]=>
  string(20) "cytochrome c oxidase"
  [2]=>
  string(10) "ferredoxin"
}

参考

  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_numeric() - 変数が数字または数値形式の文字列であるかを調べる
  • is_real() - is_float のエイリアス
  • is_string() - 変数の型が文字列かどうかを調べる
  • is_bool() - 変数が boolean であるかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_array() - 変数が配列かどうかを検査する


変数の型が文字列かどうかを調べる

  • ≪ is_scalar
  • isset ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の型が文字列かどうかを調べる

is_string

(PHP 4, PHP 5, PHP 7, PHP 8)

is_string — 変数の型が文字列かどうかを調べる

説明

is_string(mixed $value): bool

指定した変数の型が文字列かどうかを調べます。

パラメータ

value

評価する変数。

戻り値

value の型が string である場合に true、それ以外の場合に false を返します。

例

例1 is_string() の例

<?php
$values = array(false, true, null, 'abc', '23', 23, '23.5', 23.5, '', ' ', '0', 0);
foreach ($values as $value) {
echo "is_string(";
var_export($value);
echo ") = ";
echo var_dump(is_string($value));
}
?>

上の例の出力は以下となります。

is_string(false) = bool(false)
is_string(true) = bool(false)
is_string(NULL) = bool(false)
is_string('abc') = bool(true)
is_string('23') = bool(true)
is_string(23) = bool(false)
is_string('23.5') = bool(true)
is_string(23.5) = bool(false)
is_string('') = bool(true)
is_string(' ') = bool(true)
is_string('0') = bool(true)
is_string(0) = bool(false)

参考

  • is_float() - 変数の型が float かどうか調べる
  • is_int() - 変数が整数型かどうかを検査する
  • is_bool() - 変数が boolean であるかを調べる
  • is_object() - 変数がオブジェクトかどうかを検査する
  • is_array() - 変数が配列かどうかを検査する


変数が宣言されていること、そして null とは異なることを検査する

  • ≪ is_string
  • print_r ≫
  • PHP Manual
  • 変数操作 関数
  • 変数が宣言されていること、そして null とは異なることを検査する

isset

(PHP 4, PHP 5, PHP 7, PHP 8)

isset — 変数が宣言されていること、そして null とは異なることを検査する

説明

isset(mixed $var, mixed ...$vars): bool

変数がセットされているかを調べます。 これは変数が宣言されており、 null とは異なる値だということです。

変数が、unset() により割当を解除された場合、 もはやセットされているとは見做されません。

null が代入されている変数をチェックしたときは、 isset() は false を返します。 null文字 ("\0") は PHP の null 定数とは異なることにも注意してください。

複数のパラメータが渡された場合は、 isset() は全てのパラメータがセットされている場合にだけ true を返します。 評価は左から右へと行われ、セットされていない値に出会うとすぐに評価が止まります。

パラメータ

var

調べたい変数。

vars

別の変数。

戻り値

var が存在して null 以外の値をとれば true、 そうでなければ false を返します。

例

例1 isset() の例

<?php

$var = '';

// これは TRUE と評価されるので、テキストが出力される
if (isset($var)) {
echo "This var is set so I will print.";
}

// 次の例では、isset() の戻り値を出力するため var_dump を
// 使用している

$a = "test";
$b = "anothertest";

var_dump(isset($a)); // TRUE
var_dump(isset($a, $b)); // TRUE

unset ($a);

var_dump(isset($a)); // FALSE
var_dump(isset($a, $b)); // FALSE

$foo = NULL;
var_dump(isset($foo)); // FALSE

?>

この関数は配列の要素に対しても動作します:

<?php

$a = array ('test' => 1, 'hello' => NULL, 'pie' => array('a' => 'apple'));

var_dump(isset($a['test'])); // TRUE
var_dump(isset($a['foo'])); // FALSE
var_dump(isset($a['hello'])); // FALSE

// キー 'hello' は NULL と等しいのでセットされていないと見なされる。
// もし NULL なキー値に対してチェックを行いたい場合、次を試してみること:
var_dump(array_key_exists('hello', $a)); // TRUE

// 配列の深い要素の値のチェック
var_dump(isset($a['pie']['a'])); // TRUE
var_dump(isset($a['pie']['b'])); // FALSE
var_dump(isset($a['cake']['a']['b'])); // FALSE

?>

例2 文字列のオフセットに対する isset()

<?php
$expected_array_got_string = 'somestring';
var_dump(isset($expected_array_got_string['some_key']));
var_dump(isset($expected_array_got_string[0]));
var_dump(isset($expected_array_got_string['0']));
var_dump(isset($expected_array_got_string[0.5]));
var_dump(isset($expected_array_got_string['0.5']));
var_dump(isset($expected_array_got_string['0 Mostel']));
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(true)
bool(true)
bool(false)
bool(false)

注意

警告

isset() は何らかの値が渡された 変数の場合のみ動作します。そうでない場合、パースエラーとなります。 もし 定数 が設定されているかどうかをチェックする場合は、 defined() を使用してください。

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

注意:

オブジェクトのアクセス不能なプロパティに対して isset() を使用した場合は、もしオーバーロードメソッド __isset() が宣言されていればそれをコールします。

参考

  • empty() - 変数が空であるかどうかを検査する
  • __isset()
  • unset() - 指定した変数の割当を解除する
  • defined() - 指定した名前の定数が存在するかどうかを調べる
  • PHP 型の比較表
  • array_key_exists() - 指定したキーまたは添字が配列にあるかどうかを調べる
  • is_null() - 変数が null かどうか調べる
  • エラー制御演算子 @


指定した変数に関する情報を解りやすく出力する

  • ≪ isset
  • serialize ≫
  • PHP Manual
  • 変数操作 関数
  • 指定した変数に関する情報を解りやすく出力する

print_r

(PHP 4, PHP 5, PHP 7, PHP 8)

print_r — 指定した変数に関する情報を解りやすく出力する

説明

print_r(mixed $value, bool $return = false): string|bool

print_r() は、 変数の値に関する情報を解り易い形式で表示します。

print_r()、var_dump() および var_export() は、オブジェクトの protected および private のプロパティも表示します。 static が付いたクラスメンバーは表示されません。

パラメータ

value

表示したい式。

return

print_r() の結果を取得したい場合には return 引数を使います。 この引数が true の場合には、 print_r() は情報を表示するかわりに情報を返します。

戻り値

string、int, float を指定した場合はその値が出力されます。 array を指定した場合、キーと要素を表す形式で値が 表示されます。object に関しても同様の表示形式となります。

return パラメータが true の場合は、 この関数は string を返します。それ以外の場合の戻り値は true です。

例

例1 print_r() の例

<pre>
<?php
$a = array ('a' => 'apple', 'b' => 'banana', 'c' => array ('x', 'y', 'z'));
print_r ($a);
?>
</pre>

上の例の出力は以下となります。

<pre>
Array
(
    [a] => apple
    [b] => banana
    [c] => Array
        (
            [0] => x
            [1] => y
            [2] => z
        )
)
</pre>

例2 return 引数の例

<?php
$b = array ('m' => 'monkey', 'foo' => 'bar', 'x' => array ('x', 'y', 'z'));
$results = print_r($b, true); // print_r の結果が $results に格納されます
?>

注意

注意:

return パラメータを使う場合、かつ PHP 7.1.0 より前のバージョンでは、この関数は内部的な出力バッファリングを使っていました。この場合、ob_start() のコールバック関数の中では使えません。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • var_dump() - 変数に関する情報をダンプする
  • var_export() - 変数の文字列表現を出力または返す


値の保存可能な表現を生成する

  • ≪ print_r
  • settype ≫
  • PHP Manual
  • 変数操作 関数
  • 値の保存可能な表現を生成する

serialize

(PHP 4, PHP 5, PHP 7, PHP 8)

serialize — 値の保存可能な表現を生成する

説明

serialize(mixed $value): string

値の保存可能な表現を生成します。

型や構造を失わずに PHP の値を保存または渡す際に有用です。

シリアル化された文字列を PHP の値に戻すには、 unserialize() を使用してください。

パラメータ

value

シリアル化する値。 serialize() は、resource および一部の object 以外のすべての型を処理します。（下記の注を参照ください） 自分自身への参照を含む配列を serialize() することも可能です。 シリアル化した配列/オブジェクト内の 循環参照も保存されます。その他の参照は失われます。

PHP は、シリアル化の前にまずメンバ関数 __serialize() または __sleep() のコールを試みます。ここで、シリアル化の前のオブジェクトの後始末処理 などを行います。同様に、unserialize() で オブジェクトを復元した際にはメンバ関数 __unserialize() または __wakeup() がコールされます。

注意:

オブジェクトの private メンバは、メンバ名の前にクラス名がつきます。 また protected メンバはメンバ名の前に '*' がつきます。 前に付加されるこれらの値の前後には null バイトがついています。

戻り値

value の保存可能なバイトストリーム表現を含む文字列を返します。

これはバイナリ文字列であり、null バイトを含む可能性もあることに注意しましょう。 保存したり利用したりするときも、null バイトが含まれることを想定しておかないといけません。 たとえば、serialize() の出力をデータベースに格納するときには、 通常は CHAR 型や TEXT 型ではなく BLOB 型を使わないといけません。

例

例1 serialize() の例

<?php
// $session_data はカレントユーザーのセッション情報を含む多次元配列を
// 保持しています。リクエストの最後にこれをデータベースに保存するために
// serialize() を使用します。

$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn,
"UPDATE sessions SET data = ? WHERE id = ?");
$sqldata = array (serialize($session_data), $_SERVER['PHP_AUTH_USER']);
if (!odbc_execute($stmt, $sqldata)) {
$stmt = odbc_prepare($conn,
"INSERT INTO sessions (id, data) VALUES(?, ?)");
if (!odbc_execute($stmt, array_reverse($sqldata))) {
/* 何か問題があったようです.. */
}
}
?>

注意

注意:

PHP の組み込みオブジェクトの多くはシリアル化できないことに注意しましょう。しかし、 Serializable インターフェイスを実装しているか、あるいはマジックメソッド __serialize()/__unserialize() または __sleep()/__wakeup() を実装していればシリアル化することができます。 内部クラスがこれらの要件を満たしていない場合は、確実にシリアル化することはできません。

この規則には歴史的な例外もあり、 上記のインターフェイスやマジックメソッドを実装していない内部オブジェクトの中にも シリアル化可能なものがあります。

警告

serialize() でオブジェクトをシリアル化するときに、 名前空間を指定したクラスの名前の先頭にあるバックスラッシュは含めません。これは互換性を高めるためです。

参考

  • unserialize() - 保存用表現から PHP の値を生成する
  • var_export() - 変数の文字列表現を出力または返す
  • json_encode() - 値を JSON 形式にして返す
  • オブジェクトのシリアル化
  • __sleep()
  • __wakeup()
  • __serialize()
  • __unserialize()


変数の型をセットする

  • ≪ serialize
  • strval ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の型をセットする

settype

(PHP 4, PHP 5, PHP 7, PHP 8)

settype — 変数の型をセットする

説明

settype(mixed &$var, string $type): bool

変数 var の型を type にセットします。

パラメータ

var

変換する変数。

type

type の値は以下の命令のいずれかです。

  • "boolean" または "bool"
  • "integer" または "int"
  • "float" または "double"
  • "string"
  • "array"
  • "object"
  • "null"

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 settype() の例

<?php
$foo = "5bar"; // string
$bar = true; // boolean

settype($foo, "integer"); // ここでは、$foo は 5です (整数)
settype($bar, "string"); // ここでは、$bar は "1" です (文字列)
?>

注意

注意:

"int" の最大値は PHP_INT_MAX です。

参考

  • gettype() - 変数の型を取得する
  • 型キャスト
  • 型の相互変換


変数の文字列としての値を取得する

  • ≪ settype
  • unserialize ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の文字列としての値を取得する

strval

(PHP 4, PHP 5, PHP 7, PHP 8)

strval — 変数の文字列としての値を取得する

説明

strval(mixed $value): string

value の string としての値を 返します。文字列への変換の詳細については、string の ドキュメントを参照ください。

この関数は、戻り値の書式設定は行いません。数値を文字列形式で書式設定したい場合は sprintf() あるいは number_format() を参照ください。

パラメータ

value

文字列に変換したい変数。

value には、任意のスカラー型、null および __toString() メソッドを実装した object を使うこともできます。 strval() は配列に対して使うことはできず、 __toString() メソッドを実装していないオブジェクトに対しても使うことはできません。

戻り値

value の文字列値を返します。

例

例1 マジックメソッド __toString() を使う strval() の例

<?php
class StrValTest
{
public function __toString()
{
return __CLASS__;
}
}

// 'StrValTest' と表示します
echo strval(new StrValTest);
?>

参考

  • boolval() - 変数の boolean としての値を取得する
  • floatval() - 変数の float 値を取得する
  • intval() - 変数の整数としての値を取得する
  • settype() - 変数の型をセットする
  • sprintf() - フォーマットされた文字列を返す
  • number_format() - 数字を千の位毎にグループ化してフォーマットする
  • 型の相互変換
  • __toString()


保存用表現から PHP の値を生成する

  • ≪ strval
  • unset ≫
  • PHP Manual
  • 変数操作 関数
  • 保存用表現から PHP の値を生成する

unserialize

(PHP 4, PHP 5, PHP 7, PHP 8)

unserialize — 保存用表現から PHP の値を生成する

説明

unserialize(string $data, array $options = []): mixed

unserialize() は、シリアル化された変数を PHP の値に戻す変換(アンシリアライズ)を行います。

警告

allowed_classes の options の値にかかわらず、 ユーザーからの入力をそのまま unserialize() に渡してはいけません。 アンシリアライズの時には、オブジェクトのインスタンス生成やオートローディングなどで コードが実行されることがあり、悪意のあるユーザーがこれを悪用するかもしれないからです。 シリアル化したデータをユーザーに渡す必要がある場合は、安全で標準的なデータ交換フォーマットである JSON などを使うようにしましょう。 json_decode() および json_encode() を利用します。

外部に保存されているシリアル化されたデータをアンシリアライズする必要がある場合は、 hash_hmac() を使ったデータの検証を検討しましょう。 他者によるデータの改ざんがないことを確かめるためです。

パラメータ

data

シリアル化された文字列。

もしアンシリアライズする変数がオブジェクトの場合、 オブジェクトが無事再作成された後、PHP は自動的にメンバ関数 __unserialize() または __wakeup() (存在していれば) をコールしようとします。

注意: unserialize_callback_func ディレクティブ

コールバック関数を設定することが可能です。(不完全な object __PHP_Incomplete_Class を得ることを防ぐため) コールバック関数は、非シリアル化する際に未定義のクラスをインスタ ンス化する必要がある場合にコールされます。 'unserialize_callback_func'を定義するためには、 php.ini, ini_set(), .htaccess を使用し てください。未定義のクラスをインスタンス化する度に、コールバック関 数がコールされます。この機能を無効とするには、 単純にこの設定を空にしてください。

options

unserialize() に連想配列で渡すオプション。

有効なオプション
名前 | 型 | 説明
allowed_classes | mixed | 受け付けるクラス名の配列を指定します。あらゆるクラスを拒否する場合は false、あらゆるクラスを受け付ける場合は true を指定します。 このオプションを指定しているときに、もし unserialize() が受け付け対象外のクラスのオブジェクトに遭遇すると、 そのオブジェクトを __PHP_Incomplete_Class のインスタンスに変換します。 このオプションを省略すると、true を指定したのと同じ意味になります。 つまり、PHP はあらゆるクラスのオブジェクトをインスタンス化しようとします。
max_depth | int | アンシリアライズ処理の間に許される、 データ構造の再帰の深さの最大値を設定します。 これは、スタックオーバーフローを防ぐためのものです。 デフォルトの深さの最大値は 4096 であり、 0 に設定すると、 この制限を無効にすることができます。

戻り値

変換された値が返されます。その値は、 bool, int, float, string, array, object のいずれかとなります。

渡された文字列が復元できなかった場合、false を返して E_WARNING を発生します。

エラー / 例外

オブジェクトは、 アンシリアライズを実行するハンドラで Throwable をスローしても構いません。

変更履歴

バージョン | 説明
8.3.0 | 渡された文字列が復元できない場合、 E_WARNING が発生するようになりました。 これより前のバージョンでは、E_NOTICE が発生していました。
7.4.0 | options に max_depth が追加されました。 これは、アンシリアライズ処理の間に許される、 データ構造の再帰の深さの最大値を設定するものです。
7.1.0 | options の allowed_classes 要素は、 型を厳密に調べるようになりました。 つまり、array または bool 以外の型が与えられると、 unserialize() 関数は false を返し、 E_WARNING レベルの警告を発生させます。

例

例1 unserialize() の例

<?php
// ここで、データベースから $session_data にセッションデータをロード
// するために unserialize() を使用します。
// この例は、serialize() で記述された例を補足するものです。

$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array($_SERVER['PHP_AUTH_USER']);
if (!odbc_execute($stmt, $sqldata) || !odbc_fetch_into($stmt, $tmp)) {
// 実行または取得が失敗した場合、空の配列で初期化します
$session_data = array();
} else {
// tmp[0] にシリアル化されたデータを保持している必要があります。
$session_data = unserialize($tmp[0]);
if (!is_array($session_data)) {
// 何か問題があったため、空の配列で初期化します。
$session_data = array();
}
}
?>

例2 unserialize_callback_func の例

<?php
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';

ini_set('unserialize_callback_func', 'mycallback'); // 独自のコールバック関数を設定する

function mycallback($classname)
{
// クラスが定義されているファイルをインクルードするだけです。
// どのクラス定義が必要になるのかを $classname で判断します。
}
?>

注意

警告

エラーやシリアライズされた false 値をアンシリアライズする場合、 false が返されます。この特殊なケースは data を serialize(false) で比較する、もしくは E_NOTICE をキャッチすることで区別することができます。

参考

  • json_encode() - 値を JSON 形式にして返す
  • json_decode() - JSON 文字列をデコードする
  • hash_hmac() - HMAC 方式を使用してハッシュ値を生成する
  • serialize() - 値の保存可能な表現を生成する
  • クラスのオートローディング
  • unserialize_callback_func
  • unserialize_max_depth
  • __wakeup()
  • __serialize()
  • __unserialize()


指定した変数の割当を解除する

  • ≪ unserialize
  • var_dump ≫
  • PHP Manual
  • 変数操作 関数
  • 指定した変数の割当を解除する

unset

(PHP 4, PHP 5, PHP 7, PHP 8)

unset — 指定した変数の割当を解除する

説明

unset(mixed $var, mixed ...$vars): void

unset() は指定した変数を破棄します。

関数 unset() の内部動作は、 破棄しようとする変数の型に依存します。

あるグローバル変数が関数の中で unset() された場合、ローカル変数のみが破棄されます。呼出側の環境にある変数は、 unset() がコールされる前と同じ値を保持します。

<?php
function destroy_foo()
{
global $foo;
unset($foo);
}

$foo = 'bar';
destroy_foo();
echo $foo;
?>

上の例の出力は以下となります。

bar

グローバル変数を関数の内部で unset() するには、 $GLOBALS 配列を使います。

<?php
function foo()
{
unset($GLOBALS['bar']);
}

$bar = "something";
foo();
?>

参照渡しされた変数が関数内で unset() された場合に、 ローカル変数のみが破棄されます。呼出側の環境でその変数は、 unset() がコールされる前と同じ値を保持します。

<?php
function foo(&$bar)
{
unset($bar);
$bar = "blah";
}

$bar = 'something';
echo "$bar\n";

foo($bar);
echo "$bar\n";
?>

上の例の出力は以下となります。

something
something

static変数が関数の内部で unset() された場合、 unset() は、その関数の残りのコンテキスト内においてのみ 変数を破棄します。関数を再度コールすると、破棄する前の値が復元されます。

<?php
function foo()
{
static $bar;
$bar++;
echo "Before unset: $bar, ";
unset($bar);
$bar = 23;
echo "after unset: $bar\n";
}

foo();
foo();
foo();
?>

上の例の出力は以下となります。

Before unset: 1, after unset: 23
Before unset: 2, after unset: 23
Before unset: 3, after unset: 23

パラメータ

var

破棄する変数。

vars

別の変数。

戻り値

値を返しません。

例

例1 unset() の例

<?php
// 変数を一つ破棄する
unset($foo);

// 配列の要素の一つを破棄する
unset($bar['quux']);

// 複数の変数を破棄する
unset($foo1, $foo2, $foo3);
?>

例2 (unset) によるキャスト

(unset) によるキャストは unset() 関数と混同されがちです。 (unset) によるキャストは、 単に NULL 型へのキャストを徹底するだけであり、 キャストした変数の値を書き換えるわけではありません。 (unset) によるキャストは、PHP 7.2.0 で非推奨になり、 PHP 8.0.0 で削除されました。

<?php
$name = 'Felipe';

var_dump((unset) $name);
var_dump($name);
?>

上の例の出力は以下となります。

NULL
string(6) "Felipe"

注意

注意: これは、関数ではなく 言語構造のため、可変関数 や 名前付き引数 を用いてコールすることはできません。

注意:

現在のコンテキストで見えるものであれば、 オブジェクトのプロパティも破棄することが可能です。

破棄されたプロパティにアクセスする場合、 もし宣言されていれば __get() がコールされます。 破棄されたプロパティに値を設定を設定する場合、 もし宣言されていれば __set() がコールされます。

注意:

オブジェクトのメソッド内で $this を破棄することはできません。

注意:

オブジェクトのアクセス不能なプロパティに対して unset() を使用した場合は、もしオーバーロードメソッド __unset() が宣言されていればそれをコールします。

参考

  • isset() - 変数が宣言されていること、そして null とは異なることを検査する
  • empty() - 変数が空であるかどうかを検査する
  • __unset()
  • array_splice() - 配列の一部を削除し、他の要素で置換する
  • (unset) casting


変数に関する情報をダンプする

  • ≪ unset
  • var_export ≫
  • PHP Manual
  • 変数操作 関数
  • 変数に関する情報をダンプする

var_dump

(PHP 4, PHP 5, PHP 7, PHP 8)

var_dump — 変数に関する情報をダンプする

説明

var_dump(mixed $value, mixed ...$values): void

この関数は、指定した式に関してその型や値を含む構造化された情報を 返します。配列の場合、その構造を表示するために各値について再帰的に 探索されます。

オブジェクトのすべての public、private および protected なプロパティが出力されます。ただし、そのオブジェクトが __debugInfo() メソッド を実装している場合は、その限りではありません。

ヒント

ブラウザに直接結果を出力する すべてのものと同様に、出力制御関数 を使用してこの関数の出力をキャプチャーし、(例えば)文字列 (string)に保存することが可能です。

パラメータ

value

ダンプしたい変数。

values

ダンプしたい追加の変数。

戻り値

値を返しません。

例

例1 var_dump() の例

<?php
$a = array(1, 2, array("a", "b", "c"));
var_dump($a);
?>

上の例の出力は以下となります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  array(3) {
    [0]=>
    string(1) "a"
    [1]=>
    string(1) "b"
    [2]=>
    string(1) "c"
  }
}
<?php

$b = 3.1;
$c = true;
var_dump($b, $c);

?>

上の例の出力は以下となります。

float(3.1)
bool(true)

参考

  • print_r() - 指定した変数に関する情報を解りやすく出力する
  • debug_zval_dump() - 内部的な zval を表す文字列をダンプする
  • var_export() - 変数の文字列表現を出力または返す
  • __debugInfo()


変数の文字列表現を出力または返す

  • ≪ var_dump
  • ウェブサービス ≫
  • PHP Manual
  • 変数操作 関数
  • 変数の文字列表現を出力または返す

var_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

var_export — 変数の文字列表現を出力または返す

説明

var_export(mixed $value, bool $return = false): ?string

var_export() は、 渡された変数に関する構造化された情報を返します。この関数は var_dump() に似ていますが、 返される表現が有効な PHP コードであるところが異なります。

パラメータ

value

エクスポートしたい変数

return

使用されかつ true に設定された場合、var_export() は変数表現を出力する代わりに返します。

戻り値

return パラメータが使用され true と評価される場合、 変数表現を返します。そうでない場合、この関数は null を返します。

変更履歴

バージョン | 説明
8.2.0 | クラス名をエクスポートする場合、そのクラス名は完全修飾名になりました。 これより前のバージョンでは、先頭のバックスラッシュが省略されていました。
7.3.0 | stdClass オブジェクトは、 存在しないメソッド stdClass::__setState() を使わず、 配列をオブジェクトにキャストした形 ((object) array( ... )) でエクスポートされるようになりました。 この変更によって、stdClass がエクスポート可能になり、 このバージョンより前の PHP でもエクスポートした結果が動くようになりました。

例

例1 var_export() の例

<?php
$a = array (1, 2, array ("a", "b", "c"));
var_export($a);
?>

上の例の出力は以下となります。

array (
  0 => 1,
  1 => 2,
  2 =>
  array (
    0 => 'a',
    1 => 'b',
    2 => 'c',
  ),
)
<?php

$b = 3.1;
$v = var_export($b, true);
echo $v;

?>

上の例の出力は以下となります。

3.1

例2 PHP 7.3.0 以降で stdClass をエクスポートする

<?php
$person = new stdClass;
$person->name = 'ElePHPant ElePHPantsdotter';
$person->website = 'https://php.net/elephpant.php';

var_export($person);

上の例の出力は以下となります。

(object) array(
   'name' => 'ElePHPant ElePHPantsdotter',
   'website' => 'https://php.net/elephpant.php',
)

例3 クラスのエクスポート

<?php
class A { public $var; }
$a = new A;
$a->var = 5;
var_export($a);
?>

上の例の出力は以下となります。

A::__set_state(array(
   'var' => 5,
))

例4 __set_state() の使用法

<?php
class A
{
public $var1;
public $var2;

public static function __set_state($an_array)
{
$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"
}

注意

注意:

リソース型 の変数は、 この関数ではエクスポートする事ができません。

注意:

var_export() では循環参照を扱うことができません。 循環参照を表す解析可能な PHP コードを生成することは、不可能に近いからです。 配列やオブジェクトを完全な形式で扱いたい場合は serialize() を使用してください。

警告

PHP 8.2.0 より前のバージョンでは、var_export() でオブジェクトをエクスポートするときに、 名前空間を指定したクラスの名前の先頭にあるバックスラッシュは含めませんでした。これは互換性を高めるためでした。

注意:

var_export() が生成する PHP を評価できるようにするためには、 処理対象のすべてのオブジェクトがマジックメソッド __set_state を実装している必要があります。 これの唯一の例外は stdClass です。 stdClass は、配列をオブジェクトにキャストした形でエクスポートされます。

参考

  • print_r() - 指定した変数に関する情報を解りやすく出力する
  • serialize() - 値の保存可能な表現を生成する
  • var_dump() - 変数に関する情報をダンプする


ウェブサービス

  • OAuth
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • OAuth 関数
    • OAuth — OAuth クラス
    • OAuthProvider — OAuthProvider クラス
    • OAuthException — OAuthException クラス
  • SOAP
    • はじめに
    • インストール/設定
    • 定義済み定数
    • SOAP 関数
    • SoapClient — SoapClient クラス
    • SoapServer — SoapServer クラス
    • SoapFault — SoapFault クラス
    • SoapHeader — SoapHeader クラス
    • SoapParam — SoapParam クラス
    • SoapVar — SoapVar クラス
  • Yar — Yet Another RPC Framework
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • Yar_Server — The Yar_Server class
    • Yar_Client — The Yar_Client class
    • Yar_Concurrent_Client — The Yar_Concurrent_Client class
    • Yar_Server_Exception — The Yar_Server_Exception class
    • Yar_Client_Exception — The Yar_Client_Exception class
  • XML-RPC
    • はじめに
    • インストール/設定
    • XML-RPC 関数


OAuth

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
    • 米Yahoo! の位置情報プラットフォーム FireEagle の例
  • OAuth 関数
    • oauth_get_sbs — SBSを生成する
    • oauth_urlencode — URI を RFC 3686 形式でエンコードする
  • OAuth — OAuth クラス
    • OAuth::__construct — 新しい OAuth オブジェクトを作成する
    • OAuth::__destruct — デストラクタ
    • OAuth::disableDebug — デバッグを無効にする
    • OAuth::disableRedirects — リダイレクトを無効にする
    • OAuth::disableSSLChecks — SSL チェックを無効にする
    • OAuth::enableDebug — デバッグを有効にする
    • OAuth::enableRedirects — リダイレクトを有効にする
    • OAuth::enableSSLChecks — SSL チェックを有効にする
    • OAuth::fetch — OAuth で保護されたリソースを取得する
    • OAuth::generateSignature — シグネチャを生成する
    • OAuth::getAccessToken — アクセストークンを取得する
    • OAuth::getCAPath — CA 情報を取得する
    • OAuth::getLastResponse — 直近のレスポンスを取得する
    • OAuth::getLastResponseHeaders — 最後のレスポンスのヘッダを取得する
    • OAuth::getLastResponseInfo — 直近のレスポンスの HTTP 情報を取得する
    • OAuth::getRequestHeader — OAuth ヘッダ文字列シグネチャを生成する
    • OAuth::getRequestToken — リクエストトークンを取得する
    • OAuth::setAuthType — 認証方式を設定する
    • OAuth::setCAPath — CA パスおよび情報を設定する
    • OAuth::setNonce — 続くリクエスト用のノンスを設定する
    • OAuth::setRequestEngine — setRequestEngine
    • OAuth::setRSACertificate — RSA 証明書を設定する
    • OAuth::setSSLChecks — リクエストに固有の SSL チェックを調整する
    • OAuth::setTimestamp — タイムスタンプを設定する
    • OAuth::setToken — トークンと secret を設定する
    • OAuth::setVersion — OAuth のバージョンを設定する
  • OAuthProvider — OAuthProvider クラス
    • OAuthProvider::addRequiredParameter — 必須パラメータを追加する
    • OAuthProvider::callconsumerHandler — consumerNonceHandler コールバックをコールする
    • OAuthProvider::callTimestampNonceHandler — timestampNonceHandler コールバックをコールする
    • OAuthProvider::calltokenHandler — tokenNonceHandler コールバックをコールする
    • OAuthProvider::checkOAuthRequest — oauth リクエストをチェックする
    • OAuthProvider::__construct — 新しい OAuthProvider オブジェクトを作る
    • OAuthProvider::consumerHandler — consumerHandler コールバックを設定する
    • OAuthProvider::generateToken — ランダムなトークンを生成する
    • OAuthProvider::is2LeggedEndpoint — is2LeggedEndpoint
    • OAuthProvider::isRequestTokenEndpoint — isRequestTokenEndpoint を設定する
    • OAuthProvider::removeRequiredParameter — 必須パラメータを削除する
    • OAuthProvider::reportProblem — 問題を報告する
    • OAuthProvider::setParam — パラメータを設定する
    • OAuthProvider::setRequestTokenPath — リクエストトークンのパスを設定する
    • OAuthProvider::timestampNonceHandler — timestampNonceHandler コールバックを設定する
    • OAuthProvider::tokenHandler — tokenHandler コールバックを設定する
  • OAuthException — OAuthException クラス


はじめに

この拡張モジュールは、OAuth 1.0a コンシューマおよびプロバイダの機能を提供します。 OAuth は HTTP 上に構築された認証プロトコルで、 アプリケーションからデータへのアクセスが安全にできるようになります。 アプリケーション側でユーザー名やパスワードを保存する必要はありません。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • OAuth
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

PECL/oauth には、PHP 5.1 以降と ext/hash、そして ext/pcre が必要です。

PECL/oauth は、ビルド時に選択した場合に、オプションで libcurl が必要な場合があります。 libcurl を含めてコンパイルする場合、libcurl を HTTPS サポート付きでビルドしなければいけません。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pear.php.net/package/oauth


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

これらの定数の大半には何らかの問題があります。問題点については OAuth の公式ページにも » 問題一覧 があります。 ここで扱う定数名は PHP 固有のものですが、命名方式は似ています。

OAUTH_SIG_METHOD_RSASHA1 (string)
OAuth RSA-SHA1 署名方式。
OAUTH_SIG_METHOD_HMACSHA1 (string)

OAuth HMAC-SHA1 署名方式。

OAUTH_SIG_METHOD_HMACSHA256 (string)
OAuth HMAC-SHA256 署名方式。
OAUTH_AUTH_TYPE_AUTHORIZATION (string)

この定数は、OAuth パラメータを Authorization ヘッダ内に記述することを表します。

OAUTH_AUTH_TYPE_NONE (string)

この定数は、NoAuth OAuth リクエストを表します。

OAUTH_AUTH_TYPE_URI (string)

この定数は、OAuth パラメータをリクエスト URI に記述することを表します。

OAUTH_AUTH_TYPE_FORM (string)

この定数は、OAuth パラメータを HTTP POST の本文の一部として記述することを表します。

OAUTH_HTTP_METHOD_GET (string)

GET メソッドを OAuth リクエストで使用します。

OAUTH_HTTP_METHOD_POST (string)

POST メソッドを OAuth リクエストで使用します。

OAUTH_HTTP_METHOD_PUT (string)

PUT メソッドを OAuth リクエストで使用します。

OAUTH_HTTP_METHOD_HEAD (string)

HEAD メソッドを OAuth リクエストで使用します。

OAUTH_HTTP_METHOD_DELETE (string)
DELETE メソッドを OAuth リクエストで使用します。
OAUTH_REQENGINE_STREAMS (int)
OAuth::setRequestEngine() で使用するもので、 エンジンを PHP ストリーム に設定します。 Curl を使う場合は OAUTH_REQENGINE_CURL を用います。
OAUTH_REQENGINE_CURL (int)
OAuth::setRequestEngine() で使用するもので、 エンジンを Curl に設定します。 PHP streams を使う場合は OAUTH_REQENGINE_STREAMS を用います。
OAUTH_OK (int)
無事に生きています。
OAUTH_BAD_NONCE (int)
oauth_nonce の値が前のリクエストで使われたものなので、 このリクエストでは使えません。
OAUTH_BAD_TIMESTAMP (int)
oauth_timestamp の値がサービスプロバイダに受け入れられませんでした。 この場合、レスポンスには oauth_acceptable_timestamps パラメータが含まれていなければなりません。
OAUTH_CONSUMER_KEY_UNKNOWN (int)
oauth_consumer_key が、一時的にサービスプロバイダに受け入れられませんでした。 プロバイダ側でコンシューマに制限をかけているなどの可能性が考えられます。
OAUTH_CONSUMER_KEY_REFUSED (int)
コンシューマキーが拒否されました。
OAUTH_INVALID_SIGNATURE (int)
oauth_signature が無効です。 サービスプロバイダが算出したシグネチャとマッチしません。
OAUTH_TOKEN_USED (int)
oauth_token が使用済みです。 これまでのリクエストで既に使用済みであるため、もう使うことはできません。
OAUTH_TOKEN_EXPIRED (int)
oauth_token の有効期限が切れました。
OAUTH_TOKEN_REVOKED (int)
oauth_token が無効になりました。もう使えません。
OAUTH_TOKEN_REJECTED (int)
oauth_token がサービスプロバイダに受け入れられませんでした。 理由は不明ですが、 トークンが発行されていない・すでに使用済みである・プロバイダ側で忘れられてしまった といった原因が考えられます。
OAUTH_VERIFIER_INVALID (int)
oauth_verifier が無効です。
OAUTH_PARAMETER_ABSENT (int)
必須パラメータが含まれていません。 この場合、レスポンスには oauth_parameters_absent パラメータが含まれていなければなりません。
OAUTH_SIGNATURE_METHOD_REJECTED (int)
oauth_signature_method がサービスプロバイダに受け入れられませんでした。


  • ≪ 定義済み定数
  • 米Yahoo! の位置情報プラットフォーム FireEagle の例 ≫
  • PHP Manual
  • OAuth
  • 例

例

目次

  • 米Yahoo! の位置情報プラットフォーム FireEagle の例


米Yahoo! の位置情報プラットフォーム FireEagle の例

<?php
$req_url = 'https://fireeagle.yahooapis.com/oauth/request_token';
$authurl = 'https://fireeagle.yahoo.net/oauth/authorize';
$acc_url = 'https://fireeagle.yahooapis.com/oauth/access_token';
$api_url = 'https://fireeagle.yahooapis.com/api/0.1';
$conskey = 'your_consumer_key';
$conssec = 'your_consumer_secret';

session_start();

// セッションの state の値が1の場合、次のリクエストには oauth_token の値が含まれているはずである
if(!isset($_GET['oauth_token']) && $_SESSION['state']==1) $_SESSION['state'] = 0;
try {
$oauth = new OAuth($conskey,$conssec,OAUTH_SIG_METHOD_HMACSHA1,OAUTH_AUTH_TYPE_URI);
$oauth->enableDebug();
if(!isset($_GET['oauth_token']) && !$_SESSION['state']) {
$request_token_info = $oauth->getRequestToken($req_url);
$_SESSION['secret'] = $request_token_info['oauth_token_secret'];
$_SESSION['state'] = 1;
header('Location: '.$authurl.'?oauth_token='.$request_token_info['oauth_token']);
exit;
} else if($_SESSION['state']==1) {
$oauth->setToken($_GET['oauth_token'],$_SESSION['secret']);
$access_token_info = $oauth->getAccessToken($acc_url);
$_SESSION['state'] = 2;
$_SESSION['token'] = $access_token_info['oauth_token'];
$_SESSION['secret'] = $access_token_info['oauth_token_secret'];
}
$oauth->setToken($_SESSION['token'],$_SESSION['secret']);
$oauth->fetch("$api_url/user.json");
$json = json_decode($oauth->getLastResponse());
print_r($json);
} catch(OAuthException $E) {
print_r($E);
}
?>


  • ≪ 米Yahoo! の位置情報プラットフォーム FireEagle の例
  • oauth_get_sbs ≫
  • PHP Manual
  • OAuth
  • OAuth 関数

OAuth 関数

目次

  • oauth_get_sbs — SBSを生成する
  • oauth_urlencode — URI を RFC 3686 形式でエンコードする


SBSを生成する

  • ≪ OAuth 関数
  • oauth_urlencode ≫
  • PHP Manual
  • OAuth 関数
  • SBSを生成する

oauth_get_sbs

(PECL OAuth >=0.99.7)

oauth_get_sbs — SBSを生成する

説明

oauth_get_sbs(string $http_method, string $uri, array $request_parameters = ?): string

pecl/oauth に関するSBSを生成します

パラメータ

http_method

HTTPメソッド

uri

エンコードするURI

request_parameters

リクエストパラメータの配列

戻り値

SBSを返します


URI を RFC 3686 形式でエンコードする

  • ≪ oauth_get_sbs
  • OAuth ≫
  • PHP Manual
  • OAuth 関数
  • URI を RFC 3686 形式でエンコードする

oauth_urlencode

(PECL OAuth >=0.99.2)

oauth_urlencode — URI を RFC 3686 形式でエンコードする

説明

oauth_urlencode(string $uri): string

URI を » RFC 3686 形式でエンコードします。

パラメータ

uri

エンコードしたい URI。

戻り値

» RFC 3686 形式でエンコードした文字列を返します。


OAuth クラス

(PECL OAuth >= 0.99.1)

はじめに

OAuth 拡張モジュールは、データプロバイダとやりとりするためのシンプルなインターフェイスを提供します。 OAuth HTTP 仕様を用いることで、プライベートなリソースを保護します。

クラス概要

class OAuth {
/* プロパティ */
public $debug;
public $sslChecks;
public $debugInfo;
/* メソッド */
public __construct(
string $consumer_key,
string $consumer_secret,
string $signature_method = OAUTH_SIG_METHOD_HMACSHA1,
int $auth_type = 0
)
public __destruct(): void
public disableDebug(): bool
public disableRedirects(): bool
public disableSSLChecks(): bool
public enableDebug(): bool
public enableRedirects(): bool
public enableSSLChecks(): bool
public fetch(
string $protected_resource_url,
array $extra_parameters = ?,
string $http_method = ?,
array $http_headers = ?
): mixed
public generateSignature(string $http_method, string $url, mixed $extra_parameters = ?): string|false
public getAccessToken(string $access_token_url, string $verifier_token = ?, string $http_method = ?): array
public getCAPath(): array
public getLastResponse(): string
public getLastResponseHeaders(): string|false
public getLastResponseInfo(): array
public getRequestHeader(string $http_method, string $url, mixed $extra_parameters = ?): string|false
public getRequestToken(string $request_token_url, string $callback_url = ?, string $http_method = ?): array
public setAuthType(int $auth_type): bool
public setCAPath(string $ca_path = ?, string $ca_info = ?): mixed
public setNonce(string $nonce): mixed
public setRequestEngine(int $reqengine): void
public setRSACertificate(string $cert): mixed
public setSSLChecks(int $sslcheck): bool
public setTimestamp(string $timestamp): mixed
public setToken(string $token, string $token_secret): bool
public setVersion(string $version): bool
}

プロパティ

debug

sslChecks

debugInfo

目次

  • OAuth::__construct — 新しい OAuth オブジェクトを作成する
  • OAuth::__destruct — デストラクタ
  • OAuth::disableDebug — デバッグを無効にする
  • OAuth::disableRedirects — リダイレクトを無効にする
  • OAuth::disableSSLChecks — SSL チェックを無効にする
  • OAuth::enableDebug — デバッグを有効にする
  • OAuth::enableRedirects — リダイレクトを有効にする
  • OAuth::enableSSLChecks — SSL チェックを有効にする
  • OAuth::fetch — OAuth で保護されたリソースを取得する
  • OAuth::generateSignature — シグネチャを生成する
  • OAuth::getAccessToken — アクセストークンを取得する
  • OAuth::getCAPath — CA 情報を取得する
  • OAuth::getLastResponse — 直近のレスポンスを取得する
  • OAuth::getLastResponseHeaders — 最後のレスポンスのヘッダを取得する
  • OAuth::getLastResponseInfo — 直近のレスポンスの HTTP 情報を取得する
  • OAuth::getRequestHeader — OAuth ヘッダ文字列シグネチャを生成する
  • OAuth::getRequestToken — リクエストトークンを取得する
  • OAuth::setAuthType — 認証方式を設定する
  • OAuth::setCAPath — CA パスおよび情報を設定する
  • OAuth::setNonce — 続くリクエスト用のノンスを設定する
  • OAuth::setRequestEngine — setRequestEngine
  • OAuth::setRSACertificate — RSA 証明書を設定する
  • OAuth::setSSLChecks — リクエストに固有の SSL チェックを調整する
  • OAuth::setTimestamp — タイムスタンプを設定する
  • OAuth::setToken — トークンと secret を設定する
  • OAuth::setVersion — OAuth のバージョンを設定する


新しい OAuth オブジェクトを作成する

  • ≪ OAuth
  • OAuth::__destruct ≫
  • PHP Manual
  • OAuth
  • 新しい OAuth オブジェクトを作成する

OAuth::__construct

(PECL OAuth >= 0.99.1)

OAuth::__construct — 新しい OAuth オブジェクトを作成する

説明

public OAuth::__construct(
string $consumer_key,
string $consumer_secret,
string $signature_method = OAUTH_SIG_METHOD_HMACSHA1,
int $auth_type = 0
)

新しい OAuth オブジェクトを作成します。

パラメータ

consumer_key

サービスプロバイダが提供する consumer key。

consumer_secret

サービスプロバイダが提供する consumer secret。

signature_method

このオプションのパラメータで、使用する署名方式を定義します。 デフォルトは OAUTH_SIG_METHOD_HMACSHA1 (HMAC-SHA1) です。

auth_type

このオプションのパラメータで、OAuth パラメータをコンシューマに渡す方法を定義します。 デフォルトは OAUTH_AUTH_TYPE_AUTHORIZATION (Authorization ヘッダを使用する) です。


デストラクタ

  • ≪ OAuth::__construct
  • OAuth::disableDebug ≫
  • PHP Manual
  • OAuth
  • デストラクタ

OAuth::__destruct

(PECL OAuth >= 0.99.9)

OAuth::__destruct — デストラクタ

説明

public OAuth::__destruct(): void

デストラクタです。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • OAuth::__construct() - 新しい OAuth オブジェクトを作成する


デバッグを無効にする

  • ≪ OAuth::__destruct
  • OAuth::disableRedirects ≫
  • PHP Manual
  • OAuth
  • デバッグを無効にする

OAuth::disableDebug

(PECL OAuth >= 0.99.3)

OAuth::disableDebug — デバッグを無効にする

説明

public OAuth::disableDebug(): bool

冗長なリクエスト情報を無効にします (デフォルトは無効です)。 あるいは、debug プロパティに false を設定することによってもデバッグを無効にできます。

パラメータ

この関数にはパラメータはありません。

戻り値

true

変更履歴

バージョン | 説明
PECL oauth 0.99.8 | debug プロパティが追加されました。

参考

  • OAuth::enableDebug() - デバッグを有効にする


リダイレクトを無効にする

  • ≪ OAuth::disableDebug
  • OAuth::disableSSLChecks ≫
  • PHP Manual
  • OAuth
  • リダイレクトを無効にする

OAuth::disableRedirects

(PECL OAuth >= 0.99.9)

OAuth::disableRedirects — リダイレクトを無効にする

説明

public OAuth::disableRedirects(): bool

リダイレクト先を自動的にたどる機能を無効にし、リクエストを手動でリダイレクトできるようにします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

true

参考

  • OAuth::enableRedirects() - リダイレクトを有効にする


SSL チェックを無効にする

  • ≪ OAuth::disableRedirects
  • OAuth::enableDebug ≫
  • PHP Manual
  • OAuth
  • SSL チェックを無効にする

OAuth::disableSSLChecks

(PECL OAuth >= 0.99.5)

OAuth::disableSSLChecks — SSL チェックを無効にする

説明

public OAuth::disableSSLChecks(): bool

通常の SSL ピア証明書およびホストのチェックを無効にします。 これは実運用に使うものではありません。 あるいは、sslChecks メンバーに false を設定することによっても SSL チェックを無効にできます。

パラメータ

この関数にはパラメータはありません。

戻り値

true

変更履歴

バージョン | 説明
PECL oauth 0.99.8 | sslChecks メンバーが追加されました。

参考

  • OAuth::enableSSLChecks() - SSL チェックを有効にする


デバッグを有効にする

  • ≪ OAuth::disableSSLChecks
  • OAuth::enableRedirects ≫
  • PHP Manual
  • OAuth
  • デバッグを有効にする

OAuth::enableDebug

(PECL OAuth >= 0.99.3)

OAuth::enableDebug — デバッグを有効にする

説明

public OAuth::enableDebug(): bool

デバッグに使用できる、冗長なリクエスト情報の出力を有効にします。 デバッグ情報は debugInfo メンバーに格納されます。 あるいは、debug メンバーに false 以外の値を設定することによってもデバッグを有効にできます。

パラメータ

この関数にはパラメータはありません。

戻り値

true

変更履歴

バージョン | 説明
PECL oauth 0.99.8 | debug および debugInfo メンバーが追加されました。

参考

  • OAuth::disableDebug() - デバッグを無効にする


リダイレクトを有効にする

  • ≪ OAuth::enableDebug
  • OAuth::enableSSLChecks ≫
  • PHP Manual
  • OAuth
  • リダイレクトを有効にする

OAuth::enableRedirects

(PECL OAuth >= 0.99.9)

OAuth::enableRedirects — リダイレクトを有効にする

説明

public OAuth::enableRedirects(): bool

自動的にリダイレクトをたどりまず。デフォルトで有効となっています。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

true

参考

  • OAuth::disableRedirects() - リダイレクトを無効にする


SSL チェックを有効にする

  • ≪ OAuth::enableRedirects
  • OAuth::fetch ≫
  • PHP Manual
  • OAuth
  • SSL チェックを有効にする

OAuth::enableSSLChecks

(PECL OAuth >= 0.99.5)

OAuth::enableSSLChecks — SSL チェックを有効にする

説明

public OAuth::enableSSLChecks(): bool

通常の SSL ピア証明書およびホストのチェックを有効にします (デフォルトは有効です)。 あるいは、sslChecks メンバーに false 以外の値を設定することによっても SSL チェックを有効にできます。

パラメータ

この関数にはパラメータはありません。

戻り値

true

変更履歴

バージョン | 説明
PECL oauth 0.99.8 | sslChecks メンバーが追加されました。

参考

  • OAuth::disableSSLChecks() - SSL チェックを無効にする


OAuth で保護されたリソースを取得する

  • ≪ OAuth::enableSSLChecks
  • OAuth::generateSignature ≫
  • PHP Manual
  • OAuth
  • OAuth で保護されたリソースを取得する

OAuth::fetch

(PECL OAuth >= 0.99.1)

OAuth::fetch — OAuth で保護されたリソースを取得する

説明

public OAuth::fetch(
string $protected_resource_url,
array $extra_parameters = ?,
string $http_method = ?,
array $http_headers = ?
): mixed

リソースを取得します。

パラメータ

protected_resource_url

OAuth で保護されたリソースへの URL。

extra_parameters

リソースへのリクエストとともに送信する追加パラメータ。

http_method

OAUTH_HTTP_METHOD_* OAUTH 定数 のいずれか。 GET、POST、PUT、HEAD そして DELETE があります。

HEAD (OAUTH_HTTP_METHOD_HEAD) は、 実際のリクエストの前に (OAuth 認証情報が Authorization ヘッダにあるかどうかなどの) 情報を取得するときに有用です。

http_headers

HTTP クライアントヘッダ (User-Agent や Accept など)。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。
PECL oauth 0.99.5 | http_method パラメータが追加されました。
PECL oauth 0.99.8 | http_headers パラメータが追加されました。

例

例1 OAuth::fetch() の例

<?php
try {
$oauth = new OAuth("consumer_key","consumer_secret",OAUTH_SIG_METHOD_HMACSHA1,OAUTH_AUTH_TYPE_AUTHORIZATION);
$oauth->setToken("access_token","access_token_secret");

$oauth->fetch("http://photos.example.net/photo?file=vacation.jpg");

$response_info = $oauth->getLastResponseInfo();
header("Content-Type: {$response_info["content_type"]}");
echo $oauth->getLastResponse();
} catch(OAuthException $E) {
echo "Exception caught!\n";
echo "Response: ". $E->lastResponse . "\n";
}
?>

参考

  • OAuth::getLastResponse() - 直近のレスポンスを取得する
  • OAuth::getLastResponseInfo() - 直近のレスポンスの HTTP 情報を取得する
  • OAuth::setToken() - トークンと secret を設定する


シグネチャを生成する

  • ≪ OAuth::fetch
  • OAuth::getAccessToken ≫
  • PHP Manual
  • OAuth
  • シグネチャを生成する

OAuth::generateSignature

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

OAuth::generateSignature — シグネチャを生成する

説明

public OAuth::generateSignature(string $http_method, string $url, mixed $extra_parameters = ?): string|false

最後の HTTP メソッド、URL そしてパラメータ文字列あるいは配列にもとづいてシグネチャを生成します。

パラメータ

http_method

リクエストの HTTP メソッド。

url

リクエストの URL。

extra_parameters

パラメータ文字列あるいは配列。

戻り値

生成されたシグネチャを文字列で返します。失敗した場合に false を返します


アクセストークンを取得する

  • ≪ OAuth::generateSignature
  • OAuth::getCAPath ≫
  • PHP Manual
  • OAuth
  • アクセストークンを取得する

OAuth::getAccessToken

(PECL OAuth >= 0.99.1)

OAuth::getAccessToken — アクセストークンを取得する

説明

public OAuth::getAccessToken(string $access_token_url, string $verifier_token = ?, string $http_method = ?): array

アクセストークン、secret そして追加のレスポンスパラメータをサービスプロバイダから取得します。

パラメータ

access_token_url

アクセストークン API の URL。

auth_session_handle

認証セッションハンドル。このパラメータはコア OAuth 1.0 仕様を引用していませんが、大手プロバイダでは実装されているでしょう。 詳細な情報は » ScalableOAuth を参照ください。

verifier_token

1.0a をサポートするサービスプロバイダでは、リクエストトークンとアクセストークンを交換する際に verifier_token を渡す必要があります。 verifier_token が $_GET あるいは $_POST に存在する場合は自動的にそれが渡され、 呼び出し側が verifier_token を指定する必要はありません (通常、アクセストークンを oauth_callback URL で交換する場合はこのようになります)。 詳細な情報は » ScalableOAuth を参照ください。

http_method

利用する HTTP メソッド。GET や POST など。

戻り値

成功した場合は OAuth レスポンスをパースした配列、失敗した場合は false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。
PECL oauth 0.99.9 | verifier_token パラメータが追加されました。

例

例1 OAuth::getAccessToken() の例

<?php
try {
$oauth = new OAuth(OAUTH_CONSUMER_KEY,OAUTH_CONSUMER_SECRET);
$oauth->setToken($request_token,$request_token_secret);
$access_token_info = $oauth->getAccessToken("https://example.com/oauth/access_token");
if(!empty($access_token_info)) {
print_r($access_token_info);
} else {
print "Failed fetching access token, response was: " . $oauth->getLastResponse();
}
} catch(OAuthException $E) {
echo "Response: ". $E->lastResponse . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [oauth_token] => some_token
    [oauth_token_secret] => some_token_secret
)

参考

  • OAuth::getLastResponse() - 直近のレスポンスを取得する
  • OAuth::getLastResponseInfo() - 直近のレスポンスの HTTP 情報を取得する
  • OAuth::setToken() - トークンと secret を設定する


CA 情報を取得する

  • ≪ OAuth::getAccessToken
  • OAuth::getLastResponse ≫
  • PHP Manual
  • OAuth
  • CA 情報を取得する

OAuth::getCAPath

(PECL OAuth >= 0.99.8)

OAuth::getCAPath — CA 情報を取得する

説明

public OAuth::getCAPath(): array

認証局の情報を取得します。ここには、 OAuth::setCaPath() で設定した ca_path や ca_info が含まれます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

認証局の情報を含む配列を返します。返される連想配列のキーには ca_path と ca_info が含まれます。

参考

  • OAuth::setCAPath() - CA パスおよび情報を設定する
  • OAuth::getLastResponseInfo() - 直近のレスポンスの HTTP 情報を取得する


直近のレスポンスを取得する

  • ≪ OAuth::getCAPath
  • OAuth::getLastResponseHeaders ≫
  • PHP Manual
  • OAuth
  • 直近のレスポンスを取得する

OAuth::getLastResponse

(PECL OAuth >= 0.99.1)

OAuth::getLastResponse — 直近のレスポンスを取得する

説明

public OAuth::getLastResponse(): string

直近のリクエストに対するレスポンスをそのままの形式で取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近のレスポンスを含む文字列を返します。

参考

  • OAuth::getLastResponseInfo() - 直近のレスポンスの HTTP 情報を取得する
  • OAuth::fetch() - OAuth で保護されたリソースを取得する


最後のレスポンスのヘッダを取得する

  • ≪ OAuth::getLastResponse
  • OAuth::getLastResponseInfo ≫
  • PHP Manual
  • OAuth
  • 最後のレスポンスのヘッダを取得する

OAuth::getLastResponseHeaders

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

OAuth::getLastResponseHeaders — 最後のレスポンスのヘッダを取得する

説明

public OAuth::getLastResponseHeaders(): string|false

最後のレスポンスのヘッダを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

最後のレスポンスのヘッダを文字列で返します。失敗した場合に false を返します


直近のレスポンスの HTTP 情報を取得する

  • ≪ OAuth::getLastResponseHeaders
  • OAuth::getRequestHeader ≫
  • PHP Manual
  • OAuth
  • 直近のレスポンスの HTTP 情報を取得する

OAuth::getLastResponseInfo

(PECL OAuth >= 0.99.1)

OAuth::getLastResponseInfo — 直近のレスポンスの HTTP 情報を取得する

説明

public OAuth::getLastResponseInfo(): array

直近のレスポンスに関する HTTP 情報を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直近のリクエストに対するレスポンスの情報を含む配列を返します。 curl_getinfo() の定数が使われます。

参考

  • OAuth::fetch() - OAuth で保護されたリソースを取得する
  • OAuth::getLastResponse() - 直近のレスポンスを取得する


OAuth ヘッダ文字列シグネチャを生成する

  • ≪ OAuth::getLastResponseInfo
  • OAuth::getRequestToken ≫
  • PHP Manual
  • OAuth
  • OAuth ヘッダ文字列シグネチャを生成する

OAuth::getRequestHeader

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

OAuth::getRequestHeader — OAuth ヘッダ文字列シグネチャを生成する

説明

public OAuth::getRequestHeader(string $http_method, string $url, mixed $extra_parameters = ?): string|false

最後の HTTP メソッド、URL そしてパラメータ文字列あるいは配列にもとづいて OAuth ヘッダ文字列シグネチャを生成します。

パラメータ

http_method

リクエストの HTTP メソッド。

url

リクエストの URL。

extra_parameters

パラメータ文字列あるいは配列。

戻り値

生成されたリクエストヘッダを文字列で返します。失敗した場合に false を返します


リクエストトークンを取得する

  • ≪ OAuth::getRequestHeader
  • OAuth::setAuthType ≫
  • PHP Manual
  • OAuth
  • リクエストトークンを取得する

OAuth::getRequestToken

(PECL OAuth >= 0.99.1)

OAuth::getRequestToken — リクエストトークンを取得する

説明

public OAuth::getRequestToken(string $request_token_url, string $callback_url = ?, string $http_method = ?): array

リクエストトークン、secret そして追加のレスポンスパラメータをサービスプロバイダから取得します。

パラメータ

request_token_url

リクエストトークン API の URL。

callback_url

OAuth コールバック URL。callback_url に空の値を渡すと、"oob" に設定されて OAuth 2009.1 advisory を指すことになります。

http_method

利用する HTTP メソッド。GET や POST など。

戻り値

成功した場合は OAuth レスポンスをパースした配列、失敗した場合は false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。
PECL oauth 0.99.9 | callback_url パラメータが追加されました。

例

例1 OAuth::getRequestToken() の例

<?php
try {
$oauth = new OAuth(OAUTH_CONSUMER_KEY,OAUTH_CONSUMER_SECRET);
$request_token_info = $oauth->getRequestToken("https://example.com/oauth/request_token");
if(!empty($request_token_info)) {
print_r($request_token_info);
} else {
print "Failed fetching request token, response was: " . $oauth->getLastResponse();
}
} catch(OAuthException $E) {
echo "Response: ". $E->lastResponse . "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [oauth_token] => some_token
    [oauth_token_secret] => some_token_secret
)

参考

  • OAuth::getLastResponse() - 直近のレスポンスを取得する
  • OAuth::getLastResponseInfo() - 直近のレスポンスの HTTP 情報を取得する


認証方式を設定する

  • ≪ OAuth::getRequestToken
  • OAuth::setCAPath ≫
  • PHP Manual
  • OAuth
  • 認証方式を設定する

OAuth::setAuthType

(PECL OAuth >= 0.99.1)

OAuth::setAuthType — 認証方式を設定する

説明

public OAuth::setAuthType(int $auth_type): bool

OAuth パラメータをどこで渡すかを設定します。

パラメータ

auth_type

auth_type は、次のフラグ (OAuth 1.0 section 5.2 において優先度の高い順) のいずれかです。

OAUTH_AUTH_TYPE_AUTHORIZATION
OAuth パラメータを HTTP Authorization ヘッダで渡します。
OAUTH_AUTH_TYPE_FORM
OAuth パラメータを HTTP POST リクエストの本文に追加します。
OAUTH_AUTH_TYPE_URI
OAuth パラメータをリクエスト URI に追加します。
OAUTH_AUTH_TYPE_NONE
何もなし。

戻り値

パラメータを正しく設定した場合に true を返します。 それ以外の場合 (無効な auth_type を渡した場合など) は false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。


CA パスおよび情報を設定する

  • ≪ OAuth::setAuthType
  • OAuth::setNonce ≫
  • PHP Manual
  • OAuth
  • CA パスおよび情報を設定する

OAuth::setCAPath

(PECL OAuth >= 0.99.8)

OAuth::setCAPath — CA パスおよび情報を設定する

説明

public OAuth::setCAPath(string $ca_path = ?, string $ca_info = ?): mixed

認証局 (CA) のパスと情報を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ca_path

設定したい CA パス。

ca_info

設定したい CA 情報。

戻り値

成功した場合に true を返します。ca_path あるいは ca_info が無効な形式の場合は false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。

参考

  • OAuth::getCaPath() - CA 情報を取得する


続くリクエスト用のノンスを設定する

  • ≪ OAuth::setCAPath
  • OAuth::setRequestEngine ≫
  • PHP Manual
  • OAuth
  • 続くリクエスト用のノンスを設定する

OAuth::setNonce

(PECL OAuth >= 0.99.1)

OAuth::setNonce — 続くリクエスト用のノンスを設定する

説明

public OAuth::setNonce(string $nonce): mixed

それ以降のすべてのリクエスト用のノンスを設定します。

パラメータ

nonce

oauth_nonce の値。

戻り値

成功した場合に true を返します。 nonce が無効な場合に false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。

参考

  • OAuth::setToken() - トークンと secret を設定する
  • OAuth::setAuthType() - 認証方式を設定する
  • OAuth::setVersion() - OAuth のバージョンを設定する


setRequestEngine

  • ≪ OAuth::setNonce
  • OAuth::setRSACertificate ≫
  • PHP Manual
  • OAuth
  • setRequestEngine

OAuth::setRequestEngine

(PECL OAuth >= 1.0.0)

OAuth::setRequestEngine — setRequestEngine

説明

public OAuth::setRequestEngine(int $reqengine): void

HTTP リクエストの送信に使うリクエストエンジンを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

reqengine

使いたいリクエストエンジン。OAUTH_REQENGINE_STREAMS は PHP のストリームを使い、OAUTH_REQENGINE_CURL は Curl を使います。

戻り値

値を返しません。

エラー / 例外

無効なリクエストエンジンを選んだ場合には OAuthException が発生します。

例

例1 OAuth::setRequestEngine() example

<?php
$consumer = new OAuth();

$consumer->setRequestEngine(OAUTH_REQENGINE_STREAMS);
?>

参考

  • Curl
  • PHP streams
  • OAuthException


RSA 証明書を設定する

  • ≪ OAuth::setRequestEngine
  • OAuth::setSSLChecks ≫
  • PHP Manual
  • OAuth
  • RSA 証明書を設定する

OAuth::setRSACertificate

(PECL OAuth >= 1.0.0)

OAuth::setRSACertificate — RSA 証明書を設定する

説明

public OAuth::setRSACertificate(string $cert): mixed

RSA 証明書を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

cert

RSA 証明書。

戻り値

成功した場合に true、失敗した場合 (RSA 証明書がパースできなかった場合はど) に false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。

例

例1 OAuth::setRsaCertificate() の例

<?php
$consume = new OAuth('1234', '', OAUTH_SIG_METHOD_RSASHA1);

$consume->setRSACertificate(file_get_contents('test.pem'));
?>

参考

  • OAuth::setCaPath() - CA パスおよび情報を設定する


リクエストに固有の SSL チェックを調整する

  • ≪ OAuth::setRSACertificate
  • OAuth::setTimestamp ≫
  • PHP Manual
  • OAuth
  • リクエストに固有の SSL チェックを調整する

OAuth::setSSLChecks

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

OAuth::setSSLChecks — リクエストに固有の SSL チェックを調整する

説明

public OAuth::setSSLChecks(int $sslcheck): bool

リクエストに固有の SSL チェックを調整します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

sslcheck

戻り値

成功した場合に true を、失敗した場合に false を返します。


タイムスタンプを設定する

  • ≪ OAuth::setSSLChecks
  • OAuth::setToken ≫
  • PHP Manual
  • OAuth
  • タイムスタンプを設定する

OAuth::setTimestamp

(PECL OAuth >= 1.0.0)

OAuth::setTimestamp — タイムスタンプを設定する

説明

public OAuth::setTimestamp(string $timestamp): mixed

それ以降のリクエスト用の OAuth タイムスタンプを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

timestamp

タイムスタンプ。

戻り値

true を返します。 timestamp が無効な形式の場合は false を返します。

変更履歴

バージョン | 説明
PECL oauth 1.0.0 | 以前は、失敗したときに false ではなく null を返していました。

参考

  • OAuth::setNonce() - 続くリクエスト用のノンスを設定する


トークンと secret を設定する

  • ≪ OAuth::setTimestamp
  • OAuth::setVersion ≫
  • PHP Manual
  • OAuth
  • トークンと secret を設定する

OAuth::setToken

(PECL OAuth >= 0.99.1)

OAuth::setToken — トークンと secret を設定する

説明

public OAuth::setToken(string $token, string $token_secret): bool

それ以降のリクエスト用のトークンと secret を設定します。

パラメータ

token

OAuth トークン。

token_secret

OAuth トークン secret。

戻り値

true

例

例1 OAuth::setToken() の例

<?php
$oauth = new OAuth(OAUTH_CONSUMER_KEY,OAUTH_CONSUMER_SECRET);
$oauth->setToken("token","token-secret");
?>


OAuth のバージョンを設定する

  • ≪ OAuth::setToken
  • OAuthProvider ≫
  • PHP Manual
  • OAuth
  • OAuth のバージョンを設定する

OAuth::setVersion

(PECL OAuth >= 0.99.1)

OAuth::setVersion — OAuth のバージョンを設定する

説明

public OAuth::setVersion(string $version): bool

それ以降のリクエスト用の OAuth のバージョンを設定します。

パラメータ

version

OAuth のバージョン。デフォルトは常に "1.0"。

戻り値

成功した場合に true を、失敗した場合に false を返します。


OAuthProvider クラス

(PECL OAuth >= 1.0.0)

はじめに

OAuth プロバイダを管理するクラスです。

別のサイトで公開されている詳細なチュートリアル » Writing an OAuth Provider Service には、このサービスを作成する方法がハンズオン形式で公開されています。 OAuth 拡張モジュールのソースの中には » OAuth プロバイダのサンプル もあります。

クラス概要

class OAuthProvider {
/* メソッド */
final public addRequiredParameter(string $req_params): bool
public callconsumerHandler(): void
public callTimestampNonceHandler(): void
public calltokenHandler(): void
public checkOAuthRequest(string $uri = ?, string $method = ?): void
public __construct(array $params_array = ?)
public consumerHandler(callable $callback_function): void
final public static generateToken(int $size, bool $strong = false): string
public is2LeggedEndpoint(mixed $params_array): void
public isRequestTokenEndpoint(bool $will_issue_request_token): void
final public removeRequiredParameter(string $req_params): bool
final public static reportProblem(string $oauthexception, bool $send_headers = true): string
final public setParam(string $param_key, mixed $param_val = ?): bool
final public setRequestTokenPath(string $path): bool
public timestampNonceHandler(callable $callback_function): void
public tokenHandler(callable $callback_function): void
}

目次

  • OAuthProvider::addRequiredParameter — 必須パラメータを追加する
  • OAuthProvider::callconsumerHandler — consumerNonceHandler コールバックをコールする
  • OAuthProvider::callTimestampNonceHandler — timestampNonceHandler コールバックをコールする
  • OAuthProvider::calltokenHandler — tokenNonceHandler コールバックをコールする
  • OAuthProvider::checkOAuthRequest — oauth リクエストをチェックする
  • OAuthProvider::__construct — 新しい OAuthProvider オブジェクトを作る
  • OAuthProvider::consumerHandler — consumerHandler コールバックを設定する
  • OAuthProvider::generateToken — ランダムなトークンを生成する
  • OAuthProvider::is2LeggedEndpoint — is2LeggedEndpoint
  • OAuthProvider::isRequestTokenEndpoint — isRequestTokenEndpoint を設定する
  • OAuthProvider::removeRequiredParameter — 必須パラメータを削除する
  • OAuthProvider::reportProblem — 問題を報告する
  • OAuthProvider::setParam — パラメータを設定する
  • OAuthProvider::setRequestTokenPath — リクエストトークンのパスを設定する
  • OAuthProvider::timestampNonceHandler — timestampNonceHandler コールバックを設定する
  • OAuthProvider::tokenHandler — tokenHandler コールバックを設定する


必須パラメータを追加する

  • ≪ OAuthProvider
  • OAuthProvider::callconsumerHandler ≫
  • PHP Manual
  • OAuthProvider
  • 必須パラメータを追加する

OAuthProvider::addRequiredParameter

(PECL OAuth >= 1.0.0)

OAuthProvider::addRequiredParameter — 必須パラメータを追加する

説明

final public OAuthProvider::addRequiredParameter(string $req_params): bool

oauth プロバイダの必須パラメータを追加します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

req_params

必須パラメータ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • OAuthProvider::removeRequiredParameter() - 必須パラメータを削除する


consumerNonceHandler コールバックをコールする

  • ≪ OAuthProvider::addRequiredParameter
  • OAuthProvider::callTimestampNonceHandler ≫
  • PHP Manual
  • OAuthProvider
  • consumerNonceHandler コールバックをコールする

OAuthProvider::callconsumerHandler

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

OAuthProvider::callconsumerHandler — consumerNonceHandler コールバックをコールする

説明

public OAuthProvider::callconsumerHandler(): void

コンシューマハンドラコールバックとして登録した関数をコールします。この関数は OAuthProvider::consumerHandler() で登録します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

コールバック関数をコールできなかったり、 あるいは定義されていなかったりした場合は E_ERROR レベルのエラーとなります。

参考

  • OAuthProvider::consumerHandler() - consumerHandler コールバックを設定する


timestampNonceHandler コールバックをコールする

  • ≪ OAuthProvider::callconsumerHandler
  • OAuthProvider::calltokenHandler ≫
  • PHP Manual
  • OAuthProvider
  • timestampNonceHandler コールバックをコールする

OAuthProvider::callTimestampNonceHandler

(PECL OAuth >= 1.0.0)

OAuthProvider::callTimestampNonceHandler — timestampNonceHandler コールバックをコールする

説明

public OAuthProvider::callTimestampNonceHandler(): void

タイムスタンプハンドラコールバックとして登録した関数をコールします。この関数は OAuthProvider::timestampNonceHandler() で登録します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

コールバック関数をコールできなかったり、 あるいは定義されていなかったりした場合は E_ERROR レベルのエラーとなります。

参考

  • OAuthProvider::timestampNonceHandler() - timestampNonceHandler コールバックを設定する


tokenNonceHandler コールバックをコールする

  • ≪ OAuthProvider::callTimestampNonceHandler
  • OAuthProvider::checkOAuthRequest ≫
  • PHP Manual
  • OAuthProvider
  • tokenNonceHandler コールバックをコールする

OAuthProvider::calltokenHandler

(PECL OAuth >= 1.0.0)

OAuthProvider::calltokenHandler — tokenNonceHandler コールバックをコールする

説明

public OAuthProvider::calltokenHandler(): void

トークンハンドラコールバックとして登録した関数をコールします。この関数は OAuthProvider::tokenHandler() でコールします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

エラー / 例外

コールバック関数をコールできなかったり、 あるいは定義されていなかったりした場合は E_ERROR レベルのエラーとなります。

参考

  • OAuthProvider::tokenHandler() - tokenHandler コールバックを設定する


oauth リクエストをチェックする

  • ≪ OAuthProvider::calltokenHandler
  • OAuthProvider::__construct ≫
  • PHP Manual
  • OAuthProvider
  • oauth リクエストをチェックする

OAuthProvider::checkOAuthRequest

(PECL OAuth >= 1.0.0)

OAuthProvider::checkOAuthRequest — oauth リクエストをチェックする

説明

public OAuthProvider::checkOAuthRequest(string $uri = ?, string $method = ?): void

OAuth リクエストをチェックします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

uri

オプションの URI、あるいはエンドポイント。

method

HTTP メソッド。 OAUTH_HTTP_METHOD_* OAuth 定数 のいずれかをオプションで渡します。

戻り値

値を返しません。

エラー / 例外

HTTP メソッドを検出できない場合には E_ERROR レベルのエラーが発生します。

参考

  • OAuthProvider::reportProblem() - 問題を報告する


新しい OAuthProvider オブジェクトを作る

  • ≪ OAuthProvider::checkOAuthRequest
  • OAuthProvider::consumerHandler ≫
  • PHP Manual
  • OAuthProvider
  • 新しい OAuthProvider オブジェクトを作る

OAuthProvider::__construct

(PECL OAuth >= 1.0.0)

OAuthProvider::__construct — 新しい OAuthProvider オブジェクトを作る

説明

public OAuthProvider::__construct(array $params_array = ?)

新しい OAuthProvider オブジェクトのインスタンスを作成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

params_array

これらのオプションパラメータを設定できるのは CLI SAPI のみです。

戻り値

OAuthProvider オブジェクトを返します。

例

例1 OAuthProvider::__construct() の例

<?php
try {

$op = new OAuthProvider();

// ユーザー定義のコールバック関数を使います
$op->consumerHandler(array($this, 'lookupConsumer'));
$op->timestampNonceHandler(array($this, 'timestampNonceChecker'));
$op->tokenHandler(array($this, 'myTokenHandler'));

// foo_uri パラメータは無視します
$op->setParam('foo_uri', NULL);

// このエンドポイントにはトークンは不要です
$op->setRequestTokenPath('/v1/oauth/request_token');

$op->checkOAuthRequest();

} catch (OAuthException $e) {

echo OAuthProvider::reportProblem($e);
}
?>

参考

  • OAuthProvider::setParam() - パラメータを設定する


consumerHandler コールバックを設定する

  • ≪ OAuthProvider::__construct
  • OAuthProvider::generateToken ≫
  • PHP Manual
  • OAuthProvider
  • consumerHandler コールバックを設定する

OAuthProvider::consumerHandler

(PECL OAuth >= 1.0.0)

OAuthProvider::consumerHandler — consumerHandler コールバックを設定する

説明

public OAuthProvider::consumerHandler(callable $callback_function): void

コンシューマハンドラコールバックを設定します。これは OAuthProvider::callConsumerHandler() でコールされる関数です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

callback_function

callable 関数名。

戻り値

値を返しません。

例

例1 OAuthProvider::consumerHandler() コールバックの例

<?php
function lookupConsumer($provider) {

if ($provider->consumer_key === 'unknown') {
return OAUTH_CONSUMER_KEY_UNKNOWN;
} else if($provider->consumer_key == 'blacklisted' || $provider->consumer_key === 'throttled') {
return OAUTH_CONSUMER_KEY_REFUSED;
}

$provider->consumer_secret = "the_consumers_secret";

return OAUTH_OK;
}
?>

参考

  • OAuthProvider::callConsumerHandler() - consumerNonceHandler コールバックをコールする


ランダムなトークンを生成する

  • ≪ OAuthProvider::consumerHandler
  • OAuthProvider::is2LeggedEndpoint ≫
  • PHP Manual
  • OAuthProvider
  • ランダムなトークンを生成する

OAuthProvider::generateToken

(PECL OAuth >= 1.0.0)

OAuthProvider::generateToken — ランダムなトークンを生成する

説明

final public static OAuthProvider::generateToken(int $size, bool $strong = false): string

擬似乱数を使ってランダムなバイトの文字列を生成します。

パラメータ

size

トークンの長さ。バイト単位で指定します。

strong

true に設定すると、エントロピーとして /dev/random を使います。 それ以外の場合は、ブロックされることのない /dev/urandom を使います。 このパラメータは、Windows では無視されます。

戻り値

生成されたトークンをバイト文字列で返します。

エラー / 例外

strong パラメータが true のときは、 (十分な量の初期ランダムデータがなかったなどの理由で) 代替 rand() 実装を使うことになった場合に E_WARNING レベルのエラーが発生します。

例

例1 OAuthProvider::generateToken() の例

<?php
$p = new OAuthProvider();

$t = $p->generateToken(4);

echo strlen($t), PHP_EOL;
echo bin2hex($t), PHP_EOL;

?>

上の例の出力は、 たとえば以下のようになります。

4
b6a82c27

注意

注意:

十分な量のランダムデータがシステムから得られなかった場合、この関数は PHP の rand() 関数の実装を使って残りのバイトを埋めます。

参考

  • openssl_random_pseudo_bytes() - 疑似ランダムなバイト文字列を生成する
  • mcrypt_create_iv() - Creates an initialization vector (IV) from a random source


is2LeggedEndpoint

  • ≪ OAuthProvider::generateToken
  • OAuthProvider::isRequestTokenEndpoint ≫
  • PHP Manual
  • OAuthProvider
  • is2LeggedEndpoint

OAuthProvider::is2LeggedEndpoint

(PECL OAuth >= 1.0.0)

OAuthProvider::is2LeggedEndpoint — is2LeggedEndpoint

説明

public OAuthProvider::is2LeggedEndpoint(mixed $params_array): void

2-legged フローあるいはリクエストの署名。トークンは不要です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

params_array

戻り値

OAuthProvider オブジェクトを返します。

例

例1 OAuthProvider::is2LeggedEndpoint() の例

<?php

$provider = new OAuthProvider();

$provider->is2LeggedEndpoint(true);

?>

参考

  • OAuthProvider::__construct() - 新しい OAuthProvider オブジェクトを作る


isRequestTokenEndpoint を設定する

  • ≪ OAuthProvider::is2LeggedEndpoint
  • OAuthProvider::removeRequiredParameter ≫
  • PHP Manual
  • OAuthProvider
  • isRequestTokenEndpoint を設定する

OAuthProvider::isRequestTokenEndpoint

(PECL OAuth >= 1.0.0)

OAuthProvider::isRequestTokenEndpoint — isRequestTokenEndpoint を設定する

説明

public OAuthProvider::isRequestTokenEndpoint(bool $will_issue_request_token): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

will_issue_request_token

リクエストトークンを発行するか否かを設定します。つまり OAuthProvider::tokenHandler() がコールされる必要があるかどうかを決めるということです。

戻り値

値を返しません。

参考

  • OAuthProvider::setRequestTokenPath() - リクエストトークンのパスを設定する
  • OAuthProvider::reportProblem() - 問題を報告する


必須パラメータを削除する

  • ≪ OAuthProvider::isRequestTokenEndpoint
  • OAuthProvider::reportProblem ≫
  • PHP Manual
  • OAuthProvider
  • 必須パラメータを削除する

OAuthProvider::removeRequiredParameter

(PECL OAuth >= 1.0.0)

OAuthProvider::removeRequiredParameter — 必須パラメータを削除する

説明

final public OAuthProvider::removeRequiredParameter(string $req_params): bool

必須パラメータを削除します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

req_params

削除したい必須パラメータ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • OAuthProvider::setParam() - パラメータを設定する
  • OAuthProvider::addRequiredParameter() - 必須パラメータを追加する


問題を報告する

  • ≪ OAuthProvider::removeRequiredParameter
  • OAuthProvider::setParam ≫
  • PHP Manual
  • OAuthProvider
  • 問題を報告する

OAuthProvider::reportProblem

(PECL OAuth >= 1.0.0)

OAuthProvider::reportProblem — 問題を報告する

説明

final public static OAuthProvider::reportProblem(string $oauthexception, bool $send_headers = true): string

問題を、OAuthException 形式で渡します。設定できる問題については OAuth 定数 のセクションを参照ください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

oauthexception

OAuthException。

戻り値

値を返しません。

参考

  • OAuthProvider::checkOAuthRequest() - oauth リクエストをチェックする
  • OAuthProvider::isRequestTokenEndpoint() - isRequestTokenEndpoint を設定する


パラメータを設定する

  • ≪ OAuthProvider::reportProblem
  • OAuthProvider::setRequestTokenPath ≫
  • PHP Manual
  • OAuthProvider
  • パラメータを設定する

OAuthProvider::setParam

(PECL OAuth >= 1.0.0)

OAuthProvider::setParam — パラメータを設定する

説明

final public OAuthProvider::setParam(string $param_key, mixed $param_val = ?): bool

パラメータを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

param_key

パラメータのキー。

param_val

パラメータの値。

パラメータをシグネチャの検証から除外するには、この値を null にします。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • OAuthProvider::addRequiredParameter() - 必須パラメータを追加する


リクエストトークンのパスを設定する

  • ≪ OAuthProvider::setParam
  • OAuthProvider::timestampNonceHandler ≫
  • PHP Manual
  • OAuthProvider
  • リクエストトークンのパスを設定する

OAuthProvider::setRequestTokenPath

(PECL OAuth >= 1.0.0)

OAuthProvider::setRequestTokenPath — リクエストトークンのパスを設定する

説明

final public OAuthProvider::setRequestTokenPath(string $path): bool

リクエストトークンのパスを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

path

パス。

戻り値

true

参考

  • OAuthProvider::tokenHandler() - tokenHandler コールバックを設定する


timestampNonceHandler コールバックを設定する

  • ≪ OAuthProvider::setRequestTokenPath
  • OAuthProvider::tokenHandler ≫
  • PHP Manual
  • OAuthProvider
  • timestampNonceHandler コールバックを設定する

OAuthProvider::timestampNonceHandler

(PECL OAuth >= 1.0.0)

OAuthProvider::timestampNonceHandler — timestampNonceHandler コールバックを設定する

説明

public OAuthProvider::timestampNonceHandler(callable $callback_function): void

タイムスタンプ ノンス ハンドラコールバックを設定します。これは OAuthProvider::callTimestampNonceHandler() でコールされる関数です。タイムスタンプやノンスに関するエラーはこのコールバックにスローされます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

callback_function

callable 関数名。

戻り値

値を返しません。

例

例1 OAuthProvider::timestampNonceHandler() コールバックの例

<?php
function timestampNonceChecker($provider) {

if ($provider->nonce === 'bad') {
return OAUTH_BAD_NONCE;
} elseif ($provider->timestamp == '0') {
return OAUTH_BAD_TIMESTAMP;
}

return OAUTH_OK;
}
?>

参考

  • OAuthProvider::callTimestampNonceHandler() - timestampNonceHandler コールバックをコールする


tokenHandler コールバックを設定する

  • ≪ OAuthProvider::timestampNonceHandler
  • OAuthException ≫
  • PHP Manual
  • OAuthProvider
  • tokenHandler コールバックを設定する

OAuthProvider::tokenHandler

(PECL OAuth >= 1.0.0)

OAuthProvider::tokenHandler — tokenHandler コールバックを設定する

説明

public OAuthProvider::tokenHandler(callable $callback_function): void

トークンハンドラコールバックを設定します。これは OAuthProvider::callTokenHandler() でコールされる関数です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

callback_function

callable 関数名。

戻り値

値を返しません。

例

例1 OAuthProvider::tokenHandler() コールバックの例

<?php
function tokenHandler($provider) {

if ($provider->token === 'rejected') {
return OAUTH_TOKEN_REJECTED;
} elseif ($provider->token === 'revoked') {
return OAUTH_TOKEN_REVOKED;
}

$provider->token_secret = "the_tokens_secret";
return OAUTH_OK;
}
?>

参考

  • OAuthProvider::callTokenHandler() - tokenNonceHandler コールバックをコールする


OAuthException クラス

(PECL OAuth >= 0.99.1)

はじめに

この例外は、OAuth 拡張モジュールの使用中に例外エラーが発生したときにスローされます。 デバッグに有用な情報が含まれています。

クラス概要

class OAuthException extends Exception {
/* プロパティ */
public $lastResponse;
public $debugInfo;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

lastResponse

発生した例外のレスポンス (存在する場合)。

debugInfo


SOAP

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • SOAP 関数
    • is_soap_fault — SOAP コールが失敗したかどうかを調べる
    • use_soap_error_handler — SOAP エラーハンドラを使用するかどうかを設定する
  • SoapClient — SoapClient クラス
    • SoapClient::__call — SOAP 関数をコールする (非推奨)
    • SoapClient::__construct — SoapClient のコンストラクタ
    • SoapClient::__doRequest — SOAP リクエストを実行する
    • SoapClient::__getCookies — クッキーの一覧を取得する
    • SoapClient::__getFunctions — SOAP 関数の一覧を返す
    • SoapClient::__getLastRequest — 直近の SOAP リクエストを返す
    • SoapClient::__getLastRequestHeaders — 直近の SOAP リクエストヘッダを返す
    • SoapClient::__getLastResponse — 直近の SOAP レスポンスを返す
    • SoapClient::__getLastResponseHeaders — 直近の SOAP レスポンスヘッダを返す
    • SoapClient::__getTypes — SOAP 型の一覧を返す
    • SoapClient::__setCookie — SOAP リクエストと共に送信されるクッキーを設定する
    • SoapClient::__setLocation — 使用するウェブサービスの場所を設定する
    • SoapClient::__setSoapHeaders — 以降のコール用の SOAP ヘッダを設定する
    • SoapClient::__soapCall — SOAP 関数をコールする
  • SoapServer — SoapServer クラス
    • SoapServer::addFunction — SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する
    • SoapServer::addSoapHeader — SOAP ヘッダをレスポンスに追加する
    • SoapServer::__construct — SoapServer コンストラクタ
    • SoapServer::fault — エラーを示す SoapServer フォールト を発行する
    • SoapServer::getFunctions — 定義されている関数の一覧を返す
    • SoapServer::handle — SOAP リクエストを処理する
    • SoapServer::setClass — SOAP リクエストを処理するクラスを設定する
    • SoapServer::setObject — SOAP リクエストの処理に使用するオブジェクトを設定する
    • SoapServer::setPersistence — SoapServer の持続モードを設定する
  • SoapFault — SoapFault クラス
    • SoapFault::__construct — SoapFault コンストラクタ
    • SoapFault::__toString — SoapFault の文字列表現を取得する
  • SoapHeader — SoapHeader クラス
    • SoapHeader::__construct — SoapHeader コンストラクタ
  • SoapParam — SoapParam クラス
    • SoapParam::__construct — SoapParam コンストラクタ
  • SoapVar — SoapVar クラス
    • SoapVar::__construct — SoapVar コンストラクタ


はじめに

SOAP拡張モジュールは、 SOAPサーバーおよびクライアントを書くために使用することができます。 本拡張モジュールは、» SOAP 1.1、 » SOAP 1.2 および » WSDL 1.1 規約のサブセットをサポートします。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SOAP
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

この拡張モジュールを使うには libxml 拡張モジュールが必要です。つまり、 PHP 7.4 以降では --with-libxml、それより前のバージョンでは --enable-libxml も指定しなければならないということです。 しかし、libxml はデフォルトで有効になっているのでこのオプションは暗黙のうちに指定されています。


インストール手順

SOAP サポートを有効にするには、--enable-soap を指定して PHP の configure を行います。


実行時設定

php.ini の設定により動作が変化します。

SOAP 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
soap.wsdl_cache_enabled | 1 | INI_ALL |
soap.wsdl_cache_dir | /tmp | INI_ALL |
soap.wsdl_cache_ttl | 86400 | INI_ALL |
soap.wsdl_cache | 1 | INI_ALL |
soap.wsdl_cache_limit | 5 | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

soap.wsdl_cache_enabled int

WSDLキャッシュ機能有効または無効にします。

soap.wsdl_cache_dir string

SOAP 拡張モジュールがキャッシュファイルを置くディレクトリの名前を設定します。

soap.wsdl_cache_ttl int

キャッシュされたファイルが元のファイルの代わりに使用される秒数 (有効期間)を設定します。

soap.wsdl_cache int

soap.wsdl_cache_enabled が on の場合に、 この設定によってキャッシュ方式を決めます。 WSDL_CACHE_NONE (0)、 WSDL_CACHE_DISK (1)、 WSDL_CACHE_MEMORY (2) あるいは WSDL_CACHE_BOTH (3) のいずれかです。これは、 SoapClient や SoapServer のコンストラクタにおける配列 options で設定することもできます。

soap.wsdl_cache_limit int

WSDL ファイルのキャッシュに使用するメモリの最大数を設定します。 メモリキャッシュがいっぱいのときにさらにファイルを追加する場合は、 既存のキャッシュの中のいちばん古いファイルを削除します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

SOAP 定数
定数 | 値 | 説明
SOAP_1_1 (int) | 1 | soap_version オプションを SoapServer::__construct() や SoapClient::__construct() に渡す際、SOAP 1.1 を使うように指定します。
SOAP_1_2 (int) | 2 | soap_version オプションを SoapServer::__construct() や SoapClient::__construct() に渡す際、SOAP 1.2 を使うように指定します。
SOAP_PERSISTENCE_SESSION (int) | 1 |
SOAP_PERSISTENCE_REQUEST (int) | 2 |
SOAP_FUNCTIONS_ALL (int) | 999 |
SOAP_ENCODED (int) | 1 | use オプションを SoapClient::__construct() に渡す際、SOAP エンコーディングを使うように指定します。
SOAP_LITERAL (int) | 2 | use オプションを SoapClient::__construct() に渡す際、サービス特有のエンコーディングを使うように指定します。
SOAP_RPC (int) | 1 | style オプションを SoapClient::__construct() に渡す際、RPC スタイルのバインディングを使うように指定します。
SOAP_DOCUMENT (int) | 2 | style オプションを SoapClient::__construct() に渡す際、ドキュメントのバインディングを使うよに指定します。
SOAP_ACTOR_NEXT (int) | 1 |
SOAP_ACTOR_NONE (int) | 2 |
SOAP_ACTOR_UNLIMATERECEIVER (int) | 3 |
SOAP_COMPRESSION_ACCEPT (int) | 32 | compression オプション の一部を SoapClient::__construct() に渡す際、"Accept-Encoding" を使うことを指定します。
SOAP_COMPRESSION_GZIP (int) | 0 | compression オプション の一部を SoapClient::__construct() に渡す際、gzip 圧縮 を使うことを指定します。
SOAP_COMPRESSION_DEFLATE (int) | 16 | compression オプション の一部を SoapClient::__construct() に渡す際、deflate 圧縮 を使うことを指定します。
SOAP_AUTHENTICATION_BASIC (int) | 0 | authentication オプションを SoapClient::__construct() に渡す際、Basic 認証を使うことを指定します。
SOAP_AUTHENTICATION_DIGEST (int) | 1 | authentication オプションを SoapClient::__construct() に渡す際、Digest 認証を使うことを指定します。
SOAP_SSL_METHOD_TLS (int) | 0 | 推奨されていない ssl_methodオプション と一緒に、 SoapClient::__construct() で使います。
SOAP_SSL_METHOD_SSLv2 (int) | 1 | 推奨されていない ssl_methodオプション と一緒に、 SoapClient::__construct() で使います。
SOAP_SSL_METHOD_SSLv3 (int) | 2 | 推奨されていない ssl_methodオプション と一緒に、 SoapClient::__construct() で使います。
SOAP_SSL_METHOD_SSLv23 (int) | 3 | 推奨されていない ssl_methodオプション と一緒に、 SoapClient::__construct() で使います。
UNKNOWN_TYPE (int) | 999998 |
XSD_STRING (int) | 101 |
XSD_BOOLEAN (int) | 102 |
XSD_DECIMAL (int) | 103 |
XSD_FLOAT (int) | 104 |
XSD_DOUBLE (int) | 105 |
XSD_DURATION (int) | 106 |
XSD_DATETIME (int) | 107 |
XSD_TIME (int) | 108 |
XSD_DATE (int) | 109 |
XSD_GYEARMONTH (int) | 110 |
XSD_GYEAR (int) | 111 |
XSD_GMONTHDAY (int) | 112 |
XSD_GDAY (int) | 113 |
XSD_GMONTH (int) | 114 |
XSD_HEXBINARY (int) | 115 |
XSD_BASE64BINARY (int) | 116 |
XSD_ANYURI (int) | 117 |
XSD_QNAME (int) | 118 |
XSD_NOTATION (int) | 119 |
XSD_NORMALIZEDSTRING (int) | 120 |
XSD_TOKEN (int) | 121 |
XSD_LANGUAGE (int) | 122 |
XSD_NMTOKEN (int) | 123 |
XSD_NAME (int) | 124 |
XSD_NCNAME (int) | 125 |
XSD_ID (int) | 126 |
XSD_IDREF (int) | 127 |
XSD_IDREFS (int) | 128 |
XSD_ENTITY (int) | 129 |
XSD_ENTITIES (int) | 130 |
XSD_INTEGER (int) | 131 |
XSD_NONPOSITIVEINTEGER (int) | 132 |
XSD_NEGATIVEINTEGER (int) | 133 |
XSD_LONG (int) | 134 |
XSD_INT (int) | 135 |
XSD_SHORT (int) | 136 |
XSD_BYTE (int) | 137 |
XSD_NONNEGATIVEINTEGER (int) | 138 |
XSD_UNSIGNEDLONG (int) | 139 |
XSD_UNSIGNEDINT (int) | 140 |
XSD_UNSIGNEDSHORT (int) | 141 |
XSD_UNSIGNEDBYTE (int) | 142 |
XSD_POSITIVEINTEGER (int) | 143 |
XSD_NMTOKENS (int) | 144 |
XSD_ANYTYPE (int) | 145 |
XSD_ANYXML (int) | 147 |
APACHE_MAP (int) | 200 |
SOAP_ENC_OBJECT (int) | 301 |
SOAP_ENC_ARRAY (int) | 300 |
XSD_1999_TIMEINSTANT (int) | 401 |
XSD_NAMESPACE (string) | http://www.w3.org/2001/XMLSchema |
XSD_1999_NAMESPACE (string) | http://www.w3.org/1999/XMLSchema |
SOAP_SINGLE_ELEMENT_ARRAYS (int) | 1 | features オプション と一緒に、 SoapClient::__construct() で使います。
SOAP_WAIT_ONE_WAY_CALLS (int) | 2 | features オプション と一緒に、 SoapClient::__construct() で使います。
SOAP_USE_XSI_ARRAY_TYPE (int) | 4 | features オプション と一緒に、 SoapClient::__construct() で使います。
WSDL_CACHE_NONE (int) | 0 | SoapClient::__construct() や SoapServer::__construct() に渡す soap.wsdl_cache や wsdl_cache オプションで使う WDSL キャッシュを無効にします。
WSDL_CACHE_DISK (int) | 1 | SoapClient::__construct() や SoapServer::__construct() に渡す soap.wsdl_cache や wsdl_cache オプションで ディスク上の WDSL キャッシュだけを使うことを指定します。
WSDL_CACHE_MEMORY (int) | 2 | SoapClient::__construct() や SoapServer::__construct() に渡す soap.wsdl_cache や wsdl_cache オプションで オンメモリの WDSL キャッシュだけを使うことを指定します。
WSDL_CACHE_BOTH (int) | 3 | SoapClient::__construct() や SoapServer::__construct() に渡す soap.wsdl_cache や wsdl_cache オプションで オンメモリとディスク上の WDSL キャッシュを両方使うように指定します。


SOAP 関数

目次

  • is_soap_fault — SOAP コールが失敗したかどうかを調べる
  • use_soap_error_handler — SOAP エラーハンドラを使用するかどうかを設定する


SOAP コールが失敗したかどうかを調べる

  • ≪ SOAP 関数
  • use_soap_error_handler ≫
  • PHP Manual
  • SOAP 関数
  • SOAP コールが失敗したかどうかを調べる

is_soap_fault

(PHP 5, PHP 7, PHP 8)

is_soap_fault — SOAP コールが失敗したかどうかを調べる

説明

is_soap_fault(mixed $object): bool

この関数は、SOAP コールが失敗したかどうかを調べたいが、例外を使用したくない 場合に有用です。 この関数を使用するには、オプション exceptions に ゼロまたは false を指定して SoapClient オブジェクトを作成する必要があります。 この場合、SOAP メソッドは、特別な SoapFault オブジェクトを返します。 このオブジェクトには、フォルトの詳細 (faultcode, faultstring, faultactor および faultdetails) が含まれています。

exceptions が設定されていない場合、 SOAPコールは、エラー時に例外をスローします。 is_soap_fault() は指定したパラメータ SoapFault オブジェクトであるかどうかを調べます。

パラメータ

object

検査するオブジェクト

戻り値

エラー時に true、それ以外の場合に false を返します。

例

例1 is_soap_fault() の例

<?php
$client = new SoapClient("some.wsdl", array('exceptions' => 0));
$result = $client->SomeFunction();
if (is_soap_fault($result)) {
trigger_error("SOAP Fault: (faultcode: {$result->faultcode}, faultstring: {$result->faultstring})", E_USER_ERROR);
}
?>

例2 SOAP の標準的なエラーレポートメソッドは例外となる

<?php
try {
$client = new SoapClient("some.wsdl");
$result = $client->SomeFunction(/* ... */);
} catch (SoapFault $fault) {
trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}
?>

参考

  • SoapClient::__construct() - SoapClient のコンストラクタ
  • SoapFault::__construct() - SoapFault コンストラクタ


SOAP エラーハンドラを使用するかどうかを設定する

  • ≪ is_soap_fault
  • SoapClient ≫
  • PHP Manual
  • SOAP 関数
  • SOAP エラーハンドラを使用するかどうかを設定する

use_soap_error_handler

(PHP 5, PHP 7, PHP 8)

use_soap_error_handler — SOAP エラーハンドラを使用するかどうかを設定する

説明

use_soap_error_handler(bool $enable = true): bool

この関数は、SOAP サーバーで SOAP エラーハンドラを使用するかどうかを設定します。 それまでに設定されていた値を返します。 true に設定すると、 SoapServer アプリケーションでのエラーの詳細が SOAP フォールトメッセージとしてクライアントに送信されます。 false の場合は PHP の標準エラーハンドラを使います。 デフォルトは、エラーを SOAP フォールトメッセージとしてクライアントに送信します。

パラメータ

enable

true に設定すると、エラーの詳細をクライアントに送信します。

戻り値

元の値を返します。

参考

  • set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
  • set_exception_handler() - ユーザー定義の例外ハンドラ関数を設定する


SoapClient クラス

(PHP 5, PHP 7, PHP 8)

はじめに

SoapClient クラスは » SOAP 1.1、» SOAP 1.2 サーバー用のクライアントとなります。 WSDL モードあるいは non-WSDL モードで動作します。

クラス概要

class SoapClient {
/* プロパティ */
private ?string $uri = null;
private ?int $style = null;
private ?int $use = null;
private ?string $location = null;
private bool $trace = false;
private ?int $compression = null;
private ?resource $sdl = null;
private ?resource $typemap = null;
private ?resource $httpsocket = null;
private ?resource $httpurl = null;
private ?string $_login = null;
private ?string $_password = null;
private bool $_use_digest = false;
private ?string $_digest = null;
private ?string $_proxy_host = null;
private ?int $_proxy_port = null;
private ?string $_proxy_login = null;
private ?string $_proxy_password = null;
private bool $_exceptions = true;
private ?string $_encoding = null;
private ?array $_classmap = null;
private ?int $_features = null;
private int $_connection_timeout;
private ?resource $_stream_context = null;
private ?string $_user_agent = null;
private bool $_keep_alive = true;
private ?int $_ssl_method = null;
private int $_soap_version;
private ?int $_use_proxy = null;
private array $_cookies = [];
private ?array $__default_headers = null;
private ?SoapFault $__soap_fault = null;
private ?string $__last_request = null;
private ?string $__last_response = null;
private ?string $__last_request_headers = null;
private ?string $__last_response_headers = null;
/* メソッド */
public __construct(?string $wsdl, array $options = [])
public __call(string $name, array $args): mixed
public __doRequest(
string $request,
string $location,
string $action,
int $version,
bool $oneWay = false
): ?string
public __getCookies(): array
public __getFunctions(): ?array
public __getLastRequest(): ?string
public __getLastRequestHeaders(): ?string
public __getLastResponse(): ?string
public __getLastResponseHeaders(): ?string
public __getTypes(): ?array
public __setCookie(string $name, ?string $value = null): void
public __setLocation(?string $location = null): ?string
public __setSoapHeaders(SoapHeader|array|null $headers = null): bool
public __soapCall(
string $name,
array $args,
?array $options = null,
SoapHeader|array|null $inputHeaders = null,
array &$outputHeaders = null
): mixed
}

プロパティ

__default_headers

__last_request

__last_request_headers

__last_response

__last_response_headers

__soap_fault

_classmap

_connection_timeout

_cookies

_digest

_encoding

_exceptions

_features

_keep_alive

_login

_password

_proxy_host

_proxy_login

_proxy_password

_proxy_port

_soap_version

_ssl_method

_stream_context

_use_digest

_use_proxy

_user_agent

compression

httpsocket

httpurl

location

sdl

style

trace

typemap

uri

use

目次

  • SoapClient::__call — SOAP 関数をコールする (非推奨)
  • SoapClient::__construct — SoapClient のコンストラクタ
  • SoapClient::__doRequest — SOAP リクエストを実行する
  • SoapClient::__getCookies — クッキーの一覧を取得する
  • SoapClient::__getFunctions — SOAP 関数の一覧を返す
  • SoapClient::__getLastRequest — 直近の SOAP リクエストを返す
  • SoapClient::__getLastRequestHeaders — 直近の SOAP リクエストヘッダを返す
  • SoapClient::__getLastResponse — 直近の SOAP レスポンスを返す
  • SoapClient::__getLastResponseHeaders — 直近の SOAP レスポンスヘッダを返す
  • SoapClient::__getTypes — SOAP 型の一覧を返す
  • SoapClient::__setCookie — SOAP リクエストと共に送信されるクッキーを設定する
  • SoapClient::__setLocation — 使用するウェブサービスの場所を設定する
  • SoapClient::__setSoapHeaders — 以降のコール用の SOAP ヘッダを設定する
  • SoapClient::__soapCall — SOAP 関数をコールする


SOAP 関数をコールする (非推奨)

  • ≪ SoapClient
  • SoapClient::__construct ≫
  • PHP Manual
  • SoapClient
  • SOAP 関数をコールする (非推奨)

SoapClient::__call

(PHP 5, PHP 7, PHP 8)

SoapClient::__call — SOAP 関数をコールする (非推奨)

説明

public SoapClient::__call(string $name, array $args): mixed

このメソッドを直接呼ぶのは推奨しません。 通常、SOAP の関数は SoapClient オブジェクトのメソッドとして呼べるようになっています。 それができない場合、あるいは追加オプションを指定する必要がある場合は、 SoapClient::__soapCall() を使いましょう。

パラメータ

name

コールするSOAP関数の名前。

args

関数に渡す引数の配列。 連想配列でも、数値添字形式の配列でも構いません。 ほとんどのSOAPサーバーに対しては、 引数の名前を指定することが必須であり、 その場合は、連想配列を指定する必要があることに注意して下さい。

戻り値

SOAP 関数は、一つまたは複数の値を返す可能性があります。 SOAP 関数から値をひとつだけ返す場合は、 返り値はスカラーになります。 複数の値を返す場合は、出力パラメータの名前がついた連想配列を返します。

エラーが発生した場合、 かつ SoapClient の exceptions を false に設定した場合は、 SoapFault オブジェクトを返します。


SoapClient のコンストラクタ

  • ≪ SoapClient::__call
  • SoapClient::__doRequest ≫
  • PHP Manual
  • SoapClient
  • SoapClient のコンストラクタ

SoapClient::__construct

(PHP 5, PHP 7, PHP 8)

SoapClient::__construct — SoapClient のコンストラクタ

説明

public SoapClient::__construct(?string $wsdl, array $options = [])

SOAP サービスに接続するための SoapClient オブジェクトを生成します。

パラメータ

wsdl

サービスを記述した WSDL ファイルまたは URI。 これは自動的にクライアントを設定します。 指定されない場合、クライアントは 非WSDL モードで動作します。

注意:

デフォルトでは、 WSDL ファイルはパフォーマンスのためキャッシュされます。 このキャッシュ機能を無効にしたり、設定を変更する場合は、 SOAP 設定オプション や cache_wsdl オプション を参照ください。

options

SOAP クライアントに指定する追加オプションを連想配列で指定します。 wsdl が指定された場合、 このパラメータはオプションです。 指定されない場合、 location とurl オプションを指定する必要があります。

location string

リクエストを送信する SOAP サーバーのURL

wsdl パラメータが指定されない場合、 必須です。 wsdl と location が指定された場合、 location オプションは WSDL ファイルで指定されたあらゆる location を上書きします。

uri string

SOAP サービスのターゲット名前空間です。

wsdl が指定されていない場合、このパラメータは必須です。 そうでない場合、この値は無視されます。

style int

SOAP_RPC と SOAP_DOCUMENT を使うと、 このクライアントで使うバインディングスタイルを指定します。 SOAP_RPC は RPCスタイルのバインディングを指定します。 この場合の SOAP リクエストのボディには、 関数コールの標準エンコーディングが含まれます。 SOAP_DOCUMENT は ドキュメントスタイルのバインディングを指定します。 この場合の SOAP リクエストのボディには、 サービス定義を記した XML ドキュメントが含まれます。

wsdl が指定された場合、 このオプションは無視され、 スタイルは WDSL ファイルから読み込まれます。

このオプションと wsdl パラメータ を両方指定しなかった場合、 RPCスタイルを使います。

use int

SOAP_ENCODED や SOAP_LITERAL を使うと、 このクライアントで使うエンコーディングスタイルを指定します。 SOAP_ENCODED は、 SOAP 仕様で定義された型を使い、エンコーディングを指定します。 SOAP_LITERAL は、 サービスで定義されたスキームを使い、 エンコーディングを指定します。

wsdl が指定された場合、 このオプションは無視され、 エンコーディングは WDSL ファイルから読み込まれます。

このオプションと wsdl パラメータ を両方指定しなかった場合、 "encoded" スタイルを使います。

soap_version int

使用する SOAP プロトコルのバージョンを指定します: SOAP 1.1 の場合は SOAP_1_1 を指定します。 SOAP 1.2 の場合は SOAP_1_2 を指定します。

省略した場合は、SOAP 1.1 を使います。

authentication int

HTTP 認証をリクエスト時に使う際の、 認証方法を指定します。 SOAP_AUTHENTICATION_BASIC と SOAP_AUTHENTICATION_DIGEST が指定できます。

省略された場合、 かつ login オプションが指定されると Basic 認証を使います。

login string

Basic 認証と、Digest 認証で使うユーザー名を指定します。

password string

Basic 認証と、Digest 認証で使うパスワードを指定します。

HTTPS クライアント認証で使う passphrase と混同しないようにして下さい。

local_cert string

HTTPS 認証で使うクライアント証明書のパス。 証明書ファイルは、 証明書と秘密鍵が両方入った状態で、 PEMエンコードされている必要があります。

このファイルには、発行者のチェインも含めることができます。 それらを含める場合、クライアント証明書の後に置く必要があります。

stream_context でも設定できます。 この場合、秘密鍵のファイルは別に指定できます。

passphrase string

local_cert オプションで指定したクライアント証明書のための パスフレーズ。

Basic 認証や Digest 認証で使う password と混同しないようにして下さい。

stream_context でも設定できます。

proxy_host string

HTTPリクエスト時に使う、 プロキシサーバーとして用いるホスト名を指定します。

proxy_port オプションも指定する必要があります。

proxy_port int

proxy_host で指定したプロキシサーバーに接続する際に使うポート番号。

proxy_login string

proxy_host で指定したプロキシサーバーに接続する際に、 Basic 認証で用いるオプションのユーザー名

proxy_password string

proxy_host で指定したプロキシサーバーに接続する際に、 Basic 認証で用いるオプションのパスワード

compression int

SOAP リクエストとレスポンスの圧縮を有効にします。

この値は、3つの値を ビット演算のOR で指定します: オプションの SOAP_COMPRESSION_ACCEPT は、"Accept-Encoding" ヘッダを指定します。 SOAP_COMPRESSION_GZIP や SOAP_COMPRESSION_DEFLATE は、使用する圧縮アルゴリズムと、 リクエストで使う圧縮レベルを 1 から 9 の間の数値で指定します。 たとえば、双方向の gzip 圧縮を最高の圧縮レベルで行う場合は、 SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9 を指定します。

encoding string

内部的な文字エンコーディングを指定します。 リクエストはここで指定されたエンコーディングから、 常に UTF-8 に変換して送られ、 レスポンスはこのエンコーディングに変換されます。

trace bool

リクエストやレスポンスのキャプチャを行います。 キャプチャした情報は SoapClient::__getLastRequest(), SoapClient::__getLastRequestHeaders(), SoapClient::__getLastResponse(), SoapClient::__getLastResponseHeaders(). を使ってアクセスできます。

省略した場合のデフォルト値は false です。

classmap array

WSDL 型を PHP クラスにマッピングするために使用可能です。 このオプションには、キーとしてWSDL 型、 値として PHP クラスの名前を持つ配列を指定する必要があります。 型の名前は、 要素の(タグ)名前と一致させる必要はないことに注意して下さい。

指定するクラス名は、常に 名前空間 で完全修飾されているべきですし、 \ で始まってはいけません。 正しい名前は、 ::class を使えば生成できます。

クラスのインスタンスを生成する場合、 コンストラクタはコールされず、 個別のプロパティに対して マジックメソッド __set() と __get() が コールされる点にも注意して下さい。

typemap array

ユーザー定義のコールバック関数を使って、 型マッピングを定義します。 型マッピングは配列で定義され、 キーは type_name (XML 要素型を指定した文字列)、 type_ns (名前空間URI を指定した文字列)、 from_xml (文字列を受け取り、 オブジェクトを返す callable)、 to_xml (オブジェクトをひとつ受け取り、 文字列を返す callable) です。

exceptions bool

エラーが起きた際に、 SoapFault をスローするかどうかを指定します。

デフォルトは true です。

connection_timeout int

SOAP サービスに接続する際のタイムアウト秒数を指定します。 これを使用しても、 レスポンスが遅いサービスのタイムアウトを定義することはできません。 サービスのコールが完了するまでの待ち時間を制限するには、 default_socket_timeout が使えます。

cache_wsdl int

wsdl を指定した場合、 かつ soap.wsdl_cache_enabled が有効になっている場合に、 このオプションはキャッシュのタイプを指定します。 WSDL_CACHE_NONE, WSDL_CACHE_DISK, WSDL_CACHE_MEMORY, WSDL_CACHE_BOTH のいずれかが指定できます。

ふたつのタイプのキャッシュが利用できます。 WSDL を現在のプロセスのメモリにキャッシュする インメモリのキャッシュと、 WSDL をディスク上にキャッシュし、 全てのプロセスと共有するディスクキャッシュがあります。 ディスクキャッシュで使うディレクトリは soap.wsdl_cache_dir で指定できます。 どちらのタイプのキャッシュでも、 soap.wsdl_cache_ttl で指定した寿命があります。 インメモリキャッシュの場合、 soap.wsdl_cache_limit でキャッシュエントリの数の最大値も指定できます。

この値を指定しない場合、 soap.wsdl_cache オプションの値を使います。

user_agent string

リクエストをする際に User-Agent で使う値。

stream_context でも指定できます。

この値を指定しない場合、 "PHP-SOAP/" の後に、 PHP_VERSION の値を付けたものを使います。

stream_context resource

追加のオプションを設定できる stream context。 これは stream_context_create() で生成できます。

このコンテキストには、 socket context options, SSL context options, HTTP context options が含まれます: content_type, header, max_redirects, protocol_version, user_agent が設定できます。

'header' コンテキストオプションで指定された場合、以下のHTTPヘッダは自動生成され、無視されることに注意して下さい: host, connection, user-agent, content-length, content-type, cookie, authorization, proxy-authorization

features int

以下の機能を有効にするための、ひとつ以上のビットマスク:

SOAP_SINGLE_ELEMENT_ARRAYS

レスポンスを配列にデコードする際には、 特定の親要素の中で要素名が一度または複数回現れるかをデフォルトで自動検知します。 一度しか現れない要素については、 オブジェクトのプロパティを通じてコンテンツに直接アクセスできます。 複数回現れる要素については、 プロパティには配列が含まれ、 マッチする要素の内容の配列が入ります。

SOAP_SINGLE_ELEMENT_ARRAYS が有効になった場合、 一度しか現れない要素は要素数がひとつの配列になります。 これは全ての要素と一貫性を保つためです。 これは、レスポンスにスキーマを含んでいるWSDLを使っている場合にのみ意味があります。具体的には、以下の例を参照ください。

SOAP_USE_XSI_ARRAY_TYPE

use オプション を使ったり、 WSDL プロパティを encoded に設定した場合に、 配列の型をスキーマ特有のそれにするのではなく、 SOAP-ENC:Array にします。

SOAP_WAIT_ONE_WAY_CALLS

WDSL が一方向のリクエストを指定していた場合であっても、 レスポンスを待つ。

keep_alive bool

Connection: Keep-Alive ヘッダや Connection: close を送信するかどうかを boolean で指定します。

デフォルトは true です。

ssl_method string

セキュアな HTTP 接続で用いる、 SSL または TLS のバージョンを指定します。 SOAP_SSL_METHOD_SSLv2 や SOAP_SSL_METHOD_SSLv3 を指定すると、 それぞれ SSL 2、 SSL 3 を強制的に使います。 SOAP_SSL_METHOD_SSLv23 を指定しても意味がありません。 これは後方互換のためだけに存在しています。 PHP 7.2 以降では、 SOAP_SSL_METHOD_TLS を指定しても同様に意味がありません。 これより前のバージョンでは、 この定数を指定すると TLS 1.0 を強制的に使っていました。

SSL バージョン 2 と 3 はセキュアでないとみなされています。 よってインストール済みの OpenSSL ライブラリではサポートされていない可能性があることに注意しましょう。

このオプションは PHP 8.1.0 以降では 推奨されません。 個別の TLS のバージョンを指定できる、 より柔軟性に富んだ代替があります。 stream_context オプションを 'crypto_method' コンテキストパラメータと一緒に使うようにして下さい。

例1 TLS 1.3 だけを指定する

<?php
$context = stream_context_create([
'ssl' => [
'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
]
]);
$client = new SoapClient("some.wsdl", ['context' => $context]);

エラー / 例外

SoapClient::__construct() は、 非 WSDL モードで location や uri オプションを指定しなかったときに E_ERROR エラーとなります。

wsdl URI が読み込めなかった場合に SoapFault をスローします。

例

例2 SoapClient::__construct() の例

<?php

$client = new SoapClient("some.wsdl");

$client = new SoapClient("some.wsdl", array('soap_version' => SOAP_1_2));

$client = new SoapClient("some.wsdl", array('login' => "some_name",
'password' => "some_password"));

$client = new SoapClient("some.wsdl", array('proxy_host' => "localhost",
'proxy_port' => 8080));

$client = new SoapClient("some.wsdl", array('proxy_host' => "localhost",
'proxy_port' => 8080,
'proxy_login' => "some_name",
'proxy_password' => "some_password"));

$client = new SoapClient("some.wsdl", array('local_cert' => "cert_key.pem"));

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/",
'style' => SOAP_DOCUMENT,
'use' => SOAP_LITERAL));

$client = new SoapClient("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9));

$client = new SoapClient("some.wsdl", array('encoding'=>'ISO-8859-1'));

class MyBook {
public $title;
public $author;
}

$client = new SoapClient("books.wsdl", array('classmap' => array('book' => "MyBook")));

$typemap = array(
array("type_ns" => "http://schemas.example.com",
"type_name" => "book",
"from_xml" => "unserialize_book",
"to_xml" => "serialize_book")
);
$client = new SoapClient("books.wsdl", array('typemap' => $typemap));

?>

例3 SOAP_SINGLE_ELEMENT_ARRAYS の機能を使う

/* Assuming a response like this, and an appropriate WSDL:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:example">
<SOAP-ENV:Body>
<response>
<collection>
<item>Single</item>
</collection>
<collection>
<item>First</item>
<item>Second</item>
</collection>
</response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
*/

echo "Default:\n";

$client = new TestSoapClient(__DIR__ . '/temp.wsdl');
$response = $client->exampleRequest();
var_dump( $response->collection[0]->item );
var_dump( $response->collection[1]->item );

echo "\nWith SOAP_SINGLE_ELEMENT_ARRAYS:\n";

$client = new TestSoapClient(__DIR__ . '/temp.wsdl', ['features' => SOAP_SINGLE_ELEMENT_ARRAYS]);
$response = $client->exampleRequest();
var_dump( $response->collection[0]->item );
var_dump( $response->collection[1]->item );

上の例の出力は以下となります。

Default:
string(6) "Single"
array(2) {
  [0] =>
  string(5) "First"
  [1] =>
  string(6) "Second"
}

With SOAP_SINGLE_ELEMENT_ARRAYS:
array(1) {
  [0] =>
  string(6) "Single"
}
array(2) {
  [0] =>
  string(5) "First"
  [1] =>
  string(6) "Second"
}


SOAP リクエストを実行する

  • ≪ SoapClient::__construct
  • SoapClient::__getCookies ≫
  • PHP Manual
  • SoapClient
  • SOAP リクエストを実行する

SoapClient::__doRequest

(PHP 5, PHP 7, PHP 8)

SoapClient::__doRequest — SOAP リクエストを実行する

説明

public SoapClient::__doRequest(
string $request,
string $location,
string $action,
int $version,
bool $oneWay = false
): ?string

HTTP 上で SOAP リクエストを実行します。

異なるトランスポート層や追加の XML を処理する、もしくは他の目的のために サブクラスでこのメソッドをオーバーライドする事ができます。

パラメータ

request

XML SOAP リクエスト

location

リクエスト先の URL

action

SOAP アクション

version

SOAP バージョン

oneWay

oneWay に true を設定すると、このメソッドは何も返しません。 レスポンスが不要なときにこれを使用します。

戻り値

XML SOAP レスポンス

変更履歴

バージョン | 説明
8.0.0 | oneWay の型は bool になりました。 これより前のバージョンでは、int でした。

例

例1 SoapClient::__doRequest() の例

<?php
function Add($x, $y) {
return $x + $y;
}

class LocalSoapClient extends SoapClient {
private $server;

function __construct($wsdl, $options) {
parent::__construct($wsdl, $options);
$this->server = new SoapServer($wsdl, $options);
$this->server->addFunction('Add');
}

function __doRequest($request, $location, $action, $version, $one_way = false): ?string {
ob_start();
$this->server->handle($request);
$response = ob_get_contents();
ob_end_clean();
return $response;
}

}

$x = new LocalSoapClient(NULL, ['location'=>'test://', 'uri'=>'http://testuri.org']);
var_dump($x->Add(3, 4));
?>


クッキーの一覧を取得する

  • ≪ SoapClient::__doRequest
  • SoapClient::__getFunctions ≫
  • PHP Manual
  • SoapClient
  • クッキーの一覧を取得する

SoapClient::__getCookies

(PHP 5 >= 5.4.30, PHP 7, PHP 8)

SoapClient::__getCookies — クッキーの一覧を取得する

説明

public SoapClient::__getCookies(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


SOAP 関数の一覧を返す

  • ≪ SoapClient::__getCookies
  • SoapClient::__getLastRequest ≫
  • PHP Manual
  • SoapClient
  • SOAP 関数の一覧を返す

SoapClient::__getFunctions

(PHP 5, PHP 7, PHP 8)

SoapClient::__getFunctions — SOAP 関数の一覧を返す

説明

public SoapClient::__getFunctions(): ?array

ウェブサービスの WSDL に記述されている関数の配列を返します。

注意:

この関数は WSDL モードでのみ動作します。

パラメータ

この関数にはパラメータはありません。

戻り値

SOAP 関数のプロトタイプ、戻り値の型、関数名、引数の型情報を含めた配列を返します。

例

例1 SoapClient::__getFunctions() の例

<?php
$client = new SoapClient('http://soap.amazon.com/schemas3/AmazonWebServices.wsdl');
var_dump($client->__getFunctions());
?>

上の例の出力は以下となります。

array(26) {
  [0]=>
  string(70) "ProductInfo KeywordSearchRequest(KeywordRequest $KeywordSearchRequest)"
  [1]=>
  string(79) "ProductInfo TextStreamSearchRequest(TextStreamRequest $TextStreamSearchRequest)"
  [2]=>
  string(64) "ProductInfo PowerSearchRequest(PowerRequest $PowerSearchRequest)"
...
  [23]=>
  string(107) "ShoppingCart RemoveShoppingCartItemsRequest(RemoveShoppingCartItemsRequest $RemoveShoppingCartItemsRequest)"
  [24]=>
  string(107) "ShoppingCart ModifyShoppingCartItemsRequest(ModifyShoppingCartItemsRequest $ModifyShoppingCartItemsRequest)"
  [25]=>
  string(118) "GetTransactionDetailsResponse GetTransactionDetailsRequest(GetTransactionDetailsRequest $GetTransactionDetailsRequest)"
}

参考

  • SoapClient::__construct() - SoapClient のコンストラクタ


直近の SOAP リクエストを返す

  • ≪ SoapClient::__getFunctions
  • SoapClient::__getLastRequestHeaders ≫
  • PHP Manual
  • SoapClient
  • 直近の SOAP リクエストを返す

SoapClient::__getLastRequest

(PHP 5, PHP 7, PHP 8)

SoapClient::__getLastRequest — 直近の SOAP リクエストを返す

説明

public SoapClient::__getLastRequest(): ?string

直近の SOAP リクエストで送信された XML を返します。

注意:

このメソッドは、オプション trace を指定して SoapClient が作成されている場合のみ使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の SOAP リクエストを XML 文字列で返します。

例

例1 SoapClient::__getLastRequest() の例

<?php
$client = new SoapClient("some.wsdl", array('trace' => 1));
$result = $client->SomeFunction();
echo "REQUEST:\n" . $client->__getLastRequest() . "\n";
?>

参考

  • SoapClient::__getLastRequestHeaders() - 直近の SOAP リクエストヘッダを返す
  • SoapClient::__getLastResponse() - 直近の SOAP レスポンスを返す
  • SoapClient::__getLastResponseHeaders() - 直近の SOAP レスポンスヘッダを返す


直近の SOAP リクエストヘッダを返す

  • ≪ SoapClient::__getLastRequest
  • SoapClient::__getLastResponse ≫
  • PHP Manual
  • SoapClient
  • 直近の SOAP リクエストヘッダを返す

SoapClient::__getLastRequestHeaders

(PHP 5, PHP 7, PHP 8)

SoapClient::__getLastRequestHeaders — 直近の SOAP リクエストヘッダを返す

説明

public SoapClient::__getLastRequestHeaders(): ?string

直近の SOAP リクエストヘッダを返します。

注意:

このメソッドは、オプション trace を指定して SoapClient が作成されている場合のみ使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の SOAP リクエストヘッダ

例

例1 SoapClient::__getLastRequestHeaders() の例

<?php
$client = SoapClient("some.wsdl", array('trace' => 1));
$result = $client->SomeFunction();
echo "REQUEST HEADERS:\n" . $client->__getLastRequestHeaders() . "\n";
?>

参考

  • SoapClient::__getLastResponseHeaders() - 直近の SOAP レスポンスヘッダを返す
  • SoapClient::__getLastRequest() - 直近の SOAP リクエストを返す
  • SoapClient::__getLastResponse() - 直近の SOAP レスポンスを返す


直近の SOAP レスポンスを返す

  • ≪ SoapClient::__getLastRequestHeaders
  • SoapClient::__getLastResponseHeaders ≫
  • PHP Manual
  • SoapClient
  • 直近の SOAP レスポンスを返す

SoapClient::__getLastResponse

(PHP 5, PHP 7, PHP 8)

SoapClient::__getLastResponse — 直近の SOAP レスポンスを返す

説明

public SoapClient::__getLastResponse(): ?string

直近の SOAP レスポンスで受信した XML を返します。

注意:

このメソッドは、オプション trace を指定して SoapClient が作成されている場合のみ使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の SOAP レスポンスを XML 文字列で返します。

例

例1 SoapClient::__getLastResponse() の例

<?php
$client = SoapClient("some.wsdl", array('trace' => 1));
$result = $client->SomeFunction();
echo "Response:\n" . $client->__getLastResponse() . "\n";
?>

参考

  • SoapClient::__getLastResponseHeaders() - 直近の SOAP レスポンスヘッダを返す
  • SoapClient::__getLastRequest() - 直近の SOAP リクエストを返す
  • SoapClient::__getLastRequestHeaders() - 直近の SOAP リクエストヘッダを返す


直近の SOAP レスポンスヘッダを返す

  • ≪ SoapClient::__getLastResponse
  • SoapClient::__getTypes ≫
  • PHP Manual
  • SoapClient
  • 直近の SOAP レスポンスヘッダを返す

SoapClient::__getLastResponseHeaders

(PHP 5, PHP 7, PHP 8)

SoapClient::__getLastResponseHeaders — 直近の SOAP レスポンスヘッダを返す

説明

public SoapClient::__getLastResponseHeaders(): ?string

直近の SOAP レスポンスヘッダを返します。

注意:

このメソッドは、オプション trace を指定して SoapClient が作成されている場合のみ使用可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

直近の SOAP レスポンスヘッダ

例

例1 SoapClient::__getLastResponse() の例

<?php
$client = SoapClient("some.wsdl", array('trace' => 1));
$result = $client->SomeFunction();
echo "RESPONSE HEADERS:\n" . $client->__getLastResponseHeaders() . "\n";
?>

参考

  • SoapClient::__getLastRequestHeaders() - 直近の SOAP リクエストヘッダを返す
  • SoapClient::__getLastRequest() - 直近の SOAP リクエストを返す
  • SoapClient::__getLastResponse() - 直近の SOAP レスポンスを返す


SOAP 型の一覧を返す

  • ≪ SoapClient::__getLastResponseHeaders
  • SoapClient::__setCookie ≫
  • PHP Manual
  • SoapClient
  • SOAP 型の一覧を返す

SoapClient::__getTypes

(PHP 5, PHP 7, PHP 8)

SoapClient::__getTypes — SOAP 型の一覧を返す

説明

public SoapClient::__getTypes(): ?array

ウェブサービスの WSDL で定義されている型の配列を返します。

注意:

この関数は WSDL モードでのみ動作します。

パラメータ

この関数にはパラメータはありません。

戻り値

SOAP 型の配列を返します。すべての構造や型が含まれています。

例

例1 SoapClient::__getTypes() の例

<?php
$client = new SoapClient('http://soap.amazon.com/schemas3/AmazonWebServices.wsdl');
var_dump($client->__getTypes());
?>

上の例の出力は以下となります。

array(88) {
  [0]=>
  string(30) "ProductLine ProductLineArray[]"
  [1]=>
  string(85) "struct ProductLine {
 string Mode;
 string RelevanceRank;
 ProductInfo ProductInfo;
}"
  [2]=>
  string(105) "struct ProductInfo {
 string TotalResults;
 string TotalPages;
 string ListName;
 DetailsArray Details;
}"
...
  [85]=>
  string(32) "ShortSummary ShortSummaryArray[]"
  [86]=>
  string(121) "struct GetTransactionDetailsRequest {
 string tag;
 string devtag;
 string key;
 OrderIdArray OrderIds;
 string locale;
}"
  [87]=>
  string(75) "struct GetTransactionDetailsResponse {
 ShortSummaryArray ShortSummaries;
}"
}

参考

  • SoapClient::__construct() - SoapClient のコンストラクタ


SOAP リクエストと共に送信されるクッキーを設定する

  • ≪ SoapClient::__getTypes
  • SoapClient::__setLocation ≫
  • PHP Manual
  • SoapClient
  • SOAP リクエストと共に送信されるクッキーを設定する

SoapClient::__setCookie

(PHP 5 >= 5.0.4, PHP 7, PHP 8)

SoapClient::__setCookie — SOAP リクエストと共に送信されるクッキーを設定する

説明

public SoapClient::__setCookie(string $name, ?string $value = null): void

SOAP リクエストと共に送信されるクッキーを定義します。

注意:

このメソッドをコールすることで、その後のすべての SoapClient メソッドコール に影響します。

パラメータ

name

クッキーの名前

value

クッキーの値。指定されない場合、クッキーは削除されます。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | value は、nullable になりました。


使用するウェブサービスの場所を設定する

  • ≪ SoapClient::__setCookie
  • SoapClient::__setSoapHeaders ≫
  • PHP Manual
  • SoapClient
  • 使用するウェブサービスの場所を設定する

SoapClient::__setLocation

(PHP 5 >= 5.0.4, PHP 7, PHP 8)

SoapClient::__setLocation — 使用するウェブサービスの場所を設定する

説明

public SoapClient::__setLocation(?string $location = null): ?string

それ以降の SOAP リクエストで使用するエンドポイント URL を設定します。 これは、SoapClient を作成する際に location オプションを指定するのと同じことです。

注意:

このメソッドのコールは必須ではありません。SoapClient は、デフォルトで WSDL ファイルから取得したエンドポイントを使用します。

パラメータ

location

新しいエンドポイント URL。

戻り値

それまでのエンドポイント URL を返します。

変更履歴

バージョン | 説明
8.0.3 | location は、nullable になりました。

例

例1 SoapClient::__setLocation() の例

<?php
$client = new SoapClient('http://example.com/webservice.php?wsdl');

$client->__setLocation('http://www.somethirdparty.com');

$old_location = $client->__setLocation(); // location オプションの設定を解除します

echo $old_location;

?>

上の例の出力は、 たとえば以下のようになります。

http://www.somethirdparty.com

参考

  • SoapClient::__construct() - SoapClient のコンストラクタ


以降のコール用の SOAP ヘッダを設定する

  • ≪ SoapClient::__setLocation
  • SoapClient::__soapCall ≫
  • PHP Manual
  • SoapClient
  • 以降のコール用の SOAP ヘッダを設定する

SoapClient::__setSoapHeaders

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

SoapClient::__setSoapHeaders — 以降のコール用の SOAP ヘッダを設定する

説明

public SoapClient::__setSoapHeaders(SoapHeader|array|null $headers = null): bool

SOAP リクエストで送信するヘッダを定義します。

注意:

このメソッドをコールすると、それまでの値はすべて上書きされます。

パラメータ

headers

設定したいヘッダ。SoapHeader オブジェクト、あるいは SoapHeader オブジェクトの配列です。 省略したり null を設定したりした場合はヘッダが削除されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 SoapClient::__setSoapHeaders() の例

<?php

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));
$header = new SoapHeader('http://soapinterop.org/echoheader/',
'echoMeStringRequest',
'hello world');

$client->__setSoapHeaders($header);

$client->__soapCall("echoVoid", null);
?>

例2 複数のヘッダの設定

<?php

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));
$headers = array();

$headers[] = new SoapHeader('http://soapinterop.org/echoheader/',
'echoMeStringRequest',
'hello world');

$headers[] = new SoapHeader('http://soapinterop.org/echoheader/',
'echoMeStringRequest',
'hello world again');

$client->__setSoapHeaders($headers);

$client->__soapCall("echoVoid", null);
?>


SOAP 関数をコールする

  • ≪ SoapClient::__setSoapHeaders
  • SoapServer ≫
  • PHP Manual
  • SoapClient
  • SOAP 関数をコールする

SoapClient::__soapCall

(PHP 5, PHP 7, PHP 8)

SoapClient::__soapCall — SOAP 関数をコールする

説明

public SoapClient::__soapCall(
string $name,
array $args,
?array $options = null,
SoapHeader|array|null $inputHeaders = null,
array &$outputHeaders = null
): mixed

本メソッドは、SOAP コールを行う低レベル API 関数です。 通常、WSDL モードでは、SOAP 関数を SoapClient のメソッドとして簡単にコールすることができます。 本メソッドは、soapaction が不明な場合や、 uri がデフォルトと異なっていたり、 SOAP ヘッダを送受信したい場合に、非 WSDL モードを使用する際に有用です。

エラーの場合に SOAP 関数を呼び出すと、PHP の例外が発生するか、例外が無効な場合には SoapFault オブジェクトが返されます。 この関数コールが失敗したかどうかを調べるには、 SoapFault 例外をキャッチするか、is_soap_fault() の結果を調べてください。

パラメータ

name

コールしたい SOAP 関数の名前。

args

関数に渡す引数の配列。これは、数値添字配列あるいは連想配列のどちらの形式でもかまいません。 たいていの SOAP サーバーは、パラメータ名を指定しないといけないことに注意しましょう。 そんな場合は、連想配列でないといけません。

options

クライアントに渡すオプションの連想配列。

location はリモートウェブサービスの URL です。

uri は SOAP サービスのターゲット名前空間です。

soapaction はコールしたいアクションです。

inputHeaders

SOAP リクエストで送信するヘッダの配列。

outputHeaders

指定すると、この配列に SOAP レスポンスのヘッダが書き込まれます。

戻り値

SOAP 関数は、一つまたは複数の値を返す可能性があります。 SOAP 関数から値をひとつだけ返す場合は、 返り値はスカラーになります。 複数の値を返す場合は、出力パラメータの名前がついた連想配列を返します。

エラーが発生した場合、 かつ SoapClient の exceptions を false に設定した場合は、 SoapFault オブジェクトを返します。

例

例1 SoapClient::__soapCall() の例

<?php

$client = new SoapClient("some.wsdl");
$client->SomeFunction($a, $b, $c);

$client->__soapCall("SomeFunction", array($a, $b, $c));
$client->__soapCall("SomeFunction", array($a, $b, $c), NULL,
new SoapHeader(), $output_headers);

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));
$client->SomeFunction($a, $b, $c);
$client->__soapCall("SomeFunction", array($a, $b, $c));
$client->__soapCall("SomeFunction", array($a, $b, $c),
array('soapaction' => 'some_action',
'uri' => 'some_uri'));
?>

参考

  • SoapClient::__construct() - SoapClient のコンストラクタ
  • SoapParam::__construct() - SoapParam コンストラクタ
  • SoapVar::__construct() - SoapVar コンストラクタ
  • SoapHeader::__construct() - SoapHeader コンストラクタ
  • SoapFault::__construct() - SoapFault コンストラクタ
  • is_soap_fault() - SOAP コールが失敗したかどうかを調べる


SoapServer クラス

(PHP 5, PHP 7, PHP 8)

はじめに

SoapServer クラスは » SOAP 1.1 および » SOAP 1.2 プロトコル用のサーバーとなります。 WSDL サービス記述を使用することもしないこともできます。

クラス概要

class SoapServer {
/* プロパティ */
private ?SoapFault $__soap_fault = null;
/* メソッド */
public __construct(?string $wsdl, array $options = [])
public addFunction(array|string|int $functions): void
public addSoapHeader(SoapHeader $header): void
public fault(
string $code,
string $string,
string $actor = "",
mixed $details = null,
string $name = ""
): void
public getFunctions(): array
public handle(?string $request = null): void
public setClass(string $class, mixed ...$args): void
public setObject(object $object): void
public setPersistence(int $mode): void
}

プロパティ

service

__soap_fault

目次

  • SoapServer::addFunction — SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する
  • SoapServer::addSoapHeader — SOAP ヘッダをレスポンスに追加する
  • SoapServer::__construct — SoapServer コンストラクタ
  • SoapServer::fault — エラーを示す SoapServer フォールト を発行する
  • SoapServer::getFunctions — 定義されている関数の一覧を返す
  • SoapServer::handle — SOAP リクエストを処理する
  • SoapServer::setClass — SOAP リクエストを処理するクラスを設定する
  • SoapServer::setObject — SOAP リクエストの処理に使用するオブジェクトを設定する
  • SoapServer::setPersistence — SoapServer の持続モードを設定する


SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する

  • ≪ SoapServer
  • SoapServer::addSoapHeader ≫
  • PHP Manual
  • SoapServer
  • SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する

SoapServer::addFunction

(PHP 5, PHP 7, PHP 8)

SoapServer::addFunction — SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する

説明

public SoapServer::addFunction(array|string|int $functions): void

リモートクライアント用に単一もしくは複数の関数をエクスポートします。

パラメータ

functions

単一の関数をエクスポートするには、 このパラメータに文字列として関数名を渡してください。

いくつかの関数をエクスポートするには、関数名の配列を渡してください。

全ての関数をエクスポートする場合、特別な定数 SOAP_FUNCTIONS_ALL を渡してください。

注意:

functions は、全ての入力引数を WSDL ファイルで定義されている順序と同じ順序で受け取る必要があり (これらの関数は出力パラメータを引数として受け取ることはありません) 、一つまたは複数の値を返す必要があります。 複数の値を返すには、名前付き出力パラメータの配列を返す必要があります。

戻り値

値を返しません。

例

例1 SoapServer::addFunction() の例

<?php

function echoString($inputString)
{
return $inputString;
}

$server->addFunction("echoString");

function echoTwoStrings($inputString1, $inputString2)
{
return array("outputString1" => $inputString1,
"outputString2" => $inputString2);
}
$server->addFunction(array("echoString", "echoTwoStrings"));

$server->addFunction(SOAP_FUNCTIONS_ALL);

?>

参考

  • SoapServer::__construct() - SoapServer コンストラクタ
  • SoapServer::setClass() - SOAP リクエストを処理するクラスを設定する


SOAP ヘッダをレスポンスに追加する

  • ≪ SoapServer::addFunction
  • SoapServer::__construct ≫
  • PHP Manual
  • SoapServer
  • SOAP ヘッダをレスポンスに追加する

SoapServer::addSoapHeader

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

SoapServer::addSoapHeader — SOAP ヘッダをレスポンスに追加する

説明

public SoapServer::addSoapHeader(SoapHeader $header): void

現在のリクエストから返されるレスポンスに SOAP ヘッダを追加します。

パラメータ

header

返すヘッダ。

戻り値

値を返しません。


SoapServer コンストラクタ

  • ≪ SoapServer::addSoapHeader
  • SoapServer::fault ≫
  • PHP Manual
  • SoapServer
  • SoapServer コンストラクタ

SoapServer::__construct

(PHP 5, PHP 7, PHP 8)

SoapServer::__construct — SoapServer コンストラクタ

説明

public SoapServer::__construct(?string $wsdl, array $options = [])

このコンストラクタにより SoapServer オブジェクトを WSDL または非 WSDL モードで作成することが可能です。

パラメータ

wsdl

WSDL モードの場合、これに WSDL ファイルの URI を指定する必要があります。 WSDL モードでない場合、null を指定し、uri オプションを設定する必要があります。

options

デフォルトの SOAP バージョン (soap_version), 内部の文字エンコーディング (encoding), アクターの URI (actor) を指定することができます。

classmap オプションにより、WSDL 型を PHP のクラスにマッピングすることが可能です。 このオプションには、キーとしてWSDL 型、値として PHP クラスの名前を持つ配列を指定する必要があります。

typemap オプションは、型マッピングの配列です。 この配列のキーは type_name、 type_ns (名前空間 URI)、from_xml (引数として文字列をひとつ受け取るコールバック) そして to_xml (引数としてオブジェクトをひとつ受け取るコールバック) です。

cache_wsdl オプションは、 WSDL_CACHE_NONE、 WSDL_CACHE_DISK、 WSDL_CACHE_MEMORY あるいは WSDL_CACHE_BOTH のいずれかです。

その他に features というオプションもあり、 SOAP_WAIT_ONE_WAY_CALLS、 SOAP_SINGLE_ELEMENT_ARRAYS、 SOAP_USE_XSI_ARRAY_TYPE を設定することができます。

send_errors オプションを false にすると、 個別のエラーメッセージではなく汎用的なメッセージ ("Internal error") を送信できます。

例

例1 SoapServer::__construct() の例

<?php

$server = new SoapServer("some.wsdl");

$server = new SoapServer("some.wsdl", array('soap_version' => SOAP_1_2));

$server = new SoapServer("some.wsdl", array('actor' => "http://example.org/ts-tests/C"));

$server = new SoapServer("some.wsdl", array('encoding'=>'ISO-8859-1'));

$server = new SoapServer(null, array('uri' => "http://test-uri/"));

class MyBook {
public $title;
public $author;
}

$server = new SoapServer("books.wsdl", array('classmap' => array('book' => "MyBook")));

?>

参考

  • SoapClient::__construct() - SoapClient のコンストラクタ


エラーを示す SoapServer フォールト を発行する

  • ≪ SoapServer::__construct
  • SoapServer::getFunctions ≫
  • PHP Manual
  • SoapServer
  • エラーを示す SoapServer フォールト を発行する

SoapServer::fault

(PHP 5, PHP 7, PHP 8)

SoapServer::fault — エラーを示す SoapServer フォールト を発行する

説明

public SoapServer::fault(
string $code,
string $string,
string $actor = "",
mixed $details = null,
string $name = ""
): void

現在のリクエストに対するレスポンスとして、エラーを表す内容をクライアントに送信します。

注意:

これは、リクエストを処理する際にのみコールされます。

パラメータ

code

返したいエラーコード。

string

エラーについての簡単な説明。

actor

フォールトを引き起こしたアクターをあらわす文字列。

details

フォールトについての詳細。

name

フォールトの名前。これは WSDL ファイルにある名前を使うことができます。

戻り値

値を返しません。

参考

  • SoapFault::__construct() - SoapFault コンストラクタ


定義されている関数の一覧を返す

  • ≪ SoapServer::fault
  • SoapServer::handle ≫
  • PHP Manual
  • SoapServer
  • 定義されている関数の一覧を返す

SoapServer::getFunctions

(PHP 5, PHP 7, PHP 8)

SoapServer::getFunctions — 定義されている関数の一覧を返す

説明

public SoapServer::getFunctions(): array

SoapServer オブジェクトで定義されている関数の一覧を返します。 このメソッドは、 SoapServer::addFunction() もしくは SoapServer::setClass() で追加された全ての関数の一覧を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

定義されている関数の配列を返します。

例

例1 SoapServer::getFunctions() の例

<?php
$server = new SoapServer(NULL, array("uri" => "http://test-uri"));
$server->addFunction(SOAP_FUNCTIONS_ALL);
if ($_SERVER["REQUEST_METHOD"] == "POST") {
$server->handle();
} else {
echo "This SOAP server can handle following functions: ";
$functions = $server->getFunctions();
foreach($functions as $func) {
echo $func . "\n";
}
}
?>

参考

  • SoapServer::__construct() - SoapServer コンストラクタ
  • SoapServer::addFunction() - SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する
  • SoapServer::setClass() - SOAP リクエストを処理するクラスを設定する


SOAP リクエストを処理する

  • ≪ SoapServer::getFunctions
  • SoapServer::setClass ≫
  • PHP Manual
  • SoapServer
  • SOAP リクエストを処理する

SoapServer::handle

(PHP 5, PHP 7, PHP 8)

SoapServer::handle — SOAP リクエストを処理する

説明

public SoapServer::handle(?string $request = null): void

SOAP リクエストを処理し、必要な関数をコールし、レスポンスを返送します。

パラメータ

request

SOAP リクエスト。もし引数が省略された場合、 HTTP リクエストで POST されたデータの中にリクエストがあるとみなします。

戻り値

値を返しません。

変更履歴

バージョン | 説明
8.0.0 | request は、nullable になりました。

例

例1 SoapServer::handle() の例

<?php
function test($x)
{
return $x;
}

$server = new SoapServer(null, array('uri' => "http://test-uri/"));
$server->addFunction("test");
$server->handle();
?>

参考

  • SoapServer::__construct() - SoapServer コンストラクタ


SOAP リクエストを処理するクラスを設定する

  • ≪ SoapServer::handle
  • SoapServer::setObject ≫
  • PHP Manual
  • SoapServer
  • SOAP リクエストを処理するクラスを設定する

SoapServer::setClass

(PHP 5, PHP 7, PHP 8)

SoapServer::setClass — SOAP リクエストを処理するクラスを設定する

説明

public SoapServer::setClass(string $class, mixed ...$args): void

指定されたクラスから全てのメソッドをエクスポートします。

このオブジェクトは SoapServer::setPersistence() メソッドにより指定した PHP セッションに関するリクエストをまたがる 持続性を持たせることができます

パラメータ

class

エクスポートするクラス名

args

これらのオプションパラメータは、 オブジェクト作成時にデフォルトのクラスコンストラクタに渡されます。

戻り値

値を返しません。

参考

  • SoapServer::__construct() - SoapServer コンストラクタ
  • SoapServer::addFunction() - SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する
  • SoapServer::setPersistence() - SoapServer の持続モードを設定する


SOAP リクエストの処理に使用するオブジェクトを設定する

  • ≪ SoapServer::setClass
  • SoapServer::setPersistence ≫
  • PHP Manual
  • SoapServer
  • SOAP リクエストの処理に使用するオブジェクトを設定する

SoapServer::setObject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

SoapServer::setObject — SOAP リクエストの処理に使用するオブジェクトを設定する

説明

public SoapServer::setObject(object $object): void

SOAP リクエストを処理するハンドラとして、SoapServer::setClass() のような単なるクラスではなく特定のオブジェクトを設定します。

パラメータ

object

リクエストを処理するオブジェクト。

戻り値

値を返しません。

参考

  • SoapServer::setClass() - SOAP リクエストを処理するクラスを設定する


SoapServer の持続モードを設定する

  • ≪ SoapServer::setObject
  • SoapFault ≫
  • PHP Manual
  • SoapServer
  • SoapServer の持続モードを設定する

SoapServer::setPersistence

(PHP 5, PHP 7, PHP 8)

SoapServer::setPersistence — SoapServer の持続モードを設定する

説明

public SoapServer::setPersistence(int $mode): void

この関数により、SoapServer オブジェクトの永続状態をリクエスト間で変更できるようになります。 この関数は、リクエスト間でのデータの保存に PHP のセッションを使います。 このメソッドが SoapServer に影響を及ぼすのは、SoapServer::setClass() を使って関数をエクスポートした後となります。

注意:

持続モード SOAP_PERSISTENCE_SESSION は、そのクラスのオブジェクトについてのみ持続させます。 クラスのスタティックなデータについては対象となりません。 self::$bar ではなく $this->bar を使用しましょう。

注意:

SOAP_PERSISTENCE_SESSION は、クラスのオブジェクト上のデータもリクエスト間でシリアライズします。 リソース (PDO など) を適切に扱うには、マジックメソッド __wakeup() および __sleep() を使う必要があります。

パラメータ

mode

SOAP_PERSISTENCE_XXX 定数のうちの一つ

SOAP_PERSISTENCE_REQUEST - SoapServer のデータはリクエスト間で持続しません。 これは、SoapServer オブジェクトで setClass をコールした直後のデフォルトの挙動です。

SOAP_PERSISTENCE_SESSION - SoapServer のデータをリクエスト間で持続させます。 これを実現するために、SoapServer クラスのデータをシリアライズして $_SESSION['_bogus_session_name'] に格納します。 そのため、このモードを設定する前に session_start() をコールしておく必要があります。

戻り値

値を返しません。

例

例1 SoapServer::setPersistence() の例

<?php
class MyFirstPersistentSoapServer {
private $resource; // (Such as PDO, mysqli, etc..)
public $myvar1;
public $myvar2;

public function __construct() {
$this->__wakeup(); // We're calling our wakeup to handle starting our resource
}

public function __wakeup() {
$this->resource = CodeToStartOurResourceUp();
}

public function __sleep() {
// We make sure to leave out $resource here, so our session data remains persistent
// Failure to do so will result in the failure during the unserialization of data
// on the next request; thus, our SoapObject would not be persistent across requests.
return array('myvar1','myvar2');
}
}

try {
session_start();
$server = new SoapServer(null, array('uri' => $_SERVER['REQUEST_URI']));
$server->setClass('MyFirstPersistentSoapServer');
// setPersistence MUST be called after setClass, because setClass's
// behavior sets SESSION_PERSISTENCE_REQUEST upon enacting the method.
$server->setPersistence(SOAP_PERSISTENCE_SESSION);
$server->handle();
} catch(SoapFault $e) {
error_log("SOAP ERROR: ". $e->getMessage());
}
?>

参考

  • SoapServer::setClass() - SOAP リクエストを処理するクラスを設定する


SoapFault クラス

(PHP 5, PHP 7, PHP 8)

はじめに

SOAP fault をあらわします。

クラス概要

class SoapFault extends Exception {
/* プロパティ */
public string $faultstring;
public ?string $faultcode = null;
public ?string $faultcodens = null;
public ?string $faultactor = null;
public mixed $detail = null;
public ?string $_name = null;
public mixed $headerfault = null;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
public __construct(
array|string|null $code,
string $string,
?string $actor = null,
mixed $details = null,
?string $name = null,
mixed $headerFault = null
)
public __toString(): string
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

_name

detail

faultactor

faultcode

faultcodens

faultstring

headerfault

目次

  • SoapFault::__construct — SoapFault コンストラクタ
  • SoapFault::__toString — SoapFault の文字列表現を取得する


SoapFault コンストラクタ

  • ≪ SoapFault
  • SoapFault::__toString ≫
  • PHP Manual
  • SoapFault
  • SoapFault コンストラクタ

SoapFault::__construct

(PHP 5, PHP 7, PHP 8)

SoapFault::__construct — SoapFault コンストラクタ

説明

public SoapFault::__construct(
array|string|null $code,
string $string,
?string $actor = null,
mixed $details = null,
?string $name = null,
mixed $headerFault = null
)

このクラスは、PHP ハンドラから SOAP フォールトレスポンスを送信した場合に有用です。 faultcode, faultstring, faultactor および detail は SOAP フォールトの標準的な要素です。

パラメータ

faultcode

SoapFault のエラーコード

faultstring

SoapFault のエラーメッセージ

faultactor

エラーの原因となったアクターを識別する文字列

detail

エラーの原因についての詳細な情報

faultname

WSDL からの厳密なフォールトエンコーディングを取得するために利用可能

headerfault

レスポンスヘッダにおいて SOAP ハンドラがエラーの報告処理を行っている間に利用可能

例

例1 いくつかの例

<?php
function test($x)
{
return new SoapFault("Server", "Some error message");
}

$server = new SoapServer(null, array('uri' => "http://test-uri/"));
$server->addFunction("test");
$server->handle();
?>

SOAP フォールトをスローするために PHP の例外機構を使用することができます。

例2 いくつかの例

<?php
function test($x)
{
throw new SoapFault("Server", "Some error message");
}

$server = new SoapServer(null, array('uri' => "http://test-uri/"));
$server->addFunction("test");
$server->handle();
?>

参考

  • SoapServer::fault() - エラーを示す SoapServer フォールト を発行する
  • is_soap_fault() - SOAP コールが失敗したかどうかを調べる


SoapFault の文字列表現を取得する

  • ≪ SoapFault::__construct
  • SoapHeader ≫
  • PHP Manual
  • SoapFault
  • SoapFault の文字列表現を取得する

SoapFault::__toString

(PHP 5, PHP 7, PHP 8)

SoapFault::__toString — SoapFault の文字列表現を取得する

説明

public SoapFault::__toString(): string

SoapFault の文字列表現を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

SoapFault を文字列であらわした内容を返します。


SoapHeader クラス

(PHP 5, PHP 7, PHP 8)

はじめに

SOAP ヘッダをあらわします。

クラス概要

class SoapHeader {
/* プロパティ */
public string $namespace;
public string $name;
public mixed $data = null;
public bool $mustUnderstand;
public string|int|null $actor;
/* メソッド */
public __construct(
string $namespace,
string $name,
mixed $data = ?,
bool $mustunderstand = ?,
string $actor = ?
)
}

プロパティ

actor

data

mustUnderstand

name

namespace

目次

  • SoapHeader::__construct — SoapHeader コンストラクタ


SoapHeader コンストラクタ

  • ≪ SoapHeader
  • SoapParam ≫
  • PHP Manual
  • SoapHeader
  • SoapHeader コンストラクタ

SoapHeader::__construct

(PHP 5, PHP 7, PHP 8)

SoapHeader::__construct — SoapHeader コンストラクタ

説明

public SoapHeader::__construct(
string $namespace,
string $name,
mixed $data = ?,
bool $mustunderstand = ?,
string $actor = ?
)

新しい SoapHeader オブジェクトを生成します。

パラメータ

namespace

SOAP ヘッダ要素の名前空間

name

SOAP ヘッダ要素の名前

data

SOAP ヘッダの内容。PHP の値もしくは SoapVar オブジェクトです。

mustUnderstand

SOAP ヘッダ要素の mustUnderstand 属性の値

actor

SOAP ヘッダ要素の actor 属性の値

例

例1 SoapHeader::__construct() の例

<?php
$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));
$client->__soapCall("echoVoid", null, null,
new SoapHeader('http://soapinterop.org/echoheader/',
'echoMeStringRequest',
'hello world'));
?>

参考

  • SoapClient::__soapCall() - SOAP 関数をコールする
  • SoapVar::__construct() - SoapVar コンストラクタ
  • SoapParam::__construct() - SoapParam コンストラクタ
  • SoapServer::addSoapHeader() - SOAP ヘッダをレスポンスに追加する


SoapParam クラス

(PHP 5, PHP 7, PHP 8)

はじめに

SOAP コールのパラメータをあらわします。

クラス概要

class SoapParam {
/* プロパティ */
public string $param_name;
public mixed $param_data;
/* メソッド */
public __construct(mixed $data, string $name)
}

プロパティ

param_data

param_name

目次

  • SoapParam::__construct — SoapParam コンストラクタ


SoapParam コンストラクタ

  • ≪ SoapParam
  • SoapVar ≫
  • PHP Manual
  • SoapParam
  • SoapParam コンストラクタ

SoapParam::__construct

(PHP 5, PHP 7, PHP 8)

SoapParam::__construct — SoapParam コンストラクタ

説明

public SoapParam::__construct(mixed $data, string $name)

新しい SoapParam オブジェクトを生成します。

パラメータ

data

渡すもしくは返すデータ。 PHP の値としてこのパラメータを直接渡すことができますが、この場合、 paramN という名前が付けられますので SOAP サービスがこれを理解しないかも知れません。

name

パラメータの名前

例

例1 SoapParam::__construct() の例

<?php
$client = new SoapClient(null,array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));
$client->SomeFunction(new SoapParam($a, "a"),
new SoapParam($b, "b"),
new SoapParam($c, "c"));
?>

参考

  • SoapClient::__soapCall() - SOAP 関数をコールする
  • SoapVar::__construct() - SoapVar コンストラクタ


SoapVar クラス

(PHP 5, PHP 7, PHP 8)

はじめに

SOAP サービスが使用する変数やオブジェクトをあらわします。

クラス概要

class SoapVar {
/* プロパティ */
public int $enc_type;
public mixed $enc_value = null;
public ?string $enc_stype = null;
public ?string $enc_ns = null;
public ?string $enc_name = null;
public ?string $enc_namens = null;
/* メソッド */
public __construct(
mixed $data,
?int $encoding,
?string $typeName = null,
?string $typeNamespace = null,
?string $nodeName = null,
?string $nodeNamespace = null
)
}

プロパティ

enc_name

enc_namens

enc_ns

enc_type

enc_stype

enc_value

目次

  • SoapVar::__construct — SoapVar コンストラクタ


SoapVar コンストラクタ

  • ≪ SoapVar
  • Yar ≫
  • PHP Manual
  • SoapVar
  • SoapVar コンストラクタ

SoapVar::__construct

(PHP 5, PHP 7, PHP 8)

SoapVar::__construct — SoapVar コンストラクタ

説明

public SoapVar::__construct(
mixed $data,
?int $encoding,
?string $typeName = null,
?string $typeNamespace = null,
?string $nodeName = null,
?string $nodeNamespace = null
)

新しい SoapVar オブジェクトを生成します。

パラメータ

data

渡すもしくは返すデータ

encoding

エンコーディング ID。XSD_... 定数のうちの一つ。

type_name

型の名前

type_namespace

型の名前空間

node_name

XML ノードの名前

node_namespace

XML ノードの名前空間

変更履歴

バージョン | 説明
8.0.3 | typeName, typeNamespace, nodeName, nodeNamespace は、nullable になりました。

例

例1 SoapVar::__construct() の例

<?php
class SOAPStruct {
function SOAPStruct($s, $i, $f)
{
$this->varString = $s;
$this->varInt = $i;
$this->varFloat = $f;
}
}
$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
'uri' => "http://test-uri/"));
$struct = new SOAPStruct('arg', 34, 325.325);
$soapstruct = new SoapVar($struct, SOAP_ENC_OBJECT, "SOAPStruct", "http://soapinterop.org/xsd");
$client->echoStruct(new SoapParam($soapstruct, "inputStruct"));
?>

参考

  • SoapClient::__soapCall() - SOAP 関数をコールする
  • SoapParam::__construct() - SoapParam コンストラクタ


Yet Another RPC Framework

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • リソース型
  • 定義済み定数
  • 例
  • Yar_Server — The Yar_Server class
    • Yar_Server::__construct — Register a server
    • Yar_Server::handle — Start RPC Server
  • Yar_Client — The Yar_Client class
    • Yar_Client::__call — Call service
    • Yar_Client::__construct — Create a client
    • Yar_Client::setOpt — Set calling contexts
  • Yar_Concurrent_Client — The Yar_Concurrent_Client class
    • Yar_Concurrent_Client::call — Register a concurrent call
    • Yar_Concurrent_Client::loop — Send all calls
    • Yar_Concurrent_Client::reset — Clean all registered calls
  • Yar_Server_Exception — The Yar_Server_Exception class
    • Yar_Server_Exception::getType — Retrieve exception's type
  • Yar_Client_Exception — The Yar_Client_Exception class
    • Yar_Client_Exception::getType — Retrieve exception's type


はじめに

Yar is a RPC framework which aims to provide a simple and easy way to do communication between PHP applications It has the ability to concurrently call multiple remote services.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • Yar
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • リソース型


要件

if you want to use msgpack as packager, you need compile Yar by your self with ./configure --enable-msgpack


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/yar.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください


実行時設定

php.ini の設定により動作が変化します。

Yar 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
yar.packager | php | INI_SYSTEM |
yar.debug | Off | INI_ALL |
yar.connect_timeout | 1000 | INI_ALL |
yar.timeout | 5000 | INI_ALL |
yar.expose_info | On | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

yar.packager string

it could be php, json, and msgpack(require built with msgpack support)

yar.debug string

yar.connect_timeout int

timeout in ms

yar.timeout int

timeout in ms

yar.expose_info bool

whether expose the service info(when access the server via GET)


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

YAR_VERSION (string)
YAR_CLIENT_PROTOCOL_HTTP (int)
YAR_OPT_PACKAGER (int)
YAR_OPT_TIMEOUT (int)
YAR_OPT_CONNECT_TIMEOUT (int)
YAR_OPT_HEADER (array)
2.0.4 以降
YAR_PACKAGER_PHP (string)
YAR_PACKAGER_JSON (string)
YAR_ERR_OKEY (int)
YAR_ERR_OUTPUT (int)
YAR_ERR_TRANSPORT (int)
YAR_ERR_REQUEST (int)
YAR_ERR_PROTOCOL (int)
YAR_ERR_PACKAGER (int)
YAR_ERR_EXCEPTION (int)


例

例1 Yar Server Example

<?php

/* assume this page can be accessed by http://example.com/operator.php */

class Operator {

/**
* Add two operands
* @param interge
* @return interge
*/
public function add($a, $b) {
return $this->_add($a, $b);
}

/**
* Sub
*/
public function sub($a, $b) {
return $a - $b;
}

/**
* Mul
*/
public function mul($a, $b) {
return $a * $b;
}

/**
* Protected methods will not be exposed
* @param interge
* @return interge
*/
protected function _add($a, $b) {
return $a + $b;
}
}

$server = new Yar_Server(new Operator());
$server->handle();
?>

例2 Access the server in borwser(GET request)

上の例の出力は、 たとえば以下のようになります。

Yar Server Info

例3 Yar Client Example

<?php
$client = new yar_client("http://example.com/operator.php");

/* call directly */
var_dump($client->add(1, 2));

/* call via call */
var_dump($client->call("add", array(3, 2)));

/* __add can not be called */
var_dump($client->_add(1, 2));
?>

上の例の出力は、 たとえば以下のようになります。

int(3)
int(5)
PHP Fatal error:  Uncaught exception 'Yar_Server_Exception' with message 'call to api Operator::_add() failed' in *

例4 Yar Concurrent Client Example

<?php
function callback($ret, $callinfo) {
echo $callinfo['method'] , " result: ", $ret , "\n";
}

/* register async call to remote services */
Yar_Concurrent_Client::call("http://example.com/operator.php", "add", array(1, 2), "callback");
Yar_Concurrent_Client::call("http://example.com/operator.php", "sub", array(2, 1), "callback");
Yar_Concurrent_Client::call("http://example.com/operator.php", "mul", array(2, 2), "callback");

/* sent all request and wait for response */
Yar_Concurrent_Client::loop();
?>

上の例の出力は、 たとえば以下のようになります。

mul result: 4
sub result: 1
add result: 3


The Yar_Server class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

class Yar_Server {
/* プロパティ */
protected $_executor;
/* メソッド */
final public __construct(Object $obj)
public handle(): bool
}

プロパティ

_executor

目次

  • Yar_Server::__construct — Register a server
  • Yar_Server::handle — Start RPC Server


Register a server

  • ≪ Yar_Server
  • Yar_Server::handle ≫
  • PHP Manual
  • Yar_Server
  • Register a server

Yar_Server::__construct

(PECL yar >= 1.0.0)

Yar_Server::__construct — Register a server

説明

final public Yar_Server::__construct(Object $obj)

Set up a Yar HTTP RPC Server, All the public methods of $obj will be register as a RPC service.

パラメータ

obj

An Object, all public methods of its will be registered as RPC services.

戻り値

An instance of Yar_Server.

例

例1 Yar_Server::__construct() example

<?php
class API {
/**
* the doc info will be generated automatically into service info page.
* @params
* @return
*/
public function some_method($parameter, $option = "foo") {
return "some_method";
}

protected function client_can_not_see() {
}
}

$service = new Yar_Server(new API());
$service->handle();
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Server::handle() - Start RPC Server
    •


Start RPC Server

  • ≪ Yar_Server::__construct
  • Yar_Client ≫
  • PHP Manual
  • Yar_Server
  • Start RPC Server

Yar_Server::handle

(PECL yar >= 1.0.0)

Yar_Server::handle — Start RPC Server

説明

public Yar_Server::handle(): bool

Start a RPC HTTP server, and ready for accpet RPC requests.

注意:

Usual RPC calls will be issued as HTTP POST requests. If a HTTP GET request is issued to the uri, the service information (commented section above) will be printed on the page

パラメータ

この関数にはパラメータはありません。

戻り値

boolean

例

例1 Yar_Server::handle() example

<?php
class API {
/**
* the doc info will be generated automatically into service info page.
* @params
* @return
*/
public function some_method($parameter, $option = "foo") {
}

protected function client_can_not_see() {
}
}

$service = new Yar_Server(new API());
$service->handle();
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Server::__construct() - Register a server
    •


The Yar_Client class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

class Yar_Client {
/* プロパティ */
protected $_protocol;
protected $_uri;
protected $_options;
protected $_running;
/* メソッド */
public __call(string $method, array $parameters): void
final public __construct(string $url, array $options = ?)
public setOpt(int $name, mixed $value): Yar_Client|false
}

プロパティ

_protocol

_uri

_options

_running

目次

  • Yar_Client::__call — Call service
  • Yar_Client::__construct — Create a client
  • Yar_Client::setOpt — Set calling contexts


Call service

  • ≪ Yar_Client
  • Yar_Client::__construct ≫
  • PHP Manual
  • Yar_Client
  • Call service

Yar_Client::__call

(PECL yar >= 1.0.0)

Yar_Client::__call — Call service

説明

public Yar_Client::__call(string $method, array $parameters): void

Issue a call to remote RPC method.

パラメータ

method

Remote RPC method name.

parameters

Parameters.

戻り値

例

例1 Yar_Client::__call() example

<?php

$client = new Yar_Client("http://host/api/");

/* call remote service */
$result = $client->some_method("parameter");
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Client::setOpt() - Set calling contexts
    •


Create a client

  • ≪ Yar_Client::__call
  • Yar_Client::setOpt ≫
  • PHP Manual
  • Yar_Client
  • Create a client

Yar_Client::__construct

(PECL yar >= 1.0.0)

Yar_Client::__construct — Create a client

説明

final public Yar_Client::__construct(string $url, array $options = ?)

Create a Yar_Client to a Yar_Server.

パラメータ

url

Yar Server URL.

戻り値

Yar_Client instance.

例

例1 Yar_Client::__construct() example

<?php
$client = new Yar_Client("http://host/api/");
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Client::__call() - Call service
    •

  • Yar_Client::setOpt() - Set calling contexts
    •


Set calling contexts

  • ≪ Yar_Client::__construct
  • Yar_Concurrent_Client ≫
  • PHP Manual
  • Yar_Client
  • Set calling contexts

Yar_Client::setOpt

(PECL yar >= 1.0.0)

Yar_Client::setOpt — Set calling contexts

説明

public Yar_Client::setOpt(int $name, mixed $value): Yar_Client|false

パラメータ

name

it can be: YAR_OPT_PACKAGER, YAR_OPT_PERSISTENT (Need server support), YAR_OPT_TIMEOUT, YAR_OPT_CONNECT_TIMEOUT, YAR_OPT_HEADER (as of 2.0.4), YAR_OPT_PROXY (as of 2.2.0)

value

戻り値

Returns $this on success失敗した場合に false を返します.

例

例1 Yar_Client::setOpt() example

<?php

$cient = new Yar_Client("http://host/api/");

//Set timeout to 1s
$client->SetOpt(YAR_OPT_CONNECT_TIMEOUT, 1000);

//Set packager to JSON
$client->SetOpt(YAR_OPT_PACKAGER, "json");

//Set Custom headers
$client->SetOpt(YAR_OPT_HEADER, array("hr1: val1", "hd2: val2"));

// Set Http Proxy
$client->SetOpt(YAR_OPT_PROXY, "127.0.0.1:8888");

/* call remote service */
$result = $client->some_method("parameter");
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Client::__call() - Call service
    •


The Yar_Concurrent_Client class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

class Yar_Concurrent_Client {
/* プロパティ */
static $_callstack;
static $_callback;
static $_error_callback;
/* メソッド */
public static call(
string $uri,
string $method,
array $parameters = ?,
callable $callback = ?,
callable $error_callback = ?,
array $options = ?
): int
public static loop(callable $callback = ?, callable $error_callback = ?): bool
public static reset(): bool
}

プロパティ

_callstack

_callback

_error_callback

目次

  • Yar_Concurrent_Client::call — Register a concurrent call
  • Yar_Concurrent_Client::loop — Send all calls
  • Yar_Concurrent_Client::reset — Clean all registered calls


Register a concurrent call

  • ≪ Yar_Concurrent_Client
  • Yar_Concurrent_Client::loop ≫
  • PHP Manual
  • Yar_Concurrent_Client
  • Register a concurrent call

Yar_Concurrent_Client::call

(PECL yar >= 1.0.0)

Yar_Concurrent_Client::call — Register a concurrent call

説明

public static Yar_Concurrent_Client::call(
string $uri,
string $method,
array $parameters = ?,
callable $callback = ?,
callable $error_callback = ?,
array $options = ?
): int

Register a RPC call, but won't sent it immediately, it will be send while further call to Yar_Concurrent_Client::loop()

パラメータ

uri

The RPC server URI(http, tcp)

method

Service name(aka the method name)

parameters

Parameters

callback

A function callback, which will be called while the response return.

戻り値

An unique id, can be used to identified which call it is.

例

例1 Yar_Concurrent_Client::call() example

<?php
function callback($retval, $callinfo) {
var_dump($retval);
}

function error_callback($type, $error, $callinfo) {
error_log($error);
}

Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback");
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters")); // if the callback is not specificed,
// callback in loop will be used
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json"));
//this server accept json packager
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT=>1));
//custom timeout

//The requests are not sent yet
?>

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Concurrent_Client::loop() - Send all calls
    •

  • Yar_Concurrent_Client::reset() - Clean all registered calls
    •

  • Yar_Server::__construct() - Register a server
    •

  • Yar_Server::handle() - Start RPC Server
    •


Send all calls

  • ≪ Yar_Concurrent_Client::call
  • Yar_Concurrent_Client::reset ≫
  • PHP Manual
  • Yar_Concurrent_Client
  • Send all calls

Yar_Concurrent_Client::loop

(PECL yar >= 1.0.0)

Yar_Concurrent_Client::loop — Send all calls

説明

public static Yar_Concurrent_Client::loop(callable $callback = ?, callable $error_callback = ?): bool

Send all registed remote RPC calls.

パラメータ

callback

If this callback is set, then Yar will call this callback after all calls are sent and before any response return, with a $callinfo NULL.

Then, if user didn't specify callback when registering concurrent call, this callback will be used to handle response, otherwise, the callback specified while registering will be used.

error_callback

If this callback is set, then Yar will call this callback while error occurred.

戻り値

例

例1 Yar_Concurrent_Client::loop() example

<?php
function callback($retval, $callinfo) {
if ($callinfo == NULL) {
echo "Now, all requests are sent, and no any response available\n";
} else {
echo "This is a remote call response, the method name is", $callinfo["method"],
". calling sequence is " , $callinfo["sequence"] , "\n";
var_dump($retval);
}
}

function error_callback($type, $error, $callinfo) {
error_log($error);
}

Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback");
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters")); // if the callback is not specificed,
// callback in loop will be used
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json"));
//this server accept json packager
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT=>1));
//custom timeout

Yar_Concurrent_Client::loop("callback", "error_callback"); //send the requests,
//the error_callback is optional
?>

上の例の出力は、 たとえば以下のようになります。

Now, all requests are sent, and no any response available
This is a remote call response, the method name issome_method. calling sequence is 4
string(11) "some_method"
This is a remote call response, the method name issome_method. calling sequence is 1
string(11) "some_method"
This is a remote call response, the method name issome_method. calling sequence is 2
string(11) "some_method"
This is a remote call response, the method name issome_method. calling sequence is 3
string(11) "some_method"

参考

  • Yar_Concurrent_Client::call() - Register a concurrent call
  • Yar_Concurrent_Client::reset() - Clean all registered calls
  • Yar_Server::__construct() - Register a server
  • Yar_Server::handle() - Start RPC Server


Clean all registered calls

  • ≪ Yar_Concurrent_Client::loop
  • Yar_Server_Exception ≫
  • PHP Manual
  • Yar_Concurrent_Client
  • Clean all registered calls

Yar_Concurrent_Client::reset

(PECL yar >= 1.2.4)

Yar_Concurrent_Client::reset — Clean all registered calls

説明

public static Yar_Concurrent_Client::reset(): bool

Clean all registered calls

パラメータ

この関数にはパラメータはありません。

戻り値

例

例1 Yar_Concurrent_Client::reset() example

上の例の出力は、 たとえば以下のようになります。

参考

  • Yar_Concurrent_Client::call() - Register a concurrent call
    •

  • Yar_Concurrent_Client::loop() - Send all calls
    •

  • Yar_Server::__construct() - Register a server
    •

  • Yar_Server::handle() - Start RPC Server
    •


The Yar_Server_Exception class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

If service threw exceptions, A Yar_Server_Exception will be threw in client side.

クラス概要

class Yar_Server_Exception extends Exception {
/* プロパティ */
protected $_type;
/* メソッド */
public getType(): string
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

message

code

file

line

_type

目次

  • Yar_Server_Exception::getType — Retrieve exception's type


Retrieve exception's type

  • ≪ Yar_Server_Exception
  • Yar_Client_Exception ≫
  • PHP Manual
  • Yar_Server_Exception
  • Retrieve exception's type

Yar_Server_Exception::getType

(PECL yar >= 1.0.0)

Yar_Server_Exception::getType — Retrieve exception's type

説明

public Yar_Server_Exception::getType(): string

Get the exception original type threw by server

パラメータ

この関数にはパラメータはありません。

戻り値

string

例

例1 Yar_Server_Exception::getType() example

//Server.php
<?php
class Custom_Exception extends Exception {};

class API {
public function throw_exception($name) {
throw new Custom_Exception($name);
}
}

$service = new Yar_Server(new API());
$service->handle();
?>

//Client.php
<?php
$client = new Yar_Client("http://host/api.php");

try {
$client->throw_exception("client");
} catch (Yar_Server_Exception $e) {
var_dump($e->getType());
var_dump($e->getMessage());
}

上の例の出力は、 たとえば以下のようになります。

string(16) "Custom_Exception"
string(6) "client"

参考


The Yar_Client_Exception class

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

はじめに

クラス概要

class Yar_Client_Exception extends Exception {
/* プロパティ */
/* メソッド */
public getType(): string
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

message

code

file

line

目次

  • Yar_Client_Exception::getType — Retrieve exception's type


Retrieve exception's type

  • ≪ Yar_Client_Exception
  • XML-RPC ≫
  • PHP Manual
  • Yar_Client_Exception
  • Retrieve exception's type

Yar_Client_Exception::getType

(PECL yar >= 1.0.0)

Yar_Client_Exception::getType — Retrieve exception's type

説明

public Yar_Client_Exception::getType(): string

パラメータ

この関数にはパラメータはありません。

戻り値

Returns "Yar_Exception_Client".

例

例1 Yar_Client_Exception::getType() example

<?php

/* ... */

?>

上の例の出力は、 たとえば以下のようになります。

...

参考

  • Yaf_Server_Exception::getType()


XML-RPC

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • XML-RPC 関数
    • xmlrpc_decode — XML をネイティブな PHP 型にデコードする
    • xmlrpc_decode_request — XML をネイティブなPHP 型にデコードする
    • xmlrpc_encode — PHP の値に関する XML を生成する
    • xmlrpc_encode_request — メソッドリクエスト用の XML を生成する
    • xmlrpc_get_type — PHP の値に関する xmlrpc 型を取得する
    • xmlrpc_is_fault — 配列の値が XMLRPC の失敗であるかどうかを調べる
    • xmlrpc_parse_method_descriptions — XML を、メソッド説明のリストにデコードする
    • xmlrpc_server_add_introspection_data — introspection ドキュメントを追加する
    • xmlrpc_server_call_method — XML リクエストをパースし、メソッドをコールする
    • xmlrpc_server_create — xmlrpc サーバーを作成する
    • xmlrpc_server_destroy — サーバーリソースを破棄する
    • xmlrpc_server_register_introspection_callback — ドキュメントを生成する PHP 関数を登録する
    • xmlrpc_server_register_method — メソッド名が一致するメソッドリソースに PHP 関数を登録する
    • xmlrpc_set_type — PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する


はじめに

これらの関数を使うと、XML-RPCサーバーおよびクライアントを書くことができます。 XML-RPCに関する詳細な情報については、 » http://www.xmlrpc.com/ を参照ください。 そして、この拡張モジュールと関数に関する詳細なドキュメントについては、 » http://xmlrpc-epi.sourceforge.net/を参照ください。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XML-RPC
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


インストール手順

PHPのXML-RPCサポートはデフォルトでは有効となっていません。 XML-RPCサポートを有効にするには、PHPをコンパイルする際に設定オプション --with-xmlrpc[=DIR] を使用する必要があります。


リソース型

この拡張モジュールでは XML-RPC サーバーリソースを定義しています。これは xmlrpc_server_create() が返すものです。


XML-RPC 関数

目次

  • xmlrpc_decode — XML をネイティブな PHP 型にデコードする
  • xmlrpc_decode_request — XML をネイティブなPHP 型にデコードする
  • xmlrpc_encode — PHP の値に関する XML を生成する
  • xmlrpc_encode_request — メソッドリクエスト用の XML を生成する
  • xmlrpc_get_type — PHP の値に関する xmlrpc 型を取得する
  • xmlrpc_is_fault — 配列の値が XMLRPC の失敗であるかどうかを調べる
  • xmlrpc_parse_method_descriptions — XML を、メソッド説明のリストにデコードする
  • xmlrpc_server_add_introspection_data — introspection ドキュメントを追加する
  • xmlrpc_server_call_method — XML リクエストをパースし、メソッドをコールする
  • xmlrpc_server_create — xmlrpc サーバーを作成する
  • xmlrpc_server_destroy — サーバーリソースを破棄する
  • xmlrpc_server_register_introspection_callback — ドキュメントを生成する PHP 関数を登録する
  • xmlrpc_server_register_method — メソッド名が一致するメソッドリソースに PHP 関数を登録する
  • xmlrpc_set_type — PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する


XML をネイティブな PHP 型にデコードする

  • ≪ XML-RPC 関数
  • xmlrpc_decode_request ≫
  • PHP Manual
  • XML-RPC 関数
  • XML をネイティブな PHP 型にデコードする

xmlrpc_decode

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_decode — XML をネイティブな PHP 型にデコードする

説明

xmlrpc_decode(string $xml, string $encoding = "iso-8859-1"): mixed
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

xml

XMLRPC メソッドが返す XML レスポンス。

encoding

iconv がサポートする入力エンコーディング。

戻り値

XMLRPC メソッドのレスポンスをもとに作成した、 配列あるいは整数、文字列、boolean 値を返します。

例

xmlrpc_encode_request() の例を参照ください。

参考

  • xmlrpc_encode_request() - メソッドリクエスト用の XML を生成する
  • xmlrpc_is_fault() - 配列の値が XMLRPC の失敗であるかどうかを調べる


XML をネイティブなPHP 型にデコードする

  • ≪ xmlrpc_decode
  • xmlrpc_encode ≫
  • PHP Manual
  • XML-RPC 関数
  • XML をネイティブなPHP 型にデコードする

xmlrpc_decode_request

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_decode_request — XML をネイティブなPHP 型にデコードする

説明

xmlrpc_decode_request(string $xml, string &$method, string $encoding = ?): mixed
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


PHP の値に関する XML を生成する

  • ≪ xmlrpc_decode_request
  • xmlrpc_encode_request ≫
  • PHP Manual
  • XML-RPC 関数
  • PHP の値に関する XML を生成する

xmlrpc_encode

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_encode — PHP の値に関する XML を生成する

説明

xmlrpc_encode(mixed $value): string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


メソッドリクエスト用の XML を生成する

  • ≪ xmlrpc_encode
  • xmlrpc_get_type ≫
  • PHP Manual
  • XML-RPC 関数
  • メソッドリクエスト用の XML を生成する

xmlrpc_encode_request

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_encode_request — メソッドリクエスト用の XML を生成する

説明

xmlrpc_encode_request(string $method, mixed $params, array $output_options = ?): string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

method

コールするメソッドの名前。

params

メソッドのシグネチャに対応したパラメータ。

output_options

出力オプションを指定する配列。以下の内容が指定できます (強調してあるものがデフォルトです)。

  • output_type: php, xml

  • verbosity: no_white_space, newlines_only, pretty

  • escaping: cdata, non-ascii, non-print, markup (単一の値を表す文字列、あるいは複数の値の配列となります)

  • version: simple, xmlrpc, soap 1.1, auto

  • encoding: iso-8859-1, その他 iconv がサポートする文字セット

戻り値

リクエストを表す XML 文字列を返します。

例

例1 XMLRPC クライアント関数の例

<?php
$request = xmlrpc_encode_request("method", array(1, 2, 3));
$context = stream_context_create(array('http' => array(
'method' => "POST",
'header' => "Content-Type: text/xml",
'content' => $request
)));
$file = file_get_contents("http://www.example.com/xmlrpc", false, $context);
$response = xmlrpc_decode($file);
if ($response && xmlrpc_is_fault($response)) {
trigger_error("xmlrpc: $response[faultString] ($response[faultCode])");
} else {
print_r($response);
}
?>

参考

  • stream_context_create() - ストリームコンテキストを作成する
  • file_get_contents() - ファイルの内容を全て文字列に読み込む
  • xmlrpc_decode() - XML をネイティブな PHP 型にデコードする


PHP の値に関する xmlrpc 型を取得する

  • ≪ xmlrpc_encode_request
  • xmlrpc_is_fault ≫
  • PHP Manual
  • XML-RPC 関数
  • PHP の値に関する xmlrpc 型を取得する

xmlrpc_get_type

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_get_type — PHP の値に関する xmlrpc 型を取得する

説明

xmlrpc_get_type(mixed $value): string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

この関数は特に base64 及び datetime 文字列で有用です。

パラメータ

value

PHP の値。

戻り値

XML-RPC の型を返します。

例

例1 XML-RPC の型の例

<?php
echo xmlrpc_get_type(null) . "\n"; // base64
echo xmlrpc_get_type(false) . "\n"; // boolean
echo xmlrpc_get_type(1) . "\n"; // int
echo xmlrpc_get_type(1.0) . "\n"; // double
echo xmlrpc_get_type("") . "\n"; // string
echo xmlrpc_get_type(array()) . "\n"; // array
echo xmlrpc_get_type(new stdClass) . "\n"; // array
echo xmlrpc_get_type(STDIN) . "\n"; // int
?>

参考

  • xmlrpc_set_type() - PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する


配列の値が XMLRPC の失敗であるかどうかを調べる

  • ≪ xmlrpc_get_type
  • xmlrpc_parse_method_descriptions ≫
  • PHP Manual
  • XML-RPC 関数
  • 配列の値が XMLRPC の失敗であるかどうかを調べる

xmlrpc_is_fault

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

xmlrpc_is_fault — 配列の値が XMLRPC の失敗であるかどうかを調べる

説明

xmlrpc_is_fault(array $arg): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

arg

xmlrpc_decode() が返す配列。

戻り値

引数が失敗を表す場合に true、それ以外の場合に false を返します。 失敗の内容は $arg["faultString"]、失敗のコードは $arg["faultCode"] に格納されます。

例

xmlrpc_encode_request() の例を参照ください。

参考

  • xmlrpc_decode() - XML をネイティブな PHP 型にデコードする


XML を、メソッド説明のリストにデコードする

  • ≪ xmlrpc_is_fault
  • xmlrpc_server_add_introspection_data ≫
  • PHP Manual
  • XML-RPC 関数
  • XML を、メソッド説明のリストにデコードする

xmlrpc_parse_method_descriptions

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_parse_method_descriptions — XML を、メソッド説明のリストにデコードする

説明

xmlrpc_parse_method_descriptions(string $xml): array
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


introspection ドキュメントを追加する

  • ≪ xmlrpc_parse_method_descriptions
  • xmlrpc_server_call_method ≫
  • PHP Manual
  • XML-RPC 関数
  • introspection ドキュメントを追加する

xmlrpc_server_add_introspection_data

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_server_add_introspection_data — introspection ドキュメントを追加する

説明

xmlrpc_server_add_introspection_data(resource $server, array $desc): int
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


XML リクエストをパースし、メソッドをコールする

  • ≪ xmlrpc_server_add_introspection_data
  • xmlrpc_server_create ≫
  • PHP Manual
  • XML-RPC 関数
  • XML リクエストをパースし、メソッドをコールする

xmlrpc_server_call_method

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_server_call_method — XML リクエストをパースし、メソッドをコールする

説明

xmlrpc_server_call_method(
resource $server,
string $xml,
mixed $user_data,
array $output_options = ?
): string
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


xmlrpc サーバーを作成する

  • ≪ xmlrpc_server_call_method
  • xmlrpc_server_destroy ≫
  • PHP Manual
  • XML-RPC 関数
  • xmlrpc サーバーを作成する

xmlrpc_server_create

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_server_create — xmlrpc サーバーを作成する

説明

xmlrpc_server_create(): resource
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


サーバーリソースを破棄する

  • ≪ xmlrpc_server_create
  • xmlrpc_server_register_introspection_callback ≫
  • PHP Manual
  • XML-RPC 関数
  • サーバーリソースを破棄する

xmlrpc_server_destroy

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_server_destroy — サーバーリソースを破棄する

説明

xmlrpc_server_destroy(resource $server): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


ドキュメントを生成する PHP 関数を登録する

  • ≪ xmlrpc_server_destroy
  • xmlrpc_server_register_method ≫
  • PHP Manual
  • XML-RPC 関数
  • ドキュメントを生成する PHP 関数を登録する

xmlrpc_server_register_introspection_callback

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_server_register_introspection_callback — ドキュメントを生成する PHP 関数を登録する

説明

xmlrpc_server_register_introspection_callback(resource $server, string $function): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


メソッド名が一致するメソッドリソースに PHP 関数を登録する

  • ≪ xmlrpc_server_register_introspection_callback
  • xmlrpc_set_type ≫
  • PHP Manual
  • XML-RPC 関数
  • メソッド名が一致するメソッドリソースに PHP 関数を登録する

xmlrpc_server_register_method

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_server_register_method — メソッド名が一致するメソッドリソースに PHP 関数を登録する

説明

xmlrpc_server_register_method(resource $server, string $method_name, string $function): bool
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。


PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する

  • ≪ xmlrpc_server_register_method
  • Windows 用のモジュール ≫
  • PHP Manual
  • XML-RPC 関数
  • PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する

xmlrpc_set_type

(PHP 4 >= 4.1.0, PHP 5, PHP 7)

xmlrpc_set_type — PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する

説明

xmlrpc_set_type(string &$value, string $type): bool

PHP の文字列用の xmlrpc 型を、base64 あるいは datetime に設定します。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

value

型を設定する値。

type

'base64' あるいは 'datetime'。

戻り値

成功した場合に true を、失敗した場合に false を返します。 成功した場合、value はオブジェクト型に変換されます。

エラー / 例外

XMLRPC がサポートしていない型を指定した場合は E_WARNING が発生します。

例

例1 xmlrpc_set_type() の例

<?php

$params = date("Ymd\TH:i:s", time());
xmlrpc_set_type($params, 'datetime');
echo xmlrpc_encode($params);

?>

上の例の出力は、 たとえば以下のようになります。

<?xml version="1.0" encoding="utf-8"?>
<params>
<param>
 <value>
  <dateTime.iso8601>20090322T23:43:03</dateTime.iso8601>
 </value>
</param>
</params>


Windows 用のモジュール

  • COM — COM および .Net (Windows)
    • はじめに
    • インストール/設定
    • 定義済み定数
    • エラーおよびエラー処理
    • 例
    • com — com クラス
    • dotnet — dotnet クラス
    • variant — variant クラス
    • COMPersistHelper — COMPersistHelper クラス
    • com_exception — com_exception クラス
    • com_safearray_proxy — com_safearray_proxy クラス
    • COM関数
  • win32service
    • はじめに
    • インストール/設定
    • 定義済み定数
    • Win32ServiceException — The Win32ServiceException class
    • 例
    • win32service 関数


COM および .Net (Windows)

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
  • 定義済み定数
  • エラーおよびエラー処理
  • 例
    • For Each
    • 配列と配列形式の COM プロパティ
  • com — com クラス
    • com::__construct — com クラスのコンストラクタ
  • dotnet — dotnet クラス
    • dotnet::__construct — dotnet クラスのコンストラクタ
  • variant — variant クラス
    • variant::__construct — variant クラスのコンストラクタ
  • COMPersistHelper — COMPersistHelper クラス
    • COMPersistHelper::__construct — COMPersistHelper オブジェクトを構築する
    • COMPersistHelper::GetCurFileName — 現在のファイル名を取得する
    • COMPersistHelper::GetMaxStreamSize — ストリームのサイズの最大値を取得する
    • COMPersistHelper::InitNew — オブジェクトをデフォルトの状態に初期化する
    • COMPersistHelper::LoadFromFile — オブジェクトをファイルから読み込む
    • COMPersistHelper::LoadFromStream — ストリームからオブジェクトを読み込む
    • COMPersistHelper::SaveToFile — オブジェクトをファイルに保存する
    • COMPersistHelper::SaveToStream — オブジェクトをストリームに保存する
  • com_exception — com_exception クラス
  • com_safearray_proxy — com_safearray_proxy クラス
  • COM関数
    • com_create_guid — グローバルユニーク ID (GUID) を生成する
    • com_event_sink — COM オブジェクトのイベントを PHP オブジェクトに接続する
    • com_get_active_object — すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す
    • com_load_typelib — タイプライブラリを読み込む
    • com_message_pump — COM メッセージを処理し、timeoutms ミリ秒の間待つ
    • com_print_typeinfo — ディスパッチインターフェイスのために、PHP のクラス定義を出力する
    • variant_abs — variant の絶対値を返す
    • variant_add — 2 つの variant 値を「加算」し、結果を返す
    • variant_and — 2 つの variant の論理積を計算し、結果を返す
    • variant_cast — variant を、別の型の新しい variant に変換する
    • variant_cat — 2 つの variant 値を連結し、その結果を返す
    • variant_cmp — 2 つの variant を比較する
    • variant_date_from_timestamp — Unix タイムスタンプを、日付形式の variant で返す
    • variant_date_to_timestamp — 日付/時刻の variant 値を Unix タイムスタンプに変換する
    • variant_div — 2 つの variant の除算結果を返す
    • variant_eqv — 2 つの variant のビット値が等しいかどうかを調べる
    • variant_fix — variant の整数部を返す
    • variant_get_type — variant オブジェクトの型を返す
    • variant_idiv — variants を整数に変換し、除算の結果を返す
    • variant_imp — 2 つの variant のビット implication を行う
    • variant_int — variant の整数部を返す
    • variant_mod — 2 つの variant の除算を行い、剰余を返す
    • variant_mul — 2 つの variant の乗算を行い、その結果を返す
    • variant_neg — variant の論理否定演算を行う
    • variant_not — variant のビット否定演算を行う
    • variant_or — 2 つの variant の論理和を計算する
    • variant_pow — 2 つの variant の累乗計算を行い、その結果を返す
    • variant_round — 指定した桁で variant を丸める
    • variant_set — variant オブジェクトに新しい値を代入する
    • variant_set_type — variant を「その場で」別の型に変換する
    • variant_sub — 左の variant から右の variant を引き、その結果を返す
    • variant_xor — 2 つの variant の排他的論理和を計算する


はじめに

COM は Component Object Model の略語であり、 DCE RPC (オープンスタンダード) の最上位のオブジェクト指向レイヤーです。 COM はコール手順を共通化し、あらゆる言語でコードを記述し、 (COM に対応した)他の言語で書かれたコードをコール、相互運用することを可能にします。 あらゆる言語で書くことを可能にするだけではなく、 同じ実行形式の一部となることすら不要です。 コードは、同じマシンで実行される他のプロセスのコードである DLL からロードしたり、 または、リモートマシン上の他のプロセスにあるコードを DCOM (分散 COM) で 利用することができます。 この場合、コードの中では、コンポーネントの存在する場所を意識する必要はありません。

OLE オートメーションと呼ばれる COM のサブセットがあります。 これは、COM オブジェクトに疎な結合を行うことができる COM インターフェイスを 提供します。これにより、コンパイル時にオブジェクトの動作を知ることなく、 実行時にコールを行うことができるようになります。 PHP COM 拡張モジュールは、OLE オートメーションを使用して スクリプトから互換性のあるオブジェクトを作成/コールすることができます。 技術的に述べると、 全ての COM オブジェクトが OLE 互換であるというわけではないため、 実際には、この拡張モジュールは "PHP の OLE オートメーション 拡張モジュール" と呼ばれるべきものです。

ところで、なぜ COM を使用する必要があるのでしょう? COM は、 Windows 環境でアプリケーションとコンポーネントを結び付ける代表的な手法の一つで、 COM を使用して Microsoft Word を起動し、 ドキュメントテンプレートを埋めて、Word 文書として結果を保存し、Web サイトの 訪問者に送信することができます。 また COM を使用して、ネットワークの管理タスクを処理したり IIS を設定したりすることができます。これらは最も一般的な使用法にすぎません。 COM でできることはまだまだたくさんあります。

さらに Microsoft により提供された COM との相互運用レイヤーを用いて .Net アセンブリのインスタンス化と生成をサポートしました。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • COM
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定


要件

COM 関数は、Windows 版の PHP でのみ利用可能です。

.Net サポートには .Net ランタイムが必要です。


インストール手順

これらの関数を使うには、php_com_dotnet.dll を php.ini で有効にしておく必要があります。

使いたい COM オブジェクト (MS Word など) は別途インストールしておかないといけません。 そういった COM オブジェクトは PHP にバンドルされていませんし、 そもそもバンドルできません。


実行時設定

php.ini の設定により動作が変化します。

COM 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
com.allow_dcom | "0" | INI_SYSTEM |
com.autoregister_typelib | "0" | INI_ALL |
com.autoregister_verbose | "0" | INI_ALL |
com.autoregister_casesensitive | "1" | INI_ALL |
com.code_page | "" | INI_ALL |
com.dotnet_version | "" | INI_SYSTEM | PHP 8.0.0 以降で利用可能
com.typelib_file | "" | INI_SYSTEM |
INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

com.allow_dcom

これを on にすると、PHP が D-COM (分散 COM) クライアントとして動作することを許可し、 PHP スクリプトがリモートサーバー上に COM オブジェクトを生成することを 許可します。

com.autoregister_typelib

これを on にすると、 生成した COMオブジェクトのタイプライブラリから取得した 定数を PHP に登録しようと試みます。ただし、それはオブジェクトが 当該情報を取得するためのインターフェイスを提供している場合のみです。 登録する定数の大文字小文字を区別するかどうかについては、 com.autoregister_casesensitive php.ini 設定ディレクティブで制御します。

com.autoregister_verbose

これを on にすると、オブジェクト生成時のタイプライブラリの読み込み中に 発生したすべての問題が PHP のエラー機構を用いて報告されます。 デフォルトは off で、この場合はタイプライブラリの検索や読み込みの際の エラーは一切報告されません。

com.autoregister_casesensitive

これを on にすると (デフォルト)、 COMオブジェクトをインスタンス化中に自動読み込みされた タイプライブラリ中に見つかった定数が、大文字小文字を区別して 登録されます。詳細は com_load_typelib() を参照ください。

com.code_page

これは、COM オブジェクトとの文字列の受け渡しに使用するデフォルトの 文字セットコードページを制御します。空の文字列が設定された場合、 PHP は CP_ACP が指定されたと仮定します。 これは、デフォルトのシステム ANSI コードページです。

スクリプト中のテキストがデフォルトとは異なるエンコーディング/ 文字セットを使用している場合、このディレクティブを設定することで com クラスのコンストラクタのパラメータとして コードページを指定する必要がなくなります。 (他の PHP 設定ディレクティブとともに) このディレクティブを使用すると、 PHP スクリプトの移植可能性が悪くなることに注意しましょう。 できる限り、COM のコンストラクタにパラメータを指定する方式をとるべきです。

com.dotnet_version

dotnet オブジェクトが使う、.NET framework のバージョン。 この値は、framework のバージョン番号のうち、ドットで区切られた最初の3つの部分で、 v が先頭に付きます。たとえば v4.0.30319 のようなものです。

com.typelib_file

このパラメータでは、起動時に読み込まれるタイプライブラリの一覧を 含むファイルへのパスを保持します。このファイル内の各行が タイプライブラリ名として扱われ、com_load_typelib() をコールした際にそれが読み込まれます。登録された定数は永続的に 保持されるので、ライブラリの読み込みは一度だけでよくなります。 タイプライブラリの名前が #cis あるいは #case_insensitive で終わる場合は、そのライブラリから 読み込まれた定数は大文字小文字を区別せずに登録されます。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

COM 定数
定数 | 説明 | 備考
CLSCTX_INPROC_SERVER (int) | このクラスのコードを作成および管理するコードは DLL で、 クラスのコンテキストを指定する呼び出し元の関数と同じプロセスで動きます。 |
CLSCTX_INPROC_HANDLER (int) | このクラスのオブジェクトを管理するコードはプロセス内ハンドラです。 これは DLL で、クライアントプロセスで動きます。 クラスのインスタンスがリモートでアクセスされるときに、 このクラスのクライアント側の構造を実装します。 |
CLSCTX_LOCAL_SERVER (int) | このクラスのオブジェクトを作成および管理する EXE コードで、 同じマシンで動きますが別のプロセス空間にロードされます。 |
CLSCTX_REMOTE_SERVER (int) | リモートコンテキスト。 このクラスのオブジェクトを作成および管理するコードは、別のコンピュータで動きます。 |
CLSCTX_SERVER (int) | プロセス内、ローカル、リモートのすべてのサーバーコードを表します。 CLSCTX_INPROC_SERVER、 CLSCTX_LOCAL_SERVER および CLSCTX_REMOTE_SERVER を OR で連結したものです。 |
CLSCTX_ALL (int) | すべてのクラスコンテキストを表します。 CLSCTX_INPROC_HANDLER と CLSCTX_SERVER を OR で連結したものです。 |
VT_NULL (int) | NULL ポインタへの参照。 |
VT_EMPTY (int) | 型インジケータが VT_EMPTY であるプロパティには、 何もデータが関連づけられていません。つまり、この値のサイズはゼロです。 |
VT_INT (int) | 4 バイト符号つき整数値 (VT_I4 と同じ)。 |
VT_I1 (int) | 1 バイト符号つき整数値。 |
VT_I2 (int) | 2 バイト符号つき整数値。 |
VT_I4 (int) | 4 バイト符号つき整数値。 |
VT_I8 (int) | 8 バイト符号つき整数値。 | x64 のみ
VT_UINT (int) | 4 バイト符号なし整数値 (VT_I4 と同じ)。 |
VT_UI1 (int) | 1 バイト符号なし整数値。 |
VT_UI2 (int) | 2 バイト符号なし整数値。 |
VT_UI4 (int) | 4 バイト符号なし整数値。 |
VT_UI8 (int) | 8 バイト符号なし整数値。 | x64 のみ
VT_R4 (int) | 32 ビット IEEE 浮動小数点値。 |
VT_R8 (int) | 64 ビット IEEE 浮動小数点値。 |
VT_BOOL (int) | Boolean 値。 |
VT_ERROR (int) | エラーコード。エラーに関連づけられたステータスコードです。 |
VT_CY (int) | 8 バイト整数値をふたつつなげたもの (スケールは 10,000)。 |
VT_DATE (int) | 64 ビット浮動小数点値で、December 31, 1899 からの経過日数 (秒ではありません) を表します。たとえば January 1, 1900 は 2.0、 January 2, 1900 は 3.0 のようになります。 格納されるときは VT_R8 と同じ形式になります。 |
VT_BSTR (int) | Null 終端の Unicode 文字列へのポインタ。 |
VT_DECIMAL (int) | 十進型。 |
VT_UNKNOWN (int) | IUnknown インターフェイスを実装したオブジェクトへのポインタ。 |
VT_DISPATCH (int) | 指定したオブジェクトへのポインタのポインタ。 |
VT_VARIANT (int) | 対応する値を表す型インジケータ。 VT_VARIANT を使うのは、 VT_BYREF と組み合わせる場合のみです。 |
VT_ARRAY (int) | 型インジケータを VT_ARRAY と OR 演算子で組み合わせると、 その値は SAFEARRAY へのポインタとなります。 VT_ARRAY は、次のデータ型と OR で連結可能です。 VT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_INT, VT_UINT, VT_R4, VT_R8, VT_BOOL, VT_DECIMAL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DISPATCH, VT_UNKNOWN および VT_VARIANT. |
VT_BYREF (int) | 型インジケータを VT_BYREF と OR 演算子で組み合わせると、 その値は参照となります。参照型はデータへの参照として扱われます。 C++ における参照型と同じです。 |
CP_ACP (int) | ANSI コードページのデフォルト。 |
CP_MACCP (int) | Macintosh コードページ。 |
CP_OEMCP (int) | OEM コードページのデフォルト。 |
CP_UTF7 (int) | Unicode (UTF-7)。 |
CP_UTF8 (int) | Unicode (UTF-8)。 |
CP_SYMBOL (int) | SYMBOL 変換。 |
CP_THREAD_ACP (int) | 現在のスレッドの ANSI コードページ。 |
VARCMP_LT (int) | 左の bstr のほうが右の bstr より小さい。 |
VARCMP_EQ (int) | ふたつのパラメータが等しい。 |
VARCMP_GT (int) | 左の bstr のほうが右の bstr より大きい。 |
VARCMP_NULL (int) | 両方の式が NULL である。 |
NORM_IGNORECASE (int) | 大文字小文字を区別しない。 |
NORM_IGNORENONSPACE (int) | 空白文字以外を無視する。 |
NORM_IGNORESYMBOLS (int) | 記号を無視する。 |
NORM_IGNOREWIDTH (int) | 文字幅を無視する。 |
NORM_IGNOREKANATYPE (int) | カナの型を無視する。 |
NORM_IGNOREKASHIDA (int) | アラビア語の kashida 文字を無視する。 | 使えるかどうかは、元となるライブラリに依存します。
DISP_E_DIVBYZERO (int) | ゼロ除算エラー。 |
DISP_E_OVERFLOW (int) | 期待する形式で値を表すことができないことを意味するエラー。 |
DISP_E_BADINDEX (int) | -2147352565 | 配列のインデックスが存在しないことを意味するエラー。 | PHP 7.0.0 以降、x64 における値は 2147614731 です。
DISP_E_PARAMNOTFOUND (int) | パラメータのIDのうちのひとつが、 メソッドのパラメータに関連付けられていない戻り値であることを示します。 |
MK_E_UNAVAILABLE (int) | iMoniker COM ステータスコード。 その関数が使えないことを表します。 |
LOCALE_NEUTRAL (int) | ニュートラルロケール。 一般的に、この定数は NLS のAPIを呼び出すのに使いません。 代わりに、LOCALE_SYSTEM_DEFAULT を使って下さい。 |
LOCALE_SYSTEM_DEFAULT (int) | オペレーティングシステムのデフォルトのロケール |


エラーおよびエラー処理

COM から致命的なエラーが報告された場合、この拡張モジュールは com_exception クラスのインスタンスをスローします。 すべての COM 例外は code という定義済みの プロパティを保持しており、これは COM 操作が返す HRESULT 値に対応します。 プログラム上での例外の処理方法を決定するために、この値を使用する ことができます。


  • ≪ エラーおよびエラー処理
  • For Each ≫
  • PHP Manual
  • COM
  • 例

例

目次

  • For Each
  • 配列と配列形式の COM プロパティ


For Each

標準的な COM/OLE IEnumVariant の内容について、 PHP の foreach 命令を使用した反復処理を行うことができます。分かりやすく言うと、 これは、VB/ASP のコードで For Each を使用できる場所には foreach を使用できるということを意味します。

例1 ASP における For Each

<%
Set domainObject = GetObject("WinNT://Domain")
For Each obj in domainObject
  Response.Write obj.Name & "<br />"
Next
%>

例2 PHP 5 における foreach

<?php
$domainObject = new COM("WinNT://Domain");
foreach ($domainObject as $obj) {
echo $obj->Name . "<br />";
}
?>


配列と配列形式の COM プロパティ

多くの COM オブジェクトは、プロパティを配列で公開したり 配列形式を使用してアクセスできるようにしています。

以下のことができます:

  • 多次元配列・複数パラメータを要求する COM プロパティへの PHP の配列構文を使用したアクセス。 書き込みやプロパティの設定にもこの技法が使用可能です。

  • foreach 制御構造を使用した SafeArrays ("真の" 配列) の値の取得。SafeArrays が自分自身の サイズについての情報を含んでいることからこれが可能となります。 配列形式のプロパティが IEnumVariant を実装している場合は、その プロパティに対しても foreach が使用可能です。この項目についての 詳細な情報は、For Each をごらんください。


com クラス

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

はじめに

com クラスにより、OLE 互換の COM オブジェクトのインスタンスを作成し、 そのメソッドをコールしたりそのプロパティにアクセスしたりすることが 可能となります。

クラス概要

class com extends variant {
/* メソッド */
public __construct(
string $module_name,
array|string|null $server_name = null,
int $codepage = CP_ACP,
string $typelib = ""
)
}

Overloaded Methods

返されるオブジェクトは、オーバーロードされたものです。つまり、 PHP 側では通常のクラスのメソッドは見えないということです。 その代わりに、プロパティやメソッドへのアクセスは COM を通じて行います。

参照渡しのパラメータを受け付けるメソッドを PHP が 自動検出するようになりました。それらのメソッドについては、PHP が自動的に 変数を参照渡し形式に変換します。つまり、メソッドのコールをより自然に 行えるということです。コードの中で特別な処理をする必要はありません。

com の例

例1 com の例 (1)

<?php
// word を起動します
$word = new com("word.application") or die("Unable to instantiate Word");
echo "Loaded Word, version {$word->Version}\n";

// 前面に移動させます
$word->Visible = 1;

// 空のドキュメントを開きます
$word->Documents->Add();

// 何か複雑なことを行います
$word->Selection->TypeText("This is a test...");
$word->Documents[1]->SaveAs("Useless test.doc");

// word を閉じます
$word->Quit();

// オブジェクトを開放します
$word = null;

?>

例2 com の例 (2)

<?php

$conn = new com("ADODB.Connection") or die("Cannot start ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

$rs = $conn->Execute("SELECT * FROM sometable"); // Recordset

$num_columns = $rs->Fields->Count();
echo $num_columns . "\n";

for ($i=0; $i < $num_columns; $i++) {
$fld[$i] = $rs->Fields($i);
}

$rowcount = 0;
while (!$rs->EOF) {
for ($i=0; $i < $num_columns; $i++) {
echo $fld[$i]->value . "\t";
}
echo "\n";
$rowcount++; // increments rowcount
$rs->MoveNext();
}

$rs->Close();
$conn->Close();

$rs = null;
$conn = null;

?>

目次

  • com::__construct — com クラスのコンストラクタ


com クラスのコンストラクタ

  • ≪ com
  • dotnet ≫
  • PHP Manual
  • com
  • com クラスのコンストラクタ

com::__construct

(PHP 4 > 4.1.0, PHP 5, PHP 7, PHP 8)

com::__construct — com クラスのコンストラクタ

説明

public com::__construct(
string $module_name,
array|string|null $server_name = null,
int $codepage = CP_ACP,
string $typelib = ""
)

新しい com オブジェクトを構築します。

パラメータ

module_name
ロードするコンポーネントの名前を表す ProgID, ClassID または Moniker。 ProgID は通常、アプリケーションまたは DLL の名前で、その後にピリオドが続き、 オブジェクト名が続きます。e.g: Word.Application ClassID は、与えられたクラスを一意に識別するUUIDです。 Moniker は、URL スキームの概念に似た特別な名前付けのやり方で、 リソースを識別し、どのようにロードするかを指定します。 たとえば、Microsoft Word をロードし、 Word ドキュメントを表現するオブジェクトを取得するために、 フルパスをモジュール名として指定できます。 また、LDAP への ADSI インターフェイスを使う moniker として LDAP: が使えます。
server_name
コンポーネントをロードし、実行する DCOM サーバー名。 null の場合、そのアプリケーションのデフォルトが使われ、実行されます。 デフォルトは通常はローカルマシン上で実行することですが、 管理者が異なるマシン上で起動するアプリケーションを設定するかもしれません。 server に null でない値を指定すると、PHP は com.allow_dcom php.ini 設定オプションが true でない限りオブジェクトのロードを拒否します。

server_name が配列の場合、 次の要素が含まれるべきです(大文字小文字を区別します！)。 但し、これらは全てオプション(ユーザー名とパスワードは一緒に指定する必要があります) であることに注意してください。つまり、サーバーの設定を省略すると、 (既に述べたとおり)デフォルトのサーバーが使われ、オブジェクトのインスタンス化は com.allow_dcom php.ini ディレクティブによって影響を受けません。

DCOM サーバー名
キー | タイプ | 説明
Server | string | サーバー名
Username | string | 接続するユーザ名
Password | string | Username のパスワード
Domain | string | server のドメイン
Flags | integer | 以下の定数をひとつ以上、論理ORで指定します: CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER, CLSCTX_SERVER および CLSCTX_ALL。 指定されなかった場合のデフォルト値は Server も省略した場合は、 CLSCTX_SERVER ですが、 server を指定した場合は CLSCTX_REMOTE_SERVER です。 これらの定数の意味の詳細情報は、 Microsoft の CoCreateInstance のドキュメントも参照ください。 通常、それらを使わないことはないはずです。

codepage
文字列をUnicode文字列その他に変換するために使うコードページを指定します。 PHP の文字列が この COM オブジェクトのメソッドとパラメータをやりとりする時に 常にこの変換は適用されます。このコードページは sticky です。 つまり、コードページはオブジェクトから返されるオブジェクトやバリアントに伝播するということです。 有効な値は CP_ACP (システムデフォルトの ANSI コードページを使う - このパラメータが省略された場合のデフォルト値), CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP (現在実行中のスレッドのコードページ/ロケールを使う), CP_UTF7 および CP_UTF8 です。 コードページの数値も使えます。 コードページとその数値に関する詳細な情報は、Microsoft のドキュメントを参照ください。


dotnet クラス

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

はじめに

dotnet クラスにより、 クラスやメソッドが » COM に見えている場合、 .Net アセンブリからクラスを生成して そのメソッドをコールしたりプロパティにアクセスしたりできるようになります。

staticクラス をインスタンス化したり、staticメソッド を呼び出すことはサポートされていません。 System.Collections.Generic.List のようなジェネリッククラスをインスタンス化することもサポートしていません。

.Net クラスによっては、IDispatch を実装していないものがあります。 それらはインスタンス化はできるものの、メソッドをコールしたり プロパティへアクセスすることをサポートしていません。

注意:

この機能を利用するには、Webサーバーに .Netランタイムをインストールする必要があります。

注意:

PHP 8.0.0 より前のバージョンでは、 dotnet クラスは.Net framework 4.0 以降をサポートしていませんでした。 アセンブリが regasm.exe によって登録されている場合は、 それらのクラスは com オブジェクトを通じてインスタンス化できます。 PHP 8.0.0 以降では、php.ini の com.dotnet_version を指定することで .Net framework 4.0 以降をサポートします。

クラス概要

class dotnet extends variant {
/* メソッド */
public __construct(string $assembly_name, string $datatype_name, int $codepage = CP_ACP)
}

オーバーロードされたメソッド

返されるオブジェクトはオーバーロードされています。つまり、通常の クラスのような固定されたメソッドは存在しないということです。 そのかわりに、プロパティやメソッドへのアクセスは COM を通じて DOTNET に渡されます。言い換えれば、.Net ランタイムが提供する COM相互運用レイヤによって .Net オブジェクトが COM 連携用にマップされているという ことです。

dotnet オブジェクトが作成されると、PHP はそれを他の COM オブジェクトと同等のものとして扱い、同様の規則が適用されます。

dotnet の例

例1 dotnet の例

<?php
$stack = new dotnet("mscorlib", "System.Collections.Stack");
$stack->Push(".Net");
$stack->Push("Hello ");
echo $stack->Pop() . $stack->Pop();
?>

目次

  • dotnet::__construct — dotnet クラスのコンストラクタ


dotnet クラスのコンストラクタ

  • ≪ dotnet
  • variant ≫
  • PHP Manual
  • dotnet
  • dotnet クラスのコンストラクタ

dotnet::__construct

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

dotnet::__construct — dotnet クラスのコンストラクタ

説明

public dotnet::__construct(string $assembly_name, string $datatype_name, int $codepage = CP_ACP)

新しい dotnet オブジェクトを構築します。

パラメータ

assembly_name
ロードすべきアセンブリ名を指定します。
datatype_name
アセンブリ中のどのクラスをインスタンス化するかを指定します。
codepage
Unicode文字列の変換に使うコードページ。 詳細な情報は com クラスの同じ名前のパラメータを参照ください。


variant クラス

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

はじめに

VARIANT は、PHP の zval と同等の COM の値です。構造体形式になっており、 異なる型の値を含めることが可能です。COM 拡張モジュールが提供する variant クラスによって、PHP と COM の間のデータの受け渡しを制御できるように なります。

クラス概要

class variant {
/* メソッド */
public __construct(mixed $value = null, int $type = VT_EMPTY, int $codepage = CP_ACP)
}

variant の例

例1 variant の例

<?php
$v = new variant(42);
print "The type is " . variant_get_type($v) . "<br/>";
print "The value is " . $v . "<br/>";
?>

注意:

値を返したり variant プロパティを取得したりする際に variant が PHP の値に変換されるのは、情報を失うことなく型変換ができる型が 存在する場合に限られます。それ以外の場合は、結果は variant クラスの インスタンスとして返されます。明示的にキャスト演算子を指定することで variant を PHP のネイティブ型として扱うことが可能です。また、 print を使用すると、暗黙のうちに値が文字列に 変換されます。variant に対する計算のためのさまざまな関数が用意されており、 型変換でデータを失うリスクを犯さなくてもそのままの形式で計算を 行うことが可能です。

variant_get_type() も参照ください。

目次

  • variant::__construct — variant クラスのコンストラクタ


variant クラスのコンストラクタ

  • ≪ variant
  • COMPersistHelper ≫
  • PHP Manual
  • variant
  • variant クラスのコンストラクタ

variant::__construct

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

variant::__construct — variant クラスのコンストラクタ

説明

public variant::__construct(mixed $value = null, int $type = VT_EMPTY, int $codepage = CP_ACP)

新しい variant オブジェクトを構築します。

パラメータ

value
初期値。省略するか null を設定すると、VT_EMPTY オブジェクトが作成されます。
type
variant オブジェクトの型を指定します。 有効な値は 定義済み定数 の VT_XXX のうちの一つです。 PHP は参照渡しを自動で認識できます。 つまり、variant オブジェクトとして渡す必要すらないということです。 VARIANT 型に関する追加情報は、MSDN ライブラリを調べてください。
codepage
文字列をUnicodeに変換するのに使うコードページ。 詳細な情報は com クラスの同じ名前のパラメータを参照ください。


COMPersistHelper クラス

(PHP 5, PHP 7, PHP 8)

はじめに

COMPersistHelper クラスは、 php.ini の open_basedir ディレクティブと ストリーム リソース を考慮して COM と PHP の相互運用性を高めます。

クラス概要

final class COMPersistHelper {
/* メソッド */
public __construct(?variant $variant = null)
public GetCurFileName(): string|false
public GetMaxStreamSize(): int
public InitNew(): bool
public LoadFromFile(string $filename, int $flags = 0): bool
public LoadFromStream(resource $stream): bool
public SaveToFile(?string $filename, bool $remember = true): bool
public SaveToStream(resource $stream): bool
}

目次

  • COMPersistHelper::__construct — COMPersistHelper オブジェクトを構築する
  • COMPersistHelper::GetCurFileName — 現在のファイル名を取得する
  • COMPersistHelper::GetMaxStreamSize — ストリームのサイズの最大値を取得する
  • COMPersistHelper::InitNew — オブジェクトをデフォルトの状態に初期化する
  • COMPersistHelper::LoadFromFile — オブジェクトをファイルから読み込む
  • COMPersistHelper::LoadFromStream — ストリームからオブジェクトを読み込む
  • COMPersistHelper::SaveToFile — オブジェクトをファイルに保存する
  • COMPersistHelper::SaveToStream — オブジェクトをストリームに保存する


COMPersistHelper オブジェクトを構築する

  • ≪ COMPersistHelper
  • COMPersistHelper::GetCurFileName ≫
  • PHP Manual
  • COMPersistHelper
  • COMPersistHelper オブジェクトを構築する

COMPersistHelper::__construct

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::__construct — COMPersistHelper オブジェクトを構築する

説明

public COMPersistHelper::__construct(?variant $variant = null)

永続化を助けるオブジェクトを構築します。 これは通常、variant に結びつけて使います。

パラメータ

variant
IDispatch を実装した COM オブジェクト。 COMPersistHelper のあらゆるメソッドを呼べるようにするためには、 IPersistFile, IPersistStream かつ/または IPersistStreamInit をオブジェクトが実装していなければなりません。 variant に nullを渡す意味があるのは、 COMPersistHelper::LoadFromStream() を呼び出してオブジェクトを読み込んだ場合に限ります。


現在のファイル名を取得する

  • ≪ COMPersistHelper::__construct
  • COMPersistHelper::GetMaxStreamSize ≫
  • PHP Manual
  • COMPersistHelper
  • 現在のファイル名を取得する

COMPersistHelper::GetCurFileName

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::GetCurFileName — 現在のファイル名を取得する

説明

public COMPersistHelper::GetCurFileName(): string|false

オブジェクトに関連付けられた現在のファイル名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトに関連付けられた現在のファイル名を返します。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistFile を実装していないか、 IPersistFile::GetCurFile() の呼び出しに失敗した場合、 com_exception がスローされます。


ストリームのサイズの最大値を取得する

  • ≪ COMPersistHelper::GetCurFileName
  • COMPersistHelper::InitNew ≫
  • PHP Manual
  • COMPersistHelper
  • ストリームのサイズの最大値を取得する

COMPersistHelper::GetMaxStreamSize

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::GetMaxStreamSize — ストリームのサイズの最大値を取得する

説明

public COMPersistHelper::GetMaxStreamSize(): int

オブジェクトを保存するのに必要なストリームのサイズを取得します(バイト単位)。

パラメータ

この関数にはパラメータはありません。

戻り値

オブジェクトを保存するのに必要なストリームのサイズを返します(バイト単位)。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistStreamInit と IPersistStream をいずれも実装していないか、 IPersistStream::GetSizeMax() の呼び出しに失敗した場合、 com_exception がスローされます。


オブジェクトをデフォルトの状態に初期化する

  • ≪ COMPersistHelper::GetMaxStreamSize
  • COMPersistHelper::LoadFromFile ≫
  • PHP Manual
  • COMPersistHelper
  • オブジェクトをデフォルトの状態に初期化する

COMPersistHelper::InitNew

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::InitNew — オブジェクトをデフォルトの状態に初期化する

説明

public COMPersistHelper::InitNew(): bool

オブジェクトをデフォルトの状態に初期化します

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistStreamInit を実装していないか、 IPersistStreamInit::Init() の呼び出しに失敗した場合、 com_exception がスローされます。


オブジェクトをファイルから読み込む

  • ≪ COMPersistHelper::InitNew
  • COMPersistHelper::LoadFromStream ≫
  • PHP Manual
  • COMPersistHelper
  • オブジェクトをファイルから読み込む

COMPersistHelper::LoadFromFile

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::LoadFromFile — オブジェクトをファイルから読み込む

説明

public COMPersistHelper::LoadFromFile(string $filename, int $flags = 0): bool

指定されたファイルを開き、そのファイルの内容でオブジェクトを初期化します。

パラメータ

filename
読み込むオブジェクトが保存されたファイル名
flags
ファイルをオープンする際のアクセスモード。 有効な値は » STGM enumeration を参照ください。 メソッドはこの値を参考程度に扱い、必要に応じてより制限的なパーミッションを追加します。 flags に 0 を指定すると、 ユーザーがファイルを開くときのデフォルトのパーミッションを使ってファイルを開きます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistFile を実装していないか、 IPersistFile::Load() の呼び出しに失敗した場合、 com_exception がスローされます。


ストリームからオブジェクトを読み込む

  • ≪ COMPersistHelper::LoadFromFile
  • COMPersistHelper::SaveToFile ≫
  • PHP Manual
  • COMPersistHelper
  • ストリームからオブジェクトを読み込む

COMPersistHelper::LoadFromStream

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::LoadFromStream — ストリームからオブジェクトを読み込む

説明

public COMPersistHelper::LoadFromStream(resource $stream): bool

以前オブジェクトを保存したストリームの内容でオブジェクトを初期化します。

パラメータ

stream
オブジェクトを読み込むストリームリソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistStream を実装していないか、 IPersistStream::Load() の呼び出しに失敗した場合、 com_exception がスローされます。


オブジェクトをファイルに保存する

  • ≪ COMPersistHelper::LoadFromStream
  • COMPersistHelper::SaveToStream ≫
  • PHP Manual
  • COMPersistHelper
  • オブジェクトをファイルに保存する

COMPersistHelper::SaveToFile

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::SaveToFile — オブジェクトをファイルに保存する

説明

public COMPersistHelper::SaveToFile(?string $filename, bool $remember = true): bool

オブジェクトのコピーを指定されたファイルに保存します

パラメータ

filename
オブジェクトを保存するファイル名
remember
filename パラメータを現在作業中のファイルに使うかを指定します。 true を指定すると、 filename は現在作業中のファイルに指定され、 保存された後にダーティーフラグがクリアされます。 false を指定すると、保存する操作は "ファイルに名前を付けて保存" する操作になります。 この場合、現在のファイルは変更されず、オブジェクトのダーティーフラグはクリアされません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistFile を実装していないか、 IPersistFile::Save() の呼び出しに失敗した場合、 com_exception がスローされます。

例

例1 COMPersistHelper::saveToFile() の基本的な使い方

<?php
$word = new COM('Word.Application');
$doc = $word->Documents->Add();
$ph = new COMPersistHelper($doc);
$ph->SaveToFile('C:\\Users\\cmb\\Documents\\my.docx');
$word->Quit();
?>


オブジェクトをストリームに保存する

  • ≪ COMPersistHelper::SaveToFile
  • com_exception ≫
  • PHP Manual
  • COMPersistHelper
  • オブジェクトをストリームに保存する

COMPersistHelper::SaveToStream

(PHP 5, PHP 7, PHP 8)

COMPersistHelper::SaveToStream — オブジェクトをストリームに保存する

説明

public COMPersistHelper::SaveToStream(resource $stream): bool

オブジェクトを指定されたストリームに保存します。

パラメータ

stream
オブジェクトを保存するストリーム リソース

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

関連付けられたオブジェクトが COM のインターフェイス IPersistStream と IPersistStreamInit をいずれも実装していないか、 IPersistStream::Save() の呼び出しに失敗した場合、 com_exception がスローされます。


com_exception クラス

(PHP 5, PHP 7, PHP 8)

はじめに

クラス概要

final class com_exception extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


com_safearray_proxy クラス

(PHP 5, PHP 7, PHP 8)

はじめに

com_safearray_proxy は、 SafeArray 型上での多次元配列へのアクセスを解決するのに使われる内部クラスです。

クラス概要

final class com_safearray_proxy {
}


COM関数

参考

COM についてのより詳細な情報は » COM 仕様 を読みましょう。 PHP と COM の FAQ からも情報が得られるでしょう。 MS Office アプリケーションをサーバーサイドで使用しようと考えておられるなら、 » Considerations for Server-Side Automation of Office の情報も読んでおくべきでしょう。

目次

  • com_create_guid — グローバルユニーク ID (GUID) を生成する
  • com_event_sink — COM オブジェクトのイベントを PHP オブジェクトに接続する
  • com_get_active_object — すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す
  • com_load_typelib — タイプライブラリを読み込む
  • com_message_pump — COM メッセージを処理し、timeoutms ミリ秒の間待つ
  • com_print_typeinfo — ディスパッチインターフェイスのために、PHP のクラス定義を出力する
  • variant_abs — variant の絶対値を返す
  • variant_add — 2 つの variant 値を「加算」し、結果を返す
  • variant_and — 2 つの variant の論理積を計算し、結果を返す
  • variant_cast — variant を、別の型の新しい variant に変換する
  • variant_cat — 2 つの variant 値を連結し、その結果を返す
  • variant_cmp — 2 つの variant を比較する
  • variant_date_from_timestamp — Unix タイムスタンプを、日付形式の variant で返す
  • variant_date_to_timestamp — 日付/時刻の variant 値を Unix タイムスタンプに変換する
  • variant_div — 2 つの variant の除算結果を返す
  • variant_eqv — 2 つの variant のビット値が等しいかどうかを調べる
  • variant_fix — variant の整数部を返す
  • variant_get_type — variant オブジェクトの型を返す
  • variant_idiv — variants を整数に変換し、除算の結果を返す
  • variant_imp — 2 つの variant のビット implication を行う
  • variant_int — variant の整数部を返す
  • variant_mod — 2 つの variant の除算を行い、剰余を返す
  • variant_mul — 2 つの variant の乗算を行い、その結果を返す
  • variant_neg — variant の論理否定演算を行う
  • variant_not — variant のビット否定演算を行う
  • variant_or — 2 つの variant の論理和を計算する
  • variant_pow — 2 つの variant の累乗計算を行い、その結果を返す
  • variant_round — 指定した桁で variant を丸める
  • variant_set — variant オブジェクトに新しい値を代入する
  • variant_set_type — variant を「その場で」別の型に変換する
  • variant_sub — 左の variant から右の variant を引き、その結果を返す
  • variant_xor — 2 つの variant の排他的論理和を計算する


グローバルユニーク ID (GUID) を生成する

  • ≪ COM関数
  • com_event_sink ≫
  • PHP Manual
  • COM関数
  • グローバルユニーク ID (GUID) を生成する

com_create_guid

(PHP 5, PHP 7, PHP 8)

com_create_guid — グローバルユニーク ID (GUID) を生成する

説明

com_create_guid(): string|false

グローバルユニーク ID (GUID) を生成します。

GUID は DCE UUID と同様の方法で生成されますが、Microsoft の 規約により、GUID が中括弧で囲まれるという点が異なります。

パラメータ

この関数にはパラメータはありません。

戻り値

GUID を文字列で返します。 失敗した場合に false を返します

参考

  • PECL uuid 拡張モジュールの uuid_create()


COM オブジェクトのイベントを PHP オブジェクトに接続する

  • ≪ com_create_guid
  • com_get_active_object ≫
  • PHP Manual
  • COM関数
  • COM オブジェクトのイベントを PHP オブジェクトに接続する

com_event_sink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

com_event_sink — COM オブジェクトのイベントを PHP オブジェクトに接続する

説明

com_event_sink(variant $variant, object $sink_object, array|string|null $sink_interface = null): bool

variant が生成したイベントを PHP オブジェクト sink_object に通知するよう、COM に指示します。

この機能を利用する際には注意しましょう。もし以下の例のようなことを 行いたいのであれば、Web サーバー上でそれを行うことには まったく意味がありません。

パラメータ

variant

sink_object

sink_object には、要求されるディスパッチ インターフェイスと同じ名前のメソッドを持つクラスのインスタンスを 指定する必要があります。この要求を満たすクラスを作成するために、 com_print_typeinfo() を使用することができます。

sink_interface

PHP は variant に関連するタイプライブラリで 指定されたデフォルトのディスパッチインターフェイスを使用しようと しますが、使用させたいインターフェイス名を sink_interface に指定することで、それを 上書きすることが可能です。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | sink_interface は、nullable になりました。

例

例1 COM イベントシンクの例

<?php
class IEEventSinker {
var $terminated = false;

function ProgressChange($progress, $progressmax) {
echo "ダウンロードの進行状況: $progress / $progressmax\n";
}

function DocumentComplete(&$dom, $url) {
echo "ドキュメント $url 完了\n";
}

function OnQuit() {
echo "終了!\n";
$this->terminated = true;
}
}
$ie = new COM("InternetExplorer.Application");
$sink = new IEEventSinker();
com_event_sink($ie, $sink, "DWebBrowserEvents2");
$ie->Visible = true;
$ie->Navigate("http://www.example.org");
while(!$sink->terminated) {
com_message_pump(4000);
}
$ie = null;
?>

注意

警告

PHP 8.0.0 より前のバージョンでは、 イベントハンドラから exit() を呼ぶことはサポートされていませんでした。 そうしてしまうと、PHP がハングする可能性もありました。 この事象は、イベントハンドラから例外をスローしてメインのコードでキャッチし、 exit() を呼び出すことで回避できます。

参考

  • com_print_typeinfo() - ディスパッチインターフェイスのために、PHP のクラス定義を出力する
  • com_message_pump() - COM メッセージを処理し、timeoutms ミリ秒の間待つ


すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す

  • ≪ com_event_sink
  • com_load_typelib ≫
  • PHP Manual
  • COM関数
  • すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す

com_get_active_object

(PHP 5, PHP 7, PHP 8)

com_get_active_object — すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す

説明

com_get_active_object(string $prog_id, ?int $codepage = null): variant

com_get_active_object() は、新しい com オブジェクトのインスタンスを作成することに 似ています。しかし、オブジェクトがすでに実行中の場合には そのオブジェクトが返されるという点が違います。 OLE アプリケーションは、既知のアプリケーションを一度だけ起動させる ことを許可するために、"Running Object Table" というものを使用します。 この関数は、実行中のインスタンスのハンドルを取得するために COM ライブラリ関数 GetActiveObject() を公開します。

パラメータ

prog_id

prog_id は、アクセスしたいオブジェクトの ProgID あるいは CLSID (たとえば Word.Application) である必要があります。

codepage

com クラスの場合と同様の働きをします。

戻り値

要求されたオブジェクトが実行中の場合は、他の COM オブジェクトと 同様にスクリプトへ返されます。

エラー / 例外

この関数が失敗する 理由はさまざまなものが考えられますが、最も一般的なのは オブジェクトがまだ起動していないことです。そのような場合、 例外のエラーコードは MK_E_UNAVAILABLE となります。例外オブジェクトの getCode メソッドを使用することで、例外コードの内容を調べることが可能です。

変更履歴

バージョン | 説明
8.0.0 | codepage は、nullable になりました。

注意

警告

Web 環境で com_get_active_object() を使用する ことは、あまり良い考えではありません。ほとんどの COM/OLE アプリケーションは複数のクライアントから同時に利用されることを 考慮していないのです。(あの) Microsoft Office でさえもです! この件に関する一般的な問題についての詳細な情報は、» Considerations for Server-Side Automation of Office を参照ください。


タイプライブラリを読み込む

  • ≪ com_get_active_object
  • com_message_pump ≫
  • PHP Manual
  • COM関数
  • タイプライブラリを読み込む

com_load_typelib

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

com_load_typelib — タイプライブラリを読み込む

説明

com_load_typelib(string $typelib, bool $case_insensitive = true): bool

タイプライブラリを読み込んで定数をエンジン内に登録し、それらが define() を使用して定義されているかのように 扱えるようにします。

あまり融通の利く方法ではありませんが、 com.typelib-file php.ini 設定を利用して定数の 事前読み込みと登録をすませるほうがずっと効率的であることに 注意しましょう。

com.autoregister-typelib を有効にすると、 PHP がインスタンス化した COM オブジェクトに関連付けられている定数を 自動的に登録しようと試みます。これは COM オブジェクト自身の提供する インターフェイスに依存し、常に可能であるとは限りません。

パラメータ

typelib

typelib は、以下のいずれかの形式となります。

  • .tlb ファイル、あるいはタイプライブラリを含む 実行モジュールのファイル名。

  • タイプライブラリの GUID の後にバージョン番号を続ける。たとえば {00000200-0000-0010-8000-00AA006D2EA4},2,0 のような形式。

  • タイプライブラリ名。たとえば Microsoft OLE DB ActiveX Data Objects 1.0 Library のような形式。

PHP は、この順序でタイプライブラリ名の解決を試みます。リストの下の ほうにいくほど検索処理のコストが高くなります。タイプライブラリ名に よる検索は、一致するものが見つかるまでレジストリを物理的に列挙していく という方法をとっています。

case_insensitive

case_insensitive は、 define() 関数の $case_insensitive とは逆の動きをします。

戻り値

成功した場合に true を、失敗した場合に false を返します。


COM メッセージを処理し、timeoutms ミリ秒の間待つ

  • ≪ com_load_typelib
  • com_print_typeinfo ≫
  • PHP Manual
  • COM関数
  • COM メッセージを処理し、timeoutms ミリ秒の間待つ

com_message_pump

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

com_message_pump — COM メッセージを処理し、timeoutms ミリ秒の間待つ

説明

com_message_pump(int $timeout_milliseconds = 0): bool

この関数は、timeout_milliseconds ミリ秒が経過するか キューにメッセージが到着するまで待機します。

この関数の目的は、別々の場所にある COM のコールを振り分け、同期の 問題をうまく処理することです。これにより、発生するイベントを 効率的にスクリプトで待ち受けられるようになり、バックグラウンドで 動作している他のコードやイベントも処理できるようになります。 COM オブジェクトのイベントを使用している間は、 com_event_sink() 関数の例で示したように この関数をループ内で使用すべきです。

パラメータ

timeout_milliseconds

タイムアウト。ミリ秒単位で指定します。

timeout_milliseconds の値を指定しなかった場合は 0 であるとみなされます。0 という値は、一切待機しないことを 意味します。処理待ち状態のメッセージがあればそれを処理し、 なければこの関数はすぐに false を返します。

戻り値

タイムアウトの前に メッセージが到着した場合は、そのメッセージが処理されて 関数は true を返します。メッセージを処理することなく タイムアウトが発生した場合は、この関数は false を返します。


ディスパッチインターフェイスのために、PHP のクラス定義を出力する

  • ≪ com_message_pump
  • variant_abs ≫
  • PHP Manual
  • COM関数
  • ディスパッチインターフェイスのために、PHP のクラス定義を出力する

com_print_typeinfo

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

com_print_typeinfo — ディスパッチインターフェイスのために、PHP のクラス定義を出力する

説明

com_print_typeinfo(variant|string $variant, ?string $dispatch_interface = null, bool $display_sink = false): bool

この関数の目的は、イベントシンクに使用するスケルトンクラスの作成を支援することです。 もし 対象の COM オブジェクトが イントロスペクションのインターフェイスを十分サポートしており、 表示したいインターフェイスの名前をあなたが知っている場合、 その COM オブジェクトのダンプを生成するのにも使えます。

パラメータ

variant

variant は、COM オブジェクトのインスタンスか あるいはタイプライブラリの名前 (com_load_typelib() の規則にしたがって名前解決されます) のいずれかです。

dispatch_interface

結果を表示したいインターフェイスで、 このインターフェイスは IDispatch を継承したものです。

display_sink

true の場合、対応するシンクインターフェイスが代わりに表示されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • com_event_sink() - COM オブジェクトのイベントを PHP オブジェクトに接続する
  • com_load_typelib() - タイプライブラリを読み込む


variant の絶対値を返す

  • ≪ com_print_typeinfo
  • variant_add ≫
  • PHP Manual
  • COM関数
  • variant の絶対値を返す

variant_abs

(PHP 5, PHP 7, PHP 8)

variant_abs — variant の絶対値を返す

説明

variant_abs(mixed $value): variant

variant の絶対値を返します。

パラメータ

value

variant。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

value の絶対値を返します。

エラー / 例外

失敗時に com_exception をスローします。

参考

  • abs() - 絶対値


2 つの variant 値を「加算」し、結果を返す

  • ≪ variant_abs
  • variant_and ≫
  • PHP Manual
  • COM関数
  • 2 つの variant 値を「加算」し、結果を返す

variant_add

(PHP 5, PHP 7, PHP 8)

variant_add — 2 つの variant 値を「加算」し、結果を返す

説明

variant_add(mixed $left, mixed $right): variant

(MSDN ライブラリによる) 以下の規則に従い、 left を right に加算します。この規則は Visual Basic の規則と一致します。

Variant の加算規則
もし～なら | このようにします
両者ともに文字列型 | 連結
一方が文字列型で、もう一方が文字 | 追加
一方が数値で、もう一方が文字列 | 追加
両者ともに数値 | 加算
どちらか一方が NULL | NULL が返される
両者ともに空の値 | Integer 型が返される

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

結果を返します。

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_sub() - 左の variant から右の variant を引き、その結果を返す


2 つの variant の論理積を計算し、結果を返す

  • ≪ variant_add
  • variant_cast ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の論理積を計算し、結果を返す

variant_and

(PHP 5, PHP 7, PHP 8)

variant_and — 2 つの variant の論理積を計算し、結果を返す

説明

variant_and(mixed $left, mixed $right): variant

以下の表に基づいた論理 AND 処理を行います。通常の AND 操作とは 少し違いがあることに注意しましょう。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の AND 規則
left | right | 結果
true | true | true
true | false | false
true | null | null
false | true | false
false | false | false
false | null | false
null | true | null
null | false | false
null | null | null

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_or() - 2 つの variant の論理和を計算する


variant を、別の型の新しい variant に変換する

  • ≪ variant_and
  • variant_cat ≫
  • PHP Manual
  • COM関数
  • variant を、別の型の新しい variant に変換する

variant_cast

(PHP 5, PHP 7, PHP 8)

variant_cast — variant を、別の型の新しい variant に変換する

説明

variant_cast(variant $variant, int $type): variant

この関数は、variant のコピーを作成して、 それを指定した type に強制的に変換します。

この関数は、COM ライブラリの VariantChangeType() をラップしたものです。 詳細な情報は MSDN ライブラリを参照ください。

パラメータ

variant

variant。

type

type は、定数 VT_XXX の中のひとつでなければなりません。

戻り値

与えられた type の variant を返します。

参考

  • variant_set_type() - variant を「その場で」別の型に変換する


2 つの variant 値を連結し、その結果を返す

  • ≪ variant_cast
  • variant_cmp ≫
  • PHP Manual
  • COM関数
  • 2 つの variant 値を連結し、その結果を返す

variant_cat

(PHP 5, PHP 7, PHP 8)

variant_cat — 2 つの variant 値を連結し、その結果を返す

説明

variant_cat(mixed $left, mixed $right): variant

left と right を連結し、その結果を返します。

この関数は、理論上は $left . $right と等価です。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

連結した結果を返します。

エラー / 例外

失敗時に com_exception をスローします。

参考

  • 文字列の連結演算子については 文字列演算子


2 つの variant を比較する

  • ≪ variant_cat
  • variant_date_from_timestamp ≫
  • PHP Manual
  • COM関数
  • 2 つの variant を比較する

variant_cmp

(PHP 5, PHP 7, PHP 8)

variant_cmp — 2 つの variant を比較する

説明

variant_cmp(
mixed $left,
mixed $right,
int $locale_id = LOCALE_SYSTEM_DEFAULT,
int $flags = 0
): int

left と right を比較します。

この関数はスカラー値のみを比較します。配列や variant レコードは比較しません。

パラメータ

left

左オペランド。

right

右オペランド。

locale_id

文字列の比較に使用する有効なロケール識別子です (これは文字列の比較に影響します)。

flags

flags は、以下のひとつあるいは複数の値を OR で組み合わせたもので、文字列の比較に影響します。

Variant の比較フラグ
値 | 意味
NORM_IGNORECASE | 大文字小文字を区別せずに比較する
NORM_IGNORENONSPACE | 非スペーシング文字を無視する
NORM_IGNORESYMBOLS | 記号を無視する
NORM_IGNOREWIDTH | 全角半角を区別しない
NORM_IGNOREKANATYPE | ひらがなカタカナを区別しない
NORM_IGNOREKASHIDA | アラビア語の kashida 文字を無視する

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

以下のいずれかを返します。

Variant の比較結果
値 | 意味
VARCMP_LT | left は right より小さい
VARCMP_EQ | left は right と等しい
VARCMP_GT | left は right より大きい
VARCMP_NULL | left と right のいずれか、あるいは両方が null


Unix タイムスタンプを、日付形式の variant で返す

  • ≪ variant_cmp
  • variant_date_to_timestamp ≫
  • PHP Manual
  • COM関数
  • Unix タイムスタンプを、日付形式の variant で返す

variant_date_from_timestamp

(PHP 5, PHP 7, PHP 8)

variant_date_from_timestamp — Unix タイムスタンプを、日付形式の variant で返す

説明

variant_date_from_timestamp(int $timestamp): variant

unix タイムスタンプ値 timestamp を VT_DATE 型の variant に変換します。 これにより、PHP の unix 的な部分と COM とのやりとりが容易になります。

パラメータ

timestamp

unix タイムスタンプ。

戻り値

VT_DATE 型の variant を返します。

参考

  • variant_date_to_timestamp() - 日付/時刻の variant 値を Unix タイムスタンプに変換する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • time() - 現在の Unix タイムスタンプを返す


日付/時刻の variant 値を Unix タイムスタンプに変換する

  • ≪ variant_date_from_timestamp
  • variant_div ≫
  • PHP Manual
  • COM関数
  • 日付/時刻の variant 値を Unix タイムスタンプに変換する

variant_date_to_timestamp

(PHP 5, PHP 7, PHP 8)

variant_date_to_timestamp — 日付/時刻の variant 値を Unix タイムスタンプに変換する

説明

variant_date_to_timestamp(variant $variant): ?int

variant を、VT_DATE (あるいはそれに似た型) から Unix タイムスタンプに変換します。 これにより、PHP の Unix 的な部分と COM とのやりとりが容易になります。

パラメータ

variant

variant。

戻り値

unix タイムスタンプを返します。 失敗時には null を返します。

参考

  • variant_date_from_timestamp() - Unix タイムスタンプを、日付形式の variant で返す
  • date() - Unixタイムスタンプを書式化する
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする


2 つの variant の除算結果を返す

  • ≪ variant_date_to_timestamp
  • variant_eqv ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の除算結果を返す

variant_div

(PHP 5, PHP 7, PHP 8)

variant_div — 2 つの variant の除算結果を返す

説明

variant_div(mixed $left, mixed $right): mixed

left を right で割り、その結果を返します。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の除算規則
もし～なら | このようにします
両者ともに文字列型・日付型・文字・論理型 | Double 型を返す
一方が文字列型で、もう一方が文字 | 除算結果を double 型で返す
一方が数値で、もう一方が文字列 | 除算結果を double 型で返す
両者ともに数値 | 除算結果を double 型で返す
どちらか一方が NULL | NULL が返される
right が空の値で left がそれ以外の型 | コード DISP_E_DIVBYZERO を持った com_exception がスローされる
left が空の値で right がそれ以外の型 | double 型の 0 が返される
両者ともに空の値 | コード DISP_E_OVERFLOW を持った com_exception がスローされる

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_idiv() - variants を整数に変換し、除算の結果を返す


2 つの variant のビット値が等しいかどうかを調べる

  • ≪ variant_div
  • variant_fix ≫
  • PHP Manual
  • COM関数
  • 2 つの variant のビット値が等しいかどうかを調べる

variant_eqv

(PHP 5, PHP 7, PHP 8)

variant_eqv — 2 つの variant のビット値が等しいかどうかを調べる

説明

variant_eqv(mixed $left, mixed $right): variant

2 つの variant のビット値が等しいかどうかを調べます。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

left の各ビットが right の対応するビットに等しい場合に true を、それ以外の場合に false を返します。

エラー / 例外

失敗時に com_exception をスローします。


variant の整数部を返す

  • ≪ variant_eqv
  • variant_get_type ≫
  • PHP Manual
  • COM関数
  • variant の整数部を返す

variant_fix

(PHP 5, PHP 7, PHP 8)

variant_fix — variant の整数部を返す

説明

variant_fix(mixed $value): variant

variant の整数部を取得します。

パラメータ

value

variant。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

value が負の数の場合、variant の値以上の 最初の整数値を返します。それ以外の場合は value の値の整数部分を返します。

エラー / 例外

失敗時に com_exception をスローします。

注意

警告

このドキュメントは MSDN ドキュメントに基づいています。 この関数は variant_int() とまったく同じか、 そうでなければ MSDN ドキュメントに間違いがあると思われます。

参考

  • variant_int() - variant の整数部を返す
  • variant_round() - 指定した桁で variant を丸める
  • floor() - 端数の切り捨て
  • ceil() - 端数の切り上げ
  • round() - 浮動小数点数を丸める


variant オブジェクトの型を返す

  • ≪ variant_fix
  • variant_idiv ≫
  • PHP Manual
  • COM関数
  • variant オブジェクトの型を返す

variant_get_type

(PHP 5, PHP 7, PHP 8)

variant_get_type — variant オブジェクトの型を返す

説明

variant_get_type(variant $variant): int

variant オブジェクトの型を返します。

パラメータ

variant

variant オブジェクト。

戻り値

この関数は、variant の型を表す整数値を返します。 variant は com、 dotnet あるいは variant クラスのインスタンスです。 返される値は、VT_XXX 定数のいずれかと比較することが可能です。

COM および DOTNET オブジェクトの返す値は、通常 VT_DISPATCH です。これらのクラスに対して この関数が動作する理由は、単に COM および DOTNET が VARIANT を 継承しているからというだけのことです。

参考

  • variant_set_type() - variant を「その場で」別の型に変換する


variants を整数に変換し、除算の結果を返す

  • ≪ variant_get_type
  • variant_imp ≫
  • PHP Manual
  • COM関数
  • variants を整数に変換し、除算の結果を返す

variant_idiv

(PHP 5, PHP 7, PHP 8)

variant_idiv — variants を整数に変換し、除算の結果を返す

説明

variant_idiv(mixed $left, mixed $right): variant

left および right を 整数値に変換し、整数の除算を行います。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の整数除算規則
もし～なら | このようにします
両者ともに文字列型・日付型・文字・論理型 | 除算結果を integer 型で返す
一方が文字列型で、もう一方が文字 | 除算
一方が数値で、もう一方が文字列 | 除算
両者ともに数値 | 除算
どちらか一方が NULL | NULL が返される
両者ともに空の値 | com_exception コード DISP_E_DIVBYZERO がスローされる

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_div() - 2 つの variant の除算結果を返す


2 つの variant のビット implication を行う

  • ≪ variant_idiv
  • variant_int ≫
  • PHP Manual
  • COM関数
  • 2 つの variant のビット implication を行う

variant_imp

(PHP 5, PHP 7, PHP 8)

variant_imp — 2 つの variant のビット implication を行う

説明

variant_imp(mixed $left, mixed $right): variant

ビットの implication 操作を行います。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant Implication テーブル
left | right | 結果
true | true | true
true | false | false
true | null | true
false | true | true
false | false | true
false | null | true
null | true | true
null | false | null
null | null | null

エラー / 例外

失敗時に com_exception をスローします。


variant の整数部を返す

  • ≪ variant_imp
  • variant_mod ≫
  • PHP Manual
  • COM関数
  • variant の整数部を返す

variant_int

(PHP 5, PHP 7, PHP 8)

variant_int — variant の整数部を返す

説明

variant_int(mixed $value): variant

variant の整数部を返します。

パラメータ

value

variant。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

value が負の数の場合、variant の値以上の 最初の整数値を返します。それ以外の場合は value の値の整数部分を返します。

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_fix() - variant の整数部を返す
  • variant_round() - 指定した桁で variant を丸める
  • floor() - 端数の切り捨て
  • ceil() - 端数の切り上げ
  • round() - 浮動小数点数を丸める


2 つの variant の除算を行い、剰余を返す

  • ≪ variant_int
  • variant_mul ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の除算を行い、剰余を返す

variant_mod

(PHP 5, PHP 7, PHP 8)

variant_mod — 2 つの variant の除算を行い、剰余を返す

説明

variant_mod(mixed $left, mixed $right): variant

left を right で除算し、剰余を返します。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

除算の剰余を返します。

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_div() - 2 つの variant の除算結果を返す
  • variant_idiv() - variants を整数に変換し、除算の結果を返す


2 つの variant の乗算を行い、その結果を返す

  • ≪ variant_mod
  • variant_neg ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の乗算を行い、その結果を返す

variant_mul

(PHP 5, PHP 7, PHP 8)

variant_mul — 2 つの variant の乗算を行い、その結果を返す

説明

variant_mul(mixed $left, mixed $right): variant

left と right の乗算を行います。

パラメータ

left

左オペランド。

right

右オペランド。

論理型の値は、false が -1 に、そして true が 0 に変換されます。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の乗算規則
もし～なら | このようにします
両者ともに文字列型・日付型・文字・論理型 | 乗算
一方が文字列型で、もう一方が文字 | 乗算
一方が数値で、もう一方が文字列 | 乗算
両者ともに数値 | 乗算
どちらか一方が NULL | NULL が返される
両者ともに空の値 | 空の文字列が返される

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_div() - 2 つの variant の除算結果を返す
  • variant_idiv() - variants を整数に変換し、除算の結果を返す


variant の論理否定演算を行う

  • ≪ variant_mul
  • variant_not ≫
  • PHP Manual
  • COM関数
  • variant の論理否定演算を行う

variant_neg

(PHP 5, PHP 7, PHP 8)

variant_neg — variant の論理否定演算を行う

説明

variant_neg(mixed $value): variant

value の論理否定演算を行います。

パラメータ

value

variant。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

論理否定演算の結果を返します。

エラー / 例外

失敗時に com_exception をスローします。


variant のビット否定演算を行う

  • ≪ variant_neg
  • variant_or ≫
  • PHP Manual
  • COM関数
  • variant のビット否定演算を行う

variant_not

(PHP 5, PHP 7, PHP 8)

variant_not — variant のビット否定演算を行う

説明

variant_not(mixed $value): variant

value のビット否定演算を行い、その結果を返します。

パラメータ

value

variant。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

ビット否定演算の結果を返します。 value が null の場合、 結果も null となります。

エラー / 例外

失敗時に com_exception をスローします。


2 つの variant の論理和を計算する

  • ≪ variant_not
  • variant_pow ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の論理和を計算する

variant_or

(PHP 5, PHP 7, PHP 8)

variant_or — 2 つの variant の論理和を計算する

説明

variant_or(mixed $left, mixed $right): variant

論理 OR 処理を行います。通常の OR 操作とは少し違いがあることに注意しましょう。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の OR 規則
left | right | 結果
true | true | true
true | false | true
true | null | true
false | true | true
false | false | false
false | null | null
null | true | true
null | false | null
null | null | null

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_and() - 2 つの variant の論理積を計算し、結果を返す
  • variant_xor() - 2 つの variant の排他的論理和を計算する


2 つの variant の累乗計算を行い、その結果を返す

  • ≪ variant_or
  • variant_round ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の累乗計算を行い、その結果を返す

variant_pow

(PHP 5, PHP 7, PHP 8)

variant_pow — 2 つの variant の累乗計算を行い、その結果を返す

説明

variant_pow(mixed $left, mixed $right): variant

left の right 乗を返します。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

left の right 乗を返します。

エラー / 例外

失敗時に com_exception をスローします。

参考

  • pow() - 指数表現


指定した桁で variant を丸める

  • ≪ variant_pow
  • variant_set ≫
  • PHP Manual
  • COM関数
  • 指定した桁で variant を丸める

variant_round

(PHP 5, PHP 7, PHP 8)

variant_round — 指定した桁で variant を丸める

説明

variant_round(mixed $value, int $decimals): ?variant

value を、 decimals で指定した桁で丸めた結果を返します。

パラメータ

value

variant。

decimals

小数点の位置。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

丸めた結果を返します。 失敗した場合は null を返します。

参考

  • round() - 浮動小数点数を丸める


variant オブジェクトに新しい値を代入する

  • ≪ variant_round
  • variant_set_type ≫
  • PHP Manual
  • COM関数
  • variant オブジェクトに新しい値を代入する

variant_set

(PHP 5, PHP 7, PHP 8)

variant_set — variant オブジェクトに新しい値を代入する

説明

variant_set(variant $variant, mixed $value): void

value を variant に変換し、それを variant オブジェクトに代入します。 新しい variant オブジェクトは作成されず、 variant の元の値は開放されます。

パラメータ

variant

variant。

value

戻り値

値を返しません。


variant を「その場で」別の型に変換する

  • ≪ variant_set
  • variant_sub ≫
  • PHP Manual
  • COM関数
  • variant を「その場で」別の型に変換する

variant_set_type

(PHP 5, PHP 7, PHP 8)

variant_set_type — variant を「その場で」別の型に変換する

説明

variant_set_type(variant $variant, int $type): void

この関数は variant_cast() に似ていますが、 「その場で」変換されるという点が異なります。新しい variant は 作成されません。この関数に渡すパラメータの意味は variant_cast() の場合と同じです。

パラメータ

variant

variant。

type

戻り値

値を返しません。

参考

  • variant_cast() - variant を、別の型の新しい variant に変換する
  • variant_get_type() - variant オブジェクトの型を返す


左の variant から右の variant を引き、その結果を返す

  • ≪ variant_set_type
  • variant_xor ≫
  • PHP Manual
  • COM関数
  • 左の variant から右の variant を引き、その結果を返す

variant_sub

(PHP 5, PHP 7, PHP 8)

variant_sub — 左の variant から右の variant を引き、その結果を返す

説明

variant_sub(mixed $left, mixed $right): variant

right を left から引きます。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の減算規則
もし～なら | このようにします
両者ともに文字列型 | 減算
一方が文字列型で、もう一方が文字 | 減算
一方が数値で、もう一方が文字列 | 減算
両者ともに数値 | 減算
どちらか一方が NULL | NULL が返される
両者ともに空の値 | 空の文字列が返される

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_add() - 2 つの variant 値を「加算」し、結果を返す


2 つの variant の排他的論理和を計算する

  • ≪ variant_sub
  • win32service ≫
  • PHP Manual
  • COM関数
  • 2 つの variant の排他的論理和を計算する

variant_xor

(PHP 5, PHP 7, PHP 8)

variant_xor — 2 つの variant の排他的論理和を計算する

説明

variant_xor(mixed $left, mixed $right): variant

排他的論理和を計算します。

パラメータ

left

左オペランド。

right

右オペランド。

注意:

variant に関するすべての計算用関数と同様、この関数のパラメータには PHP のネイティブ型 (整数、文字列、浮動小数点数、boolean あるいは null) あるいは COM、VARIANT、DOTNET クラスのインスタンスが使用できます。 PHP のネイティブ型は、variant クラスのコンストラクタと同じ方法で variant に変換されます。 COM オブジェクトおよび DOTNET オブジェクトはデフォルトプロパティの値を持っており、 これを variant の値として使用します。

variant に関する計算関数は、COM ライブラリの同名の関数のラッパーです。 これらの関数についての詳細な情報は、MSDN ライブラリでご確認ください。 PHP での関数名は微妙に異なります。たとえば、PHP での関数 variant_add() に対応する関数は、MSDN のドキュメントでは VarAdd() となります。

戻り値

Variant の XOR 規則
left | right | 結果
true | true | false
true | false | true
false | true | true
false | false | false
null | null | null

エラー / 例外

失敗時に com_exception をスローします。

参考

  • variant_or() - 2 つの variant の論理和を計算する
  • variant_and() - 2 つの variant の論理積を計算し、結果を返す


win32service

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • 実行時設定
    • セキュリティの考慮
  • 定義済み定数
  • Win32ServiceException — The Win32ServiceException class
  • 例
  • win32service 関数
    • win32_continue_service — 中断したサービスを再開する
    • win32_create_service — SCM データベースに新しいサービスのエントリを作成する
    • win32_delete_service — SCM データベースからサービスのエントリを削除する
    • win32_get_last_control_message — サービスに送信された直近の制御メッセージを返す
    • win32_pause_service — サービスを中断する
    • win32_query_service_status — サービスの状態を問い合わせる
    • win32_send_custom_control — Send a custom control to the service
    • win32_set_service_exit_code — Define or return the exit code for the current running service
    • win32_set_service_exit_mode — Define or return the exit mode for the current running service
    • win32_set_service_status — サービスの状態を更新する
    • win32_start_service — サービスを開始する
    • win32_start_service_ctrl_dispatcher — スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
    • win32_stop_service — サービスを停止する


はじめに

win32service は Windows 限定の拡張モジュールです。 サービスコントロールマネージャと連携してサービスの開始・停止・登録・解除を行ったり、 PHP スクリプトをサービスとして実行させる機能を提供します。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • win32service
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • 実行時設定
  • セキュリティの考慮


要件

サポートされているWindows のバージョンは、 PHP をビルドするのに使う Visual C++ 再頒布可能パッケージ がサポートするバージョンと同じです。


インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/win32service


  • ≪ インストール手順
  • セキュリティの考慮 ≫
  • PHP Manual
  • インストール/設定
  • 実行時設定

実行時設定

設定ディレクティブは定義されていません。


セキュリティの考慮

この拡張モジュールでは、アクションによっては管理者権限が必要なものがあります。 たとえば create, delete, start, stop, pause そして continue です。 これによって、Webインターフェイスやリモートからのサービスの操作が可能な場合、 権限の昇格が起きる可能性があります。

現在の管理者のタスクを、非管理者またはサービスアカウントに委譲するために、 サービスにACLを設定できます。 詳細な手順は、 » Microsoft Knowledge Base を参照ください。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Win32Service サービス型のビットマスク
定数 | 値 | 説明
WIN32_SERVICE_WIN32_OWN_PROCESS | 0x00000010 | サービスは自分のプロセスで動作します。
WIN32_SERVICE_INTERACTIVE_PROCESS | 0x00000100 | サービスはデスクトップとのやりとりができます。このオプションは、Windows Vista 以降では使えません。
WIN32_SERVICE_WIN32_OWN_PROCESS_INTERACTIVE | 0x00000110 | サービスは自分のプロセスで動作し、デスクトップとのやりとりができます。このオプションは、Windows Vista 以降では使えません。
Win32Service サービスステータス定数
定数 | 値 | 説明
WIN32_SERVICE_CONTINUE_PENDING | 0x00000005 | サービスの続行が待機状態です。
WIN32_SERVICE_PAUSE_PENDING | 0x00000006 | サービスの中断が待機状態です。
WIN32_SERVICE_PAUSED | 0x00000007 | サービスは中断しています。
WIN32_SERVICE_RUNNING | 0x00000004 | サービスは実行中です。
WIN32_SERVICE_START_PENDING | 0x00000002 | サービスは開始中です。
WIN32_SERVICE_STOP_PENDING | 0x00000003 | サービスは停止中です。
WIN32_SERVICE_STOPPED | 0x00000001 | サービスは動作していません。
Win32Service サービス制御メッセージ定数
定数 | 値 | 説明
WIN32_SERVICE_CONTROL_CONTINUE | 0x00000003 | 停止中のサービスに再開を指示します。
WIN32_SERVICE_CONTROL_DEVICEEVENT | 0x0000000B |
WIN32_SERVICE_CONTROL_HARDWAREPROFILECHANGE | 0x0000000C |
WIN32_SERVICE_CONTROL_INTERROGATE | 0x00000004 | 現状の情報をサービス制御マネージャーに報告するようサービスに指示します。
WIN32_SERVICE_CONTROL_NETBINDADD | 0x00000007 | バインドする新しいコンポーネントがあった場合、ネットワークサービスに通知します。
WIN32_SERVICE_CONTROL_NETBINDDISABLE | 0x0000000A | バインドされているコンポーネントが無効にされた場合、ネットワークサービスに通知します。
WIN32_SERVICE_CONTROL_NETBINDENABLE | 0x00000009 | 無効にされていたバインディングが有効になった場合、ネットワークサービスに通知します。
WIN32_SERVICE_CONTROL_NETBINDREMOVE | 0x00000008 | バインドされているコンポーネントが削除された場合、ネットワークサービスに通知します。
WIN32_SERVICE_CONTROL_PARAMCHANGE | 0x00000006 | 起動時のパラメータが変更されたことをサービスに通知します。
WIN32_SERVICE_CONTROL_PAUSE | 0x00000002 | サービスに停止するよう指示します。
WIN32_SERVICE_CONTROL_POWEREVENT | 0x0000000D |
WIN32_SERVICE_CONTROL_PRESHUTDOWN | 0x0000000F | サービスに、システムのシャットダウンを通知します。 この通知を処理するサービスは、サービスが終了するかあるいはシャットダウン前のタイムアウトに達するまで システムのシャットダウンを待機させることができます。 この値は、Windows Server 2003 および Windows XP/2000 以降では使えません。
WIN32_SERVICE_CONTROL_SESSIONCHANGE | 0x0000000E |
WIN32_SERVICE_CONTROL_SHUTDOWN | 0x00000005 | サービスに、システムがシャットダウンするので後始末をするよう通知します。 サービスがこの制御コードを受け付けた場合は、 後始末のタスクを終えてからサービスを終了しなければなりません。 SCM がこの制御コードを送った後は、他の制御コードを送ることはできません。
WIN32_SERVICE_CONTROL_STOP | 0x00000001 | サービスに終了するよう指示します。
Win32Service サービス制御メッセージが受領されたときのビットマスク
定数 | 値 | 説明
WIN32_SERVICE_ACCEPT_HARDWAREPROFILECHANGE | 0x00000020 | コンピューターのハードウェアプロファイルが変化した場合にサービスに通知します。 これによって、システムは WIN32_SERVICE_CONTROL_HARDWAREPROFILECHANGE をサービスに通知できるようになります。
WIN32_SERVICE_ACCEPT_NETBINDCHANGE | 0x00000010 | このサービスは、停止や再起動なしに、 バインディングの変更を受け入れることができるネットワークコンポーネントです。 この制御コードは、サービスが WIN32_SERVICE_CONTROL_NETBINDADD, WIN32_SERVICE_CONTROL_NETBINDREMOVE, WIN32_SERVICE_CONTROL_NETBINDENABLE および WIN32_SERVICE_CONTROL_NETBINDDISABLE の通知を受け取れることを表します。
WIN32_SERVICE_ACCEPT_PARAMCHANGE | 0x00000008 | サービスを停止したり再起動することなく、スタートアップパラメータを再読込できるサービスです。 この制御コードは、サービスが WIN32_SERVICE_CONTROL_PARAMCHANGE の通知を受け取れることを表します。
WIN32_SERVICE_ACCEPT_PAUSE_CONTINUE | 0x00000002 | サービスは一時停止して続行できます。この制御コードは、サービスが WIN32_SERVICE_CONTROL_PAUSE および WIN32_SERVICE_CONTROL_CONTINUE の通知を受け取れることを表します。
WIN32_SERVICE_ACCEPT_POWEREVENT | 0x00000040 | コンピューターの電源状態が変化した時にサービスに通知します。 これによって、システムが WIN32_SERVICE_CONTROL_POWEREVENT 通知をサービスに送信できるようになります。
WIN32_SERVICE_ACCEPT_PRESHUTDOWN | 0x00000100 | サービスはシャットダウン前のタスクを処理できます。この制御コードは、サービスが WIN32_SERVICE_CONTROL_PRESHUTDOWN の通知を受け取れることを表します。 この値は Windows Server 2003 や Windows XP/2000 以降では使えません。
WIN32_SERVICE_ACCEPT_SESSIONCHANGE | 0x00000080 | コンピューターのセッション状態が変更された場合にサービスに通知します。 これによって、システムは WIN32_SERVICE_CONTROL_SESSIONCHANGE 通知をサービスに送信できるようになります。 Windows 2000 では、この値は使えません。
WIN32_SERVICE_ACCEPT_SHUTDOWN | 0x00000004 | サービスはシステムのシャットダウン通知を受け取ります。この制御コードは、サービスが WIN32_SERVICE_CONTROL_SHUTDOWN の通知を受け取れることを表します。
WIN32_SERVICE_ACCEPT_STOP | 0x00000001 | サービスは終了できます。この制御コードは、サービスが WIN32_SERVICE_CONTROL_STOP の通知を受け取れることを表します。
WIN32_SERVICE_ACCEPT_TIMECHANGE | 0x00000200 | システム時刻が変更された場合にサービスに通知します。 これによって、システムは WIN32_SERVICE_CONTROL_TIMECHANGE 通知をサービスに送信できるようになります。 Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP/2000 では、この制御コードはサポートされていません。
WIN32_SERVICE_ACCEPT_TRIGGEREVENT | 0x00000400 | サービスの登録イベントが起きた場合にサービスに通知します。 これによって、システムは WIN32_SERVICE_CONTROL_TRIGGEREVENT 通知をサービスに送信できるようになります。 Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP/2000 では、この制御コードはサポートされていません。
Win32Service サービス開始型定数
定数 | 値 | 説明
WIN32_SERVICE_BOOT_START | 0x00000000 | デバイスドライバがシステムローダによって開始されました。 この値はドライバサービス向けにのみ有効です。
WIN32_SERVICE_SYSTEM_START | 0x00000001 | デバイスドライバが IoInitSystem 関数によって開始されました。 この値はドライバサービス向けにのみ有効です。
WIN32_SERVICE_AUTO_START | 0x00000002 | システムの起動時に、サービス制御マネージャーが自動的にサービスを開始します。
WIN32_SERVICE_DEMAND_START | 0x00000003 | プロセスが StartService 関数をコールしたときに、 サービス制御マネージャーがサービスを開始します。
WIN32_SERVICE_DISABLED | 0x00000004 | サービスを開始することができません。開始させようとすると、エラーコード WIN32_ERROR_SERVICE_DISABLED を返します。
Win32Service サービスエラー制御定数
定数 | 値 | 説明
WIN32_SERVICE_ERROR_IGNORE | 0x00000000 | 起動プログラムはエラーを無視し、開始操作を続行します。
WIN32_SERVICE_ERROR_NORMAL | 0x00000001 | 起動プログラムはエラーをイベントログに記録し、開始操作を続行します。
WIN32_SERVICE_ERROR_SEVERE | 0x00000002 | 起動プログラムはエラーをイベントログに記録します。 最後に正常起動した構成で起動中の場合、 起動処理は続行されます。そうでない場合、 システムは最後に正常起動した構成で再起動されます。
WIN32_SERVICE_ERROR_CRITICAL | 0x00000003 | 起動プログラムは可能であれば、エラーをイベントログに記録します。 最後に正常起動した構成で起動中の場合、 起動処理は失敗します。 そうでない場合、 システムは最後に正常起動した構成で再起動されます。
Win32Service サービスフラグ定数
定数 | 値 | 説明
WIN32_SERVICE_RUNS_IN_SYSTEM_PROCESS | 0x00000001 | サービスはシステムプロセスで動作し、常に動作している必要があります。

注意:

これらの定数は、Win32Service 1.0.0 以降では使えません。

Win32 エラーコード
定数 | 値 | 説明
WIN32_ERROR_ACCESS_DENIED | 0x00000005 | SCM データベースへのハンドルに適切なアクセス権限がありません。
WIN32_ERROR_CIRCULAR_DEPENDENCY | 0x00000423 | 循環依存のサービスを指定しました。
WIN32_ERROR_DATABASE_DOES_NOT_EXIST | 0x00000429 | 指定したデータベースが存在しません。
WIN32_ERROR_DEPENDENT_SERVICES_RUNNING | 0x0000041B | 他の実行中のサービスがこのサービスに依存しているため、サービスを終了できません。
WIN32_ERROR_DUPLICATE_SERVICE_NAME | 0x00000436 | その表示名が、サービス制御マネージャーのデータベース内に (データベース名あるいは別の表示名として) 既に存在します。
WIN32_ERROR_FAILED_SERVICE_CONTROLLER_CONNECT | 0x00000427 | このエラーは、サービスではなくコンソールアプリケーションとしてプログラムを実行したときに返されます。 デバッグ用にコンソールアプリケーションとして実行する場合は、 サービスに固有のコードをコールしないようにしましょう。
WIN32_ERROR_INSUFFICIENT_BUFFER | 0x0000007A | サービス状況構造体用のバッファが小さすぎます。構造体には何も書き込まれませんでした。
WIN32_ERROR_INVALID_DATA | 0x0000000D | 指定したサービス状況構造体が無効です。
WIN32_ERROR_INVALID_HANDLE | 0x00000006 | サービス制御マネージャーデータベースへのハンドルが無効です。
WIN32_ERROR_INVALID_LEVEL | 0x0000007C | InfoLevel パラメータにサポートしていない値が含まれています。
WIN32_ERROR_INVALID_NAME | 0x0000007B | 指定したサービス名が無効です。
WIN32_ERROR_INVALID_PARAMETER | 0x00000057 | 指定したパラメータが無効です。
WIN32_ERROR_INVALID_SERVICE_ACCOUNT | 0x00000421 | user で指定したユーザーアカウントが存在しません。 win32_create_service() を参照ください。
WIN32_ERROR_INVALID_SERVICE_CONTROL | 0x0000041C | 指定した制御コードが無効、あるいはこのサービスでは処理できません。
WIN32_ERROR_PATH_NOT_FOUND | 0x00000003 | サービスのバイナリファイルが見つかりません。
WIN32_ERROR_SERVICE_ALREADY_RUNNING | 0x00000420 | サービスのインスタンスが既に動作中です。
WIN32_ERROR_SERVICE_CANNOT_ACCEPT_CTRL | 0x00000425 | 指定した制御コードをサービスに送れませんでした。サービスの状態が WIN32_SERVICE_STOPPED、 WIN32_SERVICE_START_PENDING あるいは WIN32_SERVICE_STOP_PENDING だったためです。
WIN32_ERROR_SERVICE_DATABASE_LOCKED | 0x0000041F | データベースがロックされています。
WIN32_ERROR_SERVICE_DEPENDENCY_DELETED | 0x00000433 | このサービスが依存する別のサービスが存在しないか、あるいは削除マークがつけられています。
WIN32_ERROR_SERVICE_DEPENDENCY_FAIL | 0x0000042C | このサービスが依存する別のサービスの起動に失敗しました。
WIN32_ERROR_SERVICE_DISABLED | 0x00000422 | サービスが無効化されました。
WIN32_ERROR_SERVICE_DOES_NOT_EXIST | 0x00000424 | 指定したサービスはインストール済みのサービスの中に存在しません。
WIN32_ERROR_SERVICE_EXISTS | 0x00000431 | 指定したサービスは既にこのデータベースに存在します。
WIN32_ERROR_SERVICE_LOGON_FAILED | 0x0000042D | ログオンに失敗したためサービスを起動できません。このエラーが発生するのは、 そのサービスが "Log on as a service" 権限のないアカウントで動作するように設定されている場合です。
WIN32_ERROR_SERVICE_MARKED_FOR_DELETE | 0x00000430 | 指定したサービスには既に削除マークがついています。
WIN32_ERROR_SERVICE_NO_THREAD | 0x0000041E | このサービスのスレッドを作成できません。
WIN32_ERROR_SERVICE_NOT_ACTIVE | 0x00000426 | サービスが起動していません。
WIN32_ERROR_SERVICE_REQUEST_TIMEOUT | 0x0000041D | サービスのプロセスは起動しましたが StartServiceCtrlDispatcher をコールしていません。あるいは StartServiceCtrlDispatcher をコールしたスレッドが制御ハンドラ関数でブロックされています。
WIN32_ERROR_SHUTDOWN_IN_PROGRESS | 0x0000045B | システムがシャットダウン中なので、この関数はコールできません。
WIN32_ERROR_SERVICE_SPECIFIC_ERROR | 0x0000042A | サービスがサービス特有のエラーコードを返しました。
WIN32_NO_ERROR | 0x00000000 | エラーはありません。
Win32 ベース優先度クラス
定数 | 値 | 説明
WIN32_ABOVE_NORMAL_PRIORITY_CLASS | 0x00008000 | WIN32_NORMAL_PRIORITY_CLASS よりも高いけれど WIN32_HIGH_PRIORITY_CLASS よりは低い優先度のプロセス。
WIN32_BELOW_NORMAL_PRIORITY_CLASS | 0x00004000 | WIN32_IDLE_PRIORITY_CLASS よりも高いけれど WIN32_NORMAL_PRIORITY_CLASS よりは低い優先度のプロセス。
WIN32_HIGH_PRIORITY_CLASS | 0x00000080 | ただちに実行しなければならないような、時間制約の厳しいプロセス。 このプロセスのスレッドは、優先度クラスが NORMAL あるいは IDLE であるすべてのプロセスのスレッドを先取りします。 このクラスを使う例はタスクリストです。 タスクリストは、ユーザーが呼び出したときは OS の負荷にかかわらずすぐに反応しなければなりません。 この優先度クラスを使うときには細心の注意が必要です。 この優先度クラスのアプリケーションは CPU をほぼすべて使い切ってしまうこともあるからです。
WIN32_IDLE_PRIORITY_CLASS | 0x00000040 | システムがアイドル状態のときにだけスレッドが実行されるプロセス。 より優先度クラスの高いプロセスが実行中の場合は、 そちらのスレッドが優先的に実行されます。 このクラスを使う例はスクリーンセーバーです。 この優先度クラスは、子プロセスにも引き継がれます。
WIN32_NORMAL_PRIORITY_CLASS | 0x00000020 | 特別なスケジューリングが不要なプロセス。
WIN32_REALTIME_PRIORITY_CLASS | 0x00000100 | 可能な限り優先度を高くするプロセス。 このプロセスのスレッドは、他のすべてのプロセスのスレッドを先取りします。 重要なタスクをこなす OS のプロセスであっても例外ではありません。 リアルタイムプロセスを非常に短い間隔で実行させると、 ディスクキャッシュがフラッシュされなくなったり マウスが反応しなくなったりすることがあり得ます。
Win32 リカバリアクション
定数 | 値 | 説明
WIN32_SC_ACTION_NONE | 0x00000000 | アクションを実行しません。
WIN32_SC_ACTION_RESTART | 0x00000001 | サービスを再起動します。
WIN32_SC_ACTION_REBOOT | 0x00000002 | サーバーを再起動します。
WIN32_SC_ACTION_RUN_COMMAND | 0x00000003 | コマンドを実行します。
Win32 サービスの情報
定数 | 値 | 説明
WIN32_INFO_SERVICE | "service" |
WIN32_INFO_DISPLAY | "display" |
WIN32_INFO_USER | "user" |
WIN32_INFO_PASSWORD | "password" |
WIN32_INFO_PATH | "path" |
WIN32_INFO_PARAMS | "params" |
WIN32_INFO_DESCRIPTION | "description" |
WIN32_INFO_START_TYPE | "start_type" |
INFO_LOAD_ORDER | "load_order" |
INFO_SVC_TYPE | "svc_type" |
INFO_ERROR_CONTROL | "error_control" |
INFO_DELAYED_START | "delayed_start" |
INFO_BASE_PRIORITY | "base_priority" |
INFO_DEPENDENCIES | "dependencies" |
INFO_RECOVERY_DELAY | "recovery_delay" |
INFO_RECOVERY_ACTION_1 | "recovery_action_1" |
INFO_RECOVERY_ACTION_2 | "recovery_action_2" |
INFO_RECOVERY_ACTION_3 | "recovery_action_3" |
INFO_RECOVERY_RESET_PERIOD | "recovery_reset_period" |
INFO_RECOVERY_ENABLED | "recovery_enabled" |
INFO_RECOVERY_REBOOT_MSG | "recovery_reboot_msg" |
INFO_RECOVERY_COMMAND | "recovery_command" |


The Win32ServiceException class

(PECL win32service >=1.0.0)

はじめに

この例外は、 エラーを検知するために、 定数と比較する必要があった古いやり方を置き換えるものです。 この例外が持つコードは、対応する定数の値と等しく、 例外メッセージも対応する定数名に基づいています。

クラス概要

class Win32ServiceException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


例

例1 PHP スクリプトをサービスとして登録する

<?php
win32_create_service(array(
'service' => 'dummyphp', # サービスの名前
'display' => 'sample dummy PHP service', # 短い説明
'description' => 'This is a dummy Windows service created using PHP.', # 長い説明
'params' => '"' . __FILE__ . '" run', # スクリプトへのパスとパラメータ
));
?>

例2 サービスの登録を解除する

<?php
win32_delete_service('dummyphp');
?>

例3 サービスとして実行する

<?php
if ($argv[1] == 'run') {
win32_start_service_ctrl_dispatcher('dummyphp');

while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) {
# ここに実際の作業内容を書きます。
# 1 回のループに 30 秒以上かからないように心がけてください。
}
}
?>


win32service 関数

目次

  • win32_continue_service — 中断したサービスを再開する
  • win32_create_service — SCM データベースに新しいサービスのエントリを作成する
  • win32_delete_service — SCM データベースからサービスのエントリを削除する
  • win32_get_last_control_message — サービスに送信された直近の制御メッセージを返す
  • win32_pause_service — サービスを中断する
  • win32_query_service_status — サービスの状態を問い合わせる
  • win32_send_custom_control — Send a custom control to the service
  • win32_set_service_exit_code — Define or return the exit code for the current running service
  • win32_set_service_exit_mode — Define or return the exit mode for the current running service
  • win32_set_service_status — サービスの状態を更新する
  • win32_start_service — サービスを開始する
  • win32_start_service_ctrl_dispatcher — スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
  • win32_stop_service — サービスを停止する


中断したサービスを再開する

  • ≪ win32service 関数
  • win32_create_service ≫
  • PHP Manual
  • win32service 関数
  • 中断したサービスを再開する

win32_continue_service

(PECL win32service >=0.1.0)

win32_continue_service — 中断したサービスを再開する

説明

win32_continue_service(string $servicename, string $machine = ?): void

指定した名前の、中断しているサービスを再開します。 管理者権限、 またはサービスのACLで適切な権限が設定されたアカウントが必要です。

パラメータ

servicename

サービスの短い名前。

machine

マシン名。省略可能で、省略した場合はローカルマシンを使います。

戻り値

値を返しません。

バージョン 1.0.0 より前では、 成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

servicename の値が空の場合は、 ValueError がスローされます。

エラーが発生した場合は、 Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.3.0 | ACLが別のアカウントに設定されていた場合、 この関数には管理者権限が不要になりました。

参考

  • win32_start_service() - サービスを開始する
  • win32_stop_service() - サービスを停止する
  • win32_pause_service() - サービスを中断する
  • win32_send_custom_control() - Send a custom control to the service
  • Win32 エラーコード


SCM データベースに新しいサービスのエントリを作成する

  • ≪ win32_continue_service
  • win32_delete_service ≫
  • PHP Manual
  • win32service 関数
  • SCM データベースに新しいサービスのエントリを作成する

win32_create_service

(PECL win32service >=0.1.0)

win32_create_service — SCM データベースに新しいサービスのエントリを作成する

説明

win32_create_service(array $details, string $machine = ?): void

SCM データベースに新しいサービスの追加を試みます。 この操作を成功させるには、管理者権限が必要です。

パラメータ

details

サービスの詳細情報を含む配列。

service

サービスの短い名前。net コマンドでサービスを 制御する際に、この名前を使用します。この名前は一意である（同名の サービスが 2 つ存在することがない）必要があり、スペースを含む 名前は可能な限り避けるべきです。

display

サービスの表示名。これは、サービスアプレットに表示される名前です。

description

サービスの長い名前。これは「サービス」アプレットで表示される名前です。

user

サービスを実行するユーザー名。指定しなかった場合、サービスは LocalSystem アカウントで実行されます。ユーザー名が指定された場合、 password も指定する必要があります。

password

user に対応するパスワード。

path

サービスの開始時に起動される実行モジュールのフルパス。 指定しなかった場合、現在の PHP プロセスへのパスが使用されます。

params

サービスの開始時に渡されるコマンドラインパラメータ。 PHP スクリプトをサービスとして実行したい場合は、最初のパラメータは 実行するスクリプトへのフルパスとなります。 スクリプト名やパスにスペースを含む場合は、PHP スクリプトへのフルパスを " で囲まなければなりません。

load_order

load_order を制御します。現時点では完全にはサポートされていません。

svc_type

サービスの型を指定します。指定しなかった場合、デフォルト値は WIN32_SERVICE_WIN32_OWN_PROCESS です。 よくわからない場合はこの値を変更しないでください。

start_type

サービスをどのように開始させるかを指定します。デフォルトは WIN32_SERVICE_AUTO_START で、これは マシンの起動時にサービスを開始させることを意味します。

error_control

サービスに問題が発生した際にとるべき行動を SCM に指示します。 デフォルトは WIN32_SERVER_ERROR_IGNORE です。 この値を変更することは、現時点では完全にはサポートされていません。

delayed_start

delayed_start を true にすると、 他の自動起動サービスが開始したあとで少し間をおいてサービスが起動するようになります。

任意のサービスに対してこれを指定することができますが、そのサービスの start_type が WIN32_SERVICE_AUTO_START でない場合は何の効果も及ぼしません。

この設定が使えるのは、Windows Vista および Windows Server 2008 以降のみです。

base_priority

プロセッサの使用状況への影響を考慮すると、 ベース優先度は通常より低めに設定しておかなければなりません。

base_priority には、 Win32 ベース優先度クラス で定義された定数のいずれかを設定します。

dependencies

サービスへの依存性を定義します。 サービス名の一覧を配列として設定する必要があるかもしれません。

recovery_delay

失敗時とリカバリアクションの実行の間に取る時間を定義します。 この値はマイクロ秒単位です。

デフォルトは 60000 です。

recovery_action_1

最初の失敗時に実行されるアクションです。 デフォルトの値は WIN32_SC_ACTION_NONE です。

recovery_action_1 は、 Win32 Recovery action で定義された定数のうちのひとつを設定できます。

recovery_action_2

二回目の失敗時に実行されるアクションです。 デフォルトの値は WIN32_SC_ACTION_NONE です。

recovery_action_2 は、 Win32 Recovery action で定義された定数のうちのひとつを設定できます。

recovery_action_3

3回目以降の失敗時に実行されるアクションです。 デフォルトの値は WIN32_SC_ACTION_NONE です。

recovery_action_3 は、 Win32 Recovery action で定義された定数のうちのひとつを設定できます。

recovery_reset_period

ここで定義された時間が経過すると、失敗のカウンタがリセットされます。 秒単位で設定します。

デフォルト値は 86400 です。

recovery_enabled

リカバリ設定を有効にする場合は true を設定します。 無効にする場合は false を設定します。

デフォルトは false です。

recovery_reboot_msg

リブート時に Windows のイベントログに記録されるメッセージを設定します。 アクションを WIN32_SC_ACTION_REBOOT に設定する場合にだけ使ってください。

recovery_command

アクションが WIN32_SC_ACTION_RUN_COMMAND に設定された場合に、実行されるコマンドを設定します。

machine

オプションで、サービスを作成したいマシン名を指定します。 指定しなかった場合は、ローカルマシンを使用します。

戻り値

値を返しません。

バージョン 1.0.0 より前では、成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

service 引数が空の場合、 ValueError がスローされます。

path 引数が渡されていないか、空の場合、 ValueError がスローされます。

svc_type 引数が不正な場合は、 ValueError がスローされます。

start_type 引数が不正な場合は、 ValueError がスローされます。

error_control 引数が不正な場合は、 ValueError がスローされます。

base_priority 引数が不正な場合は、 ValueError がスローされます。

recovery_delay 引数が 0 と PHP_INT_MAX の間にない場合は、 ValueError がスローされます。

recovery_action_1 引数が不正な場合は、 ValueError がスローされます。

recovery_action_2 引数が不正な場合は、 ValueError がスローされます。

recovery_action_3 引数が不正な場合は、 ValueError がスローされます。

recovery_reset_period 引数が 0 と PHP_INT_MAX の間にない場合は、 ValueError がスローされます。

エラーが発生した場合は、Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.4.0 | dependencies, recovery_delay, recovery_action_1, recovery_action_2, recovery_action_3, recovery_reset_period, recovery_enabled, recovery_reboot_msg および recovery_command パラメータが追加されました。

例

例1 win32_create_service() の例

'dummyphp' というショートネームのサービスを作ります。

<?php
$x = win32_create_service(array(
'service' => 'dummyphp', // サービスの名前
'display' => 'sample dummy PHP service', // 短い説明
'description' => 'This is a dummy Windows service created using PHP.', // 長い説明
'params' => '"' . __FILE__ . '" run', // スクリプトへのパスとパラメータ
));
debug_zval_dump($x);
?>

例2 依存性を用いた win32_create_service() の例

依存性がある 'dummyphp' というショートネームのサービスを作ります。

<?php
$x = win32_create_service(array(
'service' => 'dummyphp', // サービスの名前
'display' => 'sample dummy PHP service', // 短い説明
'description' => 'This is a dummy Windows service created using PHP.', // 長い説明
'params' => '"' . __FILE__ . '" run', // スクリプトへのパスとパラメータ
'dependencies' => array("Netman"), // 依存性のリスト
));
debug_zval_dump($x);
?>

例3 リカバリ設定を用いた win32_create_service() の例

リカバリ設定がある 'dummyphp' というショートネームのサービスを作ります。

<?php
$x = win32_create_service(array(
'service' => 'dummyphp', // サービスの名前
'display' => 'sample dummy PHP service', // 短い説明
'description' => 'This is a dummy Windows service created using PHP.', // 長い説明
'params' => '"' . __FILE__ . '" run', // スクリプトへのパスとパラメータ
'recovery_delay' => 120000, // 2分後に実行されるリカバリアクション
'recovery_action_1' => WIN32_SC_ACTION_RESTART, // 最初の失敗時にサービスを再起動する
'recovery_action_2' => WIN32_SC_ACTION_RUN_COMMAND, // 2回目の失敗時にはコマンドを実行
'recovery_action_3' => WIN32_SC_ACTION_NONE, // その他の失敗時には何もしない
'recovery_reset_period' => 86400, // 1日後には失敗のカウンタをリセット
'recovery_enabled' => true, // リカバリパラメータを有効にする
'recovery_reboot_msg' => null, // 不要ならリブート時のメッセージは定義するな
'recovery_command' => "c:\clean-service.bat", // アクションが WIN32_SC_ACTION_RUN_COMMAND の場合、このコマンドが実行される
));
debug_zval_dump($x);
?>

参考

  • win32_delete_service() - SCM データベースからサービスのエントリを削除する
  • Win32 Base Priority Classes
  • Win32 Recovery action
  • Win32 Error Codes


SCM データベースからサービスのエントリを削除する

  • ≪ win32_create_service
  • win32_get_last_control_message ≫
  • PHP Manual
  • win32service 関数
  • SCM データベースからサービスのエントリを削除する

win32_delete_service

(PECL win32service >=0.1.0)

win32_delete_service — SCM データベースからサービスのエントリを削除する

説明

win32_delete_service(string $servicename, string $machine = ?): void

SCM データベースからサービスの削除を試みます。管理者権限が必要です。

この関数は、単にサービスに削除マークをつけるだけです。もし他のプロセス （サービスアプレットなど）が開かれた場合、削除処理はそのアプリケーションが 終了するまで延期されます。サービスに削除マークがつけられると、それ以降は 同じサービスに対する削除の試行は失敗します。また同名の新規サービスを作成 しようとする処理も失敗します。

パラメータ

servicename

サービスの短い名前。

machine

オプションのマシン名。指定しなかった場合、ローカルマシンが使用されます。

戻り値

値を返しません。

バージョン 1.0.0 より前では、 成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

servicename 引数が空の場合は、 ValueError がスローされます。

エラー時には Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。

例

例1 win32_delete_service() の例

dummyphp サービスを削除します。

<?php
win32_delete_service('dummyphp');
?>

参考

  • win32_create_service() - SCM データベースに新しいサービスのエントリを作成する
  • Win32 エラーコード


サービスに送信された直近の制御メッセージを返す

  • ≪ win32_delete_service
  • win32_pause_service ≫
  • PHP Manual
  • win32service 関数
  • サービスに送信された直近の制御メッセージを返す

win32_get_last_control_message

(PECL win32service >=0.1.0)

win32_get_last_control_message — サービスに送信された直近の制御メッセージを返す

説明

win32_get_last_control_message(): int

サービスプロセスに送信された、直近の制御コードを返します。 サービスの実行中は、サービスを停止させる必要がないかを調べるために 定期的にこれをチェックすべきです。

警告

0.2.0 以降では、この関数は "cli" SAPI でのみ動作します。 他の SAPI では、この関数は無効になっています。

パラメータ

この関数にはパラメータはありません。

戻り値

制御コード定数を返します。以下の Win32Service サービス制御メッセージ定数 のひとつです。 WIN32_SERVICE_CONTROL_CONTINUE, WIN32_SERVICE_CONTROL_DEVICEEVENT, WIN32_SERVICE_CONTROL_HARDWAREPROFILECHANGE, WIN32_SERVICE_CONTROL_INTERROGATE, WIN32_SERVICE_CONTROL_NETBINDADD, WIN32_SERVICE_CONTROL_NETBINDDISABLE, WIN32_SERVICE_CONTROL_NETBINDENABLE, WIN32_SERVICE_CONTROL_NETBINDREMOVE, WIN32_SERVICE_CONTROL_PARAMCHANGE, WIN32_SERVICE_CONTROL_PAUSE, WIN32_SERVICE_CONTROL_POWEREVENT, WIN32_SERVICE_CONTROL_PRESHUTDOWN, WIN32_SERVICE_CONTROL_SESSIONCHANGE, WIN32_SERVICE_CONTROL_SHUTDOWN, WIN32_SERVICE_CONTROL_STOP。

値が 128 から 255 の場合、制御コードはカスタムの値です。

エラー / 例外

バージョン 1.0.0 より前のバージョンでは、SAPI が "cli" でない場合、 この関数は E_ERROR レベルのエラーを発生させていました。

バージョン 1.0.0 移行は、 SAPI が "cli" でない場合、 Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 0.2.0 | この関数は "cli" SAPI でのみ動作するようになりました。

参考

  • win32_start_service_ctrl_dispatcher() - スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
  • win32_set_service_status() - サービスの状態を更新する
  • win32_set_service_exit_mode() - Define or return the exit mode for the current running service
  • win32_set_service_exit_code() - Define or return the exit code for the current running service
  • Win32Service サービス制御メッセージ定数


サービスを中断する

  • ≪ win32_get_last_control_message
  • win32_query_service_status ≫
  • PHP Manual
  • win32service 関数
  • サービスを中断する

win32_pause_service

(PECL win32service >=0.1.0)

win32_pause_service — サービスを中断する

説明

win32_pause_service(string $servicename, string $machine = ?): void

指定した名前のサービスを中断します。 管理者権限、 またはサービスのACLで適切な権限が設定されたアカウントが必要です。

パラメータ

servicename

サービスの短い名前。

machine

マシン名。省略可能で、省略した場合はローカルマシンを使います。

戻り値

値を返しません。

バージョン 1.0.0 より前では、 成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

servicename 引数が空の場合、 ValueError がスローされます。

エラー時には Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.3.0 | ACLが別のアカウントに設定されていた場合、 この関数には管理者権限が不要になりました。

参考

  • win32_start_service() - サービスを開始する
  • win32_stop_service() - サービスを停止する
  • win32_continue_service() - 中断したサービスを再開する
  • win32_send_custom_control() - Send a custom control to the service
  • Win32 エラーコード


サービスの状態を問い合わせる

  • ≪ win32_pause_service
  • win32_send_custom_control ≫
  • PHP Manual
  • win32service 関数
  • サービスの状態を問い合わせる

win32_query_service_status

(PECL win32service >=0.1.0)

win32_query_service_status — サービスの状態を問い合わせる

説明

win32_query_service_status(string $servicename, string $machine = ?): array

サービスの稼動状況を問い合わせ、情報を配列で返します。

パラメータ

servicename

サービスの短い名前。

machine

オプションのマシン名。指定しなかった場合、ローカルマシンが使用されます。

戻り値

成功した場合に以下の情報を含む配列を返します。

バージョン 1.0.0 より前では、パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

ServiceType

dwServiceType Win32Service サービス型のビットマスク を参照ください。

CurrentState

dwCurrentState Win32Service サービスステータス定数 を参照ください。

ControlsAccepted

サービスが許可しているコントロール。 Win32Service サービス制御メッセージが受領されたときのビットマスク を参照ください。

Win32ExitCode

サービスが終了した際にプロセスが返すコード。 この値は終了モードがgracefulでなかった場合、 WIN32_ERROR_SERVICE_SPECIFIC_ERROR と同じです。 Win32Service エラーコード および win32_set_service_exit_mode() も参照ください。

ServiceSpecificExitCode

サービスが異常終了した際にイベントログに記録されるコード。 この値は win32_set_service_exit_code() で定義された値と同じです。

CheckPoint

サービスが終了する際に、現在のチェックポイント番号を保持します。 SCM はこれをいわゆる心拍のように扱い、反応しなくなったサービスを 検出するために使用します。この値は、WaitHint の値と組み合わせて 用いられます。

WaitHint

サービスが終了する際に、WaitHint を checkpoint の値に設定します。 この処理が終了した時点でサービスの終了処理が 100% 完了したことを示します。 これは、進捗状況のインジケータを実装する際に使用します。

ProcessId

Windows のプロセス ID 。0 の場合、プロセスは実行していません。

ServiceFlags

dwServiceFlags Win32Service サービスフラグ定数 を参照ください。

エラー / 例外

servicename 引数が空の場合、 ValueError がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が array になりました。 これより前のバージョンでは、mixed でした。

参考

  • Win32Service 定義済み定数


Send a custom control to the service

  • ≪ win32_query_service_status
  • win32_set_service_exit_code ≫
  • PHP Manual
  • win32service 関数
  • Send a custom control to the service

win32_send_custom_control

(PECL win32service >=0.4.0)

win32_send_custom_control — Send a custom control to the service

説明

win32_send_custom_control(string $servicename, int $control, string $machine = ?): void

See » Microsoft ControlService function for more details

パラメータ

servicename

The short name of the service.

control

The custom contole value between 128 and 255.

machine

Optional machine name. If omitted, the local machine is used.

戻り値

値を返しません。

Prior to version 1.0.0, 成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

Prior to version 1.0.0, if the control value is not between 128 and 255, this function emits an E_ERROR level error.

A ValueError is thrown if the value of servicename parameter is empty.

A ValueError is thrown if the value of control parameter is not between 128 and 255.

A Win32ServiceException is thrown on error.

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | Throws a ValueError on invalid data in parameters, previously false was returned.
PECL win32service 1.0.0 | Throws a Win32ServiceException on error, previously a Win32 Error Code was returned.
PECL win32service 1.0.0 | The return type is now void, previously it was mixed.

参考

  • win32_start_service() - サービスを開始する
  • win32_stop_service() - サービスを停止する
  • win32_pause_service() - サービスを中断する
  • win32_continue_service() - 中断したサービスを再開する
  • Win32 Error Codes


Define or return the exit code for the current running service

  • ≪ win32_send_custom_control
  • win32_set_service_exit_mode ≫
  • PHP Manual
  • win32service 関数
  • Define or return the exit code for the current running service

win32_set_service_exit_code

(PECL win32service >=0.4.0)

win32_set_service_exit_code — Define or return the exit code for the current running service

説明

win32_set_service_exit_code(int $exitCode = 1): int

Change or return the exit code. The exit code is used only if the exit mode is not graceful. If the value is not zero, the recovery configuration can be used after service fail. See » Microsoft system error codes for more details

警告

This function work only in "cli" SAPI. On other SAPI this function is disabled.

パラメータ

exitCode

The return code used on exit.

戻り値

Return the current or old exit code.

エラー / 例外

Prior to version 1.0.0, if the SAPI is not "cli", this function emits an E_ERROR level error.

As of version 1.0.0, will throw a Win32ServiceException if SAPI is not "cli"

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | Throws a ValueError on invalid data in parameters, previously false was returned.
PECL win32service 1.0.0 | Throws a Win32ServiceException on error, previously a Win32 Error Code was returned.

参考

  • win32_start_service_ctrl_dispatcher() - スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
  • win32_set_service_status() - サービスの状態を更新する
  • win32_set_service_exit_mode() - Define or return the exit mode for the current running service


Define or return the exit mode for the current running service

  • ≪ win32_set_service_exit_code
  • win32_set_service_status ≫
  • PHP Manual
  • win32service 関数
  • Define or return the exit mode for the current running service

win32_set_service_exit_mode

(PECL win32service >=0.4.0)

win32_set_service_exit_mode — Define or return the exit mode for the current running service

説明

win32_set_service_exit_mode(bool $gracefulMode = true): bool

If gracefulMode parameter is provided, the exit mode is changed. When the exit mode is not gracefuly, the exit code used can be set with the win32_set_service_exit_code() function.

警告

This function work only in "cli" SAPI. On other SAPI this function is disabled.

パラメータ

gracefulMode

true for exit graceful. false for exit with error.

戻り値

Return the current or old exit mode.

エラー / 例外

Prior to version 1.0.0, if the SAPI is not "cli", this function emits an E_ERROR level error.

As of version 1.0.0, will throw a Win32ServiceException if SAPI is not "cli"

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | Throws a ValueError on invalid data in parameters, previously false was returned.
PECL win32service 1.0.0 | Throws a Win32ServiceException on error, previously a Win32 Error Code was returned.

参考

  • win32_start_service_ctrl_dispatcher() - スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
  • win32_set_service_status() - サービスの状態を更新する
  • win32_set_service_exit_code() - Define or return the exit code for the current running service


サービスの状態を更新する

  • ≪ win32_set_service_exit_mode
  • win32_start_service ≫
  • PHP Manual
  • win32service 関数
  • サービスの状態を更新する

win32_set_service_status

(PECL win32service >=0.1.0)

win32_set_service_status — サービスの状態を更新する

説明

win32_set_service_status(int $status, int $checkpoint = 0): void

SCM に、実行中のサービスの現在の状態を通知します。 この関数のコールは、現在実行中のサービスについてのみ有効です。

警告

バージョン 0.2.0 以降は、この関数は "cli" SAPI でのみ動作します。 他の SAPI では、この関数は無効になっています。

パラメータ

status

以下のステータスコードのうちのひとつ。 WIN32_SERVICE_RUNNING、 WIN32_SERVICE_STOPPED、 WIN32_SERVICE_STOP_PENDING、 WIN32_SERVICE_START_PENDING、 WIN32_SERVICE_CONTINUE_PENDING、 WIN32_SERVICE_PAUSE_PENDING、 WIN32_SERVICE_PAUSED。

checkpoint

start, stop, pause や continue の操作がとても時間がかかる場合に、 その状態を報告する目的で定期的にインクリメントされるチェックポイントの値。 たとえば、サービスが起動中の場合は、 初期化のステップがひとつ終了するたびに、 この値をインクリメントすべきです。

checkpoint の値は、 status が以下の場合のみ、正しい値です: WIN32_SERVICE_STOP_PENDING, WIN32_SERVICE_START_PENDING, WIN32_SERVICE_CONTINUE_PENDING, WIN32_SERVICE_PAUSE_PENDING.

戻り値

値を返しません。

バージョン 1.0.0 より前では、成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

バージョン 1.0.0 より前では、 SAPI が "cli" でない場合、 この関数は E_ERROR レベルのエラーを発生させていました。

バージョン 1.0.0 以降では、 SAPI が "cli" でない場合、 Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.2.0 | この関数は、"cli" SAPI でのみ動作するようになりました。

参考

  • win32_start_service_ctrl_dispatcher() - スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
  • win32_get_last_control_message() - サービスに送信された直近の制御メッセージを返す
  • win32_set_service_exit_mode() - Define or return the exit mode for the current running service
  • win32_set_service_exit_code() - Define or return the exit code for the current running service
  • Win32Service サービスステータス定数


サービスを開始する

  • ≪ win32_set_service_status
  • win32_start_service_ctrl_dispatcher ≫
  • PHP Manual
  • win32service 関数
  • サービスを開始する

win32_start_service

(PECL win32service >=0.1.0)

win32_start_service — サービスを開始する

説明

win32_start_service(string $servicename, string $machine = ?): void

指定したサービスの開始を試みます。 管理者権限、 またはサービスのACLで適切な権限が設定されたアカウントが必要です。

パラメータ

servicename

サービスの短い名前。

machine

オプションのマシン名。指定しなかった場合、ローカルマシンが使用されます。

戻り値

値を返しません。

バージョン 1.0.0 より前では、 成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

servicename が空の場合、 ValueError がスローされます。

エラー時には、Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.3.0 | ACLが別のアカウントに設定されていた場合、 この関数には管理者権限が不要になりました。

参考

  • win32_stop_service() - サービスを停止する
  • win32_pause_service() - サービスを中断する
  • win32_continue_service() - 中断したサービスを再開する
  • win32_send_custom_control() - Send a custom control to the service
  • Win32 エラーコード


スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする

  • ≪ win32_start_service
  • win32_stop_service ≫
  • PHP Manual
  • win32service 関数
  • スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする

win32_start_service_ctrl_dispatcher

(PECL win32service >=0.1.0)

win32_start_service_ctrl_dispatcher — スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする

説明

win32_start_service_ctrl_dispatcher(string $name, bool $gracefulMode = true): void

サービスコントロールマネージャ経由で起動させる際、サービスプロセスは 「チェックイン」を要求され、これによってサービスのモニタリングや 通信の機能を確立します。この関数は、サービスコントロールマネージャとの 低レベル通信を処理するスレッドを生成し、チェックインを実行します。

サービスが開始したら、サービスプロセスで行わなければならないことは次のふたつです。 まず最初は、サービスが実行中であることをサービスコントロールマネージャに通知することです。 これは、win32_set_service_status() に定数 WIN32_SERVICE_RUNNING を指定してコールすれば実現できます。 サービスが実際に動き出すまでに何らかの長い処理を要する場合は、定数 WIN32_SERVICE_START_PENDING を使うこともできます。 もうひとつは、常にサービスコントロールマネージャにチェックインし続け、 サービスをいつ終了させるべきかを確認することです。 これは、定期的に win32_get_last_control_message() をコールして戻り値を適切に処理することで実現できます。

警告

0.2.0 以降では、この関数は "cli" SAPI でのみ動作します。 他の SAPI では、この関数は無効になっています。

パラメータ

name

サービスの短い名前。win32_create_service() で登録されたもの。

gracefulMode

true の場合、graceful に終了します。 false の場合、エラーで終了します。 詳細は win32_set_service_exit_mode() を参照ください。

戻り値

値を返しません。

バージョン 1.0.0 より前では、成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

バージョン 1.0.0 より前では、 SAPI が "cli" でない場合、 この関数は E_ERROR レベルのエラーを発生させていました。

バージョン 1.0.0 以降では、 SAPI が "cli" でない場合、 Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.4.0 | gracefulMode パラメータが追加されました。
PECL win32service 0.2.0 | この関数は "cli" SAPI でのみ動作するようになりました。

例

例1 win32_start_service_ctrl_dispatcher() の例

サービスが SCM で実行されているかどうかを調べます。

<?php
if (!win32_start_service_ctrl_dispatcher('dummyphp')) {
die("I'm probably not running under the service control manager");
}

win32_set_service_status(WIN32_SERVICE_START_PENDING);

// このサービスを処理するための、何らかの長い処理をします

win32_set_service_status(WIN32_SERVICE_RUNNING);

while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) {
# ここでなんらかの処理をします。1 回のループに 30 秒以上かからない
# ように心がけてください。
}
?>

参考

  • win32_set_service_status() - サービスの状態を更新する
  • win32_get_last_control_message() - サービスに送信された直近の制御メッセージを返す
  • win32_set_service_exit_mode() - Define or return the exit mode for the current running service
  • win32_set_service_exit_code() - Define or return the exit code for the current running service
  • Win32 エラーコード


サービスを停止する

  • ≪ win32_start_service_ctrl_dispatcher
  • XML 操作 ≫
  • PHP Manual
  • win32service 関数
  • サービスを停止する

win32_stop_service

(PECL win32service >=0.1.0)

win32_stop_service — サービスを停止する

説明

win32_stop_service(string $servicename, string $machine = ?): void

サービスを停止します。管理者権限、 またはサービスのACLで適切な権限が設定されたアカウントが必要です。

パラメータ

servicename

サービスの短い名前。

machine

オプションのマシン名。指定しなかった場合、ローカルマシンが使用されます。

戻り値

値を返しません。

バージョン 1.0.0 より前では、 成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

servicename 引数が空の場合、 ValueError がスローされます。

エラー時には、Win32ServiceException がスローされます。

変更履歴

バージョン | 説明
PECL win32service 1.0.0 | 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 | エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 | 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.3.0 | ACLが別のアカウントに設定されていた場合、 この関数には管理者権限が不要になりました。

参考

  • win32_start_service() - サービスを開始する
  • win32_pause_service() - サービスを中断する
  • win32_continue_service() - 中断したサービスを再開する
  • win32_send_custom_control() - Send a custom control to the service
  • Win32 エラーコード


XML 操作

  • DOM — Document Object Model
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • DOMAttr — DOMAttr クラス
    • DOMCdataSection — DOMCdataSection クラス
    • DOMCharacterData — DOMCharacterData クラス
    • DOMChildNode — DOMChildNode インターフェイス
    • DOMComment — DOMComment クラス
    • DOMDocument — DOMDocument クラス
    • DOMDocumentFragment — DOMDocumentFragment クラス
    • DOMDocumentType — DOMDocumentType クラス
    • DOMElement — DOMElement クラス
    • DOMEntity — DOMEntity クラス
    • DOMEntityReference — DOMEntityReference クラス
    • DOMException — DOMException クラス
    • DOMImplementation — DOMImplementation クラス
    • DOMNamedNodeMap — DOMNamedNodeMap クラス
    • DOMNameSpaceNode — DOMNameSpaceNode クラス
    • DOMNode — DOMNode クラス
    • DOMNodeList — DOMNodeList クラス
    • DOMNotation — DOMNotation クラス
    • DOMParentNode — DOMParentNode インターフェイス
    • DOMProcessingInstruction — DOMProcessingInstruction クラス
    • DOMText — DOMText クラス
    • DOMXPath — DOMXPath クラス
    • DOM 関数
  • libxml
    • はじめに
    • インストール/設定
    • 定義済み定数
    • LibXMLError — LibXMLError クラス
    • libxml 関数
  • SimpleXML
    • はじめに
    • インストール/設定
    • 例
    • SimpleXMLElement — SimpleXMLElement クラス
    • SimpleXMLIterator — SimpleXMLIterator クラス
    • SimpleXML 関数
  • WDDX
    • はじめに
    • インストール/設定
    • 例
    • WDDX 関数
  • XMLDiff — XML diff and merge
    • はじめに
    • インストール/設定
    • XMLDiff\Base — The XMLDiff\Base class
    • XMLDiff\DOM — The XMLDiff\DOM class
    • XMLDiff\Memory — The XMLDiff\Memory class
    • XMLDiff\File — The XMLDiff\File class
  • XML パーサ
    • はじめに
    • インストール/設定
    • 定義済み定数
    • イベントハンドラ
    • 大文字変換(Case Folding)
    • エラーコード
    • 文字エンコーディング
    • 例
    • XML パーサ 関数
    • XMLParser — XMLParser クラス
  • XMLReader
    • はじめに
    • インストール/設定
    • XMLReader — XMLReader クラス
  • XMLWriter
    • はじめに
    • インストール/設定
    • 例
    • XMLWriter — XMLWriter クラス
  • XSL
    • はじめに
    • インストール/設定
    • 定義済み定数
    • 例
    • XSLTProcessor — XSLTProcessor クラス


Document Object Model

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
  • DOMAttr — DOMAttr クラス
    • DOMAttr::__construct — 新しい DOMAttr オブジェクトを作成する
    • DOMAttr::isId — 属性が定義済みの ID かどうかを調べる
  • DOMCdataSection — DOMCdataSection クラス
    • DOMCdataSection::__construct — 新しい DOMCdataSection オブジェクトを作成する
  • DOMCharacterData — DOMCharacterData クラス
    • DOMCharacterData::after — 文字データの後ろにノードを追加する
    • DOMCharacterData::appendData — ノードの文字データの最後に文字列を追加する
    • DOMCharacterData::before — ノードの前にノードを追加する
    • DOMCharacterData::deleteData — 指定した範囲の文字列をノードから削除する
    • DOMCharacterData::insertData — 指定した 16 ビット単位のオフセットに、文字列を挿入する
    • DOMCharacterData::remove — 文字データを削除する
    • DOMCharacterData::replaceData — DOMCharacterData ノードの文字列の一部を置換する
    • DOMCharacterData::replaceWith — 文字データを新しいノードで置き換える
    • DOMCharacterData::substringData — ノードから指定した範囲のデータを抽出する
  • DOMChildNode — DOMChildNode インターフェイス
    • DOMChildNode::after — ノードの後ろにノードを追加する
    • DOMChildNode::before — ノードの前にノードを追加する
    • DOMChildNode::remove — ノードを削除する
    • DOMChildNode::replaceWith — ノードを新しいノードで置き換える
  • DOMComment — DOMComment クラス
    • DOMComment::__construct — 新しい DOMComment オブジェクトを作成する
  • DOMDocument — DOMDocument クラス
    • DOMDocument::adoptNode — ノードを別のドキュメントに移す
    • DOMDocument::append — 最後の子ノードの後ろにノードを追加する
    • DOMDocument::__construct — 新しい DOMDocument オブジェクトを作成する
    • DOMDocument::createAttribute — 新しい属性を作成する
    • DOMDocument::createAttributeNS — 関連付けられた名前空間に新しい属性を作成する
    • DOMDocument::createCDATASection — 新しい cdata ノードを作成する
    • DOMDocument::createComment — 新しい comment ノードを作成する
    • DOMDocument::createDocumentFragment — 新しい文書片を作成する
    • DOMDocument::createElement — 新しい要素ノードを作成する
    • DOMDocument::createElementNS — 関連付けられた名前空間に新しい要素を作成する
    • DOMDocument::createEntityReference — 新しいエンティティ参照ノードを作成する
    • DOMDocument::createProcessingInstruction — 新しい PI ノードを作成する
    • DOMDocument::createTextNode — 新しいテキストノードを作成する
    • DOMDocument::getElementById — id に対応する要素を検索する
    • DOMDocument::getElementsByTagName — 指定したローカルタグ名に対応するすべての要素を検索する
    • DOMDocument::getElementsByTagNameNS — 指定した名前空間で、タグ名に対応するすべての要素を検索する
    • DOMDocument::importNode — 現在のドキュメントにノードをインポートする
    • DOMDocument::load — ファイルから XML を読み込む
    • DOMDocument::loadHTML — 文字列から HTML を読み込む
    • DOMDocument::loadHTMLFile — ファイルから HTML を読み込む
    • DOMDocument::loadXML — 文字列から XML を読み込む
    • DOMDocument::normalizeDocument — ドキュメントを正規化する
    • DOMDocument::prepend — 最初の子ノードの前にノードを追加する
    • DOMDocument::registerNodeClass — 基底ノード型を作成する際に使用する拡張クラスを登録する
    • DOMDocument::relaxNGValidate — ドキュメントを relaxNG で検証する
    • DOMDocument::relaxNGValidateSource — ドキュメントを relaxNG で検証する
    • DOMDocument::replaceChildren — ドキュメントの子を置換する
    • DOMDocument::save — 内部の XML ツリーをファイルに出力する
    • DOMDocument::saveHTML — 内部のドキュメントを HTML 形式の文字列として出力する
    • DOMDocument::saveHTMLFile — 内部のドキュメントを HTML 形式でファイルに出力する
    • DOMDocument::saveXML — 内部の XML ツリーを文字列として出力する
    • DOMDocument::schemaValidate — スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
    • DOMDocument::schemaValidateSource — スキーマに基づいてドキュメントを検証する
    • DOMDocument::validate — DTD に基づいてドキュメントを検証する
    • DOMDocument::xinclude — DOMDocument オブジェクト内の XIncludes を置換する
  • DOMDocumentFragment — DOMDocumentFragment クラス
    • DOMDocumentFragment::append — 最後の子ノードの後ろにノードを追加する
    • DOMDocumentFragment::appendXML — 生の XML データを追加する
    • DOMDocumentFragment::__construct — DOMDocumentFragment オブジェクトを構築する
    • DOMDocumentFragment::prepend — 最初の子ノードの前にノードを追加する
    • DOMDocumentFragment::replaceChildren — 文書片の子を置換する
  • DOMDocumentType — DOMDocumentType クラス
  • DOMElement — DOMElement クラス
    • DOMElement::after — 要素の後ろにノードを追加する
    • DOMElement::append — 最後のノードの後ろにノードを追加する
    • DOMElement::before — 要素の前にノードを追加する
    • DOMElement::__construct — 新しい DOMElement オブジェクトを作成する
    • DOMElement::getAttribute — 属性の値を返す
    • DOMElement::getAttributeNames — 属性の名前を取得する
    • DOMElement::getAttributeNode — 属性ノードを返す
    • DOMElement::getAttributeNodeNS — 属性ノードを返す
    • DOMElement::getAttributeNS — 属性の値を返す
    • DOMElement::getElementsByTagName — タグ名から要素を取得する
    • DOMElement::getElementsByTagNameNS — 名前空間 URI とローカル名から要素を取得する
    • DOMElement::hasAttribute — 属性が存在するかどうかを調べる
    • DOMElement::hasAttributeNS — 属性が存在するかどうかを調べる
    • DOMElement::insertAdjacentElement — 隣接する要素を挿入する
    • DOMElement::insertAdjacentText — 隣接するテキストを挿入する
    • DOMElement::prepend — 最初の子ノードの前にノードを追加する
    • DOMElement::remove — 要素を削除する
    • DOMElement::removeAttribute — 属性を削除する
    • DOMElement::removeAttributeNode — 属性を削除する
    • DOMElement::removeAttributeNS — 属性を削除する
    • DOMElement::replaceChildren — 要素中の子を置換する
    • DOMElement::replaceWith — 要素を新しいノードで置換する
    • DOMElement::setAttribute — 属性を新しく追加する、または変更する
    • DOMElement::setAttributeNode — 新しい属性ノードを要素に追加する
    • DOMElement::setAttributeNodeNS — 新しい属性ノードを要素に追加する
    • DOMElement::setAttributeNS — 新しい属性を追加する
    • DOMElement::setIdAttribute — ID 型の属性を名前で宣言する
    • DOMElement::setIdAttributeNode — ID 型の属性をノードで宣言する
    • DOMElement::setIdAttributeNS — ID 型の属性をローカル名および名前空間 URI で宣言する
    • DOMElement::toggleAttribute — 属性の値を切り替える
  • DOMEntity — DOMEntity クラス
  • DOMEntityReference — DOMEntityReference クラス
    • DOMEntityReference::__construct — 新しい DOMEntityReference オブジェクトを作成する
  • DOMException — DOMException クラス
  • DOMImplementation — DOMImplementation クラス
    • DOMImplementation::__construct — 新しい DOMImplementation オブジェクトを作成する
    • DOMImplementation::createDocument — 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する
    • DOMImplementation::createDocumentType — 空の DOMDocumentType オブジェクトを作成する
    • DOMImplementation::hasFeature — DOM 実装が、指定した機能を実装しているかどうかを調べる
  • DOMNamedNodeMap — DOMNamedNodeMap クラス
    • DOMNamedNodeMap::count — マップにあるノードの数を取得する
    • DOMNamedNodeMap::getIterator — 外部のイテレータを取得する
    • DOMNamedNodeMap::getNamedItem — 名前で指定されたノードを取得する
    • DOMNamedNodeMap::getNamedItemNS — ローカル名および名前空間 URI で指定したノードを取得する
    • DOMNamedNodeMap::item — インデックスで指定したノードを取得する
  • DOMNameSpaceNode — DOMNameSpaceNode クラス
  • DOMNode — DOMNode クラス
    • DOMNode::appendChild — 子要素群の最後に新しい子要素を追加する
    • DOMNode::C14N — ノードを文字列に正規化する
    • DOMNode::C14NFile — ノードをファイルに正規化する
    • DOMNode::cloneNode — ノードを複製する
    • DOMNode::contains — ノードが別のノードを含んでいるかを調べる
    • DOMNode::getLineNo — ノードが存在する行の番号を取得します。
    • DOMNode::getNodePath — ノードの XPath を取得する
    • DOMNode::getRootNode — ルート(根)ノードを取得する
    • DOMNode::hasAttributes — ノードが属性を保持しているかどうかを調べる
    • DOMNode::hasChildNodes — ノードが子を保持しているかどうかを調べる
    • DOMNode::insertBefore — 参照しているノードの前に新しい子を追加する
    • DOMNode::isDefaultNamespace — 指定した namespaceURI がデフォルトの名前空間かどうかを調べる
    • DOMNode::isEqualNode — ノードが等しいかを調べる
    • DOMNode::isSameNode — 2 つのノードが等しいかどうかを調べる
    • DOMNode::isSupported — 指定したバージョンで機能がサポートされているかどうかを調べる
    • DOMNode::lookupNamespaceURI — プレフィックスに基づいて、ノードの名前空間 URI を取得する
    • DOMNode::lookupPrefix — 名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する
    • DOMNode::normalize — ノードを正規化する
    • DOMNode::removeChild — 子要素群から子要素を削除する
    • DOMNode::replaceChild — 子を置き換える
  • DOMNodeList — DOMNodeList クラス
    • DOMNodeList::count — リストにあるノードの数を取得する
    • DOMNodeList::getIterator — 外部のイテレータを取得する
    • DOMNodelist::item — インデックスで指定したノードを取得する
  • DOMNotation — DOMNotation クラス
  • DOMParentNode — DOMParentNode インターフェイス
    • DOMParentNode::append — 最後の子ノードの後ろにノードを追加する
    • DOMParentNode::prepend — 最初の子ノードの前にノードを追加する
    • DOMParentNode::replaceChildren — ノード中の子を置換する
  • DOMProcessingInstruction — DOMProcessingInstruction クラス
    • DOMProcessingInstruction::__construct — 新しい DOMProcessingInstruction オブジェクトを作成する
  • DOMText — DOMText クラス
    • DOMText::__construct — 新しい DOMText オブジェクトを作成する
    • DOMText::isElementContentWhitespace — このテキストノードが、要素の内容にホワイトスペースが含まれているかを返す
    • DOMText::isWhitespaceInElementContent — このテキストノードが空白を含むかどうかを示す
    • DOMText::splitText — 指定したオフセットでノードを 2 つに分割する
  • DOMXPath — DOMXPath クラス
    • DOMXPath::__construct — 新しい DOMXPath オブジェクトを作成する
    • DOMXPath::evaluate — 与えられた XPath 式を評価し、可能であれば結果を返す
    • DOMXPath::query — 与えられた XPath 式を評価する
    • DOMXPath::registerNamespace — DOMXPath オブジェクトの名前空間を登録する
    • DOMXPath::registerPhpFunctions — PHP の関数を XPath 関数として登録する
  • DOM 関数
    • dom_import_simplexml — SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する


はじめに

DOM 拡張モジュールを使用すると、DOM API を使用した XML や HTML ドキュメントの操作を PHP で行えます。

注意:

DOM拡張モジュール は UTF-8 エンコーディングを使います。他のエンコーディングを扱う場合は、mb_convert_encoding(), UConverter::transcode(), iconv() を使ってください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • DOM
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-dom


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XML 定数
定数 | 値 | 説明
XML_ELEMENT_NODE (int) | 1 | ノードは DOMElement です。
XML_ATTRIBUTE_NODE (int) | 2 | ノードは DOMAttr です。
XML_TEXT_NODE (int) | 3 | ノードは DOMText です。
XML_CDATA_SECTION_NODE (int) | 4 | ノードは DOMCharacterData です。
XML_ENTITY_REF_NODE (int) | 5 | ノードは DOMEntityReference です。
XML_ENTITY_NODE (int) | 6 | ノードは DOMEntity です。
XML_PI_NODE (int) | 7 | ノードは DOMProcessingInstruction です。
XML_COMMENT_NODE (int) | 8 | ノードは DOMComment です。
XML_DOCUMENT_NODE (int) | 9 | ノードは DOMDocument です。
XML_DOCUMENT_TYPE_NODE (int) | 10 | ノードは DOMDocumentType です。
XML_DOCUMENT_FRAG_NODE (int) | 11 | ノードは DOMDocumentFragment です。
XML_NOTATION_NODE (int) | 12 | ノードは DOMNotation です。
XML_HTML_DOCUMENT_NODE (int) | 13 |
XML_DTD_NODE (int) | 14 |
XML_ELEMENT_DECL_NODE (int) | 15 |
XML_ATTRIBUTE_DECL_NODE (int) | 16 |
XML_ENTITY_DECL_NODE (int) | 17 |
XML_NAMESPACE_DECL_NODE (int) | 18 |
XML_ATTRIBUTE_CDATA (int) | 1 |
XML_ATTRIBUTE_ID (int) | 2 |
XML_ATTRIBUTE_IDREF (int) | 3 |
XML_ATTRIBUTE_IDREFS (int) | 4 |
XML_ATTRIBUTE_ENTITY (int) | 5 |
XML_ATTRIBUTE_NMTOKEN (int) | 7 |
XML_ATTRIBUTE_NMTOKENS (int) | 8 |
XML_ATTRIBUTE_ENUMERATION (int) | 9 |
XML_ATTRIBUTE_NOTATION (int) | 10 |
XML_LOCAL_NAMESPACE (int) |  | 名前空間を宣言したノード
DOMException 定数
定数 | 値 | 説明
DOM_PHP_ERR (int) | 0 | DOM の仕様にないエラーコードです。PHP のエラーを意味します。
DOM_INDEX_SIZE_ERR (int) | 1 | インデックスあるいはサイズが負です。または上限を超えています。
DOMSTRING_SIZE_ERR (int) | 2 | 指定したテキストは DOMString 内に収まりません。
DOM_HIERARCHY_REQUEST_ERR (int) | 3 | そのノードが所属できない場所に挿入されました。
DOM_WRONG_DOCUMENT_ERR (int) | 4 | ノードが、もともと作成されたのと別のドキュメントで使用されました。
DOM_INVALID_CHARACTER_ERR (int) | 5 | 名前などで、不正な文字が指定されました。
DOM_NO_DATA_ALLOWED_ERR (int) | 6 | データをサポートしていないノードでデータが指定されました。
DOM_NO_MODIFICATION_ALLOWED_ERR (int) | 7 | 変更が許可されていないオブジェクトを変更しようとしました。
DOM_NOT_FOUND_ERR (int) | 8 | 存在しないノードを参照しようとしました。
DOM_NOT_SUPPORTED_ERR (int) | 9 | 指定した型のオブジェクトや操作は、この実装ではサポートしていません。
DOM_INUSE_ATTRIBUTE_ERR (int) | 10 | 別の場所で使用中の属性を追加しようとしました。
DOM_INVALID_STATE_ERR (int) | 11 | 現在使用できない、あるいは使用できなくなったオブジェクトを 使用しようとしました。
DOM_SYNTAX_ERR (int) | 12 | 不正な文字列が指定されました。
DOM_INVALID_MODIFICATION_ERR (int) | 13 | 基底オブジェクトの型を変更しようとしました。
DOM_NAMESPACE_ERR (int) | 14 | 名前空間に存在しないオブジェクトを作成または変更しようとしました。
DOM_INVALID_ACCESS_ERR (int) | 15 | パラメータや操作は基底オブジェクトではサポートされていません。
DOM_VALIDATION_ERR (int) | 16 | insertBefore や removeChild のようなメソッドのコールによってノードの 「部分的な妥当性」が満たされなくなった際にこの例外が発生し、操作は 行われません。


例

このリファレンスの多くの例で、XMLファイルが必要です。 私たちは、次のような形式の book.xml を使用します。

例1 book.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<book id="listing">
 <title>My lists</title>
 <chapter id="books">
  <title>My books</title>
  <para>
   <informaltable>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>Title</entry>
       <entry>Author</entry>
       <entry>Language</entry>
       <entry>ISBN</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>The Grapes of Wrath</entry>
       <entry>John Steinbeck</entry>
       <entry>en</entry>
       <entry>0140186409</entry>
      </row>
      <row>
       <entry>The Pearl</entry>
       <entry>John Steinbeck</entry>
       <entry>en</entry>
       <entry>014017737X</entry>
      </row>
      <row>
       <entry>Samarcande</entry>
       <entry>Amine Maalouf</entry>
       <entry>fr</entry>
       <entry>2253051209</entry>
      </row>
      <!-- TODO: I have a lot of remaining books to add.. -->
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </chapter>
</book>


DOMAttr クラス

(PHP 5, PHP 7, PHP 8)

はじめに

DOMNode を継承します。DOMAttr は、DOMElement オブジェクトの属性を表します。

クラス概要

class DOMAttr extends DOMNode {
/* プロパティ */
public readonly string $name;
public readonly bool $specified = true;
public string $value;
public readonly ?DOMElement $ownerElement;
public readonly mixed $schemaTypeInfo = null;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $name, string $value = "")
public isId(): bool
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

name

属性の名前

ownerElement

属性を保持する要素。存在しない場合は null になります。

schemaTypeInfo

未実装です。常に null を返します。

specified

未実装です。常に true を返します。

value

属性の値

注意:

値を設定する際には、XML のエンティティが展開されるので注意してください。 つまり、& 文字は特別な意味を持ちます。 value に & が含まれている場合、それを直接設定すると処理が失敗します。 エンティティの展開を避けるためには、 DOMElement::setAttribute() を代わりに使います。

参考

  • » W3C specification of Attr

目次

  • DOMAttr::__construct — 新しい DOMAttr オブジェクトを作成する
  • DOMAttr::isId — 属性が定義済みの ID かどうかを調べる


新しい DOMAttr オブジェクトを作成する

  • ≪ DOMAttr
  • DOMAttr::isId ≫
  • PHP Manual
  • DOMAttr
  • 新しい DOMAttr オブジェクトを作成する

DOMAttr::__construct

(PHP 5, PHP 7, PHP 8)

DOMAttr::__construct — 新しい DOMAttr オブジェクトを作成する

説明

public DOMAttr::__construct(string $name, string $value = "")

新しい DOMAttr オブジェクトを作成します。 このオブジェクトは読み込み専用です。このオブジェクトはドキュメントに 追加することができますが、さらに追加のノードを付け加えるためには ノードをドキュメントに関連付ける必要があります。書き込み可能な ノードを作成するには、 DOMDocument::createAttribute を使用します。

パラメータ

name

属性のタグ名。

value

属性の値。

例

例1 新しい DOMAttr オブジェクトを作成する

<?php

$dom = new DOMDocument('1.0', 'iso-8859-1');
$element = $dom->appendChild(new DOMElement('root'));
$attr = $element->setAttributeNode(new DOMAttr('attr', 'attrvalue'));
echo $dom->saveXML();

?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="iso-8859-1"?>
<root attr="attrvalue" />

参考

  • DOMDocument::createAttribute() - 新しい属性を作成する


属性が定義済みの ID かどうかを調べる

  • ≪ DOMAttr::__construct
  • DOMCdataSection ≫
  • PHP Manual
  • DOMAttr
  • 属性が定義済みの ID かどうかを調べる

DOMAttr::isId

(PHP 5, PHP 7, PHP 8)

DOMAttr::isId — 属性が定義済みの ID かどうかを調べる

説明

public DOMAttr::isId(): bool

この関数は、属性が定義済みの ID かどうかを調べます。

DOM 標準規格によると、DTD では ID 型の属性 ID が定義されていなければ なりません。この関数を使用する前には、 DOMDocument::validate あるいは DOMDocument::$validateOnParse を使用して ドキュメントを検証する必要があります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 DOMAttr::isId() の例

<?php

$doc = new DomDocument;

// id を参照する前に、ドキュメントを検証しなければなりません
$doc->validateOnParse = true;
$doc->Load('book.xml');

// chapter 要素から、id という名前の属性を取得します
$attr = $doc->getElementsByTagName('chapter')->item(0)->getAttributeNode('id');

var_dump($attr->isId()); // bool(true)

?>


DOMCdataSection クラス

(PHP 5, PHP 7, PHP 8)

はじめに

DOMCdataSection は DOMText を継承したクラスで、 CData のテキスト表現に使います。

クラス概要

class DOMCdataSection extends DOMText {
/* 継承したプロパティ */
public readonly string $wholeText;
public string $data;
public readonly int $length;
public readonly ?DOMElement $previousElementSibling;
public readonly ?DOMElement $nextElementSibling;
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $data)
/* 継承したメソッド */
public DOMText::isElementContentWhitespace(): bool
public DOMText::isWhitespaceInElementContent(): bool
public DOMText::splitText(int $offset): DOMText|false
public DOMCharacterData::after(DOMNode|string ...$nodes): void
public DOMCharacterData::appendData(string $data): true
public DOMCharacterData::before(DOMNode|string ...$nodes): void
public DOMCharacterData::deleteData(int $offset, int $count): bool
public DOMCharacterData::insertData(int $offset, string $data): bool
public DOMCharacterData::remove(): void
public DOMCharacterData::replaceData(int $offset, int $count, string $data): bool
public DOMCharacterData::replaceWith(DOMNode|string ...$nodes): void
public DOMCharacterData::substringData(int $offset, int $count): string|false
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

目次

  • DOMCdataSection::__construct — 新しい DOMCdataSection オブジェクトを作成する


新しい DOMCdataSection オブジェクトを作成する

  • ≪ DOMCdataSection
  • DOMCharacterData ≫
  • PHP Manual
  • DOMCdataSection
  • 新しい DOMCdataSection オブジェクトを作成する

DOMCdataSection::__construct

(PHP 5, PHP 7, PHP 8)

DOMCdataSection::__construct — 新しい DOMCdataSection オブジェクトを作成する

説明

public DOMCdataSection::__construct(string $data)

新しい CDATA ノードを作成します。これは、DOMText クラスと同じように動作します。

パラメータ

data

CDATA ノードの値。省略した場合は、空の CDATA ノードを作成します。

例

例1 新しい DOMCdataSection オブジェクトの作成

<?php

$dom = new DOMDocument('1.0', 'utf-8');
$element = $dom->appendChild(new DOMElement('root'));
$text = $element->appendChild(new DOMCdataSection('root value'));
echo $dom->saveXML();

?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="utf-8"?>
<root><![CDATA[root value]]></root>

参考

  • DOMText::__construct() - 新しい DOMText オブジェクトを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


DOMCharacterData クラス

(PHP 5, PHP 7, PHP 8)

はじめに

文字データノードを表します。このクラスに直接対応するノードはなく、 他のノードがこれを継承します。

クラス概要

class DOMCharacterData extends DOMNode implements DOMChildNode {
/* プロパティ */
public string $data;
public readonly int $length;
public readonly ?DOMElement $previousElementSibling;
public readonly ?DOMElement $nextElementSibling;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public after(DOMNode|string ...$nodes): void
public appendData(string $data): true
public before(DOMNode|string ...$nodes): void
public deleteData(int $offset, int $count): bool
public insertData(int $offset, string $data): bool
public remove(): void
public replaceData(int $offset, int $count, string $data): bool
public replaceWith(DOMNode|string ...$nodes): void
public substringData(int $offset, int $count): string|false
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

data

ノードの内容。

length

内容の長さ。

nextElementSibling

次の兄弟要素。存在しない場合は null になります。

previousElementSibling

前の兄弟要素。存在しない場合は null になります。

変更履歴

バージョン | 説明
8.0.0 | プロパティ nextElementSibling と previousElementSibling が追加されました。
8.0.0 | DOMCharacterData は、 DOMChildNode を実装しました。

参考

  • » W3C specification of CharacterData

目次

  • DOMCharacterData::after — 文字データの後ろにノードを追加する
  • DOMCharacterData::appendData — ノードの文字データの最後に文字列を追加する
  • DOMCharacterData::before — ノードの前にノードを追加する
  • DOMCharacterData::deleteData — 指定した範囲の文字列をノードから削除する
  • DOMCharacterData::insertData — 指定した 16 ビット単位のオフセットに、文字列を挿入する
  • DOMCharacterData::remove — 文字データを削除する
  • DOMCharacterData::replaceData — DOMCharacterData ノードの文字列の一部を置換する
  • DOMCharacterData::replaceWith — 文字データを新しいノードで置き換える
  • DOMCharacterData::substringData — ノードから指定した範囲のデータを抽出する


文字データの後ろにノードを追加する

  • ≪ DOMCharacterData
  • DOMCharacterData::appendData ≫
  • PHP Manual
  • DOMCharacterData
  • 文字データの後ろにノードを追加する

DOMCharacterData::after

(PHP 8)

DOMCharacterData::after — 文字データの後ろにノードを追加する

説明

public DOMCharacterData::after(DOMNode|string ...$nodes): void

渡された nodes をノードの後ろに追加します。

パラメータ

nodes

ノードの後ろに追加されるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMCharacterData::after() の例

文字データの後ろにノードを追加します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><![CDATA[hello]]></container>");
$cdata = $doc->documentElement->firstChild;

$cdata->after("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container><![CDATA[hello]]>beautiful<world/></container>

参考

  • DOMChildNode::after() - ノードの後ろにノードを追加する
  • DOMCharacterData::before() - ノードの前にノードを追加する


ノードの文字データの最後に文字列を追加する

  • ≪ DOMCharacterData::after
  • DOMCharacterData::before ≫
  • PHP Manual
  • DOMCharacterData
  • ノードの文字データの最後に文字列を追加する

DOMCharacterData::appendData

(PHP 5, PHP 7, PHP 8)

DOMCharacterData::appendData — ノードの文字データの最後に文字列を追加する

説明

public DOMCharacterData::appendData(string $data): true

ノードの文字データの最後に文字列 data を追加します。

パラメータ

data

追加する文字列。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.3.0 | この関数の仮の戻り値の型が、true になりました。

参考

  • DOMCharacterData::deleteData() - 指定した範囲の文字列をノードから削除する
  • DOMCharacterData::insertData() - 指定した 16 ビット単位のオフセットに、文字列を挿入する
  • DOMCharacterData::replaceData() - DOMCharacterData ノードの文字列の一部を置換する
  • DOMCharacterData::substringData() - ノードから指定した範囲のデータを抽出する


ノードの前にノードを追加する

  • ≪ DOMCharacterData::appendData
  • DOMCharacterData::deleteData ≫
  • PHP Manual
  • DOMCharacterData
  • ノードの前にノードを追加する

DOMCharacterData::before

(PHP 8)

DOMCharacterData::before — ノードの前にノードを追加する

説明

public DOMCharacterData::before(DOMNode|string ...$nodes): void

渡された nodes をノードの前に追加します。

パラメータ

nodes

ノードの前に追加されるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMCharacterData::before() の例

文字データの前にノードを追加します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><![CDATA[world]]></container>");
$cdata = $doc->documentElement->firstChild;

$cdata->before("hello", $doc->createElement("beautiful"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container>hello<beautiful/><![CDATA[world]]></container>

参考

  • DOMChildNode::before() - ノードの前にノードを追加する
  • DOMCharacterData::after() - 文字データの後ろにノードを追加する


指定した範囲の文字列をノードから削除する

  • ≪ DOMCharacterData::before
  • DOMCharacterData::insertData ≫
  • PHP Manual
  • DOMCharacterData
  • 指定した範囲の文字列をノードから削除する

DOMCharacterData::deleteData

(PHP 5, PHP 7, PHP 8)

DOMCharacterData::deleteData — 指定した範囲の文字列をノードから削除する

説明

public DOMCharacterData::deleteData(int $offset, int $count): bool

offset で指定した位置から count 文字ぶんの文字を削除します。

パラメータ

offset

削除開始位置のオフセット。

count

削除する文字の数。 offset と count の和が文字列の長さをこえている場合、データ末尾までのすべての データが削除されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

DOM_INDEX_SIZE_ERR

offset が負、あるいは 16 ビット単位の データ長より大きい場合、または count が 負の場合に発生します。

参考

  • DOMCharacterData::appendData() - ノードの文字データの最後に文字列を追加する
  • DOMCharacterData::insertData() - 指定した 16 ビット単位のオフセットに、文字列を挿入する
  • DOMCharacterData::replaceData() - DOMCharacterData ノードの文字列の一部を置換する
  • DOMCharacterData::substringData() - ノードから指定した範囲のデータを抽出する


指定した 16 ビット単位のオフセットに、文字列を挿入する

  • ≪ DOMCharacterData::deleteData
  • DOMCharacterData::remove ≫
  • PHP Manual
  • DOMCharacterData
  • 指定した 16 ビット単位のオフセットに、文字列を挿入する

DOMCharacterData::insertData

(PHP 5, PHP 7, PHP 8)

DOMCharacterData::insertData — 指定した 16 ビット単位のオフセットに、文字列を挿入する

説明

public DOMCharacterData::insertData(int $offset, string $data): bool

offset の位置に、文字列 data を挿入します。

パラメータ

offset

挿入する場所の文字オフセット。

data

挿入する文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

DOM_INDEX_SIZE_ERR

offset が負であるか、あるいは 16 ビット単位の データ長より大きい場合に発生します。

参考

  • DOMCharacterData::appendData() - ノードの文字データの最後に文字列を追加する
  • DOMCharacterData::deleteData() - 指定した範囲の文字列をノードから削除する
  • DOMCharacterData::replaceData() - DOMCharacterData ノードの文字列の一部を置換する
  • DOMCharacterData::substringData() - ノードから指定した範囲のデータを抽出する


文字データを削除する

  • ≪ DOMCharacterData::insertData
  • DOMCharacterData::replaceData ≫
  • PHP Manual
  • DOMCharacterData
  • 文字データを削除する

DOMCharacterData::remove

(PHP 8)

DOMCharacterData::remove — 文字データを削除する

説明

public DOMCharacterData::remove(): void

文字データを削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 DOMCharacterData::remove() の例

文字データを削除します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><![CDATA[hello]]><world/></container>");
$cdata = $doc->documentElement->firstChild;

$cdata->remove();

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container><world/></container>

参考

  • DOMChildNode::remove() - ノードを削除する
  • DOMCharacterData::after() - 文字データの後ろにノードを追加する
  • DOMCharacterData::before() - ノードの前にノードを追加する
  • DOMCharacterData::replaceWith() - 文字データを新しいノードで置き換える
  • DOMNode::removeChild() - 子要素群から子要素を削除する


DOMCharacterData ノードの文字列の一部を置換する

  • ≪ DOMCharacterData::remove
  • DOMCharacterData::replaceWith ≫
  • PHP Manual
  • DOMCharacterData
  • DOMCharacterData ノードの文字列の一部を置換する

DOMCharacterData::replaceData

(PHP 5, PHP 7, PHP 8)

DOMCharacterData::replaceData — DOMCharacterData ノードの文字列の一部を置換する

説明

public DOMCharacterData::replaceData(int $offset, int $count, string $data): bool

位置 offset から count 文字ぶんのデータを、data に置換します。

パラメータ

offset

置換開始位置のオフセット。

count

置換する文字の数。 offset と count の和が文字列の長さをこえている場合、データ末尾までのすべての データが置換されます。

data

置換する文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

DOM_INDEX_SIZE_ERR

offset が負、あるいは 16 ビット単位の データ長より大きい場合、または count が 負の場合に発生します。

参考

  • DOMCharacterData::appendData() - ノードの文字データの最後に文字列を追加する
  • DOMCharacterData::deleteData() - 指定した範囲の文字列をノードから削除する
  • DOMCharacterData::insertData() - 指定した 16 ビット単位のオフセットに、文字列を挿入する
  • DOMCharacterData::substringData() - ノードから指定した範囲のデータを抽出する


文字データを新しいノードで置き換える

  • ≪ DOMCharacterData::replaceData
  • DOMCharacterData::substringData ≫
  • PHP Manual
  • DOMCharacterData
  • 文字データを新しいノードで置き換える

DOMCharacterData::replaceWith

(PHP 8)

DOMCharacterData::replaceWith — 文字データを新しいノードで置き換える

説明

public DOMCharacterData::replaceWith(DOMNode|string ...$nodes): void

文字データを新しい nodes で置き換えます。

パラメータ

nodes

置き換えるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMCharacterData::replaceWith() の例

文字データを新しいノードで置き換えます。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><![CDATA[hello]]></container>");
$cdata = $doc->documentElement->firstChild;

$cdata->replaceWith("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container>beautiful<world/></container>

参考

  • DOMChildNode::replaceWith() - ノードを新しいノードで置き換える
  • DOMCharacterData::after() - 文字データの後ろにノードを追加する
  • DOMCharacterData::before() - ノードの前にノードを追加する
  • DOMCharacterData::remove() - 文字データを削除する


ノードから指定した範囲のデータを抽出する

  • ≪ DOMCharacterData::replaceWith
  • DOMChildNode ≫
  • PHP Manual
  • DOMCharacterData
  • ノードから指定した範囲のデータを抽出する

DOMCharacterData::substringData

(PHP 5, PHP 7, PHP 8)

DOMCharacterData::substringData — ノードから指定した範囲のデータを抽出する

説明

public DOMCharacterData::substringData(int $offset, int $count): string|false

指定した部分文字列を返します。

パラメータ

offset

部分文字列の抽出開始位置のオフセット。

count

抽出する文字数。

戻り値

指定された部分文字列を返します。 offset と count の和が文字列の長さをこえている場合、データの末尾までのすべての 16 ビット単位が返されます。

エラー / 例外

DOM_INDEX_SIZE_ERR

offset が負、あるいは 16 ビット単位の データ長より大きい場合、または count が 負の場合に発生します。

参考

  • DOMCharacterData::appendData() - ノードの文字データの最後に文字列を追加する
  • DOMCharacterData::deleteData() - 指定した範囲の文字列をノードから削除する
  • DOMCharacterData::insertData() - 指定した 16 ビット単位のオフセットに、文字列を挿入する
  • DOMCharacterData::replaceData() - DOMCharacterData ノードの文字列の一部を置換する


DOMChildNode インターフェイス

(PHP 8)

インターフェイス概要

interface DOMChildNode {
/* メソッド */
public after(DOMNode|string ...$nodes): void
public before(DOMNode|string ...$nodes): void
public remove(): void
public replaceWith(DOMNode|string ...$nodes): void
}

目次

  • DOMChildNode::after — ノードの後ろにノードを追加する
  • DOMChildNode::before — ノードの前にノードを追加する
  • DOMChildNode::remove — ノードを削除する
  • DOMChildNode::replaceWith — ノードを新しいノードで置き換える


ノードの後ろにノードを追加する

  • ≪ DOMChildNode
  • DOMChildNode::before ≫
  • PHP Manual
  • DOMChildNode
  • ノードの後ろにノードを追加する

DOMChildNode::after

(PHP 8)

DOMChildNode::after — ノードの後ろにノードを追加する

説明

public DOMChildNode::after(DOMNode|string ...$nodes): void

渡された nodes をノードの後ろに追加します。

パラメータ

nodes

ノードの後ろに追加されるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

参考

  • DOMChildNode::before() - ノードの前にノードを追加する
  • DOMChildNode::remove() - ノードを削除する
  • DOMChildNode::replaceWith() - ノードを新しいノードで置き換える
  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する


ノードの前にノードを追加する

  • ≪ DOMChildNode::after
  • DOMChildNode::remove ≫
  • PHP Manual
  • DOMChildNode
  • ノードの前にノードを追加する

DOMChildNode::before

(PHP 8)

DOMChildNode::before — ノードの前にノードを追加する

説明

public DOMChildNode::before(DOMNode|string ...$nodes): void

渡された nodes をノードの前に追加します。

パラメータ

nodes

ノードの前に追加されるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

参考

  • DOMChildNode::after() - ノードの後ろにノードを追加する
  • DOMChildNode::remove() - ノードを削除する
  • DOMChildNode::replaceWith() - ノードを新しいノードで置き換える


ノードを削除する

  • ≪ DOMChildNode::before
  • DOMChildNode::replaceWith ≫
  • PHP Manual
  • DOMChildNode
  • ノードを削除する

DOMChildNode::remove

(PHP 8)

DOMChildNode::remove — ノードを削除する

説明

public DOMChildNode::remove(): void

ノードを削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • DOMChildNode::after() - ノードの後ろにノードを追加する
  • DOMChildNode::before() - ノードの前にノードを追加する
  • DOMChildNode::replaceWith() - ノードを新しいノードで置き換える
  • DOMNode::removeChild() - 子要素群から子要素を削除する


ノードを新しいノードで置き換える

  • ≪ DOMChildNode::remove
  • DOMComment ≫
  • PHP Manual
  • DOMChildNode
  • ノードを新しいノードで置き換える

DOMChildNode::replaceWith

(PHP 8)

DOMChildNode::replaceWith — ノードを新しいノードで置き換える

説明

public DOMChildNode::replaceWith(DOMNode|string ...$nodes): void

ノードを新しい nodes で置き換えます。

パラメータ

nodes

置き換えるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

参考

  • DOMChildNode::after() - ノードの後ろにノードを追加する
  • DOMChildNode::before() - ノードの前にノードを追加する
  • DOMChildNode::remove() - ノードを削除する
  • DOMNode::replaceChild() - 子を置き換える


DOMComment クラス

(PHP 5, PHP 7, PHP 8)

はじめに

コメントノード、つまり <!-- と --> で囲まれた文字を表します。

クラス概要

class DOMComment extends DOMCharacterData {
/* 継承したプロパティ */
public string $data;
public readonly int $length;
public readonly ?DOMElement $previousElementSibling;
public readonly ?DOMElement $nextElementSibling;
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $data = "")
/* 継承したメソッド */
public DOMCharacterData::after(DOMNode|string ...$nodes): void
public DOMCharacterData::appendData(string $data): true
public DOMCharacterData::before(DOMNode|string ...$nodes): void
public DOMCharacterData::deleteData(int $offset, int $count): bool
public DOMCharacterData::insertData(int $offset, string $data): bool
public DOMCharacterData::remove(): void
public DOMCharacterData::replaceData(int $offset, int $count, string $data): bool
public DOMCharacterData::replaceWith(DOMNode|string ...$nodes): void
public DOMCharacterData::substringData(int $offset, int $count): string|false
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

参考

  • » W3C specification of Comment

目次

  • DOMComment::__construct — 新しい DOMComment オブジェクトを作成する


新しい DOMComment オブジェクトを作成する

  • ≪ DOMComment
  • DOMDocument ≫
  • PHP Manual
  • DOMComment
  • 新しい DOMComment オブジェクトを作成する

DOMComment::__construct

(PHP 5, PHP 7, PHP 8)

DOMComment::__construct — 新しい DOMComment オブジェクトを作成する

説明

public DOMComment::__construct(string $data = "")

新しい DOMComment オブジェクトを作成します。 このオブジェクトは読み込み専用です。このオブジェクトをドキュメントに 追加することが可能ですが、ノードがドキュメントと関連付けられるまでは ノードを追加することはできません。書き込み可能なノードを作成するには、 DOMDocument::createComment を使用します。

パラメータ

data

コメントの値。

例

例1 新しい DOMComment を作成する

<?php

$dom = new DOMDocument('1.0', 'iso-8859-1');
$element = $dom->appendChild(new DOMElement('root'));
$comment = $element->appendChild(new DOMComment('root comment'));
echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root><!--root comment--></root> */

?>

参考

  • DOMDocument::createComment() - 新しい comment ノードを作成する


DOMDocument クラス

(PHP 5, PHP 7, PHP 8)

はじめに

HTML ドキュメントあるいは XML ドキュメント全体を表し、 ドキュメントツリーのルートとなります。

クラス概要

class DOMDocument extends DOMNode implements DOMParentNode {
/* プロパティ */
public readonly ?DOMDocumentType $doctype;
public readonly DOMImplementation $implementation;
public readonly ?DOMElement $documentElement;
public readonly ?string $actualEncoding;
public ?string $encoding;
public readonly ?string $xmlEncoding;
public bool $standalone;
public bool $xmlStandalone;
public ?string $version;
public ?string $xmlVersion;
public bool $strictErrorChecking;
public ?string $documentURI;
public readonly mixed $config;
public bool $formatOutput;
public bool $validateOnParse;
public bool $resolveExternals;
public bool $preserveWhiteSpace;
public bool $recover;
public bool $substituteEntities;
public readonly ?DOMElement $firstElementChild;
public readonly ?DOMElement $lastElementChild;
public readonly int $childElementCount;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $version = "1.0", string $encoding = "")
public adoptNode(DOMNode $node): DOMNode|false
public append(DOMNode|string ...$nodes): void
public createAttribute(string $localName): DOMAttr|false
public createAttributeNS(?string $namespace, string $qualifiedName): DOMAttr|false
public createCDATASection(string $data): DOMCdataSection|false
public createComment(string $data): DOMComment
public createDocumentFragment(): DOMDocumentFragment
public createElement(string $localName, string $value = ""): DOMElement|false
public createElementNS(?string $namespace, string $qualifiedName, string $value = ""): DOMElement|false
public createEntityReference(string $name): DOMEntityReference|false
public createProcessingInstruction(string $target, string $data = ""): DOMProcessingInstruction|false
public createTextNode(string $data): DOMText
public getElementById(string $elementId): ?DOMElement
public getElementsByTagName(string $qualifiedName): DOMNodeList
public getElementsByTagNameNS(?string $namespace, string $localName): DOMNodeList
public importNode(DOMNode $node, bool $deep = false): DOMNode|false
public load(string $filename, int $options = 0): bool
public loadHTML(string $source, int $options = 0): bool
public loadHTMLFile(string $filename, int $options = 0): bool
public loadXML(string $source, int $options = 0): bool
public normalizeDocument(): void
public prepend(DOMNode|string ...$nodes): void
public registerNodeClass(string $baseClass, ?string $extendedClass): bool
public relaxNGValidate(string $filename): bool
public relaxNGValidateSource(string $source): bool
public replaceChildren(DOMNode|string ...$nodes): void
public save(string $filename, int $options = 0): int|false
public saveHTML(?DOMNode $node = null): string|false
public saveHTMLFile(string $filename): int|false
public saveXML(?DOMNode $node = null, int $options = 0): string|false
public schemaValidate(string $filename, int $flags = 0): bool
public schemaValidateSource(string $source, int $flags = 0): bool
public validate(): bool
public xinclude(int $options = 0): int|false
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

actualEncoding

非推奨。ドキュメントの実際のエンコーディング。 読み込み専用で、 encoding と同等の内容です。

childElementCount

子要素の数

config

非推奨。 DOMDocument::normalizeDocument() を実行する際に使用する設定。

doctype

このドキュメントに関連付けられた文書型宣言

documentElement

最初のドキュメント要素を示す DOMElement オブジェクト。 存在しない場合は null になります。

documentURI

ドキュメントの位置。未定義の場合は null

encoding

XML 宣言で指定したドキュメントのエンコーディング。 この属性は、DOM Level 3 の最終的な仕様には存在しません。 しかし、この実装で XML ドキュメントのエンコーディングを扱うにはこれを使用するしかありません。

firstElementChild

最初の子要素。存在しない場合は null になります。

formatOutput

字下げや空白を考慮してきれいに整形した出力を行う。 これは、ドキュメントを preserveWhitespace を有効にして読み込んだ場合は効果がありません。

implementation

このドキュメントを処理する DOMImplementation オブジェクト

lastElementChild

最後の子要素。存在しない場合は null になります。

preserveWhiteSpace

余分な空白を取り除かない。デフォルトは true false に設定すると、 DOMDocument::load() の option に LIBXML_NOBLANKS を渡すのと同じ効果があります。

recover

非標準。 リカバリーモードを有効にし、整形式でないドキュメントのパースを試みます。 この属性は DOM の仕様にはなく、libxml 固有の独自仕様です。

resolveExternals

文書型宣言で外部エンティティを読み込む際に true を設定する。 XML ドキュメントに文字エンティティを含める際に便利です。

standalone

非推奨。 そのドキュメントがスタンドアローンかどうかを XML 宣言で指定したもの。 xmlStandalone に対応します。

strictErrorChecking

エラー時に DOMException をスローする。デフォルトは true

substituteEntities

非標準。 エンティティの置換を行うかどうか。 この属性は DOM の仕様にはなく、libxml 固有の独自仕様です。 デフォルトは false です。

警告

エンティティの置換を有効にすると、XML外部エンティティ参照攻撃(XXE) を容易にしてしまうかもしれません。

validateOnParse

DTD を読み込んで検証する。デフォルトは false

警告

DTD の検証を有効にすると、XML外部エンティティ参照攻撃(XXE) を容易にしてしまうかもしれません。

version

非推奨。 XML のバージョン。 xmlVersion に対応します。

xmlEncoding

XML 宣言の一部として、このドキュメントのエンコーディングを 指定する属性。指定されていない場合や不明な場合 (たとえば ドキュメントがメモリ上に存在する場合など) は null

xmlStandalone

XML 宣言の一部として、このドキュメントがスタンドアローンか どうかを指定する。指定されていない場合は false スタンドアローンドキュメントとは、 外部のマークアップ宣言を持たないドキュメントのことです。 スタンドアローンドキュメントの例としては、 DTD がデフォルトの値で宣言されているものが挙げられます。

xmlVersion

XML 宣言の一部として、このドキュメントのバージョン番号を指定する。 バージョン番号が定義されておらず、ドキュメントが "XML" の機能を サポートしている場合は、値は "1.0"

変更履歴

バージョン | 説明
8.0.0 | DOMDocument は、 DOMParentNode を実装しました。
8.0.0 | 実装されていなかったメソッド DOMDocument::renameNode() が削除されました。

注意

注意:

DOM拡張モジュール は UTF-8 エンコーディングを使います。他のエンコーディングを扱う場合は、mb_convert_encoding(), UConverter::transcode(), iconv() を使ってください。

注意:

DOMDocument オブジェクトに対して json_encode() を使うと、結果は空オブジェクトをエンコードしたものになります。

参考

  • » W3C specification for Document

目次

  • DOMDocument::adoptNode — ノードを別のドキュメントに移す
  • DOMDocument::append — 最後の子ノードの後ろにノードを追加する
  • DOMDocument::__construct — 新しい DOMDocument オブジェクトを作成する
  • DOMDocument::createAttribute — 新しい属性を作成する
  • DOMDocument::createAttributeNS — 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection — 新しい cdata ノードを作成する
  • DOMDocument::createComment — 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment — 新しい文書片を作成する
  • DOMDocument::createElement — 新しい要素ノードを作成する
  • DOMDocument::createElementNS — 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference — 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction — 新しい PI ノードを作成する
  • DOMDocument::createTextNode — 新しいテキストノードを作成する
  • DOMDocument::getElementById — id に対応する要素を検索する
  • DOMDocument::getElementsByTagName — 指定したローカルタグ名に対応するすべての要素を検索する
  • DOMDocument::getElementsByTagNameNS — 指定した名前空間で、タグ名に対応するすべての要素を検索する
  • DOMDocument::importNode — 現在のドキュメントにノードをインポートする
  • DOMDocument::load — ファイルから XML を読み込む
  • DOMDocument::loadHTML — 文字列から HTML を読み込む
  • DOMDocument::loadHTMLFile — ファイルから HTML を読み込む
  • DOMDocument::loadXML — 文字列から XML を読み込む
  • DOMDocument::normalizeDocument — ドキュメントを正規化する
  • DOMDocument::prepend — 最初の子ノードの前にノードを追加する
  • DOMDocument::registerNodeClass — 基底ノード型を作成する際に使用する拡張クラスを登録する
  • DOMDocument::relaxNGValidate — ドキュメントを relaxNG で検証する
  • DOMDocument::relaxNGValidateSource — ドキュメントを relaxNG で検証する
  • DOMDocument::replaceChildren — ドキュメントの子を置換する
  • DOMDocument::save — 内部の XML ツリーをファイルに出力する
  • DOMDocument::saveHTML — 内部のドキュメントを HTML 形式の文字列として出力する
  • DOMDocument::saveHTMLFile — 内部のドキュメントを HTML 形式でファイルに出力する
  • DOMDocument::saveXML — 内部の XML ツリーを文字列として出力する
  • DOMDocument::schemaValidate — スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
  • DOMDocument::schemaValidateSource — スキーマに基づいてドキュメントを検証する
  • DOMDocument::validate — DTD に基づいてドキュメントを検証する
  • DOMDocument::xinclude — DOMDocument オブジェクト内の XIncludes を置換する


ノードを別のドキュメントに移す

  • ≪ DOMDocument
  • DOMDocument::append ≫
  • PHP Manual
  • DOMDocument
  • ノードを別のドキュメントに移す

DOMDocument::adoptNode

(PHP >= 8.3)

DOMDocument::adoptNode — ノードを別のドキュメントに移す

説明

public DOMDocument::adoptNode(DOMNode $node): DOMNode|false

ノードを別のドキュメントから、現在のドキュメントに移します。

パラメータ

node

移すノード

戻り値

移したノードを返します。エラー時に false を返します。

エラー / 例外

DOM_NOT_SUPPORTED_ERR

ノードの型が、転送先のノードでサポートされていない場合に発生します。

例

例1 DOMDocument::adoptNode() の例

最初のドキュメントの hello 要素を二番目のものに移します。

<?php
$doc1 = new DOMDocument;
$doc1->loadXML("<container><hello><world/></hello></container>");
$hello = $doc1->documentElement->firstChild;

$doc2 = new DOMDocument;
$doc2->loadXML("<root/>");
$doc2->documentElement->appendChild($doc2->adoptNode($hello));

echo $doc1->saveXML() . PHP_EOL;
echo $doc2->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container/>

<?xml version="1.0"?>
<root><hello><world/></hello></root>

参考

  • DOMDocument::importNode() - 現在のドキュメントにノードをインポートする


最後の子ノードの後ろにノードを追加する

  • ≪ DOMDocument::adoptNode
  • DOMDocument::__construct ≫
  • PHP Manual
  • DOMDocument
  • 最後の子ノードの後ろにノードを追加する

DOMDocument::append

(PHP 8)

DOMDocument::append — 最後の子ノードの後ろにノードを追加する

説明

public DOMDocument::append(DOMNode|string ...$nodes): void

ひとつ以上の nodes を子要素のリストに追加します。 追加されるのは、最後の子ノードの後ろになります。

パラメータ

nodes

追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMDocument::append() の例

ドキュメントのルートの後ろにノードを追加します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<hello/>");

$doc->append("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<hello/>
beautiful
<world/>

参考

  • DOMParentNode::append() - 最後の子ノードの後ろにノードを追加する
  • DOMDocument::prepend() - 最初の子ノードの前にノードを追加する


新しい DOMDocument オブジェクトを作成する

  • ≪ DOMDocument::append
  • DOMDocument::createAttribute ≫
  • PHP Manual
  • DOMDocument
  • 新しい DOMDocument オブジェクトを作成する

DOMDocument::__construct

(PHP 5, PHP 7, PHP 8)

DOMDocument::__construct — 新しい DOMDocument オブジェクトを作成する

説明

public DOMDocument::__construct(string $version = "1.0", string $encoding = "")

新しい DOMDocument オブジェクトを作成します。

パラメータ

version

XML 宣言の一部である、ドキュメントのバージョン番号。

encoding

XML 宣言の一部である、ドキュメントのエンコーディング。

例

例1 新しい DOMDocument を作成する

<?php

$dom = new DOMDocument('1.0', 'iso-8859-1');

echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?> */

?>

参考

  • DOMImplementation::createDocument() - 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する


新しい属性を作成する

  • ≪ DOMDocument::__construct
  • DOMDocument::createAttributeNS ≫
  • PHP Manual
  • DOMDocument
  • 新しい属性を作成する

DOMDocument::createAttribute

(PHP 5, PHP 7, PHP 8)

DOMDocument::createAttribute — 新しい属性を作成する

説明

public DOMDocument::createAttribute(string $localName): DOMAttr|false

この関数は、DOMAttr クラスの新しいインスタンスを作成します。 このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

localName

属性の名前。

戻り値

新しい DOMAttr、あるいはエラーが発生した場合は false を返します。

エラー / 例外

DOM_INVALID_CHARACTER_ERR

localName が無効な文字を含んでいる場合に発生します。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


関連付けられた名前空間に新しい属性を作成する

  • ≪ DOMDocument::createAttribute
  • DOMDocument::createCDATASection ≫
  • PHP Manual
  • DOMDocument
  • 関連付けられた名前空間に新しい属性を作成する

DOMDocument::createAttributeNS

(PHP 5, PHP 7, PHP 8)

DOMDocument::createAttributeNS — 関連付けられた名前空間に新しい属性を作成する

説明

public DOMDocument::createAttributeNS(?string $namespace, string $qualifiedName): DOMAttr|false

この関数は、DOMAttr クラスの新しいインスタンスを作成します。 このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

namespace

名前空間の URI。

qualifiedName

属性のタグ名とプレフィックスを、prefix:tagname のような形式で指定する。

戻り値

新しい DOMAttr、あるいはエラーが発生した場合は false を返します。

エラー / 例外

DOM_INVALID_CHARACTER_ERR

qualifiedName が無効な文字を含んでいる場合に発生します。

DOM_NAMESPACE_ERR

qualifiedName が不正な形式である場合、あるいは qualifiedName がプレフィックスを含んでいる にもかかわらず namespace が null である場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | prefix を指定せずにこのメソッドをコールしても、デフォルトの名前空間を仮定する代わりに prefix を選ぶようになりました。これより前のバージョンでは、prefix なしの属性を作成し、誤ってオーナーとなる要素の名前空間を適用していました。なぜなら、デフォルトの名前空間は属性には適用されないためです。
8.3.0 | オーナーとなる要素で prefix が既に異なる namespace URI で使われている場合にこのメソッドを呼び出しても、名前空間の衝突を避けるために新しく prefix を異なるものに変更するようになりました。これは DOM の仕様が要求する振る舞いに合わせるためです。これより前のバージョンでは、エラーコード DOM_NAMESPACE_ERR を持つ DOMException をスローしていました。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しい cdata ノードを作成する

  • ≪ DOMDocument::createAttributeNS
  • DOMDocument::createComment ≫
  • PHP Manual
  • DOMDocument
  • 新しい cdata ノードを作成する

DOMDocument::createCDATASection

(PHP 5, PHP 7, PHP 8)

DOMDocument::createCDATASection — 新しい cdata ノードを作成する

説明

public DOMDocument::createCDATASection(string $data): DOMCdataSection|false

この関数は、DOMCDATASection クラスの新しいインスタンスを作成します。このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

data

cdata の内容。

戻り値

新しい DOMCDATASection、あるいはエラーが発生した場合は false を返します。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しい comment ノードを作成する

  • ≪ DOMDocument::createCDATASection
  • DOMDocument::createDocumentFragment ≫
  • PHP Manual
  • DOMDocument
  • 新しい comment ノードを作成する

DOMDocument::createComment

(PHP 5, PHP 7, PHP 8)

DOMDocument::createComment — 新しい comment ノードを作成する

説明

public DOMDocument::createComment(string $data): DOMComment

この関数は、DOMComment クラスの新しいインスタンスを作成します。このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

data

コメントの内容。

戻り値

新しい DOMComment を返します。

変更履歴

バージョン | 説明
8.1.0 | エラーが発生した場合に、 DomException をスローするようになりました。 これより前のバージョンでは、false を返していました。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しい文書片を作成する

  • ≪ DOMDocument::createComment
  • DOMDocument::createElement ≫
  • PHP Manual
  • DOMDocument
  • 新しい文書片を作成する

DOMDocument::createDocumentFragment

(PHP 5, PHP 7, PHP 8)

DOMDocument::createDocumentFragment — 新しい文書片を作成する

説明

public DOMDocument::createDocumentFragment(): DOMDocumentFragment

この関数は、DOMDocumentFragment クラスの新しいインスタンスを作成します。このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

この関数にはパラメータはありません。

戻り値

新しい DOMDocumentFragment を返します。

変更履歴

バージョン | 説明
8.1.0 | エラーが発生した場合に、 DomException をスローするようになりました。 これより前のバージョンでは、false を返していました。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しい要素ノードを作成する

  • ≪ DOMDocument::createDocumentFragment
  • DOMDocument::createElementNS ≫
  • PHP Manual
  • DOMDocument
  • 新しい要素ノードを作成する

DOMDocument::createElement

(PHP 5, PHP 7, PHP 8)

DOMDocument::createElement — 新しい要素ノードを作成する

説明

public DOMDocument::createElement(string $localName, string $value = ""): DOMElement|false

この関数は、DOMElement クラスの新しいインスタンスを作成します。 このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

localName

要素のタグ名。

value

要素の値。デフォルトでは、空の要素が作成されます。 その後に DOMElement::$nodeValue で値を設定することも可能です。

指定した値はすべてそのまま用いますが、エンティティ参照 < と > だけはエスケープします。& は手動でエスケープする必要があることに注意しましょう。 そうしないと、エンティティ参照の開始とみなされてしまいます。また、" はエスケープされません。

戻り値

新しい DOMElement クラスの新しいインスタンス、 あるいはエラーが発生した場合は false を返します。

エラー / 例外

DOM_INVALID_CHARACTER_ERR

localName が無効な文字を含んでいる場合に発生します。

例

例1 新しい要素を作成し、ルートとして挿入する

<?php

$dom = new DOMDocument('1.0', 'utf-8');

$element = $dom->createElement('test', 'This is the root element!');

// 新しい要素をルート (ドキュメントの子要素) として挿入する
$dom->appendChild($element);

echo $dom->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="utf-8"?>
<test>This is the root element!</test>

例2 & をエスケープせずに value に渡す例

<?php
$dom = new DOMDocument('1.0', 'utf-8');
$element = $dom->createElement('foo', 'me & you');
$dom->appendChild($element);
echo $dom->saveXML();
?>

上の例の出力は、 たとえば以下のようになります。

Warning: DOMDocument::createElement(): unterminated entity reference             you in /in/BjTCg on line 4
<?xml version="1.0" encoding="utf-8"?>
<foo/>

注意

注意:

value は エスケープされません。 エスケープに対応した テキストノードを作るには DOMDocument::createTextNode() を使います。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


関連付けられた名前空間に新しい要素を作成する

  • ≪ DOMDocument::createElement
  • DOMDocument::createEntityReference ≫
  • PHP Manual
  • DOMDocument
  • 関連付けられた名前空間に新しい要素を作成する

DOMDocument::createElementNS

(PHP 5, PHP 7, PHP 8)

DOMDocument::createElementNS — 関連付けられた名前空間に新しい要素を作成する

説明

public DOMDocument::createElementNS(?string $namespace, string $qualifiedName, string $value = ""): DOMElement|false

この関数は、関連付けられた名前空間に新しい要素を作成します。 このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

namespace

名前空間の URI。

qualifiedName

要素名を、prefix:tagname のような形式で指定する。

value

要素の値。デフォルトでは、空の要素が作成されます。 その後に DOMElement::$nodeValue で値を設定することも可能です。

戻り値

新しい DOMElement、 あるいはエラーが発生した場合には false を返します。

エラー / 例外

DOM_INVALID_CHARACTER_ERR

qualifiedName が無効な文字を含んでいる場合に発生します。

DOM_NAMESPACE_ERR

qualifiedName が無効な名前である場合に発生します。

例

例1 新しい要素を作成し、ルートとして挿入する

<?php

$dom = new DOMDocument('1.0', 'utf-8');

$element = $dom->createElementNS('http://www.example.com/XFoo', 'xfoo:test', 'This is the root element!');

// 新しい要素をルート (ドキュメントの子要素) として挿入する
$dom->appendChild($element);

echo $dom->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="iso-8859-1"?>
<xfoo:test xmlns:xfoo="http://www.example.com/XFoo">This is the root element!</xfoo:test>

例2 名前空間プレフィックスの例

<?php
$doc = new DOMDocument('1.0', 'utf-8');
$doc->formatOutput = true;
$root = $doc->createElementNS('http://www.w3.org/2005/Atom', 'element');
$doc->appendChild($root);
$root->setAttributeNS('http://www.w3.org/2000/xmlns/' ,'xmlns:g', 'http://base.google.com/ns/1.0');
$item = $doc->createElementNS('http://base.google.com/ns/1.0', 'g:item_type', 'house');
$root->appendChild($item);

echo $doc->saveXML(), "\n";

echo $item->namespaceURI, "\n"; // 出力: http://base.google.com/ns/1.0
echo $item->prefix, "\n"; // 出力: g
echo $item->localName, "\n"; // 出力: item_type
?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="utf-8"?>
<element xmlns="http://www.w3.org/2005/Atom" xmlns:g="http://base.google.com/ns/1.0">
  <g:item_type>house</g:item_type>
</element>

http://base.google.com/ns/1.0
g
item_type

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しいエンティティ参照ノードを作成する

  • ≪ DOMDocument::createElementNS
  • DOMDocument::createProcessingInstruction ≫
  • PHP Manual
  • DOMDocument
  • 新しいエンティティ参照ノードを作成する

DOMDocument::createEntityReference

(PHP 5, PHP 7, PHP 8)

DOMDocument::createEntityReference — 新しいエンティティ参照ノードを作成する

説明

public DOMDocument::createEntityReference(string $name): DOMEntityReference|false

この関数は、DOMEntityReference クラスの新しいインスタンスを作成します。このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

name

エンティティ参照の内容、つまり、エンティティ参照から 先頭の & および末尾の ; を取り除いたもの。

戻り値

新しい DOMEntityReference、 あるいはエラーが発生した場合には false を返します。

エラー / 例外

DOM_INVALID_CHARACTER_ERR

name が無効な文字を含んでいる場合に発生します。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しい PI ノードを作成する

  • ≪ DOMDocument::createEntityReference
  • DOMDocument::createTextNode ≫
  • PHP Manual
  • DOMDocument
  • 新しい PI ノードを作成する

DOMDocument::createProcessingInstruction

(PHP 5, PHP 7, PHP 8)

DOMDocument::createProcessingInstruction — 新しい PI ノードを作成する

説明

public DOMDocument::createProcessingInstruction(string $target, string $data = ""): DOMProcessingInstruction|false

この関数は、DOMProcessingInstruction クラスの新しいインスタンスを作成します。このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

target

処理命令の対象。

data

処理命令の内容。

戻り値

新しい DOMProcessingInstruction、 あるいはエラーが発生した場合には false を返します。

エラー / 例外

DOM_INVALID_CHARACTER_ERR

target が無効な文字を含んでいる場合に発生します。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


新しいテキストノードを作成する

  • ≪ DOMDocument::createProcessingInstruction
  • DOMDocument::getElementById ≫
  • PHP Manual
  • DOMDocument
  • 新しいテキストノードを作成する

DOMDocument::createTextNode

(PHP 5, PHP 7, PHP 8)

DOMDocument::createTextNode — 新しいテキストノードを作成する

説明

public DOMDocument::createTextNode(string $data): DOMText

この関数は、DOMText クラスの新しいインスタンスを作成します。このノードは、( DOMNode::appendChild() などで) 挿入されない限り、ドキュメント内にあらわれません。

パラメータ

data

テキストの内容。

戻り値

新しい DOMText を返します。

変更履歴

バージョン | 説明
8.1.0 | エラーが発生した場合に、 DomException をスローするようになりました。 これより前のバージョンでは、false を返していました。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMDocument::createAttribute() - 新しい属性を作成する
  • DOMDocument::createAttributeNS() - 関連付けられた名前空間に新しい属性を作成する
  • DOMDocument::createCDATASection() - 新しい cdata ノードを作成する
  • DOMDocument::createComment() - 新しい comment ノードを作成する
  • DOMDocument::createDocumentFragment() - 新しい文書片を作成する
  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する
  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する
  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する


id に対応する要素を検索する

  • ≪ DOMDocument::createTextNode
  • DOMDocument::getElementsByTagName ≫
  • PHP Manual
  • DOMDocument
  • id に対応する要素を検索する

DOMDocument::getElementById

(PHP 5, PHP 7, PHP 8)

DOMDocument::getElementById — id に対応する要素を検索する

説明

public DOMDocument::getElementById(string $elementId): ?DOMElement

この関数は、 DOMDocument::getElementsByTagName と同じですが、指定した ID から要素を検索する点が違います。

この関数を動作させるには、何らかの ID 属性を DOMElement::setIdAttribute で設定するか、あるいは DTD で ID 型の属性を定義する必要があります。 後者の場合は、 DOMDocument::validate あるいは DOMDocument::$validateOnParse を使用してドキュメントを検証する必要があります。

パラメータ

elementId

要素の ID。

戻り値

DOMElement、 あるいは要素が見つからなかった場合は null を返します。

例

例1 DOMDocument::getElementById() の例

次の例では、以下のような内容の book.xml を使います。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE books [
  <!ELEMENT books   (book+)>
  <!ELEMENT book    (title, author+, xhtml:blurb?)>
  <!ELEMENT title   (#PCDATA)>
  <!ELEMENT blurb   (#PCDATA)>
  <!ELEMENT author  (#PCDATA)>
  <!ATTLIST books   xmlns        CDATA  #IMPLIED>
  <!ATTLIST books   xmlns:xhtml  CDATA  #IMPLIED>
  <!ATTLIST book    id           ID     #IMPLIED>
  <!ATTLIST author  email        CDATA  #IMPLIED>
]>
<?xml-stylesheet type="text/xsl" href="style.xsl"?>
<books xmlns="http://books.php/" xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <book id="php-basics">
    <title>PHP Basics</title>
    <author email="jim.smith@basics.php">Jim Smith</author>
    <author email="jane.smith@basics.php">Jane Smith</author>
    <xhtml:blurb><![CDATA[
<p><em>PHP Basics</em> provides an introduction to PHP.</p>
]]></xhtml:blurb>
  </book>
  <book id="php-advanced">
    <title>PHP Advanced Programming</title>
    <author email="jon.doe@advanced.php">Jon Doe</author>
  </book>
</books>
<?php

$doc = new DomDocument;

// ID を参照する前に、ドキュメントを検証する必要があります
$doc->validateOnParse = true;
$doc->Load('book.xml');

echo "ID が 'php-basics' の要素は " . $doc->getElementById('php-basics')->tagName . " です。\n";

?>

上の例の出力は以下となります。

ID が 'php-basics' の要素は book です。

参考

  • DOMDocument::getElementsByTagName() - 指定したローカルタグ名に対応するすべての要素を検索する


指定したローカルタグ名に対応するすべての要素を検索する

  • ≪ DOMDocument::getElementById
  • DOMDocument::getElementsByTagNameNS ≫
  • PHP Manual
  • DOMDocument
  • 指定したローカルタグ名に対応するすべての要素を検索する

DOMDocument::getElementsByTagName

(PHP 5, PHP 7, PHP 8)

DOMDocument::getElementsByTagName — 指定したローカルタグ名に対応するすべての要素を検索する

説明

public DOMDocument::getElementsByTagName(string $qualifiedName): DOMNodeList

この関数は、指定したローカルタグ名のすべての要素を含む DOMNodeList クラスの新しいインスタンスを返します。

パラメータ

qualifiedName

タグのローカル名 (名前空間を除いたもの) に一致する名前。* はすべてのタグに一致します。

戻り値

一致するすべての要素を含む、新しい DOMNodeList オブジェクトを返します。

例

例1 基本的な使用例

<?php
$xml = <<< XML
<?xml version="1.0" encoding="utf-8"?>
<books>
<book>Patterns of Enterprise Application Architecture</book>
<book>Design Patterns: Elements of Reusable Software Design</book>
<book>Clean Code</book>
</books>
XML;

$dom = new DOMDocument;
$dom->loadXML($xml);
$books = $dom->getElementsByTagName('book');
foreach ($books as $book) {
echo $book->nodeValue, PHP_EOL;
}
?>

上の例の出力は以下となります。

Patterns of Enterprise Application Architecture
Design Patterns: Elements of Reusable Software Design
Clean Code

参考

  • DOMDocument::getElementsByTagNameNS() - 指定した名前空間で、タグ名に対応するすべての要素を検索する


指定した名前空間で、タグ名に対応するすべての要素を検索する

  • ≪ DOMDocument::getElementsByTagName
  • DOMDocument::importNode ≫
  • PHP Manual
  • DOMDocument
  • 指定した名前空間で、タグ名に対応するすべての要素を検索する

DOMDocument::getElementsByTagNameNS

(PHP 5, PHP 7, PHP 8)

DOMDocument::getElementsByTagNameNS — 指定した名前空間で、タグ名に対応するすべての要素を検索する

説明

public DOMDocument::getElementsByTagNameNS(?string $namespace, string $localName): DOMNodeList

指定したローカル名および名前空間 URI に一致するすべての要素の DOMNodeList を返します。

パラメータ

namespace

条件に一致する要素の名前空間 URI。 "*" はすべての名前空間に一致します。 null を渡すと、空の名前空間に一致します。

localName

条件に一致する要素のローカル名。 "*" はすべてのローカル名に一致します。

戻り値

一致するすべての要素を含む、新しい DOMNodeList オブジェクトを返します。

変更履歴

バージョン | 説明
8.0.3 | namespace は、nullable になりました。

例

例1 すべての XInclude 要素を取得する

<?php

$xml = <<<EOD
<?xml version="1.0" ?>
<chapter xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Books of the other guy..</title>
<para>
<xi:include href="book.xml">
<xi:fallback>
<error>xinclude: book.xml not found</error>
</xi:fallback>
</xi:include>
<include>
This is another namespace
</include>
</para>
</chapter>
EOD;
$dom = new DOMDocument;

// 上で定義した XML 文字列を読み込みます
$dom->loadXML($xml);

foreach ($dom->getElementsByTagNameNS('http://www.w3.org/2001/XInclude', '*') as $element) {
echo 'local name: ', $element->localName, ', prefix: ', $element->prefix, "\n";
}
?>

上の例の出力は以下となります。

local name: include, prefix: xi
local name: fallback, prefix: xi

参考

  • DOMDocument::getElementsByTagName() - 指定したローカルタグ名に対応するすべての要素を検索する


現在のドキュメントにノードをインポートする

  • ≪ DOMDocument::getElementsByTagNameNS
  • DOMDocument::load ≫
  • PHP Manual
  • DOMDocument
  • 現在のドキュメントにノードをインポートする

DOMDocument::importNode

(PHP 5, PHP 7, PHP 8)

DOMDocument::importNode — 現在のドキュメントにノードをインポートする

説明

public DOMDocument::importNode(DOMNode $node, bool $deep = false): DOMNode|false

この関数は、インポートするノードのコピーを返し、 それを現在のドキュメントに関連付けます。

パラメータ

node

インポートするノード。

deep

true の場合、このメソッドは node 以下のサブツリーも再帰的にインポートします。

注意:

ノードの属性をコピーするには deep を true に設定しなければなりません。

戻り値

コピーされたノードを返します。 コピーできなかった場合は false を返します。

エラー / 例外

ノードがインポートできなかった場合には DOMException がスローされます。

例

例1 DOMDocument::importNode() の例

ノードをドキュメント間でコピーします。

<?php

$orgdoc = new DOMDocument;
$orgdoc->loadXML("<root><element><child>text in child</child></element></root>");

// 新しいドキュメントにインポートしたいノード
$node = $orgdoc->getElementsByTagName("element")->item(0);

// 新しいドキュメントを作成します
$newdoc = new DOMDocument;
$newdoc->formatOutput = true;

// マークアップを追加します
$newdoc->loadXML("<root><someelement>text in some element</someelement></root>");

echo "The 'new document' before copying nodes into it:\n";
echo $newdoc->saveXML();

// ノードとそのすべての子をドキュメントにインポートします
$node = $newdoc->importNode($node, true);
// それから、それを "<root>" ノードに追加します
$newdoc->documentElement->appendChild($node);

echo "\nThe 'new document' after copying the nodes into it:\n";
echo $newdoc->saveXML();
?>

上の例の出力は以下となります。

The 'new document' before copying nodes into it:
<?xml version="1.0"?>
<root>
  <someelement>text in some element</someelement>
</root>

The 'new document' after copying the nodes into it:
<?xml version="1.0"?>
<root>
  <someelement>text in some element</someelement>
  <element>
    <child>text in child</child>
  </element>
</root>


ファイルから XML を読み込む

  • ≪ DOMDocument::importNode
  • DOMDocument::loadHTML ≫
  • PHP Manual
  • DOMDocument
  • ファイルから XML を読み込む

DOMDocument::load

(PHP 5, PHP 7, PHP 8)

DOMDocument::load — ファイルから XML を読み込む

説明

public DOMDocument::load(string $filename, int $options = 0): bool

XML ドキュメントをファイルから読み込みます。

警告

Unix 風のパス (スラッシュを使った方式) を Windows 上で使用すると、 パフォーマンスが著しく低下します。そんな場合は realpath() をコールしましょう。

パラメータ

filename

XML ドキュメントへのパス。

options

libxml オプション定数 を ビット OR で連結したもの。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

空の文字列を filename に渡したり中身が空のファイルを指定したりすると、警告が発生します。 この警告は libxml が発するものではないので、libxml のエラー処理関数では処理できません。

変更履歴

バージョン | 説明
8.3.0 | この関数の仮の戻り値の型が、bool になりました。
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

例

例1 ドキュメントの作成

<?php
$doc = new DOMDocument();
$doc->load('book.xml');
echo $doc->saveXML();
?>

参考

  • DOMDocument::loadXML() - 文字列から XML を読み込む
  • DOMDocument::save() - 内部の XML ツリーをファイルに出力する
  • DOMDocument::saveXML() - 内部の XML ツリーを文字列として出力する


文字列から HTML を読み込む

  • ≪ DOMDocument::load
  • DOMDocument::loadHTMLFile ≫
  • PHP Manual
  • DOMDocument
  • 文字列から HTML を読み込む

DOMDocument::loadHTML

(PHP 5, PHP 7, PHP 8)

DOMDocument::loadHTML — 文字列から HTML を読み込む

説明

public DOMDocument::loadHTML(string $source, int $options = 0): bool

この関数は、文字列 source に含まれる HTML を パースします。XML を読み込む場合とは異なり、妥当な HTML でなくても 読み込むことができます。

警告

この関数は、HTML4 のパーサを使って入力をパースします。モダンなWebブラウザが採用している HTML5 のパースルールとは異なります。入力によっては、このことが原因で異なるDOM構造になるかもしれません。よって、この関数はHTMLを無害化する目的で安全に使えません。

HTML をパースする挙動は、利用している libxml のバージョンに依存します。 特にエッジケースやエラーハンドリングについてそれが当てはまります。 HTML5 に準拠したパースを行うには、PHP 8.4 で追加される Dom\HTMLDocument::createFromString() や Dom\HTMLDocument::createFromFile() を使いましょう。

例を挙げましょう。HTML要素によっては、暗黙のうちに親の要素を閉じるものがあります。親要素を自動で閉じるルールは、HTML4 と HTML5 で異なります。よって、DOMDocument が表す DOM 構造は Webブラウザ上のそれと異なる可能性があります。このことから、攻撃者がHTMLを壊す攻撃を許す可能性があります。

パラメータ

source

HTML 文字列。

options

追加の Libxml パラメータ を、ビット演算子の OR で指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

空の文字列を source に渡すと、警告が発生します。 この警告は libxml が発するものではないので、libxml のエラー処理関数では処理できません。

壊れた HTML も読み込めますが、マークアップが正しくない場合には E_WARNING が発生します。 このエラーの処理には libxml のエラー処理関数 が使えます。

変更履歴

バージョン | 説明
8.3.0 | この関数の仮の戻り値の型が、bool になりました。
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

例

例1 ドキュメントを作成する

<?php
$doc = new DOMDocument();
$doc->loadHTML("<html><body>Test<br></body></html>");
echo $doc->saveHTML();
?>

参考

  • DOMDocument::loadHTMLFile() - ファイルから HTML を読み込む
  • DOMDocument::saveHTML() - 内部のドキュメントを HTML 形式の文字列として出力する
  • DOMDocument::saveHTMLFile() - 内部のドキュメントを HTML 形式でファイルに出力する


ファイルから HTML を読み込む

  • ≪ DOMDocument::loadHTML
  • DOMDocument::loadXML ≫
  • PHP Manual
  • DOMDocument
  • ファイルから HTML を読み込む

DOMDocument::loadHTMLFile

(PHP 5, PHP 7, PHP 8)

DOMDocument::loadHTMLFile — ファイルから HTML を読み込む

説明

public DOMDocument::loadHTMLFile(string $filename, int $options = 0): bool

この関数は、filename という名前のファイルから 読み込んだ HTML ドキュメントをパースします。 XML を読み込む場合とは異なり、妥当な HTML でなくても 読み込むことができます。

警告

この関数は、HTML4 のパーサを使って入力をパースします。モダンなWebブラウザが採用している HTML5 のパースルールとは異なります。入力によっては、このことが原因で異なるDOM構造になるかもしれません。よって、この関数はHTMLを無害化する目的で安全に使えません。

HTML をパースする挙動は、利用している libxml のバージョンに依存します。 特にエッジケースやエラーハンドリングについてそれが当てはまります。 HTML5 に準拠したパースを行うには、PHP 8.4 で追加される Dom\HTMLDocument::createFromString() や Dom\HTMLDocument::createFromFile() を使いましょう。

例を挙げましょう。HTML要素によっては、暗黙のうちに親の要素を閉じるものがあります。親要素を自動で閉じるルールは、HTML4 と HTML5 で異なります。よって、DOMDocument が表す DOM 構造は Webブラウザ上のそれと異なる可能性があります。このことから、攻撃者がHTMLを壊す攻撃を許す可能性があります。

パラメータ

filename

HTML ファイルへのパス。

options

追加の Libxml パラメータ を、ビット演算子の OR で指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

空の文字列を filename に渡したり中身が空のファイルを指定したりすると、警告が発生します。 この警告は libxml が発するものではないので、libxml のエラー処理関数 では処理できません。

壊れた HTML も読み込めますが、マークアップが正しくない場合には E_WARNING が発生します。 このエラーの処理には libxml のエラー処理関数 が使えます。

変更履歴

バージョン | 説明
8.3.0 | この関数の仮の戻り値の型が、bool になりました。+
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

例

例1 ドキュメントを作成する

<?php
$doc = new DOMDocument();
$doc->loadHTMLFile("filename.html");
echo $doc->saveHTML();
?>

参考

  • DOMDocument::loadHTML() - 文字列から HTML を読み込む
  • DOMDocument::saveHTML() - 内部のドキュメントを HTML 形式の文字列として出力する
  • DOMDocument::saveHTMLFile() - 内部のドキュメントを HTML 形式でファイルに出力する


文字列から XML を読み込む

  • ≪ DOMDocument::loadHTMLFile
  • DOMDocument::normalizeDocument ≫
  • PHP Manual
  • DOMDocument
  • 文字列から XML を読み込む

DOMDocument::loadXML

(PHP 5, PHP 7, PHP 8)

DOMDocument::loadXML — 文字列から XML を読み込む

説明

public DOMDocument::loadXML(string $source, int $options = 0): bool

XML ドキュメントを文字列から読み込みます。

パラメータ

source

XML を含む文字列。

options

libxml オプション定数 を ビット OR で連結したもの。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

空の文字列を source に渡すと、警告が発生します。 この警告は libxml が発するものではないので、libxml のエラー処理関数では処理できません。

変更履歴

バージョン | 説明
8.3.0 | この関数の仮の戻り値の型が、bool になりました。
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

例

例1 ドキュメントを作成する

<?php
$doc = new DOMDocument();
$doc->loadXML('<root><node/></root>');
echo $doc->saveXML();
?>

参考

  • DOMDocument::load() - ファイルから XML を読み込む
  • DOMDocument::save() - 内部の XML ツリーをファイルに出力する
  • DOMDocument::saveXML() - 内部の XML ツリーを文字列として出力する


ドキュメントを正規化する

  • ≪ DOMDocument::loadXML
  • DOMDocument::prepend ≫
  • PHP Manual
  • DOMDocument
  • ドキュメントを正規化する

DOMDocument::normalizeDocument

(PHP 5, PHP 7, PHP 8)

DOMDocument::normalizeDocument — ドキュメントを正規化する

説明

public DOMDocument::normalizeDocument(): void

このメソッドは、まるでドキュメントを一度保存してから読み込みなおしたかのように動作し、 ドキュメントを "正規化された" 形式にします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • » The DOM Specification
  • DOMNode::normalize() - ノードを正規化する


最初の子ノードの前にノードを追加する

  • ≪ DOMDocument::normalizeDocument
  • DOMDocument::registerNodeClass ≫
  • PHP Manual
  • DOMDocument
  • 最初の子ノードの前にノードを追加する

DOMDocument::prepend

(PHP 8)

DOMDocument::prepend — 最初の子ノードの前にノードを追加する

説明

public DOMDocument::prepend(DOMNode|string ...$nodes): void

ひとつ以上の nodes を、 最初の子ノードの前の、子ノードのリストに追加します。

パラメータ

nodes

ノードの前に追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMDocument::prepend() の例

ドキュメントのルートの前にノードを追加します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<world/>");

$doc->prepend($doc->createElement("hello"), "beautiful");

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<hello/>
beautiful
<world/>

参考

  • DOMParentNode::prepend() - 最初の子ノードの前にノードを追加する
  • DOMDocument::append() - 最後の子ノードの後ろにノードを追加する


基底ノード型を作成する際に使用する拡張クラスを登録する

  • ≪ DOMDocument::prepend
  • DOMDocument::relaxNGValidate ≫
  • PHP Manual
  • DOMDocument
  • 基底ノード型を作成する際に使用する拡張クラスを登録する

DOMDocument::registerNodeClass

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DOMDocument::registerNodeClass — 基底ノード型を作成する際に使用する拡張クラスを登録する

説明

public DOMDocument::registerNodeClass(string $baseClass, ?string $extendedClass): bool

このメソッドにより、独自に拡張した DOM クラスを登録することができます。 これを、後で PHP DOM 拡張モジュールで使用します。

このメソッドは、DOM の標準にはないものです。

警告

登録済みのクラスの、インスタンスのコンストラクタはコールされません。

パラメータ

baseClass

拡張したい DOM クラス。クラス名の一覧は、 この章の導入部にあります。

extendedClass

拡張したクラスの名前。null を渡した場合は、 それまでに baseClass を拡張して作成したすべてのクラスが削除されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 新しいメソッドを DOMElement に追加し、コードを書きやすくする

<?php

class myElement extends DOMElement {
function appendElement($name) {
return $this->appendChild(new myElement($name));
}
}

class myDocument extends DOMDocument {
function setRoot($name) {
return $this->appendChild(new myElement($name));
}
}

$doc = new myDocument();
$doc->registerNodeClass('DOMElement', 'myElement');

// これ以降、他の要素への要素の追加が一回のメソッドコールでできるようになります!
$root = $doc->setRoot('root');
$child = $root->appendElement('child');
$child->setAttribute('foo', 'bar');

echo $doc->saveXML();

?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<root><child foo="bar"/></root>

例2 カスタムクラス形式での要素の取得

<?php
class myElement extends DOMElement {
public function __toString() {
return $this->nodeValue;
}
}

$doc = new DOMDocument;
$doc->loadXML("<root><element><child>text in child</child></element></root>");
$doc->registerNodeClass("DOMElement", "myElement");

$element = $doc->getElementsByTagName("child")->item(0);
var_dump(get_class($element));

// __toString メソッドの助けを借ります..
echo $element;
?>

上の例の出力は以下となります。

string(9) "myElement"
text in child

例3 オーナードキュメントの取得

自作の DOMDocument インスタンスを作成すると、 ownerDocument プロパティが作成元のクラスを指すようになります。 しかし、そのクラスへの参照が全て削除されると、 そのクラスは削除され、新しい DOMDocument が代わりに作成されます。よって、 DOMDocument::registerNodeClass() を、 DOMDocument と一緒に使うことができます。

<?php
class MyDOMDocument extends DOMDocument {
}

class MyOtherDOMDocument extends DOMDocument {
}

// XML から myDOMDocument を作成します
$doc = new MyDOMDocument;
$doc->loadXML("<root><element><child>text in child</child></element></root>");

$child = $doc->getElementsByTagName("child")->item(0);

// このノードの現在のオーナーは myDOMDocument です
var_dump(get_class($child->ownerDocument));
// MyDOMDocument を破棄します
unset($doc);
// そして新しい DOMDocument が作成されます
var_dump(get_class($child->ownerDocument));

// MyDOMDocument からノードを import します
$newdoc = new MyOtherDOMDocument;
$child = $newdoc->importNode($child);

// カスタムの DOMDocument を登録します
$newdoc->registerNodeClass("DOMDocument", "MyOtherDOMDocument");

var_dump(get_class($child->ownerDocument));
unset($doc);
// 新しい MyOtherDOMDocument を作成します
var_dump(get_class($child->ownerDocument));
?>

上の例の出力は以下となります。

string(13) "MyDOMDocument"
string(11) "DOMDocument"
string(18) "MyOtherDOMDocument"
string(18) "MyOtherDOMDocument"

例4 カスタムオブジェクトは一時的なもの

警告

登録されたノードクラスは、一時的なものです。 つまり、PHPコードから参照されなくなった時には破棄され、 再度取得される際に再生成されます。 これは、カスタムプロパティの値は再生成された時に失われるということです。

<?php
class MyDOMElement extends DOMElement
{
public $myProp = 'default value';
}

$doc = new DOMDocument();
$doc->registerNodeClass('DOMElement', 'MyDOMElement');

$node = $doc->createElement('a');
$node->myProp = 'modified value';
$doc->appendChild($node);

echo $doc->childNodes[0]->myProp, PHP_EOL;
unset($node);
echo $doc->childNodes[0]->myProp, PHP_EOL;
?>

上の例の出力は以下となります。

modified value
default value


ドキュメントを relaxNG で検証する

  • ≪ DOMDocument::registerNodeClass
  • DOMDocument::relaxNGValidateSource ≫
  • PHP Manual
  • DOMDocument
  • ドキュメントを relaxNG で検証する

DOMDocument::relaxNGValidate

(PHP 5, PHP 7, PHP 8)

DOMDocument::relaxNGValidate — ドキュメントを relaxNG で検証する

説明

public DOMDocument::relaxNGValidate(string $filename): bool

指定した RNG スキーマに基づいて、ドキュメントを » relaxNG で検証します。

パラメータ

filename

RNG ファイル。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMDocument::relaxNGValidateSource() - ドキュメントを relaxNG で検証する
  • DOMDocument::schemaValidate() - スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
  • DOMDocument::schemaValidateSource() - スキーマに基づいてドキュメントを検証する
  • DOMDocument::validate() - DTD に基づいてドキュメントを検証する


ドキュメントを relaxNG で検証する

  • ≪ DOMDocument::relaxNGValidate
  • DOMDocument::replaceChildren ≫
  • PHP Manual
  • DOMDocument
  • ドキュメントを relaxNG で検証する

DOMDocument::relaxNGValidateSource

(PHP 5, PHP 7, PHP 8)

DOMDocument::relaxNGValidateSource — ドキュメントを relaxNG で検証する

説明

public DOMDocument::relaxNGValidateSource(string $source): bool

指定した RNG ソースに基づいて、ドキュメントを » relaxNG で検証します。

パラメータ

source

RNG スキーマを含む文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMDocument::relaxNGValidate() - ドキュメントを relaxNG で検証する
  • DOMDocument::schemaValidate() - スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
  • DOMDocument::schemaValidateSource() - スキーマに基づいてドキュメントを検証する
  • DOMDocument::validate() - DTD に基づいてドキュメントを検証する


ドキュメントの子を置換する

  • ≪ DOMDocument::relaxNGValidateSource
  • DOMDocument::save ≫
  • PHP Manual
  • DOMDocument
  • ドキュメントの子を置換する

DOMDocument::replaceChildren

(PHP 8 >= 8.3.0)

DOMDocument::replaceChildren — ドキュメントの子を置換する

説明

public DOMDocument::replaceChildren(DOMNode|string ...$nodes): void

ドキュメント中の子を、新しい nodes で置換します。

パラメータ

nodes

子を置き換えるノード 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMDocument::replaceChildren() の例

子を新しいノードで置換します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><hello/></container>");

$doc->replaceWith("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
beautiful
<world/>

参考

  • DOMParentNode::replaceChildren() - ノード中の子を置換する
  • DOMDocument::append() - 最後の子ノードの後ろにノードを追加する
  • DOMDocument::prepend() - 最初の子ノードの前にノードを追加する


内部の XML ツリーをファイルに出力する

  • ≪ DOMDocument::replaceChildren
  • DOMDocument::saveHTML ≫
  • PHP Manual
  • DOMDocument
  • 内部の XML ツリーをファイルに出力する

DOMDocument::save

(PHP 5, PHP 7, PHP 8)

DOMDocument::save — 内部の XML ツリーをファイルに出力する

説明

public DOMDocument::save(string $filename, int $options = 0): int|false

DOM 表現から XML ドキュメントを作成します。この関数は、通常は以下の例のように DOM ドキュメントを新しく作成した後にコールされます。

パラメータ

filename

保存された XML ドキュメントへのパス。

options

追加のオプション。現在は LIBXML_NOEMPTYTAG のみが サポートされています。

戻り値

書き込んだバイト数、あるいはエラーが発生した場合は false を返します。

例

例1 DOM ツリーをファイルに保存する

<?php

$doc = new DOMDocument('1.0');
// 出力はきれいに整形したいですね。
$doc->formatOutput = true;

$root = $doc->createElement('book');
$root = $doc->appendChild($root);

$title = $doc->createElement('title');
$title = $root->appendChild($title);

$text = $doc->createTextNode('This is the title');
$text = $title->appendChild($text);

echo 'Wrote: ' . $doc->save("/tmp/test.xml") . ' bytes'; // Wrote: 72 bytes

?>

参考

  • DOMDocument::saveXML() - 内部の XML ツリーを文字列として出力する
  • DOMDocument::load() - ファイルから XML を読み込む
  • DOMDocument::loadXML() - 文字列から XML を読み込む


内部のドキュメントを HTML 形式の文字列として出力する

  • ≪ DOMDocument::save
  • DOMDocument::saveHTMLFile ≫
  • PHP Manual
  • DOMDocument
  • 内部のドキュメントを HTML 形式の文字列として出力する

DOMDocument::saveHTML

(PHP 5, PHP 7, PHP 8)

DOMDocument::saveHTML — 内部のドキュメントを HTML 形式の文字列として出力する

説明

public DOMDocument::saveHTML(?DOMNode $node = null): string|false

DOM 表現から HTML ドキュメントを作成します。この関数は、通常は以下の例のように DOM ドキュメントを新しく作成した後にコールされます。

パラメータ

node

ドキュメントのサブセットを出力するオプションのパラメータ。

戻り値

HTML、あるいはエラーが発生した場合は false を返します。

例

例1 HTML ツリーを文字列に保存する

<?php

$doc = new DOMDocument('1.0');

$root = $doc->createElement('html');
$root = $doc->appendChild($root);

$head = $doc->createElement('head');
$head = $root->appendChild($head);

$title = $doc->createElement('title');
$title = $head->appendChild($title);

$text = $doc->createTextNode('This is the title');
$text = $title->appendChild($text);

echo $doc->saveHTML();

?>

参考

  • DOMDocument::saveHTMLFile() - 内部のドキュメントを HTML 形式でファイルに出力する
  • DOMDocument::loadHTML() - 文字列から HTML を読み込む
  • DOMDocument::loadHTMLFile() - ファイルから HTML を読み込む


内部のドキュメントを HTML 形式でファイルに出力する

  • ≪ DOMDocument::saveHTML
  • DOMDocument::saveXML ≫
  • PHP Manual
  • DOMDocument
  • 内部のドキュメントを HTML 形式でファイルに出力する

DOMDocument::saveHTMLFile

(PHP 5, PHP 7, PHP 8)

DOMDocument::saveHTMLFile — 内部のドキュメントを HTML 形式でファイルに出力する

説明

public DOMDocument::saveHTMLFile(string $filename): int|false

DOM 表現から HTML ドキュメントを作成します。この関数は、通常は以下の例のように DOM ドキュメントを新しく作成した後にコールされます。

パラメータ

filename

保存された HTML ドキュメントへのパス。

戻り値

書き込んだバイト数、あるいはエラーが発生した場合は false を返します。

例

例1 HTML ツリーをファイルに保存する

<?php

$doc = new DOMDocument('1.0');
// 出力はきれいに整形したいですね。
$doc->formatOutput = true;

$root = $doc->createElement('html');
$root = $doc->appendChild($root);

$head = $doc->createElement('head');
$head = $root->appendChild($head);

$title = $doc->createElement('title');
$title = $head->appendChild($title);

$text = $doc->createTextNode('This is the title');
$text = $title->appendChild($text);

echo 'Wrote: ' . $doc->saveHTMLFile("/tmp/test.html") . ' bytes'; // Wrote: 129 bytes

?>

参考

  • DOMDocument::saveHTML() - 内部のドキュメントを HTML 形式の文字列として出力する
  • DOMDocument::loadHTML() - 文字列から HTML を読み込む
  • DOMDocument::loadHTMLFile() - ファイルから HTML を読み込む


内部の XML ツリーを文字列として出力する

  • ≪ DOMDocument::saveHTMLFile
  • DOMDocument::schemaValidate ≫
  • PHP Manual
  • DOMDocument
  • 内部の XML ツリーを文字列として出力する

DOMDocument::saveXML

(PHP 5, PHP 7, PHP 8)

DOMDocument::saveXML — 内部の XML ツリーを文字列として出力する

説明

public DOMDocument::saveXML(?DOMNode $node = null, int $options = 0): string|false

DOM 表現から XML ドキュメントを作成します。この関数は、通常は以下の例のように DOM ドキュメントを新しく作成した後にコールされます。

パラメータ

node

ドキュメント全体ではなく、XML 宣言以外の特定のノードだけを 出力したい場合にこのパラメータを使用します。

options

追加のオプション。LIBXML_NOEMPTYTAG と LIBXML_NOXMLDECL がサポートされています。 PHP 8.3.0 より前のバージョンでは、LIBXML_NOEMPTYTAG だけがサポートされていました。

戻り値

XML、あるいはエラーが発生した場合は false を返します。

エラー / 例外

DOM_WRONG_DOCUMENT_ERR

node が別のドキュメントのものである場合に 発生します。

変更履歴

バージョン | 説明
8.3.0 | LIBXML_NOXMLDECL がサポートされました。

例

例1 DOM ツリーを文字列に保存する

<?php

$doc = new DOMDocument('1.0');
// 出力はきれいに整形したいですね。
$doc->formatOutput = true;

$root = $doc->createElement('book');
$root = $doc->appendChild($root);

$title = $doc->createElement('title');
$title = $root->appendChild($title);

$text = $doc->createTextNode('これはタイトルです');
$text = $title->appendChild($text);

echo "ドキュメント全体を保存します\n";
echo $doc->saveXML() . "\n";

echo "タイトルの部分のみを保存します\n";
echo $doc->saveXML($title);

?>

上の例の出力は以下となります。

ドキュメント全体を保存します
<?xml version="1.0"?>
<book>
  <title>これはタイトルです</title>
</book>

タイトルの部分のみを保存します
<title>これはタイトルです</title>

参考

  • DOMDocument::save() - 内部の XML ツリーをファイルに出力する
  • DOMDocument::load() - ファイルから XML を読み込む
  • DOMDocument::loadXML() - 文字列から XML を読み込む


スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。

  • ≪ DOMDocument::saveXML
  • DOMDocument::schemaValidateSource ≫
  • PHP Manual
  • DOMDocument
  • スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。

DOMDocument::schemaValidate

(PHP 5, PHP 7, PHP 8)

DOMDocument::schemaValidate — スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。

説明

public DOMDocument::schemaValidate(string $filename, int $flags = 0): bool

指定されたスキーマファイルに基づいてドキュメントを検証します。

パラメータ

filename

スキーマへのパス。

flags

Libxml のスキーマ検証フラグのビットマスク。現在サポートしている値は LIBXML_SCHEMA_CREATE だけです。 Libxml 2.6.14 以降で使えます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMDocument::schemaValidateSource() - スキーマに基づいてドキュメントを検証する
  • DOMDocument::relaxNGValidate() - ドキュメントを relaxNG で検証する
  • DOMDocument::relaxNGValidateSource() - ドキュメントを relaxNG で検証する
  • DOMDocument::validate() - DTD に基づいてドキュメントを検証する


スキーマに基づいてドキュメントを検証する

  • ≪ DOMDocument::schemaValidate
  • DOMDocument::validate ≫
  • PHP Manual
  • DOMDocument
  • スキーマに基づいてドキュメントを検証する

DOMDocument::schemaValidateSource

(PHP 5, PHP 7, PHP 8)

DOMDocument::schemaValidateSource — スキーマに基づいてドキュメントを検証する

説明

public DOMDocument::schemaValidateSource(string $source, int $flags = 0): bool

指定した文字列に定義されているスキーマに基づいてドキュメントを検証します。

パラメータ

source

スキーマを含む文字列。

flags

Libxml のスキーマ検証フラグのビットマスク。現在サポートしている値は LIBXML_SCHEMA_CREATE だけです。 Libxml 2.6.14 以降で使えます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMDocument::schemaValidate() - スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
  • DOMDocument::relaxNGValidate() - ドキュメントを relaxNG で検証する
  • DOMDocument::relaxNGValidateSource() - ドキュメントを relaxNG で検証する
  • DOMDocument::validate() - DTD に基づいてドキュメントを検証する


DTD に基づいてドキュメントを検証する

  • ≪ DOMDocument::schemaValidateSource
  • DOMDocument::xinclude ≫
  • PHP Manual
  • DOMDocument
  • DTD に基づいてドキュメントを検証する

DOMDocument::validate

(PHP 5, PHP 7, PHP 8)

DOMDocument::validate — DTD に基づいてドキュメントを検証する

説明

public DOMDocument::validate(): bool

DTD に基づいてドキュメントを検証します。

DTD による検証を行うには、DOMDocument の validateOnParse プロパティを使用することも可能です。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。 ドキュメントに DTD が添付されていない場合は、このメソッドは false を返します。

例

例1 DTD による検証の例

<?php
$dom = new DOMDocument;
$dom->load('book.xml');
if ($dom->validate()) {
echo "このドキュメントは正常です!\n";
}
?>

XML ファイルの読み込み時に検証することも可能です。

<?php
$dom = new DOMDocument;
$dom->validateOnParse = true;
$dom->load('book.xml');
?>

参考

  • DOMDocument::schemaValidate() - スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
  • DOMDocument::schemaValidateSource() - スキーマに基づいてドキュメントを検証する
  • DOMDocument::relaxNGValidate() - ドキュメントを relaxNG で検証する
  • DOMDocument::relaxNGValidateSource() - ドキュメントを relaxNG で検証する


DOMDocument オブジェクト内の XIncludes を置換する

  • ≪ DOMDocument::validate
  • DOMDocumentFragment ≫
  • PHP Manual
  • DOMDocument
  • DOMDocument オブジェクト内の XIncludes を置換する

DOMDocument::xinclude

(PHP 5, PHP 7, PHP 8)

DOMDocument::xinclude — DOMDocument オブジェクト内の XIncludes を置換する

説明

public DOMDocument::xinclude(int $options = 0): int|false

このメソッドは、DOMDocument オブジェクト内の » XIncludes を置換します。

注意:

include される XML ファイルに DTD が添付されている場合は libxml2 が自動的にエンティティを解決するため、 このメソッドは予期せぬ結果を引き起こすことがあります。

パラメータ

options

追加の Libxml パラメータ を、ビット演算子の OR で指定します。

戻り値

ドキュメント内の XIncludes の数を返します。 何かの処理に失敗した場合は -1、 置換が発生しなかった場合は false を返します。

例

例1 DOMDocument::xinclude() の例

<?php

$xml = <<<EOD
<?xml version="1.0" ?>
<chapter xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Books of the other guy..</title>
<para>
<xi:include href="book.xml">
<xi:fallback>
<error>xinclude: book.xml not found</error>
</xi:fallback>
</xi:include>
</para>
</chapter>
EOD;

$dom = new DOMDocument;

// 見た目をきれいにします
$dom->preserveWhiteSpace = false;
$dom->formatOutput = true;

// 上で定義した XML 文字列を読み込みます
$dom->loadXML($xml);

// xincludes を置換します
$dom->xinclude();

echo $dom->saveXML();

?>

上の例の出力は、 たとえば以下のようになります。

<?xml version="1.0"?>
<chapter xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Books of the other guy..</title>
  <para>
    <row xml:base="/home/didou/book.xml">
       <entry>The Grapes of Wrath</entry>
       <entry>John Steinbeck</entry>
       <entry>en</entry>
       <entry>0140186409</entry>
      </row>
    <row xml:base="/home/didou/book.xml">
       <entry>The Pearl</entry>
       <entry>John Steinbeck</entry>
       <entry>en</entry>
       <entry>014017737X</entry>
      </row>
    <row xml:base="/home/didou/book.xml">
       <entry>Samarcande</entry>
       <entry>Amine Maalouf</entry>
       <entry>fr</entry>
       <entry>2253051209</entry>
      </row>
  </para>
</chapter>


DOMDocumentFragment クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMDocumentFragment extends DOMNode implements DOMParentNode {
/* プロパティ */
public readonly ?DOMElement $firstElementChild;
public readonly ?DOMElement $lastElementChild;
public readonly int $childElementCount;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct()
public append(DOMNode|string ...$nodes): void
public appendXML(string $data): bool
public prepend(DOMNode|string ...$nodes): void
public replaceChildren(DOMNode|string ...$nodes): void
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

childElementCount

子要素の数。

firstElementChild

最初の子要素。存在しない場合は null になります。

lastElementChild

最後の子要素。存在しない場合は null になります。

変更履歴

バージョン | 説明
8.0.0 | プロパティ firstElementChild, lastElementChild, childElementCount が追加されました。
8.0.0 | DOMDocumentFragment は、 DOMParentNode を実装しました。

目次

  • DOMDocumentFragment::append — 最後の子ノードの後ろにノードを追加する
  • DOMDocumentFragment::appendXML — 生の XML データを追加する
  • DOMDocumentFragment::__construct — DOMDocumentFragment オブジェクトを構築する
  • DOMDocumentFragment::prepend — 最初の子ノードの前にノードを追加する
  • DOMDocumentFragment::replaceChildren — 文書片の子を置換する


最後の子ノードの後ろにノードを追加する

  • ≪ DOMDocumentFragment
  • DOMDocumentFragment::appendXML ≫
  • PHP Manual
  • DOMDocumentFragment
  • 最後の子ノードの後ろにノードを追加する

DOMDocumentFragment::append

(PHP 8)

DOMDocumentFragment::append — 最後の子ノードの後ろにノードを追加する

説明

public DOMDocumentFragment::append(DOMNode|string ...$nodes): void

ひとつ以上の nodes を、子のリストに追加します。 追加されるのは、最後の子ノードの後ろになります。

パラメータ

nodes

追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMDocumentFragment::append() の例

文書片にノードを追加します。

<?php
$doc = new DOMDocument;
$fragment = $doc->createDocumentFragment();
$fragment->appendChild($doc->createElement("hello"));

$fragment->append("beautiful", $doc->createElement("world"));

echo $doc->saveXML($fragment);
?>

上の例の出力は以下となります。

<hello/>beautiful<world/>

参考

  • DOMParentNode::append() - 最後の子ノードの後ろにノードを追加する
  • DOMDocumentFragment::prepend() - 最初の子ノードの前にノードを追加する


生の XML データを追加する

  • ≪ DOMDocumentFragment::append
  • DOMDocumentFragment::__construct ≫
  • PHP Manual
  • DOMDocumentFragment
  • 生の XML データを追加する

DOMDocumentFragment::appendXML

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

DOMDocumentFragment::appendXML — 生の XML データを追加する

説明

public DOMDocumentFragment::appendXML(string $data): bool

生の XML データを DOMDocumentFragment に追加します。

このメソッドは、DOM の標準にはないものです。 これは、XML DocumentFragment を DOMDocument に簡単に追加できるように作成されました。

標準に従いたい場合は、まずテンポラリの DOMDocument をダミーのルートで作成し、 追加したい XML データのルートの子ノードを順にループする必要があります。

パラメータ

data

追加する XML。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 XML データのドキュメントへの追加

<?php
$doc = new DOMDocument();
$doc->loadXML("<root/>");
$f = $doc->createDocumentFragment();
$f->appendXML("<foo>text</foo><bar>text2</bar>");
$doc->documentElement->appendChild($f);
echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<root><foo>text</foo><bar>text2</bar></root>


DOMDocumentFragment オブジェクトを構築する

  • ≪ DOMDocumentFragment::appendXML
  • DOMDocumentFragment::prepend ≫
  • PHP Manual
  • DOMDocumentFragment
  • DOMDocumentFragment オブジェクトを構築する

DOMDocumentFragment::__construct

(PHP 5, PHP 7, PHP 8)

DOMDocumentFragment::__construct — DOMDocumentFragment オブジェクトを構築する

説明

public DOMDocumentFragment::__construct()

パラメータ

この関数にはパラメータはありません。


最初の子ノードの前にノードを追加する

  • ≪ DOMDocumentFragment::__construct
  • DOMDocumentFragment::replaceChildren ≫
  • PHP Manual
  • DOMDocumentFragment
  • 最初の子ノードの前にノードを追加する

DOMDocumentFragment::prepend

(PHP 8)

DOMDocumentFragment::prepend — 最初の子ノードの前にノードを追加する

説明

public DOMDocumentFragment::prepend(DOMNode|string ...$nodes): void

ひとつ以上の nodes を、子ノードのリストに追加します。 追加されるのは、最初の子ノードの前になります。

パラメータ

nodes

ノードの前に追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMDocumentFragment::prepend() の例

文書片のルートの前にノードを追加します。

<?php
$doc = new DOMDocument;
$fragment = $doc->createDocumentFragment();
$fragment->appendChild($doc->createElement("world"));

$fragment->prepend($doc->createElement("hello"), "beautiful");

echo $doc->saveXML($fragment);
?>

上の例の出力は以下となります。

<hello/>beautiful<world/>

参考

  • DOMParentNode::prepend() - 最初の子ノードの前にノードを追加する
  • DOMDocumentFragment::append() - 最後の子ノードの後ろにノードを追加する


文書片の子を置換する

  • ≪ DOMDocumentFragment::prepend
  • DOMDocumentType ≫
  • PHP Manual
  • DOMDocumentFragment
  • 文書片の子を置換する

DOMDocumentFragment::replaceChildren

(PHP 8 >= 8.3.0)

DOMDocumentFragment::replaceChildren — 文書片の子を置換する

説明

public DOMDocumentFragment::replaceChildren(DOMNode|string ...$nodes): void

文書片に含まれる子を、新しい nodes で置換します。

パラメータ

nodes

子を置き換えるノード 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMDocumentFragment::replaceChildren() の例

子を新しいノードで置換します

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><hello/></container>");
$fragment = $doc->createDocumentFragment();
$fragment->append("hello");

$fragment->replaceWith("beautiful", $doc->createElement("world"));

echo $doc->saveXML($fragment);
?>

上の例の出力は以下となります。

beautiful
<world/>

参考

  • DOMParentNode::replaceChildren() - ノード中の子を置換する
  • DOMDocumentFragment::append() - 最後の子ノードの後ろにノードを追加する
  • DOMDocumentFragment::prepend() - 最初の子ノードの前にノードを追加する


DOMDocumentType クラス

(PHP 5, PHP 7, PHP 8)

はじめに

各 DOMDocument は doctype 属性を保持しており、その値は null あるいは DOMDocumentType オブジェクトです。

クラス概要

class DOMDocumentType extends DOMNode {
/* プロパティ */
public readonly string $publicId;
public readonly string $systemId;
public readonly string $name;
public readonly DOMNamedNodeMap $entities;
public readonly DOMNamedNodeMap $notations;
public readonly string $internalSubset;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

publicId

外部サブセットの公開 ID。

systemId

外部サブセットのシステム ID。完全 URI である場合とそうでない場合がある。

name

DTD の名前。すなわち、DOCTYPE キーワードに続く値。

entities

DTD で宣言されている一般エンティティ (外部・内部とも) を含む DOMNamedNodeMap。

notations

DTD で宣言されている記法を含む DOMNamedNodeMap。

internalSubset

内部サブセットを文字列として取得する。存在しない場合は null となる。区切りの角括弧は含まない。


DOMElement クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMElement extends DOMNode implements DOMParentNode, DOMChildNode {
/* プロパティ */
public readonly string $tagName;
public string $className;
public string $id;
public readonly mixed $schemaTypeInfo = null;
public readonly ?DOMElement $firstElementChild;
public readonly ?DOMElement $lastElementChild;
public readonly int $childElementCount;
public readonly ?DOMElement $previousElementSibling;
public readonly ?DOMElement $nextElementSibling;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $qualifiedName, ?string $value = null, string $namespace = "")
public after(DOMNode|string ...$nodes): void
public append(DOMNode|string ...$nodes): void
public before(DOMNode|string ...$nodes): void
public getAttribute(string $qualifiedName): string
public getAttributeNames(): array
public getAttributeNode(string $qualifiedName): DOMAttr|DOMNameSpaceNode|false
public getAttributeNodeNS(?string $namespace, string $localName): DOMAttr|DOMNameSpaceNode|null
public getAttributeNS(?string $namespace, string $localName): string
public getElementsByTagName(string $qualifiedName): DOMNodeList
public getElementsByTagNameNS(?string $namespace, string $localName): DOMNodeList
public hasAttribute(string $qualifiedName): bool
public hasAttributeNS(?string $namespace, string $localName): bool
public insertAdjacentElement(string $where, DOMElement $element): ?DOMElement
public insertAdjacentText(string $where, string $data): void
public prepend(DOMNode|string ...$nodes): void
public remove(): void
public removeAttribute(string $qualifiedName): bool
public removeAttributeNode(DOMAttr $attr): DOMAttr|false
public removeAttributeNS(?string $namespace, string $localName): void
public replaceChildren(DOMNode|string ...$nodes): void
public replaceWith(DOMNode|string ...$nodes): void
public setAttribute(string $qualifiedName, string $value): DOMAttr|bool
public setAttributeNode(DOMAttr $attr): DOMAttr|null|false
public setAttributeNodeNS(DOMAttr $attr): DOMAttr|null|false
public setAttributeNS(?string $namespace, string $qualifiedName, string $value): void
public setIdAttribute(string $qualifiedName, bool $isId): void
public setIdAttributeNode(DOMAttr $attr, bool $isId): void
public setIdAttributeNS(string $namespace, string $qualifiedName, bool $isId): void
public toggleAttribute(string $qualifiedName, ?bool $force = null): bool
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

childElementCount

子要素の数。

firstElementChild

最初の子要素。存在しない場合は null になります。

lastElementChild

最後の子要素。存在しない場合は null になります。

nextElementSibling

次の兄弟要素。存在しない場合は null になります。

previousElementSibling

前の兄弟要素。存在しない場合は null になります。

schemaTypeInfo

未実装。常に null を返す。

tagName

要素名

className

スペースで分割された、要素のクラスを表す文字列

id

要素のID

変更履歴

バージョン | 説明
8.0.0 | プロパティ firstElementChild, lastElementChild, childElementCount, previousElementSibling, nextElementSibling が追加されました。
8.0.0 | DOMElement は、 DOMParentNode と DOMChildNode を実装しました。

注意

注意:

DOM拡張モジュール は UTF-8 エンコーディングを使います。他のエンコーディングを扱う場合は、mb_convert_encoding(), UConverter::transcode(), iconv() を使ってください。

目次

  • DOMElement::after — 要素の後ろにノードを追加する
  • DOMElement::append — 最後のノードの後ろにノードを追加する
  • DOMElement::before — 要素の前にノードを追加する
  • DOMElement::__construct — 新しい DOMElement オブジェクトを作成する
  • DOMElement::getAttribute — 属性の値を返す
  • DOMElement::getAttributeNames — 属性の名前を取得する
  • DOMElement::getAttributeNode — 属性ノードを返す
  • DOMElement::getAttributeNodeNS — 属性ノードを返す
  • DOMElement::getAttributeNS — 属性の値を返す
  • DOMElement::getElementsByTagName — タグ名から要素を取得する
  • DOMElement::getElementsByTagNameNS — 名前空間 URI とローカル名から要素を取得する
  • DOMElement::hasAttribute — 属性が存在するかどうかを調べる
  • DOMElement::hasAttributeNS — 属性が存在するかどうかを調べる
  • DOMElement::insertAdjacentElement — 隣接する要素を挿入する
  • DOMElement::insertAdjacentText — 隣接するテキストを挿入する
  • DOMElement::prepend — 最初の子ノードの前にノードを追加する
  • DOMElement::remove — 要素を削除する
  • DOMElement::removeAttribute — 属性を削除する
  • DOMElement::removeAttributeNode — 属性を削除する
  • DOMElement::removeAttributeNS — 属性を削除する
  • DOMElement::replaceChildren — 要素中の子を置換する
  • DOMElement::replaceWith — 要素を新しいノードで置換する
  • DOMElement::setAttribute — 属性を新しく追加する、または変更する
  • DOMElement::setAttributeNode — 新しい属性ノードを要素に追加する
  • DOMElement::setAttributeNodeNS — 新しい属性ノードを要素に追加する
  • DOMElement::setAttributeNS — 新しい属性を追加する
  • DOMElement::setIdAttribute — ID 型の属性を名前で宣言する
  • DOMElement::setIdAttributeNode — ID 型の属性をノードで宣言する
  • DOMElement::setIdAttributeNS — ID 型の属性をローカル名および名前空間 URI で宣言する
  • DOMElement::toggleAttribute — 属性の値を切り替える


要素の後ろにノードを追加する

  • ≪ DOMElement
  • DOMElement::append ≫
  • PHP Manual
  • DOMElement
  • 要素の後ろにノードを追加する

DOMElement::after

(PHP 8)

DOMElement::after — 要素の後ろにノードを追加する

説明

public DOMElement::after(DOMNode|string ...$nodes): void

渡された nodes を要素の後ろに追加します。

パラメータ

nodes

ノードの後ろに追加されるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMElement::after() の例

hello 要素の後ろにノードを追加します

<?php
$doc = new DOMDocument;
$doc->loadXML("<hello/>");
$container = $doc->documentElement;

$container->after("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<hello/>
beautiful
<world/>

参考

  • DOMChildNode::after() - ノードの後ろにノードを追加する
  • DOMElement::before() - 要素の前にノードを追加する


最後のノードの後ろにノードを追加する

  • ≪ DOMElement::after
  • DOMElement::before ≫
  • PHP Manual
  • DOMElement
  • 最後のノードの後ろにノードを追加する

DOMElement::append

(PHP 8)

DOMElement::append — 最後のノードの後ろにノードを追加する

説明

public DOMElement::append(DOMNode|string ...$nodes): void

ひとつ以上の nodes を子のリストに追加します。 追加されるのは、最後の子要素の後ろになります。

パラメータ

nodes

追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMElement::append() の例

container 要素の中に要素を追加します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container>hello </container>");
$world = $doc->documentElement;

$world->append("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container>hello beautiful<world/></container>

参考

  • DOMParentNode::append() - 最後の子ノードの後ろにノードを追加する
  • DOMElement::prepend() - 最初の子ノードの前にノードを追加する


要素の前にノードを追加する

  • ≪ DOMElement::append
  • DOMElement::__construct ≫
  • PHP Manual
  • DOMElement
  • 要素の前にノードを追加する

DOMElement::before

(PHP 8)

DOMElement::before — 要素の前にノードを追加する

説明

public DOMElement::before(DOMNode|string ...$nodes): void

渡された nodes を要素の前に追加します。

パラメータ

nodes

ノードの前に追加されるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMElement::before() の例

hello 要素の前にノードを追加します

<?php
$doc = new DOMDocument;
$doc->loadXML("<world/>");
$world = $doc->documentElement;

$world->before("hello", $doc->createElement("beautiful"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

hello
<beautiful/>
<world/>

参考

  • DOMChildNode::before() - ノードの前にノードを追加する
  • DOMElement::after() - 要素の後ろにノードを追加する


新しい DOMElement オブジェクトを作成する

  • ≪ DOMElement::before
  • DOMElement::getAttribute ≫
  • PHP Manual
  • DOMElement
  • 新しい DOMElement オブジェクトを作成する

DOMElement::__construct

(PHP 5, PHP 7, PHP 8)

DOMElement::__construct — 新しい DOMElement オブジェクトを作成する

説明

public DOMElement::__construct(string $qualifiedName, ?string $value = null, string $namespace = "")

新しい DOMElement オブジェクトを作成します。 このオブジェクトは読み込み専用です。このオブジェクトをドキュメントに 追加することが可能ですが、ノードがドキュメントに関連付けられるまでは ノードを追加することはできません。書き込み可能なノードを作成するには、 DOMDocument::createElement あるいは DOMDocument::createElementNS を使用します。

パラメータ

qualifiedName

要素のタグ名。namespaceURI をともに指定した場合、 この URI に関連付けられたプレフィックスが与えられます。

value

要素の値。

namespace

指定した名前空間の中で要素を作成するための 名前空間 URI。

例

例1 新しい DOMElement を作成する

<?php

$dom = new DOMDocument('1.0', 'iso-8859-1');
$element = $dom->appendChild(new DOMElement('root'));
$element_ns = new DOMElement('pr:node1', 'thisvalue', 'http://xyz');
$element->appendChild($element_ns);
echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?>
<root><pr:node1 xmlns:pr="http://xyz">thisvalue</pr:node1></root> */

?>

参考

  • DOMDocument::createElement() - 新しい要素ノードを作成する
  • DOMDocument::createElementNS() - 関連付けられた名前空間に新しい要素を作成する


属性の値を返す

  • ≪ DOMElement::__construct
  • DOMElement::getAttributeNames ≫
  • PHP Manual
  • DOMElement
  • 属性の値を返す

DOMElement::getAttribute

(PHP 5, PHP 7, PHP 8)

DOMElement::getAttribute — 属性の値を返す

説明

public DOMElement::getAttribute(string $qualifiedName): string

現在のノードから、名前が qualifiedName である属性の値を取得します。

パラメータ

qualifiedName

属性の名前。

戻り値

属性の値、あるいは qualifiedName に対応する属性が 見つからなかった場合には空の文字列を返します。

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::setAttribute() - 属性を新しく追加する、または変更する
  • DOMElement::removeAttribute() - 属性を削除する


属性の名前を取得する

  • ≪ DOMElement::getAttribute
  • DOMElement::getAttributeNode ≫
  • PHP Manual
  • DOMElement
  • 属性の名前を取得する

DOMElement::getAttributeNames

(PHP 8 >= 8.3.0)

DOMElement::getAttributeNames — 属性の名前を取得する

説明

public DOMElement::getAttributeNames(): array

属性の名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

属性の名前を返します。

例

例1 DOMElement::getAttributeNames() の例

<?php

$dom = new DOMDocument();
$dom->loadXML('<html xmlns:some="some:ns" some:test="a" test2="b"/>');
var_dump($dom->documentElement->getAttributeNames());
?>

上の例の出力は以下となります。

array(3) {
 [0]=>
 string(10) "xmlns:some"
 [1]=>
 string(9) "some:test"
 [2]=>
 string(5) "test2"
}


属性ノードを返す

  • ≪ DOMElement::getAttributeNames
  • DOMElement::getAttributeNodeNS ≫
  • PHP Manual
  • DOMElement
  • 属性ノードを返す

DOMElement::getAttributeNode

(PHP 5, PHP 7, PHP 8)

DOMElement::getAttributeNode — 属性ノードを返す

説明

public DOMElement::getAttributeNode(string $qualifiedName): DOMAttr|DOMNameSpaceNode|false

現在の要素の、qualifiedName という名前の属性ノードを返します。

パラメータ

qualifiedName

属性の名前。

戻り値

属性ノードを返します。 XML の名前空間宣言 (xmlns や xmlns:* 属性) については、 DOMAttr オブジェクトではなく、 DOMNameSpaceNode が返されることに注意してください。

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::setAttributeNode() - 新しい属性ノードを要素に追加する
  • DOMElement::removeAttributeNode() - 属性を削除する


属性ノードを返す

  • ≪ DOMElement::getAttributeNode
  • DOMElement::getAttributeNS ≫
  • PHP Manual
  • DOMElement
  • 属性ノードを返す

DOMElement::getAttributeNodeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::getAttributeNodeNS — 属性ノードを返す

説明

public DOMElement::getAttributeNodeNS(?string $namespace, string $localName): DOMAttr|DOMNameSpaceNode|null

現在のノードの、名前空間 namespaceにおける localName というローカル名の属性ノードを返します。

パラメータ

namespace

名前空間 URI。

localName

ローカル名。

戻り値

属性ノードを返します。 XML の名前空間宣言 (xmlns や xmlns:* 属性) については、 DOMAttr オブジェクトではなく、 DOMNameSpaceNode が返されることに注意してください。

参考

  • DOMElement::hasAttributeNS() - 属性が存在するかどうかを調べる
  • DOMElement::setAttributeNodeNS() - 新しい属性ノードを要素に追加する
  • DOMElement::removeAttributeNode() - 属性を削除する


属性の値を返す

  • ≪ DOMElement::getAttributeNodeNS
  • DOMElement::getElementsByTagName ≫
  • PHP Manual
  • DOMElement
  • 属性の値を返す

DOMElement::getAttributeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::getAttributeNS — 属性の値を返す

説明

public DOMElement::getAttributeNS(?string $namespace, string $localName): string

現在のノードから、名前空間 namespace における localName というローカル名の属性の値を取得します。

パラメータ

namespace

名前空間 URI。

localName

ローカル名。

戻り値

属性の値、あるいは localName および namespace に対応する属性が 見つからなかった場合には空の文字列を返します。

参考

  • DOMElement::hasAttributeNS() - 属性が存在するかどうかを調べる
  • DOMElement::setAttributeNS() - 新しい属性を追加する
  • DOMElement::removeAttributeNS() - 属性を削除する


タグ名から要素を取得する

  • ≪ DOMElement::getAttributeNS
  • DOMElement::getElementsByTagNameNS ≫
  • PHP Manual
  • DOMElement
  • タグ名から要素を取得する

DOMElement::getElementsByTagName

(PHP 5, PHP 7, PHP 8)

DOMElement::getElementsByTagName — タグ名から要素を取得する

説明

public DOMElement::getElementsByTagName(string $qualifiedName): DOMNodeList

この関数は、指定した名前 qualifiedName のタグを持つ すべての子孫要素からなるクラス DOMNodeList の新しいインスタンスを返します。要素は、ツリーをたどっていく際に 見つかった順に並べられます。

パラメータ

qualifiedName

タグ名。ツリー内のすべての要素を返すには * を使用します。

戻り値

この関数は、一致したすべての要素からなる DOMNodeList クラスのインスタンスを返します。

参考

  • DOMElement::getElementsByTagNameNS() - 名前空間 URI とローカル名から要素を取得する


名前空間 URI とローカル名から要素を取得する

  • ≪ DOMElement::getElementsByTagName
  • DOMElement::hasAttribute ≫
  • PHP Manual
  • DOMElement
  • 名前空間 URI とローカル名から要素を取得する

DOMElement::getElementsByTagNameNS

(PHP 5, PHP 7, PHP 8)

DOMElement::getElementsByTagNameNS — 名前空間 URI とローカル名から要素を取得する

説明

public DOMElement::getElementsByTagNameNS(?string $namespace, string $localName): DOMNodeList

この関数は、指定した名前 localName および namespace のタグを持つ すべての子孫要素を取得します。

パラメータ

namespace

条件に一致する要素の名前空間 URI。 "*" はすべての名前空間に一致します。 null を渡すと、空の名前空間に一致します。

localName

条件に一致する要素のローカル名。 "*" はすべてのローカル名に一致します。

戻り値

この関数は、一致したすべての要素からなる DOMNodeList クラスのインスタンスを返します。 各要素は、ツリー内の探索時に見つかった順で並べられます。

変更履歴

バージョン | 説明
8.0.3 | namespace は、nullable になりました。

参考

  • DOMElement::getElementsByTagName() - タグ名から要素を取得する


属性が存在するかどうかを調べる

  • ≪ DOMElement::getElementsByTagNameNS
  • DOMElement::hasAttributeNS ≫
  • PHP Manual
  • DOMElement
  • 属性が存在するかどうかを調べる

DOMElement::hasAttribute

(PHP 5, PHP 7, PHP 8)

DOMElement::hasAttribute — 属性が存在するかどうかを調べる

説明

public DOMElement::hasAttribute(string $qualifiedName): bool

要素のメンバとして qualifiedName という名前の属性が 存在するかどうかを示します。

パラメータ

qualifiedName

要素名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMElement::hasAttributeNS() - 属性が存在するかどうかを調べる
  • DOMElement::getAttribute() - 属性の値を返す
  • DOMElement::setAttribute() - 属性を新しく追加する、または変更する
  • DOMElement::removeAttribute() - 属性を削除する


属性が存在するかどうかを調べる

  • ≪ DOMElement::hasAttribute
  • DOMElement::insertAdjacentElement ≫
  • PHP Manual
  • DOMElement
  • 属性が存在するかどうかを調べる

DOMElement::hasAttributeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::hasAttributeNS — 属性が存在するかどうかを調べる

説明

public DOMElement::hasAttributeNS(?string $namespace, string $localName): bool

要素のメンバとして localName という名前の属性が 名前空間 namespace に存在するかどうかを示します。

パラメータ

namespace

名前空間 URI。

localName

ローカル名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::getAttributeNS() - 属性の値を返す
  • DOMElement::setAttributeNS() - 新しい属性を追加する
  • DOMElement::removeAttributeNS() - 属性を削除する


隣接する要素を挿入する

  • ≪ DOMElement::hasAttributeNS
  • DOMElement::insertAdjacentText ≫
  • PHP Manual
  • DOMElement
  • 隣接する要素を挿入する

DOMElement::insertAdjacentElement

(PHP 8 >= 8.3.0)

DOMElement::insertAdjacentElement — 隣接する要素を挿入する

説明

public DOMElement::insertAdjacentElement(string $where, DOMElement $element): ?DOMElement

where で指定された相対的な位置に、 要素を挿入します。

パラメータ

where

  • beforebegin - 目的の要素の直前に挿入します
  • afterbegin - 目的の要素の最初の子要素として挿入します
  • beforeend - 目的の要素の最後の子要素として挿入します
  • afterend - 目的の要素の直後に挿入します

element

挿入する要素

戻り値

DOMElement を返します。 失敗した場合は null を返します。

例

例1 DOMElement::insertAdjacentElement() の例

<?php

$dom = new DOMDocument();
$dom->loadXML('<?xml version="1.0"?><container><p>foo</p></container>');
$container = $dom->documentElement;
$p = $container->firstElementChild;

$p->insertAdjacentElement('beforebegin', $dom->createElement('A'));
echo $dom->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container><A/><p>foo</p></container>

参考

  • DOMElement::insertAdjacentText() - 隣接するテキストを挿入する


隣接するテキストを挿入する

  • ≪ DOMElement::insertAdjacentElement
  • DOMElement::prepend ≫
  • PHP Manual
  • DOMElement
  • 隣接するテキストを挿入する

DOMElement::insertAdjacentText

(PHP 8 >= 8.3.0)

DOMElement::insertAdjacentText — 隣接するテキストを挿入する

説明

public DOMElement::insertAdjacentText(string $where, string $data): void

where で指定された相対的な位置に、 テキストを挿入します。

パラメータ

where

  • beforebegin - 目的の要素の直前に挿入します
  • afterbegin - 目的の要素の最初の子要素として挿入します
  • beforeend - 目的の要素の最後の子要素として挿入します
  • afterend - 目的の要素の直後に挿入します

data

挿入する文字列

戻り値

値を返しません。

例

例1 DOMElement::insertAdjacentText() の例

<?php

$dom = new DOMDocument();
$dom->loadXML('<?xml version="1.0"?><container><p>H</p></container>');

$container = $dom->documentElement;
$p = $container->firstElementChild;

$p->insertAdjacentText("afterbegin", "P");
$p->insertAdjacentText("beforeend", "P");

echo $dom->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container><p>PHP</p></container>

参考

  • DOMElement::insertAdjacentElement() - 隣接する要素を挿入する


最初の子ノードの前にノードを追加する

  • ≪ DOMElement::insertAdjacentText
  • DOMElement::remove ≫
  • PHP Manual
  • DOMElement
  • 最初の子ノードの前にノードを追加する

DOMElement::prepend

(PHP 8)

DOMElement::prepend — 最初の子ノードの前にノードを追加する

説明

public DOMElement::prepend(DOMNode|string ...$nodes): void

ひとつ以上の nodes を、子のリストに追加します。 追加されるのは、最初の子ノードの前になります。

パラメータ

nodes

ノードの前に追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMElement::prepend() の例

container 要素の前にノードを追加します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container> world</container>");
$world = $doc->documentElement;

$world->prepend($doc->createElement("hello"), "beautiful");

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container><hello/>beautiful world</container>

参考

  • DOMParentNode::prepend() - 最初の子ノードの前にノードを追加する
  • DOMElement::append() - 最後のノードの後ろにノードを追加する


要素を削除する

  • ≪ DOMElement::prepend
  • DOMElement::removeAttribute ≫
  • PHP Manual
  • DOMElement
  • 要素を削除する

DOMElement::remove

(PHP 8)

DOMElement::remove — 要素を削除する

説明

public DOMElement::remove(): void

要素を削除します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 DOMElement::remove() の例

要素を削除します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><hello/><world/></container>");
$hello = $doc->documentElement->firstChild;

$hello->remove();

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container><world/></container>

参考

  • DOMElement::after() - 要素の後ろにノードを追加する
  • DOMElement::before() - 要素の前にノードを追加する
  • DOMElement::replaceWith() - 要素を新しいノードで置換する
  • DOMNode::removeChild() - 子要素群から子要素を削除する


属性を削除する

  • ≪ DOMElement::remove
  • DOMElement::removeAttributeNode ≫
  • PHP Manual
  • DOMElement
  • 属性を削除する

DOMElement::removeAttribute

(PHP 5, PHP 7, PHP 8)

DOMElement::removeAttribute — 属性を削除する

説明

public DOMElement::removeAttribute(string $qualifiedName): bool

qualifiedName という名前の属性を要素から削除します。

パラメータ

qualifiedName

属性の名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用の場合に発生します。

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::getAttribute() - 属性の値を返す
  • DOMElement::setAttribute() - 属性を新しく追加する、または変更する


属性を削除する

  • ≪ DOMElement::removeAttribute
  • DOMElement::removeAttributeNS ≫
  • PHP Manual
  • DOMElement
  • 属性を削除する

DOMElement::removeAttributeNode

(PHP 5, PHP 7, PHP 8)

DOMElement::removeAttributeNode — 属性を削除する

説明

public DOMElement::removeAttributeNode(DOMAttr $attr): DOMAttr|false

属性 attr を要素から削除します。

パラメータ

attr

属性ノード。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用の場合に発生します。

DOM_NOT_FOUND_ERR

attr が要素の属性でない場合に発生します。

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::getAttributeNode() - 属性ノードを返す
  • DOMElement::setAttributeNode() - 新しい属性ノードを要素に追加する


属性を削除する

  • ≪ DOMElement::removeAttributeNode
  • DOMElement::replaceChildren ≫
  • PHP Manual
  • DOMElement
  • 属性を削除する

DOMElement::removeAttributeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::removeAttributeNS — 属性を削除する

説明

public DOMElement::removeAttributeNS(?string $namespace, string $localName): void

名前空間 namespace にある localName という名前の属性を 要素から削除します。

パラメータ

namespace

名前空間 URI。

localName

ローカル名。

戻り値

値を返しません。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用の場合に発生します。

参考

  • DOMElement::hasAttributeNS() - 属性が存在するかどうかを調べる
  • DOMElement::getAttributeNS() - 属性の値を返す
  • DOMElement::setAttributeNS() - 新しい属性を追加する


要素中の子を置換する

  • ≪ DOMElement::removeAttributeNS
  • DOMElement::replaceWith ≫
  • PHP Manual
  • DOMElement
  • 要素中の子を置換する

DOMElement::replaceChildren

(PHP 8 >= 8.3.0)

DOMElement::replaceChildren — 要素中の子を置換する

説明

public DOMElement::replaceChildren(DOMNode|string ...$nodes): void

要素中の子を、新しい nodes で置換します。

パラメータ

nodes

子を置き換えるノード 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMElement::replaceChildren() の例

子を新しいノードで置換します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><hello/></container>");
$container = $doc->documentElement;

$container->replaceWith("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
beautiful
<world/>

参考

  • DOMParentNode::replaceChildren() - ノード中の子を置換する
  • DOMElement::replaceWith() - 要素を新しいノードで置換する
  • DOMElement::after() - 要素の後ろにノードを追加する
  • DOMElement::before() - 要素の前にノードを追加する
  • DOMElement::remove() - 要素を削除する


要素を新しいノードで置換する

  • ≪ DOMElement::replaceChildren
  • DOMElement::setAttribute ≫
  • PHP Manual
  • DOMElement
  • 要素を新しいノードで置換する

DOMElement::replaceWith

(PHP 8)

DOMElement::replaceWith — 要素を新しいノードで置換する

説明

public DOMElement::replaceWith(DOMNode|string ...$nodes): void

要素を新しい nodes で置換します。

パラメータ

nodes

置き換えるノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | 親がないノードに対して、 このメソッドをコールしても何もしなくなりました。 これは DOM の仕様が要求する振る舞いに合わせるためです。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMElement::replaceWith() の例

要素を新しいノードで置換します。

<?php
$doc = new DOMDocument;
$doc->loadXML("<container><hello/></container>");
$cdata = $doc->documentElement->firstChild;

$cdata->replaceWith("beautiful", $doc->createElement("world"));

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<container>beautiful<world/></container>

参考

  • DOMChildNode::replaceWith() - ノードを新しいノードで置き換える
  • DOMElement::replaceChildren() - 要素中の子を置換する
  • DOMElement::after() - 要素の後ろにノードを追加する
  • DOMElement::before() - 要素の前にノードを追加する
  • DOMElement::remove() - 要素を削除する


属性を新しく追加する、または変更する

  • ≪ DOMElement::replaceWith
  • DOMElement::setAttributeNode ≫
  • PHP Manual
  • DOMElement
  • 属性を新しく追加する、または変更する

DOMElement::setAttribute

(PHP 5, PHP 7, PHP 8)

DOMElement::setAttribute — 属性を新しく追加する、または変更する

説明

public DOMElement::setAttribute(string $qualifiedName, string $value): DOMAttr|bool

qualifiedName という名前の属性を、指定した値に設定します。 属性が存在しない場合は、作成されます。

パラメータ

qualifiedName

属性の名前。

value

属性の値。

戻り値

新しく作られた、または変更された DOMAttr を返します。 エラーが発生した場合は false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用の場合に発生します。

例

例1 属性を設定する

<?php
$doc = new DOMDocument("1.0");
$node = $doc->createElement("para");
$newnode = $doc->appendChild($node);
$newnode->setAttribute("align", "left");
?>

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::getAttribute() - 属性の値を返す
  • DOMElement::removeAttribute() - 属性を削除する


新しい属性ノードを要素に追加する

  • ≪ DOMElement::setAttribute
  • DOMElement::setAttributeNodeNS ≫
  • PHP Manual
  • DOMElement
  • 新しい属性ノードを要素に追加する

DOMElement::setAttributeNode

(PHP 5, PHP 7, PHP 8)

DOMElement::setAttributeNode — 新しい属性ノードを要素に追加する

説明

public DOMElement::setAttributeNode(DOMAttr $attr): DOMAttr|null|false

新しい属性ノード attr を要素に追加します。 要素に同じ名前の属性が既に存在している場合、 その属性は attr で置き換えられます。

パラメータ

attr

属性ノード。

戻り値

属性が置換された場合は置換前のノード、そうでない場合は null を返します。 DOM_WRONG_DOCUMENT_ERR エラーが発生した場合、 かつ strictErrorChecking が false の場合には、false を返します。

エラー / 例外

DOM_WRONG_DOCUMENT_ERR

attr が、要素とは異なるドキュメントに存在する場合に発生します。

参考

  • DOMElement::hasAttribute() - 属性が存在するかどうかを調べる
  • DOMElement::getAttributeNode() - 属性ノードを返す
  • DOMElement::removeAttributeNode() - 属性を削除する


新しい属性ノードを要素に追加する

  • ≪ DOMElement::setAttributeNode
  • DOMElement::setAttributeNS ≫
  • PHP Manual
  • DOMElement
  • 新しい属性ノードを要素に追加する

DOMElement::setAttributeNodeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::setAttributeNodeNS — 新しい属性ノードを要素に追加する

説明

public DOMElement::setAttributeNodeNS(DOMAttr $attr): DOMAttr|null|false

新しい属性ノード attr を要素に追加しますが、名前空間を考慮します。 要素に同じ名前の属性が既に存在している場合、 その属性は attr で置き換えられます。

パラメータ

attr

属性ノード。

戻り値

属性が置換された場合は置換前のノード、古い属性がない場合は null を返します。 DOM_WRONG_DOCUMENT_ERR エラーが発生した場合、 かつ strictErrorChecking が false の場合には、false を返します。

エラー / 例外

DOM_WRONG_DOCUMENT_ERR

attr が、要素とは異なるドキュメントに存在する場合に発生します。

参考

  • DOMElement::hasAttributeNS() - 属性が存在するかどうかを調べる
  • DOMElement::getAttributeNodeNS() - 属性ノードを返す
  • DOMElement::removeAttributeNode() - 属性を削除する


新しい属性を追加する

  • ≪ DOMElement::setAttributeNodeNS
  • DOMElement::setIdAttribute ≫
  • PHP Manual
  • DOMElement
  • 新しい属性を追加する

DOMElement::setAttributeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::setAttributeNS — 新しい属性を追加する

説明

public DOMElement::setAttributeNS(?string $namespace, string $qualifiedName, string $value): void

名前空間 namespace にある qualifiedName という名前の属性を、指定した値に設定します。 属性が存在しない場合は、作成されます。

パラメータ

namespace

名前空間 URI。

qualifiedName

prefix:tagname 形式で表した属性名。

value

属性の値。

戻り値

値を返しません。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用の場合に発生します。

DOM_NAMESPACE_ERR

qualifiedName が不正な形式であった場合や、 qualifiedName がプレフィックスを含むにもかかわらず namespace が null の場合に発生します。

参考

  • DOMElement::hasAttributeNS() - 属性が存在するかどうかを調べる
  • DOMElement::getAttributeNS() - 属性の値を返す
  • DOMElement::removeAttributeNS() - 属性を削除する


ID 型の属性を名前で宣言する

  • ≪ DOMElement::setAttributeNS
  • DOMElement::setIdAttributeNode ≫
  • PHP Manual
  • DOMElement
  • ID 型の属性を名前で宣言する

DOMElement::setIdAttribute

(PHP 5, PHP 7, PHP 8)

DOMElement::setIdAttribute — ID 型の属性を名前で宣言する

説明

public DOMElement::setIdAttribute(string $qualifiedName, bool $isId): void

ID 型となる属性を qualifiedName で宣言します。

パラメータ

qualifiedName

属性の名前。

isId

qualifiedName を ID 型にしたい場合に true、 それ以外の場合に false を設定します。

戻り値

値を返しません。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用である場合に発生します。

DOM_NOT_FOUND_ERR

qualifiedName がこの要素の属性でない場合に発生します。

参考

  • DOMDocument::getElementById() - id に対応する要素を検索する
  • DOMElement::setIdAttributeNode() - ID 型の属性をノードで宣言する
  • DOMElement::setIdAttributeNS() - ID 型の属性をローカル名および名前空間 URI で宣言する


ID 型の属性をノードで宣言する

  • ≪ DOMElement::setIdAttribute
  • DOMElement::setIdAttributeNS ≫
  • PHP Manual
  • DOMElement
  • ID 型の属性をノードで宣言する

DOMElement::setIdAttributeNode

(PHP 5, PHP 7, PHP 8)

DOMElement::setIdAttributeNode — ID 型の属性をノードで宣言する

説明

public DOMElement::setIdAttributeNode(DOMAttr $attr, bool $isId): void

ID 型となる属性 attr を宣言します。

パラメータ

attr

属性ノード。

isId

name を ID 型にしたい場合に true、 それ以外の場合に false を設定します。

戻り値

値を返しません。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用である場合に発生します。

DOM_NOT_FOUND_ERR

name がこの要素の属性でない場合に発生します。

参考

  • DOMDocument::getElementById() - id に対応する要素を検索する
  • DOMElement::setIdAttribute() - ID 型の属性を名前で宣言する
  • DOMElement::setIdAttributeNS() - ID 型の属性をローカル名および名前空間 URI で宣言する


ID 型の属性をローカル名および名前空間 URI で宣言する

  • ≪ DOMElement::setIdAttributeNode
  • DOMElement::toggleAttribute ≫
  • PHP Manual
  • DOMElement
  • ID 型の属性をローカル名および名前空間 URI で宣言する

DOMElement::setIdAttributeNS

(PHP 5, PHP 7, PHP 8)

DOMElement::setIdAttributeNS — ID 型の属性をローカル名および名前空間 URI で宣言する

説明

public DOMElement::setIdAttributeNS(string $namespace, string $qualifiedName, bool $isId): void

ID 型となる属性を qualifiedName および namespace で宣言します。

パラメータ

namespace

属性の名前空間 URI。

qualifiedName

属性のローカル名。prefix:tagname 形式。

isId

name を ID 型にしたい場合に true、 それ以外の場合に false を設定します。

戻り値

値を返しません。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用である場合に発生します。

DOM_NOT_FOUND_ERR

name がこの要素の属性でない場合に発生します。

参考

  • DOMDocument::getElementById() - id に対応する要素を検索する
  • DOMElement::setIdAttribute() - ID 型の属性を名前で宣言する
  • DOMElement::setIdAttributeNode() - ID 型の属性をノードで宣言する


属性の値を切り替える

  • ≪ DOMElement::setIdAttributeNS
  • DOMEntity ≫
  • PHP Manual
  • DOMElement
  • 属性の値を切り替える

DOMElement::toggleAttribute

(PHP 8 >= 8.3.0)

DOMElement::toggleAttribute — 属性の値を切り替える

説明

public DOMElement::toggleAttribute(string $qualifiedName, ?bool $force = null): bool

属性の値を切り替えます。

パラメータ

qualifiedName

属性の修飾名

force

  • null を指定すると、この関数は属性の値を切り替えます
  • true を指定すると、この関数は属性の値を追加します
  • false を指定すると、この関数は属性を削除します

戻り値

この関数をコールした後、属性が存在していれば true を返します。 そうでない場合、false を返します。

例

例1 DOMElement::toggleAttribute() の例

<?php

$dom = new DOMDocument();
$dom->loadXML("<?xml version='1.0'?><container selected=\"\"/>");

var_dump($dom->documentElement->toggleAttribute('selected'));
echo $dom->saveXML() . PHP_EOL;

var_dump($dom->documentElement->toggleAttribute('selected'));
echo $dom->saveXML();
?>

上の例の出力は以下となります。

bool(false)
<?xml version="1.0"?>
<container/>

bool(true)
<?xml version="1.0"?>
<container selected=""/>


DOMEntity クラス

(PHP 5, PHP 7, PHP 8)

はじめに

このインターフェイスは、XML ドキュメント内の既知のエンティティを表します。 パース済みかどうかは関係ありません。

クラス概要

class DOMEntity extends DOMNode {
/* プロパティ */
public readonly ?string $publicId;
public readonly ?string $systemId;
public readonly ?string $notationName;
public readonly ?string $actualEncoding = null;
public readonly ?string $encoding = null;
public readonly ?string $version = null;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

publicId

エンティティに関連付けられているパブリック ID が存在すればその値、 それ以外の場合は null

systemId

エンティティに関連付けられているシステム ID が存在すればその値、 それ以外の場合は null。これは完全な URI かもしれないし、 そうでないかもしれない。

notationName

パースされていないエンティティの場合はそのエンティティの名前、 パース済みのエンティティの場合は null

actualEncoding

外部でパースされたエンティティの場合は、このエンティティの パース時に使用されたエンコーディングを指定する属性。 内部サブセットからのエンティティであったり未知のエンティティで あった場合は null

encoding

外部でパースされたエンティティの場合は、テキスト宣言の一部として このエンティティのエンコーディングを指定する属性。それ以外の場合は null

version

外部でパースされたエンティティの場合は、テキスト宣言の一部として このエンティティのバージョン番号を指定する属性。それ以外の場合は null


DOMEntityReference クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMEntityReference extends DOMNode {
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $name)
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

目次

  • DOMEntityReference::__construct — 新しい DOMEntityReference オブジェクトを作成する


新しい DOMEntityReference オブジェクトを作成する

  • ≪ DOMEntityReference
  • DOMException ≫
  • PHP Manual
  • DOMEntityReference
  • 新しい DOMEntityReference オブジェクトを作成する

DOMEntityReference::__construct

(PHP 5, PHP 7, PHP 8)

DOMEntityReference::__construct — 新しい DOMEntityReference オブジェクトを作成する

説明

public DOMEntityReference::__construct(string $name)

新しい DOMEntityReference オブジェクトを作成します。

パラメータ

name

エンティティ参照の名前。

例

例1 新しい DOMEntityReference を作成する

<?php

$dom = new DOMDocument('1.0', 'iso-8859-1');
$element = $dom->appendChild(new DOMElement('root'));
$entity = $element->appendChild(new DOMEntityReference('nbsp'));
echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root>&nbsp;</root> */

?>

参考

  • DOMDocument::createEntityReference() - 新しいエンティティ参照ノードを作成する


DOMException クラス

(PHP 5, PHP 7, PHP 8)

はじめに

しかるべき状況、すなわち論理的に不可能な操作を行った際などの場合に DOM 操作は例外を発生させます。

例外(exceptions) も参照ください。

クラス概要

final class DOMException extends Exception {
/* プロパティ */
public int $code;
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}

プロパティ

code

発生したエラーの型を示す整数値


DOMImplementation クラス

(PHP 5, PHP 7, PHP 8)

はじめに

DOMImplementation クラスは、 個々のドキュメントオブジェクトモデルのインスタンス独自の操作を行うためのメソッド群を提供します。

クラス概要

class DOMImplementation {
/* メソッド */
public createDocument(?string $namespace = null, string $qualifiedName = "", ?DOMDocumentType $doctype = null): DOMDocument|false
public createDocumentType(string $qualifiedName, string $publicId = "", string $systemId = ""): DOMDocumentType|false
public hasFeature(string $feature, string $version): bool
}

目次

  • DOMImplementation::__construct — 新しい DOMImplementation オブジェクトを作成する
  • DOMImplementation::createDocument — 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する
  • DOMImplementation::createDocumentType — 空の DOMDocumentType オブジェクトを作成する
  • DOMImplementation::hasFeature — DOM 実装が、指定した機能を実装しているかどうかを調べる


新しい DOMImplementation オブジェクトを作成する

  • ≪ DOMImplementation
  • DOMImplementation::createDocument ≫
  • PHP Manual
  • DOMImplementation
  • 新しい DOMImplementation オブジェクトを作成する

DOMImplementation::__construct

(PHP 5, PHP 7)

DOMImplementation::__construct — 新しい DOMImplementation オブジェクトを作成する

説明

DOMImplementation::__construct()

新しい DOMImplementation オブジェクトを作成します。

パラメータ

この関数にはパラメータはありません。


指定した型とドキュメント要素の DOMDocument オブジェクトを作成する

  • ≪ DOMImplementation::__construct
  • DOMImplementation::createDocumentType ≫
  • PHP Manual
  • DOMImplementation
  • 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する

DOMImplementation::createDocument

(PHP 5, PHP 7, PHP 8)

DOMImplementation::createDocument — 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する

説明

public DOMImplementation::createDocument(?string $namespace = null, string $qualifiedName = "", ?DOMDocumentType $doctype = null): DOMDocument|false

指定した型とドキュメント要素の DOMDocument オブジェクトを作成します。

パラメータ

namespace

作成するドキュメント要素の名前空間 URI。

qualifiedName

作成するドキュメント要素の修飾名。

doctype

作成するドキュメントの型、あるいは null。

戻り値

新しい DOMDocument オブジェクトを返します。 エラーの場合は false を返します。 namespace、qualifiedName および doctype が null の場合は、 ドキュメント要素を含まない空の DOMDocument を返します。

エラー / 例外

DOM_WRONG_DOCUMENT_ERR

doctype が既に別のドキュメントで使用されていたり、 別の実装で作成されている場合に発生します。

DOM_NAMESPACE_ERR

namespace および qualifiedName で指定した名前空間に間違いがある場合に発生します。

変更履歴

バージョン | 説明
8.0.3 | namespace は、nullable になりました。
8.0.0 | doctype は、nullable になりました。
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

参考

  • DOMDocument::__construct() - 新しい DOMDocument オブジェクトを作成する
  • DOMImplementation::createDocumentType() - 空の DOMDocumentType オブジェクトを作成する


空の DOMDocumentType オブジェクトを作成する

  • ≪ DOMImplementation::createDocument
  • DOMImplementation::hasFeature ≫
  • PHP Manual
  • DOMImplementation
  • 空の DOMDocumentType オブジェクトを作成する

DOMImplementation::createDocumentType

(PHP 5, PHP 7, PHP 8)

DOMImplementation::createDocumentType — 空の DOMDocumentType オブジェクトを作成する

説明

public DOMImplementation::createDocumentType(string $qualifiedName, string $publicId = "", string $systemId = ""): DOMDocumentType|false

空の DOMDocumentType オブジェクトを作成します。 エンティティ宣言および記法は使用可能にはなりません。エンティティ参照の 展開やデフォルト属性の追加は発生しません。

パラメータ

qualifiedName

作成されるドキュメント型の修飾名。

publicId

外部サブセットの公開 ID。

systemId

外部サブセットのシステム ID。

戻り値

ownerDocument を null に設定した 新しい DOMDocumentType ノードを返します。 エラーの場合は false を返します。

エラー / 例外

DOM_NAMESPACE_ERR

qualifiedName で指定した名前空間に間違いがある場合に発生します。

変更履歴

バージョン | 説明
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

例

例1 DTD を添付してドキュメントを作成する

<?php

// DOMImplementation クラスのインスタンスを作成します
$imp = new DOMImplementation;

// DOMDocumentType のインスタンスを作成します
$dtd = $imp->createDocumentType('graph', '', 'graph.dtd');

// DOMDocument のインスタンスを作成します
$dom = $imp->createDocument("", "", $dtd);

// その他のプロパティを設定します
$dom->encoding = 'UTF-8';
$dom->standalone = false;

// 空の要素を作成します
$element = $dom->createElement('graph');

// 要素を追加します
$dom->appendChild($element);

// ドキュメントの内容を出力します
echo $dom->saveXML();

?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE graph SYSTEM "graph.dtd">
<graph/>

参考

  • DOMImplementation::createDocument() - 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する


DOM 実装が、指定した機能を実装しているかどうかを調べる

  • ≪ DOMImplementation::createDocumentType
  • DOMNamedNodeMap ≫
  • PHP Manual
  • DOMImplementation
  • DOM 実装が、指定した機能を実装しているかどうかを調べる

DOMImplementation::hasFeature

(PHP 5, PHP 7, PHP 8)

DOMImplementation::hasFeature — DOM 実装が、指定した機能を実装しているかどうかを調べる

説明

public DOMImplementation::hasFeature(string $feature, string $version): bool

DOM 実装が、指定した機能 feature を実装しているかどうかを調べます。

DOM 仕様の » Conformance の節に、すべての機能の一覧があります。

パラメータ

feature

調べる機能。

version

調べる feature のバージョン番号。 DOM level 2 においては、これは 2.0 あるいは 1.0 のいずれかです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数を static メソッドとしてコールすると、 Error がスローされるようになりました。 これより前のバージョンでは、 E_DEPRECATED が発生していました。

例

例1 DOM の実装を調べる

<?php

$features = array(
'Core' => 'Core module',
'XML' => 'XML module',
'HTML' => 'HTML module',
'Views' => 'Views module',
'Stylesheets' => 'Style Sheets module',
'CSS' => 'CSS module',
'CSS2' => 'CSS2 module',
'Events' => 'Events module',
'UIEvents' => 'User interface Events module',
'MouseEvents' => 'Mouse Events module',
'MutationEvents' => 'Mutation Events module',
'HTMLEvents' => 'HTML Events module',
'Range' => 'Range module',
'Traversal' => 'Traversal module'
);

$implementation = new DOMImplementation;

foreach ($features as $key => $name) {
if ($implementation->hasFeature($key, '2.0')) {
echo "$name の機能を保持しています\n";
} else {
echo "$name の機能は保持していません\n";
}
}

?>

参考

  • DOMNode::isSupported() - 指定したバージョンで機能がサポートされているかどうかを調べる


DOMNamedNodeMap クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMNamedNodeMap implements IteratorAggregate, Countable {
/* プロパティ */
public readonly int $length;
/* メソッド */
public count(): int
public getIterator(): Iterator
public getNamedItem(string $qualifiedName): ?DOMNode
public getNamedItemNS(?string $namespace, string $localName): ?DOMNode
public item(int $index): ?DOMNode
}

プロパティ

length

マップ内のノードの数。子ノードのインデックスとして有効な範囲は 0 から length - 1 まで (両端を含む) です。

変更履歴

バージョン | 説明
8.0.0 | 実装されていなかったメソッド DOMNamedNodeMap::setNamedItem(), DOMNamedNodeMap::removeNamedItem(), DOMNamedNodeMap::setNamedItemNS(), DOMNamedNodeMap::removeNamedItem() が削除されました。
8.0.0 | DOMNamedNodeMap は IteratorAggregate を実装しました。 これより前のバージョンでは、 Traversable が代わりに実装されていました。

目次

  • DOMNamedNodeMap::count — マップにあるノードの数を取得する
  • DOMNamedNodeMap::getIterator — 外部のイテレータを取得する
  • DOMNamedNodeMap::getNamedItem — 名前で指定されたノードを取得する
  • DOMNamedNodeMap::getNamedItemNS — ローカル名および名前空間 URI で指定したノードを取得する
  • DOMNamedNodeMap::item — インデックスで指定したノードを取得する


マップにあるノードの数を取得する

  • ≪ DOMNamedNodeMap
  • DOMNamedNodeMap::getIterator ≫
  • PHP Manual
  • DOMNamedNodeMap
  • マップにあるノードの数を取得する

DOMNamedNodeMap::count

(PHP 7 >= 7.2.0, PHP 8)

DOMNamedNodeMap::count — マップにあるノードの数を取得する

説明

public DOMNamedNodeMap::count(): int

マップにあるノードの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

マップにあるノードの数を返します。これは length プロパティと等しくなります。


外部のイテレータを取得する

  • ≪ DOMNamedNodeMap::count
  • DOMNamedNodeMap::getNamedItem ≫
  • PHP Manual
  • DOMNamedNodeMap
  • 外部のイテレータを取得する

DOMNamedNodeMap::getIterator

(PHP 8)

DOMNamedNodeMap::getIterator — 外部のイテレータを取得する

説明

public DOMNamedNodeMap::getIterator(): Iterator

名前付きノードのマップ向けに、外部のイテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Iterator あるいは Traversable を実装したオブジェクトのインスタンスを返します。

エラー / 例外

失敗した場合は Exception をスローします。

参考

  • IteratorAggregate::getIterator() - 外部イテレータを取得する


名前で指定されたノードを取得する

  • ≪ DOMNamedNodeMap::getIterator
  • DOMNamedNodeMap::getNamedItemNS ≫
  • PHP Manual
  • DOMNamedNodeMap
  • 名前で指定されたノードを取得する

DOMNamedNodeMap::getNamedItem

(PHP 5, PHP 7, PHP 8)

DOMNamedNodeMap::getNamedItem — 名前で指定されたノードを取得する

説明

public DOMNamedNodeMap::getNamedItem(string $qualifiedName): ?DOMNode

nodeName で指定されたノードを取得します。

パラメータ

qualifiedName

取得するノードの名前。

戻り値

指定した (任意の型の) nodeName のノード、 あるいはノードが見つからなかった場合には null を返します。

参考

  • DOMNamedNodeMap::getNamedItemNS() - ローカル名および名前空間 URI で指定したノードを取得する


ローカル名および名前空間 URI で指定したノードを取得する

  • ≪ DOMNamedNodeMap::getNamedItem
  • DOMNamedNodeMap::item ≫
  • PHP Manual
  • DOMNamedNodeMap
  • ローカル名および名前空間 URI で指定したノードを取得する

DOMNamedNodeMap::getNamedItemNS

(PHP 5, PHP 7, PHP 8)

DOMNamedNodeMap::getNamedItemNS — ローカル名および名前空間 URI で指定したノードを取得する

説明

public DOMNamedNodeMap::getNamedItemNS(?string $namespace, string $localName): ?DOMNode

localName および namespace で指定したノードを取得します。

パラメータ

namespace

取得するノードの名前空間 URI。

localName

取得するノードのローカル名。

戻り値

指定した (任意の型の) ローカル名および名前空間 URI のノード、 あるいはノードが見つからなかった場合には null を返します。

参考

  • DOMNamedNodeMap::getNamedItem() - 名前で指定されたノードを取得する


インデックスで指定したノードを取得する

  • ≪ DOMNamedNodeMap::getNamedItemNS
  • DOMNameSpaceNode ≫
  • PHP Manual
  • DOMNamedNodeMap
  • インデックスで指定したノードを取得する

DOMNamedNodeMap::item

(PHP 5, PHP 7, PHP 8)

DOMNamedNodeMap::item — インデックスで指定したノードを取得する

説明

public DOMNamedNodeMap::item(int $index): ?DOMNode

DOMNamedNodeMap オブジェクトから、 index で指定したノードを取得します。

パラメータ

index

マップ内のインデックス。

戻り値

マップ内の index 番目の位置にあるノード、 あるいはインデックスが不正な形式 (マップ内の要素数以上) の場合は null を返します。


DOMNameSpaceNode クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMNameSpaceNode {
/* プロパティ */
public readonly string $nodeName;
public readonly ?string $nodeValue;
public readonly int $nodeType;
public readonly string $prefix;
public readonly ?string $localName;
public readonly ?string $namespaceURI;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
}

プロパティ

nodeName

このノードの修飾名

nodeValue

このノードが宣言している名前空間URI。 名前空間が空の場合は、null

nodeType

ノードのタイプ。 XML_NAMESPACE_DECL_NODE になります。

prefix

このノードが宣言している名前空間のprefix

localName

このノードの修飾名のローカルパート

namespaceURI

このノードが宣言している名前空間URI。 未指定の場合は null

isConnected

ノードがドキュメントに接続しているかどうか

ownerDocument

このノードと関連がある DOMDocument。 このノードが DOMDocument でない場合は null

parentNode

このノードの親ノード。 該当するノードがない場合、null を返します。

parentElement

このノードの親要素。 該当するノードがない場合、null を返します。

変更履歴

バージョン | 説明
8.3.0 | DOMNameSpaceNode::$parentElement と DOMNameSpaceNode::$isConnected が追加されました。


DOMNode クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMNode {
/* プロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public appendChild(DOMNode $node): DOMNode|false
public C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public cloneNode(bool $deep = false): DOMNode|false
public contains(DOMNode|DOMNameSpaceNode|null $other): bool
public getLineNo(): int
public getNodePath(): ?string
public getRootNode(?array $options = null): DOMNode
public hasAttributes(): bool
public hasChildNodes(): bool
public insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public isDefaultNamespace(string $namespace): bool
public isEqualNode(?DOMNode $otherNode): bool
public isSameNode(DOMNode $otherNode): bool
public isSupported(string $feature, string $version): bool
public lookupNamespaceURI(?string $prefix): ?string
public lookupPrefix(string $namespace): ?string
public normalize(): void
public removeChild(DOMNode $child): DOMNode|false
public replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

nodeName

現在のノード型の正確な名前を返す

nodeValue

その型に応じてノードの値を返す。 W3C の仕様とは異なり、 DOMElement ノードの値は null ではなく DOMNode::textContent と等しくなる。

nodeType

ノードの型を、定義済みの定数 XML_xxx_NODE のいずれかで返す

parentNode

このノードの親 (存在しない場合は null) を返す

parentElement

この要素の親要素。存在しない場合は null を返す

childNodes

このノードのすべての子を含む DOMNodeList。 子が存在しない場合は、空の DOMNodeList

firstChild

このノードの最初の子。存在しない場合は null を返す

lastChild

このノードの最後の子。存在しない場合は null を返す

previousSibling

このノードの直前のノード。存在しない場合は null を返す

nextSibling

このノードの直後のノード。存在しない場合は null を返す

attributes

このノードが DOMElement の場合は ノードの属性を含む DOMNamedNodeMap、 それ以外の場合は null

isConnected

ノードが Document に接続されているかどうか

ownerDocument

このノードに関連付けられている DOMDocument オブジェクト このノードが DOMDocument だった場合は、null

namespaceURI

このノードの名前空間 URI。指定されていない場合は null

prefix

このノードの名前空間プレフィックス

localName

このノードの名前のローカル部分を返す

baseURI

このノードの完全なベース URI。もし実装が完全な URL を できなかった場合は null

textContent

このノードとその子孫ノードのテキスト

変更履歴

バージョン | 説明
8.3.0 | プロパティ DOMNode::$parentElement と DOMNode::$isConnected が追加されました。
8.0.0 | 実装されていなかったメソッド DOMNode::compareDocumentPosition(), DOMNode::isEqualNode(), DOMNode::getFeature(), DOMNode::setUserData(), DOMNode::getUserData() が削除されました。

注意

注意:

DOM拡張モジュール は UTF-8 エンコーディングを使います。他のエンコーディングを扱う場合は、mb_convert_encoding(), UConverter::transcode(), iconv() を使ってください。

参考

  • » W3C specification of Node

目次

  • DOMNode::appendChild — 子要素群の最後に新しい子要素を追加する
  • DOMNode::C14N — ノードを文字列に正規化する
  • DOMNode::C14NFile — ノードをファイルに正規化する
  • DOMNode::cloneNode — ノードを複製する
  • DOMNode::contains — ノードが別のノードを含んでいるかを調べる
  • DOMNode::getLineNo — ノードが存在する行の番号を取得します。
  • DOMNode::getNodePath — ノードの XPath を取得する
  • DOMNode::getRootNode — ルート(根)ノードを取得する
  • DOMNode::hasAttributes — ノードが属性を保持しているかどうかを調べる
  • DOMNode::hasChildNodes — ノードが子を保持しているかどうかを調べる
  • DOMNode::insertBefore — 参照しているノードの前に新しい子を追加する
  • DOMNode::isDefaultNamespace — 指定した namespaceURI がデフォルトの名前空間かどうかを調べる
  • DOMNode::isEqualNode — ノードが等しいかを調べる
  • DOMNode::isSameNode — 2 つのノードが等しいかどうかを調べる
  • DOMNode::isSupported — 指定したバージョンで機能がサポートされているかどうかを調べる
  • DOMNode::lookupNamespaceURI — プレフィックスに基づいて、ノードの名前空間 URI を取得する
  • DOMNode::lookupPrefix — 名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する
  • DOMNode::normalize — ノードを正規化する
  • DOMNode::removeChild — 子要素群から子要素を削除する
  • DOMNode::replaceChild — 子を置き換える


子要素群の最後に新しい子要素を追加する

  • ≪ DOMNode
  • DOMNode::C14N ≫
  • PHP Manual
  • DOMNode
  • 子要素群の最後に新しい子要素を追加する

DOMNode::appendChild

(PHP 5, PHP 7, PHP 8)

DOMNode::appendChild — 子要素群の最後に新しい子要素を追加する

説明

public DOMNode::appendChild(DOMNode $node): DOMNode|false

この関数は、既存の子要素のリストに新しい子要素を追加するか、 あるいは新しい子要素リストを作成します。子要素の作成には DOMDocument::createElement()、 DOMDocument::createTextNode() などを使用するか、単に別のノードを使用します。

既存のノードを使う場合、そのノードは移動します。

パラメータ

node

追加する子要素。

戻り値

追加したノードを返します。 エラーの場合は false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用であったり、挿入するノードの以前の親が 読み込み専用であったりした場合に発生します。

DOM_HIERARCHY_REQUEST_ERR

node で指定した型の子ノードを 保持することが許可されていない場合、あるいは追加しようとしている ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

node が、このノードとは別の ドキュメントで作成されたものである場合に発生します。

例

以下の例は、新しいドキュメントに新しい要素を追加します。

例1 子要素の追加

<?php

$doc = new DOMDocument;

$node = $doc->createElement("para");
$newnode = $doc->appendChild($node);

echo $doc->saveXML();
?>

例2 ネストされた子ノード

<?php

$doc = new DOMDocument;

$headNode = $doc->createElement("head");
$doc->appendChild($headNode);

$titleNode = $doc->createElement("title");
$headNode->appendChild($titleNode);

echo $doc->saveXML();
?>

参考

  • DOMChildNode::after() - ノードの後ろにノードを追加する
  • DOMNode::insertBefore() - 参照しているノードの前に新しい子を追加する
  • DOMNode::removeChild() - 子要素群から子要素を削除する
  • DOMNode::replaceChild() - 子を置き換える


ノードを文字列に正規化する

  • ≪ DOMNode::appendChild
  • DOMNode::C14NFile ≫
  • PHP Manual
  • DOMNode
  • ノードを文字列に正規化する

DOMNode::C14N

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DOMNode::C14N — ノードを文字列に正規化する

説明

public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false

ノードを文字列に正規化します。

パラメータ

exclusive

指定した xpath あるいは名前空間プレフィックスにマッチするノードだけを対象としたパースを有効にする。

withComments

コメントを残して出力する。

xpath

ノードをフィルタする XPath の配列。 この配列のそれぞれのエントリは、以下の情報を持つ連想配列です:

  • XPath の式の文字列を含む query キー。必須です。
  • 名前空間のプレフィックス(keys) を名前空間URI (values) にマップした配列を含む namespaces キー。オプションです。

nsPrefixes

ノードを絞り込むための名前空間プレフィックスの配列。

戻り値

正規化したノードを文字列で返します。 失敗した場合に false を返します

例

例1 XPath クエリの例

以下のコードは、XPath クエリを使ってノードをフィルタし、 正規化する高度なやり方を示します。

<?php
$dom = new DOMDocument();
$dom->loadXML(<<<XML
<root xmlns:food="urn:food">
<!-- redundant namespace declaration will be canonicalized -->
<food:fruit xmlns:food="urn:food">Apple</food:fruit>
<food:fruit>Orange</food:fruit>
<food:fruit>Pear</food:fruit>
<!-- vegetables here -->
<food:vegetable>Lettuce</food:vegetable>
</root>
XML);
echo $dom->C14N(true, false, [
"query" => ".//f:fruit|.//f:fruit/text()",
"namespaces" => ["f" => "urn:food"],
]);
?>

上の例の出力は以下となります。

<food:fruit>Apple</food:fruit><food:fruit>Orange</food:fruit><food:fruit>Pear</food:fruit>

参考

  • DOMNode::C14NFile() - ノードをファイルに正規化する


ノードをファイルに正規化する

  • ≪ DOMNode::C14N
  • DOMNode::cloneNode ≫
  • PHP Manual
  • DOMNode
  • ノードをファイルに正規化する

DOMNode::C14NFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DOMNode::C14NFile — ノードをファイルに正規化する

説明

public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false

ノードをファイルに正規化します。

パラメータ

uri

出力を書き出すパス。

exclusive

指定した xpath あるいは名前空間プレフィックスにマッチするノードだけを対象としたパースを有効にする。

withComments

コメントを残して出力する。

xpath

ノードをフィルタする XPath の配列。 この配列のそれぞれのエントリは、以下の情報を持つ連想配列です:

  • XPath の式の文字列を含む query キー。必須です。
  • 名前空間のプレフィックス(keys) を名前空間URI (values) にマップした配列を含む namespaces キー。オプションです。

nsPrefixes

ノードを絞り込むための名前空間プレフィックスの配列。

戻り値

書き込んだバイト数を返します。 失敗した場合に false を返します

参考

  • DOMNode::C14N() - ノードを文字列に正規化する


ノードを複製する

  • ≪ DOMNode::C14NFile
  • DOMNode::contains ≫
  • PHP Manual
  • DOMNode
  • ノードを複製する

DOMNode::cloneNode

(PHP 5, PHP 7, PHP 8)

DOMNode::cloneNode — ノードを複製する

説明

public DOMNode::cloneNode(bool $deep = false): DOMNode|false

ノードのコピーを作成します。

パラメータ

deep

子孫要素を含めてコピーするかどうかを指定します。 このパラメータのデフォルト値は false です。

戻り値

複製されたノードを返します。


ノードが別のノードを含んでいるかを調べる

  • ≪ DOMNode::cloneNode
  • DOMNode::getLineNo ≫
  • PHP Manual
  • DOMNode
  • ノードが別のノードを含んでいるかを調べる

DOMNode::contains

(PHP 8 >= 8.3.0)

DOMNode::contains — ノードが別のノードを含んでいるかを調べる

説明

public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool

ノードが other ノードを含んでいるかを調べます。

パラメータ

other

調べるノード

戻り値

ノードが other ノードを含んでいる場合 true を返します。そうでない場合に false を返します。

例

例1 DOMNode::contains() の例

<?php

$dom = new DOMDocument();
$dom->loadXML(<<<XML
<!DOCTYPE HTML>
<html>
<body>
<main>
<p>Hello, world!</p>
</main>
</body>
</html>
XML);

$xpath = new DOMXPath($dom);
$main = $xpath->query("//main")[0];

var_dump($dom->documentElement->contains($main));
?>

上の例の出力は以下となります。

bool(true)


ノードが存在する行の番号を取得します。

  • ≪ DOMNode::contains
  • DOMNode::getNodePath ≫
  • PHP Manual
  • DOMNode
  • ノードが存在する行の番号を取得します。

DOMNode::getLineNo

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DOMNode::getLineNo — ノードが存在する行の番号を取得します。

説明

public DOMNode::getLineNo(): int

パース時にノードが定義された行の番号を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

パース時にノードが定義された行の番号を返します。 ノードが手動で作成された場合、戻り値は 0 になります。

例

例1 DOMNode::getLineNo() メソッドの例

<?php
// 以下の例で使うXMLのダンプ
$xml = <<<XML
<?xml version="1.0" encoding="utf-8"?>
<root>
<node />
</root>
XML;

// DOMDocumentクラスのインスタンスを生成する
$dom = new DOMDocument;

// XMLをロードする
$dom->loadXML($xml);

// <node> 要素が定義された行がどこにあるかを表示する
printf('The <node> tag is defined on line %d', $dom->getElementsByTagName('node')->item(0)->getLineNo());
?>

上の例の出力は以下となります。

The <node> tag is defined in line 3


ノードの XPath を取得する

  • ≪ DOMNode::getLineNo
  • DOMNode::getRootNode ≫
  • PHP Manual
  • DOMNode
  • ノードの XPath を取得する

DOMNode::getNodePath

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DOMNode::getNodePath — ノードの XPath を取得する

説明

public DOMNode::getNodePath(): ?string

ノードの XPath ロケーションパスを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

XPath を含む文字列、あるいはエラー時に null を返します。

例

例1 DOMNode::getNodePath() の例

<?php
// 新しい DOMDocument インスタンスを作ります
$dom = new DOMDocument;

// XML を読み込みます
$dom->loadXML('
<fruits>
<apples>
<apple>braeburn</apple>
<apple>granny smith</apple>
</apples>
<pears>
<pear>conference</pear>
</pears>
</fruits>
');

// 各要素の XPath を表示します
foreach ($dom->getElementsByTagName('*') as $node) {
echo $node->getNodePath() . "\n";
}
?>

上の例の出力は以下となります。

/fruits
/fruits/apples
/fruits/apples/apple[1]
/fruits/apples/apple[2]
/fruits/pears
/fruits/pears/pear

参考

  • DOMXPath


ルート(根)ノードを取得する

  • ≪ DOMNode::getNodePath
  • DOMNode::hasAttributes ≫
  • PHP Manual
  • DOMNode
  • ルート(根)ノードを取得する

DOMNode::getRootNode

(PHP 8 >= 8.3.0)

DOMNode::getRootNode — ルート(根)ノードを取得する

説明

public DOMNode::getRootNode(?array $options = null): DOMNode

ルート(根)ノードを取得します。

パラメータ

options

このパラメータにはまだ意味がありません

戻り値

ルート(根)ノードを返します。

例

例1 DOMNode::getRootNode() の例

<?php

$dom = new DOMDocument();
$dom->loadXML('<?xml version="1.0"?><html><body/></html>');

var_dump($dom->documentElement->firstElementChild->getRootNode() === $dom);
?>

上の例の出力は以下となります。

bool(true)


ノードが属性を保持しているかどうかを調べる

  • ≪ DOMNode::getRootNode
  • DOMNode::hasChildNodes ≫
  • PHP Manual
  • DOMNode
  • ノードが属性を保持しているかどうかを調べる

DOMNode::hasAttributes

(PHP 5, PHP 7, PHP 8)

DOMNode::hasAttributes — ノードが属性を保持しているかどうかを調べる

説明

public DOMNode::hasAttributes(): bool

このメソッドは、ノードが属性を保持しているかどうかを調べます。 調べるノードは XML_ELEMENT_NODE である必要があります。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMNode::hasChildNodes() - ノードが子を保持しているかどうかを調べる


ノードが子を保持しているかどうかを調べる

  • ≪ DOMNode::hasAttributes
  • DOMNode::insertBefore ≫
  • PHP Manual
  • DOMNode
  • ノードが子を保持しているかどうかを調べる

DOMNode::hasChildNodes

(PHP 5, PHP 7, PHP 8)

DOMNode::hasChildNodes — ノードが子を保持しているかどうかを調べる

説明

public DOMNode::hasChildNodes(): bool

この関数は、ノードが子を保持しているかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMNode::hasAttributes() - ノードが属性を保持しているかどうかを調べる


参照しているノードの前に新しい子を追加する

  • ≪ DOMNode::hasChildNodes
  • DOMNode::isDefaultNamespace ≫
  • PHP Manual
  • DOMNode
  • 参照しているノードの前に新しい子を追加する

DOMNode::insertBefore

(PHP 5, PHP 7, PHP 8)

DOMNode::insertBefore — 参照しているノードの前に新しい子を追加する

説明

public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false

この関数は、参照しているノードの直前に新しいノードを挿入します。 追加するノードに対して変更を加えたい場合は、この関数から返される ノードを使用します。

既存のノードを使う場合、そのノードは移動します。

パラメータ

node

新しいノード。

child

参照ノード。指定されなかった場合は、node が子要素として追加されます。

戻り値

挿入されたノードを返します。 エラーの場合は false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

このノードが読み込み専用であったり、挿入されるノードの以前の親が 読み込み専用であった場合に発生します。

DOM_HIERARCHY_REQUEST_ERR

node で指定した型の子ノードを 保持することが許可されていない場合、あるいは追加しようとしている ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

node が、このノードとは別の ドキュメントで作成されたものである場合に発生します。

DOM_NOT_FOUND_ERR

child がこのノードの子ではない場合に 発生します。

参考

  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する


指定した namespaceURI がデフォルトの名前空間かどうかを調べる

  • ≪ DOMNode::insertBefore
  • DOMNode::isEqualNode ≫
  • PHP Manual
  • DOMNode
  • 指定した namespaceURI がデフォルトの名前空間かどうかを調べる

DOMNode::isDefaultNamespace

(PHP 5, PHP 7, PHP 8)

DOMNode::isDefaultNamespace — 指定した namespaceURI がデフォルトの名前空間かどうかを調べる

説明

public DOMNode::isDefaultNamespace(string $namespace): bool

namespace がデフォルトの名前空間であるかどうかを調べます。

パラメータ

namespace

調べる名前空間 URI。

戻り値

namespace がデフォルトの名前空間である場合に true、それ以外の場合に false を返します。


ノードが等しいかを調べる

  • ≪ DOMNode::isDefaultNamespace
  • DOMNode::isSameNode ≫
  • PHP Manual
  • DOMNode
  • ノードが等しいかを調べる

DOMNode::isEqualNode

(PHP 8 >= 8.3.0)

DOMNode::isEqualNode — ノードが等しいかを調べる

説明

public DOMNode::isEqualNode(?DOMNode $otherNode): bool

ノードが等しいかを調べます。

パラメータ

otherNode

ノード

戻り値

双方のノードが等しい場合 true を返します。 そうでない場合、false を返します。

例

例1 DOMNode::isEqualNode() の例

<?php

$dom1 = (new DOMDocument())->createElement('h1', 'Hello World!');
$dom2 = (new DOMDocument())->createElement('h1', 'Hello World!');

var_dump($dom1->isEqualNode($dom2));
?>

上の例の出力は以下となります。

bool(true)


2 つのノードが等しいかどうかを調べる

  • ≪ DOMNode::isEqualNode
  • DOMNode::isSupported ≫
  • PHP Manual
  • DOMNode
  • 2 つのノードが等しいかどうかを調べる

DOMNode::isSameNode

(PHP 5, PHP 7, PHP 8)

DOMNode::isSameNode — 2 つのノードが等しいかどうかを調べる

説明

public DOMNode::isSameNode(DOMNode $otherNode): bool

この関数は、2 つのノードが等しいかどうかを調べます。この比較は、 その内容に基づくものではありません。

パラメータ

otherNode

比較対象となるノード。

戻り値

成功した場合に true を、失敗した場合に false を返します。


指定したバージョンで機能がサポートされているかどうかを調べる

  • ≪ DOMNode::isSameNode
  • DOMNode::lookupNamespaceURI ≫
  • PHP Manual
  • DOMNode
  • 指定したバージョンで機能がサポートされているかどうかを調べる

DOMNode::isSupported

(PHP 5, PHP 7, PHP 8)

DOMNode::isSupported — 指定したバージョンで機能がサポートされているかどうかを調べる

説明

public DOMNode::isSupported(string $feature, string $version): bool

指定したバージョン version で、機能 feature がサポートされているかどうかを調べます。

パラメータ

feature

調べる機能。機能の一覧については DOMImplementation::hasFeature() の例を参照ください。

version

調べる機能 feature のバージョン番号。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • DOMImplementation::hasFeature() - DOM 実装が、指定した機能を実装しているかどうかを調べる


プレフィックスに基づいて、ノードの名前空間 URI を取得する

  • ≪ DOMNode::isSupported
  • DOMNode::lookupPrefix ≫
  • PHP Manual
  • DOMNode
  • プレフィックスに基づいて、ノードの名前空間 URI を取得する

DOMNode::lookupNamespaceURI

(PHP 5, PHP 7, PHP 8)

DOMNode::lookupNamespaceURI — プレフィックスに基づいて、ノードの名前空間 URI を取得する

説明

public DOMNode::lookupNamespaceURI(?string $prefix): ?string

prefix に基づいて、 ノードの名前空間 URI を取得します。

パラメータ

prefix

探す名前空間のプレフィックス。 null を指定した場合、デフォルトの名前空間URIを返します。 但し、存在する場合に限ります。

戻り値

関連する名前空間 URI を返します。 見つからなかった場合は null を返します。

参考

  • DOMNode::lookupPrefix() - 名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する


名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する

  • ≪ DOMNode::lookupNamespaceURI
  • DOMNode::normalize ≫
  • PHP Manual
  • DOMNode
  • 名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する

DOMNode::lookupPrefix

(PHP 5, PHP 7, PHP 8)

DOMNode::lookupPrefix — 名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する

説明

public DOMNode::lookupPrefix(string $namespace): ?string

名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得します。

パラメータ

namespace

名前空間 URI。

戻り値

名前空間のプレフィックスを返します。 エラーの場合は null を返します。

参考

  • DOMNode::lookupNamespaceUri() - プレフィックスに基づいて、ノードの名前空間 URI を取得する


ノードを正規化する

  • ≪ DOMNode::lookupPrefix
  • DOMNode::removeChild ≫
  • PHP Manual
  • DOMNode
  • ノードを正規化する

DOMNode::normalize

(PHP 5, PHP 7, PHP 8)

DOMNode::normalize — ノードを正規化する

説明

public DOMNode::normalize(): void

空のテキストノードを削除し、このノードに隣接するテキストノードとそのすべての子をマージします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • » The DOM Specification
  • DOMDocument::normalizeDocument() - ドキュメントを正規化する


子要素群から子要素を削除する

  • ≪ DOMNode::normalize
  • DOMNode::replaceChild ≫
  • PHP Manual
  • DOMNode
  • 子要素群から子要素を削除する

DOMNode::removeChild

(PHP 5, PHP 7, PHP 8)

DOMNode::removeChild — 子要素群から子要素を削除する

説明

public DOMNode::removeChild(DOMNode $child): DOMNode|false

この関数は、子要素群から子要素を削除します。

パラメータ

child

削除する子要素。

戻り値

子要素の削除に成功した場合に、削除した要素を返します。 エラーの場合は false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

ノードが読み込み専用の場合に発生します。

DOM_NOT_FOUND_ERR

child がこのノードの子要素でない場合に発生します。

例

以下の例は、XML ドキュメントから chapter 要素を削除します。

例1 子要素の削除

<?php

$doc = new DOMDocument;
$doc->load('book.xml');

$book = $doc->documentElement;

// chapter を取得し、それを book から削除します
$chapter = $book->getElementsByTagName('chapter')->item(0);
$oldchapter = $book->removeChild($chapter);

echo $doc->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="listing">
 <title>My lists</title>

</book>

参考

  • DOMChildNode::remove() - ノードを削除する
  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMNode::replaceChild() - 子を置き換える


子を置き換える

  • ≪ DOMNode::removeChild
  • DOMNodeList ≫
  • PHP Manual
  • DOMNode
  • 子を置き換える

DOMNode::replaceChild

(PHP 5, PHP 7, PHP 8)

DOMNode::replaceChild — 子を置き換える

説明

public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false

この関数は、子要素 child を新しいノードに 置き換えます。もし node がすでに子要素であった場合は、 それがふたたび追加されることはありません。置き換えに成功すると、 置き換え前のノードが返されます。

パラメータ

node

新しいノード。対象ドキュメントのメンバ、 すなわち、DOMDocument->createXXX() メソッドのひとつで作成されたものか DOMDocument::importNode で ドキュメントにインポートされたものである必要があります。

child

古いノード。

戻り値

古いノード、あるいはエラーが発生した場合は false を返します。

エラー / 例外

DOM_NO_MODIFICATION_ALLOWED_ERR

このノードが読み込み専用であったり、挿入されるノードの以前の親が 読み込み専用であった場合に発生します。

DOM_HIERARCHY_REQUEST_ERR

node で指定した型の子ノードを 保持することが許可されていない場合、あるいは追加しようとしている ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

node が、このノードとは別の ドキュメントで作成されたものである場合に発生します。

DOM_NOT_FOUND_ERR

child がこのノードの子でない場合に発生します。

参考

  • DOMChildNode::replaceWith() - ノードを新しいノードで置き換える
  • DOMNode::appendChild() - 子要素群の最後に新しい子要素を追加する
  • DOMNode::removeChild() - 子要素群から子要素を削除する


DOMNodeList クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMNodeList implements IteratorAggregate, Countable {
/* プロパティ */
public readonly int $length;
/* メソッド */
public count(): int
public getIterator(): Iterator
public item(int $index): DOMElement|DOMNode|DOMNameSpaceNode|null
}

プロパティ

length

リスト内のノードの数。有効な子ノードのインデックスの範囲は 0 以上 length - 1 以下

変更履歴

バージョン | 説明
8.0.0 | DOMNodeList は IteratorAggregate を実装しました。 これより前のバージョンでは、 Traversable を代わりに実装していました。
7.2.0 | Countable インターフェイスが実装され、 length の値を返すようになりました。

参考

  • » W3C での NodeList の仕様

目次

  • DOMNodeList::count — リストにあるノードの数を取得する
  • DOMNodeList::getIterator — 外部のイテレータを取得する
  • DOMNodelist::item — インデックスで指定したノードを取得する


リストにあるノードの数を取得する

  • ≪ DOMNodeList
  • DOMNodeList::getIterator ≫
  • PHP Manual
  • DOMNodeList
  • リストにあるノードの数を取得する

DOMNodeList::count

(PHP 7 >= 7.2.0, PHP 8)

DOMNodeList::count — リストにあるノードの数を取得する

説明

public DOMNodeList::count(): int

リストにあるノードの数を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

リストにあるノードの数を返します。 これは length プロパティに等しくなります。


外部のイテレータを取得する

  • ≪ DOMNodeList::count
  • DOMNodelist::item ≫
  • PHP Manual
  • DOMNodeList
  • 外部のイテレータを取得する

DOMNodeList::getIterator

(PHP 8)

DOMNodeList::getIterator — 外部のイテレータを取得する

説明

public DOMNodeList::getIterator(): Iterator

ノードリスト向けの、外部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

Iterator あるいは Traversable を実装したオブジェクトのインスタンスを返します。

エラー / 例外

失敗した場合は Exception をスローします。

参考

  • IteratorAggregate::getIterator() - 外部イテレータを取得する


インデックスで指定したノードを取得する

  • ≪ DOMNodeList::getIterator
  • DOMNotation ≫
  • PHP Manual
  • DOMNodeList
  • インデックスで指定したノードを取得する

DOMNodelist::item

(PHP 5, PHP 7, PHP 8)

DOMNodelist::item — インデックスで指定したノードを取得する

説明

public DOMNodeList::item(int $index): DOMElement|DOMNode|DOMNameSpaceNode|null

DOMNodeList オブジェクトから、 index で指定したノードを取得します。

ヒント

コレクション内のノードの数を知るには、 DOMNodeList オブジェクトの length プロパティを使用します。

パラメータ

index

コレクション内のノードのインデックス。

戻り値

DOMNodeList 内の index 番目の位置にあるノード、あるいはインデックスが不正な形式の場合は null を返します。

例

例1 テーブル内のすべての要素を取得する

<?php

$doc = new DOMDocument;
$doc->load('book.xml');

$items = $doc->getElementsByTagName('entry');

for ($i = 0; $i < $items->length; $i++) {
echo $items->item($i)->nodeValue . "\n";
}

?>

別の方法として foreach を使用することも可能で、 こちらのほうがずっと使いやすいでしょう。

<?php

foreach ($items as $item) {
echo $item->nodeValue . "\n";
}

?>

上の例の出力は以下となります。

Title
Author
Language
ISBN
The Grapes of Wrath
John Steinbeck
en
0140186409
The Pearl
John Steinbeck
en
014017737X
Samarcande
Amine Maalouf
fr
2253051209


DOMNotation クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMNotation extends DOMNode {
/* プロパティ */
public readonly string $publicId;
public readonly string $systemId;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

publicId

systemId


DOMParentNode インターフェイス

(PHP 8)

インターフェイス概要

interface DOMParentNode {
/* メソッド */
public append(DOMNode|string ...$nodes): void
public prepend(DOMNode|string ...$nodes): void
public replaceChildren(DOMNode|string ...$nodes): void
}

目次

  • DOMParentNode::append — 最後の子ノードの後ろにノードを追加する
  • DOMParentNode::prepend — 最初の子ノードの前にノードを追加する
  • DOMParentNode::replaceChildren — ノード中の子を置換する


最後の子ノードの後ろにノードを追加する

  • ≪ DOMParentNode
  • DOMParentNode::prepend ≫
  • PHP Manual
  • DOMParentNode
  • 最後の子ノードの後ろにノードを追加する

DOMParentNode::append

(PHP 8)

DOMParentNode::append — 最後の子ノードの後ろにノードを追加する

説明

public DOMParentNode::append(DOMNode|string ...$nodes): void

ひとつ以上の nodes を、 最後の子ノードの後ろの、子ノードのリストに追加します。

パラメータ

nodes

追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

参考

  • DOMParentNode::prepend() - 最初の子ノードの前にノードを追加する


最初の子ノードの前にノードを追加する

  • ≪ DOMParentNode::append
  • DOMParentNode::replaceChildren ≫
  • PHP Manual
  • DOMParentNode
  • 最初の子ノードの前にノードを追加する

DOMParentNode::prepend

(PHP 8)

DOMParentNode::prepend — 最初の子ノードの前にノードを追加する

説明

public DOMParentNode::prepend(DOMNode|string ...$nodes): void

ひとつ以上の nodes を、 最初の子ノードの前の、 子ノードのリストに追加します。

パラメータ

nodes

ノードの前に追加するノード。 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

参考

  • DOMParentNode::append() - 最後の子ノードの後ろにノードを追加する


ノード中の子を置換する

  • ≪ DOMParentNode::prepend
  • DOMProcessingInstruction ≫
  • PHP Manual
  • DOMParentNode
  • ノード中の子を置換する

DOMParentNode::replaceChildren

(PHP 8 >= 8.3.0)

DOMParentNode::replaceChildren — ノード中の子を置換する

説明

public DOMParentNode::replaceChildren(DOMNode|string ...$nodes): void

ノード中の子を置換します。

パラメータ

nodes

子を置き換えるノード 文字列は自動的にテキストノードに変換されます。

戻り値

値を返しません。

エラー / 例外

DOM_HIERARCHY_REQUEST_ERR

指定された nodes のうちの一つの子ノードの型を、 親ノードが許可していない場合や、ノードが自分自身やその祖先であった場合に発生します。

DOM_WRONG_DOCUMENT_ERR

指定された nodes のうちの一つが、 このノードを作成したドキュメントとは異なるものから作成された場合に発生します。

変更履歴

バージョン | 説明
8.3.0 | オーナーとなるドキュメントがないノードに対して、 このメソッドをコールしても動作するようになりました。 これより前のバージョンでは、エラーコード DOM_HIERARCHY_REQUEST_ERR を持つ DOMException がスローされていました。

例

例1 DOMParentNode::replaceChildren() の例

<?php

$dom = new DOMDocument();
$dom->loadHTML('<!DOCTYPE HTML><html><p>hi</p> test <p>hi2</p></html>');

$dom->documentElement->replaceChildren('foo', $dom->createElement('p'), 'bar');
echo $dom->saveXML();
?>

上の例の出力は以下となります。

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE HTML>
<html>foo<p/>bar</html>


DOMProcessingInstruction クラス

(PHP 5, PHP 7, PHP 8)

クラス概要

class DOMProcessingInstruction extends DOMNode {
/* プロパティ */
public readonly string $target;
public string $data;
/* 継承したプロパティ */
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $name, string $value = "")
/* 継承したメソッド */
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

target

data

目次

  • DOMProcessingInstruction::__construct — 新しい DOMProcessingInstruction オブジェクトを作成する


新しい DOMProcessingInstruction オブジェクトを作成する

  • ≪ DOMProcessingInstruction
  • DOMText ≫
  • PHP Manual
  • DOMProcessingInstruction
  • 新しい DOMProcessingInstruction オブジェクトを作成する

DOMProcessingInstruction::__construct

(PHP 5, PHP 7, PHP 8)

DOMProcessingInstruction::__construct — 新しい DOMProcessingInstruction オブジェクトを作成する

説明

public DOMProcessingInstruction::__construct(string $name, string $value = "")

新しい DOMProcessingInstruction オブジェクトを 作成します。このオブジェクトは読み込み専用です。このオブジェクトを ドキュメントに追加することは可能ですが、ノードをドキュメントに 関連付けるまではこのノードに別のノードを追加することはできません。 書き込み可能なノードを作成するには、 DOMDocument::createProcessingInstruction を使用してください。

パラメータ

name

処理命令のタグ名。

value

処理命令の値。

例

例1 新しい DOMProcessingInstruction を作成する

<?php

$dom = new DOMDocument('1.0', 'UTF-8');
$html = $dom->appendChild(new DOMElement('html'));
$body = $html->appendChild(new DOMElement('body'));
$pinode = new DOMProcessingInstruction('php', 'echo "Hello World"; ');
$body->appendChild($pinode);
echo $dom->saveXML();

?>

上の例の出力は以下となります。

<?xml version="1.0" encoding="UTF-8"?>
<html><body><?php echo "Hello World"; ?></body></html>

参考

  • DOMDocument::createProcessingInstruction() - 新しい PI ノードを作成する


DOMText クラス

(PHP 5, PHP 7, PHP 8)

はじめに

DOMText クラスは DOMCharacterData を継承しており、 DOMElement あるいは DOMAttr の中身のテキストを表します。

クラス概要

class DOMText extends DOMCharacterData {
/* プロパティ */
public readonly string $wholeText;
/* 継承したプロパティ */
public string $data;
public readonly int $length;
public readonly ?DOMElement $previousElementSibling;
public readonly ?DOMElement $nextElementSibling;
public readonly string $nodeName;
public ?string $nodeValue;
public readonly int $nodeType;
public readonly ?DOMNode $parentNode;
public readonly ?DOMElement $parentElement;
public readonly DOMNodeList $childNodes;
public readonly ?DOMNode $firstChild;
public readonly ?DOMNode $lastChild;
public readonly ?DOMNode $previousSibling;
public readonly ?DOMNode $nextSibling;
public readonly ?DOMNamedNodeMap $attributes;
public readonly bool $isConnected;
public readonly ?DOMDocument $ownerDocument;
public readonly ?string $namespaceURI;
public string $prefix;
public readonly ?string $localName;
public readonly ?string $baseURI;
public string $textContent;
/* メソッド */
public __construct(string $data = "")
public isElementContentWhitespace(): bool
public isWhitespaceInElementContent(): bool
public splitText(int $offset): DOMText|false
/* 継承したメソッド */
public DOMCharacterData::after(DOMNode|string ...$nodes): void
public DOMCharacterData::appendData(string $data): true
public DOMCharacterData::before(DOMNode|string ...$nodes): void
public DOMCharacterData::deleteData(int $offset, int $count): bool
public DOMCharacterData::insertData(int $offset, string $data): bool
public DOMCharacterData::remove(): void
public DOMCharacterData::replaceData(int $offset, int $count, string $data): bool
public DOMCharacterData::replaceWith(DOMNode|string ...$nodes): void
public DOMCharacterData::substringData(int $offset, int $count): string|false
public DOMNode::appendChild(DOMNode $node): DOMNode|false
public DOMNode::C14N(
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): string|false
public DOMNode::C14NFile(
string $uri,
bool $exclusive = false,
bool $withComments = false,
?array $xpath = null,
?array $nsPrefixes = null
): int|false
public DOMNode::cloneNode(bool $deep = false): DOMNode|false
public DOMNode::contains(DOMNode|DOMNameSpaceNode|null $other): bool
public DOMNode::getLineNo(): int
public DOMNode::getNodePath(): ?string
public DOMNode::getRootNode(?array $options = null): DOMNode
public DOMNode::hasAttributes(): bool
public DOMNode::hasChildNodes(): bool
public DOMNode::insertBefore(DOMNode $node, ?DOMNode $child = null): DOMNode|false
public DOMNode::isDefaultNamespace(string $namespace): bool
public DOMNode::isEqualNode(?DOMNode $otherNode): bool
public DOMNode::isSameNode(DOMNode $otherNode): bool
public DOMNode::isSupported(string $feature, string $version): bool
public DOMNode::lookupNamespaceURI(?string $prefix): ?string
public DOMNode::lookupPrefix(string $namespace): ?string
public DOMNode::normalize(): void
public DOMNode::removeChild(DOMNode $child): DOMNode|false
public DOMNode::replaceChild(DOMNode $node, DOMNode $child): DOMNode|false
}

プロパティ

wholeText

論理的に隣接した (要素やコメント、処理命令などで分割されていない) テキストノードの全テキストを保持します。

変更履歴

バージョン | 説明
8.0.0 | 実装されていなかったメソッド DOMText::replaceWholeText() が削除されました。

目次

  • DOMText::__construct — 新しい DOMText オブジェクトを作成する
  • DOMText::isElementContentWhitespace — このテキストノードが、要素の内容にホワイトスペースが含まれているかを返す
  • DOMText::isWhitespaceInElementContent — このテキストノードが空白を含むかどうかを示す
  • DOMText::splitText — 指定したオフセットでノードを 2 つに分割する


新しい DOMText オブジェクトを作成する

  • ≪ DOMText
  • DOMText::isElementContentWhitespace ≫
  • PHP Manual
  • DOMText
  • 新しい DOMText オブジェクトを作成する

DOMText::__construct

(PHP 5, PHP 7, PHP 8)

DOMText::__construct — 新しい DOMText オブジェクトを作成する

説明

public DOMText::__construct(string $data = "")

新しい DOMText オブジェクトを作成します。

パラメータ

data

text ノードの値。指定しなかった場合は空の text ノードが作成されます。

例

例1 新しい DOMText を作成する

<?php

$dom = new DOMDocument('1.0', 'iso-8859-1');
$element = $dom->appendChild(new DOMElement('root'));
$text = $element->appendChild(new DOMText('root value'));
echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root>root value</root> */

?>

参考

  • DOMDocument::createTextNode() - 新しいテキストノードを作成する


このテキストノードが、要素の内容にホワイトスペースが含まれているかを返す

  • ≪ DOMText::__construct
  • DOMText::isWhitespaceInElementContent ≫
  • PHP Manual
  • DOMText
  • このテキストノードが、要素の内容にホワイトスペースが含まれているかを返す

DOMText::isElementContentWhitespace

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

DOMText::isElementContentWhitespace — このテキストノードが、要素の内容にホワイトスペースが含まれているかを返す

説明

public DOMText::isElementContentWhitespace(): bool

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。


このテキストノードが空白を含むかどうかを示す

  • ≪ DOMText::isElementContentWhitespace
  • DOMText::splitText ≫
  • PHP Manual
  • DOMText
  • このテキストノードが空白を含むかどうかを示す

DOMText::isWhitespaceInElementContent

(PHP 5, PHP 7, PHP 8)

DOMText::isWhitespaceInElementContent — このテキストノードが空白を含むかどうかを示す

説明

public DOMText::isWhitespaceInElementContent(): bool

このテキストノードが空白のみを含む（あるいは空である）かどうかを示します。 このテキストノードが要素の内容に空白を含むかどうかは、 ドキュメントの読み込み時に決定されます。

パラメータ

この関数にはパラメータはありません。

戻り値

ノードにゼロ個以上の空白文字だけが含まれる場合に true、 それ以外の場合に false を返します。


指定したオフセットでノードを 2 つに分割する

  • ≪ DOMText::isWhitespaceInElementContent
  • DOMXPath ≫
  • PHP Manual
  • DOMText
  • 指定したオフセットでノードを 2 つに分割する

DOMText::splitText

(PHP 5, PHP 7, PHP 8)

DOMText::splitText — 指定したオフセットでノードを 2 つに分割する

説明

public DOMText::splitText(int $offset): DOMText|false

指定したオフセット offset でノードを 2 つに分割します。分割したノードのツリー内での位置関係は、兄弟となります。

分割した後は、このノードは offset 位置までの 内容を保持するようになります。元のノードが親ノードを保持している場合、 新しいノードは元のノードの兄弟として元のノードの次の位置に挿入されます。 offset がこのノードの長さに等しい場合は、 新しいノードにはデータが含まれません。

パラメータ

offset

分割する位置を示すオフセット。0 から始まります。

戻り値

同じ型の新しいノードを返します。offset 以降の内容をデータとして保持します。


DOMXPath クラス

(PHP 5, PHP 7, PHP 8)

はじめに

XPath 1.0 をサポートします。

クラス概要

class DOMXPath {
/* プロパティ */
public readonly DOMDocument $document;
public bool $registerNodeNamespaces;
/* メソッド */
public __construct(DOMDocument $document, bool $registerNodeNS = true)
public evaluate(string $expression, ?DOMNode $contextNode = null, bool $registerNodeNS = true): mixed
public query(string $expression, ?DOMNode $contextNode = null, bool $registerNodeNS = true): mixed
public registerNamespace(string $prefix, string $namespace): bool
public registerPhpFunctions(string|array|null $restrict = null): void
}

プロパティ

document

registerNodeNamespaces

true に設定すると、ノードの名前空間が登録されます。

変更履歴

バージョン | 説明
8.0.0 | プロパティ registerNodeNamespaces が追加されました。

目次

  • DOMXPath::__construct — 新しい DOMXPath オブジェクトを作成する
  • DOMXPath::evaluate — 与えられた XPath 式を評価し、可能であれば結果を返す
  • DOMXPath::query — 与えられた XPath 式を評価する
  • DOMXPath::registerNamespace — DOMXPath オブジェクトの名前空間を登録する
  • DOMXPath::registerPhpFunctions — PHP の関数を XPath 関数として登録する


新しい DOMXPath オブジェクトを作成する

  • ≪ DOMXPath
  • DOMXPath::evaluate ≫
  • PHP Manual
  • DOMXPath
  • 新しい DOMXPath オブジェクトを作成する

DOMXPath::__construct

(PHP 5, PHP 7, PHP 8)

DOMXPath::__construct — 新しい DOMXPath オブジェクトを作成する

説明

public DOMXPath::__construct(DOMDocument $document, bool $registerNodeNS = true)

新しい DOMXPath オブジェクトを作成します。

パラメータ

document

DOMXPath に関連付けられた DOMDocument。

registerNodeNS

コンテキストノードのスコープ内の名前空間を、DOMXPath オブジェクトに自動登録するかどうか。 このオプションを使うと、スコープ内の名前空間ごとに、手動で DOMXPath::registerNamespace() をコールする必要がなくなります。 名前空間のプレフィックスが衝突した場合は、直近の子孫の名前空間プレフィックスのみが登録されます。


与えられた XPath 式を評価し、可能であれば結果を返す

  • ≪ DOMXPath::__construct
  • DOMXPath::query ≫
  • PHP Manual
  • DOMXPath
  • 与えられた XPath 式を評価し、可能であれば結果を返す

DOMXPath::evaluate

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

DOMXPath::evaluate — 与えられた XPath 式を評価し、可能であれば結果を返す

説明

public DOMXPath::evaluate(string $expression, ?DOMNode $contextNode = null, bool $registerNodeNS = true): mixed

与えられた XPath 式 expression を実行し、 可能であれば型付けされた結果を返します。

パラメータ

expression

実行する XPath 式。

contextNode

相対 XPath クエリを実行する場合に、オプションで基準ノードを指定することが可能です。 デフォルトでは、クエリは root 要素に対する相対パスとなります。

registerNodeNS

コンテキストノードのスコープ内の名前空間を、DOMXPath オブジェクトに自動登録するかどうか。 このオプションを使うと、スコープ内の名前空間ごとに、手動で DOMXPath::registerNamespace() をコールする必要がなくなります。 名前空間のプレフィックスが衝突した場合は、直近の子孫の名前空間プレフィックスのみが登録されます。

戻り値

可能であれば型付けされた結果、あるいは指定された XPath 式 expression にマッチするすべてのノードを含む DOMNodeList を返します。

expression が不正な形式な場合や contextNode が無効な場合は、 DOMXPath::evaluate() は false を返します。

例

例1 英語の書籍の数を取得する

<?php

$doc = new DOMDocument;

$doc->load('book.xml');

$xpath = new DOMXPath($doc);

$tbody = $doc->getElementsByTagName('tbody')->item(0);

// tbody ノードを基準とした相対クエリとなります
$query = 'count(row/entry[. = "en"])';

$entries = $xpath->evaluate($query, $tbody);
echo "There are $entries english books\n";

?>

上の例の出力は以下となります。

There are 2 english books

参考

  • DOMXPath::query() - 与えられた XPath 式を評価する


与えられた XPath 式を評価する

  • ≪ DOMXPath::evaluate
  • DOMXPath::registerNamespace ≫
  • PHP Manual
  • DOMXPath
  • 与えられた XPath 式を評価する

DOMXPath::query

(PHP 5, PHP 7, PHP 8)

DOMXPath::query — 与えられた XPath 式を評価する

説明

public DOMXPath::query(string $expression, ?DOMNode $contextNode = null, bool $registerNodeNS = true): mixed

与えられた XPath 式 expression を評価します。

パラメータ

expression

実行する XPath 式。

contextNode

相対 XPath クエリを実行する場合に、オプションで基準ノードを指定することが可能です。 デフォルトでは、クエリは root 要素に対する相対パスとなります。

registerNodeNS

コンテキストノードのスコープ内の名前空間を、DOMXPath オブジェクトに自動登録するかどうか。 このオプションを使うと、スコープ内の名前空間ごとに、手動で DOMXPath::registerNamespace() をコールする必要がなくなります。 名前空間のプレフィックスが衝突した場合は、直近の子孫の名前空間プレフィックスのみが登録されます。

戻り値

与えられた XPath 式 expression にマッチする すべてのノードを含む DOMNodeList を返します。 ノードを返さない式の場合は、空の DOMNodeList を返します。

expression が不正な形式な場合や contextNode が無効な場合は、 DOMXPath::query() は false を返します。

例

例1 すべての英語の書籍を取得する

<?php

$doc = new DOMDocument;

// 空白に悩まされたくはありません
$doc->preserveWhiteSpace = false;

$doc->load('book.xml');

$xpath = new DOMXPath($doc);

// root 要素から開始します
$query = '//book/chapter/para/informaltable/tgroup/tbody/row/entry[. = "en"]';

$entries = $xpath->query($query);

foreach ($entries as $entry) {
echo "Found {$entry->previousSibling->previousSibling->nodeValue}," .
" by {$entry->previousSibling->nodeValue}\n";
}
?>

上の例の出力は以下となります。

Found The Grapes of Wrath, by John Steinbeck
Found The Pearl, by John Steinbeck

式を短くするため、contextNode パラメータを使用することも可能です。

<?php

$doc = new DOMDocument;
$doc->preserveWhiteSpace = false;

$doc->load('book.xml');

$xpath = new DOMXPath($doc);

$tbody = $doc->getElementsByTagName('tbody')->item(0);

// tbody ノードからの相対クエリです
$query = 'row/entry[. = "en"]';

$entries = $xpath->query($query, $tbody);

foreach ($entries as $entry) {
echo "Found {$entry->previousSibling->previousSibling->nodeValue}," .
" by {$entry->previousSibling->nodeValue}\n";
}
?>

参考

  • DOMXPath::evaluate() - 与えられた XPath 式を評価し、可能であれば結果を返す


DOMXPath オブジェクトの名前空間を登録する

  • ≪ DOMXPath::query
  • DOMXPath::registerPhpFunctions ≫
  • PHP Manual
  • DOMXPath
  • DOMXPath オブジェクトの名前空間を登録する

DOMXPath::registerNamespace

(PHP 5, PHP 7, PHP 8)

DOMXPath::registerNamespace — DOMXPath オブジェクトの名前空間を登録する

説明

public DOMXPath::registerNamespace(string $prefix, string $namespace): bool

DOMXPath オブジェクトに、 namespace および prefix を登録します。

パラメータ

prefix

プレフィックス。

namespace

名前空間の URI。

戻り値

成功した場合に true を、失敗した場合に false を返します。


PHP の関数を XPath 関数として登録する

  • ≪ DOMXPath::registerNamespace
  • DOM 関数 ≫
  • PHP Manual
  • DOMXPath
  • PHP の関数を XPath 関数として登録する

DOMXPath::registerPhpFunctions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DOMXPath::registerPhpFunctions — PHP の関数を XPath 関数として登録する

説明

public DOMXPath::registerPhpFunctions(string|array|null $restrict = null): void

このメソッドは、PHP の関数を XPath 式の中で使えるようにします。

パラメータ

restrict

このパラメータを使って、特定の関数のみを XPath からコールできるように制限することができます。

このパラメータには、文字列 (関数名) あるいは関数名の配列を指定します。

戻り値

値を返しません。

例

次の例では、以下のような内容の book.xml を使います。

例1 book.xml

<?xml version="1.0" encoding="UTF-8"?>
<books>
 <book>
  <title>PHP Basics</title>
  <author>Jim Smith</author>
  <author>Jane Smith</author>
 </book>
 <book>
  <title>PHP Secrets</title>
  <author>Jenny Smythe</author>
 </book>
 <book>
  <title>XML basics</title>
  <author>Joe Black</author>
 </book>
</books>

例2 DOMXPath::registerPHPFunctions() と php:functionString の例

<?php
$doc = new DOMDocument;
$doc->load('book.xml');

$xpath = new DOMXPath($doc);

// 名前空間 php: を登録します (必須)
$xpath->registerNamespace("php", "http://php.net/xpath");

// PHP の関数を登録します (無制限)
$xpath->registerPHPFunctions();

// substr 関数を book の title に適用します
$nodes = $xpath->query('//book[php:functionString("substr", title, 0, 3) = "PHP"]');

echo "Found {$nodes->length} books starting with 'PHP':\n";
foreach ($nodes as $node) {
$title = $node->getElementsByTagName("title")->item(0)->nodeValue;
$author = $node->getElementsByTagName("author")->item(0)->nodeValue;
echo "$title by $author\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Found 2 books starting with 'PHP':
PHP Basics by Jim Smith
PHP Secrets by Jenny Smythe

例3 DOMXPath::registerPHPFunctions() と php:function の例

<?php
$doc = new DOMDocument;
$doc->load('book.xml');

$xpath = new DOMXPath($doc);

// 名前空間 php: を登録します (必須)
$xpath->registerNamespace("php", "http://php.net/xpath");

// PHP の関数を登録します (has_multiple 限定)
$xpath->registerPHPFunctions("has_multiple");

function has_multiple($nodes) {
// author が複数ある場合に true を返します
return count($nodes) > 1;
}
// 複数の author がいる book のみを取り出します
$books = $xpath->query('//book[php:function("has_multiple", author)]');

echo "Books with multiple authors:\n";
foreach ($books as $book) {
echo $book->getElementsByTagName("title")->item(0)->nodeValue . "\n";
}

?>

上の例の出力は、 たとえば以下のようになります。

Books with multiple authors:
PHP Basics

参考

  • DOMXPath::registerNamespace() - DOMXPath オブジェクトの名前空間を登録する
  • DOMXPath::query() - 与えられた XPath 式を評価する
  • DOMXPath::evaluate() - 与えられた XPath 式を評価し、可能であれば結果を返す


  • ≪ DOMXPath::registerPhpFunctions
  • dom_import_simplexml ≫
  • PHP Manual
  • DOM
  • DOM 関数

DOM 関数

目次

  • dom_import_simplexml — SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する


SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する

  • ≪ DOM 関数
  • libxml ≫
  • PHP Manual
  • DOM 関数
  • SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する

dom_import_simplexml

(PHP 5, PHP 7, PHP 8)

dom_import_simplexml — SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する

説明

dom_import_simplexml(object $node): DOMElement

この関数は、SimpleXML クラスの ノード node を受け取り、それを DOMElement ノードに変換します。新しいオブジェクトは、 DOMElement ノードとして使用可能です。

パラメータ

node

SimpleXMLElement ノード。

戻り値

追加された DOMElement ノードを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は、失敗時に null を返さなくなりました。

例

例1 dom_import_simplexml() を用いて SimpleXML を DOM にインポートする

<?php

$sxe = simplexml_load_string('<books><book><title>blah</title></book></books>');

if ($sxe === false) {
echo 'ドキュメントのパース中にエラー';
exit;
}

$dom_sxe = dom_import_simplexml($sxe);
if (!$dom_sxe) {
echo 'XML の変換中にエラー';
exit;
}

$dom = new DOMDocument('1.0');
$dom_sxe = $dom->importNode($dom_sxe, true);
$dom_sxe = $dom->appendChild($dom_sxe);

echo $dom->saveXML();

?>

参考

  • simplexml_import_dom() - DOM ノードから SimpleXMLElement オブジェクトを取得する


libxml

  • はじめに
  • インストール/設定
    • 要件
    • PHP >= 7.4 におけるインストール手順
    • PHP < 7.4 におけるインストール手順
  • 定義済み定数
  • LibXMLError — LibXMLError クラス
  • libxml 関数
    • libxml_clear_errors — libxmlエラーハンドラをクリアする
    • libxml_disable_entity_loader — 外部エンティティの読み込み機能を無効にする
    • libxml_get_errors — エラー配列を取得する
    • libxml_get_external_entity_loader — 現在の外部エンティティローダーを取得する
    • libxml_get_last_error — libxmlから直近のエラーを取得する
    • libxml_set_external_entity_loader — デフォルトの外部エンティティローダーを変更する
    • libxml_set_streams_context — 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する
    • libxml_use_internal_errors — libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする


はじめに

これらの関数/定数は PHP 5.1.0 以降で使用可能です。 また、以下にあげるコア拡張モジュールは、この libxml 拡張モジュールに依存しています。 DOM, libxml, SimpleXML, SOAP, WDDX, XSL, XML, XMLReader, XMLRPC そして XMLWriter


インストール/設定

目次

  • 要件
  • PHP >= 7.4 におけるインストール手順
  • PHP < 7.4 におけるインストール手順


要件

この拡張モジュールは、PHP 8.0 以降では » libxml >= 2.9.0 が必要です。PHP 8.0 より前のバージョンでは、libxml >= 2.6.0 が必要です。


PHP >= 7.4 におけるインストール手順

libxml 拡張モジュールはデフォルトで有効となりますが、 --without-libxml で無効になっている可能性もあります。

PHP は libxml2 向けの正しいライブラリファイルやヘッダファイル、 コンパイルフラグを選ぶために pkg-config を使います。 configure スクリプトを実行する前に、 望ましいバージョンの libxml2 が選ばれるようにするために、 pkg-config の検索パスを制御する目的で 以下のようにして環境変数 PKG_CONFIG_PATH が使えます:

PKG_CONFIG_PATH="/path/to/libxml2/prefix/lib/pkgconfig:/lib/pkgconfig"


PHP < 7.4 におけるインストール手順

libxml 拡張モジュールはデフォルトで有効となりますが、 --disable-libxml で無効になっている可能性もあります。

オプションの --with-libxml-dir ディレクティブを使って、PHP をコンパイルするシステム上での libxml の位置を指定することができます。 指定しなければ、デフォルトの場所のみを探します。configure の際に libxml (具体的には xml2-config) を探す順序は次のとおりです。

  1. --with-libxml-dir で指定した ([DIR]) 場所 ([DIR]=/bin/xml2-config)

  2. /usr/local/bin/xml2-config

  3. /usr/bin/xml2-config

configure 時に --with-libxml-dir で指定したディレクトリで xml2-config が見つからない場合は、デフォルトの場所を探します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

LIBXML_BIGLINES (int)
行数が 65535 を超えても正しく報告する

注意:

PHP 7.0.0 以降で Libxml >= 2.9.0 の場合のみ有効

LIBXML_COMPACT (int)
小さなノードを割り当てるように最適化する。アプリケーションの コードを変更することなしにスピードアップさせることができる

注意:

Libxml >= 2.6.21 でのみ有効

LIBXML_DTDATTR (int)
デフォルトのDTD属性
LIBXML_DTDLOAD (int)
外部サブセットをロードする
LIBXML_DTDVALID (int)
DTDで検証する
警告

DTD の検証を有効にすると、XML外部エンティティ参照攻撃(XXE) を容易にしてしまうかもしれません。

LIBXML_HTML_NOIMPLIED (int)
HTML_PARSE_NOIMPLIED フラグを設定する。 これは、暗黙の html/body... 要素の自動追加を無効にする。

注意:

Libxml >= 2.7.7 (PHP >= 5.4.0) でのみ有効

LIBXML_HTML_NODEFDTD (int)
HTML_PARSE_NODEFDTD フラグを設定する。 これは、doctype が見つからないときにデフォルトの doctype を追加しないようにする。

注意:

Libxml >= 2.7.8 (PHP >= 5.4.0) でのみ有効

LIBXML_LOADED_VERSION (string)
libxml のコアパーサのバージョン
LIBXML_NOBLANKS (int)
空白のノードを削除
LIBXML_NOCDATA (int)
CDATA をテキストノードとしてマージ
LIBXML_NOEMPTYTAG (int)
空タグを拡張する（例 <br/> を <br></br> にする）

注意:

このオプションは、現在 DOMDocument::save および DOMDocument::saveXML 関数でのみ有効です。

LIBXML_NOENT (int)
エンティティを置換
警告

エンティティの置換を有効にすると、XML外部エンティティ参照攻撃(XXE) を容易にしてしまうかもしれません。

LIBXML_NOERROR (int)
エラー出力を抑制
LIBXML_NONET (int)
ドキュメントロード時にネットワークアクセスを無効にする
LIBXML_NOWARNING (int)
警告出力を抑制する
LIBXML_NOXMLDECL (int)
ドキュメントの保存時に XML 宣言を削除する

注意:

Libxml >= 2.6.21 でのみ有効

LIBXML_NSCLEAN (int)
冗長な名前空間宣言を削除する
LIBXML_PARSEHUGE (int)
パーサでハードコーディングされたすべての制限を緩和するための XML_PARSE_HUGE フラグを設定する。 これは、ドキュメントやエンティティの再帰の最大数や テキストノードのサイズなどの制限に影響する。

注意:

Libxml >= 2.7.0 (PHP >= 5.3.2 あるいは PHP >= 5.2.12) でのみ有効

LIBXML_PEDANTIC (int)
XML_PARSE_PEDANTIC フラグを設定する。これは、より細かいエラー報告を出す。

注意:

PHP >= 5.4.0 でのみ有効

LIBXML_XINCLUDE (int)
XInclude 置換を実装する
LIBXML_ERR_ERROR (int)
復帰可能なエラー
LIBXML_ERR_FATAL (int)
致命的なエラー
LIBXML_ERR_NONE (int)
エラーなし
LIBXML_ERR_WARNING (int)
単純な警告
LIBXML_VERSION (int)
20605 や 20617 のような libxml のバージョン
LIBXML_DOTTED_VERSION (string)
2.6.5または2.6.17のようなlibxmlのバージョン
LIBXML_SCHEMA_CREATE (int)
XSD スキーマの検証時にデフォルト/固定の値ノードを作る

注意:

Libxml >= 2.6.14 (PHP >= 5.5.2) 以降で利用可能


LibXMLError クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

libxml がスローするエラーについてのさまざまな情報を含みます。エラーコードについての説明は、公式の » xmlError API ドキュメント をごらんください。

クラス概要

class LibXMLError {
/* プロパティ */
public int $level;
public int $code;
public int $column;
public string $message;
public string $file;
public int $line;
}

プロパティ

level

エラーの深刻度 (次の定数 LIBXML_ERR_WARNING、 LIBXML_ERR_ERROR あるいは LIBXML_ERR_FATAL のいずれか)。

code

エラーコード。

column

エラーが発生した列。

注意:

このプロパティは libxml で完全には実装されておらず、しばしば 0 が返されることがあります。

message

エラーメッセージ (存在する場合)。

file

ファイル名。XML を文字列から読み込んだ場合は空文字列。

line

エラーが発生した行。


libxml 関数

目次

  • libxml_clear_errors — libxmlエラーハンドラをクリアする
  • libxml_disable_entity_loader — 外部エンティティの読み込み機能を無効にする
  • libxml_get_errors — エラー配列を取得する
  • libxml_get_external_entity_loader — 現在の外部エンティティローダーを取得する
  • libxml_get_last_error — libxmlから直近のエラーを取得する
  • libxml_set_external_entity_loader — デフォルトの外部エンティティローダーを変更する
  • libxml_set_streams_context — 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する
  • libxml_use_internal_errors — libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする


libxmlエラーハンドラをクリアする

  • ≪ libxml 関数
  • libxml_disable_entity_loader ≫
  • PHP Manual
  • libxml 関数
  • libxmlエラーハンドラをクリアする

libxml_clear_errors

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

libxml_clear_errors — libxmlエラーハンドラをクリアする

説明

libxml_clear_errors(): void

libxml_clear_errors()は、libxmlエラーバッファをクリアします。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

参考

  • libxml_get_errors() - エラー配列を取得する
  • libxml_get_last_error() - libxmlから直近のエラーを取得する


外部エンティティの読み込み機能を無効にする

  • ≪ libxml_clear_errors
  • libxml_get_errors ≫
  • PHP Manual
  • libxml 関数
  • 外部エンティティの読み込み機能を無効にする

libxml_disable_entity_loader

(PHP 5 >= 5.2.11, PHP 7, PHP 8)

libxml_disable_entity_loader — 外部エンティティの読み込み機能を無効にする

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

説明

libxml_disable_entity_loader(bool $disable = true): bool

外部エンティティ読み込み機能の有効/無効を切り替えます。 外部エンティティの読み込みを無効にすると、 XML文書を読み込む際に問題が起こる可能性があることに注意して下さい。 しかし、libxml 2.9.0 以降では、エンティティの置換はデフォルトで無効になっているため、 LIBXML_NOENT を使って内部エンティティの参照を解決する必要がない限り、 外部エンティティの読み込みを無効にする必要はありません。 一般的には、外部エンティティの読み込みを抑制するのであれば、 libxml_set_external_entity_loader() を使うことが望ましいです。

パラメータ

disable

libxml を使用する拡張モジュール (DOM、XMLWriter および XMLReader) で、外部エンティティの読み込み機能を 無効 (true) あるいは有効 (false) にします。

戻り値

変更前の値を返します。

参考

  • libxml_use_internal_errors() - libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする
  • libxml_set_external_entity_loader() - デフォルトの外部エンティティローダーを変更する
  • LIBXML_NOENT 定数


エラー配列を取得する

  • ≪ libxml_disable_entity_loader
  • libxml_get_external_entity_loader ≫
  • PHP Manual
  • libxml 関数
  • エラー配列を取得する

libxml_get_errors

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

libxml_get_errors — エラー配列を取得する

説明

libxml_get_errors(): array

エラー配列を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがバッファにある場合に LibXMLError オブジェクトの配列、 それ以外の場合に空の配列を返します。

例

例1 libxml_get_errors() の例

この例は、簡単な libxml エラーハンドラを構築する方法を示すものです。

<?php

libxml_use_internal_errors(true);

$xmlstr = <<< XML
<?xml version='1.0' standalone='yes'?>
<movies>
<movie>
<titles>PHP: Behind the Parser</title>
</movie>
</movies>
XML;

$doc = simplexml_load_string($xmlstr);
$xml = explode("\n", $xmlstr);

if ($doc === false) {
$errors = libxml_get_errors();

foreach ($errors as $error) {
echo display_xml_error($error, $xml);
}

libxml_clear_errors();
}

function display_xml_error($error, $xml)
{
$return = $xml[$error->line - 1] . "\n";
$return .= str_repeat('-', $error->column) . "^\n";

switch ($error->level) {
case LIBXML_ERR_WARNING:
$return .= "Warning $error->code: ";
break;
case LIBXML_ERR_ERROR:
$return .= "Error $error->code: ";
break;
case LIBXML_ERR_FATAL:
$return .= "Fatal Error $error->code: ";
break;
}

$return .= trim($error->message) .
"\n Line: $error->line" .
"\n Column: $error->column";

if ($error->file) {
$return .= "\n File: $error->file";
}

return "$return\n\n--------------------------------------------\n\n";
}

?>

上の例の出力は以下となります。

<titles>PHP: Behind the Parser</title>
----------------------------------------------^
Fatal Error 76: Opening and ending tag mismatch: titles line 4 and title
  Line: 4
  Column: 46

--------------------------------------------

参考

  • libxml_get_last_error() - libxmlから直近のエラーを取得する
  • libxml_clear_errors() - libxmlエラーハンドラをクリアする


現在の外部エンティティローダーを取得する

  • ≪ libxml_get_errors
  • libxml_get_last_error ≫
  • PHP Manual
  • libxml 関数
  • 現在の外部エンティティローダーを取得する

libxml_get_external_entity_loader

(PHP 8 >= 8.2.0)

libxml_get_external_entity_loader — 現在の外部エンティティローダーを取得する

説明

libxml_get_external_entity_loader(): ?callable

直前に libxml_set_external_entity_loader() を使って設定した、外部エンティティローダーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

直前に libxml_set_external_entity_loader() を使って設定した、外部エンティティローダーを返します。 libxml_set_external_entity_loader() をコールしたことがないか、null を渡して呼び出した場合は null を返します。

参考

  • libxml_set_external_entity_loader() - デフォルトの外部エンティティローダーを変更する


libxmlから直近のエラーを取得する

  • ≪ libxml_get_external_entity_loader
  • libxml_set_external_entity_loader ≫
  • PHP Manual
  • libxml 関数
  • libxmlから直近のエラーを取得する

libxml_get_last_error

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

libxml_get_last_error — libxmlから直近のエラーを取得する

説明

libxml_get_last_error(): LibXMLError|false

libxmlから直近のエラーを取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

エラーがバッファにある場合にLibXMLErrorオブジェクト、 それ以外の場合に false を返します。

参考

  • libxml_get_errors() - エラー配列を取得する
  • libxml_clear_errors() - libxmlエラーハンドラをクリアする


デフォルトの外部エンティティローダーを変更する

  • ≪ libxml_get_last_error
  • libxml_set_streams_context ≫
  • PHP Manual
  • libxml 関数
  • デフォルトの外部エンティティローダーを変更する

libxml_set_external_entity_loader

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

libxml_set_external_entity_loader — デフォルトの外部エンティティローダーを変更する

説明

libxml_set_external_entity_loader(?callable $resolver_function): bool

デフォルトの外部エンティティローダーを変更します。 たとえ LIBXML_NOENT が個別のXMLの操作に設定されている場合でも、 XXE攻撃を避けるために、任意の外部エンティティの展開を抑制するために使うことができます。 また、 libxml_disable_entity_loader() を呼び出すことよりも、この関数を呼び出すほうが通常は好ましいです。

パラメータ

resolver_function

次のシグネチャを持つ callable を指定します。:

resolver(?string $public_id, string $system_id, array $context): resource|string|null
public_id
パブリック ID
system_id
システムID
context
4つのキーを持つ配列。 キーは "directory", "intSubName", "extSubURI", "extSubSystem" です。
この callable は、 リソースまたはリソースをオープンできる文字列あるいは null でなければなりません。null を返す場合、エンティティ参照の解決は失敗します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 libxml_set_external_entity_loader() の例

<?php
$xml = <<<XML
<!DOCTYPE foo PUBLIC "-//FOO/BAR" "http://example.com/foobar">
<foo>bar</foo>
XML;

$dtd = <<<DTD
<!ELEMENT foo (#PCDATA)>
DTD;

libxml_set_external_entity_loader(
function ($public, $system, $context) use($dtd) {
var_dump($public);
var_dump($system);
var_dump($context);
$f = fopen("php://temp", "r+");
fwrite($f, $dtd);
rewind($f);
return $f;
}
);

$dd = new DOMDocument;
$r = $dd->loadXML($xml);

var_dump($dd->validate());
?>

上の例の出力は以下となります。

string(10) "-//FOO/BAR"
string(25) "http://example.com/foobar"
array(4) {
    ["directory"]    => NULL
    ["intSubName"]   => NULL
    ["extSubURI"]    => NULL
    ["extSubSystem"] => NULL
}
bool(true)

参考

  • libxml_disable_entity_loader() - 外部エンティティの読み込み機能を無効にする
  • libxml_get_external_entity_loader() - 現在の外部エンティティローダーを取得する


次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する

  • ≪ libxml_set_external_entity_loader
  • libxml_use_internal_errors ≫
  • PHP Manual
  • libxml 関数
  • 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する

libxml_set_streams_context

(PHP 5, PHP 7, PHP 8)

libxml_set_streams_context — 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する

説明

libxml_set_streams_context(resource $context): void

次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定します。

パラメータ

context

ストリームコンテキストリソース( stream_context_create()で作成)

戻り値

値を返しません。

例

例1 libxml_set_streams_context() の例

<?php

$opts = array(
'http' => array(
'user_agent' => 'PHP libxml agent',
)
);

$context = stream_context_create($opts);
libxml_set_streams_context($context);

// HTTPによりファイルをリクエスト
$doc = DOMDocument::load('http://www.example.com/file.xml');

?>

参考

  • stream_context_create() - ストリームコンテキストを作成する


libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする

  • ≪ libxml_set_streams_context
  • SimpleXML ≫
  • PHP Manual
  • libxml 関数
  • libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする

libxml_use_internal_errors

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

libxml_use_internal_errors — libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする

説明

libxml_use_internal_errors(?bool $use_errors = null): bool

libxml_use_internal_errors() により、 標準のlibxmlエラーを無効にし、ユーザーによるエラー処理を有効にすることができます。

パラメータ

use_errors

ユーザーによるエラー処理を有効 (true) または無効 (false) にする。 無効にすると、既に存在する libxml のエラーもすべてクリアします。

戻り値

この関数は、 use_errorsの前の値を返します。

変更履歴

バージョン | 説明
8.0.0 | use_errors は、nullable になりました。 これより前のバージョンでは、デフォルトは false でした。

例

例1 libxml_use_internal_errors()の例

この例では、libxml関数のエラー処理とこの関数の戻り値の 基本的な使い方を示しています。

<?php

// ユーザーによるエラー処理を有効にします
var_dump(libxml_use_internal_errors(true));

// ドキュメントを読み込みます
$doc = new DOMDocument;

if (!$doc->load('file.xml')) {
foreach (libxml_get_errors() as $error) {
// ここでエラー処理をします
}

libxml_clear_errors();
}

?>

上の例の出力は以下となります。

bool(false)

参考

  • libxml_clear_errors() - libxmlエラーハンドラをクリアする
  • libxml_get_errors() - エラー配列を取得する


SimpleXML

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 例
    • 基本的な SimpleXML の使用法
    • XML エラーの対応
  • SimpleXMLElement — SimpleXMLElement クラス
    • SimpleXMLElement::addAttribute — SimpleXML 要素に属性を追加する
    • SimpleXMLElement::addChild — XML ノードに子要素を追加する
    • SimpleXMLElement::asXML — SimpleXML 要素に基づき整形式の XML 文字列を返す
    • SimpleXMLElement::attributes — 要素の属性を定義する
    • SimpleXMLElement::children — 指定したノードの子ノードを見付ける
    • SimpleXMLElement::__construct — 新しい SimpleXMLElement オブジェクトを作成する
    • SimpleXMLElement::count — 子要素を数える
    • SimpleXMLElement::current — 現在の要素を返す
    • SimpleXMLElement::getDocNamespaces — ドキュメントで宣言されている名前空間を返す
    • SimpleXMLElement::getName — XML 要素の名前を取得する
    • SimpleXMLElement::getNamespaces — ドキュメントで使用している名前空間を返す
    • SimpleXMLElement::getChildren — 現在の要素の子要素を返す
    • SimpleXMLElement::hasChildren — 現在の要素が子要素を持つかどうかを調べる
    • SimpleXMLElement::key — 現在のキーを返す
    • SimpleXMLElement::next — 次の要素に移動する
    • SimpleXMLElement::registerXPathNamespace — 次の XPath クエリ用の prefix/ns コンテキストを作成する
    • SimpleXMLElement::rewind — 最初の要素に巻き戻す
    • SimpleXMLElement::saveXML — SimpleXMLElement::asXML のエイリアス
    • SimpleXMLElement::__toString — 文字列で要素の内容を返す
    • SimpleXMLElement::valid — 現在の要素が有効かどうかを調べる
    • SimpleXMLElement::xpath — XML データに Xpath クエリを実行する
  • SimpleXMLIterator — SimpleXMLIterator クラス
  • SimpleXML 関数
    • simplexml_import_dom — DOM ノードから SimpleXMLElement オブジェクトを取得する
    • simplexml_load_file — XMLファイルをパースし、オブジェクトに代入する
    • simplexml_load_string — XML 文字列をオブジェクトに代入する


はじめに

SimpleXML拡張モジュールは、 XMLをオブジェクトにとても簡単かつ容易に変換するための機能を 提供します。変換後のオブジェクトでは、 通常のプロパティセレクタや配列反復子を用いて処理を行うことが 可能です。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • SimpleXML
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-simplexml


  • ≪ インストール手順
  • 基本的な SimpleXML の使用法 ≫
  • PHP Manual
  • SimpleXML
  • 例

例

目次

  • 基本的な SimpleXML の使用法
  • XML エラーの対応


基本的な SimpleXML の使用法

このリファレンスの多くの例では XML 文字列が必要です。それぞれの例で この文字列をくり返す代わりに、あるファイルにこの文字列を保存して、 例ごとに読みこむことにします。この読みこまれるファイルは、以下の例 に関するセクションで使います。 もしくは、XMLドキュメントを作成し、 simplexml_load_file() により読みこむことも 可能です。

例1 XML 文字列を設定するインクルードファイル example.php

<?php
$xmlstr = <<<XML
<?xml version='1.0' standalone='yes'?>
<movies>
<movie>
<title>PHP: Behind the Parser</title>
<characters>
<character>
<name>Ms. Coder</name>
<actor>Onlivia Actora</actor>
</character>
<character>
<name>Mr. Coder</name>
<actor>El Act&#211;r</actor>
</character>
</characters>
<plot>
So, this language. It's like, a programming language. Or is it a
scripting language? All is revealed in this thrilling horror spoof
of a documentary.
</plot>
<great-lines>
<line>PHP solves all my web problems</line>
</great-lines>
<rating type="thumbs">7</rating>
<rating type="stars">5</rating>
</movie>
</movies>
XML;
?>

SimpleXML の容易さが最も明確に現われるのは、 簡単な XML ドキュメントから文字列または数字を展開する時です。

例2 <plot> を取得する

<?php
include 'example.php';

$movies = new SimpleXMLElement($xmlstr);

echo $movies->movie[0]->plot;
?>

上の例の出力は以下となります。

   So, this language. It's like, a programming language. Or is it a
   scripting language? All is revealed in this thrilling horror spoof
   of a documentary.

XML ドキュメント内の要素のうち、PHP の命名規約で許可されていない文字 (たとえばハイフンなど) を含む名前のものにアクセスするには、 要素名を括弧とアポストロフィで囲みます。

例3 <line> を取得する

<?php
include 'example.php';

$movies = new SimpleXMLElement($xmlstr);

echo $movies->movie->{'great-lines'}->line;
?>

上の例の出力は以下となります。

PHP solves all my web problems

例4 SimpleXML でユニークでない要素にアクセスする

単一の親要素の子要素としてある要素のインスタンスが複数存在する時、 通常の反復処理を適用することができます。

<?php
include 'example.php';

$movies = new SimpleXMLElement($xmlstr);

/* 個々の <character> ノードに対して、<name> を分割して表示します */
foreach ($movies->movie->characters->character as $character) {
echo $character->name, ' played by ', $character->actor, PHP_EOL;
}

?>

上の例の出力は以下となります。

Ms. Coder played by Onlivia Actora
Mr. Coder played by El ActOr

注意:

プロパティ (先ほどの例の $movies->movie) は配列ではありません。反復処理 と 配列形式でのアクセス ができるオブジェクトです。

例5 属性を使用する

ここまでは、要素の名前と値を読む方法のみを扱って来ました。 SimpleXML は要素の属性にアクセスすることも可能です。 要素の属性にアクセスする方法は、配列 の要素に アクセスするのと全く同じです。

<?php
include 'example.php';

$movies = new SimpleXMLElement($xmlstr);

/* 最初の映画の <rating> ノードにアクセスします。
* また、その評価も出力します。*/
foreach ($movies->movie[0]->rating as $rating) {
switch((string) $rating['type']) { // 要素のインデックスとして、属性を取得します
case 'thumbs':
echo $rating, ' thumbs up';
break;
case 'stars':
echo $rating, ' stars';
break;
}
}
?>

上の例の出力は以下となります。

7 thumbs up5 stars

例6 要素および属性をテキストと比較する

要素または属性を文字列と比較する、もしくは、文字列を引数とする関数に 渡すには、(string) により文字列にキャストする 必要があります。さもないと、PHP はこの要素をオブジェクトとして扱います。

<?php
include 'example.php';

$movies = new SimpleXMLElement($xmlstr);

if ((string) $movies->movie->title == 'PHP: Behind the Parser') {
print 'My favorite movie.';
}

echo htmlentities((string) $movies->movie->title);
?>

上の例の出力は以下となります。

My favorite movie.PHP: Behind the Parser

例7 ふたつの要素の比較

たとえ同一の要素を指していたとしても 2 つの SimpleXMLElements は異なるものと見なされます。

<?php
include 'example.php';

$movies1 = new SimpleXMLElement($xmlstr);
$movies2 = new SimpleXMLElement($xmlstr);
var_dump($movies1 == $movies2);
?>

上の例の出力は以下となります。

bool(false)

例8 XPath の使用

SimpleXML は、XPath を標準でサポートしています。 <character> 要素をすべて見つけるには、 以下のようにします。

<?php
include 'example.php';

$movies = new SimpleXMLElement($xmlstr);

foreach ($movies->xpath('//character') as $character) {
echo $character->name, ' played by ', $character->actor, PHP_EOL;
}
?>

'//' はワイルドカードとして動作します。絶対パスを指定するには、 スラッシュを一つだけにします。

上の例の出力は以下となります。

Ms. Coder played by Onlivia Actora
Mr. Coder played by El ActOr

例9 値を設定する

SimpleXMLの中のデータは、定数とすることができません。 オブジェクトは、その全ての要素について変更が可能です。

<?php
include 'example.php';
$movies = new SimpleXMLElement($xmlstr);

$movies->movie[0]->characters->character[0]->name = 'Miss Coder';

echo $movies->asXML();
?>

上の例の出力は以下となります。

<?xml version="1.0" standalone="yes"?>
<movies>
 <movie>
  <title>PHP: Behind the Parser</title>
  <characters>
   <character>
    <name>Miss Coder</name>
    <actor>Onlivia Actora</actor>
   </character>
   <character>
    <name>Mr. Coder</name>
    <actor>El Act&#xD3;r</actor>
   </character>
  </characters>
  <plot>
   So, this language. It's like, a programming language. Or is it a
   scripting language? All is revealed in this thrilling horror spoof
   of a documentary.
  </plot>
  <great-lines>
   <line>PHP solves all my web problems</line>
  </great-lines>
  <rating type="thumbs">7</rating>
  <rating type="stars">5</rating>
 </movie>
</movies>

例10 要素と属性を追加する

SimpleXML を使用して簡単に子要素および属性を追加することができます。

<?php
include 'example.php';
$movies = new SimpleXMLElement($xmlstr);

$character = $movies->movie[0]->characters->addChild('character');
$character->addChild('name', 'Mr. Parser');
$character->addChild('actor', 'John Doe');

$rating = $movies->movie[0]->addChild('rating', 'PG');
$rating->addAttribute('type', 'mpaa');

echo $movies->asXML();
?>

上の例の出力は以下となります。

<?xml version="1.0" standalone="yes"?>
<movies>
 <movie>
  <title>PHP: Behind the Parser</title>
  <characters>
   <character>
    <name>Ms. Coder</name>
    <actor>Onlivia Actora</actor>
   </character>
   <character>
    <name>Mr. Coder</name>
    <actor>El Act&#xD3;r</actor>
   </character>
  <character><name>Mr. Parser</name><actor>John Doe</actor></character></characters>
  <plot>
   So, this language. It's like, a programming language. Or is it a
   scripting language? All is revealed in this thrilling horror spoof
   of a documentary.
  </plot>
  <great-lines>
   <line>PHP solves all my web problems</line>
  </great-lines>
  <rating type="thumbs">7</rating>
  <rating type="stars">5</rating>
 <rating type="mpaa">PG</rating></movie>
</movies>

例11 DOM との相互運用性

PHP は、SimpleXML 形式と DOM 形式の間で XML ノードを変換する機構を有しています。 この例では、DOM 要素を SimpleXML に変換することができます。

<?php
$dom = new DOMDocument;
$dom->loadXML('<books><book><title>blah</title></book></books>');
if (!$dom) {
echo 'Error while parsing the document';
exit;
}

$books = simplexml_import_dom($dom);

echo $books->book[0]->title;
?>

上の例の出力は以下となります。

blah


XML エラーの対応

ドキュメント読み込み時の XML エラーに対処するのは非常にシンプルな作業です。 libxml の機能を使うと、 ドキュメント読み込み時のすべての XML エラーを抑制して後からそれを処理することができます。

libxml_get_errors() が返す libXMLError オブジェクトには、エラーについての message や line、 column (場所) といったプロパティが含まれます。

例1 壊れた XML 文字列の読み込み

<?php
libxml_use_internal_errors(true);
$sxe = simplexml_load_string("<?xml version='1.0'><broken><xml></broken>");
if ($sxe === false) {
echo "Failed loading XML\n";
foreach(libxml_get_errors() as $error) {
echo "\t", $error->message;
}
}
?>

上の例の出力は以下となります。

Failed loading XML
    Blank needed here
    parsing XML declaration: '?>' expected
    Opening and ending tag mismatch: xml line 1 and broken
    Premature end of data in tag broken line 1

参考

  • libxml_use_internal_errors()
  • libxml_get_errors()
  • LibXMLError


SimpleXMLElement クラス

(PHP 5, PHP 7, PHP 8)

はじめに

XML ドキュメントの要素をあらわします。

クラス概要

class SimpleXMLElement implements Stringable, Countable, RecursiveIterator {
/* メソッド */
public __construct(
string $data,
int $options = 0,
bool $dataIsURL = false,
string $namespaceOrPrefix = "",
bool $isPrefix = false
)
public addAttribute(string $qualifiedName, string $value, ?string $namespace = null): void
public addChild(string $qualifiedName, ?string $value = null, ?string $namespace = null): ?SimpleXMLElement
public asXML(?string $filename = null): string|bool
public attributes(?string $namespaceOrPrefix = null, bool $isPrefix = false): ?SimpleXMLElement
public children(?string $namespaceOrPrefix = null, bool $isPrefix = false): ?SimpleXMLElement
public count(): int
public current(): SimpleXMLElement
public getDocNamespaces(bool $recursive = false, bool $fromRoot = true): array|false
public getName(): string
public getNamespaces(bool $recursive = false): array
public getChildren(): ?SimpleXMLElement
public hasChildren(): bool
public key(): string
public next(): void
public registerXPathNamespace(string $prefix, string $namespace): bool
public rewind(): void
public __toString(): string
public valid(): bool
public xpath(string $expression): array|null|false
}

変更履歴

バージョン | 説明
8.0.0 | SimpleXMLElement は、 Stringable, Countable, RecursiveIterator を新たに実装しました。

目次

  • SimpleXMLElement::addAttribute — SimpleXML 要素に属性を追加する
  • SimpleXMLElement::addChild — XML ノードに子要素を追加する
  • SimpleXMLElement::asXML — SimpleXML 要素に基づき整形式の XML 文字列を返す
  • SimpleXMLElement::attributes — 要素の属性を定義する
  • SimpleXMLElement::children — 指定したノードの子ノードを見付ける
  • SimpleXMLElement::__construct — 新しい SimpleXMLElement オブジェクトを作成する
  • SimpleXMLElement::count — 子要素を数える
  • SimpleXMLElement::current — 現在の要素を返す
  • SimpleXMLElement::getDocNamespaces — ドキュメントで宣言されている名前空間を返す
  • SimpleXMLElement::getName — XML 要素の名前を取得する
  • SimpleXMLElement::getNamespaces — ドキュメントで使用している名前空間を返す
  • SimpleXMLElement::getChildren — 現在の要素の子要素を返す
  • SimpleXMLElement::hasChildren — 現在の要素が子要素を持つかどうかを調べる
  • SimpleXMLElement::key — 現在のキーを返す
  • SimpleXMLElement::next — 次の要素に移動する
  • SimpleXMLElement::registerXPathNamespace — 次の XPath クエリ用の prefix/ns コンテキストを作成する
  • SimpleXMLElement::rewind — 最初の要素に巻き戻す
  • SimpleXMLElement::saveXML — SimpleXMLElement::asXML のエイリアス
  • SimpleXMLElement::__toString — 文字列で要素の内容を返す
  • SimpleXMLElement::valid — 現在の要素が有効かどうかを調べる
  • SimpleXMLElement::xpath — XML データに Xpath クエリを実行する


SimpleXML 要素に属性を追加する

  • ≪ SimpleXMLElement
  • SimpleXMLElement::addChild ≫
  • PHP Manual
  • SimpleXMLElement
  • SimpleXML 要素に属性を追加する

SimpleXMLElement::addAttribute

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

SimpleXMLElement::addAttribute — SimpleXML 要素に属性を追加する

説明

public SimpleXMLElement::addAttribute(string $qualifiedName, string $value, ?string $namespace = null): void

SimpleXML 要素に属性を追加します。

パラメータ

qualifiedName

追加する属性の名前。

value

属性の値。

namespace

指定されている場合は、その属性が所属する名前空間。

戻り値

値を返しません。

例

注意:

この例では example.php をインクルードしていますが、これは 基本的な使用法 の最初のサンプルにある XML 文字列を参照しています。

例1 SimpleXML 要素への属性と子要素の追加

<?php

include 'example.php';

$sxe = new SimpleXMLElement($xmlstr);
$sxe->addAttribute('type', 'documentary');

$movie = $sxe->addChild('movie');
$movie->addChild('title', 'PHP2: More Parser Stories');
$movie->addChild('plot', 'This is all about the people who make it work.');

$characters = $movie->addChild('characters');
$character = $characters->addChild('character');
$character->addChild('name', 'Mr. Parser');
$character->addChild('actor', 'John Doe');

$rating = $movie->addChild('rating', '5');
$rating->addAttribute('type', 'stars');

echo $sxe->asXML();

?>

上の例の出力は、 たとえば以下のようになります。

<?xml version="1.0" standalone="yes"?>
<movies type="documentary">
 <movie>
  <title>PHP: Behind the Parser</title>
  <characters>
   <character>
    <name>Ms. Coder</name>
    <actor>Onlivia Actora</actor>
   </character>
   <character>
    <name>Mr. Coder</name>
    <actor>El Act&#xD3;r</actor>
   </character>
  </characters>
  <plot>
   So, this language. It's like, a programming language. Or is it a
   scripting language? All is revealed in this thrilling horror spoof
   of a documentary.
  </plot>
  <great-lines>
   <line>PHP solves all my web problems</line>
  </great-lines>
  <rating type="thumbs">7</rating>
  <rating type="stars">5</rating>
 </movie>
 <movie>
  <title>PHP2: More Parser Stories</title>
  <plot>This is all about the people who make it work.</plot>
  <characters>
   <character>
    <name>Mr. Parser</name>
    <actor>John Doe</actor>
   </character>
  </characters>
  <rating type="stars">5</rating>
 </movie>
</movies>

参考

  • SimpleXMLElement::addChild() - XML ノードに子要素を追加する
  • 基本的な SimpleXML の使用法


XML ノードに子要素を追加する

  • ≪ SimpleXMLElement::addAttribute
  • SimpleXMLElement::asXML ≫
  • PHP Manual
  • SimpleXMLElement
  • XML ノードに子要素を追加する

SimpleXMLElement::addChild

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

SimpleXMLElement::addChild — XML ノードに子要素を追加する

説明

public SimpleXMLElement::addChild(string $qualifiedName, ?string $value = null, ?string $namespace = null): ?SimpleXMLElement

ノードに子要素を追加し、子要素の SimpleXMLElement を返します。

パラメータ

qualifiedName

追加する子要素の名前。

value

指定されている場合は、子要素の値。

namespace

指定されている場合は、その子要素が所属する名前空間。

戻り値

addChild メソッドは、 XML ノードに追加した子要素を表す SimpleXMLElement オブジェクトを返します。 失敗時に null を返します。

例

注意:

この例では example.php をインクルードしていますが、これは 基本的な使用法 の最初のサンプルにある XML 文字列を参照しています。

例1 SimpleXML 要素への属性と子要素の追加

<?php

include 'example.php';

$sxe = new SimpleXMLElement($xmlstr);
$sxe->addAttribute('type', 'documentary');

$movie = $sxe->addChild('movie');
$movie->addChild('title', 'PHP2: More Parser Stories');
$movie->addChild('plot', 'This is all about the people who make it work.');

$characters = $movie->addChild('characters');
$character = $characters->addChild('character');
$character->addChild('name', 'Mr. Parser');
$character->addChild('actor', 'John Doe');

$rating = $movie->addChild('rating', '5');
$rating->addAttribute('type', 'stars');

echo $sxe->asXML();

?>

上の例の出力は、 たとえば以下のようになります。

<?xml version="1.0" standalone="yes"?>
<movies type="documentary">
 <movie>
  <title>PHP: Behind the Parser</title>
  <characters>
   <character>
    <name>Ms. Coder</name>
    <actor>Onlivia Actora</actor>
   </character>
   <character>
    <name>Mr. Coder</name>
    <actor>El Act&#xD3;r</actor>
   </character>
  </characters>
  <plot>
   So, this language. It's like, a programming language. Or is it a
   scripting language? All is revealed in this thrilling horror spoof
   of a documentary.
  </plot>
  <great-lines>
   <line>PHP solves all my web problems</line>
  </great-lines>
  <rating type="thumbs">7</rating>
  <rating type="stars">5</rating>
 </movie>
 <movie>
  <title>PHP2: More Parser Stories</title>
  <plot>This is all about the people who make it work.</plot>
  <characters>
   <character>
    <name>Mr. Parser</name>
    <actor>John Doe</actor>
   </character>
  </characters>
  <rating type="stars">5</rating>
 </movie>
</movies>

参考

  • SimpleXMLElement::addAttribute() - SimpleXML 要素に属性を追加する
  • 基本的な SimpleXML の使用法


SimpleXML 要素に基づき整形式の XML 文字列を返す

  • ≪ SimpleXMLElement::addChild
  • SimpleXMLElement::attributes ≫
  • PHP Manual
  • SimpleXMLElement
  • SimpleXML 要素に基づき整形式の XML 文字列を返す

SimpleXMLElement::asXML

(PHP 5, PHP 7, PHP 8)

SimpleXMLElement::asXML — SimpleXML 要素に基づき整形式の XML 文字列を返す

説明

public SimpleXMLElement::asXML(?string $filename = null): string|bool

asXML メソッドは、親オブジェクトのデータを XML version 1.0 形式にフォーマットします。

パラメータ

filename

文字列を指定した場合、データを返すかわりにファイルにデータを書き込みます。

戻り値

filename が指定されていない場合、この関数は 成功時に string 、エラー時に false を返します。 パラメータが指定されていた場合は、ファイルが正常に書き込めたときに true 、そうでないときに false を返します。

変更履歴

バージョン | 説明
8.0.0 | filename は、nullable になりました。

例

例1 XML を取得する

<?php
$string = <<<XML
<a>
<b>
<c>text</c>
<c>stuff</c>
</b>
<d>
<c>code</c>
</d>
</a>
XML;

$xml = new SimpleXMLElement($string);

echo $xml->asXML();

?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<a>
 <b>
  <c>text</c>
  <c>stuff</c>
 </b>
 <d>
  <c>code</c>
 </d>
</a>

asXML は Xpath の結果にも適用できます:

例2 SimpleXMLElement::xpath() の結果に asXML() を使用する

<?php
// 上の XML の例から続く

/* <a><b><c>を探す */
$result = $xml->xpath('/a/b/c');

foreach ($result as $node) {
echo $node->asXML();
}
?>

上の例の出力は以下となります。

<c>text</c><c>stuff</c>

参考

  • SimpleXMLElement::__toString() - 文字列で要素の内容を返す
  • 基本的な SimpleXML の使用法


要素の属性を定義する

  • ≪ SimpleXMLElement::asXML
  • SimpleXMLElement::children ≫
  • PHP Manual
  • SimpleXMLElement
  • 要素の属性を定義する

SimpleXMLElement::attributes

(PHP 5, PHP 7, PHP 8)

SimpleXMLElement::attributes — 要素の属性を定義する

説明

public SimpleXMLElement::attributes(?string $namespaceOrPrefix = null, bool $isPrefix = false): ?SimpleXMLElement

この関数は、XMLタグの中で定義された属性とその値を取得します。

注意: SimpleXML では、ほとんどのメソッドに反復処理を追加するための手順が定義されています。 これらは、var_dump() やオブジェクトを評価する他の手段で 見ることはできません。

パラメータ

namespaceOrPrefix

オプションで指定する、取得した属性の名前空間。

isPrefix

デフォルトは false。

戻り値

SimpleXMLElement オブジェクトを返します。 これを反復処理すれば、そのタグの属性を順に処理することができます。

タグではなく属性を指している SimpleXMLElement に対してコールした場合は null を返します。

例

例1 XML文字列を解釈する

<?php
$string = <<<XML
<a>
<foo name="one" game="lonely">1</foo>
</a>
XML;

$xml = simplexml_load_string($string);
foreach($xml->foo[0]->attributes() as $a => $b) {
echo $a,'="',$b,"\"\n";
}
?>

上の例の出力は以下となります。

name="one"
game="lonely"

参考

  • 基本的な SimpleXML の使用法


指定したノードの子ノードを見付ける

  • ≪ SimpleXMLElement::attributes
  • SimpleXMLElement::__construct ≫
  • PHP Manual
  • SimpleXMLElement
  • 指定したノードの子ノードを見付ける

SimpleXMLElement::children

(PHP 5, PHP 7, PHP 8)

SimpleXMLElement::children — 指定したノードの子ノードを見付ける

説明

public SimpleXMLElement::children(?string $namespaceOrPrefix = null, bool $isPrefix = false): ?SimpleXMLElement

このメソッドは、指定した要素の子を見つけます。 結果は、通常の反復子により取得できます。

注意: SimpleXML では、ほとんどのメソッドに反復処理を追加するための手順が定義されています。 これらは、var_dump() やオブジェクトを評価する他の手段で 見ることはできません。

パラメータ

namespaceOrPrefix

XML 名前空間。

isPrefix

isPrefix が true の場合は namespaceOrPrefix をプレフィックスとして扱います。false の場合は namespaceOrPrefix を名前空間 URL として扱います。

戻り値

ノードが子を持つかどうかにかかわらず SimpleXMLElement 要素を返します。 ノードが属性である場合は、null を返します。

例

例1 children() 疑似配列を走査する

<?php
$xml = new SimpleXMLElement(
'<person>
<child role="son">
<child role="daughter"/>
</child>
<child role="daughter">
<child role="son">
<child role="son"/>
</child>
</child>
</person>');

foreach ($xml->children() as $second_gen) {
echo ' The person begot a ' . $second_gen['role'];

foreach ($second_gen->children() as $third_gen) {
echo ' who begot a ' . $third_gen['role'] . ';';

foreach ($third_gen->children() as $fourth_gen) {
echo ' and that ' . $third_gen['role'] .
' begot a ' . $fourth_gen['role'];
}
}
}
?>

上の例の出力は以下となります。

The person begot a son who begot a daughter; The person
begot a daughter who begot a son; and that son begot a son

例2 名前空間の使用

<?php
$xml = '<example xmlns:foo="my.foo.urn">
<foo:a>Apple</foo:a>
<foo:b>Banana</foo:b>
<c>Cherry</c>
</example>';

$sxe = new SimpleXMLElement($xml);

$kids = $sxe->children('foo');
var_dump(count($kids));

$kids = $sxe->children('foo', TRUE);
var_dump(count($kids));

$kids = $sxe->children('my.foo.urn');
var_dump(count($kids));

$kids = $sxe->children('my.foo.urn', TRUE);
var_dump(count($kids));

$kids = $sxe->children();
var_dump(count($kids));
?>
int(0)
int(2)
int(2)
int(0)
int(1)

参考

  • SimpleXMLElement::count() - 子要素を数える
  • count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える


新しい SimpleXMLElement オブジェクトを作成する

  • ≪ SimpleXMLElement::children
  • SimpleXMLElement::count ≫
  • PHP Manual
  • SimpleXMLElement
  • 新しい SimpleXMLElement オブジェクトを作成する

SimpleXMLElement::__construct

(PHP 5, PHP 7, PHP 8)

SimpleXMLElement::__construct — 新しい SimpleXMLElement オブジェクトを作成する

説明

public SimpleXMLElement::__construct(
string $data,
int $options = 0,
bool $dataIsURL = false,
string $namespaceOrPrefix = "",
bool $isPrefix = false
)

新しい SimpleXMLElement オブジェクトを作成します。

パラメータ

data

整形式 XML 文字列。 もし dataIsURL が true の場合には、XML ドキュメントへのパスあるいは URL。

options

オプションで、XML文書を読み込む場合に影響する 追加の Libxml パラメータを指定するために使います。 XML文書を出力する場合に影響するオプション(例: LIBXML_NOEMPTYTAG) は静かに無視されます。

注意:

深くネストされた XML や巨大なテキストノードを処理する際には LIBXML_PARSEHUGE を指定することになるでしょう。

dataIsURL

デフォルトでは dataIsURL は false です。 data が、文字列データではなく XML ドキュメントへのパスあるいは URL である場合に true を使用します。

namespaceOrPrefix

名前空間プレフィックスあるいは URI。

isPrefix

namespaceOrPrefix がプレフィックスの場合は true、 URI の場合は false。デフォルトは false。

エラー / 例外

XML データ内でエラーが見つかるたびに E_WARNING エラーメッセージが発生します。さらに、XML データのパースに失敗した場合は例外をスローします。

ヒント

libxml_use_internal_errors() ですべての XML エラーを抑制し、 後から libxml_get_errors() で取得することもできます。

例

注意:

この例では example.php をインクルードしていますが、これは 基本的な使用法 の最初のサンプルにある XML 文字列を参照しています。

例1 SimpleXMLElement オブジェクトの作成

<?php

include 'example.php';

$sxe = new SimpleXMLElement($xmlstr);
echo $sxe->movie[0]->title;

?>

上の例の出力は以下となります。

PHP: Behind the Parser

例2 URL からの SimpleXMLElement オブジェクトの作成

<?php

$sxe = new SimpleXMLElement('http://example.org/document.xml', 0, true);
echo $sxe->asXML();

?>

参考

  • 基本的な SimpleXML の使用法
  • simplexml_load_string() - XML 文字列をオブジェクトに代入する
  • simplexml_load_file() - XMLファイルをパースし、オブジェクトに代入する
  • XML エラーの対応
  • libxml_use_internal_errors() - libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする
  • libxml_set_streams_context() - 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する


子要素を数える

  • ≪ SimpleXMLElement::__construct
  • SimpleXMLElement::current ≫
  • PHP Manual
  • SimpleXMLElement
  • 子要素を数える

SimpleXMLElement::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SimpleXMLElement::count — 子要素を数える

説明

public SimpleXMLElement::count(): int

このメソッドは、子要素を数えます。

パラメータ

この関数にはパラメータはありません。

戻り値

子要素の数を返します。

例

例1 子要素の数の取得

<?php
$xml = <<<EOF
<people>
<person name="Person 1">
<child/>
<child/>
<child/>
</person>
<person name="Person 2">
<child/>
<child/>
<child/>
<child/>
<child/>
</person>
</people>
EOF;

$elem = new SimpleXMLElement($xml);

foreach ($elem as $person) {
printf("%s has got %d children.\n", $person['name'], $person->count());
}
?>

上の例の出力は以下となります。

Person 1 has got 3 children.
Person 2 has got 5 children.

参考

  • SimpleXMLElement::children() - 指定したノードの子ノードを見付ける


現在の要素を返す

  • ≪ SimpleXMLElement::count
  • SimpleXMLElement::getDocNamespaces ≫
  • PHP Manual
  • SimpleXMLElement
  • 現在の要素を返す

SimpleXMLElement::current

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::current — 現在の要素を返す

説明

public SimpleXMLElement::current(): SimpleXMLElement
警告

PHP 8.0 より前のバージョンでは、 SimpleXMLElement::current() はサブクラスの SimpleXMLIterator でのみ宣言されていました。

このメソッドは、現在の要素の SimpleXMLElement を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

このメソッドは、現在の要素の SimpleXMLElement を返します。

エラー / 例外

失敗した場合は Error をスローします。

変更履歴

バージョン | 説明
8.1.0 | SimpleXMLElement::current() に不正なイテレータを渡してコールすると、 Error をスローするようになりました。 これより前のバージョンでは、null を返していました。

例

例1 現在の要素を返す

<?php
$xmlElement = new SimpleXMLElement('<books><book>PHP basics</book><book>XML basics</book></books>');

$xmlElement->rewind(); // 最初の要素に巻き戻します。こうしないと current() は動作しません。
var_dump($xmlElement->current());
?>

上の例の出力は以下となります。

object(SimpleXMLElement)#2 (1) {
  [0]=>
  string(10) "PHP basics"
}

参考

  • SimpleXMLElement::key() - 現在のキーを返す
  • SimpleXMLElement::next() - 次の要素に移動する
  • SimpleXMLElement::rewind() - 最初の要素に巻き戻す
  • SimpleXMLElement::valid() - 現在の要素が有効かどうかを調べる
  • SimpleXMLElement


ドキュメントで宣言されている名前空間を返す

  • ≪ SimpleXMLElement::current
  • SimpleXMLElement::getName ≫
  • PHP Manual
  • SimpleXMLElement
  • ドキュメントで宣言されている名前空間を返す

SimpleXMLElement::getDocNamespaces

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SimpleXMLElement::getDocNamespaces — ドキュメントで宣言されている名前空間を返す

説明

public SimpleXMLElement::getDocNamespaces(bool $recursive = false, bool $fromRoot = true): array|false

ドキュメントで宣言されている名前空間を返します。

パラメータ

recursive

指定されている場合は、親ノードおよび子ノードで宣言されている全ての名前空間を返します。 されていない場合は、ルートノードで宣言されている名前空間のみを返します。

fromRoot

XML 文書のルートノードからでなく、子ノードの配下の名前空間を再帰的にチェックできるようにします。

戻り値

getDocNamespaces メソッドは、 名前空間名および関連付けられた URI を配列で返します。

例

例1 ドキュメントの名前空間の取得

<?php

$xml = <<<XML
<?xml version="1.0" standalone="yes"?>
<people xmlns:p="http://example.org/ns">
<p:person id="1">John Doe</p:person>
<p:person id="2">Susie Q. Public</p:person>
</people>
XML;

$sxe = new SimpleXMLElement($xml);

$namespaces = $sxe->getDocNamespaces();
var_dump($namespaces);

?>

上の例の出力は以下となります。

array(1) {
   ["p"]=>
   string(21) "http://example.org/ns"
}

例2 複数の名前空間での動作

<?php

$xml = <<<XML
<?xml version="1.0" standalone="yes"?>
<people xmlns:p="http://example.org/ns" xmlns:t="http://example.org/test">
<p:person t:id="1">John Doe</p:person>
<p:person t:id="2" a:addr="123 Street" xmlns:a="http://example.org/addr">
Susie Q. Public
</p:person>
</people>
XML;

$sxe = new SimpleXMLElement($xml);

$namespaces = $sxe->getDocNamespaces(TRUE);
var_dump($namespaces);

?>

上の例の出力は以下となります。

array(3) {
  ["p"]=>
  string(21) "http://example.org/ns"
  ["t"]=>
  string(23) "http://example.org/test"
  ["a"]=>
  string(23) "http://example.org/addr"
}

参考

  • SimpleXMLElement::getNamespaces() - ドキュメントで使用している名前空間を返す
  • SimpleXMLElement::registerXPathNamespace() - 次の XPath クエリ用の prefix/ns コンテキストを作成する


XML 要素の名前を取得する

  • ≪ SimpleXMLElement::getDocNamespaces
  • SimpleXMLElement::getNamespaces ≫
  • PHP Manual
  • SimpleXMLElement
  • XML 要素の名前を取得する

SimpleXMLElement::getName

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

SimpleXMLElement::getName — XML 要素の名前を取得する

説明

public SimpleXMLElement::getName(): string

XML 要素の名前を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

getName メソッドは、 SimpleXMLElement オブジェクトが参照している XML タグの名前を string で返します。

例

注意:

この例では example.php をインクルードしていますが、これは 基本的な使用法 の最初のサンプルにある XML 文字列を参照しています。

例1 XML 要素の名前の取得

<?php
include 'example.php';
$sxe = new SimpleXMLElement($xmlstr);

echo $sxe->getName() . "\n";

foreach ($sxe->children() as $child)
{
echo $child->getName() . "\n";
}

?>

上の例の出力は以下となります。

movies
movie


ドキュメントで使用している名前空間を返す

  • ≪ SimpleXMLElement::getName
  • SimpleXMLElement::getChildren ≫
  • PHP Manual
  • SimpleXMLElement
  • ドキュメントで使用している名前空間を返す

SimpleXMLElement::getNamespaces

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

SimpleXMLElement::getNamespaces — ドキュメントで使用している名前空間を返す

説明

public SimpleXMLElement::getNamespaces(bool $recursive = false): array

ドキュメントで使用している名前空間を返します。

パラメータ

recursive

指定されている場合は、親ノードおよび子ノードで使用している全ての名前空間を返します。 されていない場合は、ルートノードで使用している名前空間のみを返します。

戻り値

getNamespaces メソッドは、 名前空間名および関連付けられた URI を配列で返します。

例

例1 ドキュメントで使用している名前空間の取得

<?php

$xml = <<<XML
<?xml version="1.0" standalone="yes"?>
<people xmlns:p="http://example.org/ns" xmlns:t="http://example.org/test">
<p:person id="1">John Doe</p:person>
<p:person id="2">Susie Q. Public</p:person>
</people>
XML;

$sxe = new SimpleXMLElement($xml);

$namespaces = $sxe->getNamespaces(true);
var_dump($namespaces);

?>

上の例の出力は以下となります。

array(1) {
  ["p"]=>
  string(21) "http://example.org/ns"
}

参考

  • SimpleXMLElement::getDocNamespaces() - ドキュメントで宣言されている名前空間を返す
  • SimpleXMLElement::registerXPathNamespace() - 次の XPath クエリ用の prefix/ns コンテキストを作成する


現在の要素の子要素を返す

  • ≪ SimpleXMLElement::getNamespaces
  • SimpleXMLElement::hasChildren ≫
  • PHP Manual
  • SimpleXMLElement
  • 現在の要素の子要素を返す

SimpleXMLElement::getChildren

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::getChildren — 現在の要素の子要素を返す

説明

public SimpleXMLElement::getChildren(): ?SimpleXMLElement
警告

PHP 8.0 より前のバージョンでは、 SimpleXMLElement::getChildren() は サブクラスの SimpleXMLIterator でのみ宣言されていました。

このメソッドは、現在の SimpleXMLElement 要素の子要素を含む SimpleXMLElement オブジェクトを返します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素の子要素を含む SimpleXMLElement オブジェクトを返します。

例

例1 現在の要素の子要素を返す

<?php
$xml = <<<XML
<books>
<book>
<title>PHP Basics</title>
<author>Jim Smith</author>
</book>
<book>XML basics</book>
</books>
XML;

$xmlElement = new SimpleXMLElement($xml);
for ($xmlElement->rewind(); $xmlElement->valid(); $xmlElement->next()) {
foreach($xmlElement->getChildren() as $name => $data) {
echo "The $name is '$data' from the class " . get_class($data) . "\n";
}
}
?>

上の例の出力は以下となります。

The title is 'PHP Basics' from the class SimpleXMLElement
The author is 'Jim Smith' from the class SimpleXMLElement


現在の要素が子要素を持つかどうかを調べる

  • ≪ SimpleXMLElement::getChildren
  • SimpleXMLElement::key ≫
  • PHP Manual
  • SimpleXMLElement
  • 現在の要素が子要素を持つかどうかを調べる

SimpleXMLElement::hasChildren

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::hasChildren — 現在の要素が子要素を持つかどうかを調べる

説明

public SimpleXMLElement::hasChildren(): bool
警告

PHP 8.0 より前のバージョンでは、 SimpleXMLElement::hasChildren() は サブクラスの SimpleXMLIterator でのみ宣言されていました。

このメソッドは、現在の SimpleXMLElement 要素が子要素を持つかどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素が子要素を持つ場合に true、それ以外の場合に false を返します。

例

例1 現在の要素が子要素を持つかどうかを調べる

<?php
$xml = <<<XML
<books>
<book>
<title>PHP Basics</title>
<author>Jim Smith</author>
</book>
<book>XML basics</book>
</books>
XML;

$xmlElement = new SimpleXMLElement($xml);
for ($xmlElement->rewind(); $xmlElement->valid(); $xmlElement->next()) {
if ($xmlElement->hasChildren()) {
var_dump($xmlElement->current());
}
}
?>

上の例の出力は以下となります。

object(SimpleXMLElement)#2 (2) {
  ["title"]=>
  string(10) "PHP Basics"
  ["author"]=>
  string(9) "Jim Smith"
}


現在のキーを返す

  • ≪ SimpleXMLElement::hasChildren
  • SimpleXMLElement::next ≫
  • PHP Manual
  • SimpleXMLElement
  • 現在のキーを返す

SimpleXMLElement::key

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::key — 現在のキーを返す

説明

public SimpleXMLElement::key(): string
警告

PHP 8.0 より前のバージョンでは、 SimpleXMLElement::key() はサブクラスの SimpleXMLIterator でのみ宣言されていました。

このメソッドは、現在の要素の XML タグ名を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の SimpleXMLElement オブジェクトが参照する要素の XML タグ名を返します。

エラー / 例外

失敗した場合にError をスローします。

変更履歴

バージョン | 説明
8.1.0 | SimpleXMLElement::key() を不正なイテレータを渡してコールすると、 Error をスローするようになりました。 これより前のバージョンでは、false を返していました。

例

例1 現在の XML タグキーの取得

<?php
$xmlElement = new SimpleXMLElement('<books><book>PHP basics</book><book>XML basics</book></books>');

echo var_dump($xmlElement->key());
$xmlElement->rewind(); // 最初の要素に巻き戻します
echo var_dump($xmlElement->key());

?>

上の例の出力は以下となります。

bool(false)
string(4) "book"


次の要素に移動する

  • ≪ SimpleXMLElement::key
  • SimpleXMLElement::registerXPathNamespace ≫
  • PHP Manual
  • SimpleXMLElement
  • 次の要素に移動する

SimpleXMLElement::next

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::next — 次の要素に移動する

説明

public SimpleXMLElement::next(): void

このメソッドは、SimpleXMLElement を次の要素に移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 次の要素への移動

<?php
$xmlElement = new SimpleXMLElement('<books><book>PHP Basics</book><book>XML basics</book></books>');
$xmlElement->rewind(); // 最初の要素に巻き戻します
$xmlElement->next();

var_dump($xmlElement->current());
?>

上の例の出力は以下となります。

object(SimpleXMLElement)#2 (1) {
  [0]=>
  string(10) "XML basics"
}


次の XPath クエリ用の prefix/ns コンテキストを作成する

  • ≪ SimpleXMLElement::next
  • SimpleXMLElement::rewind ≫
  • PHP Manual
  • SimpleXMLElement
  • 次の XPath クエリ用の prefix/ns コンテキストを作成する

SimpleXMLElement::registerXPathNamespace

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

SimpleXMLElement::registerXPathNamespace — 次の XPath クエリ用の prefix/ns コンテキストを作成する

説明

public SimpleXMLElement::registerXPathNamespace(string $prefix, string $namespace): bool

次の XPath クエリ用の prefix/ns コンテキストを作成します。特にこれが有用なのは、 XML ドキュメントの提供者が名前空間プレフィックスを変更したような場合です。 registerXPathNamespace はプレフィックスを作成して名前空間に関連付け、 そのプレフィックスで名前空間のノードにアクセスできるようにします。 提供者側がプレフィックスを変更したとしても、コードを書き換える必要はありません。

パラメータ

prefix

ns で指定した名前空間への XPath クエリで使用する、 名前空間プレフィックス。

ns

XPath クエリで使用する名前空間。 これは XML ドキュメントで使用している名前空間と一致していなければなりません。 一致していない場合、prefix を使用した XPath クエリは何も結果を返しません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 XPath クエリで使用する名前空間プレフィックスの設定

<?php

$xml = <<<EOD
<book xmlns:chap="http://example.org/chapter-title">
<title>My Book</title>
<chapter id="1">
<chap:title>Chapter 1</chap:title>
<para>Donec velit. Nullam eget tellus vitae tortor gravida scelerisque.
In orci lorem, cursus imperdiet, ultricies non, hendrerit et, orci.
Nulla facilisi. Nullam velit nisl, laoreet id, condimentum ut,
ultricies id, mauris.</para>
</chapter>
<chapter id="2">
<chap:title>Chapter 2</chap:title>
<para>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin
gravida. Phasellus tincidunt massa vel urna. Proin adipiscing quam
vitae odio. Sed dictum. Ut tincidunt lorem ac lorem. Duis eros
tellus, pharetra id, faucibus eu, dapibus dictum, odio.</para>
</chapter>
</book>
EOD;

$sxe = new SimpleXMLElement($xml);

$sxe->registerXPathNamespace('c', 'http://example.org/chapter-title');
$result = $sxe->xpath('//c:title');

foreach ($result as $title) {
echo $title . "\n";
}

?>

上の例の出力は以下となります。

Chapter 1
Chapter 2

上の例の XML ドキュメントでは、プレフィックス chap で名前空間を指定していることを確認しておきましょう。仮に、このドキュメント (あるいはよく似た別のドキュメント) が以前に同じ名前空間に対してプレフィックス c を使用していたとしましょう。プレフィックスが変わった時点で、 これまでの XPath クエリは正しい値を返さないようになります。 そしてクエリに対して何らかの変更が必要となります。 registerXPathNamespace を使用すると、 仮に名前空間プレフィックスが変更された場合でもクエリの変更する必要がなくなります。

参考

  • SimpleXMLElement::xpath() - XML データに Xpath クエリを実行する
  • SimpleXMLElement::getDocNamespaces() - ドキュメントで宣言されている名前空間を返す
  • SimpleXMLElement::getNamespaces() - ドキュメントで使用している名前空間を返す


最初の要素に巻き戻す

  • ≪ SimpleXMLElement::registerXPathNamespace
  • SimpleXMLElement::saveXML ≫
  • PHP Manual
  • SimpleXMLElement
  • 最初の要素に巻き戻す

SimpleXMLElement::rewind

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::rewind — 最初の要素に巻き戻す

説明

public SimpleXMLElement::rewind(): void

このメソッドは、SimpleXMLElement を最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 最初の要素に巻き戻す

<?php
$xmlElement = new SimpleXMLElement('<books><book>PHP Basics</book><book>XML Basics</book></books>');
$xmlElement->rewind();

var_dump($xmlElement->current());
?>

上の例の出力は以下となります。

object(SimpleXMLElement)#2 (1) {
  [0]=>
  string(10) "PHP Basics"
}


SimpleXMLElement::asXML のエイリアス

  • ≪ SimpleXMLElement::rewind
  • SimpleXMLElement::__toString ≫
  • PHP Manual
  • SimpleXMLElement
  • SimpleXMLElement::asXML のエイリアス

SimpleXMLElement::saveXML

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

SimpleXMLElement::saveXML — SimpleXMLElement::asXML() のエイリアス

説明

このメソッドは次のメソッドのエイリアスです。 SimpleXMLElement::asXML()


文字列で要素の内容を返す

  • ≪ SimpleXMLElement::saveXML
  • SimpleXMLElement::valid ≫
  • PHP Manual
  • SimpleXMLElement
  • 文字列で要素の内容を返す

SimpleXMLElement::__toString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SimpleXMLElement::__toString — 文字列で要素の内容を返す

説明

public SimpleXMLElement::__toString(): string

この要素に直接入っているテキストの内容を返します。 この要素の子要素の内部にあるテキストの内容を返してはいけません。

パラメータ

この関数にはパラメータはありません。

戻り値

成功したときは、テキストの内容を文字列で返します。 失敗したときは空文字列を返します。

例

例1 文字列で内容を取得する

<?php
$xml = new SimpleXMLElement('<a>1 <b>2 </b>3</a>');
echo $xml;
?>

上の例の出力は以下となります。

1 3

参考

  • SimpleXMLElement::asXML() - SimpleXML 要素に基づき整形式の XML 文字列を返す


現在の要素が有効かどうかを調べる

  • ≪ SimpleXMLElement::__toString
  • SimpleXMLElement::xpath ≫
  • PHP Manual
  • SimpleXMLElement
  • 現在の要素が有効かどうかを調べる

SimpleXMLElement::valid

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

SimpleXMLElement::valid — 現在の要素が有効かどうかを調べる

説明

public SimpleXMLElement::valid(): bool

このメソッドは、現在の要素が SimpleXMLElement::rewind() あるいは SimpleXMLElement::next() をコールした後で有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在の要素が有効な場合に true、そうでない場合に false を返します。

例

例1 現在の要素が有効かどうかを調べる

<?php
$xmlElement = new SimpleXMLElement('<books><book>SQL Basics</book></books>');
$xmlElement->rewind(); // 最初の要素に巻き戻します
echo var_dump($xmlElement->valid()); // bool(true)
$xmlElement->next(); // 次の要素に進めます
echo var_dump($xmlElement->valid()); // 要素がひとつしかないので bool(false) となります
?>


XML データに Xpath クエリを実行する

  • ≪ SimpleXMLElement::valid
  • SimpleXMLIterator ≫
  • PHP Manual
  • SimpleXMLElement
  • XML データに Xpath クエリを実行する

SimpleXMLElement::xpath

(PHP 5, PHP 7, PHP 8)

SimpleXMLElement::xpath — XML データに Xpath クエリを実行する

説明

public SimpleXMLElement::xpath(string $expression): array|null|false

xpathメソッドは、 XPath expressionにマッチする SimpleXML ノードを検索します。

パラメータ

expression

XPath パス。

戻り値

SimpleXMLElement オブジェクトの配列を返します。 エラーが発生した場合は null または false を返します。

例

例1 Xpath

<?php
$string = <<<XML
<a>
<b>
<c>text</c>
<c>stuff</c>
</b>
<d>
<c>code</c>
</d>
</a>
XML;

$xml = new SimpleXMLElement($string);

/* <a><b><c> を探します */
$result = $xml->xpath('/a/b/c');

foreach ($result as $node) {
echo '/a/b/c: ',$node,"\n";
}

/* 相対パスでも動作します... */
$result = $xml->xpath('b/c');

foreach ($result as $node) {
echo 'b/c: ',$node,"\n";
}
?>

上の例の出力は以下となります。

/a/b/c: text
/a/b/c: stuff
b/c: text
b/c: stuff

これら二つの結果は同じであることに注意してください。

参考

  • SimpleXMLElement::registerXPathNamespace() - 次の XPath クエリ用の prefix/ns コンテキストを作成する
  • SimpleXMLElement::getDocNamespaces() - ドキュメントで宣言されている名前空間を返す
  • SimpleXMLElement::getNamespaces() - ドキュメントで使用している名前空間を返す
  • 基本的な SimpleXML の使用法


SimpleXMLIterator クラス

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

はじめに

SimpleXMLIterator は、SimpleXMLElement オブジェクトのすべてのノードに対する再帰的な反復処理を提供します。

クラス概要

class SimpleXMLIterator extends SimpleXMLElement {
/* 継承したメソッド */
public SimpleXMLElement::__construct(
string $data,
int $options = 0,
bool $dataIsURL = false,
string $namespaceOrPrefix = "",
bool $isPrefix = false
)
public SimpleXMLElement::addAttribute(string $qualifiedName, string $value, ?string $namespace = null): void
public SimpleXMLElement::addChild(string $qualifiedName, ?string $value = null, ?string $namespace = null): ?SimpleXMLElement
public SimpleXMLElement::asXML(?string $filename = null): string|bool
public SimpleXMLElement::attributes(?string $namespaceOrPrefix = null, bool $isPrefix = false): ?SimpleXMLElement
public SimpleXMLElement::children(?string $namespaceOrPrefix = null, bool $isPrefix = false): ?SimpleXMLElement
public SimpleXMLElement::count(): int
public SimpleXMLElement::current(): SimpleXMLElement
public SimpleXMLElement::getDocNamespaces(bool $recursive = false, bool $fromRoot = true): array|false
public SimpleXMLElement::getName(): string
public SimpleXMLElement::getNamespaces(bool $recursive = false): array
public SimpleXMLElement::getChildren(): ?SimpleXMLElement
public SimpleXMLElement::hasChildren(): bool
public SimpleXMLElement::key(): string
public SimpleXMLElement::next(): void
public SimpleXMLElement::registerXPathNamespace(string $prefix, string $namespace): bool
public SimpleXMLElement::rewind(): void
public SimpleXMLElement::__toString(): string
public SimpleXMLElement::valid(): bool
public SimpleXMLElement::xpath(string $expression): array|null|false
}

変更履歴

バージョン | 説明
8.0.0 | イテレータのメソッド (SimpleXMLIterator::hasChildren(), SimpleXMLIterator::getChildren(), SimpleXMLIterator::current(), SimpleXMLIterator::key(), SimpleXMLIterator::next(),SimpleXMLIterator::rewind(), SimpleXMLIterator::valid()) は、SimpleXMLElement に移動しました。
8.0.0 | SimpleXMLIterator は、 Stringable を新たに実装しました。


SimpleXML 関数

目次

  • simplexml_import_dom — DOM ノードから SimpleXMLElement オブジェクトを取得する
  • simplexml_load_file — XMLファイルをパースし、オブジェクトに代入する
  • simplexml_load_string — XML 文字列をオブジェクトに代入する


DOM ノードから SimpleXMLElement オブジェクトを取得する

  • ≪ SimpleXML 関数
  • simplexml_load_file ≫
  • PHP Manual
  • SimpleXML 関数
  • DOM ノードから SimpleXMLElement オブジェクトを取得する

simplexml_import_dom

(PHP 5, PHP 7, PHP 8)

simplexml_import_dom — DOM ノードから SimpleXMLElement オブジェクトを取得する

説明

simplexml_import_dom(object $node, ?string $class_name = SimpleXMLElement::class): ?SimpleXMLElement

この関数は、DOM ドキュメントのノードを引数とし、 SimpleXML ノードを作成します。この新しいオブジェクトは、 この後、通常の SimpleXML 要素として使用できます。

パラメータ

node

DOM 要素ノード。

class_name

このオプションパラメータを使用すると、 simplexml_import_dom() は指定したクラスのオブジェクトを返します。このクラスは SimpleXMLElement を継承していなければなりません。

戻り値

SimpleXMLElement を返します。 失敗時に null を返します。

例

例1 DOM のインポート

<?php
$dom = new DOMDocument;
$dom->loadXML('<books><book><title>blah</title></book></books>');
if (!$dom) {
echo 'ドキュメントのパース時にエラーが発生しました';
exit;
}

$s = simplexml_import_dom($dom);

echo $s->book[0]->title;
?>

上の例の出力は以下となります。

blah

参考

  • dom_import_simplexml() - SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する
  • 基本的な SimpleXML の使用法


XMLファイルをパースし、オブジェクトに代入する

  • ≪ simplexml_import_dom
  • simplexml_load_string ≫
  • PHP Manual
  • SimpleXML 関数
  • XMLファイルをパースし、オブジェクトに代入する

simplexml_load_file

(PHP 5, PHP 7, PHP 8)

simplexml_load_file — XMLファイルをパースし、オブジェクトに代入する

説明

simplexml_load_file(
string $filename,
?string $class_name = SimpleXMLElement::class,
int $options = 0,
string $namespace_or_prefix = "",
bool $is_prefix = false
): SimpleXMLElement|false

指定したファイルの中の整形式 XML ドキュメントをオブジェクトに変換します。

パラメータ

filename

XML ファイルへのパス。

class_name

simplexml_load_file() が指定されたクラスのオブジェクトを返すようにするために、 このオプションのパラメータを使用します。 このクラスは、SimpleXMLElement クラスを継承していなければなりません。

options

追加の Libxml パラメータ を、ビット演算子の OR で指定します。

namespace_or_prefix

名前空間プレフィックスあるいは URI。

is_prefix

namespace_or_prefix がプレフィックスである場合に true、 URI である場合に false。デフォルトは false です。

戻り値

SimpleXMLElement クラスのオブジェクトを返します。 XML ドキュメント内のデータをプロパティに含みます。 失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

エラー / 例外

XML データ内でエラーが見つかるたびに E_WARNING エラーメッセージが発生します。

ヒント

libxml_use_internal_errors() ですべての XML エラーを抑制し、 後から libxml_get_errors() で取得することもできます。

例

例1 XMLドキュメントをパースする

<?php
// The file test.xml contains an XML document with a root element
// and at least an element /[root]/title.

if (file_exists('test.xml')) {
$xml = simplexml_load_file('test.xml');

print_r($xml);
} else {
exit('Failed to open test.xml.');
}
?>

このスクリプトは成功時に以下のように出力します。

SimpleXMLElement Object
(
  [title] => Example Title
  ...
)

この時点で、$xml->title としたり、 他の全ての要素にアクセスすることができます。

参考

  • simplexml_load_string() - XML 文字列をオブジェクトに代入する
  • SimpleXMLElement::__construct() - 新しい SimpleXMLElement オブジェクトを作成する
  • XML エラーの対応
  • libxml_use_internal_errors() - libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする
  • 基本的な SimpleXML の使用法
  • libxml_set_streams_context() - 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する


XML 文字列をオブジェクトに代入する

  • ≪ simplexml_load_file
  • WDDX ≫
  • PHP Manual
  • SimpleXML 関数
  • XML 文字列をオブジェクトに代入する

simplexml_load_string

(PHP 5, PHP 7, PHP 8)

simplexml_load_string — XML 文字列をオブジェクトに代入する

説明

simplexml_load_string(
string $data,
?string $class_name = SimpleXMLElement::class,
int $options = 0,
string $namespace_or_prefix = "",
bool $is_prefix = false
): SimpleXMLElement|false

整形式 XML 文字列をオブジェクトとして返します。

パラメータ

data

整形式 XML 文字列。

class_name

このオプションのパラメータを使用して、 simplexml_load_file() が指定されたクラスのオブジェクトを返すようにします。 このクラスは、SimpleXMLElement クラスを継承していなければなりません。

options

追加の Libxml パラメータ を、ビット演算子の OR で指定します。

namespace_or_prefix

名前空間プレフィックスあるいは URI。

is_prefix

namespace_or_prefix がプレフィックスである場合に true、 URI である場合に false。デフォルトは false です。

戻り値

SimpleXMLElement クラスのオブジェクトを返します。 XML ドキュメント内のデータをプロパティに含みます。 失敗した場合に false を返します。

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

エラー / 例外

XML データ内でエラーが見つかるたびに E_WARNING エラーメッセージが発生します。

ヒント

libxml_use_internal_errors() ですべての XML エラーを抑制し、 後から libxml_get_errors() で取得することもできます。

例

例1 XML 文字列をパースする

<?php
$string = <<<XML
<?xml version='1.0'?>
<document>
<title>Forty What?</title>
<from>Joe</from>
<to>Jane</to>
<body>
I know that's the answer -- but what's the question?
</body>
</document>
XML;

$xml = simplexml_load_string($string);

print_r($xml);
?>

上の例の出力は以下となります。

SimpleXMLElement Object
(
  [title] => Forty What?
  [from] => Joe
  [to] => Jane
  [body] =>
   I know that's the answer -- but what's the question?
)

この時点で、$xml->body のようにアクセスすることができます。

参考

  • simplexml_load_file() - XMLファイルをパースし、オブジェクトに代入する
  • SimpleXMLElement::__construct() - 新しい SimpleXMLElement オブジェクトを作成する
  • XML エラーの対応
  • libxml_use_internal_errors() - libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする
  • 基本的な SimpleXML の使用法


WDDX

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 例
    • wddx の例
  • WDDX 関数
    • wddx_add_vars — 指定した ID の WDDX パケットに変数を追加する
    • wddx_deserialize — WDDX パケットをアンシリアライズする
    • wddx_packet_end — 指定した ID の WDDX パケットを終了する
    • wddx_packet_start — 新規の WDDX パケットを内部の構造体を用いて開始する
    • wddx_serialize_value — 単一の値を WDDX パケットにシリアライズする
    • wddx_serialize_vars — 変数を WDDX パケットにシリアライズする


はじめに

警告

この拡張モジュールは 推奨されていません し PHP 7.4.0 以降では バンドルされていません。

以下の関数は、» WDDX と組み合わせて動作することを想定しています。

警告

信頼できないユーザーの入力を wddx_deserialize() 関数に渡してはいけません。 アンシリアライズ処理が、オブジェクトのインスタンス化とオートローディングのために、 コードをロードして実行してしまいかねませんし、悪意のあるユーザーがこれを悪用できてしまいます。 シリアライズされた値をユーザーに渡す必要があるなら、 (json_decode() や json_encode() 経由で) JSON のような安全で、標準になっているデータ交換フォーマットを使ってください。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • WDDX
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

この拡張モジュールを使うには libxml 拡張モジュールが必要です。つまり、 PHP 7.4 以降では --with-libxml、それより前のバージョンでは --enable-libxml も指定しなければならないということです。 しかし、libxml はデフォルトで有効になっているのでこのオプションは暗黙のうちに指定されています。

WDDX を使用するには、(Apache 1.3.7 以降に付属する) expat ライブラリをインストールする必要があります。


インストール手順

PHP 7.4 以降

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/wddx.

PHP < 7.4

必須ライブラリ expat をインストールした後、PHP のコンパイル時に --enable-wddx を指定します。また --with-libexpat-dir で expat を指定します。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


リソース型

この拡張モジュールでは、WDDX パケット ID を定義しています。これは wddx_packet_start() が返すものです。


  • ≪ リソース型
  • wddx の例 ≫
  • PHP Manual
  • WDDX
  • 例

例

目次

  • wddx の例


wddx の例

変数をシリアル化する全ての関数は配列の最初要素をその配列が配列と 構造体のどちらでシリアル化されるのかを定義するために使用するということに 注意してください。最初の要素が文字列をキーとして有する場合は 構造体でシリアル化され、その他の場合は配列でシリアル化されます。

例1 WDDX を使用した単一の値のシリアル化

<?php
echo wddx_serialize_value("PHP to WDDX packet example", "PHP packet");
?>

この例は次の出力を行います。

<wddxPacket version='1.0'><header comment='PHP packet'/><data>
<string>PHP to WDDX packet example</string></data></wddxPacket>

例2 WDDX を使用してパケットを追加する例

<?php
$pi = 3.1415926;
$packet_id = wddx_packet_start("PHP");
wddx_add_vars($packet_id, "pi");

/* $cities はデータベースから取得するものと仮定します */
$cities = array("Austin", "Novato", "Seattle");
wddx_add_vars($packet_id, "cities");

$packet = wddx_packet_end($packet_id);
echo $packet;
?>

この例は次のような出力を行います。

<wddxPacket version='1.0'><header comment='PHP'/><data><struct>
<var name='pi'><number>3.1415926</number></var><var name='cities'>
<array length='3'><string>Austin</string><string>Novato</string>
<string>Seattle</string></array></var></struct></data></wddxPacket>

注意:

文字列は UTF-8 でエンコードされているべきです。 つまり、他のエンコーディングを扱うには、 文字列をはじめに mb_convert_encoding() や UConverter::transcode(), iconv() を使って変換するようにして下さい。


WDDX 関数

目次

  • wddx_add_vars — 指定した ID の WDDX パケットに変数を追加する
  • wddx_deserialize — WDDX パケットをアンシリアライズする
  • wddx_packet_end — 指定した ID の WDDX パケットを終了する
  • wddx_packet_start — 新規の WDDX パケットを内部の構造体を用いて開始する
  • wddx_serialize_value — 単一の値を WDDX パケットにシリアライズする
  • wddx_serialize_vars — 変数を WDDX パケットにシリアライズする


指定した ID の WDDX パケットに変数を追加する

  • ≪ WDDX 関数
  • wddx_deserialize ≫
  • PHP Manual
  • WDDX 関数
  • 指定した ID の WDDX パケットに変数を追加する

wddx_add_vars

(PHP 4, PHP 5, PHP 7)

wddx_add_vars — 指定した ID の WDDX パケットに変数を追加する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

wddx_add_vars(resource $packet_id, mixed $var_name, mixed ...$var_names): bool

渡された変数をシリアライズし、 指定したパケットに結果を追加します。

パラメータ

この関数は、可変長のパラメータを受け取ります。

packet_id

wddx_packet_start() が返す WDDX パケット。

var_name

変数名を表す文字列、あるいは配列。 配列の中身は、変数名を表す文字列あるいは別の配列などとなります。

var_names

戻り値

成功した場合に true を、失敗した場合に false を返します。


WDDX パケットをアンシリアライズする

  • ≪ wddx_add_vars
  • wddx_packet_end ≫
  • PHP Manual
  • WDDX 関数
  • WDDX パケットをアンシリアライズする

wddx_deserialize

(PHP 4, PHP 5, PHP 7)

wddx_deserialize — WDDX パケットをアンシリアライズする

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

wddx_deserialize(string $packet): mixed

WDDX packet をアンシリアライズします。

警告

信頼できないユーザーの入力を wddx_deserialize() 関数に渡してはいけません。 アンシリアライズ処理が、オブジェクトのインスタンス化とオートローディングのために、 コードをロードして実行してしまいかねませんし、悪意のあるユーザーがこれを悪用できてしまいます。 シリアライズされた値をユーザーに渡す必要があるなら、 (json_decode() や json_encode() 経由で) JSON のような安全で、標準になっているデータ交換フォーマットを使ってください。

パラメータ

packet

WDDX パケット。文字列あるいはストリームで指定します。

戻り値

アンシリアライズした値を返します。値は文字列か数値、あるいは配列のいずれかとなります。 構造体は連想配列に変換されることに注意しましょう。


指定した ID の WDDX パケットを終了する

  • ≪ wddx_deserialize
  • wddx_packet_start ≫
  • PHP Manual
  • WDDX 関数
  • 指定した ID の WDDX パケットを終了する

wddx_packet_end

(PHP 4, PHP 5, PHP 7)

wddx_packet_end — 指定した ID の WDDX パケットを終了する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

wddx_packet_end(resource $packet_id): string

指定した WDDX パケットを終了し、 パケットを含む文字列を返します。

パラメータ

packet_id

wddx_packet_start() が返す WDDX パケット。

戻り値

WDDX パケットを含む文字列を返します。


新規の WDDX パケットを内部の構造体を用いて開始する

  • ≪ wddx_packet_end
  • wddx_serialize_value ≫
  • PHP Manual
  • WDDX 関数
  • 新規の WDDX パケットを内部の構造体を用いて開始する

wddx_packet_start

(PHP 4, PHP 5, PHP 7)

wddx_packet_start — 新規の WDDX パケットを内部の構造体を用いて開始する

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

wddx_packet_start(string $comment = ?): resource

変数を順に追加していくための新しい WDDX パケットを開始します。 この関数は、パケットの内部に自動的に構造体の定義を作成し、 そこに変数を保持します。

パラメータ

comment

オプションのコメント文字列。

戻り値

後で他の関数で使用するためのパケット ID、あるいはエラー時に false を返します。


単一の値を WDDX パケットにシリアライズする

  • ≪ wddx_packet_start
  • wddx_serialize_vars ≫
  • PHP Manual
  • WDDX 関数
  • 単一の値を WDDX パケットにシリアライズする

wddx_serialize_value

(PHP 4, PHP 5, PHP 7)

wddx_serialize_value — 単一の値を WDDX パケットにシリアライズする

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

wddx_serialize_value(mixed $var, string $comment = ?): string

指定した単一の値をもとにして WDDX パケットを作成します。

パラメータ

var

シリアライズする値。

comment

オプションのコメント文字列。これはヘッダ内で用いられます。

戻り値

WDDX パケット、あるいはエラー時に false を返します。


変数を WDDX パケットにシリアライズする

  • ≪ wddx_serialize_value
  • XMLDiff ≫
  • PHP Manual
  • WDDX 関数
  • 変数を WDDX パケットにシリアライズする

wddx_serialize_vars

(PHP 4, PHP 5, PHP 7)

wddx_serialize_vars — 変数を WDDX パケットにシリアライズする

警告

この機能は PHP 7.4.0 で 削除 されました。

説明

wddx_serialize_vars(mixed $var_name, mixed ...$var_names): string

指定された変数をシリアライズしたものを含む構造体を用いて WDDX パケットを作成します。

パラメータ

この関数は、可変長のパラメータを受け取ります。

var_name

変数名を表す文字列、あるいは配列。 配列の中身は、変数名を表す文字列あるいは別の配列などとなります。

var_names

戻り値

WDDX パケット、あるいはエラー時に false を返します。

例

例1 wddx_serialize_vars() の例

<?php
$a = 1;
$b = 5.5;
$c = array("blue", "orange", "violet");
$d = "colors";

$clvars = array("c", "d");
echo wddx_serialize_vars("a", "b", $clvars);
?>

上の例の出力は以下となります。

<wddxPacket version='1.0'><header/><data><struct><var name='a'><number>1</number></var>
<var name='b'><number>5.5</number></var><var name='c'><array length='3'>
<string>blue</string><string>orange</string><string>violet</string></array></var>
<var name='d'><string>colors</string></var></struct></data></wddxPacket>


XML diff and merge

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • XMLDiff\Base — The XMLDiff\Base class
    • XMLDiff\Base::__construct — Constructor
    • XMLDiff\Base::diff — Produce diff of two XML documents
    • XMLDiff\Base::merge — Produce new XML document based on diff
  • XMLDiff\DOM — The XMLDiff\DOM class
    • XMLDiff\DOM::diff — Diff two DOMDocument objects
    • XMLDiff\DOM::merge — Produce merged DOMDocument
  • XMLDiff\Memory — The XMLDiff\Memory class
    • XMLDiff\Memory::diff — Diff two XML documents
    • XMLDiff\Memory::merge — Produce merged XML document
  • XMLDiff\File — The XMLDiff\File class
    • XMLDiff\File::diff — Diff two XML files
    • XMLDiff\File::merge — Produce merged XML document


はじめに

The extension is able to produce diffs of two XML documents and then to apply the difference to the source document. The diff is a XML document containing copy/insert/delete instruction nodes in human readable format. DOMDocument objects, local files and strings in memory can be processed.


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XMLDiff
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

libdiffmark - version 0.10 is bundled with the extension. If diffmark is available from your system packages, its usage is strongly encouraged.

libxml extension

DOM extension


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xmldiff.

A DLL for this PECL extension is available under » http://windows.php.net/downloads/pecl/releases/xmldiff/.


The XMLDiff\Base class

(PECL xmldiff >= 0.8.0)

はじめに

Base abstract class for all the comparsion classes in the extension.

クラス概要

class XMLDiff\Base {
/* メソッド */
public __construct(string $nsname)
abstract public diff(mixed $from, mixed $to): mixed
abstract public merge(mixed $src, mixed $diff): mixed
}

目次

  • XMLDiff\Base::__construct — Constructor
  • XMLDiff\Base::diff — Produce diff of two XML documents
  • XMLDiff\Base::merge — Produce new XML document based on diff


Constructor

  • ≪ XMLDiff\Base
  • XMLDiff\Base::diff ≫
  • PHP Manual
  • XMLDiff\Base
  • Constructor

XMLDiff\Base::__construct

(PECL xmldiff >= 0.8.0)

XMLDiff\Base::__construct — Constructor

説明

public XMLDiff\Base::__construct(string $nsname)

Base constructor for all the worker classes in the xmldiff extension.

パラメータ

nsname

Custom namespace name for the diff document. The default namespace is http://www.locus.cz/diffmark and that's enough to avoid namespace conflicts. Use this parameter if you want to change it for some reason.


Produce diff of two XML documents

  • ≪ XMLDiff\Base::__construct
  • XMLDiff\Base::merge ≫
  • PHP Manual
  • XMLDiff\Base
  • Produce diff of two XML documents

XMLDiff\Base::diff

(PECL xmldiff >= 0.8.0)

XMLDiff\Base::diff — Produce diff of two XML documents

説明

abstract public XMLDiff\Base::diff(mixed $from, mixed $to): mixed

Abstract diff method to be implemented by inheriting classes.

The basic purpose of this method is to produce diff of the two documents. The param order matters and will produce different output.

パラメータ

from

Source XML document.

to

Target XML document.

戻り値

Implementation dependent.


Produce new XML document based on diff

  • ≪ XMLDiff\Base::diff
  • XMLDiff\DOM ≫
  • PHP Manual
  • XMLDiff\Base
  • Produce new XML document based on diff

XMLDiff\Base::merge

(PECL xmldiff >= 0.8.0)

XMLDiff\Base::merge — Produce new XML document based on diff

説明

abstract public XMLDiff\Base::merge(mixed $src, mixed $diff): mixed

Abstract merge method to be implemented by inheriting classes.

Basically the method purpose is to produce a new XML document based on the diff information.

パラメータ

src

Source XML document.

diff

Document produced by the diff method.

戻り値

Implementation dependent.


The XMLDiff\DOM class

(PECL xmldiff >= 0.8.0)

はじめに

クラス概要

class XMLDiff\DOM extends XMLDiff\Base {
/* メソッド */
public diff(DOMDocument $from, DOMDocument $to): DOMDocument
public merge(DOMDocument $src, DOMDocument $diff): DOMDocument
/* 継承したメソッド */
abstract public XMLDiff\Base::diff(mixed $from, mixed $to): mixed
abstract public XMLDiff\Base::merge(mixed $src, mixed $diff): mixed
}

目次

  • XMLDiff\DOM::diff — Diff two DOMDocument objects
  • XMLDiff\DOM::merge — Produce merged DOMDocument


Diff two DOMDocument objects

  • ≪ XMLDiff\DOM
  • XMLDiff\DOM::merge ≫
  • PHP Manual
  • XMLDiff\DOM
  • Diff two DOMDocument objects

XMLDiff\DOM::diff

(PECL xmldiff >= 0.8.0)

XMLDiff\DOM::diff — Diff two DOMDocument objects

説明

public XMLDiff\DOM::diff(DOMDocument $from, DOMDocument $to): DOMDocument

Diff two DOMDocument instances and produce the new one containing the diff information.

パラメータ

from

Source DOMDocument object.

to

Target DOMDocument object.

戻り値

DOMDocument with the diff information or NULL.


Produce merged DOMDocument

  • ≪ XMLDiff\DOM::diff
  • XMLDiff\Memory ≫
  • PHP Manual
  • XMLDiff\DOM
  • Produce merged DOMDocument

XMLDiff\DOM::merge

(PECL xmldiff >= 0.8.0)

XMLDiff\DOM::merge — Produce merged DOMDocument

説明

public XMLDiff\DOM::merge(DOMDocument $src, DOMDocument $diff): DOMDocument

Create new DOMDocument based on the diff.

パラメータ

src

Source DOMDocument object.

diff

DOMDocument object containing the diff information.

戻り値

Merged DOMDocument or NULL.


The XMLDiff\Memory class

(PECL xmldiff >= 0.8.0)

はじめに

クラス概要

class XMLDiff\Memory extends XMLDiff\Base {
/* メソッド */
public diff(string $from, string $to): string
public merge(string $src, string $diff): string
/* 継承したメソッド */
abstract public XMLDiff\Base::diff(mixed $from, mixed $to): mixed
abstract public XMLDiff\Base::merge(mixed $src, mixed $diff): mixed
}

目次

  • XMLDiff\Memory::diff — Diff two XML documents
  • XMLDiff\Memory::merge — Produce merged XML document


Diff two XML documents

  • ≪ XMLDiff\Memory
  • XMLDiff\Memory::merge ≫
  • PHP Manual
  • XMLDiff\Memory
  • Diff two XML documents

XMLDiff\Memory::diff

(PECL xmldiff >= 0.8.0)

XMLDiff\Memory::diff — Diff two XML documents

説明

public XMLDiff\Memory::diff(string $from, string $to): string

Diff two strings containing XML documents and produce the diff information.

パラメータ

from

Source XML document.

to

Target XML document.

戻り値

String with the XML document containing the diff information or NULL.


Produce merged XML document

  • ≪ XMLDiff\Memory::diff
  • XMLDiff\File ≫
  • PHP Manual
  • XMLDiff\Memory
  • Produce merged XML document

XMLDiff\Memory::merge

(PECL xmldiff >= 0.8.0)

XMLDiff\Memory::merge — Produce merged XML document

説明

public XMLDiff\Memory::merge(string $src, string $diff): string

Create new XML document based on diffs and source document.

パラメータ

src

Source XML document.

diff

XML document containing diff information.

戻り値

String with the new XML document or NULL.


The XMLDiff\File class

(PECL xmldiff >= 0.8.0)

はじめに

クラス概要

class XMLDiff\File extends XMLDiff\Base {
/* メソッド */
public diff(string $from, string $to): string
public merge(string $src, string $diff): string
/* 継承したメソッド */
abstract public XMLDiff\Base::diff(mixed $from, mixed $to): mixed
abstract public XMLDiff\Base::merge(mixed $src, mixed $diff): mixed
}

目次

  • XMLDiff\File::diff — Diff two XML files
  • XMLDiff\File::merge — Produce merged XML document


Diff two XML files

  • ≪ XMLDiff\File
  • XMLDiff\File::merge ≫
  • PHP Manual
  • XMLDiff\File
  • Diff two XML files

XMLDiff\File::diff

(PECL xmldiff >= 0.8.0)

XMLDiff\File::diff — Diff two XML files

説明

public XMLDiff\File::diff(string $from, string $to): string

Diff two local XML files and produce string with the diff information.

パラメータ

from

Path to the source document.

to

Path to the target document.

戻り値

String with the XML document containing the diff information or NULL.


Produce merged XML document

  • ≪ XMLDiff\File::diff
  • XML パーサ ≫
  • PHP Manual
  • XMLDiff\File
  • Produce merged XML document

XMLDiff\File::merge

(PECL xmldiff >= 0.8.0)

XMLDiff\File::merge — Produce merged XML document

説明

public XMLDiff\File::merge(string $src, string $diff): string

Create new XML document based on diffs and source document.

パラメータ

src

Path to the source XML document.

diff

Path to the XML document with the diff information.

戻り値

String with the new XML document or NULL.


XML パーサ

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 定義済み定数
  • イベントハンドラ
  • 大文字変換(Case Folding)
  • エラーコード
  • 文字エンコーディング
  • 例
    • XML エレメント構造の例
    • XMLタグのマッピングの例
    • XML 外部エンティティの例
  • XML パーサ 関数
    • xml_error_string — XML パーサのエラー文字列を得る
    • xml_get_current_byte_index — XML パーサのカレントのバイトインデックスを得る
    • xml_get_current_column_number — XML パーサのカレントのカラム番号を取得する
    • xml_get_current_line_number — XML パーサのカレントの行番号を得る
    • xml_get_error_code — XML パーサのエラーコードを得る
    • xml_parse — XML ドキュメントの処理を開始する
    • xml_parse_into_struct — 配列構造体に XML データを処理する
    • xml_parser_create — XML パーサを作成する
    • xml_parser_create_ns — 名前空間をサポートした XML パーサを生成する
    • xml_parser_free — XML パーサを解放する
    • xml_parser_get_option — XML パーサからオプションを得る
    • xml_parser_set_option — XML パーサのオプションを設定する
    • xml_set_character_data_handler — 文字データハンドラを設定する
    • xml_set_default_handler — デフォルトのハンドラを設定する
    • xml_set_element_handler — 開始要素および終了要素のハンドラを設定する
    • xml_set_end_namespace_decl_handler — 名前空間終了ハンドラを設定する
    • xml_set_external_entity_ref_handler — 外部エンティティリファレンスハンドラを設定する
    • xml_set_notation_decl_handler — 表記法宣言ハンドラを設定する
    • xml_set_object — オブジェクト内部で XML パーサを使用する
    • xml_set_processing_instruction_handler — 処理命令 (PI) 用ハンドラを設定する
    • xml_set_start_namespace_decl_handler — 名前空間開始ハンドラを設定する
    • xml_set_unparsed_entity_decl_handler — 処理されないエンティティ宣言用ハンドラを設定する
  • XMLParser — XMLParser クラス


はじめに

XML (eXtensible Markup Language) は、Web における構造化された ドキュメント交換用のデータフォーマットです。XML は、World Wide Web consortium (W3C) で規定された規格です。XML に関する情報およ び関連する技術は、» http://www.w3.org/XML/ で参照することができます。

このPHP拡張モジュールは、James Clark氏の expatのサポートをPHPに付加します。 このツールキットは、XML ドキュメントの構文解析をしますが、 検証は行いません。3種類のソース 文字エンコーディング、 US-ASCII, ISO-8859-1 ,UTF-8 がPHPでサポートされます。UTF-16 はサポートさ れません。

この拡張モジュールは、XML パーサの作成 を行い、さまざまな XML イベントに関してハンドラ を定義します。各XMLパーサーには、設定可能な小数の パラメータ もあります。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XML パーサ
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


要件

この拡張モジュールを使うには libxml 拡張モジュールが必要です。つまり、 PHP 7.4 以降では --with-libxml、それより前のバージョンでは --enable-libxml も指定しなければならないということです。 しかし、libxml はデフォルトで有効になっているのでこのオプションは暗黙のうちに指定されています。

この拡張モジュールは、expat を使用します。 これは、» https://libexpat.github.io/にあります。 expat に付属のMakefileは、デフォルトでライブラリを構築しません。 これを行うmakeルールを次のように指定できます。

libexpat.a: $(OBJS)
    ar -rc $@ $(OBJS)
    ranlib $@
expat のソース RPM パッケージが » https://sourceforge.net/projects/expat/ にあります。


インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-xml

付属しているexpatライブラリを用いて以下の関数はデフォルトで有効となっ ています。 --disable-xmlを指定してXMLサポート を無効にすることができます。Apache 1.3.9以降でモジュールとしてPHPを コンパイルする場合、PHPは、Apacheから自動的に付属する expatライブラリを使用します。 付属するexpatライブラリを使用したくない場合には、 --with-expat-dir=DIRを指定してPHP のconfigureを実行してください。ただし、DIRは、expatをインストールした ベースディレクトリです。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。


リソース型

PHP 8.0.0 より前のバージョンでは、xml_parser_create()および xml_parser_create_ns() により返された xmlリソースは、 この拡張モジュールにより提供された関数で使用される XMLパーサのインスタンスを参照します。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XML_ERROR_NONE (int)
XML_ERROR_NO_MEMORY (int)
XML_ERROR_SYNTAX (int)
XML_ERROR_NO_ELEMENTS (int)
XML_ERROR_INVALID_TOKEN (int)
XML_ERROR_UNCLOSED_TOKEN (int)
XML_ERROR_PARTIAL_CHAR (int)
XML_ERROR_TAG_MISMATCH (int)
XML_ERROR_DUPLICATE_ATTRIBUTE (int)
XML_ERROR_JUNK_AFTER_DOC_ELEMENT (int)
XML_ERROR_PARAM_ENTITY_REF (int)
XML_ERROR_UNDEFINED_ENTITY (int)
XML_ERROR_RECURSIVE_ENTITY_REF (int)
XML_ERROR_ASYNC_ENTITY (int)
XML_ERROR_BAD_CHAR_REF (int)
XML_ERROR_BINARY_ENTITY_REF (int)
XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (int)
XML_ERROR_MISPLACED_XML_PI (int)
XML_ERROR_UNKNOWN_ENCODING (int)
XML_ERROR_INCORRECT_ENCODING (int)
XML_ERROR_UNCLOSED_CDATA_SECTION (int)
XML_ERROR_EXTERNAL_ENTITY_HANDLING (int)
XML_OPTION_CASE_FOLDING (int)
XML_OPTION_TARGET_ENCODING (int)
XML_OPTION_SKIP_TAGSTART (int)
XML_OPTION_SKIP_WHITE (int)
XML_SAX_IMPL (string)
SAX の実装方式を保持します。 libxml あるいは expat となります。


イベントハンドラ

XML イベントハンドラは次のように定義されます。

サポートされる XML ハンドラ
ハンドラ設定用の PHP 関数 | イベントの説明
xml_set_element_handler() | 要素イベントは、XML パーサーが開始または終了タグに出会うたび に発行されます。開始タグと終了タグについて別のハンドラがあり ます。
xml_set_character_data_handler() | 文字データは、タグの間の空白を含めて XML ドキュメントにおけ るほぼ全ての非マークアップ部分の内容です。XML パーサーは、 空白を加えたり削除したりしないことに注意してください。空白が 意味を有するかどうかを決めるのは、アプリケーション側の責任 です。
xml_set_processing_instruction_handler() | PHP プログラマは、既に処理用命令 (PI) に既に慣れているに違 いありません。<?php ?> は処理用命令であり、この場合、 php は "PI ターゲット"と呼ばれます。 これらの処理はアプリケーション依存ですが、全ての PI ターゲッ トが "XML" から始まることだけは、規定されています。
xml_set_default_handler() | 別のハンドラでしないことをデフォルトのハンドラで行います。 XML およびドキュメント型の宣言のようなことをデフォルトハンドラで 行います。
xml_set_unparsed_entity_decl_handler() | このハンドラは、処理されない (NDATA) エンティティの宣言用に コールされます。
xml_set_notation_decl_handler() | このハンドラは、表記の宣言用にコールされます。
xml_set_external_entity_ref_handler() | このハンドラは、XML パーサーが外部処理された通常のエンティティ への参照を見つけた際にコールされます。これは、例えば、ファ イルまたは URL への参照とすることが可能です。例としては、 外部エンティティ の例 を参照ください。
xml_set_start_namespace_decl_handler() | このハンドラは、名前空間宣言の開始時にコールされます。
xml_set_end_namespace_decl_handler() | このハンドラは、名前空間宣言の終了時にコールされます。このイベントは libXML によりトリガーされない ことに注意しましょう。


大文字変換(Case Folding)

要素ハンドラ関数は、その要素に大文字小文字を変換する (case-folded)の名前をつけることができます。 大文字変換(case-folding) は、 "大文字でないものは等価な大文字に置換される一連の文字に適用されるプロセス" として定義されています。言い替えると、 XML に関しては単に大文字変換は大文字にすることを意味します。

デフォルトで、ハンドラ関数に渡される全ての要素名は、大文字変換さ れます。この動作は、xml_parser_get_option() およびxml_parser_set_option() 関数でXMLパーサー 毎にそれぞれ問い合わせ、制御することが可能です。


エラーコード

(xml_parse() により返されるものとして) XMLエラーコードとして次のような定数が定義されています。:

  • XML_ERROR_NONE
  • XML_ERROR_NO_MEMORY
  • XML_ERROR_SYNTAX
  • XML_ERROR_NO_ELEMENTS
  • XML_ERROR_INVALID_TOKEN
  • XML_ERROR_UNCLOSED_TOKEN
  • XML_ERROR_PARTIAL_CHAR
  • XML_ERROR_TAG_MISMATCH
  • XML_ERROR_DUPLICATE_ATTRIBUTE
  • XML_ERROR_JUNK_AFTER_DOC_ELEMENT
  • XML_ERROR_PARAM_ENTITY_REF
  • XML_ERROR_UNDEFINED_ENTITY
  • XML_ERROR_RECURSIVE_ENTITY_REF
  • XML_ERROR_ASYNC_ENTITY
  • XML_ERROR_BAD_CHAR_REF
  • XML_ERROR_BINARY_ENTITY_REF
  • XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
  • XML_ERROR_MISPLACED_XML_PI
  • XML_ERROR_UNKNOWN_ENCODING
  • XML_ERROR_INCORRECT_ENCODING
  • XML_ERROR_UNCLOSED_CDATA_SECTION
  • XML_ERROR_EXTERNAL_ENTITY_HANDLING


文字エンコーディング

PHPのXML拡張モジュールは、異なった文字エンコーディング を通じて» Unicode 文字セットをサポートします。ソースエンコーディング およびターゲットエンコーディング という2種類の文字エンコーディングがあります。 PHP におけるドキュメントの内部表現は、常に UTF-8でエンコードされます。

ソースエンコーディングは、XMLドキュメントが 構文解析された際に行わ れます。XML パーサの 作成を行う際に、ソースエンコードを指定することができます。 (このエンコーディングは、その XML パーサーが存在する間、後で変更す ることはできません)サポートされるソースエンコーディングは、 ISO-8859-1, US-ASCII , UTF-8 です。前の二つは、シングルバイトエンコー ディングです。これは、各文字がシングルバイトで表現されることを意 味します。UTF-8 は、1から4バイトの可変ビット 数(最大21ビット)で構成された文字をエンコードすることが可能です。 PHP で用いられるデフォルトのソースエンコーディングは、 ISO-8859-1です。

ターゲットエンコーディングは、PHPがデータをXMLハンドラ関数に 渡す時に行われます。あるXMLパーサが作成された際、ターゲットエン コーディングは、ソースエンコーディングと同様に設定されます。 しかし、これは、いつでも変更可能です。ターゲットエンコーディング は、タグ名と同様に文字データに作用し、命令を処理します。

XML パーサがソースエンコーディングが表現できる範囲の外側の文字に 出会った場合、エラーが返されます。

解釈するXMLドキュメントにおいてPHPが文字に出会った際に、選択した ターゲットエンコーディングで表現できない文字に出会った場合、問題 の文字は "降格" されます。現在、このことはこのような文字が疑問符 で置換されることを意味します。


  • ≪ 文字エンコーディング
  • XML エレメント構造の例 ≫
  • PHP Manual
  • XML パーサ
  • 例

例

目次

  • XML エレメント構造の例
  • XMLタグのマッピングの例
  • XML 外部エンティティの例


XML エレメント構造の例

この最初の例は、あるドキュメント中のstart エレメントの構造をイン デントを付けて表示します。

例1 XML エレメント構造を表示

<?php
$file = "data.xml";
$depth = 0;

function startElement($parser, $name, $attrs)
{
global $depth;

for ($i = 0; $i < $depth; $i++) {
echo " ";
}
echo "$name\n";
$depth++;
}

function endElement($parser, $name)
{
global $depth;
$depth--;
}

$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, "startElement", "endElement");
if (!($fp = fopen($file, "r"))) {
die("XML 入力をオープンできませんでした");
}

while ($data = fread($fp, 4096)) {
if (!xml_parse($xml_parser, $data, feof($fp))) {
die(sprintf("XML エラー: %s が %d 行目で発生しました",
xml_error_string(xml_get_error_code($xml_parser)),
xml_get_current_line_number($xml_parser)));
}
}
xml_parser_free($xml_parser);
?>


XMLタグのマッピングの例

例1 XMLをHTMLにマップする

この例は、XMLドキュメントのタグを直接HTMLタグにマップします。 "map array" にないエレメントは無視されます。もちろん、この例は、 特定の XML ドキュメント型を有する場合のみ動作します。

<?php
$file = "data.xml";
$map_array = array(
"BOLD" => "B",
"EMPHASIS" => "I",
"LITERAL" => "TT"
);

function startElement($parser, $name, $attrs)
{
global $map_array;
if (isset($map_array[$name])) {
echo "<$map_array[$name]>";
}
}

function endElement($parser, $name)
{
global $map_array;
if (isset($map_array[$name])) {
echo "</$map_array[$name]>";
}
}

function characterData($parser, $data)
{
echo $data;
}

$xml_parser = xml_parser_create();
// case-folding を用いることで、$map_array から確実にタグを見つけられるようにします
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true);
xml_set_element_handler($xml_parser, "startElement", "endElement");
xml_set_character_data_handler($xml_parser, "characterData");
if (!($fp = fopen($file, "r"))) {
die("XML 入力をオープンできませんでした");
}

while ($data = fread($fp, 4096)) {
if (!xml_parse($xml_parser, $data, feof($fp))) {
die(sprintf("XML エラー: %s が %d 行目で発生しました",
xml_error_string(xml_get_error_code($xml_parser)),
xml_get_current_line_number($xml_parser)));
}
}
xml_parser_free($xml_parser);
?>


XML 外部エンティティの例

この例は、XML コードに焦点を当てます。この例は、他のドキュメント をインクルードし処理するための外部エンティティリファレンスのハン ドラの使用法およびPIの処理方法、PIが含むコードに関する"信頼度" を定義する手段を説明します。

この例で使用される XML ドキュメントは、例題ファイル (xmltest.xml および xmltest2.xml) にあります。

例1 外部エンティティの例

<?php
$file = "xmltest.xml";

function trustedFile($file)
{
// 信頼できるのは、自分自身が所有しているローカルファイルのみです
if (!preg_match("@^([a-z][a-z0-9+.-]*)\:\/\/@i", $file)
&& fileowner($file) == getmyuid()) {
return true;
}
return false;
}

function startElement($parser, $name, $attribs)
{
echo "&lt;<font color=\"#0000cc\">$name</font>";
if (count($attribs)) {
foreach ($attribs as $k => $v) {
echo " <font color=\"#009900\">$k</font>=\"<font
color=\"#990000\">$v</font>\"";
}
}
echo "&gt;";
}

function endElement($parser, $name)
{
echo "&lt;/<font color=\"#0000cc\">$name</font>&gt;";
}

function characterData($parser, $data)
{
echo "<b>$data</b>";
}

function PIHandler($parser, $target, $data)
{
switch (strtolower($target)) {
case "php":
global $parser_file;
// もし「信頼できる」ドキュメントだった場合、その中に書かれている
// PHP コードを実行しても安全だと考えます。そうでない場合、
// コードを実行するかわりにコードそのものを表示します。
if (trustedFile($parser_file[$parser])) {
eval($data);
} else {
printf("信頼できない PHP コード: <i>%s</i>",
htmlspecialchars($data));
}
break;
}
}

function defaultHandler($parser, $data)
{
if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") {
printf('<font color="#aa00aa">%s</font>',
htmlspecialchars($data));
} else {
printf('<font size="-1">%s</font>',
htmlspecialchars($data));
}
}

function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId,
$publicId) {
if ($systemId) {
if (!list($parser, $fp) = new_xml_parser($systemId)) {
printf("エンティティ %s (%s にある) をオープンできませんでした\n", $openEntityNames,
$systemId);
return false;
}
while ($data = fread($fp, 4096)) {
if (!xml_parse($parser, $data, feof($fp))) {
printf("XML エラー: %s が、%d 行目でエンティティ %s のパース中に発生しました\n",
xml_error_string(xml_get_error_code($parser)),
xml_get_current_line_number($parser), $openEntityNames);
xml_parser_free($parser);
return false;
}
}
xml_parser_free($parser);
return true;
}
return false;
}

function new_xml_parser($file)
{
global $parser_file;

$xml_parser = xml_parser_create();
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1);
xml_set_element_handler($xml_parser, "startElement", "endElement");
xml_set_character_data_handler($xml_parser, "characterData");
xml_set_processing_instruction_handler($xml_parser, "PIHandler");
xml_set_default_handler($xml_parser, "defaultHandler");
xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler");

if (!($fp = @fopen($file, "r"))) {
return false;
}
if (!is_array($parser_file)) {
settype($parser_file, "array");
}
$parser_file[$xml_parser] = $file;
return array($xml_parser, $fp);
}

if (!(list($xml_parser, $fp) = new_xml_parser($file))) {
die("XML 入力をオープンできませんでした");
}

echo "<pre>";
while ($data = fread($fp, 4096)) {
if (!xml_parse($xml_parser, $data, feof($fp))) {
die(sprintf("XML エラー: %s が %d 行目で発生しました\n",
xml_error_string(xml_get_error_code($xml_parser)),
xml_get_current_line_number($xml_parser)));
}
}
echo "</pre>";
echo "パースが完了しました\n";
xml_parser_free($xml_parser);

?>

例2 xmltest.xml

<?xml version='1.0'?>
<!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [
<!ENTITY plainEntity "FOO entity">
<!ENTITY systemEntity SYSTEM "xmltest2.xml">
]>
<chapter>
 <TITLE>Title &plainEntity;</TITLE>
 <para>
  <informaltable>
   <tgroup cols="3">
    <tbody>
     <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row>
     <row><entry>a2</entry><entry>c2</entry></row>
     <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row>
    </tbody>
   </tgroup>
  </informaltable>
 </para>
 &systemEntity;
 <section id="about">
  <title>About this Document</title>
  <para>
   <!-- this is a comment -->
   <?php echo 'Hi!  This is PHP version ' . phpversion(); ?>
  </para>
 </section>
</chapter>

このファイルは、xmltest.xml からインクルードされます。

例3 xmltest2.xml

<?xml version="1.0"?>
<!DOCTYPE foo [
<!ENTITY testEnt "test entity">
]>
<foo>
   <element attrib="value"/>
   &testEnt;
   <?php echo "This is some more PHP code being executed."; ?>
</foo>


XML パーサ 関数

目次

  • xml_error_string — XML パーサのエラー文字列を得る
  • xml_get_current_byte_index — XML パーサのカレントのバイトインデックスを得る
  • xml_get_current_column_number — XML パーサのカレントのカラム番号を取得する
  • xml_get_current_line_number — XML パーサのカレントの行番号を得る
  • xml_get_error_code — XML パーサのエラーコードを得る
  • xml_parse — XML ドキュメントの処理を開始する
  • xml_parse_into_struct — 配列構造体に XML データを処理する
  • xml_parser_create — XML パーサを作成する
  • xml_parser_create_ns — 名前空間をサポートした XML パーサを生成する
  • xml_parser_free — XML パーサを解放する
  • xml_parser_get_option — XML パーサからオプションを得る
  • xml_parser_set_option — XML パーサのオプションを設定する
  • xml_set_character_data_handler — 文字データハンドラを設定する
  • xml_set_default_handler — デフォルトのハンドラを設定する
  • xml_set_element_handler — 開始要素および終了要素のハンドラを設定する
  • xml_set_end_namespace_decl_handler — 名前空間終了ハンドラを設定する
  • xml_set_external_entity_ref_handler — 外部エンティティリファレンスハンドラを設定する
  • xml_set_notation_decl_handler — 表記法宣言ハンドラを設定する
  • xml_set_object — オブジェクト内部で XML パーサを使用する
  • xml_set_processing_instruction_handler — 処理命令 (PI) 用ハンドラを設定する
  • xml_set_start_namespace_decl_handler — 名前空間開始ハンドラを設定する
  • xml_set_unparsed_entity_decl_handler — 処理されないエンティティ宣言用ハンドラを設定する


XML パーサのエラー文字列を得る

  • ≪ XML パーサ 関数
  • xml_get_current_byte_index ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサのエラー文字列を得る

xml_error_string

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_error_string — XML パーサのエラー文字列を得る

説明

xml_error_string(int $error_code): ?string

エラーコード error_code の説明を有する文字列を 返します。

パラメータ

error_code

xml_get_error_code() からのエラーコード。

戻り値

エラーコード error_code の説明を有する文字列を 返します。説明がない場合には null または "Unknown" を返します。

参考

  • xml_get_error_code() - XML パーサのエラーコードを得る


XML パーサのカレントのバイトインデックスを得る

  • ≪ xml_error_string
  • xml_get_current_column_number ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサのカレントのバイトインデックスを得る

xml_get_current_byte_index

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_get_current_byte_index — XML パーサのカレントのバイトインデックスを得る

説明

xml_get_current_byte_index(XMLParser $parser): int

指定した XML パーサのカレントのバイトインデックスを取得します。

パラメータ

parser

バイトインデックスを得る XML パーサへのリファレンス。

戻り値

データバッファにおいて、パーサが現在処理中のバイトインデックス (先頭が 0) を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

注意

警告

この関数は、UTF-8 エンコードされたテキストに基づいたバイトインデックスを返します。 入力が他のエンコーディングであっても無視します。

参考

  • xml_get_current_column_number() - XML パーサのカレントのカラム番号を取得する
  • xml_get_current_line_number() - XML パーサのカレントの行番号を得る


XML パーサのカレントのカラム番号を取得する

  • ≪ xml_get_current_byte_index
  • xml_get_current_line_number ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサのカレントのカラム番号を取得する

xml_get_current_column_number

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_get_current_column_number — XML パーサのカレントのカラム番号を取得する

説明

xml_get_current_column_number(XMLParser $parser): int

指定した XML パーサのカレントのカラム番号を取得します。

パラメータ

parser

カラム番号を得る XML パーサへのリファレンス。

戻り値

現在のパーサの (xml_get_current_line_number() で取得した) 現在の行のカラムを返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

参考

  • xml_get_current_byte_index() - XML パーサのカレントのバイトインデックスを得る
  • xml_get_current_line_number() - XML パーサのカレントの行番号を得る


XML パーサのカレントの行番号を得る

  • ≪ xml_get_current_column_number
  • xml_get_error_code ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサのカレントの行番号を得る

xml_get_current_line_number

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_get_current_line_number — XML パーサのカレントの行番号を得る

説明

xml_get_current_line_number(XMLParser $parser): int

指定した XML パーサのカレントの行番号を取得します。

パラメータ

parser

行番号を得る XML パーサへのリファレンス。

戻り値

データバッファの中で、現在パーサが処理中の行番号を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

参考

  • xml_get_current_column_number() - XML パーサのカレントのカラム番号を取得する
  • xml_get_current_byte_index() - XML パーサのカレントのバイトインデックスを得る


XML パーサのエラーコードを得る

  • ≪ xml_get_current_line_number
  • xml_parse ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサのエラーコードを得る

xml_get_error_code

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_get_error_code — XML パーサのエラーコードを得る

説明

xml_get_error_code(XMLParser $parser): int

XML パーサのエラーコードを取得します。

パラメータ

parser

エラーコードを得る XML パーサへのリファレンス。

戻り値

エラーコードセクション に 一覧が示されたエラーコードを返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

参考

  • xml_error_string() - XML パーサのエラー文字列を得る


XML ドキュメントの処理を開始する

  • ≪ xml_get_error_code
  • xml_parse_into_struct ≫
  • PHP Manual
  • XML パーサ 関数
  • XML ドキュメントの処理を開始する

xml_parse

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_parse — XML ドキュメントの処理を開始する

説明

xml_parse(XMLParser $parser, string $data, bool $is_final = false): int

xml_parse() は XML ドキュメントを処理します。 設定されているイベントのハンドラが、必要に応じてコールされます。

パラメータ

parser

使用する XML パーサへのリファレンス。

data

処理するデータ。ドキュメントは、 is_final パラメータが設定され、 最後のデータが処理され true になるまで、新規のデータに関して 複数回 xml_parse() をコールすることにより、 部分毎で処理することが可能です。

is_final

true が設定された場合、data は この処理の間に送られた最後のデータということになります。

戻り値

成功した場合に 1、失敗した場合に 0 を返します。

処理が成功しなかった場合、エラー情報を
xml_get_error_code(),
xml_error_string(),
xml_get_current_line_number(),
xml_get_current_column_number() および
xml_get_current_byte_index()
により取得可能です。

注意:

エンティティのエラーが報告されるのは、ドキュメントの最後で行われます。 つまり is_final が true に設定されている場合だけです。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

例

例1 巨大なXML文書を切り分けてパースする

この例は、 どのようにして巨大なXML文書を読み取り、チャンクに分けて パースするのかを示しています。 これにより、文書全体をメモリに置く必要がないようにします。 エラーハンドリングは例を簡単にするため省略しています。

<?php
$stream = fopen('large.xml', 'r');
$parser = xml_parser_create();
// ハンドラをセットアップする
while (($data = fread($stream, 16384))) {
xml_parse($parser, $data); // 現在のチャンクをパースする
}
xml_parse($parser, '', true); // パースを終了する
xml_parser_free($parser);
fclose($stream);


配列構造体に XML データを処理する

  • ≪ xml_parse
  • xml_parser_create ≫
  • PHP Manual
  • XML パーサ 関数
  • 配列構造体に XML データを処理する

xml_parse_into_struct

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_parse_into_struct — 配列構造体に XML データを処理する

説明

xml_parse_into_struct(
XMLParser $parser,
string $data,
array &$values,
array &$index = null
): int

この関数は、XML 文字列を処理し、2つの配列構造体に代入します。 ひとつめの配列 (index) は、配列 values にある適当な値の位置を指すポインタを保持しています。 これら最後の二つのパラメータは参照渡しとする必要があります。

パラメータ

parser

XML パーサへの参照。

data

XML データを含む文字列。

values

XML データの値を含む配列。

index

$values 内の適切な値の場所をさすポインタの配列。

戻り値

xml_parse_into_struct() は失敗した場合に 0、 成功した場合に 1 を返します。これは false および true とは 異なるものですので、=== のような演算子を使用する場合は注意しましょう。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

例

以下の例は、この関数により生成された配列の内部構造を示すものです。 noteタグをparaタグの中に埋 め込んで使用した後、これをパースし、生成された構造体を出力します。

例1 xml_parse_into_struct() の例

<?php
$simple = "<para><note>simple note</note></para>";
$p = xml_parser_create();
xml_parse_into_struct($p, $simple, $vals, $index);
xml_parser_free($p);
echo "Index array\n";
print_r($index);
echo "\nVals array\n";
print_r($vals);
?>

このコードを実行した場合、出力は次のようになります。

Index array
Array
(
    [PARA] => Array
        (
            [0] => 0
            [1] => 2
        )

    [NOTE] => Array
        (
            [0] => 1
        )

)

Vals array
Array
(
    [0] => Array
        (
            [tag] => PARA
            [type] => open
            [level] => 1
        )

    [1] => Array
        (
            [tag] => NOTE
            [type] => complete
            [level] => 2
            [value] => simple note
        )

    [2] => Array
        (
            [tag] => PARA
            [type] => close
            [level] => 1
        )

)

(expatライブラリを使用した)イベント駆動型パーサによる処理は、XML ドキュメントが複雑な場合に複雑になる場合があります。この関数は、 DOM形式のオブジェクトを生成しませんが、ツリー風に一連の処理を行い 得る構造体を生成します。つまり、XMLのファイルを表すオブジェクトを 容易に作成することが可能です。次のXMLファイルを見てみましょう。 このファイルでは、アミノ酸の情報に関する小さなデータベースを表します。

例2 moldb.xml - 分子情報の小さなデータベース

<?xml version="1.0"?>
<moldb>

  <molecule>
      <name>Alanine</name>
      <symbol>ala</symbol>
      <code>A</code>
      <type>hydrophobic</type>
  </molecule>

  <molecule>
      <name>Lysine</name>
      <symbol>lys</symbol>
      <code>K</code>
      <type>charged</type>
  </molecule>

</moldb>
ドキュメントを処理し、適当なオブジェクトを生成するいくつかのコード

例3 parsemoldb.php - moldb.xml を処理し、分子オブジェクトの配列に代入

<?php

class AminoAcid {
var $name; // aa name
var $symbol; // three letter symbol
var $code; // one letter code
var $type; // hydrophobic, charged or neutral

function __construct ($aa)
{
foreach ($aa as $k=>$v)
$this->$k = $aa[$k];
}
}

function readDatabase($filename)
{
// read the XML database of aminoacids
$data = file_get_contents($filename);
$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);
xml_parse_into_struct($parser, $data, $values, $tags);
xml_parser_free($parser);

// loop through the structures
foreach ($tags as $key=>$val) {
if ($key == "molecule") {
$molranges = $val;
// each contiguous pair of array entries are the
// lower and upper range for each molecule definition
for ($i=0; $i < count($molranges); $i+=2) {
$offset = $molranges[$i] + 1;
$len = $molranges[$i + 1] - $offset;
$tdb[] = parseMol(array_slice($values, $offset, $len));
}
} else {
continue;
}
}
return $tdb;
}

function parseMol($mvalues)
{
for ($i=0; $i < count($mvalues); $i++) {
$mol[$mvalues[$i]["tag"]] = $mvalues[$i]["value"];
}
return new AminoAcid($mol);
}

$db = readDatabase("moldb.xml");
echo "** Database of AminoAcid objects:\n";
print_r($db);

?>
parsemoldb.phpを実行した後、変数 $db は、オブジェクト AminoAcidの配列を有しており、スクリプトの 出力は、次のようになります。
** Database of AminoAcid objects:
Array
(
    [0] => aminoacid Object
        (
            [name] => Alanine
            [symbol] => ala
            [code] => A
            [type] => hydrophobic
        )

    [1] => aminoacid Object
        (
            [name] => Lysine
            [symbol] => lys
            [code] => K
            [type] => charged
        )

)


XML パーサを作成する

  • ≪ xml_parse_into_struct
  • xml_parser_create_ns ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサを作成する

xml_parser_create

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_parser_create — XML パーサを作成する

説明

xml_parser_create(?string $encoding = null): XMLParser

xml_parser_create() は新しい XML パーサを作成し、 他の XML 関数が使用する XMLParser のインスタンスを返します。

パラメータ

encoding

入力のエンコーディングは 自動判定されるので、encoding パラメータは 出力のエンコーディングのみを指定することになります。 もし空の文字列が渡された場合、先頭の 3 あるいは 4 バイトの内容をもとに パーサがエンコーディングの判別を試みます。 ではデフォルトの出力文字セットは UTF-8 です。 サポートされるエンコーディングは ISO-8859-1、UTF-8 および US-ASCII です。

戻り値

新しい XMLParser のインスタンスを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は XMLParser のインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返され、失敗した場合は false が返っていました。
8.0.0 | encoding は、nullable になりました。

参考

  • xml_parser_create_ns() - 名前空間をサポートした XML パーサを生成する
  • xml_parser_free() - XML パーサを解放する


名前空間をサポートした XML パーサを生成する

  • ≪ xml_parser_create
  • xml_parser_free ≫
  • PHP Manual
  • XML パーサ 関数
  • 名前空間をサポートした XML パーサを生成する

xml_parser_create_ns

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

xml_parser_create_ns — 名前空間をサポートした XML パーサを生成する

説明

xml_parser_create_ns(?string $encoding = null, string $separator = ":"): XMLParser

xml_parser_create_ns() は XML 名前空間をサポートした 新しい XML パーサを作成し、他の XML 関数が使用する XMLParser インスタンスを返します。

パラメータ

encoding

入力のエンコーディングは 自動判定されるので、encoding パラメータは 出力のエンコーディングのみを指定することになります。 デフォルトの出力文字セットは UTF-8 です。 サポートされるエンコーディングは ISO-8859-1、UTF-8 および US-ASCII です。

separator

名前空間を含めたタグパラメータをハンドラ関数に渡す際には、 名前空間名とタグ名を文字列 separator でつなげたものが使用されます。

戻り値

新しい XMLParser のインスタンスを返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は XMLParser のインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返され、失敗した場合は false が返されていました。
8.0.0 | encoding は、 nullable になりました。

参考

  • xml_parser_create() - XML パーサを作成する
  • xml_parser_free() - XML パーサを解放する


XML パーサを解放する

  • ≪ xml_parser_create_ns
  • xml_parser_get_option ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサを解放する

xml_parser_free

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_parser_free — XML パーサを解放する

説明

xml_parser_free(XMLParser $parser): bool

注意:

この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

指定した XML パーサ parser を解放します。

警告

パースが終了した際、 xml_parser_free() 関数を呼び出すのに加えて、 PHP 8.0.0 より前のバージョンでは オブジェクトがパーサのリソースを参照している場合に、 メモリリークを避けるために parser の参照を 明示的に unset することも必要になっています。

パラメータ

parser
解放したい XML パーサへのリファレンス。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


XML パーサからオプションを得る

  • ≪ xml_parser_free
  • xml_parser_set_option ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサからオプションを得る

xml_parser_get_option

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_parser_get_option — XML パーサからオプションを得る

説明

xml_parser_get_option(XMLParser $parser, int $option): string|int|bool

XML パーサからオプションの値を取得します。

パラメータ

parser
オプションを取得する XML パーサへのリファレンス。
option
取得するオプション。XML_OPTION_CASE_FOLDING, XML_OPTION_SKIP_TAGSTART, XML_OPTION_SKIP_WHITE あるいは XML_OPTION_TARGET_ENCODING が使用可能です。 詳細は xml_parser_set_option() を参照ください。

戻り値

オプションの値を返します。

エラー / 例外

無効な値を option に渡すと、ValueError がスローされます。

PHP 8.0.0 より前のバージョンでは、 無効な値を option に渡すと E_WARNING が発生し、false を返していました。

変更履歴

バージョン | 説明
8.3.0 | この関数は、boolean のオプションを返すようになりました。
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。
8.0.0 | option が無効な値の場合、 ValueError がスローされるようになりました。
7.1.24, 7.2.12, 7.3.0 | options が 新たに XML_OPTION_SKIP_TAGSTART と XML_OPTION_SKIP_WHITE をサポートしました。


XML パーサのオプションを設定する

  • ≪ xml_parser_get_option
  • xml_set_character_data_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • XML パーサのオプションを設定する

xml_parser_set_option

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_parser_set_option — XML パーサのオプションを設定する

説明

xml_parser_set_option(XMLParser $parser, int $option, string|int|bool $value): bool

XML パーサのオプションを設定します。

パラメータ

parser

オプションを設定する XML パーサへのリファレンス。

option

設定するオプション。以下を参照ください。

次のオプションが利用可能です。

XML パーサオプション
オプション定数 | データ型 | 説明
XML_OPTION_CASE_FOLDING | bool | XMLパーサの大文字変換 を有効にするかどうかを制御する。デフォルトで有効。
XML_OPTION_SKIP_TAGSTART | integer | タグ名の最初の何文字を読み飛ばすかどうかを設定する。
XML_OPTION_SKIP_WHITE | bool | 空白文字からなる値を読み飛ばすかどうかを設定する。
XML_OPTION_TARGET_ENCODING | string | XML パーサについてどの ターゲット エンコーディング を使用するかを設定する。デフォルトでは、 xml_parser_create() により使用されたソース エンコーディングと同じエンコーディングが設定されます。 サポートされるターゲットエンコーディングは、 ISO-8859-1, US-ASCII, UTF-8 です。

value

そのオプションの新しい設定値。

戻り値

成功した場合に true を返します。 失敗した場合、false を返します。

エラー / 例外

無効な値を option に渡すと、ValueError がスローされます。

PHP 8.0.0 より前のバージョンでは、 無効な値を option に渡すと E_WARNING が発生し、false を返していました。

変更履歴

バージョン | 説明
8.3.0 | value パラメータは、 boolean の値を受け入れるようになりました。 XML_OPTION_CASE_FOLDING と XML_OPTION_SKIP_WHITE が boolean の値を受け入れるようになっています。
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。
8.0.0 | option が無効な値の場合、 ValueError がスローされるようになりました。


文字データハンドラを設定する

  • ≪ xml_parser_set_option
  • xml_set_default_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • 文字データハンドラを設定する

xml_set_character_data_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_character_data_handler — 文字データハンドラを設定する

説明

xml_set_character_data_handler(XMLParser $parser, callable $handler): true

XML パーサ parser の文字データ用ハンドラ関数を設定します。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、以下でなければいけません:

handler(XMLParser $parser, string $data): void
parser
ハンドラをコールするXMLパーサ
data
文字データを文字列として指定します。

文字データハンドラは、XML ドキュメントのすべてのテキストに対してコールされます。 (たとえば非 ASCII 文字列などで) ひとつのフラグメント内で複数回コールされることもあります。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


デフォルトのハンドラを設定する

  • ≪ xml_set_character_data_handler
  • xml_set_element_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • デフォルトのハンドラを設定する

xml_set_default_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_default_handler — デフォルトのハンドラを設定する

説明

xml_set_default_handler(XMLParser $parser, callable $handler): true

XMLパーサ parser のデフォルトのハンドラ関数を設定します。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、以下でなければいけません:

handler(XMLParser $parser, string $data): void
parser
ハンドラをコールするXMLパーサ
data
data には、文字データを文字列として指定します。 これは、XML 宣言またはドキュメント型宣言、エンティティ、 他にハンドラがない別のデータとすることが可能です。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


開始要素および終了要素のハンドラを設定する

  • ≪ xml_set_default_handler
  • xml_set_end_namespace_decl_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • 開始要素および終了要素のハンドラを設定する

xml_set_element_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_element_handler — 開始要素および終了要素のハンドラを設定する

説明

xml_set_element_handler(XMLParser $parser, callable $start_handler, callable $end_handler): true

XML パーサ parser の要素ハンドラ関数を設定します。

start_handler は、新しいXML要素が開始された場合にコールされます。end_handler は、XML要素が終了した場合にコールされます。

パラメータ

parser

XMLパーサ

start_handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

シグネチャは、以下でなければいけません:

start_element_handler(XMLParser $parser, string $name, array $attributes): void
parser
ハンドラをコールするXMLパーサ
name
このハンドラがコールされた要素の名前です。 大文字変換 がこのパーサに関して有効な場合、要素の名前は大文字になります。
attributes
要素の属性に関する連想配列です。 要素に属性がない場合、配列は空になります。 この配列のキーは属性の名前であり、 値は属性の値です。属性の名前は、要素名と同様に 大文字変換 となります。 属性の値は、大文字変換 されません。 attributes を順次アクセスすることにより、 属性を宣言した元の順序で取得することができます。

end_handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

ハンドラのシグネチャは、以下でなければいけません:

end_element_handler(XMLParser $parser, string $name): void
parser
ハンドラをコールするXMLパーサ
name
このハンドラがコールされた要素の名前です。 このパーサにおいて 大文字変換 が有効な場合、要素名は大文字になります。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


名前空間終了ハンドラを設定する

  • ≪ xml_set_element_handler
  • xml_set_external_entity_ref_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • 名前空間終了ハンドラを設定する

xml_set_end_namespace_decl_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

xml_set_end_namespace_decl_handler — 名前空間終了ハンドラを設定する

説明

xml_set_end_namespace_decl_handler(XMLParser $parser, callable $handler): true

名前空間宣言のスコープを抜けるときにコールされるハンドラを設定します。 これがコールされるのは、各名前空間宣言において、 名前空間が宣言された要素の終了タグのハンドラがコールされた後のことです。

警告

このイベントは libXML ではサポートされていません。 そのため、登録されたハンドラは呼ばれません。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、以下でなければいけません:

handler(XMLParser $parser, string|false $prefix)
parser
ハンドラをコールするXMLパーサ
prefix
XML オブジェクト内の名前空間を参照する際に使う文字列。 prefix が存在しない場合は、false になります。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

参考

  • xml_set_start_namespace_decl_handler() - 名前空間開始ハンドラを設定する


外部エンティティリファレンスハンドラを設定する

  • ≪ xml_set_end_namespace_decl_handler
  • xml_set_notation_decl_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • 外部エンティティリファレンスハンドラを設定する

xml_set_external_entity_ref_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_external_entity_ref_handler — 外部エンティティリファレンスハンドラを設定する

説明

xml_set_external_entity_ref_handler(XMLParser $parser, callable $handler): true

XML パーサ parser の外部エンティティ参照用ハンドラ関数を設定します。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、以下でなければいけません:

handler(
XMLParser $parser,
string $open_entity_names,
string|false $base,
string $system_id,
string|false $public_id
): bool
parser
ハンドラをコールするXMLパーサ
open_entity_names
エンティティの処理を行うためにオープンされたエンティティの 名前のスペース区切りのリストです (参照されるエンティティの名前を含みます)。
base
これは外部エンティティのシステム ID (systemid) のベースとして解決されます。
system_id
エンティティ宣言で指定されたシステム ID です。
public_id
エンティティ宣言で 指定されたパブリック ID または指定されない場合は空の 文字列です。パブリック ID の中の空白文字は、XML 仕様で規定された 正規化を行っています。

ハンドラは、エンティティを処理された場合、true を返す必要があります。 そうでない場合、false を返すべきです。 ハンドラから返された値が false の場合、XML パーサは処理を中断し、 xml_get_error_code() は XML_ERROR_EXTERNAL_ENTITY_HANDLING を返します。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。
7.3.0 | 拡張モジュールが libxml を使ってビルドされた場合には、コールバック handler の戻り値が無視されることはなくなりました。 このバージョン以前はコールバックの戻り値が無視され、パースが止まりませんでした。

変更履歴

バージョン | 説明
7.3.0 | 拡張モジュールが libxml を使ってビルドされていた場合、 handler の戻り値は無視されることはなくなりました。 これより前のバージョンでは、戻り値が無視されていた上、パースが止まりませんでした。


表記法宣言ハンドラを設定する

  • ≪ xml_set_external_entity_ref_handler
  • xml_set_object ≫
  • PHP Manual
  • XML パーサ 関数
  • 表記法宣言ハンドラを設定する

xml_set_notation_decl_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_notation_decl_handler — 表記法宣言ハンドラを設定する

説明

xml_set_notation_decl_handler(XMLParser $parser, callable $handler): true

XML パーサ parser の表記法宣言用ハンドラ関数を設定します。

表記法の宣言は、ドキュメントの DTD の一部であり、 次のようなフォーマットとなります。

<!NOTATION <parameter>name</parameter>
{ <parameter>systemId</parameter> | <parameter>publicId</parameter>?>
表記法宣言の定義に関しては、 » XML 1.0 仕様の 4.7 節 を参照ください。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

ハンドラのシグネチャは、以下でなければいけません:

handler(
XMLParser $parser,
string $notation_name,
string|false $base,
string $system_id,
string|false $public_id
): void
parser
ハンドラをコールするXMLパーサ
notation_name
これは、前述の表記用フォーマットに示すように表記法の名前です。
base
外部エンティティのシステムID(system_id)を 取得する際の基本となります。
system_id
外部表記用宣言のシステム ID
public_id
外部表記用宣言のパブリック ID

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


オブジェクト内部で XML パーサを使用する

  • ≪ xml_set_notation_decl_handler
  • xml_set_processing_instruction_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • オブジェクト内部で XML パーサを使用する

xml_set_object

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_object — オブジェクト内部で XML パーサを使用する

説明

xml_set_object(XMLParser $parser, object $object): true

この関数は、object の内部から parser を使用可能にします。 xml_set_element_handler() 等により設定される 全てのコールバック関数は、object のメソッドであると仮定されます。

パラメータ

parser

オブジェクト内部で使う XML パーサへの参照。

object

XML パーサを使うオブジェクト。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

例

例1 xml_set_object() の例

<?php
class CustomXMLParser
{
private $parser;

function __construct()
{
$this->parser = xml_parser_create();

xml_set_object($this->parser, $this);
xml_set_element_handler($this->parser, "tag_open", "tag_close");
xml_set_character_data_handler($this->parser, "cdata");
}

function parse($data)
{
xml_parse($this->parser, $data);
}

function tag_open($parser, $tag, $attributes)
{
var_dump($tag, $attributes);
}

function cdata($parser, $cdata)
{
var_dump($cdata);
}

function tag_close($parser, $tag)
{
var_dump($tag);
}
}

$xml_parser = new CustomXMLParser();
$xml_parser->parse("<A ID='hallo'>PHP</A>");
?>

上の例の出力は以下となります。

string(1) "A"
array(1) {
  ["ID"]=>
  string(5) "hallo"
}
string(3) "PHP"
string(1) "A"


処理命令 (PI) 用ハンドラを設定する

  • ≪ xml_set_object
  • xml_set_start_namespace_decl_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • 処理命令 (PI) 用ハンドラを設定する

xml_set_processing_instruction_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_processing_instruction_handler — 処理命令 (PI) 用ハンドラを設定する

説明

xml_set_processing_instruction_handler(XMLParser $parser, callable $handler): true

XML パーサ parserの処理命令 (PI) 用ハンドラ関数を設定します。

処理命令のフォーマットは以下のとおりです:

<?target
data
?>

警告

PHP コードは、処理命令 <?php によって区切られます。 よって、XMLドキュメントに PHP コードを入れることが可能です。 しかし、PI 終了タグ (?>) をデータに含めてはいけません。 PI 終了タグ が埋め込まれたPHPコードの一部として存在していた場合、 残りの PHP コードは、"真の" PI 終了タグと同じく文字データとして処理されます。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、下記でなければいけません:

handler(XMLParser $parser, string $target, string $data): void
parser
ハンドラをコールするXMLパーサ
target
処理命令のターゲット
data
処理命令のデータ

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


名前空間開始ハンドラを設定する

  • ≪ xml_set_processing_instruction_handler
  • xml_set_unparsed_entity_decl_handler ≫
  • PHP Manual
  • XML パーサ 関数
  • 名前空間開始ハンドラを設定する

xml_set_start_namespace_decl_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

xml_set_start_namespace_decl_handler — 名前空間開始ハンドラを設定する

説明

xml_set_start_namespace_decl_handler(XMLParser $parser, callable $handler): true

名前空間を宣言したところでコールされるハンドラを設定します。 名前空間の宣言は、開始タグの中で行います。 しかし、名前空間宣言の開始ハンドラがコールされるのは、 その開始タグのハンドラがコールされるより前になります。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、以下でなければいけません:

handler(XMLParser $parser, string|false $prefix, string $uri): void
parser
ハンドラをコールするXMLパーサ
prefix
XML オブジェクト内の名前空間を参照する際に使う文字列。 存在しない場合は false になります。
uri
名前空間の URI。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。

参考

  • xml_set_end_namespace_decl_handler() - 名前空間終了ハンドラを設定する


処理されないエンティティ宣言用ハンドラを設定する

  • ≪ xml_set_start_namespace_decl_handler
  • XMLParser ≫
  • PHP Manual
  • XML パーサ 関数
  • 処理されないエンティティ宣言用ハンドラを設定する

xml_set_unparsed_entity_decl_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

xml_set_unparsed_entity_decl_handler — 処理されないエンティティ宣言用ハンドラを設定する

説明

xml_set_unparsed_entity_decl_handler(XMLParser $parser, callable $handler): true

XML パーサ parser の、 処理されないエンティティ宣言用ハンドラ関数を設定します。

このハンドラは、XML パーサが次のような NDATA 宣言を有する 外部エンティティ宣言を処理する際にコールされます。

<!ENTITY <parameter>name</parameter> {<parameter>publicId</parameter> | <parameter>systemId</parameter>}
        NDATA <parameter>notationName</parameter>

外部エンティティ宣言の記述用定義に関しては、 » XML 1.0 仕様の 4.2.2 節を参照ください。

パラメータ

parser

XMLパーサ

handler

null や空文字列を渡すと、ハンドラはデフォルトの状態にリセットされます。

handler が callable の場合、その callable がハンドラとして設定されます。

handler が文字列の場合、xml_set_object() で設定されたオブジェクトのメソッド名になります。

handler のシグネチャは、以下でなければいけません:

handler(
XMLParser $parser,
string $entity_name,
string|false $base,
string $system_id,
string|false $public_id,
string|false $notation_name
): void
parser
ハンドラをコールするXMLパーサ
entity_name
定義しようとするエンティティの名前。
base
外部エンティティのシステム ID(systemId) を取得する際のベースになります。
system_id
外部エンティティのシステム ID。
public_id
外部エンティティのパブリック ID。
notation_name
このエンティティの表記法の名前 (xml_set_notation_decl_handler() を参照ください)。

戻り値

常に true を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 parser は、 XMLParser インスタンスを期待するようになりました。 これより前のバージョンでは、有効な xml resource が期待されていました。


  • ≪ xml_set_unparsed_entity_decl_handler
  • XMLReader ≫
  • PHP Manual
  • XML パーサ
  • XMLParser クラス

XMLParser クラス

(PHP 8)

はじめに

PHP 8.0.0 以降、 xml リソースを置き換える完全不透明クラスです。

クラス概要

final class XMLParser {
}


XMLReader

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • XMLReader — XMLReader クラス
    • XMLReader::close — XMLReader の入力を閉じる
    • XMLReader::expand — 現在のノードのコピーを DOM オブジェクトとして返す
    • XMLReader::getAttribute — 名前をもとに、属性の値を取得する
    • XMLReader::getAttributeNo — インデックスをもとに、属性の値を取得する
    • XMLReader::getAttributeNs — 名前および URI をもとに、属性の値を取得する
    • XMLReader::getParserProperty — 指定したプロパティが設定されているかどうかを示す
    • XMLReader::isValid — パースしているドキュメントの妥当性を示す
    • XMLReader::lookupNamespace — プレフィックスから、名前空間を検索する
    • XMLReader::moveToAttribute — 指定した名前の属性にカーソルを移動する
    • XMLReader::moveToAttributeNo — 指定したインデックスの属性にカーソルを移動する
    • XMLReader::moveToAttributeNs — 指定した名前の属性にカーソルを移動する
    • XMLReader::moveToElement — 現在の属性の親要素にカーソルを移動する
    • XMLReader::moveToFirstAttribute — 最初の属性にカーソルを移動する
    • XMLReader::moveToNextAttribute — 次の属性にカーソルを移動する
    • XMLReader::next — すべてのサブツリーを飛ばして、次のノードにカーソルを移動する
    • XMLReader::open — パースする XML を含む URI を設定する
    • XMLReader::read — ドキュメント内の次のノードに移動する
    • XMLReader::readInnerXml — 現在のノードから XML を取得する
    • XMLReader::readOuterXml — 現在のノードから自分自身も含めた XML を取得する
    • XMLReader::readString — 現在のノードの内容を文字列で読み込む
    • XMLReader::setParserProperty — パーサのオプションを設定する
    • XMLReader::setRelaxNGSchema — RelaxNG スキーマのファイル名あるいは URI を設定する
    • XMLReader::setRelaxNGSchemaSource — RelaxNG スキーマを含むデータを設定する
    • XMLReader::setSchema — ドキュメントを XSD で検証する
    • XMLReader::XML — パースする XML を含むデータを設定する


はじめに

XMLReader 拡張モジュールは、プル型の XML パーサです。ドキュメント ストリーム内をカーソル風に進んでいき、その途中の各ノードで立ち止まります。

エンコーディング

内部的には、libxml は UTF-8 エンコーディングを使用しています。 したがって、取得したデータはすべて UTF-8 エンコーディングに変換されます。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XMLReader
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


インストール手順

XMLReader 拡張モジュールは、PHP にバンドルされています。 この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-xmlreader


XMLReader クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

はじめに

XMLReader 拡張モジュールは、プル型の XML パーサです。ドキュメント ストリーム内をカーソル風に進んでいき、その途中の各ノードで立ち止まります。

クラス概要

class XMLReader {
/* 定数 */
public const int NONE;
public const int ELEMENT;
public const int ATTRIBUTE;
public const int TEXT;
public const int CDATA;
public const int ENTITY_REF;
public const int ENTITY;
public const int PI;
public const int COMMENT;
public const int DOC;
public const int DOC_TYPE;
public const int DOC_FRAGMENT;
public const int NOTATION;
public const int WHITESPACE;
public const int SIGNIFICANT_WHITESPACE;
public const int END_ELEMENT;
public const int END_ENTITY;
public const int XML_DECLARATION;
public const int LOADDTD;
public const int DEFAULTATTRS;
public const int VALIDATE;
public const int SUBST_ENTITIES;
/* プロパティ */
public int $attributeCount;
public string $baseURI;
public int $depth;
public bool $hasAttributes;
public bool $hasValue;
public bool $isDefault;
public bool $isEmptyElement;
public string $localName;
public string $name;
public string $namespaceURI;
public int $nodeType;
public string $prefix;
public string $value;
public string $xmlLang;
/* メソッド */
public close(): true
public expand(?DOMNode $baseNode = null): DOMNode|false
public getAttribute(string $name): ?string
public getAttributeNo(int $index): ?string
public getAttributeNs(string $name, string $namespace): ?string
public getParserProperty(int $property): bool
public isValid(): bool
public lookupNamespace(string $prefix): ?string
public moveToAttribute(string $name): bool
public moveToAttributeNo(int $index): bool
public moveToAttributeNs(string $name, string $namespace): bool
public moveToElement(): bool
public moveToFirstAttribute(): bool
public moveToNextAttribute(): bool
public next(?string $name = null): bool
public static open(string $uri, ?string $encoding = null, int $flags = 0): XMLReader
public open(string $uri, ?string $encoding = null, int $flags = 0): bool
public read(): bool
public readInnerXml(): string
public readOuterXml(): string
public readString(): string
public setParserProperty(int $property, bool $value): bool
public setRelaxNGSchema(?string $filename): bool
public setRelaxNGSchemaSource(?string $source): bool
public setSchema(?string $filename): bool
public static XML(string $source, ?string $encoding = null, int $flags = 0): XMLReader
public XML(string $source, ?string $encoding = null, int $flags = 0): bool
}

プロパティ

attributeCount

ノード上の属性の数

baseURI

ノードのベース URI

depth

ツリー内でのノードの階層 (0 から数える)

hasAttributes

ノードが属性を保持しているかどうか

hasValue

ノードがテキストの値を保持しているかどうか

isDefault

属性が DTD のデフォルトかどうか

isEmptyElement

ノードが空要素のタグかどうか

localName

ノードのローカル名

name

ノードの限定名

namespaceURI

ノードに関連付けられた名前空間の URI

nodeType

ノードの型

prefix

ノードに関連付けられた名前空間のプレフィックス

value

ノードのテキスト値

xmlLang

ノードが存在する xml:lang スコープ

定義済み定数

XMLReader ノード型

XMLReader::NONE

ノード型なし

XMLReader::ELEMENT

開始要素

XMLReader::ATTRIBUTE

属性ノード

XMLReader::TEXT

テキストノード

XMLReader::CDATA

CDATA ノード

XMLReader::ENTITY_REF

エンティティ参照ノード

XMLReader::ENTITY

エンティティ宣言ノード

XMLReader::PI

処理命令 (Processing Instruction) ノード

XMLReader::COMMENT

コメントノード

XMLReader::DOC

文書ノード

XMLReader::DOC_TYPE

文書型ノード

XMLReader::DOC_FRAGMENT

文書片ノード

XMLReader::NOTATION

記法ノード

XMLReader::WHITESPACE

Whitespace ノード

XMLReader::SIGNIFICANT_WHITESPACE

Significant Whitespace ノード

XMLReader::END_ELEMENT

終了要素

XMLReader::END_ENTITY

終了エンティティ

XMLReader::XML_DECLARATION

XML 宣言ノード

XMLReader パーサオプション

XMLReader::LOADDTD

DTD を読み込むが、妥当性は検証しない

XMLReader::DEFAULTATTRS

DTD およびデフォルト属性を読み込むが、妥当性は検証しない

XMLReader::VALIDATE

DTD を読み込み、パース時に妥当性を検証する

XMLReader::SUBST_ENTITIES

エンティティを参照で置き換える

目次

  • XMLReader::close — XMLReader の入力を閉じる
  • XMLReader::expand — 現在のノードのコピーを DOM オブジェクトとして返す
  • XMLReader::getAttribute — 名前をもとに、属性の値を取得する
  • XMLReader::getAttributeNo — インデックスをもとに、属性の値を取得する
  • XMLReader::getAttributeNs — 名前および URI をもとに、属性の値を取得する
  • XMLReader::getParserProperty — 指定したプロパティが設定されているかどうかを示す
  • XMLReader::isValid — パースしているドキュメントの妥当性を示す
  • XMLReader::lookupNamespace — プレフィックスから、名前空間を検索する
  • XMLReader::moveToAttribute — 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToAttributeNo — 指定したインデックスの属性にカーソルを移動する
  • XMLReader::moveToAttributeNs — 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToElement — 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToFirstAttribute — 最初の属性にカーソルを移動する
  • XMLReader::moveToNextAttribute — 次の属性にカーソルを移動する
  • XMLReader::next — すべてのサブツリーを飛ばして、次のノードにカーソルを移動する
  • XMLReader::open — パースする XML を含む URI を設定する
  • XMLReader::read — ドキュメント内の次のノードに移動する
  • XMLReader::readInnerXml — 現在のノードから XML を取得する
  • XMLReader::readOuterXml — 現在のノードから自分自身も含めた XML を取得する
  • XMLReader::readString — 現在のノードの内容を文字列で読み込む
  • XMLReader::setParserProperty — パーサのオプションを設定する
  • XMLReader::setRelaxNGSchema — RelaxNG スキーマのファイル名あるいは URI を設定する
  • XMLReader::setRelaxNGSchemaSource — RelaxNG スキーマを含むデータを設定する
  • XMLReader::setSchema — ドキュメントを XSD で検証する
  • XMLReader::XML — パースする XML を含むデータを設定する


XMLReader の入力を閉じる

  • ≪ XMLReader
  • XMLReader::expand ≫
  • PHP Manual
  • XMLReader
  • XMLReader の入力を閉じる

XMLReader::close

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::close — XMLReader の入力を閉じる

説明

public XMLReader::close(): true

XMLReader オブジェクトが現在パースしている入力を閉じます。

パラメータ

この関数にはパラメータはありません。

戻り値

常に true を返します。

参考

  • XMLReader::open() - パースする XML を含む URI を設定する
  • XMLReader::xml() - パースする XML を含むデータを設定する


現在のノードのコピーを DOM オブジェクトとして返す

  • ≪ XMLReader::close
  • XMLReader::getAttribute ≫
  • PHP Manual
  • XMLReader
  • 現在のノードのコピーを DOM オブジェクトとして返す

XMLReader::expand

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::expand — 現在のノードのコピーを DOM オブジェクトとして返す

説明

public XMLReader::expand(?DOMNode $baseNode = null): DOMNode|false

このメソッドは、現在のノードをコピーして適切な DOM オブジェクトを返します。

パラメータ

baseNode

DOM オブジェクトを作る対象の DOMDocument を示す DOMNode。

戻り値

DOMNode か、エラー時には false を返します。


名前をもとに、属性の値を取得する

  • ≪ XMLReader::expand
  • XMLReader::getAttributeNo ≫
  • PHP Manual
  • XMLReader
  • 名前をもとに、属性の値を取得する

XMLReader::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::getAttribute — 名前をもとに、属性の値を取得する

説明

public XMLReader::getAttribute(string $name): ?string

指定した名前の属性の値を返します。属性が存在しなかったり 現在位置が要素ノードでなかったりした場合には null を返します。

パラメータ

name

属性の名前。

戻り値

属性の値を返します。指定した名前 name の 属性が見つからなかったり、現在位置が要素ノードではなかったりした場合には null を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は false を返さなくなりました。

参考

  • XMLReader::getAttributeNo() - インデックスをもとに、属性の値を取得する
  • XMLReader::getAttributeNs() - 名前および URI をもとに、属性の値を取得する


インデックスをもとに、属性の値を取得する

  • ≪ XMLReader::getAttribute
  • XMLReader::getAttributeNs ≫
  • PHP Manual
  • XMLReader
  • インデックスをもとに、属性の値を取得する

XMLReader::getAttributeNo

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::getAttributeNo — インデックスをもとに、属性の値を取得する

説明

public XMLReader::getAttributeNo(int $index): ?string

その位置をもとにして属性の値を返します。属性が存在しなかったり 現在位置が要素ノードでなかったりした場合には空の文字列を返します。

パラメータ

index

属性の位置。

戻り値

属性の値を返します。指定した位置 index に 属性が見つからなかったり、現在位置が要素ではなかったりした場合には null を返します。

参考

  • XMLReader::getAttribute() - 名前をもとに、属性の値を取得する
  • XMLReader::getAttributeNs() - 名前および URI をもとに、属性の値を取得する


名前および URI をもとに、属性の値を取得する

  • ≪ XMLReader::getAttributeNo
  • XMLReader::getParserProperty ≫
  • PHP Manual
  • XMLReader
  • 名前および URI をもとに、属性の値を取得する

XMLReader::getAttributeNs

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::getAttributeNs — 名前および URI をもとに、属性の値を取得する

説明

public XMLReader::getAttributeNs(string $name, string $namespace): ?string

名前および名前空間 URI をもとにして属性の値を返します。 属性が存在しなかったり、現在位置が要素ノードでなかったりした場合には 空の文字列を返します。

パラメータ

name

ローカルの名前。

namespace

名前空間の URI。

戻り値

属性の値を返します。指定した name および namespace に属性が見つからなかったり、 現在位置が要素ではなかったりした場合には null を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は false を返さなくなりました。

参考

  • XMLReader::getAttribute() - 名前をもとに、属性の値を取得する
  • XMLReader::getAttributeNo() - インデックスをもとに、属性の値を取得する


指定したプロパティが設定されているかどうかを示す

  • ≪ XMLReader::getAttributeNs
  • XMLReader::isValid ≫
  • PHP Manual
  • XMLReader
  • 指定したプロパティが設定されているかどうかを示す

XMLReader::getParserProperty

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::getParserProperty — 指定したプロパティが設定されているかどうかを示す

説明

public XMLReader::getParserProperty(int $property): bool

指定したプロパティが設定されているかどうかを示します。

パラメータ

property

パーサオプション定数 のうちのひとつ。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::setParserProperty() - パーサのオプションを設定する


パースしているドキュメントの妥当性を示す

  • ≪ XMLReader::getParserProperty
  • XMLReader::lookupNamespace ≫
  • PHP Manual
  • XMLReader
  • パースしているドキュメントの妥当性を示す

XMLReader::isValid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::isValid — パースしているドキュメントの妥当性を示す

説明

public XMLReader::isValid(): bool

DTD や RelaxNG schema を参照し、 パースしているドキュメントが妥当なものであるかどうかを論理型で返します。 schema がない場合、かつ DTD の検証オプションが指定されない場合、 このメソッドは false を返します。

パラメータ

この関数にはパラメータはありません。

戻り値

ドキュメントが妥当である場合は true を返します。 そうでない場合、false を返します。

例

例1 XML の妥当性の検証

<?php
$xml = XMLReader::open('test.xml');

// validate オプションを有効にしておかないと、
// このメソッドは正しく動作しません
$xml->setParserProperty(XMLReader::VALIDATE, true);

var_dump($xml->isValid());
?>

注意

注意: このメソッドは、現在のノードだけをチェックします。ドキュメント全体をチェックするわけではありません。

参考

  • XMLReader::setParserProperty() - パーサのオプションを設定する
  • XMLReader::setRelaxNGSchema() - RelaxNG スキーマのファイル名あるいは URI を設定する
  • XMLReader::setRelaxNGSchemaSource() - RelaxNG スキーマを含むデータを設定する
  • XMLReader::setSchema() - ドキュメントを XSD で検証する


プレフィックスから、名前空間を検索する

  • ≪ XMLReader::isValid
  • XMLReader::moveToAttribute ≫
  • PHP Manual
  • XMLReader
  • プレフィックスから、名前空間を検索する

XMLReader::lookupNamespace

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::lookupNamespace — プレフィックスから、名前空間を検索する

説明

public XMLReader::lookupNamespace(string $prefix): ?string

指定したプレフィックスをもとに、スコープの名前空間を検索します。

パラメータ

prefix

プレフィックスを含む文字列。

戻り値

名前空間の値を返します。 見つからなかった場合は、null を返します。

変更履歴

バージョン | 説明
8.0.0 | この関数は false を返さなくなりました。


指定した名前の属性にカーソルを移動する

  • ≪ XMLReader::lookupNamespace
  • XMLReader::moveToAttributeNo ≫
  • PHP Manual
  • XMLReader
  • 指定した名前の属性にカーソルを移動する

XMLReader::moveToAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::moveToAttribute — 指定した名前の属性にカーソルを移動する

説明

public XMLReader::moveToAttribute(string $name): bool

指定した名前の属性にカーソルを移動します。

パラメータ

name

属性の名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttributeNo() - 指定したインデックスの属性にカーソルを移動する
  • XMLReader::moveToAttributeNs() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToFirstAttribute() - 最初の属性にカーソルを移動する


指定したインデックスの属性にカーソルを移動する

  • ≪ XMLReader::moveToAttribute
  • XMLReader::moveToAttributeNs ≫
  • PHP Manual
  • XMLReader
  • 指定したインデックスの属性にカーソルを移動する

XMLReader::moveToAttributeNo

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::moveToAttributeNo — 指定したインデックスの属性にカーソルを移動する

説明

public XMLReader::moveToAttributeNo(int $index): bool

指定した位置の属性にカーソルを移動します。

パラメータ

index

属性の位置。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToAttributeNs() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToFirstAttribute() - 最初の属性にカーソルを移動する


指定した名前の属性にカーソルを移動する

  • ≪ XMLReader::moveToAttributeNo
  • XMLReader::moveToElement ≫
  • PHP Manual
  • XMLReader
  • 指定した名前の属性にカーソルを移動する

XMLReader::moveToAttributeNs

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::moveToAttributeNs — 指定した名前の属性にカーソルを移動する

説明

public XMLReader::moveToAttributeNs(string $name, string $namespace): bool

指定した名前空間内で、指定した名前の属性にカーソルを移動します。

パラメータ

name

ローカル名。

namespace

名前空間の URI。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToAttributeNo() - 指定したインデックスの属性にカーソルを移動する
  • XMLReader::moveToFirstAttribute() - 最初の属性にカーソルを移動する


現在の属性の親要素にカーソルを移動する

  • ≪ XMLReader::moveToAttributeNs
  • XMLReader::moveToFirstAttribute ≫
  • PHP Manual
  • XMLReader
  • 現在の属性の親要素にカーソルを移動する

XMLReader::moveToElement

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::moveToElement — 現在の属性の親要素にカーソルを移動する

説明

public XMLReader::moveToElement(): bool

現在の属性の親要素にカーソルを移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true、失敗した場合、 あるいはメソッドがコールされた際の位置が属性ノードではなかった場合に false を返します。

参考

  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToAttributeNo() - 指定したインデックスの属性にカーソルを移動する
  • XMLReader::moveToAttributeNs() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToFirstAttribute() - 最初の属性にカーソルを移動する


最初の属性にカーソルを移動する

  • ≪ XMLReader::moveToElement
  • XMLReader::moveToNextAttribute ≫
  • PHP Manual
  • XMLReader
  • 最初の属性にカーソルを移動する

XMLReader::moveToFirstAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::moveToFirstAttribute — 最初の属性にカーソルを移動する

説明

public XMLReader::moveToFirstAttribute(): bool

最初の属性にカーソルを移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToAttributeNo() - 指定したインデックスの属性にカーソルを移動する
  • XMLReader::moveToAttributeNs() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToNextAttribute() - 次の属性にカーソルを移動する


次の属性にカーソルを移動する

  • ≪ XMLReader::moveToFirstAttribute
  • XMLReader::next ≫
  • PHP Manual
  • XMLReader
  • 次の属性にカーソルを移動する

XMLReader::moveToNextAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::moveToNextAttribute — 次の属性にカーソルを移動する

説明

public XMLReader::moveToNextAttribute(): bool

現在位置が属性ノードの場合は次の属性にカーソルを移動します。 現在位置が要素ノードの場合は最初の属性にカーソルを移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToAttributeNo() - 指定したインデックスの属性にカーソルを移動する
  • XMLReader::moveToAttributeNs() - 指定した名前の属性にカーソルを移動する
  • XMLReader::moveToFirstAttribute() - 最初の属性にカーソルを移動する


すべてのサブツリーを飛ばして、次のノードにカーソルを移動する

  • ≪ XMLReader::moveToNextAttribute
  • XMLReader::open ≫
  • PHP Manual
  • XMLReader
  • すべてのサブツリーを飛ばして、次のノードにカーソルを移動する

XMLReader::next

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::next — すべてのサブツリーを飛ばして、次のノードにカーソルを移動する

説明

public XMLReader::next(?string $name = null): bool

すべてのサブツリーを飛ばして、カーソルを次のノードに移動します。 次のノードが存在しない場合、カーソルは文書の一番最後に移動します。

パラメータ

name

移動先のノードの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | name は、nullable になりました。

参考

  • XMLReader::moveToNextAttribute() - 次の属性にカーソルを移動する
  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する


パースする XML を含む URI を設定する

  • ≪ XMLReader::next
  • XMLReader::read ≫
  • PHP Manual
  • XMLReader
  • パースする XML を含む URI を設定する

XMLReader::open

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::open — パースする XML を含む URI を設定する

説明

public static XMLReader::open(string $uri, ?string $encoding = null, int $flags = 0): XMLReader
public XMLReader::open(string $uri, ?string $encoding = null, int $flags = 0): bool

パースされる XML ドキュメントを含む URI を設定します。

パラメータ

uri

ドキュメントを指す URI。

encoding

ドキュメントのエンコーディングあるいは null。

flags

LIBXML_* 定数のビットマスク。

戻り値

成功した場合に true を、失敗した場合に false を返します。 static メソッドとしてコールされた場合には XMLReader を返します。 失敗した場合に false を返します

エラー / 例外

このメソッドは、staticメソッドとしてコールすることが出来ます。 しかし、PHP 8.0.0 より前のバージョンでは、 staticメソッドとしてコールすると E_DEPRECATED が発生していました。

変更履歴

バージョン | 説明
8.0.0 | XMLReader::open() はstaticメソッドとして宣言されるようになりました。 しかし、XMLReader のインスタンス経由でも呼び出すことが出来ます。

参考

  • XMLReader::xml() - パースする XML を含むデータを設定する
  • XMLReader::close() - XMLReader の入力を閉じる


ドキュメント内の次のノードに移動する

  • ≪ XMLReader::open
  • XMLReader::readInnerXml ≫
  • PHP Manual
  • XMLReader
  • ドキュメント内の次のノードに移動する

XMLReader::read

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::read — ドキュメント内の次のノードに移動する

説明

public XMLReader::read(): bool

ドキュメント内の次のノードにカーソルを移動します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::moveToElement() - 現在の属性の親要素にカーソルを移動する
  • XMLReader::moveToAttribute() - 指定した名前の属性にカーソルを移動する
  • XMLReader::next() - すべてのサブツリーを飛ばして、次のノードにカーソルを移動する


現在のノードから XML を取得する

  • ≪ XMLReader::read
  • XMLReader::readOuterXml ≫
  • PHP Manual
  • XMLReader
  • 現在のノードから XML を取得する

XMLReader::readInnerXml

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

XMLReader::readInnerXml — 現在のノードから XML を取得する

説明

public XMLReader::readInnerXml(): string

現在のノードの中身を、子ノードやマークアップも含めて読み込みます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードの中身を文字列で返します。失敗した場合は空文字列を返します。

注意

警告

この関数は、PHP を libxml 20620 以降と組み合わせてコンパイルした場合にのみ使用可能です。

参考

  • XMLReader::readString() - 現在のノードの内容を文字列で読み込む
  • XMLReader::readOuterXml() - 現在のノードから自分自身も含めた XML を取得する
  • XMLReader::expand() - 現在のノードのコピーを DOM オブジェクトとして返す


現在のノードから自分自身も含めた XML を取得する

  • ≪ XMLReader::readInnerXml
  • XMLReader::readString ≫
  • PHP Manual
  • XMLReader
  • 現在のノードから自分自身も含めた XML を取得する

XMLReader::readOuterXml

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

XMLReader::readOuterXml — 現在のノードから自分自身も含めた XML を取得する

説明

public XMLReader::readOuterXml(): string

現在のノードの中身を、ノード自身も含めて読み込みます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードの中身を、自分自身も含めて文字列で返します。失敗した場合は空文字列を返します。

注意

警告

この関数は、PHP を libxml 20620 以降と組み合わせてコンパイルした場合にのみ使用可能です。

参考

  • XMLReader::readString() - 現在のノードの内容を文字列で読み込む
  • XMLReader::readInnerXml() - 現在のノードから XML を取得する
  • XMLReader::expand() - 現在のノードのコピーを DOM オブジェクトとして返す


現在のノードの内容を文字列で読み込む

  • ≪ XMLReader::readOuterXml
  • XMLReader::setParserProperty ≫
  • PHP Manual
  • XMLReader
  • 現在のノードの内容を文字列で読み込む

XMLReader::readString

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

XMLReader::readString — 現在のノードの内容を文字列で読み込む

説明

public XMLReader::readString(): string

現在のノードの内容を文字列で読み込みます。

パラメータ

この関数にはパラメータはありません。

戻り値

現在のノードの内容を文字列で返します。失敗した場合は空文字列を返します。

注意

警告

この関数は、PHP を libxml 20620 以降と組み合わせてコンパイルした場合にのみ使用可能です。

参考

  • XMLReader::readOuterXml() - 現在のノードから自分自身も含めた XML を取得する
  • XMLReader::readInnerXml() - 現在のノードから XML を取得する
  • XMLReader::expand() - 現在のノードのコピーを DOM オブジェクトとして返す


パーサのオプションを設定する

  • ≪ XMLReader::readString
  • XMLReader::setRelaxNGSchema ≫
  • PHP Manual
  • XMLReader
  • パーサのオプションを設定する

XMLReader::setParserProperty

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::setParserProperty — パーサのオプションを設定する

説明

public XMLReader::setParserProperty(int $property, bool $value): bool

パーサのオプションを設定します。オプションは、
XMLReader::open() あるいは
XMLReader::xml() がコールされた後で、かつ
XMLReader::read() が最初にコールされる前に
設定する必要があります。

パラメータ

property

パーサオプション定数 のひとつ。

value

true を設定するとオプションが有効になり、それ以外を設定すると 無効になります。

戻り値

成功した場合に true を、失敗した場合に false を返します。


RelaxNG スキーマのファイル名あるいは URI を設定する

  • ≪ XMLReader::setParserProperty
  • XMLReader::setRelaxNGSchemaSource ≫
  • PHP Manual
  • XMLReader
  • RelaxNG スキーマのファイル名あるいは URI を設定する

XMLReader::setRelaxNGSchema

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::setRelaxNGSchema — RelaxNG スキーマのファイル名あるいは URI を設定する

説明

public XMLReader::setRelaxNGSchema(?string $filename): bool

検証の際に使用する RelaxNG スキーマのファイル名あるいは URI を 設定します。

パラメータ

filename

RelaxNG スキーマを指すファイル名あるいは URI。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::setRelaxNGSchemaSource() - RelaxNG スキーマを含むデータを設定する
  • XMLReader::setSchema() - ドキュメントを XSD で検証する
  • XMLReader::isValid() - パースしているドキュメントの妥当性を示す


RelaxNG スキーマを含むデータを設定する

  • ≪ XMLReader::setRelaxNGSchema
  • XMLReader::setSchema ≫
  • PHP Manual
  • XMLReader
  • RelaxNG スキーマを含むデータを設定する

XMLReader::setRelaxNGSchemaSource

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::setRelaxNGSchemaSource — RelaxNG スキーマを含むデータを設定する

説明

public XMLReader::setRelaxNGSchemaSource(?string $source): bool

検証の際に使用する RelaxNG スキーマを含むデータを設定します。

パラメータ

source

RelaxNG スキーマを含む文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XMLReader::setRelaxNGSchema() - RelaxNG スキーマのファイル名あるいは URI を設定する
  • XMLReader::setSchema() - ドキュメントを XSD で検証する
  • XMLReader::isValid() - パースしているドキュメントの妥当性を示す


ドキュメントを XSD で検証する

  • ≪ XMLReader::setRelaxNGSchemaSource
  • XMLReader::XML ≫
  • PHP Manual
  • XMLReader
  • ドキュメントを XSD で検証する

XMLReader::setSchema

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

XMLReader::setSchema — ドキュメントを XSD で検証する

説明

public XMLReader::setSchema(?string $filename): bool

W3C XSD スキーマを用いて、処理中のドキュメントを検証します。 最初の Read() の前にのみ実行可能です。

パラメータ

filename

XSD スキーマファイル名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

エラー / 例外

libxml がスキーマのサポートなしでビルドされていた場合、 スキーマにエラーが存在する場合、 あるいは既に XMLReader::read() がコールされた後である場合に E_WARNING を発行します。

注意

警告

この関数は、PHP を libxml 20620 以降と組み合わせてコンパイルした場合にのみ使用可能です。

参考

  • XMLReader::setRelaxNGSchema() - RelaxNG スキーマのファイル名あるいは URI を設定する
  • XMLReader::setRelaxNGSchemaSource() - RelaxNG スキーマを含むデータを設定する
  • XMLReader::isValid() - パースしているドキュメントの妥当性を示す


パースする XML を含むデータを設定する

  • ≪ XMLReader::setSchema
  • XMLWriter ≫
  • PHP Manual
  • XMLReader
  • パースする XML を含むデータを設定する

XMLReader::XML

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

XMLReader::XML — パースする XML を含むデータを設定する

説明

public static XMLReader::XML(string $source, ?string $encoding = null, int $flags = 0): XMLReader
public XMLReader::XML(string $source, ?string $encoding = null, int $flags = 0): bool

パースする XML を含むデータを設定します。

パラメータ

source

パースされる XML を含む文字列。

encoding

ドキュメントのエンコーディングあるいは null。

flags

LIBXML_* 定数のビットマスク。

戻り値

成功した場合に true を、失敗した場合に false を返します。 staticメソッドとしてコールされた場合には XMLReader を返します。 失敗した場合に false を返します

エラー / 例外

このメソッドは、staticメソッドとしてコールすることが出来ます。 しかし、PHP 8.0.0 より前のバージョンでは、 staticメソッドとしてコールすると E_DEPRECATED が発生していました。

変更履歴

バージョン | 説明
8.0.0 | XMLReader::XML() は、staticメソッドとして宣言されるようになりました。 しかし、XMLReader のインスタンス経由でも呼び出すことができます。

参考

  • XMLReader::open() - パースする XML を含む URI を設定する
  • XMLReader::close() - XMLReader の入力を閉じる


XMLWriter

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
    • リソース型
  • 例
    • 単純な XML ドキュメントの作成
    • XML 名前空間の使用
    • オブジェクト指向 API の使用
  • XMLWriter — XMLWriter クラス
    • XMLWriter::endAttribute — 属性を終了する
    • XMLWriter::endCdata — 現在の CDATA を終了する
    • XMLWriter::endComment — コメントの終了部を作成する
    • XMLWriter::endDocument — 現在のドキュメントを終了する
    • XMLWriter::endDtd — 現在の DTD を終了する
    • XMLWriter::endDtdAttlist — 現在の DTD 属性リストを終了する
    • XMLWriter::endDtdElement — 現在の DTD 要素を終了する
    • XMLWriter::endDtdEntity — 現在の DTD エンティティを終了する
    • XMLWriter::endElement — 現在の要素を終了する
    • XMLWriter::endPi — 現在の PI (処理命令) を終了する
    • XMLWriter::flush — 現在のバッファをフラッシュする
    • XMLWriter::fullEndElement — 現在の要素を終了する
    • XMLWriter::openMemory — 文字列の出力にメモリを使用する新しい xmlwriter を作成する
    • XMLWriter::openUri — ソース URI を指定して新しい xmlwriter を作成する
    • XMLWriter::outputMemory — 現在のバッファを返す
    • XMLWriter::setIndent — 字下げの on/off を切り替える
    • XMLWriter::setIndentString — 字下げに使用する文字列を設定する
    • XMLWriter::startAttribute — 属性を開始する
    • XMLWriter::startAttributeNs — 名前空間つきの属性を開始する
    • XMLWriter::startCdata — CDATA の開始タグを作成する
    • XMLWriter::startComment — コメントを開始する
    • XMLWriter::startDocument — ドキュメントタグを作成する
    • XMLWriter::startDtd — DTD の開始タグを作成する
    • XMLWriter::startDtdAttlist — DTD 属性リストを開始する
    • XMLWriter::startDtdElement — DTD 要素を開始する
    • XMLWriter::startDtdEntity — DTD エンティティを開始する
    • XMLWriter::startElement — 要素の開始タグを作成する
    • XMLWriter::startElementNs — 名前空間つき要素の開始タグを作成する
    • XMLWriter::startPi — PI (処理命令) の開始タグを作成する
    • XMLWriter::text — テキストを書き込む
    • XMLWriter::writeAttribute — 属性全体を書き込む
    • XMLWriter::writeAttributeNs — 名前空間つき属性全体を書き込む
    • XMLWriter::writeCdata — CDATA タグ全体を書き込む
    • XMLWriter::writeComment — コメントタグ全体を書き込む
    • XMLWriter::writeDtd — DTD タグ全体を書き込む
    • XMLWriter::writeDtdAttlist — DTD 属性リストタグ全体を書き込む
    • XMLWriter::writeDtdElement — DTD 要素タグ全体を書き込む
    • XMLWriter::writeDtdEntity — DTD エンティティタグ全体を書き込む
    • XMLWriter::writeElement — 要素タグ全体を書き込む
    • XMLWriter::writeElementNs — 名前空間つき要素タグ全体を書き込む
    • XMLWriter::writePi — PI (処理命令) 書き込む
    • XMLWriter::writeRaw — 生の XML テキストを書き込む


はじめに

これは、XMLWriter 拡張モジュールです。 libxml の xmlWriter API をラップしています。

この拡張モジュールは、キャッシュ処理をしない前進のみのライターで、 XML データを含むストリームあるいはファイルを作成します。

この拡張モジュールは、オブジェクト指向形式と手続き型のどちらでも使用可能です。 全メソッドについて、その両方のコール方法を説明しています。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XMLWriter
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順
  • リソース型


インストール手順

XMLWriter 拡張モジュールは、PHP にバンドルされています。 この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-xmlwriter


リソース型

PHP 8.0.0 より前のバージョンでは、手続き型の XMLWriter 拡張モジュールでは、 一種類のリソースを使用していました。 これは、xmlwriter_open_memory() あるいは xmlwriter_open_uri() が返すものです。


  • ≪ リソース型
  • 単純な XML ドキュメントの作成 ≫
  • PHP Manual
  • XMLWriter
  • 例

例

目次

  • 単純な XML ドキュメントの作成
  • XML 名前空間の使用
  • オブジェクト指向 API の使用


単純な XML ドキュメントの作成

この例では、XMLWriter を使ってメモリ上に XML ドキュメントを作る方法を示します。

例1 単純な XML ドキュメントの作成

<?php

$xw = xmlwriter_open_memory();
xmlwriter_set_indent($xw, 1);
$res = xmlwriter_set_indent_string($xw, ' ');

xmlwriter_start_document($xw, '1.0', 'UTF-8');

// 最初の要素
xmlwriter_start_element($xw, 'tag1');

// 要素 'tag1' の属性 'att1'
xmlwriter_start_attribute($xw, 'att1');
xmlwriter_text($xw, 'valueofatt1');
xmlwriter_end_attribute($xw);

xmlwriter_write_comment($xw, 'this is a comment.');

// 子要素を開始
xmlwriter_start_element($xw, 'tag11');
xmlwriter_text($xw, 'This is a sample text, a');
xmlwriter_end_element($xw); // tag11

xmlwriter_end_element($xw); // tag1

// CDATA
xmlwriter_start_element($xw, 'testc');
xmlwriter_write_cdata($xw, "This is cdata content");
xmlwriter_end_element($xw); // testc

xmlwriter_start_element($xw, 'testc');
xmlwriter_start_cdata($xw);
xmlwriter_text($xw, "test cdata2");
xmlwriter_end_cdata($xw);
xmlwriter_end_element($xw); // testc

// 処理命令
xmlwriter_start_pi($xw, 'php');
xmlwriter_text($xw, '$foo=2;echo $foo;');
xmlwriter_end_pi($xw);

xmlwriter_end_document($xw);

echo xmlwriter_output_memory($xw);

上の例の出力は以下となります。

<?xml version="1.0" encoding="UTF-8"?>
<tag1 att1="valueofatt1">
 <!--this is a comment.-->
 <tag11>This is a sample text, a</tag11>
</tag1>
<testc><![CDATA[This is cdata content]]></testc>
<testc><![CDATA[test cdata2]]></testc>
<?php $foo=2;echo $foo;?>


XML 名前空間の使用

この例では、名前空間を指定した XML 要素を作る方法を示します。

例1 XML 名前空間の使用

<?php

$xw = xmlwriter_open_memory();
xmlwriter_set_indent($xw, 1);
$res = xmlwriter_set_indent_string($xw, ' ');

xmlwriter_start_document($xw, '1.0', 'UTF-8');
// 最初の要素
xmlwriter_start_element_ns($xw,'prefix', 'books', 'uri');
xmlwriter_start_attribute($xw, 'isbn');

xmlwriter_start_attribute_ns($xw, 'prefix', 'isbn', 'uri');
xmlwriter_end_attribute($xw);

xmlwriter_end_attribute($xw);

xmlwriter_text($xw, 'book1');
xmlwriter_end_element($xw);

xmlwriter_end_document($xw);

echo xmlwriter_output_memory($xw);

上の例の出力は以下となります。

<?xml version="1.0" encoding="UTF-8"?>
<prefix:books isbn="" prefix:isbn="" xmlns:prefix="uri">book1</prefix:books>


オブジェクト指向 API の使用

この例では、XMLWriter のオブジェクト指向 API を使う方法を示します。

例1 オブジェクト指向 API の使用

<?php

$xw = new XMLWriter();
$xw->openMemory();
$xw->startDocument("1.0");
$xw->startElement("book");
$xw->text("example");
$xw->endElement();
$xw->endDocument();
echo $xw->outputMemory();

上の例の出力は以下となります。

<?xml version="1.0"?>
<book>example</book>


XMLWriter クラス

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

はじめに

クラス概要

class XMLWriter {
/* メソッド */
public endAttribute(): bool
public endCdata(): bool
public endComment(): bool
public endDocument(): bool
public endDtd(): bool
public endDtdAttlist(): bool
public endDtdElement(): bool
public endDtdEntity(): bool
public endElement(): bool
public endPi(): bool
public flush(bool $empty = true): string|int
public fullEndElement(): bool
public openMemory(): bool
public openUri(string $uri): bool
public outputMemory(bool $flush = true): string
public setIndent(bool $enable): bool
public setIndentString(string $indentation): bool
public startAttribute(string $name): bool
public startAttributeNs(?string $prefix, string $name, ?string $namespace): bool
public startCdata(): bool
public startComment(): bool
public startDocument(?string $version = "1.0", ?string $encoding = null, ?string $standalone = null): bool
public startDtd(string $qualifiedName, ?string $publicId = null, ?string $systemId = null): bool
public startDtdAttlist(string $name): bool
public startDtdElement(string $qualifiedName): bool
public startDtdEntity(string $name, bool $isParam): bool
public startElement(string $name): bool
public startElementNs(?string $prefix, string $name, ?string $namespace): bool
public startPi(string $target): bool
public text(string $content): bool
public writeAttribute(string $name, string $value): bool
public writeAttributeNs(
?string $prefix,
string $name,
?string $namespace,
string $value
): bool
public writeCdata(string $content): bool
public writeComment(string $content): bool
public writeDtd(
string $name,
?string $publicId = null,
?string $systemId = null,
?string $content = null
): bool
public writeDtdAttlist(string $name, string $content): bool
public writeDtdElement(string $name, string $content): bool
public writeDtdEntity(
string $name,
string $content,
bool $isParam = false,
?string $publicId = null,
?string $systemId = null,
?string $notationData = null
): bool
public writeElement(string $name, ?string $content = null): bool
public writeElementNs(
?string $prefix,
string $name,
?string $namespace,
?string $content = null
): bool
public writePi(string $target, string $content): bool
public writeRaw(string $content): bool
}

目次

  • XMLWriter::endAttribute — 属性を終了する
  • XMLWriter::endCdata — 現在の CDATA を終了する
  • XMLWriter::endComment — コメントの終了部を作成する
  • XMLWriter::endDocument — 現在のドキュメントを終了する
  • XMLWriter::endDtd — 現在の DTD を終了する
  • XMLWriter::endDtdAttlist — 現在の DTD 属性リストを終了する
  • XMLWriter::endDtdElement — 現在の DTD 要素を終了する
  • XMLWriter::endDtdEntity — 現在の DTD エンティティを終了する
  • XMLWriter::endElement — 現在の要素を終了する
  • XMLWriter::endPi — 現在の PI (処理命令) を終了する
  • XMLWriter::flush — 現在のバッファをフラッシュする
  • XMLWriter::fullEndElement — 現在の要素を終了する
  • XMLWriter::openMemory — 文字列の出力にメモリを使用する新しい xmlwriter を作成する
  • XMLWriter::openUri — ソース URI を指定して新しい xmlwriter を作成する
  • XMLWriter::outputMemory — 現在のバッファを返す
  • XMLWriter::setIndent — 字下げの on/off を切り替える
  • XMLWriter::setIndentString — 字下げに使用する文字列を設定する
  • XMLWriter::startAttribute — 属性を開始する
  • XMLWriter::startAttributeNs — 名前空間つきの属性を開始する
  • XMLWriter::startCdata — CDATA の開始タグを作成する
  • XMLWriter::startComment — コメントを開始する
  • XMLWriter::startDocument — ドキュメントタグを作成する
  • XMLWriter::startDtd — DTD の開始タグを作成する
  • XMLWriter::startDtdAttlist — DTD 属性リストを開始する
  • XMLWriter::startDtdElement — DTD 要素を開始する
  • XMLWriter::startDtdEntity — DTD エンティティを開始する
  • XMLWriter::startElement — 要素の開始タグを作成する
  • XMLWriter::startElementNs — 名前空間つき要素の開始タグを作成する
  • XMLWriter::startPi — PI (処理命令) の開始タグを作成する
  • XMLWriter::text — テキストを書き込む
  • XMLWriter::writeAttribute — 属性全体を書き込む
  • XMLWriter::writeAttributeNs — 名前空間つき属性全体を書き込む
  • XMLWriter::writeCdata — CDATA タグ全体を書き込む
  • XMLWriter::writeComment — コメントタグ全体を書き込む
  • XMLWriter::writeDtd — DTD タグ全体を書き込む
  • XMLWriter::writeDtdAttlist — DTD 属性リストタグ全体を書き込む
  • XMLWriter::writeDtdElement — DTD 要素タグ全体を書き込む
  • XMLWriter::writeDtdEntity — DTD エンティティタグ全体を書き込む
  • XMLWriter::writeElement — 要素タグ全体を書き込む
  • XMLWriter::writeElementNs — 名前空間つき要素タグ全体を書き込む
  • XMLWriter::writePi — PI (処理命令) 書き込む
  • XMLWriter::writeRaw — 生の XML テキストを書き込む


属性を終了する

  • ≪ XMLWriter
  • XMLWriter::endCdata ≫
  • PHP Manual
  • XMLWriter
  • 属性を終了する

XMLWriter::endAttribute

xmlwriter_end_attribute

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endAttribute -- xmlwriter_end_attribute — 属性を終了する

説明

オブジェクト指向型

public XMLWriter::endAttribute(): bool

手続き型

xmlwriter_end_attribute(XMLWriter $writer): bool

現在の属性を終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startAttribute() - 属性を開始する
  • XMLWriter::startAttributeNs() - 名前空間つきの属性を開始する
  • XMLWriter::writeAttribute() - 属性全体を書き込む
  • XMLWriter::writeAttributeNs() - 名前空間つき属性全体を書き込む


現在の CDATA を終了する

  • ≪ XMLWriter::endAttribute
  • XMLWriter::endComment ≫
  • PHP Manual
  • XMLWriter
  • 現在の CDATA を終了する

XMLWriter::endCdata

xmlwriter_end_cdata

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endCdata -- xmlwriter_end_cdata — 現在の CDATA を終了する

説明

オブジェクト指向型

public XMLWriter::endCdata(): bool

手続き型

xmlwriter_end_cdata(XMLWriter $writer): bool

現在の CDATA セクションを終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startCdata() - CDATA の開始タグを作成する
  • XMLWriter::writeCdata() - CDATA タグ全体を書き込む


コメントの終了部を作成する

  • ≪ XMLWriter::endCdata
  • XMLWriter::endDocument ≫
  • PHP Manual
  • XMLWriter
  • コメントの終了部を作成する

XMLWriter::endComment

xmlwriter_end_comment

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 1.0.0)

XMLWriter::endComment -- xmlwriter_end_comment — コメントの終了部を作成する

説明

オブジェクト指向型

public XMLWriter::endComment(): bool

手続き型

xmlwriter_end_comment(XMLWriter $writer): bool

現在のコメントを終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startComment() - コメントを開始する
  • XMLWriter::writeComment() - コメントタグ全体を書き込む


現在のドキュメントを終了する

  • ≪ XMLWriter::endComment
  • XMLWriter::endDtd ≫
  • PHP Manual
  • XMLWriter
  • 現在のドキュメントを終了する

XMLWriter::endDocument

xmlwriter_end_document

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endDocument -- xmlwriter_end_document — 現在のドキュメントを終了する

説明

オブジェクト指向型

public XMLWriter::endDocument(): bool

手続き型

xmlwriter_end_document(XMLWriter $writer): bool

現在のドキュメントを終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDocument() - ドキュメントタグを作成する


現在の DTD を終了する

  • ≪ XMLWriter::endDocument
  • XMLWriter::endDtdAttlist ≫
  • PHP Manual
  • XMLWriter
  • 現在の DTD を終了する

XMLWriter::endDtd

xmlwriter_end_dtd

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endDtd -- xmlwriter_end_dtd — 現在の DTD を終了する

説明

オブジェクト指向型

public XMLWriter::endDtd(): bool

手続き型

xmlwriter_end_dtd(XMLWriter $writer): bool

ドキュメントの DTD を終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtd() - DTD の開始タグを作成する
  • XMLWriter::writeDtd() - DTD タグ全体を書き込む


現在の DTD 属性リストを終了する

  • ≪ XMLWriter::endDtd
  • XMLWriter::endDtdElement ≫
  • PHP Manual
  • XMLWriter
  • 現在の DTD 属性リストを終了する

XMLWriter::endDtdAttlist

xmlwriter_end_dtd_attlist

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endDtdAttlist -- xmlwriter_end_dtd_attlist — 現在の DTD 属性リストを終了する

説明

オブジェクト指向型

public XMLWriter::endDtdAttlist(): bool

手続き型

xmlwriter_end_dtd_attlist(XMLWriter $writer): bool

現在の DTD 属性リストを終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtdAttlist() - DTD 属性リストを開始する
  • XMLWriter::writeDtdAttlist() - DTD 属性リストタグ全体を書き込む


現在の DTD 要素を終了する

  • ≪ XMLWriter::endDtdAttlist
  • XMLWriter::endDtdEntity ≫
  • PHP Manual
  • XMLWriter
  • 現在の DTD 要素を終了する

XMLWriter::endDtdElement

xmlwriter_end_dtd_element

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endDtdElement -- xmlwriter_end_dtd_element — 現在の DTD 要素を終了する

説明

オブジェクト指向型

public XMLWriter::endDtdElement(): bool

手続き型

xmlwriter_end_dtd_element(XMLWriter $writer): bool

現在の DTD 要素を終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtdElement() - DTD 要素を開始する
  • XMLWriter::writeDtdElement() - DTD 要素タグ全体を書き込む


現在の DTD エンティティを終了する

  • ≪ XMLWriter::endDtdElement
  • XMLWriter::endElement ≫
  • PHP Manual
  • XMLWriter
  • 現在の DTD エンティティを終了する

XMLWriter::endDtdEntity

xmlwriter_end_dtd_entity

(PHP 5 >= 5.2.1, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endDtdEntity -- xmlwriter_end_dtd_entity — 現在の DTD エンティティを終了する

説明

オブジェクト指向型

public XMLWriter::endDtdEntity(): bool

手続き型

xmlwriter_end_dtd_entity(XMLWriter $writer): bool

現在の DTD エンティティを終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtdEntity() - DTD エンティティを開始する
  • XMLWriter::writeDtdEntity() - DTD エンティティタグ全体を書き込む


現在の要素を終了する

  • ≪ XMLWriter::endDtdEntity
  • XMLWriter::endPi ≫
  • PHP Manual
  • XMLWriter
  • 現在の要素を終了する

XMLWriter::endElement

xmlwriter_end_element

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endElement -- xmlwriter_end_element — 現在の要素を終了する

説明

オブジェクト指向型

public XMLWriter::endElement(): bool

手続き型

xmlwriter_end_element(XMLWriter $writer): bool

現在の要素を終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startElement() - 要素の開始タグを作成する
  • XMLWriter::writeElement() - 要素タグ全体を書き込む


現在の PI (処理命令) を終了する

  • ≪ XMLWriter::endElement
  • XMLWriter::flush ≫
  • PHP Manual
  • XMLWriter
  • 現在の PI (処理命令) を終了する

XMLWriter::endPi

xmlwriter_end_pi

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::endPi -- xmlwriter_end_pi — 現在の PI (処理命令) を終了する

説明

オブジェクト指向型

public XMLWriter::endPi(): bool

手続き型

xmlwriter_end_pi(XMLWriter $writer): bool

現在の処理命令を終了します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startPi() - PI (処理命令) の開始タグを作成する
  • XMLWriter::writePi() - PI (処理命令) 書き込む


現在のバッファをフラッシュする

  • ≪ XMLWriter::endPi
  • XMLWriter::fullEndElement ≫
  • PHP Manual
  • XMLWriter
  • 現在のバッファをフラッシュする

XMLWriter::flush

xmlwriter_flush

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 1.0.0)

XMLWriter::flush -- xmlwriter_flush — 現在のバッファをフラッシュする

説明

オブジェクト指向型

public XMLWriter::flush(bool $empty = true): string|int

手続き型

xmlwriter_flush(XMLWriter $writer, bool $empty = true): string|int

現在のバッファをフラッシュします。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

empty

バッファを空にするかどうか。デフォルトは true です。

戻り値

ライターをメモリにオープンした場合は、この関数は出来上がった XML バッファを返します。 そうではなく URI を使用している場合は、この関数はバッファを書き込み、 書き込んだバイト数を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。
8.0.0 | この関数は、false を返さなくなりました。


現在の要素を終了する

  • ≪ XMLWriter::flush
  • XMLWriter::openMemory ≫
  • PHP Manual
  • XMLWriter
  • 現在の要素を終了する

XMLWriter::fullEndElement

xmlwriter_full_end_element

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL xmlwriter >= 2.0.4)

XMLWriter::fullEndElement -- xmlwriter_full_end_element — 現在の要素を終了する

説明

オブジェクト指向型

public XMLWriter::fullEndElement(): bool

手続き型

xmlwriter_full_end_element(XMLWriter $writer): bool

現在の xml 要素を終了します。要素が空であっても終了タグを書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endElement() - 現在の要素を終了する


文字列の出力にメモリを使用する新しい xmlwriter を作成する

  • ≪ XMLWriter::fullEndElement
  • XMLWriter::openUri ≫
  • PHP Manual
  • XMLWriter
  • 文字列の出力にメモリを使用する新しい xmlwriter を作成する

XMLWriter::openMemory

xmlwriter_open_memory

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::openMemory -- xmlwriter_open_memory — 文字列の出力にメモリを使用する新しい xmlwriter を作成する

説明

オブジェクト指向型

public XMLWriter::openMemory(): bool

手続き型

xmlwriter_open_memory(): XMLWriter|false

文字列の出力にメモリを使用する新しい XMLWriter を作成します。

パラメータ

戻り値

オブジェクト指向型: 成功した場合に true を、失敗した場合に false を返します。

手続き型: 成功した場合に、その後の xmlwriter 関数で使用するための新しい XMLWriter のインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は、成功した時に XMLWriter のインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。

参考

  • XMLWriter::openUri() - ソース URI を指定して新しい xmlwriter を作成する


ソース URI を指定して新しい xmlwriter を作成する

  • ≪ XMLWriter::openMemory
  • XMLWriter::outputMemory ≫
  • PHP Manual
  • XMLWriter
  • ソース URI を指定して新しい xmlwriter を作成する

XMLWriter::openUri

xmlwriter_open_uri

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::openUri -- xmlwriter_open_uri — ソース URI を指定して新しい xmlwriter を作成する

説明

オブジェクト指向型

public XMLWriter::openUri(string $uri): bool

手続き型

xmlwriter_open_uri(string $uri): XMLWriter|false

uri を指定した新しい XMLWriter を作成します。

パラメータ

uri

出力するリソースの URI。

戻り値

オブジェクト指向型: 成功した場合に true を、失敗した場合に false を返します。

手続き型: 成功した場合に、その後の xmlwriter 関数で使用するための新しい XMLWriter のインスタンスを返します。 失敗した場合に false を返します

変更履歴

バージョン | 説明
8.0.0 | この関数は、成功時に XMLWriter のインスタンスを返すようになりました。 これより前のバージョンでは、リソースが返されていました。

例

例1 XML を直接出力する

php://output ストリームラッパー を使えば、直接XMLを出力することが出来ます。

<?php
$out =new XMLWriter();
$out->openURI('php://output');
?>

注意

注意:

Windows では、この関数を使って開いたファイルは writer が解放されるまでロックされます。

参考

  • XMLWriter::openMemory() - 文字列の出力にメモリを使用する新しい xmlwriter を作成する


現在のバッファを返す

  • ≪ XMLWriter::openUri
  • XMLWriter::setIndent ≫
  • PHP Manual
  • XMLWriter
  • 現在のバッファを返す

XMLWriter::outputMemory

xmlwriter_output_memory

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::outputMemory -- xmlwriter_output_memory — 現在のバッファを返す

説明

オブジェクト指向型

public XMLWriter::outputMemory(bool $flush = true): string

手続き型

xmlwriter_output_memory(XMLWriter $writer, bool $flush = true): string

現在のバッファを返します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

flush

出力バッファをフラッシュするかどうか。デフォルトは true。

戻り値

現在のバッファを文字列で返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::flush() - 現在のバッファをフラッシュする


字下げの on/off を切り替える

  • ≪ XMLWriter::outputMemory
  • XMLWriter::setIndentString ≫
  • PHP Manual
  • XMLWriter
  • 字下げの on/off を切り替える

XMLWriter::setIndent

xmlwriter_set_indent

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::setIndent -- xmlwriter_set_indent — 字下げの on/off を切り替える

説明

オブジェクト指向型

public XMLWriter::setIndent(bool $enable): bool

手続き型

xmlwriter_set_indent(XMLWriter $writer, bool $enable): bool

字下げの on/off を切り替えます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

enable

字下げを有効にするかどうか。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 XMLWriter::setIndent() と mixed content

mixed content では字下げを有効にしてもうまく動きません。 字下げされた文字列は、インライン要素の前に挿入されるからです。

<?php
$writer = new XMLWriter();
$writer->openMemory();
$writer->setIndent(2);
$writer->startDocument();
$writer->startElement('p');
$writer->text('before');
$writer->writeElement('a', 'element');
$writer->text('after');
$writer->endElement();
$writer->endDocument();
echo $writer->outputMemory();
?>

上の例の出力は以下となります。

<?xml version="1.0"?>
<p>before <a>element</a>
after</p>

注意

注意:

xmlwriter がオープンされた時に、字下げの状態はリセットされます。

参考

  • XMLWriter::setIndentString() - 字下げに使用する文字列を設定する


字下げに使用する文字列を設定する

  • ≪ XMLWriter::setIndent
  • XMLWriter::startAttribute ≫
  • PHP Manual
  • XMLWriter
  • 字下げに使用する文字列を設定する

XMLWriter::setIndentString

xmlwriter_set_indent_string

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::setIndentString -- xmlwriter_set_indent_string — 字下げに使用する文字列を設定する

説明

オブジェクト指向型

public XMLWriter::setIndentString(string $indentation): bool

手続き型

xmlwriter_set_indent_string(XMLWriter $writer, string $indentation): bool

文字列を設定します。この文字を使用して、結果の xml の要素/属性 を字下げします。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

indentation

字下げ用の文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

注意

注意:

xmlwriter がオープンされた時に、字下げの状態はリセットされます。

参考

  • XMLWriter::setIndent() - 字下げの on/off を切り替える


属性を開始する

  • ≪ XMLWriter::setIndentString
  • XMLWriter::startAttributeNs ≫
  • PHP Manual
  • XMLWriter
  • 属性を開始する

XMLWriter::startAttribute

xmlwriter_start_attribute

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startAttribute -- xmlwriter_start_attribute — 属性を開始する

説明

オブジェクト指向型

public XMLWriter::startAttribute(string $name): bool

手続き型

xmlwriter_start_attribute(XMLWriter $writer, string $name): bool

属性を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

属性の名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 XMLWriter::startAttribute() の基本的な使い方

<?php
$writer = new XMLWriter;
$writer->openURI('php://output');
$writer->startDocument('1.0', 'UTF-8');
$writer->startElement('element');
$writer->startAttribute('attribute');
$writer->text('value');
$writer->endAttribute();
$writer->endElement();
$writer->endDocument();

上の例の出力は、 たとえば以下のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<element attribute="value"/>

参考

  • XMLWriter::startAttributeNs() - 名前空間つきの属性を開始する
  • XMLWriter::endAttribute() - 属性を終了する
  • XMLWriter::writeAttribute() - 属性全体を書き込む
  • XMLWriter::writeAttributeNs() - 名前空間つき属性全体を書き込む


名前空間つきの属性を開始する

  • ≪ XMLWriter::startAttribute
  • XMLWriter::startCdata ≫
  • PHP Manual
  • XMLWriter
  • 名前空間つきの属性を開始する

XMLWriter::startAttributeNs

xmlwriter_start_attribute_ns

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startAttributeNs -- xmlwriter_start_attribute_ns — 名前空間つきの属性を開始する

説明

オブジェクト指向型

public XMLWriter::startAttributeNs(?string $prefix, string $name, ?string $namespace): bool

手続き型

xmlwriter_start_attribute_ns(
XMLWriter $writer,
?string $prefix,
string $name,
?string $namespace
): bool

名前空間つきの属性を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

prefix

名前空間プレフィックス。

name

属性の名前。

namespace

名前空間 URI。 namespace が null の場合、名前空間の宣言は省略されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。
8.0.0 | prefix is nullable now.

参考

  • XMLWriter::startAttribute() - 属性を開始する
  • XMLWriter::endAttribute() - 属性を終了する
  • XMLWriter::writeAttribute() - 属性全体を書き込む
  • XMLWriter::writeAttributeNs() - 名前空間つき属性全体を書き込む


CDATA の開始タグを作成する

  • ≪ XMLWriter::startAttributeNs
  • XMLWriter::startComment ≫
  • PHP Manual
  • XMLWriter
  • CDATA の開始タグを作成する

XMLWriter::startCdata

xmlwriter_start_cdata

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startCdata -- xmlwriter_start_cdata — CDATA の開始タグを作成する

説明

オブジェクト指向型

public XMLWriter::startCdata(): bool

手続き型

xmlwriter_start_cdata(XMLWriter $writer): bool

CDATA を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endCdata() - 現在の CDATA を終了する
  • XMLWriter::writeCdata() - CDATA タグ全体を書き込む


コメントを開始する

  • ≪ XMLWriter::startCdata
  • XMLWriter::startDocument ≫
  • PHP Manual
  • XMLWriter
  • コメントを開始する

XMLWriter::startComment

xmlwriter_start_comment

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 1.0.0)

XMLWriter::startComment -- xmlwriter_start_comment — コメントを開始する

説明

オブジェクト指向型

public XMLWriter::startComment(): bool

手続き型

xmlwriter_start_comment(XMLWriter $writer): bool

コメントを開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endComment() - コメントの終了部を作成する
  • XMLWriter::writeComment() - コメントタグ全体を書き込む


ドキュメントタグを作成する

  • ≪ XMLWriter::startComment
  • XMLWriter::startDtd ≫
  • PHP Manual
  • XMLWriter
  • ドキュメントタグを作成する

XMLWriter::startDocument

xmlwriter_start_document

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startDocument -- xmlwriter_start_document — ドキュメントタグを作成する

説明

オブジェクト指向型

public XMLWriter::startDocument(?string $version = "1.0", ?string $encoding = null, ?string $standalone = null): bool

手続き型

xmlwriter_start_document(
XMLWriter $writer,
?string $version = "1.0",
?string $encoding = null,
?string $standalone = null
): bool

ドキュメントを開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

version

XML 宣言で使用するドキュメントのバージョン番号。

encoding

XML 宣言で使用するドキュメントのエンコーディング。

standalone

yes あるいは no。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endDocument() - 現在のドキュメントを終了する


DTD の開始タグを作成する

  • ≪ XMLWriter::startDocument
  • XMLWriter::startDtdAttlist ≫
  • PHP Manual
  • XMLWriter
  • DTD の開始タグを作成する

XMLWriter::startDtd

xmlwriter_start_dtd

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startDtd -- xmlwriter_start_dtd — DTD の開始タグを作成する

説明

オブジェクト指向型

public XMLWriter::startDtd(string $qualifiedName, ?string $publicId = null, ?string $systemId = null): bool

手続き型

xmlwriter_start_dtd(
XMLWriter $writer,
string $qualifiedName,
?string $publicId = null,
?string $systemId = null
): bool

DTD を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

qualifiedName

作成するドキュメント型の修飾名。

publicId

外部サブセットの公開識別子。

systemId

外部サブセットのシステム識別子。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endDtd() - 現在の DTD を終了する
  • XMLWriter::writeDtd() - DTD タグ全体を書き込む


DTD 属性リストを開始する

  • ≪ XMLWriter::startDtd
  • XMLWriter::startDtdElement ≫
  • PHP Manual
  • XMLWriter
  • DTD 属性リストを開始する

XMLWriter::startDtdAttlist

xmlwriter_start_dtd_attlist

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startDtdAttlist -- xmlwriter_start_dtd_attlist — DTD 属性リストを開始する

説明

オブジェクト指向型

public XMLWriter::startDtdAttlist(string $name): bool

手続き型

xmlwriter_start_dtd_attlist(XMLWriter $writer, string $name): bool

DTD 属性リストを開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

属性リストの名前。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endDtdAttlist() - 現在の DTD 属性リストを終了する
  • XMLWriter::writeDtdAttlist() - DTD 属性リストタグ全体を書き込む


DTD 要素を開始する

  • ≪ XMLWriter::startDtdAttlist
  • XMLWriter::startDtdEntity ≫
  • PHP Manual
  • XMLWriter
  • DTD 要素を開始する

XMLWriter::startDtdElement

xmlwriter_start_dtd_element

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startDtdElement -- xmlwriter_start_dtd_element — DTD 要素を開始する

説明

オブジェクト指向型

public XMLWriter::startDtdElement(string $qualifiedName): bool

手続き型

xmlwriter_start_dtd_element(XMLWriter $writer, string $qualifiedName): bool

DTD 要素を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

qualifiedName

作成するドキュメント型の修飾名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endDtdElement() - 現在の DTD 要素を終了する
  • XMLWriter::writeDtdElement() - DTD 要素タグ全体を書き込む


DTD エンティティを開始する

  • ≪ XMLWriter::startDtdElement
  • XMLWriter::startElement ≫
  • PHP Manual
  • XMLWriter
  • DTD エンティティを開始する

XMLWriter::startDtdEntity

xmlwriter_start_dtd_entity

(PHP 5 >= 5.2.1, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startDtdEntity -- xmlwriter_start_dtd_entity — DTD エンティティを開始する

説明

オブジェクト指向型

public XMLWriter::startDtdEntity(string $name, bool $isParam): bool

手続き型

xmlwriter_start_dtd_entity(XMLWriter $writer, string $name, bool $isParam): bool

DTD エンティティを開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

エンティティの名前。

isParam

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endDtdEntity() - 現在の DTD エンティティを終了する
  • XMLWriter::writeDtdEntity() - DTD エンティティタグ全体を書き込む


要素の開始タグを作成する

  • ≪ XMLWriter::startDtdEntity
  • XMLWriter::startElementNs ≫
  • PHP Manual
  • XMLWriter
  • 要素の開始タグを作成する

XMLWriter::startElement

xmlwriter_start_element

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startElement -- xmlwriter_start_element — 要素の開始タグを作成する

説明

オブジェクト指向型

public XMLWriter::startElement(string $name): bool

手続き型

xmlwriter_start_element(XMLWriter $writer, string $name): bool

要素を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

要素名。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endElement() - 現在の要素を終了する
  • XMLWriter::writeElement() - 要素タグ全体を書き込む


名前空間つき要素の開始タグを作成する

  • ≪ XMLWriter::startElement
  • XMLWriter::startPi ≫
  • PHP Manual
  • XMLWriter
  • 名前空間つき要素の開始タグを作成する

XMLWriter::startElementNs

xmlwriter_start_element_ns

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startElementNs -- xmlwriter_start_element_ns — 名前空間つき要素の開始タグを作成する

説明

オブジェクト指向型

public XMLWriter::startElementNs(?string $prefix, string $name, ?string $namespace): bool

手続き型

xmlwriter_start_element_ns(
XMLWriter $writer,
?string $prefix,
string $name,
?string $namespace
): bool

名前空間つき要素を開始します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

prefix

名前空間プレフィックス。 prefix が null の場合、名前空間は省略されます。

name

要素名。

namespace

名前空間 URI。 namespace が null の場合、名前空間の宣言は省略されます。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endElement() - 現在の要素を終了する
  • XMLWriter::writeElementNs() - 名前空間つき要素タグ全体を書き込む


PI (処理命令) の開始タグを作成する

  • ≪ XMLWriter::startElementNs
  • XMLWriter::text ≫
  • PHP Manual
  • XMLWriter
  • PI (処理命令) の開始タグを作成する

XMLWriter::startPi

xmlwriter_start_pi

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::startPi -- xmlwriter_start_pi — PI (処理命令) の開始タグを作成する

説明

オブジェクト指向型

public XMLWriter::startPi(string $target): bool

手続き型

xmlwriter_start_pi(XMLWriter $writer, string $target): bool

処理命令の開始タグを作成します。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

target

処理命令の対象。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::endPi() - 現在の PI (処理命令) を終了する
  • XMLWriter::writePi() - PI (処理命令) 書き込む


テキストを書き込む

  • ≪ XMLWriter::startPi
  • XMLWriter::writeAttribute ≫
  • PHP Manual
  • XMLWriter
  • テキストを書き込む

XMLWriter::text

xmlwriter_text

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::text -- xmlwriter_text — テキストを書き込む

説明

オブジェクト指向型

public XMLWriter::text(string $content): bool

手続き型

xmlwriter_text(XMLWriter $writer, string $content): bool

テキストを書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

content

テキストの内容。 <, >, &, " は、実体参照として書き込みます。 (つまり、 &lt;, &gt;, &amp;, &quot;, をそれぞれ書き込みます)。 それ以外の文字は、' を含めてそのまま書き込みます。 XML で特別な文字や、実体参照をそのまま書き込むには、 xmlwriter_write_raw() を使わなければなりません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。


属性全体を書き込む

  • ≪ XMLWriter::text
  • XMLWriter::writeAttributeNs ≫
  • PHP Manual
  • XMLWriter
  • 属性全体を書き込む

XMLWriter::writeAttribute

xmlwriter_write_attribute

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeAttribute -- xmlwriter_write_attribute — 属性全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeAttribute(string $name, string $value): bool

手続き型

xmlwriter_write_attribute(XMLWriter $writer, string $name, string $value): bool

属性全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

属性の名前。

value

属性の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 子要素と属性を混在させる

子要素と属性が混在した場合、最初の子要素より後に属性を書き込もうとしても失敗し、false が返ります。

<?php
$xml = new XMLWriter();
$xml->openMemory();

$xml->startElement('element');
$xml->writeAttribute('attr1', '0');
$xml->writeElement('subelem', '0');
var_dump($xml->writeAttribute('attr2', '0'));
$xml->endElement();

echo $xml->flush();
?>

上の例の出力は以下となります。

bool(false)
<element attr1="0"><subelem>0</subelem></element>

参考

  • XMLWriter::writeAttributeNs() - 名前空間つき属性全体を書き込む
  • XMLWriter::startAttribute() - 属性を開始する
  • XMLWriter::startAttributeNs() - 名前空間つきの属性を開始する
  • XMLWriter::endAttribute() - 属性を終了する


名前空間つき属性全体を書き込む

  • ≪ XMLWriter::writeAttribute
  • XMLWriter::writeCdata ≫
  • PHP Manual
  • XMLWriter
  • 名前空間つき属性全体を書き込む

XMLWriter::writeAttributeNs

xmlwriter_write_attribute_ns

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeAttributeNs -- xmlwriter_write_attribute_ns — 名前空間つき属性全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeAttributeNs(
?string $prefix,
string $name,
?string $namespace,
string $value
): bool

手続き型

xmlwriter_write_attribute_ns(
XMLWriter $writer,
?string $prefix,
string $name,
?string $namespace,
string $value
): bool

名前空間つき属性全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

prefix

名前空間プレフィックス。 prefix が null の場合、名前空間は省略されます。

name

属性名。

namespace

名前空間 URI。 namespace が null の場合、名前空間の宣言は省略されます。

value

属性の値。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::writeAttribute() - 属性全体を書き込む
  • XMLWriter::startAttribute() - 属性を開始する
  • XMLWriter::startAttributeNs() - 名前空間つきの属性を開始する
  • XMLWriter::endAttribute() - 属性を終了する


CDATA タグ全体を書き込む

  • ≪ XMLWriter::writeAttributeNs
  • XMLWriter::writeComment ≫
  • PHP Manual
  • XMLWriter
  • CDATA タグ全体を書き込む

XMLWriter::writeCdata

xmlwriter_write_cdata

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeCdata -- xmlwriter_write_cdata — CDATA タグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeCdata(string $content): bool

手続き型

xmlwriter_write_cdata(XMLWriter $writer, string $content): bool

CDATA 全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

content

CDATA の内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

例

例1 xmlwriter_write_cdata() の基本的な使い方

<?php
// set up the document
$xml = new XmlWriter();
$xml->openMemory();
$xml->setIndent(true);
$xml->startDocument('1.0', 'UTF-8');
$xml->startElement('mydoc');
$xml->startElement('myele');

// CData output
$xml->startElement('mycdataelement');
$xml->writeCData("text for inclusion as CData");
$xml->endElement();

// end the document and output
$xml->endElement();
$xml->endElement();
echo $xml->outputMemory(true);
?>

上の例の出力は以下となります。

<mydoc>
 <myele>
  <mycdataelement><![CDATA[text for inclusion as CData]?]></mycdataelement>
 </myele>
</mydoc>

参考

  • XMLWriter::startCdata() - CDATA の開始タグを作成する
  • XMLWriter::endCdata() - 現在の CDATA を終了する


コメントタグ全体を書き込む

  • ≪ XMLWriter::writeCdata
  • XMLWriter::writeDtd ≫
  • PHP Manual
  • XMLWriter
  • コメントタグ全体を書き込む

XMLWriter::writeComment

xmlwriter_write_comment

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeComment -- xmlwriter_write_comment — コメントタグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeComment(string $content): bool

手続き型

xmlwriter_write_comment(XMLWriter $writer, string $content): bool

コメント全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

content

コメントの内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startComment() - コメントを開始する
  • XMLWriter::endComment() - コメントの終了部を作成する


DTD タグ全体を書き込む

  • ≪ XMLWriter::writeComment
  • XMLWriter::writeDtdAttlist ≫
  • PHP Manual
  • XMLWriter
  • DTD タグ全体を書き込む

XMLWriter::writeDtd

xmlwriter_write_dtd

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeDtd -- xmlwriter_write_dtd — DTD タグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeDtd(
string $name,
?string $publicId = null,
?string $systemId = null,
?string $content = null
): bool

手続き型

xmlwriter_write_dtd(
XMLWriter $writer,
string $name,
?string $publicId = null,
?string $systemId = null,
?string $content = null
): bool

DTD 全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

DTD 名。

publicId

外部サブセットの公開識別子。

systemId

外部サブセットのシステム識別子。

content

DTD の内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtd() - DTD の開始タグを作成する
  • XMLWriter::endDtd() - 現在の DTD を終了する


DTD 属性リストタグ全体を書き込む

  • ≪ XMLWriter::writeDtd
  • XMLWriter::writeDtdElement ≫
  • PHP Manual
  • XMLWriter
  • DTD 属性リストタグ全体を書き込む

XMLWriter::writeDtdAttlist

xmlwriter_write_dtd_attlist

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeDtdAttlist -- xmlwriter_write_dtd_attlist — DTD 属性リストタグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeDtdAttlist(string $name, string $content): bool

手続き型

xmlwriter_write_dtd_attlist(XMLWriter $writer, string $name, string $content): bool

DTD 属性リストを書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

DTD 属性リストの名前。

content

DTD 属性リストの内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtdAttlist() - DTD 属性リストを開始する
  • XMLWriter::endDtdAttlist() - 現在の DTD 属性リストを終了する


DTD 要素タグ全体を書き込む

  • ≪ XMLWriter::writeDtdAttlist
  • XMLWriter::writeDtdEntity ≫
  • PHP Manual
  • XMLWriter
  • DTD 要素タグ全体を書き込む

XMLWriter::writeDtdElement

xmlwriter_write_dtd_element

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeDtdElement -- xmlwriter_write_dtd_element — DTD 要素タグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeDtdElement(string $name, string $content): bool

手続き型

xmlwriter_write_dtd_element(XMLWriter $writer, string $name, string $content): bool

DTD 要素全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

DTD 要素の名前。

content

要素の内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startDtdElement() - DTD 要素を開始する
  • XMLWriter::endDtdElement() - 現在の DTD 要素を終了する


DTD エンティティタグ全体を書き込む

  • ≪ XMLWriter::writeDtdElement
  • XMLWriter::writeElement ≫
  • PHP Manual
  • XMLWriter
  • DTD エンティティタグ全体を書き込む

XMLWriter::writeDtdEntity

xmlwriter_write_dtd_entity

(PHP 5 >= 5.2.1, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeDtdEntity -- xmlwriter_write_dtd_entity — DTD エンティティタグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeDtdEntity(
string $name,
string $content,
bool $isParam = false,
?string $publicId = null,
?string $systemId = null,
?string $notationData = null
): bool

手続き型

xmlwriter_write_dtd_entity(
XMLWriter $writer,
string $name,
string $content,
bool $isParam = false,
?string $publicId = null,
?string $systemId = null,
?string $notationData = null
): bool

DTD エンティティ全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

エンティティの名前。

content

エンティティの内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。
8.0.0 | publicId, systemId, notationData は、nullable になりました。

参考

  • XMLWriter::startDtdEntity() - DTD エンティティを開始する
  • XMLWriter::endDtdEntity() - 現在の DTD エンティティを終了する


要素タグ全体を書き込む

  • ≪ XMLWriter::writeDtdEntity
  • XMLWriter::writeElementNs ≫
  • PHP Manual
  • XMLWriter
  • 要素タグ全体を書き込む

XMLWriter::writeElement

xmlwriter_write_element

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeElement -- xmlwriter_write_element — 要素タグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeElement(string $name, ?string $content = null): bool

手続き型

xmlwriter_write_element(XMLWriter $writer, string $name, ?string $content = null): bool

要素タグ全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

name

要素名。

content

要素の内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startElement() - 要素の開始タグを作成する
  • XMLWriter::endElement() - 現在の要素を終了する
  • XMLWriter::writeElementNs() - 名前空間つき要素タグ全体を書き込む


名前空間つき要素タグ全体を書き込む

  • ≪ XMLWriter::writeElement
  • XMLWriter::writePi ≫
  • PHP Manual
  • XMLWriter
  • 名前空間つき要素タグ全体を書き込む

XMLWriter::writeElementNs

xmlwriter_write_element_ns

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writeElementNs -- xmlwriter_write_element_ns — 名前空間つき要素タグ全体を書き込む

説明

オブジェクト指向型

public XMLWriter::writeElementNs(
?string $prefix,
string $name,
?string $namespace,
?string $content = null
): bool

手続き型

xmlwriter_write_element_ns(
XMLWriter $writer,
?string $prefix,
string $name,
?string $namespace,
?string $content = null
): bool

名前空間つき要素タグ全体を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

prefix

名前空間プレフィックス。 prefix が null の場合、名前空間は省略されます。

name

要素名。

namespace

名前空間 URI。 namespace が null の場合、名前空間の宣言は省略されます。

content

要素の内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startElementNs() - 名前空間つき要素の開始タグを作成する
  • XMLWriter::endElement() - 現在の要素を終了する
  • XMLWriter::writeElement() - 要素タグ全体を書き込む


PI (処理命令) 書き込む

  • ≪ XMLWriter::writeElementNs
  • XMLWriter::writeRaw ≫
  • PHP Manual
  • XMLWriter
  • PI (処理命令) 書き込む

XMLWriter::writePi

xmlwriter_write_pi

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL xmlwriter >= 0.1.0)

XMLWriter::writePi -- xmlwriter_write_pi — PI (処理命令) 書き込む

説明

オブジェクト指向型

public XMLWriter::writePi(string $target, string $content): bool

手続き型

xmlwriter_write_pi(XMLWriter $writer, string $target, string $content): bool

処理命令を書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

target

処理命令の対象。

content

処理命令の内容。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::startPi() - PI (処理命令) の開始タグを作成する
  • XMLWriter::endPi() - 現在の PI (処理命令) を終了する


生の XML テキストを書き込む

  • ≪ XMLWriter::writePi
  • XSL ≫
  • PHP Manual
  • XMLWriter
  • 生の XML テキストを書き込む

XMLWriter::writeRaw

xmlwriter_write_raw

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL xmlwriter >= 2.0.4)

XMLWriter::writeRaw -- xmlwriter_write_raw — 生の XML テキストを書き込む

説明

オブジェクト指向型

public XMLWriter::writeRaw(string $content): bool

手続き型

xmlwriter_write_raw(XMLWriter $writer, string $content): bool

生の xml テキストを書き込みます。

パラメータ

writer

手続き型のコールでのみ使用します。 変更される XMLWriter のインスタンスです。 このインスタンスは、xmlwriter_open_uri() あるいは xmlwriter_open_memory() を呼び出すことで取得したものです。

content

書き込むテキスト文字列。

戻り値

成功した場合に true を、失敗した場合に false を返します。

変更履歴

バージョン | 説明
8.0.0 | 引数 writer は、XMLWriter のインスタンスを期待するようになりました。 これより前のバージョンでは、リソースが期待されていました。

参考

  • XMLWriter::text() - テキストを書き込む


XSL

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • 定義済み定数
  • 例
    • collection.xml および collection.xsl ファイルの例
    • libxml のエラー処理関数によるエラー処理
  • XSLTProcessor — XSLTProcessor クラス
    • XSLTProcessor::__construct — 新しい XSLTProcessor オブジェクトを作成する
    • XSLTProcessor::getParameter — パラメータの値を取得する
    • XSLTProcessor::getSecurityPrefs — セキュリティ設定を取得する
    • XSLTProcessor::hasExsltSupport — PHP が EXSLT をサポートしているかどうかを判定する
    • XSLTProcessor::importStylesheet — スタイルシートを取り込む
    • XSLTProcessor::registerPHPFunctions — PHP 関数を XSLT 関数として利用できるようにする
    • XSLTProcessor::removeParameter — パラメータを削除する
    • XSLTProcessor::setParameter — パラメータの値を設定する
    • XSLTProcessor::setProfiling — プロファイル情報の出力ファイルを設定する
    • XSLTProcessor::setSecurityPrefs — セキュリティ設定を指定する
    • XSLTProcessor::transformToDoc — ドキュメント に変換する
    • XSLTProcessor::transformToUri — URI に変換する
    • XSLTProcessor::transformToXml — XML に変換する


はじめに

XSL 拡張モジュールは、XSL の標準規格を実装したもので、 » libxslt ライブラリ を用いて » XSLT 変換 を行います。


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • XSL
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

この拡張モジュールを使うには libxml 拡張モジュールが必要です。つまり、 PHP 7.4 以降では --with-libxml、それより前のバージョンでは --enable-libxml も指定しなければならないということです。 しかし、libxml はデフォルトで有効になっているのでこのオプションは暗黙のうちに指定されています。

この拡張モジュールは » http://xmlsoft.org/XSLT/ にある libxslt を使用します。 libxslt バージョン 1.1.0 以降が必要です。


インストール手順

PHP には、デフォルトでXSL拡張モジュールが含まれており、 configureに引数--with-xsl[=DIR] を追加することにより有効にすることができます (DIR は libxslt をインストールしたディレクトリです)。


定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XSL_CLONE_AUTO (int)
XSL_CLONE_NEVER (int)
XSL_CLONE_ALWAYS (int)
LIBXSLT_VERSION (int)
libxslt のバージョンを 10117 のように表します。
LIBXSLT_DOTTED_VERSION (string)
libxslt のバージョンを 1.1.17 のように表します。
LIBEXSLT_VERSION (int)
libexslt のバージョンを 813 のように表します。
LIBEXSLT_DOTTED_VERSION (string)
libexslt のバージョンを 1.1.17 のように表します。
XSL_SECPREF_NONE (int)
セキュリティに関する制限をすべて無効化します。
XSL_SECPREF_READ_FILE (int)
ファイルの読み込みを拒否します。
XSL_SECPREF_WRITE_FILE (int)
ファイルへの書き込みを拒否します。
XSL_SECPREF_CREATE_DIRECTORY (int)
ディレクトリの作成を拒否します。
XSL_SECPREF_READ_NETWORK (int)
ネットワークファイルの読み込みを拒否します。
XSL_SECPREF_WRITE_NETWORK (int)
ネットワークファイルへの書き込みを拒否します。
XSL_SECPREF_DEFAULT (int)
すべての書き込みアクセスを拒否します。つまり、 XSL_SECPREF_WRITE_NETWORK | XSL_SECPREF_CREATE_DIRECTORY | XSL_SECPREF_WRITE_FILE と同等です。


  • ≪ 定義済み定数
  • collection.xml および collection.xsl ファイルの例 ≫
  • PHP Manual
  • XSL
  • 例

例

目次

  • collection.xml および collection.xsl ファイルの例
  • libxml のエラー処理関数によるエラー処理


collection.xml および collection.xsl ファイルの例

このリファレンスにある多くの例は、XML ファイルと XSL ファイルの両方が必要です。 例では、以下の内容を含む collection.xml と collection.xsl を使用します。

例1 collection.xml

<collection>
 <cd>
  <title>Fight for your mind</title>
  <artist>Ben Harper</artist>
  <year>1995</year>
 </cd>
 <cd>
  <title>Electric Ladyland</title>
  <artist>Jimi Hendrix</artist>
  <year>1997</year>
 </cd>
</collection>

例2 collection.xsl

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 <xsl:param name="owner" select="'Nicolas Eliaszewicz'"/>
 <xsl:output method="html" encoding="iso-8859-1" indent="no"/>
 <xsl:template match="collection">
  Hey! Welcome to <xsl:value-of select="$owner"/>'s sweet CD collection!
  <xsl:apply-templates/>
 </xsl:template>
 <xsl:template match="cd">
  <h1><xsl:value-of select="title"/></h1>
  <h2>by <xsl:value-of select="artist"/> - <xsl:value-of select="year"/></h2>
  <hr />
 </xsl:template>
</xsl:stylesheet>


libxml のエラー処理関数によるエラー処理

libxml にはエラー処理用の関数が用意されており、これらを使うと、 XSLT の処理中のエラーを捕らえて対応できます。

例1 fruits.xml

妥当な XML ファイルです。

<fruits>
 <fruit>Apple</fruit>
 <fruit>Banana</fruit>
 <fruit>Cherry</fruit>
</fruits>

例2 fruits.xsl

無効な select 式が含まれています。

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 <xsl:output method="html" encoding="utf-8" indent="no"/>
 <xsl:template match="fruits">
  <ul>
   <xsl:apply-templates/>
  </ul>
 </xsl:template>
 <xsl:template match="fruit">
  <li><xsl:value-of select="THIS IS A DELIBERATE ERROR!"/></li>
 </xsl:template>
</xsl:stylesheet>

例3 エラーの捕捉と表示

以下の例は、エラーを含むスタイルシートで XSLTProcessor::importStyleSheet() を呼んだ際に発生する libxml のエラーを捕らえて表示するものです。

<?php

$xmldoc = new DOMDocument();
$xsldoc = new DOMDocument();
$xsl = new XSLTProcessor();

$xmldoc->loadXML('fruits.xml');
$xsldoc->loadXML('fruits.xsl');

libxml_use_internal_errors(true);
$result = $xsl->importStyleSheet($xsldoc);
if (!$result) {
foreach (libxml_get_errors() as $error) {
echo "Libxml error: {$error->message}\n";
}
}
libxml_use_internal_errors(false);

if ($result) {
echo $xsl->transformToXML($xmldoc);
}

?>

上の例の出力は、 たとえば以下のようになります。

Libxml error: Invalid expression

Libxml error: compilation error: file fruits.xsl line 9 element value-of
Libxml error: xsl:value-of : could not compile select expression 'THIS IS A DELIBERATE ERROR!'


XSLTProcessor クラス

(PHP 5, PHP 7, PHP 8)

はじめに

クラス概要

class XSLTProcessor {
/* メソッド */
public getParameter(string $namespace, string $name): string|false
public getSecurityPrefs(): int
public hasExsltSupport(): bool
public importStylesheet(object $stylesheet): bool
public registerPHPFunctions(array|string|null $functions = null): void
public removeParameter(string $namespace, string $name): bool
public setParameter(string $namespace, string $name, string $value): bool
public setParameter(string $namespace, array $options): bool
public setProfiling(?string $filename): true
public setSecurityPrefs(int $preferences): int
public transformToDoc(object $document, ?string $returnClass = null): DOMDocument|false
public transformToUri(object $document, string $uri): int
public transformToXml(object $document): string|null|false
}

目次

  • XSLTProcessor::__construct — 新しい XSLTProcessor オブジェクトを作成する
  • XSLTProcessor::getParameter — パラメータの値を取得する
  • XSLTProcessor::getSecurityPrefs — セキュリティ設定を取得する
  • XSLTProcessor::hasExsltSupport — PHP が EXSLT をサポートしているかどうかを判定する
  • XSLTProcessor::importStylesheet — スタイルシートを取り込む
  • XSLTProcessor::registerPHPFunctions — PHP 関数を XSLT 関数として利用できるようにする
  • XSLTProcessor::removeParameter — パラメータを削除する
  • XSLTProcessor::setParameter — パラメータの値を設定する
  • XSLTProcessor::setProfiling — プロファイル情報の出力ファイルを設定する
  • XSLTProcessor::setSecurityPrefs — セキュリティ設定を指定する
  • XSLTProcessor::transformToDoc — ドキュメント に変換する
  • XSLTProcessor::transformToUri — URI に変換する
  • XSLTProcessor::transformToXml — XML に変換する


新しい XSLTProcessor オブジェクトを作成する

  • ≪ XSLTProcessor
  • XSLTProcessor::getParameter ≫
  • PHP Manual
  • XSLTProcessor
  • 新しい XSLTProcessor オブジェクトを作成する

XSLTProcessor::__construct

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::__construct — 新しい XSLTProcessor オブジェクトを作成する

説明

XSLTProcessor::__construct()

新しい XSLTProcessor オブジェクトを作成します。

パラメータ

この関数にはパラメータはありません。

例

例1 XSLTProcessor の作成

<?php

$xsldoc = new DOMDocument();
$xsldoc->load($xsl_filename);

$xmldoc = new DOMDocument();
$xmldoc->load($xml_filename);

$xsl = new XSLTProcessor();
$xsl->importStyleSheet($xsldoc);
echo $xsl->transformToXML($xmldoc);

?>


パラメータの値を取得する

  • ≪ XSLTProcessor::__construct
  • XSLTProcessor::getSecurityPrefs ≫
  • PHP Manual
  • XSLTProcessor
  • パラメータの値を取得する

XSLTProcessor::getParameter

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::getParameter — パラメータの値を取得する

説明

public XSLTProcessor::getParameter(string $namespace, string $name): string|false

パラメータがあらかじめ XSLTProcessor::setParameter() で設定されている場合、 それを取得します。

パラメータ

namespace

XSLT パラメータの名前空間 URI を指定します。

name

XSLT パラメータのローカル名を指定します。

戻り値

パラメータの値 (文字列)、あるいは設定されていない場合は false を返します。

参考

  • XSLTProcessor::setParameter() - パラメータの値を設定する
  • XSLTProcessor::removeParameter() - パラメータを削除する


セキュリティ設定を取得する

  • ≪ XSLTProcessor::getParameter
  • XSLTProcessor::hasExsltSupport ≫
  • PHP Manual
  • XSLTProcessor
  • セキュリティ設定を取得する

XSLTProcessor::getSecurityPrefs

(PHP >= 5.4.0, PHP 7, PHP 8)

XSLTProcessor::getSecurityPrefs — セキュリティ設定を取得する

説明

public XSLTProcessor::getSecurityPrefs(): int

セキュリティ設定を取得します。

パラメータ

この関数にはパラメータはありません。

戻り値

XSL_SECPREF_READ_FILE、 XSL_SECPREF_WRITE_FILE、 XSL_SECPREF_CREATE_DIRECTORY、 XSL_SECPREF_READ_NETWORK、 XSL_SECPREF_WRITE_NETWORK を含むビットマスクを返します。


PHP が EXSLT をサポートしているかどうかを判定する

  • ≪ XSLTProcessor::getSecurityPrefs
  • XSLTProcessor::importStylesheet ≫
  • PHP Manual
  • XSLTProcessor
  • PHP が EXSLT をサポートしているかどうかを判定する

XSLTProcessor::hasExsltSupport

(PHP 5 >= 5.0.4, PHP 7, PHP 8)

XSLTProcessor::hasExsltSupport — PHP が EXSLT をサポートしているかどうかを判定する

説明

public XSLTProcessor::hasExsltSupport(): bool

このメソッドは PHP が » EXSLT library と共にビルドされたかどうかを判定します。

パラメータ

この関数にはパラメータはありません。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 EXSLT サポートの判定

<?php

$proc = new XSLTProcessor;
if (!$proc->hasExsltSupport()) {
die('EXSLT support not available');
}

// EXSLT 処理がここに ..

?>


スタイルシートを取り込む

  • ≪ XSLTProcessor::hasExsltSupport
  • XSLTProcessor::registerPHPFunctions ≫
  • PHP Manual
  • XSLTProcessor
  • スタイルシートを取り込む

XSLTProcessor::importStylesheet

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::importStylesheet — スタイルシートを取り込む

説明

public XSLTProcessor::importStylesheet(object $stylesheet): bool

このメソッドは XSLTProcessor に変換のためのスタイルシートを取り込みます。

パラメータ

stylesheet

取り込まれるスタイルシートを DOMDocument オブジェクトあるいは SimpleXMLElement オブジェクトとして指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。


PHP 関数を XSLT 関数として利用できるようにする

  • ≪ XSLTProcessor::importStylesheet
  • XSLTProcessor::removeParameter ≫
  • PHP Manual
  • XSLTProcessor
  • PHP 関数を XSLT 関数として利用できるようにする

XSLTProcessor::registerPHPFunctions

(PHP 5 >= 5.0.4, PHP 7, PHP 8)

XSLTProcessor::registerPHPFunctions — PHP 関数を XSLT 関数として利用できるようにする

説明

public XSLTProcessor::registerPHPFunctions(array|string|null $functions = null): void

このメソッドは、PHP 関数を XSL スタイルシートでの XSLT 関数として利用できるようにします。

パラメータ

functions

このパラメータは、XSLT からコールされる信頼できる関数のみを許可します。

このパラメータには文字列 (関数名) あるいは関数の配列のいずれかを指定します。

戻り値

値を返しません。

例

例1 スタイルシートからの単純な PHP 関数コール

<?php
$xml = <<<EOB
<allusers>
<user>
<uid>bob</uid>
</user>
<user>
<uid>joe</uid>
</user>
</allusers>
EOB;
$xsl = <<<EOB
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:php="http://php.net/xsl">
<xsl:output method="html" encoding="utf-8" indent="yes"/>
<xsl:template match="allusers">
<html><body>
<h2>Users</h2>
<table>
<xsl:for-each select="user">
<tr><td>
<xsl:value-of
select="php:function('ucfirst',string(uid))"/>
</td></tr>
</xsl:for-each>
</table>
</body></html>
</xsl:template>
</xsl:stylesheet>
EOB;
$xmldoc = new DOMDocument();
$xmldoc->loadXML($xml);
$xsldoc = new DOMDocument();
$xsldoc->loadXML($xsl);

$proc = new XSLTProcessor();
$proc->registerPHPFunctions();
$proc->importStyleSheet($xsldoc);
echo $proc->transformToXML($xmldoc);
?>


パラメータを削除する

  • ≪ XSLTProcessor::registerPHPFunctions
  • XSLTProcessor::setParameter ≫
  • PHP Manual
  • XSLTProcessor
  • パラメータを削除する

XSLTProcessor::removeParameter

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::removeParameter — パラメータを削除する

説明

public XSLTProcessor::removeParameter(string $namespace, string $name): bool

もしパラメータが設定されていれば削除します。これにより、 プロセッサはスタイルシートで指定されるようなパラメータに デフォルト値を使用します。

パラメータ

namespace

XSLT パラメータの名前空間 URI を指定します。

name

XSLT パラメータのローカル名を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

参考

  • XSLTProcessor::setParameter() - パラメータの値を設定する
  • XSLTProcessor::getParameter() - パラメータの値を取得する


パラメータの値を設定する

  • ≪ XSLTProcessor::removeParameter
  • XSLTProcessor::setProfiling ≫
  • PHP Manual
  • XSLTProcessor
  • パラメータの値を設定する

XSLTProcessor::setParameter

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::setParameter — パラメータの値を設定する

説明

public XSLTProcessor::setParameter(string $namespace, string $name, string $value): bool
public XSLTProcessor::setParameter(string $namespace, array $options): bool

XSLTProcessor を使った変換のための 1 つあるいは多くのパラメータの値を設定します。 もしパラメータがスタイルシートに存在しない場合、無視されます。

パラメータ

namespace

XSLT パラメータの名前空間 URI を指定します。

name

XSLT パラメータのローカル名を指定します。

value

XSLT パラメータの新しい値を指定します。

options

名前 => 値 の組の配列を指定します。

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 変換前に所有者を変更する

<?php

$collections = array(
'Marc Rutkowski' => 'marc',
'Olivier Parmentier' => 'olivier'
);

$xsl = new DOMDocument;
$xsl->load('collection.xsl');

// 変換の設定を行う
$proc = new XSLTProcessor;
$proc->importStyleSheet($xsl); // attach the xsl rules

foreach ($collections as $name => $file) {
// XML ソースをロードする
$xml = new DOMDocument;
$xml->load('collection_' . $file . '.xml');

$proc->setParameter('', 'owner', $name);
$proc->transformToURI($xml, 'file:///tmp/' . $file . '.html');
}

?>

参考

  • XSLTProcessor::getParameter() - パラメータの値を取得する
  • XSLTProcessor::removeParameter() - パラメータを削除する


プロファイル情報の出力ファイルを設定する

  • ≪ XSLTProcessor::setParameter
  • XSLTProcessor::setSecurityPrefs ≫
  • PHP Manual
  • XSLTProcessor
  • プロファイル情報の出力ファイルを設定する

XSLTProcessor::setProfiling

(PHP >= 5.3.0, PHP 7, PHP 8)

XSLTProcessor::setProfiling — プロファイル情報の出力ファイルを設定する

説明

public XSLTProcessor::setProfiling(?string $filename): true

スタイルシート処理時のプロファイル情報を出力するファイルを設定します。

パラメータ

filename

プロファイル情報を出力するファイルへのパス。

戻り値

常に true を返します。

例

例1 プロファイル出力の例

<?php
// XML ソースを読み込みます
$xml = new DOMDocument;
$xml->load('collection.xml');

$xsl = new DOMDocument;
$xsl->load('collection.xsl');

// 変換器を設定します
$proc = new XSLTProcessor;
$proc->setProfiling('profiling.txt');
$proc->importStyleSheet($xsl); // xsl ルールをアタッチします

echo trim($proc->transformToDoc($xml)->firstChild->wholeText);
?>

上のコードは、ファイルの処理時に次のような情報を出力します。

number               match                name      mode  Calls Tot 100us Avg

    0                   cd                                    2      3      1
    1           collection                                    1      1      1

                         Total                                3      4


セキュリティ設定を指定する

  • ≪ XSLTProcessor::setProfiling
  • XSLTProcessor::transformToDoc ≫
  • PHP Manual
  • XSLTProcessor
  • セキュリティ設定を指定する

XSLTProcessor::setSecurityPrefs

(PHP >= 5.4.0, PHP 7, PHP 8)

XSLTProcessor::setSecurityPrefs — セキュリティ設定を指定する

説明

public XSLTProcessor::setSecurityPrefs(int $preferences): int

セキュリティ設定を指定します。

パラメータ

preferences

新しいセキュリティ設定。以下の定数を OR で指定できます。 XSL_SECPREF_READ_FILE、 XSL_SECPREF_WRITE_FILE、 XSL_SECPREF_CREATE_DIRECTORY、 XSL_SECPREF_READ_NETWORK、 XSL_SECPREF_WRITE_NETWORK。あるいは XSL_SECPREF_NONE や XSL_SECPREF_DEFAULT を渡すこともできます。

戻り値

元のセキュリティ設定を返します。


ドキュメント に変換する

  • ≪ XSLTProcessor::setSecurityPrefs
  • XSLTProcessor::transformToUri ≫
  • PHP Manual
  • XSLTProcessor
  • ドキュメント に変換する

XSLTProcessor::transformToDoc

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::transformToDoc — ドキュメント に変換する

説明

public XSLTProcessor::transformToDoc(object $document, ?string $returnClass = null): DOMDocument|false

XSLTProcessor::importStylesheet() メソッドで与えられたスタイルシートを適用し、 ソースノードをドキュメント (例: DOMDocument) に変換します。

パラメータ

document

変換される DOMDocument、SimpleXMLElement、または libxml と互換性があるオブジェクトを指定します。

returnClass

XSLTProcessor::transformToDoc() が返すオブジェクトのクラス名を指定する、オプションのパラメータです。ここで指定するクラスは、document と同じものか、それを継承したクラスであるべきです。

戻り値

結果の ドキュメント を返します。 エラーが発生した場合は false を返します。

例

例1 DOMDocument への変換

<?php

// XML ソースをロードする
$xml = new DOMDocument;
$xml->load('collection.xml');

$xsl = new DOMDocument;
$xsl->load('collection.xsl');

// 変換の設定を行う
$proc = new XSLTProcessor;
$proc->importStyleSheet($xsl); // XSL ルールを適用する

echo trim($proc->transformToDoc($xml)->firstChild->wholeText);

?>

上の例の出力は以下となります。

Hey! Welcome to Nicolas Eliaszewicz's sweet CD collection!

参考

  • XSLTProcessor::transformToUri() - URI に変換する
  • XSLTProcessor::transformToXml() - XML に変換する


URI に変換する

  • ≪ XSLTProcessor::transformToDoc
  • XSLTProcessor::transformToXml ≫
  • PHP Manual
  • XSLTProcessor
  • URI に変換する

XSLTProcessor::transformToUri

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::transformToUri — URI に変換する

説明

public XSLTProcessor::transformToUri(object $document, string $uri): int

XSLTProcessor::importStylesheet() メソッドで与えられたスタイルシートを適用し、 ソースノードを URI に変換します。

パラメータ

document

変換される DOMDocument または SimpleXMLElement オブジェクトを指定します。

uri

変換先の URI。

戻り値

書き込まれたバイト数。エラーが発生した場合は false 。

例

例1 HTML ファイルへの変換

<?php

// XML ソースをロードする
$xml = new DOMDocument;
$xml->load('collection.xml');

$xsl = new DOMDocument;
$xsl->load('collection.xsl');

// 変換の設定を行う
$proc = new XSLTProcessor;
$proc->importStyleSheet($xsl); // XSL ルールを適用する

$proc->transformToURI($xml, 'file:///tmp/out.html');

?>

参考

  • XSLTProcessor::transformToDoc() - ドキュメント に変換する
  • XSLTProcessor::transformToXml() - XML に変換する


XML に変換する

  • ≪ XSLTProcessor::transformToUri
  • GUI用の拡張モジュール ≫
  • PHP Manual
  • XSLTProcessor
  • XML に変換する

XSLTProcessor::transformToXml

(PHP 5, PHP 7, PHP 8)

XSLTProcessor::transformToXml — XML に変換する

説明

public XSLTProcessor::transformToXml(object $document): string|null|false

xsltprocessor::importStylesheet() メソッドで与えられたスタイルシートを適用し、 ソースノードを文字列に変換します。

パラメータ

document

変換される DOMDocument または SimpleXMLElement オブジェクトを指定します。

戻り値

変換結果の文字列。エラーが発生した場合は false 。

例

例1 文字列への変換

<?php

// XML ソースをロードする
$xml = new DOMDocument;
$xml->load('collection.xml');

$xsl = new DOMDocument;
$xsl->load('collection.xsl');

// 変換の設定を行う
$proc = new XSLTProcessor;
$proc->importStyleSheet($xsl); // XSL ルールを適用する

echo $proc->transformToXML($xml);

?>

上の例の出力は以下となります。

Hey! Welcome to Nicolas Eliaszewicz's sweet CD collection!

<h1>Fight for your mind</h1><h2>by Ben Harper - 1995</h2><hr>
<h1>Electric Ladyland</h1><h2>by Jimi Hendrix - 1997</h2><hr>

参考

  • XSLTProcessor::transformToDoc() - ドキュメント に変換する
  • XSLTProcessor::transformToUri() - URI に変換する


GUI用の拡張モジュール

  • UI
    • はじめに
    • インストール/設定
    • UI\Point — Represents a position (x,y)
    • UI\Size — Represents dimensions (width, height)
    • UI\Window — Window
    • UI\Control — Control
    • UI\Menu — Menu
    • UI\MenuItem — Menu Item
    • UI\Area — Area
    • UI\Executor — Execution Scheduler
    • UI\Controls\Tab — Tab Control
    • UI\Controls\Check — Check Control
    • UI\Controls\Button — Button Control
    • UI\Controls\ColorButton — ColorButton Control
    • UI\Controls\Label — Label Control
    • UI\Controls\Entry — Entry Control
    • UI\Controls\MultilineEntry — MultilineEntry Control
    • UI\Controls\Spin — Spin Control
    • UI\Controls\Slider — Slider Control
    • UI\Controls\Progress — Progress Control
    • UI\Controls\Separator — Control Separator
    • UI\Controls\Combo — Combo Control
    • UI\Controls\EditableCombo — EdiableCombo Control
    • UI\Controls\Radio — Radio Control
    • UI\Controls\Picker — Picker Control
    • UI\Controls\Form — Control Form (Arrangement)
    • UI\Controls\Grid — Control Grid (Arrangement)
    • UI\Controls\Group — Control Group (Arrangement)
    • UI\Controls\Box — Control Box (Arrangement)
    • UI\Draw\Pen — Draw Pen
    • UI\Draw\Path — Draw Path
    • UI\Draw\Matrix — Draw Matrix
    • UI\Draw\Color — Color Representation
    • UI\Draw\Stroke — Draw Stroke
    • UI\Draw\Brush — Brushes
    • UI\Draw\Brush\Gradient — Gradient Brushes
    • UI\Draw\Brush\LinearGradient — Linear Gradient
    • UI\Draw\Brush\RadialGradient — Radial Gradient
    • UI\Draw\Text\Layout — Represents Text Layout
    • UI\Draw\Text\Font — Represents a Font
    • UI\Draw\Text\Font\Descriptor — Font Descriptor
    • UI 関数
    • UI\Draw\Text\Font\Weight — Font Weight Settings
    • UI\Draw\Text\Font\Italic — Italic Font Settings
    • UI\Draw\Text\Font\Stretch — Font Stretch Settings
    • UI\Draw\Line\Cap — Line Cap Settings
    • UI\Draw\Line\Join — Line Join Settings
    • UI\Key — Key Identifiers
    • UI\Exception\InvalidArgumentException — InvalidArgumentException
    • UI\Exception\RuntimeException — RuntimeException


UI

  • はじめに
  • インストール/設定
    • 要件
    • インストール手順
  • UI\Point — Represents a position (x,y)
    • UI\Point::at — Size Coercion
    • UI\Point::__construct — Construct a new Point
    • UI\Point::getX — Retrieves X
    • UI\Point::getY — Retrieves Y
    • UI\Point::setX — Set X
    • UI\Point::setY — Set Y
  • UI\Size — Represents dimensions (width, height)
    • UI\Size::__construct — Construct a new Size
    • UI\Size::getHeight — Retrieves Height
    • UI\Size::getWidth — Retrives Width
    • UI\Size::of — Point Coercion
    • UI\Size::setHeight — Set Height
    • UI\Size::setWidth — Set Width
  • UI\Window — Window
    • UI\Window::add — Add a Control
    • UI\Window::__construct — Construct a new Window
    • UI\Window::error — Show Error Box
    • UI\Window::getSize — Get Window Size
    • UI\Window::getTitle — Get Title
    • UI\Window::hasBorders — Border Detection
    • UI\Window::hasMargin — Margin Detection
    • UI\Window::isFullScreen — Full Screen Detection
    • UI\Window::msg — Show Message Box
    • UI\Window::onClosing — Closing Callback
    • UI\Window::open — Open Dialog
    • UI\Window::save — Save Dialog
    • UI\Window::setBorders — Border Use
    • UI\Window::setFullScreen — Full Screen Use
    • UI\Window::setMargin — Margin Use
    • UI\Window::setSize — Set Size
    • UI\Window::setTitle — Window Title
  • UI\Control — Control
    • UI\Control::destroy — Destroy Control
    • UI\Control::disable — Disable Control
    • UI\Control::enable — Enable Control
    • UI\Control::getParent — Get Parent Control
    • UI\Control::getTopLevel — Get Top Level
    • UI\Control::hide — Hide Control
    • UI\Control::isEnabled — Determine if Control is enabled
    • UI\Control::isVisible — Determine if Control is visible
    • UI\Control::setParent — Set Parent Control
    • UI\Control::show — Control Show
  • UI\Menu — Menu
    • UI\Menu::append — Append Menu Item
    • UI\Menu::appendAbout — Append About Menu Item
    • UI\Menu::appendCheck — Append Checkable Menu Item
    • UI\Menu::appendPreferences — Append Preferences Menu Item
    • UI\Menu::appendQuit — Append Quit Menu Item
    • UI\Menu::appendSeparator — Append Menu Item Separator
    • UI\Menu::__construct — Construct a new Menu
  • UI\MenuItem — Menu Item
    • UI\MenuItem::disable — Disable Menu Item
    • UI\MenuItem::enable — Enable Menu Item
    • UI\MenuItem::isChecked — Detect Checked
    • UI\MenuItem::onClick — On Click Callback
    • UI\MenuItem::setChecked — Set Checked
  • UI\Area — Area
    • UI\Area::onDraw — Draw Callback
    • UI\Area::onKey — Key Callback
    • UI\Area::onMouse — Mouse Callback
    • UI\Area::redraw — Redraw Area
    • UI\Area::scrollTo — Area Scroll
    • UI\Area::setSize — Set Size
  • UI\Executor — Execution Scheduler
    • UI\Executor::__construct — Construct a new Executor
    • UI\Executor::kill — Stop Executor
    • UI\Executor::onExecute — Execution Callback
    • UI\Executor::setInterval — Interval Manipulation
  • UI\Controls\Tab — Tab Control
    • UI\Controls\Tab::append — Append Page
    • UI\Controls\Tab::delete — Delete Page
    • UI\Controls\Tab::hasMargin — Margin Detection
    • UI\Controls\Tab::insertAt — Insert Page
    • UI\Controls\Tab::pages — Page Count
    • UI\Controls\Tab::setMargin — Set Margin
  • UI\Controls\Check — Check Control
    • UI\Controls\Check::__construct — Construct a new Check
    • UI\Controls\Check::getText — Get Text
    • UI\Controls\Check::isChecked — Checked Detection
    • UI\Controls\Check::onToggle — Toggle Callback
    • UI\Controls\Check::setChecked — Set Checked
    • UI\Controls\Check::setText — Set Text
  • UI\Controls\Button — Button Control
    • UI\Controls\Button::__construct — Construct a new Button
    • UI\Controls\Button::getText — Get Text
    • UI\Controls\Button::onClick — Click Handler
    • UI\Controls\Button::setText — Set Text
  • UI\Controls\ColorButton — ColorButton Control
    • UI\Controls\ColorButton::getColor — Get Color
    • UI\Controls\ColorButton::onChange — Change Handler
    • UI\Controls\ColorButton::setColor — Set Color
  • UI\Controls\Label — Label Control
    • UI\Controls\Label::__construct — Construct a new Label
    • UI\Controls\Label::getText — Get Text
    • UI\Controls\Label::setText — Set Text
  • UI\Controls\Entry — Entry Control
    • UI\Controls\Entry::__construct — Construct a new Entry
    • UI\Controls\Entry::getText — Get Text
    • UI\Controls\Entry::isReadOnly — Detect Read Only
    • UI\Controls\Entry::onChange — Change Handler
    • UI\Controls\Entry::setReadOnly — Set Read Only
    • UI\Controls\Entry::setText — Set Text
  • UI\Controls\MultilineEntry — MultilineEntry Control
    • UI\Controls\MultilineEntry::append — Append Text
    • UI\Controls\MultilineEntry::__construct — Construct a new Multiline Entry
    • UI\Controls\MultilineEntry::getText — Get Text
    • UI\Controls\MultilineEntry::isReadOnly — Read Only Detection
    • UI\Controls\MultilineEntry::onChange — Change Handler
    • UI\Controls\MultilineEntry::setReadOnly — Set Read Only
    • UI\Controls\MultilineEntry::setText — Set Text
  • UI\Controls\Spin — Spin Control
    • UI\Controls\Spin::__construct — Construct a new Spin
    • UI\Controls\Spin::getValue — Get Value
    • UI\Controls\Spin::onChange — Change Handler
    • UI\Controls\Spin::setValue — Set Value
  • UI\Controls\Slider — Slider Control
    • UI\Controls\Slider::__construct — Construct a new Slider
    • UI\Controls\Slider::getValue — Get Value
    • UI\Controls\Slider::onChange — Change Handler
    • UI\Controls\Slider::setValue — Set Value
  • UI\Controls\Progress — Progress Control
    • UI\Controls\Progress::getValue — Get Value
    • UI\Controls\Progress::setValue — Set Value
  • UI\Controls\Separator — Control Separator
    • UI\Controls\Separator::__construct — Construct a new Separator
  • UI\Controls\Combo — Combo Control
    • UI\Controls\Combo::append — Append Option
    • UI\Controls\Combo::getSelected — Get Selected Option
    • UI\Controls\Combo::onSelected — Selected Handler
    • UI\Controls\Combo::setSelected — Set Selected Option
  • UI\Controls\EditableCombo — EdiableCombo Control
    • UI\Controls\EditableCombo::append — Append Option
    • UI\Controls\EditableCombo::getText — Get Text
    • UI\Controls\EditableCombo::onChange — Change Handler
    • UI\Controls\EditableCombo::setText — Set Text
  • UI\Controls\Radio — Radio Control
    • UI\Controls\Radio::append — Append Option
    • UI\Controls\Radio::getSelected — Get Selected Option
    • UI\Controls\Radio::onSelected — Selected Handler
    • UI\Controls\Radio::setSelected — Set Selected Option
  • UI\Controls\Picker — Picker Control
    • UI\Controls\Picker::__construct — Construct a new Picker
  • UI\Controls\Form — Control Form (Arrangement)
    • UI\Controls\Form::append — Append Control
    • UI\Controls\Form::delete — Delete Control
    • UI\Controls\Form::isPadded — Padding Detection
    • UI\Controls\Form::setPadded — Set Padding
  • UI\Controls\Grid — Control Grid (Arrangement)
    • UI\Controls\Grid::append — Append Control
    • UI\Controls\Grid::isPadded — Padding Detection
    • UI\Controls\Grid::setPadded — Set Padding
  • UI\Controls\Group — Control Group (Arrangement)
    • UI\Controls\Group::append — Append Control
    • UI\Controls\Group::__construct — Construct a new Group
    • UI\Controls\Group::getTitle — Get Title
    • UI\Controls\Group::hasMargin — Margin Detection
    • UI\Controls\Group::setMargin — Set Margin
    • UI\Controls\Group::setTitle — Set Title
  • UI\Controls\Box — Control Box (Arrangement)
    • UI\Controls\Box::append — Append Control
    • UI\Controls\Box::__construct — Construct a new Box
    • UI\Controls\Box::delete — Delete Control
    • UI\Controls\Box::getOrientation — Get Orientation
    • UI\Controls\Box::isPadded — Padding Detection
    • UI\Controls\Box::setPadded — Set Padding
  • UI\Draw\Pen — Draw Pen
    • UI\Draw\Pen::clip — Clip a Path
    • UI\Draw\Pen::fill — Fill a Path
    • UI\Draw\Pen::restore — Restore
    • UI\Draw\Pen::save — Save
    • UI\Draw\Pen::stroke — Stroke a Path
    • UI\Draw\Pen::transform — Matrix Transform
    • UI\Draw\Pen::write — Draw Text at Point
  • UI\Draw\Path — Draw Path
    • UI\Draw\Path::addRectangle — Draw a Rectangle
    • UI\Draw\Path::arcTo — Draw an Arc
    • UI\Draw\Path::bezierTo — Draw Bezier Curve
    • UI\Draw\Path::closeFigure — Close Figure
    • UI\Draw\Path::__construct — Construct a new Path
    • UI\Draw\Path::end — Finalize Path
    • UI\Draw\Path::lineTo — Draw a Line
    • UI\Draw\Path::newFigure — Draw Figure
    • UI\Draw\Path::newFigureWithArc — Draw Figure with Arc
  • UI\Draw\Matrix — Draw Matrix
    • UI\Draw\Matrix::invert — Invert Matrix
    • UI\Draw\Matrix::isInvertible — Invertible Detection
    • UI\Draw\Matrix::multiply — Multiply Matrix
    • UI\Draw\Matrix::rotate — Rotate Matrix
    • UI\Draw\Matrix::scale — Scale Matrix
    • UI\Draw\Matrix::skew — Skew Matrix
    • UI\Draw\Matrix::translate — Translate Matrix
  • UI\Draw\Color — Color Representation
    • UI\Draw\Color::__construct — Construct new Color
    • UI\Draw\Color::getChannel — Color Manipulation
    • UI\Draw\Color::setChannel — Color Manipulation
  • UI\Draw\Stroke — Draw Stroke
    • UI\Draw\Stroke::__construct — Construct a new Stroke
    • UI\Draw\Stroke::getCap — Get Line Cap
    • UI\Draw\Stroke::getJoin — Get Line Join
    • UI\Draw\Stroke::getMiterLimit — Get Miter Limit
    • UI\Draw\Stroke::getThickness — Get Thickness
    • UI\Draw\Stroke::setCap — Set Line Cap
    • UI\Draw\Stroke::setJoin — Set Line Join
    • UI\Draw\Stroke::setMiterLimit — Set Miter Limit
    • UI\Draw\Stroke::setThickness — Set Thickness
  • UI\Draw\Brush — Brushes
    • UI\Draw\Brush::__construct — Construct a new Brush
    • UI\Draw\Brush::getColor — Get Color
    • UI\Draw\Brush::setColor — Set Color
  • UI\Draw\Brush\Gradient — Gradient Brushes
    • UI\Draw\Brush\Gradient::addStop — Stop Manipulation
    • UI\Draw\Brush\Gradient::delStop — Stop Manipulation
    • UI\Draw\Brush\Gradient::setStop — Stop Manipulation
  • UI\Draw\Brush\LinearGradient — Linear Gradient
    • UI\Draw\Brush\LinearGradient::__construct — Construct a Linear Gradient
  • UI\Draw\Brush\RadialGradient — Radial Gradient
    • UI\Draw\Brush\RadialGradient::__construct — Construct a new Radial Gradient
  • UI\Draw\Text\Layout — Represents Text Layout
    • UI\Draw\Text\Layout::__construct — Construct a new Text Layout
    • UI\Draw\Text\Layout::setColor — Set Color
    • UI\Draw\Text\Layout::setWidth — Set Width
  • UI\Draw\Text\Font — Represents a Font
    • UI\Draw\Text\Font::__construct — Construct a new Font
    • UI\Draw\Text\Font::getAscent — Font Metrics
    • UI\Draw\Text\Font::getDescent — Font Metrics
    • UI\Draw\Text\Font::getLeading — Font Metrics
    • UI\Draw\Text\Font::getUnderlinePosition — Font Metrics
    • UI\Draw\Text\Font::getUnderlineThickness — Font Metrics
  • UI\Draw\Text\Font\Descriptor — Font Descriptor
    • UI\Draw\Text\Font\Descriptor::__construct — Construct a new Font Descriptor
    • UI\Draw\Text\Font\Descriptor::getFamily — Get Font Family
    • UI\Draw\Text\Font\Descriptor::getItalic — Style Detection
    • UI\Draw\Text\Font\Descriptor::getSize — Size Detection
    • UI\Draw\Text\Font\Descriptor::getStretch — Style Detection
    • UI\Draw\Text\Font\Descriptor::getWeight — Weight Detection
  • UI 関数
    • UI\Draw\Text\Font\fontFamilies — Retrieve Font Families
    • UI\quit — Quit UI Loop
    • UI\run — Enter UI Loop
  • UI\Draw\Text\Font\Weight — Font Weight Settings
  • UI\Draw\Text\Font\Italic — Italic Font Settings
  • UI\Draw\Text\Font\Stretch — Font Stretch Settings
  • UI\Draw\Line\Cap — Line Cap Settings
  • UI\Draw\Line\Join — Line Join Settings
  • UI\Key — Key Identifiers
  • UI\Exception\InvalidArgumentException — InvalidArgumentException
  • UI\Exception\RuntimeException — RuntimeException


はじめに

This extension wraps libui to provide an OO API for the cross platform development of native look-and-feel user interfaces .


  • ≪ はじめに
  • 要件 ≫
  • PHP Manual
  • UI
  • インストール/設定

インストール/設定

目次

  • 要件
  • インストール手順


要件

Installation requires the libui library, and PHP 7 or newer.

This extension requires the » libui library version 0.1.0 or higher to be installed. See the libui documentation for a list of prerequisites.


インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/ui.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。


Represents a position (x,y)

(UI 0.9.9)

はじめに

Points are used throughout UI to represent co-ordinates on a screen, control, or area.

クラス概要

final class UI\Point {
/* プロパティ */
public $x;
public $y;
/* Constructor */
public __construct(float $x, float $y)
/* メソッド */
public static at(float $point): UI\Point
public static at(UI\Size $size): UI\Point
public getX(): float
public getY(): float
public setX(float $point)
public setY(float $point)
}

プロパティ

x

Holds the X co-ordinate, can be read/written directly

y

Holds the Y co-ordinate, can be read/written directly

目次

  • UI\Point::at — Size Coercion
  • UI\Point::__construct — Construct a new Point
  • UI\Point::getX — Retrieves X
  • UI\Point::getY — Retrieves Y
  • UI\Point::setX — Set X
  • UI\Point::setY — Set Y


Size Coercion

  • ≪ UI\Point
  • UI\Point::__construct ≫
  • PHP Manual
  • UI\Point
  • Size Coercion

UI\Point::at

(UI 1.0.2)

UI\Point::at — Size Coercion

説明

public static UI\Point::at(float $point): UI\Point
public static UI\Point::at(UI\Size $size): UI\Point

Shall return a UI\Point object where x and y are equal to those supplied, either in float or UI\Size form

パラメータ

point

The value for x and y

size

The Size to convert

戻り値

The resulting Point


Construct a new Point

  • ≪ UI\Point::at
  • UI\Point::getX ≫
  • PHP Manual
  • UI\Point
  • Construct a new Point

UI\Point::__construct

(UI 0.9.9)

UI\Point::__construct — Construct a new Point

説明

public UI\Point::__construct(float $x, float $y)

Construct a new Point using new co-ordinates

パラメータ

x

The new X co-ordinate

y

The new Y co-ordinate


Retrieves X

  • ≪ UI\Point::__construct
  • UI\Point::getY ≫
  • PHP Manual
  • UI\Point
  • Retrieves X

UI\Point::getX

(UI 0.9.9)

UI\Point::getX — Retrieves X

説明

public UI\Point::getX(): float

Retrieves the X co-ordinate

パラメータ

この関数にはパラメータはありません。

戻り値

The current X co-ordinate


Retrieves Y

  • ≪ UI\Point::getX
  • UI\Point::setX ≫
  • PHP Manual
  • UI\Point
  • Retrieves Y

UI\Point::getY

(UI 0.9.9)

UI\Point::getY — Retrieves Y

説明

public UI\Point::getY(): float

Retrieves the Y co-ordinate

パラメータ

この関数にはパラメータはありません。

戻り値

The current Y co-ordinate


Set X

  • ≪ UI\Point::getY
  • UI\Point::setY ≫
  • PHP Manual
  • UI\Point
  • Set X

UI\Point::setX

(UI 0.9.9)

UI\Point::setX — Set X

説明

public UI\Point::setX(float $point)

Set the X co-ordinate

パラメータ

point

The new X co-ordinate

戻り値


Set Y

  • ≪ UI\Point::setX
  • UI\Size ≫
  • PHP Manual
  • UI\Point
  • Set Y

UI\Point::setY

(UI 0.9.9)

UI\Point::setY — Set Y

説明

public UI\Point::setY(float $point)

Set the Y co-ordinate

パラメータ

point

The new Y co-ordinate

戻り値


Represents dimensions (width, height)

(UI 0.9.9)

はじめに

Sizes are used throughout UI to represent the size of a screen, control, or area.

クラス概要

final class UI\Size {
/* プロパティ */
public $width;
public $height;
/* Constructor */
public __construct(float $width, float $height)
/* メソッド */
public getHeight(): float
public getWidth(): float
public static of(float $size): UI\Size
public static of(UI\Point $point): UI\Size
public setHeight(float $size)
public setWidth(float $size)
}

プロパティ

width

Holds the width, can be read/written directly

height

Holds the height, can be read/written directly

目次

  • UI\Size::__construct — Construct a new Size
  • UI\Size::getHeight — Retrieves Height
  • UI\Size::getWidth — Retrives Width
  • UI\Size::of — Point Coercion
  • UI\Size::setHeight — Set Height
  • UI\Size::setWidth — Set Width


Construct a new Size

  • ≪ UI\Size
  • UI\Size::getHeight ≫
  • PHP Manual
  • UI\Size
  • Construct a new Size

UI\Size::__construct

(UI 0.9.9)

UI\Size::__construct — Construct a new Size

説明

public UI\Size::__construct(float $width, float $height)

Construct a new Size using new width and height

パラメータ

width

The new width

height

The new height


Retrieves Height

  • ≪ UI\Size::__construct
  • UI\Size::getWidth ≫
  • PHP Manual
  • UI\Size
  • Retrieves Height

UI\Size::getHeight

(UI 0.9.9)

UI\Size::getHeight — Retrieves Height

説明

public UI\Size::getHeight(): float

Retrieves the Height

パラメータ

この関数にはパラメータはありません。

戻り値

The current Height


Retrives Width

  • ≪ UI\Size::getHeight
  • UI\Size::of ≫
  • PHP Manual
  • UI\Size
  • Retrives Width

UI\Size::getWidth

(UI 0.9.9)

UI\Size::getWidth — Retrives Width

説明

public UI\Size::getWidth(): float

Retrieves the Width

パラメータ

この関数にはパラメータはありません。

戻り値

The current Width


Point Coercion

  • ≪ UI\Size::getWidth
  • UI\Size::setHeight ≫
  • PHP Manual
  • UI\Size
  • Point Coercion

UI\Size::of

(UI 1.0.2)

UI\Size::of — Point Coercion

説明

public static UI\Size::of(float $size): UI\Size
public static UI\Size::of(UI\Point $point): UI\Size

Shall return a UI\Size object where width and height are equal to those supplied, either in float or UI\Point form

パラメータ

size

The value for width and height

point

The Point to convert

戻り値

The resulting Size


Set Height

  • ≪ UI\Size::of
  • UI\Size::setWidth ≫
  • PHP Manual
  • UI\Size
  • Set Height

UI\Size::setHeight

(UI 0.9.9)

UI\Size::setHeight — Set Height

説明

public UI\Size::setHeight(float $size)

Set new Height

パラメータ

size

The new Height

戻り値


Set Width

  • ≪ UI\Size::setHeight
  • UI\Window ≫
  • PHP Manual
  • UI\Size
  • Set Width

UI\Size::setWidth

(UI 0.9.9)

UI\Size::setWidth — Set Width

説明

public UI\Size::setWidth(float $size)

Set new Width

パラメータ

size

The new Width

戻り値


Window

(UI 0.9.9)

はじめに

Represents a UI Window

クラス概要

class UI\Window extends UI\Control {
/* プロパティ */
protected $controls;
/* Constructor */
public __construct(string $title, Size $size, bool $menu = false)
/* メソッド */
public add(UI\Control $control)
public error(string $title, string $msg)
public getSize(): UI\Size
public getTitle(): string
public hasBorders(): bool
public hasMargin(): bool
public isFullScreen(): bool
public msg(string $title, string $msg)
protected onClosing(): int
public open(): string
public save(): string
public setBorders(bool $borders)
public setFullScreen(bool $full)
public setMargin(bool $margin)
public setSize(UI\Size $size)
public setTitle(string $title)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

プロパティ

controls

Contains controls, should not be manipulated directly

目次

  • UI\Window::add — Add a Control
  • UI\Window::__construct — Construct a new Window
  • UI\Window::error — Show Error Box
  • UI\Window::getSize — Get Window Size
  • UI\Window::getTitle — Get Title
  • UI\Window::hasBorders — Border Detection
  • UI\Window::hasMargin — Margin Detection
  • UI\Window::isFullScreen — Full Screen Detection
  • UI\Window::msg — Show Message Box
  • UI\Window::onClosing — Closing Callback
  • UI\Window::open — Open Dialog
  • UI\Window::save — Save Dialog
  • UI\Window::setBorders — Border Use
  • UI\Window::setFullScreen — Full Screen Use
  • UI\Window::setMargin — Margin Use
  • UI\Window::setSize — Set Size
  • UI\Window::setTitle — Window Title


Add a Control

  • ≪ UI\Window
  • UI\Window::__construct ≫
  • PHP Manual
  • UI\Window
  • Add a Control

UI\Window::add

(UI 0.9.9)

UI\Window::add — Add a Control

説明

public UI\Window::add(UI\Control $control)

Shall add a Control to this Window

パラメータ

control

The Control to add

戻り値


Construct a new Window

  • ≪ UI\Window::add
  • UI\Window::error ≫
  • PHP Manual
  • UI\Window
  • Construct a new Window

UI\Window::__construct

(UI 0.9.9)

UI\Window::__construct — Construct a new Window

説明

public UI\Window::__construct(string $title, Size $size, bool $menu = false)

Shall construct a new Window

パラメータ

title

The title of the Window

size

The size of the Window

menu

Menu switch


Show Error Box

  • ≪ UI\Window::__construct
  • UI\Window::getSize ≫
  • PHP Manual
  • UI\Window
  • Show Error Box

UI\Window::error

(UI 0.9.9)

UI\Window::error — Show Error Box

説明

public UI\Window::error(string $title, string $msg)

Shall show an error box

パラメータ

title

The title of the error box

msg

The message for the error box


Get Window Size

  • ≪ UI\Window::error
  • UI\Window::getTitle ≫
  • PHP Manual
  • UI\Window
  • Get Window Size

UI\Window::getSize

(UI 0.9.9)

UI\Window::getSize — Get Window Size

説明

public UI\Window::getSize(): UI\Size

Shall return the size of this Window

パラメータ

この関数にはパラメータはありません。

戻り値


Get Title

  • ≪ UI\Window::getSize
  • UI\Window::hasBorders ≫
  • PHP Manual
  • UI\Window
  • Get Title

UI\Window::getTitle

(UI 0.9.9)

UI\Window::getTitle — Get Title

説明

public UI\Window::getTitle(): string

Shall retrieve the title of this Window

パラメータ

この関数にはパラメータはありません。

戻り値


Border Detection

  • ≪ UI\Window::getTitle
  • UI\Window::hasMargin ≫
  • PHP Manual
  • UI\Window
  • Border Detection

UI\Window::hasBorders

(UI 0.9.9)

UI\Window::hasBorders — Border Detection

説明

public UI\Window::hasBorders(): bool

Shall detect if borders are used on this Window

パラメータ

この関数にはパラメータはありません。

戻り値


Margin Detection

  • ≪ UI\Window::hasBorders
  • UI\Window::isFullScreen ≫
  • PHP Manual
  • UI\Window
  • Margin Detection

UI\Window::hasMargin

(UI 0.9.9)

UI\Window::hasMargin — Margin Detection

説明

public UI\Window::hasMargin(): bool

Shall detect if margins are used on this Window

パラメータ

この関数にはパラメータはありません。

戻り値


Full Screen Detection

  • ≪ UI\Window::hasMargin
  • UI\Window::msg ≫
  • PHP Manual
  • UI\Window
  • Full Screen Detection

UI\Window::isFullScreen

(UI 0.9.9)

UI\Window::isFullScreen — Full Screen Detection

説明

public UI\Window::isFullScreen(): bool

Shall detect if this Window us using the whole screen

パラメータ

この関数にはパラメータはありません。

戻り値


Show Message Box

  • ≪ UI\Window::isFullScreen
  • UI\Window::onClosing ≫
  • PHP Manual
  • UI\Window
  • Show Message Box

UI\Window::msg

(UI 0.9.9)

UI\Window::msg — Show Message Box

説明

public UI\Window::msg(string $title, string $msg)

Shall show a message box

パラメータ

title

The title of the message box

msg

The message


Closing Callback

  • ≪ UI\Window::msg
  • UI\Window::open ≫
  • PHP Manual
  • UI\Window
  • Closing Callback

UI\Window::onClosing

(UI 0.9.9)

UI\Window::onClosing — Closing Callback

説明

protected UI\Window::onClosing(): int

Should gracefully destroy this Window

パラメータ

この関数にはパラメータはありません。

戻り値


Open Dialog

  • ≪ UI\Window::onClosing
  • UI\Window::save ≫
  • PHP Manual
  • UI\Window
  • Open Dialog

UI\Window::open

(UI 0.9.9)

UI\Window::open — Open Dialog

説明

public UI\Window::open(): string

Shall show an open file dialog

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the name of the file selected for opening


Save Dialog

  • ≪ UI\Window::open
  • UI\Window::setBorders ≫
  • PHP Manual
  • UI\Window
  • Save Dialog

UI\Window::save

(UI 0.9.9)

UI\Window::save — Save Dialog

説明

public UI\Window::save(): string

Shall show a save dialog

パラメータ

この関数にはパラメータはありません。

戻り値

Returns the file name selecting for saving


Border Use

  • ≪ UI\Window::save
  • UI\Window::setFullScreen ≫
  • PHP Manual
  • UI\Window
  • Border Use

UI\Window::setBorders

(UI 0.9.9)

UI\Window::setBorders — Border Use

説明

public UI\Window::setBorders(bool $borders)

Shall enable or disable the use of borders on this Window

パラメータ

borders


Full Screen Use

  • ≪ UI\Window::setBorders
  • UI\Window::setMargin ≫
  • PHP Manual
  • UI\Window
  • Full Screen Use

UI\Window::setFullScreen

(UI 0.9.9)

UI\Window::setFullScreen — Full Screen Use

説明

public UI\Window::setFullScreen(bool $full)

Shall enable or disable the use of the full screen for this Window

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

full


Margin Use

  • ≪ UI\Window::setFullScreen
  • UI\Window::setSize ≫
  • PHP Manual
  • UI\Window
  • Margin Use

UI\Window::setMargin

(UI 0.9.9)

UI\Window::setMargin — Margin Use

説明

public UI\Window::setMargin(bool $margin)

Shall enable or disable the use of margins for this Window

パラメータ

margin


Set Size

  • ≪ UI\Window::setMargin
  • UI\Window::setTitle ≫
  • PHP Manual
  • UI\Window
  • Set Size

UI\Window::setSize

(UI 0.9.9)

UI\Window::setSize — Set Size

説明

public UI\Window::setSize(UI\Size $size)

Shall set the size of this Window

パラメータ

size

戻り値


Window Title

  • ≪ UI\Window::setSize
  • UI\Control ≫
  • PHP Manual
  • UI\Window
  • Window Title

UI\Window::setTitle

(UI 0.9.9)

UI\Window::setTitle — Window Title

説明

public UI\Window::setTitle(string $title)

Shall set the title for this Window

パラメータ

title

The new title


Control

(UI 0.9.9)

はじめに

This is the closed base class for all UI Controls.

クラス概要

final class UI\Control {
/* メソッド */
public destroy()
public disable()
public enable()
public getParent(): UI\Control
public getTopLevel(): int
public hide()
public isEnabled(): bool
public isVisible(): bool
public setParent(UI\Control $parent)
public show()
}

目次

  • UI\Control::destroy — Destroy Control
  • UI\Control::disable — Disable Control
  • UI\Control::enable — Enable Control
  • UI\Control::getParent — Get Parent Control
  • UI\Control::getTopLevel — Get Top Level
  • UI\Control::hide — Hide Control
  • UI\Control::isEnabled — Determine if Control is enabled
  • UI\Control::isVisible — Determine if Control is visible
  • UI\Control::setParent — Set Parent Control
  • UI\Control::show — Control Show


Destroy Control

  • ≪ UI\Control
  • UI\Control::disable ≫
  • PHP Manual
  • UI\Control
  • Destroy Control

UI\Control::destroy

(UI 0.9.9)

UI\Control::destroy — Destroy Control

説明

public UI\Control::destroy()

Shall destroy this Control

パラメータ

この関数にはパラメータはありません。

戻り値


Disable Control

  • ≪ UI\Control::destroy
  • UI\Control::enable ≫
  • PHP Manual
  • UI\Control
  • Disable Control

UI\Control::disable

(UI 0.9.9)

UI\Control::disable — Disable Control

説明

public UI\Control::disable()

Shall disable this Control

パラメータ

この関数にはパラメータはありません。

戻り値


Enable Control

  • ≪ UI\Control::disable
  • UI\Control::getParent ≫
  • PHP Manual
  • UI\Control
  • Enable Control

UI\Control::enable

(UI 0.9.9)

UI\Control::enable — Enable Control

説明

public UI\Control::enable()

Shall enable this Control

パラメータ

この関数にはパラメータはありません。

戻り値


Get Parent Control

  • ≪ UI\Control::enable
  • UI\Control::getTopLevel ≫
  • PHP Manual
  • UI\Control
  • Get Parent Control

UI\Control::getParent

(UI 0.9.9)

UI\Control::getParent — Get Parent Control

説明

public UI\Control::getParent(): UI\Control

Shall return the parent Control

パラメータ

この関数にはパラメータはありません。

戻り値


Get Top Level

  • ≪ UI\Control::getParent
  • UI\Control::hide ≫
  • PHP Manual
  • UI\Control
  • Get Top Level

UI\Control::getTopLevel

(UI 0.9.9)

UI\Control::getTopLevel — Get Top Level

説明

public UI\Control::getTopLevel(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Hide Control

  • ≪ UI\Control::getTopLevel
  • UI\Control::isEnabled ≫
  • PHP Manual
  • UI\Control
  • Hide Control

UI\Control::hide

(UI 0.9.9)

UI\Control::hide — Hide Control

説明

public UI\Control::hide()

Shall hide this Control

パラメータ

この関数にはパラメータはありません。

戻り値


Determine if Control is enabled

  • ≪ UI\Control::hide
  • UI\Control::isVisible ≫
  • PHP Manual
  • UI\Control
  • Determine if Control is enabled

UI\Control::isEnabled

(UI 0.9.9)

UI\Control::isEnabled — Determine if Control is enabled

説明

public UI\Control::isEnabled(): bool

Shall detect if this Control is enabled

パラメータ

この関数にはパラメータはありません。

戻り値


Determine if Control is visible

  • ≪ UI\Control::isEnabled
  • UI\Control::setParent ≫
  • PHP Manual
  • UI\Control
  • Determine if Control is visible

UI\Control::isVisible

(UI 0.9.9)

UI\Control::isVisible — Determine if Control is visible

説明

public UI\Control::isVisible(): bool

Shall detect if this Control is visible

パラメータ

この関数にはパラメータはありません。

戻り値


Set Parent Control

  • ≪ UI\Control::isVisible
  • UI\Control::show ≫
  • PHP Manual
  • UI\Control
  • Set Parent Control

UI\Control::setParent

(UI 0.9.9)

UI\Control::setParent — Set Parent Control

説明

public UI\Control::setParent(UI\Control $parent)

Shall set the parent Control of this Control

パラメータ

parent

The parent Control

戻り値


Control Show

  • ≪ UI\Control::setParent
  • UI\Menu ≫
  • PHP Manual
  • UI\Control
  • Control Show

UI\Control::show

(UI 0.9.9)

UI\Control::show — Control Show

説明

public UI\Control::show()

Shall show this Control

パラメータ

この関数にはパラメータはありません。

戻り値


Menu

(UI 0.9.9)

はじめに

Menus must be constructed before the first Window, and can be shown on any Window

クラス概要

class UI\Menu {
/* Constructor */
public __construct(string $name)
/* メソッド */
public append(string $name, string $type = UI\MenuItem::class): UI\MenuItem
public appendAbout(string $type = UI\MenuItem::class): UI\MenuItem
public appendCheck(string $name, string $type = UI\MenuItem::class): UI\MenuItem
public appendPreferences(string $type = UI\MenuItem::class): UI\MenuItem
public appendQuit(string $type = UI\MenuItem::class): UI\MenuItem
public appendSeparator()
}

目次

  • UI\Menu::append — Append Menu Item
  • UI\Menu::appendAbout — Append About Menu Item
  • UI\Menu::appendCheck — Append Checkable Menu Item
  • UI\Menu::appendPreferences — Append Preferences Menu Item
  • UI\Menu::appendQuit — Append Quit Menu Item
  • UI\Menu::appendSeparator — Append Menu Item Separator
  • UI\Menu::__construct — Construct a new Menu


Append Menu Item

  • ≪ UI\Menu
  • UI\Menu::appendAbout ≫
  • PHP Manual
  • UI\Menu
  • Append Menu Item

UI\Menu::append

(UI 0.9.9)

UI\Menu::append — Append Menu Item

説明

public UI\Menu::append(string $name, string $type = UI\MenuItem::class): UI\MenuItem

Shall append a new Menu Item

パラメータ

name

The name (text) for the new item

type

The type for the new item

戻り値

A constructed object of the given type


Append About Menu Item

  • ≪ UI\Menu::append
  • UI\Menu::appendCheck ≫
  • PHP Manual
  • UI\Menu
  • Append About Menu Item

UI\Menu::appendAbout

(UI 0.9.9)

UI\Menu::appendAbout — Append About Menu Item

説明

public UI\Menu::appendAbout(string $type = UI\MenuItem::class): UI\MenuItem

Shall append an About menu item

パラメータ

type

The type for the new item

戻り値

A constructed About menu item of the given type


Append Checkable Menu Item

  • ≪ UI\Menu::appendAbout
  • UI\Menu::appendPreferences ≫
  • PHP Manual
  • UI\Menu
  • Append Checkable Menu Item

UI\Menu::appendCheck

(UI 0.9.9)

UI\Menu::appendCheck — Append Checkable Menu Item

説明

public UI\Menu::appendCheck(string $name, string $type = UI\MenuItem::class): UI\MenuItem

Shall append a checkable menu item

パラメータ

name

The name (text) for the new item

type

The type for the new item

戻り値

A constructed checkable menu item of the given type


Append Preferences Menu Item

  • ≪ UI\Menu::appendCheck
  • UI\Menu::appendQuit ≫
  • PHP Manual
  • UI\Menu
  • Append Preferences Menu Item

UI\Menu::appendPreferences

(UI 0.9.9)

UI\Menu::appendPreferences — Append Preferences Menu Item

説明

public UI\Menu::appendPreferences(string $type = UI\MenuItem::class): UI\MenuItem

Shall append a Preferences menu item

パラメータ

type

The type for the new item

戻り値

A constructed Preferences menu item of the given type


Append Quit Menu Item

  • ≪ UI\Menu::appendPreferences
  • UI\Menu::appendSeparator ≫
  • PHP Manual
  • UI\Menu
  • Append Quit Menu Item

UI\Menu::appendQuit

(UI 0.9.9)

UI\Menu::appendQuit — Append Quit Menu Item

説明

public UI\Menu::appendQuit(string $type = UI\MenuItem::class): UI\MenuItem

Shall append a Quit menu item

パラメータ

type

The type for the new item

戻り値

A constructed Quit menu item of the given type


Append Menu Item Separator

  • ≪ UI\Menu::appendQuit
  • UI\Menu::__construct ≫
  • PHP Manual
  • UI\Menu
  • Append Menu Item Separator

UI\Menu::appendSeparator

(UI 0.9.9)

UI\Menu::appendSeparator — Append Menu Item Separator

説明

public UI\Menu::appendSeparator()

Shall append a separator

パラメータ

この関数にはパラメータはありません。


Construct a new Menu

  • ≪ UI\Menu::appendSeparator
  • UI\MenuItem ≫
  • PHP Manual
  • UI\Menu
  • Construct a new Menu

UI\Menu::__construct

(UI 0.9.9)

UI\Menu::__construct — Construct a new Menu

説明

public UI\Menu::__construct(string $name)

Shall construct a new Menu

パラメータ

name

The name (text) for the menu


Menu Item

(UI 0.9.9)

はじめに

Menu Items should only be created by the Menu

クラス概要

class UI\MenuItem {
/* メソッド */
public disable()
public enable()
public isChecked(): bool
protected onClick()
public setChecked(bool $checked)
}

目次

  • UI\MenuItem::disable — Disable Menu Item
  • UI\MenuItem::enable — Enable Menu Item
  • UI\MenuItem::isChecked — Detect Checked
  • UI\MenuItem::onClick — On Click Callback
  • UI\MenuItem::setChecked — Set Checked


Disable Menu Item

  • ≪ UI\MenuItem
  • UI\MenuItem::enable ≫
  • PHP Manual
  • UI\MenuItem
  • Disable Menu Item

UI\MenuItem::disable

(UI 0.9.9)

UI\MenuItem::disable — Disable Menu Item

説明

public UI\MenuItem::disable()

Shall disable this Menu Item

パラメータ

この関数にはパラメータはありません。


Enable Menu Item

  • ≪ UI\MenuItem::disable
  • UI\MenuItem::isChecked ≫
  • PHP Manual
  • UI\MenuItem
  • Enable Menu Item

UI\MenuItem::enable

(UI 0.9.9)

UI\MenuItem::enable — Enable Menu Item

説明

public UI\MenuItem::enable()

Shall enable this Menu Item

パラメータ

この関数にはパラメータはありません。


Detect Checked

  • ≪ UI\MenuItem::enable
  • UI\MenuItem::onClick ≫
  • PHP Manual
  • UI\MenuItem
  • Detect Checked

UI\MenuItem::isChecked

(UI 0.9.9)

UI\MenuItem::isChecked — Detect Checked

説明

public UI\MenuItem::isChecked(): bool

Shall detect if this Menu Item is checked

パラメータ

この関数にはパラメータはありません。


On Click Callback

  • ≪ UI\MenuItem::isChecked
  • UI\MenuItem::setChecked ≫
  • PHP Manual
  • UI\MenuItem
  • On Click Callback

UI\MenuItem::onClick

(UI 0.9.9)

UI\MenuItem::onClick — On Click Callback

説明

protected UI\MenuItem::onClick()

Shall be executed when this Menu Item is clicked

パラメータ

この関数にはパラメータはありません。


Set Checked

  • ≪ UI\MenuItem::onClick
  • UI\Area ≫
  • PHP Manual
  • UI\MenuItem
  • Set Checked

UI\MenuItem::setChecked

(UI 0.9.9)

UI\MenuItem::setChecked — Set Checked

説明

public UI\MenuItem::setChecked(bool $checked)

Shall set the checked status of this Menu Item

パラメータ

checked

The new status


Area

(UI 0.9.9)

はじめに

An Area represents a canvas which can be used to draw, and respond to mouse and key events.

クラス概要

class UI\Area extends UI\Control {
/* 定数 */
const int Ctrl;
const int Alt;
const int Shift;
const int Super;
const int Down;
const int Up;
/* メソッド */
protected onDraw(
UI\Draw\Pen $pen,
UI\Size $areaSize,
UI\Point $clipPoint,
UI\Size $clipSize
)
protected onKey(string $key, int $ext, int $flags)
protected onMouse(UI\Point $areaPoint, UI\Size $areaSize, int $flags)
public redraw()
public scrollTo(UI\Point $point, UI\Size $size)
public setSize(UI\Size $size)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

定義済み定数

UI\Area::Ctrl

Shall be set in the modifiers passed to key and mouse events when the CTRL key is active

UI\Area::Alt

Shall be set in the modifiers passed to key and mouse events when the ALT key is active

UI\Area::Shift

Shall be set in the modifiers passed to key and mouse events when the SHIFT key is active

UI\Area::Super

UI\Area::Down

Shall be set in the modifiers passed to key and mouse events

UI\Area::Up

Shall be set in the modifiers passed to key and mouse events

目次

  • UI\Area::onDraw — Draw Callback
  • UI\Area::onKey — Key Callback
  • UI\Area::onMouse — Mouse Callback
  • UI\Area::redraw — Redraw Area
  • UI\Area::scrollTo — Area Scroll
  • UI\Area::setSize — Set Size


Draw Callback

  • ≪ UI\Area
  • UI\Area::onKey ≫
  • PHP Manual
  • UI\Area
  • Draw Callback

UI\Area::onDraw

(UI 0.9.9)

UI\Area::onDraw — Draw Callback

説明

protected UI\Area::onDraw(
UI\Draw\Pen $pen,
UI\Size $areaSize,
UI\Point $clipPoint,
UI\Size $clipSize
)

Shall be invoked when this Area requires redrawing

パラメータ

pen

A Pen suitable for drawing in this Area

areaSize

The size of the Area

clipPoint

The clip point of the Area

clipSize

The clip size of the Area


Key Callback

  • ≪ UI\Area::onDraw
  • UI\Area::onMouse ≫
  • PHP Manual
  • UI\Area
  • Key Callback

UI\Area::onKey

(UI 0.9.9)

UI\Area::onKey — Key Callback

説明

protected UI\Area::onKey(string $key, int $ext, int $flags)

Shall be executed on key events

パラメータ

key

The key pressed

ext

The extended key pressed

flags

Event modifiers

戻り値


Mouse Callback

  • ≪ UI\Area::onKey
  • UI\Area::redraw ≫
  • PHP Manual
  • UI\Area
  • Mouse Callback

UI\Area::onMouse

(UI 0.9.9)

UI\Area::onMouse — Mouse Callback

説明

protected UI\Area::onMouse(UI\Point $areaPoint, UI\Size $areaSize, int $flags)

Shall be executed on mouse events

パラメータ

areaPoint

The co-ordinates of the event

areaSize

The size of the area of the event

flags

Event modifiers


Redraw Area

  • ≪ UI\Area::onMouse
  • UI\Area::scrollTo ≫
  • PHP Manual
  • UI\Area
  • Redraw Area

UI\Area::redraw

(UI 0.9.9)

UI\Area::redraw — Redraw Area

説明

public UI\Area::redraw()

Requests that this Area is redrawn

パラメータ

この関数にはパラメータはありません。

戻り値


Area Scroll

  • ≪ UI\Area::redraw
  • UI\Area::setSize ≫
  • PHP Manual
  • UI\Area
  • Area Scroll

UI\Area::scrollTo

(UI 0.9.9)

UI\Area::scrollTo — Area Scroll

説明

public UI\Area::scrollTo(UI\Point $point, UI\Size $size)

Scroll this Area

パラメータ

point

The point to scroll to

size

The size of the scroll pane


Set Size

  • ≪ UI\Area::scrollTo
  • UI\Executor ≫
  • PHP Manual
  • UI\Area
  • Set Size

UI\Area::setSize

(UI 0.9.9)

UI\Area::setSize — Set Size

説明

public UI\Area::setSize(UI\Size $size)

Sets the size of this Area

パラメータ

size

The new size


Execution Scheduler

(UI 2.0.0)

はじめに

This facility schedules repetitive execution of a callback, useful for animations and other such activities.

クラス概要

abstract class UI\Executor {
/* Constructor */
public __construct()
public __construct(int $microseconds)
public __construct(int $seconds, int $microseconds)
/* メソッド */
public kill(): void
abstract protected onExecute(): void
public setInterval(int $microseconds): bool
public setInterval(int $seconds, int $microseconds): bool
}

目次

  • UI\Executor::__construct — Construct a new Executor
  • UI\Executor::kill — Stop Executor
  • UI\Executor::onExecute — Execution Callback
  • UI\Executor::setInterval — Interval Manipulation


Construct a new Executor

  • ≪ UI\Executor
  • UI\Executor::kill ≫
  • PHP Manual
  • UI\Executor
  • Construct a new Executor

UI\Executor::__construct

(UI 2.0.0)

UI\Executor::__construct — Construct a new Executor

説明

public UI\Executor::__construct()
public UI\Executor::__construct(int $microseconds)
public UI\Executor::__construct(int $seconds, int $microseconds)

Shall construct an executor with the given interval, will not start executing until main loop is entered

パラメータ

seconds

Seconds between executions

microseconds

Microseconds between executions


Stop Executor

  • ≪ UI\Executor::__construct
  • UI\Executor::onExecute ≫
  • PHP Manual
  • UI\Executor
  • Stop Executor

UI\Executor::kill

(UI 2.0.0)

UI\Executor::kill — Stop Executor

説明

public UI\Executor::kill(): void

Shall stop an executor, the executor cannot be restarted

パラメータ

この関数にはパラメータはありません。

戻り値


Execution Callback

  • ≪ UI\Executor::kill
  • UI\Executor::setInterval ≫
  • PHP Manual
  • UI\Executor
  • Execution Callback

UI\Executor::onExecute

(UI 2.0.0)

UI\Executor::onExecute — Execution Callback

説明

abstract protected UI\Executor::onExecute(): void

Shall be repetitively queued for execution in the main thread

パラメータ

この関数にはパラメータはありません。

戻り値


Interval Manipulation

  • ≪ UI\Executor::onExecute
  • UI\Controls\Tab ≫
  • PHP Manual
  • UI\Executor
  • Interval Manipulation

UI\Executor::setInterval

(UI 2.0.0)

UI\Executor::setInterval — Interval Manipulation

説明

public UI\Executor::setInterval(int $microseconds): bool
public UI\Executor::setInterval(int $seconds, int $microseconds): bool

Shall set the new interval. An interval of 0 will pause the executor until a new interval has been set

パラメータ

seconds

microseconds

戻り値

Indication of success


Tab Control

(UI 0.9.9)

はじめに

A Tab can contain many pages of Controls, each with a title, each selectable by the user.

クラス概要

class UI\Controls\Tab extends UI\Control {
/* プロパティ */
protected $controls;
/* メソッド */
public append(string $name, UI\Control $control): int
public delete(int $index): bool
public hasMargin(int $page): bool
public insertAt(string $name, int $page, UI\Control $control)
public pages(): int
public setMargin(int $page, bool $margin)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

プロパティ

controls

Contains controls, should not be manipulated directly

目次

  • UI\Controls\Tab::append — Append Page
  • UI\Controls\Tab::delete — Delete Page
  • UI\Controls\Tab::hasMargin — Margin Detection
  • UI\Controls\Tab::insertAt — Insert Page
  • UI\Controls\Tab::pages — Page Count
  • UI\Controls\Tab::setMargin — Set Margin


Append Page

  • ≪ UI\Controls\Tab
  • UI\Controls\Tab::delete ≫
  • PHP Manual
  • UI\Controls\Tab
  • Append Page

UI\Controls\Tab::append

(UI 0.9.9)

UI\Controls\Tab::append — Append Page

説明

public UI\Controls\Tab::append(string $name, UI\Control $control): int

Append a new page to this Tab

パラメータ

name

The name for the new page

control

The control for the new page

戻り値

Shall return the index of the appended control, may be 0


Delete Page

  • ≪ UI\Controls\Tab::append
  • UI\Controls\Tab::hasMargin ≫
  • PHP Manual
  • UI\Controls\Tab
  • Delete Page

UI\Controls\Tab::delete

(UI 0.9.9)

UI\Controls\Tab::delete — Delete Page

説明

public UI\Controls\Tab::delete(int $index): bool

Shall remove the selected page from this Tab

パラメータ

index

The index of the page to remove

戻り値

Indication of success


Margin Detection

  • ≪ UI\Controls\Tab::delete
  • UI\Controls\Tab::insertAt ≫
  • PHP Manual
  • UI\Controls\Tab
  • Margin Detection

UI\Controls\Tab::hasMargin

(UI 0.9.9)

UI\Controls\Tab::hasMargin — Margin Detection

説明

public UI\Controls\Tab::hasMargin(int $page): bool

Shall detect if the given page has a margin.

パラメータ

page

The index of the page

戻り値


Insert Page

  • ≪ UI\Controls\Tab::hasMargin
  • UI\Controls\Tab::pages ≫
  • PHP Manual
  • UI\Controls\Tab
  • Insert Page

UI\Controls\Tab::insertAt

(UI 0.9.9)

UI\Controls\Tab::insertAt — Insert Page

説明

public UI\Controls\Tab::insertAt(string $name, int $page, UI\Control $control)

Shall insert a new page into this Tab

パラメータ

name

The name for the new page

page

The index to perform the insertion before

control

The control for the new page


Page Count

  • ≪ UI\Controls\Tab::insertAt
  • UI\Controls\Tab::setMargin ≫
  • PHP Manual
  • UI\Controls\Tab
  • Page Count

UI\Controls\Tab::pages

(UI 0.9.9)

UI\Controls\Tab::pages — Page Count

説明

public UI\Controls\Tab::pages(): int

Shall return the number of pages in this Tab

パラメータ

この関数にはパラメータはありません。

戻り値

The number of pages in this Tab


Set Margin

  • ≪ UI\Controls\Tab::pages
  • UI\Controls\Check ≫
  • PHP Manual
  • UI\Controls\Tab
  • Set Margin

UI\Controls\Tab::setMargin

(UI 0.9.9)

UI\Controls\Tab::setMargin — Set Margin

説明

public UI\Controls\Tab::setMargin(int $page, bool $margin)

Shall enable or disable margins on the selected page

パラメータ

page

The page to select

margin

Margin switch


Check Control

(UI 0.9.9)

はじめに

A Check is a labelled checkable box

クラス概要

class UI\Controls\Check extends UI\Control {
/* Constructor */
public __construct(string $text)
/* メソッド */
public getText(): string
public isChecked(): bool
protected onToggle()
public setChecked(bool $checked)
public setText(string $text)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Check::__construct — Construct a new Check
  • UI\Controls\Check::getText — Get Text
  • UI\Controls\Check::isChecked — Checked Detection
  • UI\Controls\Check::onToggle — Toggle Callback
  • UI\Controls\Check::setChecked — Set Checked
  • UI\Controls\Check::setText — Set Text


Construct a new Check

  • ≪ UI\Controls\Check
  • UI\Controls\Check::getText ≫
  • PHP Manual
  • UI\Controls\Check
  • Construct a new Check

UI\Controls\Check::__construct

(UI 0.9.9)

UI\Controls\Check::__construct — Construct a new Check

説明

public UI\Controls\Check::__construct(string $text)

Shall construct a new Check

パラメータ

text

The text (label) for the Check box


Get Text

  • ≪ UI\Controls\Check::__construct
  • UI\Controls\Check::isChecked ≫
  • PHP Manual
  • UI\Controls\Check
  • Get Text

UI\Controls\Check::getText

(UI 0.9.9)

UI\Controls\Check::getText — Get Text

説明

public UI\Controls\Check::getText(): string

Shall return the text (label) for this Check

パラメータ

この関数にはパラメータはありません。

戻り値

The current text (label)


Checked Detection

  • ≪ UI\Controls\Check::getText
  • UI\Controls\Check::onToggle ≫
  • PHP Manual
  • UI\Controls\Check
  • Checked Detection

UI\Controls\Check::isChecked

(UI 0.9.9)

UI\Controls\Check::isChecked — Checked Detection

説明

public UI\Controls\Check::isChecked(): bool

Shall detect the status of this Check

パラメータ

この関数にはパラメータはありません。


Toggle Callback

  • ≪ UI\Controls\Check::isChecked
  • UI\Controls\Check::setChecked ≫
  • PHP Manual
  • UI\Controls\Check
  • Toggle Callback

UI\Controls\Check::onToggle

(UI 0.9.9)

UI\Controls\Check::onToggle — Toggle Callback

説明

protected UI\Controls\Check::onToggle()

Shall be executed when the status of this Check is changed

パラメータ

この関数にはパラメータはありません。


Set Checked

  • ≪ UI\Controls\Check::onToggle
  • UI\Controls\Check::setText ≫
  • PHP Manual
  • UI\Controls\Check
  • Set Checked

UI\Controls\Check::setChecked

(UI 0.9.9)

UI\Controls\Check::setChecked — Set Checked

説明

public UI\Controls\Check::setChecked(bool $checked)

Shall change the status of this Check

パラメータ

checked

The new status


Set Text

  • ≪ UI\Controls\Check::setChecked
  • UI\Controls\Button ≫
  • PHP Manual
  • UI\Controls\Check
  • Set Text

UI\Controls\Check::setText

(UI 0.9.9)

UI\Controls\Check::setText — Set Text

説明

public UI\Controls\Check::setText(string $text)

Shall set the text (label) for this Check

パラメータ

text

The new text (label)


Button Control

(UI 0.9.9)

はじめに

Represents a labelled clickable button

クラス概要

class UI\Controls\Button extends UI\Control {
/* Constructor */
public __construct(string $text)
/* メソッド */
public getText(): string
protected onClick()
public setText(string $text)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Button::__construct — Construct a new Button
  • UI\Controls\Button::getText — Get Text
  • UI\Controls\Button::onClick — Click Handler
  • UI\Controls\Button::setText — Set Text


Construct a new Button

  • ≪ UI\Controls\Button
  • UI\Controls\Button::getText ≫
  • PHP Manual
  • UI\Controls\Button
  • Construct a new Button

UI\Controls\Button::__construct

(UI 0.9.9)

UI\Controls\Button::__construct — Construct a new Button

説明

public UI\Controls\Button::__construct(string $text)

Shall construct a new Button

パラメータ

text

The text (label) for this Button


Get Text

  • ≪ UI\Controls\Button::__construct
  • UI\Controls\Button::onClick ≫
  • PHP Manual
  • UI\Controls\Button
  • Get Text

UI\Controls\Button::getText

(UI 0.9.9)

UI\Controls\Button::getText — Get Text

説明

public UI\Controls\Button::getText(): string

Shall retrieve the text (label) for this Button

パラメータ

この関数にはパラメータはありません。

戻り値

The current text (label)


Click Handler

  • ≪ UI\Controls\Button::getText
  • UI\Controls\Button::setText ≫
  • PHP Manual
  • UI\Controls\Button
  • Click Handler

UI\Controls\Button::onClick

(UI 0.9.9)

UI\Controls\Button::onClick — Click Handler

説明

protected UI\Controls\Button::onClick()

Shall be executed when this Button is clicked

パラメータ

この関数にはパラメータはありません。


Set Text

  • ≪ UI\Controls\Button::onClick
  • UI\Controls\ColorButton ≫
  • PHP Manual
  • UI\Controls\Button
  • Set Text

UI\Controls\Button::setText

(UI 0.9.9)

UI\Controls\Button::setText — Set Text

説明

public UI\Controls\Button::setText(string $text)

Shall set the text (label) for this Button

パラメータ

text

The new text (label)


ColorButton Control

(UI 0.9.9)

はじめに

A Color Button is a button which displays a color picker when clicked

クラス概要

class UI\Controls\ColorButton extends UI\Control {
/* メソッド */
public getColor(): UI\Color
protected onChange()
public setColor(UI\Draw\Color $color)
public setColor(int $color)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\ColorButton::getColor — Get Color
  • UI\Controls\ColorButton::onChange — Change Handler
  • UI\Controls\ColorButton::setColor — Set Color


Get Color

  • ≪ UI\Controls\ColorButton
  • UI\Controls\ColorButton::onChange ≫
  • PHP Manual
  • UI\Controls\ColorButton
  • Get Color

UI\Controls\ColorButton::getColor

(UI 0.9.9)

UI\Controls\ColorButton::getColor — Get Color

説明

public UI\Controls\ColorButton::getColor(): UI\Color

Shall retrieve the currently selected Color

パラメータ

この関数にはパラメータはありません。

戻り値


Change Handler

  • ≪ UI\Controls\ColorButton::getColor
  • UI\Controls\ColorButton::setColor ≫
  • PHP Manual
  • UI\Controls\ColorButton
  • Change Handler

UI\Controls\ColorButton::onChange

(UI 0.9.9)

UI\Controls\ColorButton::onChange — Change Handler

説明

protected UI\Controls\ColorButton::onChange()

Shall be executed when the selected Color is changed

パラメータ

この関数にはパラメータはありません。


Set Color

  • ≪ UI\Controls\ColorButton::onChange
  • UI\Controls\Label ≫
  • PHP Manual
  • UI\Controls\ColorButton
  • Set Color

UI\Controls\ColorButton::setColor

(UI 0.9.9)

UI\Controls\ColorButton::setColor — Set Color

説明

public UI\Controls\ColorButton::setColor(UI\Draw\Color $color)
public UI\Controls\ColorButton::setColor(int $color)

Shall set the currently selected Color

パラメータ

color

The new color


Label Control

(UI 0.9.9)

はじめに

A Label is a single line of text, meant to identify, for the user, some element of the interface.

クラス概要

class UI\Controls\Label extends UI\Control {
/* Constructor */
public __construct(string $text)
/* メソッド */
public getText(): string
public setText(string $text)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Label::__construct — Construct a new Label
  • UI\Controls\Label::getText — Get Text
  • UI\Controls\Label::setText — Set Text


Construct a new Label

  • ≪ UI\Controls\Label
  • UI\Controls\Label::getText ≫
  • PHP Manual
  • UI\Controls\Label
  • Construct a new Label

UI\Controls\Label::__construct

(UI 0.9.9)

UI\Controls\Label::__construct — Construct a new Label

説明

public UI\Controls\Label::__construct(string $text)

Shall construct a new Label

パラメータ

text

The text for this label


Get Text

  • ≪ UI\Controls\Label::__construct
  • UI\Controls\Label::setText ≫
  • PHP Manual
  • UI\Controls\Label
  • Get Text

UI\Controls\Label::getText

(UI 0.9.9)

UI\Controls\Label::getText — Get Text

説明

public UI\Controls\Label::getText(): string

Shall return the current text for this Label

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

戻り値


Set Text

  • ≪ UI\Controls\Label::getText
  • UI\Controls\Entry ≫
  • PHP Manual
  • UI\Controls\Label
  • Set Text

UI\Controls\Label::setText

(UI 0.9.9)

UI\Controls\Label::setText — Set Text

説明

public UI\Controls\Label::setText(string $text)

Shall set the text for this Label

パラメータ

text

The new text


Entry Control

(UI 0.9.9)

はじめに

An Entry is a text entry control, suitable for entering plain text, passwords, or search terms.

クラス概要

class UI\Controls\Entry extends UI\Control {
/* 定数 */
const int Normal;
const int Password;
const int Search;
/* Constructor */
public __construct(int $type = UI\Controls\Entry::Normal)
/* メソッド */
public getText(): string
public isReadOnly(): bool
protected onChange()
public setReadOnly(bool $readOnly)
public setText(string $text)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

定義済み定数

UI\Controls\Entry::Normal

A normal single line entry

UI\Controls\Entry::Password

A password entry

UI\Controls\Entry::Search

A search entry

目次

  • UI\Controls\Entry::__construct — Construct a new Entry
  • UI\Controls\Entry::getText — Get Text
  • UI\Controls\Entry::isReadOnly — Detect Read Only
  • UI\Controls\Entry::onChange — Change Handler
  • UI\Controls\Entry::setReadOnly — Set Read Only
  • UI\Controls\Entry::setText — Set Text


Construct a new Entry

  • ≪ UI\Controls\Entry
  • UI\Controls\Entry::getText ≫
  • PHP Manual
  • UI\Controls\Entry
  • Construct a new Entry

UI\Controls\Entry::__construct

(UI 0.9.9)

UI\Controls\Entry::__construct — Construct a new Entry

説明

public UI\Controls\Entry::__construct(int $type = UI\Controls\Entry::Normal)

Construct a new entry of the given type

パラメータ

type

Entry::Normal, Entry::Password, or Entry::Search


Get Text

  • ≪ UI\Controls\Entry::__construct
  • UI\Controls\Entry::isReadOnly ≫
  • PHP Manual
  • UI\Controls\Entry
  • Get Text

UI\Controls\Entry::getText

(UI 0.9.9)

UI\Controls\Entry::getText — Get Text

説明

public UI\Controls\Entry::getText(): string

Shall return the current text from this Entry

パラメータ

この関数にはパラメータはありません。

戻り値

The current text


Detect Read Only

  • ≪ UI\Controls\Entry::getText
  • UI\Controls\Entry::onChange ≫
  • PHP Manual
  • UI\Controls\Entry
  • Detect Read Only

UI\Controls\Entry::isReadOnly

(UI 0.9.9)

UI\Controls\Entry::isReadOnly — Detect Read Only

説明

public UI\Controls\Entry::isReadOnly(): bool

Shall detect if this Entry is read only

パラメータ

この関数にはパラメータはありません。

戻り値


Change Handler

  • ≪ UI\Controls\Entry::isReadOnly
  • UI\Controls\Entry::setReadOnly ≫
  • PHP Manual
  • UI\Controls\Entry
  • Change Handler

UI\Controls\Entry::onChange

(UI 0.9.9)

UI\Controls\Entry::onChange — Change Handler

説明

protected UI\Controls\Entry::onChange()

Shall be executed when the text in this Entry changes

パラメータ

この関数にはパラメータはありません。


Set Read Only

  • ≪ UI\Controls\Entry::onChange
  • UI\Controls\Entry::setText ≫
  • PHP Manual
  • UI\Controls\Entry
  • Set Read Only

UI\Controls\Entry::setReadOnly

(UI 0.9.9)

UI\Controls\Entry::setReadOnly — Set Read Only

説明

public UI\Controls\Entry::setReadOnly(bool $readOnly)

Shall enable or disable read only for this Entry

パラメータ

readOnly


Set Text

  • ≪ UI\Controls\Entry::setReadOnly
  • UI\Controls\MultilineEntry ≫
  • PHP Manual
  • UI\Controls\Entry
  • Set Text

UI\Controls\Entry::setText

(UI 0.9.9)

UI\Controls\Entry::setText — Set Text

説明

public UI\Controls\Entry::setText(string $text)

Shall set the text for this Entry

パラメータ

text

The new text


MultilineEntry Control

(UI 0.9.9)

はじめに

A Multiline Entry is a text entry control able to hold multiple lines of text, with or without wrapping.

クラス概要

class UI\Controls\MultilineEntry extends UI\Control {
/* 定数 */
const int Wrap;
const int NoWrap;
/* Constructor */
public __construct(int $type = ?)
/* メソッド */
public append(string $text)
public getText(): string
public isReadOnly(): bool
protected onChange()
public setReadOnly(bool $readOnly)
public setText(string $text)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

定義済み定数

UI\Controls\MultilineEntry::Wrap

Allow lines to wrap

UI\Controls\MultilineEntry::NoWrap

Do not allow lines to wrap

目次

  • UI\Controls\MultilineEntry::append — Append Text
  • UI\Controls\MultilineEntry::__construct — Construct a new Multiline Entry
  • UI\Controls\MultilineEntry::getText — Get Text
  • UI\Controls\MultilineEntry::isReadOnly — Read Only Detection
  • UI\Controls\MultilineEntry::onChange — Change Handler
  • UI\Controls\MultilineEntry::setReadOnly — Set Read Only
  • UI\Controls\MultilineEntry::setText — Set Text


Append Text

  • ≪ UI\Controls\MultilineEntry
  • UI\Controls\MultilineEntry::__construct ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Append Text

UI\Controls\MultilineEntry::append

(UI 0.9.9)

UI\Controls\MultilineEntry::append — Append Text

説明

public UI\Controls\MultilineEntry::append(string $text)

Shall append the given text to the text in this Multiline Entry

パラメータ

text

The text to append


Construct a new Multiline Entry

  • ≪ UI\Controls\MultilineEntry::append
  • UI\Controls\MultilineEntry::getText ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Construct a new Multiline Entry

UI\Controls\MultilineEntry::__construct

(UI 0.9.9)

UI\Controls\MultilineEntry::__construct — Construct a new Multiline Entry

説明

public UI\Controls\MultilineEntry::__construct(int $type = ?)

Shall construct a new Multiline Entry of the given type

パラメータ

type

MultilineEntry::Wrap or MultilineEntry::NoWrap


Get Text

  • ≪ UI\Controls\MultilineEntry::__construct
  • UI\Controls\MultilineEntry::isReadOnly ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Get Text

UI\Controls\MultilineEntry::getText

(UI 0.9.9)

UI\Controls\MultilineEntry::getText — Get Text

説明

public UI\Controls\MultilineEntry::getText(): string

Shall return the text in this Multiline Entry

パラメータ

この関数にはパラメータはありません。


Read Only Detection

  • ≪ UI\Controls\MultilineEntry::getText
  • UI\Controls\MultilineEntry::onChange ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Read Only Detection

UI\Controls\MultilineEntry::isReadOnly

(UI 0.9.9)

UI\Controls\MultilineEntry::isReadOnly — Read Only Detection

説明

public UI\Controls\MultilineEntry::isReadOnly(): bool

Shall detect if this Multiline Entry is read only

パラメータ

この関数にはパラメータはありません。


Change Handler

  • ≪ UI\Controls\MultilineEntry::isReadOnly
  • UI\Controls\MultilineEntry::setReadOnly ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Change Handler

UI\Controls\MultilineEntry::onChange

(UI 0.9.9)

UI\Controls\MultilineEntry::onChange — Change Handler

説明

protected UI\Controls\MultilineEntry::onChange()

Shall be executed when the text in this Multiline Entry is changed

パラメータ

この関数にはパラメータはありません。


Set Read Only

  • ≪ UI\Controls\MultilineEntry::onChange
  • UI\Controls\MultilineEntry::setText ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Set Read Only

UI\Controls\MultilineEntry::setReadOnly

(UI 0.9.9)

UI\Controls\MultilineEntry::setReadOnly — Set Read Only

説明

public UI\Controls\MultilineEntry::setReadOnly(bool $readOnly)

Shall enable or disable read only on this Multiline Entry

パラメータ

readOnly


Set Text

  • ≪ UI\Controls\MultilineEntry::setReadOnly
  • UI\Controls\Spin ≫
  • PHP Manual
  • UI\Controls\MultilineEntry
  • Set Text

UI\Controls\MultilineEntry::setText

(UI 0.9.9)

UI\Controls\MultilineEntry::setText — Set Text

説明

public UI\Controls\MultilineEntry::setText(string $text)

Shall set the text in this Multiline Entry

パラメータ

text

The new text


Spin Control

(UI 0.9.9)

はじめに

A Spin box is a text box with an up-down control which changes the integer value in the box, within a defined range

クラス概要

class UI\Controls\Spin extends UI\Control {
/* Constructor */
public __construct(int $min, int $max)
/* メソッド */
public getValue(): int
protected onChange()
public setValue(int $value)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Spin::__construct — Construct a new Spin
  • UI\Controls\Spin::getValue — Get Value
  • UI\Controls\Spin::onChange — Change Handler
  • UI\Controls\Spin::setValue — Set Value


Construct a new Spin

  • ≪ UI\Controls\Spin
  • UI\Controls\Spin::getValue ≫
  • PHP Manual
  • UI\Controls\Spin
  • Construct a new Spin

UI\Controls\Spin::__construct

(UI 0.9.9)

UI\Controls\Spin::__construct — Construct a new Spin

説明

public UI\Controls\Spin::__construct(int $min, int $max)

Constructs a new Spin with the given range

パラメータ

min

The minimum value allowed

max

The maximum value allowed


Get Value

  • ≪ UI\Controls\Spin::__construct
  • UI\Controls\Spin::onChange ≫
  • PHP Manual
  • UI\Controls\Spin
  • Get Value

UI\Controls\Spin::getValue

(UI 0.9.9)

UI\Controls\Spin::getValue — Get Value

説明

public UI\Controls\Spin::getValue(): int

Get the value in this Spin

パラメータ

この関数にはパラメータはありません。


Change Handler

  • ≪ UI\Controls\Spin::getValue
  • UI\Controls\Spin::setValue ≫
  • PHP Manual
  • UI\Controls\Spin
  • Change Handler

UI\Controls\Spin::onChange

(UI 0.9.9)

UI\Controls\Spin::onChange — Change Handler

説明

protected UI\Controls\Spin::onChange()

Shall be executed when the value in this Spin changes

パラメータ

この関数にはパラメータはありません。


Set Value

  • ≪ UI\Controls\Spin::onChange
  • UI\Controls\Slider ≫
  • PHP Manual
  • UI\Controls\Spin
  • Set Value

UI\Controls\Spin::setValue

(UI 0.9.9)

UI\Controls\Spin::setValue — Set Value

説明

public UI\Controls\Spin::setValue(int $value)

Set the value in this Spin

パラメータ

value

The new value


Slider Control

(UI 0.9.9)

はじめに

A Slider is a control which represents a range, and a current value in the range. The sliding element of the control (sometimes called the "thumb") reflects the value, and can be adjusted within the range.

クラス概要

class UI\Controls\Slider extends UI\Control {
/* Constructor */
public __construct(int $min, int $max)
/* メソッド */
public getValue(): int
protected onChange()
public setValue(int $value)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Slider::__construct — Construct a new Slider
  • UI\Controls\Slider::getValue — Get Value
  • UI\Controls\Slider::onChange — Change Handler
  • UI\Controls\Slider::setValue — Set Value


Construct a new Slider

  • ≪ UI\Controls\Slider
  • UI\Controls\Slider::getValue ≫
  • PHP Manual
  • UI\Controls\Slider
  • Construct a new Slider

UI\Controls\Slider::__construct

(UI 0.9.9)

UI\Controls\Slider::__construct — Construct a new Slider

説明

public UI\Controls\Slider::__construct(int $min, int $max)

Construct a new Slider with the given range

パラメータ

min

The minimum allowed value

max

The maximum allowed value


Get Value

  • ≪ UI\Controls\Slider::__construct
  • UI\Controls\Slider::onChange ≫
  • PHP Manual
  • UI\Controls\Slider
  • Get Value

UI\Controls\Slider::getValue

(UI 0.9.9)

UI\Controls\Slider::getValue — Get Value

説明

public UI\Controls\Slider::getValue(): int

Get the value from this Slider

パラメータ

この関数にはパラメータはありません。


Change Handler

  • ≪ UI\Controls\Slider::getValue
  • UI\Controls\Slider::setValue ≫
  • PHP Manual
  • UI\Controls\Slider
  • Change Handler

UI\Controls\Slider::onChange

(UI 0.9.9)

UI\Controls\Slider::onChange — Change Handler

説明

protected UI\Controls\Slider::onChange()

Shall be executed when the value of this Slider changes

パラメータ

この関数にはパラメータはありません。


Set Value

  • ≪ UI\Controls\Slider::onChange
  • UI\Controls\Progress ≫
  • PHP Manual
  • UI\Controls\Slider
  • Set Value

UI\Controls\Slider::setValue

(UI 0.9.9)

UI\Controls\Slider::setValue — Set Value

説明

public UI\Controls\Slider::setValue(int $value)

Shall set the value for this Slider

パラメータ

value

The new value


Progress Control

(UI 0.9.9)

はじめに

A Progress control is a familiar Progress bar: It represents progress as a percentage, with a possible range of 0 to 100 (inclusive).

クラス概要

class UI\Controls\Progress extends UI\Control {
/* メソッド */
public getValue(): int
public setValue(int $value)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Progress::getValue — Get Value
  • UI\Controls\Progress::setValue — Set Value


Get Value

  • ≪ UI\Controls\Progress
  • UI\Controls\Progress::setValue ≫
  • PHP Manual
  • UI\Controls\Progress
  • Get Value

UI\Controls\Progress::getValue

(UI 0.9.9)

UI\Controls\Progress::getValue — Get Value

説明

public UI\Controls\Progress::getValue(): int

Shall retrieve the current value of this Progress bar

パラメータ

この関数にはパラメータはありません。


Set Value

  • ≪ UI\Controls\Progress::getValue
  • UI\Controls\Separator ≫
  • PHP Manual
  • UI\Controls\Progress
  • Set Value

UI\Controls\Progress::setValue

(UI 0.9.9)

UI\Controls\Progress::setValue — Set Value

説明

public UI\Controls\Progress::setValue(int $value)

Shall set the value for this Progress bar

パラメータ

value

An integer between 0 and 100 (inclusive)


Control Separator

(UI 0.9.9)

はじめに

A Separator represents a control separator, it has no other function.

クラス概要

class UI\Controls\Separator extends UI\Control {
/* 定数 */
const int Horizontal;
const int Vertical;
/* Constructor */
public __construct(int $type = UI\Controls\Separator::Horizontal)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

定義済み定数

UI\Controls\Separator::Horizontal

A Horizontal Separator

UI\Controls\Separator::Vertical

A Vertical Separator

目次

  • UI\Controls\Separator::__construct — Construct a new Separator


Construct a new Separator

  • ≪ UI\Controls\Separator
  • UI\Controls\Combo ≫
  • PHP Manual
  • UI\Controls\Separator
  • Construct a new Separator

UI\Controls\Separator::__construct

(UI 0.9.9)

UI\Controls\Separator::__construct — Construct a new Separator

説明

public UI\Controls\Separator::__construct(int $type = UI\Controls\Separator::Horizontal)

Shall construct a new Separator of the given type

パラメータ

type

Separator::Horizonal or Separator::Vertical


Combo Control

(UI 0.9.9)

はじめに

A Combo control represents a list of options, like the familiar select HTML element.

クラス概要

class UI\Controls\Combo extends UI\Control {
/* メソッド */
public append(string $text)
public getSelected(): int
protected onSelected()
public setSelected(int $index)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Combo::append — Append Option
  • UI\Controls\Combo::getSelected — Get Selected Option
  • UI\Controls\Combo::onSelected — Selected Handler
  • UI\Controls\Combo::setSelected — Set Selected Option


Append Option

  • ≪ UI\Controls\Combo
  • UI\Controls\Combo::getSelected ≫
  • PHP Manual
  • UI\Controls\Combo
  • Append Option

UI\Controls\Combo::append

(UI 0.9.9)

UI\Controls\Combo::append — Append Option

説明

public UI\Controls\Combo::append(string $text)

Append an option to this Combo

パラメータ

text

The text for the new option


Get Selected Option

  • ≪ UI\Controls\Combo::append
  • UI\Controls\Combo::onSelected ≫
  • PHP Manual
  • UI\Controls\Combo
  • Get Selected Option

UI\Controls\Combo::getSelected

(UI 0.9.9)

UI\Controls\Combo::getSelected — Get Selected Option

説明

public UI\Controls\Combo::getSelected(): int

Shall retrieve the index of the option selected in this Combo

パラメータ

この関数にはパラメータはありません。


Selected Handler

  • ≪ UI\Controls\Combo::getSelected
  • UI\Controls\Combo::setSelected ≫
  • PHP Manual
  • UI\Controls\Combo
  • Selected Handler

UI\Controls\Combo::onSelected

(UI 0.9.9)

UI\Controls\Combo::onSelected — Selected Handler

説明

protected UI\Controls\Combo::onSelected()

Shall be executed when an option is selected in this Combo

パラメータ

この関数にはパラメータはありません。


Set Selected Option

  • ≪ UI\Controls\Combo::onSelected
  • UI\Controls\EditableCombo ≫
  • PHP Manual
  • UI\Controls\Combo
  • Set Selected Option

UI\Controls\Combo::setSelected

(UI 0.9.9)

UI\Controls\Combo::setSelected — Set Selected Option

説明

public UI\Controls\Combo::setSelected(int $index)

Shall set the currently selected option in this Combo

パラメータ

index

The index of the option to select


EdiableCombo Control

(UI 0.9.9)

はじめに

An Editable Combo is a Combo which allows the user to enter custom options

クラス概要

class UI\Controls\EditableCombo extends UI\Control {
/* メソッド */
public append(string $text)
public getText(): string
protected onChange()
public setText(string $text)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\EditableCombo::append — Append Option
  • UI\Controls\EditableCombo::getText — Get Text
  • UI\Controls\EditableCombo::onChange — Change Handler
  • UI\Controls\EditableCombo::setText — Set Text


Append Option

  • ≪ UI\Controls\EditableCombo
  • UI\Controls\EditableCombo::getText ≫
  • PHP Manual
  • UI\Controls\EditableCombo
  • Append Option

UI\Controls\EditableCombo::append

(UI 0.9.9)

UI\Controls\EditableCombo::append — Append Option

説明

public UI\Controls\EditableCombo::append(string $text)

Shall append a new option to this Editable Combo

パラメータ

text

The text for the new option


Get Text

  • ≪ UI\Controls\EditableCombo::append
  • UI\Controls\EditableCombo::onChange ≫
  • PHP Manual
  • UI\Controls\EditableCombo
  • Get Text

UI\Controls\EditableCombo::getText

(UI 0.9.9)

UI\Controls\EditableCombo::getText — Get Text

説明

public UI\Controls\EditableCombo::getText(): string

Get the value of the currently selected option in this Editable Combo

パラメータ

この関数にはパラメータはありません。


Change Handler

  • ≪ UI\Controls\EditableCombo::getText
  • UI\Controls\EditableCombo::setText ≫
  • PHP Manual
  • UI\Controls\EditableCombo
  • Change Handler

UI\Controls\EditableCombo::onChange

(UI 0.9.9)

UI\Controls\EditableCombo::onChange — Change Handler

説明

protected UI\Controls\EditableCombo::onChange()

Shall be executed when the value of this Editable Combobox changes

パラメータ

この関数にはパラメータはありません。


Set Text

  • ≪ UI\Controls\EditableCombo::onChange
  • UI\Controls\Radio ≫
  • PHP Manual
  • UI\Controls\EditableCombo
  • Set Text

UI\Controls\EditableCombo::setText

(UI 0.9.9)

UI\Controls\EditableCombo::setText — Set Text

説明

public UI\Controls\EditableCombo::setText(string $text)

Shall set the text of the currently selected option in this Editable Combo

パラメータ

text

The new text


Radio Control

(UI 0.9.9)

はじめに

A Radio is similar to the radio input type familiar from HTML

クラス概要

class UI\Controls\Radio extends UI\Control {
/* メソッド */
public append(string $text)
public getSelected(): int
protected onSelected()
public setSelected(int $index)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

目次

  • UI\Controls\Radio::append — Append Option
  • UI\Controls\Radio::getSelected — Get Selected Option
  • UI\Controls\Radio::onSelected — Selected Handler
  • UI\Controls\Radio::setSelected — Set Selected Option


Append Option

  • ≪ UI\Controls\Radio
  • UI\Controls\Radio::getSelected ≫
  • PHP Manual
  • UI\Controls\Radio
  • Append Option

UI\Controls\Radio::append

(UI 0.9.9)

UI\Controls\Radio::append — Append Option

説明

public UI\Controls\Radio::append(string $text)

Shall append a new option to this Radio

パラメータ

text

The text (label) for the option


Get Selected Option

  • ≪ UI\Controls\Radio::append
  • UI\Controls\Radio::onSelected ≫
  • PHP Manual
  • UI\Controls\Radio
  • Get Selected Option

UI\Controls\Radio::getSelected

(UI 0.9.9)

UI\Controls\Radio::getSelected — Get Selected Option

説明

public UI\Controls\Radio::getSelected(): int

Shall retrieve the index of the currently selected option in this Radio

パラメータ

この関数にはパラメータはありません。


Selected Handler

  • ≪ UI\Controls\Radio::getSelected
  • UI\Controls\Radio::setSelected ≫
  • PHP Manual
  • UI\Controls\Radio
  • Selected Handler

UI\Controls\Radio::onSelected

(UI 0.9.9)

UI\Controls\Radio::onSelected — Selected Handler

説明

protected UI\Controls\Radio::onSelected()

Shall be executed when the option selected in this Radio changes

パラメータ

この関数にはパラメータはありません。


Set Selected Option

  • ≪ UI\Controls\Radio::onSelected
  • UI\Controls\Picker ≫
  • PHP Manual
  • UI\Controls\Radio
  • Set Selected Option

UI\Controls\Radio::setSelected

(UI 0.9.9)

UI\Controls\Radio::setSelected — Set Selected Option

説明

public UI\Controls\Radio::setSelected(int $index)

Shall set the currently selected option in this Radio

パラメータ

index

The index of the option to select


Picker Control

(UI 0.9.9)

はじめに

A Picker represents a button which when clicked presents a native Date/Time/DateTime Picker interface to the user.

クラス概要

class UI\Controls\Picker extends UI\Control {
/* 定数 */
const int Date;
const int Time;
const int DateTime;
/* Constructor */
public __construct(int $type = UI\Controls\Picker::Date)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

定義済み定数

UI\Controls\Picker::Date

A Date Picker

UI\Controls\Picker::Time

A Time Picker

UI\Controls\Picker::DateTime

A Date and Time Picker

目次

  • UI\Controls\Picker::__construct — Construct a new Picker


Construct a new Picker

  • ≪ UI\Controls\Picker
  • UI\Controls\Form ≫
  • PHP Manual
  • UI\Controls\Picker
  • Construct a new Picker

UI\Controls\Picker::__construct

(UI 0.9.9)

UI\Controls\Picker::__construct — Construct a new Picker

説明

public UI\Controls\Picker::__construct(int $type = UI\Controls\Picker::Date)

Construct a new Picker of the given type

パラメータ

type

Picker::Date, Picker::Time, or Picker::DateTime


Control Form (Arrangement)

(UI 0.9.9)

はじめに

A Form is a control which allows the arrangement of other controls into a familiar layout (the form).

クラス概要

class UI\Controls\Form extends UI\Control {
/* プロパティ */
protected $controls;
/* メソッド */
public append(string $label, UI\Control $control, bool $stretchy = false): int
public delete(int $index): bool
public isPadded(): bool
public setPadded(bool $padded)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

プロパティ

controls

Contains controls, should not be manipulated directly

目次

  • UI\Controls\Form::append — Append Control
  • UI\Controls\Form::delete — Delete Control
  • UI\Controls\Form::isPadded — Padding Detection
  • UI\Controls\Form::setPadded — Set Padding


Append Control

  • ≪ UI\Controls\Form
  • UI\Controls\Form::delete ≫
  • PHP Manual
  • UI\Controls\Form
  • Append Control

UI\Controls\Form::append

(UI 0.9.9)

UI\Controls\Form::append — Append Control

説明

public UI\Controls\Form::append(string $label, UI\Control $control, bool $stretchy = false): int

Shall append the control to the form, and set the label

パラメータ

label

The text for the label

control

A control

stretchy

Should be set true to stretch the control

戻り値

Shall return the index of the appended control, may be 0


Delete Control

  • ≪ UI\Controls\Form::append
  • UI\Controls\Form::isPadded ≫
  • PHP Manual
  • UI\Controls\Form
  • Delete Control

UI\Controls\Form::delete

(UI 0.9.9)

UI\Controls\Form::delete — Delete Control

説明

public UI\Controls\Form::delete(int $index): bool

Shall delete the control at the given index in this Form

パラメータ

index

The index of the control to remove

戻り値

Indication of succcess


Padding Detection

  • ≪ UI\Controls\Form::delete
  • UI\Controls\Form::setPadded ≫
  • PHP Manual
  • UI\Controls\Form
  • Padding Detection

UI\Controls\Form::isPadded

(UI 0.9.9)

UI\Controls\Form::isPadded — Padding Detection

説明

public UI\Controls\Form::isPadded(): bool

Shall detect if padding is enabled on this Form

パラメータ

この関数にはパラメータはありません。


Set Padding

  • ≪ UI\Controls\Form::isPadded
  • UI\Controls\Grid ≫
  • PHP Manual
  • UI\Controls\Form
  • Set Padding

UI\Controls\Form::setPadded

(UI 0.9.9)

UI\Controls\Form::setPadded — Set Padding

説明

public UI\Controls\Form::setPadded(bool $padded)

Shall enable or disable padding on this Form

パラメータ

padded


Control Grid (Arrangement)

(UI 0.9.9)

はじめに

A Grid is a control which is allows the arrangement of children into a grid

クラス概要

class UI\Controls\Grid extends UI\Control {
/* 定数 */
const int Fill;
const int Start;
const int Center;
const int End;
const int Leading;
const int Top;
const int Trailing;
const int Bottom;
/* プロパティ */
protected $controls;
/* メソッド */
public append(
UI\Control $control,
int $left,
int $top,
int $xspan,
int $yspan,
bool $hexpand,
int $halign,
bool $vexpand,
int $valign
)
public isPadded(): bool
public setPadded(bool $padding)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

定義済み定数

UI\Controls\Grid::Fill

UI\Controls\Grid::Start

UI\Controls\Grid::Center

UI\Controls\Grid::End

UI\Controls\Grid::Leading

UI\Controls\Grid::Top

UI\Controls\Grid::Trailing

UI\Controls\Grid::Bottom

プロパティ

controls

Contains controls, should not be manipulated directly

目次

  • UI\Controls\Grid::append — Append Control
  • UI\Controls\Grid::isPadded — Padding Detection
  • UI\Controls\Grid::setPadded — Set Padding


Append Control

  • ≪ UI\Controls\Grid
  • UI\Controls\Grid::isPadded ≫
  • PHP Manual
  • UI\Controls\Grid
  • Append Control

UI\Controls\Grid::append

(UI 0.9.9)

UI\Controls\Grid::append — Append Control

説明

public UI\Controls\Grid::append(
UI\Control $control,
int $left,
int $top,
int $xspan,
int $yspan,
bool $hexpand,
int $halign,
bool $vexpand,
int $valign
)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

control

The Control to append

left

top

xspan

yspan

hexpand

halign

vexpand

valign

戻り値


Padding Detection

  • ≪ UI\Controls\Grid::append
  • UI\Controls\Grid::setPadded ≫
  • PHP Manual
  • UI\Controls\Grid
  • Padding Detection

UI\Controls\Grid::isPadded

(UI 0.9.9)

UI\Controls\Grid::isPadded — Padding Detection

説明

public UI\Controls\Grid::isPadded(): bool

Shall detect if padding is enabled on this Grid

パラメータ

この関数にはパラメータはありません。


Set Padding

  • ≪ UI\Controls\Grid::isPadded
  • UI\Controls\Group ≫
  • PHP Manual
  • UI\Controls\Grid
  • Set Padding

UI\Controls\Grid::setPadded

(UI 0.9.9)

UI\Controls\Grid::setPadded — Set Padding

説明

public UI\Controls\Grid::setPadded(bool $padding)

Shall enable or disable padding for this Grid

パラメータ

padding


Control Group (Arrangement)

(UI 0.9.9)

はじめに

A Group is a titled container for child controls

クラス概要

class UI\Controls\Group extends UI\Control {
/* プロパティ */
protected $controls;
/* Constructor */
public __construct(string $title)
/* メソッド */
public append(UI\Control $control)
public getTitle(): string
public hasMargin(): bool
public setMargin(bool $margin)
public setTitle(string $title)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

プロパティ

controls

Contains controls, should not be manipulated directly

目次

  • UI\Controls\Group::append — Append Control
  • UI\Controls\Group::__construct — Construct a new Group
  • UI\Controls\Group::getTitle — Get Title
  • UI\Controls\Group::hasMargin — Margin Detection
  • UI\Controls\Group::setMargin — Set Margin
  • UI\Controls\Group::setTitle — Set Title


Append Control

  • ≪ UI\Controls\Group
  • UI\Controls\Group::__construct ≫
  • PHP Manual
  • UI\Controls\Group
  • Append Control

UI\Controls\Group::append

(バージョン情報なし。おそらく Git 版にしか存在しないでしょう)

UI\Controls\Group::append — Append Control

説明

public UI\Controls\Group::append(UI\Control $control)

Shall append a control to this Group

パラメータ

control

The control to append


Construct a new Group

  • ≪ UI\Controls\Group::append
  • UI\Controls\Group::getTitle ≫
  • PHP Manual
  • UI\Controls\Group
  • Construct a new Group

UI\Controls\Group::__construct

(UI 0.9.9)

UI\Controls\Group::__construct — Construct a new Group

説明

public UI\Controls\Group::__construct(string $title)

Shall construct a new Group with the given title

パラメータ

title

The text for the title label


Get Title

  • ≪ UI\Controls\Group::__construct
  • UI\Controls\Group::hasMargin ≫
  • PHP Manual
  • UI\Controls\Group
  • Get Title

UI\Controls\Group::getTitle

(UI 0.9.9)

UI\Controls\Group::getTitle — Get Title

説明

public UI\Controls\Group::getTitle(): string

Shall return the current title for this Group

パラメータ

この関数にはパラメータはありません。

戻り値

The current title


Margin Detection

  • ≪ UI\Controls\Group::getTitle
  • UI\Controls\Group::setMargin ≫
  • PHP Manual
  • UI\Controls\Group
  • Margin Detection

UI\Controls\Group::hasMargin

(UI 0.9.9)

UI\Controls\Group::hasMargin — Margin Detection

説明

public UI\Controls\Group::hasMargin(): bool

Shall detect if this Group has a margin

パラメータ

この関数にはパラメータはありません。


Set Margin

  • ≪ UI\Controls\Group::hasMargin
  • UI\Controls\Group::setTitle ≫
  • PHP Manual
  • UI\Controls\Group
  • Set Margin

UI\Controls\Group::setMargin

(UI 0.9.9)

UI\Controls\Group::setMargin — Set Margin

説明

public UI\Controls\Group::setMargin(bool $margin)

Shall enable or disable margins for this Group

パラメータ

margin


Set Title

  • ≪ UI\Controls\Group::setMargin
  • UI\Controls\Box ≫
  • PHP Manual
  • UI\Controls\Group
  • Set Title

UI\Controls\Group::setTitle

(UI 0.9.9)

UI\Controls\Group::setTitle — Set Title

説明

public UI\Controls\Group::setTitle(string $title)

Shall set the title for this Group

パラメータ

title

The text for the new title


Control Box (Arrangement)

(UI 0.9.9)

はじめに

A Box allows the arrangement of other controls

クラス概要

class UI\Controls\Box extends UI\Control {
/* 定数 */
const int Vertical;
const int Horizontal;
/* プロパティ */
protected $controls;
/* Constructor */
public __construct(int $orientation = UI\Controls\Box::Horizontal)
/* メソッド */
public append(Control $control, bool $stretchy = false): int
public delete(int $index): bool
public getOrientation(): int
public isPadded(): bool
public setPadded(bool $padded)
/* 継承したメソッド */
public UI\Control::destroy()
public UI\Control::disable()
public UI\Control::enable()
public UI\Control::getParent(): UI\Control
public UI\Control::getTopLevel(): int
public UI\Control::hide()
public UI\Control::isEnabled(): bool
public UI\Control::isVisible(): bool
public UI\Control::setParent(UI\Control $parent)
public UI\Control::show()
}

プロパティ

controls

Contains controls, should not be manipulated directly

定義済み定数

UI\Controls\Box::Vertical

UI\Controls\Box::Horizontal

目次

  • UI\Controls\Box::append — Append Control
  • UI\Controls\Box::__construct — Construct a new Box
  • UI\Controls\Box::delete — Delete Control
  • UI\Controls\Box::getOrientation — Get Orientation
  • UI\Controls\Box::isPadded — Padding Detection
  • UI\Controls\Box::setPadded — Set Padding


Append Control

  • ≪ UI\Controls\Box
  • UI\Controls\Box::__construct ≫
  • PHP Manual
  • UI\Controls\Box
  • Append Control

UI\Controls\Box::append

(UI 0.9.9)

UI\Controls\Box::append — Append Control

説明

public UI\Controls\Box::append(Control $control, bool $stretchy = false): int

Shall append the given control to this Box

パラメータ

control

The control to append

stretchy

Set true to stretch the control

戻り値

Shall return the index of the appended control, may be 0


Construct a new Box

  • ≪ UI\Controls\Box::append
  • UI\Controls\Box::delete ≫
  • PHP Manual
  • UI\Controls\Box
  • Construct a new Box

UI\Controls\Box::__construct

(UI 0.9.9)

UI\Controls\Box::__construct — Construct a new Box

説明

public UI\Controls\Box::__construct(int $orientation = UI\Controls\Box::Horizontal)

Shall construct a new box

パラメータ

orientation

Box::Horizontal or Box::Vertical


Delete Control

  • ≪ UI\Controls\Box::__construct
  • UI\Controls\Box::getOrientation ≫
  • PHP Manual
  • UI\Controls\Box
  • Delete Control

UI\Controls\Box::delete

(UI 0.9.9)

UI\Controls\Box::delete — Delete Control

説明

public UI\Controls\Box::delete(int $index): bool

Shall delete the control at the given index from this Box

パラメータ

index

The index of the control to delete

戻り値

Indication of success


Get Orientation

  • ≪ UI\Controls\Box::delete
  • UI\Controls\Box::isPadded ≫
  • PHP Manual
  • UI\Controls\Box
  • Get Orientation

UI\Controls\Box::getOrientation

(UI 0.9.9)

UI\Controls\Box::getOrientation — Get Orientation

説明

public UI\Controls\Box::getOrientation(): int

Shall retrieve the orientation of this Box

パラメータ

この関数にはパラメータはありません。


Padding Detection

  • ≪ UI\Controls\Box::getOrientation
  • UI\Controls\Box::setPadded ≫
  • PHP Manual
  • UI\Controls\Box
  • Padding Detection

UI\Controls\Box::isPadded

(UI 0.9.9)

UI\Controls\Box::isPadded — Padding Detection

説明

public UI\Controls\Box::isPadded(): bool

Shall detect if padding is enabled on this Box

パラメータ

この関数にはパラメータはありません。


Set Padding

  • ≪ UI\Controls\Box::isPadded
  • UI\Draw\Pen ≫
  • PHP Manual
  • UI\Controls\Box
  • Set Padding

UI\Controls\Box::setPadded

(UI 0.9.9)

UI\Controls\Box::setPadded — Set Padding

説明

public UI\Controls\Box::setPadded(bool $padded)

Shall enable or disable padding on this Box

パラメータ

padded


Draw Pen

(UI 0.9.9)

はじめに

The Pen is passed to the Area Draw event handler, it is used for clipping, filling, stroking, and writing to Draw Paths.

クラス概要

final class UI\Draw\Pen {
/* メソッド */
public clip(UI\Draw\Path $path)
public fill(UI\Draw\Path $path, UI\Draw\Brush $with)
public fill(UI\Draw\Path $path, UI\Draw\Color $with)
public fill(UI\Draw\Path $path, int $with)
public restore()
public save()
public stroke(UI\Draw\Path $path, UI\Draw\Brush $with, UI\Draw\Stroke $stroke)
public stroke(UI\Draw\Path $path, UI\Draw\Color $with, UI\Draw\Stroke $stroke)
public stroke(UI\Draw\Path $path, int $with, UI\Draw\Stroke $stroke)
public transform(UI\Draw\Matrix $matrix)
public write(UI\Point $point, UI\Draw\Text\Layout $layout)
}

目次

  • UI\Draw\Pen::clip — Clip a Path
  • UI\Draw\Pen::fill — Fill a Path
  • UI\Draw\Pen::restore — Restore
  • UI\Draw\Pen::save — Save
  • UI\Draw\Pen::stroke — Stroke a Path
  • UI\Draw\Pen::transform — Matrix Transform
  • UI\Draw\Pen::write — Draw Text at Point


Clip a Path

  • ≪ UI\Draw\Pen
  • UI\Draw\Pen::fill ≫
  • PHP Manual
  • UI\Draw\Pen
  • Clip a Path

UI\Draw\Pen::clip

(UI 0.9.9)

UI\Draw\Pen::clip — Clip a Path

説明

public UI\Draw\Pen::clip(UI\Draw\Path $path)

Shall clip the given Path

パラメータ

path

The path to clip


Fill a Path

  • ≪ UI\Draw\Pen::clip
  • UI\Draw\Pen::restore ≫
  • PHP Manual
  • UI\Draw\Pen
  • Fill a Path

UI\Draw\Pen::fill

(UI 0.9.9)

UI\Draw\Pen::fill — Fill a Path

説明

public UI\Draw\Pen::fill(UI\Draw\Path $path, UI\Draw\Brush $with)
public UI\Draw\Pen::fill(UI\Draw\Path $path, UI\Draw\Color $with)
public UI\Draw\Pen::fill(UI\Draw\Path $path, int $with)

Shall fill the given path

パラメータ

path

The path to fill

with

The color or brush to fill with


Restore

  • ≪ UI\Draw\Pen::fill
  • UI\Draw\Pen::save ≫
  • PHP Manual
  • UI\Draw\Pen
  • Restore

UI\Draw\Pen::restore

(UI 0.9.9)

UI\Draw\Pen::restore — Restore

説明

public UI\Draw\Pen::restore()

Shall restore a previously saved Pen

パラメータ

この関数にはパラメータはありません。


Save

  • ≪ UI\Draw\Pen::restore
  • UI\Draw\Pen::stroke ≫
  • PHP Manual
  • UI\Draw\Pen
  • Save

UI\Draw\Pen::save

(UI 0.9.9)

UI\Draw\Pen::save — Save

説明

public UI\Draw\Pen::save()

Shall save the Pen

パラメータ

この関数にはパラメータはありません。


Stroke a Path

  • ≪ UI\Draw\Pen::save
  • UI\Draw\Pen::transform ≫
  • PHP Manual
  • UI\Draw\Pen
  • Stroke a Path

UI\Draw\Pen::stroke

(UI 0.9.9)

UI\Draw\Pen::stroke — Stroke a Path

説明

public UI\Draw\Pen::stroke(UI\Draw\Path $path, UI\Draw\Brush $with, UI\Draw\Stroke $stroke)
public UI\Draw\Pen::stroke(UI\Draw\Path $path, UI\Draw\Color $with, UI\Draw\Stroke $stroke)
public UI\Draw\Pen::stroke(UI\Draw\Path $path, int $with, UI\Draw\Stroke $stroke)

Shall stroke the given path

パラメータ

path

The path to stroke

with

The color or brush to stroke with

stroke

The configuration of the stroke


Matrix Transform

  • ≪ UI\Draw\Pen::stroke
  • UI\Draw\Pen::write ≫
  • PHP Manual
  • UI\Draw\Pen
  • Matrix Transform

UI\Draw\Pen::transform

(UI 0.9.9)

UI\Draw\Pen::transform — Matrix Transform

説明

public UI\Draw\Pen::transform(UI\Draw\Matrix $matrix)

Shall perform matrix transformation

パラメータ

matrix

The matrix to use


Draw Text at Point

  • ≪ UI\Draw\Pen::transform
  • UI\Draw\Path ≫
  • PHP Manual
  • UI\Draw\Pen
  • Draw Text at Point

UI\Draw\Pen::write

(UI 0.9.9)

UI\Draw\Pen::write — Draw Text at Point

説明

public UI\Draw\Pen::write(UI\Point $point, UI\Draw\Text\Layout $layout)

Shall draw the given text layout at the given point

パラメータ

point

The point to perform the drawing

layout

The layout of the text to draw


Draw Path

(UI 0.9.9)

はじめに

A Draw Path guides a Draw Pen, telling the Pen where to draw on an Area.

クラス概要

class UI\Draw\Path {
/* 定数 */
const int Winding;
const int Alternate;
/* Constructor */
public __construct(int $mode = UI\Draw\Path::Winding)
/* メソッド */
public addRectangle(UI\Point $point, UI\Size $size)
public arcTo(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)
public bezierTo(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)
public closeFigure()
public end()
public lineTo(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)
public newFigure(UI\Point $point)
public newFigureWithArc(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)
}

定義済み定数

UI\Draw\Path::Winding

This is the default draw path mode

UI\Draw\Path::Alternate

This is the alternate draw path mode

目次

  • UI\Draw\Path::addRectangle — Draw a Rectangle
  • UI\Draw\Path::arcTo — Draw an Arc
  • UI\Draw\Path::bezierTo — Draw Bezier Curve
  • UI\Draw\Path::closeFigure — Close Figure
  • UI\Draw\Path::__construct — Construct a new Path
  • UI\Draw\Path::end — Finalize Path
  • UI\Draw\Path::lineTo — Draw a Line
  • UI\Draw\Path::newFigure — Draw Figure
  • UI\Draw\Path::newFigureWithArc — Draw Figure with Arc


Draw a Rectangle

  • ≪ UI\Draw\Path
  • UI\Draw\Path::arcTo ≫
  • PHP Manual
  • UI\Draw\Path
  • Draw a Rectangle

UI\Draw\Path::addRectangle

(UI 0.9.9)

UI\Draw\Path::addRectangle — Draw a Rectangle

説明

public UI\Draw\Path::addRectangle(UI\Point $point, UI\Size $size)

Shall map the path of a rectangle of the given size, at the given point

パラメータ

point

The point to begin the shape

size

The size of the rectangle


Draw an Arc

  • ≪ UI\Draw\Path::addRectangle
  • UI\Draw\Path::bezierTo ≫
  • PHP Manual
  • UI\Draw\Path
  • Draw an Arc

UI\Draw\Path::arcTo

(UI 0.9.9)

UI\Draw\Path::arcTo — Draw an Arc

説明

public UI\Draw\Path::arcTo(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)

Shall map the path for an arc

パラメータ

point

The point to begin mapping

radius

The radius of the arc

angle

The angle of the arc

sweep

The sweep of the arc

negative

戻り値


Draw Bezier Curve

  • ≪ UI\Draw\Path::arcTo
  • UI\Draw\Path::closeFigure ≫
  • PHP Manual
  • UI\Draw\Path
  • Draw Bezier Curve

UI\Draw\Path::bezierTo

(UI 0.9.9)

UI\Draw\Path::bezierTo — Draw Bezier Curve

説明

public UI\Draw\Path::bezierTo(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)

Shall draw a bezier curve

パラメータ

point

The point at which to begin mapping

radius

The radius of the curve

angle

The angle of the curve

sweep

The sweep of the curve

negative


Close Figure

  • ≪ UI\Draw\Path::bezierTo
  • UI\Draw\Path::__construct ≫
  • PHP Manual
  • UI\Draw\Path
  • Close Figure

UI\Draw\Path::closeFigure

(UI 0.9.9)

UI\Draw\Path::closeFigure — Close Figure

説明

public UI\Draw\Path::closeFigure()

Shall close the current figure

パラメータ

この関数にはパラメータはありません。


Construct a new Path

  • ≪ UI\Draw\Path::closeFigure
  • UI\Draw\Path::end ≫
  • PHP Manual
  • UI\Draw\Path
  • Construct a new Path

UI\Draw\Path::__construct

(UI 0.9.9)

UI\Draw\Path::__construct — Construct a new Path

説明

public UI\Draw\Path::__construct(int $mode = UI\Draw\Path::Winding)

Shall construct a new path in the given mode

パラメータ

mode

Path::Winding or Path::Alternate


Finalize Path

  • ≪ UI\Draw\Path::__construct
  • UI\Draw\Path::lineTo ≫
  • PHP Manual
  • UI\Draw\Path
  • Finalize Path

UI\Draw\Path::end

(UI 0.9.9)

UI\Draw\Path::end — Finalize Path

説明

public UI\Draw\Path::end()

Shall finalize this Path

パラメータ

この関数にはパラメータはありません。


Draw a Line

  • ≪ UI\Draw\Path::end
  • UI\Draw\Path::newFigure ≫
  • PHP Manual
  • UI\Draw\Path
  • Draw a Line

UI\Draw\Path::lineTo

(UI 0.9.9)

UI\Draw\Path::lineTo — Draw a Line

説明

public UI\Draw\Path::lineTo(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)

Shall map the path for a line

パラメータ

point

The point to begin mapping

radius

angle

sweep

negative

戻り値


Draw Figure

  • ≪ UI\Draw\Path::lineTo
  • UI\Draw\Path::newFigureWithArc ≫
  • PHP Manual
  • UI\Draw\Path
  • Draw Figure

UI\Draw\Path::newFigure

(UI 0.9.9)

UI\Draw\Path::newFigure — Draw Figure

説明

public UI\Draw\Path::newFigure(UI\Point $point)

Shall map a new figure at the given point

パラメータ

point

The point to begin mapping


Draw Figure with Arc

  • ≪ UI\Draw\Path::newFigure
  • UI\Draw\Matrix ≫
  • PHP Manual
  • UI\Draw\Path
  • Draw Figure with Arc

UI\Draw\Path::newFigureWithArc

(UI 0.9.9)

UI\Draw\Path::newFigureWithArc — Draw Figure with Arc

説明

public UI\Draw\Path::newFigureWithArc(
UI\Point $point,
float $radius,
float $angle,
float $sweep,
float $negative
)

パラメータ

point

radius

angle

sweep

negative

戻り値


Draw Matrix

(UI 0.9.9)

はじめに

クラス概要

class UI\Draw\Matrix {
/* メソッド */
public invert()
public isInvertible(): bool
public multiply(UI\Draw\Matrix $matrix): UI\Draw\Matrix
public rotate(UI\Point $point, float $amount)
public scale(UI\Point $center, UI\Point $point)
public skew(UI\Point $point, UI\Point $amount)
public translate(UI\Point $point)
}

目次

  • UI\Draw\Matrix::invert — Invert Matrix
  • UI\Draw\Matrix::isInvertible — Invertible Detection
  • UI\Draw\Matrix::multiply — Multiply Matrix
  • UI\Draw\Matrix::rotate — Rotate Matrix
  • UI\Draw\Matrix::scale — Scale Matrix
  • UI\Draw\Matrix::skew — Skew Matrix
  • UI\Draw\Matrix::translate — Translate Matrix


Invert Matrix

  • ≪ UI\Draw\Matrix
  • UI\Draw\Matrix::isInvertible ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Invert Matrix

UI\Draw\Matrix::invert

(UI 0.9.9)

UI\Draw\Matrix::invert — Invert Matrix

説明

public UI\Draw\Matrix::invert()

Shall invert this matrix

パラメータ

この関数にはパラメータはありません。


Invertible Detection

  • ≪ UI\Draw\Matrix::invert
  • UI\Draw\Matrix::multiply ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Invertible Detection

UI\Draw\Matrix::isInvertible

(UI 0.9.9)

UI\Draw\Matrix::isInvertible — Invertible Detection

説明

public UI\Draw\Matrix::isInvertible(): bool

Shall detect if this Matrix may be inverted

パラメータ

この関数にはパラメータはありません。


Multiply Matrix

  • ≪ UI\Draw\Matrix::isInvertible
  • UI\Draw\Matrix::rotate ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Multiply Matrix

UI\Draw\Matrix::multiply

(UI 0.9.9)

UI\Draw\Matrix::multiply — Multiply Matrix

説明

public UI\Draw\Matrix::multiply(UI\Draw\Matrix $matrix): UI\Draw\Matrix

Shall multiply this matrix with the given matrix

パラメータ

この関数にはパラメータはありません。

戻り値

The new Matrix


Rotate Matrix

  • ≪ UI\Draw\Matrix::multiply
  • UI\Draw\Matrix::scale ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Rotate Matrix

UI\Draw\Matrix::rotate

(UI 0.9.9)

UI\Draw\Matrix::rotate — Rotate Matrix

説明

public UI\Draw\Matrix::rotate(UI\Point $point, float $amount)

Shall rotate this Matrix

パラメータ

point

amount


Scale Matrix

  • ≪ UI\Draw\Matrix::rotate
  • UI\Draw\Matrix::skew ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Scale Matrix

UI\Draw\Matrix::scale

(UI 0.9.9)

UI\Draw\Matrix::scale — Scale Matrix

説明

public UI\Draw\Matrix::scale(UI\Point $center, UI\Point $point)

Shall scale this Matrix

パラメータ

center

point


Skew Matrix

  • ≪ UI\Draw\Matrix::scale
  • UI\Draw\Matrix::translate ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Skew Matrix

UI\Draw\Matrix::skew

(UI 0.9.9)

UI\Draw\Matrix::skew — Skew Matrix

説明

public UI\Draw\Matrix::skew(UI\Point $point, UI\Point $amount)

Shall skew this Matrix

パラメータ

point

amount


Translate Matrix

  • ≪ UI\Draw\Matrix::skew
  • UI\Draw\Color ≫
  • PHP Manual
  • UI\Draw\Matrix
  • Translate Matrix

UI\Draw\Matrix::translate

(UI 0.9.9)

UI\Draw\Matrix::translate — Translate Matrix

説明

public UI\Draw\Matrix::translate(UI\Point $point)

Shall translate this Matrix

パラメータ

point


Color Representation

(UI 0.9.9)

はじめに

Represents RGBA colours, individual channels are accessible via public properties.

クラス概要

class UI\Draw\Color {
/* 定数 */
const int Red;
const int Green;
const int Blue;
const int Alpha;
/* プロパティ */
public $r;
public $g;
public $b;
public $a;
/* Constructor */
public __construct(UI\Draw\Color $color = ?)
public __construct(int $color = ?)
/* メソッド */
public getChannel(int $channel): float
public setChannel(int $channel, float $value): void
}

プロパティ

r

Provides access to the red channel

g

Provides access to the green channel

b

Provides access to the blue channel

a

Provides access to the alpha channel

定義済み定数

UI\Draw\Color::Red

Identifies the red channel

UI\Draw\Color::Green

Identifies the green channel

UI\Draw\Color::Blue

Identifies the blue channel

UI\Draw\Color::Alpha

Identifies the alpha channel

目次

  • UI\Draw\Color::__construct — Construct new Color
  • UI\Draw\Color::getChannel — Color Manipulation
  • UI\Draw\Color::setChannel — Color Manipulation


Construct new Color

  • ≪ UI\Draw\Color
  • UI\Draw\Color::getChannel ≫
  • PHP Manual
  • UI\Draw\Color
  • Construct new Color

UI\Draw\Color::__construct

(UI 0.9.9)

UI\Draw\Color::__construct — Construct new Color

説明

public UI\Draw\Color::__construct(UI\Draw\Color $color = ?)
public UI\Draw\Color::__construct(int $color = ?)

Shall construct a new color

パラメータ

color

May be UI\Draw\Color or RRGGBBAA


Color Manipulation

  • ≪ UI\Draw\Color::__construct
  • UI\Draw\Color::setChannel ≫
  • PHP Manual
  • UI\Draw\Color
  • Color Manipulation

UI\Draw\Color::getChannel

(UI 0.9.9)

UI\Draw\Color::getChannel — Color Manipulation

説明

public UI\Draw\Color::getChannel(int $channel): float

Shall retrieve the value for a channel

パラメータ

channel

Constant channel identity

戻り値

The current value of the requested channel


Color Manipulation

  • ≪ UI\Draw\Color::getChannel
  • UI\Draw\Stroke ≫
  • PHP Manual
  • UI\Draw\Color
  • Color Manipulation

UI\Draw\Color::setChannel

(UI 0.9.9)

UI\Draw\Color::setChannel — Color Manipulation

説明

public UI\Draw\Color::setChannel(int $channel, float $value): void

Shall set the selected channel to the given value

パラメータ

channel

Constant channel identity

value

The new value for the selected channel

戻り値


Draw Stroke

(UI 0.9.9)

はじめに

Holds the configuration for the Pen to perform a stroke

クラス概要

class UI\Draw\Stroke {
/* Constructor */
public __construct(
int $cap = UI\Draw\Line\Cap::Flat,
int $join = UI\Draw\Line\Join::Miter,
float $thickness = 1,
float $miterLimit = 10
)
/* メソッド */
public getCap(): int
public getJoin(): int
public getMiterLimit(): float
public getThickness(): float
public setCap(int $cap)
public setJoin(int $join)
public setMiterLimit(float $limit)
public setThickness(float $thickness)
}

目次

  • UI\Draw\Stroke::__construct — Construct a new Stroke
  • UI\Draw\Stroke::getCap — Get Line Cap
  • UI\Draw\Stroke::getJoin — Get Line Join
  • UI\Draw\Stroke::getMiterLimit — Get Miter Limit
  • UI\Draw\Stroke::getThickness — Get Thickness
  • UI\Draw\Stroke::setCap — Set Line Cap
  • UI\Draw\Stroke::setJoin — Set Line Join
  • UI\Draw\Stroke::setMiterLimit — Set Miter Limit
  • UI\Draw\Stroke::setThickness — Set Thickness


Construct a new Stroke

  • ≪ UI\Draw\Stroke
  • UI\Draw\Stroke::getCap ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Construct a new Stroke

UI\Draw\Stroke::__construct

(UI 0.9.9)

UI\Draw\Stroke::__construct — Construct a new Stroke

説明

public UI\Draw\Stroke::__construct(
int $cap = UI\Draw\Line\Cap::Flat,
int $join = UI\Draw\Line\Join::Miter,
float $thickness = 1,
float $miterLimit = 10
)

Shall construct a new Stroke

パラメータ

cap

UI\Draw\Line\Cap::Flat, UI\Draw\Line\Cap::Round, or UI\Draw\Line\Cap::Square

join

UI\Draw\Line\Join::Miter, UI\Draw\Line\Join::Round, or UI\Draw\Line\Join::Bevel

thickness

The thickness of the stroke

miterLimit

Miter limit (default is sensible for all supported platforms)


Get Line Cap

  • ≪ UI\Draw\Stroke::__construct
  • UI\Draw\Stroke::getJoin ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Get Line Cap

UI\Draw\Stroke::getCap

(UI 0.9.9)

UI\Draw\Stroke::getCap — Get Line Cap

説明

public UI\Draw\Stroke::getCap(): int

Shall retrieve the line cap setting of this Stroke

パラメータ

この関数にはパラメータはありません。

戻り値

UI\Draw\Line\Cap::Flat, UI\Draw\Line\Cap::Round, or UI\Draw\Line\Cap::Square


Get Line Join

  • ≪ UI\Draw\Stroke::getCap
  • UI\Draw\Stroke::getMiterLimit ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Get Line Join

UI\Draw\Stroke::getJoin

(UI 0.9.9)

UI\Draw\Stroke::getJoin — Get Line Join

説明

public UI\Draw\Stroke::getJoin(): int

Shall retrieve the line join setting of this Stroke

パラメータ

この関数にはパラメータはありません。

戻り値

UI\Draw\Line\Join::Miter, UI\Draw\Line\Join::Round, or UI\Draw\Line\Join::Bevel


Get Miter Limit

  • ≪ UI\Draw\Stroke::getJoin
  • UI\Draw\Stroke::getThickness ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Get Miter Limit

UI\Draw\Stroke::getMiterLimit

(UI 0.9.9)

UI\Draw\Stroke::getMiterLimit — Get Miter Limit

説明

public UI\Draw\Stroke::getMiterLimit(): float

Shall retrieve the miter limit of this Stroke

パラメータ

この関数にはパラメータはありません。

戻り値

The current miter limit


Get Thickness

  • ≪ UI\Draw\Stroke::getMiterLimit
  • UI\Draw\Stroke::setCap ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Get Thickness

UI\Draw\Stroke::getThickness

(UI 0.9.9)

UI\Draw\Stroke::getThickness — Get Thickness

説明

public UI\Draw\Stroke::getThickness(): float

Shall retrieve the thickness of this Stroke

パラメータ

この関数にはパラメータはありません。

戻り値

The current thickness


Set Line Cap

  • ≪ UI\Draw\Stroke::getThickness
  • UI\Draw\Stroke::setJoin ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Set Line Cap

UI\Draw\Stroke::setCap

(UI 0.9.9)

UI\Draw\Stroke::setCap — Set Line Cap

説明

public UI\Draw\Stroke::setCap(int $cap)

Shall set the line cap setting for this Stroke

パラメータ

cap

UI\Draw\Line\Cap::Flat, UI\Draw\Line\Cap::Round, or UI\Draw\Line\Cap::Square


Set Line Join

  • ≪ UI\Draw\Stroke::setCap
  • UI\Draw\Stroke::setMiterLimit ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Set Line Join

UI\Draw\Stroke::setJoin

(UI 0.9.9)

UI\Draw\Stroke::setJoin — Set Line Join

説明

public UI\Draw\Stroke::setJoin(int $join)

Shall set the line join setting for this Stroke

パラメータ

join

UI\Draw\Line\Join::Miter, UI\Draw\Line\Join::Round, or UI\Draw\Line\Join::Bevel

戻り値


Set Miter Limit

  • ≪ UI\Draw\Stroke::setJoin
  • UI\Draw\Stroke::setThickness ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Set Miter Limit

UI\Draw\Stroke::setMiterLimit

(UI 0.9.9)

UI\Draw\Stroke::setMiterLimit — Set Miter Limit

説明

public UI\Draw\Stroke::setMiterLimit(float $limit)

Set the miter limit for this Stroke

パラメータ

limit

The new limit


Set Thickness

  • ≪ UI\Draw\Stroke::setMiterLimit
  • UI\Draw\Brush ≫
  • PHP Manual
  • UI\Draw\Stroke
  • Set Thickness

UI\Draw\Stroke::setThickness

(UI 0.9.9)

UI\Draw\Stroke::setThickness — Set Thickness

説明

public UI\Draw\Stroke::setThickness(float $thickness)

Shall set the thickness for this Stroke

パラメータ

thickness

The new thickness


Brushes

(UI 0.9.9)

はじめに

Represents a solid color brush

クラス概要

class UI\Draw\Brush {
/* Constructor */
public __construct(UI\Draw\Color $color)
public __construct(int $color)
/* メソッド */
public getColor(): UI\Draw\Color
public setColor(UI\Draw\Color $color): void
public setColor(int $color): void
}

目次

  • UI\Draw\Brush::__construct — Construct a new Brush
  • UI\Draw\Brush::getColor — Get Color
  • UI\Draw\Brush::setColor — Set Color


Construct a new Brush

  • ≪ UI\Draw\Brush
  • UI\Draw\Brush::getColor ≫
  • PHP Manual
  • UI\Draw\Brush
  • Construct a new Brush

UI\Draw\Brush::__construct

(UI 0.9.9)

UI\Draw\Brush::__construct — Construct a new Brush

説明

public UI\Draw\Brush::__construct(UI\Draw\Color $color)
public UI\Draw\Brush::__construct(int $color)

Shall construct a solid brush using the given color

パラメータ

color

Can be a UI\Draw\Color or RRGGBBAA


Get Color

  • ≪ UI\Draw\Brush::__construct
  • UI\Draw\Brush::setColor ≫
  • PHP Manual
  • UI\Draw\Brush
  • Get Color

UI\Draw\Brush::getColor

(UI 0.9.9)

UI\Draw\Brush::getColor — Get Color

説明

public UI\Draw\Brush::getColor(): UI\Draw\Color

Shall return a UI\Draw\Color for this brush

パラメータ

この関数にはパラメータはありません。

戻り値

The current color of the brush


Set Color

  • ≪ UI\Draw\Brush::getColor
  • UI\Draw\Brush\Gradient ≫
  • PHP Manual
  • UI\Draw\Brush
  • Set Color

UI\Draw\Brush::setColor

(UI 0.9.9)

UI\Draw\Brush::setColor — Set Color

説明

public UI\Draw\Brush::setColor(UI\Draw\Color $color): void
public UI\Draw\Brush::setColor(int $color): void

Shall set the color of this brush to the color provided

パラメータ

color

Can be a UI\Draw\Color or RRGGBBAA

戻り値


Gradient Brushes

(UI 2.0.0)

はじめに

Abstract for gradient brushes

クラス概要

abstract class UI\Draw\Brush\Gradient extends UI\Draw\Brush {
/* メソッド */
public addStop(float $position, UI\Draw\Color $color): int
public addStop(float $position, int $color): int
public delStop(int $index): int
public setStop(int $index, float $position, UI\Draw\Color $color): bool
public setStop(int $index, float $position, int $color): bool
/* 継承したメソッド */
public UI\Draw\Brush::getColor(): UI\Draw\Color
public UI\Draw\Brush::setColor(UI\Draw\Color $color): void
public UI\Draw\Brush::setColor(int $color): void
}

目次

  • UI\Draw\Brush\Gradient::addStop — Stop Manipulation
  • UI\Draw\Brush\Gradient::delStop — Stop Manipulation
  • UI\Draw\Brush\Gradient::setStop — Stop Manipulation


Stop Manipulation

  • ≪ UI\Draw\Brush\Gradient
  • UI\Draw\Brush\Gradient::delStop ≫
  • PHP Manual
  • UI\Draw\Brush\Gradient
  • Stop Manipulation

UI\Draw\Brush\Gradient::addStop

(UI 2.0.0)

UI\Draw\Brush\Gradient::addStop — Stop Manipulation

説明

public UI\Draw\Brush\Gradient::addStop(float $position, UI\Draw\Color $color): int
public UI\Draw\Brush\Gradient::addStop(float $position, int $color): int

Shall at a stop of the given color at the given position

パラメータ

position

The position for the new stop

color

The color for the new stop, may be UI\Draw\Color or RRGGBBAA

戻り値

Total number of stops


Stop Manipulation

  • ≪ UI\Draw\Brush\Gradient::addStop
  • UI\Draw\Brush\Gradient::setStop ≫
  • PHP Manual
  • UI\Draw\Brush\Gradient
  • Stop Manipulation

UI\Draw\Brush\Gradient::delStop

(UI 2.0.0)

UI\Draw\Brush\Gradient::delStop — Stop Manipulation

説明

public UI\Draw\Brush\Gradient::delStop(int $index): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

index

戻り値

Total number of stops


Stop Manipulation

  • ≪ UI\Draw\Brush\Gradient::delStop
  • UI\Draw\Brush\LinearGradient ≫
  • PHP Manual
  • UI\Draw\Brush\Gradient
  • Stop Manipulation

UI\Draw\Brush\Gradient::setStop

(UI 2.0.0)

UI\Draw\Brush\Gradient::setStop — Stop Manipulation

説明

public UI\Draw\Brush\Gradient::setStop(int $index, float $position, UI\Draw\Color $color): bool
public UI\Draw\Brush\Gradient::setStop(int $index, float $position, int $color): bool

パラメータ

index

The index of the stop to set

position

The position for the stop

color

The color for the stop, may be UI\Draw\Color or RRGGBBAA

戻り値

Indication of success


Linear Gradient

(UI 2.0.0)

はじめに

クラス概要

class UI\Draw\Brush\LinearGradient extends UI\Draw\Brush\Gradient {
/* Constructor */
public __construct(UI\Point $start, UI\Point $end)
/* 継承したメソッド */
public UI\Draw\Brush\Gradient::addStop(float $position, UI\Draw\Color $color): int
public UI\Draw\Brush\Gradient::addStop(float $position, int $color): int
public UI\Draw\Brush\Gradient::delStop(int $index): int
public UI\Draw\Brush\Gradient::setStop(int $index, float $position, UI\Draw\Color $color): bool
public UI\Draw\Brush\Gradient::setStop(int $index, float $position, int $color): bool
}

目次

  • UI\Draw\Brush\LinearGradient::__construct — Construct a Linear Gradient


Construct a Linear Gradient

  • ≪ UI\Draw\Brush\LinearGradient
  • UI\Draw\Brush\RadialGradient ≫
  • PHP Manual
  • UI\Draw\Brush\LinearGradient
  • Construct a Linear Gradient

UI\Draw\Brush\LinearGradient::__construct

(UI 2.0.0)

UI\Draw\Brush\LinearGradient::__construct — Construct a Linear Gradient

説明

public UI\Draw\Brush\LinearGradient::__construct(UI\Point $start, UI\Point $end)

Shall construct a new linear gradient

パラメータ

start

end


Radial Gradient

(UI 2.0.0)

はじめに

クラス概要

class UI\Draw\Brush\RadialGradient extends UI\Draw\Brush\Gradient {
/* Constructor */
public __construct(UI\Point $start, UI\Point $outer, float $radius)
/* 継承したメソッド */
public UI\Draw\Brush\Gradient::addStop(float $position, UI\Draw\Color $color): int
public UI\Draw\Brush\Gradient::addStop(float $position, int $color): int
public UI\Draw\Brush\Gradient::delStop(int $index): int
public UI\Draw\Brush\Gradient::setStop(int $index, float $position, UI\Draw\Color $color): bool
public UI\Draw\Brush\Gradient::setStop(int $index, float $position, int $color): bool
}

目次

  • UI\Draw\Brush\RadialGradient::__construct — Construct a new Radial Gradient


Construct a new Radial Gradient

  • ≪ UI\Draw\Brush\RadialGradient
  • UI\Draw\Text\Layout ≫
  • PHP Manual
  • UI\Draw\Brush\RadialGradient
  • Construct a new Radial Gradient

UI\Draw\Brush\RadialGradient::__construct

(UI 2.0.0)

UI\Draw\Brush\RadialGradient::__construct — Construct a new Radial Gradient

説明

public UI\Draw\Brush\RadialGradient::__construct(UI\Point $start, UI\Point $outer, float $radius)

Shall construct a new radial gradient

パラメータ

start

outer

radius


Represents Text Layout

(UI 0.9.9)

はじめに

A Text Layout represents the layout of text which will be drawn by the Pen

クラス概要

class UI\Draw\Text\Layout {
/* Constructor */
public __construct(string $text, UI\Draw\Text\Font $font, float $width)
/* メソッド */
public setColor(UI\Draw\Color $color, int $start = 0, int $end = ?)
public setColor(int $color, int $start = 0, int $end = ?)
public setWidth(float $width)
}

目次

  • UI\Draw\Text\Layout::__construct — Construct a new Text Layout
  • UI\Draw\Text\Layout::setColor — Set Color
  • UI\Draw\Text\Layout::setWidth — Set Width


Construct a new Text Layout

  • ≪ UI\Draw\Text\Layout
  • UI\Draw\Text\Layout::setColor ≫
  • PHP Manual
  • UI\Draw\Text\Layout
  • Construct a new Text Layout

UI\Draw\Text\Layout::__construct

(UI 0.9.9)

UI\Draw\Text\Layout::__construct — Construct a new Text Layout

説明

public UI\Draw\Text\Layout::__construct(string $text, UI\Draw\Text\Font $font, float $width)

Shall construct a new Text Layout

パラメータ

text

The text for the layout

font

The font to use for writing

width

The width of the layout


Set Color

  • ≪ UI\Draw\Text\Layout::__construct
  • UI\Draw\Text\Layout::setWidth ≫
  • PHP Manual
  • UI\Draw\Text\Layout
  • Set Color

UI\Draw\Text\Layout::setColor

(UI 0.9.9)

UI\Draw\Text\Layout::setColor — Set Color

説明

public UI\Draw\Text\Layout::setColor(UI\Draw\Color $color, int $start = 0, int $end = ?)
public UI\Draw\Text\Layout::setColor(int $color, int $start = 0, int $end = ?)

Shall set the Color for all of, or a range of the text in the Layout

パラメータ

color

The color to use

start

The starting character

end

The ending character, by default the end of the string


Set Width

  • ≪ UI\Draw\Text\Layout::setColor
  • UI\Draw\Text\Font ≫
  • PHP Manual
  • UI\Draw\Text\Layout
  • Set Width

UI\Draw\Text\Layout::setWidth

(UI 0.9.9)

UI\Draw\Text\Layout::setWidth — Set Width

説明

public UI\Draw\Text\Layout::setWidth(float $width)

Shall set the width of this Text Layout

パラメータ

width

The new width


Represents a Font

(UI 0.9.9)

はじめに

Loads a described font

クラス概要

class UI\Draw\Text\Font {
/* Constructor */
public __construct(UI\Draw\Text\Font\Descriptor $descriptor)
/* メソッド */
public getAscent(): float
public getDescent(): float
public getLeading(): float
public getUnderlinePosition(): float
public getUnderlineThickness(): float
}

目次

  • UI\Draw\Text\Font::__construct — Construct a new Font
  • UI\Draw\Text\Font::getAscent — Font Metrics
  • UI\Draw\Text\Font::getDescent — Font Metrics
  • UI\Draw\Text\Font::getLeading — Font Metrics
  • UI\Draw\Text\Font::getUnderlinePosition — Font Metrics
  • UI\Draw\Text\Font::getUnderlineThickness — Font Metrics


Construct a new Font

  • ≪ UI\Draw\Text\Font
  • UI\Draw\Text\Font::getAscent ≫
  • PHP Manual
  • UI\Draw\Text\Font
  • Construct a new Font

UI\Draw\Text\Font::__construct

(UI 0.9.9)

UI\Draw\Text\Font::__construct — Construct a new Font

説明

public UI\Draw\Text\Font::__construct(UI\Draw\Text\Font\Descriptor $descriptor)

Shall construct a new Font using the given descriptor

パラメータ

descriptor

The descriptor for the Font


Font Metrics

  • ≪ UI\Draw\Text\Font::__construct
  • UI\Draw\Text\Font::getDescent ≫
  • PHP Manual
  • UI\Draw\Text\Font
  • Font Metrics

UI\Draw\Text\Font::getAscent

(UI 1.0.3)

UI\Draw\Text\Font::getAscent — Font Metrics

説明

public UI\Draw\Text\Font::getAscent(): float

パラメータ

この関数にはパラメータはありません。

戻り値


Font Metrics

  • ≪ UI\Draw\Text\Font::getAscent
  • UI\Draw\Text\Font::getLeading ≫
  • PHP Manual
  • UI\Draw\Text\Font
  • Font Metrics

UI\Draw\Text\Font::getDescent

(UI 1.0.3)

UI\Draw\Text\Font::getDescent — Font Metrics

説明

public UI\Draw\Text\Font::getDescent(): float

パラメータ

この関数にはパラメータはありません。

戻り値


Font Metrics

  • ≪ UI\Draw\Text\Font::getDescent
  • UI\Draw\Text\Font::getUnderlinePosition ≫
  • PHP Manual
  • UI\Draw\Text\Font
  • Font Metrics

UI\Draw\Text\Font::getLeading

(UI 1.0.3)

UI\Draw\Text\Font::getLeading — Font Metrics

説明

public UI\Draw\Text\Font::getLeading(): float

パラメータ

この関数にはパラメータはありません。

戻り値


Font Metrics

  • ≪ UI\Draw\Text\Font::getLeading
  • UI\Draw\Text\Font::getUnderlineThickness ≫
  • PHP Manual
  • UI\Draw\Text\Font
  • Font Metrics

UI\Draw\Text\Font::getUnderlinePosition

(UI 1.0.3)

UI\Draw\Text\Font::getUnderlinePosition — Font Metrics

説明

public UI\Draw\Text\Font::getUnderlinePosition(): float

パラメータ

この関数にはパラメータはありません。

戻り値


Font Metrics

  • ≪ UI\Draw\Text\Font::getUnderlinePosition
  • UI\Draw\Text\Font\Descriptor ≫
  • PHP Manual
  • UI\Draw\Text\Font
  • Font Metrics

UI\Draw\Text\Font::getUnderlineThickness

(UI 1.0.3)

UI\Draw\Text\Font::getUnderlineThickness — Font Metrics

説明

public UI\Draw\Text\Font::getUnderlineThickness(): float

パラメータ

この関数にはパラメータはありません。

戻り値


Font Descriptor

(UI 0.9.9)

はじめに

Describes a font

クラス概要

class UI\Draw\Text\Font\Descriptor {
/* Constructor */
public __construct(
string $family,
float $size,
int $weight = UI\Draw\Text\Font\Weight::Normal,
int $italic = UI\Draw\Text\Font\Italic::Normal,
int $stretch = UI\Draw\Text\Font\Stretch::Normal
)
/* メソッド */
public getFamily(): string
public getItalic(): int
public getSize(): float
public getStretch(): int
public getWeight(): int
}

目次

  • UI\Draw\Text\Font\Descriptor::__construct — Construct a new Font Descriptor
  • UI\Draw\Text\Font\Descriptor::getFamily — Get Font Family
  • UI\Draw\Text\Font\Descriptor::getItalic — Style Detection
  • UI\Draw\Text\Font\Descriptor::getSize — Size Detection
  • UI\Draw\Text\Font\Descriptor::getStretch — Style Detection
  • UI\Draw\Text\Font\Descriptor::getWeight — Weight Detection


Construct a new Font Descriptor

  • ≪ UI\Draw\Text\Font\Descriptor
  • UI\Draw\Text\Font\Descriptor::getFamily ≫
  • PHP Manual
  • UI\Draw\Text\Font\Descriptor
  • Construct a new Font Descriptor

UI\Draw\Text\Font\Descriptor::__construct

(UI 0.9.9)

UI\Draw\Text\Font\Descriptor::__construct — Construct a new Font Descriptor

説明

public UI\Draw\Text\Font\Descriptor::__construct(
string $family,
float $size,
int $weight = UI\Draw\Text\Font\Weight::Normal,
int $italic = UI\Draw\Text\Font\Italic::Normal,
int $stretch = UI\Draw\Text\Font\Stretch::Normal
)

Shall construct a new Font Descriptor

パラメータ

family

The name of a valid family of fonts

size

The preferred size

weight

UI\Draw\Text\Font\Weight constant

italic

UI\Draw\Text\Font\Italic constant

stretch

UI\Draw\Text\Font\Stretch constant


Get Font Family

  • ≪ UI\Draw\Text\Font\Descriptor::__construct
  • UI\Draw\Text\Font\Descriptor::getItalic ≫
  • PHP Manual
  • UI\Draw\Text\Font\Descriptor
  • Get Font Family

UI\Draw\Text\Font\Descriptor::getFamily

(UI 1.0.3)

UI\Draw\Text\Font\Descriptor::getFamily — Get Font Family

説明

public UI\Draw\Text\Font\Descriptor::getFamily(): string

Shall return the requested font family

パラメータ

この関数にはパラメータはありません。

戻り値


Style Detection

  • ≪ UI\Draw\Text\Font\Descriptor::getFamily
  • UI\Draw\Text\Font\Descriptor::getSize ≫
  • PHP Manual
  • UI\Draw\Text\Font\Descriptor
  • Style Detection

UI\Draw\Text\Font\Descriptor::getItalic

(UI 1.0.3)

UI\Draw\Text\Font\Descriptor::getItalic — Style Detection

説明

public UI\Draw\Text\Font\Descriptor::getItalic(): int

Shall return constant setting

パラメータ

この関数にはパラメータはありません。

戻り値


Size Detection

  • ≪ UI\Draw\Text\Font\Descriptor::getItalic
  • UI\Draw\Text\Font\Descriptor::getStretch ≫
  • PHP Manual
  • UI\Draw\Text\Font\Descriptor
  • Size Detection

UI\Draw\Text\Font\Descriptor::getSize

(UI 1.0.3)

UI\Draw\Text\Font\Descriptor::getSize — Size Detection

説明

public UI\Draw\Text\Font\Descriptor::getSize(): float

Shall return the requested size

パラメータ

この関数にはパラメータはありません。

戻り値


Style Detection

  • ≪ UI\Draw\Text\Font\Descriptor::getSize
  • UI\Draw\Text\Font\Descriptor::getWeight ≫
  • PHP Manual
  • UI\Draw\Text\Font\Descriptor
  • Style Detection

UI\Draw\Text\Font\Descriptor::getStretch

(UI 1.0.3)

UI\Draw\Text\Font\Descriptor::getStretch — Style Detection

説明

public UI\Draw\Text\Font\Descriptor::getStretch(): int

Shall return requested stretch

パラメータ

この関数にはパラメータはありません。

戻り値


Weight Detection

  • ≪ UI\Draw\Text\Font\Descriptor::getStretch
  • UI 関数 ≫
  • PHP Manual
  • UI\Draw\Text\Font\Descriptor
  • Weight Detection

UI\Draw\Text\Font\Descriptor::getWeight

(UI 1.0.3)

UI\Draw\Text\Font\Descriptor::getWeight — Weight Detection

説明

public UI\Draw\Text\Font\Descriptor::getWeight(): int

Shall return requested weight

パラメータ

この関数にはパラメータはありません。

戻り値


UI 関数

目次

  • UI\Draw\Text\Font\fontFamilies — Retrieve Font Families
  • UI\quit — Quit UI Loop
  • UI\run — Enter UI Loop


Retrieve Font Families

  • ≪ UI 関数
  • UI\quit ≫
  • PHP Manual
  • UI 関数
  • Retrieve Font Families

UI\Draw\Text\Font\fontFamilies

(UI 0.9.9)

UI\Draw\Text\Font\fontFamilies — Retrieve Font Families

説明

UI\Draw\Text\Font\fontFamilies(): array

Returns an array of valid font families for the current system

パラメータ

この関数にはパラメータはありません。

戻り値

Returns an array of valid font families for the current system.


Quit UI Loop

  • ≪ UI\Draw\Text\Font\fontFamilies
  • UI\run ≫
  • PHP Manual
  • UI 関数
  • Quit UI Loop

UI\quit

(UI 2.0.0)

UI\quit — Quit UI Loop

説明

UI\quit(): void

Shall cause the main loop to be exited

パラメータ

この関数にはパラメータはありません。

戻り値


Enter UI Loop

  • ≪ UI\quit
  • UI\Draw\Text\Font\Weight ≫
  • PHP Manual
  • UI 関数
  • Enter UI Loop

UI\run

(UI 2.0.0)

UI\run — Enter UI Loop

説明

UI\run(int $flags = ?): void

Shall cause PHP to enter into the main loop, by default control will not be returned to the caller

パラメータ

flags

Set UI\Loop to return control, and UI\Wait to return control after waiting

戻り値


Font Weight Settings

(UI 0.9.9)

はじめに

クラス概要

final class UI\Draw\Text\Font\Weight {
/* 定数 */
const int Thin;
const int UltraLight;
const int Light;
const int Book;
const int Normal;
const int Medium;
const int SemiBold;
const int Bold;
const int UltraBold;
const int Heavy;
const int UltraHeavy;
}

定義済み定数

UI\Draw\Text\Font\Weight::Thin
UI\Draw\Text\Font\Weight::UltraLight
UI\Draw\Text\Font\Weight::Light
UI\Draw\Text\Font\Weight::Book
UI\Draw\Text\Font\Weight::Normal
UI\Draw\Text\Font\Weight::Medium
UI\Draw\Text\Font\Weight::SemiBold
UI\Draw\Text\Font\Weight::Bold
UI\Draw\Text\Font\Weight::UltraBold
UI\Draw\Text\Font\Weight::Heavy
UI\Draw\Text\Font\Weight::UltraHeavy


Italic Font Settings

(UI 0.9.9)

はじめに

クラス概要

final class UI\Draw\Text\Font\Italic {
/* 定数 */
const int Normal = 0;
const int Oblique = 1;
const int Italic = 2;
}

定義済み定数

UI\Draw\Text\Font\Italic::Normal
UI\Draw\Text\Font\Italic::Oblique
UI\Draw\Text\Font\Italic::Italic


Font Stretch Settings

(UI 0.9.9)

はじめに

クラス概要

final class UI\Draw\Text\Font\Stretch {
/* 定数 */
const int UltraCondensed = 0;
const int ExtraCondensed = 1;
const int Condensed = 2;
const int SemiCondensed = 3;
const int Normal = 4;
const int SemiExpanded = 5;
const int Expanded = 6;
const int ExtraExpanded = 7;
const int UltraExpanded = 8;
}

定義済み定数

UI\Draw\Text\Font\Stretch::UltraCondensed
UI\Draw\Text\Font\Stretch::ExtraCondensed
UI\Draw\Text\Font\Stretch::Condensed
UI\Draw\Text\Font\Stretch::SemiCondensed
UI\Draw\Text\Font\Stretch::Normal
UI\Draw\Text\Font\Stretch::SemiExpanded
UI\Draw\Text\Font\Stretch::Expanded
UI\Draw\Text\Font\Stretch::ExtraExpanded
UI\Draw\Text\Font\Stretch::UltraExpanded


Line Cap Settings

(UI 0.9.9)

はじめに

クラス概要

final class UI\Draw\Line\Cap {
/* 定数 */
const int Flat;
const int Round;
const int Square;
}

定義済み定数

UI\Draw\Line\Cap::Flat
UI\Draw\Line\Cap::Round
UI\Draw\Line\Cap::Square


Line Join Settings

(UI 0.9.9)

はじめに

クラス概要

final class UI\Draw\Line\Join {
/* 定数 */
const int Miter;
const int Round;
const int Bevel;
}

定義済み定数

UI\Draw\Line\Join::Miter
UI\Draw\Line\Join::Round
UI\Draw\Line\Join::Bevel


Key Identifiers

(UI 1.0.0)

はじめに

クラス概要

final class UI\Key {
/* 定数 */
const int Escape;
const int Insert;
const int Delete;
const int Home;
const int End;
const int PageUp;
const int PageDown;
const int Up;
const int Down;
const int Left;
const int Right;
const int F1;
const int F2;
const int F3;
const int F4;
const int F5;
const int F6;
const int F7;
const int F8;
const int F9;
const int F10;
const int F11;
const int F12;
const int N0;
const int N1;
const int N2;
const int N3;
const int N4;
const int N5;
const int N6;
const int N7;
const int N8;
const int N9;
const int NDot;
const int NEnter;
const int NAdd;
const int NSubtract;
const int NMultiply;
const int NDivide;
}

定義済み定数

UI\Key::Escape
UI\Key::Insert
UI\Key::Delete
UI\Key::Home
UI\Key::End
UI\Key::PageUp
UI\Key::PageDown
UI\Key::Up
UI\Key::Down
UI\Key::Left
UI\Key::Right
UI\Key::F1
UI\Key::F2
UI\Key::F3
UI\Key::F4
UI\Key::F5
UI\Key::F6
UI\Key::F7
UI\Key::F8
UI\Key::F9
UI\Key::F10
UI\Key::F11
UI\Key::F12
UI\Key::N0
UI\Key::N1
UI\Key::N2
UI\Key::N3
UI\Key::N4
UI\Key::N5
UI\Key::N6
UI\Key::N7
UI\Key::N8
UI\Key::N9
UI\Key::NDot
UI\Key::NEnter
UI\Key::NAdd
UI\Key::NSubtract
UI\Key::NMultiply
UI\Key::NDivide


InvalidArgumentException

(UI 1.0.3)

はじめに

クラス概要

class UI\Exception\InvalidArgumentException extends InvalidArgumentException implements Throwable {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


RuntimeException

(UI 1.0.3)

はじめに

クラス概要

class UI\Exception\RuntimeException extends RuntimeException implements Throwable {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
final public Exception::getMessage(): string
final public Exception::getPrevious(): ?Throwable
final public Exception::getCode(): int
final public Exception::getFile(): string
final public Exception::getLine(): int
final public Exception::getTrace(): array
final public Exception::getTraceAsString(): string
public Exception::__toString(): string
private Exception::__clone(): void
}


FAQ: よくある質問

  • 一般的な情報
  • メーリングリスト
  • PHP を手に入れるには
  • データベースに関する問題
  • インストール
  • 構築時の問題
  • PHP の使いかた
  • パスワードのハッシュ — 安全なパスワードハッシュ
  • PHP と HTML
  • PHP と COM
  • その他の質問


一般的な情報

このセクションでは PHP に関するもっとも基本的な情報 (PHP とは何か? PHP は何をするものか? 等)を扱います。

  1. PHPとは?
  2. PHP とは何の略ですか?
  3. 各バージョン間の関係は?
  4. 異なるバージョンの PHP を同時に実行することができますか?
  5. バグを見つけました! 誰に伝えればよいですか?
PHPとは?

マニュアルの序文より:

PHP は "PHP: Hypertext Preprocessor" を意味する、HTML 埋め込み型の スクリプト言語です。 PHP の多くの構文は C、Java、Perl 言語から転 用したものですが、PHP 特有の機能を実装するために独自の構文を導入 しています。PHP の目的は、Web 開発者が動的に生成されるページの 作成を速やかに行うことができるようにすることです。

PHP とは何の略ですか?

PHP は PHP: Hypertext Preprocessor の略です。 最初の文字が「頭字語の頭字語」になっているため多くの人は混乱します。 この種の頭字語は「再帰的頭字語」と呼ばれます。さらに詳細な情報に興味がある方は、» Free On-Line Dictionary of Computing あるいは » Wikipedia のエントリ で再帰的頭字語についてもっと詳しく知ることが出来ます。

各バージョン間の関係は?

PHP/FI 2.0 は PHP の初期の、 そしてもうすでにサポートされていないバージョンです。 PHP 3 は PHP/FI 2.0 の後継バージョンで、 PHP/FI 2.0 に比べて大きく進歩しています。 PHP 8 が PHP の最新バージョンです。これは Zend Engine 4 を使用しており、 さまざまな OOP 機能を提供します。

異なるバージョンの PHP を同時に実行することができますか?

はい。PHP のソースコードディストリビューションに含まれる INSTALL ファイルを見てください。

バグを見つけました! 誰に伝えればよいですか?

まず、PHP Bug Database でそれが既知のバグかどうかを調べてください。 もしデータベースで見つけることができなければ、「reporting form」 を使ってバグを報告してください。メーリングリスト等ではなく Bug Database に報告することは非常に重要です。 なぜなら個々のバグには「Tracking Number」がつけられるため、 後からバグの状態をチェックすることが可能だからです。 Bug Database は » https://github.com/php/php-src/issues にあります。


メーリングリスト

このセクションではPHPのコミュニティへの参加に関する質問を扱います。 最良の方法はメーリングリストに参加することです。

  1. PHPのメーリングリストはありますか?
  2. 他にコミュニティはありますか?
  3. PHP のメーリングリストを自分で作ってもかまいませんか?
  4. Help! メーリングリストに参加/脱退できません!
  5. どこかにメーリングリストのアーカイブ(過去ログ)はありますか?
  6. メーリングリストではどんな質問をすることができるのですか?
  7. メーリングリストに投稿するときには、どんな情報を含めればよいのですか?
PHPのメーリングリストはありますか?

もちろんです! 様々なトピックに関するたくさんのメーリングリストがあります。 もっとも一般的なコミュニティのメーリングリストは » メーリングリスト のページにあります。

最も一般的なメーリングリストが php-general です。 参加するには、空メールを » php-general+subscribe@lists.php.net に送ってください。脱退するには、空メールを » php-general+unsubscribe@lists.php.net に送ってください。

また、» メーリングリスト のページから参加/脱退を行うこともできます。 脱退方法は、メーリングリストのすべてのメッセージのフッターにも記載されています。

他にコミュニティはありますか?

世界中に数え切れないほどあります。» サポートページ には例としていくつかのリソース (そしてそれらについてより詳しく知るための情報) へのリンクがあります。

PHP のメーリングリストを自分で作ってもかまいませんか?

もちろん! 許可します。というよりむしろどんどんやってください! あなたが持つ PHP の知識や経験をみんなで共有することで、 PHP コミュニティだけでなく PHP 言語自体の発展の助けとなります。

Help! メーリングリストに参加/脱退できません!

メーリングリストからの脱退がうまくいかない原因でもっとも多いのは、 メールの転送処理にからむものです。たとえば、あなたのメールアドレスが elephpant@example.com であったとしましょう。 しかし、メーリングリストへの参加は php-lists@example.com で行っており、このアドレスは自動的に elephpant@example.com に転送されるようになっているものとします。 このとき、elephpant@example.com で脱退処理を行ってもうまくいきません。 このアドレスはメーリングリストに登録されていないからです。 この場合は、メールが実際に送信されているアドレス、つまり php-lists@example.com で脱退処理をしなければなりません。

どこかにメーリングリストのアーカイブ(過去ログ)はありますか?

はい。» メーリングリスト のページにアーカイブサイトへのリンクがあります。 それ以外にも、メーリングリストのコンテンツをアーカイブしているサイトは数多くあります。 サーチエンジンで "php mailing list archives" を検索してみるといいでしょう。

メーリングリストの記事は news メッセージとしても記録されています。 news クライアントで » news://news.php.net/ へアクセスすることができます。さらに、 » http://news.php.net/ に実験的な news サーバーへの Web インターフェイスがあります。

メーリングリストではどんな質問をすることができるのですか?

PHP が日進月歩で有名になっている影響で、php-general メーリングリストの流量も増加しています (今のところ、1日あたり75?200通の流量があります)。 なので、参加者全員の利益のために、メーリングリストは 他のどこを当たっても駄目だった場合の最後の手段にしてください。

メーリングリストに投稿する前に、 この FAQ とマニュアルを見て手がかりを探してください。 もし駄目なら次にメーリングリストのアーカイブをチェックしてください (上記参照)。もし、PHP のインストール、 もしくは設定で問題が起こっている場合は (ソースアーカイブに含まれる)すべてのドキュメントと README ファイルに目を通してください。 それでも問題が解決できない場合に、 適切なメーリングリストを使用することは大歓迎です。

適切な回答を得るため (そして他の開発者たちをいらつかせないため) にも、 質問は適切なメーリングリストに行うようにしましょう。 たとえば、PHP のインストールがうまくいかない場合には php-install メーリングリストを使用します。 注意: 名前はよく似ているけど使われかたはまったく異なるメーリングリストもあります。 Windows 上での PHP スクリプトの実行に関する質問は Windows PHP users メーリングリストへ行います。 Windows Internals メーリングリストではありません。

メーリングリストに投稿するときには、どんな情報を含めればよいのですか?

「PHP が動作しません。助けて! 何がおかしいのですか?」 といった投稿は間違いなく誰にとっても無意味なものです。 もしPHPが動作しないのであれば、 あなたが使用しているオペレーティングシステム、PHPのバージョン、 またそれをどのように手に入れたか(コンパイル済みだった、 Git から手に入れた、RPM で提供されたものだった、等) 動作させようとしてあなたはどんなことをしたのか、 どこであなたは行き詰まって、どんなエラーメッセージが出るのか、 どんな結果になるのかといった情報を記述する必要があります。

これは他のどんな問題にも当てはまることです。あなたは、何をしたのか、 何をしようとしているのか、そして何かエラーが出たのかを記述してください。 もしあなたが書いた PHP のプログラムで問題が起こった場合は、 動作しない個所のソースコードを含め、 どの行で問題が起こったのかをコメントしておく必要があります。 でも、必要以上のソースコードは含めないでください! さもないと、 あなたの投稿は非常に読みにくいものとなり、 多くのひとはこうした投稿を読み飛ばしてしまいます。 もし、どれくらいの情報を含めればいいのか分からない場合には、 あなたが十分だと思うだけの情報を記述するようにしましょう。 そして、より詳しい情報を求められたときのために準備をしておきます。

もう一つ重要な点があります。 それは Subject であなたの問題を端的に表すことです。 「助けてーー!」とか「何かおかしいのでしょうか?」といった Subject のついたメールはほとんど人に無視されてしまいます。

そして最後に、 » How To Ask Questions The Smart Way にあるペーパーを読むことをお薦めします。 このペーパーはあらゆる人、 特にあなた自身にとって多いに参考になるはずです。


PHP を手に入れるには

このセクションでは、PHP をダウンロードする詳しい場所や OS に関する話題を扱います。

  1. PHPはどこで手に入れることができますか？
  2. コンパイル済みのバージョンはありますか？
  3. 一部のPHP拡張モジュールのコンパイルに必要なライブラリはどこで手に入りま すか？
  4. 上記のライブラリはどのように使うのですか？
  5. Gitリポジトリから最新のPHPソースコードを手に入れました。Windows上でコン パイルするにはどうしたらよいですか？
  6. ブラウザキャパビリティファイルはどこで手に入りますか？
  7. PHP をダウンロードするときの「スレッドセーフ」の意味は?
PHPはどこで手に入れることができますか？

PHPネットワークのどのメンバーのサイトからでもダウンロードすることができ ます。これらは» https://www.php.net/ から見つけることができます。また匿名 Gitを使って最新のソースコードを手に入れることもできます。詳しい情報は、 » https://www.php.net/git.php を参照ください。

コンパイル済みのバージョンはありますか？

私たちはWindows版のみコンパイル済みのバイナリを配布しています。というの もPHPをすべてのLinux/Unixのプラットホーム用にすべての拡張モジュールの組 み合わせでコンパイルするのは不可能だからです。ただ、最近の多くのLinuxディ ストリビューションには予めPHPがインストールされています。Windows用のバイ ナリは» ダウンロードページ からダウンロードすることができます。Linux用のバイナリについてはあなたが 使用しているディストリビューションのウェブサイトを訪れてください。

一部のPHP拡張モジュールのコンパイルに必要なライブラリはどこで手に入りま すか？

注意: *印がついているものはスレッドセーフではないと見なされています。 マルチスレッド環境では使わないことをおすすめします。

  • » LDAP (Unix).
  • » LDAP (Unix/Win) : Mozilla Directory (LDAP) SDK
  • » free LDAP server.
  • » Berkeley DB2 (Unix/Win) : http://www.sleepycat.com/.
  • » SNMP* (Unix): .
  • » GD (Unix/Win).
  • » mSQL* (Unix).
  • » PostgreSQL (Unix).
  • » IMAP* (Win/Unix).
  • » Sybase-CT* (Linux, libc5) : Available locally.
  • » FreeType (libttf):.
  • » ZLib (Unix/Win32).
  • » expat XML parser (Unix/Win32).
  • » PDFLib.
  • » mcrypt.
  • » mhash.
  • » t1lib.
  • » dmalloc.
  • » aspell.
  • » readline.

上記のライブラリはどのように使うのですか？

個々のライブラリで提供される情報に従ってください。いくつかのライブラリ (GD等)は、PHPのconfigureスクリプト実行時に自動的に検出されます。その他の ライブラリに関してはconfigureスクリプトのオプションに '--with-EXTENSION'オプションを追加すること使用できます。 'configure --help'を実行するとこれらのオプション一覧が 表示されます。

Gitリポジトリから最新のPHPソースコードを手に入れました。Windows上でコン パイルするにはどうしたらよいですか？

最新情報は、PHP Wiki の » Step by Step Build Instructions を参照ください。

ブラウザキャパビリティファイルはどこで手に入りますか？

browscap.iniファイルは » http://browscap.org/で 手に入れることができます。

PHP をダウンロードするときの「スレッドセーフ」の意味は?

スレッドセーフである、というのは、Windows 上の Apache 2 のような マルチスレッドのウェブサーバーでも動作するバイナリだという意味です。 スレッドごとにローカルストレージのコピーを作成し、 別のスレッドとデータの衝突を起こさないようにしています。

それで、結局どっちを選べばいいのかですって? もし PHP を CGI として動かすつもりなら、スレッドセーフでなくてもかまいません。 リクエストのたびにバイナリが起動するからです。IIS5 や IIS6 といったマルチスレッドのウェブサーバーで動かす場合は、 スレッドセーフ版の PHP を選ばなければなりません。


データベースに関する問題

このセクションでは PHP とデータベースとの関係に関する一般的な質問を 扱います。なんと! PHP は事実上あらゆるデータベースにアクセスすることが できます。

  1. PHP は Microsoft SQL Server にアクセスできると聞きました。どうすれば よいのでしょうか？
  2. Microsoft Access データベースにアクセスできますか？
PHP は Microsoft SQL Server にアクセスできると聞きました。どうすれば よいのでしょうか？

Unix マシン上では、PDO_ODBC や Unified ODBC API が使えます。

Windows マシン上では、PDO_SQLSRV や SQLSRV も使えます。

次の質問に対する回答も参照ください。

Microsoft Access データベースにアクセスできますか？

Unix で PHP を動作させて Windows マシンで動作する MS Access に接続したい場合には Unix ODBC ドライバが必要です。» OpenLink Software が Unix ベースの ODBC ドライバを提供しています。

他には、Microsoft SQL Server に ODBC ドライバを使用してデータを 保存するという手段もあります。これによって、Microsoft Access (ODBC を使用します) と PHP (組み込まれているドライバを使用します) でデータに アクセスすることができます。また、Microsoft Access と PHP 両者共に 解釈可能な中間ファイル(例えば単層からなるファイルや、dBase データベース等)を使用する手もあります。これに関しては OpenLink Software の Tim Hayes が以下のように述べています。

PHP からじかに ODBC ドライバが使用できる場合(つまり OpenLink の ドライバを使用している場合)には、他のデータベースを中継手段として 用いることはよいアイデアとは言えない。どうしても中間ファイルが 必要な場合のために、OpenLink は NT、Linux、そして他の Unix 用の Virtuoso(仮想データベースエンジン)をリリースした。私たちの » ウェブサイトを 訪れてもらえれば、無料でダウンロードできる。

うまくいくことが分かってるもう一つの方法は、MySQL と Windows 用の MyODBC ドライバを利用してデータベースを同期する方法です。Steve Lawrence が言うには、

  • MySQL を説明に従って任意のプラットフォームにインストールします。 最新バージョンは » http://www.mysql.com/ にあります。データベースを作成するとき、そしてユーザーアカウントを を設定するときに、ホストフィールドに % か MySQL を使って アクセスする Windows マシンのホスト名を入力する、ということ以外には 特別な設定は必要ありません。 使用するサーバー名、ユーザー名、パスワードを書きとめておいてください。
  • MySQL サイトから Windows 用 MyODBC ドライバをダウンロードします。 それを Windows マシンにインストールします。 アーカイブに含まれるユーティリティプログラムで、 テストを行うことができます。
  • コントロールパネルの ODBC administrator を使用して、ユーザー もしくはシステム DSN を作成します。DSN 名を決定して、Step1 で MySQL に設定したホスト名、ユーザー名、パスワード、ポート等を入力します。
  • Access をフルインストールでインストールします。これは適切な アドインをインストールするためです。少なくとも ODBC サポートと リンクテーブルマネージャが必要です。
  • ここからがお楽しみです。新規データベースを作成しましょう。 テーブルウィンドウで右クリックしてリンクテーブルを選択します。 もしくはファイルメニューから外部データの取り込みを選び リンクテーブルを選択します。ファイルブラウザが表示されたら ファイルタイプから ODBC を選択します。次にシステム DSN で 選択肢 STEP3 で作成した DSN 名を選択します。リンクするテーブルを 選んで OK ボタンを押しましょう。MySQL サーバーでテーブルを オープンできるようになっていて、データの追加/削除/編集ができるように なっています。さらに、クエリの構築、テーブルのインポート/エクスポート、 フォームやレポートの構築等が可能です。

Tips and Tricks(役に立つヒント):

  • Access でテーブルを作成してそれを MySQL へエクスポートします。 それを再度アクセスからリンクすれば素早くテーブルを作成すること ができます。
  • Access でテーブルを作成するときは、そのテーブルに書き込み権限を もたせるためにプライマリキーを設定しておく必要があります。 Access とテーブルをリンクする前に MySQL にプライマリキーを設定 しておくことも忘れないでください。
  • MySQL 側でテーブル(の構成)を変更した場合、再度 Access とリンクする 必要があります。ツール>アドイン>リンクテーブルマネージャから 適切な ODBC DSN を選んで再リンクが必要なテーブルを選択します。 また、ここで OK ボタンを押す前に「リンク先を更新するための プロンプトを毎回表示する」をチェックしておけば DSN ソースを 移動させることができます。


インストール

このセクションでは PHP のインストール方法に関する一般的な質問を扱います。 PHP は、ほとんど全ての OS とウェブサーバーで 利用可能です。

PHP をインストールするには、インストールと設定 の指示に従ってください。

  1. なぜ、Apache 2 のマルチスレッド MPM モードを実運用環境で使用するべきではないのですか?
  2. Unix/Windows: php.ini ファイルはどこに置けばよいのですか?
  3. Unix: PHP をインストールしましたが、ファイルをロードするたびに 'Document Contains No Data(ページが表示できません)' という メッセージが表示されます。何が起こっているのですか?
  4. Unix: RPM を使って PHP をインストールしたのですが、Apache が PHP のページを 処理してくれません。何が起こっているのですか?
  5. Unix: Apache に FrontPage 拡張モジュールのパッチを当てたら、突然 PHP が動作しなくなってしまいました。PHP は Apache の FrontPage 拡張モジュールと共存することはできないのですか?
  6. Unix/Windows: PHP をインストールしたのですがブラウザから PHP スクリプトにアクセスしても何も表示されません。
  7. Unix/Windows: PHP をインストールしたのですがブラウザから PHP スクリプトにアクセスすると Internal Server Error 500 となってしまいます。
  8. PHP をインストールするまではエラーもなく問題なく進んだのですが、 Apache を起動させようとすると undefined symbol エラーが発生します。 [mybox:user /src/php5] root# apachectl configtest apachectl: /usr/local/apache/bin/httpd Undefined symbols: _compress _uncompress
  9. Windows: PHP をインストールしたのですがブラウザから PHP スクリプト にアクセスすると次のようなエラーが出力されます。 cgi error: The specified CGI application misbehaved by not returning a complete set of HTTP headers. The headers it did return are:
  10. Windows: 全ての説明に従っているのに PHP が IIS で動作しません!
  11. IIS, PWS, OmniHTTPD, Xitami上でCGIとしてPHPを実行するとき、 次のようなエラーが出る:Security Alert! PHP CGI cannot be accessed directly.
  12. php.ini が認識され読み込まれていることをどうやって知ることが できますか? 自分の行った変更が反映されてないらしいのですが。
  13. Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?
  14. Windows 上の PHP で、php.ini を使えるようにするにはどうしたらいいのですか?
  15. Apache のコンテントネゴシエーション（MultiViews オプション）を PHP で使用することはできますか?
  16. PHP が処理できるリクエストメソッドは GET および POST だけなのですか?
なぜ、Apache 2 のマルチスレッド MPM モードを実運用環境で使用するべきではないのですか?

PHP はグルー(糊)です。このグルーは、多くのサードパーティ製のライブラリを くっつけることによりクールな Web アプリケーションを構築するために使用され、 直観的で簡単に習得できる言語インターフェイスにより、一つの整合性のある実体として 見せることができます。 PHP の柔軟性と力は、プラットフォームの安定性と堅牢性に基づいています。 グルーによる結合をするためには、OS や Web サーバー、サードパーティ製のライブラリが必要です。 これらの一つの機能が停止した場合、PHP は問題を特定し、速やかに修正する 手段が必要です。 実行スレッドを完全に分離しなかったり、 メモリセグメントを完全に分離しなかったり、 各リクエストで使用される強力なサンドボックスを有さないことで、 基本的なフレームワークをより複雑なものにした場合、 PHP のシステムに弱点が生まれます。

マルチスレッド MPM を使いたい場合は、 PHP が自分のメモリ空間で実行される FastCGI の設定をみてください。

Unix/Windows: php.ini ファイルはどこに置けばよいのですか?

UNIX の場合、デフォルトでは /usr/local/lib です。コンパイル時に --with-config-file-path オプションを使用してこの場所を変えたいという人も多いでしょう。 例えばこのようにすることも出来ます：

--with-config-file-path=/etc
そしてディストリビューションの php.ini-development を /etc/php.ini にコピーし、環境に合うように 編集してください。

--with-config-file-scan-dir=PATH

Windows の場合、php.ini のデフォルトパスは Windows ディレクトリになります。 Apache ウェブサーバーを使っている場合はまず Apache がインストールされているディレクトリ (例えば c:\program files\apache group\apache にある php.ini を探そうとします。このため、異なる php.ini ファイルを異なるバージョンの Apache ごとに置いておくことができます。

設定ファイルの章も参照ください。

Unix: PHP をインストールしましたが、ファイルをロードするたびに 'Document Contains No Data(ページが表示できません)' という メッセージが表示されます。何が起こっているのですか?

これはおそらく PHP に何らかの問題が起こっていてコアダンプしている という状態です。サーバーのエラーログを見てこのケースかどうかチェック してください。そして小さなテストケースで問題を再現させてみてください。 もし 'gdb' の使い方が分かるならバグレポートに加えてバックトレースを 提供してもらえると開発者が問題の箇所を突き止めるのに 非常に役立ちます。もしあなたがPHPをApacheモジュールとして使用している 場合は以下のようにします：

  • httpd を停止します

  • gdb httpd

  • Stop your httpd processes

  • > run -X -f /path/to/httpd.conf

  • ブラウザから問題のある URL にアクセスします

  • > run -X -f /path/to/httpd.conf

  • もしコアダンプが発生すると gdb が知らせてくれます

  • bt とタイプします

  • このバックトレースをバグレポートに含めてください。バグレポートは » https://github.com/php/php-src/issues から送信してください。

もしそのスクリプトが正規表現関数 (preg_match() やその類似関数) を使用している場合、 PHP と Apache が同じ正規表現のパッケージを使用してコンパイルされているかどうかを確認してください。 PHP と Apache 1.3.x を使用している場合は常に確認が必要です。

Unix: RPM を使って PHP をインストールしたのですが、Apache が PHP のページを 処理してくれません。何が起こっているのですか?

あなたが Apache と PHP の両方を RPM でインストールしたとすると、以下に示す 内容の一部もしくは全てを httpd.conf ファイルに追加するか、コメントを 外す必要があります：

# Extra Modules
AddModule mod_php.c
AddModule mod_perl.c

# Extra Modules
LoadModule php_module         modules/mod_php.so
LoadModule php5_module        modules/libphp5.so
LoadModule perl_module        modules/libperl.so
そして以下の行：
AddType application/x-httpd-php .php
以上の内容を全体設定、もしくは PHP サポートを追加したいバーチャル ドメインの設定に加えてください。

Unix: Apache に FrontPage 拡張モジュールのパッチを当てたら、突然 PHP が動作しなくなってしまいました。PHP は Apache の FrontPage 拡張モジュールと共存することはできないのですか?

いいえ。PHP は FrontPage 拡張モジュールと問題なく共存できます。 問題は FrontPage 拡張モジュールのパッチが PHP が依存している Apache の 構造の一部を変更してしまうことにあります。パッチを当てた後で PHP を再コンパイル('make clean; make' としてください)すれば問題は 解決されます。

Unix/Windows: PHP をインストールしたのですがブラウザから PHP スクリプトにアクセスしても何も表示されません。

ブラウザの「ソースの表示」を実行してください。おそらく PHP の ソースコードが表示されると思います。これはウェブサーバーがスクリプトを PHP に渡していないためスクリプトが実行されていない、ということを 意味します。サーバー側の設定のどこかが間違っているはずですので、 PHP インストールマニュアルに従って再度入念に設定を確認してみてください。

Unix/Windows: PHP をインストールしたのですがブラウザから PHP スクリプトにアクセスすると Internal Server Error 500 となってしまいます。

ウェブサーバーが PHP を実行するときに何らかの問題が起きています。 どんなエラーが起こっているか確認するために、コマンドラインで PHP 実行ファイル(Windows では php.exe) のある ディレクトリに移動して php -i を実行してください。 もし PHP の実行時に問題があった場合は適切なエラーメッセージが表示されるので、 それを手がかりに次に何をすべきかを知ることができます。画面 一杯に HTML(phpinfo() 関数の出力)が表示された場合には PHP は問題なく動作していますので、問題はウェブサーバーの設定 にあるはずです。再度入念にチェックしてみてください。

PHP をインストールするまではエラーもなく問題なく進んだのですが、 Apache を起動させようとすると undefined symbol エラーが発生します。
[mybox:user /src/php5] root# apachectl configtest
 apachectl: /usr/local/apache/bin/httpd Undefined symbols:
  _compress
  _uncompress

これは、PHP とは関係なく MySQL クライアントライブラリの問題です。 このライブラリのうちある種のものは --with-zlib を指定する必要がありますが、 他のものは必要ありません。この問題は MySQL FAQ でも扱われています。

Windows: PHP をインストールしたのですがブラウザから PHP スクリプト にアクセスすると次のようなエラーが出力されます。
cgi error:
 The specified CGI application misbehaved by not
 returning a complete set of HTTP headers.
 The headers it did return are:

このエラーメッセージは PHP が(何らかの理由で)何も出力できなかった ことを意味します。詳細なエラーメッセージを得るためには、 コマンドラインから PHP 実行ファイル(Windows では php.exe)のあるディレクトリに移動して php -i を実行してください。もし PHP の実行時に問題 があった場合は適切なエラーメッセージが表示されるのでそれを 手がかりに次に何をすべきかを知ることができます。画面一杯に HTML (phpinfo()関数の出力) が表示された場合には PHP は問題なく動作しています。

PHP がコマンドラインで動作したなら、再度ブラウザから PHP スクリプトに アクセスしてみてください。もしまだ失敗するようなら以下のいずれかの 理由によるものと思われます。

  • PHP スクリプト、 php.exe、php5ts.dll、 php.ini もしくはロードしようとしている PHP 拡張モジュールの ファイルパーミッションが匿名インターネットユーザー IUSER_<machinename> にアクセスできない ものになっている。
  • スクリプトが存在しない(もしくはあなたが在ると思っている場所と ウェブサーバーのルートディレクトリからの相対位置がずれている)。 IIS を使用している場合は、Internet Service Manager でスクリプト マッピングを設定するときに「ファイルの存在を確認する」にチェックを することでこのエラーをトラップすることができます。もしスクリプト ファイルが存在しない場合はサーバーが代わりに 404 エラーを返すように なります。これにはもう一つ利点があります。それは IIS が スクリプトファイルの NTLanMan パーミッションに応じて認証を要求する ようになる、ということです。
Windows: 全ての説明に従っているのに PHP が IIS で動作しません!

PHP スクリプトを実行しようとするあらゆるユーザーが php.exe の実行権限を必要としているということを 忘れないでください。IIS はインストール時に追加された匿名ユーザーを使用 します。このユーザーに対して php.exe の実行権限が 必要です。また、認証された全てのユーザーに関しても php.exe の実行権限が必要です。IIS4 の場合はさらに PHP がスクリプトエンジンであるということを教えてやる必要があります。 この FAQ も読んでください。

IIS, PWS, OmniHTTPD, Xitami上でCGIとしてPHPを実行するとき、 次のようなエラーが出る:Security Alert! PHP CGI cannot be accessed directly.

cgi.force_redirect に 0 をセットしてください。デフォルトでは 1 にセットされていますので、そのディレクティブが ; でコメントアウトされていないことを確認してください。 他のディレクティブと同様にこれは php.ini 上でセットされます。

デフォルトは 1 なので、100% 正しく php.ini ファイルが 読み込まれているかどうかが重要です。 詳細はこの FAQ を 読んでください。

php.ini が認識され読み込まれていることをどうやって知ることが できますか? 自分の行った変更が反映されてないらしいのですが。

php.ini とそれが PHP に読み込まれているかを確認するには phpinfo() をコールして最初のほうに 表示されている Configuration File (php.ini) を見てください。これは PHP が認識している php.ini と、それが 読み込まれているか否かを示しています。ディレクトリパスだけが 表示されている場合は、読み込まれていないということなので、 そのディレクトリに php.ini を置いてください。 php.ini が PATH にある場合それが読み込まれます。

php.ini が読み込まれていてかつ PHP をモジュールとして実行 している場合、php.ini を変更した後で必ず Web サーバーを 再起動してください。

php_ini_loaded_file() も参照ください。

Windows で PHP のディレクトリを PATH に追加するにはどうすればいいのですか?

Windows では、以下のようにします。

  • コントロールパネルのシステムアイコンを選択します（スタート → コントロールパネル）。

  • 詳細設定タブに移動します。

  • 「環境変数」ボタンを押します。

  • 「システム環境変数」欄を見ます。

  • Path というエントリを見つけます（スクロールする必要があるかもしれません）。

  • Path のエントリをダブルクリックします。

  • その最後に ';' と追加し、その後に PHP のディレクトリを追加します （例: ;C:\php）。

  • OK を押します。

注意: 上の作業を行った後は、必ずコンピュータを再起動し、 PATH の変更が適用されていることを確認しましょう。

Windows 上の PHP で、php.ini を使えるようにするにはどうしたらいいのですか?

いくつかの方法があります。Apache を使用しているのなら、 Apache のドキュメントを参照ください。 それ以外の場合は、環境変数 PHPRC を指定する 必要があります。

Apache のコンテントネゴシエーション（MultiViews オプション）を PHP で使用することはできますか?

もしリンクする PHP ファイルが拡張子を持っているなら、すべては うまく動作します。この FAQ が対象としているのは、リンクする PHP ファイルが拡張子を持っておらず、拡張子のない URL から PHP ファイルを判別するためにコンテントネゴシエーションを使用する方法です。 この場合、AddType application/x-httpd-php .php という行を以下のように変更します。

AddHandler php5-script php
AddType text/html php
この方法は、Apache 1 ではうまく動作しません。なぜなら PHP モジュールが php-script をキャッチできないからです。

PHP が処理できるリクエストメソッドは GET および POST だけなのですか?

いいえ、それ以外のいかなるメソッド（例: CONNECT）でも扱えます。 適切な応答ステータスは、header() を使用して送信可能です。 GET および POST だけを処理したいなら、Apache の設定を以下のようにします。

<LimitExcept GET POST>
Deny from all
</LimitExcept>


構築時の問題

本節は、構築時に発生する多くの一般的なエラーを集めたものです。

  1. anonymous Git サービスで最新版の PHP を入手しましたが、 configure スクリプトがありません!
  2. PHPをApacheと組みあわせて動作するようにconfigureを行う際に問題が あります。httpd.hが見付からないといわれますが、 指定した場所にこのファイルはあるのです!
  3. PHPをconfigureしているときに (./configure) 以下のようなエラーに遭遇しました。 checking lex output file root... ./configure: lex: command not found configure: error: cannot find output from lex; giving up
  4. Apacheを起動するときに以下のようなメッセージが出る: fatal: relocation error: file /path/to/libphp4.so: symbol ap_block_alarms: referenced symbol not found
  5. configureを実行した際、GD、gdbmまたは他のパッケージのファイルま たはライブラリを見つけることができないと言われます。
  6. ファイルlanguage-parser.tab.cをコンパイルする際、 'yytname undeclared'というエラーが発生します。
  7. makeを実行する際、実行には成功しているようですがコンパイルする 最終的なアプリケーションをリンクしようとした際に何かファイルが見 つからないというエラーが発生します。
  8. PHP をリンクする際、未定義の参照があるというエラーが複数発生します。
  9. インストール手順に完全に従ってUnix上でApacheモジュール版をインス トールしましたが、ブラウザでアクセスするとPHPスクリプトが表示さ れ、ファイルを保存しますかと尋ねられます。
  10. --activate-module=src/modules/php4/libphp4.a と書いてありますが、ファイルがありません。このため、 --activate-module=src/modules/php4/libmodphp4.aに 変更しましたが、やはりだめです。何が起きているのでしょう?
  11. --activate-module=src/modules/php4/libphp4.a を指定し、PHPを静的モジュールとして組み込んでApacheを構築しよう とした際に、システムがANSI対応ではないというエラーを発生します。
  12. --with-apxs を指定して PHP を構築しようとした際、奇妙なエラーメッセージが出力されます。
  13. makeの間、microtimeおよび RUSAGE_関連で多くのエラーを発生します。
  14. MySQLを使用できるようにPHPをコンパイルする際、configureは正常に 実行されるがmakeの最中に以下のようなエラーが出る: ext/mysql/libmysqlclient/my_tempnam.o(.text+0x46): In function my_tempnam': /php4/ext/mysql/libmysqlclient/my_tempnam.c:103: the use of tempnam' is dangerous, better use mkstemp' 何がおかしいのか？
  15. PHPをアップグレードしたいのですが、現在インストールされているPHPを 構築するときに指定した./configureコマンドの オプションはどこで知ることが出来ますか？
  16. GDライブラリをリンクしてPHPを構築すると、コンパイルエラーが発生したり 実行時にセグメンテーション違反になってしまいます。
  17. PHP をコンパイルする際に、よくわからないエラーが発生してハングアップ します。Solaris を使用している場合に起こるようです。
anonymous Git サービスで最新版の PHP を入手しましたが、 configure スクリプトがありません!

configure.inからconfigureスクリプトを生成するためには、GNU autoconfパッケージが必要です。Gitサーバーからソースを入手した後、 最上位のディレクトリで./buildconfを実行して下 さい。(また、configure に --enable-maintainer-modeオプションを付けて実 行した場合以外は、configureスクリプトはconfigure.in ファイルが更新された際に自動的に再構築を行いません。このため、 configure.inが 変更された場合には忘れずに手動で再構築を行う必要があります。 再構築の際に行われることの１つは、configureまたは config.statusを 実行した後、Makefileの中の@VARIABLE@のような物を見つけることです。)

PHPをApacheと組みあわせて動作するようにconfigureを行う際に問題が あります。httpd.hが見付からないといわれますが、 指定した場所にこのファイルはあるのです!

configure/setupスクリプトにApacheソースツリーの最上位の場所を指 定する必要があります。これは、--with-apache=/path/to/apache を指定するのであった、--with-apache=/path/to/apache/src ではないということです。

PHPをconfigureしているときに (./configure) 以下のようなエラーに遭遇しました。

checking lex output file root... ./configure: lex: command not found
configure: error: cannot find output from lex; giving up

インストールの説明をよく読み、 PHPのコンパイルにはflexとbisonの両方が必要であることに留意してください。 ソースかあるいはRPMのようなパッケージからbisonとflexを インストールしてください。

Apacheを起動するときに以下のようなメッセージが出る:

fatal: relocation error: file /path/to/libphp4.so:
symbol ap_block_alarms: referenced symbol not found

ApacheのcoreプログラムがsharedなDSOライブラリとして コンパイルされている場合にこのエラーが出ます。 最低でも以下のフラグを使用してApacheを再configureして ください:

--enable-shared=max --enable-rule=SHARED_CORE

詳細はApacheのソースディレクトリのトップレベルにある INSTALLファイル またはApacheの » DSO manual pageをご覧ください。

configureを実行した際、GD、gdbmまたは他のパッケージのファイルま たはライブラリを見つけることができないと言われます。

Cプリプロセッサおよびリンカに次のように追加でフラグを指定するこ とにより、configureスクリプトがヘッダファイルまたはライブラリを 標準以外の場所で探すことが可能となります。

    CPPFLAGS=-I/path/to/include LDFLAGS=-L/path/to/library ./configure
ログインシェルとしてcsh系のシェルを使用している場合、次のように なります。
    env CPPFLAGS=-I/path/to/include LDFLAGS=-L/path/to/library ./configure

ファイルlanguage-parser.tab.cをコンパイルする際、 'yytname undeclared'というエラーが発生します。

bisonのバージョンを更新する必要があります。最新版は、 » http://www.gnu.org/software/bison/bison.htmlにあります。

makeを実行する際、実行には成功しているようですがコンパイルする 最終的なアプリケーションをリンクしようとした際に何かファイルが見 つからないというエラーが発生します。

古いバージョンのmakeには、functionsディレクトリにあるファイルの コンパイルされたものを同じディレクトリに正しく入れないものがあり ます。cp *.o functionsを試しに実行してから make を再度実行し、解決されるか確認して下さ い。解決される場合には、GNU makeの最近のバージョンに更新するべき です。

PHP をリンクする際、未定義の参照があるというエラーが複数発生します。

最後に適切なライブラリが全てインクルードされているかどうか 確認してください。よくあるのは、'-ldl' や 指定したデータベースのサポート機能に必要なライブラリの指定が欠けているというものです。

何名かの人から、Apache とリンクする際に 'libphp4.a' の直後に '-ldl' を追加する必要があることも報告されています。

インストール手順に完全に従ってUnix上でApacheモジュール版をインス トールしましたが、ブラウザでアクセスするとPHPスクリプトが表示さ れ、ファイルを保存しますかと尋ねられます。

これは、何らかの理由によりPHPモジュールが起動していないことを意 味しています。助けを求める質問を行う前にまず以下を確認ください。

  • 実行しているhttpdバイナリが構築したばかりの新しいhttpdバイナ リであることを確認してください。確認を行うには以下のように入力 します。 /path/to/binary/httpd -l mod_php4.c がリストの中にない場合、正し いバイナリが実行されていません。正しいバイナリを見つけて、イ ンストールしてください。
  • Apache .conf ファイルの１つに正しいMIME型 が追加されていることを確認してください。これは以下のようになります。 AddType application/x-httpd-php .php また、このAddTypeの行が、 <Virtualhost> または <Directory> ブロックの中に隠 されて、テスト用のスクリプトの場所に適用できていないようなこ とがないことを確認してください。
  • 最後に、デフォルトのApache設定ファイルの場所はApache 1.2と Apache 1.3の間で変更されています。AddTypeの行を追加した設定ファ イルが実際に読み込まれていることを確認してください。このファイ ルが正しく読み込まれている場合には、明らかな構文エラーを httpd.confファイルの中に書き込んでしまったり、何らかの明らか な変更があった可能性があります。

--activate-module=src/modules/php4/libphp4.a と書いてありますが、ファイルがありません。このため、 --activate-module=src/modules/php4/libmodphp4.aに 変更しましたが、やはりだめです。何が起きているのでしょう?

libphp4.aファイルはこの時点では存在しない、ということに気をつけてください。 このファイルは、Apacheの構築時に自動的に作成されます。

--activate-module=src/modules/php4/libphp4.a を指定し、PHPを静的モジュールとして組み込んでApacheを構築しよう とした際に、システムがANSI対応ではないというエラーを発生します。

Apacheのこのエラーメッセージは紛らわしく、より新しいバージョンで は修整されています。

--with-apxs を指定して PHP を構築しようとした際、奇妙なエラーメッセージが出力されます。

ここでは、確認すべきことが3点あります。まず、何らかの理由により、 Apacheがapxs Perlスクリプトを構築する際に適当なコンパイラやフラ グ変数を付けないで構築されてしまうことが時々あります。 使用するapxsの場所を見つけたら(which apxsコマンドを 試してみてください。/usr/local/apache/bin/apxs または/usr/sbin/apxs等にあります)、 以下の行を確認してください。

my $CFG_CFLAGS_SHLIB  = ' ';          # substituted via Makefile.tmpl
my $CFG_LD_SHLIB      = ' ';          # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = ' ';          # substituted via Makefile.tmpl
上記のようになっている場合は問題です。これらの行は空白になっているか 'q()'のような正しくない値になっていると思います。これを以下のように 変更してください。
my $CFG_CFLAGS_SHLIB  = '-fpic -DSHARED_MODULE'; # substituted via Makefile.tmpl
my $CFG_LD_SHLIB      = 'gcc';                   # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = q(-shared);              # substituted via Makefile.tmpl
可能性のある第2の問題は、RedHat-6.1と6.2でのみ存在する問題です。 RedHatが出荷した apxs スクリプトは壊れています。以下の行を見てください。
my $CFG_LIBEXECDIR    = 'modules';         # substituted via APACI install
上の行がある場合、これを次のように変更してください。
my $CFG_LIBEXECDIR    = '/usr/lib/apache'; # substituted via APACI install
最後に、Apacheのconfigure/再インストールを行います。その際、 ./configure とmakeの間に make cleanを行ってください。

makeの間、microtimeおよび RUSAGE_関連で多くのエラーを発生します。

インストール時にmakeを行っている際、以下のようなエラーを発生す るとした場合、

microtime.c: In function `php_if_getrusage':
microtime.c:94: storage size of `usg' isn't known
microtime.c:97: `RUSAGE_SELF' undeclared (first use in this function)
microtime.c:97: (Each undeclared identifier is reported only once
microtime.c:97: for each function it appears in.)
microtime.c:103: `RUSAGE_CHILDREN' undeclared (first use in this function)
make[3]: *** [microtime.lo] Error 1
make[3]: Leaving directory `/home/master/php-4.0.1/ext/standard'
make[2]: *** [all-recursive] Error 1
make[2]: Leaving directory `/home/master/php-4.0.1/ext/standard'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/home/master/php-4.0.1/ext'
make: *** [all-recursive] Error 1

あなたのシステムは壊れています。使用しているglibcと同じバージョンの glibc-develパッケージをインストールして、/usr/include ファイルを修正 する必要があります。この問題は、PHPの動作とは全く関係ありません。 これを示すには、次のような簡単なテストを行ってみてください。

$ cat >test.c <<X
#include <sys/resource.h>
X
$ gcc -E test.c >/dev/null
これが、エラーが発生する場合、インクルードファイルが見つからない ことがわかります。

MySQLを使用できるようにPHPをコンパイルする際、configureは正常に 実行されるがmakeの最中に以下のようなエラーが出る: ext/mysql/libmysqlclient/my_tempnam.o(.text+0x46): In function my_tempnam': /php4/ext/mysql/libmysqlclient/my_tempnam.c:103: the use of tempnam' is dangerous, better use mkstemp' 何がおかしいのか？

まず、これはWarningであって致命的な エラーではないと認識することが重要です。makeの 最後のほうでこの出力がしばしば見られるため致命的なエラーと 思われがちですがそうではありません。もちろん、Warningが 起きるとコンパイラが停止するような設定をしている場合は別です。 また、MySQLサポートはデフォルトで構築されることにも 留意してください。

注意:

PHP4.3.2以降、ビルド(make)完了後に以下のようなテキストが出る ことがあります:

Build complete.
(It is safe to ignore warnings about tempnam and tmpnam).

PHPをアップグレードしたいのですが、現在インストールされているPHPを 構築するときに指定した./configureコマンドの オプションはどこで知ることが出来ますか？

現在インストールされているPHPを構築した時のディレクトリにある config.nice ファイルを見るか、もしもうそのディレクトリが無い場合は

<?php phpinfo(); ?>
というスクリプトを実行すれば、最初の方にある./configure という箇所に表示されます。

GDライブラリをリンクしてPHPを構築すると、コンパイルエラーが発生したり 実行時にセグメンテーション違反になってしまいます。

リンクしたGDライブラリとPHPが同じライブラリ(例えばlibpng)に依存しているか どうかを確認してください。

PHP をコンパイルする際に、よくわからないエラーが発生してハングアップ します。Solaris を使用している場合に起こるようです。

PHP のコンパイル時に 非 GNU ツールを使用すると問題を引き起こします。 PHP を正しくコンパイルするには、GNU ツールを使用することを忘れないで ください。たとえば、Solaris で使用される SunOS BSD 互換の sed や Solaris 版の sed は正しく動作しません。しかし、 GNU 版もしくは Sun POSIX (xpg4) 版の sed ならうまく 動きます。以下を参照ください。 » GNU sed、 » GNU flex および » GNU bison 。


PHP の使いかた

このセクションにはPHPスクリプトを書くにあたってよく問題となる事柄が 集められています。

  1. PHP の関数のパラメータの順番を覚えられません。だって関数によってばらばらなんだもん。
  2. あらゆるフォームから送信されたデータを扱うことができる汎用的な PHPスクリプトを書きたいのですが、POSTメソッドでどのようなデータ が送信されたかを知るにはどうするのですか？
  3. シングルクオート(')をバックスラッシュでエスケープされた シングルクオート(\')に変換しなければならないのですが、 正規表現を用いてこれを行うにはどの様にするのですか？ 同様に " を \" に、\ を \\ に変換したいのです。
  4.       次のようなコードを実行すると、思った通りの順番で出力が表示されません。

function myfunc($argument)
{
    echo $argument + 10;
}
$variable = 10;
echo "myfunc($variable) = " . myfunc($variable);

      なぜですか？
  5. 改行されないのですが？ <pre> <?php echo "これは1行目"; ?> <?php echo "この行は改行に続いて出力されるはず"; ?> </pre>
  6. 'Warning: Cannot send session cookie - headers already sent...'や 'Cannot add header information - headers already set...'といった メッセージが出力されるのですが。 sent...'.
  7. リクエストヘッダに直接アクセスしたいのですが、どうすればよいですか？
  8. IISで認証を行おうとすると'No Input file specified'というエラーが 発生します。
  9. Windows: 他のコンピュータと共有しているファイルに、IIS でアクセスできません。
  10. どうすればXMLとPHPは共存することが出来るのですか？XMLの <?xml>タグがPHPでエラーになります。
  11. あらかじめ設定されている変数を全て網羅したリストはどこにあるので すか？なぜPHPのドキュメントにはその一覧がないのですか？
  12. フリーではない商用ライブラリである PDFLib を使わずに PDFファイルを生成するにはどうしたらよいでしょうか？ フリーのもので、外部のPDFライブラリが不要なものがいいのですが。
  13. いくつかの PHP ディレクティブでは、バイト値を int ではなく省略形で設定できます。この省略形で使えるオプションを教えてください。
PHP の関数のパラメータの順番を覚えられません。だって関数によってばらばらなんだもん。

PHP は、さまざまな外部ライブラリの間を取り持つ糊のような存在です。 そのため、時にはちょっとごちゃごちゃすることもあります。 しかし、経験上、以下のような規則があるようです。

配列関数 のパラメータは "needle, haystack" の順だけれども、 文字列関数 はその逆で "haystack, needle" の順となります。

あらゆるフォームから送信されたデータを扱うことができる汎用的な PHPスクリプトを書きたいのですが、POSTメソッドでどのようなデータ が送信されたかを知るにはどうするのですか？

PHPは$_POSTのような 定義済みの変数 を沢山提供しています。$_POSTを連想配列として ループすることでPOSTされた全ての値にアクセスできます。例えば、 foreach で単純にループして empty() で値をチェックし、 結果を出力します。

<?php
$empty = $post = array();
foreach ($_POST as $varname => $varvalue) {
if (empty($varvalue)) {
$empty[$varname] = $varvalue;
} else {
$post[$varname] = $varvalue;
}
}

print "<pre>";
if (empty($empty)) {
print "None of the POSTed values are empty, posted:\n";
var_dump($post);
} else {
print "We have " . count($empty) . " empty values\n";
print "Posted:\n"; var_dump($post);
print "Empty:\n"; var_dump($empty);
exit;
}
?>

シングルクオート(')をバックスラッシュでエスケープされた シングルクオート(\')に変換しなければならないのですが、 正規表現を用いてこれを行うにはどの様にするのですか？ 同様に " を \" に、\ を \\ に変換したいのです。

もしデータベースに格納するためにそんなことをしようとしているのなら、 データベース自身が持つエスケープの仕組みを使うようにしましょう。 MySQL なら mysql_real_escape_string()、 PostgreSQL なら pg_escape_string() などです。 汎用的な関数 addslashes() や stripslashes() もありますが、 これはさらに古い時代の PHP コードで使われていたものです。

次のようなコードを実行すると、思った通りの順番で出力が表示されません。
function myfunc($argument)
{
echo $argument + 10;
}
$variable = 10;
echo "myfunc($variable) = " . myfunc($variable);
なぜですか？

式の中で関数の実行結果を使用する(例えば上の例の様に他の文字列と 連結する)ためには、echo するのではなく、その 値を return しなければいけません。

改行されないのですが？
<pre>
<?php echo "これは1行目"; ?>
<?php echo "この行は改行に続いて出力されるはず"; ?>
</pre>

PHPでは、"?>"か"?>\n"(\nは改行を表します)をPHPのコードブロッ クの終端と見なします。このため、コードブロック終端の改行記号は省 略され、表示される文は1行になります。つまり、改行をさせるために は、PHPのコードブロックの終端の後にもう1つ改行を挿入する必要があ るということです。

なぜPHPはこのようなことをするのでしょうか？なぜならHTMLを出力する 場合にはこの方が都合のよいことが多いからです。もしとても長い1行を 出力しなければならない場合に、改行が解釈されてしまうとしたらどう でしょう。ソースコードの1行もとても読めないくらい長いものになって しまいます。

'Warning: Cannot send session cookie - headers already sent...'や 'Cannot add header information - headers already set...'といった メッセージが出力されるのですが。 sent...'.

header(), set_cookie()や セッション関数は出力ストリームに ヘッダを付加する関数で、ヘッダを送信できるのは本文の出力を 開始する前のみです。headers_sent()を使って 既にヘッダが送信済みでないかチェックすることができます。 出力制御関数もご覧ください。

リクエストヘッダに直接アクセスしたいのですが、どうすればよいですか？

もしPHPがApacheモジュールとして動作しているなら、 getallheaders()を使えば全てのヘッダを取得する ことができます。下のちょっとしたコードで全てのリクエストヘッダを 表示することができます。

$headers = getallheaders();
foreach ($headers as $name => $content) {
echo "headers[$name] = $content<br />\n";
}

apache_lookup_uri(),
apache_response_headers(),
fsockopen()も参照ください。

IISで認証を行おうとすると'No Input file specified'というエラーが 発生します。

これはIISのセキュリティモデルの欠点で、IISで動作するCGIに共通する 問題です。これを回避策するには、認証のかかったディレクトリに(PHP が解釈しない)HTMLファイルを作成します。そしてMETAタグを使ってPHP を使用したページにリダイレクトするか、リンクを張ります。こうすれ ばPHPは認証済みかどうかを正しく認識することが出来ます。 また、これは他のNTウェブサーバーに は影響ありません。詳しくは» http://support.microsoft.com/kb/q160422/ とHTTP 認証を 参照ください。

Windows: 他のコンピュータと共有しているファイルに、IIS でアクセスできません。

Go to Internet Information Services を変更する必要があります。PHP ファイルを選択して プロパティを開き、セキュリティ タブに移動し、 Edit -< Anonymous access and authentication control 。

この問題を解決するには Anonymous Access のチェックをはずして Integrated Window Authentication をチェックしたままにしておきか、 あるいは Anonymous Access をチェックしてアクセスできないユーザーを別途指定します。

どうすればXMLとPHPは共存することが出来るのですか？XMLの <?xml>タグがPHPでエラーになります。

<?xml を直接PHPコードに埋め込むには、 PHPディレクティブのshort_tags を 0 に設定しなければなりません。 このディレクティブはini_set()でセットすることは できません。short_open_tags のオン/オフに関わらず、次のようにもできます: <?php echo '<?xml'; ?> このディレクティブはデフォルトでオンです。

あらかじめ設定されている変数を全て網羅したリストはどこにあるので すか？なぜPHPのドキュメントにはその一覧がないのですか？

マニュアルの 定義済みの変数 のページを読んでください。スクリプト上で有効な定義済み変数のリストの 一部があります。有効な変数の完全なリスト（とその詳しい情報）は phpinfo()をコールすることで見ることができます。 マニュアルの PHPの外部から来る変数 のセクションも読んでください。HTMLフォームやCookie、URL等から 来る外部変数に関するシナリオが説明されています。

フリーではない商用ライブラリである PDFLib を使わずに PDFファイルを生成するにはどうしたらよいでしょうか？ フリーのもので、外部のPDFライブラリが不要なものがいいのですが。

PHPで書かれている代替手段がいくつかあります。 » FPDF や » TCPDF などです。

いくつかの PHP ディレクティブでは、バイト値を int ではなく省略形で設定できます。この省略形で使えるオプションを教えてください。

有効なオプションは K（キロバイト）、M（メガバイト）および G（ギガバイト) です。これらはすべて、大文字小文字を区別しません。 これ以外の文字はバイト値と判断されます。 1M は、1 メガバイトあるいは 1048576 バイトと等しくなります。1K は、1 キロバイトあるいは 1024 バイトです。この表記法は、 php.ini や ini_set() 関数で使えます。 ここで、数値の値は、int 型にキャストされることに注意して下さい。 たとえば、0.5M は 0 と解釈されます。

注意: キロバイト? キビバイト?

PHP の記法では 1 キロバイト = 1024 バイトとしていますが、 IEC の標準規格では 1024 バイトのことを 1 キビバイト (kibibyte) と呼ぶことになっています。 まとめ: PHP での k および K = 1024 バイト。


安全なパスワードハッシュ

この節では、なぜハッシュ関数を使ってパスワードを守るのかについての理由と、 ハッシュ処理を効率的に行う方法について説明します。

  1. なぜ、アプリケーションのユーザーが登録したパスワードをハッシュしなければならないのですか?
  2. よく使われるハッシュ関数である md5 や sha1 は、なぜパスワードのハッシュに適していないのですか?
  3. よく使われるハッシュ関数では不適切だというのなら、 パスワードをどうやってハッシュすればいいのですか?
  4. ソルトとは?
  5. ソルトはどのように保存すればいいのですか？
なぜ、アプリケーションのユーザーが登録したパスワードをハッシュしなければならないのですか?

パスワードのハッシュは、最も基本的なセキュリティ要件のひとつです。 ユーザーからパスワードを受け取るアプリケーションを設計するときには必ず考慮しなければなりません。 ハッシュしなければ、パスワードを格納したデータベースが攻撃を受けたときにパスワードを盗まれてしまいます。 それは即時にアプリケーションが乗っ取られることにつながるし、 もしそのユーザーが他のサービスでも同じアカウント・同じパスワードを使っていればさらに被害が大きくなります。

ユーザーのパスワードにハッシュアルゴリズムを適用してからデータベースに格納しておくと、 攻撃者が元のパスワードを知ることが難しくなります。 とはいえ、パスワードのハッシュ結果との比較は可能です。

しかし、ここで注意すべき点は、パスワードのハッシュ処理はあくまでもデータベースへの不正アクセスからの保護にすぎず、 アプリケーション自体に不正なコードを注入される攻撃からは守れないということです。

よく使われるハッシュ関数である md5() や sha1() は、なぜパスワードのハッシュに適していないのですか?

MD5 や SHA1 そして SHA256 といったハッシュアルゴリズムは、 高速かつ効率的なハッシュ処理のために設計されたものです。 最近のテクノロジーやハードウェア性能をもってすれば、 これらのアルゴリズムの出力をブルートフォースで(力ずくで)調べて元の入力を得るのはたやすいことです。

最近のコンピュータではハッシュアルゴリズムを高速に「逆算」できるので、 セキュリティ技術者の多くはこれらの関数をパスワードのハッシュに使わないよう強く推奨しています。

よく使われるハッシュ関数では不適切だというのなら、 パスワードをどうやってハッシュすればいいのですか?

パスワードをハッシュするときに検討すべき重要な二点は、 その計算量とソルトです。 ハッシュアルゴリズムの計算コストが増えれば増えるほど、 ブルートフォースによる出力の解析に時間を要するようになります。

PHP には ネイティブのパスワードハッシュ API が用意されており、これを使えば ハッシュの計算 や パスワードの検証 を安全に行えます。

それ以外には、crypt() 関数を使う方法もあります。 この関数は、いくつかのハッシュアルゴリズムに対応しています。 この関数を使うときには、指定したアルゴリズムが使えるかどうかを気にする必要はありません。 各アルゴリズムが PHP の内部でネイティブに実装されているので、 ご利用の OS でサポートしていないアルゴリズムでも使うことができます。

パスワードをハッシュするときのおすすめのアルゴリズムは Blowfish です。 パスワードハッシュ API でも、このアルゴリズムをデフォルトで使っています。 というのも、このアルゴリズムは MD5 や SHA1 と比較して計算コストが高いにもかかわらず、スケーラブルだからです。

crypt() でパスワードを検証する場合は、タイミング攻撃に注意が必要です。 タイミング攻撃を避けるため、処理時間が一定な文字列比較処理を使うようにしましょう。 PHP の == 演算子や === 演算子 も、そして strcmp() も、文字列比較の処理時間が一定ではありません。 その点 password_verify() はこの問題を気にしなくて済むので、 可能な限り ネイティブのパスワードハッシュ API を使うようにしましょう。

ソルトとは?

暗号理論におけるソルトとは、ハッシュ処理の際に追加するデータのことです。 事前に計算済みのハッシュとその元入力の対応表 (レインボーテーブル) で出力を解析される可能性を減らすために利用します。

端的に言うと、ソルトとはちょっとした追加データです。 これをつけるだけで、ハッシュをクラックするのが劇的に難しくなります。 事前に計算済みのハッシュとその元入力を大量にまとめた表が、オンラインで多数公開されています。 ソルトを使えば、そのハッシュ値がこれらの表に含まれている可能性を大きく減らすことができます。

password_hash() は、ソルトを指定しなかった場合にはランダムなソルトを作ります。 一般に、これがいちばんお手軽で安全なアプローチでしょう。

ソルトはどのように保存すればいいのですか？

password_hash() や crypt() を使った場合、戻り値であるパスワードハッシュの中にソルトが含まれています。 このソルトは、そのままの形式でデータベースに格納する必要があります。 というのも、利用したハッシュ関数の情報がそこに含まれており、それを直接 password_verify() や crypt() に渡せばパスワードの検証ができるからです。

crypt() や password_hash() の戻り値の書式を次の図に示します。 このように、使ったアルゴリズムや検証時に必要なソフトに関する情報もすべて含まれています。

password_hash や crypt が戻す値。 使ったアルゴリズム、そのアルゴリズムのオプション、使ったソルト、そしてハッシュしたパスワードが続く。


PHP と HTML

PHP と HTML は深く関係しています。PHP は HTML を生成し、HTML には PHP に 送信される情報が記述されています。 以下の FAQ を読む前に、どうやって 外部から来る変数を取得するかを読んでおくことは重要です。 このマニュアルにはこのトピックに関するよい例があります。

  1. フォームから、もしくは URL から値を渡す場合にはどういった エンコード/デコードが必要なのですか？
  2. <input type="image"> タグを使おうとしているのですが、変数 $foo.x と $foo.y が使えません。 $_GET['foo.x'] も存在していません。どうすればよいのですか?
  3. HTML フォームで配列を使用するにはどうすればよいですか？
  4. "select multiple" タグで選択された全ての結果を取得するには どうすればよいですか?
  5. JavaScript から PHP に変数を渡すには?
フォームから、もしくは URL から値を渡す場合にはどういった エンコード/デコードが必要なのですか？

エンコードが重要になる場面はいくつかあります。 string $data という エンコードされていない文字列データを渡す場合について考えてみると、

  • HTML を通じて渡す場合： 文字列にはどのような値が含まれるか分からないので、 データは必ず htmlspecialchars を行い、 ダブルクオートで囲まなければなりません。

  • URL を通じて渡す場合: URL はいくつかのパーツから成り立ちます。 このデータをそのパーツのうちの一つであると解釈させたいならば、 urlencode() でエンコード しなければなりません。

例1 HTML の hidden 要素

<?php
echo '<input type="hidden" value="' . htmlspecialchars($data) . '" />'."\n";
?>

注意: $data を urlencode() をしては いけません。なぜなら、その作業はブラウザに任されているからです。 一般に普及している全てのブラウザは正しくこの処理を行ってくれます。 ただ、この処理はメソッド(GET や POST)が何であるかにかかわらずに 行われるということに気をつけてください。この処理に気づくのは GET リクエストのときだけになるでしょう。なぜなら POST リクエストの内容は通常目に触れることは無いからです。

例2 ユーザーによって編集するデータ

<?php
echo "<textarea name='mydata'>\n";
echo htmlspecialchars($data)."\n";
echo "</textarea>";
?>

注意: ブラウザはエスケープされたシンボルを解釈するので、data は 意図したとおりに表示されます。 フォームの内容を送信するとき、GET か POST かにかかわらず data は ブラウザによって URL エンコードされ、PHP によって URL デコードされます。 要は、URL エンコード/デコードを自分で行う必要はなく、これらの処理は すべて自動的に行われると言うことです。

例3 URL 中の場合

<?php
echo '<a href="' . htmlspecialchars("/nextpage.php?stage=23&data=" .
urlencode($data)) . '">'."\n";
?>

注意: この例では、実は GET リクエストを摸擬しています。このため、data を手動で urlencode() する必要があります。

注意: 全ての URL を htmlspecialchars() する必要があります。 なぜなら、この URL は HTML の value 属性として扱われるからです。 この場合は、ブラウザはまず htmlspecialchars() された データを元に戻し、それから URL を渡します。URL は urlencode() されているので、PHP はこれを正しく 解釈することができます。 URL 中の & が &amp; に置き換えられていることに気づくでしょう。もしあなたがこれを忘れても ほとんどのブラウザは元に戻してくれますが、必ずそうしてくれるとは 限りませんので、URL が動的に変更されるものでなくても URL は htmlspecialchars() されるべき です。

<input type="image"> タグを使おうとしているのですが、変数 $foo.x と $foo.y が使えません。 $_GET['foo.x'] も存在していません。どうすればよいのですか?

以下のようなタグを使えば、標準のボタンの代わりに画像を使用して フォームを送信することができます。

<input type="image" src="image.gif" name="foo" />
ユーザーが画像のどこかをクリックすると、そのフォームの内容に foo.x と foo.y という 2 つの変数が追加され、サーバーに送信されます。

PHP では foo.x と foo.y という名前は変数名として正しくないので、 自動的に foo_x と foo_y という名前に変換されます。要は、ピリオドが アンダースコアに置き換えられる、と言うことです。そのため、これらの 変数にアクセスする際には 外部から来る変数 の取得についてのセクションで記述されているのと同様な方法を とります。たとえば $_GET['foo_x'] などです。

注意:

リクエスト変数名の中のスペースは、アンダースコアに置き換えられます。

HTML フォームで配列を使用するにはどうすればよいですか？

フォームの内容を PHP スクリプトで配列として受け取るには、 <input>、<select> あるいは <textarea> といった要素の name を以下のように指定します：

<input name="MyArray[]" />
<input name="MyArray[]" />
<input name="MyArray[]" />
<input name="MyArray[]" />
変数名の最後にある括弧に注意してください。これにより、フォー ムの内容が配列として扱われます。異なる要素に同じ名前をつけること で要素を配列にグループ分けすることができます。
<input name="MyArray[]" />
<input name="MyArray[]" />
<input name="MyOtherArray[]" />
<input name="MyOtherArray[]" />
上記の HTML の場合、MyArray と MyOtherArray という 2 つの配列が生成され、 PHP スクリプトに送信されます。また、配列に特定のキーを設定する こともできます。
<input name="AnotherArray[]" />
<input name="AnotherArray[]" />
<input name="AnotherArray[email]" />
<input name="AnotherArray[phone]" />
この場合、配列 AnotherArray のキーは 0、1、email そして phone となります。

注意:

HTML に配列のキーを指定するかどうかは自由です。キーを指定しなかった 場合はフォームに現れる順番に番号がつけられます。最初の例だと、 キーは 0、1、2、3 となります。

配列関数と 外部から来る変数 も参照ください。

"select multiple" タグで選択された全ての結果を取得するには どうすればよいですか?

"select multiple" タグを使うと、ユーザーはリストから複数の項目を 選択することができるようになります。選択された項目はフォームの action で指定されたハンドラに渡されます。問題は、これらの値が全て 同じ名前で渡されることです。つまり、

<select name="var" multiple="yes">
選択されたそれぞれの項目は action のハンドラに次のように渡されます：
var=option1
var=option2
var=option3
それぞれの項目は前の変数 $var の値を上書きして しまいます。この問題を解決するには、PHPの "フォームの値を配列にする" 機能を使います。以下のようにするとよいでしょう。
<select name="var[]" multiple="yes">
こうすれば PHP に $var を配列として扱うように 知らせることができ、各項目の value の値は配列の要素として var[] に 追加されます。最初の項目は $var[0] になり、 次の項目は $var[1]... というようになります。 count() 関数を使えば選択された項目の数を知る ことができます。またもし必要なら sort() 関数を 使ってソートを行うこともできます。

JavaScript を使っている場合、フォーム要素に要素名を使って(訳注： document.myform.myelement.value 等の様に)アクセスしようとすると、 要素名に含まれる [] が問題となることがあるので 気をつけてください。この場合は、数字で表されるフォーム要素の ID を 使用するか、シングルクオートで要素名を囲んでフォーム要素の配列の インデックスとしてアクセスしてください。例えば、以下のようにします：

variable = document.forms[0].elements['var[]'];

JavaScript から PHP に変数を渡すには?

JavaScript は（普通は）クライアントサイド技術であり、一方 PHP は（普通は） サーバーサイド技術です。また HTTP は"ステートレスな"プロトコルです。 そのため、この二つの言語はダイレクトに変数を共有することができません。

しかしながら、この二つの言語の間で変数を渡すことは可能です。 一つの方法は PHP と一緒に JavaScript のコードを生成し、 ブラウザに自動的にリフレッシュ（再ロード）させることです。 以下の例はまさにそれで、PHP に画面の高さと幅を認識させています。 これは通常はクライアントサイドでしかできないことです。

例4 PHP による JavaScript の生成

<?php
if (isset($_GET['width']) AND isset($_GET['height'])) {
// ジオメトリ値を出力する
echo "画面の幅: ". $_GET['width'] ."<br />\n";
echo "画面の高さ: ". $_GET['height'] ."<br />\n";
} else {
// ジオメトリ変数を渡す
// (元のクエリ文字列を保持する
// -- POST 変数は別の方法で扱う必要がある)

echo "<script language='javascript'>\n";
echo " location.href=\"{$_SERVER['SCRIPT_NAME']}?{$_SERVER['QUERY_STRING']}"
. "&width=\" + screen.width + \"&height=\" + screen.height;\n";
echo "</script>\n";
exit();
}
?>


PHP と COM

PHP は Win32 プラットフォーム上で COM と DCOM オブジェクトに アクセスすることができます。

  1. とある計算を行う DLL を作成しました。これを PHP で実行させる方法は ありますか?
  2. 'Unsupported variant type: xxxx (0xxxxx)'とはどういう意味ですか?
  3. PHP でビジュアルオブジェクトを操作できますか?
  4. COM オブジェクトをセッション情報として保存できますか?
  5. COM の出力するエラーをトラップできますか?
  6. PHP スクリプトから DLL を作成することはできますか? Perl では できるのですが。
  7. 'Unable to obtain IDispatch interface for CLSID {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}'とはどういう意味ですか?
  8. COM オブジェクトをリモートサーバーから実行するにはどうすればよいですか?
  9. 'DCOM is disabled in C:\path...\scriptname.php on line 6' という エラーが発生しました。どうすればよいですか？
  10. PHP を使用したページで ActiveX オブジェクトをロード/操作することは できますか?
  11. 実行中のコンポーネントのインスタンスを取得することはできますか?
  12. COM オブジェクトから送られてくるイベントを扱う方法はありますか？
  13. 2 つ以上のインターフェイスを公開している COM オブジェクトのメソッドを 呼び出そうとして困っています。どうすればよいですか?
  14. PHP は COM を扱えるということは分かりました。では COM+ については どうですか?
  15. PHP が COM オブジェクトを操作することができるということは、MTS を 使ってコンポーネントリソースを扱えると考えてもよいということですか？
とある計算を行う DLL を作成しました。これを PHP で実行させる方法は ありますか?

もしそれが普通の DLL なら、現在のところ PHP からそれを実行する手段は ありません。DLL が COM サーバーを含んでいて IDispatch インターフェイスが 実装されている場合、PHP からアクセスすることができます。

'Unsupported variant type: xxxx (0xxxxx)'とはどういう意味ですか?

多くの VARIANT タイプとその組み合わせがあり、そのほとんどは サポートされていますが、残りのいくつかは未だ実装されていません。 また配列も完全にサポートされているわけではなく、PHP と COM の間で 受け渡しが可能なのは 1 次元の添字付配列のみです。もしこの他に サポートされていないタイプを見つけた場合は(既知でなければ)、 できる限りの情報を添えてバグとして報告してください。

PHP でビジュアルオブジェクトを操作できますか?

基本的には可能です。しかし PHP はほとんどの場合ウェブスクリプティングの 言語として使用されウェブサーバー上で実行されるため、ビジュアルオブジェクトが サーバーのデスクトップに現れることはありません。もし PHP を アプリケーション作成に使用する、すなわち PHP-GTK と合わせて 使用する場合にはアクセスに制限はありません。COM を通じて ビジュアルオブジェクトを操作することができます。

COM オブジェクトをセッション情報として保存できますか?

できません。COM インスタンスはリソースとして扱われるため、1 つの スクリプトを実行している間のみ使用可能です。

COM の出力するエラーをトラップできますか?

COM 拡張モジュールは com_exception 例外をスローします。これをキャッチし、code メンバを調べることで次にすべきことを決定できます。

PHP スクリプトから DLL を作成することはできますか? Perl では できるのですが。

いいえ、残念ながら PHP にはそのようなツールはありません。

'Unable to obtain IDispatch interface for CLSID {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}'とはどういう意味ですか?

このエラーが発生する理由はいくつかあります。

  • CLSID が正しくない
  • 要求された DLL が無い
  • 要求されたコンポーネントが IDispatch インターフェイスを実装していない

COM オブジェクトをリモートサーバーから実行するにはどうすればよいですか?

ローカルオブジェクトを実行するのと全く同様です。ただ、COM コンストラクタの 2 番目のパラメータにリモートマシンの IP アドレスを 渡すだけです。

php.ini に com.allow_dcom =true をセットするのを忘れないでください。

'DCOM is disabled in C:\path...\scriptname.php on line 6' という エラーが発生しました。どうすればよいですか？

php.ini を編集して com.allow_dcom =true. としてください。

PHP を使用したページで ActiveX オブジェクトをロード/操作することは できますか?

これは PHP とは関係ありません。ActiveX オブジェクトは、HTML ドキュメントから要求があった場合にクライアント側でロードされます。 PHP スクリプトとは関係が無く、従ってサーバー側と直接やりとりすることも できません。

実行中のコンポーネントのインスタンスを取得することはできますか?

モニカーを使用すれば可能です。同じ Word インスタンスに対して複数の 参照を取得したい場合は、以下のようにしてインスタンスを生成します。

<?php
$word = new COM("C:\docs\word.doc");
?>

こうすれば、実行中のインスタンスが無い、もしくはインスタンスの 取得が不可能だった場合には新規に生成され、インスタンスが取得できた 場合にはそのハンドルを返します。

COM オブジェクトから送られてくるイベントを扱う方法はありますか？

イベントシンクを定義し、com_event_sink() を使用してそれをバインドすることが可能です。PHP でイベントシンククラスの 雛形を作成するために com_print_typeinfo() を 使用することが可能です。

2 つ以上のインターフェイスを公開している COM オブジェクトのメソッドを 呼び出そうとして困っています。どうすればよいですか?

この問題に対する答えは、簡単ですが残念なものです。正確には わかりませんが、おそらく打つ手はありません。もしこの問題に関する 具体的な情報があったら» 私 に教えてください。

PHP は COM を扱えるということは分かりました。では COM+ については どうですか?

COM+ とは MTS(Microsoft Transaction Server) と MSMQ(Microsfot Message Queue Service) を通じてコンポーネントを操作する フレームワークによって COM を拡張したものです。が、PHP がそういった コンポーネントをサポートするにあたって特別に必要なことはありません。

PHP が COM オブジェクトを操作することができるということは、MTS を 使ってコンポーネントリソースを扱えると考えてもよいということですか？

PHP それ自体はまだトランザクションをサポートしていません。従って エラーが発生してもロールバック処理は行われません。もし トランザクションをサポートするコンポーネントを使用する場合は、 自分でトランザクション処理を実装する必要があります。


その他の質問

ここでは他のカテゴリに分類することができないような質問を扱います。

  1. bz2 で圧縮された Windows マニュアルはどのように扱えばいいのですか？
bz2 で圧縮された Windows マニュアルはどのように扱えばいいのですか？

bz2 ファイルを処理することができるアーカイバを持っていない場合、 RedHat からコマンドラインツールを » ダウンロードしてください (詳細は下記の情報を参照)。

コマンドラインツールを使いたくない場合は、» Stuffit Expander、 » UltimateZip、 » 7-Zip、 » Quick Zip のようなフリーのツールを使用することも可能です。 » WinRAR または » Power Archiver のようなツールを持っている場合、簡単に bz2 ファイルを解凍できます。 Total Commander(以前は Windows Commander)を使用している場合は、 bz2 用のプラグインを » Total Commander のサイトから無料で手に入れることが出来ます。

Redhat から入手可能な bzip2 コマンドラインツール:

Windows 2000 SP2 のユーザーは バージョン 1.0.2 を、他の全ての Windows ユーザーはバージョン 1.00 を使用してください。 ダウンロードしたら実行ファイルの名前を bzip2.exe へ変更してください。 そしてそれをパスの通ったディレクトリ、例えば C:\Windows(ドライブ名は貴方のシステムにあわせて適宜変更してください) へコピーしてください。

注意: lang は使用する言語を意味し、 pdf のように x は指定した形式を表します。 php_manual_lang.x.bz2 を解凍するには以下のようにします。

  • コマンドプロンプトウィンドウを開きます
  • ダウンロードした php_manual_lang.x.bz2 を保存したディレクトリに cd コマンドを使用して移動します。
  • bzip2 -d php_manual_lang.x.bz2 を実行すると php_manual_lang.x というファイルが同じディレクトリに生成されます。

分割 HTML 版アーカイブ(php_manual_lang.tar.bz2) をダウンロードした場合でも手順は同じです。 唯一の違いは、bzip2 コマンドの実行後に php_manual_lang.tar が生成されることです。 tar 形式のファイルは » WinZip といったアーカイバで扱うことができます。


付録

  • PHP の歴史と関連するプロジェクト
    • PHPの歴史
    • PHP関連のプロジェクトの歴史
    • PHP関連の本
    • PHP関連の出版物
  • PHP 8.2.x から PHP 8.3.x への移行
    • 新機能
    • 新しいクラスとインターフェイス
    • 新しく追加された関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 8.3.x で推奨されなくなる機能
    • その他の変更
    • Windows のサポート
  • PHP 8.1.x から PHP 8.2.x への移行
    • 新機能
    • 新しく追加された関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 8.2.x で推奨されなくなる機能
    • その他の変更
    • Windows のサポート
  • PHP 8.0.x から PHP 8.1.x への移行
    • 新機能
    • 新しいクラスとインターフェイス
    • 新しく追加された関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 8.1.x で推奨されなくなる機能
    • その他の変更
  • PHP 7.4.x から PHP 8.0.x への移行
    • 新機能
    • 下位互換性のない変更点
    • 推奨されなくなる機能
    • その他の変更
  • PHP 7.3.x から PHP 7.4.x への移行
    • 新機能
    • 新しいクラスとインターフェイス
    • 新しく追加された関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 7.4.x で推奨されなくなる機能
    • 削除された拡張モジュール
    • その他の変更
    • Windows のサポート
  • PHP 7.2.x から PHP 7.3.x への移行
    • 新機能
    • 新しく追加された関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 7.3.x で推奨されなくなる機能
    • その他の変更
    • Windows のサポート
  • PHP 7.1.x から PHP 7.2.x への移行
    • 新機能
    • 新しい関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 7.2.x で推奨されなくなる機能
    • その他の変更
  • PHP 7.0.x から PHP 7.1.x への移行
    • 新機能
    • 新しい関数
    • 新しいグローバル定数
    • 下位互換性のない変更点
    • PHP 7.1.x で推奨されなくなる機能
    • 変更された関数
    • その他の変更
    • Windows のサポート
  • PHP 5.6.x から PHP 7.0.x への移行
    • 下位互換性のない変更点
    • 新機能
    • PHP 7.0.x で推奨されなくなる機能
    • 変更された関数
    • 新しい関数
    • 新しいクラスおよびインターフェイス
    • 新しいグローバル定数
    • SAPI モジュールの変更
    • 削除された拡張モジュールおよび SAPI
    • その他の変更
  • PHP 5.5.x から PHP 5.6.x への移行
    • 下位互換性のない変更点
    • 新機能
    • PHP 5.6.x で推奨されなくなる機能
    • 変更された関数
    • 新しい関数
    • PHP 5.6.x における OpenSSL 関連の変更
    • その他の拡張モジュールに対する変更
    • 新しいグローバル定数
  • PHP のデバッグ
    • PHP のデバッグについて
  • Configure オプション
    • 中心となる configure オプションのリスト
  • php.ini ディレクティブ
    • php.ini ディレクティブのリスト
    • php.ini のセクション一覧
    • コア php.ini ディレクティブに関する説明
  • 拡張モジュールの一覧/分類
    • アルファベット順
    • 所属
    • 状態
  • 関数エイリアスのリスト
  • 予約語の一覧
    • キーワードのリスト
    • 定義済のクラス
    • 定義済みの定数
    • その他の予約語の一覧
  • リソース型の一覧
  • 利用できるフィルタのリスト
    • 文字列フィルタ
    • 変換フィルタ
    • 圧縮フィルタ
    • 暗号化フィルタ
  • サポートされるソケットトランスポートのリスト
    • Internet ドメイン: TCP、UDP、SSL、および TLS
    • Unix ドメイン: Unix および UDG
  • PHP 型の比較表
  • パーサトークンの一覧
  • ユーザーレベルでの命名の手引き
    • グローバル名前空間
    • ルール
    • Tips
  • マニュアルについて
    • フォーマット
    • ユーザーノートについて
    • 関数の定義(プロトタイプ)を読むには
    • 本マニュアルに記載された PHP のバージョン
    • PHP に関する更なる情報を得るには
    • ドキュメントの改善を手助けするには
    • 各種フォーマットを生成する方法
    • 翻訳
  • Creative Commons Attribution 3.0
  • 索引
    • 関数・メソッド
    • サンプル
  • 変更履歴


PHP の歴史と関連するプロジェクト

目次

  • PHPの歴史
  • PHP関連のプロジェクトの歴史
  • PHP関連の本
  • PHP関連の出版物

PHP は、90年代半ばに登場してから大きな進歩を遂げました。 当初はひっそりと始まったものが、今やウェブの世界で最も強力な言語のひとつになったのです。 PHP の進化は、ギークにとってのおとぎ話のようなものでしょう。 ただ忘れてはならないのは、ここまでの成長は決してたやすいものではなかったということです。 これまでの PHP の道のりに興味がある人は、このページを読み進めてください。 過去のインターネットの歴史に触れてみたい人は、古いバージョンの PHP を » PHP Museum から取得できます。


PHPの歴史

PHP Tools、FI、Construction Kit、そして PHP/FI

現在 PHP として知られているものは、かつて PHP/FI と呼ばれていたソフトウェアの後継です。 1994 年に Rasmus Lerdorf が生み出したいちばん最初の PHP はシンプルな CGI バイナリ群で、C 言語で書かれていました。 元々は彼がオンラインで公開している経歴書のアクセス履歴を調べるために使われていましたが、 彼はそのスクリプト群を「Personal Home Page Tools」と名付けました。「PHP Tools」 と略されることが多かったようです。時を経て、さまざまな機能追加の要望が出てきたところで、 Rasmus は PHP Tools を書き直しました。より大規模でリッチな実装にしたのです。 このニューモデルはデータベースも扱えるようになり、 一種のフレームワークとして使えるようになったのです。 ユーザーは、これを使って掲示板のようなシンプルな動的ウェブアプリケーションを作れるようになりました。 1995 年 6 月、Rasmus は PHP Tools のソースコードを » 公開 しました。開発者は、それを自分の好きなように使えるようになったのです。 ユーザーが自分でバグ修正や機能改善をすることも許可されていましたし、 むしろそれを推奨していました。

同じ年の 9 月、Rasmus は PHP をさらに発展させ、短期間ですが PHP の看板を外しました。新しいツールの名前は FI ("Forms Interpreter" の略) となり、 この実装には現在の PHP の基本機能のいくつかが含まれていました。 Perl 風の変数、そしてフォーム変数の自動取得、HTML に埋め込める構文などです。 構文は Perl と似ていましたが、より制限されたシンプルなもので、 どこか一貫性に欠けるものでした。 実際、コードを HTML ファイルに埋め込むには HTML のコメントを使う必要がありました。 このやり方を誰もが気に入ったというわけではありませんでしたが、 FI はその後も成長を続け、CGI ツールとしての立場を固めていきました。 とは言え、未だに言語というにはほど遠い状態です。 しかし、翌月の 1995 年 10 月から状況は変わり始めました。 Rasmus が、コードを完全に書き直した版をリリースしたのです。 再び PHP の名前がつき、こんどは「Personal Home Page Construction Kit」 とう名前になりました。これは、当時としてはかなり進んだスクリプトインターフェイスを持っていました。 その言語は意図的に C の構文に似せて作られ、C や Perl などを知っている人たちが移行しやすいようにしてありました。 この時点ではまだ UNIX や POSIX 準拠のシステムにしか対応していませんでしたが、 Windows NT 上での実装も検討されていました。

コードはさらに一から書き直され、1996 年の 4 月には過去のリリースの名前を組み合わせた PHP/FI という名前で公開されました。この第二世代の実装で、 PHP は単なるツール群からプログラミング言語へと進化を遂げたのです。 DBM や mSQL そして Postgres95 などのデータベース、 クッキー、ユーザー定義関数などのサポートが組み込まれました。 その年の 6 月に、PHP/FI のバージョンは 2.0 になりました。 興味深いことに、PHP 2.0 の完全なバージョンとして出されたものはこれだけでした。 最終的にベータ状態を卒業したのは 1997 年 11 月のことでしたが、 そのころには裏にあるパースエンジンは完全に書き直されていました。

開発期間は短かったものの、PHP/FI は初期のウェブ開発業界での勢力を拡大し続けました。 1997 年から 1998 年にかけて、PHP/FI は世界中の数千人のマニアに使われていました。 1998 年 5 月の Netcraft の調査によると、およそ 60,000 のドメインがヘッダに "PHP" の文字を含めていたそうです。これは、そのサーバーに実際に PHP/FI がインストールされていたことを意味します。この数字は、当時のインターネット上の全ドメインの およそ 1% にあたるものでした。 これらの実績にもかかわらず、PHP/FI に円熟期が来ることはとても望めませんでした。 ちょっとした貢献をしてくれる人は何人かいたものの、 基本的には個人で開発している状態が続いていたのです。

例1 PHP/FI のコード例

<!--include /text/header.html-->

<!--getenv HTTP_USER_AGENT-->
<!--ifsubstr $exec_result Mozilla-->
  Hey, you are using Netscape!<p>
<!--endif-->

<!--sql database select * from table where user='$username'-->
<!--ifless $numentries 1-->
  Sorry, that record does not exist<p>
<!--endif exit-->
  Welcome <!--$user-->!<p>
  You have <!--$index:0--> credits left in your account.<p>

<!--include /text/footer.html-->

PHP 3

PHP 3.0 は、現存する PHP に近い状態になった最初のバージョンです。 PHP/FI 2.0 ではまだ力不足で、自分たちが大学のプロジェクトで作っている eコマースアプリケーションを構築するには機能が足りないと気づいたのは イスラエルのテルアビブにいた Andi Gutmans と Zeev Suraski でした。彼らは 1997 年に、 PHP/FI の裏にあるパーサーを新たに書き直そうとし始めました。 Rasmus をオンラインで捕まえた彼らは、PHP の現在の実装や自分たちがそれをどう作り直そうとしているのかについて議論しました。 現在のエンジンを改善させ、既存の PHP/FI のユーザーも守るために、 Andi と Rasmus、そして Zeev は協力して新たなプログラミング言語を作ることにしました。 この全く新しい言語は新しい名前でリリースされました。PHP/FI 2.0 の名前が持っていた「個人向け」というイメージをなくすためにです。 新しい名前は、シンプルに「PHP」。「PHP: Hypertext Preprocessor」 の頭文字をとったものです。

PHP 3.0 の最も強力な点は、その拡張性でした。 さまざまなデータベースやプロトコル、そして API を扱うための成熟したインターフェイスをユーザー向けに用意しただけでなく、 その言語自身も拡張しやすいものにしました。 そのおかげで、多くの開発者がさまざまなモジュールを開発するようになりました。 間違いなく、これこそが PHP 3.0 が大成功を収めた鍵でしょう。 PHP 3.0 で登場したその他の主要機能には、 オブジェクト指向プログラミングのサポートやより強力で一貫性のある言語構文などがあります。

1998 年 6 月、世界中から新たな開発者が多く参入した PHP Development Team は、PHP/FI 2.0 の正式な後継として PHP 3.0 をアナウンスしました。 アクティブな開発が続いていた PHP/FI 2.0 は前年の 11 月に開発が止まっていましたが、 ここで始めて公式に終了宣言が出たのです。約 9 か月の公開テストを経て PHP 3.0 が公式にリリースされたときには、既に世界中の 70,000 以上のドメインに PHP がインストールされていました。さらに、その環境は POSIX 準拠の OS にとどまりませんでした。 比較的少数ではあるものの、PHP がインストールされているとされるドメインの中には Windows 95 や 98 そして NT、あるいは Macintosh でサーバーが動いているところもあったのです。 最盛期には、インターネット上のウェブサーバーのほぼ 10% に PHP 3.0 がインストールされていました。

PHP 4

PHP 3.0が公式にリリースされて間もない1998年の冬、Andi Gutmans とZeev SuraskiはPHPの核となる部分を書き直し始めました。この 目的は、複雑なアプリケーションにおけるパフォーマンスの改善と PHPコードのモジュールとしての独立性を高めることでした。 そういったアプリケーションはPHP 3.0の新機能や第三者による 多くのデータベースやAPIのサポートを使用することで開発可能 でしたが、PHP 3.0はそういった複雑なアプリケーションを効率的に 扱うようにはデザインされていませんでした。

'Zend Engine'と呼ばれる新しいエンジン(開発者であるZeevとAndi の名前の組み合わせ)は、彼らの目的を十分に果たすものでした。 そしてそれは1999年中ごろに初めて紹介されました。このエンジンを 使用し、いくつかの広範囲にわたる新機能を追加したPHP 4.0は 前のバージョンのおよそ2年後となる2000年5月にリリースされました。 PHP 4.0はパフォーマンスが大幅に改善されたのに加え、 さらに多くのウェブサーバーのサポート、HTTPセッション、 出力のバッファリング、ユーザーの入力のさらに安全な取得方法の 提供、いくつかの新しい言語構造の提供といった特徴があります。

PHP 5

PHP 5は長期にわたる開発とプレリリースを経て2004年7月に公開されました。 改良の目玉は、コアである Zend Engine 2.0 で新しいオブジェクトモデルがサポートされたことで、 その他にも多くの新しい機能が追加されています。

PHP の開発チームは数十名の開発者で構成されています。 それ以外にも、何十名もの人たちが関連プロジェクトやサポートなどにかかわっています。 たとえば PEAR や PECL、そしてドキュメンテーション、 さらにはネットワーク基盤の管理などです。 PHP のネットワーク基盤は 100 を軽く上回るウェブサーバーで構成されており、 世界の七大陸のうちの六つにまたがっています。 ここ数年の統計情報に基づいて見積もると、 PHP は今や世界中の何千万から何億ものドメインに導入されていると言っても過言ではありません。

PHP 6

PHP 6 で計画されていたのは、PHP エンジンと言語内で Unicode を強く サポートすることでした。この取り組みは後に破棄されましたが、 PHP 6 をターゲットとしていた機能は PHP 5.3 (名前空間) と PHP 5.4 (トレイト と配列の "短縮" 記法) で取り込まれました。

PHP 7

PHP 7.0 は 2015年にリリースされ、 PHP コアのメジャーバージョン Zend Engine 3.0 を目玉としていました。 このバージョンは大きなパフォーマンスの向上 (PHP 5.6 と比較して最大2倍) とメモリ使用量の効率化、 一貫した64ビットのサポート、例外の機能追加、 安全な乱数生成器、 NULL合体演算子 (??), 無名クラス やその他の機能が含まれていました。

PHP 7 シリーズの後のリリースには、 リストの短縮記法 (7.1) や オブジェクトのパラメータや戻り値への型宣言(7.2)、 柔軟な heredoc と nowdoc (7.3)、 FFI (7.4) などのような、 多くの言語機能が追加されました。

PHP 8

2020年に最初にリリースされた PHP 8.0 は、 PHP 言語のさらなるメジャーアップデートです。 このバージョンには 名前付き引数, union型 , アトリビュート, コンストラクタのプロモーション, match 式、nullsafe 演算子 (?->), JIT コンパイラが含まれています。 そして、型システムやエラーハンドリングが改善され、一貫性の向上が図られていました。

PHP 8 シリーズの後のリリースには、 enum型 (8.1), ファイバー (8.1), 読み取り専用クラス (8.2), Disjunctive Normal Form (DNF) Types (8.2), クラス定数への型宣言 (8.3) が含まれています。


PHP関連のプロジェクトの歴史

PEAR

» PEAR、 PHP Extension and Application Repository (元は PHP Extension and Add-on Repositoryでした)は、 PHPで書かれた基本的なクラスの集まりで、将来的には PHPの拡張モジュールを開発者に配布する中心的な 方法になっていくでしょう。

PEARは2000年1月にTel Avivで開かれたPHP Developers' Meeting (PDM)で行われた議論の中から生まれたものです。これはStig S. Bakkenによって作成され、彼の初めて娘であるMalin Bakken に捧げられています。

2000年はじめの頃から、PEARは多くの開発者が一般的で再利用可能な 機能をPHPコミュニティ全体のために実装しました。これにより、 PEARは大きな、そして重要なプロジェクトへと成長しました。 今日PEARにはデータベースへのアクセス、キャッシュ、数学計算、 eCommerce等のバラエティに富んだクラスが含まれるようになって います。

PEARに関する詳細については、 » PEARのマニュアルを 参照ください。

PHP Quality Assurance Initiative(PHPの品質保証機関)

» PHP Quality Assurance Initiativeは、PHPのリリースが製品として様々な環境で 動作するべく十分にテストされていないという批判への対応策 として2000年の夏に開始されました。品質保証チームは現在のところ、PHPの ソースコードについて十分に理解している開発の中心となって いる人々によって構成されています。こうした開発者はPHPの ローカライズやバグフィクスに多くの時間を費やしています。 この他に、開発者の行った修正を個々の環境でテストして フィードバックを提供する多くのメンバーがいます。

PHP-GTK

» PHP-GTK は、 クライアントとして動作するGUIアプリケーションを構築するための PHPソリューションです。PHP-GTKの設計と実装は主として Andrei Zmievskiによります:

GUIプログラミングにはずっと興味を持ちつづけていて、あるとき Gtk+というものが、Cでコーディングするにはあまりに面倒なものだ ということを除けば非常にすばらしいものだと言うことを知りました。 PyGtkやGTK-Perlの実装を見て、PHPで(必要最小限の部分だけでも) Gtkインターフェイスを作成できないものだろうか、と考え始めたのです。 そして2000年の8月にちょっとした時間が出来たので実験を始めました。 私が主として参考にしたのはPyGtkの実装でした。というのもPyGtkは ほぼ全ての機能を網羅していて、且つオブジェクト指向のすばらしい インターフェイスを持っていたからです。こうした最初の段階で 私はPyGtkの作者であるJmaes Henstridgeの有用なアドバイスを得ることが 出来ました。

Gtk+関数へのインターフェイスを全て自作するのは問題外だったので コードジェネレータというアイデアに飛びつきました。これはPyGtkと 同様の方法です。コードジェネレータとはGtk+のクラス、定数、そして メソッドが記述されている .defs ファイルを読み込みPHPへのインターフェイス となるCのコードを生成するPHPのプログラムです。自動的に生成することが 出来ない部分に関しては .overrides ファイルに手動で追加していきました。

2000年の秋の間はあまり時間が取れなかったため、コードジェネレータ やインフラの構築に長い期間がかかってしまいました。しかし PHP-GTKをFrank kromannに見せると、彼は大いに興味を示して コードジェネレータとWin32版の実装を手伝い始めてくれました。 最初のプログラムHello Worldを書いて、それが動作したとき 私たちはとても興奮しました。このプロジェクトが公開するに 足るものになるにはさらに数ヶ月が必要でしたが2001年3月1日に 最初のバージョンをリリースすることが出来ました。このニュースは すぐにSlashDotにも載りました。

PHP-GTKはさらに拡張していくだろうと考え、私は専用のメーリング リストとCVSリポジトリ、そしてCollin Viebrockの助けを得て ウェブサイト(gtk.php.net)を用意しました。ドキュメンテーションは 目下進行中でJames Mooreが手伝ってくれています。

PHP-GTKはリリース以来徐々に広がっています。ドキュメンテーション チームもは日々マニュアルを更新していますし、PHP-GTK用の拡張 モジュール、そしてPHP-GTKを使った興味深いアプリケーションを 作成する人も増えてきています。


PHP関連の本

PHPが成長していくに従って、開発プラットフォームとして世界中で 有名になっていきました。この流れを確かめる面白い方法のうちの 一つは、初期の頃から現在に到るまで頻繁に出版されつづけている PHPに関する本を観察してみることです。

私たちの知る限り、PHPを扱った最初の本は1999年の4月にチェコで出版された 'PHP - tvorba interaktivnich internetovych aplikaci' (PHP - Creating Interactive Internet Applications) で、Jirka Kosekにより書かれたものです。 翌月、Egon Schmid, Christian Cartus, Richard Blumeにより 書かれたドイツ語の本が続いて出版されました。 PHPについて書かれた英語の本、 Leon Atkinsonによる'Core PHP Programming'がそのすぐ後に出版され ました。これらの本は、いずれも PHP 3.0を扱っていました。 (訳註:日本語では、PHPをタイトルとする本「PHP徹底攻略」(堀田、石井、廣川)の 初版が1999年9月に出版されています。)

こうした最初の出版物に続いて、多くの著者、出版社から数多くの 本が出版されました。その数は英語で400冊以上、ドイツ語で100冊以上、 フランス語やスペイン語で50冊以上にもなります！さらに他の言語、 たとえば韓国語、日本語そしてヘブライ語でも本が出版されています。

このようにPHPに関する書籍が、異なった著者により執筆され、 多くの出版社から出版され、多くの言語で書かれている、という 事実はPHPが世界的に成功している強い証拠であると言えるでしょう。


PHP関連の出版物

私たちの知る限り、PHPに関する記事が最初に掲載された雑誌は 1998年の春に出版されたthe Czech mutation of Computerworldで、 PHP 3.0が扱われていました。本と同様に、これに続いて様々な すばらしい雑誌にPHPに関する記事が掲載されています。

PHPに関する記事はDr. Dobbs, Linux Enterprise, Linux Magazine, その他多くの雑誌に掲載されています。ASPベースのアプリケーションを Windows上で動作するPHPに移植する記事が、なんと MicrosoftのMSDNに 掲載されています！


PHP 8.2.x から PHP 8.3.x への移行

目次

  • 新機能
  • 新しいクラスとインターフェイス
  • 新しく追加された関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 8.3.x で推奨されなくなる機能
  • その他の変更
  • Windows のサポート

この新しいマイナーバージョンには、たくさんの 新機能 と 互換性のない変更がいくつか あります。実運用環境の PHP をこのバージョンにあげる前に、これらの変更を必ずテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.1.x, 7.2.x, 7.3.x, 7.4.x, 8.0.x, 8.1.x, 8.2.x.


新機能

PHP コア

readonly 機能の修正

無名クラスも、readonly としてマークできるようになりました。

読み取り専用プロパティは、clone している間に再初期化できるようになりました。

クラス定数に対する型宣言

クラス、インターフェイス、トレイト、そして列挙型の定数は、新たに型宣言をサポートするようになりました。

マジックメソッドで作ったクロージャ

マジックメソッドで作ったクロージャは、名前付き引数を受け入れるようになりました。

トレイトのメソッドに対する final 指定

トレイトからメソッドを使う場合に、そのメソッドに対して final を指定できるようになりました。

Override アトリビュート

親クラスまたは実装済みのインターフェイス内で、メソッドが存在するかを調べるアトリビュートとして、#[\Override] が追加されました。

クラス定数への動的なアクセス構文

クラス定数は、C::{$name} という構文で動的にアクセスできるようになりました。

static 変数の初期化

static 変数を初期化する際に、任意の式が使えるようになりました。

INI 変数に対するデフォルト値指定

ini ファイル内で、デフォルト値を指定する文法をサポートしました。

<?php
/*
/path/to/user.ini に、以下の設定が含まれているとします:

listen = localhost:${DRUPAL_FPM_PORT:-9000}
*/
$user_ini = parse_ini_file('/path/to/user.ini');
echo $user_ini['listen']; // localhost:9000

CLI

複数のファイルの文法チェックを、一度にできるようになりました。

DOM

プロパティ DOMElement::$className と、DOMElement::$id が追加されました。libxml2 の制限により、現時点でこれらはバイナリセーフではありません。つまり、プロパティの値から NUL バイト以降が切り捨てられるということです。

プロパティ DOMNode::$isConnected と DOMNameSpaceNode::$isConnected が追加されました。

プロパティ DOMNode::$parentElement と DOMNameSpaceNode::$parentElement が追加されました。

FFI

FFI\CData を他の FFI\CData に代入できるようになりました。つまり、CData を構造体やフィールドに代入できるようになったということです。

Opcache

opcache_get_status()['scripts'][n]['revalidate'] の値に、いつスクリプトの更新チェックを行うかの予定が Unix タイムスタンプの形で含まれるようになりました。いつチェックを行うかは、opcache.revalidate_freq によって決まります。

POSIX

posix_getrlimit() で、リソースの制限値をひとつ取得できる、オプションの $resource パラメータが使えるようになりました。

posix_isatty() は、通常のパラメータ解釈のセマンティクス(ZPP) に従い、整数値に対して警告を発生させるようになりました。

posix_ttyname() は、通常のパラメータ解釈のセマンティクス(ZPP) に従い、整数値に対して警告を発生させるようになりました。さらに、無効なファイルディスクリプタの整数値に対しても、警告を発生させるようになっています。

Streams

以前のバージョンでは実装されていなかった新しい通知として、STREAM_NOTIFY_COMPLETED が発生させられるようになりました。


新しいクラスとインターフェイス

Date

  • DateError
  • DateObjectError
  • DateRangeError
  • DateException
  • DateInvalidOperationException
  • DateInvalidTimeZoneException
  • DateMalformedIntervalStringException
  • DateMalformedPeriodStringException
  • DateMalformedStringException

Random

  • Random\IntervalBoundary


新しく追加された関数

Date

  • DatePeriod::createFromISO8601String()

DOM

  • DOMElement::getAttributeNames()
  • DOMElement::insertAdjacentElement()
  • DOMElement::insertAdjacentText()
  • DOMElement::toggleAttribute()
  • DOMNode::contains()
  • DOMNode::getRootNode()
  • DOMNode::isEqualNode()
  • DOMNameSpaceNode::contains()
  • DOMParentNode::replaceChildren()

国際化関数

  • IntlCalendar::setDate()
  • IntlCalendar::setDateTime()
  • IntlGregorianCalendar::createFromDate()
  • IntlGregorianCalendar::createFromDateTime()

JSON

  • json_validate()

LDAP

  • ldap_connect_wallet()
  • ldap_exop_sync()

マルチバイト文字列

  • mb_str_pad()

Posix

  • posix_sysconf()
  • posix_pathconf()
  • posix_fpathconf()
  • posix_eaccess()

PostgreSQL

  • pg_set_error_context_visibility() (libpq >= 9.6)

Random

  • Random\Randomizer::getBytesFromString()
  • Random\Randomizer::nextFloat()
  • Random\Randomizer::getFloat()

Reflection

  • ReflectionMethod::createFromMethodName()

Sockets

  • socket_atmark()

Standard

  • str_increment()
  • str_decrement()
  • stream_context_set_options()

Zip

  • ZipArchive::getArchiveFlag()


新しいグローバル定数

cURL

  • CURLINFO_CAPATH (libcurl >= 7.84.0)
  • CURLINFO_CAINFO (libcurl >= 7.84.0)
  • CURLOPT_MIME_OPTIONS (libcurl >= 7.81.0)
  • CURLMIMEOPT_FORMESCAPE (libcurl >= 7.81.0)
  • CURLOPT_WS_OPTIONS (libcurl >= 7.86.0)
  • CURLWS_RAW_MODE (libcurl >= 7.86.0)
  • CURLOPT_SSH_HOSTKEYFUNCTION (libcurl >= 7.84.0)
  • CURLOPT_PROTOCOLS_STR (libcurl >= 7.85.0)
  • CURLOPT_REDIR_PROTOCOLS_STR (libcurl >= 7.85.0)
  • CURLOPT_CA_CACHE_TIMEOUT (libcurl >= 7.87.0)
  • CURLOPT_QUICK_EXIT (libcurl >= 7.87.0)
  • CURLKHMATCH_OK (libcurl >= 7.19.6)
  • CURLKHMATCH_MISMATCH (libcurl >= 7.19.6)
  • CURLKHMATCH_MISSING (libcurl >= 7.19.6)
  • CURLKHMATCH_LAST (libcurl >= 7.19.6)

国際化関数

  • MIXED_NUMBERS (Spoofchecker)
  • HIDDEN_OVERLAY (Spoofchecker)

OpenSSL

  • OPENSSL_CMS_OLDMIMETYPE
  • PKCS7_NOOLDMIMETYPE

PCNTL

  • SIGINFO

PDO_ODBC

  • PDO_ODBC_TYPE

Posix

  • POSIX_SC_ARG_MAX
  • POSIX_SC_PAGESIZE
  • POSIX_SC_NPROCESSORS_CONF
  • POSIX_SC_NPROCESSORS_ONLN
  • POSIX_PC_LINK_MAX
  • POSIX_PC_MAX_CANON
  • POSIX_PC_MAX_INPUT
  • POSIX_PC_NAME_MAX
  • POSIX_PC_PATH_MAX
  • POSIX_PC_PIPE_BUF
  • POSIX_PC_CHOWN_RESTRICTED
  • POSIX_PC_NO_TRUNC
  • POSIX_PC_ALLOC_SIZE_MIN
  • POSIX_PC_SYMLINK_MAX

Sockets

以下のソケットオプションは、サポートされている場合にのみ定義されます:

  • SO_ATTACH_REUSEPORT_CBPF (Linux)
  • SO_DETACH_BPF (Linux)
  • SO_DETACH_FILTER (Linux)
  • TCP_QUICKACK (Linux)
  • IP_DONTFRAG (FreeBSD)
  • IP_MTU_DISCOVER (Linux)
  • IP_PMTUDISC_DO (Linux)
  • IP_PMTUDISC_DONT (Linux)
  • IP_PMTUDISC_WANT (Linux)
  • IP_PMTUDISC_PROBE (Linux)
  • IP_PMTUDISC_INTERFACE (Linux)
  • IP_PMTUDISC_OMIT (Linux)
  • AF_DIVERT (FreeBSD)
  • SOL_UDPLITE
  • UDPLITE_RECV_CSCOV
  • UDPLITE_SEND_CSCOV
  • SO_RERROR (NetBSD)
  • SO_ZEROIZE (OpenBSD)
  • SO_SPLICE (OpenBSD)
  • TCP_REPAIR (Linux)
  • SO_REUSEPORT_LB (FreeBSD)
  • IP_BIND_ADDRESS_NO_PORT (Linux)

Zip

  • ZipArchive::ER_DATA_LENGTH (libzip >= 1.10)
  • ZipArchive::ER_NOT_ALLOWED (libzip >= 1.10)
  • ZipArchive::AFL_RDONLY (libzip >= 1.10)
  • ZipArchive::AFL_IS_TORRENTZIP (libzip >= 1.10)
  • ZipArchive::AFL_WANT_TORRENTZIP (libzip >= 1.10)
  • ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE (libzip >= 1.10)
  • ZipArchive::FL_OPEN_FILE_NOW
  • ZipArchive::LENGTH_TO_END (ZipArchive::addFile() と ZipArchive::replaceFile() のデフォルト値)
  • ZipArchive::LENGTH_UNCHECKED (libzip >= 1.10)


下位互換性のない変更点

PHP コア

コールスタックがオーバーフローしそうになっているプログラム

コールスタックがオーバーフローしそうになっているプログラムは、zend.max_allowed_stack_size - zend.reserved_stack_size (ファイバーの場合は fiber.stack_size - zend.reserved_stack_size) バイト以上のスタックを使い切った時点で Error をスローするようになりました。

proc_get_status() を複数回コールする

proc_get_status() を複数回コールした場合、POSIX システムでは常に正しい値を返すようになりました。これより前のバージョンでは、最初の呼び出しの場合にだけ正しい値を返していました。proc_get_status() をコールしたあとに proc_close() を呼び出した場合も、正しい終了コードを返すようになりました。これより前のバージョンでは、-1 を返していました。内部的に、この処理は POSIX システム上で結果の値をキャッシュすることで実現しています。以前の振る舞いを望む場合は、proc_get_status() が返す配列の "cached" キーをチェックすることで、結果がキャッシュされているかを確認できます。

実行時間の最大秒数を制御するタイマー

実行時間の最大秒数を制御するタイマーが、Linux 上で ZTS を有効にしてビルドした場合でもデフォルトで有効になりました。

static プロパティと一緒にトレイトを使う

static プロパティと一緒にトレイトを使うと、親クラスから継承する static プロパティを再宣言するようになりました。つまり、現在のクラスのために別の static プロパティを作成するということです。これは、トレイトを使わずに直接 static プロパティを追加する操作に似ています。

空の配列に負のインデックスを割り当てる

空の配列に負のインデックス $n を割り当てた場合、その次のインデックスは 0 ではなく、必ず $n+1 になります。

クラス定数のアクセス権

クラス定数のアクセス権が、インターフェイスから継承した場合でも正しくチェックされるようになりました。

キーが自分自身を参照している WeakMap のエントリ

WeakMap のエントリには、(おそらく推移的に) キーが自分自身を参照しているものがあります。そのキーが到達できない場合に、循環参照のコレクタがそれを削除できるようになりました。但し、WeakMap をループしている場合を除きます (ループ経由で到達できることは、weak と見なされるためです)。これより前のバージョンでは、こうしたエントリは自動で決して削除されませんでした。

Date

日付・時刻の拡張モジュールでは、DateError と DateException の階層に、拡張モジュール特有の例外とエラーを追加しました。これは、エラー時に警告や汎用の例外を発生させていた動作を置き換えるものです。これらによって、エラーや例外をチェックする必要がなくなり、エラーハンドリングが改善できます。

DOM

親が存在しないノード上で DOMChildNode::after(), DOMChildNode::before(), DOMChildNode::replaceWith() をコールしても、親子関係に関する例外をスローせず、何もしなくなりました。これは DOM の仕様が要求している振る舞いです。

ドキュメントノードが存在しない状態で DOMParentNode と DOMChildNode のメソッドを使うと、DOM_HIERARCHY_REQUEST_ERR DOMException をスローせず、エラーなしで動作するようになりました。これはDOMの仕様が要求している振る舞いです。

prefix を指定せずに DOMDocument::createAttributeNS() をコールすると、デフォルトの名前空間を誤って作成し、その名前空間中に属性ではなく要素を置いていました。PHP 8.3 では、このバグが修正されています。

以前のバージョンでは、DOMDocument::createAttributeNS() は、prefix が既に異なる URI で使われている場合に DOM_NAMESPACE_ERRNAMESPACE_ERR DOMException をスローしていました。 このバージョンからは、prefix の名前が衝突していた場合でも、異なる prefix を正しく選べるようになりました。

新しいメソッドやプロパティが DOM クラスに追加されました。ユーザー定義のクラスがこれらを継承し、メソッドやプロパティを親クラスのものと同じ名前で宣言した場合、それらの宣言には互換性がなければいけません。互換性がない宣言の場合、それを指摘するコンパイルエラーがスローされることになります。新しく実装されたメソッドやプロパティについては、新機能 のセクションと 新しく追加された関数 を参照ください。

FFI

void 型を返すC言語の関数は、object(FFI\CData:void) { } ではなく、null を返すようになりました。

Opcache

INI ディレクティブ opcache.consistency_checks が削除されました。この機能は tracing JIT や、inheritance cache (継承関係をキャッシュする機能) と一緒に使った場合に壊れてしまっていました。その後、このディレクティブを有効にする方法が見つからないまま、PHP 8.1.18 と 8.2.5 で無効にされました。tracing JIT と inheritance cache は両方、スクリプトが永続化された後に共有メモリを変更し、そのチェックサムを無効にする可能性があります。変更されうるポインタをスキップする変更も試みられましたが、複雑過ぎて受け入れられませんでした。以上の理由から、壊れてしまうバグを修正するのではなく、ディレクティブそのものが削除されることになりました。

Phar

Phar クラスの定数が、型宣言するようになりました。

標準ライブラリ

range() 関数に対して、さまざまな変更が加えられました:

  • オブジェクトやリソース、配列を境界の値として渡すと、TypeError がスローされるようになりました。
  • $step に 0 を渡すと、よりわかりやすい ValueError がスローされるようになりました。
  • 範囲が増加しているのに、$step に負の値を渡すと、ValueError がスローされるようになりました。
  • $step が整数型として解釈できる float の場合、整数型として解釈するようになりました。
  • 引数のいずれかが無限大または NAN の場合、ValueError がスローされるようになりました。
  • $start や $end が空文字列の場合、E_WARNING が発生するようになりました。値そのものが 0 にキャストされる動作は変更されていません。
  • $start や $end が1バイトより長い場合、E_WARNING が発生するようになりました。但し、それが数値形式の文字列でない場合に限ります。
  • $start や $end が整数型にキャストした値の場合、E_WARNING が発生するようになりました。なぜなら、他の境界の入力値は数値だからです。(例: range(5, 'z');)
  • $step が float の場合で、ある範囲の文字を生成しようとした場合、E_WARNING が発生するようになりました。但し、境界の値がともに数値形式の文字列の場合を除きます。(例: range('5', '9', 0.5); のようなコードは、警告が発生しません)
  • range() 関数は、境界の値の一方が数字の場合、もう片方の境界の値を整数にキャストせず、文字のリストを生成するようになりました。(例: range('9', 'A');).
<?php
range('9', 'A'); // PHP 8.3.0 以降は、["9", ":", ";", "<", "=", ">", "?", "@", "A"]
range('9', 'A'); // PHP 8.3.0 より前は、[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
?>

number_format() は、負の $decimals の値を小数点以下 $num 桁から abs($decimals) 桁に丸めるようになりました。 これより前のバージョンでは、負の $decimals は黙って無視されていました。

file() 関数の flags パラメータは、すべての不正な値をチェックするようになりました。注意すべきなのは、これより前のバージョンでは FILE_APPEND を黙って受け入れていましたが、このバージョンから受け入れなくなったことです。

SNMP

SNMP クラスの定数が、型宣言するようになりました。


PHP 8.3.x で推奨されなくなる機能

PHP コア

加算子/減算子 に対する変更

空文字列や、数値形式でない文字列、そして英数字でない文字列に対して、加算子 (++) を使うことは推奨されなくなりました。さらに、数値形式でない文字列に 加算子 を使うことも、soft-deprecated 扱いになりました。つまり、E_DEPRECATED は発生しないものの、新しいコードではこの機能を使うべきではないということです。新しい str_increment() 関数を代わりに使いましょう。

空文字列や数値形式でない文字列に対して、減算子 (--) を使うことは推奨されなくなりました。

引数を渡さずに get_class()/get_parent_class() をコールする

get_class() と get_parent_class() を、引数を渡さずにコールすることは、推奨されなくなりました。

DBA

$dba を第3引数に渡して dba_fetch() をコールすることは、推奨されなくなりました。

FFI

FFI::cast(), FFI::new(), FFI::type() を static メソッドとしてコールすることは、推奨されなくなりました。

国際化関数

定数 U_MULTIPLE_DECIMAL_SEP*E*RATORS は、推奨されなくなりました。代わりに U_MULTIPLE_DECIMAL_SEP*A*RATORS を使いましょう。

定数 NumberFormatter::TYPE_CURRENCY は、推奨されなくなりました。

LDAP

ldap_connect() に、$hostname と $port を別々に渡してコールすることは、推奨されなくなりました。

マルチバイト文字列

mb_strimwidth() に負の $width を渡すことは、推奨されなくなりました。

Phar

resource と $length を渡して Phar::setStub() をコールすることは、推奨されなくなりました。$phar->setStub(stream_get_contents($resource)); に置き換えるべきです。

Random

メルセンヌ・ツイスタ の動作モード MT_RAND_PHP は、推奨されなくなりました。

リフレクション

ReflectionProperty::setValue() にひとつだけ引数を渡してコールすることは、推奨されなくなりました。static プロパティを設定するには、最初の引数に null を渡します。

標準ライブラリ

assert_options() 関数は、推奨されなくなりました。

定数 ASSERT_ACTIVE, ASSERT_BAIL, ASSERT_CALLBACK, ASSERT_EXCEPTION, ASSERT_WARNING は、推奨されなくなりました。

INI 設定 assert.* は、推奨されなくなりました。詳細は INI ファイルの扱いの変更 を参照ください。

SQLite3

例外を使うことが推奨されるようになりました。警告は将来のバージョンで削除されます。SQLite3::enableExceptions(false) をコールすると、このバージョンでは推奨されない警告が発生します。

Zip

定数 ZipArchive::FL_RECOMPRESS は、推奨されなくなりました。将来の libzip のバージョンで削除されます。


その他の変更

PHP コア

FFI

opcache.preload_user が現在のシステムユーザーに設定されている場合、事前ロードの間に FFI::load() をコールできるようになりました。これより前のバージョンでは、opcache.preload_user が設定されている場合は、事前ロードの間に FFI::load() を呼び出せませんでした。

FPM

ソケットのパスの長さが OS がサポートする長さ以上の場合、FPM CLI のテストが失敗するようになりました。

Opcache

CLI SAPI と phpdbg SAPI では、opcache.preload_user ディレクティブを設定しなくても root として事前ロードを実行できるようになりました。これら以外の SAPI では、root として事前ロードを実行する際に このディレクティブの設定が未だ必須です。なぜなら、SAPI が特権を持っていないユーザに移行する前に事前ロードが実行されるからです。

Streams

ソケット接続をブロックする fread() 関数は、バッファリングされているデータが存在した場合、追加のデータを待つのではなく、すぐに値を返すようになりました。

seek のオフセットが終端を超えた場合でも、memory ストリームは失敗しなくなりました。代わりに、次回書き込まれたときにメモリサイズが増加し、以前の終端からオフセットまでの間は、ファイルを扱っているときのようにゼロバイトで埋められます。

stat() のファイルアクセス操作が、file_exists() 類似の関数と同様に、ストリームのパスではなく、実在のパスを使うようになりました。これはストリームをオープンするときの振る舞いと一致します。

SAPI モジュールへの変更

CLI

STDOUT, STDERR, STDIN ストリームは、リソースが破棄される際にクローズされなくなりました。リソースが破棄されるタイミングでは CLI がほぼ終了しているからです。但し、fclose() やその類似の関数を使い、これらのストリームを明示的に閉じることは未だできます。

変更された関数

PHP コア

gc_status() に、以下の8つのフィールドが追加されました:

  • "running" => bool
  • "protected" => bool
  • "full" => bool
  • "buffer_size" => int
  • "application_time" => float: gc の合計の実行時間を秒単位で示します(collector_time を含みます)
  • "collector_time" => float: 循環参照を回収するのに使った時間を秒単位で示します(dessructor_time と free_time を含みます)
  • "destructor_time" => float: 循環参照を回収している間に、デストラクタを実行した時間を秒単位で示します
  • "free_time" => float: 循環参照を回収している間に、メモリを開放するのにかかった時間を秒単位で示します

class_alias() は、内部クラスのエイリアスを作成する操作もサポートしました。

ini_set('open_basedir', ...); を実行して実行時に open_basedir を設定する場合、親ディレクトリ (..) を含んだパスを受け入れなくなりました。これより前のバージョンでは、.. で始まるパスだけを拒否していました。.. で始まるパスのみを拒否する制限は、パスの先頭に ./ を付加することで簡単に回避できてしまっていました。

ユーザー定義の例外ハンドラは、シャットダウン時の例外もキャッチするようになりました。

highlight_string() と highlight_file() の結果として出力されるHTMLが、変更されました。外側のHTMLタグの間にあるホワイトスペースは削除されます。改行とスペースはHTMLエンティティに変換されなくなりました。HTML全体を <pre> タグで囲むようになっています。外側の <span> タグは <code> タグに統合されました。

Calendar

easter_date() は、64ビットシステム上で 1970 から 2,000,000,000 までの年の値をサポートしました。これより前のバージョンでは、1970 から 2037 までの年の値だけをサポートしていました。

Curl

curl_getinfo() は、新しく2つの定数をサポートしました: CURLINFO_CAPATH と CURLINFO_CAINFO です。$option が null の場合、以下の追加のキーが含まれるようになります: "capath", "cainfo"

DOM

DOMCharacterData::appendData() の仮の戻り値の型が、true に変更されました。

DOMDocument::loadHTML(), DOMDocument::loadHTMLFile(), DOMDocument::loadXML() の仮の戻り値の型が、bool になりました。これより前のバージョンでは、DOMDocument|bool を返すとドキュメントに記されていましたが、PHP 8.0 以降は static にコールできなかったため、 DOMDocument が返せていませんでした。

Gd

imagerotate() 関数のシグネチャが変更され、$ignore_transparent パラメータが削除されました。このパラメータは PHP 5.5.0 以降、無視されていたためです。

国際化関数

datefmt_set_timezone() (とそのエイリアス IntlDateformatter::setTimeZone()) は、成功時に true を返すようになりました。これより前のバージョンでは、null を返していました。

IntlBreakiterator::setText() は、失敗時に false を返すようになりました。これより前のバージョンでは、null を返していました。 また、成功時に true を返すようになりました。これより前のバージョンでは、null を返していました。

IntlChar::enumCharNames() は、戻り値として boolean を返すようになりました。これより前のバージョンでは、成功時に null、失敗時に false を返していました。

IntlDateFormatter::__construct() は、無効なロケールを設定した場合に U_ILLEGAL_ARGUMENT_ERROR 例外をスローするようになりました。

マルチバイト文字列

mb_strtolower() と mb_convert_case() は、ギリシャ文字シグマの条件付きケース変換規則を実装しました。mb_convert_case() では、条件付きケース変換は MB_CASE_LOWER と MB_CASE_TITLE モードにのみ適用され、MB_CASE_LOWER_SIMPLE と MB_CASE_TITLE_SIMPLE には適用されません。

mb_decode_mimeheader() は、RFC 2047 で要求された通りに、Qprint でエンコードされた単語のアンダースコアを解釈するようになりました。つまり、それらはスペースに変換されます。このようにMIMEエンコードされた単語では、アンダースコアは "=5F" としてエンコードしなければいけません。

mb_encode_mimeheader() の実装が変更され、レアケースではあるものの、PHP 8.2 で生の ASCII として渡されていた入力文字列が、transfer_encoding の値でエンコードされる場合があります。

mb_encode_mimeheader() は、入力文字列が Qprint エンコーディングの場合に、NUL(ゼロ)バイトを削除しなくなりました。これより前のバージョンでは、あるテキストエンコーディングの場合(特に UTF-16 と UTF-32) に NUL バイトが削除され、mb_encode_mimeheader の結果が壊れる場合がありました。

mb_detect_encoding() の "$strict に true を指定しない" モードが、ドキュメントの通りに振る舞うようになりました。これより前のバージョンでは、入力文字列と同一のバイト(たとえば、最初のバイト) が、候補となるエンコーディングのリスト全てに対して不正と判定された場合でも、false を返していました。もっと一般化すると、不正なバイトが見つかった時点で、候補となるエンコーディングから削除してしまっていました。そして、入力と同一のバイトを削除した場合に、残りのエンコーディングをすべて候補として考慮すべき場合でも、false を返していました。一方で、候補となるエンコーディングが削除されて残りがひとつだけになった場合、文字列中で後にどれくらいエンコーディングのエラーが見つかるのかを考慮することなく、その残ったエンコーディングを返していました。この振る舞いは、ドキュメントの以下の説明と一致しません: "strict が false の場合、 もっとも近いと判定された文字エンコーディングが返されます"

mysqli

mysqli_fetch_object() は、$constructor_args が空でないのに、クラスにコンストラクタが存在しない場合、 Exception ではなく ValueError を発生させるようになりました。

mysqli_poll() は、$read と $error が両方渡されない場合、ValueError を発生させるようになりました。

mysqli_field_seek() と mysqli_result::field_seek() の戻り値の型が、bool ではなく true に変更されました。

ODBC

odbc_autocommit()は、$enable パラメータで null を受け入れるようになりました。null を渡すと、パラメータをひとつ渡した場合と同じ振る舞いをします。つまり、自動コミットが有効かどうかだけを示す動きをします。

PostgreSQL

pg_fetch_object() は、$constructor_args が空でないのに、クラスにコンストラクタが存在しない場合、Exception ではなく ValueError を発生させるようになりました。

pg_insert() は、指定されたテーブルが無効な場合に、E_WARNING ではなく ValueError を発生させるようになりました。

pg_insert() と pg_convert() は、フィールドの値/タイプ が PostgreSQL の型と一致しない場合に、E_WARNING ではなく ValueError または TypeError を発生させるようになりました。

pg_fetch_result(), pg_field_prtlen(), pg_field_is_null() のパラメータ $row は、nullable になりました。

Random

mt_srand() と srand() は、ランダムなシードを使うかを決めるために、引数の数をチェックしなくなりました。null を渡すとランダムなシードを生成します。0 を渡すとゼロをシードとして使います。これらの関数の振る舞いは、Random\Engine\Mt19937::__construct() と一貫したものになりました。

リフレクション

ReflectionClass::getStaticProperties() の戻り値の型は、nullable ではなくなりました。

標準ライブラリ

unserialize() で発生していた E_NOTICE は、E_WARNING に変更されました。

処理されていない入力が残っている場合に、unserialize() は新たに E_WARNING を発生させるようになりました。

array_pad() は、配列が持つことができる最大の要素数だけを制限するようになりました。これより前のバージョンでは、一度に追加できる最大の要素数が 1048576 になっていました。

strtok() は、トークンの分割を開始した際にトークンが与えられていない場合、E_WARNING を発生させるようになりました。

password_hash() は、ソルトの生成が失敗した場合に、ValueError の $previous (直前にスローされた例外) として、既に存在する Random\RandomException をチェインさせるようになりました。

proc_open() の $command に配列を指定する場合、空でない要素を少なくともひとつ含んでいることが必須になりました。そうでない場合、ValueError がスローされます。

proc_open() の $command に配列を指定する場合、かつそれが不正なコマンドの場合に、後に警告が発生するリソースではなく false を返すようになりました。Windows では既にそのように動作していましたが、posix_spawn を使っている場合(ほとんどのプラットフォーム Linux, BSD, MacOS) でも同様の振る舞いをするようになりました。ただ、posix_spawn をサポートしていないために、以前の振る舞いが変更されていない古いプラットフォームもまだ残っています。

array_sum() と array_product() は、配列に含まれる値が int/float に変換できない場合、警告を発生させるようになりました。これより前のバージョンでは、配列とオブジェクトは無視され、それら以外の値は int にキャストされていました。さらに、数値へのキャストを定義しているオブジェクト (例: GMP) は、無視されるのではなく、数値に変換されるようになっています。

number_format() の $decimals パラメータは、負の整数値の四捨五入も扱うようになりました。つまり、$decimals が負の値の場合、$num は 小数点以下の有効桁数 $decimals 桁に丸められます。これより前のバージョンでは、負の $decimals を指定しても、黙って無視され、数値は小数点以下が0桁になるように丸められていました。

strrchr() に $before_needle が追加されました。これは strstr() や stristr() の対応するパラメータと、似た振る舞いをします。

str_getcsv() と fgetcsv() は、最後のフィールドに終端されていないクォートだけが含まれている場合、null バイトの文字列をひとつ返すのではなく、空文字列を返すようになりました。

拡張モジュールへのその他の変更

PHP コア

bool 型の値に対して、加算子/減算子 (++/--) を使うと、警告が発生するようになりました。現状、この操作にはなんの意味もありませんが、将来的に $bool += 1 のような振る舞いをするようになるからです。

null 型の値に対して、減算子 (--) を使うと、警告が発生するようになりました。現状、この操作にはなんの意味もありませんが、将来的に $null -= 1 のような振る舞いをするようになるからです。

内部オブジェクトで、_IS_NUMBER キャストを実装しているものの、加算と減算の振る舞いを上書きする do_operator ハンドラを実装していない場合があります。この場合でも、$o += 1 や $o -= 1 をあたかも実行したかのように、値をインクリメント / デクリメントできるようになりました。

DOM

DOM の寿命を管理する仕組みが書き直され、暗黙のうちに削除されていたノードが取得できるようになりました。これより前のバージョンでは、削除されていたノードを取得しようとすると例外が発生していました。

SQLite3

SQLite3 クラスは、Exception ではなく、(Exception を継承した) SQLite3Exception をスローするようになりました。

SQLite のエラーコードは、エラーメッセージに含められるのではなく、例外に渡されるようになりました。

INI ファイルの扱いの変更

  • assert.* INI 設定は、推奨されなくなりました。 以下の INI 設定が該当します:

    • assert.active
    • assert.bail
    • assert.callback
    • assert.exception
    • assert.warning
    これらの設定値がデフォルト値の場合、推奨されない警告は発生しません。zend.assertions を代わりに使うべきです。

  • zend.max_allowed_stack_size は、許可される最大のスタックサイズの値を設定するための、新しい INI ディレクティブです。設定できる値は、0 (プロセスやスレッドの、スタックサイズの最大値を用います)、-1 (無制限)、そしてバイト単位の正の数値です。デフォルトは 0 です。プロセスやスレッドのスタックサイズの最大値がわからない場合、既知のシステムのデフォルト値を使います。この値に大き過ぎる値を設定すると、スタックサイズの制限を無効にすることと同じ効果があります。ファイバーは 許可される最大のスタックサイズとして fiber.stack_size の値を使います。プロセスのコールスタックが `zend.max_allowed_stack_size - zend.reserved_stack_size` バイトを超えると、スタックオーバーフローが引き起こすセグメンテーションフォルトを防ぐため、Error がスローされます。これは、デバッグを容易にすることが目的です。スタックサイズは、制御されていない再帰処理によって増加します。増加する範囲は、内部関数やマジックメソッド __toString(), __clone(), __sleep(), __destruct() 内も含みます。この機能はスタックバッファのオーバーフローとは無関係ですし、セキュリティのための機能でもありません。

  • zend.reserved_stack_size は、予約済みのスタックサイズをバイト単位で設定するための、新しい INI ディレクティブです。許可されたスタックサイズの最大値から、この値がバッファとして引かれ、スタックサイズがチェックされます。

パフォーマンスに関わる変更

DOM

DOMNodeList をループさせた場合、キャッシュを使うようになりました。よって、ノードをリクエストする処理に、デフォルトで O(n^2) 時間かかることはなくなりました。

ノードからテキストを取得する際に、メモリを確保する処理を避けるようになりました。この結果、パフォーマンスが向上しています。

DOMChildNode::remove() は、計算量が O(1) で実行されるようになりました。

標準ライブラリ

file() 関数の flags パラメータのエラーチェックは、約7% 高速になりました。

Standard PHP Library(SPL)

RecursiveDirectoryIterator を使ってディレクトリをループする場合の、I/O が削減されました。


  • ≪ その他の変更
  • PHP 8.1.x から PHP 8.2.x への移行 ≫
  • PHP Manual
  • PHP 8.2.x から PHP 8.3.x への移行
  • Windows のサポート

Windows のサポート

PHP コア

PHP の実行をサポートする Windows の最低バージョンが、Windows 8 と Windows Server 2012 になりました。


PHP 8.1.x から PHP 8.2.x への移行

目次

  • 新機能
  • 新しく追加された関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 8.2.x で推奨されなくなる機能
  • その他の変更
  • Windows のサポート

この新しいマイナーバージョンには、 たくさんの 新機能 と 互換性のない変更 がいくつかあります。 実運用環境の PHP をこのバージョンにあげる前に、 これらの変更を必ずテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.1.x, 7.2.x, 7.3.x, 7.4.x, 8.0.x, 8.1.x.


新機能

PHP コア

SensitiveParameter アトリビュート

バックトレースから機密情報を削除するためのアトリビュートとして、 #[\SensitiveParameter] が追加されました。

error_log_mode INI ディレクティブ

エラーログファイルに対してパーミッションを設定できる INI ディレクティブとして、 error_log_mode が追加されました。

定数式の中で、列挙型のプロパティを取得

定数式の中で、列挙型 のプロパティを取得できるようになりました。

型システムの改善

null と false が独立した型として使えるようになりました。

true 型が追加されました。

交差型 と union型 が組み合わせて使えるようになりました。 その場合、型は DNF として記す必要があります。

トレイトで定数

トレイトの中で、定数を定義できるようになりました。

読み取り専用クラス

クラスに対して readonly を指定する機能 がサポートされました。

cURL

CURLINFO_EFFECTIVE_METHOD オプションが追加されました。 これは、curl_getinfo() の戻り値として、 有効な HTTP メソッドの値を返します。

libcurl 7.62 から 7.80 までに追加された、 新しい複数の定数 が使えるようになりました。

接続を維持するためのチェックを行う関数として、 curl_upkeep() が追加されました。

DBA

データベースファイルを作成する際にサブディレクトリを作るかどうかを決めるフラグとして、 DBA_LMDB_USE_SUB_DIR と DBA_LMDB_NO_SUB_DIR が追加されました。 これらは、LMDB ドライバで使えます。

OCI8

oci8.prefetch_lob_size INI ディレクティブと、 oci_set_prefetch_lob() が追加されました。 これらを使うと、LOB(ラージオブジェクト) を取得する際に、PHP と Oracle Database 間の通信回数を削減することで、 LOB への問い合わせのパフォーマンスチューニングを行うことができます。

OpenSSL

chacha20-poly1305 向けに AEAD のサポートが追加されました。

ODBC

新しい関数 odbc_connection_string_is_quoted(), odbc_connection_string_should_quote(), odbc_connection_string_quote() が追加されました。 これらは主に、ODBC や PDO_ODBC 拡張モジュールの裏側で使われるものです。 ただ、ユニットテストを容易にしたり、 ユーザーアプリケーションやライブラリ自体がクォートを行えるようにする目的で、 ユーザーが使える関数として公開されています。

PCRE

修飾子 n (NO_AUTO_CAPTURE) のサポートが追加されました。 これを使うと、単純な (xyz) 形式でのグループ化ではキャプチャを行いません。 (?<name>xyz) のような、名前付きのグループ化を使う場合にのみ、 キャプチャを行うようになります。 これによって影響を受けるのは、どのグループがキャプチャされるかだけです。 番号付きのサブパターンによる参照もまだ使えますし、 その場合マッチ結果が格納される配列には数値が含まれています。

Random 拡張モジュール

乱数生成器に関連する既存の実装を整理し、統合する新しい拡張モジュールが追加されました。 新しく、かつ優れた乱数生成器が使えるようになり、スコープの問題も解消されています。


新しく追加された関数

cURL

  • curl_upkeep()

IMAP

  • imap_is_open() (PHP 8.2.1 以降)

MySQLi

  • mysqli_execute_query()

ODBC

  • odbc_connection_string_is_quoted()
  • odbc_connection_string_should_quote()
  • odbc_connection_string_quote()

OpenSSL

  • openssl_cipher_key_length()

Reflection

  • ReflectionFunction::isAnonymous()
  • ReflectionMethod::hasPrototype()

Sodium

XChaCha20

  • sodium_crypto_stream_xchacha20_xor_ic()

標準ライブラリ

  • memory_reset_peak_usage()
  • ini_parse_quantity()

XML

  • libxml_get_external_entity_loader()


新しいグローバル定数

COM

  • DISP_E_PARAMNOTFOUND
  • LOCALE_NEUTRAL

cURL

  • CURLALTSVC_H1 (libcurl >= 7.64.1)
  • CURLALTSVC_H2 (libcurl >= 7.64.1)
  • CURLALTSVC_H3 (libcurl >= 7.64.1)
  • CURLALTSVC_READONLYFILE (libcurl >= 7.64.1)
  • CURLAUTH_AWS_SIGV4 (libcurl >= 7.75.0)
  • CURLE_PROXY (libcurl >= 7.73.0)
  • CURLFTPMETHOD_DEFAULT
  • CURLHSTS_ENABLE (libcurl >= 7.74.0)
  • CURLHSTS_READONLYFILE (libcurl >= 7.74.0)
  • CURLINFO_PROXY_ERROR (libcurl >= 7.73.0)
  • CURLINFO_REFERER (libcurl >= 7.76.0)
  • CURLINFO_RETRY_AFTER (libcurl >= 7.66.0)
  • CURLMOPT_MAX_CONCURRENT_STREAMS (libcurl >= 7.67.0)
  • CURLOPT_ALTSVC_CTRL (libcurl >= 7.64.1)
  • CURLOPT_ALTSVC (libcurl >= 7.64.1)
  • CURLOPT_AWS_SIGV4 (libcurl >= 7.75.0)
  • CURLOPT_CAINFO_BLOB (libcurl >= 7.77.0)
  • CURLOPT_DOH_SSL_VERIFYHOST (libcurl >= 7.76.0)
  • CURLOPT_DOH_SSL_VERIFYPEER (libcurl >= 7.76.0)
  • CURLOPT_DOH_SSL_VERIFYSTATUS (libcurl >= 7.76.0)
  • CURLOPT_HSTS_CTRL (libcurl >= 7.74.0)
  • CURLOPT_HSTS (libcurl >= 7.74.0)
  • CURLOPT_MAIL_RCPT_ALLLOWFAILS (libcurl >= 7.69.0)
  • CURLOPT_MAXAGE_CONN (libcurl >= 7.65.0)
  • CURLOPT_MAXFILESIZE_LARGE
  • CURLOPT_MAXLIFETIME_CONN (libcurl >= 7.80.0)
  • CURLOPT_PROXY_CAINFO_BLOB (libcurl >= 7.77.0)
  • CURLOPT_SASL_AUTHZID (libcurl >= 7.66.0)
  • CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (libcurl >= 7.80.0)
  • CURLOPT_SSL_EC_CURVES (libcurl >= 7.73.0)
  • CURLOPT_UPKEEP_INTERVAL_MS (libcurl >= 7.62.0)
  • CURLOPT_UPLOAD_BUFFERSIZE (libcurl >= 7.62.0)
  • CURLOPT_XFERINFOFUNCTION (libcurl >= 7.32.0)
  • CURLPROTO_MQTT (libcurl >= 7.71.0)
  • CURLPX_BAD_ADDRESS_TYPE (libcurl >= 7.73.0)
  • CURLPX_BAD_VERSION (libcurl >= 7.73.0)
  • CURLPX_CLOSED (libcurl >= 7.73.0)
  • CURLPX_GSSAPI (libcurl >= 7.73.0)
  • CURLPX_GSSAPI_PERMSG (libcurl >= 7.73.0)
  • CURLPX_GSSAPI_PROTECTION (libcurl >= 7.73.0)
  • CURLPX_IDENTD_DIFFER (libcurl >= 7.73.0)
  • CURLPX_IDENTD (libcurl >= 7.73.0)
  • CURLPX_LONG_HOSTNAME (libcurl >= 7.73.0)
  • CURLPX_LONG_PASSWD (libcurl >= 7.73.0)
  • CURLPX_LONG_USER (libcurl >= 7.73.0)
  • CURLPX_NO_AUTH (libcurl >= 7.73.0)
  • CURLPX_OK (libcurl >= 7.73.0)
  • CURLPX_RECV_ADDRESS (libcurl >= 7.73.0)
  • CURLPX_RECV_AUTH (libcurl >= 7.73.0)
  • CURLPX_RECV_CONNECT (libcurl >= 7.73.0)
  • CURLPX_RECV_REQACK (libcurl >= 7.73.0)
  • CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED (libcurl >= 7.73.0)
  • CURLPX_REPLY_COMMAND_NOT_SUPPORTED (libcurl >= 7.73.0)
  • CURLPX_REPLY_CONNECTION_REFUSED (libcurl >= 7.73.0)
  • CURLPX_REPLY_GENERAL_SERVER_FAILURE (libcurl >= 7.73.0)
  • CURLPX_REPLY_HOST_UNREACHABLE (libcurl >= 7.73.0)
  • CURLPX_REPLY_NETWORK_UNREACHABLE (libcurl >= 7.73.0)
  • CURLPX_REPLY_NOT_ALLOWED (libcurl >= 7.73.0)
  • CURLPX_REPLY_TTL_EXPIRED (libcurl >= 7.73.0)
  • CURLPX_REPLY_UNASSIGNED (libcurl >= 7.73.0)
  • CURLPX_REQUEST_FAILED (libcurl >= 7.73.0)
  • CURLPX_RESOLVE_HOST (libcurl >= 7.73.0)
  • CURLPX_SEND_AUTH (libcurl >= 7.73.0)
  • CURLPX_SEND_CONNECT (libcurl >= 7.73.0)
  • CURLPX_SEND_REQUEST (libcurl >= 7.73.0)
  • CURLPX_UNKNOWN_FAIL (libcurl >= 7.73.0)
  • CURLPX_UNKNOWN_MODE (libcurl >= 7.73.0)
  • CURLPX_USER_REJECTED (libcurl >= 7.73.0)
  • CURLSSLOPT_AUTO_CLIENT_CERT (libcurl >= 7.77.0)
  • CURLSSLOPT_NATIVE_CA (libcurl >= 7.71.0)
  • CURLSSLOPT_NO_PARTIALCHAIN (libcurl >= 7.68.0)
  • CURLSSLOPT_REVOKE_BEST_EFFORT (libcurl >= 7.70.0)
  • CURL_VERSION_GSASL (libcurl >= 7.76.0)
  • CURL_VERSION_HSTS (libcurl >= 7.74.0)
  • CURL_VERSION_HTTP3 (libcurl >= 7.66.0)
  • CURL_VERSION_UNICODE (libcurl >= 7.72.0)
  • CURL_VERSION_ZSTD (libcurl >= 7.72.0)

DBA

  • DBA_LMDB_USE_SUB_DIR
  • DBA_LMDB_NO_SUB_DIR

Filter

  • FILTER_FLAG_GLOBAL_RANGE

Sockets

以下のソケットオプションは、サポートされている場合にのみ定義されます:

  • SO_INCOMING_CPU
  • SO_MEMINFO
  • SO_RTABLE (OpenBSD)
  • TCP_KEEPALIVE (MacOS)
  • TCP_KEEPCNT (Linux, others)
  • TCP_KEEPIDLE (Linux, others)
  • TCP_KEEPINTVL (Linux, others)
  • TCP_NOTSENT_LOWAT
  • LOCAL_CREDS_PERSISTENT (FreeBSD)
  • SCM_CREDS2 (FreeBSD)
  • LOCAL_CREDS (NetBSD)
  • SO_BPF_EXTENSIONS
  • SO_SETFIB
  • TCP_CONGESTION (Linux, FreeBSD)
  • SO_ZEROCOPY (Linux)
  • MSG_ZEROCOPY (Linux)


下位互換性のない変更点

Date

DateTime::createFromImmutable() の仮の戻り値の型が、 static になりました。 これより前のバージョンでは、DateTime でした。

DateTimeImmutable::createFromMutable() の仮の戻り値の型が、 static になりました。 これより前のバージョンでは、DateTimeImmutable でした。

相対的な書式 の number シンボルは、複数の符号を受け入れなくなりました。 たとえば、+-2 のようなフォーマットです。

ODBC

ODBC 拡張モジュールは、ユーザー名/パスワードと接続文字列が両方渡された場合に、 ユーザー名とパスワードをエスケープするようになりました。そして、 エスケープ済みのものを接続文字列と結合することが必須になりました。 これより前のバージョンでは、 エスケープする必要がある値が含まれたユーザー指定の文字列によって、悪意ある接続文字列を生成される可能性がありました。 また、ユーザー指定の文字列を値に注入されてしまう可能性もありました。 このエスケープのルールは .NET BCL の DbConnectionOptions の振る舞いと同じです。

PDO_ODBC

PDO_ODBC 拡張モジュールは、接続文字列を渡した場合にユーザー名とパスワードをエスケープするようになりました。 詳細は ODBC の変更点 を参照ください。

標準ライブラリ

glob() は、 すべてのパスが open_basedir によって制限されている場合に、 空の配列を返すようになりました。 これより前のバージョンでは、false を返していました。 さらに、パスの一部が open_basedir によって制限されている場合でも、 警告が発生するようになっています。

FilesystemIterator::__construct() を使うと、 以前のバージョンでは FilesystemIterator::SKIP_DOTS が常に設定され、削除できませんでしたが、この振る舞いはなくなりました。 以前の振る舞いを維持するには、 flags パラメータを使ってその定数を明示的に常に設定しなければいけません。 flags パラメータのデフォルト値は変更されていません。

strtolower(),
strtoupper(),
stristr(),
stripos(),
strripos(),
lcfirst(),
ucfirst(),
ucwords(),
str_ireplace() は、ロケールに依存しなくなりました。
これらは、ロケールが "C" であったかのように ASCII のケース変換を行います。
これらの関数のロケール対応版は、マルチバイト文字列 関数で使えます。
さらに、array_change_key_case() 関数を使った場合や、
SORT_FLAG_CASE を使ってソートを行った場合も、ASCII のケース変換を行います。

str_split() は、空文字列を渡した場合に、空の配列を返すようになりました。 これより前のバージョンでは、空文字列の要素が一つ入った配列を返していました。 mb_str_split() は、既に空の配列を返しているため、影響を受けません。

ksort() と krsort() は、 SORT_REGULAR を使って数値文字列の比較を行う際に、 PHP 8 で標準になっているルールを使うようになりました。

var_export() は、クラス名をエクスポートする際、 先頭のバックスラッシュを省略しなくなりました。 つまり、エクスポートされるクラス名は完全修飾名になりました。

Standard PHP Library (SPL)

以下のメソッドは、シグネチャを強制するようになりました:

  • SplFileInfo::_bad_state_ex()
  • SplFileObject::getCsvControl()
  • SplFileObject::fflush()
  • SplFileObject::ftell()
  • SplFileObject::fgetc()
  • SplFileObject::fpassthru()

SplFileObject::hasChildren() の仮の戻り値の型が、 false になりました。 これより前のバージョンでは、bool でした。

SplFileObject::getChildren() の仮の戻り値の型が、 null になりました。 これより前のバージョンでは、?RecursiveIterator でした。

GlobIterator は、 すべてのパスが open_basedir によって制限されている場合に、 空の配列を返すようになりました。 これより前のバージョンでは、false を返していました。 さらに、パスの一部が open_basedir によって制限されている場合でも、 警告が発生するようになっています。


PHP 8.2.x で推奨されなくなる機能

PHP コア

動的なプロパティの利用

クラスにアトリビュート #[\AllowDynamicProperties] を付加していない場合、 動的にプロパティを生成することは推奨されなくなりました。 stdClass で動的なプロパティを使うことはまだ許可されています。 マジックメソッド __get() / __set() を使う場合は、この変更の影響は受けません。 動的なプロパティによる非推奨の警告については、以下によって対応できます:

  • プロパティを宣言する (好ましい対応方法です)
  • クラスにアトリビュート #[\AllowDynamicProperties] を付加する (すべての子クラスにも適用されます)
  • 追加のデータをオブジェクトと関連付ける必要があるが、 そのオブジェクトがデータを所有していない場合、 WeakMap を使う

部分的にしかサポートされていない callable

$callable() 形式で呼び出せない (但し、call_user_func() を使うと呼び出せる) callable は、推奨されなくなりました。 特に注意すべきなのは以下です:

  • "self::method"
  • "parent::method"
  • "static::method"
  • ["self", "method"]
  • ["parent", "method"]
  • ["static", "method"]
  • ["Foo", "Bar::method"]
  • [new Foo, "Bar::method"]
この変更は、 "A::method" や ["A", "method"] のような通常のメソッド呼び出し形式の callable には影響しません。

"${var}" / "${expr}" 形式の、文字列への値の埋め込み

"${var}" と "${expr}" 形式の文字列への値の埋め込みは、推奨されなくなりました。 "$var"/"{$var}" や "{${expr}}" 形式をそれぞれ使ってください。

マルチバイト文字列

'テキストエンコーディング' QPrint, Base64, Uuencode, HTML-ENTITIES を使うことは、 全ての mbstring の関数で推奨されなくなりました。 mbstring でサポートされている他のテキストエンコーディングと異なり、 これらは Unicode のコードポイント列でエンコードされておらず、 生のバイト列でエンコードされています。 これらのテキストエンコーディングが指定された場合、 ほとんどの mbstring 関数では、何が正しい戻り値なのか明確でありません。 さらに、これらのエンコーディングについてはすべて、PHP には別の組み込みの実装が存在します。 たとえば、UUencode されたデータについては、 convert_uuencode() / convert_uudecode() が使えます。

Standard PHP Library(SPL)

内部メソッド SplFileInfo::_bad_state_ex() は、推奨されなくなりました。

標準ライブラリ

utf8_encode() と utf8_decode() は、推奨されなくなりました。


その他の変更

PHP コア

iterable 型は、コンパイル時に組み込みで array|Traversable のエイリアスと見なされるようになりました。 よって、iterable に関連するエラーメッセージは、 array|Traversable のものが使われるようになります。 型のリフレクションは、単一の iterable (および ?iterable) については iterable という名前が付いた ReflectionNamedType を生成しますが、 union 型の中で iterable を使った場合、 array|Traversable に変換されます。

送信される Cookie の日付フォーマットが 'D, d M Y H:i:s \G\M\T' になりました。 これより前のバージョンでは 'D, d-M-Y H:i:s T' でした。

SAPI モジュールへの変更

CLI

STDOUT, STDERR, STDIN ストリームは、リソースが破棄される時にクローズされなくなりました。 これらのクローズは、ほとんどの場合 CLI が終了する際に行われます。 しかし、fclose() や類似の関数を使うことで、これらのストリームを明示的に閉じることはできます。

変更された関数

PHP コア

バイナリセーフな文字列比較を行う strcmp(), strcasecmp(), strncmp(), strncasecmp(), substr_compare() は、 比較対象の文字列の長さが等しくないときに strlen($string1) - strlen($string2) を返すことが保証されなくなり、 -1 や 1 を返すようになりました。 返される具体的な値に依存する代わりに、これらの関数の戻り値は 0 と比較すべきです。

DBA

dba_open() と dba_popen() は、以下のシグネチャを強制するようになりました:

dba_open(
string $path,
string $mode,
?string $handler = null,
int $permission = 0644,
int $map_size = 0,
?int $flags = null
): resource|false

dba_fetch() のオプションの skip 引数は、 PHP でユーザーが使える関数のセマンティクスに従い、最後に置かれるようになりました。 シグネチャは以下になります:

dba_fetch(string|array $key, resource $handle, int $skip): string|false
オーバーロードされたシグネチャは下記のとおりです:
dba_fetch(string|array $key, int $skip, resource $handle): string|false
上記は、引き続き許可されていますが、新しい標準的なシグネチャを使うことを推奨します。

Random

random_bytes() と random_int() は、CSPRNG が失敗した場合に \Random\RandomException をスローするようになりました。 これより前のバージョンでは、\Exception がスローされていました。

Standard PHP Library(SPL)

iterator_to_array() と iterator_count() の iterator 引数の型が Iterator から iterable に拡張され、 配列を渡せるようになりました。

拡張モジュールへのその他の変更

Date

DatePeriod のプロパティが、適切に宣言されるようになりました。

国際化関数

IntlBreakIterator, IntlRuleBasedBreakIterator, IntlCodePointBreakIterator, IntlPartsIterator, IntlCalendar, Collator, IntlIterator, UConverter, IntlDateFormatter, IntlDatePatternGenerator, MessageFormatter, ResourceBundle, Spoofchecker, IntlTimeZone, Transliterator のインスタンスは、シリアライズできなくなりました。 これより前のバージョンでは、シリアライズはできていましたが、 アンシリアライズした際に役に立たないオブジェクトを生成したり、失敗したりしていました。

MySQLi

libmysql のサポートが削除されました。 よって、libmysql を使って mysqli をビルドすることはもはやできません。 このバージョンからは、 mysqli 拡張モジュールは mysqlnd を使った場合にのみコンパイルできます。 以下に示す、mysqlnd で利用できない、libmysql のすべての機能が削除されました:

  • mysqli_driver の reconnect プロパティ
  • mysqli.reconnect INI ディレクティブ
  • 定数 MYSQLI_IS_MARIADB は、推奨されなくなりました

OCI8

必須となる Oracle Client library の最低バージョンが、11.2 になりました。

PCRE

パターン文字列中の NUL 文字 (\0) がサポートされるようになりました。

Session

セッションがアクティブだったり、出力が既に送信された後に session.cookie_samesite を変更しようとすると、変更が失敗するとともに、警告が発生するようになりました。 この変更は、他のセッション関連の INI 設定の振る舞いに合わせたものです。

SQLite3

sqlite3.defensive の変更可能範囲が、INI_USER になりました。

標準ライブラリ

getimagesize() は、AVIF 画像の ビット数、チャンネル情報、幅と高さの情報(dimensions) を返すようになりました。 これより前のバージョンでは、幅と高さの情報は 0x0 として報告され、ビット数とチャンネル情報は全く報告されていませんでした。

Tidy

tidy クラスのプロパティが、適切に宣言されるようになりました。 tidyNode のプロパティも、readonly として適切に宣言されるようになりました。

Zip

Zip 拡張モジュールは、1.20.0 にアップデートされました。 以下のメソッドが追加されています:

  • ZipArchive::clearError()
  • ZipArchive::getStreamName()
  • ZipArchive::getStreamIndex()

INI ファイルの扱いの変更

INI ファイルに数値を設定する際、 2進数のプレフィックス (0b/0B) および、8進数のプレフィックス (0o/0O) を指定する機能がサポートされました。 INI ファイルに数値を設定する際に値をゼロ (0) から始めた場合、 引き続き8進数の数値として解釈されます。

設定項目によっては、不正な値をパースした場合に警告が発生するようになりました。 これより前のバージョンでは、静かに無視されていました。 後方互換を保つため、値を解釈する方法は変更されていません。 影響を受ける設定は、以下のとおりです:

  • bcmath.scale
  • com.code_page
  • default_socket_timeout
  • fiber.stack_size
  • hard_timeout
  • intl.error_level
  • ldap.max_links
  • max_input_nesting_level
  • max_input_vars
  • mbstring.regex_retry_limit
  • mbstring.regex_stack_limit
  • mysqli.allow_local_infile
  • mysqli.allow_persistent
  • mysqli.default_port
  • mysqli.max_links
  • mysqli.max_persistent
  • mysqli.rollback_on_cached_plink
  • mysqlnd.log_mask
  • mysqlnd.mempool_default_size
  • mysqlnd.net_read_buffer_size
  • mysqlnd.net_read_timeout
  • oci8.default_prefetch
  • oci8.max_persistent
  • oci8.persistent_timeout
  • oci8.ping_interval
  • oci8.prefetch_lob_size
  • oci8.privileged_connect
  • oci8.statement_cache_size
  • odbc.allow_persistent
  • odbc.check_persistent
  • odbc.max_persistent
  • odbc.max_links
  • odbc.defaultbinmode
  • odbc.default_cursortype
  • odbc.defaultlrl
  • opcache.consistency_checks
  • opcache.file_update_protection
  • opcache.force_restart_timeout
  • opcache.interned_strings_buffer
  • opcache.jit_bisect_limit
  • opcache.jit_blacklist_root_trace
  • opcache.jit_blacklist_side_trace
  • opcache.jit_debug
  • opcache.jit_hot_func
  • opcache.jit_hot_loop
  • opcache.jit_hot_return
  • opcache.jit_hot_side_exit
  • opcache.jit_max_exit_counters
  • opcache.jit_max_loop_unrolls
  • opcache.jit_max_polymorphic_calls
  • opcache.jit_max_recursive_calls
  • opcache.jit_max_recursive_returns
  • opcache.jit_max_root_traces
  • opcache.jit_max_side_traces
  • opcache.log_verbosity_level
  • opcache.max_file_size
  • opcache.opt_debug_level
  • opcache.optimization_level
  • opcache.revalidate_freq
  • output_buffering
  • pcre.backtrack_limit
  • pcre.recursion_limit
  • pgsql.max_links
  • pgsql.max_persistent
  • post_max_size
  • realpath_cache_size
  • realpath_cache_ttl
  • session.cache_expire
  • session.cookie_lifetime
  • session.gc_divisor
  • session.gc_maxlifetime
  • session.gc_probability
  • soap.wsdl_cache_limit
  • soap.wsdl_cache_ttl
  • unserialize_max_depth
  • upload_max_filesize
  • user_ini.cache_ttl
  • xmlrpc_error_number
  • zend.assertions
  • zlib.output_compression_level


Windows のサポート

PHP コア

Windows 特有のエラーメッセージは、ローカライズされなくなりました。 PHP のエラーメッセージによりマッチさせるため、代わりに英語で表示されます。

仮の、かつとても初期の実験的なサポートとして、 ARM64 版のビルドが追加されました。

OCI8

Oracle 10g を使ってビルドすることはもはやサポートされていないため、 configureオプション --with-oci8 は削除されました。 --with-oci8-11g, --with-oci8-12c, --with-oci8-19 は引き続きサポートされています。

Zip

Zip 拡張モジュールは、1.21.0 にアップデートされました。 かつ、デフォルトで共有ライブラリ (DLL) としてビルドされるようになりました。


PHP 8.0.x から PHP 8.1.x への移行

目次

  • 新機能
  • 新しいクラスとインターフェイス
  • 新しく追加された関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 8.1.x で推奨されなくなる機能
  • その他の変更

この新しいマイナーバージョンには、 たくさんの 新機能 と 互換性のない変更 がいくつかあります。 実運用環境の PHP をこのバージョンにあげる前に、 これらの変更を必ずテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.1.x, 7.2.x, 7.3.x, 7.4.x, 8.0.x.


新機能

PHP コア

8進数の整数リテラルのプレフィックス指定

8進数の整数値の場合に、 数値リテラルのプレフィックスとして明示的に 0o や 0O を指定できるようになりました。 これは、2進数や16進数の整数リテラルの表記と似ています。

<?php
014; // プレフィックス指定がない 8進数のリテラル
0o14; // プレフィックスを指定した 8進数のリテラル
?>

文字列をキーとして持つ配列のアンパック

文字列をキーとして持つ 配列をアンパック できるようになりました。

<?php
$arr1 = [1, 'a' => 'b'];
$arr2 = [...$arr1, 'c' => 'd']; //[1, 'a' => 'b', 'c' => 'd']
?>

引数を展開した後の名前付き引数

引数を ... で展開した後に、名前付き引数を指定できるようになりました。 e.g. foo(...$args, named: $arg).

ファイルアップロード時の full-path キーのサポート

ファイルアップロード時に、 追加で full_path キーを指定できるようになりました。 これにより、アップロードされるファイルの (basename ではなく) フルパスを指定できます。 これは、 "webkitdirectory" 属性 と組み合わせて使うことを意図しています。

列挙型(Enum)

列挙型 のサポートが追加されました。

ファイバー(Fibers)

ファイバー のサポートが追加されました。

第一級callableを生成する記法

myFunc(...) という記法 で、 callable から無名関数を生成できるようになりました。 これは、 Closure::fromCallable('myFunc') と同等です。

注意: ... は文法の一部であり、省略形ではありません。

交差型

交差型 のサポートが追加されました。

警告

交差型 は、 union 型 と一緒に使うことはできません。

Never 型

戻り値にのみ指定できる型として、 新しく never 型が追加されました。 これは、関数が exit() するか、 例外をスローするか、終了しないことを示します。

初期化時の new 式の許可

new ClassName() 式が、引数のデフォルト値の初期化時、 static 変数の初期化時、グローバルな定数の初期化時、 およびアトリビュートの引数として許可されるようになりました。 オブジェクトが define() に渡せるようにもなっています。

読み取り専用プロパティ

プロパティに対して、readonly が指定できるようになりました。

クラス定数の final 指定

クラスの定数に対して、 final が指定できる ようになりました。 また、インターフェイスの定数も、デフォルトでオーバーライド(上書き)できるようになりました。

CURL

CURLOPT_DOH_URL オプションが追加されました。

libcurl >= 7.71.0 で、 証明書を blob 経由で扱うためのオプションが追加されました。

  • CURLOPT_ISSUERCERT_BLOB
  • CURLOPT_PROXY_ISSUERCERT
  • CURLOPT_PROXY_ISSUERCERT_BLOB
  • CURLOPT_PROXY_SSLCERT_BLOB
  • CURLOPT_PROXY_SSLKEY_BLOB
  • CURLOPT_SSLCERT_BLOB
  • CURLOPT_SSLKEY_BLOB

ファイルをファイル経由ではなく、 文字列で POST するために使える CURLStringFile クラスが追加されました。

<?php
$file = new CURLStringFile($data, 'filename.txt', 'text/plain');
curl_setopt($curl, CURLOPT_POSTFIELDS, ['file' => $file]);
?>

FPM

OpenMetrics status フォーマットが追加されました。 これは、Prometheus が FPM のメトリクスを取得する用途に使います。

pm.max_spawn_rate と呼ばれる、 動的なプロセスマネージャーのための、 新しいプールオプションが追加されました。 これを指定することで、 動的なプロセスマネージャーを選択した場合に、 高速にたくさんの子プロセスが起動できるようになります。 これのデフォルト値は 32 で、 以前からハードコーディングされていたものです。

GD

libgd に Avif のサポートが組み込まれている場合に、 imagecreatefromavif() と imageavif() で Avif が使えるようになりました。

Hash

hash(),
hash_file(),
hash_init() 関数に、
オプションの引数 options が追加されました。
これによって、ハッシュアルゴリズム特有のデータを渡せるようになります。

MurmurHash3

ストリーミングをサポートした MurmurHash3 のサポートが追加されました。 以下のバリアントが実装されています:

  • murmur3a, 32-bit hash
  • murmur3c, 128-bit hash for x86
  • murmur3f, 128-bit hash for x64

ハッシュの初期ステートを 引数 options の seed キーを通じて渡すことができます。 たとえば、以下のように書くことができます:

<?php
$h = hash("murmur3f", $data, options: ["seed" => 42]);
echo $h, "\n";
?>
有効な seed の値は 0 から プラットフォーム定義の UINT_MAX までです。 この値は、通常は 4294967295 です。

xxHash

xxHash のサポートが追加されました。 以下のバリアントが実装されています:

  • xxh32, 32-bit hash
  • xxh64, 64-bit hash
  • xxh3, 64-bit hash
  • xxh128, 128-bit hash

ハッシュの初期ステートを 引数 options の seed キーを通じて渡すことができます。 たとえば、以下のように書くことができます:

<?php
$h = hash("xxh3", $data, options: ["seed" => 42]);
echo $h, "\n";
?>
以下のようにして、シークレットを引数 options の secret キーを通じて渡すこともできます:
<?php
$h = hash("xxh3", $data, options: ["secret" => "at least 136 bytes long secret here"]);
echo $h, "\n";
?>
カスタムのシークレットの品質が、 生成されるハッシュ値の品質に重大な影響を及ぼします。 できる限りエントロピーが高いシークレットを使うことを強く推奨します。

MySQLi

新しい INI ディレクティブ mysqli.local_infile_directory

mysqlnd.local_infile_directory ディレクティブが追加されました。 これによって、ファイルを読み込むことを許可するディレクトリを指定できます。 これは、 mysqli.allow_local_infile が無効の場合にだけ意味があります。 なぜなら、 この場合に全てのディレクトリからのファイルの読み込みが許可されるからです。

実行時に引数をバインド

mysqli_stmt::execute() に配列を指定することで、引数をバインドできるようになりました。 全ての値が、文字列としてバインドされます。 (連想配列でない) リストだけを指定できます。 この新機能は、MySQLi を libmysqlclient を使ってコンパイルしている場合には利用できません。

<?php
$stmt = $mysqli->prepare('INSERT INTO users(id, name) VALUES(?,?)');
$stmt->execute([1, $username]);
?>

新しいメソッド mysqli_result::fetch_column()

mysqli_result::fetch_column() が追加されました。これによって、 結果セットから単一のスカラー値を取得することができるようになります。 この新しいメソッドは、 オプションの引数 column に 0 から始まる整数値を指定することで、 どのカラムから情報を取得するかを指定できます。

<?php
$result = $mysqli->query('SELECT username FROM users WHERE id = 123');
echo $result->fetch_column();
?>

PDO

PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY 属性が追加されました。 これによって、ファイルを読み込むことを許可するディレクトリを指定できます。 これは、 PDO::MYSQL_ATTR_LOCAL_INFILE が無効の場合にだけ意味があります。 なぜなら、 この場合に全てのディレクトリからのファイルの読み込みが許可されるからです。

PDO_SQLite

SQLite の "file:" DSN 記法がサポートされるようになり、 追加のフラグも指定できるようになりました。 この機能は、open_basedir が設定されている場合は使えません。

<?php
new PDO('sqlite:file:path/to/sqlite.db?mode=ro')
?>

POSIX

POSIX_RLIMIT_KQUEUES と POSIX_RLIMIT_NPTS が追加されました。 これらの rlimits は、FreeBSD でのみ利用可能です。

標準ライブラリ

fputcsv() は、 新しい引数 eol を受け入れるようになりました。 これによって、カスタムの改行文字を定義できるようになります。 デフォルトは以前と同じで、"\n" のままです。

Standard PHP Library(SPL)

SplFileObject::fputcsv() は、 新しい引数 eol を受け入れるようになりました。 これによって、カスタムの改行文字を定義できるようになります。 デフォルトは以前と同じで、"\n" のままです。


新しいクラスとインターフェイス

cURL

  • CURLStringFile

国際化関数

  • IntlDatePatternGenerator

Reflection

  • ReflectionFiber


新しく追加された関数

PHP コア

  • array_is_list()

GD

  • imagecreatefromavif()
  • imageavif()

MySQLi

  • mysqli_result::fetch_column()
  • mysqli_fetch_column()

プロセス制御

  • pcntl_rfork()

リフレクション

  • ReflectionFunctionAbstract::getClosureUsedVariables()

標準ライブラリ

  • fsync()
  • fdatasync()

Sodium

XChaCha20

  • sodium_crypto_stream_xchacha20()
  • sodium_crypto_stream_xchacha20_keygen()
  • sodium_crypto_stream_xchacha20_xor()

Ristretto255

Ristretto255 関数は、libsodium 1.0.18 以降で利用可能です。

  • sodium_crypto_core_ristretto255_add()
  • sodium_crypto_core_ristretto255_from_hash()
  • sodium_crypto_core_ristretto255_is_valid_point()
  • sodium_crypto_core_ristretto255_random()
  • sodium_crypto_core_ristretto255_scalar_add()
  • sodium_crypto_core_ristretto255_scalar_complement()
  • sodium_crypto_core_ristretto255_scalar_invert()
  • sodium_crypto_core_ristretto255_scalar_mul()
  • sodium_crypto_core_ristretto255_scalar_negate()
  • sodium_crypto_core_ristretto255_scalar_random()
  • sodium_crypto_core_ristretto255_scalar_reduce()
  • sodium_crypto_core_ristretto255_scalar_sub()
  • sodium_crypto_core_ristretto255_sub()
  • sodium_crypto_scalarmult_ristretto255()
  • sodium_crypto_scalarmult_ristretto255_base()


新しいグローバル定数

cURL

  • CURLOPT_DOH_URL
  • CURLOPT_ISSUERCERT_BLOB
  • CURLOPT_PROXY_ISSUERCERT
  • CURLOPT_PROXY_ISSUERCERT_BLOB
  • CURLOPT_PROXY_SSLCERT_BLOB
  • CURLOPT_PROXY_SSLKEY_BLOB
  • CURLOPT_SSLCERT_BLOB
  • CURLOPT_SSLKEY_BLOB

GD

  • IMG_AVIF
  • IMG_WEBP_LOSSLESS

MySQLi

  • MYSQLI_REFRESH_REPLICA

    この定数は、MYSQLI_REFRESH_SLAVE の代替として追加されました。 MySQL の最新の変更に追随したものです。 古い定数は後方互換性を保つためにまだ残されていますが、 将来非推奨になるか、削除される可能性があります。

PCNTL

  • PRIO_DARWIN_BG
  • PRIO_DARWIN_THREAD

POSIX

  • POSIX_RLIMIT_KQUEUES
  • POSIX_RLIMIT_NPTS

Sockets

以下のソケットオプションが、 サポートされている場合に定義されるようになりました:

  • SO_ACCEPTFILTER
  • SO_DONTTRUNC
  • SO_WANTMORE
  • SO_MARK
  • TCP_DEFER_ACCEPT

Sodium

  • SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES
  • SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES
  • SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES
  • SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES
  • SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES
  • SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES
  • SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES
  • SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES

Tokenizer

  • T_READONLY


下位互換性のない変更点

PHP コア

$GLOBALS へのアクセス制限

$GLOBALS 配列へのアクセスに対し、 多くの制限が適用されるようになりました。 $GLOBALS['var'] のような、 個別の配列要素に対する読み取りや書き込みは、 これまで通り動作します。 $GLOBALS 配列全体への読み取り専用のアクセスも、 引き続きサポートされます。 しかし、$GLOBALS 配列全体への書き込みは、 もはやサポートされなくなりました。 たとえば、array_pop($GLOBALS) のようなコードは、エラーが発生します。

継承したメソッド内で static 変数を使う

static 変数を使っているメソッドが継承された (但し、オーバーライドはされていない) 場合、継承されたメソッドは static 変数を親クラスのメソッドと共有するようになりました。

<?php
class A {
public static function counter() {
static $counter = 0;
$counter++;
return $counter;
}
}
class B extends A {}
var_dump(A::counter()); // int(1)
var_dump(A::counter()); // int(2)
var_dump(B::counter()); // int(3), 以前のバージョンでは int(1)
var_dump(B::counter()); // int(4), 以前のバージョンでは int(2)
?>
これは、メソッド中の static 変数が、 static プロパティと同じ振る舞いをするようになったということです。

必須の引数の前に、デフォルト値を持つ引数を指定した場合

必須の引数の前に、 デフォルト値を持つ引数 を指定した場合、 デフォルト値を持つ引数は常に必須の引数として扱われるようになりました。 これは、 名前付き引数 を使って関数を呼び出した場合でも同様です。 PHP 8.0.0 以降、かつ 8.1.0 より前のバージョンでは、 以下のコードは推奨されない警告を発生させていましたが、 呼び出しは成功していました。 PHP 8.1.0 以降では、 ArgumentCountError がスローされるようになっています。 位置を指定して呼び出した場合でも、同じエラーがスローされます。

<?php
function makeyogurt($container = "bowl", $flavour)
{
return "Making a $container of $flavour yogurt.\n";
}
try
{
echo makeyogurt(flavour: "raspberry");
}
catch (Error $e)
{
echo get_class($e), ' - ', $e->getMessage(), "\n";
}
?>

上の例の PHP 8.0 での出力は、このようになります。:

Deprecated: Required parameter container
 in example.php on line 3
Making a bowl of raspberry yogurt.

上の例の PHP 8.1 での出力は、このようになります。:

Deprecated: Optional parameter $container declared before required parameter
 $flavour is implicitly treated as a required parameter in example.php on line 3
ArgumentCountError - makeyogurt(): Argument #1 ($container) not passed

但し、必須の引数の前であっても、 Null を許容する型 を指定するために、 引数にデフォルト値 null を指定できることに注意して下さい。 その場合でも、その引数は必須であることには変わりありません。

内部クラスと戻り値の型の互換性

ほとんどの final でない内部メソッドは、 それをオーバライドする際、 互換性がある戻り値の型を宣言することが必須になりました。 そうしない場合、継承が有効かを検証する際に、 推奨されない警告が発生するようになります。 PHP のバージョン間の互換性を保ちたいがために、 戻り値の型を宣言できない場合、 アトリビュート ReturnTypeWillChange を追加することで警告を抑止できます。

新しいキーワード

readonly は予約されたキーワードになりました。しかし、まだ関数名としては使えます。

never が予約語になりました。 よって、クラスやインターフェイス、 トレイトの名前として使えなくなっています。 名前空間の中であっても同様です。

リソースからオブジェクトへの移行

いくつかの リソース が、object に移行しました。 is_resource() 関数を使って戻り値をチェックしているコードは、 false を返すことをチェックするコードに置き換えるべきです。

  • FileInfo 関数は、 fileinfo リソース ではなく、 finfo オブジェクトを受け取り、 返すようになりました。

  • FTP 関数は、 ftp リソース ではなく、 FTP\Connection オブジェクトを受け取り、 返すようになりました。

  • IMAP 関数は、 imap リソース ではなく、 IMAP\Connection オブジェクトを受け取り、 返すようになりました。

  • LDAP 関数は、 ldap link リソース ではなく、 LDAP\Connection オブジェクトを受け取り、 返すようになりました。

  • LDAP 関数は、 ldap result リソース ではなく、 LDAP\Result オブジェクトを受け取り、 返すようになりました。

  • LDAP 関数は、 ldap result entry リソース ではなく、 LDAP\ResultEntry オブジェクトを受け取り、 返すようになりました。

  • PgSQL 関数は、 pgsql link リソース ではなく、 PgSql\Connection オブジェクトを受け取り、 返すようになりました。

  • PgSQL 関数は、 pgsql result リソース ではなく、 PgSql\Result オブジェクトを受け取り、 返すようになりました。

  • PgSQL 関数は、 pgsql large object リソース ではなく、 PgSql\Lob オブジェクトを受け取り、 返すようになりました。

  • PSpell 関数は、 pspell リソース ではなく、 PSpell\Dictionary オブジェクトを受け取り、 返すようになりました。

  • PSpell 関数は、 pspell config リソース ではなく、 PSpell\Config オブジェクトを受け取り、 返すようになりました。

MySQLi

mysqli_fetch_fields() と mysqli_fetch_field_direct() は、 max_length を指定すると 常に 0 を返すようになりました。 この情報は、結果セットを繰り返し処理する際に計算できますし、 長さの最大値をとります。 PHP でも以前のバージョンから、 内部的にこれと同じ処理が行われてきました。

MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH オプションは、もはや意味をなさなくなりました。

MYSQLI_STORE_RESULT_COPY_DATA オプションは、もはや意味をなさなくなりました。 mysqli::store_result() の mode 引数にどんな値を渡しても、 同様に意味がなくなっています。

mysqli::connect() は、 成功時に null ではなく、true を返すようになりました。

デフォルトのエラー処理モードが、 "silent" から "exceptions" に変更されました。 この変更の意味の詳細と、 どのようにこの属性を明示的に設定するかについては、 MySQLi のエラー報告モード のページを参照ください。 以前のバージョンの振る舞いは、 mysqli_report(MYSQLI_REPORT_OFF); を使うことで再現できます。

mysqli_stmt::execute() を継承したクラスは、 追加でオプションの引数を指定しなければいけません。

MySQLnd

INI ディレクティブ mysqlnd.fetch_data_copy が削除されました。 このディレクティブによって、 ユーザーの目に見える形で、振る舞いが変更されるべきではないからです。

OpenSSL

EC キーの秘密鍵は、他のキーと同じように PKCS#8 フォーマットでエクスポートされるようになりました。

openssl_pkcs7_encrypt() と openssl_cms_encrypt() は、 デフォルト値が RC2-40 から AES-128-CBC に変更されました。 RC2-40 暗号はセキュアではないと見なされており、 OpenSSL 3 からはデフォルトで有効ではなくなっています。

PHP Data Objects(PDO)

PDO::ATTR_STRINGIFY_FETCHES は、bool 型の値を "0" や "1" に変換するようになりました。 以前のバージョンでは、bool は文字列に変換されていませんでした。

PDOStatement::bindColumn() に PDO::PARAM_LOB を指定してコールした場合、 かつ、PDO::ATTR_STRINGIFY_FETCHES が有効になっていない場合は、 常にストリームに結果をバインドするようになりました。 以前のバージョンでは、 使っているデータベースドライバやバインドが行われるタイミングによって、 文字列にバインドされることもあれば、 ストリームにバインドされることもありました。

MySQL ドライバ

結果セットの整数と浮動小数点の値は、 エミュレートされたプリペアドステートメントを使った場合、 文字列ではなく、 ネイティブの PHP の型を使って返されるようになりました。 これは、ネイティブのプリペアドステートメントの振る舞いと一致します。 以前のバージョンの振る舞いは、 PDO::ATTR_STRINGIFY_FETCHES オプションを有効にすることで再現できます。

SQLite ドライバ

結果セットの整数と浮動小数点の値は、 ネイティブの PHP の型を使って返されるようになりました。 以前のバージョンの振る舞いは、 PDO::ATTR_STRINGIFY_FETCHES オプションを有効にすることで再現できます。

Phar

ArrayAccess インターフェイスに準拠するため、 Phar::offsetUnset() と、 PharData::offsetUnset() は bool を返さなくなりました。

標準ライブラリ

version_compare() は、 ドキュメントに書かれていない演算子の省略形を受け入れなくなりました。

htmlspecialchars(), htmlentities(), htmlspecialchars_decode(), html_entity_decode(), get_html_translation_table() のデフォルト値が、 ENT_COMPAT から ENT_QUOTES | ENT_SUBSTITUTE に変更されました。 これは、' が &#039; にエスケープされるようになるということです。 以前のバージョンでは、' に対してはエスケープは行われていませんでした。 さらに、不正な UTF-8 文字列は、空文字列を返すのではなく、 Unicode 置換文字に置きかえられるようになっています。

debug_zval_dump() は、 値の前に & を付加する代わりに、 自身のリファレンスカウントだけでなく、 リファレンスラッパーのリファレンスカウントも表示するようになりました。 これは、PHP 7.0 以降のリファレンスの表現をより正確にモデル化したものです。

debug_zval_dump() は、 インターン化された文字列や、 変更できない配列については、 ダミーのリファレンスカウントではなく、 interned と表示するようになりました。

Standard PHP Library (SPL)

SplFixedArray は、 array のように JSON にエンコードできるようになりました。


PHP 8.1.x で推奨されなくなる機能

PHP コア

__serialize(), __unserialize() がない状態で、 Serializable を実装するのは推奨されない

新しいこれらのメソッドだけを実装するか、 これらのメソッドをサポートしていない PHP 7.4 より前のバージョンでも使う場合は、 新旧両方のインターフェイスを実装すべきです。

ビルトイン関数の nullable でない引数に null を渡した場合

ビルトイン関数のスカラー型の引数は、 デフォルトで nullable ですが、 この振る舞いは推奨されなくなりました。 ユーザ定義の関数においては、 スカラー型の引数は nullable と明示的にマークする必要があり、 その振る舞いと合わせるためです。

<?php
var_dump(str_contains("foobar", null));
// Deprecated: Passing null to parameter #2 ($needle) of type string
// is deprecated
?>

暗黙の float から int への変換

精度を損なうことになる float から int への暗黙の変換は、 推奨されなくなりました。 これは配列のキーに float を使った場合や、 型の自動変換 (coerciveモード) 時に int 型を宣言した場合や、 int に対して演算子を適用する場合に影響します。

<?php
$a = [];
$a[15.5]; // 推奨されません。0.5 がキーの値から失われるからです
$a[15.0]; // 15.0 == 15 なので OK
?>

トレイトの static な要素をコールする

トレイトにある static メソッドや、 static プロパティに直接アクセスすることは、 推奨されなくなりました。 これらは、トレイトを使っているクラスからのみアクセスすべきものです。

__sleep() から配列でない値を返す

配列でない値を __sleep() から返すと、警告が発生するようになりました。

void の関数からリファレンスを返す

<?php
function &test(): void {}
?>
上記のような関数は矛盾しているため、 呼び出された時に Only variable references should be returned by reference という E_NOTICE が既に発生するようになっています。

false な変数を自動的に復活させる挙動(Autovivification)

Autovivification とは、 値を追加しようとする際に配列を自動で生成する処理のことです。 スカラー型の値からこのような処理を行うことは禁止されていますが、 false だけは例外でした。 このバージョンから、この例外も推奨されなくなります。

<?php
$arr = false;
$arr[] = 2; // 推奨されません
?>

注意:

null や 未定義値から、 自動的に配列を生成する処理は未だ許可されています:

<?php
// 未定義値から配列を生成
$arr[] = 'some value';
$arr['doesNotExist'][] = 2;
// null から配列を生成
$arr = null;
$arr[] = 2;
?>

ctype 関数

文字列でない引数の検証

ctype関数 に文字列でない引数を渡すことは、 推奨されなくなりました。 将来のバージョンでは、引数は ASCII コードポイントではなく、 文字列として解釈されるようになります。 ユーザが意図する振る舞いによっては、 引数を文字列にキャストするか、 chr() を明示的にコールすべきです。 全ての ctype_*() 関数が影響を受けます。

日付・時刻 関数

date_sunrise() と date_sunset() は、推奨されなくなりました。 date_sun_info() を使って下さい。

strptime() 関数は、 推奨されなくなりました。 (ロケールに依存しないパースを行う場合) date_parse_from_format() または (ロケールに依存するパースを行う場合) IntlDateFormatter::parse() を代わりに使って下さい。

strftime() と gmstrftime() は、推奨されなくなりました。 (ロケールに依存しないフォーマットを行う場合) date() または (ロケールに依存するフォーマットを行う場合) IntlDateFormatter::format() を代わりに使って下さい。

Filter

FILTER_SANITIZE_STRING と FILTER_SANITIZE_STRIPPED フィルタは、推奨されなくなりました。

INI ディレクティブ filter.default は、推奨されなくなりました。

GD

imagepolygon(), imageopenpolygon(), imagefilledpolygon() の num_points 引数は、 推奨されなくなりました。

Hash

mhash(),
mhash_keygen_s2k(),
mhash_count(),
mhash_get_block_size(),
mhash_get_hash_name()
は、推奨されなくなりました。
hash_*() 関数を代わりに使って下さい。

IMAP

定数 NIL は、推奨されなくなりました。 0 を代わりに使って下さい。

国際化関数(Intl)

IntlCalendar::roll() に bool 引数を渡してコールすることは、 推奨されなくなりました。 true と false の代わりに、 1 と -1 をそれぞれ渡すようにして下さい。

マルチバイト文字列

mb_check_encoding() 関数を引数を渡さずにコールすることは、推奨されなくなりました。

MySQLi

mysqli_driver::$driver_version プロパティは、推奨されなくなりました。 このプロパティは意味がなく、時代遅れになっています。 PHP_VERSION_ID を代わりに使って下さい。

mysqli 引数を渡して、 mysqli::get_client_info() や mysqli_get_client_info() をコールすることは、推奨されなくなりました。 クライアントライブラリのバージョン情報を取得するには、 mysqli_get_client_info() を引数なしでコールするようにして下さい。

mysqli::init() メソッドは、 推奨されなくなりました。 parent::init() のコールを parent::__construct() に置き換えるようにして下さい。

OCI8

INI ディレクティブ oci8.old_oci_close_semantics は、推奨されなくなりました。

ODBC

odbc_result_all() 関数は推奨されなくなりました。

PDO

フェッチモードの定数 PDO::FETCH_SERIALIZE は、推奨されなくなりました。

PgSQL

全ての pgsql_*() 関数に対して、接続リソースを渡さないことは推奨されなくなりました。

SOAP

SoapClient::__construct() の ssl_method オプションは推奨されなくなりました。 SSL コンテキストオプションを使うのが望ましいです。

標準ライブラリ

object に対して、 key(), current(), next(), prev(), reset(), end() を呼び出すことは推奨されなくなりました。 get_mangled_object_vars() を使って 最初に object を配列に変換するか、 ArrayIterator のような Iterator を実装したクラスのメソッドを使ってください。

INI ディレクティブ auto_detect_line_endings は、推奨されなくなりました。 必要な場合は、 "\r" を手動で扱うようにして下さい。

定数 FILE_BINARY と FILE_TEXT は推奨されなくなりました。 これらの定数は、使われたことがありませんでした。


その他の変更

SAPI モジュールへの変更

CLI

readline 拡張モジュール が組み込まれていないのに、 -a オプションを使った場合、 エラーが発生するようになりました。 以前のバージョンでは、 readline が組み込まれていない時に -a オプションを使うと、 php コマンドを引数なしでコールしたのと同じ振る舞いをするのに、 "Interactive mode enabled" というメッセージを追加で出力していました。 この場合のモードは、インタラクティブでは ありませんでした。

PHPDBG

phpdbg のリモート関連の機能が削除されました。

変更された関数

PHP コア

foreach、 var_dump()、 serialize()、 オブジェクトの比較時などで用いられるプロパティの順序が変更されました。 プロパティは宣言や継承に応じて、自然順に並ぶようになりました。 親クラスで宣言されたプロパティは、 子クラスのプロパティの前に並びます。

この順序は、 構造体 zend_object 内部のレイアウトと一致しており、 default_properties_table[] と properties_info_table[] でも同様の順序が用いられています。 以前のバージョンでは、 プロパティの順序がドキュメント化されておらず、 クラスの継承の実装の詳細に依存していました。

Filter

FILTER_VALIDATE_INT フィルタの FILTER_FLAG_ALLOW_OCTAL フラグは、 8進数のプレフィックス ("0o"/"0O") が先頭についた8進文字列を受け入れるようになりました。

GMP

全ての GMP 関数が、 8進数のプレフィックス ("0o"/"0O") が先頭についた8進文字列を受け入れるようになりました。

PDO ODBC

PDO::getAttribute() に PDO::ATTR_SERVER_INFO や PDO::ATTR_SERVER_VERSION を指定した場合でも、 値を返すようになりました。 以前のバージョンでは、 PDOException をスローしていました。

リフレクション

ReflectionProperty::setAccessible() と ReflectionMethod::setAccessible() は、もはや意味をなさなくなりました。 プロパティとメソッドは、 常にリフレクション経由でアクセス可能と見なされるようになっています。

標準ライブラリ

syslog() 関数は、バイナリセーフになりました。

拡張モジュールへのその他の変更

GD

imagewebp() 関数の quality 引数に IMG_WEBP_LOSSLESS を指定することで、 ロスレスエンコードが行えるようになりました。

システムが使っている libgd が WebP のロスレスエンコーディングをサポートしている場合にのみ、 この定数は定義されます。

MySQLi

libmysqlclient とリンクした場合に、 mysqli_stmt::next_result() と mysqli::fetch_all() が使えるようになりました。

OpenSSL

  • OpenSSL 拡張モジュール は、OpenSSL 1.0.2 以降が必須になりました。

  • OpenSSL 3.0 がサポートされるようになりました。 多くの暗号が(レガシーなプロバイダの一部となっているため) デフォルトで有効ではなくなり、 引数の検証 (たとえば鍵の最小サイズ) が厳しくなっています。

Phar

  • SHA256 が、シグネチャのデフォルトとして使われるようになりました。

  • OpenSSL_SHA256 と OpenSSL_SHA512 シグネチャのサポートが追加されました。

SNMP

  • セキュリティプロトコルのために、 SHA256 と SHA512 のサポートが追加されました。

標準ライブラリ

configure オプション --with-password-argon2 は、 libargon2 を検知するのに pkg-config を使うようになっています。 そのため、libargon2 のインストール先を指定するには、 PKG_CONFIG_PATH を使うべきです。

INI ファイルの扱いの変更

  • INI ディレクティブ log_errors_max_len は削除されました。 PHP 8.0.0 以降、この設定は意味をなさなくなっていました。

  • クォートされた文字列の先頭にドル記号がある場合、 そのドル記号はエスケープされるようになりました。 つまり、 "\${" は、 ${ という文字列として解釈されます。

  • ダブルクォートで囲まれた文字列中のバックスラッシュは、 エスケープ文字としてより一貫した形で扱われるようになりました。 以前のバージョンでは、 "foo\\" の後に改行文字以外の文字が続いた場合、 文字列の終端とは見なされませんでした。 PHP 8.1.0 以降では、foo\ という文字列として解釈されるようになります。 例外として、"foo\" の後に改行文字が続いた場合は、 foo\ という文字列として解釈されます。 文字列が終端していないとは見なされません。 但し、"C:\foo\" のような、 Windows のファイルパスを使う場合には例外が存在します。


PHP 7.4.x から PHP 8.0.x への移行

目次

  • 新機能
  • 下位互換性のない変更点
  • 推奨されなくなる機能
  • その他の変更

この新しいメジャーバージョンには、たくさんの 新機能 と 互換性のない変更 がいくつかあります。 実運用環境の PHP をこのバージョンにあげる前に、これらの変更を必ずテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.0.x, 7.1.x, 7.2.x, 7.3.x, 7.4.x.


新機能

PHP コア

名前付き引数

名前付き引数 のサポートが追加されました。

アトリビュート

アトリビュート のサポートが追加されました。

コンストラクタのプロパティ昇格機能

コンストラクタの引数をプロパティへ昇格させる機能 が追加されました。

union 型

union 型 のサポートが追加されました。

match 式

match 式 のサポートが追加されました。

nullsafe 演算子

nullsafe 演算子 (?->) のサポートが追加されました。

その他の新機能

  • WeakMap クラスが追加されました。

  • ValueError クラスが追加されました。

  • 任意の数の関数の引数が、可変長引数に置き換えられるようになりました。 但し、型に互換性がある場合に限ります。 たとえば、次のようなコードが書けるようになります:

    <?php
    class A {
    public function     method(int $many, string $parameters, $here) {}
    }
    class     B extends A {
    public function     method(...$everything) {}
    }
    ?>

  • 以下のようにして、static ("遅延静的束縛"における) 型が、 戻り値の型として使えるようになりました:

    <?php
    class Test {
    public function     create(): static {
    return new static();
    }
    }
    ?>

  • オブジェクトのクラス名を $object::class と書くことで取得できるようになりました。 この結果は、get_class($object) と同じです。

  • new と instanceof が、 new (expression)(...$args) や $obj instanceof (expression) という形で、任意の式と一緒に使えるようになりました。

  • 変数の文法に一貫性を持たせるため、いくつかの修正が適用されます。 たとえば、Foo::BAR::$baz のような書き方が許可されるようになりました。

  • インターフェイス Stringable が追加されました。 クラスが __toString() メソッドを定義していた場合、 このインターフェイスが自動的に実装されます。

  • トレイトで、private な抽象メソッドを定義できるようになりました。 このメソッドは、トレイトを使うクラスで実装されなければなりません。

  • throw が式として使えるようになりました。 これによって、以下のような書き方ができるようになります:

    <?php
    $fn     = fn() => throw new Exception('Exception in arrow function');
    $user = $session->user ?? throw new Exception('Must have user');

  • 引数のリストに付ける最後のカンマも、オプションで許可されるようになりました。

    <?php
    function functionWithLongSignature(
    Type1 $parameter1,
    Type2 $parameter2, // <-- このカンマが許可されるようになりました
    ) {
    }

  • 変数に保存せずに、 例外をキャッチするために、catch (Exception) というコードが書けるようになりました。

  • mixed 型のサポートが追加されました。

  • 親クラスで宣言された private メソッドは、 子クラスのメソッドに対して継承ルールを強制しなくなりました( private final と宣言されたコンストラクタは例外です)。 次の例は、どういった制限がなくなるのかを示しています:

    <?php
    class ParentClass {
    private function     method1() {}
    private function     method2() {}
    private static function     method3() {}
    // "final" が意味をなさなくなったので、警告が発生します:
    private final function method4() {}
    }
    class     ChildClass extends ParentClass {
    // 親クラスの private メソッドとアクセス権の修飾子が異なっている
    // 以下の全ての宣言が許されるようになりました。
    public abstract function method1() {}
    public static function     method2() {}
    public function     method3() {}
    public function     method4() {}
    }
    ?>

  • (int) $resource と同じ値を返す get_resource_id() 関数が追加されました。 よりわかりやすいAPIで、同じ機能を提供するものです。

  • InternalIterator が追加されました。

日付と時刻

  • DateTime::createFromInterface() と DateTimeImmutable::createFromInterface() が追加されました。

  • DateTime のフォーマット指定子 p が追加されました。 これは P と同じですが、 UTC の +00:00 ではなく、 Z を返します。

DOM

新しいDOMの走査と管理を行う API を持つ DOMParentNode と DOMChildNode が追加されました。

フィルタ

FILTER_VALIDATE_BOOLEAN のエイリアスとして、 FILTER_VALIDATE_BOOL が追加されました。 新しい名前のほうが望ましいです。なぜなら、 正規化された型の名前を使っているからです。

Enchant

enchant_dict_add(), enchant_dict_is_added(), LIBENCHANT_VERSION が追加されました。

FPM

新しいオプション pm.status_listen が追加されました。 これによって、異なるエンドポイント(例: ポートやUDSファイル)から、 ステータスを取得することが出来るようになります。 実行時間がかかっているリクエストを処理しているために、全ての子プロセスがビジーである場合、 ステータスを取得するのに役立ちます。

Hash

HashContext オブジェクトが、シリアライズ出来るようになりました。

国際化関数

定数 IntlDateFormatter::RELATIVE_FULL,
IntlDateFormatter::RELATIVE_LONG,
IntlDateFormatter::RELATIVE_MEDIUM,
IntlDateFormatter::RELATIVE_SHORT が追加されました。

LDAP

検索結果に含まれる参照メッセージの数を返す ldap_count_references() が追加されました。

OPcache

opcache.record_warnings INI ディレクティブが有効になっている場合、 OPcache はコンパイル時の警告を記録し、次に include されたときにそれを繰り返します。 これは、たとえキャッシュから情報を得た場合でも同じです。

OpenSSL

暗号化メッセージ構文(CMS) (» RFC 5652) のサポートが追加されました。 これは、暗号化、復号化、署名、検証と読み込みの関数が含まれます。 API は PKCS #7 の関数と似ていますが、新しいエンコーディングの定数が追加されています: OPENSSL_ENCODING_DER, OPENSSL_ENCODING_SMIME OPENSSL_ENCODING_PEM です。

  • 証明書を使ってファイル中のメッセージを暗号化し、 結果を指定されたファイルに出力する openssl_cms_encrypt() が追加されました。
  • ファイル中の S/MIME メッセージを復号化し、 結果を指定されたファイルに出力する openssl_cms_decrypt() が追加されました。
  • CMSファイルを PEM 証明書の配列にエクスポートする openssl_cms_read() が追加されました。
  • 証明書と鍵を使ってファイル中のMIMEメッセージに署名し、 結果を指定されたファイルに出力する openssl_cms_sign() が追加されました。
  • データブロックが無傷なことや、 署名した人がその人であることを検証し、 署名した人の証明書を返す openssl_cms_verify() が追加されました。

正規表現 (Perl互換)

直近で発生した PCRE に関するエラーを人間が読みやすいメッセージとして返す preg_last_error_msg() が追加されました。 これは、整数の enum を返していた preg_last_error() を補完するものです。

リフレクション

  • 以下のメソッドは、内部関数の引数のデフォルト値に関する情報を返すようになりました:

    • ReflectionParameter::isDefaultValueAvailable()
    • ReflectionParameter::getDefaultValue()
    • ReflectionParameter::isDefaultValueConstant()
    • ReflectionParameter::getDefaultValueConstantName()

SQLite3

データベース上で認証する用途に使う、 ユーザー空間のコールバックを設定する SQLite3::setAuthorizer() と、 それに対応するクラス定数が追加されました。

標準ライブラリ

  • 文字列に haystack が含まれているかどうかを調べる str_contains() 関数が追加されました。

    文字列が needle で始まるかを調べる str_starts_with() 関数が追加されました。

    文字列が needle で終わるかを調べる str_ends_with() 関数が追加されました。

  • IEEE 754 のセマンティクスに沿って浮動小数点数の割り算を行う fdiv() 関数が追加されました。 ゼロ除算は、well-defined とみなされ、 Inf, -Inf, NaN のいずれかを返します。

  • エラーメッセージで使うのに便利な型を返す get_debug_type() 関数が追加されました。 gettype() と違うのは、 この関数は正規化された型の名前を使い、オブジェクトのときはクラス名を返し、 リソースの場合はリソースのタイプを示すことです。

  • printf() 関数とその仲間の関数は、 フォーマット指定子 %h と %H をサポートしました。 これらは %g および %G と同じですが、 10進数の区切り文字を LC_NUMERIC ロケールによって決めるのではなく、 常に "." を使います。

  • printf() 関数とその仲間の関数は、 精度または広さを指定する用途のために "*" をサポートしました。 この場合、精度/広さは printf の引数として渡します。 精度として -1 を %g, %G, %h, %H に指定することも出来ます。 たとえば、次のコードで、PHP のデフォルトの浮動小数点のフォーマットを再現することができます:

    <?php
    printf    ("%.*H", (int) ini_get("precision"), $float);
    printf("%.*H", (int) ini_get("serialize_precision"), $float);
    ?>

  • proc_open() に、疑似端末(PTY) ディスクリプタのサポートが追加されました。 以下のコードは、 stdin, stdout, stderr を同じPTYにアタッチします:

    <?php
    $proc     = proc_open($command, [['pty'], ['pty'], ['pty']], $pipes);
    ?>

  • proc_open() 関数は、 ソケットペアのディスクリプタをサポートするようになりました。 以下のコードは、異なるソケットペアを stdin, stdout, stderr にアタッチします:

    <?php
    $proc     = proc_open($command, [['socket'], ['socket'], ['socket']], $pipes);
    ?>

    Windows では、パイプと異なり、ソケットは ブロッキングI/O の問題の影響を受けません。 しかし、全てのプログラムが標準入出力のソケットで正しく動くとは限りません。

  • ソート関数が安定ソートになりました。 これは、比較して等しいと判定された要素は、もともとの順序を維持するということです。

  • array_diff(), array_intersect() や、 そのバリエーションの関数は、単一の配列を引数に取れるようになりました。 これによって、以下のような使い方が出来るようになるということです:

    <?php
    // $excludes が空でも問題ありません:
    array_diff($array, ...$excludes);
    // $arrays が 単一の配列だけを含んでいても問題ありません:
    array_intersect(...$arrays);
    ?>

  • ob_implicit_flush() 関数の flag 引数が、int ではなく bool を受け取るように変更されました。

Tokenizer

PhpToken クラスは、 オブジェクトベースのインターフェイスを tokenizer に追加します。 このクラスは、統一された、人間工学に基づいた表現を提供しながら、 メモリ効率がよく、高速になっています。

Zip

  • Zip 拡張モジュールが、1.19.1 に更新されました。

  • エントリの変更時間を設定するための ZipArchive::setMtimeName(), ZipArchive::setMtimeIndex() が追加されました。

  • アーカイブがクローズされている間に行われた更新情報を提供する ZipArchive::registerProgressCallback() が追加されました。

  • アーカイブがクローズされている間にキャンセルを許可する ZipArchive::registerCancelCallback() が追加されました。

  • エントリの内容を置換する ZipArchive::replaceFile() が追加されました。

  • オプションの圧縮機能がサポートされているかをチェックする ZipArchive::isCompressionMethodSupported() が追加されました。

  • オプションの暗号化機能がサポートされているかをチェックする ZipArchive::isEncryptionMethodSupported() が追加されました。

  • 最後に追加されたエントリのインデックスの値を取得するために、 ZipArchive::lastId が追加されました。

  • ZipArchive::status や
ZipArchive::statusSys プロパティ、
または ZipArchive::getStatusString() メソッドを使って、
アーカイブがクローズされた後でもエラーをチェックできるようになりました。

  • ZipArchive::addGlob() と ZipArchive::addPattern() メソッドの 'remove_path' オプションは、 ('add_path' オプションと一貫性を保つため) 任意の文字列のプレフィックスとして扱われるようになりました。 これより前のバージョンでは、デイレクトリ名として扱われていました。

  • オプションの 圧縮/伸長 機能が phpinfo でも一覧できるようになりました。


下位互換性のない変更点

PHP コア

文字列と数値の比較

(厳密でないやり方で)数値と非数値文字列を比較する場合、 数値を文字列にキャストし、文字列と比較するようになりました。 数値と数値形式の文字列の比較は、以前と同じ振る舞いをします。 注意すべきなのは、これによって、 0 == "not-a-number" が false と見なされるようになったことです。

比較 | 変更前 | 変更後
0 == "0" | true | true
0 == "0.0" | true | true
0 == "foo" | true | false
0 == "" | true | false
42 == " 42" | true | true
42 == "42foo" | true | false

その他の下位互換性のない変更

  • match が予約語になりました。

  • mixed が予約語になりました。 よって、クラスやインターフェイス、 トレイトの名前として使えなくなっています。 名前空間の中であっても同様です。

  • アサーションに失敗すると、デフォルトで例外をスローするようになりました。 古い振る舞いを望む場合、php.ini で assert.exception=0 と設定できます。

  • クラス名と同じ名前のメソッドは、コンストラクタと解釈されなくなりました。 __construct() メソッドを代わりに使って下さい。

  • static でないメソッドを、staticメソッドとしてコールできる機能が削除されました。 static でないメソッドをクラス名を使ってチェックした場合、 is_callable() は失敗します。 (オブジェクトのインスタンスを使ってチェックしなければいけません)

  • (real) と (unset) キャストが削除されました。

  • track_errors ini ディレクティブは削除されました。 つまり、php_errormsg が利用できなくなったということです。 代わりに error_get_last() 関数が使えます。

  • 大文字小文字を区別しない定数を定義できる機能が削除されました。 define() 関数の第3引数はもはや true ではありません。

  • __autoload() 関数を使ってオートローダーを指定する機能は削除されました。 代わりに spl_autoload_register() を使うべきです。

  • set_error_handler() 関数で設定されるカスタムエラーハンドラには、 errcontext 引数は渡されなくなりました。

  • create_function() 関数は削除されました。 無名関数が代わりに使えます。

  • each() 関数は削除されました。 代わりに foreach や ArrayIterator を使うべきです。

  • Closure::fromCallable() や ReflectionMethod::getClosure() を使って メソッドから生成されたクロージャーから this の束縛を解除できる機能は削除されました。

  • this を使っている適切なクロージャーから、 this の束縛を解除する機能も削除されています。

  • オブジェクトに対して array_key_exists() 関数を使える機能は削除されました。 isset() または property_exists() を代わりに使えます。

  • array_key_exists() 関数の引数 key の型に関する振る舞いが、 isset() 関数や配列アクセスの場合と一貫したものになりました。 全てのキーの型は通常の強制が行われ、配列やオブジェクトのキーは TypeError がスローされるようになりました。

  • はじめの数値のキーとして n を持つ配列は、 たとえ n が負の値であっても、 次の暗黙のキーは n+1 を使うようになります。

  • デフォルトの error_reporting のレベルは E_ALL になりました。 これより前のバージョンでは、 E_ALL から E_NOTICE と E_DEPRECATED が除かれていました。

  • display_startup_errors は、 デフォルトで有効になりました。

  • 親クラスがないクラスの内部で parent を使うと、 致命的なコンパイルエラーが発生するようになりました。

  • @ 演算子は、致命的なエラー (E_ERROR, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR, E_RECOVERABLE_ERROR, E_PARSE) を隠さなくなりました。 @ を使う時に、 error_reporting が 0 であることを期待しているエラーハンドラは、 代わりにマスクチェックを調整すべきです:

    <?php
    // こういうエラーハンドラは
    function my_error_handler($err_no, $err_msg, $filename, $linenum) {
    if (    error_reporting() == 0) {
    return     false;
    }
    // ...
    }

    // 以下に置き換えましょう
    function my_error_handler($err_no, $err_msg, $filename, $linenum) {
    if (!(    error_reporting() & $err_no)) {
    return     false;
    }
    // ...
    }
    ?>

    さらに、実運用環境で表示されていなかった、 情報のリークに繋がるエラーメッセージにも注意を払うべきです。 エラーのロギングと併せて、 display_errors=Off となっていることを確認するようにして下さい。

  • #[ は、コメントの開始として解釈されなくなりました。 この文法は、アトリビュート として使われるようになっているからです。

  • 非互換なメソッドのシグネチャによる継承エラー(リスコフの置換原則違反)については、 常に致命的なエラーが生成されるようになりました。 これより前のバージョンでは、警告が生成される場合がありました。

  • ビットシフトや加算、減算に対する連結演算子の優先順位が変更されました。

    <?php
    echo "Sum: " . $a + $b;
    // 上記は、以前のバージョンでは以下のように解釈されていました:
    echo ("Sum: " . $a) + $b;
    // PHP 8.0.0 からは、以下のように解釈されます:
    echo "Sum:" . ($a + $b);
    ?>

  • 実行時に null に解決されるデフォルト値を持つ引数は、 引数の型を暗黙のうちに nullable とマークすることはなくなりました。 明示的に nullable と宣言するか、 明示的にデフォルト値を null と宣言しなければなりません。

    <?php
    // 以下のようなコードは
    function test(int $arg = CONST_RESOLVING_TO_NULL) {}
    // このように置き換えるか
    function test(?int $arg = CONST_RESOLVING_TO_NULL) {}
    // こう書きましょう
    function test(int $arg = null) {}
    ?>

  • たくさんの警告が Error 例外に変換されるようになりました:

    • オブジェクトでない値にプロパティを書き込もうとした場合。 これより前のバージョンでは、 null については stdClass オブジェクトが暗黙のうちに作られ、 空文字列については false となっていました。
    • PHP_INT_MAX キーが既に使われている配列に対して、 要素を追加しようとした場合。
    • 不正な型(配列やオブジェクト) を配列のキーや文字列のオフセットとして使おうとした場合。
    • スカラー値に配列のインデックスを書き込もうとした場合
    • 配列やTraversable でない値をアンパックしようとした場合
    • 未定義の、非修飾の定数にアクセスしようとした場合。 これより前のバージョンでは、 非修飾の定数にアクセスしようとすると、警告が発生し、 文字列として解釈されていました。
    • 可変長引数でない組み込み関数に、間違った数の引数を渡した場合、 ArgumentCountError がスローされるようになりました。
    • 無効な countable 型を count() に渡した場合、 TypeError がスローされるようになりました。

    多くの notice が警告に変換されるようになりました:

    • 未定義の変数を読み取ろうとした場合
    • 未定義のプロパティを読み取ろうとした場合
    • 未定義の配列のキーを読み取ろうとした場合
    • オブジェクトでない値のプロパティを読み取ろうとした場合
    • 配列でない値のインデックスにアクセスしようとした場合
    • 配列を文字列に変換しようとした場合
    • リソースを配列のキーとして使おうとした場合
    • null や bool 値や float の値を文字列オフセットとして使おうとした場合
    • 境界を超えて文字列のオフセットを読み取ろうとした場合
    • 文字列のオフセットに空文字列を割り当てようとした場合

  • 文字列のオフセットに複数バイトを割り当てようとすると、警告が発生するようになりました。

  • ソースファイル中に(文字列の範囲外のNUL バイトのような) 想定外の文字が含まれていた場合、 コンパイル時に警告を出す代わりに、 ParseError がスローされるようになりました。

  • 例外がキャッチされなかった場合、 "クリーンなシャットダウン" が行われます。 これは、例外がキャッチされなかった後、 デストラクタが呼ばれるということです。

  • コンパイル時の致命的なエラー "Only variables can be passed by reference" は、 実行時まで遅延され、 "Argument cannot be passed by reference" という Error 例外に変換されるようになりました。

  • "Only variables should be passed by reference" という警告は、 "Argument cannot be passed by reference" という例外に変換されるようになりました。

  • 無名クラスのために生成される名前が変更されました。 最初の親クラスやインターフェイスの名前が含まれるようになっています:

    <?php
    new class extends ParentClass {};
    // -> ParentClass@anonymous
    new class implements FirstInterface, SecondInterface {};
    // -> FirstInterface@anonymous
    new class {};
    // -> class@anonymous
    ?>

    上で示した名前の後に、NULバイトやユニークなサフィックスが続きます。

  • トレイトのエイリアス調整において、 クラス名を指定していないメソッド参照は、 曖昧でないことが必須になりました:

    <?php
    class X {
    use     T1, T2 {
    func as otherFunc;
    }
    function     func() {}
    }
    ?>

    T1::func() と T2::func() が両方存在している場合、 PHP 8.0.0 より前のバージョンでは、 このコードは黙って動作し、func は T1::func を参照するものと想定されていました。 PHP 8.0.0 からは、このコードは致命的なエラーが発生します。 T1::func または T2::func を明示的に書く必要があります。

  • トレイトで定義される抽象メソッドのシグネチャは それを実装するクラスのメソッド側で、 一致しているかがチェックされるようになりました:

    <?php
    trait MyTrait {
    abstract private function     neededByTrait(): string;
    }

    class     MyClass {
    use     MyTrait;

    // エラー。戻り値の型が一致しません。
    private function neededByTrait(): int { return 42; }
    }
    ?>

  • 無効にされている関数は、存在しない関数であるかのように扱われるようになりました。 無効にされている関数を呼び出しても unknown と報告されますし、 無効にされている関数を再定義することも可能になっています。

  • data:// ストリームラッパーは書き込み可能ではなくなりました。 これは、ドキュメント化されている振る舞いに一致します。

  • 算術演算子とビット演算子 +, -, *, /, **, %, <<, >>, &, |, ^, ~, ++, -- は、オペランドのひとつが配列だったり、 リソース だったり、オーバーロードされていない object だったりした場合に、 一貫して TypeError をスローするようになりました。 これに対する唯一の例外は、配列と配列を + でマージする操作で、 これはまだサポートされています。

  • float 型から文字列型へのキャストは、 ロケールに依存しないように常に振る舞うようになります。

    <?php
    setlocale    (LC_ALL, "de_DE");
    $f = 3.14;
    echo     $f, "\n";
    // PHP 8.0.0 より前のバージョン: 3,14
    // PHP 8.0.0 以降: 3.14
    ?>

    数値のフォーマットをカスタマイズする方法については、 printf(), number_format() 関数 および NumberFormatter() メソッドを参照ください。

  • 推奨されなくなっていた、 オフセットを指定してアクセスするための波括弧のサポートが削除されました。

    <?php
    // 以下ではなく:
    $array{0};
    $array{"key"};
    // このように書いて下さい:
    $array[0];
    $array["key"];
    ?>

  • private メソッドに final 修正子を指定した場合、 そのメソッドがコンストラクタでない限り、警告が発生するようになります。

  • オブジェクトのコンストラクタで exit() が呼び出された場合、 オブジェクトのデストラクタはコールされなくなりました。 これは、コンストラクタが例外をスローしたときの振る舞いと一致します。

  • 名前空間に含まれる名前には、 ホワイトスペースを含めることができなくなりました。 つまり、Foo\Bar は名前空間の名前として認識されますが Foo \ Bar は認識されなくなったということです。 逆に、予約語のキーワードは名前空間の一部として許されるようになりました。 これによって、コードの解釈が変わるかもしれません。 new\x は constant('new\x') と同じですが、 new \x() とは異なります。

  • 三項演算子をネストする場合、明示的に括弧が必要になりました。

  • debug_backtrace() と Exception::getTrace() メソッド は、引数にリファレンスを取らなくなりました。 これにより、バックトレースを通じて、関数の引数を変更できなくなります。

  • 数値形式の文字列の扱いが、より直感的で間違いにくいものに変更されました。 ホワイトスペースが前に付いている場合の扱いと一貫性を持たせるため、 数値形式の文字列の後にホワイトスペースを付けることが許されるようになりました。 これがもっとも影響するのは以下です:

    • is_numeric() 関数
    • 文字列同士の比較
    • 型宣言
    • インクリメントとデクリメント演算

    "数値が始めに来る文字列" の概念は殆どなくなっています; このケースは、移行を容易にするために存在しています。 "A non well-formed numeric value encountered" という E_NOTICE が発生する文字列 は、"A non-numeric value encountered" という E_WARNING が発生するようになっています。 そして、"A non-numeric value encountered" という E_WARNING が発生していた全ての文字列は、 TypeError が発生するようになりました。 これが最も影響するのは、以下の場合です:

    • 算術演算
    • ビット演算

    この E_WARNING から TypeError への変更は、 不正な文字列オフセットの場合に発生する "Illegal string offset 'string'" という E_WARNING にも影響します。 文字列から int/float に明示的にキャストする場合の振る舞いは変更されていません

  • マジックメソッドは引数と戻り値の型を持ち、 宣言された場合はチェックが行われるようになりました。 シグネチャは次の一覧と一致させるべきです:

    • __call(string $name, array $arguments): mixed
    • __callStatic(string $name, array $arguments): mixed
    • __clone(): void
    • __debugInfo(): ?array
    • __get(string $name): mixed
    • __invoke(mixed $arguments): mixed
    • __isset(string $name): bool
    • __serialize(): array
    • __set(string $name, mixed $value): void
    • __set_state(array $properties): object
    • __sleep(): array
    • __unserialize(array $data): void
    • __unset(string $name): void
    • __wakeup(): void

  • call_user_func_array() 関数に渡される 配列のキーは、引数名として解釈されるようになりました。 これより前のバージョンでは、静かに無視されていました。

  • 名前空間の内部で assert() と呼ばれる関数を宣言する ことは許されなくなり、 E_COMPILE_ERROR が発生するようになりました。 assert() 関数は PHP エンジンによって特別扱いを受けることになっているので、 名前空間の内部で同じ名前が定義されていると、 動作が一貫しなくなる原因になるからです。

リソースからオブジェクトへの移行

いくつかの リソース が、object に移行しました。 is_resource() 関数を使って戻り値をチェックしているコードは、 false を返すことをチェックするコードに置き換えるべきです。

  • curl_init() 関数は リソース ではなく、CurlHandle オブジェクトを返すようになりました。 curl_close() 関数はもはや意味をなしません。 CurlHandle インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • curl_multi_init() 関数は リソース ではなく、CurlMultiHandle オブジェクトを返すようになりました。 curl_multi_close() 関数はもはや意味をなしません。 CurlMultiHandle インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • curl_share_init() 関数は リソース ではなく、CurlShareHandle オブジェクトを返すようになりました。 curl_share_close() 関数はもはや意味をなしません。 CurlShareHandle インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • enchant_broker_init() 関数は リソース ではなく、EnchantBroker オブジェクトを返すようになりました。

  • enchant_broker_request_dict() と enchant_broker_request_pwl_dict() 関数は リソース ではなく、EnchantDictionary オブジェクトを返すようになりました。

  • GD 拡張モジュールは 画像の基本的なデータ構造として リソース ではなく、GdImage オブジェクトを使うようになりました。 imagedestroy() 関数はもはや意味をなしません。 GdImage インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • openssl_x509_read() と openssl_csr_sign() 関数は リソース ではなく、OpenSSLCertificate オブジェクトを返すようになりました。 openssl_x509_free() 関数は非推奨となり、 もはや意味をなしません。 OpenSSLCertificate インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • openssl_csr_new() 関数は リソース ではなく、OpenSSLCertificateSigningRequest オブジェクトを返すようになりました。

  • openssl_pkey_new() 関数は リソース ではなく、OpenSSLAsymmetricKey オブジェクトを返すようになりました。 openssl_pkey_free() 関数は非推奨となり、 もはや意味をなしません。 OpenSSLAsymmetricKey インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • shmop_open() 関数は リソース ではなく、Shmop オブジェクトを返すようになりました。 shmop_close() 関数は非推奨となり、 もはや意味をなしません。 Shmop インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • socket_create(), socket_create_listen(), socket_accept(), socket_import_stream(), socket_addrinfo_connect(), socket_addrinfo_bind(), socket_wsaprotocol_info_import() 関数は リソース ではなく、Socket オブジェクトを返すようになりました。 socket_addrinfo_lookup() 関数は リソース ではなく、AddressInfo オブジェクトを返すようになりました。

  • msg_get_queue() 関数は リソース ではなく、SysvMessageQueue オブジェクトを返すようになりました。

  • sem_get() 関数は リソース ではなく、SysvSemaphore オブジェクトを返すようになりました。

  • shm_attach() 関数は リソース ではなく、SysvSharedMemory オブジェクトを返すようになりました。

  • xml_parser_create() と xml_parser_create_ns() 関数は リソース ではなく、XMLParser オブジェクトを返すようになりました。 xml_parser_free() 関数はもはや意味をなしません。 XMLParser インスタンスは、 参照されなくなった場合に、自動的に破棄されます。

  • XMLWriter 関数 は リソース ではなく、XMLWriter オブジェクトを受け入れ、返すようになりました。

  • inflate_init() 関数は リソース ではなく、InflateContext オブジェクトを返すようになりました。

  • deflate_init() 関数は リソース ではなく、DeflateContext オブジェクトを返すようになりました。

COM および .Net (Windows)

タイプライブラリ から 大文字小文字を区別せずに定数をインポートする機能は削除されました。 com_load_typelib() 関数の第二引数は もはや false ではありません。 com.autoregister_casesensitive はもはや無効ではなくなりました。 つまり、com.typelib_file の #case_insensitive マーカーは無視されます。

CURL

CURLOPT_POSTFIELDS は、 オブジェクトを配列として受け入れなくなりました。 オブジェクトを配列として解釈させるためには、 明示的に (array) キャストを行って下さい。 配列を受け入れる他のオプションにも、同じことが当てはまります。

日付と時刻

mktime() と gmmktime() 関数は 少なくともひとつ引数が必要になりました。 現在のタイムスタンプを取得する用途には time() 関数が使えます。

DOM

DOM 拡張モジュールで実装されておらず、振る舞いも持たず、 テストデータもないクラスが削除されました。 これらのクラスは、最新のDOM標準からも削除されています:

  • DOMNameList
  • DomImplementationList
  • DOMConfiguration
  • DomError
  • DomErrorHandler
  • DOMImplementationSource
  • DOMLocator
  • DOMUserDataHandler
  • DOMTypeInfo
  • DOMStringExtend

DOM 拡張モジュールで実装されておらず、 振る舞いも持たない以下のメソッドが削除されました:

  • DOMNamedNodeMap::setNamedItem()
  • DOMNamedNodeMap::removeNamedItem()
  • DOMNamedNodeMap::setNamedItemNS()
  • DOMNamedNodeMap::removeNamedItemNS()
  • DOMText::replaceWholeText()
  • DOMNode::compareDocumentPosition()
  • DOMNode::isEqualNode()
  • DOMNode::getFeature()
  • DOMNode::setUserData()
  • DOMNode::getUserData()
  • DOMDocument::renameNode()

Enchant

  • enchant_broker_list_dicts(),
enchant_broker_describe(),
enchant_dict_suggest() 関数は、
null ではなく、空の配列を返すようになりました。

Exif

read_exif_data() 関数は削除されました。 exif_read_data() 関数を代わりに使うべきです。

フィルタ

  • FILTER_VALIDATE_URL フラグのための定数 FILTER_FLAG_SCHEME_REQUIRED と FILTER_FLAG_HOST_REQUIRED が削除されました。 scheme と host は（かつてもそうでしたが) 常に必須です。

  • filter_input() 関数などで使われている定数 INPUT_REQUEST と INPUT_SESSION は削除されました。 これらは実装されたことがなく、使うと常に警告が発生していました。

GD

  • 推奨されなくなっていた image2wbmp() 関数は削除されました。

  • 推奨されなくなっていた関数 png2wbmp() と jpeg2wbmp() が削除されました。

  • imagecropauto() 関数の mode 引数のデフォルトは -1 ではなくなりました。 IMG_CROP_DEFAULT を代わりに使うべきです。

  • Windows では、php_gd2.dll の名前が、php_gd.dll に変更されました。

GMP

gmp_random() 関数は削除されました。
gmp_random_range() や
gmp_random_bits() 関数を代わりに使うべきです。

Iconv

エラーが発生した時に errno を適切に設定していなかった iconv の実装はもはやサポートされなくなりました。

IMAP

  • imap_headerinfo() 関数で 未使用になっていた default_host 引数が削除されました。

  • imap_headerinfo() 関数のエイリアスだった imap_header() 関数は削除されました。

国際化関数

  • 推奨されなくなっていた定数 INTL_IDNA_VARIANT_2003 が削除されました。

  • 推奨されなくなっていた定数 Normalizer::NONE が削除されました。

LDAP

  • 推奨されなくなっていた関数
ldap_sort(),
ldap_control_paged_result(),
ldap_control_paged_result_response() は削除されました。

  • ldap_set_rebind_proc() のインターフェイスが変更されました。 callback 引数は空文字列を受け入れなくなりました。 null を代わりに使うべきです。

マルチバイト文字列

  • INI ディレクティブ mbstring.func_overload は削除されました。 関連する定数 MB_OVERLOAD_MAIL, MB_OVERLOAD_STRING, MB_OVERLOAD_REGEX も削除されています。 mb_get_info() 関数の "func_overload" と "func_overload_list" エントリも削除されています。

  • mb_parse_str() は、 結果の配列を指定しないと使えなくなりました。

  • たくさんの mbregex の関数エイリアスが削除されました。 どの関数を代わりに使うべきなのかは、以下の一覧を参照ください:

    • mbregex_encoding() → mb_regex_encoding()
    • mbereg() → mb_ereg()
    • mberegi() → mb_eregi()
    • mbereg_replace() → mb_ereg_replace()
    • mberegi_replace() → mb_eregi_replace()
    • mbsplit() → mb_split()
    • mbereg_match() → mb_ereg_match()
    • mbereg_search() → mb_ereg_search()
    • mbereg_search_pos() → mb_ereg_search_pos()
    • mbereg_search_regs() → mb_ereg_search_regs()
    • mbereg_search_init() → mb_ereg_search_init()
    • mbereg_search_getregs() → mb_ereg_search_getregs()
    • mbereg_search_getpos() → mb_ereg_search_getpos()
    • mbereg_search_setpos() → mb_ereg_search_setpos()

  • mb_ereg_replace() 関数の e 修正子が削除されました。 mb_ereg_replace_callback() 関数を代わりに使って下さい。

  • mb_ereg_replace() 関数に文字列でないパターン引数を渡すと、 ASCII コードポイントではなく、文字列として解釈されるようになりました。 以前のバージョンの振る舞いは、 明示的に chr() 関数を呼び出すことで復元できます。

  • mb_strpos(),
mb_strrpos(), mb_stripos(),
mb_strripos(), mb_strstr(),
mb_stristr(), mb_strrchr(),
mb_strrichr() 関数の
needle 引数は、空に出来るようになりました。

  • mb_decode_numericentity() 関数で内部的に使われていなかった 引数 is_hex は削除されました。

  • mb_strrpos() 関数の第三引数に、 オフセットではなくエンコーディングを渡していた古い振る舞いは削除されました。 明示的にオフセットに 0 を渡し、 第四引数にエンコーディングを渡す方法を代わりに使うべきです。

  • 文字エンコーディング ISO_8859-* のエイリアスは ISO8859-* に置き換えられました。 これは、iconv 拡張モジュールと相互運用性を向上させるためです。 アンダースコア付きの mbregex の ISO 8859 aliases (ISO_8859_* と ISO8859_*) も削除されています。

  • mb_ereg() と mb_eregi() 関数は、 マッチに成功した場合に true を返すようになりました。 これより前のバージョンでは、 matches が渡されなかった場合に 整数 1 が返されていました。 matches が渡された場合には max(1, strlen($matches[0])) が返されていました。

OCI8

  • OCI-Lob クラスは OCILob と呼ばれるようになり、 OCI-Collection クラスは OCICollection と呼ばれるようになりました。 これは、PHP 8 の arginfo 型アノテーションツールの 名前に関する規約で強制されたものです。

  • いくつかの関数エイリアスが推奨されなくなりました。

  • oci_internal_debug() 関数と そのエイリアス ociinternaldebug() は削除されました。

ODBC

  • odbc_connect() 関数は 接続を使い回さなくなりました。

  • odbc_exec() 関数で使われていなかった flags 引数が削除されました。

OpenSSL

  • openssl_seal() と openssl_open() 関数には method を渡すことが必須になりました。 なぜなら、以前のデフォルト値 "RC4" はセキュアでないと見なされているからです。

正規表現 (Perl互換)

不正なエスケープシーケンスを渡した場合、 もはやリテラルと解釈されなくなりました。 リテラルと解釈する振る舞いは X 修正子で必須でしたが、 無視されるようになっています。

PHP Data Objects(PDO)

  • デフォルトのエラーハンドリングのモードが "silent" から "exceptions" に変更されました。 詳細は Errors とエラーハンドリング を参照ください。

  • いくつかの PDOクラスのメソッドシグネチャが変更されました:

    • PDO::query(string $query, ?int $fetchMode = null, mixed ...$fetchModeArgs)
    • PDOStatement::setFetchMode(int $mode, mixed ...$args)

PDO ODBC

php.ini ディレクティブ pdo_odbc.db2_instance_name は削除されました。

PDO MySQL

PDO::inTransaction() は、 PDO が管理しているおおよその情報ではなく、 実際のトランザクションの状態を報告するようになりました。 クエリが "暗黙のコミット" に依存していた場合、 PDO::inTransaction() は後に false を返します。 なぜなら、トランザクションが既にアクティブではないからです。

PostgreSQL

  • pg_connect() 関数で 推奨されなくなっていた、 接続文字列の代わりに複数の引数を受け入れる文法は もはやサポートされなくなりました。

  • 推奨されなくなっていた pg_lo_import() と pg_lo_export() 関数の、 最後の引数で接続を渡すシグネチャはサポートされなくなりました。 代わりに、接続は最初の引数で渡すべきです。

  • pg_fetch_all() 関数 は 結果セットの行が0行の場合に、false ではなく空の配列を返すようになりました。

Phar

phar に関連付けられたメタデータは、自動的にアンシリアライズされなくなりました。 これは、オブジェクトのインスタンス化やオートローディングなどに起因する、 潜在的なセキュリティ上の脆弱性を修正するためです。

リフレクション

  • メソッドシグネチャに関する変更

    • ReflectionClass::newInstance($args)
    • ReflectionFunction::invoke($args)
    • ReflectionMethod::invoke($object, $args)

    は、以下のように変更されました:

    • ReflectionClass::newInstance(...$args)
    • ReflectionFunction::invoke(...$args)
    • ReflectionMethod::invoke($object, ...$args)

    PHP 7 と PHP 8 の間で互換性を保たなければならないコードは、 両方のバージョンで互換性を取るために、以下のようなシグネチャが使えます:

    • ReflectionClass::newInstance($arg = null, ...$args)
    • ReflectionFunction::invoke($arg = null, ...$args)
    • ReflectionMethod::invoke($object, $arg = null, ...$args)

  • ReflectionType::__toString() メソッドは、 完全な型のデバッグ用の文字列表現を返すようになり、非推奨ではなくなりました。 特に、nullable な型に対しては、nullを代入できることを示す情報が含まれるようになります。 戻り値のフォーマットは安定しておらず、PHP のバージョンによって変わる可能性があります。

  • リフレクションの export() メソッドは削除されました。 代わりに、リフレクションオブジェクトを文字列にキャストすることができます。

  • ReflectionMethod::isConstructor() と ReflectionMethod::isDestructor() メソッドは インターフェイスの __construct() と __destruct() についても true を返すようになりました。 これより前のバージョンでは、クラスとトレイトのメソッドに対してだけ true を返していました。

  • ReflectionType::isBuiltin() メソッドは、 ReflectionNamedType クラスに移動しました。 ReflectionUnionType クラスには存在しなくなっています。

Sockets

  • 推奨されなくなっていた socket_addrinfo_lookup() 関数の flags に指定する AI_IDN_ALLOW_UNASSIGNED および AI_IDN_USE_STD3_ASCII_RULES は削除されました。

Standard PHP Library (SPL)

  • SplFileObject::fgetss() メソッドは削除されました。

  • SplFileObject::seek() は、 常に行の先頭にシークするようになりました。 これより前のバージョンでは、 >=1 を position に指定すると、次の行の先頭を探していました。

  • SplHeap::compare() はメソッドシグネチャを指定するようになりました。 このメソッドを実装する継承先のクラスは、 互換性のあるメソッドシグネチャを持たなければなりません。

  • SplDoublyLinkedList::push(),
SplDoublyLinkedList::unshift() および
SplQueue::enqueue() は、true ではなく
void を返すようになりました。

  • spl_autoload_register() 関数は、 引数が不正な場合には常に TypeError を発生させるようになりました。 よって、2番目の引数 do_throw は無視され、 false を設定すると、警告が発生します。

  • SplFixedArray クラスは Iterator ではなく IteratorAggregate を実装しました。 SplFixedArray::rewind(), SplFixedArray::current(), SplFixedArray::key(), SplFixedArray::next(), SplFixedArray::valid() は削除されました。 代替として、SplFixedArray::getIterator() が追加されました。 SplFixedArray を通じて明示的にイテレーションを行うあらゆるコードは、 SplFixedArray::getIterator() メソッドを使い Iterator を取得しなければなりません。 これは、SplFixedArray がネストされたループ中で安全に使えるようになったということです。

標準ライブラリ

  • assert() 関数は 文字列の引数を評価しなくなりました。 代わりに、他の引数と同じように扱われます。 assert('$a == $b') ではなく assert($a == $b) を使うべきです。 INI ディレクティブ assert.quiet_eval と 定数 ASSERT_QUIET_EVAL も削除されました。 なぜなら、もはや何の効果も無いからです。

  • parse_str() は、 結果の配列を指定しなければ使えなくなりました。

  • string.strip_tags フィルタは削除されました。

  • strpos(),
strrpos(),
stripos(),
strripos(),
strstr(),
strchr(),
strrchr(),
stristr() 関数の
needle
引数は常に文字列として解釈されるようになりました。
これより前のバージョンでは、
文字列でない引数は ASCII コードポイントと解釈されていました。
chr() 関数を明示的に呼ぶことで、
以前の振る舞いを復元できます。

  • strpos(),
strrpos(),
stripos(),
strripos(),
strstr(),
stristr(),
strrchr() 関数の
needle 引数は、空に出来るようになりました。

  • substr(), substr_count(), substr_compare(), iconv_substr() 関数の length 引数は null も指定できるようになりました。 null を指定した場合、 length 引数が指定されなかったことと同じように振る舞います。 よって、この場合、空文字列ではなく、残りの文字列を返します。

  • array_splice() 関数の length 引数は null も指定できるようになりました。 null を指定した場合、引数を省略した場合と同じ振る舞いをします。 よって、offset から配列の最後までの全ての要素を削除する動きになります。

  • vsprintf(),
vfprintf(),
vprintf() 関数の
args 引数は、配列であることが必須になりました。
これより前のバージョンでは、あらゆる型の値を受け入れていました。

  • password_hash() 関数の 'salt' オプションはサポートされなくなりました。 'salt' オプションを使うと警告が生成され、 指定された salt は無視されます。 そして生成された salt が代わりに使われます。

  • quotemeta() 関数は、空文字列を渡すと空文字列を返すようになりました。 これより前のバージョンでは、false を返していました。

  • 以下の関数は削除されました:

    • hebrevc()
    • convert_cyr_string()
    • money_format()
    • ezmlm_hash()
    • restore_include_path()
    • get_magic_quotes_gpc()
    • get_magic_quotes_runtime()
    • fgetss()

  • 定数 FILTER_SANITIZE_MAGIC_QUOTES は削除されました。

  • ($pieces, $glue) のような形で、implode() 関数を逆の引数の順番で呼ぶことはサポートされなくなりました。

  • parse_url() 関数は、 query および fragment が存在しないことと、空であることを区別するようになりました:

    • http://example.com/foo → query = null, fragment = null
    • http://example.com/foo? → query = "", fragment = null
    • http://example.com/foo# → query = null, fragment = ""
    • http://example.com/foo?# → query = "", fragment = ""
    これより前のバージョンでは、上の全ての場合で、query と fragment の値が null になっていました。

  • var_dump() と debug_zval_dump() 関数は INIディレクティブ precision ではなく serialize_precision を使って浮動小数点を印字するようになりました。 デフォルトの設定では、浮動小数点はこのデバッグ関数によって 全精度で印字されるようになるということです。

  • __sleep() が返す 配列に存在しないプロパティが含まれていた場合、 静かに無視されるようになりました。 これより前のバージョンでは、 そうしたプロパティは値 null を持つかのようにシリアライズされていました。

  • デフォルトの起動時のロケールは、常に "C" になりました。 デフォルトでは、どのロケールからも環境を継承しません。 これより前のバージョンでは、 LC_ALL は "C" に設定されていましたが、 LC_CTYPE は環境から情報を継承していました。 しかしながら、関数によっては、明示的に setlocale() を呼び出さないと 継承した環境を尊重しないものもあります。 ロケールをデフォルトから変えるためには、 setlocale() 関数を明示的に呼ぶことが常に必須になりました。

  • 非推奨になっていた crypt() 関数が DES にフォールバックする振る舞いが削除されました。 不明な salt フォーマットを crypt() 関数に渡すと、 弱い DES ハッシュにフォールバックするのではなく、 *0 という値になり、失敗するようになります。

  • crypt() 関数に、 SHA256/SHA512 の範囲外の round を指定すると、 最も近い境界値に切り詰めるのではなく、 *0 という値になり、失敗するようになりました。 これは、glibc の振る舞いと一致します。

  • 配列に比較結果が等しい要素が含まれている場合、ソートを行う関数の結果が変わる可能性があります。

  • コールバックを受け入れるあらゆる関数のうち、 リファレンスの引数を受け入れるように明示的に指定して「いない」 ものに対し、 リファレンスを使ったコールバックを渡すと警告が発生するようになりました。 例としては、 array_filter() や array_reduce() 関数があります。 これらでほとんどの関数の例を示していますが、全てではありません。

  • file_get_contents() 関数のように、 関数が使うHTTPストリームラッパーは、 デフォルトで HTTP/1.0 ではなく、 HTTP/1.1 を指定するようになりました。 これによって、クライアントの振る舞いが変わるわけではありませんが、 サーバーが異なるレスポンスを返す可能性があります。 古い振る舞いをさせるには、 以下のようにして 'protocol_version' ストリームコンテキストオプションを設定して下さい。

    <?php
    $ctx     = stream_context_create(['http' => ['protocol_version' => '1.0']]);
    echo     file_get_contents('http://example.org', false, $ctx);
    ?>

  • 明示的に salt を指定せず crypt() 関数を呼ぶことはサポートされなくなりました。 自動的に生成される salt で強いハッシュを生成したい場合、 代わりに password_hash() を使って下さい。

  • substr(),
mb_substr(),
iconv_substr(),
grapheme_substr() 関数は、
文字列の境界を越えたオフセットを一貫した形で処理するようになりました。
これより前のバージョンでは、空文字列ではなく false を返す場合がありました。

  • Windows では、 シェルを使い、プログラムを実行する関数 (proc_open(), exec(), popen() など) は、 一貫して %comspec% /s /c "$commandline" を使うようになりました。 これは、(追加のクォート無しで) $commandline を実行することと同じです。

Sysvsem

  • sem_get() 関数の auto_release 引数は、 int ではなく bool の値を受け入れるように変更されました。

Tidy

  • 内部的に使われていなかった use_include_path 引数が、 tidy_repair_string() 関数から削除されました。

  • tidy::repairString(), tidy::repairFile() が、staticメソッドになりました。

Tokenizer

  • T_COMMENT トークンは最後の改行文字を含まなくなりました。 改行文字はその後に続く T_WHITESPACE トークンに含まれるようになります。 注意すべきなのは、 T_COMMENT の後にホワイトスペースが続くとは限らないことです。 T_CLOSE_TAG やファイルの終端が続く場合もありえます。

  • 名前空間の中にある名前は、 T_NAME_QUALIFIED (Foo\Bar), T_NAME_FULLY_QUALIFIED (\Foo\Bar), T_NAME_RELATIVE (namespace\Foo\Bar) トークンを使って表現されるようになりました。 T_NS_SEPARATOR トークンは 単独の名前空間の区切り文字としてだけ使われます。 そして、グループ化されたuse宣言と一緒に使った場合にだけ文法的に合法です。

XMLReader

XMLReader::open(), XMLReader::xml() が staticメソッドになりました。 これらは、まだインスタンスメソッドとして呼び出すことが出来ますが、 クラスを継承し、これらのメソッドをオーバーライドする場合は、 それらは static として宣言する必要があります。

XML-RPC

XML-RPC 拡張モジュールは PECL に移動し、PHPの一部として配布されなくなりました。

Zip

ZipArchive::OPSYS_Z_CPM は削除されました(この名前は typo でした)。 ZipArchive::OPSYS_CPM を代わりに使って下さい。

Zlib

  • gzgetss() 関数が削除されました。

  • zlib.output_compression は、Content-Type: image/* を自動的に無効にすることはなくなりました。

Windows の PHP Test Packs

テストランナーの名前が、run-test.php から run-tests.php に変更されました。 これは、php-src の名前に合わせるためです。


推奨されなくなる機能

PHP コア

  • デフォルト値を持つ引数の後に、必須の引数が続く場合、デフォルト値は意味をなしません。 こうした書き方は PHP 8.0.0 から推奨されなくなります。 以下のようにしてデフォルト値を削除することで、機能を変更することなく解決できます:

    <?php
    function test($a = [], $b) {} // 変更前
    function test($a, $b) {} // 変更後
    ?>

    このルールの唯一の例外は、Type $param = null と書かれた引数です。 null をデフォルトにすることは、型が暗黙のうちに nullable であることを示しています。 この書き方はまだ許可されていますが、以下のようにして 明示的に nullable 型を使うことを推奨します:

    <?php
    function test(A $a = null, $b) {} // まだ許可されています
    function test(?A $a, $b) {} // 推奨される書き方
    ?>

  • exclude_disabled を明示的に false に指定して get_defined_functions() 関数を呼び出すことは推奨されなくなり、 結果として何も起きなくなりました。 get_defined_functions() 関数は無効な関数を返さなくなっています。

Enchant

  • enchant_broker_set_dict_path() と enchant_broker_get_dict_path() 関数は推奨されません。 これらの機能は libenchant < 1.5 や libenchant-2 では既に利用できないからです。

  • enchant_dict_add_to_personal() は推奨されません。 enchant_dict_add() を代わりに使って下さい。

  • enchant_dict_is_in_session() は推奨されません。 enchant_dict_is_added() を代わりに使って下さい。

  • enchant_broker_free() と enchant_broker_free_dict() は推奨されません。 代わりにオブジェクトを unset して下さい。

  • 定数 ENCHANT_MYSPELL と ENCHANT_ISPELL は推奨されません。

LibXML

libxml_disable_entity_loader() 関数は推奨されなくなりました。 libxml 2.9.0 がビルドに必須になったので、 外部エンティティの読み込みはデフォルトで無効になっていることが保証されています。 よって、(未だ脆弱な) LIBXML_NOENT を使わない限り、 XXE 攻撃を防ぐためにこの関数を使う必要は既になくなっています。 LIBXML_NOENT をまだ使っている場合は、 外部エンティティの読み込みを抑制するように、 libxml_set_external_entity_loader() を使ってコードをリファクタリングすることを推奨します。

PGSQL / PDO PGSQL

  • 定数 PGSQL_LIBPQ_VERSION_STR の値は、 PGSQL_LIBPQ_VERSION と同じになりました。 よって、PGSQL_LIBPQ_VERSION_STR は推奨されません。

  • pgsql 拡張モジュールの関数エイリアスは推奨されなくなりました。 代わりにどの関数を使うべきなのかは、以下の一覧を参照ください:

    • pg_errormessage() → pg_last_error()
    • pg_numrows() → pg_num_rows()
    • pg_numfields() → pg_num_fields()
    • pg_cmdtuples() → pg_affected_rows()
    • pg_fieldname() → pg_field_name()
    • pg_fieldsize() → pg_field_size()
    • pg_fieldtype() → pg_field_type()
    • pg_fieldnum() → pg_field_num()
    • pg_result() → pg_fetch_result()
    • pg_fieldprtlen() → pg_field_prtlen()
    • pg_fieldisnull() → pg_field_is_null()
    • pg_freeresult() → pg_free_result()
    • pg_getlastoid() → pg_last_oid()
    • pg_locreate() → pg_lo_create()
    • pg_lounlink() → pg_lo_unlink()
    • pg_loopen() → pg_lo_open()
    • pg_loclose() → pg_lo_close()
    • pg_loread() → pg_lo_read()
    • pg_lowrite() → pg_lo_write()
    • pg_loreadall() → pg_lo_read_all()
    • pg_loimport() → pg_lo_import()
    • pg_loexport() → pg_lo_export()
    • pg_setclientencoding() → pg_set_client_encoding()
    • pg_clientencoding() -> pg_client_encoding()

標準ライブラリ

  • true または false を返すソートの比較関数は、推奨されない警告を発生させるようになりました。 0より大きいか、0に等しいか、0より小さい整数を返す実装に置き換えるべきです。

    <?php
    // この実装を
    usort($array, fn($a, $b) => $a > $b);
    // 以下のように置き換えて下さい
    usort($array, fn($a, $b) => $a <=> $b);
    ?>

Zip

  • 空のファイルを ZipArchive として使うことは推奨されなくなりました。 Libzip 1.6.0 は空のファイルを正しいzipアーカイブとして受け入れなくなっています。 既に存在する回避策は、次のバージョンで削除される予定です。

  • Zip の手続き型の API は推奨されなくなりました。 ZipArchive クラスを代わりに使って下さい。 ZipArchive::statIndex() と for ループを以下のようにして使えば、 全てのエントリを処理できます:

    <?php
    // 手続き型のAPIを使ってループする
    assert(is_resource($zip));
    while (    $entry = zip_read($zip)) {
    echo     zip_entry_name($entry);
    }

    // オブジェクト指向のAPIを使ってループする
    assert($zip instanceof ZipArchive);
    for (    $i = 0; $entry = $zip->statIndex($i); $i++) {
    echo     $entry['name'];
    }
    ?>

リフレクション

  • ReflectionFunction::isDisabled() は推奨されなくなりました。 無効な関数に対して ReflectionFunction を生成することはできなくなっているためです。 このメソッドは常に false を返すようになっています。

  • ReflectionParameter::getClass(),
ReflectionParameter::isArray(),
ReflectionParameter::isCallable() は推奨されません。
ReflectionParameter::getType() と
ReflectionType API を代わりに使って下さい。


その他の変更

SAPI モジュールの変更

Apache2Handler

PHP モジュールの名前が php7_module から php_module に変更されました。

変更された関数

リフレクション

ReflectionClass::getConstants() と ReflectionClass::getReflectionConstants() の結果は 新しい引数 filter を経由してフィルタされるように変更されました。 この用途のために、以下の3つの新しい定数が追加されています:

  • ReflectionClassConstant::IS_PUBLIC
  • ReflectionClassConstant::IS_PROTECTED
  • ReflectionClassConstant::IS_PRIVATE

標準ライブラリ

数学関数 abs(), ceil(), floor(), round() は、 strict_types ディレクティブ を適切に尊重するようになりました。 PHP 8.0.0 より前のバージョンでは、 たとえ strict モードであっても、 最初の引数の型を強制的に自動変換していました。

Zip

  • ZipArchive::addGlob() と ZipArchive::addPattern() メソッドは 配列 options の値に、以下の値を追加で受け入れるようになりました:

    • flags
    • comp_method
    • comp_flags
    • env_method
    • enc_password

  • ZipArchive::addEmptyDir(),
ZipArchive::addFile(),
ZipArchive::addFromString() に新しい引数
flags が追加されました。
これによって、名前のエンコーディング
(ZipArchive::FL_ENC_*)
とエントリの置換 (ZipArchive::FL_OVERWRITE) が管理できるようになります。

  • ZipArchive::extractTo() メソッドは、ファイルの変更時間も復元するようになりました。

拡張モジュールに対するその他の変更

CURL

  • CURL 拡張モジュールは、libcurl 7.29.0 以降が必須になりました。

  • 推奨されなくなっていた curl_version() 関数の version 引数が削除されました。

日付と時刻

DatePeriod クラスが、 (Traversable ではなく) IteratorAggregate を実装しました。

DOM

DOMNamedNodeMap と DOMNodeList が、 (Traversable ではなく) IteratorAggregate を実装しました。

国際化関数

IntlBreakIterator と ResourceBundle が、 (Traversable ではなく) IteratorAggregate を実装しました。

Enchant

enchant 拡張モジュールは、利用可能な場合は、デフォルトで libenchant-2 を使うようになりました。 libenchant バージョン1 もまだサポートしていますが、推奨されませんし、将来削除される可能性があります。

GD

  • imagepolygon(), imageopenpolygon(), imagefilledpolygon() 関数の num_points 引数はオプションになりました。 つまり、これらの関数は3つ、または4つの引数で呼び出すことが出来るということです。 この引数が省略された場合、この値は count($points)/2 で計算されます。

  • 現在の補間メソッドを取得するために、imagegetinterpolation() 関数が追加されました。

JSON

JSON 拡張モジュールは無効にできなくなりました。 date 拡張モジュールと同様に、PHP をビルドするために常に必須になっています。

マルチバイト文字列

Unicode データのテーブルが、バージョン 13.0.0 に更新されました。

PDO

PDOStatement は、 (Traversable ではなく) IteratorAggregate を実装しました。

LibXML

libxml の最低バージョンが 2.9.0 になりました。 これにより、外部エンティティの読み込みがデフォルトで無効であることが保証されるようになりました。 よって、XXE攻撃を防ぐために追加の手順を踏む必要はありません。

MySQLi / PDO MySQL

  • mysqlnd を使わない (これはデフォルトであり、推奨されるオプションです) 場合、 サポートされる libmysqlclient の最低バージョンは 5.5 になりました。

  • mysqli_result は、 (Traversable ではなく) IteratorAggregate を実装しました。

PGSQL / PDO PGSQL

PGSQL と PDO PGSQL 拡張モジュールは、libpq 9.1 以降が最低限必要になりました。

Readline

対話的なプロンプトが始まる前に (つまり、 auto_prepend_file を実行中に) readline_completion_function() を呼ぶと、 デフォルトの対話プロンプトの補完関数を上書きするようになりました。 PHP 8.0.0 より前のバージョンでは、 readline_completion_function() 関数は 対話的なプロンプトが始まった後に呼び出したときにだけ動作していました。

SimpleXML

SimpleXMLElement は、 RecursiveIterator を実装し、 SimpleXMLIterator の機能を吸収しました。 SimpleXMLIterator は、 SimpleXMLElement を継承しただけのものです。

INI ファイルの扱いの変更

  • com.dotnet_version は、dotnet オブジェクトで使う、 .NET framework のバージョンを選ぶための新しいINIディレクティブです。

  • zend.exception_string_param_max_len は、文字列化されたスタックトレースの引数中の、 文字列の最大の長さを設定する新しいINIディレクティブです。

EBCDIC

EBCDIC ターゲットはサポートされなくなりました。 しかし、そもそもまだ動いているわけでもなさそうです。

パフォーマンスに関わる変更

  • ジャストインタイム (JIT) コンパイラが opcache 拡張モジュールに追加されました。

  • 隙間がない配列で array_slice() 関数を使う場合、 最初のオフセットを探すために配列全体を走査しなくなりました。 これによって、オフセットが巨大、かつサイズが小さい場合に、 関数の実行時間が著しく改善する可能性があります。

  • LC_CTYPE ロケールが "C" の場合 (これはデフォルトです)、 strtolower() 関数は SIMD 実装を使うようになりました。


PHP 7.3.x から PHP 7.4.x への移行

目次

  • 新機能
  • 新しいクラスとインターフェイス
  • 新しく追加された関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 7.4.x で推奨されなくなる機能
  • 削除された拡張モジュール
  • その他の変更
  • Windows のサポート

このマイナーバージョンアップには数多くの 新機能 があります。また、互換性がない変更 が多少あるので、実運用環境の PHP をこのバージョンにあげる前にはテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.0.x, 7.1.x, 7.2.x, 7.3.x.


新機能

PHP コア

型付きプロパティ

クラスのプロパティは、新たに型宣言をサポートするようになりました

<?php
class User {
public int $id;
public string $name;
}
?>
上の例は、 $user->id には int の 値だけを、そして $user->name には string の値だけを代入できるように強制します。

アロー関数

アロー関数は、暗黙的な値スコープを持った関数を定義する簡便な文法を提供します。

<?php
$factor = 10;
$nums = array_map(fn($n) => $n * $factor, [1, 2, 3, 4]);
// $nums = array(10, 20, 30, 40);
?>

戻り値の型を狭めたり、引数の型を広げたりする

次のようなコードが動作するようになります:

<?php
class A {}
class B extends A {}

class Producer {
public function method(): A {}
}
class ChildProducer extends Producer {
public function method(): B {}
}
?>
完全な型の変位指定は、オートローディングが使われている場合のみ有効です。単一ファイル内では、型の参照が循環参照していない場合のみ可能です。なぜなら、全てのクラスは参照する前に利用可能でなければならないからです。

Null 合体代入演算子

<?php
$array['key'] ??= computeDefault();
// は、以下にほぼ等しい
if (!isset($array['key'])) {
$array['key'] = computeDefault();
}
?>

配列内での値のアンパック

<?php
$parts = ['apple', 'pear'];
$fruits = ['banana', 'orange', ...$parts, 'watermelon'];
// ['banana', 'orange', 'apple', 'pear', 'watermelon'];
?>

数値リテラルのセパレータ

数値リテラルは、桁と桁の間にアンダースコアを挿入できるようになりました。

<?php
6.674_083e-11; // float
299_792_458; // decimal
0xCAFE_F00D; // hexadecimal
0b0101_1111; // binary
?>

弱い参照

弱い参照 により、オブジェクトが破棄されるのを妨げないオブジェクトへの参照を保持することが可能です。

__toString() から例外をスロー可能に

__toString() から例外をスローできるようになりました。以前は、この場合には致命的なエラーが発生していました。この関数内に既に存在する、回復可能な致命的なエラーは Error 例外クラスに変換されます。

CURL

CURLFile は、CURL拡張モジュールが libcurl 7.56.0 より新しいものでビルドされた場合は、通常のファイル名に加えて、ストリームラッパーをサポートするようになります。

Filter

FILTER_VALIDATE_FLOAT フィルタは min_range と max_range オプションをサポートするようになりました。 これは、FILTER_VALIDATE_INT と同じセマンティクスです。

FFI

FFI は、ネイティブ関数を呼び出したり、ネイティブな値にアクセスしたり、Cライブラリで定義されたデータ構造を生成/アクセスする簡単な方法を提供する新しい拡張モジュールです。

GD

画像に scatter フィルタを適用するための IMG_FILTER_SCATTER が追加されました。

Hash

Castagnoli 多項式を使った crc32c ハッシュが追加されました。 CRC32 バリアントは、 iSCSI, SCTP, Btrfs, ext4 のようなストレージシステムで使われています。

マルチバイト文字列

str_split() と同等の機能を提供するものの、バイトではなく、コードポイント単位で動作する mb_str_split() 関数が追加されました。

OPcache

コードを事前ロードする機能 がサポートされました。

正規表現 (Perl互換)

preg_replace_callback() および preg_replace_callback_array() 関数は、追加のフラグを受け入れるようになりました。 PREG_OFFSET_CAPTURE と PREG_UNMATCHED_AS_NULL です。これは、コールバック関数に渡される matches配列のフォーマットに影響します。

PDO

ユーザー名とパスワードが、PDO DSN の一部として指定できるようになりました。対象となるのは、mysql, mssql, sybase, dblib, firebird, oci ドライバです。以前は、この機能は pgsql ドライバでのみサポートされていました。ユーザー名/パスワードがコンストラクタとDSNの両方で指定された場合は、コンストラクタの指定が優先します。

SQLクエリのクエスチョンマークが、パラメータのプレースホルダーとして解釈されるのを防ぐためにエスケープできるようになりました。?? を書くことで、単一のクエスチョンマークをデータベースに送信できるようになります。PostgreSQL のJSONのキーが存在するかを確認する演算子 (?) として使って下さい。

PDO_OCI

PDOStatement::getColumnMeta() が利用できるようになりました。

PDO_SQLite

PDOStatement::getAttribute(PDO::SQLITE_ATTR_READONLY_STATEMENT) は、ステートメントが読み取り専用かどうか、つまりそれがデータベースを変更しないかをチェックできるようになりました。

PDO::setAttribute(PDO::SQLITE_ATTR_EXTENDED_RESULT_CODES,
true) 関数によって、PDO::errorInfo() と
PDOStatement::errorInfo() 経由で SQLite3
の拡張結果コードを使えるようになりました。

SQLite3

最新の拡張結果コードを取得するために、 SQLite3::lastExtendedErrorCode() が追加されました。

SQLite3::enableExtendedResultCodes($enable = true) が追加されました。これによって、 SQLite3::lastErrorCode() が拡張結果コードを返すようになります。

標準ライブラリ

strip_tags() をタグ名の配列とともに使う

strip_tags() 関数は、許可するタグの配列も受け入れるようになりました。つまり、strip_tags($str, '<a><p>') の代わりに、 strip_tags($str, ['a', 'p']) と書けるようになったということです。

カスタムオブジェクトのシリアル化

新しいカスタムオブジェクトのシリアル化の機構が追加されました。これは、新しいふたつのマジックメソッド __serialize と __unserialize を使います。

<?php
// オブジェクトに必要な状態を全て保持した配列を返す
public function __serialize(): array;

// 与えられた data 配列から、オブジェクトの状態を復元する
public function __unserialize(array $data): void;
?>
新しいシリアル化の機構は、 Serializable インターフェイス を置き換えるものです。 Serializable インターフェイスは将来非推奨になるでしょう。

引数を渡さずに array_merge 系の関数を使用する

array_merge() および
array_merge_recursive()
関数は、引数なしでも呼び出せるようになりました。この場合、空の配列が返されます。これは、array_merge(...$arrays)
のように、... 演算子と組み合わせて使う時に便利です。

proc_open() 関数

proc_open() 関数は、コマンドの文字列ではなく、配列を受け入れるようになりました。この場合、プロセスは(shellを通さず) 直接オープンされ、PHP が必要な引数のエスケープをすべて行います。

<?php
proc_open(['php', '-r', 'echo "Hello World\n";'], $descriptors, $pipes);
?>

proc_open() が、 redirect と null ディスクリプタをサポートしました。

<?php
// シェルにおける 2>&1 のような操作
proc_open($cmd, [1 => ['pipe', 'w'], 2 => ['redirect', 1]], $pipes);
// シェルにおける 2>/dev/null や 2>null のような操作
proc_open($cmd, [1 => ['pipe', 'w'], 2 => ['null']], $pipes);
?>

libargon なしでの argon2i(d)

PHP が libargon を使わずにビルドされた場合、password_hash() 関数は sodium 拡張モジュールの argon2i と argon2id を使った実装を使うようになります。


  • ≪ 新機能
  • 新しく追加された関数 ≫
  • PHP Manual
  • PHP 7.3.x から PHP 7.4.x への移行
  • 新しいクラスとインターフェイス

新しいクラスとインターフェイス

Reflection

  • ReflectionReference


新しく追加された関数

PHP コア

  • get_mangled_object_vars()
  • password_algos()
  • sapi_windows_set_ctrl_handler()

GD

  • imagecreatefromtga()

マルチバイト文字列

  • mb_str_split()

OpenSSL

  • openssl_x509_verify()

プロセス制御

  • pcntl_unshare()

SQLite3

  • SQLite3::backup()
  • SQLite3Stmt::getSQL()


新しいグローバル定数

PHP コア

  • PHP_WINDOWS_EVENT_CTRL_C
  • PHP_WINDOWS_EVENT_CTRL_BREAK

マルチバイト文字列

  • MB_ONIGURUMA_VERSION

Socket

FreeBSD特有の、以下のオプションが追加されました:

  • SO_LABEL
  • SO_PEERLABEL
  • SO_LISTENQLIMIT
  • SO_LISTENQLEN
  • SO_USER_COOKIE

Tidy

  • TIDY_TAG_ARTICLE
  • TIDY_TAG_ASIDE
  • TIDY_TAG_AUDIO
  • TIDY_TAG_BDI
  • TIDY_TAG_CANVAS
  • TIDY_TAG_COMMAND
  • TIDY_TAG_DATALIST
  • TIDY_TAG_DETAILS
  • TIDY_TAG_DIALOG
  • TIDY_TAG_FIGCAPTION
  • TIDY_TAG_FIGURE
  • TIDY_TAG_FOOTER
  • TIDY_TAG_HEADER
  • TIDY_TAG_HGROUP
  • TIDY_TAG_MAIN
  • TIDY_TAG_MARK
  • TIDY_TAG_MENUITEM
  • TIDY_TAG_METER
  • TIDY_TAG_NAV
  • TIDY_TAG_OUTPUT
  • TIDY_TAG_PROGRESS
  • TIDY_TAG_SECTION
  • TIDY_TAG_SOURCE
  • TIDY_TAG_SUMMARY
  • TIDY_TAG_TEMPLATE
  • TIDY_TAG_TIME
  • TIDY_TAG_TRACK
  • TIDY_TAG_VIDEO


下位互換性のない変更点

PHP コア

配列でない値を配列スタイルでアクセスした場合

null, bool, int, float または resource 型を ($null["key"] のように) 配列としてアクセスしようとすると、警告が生成されるようになりました。

get_declared_classes() 関数

get_declared_classes() 関数は、まだインスタンス化されていない無名クラスを返さなくなりました。

fn キーワード

fn は、予約語になりました。特に、関数名やクラス名として使うことはできなくなりました。メソッド名やクラスの定数名の場合は使用できます。

ファイルの最後の <?php タグ

ファイルの最後の (改行が最後に付かない) <?php タグは、PHPタグの開始タグとして解釈されるようになりました。以前は、短い形式の開始タグ <? の後にリテラル php を続けたものとして解釈されるか、(short_open_tag=1 の場合は) 文法エラー になるか、(short_open_tag=0 の場合は) <?php というリテラルとして解釈されていました。

ストリームラッパー

ストリーム上で include/require を使う場合、streamWrapper::stream_set_option() が STREAM_OPTION_READ_BUFFER オプション付きで呼び出されるようになります。カスタムのストリームラッパーの実装は 警告を回避するために streamWrapper::stream_set_option() を実装する必要があるかもしれません (不十分な実装に対しては常に false を返します)

シリアル化

シリアル化フォーマット o は削除されました。 PHP によって生成されなくなるので、手動で組まれた文字列のシリアル化を復元する場合のみ、壊れる場合があります。

パスワードアルゴリズムの定数

パスワードハッシュのアルゴリズムの識別子は、数値型ではなく、nullable な文字列型になりました。

  • PASSWORD_DEFAULT は int型の 1 でしたが、 string の '2y' になりました。 (PHP 7.4.0, 7.4.1, 7.4.2 では null でした)
  • PASSWORD_BCRYPT は int型の 1 でしたが、string の '2y' になりました。
  • PASSWORD_ARGON2I は int型の 2 でしたが、string の 'argon2i' になりました。
  • PASSWORD_ARGON2ID は int型の 3 でしたが、string の 'argon2id' になりました。

PASSWORD_DEFAULT, PASSWORD_BCRYPT, PASSWORD_ARGON2I, および PASSWORD_ARGON2ID 定数を正しく使っているアプリケーションは、正しく動作し続けるはずです。

htmlentities() 関数

htmlentities() 関数は 基本的なエンティティ置換だけをサポートしているエンコーディングで使われた場合、 (E_STRICT ではなく) E_NOTICE を発生させるようになりました。E_NOTICE が発生するのは、htmlspecialchars() の場合と同等です。

fread() および fwrite() 関数

fread() と fwrite() 関数は、操作に失敗した場合に false を返すようになりました。以前は空文字列か 0 を返していました。EAGAIN/EWOULDBLOCK は、失敗と見做されません。

これらの関数は、読み取り専用のリソースに書き込もうとして失敗したような場合に E_NOTICE を発生させるようになりました。

BCMath

BCMath 関数は、"32foo" のような不完全な数値が渡された場合に警告を生成するようになりました。以前はそうした引数は0として解釈されていました。

CURL

CURLFile をシリアル化しようとすると、例外が発生するようになりました。以前は、シリアル化を復元しようとした場合のみ、例外が発生していました。

CURLPIPE_HTTP1 は非推奨になり、cURL 7.62.0 からサポートされなくなりました。

curl_version() 関数の $version 引数は推奨されません。デフォルトの CURLVERSION_NOW 以外の値が渡された場合、警告が生成され、渡された引数は無視されます。

日付と時刻

DateTime や DateTimeImmutable のインスタンスに対して var_dump() 類似の関数を呼び出しても、オブジェクトでアクセス可能なプロパティのみを表示するようになりました。

DateInterval オブジェクトを ( ==, < などを使って) 比較した場合、警告が出て常に false が返されるようになりました。以前は、プロパティがない場合、全ての DateInterval オブジェクトが等しいと見做されていました。

国際化関数

idn_to_ascii() と idn_to_utf8() 関数のデフォルト値は、非推奨の INTL_IDNA_VARIANT_2003 ではなく INTL_IDNA_VARIANT_UTS46 となりました。

MySQLi

組み込みサーバーの機能は削除されました。少なくとも PHP 7.0 以降、この機能は壊れていました。

ドキュメントに書かれていない mysqli::$stat プロパティは削除され、mysqli::stat() に置き換えられました。

OpenSSL

openssl_random_pseudo_bytes() 関数は、エラーが発生した場合に例外をスローするようになりました。random_bytes() 関数も同じです。 特に、リクエストされたバイト数が0以下の場合には、 Error がスローされ、十分なランダム性が得られなかった場合は Exception が生成されます。 $crypto_strong の出力引数は、 例外がスローされなかった場合は常に true であることが保証されるので、明示的なチェックは不要です。

Regular Expressions (Perl互換)

PREG_UNMATCHED_AS_NULL モードが使われた場合、後に続くマッチしなかったキャプチャグループにも null (offset キャプチャが有効になっていた場合は [null, -1] になります) が設定されるようになりました。 これは、$matches のサイズが常に同じになることを意味します。

PDO

PDO や PDOStatement のインスタンスをシリアル化しようとすると、PDOException ではなく Exception が生成されるようになりました。これは、シリアル化をサポートしていない他の内部的なクラスと一貫した挙動です。

ReflectionClassConstant, ReflectionMethod, ReflectionProperty のクラス定数の値が変更されました。

リフレクション

リフレクションオブジェクトをシリアル化しようとすると、例外を生成するようになりました。リフレクションオブジェクトのシリアル化はこれまでサポートされたことはなく、壊れたリフレクションオブジェクトを返していました。このバージョンから、明示的に禁止されました。

Standard PHP Library (SPL)

ArrayObject インスタンスに対して get_object_vars() 関数を呼ぶと、ArrayObject そのもの(またはそのサブクラス) のプロパティを常に返すようになりました。以前は、ArrayObject::STD_PROP_LIST フラグが指定されない限り、ラップされた 配列/オブジェクト の値を返していました。

他に影響を受ける操作として、以下が挙げられます:

  • ReflectionObject::getProperties()
  • reset(), current() など。 Iterator メソッドを代わりに使ってください。
  • オブジェクトのプロパティをリストとして扱うその他の操作も、影響を受ける可能性があります。 たとえば array_walk() 関数が挙げられます。

(array) キャストは影響を受けません。この操作は引き続き、ラップされた配列を返すか、ArrayObject のプロパティを返します。これは、ArrayObject::STD_PROP_LIST フラグが指定されたかどうかによって異なります。

SplPriorityQueue::setExtractFlags() は、0を渡された場合に例外をスローするようになりました。以前は、次の配列を展開する操作の際に回復可能な致命的なエラーを生成していました。

ArrayObject, ArrayIterator, SplDoublyLinkedList および SplObjectStorage は、Serializable に加えて、新たに __serialize() と __unserialize() 機構をサポートしました。 これによって、古いPHPバージョンでシリアル化されたペイロードはまだ復元可能であることを意味しますが、PHP 7.4 で生成された新しいペイロードを、古いバージョンは理解しないことを意味します。

Tokenizer

token_get_all() 関数は、トークンストリームに穴を開けるのではなく、T_BAD_CHARACTER トークンを生成するようになりました。

外部から入力されるCookie

PHP 7.4.11 以降は、セキュリティ上の理由により、 外部から入力される Cookie の 名前 はurlデコードされなくなりました。


PHP 7.4.x で推奨されなくなる機能

PHPコア

明示的に括弧で囲わずに三項演算子をネストする

三項演算子をネストする場合、演算の順番を示すために明示的に括弧で囲わなければならなくなりました。以前は、括弧を使わなかった場合、左結合の演算がほとんどの場合期待した動作になりませんでした。

<?php
1 ? 2 : 3 ? 4 : 5; // deprecated
(1 ? 2 : 3) ? 4 : 5; // ok
1 ? 2 : (3 ? 4 : 5); // ok
?>

2番目のオペランドをネストさせる場合は、括弧は必須では ありません。 なぜなら、これについては曖昧さがなく、結合法則に影響がないからです。

1 ? 2 ? 3 : 4 : 5 // ok

波括弧を使った、配列や文字列のオフセットへのアクセス

波括弧を使って配列や文字列のオフセットにアクセスする文法は推奨されません。$var{$idx} でなはく $var[$idx] を使って下さい。

(real) によるキャストと is_real() 関数

(real) によるキャストは推奨されません。 (float) を代わりに使って下さい。

is_real() 関数も同様に推奨されません。 is_float() 関数を使って下さい。

$this が使われている場合に、$this のバインドを解除する

$this を使っている static でないクロージャの $this のバインドを解除することは推奨されません。

親クラスがない場合における parent キーワードの利用

親クラスがないクラス内で parent を使うのは推奨されませんし、将来的にはコンパイル時にエラーが発生することになるでしょう。 現状では、この推奨されないエラーは、実行時に親クラスに対してアクセスされた場合に生成されます。

php.ini における allow_url_include オプション

allow_url_include iniディレクティブは推奨されません。これを有効にすると、起動時に推奨されない警告が生成されます。

基数を変更する関数における不正な文字

base_convert(), bindec(), octdec() および hexdec() 関数に不正な文字を渡すと、推奨されない警告が生成されるようになりました。 あたかも不正な文字が存在しないかのように結果は計算されます。空白文字が前後にあったり、(基数によっては) 0x をプレフィックスとして指定することも可能です。

オブジェクトに対する array_key_exists() 関数の使用

オブジェクトに対する array_key_exists()
関数の使用は、推奨されません。代わりに、isset() または
property_exists() を使って下さい。

マジッククォート関数

get_magic_quotes_gpc() や get_magic_quotes_runtime() 関数は推奨されません。これらの関数は常に false を返します。

hebrevc() 関数

hebrevc() 関数は推奨されません。 nl2br(hebrev($str)) で置き換えられますが、Unicode RTL のサポートを使う方が好ましいです。

convert_cyr_string() 関数

convert_cyr_string() 関数は推奨されません。
mb_convert_string(),
iconv() または UConverter
のいずれかで置き換えることができます。

money_format() 関数

money_format() 関数は推奨されません。 intl の NumberFormatter 機能に置き換えられました。

ezmlm_hash() 関数

ezmlm_hash() 関数の使用は推奨されません。

restore_include_path() 関数

restore_include_path() 関数の使用は推奨されません。 ini_restore('include_path') に置き換えることができます。

Implode 関数の、歴史的なパラメータ順序

implode() 関数に逆の順番でパラメータを渡すのは推奨されなくなりました。implode($parts, $glue) ではなく、 implode($glue, $parts) を使ってください。

COM

大文字小文字を区別せず、定数を登録することで型のライブラリをインポートすることは推奨されません。

Filter

FILTER_SANITIZE_MAGIC_QUOTES は推奨されません。 FILTER_SANITIZE_ADD_SLASHES を代わりに使って下さい。

マルチバイト文字列

mb_ereg_replace() に文字列でないパターンを渡すことは推奨されません。現状は、文字列でないパターンは ASCII コードポイントと解釈されます。PHP 8 では、パターンは文字列として解釈されるようになります。

mb_strrpos() 関数に、3番目のパラメーターとしてエンコーディングを渡すのは推奨されません。代わりに 0から始まるオフセットを渡すか、4番目のパラメーターとしてエンコーディングを渡すようにします。

LDAP

ldap_control_paged_result_response() と
ldap_control_paged_result() 関数は推奨されません。
ページングの制御は、ldap_search()
を代わりに使うことで行なえます。

Reflection

ReflectionType::__toString() を呼び出すと、推奨されない警告が生成されるようになりました。このメソッドは ReflectionNamedType::getName() を使うことが好ましいために、PHP 7.1 から推奨されていませんでしたが、技術的な理由によって、推奨されない警告をこれまで発生させてきませんでした。

Reflection クラスの全ての export() メソッドは推奨されなくなりました。次のようにして、Reflection オブジェクトを生成し、string に変換するようにして下さい:

<?php
// ReflectionClass::export(Foo::class, false) is:
echo new ReflectionClass(Foo::class), "\n";

// $str = ReflectionClass::export(Foo::class, true) is:
$str = (string) new ReflectionClass(Foo::class);
?>

Socket

glibc で推奨されなくなったため、socket_addrinfo_lookup() 関数の AI_IDN_ALLOW_UNASSIGNED と AI_IDN_USE_STD3_ASCII_RULES フラグの使用は推奨されません。


削除された拡張モジュール

以下の拡張モジュールは、PECLに移され、PHPの配布物からは削除されました。これらの拡張モジュールのPECL版は、ユーザーが必要とすれば作られるでしょう。

  • Firebird/Interbase - InterBase と/または Firebird ベースのデータベースへのアクセスは、PDO Firebird ドライバで利用可能です。
  • Recode
  • WDDX


その他の変更

パフォーマンスの向上

PHP コア

array_key_exists() 関数で使うための特別な VM opcode が追加されました。これにより、これが静的に解決される場合のパフォーマンスが向上します。名前空間内にあるコードは、 \array_key_exists() を書くか、明示的に関数を import する必要があるかもしれません。

正規表現 (Perl互換)

UTF-8モード("u" 修飾子) が同じ文字列に対して繰り返し呼ばれた(但し異なるオフセットで呼ばれる)場合、UTF-8 として正しいかどうかの確認は一度だけ行われるようになります。

INIファイルのハンドリングに対する変更

zend.exception_ignore_args は、 例外から生成されたスタックトレースに引数を含めたり、除外したりするための新しい INIディレクティブです。

opcache.preload_user は、指定されなければ root として実行されてしまう場合(これはセキュリティ上の理由で禁止されています) に、事前ロードされたコードを実行するユーザーアカウントを指定するための新しいINIディレクティブです。

pkg-config への移行

たくさんの拡張モジュールが、ライブラリへの依存性を検知するために、明示的に pkg-config に移行しました。一般的には、このことは 以前 --with-foo-dir=DIR に似た指定をしていたのが、--with-foo が使うだけで済むようになるということです。 カスタムライブラリのパスは PKG_CONFIG_PATH にディレクトリを追加するか、明示的に FOO_CFLAGS と FOO_LIBS でコンパイルオプションを指定することができます。

以下の拡張モジュールや SAPI が影響を受けます:

  • CURL:
    • --with-curl は、ディレクトリを受け入れません。
  • Enchant:
    • --with-enchant は、ディレクトリを受け入れません。
  • FPM:
    • --with-fpm-systemd オプションは、pkg-config が libsystem をチェックする用途だけに使われるようになりました。libsystemd の最小バージョンは 209 です。
  • GD:
    • --with-gd オプションは --enable-gd (拡張モジュール全部を有効にする場合) と --with-external-gd (バンドルされたものではなく、外部のlibgdを使う場合) になりました。
    • --with-png-dir は削除されました。libpng はビルドに必須です。
    • --with-zlib-dir は削除されました。zlib はビルドに必須です。
    • --with-freetype-dir は、--with-freetype になりました。
    • --with-jpeg-dir は、--with-jpeg になりました。
    • --with-webp-dir は、--with-webp になりました。
    • --with-xpm-dir は、 --with-xpm になりました。
  • IMAP:
    • --with-kerberos-systemd は、ディレクトリを受け入れません。
  • Intl:
    • --with-icu-dir は削除されました。 --enable-intl が渡された場合、libicu が常に必須になります。
  • LDAP:
    • --with-ldap-sasl は、ディレクトリを受け入れません。
  • Libxml:
    • --with-libxml-dir は削除されました。
    • --enable-libxml は、 --with-libxml になりました。
    • --with-libexpat-dir は --with-expat にリネームされ、ディレクトリを受け入れなくなりました。
  • Litespeed:
    • --with-litespeed は、 --enable-litespeed になりました。
  • Mbstring:
    • --with-onig オプションは削除されました。 --disable-mbregex が指定されない限り、libonig が必須です。
  • ODBC:
    • --with-iodbc は、ディレクトリを受け入れません。
    • ディレクトリを指定せずに --with-unixODBC を使うと、pkg-config を利用するようになります(望ましい)。libodbc.pc がない古いバージョンのために、ディレクトリもまだ受け入れ可能です。
  • OpenSSL:
    • --with-openssl は、ディレクトリを受け入れません。
  • PCRE:
    • --with-pcre-regex オプションは削除されました。 代わりに、バンドルされたものではなく、外部のPCREライブラリを使うために --with-external-pcre が提供されます。
  • PDO_SQLite:
    • --with-pdo-sqlite は、ディレクトリを受け入れません。
  • Readline:
    • --with-libedit は、ディレクトリを受け入れません。
  • Sodium:
    • --with-sodium は、ディレクトリを受け入れません。
  • SQLite3:
    • --with-sqlite3 は、ディレクトリを受け入れません。
  • XSL:
    • --with-xsl は、ディレクトリを受け入れません。
  • Zip:
    • --with-libzip は削除されました。
    • --enable-zip は、 --with-zip になりました。

CSV のエスケープ

fputcsv(),
fgetcsv(),
SplFileObject::fputcsv(),
SplFileObject::fgetcsv() および
SplFileObject::setCsvControl()
は、 $escape
パラメータに空文字列を受け入れるようになりました。
空文字列を指定すると、(RFC 4180 に準拠していない) 独自仕様の PHP のエスケープ機構が無効になります。

str_getcsv() 関数の振る舞いが適切に調整されました(正確には、空文字列がデフォルトを使うことに等しくなります)

SplFileObject::getCsvControl() は、3番目の配列要素で空文字列を返すように適切に調整されました。

データのフィルタリング

filter 拡張モジュールは、 Unix でビルドする際に --with-pcre-dir が不要になり、 ./configure コマンドで共有ライブラリとして確実にビルドされるようになりました。

GD

libgd にバンドルされた imagecropauto() 関数の振る舞いが、システムの libgd と同じになりました。

  • IMG_CROP_DEFAULT は、 IMG_CROP_SIDES にフォールバックしなくなりました。
  • Threshold-cropping は、システムの libgd のアルゴリズムを使うようになりました。

imagecropauto() 関数の $mode 引数のデフォルト値が IMG_CROP_DEFAULT に変更されました。つまり、 -1 を渡すことは推奨されなくなりました。

imagescale() 関数が、$new_width に -1 を渡すことによって、 固定の高さのアスペクト比をサポートするようになりました。

HASH メッセージダイジェストフレームワーク

hash 拡張モジュールを無効にすることはできなくなり、PHP ビルドに必須の部分として扱われます。 date 拡張モジュールも同様です。

国際化関数

intl 拡張モジュールは、ICU 50.1 以降が必須になりました。

ResourceBundle は、Countable を新たに実装しました。

LDAP

nsldap と umich_ldap のサポートは削除されました。

Libxml

すべての libxmlベースの拡張モジュールは libxml 2.7.6 以降が必須になりました。

マルチバイト文字列

oniguruma ライブラリは PHP本体にバンドルされなくなりました。代わりに、libonig がシステムで利用可能になっている必要があります。mbregex コンポーネントを無効にするために、--disable-mbregex オプションが代わりに利用できます。

OPcache

--disable-opcache-file と --enable-opcache-file オプションは削除され、opcache.file_cache INIディレクティブに置き換えられました。

パスワードハッシュ

password_hash() と password_needs_rehash() 関数は、 $algo に nullable な string と int を受け入れるようになりました。

PEAR

PEAR (PECL を含む) のインストールは、デフォルトで無効になりました。configure オプション --with-pear を使うことで明示的に有効にできますが、このオプションは推奨されなくなり、将来的に削除される可能性があります。

リフレクション

ReflectionClass, ReflectionFunction, ReflectionMethod, ReflectionObject, ReflectionProperty クラスの修飾子の定数の数値 (IS_ABSTRACT, IS_DEPRECATED, IS_EXPLICIT_ABSTRACT, IS_FINAL, IS_IMPLICIT_ABSTRACT, IS_PRIVATE, IS_PROTECTED, IS_PUBLIC, IS_STATIC) が変更されました。

SimpleXML

SimpleXMLElement クラスが、新たに Countable を実装しました。

SQLite3

バンドルされていた libsqlite は削除されました。 SQLite3 拡張モジュールをビルドするには、libsqlite3 3.7.4 以降が必須になりました。 PDO_SQLite 拡張モジュールをビルドするには、libsqlite3 3.5.0 以降が必須になりました。

SQLite3, SQLite3Stmt および SQLite3Result クラスのシリアル化とその復元は、明示的に禁止されました。 以前は、これらのクラスのシリアル化は可能でしたが、それを 復元すると不安定なオブジェクトを返していました。

@param 記法は SQLクエリパラメータを示すために使えるようになりました。

Zip

バンドルされていた libzip ライブラリは削除されました。 zip 拡張モジュールをビルドするには、libzip >= 0.11 が必要になっています。


Windows のサポート

configure フラグ

configure コマンドは、CFLAGS や LDFLAGS を環境変数と見なすようになりました。

CTRLキーの扱い

sapi_windows_set_ctrl_handler() 関数でハンドラを設定することで、コンソールにおける CTRL+C や CTRL+BREAK をキャッチできるようになりました。

Windows における proc_open() 関数は、"create_process_group" オプションを新たに渡せるようになりました。これは、子プロセスが CTRLイベントをハンドルする場合に必須です。

OPcache

OPcache は、opcache.cache_id INIディレクティブを設定することで、ユーザー単位で別々のキャッシュを、任意の数だけ持つことをサポートしました。同一のキャッシュIDとユーザーを持つ全てのプロセスは、同一のOPcacheインスタンスを共有します。

stat

stat 関数の実装がリファクタリングされました。

  • inode番号 が取得可能になりました。この値は NTFS のファイルインデックス をベースにしています。
  • デバイス番号は、ボリュームのシリアル番号をベースにするようになりました。

これらの値は、両方システムから取得され、64bitシステムで与えられるそのままの値であることに注意して下さい。32bitのシステムでは、これらの値はオーバーフローする可能性があるため、値は偽物です。

libsqlite3

libsqlite3 は、 php_sqlite3.dll と php_pdo_sqlite.dll に静的にコンパイルされず、libsqlite3.dll として利用できるようになりました。 SQLite3 と PDO_SQLITE のインストール手順をそれぞれ参照ください。


PHP 7.2.x から PHP 7.3.x への移行

目次

  • 新機能
  • 新しく追加された関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 7.3.x で推奨されなくなる機能
  • その他の変更
  • Windows のサポート

このマイナーバージョンアップには数多くの 新機能 があります。また、互換性がない変更 が多少あるので、実運用環境の PHP をこのバージョンにあげる前にはテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.0.x, 7.1.x, 7.2.x.


新機能

PHP コア

ヒアドキュメントと Nowdoc構文 がより柔軟に

文字列を閉じるマーカーの後に、セミコロンや改行文字を続ける必要はなくなりました。 それに加えて、文字列を閉じるマーカーはインデントされていても構いません。 この場合、インデントは文字列の全ての行から取り除かれます。

配列へ分割して代入する操作が、リファレンスへの代入をサポート

配列の要素に分割して代入する操作が、[&$a, [$b, &$c]] = $d という文法を用いて、リファレンスへの代入をサポートしました。 同じ操作は、list() 関数でもサポートされています。

instanceof 演算子が、リテラルを受け入れるように

instanceof 演算子が、最初のオペランドにリテラルを受け入れるようになりました。この場合、結果は常に false を返します。

いくつかのコンパイルエラーが、CompileError 例外に

CompileError 例外が新たに追加されました。これは ParseError クラスを継承しています。 少ない数ですが、いくつかのコンパイルエラーが致命的なエラーを生成せず、CompileError 例外をスローするようになります。 現状は、この変更は TOKEN_PARSE モードで token_get_all() が実行された場合にスローされる可能性があるコンパイルエラーだけに影響しますが、将来より多くのエラーがこの例外に変換される可能性があります。

関数やメソッド呼び出しの後に、カンマを付けられるように

関数やメソッド呼び出しの後に、カンマを付けられるようになりました。

Argon2id のサポート

configure コマンドに --with-password-argon2[=dir] オプションを与えることで、Argon2i と Argon2id ハッシュが password_hash(), password_verify(), password_get_info(), および password_needs_rehash() でサポートされるようになります。 PASSWORD_ARGON2ID を使うことで、パスワードはハッシュ化され、検証されます。 password_*() 関数で Argon2i と Argon2id のサポートを使うには、PHP を libargon2 ? 20161029 とリンクする必要があります。

php-fpm

FPM のロギングをカスタマイズするために、新しいオプションが追加されました。

log_limit
このグローバルオプションは、1024文字以上のログを改行なしにロギングするために、ログの長さの限界を設定するために使います。これにより、様々な改行の問題も修正されます。
log_buffering
このグローバルオプションによって、追加のバッファリングなしに、実験的なロギングを行うことができます。
decorate_workers_output
このプールオプションを使うことで、 catch_workers_output が有効になった場合に、ワーカーの出力をデコレートする機能を無効にできます。

BC Math 関数

bcscale() 関数は、現在使われている基数を取得する getter としても使えるようになりました。

LDAP

LDAPコントロールの完全なサポートが LDAP クエリ関数と ldap_parse_result() 関数に追加されました:

  • コントロールをサーバーに送信するために $controls
パラメータが ldap_add(),
ldap_mod_replace(), ldap_mod_add(),
ldap_mod_del(), ldap_rename(),
ldap_compare(), ldap_delete(),
ldap_modify_batch(),
ldap_search(), ldap_list() および
ldap_read() 関数に追加されました。
  • サーバーからコントロールを取得するために、出力パラメータ $controls が ldap_parse_result() 関数に追加されました。
  • ldap_get_option() と ldap_set_option() 関数の LDAP_OPT_SERVER_CONTROLS と LDAP_OPT_CLIENT_CONTROLS のサポートが修正されました。

マルチバイト文字列関数

完全なケースマッピングとケースフォールディングのサポート

完全なケースマッピングとケースフォールディングのサポートが追加されました。 シンプルな大文字小文字のマッピングと異なり、完全なケースマッピング では、文字列の長さが変わる場合があります。たとえば、以下のようになります:

<?php
mb_strtoupper("Strase");
// Produces STRAsE on PHP 7.2
// Produces STRASSE on PHP 7.3
?>
異なるケースマッピングやケースフォールディング のモードは、mb_convert_case() 関数で利用できます:
  • MB_CASE_LOWER (mb_strtolower() で使われています)
  • MB_CASE_UPPER (mb_strtoupper() で使われています)
  • MB_CASE_TITLE
  • MB_CASE_FOLD
  • MB_CASE_LOWER_SIMPLE
  • MB_CASE_UPPER_SIMPLE
  • MB_CASE_TITLE_SIMPLE
  • MB_CASE_FOLD_SIMPLE (大文字小文字を区別しない操作で使います)
無条件に、言語に中立かつ完全なケースマッピングのみが行われます。

大文字小文字を区別しない文字列操作は、ケースフォールディングを使う

大文字小文字を区別しない文字列操作は、比較の際にケースマッピングではなく、ケースフォールディング を使うようになりました。 これは、より多くの文字が (大文字小文字を区別しないという意味で) 等価と見做されるようになったことを意味します。

MB_CASE_TITLE による Title-Case 変換

mb_convert_case() 関数を MB_CASE_TITLE と使うと、Unicodeプロパティ由来の大文字小文字の区別の有無に基づいて、Title-case 変換を行うようになりました。この変更は特に、クォートやアポストロフィーのハンドリングも改善します。

Unicode 11 のサポート

マルチバイト文字列 のデータテーブルは、Unicode 11 をサポートするように更新されました。

長い文字列のサポート

マルチバイト文字列関数 は 2GB 以上の文字列を正しくサポートするようになりました。

パフォーマンスの向上

マルチバイト文字列 拡張モジュールのパフォーマンスが全体的に大きく向上しました。大文字小文字のケースの変換関数で、一番大きな改善が見られます。

名前付きキャプチャのサポート

mb_ereg_* 関数は、名前付きキャプチャをサポートしました。 mb_ereg() のようなマッチング関数は グループ番号と名前の両方を使って名前付きキャプチャを返します。これは PCRE に似た動作です:

<?php
mb_ereg('(?<word>\w+)', '国', $matches);
// => [0 => "国", 1 => "国", "word" => "国"];
?>
これに加えて、 mb_ereg_replace() 関数は 置換文字列で名前付きキャプチャを参照するために \k<> と \k'' 記法をサポートしました:
<?php
mb_ereg_replace('\s*(?<word>\w+)\s*', "_\k<word>_\k'word'_", ' foo ');
// => "_foo_foo_"
?>
\k<> and \k'' 記法は、数値参照にも使えます。これは、9以上のグループ番号でも動作します。

Readline

completion_append_character と completion_suppress_append オプションのサポートが readline_info() 関数に追加されました。 これらのオプションは PHP が (libedit ではなく) libreadline とリンクされた場合のみ利用できます。


新しく追加された関数

PHP コア

  • array_key_first()
  • array_key_last()
  • gc_status()
  • hrtime()
  • is_countable()
  • net_get_interfaces()

FastCGI Process Manager(FPM)

  • fpm_get_status()

日付と時刻

  • DateTime::createFromImmutable()

GNU Multiple Precision(GMP)

  • gmp_binomial()
  • gmp_kronecker()
  • gmp_lcm()
  • gmp_perfect_power()

国際化関数

  • Normalizer::getRawDecomposition()
  • normalizer_get_raw_decomposition()
  • Spoofchecker::setRestrictionLevel()

LDAP

  • ldap_add_ext()
  • ldap_bind_ext()
  • ldap_delete_ext()
  • ldap_exop_refresh()
  • ldap_mod_add_ext()
  • ldap_mod_replace_ext()
  • ldap_mod_del_ext()
  • ldap_rename_ext()

OpenSSL

  • openssl_pkey_derive()

Sockets

  • socket_wsaprotocol_info_export()
  • socket_wsaprotocol_info_import()
  • socket_wsaprotocol_info_release()


新しいグローバル定数

PHP コア

  • PASSWORD_ARGON2ID

CURL

  • CURLAUTH_BEARER
  • CURLAUTH_GSSAPI
  • CURLE_WEIRD_SERVER_REPLY
  • CURLINFO_APPCONNECT_TIME_T
  • CURLINFO_CONNECT_TIME_T
  • CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
  • CURLINFO_CONTENT_LENGTH_UPLOAD_T
  • CURLINFO_FILETIME_T
  • CURLINFO_HTTP_VERSION
  • CURLINFO_NAMELOOKUP_TIME_T
  • CURLINFO_PRETRANSFER_TIME_T
  • CURLINFO_PROTOCOL
  • CURLINFO_PROXY_SSL_VERIFYRESULT
  • CURLINFO_REDIRECT_TIME_T
  • CURLINFO_SCHEME
  • CURLINFO_SIZE_DOWNLOAD_T
  • CURLINFO_SIZE_UPLOAD_T
  • CURLINFO_SPEED_DOWNLOAD_T
  • CURLINFO_SPEED_UPLOAD_T
  • CURLINFO_STARTTRANSFER_TIME_T
  • CURLINFO_TOTAL_TIME_T
  • CURL_LOCK_DATA_CONNECT
  • CURL_LOCK_DATA_PSL
  • CURL_MAX_READ_SIZE
  • CURLOPT_ABSTRACT_UNIX_SOCKET
  • CURLOPT_DISALLOW_USERNAME_IN_URL
  • CURLOPT_DNS_SHUFFLE_ADDRESSES
  • CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
  • CURLOPT_HAPROXYPROTOCOL
  • CURLOPT_KEEP_SENDING_ON_ERROR
  • CURLOPT_PRE_PROXY
  • CURLOPT_PROXY_CAINFO
  • CURLOPT_PROXY_CAPATH
  • CURLOPT_PROXY_CRLFILE
  • CURLOPT_PROXY_KEYPASSWD
  • CURLOPT_PROXY_PINNEDPUBLICKEY
  • CURLOPT_PROXY_SSLCERT
  • CURLOPT_PROXY_SSLCERTTYPE
  • CURLOPT_PROXY_SSL_CIPHER_LIST
  • CURLOPT_PROXY_SSLKEY
  • CURLOPT_PROXY_SSLKEYTYPE
  • CURLOPT_PROXY_SSL_OPTIONS
  • CURLOPT_PROXY_SSL_VERIFYHOST
  • CURLOPT_PROXY_SSL_VERIFYPEER
  • CURLOPT_PROXY_SSLVERSION
  • CURLOPT_PROXY_TLS13_CIPHERS
  • CURLOPT_PROXY_TLSAUTH_PASSWORD
  • CURLOPT_PROXY_TLSAUTH_TYPE
  • CURLOPT_PROXY_TLSAUTH_USERNAME
  • CURLOPT_REQUEST_TARGET
  • CURLOPT_SOCKS5_AUTH
  • CURLOPT_SSH_COMPRESSION
  • CURLOPT_SUPPRESS_CONNECT_HEADERS
  • CURLOPT_TIMEVALUE_LARGE
  • CURLOPT_TLS13_CIPHERS
  • CURLPROXY_HTTPS
  • CURLSSH_AUTH_GSSAPI
  • CURL_SSLVERSION_MAX_DEFAULT
  • CURL_SSLVERSION_MAX_NONE
  • CURL_SSLVERSION_MAX_TLSv1_0
  • CURL_SSLVERSION_MAX_TLSv1_1
  • CURL_SSLVERSION_MAX_TLSv1_2
  • CURL_SSLVERSION_MAX_TLSv1_3
  • CURL_SSLVERSION_TLSv1_3
  • CURL_VERSION_ALTSVC (PHP 7.3.6 以降)
  • CURL_VERSION_ASYNCHDNS
  • CURL_VERSION_BROTLI
  • CURL_VERSION_CONV
  • CURL_VERSION_CURLDEBUG (PHP 7.3.6 以降)
  • CURL_VERSION_DEBUG
  • CURL_VERSION_GSSAPI
  • CURL_VERSION_GSSNEGOTIATE
  • CURL_VERSION_HTTPS_PROXY
  • CURL_VERSION_IDN
  • CURL_VERSION_LARGEFILE
  • CURL_VERSION_MULTI_SSL
  • CURL_VERSION_NTLM
  • CURL_VERSION_NTLM_WB
  • CURL_VERSION_PSL (PHP 7.3.6 以降)
  • CURL_VERSION_SPNEGO
  • CURL_VERSION_SSPI
  • CURL_VERSION_TLSAUTH_SRP

データのフィルタリング

  • FILTER_SANITIZE_ADD_SLASHES

JSON

  • JSON_THROW_ON_ERROR

LDAP

  • LDAP_CONTROL_ASSERT
  • LDAP_CONTROL_MANAGEDSAIT
  • LDAP_CONTROL_PROXY_AUTHZ
  • LDAP_CONTROL_SUBENTRIES
  • LDAP_CONTROL_VALUESRETURNFILTER
  • LDAP_CONTROL_PRE_READ
  • LDAP_CONTROL_POST_READ
  • LDAP_CONTROL_SORTREQUEST
  • LDAP_CONTROL_SORTRESPONSE
  • LDAP_CONTROL_PAGEDRESULTS
  • LDAP_CONTROL_AUTHZID_REQUEST
  • LDAP_CONTROL_AUTHZID_RESPONSE
  • LDAP_CONTROL_SYNC
  • LDAP_CONTROL_SYNC_STATE
  • LDAP_CONTROL_SYNC_DONE
  • LDAP_CONTROL_DONTUSECOPY
  • LDAP_CONTROL_PASSWORDPOLICYREQUEST
  • LDAP_CONTROL_PASSWORDPOLICYRESPONSE
  • LDAP_CONTROL_X_INCREMENTAL_VALUES
  • LDAP_CONTROL_X_DOMAIN_SCOPE
  • LDAP_CONTROL_X_PERMISSIVE_MODIFY
  • LDAP_CONTROL_X_SEARCH_OPTIONS
  • LDAP_CONTROL_X_TREE_DELETE
  • LDAP_CONTROL_X_EXTENDED_DN
  • LDAP_CONTROL_VLVREQUEST
  • LDAP_CONTROL_VLVRESPONSE

マルチバイト文字列

  • MB_CASE_FOLD
  • MB_CASE_LOWER_SIMPLE
  • MB_CASE_UPPER_SIMPLE
  • MB_CASE_TITLE_SIMPLE
  • MB_CASE_FOLD_SIMPLE

OpenSSL

  • STREAM_CRYPTO_PROTO_SSLv3
  • STREAM_CRYPTO_PROTO_TLSv1_0
  • STREAM_CRYPTO_PROTO_TLSv1_1
  • STREAM_CRYPTO_PROTO_TLSv1_2

PostgreSQL

  • PGSQL_DIAG_SCHEMA_NAME
  • PGSQL_DIAG_TABLE_NAME
  • PGSQL_DIAG_COLUMN_NAME
  • PGSQL_DIAG_DATATYPE_NAME
  • PGSQL_DIAG_CONSTRAINT_NAME
  • PGSQL_DIAG_SEVERITY_NONLOCALIZED


下位互換性のない変更点

PHP コア

ヒアドキュメント/Nowdoc の終了ラベルの解釈

ヒアドキュメント/Nowdoc の文法が柔軟になった ことにより、本体の内部に終了ラベルが含まれた ドキュメンテーション文字列は、エラーが発生するか、解釈の振る舞いが変わる可能性があります。 たとえば、以下のような場合です:

<?php
$str = <<<FOO
abcdefg
 FOO
FOO;
?>
インデントされた FOO が入ったとしても、以前は特別な意味は何もありませんでした。 ですが、このバージョンからは ヒアドキュメントの終了と解釈され、 後に続く FOO; が syntax error になるでしょう。 この問題は、文字列の内容に決して含まれることのない終了ラベルを選ぶことで常に回避できます。

switch の制御フローを変更する continue 文は警告が出る

switch の制御フローを変更することを狙った continue 文は、警告が出るようになりました。 PHP では、このような continue 文は break と同等で、他のプログラミング言語では continue 2 と同じように振る舞うのとは対照的です。

<?php
while ($foo) {
switch ($bar) {
case "baz":
continue;
// Warning: "continue" targeting switch is equivalent to
// "break". Did you mean to use "continue 2"?
}
}
?>

ArrayAccess を実装したオブジェクトに対する、 数値形式の文字列キーの解釈が厳密に

$obj が ArrayAccess を実装したオブジェクトで、 "123" が数値の文字列リテラルだった場合、 この "123" は暗黙のうちに整数型に変換されなくなりました。 つまり、$obj->offsetGet(123) ではなく、 $obj->offsetGet("123") がコールされるようになります。 これは、リテラルでない値の既存の振る舞いに一致します。 配列の振る舞いには全く影響しません。 配列については、数値の文字列リテラルのキーは、整数型に暗黙のうちに変換され続けます。

static なプロパティが参照の代入によって分裂しなくなった

PHP では、子クラスで明示的にオーバーライドされない限り、static なプロパティが継承関係にあるクラスの間で共有されます。しかし、 実装上の副作用により、参照を代入することによって、static なプロパティが異なる値になる可能性がありました。こうした抜け穴がこのバージョンでは修正されました。

<?php
class Test {
public static $x = 0;
}
class Test2 extends Test { }

Test2::$x = &$x;
$x = 1;

var_dump(Test::$x, Test2::$x);
// Previously: int(0), int(1)
// Now: int(1), int(1)
?>

配列から返される参照とプロパティのアクセスは、即座に分割される

配列から返された参照と、プロパティのアクセスは、 アクセスの一部として別に扱われるようになりました。 これは、配列へのアクセスと、配列の値を使う間に、値を変更できなくなったということです。

<?php
$arr = [1];
$ref =& $arr[0];
var_dump($arr[0] + ($arr[0] = 2));
// Previously: int(4), Now: int(3)
?>
これにより、参照と参照でない値の振る舞いが一貫したものになります。 単一の式の中で値を読んだり書いたりする場合の振る舞いは未定義のままであり、 将来再び動作が変更される可能性があることに注意して下さい。

Traversable への引数のアンパックを整数でないキーで行うことはサポートされない

Traversable への引数のアンパックを整数でないキーで行うコードは動作しなくなりました。 次のようなコードが、 PHP 5.6 から 7.2 の間は偶然動いていました。

<?php
function foo(...$args) {
var_dump($args);
}
function gen() {
yield 1.23 => 123;
}
foo(...gen());
?>

その他雑多な変更

ext_skel ユーティリティは、 新しいオプションで完全に再設計され、いくつかの古いオプションは削除されました。 このユーティリティは、PHP で書かれており、それ以外の外部への依存はありません。

BeOS のサポートが削除されました。

EH_THROW モードの、警告を自動的に例外に変換することで スローされる例外(e.g. いくつかの DateTime 例外) は、error_get_last() 関数の状態を収集しなくなりました。 そうした例外は、手動でスローされる例外と同じように動くようになります。

TypeError は、integer と boolean ではなく、 それぞれ int と bool を誤った型として報告するようになります。

compact() 関数に渡された未定義の値は、NOTICEレベルの警告を発生させるようになります。

getimagesize() 関数と関連する関数は、BMP画像の MIME Type を image/x-ms-bmp ではなく image/bmp と報告するようになりました。 なぜなら、後者は IANA に登録されているから (» RFC 7903 を参照) です。

stream_socket_get_name() 関数は、 ブラケットでラップされた IPv6 アドレスを返すようになります。 たとえば、"::1:1337" ではなく、 "[::1]:1337" を返すようになるでしょう。

BCMath

BCMath 関数 でスローされる全ての例外は、 PHP のエラーハンドリングの機構を使うようになりました。 以前は、いくつかのエラーが stderr に直接出力されていました。

bcmul() および bcpow() 関数は、指定された精度の数値を返すようになりました。 以前は、返される値の後ろが、0埋めされることで省略される可能性がありました。

IMAP, POP3 および NNTP

rsh/ssh ログインはデフォルトで無効になりました。 これらを有効にしたい場合、imap.enable_insecure_rsh を使って下さい。 IMAPライブラリは rsh/ssh コマンドに渡す前にメールボックス名をフィルタしないので、 rsh/ssh を有効にした状態で この関数に信頼できないデータを渡すことは安全ではありません。

マルチバイト文字列

名前付きキャプチャのサポートが追加されたことにより、 mb_ereg_*() におけるパターンに名前付きキャプチャを使うと、これまでと異なる振る舞いをします。 特に、名前付きキャプチャが matches の一部になった場合、 mb_ereg_replace() はこれを追加の文法に従って解釈します。 さらに詳しい情報は、名前付きキャプチャ を参照ください。

MySQL 改良版拡張モジュール

プリペアドステートメント が、カラムに小数の桁数を指定する(e.g. マイクロ秒を使う場合 TIMESTAMP(6) のようにする) ことによって、 DATETIME, TIME および TIMESTAMP 型の秒の小数部を報告するようになりました。 以前のバージョンでは、秒の小数部は戻り値から単に省略されていました。

MySQL関数 (PDO_MYSQL)

プリペアドステートメント が、カラムに小数の桁数を指定する(e.g. マイクロ秒を使う場合 TIMESTAMP(6) のようにする) ことによって、DATETIME, TIME および TIMESTAMP 型の秒の小数部を報告するようになりました。 以前のバージョンでは、秒の小数部は戻り値から単に省略されていました。 この変更は、PDO_MYSQL のプリペアドステートメントをエミュレートする機能を無効にしていた場合 (e.g つまり、MySQLネイティブなプリペアの機能を使っていた場合) にのみ影響があることに注意して下さい。 PDO::ATTR_EMULATE_PREPARES=true (これはデフォルトです) にした接続を使う Statement は影響を受けず、 既に適切な秒の小数部をエンジンから取得していました。

リフレクション

リフレクション を文字列にエクスポートした場合、integer と boolean ではなく、int と bool をそれぞれ使うようになりました。

Standard PHP Library (SPL)

SPL autoloader が例外をスローした場合、後に続く autoloader は実行されなくなりました。以前は、全ての autoloader が実行され、例外がチェインしていました。

SimpleXML

数学的な演算 に SimpleXML オブジェクトが含まれていた場合、テキストが int または float のうち、より適切なものとして扱われるようになりました。 以前は値が意図せず int として扱われた場合がありました。

外部から入力されるCookie

PHP 7.3.23 以降は、セキュリティ上の理由により、 外部から入力される Cookie の 名前 はurlデコードされなくなりました。


PHP 7.3.x で推奨されなくなる機能

PHP コア

大文字小文字を区別しない定数

大文字小文字を区別せず、定数を宣言することは推奨されません。 define() 関数の第3引数に true を渡すと、推奨されない警告が生成されるようになりました。宣言された定数と異なるケースで定数を使うことも推奨されません。

名前空間の中で assert() 関数の宣言

名前空間の中で assert() と呼ばれる関数を宣言することは推奨されません。 assert() 関数は PHPエンジンによって特別扱いされることが意図されているため、名前空間の中で同じ関数を宣言されると、一貫しない振る舞いに繋がる可能性があるからです。

文字列でない needle 引数による文字列の探索

文字列でない needle 引数で文字列検索関数を使うことは推奨されません。 将来的には、needle 引数は ASCII コードポイントではなく、文字列として解釈されるようになります。 あなたが意図する振る舞いに応じて、明示的に needle 引数を文字列にキャストするか、 chr() 関数を明示的に呼び出すべきです。 影響を受ける関数は以下のとおりです:

  • strpos()
  • strrpos()
  • stripos()
  • strripos()
  • strstr()
  • strchr()
  • strrchr()
  • stristr()

string.strip_tags ストリームフィルタ

fgetss() 関数と strip_tags ストリームフィルタ は推奨されません。 このことは SplFileObject::fgetss() メソッドと gzgetss() 関数にも影響します。

データのフィルタリング

FILTER_FLAG_SCHEME_REQUIRED や FILTER_FLAG_HOST_REQUIRED を明示的に使うことは推奨されなくなりました。これらは FILTER_VALIDATE_URL に含まれています。

画像処理と GD

image2wbmp() 関数は推奨されなくなりました。

国際化関数

PHP が ICU バージョン56以上とリンクされた状態で Normalizer::NONE を使うと、推奨されない警告が発生するようになりました。

マルチバイト文字列

以下のドキュメントに記されていない mbereg_*() エイリアスは推奨されなくなりました。 対応する mb_ereg_*() 関数を使ってください。

  • mbregex_encoding()
  • mbereg()
  • mberegi()
  • mbereg_replace()
  • mberegi_replace()
  • mbsplit()
  • mbereg_match()
  • mbereg_search()
  • mbereg_search_pos()
  • mbereg_search_regs()
  • mbereg_search_init()
  • mbereg_search_getregs()
  • mbereg_search_getpos()
  • mbereg_search_setpos()

ODBC と DB2 関数 (PDO_ODBC)

ini 設定 pdo_odbc.db2_instance_name は正式に推奨されなくなりました。ドキュメントでは、PHP 5.1.1 以降から推奨されないとされていました。


その他の変更

PHP コア

set(raw)cookie 関数は $option 引数を受け入れるように

setcookie() および setrawcookie() 関数は、次のようなシグネチャもサポートするようになりました:

setcookie(string $name, string $value = "", array $options = []): bool
$options は "expires", "path", "domain", "secure", "httponly" および "samesite" をキーとして受け付ける連想配列です。

新しい syslog INI ディレクティブ

error_log が syslog に設定された場合、 ロギングをカスタマイズするため、次の ini ディレクティブが追加されました: syslog:

syslog.facility
どのタイプのプログラムがメッセージをロギングするかを指定します
syslog.filter
ログメッセージをフィルタするために、 サポートされているフィルタタイプを指定します。 サポートされているのは、all, no-ctrl そして ascii です。 PHP 7.3.8 以降では、 それより前のバージョンでの振る舞いを復元する raw も使えます。 このフィルタは、syslog() をコールした際にも影響します。
syslog.ident
メッセージの先頭に付加される ident 文字列を指定します。

ガベージコレクション

cyclic GC が改良されました。かなりのパフォーマンスの向上に繋がる可能性があります。

雑多な変更

var_export() 関数は、 存在しないメソッド stdClass::__setState() を使わず、 オブジェクトにキャストされた配列 ((object) array( ... )) として stdClass を エクスポートするようになりました。

debug_zval_dump() 関数は、再帰的な配列やオブジェクトを表示する方法が、 var_dump() と同じになるように変更されました。 そうした配列やオブジェクトは、もはや二度表示されません。

array_push() および array_unshift() 関数は、単一の引数でも呼び出せるようになりました。これは spread演算子と共に使うと特に便利です。

対話的なPHPデバッガ

使われていなかった定数 PHPDBG_FILE, PHPDBG_METHOD, PHPDBG_LINENO および PHPDBG_FUNC が削除されました。

php-fpm

getallheaders() 関数も利用可能になりました。

CURL

libcurl ? 7.15.5 が必須になりました。

データのフィルタリング

FILTER_VALIDATE_FLOAT 定数が thousand オプションもサポートしました。 これにより、受け入れ可能な千単位のセパレーター文字を指定できます。 デフォルト ("',.") は、以前のPHPのバージョンと完全に互換性があります。

magic_quotes フィルタ (FILTER_SANITIZE_MAGIC_QUOTES) のエイリアスとして FILTER_SANITIZE_ADD_SLASHES が追加されました。 magic_quotes フィルタは、将来のPHPで削除される予定です。

FTP

デフォルトの転送モードが binary になりました。

国際化関数

PHP が ICU 56 以降とリンクされた場合、Normalizer::NONE は推奨されません。

NFKC_Casefold 正規化のために、 Normalizer::normalize() メソッドの引数として normalizer::form_kc_cf が追加されました。 これは、ICU 56 以降で利用可能です。

JSON

新しいフラグ JSON_THROW_ON_ERROR が追加されました。 これは json_decode() や json_encode() 関数で使うことができ、 エラー時に JsonException をスローできるようになります。 これは、グローバルなエラー状態 json_last_error() や json_last_error_msg() を取得する代わりに使えます。 JSON_PARTIAL_OUTPUT_ON_ERROR は、 JSON_THROW_ON_ERROR に優先します。

マルチバイト文字列

configure オプション --with-libmbfl は利用できなくなりました。

ODBC (Unified)

birdstep.max_links ini ディレクティブを含む、 ODBCRouter と Birdstep のサポートが削除されました。

OPcache

opcache.inherited_hack ini ディレクティブは削除されました。 この値は、PHP 5.3.0 から既に無視されていました。

OpenSSL

ssl ストリームオプション min_proto_version および max_proto_version が 指定可能な TLS プロトコルに関連する定数とともに追加されました。

正規表現 (Perl互換)

PCRE拡張 は PCRE2 にアップグレードされました。 これによって振る舞いが少し変更される可能性があります (たとえば、 クラス中の文字の範囲がより厳密に解釈されるなど) し、 既に存在している正規表現の文法が増えるかもしれません。

preg_quote() 関数は '#' もエスケープするようになりました。

Microsoft SQL Server and Sybase Functions (PDO_DBLIB)

空の行セットを自動的にスキップできるようにするために、 PDO::DBLIB_ATTR_SKIP_EMPTY_ROWSETS 属性が追加されました。

TDS バージョンを公開するための属性として、 PDO::DBLIB_ATTR_TDS_VERSION が追加されました。

DATETIME2 型のカラムは、DATETIME型の絡むと同様に扱われるようになりました。

SQLite関数 (PDO_SQLITE)

SQLite3 データベースは、 新しい PDO::SQLITE_ATTR_OPEN_FLAGS 属性を PDO::SQLITE_OPEN_READONLY に設定することにより、 読み取り専用としてオープンできるようになりました。

セッションのハンドリング

session_set_cookie_params() 関数は、以下のシグネチャもサポートしました:

session_set_cookie_params(array $options): bool
$options は、 "lifetime", "path", "domain", "secure", "httponly" および "samesite" を指定可能な連想配列です。 それに応じて、 session_get_cookie_params() 関数の戻り値にも "samesite" が含まれるようになりました。 さらに、Cookie の SameSite ディレクティブのデフォルト値を設定するため、 新しい session.cookie_samesite ini オプションが追加されました。この値のデフォルト値は "" (空文字列) なので、SameSite ディレクティブは設定されません。 この値には、"Lax" または "Strict" が設定でき、それぞれが SameSiteディレクティブに設定されます。

Tidy

» tidyp 抜きでビルドすることが透過的にサポートされました。tidyp はリリース日を取得するAPIを提供していないため、 tidyp 抜きで PHP がビルドされた場合、 tidy_get_release() や tidy::getRelease() は 'unknown' を返します。

XMLパーサ

拡張モジュールが libxml を使ってビルドされた場合には、 xml_set_external_entity_ref_handler() 関数のコールバックの戻り値が無視されることはなくなりました。 このバージョン以前はコールバックの戻り値が無視され、パースが止まりませんでした。

Zip

PHP にバンドルされている libzip を使ってビルドすることは推奨されません。 しかし、--without-libzip を configure オプションに指定することにより、まだバンドルされた libzip を使ってビルド可能です。

Zlib による圧縮

望ましい圧縮レベルの設定を楽にするために、compress.zlib ラッパー の zlib/level コンテキストオプション が追加されました。


Windows のサポート

PHP コア

POSIX にさらに準拠したファイルの削除

ファイルディスクリプタは、共有 read/write/delete モードでオープンされるのがデフォルトになりました。 これにより、POSIX のセマンティクスに効率的に対応しつつ、使用中のファイルハンドルを削除することが可能になります。これは POSIX に 100% 準拠したものではありませんが、プラットフォームごとの違いはまだ存在します。ファイルハンドルを削除した後は、オープン済みの全てのファイルハンドルが閉じられるまで、ファイル名のエントリはブロックされます。


PHP 7.1.x から PHP 7.2.x への移行

目次

  • 新機能
  • 新しい関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 7.2.x で推奨されなくなる機能
  • その他の変更

このマイナーバージョンアップには数多くの 新機能 があります。 また、 互換性がない変更 が多少あるので、実運用環境の PHP をこのバージョンにあげる前にはテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.0.x, 7.1.x.


新機能

object 型

object 型が新たに導入されました。 任意のオブジェクトに対する (反変) パラメータの型付けや (共変) 戻り値の型付けで使えます。

<?php

function test(object $obj) : object
{
return new SplQueue();
}

test(new stdClass());

名前指定による拡張モジュールのロード

読み込む共有モジュールを指定する際に、拡張子 (Unix なら .so、Windows なら .dll など) を指定する必要がなくなりました。php.ini ファイルでの指定だけでなく dl() 関数による指定でも同様です。

抽象メソッドのオーバーライド

ある抽象クラスが別の抽象クラスを継承しているときに、 継承元クラスの抽象メソッドをオーバーライドできるようになりました。

<?php

abstract class A
{
abstract function test(string $s);
}
abstract class B extends A
{
// オーバーライドしましたが、パラメータの反変性や戻り値の共変性は維持しています。
abstract function test($s) : int;
}

Sodium がコアモジュールに

モダンな暗号ライブラリである Sodium が PHP コアモジュールに含まれるようになりました。

関数のリファレンスは Sodium を参照ください。

Argon2 によるパスワードハッシュ

パスワードハッシュ API に Argon2 が追加されました。次の定数が公開されています。

  • PASSWORD_ARGON2I
  • PASSWORD_ARGON2_DEFAULT_MEMORY_COST
  • PASSWORD_ARGON2_DEFAULT_TIME_COST
  • PASSWORD_ARGON2_DEFAULT_THREADS

PDO の拡張文字列型

PDO の文字列型が拡張され、 プリペアをエミュレートする際に NCHAR 型をサポートするようになりました。 以下の定数が追加されています。

  • PDO::PARAM_STR_NATL
  • PDO::PARAM_STR_CHAR
  • PDO::ATTR_DEFAULT_STR_PARAM

これらの定数を使うには、 PDO::PARAM_STR とビット OR で連結します。

<?php

$db->quote('uber', PDO::PARAM_STR | PDO::PARAM_STR_NATL);

PDO のデバッグ情報にプリペアのエミュレートの内容を追加

PDOStatement::debugDumpParams() メソッドが改良されて、 データベースに送信される SQL を表示できるようになりました。 これは、プレースホルダの内容をバインド変数の値で置き換えた後の生のクエリです。 この機能は、プリペア機能のエミュレートをデバッグしやすくするために用意されました (そのため、プリペア機能のエミュレートが有効になっているときしか使えません)。

LDAP における拡張オペレーションのサポート

LDAP 拡張モジュールが EXOP をサポートするようになりました。 以下の関数や定数が追加されています。

  • ldap_parse_exop()
  • ldap_exop()
  • ldap_exop_passwd()
  • ldap_exop_whoami()
  • LDAP_EXOP_START_TLS
  • LDAP_EXOP_MODIFY_PASSWD
  • LDAP_EXOP_REFRESH
  • LDAP_EXOP_WHO_AM_I
  • LDAP_EXOP_TURN

ソケット 拡張モジュールでのアドレス情報の対応

ソケット拡張モジュールが、アドレス情報のルックアップや 接続、バインド、explainに対応するようになりました。 新しく追加されたのは、以下の四つの関数です。

  • socket_addrinfo_lookup()
  • socket_addrinfo_connect()
  • socket_addrinfo_bind()
  • socket_addrinfo_explain()

パラメータの型の拡大変換

メソッドをオーバーライドしたりインターフェイスを実装したりする際に、 元のパラメータの型指定を省略できるようになりました。 それでもリスコフの置換原則には違反していません。 パラメータの型は反変だからです。

<?php

interface A
{
public function Test(array $input);
}

class B implements A
{
public function Test($input){} // $input の型指定を省略
}

名前空間のグループ指定における最後のカンマの許可

PHP 7.0 で導入されたグループ指定構文で、最後にカンマを付けられるようになりました。

<?php

use Foo\Bar\{
Foo,
Bar,
Baz,
};

Windows での proc_nice() のサポート

proc_nice() 関数が Windows でも使えるようになりました。

pack() と unpack() でのエンディアンのサポート

pack() と unpack() が、 リトルエンディアンとビッグエンディアンの両方の float や double に対応するようになりました。

EXIF 拡張モジュールの機能追加

EXIF 拡張モジュールがより多くのフォーマットに対応するようになりました。 exif_read_data() 関数で画像をパースするときに、 今までよりも多くの独自タグが適切に変換されるようになります。 新たにサポートするようになったフォーマットは以下のとおりです。

  • Samsung
  • DJI
  • Panasonic
  • Sony
  • Pentax
  • Minolta
  • Sigma/Foveon
  • AGFA
  • Kyocera
  • Ricoh
  • Epson

また、exif_read_data() と exif_thumbnail() の第一引数にストリームを渡せるようになりました。

PCRE の新機能

  • J 修飾子で PCRE_DUPNAMES を設定できるようになりました。

SQLite3 での BLOB の書き込み

SQLite3::openBlob() が、BLOB フィールドを書き込みモードでオープンできるようになりました。 これまでは読み込みモードにしか対応していませんでした。

Oracle OCI8 Transparent Application Failover コールバック

Oracle Database Transparent Application Failover (TAF) コールバック のサポートが追加されました。 TAF を使うと、データベースとの接続が切れたときに、 提議済みのデータベースに自動的に再接続できます。 TAF コールバックを使うと、 フェイルオーバー時の再接続を PHP アプリケーションから監視したり制御したりできるようになります。

ZIP 拡張モジュールの機能追加

暗号化されたアーカイブの読み書きができるようになりました (libzip 1.2.0 以降が必要です)。

ZipArchive クラスが Countable インターフェイスを実装するようになりました。

zip:// ストリームのコンテキストオプションに 'password' を使えるようになりました。


新しい関数

PHP コア

  • stream_isatty()
  • sapi_windows_vt100_support()

SPL

  • spl_object_id()

DOM

  • DomNodeList::count()
  • DOMNamedNodeMap::count()

FTP

  • ftp_append()

GD

  • imagesetclip()
  • imagegetclip()
  • imageopenpolygon()
  • imageresolution()
  • imagecreatefrombmp()
  • imagebmp()

Hash

  • hash_hmac_algos()

LDAP

  • ldap_parse_exop()
  • ldap_exop()
  • ldap_exop_passwd()
  • ldap_exop_whoami()

マルチバイト文字列

  • mb_chr()
  • mb_ord()
  • mb_scrub()

Oracle OCI8

  • oci_register_taf_callback()
  • oci_unregister_taf_callback()

Sockets

  • socket_addrinfo_lookup()
  • socket_addrinfo_connect()
  • socket_addrinfo_bind()
  • socket_addrinfo_explain()

Sodium

  • sodium_add()
  • sodium_bin2hex()
  • sodium_compare()
  • sodium_crypto_aead_aes256gcm_decrypt()
  • sodium_crypto_aead_aes256gcm_encrypt()
  • sodium_crypto_aead_aes256gcm_is_available()
  • sodium_crypto_aead_aes256gcm_keygen()
  • sodium_crypto_aead_chacha20poly1305_decrypt()
  • sodium_crypto_aead_chacha20poly1305_encrypt()
  • sodium_crypto_aead_chacha20poly1305_ietf_decrypt()
  • sodium_crypto_aead_chacha20poly1305_ietf_encrypt()
  • sodium_crypto_aead_chacha20poly1305_ietf_keygen()
  • sodium_crypto_aead_chacha20poly1305_keygen()
  • sodium_crypto_auth_keygen()
  • sodium_crypto_auth_verify()
  • sodium_crypto_auth()
  • sodium_crypto_box_keypair_from_secretkey_and_publickey()
  • sodium_crypto_box_keypair()
  • sodium_crypto_box_open()
  • sodium_crypto_box_publickey_from_secretkey()
  • sodium_crypto_box_publickey()
  • sodium_crypto_box_seal_open()
  • sodium_crypto_box_seal()
  • sodium_crypto_box_secretkey()
  • sodium_crypto_box_seed_keypair()
  • sodium_crypto_box()
  • sodium_crypto_generichash_final()
  • sodium_crypto_generichash_init()
  • sodium_crypto_generichash_keygen()
  • sodium_crypto_generichash_update()
  • sodium_crypto_generichash()
  • sodium_crypto_kdf_derive_from_key()
  • sodium_crypto_kdf_keygen()
  • sodium_crypto_kx_client_session_keys()
  • sodium_crypto_kx_keypair()
  • sodium_crypto_kx_publickey()
  • sodium_crypto_kx_secretkey()
  • sodium_crypto_kx_seed_keypair()
  • sodium_crypto_kx_server_session_keys()
  • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify()
  • sodium_crypto_pwhash_scryptsalsa208sha256_str()
  • sodium_crypto_pwhash_scryptsalsa208sha256()
  • sodium_crypto_pwhash_str_verify()
  • sodium_crypto_pwhash_str()
  • sodium_crypto_pwhash()
  • sodium_crypto_scalarmult_base()
  • sodium_crypto_scalarmult()
  • sodium_crypto_secretbox_keygen()
  • sodium_crypto_secretbox_open()
  • sodium_crypto_secretbox()
  • sodium_crypto_shorthash_keygen()
  • sodium_crypto_shorthash()
  • sodium_crypto_sign_detached()
  • sodium_crypto_sign_ed25519_pk_to_curve25519()
  • sodium_crypto_sign_ed25519_sk_to_curve25519()
  • sodium_crypto_sign_keypair_from_secretkey_and_publickey()
  • sodium_crypto_sign_keypair()
  • sodium_crypto_sign_open()
  • sodium_crypto_sign_publickey_from_secretkey()
  • sodium_crypto_sign_publickey()
  • sodium_crypto_sign_secretkey()
  • sodium_crypto_sign_seed_keypair()
  • sodium_crypto_sign_verify_detached()
  • sodium_crypto_sign()
  • sodium_crypto_stream_keygen()
  • sodium_crypto_stream_xor()
  • sodium_crypto_stream()
  • sodium_hex2bin()
  • sodium_increment()
  • sodium_memcmp()
  • sodium_memzero()
  • sodium_pad()
  • sodium_unpad()

ZIP

  • ZipArchive::count()
  • ZipArchive::setEncryptionName()
  • ZipArchive::setEncryptionIndex()


新しいグローバル定数

PHP コア

  • PHP_FLOAT_DIG
  • PHP_FLOAT_EPSILON
  • PHP_FLOAT_MIN
  • PHP_FLOAT_MAX
  • PHP_OS_FAMILY

ファイル情報

  • FILEINFO_EXTENSION

JSON

  • JSON_INVALID_UTF8_IGNORE
  • JSON_INVALID_UTF8_SUBSTITUTE

GD

  • IMG_EFFECT_MULTIPLY
  • IMG_BMP

LDAP

  • LDAP_EXOP_START_TLS
  • LDAP_EXOP_MODIFY_PASSWD
  • LDAP_EXOP_REFRESH
  • LDAP_EXOP_WHO_AM_I
  • LDAP_EXOP_TURN

パスワードのハッシュ

  • PASSWORD_ARGON2I
  • PASSWORD_ARGON2_DEFAULT_MEMORY_COST
  • PASSWORD_ARGON2_DEFAULT_TIME_COST
  • PASSWORD_ARGON2_DEFAULT_THREADS

PCRE

  • PREG_UNMATCHED_AS_NULL

PDO

  • PDO::PARAM_STR_NATL
  • PDO::PARAM_STR_CHAR
  • PDO::ATTR_DEFAULT_STR_PARAM

Sodium

  • SODIUM_LIBRARY_VERSION
  • SODIUM_LIBRARY_MAJOR_VERSION
  • SODIUM_LIBRARY_MINOR_VERSION
  • SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES
  • SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES
  • SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES
  • SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES
  • SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES
  • SODIUM_CRYPTO_AUTH_BYTES
  • SODIUM_CRYPTO_AUTH_KEYBYTES
  • SODIUM_CRYPTO_BOX_SEALBYTES
  • SODIUM_CRYPTO_BOX_SECRETKEYBYTES
  • SODIUM_CRYPTO_BOX_PUBLICKEYBYTES
  • SODIUM_CRYPTO_BOX_KEYPAIRBYTES
  • SODIUM_CRYPTO_BOX_MACBYTES
  • SODIUM_CRYPTO_BOX_NONCEBYTES
  • SODIUM_CRYPTO_BOX_SEEDBYTES
  • SODIUM_CRYPTO_KDF_BYTES_MIN
  • SODIUM_CRYPTO_KDF_BYTES_MAX
  • SODIUM_CRYPTO_KDF_CONTEXTBYTES
  • SODIUM_CRYPTO_KDF_KEYBYTES
  • SODIUM_CRYPTO_KX_SEEDBYTES
  • SODIUM_CRYPTO_KX_SESSIONKEYBYTES
  • SODIUM_CRYPTO_KX_PUBLICKEYBYTES
  • SODIUM_CRYPTO_KX_SECRETKEYBYTES
  • SODIUM_CRYPTO_KX_KEYPAIRBYTES
  • SODIUM_CRYPTO_GENERICHASH_BYTES
  • SODIUM_CRYPTO_GENERICHASH_BYTES_MIN
  • SODIUM_CRYPTO_GENERICHASH_BYTES_MAX
  • SODIUM_CRYPTO_GENERICHASH_KEYBYTES
  • SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN
  • SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX
  • SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13
  • SODIUM_CRYPTO_PWHASH_ALG_DEFAULT
  • SODIUM_CRYPTO_PWHASH_SALTBYTES
  • SODIUM_CRYPTO_PWHASH_STRPREFIX
  • SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE
  • SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
  • SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE
  • SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE
  • SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE
  • SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE
  • SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES
  • SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX
  • SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE
  • SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE
  • SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE
  • SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE
  • SODIUM_CRYPTO_SCALARMULT_BYTES
  • SODIUM_CRYPTO_SCALARMULT_SCALARBYTES
  • SODIUM_CRYPTO_SHORTHASH_BYTES
  • SODIUM_CRYPTO_SHORTHASH_KEYBYTES
  • SODIUM_CRYPTO_SECRETBOX_KEYBYTES
  • SODIUM_CRYPTO_SECRETBOX_MACBYTES
  • SODIUM_CRYPTO_SECRETBOX_NONCEBYTES
  • SODIUM_CRYPTO_SIGN_BYTES
  • SODIUM_CRYPTO_SIGN_SEEDBYTES
  • SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES
  • SODIUM_CRYPTO_SIGN_SECRETKEYBYTES
  • SODIUM_CRYPTO_SIGN_KEYPAIRBYTES
  • SODIUM_CRYPTO_STREAM_NONCEBYTES
  • SODIUM_CRYPTO_STREAM_KEYBYTES

Zip

  • ZipArchive::EM_NONE
  • ZipArchive::EM_AES_128
  • ZipArchive::EM_AES_192
  • ZipArchive::EM_AES_256


下位互換性のない変更点

number_format() は負のゼロを返さない

以前のバージョンでは、number_format() 関数が -0 を返せました。 これは IEEE 754 浮動小数点標準規格に沿ったまったく問題のない値ですが、 人間が読みやすい形式に数値をフォーマットするという意味では少し不自然でした。

<?php

var_dump(number_format(-0.01)); // string(2) "-0" ではなく string(1) "0" となります

オブジェクトと配列の型変換における数値キーの扱い

配列からオブジェクトへのキャストやその逆のキャストにおける、数値キーの扱いが改善されました。 明示的なキャストだけではなく settype() を使った場合も同様です。

数値キーの配列をオブジェクトにキャストしたときに、その要素にアクセスできるようになったのです。

<?php

// 配列からオブジェクトへの変換
$arr = [0 => 1];
$obj = (object)$arr;
var_dump(
$obj,
$obj->{'0'}, // アクセスできるようになりました
$obj->{0} // アクセスできるようになりました
);

上の例の出力は以下となります。

object(stdClass)#1 (1) {
  ["0"]=>    // 数値キーではなく、文字列のキーになりました
  int(1)
}
int(1)
int(1)

また、オブジェクトに数値のキーが含まれる場合に、 配列にキャストしてもその要素にアクセスできるようになりました。

<?php

// オブジェクトから配列への変換
$obj = new class {
public function __construct()
{
$this->{0} = 1;
}
};
$arr = (array)$obj;
var_dump(
$arr,
$arr[0], // アクセスできるようになりました
$arr['0'] // アクセスできるようになりました
);

上の例の出力は以下となります。

array(1) {
  [0]=>    // 文字列のキーではなく、整数のキーになります
  int(1)
}
int(1)
int(1)

get_class() に null を渡せない

以前のバージョンでは、get_class() に null を渡すと、そのコンテキストの外側のクラスを返していました。 この機能は削除され、null を渡すと E_WARNING が発生するようになりました。 以前と同様の挙動を実現したい場合は、null を渡すのではなく単にパラメータを省略するようにしましょう。

countable ではない型をカウントしたときの警告

countable ではない型に対して count() (およびそのエイリアスである sizeof()) を使ったときに E_WARNING が発生するようになりました。

<?php

var_dump(
count(null), // NULL はカウントできません
count(1), // integer はカウントできません
count('abc'), // string はカウントできません
count(new stdClass), // Countable インターフェイスを実装していないオブジェクトはカウントできません
count([1,2]) // array はカウントできます
);

上の例の出力は以下となります。

Warning: count(): Parameter must be an array or an object that implements Countable in %s on line %d

Warning: count(): Parameter must be an array or an object that implements Countable in %s on line %d

Warning: count(): Parameter must be an array or an object that implements Countable in %s on line %d

Warning: count(): Parameter must be an array or an object that implements Countable in %s on line %d
int(0)
int(1)
int(1)
int(1)
int(2)

ext/hash がリソースからオブジェクトへ

長期にわたるリソースからオブジェクトへの移行作業の一環として、 Hash 拡張モジュールがリソースではなくオブジェクトを使うようになりました。 開発者側から見て特に変わるところはありませんが、もし is_resource() を使ったチェックを行っているのなら、 それを is_object() に書き換える必要があります。

SSL/TLS のデフォルトの改善

デフォルト設定が以下のように変わりました。

  • tls:// が、TLSv1.0 や TLSv1.1 や TLSv1.2 のデフォルトになりました。
  • ssl:// は tls:// のエイリアスになりました。
  • STREAM_CRYPTO_METHOD_TLS_* 定数のデフォルトが、 TLSv1.0 だけではなく TLSv1.0 または TLSv1.1 + TLSv1.2 となりました。

gettype() にクローズ済みのリソースを渡した際の戻り値

以前のバージョンでは、 gettype() にクローズ済みのリソースを渡すと、"unknown type" という文字列を返していました。 これからは、 "resource (closed)" という文字列が返されます。

is_object() と __PHP_Incomplete_Class

以前のバージョンでは、 __PHP_Incomplete_Class クラスに対して、 is_object() を使うと false が返されていました。 これからは true が返されます。

定義されていない定数のエラーレベル変更

定義されていない定数への参照を行った場合、 E_WARNING を生成するようになりました。 (今までは E_NOTICEを生成していました。) 次のPHPメジャーバージョンでは、Error 例外を生成するように変更される予定です。

Windows サポート

現在、公式にサポートしている最低バージョンは Windows 7/Server 2008 R2です。

trait のプロパティの値チェック

trait のプロパティの値に対して互換性があるかどうかをチェックするときは、値のキャストを行わなくなりました。

object をクラス名に使う

object という名前は、PHP 7.0 では緩く予約されていました。 PHP 7.2 からは制約が強くなり、クラスや trait、インターフェイスの名前として使うことが禁止されます。

NetWare サポート

NetWareのサポートが削除されました。

array_unique() 関数を SORT_STRING と使う場合

array_unique() 関数を SORT_STRING と使う場合、以前は配列をコピーし、重複した要素を削除 (配列を後にパックせずに) していましたが、このバージョンからは 新しい配列作られ、ユニークな要素を追加するようになりました。 これにより、以前のバージョンとは異なった数値のインデックスが生成されます。

bcmod() の小数点に対する挙動変更

bcmod() 関数が小数点切り捨てをしないようになりました。
これからは、挙動は % 演算子ではなく、 fmod()に準拠します。
たとえば、 bcmod('4', '3.5') はいままでの1ではなく、 0.5 を返します。

ハッシュ関数と非暗号化ハッシュ

hash_hmac()、 hash_hmac_file()、 hash_pbkdf2()、 および hash_init() ( HASH_HMAC) は非暗号化ハッシュを受け入れないように変更されました。

json_decode() 関数のオプション

json_decode() 関数のオプション、 JSON_OBJECT_AS_ARRAY は、2番めのパラメータ (assoc) が null の場合に使用されるようになりました。 JSON_OBJECT_AS_ARRAY はこれまで無視されていました。

rand() と mt_rand() の出力

特定のシードで rand() と mt_rand() で生成されたシーケンスは、64-bit マシンで動作しているPHP 7.1と値が異なる場合があります。 (モジュロバイアスのバグ修正が実装されました。).

sql.safe_mode のini設定削除

sql.safe_mode のini設定が削除されました。

date_parse() と date_parse_from_format() 関数への変更

date_parse() 関数 と date_parse_from_format() 関数 が返す zone 要素は、 分ではなくて秒を表現するようになり、符号も逆になりました。 たとえば -120 分は 7200 秒を意味するようになりました。

外部から入力されるCookie

PHP 7.2.34 以降は、セキュリティ上の理由により、 外部から入力される Cookie の 名前 はurlデコードされなくなりました。


PHP 7.2.x で推奨されなくなる機能

クオートしない文字列

クオートしない文字列は、その名前のグローバル定数が定義されていない場合は単なる文字列という扱いになります。 このとき、いままでは E_NOTICE が発生していました。 PHP 7.2.x 以降は、E_WARNING が発生するようになります。 次のメジャーバージョンアップ後は Error 例外が発生するようになります。

<?php

var_dump(NONEXISTENT);

/* 出力:
Warning: Use of undefined constant NONEXISTENT - assumed 'NONEXISTENT' (this will throw an Error in a future version of PHP) in %s on line %d
string(11) "NONEXISTENT"
*/

png2wbmp() および jpeg2wbmp()

GD 拡張モジュールの png2wbmp() および jpeg2wbmp() 関数は非推奨となり、次のPHPのメジャーバージョンアップで削除される予定です。

INTL_IDNA_VARIANT_2003 バリアント

Intl 拡張モジュール では、INTL_IDNA_VARIANT_2003 バリアントは非推奨になりました。 これは idn_to_ascii() および idn_to_utf8() 関数の デフォルト値として現在使われています。PHP 7.4 ではこのデフォルト値が INTL_IDNA_VARIANT_UTS46 に変更される予定ですし、 PHP の次のメジャーバージョンアップでは、 INTL_IDNA_VARIANT_2003 が削除される予定です。

__autoload() メソッド

__autoload()メソッドは非推奨になりました。なぜなら、この関数は (autoloader をチェインできない点で) spl_autoload_register() に劣っていますし、これら2つの autoload のやり方には互換性がないからです。

php.ini の track_errors および $php_errormsg 変数

php.ini で track_errors の設定が有効になると、 致命的でないエラーが起きた場合に、$php_errormsg 変数がローカルスコープに生成されます。 このようなエラー情報を収集するのに望ましい方法は、error_get_last() 関数を使うことなので この機能は非推奨になりました。

create_function() 関数

(eval() 関数のラッパーなので) この関数にはセキュリティ上の問題があるため、非推奨になりました。 好ましい代替は 無名関数 です。

php.ini の mbstring.func_overload

この設定が有効になった環境で使われる、文字列ベースの関数の相互運用上の問題により、この設定は非推奨になりました。

(unset) キャスト

あらゆる値を (unset) キャストすると null になりますが、この余分な機能は非推奨になりました。

第二引数を指定しないで parse_str() 関数を使う

2番目の引数を指定しないで parse_str() 関数を使うと、 これが使われた関数内部のシンボルテーブルを収集してしまいます。 これはセキュリティ上の問題があるため、2番目の引数を指定しないで parse_str() を使うのは非推奨になりました。この関数の2番目の引数は、クエリストリングを配列に設定してくれる ので、常に設定すべきです。

gmp_random() 関数

この関数は、外部に公開されていない、プラットフォーム依存のlimbサイズの範囲に基づいて ランダムな数を生成しています。このため、この関数は非推奨になりました。GMP 拡張モジュールを使って ランダムな数値を生成する望ましいやり方は、 gmp_random_bits() および gmp_random_range() を使うことです。

each()関数

この関数は、通常の foreachよりもループが遅く、PHPそのものの変更に伴って 実装上の問題を引き起こしたことから、非推奨になりました。

assert()関数に文字列を渡す

assert() で eval() させるには、この関数に文字列を渡す必要がありました。 リモートからコードを実行される可能性があるので、この関数に文字列を渡すのは非推奨になりました。boolean 値を渡すのが お勧めです。

エラーハンドラの $errcontext 引数

$errcontext 引数には、エラーが起きた場所の全てのローカル変数 が含まれています。これは使われることが少ないことと、PHP の内部的な最適化に問題を 引き起こすため、非推奨になりました。エラーが起きた場所のローカル変数の情報を取得 するには、デバッガを使うべきです。

read_exif_data() 関数

read_exif_data() 関数は非推奨になりました。 代わりに exif_read_data() 関数を使ってください。


その他の変更

utf8_encode() および utf8_decode() 関数の移動

utf8_encode() および utf8_decode() 関数は、文字列関数の標準拡張モジュールに移動しました。以前は、この関数を使うには、 XML 拡張モジュールが必須でした。

mail() および mb_send_mail() への変更

mail() および mb_send_mail() の $additional_headers パラメータは、string の代わりに array も受け付けるようになりました。

LMDB のサポート

DBA 拡張モジュールは、新たに LMDB をサポートしました。

PHP ビルドシステムへの変更

  • Unix: Autoconf 2.64 以上が PHP をビルドするのに必須になりました。
  • Unix: --with-pdo-oci configure 引数に対して、Oracle Instant Client のバージョン指定は不要になりました。
  • Unix: --enable-gd-native-ttf configure 引数は削除されました。これは PHP 5.5.0 以降では使われていませんでした。
  • Windows: --with-config-profile configure 引数が追加されました。 この引数は、 config.nice.bat ファイルのような形で、特定の configure引数を保存するのに使えます。

GD 関数の変更

  • システムの libgd ライブラリを使って PHP がコンパイルされた場合に imageantialias() 関数が使えるようになりました。
  • imagegd() 関数は、truecolor 画像を truecolor 画像として保存するようになりました。 以前は、パレットに変換していました。

MCrypt 拡張モジュールが PECL に移動

MCrypt 拡張モジュールは、PHPコアから PECL に移動しました。 mcrypt ライブラリは 2007年から更新されていませんし、それ自体使うことが全く推奨できないからです。 代わりに OpenSSL もしくは Sodium 拡張モジュール を使ってください。

session_module_name()

session_module_name() に "user" を渡すと、 レベル E_RECOVERABLE_ERROR のエラーが発生します。 以前は、通知せずに無視されていました。


PHP 7.0.x から PHP 7.1.x への移行

目次

  • 新機能
  • 新しい関数
  • 新しいグローバル定数
  • 下位互換性のない変更点
  • PHP 7.1.x で推奨されなくなる機能
  • 変更された関数
  • その他の変更
  • Windows のサポート

このマイナーバージョンアップには数多くの 新機能 があります。 また、 互換性がない変更 が多少あるので、実運用環境の PHP をこのバージョンにあげる前にはテストすべきです。

これらのバージョンへの移行ガイドも参照ください。 7.0.x.


新機能

nullable な型

パラメータや戻り値の型宣言で nullable 指定ができるようになりました。 型の前にクエスチョンマークをつけると、nullable であることを指定できます。 nullable 指定をすると、指定した型だけでなく null も渡せるようになります。

<?php

function testReturn(): ?string
{
return 'elePHPant';
}

var_dump(testReturn());

function testReturn(): ?string
{
return null;
}

var_dump(testReturn());

function test(?string $name)
{
var_dump($name);
}

test('elePHPant');
test(null);
test();

上の例の出力は以下となります。

string(10) "elePHPant"
NULL
string(10) "elePHPant"
NULL
Uncaught Error: Too few arguments to function test(), 0 passed in...

void 関数

戻り値の型として void が導入されました。戻り値の型を void と宣言した関数は、関数内での return 文を省略するか、あるいは空の return を使う必要があります。 void 関数から null を返すことはできません。

<?php
function swap(&$left, &$right): void
{
if ($left === $right) {
return;
}

$tmp = $left;
$left = $right;
$right = $tmp;
}

$a = 1;
$b = 2;
var_dump(swap($a, $b), $a, $b);

上の例の出力は以下となります。

null
int(2)
int(1)

void 関数の戻り値を使おうとした場合はその値は null と評価されます。 警告は発生しません。警告を発生させると、一般的な高階関数の利用にも影響するからです。

対称的な配列の分解

配列の短縮構文 ([]) を使って、 代入用に配列の値を取り出せるようになりました (foreach でも使えます)。 これは、list() の代替として使えます (list() もまだ使えます)。

<?php
$data = [
[1, 'Tom'],
[2, 'Fred'],
];

// list() 形式
list($id1, $name1) = $data[0];

// [] 形式
[$id1, $name1] = $data[0];

// list() 形式
foreach ($data as list($id, $name)) {
// $id と $name を使う処理をここに書きます
}

// [] 形式
foreach ($data as [$id, $name]) {
// $id と $name を使う処理をここに書きます
}

クラス定数のアクセス範囲指定

クラス定数のアクセス範囲を指定できるようになりました。

<?php
class ConstDemo
{
const PUBLIC_CONST_A = 1;
public const PUBLIC_CONST_B = 2;
protected const PROTECTED_CONST = 3;
private const PRIVATE_CONST = 4;
}

iterable 擬似型

新しい擬似型 (callable と同じような型) である iterable が導入されました。 パラメータおよび戻り値の型指定で使うことができます。 配列か、あるいは Traversable インターフェイスを実装したオブジェクトを受け付けるようになります。 派生型に貸しては、子クラスのパラメータの型が、 親クラスの array や Traversable を拡張して iterable に広げることができます。 戻り値の型に関しては、親クラスの iterable 型指定を子クラスで 配列あるいはオブジェクト (Traversable を実装したもの) に絞り込むことができます。

<?php
function iterator(iterable $iter)
{
foreach ($iter as $val) {
//
}
}

例外処理における複数の例外の catch

ひとつの catch ブロックで複数の例外を扱えるようになりました。 パイプ文字 (|) を使って指定します。 これは、異なるクラス階層に由来する異なる例外を同じように処理したい場合に有用です。

<?php
try {
// 何かのコード
} catch (FirstException | SecondException $e) {
// FirstException と SecondException をこのブロックで処理します
}

list() におけるキーのサポート

list() (あるいはその短縮版である [] 構文) の内部でキーを指定できるようになりました。 つまり、キーが整数でなかったりシーケンシャルでなかったりした場合でも、 配列の値を取り出せるようになったということです。

<?php
$data = [
["id" => 1, "name" => 'Tom'],
["id" => 2, "name" => 'Fred'],
];

// list() 形式
list("id" => $id1, "name" => $name1) = $data[0];

// [] 形式
["id" => $id1, "name" => $name1] = $data[0];

// list() 形式
foreach ($data as list("id" => $id, "name" => $name)) {
// $id と $name を使う処理をここに書きます
}

// [] 形式
foreach ($data as ["id" => $id, "name" => $name]) {
// $id と $name を使う処理をここに書きます
}

負の文字列オフセットのサポート

文字列操作関数 のうちオフセット指定のできるものすべてについて、負のオフセットを指定できるようになりました。 [] や {} による 文字列への文字単位のアクセス についても同様です。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

<?php
var_dump("abcdef"[-2]);
var_dump(strpos("aabbcc", "b", -3));

上の例の出力は以下となります。

string (1) "e"
int(3)

文字列や配列に対する負のオフセットが、文字列内での単純な変数パース構文においても使えるようになりました。

<?php
$string = 'bar';
echo "The last character of '$string' is '$string[-1]'.\n";
?>

上の例の出力は以下となります。

The last character of 'bar' is 'r'.

ext/openssl における AEAD のサポート

openssl_encrypt() および openssl_decrypt() の追加のパラメータで、 AEAD (GCM モードおよび CCM モード) をサポートするようになりました。

Closure::fromCallable() による callables から Closure への変換

Closure クラスに新しいstaticメソッドが追加されました。 callable を、簡単に Closure オブジェクトに変換できるようにするものです。

<?php
class Test
{
public function exposeFunction()
{
return Closure::fromCallable([$this, 'privateFunction']);
}

private function privateFunction($param)
{
var_dump($param);
}
}

$privFunc = (new Test)->exposeFunction();
$privFunc('some value');

上の例の出力は以下となります。

string(10) "some value"

非同期シグナルハンドリング

新しい関数 pcntl_async_signals() が追加されました。これは、tick を使わない非同期シグナルハンドリングを有効にするものです (tick は相当大きなオーバーヘッドになります)。

<?php
pcntl_async_signals(true); // 非同期シグナルを有効にします

pcntl_signal(SIGHUP, function($sig) {
echo "SIGHUP\n";
});

posix_kill(posix_getpid(), SIGHUP);

上の例の出力は以下となります。

SIGHUP

ext/curl における HTTP/2 サーバープッシュのサポート

CURL 拡張モジュールがサーバープッシュに対応するようになりました (curl バージョン 7.46 以降が必要です)。 curl_multi_setopt() 関数に新しい定数 CURLMOPT_PUSHFUNCTION を指定すれば、この機能を使えます。 また、定数 CURL_PUSH_OK と CURL_PUSH_DENY も新たに追加されました。 これらは、サーバープッシュコールバックの実行を許可したり拒否したりするものです。

ストリームコンテキストオプション

tcp_nodelay ストリームコンテキストオプションが追加されました。


新しい関数

PHP コア

  • sapi_windows_cp_get()
  • sapi_windows_cp_set()
  • sapi_windows_cp_conv()
  • sapi_windows_cp_is_utf8()

Closure

  • Closure::fromCallable()

CURL

  • curl_multi_errno()
  • curl_share_errno()
  • curl_share_strerror()

OpenSSL

  • openssl_get_curve_names()

Session

  • session_create_id()
  • session_gc()

SPL

  • is_iterable()

PCNTL

  • pcntl_async_signals()
  • pcntl_signal_get_handler()


新しいグローバル定数

コアで定義済みの定数

  • PHP_FD_SETSIZE

CURL

  • CURLMOPT_PUSHFUNCTION
  • CURL_PUSH_OK
  • CURL_PUSH_DENY

データのフィルタリング

  • FILTER_FLAG_EMAIL_UNICODE

Image Processing and GD

  • IMAGETYPE_WEBP

JSON

  • JSON_UNESCAPED_LINE_TERMINATORS

LDAP

  • LDAP_OPT_X_SASL_NOCANON
  • LDAP_OPT_X_SASL_USERNAME
  • LDAP_OPT_X_TLS_CACERTDIR
  • LDAP_OPT_X_TLS_CACERTFILE
  • LDAP_OPT_X_TLS_CERTFILE
  • LDAP_OPT_X_TLS_CIPHER_SUITE
  • LDAP_OPT_X_TLS_KEYFILE
  • LDAP_OPT_X_TLS_RANDOM_FILE
  • LDAP_OPT_X_TLS_CRLCHECK
  • LDAP_OPT_X_TLS_CRL_NONE
  • LDAP_OPT_X_TLS_CRL_PEER
  • LDAP_OPT_X_TLS_CRL_ALL
  • LDAP_OPT_X_TLS_DHFILE
  • LDAP_OPT_X_TLS_CRLFILE
  • LDAP_OPT_X_TLS_PROTOCOL_MIN
  • LDAP_OPT_X_TLS_PROTOCOL_SSL2
  • LDAP_OPT_X_TLS_PROTOCOL_SSL3
  • LDAP_OPT_X_TLS_PROTOCOL_TLS1_0
  • LDAP_OPT_X_TLS_PROTOCOL_TLS1_1
  • LDAP_OPT_X_TLS_PROTOCOL_TLS1_2
  • LDAP_OPT_X_TLS_PACKAGE
  • LDAP_OPT_X_KEEPALIVE_IDLE
  • LDAP_OPT_X_KEEPALIVE_PROBES
  • LDAP_OPT_X_KEEPALIVE_INTERVAL

PostgreSQL

  • PGSQL_NOTICE_LAST
  • PGSQL_NOTICE_ALL
  • PGSQL_NOTICE_CLEAR

SPL

  • MT_RAND_PHP


下位互換性のない変更点

関数に渡す引数が少ない場合の挙動

これまでのバージョンでは、ユーザー定義の関数に渡す引数が足りない場合は warning が発生していました。PHP 7.1 以降では、warning ではなく Error 例外が発生するようになります。 この変更はユーザー定義の関数に対してだけのもので、 内部関数には影響を及ぼしません。

<?php
function test($param){}
test();

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught ArgumentCountError: Too few arguments to function test(), 0 passed in %s on line %d and exactly 1 expected in %s:%d

スコープを調べる関数の動的呼び出しの禁止

ある種の関数について、動的な呼び出し ($func() や array_map('extract', ...) のような形式) が使えなくなりました。対象になるのは、別のスコープを調べたり変更したり、 あいまいな挙動になってしまったりするような関数です。 この変更の影響を受ける関数は、以下のとおりです。

  • assert() - 最初の引数に文字列を渡した場合
  • compact()
  • extract()
  • func_get_args()
  • func_get_arg()
  • func_num_args()
  • get_defined_vars()
  • mb_parse_str() - 引数が一つだけの場合
  • parse_str() - 引数が一つだけの場合
<?php
(function () {
$func = 'func_num_args';
$func();
})();

上の例の出力は以下となります。

Warning: Cannot call func_num_args() dynamically in %s on line %d

クラス、インターフェイス、トレイトに使えない名前

これらのキーワードが、クラスやインターフェイスやトレイトの名前として使えなくなりました。

  • void
  • iterable

数値形式文字列の変換が科学記法に対応

数値形式の文字列の演算や型変換が、科学記法に対応するようになりました。
(int) によるキャストや、
intval() (基数が10の場合)、
settype()、decbin()、
decoct()、dechex() といった関数もその対象です。

mt_rand() のアルゴリズムの修正

mt_rand() のデフォルトが、修正版のメルセンヌ・ツイスタ
アルゴリズムを使うようになりました。mt_rand()
の結果に依存するコードを書いていた場合は、mt_srand()
のオプションの第二引数に MT_RAND_PHP
を指定すると、これまでの挙動 (間違った実装) を維持できます。

rand() と srand() が、 それぞれ mt_rand() と mt_srand() のエイリアスとなる

rand() と srand() は、それぞれ mt_rand() と mt_srand() のエイリアスになりました。つまり、 rand()、shuffle()、 str_shuffle()、array_rand() の出力がこれまでのバージョンとは変わるということです。

ASCII 制御文字 delete は識別子として使えない

ASCII 制御文字 delete (0x7F) は、 クォートしない限りは識別子として使えなくなりました。

error_log に syslog を指定した場合の変更

INI 項目 error_log の設定値を syslog にした場合に、PHP のエラーレベルが syslog のエラーレベルにマッピングされるようになりました。 これまでのバージョンではすべてのエラーが notice レベルで記録されていましたが、 この変更によって、今までよりも細やかな区別ができるようになります。

未完成のオブジェクトのデストラクタは呼び出されない

オブジェクトのコンストラクタの実行中に例外がスローされた場合に、 そのオブジェクトのデストラクタが呼ばれることはなくなりました。 以前のバージョンでは、場合によっては (例: そのオブジェクトが例外バックトレースなどで外部から参照される場合) デストラクタが呼ばれることもありました。

参照渡しの引数の call_user_func() での扱い

引数を参照渡しで受け取る関数を call_user_func() から呼んだときに、例外が発生するようになりました。 以前のバージョンでは、完全修飾形式の呼び出しであるか否かによってこの場合の挙動が異なっていました。

さらにこの場合、call_user_func() や call_user_func_array() は関数呼び出しを中断しなくなりました。 "expected reference" という警告は出すものの、処理自体はそのまま続行します。

文字列における空のインデックス演算子はサポートしない

文字列に空のインデックス演算子を適用する (例: $str[] = $x) と、fatal エラーが発生します。これまでのバージョンではエラーにならず、 ただ配列に変換されるだけでした。

空文字列に対して、文字列インデックス経由で値を設定する操作

空文字列に対して、一文字単位で変更する操作が、 空でない文字列と同じように機能するようになりました。 つまり、範囲外のオフセットに対する書き込みがスペースで埋められ、 整数型でない値は整数に変換され、最初の文字だけが採用されるというものです。 これより前のバージョンでは、黙って空の配列として扱われていました。

<?php
$a = '';
$a[10] = 'foo';
var_dump($a);
?>

上の例の PHP 7.0 での出力は、このようになります。

array(1) {
  [10]=>
  string(3) "foo"
}

上の例の PHP 7.1 での出力は、このようになります。

string(11) "          f"

削除された INI 項目

以下の INI 項目は、削除されました。

  • session.entropy_file
  • session.entropy_length
  • session.hash_function
  • session.hash_bits_per_character

参照による代入で自動的に作られる配列の要素の並び順の変更

参照による代入で配列の要素が自動的に作られる場合に、その並び順が変更されました。

<?php
$array = [];
$array["a"] =& $array["b"];
$array["b"] = 1;
var_dump($array);
?>

上の例の PHP 7.0 での出力は、このようになります。

array(2) {
  ["a"]=>
  &int(1)
  ["b"]=>
  &int(1)
}

上の例の PHP 7.1 での出力は、このようになります。

array(2) {
  ["b"]=>
  &int(1)
  ["a"]=>
  &int(1)
}

同値な要素の並び順

内部的なソートアルゴリズムが改良されたことに伴って、 比較したときに等しいとみなされる要素の並び順が以前とは変わるかもしれません。

注意:

同値な要素の並び順に依存するコードは書かないようにしましょう。 その並び順がいつまでも同じであるとは限りません。

E_RECOVERABLE エラーのエラーメッセージ

E_RECOVERABLE エラーのエラーメッセージが、 "Catchable fatal error" から "Recoverable fatal error" に変更されました。

unserialize() 関数の $options パラメータ

unserialize() 関数の $options パラメータの allowed_classes 要素が、 型を厳密に解釈するようになりました。 つまり、array または bool 以外のあらゆる値が与えられても、 unserialize() は false を返し、 E_WARNING レベルの警告が発生します。

DateTime クラスのコンストラクタに、マイクロ秒も組み込まれる

DateTime と DateTimeImmutable は、現在時刻、明示的な時刻、 または相対時刻を示す文字列 (例: "first day of next month") から構築されると、 マイクロ秒を適切に含めるようになりました。 これは、新しく生成されたふたつのインスタンスが、true ではなくて false を返しやすくなったということです。

<?php
new DateTime() == new DateTime();
?>

致命的なエラーが Error 例外に変換される

Date 拡張モジュールでは、 DateTime または DatePeriod クラス のシリアライズデータが不正だったり、 シリアライズしたデータからタイムゾーンを初期化するのに失敗した場合、 致命的なエラーにならず、 __wakeup() や __set_state() メソッドから Error 例外をスローするようになりました。

DBA 拡張モジュールでは、 (dba_insert() のように) データを変更する関数は、キーが正確にふたつの要素を含んでいない場合に キャッチ可能な fatal error ではなく、 Error 例外をスローするようになりました。

DOM 拡張モジュールでは、 不正なスキーマ や RelaxNG検証コンテキスト は 致命的なエラーにならず、 Error 例外をスローするようになりました。 同じように、適切な基底クラスを継承しないノードクラスを登録しようとしたり、 不正なプロパティを読み出そうとしたり、 読み込み専用のプロパティに書き込もうとしたりしても、 同様に Error 例外をスローようになりました。

IMAP 拡張モジュールでは、 16385 バイト以上の email アドレスは、 致命的なエラーにならず、 Error 例外をスローするようになりました。

Intl 拡張モジュールでは、 Collator クラスを継承したクラスで、 親メソッドを呼ぶ前に親のコンストラクタを呼ぶのに失敗すると、 回復可能な fatal error にはならず、 Error 例外をスローするようになりました。 同様に、Transliterator を clone すると、 内部の transliterator の複製に失敗した時に 致命的なエラーにならず、 Error 例外をスローするようになりました。

LDAP 拡張モジュールでは、 ldap_batch_modify() 関数に不明な変更タイプを渡すと、 致命的なエラーにならず、 Error 例外をスローするようになりました。

mbstring 拡張モジュールでは、 mb_ereg() 関数と mb_eregi() 関数が、 'e' オプションを使い、かつ 不正な PHP の式が渡された場合に ParseError 例外をスローするようになりました。

Mcrypt 拡張モジュールでは、 mcrypt_encrypt() と mcrypt_decrypt() 関数が mcrypt を初期化できなかった場合に 致命的なエラーにならず、 Error 例外をスローするようになりました。

mysqli 拡張モジュールでは、 不正なプロパティを読み出そうとしたり、 読み取り専用のプロパティに書き込もうとしたりすると、 致命的なエラーにならず、 Error 例外をスローするようになりました。

Reflection 拡張モジュールでは、 リフレクションオブジェクトを取得できなかったり、 オブジェクトのプロパティを取得できなかったりすると、 致命的なエラーにならず、 Error 例外をスローするようになりました。

Session 拡張モジュールでは、 セッションIDに文字列を返さないカスタムのセッションハンドラは、 セッションIDを生成しなければならない関数を呼んだ際に 致命的なエラーにならず、 Error 例外をスローするようになりました。

SimpleXML 拡張モジュールでは、 名前が付いていない、または 重複した属性を作ろうとすると、 致命的なエラーにならず、 Error 例外をスローするようになりました。

SPL 拡張モジュールでは、 SplDirectory オブジェクトを clone しようとすると、 致命的なエラーにならず、 Error 例外をスローするようになりました。 同じように、オブジェクトを繰り返している時に ArrayIterator::append() を呼び出すと、 Error 例外をスローするようになりました。

standard 拡張モジュールでは、 assert()関数 の 最初のパラメーターに string 型の引数が与えられた場合、 かつ PHP のコードが不正だった場合に キャッチ可能な致命的なエラーではなく、 ParseError 例外をスローするようになりました。 同じように、 クラススコープの外側から forward_static_call() を呼び出すと、 Error 例外をスローするようになりました。

Tidy 拡張モジュールでは、 tidyNode を手動で作ろうとすると、 致命的なエラーにならず、 Error 例外をスローするようになりました。

WDDX 拡張モジュールでは、 シリアライズする時に循環参照が存在すると、 致命的なエラーにならず、 Error 例外をスローするようになりました。

XML-RPC 拡張モジュールでは、 シリアライズする時に循環参照が存在すると、 致命的なエラーにならず、 Error 例外をスローするようになりました。

Zip 拡張モジュールでは、 glob サポートが利用できない場合、 ZipArchive::addGlob() メソッドは 致命的なエラーにならず、 Error 例外をスローするようになりました。

字句的に束縛される変数は、名前を再利用できない

use 経由で クロージャ に束縛された変数名には、スーパーグローバル や $this またはあらゆるパラメータ と同じ名前が使えなくなりました。 たとえば、次のような関数定義はすべて致命的なエラーが発生します。

<?php
$f = function () use ($_SERVER) {};
$f = function () use ($this) {};
$f = function ($param) use ($param) {};

long2ip() のパラメータタイプの変更

long2ip() 関数は、 引数に string ではなく int を期待するようになりました。

JSON のエンコードとデコード

serialize_precision ini 設定が、 float 型の値をエンコードするときに、 シリアル化の精度を制御するようになりました。

空のキーをデコードすると、 プロパティ名が _empty_ ではなく、空のプロパティ名になります。

<?php
var_dump(json_decode(json_encode(['' => 1])));

上の例の出力は、 たとえば以下のようになります。

object(stdClass)#1 (1) {
  [""]=>
  int(1)
}

json_encode() 関数に JSON_UNESCAPED_UNICODE フラグを渡すと、 U+2028 および U+2029 がエスケープされるようになりました。

mb_ereg() および mb_eregi() 関数の引数のセマンティクスの変更

mb_ereg() 関数 と mb_eregi() 関数 の第3引数 (regs) は、 マッチするものがなかった場合、空の配列が設定されるようになりました。 これより前のバージョンでは、このパラメータは変更されませんでした。

sslv2 ストリームのサポートの削除

sslv2 ストリーム が OpenSSL から削除されました。

戻り値の型が決まっている関数で "return;" と書いてもコンパイルエラーになる

戻り値の型を宣言している関数内で、引数がないreturn文を使うと、 (戻り値の型を void と宣言していない場合) E_COMPILE_ERROR が発生するようになりました。 これは、そのreturn文に到達しない場合であっても同じです。


PHP 7.1.x で推奨されなくなる機能

ext/mcrypt

mcrypt 拡張モジュールは十年近くにわたって放置されており、極めて使いづらいものです。 そこで、この拡張モジュールを非推奨にしました。かわりに OpenSSL を使いましょう。 mcryptは PHP 7.2 でコアから削除されて、PECL に移る予定です。

mb_ereg_replace() と mb_eregi_replace() の eval オプション

mb_ereg_replace() と mb_eregi_replace() で、 パターン修飾子 e が非推奨となりました。


変更された関数

PHP コア

  • getopt() に、オプションの第三引数が追加されました。 これは参照渡しの引数で、処理対象の引数リストの次の要素のインデックスが格納されます。
  • getenv() の引数が必須ではなくなりました。 省略した場合は、現在の環境変数の内容を連想配列で返します。
  • get_headers() に新たなパラメータが追加されました。 カスタムストリームコンテキストを渡すことができます。
  • output_reset_rewrite_vars() は、セッションURLリライト変数をリセットしなくなりました。
  • parse_url() がより厳格になり、RFC3986 をサポートするようになりました。
  • unpack() にオプションの第三引数が追加されました。 アンパックの開始位置を指定することができます。

ファイルシステム

  • file_get_contents() 関数は、ストリームがシーク可能な場合、 負のシークオフセットを受け入れるようになりました。
  • tempnam() がシステムの temp ディレクトリを返す場合に、notice を発行するようになりました。

JSON

  • json_encode() に新しいオプション JSON_UNESCAPED_LINE_TERMINATORS が追加されました。 JSON_UNESCAPED_UNICODE を指定している場合に、 U+2028 と U+2029 のエスケープを無効にします。

マルチバイト文字列

  • mb_ereg() が無効なバイト列を拒否するようになりました。
  • mb_ereg_replace() が無効なバイト列を拒否するようになりました。

PDO

  • PostgreSQL 用の PDO::lastInsertId() は、 現在のセッション (postgres コネクション) で nextval がまだ呼ばれていない場合にエラーが発生するようになりました。

PostgreSQL

  • pg_last_notice() で、オプションのパラメータを使って操作を指定できるようになりました。 新しい定数 PGSQL_NOTICE_LAST、 PGSQL_NOTICE_ALL、 PGSQL_NOTICE_CLEAR のいずれかを指定します。
  • pg_fetch_all() にオプションの第二引数が追加されました。戻される結果の型を指定できます (pg_fetch_array() の第三引数と同じです)。
  • pg_select() にオプションの第四引数が追加されました。戻される結果の型を指定できます (pg_fetch_array() の第三引数と同じです)。

Session

  • session_start() 関数は、 セッションを開始できなかった場合、false を返し、 $_SESSION を初期化することはなくなりました。


その他の変更

無効な文字列による算術演算の通知

数値形式ではない文字列を使って、数値を期待する演算 (+ - * / ** % << >> | & ^ や、これらを用いた代入演算) を行おうとしたときに、 E_WARNING あるいは E_NOTICE レベルのエラーが発生するようになりました。 E_NOTICE が発生するのは、文字列が数値で始まっていながら非数値で終わる場合で、 E_WARNING が発生するのは文字列中に数値が含まれない場合です。

<?php
'1b' + 'something';

上の例の出力は以下となります。

Notice: A non well formed numeric value encountered in %s on line %d
Warning: A non-numeric value encountered in %s on line %d

八進表記のオーバーフロー時の警告

これまでのバージョンでは、八進表記のエスケープシーケンスがオーバーフローを起こしても、 警告は発生しませんでした。 PHP 7.1 以降では、この場合に E_WARNING が発生するようになりました (オーバーフローを起こした場合の振る舞いは、これまでのバージョンと変わりません)。

<?php
var_dump("\500");

上の例の出力は以下となります。

Warning: Octal escape sequence overflow \500 is greater than \377 in %s on line %d
string(1) "@"

$this の矛盾の修正

PHP において $this は特別な変数という扱いですが、 これが他の場所で変数名として使われていたり再代入されていたりしないことを、 きちんとチェックできていませんでした。 これを修正してきちんとチェックするようになったので、 $this をユーザー定義の変数名として使ったり他の値を再代入したり、 グローバル変数にしたりすることはできなくなりました。

ハッシュなしでのセッション ID の生成

セッション ID の生成時にハッシュされないようになりました。 この変更に伴い、以下の INI 項目が削除されました。

  • session.entropy_file
  • session.entropy_length
  • session.hash_function
  • session.hash_bits_per_character

また、以下のふたつの INI 項目が新たに追加されました。

  • session.sid_length - セッション ID の長さを指定します。デフォルトは 32 文字で、 これは過去のバージョンとの互換性を考慮したものです。
  • session.sid_bits_per_character - 一文字あたりに格納するビット数を指定します (つまり、これを増やすとセッション ID に使える文字の範囲が拡大します)。 デフォルトは 4 で、これは過去のバージョンとの互換性を考慮したものです。

INI ファイルの扱いに関する変更

precision

この値を -1 に設定すると、dtoa モードの 0 が使われます。 デフォルト値は 14 のままです。

serialize_precision

この値を -1 に設定すると、dtoa モードの 0 が使われます。 デフォルト値は -1 になりました。

gd.jpeg_ignore_warning

この php.ini 設定のデフォルト値は 1 になりました。 よって、デフォルトでは libjpeg の警告は無視されます。

opcache.enable_cli

この php.ini 設定のデフォルト値は、PHP 7.1.2 で 1 (有効) に変更され、 PHP 7.1.7 で 0 (無効) に戻されました。

セッションIDの生成は、CSPRNGのみから行われる

セッションID は、CSPRNG のみから生成されるようになりました。

null が許可されていた場合の TypeError メッセージがよりわかりやすく

arg_info 型をチェックする際の TypeError 例外 が、よりわかりやすいエラーメッセージを出力するようになりました。 引数の型や戻り値の型が null を許可していた場合 (デフォルト値が null だった場合や、nullable 型だった場合)、 エラーメッセージはそのことを "must be ... or null" や "must ... or be null." といった形で示すようになりました。


Windows のサポート

長いpath と UTF-8のpath のサポート

Webアプリケーションが UTF-8 に対応しているなら、追加の作業は必要ありません。 UTF-8 でないpathへの I/O に依存したアプリケーションについては、 明示的に INIディレクティブを設定する必要があります。 エンコーディングのINI設定のチェックは、コアの順番に依存します:

  • internal_encoding
  • default_charset
  • zend.multibyte

コードページを扱う関数がいくつか追加されました:

  • sapi_windows_cp_set() は、デフォルトのコードページを設定します
  • sapi_windows_cp_get() は、現在のコードページを取得します
  • sapi_windows_cp_is_utf8()
  • sapi_windows_cp_conv() は、iconv() 互換のシグネチャで、コードページ間の変換を行います。

これらの関数はスレッドセーフです。

コンソール出力のコードページは、 PHP の内部で使用されるエンコーディングに基づいて調整されます。 具体的な システム OEM のコードページによっては、 目に見える出力は正しいかもしれませんし、正しくないかもしれません。 たとえば、OEM コードページ 437 のシステム上での デフォルトの cmd.exe は、1251, 1252, 1253 や、 他のいくつかのコードページを出力しますが、 これらは UTF-8 で表示すれば正しく表示できます。 同じシステム上で、20932 のようなコードページ上の文字は、 正しく表示できません。 これは、コードページにまつわる特定のシステムのルールや、 フォントの互換性、そして特定のコンソールプログラムが関係しています。 PHP は、php.ini から読み取ったエンコーディングのルールに沿って、 コンソールのコードページを自動的に設定します。 cmd.exe 以外のコンソールを使う場合、 ケースによってはより良い体験が得られるかもしれません。

それでもなお知っておくべきなのは、 リクエストの処理が始まったあとの実行時にコードページを変更すると、 CLI 上では予測できない副作用をもたらす可能性があることです。 好ましいやり方は、Unicode をサポートしていない PHP CLI がコンソールのエミュレータとして使われている場合、必須ではないものの、 php.ini を使うことでコンソールのコードページを変更することを避けることです。 これを達成する最良のやり方は、デフォルト、 または内部エンコーディングの設定を ANSI コードページにすることです。 別のやり方として、INI ディレクティブの output_encoding と input_encoding を必要なコードページに設定することがあります。しかしこの場合、 内部のコードページと I/O のコードページが異なることが原因で、 文字化けを引き起こしがちです。レアケースではありますが、 PHP が偶然綺麗にクラッシュしたとしても、 オリジナルのコンソールのコードページがリストアされない可能性もあります。 この場合、手動でリストアする方法として、chcp コマンドが使えます。

DBCS システムについては、特別に知っておくべきことがあります。 実行時に ini_set() を使ってコードページを変更すると、 表示上の問題を引き起こす可能性があることです。 DBCS でないシステムとの違いは、 コンソールのセルふたつ分を表示に要求する拡張文字を表示する場合です。 場合によっては、フォントのグリフセットへの文字のマッピングが発生するのに、 実際のフォントは変わらないといったことが起こります。 これは DBCS システムの性質によって起こります。 この手の表示の問題を避けるもっとも簡単な方法は、 コードページの変更に ini_set() を使わないことです。

ストリームで UTF-8 がサポートされたことによって、 PHP スクリプトは ASCII や ANSI のファイル名にもはや縛られなくなりました。 これは CLI の枠を越えたサポートです。他の SAPI については、 対応するサーバーのドキュメントを見ると有益でしょう。

長いパス名のサポートは透過的です。 260バイトより長いパス名には、 自動的に \\?\ という prefix が付きます。 パス名の最大の長さは、2048バイトに制限されています。 パスセグメントの長さの制限 (basepath の長さ) はまだ続いていることも知っておいてください。

移植性を最大にするために、ファイル名や I/O 、 そして他の関連するトピックを UTF-8 で扱うことを強くお勧めします。 それに加えて、コンソールアプリケーションについては、 TrueType フォントを使うことが好ましいです。 また、コードページの変更に ini_set() を使うことは推奨されません。

readline

readline 拡張モジュール が » WinEditLine ライブラリ を通じてサポートされました。 これにより、インタラクティブな CLI シェルもサポートされました (php.exe -a)。

PHP_FCGI_CHILDREN

環境変数 PHP_FCGI_CHILDREN が尊重されるようになりました。 この環境変数が定義されていた場合、最初の php-cgi.exe プロセスが指定された数の子プロセスを実行します。 これらは同じTCPソケットを共有します。

ftok()

ftok() 関数のサポートが追加されました。


PHP 5.6.x から PHP 7.0.x への移行

目次

  • 下位互換性のない変更点
  • 新機能
  • PHP 7.0.x で推奨されなくなる機能
  • 変更された関数
  • 新しい関数
  • 新しいクラスおよびインターフェイス
  • 新しいグローバル定数
  • SAPI モジュールの変更
  • 削除された拡張モジュールおよび SAPI
  • その他の変更

PHP 7.0 は新しいメジャーバージョンではありますが、 過去のバージョンからの移行をできるだけスムーズに行えるよう心がけています。 このリリースで主に注力したのは、これまでのバージョンで廃止予定とされていた機能の削除や、 言語としての一貫性の向上です。

互換性がない変更 が多少あり、また、考慮すべき 新機能 があります。よって、 実運用環境の PHP をこのバージョンにあげる前に、あらゆるコードをテストすべきです。


下位互換性のない変更点

エラーや例外の取り扱いの変更

fatal error や recoverable fatal error の多くが、PHP 7 では例外に変換されるようになりました。 これらの例外は Error クラスを継承したもので、 このクラスは Throwable インターフェイスを実装しています。 この新しいインターフェイスを、すべての例外が実装しています。

エラーではなく例外がスローされるようになるということは、自作のエラーハンドラは呼び出されなくなるということです (Error 例外をキャッチしなかった場合は、fatal エラーが発生します)。

PHP 7 におけるエラーハンドリングの詳細な説明は PHP 7 のエラー を参照ください。 この移行ガイドでは、下位互換性のない変更点を列挙するだけにとどめます。

set_exception_handler() が常に Exception オブジェクトを受け取るとは限らない

set_exception_handler() で登録した例外ハンドラの実装で Exception 型を宣言している場合は、 Error オブジェクトがスローされると fatal エラーが発生します。

PHP 5 と PHP 7 の両方で動くハンドラを書く場合は、ハンドラで型宣言をしてはいけません。 PHP 5 で動いていたコードを移行する際に、そのコードが PHP 7 でだけ動けばいいのなら、 Exception 型で宣言している部分を単純に Throwable 型に置換するだけでかまいません。

<?php
// PHP 5 でのこの実装は、そのままでは PHP 7 では動きません
function handler(Exception $e) { ... }
set_exception_handler('handler');

// PHP 5 と 7 の両方で動きます
function handler($e) { ... }

// PHP 7 でだけ動きます
function handler(Throwable $e) { ... }
?>

内部のコンストラクタは、失敗したときに常に例外をスローする

これまでは、コンストラクタの処理が失敗した際に、 null を返したり使用不能なオブジェクトを返したりする内部クラスがありました。 PHP 7 では、同様の場合に Exception をスローするようになりました。 ユーザー定義のクラスでは以前からそうすべきだとされていたことです。

パースエラーが発生すると ParseError をスローする

パースエラーが発生すると ParseError オブジェクトをスローするようになりました。 eval() のエラーハンドリングをする際には、catch ブロックを用意してこのエラーを処理しなければいけません。

E_STRICT 通知の深刻度の変更

すべての E_STRICT 通知が、改めて別のレベルに移動しました。 定数 E_STRICT はそのまま残っているので、 error_reporting(E_ALL|E_STRICT) のような呼び出しがエラーになることはありません。

E_STRICT 通知の深刻度の変更
状況 | 新しいレベル / 挙動
Indexing by a resource | E_NOTICE
Abstract static methods | 通知は削除され、エラーにはならない
"Redefining" a constructor | 通知は削除され、エラーにはならない
Signature mismatch during inheritance | E_WARNING
Same (compatible) property in two used traits | 通知は削除され、エラーにはならない
Accessing static property non-statically | E_NOTICE
Only variables should be assigned by reference | E_NOTICE
Only variables should be passed by reference | E_NOTICE
Calling non-static methods statically | E_DEPRECATED

変数の取り扱いの変更

PHP 7 では、抽象構文木を使ってソースファイルをパースするようになりました。 そのおかげで言語としてのさまざまな改良ができるようになりました。 これまでの PHP が使っていたパーサーでは不可能だったこともできるようになったからです。 しかしその結果、一貫性を保つために一部の機能を削除することになりました。 これは、下位互換性を損ねるものです。 このセクションでは、それらについて説明します。

変数やプロパティ、メソッドへの間接的なアクセスの扱いの変更

変数やプロパティそしてメソッドへの間接的なアクセスを、厳密に左から右の順で評価するようになりました。 以前のバージョンでは、場合によって評価の順が逆転することもありました。 評価順の変更を、以下の表にまとめます。

間接的なアクセスの評価順の変更
式 | PHP 5 での解釈 | PHP 7 での解釈
$$foo['bar']['baz'] | ${$foo['bar']['baz']} | ($$foo)['bar']['baz']
$foo->$bar['baz'] | $foo->{$bar['baz']} | ($foo->$bar)['baz']
$foo->$bar['baz']() | $foo->{$bar['baz']}() | ($foo->$bar)['baz']()
Foo::$bar['baz']() | Foo::{$bar['baz']}() | (Foo::$bar)['baz']()

今までのバージョンにおける右から左の評価を想定しているコードは、 波括弧を使って評価順を明示するように (表の中央列のように) 書き直す必要があります。 そうすれば、PHP 7.x との互換性を保ちつつ、PHP 5.x との下位互換性も維持できます。

これは、global キーワードにも影響します。 必要であれば、波括弧構文を使えばこれまでのバージョンでの挙動を再現できます。

<?php
function f() {
// PHP 5 でしか使えません
global $$foo->bar;

// PHP 5 と PHP 7 の両方で使えます
global ${$foo->bar};
}
?>

list() の取り扱いの変更

list() での変数の代入が、逆順ではなくなる

list() における変数への代入が定義された順番どおりに行われるようになりました。 今までのように逆順にはなりません。 この変更の影響を受けるのは、list() を [] 演算子と組み合わせて使うときくらいでしょう。その例を示します。

<?php
list($a[], $a[], $a[]) = [1, 2, 3];
var_dump($a);
?>

上の例の PHP 5 での出力は、このようになります。

array(3) {
  [0]=>
  int(3)
  [1]=>
  int(2)
  [2]=>
  int(1)
}

上の例の PHP 7 での出力は、このようになります。

array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}

一般論として、 list() での代入がどの順で行われるかに依存するコードは書かないことを推奨します。 代入の順番は、実装の都合によって今後も変わる可能性があるからです。

空の list() の廃止

空の list() を作ることはできなくなりました。 次のようなコードは PHP 7 では使えません。

<?php
list() = $a;
list(,,) = $a;
list($x, list(), $y) = $a;
?>
list() は文字列を展開しない

list() は文字列変数を展開できなくなりました。 かわりに str_split() を使いましょう。

参照による代入で自動的に作成した配列要素の並び順の変更

参照による代入で配列の要素を自動的に作成した場合の、 要素の並び順が変更されました。 以下に例を示します。

<?php
$array = [];
$array["a"] =& $array["b"];
$array["b"] = 1;
var_dump($array);
?>

上の例の PHP 5 での出力は、このようになります。

array(2) {
  ["b"]=>
  &int(1)
  ["a"]=>
  &int(1)
}

上の例の PHP 7 での出力は、このようになります。

array(2) {
  ["a"]=>
  &int(1)
  ["b"]=>
  &int(1)
}

関数のパラメータを括弧で囲んでもその振る舞いは変わらない

PHP 5 では、関数のパラメータを冗長な括弧で囲んでおくと、 関数のパラメータを参照渡しにした場合の警告を抑止することができました。 PHP 7 では、たとえ括弧で囲んでも警告が常に発生します。

<?php
function getArray() {
return [1, 2, 3];
}

function squareArray(array &$a) {
foreach ($a as &$v) {
$v **= 2;
}
}

// PHP 7 では警告が発生します
squareArray((getArray()));
?>

上の例の出力は以下となります。

Notice: Only variables should be passed by reference in /tmp/test.php on line 13

foreach の変更

foreach の振る舞いが多少変わりました。 主に、内部の配列ポインタの扱いや、反復処理中の配列の変更に関する部分です。

foreach は内部の配列ポインタを変更しない

PHP 7 より前のバージョンでは、foreach で配列を反復処理する際に、内部の配列ポインタを変更していました。 PHP 7 ではそのようにはならず、以下の例のようになります。

<?php
$array = [0, 1, 2];
foreach ($array as &$val) {
var_dump(current($array));
}
?>

上の例の PHP 5 での出力は、このようになります。

int(1)
int(2)
bool(false)

上の例の PHP 7 での出力は、このようになります。

int(0)
int(0)
int(0)

値渡しの foreach は、配列のコピーを使って操作を進める

デフォルトの値渡しモードの場合の foreach は、 配列そのものではなくそのコピーを使って反復処理を進めるようになりました。 つまり、処理中に配列を書き換えた場合でも、反復処理の対象となる値には影響が及びません。

参照渡しの foreach の、反復処理の振る舞いを改良

参照渡しでの foreach における、 処理中の配列への変更の追跡が改良されました。 たとえば、処理中の配列に新たな要素を追加した場合に、 追加した新たな要素も反復処理の対象に含まれるようになります。

<?php
$array = [0];
foreach ($array as &$val) {
var_dump($val);
$array[1] = 1;
}
?>

上の例の PHP 5 での出力は、このようになります。

int(0)

上の例の PHP 7 での出力は、このようになります。

int(0)
int(1)

Traversable でないオブジェクトの反復処理

Traversable ではないオブジェクトの反復処理の挙動が、 配列を参照渡しで反復処理したときと同じようになりました。 反復処理中の配列を変更したときの挙動の改良 も適用され、処理中のオブジェクトにプロパティを追加したり削除したりした場合に、 それが反復処理に反映されます。

int の取り扱いの変更

無効な形式の八進リテラル

以前のバージョンでは、無効な数値が八進リテラルに含まれている場合は、 単純にそれを無視していました (たとえば 0128 は 012 として扱っていました)。 PHP 7 では、このような場合にパースエラーが発生します。

負のビットシフト

ビットシフトに負の数を指定すると、 ArithmeticError をスローするようになりました。

<?php
var_dump(1 >> -1);
?>

上の例の PHP 5 での出力は、このようになります。

int(0)

上の例の PHP 7 での出力は、このようになります。

Fatal error: Uncaught ArithmeticError: Bit shift by negative number in /tmp/test.php:2
Stack trace:
#0 {main}
  thrown in /tmp/test.php on line 2

範囲外のビットシフト

int のビット幅を超えるビットシフト (左右問わず) を行うと、結果は常に 0 となります。 以前のバージョンでは、このときの振る舞いはアーキテクチャに依存していました。

ゼロ除算の挙動の変更

以前のバージョンでは、除算演算子 (/) や剰余演算子 (%) の除数に 0 を使うと、E_WARNING が発生して結果は false となっていました。 PHP 7 では、除算演算子の返す結果は float で、 +INF、-INF あるいは NAN のいずれかとなります。 これは、IEEE 754 で指定された挙動です。 剰余演算子については E_WARNING が発生しなくなり、 DivisionByZeroError 例外をスローするようになりました。

<?php
var_dump(3/0);
var_dump(0/0);
var_dump(0%0);
?>

上の例の PHP 5 での出力は、このようになります。

Warning: Division by zero in %s on line %d
bool(false)

Warning: Division by zero in %s on line %d
bool(false)

Warning: Division by zero in %s on line %d
bool(false)

上の例の PHP 7 での出力は、このようになります。

Warning: Division by zero in %s on line %d
float(INF)

Warning: Division by zero in %s on line %d
float(NAN)

PHP Fatal error:  Uncaught DivisionByZeroError: Modulo by zero in %s line %d

文字列の取り扱いの変更

十六進数値形式の文字列は数値とはみなさない

十六進形式の数値を含む文字列は数値とはみなされなくなりました。 以下に例を示します。

<?php
var_dump("0x123" == "291");
var_dump(is_numeric("0x123"));
var_dump("0xe" + "0x1");
var_dump(substr("foo", "0x1"));
?>

上の例の PHP 5 での出力は、このようになります。

bool(true)
bool(true)
int(15)
string(2) "oo"

上の例の PHP 7 での出力は、このようになります。

bool(false)
bool(false)
int(0)

Notice: A non well formed numeric value encountered in /tmp/test.php on line 5
string(3) "foo"

filter_var() を使えば、 文字列が十六進数値形式であるかどうかをチェックでき、 その文字列を int に変換することもできます。

<?php
$str = "0xffff";
$int = filter_var($str, FILTER_VALIDATE_INT, FILTER_FLAG_ALLOW_HEX);
if (false === $int) {
throw new Exception("Invalid integer!");
}
var_dump($int); // int(65535)
?>

\u{ がエラーの原因になることがある

Unicode コードポイントのエスケープ構文 が導入されたことにより、\u{ のあとに無効なシーケンスが続く文字列が fatal error となる可能性があります。 これを回避するには、先頭のバックスラッシュをエスケープする必要があります。

削除された関数

call_user_method() および call_user_method_array()

これらの関数は PHP 4.1.0 で非推奨となり、 call_user_func() および call_user_func_array() を使うことが推奨されていました。 あるいは 可変関数 や ... 演算子を使うことを検討しましょう。

ereg* 系のすべての関数

ereg 関数はすべて削除されました。かわりに PCRE を使うことを推奨します。

mcrypt のエイリアス

非推奨の mcrypt_generic_end() 関数が削除されました。 かわりに mcrypt_generic_deinit() を使いましょう。

さらに、非推奨の mcrypt_ecb()、
mcrypt_cbc()、mcrypt_cfb()、
mcrypt_ofb() も削除されました。
mcrypt_decrypt() に、適切な
MCRYPT_MODE_* 定数を組み合わせて使いましょう。

すべての ext/mysql 関数

ext/mysql のすべての関数が削除されました。 その他の MySQL API の選択肢については MySQL API の選択 を参照ください。

すべての ext/mssql 関数

ext/mssql のすべての関数が削除されました。 代替となる選択肢については、以下を参照ください。

  • PDO_SQLSRV
  • PDO_ODBC
  • SQLSRV
  • Unified ODBC API

intl のエイリアス

非推奨のエイリアス datefmt_set_timezone_id() および
IntlDateFormatter::setTimeZoneID() が削除されました。
かわりに datefmt_set_timezone() および
IntlDateFormatter::setTimeZone() を使いましょう。

set_magic_quotes_runtime()

set_magic_quotes_runtime() およびそのエイリアスである magic_quotes_runtime() が削除されました。 これらは PHP 5.3.0 で非推奨となり、 PHP 5.4.0 でマジッククォートが廃止された時点で事実上無意味になっていました。

set_socket_blocking()

非推奨のエイリアス set_socket_blocking() が削除されました。 かわりに stream_set_blocking() を使いましょう。

PHP-FPM における dl()

dl() が PHP-FPM で使えなくなりました。 CLI や embed SAPI では今でも使えます。

GD Type1 関数群

GD 拡張モジュールから、PostScript Type1 フォントのサポートが削除されました。 その結果として、以下の関数群が削除されました。

  • imagepsbbox()
  • imagepsencodefont()
  • imagepsextendfont()
  • imagepsfreefont()
  • imagepsloadfont()
  • imagepsslantfont()
  • imagepstext()

かわりに、TrueType フォントやそれに関連する関数群を使いましょう。

削除された INI 項目

削除された機能

以下の INI 項目は、関連する機能の削除に伴って削除されました。

  • always_populate_raw_post_data
  • asp_tags

xsl.security_prefs

xsl.security_prefs が削除されました。 かわりに XsltProcessor::setSecurityPrefs() メソッドを用いて、プロセッサ単位のセキュリティ設定を制御しましょう。

下位互換性のないその他の変更

新しいオブジェクトを参照渡しで代入できない

new 文の結果を参照渡しで変数に代入することができなくなりました。 by reference:

<?php
class C {}
$c =& new C;
?>

上の例の PHP 5 での出力は、このようになります。

Deprecated: Assigning the return value of new by reference is deprecated in /tmp/test.php on line 3

上の例の PHP 7 での出力は、このようになります。

Parse error: syntax error, unexpected 'new' (T_NEW) in /tmp/test.php on line 3

無効なクラス名、インターフェイス名、トレイト名

以下の名前は、クラスやインターフェイスそしてトレイトの名前としては使えなくなりました。

  • bool
  • int
  • float
  • string
  • null
  • true
  • false

さらに、以下に挙げる名前も使うべきではありません。 PHP 7.0 の時点ではまだエラーにはなりませんが、 これらの名前は将来のバージョン用に予約されており、いずれ使えなくなると考えるべきです。

  • resource
  • object
  • mixed
  • numeric

ASP タグと script タグの廃止

ASP 形式のタグや script タグを使って PHP コードを囲むことはできなくなりました。 この影響を受けるのは、以下のタグです。

削除された ASP タグおよび script タグ
開始タグ | 終了タグ
<% | %>
<%= | %>
<script language="php"> | </script>

非互換のコンテキストからの呼び出しの削除

既に PHP 5.6 で非推奨になっていますが、 static ではないメソッドに対して非互換のコンテキストで static 呼び出しを行うと、 呼ばれた側のメソッドが未定義の $this 変数を持つことになって警告が発生します。

<?php
class A {
public function test() { var_dump($this); }
}

// クラスAを継承して「いない」ことに注目
class B {
public function callNonStaticMethodOfA() { A::test(); }
}

(new B)->callNonStaticMethodOfA();
?>

上の例の PHP 5.6 での出力は、このようになります。

Deprecated: Non-static method A::test() should not be called statically, assuming $this from incompatible context in /tmp/test.php on line 8
object(B)#1 (0) {
}

上の例の PHP 7 での出力は、このようになります。

Deprecated: Non-static method A::test() should not be called statically in /tmp/test.php on line 8

Notice: Undefined variable: this in /tmp/test.php on line 3
NULL

yield が右代入演算子に

yield で括弧が必須ではなくなり、右代入演算子に変わりました。 優先順位は print と => の間になります。 これによって、以下のように振る舞いが変わります。

<?php
echo yield -1;
// 以前はこのように解釈されました
echo (yield) - 1;
// PHP 7 ではこのように解釈されます
echo yield (-1);

yield $foo or die;
// 以前はこのように解釈されました
yield ($foo or die);
// PHP 7 ではこのように解釈されます
(yield $foo) or die;
?>

括弧を使えば、曖昧さを排除できます。

同じ名前のパラメータをひとつの関数に複数定義できない

関数内の複数のパラメータを同じ名前にすることができなくなりました。 たとえば次のようなメソッドは E_COMPILE_ERROR となります。

<?php
function foo($a, $b, $unused, $unused) {
//
}
?>

引数を調べる関数は、パラメータの その時点での 値を報告する

func_get_arg(), func_get_args(), debug_backtrace() といった関数や例外時のバックトレースで得られる値が、 パラメータとして渡されたときの値ではなくなりました。 その時点での値が得られるようになります (つまり、パラメータとして渡された値から変更されている可能性があります)。

<?php
function foo($x) {
$x++;
var_dump(func_get_arg(0));
}
foo(1);?>

上の例の PHP 5 での出力は、このようになります。

1

上の例の PHP 7 での出力は、このようになります。

2

Switch 文に複数の default ブロックを書けない

ひとつの switch 文の中に、複数の default ブロックを定義することができなくなりました。 たとえば次の switch 文は E_COMPILE_ERROR になります。

<?php
switch (1) {
default:
break;
default:
break;
}
?>

$HTTP_RAW_POST_DATA の削除

$HTTP_RAW_POST_DATA が使えなくなりました。かわりに php://input ストリームを使いましょう。

INI ファイルにおける # 形式のコメントの削除

INI ファイルにおいて # で始まる行をコメントとする機能が削除されました。 かわりに ; を使いましょう。 この変更は、php.ini だけではなく、 parse_ini_file() や parse_ini_string() が扱うファイルにもあてはまります。

JSON 拡張モジュールが JSOND に置き換わる

JSON 拡張モジュールが JSOND に置き換わりました。 下位互換性を損ねるちょっとした変更が二点あります。 まず、数値の最後を小数点で終えることができなくなりました (つまり、 34. とすることはできず、34.0 あるいは 34 としなければいけません)。 次に、科学記法を使う際に、指数記号 e を小数点の直後に置くことができなくなりました (つまり、3.e3 とすることはできず、 3.0e3 あるいは 3e3 としなければいけません)。 最後に、空の文字列は妥当な JSON だとみなされなくなりました。

内部関数がオーバーフローしたときの挙動

これまでのバージョンでは、浮動小数点数値が大きすぎて整数として表せない場合に、 float から integer に変換した結果を黙って切り詰めていました。 PHP 7 では E_WARNING が発生し、null を返します。

カスタムセッションハンドラの戻り値の修正

カスタムセッションハンドラとして実装した関数が false あるいは -1 を返すとき、fatal error が発生します。 この関数が boolean 値か -1, あるいは 0 以外を返す場合は、その関数は失敗して E_WARNING が発生します。

同値な要素の並び順

内部的なソートアルゴリズムが改良されたことに伴って、 比較したときに等しいとみなされる要素の並び順が以前とは変わるかもしれません。

注意:

同値な要素の並び順に依存するコードは書かないようにしましょう。 その並び順がいつまでも同じであるとは限りません。

break 文と continue 文の位置の間違い

ループまたは switch 制御構造の外の break および continue 文は、 以前のように実行時ではなくコンパイル時に検出され、 E_COMPILE_ERROR を起こします。

Mhash はもう拡張モジュールではありません

Mhash 拡張は Hash 拡張に完全に統合されました。
したがって、extension_loaded() で Mhash サポートを検出できなくなりました。
代わりに function_exists() を使用してください。
さらに、Mhash は get_loaded_extensions() および関連機能により報告されなくなりました。

declare(ticks)

declare(ticks) ディレクティブは、異なるコンパイル単位にリークしなくなりました。


新機能

スカラー型宣言

スカラー 型宣言 には二つの方式があります。デフォルトの自動変換(coercive) モードと、 厳密に判断する strict モードです。 パラメータとして、 文字列 (string)、整数 (int)、浮動小数点数 (float)、boolean (bool) といった型をいずれかの方式で強制できるようになりました。 これらは、PHP 5 で導入された型宣言 (クラス名やインターフェイス、配列そして callable) を強化するものです。

<?php
// デフォルトのモード
function sumOfInts(int ...$ints)
{
return array_sum($ints);
}

var_dump(sumOfInts(2, '3', 4.1));

上の例の出力は以下となります。

int(9)

strict モードを有効にするには、ファイルの先頭に declare ディレクティブを置く必要があります。 つまり、スカラー型を厳密に扱うかどうかは、ファイル単位で定めるということです。 このディレクティブは、パラメータの型宣言だけでなく、関数の戻り値の型 (戻り値の型宣言を参照ください) や PHP の標準関数、そして拡張モジュールの関数にも影響を及ぼします。

スカラー型宣言に関するドキュメントやサンプルについては、 型宣言 を参照ください。

戻り値の型宣言

PHP 7 では、 戻り値の型宣言 もできるようになりました。 引数の型宣言 と同様に、戻り値の型宣言では、関数が戻す値がどの型になるかを宣言します。 戻り値の型宣言で使える 型 は、引数の型宣言で使えるものと同じです。

<?php

function arraysSum(array ...$arrays): array
{
return array_map(function(array $array): int {
return array_sum($array);
}, $arrays);
}

print_r(arraysSum([1,2,3], [4,5,6], [7,8,9]));

上の例の出力は以下となります。

Array
(
    [0] => 6
    [1] => 15
    [2] => 24
)

詳細なドキュメントやサンプルについては、 戻り値の型宣言. を参照ください。

Null 合体演算子

null 合体演算子 (??) がシンタックスシュガーとして追加されました。 三項演算子と isset() を組み合わせる よくありがちなパターンを、より簡単に書くためのものです。 この演算子は、もし第一オペランドが非 null の値であればそれを返し、 そうでない場合は第二オペランドを返します。

<?php
// $_GET['user'] を取得します。もし存在しない場合は
// 'nobody' を用います。
$username = $_GET['user'] ?? 'nobody';
// 上のコードは、次のコードと同じ意味です。
$username = isset($_GET['user']) ? $_GET['user'] : 'nobody';

// 合体演算子を連結することもできます。次のように書くと、
// $_GET['user']、$_POST['user'] そして 'nobody'
// の順に調べて、非 &null; が定義されている最初の値を返します。
$username = $_GET['user'] ?? $_POST['user'] ?? 'nobody';
?>

宇宙船演算子

宇宙船演算子は、二つの式を比較するために使うものです。 $a が $b より大きい場合は 1、 $a と $b が等しい場合は 0、 $a が $b より小さい場合は -1 をそれぞれ返します。 比較の際には、 PHP 型の比較表 のルールを用います。

<?php
// 整数値
echo 1 <=> 1; // 0
echo 1 <=> 2; // -1
echo 2 <=> 1; // 1

// 浮動小数点数値
echo 1.5 <=> 1.5; // 0
echo 1.5 <=> 2.5; // -1
echo 2.5 <=> 1.5; // 1

// 文字列
echo "a" <=> "a"; // 0
echo "a" <=> "b"; // -1
echo "b" <=> "a"; // 1
?>

define() を用いた配列定数の定義

define() で配列の定数を定義できるようになりました。 PHP 5.6 までのバージョンでは、配列の定数は const でしか定義できませんでした。

<?php
define('ANIMALS', [
'dog',
'cat',
'bird'
]);

echo ANIMALS[1]; // "cat" と出力します
?>

無名クラス

無名クラスをサポートするようになりました。new class を使って利用します。 その場限りの使い捨てのオブジェクトなどで、完全なクラス定義のかわりとして使えます。

<?php
interface Logger {
public function log(string $msg);
}

class Application {
private $logger;

public function getLogger(): Logger {
return $this->logger;
}

public function setLogger(Logger $logger) {
$this->logger = $logger;
}
}

$app = new Application;
$app->setLogger(new class implements Logger {
public function log(string $msg) {
echo $msg;
}
});

var_dump($app->getLogger());
?>

上の例の出力は以下となります。

object(class@anonymous)#2 (0) {
}

詳細なドキュメントは 無名クラス を参照ください。

Unicode コードポイントエスケープ構文

Unicode のコードポイントを十六進形式で受け取って、 それを UTF-8 で (ダブルクォートで囲まれた文字列あるいはヒアドキュメントとして) 出力します。 妥当な形式のコードポイントならあらゆるものが使えます。先頭のゼロは省略してもかまいません。

<?php

echo "\u{aa}", PHP_EOL;
echo "\u{0000aa}", PHP_EOL;

echo "\u{9999}", PHP_EOL;

echo <<<EOT
\u{01f418}
EOT;

?>

上の例の出力は以下となります。

a
a (先頭のゼロを省略せずに書いても、前の行と同じ結果になります)
香

Closure::call()

Closure::call() は、オブジェクトのスコープをクロージャに一時的に束縛して実行するための、 より高性能で簡潔な方法です。

<?php
class A {private $x = 1;}

// 以前のバージョンのコード
$getX = function() {return $this->x;};
$getXCB = $getX->bindTo(new A, 'A'); // 中間クロージャが必要
echo $getXCB();

// PHP 7 以降でのコード
$getX = function() {return $this->x;};
echo $getX->call(new A);

上の例の出力は以下となります。

1
1

unserialize() のフィルタリング

この仕組みは、信頼できないデータからオブジェクトを復元する際に、 よりセキュリティを高められるようにするために用意されたものです。 アンシリアライズ可能なクラスの一覧をホワイトリストとして定義することで、 コードインジェクション攻撃を防ぎます。

<?php

// オブジェクトはすべて、__PHP_Incomplete_Class のオブジェクトに変換します
$data = unserialize($foo, ["allowed_classes" => false]);

// MyClassとMyClass2以外のすべてのオブジェクトを、__PHP_Incomplete_Class のオブジェクトに変換します
$data = unserialize($foo, ["allowed_classes" => ["MyClass", "MyClass2"]]);

// デフォルト (第二引数を省略した場合) の挙動は以下のようになり、すべてのオブジェクトをそのまま復元します
$data = unserialize($foo, ["allowed_classes" => true]);

IntlChar

ICU のさらなる機能を利用するために、新しく IntlChar クラスが追加されました。このクラスには数々の static メソッドと定数が定義されており、 これらを使って Unicode の文字を操作できます。

<?php

printf('%x', IntlChar::CODEPOINT_MAX);
echo IntlChar::charName('@');
var_dump(IntlChar::ispunct('!'));

上の例の出力は以下となります。

10ffff
COMMERCIAL AT
bool(true)

このクラスを使うには、Intl 拡張モジュールをインストールしなければいけません。

Expectation

Expectations は、かつての assert() 関数を、下位互換性を保ったまま拡張したものです。 これを用いると、コストをかけずに実運用コードの中にアサーションを組み込めます。 そして、アサーションが失敗した際に自作の例外をスローできるようになります。

これまでの API も下位互換性を保つために維持されていますが、 assert() は言語構造となりました。 最初のパラメータには、単に評価対象の文字列や bool 値を指定するだけではなく、式を渡せます。

<?php
ini_set('assert.exception', 1);

class CustomError extends AssertionError {}

assert(false, new CustomError('Some error message'));
?>

上の例の出力は以下となります。

Fatal error: Uncaught CustomError: Some error message

開発環境および運用環境での設定方法などの詳細については、 言語構造 assert() のマニュアルを参照ください。

use 宣言のグループ化

複数のクラスや関数そして定数を同じ namespace からインポートする際に、 単一の use 文にまとめられるようになりました。

<?php
// 以前のバージョンのコード
use some\namespace\ClassA;
use some\namespace\ClassB;
use some\namespace\ClassC as C;

use function some\namespace\fn_a;
use function some\namespace\fn_b;
use function some\namespace\fn_c;

use const some\namespace\ConstA;
use const some\namespace\ConstB;
use const some\namespace\ConstC;

// PHP 7 以降のコード
use some\namespace\{ClassA, ClassB, ClassC as C};
use function some\namespace\{fn_a, fn_b, fn_c};
use const some\namespace\{ConstA, ConstB, ConstC};
?>

ジェネレータでの return

PHP 5.5 で導入されたジェネレータの機能拡張です。 ジェネレータの内部で return 文が使えるようになりました。 これを使えば、ジェネレータが最終的に返す式を指定できます (参照を返すことはできません)。 この値を取得するには、新しいメソッド Generator::getReturn() を用います。 このメソッドを使うのは、ジェネレータが値の生成を終えた後の一度だけになるでしょう。

<?php

$gen = (function() {
yield 1;
yield 2;

return 3;
})();

foreach ($gen as $val) {
echo $val, PHP_EOL;
}

echo $gen->getReturn(), PHP_EOL;

上の例の出力は以下となります。

1
2
3

ジェネレータの最終値を明示的に返せる機能は、あれば便利なものです。 ジェネレータを実行したクライアント側のコードが、 ジェネレータが最後に返す値 (何らかのコルーチンの計算結果) を特別扱いできるようになるからです。 「取得した値が最後の値かどうかをまず調べて、最後であれば特別扱いする」 という処理をクライアント側で書くよりは、ずっとシンプルになります。

ジェネレータの委譲

ジェネレータを、別のジェネレータや Traversable オブジェクトそして配列に委譲できるようになりました。 外側のジェネレータに決まり文句を書いたりする必要はなく、単に yield from 構文を使うだけです。

<?php
function gen()
{
yield 1;
yield 2;
yield from gen2();
}

function gen2()
{
yield 3;
yield 4;
}

foreach (gen() as $val)
{
echo $val, PHP_EOL;
}
?>

上の例の出力は以下となります。

1
2
3
4

intdiv() による整数の除算

新しい intdiv() 関数は、 オペランドに対して整数の除算を行い、その結果を返します。

<?php
var_dump(intdiv(10, 3));
?>

上の例の出力は以下となります。

int(3)

セッションのオプション

session_start() にオプションの配列を渡せるようになりました。 これは、php.ini などで設定した session 設定ディレクティブ を上書きします。

新たな設定オプション session.lazy_write をサポートするようになりました。これはデフォルトで有効になっており、 セッションのデータが書き換えられたときにだけセッションファイルを上書きします。 また、read_and_close も追加されました。 このオプションは session_start() だけに渡せるもので、 セッションデータを読み込んだら何も変更せずその場でクローズするよう指示します。

たとえば、 session.cache_limiter を private にして、読み込んだセッションをすぐにクローズさせるには次のようにします。

<?php
session_start([
'cache_limiter' => 'private',
'read_and_close' => true,
]);
?>

preg_replace_callback_array()

新しい preg_replace_callback_array() 関数は、 preg_replace_callback() 関数を使ったコードをよりすっきりと書けるようにするものです。 これまでのバージョンの PHP では、正規表現ごとにコールバックを実行したければ、 コールバック関数が分岐だらけになってしまっていました。

PHP 7 以降では、個々の正規表現に対するコールバックを連想配列で登録できるようになりました。 連想配列のキーが正規表現で、その値がコールバックとなります。

CSPRNG 関数

暗号学的にセキュアな整数値および文字列を生成する、 プラットフォームに依存しない二つの新しい関数が追加されました。 random_bytes() と random_int() です。

list() が常に、 ArrayAccess を実装したオブジェクトをアンパックできるように

これまでのバージョンでは、ArrayAccess を実装したオブジェクトに対して list() が正常に機能しないことがありました。 PHP 7 ではこの問題が修正されました。

その他の機能

  • クローンしたクラスのメンバーにアクセスできるようになりました。 (clone $foo)->bar() のようにできるということです。


PHP 7.0.x で推奨されなくなる機能

PHP 4 形式のコンストラクタ

PHP 4 形式のコンストラクタ (クラス名と同じ名前のメソッドを定義するもの) が非推奨となりました。将来的に削除される見込みです。 PHP 7 では、クラス内でこの形式のコンストラクタしか定義されていない場合に E_DEPRECATED が発生します。 __construct() メソッドを実装していれば、この警告は発生しません。

<?php
class foo {
function foo() {
echo 'I am the constructor';
}
}
?>

上の例の出力は以下となります。

Deprecated: Methods with the same name as their class will not be constructors in a future version of PHP; foo has a deprecated constructor in example.php on line 3

非 static メソッドに対する static 呼び出し

static 宣言されていないメソッドに対する static 呼び出しが非推奨となりました。 将来的には削除される見込みです。

<?php
class foo {
function bar() {
echo 'I am not static!';
}
}

foo::bar();
?>

上の例の出力は以下となります。

Deprecated: Non-static method foo::bar() should not be called statically in - on line 8
I am not static!

password_hash() の salt オプション

password_hash() 関数の salt オプションが非推奨となりました。 これは、開発者が自前で (たいていは安全でない) salt を作ってしまうことを避けるためです。 開発者が salt を指定しない場合は、この関数自身が暗号学的にセキュアな salt を生成します。 したがって、もはや自前で salt を作る必要はありません。

capture_session_meta SSL コンテキストオプション

SSL コンテキストオプション capture_session_meta が非推奨となりました。 SSL メタデータは stream_get_meta_data() 関数で利用できるようになります。

LDAP

以下の関数が非推奨になりました。

  • ldap_sort()


変更された関数

PHP コア

  • debug_zval_dump() の出力が、"long" ではなく "int" に、 そして "double" ではなく "float" になりました。
  • dirname() が、オプションの第二パラメータ depth を受け付けるようになりました。これは、 カレントディレクトリから depth 段階さかのぼったディレクトリ名を取得します。
  • getrusage() が Windows 上でも使えるようになりました。
  • mktime() 関数と gmmktime() 関数が、 is_dst パラメータを受け付けなくなりました。
  • preg_replace() 関数が "\e" (PREG_REPLACE_EVAL) をサポートしなくなりました。 かわりに preg_replace_callback() を使いましょう。
  • setlocale() 関数で、category を文字列で渡すことができなくなりました。定数 LC_* を指定する必要があります。
  • exec() 関数、system() 関数および passthru() 関数が、NULL バイト攻撃に対応しました。
  • shmop_open() は int ではなくリソースを返すようになりました。
これを、shmop_size() や
shmop_write()、shmop_read()、
shmop_close()、shmop_delete()
に渡す必要があります。
  • substr() および iconv_substr()は、 文字列の長さが開始位置と等しい場合に空文字列を返すようになりました。
  • パーサーリソースがオブジェクトを参照し、このオブジェクトがそのパーサーリソースを参照する場合、 xml_parser_free() は、パーサーリソースを解放するのに十分ではなくなりました。 この場合、さらに $parser を unset する必要があります。


新しい関数

Closure

  • Closure::call()

CSPRNG

  • random_bytes()
  • random_int()

エラー処理およびログ記録

  • error_clear_last()

Generator

  • Generator::getReturn()

GNU Multiple Precision

  • gmp_random_seed()

数学関数

  • intdiv()

PCRE

  • preg_replace_callback_array()

PHP オプションと情報

  • gc_mem_caches()
  • get_resources()

POSIX

  • posix_setrlimit()

リフレクション

  • ReflectionParameter::getType()
  • ReflectionParameter::hasType()
  • ReflectionFunctionAbstract::getReturnType()
  • ReflectionFunctionAbstract::hasReturnType()

Zip

  • ZipArchive::setCompressionIndex()
  • ZipArchive::setCompressionName()

Zlib 圧縮

  • inflate_add()
  • deflate_add()
  • inflate_init()
  • deflate_init()


新しいクラスおよびインターフェイス

Intl

  • IntlChar

リフレクション

  • ReflectionGenerator
  • ReflectionType

セッション処理

  • SessionUpdateTimestampHandlerInterface

例外の階層

  • Throwable
  • Error
  • TypeError
  • ParseError
  • AssertionError
  • ArithmeticError
  • DivisionByZeroError


新しいグローバル定数

コアで定義済みの定数

  • PHP_INT_MIN

GD

  • IMG_WEBP (PHP 7.0.10 以降)

JSON

  • JSON_ERROR_INVALID_PROPERTY_NAME
  • JSON_ERROR_UTF16

LibXML

  • LIBXML_BIGLINES

PCRE

  • PREG_JIT_STACKLIMIT_ERROR

POSIX

  • POSIX_RLIMIT_AS
  • POSIX_RLIMIT_CORE
  • POSIX_RLIMIT_CPU
  • POSIX_RLIMIT_DATA
  • POSIX_RLIMIT_FSIZE
  • POSIX_RLIMIT_LOCKS
  • POSIX_RLIMIT_MEMLOCK
  • POSIX_RLIMIT_MSGQUEUE
  • POSIX_RLIMIT_NICE
  • POSIX_RLIMIT_NOFILE
  • POSIX_RLIMIT_NPROC
  • POSIX_RLIMIT_RSS
  • POSIX_RLIMIT_RTPRIO
  • POSIX_RLIMIT_RTTIME
  • POSIX_RLIMIT_SIGPENDING
  • POSIX_RLIMIT_STACK
  • POSIX_RLIMIT_INFINITY

Zlib

  • ZLIB_ENCODING_RAW
  • ZLIB_ENCODING_DEFLATE
  • ZLIB_ENCODING_GZIP
  • ZLIB_FILTERED
  • ZLIB_HUFFMAN_ONLY
  • ZLIB_FIXED
  • ZLIB_RLE
  • ZLIB_DEFAULT_STRATEGY
  • ZLIB_BLOCK
  • ZLIB_FINISH
  • ZLIB_FULL_FLUSH
  • ZLIB_NO_FLUSH
  • ZLIB_PARTIAL_FLUSH
  • ZLIB_SYNC_FLUSH


SAPI モジュールの変更

FPM

制限のない listen ポートは、 IPv4 と IPv6 の両方をリスンするようになりました。

PHP 5 では、listen ディレクティブにポート番号だけを指定した場合は、 すべてのインターフェイス上で IPv4 だけをリスンしていました。PHP 7 では、 IPv4 と IPv6 の両方のリクエストを受け付けるようになります。

特定の IP アドレスを指定しているディレクティブには何も影響を及ぼしません。 IP アドレスを指定している場合は、そのアドレスとプロトコルだけを受け付けます。


削除された拡張モジュールおよび SAPI

削除された拡張モジュール

  • ereg
  • mssql
  • mysql
  • sybase_ct

削除された SAPI

  • aolserver
  • apache
  • apache_hooks
  • apache2filter
  • caudium
  • continuity
  • isapi
  • milter
  • nsapi
  • phttpd
  • pi3web
  • roxen
  • thttpd
  • tux
  • webjames


その他の変更

予約語の制約の緩和

クラスやインターフェイスそしてトレイトの内部で、 プロパティや定数そしてメソッドの名前にグローバルな予約語を使えるようになりました。 これで、今後新たなキーワードが導入された場合でも下位互換性を維持しやすくなります。 そして、API の命名の制約も軽減できるでしょう。

これは、流れるようなインターフェイスを用いた内部 DSL を作る際などに便利です。

<?php
// 'new', 'private', 'for' は、これまでなら使うことができませんでした
Project::new('Project Name')->private()->for('purpose here')->with('username here');
?>

唯一の例外は class キーワードで、このキーワードを定数名として使うことはできません。 これを許してしまうと、クラス名の解決に使う構文 (ClassName::class) と衝突してしまうからです。

date.timezone に関する警告の削除

これまでのバージョンでは、INI 項目 date.timezone を設定せずに日付・時刻関連の関数を使おうとすると、警告が発生していました。 PHP 7 では、この警告は発生しなくなりました (date.timezone のデフォルトは、これまでどおり UTC です)。


PHP 5.5.x から PHP 5.6.x への移行

目次

  • 下位互換性のない変更点
  • 新機能
  • PHP 5.6.x で推奨されなくなる機能
  • 変更された関数
  • 新しい関数
  • PHP 5.6.x における OpenSSL 関連の変更
  • その他の拡張モジュールに対する変更
  • 新しいグローバル定数

PHP 5.5.x で改良された点のほどんどは、既存のコードに影響を及ぼしません。ただ、 互換性がない変更 や 考慮すべき 新機能 があります。よって、 実運用環境の PHP をこのバージョンにあげる前に、あらゆるコードをテストすべきです。


下位互換性のない変更点

既存の PHP 5 のコードのほとんどは変更なしで動作するはずですが、 以下の下位互換性のない変更点については注意しましょう。

配列リテラルを用いてクラスのプロパティに配列を設定した場合、配列のキーが上書きされない

以前のバージョンでは、クラスのプロパティとして宣言されている配列で明示的なキーと暗黙のキーが混在している場合に、 明示的に指定したキーと暗黙の数値キーが重複すると、黙って上書きされていました。以下に、例を示します。

<?php
class C {
const ONE = 1;
public $array = [
self::ONE => 'foo',
'bar',
'quux',
];
}

var_dump((new C)->array);
?>

上の例の PHP 5.5 での出力は、このようになります。

array(2) {
  [0]=>
  string(3) "bar"
  [1]=>
  string(4) "quux"
}

上の例の PHP 5.6 での出力は、このようになります。

array(3) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(4) "quux"
}

json_decode() が、より厳格に

json_decode() は、JSON リテラル true、false および null について、すべて小文字のものしか受け付けなくなりました。 これは、JSON の仕様に基づくものです。小文字以外の場合は、json_last_error() にエラーが設定されます。 以前のバージョンの json_decode() は、大文字が混ざっているものでも受け付けていました。

この変更の影響を受けるのは、無効な形式の JSON を json_decode() に渡していた場合だけです。 妥当な形式の JSON は、この変更の影響を受けず、通常通りに処理されます。

ストリームラッパーが、SSL/TLS を使っている場合のピア証明書とホスト名の検証にデフォルトで対応

暗号化されたすべてのクライアントストリームで、ピア検証がデフォルトで有効になりました。 デフォルトでは、OpenSSL のデフォルト CA バンドルを使ってピア証明書を検証します。 たいていの場合は、正しい SSL 証明書を持つサーバーと通信するならこれを変更する必要はありません。 OpenSSL が、よく知られた CA バンドルを使うように設定されているからです。

デフォルトの CA バンドルを上書きすることもできます。 openssl.cafile あるいは openssl.capath を設定すればグローバルに変更でき、コンテキストオプション cafile あるいは capath を使えばリクエスト単位で変更できます。

一般的にはおすすめできませんが、 コンテキストオプション verify_peer を false にしてリクエストでのピア証明書の検証を無効化することもできます。 また同じく、ピア名の検証も、コンテキストオプション verify_peer_name を false にすれば無効化できます。

GMP リソースがオブジェクトに

GMP リソースがオブジェクトになりました。 GMP 拡張モジュールに実装されている API に変更はなく、コードに手を加えなくてもそのまま動作します。 しかし、is_resource() などでリソースかどうかを明示的に調べている場合は注意が必要です。

Mcrypt 関数は、有効なキーと IV を要求する

mcrypt_encrypt()、mcrypt_decrypt()、
mcrypt_cbc()、mcrypt_cfb()、
mcrypt_ecb()、mcrypt_generic() および
mcrypt_ofb() は、無効なサイズのキーや IV を受け付けなくなりました。
IV が必要なブロック暗号化モードで IV が指定されていない場合にも、処理が失敗するようになりました。

cURL でのファイルアップロード

@file 構文によるファイルアップロードを行う際には、CURLOPT_SAFE_UPLOAD を false に設定しなければいけなくなりました。 この機能を使うのではなく、CURLFile を使うべきです。


新機能

定数式

数値や文字列リテラルと定数を、これまでのバージョンでは静的な値が想定されていた場面 (定数やプロパティの宣言、関数のデフォルト引数など) で、スカラー式として扱えるようになりました。

<?php
const ONE = 1;
const TWO = ONE * 2;

class C {
const THREE = TWO + 1;
const ONE_THIRD = ONE / self::THREE;
const SENTENCE = 'THREE の値は '.self::THREE;

public function f($a = ONE + self::THREE) {
return $a;
}
}

echo (new C)->f()."\n";
echo C::SENTENCE;
?>

上の例の出力は以下となります。

4
THREE の値は 3

配列も、 const キーワードで定数として定義できるようになりました。

<?php
const ARR = ['a', 'b'];

echo ARR[0];
?>

上の例の出力は以下となります。

a

... による可変個引数関数

可変個引数の関数 の実装に ... 演算子が使えるようになり、 func_get_args() を使わずに済むようになりました。

<?php
function f($req, $opt = null, ...$params) {
// $params は配列で、残りのすべての引数が含まれます
printf('$req: %d; $opt: %d; パラメータ数: %d'."\n",
$req, $opt, count($params));
}

f(1);
f(1, 2);
f(1, 2, 3);
f(1, 2, 3, 4);
f(1, 2, 3, 4, 5);
?>

上の例の出力は以下となります。

$req: 1; $opt: 0; パラメータ数: 0
$req: 1; $opt: 2; パラメータ数: 0
$req: 1; $opt: 2; パラメータ数: 1
$req: 1; $opt: 2; パラメータ数: 2
$req: 1; $opt: 2; パラメータ数: 3

... による引数のアンパック

配列 や Traversable オブジェクトを引数リストにアンパックするために、 関数の呼び出し時に ... 演算子が使えるようになりました。 これは、Ruby などの他の言語では splat 演算子と呼ばれることもあります。

<?php
function add($a, $b, $c) {
return $a + $b + $c;
}

$operators = [2, 3];
echo add(1, ...$operators);
?>

上の例の出力は以下となります。

6

累乗演算子 **

右から評価する ** 演算子が追加されました。 これは累乗をサポートするものです。さらに、短縮代入演算子 **= も追加されました。

<?php
printf("2 ** 3 == %d\n", 2 ** 3);
printf("2 ** 3 ** 2 == %d\n", 2 ** 3 ** 2);

$a = 2;
$a **= 3;
printf("a == %d\n", $a);
?>

上の例の出力は以下となります。

2 ** 3 ==      8
2 ** 3 ** 2 == 512
a ==           8

use function および use const

The use 演算子を拡張し、クラスだけではなく関数や定数もインポートできるようになりました。 それぞれ、言語構造 use function および use const を用います。

<?php
namespace Name\Space {
const FOO = 42;
function f() { echo __FUNCTION__."\n"; }
}

namespace {
use const Name\Space\FOO;
use function Name\Space\f;

echo FOO."\n";
f();
}
?>

上の例の出力は以下となります。

42
Name\Space\f

phpdbg

PHP は、今や SAPI モジュールとして実装された phpdbg という対話型デバッガーを含みます。 詳細な情報は » phpdbg のドキュメント を参照ください。

デフォルトの文字エンコーディング

エンコーディングに依存する関数 htmlentities() や html_entity_decode() そして htmlspecialchars() におけるデフォルトの文字セットとして、 default_charset を利用するようになりました。 iconv (非推奨) や mbstring でのエンコードが設定されている場合は、 default_charset よりもそちらのほうが優先されます。

この設定のデフォルト値は UTF-8 です。

php://input が再利用可能に

php://input が再オープンできるようになり、必要に応じて何度でも読めるようになりました。 その結果として、POST されたデータを読むときに必要となるメモリの量が大幅に削減されました。

巨大なファイルのアップロード

2 ギガバイトより大きいサイズのファイルもアップロードできるようになりました。

GMP での演算子オーバーロードのサポート

GMP オブジェクトが、 演算子のオーバーロードやスカラー型へのキャストに対応するようになりました。 GMP を使って、よりわかりやすいコードが書けるようになります。

<?php
$a = gmp_init(42);
$b = gmp_init(17);

if (version_compare(PHP_VERSION, '5.6', '<')) {
echo gmp_intval(gmp_add($a, $b)), PHP_EOL;
echo gmp_intval(gmp_add($a, 17)), PHP_EOL;
echo gmp_intval(gmp_add(42, $b)), PHP_EOL;
} else {
echo $a + $b, PHP_EOL;
echo $a + 17, PHP_EOL;
echo 42 + $b, PHP_EOL;
}
?>

上の例の出力は以下となります。

59
59
59

hash_equals() による、タイミング攻撃に対応した文字列比較

hash_equals() 関数が追加されました。 この関数は、二つの文字列の比較を一定の時間で行います。 タイミング攻撃を防ぐために、文字列の比較にはこの関数を使うべきです。 たとえば crypt() のパスワードハッシュをチェックしたりするときに使えます (password_hash() や password_verify() が使えない場合を想定。 これらの関数は、タイミング攻撃の影響を受けません)。

<?php
$expected = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$correct = crypt('12345', '$2a$07$usesomesillystringforsalt$');
$incorrect = crypt('1234', '$2a$07$usesomesillystringforsalt$');

var_dump(hash_equals($expected, $correct));
var_dump(hash_equals($expected, $incorrect));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

__debugInfo()

マジックメソッド __debugInfo() が追加されました。 var_dump() でオブジェクトの情報を出力する際の、 プロパティやその値の表示方法を変更できます。

<?php
class C {
private $prop;

public function __construct($val) {
$this->prop = $val;
}

public function __debugInfo() {
return [
'propSquared' => $this->prop ** 2,
];
}
}

var_dump(new C(42));
?>

上の例の出力は以下となります。

object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}

gost-crypto ハッシュアルゴリズム

ハッシュアルゴリズム gost-crypto が追加されました。 これは GOST ハッシュ関数を実装したもので、 » RFC 4357, section 11.2 に記載されている CryptoPro S-box テーブルを使っています。

SSL/TLS の改良

PHP 5.6 では、SSL/TLS のサポートに幅広い改良が加わりました。 ピア検証にデフォルトで対応したり、 証明書のフィンガープリントのマッチングに対応したり、 TLS 再ネゴシエーションアタックの対策をしたり、多数の SSL コンテキストオプションを新たに導入したりしました。 これらによって、暗号化されたストリームに関するよりきめ細やかな制御ができるようになりました。

変更内容の詳細を、 PHP 5.6.x における OpenSSL 関連の変更 にまとめました。

pgsql の非同期サポート

pgsql 拡張モジュールが、 非同期の接続や問い合わせに対応しました。 PostgreSQL データベースとのやりとりで、ノンブロッキング処理ができるようになります。 非同期接続を確立するには、定数 PGSQL_CONNECT_ASYNC を利用します。そして、新しい関数 pg_connect_poll()、pg_socket()、 pg_consume_input()、pg_flush() を使って、非同期接続や問い合わせを処理します。


PHP 5.6.x で推奨されなくなる機能

非互換のコンテキストからの呼び出し

非互換のコンテキストからのメソッド呼び出しが非推奨となり、 E_STRICT ではなく E_DEPRECATED が発生するようになりました。 この機能は、将来のバージョンの PHP で削除される予定です。

具体例を示します。

<?php
class A {
function f() { echo get_class($this); }
}

class B {
function f() { A::f(); }
}

(new B)->f();
?>

上の例の出力は以下となります。

Deprecated: Non-static method A::f() should not be called statically, assuming $this from incompatible context in - on line 7
B

$HTTP_RAW_POST_DATA および always_populate_raw_post_data

always_populate_raw_post_data を使うと、$HTTP_RAW_POST_DATA に値が入っている場合に E_DEPRECATED が発生するようになりました。 新しいコードでは、$HTTP_RAW_POST_DATA ではなく php://input を使うようにしましょう。$HTTP_RAW_POST_DATA は、将来のバージョンで削除される予定です。 この新しい振る舞い ($HTTP_RAW_POST_DATA が定義されておらず、E_DEPRECATED が発生しない状態) を試すには、 always_populate_raw_post_data に -1 を設定します。

iconv および mbstring のエンコーディング設定

iconv および mbstring の、エンコーディングに関するオプションが非推奨となりました。 代わりに default_charset を使いましょう。 非推奨になったオプションは、以下のとおりです。

  • iconv.input_encoding
  • iconv.output_encoding
  • iconv.internal_encoding
  • mbstring.http_input
  • mbstring.http_output
  • mbstring.internal_encoding


変更された関数

PHP コア

  • crypt() で、salt パラメータを省略したときに E_NOTICE が発生するようになりました。
  • substr_compare() が、 length パラメータに 0 を受け付けるようになりました。
  • unserialize() に渡したシリアライズ済みデータが、 自身のコンストラクタを呼ばないようなオブジェクトに改変されている場合に、 処理が失敗するようになりました。

cURL

  • @file 構文を使ったアップロードは、 CURLOPT_SAFE_UPLOAD オプションを false にしたときだけサポートするようになりました。 かわりに CURLFile を使うようにしましょう。

Mcrypt

  • mcrypt_create_iv() の source パラメータのデフォルトが、 MCRYPT_DEV_RANDOM から MCRYPT_DEV_URANDOM に変わりました。

OpenSSL

  • stream_socket_enable_crypto() で、 crypto_type パラメータをオプションにすることができるようになりました。 ストリームの SSL コンテキストに、新しいオプション crypto_type を指定します。

PostgreSQL

  • pg_insert()、pg_select()、 pg_update()、pg_delete() が、実験的な関数ではなくなりました。
  • pg_send_execute()、
pg_send_prepare()、pg_send_query()、
pg_send_query_params() が、
データベース接続に使っているソケットストリームがノンブロッキングモードの場合は、
クエリの書き込み完了まで待つようなブロックをしなくなりました。

Reflection

  • ReflectionClass::newInstanceWithoutConstructor() で、final ではない内部関数をインスタンス化できるようになりました。

XMLReader

  • XMLReader::getAttributeNs() と XMLReader::getAttributeNo() が、 属性が見つからない場合に null を返すようになりました。これは XMLReader::getAttribute() と同じ挙動です。


新しい関数

日付・時刻

  • DateTimeImmutable::createFromMutable()

GMP

  • gmp_root()
  • gmp_rootrem()

Hash

  • hash_equals()

LDAP

  • ldap_escape()
  • ldap_modify_batch()

MySQLi

  • mysqli_get_links_stats()

OCI8

  • oci_get_implicit_resultset()

OpenSSL

  • openssl_get_cert_locations()
  • openssl_x509_fingerprint()
  • openssl_spki_new()
  • openssl_spki_verify()
  • openssl_spki_export_challenge()
  • openssl_spki_export()

PostgreSQL

  • pg_connect_poll()
  • pg_consume_input()
  • pg_flush()
  • pg_socket()

PDO_PGSQL

  • PDO::pgsqlGetNotify()
  • PDO::pgsqlGetPid()

Session

  • session_abort()
  • session_reset()

Zip

  • ZipArchive::setPassword()


PHP 5.6.x における OpenSSL 関連の変更

ストリームラッパーが、SSL/TLS を使っている場合のピア証明書とホスト名の検証にデフォルトで対応

暗号化されたすべてのクライアントストリームで、ピア検証がデフォルトで有効になりました。 デフォルトでは、OpenSSL のデフォルト CA バンドルを使ってピア証明書を検証します。 たいていの場合は、正しい SSL 証明書を持つサーバーと通信するならこれを変更する必要はありません。 OpenSSL が、よく知られた CA バンドルを使うように設定されているからです。

デフォルトの CA バンドルを上書きすることもできます。 openssl.cafile あるいは openssl.capath を設定すればグローバルに変更でき、コンテキストオプション cafile あるいは capath を使えばリクエスト単位で変更できます。

一般的にはおすすめできませんが、 コンテキストオプション verify_peer を false にしてリクエストでのピア証明書の検証を無効化することもできます。 また同じく、ピア名の検証も、コンテキストオプション verify_peer_name を false にすれば無効化できます。

証明書のフィンガープリント

証明書のフィンガープリントの抽出と、その検証に対応しました。 新たに追加された openssl_x509_fingerprint() 関数が、 X.509 証明書からフィンガープリントを抽出します。また、 SSL ストリームコンテキスト に二つのオプションが追加されました。 capture_peer_cert はピアの X.509 証明書を取り込み、 peer_fingerprint はピアの証明書が指定したフィンガープリントにマッチすることを確かめます。

デフォルトの暗号の更新

PHP がデフォルトで使う暗号が更新され、 » Mozilla cipher recommendations に基づいた、よりセキュアなリストになりました。 リストにない例外は、anonymous Diffie-Hellman ciphers と RC4 です。

新しい定数 OPENSSL_DEFAULT_STREAM_CIPHERS で、この一覧にアクセスできます。 また、(過去のバージョンの PHP のように) 上書きもできます。上書きをするには、コンテキストオプション ciphers を設定します。

デフォルトでの圧縮の無効化

SSL/TLS の圧縮が、デフォルトで無効になりました。これは、CRIME 攻撃への対応です。 PHP 5.4.13 で新たにコンテキストオプション disable_compression が加わり、圧縮を無効にできるようになりました。そのデフォルト値が true （つまり圧縮が無効になっている) に変わったのです。

サーバーの暗号の優先が可能に

SSL コンテキストオプション honor_cipher_order が追加されました。これによって、暗号化されたストリームサーバーでの BEAST 脆弱性を除去するために、サーバーの暗号をクライアントよりも優先させられるようになります。

ネゴシエート済みのプロトコルと暗号へのアクセス

暗号化ストリームでネゴシエート済みのプロトコルと暗号へのアクセスが、 stream_get_meta_data() あるいは stream_context_get_options() でできるようになりました。 これは、SSL コンテキストオプション capture_session_meta が true になっている場合に有効です。

<?php
$ctx = stream_context_create(['ssl' => [
'capture_session_meta' => TRUE
]]);

$html = file_get_contents('https://google.com/', FALSE, $ctx);
$meta = stream_context_get_options($ctx)['ssl']['session_meta'];
var_dump($meta);
?>

上の例の出力は以下となります。

array(4) {
  ["protocol"]=>
  string(5) "TLSv1"
  ["cipher_name"]=>
  string(20) "ECDHE-RSA-AES128-SHA"
  ["cipher_bits"]=>
  int(128)
  ["cipher_version"]=>
  string(11) "TLSv1/SSLv3"
}

暗号化ストリームサーバーでの前方秘匿性に関する新たなオプション

暗号化クライアントストリームはすでに前方秘匿性に対応しています。 というのも、一般に前方秘匿性は、サーバーが制御するものだからです。 PHP の暗号化サーバーストリームが使っている証明書は前方秘匿性に対応しており、 何もしなくても有効になっています。 しかし、前方秘匿性に関してより決め細やかな制御をしたり、 互換性に関する問題に対応したりするために、 新たな SSL コンテキストオプションがいくつか追加されました。

ecdh_curve

このオプションで、ECDH 暗号で使う曲線を選択できるようになります。 省略した場合は prime256v1 を使います。

dh_param

Diffie-Hellman 鍵交換用のパラメータを含むファイルへのパス。 このファイルは、たとえば以下のようなコマンドで生成したものです。

openssl dhparam -out /path/to/my/certs/dh-2048.pem 2048
single_dh_use

true にすると、Diffie-Hellman パラメータを使うときに、 新たな鍵ペアを作成します。これにより、前方秘匿性が向上します。

single_ecdh_use

true にすると、ECDH 暗号スイートでのネゴシエート時に 新たな鍵ペアを作成します。これにより、前方秘匿性が向上します。

SSL/TLS のバージョンの選択

SSL や TLS の、特定のバージョンを指定できるようになりました。SSL コンテキストオプション crypto_method を利用するか、 あるいはストリームラッパーの作成時に (stream_socket_client() あるいは stream_socket_server() を呼んで) トランスポートを指定します。

SSL コンテキストオプション crypto_method には、 stream_socket_enable_crypto() 関数の crypto_type と同様に、 許可するプロトコルをビットマスクで指定します。

プロトコルのバージョンと、対応するオプション
プロトコル | クライアントのフラグ | サーバーのフラグ | トランスポート
任意のバージョンの TLS あるいは SSL | STREAM_CRYPTO_METHOD_ANY_CLIENT | STREAM_CRYPTO_METHOD_ANY_SERVER | ssl://
任意のバージョンの TLS | STREAM_CRYPTO_METHOD_TLS_CLIENT | STREAM_CRYPTO_METHOD_TLS_SERVER | tls://
TLS 1.0 | STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT | STREAM_CRYPTO_METHOD_TLSv1_0_SERVER | tlsv1.0://
TLS 1.1 | STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT | STREAM_CRYPTO_METHOD_TLSv1_1_SERVER | tlsv1.1://
TLS 1.2 | STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT | STREAM_CRYPTO_METHOD_TLSv1_2_SERVER | tlsv1.2://
SSL 3 | STREAM_CRYPTO_METHOD_SSLv3_CLIENT | STREAM_CRYPTO_METHOD_SSLv3_SERVER | sslv3://
<?php

// file_get_contents() を使うには TLS 1.0 以降が必要です
$ctx = stream_context_create([
'ssl' => [
'crypto_method' => STREAM_CRYPTO_METHOD_TLS_CLIENT,
],
]);
$html = file_get_contents('https://google.com/', false, $ctx);

// TLS 1.1 あるいは 1.2 が必要です
$ctx = stream_context_create([
'ssl' => [
'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT |
STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT,
],
]);
$html = file_get_contents('https://google.com/', false, $ctx);

// 接続時に tlsv1.2:// ストリームソケットトランスポートを利用します
$sock = stream_socket_client('tlsv1.2://google.com:443/');

?>

openssl_get_cert_locations() の追加

openssl_get_cert_locations() 関数が追加されました。 この関数は、PHP が CA バンドルを探す際のデフォルトの場所を返します。

<?php
var_dump(openssl_get_cert_locations());
?>

上の例の出力は以下となります。

array(8) {
  ["default_cert_file"]=>
  string(21) "/etc/pki/tls/cert.pem"
  ["default_cert_file_env"]=>
  string(13) "SSL_CERT_FILE"
  ["default_cert_dir"]=>
  string(18) "/etc/pki/tls/certs"
  ["default_cert_dir_env"]=>
  string(12) "SSL_CERT_DIR"
  ["default_private_dir"]=>
  string(20) "/etc/pki/tls/private"
  ["default_default_cert_area"]=>
  string(12) "/etc/pki/tls"
  ["ini_cafile"]=>
  string(0) ""
  ["ini_capath"]=>
  string(0) ""
}

SPKI のサポート

署名された公開鍵およびチャレンジ (SPKAC) の生成や抽出、そして検証のサポートが追加されました。 新たに追加された関数 openssl_spki_new()、 openssl_spki_verify()、 openssl_spki_export_challenge() そして openssl_spki_export() で、 SPKAC が HTML5 の KeyGen 要素から生成した PEM 公開鍵とチャレンジの作成、検証、エクスポートを行います。

openssl_spki_new

秘密鍵とチャレンジ文字列、そしてハッシュアルゴリズムを指定して、 新しい SPKAC を生成します。

<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
?>

上の例の出力は以下となります。

SPKAC=MIIBXjCByDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA3L0IfUijj7+A8CPC8EmhcdNoe5fUAog7OrBdhn7EkxFButUp40P7+LiYiygYG1TmoI/a5EgsLU3s9twEz3hmgY9mYIqb/rb+SF8qlD/K6KVyUORC7Wlz1Df4L8O3DuRGzx6/+3jIW6cPBpfgH1sVuYS1vDBsP/gMMIxwTsKJ4P0CAwEAARYkYjViMzYxMTktNjY5YS00ZDljLWEyYzctMGZjNGFhMjVlMmE2MA0GCSqGSIb3DQEBAwUAA4GBAF7hu0ifzmjonhAak2FhhBRsKFDzXdKIkrWxVNe8e0bZzMrWOxFM/rqBgeH3/gtOUDRS5Fnzyq425UsTYbjfiKzxGeCYCQJb1KJ2V5Ij/mIJHZr53WYEXHQTNMGR8RPm7IxwVXVSHIgAfXsXZ9IXNbFbcaLRiSTr9/N4U+MXUWL7
openssl_spki_verify

指定した SPKAC を検証します。

<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
var_dump(openssl_spki_verify($spkac));
?>
openssl_spki_export_challenge

指定した SPKAC から、関連付けられたチャレンジをエクスポートします。

<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
$challenge = openssl_spki_export_challenge($spkac);
echo $challenge;
?>

上の例の出力は以下となります。

challenge string
openssl_spki_export

PEM フォーマットされた RSA 公開鍵を、SPKAC からエクスポートします。

<?php
$pkey = openssl_pkey_new();
openssl_pkey_export($pkey, 'secret passphrase');

$spkac = openssl_spki_new($pkey, 'challenge string');
echo openssl_spki_export($spkac);
?>

上の例の出力は以下となります。

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDcvQh9SKOPv4DwI8LwSaFx02h7
l9QCiDs6sF2GfsSTEUG61SnjQ/v4uJiLKBgbVOagj9rkSCwtTez23ATPeGaBj2Zg
ipv+tv5IXyqUP8ropXJQ5ELtbXPUN/gvw7cO5EbPHr/7eMhbpw8Gl+AfWxW5hLW8
MGw/+AwwjHBOwong/QIDAQAB
-----END PUBLIC KEY-----


その他の拡張モジュールに対する変更

cURL

cURL ライブラリで非推奨とされてきた以下の定数が、削除されました。

  • CURLOPT_CLOSEPOLICY
  • CURLCLOSEPOLICY_CALLBACK
  • CURLCLOSEPOLICY_LEAST_RECENTLY_USED
  • CURLCLOSEPOLICY_LEAST_TRAFFIC
  • CURLCLOSEPOLICY_OLDEST
  • CURLCLOSEPOLICY_SLOWEST

OCI8

  • Oracle Database 12c の暗黙の結果セットをサポートするようになりました。 新しい関数 oci_get_implicit_resultset() を利用します。
  • SELECT に対して oci_execute($s, OCI_NO_AUTO_COMMIT) を使った場合に、接続を閉じるときに、不要な内部 ROLLBACK を起動することがなくなりました。
  • DTrace プローブが追加されました。 --enable-dtrace オプションで制御します。
  • oci_internal_debug() は、何もしない関数になりました。
  • phpinfo() における OCI8 の出力フォーマットが変わりました。

Zip

設定オプション --with-libzip が追加されました。 これを指定すると、システムにインストールされている libzip を利用します。 libzip バージョン 0.11 が必須です。0.11.2 以降を推奨します。

MySQLi

新しいオプション mysqli.rollback_on_cached_plink が追加されました。持続的接続のロールバック動作を制御します。


新しいグローバル定数

GD

  • IMG_WEBP (PHP 5.6.25 以降)

LDAP

  • LDAP_ESCAPE_DN
  • LDAP_ESCAPE_FILTER

OpenSSL

  • OPENSSL_DEFAULT_STREAM_CIPHERS
  • STREAM_CRYPTO_METHOD_ANY_CLIENT
  • STREAM_CRYPTO_METHOD_ANY_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_0_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_1_SERVER
  • STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT
  • STREAM_CRYPTO_METHOD_TLSv1_2_SERVER

PostgreSQL

  • PGSQL_CONNECT_ASYNC
  • PGSQL_CONNECTION_AUTH_OK
  • PGSQL_CONNECTION_AWAITING_RESPONSE
  • PGSQL_CONNECTION_MADE
  • PGSQL_CONNECTION_SETENV
  • PGSQL_CONNECTION_SSL_STARTUP
  • PGSQL_CONNECTION_STARTED
  • PGSQL_DML_ESCAPE
  • PGSQL_POLLING_ACTIVE
  • PGSQL_POLLING_FAILED
  • PGSQL_POLLING_OK
  • PGSQL_POLLING_READING
  • PGSQL_POLLING_WRITING


  • ≪ 新しいグローバル定数
  • PHP のデバッグについて ≫
  • PHP Manual
  • 付録
  • PHP のデバッグ

PHP のデバッグ

目次

  • PHP のデバッグについて


PHP のデバッグについて

PHP には、コマンドラインの対話型デバッガ phpdbg が同梱されています。

ほとんどのIDE は » Xdebug をサポートしています。 これはフリーのデバッグツールで、PHP アプリケーションをステップ実行することでデバッグできます。


  • ≪ PHP のデバッグについて
  • 中心となる configure オプションのリスト ≫
  • PHP Manual
  • 付録
  • Configure オプション

Configure オプション

目次

  • 中心となる configure オプションのリスト


中心となる configure オプションのリスト

以下のリストは、Unix 系の環境で PHP をコンパイルする際に用いられる configure スクリプトのオプションの一部です。 ほとんどのオプションはそれぞれの拡張モジュールのリファレンスページで 説明されており、ここにはありません。最新の configure オプションの 完全なリストを得るには、PHP のソースディレクトリで autoconf を実行した後、./configure --help を実行してください（インストールと設定 も参照ください）。--prefix=PREFIX のような追加の configure オプションについて興味がある方は、 » GNU configure のドキュメントが 参考になるでしょう。

注意:

これらの設定はコンパイル時にのみ使用可能です。PHP の動作を 実行時に設定したい場合は、実行時設定 の章を参照ください。

  • 一般
  • PHP の動作
  • サーバー

PHP の Configure オプション

一般的なオプション

--enable-debug

デバッグシンボルつきでコンパイルします。

--with-layout=TYPE

インストールされるファイルのレイアウトを設定します。Type には PHP（デフォルト）または GNU のどちらかが指定できます。 manページを PREFIX 直下にインストールした場合(デフォルト)、 manpath ユーティリティの検索パスで見つかった順に、 GNU スタイルのレイアウトが選択されるので注意しましょう。

--with-pear=DIR

PEAR を DIR（デフォルトは PREFIX/lib/php）にインストールします。

--without-pear

PEAR をインストールしません。

--enable-sigchild

PHP 独自の SIGCHLD ハンドラを有効にします。

--disable-rpath

実行時にライブラリの検索パスを追加できないようにします。

--enable-libgcc

明示的に libgcc とリンクします。

--enable-php-streams

実験的な PHP ストリーム機能を組み込みます。PHP そのものをテストする 目的以外では使用しないでください。

--with-zlib-dir[=DIR]

zlib のインストールディレクトリを指定します。

--with-tsrm-pthreads

POSIX スレッドを使用します（デフォルト）。

--enable-shared[=PKGS]

共有ライブラリをビルドします [default=yes]。

--enable-static[=PKGS]

静的ライブラリをビルドします [default=yes]。

--enable-fast-install[=PKGS]

インストール速度を上げるように最適化します [default=yes]。

--with-gnu-ld

C コンパイラが GNU ld を使用するとみなします [default=no]。

--disable-libtool-lock

ロックを回避します（並列ビルドに失敗する可能性があります）。

--with-pic

PIC/non-PIC オブジェクトのどちらか一方のみを使用するようにします [default=use both]。

--enable-versioning

要求されるシンボルのみをエクスポートします。 詳細な情報は INSTALL を参照ください。

PHP オプション

--enable-maintainer-mode

一般の利用者にとってあまり便利でない（そして時に混乱のもととなる） make ルールや依存性を有効にします。

--with-config-file-path=PATH

php.ini を探すパスを設定します。デフォルト値は PREFIX/lib です。

--disable-short-tags

開始タグの短縮形 <? をデフォルトで無効にします。

--with-libdir

Unix システムにおいて、PHP をビルドするためのライブラリがあるディレクトリを指定します。 64 ビットシステムでは、この引数を --with-libdir=lib64 のようにして lib64 ディレクトリを指定しなければなりません。

--enable-zts

Zend Thread Safety を有効にします。 PHP 8.0.0 より前のバージョン、かつ Windows 以外のシステムでは、 このオプションは --enable-maintainer-zts と呼ばれていました。

SAPI オプション

以下のリストには、PHP で有効な SAPI（Server Application Programming Interface）が含まれています。

--with-apxs[=FILE]

Apache 共有モジュールをビルドします。FILE は Apache apxs ツールへの パスで、デフォルトは apxs です。Apache のソース Tarball に含まれる apxs を指定するのではなく、そのシステムに実際にインストールされている バージョンの apxs を指定するようにしましょう。

--with-apache[=DIR]

静的 Apache モジュールをビルドします。DIR は Apache のビルドディレクトリで、 デフォルトは /usr/local/apache です。

--with-mod_charset

（ロシアの Apache 用の）mod_charset のための変換テーブルを 有効にします。

--with-apxs2[=FILE]

Apache 2.0 共有モジュールをビルドします。FILE は、オプションで指定する Apache apxs ツールへのパスです。デフォルトは apxs です。

--disable-cli

PHP の CLI バージョンのビルドを 無効にします（自動的に --without-pear も指定されます）。詳細な情報は PHP をコマンドラインから使用する を参照ください。

--enable-phpdbg

phpdbg インタラクティブデバッガ SAPI モジュールのサポートを有効にします。

--enable-embed[=TYPE]

組み込み SAPI ライブラリのビルドを有効にします。TYPE は shared あるいは static のいずれかで、デフォルトは shared です。

--with-servlet[=DIR]

サーブレットのサポートを含めます。DIR は JSDK のインストールディレクトリです。 java 拡張モジュールが共有ライブラリとしてビルドされていることが 前提条件です。

--disable-cgi

PHP の CGI バージョンをビルドしないようにします。

この引数は FastCGI も有効にします。


  • ≪ 中心となる configure オプションのリスト
  • php.ini ディレクティブのリスト ≫
  • PHP Manual
  • 付録
  • php.ini ディレクティブ

php.ini ディレクティブ

目次

  • php.ini ディレクティブのリスト
  • php.ini のセクション一覧
  • コア php.ini ディレクティブに関する説明


php.ini ディレクティブのリスト

以下のリストには、PHP の設定を行うための php.ini ディレクティブが 含まれます。

"変更可能" カラムは、そのディレクティブをいつどこで定義できるかを表すモードです。その意味については どこで設定を行うのか を参照ください。

設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
allow_url_fopen | "1" | INI_SYSTEM |
allow_url_include | "0" | INI_SYSTEM | PHP 7.4.0 以降は非推奨
arg_separator.input | "&" | INI_PERDIR |
arg_separator.output | "&" | INI_ALL |
assert.active | "1" | INI_ALL |
assert.bail | "0" | INI_ALL |
assert.callback | null | INI_ALL |
assert.exception | "0" | INI_ALL |
assert.quiet_eval | "0" | INI_ALL | PHP 8.0.0 以降では削除されました
assert.warning | "1" | INI_ALL |
auto_append_file | null | INI_PERDIR |
auto_detect_line_endings | "0" | INI_ALL |
auto_globals_jit | "1" | INI_PERDIR |
auto_prepend_file | null | INI_PERDIR |
bcmath.scale | "0" | INI_ALL |
browscap | null | INI_SYSTEM |
cgi.check_shebang_line | "1" | INI_SYSTEM |
cgi.discard_path | "0" | INI_SYSTEM |
cgi.fix_pathinfo | "1" | INI_SYSTEM |
cgi.force_redirect | "1" | INI_SYSTEM |
cgi.nph | "0" | INI_ALL |
cgi.redirect_status_env | null | INI_SYSTEM |
cgi.rfc2616_headers | "0" | INI_ALL |
child_terminate | "0" | INI_ALL |
cli.pager | "" | INI_ALL |
cli.prompt | "\\b \\> " | INI_ALL |
cli_server.color | "0" | INI_ALL |
com.allow_dcom | "0" | INI_SYSTEM |
com.autoregister_typelib | "0" | INI_ALL |
com.autoregister_verbose | "0" | INI_ALL |
com.autoregister_casesensitive | "1" | INI_ALL |
com.code_page | "" | INI_ALL |
com.dotnet_version | "" | INI_SYSTEM | PHP 8.0.0 以降で利用可能
com.typelib_file | "" | INI_SYSTEM |
curl.cainfo | NULL | INI_SYSTEM |
date.default_latitude | "31.7667" | INI_ALL |
date.default_longitude | "35.2333" | INI_ALL |
date.sunrise_zenith | "90.833333" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "90.583333" でした。
date.sunset_zenith | "90.833333" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "90.583333" でした。
date.timezone | "UTC" | INI_ALL | PHP 8.2 以降では、この値に無効な値や空文字列を設定すると、警告が発生します。
dba.default_handler | DBA_DEFAULT | INI_ALL |
default_charset | "UTF-8" | INI_ALL
input_encoding | "" | INI_ALL |
output_encoding | "" | INI_ALL |
internal_encoding | "" | INI_ALL |
default_mimetype | "text/html" | INI_ALL |
default_socket_timeout | "60" | INI_ALL |
disable_classes | "" | php.ini のみ |
disable_functions | "" | php.ini のみ |
display_errors | "1" | INI_ALL |
display_startup_errors | "1" | INI_ALL | PHP 8.0.0 より前のバージョンでは、デフォルト値は "0" でした。
docref_ext | "" | INI_ALL |
docref_root | "" | INI_ALL |
doc_root | null | INI_SYSTEM |
enable_dl | "1" | INI_SYSTEM | この非推奨の機能は、きっと 将来 削除 されるでしょう。
enable_post_data_reading | "On" | INI_PERDIR |
engine | "1" | INI_ALL |
error_append_string | null | INI_ALL |
error_log | null | INI_ALL |
error_log_mode | 0o644 | INI_ALL | PHP 8.2.0 以降で利用可能
error_prepend_string | null | INI_ALL |
error_reporting | null | INI_ALL |
exif.encode_unicode | "ISO-8859-15" | INI_ALL |
exif.decode_unicode_motorola | "UCS-2BE" | INI_ALL |
exif.decode_unicode_intel | "UCS-2LE" | INI_ALL |
exif.encode_jis | "" | INI_ALL |
exif.decode_jis_motorola | "JIS" | INI_ALL |
exif.decode_jis_intel | "JIS" | INI_ALL |
exit_on_timeout | "" | INI_ALL |
expect.timeout | "10" | INI_ALL |
expect.loguser | "1" | INI_ALL |
expect.logfile | "" | INI_ALL |
expect.match_max | "" | INI_ALL |
expose_php | "1" | php.ini のみ |
extension | null | php.ini のみ |
extension_dir | "/path/to/php" | INI_SYSTEM |
fastcgi.impersonate | "0" | INI_SYSTEM |
fastcgi.logging | "1" | INI_SYSTEM |
file_uploads | "1" | INI_SYSTEM |
filter.default | "unsafe_raw" | INI_PERDIR | PHP 8.1.0 以降は非推奨
filter.default_flags | NULL | INI_PERDIR |
from | "" | INI_ALL |
gd.jpeg_ignore_warning | "1" | INI_ALL |
geoip.custom_directory | "" | INI_ALL |
hard_timeout | "2" | INI_SYSTEM | PHP 7.1.0 以降で利用可能。
highlight.comment | "#FF8000" | INI_ALL |
highlight.default | "#0000BB" | INI_ALL |
highlight.html | "#000000" | INI_ALL |
highlight.keyword | "#007700" | INI_ALL |
highlight.string | "#DD0000" | INI_ALL |
html_errors | "1" | INI_ALL |
ibase.allow_persistent | "1" | INI_SYSTEM |
ibase.max_persistent | "-1" | INI_SYSTEM |
ibase.max_links | "-1" | INI_SYSTEM |
ibase.default_db | NULL | INI_SYSTEM |
ibase.default_user | NULL | INI_ALL |
ibase.default_password | NULL | INI_ALL |
ibase.default_charset | NULL | INI_ALL |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | INI_ALL |
ibase.dateformat | "%Y-%m-%d" | INI_ALL |
ibase.timeformat | "%H:%M:%S" | INI_ALL |
ibm_db2.binmode | "1" | INI_ALL |
ibm_db2.i5_all_pconnect | "0" | INI_SYSTEM | ibm_db2 1.6.5 以降で利用可能
ibm_db2.i5_allow_commit | "0" | INI_SYSTEM | ibm_db2 1.4.9 以降で利用可能
ibm_db2.i5_blank_userid | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_char_trim | "0" | INI_SYSTEM | ibm_db2 2.1.0 以降で利用可能
ibm_db2.i5_dbcs_alloc | "0" | INI_SYSTEM | ibm_db2 1.5.0 以降で利用可能
ibm_db2.i5_guard_profile | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_ignore_userid | "0" | INI_SYSTEM | ibm_db2 1.8.0 以降で利用可能
ibm_db2.i5_job_sort | "0" | INI_SYSTEM | ibm_db2 1.8.4 以降で利用可能
ibm_db2.i5_log_verbose | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_max_pconnect | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_override_ccsid | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_servermode_subsystem | NULL | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.i5_sys_naming | "0" | INI_SYSTEM | ibm_db2 1.9.7 以降で利用可能
ibm_db2.instance_name | NULL | INI_SYSTEM | ibm_db2 1.0.2 以降で利用可能
iconv.input_encoding | "" | INI_ALL | PHP 5.6.0 で非推奨となりました。
iconv.output_encoding | "" | INI_ALL | PHP 5.6.0 で非推奨となりました。
iconv.internal_encoding | "" | INI_ALL | PHP 5.6.0 で非推奨となりました。
ignore_repeated_errors | "0" | INI_ALL |
ignore_repeated_source | "0" | INI_ALL |
ignore_user_abort | "0" | INI_ALL |
implicit_flush | "0" | INI_ALL |
include_path | ".:/path/to/php/pear" | INI_ALL |
intl.default_locale |  | INI_ALL |
intl.error_level | 0 | INI_ALL |
intl.use_exceptions | 0 | INI_ALL | PECL 3.0.0a1 以降で使用可能。
last_modified | "0" | INI_ALL |
ldap.max_links | "-1" | INI_SYSTEM |
log_errors | "0" | INI_ALL |
log_errors_max_len | "1024" | INI_ALL |
mail.add_x_header | "0" | INI_PERDIR |
mail.force_extra_parameters | null | php.ini のみ |
mail.log | "" | INI_PERDIR |
max_execution_time | "30" | INI_ALL |
max_input_nesting_level | "64" | INI_PERDIR |
max_input_vars | 1000 | INI_PERDIR |
max_input_time | "-1" | INI_PERDIR |
mbstring.language | "neutral" | INI_ALL |
mbstring.detect_order | NULL | INI_ALL |
mbstring.http_input | "pass" | INI_ALL | 非推奨になりました。
mbstring.http_output | "pass" | INI_ALL | 非推奨になりました。
mbstring.internal_encoding | NULL | INI_ALL | 非推奨になりました。
mbstring.substitute_character | NULL | INI_ALL |
mbstring.func_overload | "0" | INI_SYSTEM | PHP 7.2.0 で非推奨になり、PHP 8.0.0 で削除されました。
mbstring.encoding_translation | "0" | INI_PERDIR |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | INI_ALL |
mbstring.strict_detection | "0" | INI_ALL |
mbstring.regex_retry_limit | "1000000" | INI_ALL | PHP 7.4.0 以降で利用可能です。
mbstring.regex_stack_limit | "100000" | INI_ALL | PHP 7.3.5 以降で利用可能です。
mcrypt.algorithms_dir | null | INI_ALL |
mcrypt.modes_dir | null | INI_ALL |
memcache.allow_failover | "1" | INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.max_failover_attempts | "20" | INI_ALL | memcache 2.1.0 以降で使用可能です
memcache.chunk_size | "8192" | INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.default_port | "11211" | INI_ALL | memcache 2.0.2 以降で使用可能です
memcache.hash_strategy | "standard" | INI_ALL | memcache 2.2.0 以降で使用可能です
memcache.hash_function | "crc32" | INI_ALL | memcache 2.2.0 以降で使用可能です
memcache.protocol | ascii | INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.redundancy | 1 | INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.session_redundancy | 2 | INI_ALL | memcache 3.0.0 以降で使用可能です
memcache.compress_threshold | 20000 | INI_ALL | memcache 3.0.3 以降で使用可能です
memcache.lock_timeout | 15 | INI_ALL | memcache 3.0.4 以降で使用可能です
memory_limit | "128M" | INI_ALL |
mysql.allow_local_infile | "1" | INI_SYSTEM |
mysql.allow_persistent | "1" | INI_SYSTEM |
mysql.max_persistent | "-1" | INI_SYSTEM |
mysql.max_links | "-1" | INI_SYSTEM |
mysql.trace_mode | "0" | INI_ALL |
mysql.default_port | NULL | INI_ALL |
mysql.default_socket | NULL | INI_ALL |
mysql.default_host | NULL | INI_ALL |
mysql.default_user | NULL | INI_ALL |
mysql.default_password | NULL | INI_ALL |
mysql.connect_timeout | "60" | INI_ALL |
mysqli.allow_local_infile | "0" | INI_SYSTEM | PHP 7.2.16, 7.3.3 より前のバージョンでは デフォルト値は "1" でした。
mysqli.local_infile_directory |  | INI_SYSTEM | PHP 8.1.0 以降で利用可能です。
mysqli.allow_persistent | "1" | INI_SYSTEM |
mysqli.max_persistent | "-1" | INI_SYSTEM |
mysqli.max_links | "-1" | INI_SYSTEM |
mysqli.default_port | "3306" | INI_ALL |
mysqli.default_socket | NULL | INI_ALL |
mysqli.default_host | NULL | INI_ALL |
mysqli.default_user | NULL | INI_ALL |
mysqli.default_pw | NULL | INI_ALL |
mysqli.reconnect | "0" | INI_SYSTEM | PHP 8.2.0 で削除されました。
mysqli.rollback_on_cached_plink | "0" | INI_SYSTEM |
mysqlnd.collect_statistics | "1" | INI_SYSTEM |
mysqlnd.collect_memory_statistics | "0" | INI_SYSTEM |
mysqlnd.debug | "" | INI_SYSTEM |
mysqlnd.log_mask | 0 | INI_ALL |
mysqlnd.mempool_default_size | 16000 | INI_ALL |
mysqlnd.net_read_timeout | "86400" | INI_ALL | PHP 7.2.0 より前のバージョンでは、 デフォルト値は "31536000" で、変更可能な範囲が INI_SYSTEM でした。
mysqlnd.net_cmd_buffer_size | "4096" | INI_SYSTEM |
mysqlnd.net_read_buffer_size | "32768" | INI_SYSTEM |
mysqlnd.sha256_server_public_key | "" | INI_PERDIR |
mysqlnd.trace_alloc | "" | INI_SYSTEM |
mysqlnd.fetch_data_copy | 0 | INI_ALL | PHP 8.1.0 で削除されました。
oci8.connection_class | "" | INI_ALL |
oci8.default_prefetch | "100" | INI_SYSTEM |
oci8.events | Off | INI_SYSTEM |
oci8.max_persistent | "-1" | INI_SYSTEM |
oci8.old_oci_close_semantics | Off | INI_SYSTEM | PHP 8.1.0 以降は非推奨。
oci8.persistent_timeout | "-1" | INI_SYSTEM |
oci8.ping_interval | "60" | INI_SYSTEM |
oci8.prefetch_lob_size | "0" | INI_ALL | PECL OCI8 3.2 以降で利用可能
oci8.privileged_connect | Off | INI_SYSTEM |
oci8.statement_cache_size | "20" | INI_SYSTEM |
odbc.allow_persistent | "1" | INI_SYSTEM |
odbc.check_persistent | "1" | INI_SYSTEM |
odbc.max_persistent | "-1" | INI_SYSTEM |
odbc.max_links | "-1" | INI_SYSTEM |
odbc.defaultlrl | "4096" | INI_ALL |
odbc.defaultbinmode | "1" | INI_ALL |
odbc.default_cursortype | "3" | INI_ALL |
opcache.enable | 1 | INI_ALL |
opcache.enable_cli | 0 | INI_SYSTEM | PHP 7.1.2 と 7.1.6 の間では、デフォルトは 1 でした
opcache.memory_consumption | 128 | INI_SYSTEM |
opcache.interned_strings_buffer | 8 | INI_SYSTEM |
opcache.max_accelerated_files | 10000 | INI_SYSTEM |
opcache.max_wasted_percentage | 5 | INI_SYSTEM |
opcache.use_cwd | 1 | INI_SYSTEM |
opcache.validate_timestamps | 1 | INI_ALL |
opcache.revalidate_freq | 2 | INI_ALL |
opcache.revalidate_path | 0 | INI_ALL |
opcache.save_comments | 1 | INI_SYSTEM |
opcache.fast_shutdown | 0 | INI_SYSTEM | PHP 7.2.0 で削除されました
opcache.enable_file_override | 0 | INI_SYSTEM |
opcache.optimization_level | 0x7FFEBFFF | INI_SYSTEM | PHP 7.3.0 で 0x7FFFBFFF から変更されました。
opcache.inherited_hack | 1 | INI_SYSTEM | PHP 7.3.0 で削除されました
opcache.dups_fix | 0 | INI_ALL |
opcache.blacklist_filename | "" | INI_SYSTEM |
opcache.max_file_size | 0 | INI_SYSTEM |
opcache.consistency_checks | 0 | INI_ALL | PHP 8.1.18 と PHP 8.2.5 で無効。PHP 8.3.0 で削除。
opcache.force_restart_timeout | 180 | INI_SYSTEM |
opcache.error_log | "" | INI_SYSTEM |
opcache.log_verbosity_level | 1 | INI_SYSTEM |
opcache.record_warnings | 0 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.preferred_memory_model | "" | INI_SYSTEM |
opcache.protect_memory | 0 | INI_SYSTEM |
opcache.mmap_base | null | INI_SYSTEM | Windows のみ
opcache.restrict_api | "" | INI_SYSTEM |
opcache.file_update_protection | 2 | INI_ALL |
opcache.huge_code_pages | 0 | INI_SYSTEM |
opcache.lockfile_path | "/tmp" | INI_SYSTEM |
opcache.opt_debug_level | 0 | INI_SYSTEM | PHP 7.1.0 以降で利用可能
opcache.file_cache | null | INI_SYSTEM |
opcache.file_cache_only | 0 | INI_SYSTEM |
opcache.file_cache_consistency_checks | 1 | INI_SYSTEM |
opcache.file_cache_fallback | 1 | INI_SYSTEM | Windows のみ
opcache.validate_permission | 0 | INI_SYSTEM | PHP 7.0.14 以降で利用可能
opcache.validate_root | 0 | INI_SYSTEM | PHP 7.0.14 以降で利用可能
opcache.preload | "" | INI_SYSTEM | PHP 7.4.0 以降で利用可能
opcache.preload_user | "" | INI_SYSTEM | PHP 7.4.0 以降で利用可能
opcache.cache_id | "" | INI_SYSTEM | Windows のみ。PHP 7.4.0 以降で利用可能
opcache.jit | "tracing" | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_buffer_size | 0 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_debug | 0 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_bisect_limit | 0 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_prof_threshold | 0.005 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_root_traces | 1024 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_max_side_traces | 128 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_max_exit_counters | 8192 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_loop | 64 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_func | 127 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_return | 8 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_hot_side_exit | 8 | INI_SYSTEM | PHP 8.0.0 以降で利用可能
opcache.jit_blacklist_root_trace | 16 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_blacklist_side_trace | 8 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_loop_unrolls | 8 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_recursive_calls | 2 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_recursive_returns | 2 | INI_ALL | PHP 8.0.0 以降で利用可能
opcache.jit_max_polymorphic_calls | 2 | INI_ALL | PHP 8.0.0 以降で利用可能
open_basedir | null | INI_ALL |
output_buffering | "0" | INI_PERDIR |
output_handler | null | INI_PERDIR |
pcre.backtrack_limit | "1000000" | INI_ALL |
pcre.recursion_limit | "100000" | INI_ALL |
pcre.jit | "1" | INI_ALL |
pdo.dsn.* |  | php.ini のみ |
pdo_odbc.connection_pooling | "strict" | INI_ALL |
pdo_odbc.db2_instance_name | NULL | INI_SYSTEM | この非推奨の機能は、きっと 将来 削除 されるでしょう。
pgsql.allow_persistent | "1" | INI_SYSTEM |
pgsql.max_persistent | "-1" | INI_SYSTEM |
pgsql.max_links | "-1" | INI_SYSTEM |
pgsql.auto_reset_persistent | "0" | INI_SYSTEM |
pgsql.ignore_notice | "0" | INI_ALL |
pgsql.log_notice | "0" | INI_ALL |
phar.readonly | "1" | INI_ALL |
phar.require_hash | "1" | INI_ALL |
phar.cache_list | "" | INI_SYSTEM |
post_max_size | "8M" | INI_PERDIR |
precision | "14" | INI_ALL |
realpath_cache_size | "16K" | INI_SYSTEM |
realpath_cache_ttl | "120" | INI_SYSTEM |
register_argc_argv | "1" | INI_PERDIR |
report_memleaks | "1" | INI_ALL |
report_zend_debug | "1" | INI_ALL |
request_order | "" | INI_PERDIR |
runkit.superglobal | "" | INI_PERDIR |
runkit.internal_override | "0" | INI_SYSTEM |
sendmail_from | null | INI_ALL |
sendmail_path | "/usr/sbin/sendmail -t -i" | INI_SYSTEM |
serialize_precision | "-1" | INI_ALL | PHP 7.1.0 より前のバージョンでは、デフォルト値は 17 でした。
session.save_path | "" | INI_ALL |
session.name | "PHPSESSID" | INI_ALL |
session.save_handler | "files" | INI_ALL |
session.auto_start | "0" | INI_PERDIR |
session.gc_probability | "1" | INI_ALL |
session.gc_divisor | "100" | INI_ALL |
session.gc_maxlifetime | "1440" | INI_ALL |
session.serialize_handler | "php" | INI_ALL |
session.cookie_lifetime | "0" | INI_ALL |
session.cookie_path | "/" | INI_ALL |
session.cookie_domain | "" | INI_ALL |
session.cookie_secure | "0" | INI_ALL | PHP 7.2.0 より前のバージョンでは、デフォルト値は "" でした。
session.cookie_httponly | "0" | INI_ALL | PHP 7.2.0 より前のバージョンでは、デフォルト値は "" でした。""
session.cookie_samesite | "" | INI_ALL | PHP 7.3.0 から利用可能
session.use_strict_mode | "0" | INI_ALL |
session.use_cookies | "1" | INI_ALL |
session.use_only_cookies | "1" | INI_ALL |
session.referer_check | "" | INI_ALL |
session.cache_limiter | "nocache" | INI_ALL |
session.cache_expire | "180" | INI_ALL |
session.use_trans_sid | "0" | INI_ALL |
session.trans_sid_tags | "a=href,area=href,frame=src,form=" | INI_ALL | PHP 7.1.0 から利用可能
session.trans_sid_hosts | $_SERVER['HTTP_HOST'] | INI_ALL | PHP 7.1.0 から利用可能
session.sid_length | "32" | INI_ALL | PHP 7.1.0 から利用可能
session.sid_bits_per_character | "4" | INI_ALL | PHP 7.1.0 から利用可能
session.upload_progress.enabled | "1" | INI_PERDIR |
session.upload_progress.cleanup | "1" | INI_PERDIR |
session.upload_progress.prefix | "upload_progress_" | INI_PERDIR |
session.upload_progress.name | "PHP_SESSION_UPLOAD_PROGRESS" | INI_PERDIR |
session.upload_progress.freq | "1%" | INI_PERDIR |
session.upload_progress.min_freq | "1" | INI_PERDIR |
session.lazy_write | "1" | INI_ALL |
session.hash_function | "0" | INI_ALL | PHP 7.1.0 で削除されました。
session.hash_bits_per_character | "4" | INI_ALL | PHP 7.1.0 で削除されました。
session.entropy_file | "" | INI_ALL | PHP 7.1.0 で削除されました。
session.entropy_length | "0" | INI_ALL | PHP 7.1.0 で削除されました。
short_open_tag | "1" | INI_PERDIR |
SMTP | "localhost" | INI_ALL |
smtp_port | "25" | INI_ALL |
soap.wsdl_cache_enabled | 1 | INI_ALL |
soap.wsdl_cache_dir | /tmp | INI_ALL |
soap.wsdl_cache_ttl | 86400 | INI_ALL |
soap.wsdl_cache | 1 | INI_ALL |
soap.wsdl_cache_limit | 5 | INI_ALL |
sql.safe_mode | "0" | INI_SYSTEM | PHP 7.2.0 で削除
sqlite3.extension_dir | "" | INI_SYSTEM |
sqlite3.defensive | 1 | INI_USER | PHP 7.2.17 ,7.3.4 以降、かつ libsqlite ? 3.26.0 でビルドした場合に利用可能 PHP 8.2.0 より前のバージョンでは、この値は INI_SYSTEM のモードでのみ変更可能でした。
syslog.facility | "LOG_USER" | INI_SYSTEM | PHP 7.3.0 以降で利用可能
syslog.filter | "no-ctrl" | INI_ALL | PHP 7.3.0 以降で利用可能
syslog.ident | "php" | INI_SYSTEM | PHP 7.3.0 以降で利用可能
sys_temp_dir | "" | INI_SYSTEM |
sysvshm.init_mem | 10000 | INI_SYSTEM |
tidy.default_config | "" | INI_SYSTEM |
tidy.clean_output | "0" | INI_USER |
track_errors | "0" | INI_ALL | PHP 7.2.0 以降は非推奨になり、PHP 8.0.0 で 削除されました。
unserialize_callback_func | null | INI_ALL |
unserialize_max_depth | "4096" | INI_ALL | PHP 7.4.0 以降で利用可能。
uploadprogress.file.filename_template | "/tmp/upt_%s.txt" | INI_ALL |
upload_max_filesize | "2M" | INI_PERDIR |
max_file_uploads | 20 | INI_SYSTEM |
upload_tmp_dir | null | INI_SYSTEM |
url_rewriter.hosts | "" | INI_ALL | PHP 7.1.0 以降で利用可能
url_rewriter.tags | "form=" | INI_ALL | PHP 7.1.0 より前のバージョンでは、デフォルト値は "a=href,area=href,frame=src,form=,fieldset=" でした。
user_agent | null | INI_ALL |
user_dir | null | INI_SYSTEM |
user_ini.cache_ttl | "300" | INI_SYSTEM |
user_ini.filename | ".user.ini" | INI_SYSTEM |
uopz.disable | "0" | INI_SYSTEM | uopz 5.0.2 以降で利用可能
uopz.exit | "0" | INI_SYSTEM | uopz 6.0.1 以降で利用可能
uopz.overloads | "1" | INI_SYSTEM | uopz 2.0.2 以降で利用可能。uopz 5.0.0 以降は削除されています
variables_order | "EGPCS" | INI_PERDIR |
windows.show_crt_warning | "0" | INI_ALL |
xbithack | "0" | INI_ALL |
xmlrpc_errors | "0" | INI_SYSTEM |
xmlrpc_error_number | "0" | INI_ALL |
yaz.keepalive | "120" | INI_ALL |
yaz.log_mask | null | INI_ALL | yaz 1.0.3 以降で利用可能。
zend.assertions | "1" | INI_ALL |
zend.detect_unicode | "1" | INI_ALL |
zend.enable_gc | "1" | INI_ALL |
zend.multibyte | "0" | INI_PERDIR |
zend.script_encoding | null | INI_ALL |
zend.signal_check | "0" | INI_SYSTEM |
zend_extension | null | php.ini のみ |
zlib.output_compression | "0" | INI_ALL |
zlib.output_compression_level | "-1" | INI_ALL |
zlib.output_handler | "" | INI_ALL |


php.ini のセクション一覧

この一覧では、ホスト単位やパス単位で PHP の設定を行いたい場合に設定する php.ini のセクションをまとめます。これらのセクションはオプションです。

これらのセクションは、PHP に直接影響を及ぼすわけではありません。 さまざまな php.ini ディレクティブをひとまとめにして、 それを特定のホストや特定のパスにだけ適用する場合に使用します。

これらのセクションは CGI/FastCGI モードでのみ使用します。 extension および zend_extension ディレクティブは設定できません。

セクション
名前 | 変更可能 | 変更履歴
[HOST=] | INI_SYSTEM |
[PATH=] | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

[HOST=<host>]

このセクションで指定した php.ini ディレクティブは、 指定した名前のホスト上でのみ有効となります。

例1 dev. ドメインではエラーを画面に表示させるようにする例

[HOST=dev.site.com]
error_reporting = E_ALL
display_errors = On

[PATH=<path>]

このセクションで指定した php.ini ディレクティブは、 指定したパスで実行したスクリプトでのみ有効となります。

例2 保護エリア内でのスクリプトのセキュリティ確保

[PATH=/home/site/public/secure]
auto_prepend_file=security.php


コア php.ini ディレクティブに関する説明

このリストには、PHPを設定する際に使用可能なコア php.ini ディレクティブが 含まれています。拡張モジュールにより処理されるディレクティブは、それぞれの 拡張モジュールのドキュメントページにリストと詳細が記述されています。 例えば、セッション用ディレクティブに関する情報は、 セッションのページにあります。

注意:

これらのデフォルト値は、php.ini が読み込まれなかったときに使われるものです。 運用時と開発時では php.ini の値が変わることもあるでしょう。

言語オプション

言語およびその他の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
short_open_tag | "1" | INI_PERDIR |
precision | "14" | INI_ALL |
serialize_precision | "-1" | INI_ALL | PHP 7.1.0 より前は、デフォルト値は 17 でした。
disable_functions | "" | INI_SYSTEM のみ |
disable_classes | "" | php.ini のみ |
exit_on_timeout | "" | INI_ALL |
expose_php | "1" | php.ini のみ |
hard_timeout | "2" | INI_SYSTEM | PHP 7.1.0 以降で利用可能。
zend.exception_ignore_args | "0" | INI_ALL | PHP 7.4.0 以降で利用可能。
zend.multibyte | "0" | INI_ALL |
zend.script_encoding | NULL | INI_ALL |
zend.detect-unicode | NULL | INI_ALL |
zend.signal_check | "0" | INI_SYSTEM |
zend.assertions | "1" | INI_ALL (制限あり) |
zend.exception_string_param_max_len | "15" | INI_ALL | PHP 8.0.0 以降で利用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

short_open_tag bool

PHP タグの短縮型 (<? ?>) を使用 可能にするかどうかを設定します。PHPをXMLと組み合わせて用いる 場合は、<?xml ?>をファイル中で用 いるためにこのオプションをオフにする必要があります。オンにし た場合にPHPでXMLを出力するには、例えば、次のようにします。 <?php echo '<?xml version="1.0"?>'; ?> これをオフにした場合、長い方の形式のタグ (<?php ?>)を使用する必要があります。

注意:

これは、<?= 記法に影響を与えません。常に有効となります。

precision int
浮動小数点数に関して表示される最大桁数を指定します。 -1 は、数値を丸める際に拡張アルゴリズムを用いることを意味します。
serialize_precision int
浮動小数点数をシリアライズするときに格納する桁数を指定します。 -1 は、数値を丸める際に拡張アルゴリズムを用いることを意味します。
expose_php bool

PHP がサーバーにインストールされていることを全世界に晒し、PHP のバージョンも HTTP ヘッダに含めます (X-Powered-By: PHP/5.3.7 など)。

disable_functions string
このディレクティブを使うと、特定の関数を無効にすることができます。 関数名の一覧をカンマ区切りで指定します。 PHP 8.0.0 以降では、関数を無効にすると定義を削除しますが、 ユーザーランドで再定義できます。 PHP 8.0.0 より前のバージョンでは、 関数を無効にすると、その関数は呼び出せませんでした。 このディレクティブを使って無効にできるのは、 内部関数 だけです。 ユーザー定義関数 は影響を受けません。 このディレクティブは php.ini で設定しなければなりません。 httpd.conf では設定できません。
disable_classes string

このディレクティブを使うと、特定のクラスを無効にすることができます。 クラス名の一覧をカンマ区切りで指定します。 クラスを無効にすると、クラスのインスタンス化ができなくなります。

このディレクティブを使って無効にできるのは、内部クラスのみです。 ユーザーが定義したクラスは影響を受けません。

このディレクティブは php.ini で設定しなければなりません。 httpd.conf では設定できません。
zend.assertions int
1 にすると、アサーションのコードを生成して実行します (開発モード)。 0 にすると、アサーションのコードは生成しますが実行時にはスキップします (実行しません)。 -1 にすると、アサーションのコードを生成せず、アサーションのコストがゼロになります (実運用モード)。

注意:

実運用モードで開始したプロセスでは、zend.assertions を実行時に変更することはできません。アサーションのコードが生成されていないからです。

開発モードで開始したプロセスでは、zend.assertions を実行時に -1 に変更することはできません。

zend.exception_string_param_max_len int
文字列化されたスタックトレース中の、関数の引数の長さの最大値。 "0" と "1000000" の間でなければいけません。
hard_timeout int

max_execution_time で設定されたタイムアウトに達すると、 PHPランタイムはリソースをgracefulに開放します。 リソースを開放する処理が何らかの原因で止まってしまった場合、 hard_timeout のカウントがここで設定した秒数行われます。 hard_timeout のタイムアウトに達すると、 PHP はgracefulにリソースを開放せずに終了します。 この値を 0 に設定すると、この機能は無効になります。

PHP が hard timeout で停止すると、 以下のようなメッセージが残るでしょう。

Fatal error: Maximum execution time of 30+2 seconds exceeded (terminated) in Unknown on line 0

zend.exception_ignore_args bool

例外経由で生成されたスタックトレースから、引数を除外します。

zend.multibyte bool

マルチバイトエンコーディングで書かれたソースファイルをパースできるようにします。 zend.multibyte を有効にしないと、マルチバイト文字データの中に特殊文字を含むエンコーディング (SJIS や BIG5 など) を使えません。 ISO-8859-1 互換のエンコーディングである UTF-8 や EUC などを使う場合は、このオプションは不要です。

zend.multibyte を有効にしたい場合は、mbstring 拡張モジュールを有効にしなければいけません。

zend.script_encoding string

この値を使うのは、 declare(encoding=...) ディレクティブがスクリプトの先頭に存在しない場合です。 ISO-8859-1 非互換のエンコーディングを使う場合は、 zend.multibyte と zend.script_encoding を両方とも指定する必要があります。

リテラル文字列は、zend.script_encoding から mbstring.internal_encoding に変換されます。 mb_convert_encoding() が呼ばれたときと同じです。

zend.detect_unicode bool

BOM (Byte Order Mark) を調べ、 ファイルが有効なマルチバイト文字を含むかどうかを確認します。 この検出は、 __halt_compiler() の処理より前に行われます。 Zend Multibyte モードでのみ利用可能です。

zend.signal_check bool

置き換えられたシグナルハンドラを、シャットダウン時にチェックします。

exit_on_timeout bool

これは Apache1 の mod_php だけで使える項目で、PHP の実行タイムアウトが発生したときに Apache の子プロセスを強制終了させます。このタイムアウトがおこると Apache1 の内部で longjmp() がコールされ、その結果としていくつかの拡張モジュールが一貫性を欠く状態になってしまいます。 プロセスを強制終了させることで、未処理のロックやメモリの後始末も行います。

リソース制限

リソース制限
名前 | デフォルト | 変更可能 | 変更履歴
memory_limit | "128M" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

memory_limit int

スクリプトが確保できる最大メモリをバイト数で指定します。この命令は、 正しく書かれていないスクリプトがサーバーのメモリを食いつぶすことを防止するのに役立ちます。 もし、使用可能メモリに制限を設けたくない場合は、 ここに -1 を指定してください。

intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。

max_execution_time も参照ください。

パフォーマンスチューニング

パフォーマンスチューニング
名前 | デフォルト | 変更可能 | 変更履歴
realpath_cache_size | "4M" | INI_SYSTEM | PHP 7.0.16 および 7.1.2 より前のバージョンでは、 デフォルト値は "16K" でした。
realpath_cache_ttl | "120" | INI_SYSTEM |

注意:

open_basedir を使用すると、 realpath キャッシュが disable にされます。

以下に設定ディレクティブに関する 簡単な説明を示します。

realpath_cache_size int

PHP が使用する realpath キャッシュの大きさを設定します。 PHP で大量にファイルをオープンする際に、 この値を大きくすることによってファイル操作のパフォーマンスを 向上させます。

このサイズが表すのは、格納するパス文字列の総バイト数と、 キャッシュエントリに関連づけるデータのサイズを足したものです。 つまり、長いパスをキャッシュに格納するには、キャッシュのサイズを大きくしなければいけません。 この値を使って、最大何件のパスをキャッシュするのかを制御することはできません。

キャッシュエントリのデータに必要なサイズは、システムによって変わります。

realpath_cache_ttl int

与えられたファイルやディレクトリについての realpath 情報キャッシュの有効期限を (秒単位で) 設定します。 ファイルを変更することがほとんどない場合は、 この値を大きくすることを検討してください。

データ処理

データ処理設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
arg_separator.output | "&" | INI_ALL |
arg_separator.input | "&" | INI_SYSTEM|INI_PERDIR |
variables_order | "EGPCS" | INI_PERDIR |
request_order | "" | INI_PERDIR |
auto_globals_jit | "1" | INI_PERDIR |
register_argc_argv | "1" | INI_PERDIR |
enable_post_data_reading | "1" | INI_PERDIR |
post_max_size | "8M" | INI_PERDIR |
auto_prepend_file | "" | INI_PERDIR |
auto_append_file | "" | INI_PERDIR |
default_mimetype | "text/html" | INI_ALL |
default_charset | "UTF-8" | INI_ALL |
input_encoding | "" | INI_ALL |
output_encoding | "" | INI_ALL |
internal_encoding | "" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

arg_separator.output string

PHPがURLを生成する際にURL引数を区分するために使用されるセパレータ。

arg_separator.input string

入力されたURLを変数にパースする際にPHPが使用するセパレータのリスト。

注意:

このディレクティブで指定した全ての文字は、 セパレータとして認識されます!

variables_order string

EGPCS (Environment (環境変数)、 Get、Post、 Cookie (クッキー)、そして Server) 変数のパースの順番を設定します。例えば variables_order を "SP" に設定すると、PHP は スーパーグローバル $_SERVER および $_POST を作成しますが、 $_ENV、$_GET および $_COOKIE は作成しません。"" に設定すると、一切 スーパーグローバル を設定しません。

警告

CGI および FastCGI SAPI の両方で、 $_SERVER にも環境変数の値が格納されます。 つまり、S を指定すると、 ES と指定したのと同じ意味になります。 これは、E が他のどこかで指定されていたとしても同じです。

注意:

$_REQUEST の内容や順序も、このディレクティブの影響を受けます。

request_order string

このディレクティブは、PHP が GET 変数や POST 変数そしてクッキー変数を _REQUEST 配列に登録する際の順序を表します。 登録は左から右の順に行い、後から登録した値が古い値を上書きします。

このディレクティブが設定されていない場合は、variables_order を使用して $_REQUEST を設定します。

デフォルトの配布状態の php.ini ファイルには、クッキーの 'C' が含まれていないことに注意しましょう。 セキュリティを考慮したためです。

auto_globals_jit bool

有効にした場合、SERVER、REQUEST および ENV 変数はスクリプトの開始時ではなく、 最初に使用された時 (Just In Time) に作成されるようになります。 これらの変数がスクリプトの中で使用されない場合、 このディレクティブを使用することで性能が向上します。

警告

SERVER、REQUEST および ENV 変数の利用チェックはコンパイル時に行われます。 したがって、たとえば 可変変数 で使用した場合は初期化を行いません。

register_argc_argv bool
PHPが変数argvとargcを宣言するかどうかを指定します (これらにはGETの情報が格納されます)。 コマンドライン も参照ください。
enable_post_data_reading bool
このオプションを無効にすると、$_POST や $_FILES に値が入らなくなります。 この場合、投稿されたデータを読むには、ストリームラッパー php://input を使う以外の方法はなくなります。 これは、リクエストをプロキシしたり POST データを処理する際のメモリ消費量を抑えたりする際に有用です。
post_max_size int
POSTデータに許可される最大サイズを設定します。この設定は、ファ イルアップロードにも影響します。大きなファイルをアップロード するには、この値を upload_max_filesize より大きく設定する必要があります。 一般的に memory_limit は、 post_max_sizeよりも大きく する必要があります。 intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。 POSTデータの大きさが、post_max_sizeより大きい場合、 $_POST と $_FILES スーパーグローバル は空になります。この事象は、いくつかの方法で検出することができます。 例えば、$_GET 変数をデータを <form action="edit.php?processed=1">のように 処理するスクリプトに渡し、 $_GET['processed'] が設定されているかどうかを 確認する方法があります。

注意:

PHP では、バイト値を表すショートカット K (kilo)、M (mega) および G (giga) を使用することができます。 これらを使用した場合、PHP が規約にしたがって自動的に値を判断します。 32 ビット符号付き整数の最大値を上回る値を指定しないように注意しましょう (32 ビットシステムを使用している場合)。 そのようなことをすると、スクリプトの実行が失敗します。

post_max_size の変更履歴
バージョン | 説明
5.3.4 | コンテンツタイプが application/x-www-form-urlencoded であったり、あるいは PHP に登録されていないものであった場合は、 post_max_size = 0 にしても上限を無効にできなくなりました。
5.3.2 , 5.2.12 | post_max_size を 0 にすることで、サイズを無制限にできるようになりました。

auto_prepend_file string

メインファイルの前に自動的に付加されるファイルの名前を指定します。 このファイルは、require 関数のコール時と同様に読み込まれます。 このため、include_path が使用されます。

特別な値 none を指 定すると、ファイルを前に追加する機能は無効となります。

auto_append_file string

メインファイルの後に自動的に追加されるファイルの名前を指定します。 このファイルは、require 関数のコール時と同様に読み込まれます。 このため、include_path が使用されます。

none を値として 指定するとこの自動付加機能はオフとなります。

注意: スクリプトが exit() で終了する場合、 この自動付加機能は使用されません 。

default_mimetype string

デフォルトでは、PHP はメディアタイプを Content-Type ヘッダで出力します。 これを無効にするには、ここに空文字列を設定しましょう。

PHP のデフォルトのメディアタイプは text/html です。

default_charset string

"UTF-8" がデフォルトの値です。 htmlentities() や html_entity_decode() そして htmlspecialchars() で encoding パラメータを省略した場合は、このデフォルト値を利用します。 また、default_charset の値は、 iconv 関数で iconv.input_encoding、 iconv.output_encoding、 iconv.internal_encoding が未設定の場合や、 mbstring 関数で mbstring.http_input mbstring.http_output mbstring.internal_encoding が未設定の場合のデフォルトとしても用いられます。

すべてのバージョンの PHP は、PHP から送信する Content-Type ヘッダのデフォルト値としてこれを使います。 ただし、header() で上書きされている場合は別です。

default_charset に空文字列を指定することは、おすすめしません。

input_encoding string

この設定は、mbstring や iconv などのマルチバイトモジュールが使うものです。デフォルトは空文字列です。

output_encoding string

この設定は、mbstring や iconv などのマルチバイトモジュールが使うものです。デフォルトは空文字列です。

internal_encoding string

この設定は、mbstring や iconv などのマルチバイトモジュールが使うものです。デフォルトは空文字列です。 空文字列を指定した場合は、 default_charset を利用します。

パスおよびディレクトリ

パスおよびディレクトリ設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
include_path | ".;/path/to/php/pear" | INI_ALL |
open_basedir | NULL | INI_ALL |
doc_root | NULL | INI_SYSTEM |
user_dir | NULL | INI_SYSTEM |
user_ini.cache_ttl | "300" | INI_SYSTEM |
user_ini.filename | ".user.ini" | INI_SYSTEM |
extension_dir | "/path/to/php" | INI_SYSTEM |
extension | NULL | php.ini のみ |
zend_extension | NULL | php.ini のみ |
cgi.check_shebang_line | "1" | INI_SYSTEM |
cgi.discard_path | "0" | INI_SYSTEM |
cgi.fix_pathinfo | "1" | INI_SYSTEM |
cgi.force_redirect | "1" | INI_SYSTEM |
cgi.nph | "0" | INI_SYSTEM |
cgi.redirect_status_env | NULL | INI_SYSTEM |
cgi.rfc2616_headers | "0" | INI_ALL |
fastcgi.impersonate | "0" | INI_SYSTEM |
fastcgi.logging | "1" | INI_SYSTEM |

以下に設定ディレクティブに関する 簡単な説明を示します。

include_path string

require、include、 fopen()、file()、 readfile() および file_get_contents() 関数がファイルを 探すディレクトリのリストを指定します。フォーマットは、システ ムの環境変数 PATHと同じです。つまり、UNIXでは コロンで、Windowsではセミコロンで区切ったディレクトリのリスト で指定します。

PHP は、インクルードするファイルを探す際に インクルードパスの各エントリを個別に調べます。 まず最初のパスを調べ、見つからなければ次のパスを調べ、...... というように、ファイルが見つかるか E_WARNING あるいは E_ERROR が発生するまで続けます。インクルードパスを実行時に変更したり設定したりするには set_include_path() を使用します。

例1 Unix include_path

include_path=".:/php/includes"

例2 Windows include_path

include_path=".;c:\php\includes"

インクルードパスに . (カレントディレクトリ) を指定すると、相対パス指定によるインクルードができるようになります。 しかし、インクルードのたびに毎回 PHP にカレントディレクトリをチェックさせるよりは、 明示的に include './file' を指定したほうが効率的です。

注意:

ENV 変数は .ini ファイルの中でもアクセスできます。 たとえば、ホームディレクトリを参照するときに ${LOGIN} や ${USER} が使えます。

環境変数はサーバー API の種類によって異なるので、この環境も異なることがあります。

例3 Unix include_path で環境変数 ${USER} を使う例

include_path = ".:${USER}/pear/php"

open_basedir string

PHP からアクセスできるファイルを、指定したディレクトリツリーに限定します。 ファイル自身も含みます。

スクリプトから include や fopen() などでファイルシステムにアクセスしようとしたときに、そのファイルの場所をチェックします。 ファイルが指定したディレクトリツリーの外にある場合は、PHP はそのファイルへのアクセスを拒否します。 シンボリックリンクの解決も行うので、 シンボリックリンクでこの制限を回避することはできません。 存在しないファイルへのシンボリックリンクは解決できないので、 ファイル名を open_basedir と比較します。

open_basedir は、ファイルシステム関数以外の挙動にも影響を及ぼします。 たとえば MySQL の設定で mysqlnd ドライバーを使うようにしている場合に、 LOAD DATA INFILE は open_basedir の影響を受けます。 PHP の拡張モジュールの多くが、open_basedir をこのように利用しています。

特別な値 . は、 スクリプトの作業ディレクトリを表します。これをベースディレクトリとすることもできますが、 少し危険です。スクリプトの作業ディレクトリは chdir() で容易に変更できるからです。

httpd.conf で、(たとえばバーチャルホスト単位で) open_basedir を無効にすることができます。 その他の設定ディレクティブの場合と 同様に "php_admin_value open_basedir none" のようにします。

Windows では、ディレクトリの区切りはセミコロンとなります。 その他のシステムでは、コロンで区切ります。Apache モジュールでは、 親ディレクトリからの open_basedir パスを自動的に継承します。

open_basedir で指定する制約は、 ディレクトリ名となります。プレフィックスではありません。

デフォルトでは、すべてのファイルを開くことができます。

注意:

open_basedir の設定を実行時に厳しくすることができます。 これは、open_basedir が php.ini で /www/ と設定されているときに、スクリプト内で ini_set() を使って設定を厳しくして /www/tmp/ のようにできるということです。 複数のディレクトリを指定するときには、定数 PATH_SEPARATOR を使えば OS に依存しない記述ができます。

注意:

open_basedir を使用すると、realpath_cache_size　は 0 に設定され、結果として realpath キャッシュは disable にされます。

警告

open_basedir は、追加のセキュリティ機構でしかありません。 つまり、広範囲に適用できるものでは決してないため、 セキュリティを高める必要がある際にそれだけに依存してはいけません。

doc_root string

サーバーにおけるPHPの"ルートディレクトリ"です。この値は空で無 い場合のみ使用されます。 PHPがFORCE_REDIRECTを指定してコンパイルされていない場合、 (IIS以外の)WebサーバーのもとでCGIとしてPHPを実行する際には、 doc_rootを指定するべきです。 他の方法としては、後述の cgi.force_redirect 設定の使用があります。

user_ini.cache_ttl int

user_ini.filename string

user_dir string

PHPファイル用にユーザーのホームディレクトリ として使用する基本ディレクトリの名前。例えば、 public_html となります。

extension_dir string

動的にロード可能な拡張モジュールを置くディレクトリを 指定します。 絶対パスを指定することを推奨します。 enable_dl と dl() も参照ください。

extension string

PHP の開始時に、どの動的ロード可能な拡張モジュールをロードするかを指定します。

zend_extension string

PHP の起動時に読み込む動的読み込み可能な Zend 拡張モジュール (たとえば XDebug) の名前。

cgi.check_shebang_line bool

CGI 版の PHP が、実行するスクリプトの先頭にある #! から始まる行 (shebang) をチェックするかどうかを指定します。 同じスクリプトをスタンドアロンと PHP CGI 経由の両方で使用したい場合などに、 この行が必要になるでしょう。このディレクティブを on にしておくと、 CGI 版の PHP はこの行の内容を読み飛ばすようになります。

cgi.discard_path bool

これを有効にすると、PHP CGI のバイナリを web ルートのツリーの外部に配置できるようになります。 これで、.htaccess のセキュリティをくぐり抜けてアクセスされる心配がなくなります。

cgi.fix_pathinfo bool

本来の PATH_INFO/PATH_TRANSLATED サポートをCGIで提供します。 PHPの以前の動作は、 SCRIPT_FILENAMEにPATH_TRANSLATEDを設定するというもので、 PATH_INFOの定義を理解していませんんでした。 PATH_INFOに関する詳細については、CGIの仕様を参照ください。 このオプションを1にすることにより、 PHP CGIはこのパスを仕様にあうように修正します。 ゼロとすると、 PHPは以前と同様に動作します。これは、デフォルトでオンになっています。 PATH_TRANSLATEDではなく、SCRIPT_FILENAMEを使用するようにスクリプト を修正する必要があります。

cgi.force_redirect bool

cgi.force_redirect は、ほとんどのWebサーバーのもとで CGI として PHP を実行する際のセキュリティを確保するために必要です。 未定義のままの場合、PHPはデフォルトでこれを on にします。 これを off にする時は、自己責任 の下に 行なってください。

注意:

Windowsユーザー: IIS を使う場合は、このオプションは 必ず off にしなければなりません。 OmniHTTPD や Xitami の場合も同様です。

cgi.nph bool

cgi.nph を有効にすると、すべてのリクエストに対して cgi がステータスコード 200 を返すように強制します。

cgi.redirect_status_env string

cgi.force_redirect を on にし、Apache または Netscape (iPlanet) Webサーバーのもとで実行していない場合、 実行を継続して良いかどうかをPHPが判断するために 環境変数の名前を設定する必要があるかもしれません。

注意:

この変数を設定することにより、セキュリティ上の問題を発生する 場合があります。行うことのリスクをまず把握してください。

cgi.rfc2616_headers int

PHP に、HTTP レスポンスを返す際に、どの形式のヘッダーを使うか 指示します。0 にセットした場合は、Apache やその他の web サーバーで サポートされている » RFC 3875 Status: ヘッダーを送信します。このオプションの値を 1 にセットした場合は、PHP は » RFC 2616 の仕様に適合した形式のヘッダーを送信します。

このオプションを有効にして、かつ PHP を CGI 環境 (PHP-FPM など) で動かしている場合は、 標準の RFC 2616 形式の HTTP ステータスレスポンスヘッダーを使ってはいけません。そのかわりに RFC 3875 形式にする必要があります。つまり、 header("HTTP/1.0 404 Not found"); ではなく header("Status: 404 Not Found"); にしなければいけないということです。

よくわからないときは、この値は 0 のままにしておきましょう。

fastcgi.impersonate string

IIS (または WINNT ベースの OS) のもとでの FastCGI は、 クライアントをコールする際にセキュリティトークンを 匿名化する機能をサポートしています。 これにより、IIS がリクエストを処理するセキュリティコンテキストを 定義できるようになります。Apacheのもとで実行される mod_fastcgi は現在 (2002/03/17) この機能をサポートしていません。 IIS のもとで実行するには、1 に設定してください。 デフォルトは 0 です。

fastcgi.logging bool

FastCGI 使用中の SAPI ロギングを有効にします。 デフォルトはロギングが有効となっています。

ファイルアップロード

ファイルアップロード設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
file_uploads | "1" | INI_SYSTEM |
upload_tmp_dir | NULL | INI_SYSTEM |
max_input_nesting_level | 64 | INI_PERDIR |
max_input_vars | 1000 | INI_PERDIR |
upload_max_filesize | "2M" | INI_PERDIR |
max_file_uploads | 20 | INI_PERDIR |

以下に設定ディレクティブに関する 簡単な説明を示します。

file_uploads bool

HTTP ファイルアップロード を有効とするかどうか。 upload_max_filesize, upload_tmp_dir, post_max_size ディレクティブも参照ください。

upload_tmp_dir string

ファイルアップロード時にファイル保存に用いるテンポラリディレクトリ。 PHPの実行ユーザーが書きこみ可能である必要が あります。指定されない場合、PHPはシステムのデフォルト設定を 使用します。

ここで指定したディレクトリに書き込むことができない場合、 PHP はかわりにシステムのデフォルトテンポラリディレクトリを使用します。 open_basedir が on の場合は、システムのデフォルトテンポラリディレクトリへのアップロードを許可しておかなければなりません。

upload_max_filesize int

アップロードされるファイルの最大サイズ。

post_max_size には、 この値より大きな値を指定しなければいけません。

intを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。
max_file_uploads int

同時にアップロードできるファイルの最大数。 何もファイルを指定せずに送信されたアップロードフィールドは ファイル数に数えられません。

SQL全般

SQL全般の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
sql.safe_mode | "0" | INI_SYSTEM | PHP 7.2.0 以降は削除されています。

以下に設定ディレクティブに関する 簡単な説明を示します。

sql.safe_mode bool

オンにすると、デフォルト値が指定されているデータベース接続関数は、 引数で指定された値よりもデフォルト値を優先して使用します。 デフォルト値の詳細については、関連するデータベースのドキュメントを参照ください。

警告

この機能は PHP 7.2.0 で 削除 されました。

Windows のみ

Windows 特有の設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
windows.show_crt_warning | "0" | INI_ALL |

以下に設定ディレクティブに関する 簡単な説明を示します。

windows.show_crt_warning bool

このディレクティブを有効にすると、Windows CRT の警告を表示します。


拡張モジュールの一覧/分類

目次

  • アルファベット順
  • 所属
  • 状態

この付録では、PHP マニュアルに掲載されている 150 以上の 拡張モジュールを分類します。


アルファベット順

  • Apache
  • APCu
  • 配列
  • BC Math
  • Bzip2
  • カレンダー
  • クラス/オブジェクト
  • CommonMark
  • COM
  • Componere
  • Ctype
  • CUBRID
  • cURL
  • Date/Time
  • DBA
  • dBase
  • ダイレクト IO
  • ディレクトリ
  • DOM
  • Data Structures
  • Eio
  • Enchant
  • エラー処理
  • Ev
  • Event
  • プログラムの実行
  • Exif
  • Expect
  • FANN
  • FDF
  • FFI
  • Fileinfo
  • ファイルシステム
  • Filter
  • FastCGI Process Manager(FPM)
  • FTP
  • 関数処理
  • Gearman
  • Gender
  • GeoIP
  • Gettext
  • Gmagick
  • GMP
  • GnuPG
  • Hash
  • HRTime
  • Firebird/InterBase
  • IBM DB2
  • iconv
  • Igbinary
  • GD
  • ImageMagick
  • IMAP
  • PHP Options/Info
  • Inotify
  • intl
  • JSON
  • LDAP
  • libxml
  • Lua
  • LuaSandbox
  • LZF
  • メール
  • Mailparse
  • Math
  • マルチバイト文字列
  • Mcrypt
  • Memcache
  • Memcached
  • Mhash
  • その他
  • mqseries
  • MySQL (最初の API)
  • Mysql_xdevapi
  • MySQLi
  • Mysqlnd
  • ネットワーク
  • OAuth
  • OCI8
  • OPcache
  • OpenAL
  • OpenSSL
  • 出力制御
  • parallel
  • Parle
  • パスワードのハッシュ
  • PCNTL
  • PCRE
  • PDO
  • CUBRID (PDO)
  • MS SQL Server (PDO)
  • Firebird (PDO)
  • IBM (PDO)
  • Informix (PDO)
  • MySQL (PDO)
  • Oracle (PDO)
  • ODBC and DB2 (PDO)
  • PostgreSQL (PDO)
  • SQLite (PDO)
  • MS SQL Server (PDO)
  • PostgreSQL
  • Phar
  • phpdbg
  • POSIX
  • PS
  • Pspell
  • pthreads
  • Quickhash
  • Radius
  • Random
  • Rar
  • Readline
  • Recode
  • リフレクション
  • Rnp
  • RpmInfo
  • RRD
  • runkit7
  • ScoutAPM
  • Seaslog
  • セマフォ
  • Sessions
  • 共有メモリ
  • Simdjson
  • SimpleXML
  • SNMP
  • SOAP
  • ソケット
  • Sodium
  • Solr
  • SPL
  • SQLite3
  • SQLSRV
  • ssdeep
  • SSH2
  • Statistics
  • Stomp
  • ストリーム
  • 文字列
  • SVM
  • SVN
  • Swoole
  • Sync
  • Taint
  • TCP
  • Tidy
  • Tokenizer
  • Trader
  • UI
  • ODBC
  • uopz
  • URLs
  • V8js
  • 変数操作
  • var_representation
  • Varnish
  • WDDX
  • win32service
  • WinCache
  • wkhtmltox
  • xattr
  • xdiff
  • Xhprof
  • XLSWriter
  • XML パーサ
  • XMLDiff
  • XMLReader
  • XML-RPC
  • XMLWriter
  • XSL
  • Yac
  • Yaconf
  • Yaf
  • Yaml
  • Yar
  • YAZ
  • Zip
  • Zlib
  • 0MQ messaging
  • ZooKeeper


所属

コア拡張

これらは実際のところ拡張ではありません。 PHP のコアに組み込まれており、 コンパイルオプションで無効にすることはできません。

  • 配列

  • クラス/オブジェクト

  • Date/Time

  • ディレクトリ

  • エラー処理

  • プログラムの実行

  • ファイルシステム

  • FastCGI Process Manager(FPM)

  • 関数処理

  • Hash

  • PHP Options/Info

  • JSON

  • メール

  • Math

  • その他

  • ネットワーク

  • OPcache

  • 出力制御

  • パスワードのハッシュ

  • PCRE

  • Random

  • リフレクション

  • SPL

  • ストリーム

  • 文字列

  • URLs

  • 変数操作

バンドルされている拡張

これらの拡張は PHP にバンドルされています。

  • Apache

  • BC Math

  • カレンダー

  • COM

  • Ctype

  • DBA

  • Exif

  • FFI

  • Fileinfo

  • Filter

  • FTP

  • iconv

  • GD

  • intl

  • マルチバイト文字列

  • Mhash

  • PCNTL

  • PDO

  • Phar

  • phpdbg

  • POSIX

  • セマフォ

  • Sessions

  • 共有メモリ

  • ソケット

  • SQLite3

  • Tokenizer

  • Zlib

外部拡張

これらの拡張は PHP にバンドルされていますが、コンパイルするには外部ライブラリが必要となります。

  • Bzip2

  • cURL

  • DOM

  • Enchant

  • Gettext

  • GMP

  • IMAP

  • LDAP

  • libxml

  • MySQLi

  • Mysqlnd

  • OCI8

  • OpenSSL

  • MS SQL Server (PDO)

  • Firebird (PDO)

  • MySQL (PDO)

  • Oracle (PDO)

  • ODBC and DB2 (PDO)

  • PostgreSQL (PDO)

  • SQLite (PDO)

  • PostgreSQL

  • Pspell

  • Readline

  • SimpleXML

  • SNMP

  • SOAP

  • Sodium

  • Tidy

  • ODBC

  • XML パーサ

  • XMLReader

  • XMLWriter

  • XSL

  • Zip

PECL 拡張

これらの拡張は » PECL にあります。 また、外部のライブラリを必要とするかもしれません。PECL には、この他にもまだ PHP マニュアルで文書化されていない拡張があります。

  • APCu

  • CommonMark

  • Componere

  • CUBRID

  • dBase

  • ダイレクト IO

  • Data Structures

  • Eio

  • Ev

  • Event

  • Expect

  • FANN

  • FDF

  • Gearman

  • Gender

  • GeoIP

  • Gmagick

  • GnuPG

  • HRTime

  • Firebird/InterBase

  • IBM DB2

  • Igbinary

  • ImageMagick

  • Inotify

  • Lua

  • LuaSandbox

  • LZF

  • Mailparse

  • Mcrypt

  • Memcache

  • Memcached

  • mqseries

  • MySQL (最初の API)

  • Mysql_xdevapi

  • OAuth

  • OpenAL

  • parallel

  • Parle

  • CUBRID (PDO)

  • IBM (PDO)

  • Informix (PDO)

  • MS SQL Server (PDO)

  • PS

  • pthreads

  • Quickhash

  • Radius

  • Rar

  • Recode

  • Rnp

  • RpmInfo

  • RRD

  • runkit7

  • ScoutAPM

  • Seaslog

  • Simdjson

  • Solr

  • SQLSRV

  • ssdeep

  • SSH2

  • Statistics

  • Stomp

  • SVM

  • SVN

  • Swoole

  • Sync

  • Taint

  • TCP

  • Trader

  • UI

  • uopz

  • V8js

  • var_representation

  • Varnish

  • WDDX

  • win32service

  • WinCache

  • wkhtmltox

  • xattr

  • xdiff

  • Xhprof

  • XLSWriter

  • XMLDiff

  • XML-RPC

  • Yac

  • Yaconf

  • Yaf

  • Yaml

  • Yar

  • YAZ

  • 0MQ messaging

  • ZooKeeper


状態

このパートでは、実用向けではない拡張を挙げます。- これらは "古すぎる"（廃止予定 / deprecated）あるいは "新しすぎる"（実験的 / experimental）のどちらかです。

廃止予定の拡張

これらの拡張は非推奨です。通常は同じ機能を持つ別の拡張が存在します。

  • MySQL (最初の API)

  • WDDX

  • XML-RPC

実験的な拡張

これらの拡張の振る舞いは、PHP の将来のリリースで （その関数名や文書化されているあらゆる内容を含めて） 予告なく変更される可能性があります。自己責任のもとで利用してください。

  • ImageMagick


関数エイリアスのリスト

数はかなり少ないですが、PHPには複数の名前でコールされる関数があります。 いくつかの関数は単に二つの名前があり、実際の機能を持ちません。 （例えばis_int()とis_integer() は完全に同じです） いくつかの場合、これら複数の名前のどちらかが好ましいとはされていません。 例えば、is_int() と is_integer() は等しく好ましいとされています。 しかし、APIの整理や他の理由により名前が変更された関数があり、古い名前が 下位互換性の維持のためだけに残されている場合があります。 エイリアスの使用は古かったり、名前が変更されていたりで移植性の 低いスクリプトとなるため推奨されません。このリストは、古いスクリプト から新しい構文に更新しようとする人の助けとなるために提供されるもので す。

エイリアス
エイリアス | 正規化された関数名 | 使用されている拡張モジュール
_ | gettext() | Gettext
chop | rtrim() | Base syntax
close | closedir() | Base syntax
com_get | com_propget() | COM
com_propset | com_propput() | COM
com_set | com_propput() | COM
die | exit() | Miscellaneous functions
diskfreespace | disk_free_space() | Filesystem
doubleval | floatval() | Base syntax
fputs | fwrite() | Base syntax
gzputs | gzwrite() | Zlib
i18n_convert | mb_convert_encoding() | Multi-bytes Strings
i18n_discover_encoding | mb_detect_encoding() | Multi-bytes Strings
i18n_http_input | mb_http_input() | Multi-bytes Strings
i18n_http_output | mb_http_output() | Multi-bytes Strings
i18n_internal_encoding | mb_internal_encoding() | Multi-bytes Strings
i18n_ja_jp_hantozen | mb_convert_kana() | Multi-bytes Strings
i18n_mime_header_decode | mb_decode_mimeheader() | Multi-bytes Strings
i18n_mime_header_encode | mb_encode_mimeheader() | Multi-bytes Strings
imap_create | imap_createmailbox() | IMAP
imap_fetchtext | imap_body() | IMAP
imap_getmailboxes | imap_list_full() | IMAP
imap_getsubscribed | imap_lsub_full() | IMAP
imap_header | imap_headerinfo() | IMAP
imap_listmailbox | imap_list() | IMAP
imap_listsubscribed | imap_lsub() | IMAP
imap_rename | imap_renamemailbox() | IMAP
imap_scan | imap_listscan() | IMAP
imap_scanmailbox | imap_listscan() | IMAP
ini_alter | ini_set() | Base syntax
is_double | is_float() | Base syntax
is_integer | is_int() | Base syntax
is_long | is_int() | Base syntax
is_real | is_float() | Base syntax
is_writeable | is_writable() | Base syntax
join | implode() | Base syntax
key_exists | array_key_exists() | Base syntax
ldap_close | ldap_unbind() | LDAP
mbstrcut | mb_strcut() | Multi-bytes Strings
mbstrlen | mb_strlen() | Multi-bytes Strings
mbstrpos | mb_strpos() | Multi-bytes Strings
mbstrrpos | mb_strrpos() | Multi-bytes Strings
mbsubstr | mb_substr() | Multi-bytes Strings
mysql | mysql_db_query() | MySQL
mysql_createdb | mysql_create_db() | MySQL
mysql_db_name | mysql_result() | MySQL
mysql_dbname | mysql_result() | MySQL
mysql_dropdb | mysql_drop_db() | MySQL
mysql_fieldflags | mysql_field_flags() | MySQL
mysql_fieldlen | mysql_field_len() | MySQL
mysql_fieldname | mysql_field_name() | MySQL
mysql_fieldtable | mysql_field_table() | MySQL
mysql_fieldtype | mysql_field_type() | MySQL
mysql_freeresult | mysql_free_result() | MySQL
mysql_listdbs | mysql_list_dbs() | MySQL
mysql_listfields | mysql_list_fields() | MySQL
mysql_listtables | mysql_list_tables() | MySQL
mysql_numfields | mysql_num_fields() | MySQL
mysql_numrows | mysql_num_rows() | MySQL
mysql_selectdb | mysql_select_db() | MySQL
mysql_tablename | mysql_result() | MySQL
ociassignelem | OCICollection::assignElem | OCI8
ocibindbyname | oci_bind_by_name() | OCI8
ocicancel | oci_cancel() | OCI8
ocicloselob | OCILob::close | OCI8
ocicollappend | OCICollection::append | OCI8
ocicollassign | OCICollection::assign | OCI8
ocicollmax | OCICollection::max | OCI8
ocicollsize | OCICollection::size | OCI8
ocicolltrim | OCICollection::trim | OCI8
ocicolumnisnull | oci_field_is_null() | OCI8
ocicolumnname | oci_field_name() | OCI8
ocicolumnprecision | oci_field_precision() | OCI8
ocicolumnscale | oci_field_scale() | OCI8
ocicolumnsize | oci_field_size() | OCI8
ocicolumntype | oci_field_type() | OCI8
ocicolumntyperaw | oci_field_type_raw() | OCI8
ocicommit | oci_commit() | OCI8
ocidefinebyname | oci_define_by_name() | OCI8
ocierror | oci_error() | OCI8
ociexecute | oci_execute() | OCI8
ocifetch | oci_fetch() | OCI8
ocifetchinto | oci_fetch_array(), oci_fetch_row(), oci_fetch_assoc(), oci_fetch_object() | OCI8
ocifetchstatement | oci_fetch_all() | OCI8
ocifreecollection | OCICollection::free | OCI8
ocifreecursor | oci_free_statement() | OCI8
ocifreedesc | oci_free_descriptor() | OCI8
ocifreestatement | oci_free_statement() | OCI8
ocigetelem | OCICollection::getElem | OCI8
ociinternaldebug | oci_internal_debug() | OCI8
ociloadlob | OCILob::load | OCI8
ocilogon | oci_connect() | OCI8
ocinewcollection | oci_new_collection() | OCI8
ocinewcursor | oci_new_cursor() | OCI8
ocinewdescriptor | oci_new_descriptor() | OCI8
ocinlogon | oci_new_connect() | OCI8
ocinumcols | oci_num_fields() | OCI8
ociparse | oci_parse() | OCI8
ocipasswordchange | oci_password_change() | OCI8
ociplogon | oci_pconnect() | OCI8
ociresult | oci_result() | OCI8
ocirollback | oci_rollback() | OCI8
ocisavelob | OCILob::save | OCI8
ocisavelobfile | OCILob::import | OCI8
ociserverversion | oci_server_version() | OCI8
ocisetprefetch | oci_set_prefetch() | OCI8
ocistatementtype | oci_statement_type() | OCI8
ociwritelobtofile | OCILob::export | OCI8
ociwritetemporarylob | OCILob::writeTemporary | OCI8
odbc_do | odbc_exec() | ODBC
odbc_field_precision | odbc_field_len() | ODBC
pg_clientencoding | pg_client_encoding() | PostgreSQL
pg_setclientencoding | pg_set_client_encoding() | PostgreSQL
pos | current() | Base syntax
recode | recode_string() | Recode
show_source | highlight_file() | Base syntax
sizeof | count() | Base syntax
snmpwalkoid | snmprealwalk() | SNMP
strchr | strstr() | Base syntax


予約語の一覧

目次

  • キーワードのリスト
  • 定義済のクラス
  • 定義済みの定数
  • その他の予約語の一覧

以下に PHP で定義済みの ID の一覧を示します。ここに示す ID はいずれも、 別途明記されていない限りはスクリプトの中で ID として使用することはできません。これらの一覧には キーワード、定義済みの変数、定数、クラス名が含まれています。これらの一覧は、 全てを網羅しているわけではありません。


キーワードのリスト

これらのキーワードは、PHP では特別な意味があります。これらのいくつかは 関数やメソッドのようなものを表し、いくつかは定数のようなものを表す、 といったようになっていますが、実際にはそうではありません。実際には、 これらは言語を構成するものです。 以下のキーワードはいずれも定数、クラス名、 関数名として使用することはできません。 しかし、クラスやインターフェイス、そしてトレイトの内部では、 プロパティ、定数、メソッドの名前として使うことができます。 但し、class だけは例外で、これを定数名として使うことはできません。

PHP のキーワード
__halt_compiler() | abstract | and | array() | as
break | callable | case | catch | class
clone | const | continue | declare | default
die() | do | echo | else | elseif
empty() | enddeclare | endfor | endforeach | endif
endswitch | endwhile | eval() | exit() | extends
final | finally | fn (PHP 7.4 以降) | for | foreach
function | global | goto | if | implements
include | include_once | instanceof | insteadof | interface
isset() | list() | match (PHP 8.0 以降) | namespace | new
or | print | private | protected | public
readonly (PHP 8.1.0 以降) * | require | require_once | return | static
switch | throw | trait | try | unset()
use | var | while | xor | yield
yield from |  |  |  |

* readonly は、関数名として使用できます。

コンパイル時の定数


定義済のクラス

ここでは、標準で定義されているクラスをとりあげます。 さまざまな拡張モジュールで定義されるその他のクラスについては、 個々の拡張モジュールのリファレンスで述べられています。

標準で定義されているクラス

以下のクラスは、PHP ビルドに含まれる標準関数セットで定義されています。

Directory
dir() 関数が作成します。
stdClass
オブジェクトへの型変換 や、いろいろな標準の関数によって作られる、汎用的な空のクラスです。
__PHP_Incomplete_Class
unserialize() 関数が作成する可能性があります。
Exception
ErrorException
php_user_filter
Closure
定義済みの final クラス Closure は、 無名クラス を表現するために使います。
Generator
定義済みの final クラス Generator は、 ジェネレータ を表現するために使います。
ArithmeticError
AssertionError
DivisionByZeroError
Error
Throwable
ParseError
TypeError

特別なクラス

次の識別子は特別な意味を持っているので、クラス名としては使えません。

self
現在のクラス。
static
実行時における現在のクラス。
parent
親クラス。


定義済みの定数

コアの定義済みの定数

これらの定数は PHP のコアで定義済みの定数です。 PHP, Zend engine, SAPI モジュールも含みます。

PHP_VERSION (string)
現在の PHP のバージョンを "major.minor.release[extra]" 形式の文字列で表したもの。
PHP_MAJOR_VERSION (int)
現在の PHP のメジャーバージョンを整数値で表したもの (たとえば、バージョンが "5.2.7-extra" の場合は int(5) となる)。
PHP_MINOR_VERSION (int)
現在の PHP のマイナーバージョンを整数値で表したもの (たとえば、バージョンが "5.2.7-extra" の場合は int(2) となる)。
PHP_RELEASE_VERSION (int)
現在の PHP のリリースバージョンを整数値で表したもの (たとえば、バージョンが "5.2.7-extra" の場合は int(7) となる)。
PHP_VERSION_ID (int)
現在の PHP のバージョンを整数値で表したもの。バージョンを比較する際に有用 (たとえば、バージョンが "5.2.7-extra" の場合は int(50207) となる)。
PHP_EXTRA_VERSION (string)
現在の PHP の追加バージョンを文字列で表したもの (たとえば、バージョンが "5.2.7-extra" の場合は '-extra' となる)。 ディストリビューションのベンダーが、パッケージのバージョンを示すために使うことが多い。
ZEND_THREAD_SAFE (bool)
PHP の現状のビルドが、スレッドセーフ版であるかどうかを示す。
ZEND_DEBUG_BUILD (bool)
PHP の現状のビルドが、デバッグビルド版であるかどうかを示す。
PHP_ZTS (int)
PHP の現状のビルドが、スレッドセーフ版であるかどうかを示す。
PHP_DEBUG (int)
PHP の現状のビルドが、デバッグビルド版であるかどうかを示す。
DEBUG_BACKTRACE_PROVIDE_OBJECT (int)
"object" のインデックスを収集します。
DEBUG_BACKTRACE_IGNORE_ARGS (int)
スタックトレース中の関数の情報に、引数の情報を含めません。
PHP_MAXPATHLEN (int)
この PHP がサポートする、ファイル名の長さ (パスを含む) の最大値。 PHP 5.3.0 以降で利用可能。
PHP_OS (string)
PHP がビルドされた OS。
PHP_OS_FAMILY (string)
PHP がビルドされたオペレーティングシステムファミリー。 以下のうちひとつです。 'Windows', 'BSD', 'Darwin', 'Solaris', 'Linux' or 'Unknown'. PHP 7.2.0 以降で利用可能。
PHP_SAPI (string)
この PHP のサーバー API。 php_sapi_name() も参照ください。
PHP_EOL (string)
このプラットフォームの行末文字。
PHP_INT_MAX (int)
この PHP がサポートする整数型の最大値。32bit のシステムでは 通常は int(2147483647)。 64bit のシステムでは、int(9223372036854775807)。
PHP_INT_MIN (int)
この PHP がサポートする整数型の最小値。通常は、32ビットシステムなら int(-2147483648)、 64ビットシステムなら int(-9223372036854775808)。 通常は PHP_INT_MIN === ~PHP_INT_MAX となる。
PHP_INT_SIZE (int)
この PHP ビルドにおける整数型のサイズ (バイト数)。
PHP_FLOAT_DIG (int)
float への丸めやその逆操作の際に精度を維持できる数値の桁数。 PHP 7.2.0 以降で利用可能。
PHP_FLOAT_EPSILON (float)
x + 1.0 != 1.0 となる正の数 x のうちで、浮動小数点数値として表せる最小の数。 PHP 7.2.0 以降で利用可能。
PHP_FLOAT_MIN (float)
正 の浮動小数点数値として表せる最小の数。 浮動小数点数値として表せる 負の 最小値が必要なら、- PHP_FLOAT_MAX を使って下さい。 PHP 7.2.0 以降で利用可能。
PHP_FLOAT_MAX (float)
浮動小数点数値として表せる最大の数。 PHP 7.2.0 以降で利用可能。
DEFAULT_INCLUDE_PATH (string)
PEAR_INSTALL_DIR (string)
PEAR_EXTENSION_DIR (string)
PHP_EXTENSION_DIR (string)
動的にロード可能な拡張モジュールを探すデフォルトのディレクトリ。 (但し、extension_dir で上書きされた場合を除きます) デフォルトは PHP_PREFIX です。 (Windows では、 PHP_PREFIX . "\\ext" です。)
PHP_PREFIX (string)
configure 時に設定された --prefix の値。 Windows の場合、configure 時に設定された --with-prefix の値になります。
PHP_BINDIR (string)
configure 時に設定された --bindir の値。 Windows の場合、configure 時に設定された --with-prefix の値になります。
PHP_BINARY (string)
スクリプト実行時の PHP バイナリのパス。
PHP_MANDIR (string)
man ページのインストール先。
PHP_LIBDIR (string)
PHP_DATADIR (string)
PHP_SYSCONFDIR (string)
PHP_LOCALSTATEDIR (string)
PHP_CONFIG_FILE_PATH (string)
PHP_CONFIG_FILE_SCAN_DIR (string)
PHP_SHLIB_SUFFIX (string)
このプラットフォームの共有ライブラリの拡張子。"so" (多くの Unix 系 OS) や "dll" (Windows) など。
PHP_FD_SETSIZE (int)
select システムコール用のファイルディスクリプタの最大数。 PHP 7.1.0 以降で使用可能です。
E_ERROR (int)
エラーを報告する定数
E_WARNING (int)
エラーを報告する定数
E_PARSE (int)
エラーを報告する定数
E_NOTICE (int)
エラーを報告する定数
E_CORE_ERROR (int)
エラーを報告する定数
E_CORE_WARNING (int)
エラーを報告する定数
E_COMPILE_ERROR (int)
エラーを報告する定数
E_COMPILE_WARNING (int)
エラーを報告する定数
E_USER_ERROR (int)
エラーを報告する定数
E_USER_WARNING (int)
エラーを報告する定数
E_USER_NOTICE (int)
E_RECOVERABLE_ERROR (int)
エラーを報告する定数
E_DEPRECATED (int)
エラーを報告する定数
E_USER_DEPRECATED (int)
エラーを報告する定数
E_ALL (int)
エラーを報告する定数
E_STRICT (int)
エラーを報告する定数
__COMPILER_HALT_OFFSET__ (int)
true (bool)
Booleans も参照ください。
false (bool)
Booleans も参照ください。
null (null)
Null も参照ください。
PHP_WINDOWS_EVENT_CTRL_C (int)
Windows の CTRL+C イベント。 PHP 7.4.0 から利用可能です。(Windows のみ)
PHP_WINDOWS_EVENT_CTRL_BREAK (int)
Windows の CTRL+BREAK イベント。 PHP 7.4.0 から利用可能です。(Windows のみ)
PHP_CLI_PROCESS_TITLE (bool)
プロセスのタイトルを設定/取得できるかどうかを示します。 CLI SAPI でのみ利用可能です。
STDERR (resource)
stderr に対して、 既にオープンされているストリーム。 CLI SAPI でのみ利用可能です。
STDIN (resource)
stdin に対して、 既にオープンされているストリーム。 CLI SAPI でのみ利用可能です。
STDOUT (resource)
stdout に対して、 既にオープンされているストリーム。 CLI SAPI でのみ利用可能です。

マジック定数 も参照ください。

標準の定義済み定数

コアモジュール の定数は、すべて PHP にデフォルトで定義されています。


その他の予約語の一覧

これらの名前は、クラスやインターフェイスそしてトレイトの名前として使えません。 PHP 8.0 より前のバージョンでは、名前空間の中であっても使えませんでした。

予約語
int | float | bool | string
true | false | null | void
iterable (PHP 7.1 以降) | object (PHP 7.2 以降) | mixed (PHP 8.0 以降) | never (PHP 8.1 以降)

これらの名前は、弱い予約語として確保されています。 クラスやインターフェイスそしてトレイトの名前として使えますが、 使わないことを強く推奨します。将来のバージョンの PHP で使われる可能性があるためです。

弱い予約語
enum resource numeric


リソース型の一覧

以下にPHPのリソースを生成、使用、破棄するための関数の一覧を示します。 is_resource()によりある変数がリソースであるかど うかを調べることが可能です。また、 get_resource_type()は変数のリソース型を返します。

Resource Types
リソース型の名前 | 生成する関数 | 使用する関数 | 破棄する関数 | 説明
AddressInfo | socket_addrinfo_lookup() | socket_addrinfo_bind(), socket_addrinfo_connect(), socket_addrinfo_explain(), | None | AddressInfo (ソケット)
bzip2 | bzopen() | bzerrno(), bzerror(), bzerrstr(), bzflush(), bzread(), bzwrite() | bzclose() | Bzip2 ファイル
cubrid 接続 | cubrid_connect() cubrid_connect_with_url() | cubrid_col_get() cubrid_col_size() cubrid_commit() cubrid_drop() cubrid_execute() cubrid_get_autocommit() cubrid_get_charset() cubrid_get_class_name() cubrid_get_db_parameter() cubrid_get_server_info() cubrid_get() cubrid_insert_id() cubrid_is_instance() cubrid_lob_export() cubrid_lob_get() cubrid_lob_send() cubrid_lock_read() cubrid_lock_write() cubrid_prepare() cubrid_put() cubrid_rollback() cubrid_schema() cubrid_seq_drop() cubrid_seq_insert() cubrid_seq_put() cubrid_set_add() cubrid_set_autocommit() cubrid_set_db_parameter() cubrid_set_drop() cubrid_affected_rows() cubrid_client_encoding() cubrid_errno() cubrid_error() cubrid_list_dbs() cubrid_ping() cubrid_query() cubrid_real_escape_string() | cubrid_close() cubrid_disconnect() | CUBRID データベースへの接続
持続的な cubrid 接続 | cubrid_pconnect() cubrid_pconnect_with_url() | cubrid_col_get() cubrid_col_size() cubrid_commit() cubrid_drop() cubrid_execute() cubrid_get_autocommit() cubrid_get_charset() cubrid_get_class_name() cubrid_get_db_parameter() cubrid_get_server_info() cubrid_get() cubrid_insert_id() cubrid_is_instance() cubrid_lob_export() cubrid_lob_get() cubrid_lob_send() cubrid_lock_read() cubrid_lock_write() cubrid_prepare() cubrid_put() cubrid_rollback() cubrid_schema() cubrid_seq_drop() cubrid_seq_insert() cubrid_seq_put() cubrid_set_add() cubrid_set_autocommit() cubrid_set_db_parameter() cubrid_set_drop() cubrid_affected_rows() cubrid_client_encoding() cubrid_errno() cubrid_error() cubrid_list_dbs() cubrid_ping() cubrid_query() cubrid_real_escape_string() cubrid_lob2_new() | CUBRID データベースへの持続的な接続
cubrid request | cubrid_prepare() cubrid_execute() cubrid_query() cubrid_unbuffered_query() | cubrid_bind() cubrid_column_names() cubrid_column_types() cubrid_current_oid() cubrid_execute() cubrid_free_result() cubrid_get_query_timeout() cubrid_move_cursor() cubrid_next_result() cubrid_num_cols() cubrid_num_rows() cubrid_set_query_timeout() cubrid_data_seek() cubrid_fetch_array() cubrid_fetch_assoc() cubrid_fetch_field() cubrid_fetch_lengths() cubrid_fetch_object() cubrid_fetch_row() cubrid_field_flags() cubrid_field_len() cubrid_field_name() cubrid_field_seek() cubrid_field_table() cubrid_field_type() cubrid_num_fields() cubrid_result() cubrid_lob2_bind() | cubrid_close_prepare() cubrid_close_request() | CUBRID request
cubrid lob | cubrid_lob_get() | cubrid_lob_export() cubrid_lob_send() cubrid_lob_size() | cubrid_lob_close() | None
cubrid lob2 | cubrid_lob2_new() cubrid_fetch() cubrid_fetch_row() cubrid_fetch_array() cubrid_fetch_assoc() cubrid_fetch_object() | cubrid_lob2_export() cubrid_lob2_import() cubrid_lob2_read() cubrid_lob2_write() cubrid_lob2_tell() cubrid_lob2_tell64() cubrid_lob2_seek() cubrid_lob2_seek64() cubrid_lob2_size() cubrid_lob2_size64() | cubrid_lob2_close() | None
curl | curl_copy_handle(), curl_init() | curl_copy_handle(), curl_errno(), curl_error(), curl_exec(), curl_getinfo(), curl_setopt() | curl_close() | cURL ハンドル
curl_multi | curl_multi_init() | curl_multi_errno(), curl_multi_exec(), curl_multi_info_read(), curl_multi_remove_handle(), curl_multi_select(), curl_multi_setopt() | curl_multi_close() | cURL マルチハンドル
curl_share | curl_share_init() | curl_share_errno(), curl_share_setopt() | curl_share_close() | cURL 共有ハンドル
dba | dba_open() | dba_delete(), dba_exists(), dba_fetch(), dba_firstkey(), dba_insert(), dba_nextkey(), dba_optimize(), dba_replace(), dba_sync() | dba_close() | DBAデータベースへのリンク
dba persistent | dba_popen() | dba_delete(), dba_exists(), dba_fetch(), dba_firstkey(), dba_insert(), dba_nextkey(), dba_optimize(), dba_replace(), dba_sync() | None | DBAデータベースへの持続的なリンク
dbase | dbase_open() | dbase_pack(), dbase_add_record(), dbase_replace_record(), dbase_delete_record(), dbase_get_record(), dbase_get_record_with_names(), dbase_numfields(), dbase_numrecords() | dbase_close() | Dbaseデータベースへのリンク
enchant_broker | enchant_broker_init() | enchant_broker_describe(), enchant_broker_dict_exists(), enchant_broker_get_dict_path(), enchant_broker_get_error(), enchant_broker_list_dicts(), enchant_broker_set_dict_path(), enchant_broker_set_ordering() | enchant_broker_free() | Enchant ブローカー (PHP 8.0.0 より前)
enchant_dict | enchant_broker_request_dict() enchant_broker_request_pwl_dict() | enchant_dict_add_to_personal(), enchant_dict_add_to_session(), enchant_dict_check(), enchant_dict_describe(), enchant_dict_get_error(), enchant_dict_is_in_session(), enchant_dict_store_replacement(), enchant_dict_suggest() | enchant_broker_free_dict() | Enchant 辞書 (PHP 8.0.0 より前)
fdf | fdf_open() | fdf_create(), fdf_save(), fdf_get_value(), fdf_set_value(), fdf_next_field_name(), fdf_set_ap(), fdf_set_status(), fdf_get_status(), fdf_set_file(), fdf_get_file(), fdf_set_flags(), fdf_set_opt(), fdf_set_submit_form_action(), fdf_set_javascript_action() | fdf_close() | FDF File
ftp | ftp_connect(), ftp_ssl_connect() | ftp_login(), ftp_pwd(), ftp_cdup(), ftp_chdir(), ftp_mkdir(), ftp_rmdir(), ftp_nlist(), ftp_rawlist(), ftp_systype(), ftp_pasv(), ftp_get(), ftp_fget(), ftp_put(), ftp_fput(), ftp_size(), ftp_mdtm(), ftp_rename(), ftp_delete(), ftp_site(), ftp_alloc(), ftp_chmod(), ftp_exec(), ftp_get_option(), ftp_nb_continue(), ftp_nb_fget(), ftp_nb_fput(), ftp_nb_get(), ftp_nb_put(), ftp_raw(), ftp_set_option() | ftp_close() | FTP 接続 (PHP 8.1.0 より前)
gd | imagecreate(), imagecreatefromgd(), imagecreatefromgd2(), imagecreatefromgd2part(), imagecreatefromgif(), imagecreatefromjpeg(), imagecreatefrompng(), imagecreatefromwbmp(), imagecreatefromstring(), imagecreatefromxbm(), imagecreatefromxpm(), imagecreatetruecolor(), imagerotate() | imagearc(), imagechar(), imagecharup(), imagecolorallocate(), imagecolorat(), imagecolorclosest(), imagecolorexact(), imagecolorresolve(), imagegammacorrect(), imagegammacorrect(), imagecolorset(), imagecolorsforindex(), imagecolorstotal(), imagecolortransparent(), imagecopy(), imagecopyresized(), imagedashedline(), imagefill(), imagefilledpolygon(), imagefilledrectangle(), imagefilltoborder(), imagegif(), imagepng(), imagejpeg(), imagewbmp(), imageinterlace(), imageline(), imagepolygon(), imagerectangle(), imagerotate(), imagesetpixel(), imagestring(), imagestringup(), imagesx(), imagesy(), imagettftext(), imagefilledarc(), imageellipse(), imagefilledellipse(), imagecolorclosestalpha(), imagecolorexactalpha(), imagecolorresolvealpha(), imagecopymerge(), imagecopymergegray(), imagecopyresampled(), imagetruecolortopalette(), imagesetbrush(), imagesettile(), imagesetthickness(), image2wbmp(), imagealphablending(), imageantialias(), imagecolorallocatealpha(), imagecolorclosesthwb(), imagecolordeallocate(), imagecolormatch(), imagefilter(), imagefttext(), imagegd(), imagegd2(), imageistruecolor(), imagelayereffect(), imagepalettecopy(), imagesavealpha(), imagesetstyle(), imagexbm() | imagedestroy() | GD Image (PHP 8.0.0 より前)
gd font | imageloadfont() | imagechar(), imagecharup(), imagefontheight() | None | GD用のフォント (PHP 8.1.0 より前)
imap | imap_open() | imap_append(), imap_body(), imap_check(), imap_createmailbox(), imap_delete(), imap_deletemailbox(), imap_expunge(), imap_fetchbody(), imap_fetchstructure(), imap_headerinfo(), imap_header(), imap_headers(), imap_listmailbox(), imap_getmailboxes(), imap_get_quota(), imap_status(), imap_listsubscribed(), imap_set_quota(), imap_set_quota(), imap_getsubscribed(), imap_mail_copy(), imap_mail_move(), imap_num_msg(), imap_num_recent(), imap_ping(), imap_renamemailbox(), imap_reopen(), imap_subscribe(), imap_undelete(), imap_unsubscribe(), imap_scanmailbox(), imap_mailboxmsginfo(), imap_fetchheader(), imap_uid(), imap_msgno(), imap_search(), imap_fetch_overview() | imap_close() | IMAP, POP3 server への接続リンク(PHP 8.1.0 より前)
interbase blob | ibase_blob_create(), ibase_blob_import(), ibase_blob_open() | ibase_blob_add(), ibase_blob_cancel(), ibase_blob_echo(), ibase_blob_get(), ibase_blob_info() | ibase_blob_close()
interbase link | ibase_connect() | ibase_query(), ibase_prepare(), ibase_trans() | ibase_close() | Interbase データベースへのリンク
interbase link persistent | ibase_pconnect() | ibase_query(), ibase_prepare(), ibase_trans() | None | Interbase データベースへの持続的なリンク
interbase query | ibase_prepare() | ibase_execute() | ibase_free_query() | Interbase query
interbase 結果 | ibase_query() | ibase_fetch_row(), ibase_fetch_object(), ibase_field_info(), ibase_num_fields() | ibase_free_result() | Interbase 結果
interbase transaction | ibase_trans() | ibase_commit() | ibase_rollback() | Interbase transaction
ldap link | ldap_connect(), ldap_search() | ldap_count_entries(), ldap_first_attribute(), ldap_first_entry(), ldap_get_attributes(), ldap_get_dn(), ldap_get_entries(), ldap_get_values(), ldap_get_values_len(), ldap_next_attribute(), ldap_next_entry() | ldap_close() | ldap connection (PHP 8.1.0 より前)
ldap result | ldap_read() | ldap_add(), ldap_compare(), ldap_bind(), ldap_count_entries(), ldap_delete(), ldap_errno(), ldap_error(), ldap_first_attribute(), ldap_first_entry(), ldap_get_attributes(), ldap_get_dn(), ldap_get_entries(), ldap_get_values(), ldap_get_values_len(), ldap_get_option(), ldap_list(), ldap_modify(), ldap_mod_add(), ldap_mod_replace(), ldap_next_attribute(), ldap_next_entry(), ldap_mod_del(), ldap_set_option(), ldap_unbind() | ldap_free_result() | ldap search result (PHP 8.1.0 より前)
ldap result entry (PHP 8.1.0 より前)
mailparse_mail_structure | mailparse_msg_create() mailparse_msg_parse_file() | mailparse_msg_extract_part_file() mailparse_msg_extract_part() mailparse_msg_extract_whole_part_file() mailparse_msg_get_part_data() mailparse_msg_get_part() mailparse_msg_get_structure() mailparse_msg_parse() | mailparse_msg_free()
mysql link | mysql_connect() | mysql_affected_rows(), mysql_create_db(), mysql_data_seek(), mysql_db_name(), mysql_db_query(), mysql_drop_db(), mysql_errno(), mysql_error(), mysql_insert_id(), mysql_list_dbs(), mysql_list_fields(), mysql_list_tables(), mysql_query(), mysql_result(), mysql_select_db(), mysql_tablename(), mysql_get_host_info(), mysql_get_proto_info(), mysql_get_server_info() | mysql_close() | MySQL データベースへのリンク
mysql link persistent | mysql_pconnect() | mysql_affected_rows(), mysql_create_db(), mysql_data_seek(), mysql_db_name(), mysql_db_query(), mysql_drop_db(), mysql_errno(), mysql_error(), mysql_insert_id(), mysql_list_dbs(), mysql_list_fields(), mysql_list_tables(), mysql_query(), mysql_result(), mysql_select_db(), mysql_tablename(), mysql_get_host_info(), mysql_get_proto_info(), mysql_get_server_info() | None | MySQL データベースへの持続的なリンク
mysql 結果 | mysql_db_query(), mysql_list_dbs(), mysql_list_fields(), mysql_list_processes(), mysql_list_tables(), mysql_query(), mysql_unbuffered_query() | mysql_data_seek(), mysql_db_name(), mysql_fetch_array(), mysql_fetch_assoc(), mysql_fetch_field(), mysql_fetch_lengths(), mysql_fetch_object(), mysql_fetch_row(), mysql_fetch_row(), mysql_field_flags(), mysql_field_name(), mysql_field_len(), mysql_field_seek(), mysql_field_table(), mysql_field_type(), mysql_num_fields(), mysql_num_rows(), mysql_result(), mysql_tablename() | mysql_free_result() | MySQL 結果
oci8 collection | oci_new_collection() | OCI-Collection::append(), OCI-Collection::assign(), OCI-Collection::assignElem(), OCI-Collection::getElem(), OCI-Collection::max(), OCI-Collection::size(), OCI-Collection::trim() | OCI-Collection::free() | Oracle Collection
oci8 接続 | oci_connect(), oci_pconnect(), oci_new_connect() | oci_commit(), oci_error(), oci_new_cursor(), oci_parse(), oci_password_change(), oci_rollback(), oci_server_version(), oci_set_action(), oci_set_client_identifier(), oci_set_client_info(), oci_set_module_name() | oci_close() | Oracle データベースへの接続
oci8 lob | oci_new_descriptor() | OCI-Lob::append(), OCI-Lob::close(), OCI-Lob::eof(), OCI-Lob::erase(), OCI-Lob::export(), OCI-Lob::flush(), OCI-Lob::getBuffering(), OCI-Lob::import(), OCI-Lob::load(), OCI-Lob::read(), OCI-Lob::rewind(), OCI-Lob::save(), OCI-Lob::saveFile(), OCI-Lob::seek(), OCI-Lob::setBuffering(), OCI-Lob::size(), OCI-Lob::tell(), OCI-Lob::truncate(), OCI-Lob::write(), OCI-Lob::writeTemporary(), OCI-Lob::writeToFile(), oci_lob_copy(), oci_lob_is_equal() | OCI-Lob::free() | Oracle large objects
oci8 statement | oci_parse(), oci_new_cursor() | oci_bind_array_by_name(), oci_bind_by_name(), oci_cancel(), oci_define_by_name(), oci_error() oci_execute(), oci_fetch_all(), oci_fetch_array(), oci_fetch_assoc(), oci_fetch_object(), oci_fetch_row(), oci_fetch(), oci_field_is_null(), oci_field_name(), oci_field_precision(), oci_field_scale(), oci_field_size(), oci_field_type_raw(), oci_field_type(), oci_num_fields(), oci_num_rows(), oci_result(), oci_set_prefetch(), oci_statement_type() | oci_free_statement() | Oracle カーソル
odbc link | odbc_connect() | odbc_autocommit(), odbc_commit(), odbc_error(), odbc_errormsg(), odbc_exec(), odbc_tables(), odbc_tableprivileges(), odbc_do(), odbc_prepare(), odbc_columns(), odbc_columnprivileges(), odbc_procedurecolumns(), odbc_specialcolumns(), odbc_rollback(), odbc_setoption(), odbc_gettypeinfo(), odbc_primarykeys(), odbc_foreignkeys(), odbc_procedures(), odbc_statistics() | odbc_close() | ODBC データベースへのリンク
odbc link persistent | odbc_pconnect() | odbc_autocommit(), odbc_commit(), odbc_error(), odbc_errormsg(), odbc_exec(), odbc_tables(), odbc_tableprivileges(), odbc_do(), odbc_prepare(), odbc_columns(), odbc_columnprivileges(), odbc_procedurecolumns(), odbc_specialcolumns(), odbc_rollback(), odbc_setoption(), odbc_gettypeinfo(), odbc_primarykeys(), odbc_foreignkeys(), odbc_procedures(), odbc_statistics() | None | ODBC データベースへの持続的なリンク
odbc 結果 | odbc_prepare() | odbc_binmode(), odbc_cursor(), odbc_execute(), odbc_fetch_into(), odbc_fetch_row(), odbc_field_name(), odbc_field_num(), odbc_field_type(), odbc_field_len(), odbc_field_precision(), odbc_field_scale(), odbc_longreadlen(), odbc_num_fields(), odbc_num_rows(), odbc_result(), odbc_result_all(), odbc_setoption() | odbc_free_result() | ODBC 結果
birdstep link(PHP 7.3.0より前)
birdstep 結果(PHP 7.3.0より前)
OpenSSL key | openssl_get_privatekey(), openssl_get_publickey() | openssl_sign(), openssl_seal(), openssl_open(), openssl_verify() | openssl_free_key() | OpenSSL key
OpenSSL X.509 | openssl_x509_read() | openssl_x509_parse(), openssl_x509_checkpurpose() | openssl_x509_free() | Public Key
pgsql large object | pg_lo_open() | pg_lo_open(), pg_lo_create(), pg_lo_read(), pg_lo_read_all(), pg_lo_seek(), pg_lo_tell(), pg_lo_unlink(), pg_lo_write() | pg_lo_close() | PostgreSQL ラージオブジェクト (PHP 8.1.0 より前)
pgsql link | pg_connect() | pg_affected_rows(), pg_query(), pg_send_query(), pg_get_result(), pg_connection_busy(), pg_connection_reset(), pg_connection_status(), pg_last_error(), pg_last_notice(), pg_lo_create(), pg_lo_export(), pg_lo_import(), pg_lo_open(), pg_lo_unlink(), pg_host(), pg_port(), pg_dbname(), pg_options(), pg_copy_from(), pg_copy_to(), pg_end_copy(), pg_put_line(), pg_tty(), pg_trace(), pg_untrace(), pg_set_client_encoding(), pg_client_encoding(), pg_meta_data(), pg_convert(), pg_insert(), pg_select(), pg_delete(), pg_update() | pg_close() | PostgreSQL データベースへのリンク (PHP 8.1.0 より前)
pgsql link persistent | pg_pconnect() | pg_affected_rows(), pg_query(), pg_send_query(), pg_get_result(), pg_connection_busy(), pg_connection_reset(), pg_connection_status(), pg_last_error(), pg_last_notice(), pg_lo_create(), pg_lo_export(), pg_lo_import(), pg_lo_open(), pg_lo_unlink(), pg_host(), pg_port(), pg_dbname(), pg_options(), pg_copy_from(), pg_copy_to(), pg_end_copy(), pg_put_line(), pg_tty(), pg_trace(), pg_untrace(), pg_set_client_encoding(), pg_client_encoding(), pg_meta_data(), pg_convert(), pg_insert(), pg_select(), pg_delete(), pg_update() | None | PostgreSQL データベースへの持続的なリンク
pgsql 結果 | pg_execute(), pg_query(), pg_query_params(), pg_get_result() | pg_fetch_array(), pg_fetch_object(), pg_fetch_result(), pg_fetch_row(), pg_field_is_null(), pg_field_name(), pg_field_num(), pg_field_prtlen(), pg_field_size(), pg_field_type(), pg_last_oid(), pg_num_fields(), pg_num_rows(), pg_result_error(), pg_result_status() | pg_free_result() | PostgreSQL 結果 (PHP 8.1.0 より前)
pgsql string
pspell | pspell_new(), pspell_new_config(), pspell_new_personal() | pspell_add_to_personal(), pspell_add_to_session(), pspell_check(), pspell_clear_session(), pspell_config_ignore(), pspell_config_mode(), pspell_config_personal(), pspell_config_repl(), pspell_config_runtogether(), pspell_config_save_repl(), pspell_save_wordlist(), pspell_store_replacement(), pspell_suggest() | None | pspell 辞書 (PHP 8.1.0 より前)
pspell config | pspell_config_create() | pspell_new_config() | None | pspell 設定 (PHP 8.1.0 より前)
shmop | shmop_open() | shmop_read(), shmop_write(), shmop_size(), shmop_delete() | shmop_close() | 共有メモリブロックハンドル (PHP 8.0.0 より前)
ソケット | socket_accept(), socket_addrinfo_bind(), socket_addrinfo_connect(), socket_create(), socket_create_listen(), socket_import_stream(), socket_wsaprotocol_info_import() | socket_accept(), socket_bind(), socket_clear_error(), socket_connect(), socket_get_option(), socket_getpeername(), socket_getsockname(), socket_last_error(), socket_listen(), socket_read(), socket_recv(), socket_recvfrom(), socket_recvmsg(), socket_select(), socket_send(), socket_sendmsg(), socket_sendto(), socket_set_block(), socket_set_nonblock(), socket_set_option(), socket_shutdown(), socket_write(), socket_wsaprotocol_info_export(), socket_wsaprotocol_info_release() | socket_close() | Socket (ソケット拡張モジュール)
stream | opendir() | readdir(), rewinddir() | closedir() | ディレクトリハンドル
stream | fopen(), tmpfile() | feof(), fflush(), fgetc(), fgetcsv(), fgets(), fgetss(), flock(), fpassthru(), fputs(), fwrite(), fread(), fseek(), ftell(), fstat(), ftruncate(), set_file_buffer(), rewind() | fclose() | ファイルハンドル
stream | popen(), fsockopen(), pfsockopen() | feof(), fflush(), fgetc(), fgetcsv(), fgets(), fgetss(), fpassthru(), fputs(), fwrite(), fread() | pclose() | Process handle
socket | fflush(), fgetc(), fgetcsv(), fgets(), fgetss(), fpassthru(), fputs(), fwrite(), fread() | fclose() | ソケットハンドル
SSH2 セッション | ssh2_connect() | ssh2_disconnect()
SSH2 リスナー | ssh2_forward_listen()
SSH2 SFTP | ssh2_sftp()
SSH2 公開鍵サブシステム | ssh2_publickey_init()
sysvmsg queue | msg_get_queue() | msg_queue_exists(), msg_receive(), msg_send(), msg_set_queue(), msg_stat_queue() | msg_remove_queue() | System V メッセージキュー(PHP 8.0.0 より前)
sysvsem | sem_get() | sem_acquire() | sem_release() | System V セマフォ(PHP 8.0.0 より前)
sysvshm | shm_attach() | shm_remove(), shm_put_var(), shm_get_var(), shm_remove_var() | shm_detach() | System V 共有メモリ(PHP 8.0.0 より前)
wddx | wddx_packet_start() | wddx_add_vars() | wddx_packet_end() | WDDX packet
xml | xml_parser_create(), xml_parser_create_ns() | xml_set_object(), xml_set_element_handler(), xml_set_character_data_handler(), xml_set_processing_instruction_handler(), xml_set_default_handler(), xml_set_unparsed_entity_decl_handler(), xml_set_notation_decl_handler(), xml_set_external_entity_ref_handler(), xml_parse(), xml_get_error_code(), xml_error_string(), xml_get_current_line_number(), xml_get_current_column_number(), xml_get_current_byte_index(), xml_parse_into_struct(), xml_parser_set_option(), xml_parser_get_option() | xml_parser_free() | XML パーサ(PHP 8.0.0 より前)
zlib | gzopen() | gzeof(), gzgetc(), gzgets(), gzgetss(), gzpassthru(), gzputs(), gzread(), gzrewind(), gzseek(), gztell(), gzwrite() | gzclose() | gz で圧縮したファイル
zlib.deflate | deflate_init() | deflate_add() | なし | インクリメンタル圧縮コンテキスト(PHP 8.0.0 より前)
zlib.inflate | inflate_init() | inflate_add() inflate_add(), inflate_get_read_len(), inflate_get_status() | なし | インクリメンタル伸長コンテキスト(PHP 8.0.0 より前)


利用できるフィルタのリスト

目次

  • 文字列フィルタ
  • 変換フィルタ
  • 圧縮フィルタ
  • 暗号化フィルタ

以下は、stream_filter_append() で利用できる 組み込みフィルタのリストです。PHP のバージョンによっては このリスト以外のフィルタがあったり、このリストにあるフィルタが存在 しなかったりするかもしれません。

stream_filter_append() と stream_filter_prepend() のちょっとした違いに ついて説明します。 すべての PHP ストリームはその内部に小さな読み込みバッファ を持っており、ファイルシステムもしくは他のリソースから読み込まれた データはこのバッファに格納されます。このことで、データをより効率的に 扱うことができるのです。リソースがストリームの内部バッファに 取り込まれたら、アプリケーション側で準備ができているかどうかに かかわらずすぐにフィルタ処理が行われます。フィルタが append されていた場合、読み込みバッファに はいってきたデータはすぐにフィルタ処理されます。つまり、バッファの 存在をまったく意識せずに扱えるということです。しかし、もしフィルタが prepend されていた場合、読み込みバッファにデータが 入ってきた段階ではフィルタ処理されません。 リソースから次のデータブロックが読み込まれるまで、フィルタ処理を 待機するのです。

あなたが使っている PHP にどのようなフィルタが登録されているかを 知るには、stream_get_filters() を利用します。


文字列フィルタ

これらのフィルタは、まさしくその名が示すとおりの働きをし、PHP 組み込み の文字列処理関数と同じように動作します。これらのフィルタについての より詳しい情報は、対応する関数のマニュアルを参照ください。

string.rot13

このフィルタは、すべてのストリームデータに対して str_rot13() 関数を適用するのと同じ動作をします。

例1 string.rot13

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.rot13');
fwrite($fp, "This is a test.\n");
/* 出力: Guvf vf n grfg. */
?>

string.toupper

このフィルタは、すべてのストリームデータに対して strtoupper() 関数を適用するのと同じ動作をします。

例2 string.toupper

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.toupper');
fwrite($fp, "This is a test.\n");
/* 出力: THIS IS A TEST. */
?>

string.tolower

このフィルタは、すべてのストリームデータに対して strtolower() 関数を適用するのと同じ動作をします。

例3 string.tolower

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.tolower');
fwrite($fp, "This is a test.\n");
/* 出力: this is a test. */
?>

string.strip_tags

このフィルタは、すべてのストリームデータに対して strip_tags() 関数を適用するのと同じ動作をします。 以下の２つのうちどちらかの形式でパラメータを渡すことができます。 ひとつは、strip_tags() 関数の第２パラメータと同じ 形式でタグを並べた文字列、もうひとつはタグ名の配列です。

警告

この機能は PHP 7.3.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

例4 string.strip_tags

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, "<b><i><u>");
fwrite($fp, "<b>bolded text</b> enlarged to a <h1>level 1 heading</h1>\n");
fclose($fp);
/* 出力: bolded text enlarged to a level 1 heading */

$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, array('b','i','u'));
fwrite($fp, "<b>bolded text</b> enlarged to a <h1>level 1 heading</h1>\n");
fclose($fp);
/* 出力: bolded text enlarged to a level 1 heading */
?>


変換フィルタ

string.* フィルタと同様、convert.* フィルタもその名前と同じような 動作をします。 これらのフィルタについてのより詳しい情報は、対応する関数のマニュアルを 参照ください。

convert.base64-encode と convert.base64-decode による変換

これらのフィルタは、すべてのストリームデータに対してそれぞれ base64_encode() または base64_decode() 関数を適用するのと同じ動作をします。 convert.base64-encode は、パラメータを連想配列形式で 受け取ることができます。line-length が与えられた 場合、base64 出力は line-length 文字単位に 分割されます。 line-break-chars が与えられた場合、 分割されたデータは、line-break-chars で指定された文字列で区切って出力されます。 これらのパラメータは、base64_encode() を chunk_split() とともに利用した場合と同じ動作をします。

例1 convert.base64-encode と convert.base64-decode

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.base64-encode');
fwrite($fp, "This is a test.\n");
fclose($fp);
/* 出力: VGhpcyBpcyBhIHRlc3QuCg== */

$param = array('line-length' => 8, 'line-break-chars' => "\r\n");
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.base64-encode', STREAM_FILTER_WRITE, $param);
fwrite($fp, "This is a test.\n");
fclose($fp);
/* 出力: VGhpcyBp
: cyBhIHRl
: c3QuCg== */

$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.base64-decode');
fwrite($fp, "VGhpcyBpcyBhIHRlc3QuCg==");
fclose($fp);
/* 出力: This is a test. */
?>

convert.quoted-printable-encode と convert.quoted-printable-decode

これらのフィルタのうち、デコードフィルタはすべてのストリームデータに 対して quoted_printable_decode() 関数を適用するのと 同じ動作をします。 convert.quoted-printable-encode に対応する関数は存在しません。 convert.quoted-printable-encode は、パラメータを 連想配列形式で受け取ることができます。convert.base64-encode でサポートされているパラメータに加え、convert.quoted-printable-encode は binary と force-encode-first という２つの論理型パラメータをサポートしています。 convert.base64-decode は line-break-chars パラメータのみをサポートしており、 これは符号化されたデータを分割する際に用いられます。

例2 convert.quoted-printable-encode と convert.quoted-printable-decode

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.quoted-printable-encode');
fwrite($fp, "This is a test.\n");
/* 出力: =This is a test.=0A */
?>

convert.iconv.*

convert.iconv.* フィルタは、 iconv サポートが有効になっている場合に利用できます。 このフィルタは、すべてのストリームデータに iconv() 関数を適用するのと 同じ動作をします。 これらのフィルタは引数をサポートしていませんが、 その代わりに、入力と出力のエンコーディングがフィルタ名の一部として与えられます。 つまり、以下のような形になります。 convert.iconv.<input-encoding>.<output-encoding> または convert.iconv.<input-encoding>/<output-encoding> (どちらの記法もセマンティクス的には同等です).

例3 convert.iconv.*

<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.iconv.utf-16le.utf-8');
fwrite($fp, "T\0h\0i\0s\0 \0i\0s\0 \0a\0 \0t\0e\0s\0t\0.\0\n\0");
fclose($fp);
/* 出力: This is a test. */
?>


圧縮フィルタ

圧縮ストリーム を用いれば ローカルファイルシステム上に gzip や bz2 と互換性のある圧縮ファイルを 作成することができます。しかし、これはネットワーク越しの圧縮機能を 持っておらず、また非圧縮ストリームを圧縮されたストリームに変換することも できません。その点、圧縮フィルタはどんなストリームリソースでもどんな場合 でも適用可能です。

注意: 圧縮フィルタは、gzip のようなコマンドライン ユーティリティで使われるヘッダを生成しません。 これらのフィルタは、（ヘッダ部を除いた）データストリームの本体のみを 圧縮・展開するものです。

zlib.deflate と zlib.inflate

zlib.deflate (圧縮) と zlib.inflate (展開) は、 » RFC 1951 で述べられている圧縮方法を 実装したものです。deflate フィルタには、次の 3 つの パラメータを連想配列形式で渡すことができます: level は、圧縮の度合いを 1から9 までで表した ものです。数字が大きいほど圧縮後のサイズが小さくなりますが、そのぶん 処理時間が長くかかります。次の2つの値は特別な意味を持ちます。 0 (一切圧縮しない)、そして -1 (zlib のデフォルト設定 -- 現在は 6)。 window は、圧縮用ループバックウィンドウのサイズを （2 を底とする）対数で指定します。大きな値 (15 -- つまり 32768 バイトまで 引き上げる) を指定するとメモリをふんだんに利用してより小さく圧縮されます。 一方、小さな値 (9 -- つまり 512 バイトまで絞り込む) を指定すると、圧縮の 効率は落ちますがメモリの消費量を抑えられます。値を指定しなかった際の window の初期値は、現在 15 です。 memory は、作業用の一時メモリをどの程度割り当てるかを 指定します。1 (最小限) から 9 (最大限) の間で指定できます。この値は 圧縮の速度のみに影響し、圧縮後のデータのサイズには影響しません。

注意: level は一番よく使われるパラメータなので、このパラメータについては （配列形式ではなく）直接整数値として設定することも可能にしています。

zlib サポートが有効な場合、 zlib.* 圧縮フィルタが利用可能になります。

例1 zlib.deflate と zlib.inflate

<?php
$params = array('level' => 6, 'window' => 15, 'memory' => 9);

$original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n";
echo "もとのテキストの長さは " . strlen($original_text) . " 文字です。\n";

$fp = fopen('test.deflated', 'w');
stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, $params);
fwrite($fp, $original_text);
fclose($fp);

echo "圧縮後のファイルの大きさは " . filesize('test.deflated') . " バイトです。\n";
echo "もとのテキストは:\n";
/* readfile と zlib.inflate を利用し、メモリ上で展開します */
readfile('php://filter/zlib.inflate/resource=test.deflated');

/* 生成される出力:

もとのテキストの長さは 70 文字です。
圧縮後のファイルの大きさは 56 バイトです。
もとのテキストは:
This is a test.
This is only a test.
This is not an important string.

*/
?>

例2 zlib.deflate のシンプルな例

<?php
$original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n";
echo "もとのテキストの長さは " . strlen($original_text) . " 文字です。\n";

$fp = fopen('test.deflated', 'w');
/* この "6" は、パラメータ "level" が 6 であるということ */
stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, 6);
fwrite($fp, $original_text);
fclose($fp);

echo "圧縮後のファイルの大きさは " . filesize('test.deflated') . " バイトです。\n";

/* 生成される出力:

もとのテキストの長さは 70 文字です。
圧縮後のファイルの大きさは 56 バイトです。

*/
?>

bzip2.compress と bzip2.decompress

bzip2.compress と bzip2.decompress は、上で示した zlib フィルタと同じような動作をします。 bzip2.compress フィルタには、次の 2 つの パラメータを連想配列形式で渡すことができます: blocks は 1 から 9 までの整数値を設定します。 これは一時領域として割り当てるメモリのサイズを 100kバイトブロックの 数で示したものです。 work も整数値で、0 から 250 までの値を設定します。 これは、通常の圧縮方法がうまくいかなかった際に、どのくらい再試行した後で 速度の遅い（ただしより確実な）方法に切りかえるかを示します。 このパラメータは圧縮の速度のみに影響します。圧縮後のデータのサイズや 圧縮時のメモリ使用量は変わりません。0 を指定した場合は、bzip ライブラリの 初期設定値が利用されます。 bzip2.decompress フィルタには 1 つのパラメータを 渡すことができます。このパラメータは普通に論理型の値として渡すことも できますし、連想配列形式で small という名前の 要素として渡すこともできます。 small を true に設定した場合、bzip ライブラリは メモリ使用量をできるだけ抑えるようになり、その分、処理速度は遅くなります。

bz2 サポートが有効な場合、 bzip2.* 圧縮フィルタが利用可能になります。

例3 bzip2.compress と bzip2.decompress

<?php
$param = array('blocks' => 9, 'work' => 0);

echo "もとのファイルの大きさは " . filesize('LICENSE') . " バイトです。\n";

$fp = fopen('LICENSE.compressed', 'w');
stream_filter_append($fp, 'bzip2.compress', STREAM_FILTER_WRITE, $param);
fwrite($fp, file_get_contents('LICENSE'));
fclose($fp);

echo "圧縮後のファイルの大きさは " . filesize('LICENSE.compressed') . " バイトです。\n";

/* 生成される出力:

もとのファイルの大きさは 3288 バイトです。
圧縮後のファイルの大きさは 1488 バイトです。

*/
?>


暗号化フィルタ

暗号化フィルタは、ファイル/ストリーム を暗号化する場合に特に有用です。

mcrypt.* と mdecrypt.*

警告

この機能は PHP 7.1.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

mcrypt.* と mdecrypt.* は、libmcrypt を用いた暗号化・復号化を行います。これらのフィルタは、 mcrypt 暗号化関数 で利用可能な アルゴリズムをサポートしており、mcrypt.ciphername という名前で利用できます。ciphername の部分は、 mcrypt_module_open() に渡すのと同じアルゴリズム名 です。また、以下の 5 つのパラメータが利用できます。

mcrypt フィルタのパラメータ
パラメータ名 | 必須？ | 初期値 | 値の例
mode | 任意 | cbc | cbc, cfb, ecb, nofb, ofb, stream
algorithms_dir | 任意 | ini_get('mcrypt.algorithms_dir') | アルゴリズムモジュールのある場所
modes_dir | 任意 | ini_get('mcrypt.modes_dir') | モードモジュールのある場所
iv | 必須 | N/A | 通常は 8, 16, あるいは 32 バイトのバイナリデータ。暗号の形式に依存する
key | 必須 | N/A | 通常は 8, 16, あるいは 32 バイトのバイナリデータ。暗号の形式に依存する

例1 Blowfish を用いた 暗号化/復号化

<?php
//$key は、ここより以前で生成されているものとする
$iv_size = mcrypt_get_iv_size(MCRYPT_BLOWFISH, MCRYPT_MODE_CBC);
$iv = mcrypt_create_iv($iv_size, MCRYPT_DEV_URANDOM);
$fp = fopen('encrypted-file.enc', 'wb');
fwrite($fp, $iv);
$opts = array('mode'=>'cbc','iv'=>$iv, 'key'=>$key);
stream_filter_append($fp, 'mcrypt.blowfish', STREAM_FILTER_WRITE, $opts);
fwrite($fp, 'message to encrypt');
fclose($fp);

// 復号化する...
$fp = fopen('encrypted-file.enc', 'rb');
$iv = fread($fp, $iv_size = mcrypt_get_iv_size(MCRYPT_BLOWFISH, MCRYPT_MODE_CBC));
$opts = array('mode'=>'cbc','iv'=>$iv, 'key'=>$key)
stream_filter_append($fp, 'mdecrypt.blowfish', STREAM_FILTER_READ, $opts);
$data = rtrim(stream_get_contents($fp));//trims off null padding
fclose($fp);
echo $data;
?>

例2 ファイルを AES-128 CBC と SHA256 HMAC で暗号化する

<?php
AES_CBC::encryptFile($password, "plaintext.txt", "encrypted.enc");
AES_CBC::decryptFile($password, "encrypted.enc", "decrypted.txt");

class AES_CBC
{
protected static $KEY_SIZES = array('AES-128'=>16,'AES-192'=>24,'AES-256'=>32);
protected static function key_size() { return self::$KEY_SIZES['AES-128']; } //default AES-128
public static function encryptFile($password, $input_stream, $aes_filename){
$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
$fin = fopen($input_stream, "rb");
$fc = fopen($aes_filename, "wb+");
if (!empty($fin) && !empty($fc)) {
fwrite($fc, str_repeat("_", 32) );//placeholder, SHA256 HMAC will go here later
fwrite($fc, $hmac_salt = mcrypt_create_iv($iv_size, MCRYPT_DEV_URANDOM));
fwrite($fc, $esalt = mcrypt_create_iv($iv_size, MCRYPT_DEV_URANDOM));
fwrite($fc, $iv = mcrypt_create_iv($iv_size, MCRYPT_DEV_URANDOM));
$ekey = hash_pbkdf2("sha256", $password, $esalt, $it=1000, self::key_size(), $raw=true);
$opts = array('mode'=>'cbc', 'iv'=>$iv, 'key'=>$ekey);
stream_filter_append($fc, 'mcrypt.rijndael-128', STREAM_FILTER_WRITE, $opts);
$infilesize = 0;
while (!feof($fin)) {
$block = fread($fin, 8192);
$infilesize+=strlen($block);
fwrite($fc, $block);
}
$block_size = mcrypt_get_block_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
$padding = $block_size - ($infilesize % $block_size);//$padding is a number from 1-16
fwrite($fc, str_repeat(chr($padding), $padding) );//perform PKCS7 padding
fclose($fin);
fclose($fc);
$hmac_raw = self::calculate_hmac_after_32bytes($password, $hmac_salt, $aes_filename);
$fc = fopen($aes_filename, "rb+");
fwrite($fc, $hmac_raw);//overwrite placeholder
fclose($fc);
}
}
public static function decryptFile($password, $aes_filename, $out_stream) {
$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
$hmac_raw = file_get_contents($aes_filename, false, NULL, 0, 32);
$hmac_salt = file_get_contents($aes_filename, false, NULL, 32, $iv_size);
$hmac_calc = self::calculate_hmac_after_32bytes($password, $hmac_salt, $aes_filename);
$fc = fopen($aes_filename, "rb");
$fout = fopen($out_stream, 'wb');
if (!empty($fout) && !empty($fc) && self::hash_equals($hmac_raw,$hmac_calc)) {
fread($fc, 32+$iv_size);//skip sha256 hmac and salt
$esalt = fread($fc, $iv_size);
$iv = fread($fc, $iv_size);
$ekey = hash_pbkdf2("sha256", $password, $esalt, $it=1000, self::key_size(), $raw=true);
$opts = array('mode'=>'cbc', 'iv'=>$iv, 'key'=>$ekey);
stream_filter_append($fc, 'mdecrypt.rijndael-128', STREAM_FILTER_READ, $opts);
while (!feof($fc)) {
$block = fread($fc, 8192);
if (feof($fc)) {
$padding = ord($block[strlen($block) - 1]);//assume PKCS7 padding
$block = substr($block, 0, 0-$padding);
}
fwrite($fout, $block);
}
fclose($fout);
fclose($fc);
}
}
private static function hash_equals($str1, $str2) {
if(strlen($str1) == strlen($str2)) {
$res = $str1 ^ $str2;
for($ret=0,$i = strlen($res) - 1; $i >= 0; $i--) $ret |= ord($res[$i]);
return !$ret;
}
return false;
}
private static function calculate_hmac_after_32bytes($password, $hsalt, $filename) {
static $init=0;
$init or $init = stream_filter_register("user-filter.skipfirst32bytes", "FileSkip32Bytes");
$stream = 'php://filter/read=user-filter.skipfirst32bytes/resource=' . $filename;
$hkey = hash_pbkdf2("sha256", $password, $hsalt, $iterations=1000, 24, $raw=true);
return hash_hmac_file('sha256', $stream, $hkey, $raw=true);
}
}
class FileSkip32Bytes extends php_user_filter
{
private $skipped=0;
function filter($in, $out, &$consumed, $closing) {
while ($bucket = stream_bucket_make_writeable($in)) {
$outlen = $bucket->datalen;
if ($this->skipped<32){
$outlen = min($bucket->datalen,32-$this->skipped);
$bucket->data = substr($bucket->data, $outlen);
$bucket->datalen = $bucket->datalen-$outlen;
$this->skipped+=$outlen;
}
$consumed += $outlen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
class AES_128_CBC extends AES_CBC {
protected static function key_size() { return self::$KEY_SIZES['AES-128']; }
}
class AES_192_CBC extends AES_CBC {
protected static function key_size() { return self::$KEY_SIZES['AES-192']; }
}
class AES_256_CBC extends AES_CBC {
protected static function key_size() { return self::$KEY_SIZES['AES-256']; }
}


サポートされるソケットトランスポートのリスト

目次

  • Internet ドメイン: TCP、UDP、SSL、および TLS
  • Unix ドメイン: Unix および UDG

以下は、PHP がビルトインで持っている fsockopen() や stream_socket_client() のような ストリームに基づくソケットトランスポートとともに使用できる URL 形式のソケットトランスポートのリストです。 これらの転送は ソケット拡張モジュールの ソケット関数には 適用されません。

自分が使用している PHP のバージョンのトランスポートのリストを得るには stream_get_transports() を使用してください。


Internet ドメイン: TCP、UDP、SSL、および TLS

ssl://, tls://, sslv2:// & sslv3://.

注意: トランスポートが指定されなければ、tcp:// と仮定されます。

  • 127.0.0.1
  • fe80::1
  • www.example.com
  • tcp://127.0.0.1
  • tcp://fe80::1
  • tcp://www.example.com
  • udp://www.example.com
  • ssl://www.example.com
  • sslv2://www.example.com
  • sslv3://www.example.com
  • tls://www.example.com

Internet ドメインソケットは、対象のアドレスに加えてポート番号を 受け付けます。fsockopen() の場合、これは 2 番目の パラメータとして指定するので、トランスポートの URL には影響を与えません。 しかし、stream_socket_client() および関連する関数では 伝統的な URL を使用します。この場合、ポート番号はトランスポート URL の 後にコロンで区切ってつなげます。

  • tcp://127.0.0.1:80
  • tcp://[fe80::1]:80
  • tcp://www.example.com:80

注意: IPv6 数値アドレスとポート番号
IPv4 やホスト名形式の例では、ポート番号はアドレスやホスト名の直後に コロンでつながっていますが、上の 2 番目の例では IPv6 アドレスが 角括弧でかこまれて [fe80::1] となっています。 これは、IPv6 アドレスに使用されるコロンとポート番号を表す際のコロンを 区別するためです。

ssl:// および tls:// のトランスポート （PHP が openssl サポートを含めてコンパイルされている場合のみ有効）は、 tcp:// トランスポートに SSL 暗号化を含めた拡張です。

ssl:// は SSL V2 での接続を試みます。 あるいはリモートホストの設定によっては SSL V3 での接続を試みます。 sslv2:// および sslv3:// は、SSL V2 と SSL V3 のどちらのプロトコルを 使用するかを明示的に指定します。


Unix ドメイン: Unix および UDG

unix:// および udg://

  • unix:///tmp/mysock
  • udg:///tmp/mysock

unix:// は、Unix ドメインを使用したソケットストリーム 接続へのアクセスを提供します。udg:// は、UDP を使用した別方式での Unix ドメインソケットのトランスポートを提供します。

Unix ドメインソケットは、Internet ドメインソケットと異なり ポート番号を受け付けません。fsockopen() の場合、 portno パラメータは 0 に設定します。

注意: Unix ドメインソケットは、Windows ではサポートされていません。


PHP 型の比較表

下記の表はPHPの型と 比較演算子 の振る舞いについて、緩やかな場合と厳密な場合の両方について 例を示しています。この付録はマニュアルの 型の相互変換 にも関連しています。種々のユーザーコメントと » BlueShoesの働きの おかげです。

この表を活用する前に、型とその意味について理解しておく必要があります。 例えば、"42"は文字列ですが 42は整数です。 falseはboolですが"false"は 文字列です。

注意:

HTMLフォームは整数、浮動小数点数、booleanを渡してはくれず、 文字列を渡します。文字が数値であるかどうか確認するには、 is_numeric()を使うとよいでしょう。

注意:

$xが定義されていない状態で単に
if ($x)とするとE_NOTICE
レベルのエラーが発生します。代わりに、empty()や
isset()を使うか、あるいは変数を初期化するように
してください。

注意:

数値演算の結果が、定数 NAN で表される値になることがあります。 この値を他の値と比較すると、緩やかな比較および厳密な比較のいずれでも結果は false になります。 自分自身と比較した場合も含みますが、true と比較した場合は除きます。 (つまり NAN != NAN であり NAN !== NAN であるということです)。 結果が NAN になる演算の例には sqrt(-1) や asin(2) そして acosh(0) があります。

PHP 関数による $x の比較
式 | gettype() | empty() | is_null() | isset() | bool : if($x)
$x = ""; | string | true | false | true | false
$x = null; | NULL | true | true | false | false
var $x; | NULL | true | true | false | false
$x が未定義 | NULL | true | true | false | false
$x = []; | array | true | false | true | false
$x = ['a', 'b']; | array | false | false | true | true
$x = false; | bool | true | false | true | false
$x = true; | bool | false | false | true | true
$x = 1; | int | false | false | true | true
$x = 42; | int | false | false | true | true
$x = 0; | int | true | false | true | false
$x = -1; | int | false | false | true | true
$x = "1"; | string | false | false | true | true
$x = "0"; | string | true | false | true | false
$x = "-1"; | string | false | false | true | true
$x = "php"; | string | false | false | true | true
$x = "true"; | string | false | false | true | true
$x = "false"; | string | false | false | true | true

== による緩やかな比較
 | true | false | 1 | 0 | -1 | "1" | "0" | "-1" | null | [] | "php" | ""
true | true | false | true | false | true | true | false | true | false | false | true | false
false | false | true | false | true | false | false | true | false | true | true | false | true
1 | true | false | true | false | false | true | false | false | false | false | false | false
0 | false | true | false | true | false | false | true | false | true | false | false* | false*
-1 | true | false | false | false | true | false | false | true | false | false | false | false
"1" | true | false | true | false | false | true | false | false | false | false | false | false
"0" | false | true | false | true | false | false | true | false | false | false | false | false
"-1" | true | false | false | false | true | false | false | true | false | false | false | false
null | false | true | false | true | false | false | false | false | true | true | false | true
[] | false | true | false | false | false | false | false | false | true | true | false | false
"php" | true | false | false | false* | false | false | false | false | false | false | true | false
"" | false | true | false | false* | false | false | false | false | true | false | false | true
* PHP 8.0.0 より前のバージョンでは、true でした。

=== による厳密な比較
 | true | false | 1 | 0 | -1 | "1" | "0" | "-1" | null | [] | "php" | ""
true | true | false | false | false | false | false | false | false | false | false | false | false
false | false | true | false | false | false | false | false | false | false | false | false | false
1 | false | false | true | false | false | false | false | false | false | false | false | false
0 | false | false | false | true | false | false | false | false | false | false | false | false
-1 | false | false | false | false | true | false | false | false | false | false | false | false
"1" | false | false | false | false | false | true | false | false | false | false | false | false
"0" | false | false | false | false | false | false | true | false | false | false | false | false
"-1" | false | false | false | false | false | false | false | true | false | false | false | false
null | false | false | false | false | false | false | false | false | true | false | false | false
[] | false | false | false | false | false | false | false | false | false | true | false | false
"php" | false | false | false | false | false | false | false | false | false | false | true | false
"" | false | false | false | false | false | false | false | false | false | false | false | true


パーサトークンの一覧

PHP 言語の種々の部分は、内部的に トークン で表現されています。 不正なトークンのシーケンスが含まれるコードスニペットの場合、 Parse error: syntax error, unexpected token "==", expecting "(" in script.php on line 10." のようなエラーが発生します。 この場合、トークン == が内部的に T_IS_EQUAL として表現されています。

以下の表に、全てのトークンの一覧を示します。 これらは、全て PHP の定数としても利用できます。

注意: 定数 T_* の使いかた

T_* (T_ で始まる) 定数は、 PHP のベースとなるパーサ基盤に基づいて自動生成されます。 つまり、トークンの具体的な値は、PHP のバージョンが違えば変わる可能性があるということです。 つまり、バージョン間で互換性を保つためには、 コードの中では決して T_* の実際の値を使ってはいけないということです。

異なる PHP のバージョン間で互換性を保った形で T_* 定数を使うには、 PHP の複数のバージョン間で T_* の値が動作するように、 (10000 のような大きな数を使うなどの) 適切な戦略を用いて、未定義の定数をユーザが定義するようにします。

<?php
// PHP 7.4.0 より前のバージョンでは、定数 T_FN は定義されていません
defined('T_FN') || define('T_FN', 10001);

トークン
トークン | 構文 | 参照先
T_ABSTRACT | abstract | クラスの抽象化
T_AMPERSAND_FOLLOWED_BY_VAR_OR_VARARG | & | 型宣言 (PHP 8.1.0 以降で利用可能)
T_AMPERSAND_NOT_FOLLOWED_BY_VAR_OR_VARARG | & | 型宣言 (PHP 8.1.0 以降で利用可能)
T_AND_EQUAL | &= | 代入演算子
T_ARRAY | array() | array(), array 構文
T_ARRAY_CAST | (array) | 型キャスト
T_AS | as | foreach
T_ATTRIBUTE | #[ | アトリビュート (PHP 8.0.0 以降で利用可能)
T_BAD_CHARACTER |  | ASCII 32以下の全ての文字。\t (0x09), \n (0x0a) , \r (0x0d) は除く (PHP 7.4.0 以降で利用可能)
T_BOOLEAN_AND | && | 論理演算子
T_BOOLEAN_OR | || | 論理演算子
T_BOOL_CAST | (bool) or (boolean) | 型キャスト
T_BREAK | break | break
T_CALLABLE | callable | callable
T_CASE | case | switch
T_CATCH | catch | 例外(exceptions)
T_CLASS | class | クラスとオブジェクト
T_CLASS_C | __CLASS__ | マジック定数
T_CLONE | clone | クラスとオブジェクト
T_CLOSE_TAG | ?> or %> | HTML からの脱出
T_COALESCE | ?? | 比較演算子
T_COALESCE_EQUAL | ??= | NULL合体代入演算子 (PHP 7.4.0 以降で利用可能)
T_COMMENT | // or #, and /* */ | コメント
T_CONCAT_EQUAL | .= | 代入演算子
T_CONST | const | クラス定数
T_CONSTANT_ENCAPSED_STRING | "foo" or 'bar' | 文字列構文
T_CONTINUE | continue | continue
T_CURLY_OPEN | {$ | 複雑な (波括弧) 構文
T_DEC | -- | 可算/減算演算子
T_DECLARE | declare | declare
T_DEFAULT | default | switch
T_DIR | __DIR__ | マジック定数
T_DIV_EQUAL | /= | 代入演算子
T_DNUMBER | 0.12, etc. | 浮動小数点数
T_DO | do | do..while
T_DOC_COMMENT | /** */ | PHPDoc 形式のコメント
T_DOLLAR_OPEN_CURLY_BRACES | ${ | 複雑な (波括弧) 構文
T_DOUBLE_ARROW | => | array 構文
T_DOUBLE_CAST | (real), (double) or (float) | 型キャスト
T_DOUBLE_COLON | :: | T_PAAMAYIM_NEKUDOTAYIM を参照ください
T_ECHO | echo | echo
T_ELLIPSIS | ... | 関数の引数
T_ELSE | else | else
T_ELSEIF | elseif | elseif
T_EMPTY | empty | empty()
T_ENCAPSED_AND_WHITESPACE | " $a" | 文字列のパース
T_ENDDECLARE | enddeclare | declare, 別の構文
T_ENDFOR | endfor | for, 別の構文
T_ENDFOREACH | endforeach | foreach, 別の構文
T_ENDIF | endif | if, 別の構文
T_ENDSWITCH | endswitch | switch, 別の構文
T_ENDWHILE | endwhile | while, 別の構文
T_ENUM | enum | Enumerations (PHP 8.1.0 以降で利用可能)
T_END_HEREDOC |  | ヒアドキュメント構文
T_EVAL | eval() | eval()
T_EXIT | exit or die | exit(), die()
T_EXTENDS | extends | extends, クラスとオブジェクト
T_FILE | __FILE__ | マジック定数
T_FINAL | final | finalキーワード
T_FINALLY | finally | 例外(exceptions)
T_FN | fn | アロー関数 (PHP 7.4.0 以降で利用可能)
T_FOR | for | for
T_FOREACH | foreach | foreach
T_FUNCTION | function | 関数
T_FUNC_C | __FUNCTION__ | マジック定数
T_GLOBAL | global | 変数のスコープ
T_GOTO | goto | goto
T_HALT_COMPILER | __halt_compiler() | __halt_compiler
T_IF | if | if
T_IMPLEMENTS | implements | オブジェクト インターフェイス
T_INC | ++ | 可算/減算演算子
T_INCLUDE | include | include
T_INCLUDE_ONCE | include_once | include_once
T_INLINE_HTML |  | PHP の外部のテキスト
T_INSTANCEOF | instanceof | 型演算子
T_INSTEADOF | insteadof | トレイト
T_INTERFACE | interface | オブジェクト インターフェイス
T_INT_CAST | (int) or (integer) | 型キャスト
T_ISSET | isset() | isset()
T_IS_EQUAL | == | 比較演算子
T_IS_GREATER_OR_EQUAL | >= | 比較演算子
T_IS_IDENTICAL | === | 比較演算子
T_IS_NOT_EQUAL | != or <> | 比較演算子
T_IS_NOT_IDENTICAL | !== | 比較演算子
T_IS_SMALLER_OR_EQUAL | <= | 比較演算子
T_LINE | __LINE__ | マジック定数
T_LIST | list() | list()
T_LNUMBER | 123, 012, 0x1ac, etc. | 整数
T_LOGICAL_AND | and | 論理演算子
T_LOGICAL_OR | or | 論理演算子
T_LOGICAL_XOR | xor | 論理演算子
T_MATCH | match | match (PHP 8.0.0 以降で利用可能)
T_METHOD_C | __METHOD__ | マジック定数
T_MINUS_EQUAL | -= | 代入演算子
T_MOD_EQUAL | %= | 代入演算子
T_MUL_EQUAL | *= | 代入演算子
T_NAMESPACE | namespace | 名前空間
T_NAME_FULLY_QUALIFIED | \App\Namespace | 名前空間 (PHP 8.0.0 以降で利用可能)
T_NAME_QUALIFIED | App\Namespace | 名前空間 (PHP 8.0.0 以降で利用可能)
T_NAME_RELATIVE | namespace\Namespace | 名前空間 (PHP 8.0.0 以降で利用可能)
T_NEW | new | クラスとオブジェクト
T_NS_C | __NAMESPACE__ | 名前空間
T_NS_SEPARATOR | \ | 名前空間
T_NUM_STRING | "$a[0]" | 文字列内の配列の添字
T_OBJECT_CAST | (object) | 型キャスト
T_OBJECT_OPERATOR | -> | クラスとオブジェクト
T_NULLSAFE_OBJECT_OPERATOR | ?-> | クラスとオブジェクト
T_OPEN_TAG | <?php, <? or <% | HTML からのエスケープ
T_OPEN_TAG_WITH_ECHO | <?= or <%= | escaping from HTML
T_OR_EQUAL | |= | 代入演算子
T_PAAMAYIM_NEKUDOTAYIM | :: | ::. T_DOUBLE_COLONとしても定義されています。
T_PLUS_EQUAL | += | 代入演算子
T_POW | ** | 算術演算子
T_POW_EQUAL | **= | 代入演算子
T_PRINT | print | print
T_PRIVATE | private | クラスとオブジェクト
T_PROTECTED | protected | クラスとオブジェクト
T_PUBLIC | public | クラスとオブジェクト
T_READONLY | readonly | クラスとオブジェクト (PHP 8.1.0 以降で利用可能)
T_REQUIRE | require | require
T_REQUIRE_ONCE | require_once | require_once
T_RETURN | return | 値を返す
T_SL | << | ビット演算子
T_SL_EQUAL | <<= | 代入演算子
T_SPACESHIP | <=> | 比較演算子
T_SR | >> | ビット演算子
T_SR_EQUAL | >>= | 代入演算子
T_START_HEREDOC | <<< | ヒアドキュメント構文
T_STATIC | static | 変数のスコープ
T_STRING | parent, self, etc. | 識別子。たとえば parent や self といったオブジェクト指向のキーワード、そして関数名やクラス名などにマッチします。 T_CONSTANT_ENCAPSED_STRING も参照ください。
T_STRING_CAST | (string) | 型キャスト
T_STRING_VARNAME | "${a | 複雑な (波括弧) 構文
T_SWITCH | switch | switch
T_THROW | throw | 例外(exceptions)
T_TRAIT | trait | トレイト
T_TRAIT_C | __TRAIT__ | __TRAIT__
T_TRY | try | 例外(exceptions)
T_UNSET | unset() | unset()
T_UNSET_CAST | (unset) | 型キャスト
T_USE | use | 名前空間
T_VAR | var | クラスとオブジェクト
T_VARIABLE | $foo | 変数
T_WHILE | while | while, do..while
T_WHITESPACE | \t \r\n |
T_XOR_EQUAL | ^= | 代入演算子
T_YIELD | yield | ジェネレータ
T_YIELD_FROM | yield from | ジェネレータ

token_name() も参照ください。


ユーザーレベルでの命名の手引き

目次

  • グローバル名前空間
  • ルール
  • Tips

これは、あなたが書く PHP コード中の識別子によりよい名前をつけるための手引きです。 グローバル名前空間のシンボルを作成するコードでシンボルの名前を決める際には、 以下のガイドラインを考慮することが重要です。これにより、 PHP の将来のバージョンとの衝突を避けることができます。


グローバル名前空間

グローバル名前空間に属する言語構造には、このようなものがあります。

  • 関数

  • クラス

  • インターフェイス

  • 定数 (クラス定数以外)

  • 関数/メソッド の外部で定義された変数


ルール

以下のリストは、PHP プロジェクトで新たな内部識別子を作成する際に どのような基準で名前を決めているのかを おおまかにまとめたものです。完全な規約は、公式の » コーディング規約 を参照ください。

  • PHP はトップレベルの名前空間を所有していますが、 きちんとしたわかりやすい名前をつけるようにこころがけ、 衝突が起こらないようにしています。

  • 関数名では、単語の間にアンダースコアを使用します。クラスの場合は、 キャメルケース (camelCase) 形式や パスカルケース (PascalCase) 形式を使います。

  • PHP の拡張モジュールのグローバルシンボルには、 その拡張モジュールの名前を先頭につけます (過去には、この原則を守っていない例が大量にありました)。 たとえば次のようになります。

    • curl_close()

    • mysql_query()

    • PREG_SPLIT_DELIM_CAPTURE

    • new DOMDocument()

    • strpos() (過去に間違えた例)

    • new SplFileObject()

  • しかし、イテレータや例外については、単純に最後に "Iterator" および "Exception" を追加するようにします。例えば次のようになります。

    • ArrayIterator

    • LogicException

  • PHP では、__ で始まるシンボルを特殊なものとして予約済みです。 以下にあげるような文書化されている機能を使用する場合を除き、 __ で始まるシンボルを作成しないことを推奨します。

    • __get()

    • __autoload()


Tips

将来もそのまま使用できるようなコードを書くためには、 グローバル名前空間にあまり多くの変数や関数やクラスを置かないことをおすすめします。 そうしておけば、サードパーティのコードと名前が衝突したり PHP 自体に追加された機能と名前が衝突したりする可能性を減らせます。

関数やクラスの名前が衝突することを防ぐ手としてよくあるのが、 それ専用の namespace を用意することです。

<?php

namespace MyProject;

function my_function() {
return true;
}

\MyProject\my_function();

既存の名前空間と名前が重複してしまわないように気をつける必要はありますが、 いったん名前空間を用意してしまえば、そこに関数やクラスを追加するときには 名前が衝突する心配をせずに済むようになります。

サードパーティのコードとの名前の衝突を防ぐという意味で、 グローバル名前空間への変数の追加をできるだけ避けるというのはよい習慣だと考えられています。

注意: 変数のスコープ

PHP の 変数のスコープのルール では、関数やメソッドの内部で定義した変数はグローバルスコープにはなりません。 そのため、グローバルスコープで定義された変数との名前の衝突を気にする必要はありません。


マニュアルについて

目次

  • フォーマット
  • ユーザーノートについて
  • 関数の定義(プロトタイプ)を読むには
  • 本マニュアルに記載された PHP のバージョン
  • PHP に関する更なる情報を得るには
  • ドキュメントの改善を手助けするには
  • 各種フォーマットを生成する方法
  • 翻訳


フォーマット

PHP のマニュアルはいくつかのフォーマットで提供されています。 大まかに言うとフォーマットには2つの種類があります。オンラインで 読むことのできるフォーマットとダウンロード可能なパッケージです。

注意:

いくつかの出版社は印刷されたマニュアルを提供しています。私たち としてはそれらをお勧めすることは出来ません。何故ならそういった ものはすぐに古いものになってしまいがちだからです。

オンラインマニュアルは » PHP.net Web サイト で読むことができます。 オンライン版の PHP マニュアルには、現在二種類の CSS スタイルシートが提供されています。それぞれ、 ウェブでの閲覧に適したものと、プリンタでの印刷に適したものです。

オンラインマニュアルがオフライン版より優れている点は、 ユーザーノートと 見たいマニュアルのページを速やかに入手できる » URL ショートカットが 統合されていることでしょう。不利な点は、当然ですがマニュアルを見るためには 常にオンラインでいる必要があることです。

オフラインフォーマットにはいくつかのタイプがあるので、使用している OS や読み方にあわせて最適なものを選択してください。これらの異なった フォーマットのドキュメントをどのように生成しているかという 情報については、この付録の 各種フォーマットを生成する方法の項を読んでください。

最もプラットフォーム依存性が少いマニュアルのフォーマットは HTML 版です。このマニュアルは、一つのファイルにまとめられたものと、 章ごとに分割されたファイルのパッケージ (その結果、総数は数千にもなっています)の両方があります。 これらの HTML 版は圧縮された状態で提供されているため、 アーカイブの中のファイルを取得するには解凍用ユーティリティ が必要です。

Windows 上では、Windows HTML Help で Windows HTML Help 版のマニュアルを使用すると非常に便利です。このバージョンは全文検索、完全な目次、 そしてブックマーク機能を提供します。多くの有名な Windows 上での PHP 開発環境ではこのバージョンのマニュアルを統合する機能を備えていて、 間単にアクセスすることが出来ます。Linux デスクトップ用の CHM ビューワも 利用可能です。 » xCHM または » GnoCHM を参照ください。

» 拡張 CHM 版も使用可能です。 その更新頻度はより少なくなっていますが、より多くの追加機能があります。 これは、ヘルプページを構築する際に使用される技術のために Microsoft Windows でのみ動作します。


ユーザーノートについて

ユーザーノートは PHP マニュアルを作成していく上で重要な役割を 持っています。マニュアルの読者が実例、警告そしてさらに詳しい 説明をブラウザから提供できるようにすることで、そうした フィードバックをマニュアルの本文に取り込むことが出来るのです。 そして記事が本文に取り入れられるまでの間は、その内容をオンライン、 もしくはいくつかのオフラインフォーマットで参照できるでしょう。

ユーザーノートが PHP のサイトに表示される際に、何らかの 査閲がされているわけではない、ということに注意してください。 従って、そこに書かれた内容、実例の質については保証 されません(とはいえ、マニュアルの本文そのものの 質が保証されない、ということではありません)。

注意:

著作権の適用範囲として、ユーザーノートは PHP マニュアルの一部と見なされます。 それゆえ、このドキュメンテーションのライセンス(現状は Creative Commons Attribution License)が適用されます。 詳細は Manual's Copyright をご覧ください。


関数の定義(プロトタイプ)を読むには

各関数についてクイックリファレンスが記述されているので、 マニュアルを読み理解するノウハウは PHP の利用をより簡単にしてくれます。 例示やカットアンドペーストに頼るより、関数の定義（プロトタイプ）を 読む方法を覚えるべきです。やってみましょう:

注意: 前提条件: 型の基本的な理解

PHP は型についてルーズな言語ですが、重要な意味があるので、 型の基本を理解することは重要です。

関数の定義には戻り値が どんな型であるかが示されています。最初の例として、 strlen()の定義を考えてみましょう。

strlen ( string $string ) : int

(PHP 4, PHP 5, PHP 7)
 strlen -- 文字列の長さを得る

 説明
int strlen ( string $string )

指定した文字列の長さを返します

関数の定義の説明
Part | 説明
strlen | 関数の名前
(PHP 4, PHP 5, PHP 7) | strlen()は PHP 4 と PHP 5、そして PHP 7 のすべてのバージョンで使用できる
( string $string ) | strlen() 関数の最初の（この場合は唯一の）引数が stringという名前であり それは文字列である
int | 関数が戻す値の型。ここでは整数型 (文字列の長さが数字で数えられている)

上の関数定義は、一般的な書き方では以下のようにも書けます。

     function name    ( parameter type   parameter name ) : returned type

多くの関数は複数の引数を取ります。例えば in_array()。 このプロトタイプは次のようになります:

      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool

これは何を意味しているのでしょう？ in_array() は boolean の値を返します。 成功した場合は true(needle が haystack の中にある場合)、失敗した場合に false を返します (needle が haystack の中にない場合)。最初の引数は needle と名づけられており、それは多くの違った 型をとることができます。その場合"mixed"と 呼ばれます。 needle (我々が探しているもの)はスカラー値（文字列,整数, 又は float)でも、 配列でもかまいません。 haystack (対象を探す配列)は二番目の引数です。 三番目のオプションの引数は strict と名づけられています。全てのオプション引数はデフォルト値を持ちます。 デフォルト値が不明な場合、? と表示されます。 strict パラメータはデフォルトでは boolean の false であるとマニュアルに述べられています。機能の詳細については 各関数のマニュアルをご覧ください。

さらに、& (アンパサンド) 記号を関数のパラメータの前につけると、 そのパラメータをリファレンス渡しにすることができます。

       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false

この例では、三番目のオプションのパラメータ &$matches がリファレンス渡しとなります。

より複雑なバージョンとの関係を有する関数もあります。以下が html_entity_decode() の例です。

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

これは、この関数が PHP 4.3.0 以降のバージョンでのみ利用可能であることを意味します。


本マニュアルに記載された PHP のバージョン

このマニュアルに含まれている情報は、過去や現在のバージョンの PHP だけでなく将来のバージョンの PHP に関するものもあります。 バージョン間での変更内容は「注意」や「更新履歴」 あるいはマニュアルの本文の中で説明しています。 このドキュメントでは、PHP 7.0.0 以降のバージョンを扱っています。

最新の (まだリリースされていない) 開発版に関するドキュメントには "Git 版のみ" や "開発版" といった記述があります。 これらの変更は予定通りに進むのが普通ですが、まれに予定が変更されることもあります。

開発はすべて Git で進められており、 » 匿名での Git へのアクセス のページに書かれている方法でチェックアウトすることができます。

マニュアルでは、PHP のバージョンをメジャー、マイナー、ポイントの三つで表します。 たとえば PHP 7.3.1 を例にとると、7 がメジャーリリースで 3 がマイナーリリース、 そして 1 がポイントリリースとなります。 通常 PHP では、新機能の追加はメジャーリリースやマイナーリリースでしか行いません。 しかし、この決まりが常に守られるとは限りません。

また、PHP のマニュアルは現在形で書かれていることに注意しましょう。 たとえその機能がまだ搭載されていなくても、未来形にはなりません。 マニュアルは長く使い続けられるものです。 PHP のリリースのたびに時制の変更を繰り返すのは退屈な作業なので、そのようにしました。

PHP のマニュアルでは、多くの項目で「デフォルト値」を記載しています。 これらの値は、設定ファイル php.ini がないときの PHP の挙動にもとづいています。 そのため、同梱の設定ファイル php.ini-development や php.ini-production に書かれている内容とは異なる可能性があります。 これらの値は最新版の PHP にもとづくものですが、 過去の値についても更新履歴に記載しています。 これらの値や変更履歴についての詳細は PHP ディレクティブのリスト を参照ください。


PHP に関する更なる情報を得るには

このマニュアルは一般的なプログラミングの解説を提供しよう としているわけではありません。従って、もしあなたが全く初めて プログラミングを行う、もしくはほとんど初心者である、と言う場合は このマニュアルだけを使って、PHP のプログラミングを習得するのは 難しいでしょう。そうした場合には初心者向けの本を探したほうが よいかもしれません。

PHP に関する様々な側面について活発に議論しているメーリングリストも 多数あります。もし問題にぶつかったら、これらのメーリングリストの 利用を考えてください。メーリングリストを含むサポート情報は » PHP.net サポートページ にあります。


ドキュメントの改善を手助けするには

ドキュメントを改善していくには 複数のやり方があります。

もし(どの言語でかかれたものでも)マニュアルに間違いが見つかったら » https://github.com/php にある、各言語の issue tracker を使って問題を報告して下さい。 たとえば、日本語版のマニュアルについては、 » https://github.com/php/doc-ja/issues になります。 マニュアルのフォーマットを含め、 ドキュメントに関する問題はすべてここから送信してください。

注意:

issue tracker に助けを要求することでシステムを無駄に使用しないでください。 かわりに、たくさんの» サポートオプション の中のひとつを利用してください。

各ページに注釈をつけることで、原文に実例、警告等の更なる説明を 追加することが出来ます。とはいえ、この注釈システムを使って バグレポートを送信しないでください。ユーザーノートの詳細については、 ユーザーノートについての 項を読んでください。

» PHP マニュアルのリポジトリのミラー 経由で Pull Request を送信することもできます。

PHP マニュアルは多くの言語に翻訳されています。英語とその他の外国語が わかる方なら、翻訳チームを手伝うことで PHP マニュアルの改善に協力できます。 新しく翻訳を始めたい場合や、現在翻訳されているバージョンを手伝おうと 思ったら、» http://doc.php.net/tutorial/ を是非読んでください。

PHP ドキュメント作成プロジェクトの IRC チャネルには、マニュアルの 作者の多くが参加しています。irc.efnet.org の #php.doc で、PHP ドキュメントを改善する方法に ついて議論しましょう。


各種フォーマットを生成する方法

このマニュアルは、» DocBook XML DTD を用いて XML で記述されています。 また、» PhD (The [PH]P based [D]ocBook renderer) を用いて保守やフォーマットを行います。

XML をソースファイルのフォーマットとして 使用することで、一つのソースファイルを管理するだけで、 多くの出力形式を生成することができるようになっています。 オンライン版のマニュアルを作成する際には » PhD を使用しています。 Windows HTML Help 形式のマニュアルを作成するためには » Microsoft HTML Help Workshop を使用しています。またちょっとした変換処理やフォーマットの 処理にはもちろん PHP を使っています。

PHP マニュアルは多くの言語とフォーマットで作成されています。詳しい 情報は » https://www.php.net/docs.php を参照ください。 このドキュメントの XML ソースコードは、 » https://github.com/php/doc-ja からダウンロードしたり、閲覧したりできます。


翻訳

PHP マニュアルはさまざまな形式で読めるだけでなく、さまざまな言語で 読むことができます。マニュアルの文章はまず最初に英語で書かれ、 その後世界中のチームによってそれぞれの母国語に翻訳されます。 もし特定の関数や章がまだ翻訳されていない場合、マニュアル生成システム はその英語版を自動的に挿入します。

翻訳に携わる人は » https://github.com/php/doc-ja から アクセスできる XML ソースコードを母国語に 翻訳することから始めます。生成されたバージョン（HTML やプレーンテキストなど）を扱うことはありません。 XMLを人間が読める形式に変換する処理をしてくれるのが ビルドシステムです。

注意:

もしドキュメントをあなたの母国語に翻訳することを手伝いたいと思ったら、 phpdocメーリングリストに加入してドキュメント／翻訳チームと連絡を取ってください。 » phpdoc+subscribe@lists.php.net に空のメールを送るだけです。 メーリングリストのアドレスは phpdoc@lists.php.net です。 マニュアルの翻訳に関心があることをメッセージに書いてください。 誰かから返事をもらって新しい言語への翻訳をスタートする手助けをしてもらうか、 あるいは、その言語について既に活動している翻訳チームと連絡が取れます。

現在のところ、10 以上の言語において全て又は一部のマニュアルが利用できます。

これらはすべて、» https://www.php.net/docs.php からダウンロードできます。


Creative Commons Attribution 3.0

THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.

1. Definitions

  1. "Adaptation" means a work based upon the Work, or upon the Work and other pre-existing works, such as a translation, adaptation, derivative work, arrangement of music or other alterations of a literary or artistic work, or phonogram or performance and includes cinematographic adaptations or any other form in which the Work may be recast, transformed, or adapted including in any form recognizably derived from the original, except that a work that constitutes a Collection will not be considered an Adaptation for the purpose of this License. For the avoidance of doubt, where the Work is a musical work, performance or phonogram, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered an Adaptation for the purpose of this License.
  2. "Collection" means a collection of literary or artistic works, such as encyclopedias and anthologies, or performances, phonograms or broadcasts, or other works or subject matter other than works listed in Section 1(f) below, which, by reason of the selection and arrangement of their contents, constitute intellectual creations, in which the Work is included in its entirety in unmodified form along with one or more other contributions, each constituting separate and independent works in themselves, which together are assembled into a collective whole. A work that constitutes a Collection will not be considered an Adaptation (as defined above) for the purposes of this License.
  3. "Distribute" means to make available to the public the original and copies of the Work or Adaptation, as appropriate, through sale or other transfer of ownership.
  4. "Licensor" means the individual, individuals, entity or entities that offer(s) the Work under the terms of this License.
  5. "Work" means the literary and/or artistic work offered under the terms of this License including without limitation any production in the literary, scientific and artistic domain, whatever may be the mode or form of its expression including digital form, such as a book, pamphlet and other writing; a lecture, address, sermon or other work of the same nature; a dramatic or dramatico-musical work; a choreographic work or entertainment in dumb show; a musical composition with or without words; a cinematographic work to which are assimilated works expressed by a process analogous to cinematography; a work of drawing, painting, architecture, sculpture, engraving or lithography; a photographic work to which are assimilated works expressed by a process analogous to photography; a work of applied art; an illustration, map, plan, sketch or three-dimensional work relative to geography, topography, architecture or science; a performance; a broadcast; a phonogram; a compilation of data to the extent it is protected as a copyrightable work; or a work performed by a variety or circus performer to the extent it is not otherwise considered a literary or artistic work.
  6. "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.
  7. "Publicly Perform" means to perform public recitations of the Work and to communicate to the public those public recitations, by any means or process, including by wire or wireless means or public digital performances; to make available to the public Works in such a way that members of the public may access these Works from a place and at a place individually chosen by them; to perform the Work to the public by any means or process and the communication to the public of the performances of the Work, including by public digital performance; to broadcast and rebroadcast the Work by any means including signs, sounds or images.
  8. "Reproduce" means to make copies of the Work by any means including without limitation by sound or visual recordings and the right of fixation and reproducing fixations of the Work, including storage of a protected performance or phonogram in digital form or other electronic medium.

2. Fair Dealing Rights. Nothing in this License is intended to reduce, limit, or restrict any uses free from copyright or rights arising from limitations or exceptions that are provided for in connection with the copyright protection under copyright law or other applicable laws.

3. License Grant. Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:

  1. to Reproduce the Work, to incorporate the Work into one or more Collections, and to Reproduce the Work as incorporated in the Collections;
  2. to create and Reproduce Adaptations provided that any such Adaptation, including any translation in any medium, takes reasonable steps to clearly label, demarcate or otherwise identify that changes were made to the original Work. For example, a translation could be marked "The original work was translated from English to Spanish," or a modification could indicate "The original work has been modified.";
  3. to Distribute and Publicly Perform the Work including as incorporated in Collections; and,
  4. to Distribute and Publicly Perform Adaptations.

  5. For the avoidance of doubt:

    1. Non-waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme cannot be waived, the Licensor reserves the exclusive right to collect such royalties for any exercise by You of the rights granted under this License;
    2. Waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme can be waived, the Licensor waives the exclusive right to collect such royalties for any exercise by You of the rights granted under this License; and,
    3. Voluntary License Schemes. The Licensor waives the right to collect royalties, whether individually or, in the event that the Licensor is a member of a collecting society that administers voluntary licensing schemes, via that society, from any exercise by You of the rights granted under this License.

The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. Subject to Section 8(f), all rights not expressly granted by Licensor are hereby reserved.

4. Restrictions. The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:

  1. You may Distribute or Publicly Perform the Work only under the terms of this License. You must include a copy of, or the Uniform Resource Identifier (URI) for, this License with every copy of the Work You Distribute or Publicly Perform. You may not offer or impose any terms on the Work that restrict the terms of this License or the ability of the recipient of the Work to exercise the rights granted to that recipient under the terms of the License. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties with every copy of the Work You Distribute or Publicly Perform. When You Distribute or Publicly Perform the Work, You may not impose any effective technological measures on the Work that restrict the ability of a recipient of the Work from You to exercise the rights granted to that recipient under the terms of the License. This Section 4(a) applies to the Work as incorporated in a Collection, but this does not require the Collection apart from the Work itself to be made subject to the terms of this License. If You create a Collection, upon notice from any Licensor You must, to the extent practicable, remove from the Collection any credit as required by Section 4(b), as requested. If You create an Adaptation, upon notice from any Licensor You must, to the extent practicable, remove from the Adaptation any credit as required by Section 4(b), as requested.
  2. If You Distribute, or Publicly Perform the Work or any Adaptations or Collections, You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or if the Original Author and/or Licensor designate another party or parties (e.g., a sponsor institute, publishing entity, journal) for attribution ("Attribution Parties") in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; (ii) the title of the Work if supplied; (iii) to the extent reasonably practicable, the URI, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and (iv) , consistent with Section 3(b), in the case of an Adaptation, a credit identifying the use of the Work in the Adaptation (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). The credit required by this Section 4 (b) may be implemented in any reasonable manner; provided, however, that in the case of a Adaptation or Collection, at a minimum such credit will appear, if a credit for all contributing authors of the Adaptation or Collection appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors. For the avoidance of doubt, You may only use the credit required by this Section for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by the Original Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties.
  3. Except as otherwise agreed in writing by the Licensor or as may be otherwise permitted by applicable law, if You Reproduce, Distribute or Publicly Perform the Work either by itself or as part of any Adaptations or Collections, You must not distort, mutilate, modify or take other derogatory action in relation to the Work which would be prejudicial to the Original Author's honor or reputation. Licensor agrees that in those jurisdictions (e.g. Japan), in which any exercise of the right granted in Section 3(b) of this License (the right to make Adaptations) would be deemed to be a distortion, mutilation, modification or other derogatory action prejudicial to the Original Author's honor and reputation, the Licensor will waive or not assert, as appropriate, this Section, to the fullest extent permitted by the applicable national law, to enable You to reasonably exercise Your right under Section 3(b) of this License (right to make Adaptations) but not otherwise.

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. Termination.

  1. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Adaptations or Collections from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.
  2. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.

8. Miscellaneous

  1. Each time You Distribute or Publicly Perform the Work or a Collection, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.
  2. Each time You Distribute or Publicly Perform an Adaptation, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License.
  3. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
  4. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent
  5. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.
  6. The rights granted under, and the subject matter referenced, in this License were drafted utilizing the terminology of the Berne Convention for the Protection of Literary and Artistic Works (as amended on September 28, 1979), the Rome Convention of 1961, the WIPO Copyright Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 and the Universal Copyright Convention (as revised on July 24, 1971). These rights and subject matter take effect in the relevant jurisdiction in which the License terms are sought to be enforced according to the corresponding provisions of the implementation of those treaty provisions in the applicable national law. If the standard suite of rights granted under applicable copyright law includes additional rights not granted under this License, such additional rights are deemed to be included in the License; this License is not intended to restrict the license of any rights under applicable law.


  • ≪ Creative Commons Attribution 3.0
  • 関数・メソッド ≫
  • PHP Manual
  • 付録
  • 索引

索引

目次

  • 関数・メソッド
  • サンプル


関数・メソッド

マニュアル内の全関数およびメソッドの一覧

a b c d e f g h i j k l m n o p q r s t u v w x y z _

  • a
    • abs - 絶対値
    • acos - 逆余弦（アークコサイン）
    • acosh - 逆双曲線余弦（アークハイパボリックコサイン）
    • addcslashes - C 言語と同様にスラッシュで文字列をクォートする
    • addslashes - 文字列をスラッシュでクォートする
    • AllowDynamicProperties::__construct - 新しい AllowDynamicProperties のインスタンスを作成する
    • apache_child_terminate - このリクエストの後にApacheプロセスを終了する
    • apache_getenv - Apache の subprocess_env 変数を取得する
    • apache_get_modules - ロードされた Apache モジュールのリストを取得する
    • apache_get_version - Apache のバージョンを取得する
    • apache_lookup_uri - リクエストの一部を指定したURIに対して行い、全ての情報を返す
    • apache_note - Apacheリクエスト記号(note)を取得/設定する
    • apache_request_headers - すべての HTTP リクエストヘッダを取得する
    • apache_response_headers - HTTPレスポンスヘッダを全て取得する
    • apache_setenv - Apacheサブプロセスの環境変数を設定する
    • APCUIterator::current - 現在の項目を取得する
    • APCUIterator::getTotalCount - 総数を取得する
    • APCUIterator::getTotalHits - キャッシュヒットの総数を取得する
    • APCUIterator::getTotalSize - キャッシュのサイズの合計を取得する
    • APCUIterator::key - イテレータのキーを取得する
    • APCUIterator::next - ポインタを次の項目に移動させる
    • APCUIterator::rewind - イテレータを巻き戻す
    • APCUIterator::valid - 現在位置が有効かどうかを調べる
    • APCUIterator::__construct - APCUIterator イテレータオブジェクトを作成する
    • apcu_add - 新規の変数をデータ領域にキャッシュする
    • apcu_cache_info - APCu のデータから、キャッシュされた情報を取得する
    • apcu_cas - 古い値を新しい値に更新する
    • apcu_clear_cache - APCu キャッシュをクリアする
    • apcu_dec - 保存した数値を減らす
    • apcu_delete - 格納されている変数をキャッシュから取り除く
    • apcu_enabled - 現在の環境で apcu が使えるかを確認する
    • apcu_entry - アトミックに値を取得するか、キャッシュエントリを生成する
    • apcu_exists - エントリが存在するかどうかを調べる
    • apcu_fetch - 格納されている変数をキャッシュから取得する
    • apcu_inc - 保存した数値を増やす
    • apcu_key_info - キャッシュのキーに関する詳細な情報を取得する
    • apcu_sma_info - APCu の共有メモリ割り当てに関する情報を取得する
    • apcu_store - 変数をデータ領域にキャッシュする
    • AppendIterator::append - イテレータを追加する
    • AppendIterator::current - 現在の値を取得する
    • AppendIterator::getArrayIterator - ArrayIterator を取得する
    • AppendIterator::getIteratorIndex - イテレータのインデックスを取得する
    • AppendIterator::key - 現在のキーを取得する
    • AppendIterator::next - 次の要素に移動する
    • AppendIterator::rewind - イテレータを巻き戻す
    • AppendIterator::valid - 現在の要素が有効かどうかを調べる
    • AppendIterator::__construct - AppendIterator を作成する
    • array - 配列を生成する
    • ArrayAccess::offsetExists - オフセットが存在するかどうか
    • ArrayAccess::offsetGet - オフセットを取得する
    • ArrayAccess::offsetSet - 指定したオフセットに値を設定する
    • ArrayAccess::offsetUnset - オフセットの設定を解除する
    • ArrayIterator::append - 要素を追加する
    • ArrayIterator::asort - 値で配列をソートする
    • ArrayIterator::count - 要素を数える
    • ArrayIterator::current - 現在の配列エントリを返す
    • ArrayIterator::getArrayCopy - 配列のコピーを取得する
    • ArrayIterator::getFlags - 振る舞いのフラグを取得する
    • ArrayIterator::key - 現在の配列キーを返す
    • ArrayIterator::ksort - キーで配列をソートする
    • ArrayIterator::natcasesort - 大文字小文字を区別せずに自然順で配列をソートする
    • ArrayIterator::natsort - 自然順で配列をソートする
    • ArrayIterator::next - 次のエントリに移動する
    • ArrayIterator::offsetExists - オフセットが存在するかどうかを調べる
    • ArrayIterator::offsetGet - オフセットの値を取得する
    • ArrayIterator::offsetSet - オフセットの値を設定する
    • ArrayIterator::offsetUnset - オフセットの値を削除する
    • ArrayIterator::rewind - 配列を最初に巻き戻す
    • ArrayIterator::seek - 位置を移動する
    • ArrayIterator::serialize - シリアライズする
    • ArrayIterator::setFlags - 振る舞いのフラグを設定する
    • ArrayIterator::uasort - ユーザー定義の比較関数を使ってソートを行い、インデックスとの関連を管理する
    • ArrayIterator::uksort - ユーザー定義の比較関数を使い、キーでソートする
    • ArrayIterator::unserialize - アンシリアライズする
    • ArrayIterator::valid - 配列がまだエントリを持っているかどうかチェックする
    • ArrayIterator::__construct - ArrayIterator を作成する
    • ArrayObject::append - 値を追加する
    • ArrayObject::asort - 値でエントリをソートする
    • ArrayObject::count - ArrayObject の public プロパティの数を取得する
    • ArrayObject::exchangeArray - 配列を別の配列と交換する
    • ArrayObject::getArrayCopy - ArrayObject のコピーを作成する
    • ArrayObject::getFlags - 振る舞いのフラグを取得する
    • ArrayObject::getIterator - ArrayObject インスタンスから新規イテレータを生成する
    • ArrayObject::getIteratorClass - ArrayObject のイテレータクラス名を取得する
    • ArrayObject::ksort - キーでエントリをソートする
    • ArrayObject::natcasesort - 大文字小文字を区別しない "自然順" アルゴリズムでエントリをソートする
    • ArrayObject::natsort - "自然順" アルゴリズムでエントリをソートする
    • ArrayObject::offsetExists - 要求されたインデックスが存在するかどうかを返す
    • ArrayObject::offsetGet - 指定したインデックスの値を返す
    • ArrayObject::offsetSet - 指定したインデックスに新しい値をセットする
    • ArrayObject::offsetUnset - 指定したインデックスの値を解除する
    • ArrayObject::serialize - ArrayObject をシリアライズする
    • ArrayObject::setFlags - 処理フラグを設定する
    • ArrayObject::setIteratorClass - ArrayObject のイテレータクラス名を設定する
    • ArrayObject::uasort - ユーザー定義の比較関数でエントリをソートし、キーとの対応は保持する
    • ArrayObject::uksort - ユーザー定義の比較関数を使って、キーでエントリをソートする
    • ArrayObject::unserialize - ArrayObject をアンシリアライズする
    • ArrayObject::__construct - 新規配列オブジェクトを生成する
    • array_change_key_case - 配列のすべてのキーの大文字小文字を変更する
    • array_chunk - 配列を分割する
    • array_column - 入力配列から単一のカラムの値を返す
    • array_combine - 一方の配列をキーとして、もう一方の配列を値として、ひとつの配列を生成する
    • array_count_values - 配列内に存在する、異なる値の出現回数を数える
    • array_diff - 配列の差を計算する
    • array_diff_assoc - 追加された添字の確認を含めて配列の差を計算する
    • array_diff_key - キーを基準にして配列の差を計算する
    • array_diff_uassoc - ユーザーが指定したコールバック関数を利用し、 追加された添字の確認を含めて配列の差を計算する
    • array_diff_ukey - キーを基準にし、コールバック関数を用いて配列の差を計算する
    • array_fill - 配列を指定した値で埋める
    • array_fill_keys - キーを指定して、配列を値で埋める
    • array_filter - コールバック関数を使用して、配列の要素をフィルタリングする
    • array_flip - 配列のキーと値を反転する
    • array_intersect - 配列の共通項を計算する
    • array_intersect_assoc - 追加された添字の確認も含めて配列の共通項を確認する
    • array_intersect_key - キーを基準にして配列の共通項を計算する
    • array_intersect_uassoc - 追加された添字の確認も含め、コールバック関数を用いて 配列の共通項を確認する
    • array_intersect_ukey - キーを基準にし、コールバック関数を用いて 配列の共通項を計算する
    • array_is_list - 指定された配列がリストかどうかをチェックする
    • array_keys - 配列のキーすべて、あるいはその一部を返す
    • array_key_exists - 指定したキーまたは添字が配列にあるかどうかを調べる
    • array_key_first - 配列の最初のキーを得る
    • array_key_last - 配列の最後のキーを得る
    • array_map - 指定した配列の要素にコールバック関数を適用する
    • array_merge - ひとつまたは複数の配列をマージする
    • array_merge_recursive - 一つ以上の配列を再帰的にマージする
    • array_multisort - 複数または多次元の配列をソートする
    • array_pad - 指定長、指定した値で配列を埋める
    • array_pop - 配列の末尾から要素を取り除く
    • array_product - 配列の値の積を計算する
    • array_push - 一つ以上の要素を配列の最後に追加する
    • array_rand - 配列から一つ以上のキーをランダムに取得する
    • array_reduce - コールバック関数を繰り返し配列に適用し、配列をひとつの値にまとめる
    • array_replace - 渡された配列の要素を置き換える
    • array_replace_recursive - 渡された配列の要素を再帰的に置き換える
    • array_reverse - 要素を逆順にした配列を返す
    • array_search - 指定した値を配列で検索し、見つかった場合に対応する最初のキーを返す
    • array_shift - 配列の先頭から要素を一つ取り出す
    • array_slice - 配列の一部を展開する
    • array_splice - 配列の一部を削除し、他の要素で置換する
    • array_sum - 配列の中の値の合計を計算する
    • array_udiff - データの比較にコールバック関数を用い、配列の差を計算する
    • array_udiff_assoc - データの比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
    • array_udiff_uassoc - データと添字の比較にコールバック関数を用い、 追加された添字の確認を含めて配列の差を計算する
    • array_uintersect - データの比較にコールバック関数を用い、配列の共通項を計算する
    • array_uintersect_assoc - データの比較にコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
    • array_uintersect_uassoc - データと添字の比較に個別のコールバック関数を用い、 追加された添字の確認も含めて配列の共通項を計算する
    • array_unique - 配列から重複した値を削除する
    • array_unshift - 一つ以上の要素を配列の最初に加える
    • array_values - 配列の全ての値を返す
    • array_walk - 配列の全ての要素にユーザー定義の関数を適用する
    • array_walk_recursive - 配列の全ての要素に、ユーザー関数を再帰的に適用する
    • arsort - 連想キーと要素との関係を維持しつつ配列を降順にソートする
    • asin - 逆正弦（アークサイン）
    • asinh - 逆双曲線正弦（アークハイパボリックサイン）
    • asort - 連想キーと要素との関係を維持しつつ配列を昇順にソートする
    • assert - アサーションの値を調べる
    • assert_options - 様々な assert フラグを設定/取得する
    • atan - 逆正接（アークタンジェント）
    • atan2 - 2 変数のアークタンジェント
    • atanh - 逆双曲線正接（アークハイパボリックタンジェント）
    • Attribute::__construct - 新しい Attribute のインスタンスを作成する
  • b
    • BackedEnum::from - スカラー型の値を列挙型にマップする
    • BackedEnum::tryFrom - スカラー型の値を列挙型にマップするか、null を返す
    • base64_decode - MIME base64 方式によりエンコードされたデータをデコードする
    • base64_encode - MIME base64 方式でデータをエンコードする
    • basename - パスの最後にある名前の部分を返す
    • BaseResult::getWarnings - 直近の操作の警告を取得する
    • BaseResult::getWarningsCount - 直近の操作から発生した警告の数を取得する
    • base_convert - 数値の基数を任意に変換する
    • bcadd - 2つの任意精度の数値を加算する
    • bccomp - 2 つの任意精度数値を比較する
    • bcdiv - 2つの任意精度数値で除算を行う
    • bcmod - 2 つの任意精度数値の剰余を取得する
    • bcmul - 2つの任意精度数値の乗算を行う
    • bcpow - 任意精度数値をべき乗する
    • bcpowmod - 任意精度数値のべき乗の、指定した数値による剰余
    • bcscale - すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
    • bcsqrt - 任意精度数値の平方根を取得する
    • bcsub - 任意精度数値の減算を行う
    • bin2hex - バイナリのデータを16進表現に変換する
    • bindec - 2 進数 を 10 進数に変換する
    • bindtextdomain - ドメインのパスを取得/設定する
    • bind_textdomain_codeset - DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
    • boolval - 変数の boolean としての値を取得する
    • bzclose - bzip2 ファイルを閉じる
    • bzcompress - 文字列をbzip2形式のデータに圧縮する
    • bzdecompress - bzip2 形式のデータを解凍する
    • bzerrno - bzip2 エラー番号を返す
    • bzerror - bzip2 エラー番号とエラー文字列を配列で返す
    • bzerrstr - bzip2 エラー文字列を返す
    • bzflush - 何もしない
    • bzopen - bzip2 圧縮されたファイルをオープンする
    • bzread - バイナリ対応の bzip2 ファイル読み込み
    • bzwrite - バイナリ対応の bzip2 ファイルへの書き込み
  • c
    • CachingIterator::count - イテレータ内の要素の数
    • CachingIterator::current - 現在の要素を返す
    • CachingIterator::getCache - キャッシュの内容を取得する
    • CachingIterator::getFlags - 使用しているフラグを取得する
    • CachingIterator::hasNext - 内部イテレータが有効な次の要素を持つかどうかをチェックする
    • CachingIterator::key - 現在の要素のキーを返す
    • CachingIterator::next - イテレータを前方に移動する
    • CachingIterator::offsetExists - The offsetExists purpose
    • CachingIterator::offsetGet - The offsetGet purpose
    • CachingIterator::offsetSet - The offsetSet purpose
    • CachingIterator::offsetUnset - The offsetUnset purpose
    • CachingIterator::rewind - イテレータを巻き戻す
    • CachingIterator::setFlags - The setFlags purpose
    • CachingIterator::valid - 現在の要素が有効かどうかをチェックする
    • CachingIterator::__construct - 新しい CachingIterator オブジェクトを作成する
    • CachingIterator::__toString - 現在の要素の文字列表現を返す
    • CallbackFilterIterator::accept - 現在の値、現在のキー、そして内部イテレータを引数としてでコールバックを呼び出す
    • CallbackFilterIterator::__construct - フィルタリングしたイテレータを別のイテレータから作成する
    • call_user_func - 最初の引数で指定したコールバック関数をコールする
    • call_user_func_array - パラメータの配列を指定してコールバック関数をコールする
    • cal_days_in_month - 指定した年とカレンダーについて、月の日数を返す
    • cal_from_jd - ユリウス積算日からサポートされるカレンダーに変換する
    • cal_info - 特定のカレンダーに関する情報を返す
    • cal_to_jd - サポートされるカレンダーからユリウス積算日に変換する
    • ceil - 端数の切り上げ
    • chdir - ディレクトリを変更する
    • checkdate - グレゴリオ暦の日付/時刻の妥当性を確認します
    • checkdnsrr - 指定したインターネットホスト名もしくは IP アドレスに対応する DNS レコードを検索する
    • chgrp - ファイルのグループを変更する
    • chmod - ファイルのモードを変更する
    • chop - rtrim のエイリアス
    • chown - ファイルの所有者を変更する
    • chr - 数値から、1バイトの文字列を生成する
    • chroot - ルートディレクトリを変更する
    • chunk_split - 文字列をより小さな部分に分割する
    • class_alias - クラスのエイリアスを作成する
    • class_exists - クラスが定義済みかどうかを確認する
    • class_implements - 与えられたクラスあるいはインターフェイスが実装しているインターフェイスを返す
    • class_parents - 与えられたクラスの親クラスを返す
    • class_uses - 指定したクラスが使っているトレイトを返す
    • clearstatcache - ファイルのステータスのキャッシュをクリアする
    • Client::getClient - クライアントのセッションを取得する
    • Client::__construct - Client のコンストラクタ
    • cli_get_process_title - 現在のプロセスのタイトルを返す
    • cli_set_process_title - プロセスのタイトルを設定する
    • closedir - ディレクトリハンドルをクローズする
    • closelog - システムログへの接続を閉じる
    • Closure::bind - バインドされたオブジェクトとクラスのスコープでクロージャを複製する
    • Closure::bindTo - 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する
    • Closure::call - クロージャを束縛して呼び出す
    • Closure::fromCallable - callable をクロージャに変換する
    • Closure::__construct - インスタンス作成を無効化したコンストラクタ
    • Collator::asort - インデックスの情報を保持しつつ配列を並べ替える
    • Collator::compare - ふたつの Unicode 文字列を比較する
    • Collator::create - collator を作成する
    • Collator::getAttribute - 照合用の属性の値を取得する
    • Collator::getErrorCode - collator の直近のエラーコードを取得する
    • Collator::getErrorMessage - collator の直近のエラーコードのテキストを取得する
    • Collator::getLocale - collator のロケール名を取得する
    • Collator::getSortKey - 文字列のソート用のキーを取得する
    • Collator::getStrength - 現在の照合強度を取得する
    • Collator::setAttribute - 照合用の属性を設定する
    • Collator::setStrength - 照合強度を設定する
    • Collator::sort - 指定した collator で配列を並べ替える
    • Collator::sortWithSortKeys - 指定した collator とキーで配列を並べ替える
    • Collator::__construct - collator を作成する
    • Collectable::isGarbage - Determine whether an object has been marked as garbage
    • Collection::add - コレクションにドキュメントを追加する
    • Collection::addOrReplaceOne - コレクションのドキュメントを追加または置換する
    • Collection::count - ドキュメントの数を取得する
    • Collection::createIndex - コレクションにインデックスを作成
    • Collection::dropIndex - コレクションのインデックスを削除
    • Collection::existsInDatabase - コレクションがデータベースに存在するかをチェックする
    • Collection::find - ドキュメントを検索する
    • Collection::getName - コレクションの名前を得る
    • Collection::getOne - ドキュメントをひとつ取得
    • Collection::getSchema - スキーマオブジェクトを得る
    • Collection::getSession - セッションオブジェクトを取得
    • Collection::modify - コレクションのドキュメントを変更する
    • Collection::remove - コレクションを削除する
    • Collection::removeOne - コレクションからドキュメントをひとつ削除する
    • Collection::replaceOne - コレクションのドキュメントをひとつ置き換える
    • Collection::__construct - Collection のコンストラクタ
    • CollectionAdd::execute - ステートメントを実行する
    • CollectionAdd::__construct - CollectionAdd のコンストラクタ
    • CollectionFind::bind - クエリのプレースホルダーに値をバインドする
    • CollectionFind::execute - ステートメントを実行する
    • CollectionFind::fields - ドキュメントのフィールドのフィルタを設定する
    • CollectionFind::groupBy - グループ化の条件を設定する
    • CollectionFind::having - 集約関数の条件を設定する
    • CollectionFind::limit - 返されるドキュメントの数を限定する
    • CollectionFind::lockExclusive - Execute operation with EXCLUSIVE LOCK
    • CollectionFind::lockShared - SHARED LOCK 付きで操作を実行する
    • CollectionFind::offset - 返される要素の数から、与えられた数をスキップする
    • CollectionFind::sort - ソート条件を設定する
    • CollectionFind::__construct - CollectionFind のコンストラクタ
    • CollectionModify::arrayAppend - 配列のフィールドに要素を追加する
    • CollectionModify::arrayInsert - 配列のフィールドに要素を挿入する
    • CollectionModify::bind - クエリのプレースホルダーに値をバインドする
    • CollectionModify::execute - 変更の操作を実行する
    • CollectionModify::limit - 変更されるドキュメントの数を限定する
    • CollectionModify::patch - document にパッチを当てる
    • CollectionModify::replace - ドキュメントのフィールドを置き換える
    • CollectionModify::set - ドキュメントの属性を設定する
    • CollectionModify::skip - 要素をスキップする
    • CollectionModify::sort - ソート条件を設定する
    • CollectionModify::unset - ドキュメントのフィールドの値を削除する
    • CollectionModify::__construct - CollectionModify のコンストラクタ
    • CollectionRemove::bind - プレースホルダーに値をバインドする
    • CollectionRemove::execute - 削除操作を実行する
    • CollectionRemove::limit - 削除するドキュメントの数を限定する
    • CollectionRemove::sort - ソート条件を設定する
    • CollectionRemove::__construct - CollectionRemove のコンストラクタ
    • ColumnResult::getCharacterSetName - キャラクタセットを取得する
    • ColumnResult::getCollationName - 照合順序名を取得する
    • ColumnResult::getColumnLabel - カラムのラベルを取得する
    • ColumnResult::getColumnName - カラム名を取得する
    • ColumnResult::getFractionalDigits - カラムの小数の桁数を取得する
    • ColumnResult::getLength - カラムのフィールドの長さを取得する
    • ColumnResult::getSchemaName - スキーマ名を取得する
    • ColumnResult::getTableLabel - テーブルラベルを取得する
    • ColumnResult::getTableName - テーブル名を取得する
    • ColumnResult::getType - カラムの型を取得する
    • ColumnResult::isNumberSigned - 符号付きの型かどうかを調べる
    • ColumnResult::isPadded - パディングされているかを調べる
    • ColumnResult::__construct - ColumnResult のコンストラクタ
    • com::__construct - com クラスのコンストラクタ
    • CommonMark\CQL::__construct - CQL Construction
    • CommonMark\CQL::__invoke - CQL Execution
    • CommonMark\Interfaces\IVisitable::accept - Visitation
    • CommonMark\Interfaces\IVisitor::enter - Visitation
    • CommonMark\Interfaces\IVisitor::leave - Visitation
    • CommonMark\Node::accept - Visitation
    • CommonMark\Node::appendChild - AST Manipulation
    • CommonMark\Node::insertAfter - AST Manipulation
    • CommonMark\Node::insertBefore - AST Manipulation
    • CommonMark\Node::prependChild - AST Manipulation
    • CommonMark\Node::replace - AST Manipulation
    • CommonMark\Node::unlink - AST Manipulation
    • CommonMark\Node\BulletList::__construct - BulletList Construction
    • CommonMark\Node\CodeBlock::__construct - CodeBlock Construction
    • CommonMark\Node\Heading::__construct - Heading Construction
    • CommonMark\Node\Image::__construct - Image Construction
    • CommonMark\Node\Link::__construct - Link Construction
    • CommonMark\Node\OrderedList::__construct - OrderedList Construction
    • CommonMark\Node\Text::__construct - Text Construction
    • CommonMark\Parse - Parsing
    • CommonMark\Parser::finish - Parsing
    • CommonMark\Parser::parse - Parsing
    • CommonMark\Parser::__construct - Parsing
    • CommonMark\Render - Rendering
    • CommonMark\Render\HTML - Rendering
    • CommonMark\Render\Latex - Rendering
    • CommonMark\Render\Man - Rendering
    • CommonMark\Render\XML - Rendering
    • compact - 変数名とその値から配列を作成する
    • COMPersistHelper::GetCurFileName - 現在のファイル名を取得する
    • COMPersistHelper::GetMaxStreamSize - ストリームのサイズの最大値を取得する
    • COMPersistHelper::InitNew - オブジェクトをデフォルトの状態に初期化する
    • COMPersistHelper::LoadFromFile - オブジェクトをファイルから読み込む
    • COMPersistHelper::LoadFromStream - ストリームからオブジェクトを読み込む
    • COMPersistHelper::SaveToFile - オブジェクトをファイルに保存する
    • COMPersistHelper::SaveToStream - オブジェクトをストリームに保存する
    • COMPersistHelper::__construct - COMPersistHelper オブジェクトを構築する
    • Componere\Abstract\Definition::addInterface - Add Interface
    • Componere\Abstract\Definition::addMethod - Add Method
    • Componere\Abstract\Definition::addTrait - Add Trait
    • Componere\Abstract\Definition::getReflector - Reflection
    • Componere\cast - Casting
    • Componere\cast_by_ref - Casting
    • Componere\Definition::addConstant - Add Constant
    • Componere\Definition::addProperty - Add Property
    • Componere\Definition::getClosure - Get Closure
    • Componere\Definition::getClosures - Get Closures
    • Componere\Definition::isRegistered - State Detection
    • Componere\Definition::register - Registration
    • Componere\Definition::__construct - Definition Construction
    • Componere\Method::getReflector - Reflection
    • Componere\Method::setPrivate - Accessibility Modification
    • Componere\Method::setProtected - Accessibility Modification
    • Componere\Method::setStatic - Accessibility Modification
    • Componere\Method::__construct - Method Construction
    • Componere\Patch::apply - Application
    • Componere\Patch::derive - Patch Derivation
    • Componere\Patch::getClosure - Get Closure
    • Componere\Patch::getClosures - Get Closures
    • Componere\Patch::isApplied - State Detection
    • Componere\Patch::revert - Reversal
    • Componere\Patch::__construct - Patch Construction
    • Componere\Value::hasDefault - Value Interaction
    • Componere\Value::isPrivate - Accessibility Detection
    • Componere\Value::isProtected - Accessibility Detection
    • Componere\Value::isStatic - Accessibility Detection
    • Componere\Value::setPrivate - Accessibility Modification
    • Componere\Value::setProtected - Accessibility Modification
    • Componere\Value::setStatic - Accessibility Modification
    • Componere\Value::__construct - Value Construction
    • com_create_guid - グローバルユニーク ID (GUID) を生成する
    • com_event_sink - COM オブジェクトのイベントを PHP オブジェクトに接続する
    • com_get_active_object - すでに実行中の COM オブジェクトのインスタンスへのハンドルを返す
    • com_load_typelib - タイプライブラリを読み込む
    • com_message_pump - COM メッセージを処理し、timeoutms ミリ秒の間待つ
    • com_print_typeinfo - ディスパッチインターフェイスのために、PHP のクラス定義を出力する
    • connection_aborted - クライアントとの接続が切断されているかどうかを調べる
    • connection_status - 接続ステータスのビットフィールドを返す
    • constant - 定数の値を返す
    • convert_cyr_string - キリル文字セットを他のものに変換する
    • convert_uudecode - uuencode された文字列をデコードする
    • convert_uuencode - 文字列を uuencode する
    • copy - ファイルをコピーする
    • cos - 余弦（コサイン）
    • cosh - 双曲線余弦（ハイパボリックコサイン）
    • count - 配列または Countable オブジェクトに含まれるすべての要素の数を数える
    • Countable::count - オブジェクトの要素数を数える
    • count_chars - 文字列で使用されている文字に関する情報を返す
    • crc32 - 文字列の crc32 多項式計算を行う
    • create_function - 文字列のコードを評価し、動的に関数を作成する
    • CrudOperationBindable::bind - プレースホルダーに値をバインドする
    • CrudOperationLimitable::limit - 結果を限定する
    • CrudOperationSkippable::skip - スキップする操作の数
    • CrudOperationSortable::sort - 結果をソートする
    • crypt - 文字列の一方向のハッシュ化を行う
    • ctype_alnum - 英数字かどうかを調べる
    • ctype_alpha - 英字かどうかを調べる
    • ctype_cntrl - 制御文字かどうかを調べる
    • ctype_digit - 数字かどうかを調べる
    • ctype_graph - 空白以外の印字可能な文字かどうかを調べる
    • ctype_lower - 小文字かどうかを調べる
    • ctype_print - 印字可能な文字かどうかを調べる
    • ctype_punct - 空白、英数字以外の出力可能な文字かどうかを調べる
    • ctype_space - 空白文字かどうか調べる
    • ctype_upper - 大文字かどうか調べる
    • ctype_xdigit - 16 進数を表す文字かどうかを調べる
    • cubrid_affected_rows - Return the number of rows affected by the last SQL statement
    • cubrid_bind - Bind variables to a prepared statement as parameters
    • cubrid_client_encoding - Return the current CUBRID connection charset
    • cubrid_close - Close CUBRID connection
    • cubrid_close_prepare - Close the request handle
    • cubrid_close_request - Close the request handle
    • cubrid_column_names - Get the column names in result
    • cubrid_column_types - Get column types in result
    • cubrid_col_get - Get contents of collection type column using OID
    • cubrid_col_size - Get the number of elements in collection type column using OID
    • cubrid_commit - Commit a transaction
    • cubrid_connect - Open a connection to a CUBRID Server
    • cubrid_connect_with_url - Establish the environment for connecting to CUBRID server
    • cubrid_current_oid - Get OID of the current cursor location
    • cubrid_data_seek - Move the internal row pointer of the CUBRID result
    • cubrid_db_name - Get db name from results of cubrid_list_dbs
    • cubrid_disconnect - Close a database connection
    • cubrid_drop - Delete an instance using OID
    • cubrid_errno - Return the numerical value of the error message from previous CUBRID operation
    • cubrid_error - Get the error message
    • cubrid_error_code - Get error code for the most recent function call
    • cubrid_error_code_facility - Get the facility code of error
    • cubrid_error_msg - Get last error message for the most recent function call
    • cubrid_execute - Execute a prepared SQL statement
    • cubrid_fetch - Fetch the next row from a result set
    • cubrid_fetch_array - Fetch a result row as an associative array, a numeric array, or both
    • cubrid_fetch_assoc - Return the associative array that corresponds to the fetched row
    • cubrid_fetch_field - Get column information from a result and return as an object
    • cubrid_fetch_lengths - Return an array with the lengths of the values of each field from the current row
    • cubrid_fetch_object - Fetch the next row and return it as an object
    • cubrid_fetch_row - Return a numerical array with the values of the current row
    • cubrid_field_flags - Return a string with the flags of the given field offset
    • cubrid_field_len - Get the maximum length of the specified field
    • cubrid_field_name - Return the name of the specified field index
    • cubrid_field_seek - Move the result set cursor to the specified field offset
    • cubrid_field_table - Return the name of the table of the specified field
    • cubrid_field_type - Return the type of the column corresponding to the given field offset
    • cubrid_free_result - Free the memory occupied by the result data
    • cubrid_get - Get a column using OID
    • cubrid_get_autocommit - Get auto-commit mode of the connection
    • cubrid_get_charset - Return the current CUBRID connection charset
    • cubrid_get_class_name - Get the class name using OID
    • cubrid_get_client_info - Return the client library version
    • cubrid_get_db_parameter - Returns the CUBRID database parameters
    • cubrid_get_query_timeout - Get the query timeout value of the request
    • cubrid_get_server_info - Return the CUBRID server version
    • cubrid_insert_id - Return the ID generated for the last updated AUTO_INCREMENT column
    • cubrid_is_instance - Check whether the instance pointed by OID exists
    • cubrid_list_dbs - Return an array with the list of all existing CUBRID databases
    • cubrid_load_from_glo - Read data from a GLO instance and save it in a file
    • cubrid_lob2_bind - Bind a lob object or a string as a lob object to a prepared statement as parameters
    • cubrid_lob2_close - Close LOB object
    • cubrid_lob2_export - Export the lob object to a file
    • cubrid_lob2_import - Import BLOB/CLOB data from a file
    • cubrid_lob2_new - Create a lob object
    • cubrid_lob2_read - Read from BLOB/CLOB data
    • cubrid_lob2_seek - Move the cursor of a lob object
    • cubrid_lob2_seek64 - Move the cursor of a lob object
    • cubrid_lob2_size - Get a lob object's size
    • cubrid_lob2_size64 - Get a lob object's size
    • cubrid_lob2_tell - Tell the cursor position of the LOB object
    • cubrid_lob2_tell64 - Tell the cursor position of the LOB object
    • cubrid_lob2_write - Write to a lob object
    • cubrid_lob_close - Close BLOB/CLOB data
    • cubrid_lob_export - Export BLOB/CLOB data to file
    • cubrid_lob_get - Get BLOB/CLOB data
    • cubrid_lob_send - Read BLOB/CLOB data and send straight to browser
    • cubrid_lob_size - Get BLOB/CLOB data size
    • cubrid_lock_read - Set a read lock on the given OID
    • cubrid_lock_write - Set a write lock on the given OID
    • cubrid_move_cursor - Move the cursor in the result
    • cubrid_new_glo - Create a glo instance
    • cubrid_next_result - Get result of next query when executing multiple SQL statements
    • cubrid_num_cols - Return the number of columns in the result set
    • cubrid_num_fields - Return the number of columns in the result set
    • cubrid_num_rows - Get the number of rows in the result set
    • cubrid_pconnect - Open a persistent connection to a CUBRID server
    • cubrid_pconnect_with_url - Open a persistent connection to CUBRID server
    • cubrid_ping - Ping a server connection or reconnect if there is no connection
    • cubrid_prepare - Prepare a SQL statement for execution
    • cubrid_put - Update a column using OID
    • cubrid_query - Send a CUBRID query
    • cubrid_real_escape_string - Escape special characters in a string for use in an SQL statement
    • cubrid_result - Return the value of a specific field in a specific row
    • cubrid_rollback - Roll back a transaction
    • cubrid_save_to_glo - Save requested file in a GLO instance
    • cubrid_schema - Get the requested schema information
    • cubrid_send_glo - Read data from glo and send it to std output
    • cubrid_seq_drop - Delete an element from sequence type column using OID
    • cubrid_seq_insert - Insert an element to a sequence type column using OID
    • cubrid_seq_put - Update the element value of sequence type column using OID
    • cubrid_set_add - Insert a single element to set type column using OID
    • cubrid_set_autocommit - Set autocommit mode of the connection
    • cubrid_set_db_parameter - Sets the CUBRID database parameters
    • cubrid_set_drop - Delete an element from set type column using OID
    • cubrid_set_query_timeout - Set the timeout time of query execution
    • cubrid_unbuffered_query - Perform a query without fetching the results into memory
    • cubrid_version - Get the CUBRID PHP module's version
    • CURLFile::getFilename - ファイル名を取得する
    • CURLFile::getMimeType - MIME タイプを取得する
    • CURLFile::getPostFilename - POST 用のファイル名を取得する
    • CURLFile::setMimeType - MIME タイプを設定する
    • CURLFile::setPostFilename - POST 用のファイル名を設定する
    • CURLFile::__construct - CURLFile オブジェクトを作る
    • CURLStringFile::__construct - CURLStringFile オブジェクトを作る
    • curl_close - cURL セッションを閉じる
    • curl_copy_handle - cURL ハンドルを、その設定も含めてコピーする
    • curl_errno - 直近のエラー番号を返す
    • curl_error - 現在のセッションに関する直近のエラー文字列を返す
    • curl_escape - 指定した文字列を URL エンコードする
    • curl_exec - cURL セッションを実行する
    • curl_getinfo - 指定した伝送に関する情報を得る
    • curl_init - cURL セッションを初期化する
    • curl_multi_add_handle - cURL マルチハンドルに、通常の cURL ハンドルを追加する
    • curl_multi_close - cURL ハンドルのセットを閉じる
    • curl_multi_errno - 直近のマルチハンドルに対するエラー番号を返す
    • curl_multi_exec - 現在の cURL ハンドルから、サブ接続を実行する
    • curl_multi_getcontent - CURLOPT_RETURNTRANSFER が設定されている場合に、cURL ハンドルの内容を返す
    • curl_multi_info_read - 現在の転送についての情報を表示する
    • curl_multi_init - 新規 cURL マルチハンドルを返す
    • curl_multi_remove_handle - cURL ハンドルのセットからマルチハンドルを削除する
    • curl_multi_select - curl_multi 接続のアクティビティを待つ
    • curl_multi_setopt - cURL マルチハンドル用のオプションを設定する
    • curl_multi_strerror - エラーの内容を表す文字列を返す
    • curl_pause - 接続の中断と再開をする
    • curl_reset - libcurl セッションハンドルのすべてのオプションをリセットする
    • curl_setopt - cURL 転送用オプションを設定する
    • curl_setopt_array - CURL 転送用の複数のオプションを設定する
    • curl_share_close - cURL 共有ハンドルを閉じる
    • curl_share_errno - 直近の共有ハンドルに対するエラー番号を返す
    • curl_share_init - curl 共有ハンドルを初期化する
    • curl_share_setopt - cURL 共有ハンドルのオプションを設定する
    • curl_share_strerror - 与えられたエラーコードを説明する文字列を返す
    • curl_strerror - エラーコードの説明を返す
    • curl_unescape - URL エンコードされた文字列をデコードする
    • curl_upkeep - 接続を維持するためのチェックを行う
    • curl_version - cURL のバージョンを返す
    • current - 配列内の現在の要素を返す
  • d
    • DatabaseObject::existsInDatabase - オブジェクトがデータベースに存在するかをチェックする
    • DatabaseObject::getName - オブジェクトの名前を取得する
    • DatabaseObject::getSession - セッションの名前を取得する
    • date - Unixタイムスタンプを書式化する
    • DateInterval::createFromDateString - 相対指定文字列から DateInterval を作成する
    • DateInterval::format - 間隔をフォーマットする
    • DateInterval::__construct - 新しい DateInterval オブジェクトを作成する
    • DatePeriod::createFromISO8601String - ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する
    • DatePeriod::getDateInterval - 間隔を取得する
    • DatePeriod::getEndDate - 終了日を取得する
    • DatePeriod::getRecurrences - 繰り返しの数を取得する
    • DatePeriod::getStartDate - 開始日を取得する
    • DatePeriod::__construct - 新しい DatePeriod オブジェクトを作成する
    • DateTime::add - 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
    • DateTime::createFromFormat - 指定した書式で時刻文字列をパースする
    • DateTime::createFromImmutable - 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す
    • DateTime::createFromInterface - 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
    • DateTime::getLastErrors - DateTimeImmutable::getLastErrors のエイリアス
    • DateTime::modify - タイムスタンプを変更する
    • DateTime::setDate - 日付を設定する
    • DateTime::setISODate - ISO 形式の日付を設定する
    • DateTime::setTime - 時刻を設定する
    • DateTime::setTimestamp - Unix タイムスタンプを用いて日付と時刻を設定する
    • DateTime::setTimezone - DateTime オブジェクトのタイムゾーンを設定する
    • DateTime::sub - 年月日時分秒の値を DateTime オブジェクトから引く
    • DateTime::__construct - 新しい DateTime オブジェクトを返す
    • DateTime::__set_state - __set_state ハンドラ
    • DateTime::__wakeup - __wakeup ハンドラ
    • DateTimeImmutable::add - 年月日時分秒の値を加え、新しいオブジェクトを返す
    • DateTimeImmutable::createFromFormat - 時刻の文字列を指定されたフォーマットに従ってパースする
    • DateTimeImmutable::createFromInterface - 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::createFromMutable - 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す
    • DateTimeImmutable::getLastErrors - 警告およびエラーを返す
    • DateTimeImmutable::modify - タイムスタンプを変更した新しいオブジェクトを作る
    • DateTimeImmutable::setDate - 日付を設定する
    • DateTimeImmutable::setISODate - ISO 日付を設定する
    • DateTimeImmutable::setTime - 時刻を設定する
    • DateTimeImmutable::setTimestamp - Unix タイムスタンプを用いて日付と時刻を設定する
    • DateTimeImmutable::setTimezone - タイムゾーンを設定する
    • DateTimeImmutable::sub - 年月日時分秒の値を引く
    • DateTimeImmutable::__construct - 新しい DateTimeImmutable オブジェクトを返す
    • DateTimeImmutable::__set_state - __set_state ハンドラ
    • DateTimeInterface::diff - ふたつの DateTime オブジェクトの差を返す
    • DateTimeInterface::format - 指定した書式でフォーマットした日付を返す
    • DateTimeInterface::getOffset - タイムゾーンのオフセットを返す
    • DateTimeInterface::getTimestamp - Unix タイムスタンプを取得する
    • DateTimeInterface::getTimezone - 指定した DateTime に関連するタイムゾーンを返す
    • DateTimeZone::getLocation - タイムゾーンの位置情報を返す
    • DateTimeZone::getName - タイムゾーンの名前を返す
    • DateTimeZone::getOffset - GMT からのタイムゾーンのオフセットを返す
    • DateTimeZone::getTransitions - タイムゾーンの変遷を返す
    • DateTimeZone::listAbbreviations - 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す
    • DateTimeZone::listIdentifiers - すべてのタイムゾーン識別子を含む配列を返す
    • DateTimeZone::__construct - 新しい DateTimeZone オブジェクトを作成する
    • date_add - DateTime::add のエイリアス
    • date_create - 新しい DateTime オブジェクトを作成する
    • date_create_from_format - DateTime::createFromFormat のエイリアス
    • date_create_immutable - 新しい DateTimeImmutable オブジェクトを作成する
    • date_create_immutable_from_format - DateTimeImmutable::createFromFormat のエイリアス
    • date_date_set - DateTime::setDate のエイリアス
    • date_default_timezone_get - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する
    • date_default_timezone_set - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する
    • date_diff - DateTime::diff のエイリアス
    • date_format - DateTime::format のエイリアス
    • date_get_last_errors - DateTimeImmutable::getLastErrors のエイリアス
    • date_interval_create_from_date_string - DateInterval::createFromDateString のエイリアス
    • date_interval_format - DateInterval::format のエイリアス
    • date_isodate_set - DateTime::setISODate のエイリアス
    • date_modify - DateTime::modify のエイリアス
    • date_offset_get - DateTime::getOffset のエイリアス
    • date_parse - 指定した日付/時刻の詳細な情報を連想配列で返す
    • date_parse_from_format - 指定した書式でフォーマットされた日付についての情報を取得する
    • date_sub - DateTime::sub のエイリアス
    • date_sunrise - 指定した日付と場所についての日の出時刻を返す
    • date_sunset - 指定した日付と場所についての日の入り時刻を返す
    • date_sun_info - 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す
    • date_timestamp_get - DateTime::getTimestamp のエイリアス
    • date_timestamp_set - DateTime::setTimestamp のエイリアス
    • date_timezone_get - DateTime::getTimezone のエイリアス
    • date_timezone_set - DateTime::setTimezone のエイリアス
    • date_time_set - DateTime::setTime のエイリアス
    • db2_autocommit - データベース接続の AUTOCOMMIT の状態を取得または設定する
    • db2_bind_param - PHP 変数を SQL 文のパラメータにバインドする
    • db2_client_info - DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す
    • db2_close - データベース接続を閉じる
    • db2_columns - テーブルのカラムおよび関連するメタデータを含む結果セットを返す
    • db2_column_privileges - テーブルのカラムおよび関連する権限情報を含む結果セットを返す
    • db2_commit - トランザクションをコミットする
    • db2_connect - データベースへの接続を返す
    • db2_conn_error - 直近の接続から返された SQLSTATE を含む文字列を返す
    • db2_conn_errormsg - 直近の接続エラーメッセージおよび SQLCODE を返す
    • db2_cursor_type - ステートメントリソースが使用しているカーソルの型を返す
    • db2_escape_string - 特定の文字をエスケープする
    • db2_exec - SQL 文を直接実行する
    • db2_execute - プリペアドステートメントを実行する
    • db2_fetch_array - 結果セット内の行を表す、カラム位置をインデックスとする配列を返す
    • db2_fetch_assoc - 結果セット内の行を表す、カラム名をインデックスとする配列を返す
    • db2_fetch_both - 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す
    • db2_fetch_object - 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す
    • db2_fetch_row - 結果セットポインタを次の行あるいは要求された行に設定する
    • db2_field_display_size - カラムを表示するために必要な最大のバイト数を返す
    • db2_field_name - 結果セット内のカラムの名前を返す
    • db2_field_num - 結果セット内の指定したカラムの位置を返す
    • db2_field_precision - 結果セット内の指定したカラムの精度を返す
    • db2_field_scale - 結果セット内の指定したカラムの位取りを返す
    • db2_field_type - 結果セット内の指定したカラムのデータ型を返す
    • db2_field_width - 結果セット内の指定したカラムの現在値の幅を返す
    • db2_foreign_keys - テーブルの外部キーを含む結果セットを返す
    • db2_free_result - 結果セットに関連付けられたリソースを開放する
    • db2_free_stmt - 指定されたステートメントリソースに関連付けられたリソースを開放する
    • db2_get_option - ステートメントリソースあるいは接続リソースからオプションの値を取得する
    • db2_last_insert_id - この接続上で最後に成功した insert クエリが自動生成した ID を返す
    • db2_lob_read - LOB ファイルから、ユーザーが定義したサイズの内容を取得する
    • db2_next_result - ストアドプロシージャから、次の結果セットを要求する
    • db2_num_fields - 結果セットに含まれるフィールドの数を返す
    • db2_num_rows - SQL 文によって変更された行の数を返す
    • db2_pclose - 持続的データベース接続を閉じる
    • db2_pconnect - データベースへの持続的接続を返す
    • db2_prepare - 実行する SQL 文を準備する
    • db2_primary_keys - テーブルの主キーを含む結果セットを返す
    • db2_procedures - データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す
    • db2_procedure_columns - ストアドプロシージャのパラメータを含む結果セットを返す
    • db2_result - 結果セットの行からひとつのカラムを返す
    • db2_rollback - トランザクションをロールバックする
    • db2_server_info - DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す
    • db2_set_option - 接続リソースあるいはステートメントリソースのオプションを設定する
    • db2_special_columns - テーブルのユニーク行 ID カラムを含む結果セットを返す
    • db2_statistics - インデックスの情報およびテーブルの統計情報を含む結果セットを返す
    • db2_stmt_error - SQL 文が返す SQLSTATE を含む文字列を返す
    • db2_stmt_errormsg - 直近の SQL 文のエラーメッセージを含む文字列を返す
    • db2_tables - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す
    • db2_table_privileges - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す
    • dbase_add_record - Adds a record to a database
    • dbase_close - Closes a database
    • dbase_create - Creates a database
    • dbase_delete_record - Deletes a record from a database
    • dbase_get_header_info - Gets the header info of a database
    • dbase_get_record - Gets a record from a database as an indexed array
    • dbase_get_record_with_names - Gets a record from a database as an associative array
    • dbase_numfields - Gets the number of fields of a database
    • dbase_numrecords - Gets the number of records in a database
    • dbase_open - Opens a database
    • dbase_pack - Packs a database
    • dbase_replace_record - Replaces a record in a database
    • dba_close - DBA データベースを閉じる
    • dba_delete - キーが指す DBA エントリを削除する
    • dba_exists - キーが存在するかどうかを確認する
    • dba_fetch - キーが指すデータを取得する
    • dba_firstkey - 最初のキーを取得する
    • dba_handlers - 利用可能なハンドラの一覧を得る
    • dba_insert - エントリを挿入する
    • dba_key_split - 文字列形式のキーを配列形式に分割する
    • dba_list - オープンされている全データベースファイルのリストを得る
    • dba_nextkey - 次のキーを取得する
    • dba_open - データベースをオープンする
    • dba_optimize - データベースを最適化する
    • dba_popen - データベースを持続的にオープンする
    • dba_replace - エントリを置換または挿入する
    • dba_sync - データベースを同期する
    • dcgettext - 単一の参照に関するドメインを上書きする
    • dcngettext - dcgettext の複数形版
    • debug_backtrace - バックトレースを生成する
    • debug_print_backtrace - バックトレースを表示する
    • debug_zval_dump - 内部的な zval を表す文字列をダンプする
    • decbin - 10 進数を 2 進数に変換する
    • dechex - 10 進数を 16 進数に変換する
    • decoct - 10 進数を 8 進数に変換する
    • define - 名前を指定して定数を定義する
    • defined - 指定した名前の定数が存在するかどうかを調べる
    • deflate_add - インクリメンタルにデータを圧縮する
    • deflate_init - インクリメンタルな圧縮コンテキストを初期化する
    • deg2rad - 度単位の数値をラジアン単位に変換する
    • delete - unlink か unset を参照ください
    • dgettext - 現在のドメインを上書きする
    • die - exit と同等
    • dio_close - fd で指定したファイル記述子を閉じる
    • dio_fcntl - fd について C ライブラリの fcntl を実行する
    • dio_open - C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)
    • dio_read - ファイル記述子からバイトデータを読み込む
    • dio_seek - fd 上で whence から pos に移動する
    • dio_stat - ファイル記述子 fd に関する stat 情報を取得する
    • dio_tcsetattr - シリアルポートの端末属性とボーレートを設定する
    • dio_truncate - ファイル記述子 fd をオフセットバイトへ丸める
    • dio_write - オプションで丸め長さを指定してデータを書き込む
    • dir - ディレクトリクラスのインスタンスを返す
    • Directory::close - ディレクトリハンドルをクローズする
    • Directory::read - ディレクトリハンドルからエントリを読み込む
    • Directory::rewind - ディレクトリハンドルを元に戻す
    • DirectoryIterator::current - 現在の DirectoryIterator アイテムを返す
    • DirectoryIterator::getBasename - 現在の DirectoryIterator のアイテムのベース名を取得する
    • DirectoryIterator::getExtension - ファイルの拡張子を取得する
    • DirectoryIterator::getFilename - 現在の DirectoryIterator アイテムのファイル名を返す
    • DirectoryIterator::isDot - 現在の DirectoryIterator アイテムが '.' もしくは '..' であるかどうかを調べる
    • DirectoryIterator::key - 現在の DirectoryIterator アイテムのキーを返す
    • DirectoryIterator::next - 次の DirectoryIterator アイテムに移動する
    • DirectoryIterator::rewind - DirectoryIterator を最初に巻き戻す
    • DirectoryIterator::seek - DirectoryIterator のアイテムを移動する
    • DirectoryIterator::valid - 現在の DirectoryIterator の位置が有効なファイルであるかどうかチェックする
    • DirectoryIterator::__construct - パスから新規ディレクトリイテレータを生成する
    • DirectoryIterator::__toString - ファイル名を文字列として取得する
    • dirname - 親ディレクトリのパスを返す
    • diskfreespace - disk_free_space のエイリアス
    • disk_free_space - ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す
    • disk_total_space - ファイルシステムあるいはディスクパーティションの全体サイズを返す
    • dl - 実行時に PHP 拡張モジュールをロードする
    • dngettext - dgettext の複数形版
    • dns_check_record - checkdnsrr のエイリアス
    • dns_get_mx - getmxrr のエイリアス
    • dns_get_record - ホスト名に関連する DNS リソースレコードを取得する
    • DocResult::fetchAll - 全ての行を取得する
    • DocResult::fetchOne - 一行取得する
    • DocResult::getWarnings - 直近の操作から発生した警告を取得する
    • DocResult::getWarningsCount - 直近の操作で発生した警告の数を取得する
    • DocResult::__construct - DocResult のコンストラクタ
    • DOMAttr::isId - 属性が定義済みの ID かどうかを調べる
    • DOMAttr::__construct - 新しい DOMAttr オブジェクトを作成する
    • DOMCdataSection::__construct - 新しい DOMCdataSection オブジェクトを作成する
    • DOMCharacterData::after - 文字データの後ろにノードを追加する
    • DOMCharacterData::appendData - ノードの文字データの最後に文字列を追加する
    • DOMCharacterData::before - ノードの前にノードを追加する
    • DOMCharacterData::deleteData - 指定した範囲の文字列をノードから削除する
    • DOMCharacterData::insertData - 指定した 16 ビット単位のオフセットに、文字列を挿入する
    • DOMCharacterData::remove - 文字データを削除する
    • DOMCharacterData::replaceData - DOMCharacterData ノードの文字列の一部を置換する
    • DOMCharacterData::replaceWith - 文字データを新しいノードで置き換える
    • DOMCharacterData::substringData - ノードから指定した範囲のデータを抽出する
    • DOMChildNode::after - ノードの後ろにノードを追加する
    • DOMChildNode::before - ノードの前にノードを追加する
    • DOMChildNode::remove - ノードを削除する
    • DOMChildNode::replaceWith - ノードを新しいノードで置き換える
    • DOMComment::__construct - 新しい DOMComment オブジェクトを作成する
    • DOMDocument::adoptNode - ノードを別のドキュメントに移す
    • DOMDocument::append - 最後の子ノードの後ろにノードを追加する
    • DOMDocument::createAttribute - 新しい属性を作成する
    • DOMDocument::createAttributeNS - 関連付けられた名前空間に新しい属性を作成する
    • DOMDocument::createCDATASection - 新しい cdata ノードを作成する
    • DOMDocument::createComment - 新しい comment ノードを作成する
    • DOMDocument::createDocumentFragment - 新しい文書片を作成する
    • DOMDocument::createElement - 新しい要素ノードを作成する
    • DOMDocument::createElementNS - 関連付けられた名前空間に新しい要素を作成する
    • DOMDocument::createEntityReference - 新しいエンティティ参照ノードを作成する
    • DOMDocument::createProcessingInstruction - 新しい PI ノードを作成する
    • DOMDocument::createTextNode - 新しいテキストノードを作成する
    • DOMDocument::getElementById - id に対応する要素を検索する
    • DOMDocument::getElementsByTagName - 指定したローカルタグ名に対応するすべての要素を検索する
    • DOMDocument::getElementsByTagNameNS - 指定した名前空間で、タグ名に対応するすべての要素を検索する
    • DOMDocument::importNode - 現在のドキュメントにノードをインポートする
    • DOMDocument::load - ファイルから XML を読み込む
    • DOMDocument::loadHTML - 文字列から HTML を読み込む
    • DOMDocument::loadHTMLFile - ファイルから HTML を読み込む
    • DOMDocument::loadXML - 文字列から XML を読み込む
    • DOMDocument::normalizeDocument - ドキュメントを正規化する
    • DOMDocument::prepend - 最初の子ノードの前にノードを追加する
    • DOMDocument::registerNodeClass - 基底ノード型を作成する際に使用する拡張クラスを登録する
    • DOMDocument::relaxNGValidate - ドキュメントを relaxNG で検証する
    • DOMDocument::relaxNGValidateSource - ドキュメントを relaxNG で検証する
    • DOMDocument::replaceChildren - ドキュメントの子を置換する
    • DOMDocument::save - 内部の XML ツリーをファイルに出力する
    • DOMDocument::saveHTML - 内部のドキュメントを HTML 形式の文字列として出力する
    • DOMDocument::saveHTMLFile - 内部のドキュメントを HTML 形式でファイルに出力する
    • DOMDocument::saveXML - 内部の XML ツリーを文字列として出力する
    • DOMDocument::schemaValidate - スキーマに基づいてドキュメントを検証する。XML Schema 1.0 のみサポート。
    • DOMDocument::schemaValidateSource - スキーマに基づいてドキュメントを検証する
    • DOMDocument::validate - DTD に基づいてドキュメントを検証する
    • DOMDocument::xinclude - DOMDocument オブジェクト内の XIncludes を置換する
    • DOMDocument::__construct - 新しい DOMDocument オブジェクトを作成する
    • DOMDocumentFragment::append - 最後の子ノードの後ろにノードを追加する
    • DOMDocumentFragment::appendXML - 生の XML データを追加する
    • DOMDocumentFragment::prepend - 最初の子ノードの前にノードを追加する
    • DOMDocumentFragment::replaceChildren - 文書片の子を置換する
    • DOMDocumentFragment::__construct - DOMDocumentFragment オブジェクトを構築する
    • DOMElement::after - 要素の後ろにノードを追加する
    • DOMElement::append - 最後のノードの後ろにノードを追加する
    • DOMElement::before - 要素の前にノードを追加する
    • DOMElement::getAttribute - 属性の値を返す
    • DOMElement::getAttributeNames - 属性の名前を取得する
    • DOMElement::getAttributeNode - 属性ノードを返す
    • DOMElement::getAttributeNodeNS - 属性ノードを返す
    • DOMElement::getAttributeNS - 属性の値を返す
    • DOMElement::getElementsByTagName - タグ名から要素を取得する
    • DOMElement::getElementsByTagNameNS - 名前空間 URI とローカル名から要素を取得する
    • DOMElement::hasAttribute - 属性が存在するかどうかを調べる
    • DOMElement::hasAttributeNS - 属性が存在するかどうかを調べる
    • DOMElement::insertAdjacentElement - 隣接する要素を挿入する
    • DOMElement::insertAdjacentText - 隣接するテキストを挿入する
    • DOMElement::prepend - 最初の子ノードの前にノードを追加する
    • DOMElement::remove - 要素を削除する
    • DOMElement::removeAttribute - 属性を削除する
    • DOMElement::removeAttributeNode - 属性を削除する
    • DOMElement::removeAttributeNS - 属性を削除する
    • DOMElement::replaceChildren - 要素中の子を置換する
    • DOMElement::replaceWith - 要素を新しいノードで置換する
    • DOMElement::setAttribute - 属性を新しく追加する、または変更する
    • DOMElement::setAttributeNode - 新しい属性ノードを要素に追加する
    • DOMElement::setAttributeNodeNS - 新しい属性ノードを要素に追加する
    • DOMElement::setAttributeNS - 新しい属性を追加する
    • DOMElement::setIdAttribute - ID 型の属性を名前で宣言する
    • DOMElement::setIdAttributeNode - ID 型の属性をノードで宣言する
    • DOMElement::setIdAttributeNS - ID 型の属性をローカル名および名前空間 URI で宣言する
    • DOMElement::toggleAttribute - 属性の値を切り替える
    • DOMElement::__construct - 新しい DOMElement オブジェクトを作成する
    • DOMEntityReference::__construct - 新しい DOMEntityReference オブジェクトを作成する
    • DOMImplementation::createDocument - 指定した型とドキュメント要素の DOMDocument オブジェクトを作成する
    • DOMImplementation::createDocumentType - 空の DOMDocumentType オブジェクトを作成する
    • DOMImplementation::hasFeature - DOM 実装が、指定した機能を実装しているかどうかを調べる
    • DOMImplementation::__construct - 新しい DOMImplementation オブジェクトを作成する
    • DOMNamedNodeMap::count - マップにあるノードの数を取得する
    • DOMNamedNodeMap::getIterator - 外部のイテレータを取得する
    • DOMNamedNodeMap::getNamedItem - 名前で指定されたノードを取得する
    • DOMNamedNodeMap::getNamedItemNS - ローカル名および名前空間 URI で指定したノードを取得する
    • DOMNamedNodeMap::item - インデックスで指定したノードを取得する
    • DOMNode::appendChild - 子要素群の最後に新しい子要素を追加する
    • DOMNode::C14N - ノードを文字列に正規化する
    • DOMNode::C14NFile - ノードをファイルに正規化する
    • DOMNode::cloneNode - ノードを複製する
    • DOMNode::contains - ノードが別のノードを含んでいるかを調べる
    • DOMNode::getLineNo - ノードが存在する行の番号を取得します。
    • DOMNode::getNodePath - ノードの XPath を取得する
    • DOMNode::getRootNode - ルート(根)ノードを取得する
    • DOMNode::hasAttributes - ノードが属性を保持しているかどうかを調べる
    • DOMNode::hasChildNodes - ノードが子を保持しているかどうかを調べる
    • DOMNode::insertBefore - 参照しているノードの前に新しい子を追加する
    • DOMNode::isDefaultNamespace - 指定した namespaceURI がデフォルトの名前空間かどうかを調べる
    • DOMNode::isEqualNode - ノードが等しいかを調べる
    • DOMNode::isSameNode - 2 つのノードが等しいかどうかを調べる
    • DOMNode::isSupported - 指定したバージョンで機能がサポートされているかどうかを調べる
    • DOMNode::lookupNamespaceURI - プレフィックスに基づいて、ノードの名前空間 URI を取得する
    • DOMNode::lookupPrefix - 名前空間 URI に基づいて、ノードの名前空間プレフィックスを取得する
    • DOMNode::normalize - ノードを正規化する
    • DOMNode::removeChild - 子要素群から子要素を削除する
    • DOMNode::replaceChild - 子を置き換える
    • DOMNodeList::count - リストにあるノードの数を取得する
    • DOMNodeList::getIterator - 外部のイテレータを取得する
    • DOMNodelist::item - インデックスで指定したノードを取得する
    • DOMParentNode::append - 最後の子ノードの後ろにノードを追加する
    • DOMParentNode::prepend - 最初の子ノードの前にノードを追加する
    • DOMParentNode::replaceChildren - ノード中の子を置換する
    • DOMProcessingInstruction::__construct - 新しい DOMProcessingInstruction オブジェクトを作成する
    • DOMText::isElementContentWhitespace - このテキストノードが、要素の内容にホワイトスペースが含まれているかを返す
    • DOMText::isWhitespaceInElementContent - このテキストノードが空白を含むかどうかを示す
    • DOMText::splitText - 指定したオフセットでノードを 2 つに分割する
    • DOMText::__construct - 新しい DOMText オブジェクトを作成する
    • DOMXPath::evaluate - 与えられた XPath 式を評価し、可能であれば結果を返す
    • DOMXPath::query - 与えられた XPath 式を評価する
    • DOMXPath::registerNamespace - DOMXPath オブジェクトの名前空間を登録する
    • DOMXPath::registerPhpFunctions - PHP の関数を XPath 関数として登録する
    • DOMXPath::__construct - 新しい DOMXPath オブジェクトを作成する
    • dom_import_simplexml - SimpleXMLElement オブジェクトから DOMElement オブジェクトを取得する
    • dotnet::__construct - dotnet クラスのコンストラクタ
    • doubleval - floatval のエイリアス
    • Ds\Collection::clear - Removes all values
    • Ds\Collection::copy - Returns a shallow copy of the collection
    • Ds\Collection::isEmpty - Returns whether the collection is empty
    • Ds\Collection::toArray - Converts the collection to an array
    • Ds\Deque::allocate - Allocates enough memory for a required capacity
    • Ds\Deque::apply - Updates all values by applying a callback function to each value
    • Ds\Deque::capacity - Returns the current capacity
    • Ds\Deque::clear - Removes all values from the deque
    • Ds\Deque::contains - Determines if the deque contains given values
    • Ds\Deque::copy - Returns a shallow copy of the deque
    • Ds\Deque::count - Returns the number of values in the collection
    • Ds\Deque::filter - Creates a new deque using a callable to determine which values to include
    • Ds\Deque::find - Attempts to find a value's index
    • Ds\Deque::first - Returns the first value in the deque
    • Ds\Deque::get - Returns the value at a given index
    • Ds\Deque::insert - Inserts values at a given index
    • Ds\Deque::isEmpty - Returns whether the deque is empty
    • Ds\Deque::join - Joins all values together as a string
    • Ds\Deque::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Deque::last - Returns the last value
    • Ds\Deque::map - Returns the result of applying a callback to each value
    • Ds\Deque::merge - Returns the result of adding all given values to the deque
    • Ds\Deque::pop - Removes and returns the last value
    • Ds\Deque::push - Adds values to the end of the deque
    • Ds\Deque::reduce - Reduces the deque to a single value using a callback function
    • Ds\Deque::remove - Removes and returns a value by index
    • Ds\Deque::reverse - Reverses the deque in-place
    • Ds\Deque::reversed - Returns a reversed copy
    • Ds\Deque::rotate - Rotates the deque by a given number of rotations
    • Ds\Deque::set - Updates a value at a given index
    • Ds\Deque::shift - Removes and returns the first value
    • Ds\Deque::slice - Returns a sub-deque of a given range
    • Ds\Deque::sort - Sorts the deque in-place
    • Ds\Deque::sorted - Returns a sorted copy
    • Ds\Deque::sum - Returns the sum of all values in the deque
    • Ds\Deque::toArray - Converts the deque to an array
    • Ds\Deque::unshift - Adds values to the front of the deque
    • Ds\Deque::__construct - Creates a new instance
    • Ds\Hashable::equals - Determines whether an object is equal to the current instance
    • Ds\Hashable::hash - Returns a scalar value to be used as a hash value
    • Ds\Map::allocate - Allocates enough memory for a required capacity
    • Ds\Map::apply - Updates all values by applying a callback function to each value
    • Ds\Map::capacity - Returns the current capacity
    • Ds\Map::clear - Removes all values
    • Ds\Map::copy - Returns a shallow copy of the map
    • Ds\Map::count - Returns the number of values in the map
    • Ds\Map::diff - Creates a new map using keys that aren't in another map
    • Ds\Map::filter - Creates a new map using a callable to determine which pairs to include
    • Ds\Map::first - Returns the first pair in the map
    • Ds\Map::get - Returns the value for a given key
    • Ds\Map::hasKey - Determines whether the map contains a given key
    • Ds\Map::hasValue - Determines whether the map contains a given value
    • Ds\Map::intersect - Creates a new map by intersecting keys with another map
    • Ds\Map::isEmpty - Returns whether the map is empty
    • Ds\Map::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Map::keys - Returns a set of the map's keys
    • Ds\Map::ksort - Sorts the map in-place by key
    • Ds\Map::ksorted - Returns a copy, sorted by key
    • Ds\Map::last - Returns the last pair of the map
    • Ds\Map::map - Returns the result of applying a callback to each value
    • Ds\Map::merge - Returns the result of adding all given associations
    • Ds\Map::pairs - Returns a sequence containing all the pairs of the map
    • Ds\Map::put - Associates a key with a value
    • Ds\Map::putAll - Associates all key-value pairs of a traversable object or array
    • Ds\Map::reduce - Reduces the map to a single value using a callback function
    • Ds\Map::remove - Removes and returns a value by key
    • Ds\Map::reverse - Reverses the map in-place
    • Ds\Map::reversed - Returns a reversed copy
    • Ds\Map::skip - Returns the pair at a given positional index
    • Ds\Map::slice - Returns a subset of the map defined by a starting index and length
    • Ds\Map::sort - Sorts the map in-place by value
    • Ds\Map::sorted - Returns a copy, sorted by value
    • Ds\Map::sum - Returns the sum of all values in the map
    • Ds\Map::toArray - Converts the map to an array
    • Ds\Map::union - Creates a new map using values from the current instance and another map
    • Ds\Map::values - Returns a sequence of the map's values
    • Ds\Map::xor - Creates a new map using keys of either the current instance or of another map, but not of both
    • Ds\Map::__construct - Creates a new instance
    • Ds\Pair::clear - Removes all values
    • Ds\Pair::copy - Returns a shallow copy of the pair
    • Ds\Pair::isEmpty - Returns whether the pair is empty
    • Ds\Pair::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Pair::toArray - Converts the pair to an array
    • Ds\Pair::__construct - Creates a new instance
    • Ds\PriorityQueue::allocate - Allocates enough memory for a required capacity
    • Ds\PriorityQueue::capacity - Returns the current capacity
    • Ds\PriorityQueue::clear - Removes all values
    • Ds\PriorityQueue::copy - Returns a shallow copy of the queue
    • Ds\PriorityQueue::count - Returns the number of values in the queue
    • Ds\PriorityQueue::isEmpty - Returns whether the queue is empty
    • Ds\PriorityQueue::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\PriorityQueue::peek - Returns the value at the front of the queue
    • Ds\PriorityQueue::pop - Removes and returns the value with the highest priority
    • Ds\PriorityQueue::push - Pushes values into the queue
    • Ds\PriorityQueue::toArray - Converts the queue to an array
    • Ds\PriorityQueue::__construct - Creates a new instance
    • Ds\Queue::allocate - Allocates enough memory for a required capacity
    • Ds\Queue::capacity - Returns the current capacity
    • Ds\Queue::clear - Removes all values
    • Ds\Queue::copy - Returns a shallow copy of the queue
    • Ds\Queue::count - Returns the number of values in the queue
    • Ds\Queue::isEmpty - Returns whether the queue is empty
    • Ds\Queue::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Queue::peek - Returns the value at the front of the queue
    • Ds\Queue::pop - Removes and returns the value at the front of the queue
    • Ds\Queue::push - Pushes values into the queue
    • Ds\Queue::toArray - Converts the queue to an array
    • Ds\Queue::__construct - Creates a new instance
    • Ds\Sequence::allocate - Allocates enough memory for a required capacity
    • Ds\Sequence::apply - Updates all values by applying a callback function to each value
    • Ds\Sequence::capacity - Returns the current capacity
    • Ds\Sequence::contains - Determines if the sequence contains given values
    • Ds\Sequence::filter - Creates a new sequence using a callable to determine which values to include
    • Ds\Sequence::find - Attempts to find a value's index
    • Ds\Sequence::first - Returns the first value in the sequence
    • Ds\Sequence::get - Returns the value at a given index
    • Ds\Sequence::insert - Inserts values at a given index
    • Ds\Sequence::join - Joins all values together as a string
    • Ds\Sequence::last - Returns the last value
    • Ds\Sequence::map - Returns the result of applying a callback to each value
    • Ds\Sequence::merge - Returns the result of adding all given values to the sequence
    • Ds\Sequence::pop - Removes and returns the last value
    • Ds\Sequence::push - Adds values to the end of the sequence
    • Ds\Sequence::reduce - Reduces the sequence to a single value using a callback function
    • Ds\Sequence::remove - Removes and returns a value by index
    • Ds\Sequence::reverse - Reverses the sequence in-place
    • Ds\Sequence::reversed - Returns a reversed copy
    • Ds\Sequence::rotate - Rotates the sequence by a given number of rotations
    • Ds\Sequence::set - Updates a value at a given index
    • Ds\Sequence::shift - Removes and returns the first value
    • Ds\Sequence::slice - Returns a sub-sequence of a given range
    • Ds\Sequence::sort - Sorts the sequence in-place
    • Ds\Sequence::sorted - Returns a sorted copy
    • Ds\Sequence::sum - Returns the sum of all values in the sequence
    • Ds\Sequence::unshift - Adds values to the front of the sequence
    • Ds\Set::add - Adds values to the set
    • Ds\Set::allocate - Allocates enough memory for a required capacity
    • Ds\Set::capacity - Returns the current capacity
    • Ds\Set::clear - Removes all values
    • Ds\Set::contains - Determines if the set contains all values
    • Ds\Set::copy - Returns a shallow copy of the set
    • Ds\Set::count - Returns the number of values in the set
    • Ds\Set::diff - Creates a new set using values that aren't in another set
    • Ds\Set::filter - Creates a new set using a callable to determine which values to include
    • Ds\Set::first - Returns the first value in the set
    • Ds\Set::get - Returns the value at a given index
    • Ds\Set::intersect - Creates a new set by intersecting values with another set
    • Ds\Set::isEmpty - Returns whether the set is empty
    • Ds\Set::join - Joins all values together as a string
    • Ds\Set::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Set::last - Returns the last value in the set
    • Ds\Set::merge - Returns the result of adding all given values to the set
    • Ds\Set::reduce - Reduces the set to a single value using a callback function
    • Ds\Set::remove - Removes all given values from the set
    • Ds\Set::reverse - Reverses the set in-place
    • Ds\Set::reversed - Returns a reversed copy
    • Ds\Set::slice - Returns a sub-set of a given range
    • Ds\Set::sort - Sorts the set in-place
    • Ds\Set::sorted - Returns a sorted copy
    • Ds\Set::sum - Returns the sum of all values in the set
    • Ds\Set::toArray - Converts the set to an array
    • Ds\Set::union - Creates a new set using values from the current instance and another set
    • Ds\Set::xor - Creates a new set using values in either the current instance or in another set, but not in both
    • Ds\Set::__construct - Creates a new instance
    • Ds\Stack::allocate - Allocates enough memory for a required capacity
    • Ds\Stack::capacity - Returns the current capacity
    • Ds\Stack::clear - Removes all values
    • Ds\Stack::copy - Returns a shallow copy of the stack
    • Ds\Stack::count - Returns the number of values in the stack
    • Ds\Stack::isEmpty - Returns whether the stack is empty
    • Ds\Stack::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Stack::peek - Returns the value at the top of the stack
    • Ds\Stack::pop - Removes and returns the value at the top of the stack
    • Ds\Stack::push - Pushes values onto the stack
    • Ds\Stack::toArray - Converts the stack to an array
    • Ds\Stack::__construct - Creates a new instance
    • Ds\Vector::allocate - Allocates enough memory for a required capacity
    • Ds\Vector::apply - Updates all values by applying a callback function to each value
    • Ds\Vector::capacity - Returns the current capacity
    • Ds\Vector::clear - Removes all values
    • Ds\Vector::contains - Determines if the vector contains given values
    • Ds\Vector::copy - Returns a shallow copy of the vector
    • Ds\Vector::count - Returns the number of values in the collection
    • Ds\Vector::filter - Creates a new vector using a callable to determine which values to include
    • Ds\Vector::find - Attempts to find a value's index
    • Ds\Vector::first - Returns the first value in the vector
    • Ds\Vector::get - Returns the value at a given index
    • Ds\Vector::insert - Inserts values at a given index
    • Ds\Vector::isEmpty - Returns whether the vector is empty
    • Ds\Vector::join - Joins all values together as a string
    • Ds\Vector::jsonSerialize - Returns a representation that can be converted to JSON
    • Ds\Vector::last - Returns the last value
    • Ds\Vector::map - Returns the result of applying a callback to each value
    • Ds\Vector::merge - Returns the result of adding all given values to the vector
    • Ds\Vector::pop - Removes and returns the last value
    • Ds\Vector::push - Adds values to the end of the vector
    • Ds\Vector::reduce - Reduces the vector to a single value using a callback function
    • Ds\Vector::remove - Removes and returns a value by index
    • Ds\Vector::reverse - Reverses the vector in-place
    • Ds\Vector::reversed - Returns a reversed copy
    • Ds\Vector::rotate - Rotates the vector by a given number of rotations
    • Ds\Vector::set - Updates a value at a given index
    • Ds\Vector::shift - Removes and returns the first value
    • Ds\Vector::slice - Returns a sub-vector of a given range
    • Ds\Vector::sort - Sorts the vector in-place
    • Ds\Vector::sorted - Returns a sorted copy
    • Ds\Vector::sum - Returns the sum of all values in the vector
    • Ds\Vector::toArray - Converts the vector to an array
    • Ds\Vector::unshift - Adds values to the front of the vector
    • Ds\Vector::__construct - Creates a new instance
  • e
    • each - 配列から現在のキーと値のペアを返して、カーソルを進める
    • easter_date - 指定した年における復活祭の真夜中のUnix時を得る
    • easter_days - 指定した年において、3 月 21 日から復活祭までの日数を得る
    • echo - 1 つ以上の文字列を出力する
    • eio_busy - 人為的に負荷を高くする。テストやベンチマークなどで有用
    • eio_cancel - リクエストを取り消す
    • eio_chmod - ファイルやディレクトリのパーミッションを変更する
    • eio_chown - ファイルやディレクトリのオーナーを変更する
    • eio_close - ファイルを閉じる
    • eio_custom - eio_* のようなカスタムリクエストを実行する
    • eio_dup2 - ファイルディスクリプタを複製する
    • eio_event_loop - すべてのリクエストを処理し終えるまで libeio をポールする
    • eio_fallocate - 呼び出し元が、ファイルに割り当てられたディスク空間を直接操作できるようにする
    • eio_fchmod - ファイルのパーミッションを変更する
    • eio_fchown - ファイルのオーナーを変更する
    • eio_fdatasync - ファイルのコア内の情報をストレージデバイスに同期させる
    • eio_fstat - ファイルの状態を取得する
    • eio_fstatvfs - ファイルシステムの状態を取得する
    • eio_fsync - メモリ内でのファイルの状態をストレージデバイスに同期させる
    • eio_ftruncate - ファイルを切り詰める
    • eio_futime - ファイルの最終アクセス時刻と変更時刻を変更する
    • eio_get_event_stream - 内部での libeio との通信に使う変数を表すストリームを取得する
    • eio_get_last_error - リクエストリソースに関連づけられた直近のエラーの説明を文字列で返す
    • eio_grp - リクエストグループを作る
    • eio_grp_add - リクエストをリクエストグループに追加する
    • eio_grp_cancel - リクエストグループをキャンセルする
    • eio_grp_limit - グループリミットを設定する
    • eio_init - Eio を初期化する
    • eio_link - ファイルのハードリンクを作る
    • eio_lstat - ファイルの状態を取得する
    • eio_mkdir - ディレクトリを作る
    • eio_mknod - 特殊ファイルあるいは一般ファイルを作る
    • eio_nop - 何もせず、ただリクエストのサイクルを回す
    • eio_npending - 終了したけれども処理されなかったリクエストの数を返す
    • eio_nready - 未処理のリクエスト数を返す
    • eio_nreqs - 処理対象のリクエスト数を返す
    • eio_nthreads - 現在利用中のスレッド数を返す
    • eio_open - ファイルを開く
    • eio_poll - 未処理のリクエストがあるかどうかを調べる
    • eio_read - ファイルを、指定したオフセットから読み込む
    • eio_readahead - ファイルを先読みしてページキャッシュに格納する
    • eio_readdir - ディレクトリ全体を読み込む
    • eio_readlink - シンボリックリンクの値を読む
    • eio_realpath - 正規化された絶対パスを取得する
    • eio_rename - ファイル名や場所を変更する
    • eio_rmdir - ディレクトリを削除する
    • eio_seek - fd で指定したファイル内でのオフセットを、offset と whence に従って移動する
    • eio_sendfile - ファイルディスクリプタ間でデータを転送する
    • eio_set_max_idle - アイドルスレッドの最大数を設定する
    • eio_set_max_parallel - 最大の並列スレッド数を設定する
    • eio_set_max_poll_reqs - 一度のポールで行う最大のリクエスト回数を設定する
    • eio_set_max_poll_time - 最大のポール時間を設定する
    • eio_set_min_parallel - 最小の並列スレッド数を設定する
    • eio_stat - ファイルの状態を取得する
    • eio_statvfs - ファイルシステムの状態を取得する
    • eio_symlink - シンボリックリンクを作る
    • eio_sync - バッファのキャッシュをディスクに書き込む
    • eio_syncfs - Linux の syncfs システムコールが使えれば、それを呼ぶ
    • eio_sync_file_range - ファイルセグメントをディスクに同期する
    • eio_truncate - ファイルを切り詰める
    • eio_unlink - 名前を削除し、その名前で参照しているファイルも削除する
    • eio_utime - ファイルの最終アクセス時刻と変更時刻を変更する
    • eio_write - ファイルに書き込む
    • empty - 変数が空であるかどうかを検査する
    • EmptyIterator::current - current() メソッド
    • EmptyIterator::key - key() メソッド
    • EmptyIterator::next - next() メソッド
    • EmptyIterator::rewind - rewind() メソッド
    • EmptyIterator::valid - 現在の要素が有効かどうかを調べる
    • enchant_broker_describe - Enchant プロバイダを列挙する
    • enchant_broker_dict_exists - 辞書が存在するかどうかを調べる。空でないタグを使用する
    • enchant_broker_free - ブローカーリソースおよびその辞書を開放する
    • enchant_broker_free_dict - 辞書リソースを開放する
    • enchant_broker_get_dict_path - 指定されたバックエンドの辞書のパスを取得する
    • enchant_broker_get_error - ブローカーの直近のエラーを返す
    • enchant_broker_init - 要求を満たすブローカーオブジェクトを作成する
    • enchant_broker_list_dicts - 使用可能な辞書の一覧を返す
    • enchant_broker_request_dict - タグを使用して新しい辞書を作成する
    • enchant_broker_request_pwl_dict - PWL ファイルを使用して辞書を作成する
    • enchant_broker_set_dict_path - 指定されたバックエンドの辞書のパスを設定する
    • enchant_broker_set_ordering - その言語で使用する辞書の優先順位を宣言する
    • enchant_dict_add - 単語リストに単語を追加する
    • enchant_dict_add_to_personal - のエイリアス enchant_dict_add
    • enchant_dict_add_to_session - '単語' を、このスペルチェックセッションに追加する
    • enchant_dict_check - 単語のスペルが正しいかどうかを調べる
    • enchant_dict_describe - 個々の辞書について説明する
    • enchant_dict_get_error - 現在のスペリングセッションの直近のエラーを返す
    • enchant_dict_is_added - 現在のセッションに、単語が存在するかどうかを調べる
    • enchant_dict_is_in_session - のエイリアス enchant_dict_is_added
    • enchant_dict_quick_check - 単語のスペルが正しいかどうかを調べ、修正候補を提供する
    • enchant_dict_store_replacement - 単語の修正候補を追加する
    • enchant_dict_suggest - 修正候補となる値の一覧を返す
    • end - 配列の内部ポインタを最終要素にセットする
    • enum_exists - 列挙型が定義されているかを調べる
    • Error::getCode - エラーコードを取得する
    • Error::getFile - エラーが起きたファイルを取得する
    • Error::getLine - エラーが起きた行番号を取得する
    • Error::getMessage - エラーメッセージを取得する
    • Error::getPrevious - 直前の Throwable を返す
    • Error::getTrace - スタックトレースを取得する
    • Error::getTraceAsString - スタックトレースを文字列として取得する
    • Error::__clone - エラーをクローンする
    • Error::__construct - エラーオブジェクトを生成する
    • Error::__toString - エラーの文字列表現
    • ErrorException::getSeverity - 例外の深刻度を取得する
    • ErrorException::__construct - 例外を作成する
    • error_clear_last - 最も最近のエラーをクリア
    • error_get_last - 最後に発生したエラーを取得する
    • error_log - 定義されたエラー処理ルーチンにエラーメッセージを送信する
    • error_reporting - 出力する PHP エラーの種類を設定する
    • escapeshellarg - シェル引数として使用される文字列をエスケープする
    • escapeshellcmd - シェルのメタ文字をエスケープする
    • Ev::backend - libev が使うバックエンドを表す整数値を返す
    • Ev::depth - 再帰の深さを返す
    • Ev::embeddableBackends - 他のイベントループに埋め込めるバックエンド群を返す
    • Ev::feedSignal - シグナルイベントを Ev に送る
    • Ev::feedSignalEvent - シグナルイベントの情報をデフォルトループに送る
    • Ev::iteration - デフォルトのイベントループが新しいイベントをポーリングした回数を返す
    • Ev::now - デフォルトのイベントループで直近の処理が始まった時刻を返す
    • Ev::nowUpdate - カーネルに問い合わせて現在時刻を確認し、処理中の Ev::now が返す時刻を更新する
    • Ev::recommendedBackends - 現在のプラットフォーム上でおすすめのバックエンドのビットマスクを返す
    • Ev::resume - 一時停止していたデフォルトのイベントループを再開させる
    • Ev::run - イベントのチェックとデフォルトループのコールバックの呼び出しを開始する
    • Ev::sleep - 指定した秒数だけプロセスをブロックする
    • Ev::stop - デフォルトのイベントループを止める
    • Ev::supportedBackends - 現在の libev の構成でサポートするバックエンド群を返す
    • Ev::suspend - デフォルトのイベントループを一時停止する
    • Ev::time - epoch から現在時刻までの秒数を返す
    • Ev::verify - 内部の整合性をチェックする (デバッグ用)
    • eval - 文字列を PHP コードとして評価する
    • EvCheck::createStopped - 停止した EvCheck ウォッチャーのインスタンスを作る
    • EvCheck::__construct - EvCheck ウォッチャーオブジェクトを作る
    • EvChild::createStopped - 停止した EvChild ウォッチャーのインスタンスを作る
    • EvChild::set - ウォッチャーを設定する
    • EvChild::__construct - EvChild ウォッチャーオブジェクトを作る
    • EvEmbed::createStopped - 停止した EvEmbed ウォッチャーのインスタンスを作る
    • EvEmbed::set - ウォッチャーを設定する
    • EvEmbed::sweep - 埋め込んだループに対して単一の非ブロックスイープを行う
    • EvEmbed::__construct - EvEmbed オブジェクトを作る
    • Event::add - Makes event pending
    • Event::addSignal - のエイリアス Event::add
    • Event::addTimer - のエイリアス Event::add
    • Event::del - Makes event non-pending
    • Event::delSignal - のエイリアス Event::del
    • Event::delTimer - のエイリアス Event::del
    • Event::free - Make event non-pending and free resources allocated for this event
    • Event::getSupportedMethods - Returns array with of the names of the methods supported in this version of Libevent
    • Event::pending - Detects whether event is pending or scheduled
    • Event::set - Re-configures event
    • Event::setPriority - Set event priority
    • Event::setTimer - Re-configures timer event
    • Event::signal - Constructs signal event object
    • Event::timer - Constructs timer event object
    • Event::__construct - Constructs Event object
    • EventBase::dispatch - Dispatch pending events
    • EventBase::exit - Stop dispatching events
    • EventBase::free - Free resources allocated for this event base
    • EventBase::getFeatures - Returns bitmask of features supported
    • EventBase::getMethod - Returns event method in use
    • EventBase::getTimeOfDayCached - Returns the current event base time
    • EventBase::gotExit - Checks if the event loop was told to exit
    • EventBase::gotStop - Checks if the event loop was told to exit
    • EventBase::loop - Dispatch pending events
    • EventBase::priorityInit - Sets number of priorities per event base
    • EventBase::reInit - Re-initialize event base(after a fork)
    • EventBase::stop - Tells event_base to stop dispatching events
    • EventBase::__construct - Constructs EventBase object
    • EventBuffer::add - Append data to the end of an event buffer
    • EventBuffer::addBuffer - Move all data from a buffer provided to the current instance of EventBuffer
    • EventBuffer::appendFrom - Moves the specified number of bytes from a source buffer to the end of the current buffer
    • EventBuffer::copyout - Copies out specified number of bytes from the front of the buffer
    • EventBuffer::drain - Removes specified number of bytes from the front of the buffer without copying it anywhere
    • EventBuffer::enableLocking - 説明
    • EventBuffer::expand - Reserves space in buffer
    • EventBuffer::freeze - Prevent calls that modify an event buffer from succeeding
    • EventBuffer::lock - Acquires a lock on buffer
    • EventBuffer::prepend - Prepend data to the front of the buffer
    • EventBuffer::prependBuffer - Moves all data from source buffer to the front of current buffer
    • EventBuffer::pullup - Linearizes data within buffer and returns it's contents as a string
    • EventBuffer::read - Read data from an evbuffer and drain the bytes read
    • EventBuffer::readFrom - Read data from a file onto the end of the buffer
    • EventBuffer::readLine - Extracts a line from the front of the buffer
    • EventBuffer::search - Scans the buffer for an occurrence of a string
    • EventBuffer::searchEol - Scans the buffer for an occurrence of an end of line
    • EventBuffer::substr - Substracts a portion of the buffer data
    • EventBuffer::unfreeze - Re-enable calls that modify an event buffer
    • EventBuffer::unlock - Releases lock acquired by EventBuffer::lock
    • EventBuffer::write - Write contents of the buffer to a file or socket
    • EventBuffer::__construct - Constructs EventBuffer object
    • EventBufferEvent::close - Closes file descriptor associated with the current buffer event
    • EventBufferEvent::connect - Connect buffer event's file descriptor to given address or UNIX socket
    • EventBufferEvent::connectHost - Connects to a hostname with optionally asyncronous DNS resolving
    • EventBufferEvent::createPair - Creates two buffer events connected to each other
    • EventBufferEvent::disable - Disable events read, write, or both on a buffer event
    • EventBufferEvent::enable - Enable events read, write, or both on a buffer event
    • EventBufferEvent::free - Free a buffer event
    • EventBufferEvent::getDnsErrorString - Returns string describing the last failed DNS lookup attempt
    • EventBufferEvent::getEnabled - Returns bitmask of events currently enabled on the buffer event
    • EventBufferEvent::getInput - Returns underlying input buffer associated with current buffer event
    • EventBufferEvent::getOutput - Returns underlying output buffer associated with current buffer event
    • EventBufferEvent::read - Read buffer's data
    • EventBufferEvent::readBuffer - Drains the entire contents of the input buffer and places them into buf
    • EventBufferEvent::setCallbacks - Assigns read, write and event(status) callbacks
    • EventBufferEvent::setPriority - Assign a priority to a bufferevent
    • EventBufferEvent::setTimeouts - Set the read and write timeout for a buffer event
    • EventBufferEvent::setWatermark - Adjusts read and/or write watermarks
    • EventBufferEvent::sslError - Returns most recent OpenSSL error reported on the buffer event
    • EventBufferEvent::sslFilter - Create a new SSL buffer event to send its data over another buffer event
    • EventBufferEvent::sslGetCipherInfo - Returns a textual description of the cipher
    • EventBufferEvent::sslGetCipherName - Returns the current cipher name of the SSL connection
    • EventBufferEvent::sslGetCipherVersion - Returns version of cipher used by current SSL connection
    • EventBufferEvent::sslGetProtocol - Returns the name of the protocol used for current SSL connection
    • EventBufferEvent::sslRenegotiate - Tells a bufferevent to begin SSL renegotiation
    • EventBufferEvent::sslSocket - Creates a new SSL buffer event to send its data over an SSL on a socket
    • EventBufferEvent::write - Adds data to a buffer event's output buffer
    • EventBufferEvent::writeBuffer - Adds contents of the entire buffer to a buffer event's output buffer
    • EventBufferEvent::__construct - Constructs EventBufferEvent object
    • EventConfig::avoidMethod - Tells libevent to avoid specific event method
    • EventConfig::requireFeatures - Enters a required event method feature that the application demands
    • EventConfig::setFlags - Sets one or more flags to configure the eventual EventBase will be initialized
    • EventConfig::setMaxDispatchInterval - Prevents priority inversion
    • EventConfig::__construct - Constructs EventConfig object
    • EventDnsBase::addNameserverIp - Adds a nameserver to the DNS base
    • EventDnsBase::addSearch - Adds a domain to the list of search domains
    • EventDnsBase::clearSearch - Removes all current search suffixes
    • EventDnsBase::countNameservers - Gets the number of configured nameservers
    • EventDnsBase::loadHosts - Loads a hosts file (in the same format as /etc/hosts) from hosts file
    • EventDnsBase::parseResolvConf - Scans the resolv.conf-formatted file
    • EventDnsBase::setOption - Set the value of a configuration option
    • EventDnsBase::setSearchNdots - Set the 'ndots' parameter for searches
    • EventDnsBase::__construct - Constructs EventDnsBase object
    • EventHttp::accept - Makes an HTTP server accept connections on the specified socket stream or resource
    • EventHttp::addServerAlias - Adds a server alias to the HTTP server object
    • EventHttp::bind - Binds an HTTP server on the specified address and port
    • EventHttp::removeServerAlias - Removes server alias
    • EventHttp::setAllowedMethods - Sets the what HTTP methods are supported in requests accepted by this server, and passed to user callbacks
    • EventHttp::setCallback - Sets a callback for specified URI
    • EventHttp::setDefaultCallback - Sets default callback to handle requests that are not caught by specific callbacks
    • EventHttp::setMaxBodySize - Sets maximum request body size
    • EventHttp::setMaxHeadersSize - Sets maximum HTTP header size
    • EventHttp::setTimeout - Sets the timeout for an HTTP request
    • EventHttp::__construct - Constructs EventHttp object (the HTTP server)
    • EventHttpConnection::getBase - Returns event base associated with the connection
    • EventHttpConnection::getPeer - Gets the remote address and port associated with the connection
    • EventHttpConnection::makeRequest - Makes an HTTP request over the specified connection
    • EventHttpConnection::setCloseCallback - Set callback for connection close
    • EventHttpConnection::setLocalAddress - Sets the IP address from which HTTP connections are made
    • EventHttpConnection::setLocalPort - Sets the local port from which connections are made
    • EventHttpConnection::setMaxBodySize - Sets maximum body size for the connection
    • EventHttpConnection::setMaxHeadersSize - Sets maximum header size
    • EventHttpConnection::setRetries - Sets the retry limit for the connection
    • EventHttpConnection::setTimeout - Sets the timeout for the connection
    • EventHttpConnection::__construct - Constructs EventHttpConnection object
    • EventHttpRequest::addHeader - Adds an HTTP header to the headers of the request
    • EventHttpRequest::cancel - Cancels a pending HTTP request
    • EventHttpRequest::clearHeaders - Removes all output headers from the header list of the request
    • EventHttpRequest::closeConnection - Closes associated HTTP connection
    • EventHttpRequest::findHeader - Finds the value belonging a header
    • EventHttpRequest::free - Frees the object and removes associated events
    • EventHttpRequest::getBufferEvent - Returns EventBufferEvent object
    • EventHttpRequest::getCommand - Returns the request command(method)
    • EventHttpRequest::getConnection - Returns EventHttpConnection object
    • EventHttpRequest::getHost - Returns the request host
    • EventHttpRequest::getInputBuffer - Returns the input buffer
    • EventHttpRequest::getInputHeaders - Returns associative array of the input headers
    • EventHttpRequest::getOutputBuffer - Returns the output buffer of the request
    • EventHttpRequest::getOutputHeaders - Returns associative array of the output headers
    • EventHttpRequest::getResponseCode - Returns the response code
    • EventHttpRequest::getUri - Returns the request URI
    • EventHttpRequest::removeHeader - Removes an HTTP header from the headers of the request
    • EventHttpRequest::sendError - Send an HTML error message to the client
    • EventHttpRequest::sendReply - Send an HTML reply to the client
    • EventHttpRequest::sendReplyChunk - Send another data chunk as part of an ongoing chunked reply
    • EventHttpRequest::sendReplyEnd - Complete a chunked reply, freeing the request as appropriate
    • EventHttpRequest::sendReplyStart - Initiate a chunked reply
    • EventHttpRequest::__construct - Constructs EventHttpRequest object
    • EventListener::disable - Disables an event connect listener object
    • EventListener::enable - Enables an event connect listener object
    • EventListener::getBase - Returns event base associated with the event listener
    • EventListener::getSocketName - Retreives the current address to which the listener's socket is bound
    • EventListener::setCallback - The setCallback purpose
    • EventListener::setErrorCallback - Set event listener's error callback
    • EventListener::__construct - Creates new connection listener associated with an event base
    • EventSslContext::__construct - Constructs an OpenSSL context for use with Event classes
    • EventUtil::getLastSocketErrno - Returns the most recent socket error number
    • EventUtil::getLastSocketError - Returns the most recent socket error
    • EventUtil::getSocketFd - Returns numeric file descriptor of a socket, or stream
    • EventUtil::getSocketName - Retreives the current address to which the socket is bound
    • EventUtil::setSocketOption - Sets socket options
    • EventUtil::sslRandPoll - Generates entropy by means of OpenSSL's RAND_poll()
    • EventUtil::__construct - The abstract constructor
    • EvFork::createStopped - 停止した EvFork ウォッチャーのインスタンスを作る
    • EvFork::__construct - EvFork ウォッチャーオブジェクトを作る
    • EvIdle::createStopped - Creates instance of a stopped EvIdle watcher object
    • EvIdle::__construct - Constructs the EvIdle watcher object
    • EvIo::createStopped - Create stopped EvIo watcher object
    • EvIo::set - Configures the watcher
    • EvIo::__construct - Constructs EvIo watcher object
    • EvLoop::backend - Returns an integer describing the backend used by libev
    • EvLoop::check - Creates EvCheck object associated with the current event loop instance
    • EvLoop::child - Creates EvChild object associated with the current event loop
    • EvLoop::defaultLoop - Returns or creates the default event loop
    • EvLoop::embed - Creates an instance of EvEmbed watcher associated with the current EvLoop object
    • EvLoop::fork - Creates EvFork watcher object associated with the current event loop instance
    • EvLoop::idle - Creates EvIdle watcher object associated with the current event loop instance
    • EvLoop::invokePending - Invoke all pending watchers while resetting their pending state
    • EvLoop::io - Create EvIo watcher object associated with the current event loop instance
    • EvLoop::loopFork - Must be called after a fork
    • EvLoop::now - Returns the current "event loop time"
    • EvLoop::nowUpdate - Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress
    • EvLoop::periodic - Creates EvPeriodic watcher object associated with the current event loop instance
    • EvLoop::prepare - Creates EvPrepare watcher object associated with the current event loop instance
    • EvLoop::resume - Resume previously suspended default event loop
    • EvLoop::run - Begin checking for events and calling callbacks for the loop
    • EvLoop::signal - Creates EvSignal watcher object associated with the current event loop instance
    • EvLoop::stat - Creates EvStat watcher object associated with the current event loop instance
    • EvLoop::stop - Stops the event loop
    • EvLoop::suspend - Suspend the loop
    • EvLoop::timer - Creates EvTimer watcher object associated with the current event loop instance
    • EvLoop::verify - Performs internal consistency checks(for debugging)
    • EvLoop::__construct - Constructs the event loop object
    • EvPeriodic::again - Simply stops and restarts the periodic watcher again
    • EvPeriodic::at - Returns the absolute time that this watcher is supposed to trigger next
    • EvPeriodic::createStopped - Create a stopped EvPeriodic watcher
    • EvPeriodic::set - Configures the watcher
    • EvPeriodic::__construct - Constructs EvPeriodic watcher object
    • EvPrepare::createStopped - 停止した EvPrepare ウォッチャーのインスタンスを作る
    • EvPrepare::__construct - EvPrepare ウォッチャーオブジェクトを作る
    • EvSignal::createStopped - Create stopped EvSignal watcher object
    • EvSignal::set - Configures the watcher
    • EvSignal::__construct - Constructs EvSignal watcher object
    • EvStat::attr - Returns the values most recently detected by Ev
    • EvStat::createStopped - Create a stopped EvStat watcher object
    • EvStat::prev - Returns the previous set of values returned by EvStat::attr
    • EvStat::set - Configures the watcher
    • EvStat::stat - Initiates the stat call
    • EvStat::__construct - Constructs EvStat watcher object
    • EvTimer::again - Restarts the timer watcher
    • EvTimer::createStopped - Creates EvTimer stopped watcher object
    • EvTimer::set - Configures the watcher
    • EvTimer::__construct - Constructs an EvTimer watcher object
    • EvWatcher::clear - Clear watcher pending status
    • EvWatcher::feed - Feeds the given revents set into the event loop
    • EvWatcher::getLoop - Returns the loop responsible for the watcher
    • EvWatcher::invoke - Invokes the watcher callback with the given received events bit mask
    • EvWatcher::keepalive - Configures whether to keep the loop from returning
    • EvWatcher::setCallback - Sets new callback for the watcher
    • EvWatcher::start - Starts the watcher
    • EvWatcher::stop - Stops the watcher
    • EvWatcher::__construct - Abstract constructor of a watcher object
    • Exception::getCode - 例外コードを取得する
    • Exception::getFile - 例外が作られたファイルを取得する
    • Exception::getLine - 例外が作られた行を取得する
    • Exception::getMessage - 例外メッセージを取得する
    • Exception::getPrevious - 前の例外(Throwable)を返す
    • Exception::getTrace - スタックトレースを取得する
    • Exception::getTraceAsString - スタックトレースを文字列で取得する
    • Exception::__clone - 例外をコピーする
    • Exception::__construct - 例外を作成する
    • Exception::__toString - 例外の文字列表現
    • exec - 外部プログラムを実行する
    • Executable::execute - ステートメントを実行する
    • ExecutionStatus::__construct - ExecutionStatus のコンストラクタ
    • exif_imagetype - イメージの型を定義する
    • exif_read_data - 画像ファイルから EXIF ヘッダを読み込む
    • exif_tagname - インデックスに対応するヘッダ名を取得する
    • exif_thumbnail - 画像に埋め込まれたサムネイルを取得する
    • exit - メッセージを出力し、現在のスクリプトを終了する
    • exp - e の累乗を計算する
    • expect_expectl - プロセスの出力がパターンに一致する・指定した時間が経過する・ あるいは EOF に達するのいずれかにあてはまるまで待ち続ける
    • expect_popen - Bourne シェル経由でコマンドを実行し、プロセスへの PTY ストリームをオープンする
    • explode - 文字列を文字列により分割する
    • expm1 - 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す
    • expression - プリペアドステートメントの変数をパラメータとしてバインドする
    • Expression::__construct - Expression のコンストラクタ
    • extension_loaded - ある拡張モジュールがロードされているかどうかを調べる
    • extract - 配列からシンボルテーブルに変数をインポートする
    • ezmlm_hash - EZMLM で必要なハッシュ値を計算する
  • f
    • FANNConnection::getFromNeuron - Returns the postions of starting neuron
    • FANNConnection::getToNeuron - Returns the postions of terminating neuron
    • FANNConnection::getWeight - Returns the connection weight
    • FANNConnection::setWeight - Sets the connections weight
    • FANNConnection::__construct - The connection constructor
    • fann_cascadetrain_on_data - Trains on an entire dataset, for a period of time using the Cascade2 training algorithm
    • fann_cascadetrain_on_file - Trains on an entire dataset read from file, for a period of time using the Cascade2 training algorithm
    • fann_clear_scaling_params - Clears scaling parameters
    • fann_copy - Creates a copy of a fann structure
    • fann_create_from_file - Constructs a backpropagation neural network from a configuration file
    • fann_create_shortcut - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
    • fann_create_shortcut_array - Creates a standard backpropagation neural network which is not fully connectected and has shortcut connections
    • fann_create_sparse - Creates a standard backpropagation neural network, which is not fully connected
    • fann_create_sparse_array - Creates a standard backpropagation neural network, which is not fully connected using an array of layer sizes
    • fann_create_standard - Creates a standard fully connected backpropagation neural network
    • fann_create_standard_array - Creates a standard fully connected backpropagation neural network using an array of layer sizes
    • fann_create_train - Creates an empty training data struct
    • fann_create_train_from_callback - Creates the training data struct from a user supplied function
    • fann_descale_input - Scale data in input vector after get it from ann based on previously calculated parameters
    • fann_descale_output - Scale data in output vector after get it from ann based on previously calculated parameters
    • fann_descale_train - Descale input and output data based on previously calculated parameters
    • fann_destroy - Destroys the entire network and properly freeing all the associated memory
    • fann_destroy_train - Destructs the training data
    • fann_duplicate_train_data - Returns an exact copy of a fann train data
    • fann_get_activation_function - Returns the activation function
    • fann_get_activation_steepness - Returns the activation steepness for supplied neuron and layer number
    • fann_get_bias_array - Get the number of bias in each layer in the network
    • fann_get_bit_fail - The number of fail bits
    • fann_get_bit_fail_limit - Returns the bit fail limit used during training
    • fann_get_cascade_activation_functions - Returns the cascade activation functions
    • fann_get_cascade_activation_functions_count - Returns the number of cascade activation functions
    • fann_get_cascade_activation_steepnesses - Returns the cascade activation steepnesses
    • fann_get_cascade_activation_steepnesses_count - The number of activation steepnesses
    • fann_get_cascade_candidate_change_fraction - Returns the cascade candidate change fraction
    • fann_get_cascade_candidate_limit - Return the candidate limit
    • fann_get_cascade_candidate_stagnation_epochs - Returns the number of cascade candidate stagnation epochs
    • fann_get_cascade_max_cand_epochs - Returns the maximum candidate epochs
    • fann_get_cascade_max_out_epochs - Returns the maximum out epochs
    • fann_get_cascade_min_cand_epochs - Returns the minimum candidate epochs
    • fann_get_cascade_min_out_epochs - Returns the minimum out epochs
    • fann_get_cascade_num_candidates - Returns the number of candidates used during training
    • fann_get_cascade_num_candidate_groups - Returns the number of candidate groups
    • fann_get_cascade_output_change_fraction - Returns the cascade output change fraction
    • fann_get_cascade_output_stagnation_epochs - Returns the number of cascade output stagnation epochs
    • fann_get_cascade_weight_multiplier - Returns the weight multiplier
    • fann_get_connection_array - Get connections in the network
    • fann_get_connection_rate - Get the connection rate used when the network was created
    • fann_get_errno - Returns the last error number
    • fann_get_errstr - Returns the last errstr
    • fann_get_layer_array - Get the number of neurons in each layer in the network
    • fann_get_learning_momentum - Returns the learning momentum
    • fann_get_learning_rate - Returns the learning rate
    • fann_get_MSE - Reads the mean square error from the network
    • fann_get_network_type - Get the type of neural network it was created as
    • fann_get_num_input - Get the number of input neurons
    • fann_get_num_layers - Get the number of layers in the neural network
    • fann_get_num_output - Get the number of output neurons
    • fann_get_quickprop_decay - Returns the decay which is a factor that weights should decrease in each iteration during quickprop training
    • fann_get_quickprop_mu - Returns the mu factor
    • fann_get_rprop_decrease_factor - Returns the increase factor used during RPROP training
    • fann_get_rprop_delta_max - Returns the maximum step-size
    • fann_get_rprop_delta_min - Returns the minimum step-size
    • fann_get_rprop_delta_zero - Returns the initial step-size
    • fann_get_rprop_increase_factor - Returns the increase factor used during RPROP training
    • fann_get_sarprop_step_error_shift - Returns the sarprop step error shift
    • fann_get_sarprop_step_error_threshold_factor - Returns the sarprop step error threshold factor
    • fann_get_sarprop_temperature - Returns the sarprop temperature
    • fann_get_sarprop_weight_decay_shift - Returns the sarprop weight decay shift
    • fann_get_total_connections - Get the total number of connections in the entire network
    • fann_get_total_neurons - Get the total number of neurons in the entire network
    • fann_get_training_algorithm - Returns the training algorithm
    • fann_get_train_error_function - Returns the error function used during training
    • fann_get_train_stop_function - Returns the stop function used during training
    • fann_init_weights - Initialize the weights using Widrow + Nguyen’s algorithm
    • fann_length_train_data - Returns the number of training patterns in the train data
    • fann_merge_train_data - Merges the train data
    • fann_num_input_train_data - Returns the number of inputs in each of the training patterns in the train data
    • fann_num_output_train_data - Returns the number of outputs in each of the training patterns in the train data
    • fann_print_error - Prints the error string
    • fann_randomize_weights - Give each connection a random weight between min_weight and max_weight
    • fann_read_train_from_file - Reads a file that stores training data
    • fann_reset_errno - Resets the last error number
    • fann_reset_errstr - Resets the last error string
    • fann_reset_MSE - Resets the mean square error from the network
    • fann_run - Will run input through the neural network
    • fann_save - Saves the entire network to a configuration file
    • fann_save_train - Save the training structure to a file
    • fann_scale_input - Scale data in input vector before feed it to ann based on previously calculated parameters
    • fann_scale_input_train_data - Scales the inputs in the training data to the specified range
    • fann_scale_output - Scale data in output vector before feed it to ann based on previously calculated parameters
    • fann_scale_output_train_data - Scales the outputs in the training data to the specified range
    • fann_scale_train - Scale input and output data based on previously calculated parameters
    • fann_scale_train_data - Scales the inputs and outputs in the training data to the specified range
    • fann_set_activation_function - Sets the activation function for supplied neuron and layer
    • fann_set_activation_function_hidden - Sets the activation function for all of the hidden layers
    • fann_set_activation_function_layer - Sets the activation function for all the neurons in the supplied layer
    • fann_set_activation_function_output - Sets the activation function for the output layer
    • fann_set_activation_steepness - Sets the activation steepness for supplied neuron and layer number
    • fann_set_activation_steepness_hidden - Sets the steepness of the activation steepness for all neurons in the all hidden layers
    • fann_set_activation_steepness_layer - Sets the activation steepness for all of the neurons in the supplied layer number
    • fann_set_activation_steepness_output - Sets the steepness of the activation steepness in the output layer
    • fann_set_bit_fail_limit - Set the bit fail limit used during training
    • fann_set_callback - Sets the callback function for use during training
    • fann_set_cascade_activation_functions - Sets the array of cascade candidate activation functions
    • fann_set_cascade_activation_steepnesses - Sets the array of cascade candidate activation steepnesses
    • fann_set_cascade_candidate_change_fraction - Sets the cascade candidate change fraction
    • fann_set_cascade_candidate_limit - Sets the candidate limit
    • fann_set_cascade_candidate_stagnation_epochs - Sets the number of cascade candidate stagnation epochs
    • fann_set_cascade_max_cand_epochs - Sets the max candidate epochs
    • fann_set_cascade_max_out_epochs - Sets the maximum out epochs
    • fann_set_cascade_min_cand_epochs - Sets the min candidate epochs
    • fann_set_cascade_min_out_epochs - Sets the minimum out epochs
    • fann_set_cascade_num_candidate_groups - Sets the number of candidate groups
    • fann_set_cascade_output_change_fraction - Sets the cascade output change fraction
    • fann_set_cascade_output_stagnation_epochs - Sets the number of cascade output stagnation epochs
    • fann_set_cascade_weight_multiplier - Sets the weight multiplier
    • fann_set_error_log - Sets where the errors are logged to
    • fann_set_input_scaling_params - Calculate input scaling parameters for future use based on training data
    • fann_set_learning_momentum - Sets the learning momentum
    • fann_set_learning_rate - Sets the learning rate
    • fann_set_output_scaling_params - Calculate output scaling parameters for future use based on training data
    • fann_set_quickprop_decay - Sets the quickprop decay factor
    • fann_set_quickprop_mu - Sets the quickprop mu factor
    • fann_set_rprop_decrease_factor - Sets the decrease factor used during RPROP training
    • fann_set_rprop_delta_max - Sets the maximum step-size
    • fann_set_rprop_delta_min - Sets the minimum step-size
    • fann_set_rprop_delta_zero - Sets the initial step-size
    • fann_set_rprop_increase_factor - Sets the increase factor used during RPROP training
    • fann_set_sarprop_step_error_shift - Sets the sarprop step error shift
    • fann_set_sarprop_step_error_threshold_factor - Sets the sarprop step error threshold factor
    • fann_set_sarprop_temperature - Sets the sarprop temperature
    • fann_set_sarprop_weight_decay_shift - Sets the sarprop weight decay shift
    • fann_set_scaling_params - Calculate input and output scaling parameters for future use based on training data
    • fann_set_training_algorithm - Sets the training algorithm
    • fann_set_train_error_function - Sets the error function used during training
    • fann_set_train_stop_function - Sets the stop function used during training
    • fann_set_weight - Set a connection in the network
    • fann_set_weight_array - Set connections in the network
    • fann_shuffle_train_data - Shuffles training data, randomizing the order
    • fann_subset_train_data - Returns an copy of a subset of the train data
    • fann_test - Test with a set of inputs, and a set of desired outputs
    • fann_test_data - Test a set of training data and calculates the MSE for the training data
    • fann_train - Train one iteration with a set of inputs, and a set of desired outputs
    • fann_train_epoch - Train one epoch with a set of training data
    • fann_train_on_data - Trains on an entire dataset for a period of time
    • fann_train_on_file - Trains on an entire dataset, which is read from file, for a period of time
    • fastcgi_finish_request - すべてのレスポンスデータをクライアントにフラッシュする
    • fbird_add_user - のエイリアス ibase_add_user
    • fbird_affected_rows - のエイリアス ibase_affected_rows
    • fbird_backup - のエイリアス ibase_backup
    • fbird_blob_add - のエイリアス ibase_blob_add
    • fbird_blob_cancel - Cancel creating blob
    • fbird_blob_close - のエイリアス ibase_blob_close
    • fbird_blob_create - のエイリアス ibase_blob_create
    • fbird_blob_echo - のエイリアス ibase_blob_echo
    • fbird_blob_get - のエイリアス ibase_blob_get
    • fbird_blob_import - のエイリアス ibase_blob_import
    • fbird_blob_info - のエイリアス ibase_blob_info
    • fbird_blob_open - のエイリアス ibase_blob_open
    • fbird_close - のエイリアス ibase_close
    • fbird_commit - のエイリアス ibase_commit
    • fbird_commit_ret - のエイリアス ibase_commit_ret
    • fbird_connect - のエイリアス ibase_connect
    • fbird_db_info - のエイリアス ibase_db_info
    • fbird_delete_user - のエイリアス ibase_delete_user
    • fbird_drop_db - のエイリアス ibase_drop_db
    • fbird_errcode - のエイリアス ibase_errcode
    • fbird_errmsg - のエイリアス ibase_errmsg
    • fbird_execute - のエイリアス ibase_execute
    • fbird_fetch_assoc - のエイリアス ibase_fetch_assoc
    • fbird_fetch_object - のエイリアス ibase_fetch_object
    • fbird_fetch_row - のエイリアス ibase_fetch_row
    • fbird_field_info - のエイリアス ibase_field_info
    • fbird_free_event_handler - のエイリアス ibase_free_event_handler
    • fbird_free_query - のエイリアス ibase_free_query
    • fbird_free_result - のエイリアス ibase_free_result
    • fbird_gen_id - のエイリアス ibase_gen_id
    • fbird_maintain_db - のエイリアス ibase_maintain_db
    • fbird_modify_user - のエイリアス ibase_modify_user
    • fbird_name_result - のエイリアス ibase_name_result
    • fbird_num_fields - のエイリアス ibase_num_fields
    • fbird_num_params - のエイリアス ibase_num_params
    • fbird_param_info - のエイリアス ibase_param_info
    • fbird_pconnect - のエイリアス ibase_pconnect
    • fbird_prepare - のエイリアス ibase_prepare
    • fbird_query - のエイリアス ibase_query
    • fbird_restore - のエイリアス ibase_restore
    • fbird_rollback - のエイリアス ibase_rollback
    • fbird_rollback_ret - のエイリアス ibase_rollback_ret
    • fbird_server_info - のエイリアス ibase_server_info
    • fbird_service_attach - のエイリアス ibase_service_attach
    • fbird_service_detach - のエイリアス ibase_service_detach
    • fbird_set_event_handler - のエイリアス ibase_set_event_handler
    • fbird_trans - のエイリアス ibase_trans
    • fbird_wait_event - のエイリアス ibase_wait_event
    • fclose - オープンされたファイルポインタをクローズする
    • fdatasync - データをファイルに同期する(但しメタデータは除く)
    • fdf_add_doc_javascript - FDF ドキュメントに javascript コードを追加する
    • fdf_add_template - テンプレートを FDF ドキュメントに追加する
    • fdf_close - FDF ドキュメントを閉じる
    • fdf_create - 新規 FDF ドキュメントを作成する
    • fdf_enum_values - 各ドキュメントの値に対してユーザー定義関数をコールする
    • fdf_errno - 直近の fdf 操作に関するエラーコードを返す
    • fdf_error - 直近の fdf エラーコードについての説明を返す
    • fdf_get_ap - フィールドの外観を取得する
    • fdf_get_attachment - FDF に埋め込まれている、アップロードされたファイルを展開する
    • fdf_get_encoding - /Encoding キーの値を取得する
    • fdf_get_file - /F キーの値を得る
    • fdf_get_flags - フィールドのフラグを取得する
    • fdf_get_opt - フィールドのオプション配列から値を取得する
    • fdf_get_status - /STATUS キーの値を得る
    • fdf_get_value - フィールドの値を得る
    • fdf_get_version - FDF API あるいはファイルのバージョンを取得する
    • fdf_header - FDF 固有の出力ヘッダをセットする
    • fdf_next_field_name - 次のフィールド名を得る
    • fdf_open - FDF ドキュメントをオープンする
    • fdf_open_string - 文字列から FDF ドキュメントを読み込む
    • fdf_remove_item - フォームのターゲットフレームを設定する
    • fdf_save - FDF ドキュメントを保存する
    • fdf_save_string - FDF ドキュメントを文字列として返す
    • fdf_set_ap - フィールドの外観を設定する
    • fdf_set_encoding - FDF 文字エンコーディングを設定する
    • fdf_set_file - FDF データを表示する PDF ドキュメントを設定する
    • fdf_set_flags - フィールドのフラグを設定する
    • fdf_set_javascript_action - フィールドの javascript アクションを設定する
    • fdf_set_on_import_javascript - Acrobat が FDF をオープンした際に実行される javascript のコードを追加する
    • fdf_set_opt - フィールドのオプションを設定する
    • fdf_set_status - /STATUS キーの値を設定する
    • fdf_set_submit_form_action - フィールドの投稿フォームアクションを設定する
    • fdf_set_target_frame - フォームの表示対象となるフレームを設定する
    • fdf_set_value - フィールドの値を設定する
    • fdf_set_version - FDF ファイルのバージョン番号を設定する
    • fdiv - IEEE 754 に従い、数値の除算を行う
    • feof - ファイルポインタがファイル終端に達しているかどうか調べる
    • FFI::addr - Creates an unmanaged pointer to C data
    • FFI::alignof - Gets the alignment
    • FFI::arrayType - Dynamically constructs a new C array type
    • FFI::cast - Performs a C type cast
    • FFI::cdef - Creates a new FFI object
    • FFI::free - Releases an unmanaged data structure
    • FFI::isNull - Checks whether a FFI\CData is a null pointer
    • FFI::load - Loads C declarations from a C header file
    • FFI::memcmp - Compares memory areas
    • FFI::memcpy - Copies one memory area to another
    • FFI::memset - Fills a memory area
    • FFI::new - Creates a C data structure
    • FFI::scope - Instantiates an FFI object with C declarations parsed during preloading
    • FFI::sizeof - Gets the size of C data or types
    • FFI::string - Creates a PHP string from a memory area
    • FFI::type - Creates an FFI\CType object from a C declaration
    • FFI::typeof - Gets the FFI\CType of FFI\CData
    • FFI\CType::getAlignment - Description
    • FFI\CType::getArrayElementType - Description
    • FFI\CType::getArrayLength - Description
    • FFI\CType::getAttributes - Description
    • FFI\CType::getEnumKind - Description
    • FFI\CType::getFuncABI - Description
    • FFI\CType::getFuncParameterCount - Description
    • FFI\CType::getFuncParameterType - Description
    • FFI\CType::getFuncReturnType - Description
    • FFI\CType::getKind - Description
    • FFI\CType::getName - Description
    • FFI\CType::getPointerType - Description
    • FFI\CType::getSize - Description
    • FFI\CType::getStructFieldNames - Description
    • FFI\CType::getStructFieldOffset - Description
    • FFI\CType::getStructFieldType - Description
    • fflush - 出力をファイルにフラッシュする
    • fgetc - ファイルポインタから1文字取り出す
    • fgetcsv - ファイルポインタから行を取得し、CSVフィールドを処理する
    • fgets - ファイルポインタから 1 行取得する
    • fgetss - ファイルポインタから 1 行取り出し、HTML タグを取り除く
    • Fiber::getCurrent - 現在実行中のファイバーのインスタンスを取得する
    • Fiber::getReturn - ファイバーが返した値を取得する
    • Fiber::isRunning - ファイバーが実行中かどうかを調べる
    • Fiber::isStarted - ファイバーが開始したかどうかを調べる
    • Fiber::isSuspended - ファイバーが停止中かどうかを調べる
    • Fiber::isTerminated - ファイバーが終了しているかを調べる
    • Fiber::resume - 値を渡して、ファイバーの実行を再開させる
    • Fiber::start - ファイバーの実行を開始する
    • Fiber::suspend - 現在実行中のファイバーを停止する
    • Fiber::throw - ファイバーの実行を、例外をスローすることで再開する
    • Fiber::__construct - 新しいファイバーのインスタンスを構築する
    • FiberError::__construct - インスタンス化を禁止するためのコンストラクタ
    • file - ファイル全体を読み込んで配列に格納する
    • fileatime - ファイルの最終アクセス時刻を取得する
    • filectime - ファイルの inode 変更時刻を取得する
    • filegroup - ファイルのグループを取得する
    • fileinode - ファイルの inode を取得する
    • filemtime - ファイルの更新時刻を取得する
    • fileowner - ファイルの所有者を取得する
    • fileperms - ファイルのパーミッションを取得する
    • filesize - ファイルのサイズを取得する
    • FilesystemIterator::current - 現在のファイル
    • FilesystemIterator::getFlags - 処理フラグを取得する
    • FilesystemIterator::key - 現在のファイルのキーを取得する
    • FilesystemIterator::next - 次のファイルに移動する
    • FilesystemIterator::rewind - 先頭に巻き戻す
    • FilesystemIterator::setFlags - 処理フラグを設定する
    • FilesystemIterator::__construct - 新しい filesystem イテレータを作成する
    • filetype - ファイルタイプを取得する
    • file_exists - ファイルまたはディレクトリが存在するかどうか調べる
    • file_get_contents - ファイルの内容を全て文字列に読み込む
    • file_put_contents - データをファイルに書き込む
    • FilterIterator::accept - イテレータの現在の要素がフィルタを満たすかどうかを調べる
    • FilterIterator::current - 現在の要素の値を取得する
    • FilterIterator::key - 現在のキーを取得する
    • FilterIterator::next - イテレータを前に移動する
    • FilterIterator::rewind - イテレータを巻き戻す
    • FilterIterator::valid - 現在の要素が有効かどうかをチェックする
    • FilterIterator::__construct - filterIterator を作成する
    • filter_has_var - 指定した型の変数が存在するかどうかを調べる
    • filter_id - フィルタの名前からフィルタ ID を返す
    • filter_input - 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
    • filter_input_array - 外部から変数を受け取り、オプションでそれらをフィルタリングする
    • filter_list - サポートされるフィルタの一覧を返す
    • filter_var - 指定したフィルタでデータをフィルタリングする
    • filter_var_array - 複数の変数を受け取り、オプションでそれらをフィルタリングする
    • finfo::buffer - finfo_buffer() のエイリアス
    • finfo::file - finfo_file() のエイリアス
    • finfo::set_flags - finfo_set_flags() のエイリアス
    • finfo::__construct - finfo_open のエイリアス
    • finfo_buffer - 文字列バッファの情報を返す
    • finfo_close - fileinfo インスタンスを閉じる
    • finfo_file - ファイルについての情報を返す
    • finfo_open - 新しい fileinfo インスタンスを作成する
    • finfo_set_flags - libmagic のオプションを設定する
    • floatval - 変数の float 値を取得する
    • flock - 汎用のファイルロックを行う
    • floor - 端数の切り捨て
    • flush - システム出力バッファをフラッシュする
    • fmod - 引数で除算をした際の剰余を返す
    • fnmatch - ファイル名がパターンにマッチするか調べる
    • fopen - ファイルまたは URL をオープンする
    • forward_static_call - static メソッドをコールする
    • forward_static_call_array - static メソッドをコールし、引数を配列で渡す
    • fpassthru - ファイルポインタ上に残っているすべてのデータを出力する
    • fpm_get_status - 現在の FPMプール の状態を返す
    • fprintf - フォーマットされた文字列をストリームに書き込む
    • fputcsv - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
    • fputs - fwrite のエイリアス
    • fread - バイナリセーフなファイルの読み込み
    • frenchtojd - フランス革命暦をユリウス積算日に変換する
    • fscanf - フォーマットに基づきファイルからの入力を処理する
    • fseek - ファイルポインタを移動する
    • fsockopen - インターネット接続もしくは Unix ドメインソケット接続をオープンする
    • fstat - オープンしたファイルポインタからファイルに関する情報を取得する
    • fsync - データをファイルに同期する(メタデータも含む)
    • ftell - ファイルの読み書き用ポインタの現在位置を返す
    • ftok - パス名とプロジェクト ID を、System V IPC キーに変換する
    • ftp_alloc - アップロードされるファイルのためのスペースを確保する
    • ftp_append - ファイルの内容をFTPサーバー上の別のファイルに追加する
    • ftp_cdup - 親ディレクトリに移動する
    • ftp_chdir - FTP サーバー上でディレクトリを移動する
    • ftp_chmod - FTP 経由でファイルのパーミッションを設定する
    • ftp_close - FTP 接続を閉じる
    • ftp_connect - FTP 接続をオープンする
    • ftp_delete - FTP サーバー上のファイルを削除する
    • ftp_exec - FTP サーバー上でのコマンドの実行をリクエストする
    • ftp_fget - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する
    • ftp_fput - オープン中のファイルを FTP サーバーにアップロードする
    • ftp_get - FTP サーバーからファイルをダウンロードする
    • ftp_get_option - カレントの FTP 接続での種々の実行時動作を取得する
    • ftp_login - FTP 接続にログインする
    • ftp_mdtm - 指定したファイルが最後に更新された時刻を返す
    • ftp_mkdir - ディレクトリを作成する
    • ftp_mlsd - ディレクトリに存在するファイルの一覧を返す
    • ftp_nb_continue - ファイルの取得/送信を継続する（非ブロッキング）
    • ftp_nb_fget - FTP サーバーからファイルをダウンロードし、オープン中のファイルに保存する（非ブロッキング）
    • ftp_nb_fput - オープン中のファイルを FTP サーバーに保存する（非ブロッキング）
    • ftp_nb_get - FTP サーバーからファイルを取得し、ローカルファイルに書き込む（非ブロッキング）
    • ftp_nb_put - FTP サーバーにファイルを保存する（非ブロッキング）
    • ftp_nlist - 指定したディレクトリのファイルの一覧を返す
    • ftp_pasv - パッシブモードをオンまたはオフにする
    • ftp_put - FTP サーバーにファイルをアップロードする
    • ftp_pwd - カレントのディレクトリ名を返す
    • ftp_quit - ftp_close のエイリアス
    • ftp_raw - FTP サーバーに任意のコマンドを送信する
    • ftp_rawlist - 指定したディレクトリの詳細なファイル一覧を返す
    • ftp_rename - FTP サーバー上のファイルまたはディレクトリの名前を変更する
    • ftp_rmdir - ディレクトリを削除する
    • ftp_set_option - さまざまな FTP 実行時オプションを設定する
    • ftp_site - SITEコマンドをサーバーに送信する
    • ftp_size - 指定したファイルのサイズを返す
    • ftp_ssl_connect - セキュアな SSL-FTP 接続をオープンする
    • ftp_systype - リモート FTP サーバーのシステム型 ID を返す
    • ftruncate - ファイルを指定した長さに丸める
    • function_exists - 指定した関数が定義されている場合に true を返す
    • func_get_arg - 引数のリストから要素をひとつ返す
    • func_get_args - 関数の引数リストを配列として返す
    • func_num_args - 関数に渡された引数の数を返す
    • fwrite - バイナリセーフなファイル書き込み処理
  • g
    • gc_collect_cycles - すべての既存ガベージサイクルを強制的に収集する
    • gc_disable - 循環参照コレクタを無効にする
    • gc_enable - 循環参照コレクタを有効にする
    • gc_enabled - 循環参照コレクタの状態を返す
    • gc_mem_caches - Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する
    • gc_status - ガベージコレクタに関する情報を取得する
    • gd_info - 現在インストールされているGDライブラリに関する情報を取得する
    • GearmanClient::addOptions - Add client options
    • GearmanClient::addServer - Add a job server to the client
    • GearmanClient::addServers - Add a list of job servers to the client
    • GearmanClient::addTask - Add a task to be run in parallel
    • GearmanClient::addTaskBackground - Add a background task to be run in parallel
    • GearmanClient::addTaskHigh - Add a high priority task to run in parallel
    • GearmanClient::addTaskHighBackground - Add a high priority background task to be run in parallel
    • GearmanClient::addTaskLow - Add a low priority task to run in parallel
    • GearmanClient::addTaskLowBackground - Add a low priority background task to be run in parallel
    • GearmanClient::addTaskStatus - Add a task to get status
    • GearmanClient::clearCallbacks - Clear all task callback functions
    • GearmanClient::clone - Create a copy of a GearmanClient object
    • GearmanClient::context - Get the application context
    • GearmanClient::data - Get the application data (deprecated)
    • GearmanClient::do - Run a single task and return a result [deprecated]
    • GearmanClient::doBackground - Run a task in the background
    • GearmanClient::doHigh - Run a single high priority task
    • GearmanClient::doHighBackground - Run a high priority task in the background
    • GearmanClient::doJobHandle - Get the job handle for the running task
    • GearmanClient::doLow - Run a single low priority task
    • GearmanClient::doLowBackground - Run a low priority task in the background
    • GearmanClient::doNormal - Run a single task and return a result
    • GearmanClient::doStatus - Get the status for the running task
    • GearmanClient::echo - Send data to all job servers to see if they echo it back [deprecated]
    • GearmanClient::error - Returns an error string for the last error encountered
    • GearmanClient::getErrno - Get an errno value
    • GearmanClient::jobStatus - Get the status of a background job
    • GearmanClient::ping - Send data to all job servers to see if they echo it back
    • GearmanClient::removeOptions - Remove client options
    • GearmanClient::returnCode - Get the last Gearman return code
    • GearmanClient::runTasks - Run a list of tasks in parallel
    • GearmanClient::setClientCallback - Callback function when there is a data packet for a task (deprecated)
    • GearmanClient::setCompleteCallback - Set a function to be called on task completion
    • GearmanClient::setContext - Set application context
    • GearmanClient::setCreatedCallback - Set a callback for when a task is queued
    • GearmanClient::setData - Set application data (deprecated)
    • GearmanClient::setDataCallback - Callback function when there is a data packet for a task
    • GearmanClient::setExceptionCallback - Set a callback for worker exceptions
    • GearmanClient::setFailCallback - Set callback for job failure
    • GearmanClient::setOptions - Set client options
    • GearmanClient::setStatusCallback - Set a callback for collecting task status
    • GearmanClient::setTimeout - Set socket I/O activity timeout
    • GearmanClient::setWarningCallback - Set a callback for worker warnings
    • GearmanClient::setWorkloadCallback - Set a callback for accepting incremental data updates
    • GearmanClient::timeout - Get current socket I/O activity timeout value
    • GearmanClient::wait - Wait for I/O activity on all connections in a client
    • GearmanClient::__construct - Create a GearmanClient instance
    • GearmanJob::complete - Send the result and complete status (deprecated)
    • GearmanJob::data - Send data for a running job (deprecated)
    • GearmanJob::exception - Send exception for running job (deprecated)
    • GearmanJob::fail - Send fail status (deprecated)
    • GearmanJob::functionName - Get function name
    • GearmanJob::handle - Get the job handle
    • GearmanJob::returnCode - Get last return code
    • GearmanJob::sendComplete - Send the result and complete status
    • GearmanJob::sendData - Send data for a running job
    • GearmanJob::sendException - Send exception for running job (exception)
    • GearmanJob::sendFail - Send fail status
    • GearmanJob::sendStatus - Send status
    • GearmanJob::sendWarning - Send a warning
    • GearmanJob::setReturn - Set a return value
    • GearmanJob::status - Send status (deprecated)
    • GearmanJob::unique - Get the unique identifier
    • GearmanJob::warning - Send a warning (deprecated)
    • GearmanJob::workload - Get workload
    • GearmanJob::workloadSize - Get size of work load
    • GearmanJob::__construct - Create a GearmanJob instance
    • GearmanTask::create - Create a task (deprecated)
    • GearmanTask::data - Get data returned for a task
    • GearmanTask::dataSize - Get the size of returned data
    • GearmanTask::function - Get associated function name (deprecated)
    • GearmanTask::functionName - Get associated function name
    • GearmanTask::isKnown - Determine if task is known
    • GearmanTask::isRunning - Test whether the task is currently running
    • GearmanTask::jobHandle - Get the job handle
    • GearmanTask::recvData - Read work or result data into a buffer for a task
    • GearmanTask::returnCode - Get the last return code
    • GearmanTask::sendData - Send data for a task (deprecated)
    • GearmanTask::sendWorkload - Send data for a task
    • GearmanTask::taskDenominator - Get completion percentage denominator
    • GearmanTask::taskNumerator - Get completion percentage numerator
    • GearmanTask::unique - Get the unique identifier for a task
    • GearmanTask::uuid - Get the unique identifier for a task (deprecated)
    • GearmanTask::__construct - Create a GearmanTask instance
    • GearmanWorker::addFunction - Register and add callback function
    • GearmanWorker::addOptions - Add worker options
    • GearmanWorker::addServer - Add a job server
    • GearmanWorker::addServers - Add job servers
    • GearmanWorker::clone - Create a copy of the worker
    • GearmanWorker::echo - Test job server response
    • GearmanWorker::error - Get the last error encountered
    • GearmanWorker::getErrno - Get errno
    • GearmanWorker::options - Get worker options
    • GearmanWorker::register - Register a function with the job server
    • GearmanWorker::removeOptions - Remove worker options
    • GearmanWorker::returnCode - Get last Gearman return code
    • GearmanWorker::setId - Give the worker an identifier so it can be tracked when asking gearmand for the list of available workers
    • GearmanWorker::setOptions - Set worker options
    • GearmanWorker::setTimeout - Set socket I/O activity timeout
    • GearmanWorker::timeout - Get socket I/O activity timeout
    • GearmanWorker::unregister - Unregister a function name with the job servers
    • GearmanWorker::unregisterAll - Unregister all function names with the job servers
    • GearmanWorker::wait - Wait for activity from one of the job servers
    • GearmanWorker::work - Wait for and perform jobs
    • GearmanWorker::__construct - Create a GearmanWorker instance
    • Gender\Gender::connect - 外部の名前ディレクトリに接続する
    • Gender\Gender::country - 国を表すテキストを取得する
    • Gender\Gender::get - 性別を取得する
    • Gender\Gender::isNick - name0 が name1 のエイリアスかどうかを調べる
    • Gender\Gender::similarNames - 似た名前を取得する
    • Gender\Gender::__construct - Gender オブジェクトを作る
    • Generator::current - yield した値を取得する
    • Generator::getReturn - ジェネレータの戻り値を取得する
    • Generator::key - yield したキーを取得する
    • Generator::next - ジェネレータを続行する
    • Generator::rewind - イテレータを巻き戻す
    • Generator::send - 値をジェネレータに送る
    • Generator::throw - 例外をジェネレータにスローする
    • Generator::valid - イテレータが終了したかどうかを調べる
    • Generator::__wakeup - シリアライズのコールバック
    • geoip_asnum_by_name - AS番号(ASN) を取得する
    • geoip_continent_code_by_name - 二文字の大陸コードを取得する
    • geoip_country_code3_by_name - 三文字の国コードを取得する
    • geoip_country_code_by_name - 二文字の国コードを取得する
    • geoip_country_name_by_name - 完全な国名を取得する
    • geoip_database_info - GeoIP データベースの情報を取得する
    • geoip_db_avail - GeoIP データベースが使用可能かどうかを調べる
    • geoip_db_filename - 対応する GeoIP データベースのファイル名を返す
    • geoip_db_get_all_info - すべての GeoIP データベース形式についての詳細情報を返す
    • geoip_domain_by_name - セカンドレベルドメインの名前を取得する
    • geoip_id_by_name - インターネット接続方式を取得する
    • geoip_isp_by_name - インターネットサービスプロバイダ (ISP) 名を取得する
    • geoip_netspeedcell_by_name - インターネットへの接続速度を取得する
    • geoip_org_by_name - 組織名を取得する
    • geoip_record_by_name - GeoIP データベースで見つかった詳細な都市情報を返す
    • geoip_region_by_name - 国コードおよび地域を取得する
    • geoip_region_name_by_code - 国コードと地域コードから地域名を返す
    • geoip_setup_custom_directory - GeoIP データベースのカスタムディレクトリを設定する
    • geoip_time_zone_by_country_and_region - 国コードと地域コードからタイムゾーンを返す
    • getallheaders - 全てのHTTPリクエストヘッダを取得する
    • getcwd - カレントのワーキングディレクトリを取得する
    • getdate - 日付/時刻情報を取得する
    • getenv - 環境変数の値をひとつ、または全て取得する
    • gethostbyaddr - 指定した IP アドレスに対応するインターネットホスト名を取得する
    • gethostbyname - インターネットホスト名に対応するIPv4アドレスを取得する
    • gethostbynamel - 指定したインターネットホスト名に対応するIPv4アドレスのリストを取得する
    • gethostname - ホスト名を取得する
    • getimagesize - 画像の大きさを取得する
    • getimagesizefromstring - 画像の大きさを文字列から取得する
    • getlastmod - 最終更新時刻を取得する
    • getmxrr - 指定したインターネットホスト名に対応する MX レコードを取得する
    • getmygid - PHP スクリプトの所有者の GID を得る
    • getmyinode - 現在のスクリプトの inode を取得する
    • getmypid - PHP のプロセス ID を取得する
    • getmyuid - PHP スクリプト所有者のユーザー ID を取得する
    • getopt - コマンドライン引数のリストからオプションを取得する
    • getprotobyname - プロトコル名のプロトコル番号を得る
    • getprotobynumber - プロトコル番号が指すプロトコル名を取得する
    • getrandmax - 乱数の最大値を取得する
    • getrusage - 現在のリソース使用状況を取得する
    • getservbyname - インターネットサービスおよびプロトコルが関連するポート番号を取得する
    • getservbyport - ポートおよびプロトコルに対応するインターネットサービスを得る
    • getSession - MySQL サーバーに接続する
    • gettext - 現在のドメインのメッセージを参照する
    • gettimeofday - 現在の時間を得る
    • gettype - 変数の型を取得する
    • get_browser - ユーザーのブラウザの機能を取得する
    • get_called_class - "遅延静的束縛" のクラス名
    • get_cfg_var - PHP 設定オプションの値を取得する
    • get_class - オブジェクトのクラス名を返す
    • get_class_methods - クラスメソッドの名前を取得する
    • get_class_vars - クラスのデフォルトプロパティを取得する
    • get_current_user - 現在の PHP スクリプトの所有者の名前を取得する
    • get_debug_type - 変数の型名をデバッグしやすい形で取得する
    • get_declared_classes - 定義済のクラスの名前を配列として返す
    • get_declared_interfaces - 宣言されている全てのインターフェイスの配列を返す
    • get_declared_traits - 宣言されているすべてのトレイトの配列を返す
    • get_defined_constants - すべての定数の名前とその値を連想配列として返す
    • get_defined_functions - 定義済みの全ての関数を配列で返す
    • get_defined_vars - 全ての定義済の変数を配列で返す
    • get_extension_funcs - あるモジュールの関数名を配列として返す
    • get_headers - HTTP リクエストに対するレスポンス内で サーバーによって送出された全てのヘッダを取得する
    • get_html_translation_table - htmlspecialchars および htmlentities で使用される変換テーブルを返す
    • get_included_files - include または require で読み込まれたファイルの名前を配列として返す
    • get_include_path - 現在の include_path 設定オプションを取得する
    • get_loaded_extensions - コンパイル/ロードされている全てのモジュールの名前を配列として返す
    • get_magic_quotes_gpc - magic_quotes_gpc の現在の設定を得る
    • get_magic_quotes_runtime - magic_quotes_runtime の現在アクティブな設定値を取得する
    • get_mangled_object_vars - マングリングされたオブジェクトのプロパティを配列で返す
    • get_meta_tags - ファイル上のすべてのメタタグ情報を配列に展開する
    • get_object_vars - 指定したオブジェクトのプロパティを取得する
    • get_parent_class - オブジェクトの親クラスの名前を取得する
    • get_required_files - get_included_files のエイリアス
    • get_resources - アクティブなリソースを返す
    • get_resource_id - 指定されたリソースの、数値の識別子を返す
    • get_resource_type - リソース型を返す
    • glob - パターンにマッチするパス名を探す
    • GlobIterator::count - ディレクトリやファイルの数を取得する
    • GlobIterator::__construct - glob を使うディレクトリを作成する
    • Gmagick::addimage - 新しい画像を Gmagick オブジェクトの画像リストに追加する
    • Gmagick::addnoiseimage - ランダムなノイズを画像に追加する
    • Gmagick::annotateimage - 画像にテキストによる注記を加える
    • Gmagick::blurimage - blur (にじみ) フィルタを画像に追加する
    • Gmagick::borderimage - 画像の周りを枠線で囲む
    • Gmagick::charcoalimage - 木炭画をシミュレートする
    • Gmagick::chopimage - 画像の一部を取り除き、切り詰める
    • Gmagick::clear - Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする
    • Gmagick::commentimage - コメントを画像に追加する
    • Gmagick::compositeimage - ある画像を別の画像に合成する
    • Gmagick::cropimage - 画像の一部を抽出する
    • Gmagick::cropthumbnailimage - 切り取ってサムネイルを作成する
    • Gmagick::current - 現在の Gmagick オブジェクトへの参照を返す
    • Gmagick::cyclecolormapimage - 画像のカラーマップを移動する
    • Gmagick::deconstructimages - 画像間の特定のピクセルの差を返す
    • Gmagick::despeckleimage - 画像内のスペックルノイズを軽減する
    • Gmagick::destroy - Gmagick オブジェクトを破棄する
    • Gmagick::drawimage - 現在の画像上の GmagickDraw オブジェクトをレンダリングする
    • Gmagick::edgeimage - 画像の輪郭を強調する
    • Gmagick::embossimage - グレースケール画像に三次元効果を施して返す
    • Gmagick::enhanceimage - ノイジーな画像の品質を向上させる
    • Gmagick::equalizeimage - 画像ヒストグラムを均等化する
    • Gmagick::flipimage - 垂直方向に反転した画像を作成する
    • Gmagick::flopimage - 水平方向に反転した画像を作成する
    • Gmagick::frameimage - 三次元の枠線をシミュレートする
    • Gmagick::gammaimage - 画像をガンマ補正する
    • Gmagick::getcopyright - GraphicsMagick API の著作権情報を文字列で返す
    • Gmagick::getfilename - 画像シーケンスに関連付けられたファイル名を取得する
    • Gmagick::getimagebackgroundcolor - 画像の背景色を返す
    • Gmagick::getimageblueprimary - 青が一番強い点を返す
    • Gmagick::getimagebordercolor - 画像の前景色を返す
    • Gmagick::getimagechanneldepth - 特定の画像チャネルの深度を返す
    • Gmagick::getimagecolors - 指定した色マップインデックスの色を返す
    • Gmagick::getimagecolorspace - 画像の色空間を取得する
    • Gmagick::getimagecompose - 画像の合成演算子を返す
    • Gmagick::getimagedelay - 画像の遅延を取得する
    • Gmagick::getimagedepth - 画像の深度を取得する
    • Gmagick::getimagedispose - 画像の配置方法を取得する
    • Gmagick::getimageextrema - 画像の極値を取得する
    • Gmagick::getimagefilename - シーケンス内の特定の画像のファイル名を返す
    • Gmagick::getimageformat - シーケンス内の特定の画像のフォーマットを返す
    • Gmagick::getimagegamma - 画像のガンマを取得する
    • Gmagick::getimagegreenprimary - 緑が一番強い点を返す
    • Gmagick::getimageheight - 画像の高さを返す
    • Gmagick::getimagehistogram - 画像のヒストグラムを取得する
    • Gmagick::getimageindex - 現在アクティブな画像のインデックスを取得する
    • Gmagick::getimageinterlacescheme - 画像のインターレース手法を取得する
    • Gmagick::getimageiterations - 画像の反復を取得する
    • Gmagick::getimagematte - 画像がマットチャネルを持っているかどうかを調べる
    • Gmagick::getimagemattecolor - 画像のマット色を返す
    • Gmagick::getimageprofile - 指定した名前の画像プロファイルを返す
    • Gmagick::getimageredprimary - 赤が一番強い点を返す
    • Gmagick::getimagerenderingintent - 画像のレンダリング方向を取得する
    • Gmagick::getimageresolution - 画像の X 方向と Y 方向の解像度を取得する
    • Gmagick::getimagescene - 画像のシーンを取得する
    • Gmagick::getimagesignature - SHA-256 メッセージダイジェストを生成する
    • Gmagick::getimagetype - 画像の型を取得する
    • Gmagick::getimageunits - 画像の解像度の単位を取得する
    • Gmagick::getimagewhitepoint - 色度が白い点を返す
    • Gmagick::getimagewidth - 画像の幅を返す
    • Gmagick::getpackagename - GraphicsMagick パッケージ名を返す
    • Gmagick::getquantumdepth - Gmagick quantum depth を返す
    • Gmagick::getreleasedate - GraphicsMagick のリリース日を返す
    • Gmagick::getsamplingfactors - 水平方向および垂直方向のサンプリング係数を取得する
    • Gmagick::getsize - Gmagick オブジェクトのサイズを取得する
    • Gmagick::getversion - GraphicsMagick API のバージョンを返す
    • Gmagick::hasnextimage - オブジェクトが次の画像を保持しているかどうかを調べる
    • Gmagick::haspreviousimage - オブジェクトが前の画像を保持しているかどうかを調べる
    • Gmagick::implodeimage - 新しい画像をコピーとして作成する
    • Gmagick::labelimage - ラベルを画像に追加する
    • Gmagick::levelimage - 画像のレベルを調節する
    • Gmagick::magnifyimage - 画像を二倍に比例拡大する
    • Gmagick::mapimage - 画像の色を、参照画像の中の最も近い色に置き換える
    • Gmagick::medianfilterimage - デジタルフィルタを適用する
    • Gmagick::minifyimage - 画像をその半分のサイズに比例縮小する
    • Gmagick::modulateimage - 明度、彩度、色相を制御する
    • Gmagick::motionblurimage - モーションブラーをシミュレートする
    • Gmagick::newimage - 新しい画像を作成する
    • Gmagick::nextimage - 次の画像に移動する
    • Gmagick::normalizeimage - カラー画像のコントラストを強調する
    • Gmagick::oilpaintimage - 油絵をシミュレートする
    • Gmagick::previousimage - オブジェクト内の前の画像に移動する
    • Gmagick::profileimage - 画像のプロファイルを追加あるいは削除する
    • Gmagick::quantizeimage - 参照画像内の色を解析する
    • Gmagick::quantizeimages - 画像シーケンス内の色を解析する
    • Gmagick::queryfontmetrics - フォントメトリクスを表す配列を返す
    • Gmagick::queryfonts - 設定したフォントを返す
    • Gmagick::queryformats - Gmagick がサポートするフォーマットを返す
    • Gmagick::radialblurimage - 画像にラジアルブラーを施す
    • Gmagick::raiseimage - 三次元のボタン風の効果をシミュレートする
    • Gmagick::read - ファイルから画像を読み込む
    • Gmagick::readimage - ファイルから画像を読み込む
    • Gmagick::readimageblob - バイナリ文字列から画像を読み込む
    • Gmagick::readimagefile - オープンしているファイルハンドルから画像を読み込む
    • Gmagick::reducenoiseimage - 画像の輪郭をなめらかにする
    • Gmagick::removeimage - 画像リストから画像を削除する
    • Gmagick::removeimageprofile - 指定した名前の画像プロファイルを削除して返す
    • Gmagick::resampleimage - 画像を指定した解像度にリサンプリングする
    • Gmagick::resizeimage - 画像のサイズを変更する
    • Gmagick::rollimage - 画像を補正する
    • Gmagick::rotateimage - 画像を回転する
    • Gmagick::scaleimage - 画像のサイズを変更する
    • Gmagick::separateimagechannel - 画像からチャネルを分離する
    • Gmagick::setCompressionQuality - オブジェクトのデフォルトの圧縮クオリティを設定する
    • Gmagick::setfilename - 画像を読み書きする前にファイル名を設定する
    • Gmagick::setimagebackgroundcolor - 画像の背景色を設定する
    • Gmagick::setimageblueprimary - 青が一番強い点を設定する
    • Gmagick::setimagebordercolor - 画像の枠線の色を設定する
    • Gmagick::setimagechanneldepth - 特定の画像チャネルの深度を設定する
    • Gmagick::setimagecolorspace - 画像の色空間を設定する
    • Gmagick::setimagecompose - 画像の合成演算子を設定する
    • Gmagick::setimagedelay - 画像の遅延を設定する
    • Gmagick::setimagedepth - 画像の深度を設定する
    • Gmagick::setimagedispose - 画像の配置方法を設定する
    • Gmagick::setimagefilename - シーケンス内の特定の画像のファイル名を設定する
    • Gmagick::setimageformat - 特定の画像のフォーマットを設定する
    • Gmagick::setimagegamma - 画像のガンマを設定する
    • Gmagick::setimagegreenprimary - 緑が一番強い点を設定する
    • Gmagick::setimageindex - 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する
    • Gmagick::setimageinterlacescheme - 画像のインターレース手法を設定する
    • Gmagick::setimageiterations - 画像の反復を設定する
    • Gmagick::setimageprofile - 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する
    • Gmagick::setimageredprimary - 赤が一番強い点を設定する
    • Gmagick::setimagerenderingintent - 画像のレンダリング方向を設定する
    • Gmagick::setimageresolution - 画像の解像度を設定する
    • Gmagick::setimagescene - 画像のシーンを設定する
    • Gmagick::setimagetype - 画像の型を設定する
    • Gmagick::setimageunits - 画像の解像度の単位を設定する
    • Gmagick::setimagewhitepoint - 画像の色度が白い点を設定する
    • Gmagick::setsamplingfactors - 画像のサンプリング係数を設定する
    • Gmagick::setsize - Gmagick オブジェクトのサイズを設定する
    • Gmagick::shearimage - 平行四辺形を作成する
    • Gmagick::solarizeimage - 画像にソラリゼーション効果を適用する
    • Gmagick::spreadimage - ブロック内の各ピクセルをランダムに移動する
    • Gmagick::stripimage - 画像からすべてのプロパティやコメントを除去する
    • Gmagick::swirlimage - 画像の中心から、ピクセルを渦巻状にする
    • Gmagick::thumbnailimage - 画像のサイズを変更する
    • Gmagick::trimimage - 画像の輪郭を削除する
    • Gmagick::write - Gmagick::writeimage のエイリアス
    • Gmagick::writeimage - 画像を指定したファイル名で書き出す
    • Gmagick::__construct - Gmagick のコンストラクタ
    • GmagickDraw::annotate - 画像の上にテキストを描画する
    • GmagickDraw::arc - 弧を描く
    • GmagickDraw::bezier - ベジエ曲線を描く
    • GmagickDraw::ellipse - 楕円を画像上に描く
    • GmagickDraw::getfillcolor - 塗りつぶし色を返す
    • GmagickDraw::getfillopacity - 描画に使う不透明度を返す
    • GmagickDraw::getfont - フォントを返す
    • GmagickDraw::getfontsize - フォントのポイント数を返す
    • GmagickDraw::getfontstyle - フォントスタイルを返す
    • GmagickDraw::getfontweight - フォントのウェイトを返す
    • GmagickDraw::getstrokecolor - オブジェクトの輪郭の描画に使う色を返す
    • GmagickDraw::getstrokeopacity - オブジェクトの輪郭の不透明度を返す
    • GmagickDraw::getstrokewidth - オブジェクトの輪郭の描画に使う線の幅を返す
    • GmagickDraw::gettextdecoration - テキストのデコレーションを返す
    • GmagickDraw::gettextencoding - テキストのアノテーションで使うコードセットを返す
    • GmagickDraw::line - 直線を描く
    • GmagickDraw::point - 点を描く
    • GmagickDraw::polygon - 多角形を描く
    • GmagickDraw::polyline - ポリラインを描く
    • GmagickDraw::rectangle - 矩形を描く
    • GmagickDraw::rotate - 指定した回転角を現在の座標空間に適用する
    • GmagickDraw::roundrectangle - 角が丸い矩形を描く
    • GmagickDraw::scale - 倍率を調整する
    • GmagickDraw::setfillcolor - オブジェクトの塗りつぶしに使う色を設定する
    • GmagickDraw::setfillopacity - 不透明度を設定する
    • GmagickDraw::setfont - テキストのアノテーションで使うフォントの完全な名前を設定する
    • GmagickDraw::setfontsize - テキストのアノテーションで使うフォントのポイント数を設定する
    • GmagickDraw::setfontstyle - テキストのアノテーションで使うフォントのスタイルを設定する
    • GmagickDraw::setfontweight - フォントのウェイトを設定する
    • GmagickDraw::setstrokecolor - オブジェクトの輪郭の描画に使う色を設定する
    • GmagickDraw::setstrokeopacity - オブジェクトの輪郭の不透明度を設定する
    • GmagickDraw::setstrokewidth - オブジェクトの輪郭の描画に使う線の幅を設定する
    • GmagickDraw::settextdecoration - デコレーションを設定する
    • GmagickDraw::settextencoding - テキストのコードセットを設定する
    • GmagickPixel::getcolor - 色を返す
    • GmagickPixel::getcolorcount - この色の色カウントを返す
    • GmagickPixel::getcolorvalue - 指定した色チャネルの正規化した値を取得する
    • GmagickPixel::setcolor - 色を設定する
    • GmagickPixel::setcolorvalue - 色チャネルの正規化した値を設定する
    • GmagickPixel::__construct - GmagickPixel のコンストラクタ
    • gmdate - GMT/UTC の日付/時刻を書式化する
    • gmmktime - GMT 日付から Unix タイムスタンプを取得する
    • GMP::__construct - GMP数を作成する
    • GMP::__serialize - GMP オブジェクトをシリアライズする
    • GMP::__unserialize - data 引数をGMP オブジェクトとして復元する
    • gmp_abs - 絶対値
    • gmp_add - 数値を加算する
    • gmp_and - ビット AND を計算する
    • gmp_binomial - 二項係数を計算する
    • gmp_clrbit - ビットをクリアする
    • gmp_cmp - 数を比較する
    • gmp_com - 1 の補数を計算する
    • gmp_div - gmp_div_q のエイリアス
    • gmp_divexact - 正確な除算
    • gmp_div_q - 数値を除算する
    • gmp_div_qr - 除算を行い、商と余りを得る
    • gmp_div_r - 除算の余りを計算する
    • gmp_export - バイナリ文字列にエクスポートする
    • gmp_fact - 階乗
    • gmp_gcd - 最大公約数を計算する
    • gmp_gcdext - 最大公約数と乗数を計算する
    • gmp_hamdist - ハミング距離
    • gmp_import - バイナリ文字列からインポートする
    • gmp_init - GMP 数を作成する
    • gmp_intval - GMP 数を整数に変換する
    • gmp_invert - 法による逆
    • gmp_jacobi - ヤコビ記号
    • gmp_kronecker - クロネッカーの記号を計算する
    • gmp_lcm - 最小公倍数を計算する
    • gmp_legendre - ルジェンドル記号
    • gmp_mod - モジュロ演算
    • gmp_mul - 数値を乗算する
    • gmp_neg - 符号を反転する
    • gmp_nextprime - 次の素数を見つける
    • gmp_or - ビット OR を計算する
    • gmp_perfect_power - 累乗数かどうかを調べる
    • gmp_perfect_square - 平方数かどうかを調べる
    • gmp_popcount - セットされているビットの数
    • gmp_pow - べき乗を計算する
    • gmp_powm - べき乗とモジュロを計算する
    • gmp_prob_prime - 数が"おそらく素数"であるかどうかを調べる
    • gmp_random - 乱数を生成する
    • gmp_random_bits - 乱数を生成する
    • gmp_random_range - 等確率に選ばれた整数を取得する
    • gmp_random_seed - 乱数シードを設定する
    • gmp_root - n乗根の整数部を返す
    • gmp_rootrem - n乗根の整数部分と小数部分を返す
    • gmp_scan0 - 0 を探す
    • gmp_scan1 - 1 を探す
    • gmp_setbit - ビットを設定する
    • gmp_sign - 数の符号
    • gmp_sqrt - 平方根を計算する
    • gmp_sqrtrem - 余りつきの平方根
    • gmp_strval - GMP 数を文字列に変換する
    • gmp_sub - 数値の減算
    • gmp_testbit - ビットが設定されているかどうかを調べる
    • gmp_xor - ビット XOR を計算する
    • gmstrftime - ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする
    • gnupg_adddecryptkey - 復号のためのキーを追加する
    • gnupg_addencryptkey - 暗号化のためのキーを追加する
    • gnupg_addsignkey - 署名のためのキーを追加する
    • gnupg_cleardecryptkeys - 事前に復号のために設定されたすべてのキーを削除する
    • gnupg_clearencryptkeys - 事前に暗号化のために設定されたすべてのキーを削除する
    • gnupg_clearsignkeys - 事前に署名のために設定されたすべてのキーを削除する
    • gnupg_decrypt - 指定されたテキストを復号する
    • gnupg_decryptverify - 指定されたテキストを復号し、検証する
    • gnupg_deletekey - キーを削除する
    • gnupg_encrypt - 指定したテキストを暗号化する
    • gnupg_encryptsign - 指定したテキストを暗号化し、署名する
    • gnupg_export - キーをエクスポートする
    • gnupg_getengineinfo - 暗号化エンジンの情報を返す
    • gnupg_geterror - 関数が失敗した場合にエラー文字列を返す
    • gnupg_geterrorinfo - エラー情報を返す
    • gnupg_getprotocol - すべての操作で現在アクティブなプロトコルを返す
    • gnupg_gettrustlist - 信頼済みのアイテムを検索する
    • gnupg_import - キーをインポートする
    • gnupg_init - 接続を初期化する
    • gnupg_keyinfo - 指定したパターンに一致するすべてのキーについての情報を配列で返す
    • gnupg_listsignatures - キーの署名の一覧を返す
    • gnupg_setarmor - armor 形式を切り替える
    • gnupg_seterrormode - エラー報告モードを設定する
    • gnupg_setsignmode - 署名方式を設定する
    • gnupg_sign - 指定したテキストに署名する
    • gnupg_verify - 署名済みテキストを検証する
    • grapheme_extract - デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
    • grapheme_stripos - 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_stristr - 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
    • grapheme_strlen - 書記素単位で文字列の長さを取得する
    • grapheme_strpos - 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strripos - 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strrpos - 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
    • grapheme_strstr - haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
    • grapheme_substr - 部分文字列を返す
    • gregoriantojd - グレゴリウス日をユリウス積算日に変換する
    • gzclose - 開かれたgzファイルへのポインタを閉じる
    • gzcompress - 文字列を圧縮する
    • gzdecode - gzip 圧縮された文字列をデコードする
    • gzdeflate - 文字列を deflate 圧縮する
    • gzencode - gzip 圧縮された文字列を作成する
    • gzeof - gz ファイルポインタが EOF かどうか調べる
    • gzfile - gzファイル全体を配列に読み込む
    • gzgetc - gz ファイルへのポインタから文字を得る
    • gzgets - ファイルポインタから 1 行を得る
    • gzgetss - gzファイルへのポインタから1行を得て、HTMLタグを取り除く
    • gzinflate - deflate圧縮された文字列を解凍する
    • gzopen - gz ファイルを開く
    • gzpassthru - gzファイルへのポインタから残りのデータ全部を出力する
    • gzputs - gzwrite のエイリアス
    • gzread - バイナリ対応のgzファイル読み込み
    • gzrewind - gz ファイルポインタの示す位置を元に戻す
    • gzseek - gz ファイルポインタの位置を移動する
    • gztell - gz ファイルポインタの読み込み/書き込み位置を返します
    • gzuncompress - 圧縮された文字列を解凍する
    • gzwrite - バイナリセーフな gz ファイル書き込み
  • h
    • hash - ハッシュ値 (メッセージダイジェスト) を生成する
    • HashContext::__construct - private なコンストラクタのため、直接インスタンス化できません
    • HashContext::__serialize - HashContext オブジェクトをシリアライズする
    • HashContext::__unserialize - data を HashContext オブジェクト に復元する
    • hash_algos - 登録されているハッシュアルゴリズムの一覧を返す
    • hash_copy - ハッシュコンテキストをコピーする
    • hash_equals - タイミング攻撃に対しても安全な文字列比較
    • hash_file - ファイルの内容から、ハッシュ値を生成する
    • hash_final - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す
    • hash_hkdf - 与えられたキーから導出されるHKDFキーを生成する
    • hash_hmac - HMAC 方式を使用してハッシュ値を生成する
    • hash_hmac_algos - hash_hmac に合うハッシュアルゴリズムの一覧を返す
    • hash_hmac_file - HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する
    • hash_init - 段階的なハッシュコンテキストを初期化する
    • hash_pbkdf2 - PBKDF2 を使ってパスワードからキーを生成する
    • hash_update - アクティブなハッシュコンテキストにデータを投入する
    • hash_update_file - アクティブなハッシュコンテキストに、ファイルからデータを投入する
    • hash_update_stream - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
    • header - 生の HTTP ヘッダを送信する
    • headers_list - 送信した (もしくは送信される予定の) レスポンスヘッダの一覧を返す
    • headers_sent - ヘッダが既に送信されているかどうかを調べる
    • header_register_callback - ヘッダ用の関数を登録する
    • header_remove - 以前に設定したHTTPヘッダを削除する
    • hebrev - 論理表記のヘブライ語を物理表記に変換する
    • hebrevc - 論理表記のヘブライ語を、改行の変換も含めて物理表記に変換する
    • hex2bin - 16進エンコードされたバイナリ文字列をデコードする
    • hexdec - 16 進数を 10 進数に変換する
    • highlight_file - ファイルの構文ハイライト表示
    • highlight_string - 文字列の構文ハイライト表示
    • hrtime - システムの高精度な時刻を取得する
    • HRTime\PerformanceCounter::getFrequency - Timer frequency in ticks per second
    • HRTime\PerformanceCounter::getTicks - Current ticks from the system
    • HRTime\PerformanceCounter::getTicksSince - Ticks elapsed since the given value
    • HRTime\StopWatch::getElapsedTicks - Get elapsed ticks for all intervals
    • HRTime\StopWatch::getElapsedTime - Get elapsed time for all intervals
    • HRTime\StopWatch::getLastElapsedTicks - Get elapsed ticks for the last interval
    • HRTime\StopWatch::getLastElapsedTime - Get elapsed time for the last interval
    • HRTime\StopWatch::isRunning - Whether the measurement is running
    • HRTime\StopWatch::start - Start time measurement
    • HRTime\StopWatch::stop - Stop time measurement
    • htmlentities - 適用可能な文字を全て HTML エンティティに変換する
    • htmlspecialchars - 特殊文字を HTML エンティティに変換する
    • htmlspecialchars_decode - 特殊な HTML エンティティを文字に戻す
    • html_entity_decode - HTML エンティティを対応する文字に変換する
    • http_build_query - URL エンコードされたクエリ文字列を生成する
    • http_response_code - HTTP レスポンスコードを取得または設定
    • hypot - 直角三角形の斜辺の長さを計算する
  • i
    • ibase_add_user - Add a user to a security database
    • ibase_affected_rows - 直近のクエリで変更された行の数を返す
    • ibase_backup - Initiates a backup task in the service manager and returns immediately
    • ibase_blob_add - 生成された blob にデータを追加する
    • ibase_blob_cancel - blob の生成を取り消す
    • ibase_blob_close - blob を閉じる
    • ibase_blob_create - データを追加するために blob を生成する
    • ibase_blob_echo - ブラウザに blob の内容を出力する
    • ibase_blob_get - オープンした blob から len バイト分のデータを取得する
    • ibase_blob_import - blob を生成し、ファイルをコピーし、閉じる
    • ibase_blob_info - blob の長さと他の便利な情報を返す
    • ibase_blob_open - データの一部を取得するために blob をオープンする
    • ibase_close - InterBase データベースへの接続を閉じる
    • ibase_commit - トランザクションをコミットする
    • ibase_commit_ret - トランザクションを閉じずにコミットする
    • ibase_connect - データベースへの接続をオープンする
    • ibase_db_info - データベースについての統計情報を要求する
    • ibase_delete_user - Delete a user from a security database
    • ibase_drop_db - データベースを削除する
    • ibase_errcode - エラーコードを返す
    • ibase_errmsg - エラーメッセージを返す
    • ibase_execute - 準備されたクエリを実行する
    • ibase_fetch_assoc - クエリの結果から、行を連想配列として取得する
    • ibase_fetch_object - InterBase データベースからオブジェクトを得る
    • ibase_fetch_row - InterBase データベースから 1 行分の結果を取得する
    • ibase_field_info - フィールドに関する情報を得る
    • ibase_free_event_handler - 登録済みのイベントハンドラをキャンセルする
    • ibase_free_query - プリペアドクエリにより確保されたメモリを解放する
    • ibase_free_result - 結果セットを解放する
    • ibase_gen_id - 指定した名前のジェネレータをひとつ加算し、その新しい値を返す
    • ibase_maintain_db - データベースサーバーでメンテナンスコマンドを実行する
    • ibase_modify_user - Modify a user to a security database
    • ibase_name_result - 結果セットに名前を割り当てる
    • ibase_num_fields - 結果セットにおけるフィールド数を得る
    • ibase_num_params - プリペアドクエリのパラメータ数を返す
    • ibase_param_info - プリペアドクエリのパラメータに関する情報を返す
    • ibase_pconnect - InterBase データベースへの持続的接続をオープンする
    • ibase_prepare - Prepare a query for later binding of parameter placeholders and execution
    • ibase_query - InterBase データベースでクエリを実行する
    • ibase_restore - Initiates a restore task in the service manager and returns immediately
    • ibase_rollback - トランザクションをロールバックする
    • ibase_rollback_ret - トランザクションを閉じずにロールバックする
    • ibase_server_info - データベースサーバーについての情報を要求する
    • ibase_service_attach - サービスマネージャに接続する
    • ibase_service_detach - サービスマネージャとの接続を切断する
    • ibase_set_event_handler - イベントが発生した際にコールされるコールバック関数を登録する
    • ibase_trans - トランザクションを開始する
    • ibase_wait_event - データベースでイベントが発生するのを待つ
    • iconv - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
    • iconv_get_encoding - iconv 拡張モジュールの内部設定変数を取得する
    • iconv_mime_decode - MIME ヘッダフィールドをデコードする
    • iconv_mime_decode_headers - 複数の MIME ヘッダフィールドを一度にデコードする
    • iconv_mime_encode - MIME ヘッダフィールドを作成する
    • iconv_set_encoding - 文字エンコーディング変換用の設定を行なう
    • iconv_strlen - 文字列の文字数を返す
    • iconv_strpos - 文字列が最初に現れる場所を見つける
    • iconv_strrpos - 文字列が最後に現れる場所を見つける
    • iconv_substr - 文字列の一部を切り出す
    • idate - ローカルな時刻/日付の一部を整数として整形する
    • idn_to_ascii - ドメイン名をIDNAのASCII形式に変換する
    • idn_to_utf8 - IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する
    • igbinary_serialize - コンパクト、かつ保存可能な値のバイナリ表現を生成する
    • igbinary_unserialize - igbinary_serialize によって保存されたバイナリ表現から、PHP の値を復元する
    • ignore_user_abort - クライアントの接続が切断された際にスクリプトの実行を終了するかどうかを設定する
    • image2wbmp - 画像をブラウザあるいはファイルに出力する
    • imageaffine - 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す
    • imageaffinematrixconcat - 二つのアフィン変換行列を連結する
    • imageaffinematrixget - アフィン変換行列を取得する
    • imagealphablending - イメージのブレンドモードを設定する
    • imageantialias - アンチエイリアス機能を使用すべきかどうかを判断する
    • imagearc - 部分楕円を描画する
    • imageavif - 画像をブラウザあるいはファイルに出力する
    • imagebmp - ビットマップ画像をブラウザかファイルに出力する
    • imagechar - 水平に文字を描画する
    • imagecharup - 垂直に文字を描画する
    • imagecolorallocate - 画像で使用する色を作成する
    • imagecolorallocatealpha - 画像で使用する色を透過度を指定して作成する
    • imagecolorat - ピクセルの色のインデックスを取得する
    • imagecolorclosest - 指定した色に最も近い色のインデックスを取得する
    • imagecolorclosestalpha - 指定した色+アルファ値に最も近い色のインデックスを取得する
    • imagecolorclosesthwb - 色合い、白、黒を有する色のインデックスを得る
    • imagecolordeallocate - イメージの色リソースを開放する
    • imagecolorexact - 指定した色のインデックスを取得する
    • imagecolorexactalpha - 指定した色+アルファ値のインデックスを取得する
    • imagecolormatch - パレットイメージの色を True カラーイメージに近づける
    • imagecolorresolve - 指定した色または出来るだけ近い色のインデックスを得る
    • imagecolorresolvealpha - 指定した色+アルファ値または最も近い色のインデックスを取得する
    • imagecolorset - 指定したパレットインデックスの色を設定する
    • imagecolorsforindex - カラーインデックスからカラーを取得する
    • imagecolorstotal - 画像パレットの色数を検出する
    • imagecolortransparent - 透明色を定義する
    • imageconvolution - div および offset の係数を使用し、3x3 の畳み込み配列を適用する
    • imagecopy - 画像の一部をコピーする
    • imagecopymerge - イメージの一部をコピー、マージする
    • imagecopymergegray - グレースケールでイメージの一部をコピー、マージする
    • imagecopyresampled - 再サンプリングを行いイメージの一部をコピー、伸縮する
    • imagecopyresized - 画像の一部をコピーしサイズを変更する
    • imagecreate - パレットを使用する新規画像を作成する
    • imagecreatefromavif - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefrombmp - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromgd - GD ファイルまたは URL から新規イメージを生成する
    • imagecreatefromgd2 - GD2 ファイルまたは URL から新規イメージを生成する
    • imagecreatefromgd2part - GD2 ファイルまたは URL の指定した部分から新規イメージを生成する
    • imagecreatefromgif - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromjpeg - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefrompng - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromstring - 文字列の中のイメージストリームから新規イメージを作成する
    • imagecreatefromtga - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromwbmp - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromwebp - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromxbm - 新しい画像をファイルあるいは URL から作成する
    • imagecreatefromxpm - 新しい画像をファイルあるいは URL から作成する
    • imagecreatetruecolor - TrueColor イメージを新規に作成する
    • imagecrop - 指定した矩形に画像をクロップする
    • imagecropauto - 利用可能なモードを指定して、画像を自動的にクロップする
    • imagedashedline - 破線を描画する
    • imagedestroy - 画像を破棄する
    • imageellipse - 楕円を描画する
    • imagefill - 塗り潰す
    • imagefilledarc - 楕円弧を描画し、塗りつぶす
    • imagefilledellipse - 塗りつぶされた楕円を描画する
    • imagefilledpolygon - 塗りつぶした多角形を描画する
    • imagefilledrectangle - 塗りつぶした矩形を描画する
    • imagefilltoborder - 特定色で塗りつぶす
    • imagefilter - 画像にフィルタを適用する
    • imageflip - 指定したモードで画像を反転させる
    • imagefontheight - フォントの高さを取得する
    • imagefontwidth - フォントの幅を取得する
    • imageftbbox - freetype2 によるフォントを用いたテキストを囲む箱を取得する
    • imagefttext - FreeType 2 によるフォントを用いてイメージにテキストを描画する
    • imagegammacorrect - GD イメージにガンマ補正を適用する
    • imagegd - GD イメージをブラウザまたはファイルに出力する
    • imagegd2 - GD2 イメージをブラウザまたはファイルに出力する
    • imagegetclip - 長方形を切り取り、画像として取得する
    • imagegetinterpolation - 補間方法を取得する
    • imagegif - 画像をブラウザあるいはファイルに出力する
    • imagegrabscreen - 画面全体をキャプチャする
    • imagegrabwindow - ウィンドウをキャプチャする
    • imageinterlace - インターレースを有効もしくは無効にする
    • imageistruecolor - 画像が truecolor かどうか調べる
    • imagejpeg - 画像をブラウザあるいはファイルに出力する
    • imagelayereffect - アルファブレンディングフラグを設定し、レイヤ効果を使用する
    • imageline - 直線を描画する
    • imageloadfont - 新しいフォントを読み込む
    • imageopenpolygon - オープンポリゴンを描画する
    • imagepalettecopy - あるイメージから他のイメージにパレットをコピーする
    • imagepalettetotruecolor - パレット形式の画像を true color に変換する
    • imagepng - PNG イメージをブラウザまたはファイルに出力する
    • imagepolygon - 多角形を描画する
    • imagerectangle - 矩形を描画する
    • imageresolution - 画像の解像度を取得/設定する
    • imagerotate - 指定された角度で画像を回転する
    • imagesavealpha - 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する
    • imagescale - 幅と高さを指定して、画像の縮尺を変更する
    • imagesetbrush - 線の描画用にブラシイメージを設定する
    • imagesetclip - 切り取る長方形を設定する
    • imagesetinterpolation - 補間方法を設定する
    • imagesetpixel - 点を生成する
    • imagesetstyle - 線描画用のスタイルを設定する
    • imagesetthickness - 線描画用の線幅を設定する
    • imagesettile - 塗りつぶし用のイメージを設定する
    • imagestring - 文字列を水平に描画する
    • imagestringup - 文字列を垂直に描画する
    • imagesx - 画像の幅を取得する
    • imagesy - 画像の高さを取得する
    • imagetruecolortopalette - TrueColor イメージをパレットイメージに変換する
    • imagettfbbox - TypeType フォントを使用したテキストの bounding box を生成する
    • imagettftext - TrueType フォントを使用してテキストを画像に書き込む
    • imagetypes - この PHP がサポートしている画像形式を返す
    • imagewbmp - 画像をブラウザあるいはファイルに出力する
    • imagewebp - WebP 画像をブラウザあるいはファイルに出力する
    • imagexbm - XBM 画像をブラウザあるいはファイルに出力する
    • image_type_to_extension - 画像形式からファイルの拡張子を取得する
    • image_type_to_mime_type - getimagesize, exif_read_data, exif_thumbnail, exif_imagetypeから返される 画像形式のMIMEタイプを取得する
    • Imagick::adaptiveBlurImage - adaptive blur (順応性にじみ) フィルタを画像に追加する
    • Imagick::adaptiveResizeImage - データに依存する三角測量にもとづいて画像のサイズを変更する
    • Imagick::adaptiveSharpenImage - 順応して画像をシャープにする
    • Imagick::adaptiveThresholdImage - 輝度の範囲にもとづいて各ピクセルの閾値を選択する
    • Imagick::addImage - 新しい画像を Imagick オブジェクトの画像リストに追加する
    • Imagick::addNoiseImage - ランダムなノイズを画像に追加する
    • Imagick::affineTransformImage - 画像を変換する
    • Imagick::animateImages - 画像を動かす
    • Imagick::annotateImage - 画像にテキストによる注記を加える
    • Imagick::appendImages - 画像群を追加する
    • Imagick::autoLevelImage - Adjusts the levels of a particular image channel
    • Imagick::averageImages - 画像群を平均化する
    • Imagick::blackThresholdImage - 閾値に満たないすべてのピクセルを黒にする
    • Imagick::blueShiftImage - Mutes the colors of the image
    • Imagick::blurImage - blur (にじみ) フィルタを画像に追加する
    • Imagick::borderImage - 画像の周りを枠線で囲む
    • Imagick::brightnessContrastImage - Change the brightness and/or contrast of an image
    • Imagick::charcoalImage - 木炭画をシミュレートする
    • Imagick::chopImage - 画像の一部を取り除き、切り詰める
    • Imagick::clampImage - Restricts the color range from 0 to the quantum depth.
    • Imagick::clear - Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
    • Imagick::clipImage - 8BIM プロファイルの最初のパスにそって切り取る
    • Imagick::clipImagePath - Clips along the named paths from the 8BIM profile, if present
    • Imagick::clipPathImage - 8BIM プロファイルの指定した名前のパスにそって切り取る
    • Imagick::clone - Imagick オブジェクトの完全なコピーを作成する
    • Imagick::clutImage - 画像の色を置き換える
    • Imagick::coalesceImages - 複数の画像を合成する
    • Imagick::colorFloodfillImage - 対象にマッチする任意の点の色の値を変更する
    • Imagick::colorizeImage - 塗りつぶし色と画像を混合する
    • Imagick::colorMatrixImage - Apply color transformation to an image
    • Imagick::combineImages - ひとつあるいは複数の画像をひとつにまとめる
    • Imagick::commentImage - コメントを画像に追加する
    • Imagick::compareImageChannels - ひとつあるいは複数の画像の差を返す
    • Imagick::compareImageLayers - 複数の画像の中で最大の境界範囲を返す
    • Imagick::compareImages - ある画像を再構築された画像と比較する
    • Imagick::compositeImage - ある画像を別の画像に合成する
    • Imagick::contrastImage - 画像のコントラストを変更する
    • Imagick::contrastStretchImage - カラー画像のコントラストを強調する
    • Imagick::convolveImage - 独自の畳み込み関数を画像に適用する
    • Imagick::count - Get the number of images
    • Imagick::cropImage - 画像の一部を抽出する
    • Imagick::cropThumbnailImage - 切り取ってサムネイルを作成する
    • Imagick::current - 現在の Imagick オブジェクトへの参照を返す
    • Imagick::cycleColormapImage - 画像のカラーマップを移動する
    • Imagick::decipherImage - 画像を復号する
    • Imagick::deconstructImages - 画像間の特定のピクセルの差を返す
    • Imagick::deleteImageArtifact - 画像のアーチファクトを削除する
    • Imagick::deleteImageProperty - Deletes an image property
    • Imagick::deskewImage - 傾きを除去する
    • Imagick::despeckleImage - 画像内のスペックルノイズを軽減する
    • Imagick::destroy - Imagick オブジェクトを破棄する
    • Imagick::displayImage - 画像を表示する
    • Imagick::displayImages - 画像あるいは画像シーケンスを表示する
    • Imagick::distortImage - さまざまな方式で画像を歪める
    • Imagick::drawImage - 現在の画像上の ImagickDraw オブジェクトをレンダリングする
    • Imagick::edgeImage - 画像の輪郭を強調する
    • Imagick::embossImage - グレースケール画像に三次元効果を施して返す
    • Imagick::encipherImage - 画像を暗号化する
    • Imagick::enhanceImage - ノイジーな画像の品質を向上させる
    • Imagick::equalizeImage - 画像ヒストグラムを均等化する
    • Imagick::evaluateImage - 式を画像に適用する
    • Imagick::exportImagePixels - 画像の生のピクセルをエクスポートする
    • Imagick::extentImage - 画像のサイズを設定する
    • Imagick::filter - Applies a custom convolution kernel to the image
    • Imagick::flattenImages - 画像シーケンスをマージする
    • Imagick::flipImage - 垂直方向に反転した画像を作成する
    • Imagick::floodFillPaintImage - 対象にマッチする任意のピクセルの値を変更する
    • Imagick::flopImage - 水平方向に反転した画像を作成する
    • Imagick::forwardFourierTransformImage - Implements the discrete Fourier transform (DFT)
    • Imagick::frameImage - 三次元の枠線をシミュレートする
    • Imagick::functionImage - 画像に関数を適用する
    • Imagick::fxImage - 式を画像の各ピクセルに適用する
    • Imagick::gammaImage - 画像をガンマ補正する
    • Imagick::gaussianBlurImage - 画像をぼかす
    • Imagick::getColorspace - 色空間を取得する
    • Imagick::getCompression - オブジェクトの圧縮形式を取得する
    • Imagick::getCompressionQuality - オブジェクトの圧縮品質を取得する
    • Imagick::getCopyright - ImageMagick API の著作権情報を文字列で返す
    • Imagick::getFilename - 画像シーケンスに関連付けられたファイル名を取得する
    • Imagick::getFont - フォントを取得する
    • Imagick::getFormat - Imagick オブジェクトのフォーマットを取得する
    • Imagick::getGravity - gravity を取得する
    • Imagick::getHomeURL - ImageMagick のホーム URL を返す
    • Imagick::getImage - 新しい Imagick オブジェクトを返す
    • Imagick::getImageAlphaChannel - 画像がアルファチャネルを持つかを調べる
    • Imagick::getImageArtifact - 画像のアーチファクトを取得する
    • Imagick::getImageAttribute - Returns a named attribute
    • Imagick::getImageBackgroundColor - 画像の背景色を返す
    • Imagick::getImageBlob - 画像シーケンスを blob で返す
    • Imagick::getImageBluePrimary - 青が一番強い点を返す
    • Imagick::getImageBorderColor - 画像の前景色を返す
    • Imagick::getImageChannelDepth - 特定の画像チャネルの深度を返す
    • Imagick::getImageChannelDistortion - 画像のチャネルを再構築した画像と比較する
    • Imagick::getImageChannelDistortions - チャネルの歪みを取得する
    • Imagick::getImageChannelExtrema - ひとつあるいは複数の画像チャネルの極値を取得する
    • Imagick::getImageChannelKurtosis - getImageChannelKurtosis
    • Imagick::getImageChannelMean - 平均値と標準偏差を取得する
    • Imagick::getImageChannelRange - チャネルの範囲を取得する
    • Imagick::getImageChannelStatistics - 画像の各チャネルの統計情報を返す
    • Imagick::getImageClipMask - 画像のクリップマスクを取得する
    • Imagick::getImageColormapColor - 指定したインデックスに対応する色マップ上の色を返す
    • Imagick::getImageColors - 画像で使われている色の数を取得する
    • Imagick::getImageColorspace - 画像の色空間を取得する
    • Imagick::getImageCompose - 画像の合成演算子を返す
    • Imagick::getImageCompression - 現在の画像の圧縮形式を取得する
    • Imagick::getImageCompressionQuality - 現在の画像の圧縮品質を取得する
    • Imagick::getImageDelay - 画像の遅延を取得する
    • Imagick::getImageDepth - 画像の深度を取得する
    • Imagick::getImageDispose - 画像の配置方法を取得する
    • Imagick::getImageDistortion - ある画像と再構築した画像を比較する
    • Imagick::getImageExtrema - 画像の極値を取得する
    • Imagick::getImageFilename - シーケンス内の特定の画像のファイル名を返す
    • Imagick::getImageFormat - シーケンス内の特定の画像のフォーマットを返す
    • Imagick::getImageGamma - 画像のガンマを取得する
    • Imagick::getImageGeometry - 幅と高さを連想配列で取得する
    • Imagick::getImageGravity - 画像の gravity を取得する
    • Imagick::getImageGreenPrimary - 緑が一番強い点を返す
    • Imagick::getImageHeight - 画像の高さを返す
    • Imagick::getImageHistogram - 画像のヒストグラムを取得する
    • Imagick::getImageIndex - 現在アクティブな画像のインデックスを取得する
    • Imagick::getImageInterlaceScheme - 画像のインターレース手法を取得する
    • Imagick::getImageInterpolateMethod - 画像の補間方式を返す
    • Imagick::getImageIterations - 画像の反復を取得する
    • Imagick::getImageLength - 画像の長さをバイト数で取得する
    • Imagick::getImageMatte - 画像がマットチャネルを持っているかどうかを返す
    • Imagick::getImageMatteColor - 画像のマット色を返す
    • Imagick::getImageMimeType - Returns the image mime-type
    • Imagick::getImageOrientation - 画像の方向を取得する
    • Imagick::getImagePage - ページのジオメトリを返す
    • Imagick::getImagePixelColor - 指定したピクセルの色を返す
    • Imagick::getImageProfile - 指定した名前の画像プロファイルを返す
    • Imagick::getImageProfiles - 画像プロファイルを返す
    • Imagick::getImageProperties - 画像のプロパティを返す
    • Imagick::getImageProperty - 指定した名前の画像のプロパティを返す
    • Imagick::getImageRedPrimary - 赤が一番強い点を返す
    • Imagick::getImageRegion - 画像の一部を抽出する
    • Imagick::getImageRenderingIntent - 画像のレンダリング方向を取得する
    • Imagick::getImageResolution - 画像の X 方向と Y 方向の解像度を取得する
    • Imagick::getImagesBlob - すべての画像シーケンスを blob で返す
    • Imagick::getImageScene - 画像のシーンを取得する
    • Imagick::getImageSignature - SHA-256 メッセージダイジェストを生成する
    • Imagick::getImageSize - 画像の長さをバイト数で返す
    • Imagick::getImageTicksPerSecond - 画像の ticks-per-second を取得する
    • Imagick::getImageTotalInkDensity - 画像の総インク密度を取得する
    • Imagick::getImageType - 画像の型を取得する
    • Imagick::getImageUnits - 画像の解像度の単位を取得する
    • Imagick::getImageVirtualPixelMethod - 仮想ピクセルメソッドを取得する
    • Imagick::getImageWhitePoint - 色度が白い点を返す
    • Imagick::getImageWidth - 画像の幅を返す
    • Imagick::getInterlaceScheme - オブジェクトのインターレース方式を取得する
    • Imagick::getIteratorIndex - 現在アクティブな画像のインデックスを取得する
    • Imagick::getNumberImages - オブジェクト内の画像の数を返す
    • Imagick::getOption - 指定したキーに対応する値を返す
    • Imagick::getPackageName - ImageMagick パッケージ名を返す
    • Imagick::getPage - ページのジオメトリを返す
    • Imagick::getPixelIterator - MagickPixelIterator を返す
    • Imagick::getPixelRegionIterator - 画像セクションの ImagickPixelIterator を取得する
    • Imagick::getPointSize - ポイントサイズを取得する
    • Imagick::getQuantum - Returns the ImageMagick quantum range
    • Imagick::getQuantumDepth - quantum depth を取得する
    • Imagick::getQuantumRange - Imagick quantum range を返す
    • Imagick::getRegistry - Get a StringRegistry entry
    • Imagick::getReleaseDate - ImageMagick のリリース日を返す
    • Imagick::getResource - 指定したリソースのメモリ使用状況を返す
    • Imagick::getResourceLimit - 指定したリソースの制限を返す
    • Imagick::getSamplingFactors - 水平方向および垂直方向のサンプリング係数を取得する
    • Imagick::getSize - Returns the size associated with the Imagick object
    • Imagick::getSizeOffset - サイズのオフセットを返す
    • Imagick::getVersion - ImageMagick API のバージョンを返す
    • Imagick::haldClutImage - 画像内の色を置換する
    • Imagick::hasNextImage - オブジェクトが次の画像を保持しているかどうかを調べる
    • Imagick::hasPreviousImage - オブジェクトが前の画像を保持しているかどうかを調べる
    • Imagick::identifyFormat - Formats a string with image details
    • Imagick::identifyImage - 画像を識別し、属性を取得する
    • Imagick::implodeImage - 新しい画像をコピーとして作成する
    • Imagick::importImagePixels - 画像のピクセルをインポートする
    • Imagick::inverseFourierTransformImage - Implements the inverse discrete Fourier transform (DFT)
    • Imagick::labelImage - ラベルを画像に追加する
    • Imagick::levelImage - 画像のレベルを調節する
    • Imagick::linearStretchImage - 画像の輝度を引き伸ばして飽和させる
    • Imagick::liquidRescaleImage - 画像を動かす
    • Imagick::listRegistry - List all the registry settings
    • Imagick::magnifyImage - 画像を 2 倍に比例拡大する
    • Imagick::mapImage - 画像の色を、参照画像の中の最も近い色に置き換える
    • Imagick::matteFloodfillImage - 色の透明度を変更する
    • Imagick::medianFilterImage - デジタルフィルタを適用する
    • Imagick::mergeImageLayers - 画像のレイヤーをマージする
    • Imagick::minifyImage - 画像をその半分のサイズに比例縮小する
    • Imagick::modulateImage - 明度、飽和度、色相を制御する
    • Imagick::montageImage - 合成画像を作成する
    • Imagick::morphImages - 複数の画像をモーフィングする
    • Imagick::morphology - Applies a user supplied kernel to the image according to the given morphology method.
    • Imagick::mosaicImages - 画像からモザイクを作成する
    • Imagick::motionBlurImage - モーションブラーをシミュレートする
    • Imagick::negateImage - 画像の色を打ち消す
    • Imagick::newImage - 新しい画像を作成する
    • Imagick::newPseudoImage - 新しい画像を作成する
    • Imagick::nextImage - 次の画像に移動する
    • Imagick::normalizeImage - カラー画像のコントラストを強調する
    • Imagick::oilPaintImage - 油絵をシミュレートする
    • Imagick::opaquePaintImage - 対象にマッチする任意のピクセルの色を変更する
    • Imagick::optimizeImageLayers - 画像の繰り返し部分を削除して最適化する
    • Imagick::orderedPosterizeImage - 配列ディザリングを行う
    • Imagick::paintFloodfillImage - 色にマッチするピクセルを変更する
    • Imagick::paintOpaqueImage - 色にマッチするピクセルを変更する
    • Imagick::paintTransparentImage - 色にマッチするピクセルを塗りつぶし色に変更する
    • Imagick::pingImage - 画像の基本属性を取得する
    • Imagick::pingImageBlob - 手早く属性を取得する
    • Imagick::pingImageFile - 画像の基本属性を手軽に取得する
    • Imagick::polaroidImage - ポラロイド写真をシミュレートする
    • Imagick::posterizeImage - 指定した色数まで画像を減色する
    • Imagick::previewImages - 画像処理用の適切なパラメータを手早く取得する
    • Imagick::previousImage - オブジェクト内の前の画像に移動する
    • Imagick::profileImage - 画像のプロファイルを追加あるいは削除する
    • Imagick::quantizeImage - 参照画像内の色を解析する
    • Imagick::quantizeImages - 画像シーケンス内の色を解析する
    • Imagick::queryFontMetrics - フォントメトリクスを表す配列を返す
    • Imagick::queryFonts - 設定したフォントを返す
    • Imagick::queryFormats - Imagick がサポートするフォーマットを返す
    • Imagick::radialBlurImage - 画像にラジアルブラーを施す
    • Imagick::raiseImage - 三次元のボタン風の効果をシミュレートする
    • Imagick::randomThresholdImage - コントラストの高い 2 色の画像を作成する
    • Imagick::readImage - ファイルから画像を読み込む
    • Imagick::readImageBlob - バイナリ文字列から画像を読み込む
    • Imagick::readImageFile - オープンしているファイルハンドルから画像を読み込む
    • Imagick::readimages - Reads image from an array of filenames
    • Imagick::recolorImage - 画像の色を変更する
    • Imagick::reduceNoiseImage - 画像の輪郭をなめらかにする
    • Imagick::remapImage - 画像の色を再配置する
    • Imagick::removeImage - 画像リストから画像を削除する
    • Imagick::removeImageProfile - 指定した名前の画像プロファイルを削除してそれを返す
    • Imagick::render - それまでのすべての描画コマンドをレンダリングする
    • Imagick::resampleImage - 画像を指定した解像度にリサンプリングする
    • Imagick::resetImagePage - 画像のページをリセットする
    • Imagick::resizeImage - 画像のサイズを変更する
    • Imagick::rollImage - 画像を補正する
    • Imagick::rotateImage - 画像を回転する
    • Imagick::rotationalBlurImage - Rotational blurs an image
    • Imagick::roundCorners - 画像の角を丸める
    • Imagick::sampleImage - ピクセルのサンプリングによって画像の倍率を変更する
    • Imagick::scaleImage - 画像のサイズを変更する
    • Imagick::segmentImage - 画像を分割する
    • Imagick::selectiveBlurImage - Selectively blur an image within a contrast threshold
    • Imagick::separateImageChannel - 画像からチャネルを分離する
    • Imagick::sepiaToneImage - 画像をセピア調にする
    • Imagick::setBackgroundColor - オブジェクトのデフォルト背景色を設定する
    • Imagick::setColorspace - 色空間を設定する
    • Imagick::setCompression - オブジェクトのデフォルトの圧縮方式を設定する
    • Imagick::setCompressionQuality - オブジェクトのデフォルトの圧縮品質を設定する
    • Imagick::setFilename - 画像を読み書きする前にファイル名を設定する
    • Imagick::setFirstIterator - Imagick イテレータを最初の画像に設定する
    • Imagick::setFont - フォントを設定する
    • Imagick::setFormat - Imagick オブジェクトのフォーマットを設定する
    • Imagick::setGravity - gravity を設定する
    • Imagick::setImage - オブジェクト内の画像を置き換える
    • Imagick::setImageAlphaChannel - 画像のアルファチャネルを設定する
    • Imagick::setImageArtifact - 画像のアーチファクトを設定する
    • Imagick::setImageAttribute - Sets an image attribute
    • Imagick::setImageBackgroundColor - 画像の背景色を設定する
    • Imagick::setImageBias - 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
    • Imagick::setImageBiasQuantum - Sets the image bias
    • Imagick::setImageBluePrimary - 青が一番強い点を設定する
    • Imagick::setImageBorderColor - 画像の前景色を設定する
    • Imagick::setImageChannelDepth - 特定の画像チャネルの深度を設定する
    • Imagick::setImageClipMask - 画像のクリップマスクを設定する
    • Imagick::setImageColormapColor - 指定した色マップインデックスの色を設定する
    • Imagick::setImageColorspace - 画像の色空間を設定する
    • Imagick::setImageCompose - 画像の合成演算子を設定する
    • Imagick::setImageCompression - 画像の圧縮を設定する
    • Imagick::setImageCompressionQuality - 画像の圧縮品質を設定する
    • Imagick::setImageDelay - 画像の遅延を設定する
    • Imagick::setImageDepth - 画像の深度を設定する
    • Imagick::setImageDispose - 画像の配置方法を設定する
    • Imagick::setImageExtent - 画像のサイズを設定する
    • Imagick::setImageFilename - 特定の画像のファイル名を設定する
    • Imagick::setImageFormat - 特定の画像のフォーマットを設定する
    • Imagick::setImageGamma - 画像のガンマを設定する
    • Imagick::setImageGravity - 画像の gravity を設定する
    • Imagick::setImageGreenPrimary - 緑が一番強い点を設定する
    • Imagick::setImageIndex - イテレータの位置を設定する
    • Imagick::setImageInterlaceScheme - 画像のインターレース手法を設定する
    • Imagick::setImageInterpolateMethod - 画像のピクセル補間方式を設定する
    • Imagick::setImageIterations - 画像の反復を設定する
    • Imagick::setImageMatte - 画像のマットチャネルを設定する
    • Imagick::setImageMatteColor - 画像のマット色を設定する
    • Imagick::setImageOpacity - 画像の不透明度を設定する
    • Imagick::setImageOrientation - 画像の方向を設定する
    • Imagick::setImagePage - 画像のページのジオメトリを設定する
    • Imagick::setImageProfile - 指定した名前の画像プロファイルを Imagick オブジェクトに追加する
    • Imagick::setImageProperty - 画像のプロパティを設定する
    • Imagick::setImageRedPrimary - 赤が一番強い点を設定する
    • Imagick::setImageRenderingIntent - 画像のレンダリング方向を設定する
    • Imagick::setImageResolution - 画像の解像度を設定する
    • Imagick::setImageScene - 画像のシーンを設定する
    • Imagick::setImageTicksPerSecond - 画像の ticks-per-second を設定する
    • Imagick::setImageType - 画像の型を設定する
    • Imagick::setImageUnits - 画像の解像度の単位を設定する
    • Imagick::setImageVirtualPixelMethod - 画像の仮想ピクセルメソッドを設定する
    • Imagick::setImageWhitePoint - 画像の色度が白い点を設定する
    • Imagick::setInterlaceScheme - 画像の圧縮を設定する
    • Imagick::setIteratorIndex - イテレータの位置を設定する
    • Imagick::setLastIterator - Imagick イテレータを最後の画像に設定する
    • Imagick::setOption - オプションを設定する
    • Imagick::setPage - Imagick オブジェクトのページジオメトリを設定する
    • Imagick::setPointSize - ポイントサイズを設定する
    • Imagick::setProgressMonitor - Set a callback to be called during processing
    • Imagick::setRegistry - Sets the ImageMagick registry entry named key to value
    • Imagick::setResolution - 画像の解像度を設定する
    • Imagick::setResourceLimit - 特定のリソースの制限を設定する
    • Imagick::setSamplingFactors - 画像のサンプリング係数を設定する
    • Imagick::setSize - Imagick オブジェクトのサイズを設定する
    • Imagick::setSizeOffset - Imagick オブジェクトのサイズのオフセットを設定する
    • Imagick::setType - 画像タイプ属性を設定する
    • Imagick::shadeImage - 3D 効果を作成する
    • Imagick::shadowImage - 画像の影をシミュレートする
    • Imagick::sharpenImage - 画像をシャープにする
    • Imagick::shaveImage - 画像の輪郭からピクセルを刈り取る
    • Imagick::shearImage - 平行四辺形を作成する
    • Imagick::sigmoidalContrastImage - 画像のコントラストを調整する
    • Imagick::sketchImage - 鉛筆画をシミュレートする
    • Imagick::smushImages - Takes all images from the current image pointer to the end of the image list and smushs them
    • Imagick::solarizeImage - 画像にソラリゼーション効果を適用する
    • Imagick::sparseColorImage - 色を補間する
    • Imagick::spliceImage - 無地の画像を作成する
    • Imagick::spreadImage - ブロック内の各ピクセルをランダムに移動する
    • Imagick::statisticImage - Modifies image using a statistics function
    • Imagick::steganoImage - デジタル透かしを画像に埋め込む
    • Imagick::stereoImage - ふたつの画像を合成する
    • Imagick::stripImage - 画像からすべてのプロパティやコメントを除去する
    • Imagick::subImageMatch - Searches for a subimage in the current image and returns a similarity image
    • Imagick::swirlImage - 画像の中心から、ピクセルを渦巻状にする
    • Imagick::textureImage - テクスチャ画像をタイル状に並べる
    • Imagick::thresholdImage - 閾値にもとづいて個々のピクセルの値を変更する
    • Imagick::thumbnailImage - 画像のサイズを変更する
    • Imagick::tintImage - 色ベクトルを画像の各ピクセルに適用する
    • Imagick::transformImage - 切り取るサイズと画像のジオメトリを設定する便利なメソッド
    • Imagick::transformImageColorspace - Transforms an image to a new colorspace
    • Imagick::transparentPaintImage - ピクセルを透過させる
    • Imagick::transposeImage - 垂直方向に反転させた画像を作成する
    • Imagick::transverseImage - 水平方向に反転させた画像を作成する
    • Imagick::trimImage - 画像の輪郭を削除する
    • Imagick::uniqueImageColors - ある 1 色以外のすべての色のピクセルを削除する
    • Imagick::unsharpMaskImage - 画像をシャープにする
    • Imagick::valid - 現在のアイテムが有効かどうかを調べる
    • Imagick::vignetteImage - ビネットフィルタを画像に追加する
    • Imagick::waveImage - ウェーブフィルタを画像に適用する
    • Imagick::whiteThresholdImage - 閾値に満たないすべてのピクセルを白にする
    • Imagick::writeImage - 指定した名前で画像を書き込む
    • Imagick::writeImageFile - 画像をファイルハンドルに書き出す
    • Imagick::writeImages - 画像あるいは画像シーケンスを書き込む
    • Imagick::writeImagesFile - フレームをファイルハンドルに書き出す
    • Imagick::__construct - Imagick のコンストラクタ
    • Imagick::__toString - Returns the image as a string
    • ImagickDraw::affine - 現在のアフィン変換行列を設定する
    • ImagickDraw::annotation - 画像上にテキストを描画する
    • ImagickDraw::arc - 円弧を描画する
    • ImagickDraw::bezier - ベジエ曲線を描画する
    • ImagickDraw::circle - 円を描画する
    • ImagickDraw::clear - ImagickDraw をクリアする
    • ImagickDraw::clone - 指定した ImagickDraw オブジェクトの完全なコピーを作成する
    • ImagickDraw::color - 画像上に色を描画する
    • ImagickDraw::comment - コメントを追加する
    • ImagickDraw::composite - 現在の画像上に別の画像を合成する
    • ImagickDraw::destroy - 関連付けられたすべてのリソースを開放する
    • ImagickDraw::ellipse - 画像上に楕円を描画する
    • ImagickDraw::getClipPath - 現在のクリッピングパスの ID を取得する
    • ImagickDraw::getClipRule - 現在の多角形塗りつぶしルールを返す
    • ImagickDraw::getClipUnits - クリップパスの単位の解釈を返す
    • ImagickDraw::getFillColor - 塗りつぶし色を返す
    • ImagickDraw::getFillOpacity - 描画時の透過度を返す
    • ImagickDraw::getFillRule - 塗りつぶしルールを返す
    • ImagickDraw::getFont - フォントを返す
    • ImagickDraw::getFontFamily - フォントファミリーを返す
    • ImagickDraw::getFontSize - フォントのポイント数を返す
    • ImagickDraw::getFontStretch - Gets the font stretch to use when annotating with text
    • ImagickDraw::getFontStyle - フォントのスタイルを返す
    • ImagickDraw::getFontWeight - フォントの重さを返す
    • ImagickDraw::getGravity - テキストの配置時の gravity を返す
    • ImagickDraw::getStrokeAntialias - 現在の縁取りのアンチエイリアス設定を返す
    • ImagickDraw::getStrokeColor - オブジェクトの縁取りに使用する色を返す
    • ImagickDraw::getStrokeDashArray - パスの描画に使用する破線のパターンを表す配列を返す
    • ImagickDraw::getStrokeDashOffset - 破線パターンにおける破線の開始オフセットを返す
    • ImagickDraw::getStrokeLineCap - 開かれたサブパスを描画する際に使用する端点の形状を返す
    • ImagickDraw::getStrokeLineJoin - パスの角を描画する際に使用する形状を返す
    • ImagickDraw::getStrokeMiterLimit - マイターリミットを返す
    • ImagickDraw::getStrokeOpacity - オブジェクトの枠線の透明度を返す
    • ImagickDraw::getStrokeWidth - オブジェクトの枠線の描画に使用する線の幅を返す
    • ImagickDraw::getTextAlignment - テキストの配置を返す
    • ImagickDraw::getTextAntialias - 現在のテキストのアンチエイリアス設定を返す
    • ImagickDraw::getTextDecoration - テキストの装飾を返す
    • ImagickDraw::getTextEncoding - テキストによる注記の際に使用するコードセットを返す
    • ImagickDraw::getTextInterlineSpacing - Gets the text interword spacing
    • ImagickDraw::getTextInterwordSpacing - Gets the text interword spacing
    • ImagickDraw::getTextKerning - Gets the text kerning
    • ImagickDraw::getTextUnderColor - テキストの背景色を返す
    • ImagickDraw::getVectorGraphics - ベクターグラフィックを含む文字列を返す
    • ImagickDraw::line - 直線を描画する
    • ImagickDraw::matte - 画像の opacity チャネル上に描画する
    • ImagickDraw::pathClose - パス要素を現在のパスに追加する
    • ImagickDraw::pathCurveToAbsolute - 三次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierAbsolute - 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierRelative - 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute - 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToQuadraticBezierSmoothRelative - 二次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToRelative - 三次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToSmoothAbsolute - 三次ベジエ曲線を描画する
    • ImagickDraw::pathCurveToSmoothRelative - 三次ベジエ曲線を描画する
    • ImagickDraw::pathEllipticArcAbsolute - 楕円弧を描画する
    • ImagickDraw::pathEllipticArcRelative - 楕円弧を描画する
    • ImagickDraw::pathFinish - 現在のパスを終了する
    • ImagickDraw::pathLineToAbsolute - 直線パスを描画する
    • ImagickDraw::pathLineToHorizontalAbsolute - 水平直線パスを描画する
    • ImagickDraw::pathLineToHorizontalRelative - 水平直線パスを描画する
    • ImagickDraw::pathLineToRelative - 直線パスを描画する
    • ImagickDraw::pathLineToVerticalAbsolute - 垂直直線パスを描画する
    • ImagickDraw::pathLineToVerticalRelative - 垂直直線パスを描画する
    • ImagickDraw::pathMoveToAbsolute - 新しいサブパスを開始する
    • ImagickDraw::pathMoveToRelative - 新しいサブパスを開始する
    • ImagickDraw::pathStart - パス描画リストの開始を宣言する
    • ImagickDraw::point - 点を描画する
    • ImagickDraw::polygon - 多角形を描画する
    • ImagickDraw::polyline - 線分群を描画する
    • ImagickDraw::pop - スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す
    • ImagickDraw::popClipPath - クリップパスの定義を終了する
    • ImagickDraw::popDefs - 定義リストを終了する
    • ImagickDraw::popPattern - パターン定義を終了する
    • ImagickDraw::push - 現在の ImagickDraw をコピーしてスタックに格納する
    • ImagickDraw::pushClipPath - クリップパスの定義を開始する
    • ImagickDraw::pushDefs - 後に続くコマンドが、処理の前に名前つき要素を作成することを示す
    • ImagickDraw::pushPattern - 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す
    • ImagickDraw::rectangle - 矩形を描画する
    • ImagickDraw::render - これまでのすべての描画コマンドを画像上にレンダリングする
    • ImagickDraw::resetVectorGraphics - Resets the vector graphics
    • ImagickDraw::rotate - 指定した回転を現在の座標空間に適用する
    • ImagickDraw::roundRectangle - 角が丸い矩形を描画する
    • ImagickDraw::scale - 倍率を調整する
    • ImagickDraw::setClipPath - 指定した名前のクリッピングパスを画像に関連付ける
    • ImagickDraw::setClipRule - クリッピングパスで使用する多角形塗りつぶしルールを設定する
    • ImagickDraw::setClipUnits - クリップパスの単位の解釈を設定する
    • ImagickDraw::setFillAlpha - 色やテクスチャによる塗りつぶしの際の透過度を設定する
    • ImagickDraw::setFillColor - オブジェクトの塗りつぶしに使用する色を設定する
    • ImagickDraw::setFillOpacity - 色やテクスチャによる塗りつぶしの際の透過度を設定する
    • ImagickDraw::setFillPatternURL - オブジェクトの塗りつぶしパターンとして使用する URL を設定する
    • ImagickDraw::setFillRule - 多角形の描画時に使用する塗りつぶしルールを設定する
    • ImagickDraw::setFont - テキストによる注記を行う際に使用するフォントを設定する
    • ImagickDraw::setFontFamily - テキストによる注記を行う際に使用するフォントファミリーを設定する
    • ImagickDraw::setFontSize - テキストによる注記を行う際に使用するフォントのポイント数を設定する
    • ImagickDraw::setFontStretch - テキストによる注記を行う際に使用するフォントの伸縮を設定する
    • ImagickDraw::setFontStyle - テキストによる注記を行う際に使用するフォントのスタイルを設定する
    • ImagickDraw::setFontWeight - フォントの重さを設定する
    • ImagickDraw::setGravity - テキストの配置時の gravity を設定する
    • ImagickDraw::setResolution - Sets the resolution
    • ImagickDraw::setStrokeAlpha - オブジェクトの枠線の透明度を指定する
    • ImagickDraw::setStrokeAntialias - 縁取りの枠線をアンチエイリアス処理するかどうかを制御する
    • ImagickDraw::setStrokeColor - オブジェクトの縁取りに使用する色を設定する
    • ImagickDraw::setStrokeDashArray - パスの描画に使用する破線のパターンを指定する
    • ImagickDraw::setStrokeDashOffset - 破線パターンにおける破線の開始オフセットを指定する
    • ImagickDraw::setStrokeLineCap - 開かれたサブパスを描画する際に使用する端点の形状を指定する
    • ImagickDraw::setStrokeLineJoin - パスの角を描画する際に使用する形状を指定する
    • ImagickDraw::setStrokeMiterLimit - マイターリミットを指定する
    • ImagickDraw::setStrokeOpacity - オブジェクトの枠線の透明度を指定する
    • ImagickDraw::setStrokePatternURL - オブジェクトの枠線の描画に使用するパターンを設定する
    • ImagickDraw::setStrokeWidth - オブジェクトの枠線の描画に使用する線の幅を設定する
    • ImagickDraw::setTextAlignment - テキストの配置を指定する
    • ImagickDraw::setTextAntialias - テキストをアンチエイリアス処理するかどうかを制御する
    • ImagickDraw::setTextDecoration - 装飾を指定する
    • ImagickDraw::setTextEncoding - テキストのコードセットを指定する
    • ImagickDraw::setTextInterlineSpacing - Sets the text interline spacing
    • ImagickDraw::setTextInterwordSpacing - Sets the text interword spacing
    • ImagickDraw::setTextKerning - Sets the text kerning
    • ImagickDraw::setTextUnderColor - 背景の矩形の色を指定する
    • ImagickDraw::setVectorGraphics - ベクターグラフィックを設定する
    • ImagickDraw::setViewbox - キャンバス全体の大きさを設定する
    • ImagickDraw::skewX - 現在の座標系を水平方向に傾ける
    • ImagickDraw::skewY - 現在の座標系を垂直方向に傾ける
    • ImagickDraw::translate - 現在の座標系に変換を適用する
    • ImagickDraw::__construct - ImagickDraw コンストラクタ
    • ImagickKernel::addKernel - Attach another kernel to a kernel list
    • ImagickKernel::addUnityKernel - Adds a Unity Kernel to the kernel list
    • ImagickKernel::fromBuiltIn - Create a kernel from a builtin in kernel
    • ImagickKernel::fromMatrix - Create a kernel from a 2d matrix of values
    • ImagickKernel::getMatrix - Get the 2d matrix of values used in this kernel
    • ImagickKernel::scale - Scales a kernel list by the given amount
    • ImagickKernel::separate - Separates a linked set of kernels and returns an array of ImagickKernels
    • ImagickPixel::clear - このオブジェクトに関連付けられたリソースを消去する
    • ImagickPixel::destroy - このオブジェクトに関連付けられているリソースの割り当てを解除する
    • ImagickPixel::getColor - 色を返す
    • ImagickPixel::getColorAsString - 色を文字列で返す
    • ImagickPixel::getColorCount - この色に関連付けられている色カウントを返す
    • ImagickPixel::getColorQuantum - Returns the color of the pixel in an array as Quantum values
    • ImagickPixel::getColorValue - 指定した色チャネルの値を正規化したものを取得する
    • ImagickPixel::getColorValueQuantum - Gets the quantum value of a color in the ImagickPixel
    • ImagickPixel::getHSL - ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
    • ImagickPixel::getIndex - Gets the colormap index of the pixel wand
    • ImagickPixel::isPixelSimilar - Check the distance between this color and another
    • ImagickPixel::isPixelSimilarQuantum - Returns whether two colors differ by less than the specified distance
    • ImagickPixel::isSimilar - この色と別の色の差を調べる
    • ImagickPixel::setColor - 色を設定する
    • ImagickPixel::setColorCount - Sets the color count associated with this color
    • ImagickPixel::setColorValue - 指定したチャネルの正規化した値を設定する
    • ImagickPixel::setColorValueQuantum - Sets the quantum value of a color element of the ImagickPixel
    • ImagickPixel::setHSL - 正規化した HSL カラーを設定する
    • ImagickPixel::setIndex - Sets the colormap index of the pixel wand
    • ImagickPixel::__construct - ImagickPixel のコンストラクタ
    • ImagickPixelIterator::clear - PixelIterator に関連付けられたリソースを消去する
    • ImagickPixelIterator::destroy - PixelIterator に関連付けられているリソースの割り当てを解除する
    • ImagickPixelIterator::getCurrentIteratorRow - ImagickPixel オブジェクトの現在の行を返す
    • ImagickPixelIterator::getIteratorRow - pixel iterator の現在の行を返す
    • ImagickPixelIterator::getNextIteratorRow - pixel iterator の次の行を返す
    • ImagickPixelIterator::getPreviousIteratorRow - 前の行を返す
    • ImagickPixelIterator::newPixelIterator - 新しい pixel iterator を返す
    • ImagickPixelIterator::newPixelRegionIterator - 新しい pixel iterator を返す
    • ImagickPixelIterator::resetIterator - pixel iterator をリセットする
    • ImagickPixelIterator::setIteratorFirstRow - pixel iterator を最初の行に設定する
    • ImagickPixelIterator::setIteratorLastRow - pixel iterator を最後の行に設定する
    • ImagickPixelIterator::setIteratorRow - pixel iterator の行を設定する
    • ImagickPixelIterator::syncIterator - pixel iterator を同期する
    • ImagickPixelIterator::__construct - ImagickPixelIterator のコンストラクタ
    • imap_8bit - 8 ビット文字列を quoted-printable 文字列に変換する
    • imap_alerts - 発生した IMAP 警告メッセージを返す
    • imap_append - 指定されたメールボックスに文字列メッセージを追加する
    • imap_base64 - BASE64 でエンコードされたテキストをデコードする
    • imap_binary - 8 ビット文字列を base64 文字列に変換する
    • imap_body - メッセージ本文を読む
    • imap_bodystruct - 指定したメッセージの指定した body セクションの構造を読み込む
    • imap_check - 現在のメールボックスをチェックする
    • imap_clearflag_full - メッセージのフラグをクリアする
    • imap_close - IMAP ストリームをクローズする
    • imap_create - imap_createmailbox のエイリアス
    • imap_createmailbox - 新しいメールボックスを作る
    • imap_delete - 現在のメールボックスから削除するメッセージに印を付ける
    • imap_deletemailbox - メールボックスを削除する
    • imap_errors - 発生したすべての IMAP エラーを返す
    • imap_expunge - 削除用にマークされたすべてのメッセージを削除する
    • imap_fetchbody - メッセージ本文中の特定のセクションを取り出す
    • imap_fetchheader - メッセージのヘッダを返す
    • imap_fetchmime - メッセージの特定のセクションに対する MIME ヘッダを取り出します
    • imap_fetchstructure - 特定のメッセージの構造を読み込む
    • imap_fetchtext - imap_body のエイリアス
    • imap_fetch_overview - 指定したメッセージのヘッダ情報の概要を読む
    • imap_gc - IMAP キャッシュをクリアする
    • imap_getacl - 与えられたメールボックスの ACL を取得する
    • imap_getmailboxes - メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す
    • imap_getsubscribed - 購読中の全メールボックスの一覧を取得する
    • imap_get_quota - クオータレベルの設定、メールボックス毎の使用状況を取得する
    • imap_get_quotaroot - ユーザー単位のクォータ設定を取得する
    • imap_header - imap_headerinfo のエイリアス
    • imap_headerinfo - メッセージヘッダを読み込む
    • imap_headers - メールボックス内のすべてのメッセージのヘッダを返す
    • imap_is_open - IMAP ストリームがまだ有効かを調べる
    • imap_last_error - ページリクエスト時に生じた直近の IMAP エラーを返す
    • imap_list - メールボックスのリストを読み込む
    • imap_listmailbox - imap_list のエイリアス
    • imap_listscan - 指定したテキストにマッチするメールボックスの一覧を返す
    • imap_listsubscribed - imap_lsub のエイリアス
    • imap_lsub - 購読しているすべてのメールボックスの一覧を得る
    • imap_mail - e-mail メッセージを送信する
    • imap_mailboxmsginfo - 現在のメールボックスに関する情報を得る
    • imap_mail_compose - 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する
    • imap_mail_copy - 指定されたメッセージをメールボックスにコピーする
    • imap_mail_move - 指定されたメッセージをメールボックスに移動する
    • imap_mime_header_decode - MIME ヘッダ要素をデコードする
    • imap_msgno - 指定した UID のメッセージ番号を返す
    • imap_mutf7_to_utf8 - 修正UTF-7文字列をUTF-8にデコードする
    • imap_num_msg - 現在のメールボックスのメッセージ数を取得する
    • imap_num_recent - 現在のメールボックスにある新規メッセージ数を取得する
    • imap_open - メールボックスへの IMAP ストリームをオープンする
    • imap_ping - IMAP ストリームがアクティブかどうかを調べる
    • imap_qprint - quoted-printable 文字列を 8 ビット文字列に変換する
    • imap_rename - imap_renamemailbox のエイリアス
    • imap_renamemailbox - メールボックスの名前を変更する
    • imap_reopen - 新規メールボックスへの IMAP ストリームを再度オープンする
    • imap_rfc822_parse_adrlist - アドレス文字列を解釈します
    • imap_rfc822_parse_headers - 文字列からメールヘッダを解釈する
    • imap_rfc822_write_address - 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す
    • imap_savebody - 指定した本文部をファイルに保存する
    • imap_scan - imap_listscan のエイリアス
    • imap_scanmailbox - imap_listscan のエイリアス
    • imap_search - 指定した検索条件にマッチするメッセージを配列として返す
    • imap_setacl - 指定したメールボックスの ACL を設定する
    • imap_setflag_full - メッセージにフラグをセットする
    • imap_set_quota - 指定したメールボックスにクォータを設定する
    • imap_sort - メッセージヘッダの配列をソートする
    • imap_status - 現在のメールボックス以外のメールボックスのステータス情報を返す
    • imap_subscribe - メールボックスを購読する
    • imap_thread - スレッド化したメッセージのツリーを返す
    • imap_timeout - imap タイムアウトを設定あるいは取得する
    • imap_uid - 指定したメッセージシーケンス番号の UID を返す
    • imap_undelete - 削除マークがついているメッセージのマークをはずす
    • imap_unsubscribe - メールボックスの購読をやめる
    • imap_utf7_decode - 修正版 UTF-7 エンコードされた文字列をデコードする
    • imap_utf7_encode - ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する
    • imap_utf8 - MIME エンコードされたテキストを UTF-8 に変換する
    • imap_utf8_to_mutf7 - UTF-8 文字列を修正UTF-7にエンコードする
    • implode - 配列要素を文字列により連結する
    • inet_ntop - パックされたインターネットアドレスを、人間が読める形式に変換する
    • inet_pton - 人間が読める形式の IP アドレスを、パックされた in_addr 形式に変換する
    • InfiniteIterator::next - 内部イテレータを次に移動するか、巻き戻す
    • InfiniteIterator::__construct - InfiniteIterator を作成する
    • inflate_add - インクリメンタルにエンコードされたデータを解凍する
    • inflate_get_read_len - これまでに読み取ったバイト数を得る
    • inflate_get_status - 解凍の状態を取得する
    • inflate_init - インクリメンタルな解凍コンテキストを初期化する
    • ini_alter - ini_set のエイリアス
    • ini_get - 設定オプションの値を得る
    • ini_get_all - すべての設定オプションを得る
    • ini_parse_quantity - ini ディレクティブの省略形を解釈し、サイズを取得する
    • ini_restore - 設定オプションの値を元に戻す
    • ini_set - 設定オプションの値を設定する
    • inotify_add_watch - 初期化済みの inotify インスタンスに監視対象を追加する
    • inotify_init - inotify インスタンスを初期化する
    • inotify_queue_len - 待機中のイベントがある場合に正の数を返す
    • inotify_read - inotify インスタンスからイベントを読み込む
    • inotify_rm_watch - 既存の監視を inotify インスタンスから削除する
    • intdiv - 整数値の除算
    • interface_exists - インターフェイスが宣言されているかどうかを確認する
    • InternalIterator::current - 現在の要素を返す
    • InternalIterator::key - 現在の要素のキーを返す
    • InternalIterator::next - 次の要素に進む
    • InternalIterator::rewind - イテレータの最初の要素に巻き戻す
    • InternalIterator::valid - 現在位置が有効かどうかを調べる
    • InternalIterator::__construct - private なコンストラクタのため、直接インスタンス化できません
    • IntlBreakIterator::createCharacterInstance - 文字シーケンスの組み合わせの境界用にイテレータを作る
    • IntlBreakIterator::createCodePointInstance - コードポイントの境界用にイテレータを作る
    • IntlBreakIterator::createLineInstance - 論理的に可能な改行用にイテレータを作る
    • IntlBreakIterator::createSentenceInstance - 文末用にイテレータを作る
    • IntlBreakIterator::createTitleInstance - タイトル文字の区切り用にイテレータを作る
    • IntlBreakIterator::createWordInstance - 単語の区切り用にイテレータを作る
    • IntlBreakIterator::current - 現在位置のインデックスを取得する
    • IntlBreakIterator::first - テキスト内の最初の文字を場所を取得する
    • IntlBreakIterator::following - 指定したオフセット以降の最初の境界までイテレータを進める
    • IntlBreakIterator::getErrorCode - このオブジェクトの直近のエラーコードを取得する
    • IntlBreakIterator::getErrorMessage - このオブジェクトの直近のエラーメッセージを取得する
    • IntlBreakIterator::getLocale - このオブジェクトに関連づけられたロケールを取得する
    • IntlBreakIterator::getPartsIterator - 境界と境界の間の navigating fragments 用にイテレータを作る
    • IntlBreakIterator::getText - スキャンするテキストを取得する
    • IntlBreakIterator::isBoundary - あるオフセットが境界のオフセットかどうかを調べる
    • IntlBreakIterator::last - イテレータの位置を、最後の文字より後に設定する
    • IntlBreakIterator::next - イテレータを次の境界まで進める
    • IntlBreakIterator::preceding - イテレータの位置を、指定したオフセット以前の最初の境界に設定する
    • IntlBreakIterator::previous - イテレータの位置を、現在位置の直前の境界に設定する
    • IntlBreakIterator::setText - スキャンするテキストを設定する
    • IntlBreakIterator::__construct - インスタンス化を禁止するためのprivateなコンストラクタ
    • IntlCalendar::add - フィールドに (符号付きの) 一定量の時間を追加する
    • IntlCalendar::after - このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する
    • IntlCalendar::before - このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する
    • IntlCalendar::clear - 単一または全てのフィールドをクリアする
    • IntlCalendar::createInstance - 新しい IntlCalendar を作成する
    • IntlCalendar::equals - ふたつの IntlCalendar オブジェクトの時刻を比較する
    • IntlCalendar::fieldDifference - 指定された時刻と、このオブジェクトの時刻の差を計算する
    • IntlCalendar::fromDateTime - DateTime オブジェクトまたは文字列から、IntlCalendar を作成する
    • IntlCalendar::get - フィールドの値を取得する
    • IntlCalendar::getActualMaximum - オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する
    • IntlCalendar::getActualMinimum - オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する
    • IntlCalendar::getAvailableLocales - データが存在するロケールの配列を取得する
    • IntlCalendar::getDayOfWeekType - 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す
    • IntlCalendar::getErrorCode - オブジェクトに関する直近のエラーコードを取得する
    • IntlCalendar::getErrorMessage - オブジェクトの直近のエラーメッセージを取得する
    • IntlCalendar::getFirstDayOfWeek - カレンダーのロケールに基づいて、週の始めの日を返す
    • IntlCalendar::getGreatestMinimum - 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す
    • IntlCalendar::getKeywordValuesForLocale - ロケールのキーワードの値の集合を返す
    • IntlCalendar::getLeastMaximum - 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す
    • IntlCalendar::getLocale - オブジェクトに関連付けられたロケールを取得する
    • IntlCalendar::getMaximum - フィールドのグローバルな最大値を返す
    • IntlCalendar::getMinimalDaysInFirstWeek - 特定の年や月における、最初の週の日数の最小値を返す
    • IntlCalendar::getMinimum - フィールドのグローバルな最小値を返す
    • IntlCalendar::getNow - 現在時刻を示す数値を取得する
    • IntlCalendar::getRepeatedWallTimeOption - 繰り返される実時間を扱う際の振る舞いを取得する
    • IntlCalendar::getSkippedWallTimeOption - スキップされた実時間を扱う際の振る舞いを取得する
    • IntlCalendar::getTime - このオブジェクトが表す時刻を取得する
    • IntlCalendar::getTimeZone - オブジェクトのタイムゾーンを取得する
    • IntlCalendar::getType - カレンダーのタイプを取得する
    • IntlCalendar::getWeekendTransition - 週末が開始/終了した日からの経過時間を取得する
    • IntlCalendar::inDaylightTime - オブジェクトの時刻が夏時間かを調べる
    • IntlCalendar::isEquivalentTo - 別のカレンダーが、時刻を除いて等しいかを調べる
    • IntlCalendar::isLenient - 日付と時刻の解釈を「緩いモード」で行うかを取得する
    • IntlCalendar::isSet - フィールドが設定されているかを調べる
    • IntlCalendar::isWeekend - ある日付/時刻が週末にあるかを調べる
    • IntlCalendar::roll - 次のフィールドを繰り上げずに、フィールドに値を加算する
    • IntlCalendar::set - 時刻または複数の共通フィールドを一度に設定する
    • IntlCalendar::setDate - 日付のフィールドを設定する
    • IntlCalendar::setDateTime - 日付と時刻のフィールドを設定する
    • IntlCalendar::setFirstDayOfWeek - 週の始まりと見なされる曜日を設定する
    • IntlCalendar::setLenient - 日付/時刻の解釈を「緩いモード」にするかを設定する
    • IntlCalendar::setMinimalDaysInFirstWeek - 特定の年や月における、最初の週の日数の最小値を設定する
    • IntlCalendar::setRepeatedWallTimeOption - 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する
    • IntlCalendar::setSkippedWallTimeOption - 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する
    • IntlCalendar::setTime - エポックからのカレンダーの時刻をミリ秒単位で設定する
    • IntlCalendar::setTimeZone - このカレンダーで使うタイムゾーンを設定する
    • IntlCalendar::toDateTime - IntlCalendar を DateTime オブジェクトに変換する
    • IntlCalendar::__construct - インスタンス化を禁止するための private なコンストラクタ
    • IntlChar::charAge - コードポイントの "age" を取得する
    • IntlChar::charDigitValue - 10進数の桁の文字を桁の値として取得する
    • IntlChar::charDirection - コードポイントの双方向カテゴリの値を取得する
    • IntlChar::charFromName - 名前で Unicode 文字を探し、コードポイントの値を返す
    • IntlChar::charMirror - コードポイントの "鏡文字" を取得する
    • IntlChar::charName - Unicode 文字の名前を取得する
    • IntlChar::charType - コードポイントの一般カテゴリの値を取得する
    • IntlChar::chr - コードポイント値に対応する、Unicode 文字を返す
    • IntlChar::digit - コードポイントの10進の数値を、指定された基数で返す
    • IntlChar::enumCharNames - 指定された範囲の全てのUnicode文字を走査する
    • IntlChar::enumCharTypes - Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する
    • IntlChar::foldCase - コードポイントに対してケースフォールディングを行う
    • IntlChar::forDigit - 指定された整数と基数を表す文字を取得する
    • IntlChar::getBidiPairedBracket - コードポイントと対になる括弧文字を取得する
    • IntlChar::getBlockCode - コードポイントが含まれる割当ブロックを取得する
    • IntlChar::getCombiningClass - コードポイントの合成クラスを取得する
    • IntlChar::getFC_NFKC_Closure - コードポイントの FC_NFKC_Closure プロパティの値を取得する
    • IntlChar::getIntPropertyMaxValue - Unicode プロパティの最大値を取得する
    • IntlChar::getIntPropertyMinValue - Unicode プロパティの最小値を取得する
    • IntlChar::getIntPropertyValue - コードポイントに対応する、Unicode プロパティの値を取得する
    • IntlChar::getNumericValue - Unicode のコードポイントの数値の値を取得する
    • IntlChar::getPropertyEnum - プロパティの名前に対応する定数値を取得する
    • IntlChar::getPropertyName - プロパティに対応する、Unicode での名前を取得する
    • IntlChar::getPropertyValueEnum - 指定された値の名前に対応する、プロパティの値を取得する
    • IntlChar::getPropertyValueName - プロパティの値に対応する、Unicode の名前を取得する
    • IntlChar::getUnicodeVersion - Unicode のバージョンを取得する
    • IntlChar::hasBinaryProperty - コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる
    • IntlChar::isalnum - コードポイントが英数字であるかを調べる
    • IntlChar::isalpha - コードポイントがアルファベットかを調べる
    • IntlChar::isbase - コードポイントが基底文字に含まれるかを調べる
    • IntlChar::isblank - コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる
    • IntlChar::iscntrl - コードポイントが制御文字かどうかを調べる
    • IntlChar::isdefined - コードポイントが定義されているかどうかを調べる
    • IntlChar::isdigit - コードポイントが、数字であるかを調べる
    • IntlChar::isgraph - コードポイントが図形文字であるかを調べる
    • IntlChar::isIDIgnorable - コードポイントが無視できる文字かを調べる
    • IntlChar::isIDPart - コードポイントが識別子として使えるかを調べる
    • IntlChar::isIDStart - コードポイントが識別子の最初の文字として使えるかを調べる
    • IntlChar::isISOControl - コードポイントがISOで定義された制御文字であるかを調べる
    • IntlChar::isJavaIDPart - コードポイントが、Java の識別子として使えるかを調べる
    • IntlChar::isJavaIDStart - コードポイントが Java の識別子の最初の文字として使えるかを調べる
    • IntlChar::isJavaSpaceChar - コードポイントが Java におけるスペース文字であるかを調べる
    • IntlChar::islower - コードポイントが小文字かどうかを調べる
    • IntlChar::isMirrored - コードポイントが Bidi_Mirrored プロパティを持つかを調べる
    • IntlChar::isprint - コードポイントが印字可能な文字かを調べる
    • IntlChar::ispunct - コードポイントが句読点の文字かどうかを調べる
    • IntlChar::isspace - コードポイントが、スペース文字であるかを調べる
    • IntlChar::istitle - コードポイントがタイトルケース文字であるかを調べる
    • IntlChar::isUAlphabetic - コードポイントが、Alphabetic プロパティを持つかを調べる
    • IntlChar::isULowercase - コードポイントが小文字のUnicodeプロパティを持つかを調べる
    • IntlChar::isupper - コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する
    • IntlChar::isUUppercase - コードポイントが大文字のUnicodeプロパティを持つかを調べる
    • IntlChar::isUWhiteSpace - コードポイントが、White_Space プロパティを持つかを調べる
    • IntlChar::isWhitespace - コードポイントが、ICU の空白文字であるかを調べる
    • IntlChar::isxdigit - コードポイントが、16進数の文字であるかを調べる
    • IntlChar::ord - 文字に対応する Unicode コードポイントを返す
    • IntlChar::tolower - Unicode 文字を小文字にする
    • IntlChar::totitle - Unicode 文字をタイトルケースにする
    • IntlChar::toupper - Unicode 文字を大文字にする
    • IntlCodePointBreakIterator::getLastCodePoint - イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する
    • IntlDateFormatter::create - Date Formatter を作成する
    • IntlDateFormatter::format - 日付/時刻 の値を文字列としてフォーマットする
    • IntlDateFormatter::formatObject - オブジェクトの書式を設定する
    • IntlDateFormatter::getCalendar - IntlDateFormatter が使用するカレンダー型を取得する
    • IntlDateFormatter::getCalendarObject - カレンダーオブジェクトのコピーを取得する
    • IntlDateFormatter::getDateType - IntlDateFormatter が使用する日付形式を取得する
    • IntlDateFormatter::getErrorCode - 直近の操作のエラーコードを取得する
    • IntlDateFormatter::getErrorMessage - 直近の操作のエラーテキストを取得する
    • IntlDateFormatter::getLocale - Formatter が使用するロケールを取得する
    • IntlDateFormatter::getPattern - IntlDateFormatter が使用するパターンを取得する
    • IntlDateFormatter::getTimeType - IntlDateFormatter が使用する時刻形式を取得する
    • IntlDateFormatter::getTimeZone - タイムゾーンを取得する
    • IntlDateFormatter::getTimeZoneId - IntlDateFormatter が使用するタイムゾーン ID を取得する
    • IntlDateFormatter::isLenient - IntlDateFormatter で使用する寛大さを取得する
    • IntlDateFormatter::localtime - 文字列をパースして、フィールドベースの時刻値にする
    • IntlDateFormatter::parse - 文字列をパースしてタイムスタンプにする
    • IntlDateFormatter::setCalendar - Formatter が使うカレンダー型を設定する
    • IntlDateFormatter::setLenient - パーサの寛大さを設定する
    • IntlDateFormatter::setPattern - IntlDateFormatter が使用するパターンを設定する
    • IntlDateFormatter::setTimeZone - タイムゾーンを設定する
    • IntlDatePatternGenerator::create - IntlDatePatternGenerator を作成する
    • IntlDatePatternGenerator::getBestPattern - もっとも適合した 日付/時刻 のフォーマットを決定する
    • IntlGregorianCalendar::createFromDate - 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する
    • IntlGregorianCalendar::createFromDateTime - 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する
    • IntlGregorianCalendar::getGregorianChange - グレゴリオ暦への切換え日を取得する
    • IntlGregorianCalendar::isLeapYear - 指定された年がうるう年かを判定する
    • IntlGregorianCalendar::setGregorianChange - グレゴリオ暦への切換え日を設定する
    • IntlGregorianCalendar::__construct - グレゴリオ暦の Calendar クラスを作成する
    • IntlIterator::current - 現在の要素を取得する
    • IntlIterator::key - 現在のキーを取得する
    • IntlIterator::next - 次の要素に進む
    • IntlIterator::rewind - イテレータを最初の要素に戻す
    • IntlIterator::valid - 現在の位置が有効かを調べる
    • IntlPartsIterator::getBreakIterator - この parts iterator の裏付けとなる、IntlBreakIterator を取得する
    • IntlRuleBasedBreakIterator::getBinaryRules - コンパイル済みのルールを、バイナリで取得する
    • IntlRuleBasedBreakIterator::getRules - このオブジェクトを作るのに使われているルールを取得する
    • IntlRuleBasedBreakIterator::getRuleStatus - 現在の境界位置を決めるルールから、ステータスの最大値を取得する
    • IntlRuleBasedBreakIterator::getRuleStatusVec - 現在の境界位置から定まるルールから、ステータス値を取得する
    • IntlRuleBasedBreakIterator::__construct - ルールセットから iterator を作成する
    • IntlTimeZone::countEquivalentIDs - 指定した ID を含む等価グループの中にある ID の数を取得する
    • IntlTimeZone::createDefault - このホストのデフォルトタイムゾーンの新しいコピーを作る
    • IntlTimeZone::createEnumeration - 指定した国あるいはオフセットに関連するタイムゾーン ID の一覧を取得する
    • IntlTimeZone::createTimeZone - 指定した ID のタイムゾーンオブジェクトを作る
    • IntlTimeZone::createTimeZoneIDEnumeration - 指定されたフィルタ条件を反映した、システムタイムゾーンのイテレータを取得する
    • IntlTimeZone::fromDateTimeZone - DateTimeZone からタイムゾーンオブジェクトを作る
    • IntlTimeZone::getCanonicalID - 指定したタイムゾーン ID の、正式なシステムタイムゾーン ID あるいは正規化したカスタムタイムゾーン ID を取得する
    • IntlTimeZone::getDisplayName - このタイムゾーンの、ユーザー向けに表示する名前を取得する
    • IntlTimeZone::getDSTSavings - ローカルの標準時刻からローカルの実測時刻を得るために加算する時間を取得する
    • IntlTimeZone::getEquivalentID - 指定した ID を含む等価グループの ID を取得する
    • IntlTimeZone::getErrorCode - 直近のエラーコードを取得する
    • IntlTimeZone::getErrorMessage - 直近のエラーメッセージを取得する
    • IntlTimeZone::getGMT - GMT (UTC) タイムゾーンを作る
    • IntlTimeZone::getID - タイムゾーン ID を取得する
    • IntlTimeZone::getIDForWindowsID - Windows のタイムゾーンを、システムタイムゾーンに翻訳する
    • IntlTimeZone::getOffset - 指定した時刻の、GMT へのオフセットを取得する
    • IntlTimeZone::getRawOffset - (夏時間を考慮せずに) GMT へのオフセットを取得する
    • IntlTimeZone::getRegion - 指定されたシステムタイムゾーンのIDから、地域コードを取得する
    • IntlTimeZone::getTZDataVersion - ICU が使っているタイムゾーンデータのバージョンを取得する
    • IntlTimeZone::getUnknown - "unknown" なタイムゾーンを取得する
    • IntlTimeZone::getWindowsID - システムタイムゾーンを、Windows のタイムゾーンに翻訳する
    • IntlTimeZone::hasSameRules - このタイムゾーンが別のタイムゾーンと同じルールおよびオフセットを使っているかどうかを調べる
    • IntlTimeZone::toDateTimeZone - DateTimeZone オブジェクトに変換する
    • IntlTimeZone::useDaylightTime - このタイムゾーンが夏時間を採用しているかどうかを調べる
    • IntlTimeZone::__construct - インスタンス化を禁止するためのprivateなコンストラクタ
    • intl_error_name - 指定したエラーコードに対応する名前を取得する
    • intl_get_error_code - 直近のエラーコードを取得する
    • intl_get_error_message - 直近のエラーの説明を取得する
    • intl_is_failure - 指定したエラーコードが失敗を表すかどうかを調べる
    • intval - 変数の整数としての値を取得する
    • in_array - 配列に値があるかチェックする
    • ip2long - ドット表記の (IPv4) IP アドレスを、長整数表現に変換する
    • iptcembed - バイナリ IPTC データを JPEG イメージに埋めこむ
    • iptcparse - バイナリの IPTC ブロックのタグをパースする
    • isset - 変数が宣言されていること、そして null とは異なることを検査する
    • is_a - オブジェクトが指定された型のものか、部分型であるかを調べる
    • is_array - 変数が配列かどうかを検査する
    • is_bool - 変数が boolean であるかを調べる
    • is_callable - 引数が、現在のスコープから関数としてコール可能な値かどうかを調べる
    • is_countable - 引数が、数えられる値かどうかを調べる
    • is_dir - ファイルがディレクトリかどうかを調べる
    • is_double - is_float のエイリアス
    • is_executable - ファイルが実行可能かどうかを調べる
    • is_file - 通常ファイルかどうかを調べる
    • is_finite - 浮動小数点数の値が、有限の数値であるかどうかを調べる
    • is_float - 変数の型が float かどうか調べる
    • is_infinite - 浮動小数点数の値が、無限大であるかどうかを調べる
    • is_int - 変数が整数型かどうかを検査する
    • is_integer - is_int のエイリアス
    • is_iterable - 変数の内容が反復可能な値であることを確認する
    • is_link - ファイルがシンボリックリンクかどうかを調べる
    • is_long - is_int のエイリアス
    • is_nan - 浮動小数点数の値が、非数かどうかを調べる
    • is_null - 変数が null かどうか調べる
    • is_numeric - 変数が数字または数値形式の文字列であるかを調べる
    • is_object - 変数がオブジェクトかどうかを検査する
    • is_readable - ファイルが存在し、読み込み可能であるかどうかを知る
    • is_real - is_float のエイリアス
    • is_resource - 変数がリソースかどうかを調べる
    • is_scalar - 変数がスカラかどうかを調べる
    • is_soap_fault - SOAP コールが失敗したかどうかを調べる
    • is_string - 変数の型が文字列かどうかを調べる
    • is_subclass_of - あるオブジェクトが指定したクラスのサブクラスに属するか (あるいは指定したインターフェイスを実装しているか) どうかを調べる
    • is_tainted - 文字列が汚染されているかどうかを調べる
    • is_uploaded_file - HTTP POST でアップロードされたファイルかどうかを調べる
    • is_writable - ファイルが書き込み可能かどうかを調べる
    • is_writeable - is_writable のエイリアス
    • Iterator::current - 現在の要素を返す
    • Iterator::key - 現在の要素のキーを返す
    • Iterator::next - 次の要素に進む
    • Iterator::rewind - イテレータの最初の要素に巻き戻す
    • Iterator::valid - 現在位置が有効かどうかを調べる
    • IteratorAggregate::getIterator - 外部イテレータを取得する
    • IteratorIterator::current - 現在の値を取得する
    • IteratorIterator::getInnerIterator - 内部イテレータを取得する
    • IteratorIterator::key - 現在の要素のキーを取得する
    • IteratorIterator::next - 次の要素に移動する
    • IteratorIterator::rewind - 最初の要素に巻き戻す
    • IteratorIterator::valid - 現在の要素が有効かどうかを調べる
    • IteratorIterator::__construct - traversable な何かからイテレータを作成する
    • iterator_apply - ユーザー関数をイテレータのすべての要素でコールする
    • iterator_count - イテレータにある要素をカウントする
    • iterator_to_array - イテレータを配列にコピーする
  • j
    • jddayofweek - 曜日を返す
    • jdmonthname - 月の名前を返す
    • jdtofrench - ユリウス積算日をフランス革命暦(共和暦)に変換する
    • jdtogregorian - ユリウス積算日をグレゴリウス日に変換する
    • jdtojewish - ユリウス積算日をユダヤ暦に変換する
    • jdtojulian - ユリウス積算日をユリウス暦に変換する
    • jdtounix - ユリウス歴を Unix タイムスタンプに変換する
    • jewishtojd - ユダヤ暦の日付けをユリウス積算日に変換する
    • join - implode のエイリアス
    • jpeg2wbmp - JPEG画像をWBMP画像に変換する
    • JsonSerializable::jsonSerialize - JSON にシリアライズしたいデータを指定する
    • json_decode - JSON 文字列をデコードする
    • json_encode - 値を JSON 形式にして返す
    • json_last_error - 直近に発生したエラーを返す
    • json_last_error_msg - 直近の json_encode() や json_decode() の呼び出しのエラー文字列を返す
    • json_validate - 文字列が有効なJSONかどうかを調べる
    • juliantojd - ユリウス暦をユリウス積算日に変換する
  • k
    • key - 配列からキーを取り出す
    • key_exists - array_key_exists のエイリアス
    • krsort - 配列をキーで降順にソートする
    • ksort - 配列をキーで昇順にソートする
  • l
    • lcfirst - 文字列の最初の文字を小文字にする
    • lcg_value - 複合線形合同法
    • lchgrp - シンボリックリンクのグループ所有権を変更する
    • lchown - シンボリックリンクの所有者を変更する
    • ldap_8859_to_t61 - 8859 文字を t61 文字に変換する
    • ldap_add - LDAP ディレクトリにエントリを付加する
    • ldap_add_ext - LDAP ディレクトリにエントリを付加する
    • ldap_bind - LDAP ディレクトリにバインドする
    • ldap_bind_ext - LDAP ディレクトリにバインドする
    • ldap_close - ldap_unbind のエイリアス
    • ldap_compare - 指定した DN のエントリで見付かった属性の値を比較する
    • ldap_connect - LDAP サーバーへ接続する
    • ldap_connect_wallet - LDAP サーバに接続する
    • ldap_control_paged_result - LDAP ページネーション制御情報を送信する
    • ldap_control_paged_result_response - LDAP ページネーションクッキーを取得する
    • ldap_count_entries - 検索結果のエントリ数を数える
    • ldap_count_references - 検索結果に含まれる参照数を数える
    • ldap_delete - ディレクトリからエントリを削除する
    • ldap_delete_ext - ディレクトリからエントリを削除する
    • ldap_dn2ufn - DN をユーザーに分かりやすい名前のフォーマットに変換する
    • ldap_err2str - LDAP のエラー番号をエラーメッセージ文字列に変換する
    • ldap_errno - 直近の LDAP コマンドの LDAP エラー番号を返す
    • ldap_error - 直近の LDAP コマンドの LDAP エラーメッセージを返す
    • ldap_escape - LDAP フィルタまたは DN で使われる文字列をエスケープする
    • ldap_exop - 拡張されたオペレーションを実行する
    • ldap_exop_passwd - PASSWD 拡張オペレーションのヘルパ
    • ldap_exop_refresh - Refresh 拡張操作のヘルパ
    • ldap_exop_sync - 拡張されたオペレーションを実行する
    • ldap_exop_whoami - WHOAMI 拡張オペレーションのヘルパ
    • ldap_explode_dn - DN を構成要素ごとに分割する
    • ldap_first_attribute - 最初の属性を返す
    • ldap_first_entry - 最初の結果 ID を返す
    • ldap_first_reference - 最初のリファレンスを返す
    • ldap_free_result - 結果メモリを開放する
    • ldap_get_attributes - 検索結果エントリから属性を得る
    • ldap_get_dn - 結果エントリから DN を得る
    • ldap_get_entries - 全ての結果エントリを得る
    • ldap_get_option - 指定したオプションの現在の値を得る
    • ldap_get_values - 結果エントリから全ての値を得る
    • ldap_get_values_len - 結果エントリから全てのバイナリ値を得る
    • ldap_list - 単一階層の検索を行う
    • ldap_modify - のエイリアス ldap_mod_replace
    • ldap_modify_batch - LDAP エントリの変更をまとめて実行する
    • ldap_mod_add - 現在の属性に属性を追加する
    • ldap_mod_add_ext - 現在の属性に属性を追加する
    • ldap_mod_del - 現在の属性から属性を削除する
    • ldap_mod_del_ext - 現在の属性から属性を削除する
    • ldap_mod_replace - 属性を新規の値に置換する
    • ldap_mod_replace_ext - 属性を新規の値に置換する
    • ldap_next_attribute - 結果における次の属性を得る
    • ldap_next_entry - 次の結果エントリを得る
    • ldap_next_reference - 次のリファレンスを得る
    • ldap_parse_exop - LDAP拡張オペレーションの結果オブジェクトをパースする
    • ldap_parse_reference - 参照エントリから情報を展開する
    • ldap_parse_result - 結果から情報を展開する
    • ldap_read - エントリを読み込む
    • ldap_rename - エントリ名を修正する
    • ldap_rename_ext - エントリ名を修正する
    • ldap_sasl_bind - SASL を使用して LDAP ディレクトリにバインドする
    • ldap_search - LDAP ツリーを探索する
    • ldap_set_option - 指定したオプションの値を設定する
    • ldap_set_rebind_proc - 参照先を再バインドするためのコールバック関数を設定する
    • ldap_sort - LDAP 結果エントリをクライアント側でソートする
    • ldap_start_tls - TLS を開始する
    • ldap_t61_to_8859 - t61 文字を 8859 文字に変換する
    • ldap_unbind - LDAP ディレクトリへのバインドを解除する
    • levenshtein - 二つの文字列のレーベンシュタイン距離を計算する
    • libxml_clear_errors - libxmlエラーハンドラをクリアする
    • libxml_disable_entity_loader - 外部エンティティの読み込み機能を無効にする
    • libxml_get_errors - エラー配列を取得する
    • libxml_get_external_entity_loader - 現在の外部エンティティローダーを取得する
    • libxml_get_last_error - libxmlから直近のエラーを取得する
    • libxml_set_external_entity_loader - デフォルトの外部エンティティローダーを変更する
    • libxml_set_streams_context - 次のlibxmlドキュメントの読込／書きこみのためにストリームコンテキストを設定する
    • libxml_use_internal_errors - libxmlエラーを無効にし、ユーザーが必要に応じてエラー情報を取得できるようにする
    • LimitIterator::current - 現在の要素を取得する
    • LimitIterator::getPosition - 現在の位置を返す
    • LimitIterator::key - 現在のキーを取得する
    • LimitIterator::next - イテレータを前に移動する
    • LimitIterator::rewind - イテレータを指定した開始オフセットに巻き戻す
    • LimitIterator::seek - 与えられた位置に移動する
    • LimitIterator::valid - 現在の要素が有効かどうかをチェックする
    • LimitIterator::__construct - LimitIterator を作成する
    • link - ハードリンクを作成する
    • linkinfo - リンクに関する情報を取得する
    • list - 配列と同様の形式で、複数の変数への代入を行う
    • Locale::acceptFromHttp - 最もあてはまるロケールを HTTP "Accept-Language" ヘッダにもとづいて探す
    • Locale::canonicalize - ロケール文字列を正規化する
    • Locale::composeLocale - 正しく並べ替えて区切られたロケール ID を返す
    • Locale::filterMatches - 言語タグフィルタがロケールにマッチするかどうかを調べる
    • Locale::getAllVariants - 入力ロケールの変化系を取得する
    • Locale::getDefault - INTL のグローバル 'default_locale' からデフォルトのロケールを取得する
    • Locale::getDisplayLanguage - 入力ロケールの言語の表示名を、適切に地域化して返す
    • Locale::getDisplayName - 入力ロケールの表示名を、適切に地域化して返す
    • Locale::getDisplayRegion - 入力ロケールの地域の表示名を、適切に地域化して返す
    • Locale::getDisplayScript - 入力ロケールの文字の表示名を、適切に地域化して返す
    • Locale::getDisplayVariant - 入力ロケールの変化形の表示名を、適切に地域化して返す
    • Locale::getKeywords - 入力ロケールのキーワードを取得する
    • Locale::getPrimaryLanguage - 入力ロケールのプライマリ言語を取得する
    • Locale::getRegion - 入力ロケールの地域を取得する
    • Locale::getScript - 入力ロケールの文字を取得する
    • Locale::lookup - その言語にマッチする言語タグの一覧を検索する
    • Locale::parseLocale - ロケール ID のサブタグ要素を連想配列で返す
    • Locale::setDefault - デフォルトの実行時ロケールを設定する
    • localeconv - 数値に関するフォーマット情報を得る
    • localtime - ローカルタイムを得る
    • log - 自然対数
    • log1p - 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
    • log10 - 底が 10 の対数
    • long2ip - 長整数表現のインターネットアドレスを (IPv4) インターネット標準ドット表記に変換する
    • lstat - ファイルあるいはシンボリックリンクの情報を取得する
    • ltrim - 文字列の最初から空白 (もしくはその他の文字) を取り除く
    • Lua::assign - PHP 変数を Lua にアサイン
    • Lua::call - Lua 関数を呼び出す
    • Lua::eval - 文字列を Lua コードとして評価
    • Lua::getVersion - getversion 用途
    • Lua::include - Lua スクリプトファイルをパース
    • Lua::registerCallback - PHP 関数を Lua に登録
    • Lua::__construct - Lua コンストラクタ
    • LuaClosure::__invoke - luaclosure を起動
    • LuaSandbox::callFunction - Call a function in a Lua global variable
    • LuaSandbox::disableProfiler - Disable the profiler
    • LuaSandbox::enableProfiler - Enable the profiler.
    • LuaSandbox::getCPUUsage - Fetch the current CPU time usage of the Lua environment
    • LuaSandbox::getMemoryUsage - Fetch the current memory usage of the Lua environment
    • LuaSandbox::getPeakMemoryUsage - Fetch the peak memory usage of the Lua environment
    • LuaSandbox::getProfilerFunctionReport - Fetch profiler data
    • LuaSandbox::getVersionInfo - Return the versions of LuaSandbox and Lua
    • LuaSandbox::loadBinary - Load a precompiled binary chunk into the Lua environment
    • LuaSandbox::loadString - Load Lua code into the Lua environment
    • LuaSandbox::pauseUsageTimer - Pause the CPU usage timer
    • LuaSandbox::registerLibrary - Register a set of PHP functions as a Lua library
    • LuaSandbox::setCPULimit - Set the CPU time limit for the Lua environment
    • LuaSandbox::setMemoryLimit - Set the memory limit for the Lua environment
    • LuaSandbox::unpauseUsageTimer - Unpause the timer paused by LuaSandbox::pauseUsageTimer
    • LuaSandbox::wrapPhpFunction - Wrap a PHP callable in a LuaSandboxFunction
    • LuaSandboxFunction::call - Call a Lua function
    • LuaSandboxFunction::dump - Dump the function as a binary blob
    • LuaSandboxFunction::__construct - Unused
    • lzf_compress - LZF 圧縮を行う
    • lzf_decompress - LZF 圧縮を伸長する
    • lzf_optimized_for - LZF 拡張モジュールの最適化指定を取得する
  • m
    • mail - メールを送信する
    • mailparse_determine_best_xfer_encoding - 最も適したエンコーディングを取得する
    • mailparse_msg_create - mime メールリソースを作成する
    • mailparse_msg_extract_part - メッセージセクションを展開/デコードする
    • mailparse_msg_extract_part_file - メッセージセクションを展開/デコードする
    • mailparse_msg_extract_whole_part_file - ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する
    • mailparse_msg_free - MIME リソースを解放する
    • mailparse_msg_get_part - MIME メッセージの指定したセクションに関するハンドルを返す
    • mailparse_msg_get_part_data - メッセージに関する情報の連想配列を返す
    • mailparse_msg_get_structure - 指定したメッセージ内の MIME セクション名の配列を返す
    • mailparse_msg_parse - データをパースし、バッファに追加する
    • mailparse_msg_parse_file - ファイルをパースする
    • mailparse_rfc822_parse_addresses - RFC 822 準拠のアドレスをパースする
    • mailparse_stream_encode - ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む
    • mailparse_uudecode_all - ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する
    • max - 最大値を返す
    • mb_check_encoding - 文字列が、指定したエンコーディングで有効なものかどうかを調べる
    • mb_chr - Unicode のコードポイントに対応する文字を返す
    • mb_convert_case - 文字列に対してケースフォールディングを行う
    • mb_convert_encoding - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
    • mb_convert_kana - カナを("全角かな"、"半角かな"等に)変換する
    • mb_convert_variables - 変数の文字コードを変換する
    • mb_decode_mimeheader - MIME ヘッダフィールドの文字列をデコードする
    • mb_decode_numericentity - HTML 数値エンティティを文字にデコードする
    • mb_detect_encoding - 文字エンコーディングを検出する
    • mb_detect_order - 文字エンコーディング検出順序を設定あるいは取得する
    • mb_encode_mimeheader - MIMEヘッダの文字列をエンコードする
    • mb_encode_numericentity - 文字を HTML 数値エンティティにエンコードする
    • mb_encoding_aliases - 既知のエンコーディング・タイプのエイリアスを取得
    • mb_ereg - マルチバイト対応の正規表現マッチ
    • mb_eregi - マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ
    • mb_eregi_replace - マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う
    • mb_ereg_match - マルチバイト文字列が正規表現に一致するか調べる
    • mb_ereg_replace - マルチバイト文字列に正規表現による置換を行う
    • mb_ereg_replace_callback - マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う
    • mb_ereg_search - 指定したマルチバイト文字列が正規表現に一致するか調べる
    • mb_ereg_search_getpos - 次の正規表現検索を開始する位置を取得する
    • mb_ereg_search_getregs - マルチバイト文字列が正規表現に一致する部分があるか調べる
    • mb_ereg_search_init - マルチバイト正規表現検索用の文字列と正規表現を設定する
    • mb_ereg_search_pos - 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す
    • mb_ereg_search_regs - 指定したマルチバイト文字列が正規表現に一致する部分を取得する
    • mb_ereg_search_setpos - 次の正規表現検索を開始する位置を設定する
    • mb_get_info - mbstring の内部設定値を取得する
    • mb_http_input - HTTP 入力文字エンコーディングを検出する
    • mb_http_output - HTTP 出力文字エンコーディングを設定あるいは取得する
    • mb_internal_encoding - 内部文字エンコーディングを設定あるいは取得する
    • mb_language - 現在の言語を設定あるいは取得する
    • mb_list_encodings - サポートするすべてのエンコーディングの配列を返す
    • mb_ord - 文字の Unicode コードポイントを取得する
    • mb_output_handler - 出力バッファ内で文字エンコーディングを変換するコールバック関数
    • mb_parse_str - GET/POST/COOKIE データをパースし、グローバル変数を設定する
    • mb_preferred_mime_name - MIME 文字設定を文字列で得る
    • mb_regex_encoding - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
    • mb_regex_set_options - マルチバイト正規表現関数のデフォルトオプションを取得または設定する
    • mb_scrub - 文字列に含まれる不正なバイト列を代替文字に置き換える
    • mb_send_mail - エンコード変換を行ってメールを送信する
    • mb_split - マルチバイト文字列を正規表現により分割する
    • mb_strcut - 文字列の一部を得る
    • mb_strimwidth - 指定した幅で文字列を丸める
    • mb_stripos - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
    • mb_stristr - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
    • mb_strlen - 文字列の長さを得る
    • mb_strpos - 文字列の中に指定した文字列が最初に現れる位置を見つける
    • mb_strrchr - 別の文字列の中で、ある文字が最後に現れる場所を見つける
    • mb_strrichr - 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す
    • mb_strripos - 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す
    • mb_strrpos - 文字列の中に指定した文字列が最後に現れる位置を見つける
    • mb_strstr - 文字列の中で、指定した文字列が最初に現れる位置を見つける
    • mb_strtolower - 文字列を小文字にする
    • mb_strtoupper - 文字列を大文字にする
    • mb_strwidth - 文字列の幅を返す
    • mb_str_pad - マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める
    • mb_str_split - マルチバイト文字列を受取り、文字の配列を返す
    • mb_substitute_character - 置換文字を設定あるいは取得する
    • mb_substr - 文字列の一部を得る
    • mb_substr_count - 部分文字列の出現回数を数える
    • mcrypt_create_iv - Creates an initialization vector (IV) from a random source
    • mcrypt_decrypt - Decrypts crypttext with given parameters
    • mcrypt_encrypt - 指定したパラメータでプレーンテキストを暗号化する
    • mcrypt_enc_get_algorithms_name - Returns the name of the opened algorithm
    • mcrypt_enc_get_block_size - Returns the blocksize of the opened algorithm
    • mcrypt_enc_get_iv_size - オープンされたアルゴリズムの IV の大きさを返す
    • mcrypt_enc_get_key_size - オープンされたモードでサポートされる最大キー長を返す
    • mcrypt_enc_get_modes_name - オープンされたモードの名前を返す
    • mcrypt_enc_get_supported_key_sizes - オープンされたアルゴリズムでサポートされるキー長を配列にして返す
    • mcrypt_enc_is_block_algorithm - オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べる
    • mcrypt_enc_is_block_algorithm_mode - オープンされたモードの暗号がブロックモードで動作するかどうかを調べる
    • mcrypt_enc_is_block_mode - オープンされたモードがブロック出力を行うかどうかを調べる
    • mcrypt_enc_self_test - オープンしたモジュールのセルフテストを実行する
    • mcrypt_generic - データを暗号化する
    • mcrypt_generic_deinit - 暗号化モジュールを終了する
    • mcrypt_generic_init - 暗号化に必要な全てのバッファを初期化する
    • mcrypt_get_block_size - 指定した暗号のブロックサイズを得る
    • mcrypt_get_cipher_name - 指定した暗号の名前を得る
    • mcrypt_get_iv_size - 指定した暗号/モードの組み合わせに属する IV の大きさを返す
    • mcrypt_get_key_size - 指定した暗号のキーの長さを得る
    • mcrypt_list_algorithms - サポートされる全ての暗号を配列として取得する
    • mcrypt_list_modes - サポートされる全てのモードの配列を取得する
    • mcrypt_module_close - mcrypt モジュールを閉じる
    • mcrypt_module_get_algo_block_size - 指定したアルゴリズムのブロック長を返す
    • mcrypt_module_get_algo_key_size - オープンされたモードでサポートされる最大キー長を返す
    • mcrypt_module_get_supported_key_sizes - オープンされたアルゴリズムでサポートされるキーのサイズを配列として返す
    • mcrypt_module_is_block_algorithm - 指定したアルゴリズムがブロックアルゴリズムであるかを調べる
    • mcrypt_module_is_block_algorithm_mode - 指定したモジュールがブロックアルゴリズムであるかどうかを返す
    • mcrypt_module_is_block_mode - 指定したモードがブロック出力を行うかどうかを返す
    • mcrypt_module_open - 使用するアルゴリズムおよびモードのモジュールをオープンする
    • mcrypt_module_self_test - 指定したモジュールのセルフテストを実行する
    • md5 - 文字列のmd5ハッシュ値を計算する
    • md5_file - 指定したファイルのMD5ハッシュ値を計算する
    • mdecrypt_generic - データを復号する
    • Memcache::add - サーバーに項目を追加する
    • Memcache::addServer - コネクションプールに memcached サーバーを追加する
    • Memcache::close - memcached サーバーとの接続を閉じる
    • Memcache::connect - memcached サーバーへの接続をオープンする
    • Memcache::decrement - 項目の値を減らす
    • Memcache::delete - サーバーから項目を削除する
    • Memcache::flush - サーバー上のすべての既存項目を消去する
    • Memcache::get - サーバーから項目を取得する
    • Memcache::getExtendedStats - プール内のすべてのサーバーの統計情報を取得する
    • Memcache::getServerStatus - サーバーの状態を返す
    • Memcache::getStats - サーバーの統計情報を取得する
    • Memcache::getVersion - サーバーのバージョンを返す
    • Memcache::increment - 項目の値を増やす
    • Memcache::pconnect - memcached サーバーへの持続的な接続をオープンする
    • Memcache::replace - 既存項目の値を置換する
    • Memcache::set - データをサーバーに格納する
    • Memcache::setCompressThreshold - 大きな値に対する自動圧縮処理を有効にする
    • Memcache::setServerParams - サーバーのパラメータおよび状態を、実行時に変更する
    • Memcached::add - アイテムを新しいキーで追加する
    • Memcached::addByKey - 指定したサーバーにアイテムを新しいキーで追加する
    • Memcached::addServer - サーバーをサーバープールに追加する
    • Memcached::addServers - 複数のサーバーをサーバープールに追加する
    • Memcached::append - データを既存のアイテムに追記する
    • Memcached::appendByKey - 指定したサーバーでデータを既存のアイテムに追記する
    • Memcached::cas - アイテムを比較して入れ替える
    • Memcached::casByKey - 指定したサーバーでアイテムを比較して入れ替える
    • Memcached::decrement - 数値アイテムの値を減らす
    • Memcached::decrementByKey - 指定したサーバー上にある数値アイテムの値を減らす
    • Memcached::delete - アイテムを削除する
    • Memcached::deleteByKey - 指定したサーバーからアイテムを削除する
    • Memcached::deleteMulti - 複数のアイテムを削除する
    • Memcached::deleteMultiByKey - 指定したサーバーから複数のアイテムを削除する
    • Memcached::fetch - 次の結果を取得する
    • Memcached::fetchAll - 残りのすべての結果を取得する
    • Memcached::flush - キャッシュ内のすべてのアイテムを無効にする
    • Memcached::get - アイテムを取得する
    • Memcached::getAllKeys - すべてのサーバーのキーを取得する
    • Memcached::getByKey - 指定したサーバーからアイテムを取得する
    • Memcached::getDelayed - 複数のアイテムを要求する
    • Memcached::getDelayedByKey - 指定したサーバーに複数のアイテムを要求する
    • Memcached::getMulti - 複数のアイテムを取得する
    • Memcached::getMultiByKey - 指定したサーバーから複数のアイテムを取得する
    • Memcached::getOption - Memcached のオプションの値を取得する
    • Memcached::getResultCode - 直近の操作の結果コードを返す
    • Memcached::getResultMessage - 最後に実行した操作の結果を説明したメッセージを返す。
    • Memcached::getServerByKey - キーとサーバーを関連付ける
    • Memcached::getServerList - プール内のサーバーの一覧を取得する
    • Memcached::getStats - サーバープールの統計情報を取得する
    • Memcached::getVersion - サーバープールのバージョン情報を取得する
    • Memcached::increment - 数値アイテムの値を増やす
    • Memcached::incrementByKey - 指定したサーバー上にある数値アイテムの値を増やす
    • Memcached::isPersistent - memcache への接続で持続的接続を使っているかどうかを調べる
    • Memcached::isPristine - 直近に作られたインスタンスかどうかを調べる
    • Memcached::prepend - 既存のアイテムの前にデータを付加する
    • Memcached::prependByKey - 指定したサーバーで既存のアイテムの前にデータを付加する
    • Memcached::quit - 開いている接続を閉じる
    • Memcached::replace - 既存のキーのアイテムを入れ替える
    • Memcached::replaceByKey - 指定したサーバーで既存のキーのアイテムを入れ替える
    • Memcached::resetServerList - サーバーリストからすべてのサーバーを消去する
    • Memcached::set - アイテムを格納する
    • Memcached::setByKey - 指定したサーバーにアイテムを格納する
    • Memcached::setMulti - 複数のアイテムを格納する
    • Memcached::setMultiByKey - 指定したサーバーで複数のアイテムを格納する
    • Memcached::setOption - Memcached のオプションの値を設定する
    • Memcached::setOptions - Memcached のオプションの値を設定する
    • Memcached::setSaslAuthData - 認証用の資格情報を設定する
    • Memcached::touch - アイテムに新しい有効期限を設定する
    • Memcached::touchByKey - 指定したサーバー上のアイテムに新しい有効期限を設定する
    • Memcached::__construct - Memcached のインスタンスを作成する
    • memcache_debug - デバッグ出力のオン/オフを切り替える
    • memory_get_peak_usage - PHP によって割り当てられたメモリの最大値を返す
    • memory_get_usage - PHP に割り当てられたメモリの量を返す
    • memory_reset_peak_usage - メモリの最大値をリセットする
    • MessageFormatter::create - 新しいメッセージフォーマッタを作成する
    • MessageFormatter::format - メッセージをフォーマットする
    • MessageFormatter::formatMessage - 手早くメッセージをフォーマットする
    • MessageFormatter::getErrorCode - 直近の操作のエラーコードを取得する
    • MessageFormatter::getErrorMessage - 直近の操作のエラーテキストを取得する
    • MessageFormatter::getLocale - フォーマッタを作成した際のロケールを取得する
    • MessageFormatter::getPattern - フォーマッタが使用するパターンを取得する
    • MessageFormatter::parse - パターンを使用して入力文字列をパースする
    • MessageFormatter::parseMessage - 手早く入力文字列をパースする
    • MessageFormatter::setPattern - フォーマッタが使用するパターンを設定する
    • metaphone - 文字列の metaphone キーを計算する
    • method_exists - クラスメソッドが存在するかどうかを確認する
    • mhash - ハッシュ値を計算する
    • mhash_count - 利用可能なハッシュ ID の最大値を得る
    • mhash_get_block_size - 指定したハッシュのブロックサイズを得る
    • mhash_get_hash_name - 指定したハッシュの名前を得る
    • mhash_keygen_s2k - キーを生成する
    • microtime - 現在の Unix タイムスタンプをマイクロ秒まで返す
    • mime_content_type - ファイルの MIME Content-type を検出する
    • min - 最小値を返す
    • mkdir - ディレクトリを作る
    • mktime - 日付を Unix のタイムスタンプとして取得する
    • money_format - 数値を金額文字列にフォーマットする
    • MongoDB\BSON\Binary::getData - Returns the Binary's data
    • MongoDB\BSON\Binary::getType - Returns the Binary's type
    • MongoDB\BSON\Binary::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Binary::serialize - Serialize a Binary
    • MongoDB\BSON\Binary::unserialize - Unserialize a Binary
    • MongoDB\BSON\Binary::__construct - Construct a new Binary
    • MongoDB\BSON\Binary::__toString - Returns the Binary's data
    • MongoDB\BSON\BinaryInterface::getData - Returns the BinaryInterface's data
    • MongoDB\BSON\BinaryInterface::getType - Returns the BinaryInterface's type
    • MongoDB\BSON\BinaryInterface::__toString - Returns the BinaryInterface's data
    • MongoDB\BSON\DBPointer::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\DBPointer::serialize - Serialize a DBPointer
    • MongoDB\BSON\DBPointer::unserialize - Unserialize a DBPointer
    • MongoDB\BSON\DBPointer::__construct - Construct a new DBPointer (unused)
    • MongoDB\BSON\DBPointer::__toString - Returns an empty string
    • MongoDB\BSON\Decimal128::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Decimal128::serialize - Serialize a Decimal128
    • MongoDB\BSON\Decimal128::unserialize - Unserialize a Decimal128
    • MongoDB\BSON\Decimal128::__construct - Construct a new Decimal128
    • MongoDB\BSON\Decimal128::__toString - Returns the string representation of this Decimal128
    • MongoDB\BSON\Decimal128Interface::__toString - Returns the string representation of this Decimal128Interface
    • MongoDB\BSON\Document::fromBSON - Construct a new document instance from a BSON string
    • MongoDB\BSON\Document::fromJSON - Construct a new document instance from a JSON string
    • MongoDB\BSON\Document::fromPHP - Construct a new document instance from PHP data
    • MongoDB\BSON\Document::get - Returns the value of a key in the document
    • MongoDB\BSON\Document::getIterator - Returns an iterator for the BSON document
    • MongoDB\BSON\Document::has - Returns whether a key is present in the document
    • MongoDB\BSON\Document::offsetExists - Returns whether a key is present in the document
    • MongoDB\BSON\Document::offsetGet - Returns the value of a key in the document
    • MongoDB\BSON\Document::offsetSet - Implementation of ArrayAccess
    • MongoDB\BSON\Document::offsetUnset - Implementation of ArrayAccess
    • MongoDB\BSON\Document::serialize - Serialize a Document
    • MongoDB\BSON\Document::toCanonicalExtendedJSON - Returns the Canonical Extended JSON representation of the BSON document
    • MongoDB\BSON\Document::toPHP - Returns the PHP representation of the BSON document
    • MongoDB\BSON\Document::toRelaxedExtendedJSON - Returns the Relaxed Extended JSON representation of the BSON document
    • MongoDB\BSON\Document::unserialize - Unserialize a BSON document
    • MongoDB\BSON\Document::__construct - Construct a new BSON document (unused)
    • MongoDB\BSON\Document::__toString - Returns the string representation of this BSON Document
    • MongoDB\BSON\fromJSON - Returns the BSON representation of a JSON value
    • MongoDB\BSON\fromPHP - Returns the BSON representation of a PHP value
    • MongoDB\BSON\Int64::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Int64::serialize - Serialize an Int64
    • MongoDB\BSON\Int64::unserialize - Unserialize an Int64
    • MongoDB\BSON\Int64::__construct - Construct a new Int64
    • MongoDB\BSON\Int64::__toString - Returns the string representation of this Int64
    • MongoDB\BSON\Iterator::current - Returns the current element
    • MongoDB\BSON\Iterator::key - Returns the key of the current element
    • MongoDB\BSON\Iterator::next - Advances the iterator to next element
    • MongoDB\BSON\Iterator::rewind - Rewinds the Iterator to the first element
    • MongoDB\BSON\Iterator::valid - Checks if current position is valid
    • MongoDB\BSON\Iterator::__construct - Construct a new BSON iterator (unused)
    • MongoDB\BSON\Javascript::getCode - Returns the Javascript's code
    • MongoDB\BSON\Javascript::getScope - Returns the Javascript's scope document
    • MongoDB\BSON\Javascript::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Javascript::serialize - Serialize a Javascript
    • MongoDB\BSON\Javascript::unserialize - Unserialize a Javascript
    • MongoDB\BSON\Javascript::__construct - Construct a new Javascript
    • MongoDB\BSON\Javascript::__toString - Returns the Javascript's code
    • MongoDB\BSON\JavascriptInterface::getCode - Returns the JavascriptInterface's code
    • MongoDB\BSON\JavascriptInterface::getScope - Returns the JavascriptInterface's scope document
    • MongoDB\BSON\JavascriptInterface::__toString - Returns the JavascriptInterface's code
    • MongoDB\BSON\MaxKey::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\MaxKey::serialize - Serialize a MaxKey
    • MongoDB\BSON\MaxKey::unserialize - Unserialize a MaxKey
    • MongoDB\BSON\MaxKey::__construct - Construct a new MaxKey
    • MongoDB\BSON\MinKey::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\MinKey::serialize - Serialize a MinKey
    • MongoDB\BSON\MinKey::unserialize - Unserialize a MinKey
    • MongoDB\BSON\MinKey::__construct - Construct a new MinKey
    • MongoDB\BSON\ObjectId::getTimestamp - Returns the timestamp component of this ObjectId
    • MongoDB\BSON\ObjectId::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\ObjectId::serialize - Serialize an ObjectId
    • MongoDB\BSON\ObjectId::unserialize - Unserialize an ObjectId
    • MongoDB\BSON\ObjectId::__construct - Construct a new ObjectId
    • MongoDB\BSON\ObjectId::__toString - Returns the hexidecimal representation of this ObjectId
    • MongoDB\BSON\ObjectIdInterface::getTimestamp - Returns the timestamp component of this ObjectIdInterface
    • MongoDB\BSON\ObjectIdInterface::__toString - Returns the hexidecimal representation of this ObjectIdInterface
    • MongoDB\BSON\PackedArray::fromPHP - Construct a new BSON array instance from PHP data
    • MongoDB\BSON\PackedArray::get - Returns the value of an index in the array
    • MongoDB\BSON\PackedArray::getIterator - Returns an iterator for the BSON array
    • MongoDB\BSON\PackedArray::has - Returns whether a index is present in the array
    • MongoDB\BSON\PackedArray::offsetExists - Returns whether a index is present in the array
    • MongoDB\BSON\PackedArray::offsetGet - Returns the value of an index in the array
    • MongoDB\BSON\PackedArray::offsetSet - Implementation of ArrayAccess
    • MongoDB\BSON\PackedArray::offsetUnset - Implementation of ArrayAccess
    • MongoDB\BSON\PackedArray::serialize - Serialize a BSON array
    • MongoDB\BSON\PackedArray::toPHP - Returns the PHP representation of the BSON array
    • MongoDB\BSON\PackedArray::unserialize - Unserialize a BSON array
    • MongoDB\BSON\PackedArray::__construct - Construct a new BSON array (unused)
    • MongoDB\BSON\PackedArray::__toString - Returns the string representation of this BSON array
    • MongoDB\BSON\Persistable::bsonSerialize - Provides an array or document to serialize as BSON
    • MongoDB\BSON\Regex::getFlags - Returns the Regex's flags
    • MongoDB\BSON\Regex::getPattern - Returns the Regex's pattern
    • MongoDB\BSON\Regex::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Regex::serialize - Serialize a Regex
    • MongoDB\BSON\Regex::unserialize - Unserialize a Regex
    • MongoDB\BSON\Regex::__construct - Construct a new Regex
    • MongoDB\BSON\Regex::__toString - Returns the string representation of this Regex
    • MongoDB\BSON\RegexInterface::getFlags - Returns the RegexInterface's flags
    • MongoDB\BSON\RegexInterface::getPattern - Returns the RegexInterface's pattern
    • MongoDB\BSON\RegexInterface::__toString - Returns the string representation of this RegexInterface
    • MongoDB\BSON\Serializable::bsonSerialize - Provides an array or document to serialize as BSON
    • MongoDB\BSON\Symbol::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Symbol::serialize - Serialize a Symbol
    • MongoDB\BSON\Symbol::unserialize - Unserialize a Symbol
    • MongoDB\BSON\Symbol::__construct - Construct a new Symbol (unused)
    • MongoDB\BSON\Symbol::__toString - Returns the Symbol as a string
    • MongoDB\BSON\Timestamp::getIncrement - Returns the increment component of this Timestamp
    • MongoDB\BSON\Timestamp::getTimestamp - Returns the timestamp component of this Timestamp
    • MongoDB\BSON\Timestamp::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Timestamp::serialize - Serialize a Timestamp
    • MongoDB\BSON\Timestamp::unserialize - Unserialize a Timestamp
    • MongoDB\BSON\Timestamp::__construct - Construct a new Timestamp
    • MongoDB\BSON\Timestamp::__toString - Returns the string representation of this Timestamp
    • MongoDB\BSON\TimestampInterface::getIncrement - Returns the increment component of this TimestampInterface
    • MongoDB\BSON\TimestampInterface::getTimestamp - Returns the timestamp component of this TimestampInterface
    • MongoDB\BSON\TimestampInterface::__toString - Returns the string representation of this TimestampInterface
    • MongoDB\BSON\toCanonicalExtendedJSON - Returns the Canonical Extended JSON representation of a BSON value
    • MongoDB\BSON\toJSON - Returns the Legacy Extended JSON representation of a BSON value
    • MongoDB\BSON\toPHP - Returns the PHP representation of a BSON value
    • MongoDB\BSON\toRelaxedExtendedJSON - Returns the Relaxed Extended JSON representation of a BSON value
    • MongoDB\BSON\Undefined::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\Undefined::serialize - Serialize a Undefined
    • MongoDB\BSON\Undefined::unserialize - Unserialize a Undefined
    • MongoDB\BSON\Undefined::__construct - Construct a new Undefined (unused)
    • MongoDB\BSON\Undefined::__toString - Returns an empty string
    • MongoDB\BSON\Unserializable::bsonUnserialize - Constructs the object from a BSON array or document
    • MongoDB\BSON\UTCDateTime::jsonSerialize - Returns a representation that can be converted to JSON
    • MongoDB\BSON\UTCDateTime::serialize - Serialize a UTCDateTime
    • MongoDB\BSON\UTCDateTime::toDateTime - Returns the DateTime representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::toDateTimeImmutable - Returns the DateTimeImmutable representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTime::unserialize - Unserialize a UTCDateTime
    • MongoDB\BSON\UTCDateTime::__construct - Construct a new UTCDateTime
    • MongoDB\BSON\UTCDateTime::__toString - Returns the string representation of this UTCDateTime
    • MongoDB\BSON\UTCDateTimeInterface::toDateTime - Returns the DateTime representation of this UTCDateTimeInterface
    • MongoDB\BSON\UTCDateTimeInterface::__toString - Returns the string representation of this UTCDateTimeInterface
    • MongoDB\Driver\BulkWrite::count - Count number of write operations in the bulk
    • MongoDB\Driver\BulkWrite::delete - Add a delete operation to the bulk
    • MongoDB\Driver\BulkWrite::insert - Add an insert operation to the bulk
    • MongoDB\Driver\BulkWrite::update - Add an update operation to the bulk
    • MongoDB\Driver\BulkWrite::__construct - Create a new BulkWrite
    • MongoDB\Driver\ClientEncryption::addKeyAltName - Adds an alternate name to a key document
    • MongoDB\Driver\ClientEncryption::createDataKey - Creates a key document
    • MongoDB\Driver\ClientEncryption::decrypt - Decrypt a value
    • MongoDB\Driver\ClientEncryption::deleteKey - Deletes a key document
    • MongoDB\Driver\ClientEncryption::encrypt - Encrypt a value
    • MongoDB\Driver\ClientEncryption::encryptExpression - Encrypts a match or aggregate expression
    • MongoDB\Driver\ClientEncryption::getKey - Gets a key document
    • MongoDB\Driver\ClientEncryption::getKeyByAltName - Gets a key document by an alternate name
    • MongoDB\Driver\ClientEncryption::getKeys - Gets all key documents
    • MongoDB\Driver\ClientEncryption::removeKeyAltName - Removes an alternate name from a key document
    • MongoDB\Driver\ClientEncryption::rewrapManyDataKey - Rewraps data keys
    • MongoDB\Driver\ClientEncryption::__construct - Create a new ClientEncryption object
    • MongoDB\Driver\Command::__construct - Create a new Command
    • MongoDB\Driver\Cursor::current - Returns the current element
    • MongoDB\Driver\Cursor::getId - Returns the ID for this cursor
    • MongoDB\Driver\Cursor::getServer - Returns the server associated with this cursor
    • MongoDB\Driver\Cursor::isDead - Checks if the cursor is exhausted or may have additional results
    • MongoDB\Driver\Cursor::key - Returns the current result's index within the cursor
    • MongoDB\Driver\Cursor::next - Advances the cursor to the next result
    • MongoDB\Driver\Cursor::rewind - Rewind the cursor to the first result
    • MongoDB\Driver\Cursor::setTypeMap - Sets a type map to use for BSON unserialization
    • MongoDB\Driver\Cursor::toArray - Returns an array containing all results for this cursor
    • MongoDB\Driver\Cursor::valid - Checks if the current position in the cursor is valid
    • MongoDB\Driver\Cursor::__construct - Create a new Cursor (not used)
    • MongoDB\Driver\CursorId::serialize - Serialize a CursorId
    • MongoDB\Driver\CursorId::unserialize - Unserialize a CursorId
    • MongoDB\Driver\CursorId::__construct - Create a new CursorId (not used)
    • MongoDB\Driver\CursorId::__toString - String representation of the cursor ID
    • MongoDB\Driver\CursorInterface::getId - Returns the ID for this cursor
    • MongoDB\Driver\CursorInterface::getServer - Returns the server associated with this cursor
    • MongoDB\Driver\CursorInterface::isDead - Checks if the cursor may have additional results
    • MongoDB\Driver\CursorInterface::setTypeMap - Sets a type map to use for BSON unserialization
    • MongoDB\Driver\CursorInterface::toArray - Returns an array containing all results for this cursor
    • MongoDB\Driver\Exception\CommandException::getResultDocument - Returns the result document for the failed command
    • MongoDB\Driver\Exception\RuntimeException::hasErrorLabel - Returns whether an error label is associated with an exception
    • MongoDB\Driver\Exception\WriteException::getWriteResult - Returns the WriteResult for the failed write operation
    • MongoDB\Driver\Manager::addSubscriber - Registers a monitoring event subscriber with this Manager
    • MongoDB\Driver\Manager::createClientEncryption - Create a new ClientEncryption object
    • MongoDB\Driver\Manager::executeBulkWrite - Execute one or more write operations
    • MongoDB\Driver\Manager::executeCommand - Execute a database command
    • MongoDB\Driver\Manager::executeQuery - Execute a database query
    • MongoDB\Driver\Manager::executeReadCommand - Execute a database command that reads
    • MongoDB\Driver\Manager::executeReadWriteCommand - Execute a database command that reads and writes
    • MongoDB\Driver\Manager::executeWriteCommand - Execute a database command that writes
    • MongoDB\Driver\Manager::getEncryptedFieldsMap - Return the encryptedFieldsMap auto encryption option for the Manager
    • MongoDB\Driver\Manager::getReadConcern - Return the ReadConcern for the Manager
    • MongoDB\Driver\Manager::getReadPreference - Return the ReadPreference for the Manager
    • MongoDB\Driver\Manager::getServers - Return the servers to which this manager is connected
    • MongoDB\Driver\Manager::getWriteConcern - Return the WriteConcern for the Manager
    • MongoDB\Driver\Manager::removeSubscriber - Unregisters a monitoring event subscriber with this Manager
    • MongoDB\Driver\Manager::selectServer - Select a server matching a read preference
    • MongoDB\Driver\Manager::startSession - Start a new client session for use with this client
    • MongoDB\Driver\Manager::__construct - Create new MongoDB Manager
    • MongoDB\Driver\Monitoring\addSubscriber - Registers a monitoring event subscriber globally
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName - Returns the command name
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName - Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros - Returns the command's duration in microseconds
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getError - Returns the Exception associated with the failed command
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId - Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getReply - Returns the command reply document
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId - Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServer - Returns the Server on which the command was executed
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId - Returns the server connection ID for the command
    • MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId - Returns the load balancer service ID for the command
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand - Returns the command document
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName - Returns the command name
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName - Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId - Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId - Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServer - Returns the Server on which the command was executed
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId - Returns the server connection ID for the command
    • MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId - Returns the load balancer service ID for the command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed - Notification method for a failed command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted - Notification method for a started command
    • MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded - Notification method for a successful command
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName - Returns the command name
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName - Returns the database on which the command was executed
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros - Returns the command's duration in microseconds
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId - Returns the command's operation ID
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply - Returns the command reply document
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId - Returns the command's request ID
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer - Returns the Server on which the command was executed
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId - Returns the server connection ID for the command
    • MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId - Returns the load balancer service ID for the command
    • MongoDB\Driver\Monitoring\LogSubscriber::log - Notification method for a log message
    • MongoDB\Driver\Monitoring\removeSubscriber - Unregisters a monitoring event subscriber globally
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged - Notification method for a server description change
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed - Notification method for closing a server
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed - Notification method for a failed server heartbeat
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted - Notification method for a started server heartbeat
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded - Notification method for a successful server heartbeat
    • MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening - Notification method for opening a server
    • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged - Notification method for a topology description change
    • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed - Notification method for closing the topology
    • MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening - Notification method for opening the topology
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getHost - Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription - Returns the new description for the server
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription - Returns the previous description for the server
    • MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId - Returns the topology ID associated with this server
    • MongoDB\Driver\Monitoring\ServerClosedEvent::getHost - Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerClosedEvent::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId - Returns the topology ID associated with this server
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros - Returns the heartbeat's duration in microseconds
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError - Returns the Exception associated with the failed heartbeat
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost - Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited - Returns whether the heartbeat used a streaming protocol
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost - Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited - Returns whether the heartbeat used a streaming protocol
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros - Returns the heartbeat's duration in microseconds
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost - Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply - Returns the heartbeat reply document
    • MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited - Returns whether the heartbeat used a streaming protocol
    • MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost - Returns the hostname of the server
    • MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId - Returns the topology ID associated with this server
    • MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription - Returns the new description for the topology
    • MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription - Returns the previous description for the topology
    • MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId - Returns the topology ID
    • MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId - Returns the topology ID
    • MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId - Returns the topology ID
    • MongoDB\Driver\Query::__construct - Create a new Query
    • MongoDB\Driver\ReadConcern::bsonSerialize - Returns an object for BSON serialization
    • MongoDB\Driver\ReadConcern::getLevel - Returns the ReadConcern's "level" option
    • MongoDB\Driver\ReadConcern::isDefault - Checks if this is the default read concern
    • MongoDB\Driver\ReadConcern::serialize - Serialize a ReadConcern
    • MongoDB\Driver\ReadConcern::unserialize - Unserialize a ReadConcern
    • MongoDB\Driver\ReadConcern::__construct - Create a new ReadConcern
    • MongoDB\Driver\ReadPreference::bsonSerialize - Returns an object for BSON serialization
    • MongoDB\Driver\ReadPreference::getHedge - Returns the ReadPreference's "hedge" option
    • MongoDB\Driver\ReadPreference::getMaxStalenessSeconds - Returns the ReadPreference's "maxStalenessSeconds" option
    • MongoDB\Driver\ReadPreference::getMode - Returns the ReadPreference's "mode" option
    • MongoDB\Driver\ReadPreference::getModeString - Returns the ReadPreference's "mode" option as a string
    • MongoDB\Driver\ReadPreference::getTagSets - Returns the ReadPreference's "tagSets" option
    • MongoDB\Driver\ReadPreference::serialize - Serialize a ReadPreference
    • MongoDB\Driver\ReadPreference::unserialize - Unserialize a ReadPreference
    • MongoDB\Driver\ReadPreference::__construct - Create a new ReadPreference
    • MongoDB\Driver\Server::executeBulkWrite - Execute one or more write operations on this server
    • MongoDB\Driver\Server::executeCommand - Execute a database command on this server
    • MongoDB\Driver\Server::executeQuery - Execute a database query on this server
    • MongoDB\Driver\Server::executeReadCommand - Execute a database command that reads on this server
    • MongoDB\Driver\Server::executeReadWriteCommand - Execute a database command that reads and writes on this server
    • MongoDB\Driver\Server::executeWriteCommand - Execute a database command that writes on this server
    • MongoDB\Driver\Server::getHost - Returns the hostname of this server
    • MongoDB\Driver\Server::getInfo - Returns an array of information describing this server
    • MongoDB\Driver\Server::getLatency - Returns the latency of this server in milliseconds
    • MongoDB\Driver\Server::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\Server::getServerDescription - Returns a ServerDescription for this server
    • MongoDB\Driver\Server::getTags - Returns an array of tags describing this server in a replica set
    • MongoDB\Driver\Server::getType - Returns an integer denoting the type of this server
    • MongoDB\Driver\Server::isArbiter - Checks if this server is an arbiter member of a replica set
    • MongoDB\Driver\Server::isHidden - Checks if this server is a hidden member of a replica set
    • MongoDB\Driver\Server::isPassive - Checks if this server is a passive member of a replica set
    • MongoDB\Driver\Server::isPrimary - Checks if this server is a primary member of a replica set
    • MongoDB\Driver\Server::isSecondary - Checks if this server is a secondary member of a replica set
    • MongoDB\Driver\Server::__construct - Create a new Server (not used)
    • MongoDB\Driver\ServerApi::bsonSerialize - Returns an object for BSON serialization
    • MongoDB\Driver\ServerApi::serialize - Serialize a ServerApi
    • MongoDB\Driver\ServerApi::unserialize - Unserialize a ServerApi
    • MongoDB\Driver\ServerApi::__construct - Create a new ServerApi instance
    • MongoDB\Driver\ServerDescription::getHelloResponse - Returns the server's most recent "hello" response
    • MongoDB\Driver\ServerDescription::getHost - Returns the hostname of this server
    • MongoDB\Driver\ServerDescription::getLastUpdateTime - Returns the server's last update time in microseconds
    • MongoDB\Driver\ServerDescription::getPort - Returns the port on which this server is listening
    • MongoDB\Driver\ServerDescription::getRoundTripTime - Returns the server's round trip time in milliseconds
    • MongoDB\Driver\ServerDescription::getType - Returns a string denoting the type of this server
    • MongoDB\Driver\Session::abortTransaction - Aborts a transaction
    • MongoDB\Driver\Session::advanceClusterTime - Advances the cluster time for this session
    • MongoDB\Driver\Session::advanceOperationTime - Advances the operation time for this session
    • MongoDB\Driver\Session::commitTransaction - Commits a transaction
    • MongoDB\Driver\Session::endSession - Terminates a session
    • MongoDB\Driver\Session::getClusterTime - Returns the cluster time for this session
    • MongoDB\Driver\Session::getLogicalSessionId - Returns the logical session ID for this session
    • MongoDB\Driver\Session::getOperationTime - Returns the operation time for this session
    • MongoDB\Driver\Session::getServer - Returns the server to which this session is pinned
    • MongoDB\Driver\Session::getTransactionOptions - Returns options for the currently running transaction
    • MongoDB\Driver\Session::getTransactionState - Returns the current transaction state for this session
    • MongoDB\Driver\Session::isDirty - Returns whether the session has been marked as dirty
    • MongoDB\Driver\Session::isInTransaction - Returns whether a multi-document transaction is in progress
    • MongoDB\Driver\Session::startTransaction - Starts a transaction
    • MongoDB\Driver\Session::__construct - Create a new Session (not used)
    • MongoDB\Driver\TopologyDescription::getServers - Returns the servers in the topology
    • MongoDB\Driver\TopologyDescription::getType - Returns a string denoting the type of this topology
    • MongoDB\Driver\TopologyDescription::hasReadableServer - Returns whether the topology has a readable server
    • MongoDB\Driver\TopologyDescription::hasWritableServer - Returns whether the topology has a writable server
    • MongoDB\Driver\WriteConcern::bsonSerialize - Returns an object for BSON serialization
    • MongoDB\Driver\WriteConcern::getJournal - Returns the WriteConcern's "journal" option
    • MongoDB\Driver\WriteConcern::getW - Returns the WriteConcern's "w" option
    • MongoDB\Driver\WriteConcern::getWtimeout - Returns the WriteConcern's "wtimeout" option
    • MongoDB\Driver\WriteConcern::isDefault - Checks if this is the default write concern
    • MongoDB\Driver\WriteConcern::serialize - Serialize a WriteConcern
    • MongoDB\Driver\WriteConcern::unserialize - Unserialize a WriteConcern
    • MongoDB\Driver\WriteConcern::__construct - Create a new WriteConcern
    • MongoDB\Driver\WriteConcernError::getCode - Returns the WriteConcernError's error code
    • MongoDB\Driver\WriteConcernError::getInfo - Returns metadata document for the WriteConcernError
    • MongoDB\Driver\WriteConcernError::getMessage - Returns the WriteConcernError's error message
    • MongoDB\Driver\WriteError::getCode - Returns the WriteError's error code
    • MongoDB\Driver\WriteError::getIndex - Returns the index of the write operation corresponding to this WriteError
    • MongoDB\Driver\WriteError::getInfo - Returns metadata document for the WriteError
    • MongoDB\Driver\WriteError::getMessage - Returns the WriteError's error message
    • MongoDB\Driver\WriteResult::getDeletedCount - Returns the number of documents deleted
    • MongoDB\Driver\WriteResult::getInsertedCount - Returns the number of documents inserted (excluding upserts)
    • MongoDB\Driver\WriteResult::getMatchedCount - Returns the number of documents selected for update
    • MongoDB\Driver\WriteResult::getModifiedCount - Returns the number of existing documents updated
    • MongoDB\Driver\WriteResult::getServer - Returns the server associated with this write result
    • MongoDB\Driver\WriteResult::getUpsertedCount - Returns the number of documents inserted by an upsert
    • MongoDB\Driver\WriteResult::getUpsertedIds - Returns an array of identifiers for upserted documents
    • MongoDB\Driver\WriteResult::getWriteConcernError - Returns any write concern error that occurred
    • MongoDB\Driver\WriteResult::getWriteErrors - Returns any write errors that occurred
    • MongoDB\Driver\WriteResult::isAcknowledged - Returns whether the write was acknowledged
    • move_uploaded_file - アップロードされたファイルを新しい位置に移動する
    • mqseries_back - MQSeries MQBACK
    • mqseries_begin - MQseries MQBEGIN
    • mqseries_close - MQSeries MQCLOSE
    • mqseries_cmit - MQSeries MQCMIT
    • mqseries_conn - MQSeries MQCONN
    • mqseries_connx - MQSeries MQCONNX
    • mqseries_disc - MQSeries MQDISC
    • mqseries_get - MQSeries MQGET
    • mqseries_inq - MQSeries MQINQ
    • mqseries_open - MQSeries MQOPEN
    • mqseries_put - MQSeries MQPUT
    • mqseries_put1 - MQSeries MQPUT1
    • mqseries_set - MQSeries MQSET
    • mqseries_strerror - 結果コード (MQRC) に対応するエラーメッセージを返す
    • msg_get_queue - メッセージキューを作成またはそれにアタッチする
    • msg_queue_exists - メッセージキューが存在するかどうかを調べる
    • msg_receive - メッセージキューからメッセージを受信する
    • msg_remove_queue - メッセージキューを破棄する
    • msg_send - メッセージキューにメッセージを送信する
    • msg_set_queue - メッセージキューデータ構造体の情報を設定する
    • msg_stat_queue - メッセージキューデータ構造体の情報を返す
    • mt_getrandmax - 乱数値の最大値を表示する
    • mt_rand - メルセンヌ・ツイスター乱数生成器を介して乱数値を生成する
    • mt_srand - メルセンヌ・ツイスター乱数生成器にシードを指定する
    • MultipleIterator::attachIterator - イテレータの情報をアタッチする
    • MultipleIterator::containsIterator - イテレータがアタッチされているかどうかを調べる
    • MultipleIterator::countIterators - アタッチされているイテレータインスタンスの数を取得する
    • MultipleIterator::current - 登録されているイテレータインスタンスを取得する
    • MultipleIterator::detachIterator - イテレータをデタッチする
    • MultipleIterator::getFlags - フラグの情報を取得する
    • MultipleIterator::key - 登録されているイテレータインスタンスを取得する
    • MultipleIterator::next - アタッチしているすべてのイテレータインスタンスを次に移動させる
    • MultipleIterator::rewind - アタッチしているすべてのイテレータインスタンスを巻き戻す
    • MultipleIterator::setFlags - フラグを設定する
    • MultipleIterator::valid - サブイテレータの有効性を調べる
    • MultipleIterator::__construct - 新しい MultipleIterator を作成する
    • mysqli::$affected_rows - 直前の MySQL の操作で変更された行の数を得る
    • mysqli::$client_info - MySQL クライアント情報を取得する
    • mysqli::$client_version - MySQL クライアントのバージョンを整数値で返す
    • mysqli::$connect_errno - 直近の接続コールに関するエラーコードを返す
    • mysqli::$connect_error - 直近の接続エラーの説明を返す
    • mysqli::$errno - 直近の関数コールによるエラーコードを返す
    • mysqli::$error - 直近のエラーの内容を文字列で返す
    • mysqli::$error_list - 直近で実行したコマンドからのエラーの一覧を返す
    • mysqli::$field_count - 直近のクエリのカラムの数を返す
    • mysqli::$host_info - 使用している接続の型を文字列で返す
    • mysqli::$info - 直近に実行されたクエリの情報を取得する
    • mysqli::$insert_id - 直近のクエリの AUTO_INCREMENT カラムで生成した値を返す
    • mysqli::$protocol_version - 使用している MySQL プロトコルのバージョンを返す
    • mysqli::$server_info - MySQL サーバーのバージョンを返す
    • mysqli::$server_version - MySQL サーバーのバージョンを整数値で返す
    • mysqli::$sqlstate - 直前の MySQL の操作での SQLSTATE エラーを返す
    • mysqli::$thread_id - 現在の接続のスレッド ID を返す
    • mysqli::$warning_count - 指定した接続の直近のクエリから発生した警告の数を返す
    • mysqli::autocommit - データベース更新の自動コミットをオンまたはオフにする
    • mysqli::begin_transaction - トランザクションを開始する
    • mysqli::change_user - 指定されたデータベース接続のユーザー名を変更する
    • mysqli::character_set_name - データベース接続の現在の文字コードセットを返す
    • mysqli::close - 事前にオープンしているデータベース接続を閉じる
    • mysqli::commit - 現在のトランザクションをコミットする
    • mysqli::debug - デバッグ操作を行う
    • mysqli::dump_debug_info - デバッグ情報をログに出力する
    • mysqli::escape_string - mysqli_real_escape_string のエイリアス
    • mysqli::execute_query - SQL文を準備し、変数をバインドし、実行する
    • mysqli::get_charset - 文字セットオブジェクトを返す
    • mysqli::get_connection_stats - クライアント接続に関する統計情報を返す
    • mysqli::get_warnings - SHOW WARNINGS の結果を取得する
    • mysqli::init - MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す
    • mysqli::kill - サーバーに MySQL スレッドの停止を問い合わせる
    • mysqli::more_results - マルチクエリからの結果がまだ残っているかどうかを調べる
    • mysqli::multi_query - データベース上でひとつ以上のクエリを実行する
    • mysqli::next_result - multi_query の、次の結果を準備する
    • mysqli::options - オプションを設定する
    • mysqli::ping - サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる
    • mysqli::poll - 接続を問い合わせる
    • mysqli::prepare - 実行するための SQL文 を準備する
    • mysqli::query - データベース上でクエリを実行する
    • mysqli::real_connect - mysql サーバーとの接続をオープンする
    • mysqli::real_escape_string - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
    • mysqli::real_query - SQL クエリを実行する
    • mysqli::reap_async_query - 非同期クエリから結果を取得する
    • mysqli::refresh - リフレッシュする
    • mysqli::release_savepoint - 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する
    • mysqli::rollback - 現在のトランザクションをロールバックする
    • mysqli::savepoint - トランザクションのセーブポイントを設定する
    • mysqli::select_db - クエリを実行するためのデフォルトのデータベースを選択する
    • mysqli::set_charset - クライアントの文字セットを設定する
    • mysqli::set_opt - mysqli_options のエイリアス
    • mysqli::ssl_set - SSL を使用したセキュアな接続を確立する
    • mysqli::stat - 現在のシステム状態を取得する
    • mysqli::stmt_init - ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す
    • mysqli::store_result - 直近のクエリから結果セットを転送する
    • mysqli::thread_safe - スレッドセーフであるかどうかを返す
    • mysqli::use_result - 結果セットの取得を開始する
    • mysqli::__construct - 新規に MySQL サーバーへの接続をオープンする
    • mysqli_connect - mysqli::__construct のエイリアス
    • mysqli_driver::$report_mode - mysqli のエラー報告モードを設定する
    • mysqli_driver::embedded_server_end - 組み込みサーバーを停止する
    • mysqli_driver::embedded_server_start - 組み込みサーバーを初期化して開始する
    • mysqli_execute - mysqli_stmt_execute のエイリアス
    • mysqli_get_client_stats - プロセスごとのクライアントの統計を返す
    • mysqli_get_links_stats - オープン済みとキャッシュ済みのリンクに関する情報を返す
    • mysqli_report - mysqli_driver->report_mode のエイリアス
    • mysqli_result::$current_field - 結果ポインタにおける現在のフィールドオフセットを取得する
    • mysqli_result::$field_count - 結果セットのフィールド数を取得する
    • mysqli_result::$lengths - 結果セットにおける現在の行のカラムの長さを返す
    • mysqli_result::$num_rows - 結果セットの行数を取得する
    • mysqli_result::data_seek - 結果の任意の行にポインタを移動する
    • mysqli_result::fetch_all - 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する
    • mysqli_result::fetch_array - 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する
    • mysqli_result::fetch_assoc - 結果セットの次の行を連想配列で取得する
    • mysqli_result::fetch_column - 結果セットの次の行から、単一のカラムの値を取得する
    • mysqli_result::fetch_field - 結果セットの次のフィールドを返す
    • mysqli_result::fetch_fields - 結果セットのフィールド情報をオブジェクトの配列で返す
    • mysqli_result::fetch_field_direct - 単一のフィールドのメタデータを取得する
    • mysqli_result::fetch_object - 結果セットの次の行を取得し、オブジェクトとして返す
    • mysqli_result::fetch_row - 結果セットの次の行を数値添字配列で取得する
    • mysqli_result::field_seek - 結果ポインタを、指定したフィールドオフセットに設定する
    • mysqli_result::free - 結果に関連付けられたメモリを開放する
    • mysqli_result::getIterator - 外部イテレータを取得する
    • mysqli_result::__construct - mysqli_result オブジェクトを構築する
    • mysqli_sql_exception::getSqlState - SQLSTATE エラーコードを含む情報を返す
    • mysqli_stmt::$affected_rows - 直近に実行されたステートメントで変更・削除・追加、あるいは選択された行の総数を返す
    • mysqli_stmt::$errno - 直近のステートメントのコールに関するエラーコードを返す
    • mysqli_stmt::$error - 直近のステートメントのエラー内容を文字列で返す
    • mysqli_stmt::$error_list - 直近で実行したステートメントからのエラーの一覧を返す
    • mysqli_stmt::$field_count - 指定したステートメントのカラム数を返す
    • mysqli_stmt::$insert_id - 直近の INSERT 操作で生成した ID を取得する
    • mysqli_stmt::$num_rows - サーバーから取得した結果セットの行数を返す
    • mysqli_stmt::$param_count - 指定したステートメントのパラメータ数を返す
    • mysqli_stmt::$sqlstate - 直前のステートメントの操作での SQLSTATE エラーを返す
    • mysqli_stmt::attr_get - ステートメントの属性の現在の値を取得する
    • mysqli_stmt::attr_set - プリペアドステートメントの振る舞いを変更する
    • mysqli_stmt::bind_param - プリペアドステートメントのパラメータに変数をバインドする
    • mysqli_stmt::bind_result - 結果を保存するため、プリペアドステートメントに変数をバインドする
    • mysqli_stmt::close - プリペアドステートメントを閉じる
    • mysqli_stmt::data_seek - バッファリングされた結果中の、任意の行にポインタを移動する
    • mysqli_stmt::execute - プリペアドステートメントを実行する
    • mysqli_stmt::fetch - プリペアドステートメントから結果を取得し、バインド変数に格納する
    • mysqli_stmt::free_result - 指定したステートメントハンドルの結果を格納したメモリを開放する
    • mysqli_stmt::get_result - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する
    • mysqli_stmt::get_warnings - SHOW WARNINGS の結果を取得する
    • mysqli_stmt::more_results - 複数クエリで、次の結果が存在するかどうかを調べる
    • mysqli_stmt::next_result - 複数クエリから、次の結果を読み込む
    • mysqli_stmt::prepare - SQL ステートメントを実行するために準備する
    • mysqli_stmt::reset - プリペアドステートメントをリセットする
    • mysqli_stmt::result_metadata - プリペアドステートメントから結果セットのメタデータを返す
    • mysqli_stmt::send_long_data - データをブロックで送信する
    • mysqli_stmt::store_result - 内部バッファに結果を保存する
    • mysqli_stmt::__construct - 新しい mysqli_stmt オブジェクトを構築する
    • mysqli_warning::next - 次の警告を取得する
    • mysqli_warning::__construct - インスタンス化を禁止するための private なコンストラクタ
    • mysql_affected_rows - 一番最近の操作で変更された行の数を得る
    • mysql_client_encoding - 文字セット名を返す
    • mysql_close - MySQL 接続を閉じる
    • mysql_connect - MySQL サーバーへの接続をオープンする
    • mysql_create_db - MySQL データベースを作成する
    • mysql_data_seek - 内部的な結果ポインタを移動する
    • mysql_db_name - mysql_list_dbs のコール結果からデータベース名を取得する
    • mysql_db_query - データベースを選択し、そこでクエリーを実行する
    • mysql_drop_db - MySQLデータベースを破棄(削除)する
    • mysql_errno - 直近の MySQL 処理からエラーメッセージのエラー番号を返す
    • mysql_error - 直近に実行された MySQL 操作のエラーメッセージを返す
    • mysql_escape_string - mysql_query で使用するために文字列をエスケープする
    • mysql_fetch_array - 連想配列、添字配列、またはその両方として結果の行を取得する
    • mysql_fetch_assoc - 連想配列として結果の行を取得する
    • mysql_fetch_field - 結果からカラム情報を取得し、オブジェクトとして返す
    • mysql_fetch_lengths - 結果における各出力の長さを得る
    • mysql_fetch_object - 結果の行をオブジェクトとして取得する
    • mysql_fetch_row - 結果を添字配列として取得する
    • mysql_field_flags - 結果において指定したフィールドのフラグを取得する
    • mysql_field_len - 指定したフィールドの長さを返す
    • mysql_field_name - 結果において指定したフィールド名を取得する
    • mysql_field_seek - 結果ポインタを指定したフィールドオフセットにセットする
    • mysql_field_table - 指定したフィールドが含まれるテーブルの名前を取得する
    • mysql_field_type - 結果において指定したフィールドの型を取得する
    • mysql_free_result - 結果保持用メモリを開放する
    • mysql_get_client_info - MySQL クライアント情報を取得する
    • mysql_get_host_info - MySQL ホスト情報を取得する
    • mysql_get_proto_info - MySQL プロトコル情報を取得する
    • mysql_get_server_info - MySQL サーバー情報を取得する
    • mysql_info - 直近のクエリについての情報を得る
    • mysql_insert_id - 直近のクエリで生成された ID を得る
    • mysql_list_dbs - MySQL サーバー上で利用可能なデータベースのリストを得る
    • mysql_list_fields - MySQL テーブルのフィールドのリストを得る
    • mysql_list_processes - MySQL プロセスのリストを得る
    • mysql_list_tables - MySQL データベース上のテーブルのリストを得る
    • mysql_num_fields - 結果におけるフィールドの数を得る
    • mysql_num_rows - 結果における行の数を得る
    • mysql_pconnect - MySQL サーバーへの持続的な接続をオープンする
    • mysql_ping - サーバーとの接続状況を調べ、接続されていない場合は再接続する
    • mysql_query - MySQL クエリを送信する
    • mysql_real_escape_string - SQL 文中で用いる文字列の特殊文字をエスケープする
    • mysql_result - 結果データを得る
    • mysql_select_db - MySQL データベースを選択する
    • mysql_set_charset - クライアントの文字セットを設定する
    • mysql_stat - 現在のシステムの状態を取得する
    • mysql_tablename - フィールドのテーブル名を得る
    • mysql_thread_id - カレントのスレッド ID を返す
    • mysql_unbuffered_query - MySQL に SQL クエリを送信するが、結果に対してのフェッチやバッファリングは行わない
    • mysql_xdevapi\Client::close - クライアントの接続を閉じる
  • n
    • natcasesort - 大文字小文字を区別しない"自然順"アルゴリズムを用いて配列をソートする
    • natsort - "自然順"アルゴリズムで配列をソートする
    • net_get_interfaces - ネットワークインターフェイスを取得する
    • next - 配列の内部ポインタを進める
    • ngettext - gettext の複数形版
    • nl2br - 改行文字の前に HTML の改行タグを挿入する
    • nl_langinfo - 言語およびロケール情報を検索する
    • NoRewindIterator::current - 現在の値を取得する
    • NoRewindIterator::key - 現在のキーを取得する
    • NoRewindIterator::next - 次の要素に移動する
    • NoRewindIterator::rewind - 内部イテレータの巻き戻し操作を阻止する
    • NoRewindIterator::valid - イテレータの有効性を検証する
    • NoRewindIterator::__construct - NoRewindIterator を作成する
    • Normalizer::getRawDecomposition - UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する
    • Normalizer::isNormalized - 渡された文字列が、指定した正規化を適用済みかどうかを調べる
    • Normalizer::normalize - 渡された入力を正規化し、正規化後の文字列を返す
    • NumberFormatter::create - 数値フォーマッタを作成する
    • NumberFormatter::format - 数値をフォーマットする
    • NumberFormatter::formatCurrency - 通貨の値をフォーマットする
    • NumberFormatter::getAttribute - 属性を取得する
    • NumberFormatter::getErrorCode - フォーマッタの直近のエラーコードを取得する
    • NumberFormatter::getErrorMessage - フォーマッタの直近のエラーメッセージを取得する
    • NumberFormatter::getLocale - フォーマッタのロケールを取得する
    • NumberFormatter::getPattern - フォーマッタのパターンを取得する
    • NumberFormatter::getSymbol - 記号を取得する
    • NumberFormatter::getTextAttribute - テキストの属性を取得する
    • NumberFormatter::parse - 数値をパースする
    • NumberFormatter::parseCurrency - 通貨をパースする
    • NumberFormatter::setAttribute - 属性を設定する
    • NumberFormatter::setPattern - フォーマッタのパターンを設定する
    • NumberFormatter::setSymbol - 記号の値を設定する
    • NumberFormatter::setTextAttribute - テキスト属性を設定する
    • number_format - 数字を千の位毎にグループ化してフォーマットする
  • o
    • OAuth::disableDebug - デバッグを無効にする
    • OAuth::disableRedirects - リダイレクトを無効にする
    • OAuth::disableSSLChecks - SSL チェックを無効にする
    • OAuth::enableDebug - デバッグを有効にする
    • OAuth::enableRedirects - リダイレクトを有効にする
    • OAuth::enableSSLChecks - SSL チェックを有効にする
    • OAuth::fetch - OAuth で保護されたリソースを取得する
    • OAuth::generateSignature - シグネチャを生成する
    • OAuth::getAccessToken - アクセストークンを取得する
    • OAuth::getCAPath - CA 情報を取得する
    • OAuth::getLastResponse - 直近のレスポンスを取得する
    • OAuth::getLastResponseHeaders - 最後のレスポンスのヘッダを取得する
    • OAuth::getLastResponseInfo - 直近のレスポンスの HTTP 情報を取得する
    • OAuth::getRequestHeader - OAuth ヘッダ文字列シグネチャを生成する
    • OAuth::getRequestToken - リクエストトークンを取得する
    • OAuth::setAuthType - 認証方式を設定する
    • OAuth::setCAPath - CA パスおよび情報を設定する
    • OAuth::setNonce - 続くリクエスト用のノンスを設定する
    • OAuth::setRequestEngine - setRequestEngine
    • OAuth::setRSACertificate - RSA 証明書を設定する
    • OAuth::setSSLChecks - リクエストに固有の SSL チェックを調整する
    • OAuth::setTimestamp - タイムスタンプを設定する
    • OAuth::setToken - トークンと secret を設定する
    • OAuth::setVersion - OAuth のバージョンを設定する
    • OAuth::__construct - 新しい OAuth オブジェクトを作成する
    • OAuth::__destruct - デストラクタ
    • OAuthProvider::addRequiredParameter - 必須パラメータを追加する
    • OAuthProvider::callconsumerHandler - consumerNonceHandler コールバックをコールする
    • OAuthProvider::callTimestampNonceHandler - timestampNonceHandler コールバックをコールする
    • OAuthProvider::calltokenHandler - tokenNonceHandler コールバックをコールする
    • OAuthProvider::checkOAuthRequest - oauth リクエストをチェックする
    • OAuthProvider::consumerHandler - consumerHandler コールバックを設定する
    • OAuthProvider::generateToken - ランダムなトークンを生成する
    • OAuthProvider::is2LeggedEndpoint - is2LeggedEndpoint
    • OAuthProvider::isRequestTokenEndpoint - isRequestTokenEndpoint を設定する
    • OAuthProvider::removeRequiredParameter - 必須パラメータを削除する
    • OAuthProvider::reportProblem - 問題を報告する
    • OAuthProvider::setParam - パラメータを設定する
    • OAuthProvider::setRequestTokenPath - リクエストトークンのパスを設定する
    • OAuthProvider::timestampNonceHandler - timestampNonceHandler コールバックを設定する
    • OAuthProvider::tokenHandler - tokenHandler コールバックを設定する
    • OAuthProvider::__construct - 新しい OAuthProvider オブジェクトを作る
    • oauth_get_sbs - SBSを生成する
    • oauth_urlencode - URI を RFC 3686 形式でエンコードする
    • 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_iconv_handler - 出力バッファハンドラとして文字エンコーディングを変換する
    • ob_implicit_flush - 自動フラッシュをオンまたはオフにする
    • ob_list_handlers - 使用中の出力ハンドラの一覧を取得する
    • ob_start - 出力のバッファリングを有効にする
    • ob_tidyhandler - バッファを修正するための ob_start コールバック関数
    • ocibindbyname - oci_bind_by_name のエイリアス
    • ocicancel - oci_cancel のエイリアス
    • ocicloselob - OCILob::close のエイリアス
    • ocicollappend - のエイリアス OCICollection::append
    • ocicollassign - のエイリアス OCICollection::assign
    • ocicollassignelem - のエイリアス OCICollection::assignElem
    • OCICollection::append - コレクションに要素を追加する
    • OCICollection::assign - コレクションに他の存在するコレクションから値を割り当てる
    • OCICollection::assignElem - コレクションの要素に値を割り当てる
    • OCICollection::free - コレクションオブジェクトに関連付けられたリソースを解放する
    • OCICollection::getElem - 要素の値を返す
    • OCICollection::max - コレクション内の要素の最大数を取得する
    • OCICollection::size - コレクションのサイズを返す
    • OCICollection::trim - コレクションの最後から要素を切り取る
    • ocicollgetelem - のエイリアス OCICollection::getElem
    • ocicollmax - のエイリアス OCICollection::max
    • ocicollsize - のエイリアス OCICollection::size
    • ocicolltrim - のエイリアス OCICollection::trim
    • ocicolumnisnull - oci_field_is_null のエイリアス
    • ocicolumnname - oci_field_name のエイリアス
    • ocicolumnprecision - oci_field_precision のエイリアス
    • ocicolumnscale - oci_field_scale のエイリアス
    • ocicolumnsize - oci_field_size のエイリアス
    • ocicolumntype - oci_field_type のエイリアス
    • ocicolumntyperaw - oci_field_type_raw のエイリアス
    • ocicommit - oci_commit のエイリアス
    • ocidefinebyname - oci_define_by_name のエイリアス
    • ocierror - oci_error のエイリアス
    • ociexecute - oci_execute のエイリアス
    • ocifetch - oci_fetch のエイリアス
    • ocifetchinto - 廃止された関数。oci_fetch_array や oci_fetch_object、 oci_fetch_assoc、 oci_fetch_row の変種
    • ocifetchstatement - oci_fetch_all のエイリアス
    • ocifreecollection - のエイリアス OCICollection::free
    • ocifreecursor - oci_free_statement のエイリアス
    • ocifreedesc - OCILob::free のエイリアス
    • ocifreestatement - oci_free_statement のエイリアス
    • ociinternaldebug - oci_internal_debug のエイリアス
    • ociloadlob - OCILob::load のエイリアス
    • OCILob::append - ラージオブジェクトのデータを他のラージオブジェクトに追加する
    • OCILob::close - LOB ディスクリプタを閉じる
    • OCILob::eof - ラージオブジェクトのディスクリプタが EOF かどうかを調べる
    • OCILob::erase - 内部 LOB データの特定の位置を消去する
    • OCILob::export - LOB の内容をファイルに出力する
    • OCILob::flush - LOB のバッファをサーバーにフラッシュする、あるいは書き込む
    • OCILob::free - LOB ディスクリプタに関連付けられたりソースを解放する
    • OCILob::getBuffering - ラージオブジェクトに対する現在のバッファリングの状態を返す
    • OCILob::import - ファイルデータを LOB にインポートする
    • OCILob::load - ラージオブジェクトの内容を返す
    • OCILob::read - ラージオブジェクトの一部を読み込む
    • OCILob::rewind - 内部ポインタをラージオブジェクトの先頭に移動する
    • OCILob::save - データをラージオブジェクトに保存する
    • OCILob::saveFile - のエイリアス OCILob::import
    • OCILob::seek - ラージオブジェクトの内部ポインタをセットする
    • OCILob::setBuffering - 現在のラージオブジェクト用のバッファリング状態を変更する
    • OCILob::size - ラージオブジェクトのサイズを返す
    • OCILob::tell - ラージオブジェクトの内部ポインタの現在位置を返す
    • OCILob::truncate - ラージオブジェクトを切りつめる
    • OCILob::write - データをラージオブジェクトに書き込む
    • OCILob::writeTemporary - 一時的なラージオブジェクトを書き込む
    • OCILob::writeToFile - のエイリアス OCILob::export
    • ocilogoff - oci_close のエイリアス
    • ocilogon - oci_connect のエイリアス
    • ocinewcollection - oci_new_collection のエイリアス
    • ocinewcursor - oci_new_cursor のエイリアス
    • ocinewdescriptor - oci_new_descriptor のエイリアス
    • ocinlogon - oci_new_connect のエイリアス
    • ocinumcols - oci_num_fields のエイリアス
    • ociparse - oci_parse のエイリアス
    • ociplogon - oci_pconnect のエイリアス
    • ociresult - oci_result のエイリアス
    • ocirollback - oci_rollback のエイリアス
    • ocirowcount - oci_num_rows のエイリアス
    • ocisavelob - OCILob::save のエイリアス
    • ocisavelobfile - OCILob::import のエイリアス
    • ociserverversion - oci_server_version のエイリアス
    • ocisetprefetch - oci_set_prefetch のエイリアス
    • ocistatementtype - oci_statement_type のエイリアス
    • ociwritelobtofile - OCILob::export のエイリアス
    • ociwritetemporarylob - OCILob::writeTemporary のエイリアス
    • oci_bind_array_by_name - PHP の配列を Oracle PL/SQL の配列に名前でバインドする
    • oci_bind_by_name - Oracle プレースホルダに PHP 変数をバインドする
    • oci_cancel - カーソルからの読み込みをキャンセルする
    • oci_client_version - Oracle クライアント・ライブラリのバージョンを返す
    • oci_close - Oracleとの接続を閉じる
    • oci_commit - 未解決のトランザクションをコミットする
    • oci_connect - Oracle データベースに接続する
    • oci_define_by_name - PHP の変数を、クエリで取得するカラムに関連づける
    • oci_error - 最後に見つかったエラーを返す
    • oci_execute - 文を実行する
    • oci_fetch - クエリの次の行を内部バッファに取得する
    • oci_fetch_all - クエリからの複数の行を二次元配列に取得する
    • oci_fetch_array - クエリの次の行を連想配列あるいは数値添字配列で返す
    • oci_fetch_assoc - クエリの次の行を連想配列で返す
    • oci_fetch_object - クエリの次の行をオブジェクトとして返す
    • oci_fetch_row - クエリの次の行を配列で返す
    • oci_field_is_null - フェッチしたフィールドが null であるかどうかを確認する
    • oci_field_name - 文からのフィールド名を返す
    • oci_field_precision - フィールドの精度を問い合わせる
    • oci_field_scale - フィールドの桁数を問い合わせる
    • oci_field_size - フィールドサイズを返す
    • oci_field_type - フィールドのデータ型の名前を返す
    • oci_field_type_raw - Oracle におけるフィールドの型を問い合わせる
    • oci_free_descriptor - ディスクリプタを解放する
    • oci_free_statement - 文やカーソルに関連付けられた全てのリソースを解放する
    • oci_get_implicit_resultset - Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す
    • oci_internal_debug - 内部的なデバッグ出力を有効/無効にする
    • oci_lob_copy - ラージオブジェクトをコピーする
    • oci_lob_is_equal - 2 つの LOB/FILE ロケータの等価性を比較する
    • oci_new_collection - 新しいコレクションオブジェクトを割り当てる
    • oci_new_connect - 一意な接続を使って Oracle サーバーへ接続する
    • oci_new_cursor - 新規カーソル (ステートメントハンドル) を割り当て、それを返す
    • oci_new_descriptor - 空の新規 LOB あるいは FILE ディスクリプタを初期化する
    • oci_num_fields - ある文における結果のカラム数を返す
    • oci_num_rows - 文の実行で作用された行数を取得する
    • oci_parse - 実行のために Oracle の文をパースする
    • oci_password_change - Oracle ユーザーのパスワードを変更する
    • oci_pconnect - 持続的接続を使用してOracle データベースに接続する
    • oci_register_taf_callback - Register a user-defined callback function for Oracle Database TAF
    • oci_result - フェッチした行からフィールドの値を取得する
    • oci_rollback - 未解決のデータベーストランザクションをロールバックする
    • oci_server_version - Oracle データベースのバージョンを返す
    • oci_set_action - アクション名を設定します
    • oci_set_call_timeout - Sets a millisecond timeout for database calls
    • oci_set_client_identifier - クライアント識別子を設定します
    • oci_set_client_info - クライアント情報を設定する
    • oci_set_db_operation - Sets the database operation
    • oci_set_edition - データベース・エディション を設定します
    • oci_set_module_name - モジュール名を設定します
    • oci_set_prefetch - クエリがプリフェッチする行数を設定する
    • oci_set_prefetch_lob - CLOB や BLOB ごとにプリフェッチするデータサイズを設定する
    • oci_statement_type - ステートメントの種類を返す
    • oci_unregister_taf_callback - Unregister a user-defined callback function for Oracle Database TAF
    • octdec - 8 進数を 10 進数に変換する
    • odbc_autocommit - 自動コミットの動作をオンまたはオフにする
    • odbc_binmode - バイナリカラムデータを処理する
    • odbc_close - ODBC 接続を閉じる
    • odbc_close_all - 全ての ODBC 接続を閉じる
    • odbc_columnprivileges - 指定したテーブルに関するカラムおよび付随する権限のリストを取得する
    • odbc_columns - 指定したテーブルにあるカラム名のリストを取得する
    • odbc_commit - ODBC トランザクションをコミットする
    • odbc_connect - データソースに接続する
    • odbc_connection_string_is_quoted - ODBC の接続文字列の値が、クオートされているかを調べる
    • odbc_connection_string_quote - ODBC の接続文字列をクオートする
    • odbc_connection_string_should_quote - ODBC の接続文字列を、クオートすべきかを調べる
    • odbc_cursor - カーソル名を得る
    • odbc_data_source - 利用可能なDSNについての情報を返す
    • odbc_do - odbc_exec のエイリアス
    • odbc_error - 直近のエラーコードを得る
    • odbc_errormsg - 直近のエラーメッセージを得る
    • odbc_exec - SQL文を直接実行する
    • odbc_execute - プリペアドステートメントを実行する
    • odbc_fetch_array - 連想配列として結果の行を取得する
    • odbc_fetch_into - 一行ぶんの結果を配列に取り込む
    • odbc_fetch_object - オブジェクトとして結果の行を取得する
    • odbc_fetch_row - 行を取り込む
    • odbc_field_len - フィールドの長さ (精度) を得る
    • odbc_field_name - カラム名を得る
    • odbc_field_num - カラム番号を返す
    • odbc_field_precision - odbc_field_len のエイリアス
    • odbc_field_scale - フィールドの精度を得る
    • odbc_field_type - フィールドのデータ型を返す
    • odbc_foreignkeys - 外部キーのリストを取得する
    • odbc_free_result - 結果を保持するリソースを開放する
    • odbc_gettypeinfo - データソースがサポートするデータ型についての情報を取得する
    • odbc_longreadlen - LONG カラムを処理する
    • odbc_next_result - 複数の結果が利用可能などうか確認する
    • odbc_num_fields - 結果のカラム数を返す
    • odbc_num_rows - 結果における行数を返す
    • odbc_pconnect - 持続的なデータベース接続を開く
    • odbc_prepare - 実行用に文を準備する
    • odbc_primarykeys - テーブルの主キーを取得する
    • odbc_procedurecolumns - プロシージャへのパラメータに関する情報を取得する
    • odbc_procedures - 指定したデータソースに保存されているプロシージャのリストを取得する
    • odbc_result - 結果データを得る
    • odbc_result_all - HTML テーブルとして結果を出力する
    • odbc_rollback - トランザクションをロールバックする
    • odbc_setoption - ODBC の設定を変更する
    • odbc_specialcolumns - 特殊カラムを取得する
    • odbc_statistics - テーブルに関する統計情報を取得する
    • odbc_tableprivileges - 各テーブルのリストおよび関連する権限のリストを取得する
    • odbc_tables - 指定したデータソースに保存されたテーブルの名前のリストを取得する
    • opcache_compile_file - PHP スクリプトを、実行せずにコンパイルしてキャッシュする
    • opcache_get_configuration - キャッシュについての構成情報を取得
    • opcache_get_status - キャッシュについてのステータス情報を取得
    • opcache_invalidate - キャッシュされたスクリプトを無効にする
    • opcache_is_script_cached - スクリプトが OPCache にキャッシュされているかどうかを伝えます。
    • opcache_reset - opcode のキャッシュ内容をリセットする
    • openal_buffer_create - OpenAL バッファを生成する
    • openal_buffer_data - バッファのデータを読み込む
    • openal_buffer_destroy - OpenAL バッファを削除する
    • openal_buffer_get - OpenAL バッファのプロパティを取得する
    • openal_buffer_loadwav - .wav ファイルをバッファに読み込む
    • openal_context_create - 音声処理コンテキストを作成する
    • openal_context_current - 指定したコンテキストを現在のコンテキストにする
    • openal_context_destroy - コンテキストを削除する
    • openal_context_process - 指定したコンテキストを処理する
    • openal_context_suspend - 指定したコンテキストをサスペンドする
    • openal_device_close - OpenAL デバイスを閉じる
    • openal_device_open - OpenAL 音声レイヤを初期化する
    • openal_listener_get - リスナーのプロパティを取得する
    • openal_listener_set - リスナーのプロパティを設定する
    • openal_source_create - ソースリソースを生成する
    • openal_source_destroy - ソースリソースを削除する
    • openal_source_get - OpenAL ソースのプロパティを取得する
    • openal_source_pause - ソースを一時停止する
    • openal_source_play - ソースの再生を開始する
    • openal_source_rewind - ソースを巻き戻す
    • openal_source_set - ソースのプロパティを設定する
    • openal_source_stop - ソースの再生を停止する
    • openal_stream - ソースのストリーム再生を開始する
    • opendir - ディレクトリハンドルをオープンする
    • openlog - システムのロガーへの接続をオープンする
    • openssl_cipher_iv_length - 初期化ベクトル iv の長さを取得する
    • openssl_cipher_key_length - 暗号鍵の長さを取得する
    • openssl_cms_decrypt - CMS メッセージを復号化する
    • openssl_cms_encrypt - CMS メッセージを暗号化する
    • openssl_cms_read - CMS ファイルを、PEM証明書の配列にエクスポートする
    • openssl_cms_sign - ファイルに署名する
    • openssl_cms_verify - CMS の署名を検証する
    • openssl_csr_export - CSR を文字列としてエクスポートする
    • openssl_csr_export_to_file - CSR をファイルにエクスポートする
    • openssl_csr_get_public_key - CSR の公開鍵を返す
    • openssl_csr_get_subject - CSR の subject を返す
    • openssl_csr_new - CSR を作成する
    • openssl_csr_sign - CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する
    • openssl_decrypt - データを復号する
    • openssl_dh_compute_key - ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する
    • openssl_digest - ダイジェストを計算する
    • openssl_encrypt - データを暗号化する
    • openssl_error_string - OpenSSL エラーメッセージを返す
    • openssl_free_key - キーリソースを開放する
    • openssl_get_cert_locations - 有効な証明書の格納場所を検索する
    • openssl_get_cipher_methods - 利用可能な暗号メソッドを取得
    • openssl_get_curve_names - ECC で利用可能な楕円曲線の名前を取得する
    • openssl_get_md_methods - 利用可能なダイジェスト・メソッドを取得
    • openssl_get_privatekey - openssl_pkey_get_private のエイリアス
    • openssl_get_publickey - openssl_pkey_get_public のエイリアス
    • openssl_open - シール(暗号化)されたデータをオープン(復号)する
    • openssl_pbkdf2 - PKCS5 v2 の PBKDF2 文字列を生成する
    • openssl_pkcs7_decrypt - S/MIME 暗号化されたメッセージを復号する
    • openssl_pkcs7_encrypt - S/MIME メッセージを暗号化する
    • openssl_pkcs7_read - PKCS7 ファイルを PEM証明書 の配列にエクスポートする
    • openssl_pkcs7_sign - S/MIME メッセージに署名する
    • openssl_pkcs7_verify - S/MIME で署名されたメッセージの署名を検証する
    • openssl_pkcs12_export - PKCS#12 互換の証明書保存ファイルを変数にエクスポートする
    • openssl_pkcs12_export_to_file - PKCS#12 互換の証明書保存ファイルをエクスポートする
    • openssl_pkcs12_read - PKCS#12 認証ストアをパースして配列形式にする
    • openssl_pkey_derive - リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する
    • openssl_pkey_export - エクスポート可能な形式で、キーを文字列に取得する
    • openssl_pkey_export_to_file - エクスポート可能な形式で、キーをファイルに取得する
    • openssl_pkey_free - 秘密鍵を開放する
    • openssl_pkey_get_details - キーの詳細の配列を返す
    • openssl_pkey_get_private - 秘密鍵を取得する
    • openssl_pkey_get_public - 証明書から公開鍵を抽出し、使用できるようにする
    • openssl_pkey_new - 新規に秘密鍵を生成する
    • openssl_private_decrypt - 秘密鍵でデータを復号する
    • openssl_private_encrypt - 秘密鍵でデータを暗号化する
    • openssl_public_decrypt - 公開鍵でデータを復号する
    • openssl_public_encrypt - 公開鍵でデータを暗号化する
    • openssl_random_pseudo_bytes - 疑似ランダムなバイト文字列を生成する
    • openssl_seal - データをシール(暗号化)する
    • openssl_sign - 署名を生成する
    • openssl_spki_export - 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする
    • openssl_spki_export_challenge - 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする
    • openssl_spki_new - 署名された公開鍵とチャレンジを新規に作成する
    • openssl_spki_verify - 署名済みの公開鍵とチャレンジを検証する
    • openssl_verify - 署名を検証する
    • openssl_x509_checkpurpose - 証明書が特定の目的に使用可能かどうか確認する
    • openssl_x509_check_private_key - 秘密鍵が証明書に対応するかを確認する
    • openssl_x509_export - 証明書を文字列としてエクスポートする
    • openssl_x509_export_to_file - 証明書をファイルにエクスポートする
    • openssl_x509_fingerprint - 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する
    • openssl_x509_free - 証明書リソースを開放する
    • openssl_x509_parse - X509 証明書をパースし、配列として情報を返す
    • openssl_x509_read - X.509 証明書をパースし、オブジェクトを返す
    • openssl_x509_verify - x509証明書のデジタル署名を公開鍵で検証する
    • ord - 文字列の先頭バイトを、0 から 255 までの値に変換する
    • OuterIterator::getInnerIterator - 現在のエントリの内部イテレータを返す
    • output_add_rewrite_var - URL リライタの値を追加する
    • output_reset_rewrite_vars - URL リライタの値をリセットする
    • Override::__construct - 新しいOverrideアトリビュートのインスタンスを作成する
  • p
    • pack - データをバイナリ文字列にパックする
    • parallel\bootstrap - Bootstrapping
    • parallel\Channel::close - Closing
    • parallel\Channel::make - Access
    • parallel\Channel::open - Access
    • parallel\Channel::recv - Sharing
    • parallel\Channel::send - Sharing
    • parallel\Channel::__construct - Channel Construction
    • parallel\Events::addChannel - Targets
    • parallel\Events::addFuture - Targets
    • parallel\Events::poll - Polling
    • parallel\Events::remove - Targets
    • parallel\Events::setBlocking - Behaviour
    • parallel\Events::setInput - Input
    • parallel\Events::setTimeout - Behaviour
    • parallel\Events\Input::add - Inputs
    • parallel\Events\Input::clear - Inputs
    • parallel\Events\Input::remove - Inputs
    • parallel\Future::cancel - Cancellation
    • parallel\Future::cancelled - State Detection
    • parallel\Future::done - State Detection
    • parallel\Future::value - Resolution
    • parallel\run - Execution
    • parallel\Runtime::close - Runtime Graceful Join
    • parallel\Runtime::kill - Runtime Join
    • parallel\Runtime::run - Execution
    • parallel\Runtime::__construct - Runtime Construction
    • parallel\Sync::get - Access
    • parallel\Sync::notify - Synchronization
    • parallel\Sync::set - Access
    • parallel\Sync::wait - Synchronization
    • parallel\Sync::__construct - Construction
    • parallel\Sync::__invoke - Synchronization
    • ParentIterator::accept - 受け入れ可能かどうかを調べる
    • ParentIterator::getChildren - ParentIterator に含まれる内部イテレータの子を返す
    • ParentIterator::hasChildren - 内部イテレータの現在の要素が子を持つかどうかをチェックする
    • ParentIterator::next - イテレータを前に移動する
    • ParentIterator::rewind - イテレータを巻き戻す
    • ParentIterator::__construct - ParentIterator を作成する
    • Parle\Lexer::advance - Process next lexer rule
    • Parle\Lexer::build - Finalize the lexer rule set
    • Parle\Lexer::callout - Define token callback
    • Parle\Lexer::consume - Pass the data for processing
    • Parle\Lexer::dump - Dump the state machine
    • Parle\Lexer::getToken - Retrieve the current token
    • Parle\Lexer::insertMacro - Insert regex macro
    • Parle\Lexer::push - Add a lexer rule
    • Parle\Lexer::reset - Reset lexer
    • Parle\Parser::advance - Process next parser rule
    • Parle\Parser::build - Finalize the grammar rules
    • Parle\Parser::consume - Consume the data for processing
    • Parle\Parser::dump - Dump the grammar
    • Parle\Parser::errorInfo - Retrieve the error information
    • Parle\Parser::left - Declare a token with left-associativity
    • Parle\Parser::nonassoc - Declare a token with no associativity
    • Parle\Parser::precedence - Declare a precedence rule
    • Parle\Parser::push - Add a grammar rule
    • Parle\Parser::reset - Reset parser state
    • Parle\Parser::right - Declare a token with right-associativity
    • Parle\Parser::sigil - Retrieve a matching part of a rule
    • Parle\Parser::sigilCount - Number of elements in matched rule
    • Parle\Parser::sigilName - Retrieve a rule or token name
    • Parle\Parser::token - Declare a token
    • Parle\Parser::tokenId - Get token id
    • Parle\Parser::trace - Trace the parser operation
    • Parle\Parser::validate - Validate input
    • Parle\RLexer::advance - Process next lexer rule
    • Parle\RLexer::build - Finalize the lexer rule set
    • Parle\RLexer::callout - Define token callback
    • Parle\RLexer::consume - Pass the data for processing
    • Parle\RLexer::dump - Dump the state machine
    • Parle\RLexer::getToken - Retrieve the current token
    • Parle\RLexer::insertMacro - Insert regex macro
    • Parle\RLexer::push - Add a lexer rule
    • Parle\RLexer::pushState - Push a new start state
    • Parle\RLexer::reset - Reset lexer
    • Parle\RParser::advance - Process next parser rule
    • Parle\RParser::build - Finalize the grammar rules
    • Parle\RParser::consume - Consume the data for processing
    • Parle\RParser::dump - Dump the grammar
    • Parle\RParser::errorInfo - Retrieve the error information
    • Parle\RParser::left - Declare a token with left-associativity
    • Parle\RParser::nonassoc - Declare a token with no associativity
    • Parle\RParser::precedence - Declare a precedence rule
    • Parle\RParser::push - Add a grammar rule
    • Parle\RParser::reset - Reset parser state
    • Parle\RParser::right - Declare a token with right-associativity
    • Parle\RParser::sigil - Retrieve a matching part of a rule
    • Parle\RParser::sigilCount - Number of elements in matched rule
    • Parle\RParser::sigilName - Retrieve a rule or token name
    • Parle\RParser::token - Declare a token
    • Parle\RParser::tokenId - Get token id
    • Parle\RParser::trace - Trace the parser operation
    • Parle\RParser::validate - Validate input
    • Parle\Stack::pop - Pop an item from the stack
    • Parle\Stack::push - Push an item into the stack
    • parse_ini_file - 設定ファイルをパースする
    • parse_ini_string - 設定文字列をパースする
    • parse_str - 文字列を処理し、変数に代入する
    • parse_url - URL を解釈し、その構成要素を返す
    • passthru - 外部プログラムを実行し、未整形の出力を表示する
    • password_algos - 利用可能なパスワードハッシュアルゴリズムのIDを取得する
    • password_get_info - 指定したハッシュに関する情報を返す
    • password_hash - パスワードハッシュを作る
    • password_needs_rehash - 指定したハッシュがオプションにマッチするかどうかを調べる
    • password_verify - パスワードがハッシュにマッチするかどうかを調べる
    • pathinfo - ファイルパスに関する情報を返す
    • pclose - プロセスのファイルポインタをクローズする
    • pcntl_alarm - シグナルを送信するアラームを設定する
    • pcntl_async_signals - 非同期のシグナルハンドリングを有効/無効にするか、古い設定を返す
    • pcntl_errno - pcntl_get_last_error のエイリアス
    • pcntl_exec - 現在のプロセス空間で指定したプログラムを実行する
    • pcntl_fork - 現在実行中のプロセスをフォークする
    • pcntl_getpriority - プロセスの優先度を取得する
    • pcntl_get_last_error - 直近の pcntl 関数が失敗したときのエラー番号を取得する
    • pcntl_rfork - プロセスのリソースを管理する
    • pcntl_setpriority - プロセスの優先度を変更する
    • pcntl_signal - シグナルハンドラを設定する
    • pcntl_signal_dispatch - ペンディングシグナル用のハンドラをコールする
    • pcntl_signal_get_handler - 指定されたシグナルの現在のハンドラを取得する
    • pcntl_sigprocmask - ブロックされたシグナルを設定あるいは取得する
    • pcntl_sigtimedwait - タイムアウトつきでシグナルを待つ
    • pcntl_sigwaitinfo - シグナルを待つ
    • pcntl_strerror - 指定した errno に対応するシステムのエラーメッセージを取得する
    • pcntl_unshare - プロセスの実行コンテキストの一部を切り離す
    • pcntl_wait - 待つかフォークした子プロセスのステータスを返す
    • pcntl_waitpid - 待つかフォークした子プロセスのステータスを返す
    • pcntl_wexitstatus - 終了した子プロセスのリターンコードを返す
    • pcntl_wifexited - ステータスコードが正常終了を表しているかどうかを調べる
    • pcntl_wifsignaled - ステータスコードがシグナルによる終了を表しているかどうかを調べる
    • pcntl_wifstopped - 子プロセスが現在停止しているかどうかを調べる
    • pcntl_wstopsig - 子プロセスを停止させたシグナルを返す
    • pcntl_wtermsig - 子プロセスを終了させたシグナルを返す
    • PDO::beginTransaction - トランザクションを開始する
    • PDO::commit - トランザクションをコミットする
    • PDO::cubrid_schema - 指定したスキーマ情報を取得する
    • PDO::errorCode - データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する
    • PDO::errorInfo - データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する
    • PDO::exec - SQL ステートメントを実行し、作用した行数を返す
    • PDO::getAttribute - データベース接続の属性を取得する
    • PDO::getAvailableDrivers - 利用可能な PDO ドライバの配列を返す
    • PDO::inTransaction - トランザクション内かどうかを調べる
    • PDO::lastInsertId - 最後に挿入された行の ID あるいはシーケンスの値を返す
    • PDO::pgsqlCopyFromArray - PHP の配列から、データをテーブルにコピーする
    • PDO::pgsqlCopyFromFile - ファイルからデータをテーブルにコピーする
    • PDO::pgsqlCopyToArray - データベーステーブルからのデータをPHPの配列にコピーする
    • PDO::pgsqlCopyToFile - テーブルからのデータをファイルにコピーする
    • PDO::pgsqlGetNotify - 非同期に通知を取得する
    • PDO::pgsqlGetPid - サーバーのPIDを取得する
    • PDO::pgsqlLOBCreate - 新しいラージオブジェクトを作成する
    • PDO::pgsqlLOBOpen - 既存のラージオブジェクトのストリームをオープンする
    • PDO::pgsqlLOBUnlink - ラージオブジェクトを削除する
    • PDO::prepare - 文を実行する準備を行い、文オブジェクトを返す
    • PDO::query - プレースホルダを指定せずに、SQL ステートメントを準備して実行する
    • PDO::quote - クエリ用の文字列をクオートする
    • PDO::rollBack - トランザクションをロールバックする
    • PDO::setAttribute - 属性を設定する
    • PDO::sqliteCreateAggregate - SQL 文で使用する集約ユーザー定義関数 (UDF) を登録する
    • PDO::sqliteCreateCollation - SQL文で collate 関数として使うユーザー定義関数を登録する
    • PDO::sqliteCreateFunction - SQL 文で使用するユーザー定義関数 (UDF) を登録する
    • PDO::__construct - データベースへの接続を表す PDO インスタンスを生成する
    • PDOStatement::bindColumn - カラムを PHP 変数にバインドする
    • PDOStatement::bindParam - 指定された変数名にパラメータをバインドする
    • PDOStatement::bindValue - 値をパラメータにバインドする
    • PDOStatement::closeCursor - カーソルを閉じてステートメントを再実行できるようにする
    • PDOStatement::columnCount - 結果セット中のカラム数を返す
    • PDOStatement::debugDumpParams - SQL プリペアドコマンドを出力する
    • PDOStatement::errorCode - 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する
    • PDOStatement::errorInfo - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する
    • PDOStatement::execute - プリペアドステートメントを実行する
    • PDOStatement::fetch - 結果セットから次の行を取得する
    • PDOStatement::fetchAll - 結果セットから、残っている行を取得する
    • PDOStatement::fetchColumn - 結果セットの次行から単一カラムを返す
    • PDOStatement::fetchObject - 次の行を取得し、それをオブジェクトとして返す
    • PDOStatement::getAttribute - 文の属性を取得する
    • PDOStatement::getColumnMeta - 結果セットのカラムに対するメタデータを返す
    • PDOStatement::getIterator - 結果セットのイテレータを取得する
    • PDOStatement::nextRowset - 複数の行セットを返す文ハンドラで次の行セットに移動する
    • PDOStatement::rowCount - 直近の SQL ステートメントによって作用した行数を返す
    • PDOStatement::setAttribute - 文の属性を設定する
    • PDOStatement::setFetchMode - この文に対するデフォルトのフェッチモードを設定する
    • PDO_CUBRID DSN - CUBRID データベースへの接続
    • PDO_DBLIB DSN - Microsoft SQL Server および Sybase データベースに接続する
    • PDO_FIREBIRD DSN - Firebird データベースに接続する
    • PDO_IBM DSN - IBM データベースへの接続
    • PDO_INFORMIX DSN - Informix データベースに接続する
    • PDO_MYSQL DSN - MySQL データベースに接続する
    • PDO_OCI DSN - Oracle データベースに接続する
    • PDO_ODBC DSN - ODBC あるいは DB2 データベースに接続する
    • PDO_PGSQL DSN - PostgreSQL データベースに接続する
    • PDO_SQLITE DSN - SQLite データベースに接続する
    • PDO_SQLSRV DSN - MS SQL Server および SQL Azure データベースに接続する
    • pfsockopen - 持続的な Internet または Unix ドメインソケット接続をオープンする
    • pg_affected_rows - 変更されたレコード(タプル)の数を返す
    • pg_cancel_query - 非同期クエリを取り消す
    • pg_client_encoding - クライアントのエンコーディングを取得する
    • pg_close - PostgreSQL 接続をクローズする
    • pg_connect - PostgreSQL 接続をオープンする
    • pg_connection_busy - 接続がビジーかどうか調べる
    • pg_connection_reset - 接続をリセット(再接続)する
    • pg_connection_status - 接続ステータスを取得する
    • pg_connect_poll - 進行中の非同期接続のステータスをポーリングする
    • pg_consume_input - 接続の入力を読み取る
    • pg_convert - 連想配列の値を、SQL 文として実行可能な形式に変換する
    • pg_copy_from - 配列からテーブルに挿入する
    • pg_copy_to - 配列にテーブルをコピーする
    • pg_dbname - データベース名を取得する
    • pg_delete - レコードを削除する
    • pg_end_copy - PostgreSQL バックエンドと同期する
    • pg_escape_bytea - bytea フィールドに挿入するために文字列をエスケープする
    • pg_escape_identifier - テキスト型フィールドに挿入するために、識別子をエスケープする
    • pg_escape_literal - テキスト型フィールドに挿入するために、リテラルをエスケープする
    • pg_escape_string - クエリに使う文字列をエスケープする
    • pg_execute - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
    • pg_fetch_all - 取得されたすべての行を配列として取得する
    • pg_fetch_all_columns - 指定したカラムの全ての行を配列として取得する
    • pg_fetch_array - 行を配列として取得する
    • pg_fetch_assoc - 行を連想配列として取得する
    • pg_fetch_object - 行をオブジェクトとして得る
    • pg_fetch_result - 結果インスタンスから値を返す
    • pg_fetch_row - 数値添字の配列として行を得る
    • pg_field_is_null - フィールドが SQL の NULL かどうか調べる
    • pg_field_name - フィールドの名前を返す
    • pg_field_num - 指定されたフィールドのフィールド番号を返す
    • pg_field_prtlen - 表示される長さを返す
    • pg_field_size - 指定したフィールドの内部記憶領域におけるサイズを返す
    • pg_field_table - tables フィールドの名前あるいは oid を返す
    • pg_field_type - フィールド番号に対応する型名を返す
    • pg_field_type_oid - フィールド番号に対応する型 ID（OID）を返す
    • pg_flush - 送信を待っているクエリデータをフラッシュする
    • pg_free_result - クエリ結果のメモリを開放する
    • pg_get_notify - SQL NOTIFY メッセージを取得する
    • pg_get_pid - バックエンドのプロセス ID を得る
    • pg_get_result - 非同期クエリの結果を取得する
    • pg_host - 接続に関連するホスト名を返す
    • pg_insert - テーブルに配列を挿入する
    • pg_last_error - 特定の接続から直近のエラーメッセージ文字列を取得する
    • pg_last_notice - PostgreSQL サーバーからの直近の通知メッセージを返す
    • pg_last_oid - 直近の行のオブジェクト ID を返す
    • pg_lo_close - ラージオブジェクトをクローズする
    • pg_lo_create - ラージオブジェクトを生成する
    • pg_lo_export - ラージオブジェクトをファイルにエクスポートする
    • pg_lo_import - ファイルからラージオブジェクトをインポートする
    • pg_lo_open - ラージオブジェクトをオープンする
    • pg_lo_read - ラージオブジェクトを読み込む
    • pg_lo_read_all - ラージオブジェクト全体を読み込みブラウザに直接送信する
    • pg_lo_seek - ラージオブジェクトの位置をシークする
    • pg_lo_tell - ラージオブジェクトのカレントのシーク位置を返す
    • pg_lo_truncate - ラージオブジェクトを切り詰める
    • pg_lo_unlink - ラージオブジェクトを削除する
    • pg_lo_write - ラージオブジェクトに書き込む
    • pg_meta_data - テーブルからメタデータを取得する
    • pg_num_fields - フィールド数を返す
    • pg_num_rows - 行数を返す
    • pg_options - 接続に関連するオプションを取得する
    • pg_parameter_status - サーバーのパラメータ設定を検索する
    • pg_pconnect - 持続的な PostgreSQL 接続をオープンする
    • pg_ping - データベース接続を調べる
    • pg_port - 接続に関連するポート番号を返す
    • pg_prepare - 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その完了を待つ
    • pg_put_line - NULL で終わる文字列を PostgreSQL バックエンドに送信する
    • pg_query - クエリを実行する
    • pg_query_params - SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
    • pg_result_error - 結果に関連するエラーメッセージを取得する
    • pg_result_error_field - エラー報告の各フィールドを返す
    • pg_result_seek - 結果インスタンスの内部行オフセットを設定する
    • pg_result_status - クエリ結果のステータスを取得する
    • pg_select - レコードを選択する
    • pg_send_execute - 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
    • pg_send_prepare - 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
    • pg_send_query - 非同期クエリを送信する
    • pg_send_query_params - コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
    • pg_set_client_encoding - クライアントのエンコーディングを設定する
    • pg_set_error_context_visibility - pg_last_error が返すコンテクストのエラーメッセージのアクセス権を設定する
    • pg_set_error_verbosity - pg_last_error および pg_result_error が返すメッセージの詳細度を指定する
    • pg_socket - PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する
    • pg_trace - PostgreSQL 接続のトレースを有効にする
    • pg_transaction_status - サーバー上で実行中のトランザクションの状態を返す
    • pg_tty - 接続に関する TTY 名を返す
    • pg_unescape_bytea - bytea 型のバイナリをアンエスケープする
    • pg_untrace - PostgreSQL 接続のトレースを無効にする
    • pg_update - テーブルを更新する
    • pg_version - クライアント・プロトコル・サーバーのバージョンを配列で返す
    • 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::compressFiles - 現在の 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::delete - phar アーカイブ内のファイルを削除する
    • Phar::delMetadata - phar のグローバルメタデータを削除する
    • Phar::extractTo - phar アーカイブの内容をディレクトリに展開する
    • Phar::getAlias - Phar のエイリアスを取得する
    • Phar::getMetadata - phar アーカイブのメタデータを返す
    • Phar::getModified - phar が変更されているかどうかを返す
    • Phar::getPath - 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::unlinkArchive - phar アーカイブをディスクとメモリから完全に削除する
    • Phar::webPhar - ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する
    • Phar::__construct - Phar アーカイブオブジェクトを作成する
    • Phar::__destruct - アクティブな Phar オブジェクトを破棄する
    • PharData::addEmptyDir - 空のディレクトリを tar/zip アーカイブに追加する
    • PharData::addFile - ファイルシステム上のファイルを tar/zip アーカイブに追加する
    • PharData::addFromString - 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する
    • PharData::buildFromDirectory - ディレクトリ内のファイルから tar/zip アーカイブを作成する
    • PharData::buildFromIterator - イテレータから tar あるいは zip アーカイブを作成する
    • PharData::compress - tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
    • PharData::compressFiles - 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する
    • PharData::convertToData - phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
    • PharData::convertToExecutable - 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する
    • PharData::copy - phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
    • PharData::decompress - Phar アーカイブ全体の圧縮を解除する
    • PharData::decompressFiles - 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する
    • PharData::delete - tar/zip アーカイブ内のファイルを削除する
    • PharData::delMetadata - zip アーカイブのグローバルメタデータを削除する
    • PharData::extractTo - tar/zip アーカイブの内容をディレクトリに展開する
    • PharData::isWritable - tar/zip アーカイブが変更可能な場合に true を返す
    • PharData::offsetSet - tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
    • PharData::offsetUnset - ファイルを tar/zip アーカイブから削除する
    • PharData::setAlias - ダミー関数 (Phar::setAlias は PharData では使用不能)
    • PharData::setDefaultStub - ダミー関数 (Phar::setDefaultStub は PharData では無効)
    • PharData::setMetadata - phar アーカイブのメタデータを設定する
    • PharData::setSignatureAlgorithm - phar のシグネチャのアルゴリズムを設定する
    • PharData::setStub - ダミー関数 (Phar::setStub は PharData では使用不能)
    • PharData::__construct - 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する
    • PharData::__destruct - 実行不能な tar や zip アーカイブオブジェクトを破棄する
    • PharFileInfo::chmod - ファイル固有のパーミッションビットを設定する
    • PharFileInfo::compress - 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する
    • PharFileInfo::decompress - phar 内の現在の Phar エントリの圧縮を解除する
    • PharFileInfo::delMetadata - エントリのメタデータを削除する
    • PharFileInfo::getCompressedSize - Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す
    • PharFileInfo::getContent - エントリの完全なファイルの内容を取得する
    • PharFileInfo::getCRC32 - CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする
    • PharFileInfo::getMetadata - ファイルとともに保存されている、ファイル固有のメタデータを返す
    • PharFileInfo::getPharFlags - Phar ファイルエントリのフラグを返す
    • PharFileInfo::hasMetadata - エントリのメタデータを返す
    • PharFileInfo::isCompressed - エントリが圧縮されているかどうかを調べる
    • PharFileInfo::isCRCChecked - ファイルエントリの CRC が検証されているかどうかを調べる
    • PharFileInfo::setMetadata - ファイルとともに保存する、ファイル固有のメタデータを設定する
    • PharFileInfo::__construct - Phar エントリオブジェクトを作成する
    • PharFileInfo::__destruct - Phar エントリオブジェクトを破棄する
    • phpcredits - PHP に関するクレジットを出力する
    • phpdbg_break_file - ファイルの行にブレークポイントを挿入する
    • phpdbg_break_function - 関数のエントリにブレークポイントを挿入する
    • phpdbg_break_method - メソッドのエントリにブレークポイントを挿入する
    • phpdbg_break_next - 次のオペコードにブレークポイントを挿入します
    • phpdbg_clear - 全てのブレークポイントをクリアする
    • phpdbg_color - 特定の要素に色を設定する
    • phpdbg_end_oplog - 説明
    • phpdbg_exec - 実行コンテクストの設定を試みる
    • phpdbg_get_executable - 説明
    • phpdbg_prompt - コマンドのプロンプトを設定する
    • phpdbg_start_oplog - 説明
    • phpinfo - PHP の設定情報を出力する
    • PhpToken::getTokenName - トークンの名前を返す
    • PhpToken::is - 指定された種類のトークンかを調べる
    • PhpToken::isIgnorable - トークンがPHPパーサから無視されるかを調べる
    • PhpToken::tokenize - ソースコードを PhpToken オブジェクトで表現されたトークンに分割する
    • PhpToken::__construct - 新しい PhpToken オブジェクトを返す
    • PhpToken::__toString - トークンの文字列表現を返す
    • phpversion - 現在の PHP バージョンを取得する
    • php_ini_loaded_file - 読み込まれた php.ini ファイルのパスを取得する
    • php_ini_scanned_files - 追加の ini ディレクトリにある .ini ファイルのリストを取得する
    • php_sapi_name - ウェブサーバーと PHP の間のインターフェイスの型を返す
    • php_strip_whitespace - コメントと空白文字を取り除いたソースを返す
    • php_uname - PHP が稼動しているオペレーティングシステムに関する情報を返す
    • php_user_filter::filter - フィルタを適用するときにコールされる
    • php_user_filter::onClose - フィルタを閉じるときにコールされる
    • php_user_filter::onCreate - フィルタを作成するときにコールされる
    • pi - 円周率の値を得る
    • png2wbmp - PNG画像をWBMP画像に変換する
    • Pool::collect - Collect references to completed tasks
    • Pool::resize - Resize the Pool
    • Pool::shutdown - Shutdown all workers
    • Pool::submit - Submits an object for execution
    • Pool::submitTo - Submits a task to a specific worker for execution
    • Pool::__construct - Creates a new Pool of Workers
    • popen - プロセスへのファイルポインタをオープンする
    • pos - current のエイリアス
    • posix_access - ファイルのアクセス権限を判断する
    • posix_ctermid - 制御する端末のパス名を得る
    • posix_eaccess - ファイルがアクセスできるかを調べる
    • posix_errno - posix_get_last_error のエイリアス
    • posix_fpathconf - 設定可能なリミットの値を返す
    • posix_getcwd - 現在のディレクトリのパス名
    • posix_getegid - 現在のプロセスの有効なグループ ID を返す
    • posix_geteuid - 現在のプロセスの有効なユーザー ID を返す
    • posix_getgid - 現在のプロセスの実際のグループ ID を返す
    • posix_getgrgid - 指定したグループ ID を有するグループに関する情報を返す
    • posix_getgrnam - 指定した名前のグループに関する情報を返す
    • posix_getgroups - 現在のプロセスのグループセットを返す
    • posix_getlogin - ログイン名を返す
    • posix_getpgid - ジョブ制御のプロセスグループ ID を得る
    • posix_getpgrp - 現在のプロセスのグループ ID を返す
    • posix_getpid - 現在のプロセス ID を返す
    • posix_getppid - 親プロセスの ID を返す
    • posix_getpwnam - 指定した名前のユーザーに関する情報を返す
    • posix_getpwuid - 指定 ID のユーザーに関する情報を返す
    • posix_getrlimit - システムリソース制限に関する情報を返す
    • posix_getsid - プロセスの現在の sid を得る
    • posix_getuid - 現在のプロセスの実際のユーザー ID を返す
    • posix_get_last_error - 直近で失敗した posix 関数が設定したエラー番号を取得する
    • posix_initgroups - グループアクセスリストを求める
    • posix_isatty - ファイル記述子が対話型端末であるかどうかを定義する
    • posix_kill - プロセスにシグナルを送信する
    • posix_mkfifo - fifo スペシャルファイル(名前付きパイプ)を作成する
    • posix_mknod - スペシャルファイルあるいは通常のファイルを作成する (POSIX.1)
    • posix_pathconf - 設定可能なリミットの値を返す
    • posix_setegid - 現在のプロセスの実効 GID を設定する
    • posix_seteuid - 現在のプロセスの実効 UID を設定する
    • posix_setgid - 現在のプロセスの GID を設定する
    • posix_setpgid - ジョブ制御のプロセスグループ ID を設定する
    • posix_setrlimit - システムリソース制限を設定
    • posix_setsid - 現在のプロセスをセッションリーダーにする
    • posix_setuid - 現在のプロセスの UID を設定する
    • posix_strerror - 指定したエラー番号に対応するシステムのエラーメッセージを取得する
    • posix_sysconf - システムの実行時情報を返す
    • posix_times - プロセス時間を得る
    • posix_ttyname - 端末のデバイス名を調べる
    • posix_uname - システム名を得る
    • pow - 指数表現
    • preg_filter - 正規表現による検索と置換を行う
    • preg_grep - パターンにマッチする配列の要素を返す
    • preg_last_error - 直近の PCRE 正規表現処理のエラーコードを返す
    • preg_last_error_msg - 最後に実行した PCRE 正規表現に関するエラーメッセージを返す
    • preg_match - 正規表現によるマッチングを行う
    • preg_match_all - 繰り返し正規表現検索を行う
    • preg_quote - 正規表現文字をクオートする
    • preg_replace - 正規表現検索および置換を行う
    • preg_replace_callback - 正規表現検索を行い、コールバック関数を使用して置換を行う
    • preg_replace_callback_array - 正規表現検索を行い、コールバック関数を使用して置換を行う
    • preg_split - 正規表現で文字列を分割する
    • prev - 内部の配列ポインタをひとつ前に戻す
    • print - 文字列を出力する
    • printf - フォーマット済みの文字列を出力する
    • print_r - 指定した変数に関する情報を解りやすく出力する
    • proc_close - proc_open で開かれたプロセスを閉じ、 そのプロセスの終了コードを返す
    • proc_get_status - proc_open で開かれたプロセスに関する情報を取得する
    • proc_nice - 現在のプロセスの優先度を変更する
    • proc_open - コマンドを実行し、入出力用にファイルポインタを開く
    • proc_terminate - proc_open でオープンされたプロセスを強制終了する
    • property_exists - オブジェクトもしくはクラスにプロパティが存在するかどうかを調べる
    • pspell_add_to_personal - ユーザーの単語リストに単語を追加する
    • pspell_add_to_session - 現在のセッションの単語リストに単語を追加する
    • pspell_check - 単語をチェックする
    • pspell_clear_session - 現在のセッションをクリアする
    • pspell_config_create - 辞書をオープンする際に使用する設定を作成する
    • pspell_config_data_dir - 言語のデータファイルの場所
    • pspell_config_dict_dir - メイン単語リストの場所
    • pspell_config_ignore - 長さが N 文字未満の単語を無視する
    • pspell_config_mode - 返される提案の数のモードを変更する
    • pspell_config_personal - 個人の単語リストを保持するファイルを設定する
    • pspell_config_repl - 置換候補を保持するファイルを設定する
    • pspell_config_runtogether - 複合語を有効な単語の組み合わせとして考慮する
    • pspell_config_save_repl - 単語リストと共に置換リストを保存するかどうかを定義する
    • pspell_new - 新規辞書をロードする
    • pspell_new_config - 指定した設定に基づき新規辞書をロードする
    • pspell_new_personal - 個人の単語リストを有する新規辞書をロードする
    • pspell_save_wordlist - 個人の単語リストをファイルに保存する
    • pspell_store_replacement - 単語を置換する組を保存する
    • pspell_suggest - 単語のスペルについて修正候補を示す
    • ps_add_bookmark - 現在のページにブックマークを追加する
    • ps_add_launchlink - ファイルを実行するためのリンクを追加する
    • ps_add_locallink - 同一ドキュメント内のページへのリンクを追加する
    • ps_add_note - 現在のページに注釈を追加する
    • ps_add_pdflink - 別の PDF ドキュメントのページへのリンクを追加する
    • ps_add_weblink - Web 上の場所へのリンクを追加する
    • ps_arc - 反時計回りに円弧を描く
    • ps_arcn - 時計回りに円弧を描く
    • ps_begin_page - 新しいページを開始する
    • ps_begin_pattern - 新しいパターンを開始する
    • ps_begin_template - 新しいテンプレートを開始する
    • ps_circle - 円を描く
    • ps_clip - 現在のパスを描画範囲として指定する
    • ps_close - PostScript ドキュメントを閉じる
    • ps_closepath - パスを閉じる
    • ps_closepath_stroke - パスを閉じ、描画する
    • ps_close_image - 画像を閉じ、メモリを開放する
    • ps_continue_text - 次の行にテキストを続ける
    • ps_curveto - 曲線を描く
    • ps_delete - PostScript ドキュメントの全リソースを削除する
    • ps_end_page - ページを終了する
    • ps_end_pattern - パターンを終了する
    • ps_end_template - テンプレートを終了する
    • ps_fill - 現在のパスを塗りつぶす
    • ps_fill_stroke - 現在のパスを塗りつぶし、線を引く
    • ps_findfont - フォントを読み込む
    • ps_get_buffer - 生成された PS データを含むバッファの内容を取得する
    • ps_get_parameter - パラメータを取得する
    • ps_get_value - 値を取得する
    • ps_hyphenate - 単語をハイフネーションする
    • ps_include_file - 外部ファイルを生の PostScript コードとして読み込む
    • ps_lineto - 直線を描く
    • ps_makespotcolor - スポット色を作成する
    • ps_moveto - 現在位置を設定する
    • ps_new - 新しい PostScript ドキュメントオブジェクトを作成する
    • ps_open_file - 出力用のファイルを開く
    • ps_open_image - 後で配置するために画像を読み込む
    • ps_open_image_file - ファイルから画像を開く
    • ps_open_memory_image - GD 画像を受け取り、PS ドキュメントにはめ込む画像を返す
    • ps_place_image - 画像をページに配置する
    • ps_rect - 矩形を描く
    • ps_restore - 以前に保存されたコンテキストを復元する
    • ps_rotate - 回転の程度を設定する
    • ps_save - 現在のコンテキストを保存する
    • ps_scale - 縮尺を設定する
    • ps_setcolor - 色を設定する
    • ps_setdash - 破線の形状を設定する
    • ps_setflat - 平面度を設定する
    • ps_setfont - 以降の出力で用いるフォントを設定する
    • ps_setgray - グレー値を設定する
    • ps_setlinecap - 線端の形状を設定する
    • ps_setlinejoin - 線の連結方法を設定する
    • ps_setlinewidth - 線幅を設定する
    • ps_setmiterlimit - miter limit 値を設定する
    • ps_setoverprintmode - overprint モードを設定する
    • ps_setpolydash - 破線の形状を設定する
    • ps_set_border_color - 注記の枠線の色を設定する
    • ps_set_border_dash - 注記の枠線の、破線の状態を設定する
    • ps_set_border_style - 注記の枠線の形式を設定する
    • ps_set_info - ドキュメントの情報を設定する
    • ps_set_parameter - パラメータを設定する
    • ps_set_text_pos - テキストの出力位置を設定する
    • ps_set_value - 値を設定する
    • ps_shading - 以降の出力で用いるシェーディングを作成する
    • ps_shading_pattern - シェーディング用のパターンを作成する
    • ps_shfill - 範囲をシェーディングで塗りつぶす
    • ps_show - テキストを出力する
    • ps_show2 - テキストを現在の位置に出力する
    • ps_show_boxed - テキストをボックス内に出力する
    • ps_show_xy - 指定された位置にテキストを出力する
    • ps_show_xy2 - テキストを指定した位置に出力する
    • ps_stringwidth - 文字列の幅を取得する
    • ps_string_geometry - 文字列のジオメトリを取得する
    • ps_stroke - 現在のパスを描画する
    • ps_symbol - グリフを出力する
    • ps_symbol_name - グリフ名を取得する
    • ps_symbol_width - グリフの幅を取得する
    • ps_translate - 座標変換を設定する
    • putenv - 環境変数の値を設定する
  • q
    • QuickHashIntHash::add - This method adds a new entry to the hash
    • QuickHashIntHash::delete - This method deletes an entry from the hash
    • QuickHashIntHash::exists - This method checks whether a key is part of the hash
    • QuickHashIntHash::get - This method retrieves a value from the hash by its key
    • QuickHashIntHash::getSize - Returns the number of elements in the hash
    • QuickHashIntHash::loadFromFile - This factory method creates a hash from a file
    • QuickHashIntHash::loadFromString - This factory method creates a hash from a string
    • QuickHashIntHash::saveToFile - This method stores an in-memory hash to disk
    • QuickHashIntHash::saveToString - This method returns a serialized version of the hash
    • QuickHashIntHash::set - This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
    • QuickHashIntHash::update - This method updates an entry in the hash with a new value
    • QuickHashIntHash::__construct - Creates a new QuickHashIntHash object
    • QuickHashIntSet::add - This method adds a new entry to the set
    • QuickHashIntSet::delete - This method deletes an entry from the set
    • QuickHashIntSet::exists - This method checks whether a key is part of the set
    • QuickHashIntSet::getSize - Returns the number of elements in the set
    • QuickHashIntSet::loadFromFile - This factory method creates a set from a file
    • QuickHashIntSet::loadFromString - This factory method creates a set from a string
    • QuickHashIntSet::saveToFile - This method stores an in-memory set to disk
    • QuickHashIntSet::saveToString - This method returns a serialized version of the set
    • QuickHashIntSet::__construct - Creates a new QuickHashIntSet object
    • QuickHashIntStringHash::add - This method adds a new entry to the hash
    • QuickHashIntStringHash::delete - This method deletes an entry from the hash
    • QuickHashIntStringHash::exists - This method checks whether a key is part of the hash
    • QuickHashIntStringHash::get - This method retrieves a value from the hash by its key
    • QuickHashIntStringHash::getSize - Returns the number of elements in the hash
    • QuickHashIntStringHash::loadFromFile - This factory method creates a hash from a file
    • QuickHashIntStringHash::loadFromString - This factory method creates a hash from a string
    • QuickHashIntStringHash::saveToFile - This method stores an in-memory hash to disk
    • QuickHashIntStringHash::saveToString - This method returns a serialized version of the hash
    • QuickHashIntStringHash::set - This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
    • QuickHashIntStringHash::update - This method updates an entry in the hash with a new value
    • QuickHashIntStringHash::__construct - Creates a new QuickHashIntStringHash object
    • QuickHashStringIntHash::add - This method adds a new entry to the hash
    • QuickHashStringIntHash::delete - This method deletes an entry from the hash
    • QuickHashStringIntHash::exists - This method checks whether a key is part of the hash
    • QuickHashStringIntHash::get - This method retrieves a value from the hash by its key
    • QuickHashStringIntHash::getSize - Returns the number of elements in the hash
    • QuickHashStringIntHash::loadFromFile - This factory method creates a hash from a file
    • QuickHashStringIntHash::loadFromString - This factory method creates a hash from a string
    • QuickHashStringIntHash::saveToFile - This method stores an in-memory hash to disk
    • QuickHashStringIntHash::saveToString - This method returns a serialized version of the hash
    • QuickHashStringIntHash::set - This method updates an entry in the hash with a new value, or adds a new one if the entry doesn't exist
    • QuickHashStringIntHash::update - This method updates an entry in the hash with a new value
    • QuickHashStringIntHash::__construct - Creates a new QuickHashStringIntHash object
    • quoted_printable_decode - quoted-printable 文字列を 8 ビット文字列に変換する
    • quoted_printable_encode - 8 ビット文字列を quoted-printable 文字列に変換する
    • quotemeta - メタ文字をクォートする
  • r
    • rad2deg - ラジアン単位の数値を度単位に変換する
    • radius_acct_open - 課金用の Radius ハンドルを作成する
    • radius_add_server - サーバーを追加する
    • radius_auth_open - 認証用の Radius ハンドルを作成する
    • radius_close - すべてのリソースを開放する
    • radius_config - 指定した設定ファイルをライブラリに読み込ませる
    • radius_create_request - 課金あるいは認証のリクエストを作成する
    • radius_cvt_addr - 生データを IP アドレスに変換する
    • radius_cvt_int - 生データを整数に変換する
    • radius_cvt_string - 生データを文字列に変換する
    • radius_demangle - データを復元する
    • radius_demangle_mppe_key - 変形されたデータから mppe キーを得る
    • radius_get_attr - 属性を取得する
    • radius_get_tagged_attr_data - Extracts the data from a tagged attribute
    • radius_get_tagged_attr_tag - Extracts the tag from a tagged attribute
    • radius_get_vendor_attr - ベンダ固有の属性を取得する
    • radius_put_addr - IP アドレス属性を設定する
    • radius_put_attr - バイナリ属性を設定する
    • radius_put_int - 整数属性を設定する
    • radius_put_string - 文字列属性を設定する
    • radius_put_vendor_addr - ベンダー固有の IP アドレス属性を設定する
    • radius_put_vendor_attr - ベンダー固有のバイナリ属性を設定する
    • radius_put_vendor_int - ベンダー固有の整数属性を設定する
    • radius_put_vendor_string - ベンダー固有の文字列属性を設定する
    • radius_request_authenticator - リクエスト認証子を返す
    • radius_salt_encrypt_attr - Salt-encrypts a value
    • radius_send_request - リクエストを送信し、応答を待つ
    • radius_server_secret - 共有秘密鍵を返す
    • radius_strerror - エラーメッセージを返す
    • rand - 乱数を生成する
    • Random\Engine::generate - ランダムな値を生成する
    • Random\Engine\Mt19937::generate - 32ビットのランダムな値を生成する
    • Random\Engine\Mt19937::__construct - 新しい Mt19937 エンジンを作成する
    • Random\Engine\Mt19937::__debugInfo - エンジンの内部的なステートを返す
    • Random\Engine\Mt19937::__serialize - Mt19937 オブジェクトをシリアライズする
    • Random\Engine\Mt19937::__unserialize - 指定した data を Mt19937 オブジェクトに復元する
    • Random\Engine\PcgOneseq128XslRr64::generate - 64ビットのランダムな値を生成する
    • Random\Engine\PcgOneseq128XslRr64::jump - エンジンの内部状態を、効率的に複数ステップ進める
    • Random\Engine\PcgOneseq128XslRr64::__construct - 128 ビットのステートと XSL RR 変換を使う、新しいPCGエンジンを作成する
    • Random\Engine\PcgOneseq128XslRr64::__debugInfo - エンジンの内部的なステートを返す
    • Random\Engine\PcgOneseq128XslRr64::__serialize - PcgOneseq128XslRr64 オブジェクトをシリアライズする
    • Random\Engine\PcgOneseq128XslRr64::__unserialize - 指定した data を PcgOneseq128XslRr64 オブジェクトに復元する
    • Random\Engine\Secure::generate - 暗号学的にセキュアな、ランダムなバイト列を生成する
    • Random\Engine\Xoshiro256StarStar::generate - 64ビットのランダムな値を生成する
    • Random\Engine\Xoshiro256StarStar::jump - エンジンの内部状態を、効率的に 2^128 ステップ進める
    • Random\Engine\Xoshiro256StarStar::jumpLong - エンジンの内部状態を、効率的に 2^192 ステップ進める
    • Random\Engine\Xoshiro256StarStar::__construct - 新しい xoshiro256** エンジンを作成する
    • Random\Engine\Xoshiro256StarStar::__debugInfo - エンジンの内部的なステートを返す
    • Random\Engine\Xoshiro256StarStar::__serialize - Xoshiro256StarStar オブジェクトをシリアライズする
    • Random\Engine\Xoshiro256StarStar::__unserialize - 指定した data を Xoshiro256StarStar オブジェクトに復元する
    • Random\Randomizer::getBytes - ランダムなバイト列を取得する
    • Random\Randomizer::getBytesFromString - 文字列からランダムにバイト列を取得する
    • Random\Randomizer::getFloat - 等確率に選んだ float の値を取得する
    • Random\Randomizer::getInt - 等確率に選ばれる整数を取得する
    • Random\Randomizer::nextFloat - 半開区間 [0.0, 1.0) から、float の値を取得する
    • Random\Randomizer::nextInt - 正の整数を取得する
    • Random\Randomizer::pickArrayKeys - ランダムに配列のキーを選択する
    • Random\Randomizer::shuffleArray - 配列の順列を取得する
    • Random\Randomizer::shuffleBytes - 指定された文字列の、バイト単位の順列を取得する
    • Random\Randomizer::__construct - 新しい Randomizer を作成する
    • Random\Randomizer::__serialize - Randomizer オブジェクトをシリアライズする
    • Random\Randomizer::__unserialize - 指定した data を Randomizer オブジェクトに復元する
    • random_bytes - 暗号学的にセキュアな、ランダムなバイト列を生成する
    • random_int - 暗号学的にセキュアな方法で、等確率に出る整数を取得する
    • range - ある範囲の要素を含む配列を作成する
    • RarArchive::close - Rar アーカイブをクローズし、全リソースを開放する
    • RarArchive::getComment - RAR アーカイブのコメントテキストを取得する
    • RarArchive::getEntries - RAR アーカイブからエントリの全一覧を取得する
    • RarArchive::getEntry - Rar アーカイブからエントリオブジェクトを取得する
    • RarArchive::isBroken - アーカイブが壊れている (未完成である) かどうかを調べる
    • RarArchive::isSolid - RAR アーカイブがソリッドであるかどうかを調べる
    • RarArchive::open - Rar アーカイブをオープンする
    • RarArchive::setAllowBroken - 壊れたアーカイブのオープンを許可するかどうかを設定する
    • RarArchive::__toString - テキスト形式で取得する
    • RarEntry::extract - アーカイブのエントリを展開する
    • RarEntry::getAttr - エントリの属性を取得する
    • RarEntry::getCrc - エントリの CRC を取得する
    • RarEntry::getFileTime - エントリの最終更新時刻を取得する
    • RarEntry::getHostOs - エントリのホスト OS を取得する
    • RarEntry::getMethod - エントリの圧縮方法を取得する
    • RarEntry::getName - エントリの名前を取得する
    • RarEntry::getPackedSize - 圧縮後のエントリのサイズを取得する
    • RarEntry::getStream - このエントリのファイルハンドラを取得する
    • RarEntry::getUnpackedSize - 展開後のエントリのサイズを取得する
    • RarEntry::getVersion - このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する
    • RarEntry::isDirectory - このエントリがディレクトリであるかどうかを調べる
    • RarEntry::isEncrypted - このエントリが暗号化されているかどうかを調べる
    • RarEntry::__toString - エントリのテキスト表現を取得する
    • RarException::isUsingExceptions - 例外によるエラー処理を使っているかどうかを調べる
    • RarException::setUsingExceptions - 例外によるエラー処理の有効化および無効化を行う
    • rar_wrapper_cache_stats - URL ラッパーのキャッシュのヒット数
    • rawurldecode - URL エンコードされた文字列をデコードする
    • rawurlencode - RFC 3986 に基づき URL エンコードを行う
    • readdir - ディレクトリハンドルからエントリを読み込む
    • readfile - ファイルを出力する
    • readgzfile - gz ファイルを出力する
    • readline - 一行読み込む
    • readline_add_history - ヒストリに 1 行追加する
    • readline_callback_handler_install - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
    • readline_callback_handler_remove - インストールされたハンドラを削除し、端末の設定をもとに戻す
    • readline_callback_read_char - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する
    • readline_clear_history - ヒストリをクリアする
    • readline_completion_function - 補完関数を登録する
    • readline_info - 種々の readline の内部変数を取得/設定する
    • readline_list_history - ヒストリを一覧表示する
    • readline_on_new_line - カーソルが新しい行に移動したことを readline に通知する
    • readline_read_history - ヒストリを読み込む
    • readline_redisplay - 画面を再描画する
    • readline_write_history - ヒストリを書きこむ
    • readlink - シンボリックリンク先を返す
    • read_exif_data - のエイリアス exif_read_data
    • realpath - 正規化された絶対パス名を返す
    • realpath_cache_get - realpath キャッシュ・エントリーを取得
    • realpath_cache_size - realpath キャッシュサイズを取得
    • recode - recode_string のエイリアス
    • recode_file - コード変換指令に基づきファイルからファイルにコード変換する
    • recode_string - コード変換指令に基づき文字列のコードを変換する
    • RecursiveArrayIterator::getChildren - 現在のエントリが配列あるいはオブジェクトである場合に、そのイテレータを返す
    • RecursiveArrayIterator::hasChildren - 現在のエントリが配列あるいはオブジェクトであるかどうかを返す
    • RecursiveCachingIterator::getChildren - 内部イテレータの子を RecursiveCachingIterator として返す
    • RecursiveCachingIterator::hasChildren - 内部イテレータの現在の要素が子を持つかどうかチェックする
    • RecursiveCachingIterator::__construct - コンストラクタ
    • RecursiveCallbackFilterIterator::getChildren - RecursiveCallbackFilterIterator に含まれる内部イテレータの子を返す
    • RecursiveCallbackFilterIterator::hasChildren - 内部イテレータの現在の要素が子を持つかどうかを調べる
    • RecursiveCallbackFilterIterator::__construct - RecursiveIterator から RecursiveCallbackFilterIterator を作成する
    • RecursiveDirectoryIterator::getChildren - ディレクトリであれば、現在のエントリに対するイテレータを返す
    • RecursiveDirectoryIterator::getSubPath - サブパスを取得する
    • RecursiveDirectoryIterator::getSubPathname - サブパスと名前を取得する
    • RecursiveDirectoryIterator::hasChildren - 現在のエントリがディレクトリかつ '.' もしくは '..' でないかどうかを返す
    • RecursiveDirectoryIterator::key - 現在のディレクトリエントリのパスとファイル名を返す
    • RecursiveDirectoryIterator::next - 次のエントリに移動する
    • RecursiveDirectoryIterator::rewind - ディレクトリを最初に巻き戻す
    • RecursiveDirectoryIterator::__construct - RecursiveDirectoryIterator を作成する
    • RecursiveFilterIterator::getChildren - RecursiveFilterIterator に含まれる内部イテレータの子を返す
    • RecursiveFilterIterator::hasChildren - 内部イテレータの現在の要素が子を持つかどうかを調べる
    • RecursiveFilterIterator::__construct - RecursiveIterator から RecursiveFilterIterator を作成する
    • RecursiveIterator::getChildren - 現在のエントリのイテレータを返す
    • RecursiveIterator::hasChildren - 現在のエントリのイテレータを作れるかどうかを返す
    • RecursiveIteratorIterator::beginChildren - 子を開始する
    • RecursiveIteratorIterator::beginIteration - 反復処理を開始する
    • RecursiveIteratorIterator::callGetChildren - 子を取得する
    • RecursiveIteratorIterator::callHasChildren - 子を持つかどうかを調べる
    • RecursiveIteratorIterator::current - 現在の要素の値にアクセスする
    • RecursiveIteratorIterator::endChildren - 子を終了する
    • RecursiveIteratorIterator::endIteration - 反復処理を終了する
    • RecursiveIteratorIterator::getDepth - 再帰的なイテレーションにおける現在の深さを取得する
    • RecursiveIteratorIterator::getInnerIterator - 内部イテレータを取得する
    • RecursiveIteratorIterator::getMaxDepth - 最大の深さを取得する
    • RecursiveIteratorIterator::getSubIterator - 現在の有効なサブイテレータを取得する
    • RecursiveIteratorIterator::key - 現在のキーにアクセスする
    • RecursiveIteratorIterator::next - 次の要素に移動する
    • RecursiveIteratorIterator::nextElement - 次の要素
    • RecursiveIteratorIterator::rewind - トップレベルの内部イテレータの先頭要素にイテレータを巻き戻す
    • RecursiveIteratorIterator::setMaxDepth - 最大の深さを設定する
    • RecursiveIteratorIterator::valid - 現在の位置が有効かどうかをチェックする
    • RecursiveIteratorIterator::__construct - RecursiveIteratorIterator を作成する
    • RecursiveRegexIterator::getChildren - 現在のエントリのイテレータを返す
    • RecursiveRegexIterator::hasChildren - 現在のエントリのイテレータが取得可能かどうかを返す
    • RecursiveRegexIterator::__construct - 新しい RecursiveRegexIterator を作成する
    • RecursiveTreeIterator::beginChildren - 子を開始する
    • RecursiveTreeIterator::beginIteration - 反復処理を開始する
    • RecursiveTreeIterator::callGetChildren - 子を取得する
    • RecursiveTreeIterator::callHasChildren - 子を持っているかどうかを調べる
    • RecursiveTreeIterator::current - 現在の要素を取得する
    • RecursiveTreeIterator::endChildren - 子を終了する
    • RecursiveTreeIterator::endIteration - 反復処理を終了する
    • RecursiveTreeIterator::getEntry - 現在のエントリを取得する
    • RecursiveTreeIterator::getPostfix - 接尾辞を取得する
    • RecursiveTreeIterator::getPrefix - 接頭辞を取得する
    • RecursiveTreeIterator::key - 現在の要素のキーを取得する
    • RecursiveTreeIterator::next - 次の要素に移動する
    • RecursiveTreeIterator::nextElement - 次の要素
    • RecursiveTreeIterator::rewind - イテレータを巻き戻す
    • RecursiveTreeIterator::setPostfix - postfix を設定する
    • RecursiveTreeIterator::setPrefixPart - 接頭辞の部分を設定する
    • RecursiveTreeIterator::valid - 有効性を調べる
    • RecursiveTreeIterator::__construct - RecursiveTreeIterator を作成する
    • Reflection::export - エクスポートする
    • Reflection::getModifierNames - 修飾子の名前を取得する
    • ReflectionAttribute::getArguments - アトリビュートに渡された引数を取得する
    • ReflectionAttribute::getName - アトリビュートの名前を取得する
    • ReflectionAttribute::getTarget - アトリビュートのターゲットをビットマスクとして返す
    • ReflectionAttribute::isRepeated - この名前のアトリビュートが、実際にコード上に繰り返し現れているかどうかを取得する
    • ReflectionAttribute::newInstance - アトリビュートクラスをインスタンス化する
    • ReflectionAttribute::__construct - private なコンストラクタのため、直接インスタンス化できません
    • ReflectionClass::export - クラスをエクスポートする
    • ReflectionClass::getAttributes - アトリビュートを取得する
    • ReflectionClass::getConstant - 定義されている定数を取得する
    • ReflectionClass::getConstants - 定数を取得する
    • ReflectionClass::getConstructor - クラスのコンストラクタを取得する
    • ReflectionClass::getDefaultProperties - デフォルトプロパティを取得する
    • ReflectionClass::getDocComment - ドキュメントコメントを取得する
    • ReflectionClass::getEndLine - 終了行を取得する
    • ReflectionClass::getExtension - クラスを定義する拡張モジュールを表す ReflectionExtension オブジェクトを取得する
    • ReflectionClass::getExtensionName - クラスを定義する拡張モジュールの名前を取得する
    • ReflectionClass::getFileName - クラスが定義されているファイルのファイル名を取得する
    • ReflectionClass::getInterfaceNames - インターフェイスの名前を取得する
    • ReflectionClass::getInterfaces - インターフェイスを取得する
    • ReflectionClass::getMethod - クラスメソッドの ReflectionMethod を取得する
    • ReflectionClass::getMethods - メソッドの配列を取得する
    • ReflectionClass::getModifiers - クラス修飾子を取得する
    • ReflectionClass::getName - クラスの名前を取得する
    • ReflectionClass::getNamespaceName - 名前空間の名前を取得する
    • ReflectionClass::getParentClass - 親クラスを取得する
    • ReflectionClass::getProperties - プロパティを取得する
    • ReflectionClass::getProperty - クラスのプロパティを表す ReflectionProperty を取得する
    • ReflectionClass::getReflectionConstant - クラス定数の ReflectionClassConstant を取得する
    • ReflectionClass::getReflectionConstants - クラス定数を取得する
    • ReflectionClass::getShortName - 短い名前を取得する
    • ReflectionClass::getStartLine - 開始行を取得する
    • ReflectionClass::getStaticProperties - staticプロパティを取得する
    • ReflectionClass::getStaticPropertyValue - staticプロパティの値を取得する
    • ReflectionClass::getTraitAliases - トレイトのエイリアスの配列を返す
    • ReflectionClass::getTraitNames - このクラスが使うトレイトの名前の配列を返す
    • ReflectionClass::getTraits - このクラスが使うトレイトの配列を返す
    • ReflectionClass::hasConstant - 定数が定義されているかどうかを調べる
    • ReflectionClass::hasMethod - メソッドが定義されているかどうかを調べる
    • ReflectionClass::hasProperty - プロパティが定義されているかどうかを調べる
    • ReflectionClass::implementsInterface - インターフェイスの実装を調べる
    • ReflectionClass::inNamespace - 名前空間内にあるかどうかを調べる
    • ReflectionClass::isAbstract - 抽象クラスであるかどうかを調べる
    • ReflectionClass::isAnonymous - クラスが無名クラスかを調べる
    • ReflectionClass::isCloneable - このクラスがクローン可能かどうかを返す
    • ReflectionClass::isEnum - 列挙型であるかどうかを返す
    • ReflectionClass::isFinal - final クラスであるかどうかを調べる
    • ReflectionClass::isInstance - クラスのインスタンスであるかどうかを調べる
    • ReflectionClass::isInstantiable - クラスのインスタンス化が可能であるかどうかを調べる
    • ReflectionClass::isInterface - このクラスがインターフェイスであるかどうかを調べる
    • ReflectionClass::isInternal - 拡張モジュールあるいはコアで定義された内部クラスであるかどうかを調べる
    • ReflectionClass::isIterable - このクラスがイテレーション可能かを調べる
    • ReflectionClass::isIterateable - のエイリアス ReflectionClass::isIterable
    • ReflectionClass::isReadOnly - クラスが readonly かを調べる
    • ReflectionClass::isSubclassOf - サブクラスであるかどうかを調べる
    • ReflectionClass::isTrait - トレイトであるかどうかを返す
    • ReflectionClass::isUserDefined - ユーザー定義であるかどうかを調べる
    • ReflectionClass::newInstance - 指定した引数でクラスの新しいインスタンスを作成する
    • ReflectionClass::newInstanceArgs - 指定した引数でクラスの新しいインスタンスを作成する
    • ReflectionClass::newInstanceWithoutConstructor - コンストラクタを起動せずに新しいクラスのインスタンスを作成する
    • ReflectionClass::setStaticPropertyValue - staticプロパティの値を設定する
    • ReflectionClass::__construct - ReflectionClass を作成する
    • ReflectionClass::__toString - ReflectionClass オブジェクトの文字列表現を返す
    • ReflectionClassConstant::export - リフレクションをエクスポートする
    • ReflectionClassConstant::getAttributes - アトリビュートを取得する
    • ReflectionClassConstant::getDeclaringClass - 定数を宣言しているクラスを取得する
    • ReflectionClassConstant::getDocComment - クラス定数のドキュメントコメントを取得する
    • ReflectionClassConstant::getModifiers - クラス定数の修飾子を取得する
    • ReflectionClassConstant::getName - 定数名を取得する
    • ReflectionClassConstant::getValue - 値を取得する
    • ReflectionClassConstant::isEnumCase - クラス定数が、列挙型の case かどうかを調べる
    • ReflectionClassConstant::isFinal - クラス定数が final かどうかを調べる
    • ReflectionClassConstant::isPrivate - クラス定数がprivateかを調べる
    • ReflectionClassConstant::isProtected - クラス定数が protected かを調べる
    • ReflectionClassConstant::isPublic - クラス定数が public かを調べる
    • ReflectionClassConstant::__construct - ReflectionClassConstant を構築する
    • ReflectionClassConstant::__toString - ReflectionClassConstant オブジェクトの文字列表現を返す
    • ReflectionEnum::getBackingType - 存在する場合に、列挙型が依存する型を取得する
    • ReflectionEnum::getCase - 列挙型の特定の case を返す
    • ReflectionEnum::getCases - 列挙型の全ての case を返す
    • ReflectionEnum::hasCase - 列挙型が case を持つかを調べる
    • ReflectionEnum::isBacked - 列挙型が Backed Enum かを調べる
    • ReflectionEnum::__construct - ReflectionEnum オブジェクトをインスタンス化する
    • ReflectionEnumBackedCase::getBackingValue - Backed Enum の case が持つスカラー値を取得する
    • ReflectionEnumBackedCase::__construct - ReflectionEnumBackedCase オブジェクトをインスタンス化する
    • ReflectionEnumUnitCase::getEnum - この case が属するリフレクションオブジェクトを取得する
    • ReflectionEnumUnitCase::getValue - このリフレクションオブジェクトが表す case オブジェクトを取得する
    • ReflectionEnumUnitCase::__construct - ReflectionEnumUnitCase オブジェクトをインスタンス化する
    • ReflectionExtension::export - エクスポートする
    • ReflectionExtension::getClasses - クラスを取得する
    • ReflectionExtension::getClassNames - クラス名を取得する
    • ReflectionExtension::getConstants - 定数を取得する
    • ReflectionExtension::getDependencies - 依存性を取得する
    • ReflectionExtension::getFunctions - 拡張モジュールの関数を取得する
    • ReflectionExtension::getINIEntries - 拡張モジュールの ini エントリを取得する
    • ReflectionExtension::getName - 拡張モジュール名を取得する
    • ReflectionExtension::getVersion - 拡張モジュールのバージョンを取得する
    • ReflectionExtension::info - 拡張モジュールの情報を表示する
    • ReflectionExtension::isPersistent - この拡張モジュールが永続性のあるものかどうかを返す
    • ReflectionExtension::isTemporary - この拡張モジュールが一時的なものかどうかを返す
    • ReflectionExtension::__clone - クローンする
    • ReflectionExtension::__construct - ReflectionExtension を作成する
    • ReflectionExtension::__toString - 文字列に変換する
    • ReflectionFiber::getCallable - Fiber の構築に使われた callable を取得する
    • ReflectionFiber::getExecutingFile - 現在実行中のファイル名を取得する
    • ReflectionFiber::getExecutingLine - 現在実行中の行番号を取得する
    • ReflectionFiber::getFiber - リフレクションされた Fiber クラスのインスタンスを取得する
    • ReflectionFiber::getTrace - 現在実行している時点のバックトレースを取得する
    • ReflectionFiber::__construct - Constructs a ReflectionFiber オブジェクトを構築する
    • ReflectionFunction::export - 関数をエクスポートする
    • ReflectionFunction::getClosure - この関数に動的に作成されたクロージャを返す
    • ReflectionFunction::invoke - 関数を起動する
    • ReflectionFunction::invokeArgs - 引数を指定して関数を起動する
    • ReflectionFunction::isAnonymous - 関数が無名関数かどうかを調べる
    • ReflectionFunction::isDisabled - 関数が無効になっているかどうかを調べる
    • ReflectionFunction::__construct - ReflectionFunction オブジェクトを作成する
    • ReflectionFunction::__toString - ReflectionFunction を表現する文字列を返す
    • ReflectionFunctionAbstract::getAttributes - アトリビュートを取得する
    • ReflectionFunctionAbstract::getClosureScopeClass - クロージャに関連づけられたスコープクラスを返す
    • ReflectionFunctionAbstract::getClosureThis - クロージャにバインドした this ポインタを返す
    • ReflectionFunctionAbstract::getClosureUsedVariables - クロージャ内で使われている変数の配列を返す
    • ReflectionFunctionAbstract::getDocComment - ドキュメントコメントを取得する
    • ReflectionFunctionAbstract::getEndLine - 終了行番号を取得する
    • ReflectionFunctionAbstract::getExtension - 拡張モジュールの情報を取得する
    • ReflectionFunctionAbstract::getExtensionName - 拡張モジュールの名前を取得する
    • ReflectionFunctionAbstract::getFileName - ファイル名を取得する
    • ReflectionFunctionAbstract::getName - 関数名を取得する
    • ReflectionFunctionAbstract::getNamespaceName - 名前空間名を取得する
    • ReflectionFunctionAbstract::getNumberOfParameters - パラメータ数を取得する
    • ReflectionFunctionAbstract::getNumberOfRequiredParameters - 必須パラメータの数を取得する
    • ReflectionFunctionAbstract::getParameters - パラメータを取得する
    • ReflectionFunctionAbstract::getReturnType - 指定された関数の戻り値の型を取得する
    • ReflectionFunctionAbstract::getShortName - 関数の短い名前を取得する
    • ReflectionFunctionAbstract::getStartLine - 開始行番号を取得する
    • ReflectionFunctionAbstract::getStaticVariables - static変数を取得する
    • ReflectionFunctionAbstract::getTentativeReturnType - 関数に関連付けられた仮の戻り値の型を返す
    • ReflectionFunctionAbstract::hasReturnType - 関数が戻り値の型を指定しているかを調べる
    • ReflectionFunctionAbstract::hasTentativeReturnType - 戻り値の型を仮で宣言しているかを返す
    • ReflectionFunctionAbstract::inNamespace - 関数が名前空間内にあるかどうかを調べる
    • ReflectionFunctionAbstract::isClosure - クロージャであるかどうかを調べる
    • ReflectionFunctionAbstract::isDeprecated - 非推奨であるかどうかを調べる
    • ReflectionFunctionAbstract::isGenerator - この関数がジェネレータかどうかを返す
    • ReflectionFunctionAbstract::isInternal - 内部関数かどうかを調べる
    • ReflectionFunctionAbstract::isStatic - 関数が static であるかどうかを調べる
    • ReflectionFunctionAbstract::isUserDefined - ユーザー定義関数であるかどうかを調べる
    • ReflectionFunctionAbstract::isVariadic - この関数の引数が可変長かを調べる
    • ReflectionFunctionAbstract::returnsReference - 参照返しかどうかを調べる
    • ReflectionFunctionAbstract::__clone - 関数のクローンを作成する
    • ReflectionFunctionAbstract::__toString - ReflectionFunctionAbstract を表現する文字列を返す
    • ReflectionGenerator::getExecutingFile - 現在実行中のジェネレータのファイル名を取得する
    • ReflectionGenerator::getExecutingGenerator - 実行中の Generator オブジェクトを取得する
    • ReflectionGenerator::getExecutingLine - 現在実行中のジェネレータの行を取得する
    • ReflectionGenerator::getFunction - ジェネレータの関数名を取得する
    • ReflectionGenerator::getThis - ジェネレータの $this の値を取得する
    • ReflectionGenerator::getTrace - 実行中のジェネレータのトレースを取得する
    • ReflectionGenerator::__construct - ReflectionGenerator オブジェクトを構築する
    • ReflectionIntersectionType::getTypes - 交差型に含まれている型を返す
    • ReflectionMethod::createFromMethodName - ReflectionMethod を作成する
    • ReflectionMethod::export - メソッドをエクスポートする
    • ReflectionMethod::getClosure - このメソッドに動的に作成されたクロージャを返す
    • ReflectionMethod::getDeclaringClass - メソッドが宣言されているクラスを取得する
    • ReflectionMethod::getModifiers - メソッドの修飾子を取得する
    • ReflectionMethod::getPrototype - メソッドのプロトタイプを (存在すれば) 取得する
    • ReflectionMethod::hasPrototype - メソッドがプロトタイプを持つかを調べる
    • ReflectionMethod::invoke - 実行する
    • ReflectionMethod::invokeArgs - 実行する
    • ReflectionMethod::isAbstract - 抽象メソッドであるかどうかを調べる
    • ReflectionMethod::isConstructor - コンストラクタであるかどうかを調べる
    • ReflectionMethod::isDestructor - デストラクタであるかどうかを調べる
    • ReflectionMethod::isFinal - final メソッドであるかどうかを調べる
    • ReflectionMethod::isPrivate - private メソッドであるかどうかを調べる
    • ReflectionMethod::isProtected - protected メソッドであるかどうかを調べる
    • ReflectionMethod::isPublic - public メソッドであるかどうかを調べる
    • ReflectionMethod::setAccessible - メソッドのアクセス範囲を設定する
    • ReflectionMethod::__construct - ReflectionMethod を作成する
    • ReflectionMethod::__toString - ReflectionMethod オブジェクトの文字列表現を返す
    • ReflectionNamedType::getName - 型の名前の文字列を取得する
    • ReflectionNamedType::isBuiltin - 組み込みの型であるかを調べる
    • ReflectionObject::export - エクスポートする
    • ReflectionObject::__construct - ReflectionObject を作成する
    • ReflectionParameter::allowsNull - null を許可するかどうかを調べる
    • ReflectionParameter::canBePassedByValue - このパラメータが値渡し可能かどうかを返す
    • ReflectionParameter::export - エクスポートする
    • ReflectionParameter::getAttributes - アトリビュートを取得する
    • ReflectionParameter::getClass - リフレクションされた ReflectionClass を取得する。
    • ReflectionParameter::getDeclaringClass - 宣言しているクラスを取得する
    • ReflectionParameter::getDeclaringFunction - 宣言している関数を取得する
    • ReflectionParameter::getDefaultValue - パラメータのデフォルト値を取得する
    • ReflectionParameter::getDefaultValueConstantName - デフォルト値が定数あるいは null の場合に、その定数名を返す
    • ReflectionParameter::getName - パラメータ名を取得する
    • ReflectionParameter::getPosition - パラメータの位置を取得する
    • ReflectionParameter::getType - 引数の型を取得する
    • ReflectionParameter::hasType - 引数が型を持つかを調べる
    • ReflectionParameter::isArray - 配列を受け取るパラメータであるかどうかを調べる
    • ReflectionParameter::isCallable - パラメータが callable かどうかを返す
    • ReflectionParameter::isDefaultValueAvailable - デフォルト値が存在するかどうかを調べる
    • ReflectionParameter::isDefaultValueConstant - このパラメータのデフォルト値が定数かどうかを返す
    • ReflectionParameter::isOptional - 省略可能であるかどうかを調べる
    • ReflectionParameter::isPassedByReference - 参照渡しかどうかを調べる
    • ReflectionParameter::isVariadic - 引数が可変長の個数であるかをチェックする
    • ReflectionParameter::__clone - クローンする
    • ReflectionParameter::__construct - コンストラクタ
    • ReflectionParameter::__toString - 文字列に変換する
    • ReflectionProperty::export - エクスポートする
    • ReflectionProperty::getAttributes - アトリビュートを取得する
    • ReflectionProperty::getDeclaringClass - 宣言しているクラスを取得する
    • ReflectionProperty::getDefaultValue - プロパティで宣言されたデフォルト値を返す
    • ReflectionProperty::getDocComment - プロパティのドキュメントコメントを取得する
    • ReflectionProperty::getModifiers - プロパティの修飾子を取得する
    • ReflectionProperty::getName - プロパティ名を取得する
    • ReflectionProperty::getType - プロパティの型を取得する
    • ReflectionProperty::getValue - 値を取得する
    • ReflectionProperty::hasDefaultValue - デフォルト値が宣言されているかをチェックする
    • ReflectionProperty::hasType - プロパティが型を持つかをチェックする
    • ReflectionProperty::isDefault - デフォルトプロパティであるかどうかを調べる
    • ReflectionProperty::isInitialized - プロパティが初期化されているかをチェックする
    • ReflectionProperty::isPrivate - private プロパティであるかどうかを調べる
    • ReflectionProperty::isPromoted - プロパティがコンストラクタの引数から昇格したものかを調べる
    • ReflectionProperty::isProtected - protected プロパティであるかどうかを調べる
    • ReflectionProperty::isPublic - public プロパティであるかどうかを調べる
    • ReflectionProperty::isReadOnly - プロパティが readonly かを調べる
    • ReflectionProperty::isStatic - staticプロパティであるかどうかを調べる
    • ReflectionProperty::setAccessible - プロパティのアクセス範囲を設定する
    • ReflectionProperty::setValue - プロパティの値を設定する
    • ReflectionProperty::__clone - クローンする
    • ReflectionProperty::__construct - ReflectionProperty オブジェクトを作成する
    • ReflectionProperty::__toString - 文字列に変換する
    • ReflectionReference::fromArrayElement - 配列の要素から、ReflectionReference を生成する
    • ReflectionReference::getId - リファレンスのユニークなIDを取得する
    • ReflectionReference::__construct - private なコンストラクタのため、直接インスタンス化できません
    • ReflectionType::allowsNull - null が許されるかをチェックする
    • ReflectionType::__toString - 文字列に変換する
    • ReflectionUnionType::getTypes - union 型に含まれる型を返す。
    • ReflectionZendExtension::export - エクスポート
    • ReflectionZendExtension::getAuthor - 作者を取得する
    • ReflectionZendExtension::getCopyright - 著作権情報を取得する
    • ReflectionZendExtension::getName - 名前を取得する
    • ReflectionZendExtension::getURL - URL を取得する
    • ReflectionZendExtension::getVersion - バージョンを取得する
    • ReflectionZendExtension::__clone - Clone のハンドラ
    • ReflectionZendExtension::__construct - ReflectionZendExtension オブジェクトを作成する
    • ReflectionZendExtension::__toString - 文字列変換のハンドラ
    • Reflector::export - エクスポートする
    • RegexIterator::accept - 受け入れ状況を取得する
    • RegexIterator::getFlags - フラグを取得する
    • RegexIterator::getMode - 操作モードを返す
    • RegexIterator::getPregFlags - 正規表現フラグを返す
    • RegexIterator::getRegex - 現在の正規表現を返す
    • RegexIterator::setFlags - フラグを設定する
    • RegexIterator::setMode - 操作モードを設定する
    • RegexIterator::setPregFlags - 正規表現フラグを設定する
    • RegexIterator::__construct - 新しい RegexIterator を作成する
    • register_shutdown_function - シャットダウン時に実行する関数を登録する
    • register_tick_function - 各 tick で実行する関数を登録する
    • rename - ファイルをリネームする
    • reset - 配列の内部ポインタを先頭の要素にセットする
    • ResourceBundle::count - バンドル内の要素数を取得する
    • ResourceBundle::create - リソースバンドルを作成する
    • ResourceBundle::get - バンドルからデータを取得する
    • ResourceBundle::getErrorCode - バンドルの直近のエラーコードを取得する
    • ResourceBundle::getErrorMessage - バンドルの直近のエラーメッセージを取得する
    • ResourceBundle::getLocales - サポートするロケールを取得する
    • restore_error_handler - 以前のエラーハンドラ関数を回復する
    • restore_exception_handler - 以前の例外ハンドラ関数を回復する
    • restore_include_path - include_path 設定オプションの値を元に戻す
    • Result::getAffectedItemsCount - 影響を受けた行数を得る
    • Result::getAutoIncrementValue - 自動インクリメントされた値を取得する
    • Result::getGeneratedIds - 生成された id を取得する
    • Result::getWarnings - 直近の操作から発生した警告を取得する
    • Result::getWarningsCount - 直近の操作から生じた警告の数を取得する
    • Result::__construct - Result のコンストラクタ
    • ReturnTypeWillChange::__construct - 新しい ReturnTypeWillChange のインスタンスを作成する
    • rewind - ファイルポインタの位置を先頭に戻す
    • rewinddir - ディレクトリハンドルを元に戻す
    • rmdir - ディレクトリを削除する
    • rnp_backend_string - Return cryptographic backend library name
    • rnp_backend_version - Return cryptographic backend library version
    • rnp_decrypt - Decrypt PGP message
    • rnp_dump_packets - Dump OpenPGP packets stream information in humand-readable format
    • rnp_dump_packets_to_json - Dump OpenPGP packets stream information to the JSON string
    • rnp_ffi_create - Create the top-level object used for interacting with the library
    • rnp_ffi_destroy - Destroy the top-level object used for interacting with the library
    • rnp_ffi_set_pass_provider - Set password provider callback function
    • rnp_import_keys - Import keys from PHP string to the keyring and receive JSON describing new/updated keys
    • rnp_import_signatures - Import standalone signatures to the keyring and receive JSON describing updated keys
    • rnp_key_export - Export a key
    • rnp_key_export_autocrypt - Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)
    • rnp_key_export_revocation - Generate and export primary key revocation signature
    • rnp_key_get_info - Get information about the key
    • rnp_key_remove - Remove a key from keyring(s)
    • rnp_key_revoke - Revoke a key or subkey by generating and adding revocation signature
    • rnp_list_keys - Enumerate all keys present in a keyring by specified identifer type
    • rnp_load_keys - Load keys from PHP string
    • rnp_load_keys_from_path - Load keys from specified path
    • rnp_locate_key - Search for the key
    • rnp_op_encrypt - Encrypt message
    • rnp_op_generate_key - Generate key
    • rnp_op_sign - Perform signing operation on a binary data, return embedded signature(s)
    • rnp_op_sign_cleartext - Perform signing operation on a textual data, return cleartext signed message
    • rnp_op_sign_detached - Perform signing operation, return detached signature(s)
    • rnp_op_verify - Verify embedded or cleartext signatures
    • rnp_op_verify_detached - Verify detached signatures
    • rnp_save_keys - Save keys to PHP string
    • rnp_save_keys_to_path - Save keys to specified path
    • rnp_supported_features - Get supported features in JSON format
    • rnp_version_string - RNP library version
    • rnp_version_string_full - Full version string of RNP library
    • round - 浮動小数点数を丸める
    • RowResult::fetchAll - 結果セットから全ての行を取得する
    • RowResult::fetchOne - 結果セットから行を取得する
    • RowResult::getColumnNames - 全てのカラム名を取得する
    • RowResult::getColumns - カラムのメタデータを取得する
    • RowResult::getColumnsCount - カラムの数を取得する
    • RowResult::getWarnings - 直近の操作から生じた警告を取得する
    • RowResult::getWarningsCount - 直近の操作から生じた警告の数を取得する
    • RowResult::__construct - RowResult のコンストラクタ
    • rpmaddtag - Add tag retrieved in query
    • rpmdbinfo - Get information from installed RPM
    • rpmdbsearch - Search RPM packages
    • rpmgetsymlink - Get target of a symlink
    • rpminfo - Get information from a RPM file
    • rpmvercmp - RPM version comparison
    • RRDCreator::addArchive - Adds RRA - archive of data values for each data source
    • RRDCreator::addDataSource - Adds data source definition for RRD database
    • RRDCreator::save - Saves the RRD database to a file
    • RRDCreator::__construct - Creates new RRDCreator instance
    • rrdc_disconnect - Close any outstanding connection to rrd caching daemon
    • RRDGraph::save - Saves the result of query into image
    • RRDGraph::saveVerbose - Saves the RRD database query into image and returns the verbose information about generated graph
    • RRDGraph::setOptions - Sets the options for rrd graph export
    • RRDGraph::__construct - Creates new RRDGraph instance
    • RRDUpdater::update - Update the RRD database file
    • RRDUpdater::__construct - Creates new RRDUpdater instance
    • rrd_create - Creates rrd database file
    • rrd_error - Gets latest error message
    • rrd_fetch - Fetch the data for graph as array
    • rrd_first - Gets the timestamp of the first sample from rrd file
    • rrd_graph - Creates image from a data
    • rrd_info - Gets information about rrd file
    • rrd_last - Gets unix timestamp of the last sample
    • rrd_lastupdate - Gets information about last updated data
    • rrd_restore - Restores the RRD file from XML dump
    • rrd_tune - Tunes some RRD database file header options
    • rrd_update - Updates the RRD database
    • rrd_version - Gets information about underlying rrdtool library
    • rrd_xport - Exports the information about RRD database
    • rsort - 配列を降順にソートする
    • rtrim - 文字列の最後から空白 (もしくはその他の文字) を取り除く
    • runkit7_constant_add - Similar to define(), but allows defining in class definitions as well
    • runkit7_constant_redefine - Redefine an already defined constant
    • runkit7_constant_remove - Remove/Delete an already defined constant
    • runkit7_function_add - Add a new function, similar to create_function
    • runkit7_function_copy - Copy a function to a new function name
    • runkit7_function_redefine - Replace a function definition with a new implementation
    • runkit7_function_remove - Remove a function definition
    • runkit7_function_rename - Change a function's name
    • runkit7_import - Process a PHP file importing function and class definitions, overwriting where appropriate
    • runkit7_method_add - Dynamically adds a new method to a given class
    • runkit7_method_copy - Copies a method from class to another
    • runkit7_method_redefine - Dynamically changes the code of the given method
    • runkit7_method_remove - Dynamically removes the given method
    • runkit7_method_rename - Dynamically changes the name of the given method
    • runkit7_object_id - Return the integer object handle for given object
    • runkit7_superglobals - Return numerically indexed array of registered superglobals
    • runkit7_zval_inspect - Returns information about the passed in value with data types, reference counts, etc
  • s
    • sapi_windows_cp_conv - 文字列のコードページを別のものに変換する
    • sapi_windows_cp_get - 現在のコードページを取得する
    • sapi_windows_cp_is_utf8 - コードページがUTF-8と互換性があるかを返す
    • sapi_windows_cp_set - 現在のプロセスのコードページを設定する
    • sapi_windows_generate_ctrl_event - CTRLイベント を別プロセスに送信する
    • sapi_windows_set_ctrl_handler - CTRLイベント のハンドラを設定したり削除したりする
    • sapi_windows_vt100_support - Windows コンソールの出力バッファに関連付けられたストリームのVT100サポート状況を取得/設定する
    • scandir - 指定されたパスのファイルとディレクトリのリストを取得する
    • Schema::createCollection - スキーマにコレクションを追加する
    • Schema::dropCollection - スキーマからコレクションを削除する
    • Schema::existsInDatabase - データベースに存在するかをチェックする
    • Schema::getCollection - スキーマからコレクションを取得する
    • Schema::getCollectionAsTable - コレクションをテーブルオブジェクトとして取得する
    • Schema::getCollections - スキーマに属する全てのコレクションを取得する
    • Schema::getName - スキーマの名前を取得する
    • Schema::getSession - スキーマのセッションを取得する
    • Schema::getTable - スキーマのテーブルを取得する
    • Schema::getTables - スキーマのテーブルを取得する
    • Schema::__construct - Schema のコンストラクタ
    • SchemaObject::getSchema - スキーマオブジェクトを得る
    • scoutapm_get_calls - 収集する処理が呼ばれた情報の一覧を返す
    • scoutapm_list_instrumented_functions - scoutapm がデータを収集する関数の一覧
    • SeasLog::alert - Record alert log information
    • SeasLog::analyzerCount - Get log count by level, log_path and key_word
    • SeasLog::analyzerDetail - Get log detail by level, log_path, key_word, start, limit, order
    • SeasLog::closeLoggerStream - Manually release stream flow from logger
    • SeasLog::critical - Record critical log information
    • SeasLog::debug - Record debug log information
    • SeasLog::emergency - Record emergency log information
    • SeasLog::error - Record error log information
    • SeasLog::flushBuffer - Flush logs buffer, dump to appender file, or send to remote api with tcp/udp
    • SeasLog::getBasePath - Get SeasLog base path.
    • SeasLog::getBuffer - Get the logs buffer in memory as array
    • SeasLog::getBufferEnabled - Determin if buffer enabled
    • SeasLog::getDatetimeFormat - Get SeasLog datetime format style
    • SeasLog::getLastLogger - Get SeasLog last logger path
    • SeasLog::getRequestID - Get SeasLog request_id differentiated requests
    • SeasLog::getRequestVariable - Get SeasLog request variable
    • SeasLog::info - Record info log information
    • SeasLog::log - The Common Record Log Function
    • SeasLog::notice - Record notice log information
    • SeasLog::setBasePath - Set SeasLog base path
    • SeasLog::setDatetimeFormat - Set SeasLog datetime format style
    • SeasLog::setLogger - Set SeasLog logger name
    • SeasLog::setRequestID - Set SeasLog request_id differentiated requests
    • SeasLog::setRequestVariable - Manually set SeasLog request variable
    • SeasLog::warning - Record warning log information
    • SeasLog::__construct - Description
    • SeasLog::__destruct - Description
    • seaslog_get_author - Get SeasLog author.
    • seaslog_get_version - Get SeasLog version.
    • SeekableIterator::seek - 位置を移動する
    • sem_acquire - セマフォを得る
    • sem_get - セマフォ ID を得る
    • sem_release - セマフォを解放する
    • sem_remove - セマフォを削除する
    • SensitiveParameter::__construct - 新しい SensitiveParameter のインスタンスを作成する
    • SensitiveParameterValue::getValue - 秘密の値を返す
    • SensitiveParameterValue::__construct - 新しい SensitiveParameterValue オブジェクトを作成する
    • SensitiveParameterValue::__debugInfo - 秘密の値をうっかり公開することを防止する
    • Serializable::serialize - オブジェクトの文字列表現
    • Serializable::unserialize - オブジェクトを作成する
    • serialize - 値の保存可能な表現を生成する
    • Session::close - セッションを閉じる
    • Session::commit - トランザクションをコミットする
    • Session::createSchema - 新しいスキーマを作成する
    • Session::dropSchema - スキーマを削除します
    • Session::generateUUID - 新しいUUIDを取得する
    • Session::getDefaultSchema - デフォルトのスキーマ名を取得する
    • Session::getSchema - 新しいスキーマオブジェクトを取得する
    • Session::getSchemas - スキーマを取得する
    • Session::getServerVersion - サーバーのバージョンを取得する
    • Session::listClients - クライアントの一覧を取得する
    • Session::quoteName - クォートを追加する
    • Session::releaseSavepoint - 設定されたセーブポイントをリリースする
    • Session::rollback - トランザクションをロールバックする
    • Session::rollbackTo - セーブポイントまでトランザクションをロールバックする
    • Session::setSavepoint - セーブポイントを作成する
    • Session::sql - SQLクエリを作成する
    • Session::startTransaction - トランザクションを開始する
    • Session::__construct - Session のコンストラクタ
    • SessionHandler::close - セッションを閉じる
    • SessionHandler::create_sid - 新規セッション ID を返す
    • SessionHandler::destroy - セッションを破棄する
    • SessionHandler::gc - 古いセッションを削除する
    • SessionHandler::open - セッションを開始する
    • SessionHandler::read - セッションのデータを読み込む
    • SessionHandler::write - セッションのデータを書き込む
    • SessionHandlerInterface::close - セッションを閉じる
    • SessionHandlerInterface::destroy - セッションを破棄する
    • SessionHandlerInterface::gc - 古いセッションを削除する
    • SessionHandlerInterface::open - セッションを開始する
    • SessionHandlerInterface::read - セッションのデータを読み込む
    • SessionHandlerInterface::write - セッションのデータを書き込む
    • SessionIdInterface::create_sid - セッションIDを作成する
    • SessionUpdateTimestampHandlerInterface::updateTimestamp - タイムスタンプを更新する
    • SessionUpdateTimestampHandlerInterface::validateId - セッションIDを検証する
    • session_abort - session 配列の変更を破棄してセッションを終了します
    • session_cache_expire - 現在のキャッシュの有効期限を取得/設定する
    • session_cache_limiter - 現在のキャッシュリミッタを取得または設定する
    • session_commit - session_write_close のエイリアス
    • session_create_id - 新しいセッションIDを作成する
    • session_decode - セッションエンコードされた文字列からセッションデータをデコードする
    • session_destroy - セッションに登録されたデータを全て破棄する
    • session_encode - 現在のセッションデータを、セッションエンコードされた文字列に変換する
    • session_gc - セッションデータのガベージコレクションを実行する
    • session_get_cookie_params - セッションクッキーのパラメータを得る
    • session_id - 現在のセッション ID を取得または設定する
    • session_module_name - 現在のセッションモジュールを取得または設定する
    • session_name - 現在のセッション名を取得または設定する
    • session_regenerate_id - 現在のセッションIDを新しく生成したものと置き換える
    • session_register_shutdown - セッションのシャットダウン関数
    • session_reset - session 配列を元の値で再初期化します
    • session_save_path - 現在のセッションデータ保存パスを取得または設定する
    • session_set_cookie_params - セッションクッキーパラメータを設定する
    • session_set_save_handler - ユーザー定義のセッション保存関数を設定する
    • session_start - 新しいセッションを開始、あるいは既存のセッションを再開する
    • session_status - 現在のセッションの状態を返す
    • session_unset - 全てのセッション変数を開放する
    • session_write_close - セッションデータを書き込んでセッションを終了する
    • setcookie - クッキーを送信する
    • setlocale - ロケール情報を設定する
    • setrawcookie - 値を URL エンコードせずにクッキーを送信する
    • settype - 変数の型をセットする
    • set_error_handler - ユーザー定義のエラーハンドラ関数を設定する
    • set_exception_handler - ユーザー定義の例外ハンドラ関数を設定する
    • set_file_buffer - stream_set_write_buffer のエイリアス
    • set_include_path - include_path 設定オプションをセットする
    • set_time_limit - 実行時間の最大値を制限する
    • sha1 - 文字列の sha1 ハッシュを計算する
    • sha1_file - ファイルの sha1 ハッシュを計算する
    • shell_exec - シェルによりコマンドを実行し、文字列として出力全体を返す
    • shmop_close - 共有メモリブロックを閉じる
    • shmop_delete - 共有メモリブロックを削除する
    • shmop_open - 共有メモリブロックを作成またはオープンする
    • shmop_read - 共有メモリブロックからデータを読み取る
    • shmop_size - 共有メモリブロックの大きさを取得する
    • shmop_write - 共有メモリブロックにデータを書き込む
    • shm_attach - 共有メモリセグメントを作成またはオープンする
    • shm_detach - 共有メモリセグメントへの接続を閉じる
    • shm_get_var - 共有メモリから変数を返す
    • shm_has_var - 特定のエントリが存在するかどうかを調べる
    • shm_put_var - 共有メモリの変数を挿入または更新する
    • shm_remove - Unix システムから共有メモリを削除する
    • shm_remove_var - 共有メモリから変数を削除する
    • show_source - highlight_file のエイリアス
    • shuffle - 配列をシャッフルする
    • simdjson_decode - Decodes a JSON string
    • simdjson_is_valid - Check if a JSON string is valid
    • simdjson_key_count - Returns the value at a JSON pointer.
    • simdjson_key_exists - Check if the JSON contains the value referred to by a JSON pointer.
    • simdjson_key_value - Decodes the value of a JSON string located at the requested JSON pointer.
    • similar_text - 二つの文字列の間の類似性を計算する
    • SimpleXMLElement::addAttribute - SimpleXML 要素に属性を追加する
    • SimpleXMLElement::addChild - XML ノードに子要素を追加する
    • SimpleXMLElement::asXML - SimpleXML 要素に基づき整形式の XML 文字列を返す
    • SimpleXMLElement::attributes - 要素の属性を定義する
    • SimpleXMLElement::children - 指定したノードの子ノードを見付ける
    • SimpleXMLElement::count - 子要素を数える
    • SimpleXMLElement::current - 現在の要素を返す
    • SimpleXMLElement::getChildren - 現在の要素の子要素を返す
    • SimpleXMLElement::getDocNamespaces - ドキュメントで宣言されている名前空間を返す
    • SimpleXMLElement::getName - XML 要素の名前を取得する
    • SimpleXMLElement::getNamespaces - ドキュメントで使用している名前空間を返す
    • SimpleXMLElement::hasChildren - 現在の要素が子要素を持つかどうかを調べる
    • SimpleXMLElement::key - 現在のキーを返す
    • SimpleXMLElement::next - 次の要素に移動する
    • SimpleXMLElement::registerXPathNamespace - 次の XPath クエリ用の prefix/ns コンテキストを作成する
    • SimpleXMLElement::rewind - 最初の要素に巻き戻す
    • SimpleXMLElement::saveXML - SimpleXMLElement::asXML のエイリアス
    • SimpleXMLElement::valid - 現在の要素が有効かどうかを調べる
    • SimpleXMLElement::xpath - XML データに Xpath クエリを実行する
    • SimpleXMLElement::__construct - 新しい SimpleXMLElement オブジェクトを作成する
    • SimpleXMLElement::__toString - 文字列で要素の内容を返す
    • simplexml_import_dom - DOM ノードから SimpleXMLElement オブジェクトを取得する
    • simplexml_load_file - XMLファイルをパースし、オブジェクトに代入する
    • simplexml_load_string - XML 文字列をオブジェクトに代入する
    • sin - 正弦（サイン）
    • sinh - 双曲線正弦（ハイパボリックサイン）
    • sizeof - count のエイリアス
    • sleep - 実行を遅延させる
    • snmp2_get - SNMP オブジェクトを取得する
    • snmp2_getnext - 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmp2_real_walk - 指定したすべてのオブジェクトとそのオブジェクト ID を返す
    • snmp2_set - SNMP オブジェクトの値を設定する
    • snmp2_walk - すべての SNMP オブジェクトをエージェントから取得する
    • snmp3_get - SNMP オブジェクトを取得する
    • snmp3_getnext - 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmp3_real_walk - 指定したすべてのオブジェクトとそのオブジェクト ID を返す
    • snmp3_set - SNMP オブジェクトの値を設定する
    • snmp3_walk - すべての SNMP オブジェクトをエージェントから取得する
    • SNMP::close - SNMP セッションを閉じる
    • SNMP::get - SNMP オブジェクトを取得する
    • SNMP::getErrno - 直近のエラーコードを取得する
    • SNMP::getError - 直近のエラーメッセージを取得する
    • SNMP::getnext - 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • SNMP::set - SNMP オブジェクトの値を設定する
    • SNMP::setSecurity - セキュリティ関連の SNMPv3 セッションパラメータを設定する
    • SNMP::walk - SNMP オブジェクトのサブツリーを取得する
    • SNMP::__construct - リモート SNMP エージェントへのセッションを表す SNMP インスタンスを作成する
    • snmpget - SNMP オブジェクトを取得する
    • snmpgetnext - 指定したオブジェクト ID に続く SNMP オブジェクトを取得する
    • snmprealwalk - 指定したオブジェクトに関するオブジェクト ID を含むすべてのオブジェクトを返す
    • snmpset - SNMP オブジェクトの値を設定する
    • snmpwalk - エージェントから全ての SNMP オブジェクトを取得する
    • snmpwalkoid - ネットワークエンティティに関する情報ツリーを検索する
    • snmp_get_quick_print - NET-SNMP ライブラリの quick_print の現在の設定値を取得する
    • snmp_get_valueretrieval - SNMP の値が返される方法を返す
    • snmp_read_mib - アクティブな MIB ツリーの中に MIB ファイルを読み込んでパースする
    • snmp_set_enum_print - すべての enum を、実際の整数値ではなく enum 値とともに返す
    • snmp_set_oid_numeric_print - snmp_set_oid_output_format のエイリアス
    • snmp_set_oid_output_format - OID の出力形式を設定する
    • snmp_set_quick_print - NET-SNMP ライブラリで enable の値を設定する
    • snmp_set_valueretrieval - SNMP の値が返される方法を設定する
    • SoapClient::__call - SOAP 関数をコールする (非推奨)
    • SoapClient::__construct - SoapClient のコンストラクタ
    • SoapClient::__doRequest - SOAP リクエストを実行する
    • SoapClient::__getCookies - クッキーの一覧を取得する
    • SoapClient::__getFunctions - SOAP 関数の一覧を返す
    • SoapClient::__getLastRequest - 直近の SOAP リクエストを返す
    • SoapClient::__getLastRequestHeaders - 直近の SOAP リクエストヘッダを返す
    • SoapClient::__getLastResponse - 直近の SOAP レスポンスを返す
    • SoapClient::__getLastResponseHeaders - 直近の SOAP レスポンスヘッダを返す
    • SoapClient::__getTypes - SOAP 型の一覧を返す
    • SoapClient::__setCookie - SOAP リクエストと共に送信されるクッキーを設定する
    • SoapClient::__setLocation - 使用するウェブサービスの場所を設定する
    • SoapClient::__setSoapHeaders - 以降のコール用の SOAP ヘッダを設定する
    • SoapClient::__soapCall - SOAP 関数をコールする
    • SoapFault::__construct - SoapFault コンストラクタ
    • SoapFault::__toString - SoapFault の文字列表現を取得する
    • SoapHeader::__construct - SoapHeader コンストラクタ
    • SoapParam::__construct - SoapParam コンストラクタ
    • SoapServer::addFunction - SOAP リクエストによって処理される単一もしくはいくつかの関数を追加する
    • SoapServer::addSoapHeader - SOAP ヘッダをレスポンスに追加する
    • SoapServer::fault - エラーを示す SoapServer フォールト を発行する
    • SoapServer::getFunctions - 定義されている関数の一覧を返す
    • SoapServer::handle - SOAP リクエストを処理する
    • SoapServer::setClass - SOAP リクエストを処理するクラスを設定する
    • SoapServer::setObject - SOAP リクエストの処理に使用するオブジェクトを設定する
    • SoapServer::setPersistence - SoapServer の持続モードを設定する
    • SoapServer::__construct - SoapServer コンストラクタ
    • SoapVar::__construct - SoapVar コンストラクタ
    • socket_accept - ソケットへの接続を許可する
    • socket_addrinfo_bind - 与えられた addrinfo から、ソケットを作成してバインドする
    • socket_addrinfo_connect - 与えられた addrinfo から、ソケットを作って接続する
    • socket_addrinfo_explain - addrinfo に関する情報を取得する
    • socket_addrinfo_lookup - 与えられたホスト名に関する getaddrinfo の内容を配列で取得する
    • socket_atmark - ソケットに帯域外マークが付けられているかを調べる
    • socket_bind - ソケットに名前をバインドする
    • socket_clear_error - ソケットのエラーまたは直近のエラーコードをクリアする
    • socket_close - Socket クラスのインスタンスを閉じる
    • socket_cmsg_space - メッセージバッファサイズを計算する
    • socket_connect - ソケット上の接続を初期化する
    • socket_create - ソケット（通信時の終端）を作成する
    • socket_create_listen - 接続を受けつけるためにポートにソケットをオープンする
    • socket_create_pair - 区別できないソケットの組を作成し、配列に保存する
    • socket_export_stream - ソケットをカプセル化したストリームに、ソケットをエクスポートする
    • socket_getopt - socket_get_option のエイリアス
    • socket_getpeername - 指定したソケットのリモート側に問い合わせる
    • socket_getsockname - 指定したソケットのローカル側に問い合わせ、その型に応じてホスト/ポート、あるいは Unix ファイルシステムのパスを返す
    • socket_get_option - ソケットのオプションを取得する
    • socket_get_status - stream_get_meta_data のエイリアス
    • socket_import_stream - ストリームをインポートする
    • socket_last_error - ソケットの直近のエラーを返す
    • socket_listen - ソケット上で接続待ち(listen)する
    • socket_read - ソケットから最大バイト長まで読みこむ
    • socket_recv - 接続したソケットからデータを受信する
    • socket_recvfrom - 接続しているかどうかによらず、ソケットからデータを受信する
    • socket_recvmsg - メッセージを読む
    • socket_select - 与えられたソケットの配列に対し、指定した有効時間で select() システムコールを実行する
    • socket_send - 接続したソケットにデータを送信する
    • socket_sendmsg - メッセージを送信する
    • socket_sendto - 接続しているかどうかによらずソケットにメッセージを送信する
    • socket_setopt - socket_set_option のエイリアス
    • socket_set_block - ソケットのブロッキングモードを設定する
    • socket_set_blocking - stream_set_blocking のエイリアス
    • socket_set_nonblock - ソケットリソースを非ブロックモードに設定する
    • socket_set_option - ソケットのオプションを設定する
    • socket_set_timeout - stream_set_timeout のエイリアス
    • socket_shutdown - 受信、送信、または送受信用のソケットをシャットダウンする
    • socket_strerror - ソケットエラーの内容を文字列として返す
    • socket_write - ソケットに書き込む
    • socket_wsaprotocol_info_export - WSAPROTOCOL_INFO 構造体をエクスポートする
    • socket_wsaprotocol_info_import - 別のプロセスからソケットをインポートする
    • socket_wsaprotocol_info_release - エクスポートした WSAPROTOCOL_INF 構造体を解放する
    • sodium_add - 巨大な数を加算する
    • sodium_base642bin - base64 エンコードされた文字列を、生バイナリにデコードする
    • sodium_bin2base64 - 生バイナリを base64 文字列にエンコードする
    • sodium_bin2hex - 16進数にエンコードする
    • sodium_compare - 巨大な数を比較する
    • sodium_crypto_aead_aes256gcm_decrypt - AES-256-GCM を用いてメッセージを検証し、復号する
    • sodium_crypto_aead_aes256gcm_encrypt - AES-256-GCM を使って暗号化し、認証を行う
    • sodium_crypto_aead_aes256gcm_is_available - ハードウェアが AES256-GCM をサポートしているかを確認する
    • sodium_crypto_aead_aes256gcm_keygen - ランダムな AES-256-GCM 暗号化キーを生成する
    • sodium_crypto_aead_chacha20poly1305_decrypt - ChaCha20-Poly1305 を用いてメッセージを検証し、復号する
    • sodium_crypto_aead_chacha20poly1305_encrypt - ChaCha20-Poly1305 を使って暗号化し、認証を行う
    • sodium_crypto_aead_chacha20poly1305_ietf_decrypt - 暗号化されたテキストが、有効なタグを持っているかを調べる
    • sodium_crypto_aead_chacha20poly1305_ietf_encrypt - メッセージを暗号化する
    • sodium_crypto_aead_chacha20poly1305_ietf_keygen - ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する
    • sodium_crypto_aead_chacha20poly1305_keygen - ランダムな ChaCha20-Poly1305 暗号化キーを生成する
    • sodium_crypto_aead_xchacha20poly1305_ietf_decrypt - XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)
    • sodium_crypto_aead_xchacha20poly1305_ietf_encrypt - XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)
    • sodium_crypto_aead_xchacha20poly1305_ietf_keygen - ランダムな XChaCha20-Poly1305 暗号化キーを生成する
    • sodium_crypto_auth - メッセージに対応するタグを計算する
    • sodium_crypto_auth_keygen - sodium_crypto_auth で使う、ランダムな鍵を生成する
    • sodium_crypto_auth_verify - メッセージのタグが有効かどうかを検証する
    • sodium_crypto_box - 認証付きの公開鍵による暗号化
    • sodium_crypto_box_keypair - 秘密鍵と、それに対応する公開鍵をランダムに生成する
    • sodium_crypto_box_keypair_from_secretkey_and_publickey - 秘密鍵と公開鍵から、鍵ペアを生成する
    • sodium_crypto_box_open - 認証付きの公開鍵による復号
    • sodium_crypto_box_publickey - crypto_box 鍵ペアから、公開鍵を取り出す
    • sodium_crypto_box_publickey_from_secretkey - 秘密鍵から公開鍵を計算する
    • sodium_crypto_box_seal - 匿名の公開鍵暗号による暗号化
    • sodium_crypto_box_seal_open - 匿名の公開鍵暗号による復号
    • sodium_crypto_box_secretkey - crypto_box 鍵ペアから、秘密鍵を取り出す
    • sodium_crypto_box_seed_keypair - 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる
    • sodium_crypto_core_ristretto255_add - 要素を追加する
    • sodium_crypto_core_ristretto255_from_hash - ベクトルをマップする
    • sodium_crypto_core_ristretto255_is_valid_point - 座標が ristretto255 曲線上にあるかを調べる
    • sodium_crypto_core_ristretto255_random - ランダムな鍵を生成する
    • sodium_crypto_core_ristretto255_scalar_add - スカラー値を追加する
    • sodium_crypto_core_ristretto255_scalar_complement - The sodium_crypto_core_ristretto255_scalar_complement purpose
    • sodium_crypto_core_ristretto255_scalar_invert - スカラー値を反転させる
    • sodium_crypto_core_ristretto255_scalar_mul - スカラー値を乗算する
    • sodium_crypto_core_ristretto255_scalar_negate - スカラー値の論理否定を行う
    • sodium_crypto_core_ristretto255_scalar_random - ランダムな鍵を生成する
    • sodium_crypto_core_ristretto255_scalar_reduce - スカラー値を縮小する
    • sodium_crypto_core_ristretto255_scalar_sub - スカラー値を減らす
    • sodium_crypto_core_ristretto255_sub - 要素の値を減らす
    • sodium_crypto_generichash - メッセージのハッシュ値を得る
    • sodium_crypto_generichash_final - ハッシュ値を計算する
    • sodium_crypto_generichash_init - ストリーミングのためにハッシュを初期化する
    • sodium_crypto_generichash_keygen - ランダムなハッシュキーを生成する
    • sodium_crypto_generichash_update - メッセージをハッシュに追加する
    • sodium_crypto_kdf_derive_from_key - サブキーを派生させる
    • sodium_crypto_kdf_keygen - KDF インターフェイスのために、ランダムなルートキーを生成する
    • sodium_crypto_kx_client_session_keys - クライアント側のセッションキーを計算する
    • sodium_crypto_kx_keypair - 新しい sodium の鍵ペアを生成する
    • sodium_crypto_kx_publickey - crypto_kx 鍵ペアから、公開鍵を取り出す
    • sodium_crypto_kx_secretkey - crypto_kx 鍵ペアから、秘密鍵を取り出す
    • sodium_crypto_kx_seed_keypair - Description
    • sodium_crypto_kx_server_session_keys - サーバー側のセッションキーを計算する
    • sodium_crypto_pwhash - Argon2 アルゴリズムを使い、パスワードからキーを導出する
    • sodium_crypto_pwhash_scryptsalsa208sha256 - scrypt を使い、パスワードからキーを導出する
    • sodium_crypto_pwhash_scryptsalsa208sha256_str - ASCII 文字列でエンコードされたハッシュを得る
    • sodium_crypto_pwhash_scryptsalsa208sha256_str_verify - パスワードが、有効なパスワード検証文字列かを調べる
    • sodium_crypto_pwhash_str - ASCII 文字でエンコードされたハッシュ値を得る
    • sodium_crypto_pwhash_str_needs_rehash - パスワードを再計算する必要があるかを判定する
    • sodium_crypto_pwhash_str_verify - パスワードが、ハッシュ値と一致するかを調べる
    • sodium_crypto_scalarmult - ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する
    • sodium_crypto_scalarmult_base - sodium_crypto_box_publickey_from_secretkey のエイリアス
    • sodium_crypto_scalarmult_ristretto255 - 共有シークレットを計算する
    • sodium_crypto_scalarmult_ristretto255_base - 秘密鍵から公開鍵を計算する
    • sodium_crypto_secretbox - 認証付きの共有鍵による暗号化
    • sodium_crypto_secretbox_keygen - sodium_crypto_secretbox で使うランダムな鍵を生成する
    • sodium_crypto_secretbox_open - 認証付きの共有鍵による復号
    • sodium_crypto_secretstream_xchacha20poly1305_init_pull - 復号のためのシークレットストリームのコンテキストを初期化する
    • sodium_crypto_secretstream_xchacha20poly1305_init_push - 暗号化のために、シークレットストリームのコンテキストを初期化する
    • sodium_crypto_secretstream_xchacha20poly1305_keygen - ランダムなシークレットストリームのキーを生成する
    • sodium_crypto_secretstream_xchacha20poly1305_pull - 暗号化されたストリームから、データのチャンクを複号する
    • sodium_crypto_secretstream_xchacha20poly1305_push - ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する
    • sodium_crypto_secretstream_xchacha20poly1305_rekey - シークレットストリームのステート中で、鍵を入れ替える
    • sodium_crypto_shorthash - メッセージと鍵のための短いハッシュ値を計算する
    • sodium_crypto_shorthash_keygen - 鍵のためのランダムなバイト値を得る
    • sodium_crypto_sign - メッセージに署名する
    • sodium_crypto_sign_detached - メッセージに署名する
    • sodium_crypto_sign_ed25519_pk_to_curve25519 - Ed25519 公開鍵を、Curve25519 公開鍵に変換する
    • sodium_crypto_sign_ed25519_sk_to_curve25519 - Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する
    • sodium_crypto_sign_keypair - 秘密鍵と、対応する公開鍵をランダムに生成する
    • sodium_crypto_sign_keypair_from_secretkey_and_publickey - 秘密鍵と公開鍵を結合する
    • sodium_crypto_sign_open - 署名済みのメッセージが、有効な署名を持っているかを調べる
    • sodium_crypto_sign_publickey - 鍵ペアから、Ed25519 形式の公開鍵を取り出す
    • sodium_crypto_sign_publickey_from_secretkey - 秘密鍵から、Ed25519 形式の公開鍵を取り出す
    • sodium_crypto_sign_secretkey - 鍵ペアから、Ed25519 形式の秘密鍵を取り出す
    • sodium_crypto_sign_seed_keypair - 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる
    • sodium_crypto_sign_verify_detached - メッセージの署名を検証する
    • sodium_crypto_stream - シードから、結果がひとつに定まるバイト列を生成する
    • sodium_crypto_stream_keygen - sodium_crypto_stream で用いる、ランダムな鍵を生成する
    • sodium_crypto_stream_xchacha20 - 秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する
    • sodium_crypto_stream_xchacha20_keygen - ランダムな暗号化キーを生成する
    • sodium_crypto_stream_xchacha20_xor - nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)
    • sodium_crypto_stream_xchacha20_xor_ic - nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)
    • sodium_crypto_stream_xor - 認証を行わずにメッセージを暗号化する
    • sodium_hex2bin - 16進エンコードされたバイナリ文字列をデコードする
    • sodium_increment - 巨大な数をインクリメントする
    • sodium_memcmp - 定数時間での文字列の比較
    • sodium_memzero - 文字列をNUL文字で上書きする
    • sodium_pad - パディングデータを追加する
    • sodium_unpad - パディングを削除する
    • SolrClient::addDocument - Adds a document to the index
    • SolrClient::addDocuments - Adds a collection of SolrInputDocument instances to the index
    • SolrClient::commit - Finalizes all add/deletes made to the index
    • SolrClient::deleteById - Delete by Id
    • SolrClient::deleteByIds - Deletes by Ids
    • SolrClient::deleteByQueries - Removes all documents matching any of the queries
    • SolrClient::deleteByQuery - Deletes all documents matching the given query
    • SolrClient::getById - Get Document By Id. Utilizes Solr Realtime Get (RTG)
    • SolrClient::getByIds - Get Documents by their Ids. Utilizes Solr Realtime Get (RTG)
    • SolrClient::getDebug - Returns the debug data for the last connection attempt
    • SolrClient::getOptions - Returns the client options set internally
    • SolrClient::optimize - Defragments the index
    • SolrClient::ping - Checks if Solr server is still up
    • SolrClient::query - Sends a query to the server
    • SolrClient::request - Sends a raw update request
    • SolrClient::rollback - Rollbacks all add/deletes made to the index since the last commit
    • SolrClient::setResponseWriter - Sets the response writer used to prepare the response from Solr
    • SolrClient::setServlet - Changes the specified servlet type to a new value
    • SolrClient::system - Retrieve Solr Server information
    • SolrClient::threads - スレッドの状態をチェック
    • SolrClient::__construct - Constructor for the SolrClient object
    • SolrClient::__destruct - SolrClient に対するデストラクタ
    • SolrClientException::getInternalInfo - 例外がスローされた際の内部情報を返す
    • SolrCollapseFunction::getField - Returns the field that is being collapsed on
    • SolrCollapseFunction::getHint - Returns collapse hint
    • SolrCollapseFunction::getMax - Returns max parameter
    • SolrCollapseFunction::getMin - Returns min parameter
    • SolrCollapseFunction::getNullPolicy - Returns null policy
    • SolrCollapseFunction::getSize - Returns size parameter
    • SolrCollapseFunction::setField - Sets the field to collapse on
    • SolrCollapseFunction::setHint - Sets collapse hint
    • SolrCollapseFunction::setMax - Selects the group heads by the max value of a numeric field or function query
    • SolrCollapseFunction::setMin - Sets the initial size of the collapse data structures when collapsing on a numeric field only
    • SolrCollapseFunction::setNullPolicy - Sets the NULL Policy
    • SolrCollapseFunction::setSize - Sets the initial size of the collapse data structures when collapsing on a numeric field only
    • SolrCollapseFunction::__construct - Constructor
    • SolrCollapseFunction::__toString - Returns a string representing the constructed collapse function
    • SolrDisMaxQuery::addBigramPhraseField - Adds a Phrase Bigram Field (pf2 parameter)
    • SolrDisMaxQuery::addBoostQuery - Adds a boost query field with value and optional boost (bq parameter)
    • SolrDisMaxQuery::addPhraseField - Adds a Phrase Field (pf parameter)
    • SolrDisMaxQuery::addQueryField - Add a query field with optional boost (qf parameter)
    • SolrDisMaxQuery::addTrigramPhraseField - Adds a Trigram Phrase Field (pf3 parameter)
    • SolrDisMaxQuery::addUserField - Adds a field to User Fields Parameter (uf)
    • SolrDisMaxQuery::removeBigramPhraseField - Removes phrase bigram field (pf2 parameter)
    • SolrDisMaxQuery::removeBoostQuery - Removes a boost query partial by field name (bq)
    • SolrDisMaxQuery::removePhraseField - Removes a Phrase Field (pf parameter)
    • SolrDisMaxQuery::removeQueryField - Removes a Query Field (qf parameter)
    • SolrDisMaxQuery::removeTrigramPhraseField - Removes a Trigram Phrase Field (pf3 parameter)
    • SolrDisMaxQuery::removeUserField - Removes a field from The User Fields Parameter (uf)
    • SolrDisMaxQuery::setBigramPhraseFields - Sets Bigram Phrase Fields and their boosts (and slops) using pf2 parameter
    • SolrDisMaxQuery::setBigramPhraseSlop - Sets Bigram Phrase Slop (ps2 parameter)
    • SolrDisMaxQuery::setBoostFunction - Sets a Boost Function (bf parameter)
    • SolrDisMaxQuery::setBoostQuery - Directly Sets Boost Query Parameter (bq)
    • SolrDisMaxQuery::setMinimumMatch - Set Minimum "Should" Match (mm)
    • SolrDisMaxQuery::setPhraseFields - Sets Phrase Fields and their boosts (and slops) using pf2 parameter
    • SolrDisMaxQuery::setPhraseSlop - Sets the default slop on phrase queries (ps parameter)
    • SolrDisMaxQuery::setQueryAlt - Set Query Alternate (q.alt parameter)
    • SolrDisMaxQuery::setQueryPhraseSlop - Specifies the amount of slop permitted on phrase queries explicitly included in the user's query string (qf parameter)
    • SolrDisMaxQuery::setTieBreaker - Sets Tie Breaker parameter (tie parameter)
    • SolrDisMaxQuery::setTrigramPhraseFields - Directly Sets Trigram Phrase Fields (pf3 parameter)
    • SolrDisMaxQuery::setTrigramPhraseSlop - Sets Trigram Phrase Slop (ps3 parameter)
    • SolrDisMaxQuery::setUserFields - Sets User Fields parameter (uf)
    • SolrDisMaxQuery::useDisMaxQueryParser - Switch QueryParser to be DisMax Query Parser
    • SolrDisMaxQuery::useEDisMaxQueryParser - Switch QueryParser to be EDisMax
    • SolrDisMaxQuery::__construct - Class Constructor
    • SolrDocument::addField - 文書にフィールドを追加
    • SolrDocument::clear - Drops all the fields in the document
    • SolrDocument::current - 現行のフィールドを取得
    • SolrDocument::deleteField - 文書からフィールドを除去
    • SolrDocument::fieldExists - Checks if a field exists in the document
    • SolrDocument::getChildDocuments - Returns an array of child documents (SolrDocument)
    • SolrDocument::getChildDocumentsCount - Returns the number of child documents
    • SolrDocument::getField - 名前でフィールドを取得
    • SolrDocument::getFieldCount - この文書内のフィールド数を返す
    • SolrDocument::getFieldNames - 文書内のフィールド名の配列を返す
    • SolrDocument::getInputDocument - Returns a SolrInputDocument equivalent of the object
    • SolrDocument::hasChildDocuments - Checks whether the document has any child documents
    • SolrDocument::key - 現行のキーを返す
    • SolrDocument::merge - Merges source to the current SolrDocument
    • SolrDocument::next - 内部ポインタを次のフィールドに移動
    • SolrDocument::offsetExists - 特定のフィールドが存在するかどうかチェック
    • SolrDocument::offsetGet - フィールドを取得
    • SolrDocument::offsetSet - 文書にフィールドを追加
    • SolrDocument::offsetUnset - フィールドを除去
    • SolrDocument::reset - SolrDocument::clear のエイリアス
    • SolrDocument::rewind - 内部ポインタを先頭にリセット
    • SolrDocument::serialize - カスタムのシリアライズで使われます
    • SolrDocument::sort - Sorts the fields in the document
    • SolrDocument::toArray - 文書の配列表現を返す
    • SolrDocument::unserialize - Custom serialization of SolrDocument objects
    • SolrDocument::valid - Checks if the current position internally is still valid
    • SolrDocument::__clone - SolrDocument オブジェクトのコピーを作成
    • SolrDocument::__construct - コンストラクタ
    • SolrDocument::__destruct - デストラクタ
    • SolrDocument::__get - プロパティとしてフィールドにアクセス
    • SolrDocument::__isset - フィールドが存在するかチェック
    • SolrDocument::__set - Adds another field to the document
    • SolrDocument::__unset - 文書からフィールドを除去
    • SolrDocumentField::__construct - コンストラクタ
    • SolrDocumentField::__destruct - デストラクタ
    • SolrException::getInternalInfo - 例外がスローされた際の内部情報を返す
    • SolrGenericResponse::__construct - コンストラクタ
    • SolrGenericResponse::__destruct - デストラクタ
    • SolrIllegalArgumentException::getInternalInfo - 例外がスローされた際の内部情報を返す
    • SolrIllegalOperationException::getInternalInfo - 例外がスローされた際の内部情報を返す
    • SolrInputDocument::addChildDocument - Adds a child document for block indexing
    • SolrInputDocument::addChildDocuments - Adds an array of child documents
    • SolrInputDocument::addField - 文書にフィールドを追加
    • SolrInputDocument::clear - 入力した文書をリセット
    • SolrInputDocument::deleteField - 文書からフィールドを除去
    • SolrInputDocument::fieldExists - フィールドが存在するかチェック
    • SolrInputDocument::getBoost - 文書に対する現行の boost 値を取得
    • SolrInputDocument::getChildDocuments - Returns an array of child documents (SolrInputDocument)
    • SolrInputDocument::getChildDocumentsCount - Returns the number of child documents
    • SolrInputDocument::getField - 名前でフィールドを取得
    • SolrInputDocument::getFieldBoost - 特定のフィールドに対する boost 値を取得
    • SolrInputDocument::getFieldCount - 文書内のフィールド数を返す
    • SolrInputDocument::getFieldNames - 文書内のフィールドを全て含む配列を返す
    • SolrInputDocument::hasChildDocuments - Returns true if the document has any child documents
    • SolrInputDocument::merge - Merges one input document into another
    • SolrInputDocument::reset - SolrInputDocument::clear のエイリアス
    • SolrInputDocument::setBoost - この文書に対する boost 値を設定
    • SolrInputDocument::setFieldBoost - フィールドに対するインデキシング時間の boost 値を設定
    • SolrInputDocument::sort - Sorts the fields within the document
    • SolrInputDocument::toArray - 入力した文書の配列表現を返す
    • SolrInputDocument::__clone - SolrDocument のコピーを作成
    • SolrInputDocument::__construct - コンストラクタ
    • SolrInputDocument::__destruct - デストラクタ
    • SolrModifiableParams::__construct - コンストラクタ
    • SolrModifiableParams::__destruct - デストラクタ
    • SolrObject::getPropertyNames - 全てのプロパティ名の配列を返す
    • SolrObject::offsetExists - プロパティが存在するかチェック
    • SolrObject::offsetGet - プロパティを取得するために使用される
    • SolrObject::offsetSet - プロパティに対して値を設定
    • SolrObject::offsetUnset - プロパティに対して値の設定を解除
    • SolrObject::__construct - Solr オブジェクトを生成
    • SolrObject::__destruct - デストラクタ
    • SolrParams::add - SolrParams::addParam のエイリアス
    • SolrParams::addParam - オブジェクトにパラメータを追加
    • SolrParams::get - SolrParams::getParam のエイリアス
    • SolrParams::getParam - パラメータ値を返す
    • SolrParams::getParams - URL エンコードされていないパラメータの配列を返す
    • SolrParams::getPreparedParams - URL エンコードされたパラメータの配列を返す
    • SolrParams::serialize - カスタムのシリアライズで使われます
    • SolrParams::set - SolrParams::setParam のエイリアス
    • SolrParams::setParam - パラメータを指定された値に設定
    • SolrParams::toString - オブジェクト内の名前と値のペアのパラメータを全て返します
    • SolrParams::unserialize - カスタムのシリアライズで使われます
    • SolrPingResponse::getResponse - サーバーからのレスポンスを返す
    • SolrPingResponse::__construct - コンストラクタ
    • SolrPingResponse::__destruct - デストラクタ
    • SolrQuery::addExpandFilterQuery - Overrides main filter query, determines which documents to include in the main group
    • SolrQuery::addExpandSortField - Orders the documents within the expanded groups (expand.sort parameter)
    • SolrQuery::addFacetDateField - Maps to facet.date
    • SolrQuery::addFacetDateOther - Adds another facet.date.other parameter
    • SolrQuery::addFacetField - Adds another field to the facet
    • SolrQuery::addFacetQuery - Adds a facet query
    • SolrQuery::addField - Specifies which fields to return in the result
    • SolrQuery::addFilterQuery - Specifies a filter query
    • SolrQuery::addGroupField - Add a field to be used to group results
    • SolrQuery::addGroupFunction - Allows grouping results based on the unique values of a function query (group.func parameter)
    • SolrQuery::addGroupQuery - Allows grouping of documents that match the given query
    • SolrQuery::addGroupSortField - Add a group sort field (group.sort parameter)
    • SolrQuery::addHighlightField - Maps to hl.fl
    • SolrQuery::addMltField - Sets a field to use for similarity
    • SolrQuery::addMltQueryField - Maps to mlt.qf
    • SolrQuery::addSortField - Used to control how the results should be sorted
    • SolrQuery::addStatsFacet - Requests a return of sub results for values within the given facet
    • SolrQuery::addStatsField - Maps to stats.field parameter
    • SolrQuery::collapse - Collapses the result set to a single document per group
    • SolrQuery::getExpand - Returns true if group expanding is enabled
    • SolrQuery::getExpandFilterQueries - Returns the expand filter queries
    • SolrQuery::getExpandQuery - Returns the expand query expand.q parameter
    • SolrQuery::getExpandRows - Returns The number of rows to display in each group (expand.rows)
    • SolrQuery::getExpandSortFields - Returns an array of fields
    • SolrQuery::getFacet - Returns the value of the facet parameter
    • SolrQuery::getFacetDateEnd - Returns the value for the facet.date.end parameter
    • SolrQuery::getFacetDateFields - Returns all the facet.date fields
    • SolrQuery::getFacetDateGap - Returns the value of the facet.date.gap parameter
    • SolrQuery::getFacetDateHardEnd - Returns the value of the facet.date.hardend parameter
    • SolrQuery::getFacetDateOther - Returns the value for the facet.date.other parameter
    • SolrQuery::getFacetDateStart - Returns the lower bound for the first date range for all date faceting on this field
    • SolrQuery::getFacetFields - Returns all the facet fields
    • SolrQuery::getFacetLimit - Returns the maximum number of constraint counts that should be returned for the facet fields
    • SolrQuery::getFacetMethod - Returns the value of the facet.method parameter
    • SolrQuery::getFacetMinCount - Returns the minimum counts for facet fields should be included in the response
    • SolrQuery::getFacetMissing - Returns the current state of the facet.missing parameter
    • SolrQuery::getFacetOffset - Returns an offset into the list of constraints to be used for pagination
    • SolrQuery::getFacetPrefix - Returns the facet prefix
    • SolrQuery::getFacetQueries - Returns all the facet queries
    • SolrQuery::getFacetSort - Returns the facet sort type
    • SolrQuery::getFields - Returns the list of fields that will be returned in the response
    • SolrQuery::getFilterQueries - Returns an array of filter queries
    • SolrQuery::getGroup - Returns true if grouping is enabled
    • SolrQuery::getGroupCachePercent - Returns group cache percent value
    • SolrQuery::getGroupFacet - Returns the group.facet parameter value
    • SolrQuery::getGroupFields - Returns group fields (group.field parameter values)
    • SolrQuery::getGroupFormat - Returns the group.format value
    • SolrQuery::getGroupFunctions - Returns group functions (group.func parameter values)
    • SolrQuery::getGroupLimit - Returns the group.limit value
    • SolrQuery::getGroupMain - Returns the group.main value
    • SolrQuery::getGroupNGroups - Returns the group.ngroups value
    • SolrQuery::getGroupOffset - Returns the group.offset value
    • SolrQuery::getGroupQueries - Returns all the group.query parameter values
    • SolrQuery::getGroupSortFields - Returns the group.sort value
    • SolrQuery::getGroupTruncate - Returns the group.truncate value
    • SolrQuery::getHighlight - Returns the state of the hl parameter
    • SolrQuery::getHighlightAlternateField - Returns the highlight field to use as backup or default
    • SolrQuery::getHighlightFields - Returns all the fields that Solr should generate highlighted snippets for
    • SolrQuery::getHighlightFormatter - Returns the formatter for the highlighted output
    • SolrQuery::getHighlightFragmenter - Returns the text snippet generator for highlighted text
    • SolrQuery::getHighlightFragsize - Returns the number of characters of fragments to consider for highlighting
    • SolrQuery::getHighlightHighlightMultiTerm - Returns whether or not to enable highlighting for range/wildcard/fuzzy/prefix queries
    • SolrQuery::getHighlightMaxAlternateFieldLength - Returns the maximum number of characters of the field to return
    • SolrQuery::getHighlightMaxAnalyzedChars - Returns the maximum number of characters into a document to look for suitable snippets
    • SolrQuery::getHighlightMergeContiguous - Returns whether or not the collapse contiguous fragments into a single fragment
    • SolrQuery::getHighlightRegexMaxAnalyzedChars - Returns the maximum number of characters from a field when using the regex fragmenter
    • SolrQuery::getHighlightRegexPattern - Returns the regular expression for fragmenting
    • SolrQuery::getHighlightRegexSlop - Returns the deviation factor from the ideal fragment size
    • SolrQuery::getHighlightRequireFieldMatch - Returns if a field will only be highlighted if the query matched in this particular field
    • SolrQuery::getHighlightSimplePost - Returns the text which appears after a highlighted term
    • SolrQuery::getHighlightSimplePre - Returns the text which appears before a highlighted term
    • SolrQuery::getHighlightSnippets - Returns the maximum number of highlighted snippets to generate per field
    • SolrQuery::getHighlightUsePhraseHighlighter - Returns the state of the hl.usePhraseHighlighter parameter
    • SolrQuery::getMlt - Returns whether or not MoreLikeThis results should be enabled
    • SolrQuery::getMltBoost - Returns whether or not the query will be boosted by the interesting term relevance
    • SolrQuery::getMltCount - Returns the number of similar documents to return for each result
    • SolrQuery::getMltFields - Returns all the fields to use for similarity
    • SolrQuery::getMltMaxNumQueryTerms - Returns the maximum number of query terms that will be included in any generated query
    • SolrQuery::getMltMaxNumTokens - Returns the maximum number of tokens to parse in each document field that is not stored with TermVector support
    • SolrQuery::getMltMaxWordLength - Returns the maximum word length above which words will be ignored
    • SolrQuery::getMltMinDocFrequency - Returns the treshold frequency at which words will be ignored which do not occur in at least this many docs
    • SolrQuery::getMltMinTermFrequency - Returns the frequency below which terms will be ignored in the source document
    • SolrQuery::getMltMinWordLength - Returns the minimum word length below which words will be ignored
    • SolrQuery::getMltQueryFields - Returns the query fields and their boosts
    • SolrQuery::getQuery - 主なクエリーを返す
    • SolrQuery::getRows - Returns the maximum number of documents
    • SolrQuery::getSortFields - Returns all the sort fields
    • SolrQuery::getStart - Returns the offset in the complete result set
    • SolrQuery::getStats - Returns whether or not stats is enabled
    • SolrQuery::getStatsFacets - Returns all the stats facets that were set
    • SolrQuery::getStatsFields - Returns all the statistics fields
    • SolrQuery::getTerms - Returns whether or not the TermsComponent is enabled
    • SolrQuery::getTermsField - Returns the field from which the terms are retrieved
    • SolrQuery::getTermsIncludeLowerBound - Returns whether or not to include the lower bound in the result set
    • SolrQuery::getTermsIncludeUpperBound - Returns whether or not to include the upper bound term in the result set
    • SolrQuery::getTermsLimit - Returns the maximum number of terms Solr should return
    • SolrQuery::getTermsLowerBound - Returns the term to start at
    • SolrQuery::getTermsMaxCount - Returns the maximum document frequency
    • SolrQuery::getTermsMinCount - Returns the minimum document frequency to return in order to be included
    • SolrQuery::getTermsPrefix - Returns the term prefix
    • SolrQuery::getTermsReturnRaw - Whether or not to return raw characters
    • SolrQuery::getTermsSort - Returns an integer indicating how terms are sorted
    • SolrQuery::getTermsUpperBound - Returns the term to stop at
    • SolrQuery::getTimeAllowed - Returns the time in milliseconds allowed for the query to finish
    • SolrQuery::removeExpandFilterQuery - Removes an expand filter query
    • SolrQuery::removeExpandSortField - Removes an expand sort field from the expand.sort parameter
    • SolrQuery::removeFacetDateField - Removes one of the facet date fields
    • SolrQuery::removeFacetDateOther - Removes one of the facet.date.other parameters
    • SolrQuery::removeFacetField - Removes one of the facet.date parameters
    • SolrQuery::removeFacetQuery - Removes one of the facet.query parameters
    • SolrQuery::removeField - Removes a field from the list of fields
    • SolrQuery::removeFilterQuery - Removes a filter query
    • SolrQuery::removeHighlightField - Removes one of the fields used for highlighting
    • SolrQuery::removeMltField - Removes one of the moreLikeThis fields
    • SolrQuery::removeMltQueryField - Removes one of the moreLikeThis query fields
    • SolrQuery::removeSortField - Removes one of the sort fields
    • SolrQuery::removeStatsFacet - Removes one of the stats.facet parameters
    • SolrQuery::removeStatsField - Removes one of the stats.field parameters
    • SolrQuery::setEchoHandler - Toggles the echoHandler parameter
    • SolrQuery::setEchoParams - Determines what kind of parameters to include in the response
    • SolrQuery::setExpand - Enables/Disables the Expand Component
    • SolrQuery::setExpandQuery - Sets the expand.q parameter
    • SolrQuery::setExpandRows - Sets the number of rows to display in each group (expand.rows). Server Default 5
    • SolrQuery::setExplainOther - Sets the explainOther common query parameter
    • SolrQuery::setFacet - Maps to the facet parameter. Enables or disables facetting
    • SolrQuery::setFacetDateEnd - Maps to facet.date.end
    • SolrQuery::setFacetDateGap - Maps to facet.date.gap
    • SolrQuery::setFacetDateHardEnd - Maps to facet.date.hardend
    • SolrQuery::setFacetDateStart - Maps to facet.date.start
    • SolrQuery::setFacetEnumCacheMinDefaultFrequency - Sets the minimum document frequency used for determining term count
    • SolrQuery::setFacetLimit - Maps to facet.limit
    • SolrQuery::setFacetMethod - Specifies the type of algorithm to use when faceting a field
    • SolrQuery::setFacetMinCount - Maps to facet.mincount
    • SolrQuery::setFacetMissing - Maps to facet.missing
    • SolrQuery::setFacetOffset - Sets the offset into the list of constraints to allow for pagination
    • SolrQuery::setFacetPrefix - Specifies a string prefix with which to limits the terms on which to facet
    • SolrQuery::setFacetSort - Determines the ordering of the facet field constraints
    • SolrQuery::setGroup - Enable/Disable result grouping (group parameter)
    • SolrQuery::setGroupCachePercent - Enables caching for result grouping
    • SolrQuery::setGroupFacet - Sets group.facet parameter
    • SolrQuery::setGroupFormat - Sets the group format, result structure (group.format parameter)
    • SolrQuery::setGroupLimit - Specifies the number of results to return for each group. The server default value is 1
    • SolrQuery::setGroupMain - If true, the result of the first field grouping command is used as the main result list in the response, using group.format=simple
    • SolrQuery::setGroupNGroups - If true, Solr includes the number of groups that have matched the query in the results
    • SolrQuery::setGroupOffset - Sets the group.offset parameter
    • SolrQuery::setGroupTruncate - If true, facet counts are based on the most relevant document of each group matching the query
    • SolrQuery::setHighlight - Enables or disables highlighting
    • SolrQuery::setHighlightAlternateField - Specifies the backup field to use
    • SolrQuery::setHighlightFormatter - Specify a formatter for the highlight output
    • SolrQuery::setHighlightFragmenter - Sets a text snippet generator for highlighted text
    • SolrQuery::setHighlightFragsize - The size of fragments to consider for highlighting
    • SolrQuery::setHighlightHighlightMultiTerm - Use SpanScorer to highlight phrase terms
    • SolrQuery::setHighlightMaxAlternateFieldLength - Sets the maximum number of characters of the field to return
    • SolrQuery::setHighlightMaxAnalyzedChars - Specifies the number of characters into a document to look for suitable snippets
    • SolrQuery::setHighlightMergeContiguous - Whether or not to collapse contiguous fragments into a single fragment
    • SolrQuery::setHighlightRegexMaxAnalyzedChars - Specify the maximum number of characters to analyze
    • SolrQuery::setHighlightRegexPattern - Specify the regular expression for fragmenting
    • SolrQuery::setHighlightRegexSlop - Sets the factor by which the regex fragmenter can stray from the ideal fragment size
    • SolrQuery::setHighlightRequireFieldMatch - Require field matching during highlighting
    • SolrQuery::setHighlightSimplePost - Sets the text which appears after a highlighted term
    • SolrQuery::setHighlightSimplePre - Sets the text which appears before a highlighted term
    • SolrQuery::setHighlightSnippets - Sets the maximum number of highlighted snippets to generate per field
    • SolrQuery::setHighlightUsePhraseHighlighter - Whether to highlight phrase terms only when they appear within the query phrase
    • SolrQuery::setMlt - Enables or disables moreLikeThis
    • SolrQuery::setMltBoost - Set if the query will be boosted by the interesting term relevance
    • SolrQuery::setMltCount - Set the number of similar documents to return for each result
    • SolrQuery::setMltMaxNumQueryTerms - Sets the maximum number of query terms included
    • SolrQuery::setMltMaxNumTokens - Specifies the maximum number of tokens to parse
    • SolrQuery::setMltMaxWordLength - Sets the maximum word length
    • SolrQuery::setMltMinDocFrequency - Sets the mltMinDoc frequency
    • SolrQuery::setMltMinTermFrequency - Sets the frequency below which terms will be ignored in the source docs
    • SolrQuery::setMltMinWordLength - Sets the minimum word length
    • SolrQuery::setOmitHeader - Exclude the header from the returned results
    • SolrQuery::setQuery - 検索クエリーを設定
    • SolrQuery::setRows - Specifies the maximum number of rows to return in the result
    • SolrQuery::setShowDebugInfo - Flag to show debug information
    • SolrQuery::setStart - Specifies the number of rows to skip
    • SolrQuery::setStats - Enables or disables the Stats component
    • SolrQuery::setTerms - Enables or disables the TermsComponent
    • SolrQuery::setTermsField - Sets the name of the field to get the Terms from
    • SolrQuery::setTermsIncludeLowerBound - Include the lower bound term in the result set
    • SolrQuery::setTermsIncludeUpperBound - Include the upper bound term in the result set
    • SolrQuery::setTermsLimit - Sets the maximum number of terms to return
    • SolrQuery::setTermsLowerBound - Specifies the Term to start from
    • SolrQuery::setTermsMaxCount - Sets the maximum document frequency
    • SolrQuery::setTermsMinCount - Sets the minimum document frequency
    • SolrQuery::setTermsPrefix - Restrict matches to terms that start with the prefix
    • SolrQuery::setTermsReturnRaw - Return the raw characters of the indexed term
    • SolrQuery::setTermsSort - Specifies how to sort the returned terms
    • SolrQuery::setTermsUpperBound - Sets the term to stop at
    • SolrQuery::setTimeAllowed - The time allowed for search to finish
    • SolrQuery::__construct - コンストラクタ
    • SolrQuery::__destruct - デストラクタ
    • SolrQueryResponse::__construct - コンストラクタ
    • SolrQueryResponse::__destruct - デストラクタ
    • SolrResponse::getDigestedResponse - シリアライズされた PHP データとして XML レスポンスを返す
    • SolrResponse::getHttpStatus - レスポンスの HTTP ステータスを返す
    • SolrResponse::getHttpStatusMessage - HTTP ステータスに関する詳細を返す
    • SolrResponse::getRawRequest - Solr サーバーに送られた生のリクエストを返す
    • SolrResponse::getRawRequestHeaders - Solr サーバーに送られた生のリクエストヘッダを返す
    • SolrResponse::getRawResponse - Solr サーバーからの生のレスポンスを返す
    • SolrResponse::getRawResponseHeaders - Solr サーバーからの生のレスポンスヘッダを返す
    • SolrResponse::getRequestUrl - リクエストが送られた完全な URL を返す
    • SolrResponse::getResponse - サーバーからの XML レスポンスを表現する SolrObject を返す
    • SolrResponse::setParseMode - パースモードを設定
    • SolrResponse::success - リクエストが成功したか
    • SolrServerException::getInternalInfo - 例外がスローされた際の内部情報を返す
    • SolrUpdateResponse::__construct - コンストラクタ
    • SolrUpdateResponse::__destruct - デストラクタ
    • SolrUtils::digestXmlResponse - Parses an response XML string into a SolrObject
    • SolrUtils::escapeQueryChars - Escapes a lucene query string
    • SolrUtils::getSolrVersion - Solr 拡張モジュールの現行バージョンを返す
    • SolrUtils::queryPhrase - Prepares a phrase from an unescaped lucene string
    • solr_get_version - Apache Solr 拡張モジュールの現行バージョンを返す
    • sort - 配列を昇順にソートする
    • soundex - 文字列の soundex キーを計算する
    • SplDoublyLinkedList::add - 特定のインデックスに新しい値を 追加/挿入 する
    • SplDoublyLinkedList::bottom - 双方向リンクリストの最初のノードを取得する
    • SplDoublyLinkedList::count - 双方向リンクリストの要素数を数える
    • SplDoublyLinkedList::current - 現在の配列の要素を返す
    • SplDoublyLinkedList::getIteratorMode - 反復処理のモードを返す
    • SplDoublyLinkedList::isEmpty - 双方向リンクリストが空かどうかを調べる
    • SplDoublyLinkedList::key - 現在のノードのインデックスを返す
    • SplDoublyLinkedList::next - 次のエントリに移動する
    • SplDoublyLinkedList::offsetExists - 指定した $index が存在するかどうかを返す
    • SplDoublyLinkedList::offsetGet - 指定した $index の値を返す
    • SplDoublyLinkedList::offsetSet - 指定した $index の値を $value に設定する
    • SplDoublyLinkedList::offsetUnset - 指定した $index の値を削除する
    • SplDoublyLinkedList::pop - 双方向リンクリストの末尾からノードを取り出す
    • SplDoublyLinkedList::prev - 前のエントリに移動する
    • SplDoublyLinkedList::push - 双方向リンクリストの末尾に要素を追加する
    • SplDoublyLinkedList::rewind - イテレータを先頭に巻き戻す
    • SplDoublyLinkedList::serialize - ストレージをシリアライズする
    • SplDoublyLinkedList::setIteratorMode - 反復処理のモードを設定する
    • SplDoublyLinkedList::shift - 双方向リンクリストの先頭からノードを取り出す
    • SplDoublyLinkedList::top - 双方向リンクリストの最後のノードを取得する
    • SplDoublyLinkedList::unserialize - ストレージをアンシリアライズする
    • SplDoublyLinkedList::unshift - 双方向リンクリストの先頭に要素を追加する
    • SplDoublyLinkedList::valid - 双方向リンクリストにまだノードがあるかどうかを調べる
    • SplFileInfo::getATime - ファイルの最終アクセス時刻を取得する
    • SplFileInfo::getBasename - ファイルのベース名を取得する
    • SplFileInfo::getCTime - inode 変更時刻を取得する
    • SplFileInfo::getExtension - ファイルの拡張子を取得する
    • SplFileInfo::getFileInfo - ファイルの SplFileInfo オブジェクトを取得する
    • SplFileInfo::getFilename - ファイル名を取得する
    • SplFileInfo::getGroup - ファイルのグループを取得する
    • SplFileInfo::getInode - ファイルの inode を取得する
    • SplFileInfo::getLinkTarget - リンク先を取得する
    • SplFileInfo::getMTime - 最終変更時刻を取得する
    • SplFileInfo::getOwner - ファイルの所有者を取得する
    • SplFileInfo::getPath - ファイル名を除いたパスを取得する
    • SplFileInfo::getPathInfo - パスの SplFileInfo オブジェクトを取得する
    • SplFileInfo::getPathname - ファイルへのパスを取得する
    • SplFileInfo::getPerms - ファイルのパーミッションを取得する
    • SplFileInfo::getRealPath - ファイルへの絶対パスを取得する
    • SplFileInfo::getSize - ファイルサイズを取得する
    • SplFileInfo::getType - ファイルタイプを取得する
    • SplFileInfo::isDir - ファイルがディレクトリかどうかを調べる
    • SplFileInfo::isExecutable - ファイルが実行可能かどうかを調べる
    • SplFileInfo::isFile - オブジェクトの参照先が通常のファイルであるかどうかを調べる
    • SplFileInfo::isLink - ファイルがリンクであるかどうかを調べる
    • SplFileInfo::isReadable - ファイルが読み込み可能か調べる
    • SplFileInfo::isWritable - エントリが書き込み可能であるかどうかを調べる
    • SplFileInfo::openFile - ファイルの SplFileObject オブジェクトを取得する
    • SplFileInfo::setFileClass - SplFileInfo::openFile で使用するクラスを設定する
    • SplFileInfo::setInfoClass - SplFileInfo::getFileInfo および SplFileInfo::getPathInfo で使用するクラスを設定する
    • SplFileInfo::__construct - 新しい SplFileInfo オブジェクトを作成する
    • SplFileInfo::__toString - ファイルへのパスを文字列で返す
    • SplFileObject::current - ファイルの現在の行を取得する
    • SplFileObject::eof - ファイルの終端に到達しているか調べる
    • SplFileObject::fflush - 出力をファイルにフラッシュする
    • SplFileObject::fgetc - ファイルから文字を取り出す
    • SplFileObject::fgetcsv - ファイルから行を取り出し CSV フィールドとして処理する
    • SplFileObject::fgets - ファイルから 1 行取り出す
    • SplFileObject::fgetss - ファイルから 1 行取り出し HTML タグを取り除く
    • SplFileObject::flock - 簡易なファイルロックを行う
    • SplFileObject::fpassthru - ファイルポインタに残っているデータをすべて出力する
    • SplFileObject::fputcsv - フィールドの配列を CSV の行として書き出す
    • SplFileObject::fread - ファイルから読み取る
    • SplFileObject::fscanf - フォーマットに従ってファイルからの入力をパースする
    • SplFileObject::fseek - ファイルポインタを移動させる
    • SplFileObject::fstat - ファイルの情報を得る
    • SplFileObject::ftell - ファイルポインタの現在位置を返す
    • SplFileObject::ftruncate - ファイルを指定した長さに丸める
    • SplFileObject::fwrite - ファイルに書き込む
    • SplFileObject::getChildren - 用途はなし
    • SplFileObject::getCsvControl - CSV の区切り、囲み文字、エスケープ文字を取得する
    • SplFileObject::getCurrentLine - SplFileObject::fgets のエイリアス
    • SplFileObject::getFlags - SplFileObject のフラグを取得する
    • SplFileObject::getMaxLineLen - 行の最大バイト数を取得する
    • SplFileObject::hasChildren - SplFileObject は子を持ちません
    • SplFileObject::key - 行番号を取得する
    • SplFileObject::next - 次の行を読み出す
    • SplFileObject::rewind - ファイルポインタを先頭に巻き戻す
    • SplFileObject::seek - ファイルポインタを指定行に移動させる
    • SplFileObject::setCsvControl - CSV の区切り文字、囲み文字、エスケープ文字をセットする
    • SplFileObject::setFlags - SplFileObject のフラグをセットする
    • SplFileObject::setMaxLineLen - 読み込む行の最大バイト数をセットする
    • SplFileObject::valid - ファイル終端でないかチェックする
    • SplFileObject::__construct - 新しいファイルオブジェクトを作成する
    • SplFileObject::__toString - 現在の行を文字列として取得する
    • SplFixedArray::count - 配列のサイズを返す
    • SplFixedArray::current - 現在の配列の要素を返す
    • SplFixedArray::fromArray - PHP の配列を SplFixedArray インスタンスにインポートする
    • SplFixedArray::getIterator - 配列を走査するためのイテレータを取得する
    • SplFixedArray::getSize - 配列のサイズを取得する
    • SplFixedArray::jsonSerialize - JSON に変換可能な値の表現を返す
    • SplFixedArray::key - 現在の配列の添字を返す
    • SplFixedArray::next - 次のエントリに進む
    • SplFixedArray::offsetExists - 指定した添字が存在するかどうかを返す
    • SplFixedArray::offsetGet - 指定した添字の値を返す
    • SplFixedArray::offsetSet - 指定した添字の新しい値を設定する
    • SplFixedArray::offsetUnset - 指定した添字の値を消去する
    • SplFixedArray::rewind - イテレータを先頭に巻き戻す
    • SplFixedArray::setSize - 配列のサイズを変更する
    • SplFixedArray::toArray - 固定長配列から PHP の配列を返す
    • SplFixedArray::valid - 配列にまだ要素があるかどうかを調べる
    • SplFixedArray::__construct - 新しい固定長配列を作成する
    • SplFixedArray::__serialize - SplFixedArray オブジェクトをシリアライズする
    • SplFixedArray::__unserialize - data パラメータを SplFixedArray オブジェクトに復元する
    • SplFixedArray::__wakeup - アンシリアライズ後に配列を再初期化する
    • SplHeap::compare - 要素を比較し、ヒープ内の適切な位置に置く
    • SplHeap::count - ヒープ内の要素数を数える
    • SplHeap::current - イテレータが指す現在のノードを返す
    • SplHeap::extract - ヒープの先頭からノードを取り出す
    • SplHeap::insert - ヒープに要素を挿入する
    • SplHeap::isCorrupted - ヒープが壊れているかを調べる
    • SplHeap::isEmpty - ヒープが空かどうかを調べる
    • SplHeap::key - 現在のノードのインデックスを返す
    • SplHeap::next - 次のノードに移動する
    • SplHeap::recoverFromCorruption - 破壊されたヒープを復旧し、それ以降の操作をできるようにする
    • SplHeap::rewind - イテレータを先頭に巻き戻す (何もしない)
    • SplHeap::top - ヒープの先頭のノードを取り出す
    • SplHeap::valid - ヒープにまだノードがあるかどうかを調べる
    • SplMaxHeap::compare - 要素を比較し、ヒープ内の適切な位置に置く
    • SplMinHeap::compare - 要素を比較し、ヒープ内の適切な位置に置く
    • SplObjectStorage::addAll - 別のストレージからすべてのオブジェクトを追加する
    • SplObjectStorage::attach - オブジェクトをストレージに追加する
    • SplObjectStorage::contains - ストレージに特定のオブジェクトが含まれるかどうかを調べる
    • SplObjectStorage::count - ストレージ内のオブジェクトの数を返す
    • SplObjectStorage::current - 現在のストレージの要素を返す
    • SplObjectStorage::detach - オブジェクトをストレージから取り除く
    • SplObjectStorage::getHash - 中に含むオブジェクトの一意な識別子を算出する
    • SplObjectStorage::getInfo - イテレータの現在のエントリに関連づけられたデータを返す
    • SplObjectStorage::key - イテレータの現在位置を返す
    • SplObjectStorage::next - 次のエントリに移動する
    • SplObjectStorage::offsetExists - オブジェクトがストレージ内に存在するかどうかを調べる
    • SplObjectStorage::offsetGet - オブジェクトに関連づけられたデータを返す
    • SplObjectStorage::offsetSet - ストレージ内のオブジェクトにデータを関連づける
    • SplObjectStorage::offsetUnset - ストレージからオブジェクトを取り除く
    • SplObjectStorage::removeAll - 別のストレージに含まれているオブジェクトを現在のストレージから取り除く
    • SplObjectStorage::removeAllExcept - 別のストレージに含まれているもの以外のすべてのオブジェクトを現在のストレージから取り除く
    • SplObjectStorage::rewind - イテレータをストレージの最初の要素に巻き戻す
    • SplObjectStorage::serialize - ストレージをシリアライズする
    • SplObjectStorage::setInfo - イテレータの現在のエントリに関連づけるデータを設定する
    • SplObjectStorage::unserialize - ストレージの文字列表現をアンシリアライズする
    • SplObjectStorage::valid - イテレータの現在のエントリが有効かどうかを返す
    • SplObserver::update - subject の更新を受信する
    • SplPriorityQueue::compare - 要素の優先順位を比較し、ヒープ内の適切な位置に置く
    • SplPriorityQueue::count - キュー内の要素数を数える
    • SplPriorityQueue::current - イテレータが指す現在のノードを返す
    • SplPriorityQueue::extract - ヒープの先頭からノードを取り出す
    • SplPriorityQueue::getExtractFlags - 展開する時のフラグを取得する
    • SplPriorityQueue::insert - キューに要素を挿入する
    • SplPriorityQueue::isCorrupted - 優先度付きキューが壊れているかを調べる
    • SplPriorityQueue::isEmpty - キューが空かどうかを調べる
    • SplPriorityQueue::key - 現在のノードのインデックスを返す
    • SplPriorityQueue::next - 次のノードに移動する
    • SplPriorityQueue::recoverFromCorruption - 破壊されたキューを復旧し、それ以降の操作をできるようにする
    • SplPriorityQueue::rewind - イテレータを先頭に巻き戻す (何もしない)
    • SplPriorityQueue::setExtractFlags - 取り出しモードを設定する
    • SplPriorityQueue::top - キューの先頭のノードを取り出す
    • SplPriorityQueue::valid - キューにまだノードがあるかどうかを調べる
    • SplQueue::dequeue - キューからノードを取り出す
    • SplQueue::enqueue - 要素をキューに追加する
    • SplSubject::attach - SplObserver をアタッチする
    • SplSubject::detach - observer をデタッチする
    • SplSubject::notify - observer に通知する
    • SplTempFileObject::__construct - 新しい一時ファイルオブジェクトを作成する
    • spl_autoload - __autoload() のデフォルト実装
    • spl_autoload_call - 要求されたクラスを読み込むために、すべての登録済みの __autoload() 関数を試す
    • spl_autoload_extensions - spl_autoload 用のデフォルトの拡張子を登録し、それを返す
    • spl_autoload_functions - すべての登録済み __autoload() 関数を返す
    • spl_autoload_register - 指定した関数を __autoload() の実装として登録する
    • spl_autoload_unregister - 指定した関数の、__autoload() の実装としての登録を解除する
    • spl_classes - 利用可能な SPL クラスを返す
    • spl_object_hash - 指定したオブジェクトのハッシュ ID を返す
    • spl_object_id - 与えられたオブジェクトを扱う数値オブジェクトを返す
    • Spoofchecker::areConfusable - 指定された文字列が、読み手を混乱させうるかをチェックする
    • Spoofchecker::isSuspicious - 指定されたテキストに、疑わしい文字が含まれていないかをチェックする
    • Spoofchecker::setAllowedLocales - チェック時に使うロケールを設定する
    • Spoofchecker::setChecks - 実行するチェックを設定する
    • Spoofchecker::setRestrictionLevel - 制限レベルを設定する
    • Spoofchecker::__construct - コンストラクタ
    • sprintf - フォーマットされた文字列を返す
    • SQLite3::backup - あるデータベースを、別のデータベースにバックアップする
    • SQLite3::busyTimeout - 接続がビジー状態のときのハンドラを設定する
    • SQLite3::changes - 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す
    • SQLite3::close - データベースとの接続を閉じる
    • SQLite3::createAggregate - SQL の集約関数として使用する PHP 関数を登録する
    • SQLite3::createCollation - SQLのcollate関数として使うPHP関数を登録する
    • SQLite3::createFunction - SQL のスカラー関数として使用する PHP 関数を登録する
    • SQLite3::enableExceptions - 例外のスローを有効にする
    • SQLite3::escapeString - 適切にエスケープされた文字列を返す
    • SQLite3::exec - 指定したデータベースに、結果を返さないクエリを実行する
    • SQLite3::lastErrorCode - 直近で失敗した SQLite リクエストの結果コードを数値で返す
    • SQLite3::lastErrorMsg - 直近で失敗した SQLite リクエストについての英文テキストの説明を返す
    • SQLite3::lastInsertRowID - 直近の INSERT 文でデータベースに追加された行の ID を返す
    • SQLite3::loadExtension - SQLite 拡張ライブラリを読み込む
    • SQLite3::open - SQLite データベースをオープンする
    • SQLite3::openBlob - BLOB を読み取るためのストリームリソースを開く
    • SQLite3::prepare - 実行する SQL 文を準備する
    • SQLite3::query - SQL クエリを実行する
    • SQLite3::querySingle - クエリを実行し、単一の結果を返す
    • SQLite3::setAuthorizer - SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する
    • SQLite3::version - SQLite3 ライブラリのバージョンを、文字列定数と数値で返す
    • SQLite3::__construct - SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする
    • SQLite3Result::columnName - n 番目のカラムの名前を返す
    • SQLite3Result::columnType - n 番目のカラムの型を返す
    • SQLite3Result::fetchArray - 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する
    • SQLite3Result::finalize - 結果セットを閉じる
    • SQLite3Result::numColumns - 結果セットのカラム数を返す
    • SQLite3Result::reset - 結果セットを最初の行に戻す
    • SQLite3Result::__construct - SQLite3Result を構築する
    • SQLite3Stmt::bindParam - パラメータを変数にバインドする
    • SQLite3Stmt::bindValue - パラメータの値を変数にバインドする
    • SQLite3Stmt::clear - 現在バインドされているすべてのパラメータをクリアする
    • SQLite3Stmt::close - プリペアドステートメントを閉じる
    • SQLite3Stmt::execute - プリペアドステートメントを実行し、結果セットオブジェクトを返す
    • SQLite3Stmt::getSQL - ステートメントのSQLを取得する
    • SQLite3Stmt::paramCount - プリペアドステートメント内のパラメータの数を返す
    • SQLite3Stmt::readOnly - ステートメントが読み取り専用かどうかを返す
    • SQLite3Stmt::reset - プリペアドステートメントをリセットする
    • SQLite3Stmt::__construct - SQLite3Stmt オブジェクトを構築する
    • sqlsrv_begin_transaction - Begins a database transaction
    • sqlsrv_cancel - Cancels a statement
    • sqlsrv_client_info - Returns information about the client and specified connection
    • sqlsrv_close - Closes an open connection and releases resourses associated with the connection
    • sqlsrv_commit - Commits a transaction that was begun with sqlsrv_begin_transaction
    • sqlsrv_configure - Changes the driver error handling and logging configurations
    • sqlsrv_connect - Opens a connection to a Microsoft SQL Server database
    • sqlsrv_errors - Returns error and warning information about the last SQLSRV operation performed
    • sqlsrv_execute - Executes a statement prepared with sqlsrv_prepare
    • sqlsrv_fetch - Makes the next row in a result set available for reading
    • sqlsrv_fetch_array - 行を配列として返す
    • sqlsrv_fetch_object - Retrieves the next row of data in a result set as an object
    • sqlsrv_field_metadata - Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
    • sqlsrv_free_stmt - Frees all resources for the specified statement
    • sqlsrv_get_config - Returns the value of the specified configuration setting
    • sqlsrv_get_field - Gets field data from the currently selected row
    • sqlsrv_has_rows - Indicates whether the specified statement has rows
    • sqlsrv_next_result - Makes the next result of the specified statement active
    • sqlsrv_num_fields - Retrieves the number of fields (columns) on a statement
    • sqlsrv_num_rows - Retrieves the number of rows in a result set
    • sqlsrv_prepare - Prepares a query for execution
    • sqlsrv_query - Prepares and executes a query
    • sqlsrv_rollback - Rolls back a transaction that was begun with sqlsrv_begin_transaction
    • sqlsrv_rows_affected - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
    • sqlsrv_send_stream_data - Sends data from parameter streams to the server
    • sqlsrv_server_info - Returns information about the server
    • SqlStatement::bind - ステートメントのパラメータをバインドする
    • SqlStatement::execute - 操作を実行する
    • SqlStatement::getNextResult - 次の結果を取得する
    • SqlStatement::getResult - 結果を取得する
    • SqlStatement::hasMoreResults - さらに結果があるかを調べる
    • SqlStatement::__construct - SqlStatement のコンストラクタ
    • SqlStatementResult::fetchAll - 結果セットから全行取得する
    • SqlStatementResult::fetchOne - 単一の行を取得する
    • SqlStatementResult::getAffectedItemsCount - 影響を受けた行数を取得する
    • SqlStatementResult::getColumnNames - カラム名を取得する
    • SqlStatementResult::getColumns - カラムを取得する
    • SqlStatementResult::getColumnsCount - カラムの数を取得する
    • SqlStatementResult::getGeneratedIds - 生成された id を取得する
    • SqlStatementResult::getLastInsertId - 最後に挿入されたidを取得する
    • SqlStatementResult::getWarnings - 直近の操作から発生した警告を取得する
    • SqlStatementResult::getWarningsCount - 直近の操作で発生した警告の数を取得する
    • SqlStatementResult::hasData - 結果がデータを持っているかを調べる
    • SqlStatementResult::nextResult - 次の結果を取得する
    • SqlStatementResult::__construct - SqlStatementResult のコンストラクタ
    • sqrt - 平方根
    • srand - 乱数生成器を初期化する
    • sscanf - フォーマット文字列に基づき入力を処理する
    • ssdeep_fuzzy_compare - Calculates the match score between two fuzzy hash signatures
    • ssdeep_fuzzy_hash - Create a fuzzy hash from a string
    • ssdeep_fuzzy_hash_filename - Create a fuzzy hash from a file
    • ssh2_auth_agent - SSH の認証を、ssh agent を使って行う
    • ssh2_auth_hostbased_file - ホスト公開鍵を使用して認証を行う
    • ssh2_auth_none - "none" として認証する
    • ssh2_auth_password - SSH 上でプレーンなパスワードを使用した認証を行う
    • ssh2_auth_pubkey_file - 公開鍵を使用した認証を行う
    • ssh2_connect - SSH サーバーに接続する
    • ssh2_disconnect - Close a connection to a remote SSH server
    • ssh2_exec - リモートサーバー上でコマンドを実行する
    • ssh2_fetch_stream - 拡張データストリームを取得する
    • ssh2_fingerprint - リモートサーバーのフィンガープリントを処理する
    • ssh2_forward_accept - リスナーによって作られた接続を受け付ける
    • ssh2_forward_listen - リモートサーバー上のポートにバインドし、接続を待つ
    • ssh2_methods_negotiated - ネゴシエートされたメソッドのリストを返す
    • ssh2_poll - チャンネル/リスナー/ストリーム のイベントをポーリングする
    • ssh2_publickey_add - 認証済み公開鍵を追加する
    • ssh2_publickey_init - 公開鍵サブシステムを初期化する
    • ssh2_publickey_list - 現在認証済みの公開鍵の一覧を表示する
    • ssh2_publickey_remove - 認証済み公開鍵を取り除く
    • ssh2_scp_recv - SCP 経由でファイルを要求する
    • ssh2_scp_send - SCP 経由でファイルを送信する
    • ssh2_send_eof - ストリームに EOF を送信する
    • ssh2_sftp - SFTP サブシステムを初期化する
    • ssh2_sftp_chmod - ファイルのモードを変更する
    • ssh2_sftp_lstat - シンボリックリンクの情報を取得する
    • ssh2_sftp_mkdir - ディレクトリを作成する
    • ssh2_sftp_readlink - シンボリックリンクのターゲットを返す
    • ssh2_sftp_realpath - 指定されたパス文字列の実パスを解決する
    • ssh2_sftp_rename - リモートファイルを改名する
    • ssh2_sftp_rmdir - ディレクトリを削除する
    • ssh2_sftp_stat - リモートファイルシステム上のファイルの情報を取得する
    • ssh2_sftp_symlink - シンボリックリンクを作成する
    • ssh2_sftp_unlink - ファイルを削除する
    • ssh2_shell - 対話式のシェルを要求する
    • ssh2_tunnel - リモートサーバーを経由するトンネルをオープンする
    • stat - ファイルに関する情報を取得する
    • Statement::getNextResult - 次の結果を取得する
    • Statement::getResult - 結果を取得する
    • Statement::hasMoreResults - さらに結果があるかを調べる
    • Statement::__construct - Statement のコンストラクタ
    • stats_absolute_deviation - Returns the absolute deviation of an array of values
    • stats_cdf_beta - Calculates any one parameter of the beta distribution given values for the others
    • stats_cdf_binomial - Calculates any one parameter of the binomial distribution given values for the others
    • stats_cdf_cauchy - Calculates any one parameter of the Cauchy distribution given values for the others
    • stats_cdf_chisquare - Calculates any one parameter of the chi-square distribution given values for the others
    • stats_cdf_exponential - Calculates any one parameter of the exponential distribution given values for the others
    • stats_cdf_f - Calculates any one parameter of the F distribution given values for the others
    • stats_cdf_gamma - Calculates any one parameter of the gamma distribution given values for the others
    • stats_cdf_laplace - Calculates any one parameter of the Laplace distribution given values for the others
    • stats_cdf_logistic - Calculates any one parameter of the logistic distribution given values for the others
    • stats_cdf_negative_binomial - Calculates any one parameter of the negative binomial distribution given values for the others
    • stats_cdf_noncentral_chisquare - Calculates any one parameter of the non-central chi-square distribution given values for the others
    • stats_cdf_noncentral_f - Calculates any one parameter of the non-central F distribution given values for the others
    • stats_cdf_noncentral_t - Calculates any one parameter of the non-central t-distribution give values for the others
    • stats_cdf_normal - Calculates any one parameter of the normal distribution given values for the others
    • stats_cdf_poisson - Calculates any one parameter of the Poisson distribution given values for the others
    • stats_cdf_t - Calculates any one parameter of the t-distribution given values for the others
    • stats_cdf_uniform - Calculates any one parameter of the uniform distribution given values for the others
    • stats_cdf_weibull - Calculates any one parameter of the Weibull distribution given values for the others
    • stats_covariance - Computes the covariance of two data sets
    • stats_dens_beta - Probability density function of the beta distribution
    • stats_dens_cauchy - Probability density function of the Cauchy distribution
    • stats_dens_chisquare - Probability density function of the chi-square distribution
    • stats_dens_exponential - Probability density function of the exponential distribution
    • stats_dens_f - Probability density function of the F distribution
    • stats_dens_gamma - Probability density function of the gamma distribution
    • stats_dens_laplace - Probability density function of the Laplace distribution
    • stats_dens_logistic - Probability density function of the logistic distribution
    • stats_dens_normal - Probability density function of the normal distribution
    • stats_dens_pmf_binomial - Probability mass function of the binomial distribution
    • stats_dens_pmf_hypergeometric - Probability mass function of the hypergeometric distribution
    • stats_dens_pmf_negative_binomial - Probability mass function of the negative binomial distribution
    • stats_dens_pmf_poisson - Probability mass function of the Poisson distribution
    • stats_dens_t - Probability density function of the t-distribution
    • stats_dens_uniform - Probability density function of the uniform distribution
    • stats_dens_weibull - Probability density function of the Weibull distribution
    • stats_harmonic_mean - Returns the harmonic mean of an array of values
    • stats_kurtosis - Computes the kurtosis of the data in the array
    • stats_rand_gen_beta - Generates a random deviate from the beta distribution
    • stats_rand_gen_chisquare - Generates a random deviate from the chi-square distribution
    • stats_rand_gen_exponential - Generates a random deviate from the exponential distribution
    • stats_rand_gen_f - Generates a random deviate from the F distribution
    • stats_rand_gen_funiform - Generates uniform float between low (exclusive) and high (exclusive)
    • stats_rand_gen_gamma - Generates a random deviate from the gamma distribution
    • stats_rand_gen_ibinomial - Generates a random deviate from the binomial distribution
    • stats_rand_gen_ibinomial_negative - Generates a random deviate from the negative binomial distribution
    • stats_rand_gen_int - Generates random integer between 1 and 2147483562
    • stats_rand_gen_ipoisson - Generates a single random deviate from a Poisson distribution
    • stats_rand_gen_iuniform - Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)
    • stats_rand_gen_noncentral_chisquare - Generates a random deviate from the non-central chi-square distribution
    • stats_rand_gen_noncentral_f - Generates a random deviate from the noncentral F distribution
    • stats_rand_gen_noncentral_t - Generates a single random deviate from a non-central t-distribution
    • stats_rand_gen_normal - Generates a single random deviate from a normal distribution
    • stats_rand_gen_t - Generates a single random deviate from a t-distribution
    • stats_rand_get_seeds - Get the seed values of the random number generator
    • stats_rand_phrase_to_seeds - Generate two seeds for the RGN random number generator
    • stats_rand_ranf - Generates a random floating point number between 0 and 1
    • stats_rand_setall - Set seed values to the random generator
    • stats_skew - Computes the skewness of the data in the array
    • stats_standard_deviation - Returns the standard deviation
    • stats_stat_binomial_coef - Returns a binomial coefficient
    • stats_stat_correlation - Returns the Pearson correlation coefficient of two data sets
    • stats_stat_factorial - Returns the factorial of an integer
    • stats_stat_independent_t - Returns the t-value from the independent two-sample t-test
    • stats_stat_innerproduct - Returns the inner product of two vectors
    • stats_stat_paired_t - Returns the t-value of the dependent t-test for paired samples
    • stats_stat_percentile - Returns the percentile value
    • stats_stat_powersum - Returns the power sum of a vector
    • stats_variance - Returns the variance
    • Stomp::abort - Rolls back a transaction in progress
    • Stomp::ack - Acknowledges consumption of a message
    • Stomp::begin - Starts a transaction
    • Stomp::commit - Commits a transaction in progress
    • Stomp::error - Gets the last stomp error
    • Stomp::getReadTimeout - Gets read timeout
    • Stomp::getSessionId - Gets the current stomp session ID
    • Stomp::hasFrame - Indicates whether or not there is a frame ready to read
    • Stomp::readFrame - Reads the next frame
    • Stomp::send - Sends a message
    • Stomp::setReadTimeout - Sets read timeout
    • Stomp::subscribe - Registers to listen to a given destination
    • Stomp::unsubscribe - Removes an existing subscription
    • Stomp::__construct - Opens a connection
    • Stomp::__destruct - Closes stomp connection
    • StompException::getDetails - Get exception details
    • StompFrame::__construct - Constructor
    • stomp_connect_error - Returns a string description of the last connect error
    • stomp_version - Gets the current stomp extension version
    • strcasecmp - 大文字小文字を区別しないバイナリセーフな文字列比較を行う
    • strchr - strstr のエイリアス
    • strcmp - バイナリセーフな文字列比較
    • strcoll - ロケールに基づく文字列比較
    • strcspn - マスクにマッチしない最初のセグメントの長さを返す
    • streamWrapper::dir_closedir - ディレクトリハンドルを閉じる
    • streamWrapper::dir_opendir - ディレクトリハンドルをオープンする
    • streamWrapper::dir_readdir - ディレクトリハンドルからエントリを読み込む
    • streamWrapper::dir_rewinddir - ディレクトリハンドルを巻き戻す
    • streamWrapper::mkdir - ディレクトリを作成する
    • streamWrapper::rename - ファイルあるいはディレクトリの名前を変える
    • streamWrapper::rmdir - ディレクトリを削除する
    • streamWrapper::stream_cast - 元となるリソースを取得する
    • streamWrapper::stream_close - リソースを閉じる
    • streamWrapper::stream_eof - ファイルポインタが終端にあるかどうかを調べる
    • streamWrapper::stream_flush - 出力をフラッシュする
    • streamWrapper::stream_lock - ファイルのアドバイザリ・ロック
    • streamWrapper::stream_metadata - ストリームメタデータを変更する
    • streamWrapper::stream_open - ファイルあるいは URL をオープンする
    • streamWrapper::stream_read - ストリームから読み込む
    • streamWrapper::stream_seek - ストリーム内の特定の場所に移動する
    • streamWrapper::stream_set_option - ストリームのオプションを変更する
    • streamWrapper::stream_stat - ファイルリソースについての情報を取得する
    • streamWrapper::stream_tell - ストリームの現在位置を取得する
    • streamWrapper::stream_truncate - ストリームを丸める
    • streamWrapper::stream_write - ストリームに書き込む
    • streamWrapper::unlink - ファイルを削除する
    • streamWrapper::url_stat - ファイルについての情報を取得する
    • streamWrapper::__construct - 新しいストリームラッパーを作成する
    • streamWrapper::__destruct - 既存のストリームラッパーを破棄する
    • stream_bucket_append - bucket を brigade に追加する
    • stream_bucket_make_writeable - 操作する brigade から bucket オブジェクトを返す
    • stream_bucket_new - 現在のストリームで使用する新しい bucket を作成する
    • stream_bucket_prepend - bucket を brigade の先頭に追加する
    • stream_context_create - ストリームコンテキストを作成する
    • stream_context_get_default - デフォルトのストリームコンテキストを取得する
    • stream_context_get_options - ストリーム / ラッパー / コンテキストに設定されているオプションを取得する
    • stream_context_get_params - コンテキストのパラメータを取得する
    • stream_context_set_default - デフォルトのストリームコンテキストを設定する
    • stream_context_set_option - ストリーム / ラッパー / コンテキストのオプションを設定する
    • stream_context_set_options - 指定されたコンテキストのオプションを設定する
    • stream_context_set_params - ストリーム / ラッパー / コンテキストのパラメータを設定する
    • stream_copy_to_stream - データをあるストリームから別のストリームにコピーする
    • stream_filter_append - ストリームにフィルタを付加する
    • stream_filter_prepend - フィルタをストリームに付加する
    • stream_filter_register - ユーザー定義のストリームフィルタを登録する
    • stream_filter_remove - ストリームからフィルタを取り除く
    • stream_get_contents - 残りのストリームを文字列に読み込む
    • stream_get_filters - 登録されているフィルタのリストを取得する
    • stream_get_line - 指定されたデリミタの位置までのデータを一行分としてストリームから読み込む
    • stream_get_meta_data - ヘッダーあるいはメタデータをストリームまたはファイルポインタから取得する
    • stream_get_transports - 登録されたソケットのトランスポートの一覧を取得する
    • stream_get_wrappers - 登録されているストリームのラッパーのリストを取得する
    • stream_isatty - ストリームがターミナル型のデバイスかを調べる
    • stream_is_local - ローカルストリームかどうかを調べる
    • stream_notification_callback - notification コンテキストパラメータ用のコールバック関数
    • stream_register_wrapper - stream_wrapper_register のエイリアス
    • stream_resolve_include_path - インクルードパスに対してファイル名を解決する
    • stream_select - select() システムコールと同等の操作を、 ストリームの配列に対して seconds と microseconds で指定されたタイムアウト時間をもって行う
    • stream_set_blocking - ストリームのブロックモードを有効にする / 解除する
    • stream_set_chunk_size - ストリームのチャンクサイズを設定する
    • stream_set_read_buffer - 指定したストリームのファイル読み込みバッファリングを有効にする
    • stream_set_timeout - ストリームにタイムアウトを設定する
    • stream_set_write_buffer - 指定されたストリームのファイル書き込みバッファリングを有効にする
    • stream_socket_accept - stream_socket_server で作られたソケットの接続を受け入れる
    • stream_socket_client - インターネットドメインまたは Unix ドメインのソケット接続を開く
    • stream_socket_enable_crypto - 接続済みのソケットについて暗号化の on/off を切り替える
    • stream_socket_get_name - ローカルまたはリモートのソケットの名前を取得する
    • stream_socket_pair - 接続された、区別できないソケットストリームの組を作成する
    • stream_socket_recvfrom - 接続されているかどうかにかかわらず、ソケットからのデータを受信する
    • stream_socket_sendto - 接続されているかどうかにかかわらず、ソケットにデータを送信する
    • stream_socket_server - インターネットドメインまたは Unix ドメインのサーバーソケットを作成する
    • stream_socket_shutdown - 全二重接続を終了する
    • stream_supports_lock - ストリームがロックをサポートしているかどうかを調べる
    • stream_wrapper_register - PHP のクラスとして実装された URL ラッパーを登録する
    • stream_wrapper_restore - 事前に登録を解除された組み込みラッパーを復元する
    • stream_wrapper_unregister - URL ラッパーの登録を解除する
    • strftime - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
    • Stringable::__toString - オブジェクトの文字列表現を取得する
    • stripcslashes - addcslashes でクォートされた文字列をアンクォートする
    • stripos - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
    • stripslashes - クォートされた文字列のクォート部分を取り除く
    • strip_tags - 文字列から HTML および PHP タグを取り除く
    • stristr - 大文字小文字を区別しない strstr
    • strlen - 文字列の長さを得る
    • strnatcasecmp - "自然順"アルゴリズムにより大文字小文字を区別しない文字列比較を行う
    • strnatcmp - "自然順"アルゴリズムにより文字列比較を行う
    • strncasecmp - バイナリセーフで大文字小文字を区別しない文字列比較を、最初の n 文字について行う
    • strncmp - 最初の n 文字についてバイナリセーフな文字列比較を行う
    • strpbrk - 文字列の中から任意の文字を探す
    • strpos - 文字列内の部分文字列が最初に現れる場所を見つける
    • strptime - strftime が生成した日付/時刻をパースする
    • strrchr - 文字列中に文字が最後に現れる場所を取得する
    • strrev - 文字列を逆順にする
    • strripos - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
    • strrpos - 文字列中に、ある部分文字列が最後に現れる場所を探す
    • strspn - 指定したマスク内に含まれる文字からなる文字列の最初のセグメントの長さを探す
    • strstr - 文字列が最初に現れる位置を見つける
    • strtok - 文字列をトークンに分割する
    • strtolower - 文字列を小文字にする
    • strtotime - 英文形式の日付を Unix タイムスタンプに変換する
    • strtoupper - 文字列を大文字にする
    • strtr - 文字の変換あるいは部分文字列の置換を行う
    • strval - 変数の文字列としての値を取得する
    • str_contains - 指定された部分文字列が、文字列に含まれるかを調べる
    • str_decrement - 英数字からなる文字列をデクリメントする
    • str_ends_with - 文字列が、指定された文字列で終わるかを調べる。
    • str_getcsv - CSV 文字列をパースして配列に格納する
    • str_increment - 英数字からなる文字列をインクリメントする
    • str_ireplace - 大文字小文字を区別しない str_replace
    • str_pad - 文字列を固定長の他の文字列で埋める
    • str_repeat - 文字列を反復する
    • str_replace - 検索文字列に一致したすべての文字列を置換する
    • str_rot13 - 文字列に rot13 変換を行う
    • str_shuffle - 文字列をランダムにシャッフルする
    • str_split - 文字列を配列に変換する
    • str_starts_with - 文字列が指定された部分文字列で始まるかを調べる
    • str_word_count - 文字列に使用されている単語についての情報を返す
    • substr - 文字列の一部分を返す
    • substr_compare - 指定した位置から指定した長さの 2 つの文字列について、バイナリ対応で比較する
    • substr_count - 副文字列の出現回数を数える
    • substr_replace - 文字列の一部を置換する
    • SVM::crossvalidate - Test training params on subsets of the training data
    • SVM::getOptions - 現在の訓練パラメータを返す
    • SVM::setOptions - 訓練パラメータを設定
    • SVM::train - Create a SVMModel based on training data
    • SVM::__construct - SVM オブジェクトを新規構築
    • SVMModel::checkProbabilityModel - モデルが確率情報を持つ場合 TRUE を返す
    • SVMModel::getLabels - モデルが訓練されたラベルを取得
    • SVMModel::getNrClass - モデルが訓練されたクラスの個数を返す
    • SVMModel::getSvmType - モデルが訓練された SVM の種類を取得
    • SVMModel::getSvrProbability - 回帰モデルに対するσ（シグマ）値を取得
    • SVMModel::load - 保管された SVM モデルを読み込み
    • SVMModel::predict - Predict a value for previously unseen data
    • SVMModel::predict_probability - Return class probabilities for previous unseen data
    • SVMModel::save - モデルをファイルに保管
    • SVMModel::__construct - SVMModel を新規構築
    • svn_add - Schedules the addition of an item in a working directory
    • svn_auth_get_parameter - 認証パラメータを取得する
    • svn_auth_set_parameter - 認証パラメータを設定する
    • svn_blame - ファイルの SVN blame を取得する
    • svn_cat - リポジトリ内のファイルの内容を返す
    • svn_checkout - リポジトリから作業コピーをチェックアウトする
    • svn_cleanup - 作業コピーディレクトリを再帰的にクリーンアップし、中途半端な操作を解消してロックを削除する
    • svn_client_version - SVN クライアントライブラリのバージョンを返す
    • svn_commit - Sends changes from the local working copy to the repository
    • svn_delete - Delete items from a working copy or repository
    • svn_diff - ふたつのパスの差分を再帰的に取得する
    • svn_export - Export the contents of a SVN directory
    • svn_fs_abort_txn - トランザクションを中断する
    • svn_fs_apply_text - 置換に使用するストリームを作成して返す
    • svn_fs_begin_txn2 - 新しいトランザクションを作成する
    • svn_fs_change_node_prop - 成功したら true、失敗したら false を返す
    • svn_fs_check_path - 指定したリポジトリの fsroot パスにどんなアイテムが存在するかを調べる
    • svn_fs_contents_changed - コンテンツが変更されている場合に true、されていない場合に false を返す
    • svn_fs_copy - ファイルまたはディレクトリをコピーする
    • svn_fs_delete - ファイルまたはディレクトリを削除する
    • svn_fs_dir_entries - 指定したパスのディレクトリを列挙し、ディレクトリ名とファイルタイプのハッシュを返す
    • svn_fs_file_contents - 指定したバージョンの fs から、ファイルの中身を読み込むためのストリームを返す
    • svn_fs_file_length - 指定したバージョンの fs から、ファイルの長さを返す
    • svn_fs_is_dir - 指定されたパスがディレクトリかを判定する
    • svn_fs_is_file - 指定されたパスがファイルかを判定する
    • svn_fs_make_dir - 新しい空のディレクトリを作成する
    • svn_fs_make_file - 新しい空のファイルを作成する
    • svn_fs_node_created_rev - fsroot 配下のパスが作成されたリビジョンを返す
    • svn_fs_node_prop - ノードのプロパティの値を返す
    • svn_fs_props_changed - プロパティが変更されている場合に true、それ以外の場合に false を返す
    • svn_fs_revision_prop - 指定したプロパティの値を取得する
    • svn_fs_revision_root - リポジトリのルートの指定したバージョンのハンドルを取得する
    • svn_fs_txn_root - トランザクションのルートを作成して返す
    • svn_fs_youngest_rev - ファイルシステム内で一番若いリビジョン番号を返す
    • svn_import - バージョン管理されていないパスをリポジトリにインポートする
    • svn_log - 指定したリポジトリ URL のコミットログメッセージを返す
    • svn_ls - Returns list of directory contents in repository URL, optionally at revision number
    • svn_mkdir - 作業コピーあるいはリポジトリ内にディレクトリを作成する
    • svn_repos_create - 新しい subversion リポジトリを指定したパスに作成する
    • svn_repos_fs - リポジトリ用に、ファイルシステム上のハンドルを取得する
    • svn_repos_fs_begin_txn_for_commit - 新しいトランザクションを作成する
    • svn_repos_fs_commit_txn - トランザクションをコミットし、新しいリビジョンを返す
    • svn_repos_hotcopy - repospath にあるリポジトリのホットコピーを作成し、destpath にコピーする
    • svn_repos_open - Open a shared lock on a repository
    • svn_repos_recover - Run recovery procedures on the repository located at path
    • svn_revert - Revert changes to the working copy
    • svn_status - Returns the status of working copy files and directories
    • svn_update - Update working copy
    • Swoole\Async::dnsLookup - Async and non-blocking hostname to IP lookup.
    • Swoole\Async::read - Read file stream asynchronously.
    • Swoole\Async::readFile - Read a file asynchronously.
    • Swoole\Async::set - Update the async I/O options.
    • Swoole\Async::write - Write data to a file stream asynchronously.
    • Swoole\Async::writeFile - Description
    • Swoole\Atomic::add - Add a number to the value to the atomic object.
    • Swoole\Atomic::cmpset - Compare and set the value of the atomic object.
    • Swoole\Atomic::get - Get the current value of the atomic object.
    • Swoole\Atomic::set - Set a new value to the atomic object.
    • Swoole\Atomic::sub - Subtract a number to the value of the atomic object.
    • Swoole\Atomic::__construct - Construct a swoole atomic object.
    • Swoole\Buffer::append - Append the string or binary data at the end of the memory buffer and return the new size of memory allocated.
    • Swoole\Buffer::clear - Reset the memory buffer.
    • Swoole\Buffer::expand - Expand the size of memory buffer.
    • Swoole\Buffer::read - Read data from the memory buffer based on offset and length.
    • Swoole\Buffer::recycle - Release the memory to OS which is not used by the memory buffer.
    • Swoole\Buffer::substr - Read data from the memory buffer based on offset and length. Or remove data from the memory buffer.
    • Swoole\Buffer::write - Write data to the memory buffer. The memory allocated for the buffer will not be changed.
    • Swoole\Buffer::__construct - Fixed size memory blocks allocation.
    • Swoole\Buffer::__destruct - Destruct the Swoole memory buffer.
    • Swoole\Buffer::__toString - Get the string value of the memory buffer.
    • Swoole\Channel::pop - Read and pop data from swoole channel.
    • Swoole\Channel::push - Write and push data into Swoole channel.
    • Swoole\Channel::stats - Get stats of swoole channel.
    • Swoole\Channel::__construct - Construct a Swoole Channel
    • Swoole\Channel::__destruct - Destruct a Swoole channel.
    • Swoole\Client::close - Close the connection established.
    • Swoole\Client::connect - Connect to the remote TCP or UDP port.
    • Swoole\Client::getpeername - Get the remote socket name of the connection.
    • Swoole\Client::getsockname - Get the local socket name of the connection.
    • Swoole\Client::isConnected - Check if the connection is established.
    • Swoole\Client::on - Add callback functions triggered by events.
    • Swoole\Client::pause - Pause receiving data.
    • Swoole\Client::pipe - Redirect the data to another file descriptor.
    • Swoole\Client::recv - Receive data from the remote socket.
    • Swoole\Client::resume - Resume receiving data.
    • Swoole\Client::send - Send data to the remote TCP socket.
    • Swoole\Client::sendfile - Send file to the remote TCP socket.
    • Swoole\Client::sendto - Send data to the remote UDP address.
    • Swoole\Client::set - Set the Swoole client parameters before the connection is established.
    • Swoole\Client::sleep - Remove the TCP client from system event loop.
    • Swoole\Client::wakeup - Add the TCP client back into the system event loop.
    • Swoole\Client::__construct - Create Swoole sync or async TCP/UDP client, with or without SSL.
    • Swoole\Client::__destruct - Destruct the Swoole client.
    • Swoole\Connection\Iterator::count - Count connections.
    • Swoole\Connection\Iterator::current - Return current connection entry.
    • Swoole\Connection\Iterator::key - Return key of the current connection.
    • Swoole\Connection\Iterator::next - Move to the next connection.
    • Swoole\Connection\Iterator::offsetExists - Check if offet exists.
    • Swoole\Connection\Iterator::offsetGet - Offset to retrieve.
    • Swoole\Connection\Iterator::offsetSet - Assign a Connection to the specified offset.
    • Swoole\Connection\Iterator::offsetUnset - Unset an offset.
    • Swoole\Connection\Iterator::rewind - Rewinds iterator
    • Swoole\Connection\Iterator::valid - Check if current position is valid.
    • Swoole\Coroutine::call_user_func - Call a callback given by the first parameter
    • Swoole\Coroutine::call_user_func_array - Call a callback with an array of parameters
    • Swoole\Coroutine::cli_wait - Description
    • Swoole\Coroutine::create - Description
    • Swoole\Coroutine::getuid - Description
    • Swoole\Coroutine::resume - Description
    • Swoole\Coroutine::suspend - Description
    • Swoole\Coroutine\Client::close - Description
    • Swoole\Coroutine\Client::connect - Description
    • Swoole\Coroutine\Client::getpeername - Description
    • Swoole\Coroutine\Client::getsockname - Description
    • Swoole\Coroutine\Client::isConnected - Description
    • Swoole\Coroutine\Client::recv - Description
    • Swoole\Coroutine\Client::send - Description
    • Swoole\Coroutine\Client::sendfile - Description
    • Swoole\Coroutine\Client::sendto - Description
    • Swoole\Coroutine\Client::set - Description
    • Swoole\Coroutine\Client::__construct - Description
    • Swoole\Coroutine\Client::__destruct - Description
    • Swoole\Coroutine\Http\Client::addFile - Description
    • Swoole\Coroutine\Http\Client::close - Description
    • Swoole\Coroutine\Http\Client::execute - Description
    • Swoole\Coroutine\Http\Client::get - Description
    • Swoole\Coroutine\Http\Client::getDefer - Description
    • Swoole\Coroutine\Http\Client::isConnected - Description
    • Swoole\Coroutine\Http\Client::post - Description
    • Swoole\Coroutine\Http\Client::recv - Description
    • Swoole\Coroutine\Http\Client::set - Description
    • Swoole\Coroutine\Http\Client::setCookies - Description
    • Swoole\Coroutine\Http\Client::setData - Description
    • Swoole\Coroutine\Http\Client::setDefer - Description
    • Swoole\Coroutine\Http\Client::setHeaders - Description
    • Swoole\Coroutine\Http\Client::setMethod - Description
    • Swoole\Coroutine\Http\Client::__construct - Description
    • Swoole\Coroutine\Http\Client::__destruct - Description
    • Swoole\Coroutine\MySQL::close - Description
    • Swoole\Coroutine\MySQL::connect - Description
    • Swoole\Coroutine\MySQL::getDefer - Description
    • Swoole\Coroutine\MySQL::query - Description
    • Swoole\Coroutine\MySQL::recv - Description
    • Swoole\Coroutine\MySQL::setDefer - Description
    • Swoole\Coroutine\MySQL::__construct - Description
    • Swoole\Coroutine\MySQL::__destruct - Description
    • Swoole\Event::add - Add new callback functions of a socket into the EventLoop.
    • Swoole\Event::defer - Add a callback function to the next event loop.
    • Swoole\Event::del - Remove all event callback functions of a socket.
    • Swoole\Event::exit - Exit the eventloop, only available at client side.
    • Swoole\Event::set - Update the event callback functions of a socket.
    • Swoole\Event::wait - Description
    • Swoole\Event::write - Write data to the socket.
    • Swoole\Http\Client::addFile - Add a file to the post form.
    • Swoole\Http\Client::close - Close the http connection.
    • Swoole\Http\Client::download - Download a file from the remote server.
    • Swoole\Http\Client::execute - Send the HTTP request after setting the parameters.
    • Swoole\Http\Client::get - Send GET http request to the remote server.
    • Swoole\Http\Client::isConnected - Check if the HTTP connection is connected.
    • Swoole\Http\Client::on - Register callback function by event name.
    • Swoole\Http\Client::post - Send POST http request to the remote server.
    • Swoole\Http\Client::push - Push data to websocket client.
    • Swoole\Http\Client::set - Update the HTTP client parameters.
    • Swoole\Http\Client::setCookies - Set the http request cookies.
    • Swoole\Http\Client::setData - Set the HTTP request body data.
    • Swoole\Http\Client::setHeaders - Set the HTTP request headers.
    • Swoole\Http\Client::setMethod - Set the HTTP request method.
    • Swoole\Http\Client::upgrade - Upgrade to websocket protocol.
    • Swoole\Http\Client::__construct - Construct the async HTTP client.
    • Swoole\Http\Client::__destruct - Destruct the HTTP client.
    • Swoole\Http\Request::rawcontent - Get the raw HTTP POST body.
    • Swoole\Http\Request::__destruct - Destruct the HTTP request.
    • Swoole\Http\Response::cookie - Set the cookies of the HTTP response.
    • Swoole\Http\Response::end - Send data for the HTTP request and finish the response.
    • Swoole\Http\Response::gzip - Enable the gzip of response content.
    • Swoole\Http\Response::header - Set the HTTP response headers.
    • Swoole\Http\Response::initHeader - Init the HTTP response header.
    • Swoole\Http\Response::rawcookie - Set the raw cookies to the HTTP response.
    • Swoole\Http\Response::sendfile - Send file through the HTTP response.
    • Swoole\Http\Response::status - Set the status code of the HTTP response.
    • Swoole\Http\Response::write - Append HTTP body content to the HTTP response.
    • Swoole\Http\Response::__destruct - Destruct the HTTP response.
    • Swoole\Http\Server::on - Bind callback function to HTTP server by event name.
    • Swoole\Http\Server::start - Start the swoole http server.
    • Swoole\Lock::lock - Try to acquire the lock. It will block if the lock is not available.
    • Swoole\Lock::lock_read - Lock a read-write lock for reading.
    • Swoole\Lock::trylock - Try to acquire the lock and return straight away even the lock is not available.
    • Swoole\Lock::trylock_read - Try to lock a read-write lock for reading and return straight away even the lock is not available.
    • Swoole\Lock::unlock - Release the lock.
    • Swoole\Lock::__construct - Construct a memory lock.
    • Swoole\Lock::__destruct - Destory a Swoole memory lock.
    • Swoole\Mmap::open - Map a file into memory and return the stream resource which can be used by PHP stream operations.
    • Swoole\MySQL::close - Close the async MySQL connection.
    • Swoole\MySQL::connect - Connect to the remote MySQL server.
    • Swoole\MySQL::getBuffer - Description
    • Swoole\MySQL::on - Register callback function based on event name.
    • Swoole\MySQL::query - Run the SQL query.
    • Swoole\MySQL::__construct - Construct an async MySQL client.
    • Swoole\MySQL::__destruct - Destory the async MySQL client.
    • Swoole\Process::alarm - High precision timer which triggers signal with fixed interval.
    • Swoole\Process::close - Close the pipe to the child process.
    • Swoole\Process::daemon - Change the process to be a daemon process.
    • Swoole\Process::exec - Execute system commands.
    • Swoole\Process::exit - Stop the child processes.
    • Swoole\Process::freeQueue - Destroy the message queue created by swoole_process::useQueue.
    • Swoole\Process::kill - Send signal to the child process.
    • Swoole\Process::name - Set name of the process.
    • Swoole\Process::pop - Read and pop data from the message queue.
    • Swoole\Process::push - Write and push data into the message queue.
    • Swoole\Process::read - Read data sending to the process.
    • Swoole\Process::signal - Send signal to the child processes.
    • Swoole\Process::start - Start the process.
    • Swoole\Process::statQueue - Get the stats of the message queue used as the communication method between processes.
    • Swoole\Process::useQueue - Create a message queue as the communication method between the parent process and child processes.
    • Swoole\Process::wait - Wait for the events of child processes.
    • Swoole\Process::write - Write data into the pipe and communicate with the parent process or child processes.
    • Swoole\Process::__construct - Construct a process.
    • Swoole\Process::__destruct - Destroy the process.
    • Swoole\Redis\Server::format - Description
    • Swoole\Redis\Server::setHandler - Description
    • Swoole\Redis\Server::start - Description
    • Swoole\Serialize::pack - Serialize the data.
    • Swoole\Serialize::unpack - Unserialize the data.
    • Swoole\Server::addlistener - Add a new listener to the server.
    • Swoole\Server::addProcess - Add a user defined swoole_process to the server.
    • Swoole\Server::after - Trigger a callback function after a period of time.
    • Swoole\Server::bind - Bind the connection to a user defined user ID.
    • Swoole\Server::clearTimer - Stop and destroy a timer.
    • Swoole\Server::close - Close a connection to the client.
    • Swoole\Server::confirm - Check status of the connection.
    • Swoole\Server::connection_info - Get the connection info by file description.
    • Swoole\Server::connection_list - Get all of the established connections.
    • Swoole\Server::defer - Delay execution of the callback function at the end of current EventLoop.
    • Swoole\Server::exist - Check if the connection is existed.
    • Swoole\Server::finish - Used in task process for sending result to the worker process when the task is finished.
    • Swoole\Server::getClientInfo - Get the connection info by file description.
    • Swoole\Server::getClientList - Get all of the established connections.
    • Swoole\Server::getLastError - Get the error code of the most recent error.
    • Swoole\Server::heartbeat - Check all the connections on the server.
    • Swoole\Server::listen - Listen on the given IP and port, socket type.
    • Swoole\Server::on - Register a callback function by event name.
    • Swoole\Server::pause - Stop receiving data from the connection.
    • Swoole\Server::protect - Set the connection to be protected mode.
    • Swoole\Server::reload - Restart all the worker process.
    • Swoole\Server::resume - Start receving data from the connection.
    • Swoole\Server::send - Send data to the client.
    • Swoole\Server::sendfile - Send file to the connection.
    • Swoole\Server::sendMessage - Send message to worker processes by ID.
    • Swoole\Server::sendto - Send data to the remote UDP address.
    • Swoole\Server::sendwait - Send data to the remote socket in the blocking way.
    • Swoole\Server::set - Set the runtime settings of the swoole server.
    • Swoole\Server::shutdown - Shutdown the master server process, this function can be called in worker processes.
    • Swoole\Server::start - Start the Swoole server.
    • Swoole\Server::stats - Get the stats of the Swoole server.
    • Swoole\Server::stop - Stop the Swoole server.
    • Swoole\Server::task - Send data to the task worker processes.
    • Swoole\Server::taskwait - Send data to the task worker processes in blocking way.
    • Swoole\Server::taskWaitMulti - Execute multiple tasks concurrently.
    • Swoole\Server::tick - Repeats a given function at every given time-interval.
    • Swoole\Server::__construct - Construct a Swoole server.
    • Swoole\Server\Port::on - Register callback functions by event.
    • Swoole\Server\Port::set - Set protocol of the server port.
    • Swoole\Server\Port::__construct - Construct a server port
    • Swoole\Server\Port::__destruct - Destory server port
    • Swoole\Table::column - Set the data type and size of the columns.
    • Swoole\Table::count - Count the rows in the table, or count all the elements in the table if $mode = 1.
    • Swoole\Table::create - Create the swoole memory table.
    • Swoole\Table::current - Get the current row.
    • Swoole\Table::decr - Decrement the value in the Swoole table by $row_key and $column_key.
    • Swoole\Table::del - Delete a row in the Swoole table by $row_key.
    • Swoole\Table::destroy - Destroy the Swoole table.
    • Swoole\Table::exist - Check if a row is existed by $row_key.
    • Swoole\Table::get - Get the value in the Swoole table by $row_key and $column_key.
    • Swoole\Table::incr - Increment the value by $row_key and $column_key.
    • Swoole\Table::key - Get the key of current row.
    • Swoole\Table::next - Iterator the next row.
    • Swoole\Table::rewind - Rewind the iterator.
    • Swoole\Table::set - Update a row of the table by $row_key.
    • Swoole\Table::valid - Check if the current row is valid.
    • Swoole\Table::__construct - Construct a Swoole memory table with fixed size.
    • Swoole\Timer::after - Trigger a callback function after a period of time.
    • Swoole\Timer::clear - Delete a timer by timer ID.
    • Swoole\Timer::exists - Check if a timer is existed.
    • Swoole\Timer::tick - Repeats a given function at every given time-interval.
    • Swoole\WebSocket\Server::exist - Check if the file descriptor exists.
    • Swoole\WebSocket\Server::on - Register event callback function
    • Swoole\WebSocket\Server::pack - Get a pack of binary data to send in a single frame.
    • Swoole\WebSocket\Server::push - Push data to the remote client.
    • Swoole\WebSocket\Server::unpack - Unpack the binary data received from the client.
    • swoole_async_dns_lookup - Async and non-blocking hostname to IP lookup
    • swoole_async_read - Read file stream asynchronously
    • swoole_async_readfile - Read a file asynchronously
    • swoole_async_set - Update the async I/O options
    • swoole_async_write - Write data to a file stream asynchronously
    • swoole_async_writefile - Write data to a file asynchronously
    • swoole_clear_error - Clear errors in the socket or on the last error code
    • swoole_client_select - Get the file description which are ready to read/write or error
    • swoole_cpu_num - Get the number of CPU
    • swoole_errno - Get the error code of the latest system call
    • swoole_error_log - Output error messages to the log
    • swoole_event_add - Add new callback functions of a socket into the EventLoop
    • swoole_event_defer - Add callback function to the next event loop
    • swoole_event_del - Remove all event callback functions of a socket
    • swoole_event_exit - Exit the eventloop, only available at the client side
    • swoole_event_set - Update the event callback functions of a socket
    • swoole_event_wait - Start the event loop
    • swoole_event_write - Write data to a socket
    • swoole_get_local_ip - Get the IPv4 IP addresses of each NIC on the machine
    • swoole_last_error - Get the lastest error message
    • swoole_load_module - Load a swoole extension
    • swoole_select - Select the file descriptions which are ready to read/write or error in the eventloop
    • swoole_set_process_name - Set the process name
    • swoole_strerror - Convert the Errno into error messages
    • swoole_timer_after - Trigger a one time callback function in the future
    • swoole_timer_exists - Check if a timer callback function is existed
    • swoole_timer_tick - Trigger a timer tick callback function by time interval
    • swoole_version - Get the version of Swoole
    • symlink - シンボリックリンクを作成する
    • SyncEvent::fire - Fires/sets the event
    • SyncEvent::reset - Resets a manual event
    • SyncEvent::wait - Waits for the event to be fired/set
    • SyncEvent::__construct - Constructs a new SyncEvent object
    • SyncMutex::lock - Waits for an exclusive lock
    • SyncMutex::unlock - Unlocks the mutex
    • SyncMutex::__construct - Constructs a new SyncMutex object
    • SyncReaderWriter::readlock - Waits for a read lock
    • SyncReaderWriter::readunlock - Releases a read lock
    • SyncReaderWriter::writelock - Waits for an exclusive write lock
    • SyncReaderWriter::writeunlock - Releases a write lock
    • SyncReaderWriter::__construct - Constructs a new SyncReaderWriter object
    • SyncSemaphore::lock - Decreases the count of the semaphore or waits
    • SyncSemaphore::unlock - Increases the count of the semaphore
    • SyncSemaphore::__construct - Constructs a new SyncSemaphore object
    • SyncSharedMemory::first - Check to see if the object is the first instance system-wide of named shared memory
    • SyncSharedMemory::read - Copy data from named shared memory
    • SyncSharedMemory::size - Returns the size of the named shared memory
    • SyncSharedMemory::write - Copy data to named shared memory
    • SyncSharedMemory::__construct - Constructs a new SyncSharedMemory object
    • syslog - システムログのメッセージを生成する
    • system - 外部プログラムを実行し、出力を表示する
    • sys_getloadavg - システムの平均負荷を取得する
    • sys_get_temp_dir - 一時ファイル用に使用されるディレクトリのパスを返す
  • t
    • Table::count - 行の数を取得する
    • Table::delete - テーブルから行を削除する
    • Table::existsInDatabase - テーブルがデータベースに存在するかをチェックする
    • Table::getName - テーブル名を取得する
    • Table::getSchema - テーブルスキーマを取得する
    • Table::getSession - テーブルを操作するためのセッションを取得する
    • Table::insert - テーブルに行を挿入する
    • Table::isView - テーブルがビューかどうかを調べる
    • Table::select - テーブルから行を選択する
    • Table::update - テーブルの行を更新する
    • Table::__construct - Table のコンストラクタ
    • TableDelete::bind - delete のクエリパラメータをバインドする
    • TableDelete::execute - delete文を実行する
    • TableDelete::limit - 削除する行を限定する
    • TableDelete::orderby - 削除の際のソート条件を設定する
    • TableDelete::where - 削除時の検索条件を設定する
    • TableDelete::__construct - TableDelete のコンストラクタ
    • TableInsert::execute - insert クエリを実行する
    • TableInsert::values - 挿入する行の値を追加する
    • TableInsert::__construct - TableInsert クラスのコンストラクタ
    • TableSelect::bind - select のクエリパラメータをバインドする
    • TableSelect::execute - select ステートメントを実行する
    • TableSelect::groupBy - select 時のグループ化の条件を設定する
    • TableSelect::having - select 句の having 条件を設定する
    • TableSelect::limit - 選択される行の数を限定する
    • TableSelect::lockExclusive - EXCLUSIVE LOCK を実行する
    • TableSelect::lockShared - SHARED LOCK を実行する
    • TableSelect::offset - スキップするoffsetを設定する
    • TableSelect::orderby - select 文のソート条件を設定する
    • TableSelect::where - select 文の検索条件を設定する
    • TableSelect::__construct - TableSelect のコンストラクタ
    • TableUpdate::bind - update のクエリパラメータをバインドする
    • TableUpdate::execute - update クエリを実行する
    • TableUpdate::limit - 更新する行の数を限定する
    • TableUpdate::orderby - ソート条件を設定する
    • TableUpdate::set - 更新されるフィールドを追加する
    • TableUpdate::where - 検索フィルタを設定する
    • TableUpdate::__construct - TableUpdate のコンストラクタ
    • taint - 文字列を汚染させる
    • tan - 正接（タンジェント）
    • tanh - 双曲線正接（ハイパボリックタンジェント）
    • tcpwrap_check - tcpwrap のチェックを実行する
    • tempnam - 一意なファイル名を生成する
    • textdomain - デフォルトドメインを設定する
    • Thread::getCreatorId - 識別
    • Thread::getCurrentThread - Identification
    • Thread::getCurrentThreadId - Identification
    • Thread::getThreadId - 識別
    • Thread::isJoined - 状態を検出する
    • Thread::isStarted - 状態を検出する
    • Thread::join - 同期処理
    • Thread::start - 実行する
    • Threaded::chunk - Manipulation
    • Threaded::count - Manipulation
    • Threaded::extend - Runtime Manipulation
    • Threaded::isRunning - State Detection
    • Threaded::isTerminated - State Detection
    • Threaded::merge - Manipulation
    • Threaded::notify - Synchronization
    • Threaded::notifyOne - Synchronization
    • Threaded::pop - Manipulation
    • Threaded::run - Execution
    • Threaded::shift - Manipulation
    • Threaded::synchronized - Synchronization
    • Threaded::wait - Synchronization
    • Throwable::getCode - 例外コードを取得する
    • Throwable::getFile - オブジェクトが作られたファイル名を取得する
    • Throwable::getLine - オブジェクトのインスタンスが作られた行番号を取得する
    • Throwable::getMessage - メッセージを取得する
    • Throwable::getPrevious - ひとつ前の Throwable を返す
    • Throwable::getTrace - スタックトレースを取得する
    • Throwable::getTraceAsString - スタックトレースを文字列として取得する
    • Throwable::__toString - スローされたオブジェクトの文字列表現を取得する
    • tidy::$errorBuffer - 指定したドキュメントのパースで発生した警告とエラーを返す
    • tidy::body - Tidy パースツリーの <body> タグから始まる tidyNode オブジェクトを返す
    • tidy::cleanRepair - パースされたマークアップに設定に基く誤りの修正を行う
    • tidy::diagnose - パース、修正されたマークアップの診断を行う
    • tidy::getConfig - 現在の Tidy の設定を取得する
    • tidy::getHtmlVer - 指定したドキュメントで検出された HTML バージョンを取得する
    • tidy::getOpt - Tidy ドキュメントについて指定した設定オプションの値を返す
    • tidy::getOptDoc - 与えられたオプション名に対するドキュメントを返す
    • tidy::getRelease - Tidy ライブラリのリリース日 (バージョン) を取得する
    • tidy::getStatus - 指定したドキュメントのステータスを取得する
    • tidy::head - Tidy パースツリーの <head> タグから始まる tidyNode オブジェクトを返す
    • tidy::html - Tidy パースツリーの <html> タグから始まる tidyNode オブジェクトを返す
    • tidy::isXhtml - ドキュメントが XHTML ドキュメントかどうかを示す
    • tidy::isXml - ドキュメントが一般的な XML ドキュメント (非 HTML/XHTML) かどうかを示す
    • tidy::parseFile - ファイルまたは URI にあるマークアップをパースする
    • tidy::parseString - 文字列にストアされたドキュメントをパースする
    • tidy::repairFile - ファイルを修正し、それを文字列として返す
    • tidy::repairString - 別途提供される設定ファイルを使用して文字列を修正する
    • tidy::root - Tidy パースツリーのルートを表す tidyNode を返す
    • tidy::__construct - 新しい tidy オブジェクトを作成する
    • tidyNode::getParent - カレントノードの親ノードを返す
    • tidyNode::hasChildren - ノードが子を持つかどうかを調べる
    • tidyNode::hasSiblings - このノードが兄弟ノードを持つかどうかを調べる
    • tidyNode::isAsp - このノードが ASP かどうかを調べる
    • tidyNode::isComment - このノードがコメントを表すものかどうかを調べる
    • tidyNode::isHtml - このノードが HTML要素 であるかどうかを調べる
    • tidyNode::isJste - このノードが JSTE であるかどうかを調べる
    • tidyNode::isPhp - このノードが PHP であるかどうかを調べる
    • tidyNode::isText - このノードが (マークアップでない) テキストであるかどうかを調べる
    • tidyNode::__construct - private なコンストラクタのため、直接インスタンス化できません
    • tidy_access_count - 指定したドキュメントについて発生したTidyアクセシビリティ警告の数を返す
    • tidy_config_count - 指定したドキュメントについて発生した Tidy 設定エラーの数を返す
    • tidy_error_count - 指定したドキュメントについて発生した Tidy エラーの数を返す
    • tidy_get_output - パースされた Tidy マークアップを表す文字列を返す
    • tidy_warning_count - 指定したドキュメントについて発生した Tidy 警告の数を返す
    • time - 現在の Unix タイムスタンプを返す
    • timezone_abbreviations_list - DateTimeZone::listAbbreviations のエイリアス
    • timezone_identifiers_list - DateTimeZone::listIdentifiers のエイリアス
    • timezone_location_get - DateTimeZone::getLocation のエイリアス
    • timezone_name_from_abbr - 略称とUTCオフセットから、タイムゾーン名を推測して返す
    • timezone_name_get - DateTimeZone::getName のエイリアス
    • timezone_offset_get - DateTimeZone::getOffset のエイリアス
    • timezone_open - DateTimeZone::__construct のエイリアス
    • timezone_transitions_get - DateTimeZone::getTransitions のエイリアス
    • timezone_version_get - timezonedb のバージョンを取得する
    • time_nanosleep - 秒およびナノ秒単位で実行を遅延する
    • time_sleep_until - 指定した時刻まで実行を遅延する
    • tmpfile - テンポラリファイルを作成する
    • token_get_all - 指定したソースを PHP トークンに分割する
    • token_name - 指定した PHP トークンのシンボル名を取得する
    • touch - ファイルの最終アクセス時刻および最終更新日をセットする
    • trader_acos - Vector Trigonometric ACos
    • trader_ad - Chaikin A/D Line
    • trader_add - Vector Arithmetic Add
    • trader_adosc - Chaikin A/D Oscillator
    • trader_adx - Average Directional Movement Index
    • trader_adxr - Average Directional Movement Index Rating
    • trader_apo - Absolute Price Oscillator
    • trader_aroon - Aroon
    • trader_aroonosc - Aroon Oscillator
    • trader_asin - Vector Trigonometric ASin
    • trader_atan - Vector Trigonometric ATan
    • trader_atr - Average True Range
    • trader_avgprice - Average Price
    • trader_bbands - Bollinger Bands
    • trader_beta - Beta
    • trader_bop - Balance Of Power
    • trader_cci - Commodity Channel Index
    • trader_cdl2crows - Two Crows
    • trader_cdl3blackcrows - Three Black Crows
    • trader_cdl3inside - Three Inside Up/Down
    • trader_cdl3linestrike - Three-Line Strike
    • trader_cdl3outside - Three Outside Up/Down
    • trader_cdl3starsinsouth - Three Stars In The South
    • trader_cdl3whitesoldiers - Three Advancing White Soldiers
    • trader_cdlabandonedbaby - Abandoned Baby
    • trader_cdladvanceblock - Advance Block
    • trader_cdlbelthold - Belt-hold
    • trader_cdlbreakaway - Breakaway
    • trader_cdlclosingmarubozu - Closing Marubozu
    • trader_cdlconcealbabyswall - Concealing Baby Swallow
    • trader_cdlcounterattack - Counterattack
    • trader_cdldarkcloudcover - Dark Cloud Cover
    • trader_cdldoji - Doji
    • trader_cdldojistar - Doji Star
    • trader_cdldragonflydoji - Dragonfly Doji
    • trader_cdlengulfing - Engulfing Pattern
    • trader_cdleveningdojistar - Evening Doji Star
    • trader_cdleveningstar - Evening Star
    • trader_cdlgapsidesidewhite - Up/Down-gap side-by-side white lines
    • trader_cdlgravestonedoji - Gravestone Doji
    • trader_cdlhammer - Hammer
    • trader_cdlhangingman - Hanging Man
    • trader_cdlharami - Harami Pattern
    • trader_cdlharamicross - Harami Cross Pattern
    • trader_cdlhighwave - High-Wave Candle
    • trader_cdlhikkake - Hikkake Pattern
    • trader_cdlhikkakemod - Modified Hikkake Pattern
    • trader_cdlhomingpigeon - Homing Pigeon
    • trader_cdlidentical3crows - Identical Three Crows
    • trader_cdlinneck - In-Neck Pattern
    • trader_cdlinvertedhammer - Inverted Hammer
    • trader_cdlkicking - Kicking
    • trader_cdlkickingbylength - Kicking - bull/bear determined by the longer marubozu
    • trader_cdlladderbottom - Ladder Bottom
    • trader_cdllongleggeddoji - Long Legged Doji
    • trader_cdllongline - Long Line Candle
    • trader_cdlmarubozu - Marubozu
    • trader_cdlmatchinglow - Matching Low
    • trader_cdlmathold - Mat Hold
    • trader_cdlmorningdojistar - Morning Doji Star
    • trader_cdlmorningstar - Morning Star
    • trader_cdlonneck - On-Neck Pattern
    • trader_cdlpiercing - Piercing Pattern
    • trader_cdlrickshawman - Rickshaw Man
    • trader_cdlrisefall3methods - Rising/Falling Three Methods
    • trader_cdlseparatinglines - Separating Lines
    • trader_cdlshootingstar - Shooting Star
    • trader_cdlshortline - Short Line Candle
    • trader_cdlspinningtop - Spinning Top
    • trader_cdlstalledpattern - Stalled Pattern
    • trader_cdlsticksandwich - Stick Sandwich
    • trader_cdltakuri - Takuri (Dragonfly Doji with very long lower shadow)
    • trader_cdltasukigap - Tasuki Gap
    • trader_cdlthrusting - Thrusting Pattern
    • trader_cdltristar - Tristar Pattern
    • trader_cdlunique3river - Unique 3 River
    • trader_cdlupsidegap2crows - Upside Gap Two Crows
    • trader_cdlxsidegap3methods - Upside/Downside Gap Three Methods
    • trader_ceil - Vector Ceil
    • trader_cmo - Chande Momentum Oscillator
    • trader_correl - Pearson's Correlation Coefficient (r)
    • trader_cos - Vector Trigonometric Cos
    • trader_cosh - Vector Trigonometric Cosh
    • trader_dema - Double Exponential Moving Average
    • trader_div - Vector Arithmetic Div
    • trader_dx - Directional Movement Index
    • trader_ema - Exponential Moving Average
    • trader_errno - Get error code
    • trader_exp - Vector Arithmetic Exp
    • trader_floor - Vector Floor
    • trader_get_compat - Get compatibility mode
    • trader_get_unstable_period - Get unstable period
    • trader_ht_dcperiod - Hilbert Transform - Dominant Cycle Period
    • trader_ht_dcphase - Hilbert Transform - Dominant Cycle Phase
    • trader_ht_phasor - Hilbert Transform - Phasor Components
    • trader_ht_sine - Hilbert Transform - SineWave
    • trader_ht_trendline - Hilbert Transform - Instantaneous Trendline
    • trader_ht_trendmode - Hilbert Transform - Trend vs Cycle Mode
    • trader_kama - Kaufman Adaptive Moving Average
    • trader_linearreg - Linear Regression
    • trader_linearreg_angle - Linear Regression Angle
    • trader_linearreg_intercept - Linear Regression Intercept
    • trader_linearreg_slope - Linear Regression Slope
    • trader_ln - Vector Log Natural
    • trader_log10 - Vector Log10
    • trader_ma - Moving average
    • trader_macd - Moving Average Convergence/Divergence
    • trader_macdext - MACD with controllable MA type
    • trader_macdfix - Moving Average Convergence/Divergence Fix 12/26
    • trader_mama - MESA Adaptive Moving Average
    • trader_mavp - Moving average with variable period
    • trader_max - Highest value over a specified period
    • trader_maxindex - Index of highest value over a specified period
    • trader_medprice - Median Price
    • trader_mfi - Money Flow Index
    • trader_midpoint - MidPoint over period
    • trader_midprice - Midpoint Price over period
    • trader_min - Lowest value over a specified period
    • trader_minindex - Index of lowest value over a specified period
    • trader_minmax - Lowest and highest values over a specified period
    • trader_minmaxindex - Indexes of lowest and highest values over a specified period
    • trader_minus_di - Minus Directional Indicator
    • trader_minus_dm - Minus Directional Movement
    • trader_mom - Momentum
    • trader_mult - Vector Arithmetic Mult
    • trader_natr - Normalized Average True Range
    • trader_obv - On Balance Volume
    • trader_plus_di - Plus Directional Indicator
    • trader_plus_dm - Plus Directional Movement
    • trader_ppo - Percentage Price Oscillator
    • trader_roc - Rate of change : ((price/prevPrice)-1)*100
    • trader_rocp - Rate of change Percentage: (price-prevPrice)/prevPrice
    • trader_rocr - Rate of change ratio: (price/prevPrice)
    • trader_rocr100 - Rate of change ratio 100 scale: (price/prevPrice)*100
    • trader_rsi - Relative Strength Index
    • trader_sar - Parabolic SAR
    • trader_sarext - Parabolic SAR - Extended
    • trader_set_compat - Set compatibility mode
    • trader_set_unstable_period - Set unstable period
    • trader_sin - Vector Trigonometric Sin
    • trader_sinh - Vector Trigonometric Sinh
    • trader_sma - Simple Moving Average
    • trader_sqrt - Vector Square Root
    • trader_stddev - Standard Deviation
    • trader_stoch - Stochastic
    • trader_stochf - Stochastic Fast
    • trader_stochrsi - Stochastic Relative Strength Index
    • trader_sub - Vector Arithmetic Subtraction
    • trader_sum - Summation
    • trader_t3 - Triple Exponential Moving Average (T3)
    • trader_tan - Vector Trigonometric Tan
    • trader_tanh - Vector Trigonometric Tanh
    • trader_tema - Triple Exponential Moving Average
    • trader_trange - True Range
    • trader_trima - Triangular Moving Average
    • trader_trix - 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
    • trader_tsf - Time Series Forecast
    • trader_typprice - Typical Price
    • trader_ultosc - Ultimate Oscillator
    • trader_var - Variance
    • trader_wclprice - Weighted Close Price
    • trader_willr - Williams' %R
    • trader_wma - Weighted Moving Average
    • trait_exists - トレイトが存在するかどうかを調べる
    • Transliterator::create - Transliterator を作成する
    • Transliterator::createFromRules - 規則に基づいた Transliterator を作成する
    • Transliterator::createInverse - 逆方向の Transliterator を作成する
    • Transliterator::getErrorCode - 直近のエラーコードを取得する
    • Transliterator::getErrorMessage - 直近のエラーメッセージを取得する
    • Transliterator::listIDs - Transliterator の ID を取得する
    • Transliterator::transliterate - 文字列を音訳する
    • Transliterator::__construct - インスタンス化を拒否するために private にしたコンストラクタ
    • trigger_error - ユーザーレベルのエラー/警告/通知メッセージを生成する
    • trim - 文字列の先頭および末尾にあるホワイトスペースを取り除く
  • u
    • uasort - ユーザー定義の比較関数で配列をソートし、連想インデックスを保持する
    • ucfirst - 文字列の最初の文字を大文字にする
    • UConverter::convert - ある文字セットから別の文字セットに文字列を変換する
    • UConverter::fromUCallback - デフォルトの "from" コールバック関数
    • UConverter::getAliases - 指定した名前のエイリアスを取得する
    • UConverter::getAvailable - 利用可能なコンバーター名を取得する
    • UConverter::getDestinationEncoding - 変換先エンコーディングを取得する
    • UConverter::getDestinationType - 変換先のコンバーターの型を取得する
    • UConverter::getErrorCode - 直近のエラーコードを取得する
    • UConverter::getErrorMessage - 直近のエラーメッセージを取得する
    • UConverter::getSourceEncoding - 変換元エンコーディングを取得する
    • UConverter::getSourceType - 変換元のコンバーターの型を取得する
    • UConverter::getStandards - コンバーター名に対応する標準を取得する
    • UConverter::getSubstChars - 置換文字を取得する
    • UConverter::reasonText - コールバックの理由を表す文字列を取得する
    • UConverter::setDestinationEncoding - 変換先エンコーディングを設定する
    • UConverter::setSourceEncoding - 変換元エンコーディングを設定する
    • UConverter::setSubstChars - 置換文字を設定する
    • UConverter::toUCallback - デフォルトの "to" コールバック関数
    • UConverter::transcode - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
    • UConverter::__construct - UConverter オブジェクトを作る
    • ucwords - 文字列の各単語の最初の文字を大文字にする
    • UI\Area::onDraw - Draw Callback
    • UI\Area::onKey - Key Callback
    • UI\Area::onMouse - Mouse Callback
    • UI\Area::redraw - Redraw Area
    • UI\Area::scrollTo - Area Scroll
    • UI\Area::setSize - Set Size
    • UI\Control::destroy - Destroy Control
    • UI\Control::disable - Disable Control
    • UI\Control::enable - Enable Control
    • UI\Control::getParent - Get Parent Control
    • UI\Control::getTopLevel - Get Top Level
    • UI\Control::hide - Hide Control
    • UI\Control::isEnabled - Determine if Control is enabled
    • UI\Control::isVisible - Determine if Control is visible
    • UI\Control::setParent - Set Parent Control
    • UI\Control::show - Control Show
    • UI\Controls\Box::append - Append Control
    • UI\Controls\Box::delete - Delete Control
    • UI\Controls\Box::getOrientation - Get Orientation
    • UI\Controls\Box::isPadded - Padding Detection
    • UI\Controls\Box::setPadded - Set Padding
    • UI\Controls\Box::__construct - Construct a new Box
    • UI\Controls\Button::getText - Get Text
    • UI\Controls\Button::onClick - Click Handler
    • UI\Controls\Button::setText - Set Text
    • UI\Controls\Button::__construct - Construct a new Button
    • UI\Controls\Check::getText - Get Text
    • UI\Controls\Check::isChecked - Checked Detection
    • UI\Controls\Check::onToggle - Toggle Callback
    • UI\Controls\Check::setChecked - Set Checked
    • UI\Controls\Check::setText - Set Text
    • UI\Controls\Check::__construct - Construct a new Check
    • UI\Controls\ColorButton::getColor - Get Color
    • UI\Controls\ColorButton::onChange - Change Handler
    • UI\Controls\ColorButton::setColor - Set Color
    • UI\Controls\Combo::append - Append Option
    • UI\Controls\Combo::getSelected - Get Selected Option
    • UI\Controls\Combo::onSelected - Selected Handler
    • UI\Controls\Combo::setSelected - Set Selected Option
    • UI\Controls\EditableCombo::append - Append Option
    • UI\Controls\EditableCombo::getText - Get Text
    • UI\Controls\EditableCombo::onChange - Change Handler
    • UI\Controls\EditableCombo::setText - Set Text
    • UI\Controls\Entry::getText - Get Text
    • UI\Controls\Entry::isReadOnly - Detect Read Only
    • UI\Controls\Entry::onChange - Change Handler
    • UI\Controls\Entry::setReadOnly - Set Read Only
    • UI\Controls\Entry::setText - Set Text
    • UI\Controls\Entry::__construct - Construct a new Entry
    • UI\Controls\Form::append - Append Control
    • UI\Controls\Form::delete - Delete Control
    • UI\Controls\Form::isPadded - Padding Detection
    • UI\Controls\Form::setPadded - Set Padding
    • UI\Controls\Grid::append - Append Control
    • UI\Controls\Grid::isPadded - Padding Detection
    • UI\Controls\Grid::setPadded - Set Padding
    • UI\Controls\Group::append - Append Control
    • UI\Controls\Group::getTitle - Get Title
    • UI\Controls\Group::hasMargin - Margin Detection
    • UI\Controls\Group::setMargin - Set Margin
    • UI\Controls\Group::setTitle - Set Title
    • UI\Controls\Group::__construct - Construct a new Group
    • UI\Controls\Label::getText - Get Text
    • UI\Controls\Label::setText - Set Text
    • UI\Controls\Label::__construct - Construct a new Label
    • UI\Controls\MultilineEntry::append - Append Text
    • UI\Controls\MultilineEntry::getText - Get Text
    • UI\Controls\MultilineEntry::isReadOnly - Read Only Detection
    • UI\Controls\MultilineEntry::onChange - Change Handler
    • UI\Controls\MultilineEntry::setReadOnly - Set Read Only
    • UI\Controls\MultilineEntry::setText - Set Text
    • UI\Controls\MultilineEntry::__construct - Construct a new Multiline Entry
    • UI\Controls\Picker::__construct - Construct a new Picker
    • UI\Controls\Progress::getValue - Get Value
    • UI\Controls\Progress::setValue - Set Value
    • UI\Controls\Radio::append - Append Option
    • UI\Controls\Radio::getSelected - Get Selected Option
    • UI\Controls\Radio::onSelected - Selected Handler
    • UI\Controls\Radio::setSelected - Set Selected Option
    • UI\Controls\Separator::__construct - Construct a new Separator
    • UI\Controls\Slider::getValue - Get Value
    • UI\Controls\Slider::onChange - Change Handler
    • UI\Controls\Slider::setValue - Set Value
    • UI\Controls\Slider::__construct - Construct a new Slider
    • UI\Controls\Spin::getValue - Get Value
    • UI\Controls\Spin::onChange - Change Handler
    • UI\Controls\Spin::setValue - Set Value
    • UI\Controls\Spin::__construct - Construct a new Spin
    • UI\Controls\Tab::append - Append Page
    • UI\Controls\Tab::delete - Delete Page
    • UI\Controls\Tab::hasMargin - Margin Detection
    • UI\Controls\Tab::insertAt - Insert Page
    • UI\Controls\Tab::pages - Page Count
    • UI\Controls\Tab::setMargin - Set Margin
    • UI\Draw\Brush::getColor - Get Color
    • UI\Draw\Brush::setColor - Set Color
    • UI\Draw\Brush::__construct - Construct a new Brush
    • UI\Draw\Brush\Gradient::addStop - Stop Manipulation
    • UI\Draw\Brush\Gradient::delStop - Stop Manipulation
    • UI\Draw\Brush\Gradient::setStop - Stop Manipulation
    • UI\Draw\Brush\LinearGradient::__construct - Construct a Linear Gradient
    • UI\Draw\Brush\RadialGradient::__construct - Construct a new Radial Gradient
    • UI\Draw\Color::getChannel - Color Manipulation
    • UI\Draw\Color::setChannel - Color Manipulation
    • UI\Draw\Color::__construct - Construct new Color
    • UI\Draw\Matrix::invert - Invert Matrix
    • UI\Draw\Matrix::isInvertible - Invertible Detection
    • UI\Draw\Matrix::multiply - Multiply Matrix
    • UI\Draw\Matrix::rotate - Rotate Matrix
    • UI\Draw\Matrix::scale - Scale Matrix
    • UI\Draw\Matrix::skew - Skew Matrix
    • UI\Draw\Matrix::translate - Translate Matrix
    • UI\Draw\Path::addRectangle - Draw a Rectangle
    • UI\Draw\Path::arcTo - Draw an Arc
    • UI\Draw\Path::bezierTo - Draw Bezier Curve
    • UI\Draw\Path::closeFigure - Close Figure
    • UI\Draw\Path::end - Finalize Path
    • UI\Draw\Path::lineTo - Draw a Line
    • UI\Draw\Path::newFigure - Draw Figure
    • UI\Draw\Path::newFigureWithArc - Draw Figure with Arc
    • UI\Draw\Path::__construct - Construct a new Path
    • UI\Draw\Pen::clip - Clip a Path
    • UI\Draw\Pen::fill - Fill a Path
    • UI\Draw\Pen::restore - Restore
    • UI\Draw\Pen::save - Save
    • UI\Draw\Pen::stroke - Stroke a Path
    • UI\Draw\Pen::transform - Matrix Transform
    • UI\Draw\Pen::write - Draw Text at Point
    • UI\Draw\Stroke::getCap - Get Line Cap
    • UI\Draw\Stroke::getJoin - Get Line Join
    • UI\Draw\Stroke::getMiterLimit - Get Miter Limit
    • UI\Draw\Stroke::getThickness - Get Thickness
    • UI\Draw\Stroke::setCap - Set Line Cap
    • UI\Draw\Stroke::setJoin - Set Line Join
    • UI\Draw\Stroke::setMiterLimit - Set Miter Limit
    • UI\Draw\Stroke::setThickness - Set Thickness
    • UI\Draw\Stroke::__construct - Construct a new Stroke
    • UI\Draw\Text\Font::getAscent - Font Metrics
    • UI\Draw\Text\Font::getDescent - Font Metrics
    • UI\Draw\Text\Font::getLeading - Font Metrics
    • UI\Draw\Text\Font::getUnderlinePosition - Font Metrics
    • UI\Draw\Text\Font::getUnderlineThickness - Font Metrics
    • UI\Draw\Text\Font::__construct - Construct a new Font
    • UI\Draw\Text\Font\Descriptor::getFamily - Get Font Family
    • UI\Draw\Text\Font\Descriptor::getItalic - Style Detection
    • UI\Draw\Text\Font\Descriptor::getSize - Size Detection
    • UI\Draw\Text\Font\Descriptor::getStretch - Style Detection
    • UI\Draw\Text\Font\Descriptor::getWeight - Weight Detection
    • UI\Draw\Text\Font\Descriptor::__construct - Construct a new Font Descriptor
    • UI\Draw\Text\Font\fontFamilies - Retrieve Font Families
    • UI\Draw\Text\Layout::setColor - Set Color
    • UI\Draw\Text\Layout::setWidth - Set Width
    • UI\Draw\Text\Layout::__construct - Construct a new Text Layout
    • UI\Executor::kill - Stop Executor
    • UI\Executor::onExecute - Execution Callback
    • UI\Executor::setInterval - Interval Manipulation
    • UI\Executor::__construct - Construct a new Executor
    • UI\Menu::append - Append Menu Item
    • UI\Menu::appendAbout - Append About Menu Item
    • UI\Menu::appendCheck - Append Checkable Menu Item
    • UI\Menu::appendPreferences - Append Preferences Menu Item
    • UI\Menu::appendQuit - Append Quit Menu Item
    • UI\Menu::appendSeparator - Append Menu Item Separator
    • UI\Menu::__construct - Construct a new Menu
    • UI\MenuItem::disable - Disable Menu Item
    • UI\MenuItem::enable - Enable Menu Item
    • UI\MenuItem::isChecked - Detect Checked
    • UI\MenuItem::onClick - On Click Callback
    • UI\MenuItem::setChecked - Set Checked
    • UI\Point::at - Size Coercion
    • UI\Point::getX - Retrieves X
    • UI\Point::getY - Retrieves Y
    • UI\Point::setX - Set X
    • UI\Point::setY - Set Y
    • UI\Point::__construct - Construct a new Point
    • UI\quit - Quit UI Loop
    • UI\run - Enter UI Loop
    • UI\Size::getHeight - Retrieves Height
    • UI\Size::getWidth - Retrives Width
    • UI\Size::of - Point Coercion
    • UI\Size::setHeight - Set Height
    • UI\Size::setWidth - Set Width
    • UI\Size::__construct - Construct a new Size
    • UI\Window::add - Add a Control
    • UI\Window::error - Show Error Box
    • UI\Window::getSize - Get Window Size
    • UI\Window::getTitle - Get Title
    • UI\Window::hasBorders - Border Detection
    • UI\Window::hasMargin - Margin Detection
    • UI\Window::isFullScreen - Full Screen Detection
    • UI\Window::msg - Show Message Box
    • UI\Window::onClosing - Closing Callback
    • UI\Window::open - Open Dialog
    • UI\Window::save - Save Dialog
    • UI\Window::setBorders - Border Use
    • UI\Window::setFullScreen - Full Screen Use
    • UI\Window::setMargin - Margin Use
    • UI\Window::setSize - Set Size
    • UI\Window::setTitle - Window Title
    • UI\Window::__construct - Construct a new Window
    • uksort - ユーザー定義の比較関数を用いて、キーで配列をソートする
    • umask - 現在の umask を変更する
    • uniqid - 時刻ベースの識別子を生成する
    • UnitEnum::cases - 列挙型の case 一覧を生成する
    • unixtojd - Unix タイムスタンプをユリウス歴に変換する
    • unlink - ファイルを削除する
    • unpack - バイナリ文字列からデータを切り出す
    • unregister_tick_function - 各 tick の実行用の関数の登録を解除する
    • unserialize - 保存用表現から PHP の値を生成する
    • unset - 指定した変数の割当を解除する
    • untaint - 文字列の汚染を除去する
    • uopz_add_function - Adds non-existent function or method
    • uopz_allow_exit - Allows control over disabled exit opcode
    • uopz_backup - Backup a function
    • uopz_compose - Compose a class
    • uopz_copy - Copy a function
    • uopz_delete - Delete a function
    • uopz_del_function - Deletes previously added function or method
    • uopz_extend - 実行時にクラスを継承させる
    • uopz_flags - 関数またはクラスのフラグを 取得/設定 する
    • uopz_function - Creates a function at runtime
    • uopz_get_exit_status - Retrieve the last set exit status
    • uopz_get_hook - Gets previously set hook on function or method
    • uopz_get_mock - Get the current mock for a class
    • uopz_get_property - Gets value of class or instance property
    • uopz_get_return - Gets a previous set return value for a function
    • uopz_get_static - 関数またはメソッドスコープから、static変数を取得する
    • uopz_implement - 実行時にインターフェイスを実装させる
    • uopz_overload - Overload a VM opcode
    • uopz_redefine - 定数を再定義
    • uopz_rename - Rename a function at runtime
    • uopz_restore - Restore a previously backed up function
    • uopz_set_hook - Sets hook to execute when entering a function or method
    • uopz_set_mock - 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う
    • uopz_set_property - Sets value of existing class or instance property
    • uopz_set_return - Provide a return value for an existing function
    • uopz_set_static - Sets the static variables in function or method scope
    • uopz_undefine - 定数を未定義化
    • uopz_unset_hook - Removes previously set hook on function or method
    • uopz_unset_mock - 以前に設定したモックを削除する
    • uopz_unset_return - Unsets a previously set return value for a function
    • urldecode - URL エンコードされた文字列をデコードする
    • urlencode - 文字列を URL エンコードする
    • user_error - trigger_error のエイリアス
    • use_soap_error_handler - SOAP エラーハンドラを使用するかどうかを設定する
    • usleep - マイクロ秒単位で実行を遅延する
    • usort - ユーザー定義の比較関数を使用して、配列を値でソートする
    • utf8_decode - UTF-8 エンコードされた文字列を、ISO-8859-1 に変換し、表現できない文字を置換する
    • utf8_encode - ISO-8859-1 文字列を UTF-8 に変換する
  • v
    • V8Js::executeString - 文字列を JavaScript のコードとして実行する
    • V8Js::getExtensions - 登録された拡張の配列を返す
    • V8Js::getPendingException - キャッチされなかった JavaScript 例外の中で未処理のものを返す
    • V8Js::registerExtension - V8Js で使う JavaScript の拡張を登録する
    • V8Js::__construct - 新しい V8Js オブジェクトを作成する
    • V8JsException::getJsFileName - getJsFileName
    • V8JsException::getJsLineNumber - getJsLineNumber
    • V8JsException::getJsSourceLine - getJsSourceLine
    • V8JsException::getJsTrace - getJsTrace
    • variant::__construct - variant クラスのコンストラクタ
    • variant_abs - variant の絶対値を返す
    • variant_add - 2 つの variant 値を「加算」し、結果を返す
    • variant_and - 2 つの variant の論理積を計算し、結果を返す
    • variant_cast - variant を、別の型の新しい variant に変換する
    • variant_cat - 2 つの variant 値を連結し、その結果を返す
    • variant_cmp - 2 つの variant を比較する
    • variant_date_from_timestamp - Unix タイムスタンプを、日付形式の variant で返す
    • variant_date_to_timestamp - 日付/時刻の variant 値を Unix タイムスタンプに変換する
    • variant_div - 2 つの variant の除算結果を返す
    • variant_eqv - 2 つの variant のビット値が等しいかどうかを調べる
    • variant_fix - variant の整数部を返す
    • variant_get_type - variant オブジェクトの型を返す
    • variant_idiv - variants を整数に変換し、除算の結果を返す
    • variant_imp - 2 つの variant のビット implication を行う
    • variant_int - variant の整数部を返す
    • variant_mod - 2 つの variant の除算を行い、剰余を返す
    • variant_mul - 2 つの variant の乗算を行い、その結果を返す
    • variant_neg - variant の論理否定演算を行う
    • variant_not - variant のビット否定演算を行う
    • variant_or - 2 つの variant の論理和を計算する
    • variant_pow - 2 つの variant の累乗計算を行い、その結果を返す
    • variant_round - 指定した桁で variant を丸める
    • variant_set - variant オブジェクトに新しい値を代入する
    • variant_set_type - variant を「その場で」別の型に変換する
    • variant_sub - 左の variant から右の variant を引き、その結果を返す
    • variant_xor - 2 つの variant の排他的論理和を計算する
    • VarnishAdmin::auth - varnish インスタンス上で認証する
    • VarnishAdmin::ban - VCL の式を使って URL を禁止する
    • VarnishAdmin::banUrl - VCL の式を使って URL を禁止する
    • VarnishAdmin::clearPanic - varnish インスタンスのパニックメッセージをクリアする
    • VarnishAdmin::connect - varnish インスタンスの管理インターフェイスに接続する
    • VarnishAdmin::disconnect - varnish インスタンスの管理インターフェイスとの接続を切断する
    • VarnishAdmin::getPanic - varnish インスタンスの直近のパニックメッセージを取得する
    • VarnishAdmin::getParams - 現在の varnish インスタンスの設定パラメータを取得する
    • VarnishAdmin::isRunning - varnish のスレーブプロセスが現在実行中かどうかを調べる
    • VarnishAdmin::setCompat - クラスのオプション compat を設定する
    • VarnishAdmin::setHost - クラスのオプション host を設定する
    • VarnishAdmin::setIdent - クラスのオプション ident を設定する
    • VarnishAdmin::setParam - 現在の varnish インスタンスの構成パラメータを設定する
    • VarnishAdmin::setPort - クラスのオプション port を設定する
    • VarnishAdmin::setSecret - クラスのオプション secret を設定する
    • VarnishAdmin::setTimeout - クラスのオプション timeout を設定する
    • VarnishAdmin::start - varnish ワーカープロセスを開始する
    • VarnishAdmin::stop - varnish ワーカープロセスを停止する
    • VarnishAdmin::__construct - VarnishAdmin のコンストラクタ
    • VarnishLog::getLine - ログの次の行を取得する
    • VarnishLog::getTagName - ログのタグ文字列を、インデックスから取得する
    • VarnishLog::__construct - Varnishlog のコンストラクタ
    • VarnishStat::getSnapshot - 現在の varnish インスタンスの統計スナップショットを取得する
    • VarnishStat::__construct - VarnishStat のコンストラクタ
    • var_dump - 変数に関する情報をダンプする
    • var_export - 変数の文字列表現を出力または返す
    • var_representation - Returns a short, readable, parsable string representation of a variable
    • version_compare - ふたつの "PHP 標準" バージョン番号文字列を比較する
    • vfprintf - フォーマットされた文字列をストリームに書き込む
    • virtual - Apache サブリクエストを実行する
    • vprintf - フォーマットされた文字列を出力する
    • vsprintf - フォーマットされた文字列を返す
    • Vtiful\Kernel\Excel::addSheet - Vtiful\Kernel\Excel addSheet
    • Vtiful\Kernel\Excel::autoFilter - Vtiful\Kernel\Excel autoFilter
    • Vtiful\Kernel\Excel::constMemory - Vtiful\Kernel\Excel constMemory
    • Vtiful\Kernel\Excel::data - Vtiful\Kernel\Excel data
    • Vtiful\Kernel\Excel::fileName - Vtiful\Kernel\Excel fileName
    • Vtiful\Kernel\Excel::getHandle - Vtiful\Kernel\Excel getHandle
    • Vtiful\Kernel\Excel::header - Vtiful\Kernel\Excel header
    • Vtiful\Kernel\Excel::insertFormula - Vtiful\Kernel\Excel insertFormula
    • Vtiful\Kernel\Excel::insertImage - Vtiful\Kernel\Excel insertImage
    • Vtiful\Kernel\Excel::insertText - Vtiful\Kernel\Excel insertText
    • Vtiful\Kernel\Excel::mergeCells - Vtiful\Kernel\Excel mergeCells
    • Vtiful\Kernel\Excel::output - Vtiful\Kernel\Excel output
    • Vtiful\Kernel\Excel::setColumn - Vtiful\Kernel\Excel setColumn
    • Vtiful\Kernel\Excel::setRow - Vtiful\Kernel\Excel setRow
    • Vtiful\Kernel\Excel::__construct - Vtiful\Kernel\Excel constructor
    • Vtiful\Kernel\Format::align - Vtiful\Kernel\Format align
    • Vtiful\Kernel\Format::bold - Vtiful\Kernel\Format bold
    • Vtiful\Kernel\Format::italic - Vtiful\Kernel\Format italic
    • Vtiful\Kernel\Format::underline - Vtiful\Kernel\Format underline
  • w
    • Warning::__construct - Warning のコンストラクタ
    • wddx_add_vars - 指定した ID の WDDX パケットに変数を追加する
    • wddx_deserialize - WDDX パケットをアンシリアライズする
    • wddx_packet_end - 指定した ID の WDDX パケットを終了する
    • wddx_packet_start - 新規の WDDX パケットを内部の構造体を用いて開始する
    • wddx_serialize_value - 単一の値を WDDX パケットにシリアライズする
    • wddx_serialize_vars - 変数を WDDX パケットにシリアライズする
    • WeakMap::count - マップ内に存在する有効なエントリの数を数える
    • WeakMap::getIterator - イテレータを取得する
    • WeakMap::offsetExists - あるオブジェクトがマップ内に存在するかを調べる
    • WeakMap::offsetGet - オブジェクトが指す値を返す
    • WeakMap::offsetSet - 新しいキーと値でマップを更新する
    • WeakMap::offsetUnset - マップからエントリを削除する
    • WeakReference::create - 弱い参照を生成する
    • WeakReference::get - 弱く参照されたオブジェクトを取得する
    • WeakReference::__construct - コンストラクタを使ってインスタンス化はできません
    • win32_continue_service - 中断したサービスを再開する
    • win32_create_service - SCM データベースに新しいサービスのエントリを作成する
    • win32_delete_service - SCM データベースからサービスのエントリを削除する
    • win32_get_last_control_message - サービスに送信された直近の制御メッセージを返す
    • win32_pause_service - サービスを中断する
    • win32_query_service_status - サービスの状態を問い合わせる
    • win32_send_custom_control - Send a custom control to the service
    • win32_set_service_exit_code - Define or return the exit code for the current running service
    • win32_set_service_exit_mode - Define or return the exit mode for the current running service
    • win32_set_service_status - サービスの状態を更新する
    • win32_start_service - サービスを開始する
    • win32_start_service_ctrl_dispatcher - スクリプトを SCM に登録し、指定した名前でサービスとして稼動させる ようにする
    • win32_stop_service - サービスを停止する
    • 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 - 指定したキーの排他ロックを解放する
    • wkhtmltox\Image\Converter::convert - Perform Image conversion
    • wkhtmltox\Image\Converter::getVersion - Determine version of Converter
    • wkhtmltox\Image\Converter::__construct - Create a new Image converter
    • wkhtmltox\PDF\Converter::add - Add an object for conversion
    • wkhtmltox\PDF\Converter::convert - Perform PDF conversion
    • wkhtmltox\PDF\Converter::getVersion - Determine version of Converter
    • wkhtmltox\PDF\Converter::__construct - Create a new PDF converter
    • wkhtmltox\PDF\Object::__construct - Create a new PDF Object
    • wordwrap - 指定した文字数で文字列を分割する
    • Worker::collect - Collect references to completed tasks
    • Worker::getStacked - Gets the remaining stack size
    • Worker::isShutdown - State Detection
    • Worker::shutdown - Shutdown the worker
    • Worker::stack - Stacking work
    • Worker::unstack - Unstacking work
  • x
    • xattr_get - 拡張属性を取得する
    • xattr_list - 拡張属性の一覧を取得する
    • xattr_remove - 拡張属性を削除する
    • xattr_set - 拡張属性を設定する
    • xattr_supported - ファイルシステムが拡張属性をサポートしているかどうかを調べる
    • xdiff_file_bdiff - 2 つのファイルのバイナリ diff を作成する
    • xdiff_file_bdiff_size - バイナリ diff を適用して作成するファイルのサイズを読み込む
    • xdiff_file_bpatch - ファイルにバイナリ diff 形式のパッチを適用する
    • xdiff_file_diff - 2 つのファイルの unified diff を作成する
    • xdiff_file_diff_binary - xdiff_file_bdiff のエイリアス
    • xdiff_file_merge3 - 3 つのファイルをひとつに統合する
    • xdiff_file_patch - ファイルに unified diff 形式のパッチを適用する
    • xdiff_file_patch_binary - xdiff_file_bpatch のエイリアス
    • xdiff_file_rabdiff - 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
    • xdiff_string_bdiff - 2 つの文字列のバイナリ diff を作成する
    • xdiff_string_bdiff_size - バイナリ diff を適用して作成するファイルのサイズを読み込む
    • xdiff_string_bpatch - 文字列にバイナリ diff 形式のパッチを適用する
    • xdiff_string_diff - 2 つの文字列の unified diff を作成する
    • xdiff_string_diff_binary - xdiff_string_bdiff のエイリアス
    • xdiff_string_merge3 - 3 つの文字列をひとつに統合する
    • xdiff_string_patch - 文字列に unified diff 形式のパッチを適用する
    • xdiff_string_patch_binary - xdiff_string_bpatch のエイリアス
    • xdiff_string_rabdiff - 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する
    • xhprof_disable - xhprof プロファイラを終了する
    • xhprof_enable - xhprof プロファイラを開始する
    • xhprof_sample_disable - xhprof サンプルプロファイラを終了する
    • xhprof_sample_enable - サンプリングモードでの XHProf プロファイリングを開始する
    • XMLDiff\Base::diff - Produce diff of two XML documents
    • XMLDiff\Base::merge - Produce new XML document based on diff
    • XMLDiff\Base::__construct - Constructor
    • XMLDiff\DOM::diff - Diff two DOMDocument objects
    • XMLDiff\DOM::merge - Produce merged DOMDocument
    • XMLDiff\File::diff - Diff two XML files
    • XMLDiff\File::merge - Produce merged XML document
    • XMLDiff\Memory::diff - Diff two XML documents
    • XMLDiff\Memory::merge - Produce merged XML document
    • XMLReader::close - XMLReader の入力を閉じる
    • XMLReader::expand - 現在のノードのコピーを DOM オブジェクトとして返す
    • XMLReader::getAttribute - 名前をもとに、属性の値を取得する
    • XMLReader::getAttributeNo - インデックスをもとに、属性の値を取得する
    • XMLReader::getAttributeNs - 名前および URI をもとに、属性の値を取得する
    • XMLReader::getParserProperty - 指定したプロパティが設定されているかどうかを示す
    • XMLReader::isValid - パースしているドキュメントの妥当性を示す
    • XMLReader::lookupNamespace - プレフィックスから、名前空間を検索する
    • XMLReader::moveToAttribute - 指定した名前の属性にカーソルを移動する
    • XMLReader::moveToAttributeNo - 指定したインデックスの属性にカーソルを移動する
    • XMLReader::moveToAttributeNs - 指定した名前の属性にカーソルを移動する
    • XMLReader::moveToElement - 現在の属性の親要素にカーソルを移動する
    • XMLReader::moveToFirstAttribute - 最初の属性にカーソルを移動する
    • XMLReader::moveToNextAttribute - 次の属性にカーソルを移動する
    • XMLReader::next - すべてのサブツリーを飛ばして、次のノードにカーソルを移動する
    • XMLReader::open - パースする XML を含む URI を設定する
    • XMLReader::read - ドキュメント内の次のノードに移動する
    • XMLReader::readInnerXml - 現在のノードから XML を取得する
    • XMLReader::readOuterXml - 現在のノードから自分自身も含めた XML を取得する
    • XMLReader::readString - 現在のノードの内容を文字列で読み込む
    • XMLReader::setParserProperty - パーサのオプションを設定する
    • XMLReader::setRelaxNGSchema - RelaxNG スキーマのファイル名あるいは URI を設定する
    • XMLReader::setRelaxNGSchemaSource - RelaxNG スキーマを含むデータを設定する
    • XMLReader::setSchema - ドキュメントを XSD で検証する
    • XMLReader::XML - パースする XML を含むデータを設定する
    • xmlrpc_decode - XML をネイティブな PHP 型にデコードする
    • xmlrpc_decode_request - XML をネイティブなPHP 型にデコードする
    • xmlrpc_encode - PHP の値に関する XML を生成する
    • xmlrpc_encode_request - メソッドリクエスト用の XML を生成する
    • xmlrpc_get_type - PHP の値に関する xmlrpc 型を取得する
    • xmlrpc_is_fault - 配列の値が XMLRPC の失敗であるかどうかを調べる
    • xmlrpc_parse_method_descriptions - XML を、メソッド説明のリストにデコードする
    • xmlrpc_server_add_introspection_data - introspection ドキュメントを追加する
    • xmlrpc_server_call_method - XML リクエストをパースし、メソッドをコールする
    • xmlrpc_server_create - xmlrpc サーバーを作成する
    • xmlrpc_server_destroy - サーバーリソースを破棄する
    • xmlrpc_server_register_introspection_callback - ドキュメントを生成する PHP 関数を登録する
    • xmlrpc_server_register_method - メソッド名が一致するメソッドリソースに PHP 関数を登録する
    • xmlrpc_set_type - PHP 文字列型用に xmlrpc 型、base64 または datetime を設定する
    • XMLWriter::endAttribute - 属性を終了する
    • XMLWriter::endCdata - 現在の CDATA を終了する
    • XMLWriter::endComment - コメントの終了部を作成する
    • XMLWriter::endDocument - 現在のドキュメントを終了する
    • XMLWriter::endDtd - 現在の DTD を終了する
    • XMLWriter::endDtdAttlist - 現在の DTD 属性リストを終了する
    • XMLWriter::endDtdElement - 現在の DTD 要素を終了する
    • XMLWriter::endDtdEntity - 現在の DTD エンティティを終了する
    • XMLWriter::endElement - 現在の要素を終了する
    • XMLWriter::endPi - 現在の PI (処理命令) を終了する
    • XMLWriter::flush - 現在のバッファをフラッシュする
    • XMLWriter::fullEndElement - 現在の要素を終了する
    • XMLWriter::openMemory - 文字列の出力にメモリを使用する新しい xmlwriter を作成する
    • XMLWriter::openUri - ソース URI を指定して新しい xmlwriter を作成する
    • XMLWriter::outputMemory - 現在のバッファを返す
    • XMLWriter::setIndent - 字下げの on/off を切り替える
    • XMLWriter::setIndentString - 字下げに使用する文字列を設定する
    • XMLWriter::startAttribute - 属性を開始する
    • XMLWriter::startAttributeNs - 名前空間つきの属性を開始する
    • XMLWriter::startCdata - CDATA の開始タグを作成する
    • XMLWriter::startComment - コメントを開始する
    • XMLWriter::startDocument - ドキュメントタグを作成する
    • XMLWriter::startDtd - DTD の開始タグを作成する
    • XMLWriter::startDtdAttlist - DTD 属性リストを開始する
    • XMLWriter::startDtdElement - DTD 要素を開始する
    • XMLWriter::startDtdEntity - DTD エンティティを開始する
    • XMLWriter::startElement - 要素の開始タグを作成する
    • XMLWriter::startElementNs - 名前空間つき要素の開始タグを作成する
    • XMLWriter::startPi - PI (処理命令) の開始タグを作成する
    • XMLWriter::text - テキストを書き込む
    • XMLWriter::writeAttribute - 属性全体を書き込む
    • XMLWriter::writeAttributeNs - 名前空間つき属性全体を書き込む
    • XMLWriter::writeCdata - CDATA タグ全体を書き込む
    • XMLWriter::writeComment - コメントタグ全体を書き込む
    • XMLWriter::writeDtd - DTD タグ全体を書き込む
    • XMLWriter::writeDtdAttlist - DTD 属性リストタグ全体を書き込む
    • XMLWriter::writeDtdElement - DTD 要素タグ全体を書き込む
    • XMLWriter::writeDtdEntity - DTD エンティティタグ全体を書き込む
    • XMLWriter::writeElement - 要素タグ全体を書き込む
    • XMLWriter::writeElementNs - 名前空間つき要素タグ全体を書き込む
    • XMLWriter::writePi - PI (処理命令) 書き込む
    • XMLWriter::writeRaw - 生の XML テキストを書き込む
    • xml_error_string - XML パーサのエラー文字列を得る
    • xml_get_current_byte_index - XML パーサのカレントのバイトインデックスを得る
    • xml_get_current_column_number - XML パーサのカレントのカラム番号を取得する
    • xml_get_current_line_number - XML パーサのカレントの行番号を得る
    • xml_get_error_code - XML パーサのエラーコードを得る
    • xml_parse - XML ドキュメントの処理を開始する
    • xml_parser_create - XML パーサを作成する
    • xml_parser_create_ns - 名前空間をサポートした XML パーサを生成する
    • xml_parser_free - XML パーサを解放する
    • xml_parser_get_option - XML パーサからオプションを得る
    • xml_parser_set_option - XML パーサのオプションを設定する
    • xml_parse_into_struct - 配列構造体に XML データを処理する
    • xml_set_character_data_handler - 文字データハンドラを設定する
    • xml_set_default_handler - デフォルトのハンドラを設定する
    • xml_set_element_handler - 開始要素および終了要素のハンドラを設定する
    • xml_set_end_namespace_decl_handler - 名前空間終了ハンドラを設定する
    • xml_set_external_entity_ref_handler - 外部エンティティリファレンスハンドラを設定する
    • xml_set_notation_decl_handler - 表記法宣言ハンドラを設定する
    • xml_set_object - オブジェクト内部で XML パーサを使用する
    • xml_set_processing_instruction_handler - 処理命令 (PI) 用ハンドラを設定する
    • xml_set_start_namespace_decl_handler - 名前空間開始ハンドラを設定する
    • xml_set_unparsed_entity_decl_handler - 処理されないエンティティ宣言用ハンドラを設定する
    • XSLTProcessor::getParameter - パラメータの値を取得する
    • XSLTProcessor::getSecurityPrefs - セキュリティ設定を取得する
    • XSLTProcessor::hasExsltSupport - PHP が EXSLT をサポートしているかどうかを判定する
    • XSLTProcessor::importStylesheet - スタイルシートを取り込む
    • XSLTProcessor::registerPHPFunctions - PHP 関数を XSLT 関数として利用できるようにする
    • XSLTProcessor::removeParameter - パラメータを削除する
    • XSLTProcessor::setParameter - パラメータの値を設定する
    • XSLTProcessor::setProfiling - プロファイル情報の出力ファイルを設定する
    • XSLTProcessor::setSecurityPrefs - セキュリティ設定を指定する
    • XSLTProcessor::transformToDoc - ドキュメント に変換する
    • XSLTProcessor::transformToUri - URI に変換する
    • XSLTProcessor::transformToXml - XML に変換する
    • XSLTProcessor::__construct - 新しい XSLTProcessor オブジェクトを作成する
  • y
    • Yac::add - Store into cache
    • Yac::delete - Remove items from cache
    • Yac::dump - Dump cache
    • Yac::flush - Flush the cache
    • Yac::get - Retrieve values from cache
    • Yac::info - Status of cache
    • Yac::set - Store into cache
    • Yac::__construct - Constructor
    • Yac::__get - Getter
    • Yac::__set - Setter
    • Yaconf::get - Retrieve a item
    • Yaconf::has - Determine if a item exists
    • Yaf_Action_Abstract::execute - アクションのエントリポイント
    • Yaf_Action_Abstract::getController - コントローラオブジェクトを取得する
    • Yaf_Action_Abstract::getControllerName - Get controller name
    • Yaf_Application::app - アプリケーションのインスタンスを取得する
    • Yaf_Application::bootstrap - ブートストラップをコールする
    • Yaf_Application::clearLastError - 直近のエラー情報を消す
    • Yaf_Application::environ - 環境を取得する
    • Yaf_Application::execute - コールバックを実行する
    • Yaf_Application::getAppDirectory - アプリケーションディレクトリを取得する
    • Yaf_Application::getConfig - 設定情報を取得する
    • Yaf_Application::getDispatcher - Yaf_Dispatcher のインスタンスを取得する
    • Yaf_Application::getLastErrorMsg - 直近で発生したエラーのメッセージを取得する
    • Yaf_Application::getLastErrorNo - 直近で発生したエラーのコードを取得する
    • Yaf_Application::getModules - 定義済みのモジュール名を取得する
    • Yaf_Application::run - Yaf_Application を開始する
    • Yaf_Application::setAppDirectory - アプリケーションディレクトリを変更する
    • Yaf_Application::__construct - Yaf_Application のコンストラクタ
    • Yaf_Application::__destruct - デストラクタ
    • Yaf_Config_Abstract::get - ゲッター
    • Yaf_Config_Abstract::readonly - 設定項目が読み込み専用かどうかを調べる
    • Yaf_Config_Abstract::set - セッター
    • Yaf_Config_Abstract::toArray - 配列に変換する
    • Yaf_Config_Ini::count - Yaf_Config.ini の全ての要素を数える
    • Yaf_Config_Ini::current - 現在の値を取得する
    • Yaf_Config_Ini::key - 現在の要素のキーを取得する
    • Yaf_Config_Ini::next - 内部ポインタを進める
    • Yaf_Config_Ini::offsetExists - The offsetExists purpose
    • Yaf_Config_Ini::offsetGet - The offsetGet purpose
    • Yaf_Config_Ini::offsetSet - The offsetSet purpose
    • Yaf_Config_Ini::offsetUnset - The offsetUnset purpose
    • Yaf_Config_Ini::readonly - The readonly purpose
    • Yaf_Config_Ini::rewind - The rewind purpose
    • Yaf_Config_Ini::toArray - PHP の配列として構成を返す
    • Yaf_Config_Ini::valid - The valid purpose
    • Yaf_Config_Ini::__construct - Yaf_Config_Ini のコンストラクタ
    • Yaf_Config_Ini::__get - 要素を取得する
    • Yaf_Config_Ini::__isset - キーが存在するかを判定する
    • Yaf_Config_Ini::__set - The __set purpose
    • Yaf_Config_Simple::count - The count purpose
    • Yaf_Config_Simple::current - The current purpose
    • Yaf_Config_Simple::key - The key purpose
    • Yaf_Config_Simple::next - The next purpose
    • Yaf_Config_Simple::offsetExists - The offsetExists purpose
    • Yaf_Config_Simple::offsetGet - The offsetGet purpose
    • Yaf_Config_Simple::offsetSet - The offsetSet purpose
    • Yaf_Config_Simple::offsetUnset - The offsetUnset purpose
    • Yaf_Config_Simple::readonly - The readonly purpose
    • Yaf_Config_Simple::rewind - The rewind purpose
    • Yaf_Config_Simple::toArray - PHP の配列を返す
    • Yaf_Config_Simple::valid - The valid purpose
    • Yaf_Config_Simple::__construct - コンストラクタ
    • Yaf_Config_Simple::__get - The __get purpose
    • Yaf_Config_Simple::__isset - The __isset purpose
    • Yaf_Config_Simple::__set - The __set purpose
    • Yaf_Controller_Abstract::display - The display purpose
    • Yaf_Controller_Abstract::forward - 別のアクションに転送する
    • Yaf_Controller_Abstract::getInvokeArg - The getInvokeArg purpose
    • Yaf_Controller_Abstract::getInvokeArgs - The getInvokeArgs purpose
    • Yaf_Controller_Abstract::getModuleName - モジュール名を取得する
    • Yaf_Controller_Abstract::getName - Get self name
    • Yaf_Controller_Abstract::getRequest - 現在のリクエストオブジェクトを取得する
    • Yaf_Controller_Abstract::getResponse - 現在のレスポンスオブジェクトを取得する
    • Yaf_Controller_Abstract::getView - ビューエンジンを取得する
    • Yaf_Controller_Abstract::getViewpath - getViewpath の目的を書く
    • Yaf_Controller_Abstract::init - コントローラを初期化する
    • Yaf_Controller_Abstract::initView - The initView purpose
    • Yaf_Controller_Abstract::redirect - URL にリダイレクトする
    • Yaf_Controller_Abstract::render - ビューテンプレートをレンダリングする
    • Yaf_Controller_Abstract::setViewpath - The setViewpath purpose
    • Yaf_Controller_Abstract::__construct - Yaf_Controller_Abstract のコンストラクタ
    • Yaf_Dispatcher::autoRender - 自動レンダリングのオン/オフを切り替える
    • Yaf_Dispatcher::catchException - 例外のキャッチのオン/オフを切り替える
    • Yaf_Dispatcher::disableView - ビューのレンダリングを無効にする
    • Yaf_Dispatcher::dispatch - リクエストをディスパッチする
    • Yaf_Dispatcher::enableView - ビューのレンダリングを有効にする
    • Yaf_Dispatcher::flushInstantly - その場でのフラッシュのオン/オフを切り替える
    • Yaf_Dispatcher::getApplication - アプリケーションを取得する
    • Yaf_Dispatcher::getDefaultAction - Retrive the default action name
    • Yaf_Dispatcher::getDefaultController - Retrive the default controller name
    • Yaf_Dispatcher::getDefaultModule - Retrive the default module name
    • Yaf_Dispatcher::getInstance - ディスパッチャのインスタンスを取得する
    • Yaf_Dispatcher::getRequest - リクエストのインスタンスを取得する
    • Yaf_Dispatcher::getRouter - ルーターのインスタンスを取得する
    • Yaf_Dispatcher::initView - ビューを初期化して返す
    • Yaf_Dispatcher::registerPlugin - プラグインを登録する
    • Yaf_Dispatcher::returnResponse - The returnResponse purpose
    • Yaf_Dispatcher::setDefaultAction - デフォルトのアクション名を変更する
    • Yaf_Dispatcher::setDefaultController - デフォルトのコントローラ名を変更する
    • Yaf_Dispatcher::setDefaultModule - デフォルトのモジュール名を変更する
    • Yaf_Dispatcher::setErrorHandler - エラーハンドラを設定する
    • Yaf_Dispatcher::setRequest - The setRequest purpose
    • Yaf_Dispatcher::setView - カスタムビューエンジンを設定する
    • Yaf_Dispatcher::throwException - 例外のスローのオン/オフを切り替える
    • Yaf_Dispatcher::__construct - Yaf_Dispatcher のコンストラクタ
    • Yaf_Exception::getPrevious - The getPrevious purpose
    • Yaf_Exception::__construct - コンストラクタ
    • Yaf_Loader::autoload - The autoload purpose
    • Yaf_Loader::clearLocalNamespace - The clearLocalNamespace purpose
    • Yaf_Loader::getInstance - The getInstance purpose
    • Yaf_Loader::getLibraryPath - ライブラリパスを取得する
    • Yaf_Loader::getLocalNamespace - Retrive all register namespaces info
    • Yaf_Loader::getNamespacePath - Retieve path of a registered namespace
    • Yaf_Loader::import - The import purpose
    • Yaf_Loader::isLocalName - The isLocalName purpose
    • Yaf_Loader::registerLocalNamespace - ローカルクラスプレフィックスを登録する
    • Yaf_Loader::registerNamespace - Register namespace with searching path
    • Yaf_Loader::setLibraryPath - ライブラリパスを変更する
    • Yaf_Loader::__construct - The __construct purpose
    • Yaf_Plugin_Abstract::dispatchLoopShutdown - The dispatchLoopShutdown purpose
    • Yaf_Plugin_Abstract::dispatchLoopStartup - ディスパッチループの前にフックする
    • Yaf_Plugin_Abstract::postDispatch - The postDispatch purpose
    • Yaf_Plugin_Abstract::preDispatch - The preDispatch purpose
    • Yaf_Plugin_Abstract::preResponse - The preResponse purpose
    • Yaf_Plugin_Abstract::routerShutdown - The routerShutdown purpose
    • Yaf_Plugin_Abstract::routerStartup - RouterStartup フック
    • Yaf_Registry::del - アイテムをレジストリから削除する
    • Yaf_Registry::get - アイテムをレジストリから取得する
    • Yaf_Registry::has - アイテムが存在するかどうかを調べる
    • Yaf_Registry::set - アイテムをレジストリに追加する
    • Yaf_Registry::__construct - Yaf_Registry はシングルトンを実装する
    • Yaf_Request_Abstract::clearParams - Remove all params
    • Yaf_Request_Abstract::getActionName - The getActionName purpose
    • Yaf_Request_Abstract::getBaseUri - The getBaseUri purpose
    • Yaf_Request_Abstract::getControllerName - The getControllerName purpose
    • Yaf_Request_Abstract::getEnv - ENV 変数を取得する
    • Yaf_Request_Abstract::getException - The getException purpose
    • Yaf_Request_Abstract::getLanguage - クライアントの好きな言語を取得する
    • Yaf_Request_Abstract::getMethod - リクエストメソッドを取得する
    • Yaf_Request_Abstract::getModuleName - The getModuleName purpose
    • Yaf_Request_Abstract::getParam - 呼び出しパラメータを取得する
    • Yaf_Request_Abstract::getParams - 全ての呼び出しパラメータを取得する
    • Yaf_Request_Abstract::getRequestUri - The getRequestUri purpose
    • Yaf_Request_Abstract::getServer - SERVER 変数を取得する
    • Yaf_Request_Abstract::isCli - CLIリクエストかを判定する
    • Yaf_Request_Abstract::isDispatched - リクエストがディスパッチ済みかを判定する
    • Yaf_Request_Abstract::isGet - GETリクエストかどうかを判定する
    • Yaf_Request_Abstract::isHead - HEADリクエストかどうかを判定する
    • Yaf_Request_Abstract::isOptions - OPTIONS リクエストかどうかを判定する
    • Yaf_Request_Abstract::isPost - POST リクエストかどうかを判定する
    • Yaf_Request_Abstract::isPut - PUTリクエストかどうかを判定する
    • Yaf_Request_Abstract::isRouted - リクエストがルーティング済みかを判定する
    • Yaf_Request_Abstract::isXmlHttpRequest - AJAXリクエストかどうかを判定する
    • Yaf_Request_Abstract::setActionName - アクション名を設定する
    • Yaf_Request_Abstract::setBaseUri - ベース URI を設定する
    • Yaf_Request_Abstract::setControllerName - コントローラー名を設定する
    • Yaf_Request_Abstract::setDispatched - The setDispatched purpose
    • Yaf_Request_Abstract::setModuleName - モジュール名を設定する
    • Yaf_Request_Abstract::setParam - 呼び出しパラメータをリクエストに設定する
    • Yaf_Request_Abstract::setRequestUri - The setRequestUri purpose
    • Yaf_Request_Abstract::setRouted - The setRouted purpose
    • Yaf_Request_Http::get - クライアントからの変数を取得する
    • Yaf_Request_Http::getCookie - Cookie 変数を取得する
    • Yaf_Request_Http::getFiles - The getFiles purpose
    • Yaf_Request_Http::getPost - POST 変数を取得する
    • Yaf_Request_Http::getQuery - クエリパラメータを取得する
    • Yaf_Request_Http::getRaw - 生のリクエストボディを取得する
    • Yaf_Request_Http::getRequest - The getRequest purpose
    • Yaf_Request_Http::isXmlHttpRequest - リクエストが Ajax リクエストかどうかを判断する
    • Yaf_Request_Http::__construct - Yaf_Request_Http のコンストラクタ
    • Yaf_Request_Simple::get - The get purpose
    • Yaf_Request_Simple::getCookie - The getCookie purpose
    • Yaf_Request_Simple::getFiles - The getFiles purpose
    • Yaf_Request_Simple::getPost - The getPost purpose
    • Yaf_Request_Simple::getQuery - The getQuery purpose
    • Yaf_Request_Simple::getRequest - The getRequest purpose
    • Yaf_Request_Simple::isXmlHttpRequest - リクエストが AJAX 経由のリクエストかどうかを判定する
    • Yaf_Request_Simple::__construct - Yaf_Request_Simple のコンストラクタ
    • Yaf_Response_Abstract::appendBody - レスポンス本文に追記する
    • Yaf_Response_Abstract::clearBody - 既存のすべてのレスポンス本文を破棄します
    • Yaf_Response_Abstract::clearHeaders - すべてのヘッダをクリアする
    • Yaf_Response_Abstract::getBody - コンテンツを取得する
    • Yaf_Response_Abstract::getHeader - getHeader の目的
    • Yaf_Response_Abstract::prependBody - The prependBody purpose
    • Yaf_Response_Abstract::response - レスポンスを送信する
    • Yaf_Response_Abstract::setAllHeaders - The setAllHeaders purpose
    • Yaf_Response_Abstract::setBody - コンテンツをレスポンスに設定する
    • Yaf_Response_Abstract::setHeader - レスポンスヘッダを設定する
    • Yaf_Response_Abstract::setRedirect - The setRedirect purpose
    • Yaf_Response_Abstract::__construct - The __construct purpose
    • Yaf_Response_Abstract::__destruct - The __destruct purpose
    • Yaf_Response_Abstract::__toString - すべてのレスポンスボディを文字列として取得する
    • Yaf_Router::addConfig - 設定で定義したルートをルーターに追加する
    • Yaf_Router::addRoute - 新しいルートをルーターに追加する
    • Yaf_Router::getCurrentRoute - 使われているルート名を取得する
    • Yaf_Router::getRoute - 名前を指定してルートを取得する
    • Yaf_Router::getRoutes - 登録済みのルートを取得する
    • Yaf_Router::route - The route purpose
    • Yaf_Router::__construct - Yaf_Router のコンストラクタ
    • Yaf_Route_Interface::assemble - リクエストを組み立てる
    • Yaf_Route_Interface::route - リクエストをルーティングする
    • Yaf_Route_Map::assemble - URLを組み立てる
    • Yaf_Route_Map::route - route の目的
    • Yaf_Route_Map::__construct - The __construct purpose
    • Yaf_Route_Regex::assemble - URL を組み立てる
    • Yaf_Route_Regex::route - The route purpose
    • Yaf_Route_Regex::__construct - Yaf_Route_Regex のコンストラクタ
    • Yaf_Route_Rewrite::assemble - URLを組み立てる
    • Yaf_Route_Rewrite::route - The route purpose
    • Yaf_Route_Rewrite::__construct - Yaf_Route_Rewrite のコンストラクタ
    • Yaf_Route_Simple::assemble - URLを組み立てる
    • Yaf_Route_Simple::route - リクエストをルーティングする
    • Yaf_Route_Simple::__construct - Yaf_Route_Simple のコンストラクタ
    • Yaf_Route_Static::assemble - URL を組み立てる
    • Yaf_Route_Static::match - The match purpose
    • Yaf_Route_Static::route - リクエストをルーティングする
    • Yaf_Route_Supervar::assemble - URL を組み立てる
    • Yaf_Route_Supervar::route - The route purpose
    • Yaf_Route_Supervar::__construct - The __construct purpose
    • Yaf_Session::count - The count purpose
    • Yaf_Session::current - The current purpose
    • Yaf_Session::del - The del purpose
    • Yaf_Session::getInstance - The getInstance purpose
    • Yaf_Session::has - The has purpose
    • Yaf_Session::key - The key purpose
    • Yaf_Session::next - The next purpose
    • Yaf_Session::offsetExists - The offsetExists purpose
    • Yaf_Session::offsetGet - The offsetGet purpose
    • Yaf_Session::offsetSet - The offsetSet purpose
    • Yaf_Session::offsetUnset - The offsetUnset purpose
    • Yaf_Session::rewind - The rewind purpose
    • Yaf_Session::start - The start purpose
    • Yaf_Session::valid - The valid purpose
    • Yaf_Session::__construct - Yaf_Session のコンストラクタ
    • Yaf_Session::__get - The __get purpose
    • Yaf_Session::__isset - The __isset purpose
    • Yaf_Session::__set - The __set purpose
    • Yaf_Session::__unset - The __unset purpose
    • Yaf_View_Interface::assign - 値をビューエンジンに代入する
    • Yaf_View_Interface::display - テンプレートをレンダリングして出力する
    • Yaf_View_Interface::getScriptPath - The getScriptPath purpose
    • Yaf_View_Interface::render - テンプレートをレンダリングする
    • Yaf_View_Interface::setScriptPath - The setScriptPath purpose
    • Yaf_View_Simple::assign - 値を代入する
    • Yaf_View_Simple::assignRef - The assignRef purpose
    • Yaf_View_Simple::clear - 代入した値をクリアする
    • Yaf_View_Simple::display - レンダリングして表示する
    • Yaf_View_Simple::eval - テンプレートをレンダリングする
    • Yaf_View_Simple::getScriptPath - テンプレートのディレクトリを取得する
    • Yaf_View_Simple::render - テンプレートをレンダリングする
    • Yaf_View_Simple::setScriptPath - テンプレートのディレクトリを設定する
    • Yaf_View_Simple::__construct - Yaf_View_Simple のコンストラクタ
    • Yaf_View_Simple::__get - Retrieve assigned variable
    • Yaf_View_Simple::__isset - The __isset purpose
    • Yaf_View_Simple::__set - 値をエンジンに設定する
    • yaml_emit - YAML 形式にした値を返す
    • yaml_emit_file - YAML 形式にした値をファイルに送る
    • yaml_parse - YAML ストリームをパースする
    • yaml_parse_file - ファイルからの YAML ストリームをパースする
    • yaml_parse_url - URL からの YAML ストリームをパースする
    • Yar_Client::setOpt - Set calling contexts
    • Yar_Client::__call - Call service
    • Yar_Client::__construct - Create a client
    • Yar_Client_Exception::getType - Retrieve exception's type
    • Yar_Concurrent_Client::call - Register a concurrent call
    • Yar_Concurrent_Client::loop - Send all calls
    • Yar_Concurrent_Client::reset - Clean all registered calls
    • Yar_Server::handle - Start RPC Server
    • Yar_Server::__construct - Register a server
    • Yar_Server_Exception::getType - Retrieve exception's type
    • yaz_addinfo - 詳細なエラー情報を返す
    • yaz_ccl_conf - CCL パーサを設定する
    • yaz_ccl_parse - CCL パーサを起動する
    • yaz_close - YAZ 接続をクローズする
    • yaz_connect - Z39.50 サーバーへの接続を準備する
    • yaz_database - セッション内のデータベースを指定する
    • yaz_element - 取得時の要素集合の名前を指定する
    • yaz_errno - エラー番号を返す
    • yaz_error - エラーの内容を返す
    • yaz_es - 拡張サービスのリクエストを準備する
    • yaz_es_result - 拡張サービスの結果を調査する
    • yaz_get_option - 接続に関するオプションの値を返す
    • yaz_hits - 直近の検索に関するヒット数を返す
    • yaz_itemorder - ILL リクエストパッケージを関して Z39.50 Item Order を準備する
    • yaz_present - (Z39.50による)取得の準備を行う
    • yaz_range - 取得するレコードの範囲を指定する
    • yaz_record - レコードを返す
    • yaz_scan - スキャンの準備をする
    • yaz_scan_result - スキャンリクエストの結果を返す
    • yaz_schema - 取得するスキーマを指定する
    • yaz_search - 検索を準備する
    • yaz_set_option - 接続に関するひとつあるいは複数のオプションを設定する
    • yaz_sort - ソート条件を設定する
    • yaz_syntax - 取得用に適当なレコード構文を指定する
    • yaz_wait - Z39.50 リクエストが完了するまで待つ
  • z
    • zend_thread_id - 現在のスレッドの一意な ID を返す
    • zend_version - 現在の Zend Engine のバージョンを取得する
    • ZipArchive::addEmptyDir - 新しいディレクトリを追加する
    • ZipArchive::addFile - 指定したパスからファイルを ZIP アーカイブに追加する
    • ZipArchive::addFromString - 内容を指定して、ファイルを ZIP アーカイブに追加する
    • ZipArchive::addGlob - ディレクトリから、glob パターンを使ってファイルを追加する
    • ZipArchive::addPattern - ディレクトリから、PCRE パターンを使ってファイルを追加する
    • ZipArchive::clearError - ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする
    • ZipArchive::close - アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる
    • ZipArchive::count - アーカイブにあるファイルの数を数える
    • ZipArchive::deleteIndex - インデックスを使用して、アーカイブ内のエントリを削除する
    • ZipArchive::deleteName - 名前を使用して、アーカイブからエントリを削除する
    • ZipArchive::extractTo - アーカイブの内容を展開する
    • ZipArchive::getArchiveComment - ZIP アーカイブのコメントを返す
    • ZipArchive::getArchiveFlag - Zip アーカイブのグローバルフラグの値を返す
    • ZipArchive::getCommentIndex - エントリのインデックスを使用して、エントリのコメントを返す
    • ZipArchive::getCommentName - エントリ名を使用して、エントリのコメントを返す
    • ZipArchive::getExternalAttributesIndex - インデックスで定義されたエントリの外部属性を取得する
    • ZipArchive::getExternalAttributesName - 名前で定義されたエントリの外部属性を取得する
    • ZipArchive::getFromIndex - インデックスを使用して、エントリの内容を返す
    • ZipArchive::getFromName - 名前を使用して、エントリの内容を返す
    • ZipArchive::getNameIndex - インデックスを使用して、エントリの名前を返す
    • ZipArchive::getStatusString - システムエラー、または ZIP メッセージに関するエラー情報を返す
    • ZipArchive::getStream - 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する
    • ZipArchive::getStreamIndex - インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
    • ZipArchive::getStreamName - 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)
    • ZipArchive::isCompressionMethodSupported - 圧縮方式を libzip がサポートしているかをチェックする
    • ZipArchive::isEncryptionMethodSupported - 暗号化方式を libzip がサポートしているかどうかをチェックする
    • ZipArchive::locateName - アーカイブ内のエントリのインデックスを返す
    • ZipArchive::open - ZIP ファイルアーカイブをオープンする
    • ZipArchive::registerCancelCallback - アーカイブを閉じている間にキャンセルできるようにコールバックを登録する
    • ZipArchive::registerProgressCallback - アーカイブを閉じている間に更新できるようにコールバックを登録する
    • ZipArchive::renameIndex - インデックスを使用してエントリ名を変更する
    • ZipArchive::renameName - 名前を使用してエントリ名を変更する
    • ZipArchive::replaceFile - 指定されたパスのファイルにアーカイブの一部を置き換える
    • ZipArchive::setArchiveComment - ZIP アーカイブのコメントを設定する
    • ZipArchive::setArchiveFlag - Zip アーカイブのグローバルフラグを設定する
    • ZipArchive::setCommentIndex - インデックスを使用してエントリのコメントを設定する
    • ZipArchive::setCommentName - 名前を使用してエントリのコメントを設定する
    • ZipArchive::setCompressionIndex - インデックスで定義されたエントリの圧縮方法を設定する
    • ZipArchive::setCompressionName - 名前で定義されたエントリの圧縮メソッドを設定する
    • ZipArchive::setEncryptionIndex - index で定義されたエントリの暗号化方法を指定する
    • ZipArchive::setEncryptionName - 名前で定義されたエントリの暗号化方式を設定する
    • ZipArchive::setExternalAttributesIndex - インデックスで定義されたエントリの外部属性を設定する
    • ZipArchive::setExternalAttributesName - 名前で定義されたエントリの外部属性を設定する
    • ZipArchive::setMtimeIndex - インデックスを使用してエントリの変更時間を設定する
    • ZipArchive::setMtimeName - 名前を使ってエントリの変更時間を設定する
    • ZipArchive::setPassword - アクティブなアーカイブにパスワードを設定する
    • ZipArchive::statIndex - インデックスを使用してエントリの詳細を取得する
    • ZipArchive::statName - 名前を使用してエントリの詳細を取得する
    • ZipArchive::unchangeAll - アーカイブに対するすべての変更を取り消す
    • ZipArchive::unchangeArchive - アーカイブ全体に対して行われたすべての変更を取り消す
    • ZipArchive::unchangeIndex - 指定したインデックスのエントリに対するすべての変更を取り消す
    • ZipArchive::unchangeName - 指定した名前のエントリに対するすべての変更を取り消す
    • zip_close - ZIP ファイルアーカイブを閉じる
    • zip_entry_close - ディレクトリエントリを閉じる
    • zip_entry_compressedsize - ディレクトリエントリの圧縮時のサイズを取得する
    • zip_entry_compressionmethod - ディレクトリエントリの圧縮方法を取得する
    • zip_entry_filesize - ディレクトリエントリの実際のファイルサイズを取得する
    • zip_entry_name - ディレクトリエントリの名前を取得する
    • zip_entry_open - 読込み用にディレクトリエントリをオープンする
    • zip_entry_read - オープンされたディレクトリエントリから読み込む
    • zip_open - Zip ファイルアーカイブをオープンする
    • zip_read - Zip ファイルアーカイブの中の次のエントリを読み込む
    • zlib_decode - raw/gzip/zlib で符号化されたデータを復元する
    • zlib_encode - 指定した符号化方式でデータを圧縮する
    • zlib_get_coding_type - 出力圧縮に使用されたコーディングの種類を返す
    • ZMQ::__construct - ZMQ constructor
    • ZMQContext::getOpt - Get context option
    • ZMQContext::getSocket - Create a new socket
    • ZMQContext::isPersistent - Whether the context is persistent
    • ZMQContext::setOpt - Set a socket option
    • ZMQContext::__construct - Construct a new ZMQContext object
    • ZMQDevice::getIdleTimeout - Get the idle timeout
    • ZMQDevice::getTimerTimeout - Get the timer timeout
    • ZMQDevice::run - Run the new device
    • ZMQDevice::setIdleCallback - Set the idle callback function
    • ZMQDevice::setIdleTimeout - Set the idle timeout
    • ZMQDevice::setTimerCallback - Set the timer callback function
    • ZMQDevice::setTimerTimeout - Set the timer timeout
    • ZMQDevice::__construct - Construct a new device
    • ZMQPoll::add - Add item to the poll set
    • ZMQPoll::clear - Clear the poll set
    • ZMQPoll::count - Count items in the poll set
    • ZMQPoll::getLastErrors - Get poll errors
    • ZMQPoll::poll - Poll the items
    • ZMQPoll::remove - Remove item from poll set
    • ZMQSocket::bind - Bind the socket
    • ZMQSocket::connect - Connect the socket
    • ZMQSocket::disconnect - Disconnect a socket
    • ZMQSocket::getEndpoints - Get list of endpoints
    • ZMQSocket::getPersistentId - Get the persistent id
    • ZMQSocket::getSocketType - Get the socket type
    • ZMQSocket::getSockOpt - Get socket option
    • ZMQSocket::isPersistent - Whether the socket is persistent
    • ZMQSocket::recv - Receives a message
    • ZMQSocket::recvMulti - Receives a multipart message
    • ZMQSocket::send - Sends a message
    • ZMQSocket::sendmulti - マルチパートメッセージを送る
    • ZMQSocket::setSockOpt - Set a socket option
    • ZMQSocket::unbind - Unbind the socket
    • ZMQSocket::__construct - Construct a new ZMQSocket
    • Zookeeper::addAuth - Specify application credentials
    • Zookeeper::close - Close the zookeeper handle and free up any resources
    • Zookeeper::connect - Create a handle to used communicate with zookeeper
    • Zookeeper::create - Create a node synchronously
    • Zookeeper::delete - Delete a node in zookeeper synchronously
    • Zookeeper::exists - Checks the existence of a node in zookeeper synchronously
    • Zookeeper::get - Gets the data associated with a node synchronously
    • Zookeeper::getAcl - Gets the acl associated with a node synchronously
    • Zookeeper::getChildren - Lists the children of a node synchronously
    • Zookeeper::getClientId - Return the client session id, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE)
    • Zookeeper::getConfig - Get instance of ZookeeperConfig
    • Zookeeper::getRecvTimeout - Return the timeout for this session, only valid if the connections is currently connected (ie. last watcher state is ZOO_CONNECTED_STATE). This value may change after a server re-connect
    • Zookeeper::getState - Get the state of the zookeeper connection
    • Zookeeper::isRecoverable - Checks if the current zookeeper connection state can be recovered
    • Zookeeper::set - Sets the data associated with a node
    • Zookeeper::setAcl - Sets the acl associated with a node synchronously
    • Zookeeper::setDebugLevel - Sets the debugging level for the library
    • Zookeeper::setDeterministicConnOrder - Enable/disable quorum endpoint order randomization
    • Zookeeper::setLogStream - Sets the stream to be used by the library for logging
    • Zookeeper::setWatcher - Set a watcher function
    • Zookeeper::__construct - Create a handle to used communicate with zookeeper
    • ZookeeperConfig::add - Add servers to the ensemble
    • ZookeeperConfig::get - Gets the last committed configuration of the ZooKeeper cluster as it is known to the server to which the client is connected, synchronously
    • ZookeeperConfig::remove - Remove servers from the ensemble
    • ZookeeperConfig::set - Change ZK cluster ensemble membership and roles of ensemble peers
    • zookeeper_dispatch - Calls callbacks for pending operations
  • _
    • _ - のエイリアス gettext
    • __autoload - 未定義のクラスのロードを試みる
    • __halt_compiler - コンパイラの実行を中止する


サンプル

マニュアル内の全サンプルの一覧

  • Example#0 - 初歩的な例
  • Example#1 - 初めての PHP スクリプト: hello.php
  • Example#2 - PHP からシステムに関する情報を取得する
  • Example#3 - 変数を出力する (配列要素)
  • Example#4 - 制御構造 および 関数の使用例
  • Example#5 - HTML および PHP モードの両方を混在させる
  • Example#6 - 簡単な HTML フォーム
  • Example#7 - フォームからのデータを出力する
  • Example#8 - lighttpd.conf の抜粋
  • Example#9 - FastCGI レスポンダの起動
  • Example#10 - リモートの php-fastcgi インスタンスへの接続
  • Example#11 - OpenBSD パッケージインストールの例
  • Example#12 - Debian で Apache 2 と組み合わせるインストール例
  • Example#13 - PHP インストール後に Apache を停止・起動させる
  • Example#14 - 追加の PHP パッケージを探す方法
  • Example#15 - PHP と MySQL、cURL のインストール
  • Example#16 - OpCache の推奨構成
  • Example#17 - WinCache の推奨構成
  • Example#18 - IIS と PHP の設定をするためのコマンドライン
  • Example#19 - Registry changes
  • Example#20 - PHP を Apache 2.x ハンドラとして使う設定
  • Example#21 - PHP を Apache 2.x 上で CGI として動かす例
  • Example#22 - PHP を FastCGI として動かす Apache の設定
  • Example#23 - 環境変数や PHP の設定をプールに渡す
  • Example#24 - PHP の設定を nginx.conf で行う例
  • Example#25 - phpinfo のコール
  • Example#26 - php.ini での環境変数
  • Example#27 - php.ini の例
  • Example#28 - Apache 設定の例
  • Example#29 - PHP の開始タグと終了タグ
  • Example#30 - 条件文を使った高度な脱出
  • Example#31 - 改行を囲んだ終了タグを表示させる例
  • Example#32 - 整数リテラル
  • Example#33 - 32 ビットシステムにおける整数のオーバーフロー
  • Example#34 - 64 ビットシステムにおける整数のオーバーフロー
  • Example#35 - PHP 7.3.0 以降での、基本的なヒアドキュメントの使い方
  • Example#36 - 終端ID は 文字列本体よりも奥にインデントしてはいけない
  • Example#37 - 文字列本体 や 終端ID のインデントに違う文字を使う
  • Example#38 - 終端ID の後に式を継続する
  • Example#39 - 文字列本体に 終端ID が含まれると、ParseError が起きがち
  • Example#40 - PHP 7.3.0 より前のバージョンでの間違った例
  • Example#41 - PHP 7.3.0 より前のバージョンでも有効な例
  • Example#42 - ヒアドキュメントで文字列を括る例
  • Example#43 - ヒアドキュメントを引数に使用する例
  • Example#44 - ヒアドキュメントを用いた静的な値の初期化
  • Example#45 - ヒアドキュメントでのダブルクォート
  • Example#46 - Nowdoc による文字列のクォートの例
  • Example#47 - 変数がある場合の、Nowdoc による文字列のクォートの例
  • Example#48 - 静的なデータの例
  • Example#49 - 簡単な構文の例
  • Example#50 - 負の数値インデックス
  • Example#51 - 文字列の例
  • Example#52 - 不正な文字列のオフセットの例
  • Example#53 - シンプルな配列定義
  • Example#54 - 型のキャストと値の上書きの例
  • Example#55 - 整数と文字列のキーの混在例
  • Example#56 - 数値添字配列でキーを省略する例
  • Example#57 - 一部の要素にだけキーを指定する例
  • Example#58 - 複雑な型のキャストと上書きの例
  • Example#59 - 配列の要素へのアクセス
  • Example#60 - 配列のデリファレンス
  • Example#61 - 簡単な配列のアンパック
  • Example#62 - キーが重複した場合の配列のアンパック
  • Example#63 - array() の使用例
  • Example#64 - コレクション
  • Example#65 - ループ内での要素の変更
  • Example#66 - 1 から始まる添字
  • Example#67 - 配列に代入する
  • Example#68 - 配列のソート
  • Example#69 - 再帰および多次元配列
  • Example#70 - コールバック関数の例
  • Example#71 - クロージャを使ったコールバックの例
  • Example#72 - iterable を戻り値の型として使った、ジェネレータの例
  • Example#73 - リファレンス渡しのパラメータに対する型宣言
  • Example#74 - 引数にnullを許容する古いやり方
  • Example#75 - クラスによる型宣言の基本
  • Example#76 - インターフェイスによる型宣言の基本
  • Example#77 - 基本的な戻り値の型宣言
  • Example#78 - オブジェクトを返す
  • Example#79 - Null を許容する型宣言
  • Example#80 - Null を許容する戻り値の型宣言
  • Example#81 - クラスのプロパティで型宣言
  • Example#82 - 引数の値に対する厳密な型付け
  • Example#83 - 引数の値に対する型の自動変換
  • Example#84 - 戻り値に対する厳密な型付け
  • Example#85 - union の型のひとつに変換される例
  • Example#86 - 初期化されていない変数のデフォルト値
  • Example#87 - global の使用
  • Example#88 - globalのかわりに$GLOBALSを使用する
  • Example#89 - スーパーグローバルとスコープの例
  • Example#90 - static 変数が必要な場面の例
  • Example#91 - static 変数の使用例
  • Example#92 - 再帰関数でのstatic変数の使用
  • Example#93 - static 変数の宣言
  • Example#94 - 継承されたメソッドのstatic 変数を使う
  • Example#95 - 可変プロパティの例
  • Example#96 - 簡単なHTMLフォーム
  • Example#97 - 簡単なPOST HTMLフォームからのデータにアクセスする
  • Example#98 - より複雑なフォーム変数
  • Example#99 - setcookieの例
  • Example#100 - 有効/無効な定数名の例
  • Example#101 - 定数の定義
  • Example#102 - const キーワードによる定数の定義
  • Example#103 - 結合時の評価
  • Example#104 - 評価順序は未定義
  • Example#105 - +、-、. の優先順位は同じ(PHP 8.0.0 より前のバージョン)
  • Example#106 - Perl 風に、文字列をインクリメントする例
  • Example#107 - 英数字が浮動小数点数にキャストされる挙動
  • Example#108 - 参照による代入
  • Example#109 - 整数値におけるビット AND、OR および XOR 演算
  • Example#110 - 文字列でのビット XOR 演算
  • Example#111 - 整数値のビットシフト
  • Example#112 - Boolean/null の比較
  • Example#113 - 一般的な配列の比較
  • Example#114 - デフォルト値を設定する
  • Example#115 - 三項演算子のわかりにくい挙動
  • Example#116 - 三項演算子の短縮形
  • Example#117 - デフォルト値の代入
  • Example#118 - Null 合体演算子のネスト
  • Example#119 - 論理演算子についての説明
  • Example#120 - 配列の比較
  • Example#121 - クラスでの instanceof の使用法
  • Example#122 - 継承したクラスでの instanceof の使用法
  • Example#123 - instanceof を使用して、オブジェクトがクラスのインスタンスで ない かどうかを調べる方法
  • Example#124 - インターフェイスでの instanceof の使用法
  • Example#125 - 変数を用いた instanceof の使用法
  • Example#126 - instanceof での他の変数の調べかた
  • Example#127 - instanceof を使って定数を確認する
  • Example#128 - instanceof を任意の式と一緒に使う
  • Example#129 - switch 文の構造
  • Example#130 - 基本式な match 式の使い方
  • Example#131 - 比較演算子と match 式を一緒に使う例
  • Example#132 - match 式の構造
  • Example#133 - 処理されない match 式の例
  • Example#134 - 整数の範囲に応じてmatch式を分岐させる一般的な使い方
  • Example#135 - 文字列の内容に応じてmatch式を分岐させる一般的な使い方
  • Example#136 - Tick の使用例
  • Example#137 - スクリプトのエンコーディングの宣言
  • Example#138 - 基本的な include の例
  • Example#139 - 関数内での読み込み
  • Example#140 - HTTP経由の include
  • Example#141 - インクルードの戻り値を比較する
  • Example#142 - include と return 文
  • Example#143 - 出力バッファリングを用い、 PHP ファイルの内容を文字列として読み込む
  • Example#144 - goto の例
  • Example#145 - ループでの goto の例
  • Example#146 - これは動作しません
  • Example#147 - 関数の使用法を説明するための擬似コード
  • Example#148 - 条件つきの関数
  • Example#149 - 関数の中の関数
  • Example#150 - 再帰的な関数
  • Example#151 - 関数に配列を渡す
  • Example#152 - 関数の引数リストの最後にカンマを付ける
  • Example#153 - 関数のパラメータのリファレンス渡し
  • Example#154 - 関数におけるデフォルト引数の使用法
  • Example#155 - スカラー型以外をデフォルト値として使用する
  • Example#156 - オブジェクトをデフォルト値として使用する(PHP 8.1.0 以降)
  • Example#157 - 関数の引数のデフォルト値の 間違った使用法
  • Example#158 - 関数の引数のデフォルト値の 正しい使用法
  • Example#159 - 関数の引数のデフォルト値の 正しい使用法
  • Example#160 - デフォルト値を指定した引数は、必須の引数の後に宣言する
  • Example#161 - ... を使った、可変長引数へのアクセス
  • Example#162 - 引数での ... の使用例
  • Example#163 - 型宣言つきの可変長引数
  • Example#164 - 名前付き引数の文法
  • Example#165 - 位置を指定した引数と、名前付き引数
  • Example#166 - 上と同じ例を、引数の順番を変えて渡す
  • Example#167 - 位置を指定した引数と、名前付き引数を組み合わせる
  • Example#168 - 同じ引数を複数回渡すと、Error がスローされる
  • Example#169 - 引数を展開した後に、名前付き引数を使う
  • Example#170 - return の使用法
  • Example#171 - 複数の値を得るために配列を返す例
  • Example#172 - 関数からリファレンスを返す
  • Example#173 - 可変関数の例
  • Example#174 - 可変メソッドの例
  • Example#175 - staticプロパティを含む可変メソッドの例
  • Example#176 - 複雑な callable
  • Example#177 - 無名関数の例
  • Example#178 - 変数への無名関数の代入
  • Example#179 - 親のスコープからの変数の引き継ぎ
  • Example#180 - クロージャのスコープ
  • Example#181 - $this の自動バインド
  • Example#182 - static な無名関数内での $this の使用例
  • Example#183 - static な無名関数へのオブジェクトのバインド
  • Example#184 - アロー関数は参照ではなく値を自動でキャプチャする
  • Example#185 - アロー関数は、ネストされた場合でも変数を値でキャプチャする
  • Example#186 - アロー関数の例
  • Example#187 - 外部のスコープの値はアロー関数では変更できない
  • Example#188 - 簡単な例
  • Example#189 - 古い callable の生成方法と、CallableExpr(...) の比較
  • Example#190 - 簡単なクラス定義
  • Example#191 - $this 疑似変数の例
  • Example#192 - インスタンスを作成する
  • Example#193 - オブジェクトの代入
  • Example#194 - 任意の式を使ってインスタンスを生成する
  • Example#195 - 新しいオブジェクトの作成
  • Example#196 - 新しく作成したオブジェクトのメンバーへのアクセス
  • Example#197 - プロパティへのアクセスとメソッドの呼び出し
  • Example#198 - プロパティに格納した無名関数の呼び出し
  • Example#199 - 簡単なクラスの継承
  • Example#200 - 互換性がある子クラスのメソッド
  • Example#201 - 子クラスのメソッドで引数を削除すると致命的なエラーになる
  • Example#202 - 子クラスのメソッドで、オプションの引数を必須にすると致命的なエラーになる
  • Example#203 - 子クラスで引数の名前を変更し、かつ名前付き引数を使うとエラーになる
  • Example#204 - クラス名の解決
  • Example#205 - クラス名が存在しない場合の名前解決
  • Example#206 - オブジェクトの名前解決
  • Example#207 - nullsafe 演算子
  • Example#208 - プロパティの宣言
  • Example#209 - 型付きプロパティの例
  • Example#210 - プロパティにアクセスする
  • Example#211 - 読み取り専用プロパティの例
  • Example#212 - 読み取り専用プロパティの不正な初期化
  • Example#213 - 定数の定義と使用
  • Example#214 - 名前空間の ::class の例
  • Example#215 - クラス内での定数式の例
  • Example#216 - PHP 7.1.0 以降の、クラス定数のアクセス範囲
  • Example#217 - オートロードの例
  • Example#218 - オートロードの別の例
  • Example#219 - 継承とコンストラクタ
  • Example#220 - コンストラクタを引数と一緒に使う
  • Example#221 - コンストラクタのプロモーションを使う
  • Example#222 - 初期化時に new キーワードを使う
  • Example#223 - static な生成メソッドを使う
  • Example#224 - デストラクタの例
  • Example#225 - プロパティの宣言
  • Example#226 - メソッドの宣言
  • Example#227 - PHP 7.1.0 以降での定数の宣言
  • Example#228 - 同じ型のオブジェクトの private メンバーへのアクセス
  • Example#229 - 継承の例
  • Example#230 - 戻り値の型を宣言せずにメソッドをオーバーライドする場合
  • Example#231 - 間違った型を宣言してメソッドをオーバーライドする場合
  • Example#232 - 間違った型を宣言してメソッドをオーバーライドする場合でも、警告を抑制する
  • Example#233 - クラス定義の外からの ::
  • Example#234 - クラス定義の中からの ::
  • Example#235 - 親クラスのメソッドをコールする
  • Example#236 - static メソッドの例
  • Example#237 - static プロパティの例
  • Example#238 - 抽象クラスの例
  • Example#239 - 抽象クラスの例
  • Example#240 - Interface の例
  • Example#241 - インターフェイスの継承
  • Example#242 - 共変性を保った形で、複数のインターフェイスを実装する
  • Example#243 - 複数のインターフェイスの継承
  • Example#244 - インターフェイスでの定数
  • Example#245 - 抽象クラスとインターフェイス
  • Example#246 - 継承と実装を同時に行う
  • Example#247 - トレイトの例
  • Example#248 - 優先順位の例
  • Example#249 - もうひとつの優先順位の例
  • Example#250 - 複数のトレイトの使用例
  • Example#251 - 衝突の解決
  • Example#252 - メソッドのアクセス権を変更する
  • Example#253 - トレイトを組み合わせたトレイト
  • Example#254 - 抽象メソッドによる、要件の明示
  • Example#255 - static変数
  • Example#256 - staticメソッド
  • Example#257 - staticプロパティ
  • Example#258 - プロパティの定義
  • Example#259 - 衝突の解決
  • Example#260 - 定数を定義する
  • Example#261 - 衝突の解決
  • Example#262 - __get()、
     __set()、__isset() および
     __unset() メソッドを使ったプロパティのオーバーロードの例
  • Example#263 - __call() および __callStatic() メソッドによる、メソッドのオーバーロードの例
  • Example#264 - 単純なオブジェクトの反復の例
  • Example#265 - sleep と wakeup
  • Example#266 - Serialize と unserialize
  • Example#267 - 簡単な例
  • Example#268 - __invoke() の使用
  • Example#269 - __invoke() の使用
  • Example#270 - __set_state() の使用法
  • Example#271 - __debugInfo() の使用法
  • Example#272 - finalメソッドの例
  • Example#273 - finalクラスの例
  • Example#274 - final定数の例(PHP 8.1.0 以降)
  • Example#275 - オブジェクトのクローン作成
  • Example#276 - クローンしたオブジェクトのメンバーへのアクセス
  • Example#277 - オブジェクト比較の例
  • Example#278 - self:: の使用例
  • Example#279 - static:: のシンプルな使用法
  • Example#280 - 非静的コンテキストにおける static:: の使用法
  • Example#281 - 転送するコールと転送しないコール
  • Example#282 - 参照とオブジェクト
  • Example#283 - 名前空間構文の例
  • Example#284 - 名前空間の宣言
  • Example#285 - 名前空間の宣言
  • Example#286 - 階層つきの名前空間の宣言
  • Example#287 - シンプルな組み合わせ方式による複数の名前空間の宣言
  • Example#288 - 波括弧構文による複数の名前空間の宣言
  • Example#289 - 複数の名前空間および名前空間に属さないコードの宣言
  • Example#290 - 複数の名前空間および名前空間に属さないコードの宣言
  • Example#291 - グローバルなクラス、関数および定数への名前空間内からのアクセス
  • Example#292 - 要素への動的なアクセス
  • Example#293 - 名前空間つき要素への動的なアクセス
  • Example#294 - 名前空間内のコードでの __NAMESPACE__ の例
  • Example#295 - グローバルなコードでの __NAMESPACE__ の例
  • Example#296 - __NAMESPACE__ による動的な名前の作成
  • Example#297 - 名前空間内での namespace 演算子
  • Example#298 - グローバルコードでの namespace 演算子
  • Example#299 - use 演算子によるインポート/エイリアス
  • Example#300 - use 演算子によるインポート/エイリアスで、複数の use 文を組み合わせる例
  • Example#301 - インポートと動的名
  • Example#302 - インポートと完全修飾名
  • Example#303 - 間違ったインポートの例
  • Example#304 - グローバル空間を指定する方法
  • Example#305 - 名前空間内からのグローバルクラスへのアクセス
  • Example#306 - 名前空間内からのグローバル関数/定数への移行
  • Example#307 - 名前解決の例
  • Example#308 - 名前空間の外部にあるグローバルクラスへのアクセス
  • Example#309 - 名前空間の外部にあるグローバルクラスへのアクセス
  • Example#310 - 名前空間内からの内部クラスへのアクセス
  • Example#311 - 名前空間内のクラス、関数あるいは定数へのアクセス
  • Example#312 - 完全修飾名
  • Example#313 - 修飾名
  • Example#314 - 非修飾クラス名
  • Example#315 - 非修飾関数/定数名
  • Example#316 - ダブルクォートで囲んだ文字列内で名前空間名を扱う際の危険
  • Example#317 - 未定義の定数
  • Example#318 - 未定義の定数
  • Example#319 - 基本的な、値を限定する例
  • Example#320 - 唯一の値を指定する、高度な例
  • Example#321 - エラーを例外に変換する
  • Example#322 - 例外をスローする
  • Example#323 - 例外処理での finally ブロック
  • Example#324 - finally ブロックと return の相互作用
  • Example#325 - ネストした例外
  • Example#326 - 複数の例外ハンドリングをひとつの catch で行う
  • Example#327 - キャッチする時に変数を省略する
  • Example#328 - throw を 式として扱う
  • Example#329 - 組み込みの例外クラス
  • Example#330 - 例外クラスを拡張する
  • Example#331 - ファイバーの基本的な使い方
  • Example#332 - ジェネレータを使った range の実装
  • Example#333 - 値を yield する単純な例
  • Example#334 - キー/値 のペアの yield
  • Example#335 - null の yield
  • Example#336 - 参照による値の yield
  • Example#337 - yield from と iterator_to_array
  • Example#338 - yield from の基本的な使いかた
  • Example#339 - yield from の返す値
  • Example#340 - アトリビュートを使い、インターフェイスのオプションのメソッドを実装する
  • Example#341 - アトリビュートの文法
  • Example#342 - リフレクションAPIを使い、アトリビュートを読み取る
  • Example#343 - リフレクションAPIを使い、特定のアトリビュートを読み取る
  • Example#344 - 単純なアトリビュートクラスの例
  • Example#345 - アトリビュートを使える場所を限定するために、ターゲットとなるクラスを作る
  • Example#346 - 宣言時にアトリビュートを複数回使えるように、IS_REPEATABLE を使う
  • Example#347 - 未定義の変数のリファレンスの使用
  • Example#348 - 関数内でのグローバル変数の参照
  • Example#349 - リファレンスと foreach ステートメント
  • Example#350 - $GLOBALS の例
  • Example#351 - $GLOBALS 配列全体を書き換える操作はエラーになる
  • Example#352 - $_SERVER の例
  • Example#353 - $_GET の例
  • Example#354 - $_POST の例
  • Example#355 - $_ENV の例
  • Example#356 - $_COOKIE の例
  • Example#357 - $php_errormsg の例
  • Example#358 - $http_response_header の例
  • Example#359 - $argc の例
  • Example#360 - $argv の例
  • Example#361 - Exception::getMessage の例
  • Example#362 - Exception::getPrevious の例
  • Example#363 - Exception::getCode の例
  • Example#364 - Exception::getFile の例
  • Example#365 - Exception::getLine の例
  • Example#366 - Exception::getTrace の例
  • Example#367 - Exception::getTraceAsString の例
  • Example#368 - Exception::__toString の例
  • Example#369 - set_error_handler を使用した、エラーメッセージから ErrorException への変換
  • Example#370 - ErrorException::getSeverity の例
  • Example#371 - Error::getMessage の例
  • Example#372 - Error::getPrevious の例
  • Example#373 - Error::getCode の例
  • Example#374 - Error::getFile の例
  • Example#375 - Error::getLine の例
  • Example#376 - Error::getTrace の例
  • Example#377 - Error::getTraceAsString の例
  • Example#378 - Error::__toString の例
  • Example#379 - 基本的な使用法
  • Example#380 - 基本的な例
  • Example#381 - 基本的な使用法
  • Example#382 - ArrayAccess::offsetExists の例
  • Example#383 - 基本的な使用法
  • Example#384 - Closure::bind の例
  • Example#385 - Closure::bindTo の例
  • Example#386 - Closure::call の例
  • Example#387 - オブジェクトへの型変換を使い、stdClass を作る
  • Example#388 - json_decode によって、stdClass を作る
  • Example#389 - 動的にプロパティを宣言する
  • Example#390 - Generator::getReturn の例
  • Example#391 - Generator::key の例
  • Example#392 - Generator::send による値の注入
  • Example#393 - ジェネレータへの例外のスロー
  • Example#394 - 基本的な WeakReference クラスの使い方
  • Example#395 - Weakmap の使い方の例
  • Example#396 - 基本的な Stringable インターフェイスの使い方
  • Example#397 - 基本的な使用法
  • Example#398 - 基本的な使用法
  • Example#399 - 基本的な使用法
  • Example#400 - SensitiveParameterValue オブジェクトを var_dump に渡す
  • Example#401 - SensitiveParameterValue::getValue の例
  • Example#402 - unserialize によって生成されるクラス
  • Example#403 - 基本的な bindto の使用例
  • Example#404 - ページの取得と POST データの送信
  • Example#405 - リダイレクトを無視し、ヘッダとコンテンツの取得
  • Example#406 - password の基本的な使用例
  • Example#407 - リダイレクト後の URL の検出
  • Example#408 - php://temp/maxmemory
  • Example#409 - php://filter/resource=<フィルタの対象となるストリーム>
  • Example#410 - php://filter/read=<読み込みチェーンに適用するフィルタのリスト>
  • Example#411 - php://filter/write=<書き込みチェーンに適用するフィルタのリスト>
  • Example#412 - php://memory と php://temp は再利用できない
  • Example#413 - data:// の内容の表示
  • Example#414 - media type の取得
  • Example#415 - 基本的な使用法
  • Example#416 - アクティブな接続からストリームをオープンする
  • Example#417 - $session を有効にしておかないといけない!
  • Example#418 - RAR アーカイブの走査
  • Example#419 - 暗号化されたファイルのオープン (ヘッダの暗号化)
  • Example#420 - 甘い変数の確認から生じるリスク
  • Example#421 - ... ファイルシステムへの攻撃
  • Example#422 - より安全なファイル名の確認
  • Example#423 - より安全なファイル名の確認
  • Example#424 - null バイトに対して脆弱なスクリプト
  • Example#425 - 入力を適切に検証する例
  • Example#426 - ハッシュされたパスワードフィールド
  • Example#427 - 表示するデータを分割し ... そしてスーパーユーザーを作成します。(PostgreSQLの例)
  • Example#428 - 記事...そして(全てのデータベースサーバーの)いくつかのパスワード のリストを表示する
  • Example#429 - パスワードのリセットから ... (全てのデータベースサーバーで)より多 くの権限を得るまで
  • Example#430 - データベースホストのオペレーティングシステムを攻撃する (MSSQLサーバー)
  • Example#431 - PDO のプリペアドステートメントを使い、SQLインジェクションを回避する
  • Example#432 - カスタムHTMLページにより変数を攻撃する
  • Example#433 - 一般的なデバッグ変数を探す
  • Example#434 - E_ALLで危険な変数を見つける
  • Example#435 - 危険な変数の使用
  • Example#436 - PHPを他の言語として隠す
  • Example#437 - PHP拡張子用に未知の型を使用する
  • Example#438 - PHP拡張子としてHTML型を使用する
  • Example#439 - Basic HTTP 認証の例
  • Example#440 - 新規に名前 / パスワードを入力させる HTTP 認証の例
  • Example#441 - ファイルアップロード用のフォーム
  • Example#442 - ファイルのアップロードを検証する
  • Example#443 - ファイルの配列をアップロードする
  • Example#444 - 複数ファイルのアップロード
  • Example#445 - ディレクトリ全体をアップロードする
  • Example#446 - HTTP PUT されたファイルの保存
  • Example#447 - リモートページのタイトルを得る
  • Example#448 - リモートサーバーにデータを保存する
  • Example#449 - CGI SAPI との違いを示す例
  • Example#450 - INI 設定に -d を使って値を設定する例
  • Example#451 - PHP に組み込まれた (そしてロードされた) Zend モジュールの表示
  • Example#452 - ダブルクォートの使用時に構文エラーが出る例
  • Example#453 - シングルクォートを使い、シェルの変数置換を防ぐ例
  • Example#454 - とあるプロジェクトの行数をカウントするための -B, -R そして -E オプションの使用例
  • Example#455 - -v による、SAPI 名および PHP と Zend のバージョンの取得
  • Example#456 - --ini の例
  • Example#457 - 基本的な --rf の使用法
  • Example#458 - --rc の例
  • Example#459 - --re の例
  • Example#460 - --ri の例
  • Example#461 - シェルスクリプトとしての PHP スクリプトの実行
  • Example#462 - コマンドラインから実行されることを意図したスクリプト(script.php)
  • Example#463 - コマンドライン PHP スクリプトを実行するバッチファイル(script.bat)
  • Example#464 - 対話シェル上でのコードの実行
  • Example#465 - タブ補完
  • Example#466 - 対話シェル内での php.ini の設定
  • Example#467 - ウェブサーバーの起動
  • Example#468 - ドキュメントルートディレクトリを指定した起動
  • Example#469 - ルータースクリプトの使用
  • Example#470 - CLI ウェブサーバーを使っているかどうかのチェック
  • Example#471 - 未サポートのファイル形式の処理
  • Example#472 - CLI ウェブサーバーへのリモートマシンからのアクセス
  • Example#473 - 新規 zval コンテナを作成
  • Example#474 - zval 情報を表示
  • Example#475 - zval の refcount を増加
  • Example#476 - zval refcount を減少
  • Example#477 - array zval を作成
  • Example#478 - 既存の要素を配列に追加
  • Example#479 - 配列から要素を除去
  • Example#480 - それ自体の要素として配列自体を追加
  • Example#481 - $a をアンセット
  • Example#482 - メモリ使用量の例
  • Example#483 - GC パフォーマンスの影響
  • Example#484 - 上記のスクリプトを実行
  • Example#485 - GC ベンチマーキングを使用可能にするために PHP を再コンパイル
  • Example#486 - GC 統計
  • Example#487 - DTrace を使用してすべての PHP 静的プローブをトレースするためのall_probes.d
  • Example#488 - SystemTap を使用してすべての PHP 静的プローブをトレースするためのall_probes.stp
  • Example#489 - apcu_add の例
  • Example#490 - apcu_cache_info の例
  • Example#491 - apcu_cas の例
  • Example#492 - apcu_dec の例
  • Example#493 - apcu_delete の例
  • Example#494 - apcu_entry の例
  • Example#495 - apcu_exists の例
  • Example#496 - apcu_fetch の例
  • Example#497 - apcu_inc の例
  • Example#498 - A apcu_key_info の例
  • Example#499 - apcu_sma_info の例
  • Example#500 - apcu_store の例
  • Example#501 - APCUIterator::__construct の例
  • Example#502 - スクリプト内でのエラー処理
  • Example#503 - debug_backtrace の例
  • Example#504 - debug_print_backtrace の例
  • Example#505 - error_clear_last の例
  • Example#506 - error_get_last の例
  • Example#507 - error_log の例
  • Example#508 - error_reporting の例
  • Example#509 - restore_error_handler の例
  • Example#510 - restore_exception_handler の例
  • Example#511 - set_error_handler および trigger_error によるエラー処理
  • Example#512 - set_exception_handler の例
  • Example#513 - trigger_error の例
  • Example#514 - Calling a function from shared library
  • Example#515 - Calling a function, returning a structure through an argument
  • Example#516 - Accessing existing C variables
  • Example#517 - Creating and Modifying C variables
  • Example#518 - Working with C arrays
  • Example#519 - Working with C enums
  • Example#520 - Assigning a PHP Closure to a C function pointer
  • Example#521 - 出力制御の例
  • Example#522 - 出力リライトの例
  • Example#523 - ob_end_clean の例
  • Example#524 - ob_end_flush の例
  • Example#525 - 単純な ob_get_clean の例
  • Example#526 - 単純な ob_get_contents の例
  • Example#527 - ob_get_flush の例
  • Example#528 - 単純な ob_get_length の例
  • Example#529 - full_status が false の場合に返される配列
  • Example#530 - full_status が true の場合に返される配列
  • Example#531 - ob_list_handlers の例
  • Example#532 - ユーザー定義のコールバック関数の例
  • Example#533 - 削除不可能な出力バッファを作る例
  • Example#534 - output_add_rewrite_var の例
  • Example#535 - output_reset_rewrite_vars の例
  • Example#536 - assert の例
  • Example#537 - カスタムのメッセージを使う
  • Example#538 - カスタムの例外クラスを使う
  • Example#539 - assert_options の例
  • Example#540 - cli_get_process_title の例
  • Example#541 - cli_set_process_title の例
  • Example#542 - dl の例
  • Example#543 - extension_loaded の例
  • Example#544 - gc_enabled の例
  • Example#545 - gc_status の使い方
  • Example#546 - get_current_user の例
  • Example#547 - get_defined_constants の例
  • Example#548 - XML 関数の出力
  • Example#549 - get_include_path の例
  • Example#550 - get_included_files の例
  • Example#551 - get_loaded_extensions の例
  • Example#552 - フィルタリングされていない get_resources
  • Example#553 - フィルタリングされた get_resources
  • Example#554 - getenv の例
  • Example#555 - getlastmod の例
  • Example#556 - getopt の例：基本編
  • Example#557 - getopt の例：長いオプション
  • Example#558 - getopt の例：複数のオプションを一度に渡す
  • Example#559 - getopt の例: rest_index を使う
  • Example#560 - getrusage の例
  • Example#561 - ini_get の例
  • Example#562 - ini_get_all の例
  • Example#563 - details を無効にする例
  • Example#564 - ini_parse_quantity の例
  • Example#565 - ini_restore の例
  • Example#566 - ini オプションの設定
  • Example#567 - memory_get_usage の例
  • Example#568 - memory_reset_peak_usage の例
  • Example#569 - php_ini_loaded_file の例
  • Example#570 - 返される ini ファイルを一覧する例
  • Example#571 - php_sapi_name の例
  • Example#572 - php_uname の例
  • Example#573 - OS 関連の定数の例
  • Example#574 - 全般的なクレジットの出力
  • Example#575 - コア開発者およびドキュメントグループの表示
  • Example#576 - すべてのクレジットの表示
  • Example#577 - phpinfo の例
  • Example#578 - phpversion の例
  • Example#579 - PHP_VERSION_ID の例および使用法
  • Example#580 - 環境変数の設定
  • Example#581 - restore_include_path の例
  • Example#582 - set_include_path の例
  • Example#583 - include path の追加
  • Example#584 - sys_get_temp_dir の例
  • Example#585 - version_compare の例
  • Example#586 - zend_thread_id の例
  • Example#587 - zend_version の例
  • Example#588 - Custom Superglobals with runkit.superglobal=_FOO,_BAR in php.ini
  • Example#589 - A runkit7_function_add example
  • Example#590 - A runkit7_function_copy example
  • Example#591 - A runkit7_function_redefine example
  • Example#592 - runkit7_method_add example
  • Example#593 - runkit7_method_copy example
  • Example#594 - runkit7_method_redefine example
  • Example#595 - runkit7_method_remove example
  • Example#596 - runkit7_method_rename example
  • Example#597 - runkit7_zval_inspect example
  • Example#598 - Basic uopz_add_function Usage
  • Example#599 - uopz_allow_exit example
  • Example#600 - uopz_backup example
  • Example#601 - uopz_compose example
  • Example#602 - uopz_copy example
  • Example#603 - Basic uopz_del_function Usage
  • Example#604 - uopz_delete example
  • Example#605 - uopz_delete class example
  • Example#606 - uopz_extend の例
  • Example#607 - uopz_flags の例
  • Example#608 - クラスの final 宣言を外す
  • Example#609 - uopz_function example
  • Example#610 - uopz_function class example
  • Example#611 - uopz_get_exit_status example
  • Example#612 - Basic uopz_get_hook Usage
  • Example#613 - uopz_get_mock example
  • Example#614 - Basic uopz_get_property Usage
  • Example#615 - uopz_get_return example
  • Example#616 - uopz_get_static の基本的な使い方
  • Example#617 - uopz_implement の例
  • Example#618 - uopz_overload example
  • Example#619 - uopz_redefine の例
  • Example#620 - uopz_rename example
  • Example#621 - uopz_rename class example
  • Example#622 - uopz_restore example
  • Example#623 - Basic uopz_set_hook Usage
  • Example#624 - uopz_set_mock の例
  • Example#625 - uopz_set_mock の例
  • Example#626 - uopz_set_mock と static メンバ
  • Example#627 - Basic uopz_set_property Usage
  • Example#628 - uopz_set_return example
  • Example#629 - uopz_set_return example
  • Example#630 - uopz_set_return class example
  • Example#631 - Basic uopz_set_static Usage
  • Example#632 - uopz_undefine の例
  • Example#633 - Basic uopz_unset_hook Usage
  • Example#634 - uopz_unset_mock の例
  • Example#635 - uopz_unset_return example
  • Example#636 - wincache.ignorelist の例
  • Example#637 - wincache.php 用の認証設定
  • Example#638 - WinCache セッションハンドラの有効化
  • Example#639 - WinCache の関数切り替えの有効化
  • Example#640 - Reroute.ini ファイルの内容
  • Example#641 - wincache_fcache_fileinfo の例
  • Example#642 - wincache_fcache_meminfo の例
  • Example#643 - wincache_lock の使用
  • Example#644 - wincache_ocache_fileinfo の例
  • Example#645 - wincache_ocache_meminfo の例
  • Example#646 - wincache_refresh_if_changed の例
  • Example#647 - wincache_rplist_fileinfo の例
  • Example#648 - wincache_rplist_meminfo の例
  • Example#649 - wincache_scache_info の例
  • Example#650 - wincache_scache_meminfo の例
  • Example#651 - wincache_ucache_add で key を文字列にする例
  • Example#652 - wincache_ucache_add で key を配列にする例
  • Example#653 - wincache_ucache_cas の使用法
  • Example#654 - wincache_ucache_clear の使用法
  • Example#655 - wincache_ucache_dec の使用法
  • Example#656 - wincache_ucache_delete で key に文字列を使う例
  • Example#657 - wincache_ucache_delete で key に配列を使う例
  • Example#658 - wincache_ucache_delete で key に配列を使い、いくつかの要素の削除に失敗する例
  • Example#659 - wincache_ucache_exists の使用法
  • Example#660 - wincache_ucache_get で key に文字列を使う例
  • Example#661 - wincache_ucache_get で key に配列を使う例
  • Example#662 - wincache_ucache_inc の使用法
  • Example#663 - wincache_ucache_info の使用
  • Example#664 - wincache_ucache_meminfo の例
  • Example#665 - wincache_ucache_set で key を文字列にする例
  • Example#666 - wincache_ucache_set で key を配列にする例
  • Example#667 - wincache_unlock の使用
  • Example#668 - オプションの GUI を使った Xhprof の例
  • Example#669 - xhprof_disable の例
  • Example#670 - xhprof_enable の例
  • Example#671 - xhprof_sample_disable の例
  • Example#672 - Make sure the item is stored
  • Example#673 - Using CHAP passwords
  • Example#674 - radius_acct_open の例
  • Example#675 - radius_add_server の例
  • Example#676 - radius_auth_open の例
  • Example#677 - radius_create_request の例
  • Example#678 - radius_cvt_addr の例
  • Example#679 - radius_cvt_int の例
  • Example#680 - radius_cvt_string の例
  • Example#681 - radius_get_attr の例
  • Example#682 - radius_get_tagged_attr_data example
  • Example#683 - radius_get_tagged_attr_tag example
  • Example#684 - radius_get_vendor_attr の例
  • Example#685 - radius_put_attr の例
  • Example#686 - radius_put_int の例
  • Example#687 - radius_put_string の例
  • Example#688 - radius_put_vendor_attr の例
  • Example#689 - readline の例
  • Example#690 - Readline コールバックインターフェイスの例
  • Example#691 - 簡単な bzip2 の例
  • Example#692 - データの圧縮
  • Example#693 - 文字列を解凍する
  • Example#694 - bzerror の例
  • Example#695 - bzopen の例
  • Example#696 - bzread の例
  • Example#697 - bzwrite の例
  • Example#698 - 外部ファイルの使用
  • Example#699 - Phar アーカイブ内のファイルの使用
  • Example#700 - phar 形式から tar 形式への phar アーカイブの変換
  • Example#701 - phar.cache_list の使用例
  • Example#702 - Phar::addEmptyDir の例
  • Example#703 - Phar::addFile の例
  • Example#704 - Phar::addFromString の例
  • Example#705 - Phar::apiVersion の例
  • Example#706 - Phar::buildFromDirectory の例
  • Example#707 - SplFileInfo を使用した Phar::buildFromIterator の例
  • Example#708 - その他のイテレータを使用した Phar::buildFromIterator の例
  • Example#709 - Phar::canCompress の例
  • Example#710 - Phar::canWrite の例
  • Example#711 - Phar::compress の例
  • Example#712 - Phar::compressFiles の例
  • Example#713 - Phar::__construct の例
  • Example#714 - Phar::convertToData の例
  • Example#715 - Phar::convertToExecutable の例
  • Example#716 - Phar::copy の例
  • Example#717 - Phar::count の例
  • Example#718 - Phar::createDefaultStub の例
  • Example#719 - Phar::decompress の例
  • Example#720 - Phar::decompressFiles の例
  • Example#721 - Phar::delMetaData の例
  • Example#722 - Phar::delete の例
  • Example#723 - Phar::extractTo の例
  • Example#724 - Phar::getMetadata の例
  • Example#725 - Phar::getStub の例
  • Example#726 - Phar::hasMetadata の例
  • Example#727 - Phar::interceptFileFuncs の例
  • Example#728 - Phar::interceptFileFuncs の例
  • Example#729 - Phar::isBuffering の例
  • Example#730 - Phar::isCompressed の例
  • Example#731 - Phar::loadPhar の例
  • Example#732 - Phar::mapPhar の例
  • Example#733 - Phar::mount の例
  • Example#734 - Phar::mungServer の例
  • Example#735 - Phar::offsetExists の例
  • Example#736 - Phar::offsetGet の例
  • Example#737 - Phar::offsetSet の例
  • Example#738 - Phar::offsetUnset の例
  • Example#739 - Phar::running の例
  • Example#740 - Phar::setAlias の例
  • Example#741 - Phar::setDefaultStub の例
  • Example#742 - Phar::setMetadata の例
  • Example#743 - Phar::setStub の例
  • Example#744 - Phar::startBuffering の例
  • Example#745 - Phar::stopBuffering の例
  • Example#746 - Phar::unlinkArchive の例
  • Example#747 - Phar::webPhar の例
  • Example#748 - PharData::addEmptyDir の例
  • Example#749 - PharData::addFile の例
  • Example#750 - PharData::addFromString の例
  • Example#751 - PharData::buildFromDirectory の例
  • Example#752 - SplFileInfo を使用した PharData::buildFromIterator の例
  • Example#753 - その他のイテレータを使用した PharData::buildFromIterator の例
  • Example#754 - PharData::compress の例
  • Example#755 - PharData::compressFiles の例
  • Example#756 - PharData::__construct の例
  • Example#757 - PharData::convertToData の例
  • Example#758 - PharData::convertToExecutable の例
  • Example#759 - PharData::copy の例
  • Example#760 - PharData::decompress の例
  • Example#761 - PharData::decompressFiles の例
  • Example#762 - PharData::delMetaData の例
  • Example#763 - PharData::delete の例
  • Example#764 - PharData::extractTo の例
  • Example#765 - PharData::offsetSet の例
  • Example#766 - PharData::offsetUnset の例
  • Example#767 - Phar::setMetadata の例
  • Example#768 - PharFileInfo::chmod の例
  • Example#769 - PharFileInfo::compress の例
  • Example#770 - PharFileInfo::__construct の例
  • Example#771 - PharFileInfo::decompress の例
  • Example#772 - PharFileInfo::delMetaData の例
  • Example#773 - PharFileInfo::getCRC32 の例
  • Example#774 - PharFileInfo::getCompressedSize の例
  • Example#775 - PharFileInfo::getMetadata の例
  • Example#776 - PharFileInfo::getPharFlags の例
  • Example#777 - PharFileInfo::isCRCChecked の例
  • Example#778 - PharFileInfo::isCompressed の例
  • Example#779 - PharFileInfo::setMetadata の例
  • Example#780 - Rar のインストール
  • Example#781 - オンザフライでの復元
  • Example#782 - RAR 拡張モジュールでの展開の例
  • Example#783 - オブジェクト指向型
  • Example#784 - 手続き型
  • Example#785 - オブジェクト指向型
  • Example#786 - 手続き型
  • Example#787 - オブジェクト指向型
  • Example#788 - 手続き型
  • Example#789 - オブジェクト指向型
  • Example#790 - 手続き型
  • Example#791 - オブジェクト指向型
  • Example#792 - 手続き型
  • Example#793 - オブジェクト指向型
  • Example#794 - 手続き型
  • Example#795 - オブジェクト指向型
  • Example#796 - 手続き型
  • Example#797 - ボリュームコールバック
  • Example#798 - オブジェクト指向型
  • Example#799 - 手続き型
  • Example#800 - RarArchive::__toString の例
  • Example#801 - RarEntry::extract の例
  • Example#802 - アーカイブ内のすべてのファイルを展開する方法
  • Example#803 - RarEntry::getAttr の例
  • Example#804 - RarEntry::getHostOs の例 (バージョン >= 2.0.0)
  • Example#805 - RarEntry::getHostOs の例 (バージョン <= 1.0.0)
  • Example#806 - RarEntry::getMethod の例
  • Example#807 - RarEntry::getName の例
  • Example#808 - RarEntry::getPackedSize の例
  • Example#809 - RarEntry::getStream の例
  • Example#810 - RarEntry::getUnpackedSize の例
  • Example#811 - RarEntry::getVersion の例
  • Example#812 - RarException::isUsingExceptions の例
  • Example#813 - RarException::setUsingExceptions の例
  • Example#814 - Zip アーカイブの作成
  • Example#815 - アーカイブの詳細の出力および一覧表示
  • Example#816 - Zip ストリームラッパーによる OpenOffice メタ情報の読み込み
  • Example#817 - Zip の使用例
  • Example#818 - アーカイブ内での新規ディレクトリの作成
  • Example#819 - オープンおよび追加
  • Example#820 - 新しいアーカイブへのエントリの追加
  • Example#821 - アーカイブ内のディレクトリへのファイルの追加
  • Example#822 - ZipArchive::addGlob の例
  • Example#823 - ZipArchive::addPattern の例
  • Example#824 - インデックスを使用した、アーカイブからのファイルの削除
  • Example#825 - 名前を使用した、アーカイブからのファイルやディレクトリの削除
  • Example#826 - 全エントリの展開
  • Example#827 - 二つのエントリの展開
  • Example#828 - アーカイブのコメントの出力
  • Example#829 - アーカイブが torrentzip フォーマットかを調べる
  • Example#830 - エントリのコメントの出力
  • Example#831 - エントリのコメントの出力
  • Example#832 - 全てのエントリをUnixの権限付きで展開する
  • Example#833 - ファイルの内容の取得
  • Example#834 - ファイルの内容の取得
  • Example#835 - zip エントリの画像への変換
  • Example#836 - ZipArchive::getNameIndex の例
  • Example#837 - エントリの内容を fread で取得し、それを保存する
  • Example#838 - 先ほどの例と同じことを、fopen および zip ストリームラッパーで行う
  • Example#839 - ストリームラッパーと画像の組み合わせ。xml 関数とでも使用可能
  • Example#840 - fread でエントリの内容を取得し、保存する
  • Example#841 - fread でエントリの内容を取得し、保存する
  • Example#842 - アーカイブを作成し、ZipArchive::locateName を使用する
  • Example#843 - オープンおよび展開
  • Example#844 - アーカイブの作成
  • Example#845 - 一時的なアーカイブの作成
  • Example#846 - ファイルをアーカイブする
  • Example#847 - ファイルをアーカイブする
  • Example#848 - エントリ名の変更
  • Example#849 - エントリ名の変更
  • Example#850 - オープンおよび追加
  • Example#851 - アーカイブの作成およびコメントの設定
  • Example#852 - torrentzip アーカイブを作成する
  • Example#853 - アーカイブをオープンし、エントリのコメントを設定する
  • Example#854 - アーカイブをオープンし、エントリのコメントを設定する
  • Example#855 - アーカイブに異なる圧縮メソッドでファイルを追加する
  • Example#856 - アーカイブに異なる圧縮メソッドでファイルを追加する
  • Example#857 - ファイルを追加し、圧縮メソッドを設定する
  • Example#858 - アーカイブを作成し、ファイルを暗号化する
  • Example#859 - Unix権限付きでファイルをアーカイブする
  • Example#860 - ファイルをアーカイブする
  • Example#861 - ファイルをアーカイブする
  • Example#862 - エントリの情報の出力
  • Example#863 - エントリの情報の出力
  • Example#864 - 簡単な Zlib の例
  • Example#865 - インクリメンタルな圧縮および伸長の API
  • Example#866 - gzclose の例
  • Example#867 - gzcompress の例
  • Example#868 - gzdeflate の例
  • Example#869 - gzip ファイルの生成
  • Example#870 - gzeof の例
  • Example#871 - gzfile の例
  • Example#872 - gzgetc の例
  • Example#873 - gzgets の例
  • Example#874 - gzgetss の例
  • Example#875 - gzinflate の例
  • Example#876 - gzopen の例
  • Example#877 - gzpassthru の例
  • Example#878 - gzread の例
  • Example#879 - gzseek の例
  • Example#880 - gzuncompress の例
  • Example#881 - gzwrite の例
  • Example#882 - ob_gzhandler の例
  • Example#883 - zlib_encode の例
  • Example#884 - hash の例
  • Example#885 - hash_algos の例
  • Example#886 - hash_copy の例
  • Example#887 - hash_equals の例
  • Example#888 - hash_file の使用例
  • Example#889 - hash_hkdf の例
  • Example#890 - hash_hmac の例
  • Example#891 - hash_hmac_algos の例
  • Example#892 - hash_hmac_file の例
  • Example#893 - 段階的なハッシュの例
  • Example#894 - hash_pbkdf2 の基本的な使い方の例
  • Example#895 - hash_update_stream の例
  • Example#896 - mcrypt_create_iv Example
  • Example#897 - mcrypt_enc_get_algorithms_name example
  • Example#898 - mcrypt_enc_get_modes_name の例
  • Example#899 - mcrypt_enc_get_supported_key_sizes の例
  • Example#900 - mcrypt_encrypt の例
  • Example#901 - mcrypt_get_block_size の例
  • Example#902 - mcrypt_get_cipher_name の例
  • Example#903 - mcrypt_get_iv_size の例
  • Example#904 - mcrypt_get_key_size の例
  • Example#905 - mcrypt_list_algorithms の例
  • Example#906 - mcrypt_list_modes の例
  • Example#907 - mcrypt_module_open の例
  • Example#908 - mcrypt_module_open を暗号化で使用する
  • Example#909 - mcrypt_module_self_test の例
  • Example#910 - mdecrypt_generic の例
  • Example#911 - MD5 ダイジェストと hmac を計算し、16 進数で出力する
  • Example#912 - 全ハッシュをループする
  • Example#913 - mhash_get_block_size の例
  • Example#914 - mhash_get_hash_name の例
  • Example#915 - openssl_cipher_iv_length の例
  • Example#916 - openssl_cipher_key_length の例
  • Example#917 - openssl_cms_sign の例
  • Example#918 - openssl_csr_export() の例
  • Example#919 - openssl_csr_export_to_file() の例
  • Example#920 - openssl_csr_get_public_key() の例
  • Example#921 - openssl_csr_get_subject() の例
  • Example#922 - 自己署名証明書の作成
  • Example#923 - 自己署名の ECC 証明書を作成する (PHP 7.1.0 以降)
  • Example#924 - openssl_csr_sign の例 - CSR に署名する（あなた自身の CA を作成する）
  • Example#925 - 共有シークレットを計算する
  • Example#926 - DH public/private キーペアをPHPで生成する
  • Example#927 - PHP 7.1以降で、AES を GCMモードで使う例
  • Example#928 - PHP 7.1 より前のバージョンで、AES を使う例
  • Example#929 - openssl_error_string の例
  • Example#930 - openssl_get_cert_locations の例
  • Example#931 - openssl_get_cipher_methods の例
  • Example#932 - openssl_get_curve_names の例
  • Example#933 - openssl_get_md_methods の例
  • Example#934 - openssl_open の例
  • Example#935 - openssl_pbkdf2() の例
  • Example#936 - openssl_pkcs12_read の例
  • Example#937 - openssl_pkcs7_decrypt の例
  • Example#938 - openssl_pkcs7_encrypt の例
  • Example#939 - P7B ファイルから、PEM証明書の配列を取得する
  • Example#940 - openssl_pkcs7_sign の例
  • Example#941 - openssl_pkey_derive 関数の例
  • Example#942 - 秘密鍵から、公開鍵を取得する
  • Example#943 - openssl_random_pseudo_bytes の例
  • Example#944 - openssl_seal の例
  • Example#945 - openssl_sign の例
  • Example#946 - openssl_sign の例
  • Example#947 - openssl_spki_export の例
  • Example#948 - openssl_spki_export を使い、<keygen> から取り出す例
  • Example#949 - openssl_spki_export_challenge の例
  • Example#950 - openssl_spki_export_challenge を使い、<keygen> から取り出す例
  • Example#951 - openssl_spki_new の例
  • Example#952 - openssl_spki_verify の例
  • Example#953 - <keygen> から openssl_spki_verify を使う例
  • Example#954 - openssl_verify の例
  • Example#955 - openssl_verify の例
  • Example#956 - openssl_x509_verify の例
  • Example#957 - password の基本的な使用法
  • Example#958 - password_hash の例
  • Example#959 - password_hash で、コストを手動で設定する例
  • Example#960 - password_hash で、適切なコストを探す例
  • Example#961 - Argon2i を使った password_hash の例
  • Example#962 - password_needs_rehash の使用例
  • Example#963 - password_verify の例
  • Example#964 - RNP clearsign example
  • Example#965 - simple callback function example
  • Example#966 - sodium_crypto_box_seal の例
  • Example#967 - sodium_crypto_box_seal_open の例
  • Example#968 - sodium_crypto_core_ristretto255_add の例
  • Example#969 - sodium_crypto_core_ristretto255_from_hash の例
  • Example#970 - sodium_crypto_core_ristretto255_is_valid_point の例
  • Example#971 - sodium_crypto_core_ristretto255_random の例
  • Example#972 - sodium_crypto_core_ristretto255_scalar_add の例
  • Example#973 - sodium_crypto_core_ristretto255_scalar_invertの例
  • Example#974 - sodium_crypto_core_ristretto255_scalar_negate の例
  • Example#975 - sodium_crypto_core_ristretto255_scalar_random の例
  • Example#976 - sodium_crypto_core_ristretto255_scalar_sub の例
  • Example#977 - sodium_crypto_core_ristretto255_sub の例
  • Example#978 - sodium_crypto_generichash_final の例
  • Example#979 - sodium_crypto_generichash_init の例
  • Example#980 - sodium_crypto_generichash_update の例
  • Example#981 - sodium_crypto_kx_keypair の使い方
  • Example#982 - sodium_crypto_pwhash の例
  • Example#983 - sodium_crypto_pwhash_str の例
  • Example#984 - sodium_crypto_secretbox の例
  • Example#985 - sodium_crypto_secretbox_keygen の例
  • Example#986 - sodium_crypto_secretbox_keygen と random_bytes の比較
  • Example#987 - sodium_crypto_secretbox_open の例
  • Example#988 - sodium_crypto_secretstream_xchacha20poly1305_init_pull の例
  • Example#989 - sodium_crypto_secretstream_xchacha20poly1305_init_push の例
  • Example#990 - sodium_crypto_stream_xchacha20_xor_ic の例
  • Example#991 - DBA の例
  • Example#992 - データベースへのアクセス
  • Example#993 - dba_handlers の例
  • Example#994 - カラムの権限の一覧を表示する
  • Example#995 - テーブルのカラム一覧を表示する
  • Example#996 - DSN なしの接続
  • Example#997 - odbc_connection_string_quote の例
  • Example#998 - 利用可能なDSNの一覧を表示する
  • Example#999 - odbc_execute および odbc_prepare の例
  • Example#1000 - odbc_fetch_into の例
  • Example#1001 - odbc_next_result
  • Example#1002 - odbc_execute および odbc_prepare の例
  • Example#1003 - プライマリーキーの一覧を表示する
  • Example#1004 - プロシージャーのカラムを表示する
  • Example#1005 - データベースのプロシージャ一覧を表示する
  • Example#1006 - odbc_result の例
  • Example#1007 - odbc_setoption の例
  • Example#1008 - テーブルの統計情報を表示する
  • Example#1009 - テーブルの権限を表示する
  • Example#1010 - カタログのテーブル一覧を表示する
  • Example#1011 - PDO::ATTR_DRIVER_NAME の使用例
  • Example#1012 - MySQL への接続
  • Example#1013 - 接続エラーの処理
  • Example#1014 - 接続を閉じる
  • Example#1015 - 持続的な接続
  • Example#1016 - トランザクション内で一括処理を行う
  • Example#1017 - プリペアドステートメントを使用して、繰り返し挿入処理を行う
  • Example#1018 - プリペアドステートメントを使用して、繰り返し挿入処理を行う
  • Example#1019 - プリペアドステートメントを使用してデータを取得する
  • Example#1020 - 出力パラメータを指定してストアドプロシージャをコールする
  • Example#1021 - 入出力パラメータを指定してストアドプロシージャをコールする
  • Example#1022 - プレースホルダの間違った使用法
  • Example#1023 - PDO インスタンスの作成およびエラーモードの設定
  • Example#1024 - PDO インスタンスの作成およびコンストラクタでのエラーモードの設定
  • Example#1025 - データベース内の画像を表示する
  • Example#1026 - 画像をデータベースに挿入する
  • Example#1027 - 画像をデータベースに挿入する: Oracle
  • Example#1028 - トランザクションをロールバックする
  • Example#1029 - 基本的なトランザクションをコミットする
  • Example#1030 - DDL トランザクションをコミットする
  • Example#1031 - ドライバ呼び出しにより PDO インスタンスを生成する
  • Example#1032 - URI 呼び出しにより PDO インスタンスを生成する
  • Example#1033 - エイリアスにより PDO インスタンスを生成する
  • Example#1034 - SQLSTATE コードを取得する
  • Example#1035 - DB2 データベースに対する PDO_ODBC 接続の errorInfo() フィールドを表示する
  • Example#1036 - DELETE 文の発行
  • Example#1037 - データベース接続の属性を取得する
  • Example#1038 - PDO::getAvailableDrivers の例
  • Example#1039 - 名前付きパラメータを用いて SQL ステートメントのテンプレートを準備する
  • Example#1040 - 疑問符パラメータを用いて SQL ステートメントのテンプレートを準備する
  • Example#1041 - クエスチョンマークをエスケープした、SQLステートメントのテンプレート
  • Example#1042 - プレースホルダーがないSQLを、PDO::query で実行できます
  • Example#1043 - 通常の文字列をクオートする
  • Example#1044 - 危険な文字列をクオートする
  • Example#1045 - 複雑な文字列をクオートする
  • Example#1046 - トランザクションをロールバックする
  • Example#1047 - バインドした結果セットを PHP 変数に出力する
  • Example#1048 - 名前付けされたプレースホルダを用いてプリペアドステートメントを実行する
  • Example#1049 - 疑問符プレースホルダを用いてプリペアドステートメントを実行する
  • Example#1050 - INOUT パラメータを持つストアドプロシージャをコールする
  • Example#1051 - 名前付けされたプレースホルダを用いてプリペアドステートメントを実行する
  • Example#1052 - 疑問符プレースホルダを用いてプリペアドステートメントを実行する
  • Example#1053 - PDOStatement::closeCursor の例
  • Example#1054 - カラム数を数える
  • Example#1055 - 名前つきパラメータを用いた PDOStatement::debugDumpParams の例
  • Example#1056 - 名前なしパラメータを用いた PDOStatement::debugDumpParams の例
  • Example#1057 - SQLSTATE コードを取得する
  • Example#1058 - DB2 データベースに対する PDO_ODBC 接続の errorInfo() フィールドを表示する
  • Example#1059 - 変数や値のバインドを伴うプリペアドステートメントの実行
  • Example#1060 - 名前付きの値を伴うプリペアドステートメントの実行
  • Example#1061 - 位置を指定した値を伴うプリペアドステートメントの実行
  • Example#1062 - 位置を指定したプレースホルダに、値をバインドした形でのプリペアドステートメントの実行
  • Example#1063 - IN 句で配列を使うプリペアドステートメントの実行
  • Example#1064 - 異なる取得方法で行を取得する
  • Example#1065 - スクロール可能なカーソルで行を取得する
  • Example#1066 - 構築の順序
  • Example#1067 - 結果セットに残っている全ての行をフェッチする
  • Example#1068 - 結果セットから単一カラムの全ての値を取得する
  • Example#1069 - 単一カラムによる全ての値のグループ化
  • Example#1070 - 各結果用のクラスのインスタンス作成
  • Example#1071 - 各結果に対する関数コール
  • Example#1072 - 次行の最初のカラムを返す
  • Example#1073 - カラムのメタデータを取得する
  • Example#1074 - ストアドプロシージャから複数の行セットをフェッチする
  • Example#1075 - 削除された行数を返す
  • Example#1076 - SELECT 文によって返された行をカウントする
  • Example#1077 - フェッチモードを設定する
  • Example#1078 - CUBRID PDO での LOB の追加
  • Example#1079 - CUBRID PDO での LOB の取得
  • Example#1080 - CUBRID PDO で、デフォルトのデータ型のセットを追加する例
  • Example#1081 - CUBRID PDO でのセットの追加でデータ型を指定する例
  • Example#1082 - PDO_CUBRID DSN の例
  • Example#1083 - PDO::cubrid_schema の例
  • Example#1084 - PDO_DBLIB DSN の例
  • Example#1085 - PDO_FIREBIRD DSN でのパス指定の例
  • Example#1086 - PDO_FIREBIRD DSN でのポートとパス指定の例
  • Example#1087 - PDO_FIREBIRD DSN で Debian システムのローカルホストと employee.fdb へのパスを使う例
  • Example#1088 - 方言が 1 のデータベースに接続するための PDO_FIREBIRD の DSN
  • Example#1089 - db2cli.ini を使用した PDO_IBM DSN の例
  • Example#1090 - 接続文字列を使用した PDO_IBM DSN の例
  • Example#1091 - odbc.ini を使用した PDO_INFORMIX DSN の例
  • Example#1092 - 接続文字列を使用した PDO_INFORMIX DSN の例
  • Example#1093 - MySQL の非バッファモードを使う
  • Example#1094 - PDO_MYSQL DSN の例
  • Example#1095 - PDO_SQLSRV DSN の例
  • Example#1096 - PDO_OCI DSN の例
  • Example#1097 - PDO_ODBC DSN の例 (ODBC ドライバマネージャ)
  • Example#1098 - PDO_ODBC DSN の例 (IBM DB2 非カタログ接続)
  • Example#1099 - PDO_ODBC DSN の例 (Microsoft Access 非カタログ接続)
  • Example#1100 - PDO_PGSQL DSN の例
  • Example#1101 - PDO::pgsqlLOBCreate の例
  • Example#1102 - PDO::pgsqlLOBOpen の例
  • Example#1103 - PDO::pgsqlLOBUnlink の例
  • Example#1104 - PDO_SQLITE DSN の例
  • Example#1105 - 集約関数 max_length の例
  • Example#1106 - PDO::sqliteCreateCollation の例
  • Example#1107 - PDO::sqliteCreateFunction の例
  • Example#1108 - Example of Data Retrieval
  • Example#1109 - Example of Data Insertion
  • Example#1110 - cubrid_bind example
  • Example#1111 - cubrid_bind BLOB/CLOB example
  • Example#1112 - cubrid_bind BLOB/CLOB example
  • Example#1113 - cubrid_close_prepare example
  • Example#1114 - cubrid_close_request example
  • Example#1115 - cubrid_col_get example
  • Example#1116 - cubrid_col_size example
  • Example#1117 - cubrid_column_names example
  • Example#1118 - cubrid_column_types example
  • Example#1119 - cubrid_commit example
  • Example#1120 - cubrid_connect example
  • Example#1121 - cubrid_connect_with_url url without properties example
  • Example#1122 - cubrid_connect_with_url url with properties example
  • Example#1123 - cubrid_current_oid example
  • Example#1124 - cubrid_disconnect example
  • Example#1125 - cubrid_drop example
  • Example#1126 - cubrid_error_code example
  • Example#1127 - cubrid_error_code_facility example
  • Example#1128 - cubrid_error_msg example
  • Example#1129 - cubrid_execute example
  • Example#1130 - cubrid_fetch example
  • Example#1131 - cubrid_free_result example
  • Example#1132 - cubrid_get example
  • Example#1133 - cubrid_get_charset example
  • Example#1134 - cubrid_get_class_name example
  • Example#1135 - cubrid_get_client_info example
  • Example#1136 - cubrid_get_db_parameter example
  • Example#1137 - cubrid_get_query_timeout example
  • Example#1138 - cubrid_get_server_info example
  • Example#1139 - cubrid_insert_id example
  • Example#1140 - cubrid_is_instance example
  • Example#1141 - cubrid_lob_close example
  • Example#1142 - cubrid_lob_export example
  • Example#1143 - cubrid_lob_get example
  • Example#1144 - cubrid_lob_send example
  • Example#1145 - cubrid_lob_size example
  • Example#1146 - cubrid_lob2_bind example
  • Example#1147 - cubrid_lob2_export example
  • Example#1148 - cubrid_lob2_export example
  • Example#1149 - cubrid_lob2_read example 1
  • Example#1150 - cubrid_lob2_read example 2
  • Example#1151 - cubrid_lob2_seek example
  • Example#1152 - cubrid_lob2_seek64 example
  • Example#1153 - cubrid_lob2_write example 1
  • Example#1154 - cubrid_lob2_write example 2
  • Example#1155 - cubrid_lock_read example
  • Example#1156 - cubrid_lock_write example
  • Example#1157 - cubrid_move_cursor example
  • Example#1158 - cubrid_next_result example
  • Example#1159 - cubrid_num_cols example
  • Example#1160 - cubrid_num_rows example
  • Example#1161 - cubrid_connect example
  • Example#1162 - cubrid_pconnect_with_url url without properties example
  • Example#1163 - cubrid_pconnect_with_url url with properties example
  • Example#1164 - cubrid_prepare example
  • Example#1165 - cubrid_put example
  • Example#1166 - cubrid_rollback example
  • Example#1167 - cubrid_schema example
  • Example#1168 - cubrid_seq_drop example
  • Example#1169 - cubrid_seq_insert example
  • Example#1170 - cubrid_seq_put example
  • Example#1171 - cubrid_set_add example
  • Example#1172 - cubrid_get_db_parameter example
  • Example#1173 - cubrid_set_drop example
  • Example#1174 - cubrid_version example
  • Example#1175 - cubrid_affected_rows example
  • Example#1176 - cubrid_client_encoding example
  • Example#1177 - cubrid_close example
  • Example#1178 - cubrid_data_seek example
  • Example#1179 - cubrid_db_name example
  • Example#1180 - cubrid_errno example
  • Example#1181 - cubrid_error example
  • Example#1182 - cubrid_fetch_array example
  • Example#1183 - cubrid_fetch_assoc example
  • Example#1184 - cubrid_fetch_field example
  • Example#1185 - cubrid_fetch_lengths example
  • Example#1186 - cubrid_fetch_object example
  • Example#1187 - cubrid_fetch_row example
  • Example#1188 - cubrid_field_flags example
  • Example#1189 - cubrid_field_len example
  • Example#1190 - cubrid_field_name example
  • Example#1191 - cubrid_field_seek example
  • Example#1192 - cubrid_field_table example
  • Example#1193 - cubrid_field_type example
  • Example#1194 - cubrid_list_dbs example
  • Example#1195 - cubrid_num_fields example
  • Example#1196 - cubrid_ping example
  • Example#1197 - Invalid Query
  • Example#1198 - Valid Query
  • Example#1199 - cubrid_real_escape_string example
  • Example#1200 - cubrid_result example
  • Example#1201 - cubrid_unbuffered_query example
  • Example#1202 - cubrid_load_from_glo example
  • Example#1203 - cubrid_new_glo example
  • Example#1204 - cubrid_save_to_glo example
  • Example#1205 - cubrid_send_glo example
  • Example#1206 - Inserting a record in a dBase database
  • Example#1207 - Closing a dBase database file
  • Example#1208 - Creating a dBase database file
  • Example#1209 - Showing header information for a dBase database file
  • Example#1210 - Listing all the registered members in the database
  • Example#1211 - dbase_numfields Example
  • Example#1212 - Looping over all the records of the database
  • Example#1213 - Opening a dBase database file
  • Example#1214 - Emptying a dBase database
  • Example#1215 - Updating a record in the database
  • Example#1216 - ibase_backup example
  • Example#1217 - ibase_backup example with arguments
  • Example#1218 - ibase_blob_get の例
  • Example#1219 - ibase_blob_import の例
  • Example#1220 - ibase_connect の例
  • Example#1221 - ibase_execute の例
  • Example#1222 - ibase_fetch_object の例
  • Example#1223 - ibase_field_info の例
  • Example#1224 - ibase_name_result の例
  • Example#1225 - ibase_num_fields の例
  • Example#1226 - ibase_query の例
  • Example#1227 - ibase_restore example
  • Example#1228 - ibase_restore example with arguments
  • Example#1229 - ibase_service_attach の例
  • Example#1230 - ibase_service_attach の例
  • Example#1231 - hostname/port を使った ibase_service_attach の例
  • Example#1232 - ibase_service_detach の例
  • Example#1233 - ibase_set_event_handler の例
  • Example#1234 - 接続の AUTOCOMMIT 値の取得
  • Example#1235 - 接続の AUTOCOMMIT 値の設定
  • Example#1236 - PHP 変数をプリペアドステートメントにバインドする
  • Example#1237 - IN および OUT パラメータを使用したストアドプロシージャのコール
  • Example#1238 - バイナリラージオブジェクト (BLOB) をファイルから直接挿入する
  • Example#1239 - db2_client_info の例
  • Example#1240 - 接続を閉じる
  • Example#1241 - 失敗した接続試行からの SQLSTATE の取得
  • Example#1242 - 失敗した接続試行からのエラーメッセージの取得
  • Example#1243 - カタログ接続の作成
  • Example#1244 - 非カタログ接続の作成
  • Example#1245 - 自動コミットをデフォルトで無効にした接続の作成
  • Example#1246 - i5/OS best performance
  • Example#1247 - 信頼済みコンテキストの使用
  • Example#1248 - db2_escape_string の例
  • Example#1249 - db2_exec でのテーブルの作成
  • Example#1250 - スクロール可能なカーソルでの SELECT 文の実行
  • Example#1251 - XML データを SQL の結果セットとして返す
  • Example#1252 - XML データの "JOIN"
  • Example#1253 - 大きな XML ドキュメントの一部を SQL データとして返す
  • Example#1254 - パラメータマーカを使用した SQL 文の準備と実行
  • Example#1255 - OUT パラメータを使用したストアドプロシージャのコール
  • Example#1256 - XML データを SQL の結果セットとして返す
  • Example#1257 - XML データの "JOIN"
  • Example#1258 - 大きな XML ドキュメントの一部を SQL データとして返す
  • Example#1259 - 前進のみのカーソルを使用して順に処理する
  • Example#1260 - スクロール可能なカーソルから、指定した行を db2_fetch_array で取得する
  • Example#1261 - 前進のみのカーソルを使用して順に処理する
  • Example#1262 - スクロール可能なカーソルから、指定した行を db2_fetch_assoc で取得する
  • Example#1263 - 前進のみのカーソルを使用して順に処理する
  • Example#1264 - スクロール可能なカーソルから、指定した行を db2_fetch_both で取得する
  • Example#1265 - db2_fetch_object の例
  • Example#1266 - 結果セットを順に処理する
  • Example#1267 - i5/OS recommended alternatives to db2_fetch_row/db2_result
  • Example#1268 - 接続リソースのパラメータの設定および取得
  • Example#1269 - db2_last_insert_id の例
  • Example#1270 - さまざまな型のデータの取得
  • Example#1271 - 複数の結果セットを返すストアドプロシージャをコールする
  • Example#1272 - 結果セットのフィールド数の取得
  • Example#1273 - 持続的接続の終了
  • Example#1274 - db2_pconnect の例
  • Example#1275 - 信頼済みコンテキストの使用
  • Example#1276 - パラメータマーカを使用した SQL 文の準備と実行
  • Example#1277 - db2_result の例
  • Example#1278 - DELETE 文のロールバック
  • Example#1279 - db2_server_info の例
  • Example#1280 - 接続リソースにひとつのパラメータを設定する
  • Example#1281 - 接続リソースに複数のパラメータを設定する
  • Example#1282 - 複数のパラメータを間違ったキーで設定する
  • Example#1283 - 複数のパラメータを間違った値で設定する
  • Example#1284 - 複数のパラメータを接続リソースに設定する (間違った型を指定する)
  • Example#1285 - 複数のパラメータを間違ったリソースに設定する
  • Example#1286 - すべてひとつにまとめる
  • Example#1287 - i5/OS カーソルは読み込み専用
  • Example#1288 - MongoDB\Driver\Manager::__construct basic example
  • Example#1289 - MongoDB\Driver\Manager::__construct basic examples
  • Example#1290 - MongoDB\Driver\Manager::executeBulkWrite example
  • Example#1291 - MongoDB\Driver\Manager::executeCommand with a command returning a single result document
  • Example#1292 - MongoDB\Driver\Manager::executeCommand with a command returning a cursor
  • Example#1293 - Limiting execution time for a command
  • Example#1294 - MongoDB\Driver\Manager::executeQuery example
  • Example#1295 - Limiting execution time for a query
  • Example#1296 - MongoDB\Driver\Manager::getReadConcern example
  • Example#1297 - MongoDB\Driver\Manager::getReadPreference example
  • Example#1298 - MongoDB\Driver\Manager::getServers example
  • Example#1299 - MongoDB\Driver\Manager::getWriteConcern example
  • Example#1300 - Composing MongoDB\Driver\Command to provide a helper to create collections
  • Example#1301 - MongoDB\Driver\Command::__construct example
  • Example#1302 - MongoDB\Driver\Command::__construct example
  • Example#1303 - MongoDB\Driver\Query::__construct example
  • Example#1304 - Mixed write operations are grouped by type
  • Example#1305 - Ordered write operations causing an error
  • Example#1306 - MongoDB\Driver\BulkWrite::__construct example
  • Example#1307 - MongoDB\Driver\BulkWrite::count example
  • Example#1308 - MongoDB\Driver\BulkWrite::delete example
  • Example#1309 - MongoDB\Driver\BulkWrite::insert example
  • Example#1310 - MongoDB\Driver\BulkWrite::update example
  • Example#1311 - Declare an API version on a manager
  • Example#1312 - Declare a strict API version on a manager
  • Example#1313 - MongoDB\Driver\WriteConcern::bsonSerialize with majority write concern
  • Example#1314 - MongoDB\Driver\WriteConcern::bsonSerialize with wtimeout and journal
  • Example#1315 - MongoDB\Driver\WriteConcern::__construct example
  • Example#1316 - MongoDB\Driver\WriteConcern::getJournal example
  • Example#1317 - MongoDB\Driver\WriteConcern::getW example
  • Example#1318 - MongoDB\Driver\WriteConcern::getWtimeout example
  • Example#1319 - MongoDB\Driver\WriteConcern::isDefault example
  • Example#1320 - MongoDB\Driver\ReadPreference::bsonSerialize with primary read preference
  • Example#1321 - MongoDB\Driver\ReadPreference::bsonSerialize with secondary read preference and tag sets
  • Example#1322 - MongoDB\Driver\ReadPreference::bsonSerialize with secondary read preference and max staleness
  • Example#1323 - MongoDB\Driver\ReadPreference::__construct example
  • Example#1324 - MongoDB\Driver\ReadPreference::getMaxStalenessSeconds example
  • Example#1325 - MongoDB\Driver\ReadPreference::getMode example
  • Example#1326 - MongoDB\Driver\ReadPreference::getModeString example
  • Example#1327 - MongoDB\Driver\ReadPreference::getTagSets example
  • Example#1328 - MongoDB\Driver\ReadConcern::bsonSerialize with empty read concern
  • Example#1329 - MongoDB\Driver\ReadConcern::bsonSerialize with local read concern
  • Example#1330 - MongoDB\Driver\ReadConcern::__construct example
  • Example#1331 - MongoDB\Driver\ReadConcern::getLevel example
  • Example#1332 - MongoDB\Driver\ReadConcern::isDefault example
  • Example#1333 - Reading a result set
  • Example#1334 - Reading a result set for a tailable cursor
  • Example#1335 - MongoDB\Driver\Cursor::getId example
  • Example#1336 - MongoDB\Driver\Cursor::getServer example
  • Example#1337 - MongoDB\Driver\Cursor::isDead example
  • Example#1338 - MongoDB\Driver\Cursor::setTypeMap example
  • Example#1339 - MongoDB\Driver\Cursor::toArray example
  • Example#1340 - MongoDB\Driver\CursorId::__toString example
  • Example#1341 - MongoDB\Driver\Server::getHost example
  • Example#1342 - MongoDB\Driver\Server::getInfo example
  • Example#1343 - MongoDB\Driver\Server::getLatency example
  • Example#1344 - MongoDB\Driver\Server::getPort example
  • Example#1345 - MongoDB\Driver\WriteConcernError::getCode example
  • Example#1346 - MongoDB\Driver\WriteConcernError::getInfo example
  • Example#1347 - MongoDB\Driver\WriteConcernError::getMessage example
  • Example#1348 - MongoDB\Driver\WriteError::getCode example
  • Example#1349 - MongoDB\Driver\WriteError::getIndex example
  • Example#1350 - MongoDB\Driver\WriteError::getMessage example
  • Example#1351 - MongoDB\Driver\WriteResult::getDeletedCount example
  • Example#1352 - MongoDB\Driver\WriteResult::getInsertedCount example
  • Example#1353 - MongoDB\Driver\WriteResult::getMatchedCount example
  • Example#1354 - MongoDB\Driver\WriteResult::getModifiedCount example
  • Example#1355 - MongoDB\Driver\WriteResult::getServer example
  • Example#1356 - MongoDB\Driver\WriteResult::getUpsertedCount example
  • Example#1357 - MongoDB\Driver\WriteResult::getUpsertedIds example
  • Example#1358 - MongoDB\Driver\WriteResult::getWriteConcernError example
  • Example#1359 - MongoDB\Driver\WriteResult::getWriteErrors with a single error
  • Example#1360 - MongoDB\Driver\WriteResult::getWriteErrors with multiple errors
  • Example#1361 - MongoDB\Driver\WriteResult::isAcknowledged with acknowledged write concern
  • Example#1362 - MongoDB\Driver\WriteResult::isAcknowledged with unacknowledged write concern
  • Example#1363 - MongoDB\BSON\fromJSON example
  • Example#1364 - MongoDB\BSON\fromPHP example
  • Example#1365 - MongoDB\BSON\toCanonicalExtendedJSON example
  • Example#1366 - MongoDB\BSON\toJSON example
  • Example#1367 - MongoDB\BSON\toPHP example
  • Example#1368 - MongoDB\BSON\toRelaxedExtendedJSON example
  • Example#1369 - MongoDB\BSON\Document::toCanonicalExtendedJSON example
  • Example#1370 - MongoDB\BSON\Document::toRelaxedExtendedJSON example
  • Example#1371 - MongoDB\BSON\Binary::__construct example
  • Example#1372 - MongoDB\BSON\Binary::getData example
  • Example#1373 - MongoDB\BSON\Binary::getType example
  • Example#1374 - MongoDB\BSON\Binary::__toString example
  • Example#1375 - MongoDB\BSON\Decimal128::__construct example
  • Example#1376 - MongoDB\BSON\Decimal128::__toString example
  • Example#1377 - MongoDB\BSON\Javascript::__construct example
  • Example#1378 - MongoDB\BSON\Javascript::getCode example
  • Example#1379 - MongoDB\BSON\Javascript::getScope example
  • Example#1380 - MongoDB\BSON\Javascript::__toString example
  • Example#1381 - MongoDB\BSON\MaxKey::__construct example
  • Example#1382 - MongoDB\BSON\MinKey::__construct example
  • Example#1383 - MongoDB\BSON\ObjectId::__construct example
  • Example#1384 - MongoDB\BSON\ObjectId::getTimestamp example
  • Example#1385 - MongoDB\BSON\ObjectId::__toString example
  • Example#1386 - MongoDB\BSON\Regex::__construct example
  • Example#1387 - MongoDB\BSON\Regex::getFlags example
  • Example#1388 - MongoDB\BSON\Regex::getPattern example
  • Example#1389 - MongoDB\BSON\Regex::__toString example
  • Example#1390 - MongoDB\BSON\Timestamp::__construct example
  • Example#1391 - MongoDB\BSON\Timestamp::__toString example
  • Example#1392 - MongoDB\BSON\UTCDateTime::__construct example
  • Example#1393 - MongoDB\BSON\UTCDatetime::toDateTime example
  • Example#1394 - MongoDB\BSON\UTCDatetime::toDateTimeImmutable example
  • Example#1395 - MongoDB\BSON\UTCDateTime::__toString example
  • Example#1396 - MongoDB\BSON\Serializable::bsonSerialize returning an associative array for root document
  • Example#1397 - MongoDB\BSON\Serializable::bsonSerialize returning a sequential array for root document
  • Example#1398 - MongoDB\BSON\Serializable::bsonSerialize returning an associative array for document field
  • Example#1399 - MongoDB\BSON\Serializable::bsonSerialize returning a sequential array for document field
  • Example#1400 - MongoDB\BSON\Unserializable::bsonUnserialize example
  • Example#1401 - MongoDB\BSON\Int64::__toString example
  • Example#1402 - MongoDB\Driver\Exception\WriteException::getWriteResult example
  • Example#1403 - MySQL 用 API の比較
  • Example#1404 - プリペアドステートメントの比較
  • Example#1405 - mysqlnd あるいは libmysqlclient を使う場合の configure コマンド
  • Example#1406 - 非バッファクエリの例: mysqli
  • Example#1407 - 非バッファクエリの例: pdo_mysql
  • Example#1408 - 文字セットを SQL で指定することによる問題
  • Example#1409 - 文字セットの設定: mysqli
  • Example#1410 - 文字セットの設定: pdo_mysql
  • Example#1411 - 古い mysql 拡張モジュールから移行する簡単な方法
  • Example#1412 - オブジェクト指向と手続き型のインターフェイス
  • Example#1413 - 悪いコーディングスタイル
  • Example#1414 - localhost が持つ特別な意味
  • Example#1415 - デフォルト値を設定する
  • Example#1416 - クエリを実行する
  • Example#1417 - バッファリングされた結果セットを操作する
  • Example#1418 - 結果セットをバッファリングせず、結果を操作する
  • Example#1419 - テキストプロトコルは、文字列を返すのがデフォルト
  • Example#1420 - mysqlnd と接続オプションを設定することで、ネイティブのデータ型を扱う
  • Example#1421 - プリペアドステートメント
  • Example#1422 - INSERT を一度だけ準備し、複数回実行する
  • Example#1423 - 複数INSERTを使い、クライアント・サーバー間の通信を減らす
  • Example#1424 - ネイティブのデータ型
  • Example#1425 - バインドされた値を出力する
  • Example#1426 - 結果を取得するために、mysqli_result を使う
  • Example#1427 - 柔軟に結果を読み取るために、バッファリングされた結果セットを使う
  • Example#1428 - ストアドプロシージャを呼び出す
  • Example#1429 - セッションの値を使う
  • Example#1430 - ストアドプロシージャから、結果を取得する
  • Example#1431 - ストアドプロシージャとプリペアドステートメント
  • Example#1432 - バインドAPIを使って、プリペアドステートメントとストアドプロシージャを実行する
  • Example#1433 - 複数のステートメント
  • Example#1434 - SQLインジェクション
  • Example#1435 - autocommit モードをSQL と API を使って設定する
  • Example#1436 - コミットとロールバック
  • Example#1437 - 結果セットのメタデータにアクセスする
  • Example#1438 - プリペアドステートメントのメタデータ
  • Example#1439 - $mysqli->affected_rows の例
  • Example#1440 - mysqli::autocommit の例
  • Example#1441 - mysqli::begin_transaction の例
  • Example#1442 - mysqli::change_user の例
  • Example#1443 - mysqli::character_set_name の例
  • Example#1444 - mysqli::close example
  • Example#1445 - $mysqli->connect_errno の例
  • Example#1446 - $mysqli->connect_error の例
  • Example#1447 - mysqli::__construct の例
  • Example#1448 - mysqli クラスを拡張する
  • Example#1449 - 手動によるエラーハンドリング
  • Example#1450 - トレースファイルの作成
  • Example#1451 - $mysqli->errno の例
  • Example#1452 - $mysqli->error の例
  • Example#1453 - $mysqli->error_list の例
  • Example#1454 - mysqli::execute_query の例
  • Example#1455 - $mysqli->field_count の例
  • Example#1456 - mysqli::get_charset の例
  • Example#1457 - mysqli_get_client_info
  • Example#1458 - mysqli_get_client_version
  • Example#1459 - mysqli_get_connection_stats の例
  • Example#1460 - $mysqli->host_info の例
  • Example#1461 - $mysqli->protocol_version の例
  • Example#1462 - $mysqli->server_info の例
  • Example#1463 - $mysqli->server_version の例
  • Example#1464 - $mysqli->info の例
  • Example#1465 - $mysqli->insert_id の例
  • Example#1466 - mysqli::kill の例
  • Example#1467 - mysqli::multi_query の例
  • Example#1468 - mysqli::ping の例
  • Example#1469 - mysqli_poll の例
  • Example#1470 - mysqli::prepare の例
  • Example#1471 - mysqli::query の例
  • Example#1472 - mysqli::real_connect の例
  • Example#1473 - mysqli::real_escape_string の例
  • Example#1474 - mysqli::select_db の例
  • Example#1475 - mysqli::set_charset の例
  • Example#1476 - $mysqli->sqlstate の例
  • Example#1477 - mysqli::stat の例
  • Example#1478 - $mysqli->thread_id の例
  • Example#1479 - mysqli::use_result の例
  • Example#1480 - $mysqli->warning_count の例
  • Example#1481 - mysqli_stmt_affected_rows の例
  • Example#1482 - mysqli_stmt::bind_param の例
  • Example#1483 - 引数を渡すために ... を使う
  • Example#1484 - オブジェクト指向型
  • Example#1485 - 手続き型
  • Example#1486 - オブジェクト指向型
  • Example#1487 - 手続き型
  • Example#1488 - オブジェクト指向型
  • Example#1489 - 手続き型
  • Example#1490 - オブジェクト指向型
  • Example#1491 - 手続き型
  • Example#1492 - オブジェクト指向型
  • Example#1493 - 手続き型
  • Example#1494 - プリペアドステートメントに値をバインドして実行する
  • Example#1495 - プリペアドステートメントに、値を配列で指定して実行する
  • Example#1496 - オブジェクト指向型
  • Example#1497 - 手続き型
  • Example#1498 - オブジェクト指向型
  • Example#1499 - 手続き型
  • Example#1500 - オブジェクト指向型
  • Example#1501 - 手続き型
  • Example#1502 - オブジェクト指向型
  • Example#1503 - 手続き型
  • Example#1504 - オブジェクト指向型
  • Example#1505 - 手続き型
  • Example#1506 - mysqli_stmt::prepare の例
  • Example#1507 -
  • Example#1508 - オブジェクト指向型
  • Example#1509 - 手続き型
  • Example#1510 - オブジェクト指向型
  • Example#1511 - オブジェクト指向型
  • Example#1512 - 手続き型
  • Example#1513 - オブジェクト指向型
  • Example#1514 - 手続き型
  • Example#1515 - mysqli_result オブジェクトを作る
  • Example#1516 - オブジェクト指向型
  • Example#1517 - 手続き型
  • Example#1518 - mysqli::data_seek の例
  • Example#1519 - 繰り返し処理を行う際に、結果セットのポインタを調整する
  • Example#1520 - mysqli_result::fetch_all の例
  • Example#1521 - mysqli_result::fetch_array の例
  • Example#1522 - mysqli_result::fetch_assoc の例
  • Example#1523 - mysqli_result, iterator, mysqli_result::fetch_assoc の使い方の比較
  • Example#1524 - mysqli_result::fetch_column の例
  • Example#1525 - オブジェクト指向型
  • Example#1526 - 手続き型
  • Example#1527 - オブジェクト指向型
  • Example#1528 - 手続き型
  • Example#1529 - オブジェクト指向型
  • Example#1530 - 手続き型
  • Example#1531 - mysqli_result::fetch_object の例
  • Example#1532 - mysqli_result::fetch_row の例
  • Example#1533 - オブジェクト指向型
  • Example#1534 - 手続き型
  • Example#1535 - オブジェクト指向型
  • Example#1536 - 手続き型
  • Example#1537 - オブジェクト指向型
  • Example#1538 - 手続き型
  • Example#1539 - オブジェクト指向型
  • Example#1540 - 手続き型
  • Example#1541 - オブジェクト指向型
  • Example#1542 - 手続き型
  • Example#1543 - インデックスに関するエラー以外を全て報告する
  • Example#1544 - A mysqli_get_client_stats の例
  • Example#1545 - MySQL Serverへの接続
  • Example#1546 - MySQL サーバー上で、スキーマとコレクションを作る
  • Example#1547 - データを保存し、取得する
  • Example#1548 - 複数の文書を取得し、それを走査する
  • Example#1549 - mysql_xdevapi\Expression の例
  • Example#1550 - URI の例
  • Example#1551 - mysql_xdevapi\getSession の例
  • Example#1552 - mysql_xdevapi\RowResult::getWarnings example
  • Example#1553 - mysql_xdevapi\RowResult::getWarningsCount の例
  • Example#1554 - mysql_xdevapi\Client::__construct の例
  • Example#1555 - mysql_xdevapi\Collection::add の例
  • Example#1556 - mysql_xdevapi\Collection::addOrReplaceOne の例
  • Example#1557 - mysql_xdevapi\Collection::getOne の例
  • Example#1558 - mysql_xdevapi\Collection::count の例
  • Example#1559 - mysql_xdevapi\Collection::createIndex の例
  • Example#1560 - mysql_xdevapi\Collection::dropIndex の例
  • Example#1561 - mysql_xdevapi\Collection::existsInDatabase の例
  • Example#1562 - mysql_xdevapi\Collection::find の例
  • Example#1563 - mysql_xdevapi\Collection::getName の例
  • Example#1564 - mysql_xdevapi\Collection::getOne の例
  • Example#1565 - mysql_xdevapi\Collection::getSchema の例
  • Example#1566 - mysql_xdevapi\Collection::getSession の例
  • Example#1567 - mysql_xdevapi\Collection::modify の例
  • Example#1568 - mysql_xdevapi\Collection::remove example
  • Example#1569 - mysql_xdevapi\Collection::removeOne の例
  • Example#1570 - mysql_xdevapi\Collection::replaceOne の例
  • Example#1571 - mysql_xdevapi\CollectionAdd::__construct の例
  • Example#1572 - mysql_xdevapi\CollectionAdd::execute の例
  • Example#1573 - mysql_xdevapi\CollectionFind::bind の例
  • Example#1574 - CollectionFind の例
  • Example#1575 - CollectionFind の例
  • Example#1576 - mysql_xdevapi\CollectionFind::fields の例
  • Example#1577 - mysql_xdevapi\CollectionFind::groupBy の例
  • Example#1578 - mysql_xdevapi\CollectionFind::having の例
  • Example#1579 - mysql_xdevapi\CollectionFind::limit の例
  • Example#1580 - mysql_xdevapi\CollectionFind::lockExclusive の例
  • Example#1581 - mysql_xdevapi\CollectionFind::lockShared の例
  • Example#1582 - mysql_xdevapi\CollectionFind::offset の例
  • Example#1583 - mysql_xdevapi\CollectionFind::sort の例
  • Example#1584 - mysql_xdevapi\CollectionModify::arrayAppend の例
  • Example#1585 - mysql_xdevapi\CollectionModify::arrayInsert の例
  • Example#1586 - mysql_xdevapi\CollectionModify::bind の例
  • Example#1587 - mysql_xdevapi\CollectionModify::__construct の例
  • Example#1588 - mysql_xdevapi\CollectionModify::execute の例
  • Example#1589 - mysql_xdevapi\CollectionModify::limit の例
  • Example#1590 - mysql_xdevapi\CollectionModify::patch の例
  • Example#1591 - mysql_xdevapi\CollectionModify::replace の例
  • Example#1592 - mysql_xdevapi\CollectionModify::set の例
  • Example#1593 - mysql_xdevapi\CollectionModify::skip の例
  • Example#1594 - mysql_xdevapi\CollectionModify::sort の例
  • Example#1595 - mysql_xdevapi\CollectionModify::unset の例
  • Example#1596 - mysql_xdevapi\CollectionRemove::bind の例
  • Example#1597 - mysql_xdevapi\Collection::remove の例
  • Example#1598 - mysql_xdevapi\CollectionRemove::execute の例
  • Example#1599 - mysql_xdevapi\CollectionRemove::limit example
  • Example#1600 - mysql_xdevapi\CollectionRemove::sort の例
  • Example#1601 - mysql_xdevapi\ColumnResult::__construct の例
  • Example#1602 - mysql_xdevapi\ColumnResult::getCharacterSetName の例
  • Example#1603 - mysql_xdevapi\ColumnResult::getCollationName の例
  • Example#1604 - mysql_xdevapi\ColumnResult::getColumnLabel の例
  • Example#1605 - mysql_xdevapi\ColumnResult::getColumnName の例
  • Example#1606 - mysql_xdevapi\ColumnResult::getFractionalDigits の例
  • Example#1607 - mysql_xdevapi\ColumnResult::getLength の例
  • Example#1608 - mysql_xdevapi\ColumnResult::getSchemaName の例
  • Example#1609 - mysql_xdevapi\ColumnResult::getTableLabel の例
  • Example#1610 - mysql_xdevapi\ColumnResult::getTableName の例
  • Example#1611 - mysql_xdevapi\ColumnResult::getType の例
  • Example#1612 - mysql_xdevapi\ColumnResult::isNumberSigned の例
  • Example#1613 - mysql_xdevapi\ColumnResult::isPadded の例
  • Example#1614 - mysql_xdevapi\CrudOperationBindable::bind の例
  • Example#1615 - mysql_xdevapi\CrudOperationLimitable::limit の例
  • Example#1616 - mysql_xdevapi\CrudOperationSkippable::skip の例
  • Example#1617 - mysql_xdevapi\CrudOperationSortable::sort の例
  • Example#1618 - mysql_xdevapi\DatabaseObject::existsInDatabase の例
  • Example#1619 - mysql_xdevapi\DatabaseObject::getName の例
  • Example#1620 - mysql_xdevapi\DatabaseObject::getSession の例
  • Example#1621 - DocResult の例
  • Example#1622 - mysql_xdevapi\DocResult::fetchAll の例
  • Example#1623 - mysql_xdevapi\DocResult::fetchOne の例
  • Example#1624 - mysql_xdevapi\DocResult::getWarnings の例
  • Example#1625 - mysql_xdevapi\DocResult::getWarningsCount の例
  • Example#1626 - execute() の例
  • Example#1627 - mysql_xdevapi\ExecutionStatus::__construct の例
  • Example#1628 - mysql_xdevapi\Expression::__construct の例
  • Example#1629 - mysql_xdevapi\Result::__construct の例
  • Example#1630 - mysql_xdevapi\Result::getAffectedItemsCount の例
  • Example#1631 - mysql_xdevapi\Result::getAutoIncrementValue の例
  • Example#1632 - mysql_xdevapi\Result::getGeneratedIds の例
  • Example#1633 - mysql_xdevapi\RowResult::getWarnings の例
  • Example#1634 - mysql_xdevapi\RowResult::getWarningsCount の例
  • Example#1635 - mysql_xdevapi\RowResult::__construct の例
  • Example#1636 - mysql_xdevapi\RowResult::fetchAll の例
  • Example#1637 - mysql_xdevapi\RowResult::fetchOne の例
  • Example#1638 - mysql_xdevapi\RowResult::getColumnsCount の例
  • Example#1639 - mysql_xdevapi\RowResult::getColumnNames の例
  • Example#1640 - mysql_xdevapi\RowResult::getColumns の例
  • Example#1641 - mysql_xdevapi\RowResult::getWarnings の例
  • Example#1642 - mysql_xdevapi\RowResult::getWarningsCount の例
  • Example#1643 - mysql_xdevapi\Schema::__construct の例
  • Example#1644 - mysql_xdevapi\Schema::createCollection の例
  • Example#1645 - mysql_xdevapi\Schema::createCollection の例
  • Example#1646 - mysql_xdevapi\Schema::dropCollection の例
  • Example#1647 - mysql_xdevapi\Schema::existsInDatabase の例
  • Example#1648 - mysql_xdevapi\Schema::getCollection の例
  • Example#1649 - mysql_xdevapi\Schema::getCollectionAsTable の例
  • Example#1650 - mysql_xdevapi\Schema::getCollections の例
  • Example#1651 - mysql_xdevapi\Schema::getName の例
  • Example#1652 - mysql_xdevapi\Schema::getSession の例
  • Example#1653 - mysql_xdevapi\Schema::getTable の例
  • Example#1654 - mysql_xdevapi\Schema::getTables の例
  • Example#1655 - mysql_xdevapi\Session::getSchema の例
  • Example#1656 - mysql_xdevapi\Session::close の例
  • Example#1657 - mysql_xdevapi\Session::commit の例
  • Example#1658 - mysql_xdevapi\Session::__construct の例
  • Example#1659 - mysql_xdevapi\Session::createSchema の例
  • Example#1660 - mysql_xdevapi\Session::dropSchema の例
  • Example#1661 - mysql_xdevapi\Session::generateUuid の例
  • Example#1662 - mysql_xdevapi\Session::getSchema の例
  • Example#1663 - mysql_xdevapi\Session::getSchema の例
  • Example#1664 - mysql_xdevapi\Session::getSchemas の例
  • Example#1665 - mysql_xdevapi\Session::getServerVersion の例
  • Example#1666 - mysql_xdevapi\Session::listClients の例
  • Example#1667 - mysql_xdevapi\Session::quoteName の例
  • Example#1668 - mysql_xdevapi\Session::releaseSavepoint の例
  • Example#1669 - mysql_xdevapi\Session::rollback の例
  • Example#1670 - mysql_xdevapi\Session::rollbackTo の例
  • Example#1671 - mysql_xdevapi\Session::setSavepoint の例
  • Example#1672 - mysql_xdevapi\Session::sql の例
  • Example#1673 - mysql_xdevapi\Session::startTransaction の例
  • Example#1674 - mysql_xdevapi\SqlStatement::bind の例
  • Example#1675 - mysql_xdevapi\SqlStatement::__construct の例
  • Example#1676 - mysql_xdevapi\SqlStatement::execute の例
  • Example#1677 - mysql_xdevapi\SqlStatement::getNextResult の例
  • Example#1678 - mysql_xdevapi\SqlStatement::getResult の例
  • Example#1679 - mysql_xdevapi\SqlStatement::hasMoreResults の例
  • Example#1680 - mysql_xdevapi\SqlStatementResult::__construct の例
  • Example#1681 - mysql_xdevapi\SqlStatementResult::fetchAll の例
  • Example#1682 - mysql_xdevapi\SqlStatementResult::fetchOne の例
  • Example#1683 - mysql_xdevapi\SqlStatementResult::getAffectedItemsCount の例
  • Example#1684 - mysql_xdevapi\SqlStatementResult::getColumnsCount の例
  • Example#1685 - mysql_xdevapi\SqlStatementResult::getColumnNames の例
  • Example#1686 - mysql_xdevapi\SqlStatementResult::getColumns の例
  • Example#1687 - mysql_xdevapi\SqlStatementResult::getGeneratedIds の例
  • Example#1688 - mysql_xdevapi\SqlStatementResult::getLastInsertId の例
  • Example#1689 - mysql_xdevapi\SqlStatementResult::getWarnings の例
  • Example#1690 - mysql_xdevapi\SqlStatementResult::getWarningsCount の例
  • Example#1691 - mysql_xdevapi\SqlStatementResult::hasData の例
  • Example#1692 - mysql_xdevapi\SqlStatementResult::nextResult の例
  • Example#1693 - mysql_xdevapi\Statement::__construct の例
  • Example#1694 - mysql_xdevapi\Statement::getNextResult の例
  • Example#1695 - mysql_xdevapi\Statement::getResult の例
  • Example#1696 - mysql_xdevapi\Statement::hasMoreResults の例
  • Example#1697 - mysql_xdevapi\Table::__construct の例
  • Example#1698 - mysql_xdevapi\Table::count の例
  • Example#1699 - mysql_xdevapi\Table::delete の例
  • Example#1700 - mysql_xdevapi\Table::existsInDatabase の例
  • Example#1701 - mysql_xdevapi\Table::getName の例
  • Example#1702 - mysql_xdevapi\Table::getSchema の例
  • Example#1703 - mysql_xdevapi\Table::getSession の例
  • Example#1704 - mysql_xdevapi\Table::insert の例
  • Example#1705 - mysql_xdevapi\Table::isView の例
  • Example#1706 - mysql_xdevapi\Table::count の例
  • Example#1707 - mysql_xdevapi\Table::update の例
  • Example#1708 - mysql_xdevapi\TableDelete::bind の例
  • Example#1709 - mysql_xdevapi\TableDelete::__construct の例
  • Example#1710 - mysql_xdevapi\TableDelete::execute の例
  • Example#1711 - mysql_xdevapi\TableDelete::limit の例
  • Example#1712 - mysql_xdevapi\TableDelete::orderBy の例
  • Example#1713 - mysql_xdevapi\TableDelete::where の例
  • Example#1714 - mysql_xdevapi\TableInsert::__construct の例
  • Example#1715 - mysql_xdevapi\TableInsert::execute の例
  • Example#1716 - mysql_xdevapi\TableInsert::values の例
  • Example#1717 - mysql_xdevapi\TableSelect::bind の例
  • Example#1718 - mysql_xdevapi\TableSelect::__construct の例
  • Example#1719 - mysql_xdevapi\TableSelect::execute の例
  • Example#1720 - mysql_xdevapi\TableSelect::groupBy の例
  • Example#1721 - mysql_xdevapi\TableSelect::having の例
  • Example#1722 - mysql_xdevapi\TableSelect::limit の例
  • Example#1723 - mysql_xdevapi\TableSelect::lockExclusive の例
  • Example#1724 - mysql_xdevapi\TableSelect::lockShared の例
  • Example#1725 - mysql_xdevapi\TableSelect::offset の例
  • Example#1726 - mysql_xdevapi\TableSelect::orderBy の例
  • Example#1727 - mysql_xdevapi\TableSelect::where の例
  • Example#1728 - mysql_xdevapi\TableUpdate::bind の例
  • Example#1729 - mysql_xdevapi\TableUpdate::__construct の例
  • Example#1730 - mysql_xdevapi\TableUpdate::execute の例
  • Example#1731 - mysql_xdevapi\TableUpdate::limit の例
  • Example#1732 - mysql_xdevapi\TableUpdate::orderby の例
  • Example#1733 - mysql_xdevapi\TableUpdate::set の例
  • Example#1734 - mysql_xdevapi\TableUpdate::where の例
  • Example#1735 - mysql_xdevapi\Warning::__construct の例
  • Example#1736 - MySQL 拡張モジュールに関する例
  • Example#1737 - mysql_affected_rows の例
  • Example#1738 - トランザクションを利用した mysql_affected_rows の例
  • Example#1739 - mysql_client_encoding の例
  • Example#1740 - mysql_close の例
  • Example#1741 - mysql_connect の例
  • Example#1742 - mysql_connect で hostname:port 構文を使用する例
  • Example#1743 - mysql_connect で ":/path/to/socket" 構文を使用する例
  • Example#1744 - mysql_create_db の別の例
  • Example#1745 - mysql_data_seek の例
  • Example#1746 - mysql_db_name の例
  • Example#1747 - mysql_db_query の別の例
  • Example#1748 - mysql_drop_db の別の例
  • Example#1749 - mysql_errno の例
  • Example#1750 - mysql_error の例
  • Example#1751 - mysql_escape_string の例
  • Example#1752 - 重複した列名に対して別名を定義する問い合わせ
  • Example#1753 - mysql_fetch_array を MYSQL_NUM とともに利用する
  • Example#1754 - mysql_fetch_array を MYSQL_ASSOC とともに利用する
  • Example#1755 - mysql_fetch_array を MYSQL_BOTH とともに利用する
  • Example#1756 - mysql_fetch_assoc のいろいろな例
  • Example#1757 - mysql_fetch_field の例
  • Example#1758 - mysql_fetch_lengths の例
  • Example#1759 - mysql_fetch_object の例
  • Example#1760 - mysql_fetch_object の例
  • Example#1761 - mysql_fetch_row で行を取得する
  • Example#1762 - mysql_field_flags の例
  • Example#1763 - mysql_field_len の例
  • Example#1764 - mysql_field_name の例
  • Example#1765 - mysql_field_table の例
  • Example#1766 - mysql_field_type の例
  • Example#1767 - mysql_free_result の例
  • Example#1768 - mysql_get_client_info の例
  • Example#1769 - mysql_get_host_info の例
  • Example#1770 - mysql_get_proto_info の例
  • Example#1771 - mysql_get_server_info の例
  • Example#1772 - 該当する MySQL 文
  • Example#1773 - mysql_insert_id の例
  • Example#1774 - mysql_list_dbs の例
  • Example#1775 - 非推奨である mysql_list_fields の代替例
  • Example#1776 - mysql_list_processes の例
  • Example#1777 - mysql_list_tables の別の例
  • Example#1778 - mysql_num_fields の例
  • Example#1779 - mysql_num_rows の例
  • Example#1780 - mysql_ping の例
  • Example#1781 - 間違ったクエリ
  • Example#1782 - 正しいクエリ
  • Example#1783 - 単純な mysql_real_escape_string の例
  • Example#1784 - mysql_real_escape_string には接続が必須であることを示す例
  • Example#1785 - SQL インジェクション攻撃の例
  • Example#1786 - mysql_result の例
  • Example#1787 - mysql_select_db の例
  • Example#1788 - mysql_stat の例
  • Example#1789 - mysql_stat の別の例
  • Example#1790 - mysql_tablename の例
  • Example#1791 - mysql_thread_id の例
  • Example#1792 - Examples of code snippets that cause an explicit close
  • Example#1793 - Examples of code snippets that cause an implicit close
  • Example#1794 - Usage examples
  • Example#1795 - 基本的なクエリ
  • Example#1796 - バインド変数を用いた挿入
  • Example#1797 - クエリの WHERE 句でのバインド
  • Example#1798 - CLOB カラムにデータを挿入する
  • Example#1799 - PL/SQL ストアドファンクションの使用
  • Example#1800 - PL/SQL ストアドプロシージャの使用
  • Example#1801 - REF CURSOR を返す PL/SQL ファンクションのコール
  • Example#1802 - Registering a TAF callback
  • Example#1803 - DTrace を使用して すべてのユーザーレベルの PHP OCI8 静的プローブをトレースするための user_oci8_probes.d
  • Example#1804 - oci_bind_array_by_name の例
  • Example#1805 - oci_bind_by_name によるデータの挿入
  • Example#1806 - 一度組み立てたものを複数回実行
  • Example#1807 - foreach ループでのバインド
  • Example#1808 - WHERE 句でのバインド
  • Example#1809 - LIKE 句でのバインド
  • Example#1810 - REGEXP_LIKE でのバインド
  • Example#1811 - IN 句での複数の値のバインド
  • Example#1812 - クエリが返す ROWID のバインド
  • Example#1813 - INSERT での ROWID のバインド
  • Example#1814 - PL/SQL ストアドファンクションでのバインド
  • Example#1815 - PL/SQL ストアドプロシージャでのパラメータのバインド
  • Example#1816 - CLOB 列のバインド
  • Example#1817 - PL/SQL の BOOLEAN のバインド
  • Example#1818 - oci_client_version の例
  • Example#1819 - 接続を閉じる
  • Example#1820 - 参照の全てが閉じられるまでデータベース接続は閉じられません
  • Example#1821 - 一回以上開かれた接続を閉じる
  • Example#1822 - 変数がスコープから外れると接続が閉じられます
  • Example#1823 - oci_commit の例
  • Example#1824 - Easy Connect 構文を使った基本的な oci_connect の使用例
  • Example#1825 - Network Connect 名を使った基本的な oci_connect の使用例
  • Example#1826 - oci_connect での明示的な文字セットの指定
  • Example#1827 - oci_connect での複数コールの使用
  • Example#1828 - oci_define_by_name の例
  • Example#1829 - oci_define_by_name での大文字小文字を区別するカラム名の使用
  • Example#1830 - oci_define_by_name での LOB カラムの使用
  • Example#1831 - oci_define_by_name での型の明示
  • Example#1832 - 接続エラー後の Oracle エラーメッセージの表示
  • Example#1833 - パースエラー時の Oracle エラーメッセージの表示
  • Example#1834 - 実行エラー時の、 Oracle エラーメッセージと問題となった文の表示
  • Example#1835 - oci_execute での問い合わせの例
  • Example#1836 - モードを指定せずに oci_execute を実行する例
  • Example#1837 - oci_execute で OCI_NO_AUTO_COMMIT を使う例
  • Example#1838 - oci_execute でさまざまなコミットモードを使う例
  • Example#1839 - oci_execute で OCI_DESCRIBE_ONLY を使う例
  • Example#1840 - oci_fetch での定義済みの変数の使用
  • Example#1841 - oci_fetch と oci_result の使用例
  • Example#1842 - oci_fetch_all の例
  • Example#1843 - oci_fetch_all で OCI_FETCHSTATEMENT_BY_ROW を使う例
  • Example#1844 - oci_fetch_all で OCI_NUM を使う例
  • Example#1845 - oci_fetch_array での OCI_BOTH の使用例
  • Example#1846 - oci_fetch_array での OCI_NUM の使用例
  • Example#1847 - oci_fetch_array での OCI_ASSOC の使用例
  • Example#1848 - oci_fetch_array での OCI_RETURN_NULLS の使用例
  • Example#1849 - oci_fetch_array での OCI_RETURN_LOBS の使用例
  • Example#1850 - oci_fetch_array での文字の大小を区別するカラムの使用例
  • Example#1851 - oci_fetch_array での同じ名前のカラムの使用例
  • Example#1852 - oci_fetch_array での DATE カラムの使用例
  • Example#1853 - oci_fetch_array での REF CURSOR の使用例
  • Example#1854 - oci_fetch_array での LIMIT 風のクエリによるページング
  • Example#1855 - oci_fetch_array で Oracle Database の暗黙の結果セットを使う例
  • Example#1856 - oci_fetch_assoc の例
  • Example#1857 - oci_fetch_object の例
  • Example#1858 - 文字の大小を区別するカラム名を持つ oci_fetch_object
  • Example#1859 - LOB を持つ oci_fetch_object
  • Example#1860 - oci_fetch_row の例
  • Example#1861 - oci_field_name の例
  • Example#1862 - oci_field_name の例
  • Example#1863 - oci_field_precision の例
  • Example#1864 - oci_field_scale の例
  • Example#1865 - oci_field_size の例
  • Example#1866 - oci_field_type の例
  • Example#1867 - oci_field_type_raw の例
  • Example#1868 - ループ内で暗黙の結果セットを取得
  • Example#1869 - 子ステートメントのハンドラをそれぞれ取得
  • Example#1870 - プリフェッチ数を明示的に設定
  • Example#1871 - oci_get_implicit_resultset を使用しない暗黙の結果セットの例
  • Example#1872 - oci_new_connect の例
  • Example#1873 - Oracle ストアドプロシージャにおける REF CURSOR のバインド
  • Example#1874 - oci_new_descriptor の例
  • Example#1875 - oci_new_descriptor の例
  • Example#1876 - oci_num_fields の例
  • Example#1877 - oci_num_rows の例
  • Example#1878 - oci_parse での SQL 文の例
  • Example#1879 - oci_parse での PL/SQL の例
  • Example#1880 - oci_password_change で、接続中のユーザーのパスワードを変更する例
  • Example#1881 - oci_password_change で、接続とパスワードの変更を一度に行う例
  • Example#1882 - Easy Connect 構文を使った oci_pconnect の例
  • Example#1883 - oci_fetch と oci_result を組み合わせる例
  • Example#1884 - oci_rollback の例
  • Example#1885 - SAVEPOINT へのロールバックの例
  • Example#1886 - oci_server_version の例
  • Example#1887 - アクションを設定する
  • Example#1888 - Setting the timeout
  • Example#1889 - クライアント識別子をアプリケーションのユーザーに設定する
  • Example#1890 - クライアント情報を設定する
  • Example#1891 - Setting the DBOP
  • Example#1892 - 異なるバージョンの myfunc() が利用できる例
  • Example#1893 - モジュール名を設定する
  • Example#1894 - クエリのデフォルトプリフェッチ値の変更
  • Example#1895 - REF CURSOR のデフォルトプリフェッチの変更
  • Example#1896 - REF CURSOR を Oracle に戻すときのプリフェッチの設定
  • Example#1897 - LOB のプリフェッチサイズをクエリ毎に変更する
  • Example#1898 - oci_statement_type の例
  • Example#1899 - PostgreSQL 拡張モジュールの概要
  • Example#1900 - PostgreSQL のユーザー定義関数の例
  • Example#1901 - pg_affected_rows の例
  • Example#1902 - pg_cancel_query の例
  • Example#1903 - pg_client_encoding の例
  • Example#1904 - pg_close の例
  • Example#1905 - pg_connect の使用法
  • Example#1906 - pg_connection_busy の例
  • Example#1907 - pg_connection_reset の例
  • Example#1908 - pg_connection_status の例
  • Example#1909 - pg_convert の例
  • Example#1910 - pg_copy_from の例
  • Example#1911 - pg_copy_to の例
  • Example#1912 - pg_dbname の例
  • Example#1913 - pg_delete の例
  • Example#1914 - pg_end_copy の例
  • Example#1915 - pg_escape_bytea の例
  • Example#1916 - pg_escape_identifier の例
  • Example#1917 - pg_escape_literal の例
  • Example#1918 - pg_escape_string の例
  • Example#1919 - pg_execute の使用法
  • Example#1920 - PostgreSQL fetch all
  • Example#1921 - pg_fetch_all_columns の例
  • Example#1922 - pg_fetch_array の例
  • Example#1923 - pg_fetch_assoc の例
  • Example#1924 - pg_fetch_object の例
  • Example#1925 - pg_fetch_result の例
  • Example#1926 - pg_fetch_row の例
  • Example#1927 - pg_field_is_null の例
  • Example#1928 - フィールド情報を取得する
  • Example#1929 - フィールドの情報を取得する
  • Example#1930 - フィールドの情報を取得する
  • Example#1931 - フィールドの情報を取得する
  • Example#1932 - フィールドについてのテーブル情報の取得
  • Example#1933 - フィールドの情報を取得する
  • Example#1934 - フィールドの情報を得る
  • Example#1935 - pg_free_result の例
  • Example#1936 - PostgreSQL NOTIFY メッセージ
  • Example#1937 - PostgreSQL バックエンドの PID
  • Example#1938 - pg_get_result の例
  • Example#1939 - pg_host の例
  • Example#1940 - pg_insert の例
  • Example#1941 - pg_last_error の例
  • Example#1942 - pg_last_notice の例
  • Example#1943 - pg_last_oid の例
  • Example#1944 - pg_lo_close example
  • Example#1945 - pg_lo_create の例
  • Example#1946 - pg_lo_export の例
  • Example#1947 - pg_lo_import の例
  • Example#1948 - pg_lo_open の例
  • Example#1949 - pg_lo_read の例
  • Example#1950 - pg_lo_read_all の例
  • Example#1951 - pg_lo_seek の例
  • Example#1952 - pg_lo_tell の例
  • Example#1953 - pg_lo_truncate の例
  • Example#1954 - pg_lo_unlink の例
  • Example#1955 - pg_lo_write の例
  • Example#1956 - テーブルのメタデータを得る
  • Example#1957 - pg_num_fields の例
  • Example#1958 - pg_num_rows の例
  • Example#1959 - pg_options の例
  • Example#1960 - pg_parameter_status の例
  • Example#1961 - pg_pconnect の使用法
  • Example#1962 - pg_ping の例
  • Example#1963 - pg_port の例
  • Example#1964 - pg_prepare の使用法
  • Example#1965 - pg_put_line の例
  • Example#1966 - pg_query の例
  • Example#1967 - pg_query で複数の文を使用する例
  • Example#1968 - pg_query_params の使用法
  • Example#1969 - pg_result_error の例
  • Example#1970 - pg_result_error_field の例
  • Example#1971 - pg_result_seek の例
  • Example#1972 - pg_result_status の例
  • Example#1973 - pg_select の例
  • Example#1974 - pg_send_execute の使用法
  • Example#1975 - pg_send_prepare の使用法
  • Example#1976 - pg_send_query の例
  • Example#1977 - pg_send_query_params の使用法
  • Example#1978 - pg_set_client_encoding の例
  • Example#1979 - pg_set_error_context_visibility の例
  • Example#1980 - pg_set_error_verbosity の例
  • Example#1981 - pg_trace の例
  • Example#1982 - pg_transaction_status の例
  • Example#1983 - pg_tty の例
  • Example#1984 - pg_unescape_bytea の例
  • Example#1985 - pg_untrace の例
  • Example#1986 - pg_update の例
  • Example#1987 - pg_version の例
  • Example#1988 - 既存のデータベースをバックアップする
  • Example#1989 - SQLite3::changes の例
  • Example#1990 - SQLite3::close の例
  • Example#1991 - SQLite3::__construct の例
  • Example#1992 - max_length 集約関数の例
  • Example#1993 - SQLite3::createCollation の例
  • Example#1994 - SQLite3::createFunction の例
  • Example#1995 - SQLite3::enableExceptions の例
  • Example#1996 - SQLite3::exec の例
  • Example#1997 - SQLite3::loadExtension の例
  • Example#1998 - SQLite3::open の例
  • Example#1999 - SQLite3::openBlob の例
  • Example#2000 - インクリメンタルにBLOBに書き込む
  • Example#2001 - SQLite3::prepare の例
  • Example#2002 - SQLite3::query の例
  • Example#2003 - SQLite3::querySingle の例
  • Example#2004 - SQLite3::setAuthorizer の例
  • Example#2005 - SQLite3::version の例
  • Example#2006 - SQLite3Stmt::bindParam の使い方
  • Example#2007 - SQLite3Stmt::bindValue の例
  • Example#2008 - 展開済みのSQLを調べる
  • Example#2009 - sqlsrv_begin_transaction example
  • Example#2010 - sqlsrv_cancel example
  • Example#2011 - sqlsrv_client_info example
  • Example#2012 - sqlsrv_close example
  • Example#2013 - sqlsrv_commit example
  • Example#2014 - Connect using Windows Authentication.
  • Example#2015 - Connect by specifying a user name and password.
  • Example#2016 - Connect on a specified port.
  • Example#2017 - functionname example
  • Example#2018 - sqlsrv_execute example
  • Example#2019 - sqlsrv_fetch example
  • Example#2020 - 連想配列を扱う場合の例
  • Example#2021 - 配列を扱う場合の例
  • Example#2022 - sqlsrv_fetch_object example
  • Example#2023 - sqlsrv_field_metadata example
  • Example#2024 - sqlsrv_free_stmt example
  • Example#2025 - sqlsrv_get_field example
  • Example#2026 - sqlsrv_has_rows example
  • Example#2027 - sqlsrv_next_result example
  • Example#2028 - sqlsrv_num_fields example
  • Example#2029 - sqlsrv_num_rows example
  • Example#2030 - sqlsrv_prepare example
  • Example#2031 - sqlsrv_query example
  • Example#2032 - sqlsrv_rollback example
  • Example#2033 - sqlsrv_rows_affected example
  • Example#2034 - sqlsrv_send_stream_data example
  • Example#2035 - sqlsrv_server_info example
  • Example#2036 - cal_days_in_month の例
  • Example#2037 - cal_from_jd の例
  • Example#2038 - cal_info の例
  • Example#2039 - easter_date の例
  • Example#2040 - easter_date を DateTime と一緒に使う
  • Example#2041 - easter_days の例
  • Example#2042 - カレンダー関数
  • Example#2043 - Overflow behavior
  • Example#2044 - jdtojewish の例
  • Example#2045 - DateTimeImmutable::add/sub は、経過時間を含む区間を足してしまう
  • Example#2046 - DateTimeImmutable::modify と strtotime を使い、個々のコンポーネントの値をインクリメント/デクリメントする
  • Example#2047 - 時刻を引き算すると、日付がオーバー/アンダーフローする可能性がある
  • Example#2048 - 変更可能な日付オブジェクトを作る
  • Example#2049 - 変更可能な DateTime オブジェクトを作る
  • Example#2050 - DateTime::modify の例
  • Example#2051 - 月の加減算には注意
  • Example#2052 - 全ての日付と時刻のフォーマットがサポートされています
  • Example#2053 - DateTime::setTimeZone の例
  • Example#2054 - DateTimeImmutable::add の例
  • Example#2055 - DateTimeImmutable::add の高度な例
  • Example#2056 - 月を足す場合は注意
  • Example#2057 - DateTimeImmutable::__construct の例
  • Example#2058 - DateTimeImmutable::__construct の複雑な例
  • Example#2059 - 関連付けられたタイムゾーンを変更する
  • Example#2060 - 相対日付/時刻 の文字列を使う
  • Example#2061 - DateTimeImmutable::createFromFormat の例
  • Example#2062 - 定義済みのフォーマットの定数を DateTimeImmutable::createFromFormat で使う
  • Example#2063 - DateTimeImmutable::createFromFormat の複雑な例
  • Example#2064 - リテラル文字を含む書式文字列
  • Example#2065 - オーバーフローした際のふるまい
  • Example#2066 - 曜日がオーバーフローした場合のふるまい
  • Example#2067 - オーバーフローした日付を検出する
  • Example#2068 - 貪欲なパースの振る舞い
  • Example#2069 - DateTimeImmutable オブジェクトを作る
  • Example#2070 - 変更不能な日付オブジェクトを作る
  • Example#2071 - DateTimeImmutable::getLastErrors の例
  • Example#2072 - DateTimeImmutable::modify の例
  • Example#2073 - 月の加減算には注意
  • Example#2074 - DateTimeImmutable::setDate の例
  • Example#2075 - 範囲を超えた値が親の値に加算される例
  • Example#2076 - DateTimeImmutable::setISODate の例
  • Example#2077 - 範囲を超えた値が親の値に加算される例
  • Example#2078 - その週が存在する月を探す例
  • Example#2079 - DateTimeImmutable::setTime の例
  • Example#2080 - 範囲を超えた値が親の値に加算される例
  • Example#2081 - DateTimeImmutable::setTimestamp の例
  • Example#2082 - DateTimeImmutable::setTimeZone の例
  • Example#2083 - DateTimeImmutable::sub の例
  • Example#2084 - DateTimeImmutable::sub の別な例
  • Example#2085 - 月を減算する際は注意
  • Example#2086 - DateTimeImmutable::diff の例
  • Example#2087 - 夏時間の切り替え期間中の DateTimeInterface::diff の動き
  • Example#2088 - DateTimeInterface::diff range
  • Example#2089 - DateTime オブジェクトの比較
  • Example#2090 - DateTimeInterface::format の例
  • Example#2091 - 例をもう少し
  • Example#2092 - フォーマット中に文字をエスケープする
  • Example#2093 - DateTime::getOffset の例
  • Example#2094 - DateTime::getTimestamp の例
  • Example#2095 - ミリ秒とマイクロ秒の精度でタイムスタンプを取得する
  • Example#2096 - DateTime::getTimezone の例
  • Example#2097 - DateTimeZone を作成し、DateTimeImmutable に設定する
  • Example#2098 - DateTimeZone のインスタンスを作成する際のエラー処理
  • Example#2099 - DateTimeZone::getLocation の例
  • Example#2100 - DateTimeZone::getOffset の例
  • Example#2101 - timezone_transitions_get の例
  • Example#2102 - timestampBegin を設定して timezone_transitions_get を使う例
  • Example#2103 - timezone_abbreviations_list の例
  • Example#2104 - DateTimeZone::listIdentifiers の例
  • Example#2105 - 特定の地域を指定して、識別子の一覧を取得する
  • Example#2106 - 複数の地域を指定して、識別子の一覧を取得する
  • Example#2107 - 特定の国をひとつ指定して、識別子の一覧を取得する
  • Example#2108 - DateInterval オブジェクトを作成して使う例
  • Example#2109 - DateInterval の例
  • Example#2110 - 日付の間隔のパース
  • Example#2111 - パース処理の組み合わせと、負の間隔
  • Example#2112 - 特別な相対書式の間隔をパースする
  • Example#2113 - DateInterval の例
  • Example#2114 - DateInterval での繰り越しの例
  • Example#2115 - DateInterval および DateTime::diff での修飾子 %a および %d
  • Example#2116 - DatePeriod の例
  • Example#2117 - DatePeriod で DatePeriod::EXCLUDE_START_DATE を使う例
  • Example#2118 - 一年間に含まれる、月の最後の木曜日を全て表示する、DatePeriod の例
  • Example#2119 - DatePeriod::createFromISO8601String の例
  • Example#2120 - DatePeriod::getDateInterval の例
  • Example#2121 - DatePeriod::getEndDate の例
  • Example#2122 - 終了日のない DatePeriod::getEndDate
  • Example#2123 - DatePeriod::getRecurrences が異なる値を返す例
  • Example#2124 - DatePeriod::getStartDate の例
  • Example#2125 - checkdate の例
  • Example#2126 - date の例
  • Example#2127 - date の文字をエスケープする
  • Example#2128 - date と mktime の例
  • Example#2129 - date のフォーマット指定
  • Example#2130 - デフォルトのタイムゾーンの取得
  • Example#2131 - タイムゾーンの短縮名の取得
  • Example#2132 - デフォルトのタイムゾーンの取得
  • Example#2133 - datetime に包括的な情報を指定した date_parse の例
  • Example#2134 - タイムゾーンの省略形を与えた場合の date_parse の例
  • Example#2135 - タイムゾーン情報を与えた date_parse の例
  • Example#2136 - 最低限の文字列だけを与えた date_parse の例
  • Example#2137 - "relative" フォーマットを使った date_parse の例
  • Example#2138 - date_parse の副作用
  • Example#2139 - date_parse_from_format の例
  • Example#2140 - date_parse_from_format の結果に警告が含まれる例
  • Example#2141 - date_parse_from_format の結果にエラーが含まれる例
  • Example#2142 - date_sun_info の例
  • Example#2143 - 極夜のデータに処理を少し行う例
  • Example#2144 - Midnight sun の例(Tromsø, Norway)
  • Example#2145 - 一日の長さを計算する例 (Kyiv)
  • Example#2146 - date_sunrise の例
  • Example#2147 - No sunrise
  • Example#2148 - date_sunset の例
  • Example#2149 - No sunset
  • Example#2150 - getdate の例
  • Example#2151 - gettimeofday の例
  • Example#2152 - gmdate の例
  • Example#2153 - gmmktime の基本的な例
  • Example#2154 - gmstrftime の例
  • Example#2155 - idate の例
  • Example#2156 - time の例
  • Example#2157 - タイマスクリプト実行
  • Example#2158 - microtime と REQUEST_TIME_FLOAT の例
  • Example#2159 - mktime の基本的な例
  • Example#2160 - mktime の例
  • Example#2161 - 月の末日
  • Example#2162 - strftime のロケールの例
  • Example#2163 - ISO 8601:1988 の週番号の例
  • Example#2164 - %e 修飾子を使う、クロスプラットフォーム対応の例
  • Example#2165 - すべての書式の表示
  • Example#2166 - strptime の例
  • Example#2167 - strtotime の例
  • Example#2168 - 失敗のチェック
  • Example#2169 - time の例
  • Example#2170 - timezone_name_from_abbr の例
  • Example#2171 - timezonedb のバージョンの取得
  • Example#2172 - Measure several code blocks execution and get the total
  • Example#2173 - 開いているファイル記述子を閉じる
  • Example#2174 - ロックの設定と解除
  • Example#2175 - ファイル記述子をオープンする
  • Example#2176 - ファイル内の位置の指定
  • Example#2177 - シリアルポートのボーレートを設定する
  • Example#2178 - chdir の例
  • Example#2179 - chroot の例
  • Example#2180 - closedir の例
  • Example#2181 - dir の例
  • Example#2182 - getcwd の例
  • Example#2183 - opendir の例
  • Example#2184 - ディレクトリ内の全てのエントリのリストを得る
  • Example#2185 - カレントディレクトリの全てのエントリを一覧する。ただし . および .. は取り除く
  • Example#2186 - scandir の簡単な例
  • Example#2187 - finfo_buffer の例
  • Example#2188 - finfo_file の例
  • Example#2189 - オブジェクト指向型
  • Example#2190 - 手続き型
  • Example#2191 - mime_content_type の例
  • Example#2192 - basename の例
  • Example#2193 - ファイルのグループの変更
  • Example#2194 - シンプルな chown の例
  • Example#2195 - clearstatcache の例
  • Example#2196 - copy の例
  • Example#2197 - dirname の例
  • Example#2198 - disk_free_space の例
  • Example#2199 - disk_total_space の例
  • Example#2200 - シンプルな fclose の例
  • Example#2201 - fdatasync の例
  • Example#2202 - feof のタイムアウト処理
  • Example#2203 - feof に無効なファイルポインタを使用する例
  • Example#2204 - fflush を使用するファイル書き込みの例
  • Example#2205 - fgetc の例
  • Example#2206 - CSV ファイルの全てのコンテンツを読み込み、表示する
  • Example#2207 - 行毎にファイルを読み込む
  • Example#2208 - PHP ファイルの 1 行ごとの読み込み
  • Example#2209 - file の例
  • Example#2210 - あるファイルが存在するかどうか調べる
  • Example#2211 - とあるウェブサイトのホームページのソースの取得と出力
  • Example#2212 - include_path の検索
  • Example#2213 - ファイルの一部の読み込み
  • Example#2214 - ストリームコンテキストの使用
  • Example#2215 - シンプルな使用例
  • Example#2216 - フラグの使用
  • Example#2217 - fileatime の例
  • Example#2218 - filectime の例
  • Example#2219 - ファイルのグループの取得
  • Example#2220 - 現在のファイルとのファイルの inode の比較
  • Example#2221 - filemtime の例
  • Example#2222 - ファイルの所有者の取得
  • Example#2223 - 八進形式でのパーミッションの表示
  • Example#2224 - 完全なパーミッションの表示
  • Example#2225 - filesize の例
  • Example#2226 - filetype の例
  • Example#2227 - flock の例
  • Example#2228 - flock で LOCK_NB オプションを使う例
  • Example#2229 - シェルのワイルドカードパターンによる色の名前のチェック
  • Example#2230 - fopen の例
  • Example#2231 - バイナリファイルに対する fpassthru の使用例
  • Example#2232 - fputcsv の例
  • Example#2233 - シンプルな fread の例
  • Example#2234 - バイナリの fread の例
  • Example#2235 - リモートファイルの fread の例
  • Example#2236 - fscanf の例
  • Example#2237 - users.txt の内容
  • Example#2238 - fseek の例
  • Example#2239 - fstat の例
  • Example#2240 - fsync の例
  • Example#2241 - ftell の例
  • Example#2242 - ファイルの丸めの例
  • Example#2243 - 簡単な fwrite の例
  • Example#2244 - glob が opendir と関連する関数群の代替策になるかを示す簡便な方法
  • Example#2245 - is_dir の例
  • Example#2246 - is_executable の例
  • Example#2247 - is_file の例
  • Example#2248 - シンボリックリンクの作成と、ファイルがシンボリックリンクかどうかの確認
  • Example#2249 - is_readable の例
  • Example#2250 - is_uploaded_file の例
  • Example#2251 - is_writable の例
  • Example#2252 - シンボリックリンクのグループの変更
  • Example#2253 - シンボリックリンクの所有者の変更
  • Example#2254 - シンプルなハードリンクの作成
  • Example#2255 - linkinfo の例
  • Example#2256 - stat と lstat の比較
  • Example#2257 - mkdir の例
  • Example#2258 - mkdir での recursive パラメータの使用例
  • Example#2259 - 複数のファイルのアップロード
  • Example#2260 - sample.ini の内容
  • Example#2261 - parse_ini_file の例
  • Example#2262 - parse_ini_file による php.ini ファイルのパース
  • Example#2263 - ini ファイルの値の補完
  • Example#2264 - 文字をエスケープする
  • Example#2265 - pathinfo の例
  • Example#2266 - pathinfo での、拡張子を空にしたときと拡張子がないときの違いの例
  • Example#2267 - pathinfo での、ドットファイルの例
  • Example#2268 - 配列の分解機能を、pathinfo と一緒に使う例
  • Example#2269 - pclose の例
  • Example#2270 - popen の例
  • Example#2271 - popen の例
  • Example#2272 - readfile によるダウンロードの強制
  • Example#2273 - readlink の例
  • Example#2274 - realpath の例
  • Example#2275 - Windows 上での realpath
  • Example#2276 - realpath_cache_get 例
  • Example#2277 - realpath_cache_size 例
  • Example#2278 - rename の例
  • Example#2279 - rewind での上書きの例
  • Example#2280 - rmdir の例
  • Example#2281 - stat の例
  • Example#2282 - stat の情報を touch と組み合わせる例
  • Example#2283 - シンボリックリンクの作成
  • Example#2284 - tempnam の例
  • Example#2285 - tmpfile の例
  • Example#2286 - touch の例
  • Example#2287 - touch で mtime パラメータを使用する例
  • Example#2288 - umask の例
  • Example#2289 - 基本的な unlink の使用法
  • Example#2290 - inotify の使用例
  • Example#2291 - システム管理者がファイルに署名をしているかどうかを調べる
  • Example#2292 - ファイルのすべての拡張属性の名前を表示する
  • Example#2293 - ファイルのすべての拡張属性を削除する
  • Example#2294 - .wav ファイルに拡張属性を設定する
  • Example#2295 - xattr_supported の例
  • Example#2296 - xdiff_file_bdiff の例
  • Example#2297 - xdiff_file_bdiff_size の例
  • Example#2298 - xdiff_file_bpatch の例
  • Example#2299 - xdiff_file_diff の例
  • Example#2300 - xdiff_file_diff_binary の例
  • Example#2301 - xdiff_file_merge3 の例
  • Example#2302 - xdiff_file_patch の例
  • Example#2303 - 逆パッチの例
  • Example#2304 - xdiff_file_patch_binary の例
  • Example#2305 - xdiff_file_rabdiff の例
  • Example#2306 - xdiff_string_bdiff_size の例
  • Example#2307 - xdiff_string_diff の例
  • Example#2308 - xdiff_string_patch の例
  • Example#2309 - Enchant の使用例
  • Example#2310 - 指定したブローカーが提供するバックエンドの一覧
  • Example#2311 - enchant_broker_dict_exists の例
  • Example#2312 - あるブローカーで使用可能なすべての辞書を表示する
  • Example#2313 - enchant_broker_request_dict の例
  • Example#2314 - 辞書リストに単語を追加する
  • Example#2315 - enchant_broker_dict_describe の例
  • Example#2316 - enchant_dict_quick_check の例
  • Example#2317 - enchant_dict_suggest の例
  • Example#2318 - 利用例
  • Example#2319 - Gender\Gender::country の使用例
  • Example#2320 - bindtextdomain の例
  • Example#2321 - gettext のチェック
  • Example#2322 - ngettext の例
  • Example#2323 - iconv の例
  • Example#2324 - iconv_get_encoding の例
  • Example#2325 - iconv_mime_decode の例
  • Example#2326 - iconv_mime_decode_headers の例
  • Example#2327 - iconv_mime_encode の例:
  • Example#2328 - iconv_set_encoding の例
  • Example#2329 - ob_iconv_handler の例
  • Example#2330 - 手続き型 API の使用例
  • Example#2331 - オブジェクト指向型 API の使用例
  • Example#2332 - FRENCH_COLLATION のルール
  • Example#2333 - ALTERNATE_HANDLING のルール
  • Example#2334 - CASE_FIRST のルール
  • Example#2335 - CASE_LEVEL のルール
  • Example#2336 - collator_asort の例
  • Example#2337 - collator_compare の例
  • Example#2338 - ダイアクリティカルマークや、大文字小文字の区別を無視して比較する
  • Example#2339 - Collator::__construct の例
  • Example#2340 - collator_create の例
  • Example#2341 - collator_get_attribute の例
  • Example#2342 - collator_get_error_code の例
  • Example#2343 - collator_get_error_message の例
  • Example#2344 - collator_get_locale の例
  • Example#2345 - collator_get_sort_key の例
  • Example#2346 - collator_get_strength の例
  • Example#2347 - collator_set_attribute の例
  • Example#2348 - collator_set_strength の例
  • Example#2349 - collator_sort の例
  • Example#2350 - collator_sort_with_sort_keys の例
  • Example#2351 - numfmt_create の例
  • Example#2352 - NumberFormatter::create の例
  • Example#2353 - numfmt_format の例
  • Example#2354 - オブジェクト指向の例
  • Example#2355 - numfmt_format_currency の例
  • Example#2356 - オブジェクト指向の例
  • Example#2357 - numfmt_get_attribute の例
  • Example#2358 - オブジェクト指向の例
  • Example#2359 - numfmt_get_error_code の例
  • Example#2360 - オブジェクト指向の例
  • Example#2361 - numfmt_get_error_message の例
  • Example#2362 - オブジェクト指向の例
  • Example#2363 - numfmt_get_locale の例
  • Example#2364 - numfmt_get_pattern の例
  • Example#2365 - オブジェクト指向の例
  • Example#2366 - numfmt_get_symbol の例
  • Example#2367 - オブジェクト指向の例
  • Example#2368 - numfmt_get_text_attribute の例
  • Example#2369 - オブジェクト指向の例
  • Example#2370 - numfmt_parse の例
  • Example#2371 - オブジェクト指向の例
  • Example#2372 - numfmt_parse_currency の例
  • Example#2373 - オブジェクト指向の例
  • Example#2374 - numfmt_set_attribute の例
  • Example#2375 - オブジェクト指向の例
  • Example#2376 - numfmt_set_pattern の例
  • Example#2377 - オブジェクト指向の例
  • Example#2378 - numfmt_set_symbol の例
  • Example#2379 - オブジェクト指向の例
  • Example#2380 - numfmt_set_text_attribute の例
  • Example#2381 - オブジェクト指向の例
  • Example#2382 - locale_accept_from_http の例
  • Example#2383 - オブジェクト指向の例
  • Example#2384 - locale_compose の例
  • Example#2385 - オブジェクト指向の例
  • Example#2386 - サブタグの制限
  • Example#2387 - locale_filter_matches の例
  • Example#2388 - オブジェクト指向の例
  • Example#2389 - locale_get_all_variants の例
  • Example#2390 - オブジェクト指向の例
  • Example#2391 - locale_get_default の例
  • Example#2392 - オブジェクト指向の例
  • Example#2393 - locale_get_display_language の例
  • Example#2394 - オブジェクト指向の例
  • Example#2395 - locale_get_display_name の例
  • Example#2396 - オブジェクト指向の例
  • Example#2397 - locale_get_display_region の例
  • Example#2398 - オブジェクト指向の例
  • Example#2399 - locale_get_display_script の例
  • Example#2400 - オブジェクト指向の例
  • Example#2401 - locale_get_display_variant の例
  • Example#2402 - オブジェクト指向の例
  • Example#2403 - locale_get_keywords の例
  • Example#2404 - オブジェクト指向の例
  • Example#2405 - locale_get_primary_language の例
  • Example#2406 - オブジェクト指向の例
  • Example#2407 - locale_get_region の例
  • Example#2408 - オブジェクト指向の例
  • Example#2409 - locale_get_script の例
  • Example#2410 - オブジェクト指向の例
  • Example#2411 - locale_lookup の例
  • Example#2412 - オブジェクト指向の例
  • Example#2413 - locale_parse の例
  • Example#2414 - オブジェクト指向の例
  • Example#2415 - locale_set_default の例
  • Example#2416 - オブジェクト指向の例
  • Example#2417 - Normalizer::getRawDecomposition の例
  • Example#2418 - normalizer_is_normalized の例
  • Example#2419 - オブジェクト指向の例
  • Example#2420 - normalizer_normalize の例
  • Example#2421 - オブジェクト指向の例
  • Example#2422 - msgfmt_create の例
  • Example#2423 - オブジェクト指向の例
  • Example#2424 - msgfmt_format の例
  • Example#2425 - オブジェクト指向の例
  • Example#2426 - msgfmt_format_message の例
  • Example#2427 - オブジェクト指向の例
  • Example#2428 - 通常の通貨記号と、短い形式の通貨記号を使ってフォーマットするよう、ICU に指示する
  • Example#2429 - msgfmt_get_error_message の例
  • Example#2430 - オブジェクト指向の例
  • Example#2431 - msgfmt_get_locale の例
  • Example#2432 - オブジェクト指向の例
  • Example#2433 - msgfmt_get_pattern の例
  • Example#2434 - オブジェクト指向の例
  • Example#2435 - msgfmt_parse の例
  • Example#2436 - オブジェクト指向の例
  • Example#2437 - msgfmt_parse_message の例
  • Example#2438 - オブジェクト指向の例
  • Example#2439 - msgfmt_set_pattern の例
  • Example#2440 - オブジェクト指向の例
  • Example#2441 - IntlCalendar::add
  • Example#2442 - IntlCalendar::after
  • Example#2443 - IntlCalendar::clear の例
  • Example#2444 - IntlCalendar::createInstance
  • Example#2445 - IntlCalendar::equals
  • Example#2446 - IntlCalendar::fieldDifference
  • Example#2447 - IntlCalendar::fromDateTime
  • Example#2448 - IntlCalendar::get
  • Example#2449 - IntlCalendar::getActualMaximum
  • Example#2450 - IntlCalendar::getAvailableLocales
  • Example#2451 - IntlCalendar::getDayOfWeekType
  • Example#2452 - IntlCalendar::getErrorCode と IntlCalendar::getErrorMessage の例
  • Example#2453 - IntlCalendar::getErrorMessage
  • Example#2454 - IntlCalendar::getFirstDayOfWeek
  • Example#2455 - IntlCalendar::getKeyworkValuesForLocale
  • Example#2456 - Maxima examples
  • Example#2457 - IntlCalendar::getLocale
  • Example#2458 - IntlCalendar::getMinimalDaysInFirstWeek
  • Example#2459 - IntlCalendar::getNow
  • Example#2460 - IntlCalendar::getRepeatedWallTimeOption
  • Example#2461 - IntlCalendar::getSkippedWallTimeOption
  • Example#2462 - IntlCalendar::getTime
  • Example#2463 - IntlCalendar::getTimeZone
  • Example#2464 - IntlCalendar::getType
  • Example#2465 - IntlCalendar::inDaylightTime
  • Example#2466 - IntlCalendar::isEquivalentTo
  • Example#2467 - IntlCalendar::isLenient
  • Example#2468 - IntlCalendar::isWeekend
  • Example#2469 - IntlCalendar::roll
  • Example#2470 - IntlCalendar::set
  • Example#2471 - IntlCalendar::setDate の例
  • Example#2472 - IntlCalendar::setDateTime の例
  • Example#2473 - IntlCalendar::setFirstDayOfWeek
  • Example#2474 - IntlCalendar::setTime
  • Example#2475 - IntlCalendar::setTimeZone
  • Example#2476 - IntlCalendar::toDateTime
  • Example#2477 - IntlGregorianCalendar::createFromDate の例
  • Example#2478 - IntlGregorianCalendar::createFromDateTime の例
  • Example#2479 - datefmt_create の例
  • Example#2480 - オブジェクト指向の例
  • Example#2481 - 無効なロケールを処理する例
  • Example#2482 - datefmt_format の例
  • Example#2483 - オブジェクト指向の例
  • Example#2484 - IntlCalendar オブジェクトを使う例
  • Example#2485 - IntlDateFormatter::formatObject の例
  • Example#2486 - datefmt_get_calendar の例
  • Example#2487 - オブジェクト指向の例
  • Example#2488 - 無効なロケールを処理する例
  • Example#2489 - datefmt_get_datetype の例
  • Example#2490 - オブジェクト指向の例
  • Example#2491 - datefmt_get_error_code の例
  • Example#2492 - オブジェクト指向の例
  • Example#2493 - datefmt_get_error_message の例
  • Example#2494 - オブジェクト指向の例
  • Example#2495 - datefmt_get_locale の例
  • Example#2496 - オブジェクト指向の例
  • Example#2497 - datefmt_get_pattern の例
  • Example#2498 - オブジェクト指向の例
  • Example#2499 - datefmt_get_timetype の例
  • Example#2500 - オブジェクト指向の例
  • Example#2501 - datefmt_get_timezone_id の例
  • Example#2502 - オブジェクト指向の例
  • Example#2503 - IntlDateFormatter::getCalendarObject の例
  • Example#2504 - IntlDateFormatter::getTimeZone の例
  • Example#2505 - datefmt_is_lenient の例
  • Example#2506 - オブジェクト指向の例
  • Example#2507 - datefmt_localtime の例
  • Example#2508 - オブジェクト指向の例
  • Example#2509 - オブジェクト指向の例
  • Example#2510 - datefmt_parse の例
  • Example#2511 - datefmt_set_calendar の例
  • Example#2512 - オブジェクト指向の例
  • Example#2513 - 引数に IntlCalendar を使う例
  • Example#2514 - datefmt_set_lenient の例
  • Example#2515 - オブジェクト指向の例
  • Example#2516 - datefmt_set_pattern の例
  • Example#2517 - オブジェクト指向の例
  • Example#2518 - IntlDateFormatter::setTimeZone の例
  • Example#2519 - resourcebundle_count の例
  • Example#2520 - オブジェクト指向の例
  • Example#2521 - resourcebundle_create の例
  • Example#2522 - ResourceBundle::create の例
  • Example#2523 - resourcebundle_get の例
  • Example#2524 - オブジェクト指向の例
  • Example#2525 - resourcebundle_get_error_code の例
  • Example#2526 - オブジェクト指向の例
  • Example#2527 - resourcebundle_get_error_message の例
  • Example#2528 - オブジェクト指向の例
  • Example#2529 - resourcebundle_locales の例
  • Example#2530 - オブジェクト指向の例
  • Example#2531 - Spoofchecker::areConfusable の例
  • Example#2532 - Spoofchecker::isSuspicious の例
  • Example#2533 - 登録済みの transliterator ID を取得する
  • Example#2534 - エスケープされた UTF-16 コード単位の変換
  • Example#2535 - IntlDatePatternGenerator::getBestPattern の例
  • Example#2536 - UTF-8 から UTF-16 に変換し、UTF-8 に戻す例
  • Example#2537 - 入力に不正な文字が含まれていた場合
  • Example#2538 - エンコードできない文字
  • Example#2539 - grapheme_extract の例
  • Example#2540 - grapheme_stripos の例
  • Example#2541 - grapheme_stristr の例
  • Example#2542 - grapheme_strlen の例
  • Example#2543 - grapheme_strpos example
  • Example#2544 - grapheme_strripos の例
  • Example#2545 - grapheme_strrpos example
  • Example#2546 - grapheme_strstr の例
  • Example#2547 - grapheme_substr の例
  • Example#2548 - idn_to_ascii の例
  • Example#2549 - idn_to_utf8 の例
  • Example#2550 - さまざまなコードポイントの例
  • Example#2551 - さまざまなコードポイントの例
  • Example#2552 - さまざまなコードポイントの例
  • Example#2553 - さまざまなコードポイントの例
  • Example#2554 - さまざまなコードポイントの例
  • Example#2555 - さまざまなコードポイントの例
  • Example#2556 - さまざまなコードポイントの例
  • Example#2557 - さまざまなコードポイントの例
  • Example#2558 - さまざまなコードポイントの例
  • Example#2559 - サンプルの範囲に入るコードポイントを走査する例
  • Example#2560 - サンプルのコードポイントの範囲を走査する
  • Example#2561 - さまざまなコードポイントの例
  • Example#2562 - さまざまなコードポイントの例
  • Example#2563 - さまざまなコードポイントの例
  • Example#2564 - さまざまなコードポイントの例
  • Example#2565 - さまざまなコードポイントの例
  • Example#2566 - さまざまなプロパティの例
  • Example#2567 - さまざまなプロパティの例
  • Example#2568 - さまざまなプロパティの例
  • Example#2569 - さまざまなコードポイントの例
  • Example#2570 - さまざまなプロパティの例
  • Example#2571 - さまざまなプロパティの例
  • Example#2572 - さまざまなプロパティの例
  • Example#2573 - さまざまなプロパティの例
  • Example#2574 - さまざまなプロパティの例
  • Example#2575 - さまざまなプロパティの例
  • Example#2576 - さまざまなコードポイントの例
  • Example#2577 - さまざまなコードポイントの例
  • Example#2578 - さまざまなコードポイントの例
  • Example#2579 - さまざまなコードポイントの例
  • Example#2580 - さまざまなコードポイントの例
  • Example#2581 - さまざまなコードポイントの例
  • Example#2582 - さまざまなコードポイントの例
  • Example#2583 - さまざまなコードポイントの例
  • Example#2584 - さまざまなコードポイントの例
  • Example#2585 - さまざまなコードポイントの例
  • Example#2586 - さまざまなコードポイントの例
  • Example#2587 - さまざまなコードポイントの例
  • Example#2588 - さまざまなコードポイントの例
  • Example#2589 - さまざまなコードポイントの例
  • Example#2590 - さまざまなコードポイントの例
  • Example#2591 - さまざまなコードポイントの例
  • Example#2592 - さまざまなコードポイントの例
  • Example#2593 - さまざまなコードポイントの例
  • Example#2594 - さまざまなコードポイントの例
  • Example#2595 - さまざまなコードポイントの例
  • Example#2596 - さまざまなコードポイントの例
  • Example#2597 - さまざまなコードポイントの例
  • Example#2598 - さまざまなコードポイントの例
  • Example#2599 - さまざまなコードポイントの例
  • Example#2600 - さまざまなコードポイントの例
  • Example#2601 - さまざまなコードポイントの例
  • Example#2602 - さまざまなコードポイントの例
  • Example#2603 - さまざまなコードポイントの例
  • Example#2604 - さまざまなコードポイントの例
  • Example#2605 - さまざまなコードポイントの例
  • Example#2606 - さまざまなコードポイントの例
  • Example#2607 - さまざまなコードポイントの例
  • Example#2608 - intl_error_name の例
  • Example#2609 - intl_get_error_code の例
  • Example#2610 - intl_get_error_message の例
  • Example#2611 - intl_is_failure example
  • Example#2612 - php.ini 設定の例
  • Example#2613 - EUC-JP ユーザー用の php.ini の設定
  • Example#2614 - SJIS ユーザー用の php.iniの 設定
  • Example#2615 - php.ini で HTTP 入力変換を無効にする
  • Example#2616 - php.ini の設定例
  • Example#2617 - スクリプトの例
  • Example#2618 - さまざまなコードポイントの例
  • Example#2619 - mb_convert_case の例
  • Example#2620 - 非ラテン UTF-8 テキストでの mb_convert_case の例
  • Example#2621 - mb_convert_encoding の例
  • Example#2622 - mb_convert_kana の例
  • Example#2623 - mb_convert_variables の例
  • Example#2624 - map の例
  • Example#2625 - map を使って JavaScript の文字列をエスケープする例
  • Example#2626 - mb_detect_encoding の例
  • Example#2627 - strict パラメーターの効果
  • Example#2628 - 複数のエンコーディングと一致した場合の効果
  • Example#2629 - mb_detect_order の例
  • Example#2630 - 無意味な順番の例
  • Example#2631 - mb_encode_mimeheader の例
  • Example#2632 - map の例
  • Example#2633 - mb_encode_numericentity の例
  • Example#2634 - mb_encoding_aliases 例
  • Example#2635 - mb_ereg_replace_callback の例
  • Example#2636 - 匿名関数を使用したmb_ereg_replace_callbackの例
  • Example#2637 - mb_internal_encoding の例
  • Example#2638 - mb_list_encodings の例
  • Example#2639 - A basic mb_ord example
  • Example#2640 - mb_output_handler の例
  • Example#2641 - mb_preferred_mime_name の例
  • Example#2642 - mb_str_pad の例
  • Example#2643 - mb_strimwidth の例
  • Example#2644 - mb_strtolower の例
  • Example#2645 - 非ラテン UTF-8 テキストでの mb_strtolower の例
  • Example#2646 - mb_strtoupper の例
  • Example#2647 - 非ラテン UTF-8 テキストでの mb_strtoupper の例
  • Example#2648 - mb_strwidth example
  • Example#2649 - mb_substitute_character の例
  • Example#2650 - mb_substr_count の例
  • Example#2651 - pspell_add_to_personal
  • Example#2652 - pspell_check の例
  • Example#2653 - pspell_add_to_personal の例
  • Example#2654 - pspell_config_create
  • Example#2655 - pspell_config_ignore
  • Example#2656 - pspell_config_mode の例
  • Example#2657 - pspell_config_personal
  • Example#2658 - pspell_config_repl
  • Example#2659 - pspell_config_runtogether
  • Example#2660 - pspell_new
  • Example#2661 - pspell_new_config
  • Example#2662 - pspell_new_personal
  • Example#2663 - pspell_add_to_personal
  • Example#2664 - pspell_store_replacement
  • Example#2665 - pspell_suggest の例
  • Example#2666 - 基本的な recode_file の例
  • Example#2667 - 基本的な recode_string の例
  • Example#2668 - exif_imagetype の例
  • Example#2669 - exif_read_data の例
  • Example#2670 - PHP 7.2.0 で利用できるストリームを exif_read_data で使う例
  • Example#2671 - exif_tagname の例
  • Example#2672 - exif_thumbnail の例
  • Example#2673 - PHP による PNG の生成
  • Example#2674 - アルファチャネルを使用した、画像へのすかしの追加
  • Example#2675 - imagecopymerge による半透明なすかしの作成
  • Example#2676 - gd_info の使用法
  • Example#2677 - getimagesize および MIME 型
  • Example#2678 - getimagesize の例
  • Example#2679 - getimagesize (URL)
  • Example#2680 - IPTC を返す getimagesize()
  • Example#2681 - getimagesizefromstring の例
  • Example#2682 - image_type_to_extension の例
  • Example#2683 - image_type_to_mime_type の例
  • Example#2684 - image2wbmp の例
  • Example#2685 - imageaffinematrixconcat の例
  • Example#2686 - imageaffinematrixget の例
  • Example#2687 - imagealphablending の使用例
  • Example#2688 - 2 本の直線のうち一方にアンチエイリアスを有効にする
  • Example#2689 - imagearc による円の描画
  • Example#2690 - ビットマップファイルを保存する
  • Example#2691 - imagechar の例
  • Example#2692 - imagecharup の例
  • Example#2693 - imagecolorallocate の例
  • Example#2694 - imagecolorallocatealpha の使用例
  • Example#2695 - imagecolorallocatealpha 関数を使い、典型的なアルファ値を変換する
  • Example#2696 - 個々の RGB 値へのアクセス
  • Example#2697 - imagecolorsforindex による可読形式の RGB 値
  • Example#2698 - 画像内での色セットの検索
  • Example#2699 - 画像内での色セットの検索
  • Example#2700 - imagecolorclosesthwb の使用例
  • Example#2701 - imagecolordeallocate の使用法
  • Example#2702 - GD ロゴからの色の取得
  • Example#2703 - GD ロゴからの色の取得
  • Example#2704 - imagecolormatch の例
  • Example#2705 - imagecoloresolve による画像からの色の取得
  • Example#2706 - imagecoloresolvealpha による画像からの色の取得
  • Example#2707 - imagecolorset の例
  • Example#2708 - imagecolorsforindex の例
  • Example#2709 - imagecolorstotal による画像の色の総数の取得
  • Example#2710 - imagecolortransparent の例
  • Example#2711 - PHP.net ロゴのエンボス加工
  • Example#2712 - ガウス分布のぼかし
  • Example#2713 - PHP.net のロゴの切り取り
  • Example#2714 - 2 つの PHP.net ロゴを 75% の透過度でマージ
  • Example#2715 - imagecopymergegray の使用法
  • Example#2716 - 単純な例
  • Example#2717 - イメージを均等に再サンプルする
  • Example#2718 - イメージをリサイズする
  • Example#2719 - 新しい GD 画像ストリームの作成および画像の出力
  • Example#2720 - imagecreatefrombmp を使用した BMP 画像から PNG 画像への変換
  • Example#2721 - imagecreatefromgd の例
  • Example#2722 - imagecreatefromgd2 の例
  • Example#2723 - imagecreatefromgd2part の例
  • Example#2724 - GIF の作成時のエラーを処理する例
  • Example#2725 - JPEG の作成時のエラーを処理する例
  • Example#2726 - PNG の作成時のエラーを処理する例
  • Example#2727 - imagecreatefromstring の例
  • Example#2728 - WBMP の作成時のエラーを処理する例
  • Example#2729 - imagecreatefromwebp を使った、WebP から jpeg への変換
  • Example#2730 - XBM 画像から png 画像への imagecreatefromxbm を用いた変換
  • Example#2731 - imagecreatefromxpm による画像インスタンスの作成
  • Example#2732 - 新規 GD イメージストリームの作成およびイメージの出力
  • Example#2733 - imagecrop の例
  • Example#2734 - 自動クロップの適切な処理
  • Example#2735 - imagedashedline の例
  • Example#2736 - imagedashedline のもうひとつの使用法
  • Example#2737 - PHP 8.0.0 より前のバージョンでの imagedestroy の使用例
  • Example#2738 - imageellipse の例
  • Example#2739 - imagefill の例
  • Example#2740 - 3D 風のパイを作成する
  • Example#2741 - imagefilledellipse の例
  • Example#2742 - imagefilledpolygon の例
  • Example#2743 - imagefilledrectangle の例
  • Example#2744 - 楕円の塗りつぶし
  • Example#2745 - imagefilter グレースケールの例
  • Example#2746 - imagefilter 輝度の例
  • Example#2747 - imagefilter 単色化の例
  • Example#2748 - imagefilter での打ち消しの例
  • Example#2749 - imagefilter でのモザイク処理の例
  • Example#2750 - imagefilter でのScatter効果の例
  • Example#2751 - 垂直方向の反転
  • Example#2752 - 水平方向の反転
  • Example#2753 - 組み込みフォントでの imagefontheight の使用法
  • Example#2754 - imagefontheight と imageloadfont を組み合わせた使用法
  • Example#2755 - 組み込みフォントでの imagefontwidth の使用法
  • Example#2756 - imagefontwidth と imageloadfont を組み合わせた使用法
  • Example#2757 - imageftbbox の例
  • Example#2758 - imagefttext の例
  • Example#2759 - imagegammacorrect の使用法
  • Example#2760 - GD 画像の出力
  • Example#2761 - GD 画像の保存
  • Example#2762 - GD2 画像の出力
  • Example#2763 - GD2 画像の保存
  • Example#2764 - imagegetclip の例
  • Example#2765 - imagegif による画像の出力
  • Example#2766 - imagegif による PNG 画像から GIF への変換
  • Example#2767 - imagegrabscreen の例
  • Example#2768 - imagegrabwindow の例
  • Example#2769 - imageinterlace によるインターレース処理の有効化
  • Example#2770 - imageistruecolor による、シンプルな true color 画像の検出
  • Example#2771 - JPEG 画像のブラウザへの出力
  • Example#2772 - JPEG 画像のファイルへの保存
  • Example#2773 - 75% 品質でのブラウザへの画像の出力
  • Example#2774 - imagelayereffect の例
  • Example#2775 - 太い線を描画する
  • Example#2776 - imageloadfont の使用例
  • Example#2777 - imageopenpolygon の例
  • Example#2778 - imagepalettecopy の例
  • Example#2779 - 画像オブジェクトの true color への変換
  • Example#2780 - imagepolygon の例
  • Example#2781 - シンプルな imagerectangle の例
  • Example#2782 - 画像の解像度を取得/設定する
  • Example#2783 - 画像を 180 度回転する
  • Example#2784 - 基本的な imagesavealpha の使用法
  • Example#2785 - imagesetbrush の例
  • Example#2786 - imagesetinterpolation の例
  • Example#2787 - imagesetpixel の例
  • Example#2788 - imagesetstyle の例
  • Example#2789 - imagesetthickness の例
  • Example#2790 - imagesettile の例
  • Example#2791 - imagestring の例
  • Example#2792 - imagestringup の例
  • Example#2793 - imagesx の使用法
  • Example#2794 - imagesy の使用法
  • Example#2795 - true color 画像からパレット画像への変換
  • Example#2796 - imagettfbbox の例
  • Example#2797 - imagettftext の例
  • Example#2798 - PNG をサポートしているかどうかの確認
  • Example#2799 - WBMP 画像の出力
  • Example#2800 - WBMP 画像の保存
  • Example#2801 - 別の前景での画像の出力
  • Example#2802 - WebP ファイルの保存
  • Example#2803 - XBM ファイルの保存
  • Example#2804 - 別の前景色による XBM ファイルの保存
  • Example#2805 - IPTC データの JPEG への埋め込み
  • Example#2806 - iptcparse() を getimagesize と組み合わせる使用法
  • Example#2807 - jpeg2wbmp の例
  • Example#2808 - png2wbmp の例
  • Example#2809 - Gmagick の例
  • Example#2810 - Gmagick::despeckleimage の例
  • Example#2811 - Gmagick::setCompressionQuality
  • Example#2812 - Imagick によるサムネイルの作成
  • Example#2813 - ディレクトリ内のすべての JPG ファイルのサムネイルの作成
  • Example#2814 - 画像の鏡像の作成
  • Example#2815 - グラデーションつきテキスト
  • Example#2816 - GIF 画像の読み込みと全フレームのサイズ変更
  • Example#2817 - PHP ロゴの作成
  • Example#2818 - Imagick::adaptiveBlurImage の使用法
  • Example#2819 - Imagick::adaptiveResizeImage の使用法
  • Example#2820 - Imagick::adaptiveSharpenImage の例
  • Example#2821 - Imagick::adaptiveThresholdImage
  • Example#2822 - Imagick::addNoiseImage
  • Example#2823 - Imagick::affineTransformImage
  • Example#2824 - Imagick::annotateImage の使用法
  • Example#2825 - Imagick::appendImages の例
  • Example#2826 - Imagick::autoLevelImage
  • Example#2827 - Imagick::blackThresholdImage
  • Example#2828 - Imagick::blueShiftImage
  • Example#2829 - Imagick::blurImage の使用法
  • Example#2830 - Imagick::borderImage
  • Example#2831 - Imagick::brightnessContrastImage
  • Example#2832 - Imagick::charcoalImage
  • Example#2833 - Imagick::chopImage の使用法
  • Example#2834 - Imagick オブジェクトのクローン
  • Example#2835 - Imagick::clutImage の使用法
  • Example#2836 - Imagick::colorizeImage
  • Example#2837 - Imagick::colorMatrixImage
  • Example#2838 - Imagick::commentImage の使用法
  • Example#2839 - Imagick::compareImageLayers の使用法
  • Example#2840 - Imagick::compareImages の使用法
  • Example#2841 - Imagick::compositeImage の利用例
  • Example#2842 - Imagick::contrastImage
  • Example#2843 - Imagick::convolveImage
  • Example#2844 - Imagick::cropImage
  • Example#2845 - Imagick::deskewImage
  • Example#2846 - Imagick::despeckleImage
  • Example#2847 - Imagick::distortImage の使用法
  • Example#2848 - Imagick::edgeImage
  • Example#2849 - Imagick::embossImage
  • Example#2850 - Imagick::enhanceImage
  • Example#2851 - Imagick::equalizeImage
  • Example#2852 - Imagick::evaluateImage の使用法
  • Example#2853 - Imagick::exportImagePixels の使用法
  • Example#2854 - Imagick::filter
  • Example#2855 - Imagick::flipImage
  • Example#2856 - Imagick::floodfillPaintImage の例
  • Example#2857 - Imagick::flopImage
  • Example#2858 - Imagick::forwardFourierTransformImage
  • Example#2859 - Imagick::frameImage
  • Example#2860 - シヌソイドの勾配の作成
  • Example#2861 - 多項式 (4x^2 - 4x + 1) からの勾配の作成
  • Example#2862 - 多項式 (4x^2 - 4x^2 + 1) をシヌソイドの勾配で変調した、複雑な勾配の作成
  • Example#2863 - Imagick::fxImage
  • Example#2864 - Imagick::gammaImage
  • Example#2865 - Imagick::gaussianBlurImage
  • Example#2866 - Imagick::getImageGeometry を使う
  • Example#2867 - Generates Imagick::getImageHistogram
  • Example#2868 - Imagick::getImageLength の使用法
  • Example#2869 - Imagick::getImageProperties の使用法
  • Example#2870 - Imagick::getImageProperty の使用法
  • Example#2871 - Imagick::getIteratorIndex の使用法
  • Example#2872 - Imagick::getPixelIterator
  • Example#2873 - Imagick::getPixelRegionIterator の例
  • Example#2874 - Getting the size of a raw RGB image set at 200x400, after scaling to 400x800 (compared to width / height)
  • Example#2875 - Imagick::haldClutImage
  • Example#2876 - Imagick::identifyFormat
  • Example#2877 - 結果の書式の例
  • Example#2878 - Imagick::implodeImage
  • Example#2879 - Imagick::importImagePixels の例
  • Example#2880 - Imagick::levelImage
  • Example#2881 - Imagick::linearStretchImage
  • Example#2882 - Imagick::magnifyImage
  • Example#2883 - Imagick::medianFilterImage
  • Example#2884 - Imagick::mergeImageLayers
  • Example#2885 - Imagick::modulateImage
  • Example#2886 - Convolve Imagick::morphology
  • Example#2887 - Correlate Imagick::morphology
  • Example#2888 - Erode Imagick::morphology
  • Example#2889 - Erode Intensity Imagick::morphology
  • Example#2890 - Dilate Imagick::morphology
  • Example#2891 - Dilate intensity Imagick::morphology
  • Example#2892 - Distance with Chebyshev kernel Imagick::morphology
  • Example#2893 - Distance with Manhattan kernel Imagick::morphology
  • Example#2894 - Distance with ocatagonal kernel Imagick::morphology
  • Example#2895 - Distance with Euclidean kernel Imagick::morphology
  • Example#2896 - Edge Imagick::morphology
  • Example#2897 - Open Imagick::morphology
  • Example#2898 - Open intensity Imagick::morphology
  • Example#2899 - Close Imagick::morphology
  • Example#2900 - Close Intensity Imagick::morphology
  • Example#2901 - Smooth Imagick::morphology
  • Example#2902 - Edge in Imagick::morphology
  • Example#2903 - Edge out Imagick::morphology
  • Example#2904 - The 'TopHat' method, or more specifically 'White Top Hat', returns the pixels that were removed by a Opening of the shape, that is the pixels that were removed to round off the points, and the connecting bridged between shapes. Imagick::morphology
  • Example#2905 - The 'BottomHat' method, also known as 'Black TopHat' is the pixels that a Closing of the shape adds to the image. That is the pixels that were used to fill in the 'holes', 'gaps', and 'bridges'. Imagick::morphology
  • Example#2906 - Hit and Miss Imagick::morphology
  • Example#2907 - Thinning Imagick::morphology
  • Example#2908 - Thicken Imagick::morphology
  • Example#2909 - Thick to generate a convex hull Imagick::morphology
  • Example#2910 - Iterative morphology Imagick::morphology
  • Example#2911 - Helper function to get an image silhouette Imagick::morphology
  • Example#2912 - Imagick::motionBlurImage
  • Example#2913 - Imagick::negateImage
  • Example#2914 - Imagick::newImage の使用法
  • Example#2915 - Imagick::newPseudoImage
  • Example#2916 - Imagick::normalizeImage
  • Example#2917 - Imagick::oilPaintImage
  • Example#2918 - Imagick::optimizeImageLayers の使用法
  • Example#2919 - Imagick::orderedPosterizeImage
  • Example#2920 - Imagick::pingImageBlob の使用法
  • Example#2921 - Imagick::pingImageFile の使用法
  • Example#2922 - Imagick::polaroidImage の例
  • Example#2923 - Imagick::posterizeImage
  • Example#2924 - Imagick::quantizeImage
  • Example#2925 - Imagick::queryFontMetrics の使用法
  • Example#2926 - Imagick::queryFonts
  • Example#2927 - Imagick::queryFormats
  • Example#2928 - Imagick::radialBlurImage
  • Example#2929 - Imagick::raiseImage
  • Example#2930 - Imagick::randomThresholdImage
  • Example#2931 - Imagick::readImageBlob
  • Example#2932 - Imagick::recolorImage
  • Example#2933 - Imagick::reduceNoiseImage
  • Example#2934 - Imagick::resampleImage
  • Example#2935 - Imagick::resizeImage
  • Example#2936 - Imagick::rollImage
  • Example#2937 - Imagick::rotateImage
  • Example#2938 - Imagick::rotationalBlurImage
  • Example#2939 - Imagick::roundCorners の使用法
  • Example#2940 - Imagick::scaleImage
  • Example#2941 - Imagick::segmentImage
  • Example#2942 - Imagick::selectiveBlurImage
  • Example#2943 - Imagick::separateImageChannel
  • Example#2944 - Imagick::sepiaToneImage
  • Example#2945 - Imagick::setCompressionQuality
  • Example#2946 - Imagick::setFont の例
  • Example#2947 - Imagick::setImage の例
  • Example#2948 - Imagick::setImageArtifact
  • Example#2949 - Imagick::setImageBias
  • Example#2950 - Imagick::setImageClipMask
  • Example#2951 - Imagick::setImageCompressionQuality
  • Example#2952 - Imagick::setImageDelay を使ったアニメーション GIF の変更
  • Example#2953 - 基本的な Imagick::setImageIterations の使用例
  • Example#2954 - Imagick::setImageOpacity の例
  • Example#2955 - Imagick::setImageOrientation
  • Example#2956 - Imagick::setImageProperty の使用法
  • Example#2957 - Imagick::setImageResolution
  • Example#2958 - Imagick::setImageTicksPerSecond によるアニメーション GIF の変更
  • Example#2959 - Imagick::setIteratorIndex の使用法
  • Example#2960 - Attempt to reach '$extent' sizeImagick::setOption
  • Example#2961 - Imagick::setOption
  • Example#2962 - Imagick::setOption
  • Example#2963 - Imagick::setPointSize の例
  • Example#2964 - Imagick::setProgressMonitor
  • Example#2965 - Imagick::setSamplingFactors
  • Example#2966 - Imagick::shadeImage
  • Example#2967 - Imagick::shadowImage
  • Example#2968 - Imagick::sharpenImage
  • Example#2969 - Imagick::shaveImage
  • Example#2970 - Imagick::shearImage
  • Example#2971 - Imagick::sigmoidalContrastImage によるグラデーションの作成 (ふたつの画像を、$contrast と $midpoint の定義でブレンドする)
  • Example#2972 - Imagick::sketchImage
  • Example#2973 - Imagick::smushImages
  • Example#2974 - Imagick::solarizeImage
  • Example#2975 - SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage
  • Example#2976 - SPARSECOLORMETHOD_BILINEAR Imagick::sparseColorImage
  • Example#2977 - SPARSECOLORMETHOD_SPEPARDS Imagick::sparseColorImage
  • Example#2978 - SPARSECOLORMETHOD_VORONOI Imagick::sparseColorImage
  • Example#2979 - SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage
  • Example#2980 - createGradientImage is used by other examples. Imagick::sparseColorImage
  • Example#2981 - Imagick::spliceImage
  • Example#2982 - Imagick::spreadImage
  • Example#2983 - Imagick::statisticImage
  • Example#2984 - Imagick::subImageMatch
  • Example#2985 - Imagick::swirlImage
  • Example#2986 - Imagick::textureImage
  • Example#2987 - Imagick::thresholdImage
  • Example#2988 - Imagick::thumbnailImage
  • Example#2989 - Imagick::tintImage
  • Example#2990 - Imagick::transformImage の使用
  • Example#2991 - Imagick::transformImageColorspace example
  • Example#2992 - Imagick::transparentPaintImage
  • Example#2993 - Imagick::transposeImage
  • Example#2994 - Imagick::transverseImage
  • Example#2995 - Imagick::trimImage の使用法
  • Example#2996 - Imagick::uniqueImageColors
  • Example#2997 - Imagick::unsharpMaskImage
  • Example#2998 - Imagick::vignetteImage
  • Example#2999 - WaveImage can be quite slow Imagick::waveImage
  • Example#3000 - Imagick::whiteThresholdImage
  • Example#3001 - ImagickDraw::affine の例
  • Example#3002 - ImagickDraw::arc の例
  • Example#3003 - ImagickDraw::bezier の例
  • Example#3004 - ImagickDraw::circle の例
  • Example#3005 - ImagickDraw::composite の例
  • Example#3006 - ImagickDraw::ellipse の例
  • Example#3007 - ImagickDraw::line の例
  • Example#3008 - ImagickDraw::matte の例
  • Example#3009 - ImagickDraw::pathCurveToQuadraticBezierAbsolute の例
  • Example#3010 - ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute の例
  • Example#3011 - ImagickDraw::pathCurveToQuadraticBezierSmoothRelative の例
  • Example#3012 - ImagickDraw::pathStart の例
  • Example#3013 - ImagickDraw::point の例
  • Example#3014 - ImagickDraw::polygon の例
  • Example#3015 - ImagickDraw::polyline の例
  • Example#3016 - ImagickDraw::popDefs の例
  • Example#3017 - ImagickDraw::push の例
  • Example#3018 - ImagickDraw::pushPattern の例
  • Example#3019 - ImagickDraw::rectangle の例
  • Example#3020 - ImagickDraw::rotate の例
  • Example#3021 - ImagickDraw::roundRectangle の例
  • Example#3022 - ImagickDraw::scale の例
  • Example#3023 - ImagickDraw::setClipPath の例
  • Example#3024 - ImagickDraw::setClipRule の例
  • Example#3025 - ImagickDraw::setClipUnits の例
  • Example#3026 - ImagickDraw::setFillAlpha の例
  • Example#3027 - ImagickDraw::setFillColor
  • Example#3028 - ImagickDraw::setFillOpacity
  • Example#3029 - ImagickDraw::setFillRule の例
  • Example#3030 - ImagickDraw::setFont の例
  • Example#3031 - ImagickDraw::setFontFamily の例
  • Example#3032 - ImagickDraw::setFontSize の例
  • Example#3033 - ImagickDraw::setFontStretch の例
  • Example#3034 - ImagickDraw::setFontStyle の例
  • Example#3035 - ImagickDraw::setFontWeight の例
  • Example#3036 - ImagickDraw::setGravity の例
  • Example#3037 - ImagickDraw::setStrokeAlpha の例
  • Example#3038 - ImagickDraw::setStrokeAntialias の例
  • Example#3039 - ImagickDraw::setStrokeColor の例
  • Example#3040 - ImagickDraw::setStrokeDashArray の例
  • Example#3041 - ImagickDraw::setStrokeDashOffset の例
  • Example#3042 - ImagickDraw::setStrokeLineCap の例
  • Example#3043 - ImagickDraw::setStrokeLineJoin の例
  • Example#3044 - ImagickDraw::setStrokeMiterLimit の例
  • Example#3045 - ImagickDraw::setStrokeOpacity の例
  • Example#3046 - ImagickDraw::setStrokeWidth の例
  • Example#3047 - ImagickDraw::setTextAlignment の例
  • Example#3048 - ImagickDraw::setTextAntialias の例
  • Example#3049 - ImagickDraw::setTextDecoration の例
  • Example#3050 - ImagickDraw::setTextUnderColor の例
  • Example#3051 - ImagickDraw::setVectorGraphics の例
  • Example#3052 - ImagickDraw::setViewBox の例
  • Example#3053 - ImagickDraw::skewX の例
  • Example#3054 - ImagickDraw::skewY の例
  • Example#3055 - ImagickDraw::translate の例
  • Example#3056 - ImagickPixel::construct
  • Example#3057 - 基本的な Imagick::getColor の使用例
  • Example#3058 - 基本的な Imagick::getColorAsString の使用例
  • Example#3059 - ImagickPixel getColorCount
  • Example#3060 - 基本的な Imagick::getColorValue の使用例
  • Example#3061 - ImagickPixel::getColorValueQuantum
  • Example#3062 - 基本的な Imagick::getHSL の使用例
  • Example#3063 - ImagickPixel::isSimilar
  • Example#3064 - ImagickPixel::setColor
  • Example#3065 - 基本的な Imagick::setColorValue の使用例
  • Example#3066 - ImagickPixel::setColorValueQuantum
  • Example#3067 - ImagickPixel::setHSL による色の変更
  • Example#3068 - ImagickPixelIterator::clear
  • Example#3069 - ImagickPixelIterator::construct
  • Example#3070 - ImagickPixelIterator::getNextIteratorRow
  • Example#3071 - ImagickPixelIterator::resetIterator
  • Example#3072 - ImagickPixelIterator::setIteratorRow
  • Example#3073 - ImagickKernel::addKernel
  • Example#3074 - ImagickKernel::addUnityKernel
  • Example#3075 - ImagickKernel::addUnityKernel
  • Example#3076 - ImagickKernel::fromBuiltin
  • Example#3077 - ImagickKernel::fromMatrix
  • Example#3078 - ImagickKernel::getMatrix
  • Example#3079 - ImagickKernel::scale
  • Example#3080 - ImagickKernel::separate
  • Example#3081 - imap_append の例
  • Example#3082 - imap_check の例
  • Example#3083 - imap_createmailbox example
  • Example#3084 - imap_delete の例
  • Example#3085 - imap_fetch_overview の例
  • Example#3086 - imap_gc の例
  • Example#3087 - imap_get_quota の例
  • Example#3088 - 4.3 以降のバージョンでの imap_get_quota の例
  • Example#3089 - imap_get_quotaroot の例
  • Example#3090 - imap_getacl の例
  • Example#3091 - imap_getmailboxes の例
  • Example#3092 - imap_is_open の例
  • Example#3093 - imap_list の例
  • Example#3094 - imap_mail_compose の例
  • Example#3095 - imap_mailboxmsginfo example
  • Example#3096 - imap_mime_header_decode の例
  • Example#3097 - imap_open のさまざまな使用例
  • Example#3098 - imap_open の例
  • Example#3099 - imap_ping の例
  • Example#3100 - imap_reopen の例
  • Example#3101 - imap_rfc822_parse_adrlist の例
  • Example#3102 - imap_rfc822_write_address の例
  • Example#3103 - imap_search の例
  • Example#3104 - imap_set_quota の例
  • Example#3105 - imap_setflag_full の例
  • Example#3106 - imap_status の例
  • Example#3107 - imap_thread の例
  • Example#3108 - imap_timeout の例
  • Example#3109 - Basic imap_utf8 の使い方
  • Example#3110 - ハッシュ値を計算し、ユーザーを登録する
  • Example#3111 - メールを送信する
  • Example#3112 - 追加ヘッダを付加してメールを送信する
  • Example#3113 - 追加のヘッダを array で指定してメールを送信する
  • Example#3114 - 追加のコマンドラインパラメータを指定してメールを送信する
  • Example#3115 - HTML メールを送信する
  • Example#3116 - mailparse_determine_best_xfer_encoding の例
  • Example#3117 - mailparse_rfc822_parse_addresses の例
  • Example#3118 - mailparse_stream_encode の例
  • Example#3119 - mailparse_uudecode_all の例
  • Example#3120 - bcadd の例
  • Example#3121 - bccomp の例
  • Example#3122 - bcdiv の例
  • Example#3123 - bcmod の例
  • Example#3124 - bcmod に小数の値を指定する
  • Example#3125 - bcmul の例
  • Example#3126 - bcmul で scale を指定する例
  • Example#3127 - bcpow の例
  • Example#3128 - bcpow で scale を指定する例
  • Example#3129 - bcscale の例
  • Example#3130 - bcsqrt の例
  • Example#3131 - bcsub の例
  • Example#3132 - GMP を使用した階乗関数
  • Example#3133 - gmp_abs の例
  • Example#3134 - gmp_add の例
  • Example#3135 - gmp_and の例
  • Example#3136 - gmp_clrbit の例
  • Example#3137 - gmp_cmp の例
  • Example#3138 - gmp_com の例
  • Example#3139 - gmp_div_q の例
  • Example#3140 - GMP 数の割算
  • Example#3141 - gmp_div_r の例
  • Example#3142 - gmp_divexact の例
  • Example#3143 - gmp_export の例
  • Example#3144 - gmp_fact の例
  • Example#3145 - gmp_gcd の例
  • Example#3146 - 線形不定方程式を解く
  • Example#3147 - gmp_hamdist の例
  • Example#3148 - gmp_import の例
  • Example#3149 - GMP 数の作成
  • Example#3150 - gmp_intval の例
  • Example#3151 - gmp_invert の例
  • Example#3152 - gmp_jacobi の例
  • Example#3153 - gmp_legendre の例
  • Example#3154 - gmp_mod の例
  • Example#3155 - gmp_mul の例
  • Example#3156 - gmp_neg の例
  • Example#3157 - gmp_nextprime の例
  • Example#3158 - gmp_or の例
  • Example#3159 - gmp_perfect_square の例
  • Example#3160 - gmp_popcount の例
  • Example#3161 - gmp_pow の例
  • Example#3162 - gmp_powm の例
  • Example#3163 - gmp_prob_prime の例
  • Example#3164 - gmp_random の例
  • Example#3165 - gmp_random_bits の例
  • Example#3166 - gmp_random_range の例
  • Example#3167 - gmp_random_seed の例
  • Example#3168 - gmp_scan0 の例
  • Example#3169 - gmp_scan1 の例
  • Example#3170 - gmp_setbit の例 - インデックス 0
  • Example#3171 - gmp_setbit の例 - インデックス 1
  • Example#3172 - gmp_setbit の例 - ビットのクリア
  • Example#3173 - gmp_sign の例
  • Example#3174 - gmp_sqrt の例
  • Example#3175 - gmp_sqrtrem の例
  • Example#3176 - GMP 数を文字列に変換する
  • Example#3177 - gmp_sub の例
  • Example#3178 - gmp_testbit の例
  • Example#3179 - gmp_xor の例
  • Example#3180 - abs の例
  • Example#3181 - base_convert の例
  • Example#3182 - bindec の例
  • Example#3183 - bindec が入力を符号なし整数として処理する例
  • Example#3184 - ceil の例
  • Example#3185 - cos の例
  • Example#3186 - decbin の例
  • Example#3187 - dechex の例
  • Example#3188 - dechex での大きな整数の例
  • Example#3189 - decoct の例
  • Example#3190 - deg2rad の例
  • Example#3191 - exp の例
  • Example#3192 - fdiv を使う
  • Example#3193 - floor の例
  • Example#3194 - fmod の使用法
  • Example#3195 - hexdec の例
  • Example#3196 - intdiv の例
  • Example#3197 - is_finite の例
  • Example#3198 - is_infinite の例
  • Example#3199 - is_nan の例
  • Example#3200 - max の使用例
  • Example#3201 - min の例
  • Example#3202 - octdec の例
  • Example#3203 - pi の例
  • Example#3204 - pow の例
  • Example#3205 - rad2deg の例
  • Example#3206 - round の例
  • Example#3207 - precision が、どうfloatの値に影響するか
  • Example#3208 - mode の例
  • Example#3209 - 桁数を指定した mode の例
  • Example#3210 - sin の例
  • Example#3211 - sqrt の例
  • Example#3212 - tan の例
  • Example#3213 - FDF ドキュメントの評価
  • Example#3214 - JavaScript コードを FDF に追加する
  • Example#3215 - PDF ドキュメントを公開する
  • Example#3216 - アップロードされたファイルを保存する
  • Example#3217 - FDF のすべてのフィールド名を検出する
  • Example#3218 - フォームデータへのアクセス
  • Example#3219 - フォームデータへのアクセス
  • Example#3220 - FDF の文字列での取得
  • Example#3221 - FDF データを 2 番目のフォームに渡す
  • Example#3222 - gnupg での署名の例 (手続き型)
  • Example#3223 - gnupg での署名の例 (オブジェクト指向)
  • Example#3224 - keylistiterator
  • Example#3225 - 手続き型の gnupg_adddecryptkey の例
  • Example#3226 - オブジェクト指向の gnupg_adddecryptkey の例
  • Example#3227 - 手続き型の gnupg_addencryptkey の例
  • Example#3228 - オブジェクト指向の gnupg_addencryptkey の例
  • Example#3229 - 手続き型の gnupg_addsignkey の例
  • Example#3230 - オブジェクト指向の gnupg_addsignkey の例
  • Example#3231 - 手続き型の gnupg_cleardecryptkeys の例
  • Example#3232 - オブジェクト指向の gnupg_cleardecryptkeys の例
  • Example#3233 - 手続き型の gnupg_clearencryptkeys の例
  • Example#3234 - オブジェクト指向の gnupg_clearencryptkeys の例
  • Example#3235 - 手続き型の gnupg_clearsignkeys の例
  • Example#3236 - オブジェクト指向の gnupg_clearsignkeys の例
  • Example#3237 - 手続き型の gnupg_decrypt の例
  • Example#3238 - オブジェクト指向の gnupg_decrypt の例
  • Example#3239 - 手続き型の gnupg_decryptverify の例
  • Example#3240 - オブジェクト指向の gnupg_decryptverify の例
  • Example#3241 - 手続き型の gnupg_deletekey の例
  • Example#3242 - オブジェクト指向の gnupg_deletekey の例
  • Example#3243 - 手続き型の gnupg_encrypt の例
  • Example#3244 - オブジェクト指向の gnupg_encrypt の例
  • Example#3245 - 手続き型の gnupg_encryptsign の例
  • Example#3246 - オブジェクト指向の gnupg_encryptsign の例
  • Example#3247 - Procedural gnupg_export example
  • Example#3248 - OO gnupg_export example
  • Example#3249 - 手続き型 gnupg_getengineinfo の例
  • Example#3250 - オブジェクト指向 gnupg_getengineinfo の例
  • Example#3251 - 手続き型の gnupg_geterror の例
  • Example#3252 - オブジェクト指向の gnupg_geterror の例
  • Example#3253 - 手続き型 gnupg_geterrorinfo の例
  • Example#3254 - オブジェクト指向型 gnupg_geterrorinfo の例
  • Example#3255 - 手続き型の gnupg_getprotocol の例
  • Example#3256 - オブジェクト指向の gnupg_getprotocol の例
  • Example#3257 - 手続き型の gnupg_gettrustlist の例
  • Example#3258 - オブジェクト指向の gnupg_gettrustlist の例
  • Example#3259 - 手続き型の gnupg_import の例
  • Example#3260 - オブジェクト指向の gnupg_import の例
  • Example#3261 - デフォルト値を使った、手続き型の gnupg_init の例
  • Example#3262 - ファイル名とホームディレクトリを上書きした、手続き型の gnupg_init の例
  • Example#3263 - デフォルト値を使い、オブジェクト指向型のインターフェイスで gnupg を初期化する例
  • Example#3264 - ファイル名とホームディレクトリを上書きし、オブジェクト指向型のインターフェイスで gnupg を初期化する例
  • Example#3265 - 手続き型の gnupg_keyinfo の例
  • Example#3266 - オブジェクト指向の gnupg_keyinfo の例
  • Example#3267 - 手続き型の gnupg_listsignatures の例
  • Example#3268 - オブジェクト指向の gnupg_listsignatures の例
  • Example#3269 - 手続き型の gnupg_setarmor の例
  • Example#3270 - オブジェクト指向の gnupg_setarmor の例
  • Example#3271 - 手続き型の gnupg_seterrormode の例
  • Example#3272 - オブジェクト指向の gnupg_seterrormode の例
  • Example#3273 - 手続き型の gnupg_setsignmode の例
  • Example#3274 - オブジェクト指向の gnupg_setsignmode の例
  • Example#3275 - 手続き型の gnupg_sign の例
  • Example#3276 - オブジェクト指向の gnupg_sign の例
  • Example#3277 - 手続き型の gnupg_verify の例
  • Example#3278 - オブジェクト指向の gnupg_verify の例
  • Example#3279 - パターンの作成および使用
  • Example#3280 - テンプレートの作成および使用
  • Example#3281 - テキストのハイフネーション
  • Example#3282 - 矩形を描画する
  • Example#3283 - スポット色の作成と使用
  • Example#3284 - 座標系の回転
  • Example#3285 - 指定した位置にテキストを配置する
  • Example#3286 - 破線を描画する
  • Example#3287 - 座標系の変換
  • Example#3288 - A rpmdbinfo example
  • Example#3289 - Searching for the package owning a file
  • Example#3290 - A rpminfo example
  • Example#3291 - example
  • Example#3292 - example
  • Example#3293 - example
  • Example#3294 - example
  • Example#3295 - example
  • Example#3296 - example
  • Example#3297 - example
  • Example#3298 - example
  • Example#3299 - example
  • Example#3300 - example
  • Example#3301 - example
  • Example#3302 - example
  • Example#3303 - example
  • Example#3304 - setColumn example
  • Example#3305 - setRow example
  • Example#3306 - Align style example
  • Example#3307 - Bold style example
  • Example#3308 - Italic style example
  • Example#3309 - Underline style example
  • Example#3310 - 間違ったリクエスト
  • Example#3311 - リクエストコールバックからのリクエストの呼び出し
  • Example#3312 - リクエストコールバックからのリクエストの呼び出し
  • Example#3313 - eio と libevent を組み合わせる例
  • Example#3314 - リクエストの取り消し
  • Example#3315 - eio_chmod の呼び出し
  • Example#3316 - カスタムリクエストの作成
  • Example#3317 - リクエストのグループ化
  • Example#3318 - eio と libevent 拡張モジュールを組み合わせる
  • Example#3319 - eio と event 拡張モジュールを組み合わせる
  • Example#3320 - eio_cancel の例
  • Example#3321 - eio_custom の例
  • Example#3322 - eio_event_loop の例
  • Example#3323 - eio_lstat の例
  • Example#3324 - eio を libevent とともに使う
  • Example#3325 - eio_grp の例
  • Example#3326 - リクエストのグループ化
  • Example#3327 - eio_link の例
  • Example#3328 - eio_lstat の例
  • Example#3329 - eio_mkdir の例
  • Example#3330 - eio_mknod の例
  • Example#3331 - eio_nreqs の例
  • Example#3332 - eio_open の例
  • Example#3333 - eio_poll の例
  • Example#3334 - eio_read の例
  • Example#3335 - eio_readdir の例
  • Example#3336 - eio_readlink の例
  • Example#3337 - eio_realpath の例
  • Example#3338 - eio_rename の例
  • Example#3339 - eio_rmdir の例
  • Example#3340 - eio_stat の例
  • Example#3341 - eio_statvfs の例
  • Example#3342 - eio_symlink の例
  • Example#3343 - タイマーのサンプル
  • Example#3344 - 10.5 秒おきに繰り返すタイマー
  • Example#3345 - 再スケジュールコールバックを使う定期タイマー
  • Example#3346 - すぐに開始し、10.5 秒おきに繰り返すタイマー
  • Example#3347 - STDIN が読み込み可能になるまで待つ例
  • Example#3348 - 非同期 I/O を使ったソケットへのアクセス
  • Example#3349 - ループの中に別のループを埋め込む例
  • Example#3350 - kqueue バックエンドで作ったループをデフォルトのループに埋め込む例
  • Example#3351 - SIGTERM の処理
  • Example#3352 - /var/log/messages の変更の監視
  • Example#3353 - /var/log/messages の変更の監視 (1 秒の遅延を使って、更新を見落とさないようにする)
  • Example#3354 - ステータスの変更の処理
  • Example#3355 - 再スケジュールコールバックの利用
  • Example#3356 - kqueue バックエンドで作ったループをデフォルトのループに埋め込む例
  • Example#3357 - ループの中に別のループを埋め込む例
  • Example#3358 - kqueue バックエンドで作ったループをデフォルトのループに埋め込む例
  • Example#3359 - kqueue バックエンドで作ったループをデフォルトのループに埋め込む例
  • Example#3360 - Periodic timer. Use reschedule callback
  • Example#3361 - Periodic timer. Tick every 10.5 seconds starting at now
  • Example#3362 - Hourly watcher
  • Example#3363 - Handle SIGTERM signal
  • Example#3364 - Monitor changes of /var/log/messages
  • Example#3365 - Monitor changes of /var/log/messages
  • Example#3366 - Simple timers
  • Example#3367 - Monotor changes of /var/log/messages. Avoid missing updates by means of one second delay
  • Example#3368 - Register an I/O watcher for some UDP socket but do not keep the event loop from running just because of that watcher.
  • Example#3369 - Expect の使用例
  • Example#3370 - もうひとつの Expect の使用例
  • Example#3371 - expect_expectl の例
  • Example#3372 - expect_popen の例
  • Example#3373 - プロセス制御の例
  • Example#3374 - pcntl_fork の例
  • Example#3375 - pcntl_rfork の例
  • Example#3376 - pcntl_signal の例
  • Example#3377 - pcntl_signal_dispatch の例
  • Example#3378 - pcntl_signal_get_handler の例
  • Example#3379 - pcntl_sigprocmask の例
  • Example#3380 - pcntl_sigwaitinfo の例
  • Example#3381 - posix_access の例
  • Example#3382 - posix_ctermid の例
  • Example#3383 - posix_eaccess の例
  • Example#3384 - posix_fpathconf の例
  • Example#3385 - posix_get_last_error の例
  • Example#3386 - posix_getcwd の例
  • Example#3387 - posix_getegid example
  • Example#3388 - posix_geteuid の例
  • Example#3389 - posix_getgid の例
  • Example#3390 - posix_getgrgid の使用例
  • Example#3391 - posix_getgrnam の使用例
  • Example#3392 - posix_getgroups の使用例
  • Example#3393 - posix_getlogin の使用例
  • Example#3394 - posix_getpgid の使用例
  • Example#3395 - posix_getpid の使用例
  • Example#3396 - posix_getppid の使用例
  • Example#3397 - posix_getpwnam の使用例
  • Example#3398 - posix_getpwuid の使用例
  • Example#3399 - posix_getrlimit の使用例
  • Example#3400 - posix_getsid の使用例
  • Example#3401 - posix_getuid の使用例
  • Example#3402 - posix_mknod の例
  • Example#3403 - posix_pathconf の例
  • Example#3404 - posix_setegid の例
  • Example#3405 - posix_setgid の例
  • Example#3406 - posix_setuid の例
  • Example#3407 - posix_strerror の例
  • Example#3408 - posix_sysconf の例
  • Example#3409 - posix_times の使用例
  • Example#3410 - posix_uname の使用例
  • Example#3411 - escapeshellarg の例
  • Example#3412 - escapeshellcmd の例
  • Example#3413 - exec の例
  • Example#3414 - proc_nice 関数を使い、プロセスの優先度を高に設定する
  • Example#3415 - A proc_open の例
  • Example#3416 - proc_open 関数の癖(Windows限定)
  • Example#3417 - shell_exec の例
  • Example#3418 - system の例
  • Example#3419 - Example showing Future as return value
  • Example#3420 - Example showing Future as synchronization point
  • Example#3421 - Fetch a chunk of the property table
  • Example#3422 - Counting the properties of an object
  • Example#3423 - Runtime inheritance
  • Example#3424 - Detect the state of the referenced object
  • Example#3425 - Detect the state of the referenced object
  • Example#3426 - Merging into the property table of a threaded object
  • Example#3427 - Notifications and Waiting
  • Example#3428 - Notifications and Waiting
  • Example#3429 - Popping the last item from the property table of a threaded object
  • Example#3430 - Shifting the first item from the property table of a threaded object
  • Example#3431 - Synchronizing
  • Example#3432 - Notifications and Waiting
  • Example#3433 - このスレッドを作ったスレッドあるいはプロセスの ID を返す
  • Example#3434 - Return the currently executing Thread
  • Example#3435 - Return the identity of the currently executing Thread
  • Example#3436 - このスレッドの ID を返す
  • Example#3437 - スレッドの状態を検出する
  • Example#3438 - スレッドが開始したかどうかを検出する
  • Example#3439 - スレッドとのジョイン
  • Example#3440 - スレッドの開始
  • Example#3441 - A basic example of Worker::collect
  • Example#3442 - A basic example of Worker::getStacked
  • Example#3443 - Detect the state of a worker
  • Example#3444 - Shutdown the referenced worker
  • Example#3445 - Stacking a task for execution onto a worker
  • Example#3446 - Removing objects from the stack of Workers
  • Example#3447 - A basic example of Pool::collect
  • Example#3448 - Creating Pools
  • Example#3449 - Shutting down a pool
  • Example#3450 - Submitting Tasks
  • Example#3451 - Submitting tasks to a specific worker
  • Example#3452 - New immutability semantics of Threaded
  • Example#3453 - Volatile use-case
  • Example#3454 - 共有メモリ操作の概要
  • Example#3455 - 共有メモリブロックを閉じる
  • Example#3456 - 共有メモリブロックを削除する
  • Example#3457 - 共有メモリブロックを新規に作成する
  • Example#3458 - 共有メモリブロックを読み取る
  • Example#3459 - 共有メモリブロックのサイズを取得する
  • Example#3460 - 共有メモリブロックに書き込む
  • Example#3461 - SyncMutex::__construct named mutex with lock timeout example
  • Example#3462 - SyncMutex::__construct unnamed mutex example
  • Example#3463 - SyncMutex::lock example
  • Example#3464 - SyncMutex::unlock example
  • Example#3465 - SyncSemaphore::__construct example
  • Example#3466 - SyncSemaphore::lock example
  • Example#3467 - SyncSemaphore::unlock example
  • Example#3468 - SyncEvent::__construct example
  • Example#3469 - SyncEvent::fire example
  • Example#3470 - SyncEvent::reset example
  • Example#3471 - SyncEvent::wait example
  • Example#3472 - SyncReaderWriter::__construct example
  • Example#3473 - SyncReaderWriter::readlock example
  • Example#3474 - SyncReaderWriter::readunlock example
  • Example#3475 - SyncReaderWriter::writelock example
  • Example#3476 - SyncReaderWriter::writeunlock example
  • Example#3477 - SyncSharedMemory::__construct example
  • Example#3478 - SyncSharedMemory::first example
  • Example#3479 - SyncSharedMemory::__construct example
  • Example#3480 - SyncSharedMemory::size example
  • Example#3481 - SyncSharedMemory::write example
  • Example#3482 - geoip_asnum_by_name の例
  • Example#3483 - geoip_continent_code_by_name の例
  • Example#3484 - geoip_country_code_by_name の例
  • Example#3485 - geoip_country_code3_by_name の例
  • Example#3486 - geoip_country_name_by_name の例
  • Example#3487 - geoip_database_info の例
  • Example#3488 - geoip_db_avail の例
  • Example#3489 - geoip_db_filename の例
  • Example#3490 - geoip_db_get_all_info の例
  • Example#3491 - geoip_db_get_all_info の例
  • Example#3492 - geoip_domain_by_name の例
  • Example#3493 - geoip_id_by_name の例
  • Example#3494 - geoip_isp_by_name の例
  • Example#3495 - geoip_netspeedcell_by_name の例
  • Example#3496 - geoip_org_by_name の例
  • Example#3497 - geoip_record_by_name の例
  • Example#3498 - geoip_region_by_name の例
  • Example#3499 - US/Canada の地域コードを使用した geoip_region_name_by_code の例
  • Example#3500 - FIPS コードを使用した geoip_region_name_by_code の例
  • Example#3501 - geoip_setup_custom_directory の例
  • Example#3502 - US/Canada の地域コードを使用した geoip_time_zone_by_country_and_region の例
  • Example#3503 - FIPS コードを使用した geoip_time_zone_by_country_and_region の例
  • Example#3504 - xor.data file
  • Example#3505 - Simple train
  • Example#3506 - Simple test
  • Example#3507 - fann_create_train_from_callback example
  • Example#3508 - fann_read_train_from_file example
  • Example#3509 - igbinary_serialize の例
  • Example#3510 - JsonSerializable::jsonSerialize で配列を返す例
  • Example#3511 - JsonSerializable::jsonSerialize で連想配列を返す例
  • Example#3512 - JsonSerializable::jsonSerialize で整数値を返す例
  • Example#3513 - JsonSerializable::jsonSerialize で文字列を返す例
  • Example#3514 - json_decode の例
  • Example#3515 - 無効なオブジェクトプロパティへのアクセス
  • Example#3516 - json_decode でのありがちな間違い
  • Example#3517 - depth エラー
  • Example#3518 - json_decode で大きな整数値を扱う例
  • Example#3519 - json_encode の例
  • Example#3520 - json_encode で、利用中のいくつかのフラグを表示する例
  • Example#3521 - JSON_NUMERIC_CHECK の例
  • Example#3522 - シーケンシャルな配列とそうでない配列の例
  • Example#3523 - JSON_PRESERVE_ZERO_FRACTION の例
  • Example#3524 - json_last_error の例
  • Example#3525 - json_last_error と json_encode の組み合わせ
  • Example#3526 - json_last_error と JSON_THROW_ON_ERROR の組み合わせ
  • Example#3527 - json_validate の例
  • Example#3528 - simdjson_decode examples
  • Example#3529 - Accessing invalid object properties
  • Example#3530 - common mistakes using simdjson_decode
  • Example#3531 - depth errors
  • Example#3532 - simdjson_decode of large integers
  • Example#3533 - simdjson_decode examples
  • Example#3534 - depth errors
  • Example#3535 - Lua::assignの例
  • Example#3536 - Lua::callの例
  • Example#3537 - Lua::evalの例
  • Example#3538 - Lua::registerCallbackの例
  • Example#3539 - LuaClosure::__invokeの例
  • Example#3540 - Execute some Lua code
  • Example#3541 - Calling a Lua function
  • Example#3542 - Profiling Lua code
  • Example#3543 - Loading code into Lua
  • Example#3544 - Manipulating the usage timer
  • Example#3545 - Registering PHP functions to call from Lua
  • Example#3546 - Calling a Lua function
  • Example#3547 - Calling a Lua function
  • Example#3548 - 定数に対して constant を使う例
  • Example#3549 - 列挙型の case に constant を使う例(PHP 8.1.0 以降)
  • Example#3550 - 定数の定義
  • Example#3551 - 予約された名前を定数にする
  • Example#3552 - 定数のチェック
  • Example#3553 - 列挙型のcase をチェックする(PHP 8.1.0 以降)
  • Example#3554 - eval の例 - 簡単なテキストのマージ
  • Example#3555 - exit の例
  • Example#3556 - exit でステータスを指定する例
  • Example#3557 - シャットダウン関数やデストラクタが実行される例
  • Example#3558 - ユーザーのブラウザについての全情報の一覧
  • Example#3559 - __halt_compiler の例
  • Example#3560 - highlight_string の例
  • Example#3561 - hrtime の使い方
  • Example#3562 - ignore_user_abort の例
  • Example#3563 - pack の例
  • Example#3564 - php_strip_whitespace の例
  • Example#3565 - sapi_windows_generate_ctrl_event 関数の基本的な使い方
  • Example#3566 - 基本的な sapi_windows_set_ctrl_handler 関数の使い方
  • Example#3567 - sapi_windows_vt100_support でデフォルトの状態を出力する
  • Example#3568 - sapi_windows_vt100_support で状態を変更する
  • Example#3569 - VT100 のサポートを有効にする例
  • Example#3570 - sleep の例
  • Example#3571 - sys_getloadavg の例
  • Example#3572 - time_nanosleep の例
  • Example#3573 - time_sleep_until の例
  • Example#3574 - uniqid の例
  • Example#3575 - unpack の例
  • Example#3576 - unpack でのリピータの例
  • Example#3577 - unpack で名前のないキーを扱う例
  • Example#3578 - usleep の例
  • Example#3579 - Random Example
  • Example#3580 - mt_rand の例
  • Example#3581 - rand の例
  • Example#3582 - random_bytes の例
  • Example#3583 - random_int の例
  • Example#3584 - Random\Randomizer::__construct example
  • Example#3585 - Random\Randomizer::getBytes の例
  • Example#3586 - Random\Randomizer::getBytesFromString の例
  • Example#3587 - 2要素認証向けにランダムなコードを生成する
  • Example#3588 - 一様分布していない文字列から選択する
  • Example#3589 - Random\Randomizer::getFloat の例
  • Example#3590 - Random\Randomizer::getInt の例
  • Example#3591 - Random\Randomizer::nextFloat の例
  • Example#3592 - アフィン変換を使った間違った拡大演算
  • Example#3593 - Random\Randomizer::nextInt の例
  • Example#3594 - Random\Randomizer::pickArrayKeys の例
  • Example#3595 - ランダムに値を取り出す
  • Example#3596 - Random\Randomizer::__serialize の例
  • Example#3597 - Random\Randomizer::shuffleArray の例
  • Example#3598 - Random\Randomizer::shuffleBytes の例
  • Example#3599 - バイト単位でシャッフルするとUnicode文字は壊れる
  • Example#3600 - Random\Randomizer::__unserialize の例
  • Example#3601 - Random\Engine::generate の例
  • Example#3602 - Random\Engine\Mt19937::__construct の例
  • Example#3603 - Random\Engine\Mt19937::__debugInfo の例
  • Example#3604 - Random\Engine\Mt19937::__serialize の例
  • Example#3605 - Random\Engine\Mt19937::__unserialize の例
  • Example#3606 - Random\Engine\PcgOneseq128XslRr64::__construct の例
  • Example#3607 - 文字列からシードを作る
  • Example#3608 - Random\Engine\PcgOneseq128XslRr64::__debugInfo の例
  • Example#3609 - Random\Engine\PcgOneseq128XslRr64::jump の例
  • Example#3610 - Randomizer のメソッドは、複数回エンジンをコールしても構わない
  • Example#3611 - Random\Engine\PcgOneseq128XslRr64::__serialize の例
  • Example#3612 - Random\Engine\PcgOneseq128XslRr64::__unserialize の例
  • Example#3613 - Random\Engine\Xoshiro256StarStar::__construct の例
  • Example#3614 - 文字列からシードを作る
  • Example#3615 - Random\Engine\Xoshiro256StarStar::__debugInfo の例
  • Example#3616 - Random\Engine\Xoshiro256StarStar::jump の例
  • Example#3617 - Random\Engine\Xoshiro256StarStar::jumpLong の例
  • Example#3618 - Random\Engine\Xoshiro256StarStar::__serialize の例
  • Example#3619 - Random\Engine\Xoshiro256StarStar::__unserialize の例
  • Example#3620 - Get and set base path
  • Example#3621 - Get and set logger
  • Example#3622 - Fast write log
  • Example#3623 - Fast count some type of log count value
  • Example#3624 - Acquisit some type of log list
  • Example#3625 - seaslog_get_author example
  • Example#3626 - seaslog_get_version example
  • Example#3627 - SeasLog::alert example
  • Example#3628 - SeasLog::analyzerCount example
  • Example#3629 - SeasLog::analyzerDetail example
  • Example#3630 - SeasLog::closeLoggerStream example
  • Example#3631 - SeasLog::__construct example
  • Example#3632 - SeasLog::critical example
  • Example#3633 - SeasLog::debug example
  • Example#3634 - SeasLog::__destruct example
  • Example#3635 - SeasLog::emergency example
  • Example#3636 - SeasLog::error example
  • Example#3637 - SeasLog::flushBuffer example
  • Example#3638 - SeasLog::getBasePath example
  • Example#3639 - SeasLog::getBuffer example
  • Example#3640 - SeasLog::getBufferEnabled example
  • Example#3641 - SeasLog::getDatetimeFormat example
  • Example#3642 - SeasLog::getLastLogger example
  • Example#3643 - SeasLog::getRequestID example
  • Example#3644 - SeasLog::getRequestVariable example
  • Example#3645 - SeasLog::info example
  • Example#3646 - SeasLog::log example
  • Example#3647 - SeasLog::notice example
  • Example#3648 - SeasLog::setBasePath example
  • Example#3649 - SeasLog::setDatetimeFormat example
  • Example#3650 - SeasLog::setLogger example
  • Example#3651 - SeasLog::setRequestID example
  • Example#3652 - SeasLog::setRequestVariable example
  • Example#3653 - SeasLog::warning example
  • Example#3654 - SplStack の例
  • Example#3655 - SplQueue の例
  • Example#3656 - SplQueue を使ってタスクを効率的に処理する
  • Example#3657 - SplFixedArray の使用例
  • Example#3658 - SplFixedArray::__construct の例
  • Example#3659 - SplFixedArray::count の例
  • Example#3660 - SplFixedArray::fromArray の例
  • Example#3661 - SplFixedArray::getSize の例
  • Example#3662 - SplFixedArray::setSize の例
  • Example#3663 - SplFixedArray::toArray の例
  • Example#3664 - SplObjectStorage をセットとして使用
  • Example#3665 - SplObjectStorage をマップとして使用
  • Example#3666 - SplObjectStorage::addAll の例
  • Example#3667 - SplObjectStorage::attach の例
  • Example#3668 - SplObjectStorage::contains の例
  • Example#3669 - SplObjectStorage::count の例
  • Example#3670 - SplObjectStorage::current の例
  • Example#3671 - SplObjectStorage::detach の例
  • Example#3672 - SplObjectStorage::getHash の例
  • Example#3673 - SplObjectStorage::getInfo の例
  • Example#3674 - SplObjectStorage::key の例
  • Example#3675 - SplObjectStorage::next の例
  • Example#3676 - SplObjectStorage::offsetExists の例
  • Example#3677 - SplObjectStorage::offsetGet の例
  • Example#3678 - SplObjectStorage::offsetSet の例
  • Example#3679 - SplObjectStorage::offsetUnset の例
  • Example#3680 - SplObjectStorage::removeAll の例
  • Example#3681 - SplObjectStorage::removeAllExcept の例
  • Example#3682 - SplObjectStorage::rewind の例
  • Example#3683 - SplObjectStorage::serialize の例
  • Example#3684 - SplObjectStorage::setInfo の例
  • Example#3685 - SplObjectStorage::unserialize の例
  • Example#3686 - SplObjectStorage::valid の例
  • Example#3687 - AppendIterator::append の例
  • Example#3688 - AppendIterator の foreach での使用例
  • Example#3689 - AppendIterator API による AppendIterator の処理
  • Example#3690 - AppendIterator.getIteratorIndex の基本的な例
  • Example#3691 - AppendIterator::key の基本的な例
  • Example#3692 - ArrayIterator::current の例
  • Example#3693 - ArrayIterator::key の例
  • Example#3694 - ArrayIterator::next の例
  • Example#3695 - ArrayIterator::rewind の例
  • Example#3696 - ArrayIterator::valid の例
  • Example#3697 - CachingIterator::getCache の例
  • Example#3698 - 利用可能なコールバック引数
  • Example#3699 - コールバックの基本例
  • Example#3700 - DirectoryIterator::__construct の例
  • Example#3701 - DirectoryIterator::current の例
  • Example#3702 - DirectoryIterator::getBasename の例
  • Example#3703 - DirectoryIterator::getExtension の例
  • Example#3704 - DirectoryIterator::getFilename の例
  • Example#3705 - DirectoryIterator::isDot の例
  • Example#3706 - DirectoryIterator::key の例
  • Example#3707 - DirectoryIterator::next の例
  • Example#3708 - DirectoryIterator::rewind の例
  • Example#3709 - DirectoryIterator::seek の例
  • Example#3710 - DirectoryIterator::__toString の例
  • Example#3711 - DirectoryIterator::valid の例
  • Example#3712 - FilesystemIterator::__construct の例
  • Example#3713 - FilesystemIterator::current の例
  • Example#3714 - FilesystemIterator::key の例
  • Example#3715 - FilesystemIterator::next の例
  • Example#3716 - FilesystemIterator::rewind の例
  • Example#3717 - FilesystemIterator::key の例
  • Example#3718 - FilterIterator::accept の例
  • Example#3719 - GlobIterator の例
  • Example#3720 - GlobIterator::count の例
  • Example#3721 - InfiniteIterator::__construct の例
  • Example#3722 - LimitIterator の使用例
  • Example#3723 - LimitIterator::__construct の例
  • Example#3724 - LimitIterator::getPosition の例
  • Example#3725 - MultipleIterator の反復処理
  • Example#3726 - NoRewindIterator::__construct の例
  • Example#3727 - NoRewindIterator::rewind の例
  • Example#3728 - RecursiveArrayIterator::getChildren の例
  • Example#3729 - RecursiveArrayIterator::hasChildren の例
  • Example#3730 - 利用可能なコールバック引数
  • Example#3731 - 再帰コールバックの基本例
  • Example#3732 - RecursiveCallbackFilterIterator::hasChildren の基本的な使用例
  • Example#3733 - RecursiveDirectoryIterator の例
  • Example#3734 - getSubPath の例
  • Example#3735 - getSubPathname の例
  • Example#3736 - RecursiveFilterIterator の基本例
  • Example#3737 - RecursiveFilterIterator の例
  • Example#3738 - RecursiveIteratorIterator の反復処理
  • Example#3739 - RecursiveRegexIterator::__construct の例
  • Example#3740 - RecursiveRegexIterator::getChildren の例
  • Example#3741 - RecursiveRegexIterator::hasChildren の例
  • Example#3742 - RegexIterator::accept の例
  • Example#3743 - RegexIterator::__construct の例
  • Example#3744 - RegexIterator::getFlags の例
  • Example#3745 - RegexIterator::getMode の例
  • Example#3746 - RegexIterator::getPregFlags の例
  • Example#3747 - RegexIterator::setFlags の例
  • Example#3748 - RegexIterator::setMode の例
  • Example#3749 - RegexIterator::setPregFlags の例
  • Example#3750 - Countable::count の例
  • Example#3751 - 基本的な使用法
  • Example#3752 - SeekableIterator::seek の例
  • Example#3753 - class_implements の例
  • Example#3754 - class_parents の例
  • Example#3755 - class_uses の例
  • Example#3756 - iterator_apply の例
  • Example#3757 - iterator_count の例
  • Example#3758 - iterator_count で位置を変更する例
  • Example#3759 - foreach ループ内での iterator_count
  • Example#3760 - iterator_to_array の例
  • Example#3761 - spl_autoload_extensions の例
  • Example#3762 - spl_autoload_register を __autoload 関数の代わりに使う例
  • Example#3763 - spl_autoload_register でクラスをロードしない例
  • Example#3764 - 識別子には先頭のバックスラッシュが付かない
  • Example#3765 - spl_classes の例
  • Example#3766 - spl_object_hash の例
  • Example#3767 - spl_object_id の例
  • Example#3768 - SplFileInfo::__construct の例
  • Example#3769 - SplFileInfo::getATime の例
  • Example#3770 - SplFileInfo::getBasename の例
  • Example#3771 - SplFileInfo::getCTime の例
  • Example#3772 - SplFileInfo::getExtension の例
  • Example#3773 - SplFileInfo::getFilename の例
  • Example#3774 - SplFileInfo::getGroup の例
  • Example#3775 - SplFileInfo::getLinkTarget の例
  • Example#3776 - SplFileInfo::getMTime の例
  • Example#3777 - SplFileInfo::getOwner の例
  • Example#3778 - SplFileInfo::getPath の例
  • Example#3779 - SplFileInfo::getPathInfo の例
  • Example#3780 - SplFileInfo::getPathname の例
  • Example#3781 - SplFileInfo::getPerms の例
  • Example#3782 - SplFileInfo::getRealPath の例
  • Example#3783 - SplFileInfo::getSize の例
  • Example#3784 - SplFileInfo::getType の例
  • Example#3785 - SplFileInfo::isDir の例
  • Example#3786 - SplFileInfo::isExecutable の例
  • Example#3787 - SplFileInfo::isFile の例
  • Example#3788 - SplFileInfo::isLink の例
  • Example#3789 - SplFileInfo::isReadable の例
  • Example#3790 - SplFileInfo::isWriteable の例
  • Example#3791 - SplFileInfo::openFile の例
  • Example#3792 - SplFileInfo::setFileClass の例
  • Example#3793 - SplFileInfo::setFileClass の例
  • Example#3794 - SplFileInfo::__toString の例
  • Example#3795 - SplFileObject::__construct の例
  • Example#3796 - SplFileObject::current の例
  • Example#3797 - SplFileObject::eof の例
  • Example#3798 - SplFileObject::fflush の例
  • Example#3799 - SplFileObject::fgetc の例
  • Example#3800 - SplFileObject::fgetcsv の例
  • Example#3801 - SplFileObject::READ_CSV の例
  • Example#3802 - SplFileObject::fgets の例
  • Example#3803 - SplFileObject::fgetss の例
  • Example#3804 - SplFileObject::flock の例
  • Example#3805 - SplFileObject::fpassthru の例
  • Example#3806 - SplFileObject::fputcsv の例
  • Example#3807 - SplFileObject::fread の例
  • Example#3808 - SplFileObject::fscanf の例
  • Example#3809 - SplFileObject::fseek の例
  • Example#3810 - SplFileObject::fstat の例
  • Example#3811 - SplFileObject::ftell の例
  • Example#3812 - SplFileObject::ftruncate の例
  • Example#3813 - SplFileObject::fwrite の例
  • Example#3814 - SplFileObject::getCsvControl の例
  • Example#3815 - SplFileObject::getFlags の例
  • Example#3816 - SplFileObject::getMaxLineLen の例
  • Example#3817 - SplFileObject::key の例
  • Example#3818 - SplFileObject::setMaxLineLen による SplFileObject::key の例
  • Example#3819 - SplFileObject::next の例
  • Example#3820 - SplFileObject::rewind の例
  • Example#3821 - SplFileObject::seek の例
  • Example#3822 - SplFileObject::setCsvControl の例
  • Example#3823 - SplFileObject::setFlags の例
  • Example#3824 - SplFileObject::setMaxLineLen の例
  • Example#3825 - SplFileObject::valid の例
  • Example#3826 - SplTempFileObject の例
  • Example#3827 - ArrayObject::append の例
  • Example#3828 - ArrayObject::asort の例
  • Example#3829 - ArrayObject::__construct の例
  • Example#3830 - ArrayObject::count の例
  • Example#3831 - ArrayObject::exchangeArray の例
  • Example#3832 - ArrayObject::getArrayCopy の例
  • Example#3833 - ArrayObject::getFlags の例
  • Example#3834 - ArrayObject::getIterator の例
  • Example#3835 - ArrayObject::getIteratorClass の例
  • Example#3836 - ArrayObject::ksort の例
  • Example#3837 - ArrayObject::natcasesort の例
  • Example#3838 - ArrayObject::natsort の例
  • Example#3839 - ArrayObject::offsetExists の例
  • Example#3840 - ArrayObject::offsetGet の例
  • Example#3841 - ArrayObject::offsetSet の例
  • Example#3842 - ArrayObject::offsetUnset の例
  • Example#3843 - ArrayObject::serialize の例
  • Example#3844 - ArrayObject::setFlags の例
  • Example#3845 - ArrayObject::setIteratorClass の例
  • Example#3846 - ArrayObject::uasort の例
  • Example#3847 - ArrayObject::uksort の例
  • Example#3848 - file_get_contents を使って さまざまな場所からデータを取得する
  • Example#3849 - https のサーバーに対して POST リクエストを行う
  • Example#3850 - データを圧縮ファイルに書き込む
  • Example#3851 - グローバル変数の読み書き用のストリーム
  • Example#3852 - tar アーカイブのファイル一覧
  • Example#3853 - stream_bucket_prepend の例
  • Example#3854 - stream_context_create の使用
  • Example#3855 - stream_context_get_default の使用
  • Example#3856 - stream_context_get_options の例
  • Example#3857 - stream_context_get_params の例
  • Example#3858 - stream_context_set_default の例
  • Example#3859 - stream_context_set_options の例
  • Example#3860 - stream_copy_to_stream の例
  • Example#3861 - フィルタの適用される場所を制御する
  • Example#3862 - foo-bar.txt ストリームの文字を大文字化するフィルタ
  • Example#3863 - 複数のフィルタ名に対応する一般的なフィルタクラスを登録する
  • Example#3864 - ストリームの再フィルタリングを動的に行う
  • Example#3865 - stream_get_contents の例
  • Example#3866 - stream_get_filters を使用する
  • Example#3867 - fopen を使い、http 経由で stream_get_meta_data を使う例
  • Example#3868 - stream_socket_client を使い、https 経由で stream_get_meta_data を使う例
  • Example#3869 - stream_get_transports を使った例
  • Example#3870 - stream_get_wrappers の例
  • Example#3871 - ストリームラッパーのが存在するかどうかを調べる
  • Example#3872 - stream_is_local の例
  • Example#3873 - stream_isatty の例
  • Example#3874 - stream_notification_callback の例
  • Example#3875 - コマンドラインのダウンロードツール用のシンプルなプログレスバー
  • Example#3876 - stream_resolve_include_path の例
  • Example#3877 - stream_select の例
  • Example#3878 - stream_set_timeout の例
  • Example#3879 - stream_set_write_buffer の例
  • Example#3880 - stream_socket_client の例
  • Example#3881 - UDP 接続の使用
  • Example#3882 - stream_socket_enable_crypto の例
  • Example#3883 - stream_socket_pair の例
  • Example#3884 - stream_socket_recvfrom の例
  • Example#3885 - stream_socket_sendto の例
  • Example#3886 - TCP サーバーソケットの使用
  • Example#3887 - UDP サーバーソケットを利用する
  • Example#3888 - stream_socket_shutdown の例
  • Example#3889 - ストリームラッパーの登録方法
  • Example#3890 - Tidy の基本的な使用法
  • Example#3891 - tidy::getBody の例
  • Example#3892 - tidy::cleanrepair の例
  • Example#3893 - tidy::__construct の例
  • Example#3894 - tidy::diagnose の例
  • Example#3895 - tidy_get_error_buffer の例
  • Example#3896 - tidy::getConfig の例
  • Example#3897 - tidy_getopt の例
  • Example#3898 - すべてのオプションについてのドキュメントとデフォルト値をプリントする
  • Example#3899 - tidy::getStatus の例
  • Example#3900 - tidy::head の例
  • Example#3901 - tidy::html の例
  • Example#3902 - tidy::parseFile の例
  • Example#3903 - tidy::parseString の例
  • Example#3904 - tidy::repairFile の例
  • Example#3905 - tidy::repairString の例
  • Example#3906 - tidy::root の例
  • Example#3907 - tidyNode::getParent の例
  • Example#3908 - tidyNode::hasChildren の例
  • Example#3909 - tidyNode::hasSiblings の例
  • Example#3910 - HTML ドキュメントからの ASP コードの抽出
  • Example#3911 - HTML ドキュメントからのコメントの抽出
  • Example#3912 - HTML ドキュメントからの HTML コードの抽出
  • Example#3913 - HTML ドキュメントからの JSTE コードの抽出
  • Example#3914 - HTML ドキュメントからの PHP コードの抽出
  • Example#3915 - HTML ドキュメントからのテキストの抽出
  • Example#3916 - ob_tidyhandler の例
  • Example#3917 - tidy_access_count の例
  • Example#3918 - tidy_config_count の例
  • Example#3919 - tidy_error_count の例
  • Example#3920 - tidy_get_output の例
  • Example#3921 - tidy_warning_count の例
  • Example#3922 - tokenizer によるコメントの削除
  • Example#3923 - PhpToken::getTokenName の例
  • Example#3924 - PhpToken::is の例
  • Example#3925 - この関数に配列を渡す例
  • Example#3926 - PhpToken::isIgnorable example
  • Example#3927 - PhpToken::__toString の例
  • Example#3928 - PhpToken::tokenize の例
  • Example#3929 - Extending PhpToken
  • Example#3930 - token_get_all の例
  • Example#3931 - token_get_all の間違った使いかた
  • Example#3932 - 予約語を使ったクラスでの token_get_all の例
  • Example#3933 - token_name の例
  • Example#3934 - base64_decode の例
  • Example#3935 - base64_encode の例
  • Example#3936 - get_headers の例
  • Example#3937 - get_headers で HEAD を使う例
  • Example#3938 - get_meta_tags が何をパースするのか
  • Example#3939 - get_meta_tags が何を返すのか
  • Example#3940 - http_build_query の簡単な使用法
  • Example#3941 - 数値インデックス要素の場合での http_build_query
  • Example#3942 - 複雑な配列の場合での http_build_query
  • Example#3943 - オブジェクトの場合の http_build_query の使用
  • Example#3944 - parse_url の例
  • Example#3945 - parse_url でスキームを省略した例
  • Example#3946 - rawurldecode の例
  • Example#3947 - FTP URL へのパスワードの埋め込み
  • Example#3948 - rawurlencode の例 2
  • Example#3949 - urldecode の例
  • Example#3950 - urlencode の例
  • Example#3951 - urlencode および htmlentities の例
  • Example#3952 - 基本的な JavaScript の実行
  • Example#3953 - Yaml の例
  • Example#3954 - パースコールバックの例
  • Example#3955 - Emit callback example
  • Example#3956 - yaml_emit の例
  • Example#3957 - yaml_parse の例
  • Example#3958 - 標準的なアプリケーションのディレクトリ構造
  • Example#3959 - エントリ
  • Example#3960 - リライトルール
  • Example#3961 - アプリケーションの設定
  • Example#3962 - デフォルトのコントローラ
  • Example#3963 - デフォルトのビューテンプレート
  • Example#3964 - アプリケーションの実行
  • Example#3965 - PHP の配列の例
  • Example#3966 - ini ファイルの例
  • Example#3967 - Bootstrap の例
  • Example#3968 - Yaf_Application::bootstrap の例
  • Example#3969 - Yaf_Application::clearLastError の例
  • Example#3970 - ini ファイルの例
  • Example#3971 - Yaf_Application::__construct の例
  • Example#3972 - Yaf_Application::__construct の例
  • Example#3973 - Yaf_Application::environ の例
  • Example#3974 - Yaf_Application::execute の例
  • Example#3975 - Yaf_Application::getConfig の例
  • Example#3976 - Yaf_Application::getDispatcher の例
  • Example#3977 - Yaf_Application::getLastErrorMsg の例
  • Example#3978 - Yaf_Application::getLastErrorNo の例
  • Example#3979 - Yaf_Application::getModules の例
  • Example#3980 - ブートストラップの例
  • Example#3981 - Yaf_Dispatcher::autoRender の例
  • Example#3982 - Yaf_Dispatcher::catchException の例
  • Example#3983 - Yaf_Dispatcher::registerPlugin の例
  • Example#3984 - カスタムビューエンジンの例
  • Example#3985 - Yaf_Dispatcher::setView の例
  • Example#3986 - Yaf_Dispatcher::throwexception の例
  • Example#3987 - Yaf_Dispatcher::throwexception の例
  • Example#3988 - Yaf_Config_Ini の例
  • Example#3989 - 別ファイルでのアクションの定義
  • Example#3990 - Dummy_action.php
  • Example#3991 - Yaf_Controller_Abstract::forward の例
  • Example#3992 - Yaf_Action_Abstract::execute の例
  • Example#3993 - Yaf_Action_Abstract::execute の例
  • Example#3994 - Yaf_View_Simple::assign の例
  • Example#3995 - テンプレートの例
  • Example#3996 - Yaf_View_Simple::assignRef の例
  • Example#3997 - テンプレートの例
  • Example#3998 - Yaf_View_Simple::clear の例
  • Example#3999 - Yaf_View_Simple::__constructor の例
  • Example#4000 - Yaf_View_Simple::__set の例
  • Example#4001 - 設定の例
  • Example#4002 - localnamespace の登録
  • Example#4003 - クラスのロード
  • Example#4004 - 名前空間つきのクラスのロード
  • Example#4005 - MVC クラスのロード
  • Example#4006 - MVC クラスかどうかの区別
  • Example#4007 - MVC のロード
  • Example#4008 - Yaf_Loader::registerNamespaceexample
  • Example#4009 - Yaf_Loader::registerLocalNamespace の例
  • Example#4010 - Yaf_Loader::registerNamespaceexample
  • Example#4011 - プラグインの例
  • Example#4012 - Yaf_Plugin_Abstract::routerShutdown の例
  • Example#4013 - Yaf_Response_Abstract::appendBody の例
  • Example#4014 - Yaf_Response_Abstract::getBody の例
  • Example#4015 - Yaf_Response_Abstract::prependBody の例
  • Example#4016 - Yaf_Response_Abstract::response の例
  • Example#4017 - Yaf_Response_Abstract::setBody の例
  • Example#4018 - Yaf_Route_Map::assemble の例
  • Example#4019 - Yaf_Route_Map の例
  • Example#4020 - Yaf_Route_Map の例
  • Example#4021 - Yaf_Route_Map の例
  • Example#4022 - Yaf_Route_Regex::assemble の例
  • Example#4023 - Yaf_Route_Regex の例
  • Example#4024 - Yaf_Route_Regex (2.3.0 以降) の例
  • Example#4025 - Yaf_Route_Regex と名前付きキャプチャグループ (2.3.0 以降) の例example
  • Example#4026 - Yaf_Route_Regex の例
  • Example#4027 - Yaf_Route_Rewrite::assemble の例
  • Example#4028 - Yaf_Route_Rewrite の例
  • Example#4029 - Yaf_Route_Rewrite の例
  • Example#4030 - Yaf_Route_Rewrite (2.3.0 以降) の例
  • Example#4031 - Apache 用のリライトルール
  • Example#4032 - Apache 用のリライトルール
  • Example#4033 - Lighttpd 用のリライトルール
  • Example#4034 - Nginx 用のリライトルール
  • Example#4035 - Yaf_Route_Static のデフォルトルート
  • Example#4036 - application.ini の例
  • Example#4037 - Yaf_Dispatcher::autoConfig の例
  • Example#4038 - Yaf_Dispatcher::autoRender の例
  • Example#4039 - ブートストラップでのルートの登録
  • Example#4040 - プラグイン Dummy.php (application.directory/plugins 配下)
  • Example#4041 - Yaf_Route_Simple::assemble の例
  • Example#4042 - Yaf_Route_Simple::route の例
  • Example#4043 - Yaf_Route_Simple::routeexample
  • Example#4044 - Yaf_Route_Static::assemble の例
  • Example#4045 - Yaf_Route_Static::route の例
  • Example#4046 - Yaf_Route_Supervar::assemble の例
  • Example#4047 - Yaf_Route_Supervar の例
  • Example#4048 - INI ファイルの例
  • Example#4049 - INI セクションの例
  • Example#4050 - INIexample
  • Example#4051 - taint の例
  • Example#4052 - Vector
  • Example#4053 - Map
  • Example#4054 - Ds\Collection::clear example
  • Example#4055 - Ds\Collection::copy example
  • Example#4056 - Ds\Collection::isEmpty example
  • Example#4057 - Ds\Collection::toArray example
  • Example#4058 - Ds\Hashable::hash example
  • Example#4059 - Ds\Sequence::allocate example
  • Example#4060 - Ds\Sequence::apply example
  • Example#4061 - Ds\Sequence::capacity example
  • Example#4062 - Ds\Sequence::contains example
  • Example#4063 - Ds\Sequence::filter example using callback function
  • Example#4064 - Ds\Sequence::filter example without a callback function
  • Example#4065 - Ds\Sequence::find example
  • Example#4066 - Ds\Sequence::first example
  • Example#4067 - Ds\Sequence::get example
  • Example#4068 - Ds\Sequence::get example using array syntax
  • Example#4069 - Ds\Sequence::insert example
  • Example#4070 - Ds\Sequence::join example using a separator string
  • Example#4071 - Ds\Sequence::join example without a separator string
  • Example#4072 - Ds\Sequence::last example
  • Example#4073 - Ds\Sequence::map example
  • Example#4074 - Ds\Sequence::merge example
  • Example#4075 - Ds\Sequence::pop example
  • Example#4076 - Ds\Sequence::push example
  • Example#4077 - Ds\Sequence::reduce with initial value example
  • Example#4078 - Ds\Sequence::reduce without an initial value example
  • Example#4079 - Ds\Sequence::remove example
  • Example#4080 - Ds\Sequence::reverse example
  • Example#4081 - Ds\Sequence::reversed example
  • Example#4082 - Ds\Sequence::rotate example
  • Example#4083 - Ds\Sequence::set example
  • Example#4084 - Ds\Sequence::set example using array syntax
  • Example#4085 - Ds\Sequence::shift example
  • Example#4086 - Ds\Sequence::slice example
  • Example#4087 - Ds\Sequence::sort example
  • Example#4088 - Ds\Sequence::sort example using a comparator
  • Example#4089 - Ds\Sequence::sorted example
  • Example#4090 - Ds\Sequence::sorted example using a comparator
  • Example#4091 - Ds\Sequence::sum integer example
  • Example#4092 - Ds\Sequence::sum float example
  • Example#4093 - Ds\Sequence::unshift example
  • Example#4094 - Ds\Vector::allocate example
  • Example#4095 - Ds\Vector::apply example
  • Example#4096 - Ds\Vector::capacity example
  • Example#4097 - Ds\Vector::clear example
  • Example#4098 - Ds\Vector::__construct example
  • Example#4099 - Ds\Vector::contains example
  • Example#4100 - Ds\Vector::copy example
  • Example#4101 - Ds\Vector::filter example using callback function
  • Example#4102 - Ds\Vector::filter example without a callback function
  • Example#4103 - Ds\Vector::find example
  • Example#4104 - Ds\Vector::first example
  • Example#4105 - Ds\Vector::get example
  • Example#4106 - Ds\Vector::get example using array syntax
  • Example#4107 - Ds\Vector::insert example
  • Example#4108 - Ds\Vector::isEmpty example
  • Example#4109 - Ds\Vector::join example using a separator string
  • Example#4110 - Ds\Vector::join example without a separator string
  • Example#4111 - Ds\Vector::last example
  • Example#4112 - Ds\Vector::map example
  • Example#4113 - Ds\Vector::merge example
  • Example#4114 - Ds\Vector::pop example
  • Example#4115 - Ds\Vector::push example
  • Example#4116 - Ds\Vector::reduce with initial value example
  • Example#4117 - Ds\Vector::reduce without an initial value example
  • Example#4118 - Ds\Vector::remove example
  • Example#4119 - Ds\Vector::reverse example
  • Example#4120 - Ds\Vector::reversed example
  • Example#4121 - Ds\Vector::rotate example
  • Example#4122 - Ds\Vector::set example
  • Example#4123 - Ds\Vector::set example using array syntax
  • Example#4124 - Ds\Vector::shift example
  • Example#4125 - Ds\Vector::slice example
  • Example#4126 - Ds\Vector::sort example
  • Example#4127 - Ds\Vector::sort example using a comparator
  • Example#4128 - Ds\Vector::sorted example
  • Example#4129 - Ds\Vector::sorted example using a comparator
  • Example#4130 - Ds\Vector::sum integer example
  • Example#4131 - Ds\Vector::sum float example
  • Example#4132 - Ds\Vector::toArray example
  • Example#4133 - Ds\Vector::unshift example
  • Example#4134 - Ds\Deque::allocate example
  • Example#4135 - Ds\Deque::apply example
  • Example#4136 - Ds\Deque::capacity example
  • Example#4137 - Ds\Deque::clear example
  • Example#4138 - Ds\Deque::__construct example
  • Example#4139 - Ds\Deque::contains example
  • Example#4140 - Ds\Deque::copy example
  • Example#4141 - Ds\Deque::filter example using callback function
  • Example#4142 - Ds\Deque::filter example without a callback function
  • Example#4143 - Ds\Deque::find example
  • Example#4144 - Ds\Deque::first example
  • Example#4145 - Ds\Deque::get example
  • Example#4146 - Ds\Deque::get example using array syntax
  • Example#4147 - Ds\Deque::insert example
  • Example#4148 - Ds\Deque::isEmpty example
  • Example#4149 - Ds\Deque::join example using a separator string
  • Example#4150 - Ds\Deque::join example without a separator string
  • Example#4151 - Ds\Deque::last example
  • Example#4152 - Ds\Deque::map example
  • Example#4153 - Ds\Deque::merge example
  • Example#4154 - Ds\Deque::pop example
  • Example#4155 - Ds\Deque::push example
  • Example#4156 - Ds\Deque::reduce with initial value example
  • Example#4157 - Ds\Deque::reduce without an initial value example
  • Example#4158 - Ds\Deque::remove example
  • Example#4159 - Ds\Deque::reverse example
  • Example#4160 - Ds\Deque::reversed example
  • Example#4161 - Ds\Deque::rotate example
  • Example#4162 - Ds\Deque::set example
  • Example#4163 - Ds\Deque::set example using array syntax
  • Example#4164 - Ds\Deque::shift example
  • Example#4165 - Ds\Deque::slice example
  • Example#4166 - Ds\Deque::sort example
  • Example#4167 - Ds\Deque::sort example using a comparator
  • Example#4168 - Ds\Deque::sorted example
  • Example#4169 - Ds\Deque::sorted example using a comparator
  • Example#4170 - Ds\Deque::sum integer example
  • Example#4171 - Ds\Deque::sum float example
  • Example#4172 - Ds\Deque::toArray example
  • Example#4173 - Ds\Deque::unshift example
  • Example#4174 - Ds\Map::allocate example
  • Example#4175 - Ds\Map::apply example
  • Example#4176 - Ds\Map::capacity example
  • Example#4177 - Ds\Map::clear example
  • Example#4178 - Ds\Map::__construct example
  • Example#4179 - Ds\Map::copy example
  • Example#4180 - Ds\Map::diff example
  • Example#4181 - Ds\Map::filter example using callback function
  • Example#4182 - Ds\Map::filter example without a callback function
  • Example#4183 - Ds\Map::first example
  • Example#4184 - Ds\Map::get example
  • Example#4185 - Ds\Map::get example using array syntax
  • Example#4186 - Ds\Map::hasKey example
  • Example#4187 - Ds\Map::hasValue example
  • Example#4188 - Ds\Map::intersect example
  • Example#4189 - Ds\Map::isEmpty example
  • Example#4190 - Ds\Map::keys example
  • Example#4191 - Ds\Map::ksort example
  • Example#4192 - Ds\Map::ksort example using a comparator
  • Example#4193 - Ds\Map::ksorted example
  • Example#4194 - Ds\Map::ksorted example using a comparator
  • Example#4195 - Ds\Map::last example
  • Example#4196 - Ds\Map::map example
  • Example#4197 - Ds\Map::merge example
  • Example#4198 - Ds\Map::pairs example
  • Example#4199 - Ds\Map::put example
  • Example#4200 - Ds\Map::put example using objects as keys
  • Example#4201 - Ds\Map::putAll example
  • Example#4202 - Ds\Map::reduce with initial value example
  • Example#4203 - Ds\Map::reduce without an initial value example
  • Example#4204 - Ds\Map::remove example
  • Example#4205 - Ds\Map::reverse example
  • Example#4206 - Ds\Map::reversed example
  • Example#4207 - Ds\Map::skip example
  • Example#4208 - Ds\Map::slice example
  • Example#4209 - Ds\Map::sort example
  • Example#4210 - Ds\Map::sort example using a comparator
  • Example#4211 - Ds\Map::sort example
  • Example#4212 - Ds\Map::sort example using a comparator
  • Example#4213 - Ds\Map::sum integer example
  • Example#4214 - Ds\Map::sum float example
  • Example#4215 - Ds\Map::toArray example
  • Example#4216 - Ds\Map::union example
  • Example#4217 - Ds\Map::values example
  • Example#4218 - Ds\Map::xor example
  • Example#4219 - Ds\Pair::clear example
  • Example#4220 - Ds\Pair::copy example
  • Example#4221 - Ds\Pair::isEmpty example
  • Example#4222 - Ds\Pair::toArray example
  • Example#4223 - Ds\Set::add example using integers
  • Example#4224 - Ds\Set::add example using objects
  • Example#4225 - Ds\Set::allocate example
  • Example#4226 - Ds\Set::capacity example
  • Example#4227 - Ds\Set::clear example
  • Example#4228 - Ds\Set::__construct example
  • Example#4229 - Ds\Set::contains example
  • Example#4230 - Ds\Set::copy example
  • Example#4231 - Ds\Set::diff example
  • Example#4232 - Ds\Set::filter example using callback function
  • Example#4233 - Ds\Set::filter example without a callback function
  • Example#4234 - Ds\Set::first example
  • Example#4235 - Ds\Set::get example
  • Example#4236 - Ds\Set::get example using array syntax
  • Example#4237 - Ds\Set::intersect example
  • Example#4238 - Ds\Set::isEmpty example
  • Example#4239 - Ds\Set::join example using a separator string
  • Example#4240 - Ds\Set::join example without a separator string
  • Example#4241 - Ds\Set::last example
  • Example#4242 - Ds\Set::merge example
  • Example#4243 - Ds\Set::reduce with initial value example
  • Example#4244 - Ds\Set::reduce without an initial value example
  • Example#4245 - Ds\Set::remove example
  • Example#4246 - Ds\Set::reverse example
  • Example#4247 - Ds\Set::reversed example
  • Example#4248 - Ds\Set::slice example
  • Example#4249 - Ds\Set::sort example
  • Example#4250 - Ds\Set::sort example using a comparator
  • Example#4251 - Ds\Set::sorted example
  • Example#4252 - Ds\Set::sorted example using a comparator
  • Example#4253 - Ds\Set::sum integer example
  • Example#4254 - Ds\Set::sum float example
  • Example#4255 - Ds\Set::toArray example
  • Example#4256 - Ds\Set::union example
  • Example#4257 - Ds\Set::xor example
  • Example#4258 - Ds\Stack::clear example
  • Example#4259 - Ds\Stack::__construct example
  • Example#4260 - Ds\Stack::copy example
  • Example#4261 - Ds\Stack::isEmpty example
  • Example#4262 - Ds\Stack::peek example
  • Example#4263 - Ds\Stack::pop example
  • Example#4264 - Ds\Stack::push example
  • Example#4265 - Ds\Stack::toArray example
  • Example#4266 - Ds\Queue::allocate example
  • Example#4267 - Ds\Queue::capacity example
  • Example#4268 - Ds\Queue::clear example
  • Example#4269 - Ds\Queue::__construct example
  • Example#4270 - Ds\Queue::copy example
  • Example#4271 - Ds\Queue::isEmpty example
  • Example#4272 - Ds\Queue::peek example
  • Example#4273 - Ds\Queue::pop example
  • Example#4274 - Ds\Queue::push example
  • Example#4275 - Ds\Queue::toArray example
  • Example#4276 - Ds\PriorityQueue::allocate example
  • Example#4277 - Ds\PriorityQueue::capacity example
  • Example#4278 - Ds\PriorityQueue::clear example
  • Example#4279 - Ds\PriorityQueue::__construct example
  • Example#4280 - Ds\PriorityQueue::copy example
  • Example#4281 - Ds\PriorityQueue::isEmpty example
  • Example#4282 - Ds\PriorityQueue::peek example
  • Example#4283 - Ds\PriorityQueue::pop example
  • Example#4284 - Ds\PriorityQueue::push example
  • Example#4285 - Ds\PriorityQueue::toArray example
  • Example#4286 - var_representation Examples
  • Example#4287 - Escaping control characters
  • Example#4288 - Exporting stdClass
  • Example#4289 - Exporting classes
  • Example#4290 - Using __set_state()
  • Example#4291 - PHP の cURL モジュールを使用して example.com のホームページを取得する
  • Example#4292 - 新しい cURL セッションの初期化とウェブページの取得
  • Example#4293 - cURL ハンドルのコピー
  • Example#4294 - curl_errno の例
  • Example#4295 - curl_error の例
  • Example#4296 - curl_escape の例
  • Example#4297 - ウェブページの取得
  • Example#4298 - curl_getinfo の例
  • Example#4299 - curl_getinfo で option パラメータを使う例
  • Example#4300 - 新しい cURL セッションを初期化し、ウェブページを取得する
  • Example#4301 - curl_multi_add_handle の例
  • Example#4302 - curl_multi_close の例
  • Example#4303 - curl_multi_exec の例
  • Example#4304 - curl_multi_info_read の例
  • Example#4305 - curl_multi_init の例
  • Example#4306 - curl_multi_strerror の例
  • Example#4307 - curl_reset の例
  • Example#4308 - 新規に cURL セッションを初期化、ウェブページを取得する
  • Example#4309 - 新規に CURL セッションを初期化、ウェブページを取得する
  • Example#4310 - curl_share_setopt の例
  • Example#4311 - curl_share_init の例
  • Example#4312 - curl_share_setopt の例
  • Example#4313 - curl_errno の例
  • Example#4314 - curl_escape の例
  • Example#4315 - curl_upkeep の例
  • Example#4316 - curl_version の例
  • Example#4317 - CURLFile::__construct の例
  • Example#4318 - CURLFile::__construct で、複数のファイルをアップロードする例
  • Example#4319 - CURLStringFile::__construct の例
  • Example#4320 - Simple HTTP client
  • Example#4321 - HTTP client using asynchronous DNS resolver
  • Example#4322 - Echo server
  • Example#4323 - SSL echo server
  • Example#4324 - Signal handler
  • Example#4325 - Use libevent's loop to process requests of `eio' extension
  • Example#4326 - Miscellaneous
  • Example#4327 - Simple HTTP server
  • Example#4328 - Simple HTTPS server
  • Example#4329 - OpenSSL connection
  • Example#4330 - EventHttpConnection::makeRequest example
  • Example#4331 - Connection listener based on a UNIX domain socket
  • Example#4332 - Simple SMTP server
  • Example#4333 - Handling SIGTERM signal
  • Example#4334 - Adding a custom signal
  • Example#4335 - Adding a timer
  • Example#4336 - EventBase::getFeatures example
  • Example#4337 - EventBase::getMethod example
  • Example#4338 - EventBuffer::search example
  • Example#4339 - EventBufferEvent::connect example
  • Example#4340 - Connect to UNIX domain socket which presumably is served by a server, read response from the server and output it to the console
  • Example#4341 - EventBufferEvent::connectHost example
  • Example#4342 - Buffer event's read callback
  • Example#4343 - EventBufferEvent::getOutput example
  • Example#4344 - EventBufferEvent::sslError example
  • Example#4345 - Simple SMTP server
  • Example#4346 - EventConfig::avoidMethod example
  • Example#4347 - EventConfig::__construct example
  • Example#4348 - EventConfig::requireFeatures example
  • Example#4349 - EventHttp::accept example
  • Example#4350 - EventHttp::addServerAlias example
  • Example#4351 - EventHttp::bind example
  • Example#4352 - Simple HTTP server
  • Example#4353 - EventHttp::setCallback example
  • Example#4354 - EventHttp::setDefaultCallback example
  • Example#4355 - EventHttpConnection::makeRequest example
  • Example#4356 - EventHttpConnection::setCloseCallback example
  • Example#4357 - EventHttpRequest::__construct example
  • Example#4358 - EventHttpRequest::sendError example
  • Example#4359 - EventListener::__construct example
  • Example#4360 - EventSslContext::__construct example
  • Example#4361 - FTP の例
  • Example#4362 - ftp_alloc の例
  • Example#4363 - ftp_cdup の例
  • Example#4364 - ftp_chdir の例
  • Example#4365 - ftp_chmod の例
  • Example#4366 - ftp_close の例
  • Example#4367 - ftp_connect の例
  • Example#4368 - ftp_delete の例
  • Example#4369 - ftp_exec の例
  • Example#4370 - ftp_fget の例
  • Example#4371 - ftp_fput の例
  • Example#4372 - ftp_get の例
  • Example#4373 - ftp_get_option の例
  • Example#4374 - ftp_login の例
  • Example#4375 - ftp_mdtm の例
  • Example#4376 - ftp_mkdir の例
  • Example#4377 - ftp_mlsd の例
  • Example#4378 - ftp_nb_continue の例
  • Example#4379 - ftp_nb_fget の例
  • Example#4380 - ftp_nb_fput の例
  • Example#4381 - ftp_nb_get の例
  • Example#4382 - ftp_nb_get でダウンロードを再開する
  • Example#4383 - ftp_nb_get を用い、ファイルの 100 バイト目以降から ダウンロードを再開する
  • Example#4384 - ftp_nb_put の例
  • Example#4385 - ftp_nb_put でアップロードを再開する
  • Example#4386 - ftp_nlist の例
  • Example#4387 - ftp_pasv の例
  • Example#4388 - ftp_put の例
  • Example#4389 - ftp_pwd の例
  • Example#4390 - ftp_raw を用いて FTP サーバーに手動でログインする
  • Example#4391 - ftp_rawlist の例
  • Example#4392 - ftp_rename の例
  • Example#4393 - ftp_rmdir の例
  • Example#4394 - ftp_set_option の例
  • Example#4395 - SITE コマンドを FTP サーバーに送信する
  • Example#4396 - ftp_size の例
  • Example#4397 - ftp_ssl_connect の例
  • Example#4398 - ftp_systype の例
  • Example#4399 - Basic Gearman client and worker
  • Example#4400 - Basic Gearman client and worker, background
  • Example#4401 - Basic Gearman client and worker, submitting tasks
  • Example#4402 - Adding two job servers
  • Example#4403 - Add two job servers
  • Example#4404 - Basic submission of two tasks
  • Example#4405 - Basic submission of two tasks with passing application context
  • Example#4406 - Two tasks, one background and one not
  • Example#4407 - A high priority task along with two normal tasks
  • Example#4408 - A low priority task along with two normal tasks
  • Example#4409 - Monitor completion of multiple background tasks
  • Example#4410 - Simple job submission with immediate return
  • Example#4411 - Submitting a job and retrieving incremental status
  • Example#4412 - Submit and monitor a background job
  • Example#4413 - Simple job submission with immediate return
  • Example#4414 - Submitting a job and retrieving incremental status
  • Example#4415 - Get the status of a long running job
  • Example#4416 - Monitor the status of a long running background job
  • Example#4417 - Simple worker making use of extra application context data
  • Example#4418 - Add alternate Gearman servers
  • Example#4419 - Add two job servers
  • Example#4420 - GearmanWorker::setId example
  • Example#4421 - A simple worker with a 5 second timeout
  • Example#4422 - Running worker in non-blocking mode
  • Example#4423 - GearmanWorker::work example
  • Example#4424 - ページ分けされた結果コントロールがサポートされているかをテストする
  • Example#4425 - LDAP 検索の例
  • Example#4426 - policy(パスワードポリシー) 情報とバインドする
  • Example#4427 - 空でない場合に限って、説明を変更する
  • Example#4428 - 削除する前に、いくつか値を読み取る
  • Example#4429 - 参照を削除する
  • Example#4430 - 検索結果を複数ページに分割する
  • Example#4431 - 認証型バインドの例
  • Example#4432 - LDAP バインドの使用
  • Example#4433 - LDAP 匿名バインドの使用
  • Example#4434 - パスワード確認の例
  • Example#4435 - LDAP サーバーに接続する例
  • Example#4436 - LDAP サーバーへのセキュアな接続の例
  • Example#4437 - LDAP ページネーション
  • Example#4438 - LDAP ページネーション
  • Example#4439 - ldap_count_entries の例
  • Example#4440 - 全ての LDAP エラーメッセージに番号をふる
  • Example#4441 - エラーを生成し、取得する
  • Example#4442 - Eメールアドレスを検索する
  • Example#4443 - Whoami 拡張オペレーション
  • Example#4444 - PASSWD 拡張オペレーション
  • Example#4445 - 特定のディレクトリエントリに関して保持されている属性のリストを表示
  • Example#4446 - プロトコルのバージョンを調べる
  • Example#4447 - あるディレクトリエントリの全ての "mail" 属性の一覧を表示する
  • Example#4448 - ある組織の全ての組織単位を一覧表示する
  • Example#4449 - contact に電話番号を追加する
  • Example#4450 - ユーザーの名前を変更する
  • Example#4451 - ユーザーにEメールアドレスを2つ追加する
  • Example#4452 - ユーザーのパスワードを変更する
  • Example#4453 - ユーザーのパスワードを変更する(Active Directory)
  • Example#4454 - ldap_parse_result の例
  • Example#4455 - LDAP 検索
  • Example#4456 - プロトコルバージョンの設定
  • Example#4457 - サーバーコントロールの設定
  • Example#4458 - LDAP のソート
  • Example#4459 - memcache 拡張モジュールの概要
  • Example#4460 - memcache セッションハンドラの使用例
  • Example#4461 - Memcache::add の例
  • Example#4462 - Memcache::addServer の例
  • Example#4463 - Memcache::close の例
  • Example#4464 - Memcache::connect の例
  • Example#4465 - Memcache::decrement の例
  • Example#4466 - Memcache::delete の例
  • Example#4467 - Memcache::flush の例
  • Example#4468 - Memcache::get の例
  • Example#4469 - Memcache::getExtendedStats の例
  • Example#4470 - Memcache::getServerStatus の例
  • Example#4471 - Memcache::getVersion の例
  • Example#4472 - Memcache::increment の例
  • Example#4473 - Memcache::pconnect の例
  • Example#4474 - Memcache::replace の例
  • Example#4475 - Memcache::set の例
  • Example#4476 - Memcache::set の例
  • Example#4477 - Memcache::setCompressThreshold の例
  • Example#4478 - Memcache::setServerParams の例
  • Example#4479 - Result コールバックの例
  • Example#4480 - Read-through コールバックの例
  • Example#4481 - Memcached::addServer の例
  • Example#4482 - Memcached::addServers の例
  • Example#4483 - Memcached::append の例
  • Example#4484 - Memcached::cas の例
  • Example#4485 - Memcached オブジェクトの作成
  • Example#4486 - Memcached::decrement の例
  • Example#4487 - Memcached::delete の例
  • Example#4488 - Memcached::fetch の例
  • Example#4489 - Memcached::getDelayed の例
  • Example#4490 - Memcached::flush の例
  • Example#4491 - Memcached::get の例 #1
  • Example#4492 - Memcached::get の例 #2
  • Example#4493 - Memcached::getDelayed の例
  • Example#4494 - Memcached::getMulti example for Memcached v3
  • Example#4495 - Memcached::getMulti example for Memcached v1 and v2
  • Example#4496 - Memcached v3 用の Memcached::GET_PRESERVE_ORDER の例
  • Example#4497 - Memcached v1 および v2 用の Memcached::GET_PRESERVE_ORDER の例
  • Example#4498 - Memcached オプションの取得
  • Example#4499 - Memcached::getResultCode の例
  • Example#4500 - Memcached::getResultMessageメソッドの例
  • Example#4501 - Memcached::getServerByKey の例
  • Example#4502 - Memcached::getServerList の例
  • Example#4503 - Memcached::getStats の例
  • Example#4504 - Memcached::getVersion の例
  • Example#4505 - Memcached::increment の例
  • Example#4506 - Memcached::prepend の例
  • Example#4507 - Memcached::set の例
  • Example#4508 - Memcached::setByKey の例
  • Example#4509 - Memcached::setMulti の例
  • Example#4510 - Memcached オプションの設定
  • Example#4511 - Memcached オプションの設定
  • Example#4512 - mqseries_back の例
  • Example#4513 - mqseries_begin の例
  • Example#4514 - mqseries_close の例
  • Example#4515 - mqseries_cmit の例
  • Example#4516 - mqseries_conn の例
  • Example#4517 - mqseries_connx example
  • Example#4518 - mqseries_connx example using SSL connection & OCSP Responder URL
  • Example#4519 - mqseries_disc の例
  • Example#4520 - mqseries_get example
  • Example#4521 - mqseries_inq の例
  • Example#4522 - mqseries_open の例
  • Example#4523 - mqseries_put の例
  • Example#4524 - mqseries_strerror の例
  • Example#4525 - dns_get_record の使用
  • Example#4526 - dns_get_record と DNS_ANY の使用
  • Example#4527 - fsockopen の例
  • Example#4528 - UDP 接続の使用法
  • Example#4529 - 単純な gethostbyaddr の例
  • Example#4530 - 単純な gethostbyname の例
  • Example#4531 - gethostbynamel の例
  • Example#4532 - 簡単な gethostname 関数の使用例
  • Example#4533 - getprotobyname の例
  • Example#4534 - getservbyname の例
  • Example#4535 - ダウンロードダイアログ
  • Example#4536 - キャッシュディレクティブ
  • Example#4537 - クッキーを設定する
  • Example#4538 - header_register_callback の例
  • Example#4539 - 特定のヘッダを削除する
  • Example#4540 - 以前設定したすべてヘッダを削除する
  • Example#4541 - Example using headers_list
  • Example#4542 - headers_sent 関数の使用例
  • Example#4543 - Web サーバー環境における http_response_code の使用例
  • Example#4544 - CLI 環境における http_response_code の使用例
  • Example#4545 - inet_ntop の例
  • Example#4546 - inet_pton の例
  • Example#4547 - ip2long の例
  • Example#4548 - IP アドレスの表示
  • Example#4549 - setcookie での送信の例
  • Example#4550 - setcookie による削除の例
  • Example#4551 - setcookie と配列
  • Example#4552 - syslog の使用例
  • Example#4553 - Procedural usage of rrd
  • Example#4554 - OO usage of rrd
  • Example#4555 - RRDGraph::setOptions example
  • Example#4556 - Set multiple color options
  • Example#4557 - RRDUpdater::update examples
  • Example#4558 - 収集された呼び出しを取得する
  • Example#4559 - scoutapm が情報を収集する関数の一覧を取得する
  • Example#4560 - snmp_get_quick_print の例
  • Example#4561 - snmp_get_valueretrieval の使用法
  • Example#4562 - snmp_read_mib の使用法
  • Example#4563 - snmp_set_enum_print の使用法
  • Example#4564 - snmprealwalk の使用法
  • Example#4565 - snmp_set_quick_print の使用例
  • Example#4566 - snmp_set_valueretrieval の使用法
  • Example#4567 - snmp2_get の使用法
  • Example#4568 - snmp2_get_next の使用法
  • Example#4569 - snmp2_real_walk の使用法
  • Example#4570 - snmp2_set の使用法
  • Example#4571 - BITS SNMP オブジェクト ID を設定した snmp2_set の使用法
  • Example#4572 - snmp2_pwalk の例
  • Example#4573 - snmp3_get の使用法
  • Example#4574 - snmp3_getnext の使用法
  • Example#4575 - snmp3_real_walk の使用法
  • Example#4576 - snmp3_set の使用法
  • Example#4577 - BITS SNMP オブジェクト ID を設定した snmp3_set の使用法
  • Example#4578 - snmp3_walk の例
  • Example#4579 - snmpget の使用例
  • Example#4580 - snmpgetnext の使用法
  • Example#4581 - snmprealwalk の使用法
  • Example#4582 - snmpset の使用法
  • Example#4583 - BITS SNMP オブジェクト ID を設定した snmpset の使用法
  • Example#4584 - snmpwalk の例
  • Example#4585 - snmpwalkoid の例
  • Example#4586 - SNMP::close の例
  • Example#4587 - sysLocation の取得
  • Example#4588 - 単一の SNMP オブジェクト
  • Example#4589 - 複数の SNMP オブジェクト
  • Example#4590 - SNMP::getErrno の例
  • Example#4591 - SNMP::getError の例
  • Example#4592 - 単一の SNMP オブジェクト
  • Example#4593 - 複数の SNMP オブジェクト
  • Example#4594 - 単一の SNMP オブジェクト ID の設定
  • Example#4595 - 単一の SNMP::set コールによる複数の値の設定
  • Example#4596 - BITS SNMP オブジェクト ID の設定による SNMP::set の使用法
  • Example#4597 - SNMP::setSecurity の例
  • Example#4598 - SNMP::walk の例
  • Example#4599 - suffixAsKey の例
  • Example#4600 - ソケットの例: 簡易 TCP/IP サーバー
  • Example#4601 - ソケットの例: 簡易 TCP/IP クライアント
  • Example#4602 - ソースアドレスを設定するために socket_atmark を使う例
  • Example#4603 - socket_bind を使用してソースアドレスを指定する
  • Example#4604 - socket_create_pair の例
  • Example#4605 - socket_create_pair での IPC の例
  • Example#4606 - socket_get_option の例
  • Example#4607 - socket_import_stream の例
  • Example#4608 - socket_last_error の例
  • Example#4609 - socket_recv の例
  • Example#4610 - socket_recvfrom の例
  • Example#4611 - socket_select での null の使用
  • Example#4612 - socket_select の返す結果を知る
  • Example#4613 - socket_select の例
  • Example#4614 - socket_sendto の例
  • Example#4615 - socket_set_block の例
  • Example#4616 - socket_set_nonblock の例
  • Example#4617 - socket_set_option の例
  • Example#4618 - socket_strerror の例
  • Example#4619 - ssh agent による認証
  • Example#4620 - ホスト公開鍵を使用した認証
  • Example#4621 - 認証メソッドの一覧の取得
  • Example#4622 - パスワードを用いた認証
  • Example#4623 - 公開鍵を用いた認証
  • Example#4624 - ssh2_connect の例
  • Example#4625 - コマンドの実行
  • Example#4626 - シェルをオープンし、それと関連付けられた stderr ストリームを処理する
  • Example#4627 - 既知の値に対するフィンガープリントのチェック
  • Example#4628 - どのメソッドでネゴシエートされたかの判定
  • Example#4629 - ssh2_publickey_add で公開鍵を追加する
  • Example#4630 - 認証済みの鍵の一覧を ssh2_publickey_list で表示する
  • Example#4631 - SCP 経由でのファイルのダウンロード
  • Example#4632 - SCP 経由でのファイルのアップロード
  • Example#4633 - SFTP 経由でのファイルのオープン
  • Example#4634 - リモートサーバー上でのファイルのモード変更
  • Example#4635 - SFTP 経由でのシンボリックリンクの情報の取得
  • Example#4636 - リモートサーバー上へのディレクトリの作成
  • Example#4637 - シンボリックリンクの読み込み
  • Example#4638 - パス名の解決
  • Example#4639 - sftp 経由でのファイルの改名
  • Example#4640 - リモートサーバー上のディレクトリの削除
  • Example#4641 - SFTP 経由でのファイルの情報の取得
  • Example#4642 - シンボリックリンクの作成
  • Example#4643 - ファイルの削除
  • Example#4644 - 対話シェルのリクエスト
  • Example#4645 - 任意のホストへのトンネルのオープン
  • Example#4646 - オブジェクト指向型
  • Example#4647 - 手続き型
  • Example#4648 - stomp_connect_error example
  • Example#4649 - stomp_version example
  • Example#4650 - オブジェクト指向型
  • Example#4651 - 手続き型
  • Example#4652 - オブジェクト指向型
  • Example#4653 - 手続き型
  • Example#4654 - オブジェクト指向型
  • Example#4655 - 手続き型
  • Example#4656 - オブジェクト指向型
  • Example#4657 - 手続き型
  • Example#4658 - オブジェクト指向型
  • Example#4659 - 手続き型
  • Example#4660 - オブジェクト指向型
  • Example#4661 - 手続き型
  • Example#4662 - オブジェクト指向型
  • Example#4663 - 手続き型
  • Example#4664 - オブジェクト指向型
  • Example#4665 - 手続き型
  • Example#4666 - オブジェクト指向型
  • Example#4667 - 手続き型
  • Example#4668 - Train from array
  • Example#4669 - Train from a file
  • Example#4670 - svn_add example
  • Example#4671 - デフォルトの認証の例
  • Example#4672 - svn_blame の例
  • Example#4673 - 基本的な例
  • Example#4674 - 基本的な例
  • Example#4675 - 基本的な例
  • Example#4676 - 基本的な例
  • Example#4677 - Basic example
  • Example#4678 - 基本的な例
  • Example#4679 - あるパスのふたつのリビジョンの差分の取得
  • Example#4680 - ローカルファイルの差分の取得
  • Example#4681 - svn_export example
  • Example#4682 - 基本的な例
  • Example#4683 - svn_log の例
  • Example#4684 - svn_ls example
  • Example#4685 - Basic example
  • Example#4686 - Basic example
  • Example#4687 - ローカルホストからの全接続を拒否する
  • Example#4688 - URL を禁止する
  • Example#4689 - 統計のスナップショットを取得する
  • Example#4690 - varnish の共用メモリログを読み取る
  • Example#4691 - VarnishAdmin::__construct の例
  • Example#4692 - YAZ による並列検索
  • Example#4693 - CCL 設定
  • Example#4694 - CCL のパース
  • Example#4695 - レコードの更新
  • Example#4696 - GRS-1 レコードの配列
  • Example#4697 - MARCXML の使用
  • Example#4698 - タイトルをスキャンする PHP 関数
  • Example#4699 - クエリの例
  • Example#4700 - ソート条件
  • Example#4701 - A ZMQContext example
  • Example#4702 - A ZMQContext example
  • Example#4703 - A ZMQContext example
  • Example#4704 - A ZMQSocket example
  • Example#4705 - A send/recv example
  • Example#4706 - A ZMQPoll example
  • Example#4707 - zookeeper_dispatch example #1
  • Example#4708 - zookeeper_dispatch example #2
  • Example#4709 - Zookeeper::addAuth example
  • Example#4710 - Zookeeper::create example
  • Example#4711 - Zookeeper::delete example
  • Example#4712 - Zookeeper::exists example
  • Example#4713 - Zookeeper::get example
  • Example#4714 - Zookeeper::get stat example
  • Example#4715 - Zookeeper::getAcl example
  • Example#4716 - Zookeeper::getChildren example
  • Example#4717 - Zookeeper::set example
  • Example#4718 - Zookeeper::setAcl example
  • Example#4719 - Zookeeper::setDebugLevel example
  • Example#4720 - ZookeeperConfig::add example
  • Example#4721 - ZookeeperConfig::get example
  • Example#4722 - ZookeeperConfig::remove example
  • Example#4723 - ZookeeperConfig::set example
  • Example#4724 - solr_get_version の例
  • Example#4725 - ブートストラップ・ファイルの内容
  • Example#4726 - インデックスに文書を追加
  • Example#4727 - ある文書を他の文書にマージ
  • Example#4728 - 文書を検索 - SolrObject レスポンス
  • Example#4729 - 文書を検索 - SolrDocument レスポンス
  • Example#4730 - 簡単な TermsComponent 例 - 基本
  • Example#4731 - 簡単な TermsComponent 例 - 接頭辞を使用
  • Example#4732 - 簡単な TermsComponent 例 - 最小の頻度を指定
  • Example#4733 - 簡単なファセット例
  • Example#4734 - 簡単なファセット例 - mincount を越える任意の項目と共に
  • Example#4735 - Facet Date の例
  • Example#4736 - SSL 対応サーバーに接続
  • Example#4737 - Collapsing a SolrQuery
  • Example#4738 - Solr Real Time Get (RTG) の例 SolrClient::getById
  • Example#4739 - SolrInputDocument::addChildDocument example
  • Example#4740 - SolrInputDocument::addChildDocuments example
  • Example#4741 - SolrDocument::toArray の例
  • Example#4742 - SolrObject::__construct 例
  • Example#4743 - SolrObject::offsetUnset の例
  • Example#4744 - SolrClient::addDocument example
  • Example#4745 - SolrClient::addDocument example 2
  • Example#4746 - SolrClient::addDocuments example
  • Example#4747 - SolrClient::__construct example
  • Example#4748 - SolrQuery::deleteByQuery example
  • Example#4749 - SolrClient::getById example
  • Example#4750 - SolrClient::getByIds example
  • Example#4751 - SolrClient::ping example
  • Example#4752 - SolrClient::query example
  • Example#4753 - SolrClient::request example
  • Example#4754 - SolrClient::setResponseWriter example
  • Example#4755 - SolrParams::setParam の例
  • Example#4756 - SolrQuery::addFacetField example
  • Example#4757 - SolrQuery::addFacetField example
  • Example#4758 - SolrQuery::addFilterQuery example
  • Example#4759 - SolrQuery::addGroupSortField example
  • Example#4760 - SolrQuery::collapse example
  • Example#4761 - SolrQuery::setExpand example
  • Example#4762 - SolrDisMaxQuery::addBigramPhraseField example
  • Example#4763 - SolrDisMaxQuery::addBoostQuery example
  • Example#4764 - SolrDisMaxQuery::addPhraseField example
  • Example#4765 - SolrDisMaxQuery::addQueryField example
  • Example#4766 - SolrDisMaxQuery::addTrigramPhraseField example
  • Example#4767 - SolrDisMaxQuery::addUserField example
  • Example#4768 - SolrDisMaxQuery::__construct example
  • Example#4769 - SolrDisMaxQuery::removeBigramPhraseField example
  • Example#4770 - SolrDisMaxQuery::removeBoostQuery example
  • Example#4771 - SolrDisMaxQuery::removePhraseField example
  • Example#4772 - SolrDisMaxQuery::removeQueryField example
  • Example#4773 - SolrDisMaxQuery::removeTrigramPhraseField example
  • Example#4774 - SolrDisMaxQuery::removeUserField example
  • Example#4775 - SolrDisMaxQuery::setBigramPhraseFields example
  • Example#4776 - SolrDisMaxQuery::setBigramPhraseSlop example
  • Example#4777 - SolrDisMaxQuery::setBoostFunction example
  • Example#4778 - SolrDisMaxQuery::setBoostQuery example
  • Example#4779 - SolrDisMaxQuery::setMinimumMatch example
  • Example#4780 - SolrDisMaxQuery::setPhraseFields example
  • Example#4781 - SolrDisMaxQuery::setPhraseSlop example
  • Example#4782 - SolrDisMaxQuery::setQueryAlt example
  • Example#4783 - SolrDisMaxQuery::setQueryPhraseSlop example
  • Example#4784 - SolrDisMaxQuery::setTieBreaker example
  • Example#4785 - SolrDisMaxQuery::setTrigramPhraseFields example
  • Example#4786 - SolrDisMaxQuery::setTrigramPhraseSlop example
  • Example#4787 - SolrDisMaxQuery::setUserFields example
  • Example#4788 - SolrDisMaxQuery::useDisMaxQueryParser example
  • Example#4789 - SolrDisMaxQuery::useEDisMaxQueryParser example
  • Example#4790 - SolrCollapseFunction::__construct example
  • Example#4791 - SolrCollapseFunction::setHint example
  • Example#4792 - SolrCollapseFunction::setMax example
  • Example#4793 - .htaccess により、あるディレクトリの PHP によるパースを無効にする
  • Example#4794 - apache_get_modules の例
  • Example#4795 - apache_get_version の例
  • Example#4796 - apache_getenv の例
  • Example#4797 - apache_lookup_uri の例
  • Example#4798 - PHP と Perl との間での情報のやりとり
  • Example#4799 - access.log への出力
  • Example#4800 - apache_request_headers の例
  • Example#4801 - apache_response_headers の例
  • Example#4802 - apache_setenv を使った Apache 環境変数の設定
  • Example#4803 - getallheaders の例
  • Example#4804 - $_SESSIONで変数を登録
  • Example#4805 - 変数を $_SESSION から削除する
  • Example#4806 - 単一のユーザーに関するヒット数を数える
  • Example#4807 - 情報の例
  • Example#4808 - session_cache_expire の例
  • Example#4809 - session_cache_limiter の例
  • Example#4810 - session_regenerate_id と一緒に、session_create_id を使う例
  • Example#4811 - $_SESSIONでセッションを破棄する
  • Example#4812 - cron のようなタスクマネージャでの session_gc の例
  • Example#4813 - ユーザーがアクセス可能なスクリプトでの session_gc の例
  • Example#4814 - session_name の例
  • Example#4815 - session_regenerate_id の使用例
  • Example#4816 - session_regenerate_id による、セッションの消失を避ける
  • Example#4817 - 自作のセッションハンドラ: 完全なコードは SessionHandlerInterface を参照
  • Example#4818 - page1.php
  • Example#4819 - page2.php
  • Example#4820 - クッキーの有効期限の上書き
  • Example#4821 - セッションの読み込みとクローズ
  • Example#4822 - SessionHandler を使って PHP の保存ハンドラに暗号化機能を追加する例
  • Example#4823 - SessionHandlerInterface の使用例
  • Example#4824 - Tokenize comma separated integer list
  • Example#4825 - Tokenize assign statement
  • Example#4826 - Simple calculator
  • Example#4827 - Parse words out from a sentence
  • Example#4828 - 有効なパターンの例
  • Example#4829 - 無効なパターンの例
  • Example#4830 - パターンの中でのコメントの使い方
  • Example#4831 - preg_filter と preg_replace の比較
  • Example#4832 - preg_grep の例
  • Example#4833 - preg_last_error の例
  • Example#4834 - preg_last_error_msg example
  • Example#4835 - 文字列 "php" を探す
  • Example#4836 - 単語 "web" を探す
  • Example#4837 - URL からドメイン名を得る
  • Example#4838 - 名前つきサブパターンの使用法
  • Example#4839 - テキストからすべての電話番号を得る
  • Example#4840 - HTML タグにマッチするものを見付ける（貪欲）
  • Example#4841 - 名前つきサブパターンの使用法
  • Example#4842 - preg_quote の例
  • Example#4843 - テキスト内の単語の斜体変換
  • Example#4844 - 数字リテラルが後に続く後方参照
  • Example#4845 - 添字配列の使用
  • Example#4846 - 複数値の置換
  • Example#4847 - 空白の削除
  • Example#4848 - count 引数の使用
  • Example#4849 - preg_replace_callback と無名関数
  • Example#4850 - preg_replace_callback の例
  • Example#4851 - カプセル化された BB code を処理するための、 preg_replace_callback での再帰構造の使用
  • Example#4852 - preg_replace_callback_array の例
  • Example#4853 - preg_split の例 : 検索文字列のある部分を取得
  • Example#4854 - 文字列を文字要素に分割
  • Example#4855 - 文字列をマッチするものとそのオフセットに分割
  • Example#4856 - addcslashes の例
  • Example#4857 - addslashes の例
  • Example#4858 - bin2hex の例
  • Example#4859 - chr の例
  • Example#4860 - オーバーフローの挙動
  • Example#4861 - 個別のバイトから、UTF-8 文字列を組み立てる
  • Example#4862 - chunk_split の例
  • Example#4863 - convert_uudecode の例
  • Example#4864 - convert_uuencode の例
  • Example#4865 - count_chars の例
  • Example#4866 - crc32 チェックサムの表示
  • Example#4867 - crypt の例
  • Example#4868 - echo の例
  • Example#4869 -
  • Example#4870 - explode の例
  • Example#4871 - explode の戻り値の例
  • Example#4872 - limit パラメータの例
  • Example#4873 - fprintf: 数値のゼロ埋め
  • Example#4874 - fprintf: 金額のフォーマット
  • Example#4875 - 変換テーブルの例
  • Example#4876 - hex2bin の例
  • Example#4877 - HTML エンティティのデコード
  • Example#4878 - htmlentities の例
  • Example#4879 - ENT_IGNORE の使用例
  • Example#4880 - htmlspecialchars の例
  • Example#4881 - htmlspecialchars_decode の例
  • Example#4882 - implode の例
  • Example#4883 - lcfirst の例
  • Example#4884 - levenshtein の例
  • Example#4885 - localeconv の例
  • Example#4886 - ltrim の使用例
  • Example#4887 - md5 の例
  • Example#4888 - md5_file の使用例
  • Example#4889 - metaphone の基本的な例
  • Example#4890 - phonemes パラメータの使用例
  • Example#4891 - phonemes 引数を使う
  • Example#4892 - money_format の例
  • Example#4893 - nl_langinfo の例
  • Example#4894 - nl2br の使用法
  • Example#4895 - use_xhtml パラメータを使い、妥当な HTML 形式のマークアップを生成する
  • Example#4896 - さまざまな改行文字
  • Example#4897 - number_format の例
  • Example#4898 - ord の例
  • Example#4899 - UTF-8 の文字列をバイト単位で調べる
  • Example#4900 - parse_str の使用法
  • Example#4901 - parse_str name mangling
  • Example#4902 - print の例
  • Example#4903 -
  • Example#4904 -
  • Example#4905 - printf: の様々な例
  • Example#4906 - printf: 文字列の指定子
  • Example#4907 - quoted_printable_decode の例
  • Example#4908 - quoted_printable_encode の例
  • Example#4909 - quotemeta の例
  • Example#4910 - rtrim の使用例
  • Example#4911 - setlocale の例
  • Example#4912 - Windows での setlocale の例
  • Example#4913 - sha1 の例
  • Example#4914 - sha1_file の例
  • Example#4915 - similar_text で、引数を入れ替えた場合の例
  • Example#4916 - Soundex の例
  • Example#4917 - 引数の交換
  • Example#4918 - 埋める文字を指定する
  • Example#4919 - 位置指定子と他の指定との共用
  • Example#4920 - sprintf: ゼロ埋めされた数値
  • Example#4921 - sprintf: 通貨フォーマット
  • Example#4922 - sprintf: 科学的記法
  • Example#4923 - sscanf の例
  • Example#4924 - sscanf - オプションパラメータの使用法
  • Example#4925 - 空文字列 '' を使った場合
  • Example#4926 - 大文字小文字の区別
  • Example#4927 - str_decrement の基本的な使い方
  • Example#4928 - 繰り下がりがある、str_decrement の例
  • Example#4929 - 空文字列 '' を使う場合
  • Example#4930 - 大文字小文字の区別
  • Example#4931 - str_getcsv の例
  • Example#4932 - str_getcsv に空文字列を指定した例
  • Example#4933 - str_increment の基本的な使い方
  • Example#4934 - 繰り上げがある、str_increment の例
  • Example#4935 - str_ireplace の例
  • Example#4936 - str_pad の例
  • Example#4937 - str_repeat の例
  • Example#4938 - 基本的な str_replace の例
  • Example#4939 - str_replace に関するちょっとした事実
  • Example#4940 - str_rot13 の例
  • Example#4941 - str_shuffle の例
  • Example#4942 - str_split の使用例
  • Example#4943 - 空文字列 '' を使う場合
  • Example#4944 - 大文字小文字の区別
  • Example#4945 - str_word_count の例
  • Example#4946 - strcasecmp の例
  • Example#4947 - strcmp の例
  • Example#4948 - strcspn の例
  • Example#4949 - strip_tags の例
  • Example#4950 - stripcslashes の例
  • Example#4951 - stripos の例
  • Example#4952 - stripslashes の例
  • Example#4953 - 配列に対する stripslashes の使用
  • Example#4954 - stristr の例
  • Example#4955 - 文字列が見つかるかどうかをテストする
  • Example#4956 - 文字列以外の needle の指定
  • Example#4957 - strlen の例
  • Example#4958 - strnatcasecmp の例
  • Example#4959 - strncasecmp の例
  • Example#4960 - strncmp の例
  • Example#4961 - strpbrk の例
  • Example#4962 - === の使用
  • Example#4963 - !== の使用
  • Example#4964 - オフセットの使用
  • Example#4965 - strrchr の例
  • Example#4966 - strrev で文字列を逆順にする
  • Example#4967 - 単純な strripos の例
  • Example#4968 - needle が haystack の中にあるかどうかの確認
  • Example#4969 - オフセットつきの検索
  • Example#4970 - strspn の例
  • Example#4971 - strstr の例
  • Example#4972 - strtok の例
  • Example#4973 - 空の部分が見つかった場合の strtok の動作
  • Example#4974 - strtok と explode の違い
  • Example#4975 - strtolower の例
  • Example#4976 - strtoupper の例
  • Example#4977 - strtr の例
  • Example#4978 - 2 つの引数を伴う strtr の例
  • Example#4979 - strtr の挙動の比較
  • Example#4980 - 負の offset の使用
  • Example#4981 - 負の length の使用
  • Example#4982 - 基本的な substr の使用法
  • Example#4983 - substr でのキャストの挙動
  • Example#4984 - 文字列の範囲が不正な場合
  • Example#4985 - substr_compare の例
  • Example#4986 - substr_count の例
  • Example#4987 - シンプルな substr_replace の例
  • Example#4988 - substr_replace で複数の文字列を一度に置換する例
  • Example#4989 - trimの使用例
  • Example#4990 - trim を用いて配列の値をトリミングする
  • Example#4991 - ucfirst の例
  • Example#4992 - ucwords の例
  • Example#4993 - ucwords で、区切り文字を指定する例
  • Example#4994 - ucwords で、追加の区切り文字を指定する例
  • Example#4995 - 基本的な例
  • Example#4996 - 基本的な例
  • Example#4997 - vfprintf: 数値のゼロ埋め
  • Example#4998 - vprintf: 整数のゼロ埋め
  • Example#4999 - vsprintf: 整数のゼロ埋め
  • Example#5000 - wordwrap の例
  • Example#5001 - wordwrap の例
  • Example#5002 - wordwrap の例
  • Example#5003 - array の例
  • Example#5004 - array における自動インデックス
  • Example#5005 - array で 1 から始まる配列を作成
  • Example#5006 - ダブルクオートで囲まれた配列にアクセスする
  • Example#5007 - array_change_key_case の例
  • Example#5008 - array_chunk の例
  • Example#5009 - レコードセットからのファーストネームの取得
  • Example#5010 - レコードセットから姓を取得し、"id"で並べ替える例
  • Example#5011 - オブジェクトの public プロパティ "username" からユーザー名を取得する例
  • Example#5012 - オブジェクトの private プロパティ "name" から、マジックメソッド __get を使って名前を取得する例
  • Example#5013 - array_combineの簡単な例
  • Example#5014 - array_count_values の例
  • Example#5015 - array_diff の例
  • Example#5016 - 型が一致しない場合の array_diff の例
  • Example#5017 - array_diff_assoc の例
  • Example#5018 - array_diff_assoc の例
  • Example#5019 - array_diff_key の例
  • Example#5020 - array_diff_uassoc の例
  • Example#5021 - array_diff_ukey の例
  • Example#5022 - array_fill の例
  • Example#5023 - 最初のインデックスが負の場合の、array_fill の例
  • Example#5024 - array_fill_keys の例
  • Example#5025 - array_filter の例
  • Example#5026 - callback がない array_filter
  • Example#5027 - array_filter で mode を使う例
  • Example#5028 - array_flip の例
  • Example#5029 - array_flip の例 : 衝突
  • Example#5030 - array_intersect の例
  • Example#5031 - array_intersect_assoc の例
  • Example#5032 - array_intersect_key の例
  • Example#5033 - array_intersect_uassoc の例
  • Example#5034 - array_intersect_ukey の例
  • Example#5035 - array_is_list example
  • Example#5036 - array_key_exists の例
  • Example#5037 - array_key_exists 対 isset
  • Example#5038 - 基本的な array_key_first 関数の使い方
  • Example#5039 - array_keys の例
  • Example#5040 - array_map の例
  • Example#5041 - array_map でラムダ関数を使用する例
  • Example#5042 - array_map - もっと配列を使ってみる例
  • Example#5043 - 配列のzip操作を行う
  • Example#5044 - null を callback に渡し、 array だけを渡す例
  • Example#5045 - array_map - 文字列キーの例
  • Example#5046 - array_map と連想配列
  • Example#5047 - array_merge の例
  • Example#5048 - 簡単な array_merge の例
  • Example#5049 - array_merge で配列以外の型を扱う例
  • Example#5050 - array_merge_recursive の例
  • Example#5051 - 複数の配列をソートする
  • Example#5052 - 多次元の配列をソートする
  • Example#5053 - データベースの結果をソートする
  • Example#5054 - 大文字・小文字を区別しないソート
  • Example#5055 - array_pad の例
  • Example#5056 - array_pop の例
  • Example#5057 - array_product の例
  • Example#5058 - array_push の例
  • Example#5059 - array_rand の例
  • Example#5060 - array_reduce の例
  • Example#5061 - array_replace の例
  • Example#5062 - array_replace_recursive の例
  • Example#5063 - array_replace_recursive での再帰的な挙動の例
  • Example#5064 - array_reverse の例
  • Example#5065 - array_search の例
  • Example#5066 - array_shift の例
  • Example#5067 - array_slice の例
  • Example#5068 - array_slice と、キーが1から始まる配列
  • Example#5069 - array_slice に、数値と文字列のキーが混じった配列を渡す例
  • Example#5070 - array_splice の例
  • Example#5071 - 同じ動きをする、array_splice の様々な例
  • Example#5072 - array_sum の例
  • Example#5073 - array_udiff で stdClass オブジェクトを使う例
  • Example#5074 - array_udiff で DateTime オブジェクトを使う例
  • Example#5075 - array_udiff_assoc の例
  • Example#5076 - array_udiff_uassoc の例
  • Example#5077 - array_uintersect の例
  • Example#5078 - array_uintersect_assoc の例
  • Example#5079 - array_uintersect_uassoc の例
  • Example#5080 - array_unique の例
  • Example#5081 - array_unique と型
  • Example#5082 - array_unshift の例
  • Example#5083 - 連想配列と一緒に使う例
  • Example#5084 - array_values の例
  • Example#5085 - array_walk の例
  • Example#5086 - 無名関数を使った、array_walk の例
  • Example#5087 - array_walk_recursive の例
  • Example#5088 - arsort の例
  • Example#5089 - asort の例
  • Example#5090 - compact の例
  • Example#5091 - count の例
  • Example#5092 - Countable|array でない値を渡した場合の count の例 (悪い例です - 真似しないでね！)
  • Example#5093 - 再帰的な count の例
  • Example#5094 - Countable オブジェクトの例
  • Example#5095 - current と類似関数の使用例
  • Example#5096 - each の例
  • Example#5097 - each によって配列を走査する
  • Example#5098 - end の例
  • Example#5099 - extract の例
  • Example#5100 - in_array の例
  • Example#5101 - strict を指定した in_array の例
  • Example#5102 - needleが配列の場合の in_array
  • Example#5103 - key の例
  • Example#5104 - krsort の例
  • Example#5105 - ksort の例
  • Example#5106 - 数値がキーの場合の ksort の振る舞い
  • Example#5107 - list の例
  • Example#5108 - list の使用法の例
  • Example#5109 - ネストした list の使用法
  • Example#5110 - list と添字の定義順
  • Example#5111 - list をキーを指定して使う
  • Example#5112 - natcasesort の例
  • Example#5113 - natsort の基本的な使用例
  • Example#5114 - natsort をより知るための例
  • Example#5115 - next および類似関数の使用例
  • Example#5116 - prev および類似関数の使用例
  • Example#5117 - range の例
  • Example#5118 - reset の例
  • Example#5119 - rsort の例
  • Example#5120 - shuffle の例
  • Example#5121 - sort の例
  • Example#5122 - sort で、大文字小文字を区別せずに自然順での並べ替えを行う例
  • Example#5123 - 基本的な uasort の例
  • Example#5124 - uksort の例
  • Example#5125 - usort の例
  • Example#5126 - 多次元配列を使用する usort の例
  • Example#5127 - usort でオブジェクトのメンバ関数を使用する例
  • Example#5128 - usort で クロージャ を使って多次元配列をソートする例
  • Example#5129 - usort と宇宙船演算子
  • Example#5130 - クラスの定義
  • Example#5131 - test_script.php
  • Example#5132 - class_alias の例
  • Example#5133 - class_exists の例
  • Example#5134 - autoload パラメータの例
  • Example#5135 - enum_exists の例
  • Example#5136 - get_called_class の使用法
  • Example#5137 - get_class の使用例
  • Example#5138 - get_class のスーパークラスでの使用例
  • Example#5139 - 名前空間の中にあるクラスを get_class で使う
  • Example#5140 - get_class_methods の例
  • Example#5141 - get_class_vars の例
  • Example#5142 - get_class_vars でのスコープの挙動
  • Example#5143 - get_declared_classes の例
  • Example#5144 - get_declared_interfaces の例
  • Example#5145 - get_mangled_object_vars の例
  • Example#5146 - get_object_vars の使用例
  • Example#5147 - get_parent_class の使用例
  • Example#5148 - interface_exists の例
  • Example#5149 - is_a の例
  • Example#5150 - instanceof 演算子の使用
  • Example#5151 - is_subclass_of の例
  • Example#5152 - is_subclass_of でインターフェイスを使う例
  • Example#5153 - method_exists の例
  • Example#5154 - staticメソッドに対する method_exists の例
  • Example#5155 - property_exists の例
  • Example#5156 - A ctype_alnum の例 (デフォルトのロケールを使用)
  • Example#5157 - ctype_alphaの例 (デフォルトのロケールを使用)
  • Example#5158 - ctype_cntrl の例
  • Example#5159 - ctype_digit の例
  • Example#5160 - ctype_digit で文字列と整数値を比較する例
  • Example#5161 - ctype_graph の例
  • Example#5162 - ctype_lower の例（デフォルトのロケールを利用）
  • Example#5163 - ctype_print の例
  • Example#5164 - ctype_punct の例
  • Example#5165 - ctype_space の例
  • Example#5166 - ctype_upper の例（デフォルトのロケールを利用）
  • Example#5167 - ctype_xdigit の例
  • Example#5168 - デフォルトフィルタを htmlspecialchars と同様の挙動にする設定
  • Example#5169 - デフォルトのフィルタを htmlspecialchars と同様の挙動にする設定
  • Example#5170 - filter_var でのメールアドレスの検証
  • Example#5171 - filter_var での IP アドレスの検証
  • Example#5172 - filter_var でのオプションの指定
  • Example#5173 - メールアドレスの検証、および不正な部分の除去
  • Example#5174 - デフォルトのフィルタの設定
  • Example#5175 - filter_input の例
  • Example#5176 - filter_input_array の例
  • Example#5177 - filter_list の例
  • Example#5178 - filter_var の例
  • Example#5179 - 配列をフィルタする例
  • Example#5180 - filter_var_array の例
  • Example#5181 - call_user_func の例と参照
  • Example#5182 - call_user_func の例
  • Example#5183 - 名前空間を使用した call_user_func
  • Example#5184 - call_user_func でのクラスメソッドの使用
  • Example#5185 - call_user_func でのラムダ関数の使用
  • Example#5186 - call_user_func_array の例
  • Example#5187 - call_user_func_array での名前空間の使用法
  • Example#5188 - ラムダ関数の使用
  • Example#5189 - 値の参照渡し
  • Example#5190 - call_user_func_array を名前付き引数と一緒に使う
  • Example#5191 - create_function や無名関数を使い、動的に関数を作成する
  • Example#5192 - create_function や無名関数を使い、一般的な処理を行う関数を作成する
  • Example#5193 - 動的な関数をコールバック関数として使う
  • Example#5194 - forward_static_call の例
  • Example#5195 - forward_static_call_array の例
  • Example#5196 - func_get_arg の例
  • Example#5197 - func_get_arg での引数の参照渡しと値渡しの例
  • Example#5198 - func_get_args の例
  • Example#5199 - func_get_args での引数の参照渡しと値渡しの例
  • Example#5200 - func_num_args の例
  • Example#5201 - function_exists の例
  • Example#5202 - get_defined_functions の例
  • Example#5203 - register_shutdown_function の例
  • Example#5204 - register_tick_function の例
  • Example#5205 - Quickhash Example
  • Example#5206 - Quickhash ArrayAccess Example
  • Example#5207 - Quickhash Iterator Example
  • Example#5208 - Quickhash String Values Example
  • Example#5209 - QuickHashIntSet::add example
  • Example#5210 - QuickHashIntSet::__construct example
  • Example#5211 - QuickHashIntSet::delete example
  • Example#5212 - QuickHashIntSet::exists example
  • Example#5213 - QuickHashIntSet::getSize example
  • Example#5214 - QuickHashIntSet::loadFromFile example
  • Example#5215 - QuickHashIntSet::loadFromString example
  • Example#5216 - QuickHashIntSet::saveToFile example
  • Example#5217 - QuickHashIntSet::saveToString example
  • Example#5218 - QuickHashIntHash::add example
  • Example#5219 - QuickHashIntHash::__construct example
  • Example#5220 - QuickHashIntHash::delete example
  • Example#5221 - QuickHashIntHash::exists example
  • Example#5222 - QuickHashIntHash::get example
  • Example#5223 - QuickHashIntHash::getSize example
  • Example#5224 - QuickHash IntHash file format
  • Example#5225 - QuickHash IntHash file format
  • Example#5226 - QuickHashIntHash::loadFromFile example
  • Example#5227 - QuickHashIntHash::loadFromString example
  • Example#5228 - QuickHashIntHash::saveToFile example
  • Example#5229 - QuickHashIntHash::saveToString example
  • Example#5230 - QuickHashIntHash::set example
  • Example#5231 - QuickHashIntHash::update example
  • Example#5232 - QuickHashStringIntHash::add example
  • Example#5233 - QuickHashStringIntHash::__construct example
  • Example#5234 - QuickHashStringIntHash::delete example
  • Example#5235 - QuickHashStringIntHash::get example
  • Example#5236 - QuickHashStringIntHash::getSize example
  • Example#5237 - QuickHash StringIntHash file format
  • Example#5238 - QuickHash IntHash file format
  • Example#5239 - QuickHashStringIntHash::loadFromFile example
  • Example#5240 - QuickHashStringIntHash::loadFromString example
  • Example#5241 - QuickHashStringIntHash::saveToFile example
  • Example#5242 - QuickHashStringIntHash::saveToString example
  • Example#5243 - QuickHashStringIntHash::set example
  • Example#5244 - QuickHashStringIntHash::update example
  • Example#5245 - QuickHashIntStringHash::add example
  • Example#5246 - QuickHashIntStringHash::__construct example
  • Example#5247 - QuickHashIntStringHash::delete example
  • Example#5248 - QuickHashIntStringHash::get example
  • Example#5249 - QuickHashIntStringHash::getSize example
  • Example#5250 - QuickHash IntString file format
  • Example#5251 - QuickHash IntString file format
  • Example#5252 - QuickHashIntStringHash::loadFromFile example
  • Example#5253 - QuickHashIntStringHash::loadFromString example
  • Example#5254 - QuickHashIntStringHash::saveToFile example
  • Example#5255 - QuickHashIntStringHash::saveToString example
  • Example#5256 - QuickHashIntStringHash::set example
  • Example#5257 - QuickHashIntStringHash::update example
  • Example#5258 - シェル (ターミナル) からのリフレクションの例
  • Example#5259 - 組み込みクラスを拡張する
  • Example#5260 - Reflection::getModifierNames の例
  • Example#5261 - ReflectionClass の基本的な使用例
  • Example#5262 - ReflectionClass::export の基本的な使用例
  • Example#5263 - 基本的な使用法
  • Example#5264 - クラス名で結果をフィルタする
  • Example#5265 - クラス名、かつ継承も考慮して結果をフィルタする
  • Example#5266 - ReflectionClass::getConstant の使い方
  • Example#5267 - ReflectionClass::getConstructor の基本的な使用例
  • Example#5268 - ReflectionClass::getDefaultProperties の例
  • Example#5269 - ReflectionClass::getDocComment の例
  • Example#5270 - ReflectionClass::getEndLine の例
  • Example#5271 - ReflectionClass::getExtension の基本的な使用例
  • Example#5272 - ReflectionClass::getExtensionName の基本的な使用例
  • Example#5273 - ReflectionClass::getInterfaceNames の例
  • Example#5274 - ReflectionClass::getInterfaces の例
  • Example#5275 - ReflectionClass::getMethod の基本的な使用例
  • Example#5276 - ReflectionClass::getMethods の基本的な使用例
  • Example#5277 - ReflectionClass::getMethods のフィルタリング
  • Example#5278 - ReflectionClass::getName の例
  • Example#5279 - ReflectionClass::getNamespaceName の例
  • Example#5280 - ReflectionClass::getProperties でのフィルタリングの例
  • Example#5281 - ReflectionClass::getProperty の基本的な使用例
  • Example#5282 - 基本的な ReflectionClass::getReflectionConstants の例
  • Example#5283 - ReflectionClass::getShortName の例
  • Example#5284 - ReflectionClass::getStaticPropertyValue の基本的な使用例
  • Example#5285 - ReflectionClass::hasConstant の例
  • Example#5286 - ReflectionClass::hasMethod の例
  • Example#5287 - ReflectionClass::hasProperty の例
  • Example#5288 - ReflectionClass::inNamespace の例
  • Example#5289 - ReflectionClass::isAbstract の例
  • Example#5290 - ReflectionClass::isAnonymous の例
  • Example#5291 - ReflectionClass::isCloneable の基本的な使用例
  • Example#5292 - ReflectionClass::isFinal の例
  • Example#5293 - ReflectionClass::isInstance の例
  • Example#5294 - ReflectionClass::isInstantiable の例
  • Example#5295 - ReflectionClass::isInterface の基本的な使用例
  • Example#5296 - ReflectionClass::isInternal の基本的な使用例
  • Example#5297 - 基本的な ReflectionClass::isIterable の例
  • Example#5298 - ReflectionClass::isReadOnly の例
  • Example#5299 - ReflectionClass::newInstanceArgs の基本的な使用例
  • Example#5300 - ReflectionClass::__toString の例
  • Example#5301 - 基本的な使い方
  • Example#5302 - クラス名で結果をフィルタする
  • Example#5303 - クラス名、かつ継承も考慮して結果をフィルタする
  • Example#5304 - ReflectionClassConstant::isEnumCase の例
  • Example#5305 - ReflectionEnum::getBackingType の例
  • Example#5306 - ReflectionEnum::getCase の例
  • Example#5307 - ReflectionEnum::getCases の例
  • Example#5308 - ReflectionEnum::hasCase の例
  • Example#5309 - ReflectionEnum::isBacked の例
  • Example#5310 - ReflectionEnum::getValue の例
  • Example#5311 - ReflectionEnum::getBackingValue の例
  • Example#5312 - ReflectionExtension の例
  • Example#5313 - ReflectionExtension::getClasses の例
  • Example#5314 - ReflectionExtension::getClassNames の例
  • Example#5315 - ReflectionExtension::getConstants の例
  • Example#5316 - ReflectionExtension::getDependencies の例
  • Example#5317 - ReflectionExtension::getFunctions の例
  • Example#5318 - ReflectionExtension::getINIEntries の例
  • Example#5319 - ReflectionExtension::getName の例
  • Example#5320 - ReflectionExtension::getVersion の例
  • Example#5321 - ReflectionExtension::info の例
  • Example#5322 - ReflectionFunction::__construct の例
  • Example#5323 - ReflectionFunction::invoke の例
  • Example#5324 - ReflectionFunction::invokeArgs の例
  • Example#5325 - ReflectionFunction::invokeArgs で参照を使う例
  • Example#5326 - ReflectionFunction::isAnonymous の例
  • Example#5327 - ReflectionFunction::__toString の例
  • Example#5328 - メソッドを使った、基本的な使い方
  • Example#5329 - 関数を使った、基本的な使い方
  • Example#5330 - クラス名を使って結果をフィルタする
  • Example#5331 - クラス名、かつ継承も考慮して結果をフィルタする
  • Example#5332 - ReflectionFunctionAbstract::getClosureUsedVariables の例
  • Example#5333 - ReflectionFunctionAbstract::getReturnType の例
  • Example#5334 - ビルトイン関数で使う場合
  • Example#5335 - ReflectionFunctionAbstract::getTentativeReturnType の例
  • Example#5336 - ReflectionFunctionAbstract::hasReturnType の例
  • Example#5337 - ビルトイン関数で使う
  • Example#5338 - ReflectionFunctionAbstract::hasTentativeReturnType の例
  • Example#5339 - ReflectionFunctionAbstract::isClosure の例
  • Example#5340 - ReflectionFunctionAbstract::isDeprecated の例
  • Example#5341 - ReflectionMethod::__construct の例
  • Example#5342 - ReflectionMethod::createFromMethodName の例
  • Example#5343 - ReflectionMethod::getDeclaringClass の例
  • Example#5344 - ReflectionMethod::getModifiers の例
  • Example#5345 - ReflectionMethod::getPrototype の例
  • Example#5346 - ReflectionMethod::hasPrototype の例
  • Example#5347 - ReflectionMethod::invoke の例
  • Example#5348 - ReflectionMethod::invokeArgs の例
  • Example#5349 - 簡単なクラス定義
  • Example#5350 - ReflectionMethod::__toString の例
  • Example#5351 - ReflectionNamedType::isBuiltin の例
  • Example#5352 - ReflectionParameter クラスの使用
  • Example#5353 - 基本的な使い方
  • Example#5354 - クラス名で結果をフィルタする
  • Example#5355 - クラス名、かつ継承も考慮して結果をフィルタする
  • Example#5356 - ReflectionParameter クラスの利用法
  • Example#5357 - メソッドを宣言しているクラスの取得
  • Example#5358 - 関数のパラメータのデフォルト値を取得する
  • Example#5359 - 関数のパラメーターのデフォルト値の定数を取得する
  • Example#5360 - PHP 7.1.0 以降での ReflectionParameter::getType の使い方
  • Example#5361 - PHP 7.1.0 より前の ReflectionParameter::getType の使い方
  • Example#5362 - PHP 8.0.0 以降の ReflectionParameter::getType の使い方
  • Example#5363 - ReflectionParameter::hasType の例
  • Example#5364 - PHP 8.0.0 以降で同等のことを行うには
  • Example#5365 - PHP 8.0.0 以降で同等のことを行うには
  • Example#5366 - ReflectionParameter::__toString の例
  • Example#5367 - ReflectionProperty::__construct の例
  • Example#5368 - ReflectionProperty クラスを用いた、private および protected プロパティの値の取得
  • Example#5369 - 基本的な使い方
  • Example#5370 - クラス名で結果をフィルタする
  • Example#5371 - クラス名、かつ継承も考慮して結果をフィルタする
  • Example#5372 - ReflectionProperty::getDefaultValue の例
  • Example#5373 - ReflectionProperty::getDocComment の例
  • Example#5374 - 複数のプロパティを宣言している場合
  • Example#5375 - ReflectionProperty::getType の例
  • Example#5376 - ReflectionProperty::getValue の例
  • Example#5377 - ReflectionProperty::hasDefaultValue の例
  • Example#5378 - ReflectionProperty::hasType の例
  • Example#5379 - ReflectionProperty::isDefault の例
  • Example#5380 - ReflectionProperty::isInitialized の例
  • Example#5381 - ReflectionProperty::isPromoted の例
  • Example#5382 - 簡単なクラス定義
  • Example#5383 - ReflectionProperty::setValue の例
  • Example#5384 - ReflectionType::allowsNull の例
  • Example#5385 - ReflectionType::__toString の例
  • Example#5386 - ReflectionUnionType::getTypes の例
  • Example#5387 - ReflectionGenerator::__construct の例
  • Example#5388 - ReflectionGenerator::getExecutingFile の例
  • Example#5389 - ReflectionGenerator::getExecutingGenerator の例
  • Example#5390 - ReflectionGenerator::getExecutingLine の例
  • Example#5391 - ReflectionGenerator::getFunction の例
  • Example#5392 - ReflectionGenerator::getThis の例
  • Example#5393 - ReflectionGenerator::getTrace の例
  • Example#5394 - ReflectionIntersectionType::getTypes の例
  • Example#5395 - ReflectionReference::getId の基本的な使い方
  • Example#5396 - boolval の例
  • Example#5397 - debug_zval_dump の例
  • Example#5398 -
  • Example#5399 - 簡単な empty / isset の比較
  • Example#5400 - 文字列のオフセットに対する empty
  • Example#5401 - floatval の例
  • Example#5402 - floatval で、先頭が非数値である場合の例
  • Example#5403 - get_debug_type の例
  • Example#5404 - get_defined_vars の例
  • Example#5405 - get_resource_id が、リソースを数値にキャストした場合と同じ結果になる例
  • Example#5406 - get_resource_type の例
  • Example#5407 - gettype の例
  • Example#5408 - intval の例
  • Example#5409 - 変数が配列かどうか検査する
  • Example#5410 - is_bool の例
  • Example#5411 - is_callable の例
  • Example#5412 - is_callable とコンストラクタ
  • Example#5413 - is_countable の例
  • Example#5414 - is_float の例
  • Example#5415 - is_int の例
  • Example#5416 - is_iterable の例
  • Example#5417 - is_null の例
  • Example#5418 - is_numeric の例
  • Example#5419 - 空白文字と is_numeric 関数
  • Example#5420 - is_object の例
  • Example#5421 - is_resource の例
  • Example#5422 - is_scalar の例
  • Example#5423 - is_string の例
  • Example#5424 - isset の例
  • Example#5425 - 文字列のオフセットに対する isset
  • Example#5426 - print_r の例
  • Example#5427 - return 引数の例
  • Example#5428 - serialize の例
  • Example#5429 - settype の例
  • Example#5430 - マジックメソッド __toString() を使う strval の例
  • Example#5431 - unserialize の例
  • Example#5432 - unserialize_callback_func の例
  • Example#5433 - unset の例
  • Example#5434 - (unset) によるキャスト
  • Example#5435 - var_dump の例
  • Example#5436 - var_export の例
  • Example#5437 - PHP 7.3.0 以降で stdClass をエクスポートする
  • Example#5438 - クラスのエクスポート
  • Example#5439 - __set_state() の使用法
  • Example#5440 -
  • Example#5441 - OAuth::fetch の例
  • Example#5442 - OAuth::getAccessToken の例
  • Example#5443 - OAuth::getRequestToken の例
  • Example#5444 - OAuth::setRequestEngine example
  • Example#5445 - OAuth::setRsaCertificate の例
  • Example#5446 - OAuth::setToken の例
  • Example#5447 - OAuthProvider::__construct の例
  • Example#5448 - OAuthProvider::consumerHandler コールバックの例
  • Example#5449 - OAuthProvider::generateToken の例
  • Example#5450 - OAuthProvider::is2LeggedEndpoint の例
  • Example#5451 - OAuthProvider::timestampNonceHandler コールバックの例
  • Example#5452 - OAuthProvider::tokenHandler コールバックの例
  • Example#5453 - is_soap_fault の例
  • Example#5454 - SOAP の標準的なエラーレポートメソッドは例外となる
  • Example#5455 - TLS 1.3 だけを指定する
  • Example#5456 - SoapClient::__construct の例
  • Example#5457 - SOAP_SINGLE_ELEMENT_ARRAYS の機能を使う
  • Example#5458 - SoapClient::__doRequest の例
  • Example#5459 - SoapClient::__getFunctions の例
  • Example#5460 - SoapClient::__getLastRequest() の例
  • Example#5461 - SoapClient::__getLastRequestHeaders() の例
  • Example#5462 - SoapClient::__getLastResponse() の例
  • Example#5463 - SoapClient::__getLastResponse() の例
  • Example#5464 - SoapClient::__getTypes の例
  • Example#5465 - SoapClient::__setLocation の例
  • Example#5466 - SoapClient::__setSoapHeaders の例
  • Example#5467 - 複数のヘッダの設定
  • Example#5468 - SoapClient::__soapCall の例
  • Example#5469 - SoapServer::addFunction の例
  • Example#5470 - SoapServer::__construct の例
  • Example#5471 - SoapServer::getFunctions の例
  • Example#5472 - SoapServer::handle の例
  • Example#5473 - SoapServer::setPersistence の例
  • Example#5474 - いくつかの例
  • Example#5475 - いくつかの例
  • Example#5476 - SoapHeader::__construct の例
  • Example#5477 - SoapParam::__construct の例
  • Example#5478 - SoapVar::__construct の例
  • Example#5479 - Yar Server Example
  • Example#5480 - Access the server in borwser(GET request)
  • Example#5481 - Yar Client Example
  • Example#5482 - Yar Concurrent Client Example
  • Example#5483 - Yar_Server::__construct example
  • Example#5484 - Yar_Server::handle example
  • Example#5485 - Yar_Client::__call example
  • Example#5486 - Yar_Client::__construct example
  • Example#5487 - Yar_Client::setOpt example
  • Example#5488 - Yar_Concurrent_Client::call example
  • Example#5489 - Yar_Concurrent_Client::loop example
  • Example#5490 - Yar_Concurrent_Client::reset example
  • Example#5491 - Yar_Server_Exception::getType example
  • Example#5492 - Yar_Client_Exception::getType example
  • Example#5493 - XMLRPC クライアント関数の例
  • Example#5494 - XML-RPC の型の例
  • Example#5495 - xmlrpc_set_type の例
  • Example#5496 - ASP における For Each
  • Example#5497 - PHP 5 における foreach
  • Example#5498 - com の例 (1)
  • Example#5499 - com の例 (2)
  • Example#5500 - dotnet の例
  • Example#5501 - variant の例
  • Example#5502 - COMPersistHelper::saveToFile の基本的な使い方
  • Example#5503 - COM イベントシンクの例
  • Example#5504 - PHP スクリプトをサービスとして登録する
  • Example#5505 - サービスの登録を解除する
  • Example#5506 - サービスとして実行する
  • Example#5507 - win32_create_service の例
  • Example#5508 - 依存性を用いた win32_create_service の例
  • Example#5509 - リカバリ設定を用いた win32_create_service の例
  • Example#5510 - win32_delete_service の例
  • Example#5511 - win32_start_service_ctrl_dispatcher の例
  • Example#5512 - book.xml
  • Example#5513 - 新しい DOMAttr オブジェクトを作成する
  • Example#5514 - DOMAttr::isId() の例
  • Example#5515 - 新しい DOMCdataSection オブジェクトの作成
  • Example#5516 - DOMCharacterData::after の例
  • Example#5517 - DOMCharacterData::before の例
  • Example#5518 - DOMCharacterData::remove の例
  • Example#5519 - DOMCharacterData::replaceWith の例
  • Example#5520 - 新しい DOMComment を作成する
  • Example#5521 - DOMDocument::adoptNode の例
  • Example#5522 - DOMDocument::append の例
  • Example#5523 - 新しい DOMDocument を作成する
  • Example#5524 - 新しい要素を作成し、ルートとして挿入する
  • Example#5525 - & をエスケープせずに value に渡す例
  • Example#5526 - 新しい要素を作成し、ルートとして挿入する
  • Example#5527 - 名前空間プレフィックスの例
  • Example#5528 - DOMDocument::getElementById() の例
  • Example#5529 - 基本的な使用例
  • Example#5530 - すべての XInclude 要素を取得する
  • Example#5531 - DOMDocument::importNode の例
  • Example#5532 - ドキュメントの作成
  • Example#5533 - ドキュメントを作成する
  • Example#5534 - ドキュメントを作成する
  • Example#5535 - ドキュメントを作成する
  • Example#5536 - DOMDocument::prepend の例
  • Example#5537 - 新しいメソッドを DOMElement に追加し、コードを書きやすくする
  • Example#5538 - カスタムクラス形式での要素の取得
  • Example#5539 - オーナードキュメントの取得
  • Example#5540 - カスタムオブジェクトは一時的なもの
  • Example#5541 - DOMDocument::replaceChildren の例
  • Example#5542 - DOM ツリーをファイルに保存する
  • Example#5543 - HTML ツリーを文字列に保存する
  • Example#5544 - HTML ツリーをファイルに保存する
  • Example#5545 - DOM ツリーを文字列に保存する
  • Example#5546 - DTD による検証の例
  • Example#5547 - DOMDocument::xinclude() の例
  • Example#5548 - DOMDocumentFragment::append の例
  • Example#5549 - XML データのドキュメントへの追加
  • Example#5550 - DOMDocumentFragment::prepend の例
  • Example#5551 - DOMDocumentFragment::replaceChildren の例
  • Example#5552 - DOMElement::after の例
  • Example#5553 - DOMElement::append の例
  • Example#5554 - DOMElement::before の例
  • Example#5555 - 新しい DOMElement を作成する
  • Example#5556 - DOMElement::getAttributeNames の例
  • Example#5557 - DOMElement::insertAdjacentElement の例
  • Example#5558 - DOMElement::insertAdjacentText の例
  • Example#5559 - DOMElement::prepend の例
  • Example#5560 - DOMElement::remove の例
  • Example#5561 - DOMElement::replaceChildren の例
  • Example#5562 - DOMElement::replaceWith の例
  • Example#5563 - 属性を設定する
  • Example#5564 - DOMElement::toggleAttribute の例
  • Example#5565 - 新しい DOMEntityReference を作成する
  • Example#5566 - DTD を添付してドキュメントを作成する
  • Example#5567 - DOM の実装を調べる
  • Example#5568 - 子要素の追加
  • Example#5569 - ネストされた子ノード
  • Example#5570 - XPath クエリの例
  • Example#5571 - DOMNode::contains の例
  • Example#5572 - DOMNode::getLineNo メソッドの例
  • Example#5573 - DOMNode::getNodePath の例
  • Example#5574 - DOMNode::getRootNode の例
  • Example#5575 - DOMNode::isEqualNode の例
  • Example#5576 - 子要素の削除
  • Example#5577 - テーブル内のすべての要素を取得する
  • Example#5578 - DOMParentNode::replaceChildren の例
  • Example#5579 - 新しい DOMProcessingInstruction を作成する
  • Example#5580 - 新しい DOMText を作成する
  • Example#5581 - 英語の書籍の数を取得する
  • Example#5582 - すべての英語の書籍を取得する
  • Example#5583 - book.xml
  • Example#5584 - DOMXPath::registerPHPFunctions と php:functionString の例
  • Example#5585 - DOMXPath::registerPHPFunctions と php:function の例
  • Example#5586 - dom_import_simplexml を用いて SimpleXML を DOM にインポートする
  • Example#5587 - libxml_get_errors の例
  • Example#5588 - libxml_set_external_entity_loader の例
  • Example#5589 - libxml_set_streams_context の例
  • Example#5590 - libxml_use_internal_errorsの例
  • Example#5591 - XML 文字列を設定するインクルードファイル example.php
  • Example#5592 - <plot> を取得する
  • Example#5593 - <line> を取得する
  • Example#5594 - SimpleXML でユニークでない要素にアクセスする
  • Example#5595 - 属性を使用する
  • Example#5596 - 要素および属性をテキストと比較する
  • Example#5597 - ふたつの要素の比較
  • Example#5598 - XPath の使用
  • Example#5599 - 値を設定する
  • Example#5600 - 要素と属性を追加する
  • Example#5601 - DOM との相互運用性
  • Example#5602 - 壊れた XML 文字列の読み込み
  • Example#5603 - SimpleXML 要素への属性と子要素の追加
  • Example#5604 - SimpleXML 要素への属性と子要素の追加
  • Example#5605 - XML を取得する
  • Example#5606 - SimpleXMLElement::xpath の結果に asXML() を使用する
  • Example#5607 - XML文字列を解釈する
  • Example#5608 - children() 疑似配列を走査する
  • Example#5609 - 名前空間の使用
  • Example#5610 - SimpleXMLElement オブジェクトの作成
  • Example#5611 - URL からの SimpleXMLElement オブジェクトの作成
  • Example#5612 - 子要素の数の取得
  • Example#5613 - 現在の要素を返す
  • Example#5614 - ドキュメントの名前空間の取得
  • Example#5615 - 複数の名前空間での動作
  • Example#5616 - XML 要素の名前の取得
  • Example#5617 - ドキュメントで使用している名前空間の取得
  • Example#5618 - 現在の要素の子要素を返す
  • Example#5619 - 現在の要素が子要素を持つかどうかを調べる
  • Example#5620 - 現在の XML タグキーの取得
  • Example#5621 - 次の要素への移動
  • Example#5622 - XPath クエリで使用する名前空間プレフィックスの設定
  • Example#5623 - 最初の要素に巻き戻す
  • Example#5624 - 文字列で内容を取得する
  • Example#5625 - 現在の要素が有効かどうかを調べる
  • Example#5626 - Xpath
  • Example#5627 - DOM のインポート
  • Example#5628 - XMLドキュメントをパースする
  • Example#5629 - XML 文字列をパースする
  • Example#5630 - WDDX を使用した単一の値のシリアル化
  • Example#5631 - WDDX を使用してパケットを追加する例
  • Example#5632 - wddx_serialize_vars の例
  • Example#5633 - XML エレメント構造を表示
  • Example#5634 - XMLをHTMLにマップする
  • Example#5635 - 外部エンティティの例
  • Example#5636 - xmltest.xml
  • Example#5637 - xmltest2.xml
  • Example#5638 - 巨大なXML文書を切り分けてパースする
  • Example#5639 - xml_parse_into_struct の例
  • Example#5640 - moldb.xml - 分子情報の小さなデータベース
  • Example#5641 - parsemoldb.php - moldb.xml を処理し、分子オブジェクトの配列に代入
  • Example#5642 - xml_set_object の例
  • Example#5643 - XML の妥当性の検証
  • Example#5644 - 単純な XML ドキュメントの作成
  • Example#5645 - XML 名前空間の使用
  • Example#5646 - オブジェクト指向 API の使用
  • Example#5647 - XML を直接出力する
  • Example#5648 - XMLWriter::setIndent と mixed content
  • Example#5649 - XMLWriter::startAttribute の基本的な使い方
  • Example#5650 - 子要素と属性を混在させる
  • Example#5651 - xmlwriter_write_cdata の基本的な使い方
  • Example#5652 - collection.xml
  • Example#5653 - collection.xsl
  • Example#5654 - fruits.xml
  • Example#5655 - fruits.xsl
  • Example#5656 - エラーの捕捉と表示
  • Example#5657 - XSLTProcessor の作成
  • Example#5658 - EXSLT サポートの判定
  • Example#5659 - スタイルシートからの単純な PHP 関数コール
  • Example#5660 - 変換前に所有者を変更する
  • Example#5661 - プロファイル出力の例
  • Example#5662 - DOMDocument への変換
  • Example#5663 - HTML ファイルへの変換
  • Example#5664 - 文字列への変換
  • Example#5665 - HTML の hidden 要素
  • Example#5666 - ユーザーによって編集するデータ
  • Example#5667 - URL 中の場合
  • Example#5668 - PHP による JavaScript の生成
  • Example#5669 - PHP/FI のコード例
  • Example#5670 - dev. ドメインではエラーを画面に表示させるようにする例
  • Example#5671 - 保護エリア内でのスクリプトのセキュリティ確保
  • Example#5672 - Unix include_path
  • Example#5673 - Windows include_path
  • Example#5674 - Unix include_path で環境変数 ${USER} を使う例
  • Example#5675 - string.rot13
  • Example#5676 - string.toupper
  • Example#5677 - string.tolower
  • Example#5678 - string.strip_tags
  • Example#5679 - convert.base64-encode と convert.base64-decode
  • Example#5680 - convert.quoted-printable-encode と convert.quoted-printable-decode
  • Example#5681 - convert.iconv.*
  • Example#5682 - zlib.deflate と zlib.inflate
  • Example#5683 - zlib.deflate のシンプルな例
  • Example#5684 - bzip2.compress と bzip2.decompress
  • Example#5685 - Blowfish を用いた 暗号化/復号化
  • Example#5686 - ファイルを AES-128 CBC と SHA256 HMAC で暗号化する


  • ≪ サンプル
  • HTML ヘルプ版 ≫
  • PHP Manual
  • 付録
  • 変更履歴

変更履歴

標準添付の拡張モジュールには次のような変更がありました。

Version Function 説明


HTML ヘルプ版

  • このヘルプについて
  • CHM版 の PHPマニュアル を使う
    • HTMLヘルプのツールバー
    • ナビゲーションペイン
    • キーボードショートカット
  • 全文検索
    • 一般的な検索のルール
    • 単語またはフレーズを検索する
    • 検索後を定義する
    • 入れ子の検索条件を使う
  • Integrating the PHP Manual


このヘルプについて

PHPマニュアル の Windowsヘルプ版 は、このマニュアルをいつも手元に置いておきたかったり、Webページをダウンロードするのを待つことなくマニュアルページやユーザーが書き込んだ Note を読みたい開発者を対象にしています。Windowsヘルプ版 は、PHPマニュアルの全ての内容と、ユーザーが書き込んだ Note が全て含まれていますし、このフォーマットを生成するスクリプトや他のコントリビューターがスキンの形で提供したビューアアプリケーションの素晴らしい機能がいくつか付いてきます。

PHPマニュアル の配布物に多くのファイルが含まれており、それらはメインマニュアルファイルである php_manual_ja.chm に入っています。(既にお察しの通り) あなたは PHPマニュアル をこのファイルをダブルクリックすることで見ることが出来ます。 同じフォルダで php_manual_ja.chw というファイルを見ることがあるかもしれません。これは「キーワード」タブをはじめて使うときに生成され、マニュアルページのインデックスが含まれています。

Microsoft HTMLヘルプ の技術的な詳細に興味がある方向けの素晴らしいリソースに、» http://www.helpware.net/ があります。Microsoft ヘルプフォーマットやサービスの歴史における Windows HTMLヘルプの位置付けや、さらに詳しい情報は » WinWriters の記事 を参照ください。


CHM版 の PHPマニュアル を使う

目次

  • HTMLヘルプのツールバー
  • ナビゲーションペイン
  • キーボードショートカット

CHMファイル をダブルクリックすると、HTMLヘルプビューア のウィンドウが起動します。これは3つのペインに分かれています。ウィンドウの左側はナビゲーションペインで、4つのタブがあります。目次、キーワード、検索、そしてお気に入りです。ウィンドウの右側はトピックペインで、選択したヘルプトピックを表示させたり、起動時のデフォルトのヘルプトピックが表示されたりします。ヘルプページは全て別々のHTMLファイルで、Internet Explorer がページをトピックペインに表示します。3つめのペインはツールバーです。これはウィンドウのタイトルバーの下にあります。ナビゲーションペインとトピックペインの境目は、縦方向のバーをドラッグすることでレイアウトを調整できます。

CHMファイルをはじめて開くとき、ウィンドウの位置とサイズがおかしな状態かもしれません。2回目以降は、Windows が位置とサイズ、そして最後に開いたタブを記憶しています。これら全ての情報とお気に入りに入れた情報は hh.dat に保存されます。このファイルを別の場所に移動すると、これらの情報が(お気に入りの情報も含めて!)失われてしまいます。CHMファイルを新しいものに置き換えるのは、同じファイル名であれば問題ありません。ファイル名とパス名は hh.dat に保存されています。


HTMLヘルプのツールバー

PHPマニュアルを表示したとき、HTMLヘルプのツールバーには次のアイコンが表示されます:

  • 表示/非表示 - ナビゲーションペインを表示/非表示 にします。
  • 同期 - 目次タブの内容をトピックのペインの内容に合わせます。 (検索、キーワード、お気に入りからトピックにたどり着いた場合 や目次にあるツリーの内容を見たくなったりした場合に使います)
  • 戻る - 履歴のひとつ前に戻ります。
  • 進む - ひとつ後の履歴に進みます。
  • 更新 - 現在のページを更新します。
  • ホーム - CHMのスタートアップページを開きます。
  • 印刷 - 印刷ダイアログボックスを開きます。
  • オプション - ドロップダウンで追加のオプションを提供します。
このツールバーは本当に簡単に使えます。多くのツールバーアイコンは Internet Explorer にある同様の機能と強い関連があります。


ナビゲーションペイン

ナビゲーションペインには4つのタブがあります: 目次、キーワード、検索、そしてお気に入りです。これらのタブはヘルプファイルのトピックにアクセスする異なる方法を提供します。

  • 目次タブは目次をツリー状に表示します。ここでは、ツリーの一部分を開いたり閉じたりして望みのトピックに移動することができます。目次を使うとセクションの一番深い部分にさえアクセスできます。見出しの項目を右クリックして「印刷」を選ぶと、選択中のトピックか、選択中のトピックとそのサブトピック全てを印刷するオプションが表示されます。しかし、マニュアルを印刷する機能はこのマニュアルの代表的な機能ではありません。(PDFバージョンの方が印刷に適しています)
  • キーワードタブは、莫大な数(マニュアルのタイトル全て)の「キーワード」を一覧にします。 あなたは表示されているものからひとつ選んだり、キーワードを打ち込んで表示される一覧を調整してトピックをクリックしたり、選択したトピックが見たいものであれば、エンターキーを押してトピックを表示させることも出来ます。
  • 検索タブはHTMLヘルプビューアのもっとも強力な機能、全文検索(FTS=Full Text Search)を提供します。 ここでは、検索条件を入力し、オプションでそれらの条件を AND/OR/NEAR/NOT で繋ぐこともできます。 「検索開始」ボタンをクリックする前に、画面左下にあるオプションをいくつか設定することもできます。 検索結果が表示された後、マニュアルの検索結果と User Note の検索結果は別であることに気付くでしょう。 これらふたつのタイプをソートするには、「場所」カラムヘッダをクリックします。これで、検索結果から トピックを選び出し、閲覧することが出来ます。検索したキーワードはページ上でハイライトされています。
  • お気に入りタブを使うと、もっともよく使うトピックを一覧にし、簡単にアクセスすることが出来ます。 お気に入りのリストを見ることも出来ますし、現在表示しているトピックを追加することも出来ます。 また、お気に入りのうちのひとつを削除することもできますし、お気に入りのうちのひとつをトピックペインに表示させることもできます。 「現在のトピック」ボックスにテキストを入力することで、お気に入りに独自のタイトルを付けることも出来ます。 User Noteのお気に入りページのタイトルには、通常のマニュアルページと後で簡単に区別できるように N: という文字列がはじめにつきます。


キーボードショートカット

生産性を高めるために、たくさんのキーボードショートカットがあります。 クリックするかわりに、これらのキーボードショートカットを使う方が トピックにアクセスするのに適切だと多くの人が気付いています。

ヘルプビューアの一般的なショートカット
実行する操作 | ショートカット
ヘルプビューアを閉じる | ALT+F4
オプションメニューを表示 | ALT+O
ナビゲーションペインを表示/非表示にする | ALT+O を押し、Tを押す
トピックを印刷 | ALT+O を押し、Pを押す
一つ前のトピックに戻る | ALT+LEFT ARROW
ひとつ後のトピックに移動する (以前にトピックを見ていた場合) | ALT+RIGHT ARROW
検索のハイライトを 有効/無効 にする | ALT+O を押し、O を押す
ヘルプファイルのホームに戻る | ALT+O を押し、Hを押す
ナビゲーションペインとトピックペインを切り替える | F6
ナビゲーションペインのタブにあるオプション、またはトピックペインにある全てのリンクを移動しながらスクロールする | TAB
コンテキストメニュー(右クリック) を表示する | SHIFT+F10
目次タブのショートカット
実行する操作 | ショートカット
目次タブを表示する | ALT+C
ブックまたはフォルダを開いたり閉じたりする | PLUS SIGN と MINUS SIGN または、LEFT ARROW と RIGHT ARROW
トピックを選択する | DOWN ARROW と UP ARROW
選択したトピックを表示する | ENTER
キーワードタブのショートカット
実行する操作 | ショートカット
キーワードタブを表示する | ALT+N
検索するキーワードを入力する | ALT+W を押し、検索語を入力
リスト中のキーワードを選択する | UP ARROW と DOWN ARROW
関連するトピックを表示する | ENTER または ALT+D
検索タブのショートカット
実行する操作 | ショートカット
検索タブを表示する | ALT+S
検索するキーワードを入力する | ALT+W を押し、検索語を入力
検索を開始 | ALT+L
検索結果リストにあるトピックを選択する | ALT+T を押し、UP ARROW と DOWN ARROWを押す
選択したトピックを表示する | ENTER または ALT+D
以前行った検索結果からキーワード検索する | ALT+U
キーワードに似た単語で検索する。たとえば、"run" というキーワードに対して、"running" や "runs" のような単語で検索する | ALT+M
タイトルのみ検索 | ALT+R
お気に入りタブのショートカット
実行する操作 | ショートカット
お気に入りタブを表示する | ALT+I
現在見ているトピックをお気に入りリストに追加する | ALT+A
お気に入りリストにあるトピックを選択する | ALT+P を押し、UP ARROW と DOWN ARROW を押す
選択したトピックを表示する | ENTER または ALT+D
お気に入りリストから、選択したトピックを削除する | ALT+R
トピックペインのショートカット
実行する操作 | ショートカット
インデックスを探す | 探したい単語を選択し、F1を押す
ページ内検索 | CTRL+F を押し、オプションを調整する
ページを更新する | F5


全文検索

目次

  • 一般的な検索のルール
  • 単語またはフレーズを検索する
  • 検索後を定義する
  • 入れ子の検索条件を使う

This edition of the PHP Manual includes an advanced full text search possibility provided by the viewer application. This enables users to search through every word in the help file to find a match. For example, if a user does a full-text search on the word "Apache", every topic that contains the word "Apache" will be listed. Advanced full-text search allows a user to search using boolean, wildcard, and nested expressions. A user can also limit the search to previous results, match similar words, or search topic titles only.

The usage of the search feature is fairly straightforward. Click on the search tab, type in the desired words and press ENTER (or click on "List Topics"). Then you'll receive a list of matches from the PHP Manual (and the notes). You can use the button with a right arrow on it to add boolean operators to your search (or you can type them in). As you see the results, you can use the column headings (Title, Location and Rank) to sort the topic list. The default order is by Rank. You can also adjust some parameters at the bottom of this tab.

The words found are highlighted on the current page in the Topic pane by default. You can turn off this feature by choosing the "Search Highlight Off" menu item in the Options menu. To can get this feature back similarly. If you are viewing a long topic, only the first 500 instances of a search word or phrase will be highlighted, due to a limitation of the viewer.


一般的な検索のルール

A basic search consists of the word or phrase you want to find. You can use wildcard expressions, nested expressions, boolean operators, similar word matches, a previous results list, or topic titles to further define your search.

The basic rules for formulating queries are as follows:

  • Searches are not case-sensitive, so you can type your search in uppercase or lowercase characters.
  • You may search for any combination of letters (a-z) and numbers (0-9). You cannot search for single letters (a, b, c, etc.) and common words, like: an, and, as, at, be, but, by, do, for, from, have, he, in, it, not, of, on, or, she, that, the, there, they, this, to, we, which, with, you.
  • Punctuation marks such as the period (.), colon (:), semicolon (;), comma (,), and hyphen (-) are ignored during a search.
  • Group the elements of your search using double quotes or parentheses to set apart each element. You cannot search for quotation marks.

注意:

If you are searching for a file name with an extension, you should group the entire string in double quotes, ("filename.ext"). Otherwise, the period will break the file name into two separate terms. The default operation between terms is AND, so you will create the logical equivalent to "filename AND ext."


単語またはフレーズを検索する

You can search for words or phrases and use wildcard expressions. Wildcard expressions allow you to search for one or more characters using a question mark or asterisk. The table below describes the results of these different kinds of searches.

Word and phrase searches
Search for | Example | Results
A single word | select | Topics that contain the word "select". (You will also find its grammatical variations, such as "selector" and "selection".)
A phrase | "new operator" or new operator | Topics that contain the literal phrase "new operator" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying "new AND operator," which will find topics containing both of the individual words, instead of the phrase.
Wildcard expressions | esc* or HT?? | Results for the first example include topics that contain the terms "ESC", "escape", "escalation", and so on. The asterisk cannot be the only character in the term. Results for the second example include topics that contain the terms "HTTP", "HTML" and so on. The question mark cannot be the only character in the term.

注意:

Select the Match similar words check box to include minor grammatical variations for the phrase you search. This feature only locates variations of the word with common suffixes. For example, a search on the word "add" will find "added," but it will not find "additive". This option is independent of other options or syntax. If you do a titles-only search, variations in titles will be matched. If you use quotes (or any other query operator) any variation of the word can appear; for example, "stemmed search" will also match "stemming search".


検索後を定義する

The AND, OR, NOT, and NEAR operators enable you to precisely define your search by creating a relationship between search terms. The following table shows how you can use each of these operators. If no operator is specified, AND is used. For example, the query "server cgi security" is equivalent to "server AND cgi AND security".

Search operators
Search for | Example | Results
Both terms in the same topic | http AND apache | Topics containing both the words "http" and "apache".
Either term in a topic | ming OR swflib | Topics containing either the word "ming" or the word "swflib" or both.
The first term without the second term | xml NOT expat | Topics containing the word "xml" but not the word "expat".
Both terms in the same topic, close together | database NEAR security | Topics containing the word "database" within eight words of the word "security".

注意:

The |, &, and ! characters can also be used in place of OR AND and NOT respectively. This may not work if you use a very old version of the viewer.


入れ子の検索条件を使う

Nested expressions allow you to create complex searches for information. For example, "html AND ((smtp OR pop3) NEAR mail)" finds topics containing the word "html" along with the words "smtp" and "mail" close together, or containing "html" along with the words "pop3" and "mail" close together.

The basic rules for searching help topics using nested expressions are as follows:

  • You can use parentheses to nest expressions within a query. The expressions in parentheses are evaluated before the rest of the query.
  • If a query does not contain a nested expression, it is evaluated from left to right. For example: "mail NOT pop3 OR smtp" finds topics containing the word "mail" without the word "pop3" or topics containing the word "smtp". On the other hand, "mail NOT (pop3 OR smtp)" finds topics containing the word "mail" without either of the words "pop3" or "smtp".
  • You cannot nest expressions more than five levels deep.


Integrating the PHP Manual

注意:

The information provided here is mainly aimed at IDE authors, or advanced users who would like to integrate this CHM file to their favorite IDEs or other production environment components.

There are several editors out there with support for CHM integration, but you may need to know a few things about what the CHM contains to successfully integrate the manual into your environment.

The CHM is built using XSL style sheets from XML sources. This is unique currently in the PHP Manual family, as all other versions are generated using DSSSL style sheets. This also means, that non-intentional rendering differences may come up. A special conversion script is run on the XSLT output, adding several cute features, and packing up the manual with the preferences files and skin examples.

If you never worked with CHMs, you can think of them as compressed files with OS supported access for files inside and some added search and index support. However CHMs can only be viewed using the HTML Help Viewer, you can directly access files inside them using a special URL prefix, the CHM file name and the file you request from inside. As all the help content is stored in HTML files, you can show pages of the CHM in Internet Explorer.

Assume that you placed your php_manual_en.chm to c:\phpmanual the index file in the manual (which you see the first time) can be accessed with the following URL: mk:@MSITStore:C:\phpmanual\php_manual_en.chm::/_index.html. Here mk:@MSITStore: is the special "protocol", C:\phpmanual\php_manual_en.chm is the CHM with it's full path. The /_index.html part is the path to the index file inside the CHM and :: is just what you need to put between the CHM path and this file path.

注意:

All files are in the root directory of the CHM, unlike the previous CHM versions which included a language directory. Images, style sheets and other supplemental files have names starting with an underscore (like the main index shown above), to avoid name collisions.

The names of generated files follow the same rules as the online manual, except that the extension is .html and not .php. The most important is that function documentation files are named function.FUNCNAME.html where FUNCNAME is the function name, with all underscores converted to hyphens. Some examples are function.echo.html, function.mysql-close.html, function.imagecopy.html.

Using all this information, you can show a manual page for a function requested by a user. A simple example is included in the distribution, named php_quickref.hta. This is a » HTML Application to demonstrate the simple process of showing a manual page for a function. The quickRef() function defined therein does the job.

If you would like to integrate the manual into an IDE without direct support for the PHP manual (actually the underscore to hyphen conversion), you can use the included _function.html file to access a function page. This file is simply a redirector, and can be parameterized via the URL, as _function.html#mysql_close. This page will redirect you to the mysql_close function page (function.mysql-close.html) automatically. You can provide the full path of this file if your IDE supports context sensitive help, and provide the IDE specified string as the parameter. An example for this is the UltraEdit 9 intergation (see the edition's website).

The index of the manual (accessible via the index tab on the navigation pane) can also be used for integrational purposes. All the HTML pages are included in the index with their titles as index terms (including function description pages).

If you are a desktop application developer and would like to tightly integrate the CHM into your program (such as displaying the TOC tree in your IDE's help box), you can find more information at » http://www.helpware.net/, as well as links to other useful resources. The official site for HTML Help is at » http://www.microsoft.com/download/en/details.aspx?id=21138.